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

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: Transaes Portveis  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)