Provided by:
manpages-pt-dev_20040726-4_all 
NOME
dbopen - metodos 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,C~AO
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 abre um arquivo para leitura e/ou escrita. Arquivos que nunca
tem a pretensao de ser preservados em disco podem ser criados pela
configuracao do parametro do arquivo para NULL.
As flags e argumentos de modo sao como especificados para a rotina
open(2) , porem, somente as flags O_CREAT, O_EXCL, O_EXLOCK,
O_NONBLOCK, O_RDONLY, O_RDWR, O_SHLOCK e O_TRUNC sao significativas.
(Note, a abertura de um arquivo de banco de dados O_WRONLY nao e
possivel.)
O argumento type e do tipo DBTYPE (como definido no arquivo de inclusao
<db.h>) e pode ser setado para DB_BTREE, DB_HASH ou 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 NULL, 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
NULL em caso de erro. A estrutura DB e definida no arquivo de inclusao
<db.h>, e contem 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
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 flag.
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.
O parametro 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 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.
O parametro 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 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 corrente. 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.
PARES CHAVE/DADO
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 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 memoria disponivel ao mesmo tempo. Deve-se notar que os
metodos de acesso nao dao 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 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).
VEJA TAMB'EM
btree(3), hash(3), mpool(3), recno(3)
LIBTP: Transa,c~oes Port'aveis e Modulares para UNIX, Margo Seltzer,
Michael Olson, procedimentos USENIX, Winter 1992.
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.
TRADU,C~AO PARA A L'INGUA PORTUGUESA
RUBENS DE JESUS NOGUEIRA <darkseid99@usa.net> (traducao) XXXXXX XX
XXXXX XXXXXXXX <xxxxxxxxxx@xxx.xxx> (revisao)