Provided by: manpages-pt-dev_20040726-4_all bug

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)