dbopen(3) Library Functions Manual dbopen(3) NOME dbopen - metodos de acesso a banco de dados BIBLIOTECA Biblioteca C Padrao (libc, -lc) SINOPSE #include #include #include #include DB *dbopen(const char *file, int flags, int mode, DBTYPE type, const void *openinfo); DESCRICAO Note well: This page documents interfaces provided up until glibc 2.1. Since glibc 2.2, glibc no longer provides these interfaces. Probably, you are looking for the APIs provided by the libdb library instead. dbopen() e a interface de biblioteca para arquivos de banco de dados. Os formatos de arquivos suportados sao btree, esmiucados e orientados a arquivos UNIX. O formato 'btree' e uma representacao de uma estrutura de arvore balanceada e ordenada. O formato 'hash' e um esquema de esmiucamento dinamico e extensivel. O formato 'texto plano' e um arquivo de sequencia de bytes com registros de comprimento fixo ou variavel. Os formatos e as informacoes especificas de formato sao descritas em detalhes em suas respectivas paginas de manual btree(3), hash(3) e recno(3). dbopen() opens file for reading and/or writing. Files never intended to be preserved on disk may be created by setting the file argument to NULL. The flags and mode arguments are as specified to the open(2) routine, however, only the O_CREAT, O_EXCL, O_EXLOCK, O_NONBLOCK, O_RDONLY, O_RDWR, O_SHLOCK, and O_TRUNC flags are meaningful. (Note, opening a database file O_WRONLY is not possible.) The type argument is of type DBTYPE (as defined in the include file) and may be set to DB_BTREE, DB_HASH, or DB_RECNO. O argumento openinfo e um ponteiro para uma estrutura de metodo de acesso especifica, descrita na pagina de manual do metodo de acesso. Se openinfo e NULO, cada metodo de acesso usara padroes adequados para o sistema e o metodo de acesso. dbopen() retorna um ponteiro para uma estrutura DB se for bem-sucedido, e NULO em caso de erro. A estrutura DB e definida no arquivo 'include' , e contem pelo menos os seguintes campos: typedef struct { DBTYPE type; int (*close)(const DB *db); int (*del)(const DB *db, const DBT *key, unsigned int flags); int (*fd)(const DB *db); int (*get)(const DB *db, DBT *key, DBT *data, unsigned int flags); int (*put)(const DB *db, DBT *key, const DBT *data, unsigned int flags); int (*sync)(const DB *db, unsigned int flags); int (*seq)(const DB *db, DBT *key, DBT *data, unsigned int flags); } DB; Estes elementos descrevem um tipo de banco de dados e um conjunto de funcoes realizando varias acoes. Estas funcoes usam um ponteiro para uma estrutura como retornado por dbopen(), e as vezes um ou mais ponteiros para estruturas chave/dados e um valor de sinalizacao. type O tipo de metodo-base de acesso (e formato de arquivo). close Um ponteiro para uma rotina que esvazia qualquer informacao no cache de disco, libera quaisquer recursos alocados, e fecha o(s) arquivo(s) de base. Como os pares chave/dados podem ficar no cache de memoria, uma falha em sincronizar o arquivo com uma funcao close ou sync pode resultar em inconsistencia ou perda de informacao. Rotinas close retornam -1 em caso de erro (configurando errno), e 0 em caso de sucesso. del Um ponteiro para uma rotina que remove pares chave/dados do banco de dados. The argument flag may be set to the following value: R_CURSOR Apaga o registro referenciado pelo cursor. O cursor precisa ser inicializado previamente. Rotinas delete retornam -1 em caso de erro (configurando errno), 0 em caso de sucesso, e 1 se a chave especificada nao estiver no arquivo. fd Um ponteiro para uma rotina que retorna um descritor de arquivo representativo do banco de dados de base. Um descritor de arquivo que referencia o mesmo arquivo sera retornado para todos os processos que chamam dbopen() com o mesmo nome de arquivo. Este descritor de arquivo pode ser usado com seguranca como um argumento para as funcoes de travamento fcntl(2) e flock(2). O descritor de arquivo nao e associado necessariamente com qualquer um dos arquivos de base usados pelo metodo de acesso. Nenhum descritor de arquivo esta disponivel em banco de dados de memoria. Rotinas fd retornam -1 em caso de erro (configurando errno), e o descritor de arquivo em caso de sucesso. get Um ponteiro para uma rotina que e a interface para buscas chaveadas no banco de dados. O endereco e o comprimento dos dados associados com a chave especifica na estrutura referenciada pelos dados. Rotinas get retornam -1 em caso de erro (configurando errno), 0 em caso de sucesso, e 1 se a chave nao estava no arquivo. put Um ponteiro para uma rotina que armazena pares chave/dados no banco de dados. The argument flag may be set to one of the following values: R_CURSOR Substitui os pares chave/dados referenciados pelo cursor. O cursor deve ser inicializado previamente. R_IAFTER Acrescenta o dado imediatamente apos o dado referenciado pela chave, criando um novo par chave/dado. O numero de registro do par chave/dado acrescentado e retornado na estrutura chave. (Aplicavel somente para o metodo de acesso DB_RECNO.) R_IBEFORE Insere o dado imediatamente antes do dado referenciado pela chave, criando um novo par chave/dado. O numero de registro do par chave/dado e retornado na estrutura chave. (Aplicavel somente para o metodo de acesso DB_RECNO.) R_NOOVERWRITE Entra o novo par chave/dado somente se a chave nao existe anteriormente. R_SETCURSOR Armazena o par chave/dado, configurando ou inicializando a posicao do cursor para referencia-lo. (Aplicavel somente para os metodo de acesso DB_BTREE e DB_RECNO.) R_SETCURSOR esta disponivel somente para os metodos de acesso DB_BTREE e DB_RECNO, porque ele implica que as chaves tem uma ordem inerente que nao se altera. R_IAFTER e R_IBEFORE estao disponiveis somente para o metodo de acesso DB_RECNO porque elas implicam que o metodo de acesso e capaz de criar novas chaves. Isto e verdade apenas se as chaves sao ordenadas e independentes, numeros de registro por exemplo. O comportamento padrao das rotinas put e entrar o novo par chave/dado, substituindo qualquer chave existente anteriormente. Rotinas put retornam -1 em caso de erro (configurando errno), 0 em caso de sucesso, e 1 se a flag R_NOOVERWRITE foi setada e a chave ja existe no arquivo. seq Um ponteiro para uma rotina que e a interface para uma busca sequencial no banco de dados. O endereco e o comprimento da chave sao retornados na estrutura referenciada pela chave, e o endereco e o comprimento dos dados sao retornados na estrutura referenciada pelo dado. Pares chave/dado sequenciais recuperados podem comecar a qualquer tempo, e a posicao do 'cursor' nao e afetada pela chamada das rotinas del, get, put, ou sync. As modificacoes no banco de dados durante uma busca se refletirao na busca, isto e, os registros inseridos atras do cursor nao serao retornados, enquanto que os registros inseridos na frente do cursor serao. O valor da flag precisa ser setado para um dos seguintes valores: R_CURSOR Sao retornados os dados asscociados com a chave especificada. Isto difere das rotinas get pelo fato de ela setar ou inicializar o cursor para o local da chave tambem. (Note, para o metodo de acesso DB_BTREE, a chave retornada nao e necessariamente uma combinacao exata para a chave especificada. A chave retornada e a menor chave que seja maior ou igual a chave especificada, permitindo buscas com combinacoes de chave e buscas de chave parciais.) R_FIRST E retornado o primeiro par chave/dado do banco de dados, e o cursor e setado ou inicializado para referencia-lo. R_LAST E retornado o ultimo par chave/dado do banco de dados, e o cursor e setado ou inicializado para referencia-lo. (Aplicavel somente para os metodos de acesso DB_BTREE e DB_RECNO.) R_NEXT Recupera o par chave/dado imediatamente apos o cursor. Se o cursor ainda nao estiver setado, este e o mesmo que o flag R_FIRST. R_PREV Recupera o par chave/dado imediatamente antes do cursor. Se o cursor ainda nao estiver setado, este e o mesmo que o flag R_LAST. (Aplicavel somente para os metodos de acesso DB_BTREE e DB_RECNO.) R_LAST e R_PREV estao disponiveis somente para os metodos de acesso DB_BTREE e DB_RECNO, porque eles implicam que as chaves tem uma ordem inerente que nao se altera. Rotinas seq retornam -1 em caso de erro (configurando errno), 0 em caso de sucesso e 1 se nao ha pares chave/dado menores ou maiores que a chave especificada ou atual. Se o metodo de acesso DB_RECNO esta sendo usado, e se o arquivo de banco de dados e um arquivo de caracteres especiais, e nenhum par chave/dado completo esta disponivel no momento, as rotinas seq retornam 2. sync Um ponteiro para uma rotina que esvazia qualquer informacao armazenada em cache no disco. Se o banco de dados esta somente na memoria, a rotina sync nao tem efeito e sempre sera bem-sucedida. O valor da flag sera setada para os seguintes valores: R_RECNOSYNC Se o metodo de acesso DB_RECNO estiver sendo usado, esta flag faz com que a rotina sync seja aplicada ao arquivo btree que e a base do arquivo recno, e nao ao proprio arquivo recno. (Veja o campo bfname da pagina de manual recno(3) para mais informacoes.) Rotinas sync retornam -1 em caso de erro (configurando errno), e 0 em caso de sucesso. Key/data pairs O acesso a todos os tipos de arquivos e baseado em pares chave/dado. Tanto a chave quanto os dados sao representados pela seguinte estrutura de dados: typedef struct { void *data; size_t size; } DBT; Os elementos da estrutura DBT sao definidos como segue: data Um ponteiro para uma sequencia de bytes. size O comprimento da sequencia de bytes. Sequencias de bytes de chaves e dados podem referenciar comprimentos essencialmente ilimitados, apesar de que quaisquer dois deles precisam caber na memoria disponivel ao mesmo tempo. Deve-se notar que os metodos de acesso nao dao garantia de alinhamento das sequencias de bytes. ERROS A rotina dbopen() pode falhar e setar errno para qualquer um dos erros especificados para as rotinas de biblioteca open(2) e malloc(3), ou o seguinte: EFTYPE Um arquivo foi formatado incorretamente. EINVAL Foi especificado um parametro (funcao de esmiucamento, byte de bloco, etc.) que e incompativel com a especificacao de arquivos corrente, ou que nao e significativo para a funcao (por exemplo, o uso do cursor sem inicializacao anterior), ou ha incompatibilidade entre o numero de versao do arquivo e o software. As rotinas close podem falhar e setar errno para qualquer um dos erros especificados para as rotinas de biblioteca close(2), read(2), write(2), free(3) ou fsync(2). As rotinas del, get, put e seq podem falhar e setar errno para qualquer um dos erros especificados para as rotinas de biblioteca read(2), write(2), free(3) ou malloc(3). As rotinas fd falharao e setarao errno para ENOENT nos banco de dados de memoria. As rotinas sync podem falhar e setar errno para qualquer um dos erros especificados para a rotina de biblioteca fsync(2). BUGS O tipo definido DBT e um mnemonico para 'data base thing' (objeto de banco de dados), e foi usado porque ninguem conseguiu pensar em um nome razoavel que ainda nao estivesse em uso. A interface de descritor de arquivo e um remendo e sera eliminado em uma versao futura da interface. Nenhum dos metodos de acessp prove qualquer forma de acesso concorrente, travamento ou transacoes. VEJA TAMBEM btree(3), hash(3), mpool(3), recno(3) LIBTP: Portable, Modular Transactions for UNIX, Margo Seltzer, Michael Olson, USENIX proceedings, Winter 1992. TRADUCAO A traducao para portugues brasileiro desta pagina man foi criada por Rubens de Jesus Nogueira e Andre Luiz Fassone Esta traducao e uma documentacao livre; leia a Licenca Publica Geral GNU Versao 3 ou posterior para as condicoes de direitos autorais. Nenhuma responsabilidade e aceita. Se voce encontrar algum erro na traducao desta pagina de manual, envie um e-mail para a lista de discussao de tradutores . 4.4 Berkeley Distribution 31 outubro 2023 dbopen(3)