Provided by: manpages-pt-dev_20040726-5_all 
NOME
dbopen - métodos de acesso a banco de dados
SINOPSE
#include <sys/types.h>
#include <limits.h>
#include <db.h>
DB *
dbopen(const char *file, int flags, int mode, DBTYPE type,
const void *openinfo);
DESCRIÇÃO
Dbopen é a interface de biblioteca para arquivos de banco de dados. Os formatos de arquivos suportados
são btree, esmiuçados e orientados a arquivos UNIX. O formato 'btree' é uma representação de uma
estrutura de árvore balanceada e ordenada. O formato 'hash' é um esquema de esmiuçamento dinâmico e
extensível. O formato 'texto plano' é um arquivo de sequência de bytes com registros de comprimento fixo
ou variável. Os formatos e as informações específicas de formato são descritas em detalhes em suas
respectivas páginas de manual btree(3), hash(3) e recno(3).
Dbopen abre um arquivo para leitura e/ou escrita. Arquivos que nunca têm a pretensão de ser preservados
em disco podem ser criados pela configuração do parâmetro do arquivo para NULL.
As flags e argumentos de modo são como especificados para a rotina open(2) , porém, somente as flags
O_CREAT, O_EXCL, O_EXLOCK, O_NONBLOCK, O_RDONLY, O_RDWR, O_SHLOCK e O_TRUNC são significativas. (Note, a
abertura de um arquivo de banco de dados O_WRONLY não é possível.)
O argumento type é do tipo DBTYPE (como definido no arquivo de inclusão <db.h>) e pode ser setado para
DB_BTREE, DB_HASH ou DB_RECNO.
O argumento openinfo é um ponteiro para uma estrutura de método de acesso específica, descrita na página
de manual do método de acesso. Se openinfo é NULL, cada método de acesso usará padrões adequados para o
sistema e o método de acesso.
Dbopen retorna um ponteiro para uma estrutura DB se for bem-sucedido, e NULL em caso de erro. A estrutura
DB é definida no arquivo de inclusão <db.h>, é contém pelo menos os seguintes campos:
typedef struct {
DBTYPE type;
int (*close)(const DB *db);
int (*del)(const DB *db, const DBT *key, u_int flags);
int (*fd)(const DB *db);
int (*get)(const DB *db, DBT *key, DBT *data, u_int flags);
int (*put)(const DB *db, DBT *key, const DBT *data,
u_int flags);
int (*sync)(const DB *db, u_int flags);
int (*seq)(const DB *db, DBT *key, DBT *data, u_int flags);
} DB;
Estes elementos descrevem um tipo de banco de dados e um conjunto de funções realizando várias ações.
Estas funções usam um ponteiro para uma estrutura como retornado por dbopen, e às vezes um ou mais
ponteiros para estruturas chave/dados e um valor de flag.
type O tipo de método-base de acesso (e formato de arquivo).
close Um ponteiro para uma rotina que esvazia qualquer informação 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 memória, uma falha em sincronizar o arquivo com uma função close ou sync pode resultar em
inconsistência ou perda de informação. 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.
O parâmetro flag pode ser setado para os seguintes valores:
R_CURSOR
Apaga o registro referenciado pelo cursor. O cursor precisa ser inicializado previamente.
Rotinas de apagamento retornam -1 em caso de erro (configurando errno), 0 em caso de sucesso, e 1
se a chave especificada não 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 será retornado para todos os
processos que chamam dbopen com o mesmo nome de arquivo. Este descritor de arquivo pode ser usado
com segurança como um argumento para as funções de travamento fcntl(2) e flock(2). O descritor de
arquivo não é associado necessariamente com qualquer um dos arquivos de base usados pelo método de
acesso. Nenhum descritor de arquivo está disponível em banco de dados de memória. 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 é a interface para buscas chaveadas no banco de dados. O endereço
e o comprimento dos dados associados com a chave específica 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
não estava no arquivo.
put Um ponteiro para uma rotina que armazena pares chave/dados no banco de dados.
O parâmetro flag pode ser setado para um dos seguintes valores:
R_CURSOR
Substitui os pares chave/dados referenciados pelo cursor. O cursor deve ser inicializado
previamente.
R_IAFTER
Acrescenta o dado imediatamente após o dado referenciado pela chave, criando um novo par
chave/dado. O número de registro do par chave/dado acrescentado é retornado na estrutura
chave. (Aplicável somente para o método de acesso DB_RECNO.)
R_IBEFORE
Insere o dado imediatamente antes do dado referenciado pela chave, criando um novo par
chave/dado. O número de registro do par chave/dado é retornado na estrutura chave.
(Aplicável somente para o método de acesso DB_RECNO.)
R_NOOVERWRITE
Entra o novo par chave/dado somente se a chave não existe anteriormente.
R_SETCURSOR
Armazena o par chave/dado, configurando ou inicializando a posição do cursor para
referenciá-lo. (Aplicável somente para os método de acesso DB_BTREE e DB_RECNO.)
R_SETCURSOR está disponível somente para os métodos de acesso DB_BTREE e DB_RECNO, porque ele
implica que as chaves têm uma ordem inerente que não se altera.
R_IAFTER e R_IBEFORE estão disponíveis somente para o método de acesso DB_RECNO porque elas
implicam que o método de acesso é capaz de criar novas chaves. Isto é verdade apenas se as chaves
são ordenadas e independentes, números de registro por exemplo.
O comportamento padrão das rotinas put é 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 já existe no arquivo.
seq Um ponteiro para uma rotina que é a interface para uma busca sequencial no banco de dados. O
endereço e o comprimento da chave são retornados na estrutura referenciada pela chave, e o
endereço e o comprimento dos dados são retornados na estrutura referenciada pelo dado.
Pares chave/dado sequenciais recuperados podem começar a qualquer tempo, e a posição do 'cursor'
não é afetada pela chamada das rotinas del, get, put, ou sync. As modificações no banco de dados
durante uma busca se refletirão na busca, isto é, os registros inseridos atrás do cursor não serão
retornados, enquanto que os registros inseridos na frente do cursor serão.
O valor da flag precisa ser setado para um dos seguintes valores:
R_CURSOR
São 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 também. (Note, para o
método de acesso DB_BTREE, a chave retornada não é necessariamente uma combinação exata
para a chave especificada. A chave retornada é a menor chave que seja maior ou igual à
chave especificada, permitindo buscas com combinações de chave e buscas de chave parciais.)
R_FIRST
É retornado o primeiro par chave/dado do banco de dados, e o cursor é setado ou
inicializado para referenciá-lo.
R_LAST É retornado o último par chave/dado do banco de dados, e o cursor é setado ou inicializado
para referenciá-lo. (Aplicável somente para os métodos de acesso DB_BTREE e DB_RECNO.)
R_NEXT Recupera o par chave/dado imediatamente após o cursor. Se o cursor ainda não estiver
setado, este é o mesmo que o flag R_FIRST.
R_PREV Recupera o par chave/dado imediatamente antes do cursor. Se o cursor ainda não estiver
setado, este é o mesmo que o flag R_LAST. (Aplicável somente para os métodos de acesso
DB_BTREE e DB_RECNO.)
R_LAST e R_PREV estão disponíveis somente para os métodos de acesso DB_BTREE e DB_RECNO, porque
eles implicam que as chaves têm uma ordem inerente que não se altera.
Rotinas seq retornam -1 em caso de erro (configurando errno), 0 em caso de sucesso e 1 se não há
pares chave/dado menores ou maiores que a chave especificada ou corrente. Se o método de acesso
DB_RECNO está sendo usado, e se o arquivo de banco de dados é um arquivo de caracteres especiais,
e nenhum par chave/dado completo está disponível no momento, as rotinas seq retornam 2.
sync Um ponteiro para uma rotina que esvazia qualquer informação armazenada em cache no disco. Se o
banco de dados está somente na memória, a rotina sync não tem efeito e sempre será bem-sucedida.
O valor da flag será setada para os seguintes valores:
R_RECNOSYNC
Se o método de acesso DB_RECNO estiver sendo usado, esta flag faz com que a rotina sync
seja aplicada ao arquivo btree que é a base do arquivo recno, e não ao próprio arquivo
recno. (Veja o campo bfname da página de manual recno(3) para mais informações.)
Rotinas sync retornam -1 em caso de erro (configurando errno) e 0 em caso de sucesso.
PARES CHAVE/DADO
O acesso a todos os tipos de arquivos é baseado em pares chave/dado. Tanto a chave quanto os dados são
representados pela seguinte estrutura de dados:
typedef struct {
void *data;
size_t size;
} DBT;
Os elementos da estrutura DBT são definidos como segue:
data Um ponteiro para uma string de bytes.
size O comprimento da string de bytes.
Strings de bytes de chaves e dados podem referenciar comprimentos essencialmente ilimitados, apesar de
que quaisquer dois deles precisam caber na memória disponível ao mesmo tempo. Deve-se notar que os
métodos de acesso não dão garantia de alinhamento das strings 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 parâmetro (função de esmiuçamento, byte de bloco, etc.) que é incompatível com
a especificação de arquivos corrente, ou que não é significativo para a função (por exemplo, o uso
do cursor sem inicialização anterior), ou há incompatibilidade entre o número de versão 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 falharão e setarão errno para ENOENT nos banco de dados de memória.
As rotinas sync podem falhar e setar errno para qualquer um dos erros especificados para a rotina de
biblioteca fsync(2).
VEJA TAMBÉM
btree(3), hash(3), mpool(3), recno(3)
LIBTP: Transações Portáveis e Modulares para UNIX, Margo Seltzer, Michael Olson, procedimentos USENIX,
Winter 1992.
BUGS
O tipo definido DBT é um mnemônico para "data base thing" (objeto de banco de dados), e foi usado porque
ninguém conseguiu pensar em um nome razoável que ainda não estivesse em uso .
A interface de descritor de arquivo é um remendo e será eliminado em uma versão futura da interface.
Nenhum dos métodos de acessp provê qualquer forma de acesso concorrente, travamento ou transações.
TRADUÇÃO PARA A LÍNGUA PORTUGUESA
RUBENS DE JESUS NOGUEIRA <darkseid99@usa.net> (tradução) XXXXXX XX XXXXX XXXXXXXX <xxxxxxxxxx@xxx.xxx>
(revisão)
4.4 Berkeley Distribution 2 de janeiro de 1994 DBOPEN(3)