.\" Copyright (c) 1990, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"	@(#)dbopen.3	8.5 (Berkeley) 1/2/94
.\"
.TH DBOPEN 3 "2 de janeiro de 1994"
.UC 7
.SH NOME
dbopen \- mtodos de acesso a banco de dados
.SH SINOPSE
.nf
.ft B
#include <sys/types.h>
#include <limits.h>
#include <db.h>

DB *
dbopen(const char *file, int flags, int mode, DBTYPE type,
.ti +5
const void *openinfo);
.ft R
.fi
.SH DESCRIO
.IR Dbopen
 a interface de biblioteca para arquivos de banco de dados.
Os formatos de arquivos suportados so btree, esmiuados e orientados a arquivos UNIX.
O formato 'btree'  uma representao de uma estrutura de rvore balanceada e ordenada.
O formato 'hash'  um esquema de esmiuamento dinmico e extensvel.
O formato 'texto plano'  um arquivo de sequncia de bytes com registros de comprimento
fixo ou varivel.
Os formatos e as informaes especficas de formato so descritas em detalhes em suas 
respectivas pginas de manual
.IR btree (3),
.IR hash (3)
e
.IR recno (3).
.PP
Dbopen abre um
.I arquivo
para leitura e/ou escrita.
Arquivos que nunca tm a pretenso de ser preservados em disco podem ser criados pela 
configurao do parmetro do arquivo para NULL.
.PP
As
.I flags
e
.I argumentos de modo
so como especificados para a rotina
.IR open (2)
, porm, somente as flags O_CREAT, O_EXCL, O_EXLOCK, O_NONBLOCK,
O_RDONLY, O_RDWR, O_SHLOCK e O_TRUNC so significativas.
(Note, a abertura de um arquivo de banco de dados O_WRONLY no  possvel.)
.\"Three additional options may be specified by
.\".IR or 'ing
.\"them into the
.\".I flags
.\"argument.
.\".TP
.\"DB_LOCK
.\"Do the necessary locking in the database to support concurrent access.
.\"If concurrent access isn't needed or the database is read-only this
.\"flag should not be set, as it tends to have an associated performance
.\"penalty.
.\".TP
.\"DB_SHMEM
.\"Place the underlying memory pool used by the database in shared
.\"memory.
.\"Necessary for concurrent access.
.\".TP
.\"DB_TXN
.\"Support transactions in the database.
.\"The DB_LOCK and DB_SHMEM flags must be set as well.
.PP
O argumento 
.I type
 do tipo DBTYPE (como definido no arquivo de incluso <db.h>) e
pode ser setado para DB_BTREE, DB_HASH ou DB_RECNO.
.PP
O argumento
.I openinfo
 um ponteiro para uma estrutura de mtodo de acesso especfica, descrita
na pgina de manual do mtodo de acesso.
Se
.I openinfo
 NULL, cada mtodo de acesso usar padres adequados para o sistema e o
mtodo de acesso.
.PP
.I 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 incluso <db.h>,  contm
pelo menos os seguintes campos:
.sp
.nf
typedef struct {
.RS
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,
.ti +5
u_int flags);
int (*sync)(const DB *db, u_int flags);
int (*seq)(const DB *db, DBT *key, DBT *data, u_int flags);
.RE
} DB;
.fi
.PP
Estes elementos descrevem um tipo de banco de dados e um conjunto de funes
realizando vrias aes. Estas funes usam um ponteiro para uma estrutura como 
retornado por
.IR dbopen ,
e s vezes um ou mais ponteiros para estruturas chave/dados e um valor de flag.
.TP
type
O tipo de mtodo-base de acesso (e formato de arquivo).
.TP
close
Um ponteiro para uma rotina que esvazia qualquer informao 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 memria, uma falha em sincronizar
o arquivo com uma funo
.I close
ou
.I sync
pode resultar em inconsistncia ou perda de informao.
Rotinas
.I Close
retornam -1 em caso de erro (configurando
.IR errno )
e 0 em caso de sucesso.
.TP
del
Um ponteiro para uma rotina que remove pares chave/dados do banco de dados.
.IP
O parmetro
.I flag
pode ser setado para os seguintes valores:
.RS
.TP
R_CURSOR
Apaga o registro referenciado pelo cursor. O cursor precisa ser inicializado previamente.
.RE
.IP
Rotinas de
.I apagamento
retornam -1 em caso de erro (configurando
.IR errno ),
0 em caso de sucesso, e 1 se a
.I chave
especificada no estiver no arquivo.
.TP
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
.I dbopen
com o mesmo nome de 
.I arquivo.
Este descritor de arquivo pode ser usado com segurana como um argumento para as funes de travamento
.IR fcntl (2)
e
.IR flock (2).
O descritor de arquivo no  associado necessariamente com qualquer um dos arquivos de base
usados pelo mtodo de acesso.
Nenhum descritor de arquivo est disponvel em banco de dados de memria. 
Rotinas
.I Fd
retornam -1 em caso de erro (configurando
.IR errno ),
e o descritor de arquivo em caso de sucesso.
.TP
get
Um ponteiro para uma rotina que  a interface para buscas chaveadas no
banco de dados.
O endereo e o comprimento dos dados associados com a 
.I chave
especfica na estrutura referenciada pelos
.IR dados .
Rotinas
.I get
retornam -1 em caso de erro (configurando
.IR errno ),
0 em caso de sucesso, e 1 se a 
.I chave
no estava no arquivo.
.TP
put
Um ponteiro para uma rotina que armazena pares chave/dados no banco de dados.
.IP
O parmetro
.I flag
pode ser setado para um dos seguintes valores:
.RS
.TP
R_CURSOR
Substitui os pares chave/dados referenciados pelo cursor.
O cursor deve ser inicializado previamente.
.TP
R_IAFTER
Acrescenta o dado imediatamente aps o dado referenciado pela
.IR chave ,
criando um novo par chave/dado.
O nmero de registro do par chave/dado acrescentado  retornado na estrutura
.I chave.
(Aplicvel somente para o mtodo de acesso DB_RECNO.)
.TP
R_IBEFORE
Insere o dado imediatamente antes do dado referenciado pela
.IR chave,
criando um novo par chave/dado.
O nmero de registro do par chave/dado  retornado na estrutura
.I chave.
(Aplicvel somente para o mtodo de acesso DB_RECNO.)
.TP
R_NOOVERWRITE
Entra o novo par chave/dado somente se a chave no existe anteriormente.
.TP
R_SETCURSOR
Armazena o par chave/dado, configurando ou inicializando a posio do cursor
para referenci-lo.
(Aplicvel somente para os mtodo de acesso DB_BTREE e DB_RECNO.)
.RE
.IP
R_SETCURSOR est disponvel somente para os mtodos de acesso DB_BTREE e DB_RECNO,
porque ele implica que as chaves tm uma ordem inerente que no se altera.
.IP
R_IAFTER e R_IBEFORE esto disponveis somente para o mtodo de acesso DB_RECNO 
porque elas implicam que o mtodo de acesso  capaz de criar novas chaves.
Isto  verdade apenas se as chaves so ordenadas e independentes, nmeros de registro
por exemplo.
.IP
O comportamento padro das rotinas
.I put
 entrar o novo par chave/dado, substituindo qualquer chave existente anteriormente.
.IP
Rotinas
.I put
retornam -1 em caso de erro (configurando
.IR errno ),
0 em caso de sucesso, e 1 se a 
.I flag
R_NOOVERWRITE foi setada e a chave j existe no arquivo.
.TP
seq
Um ponteiro para uma rotina que  a interface para uma busca sequencial
no banco de dados.
O endereo e o comprimento da chave so retornados na estrutura referenciada pela
.IR chave,
e o endereo e o comprimento dos dados so retornados na estrutura referenciada pelo
.IR dado.
.IP
Pares chave/dado sequenciais recuperados podem comear a qualquer tempo, e a
posio do 'cursor' no  afetada pela chamada das rotinas
.IR del ,
.IR get ,
.IR put ,
ou
.I sync.
As modificaes no banco de dados durante uma busca se refletiro na busca, isto ,
os registros inseridos atrs do cursor no sero retornados, enquanto que os registros 
inseridos na frente do cursor sero.
.IP
O valor da flag 
.B precisa
ser setado para um dos seguintes valores:
.RS
.TP
R_CURSOR
So retornados os dados asscociados com a chave especificada.
Isto difere das rotinas
.I get
pelo fato de ela setar ou inicializar o cursor para o local da chave tambm.
(Note, para o mtodo de acesso DB_BTREE, a chave retornada no  necessariamente uma 
combinao exata para a chave especificada. A chave retornada  a menor chave que seja 
maior ou igual  chave especificada, permitindo buscas com combinaes de chave e 
buscas de chave parciais.)
.TP
R_FIRST
 retornado o primeiro par chave/dado do banco de dados, e o cursor  setado ou inicializado
para referenci-lo.
.TP
R_LAST
 retornado o ltimo par chave/dado do banco de dados, e o cursor  setado ou inicializado para
referenci-lo.
(Aplicvel somente para os mtodos de acesso DB_BTREE e DB_RECNO.)
.TP
R_NEXT
Recupera o par chave/dado imediatamente aps o cursor. Se o cursor ainda no estiver
setado, este  o mesmo que o flag R_FIRST.
.TP
R_PREV
Recupera o par chave/dado imediatamente antes do cursor. Se o cursor ainda no estiver setado, 
este  o mesmo que o flag R_LAST.
(Aplicvel somente para os mtodos de acesso DB_BTREE e DB_RECNO.)
.RE
.IP
R_LAST e R_PREV esto disponveis somente para os mtodos de acesso DB_BTREE e DB_RECNO, porque
eles implicam que as chaves tm uma ordem inerente que no se altera.
.IP
Rotinas
.I seq
retornam -1 em caso de erro (configurando
.IR errno ),
0 em caso de sucesso e 1 se no h pares chave/dado menores ou maiores que a chave especificada
ou corrente. Se o mtodo 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 disponvel no momento, 
as rotinas
.I seq
retornam 2.
.TP
sync
Um ponteiro para uma rotina que esvazia qualquer informao armazenada em cache no disco.
Se o banco de dados est somente na memria, a rotina 
.I sync
no tem efeito e sempre ser bem-sucedida.
.IP
O valor da flag ser setada para os seguintes valores:
.RS
.TP
R_RECNOSYNC
Se o mtodo 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 no ao prprio 
arquivo recno.
(Veja o campo
.I bfname
da pgina de manual
.IR recno (3)
para mais informaes.)
.RE
.IP
Rotinas
.I sync
retornam -1 em caso de erro (configurando
.IR errno )
e 0 em caso de sucesso.
.SH "PARES CHAVE/DADO"
O acesso a todos os tipos de arquivos  baseado em pares chave/dado.
Tanto a chave quanto os dados so representados pela seguinte estrutura de dados:
.PP
typedef struct {
.RS
void *data;
.br
size_t size;
.RE
} DBT;
.PP
Os elementos da estrutura DBT so definidos como segue:
.TP
data
Um ponteiro para uma string de bytes.
.TP
size
O comprimento da string de bytes.
.PP
Strings de bytes de chaves e dados podem referenciar comprimentos essencialmente
ilimitados, apesar de que quaisquer dois deles precisam caber na memria disponvel
ao mesmo tempo.
Deve-se notar que os mtodos de acesso no do garantia de alinhamento das strings 
de bytes.
.SH ERROS
A rotina
.I dbopen
pode falhar e setar
.I errno
para qualquer um dos erros especificados para as rotinas de biblioteca
.IR open (2)
e
.IR malloc (3),
ou o seguinte:
.TP
[EFTYPE]
Um arquivo foi formatado incorretamente.
.TP
[EINVAL]
Foi especificado um parmetro (funo de esmiuamento, byte de bloco, etc.) que 
incompatvel com a especificao de arquivos corrente, ou que no 
significativo para a funo (por exemplo, o uso do cursor sem inicializao
anterior), ou h incompatibilidade entre o nmero de verso do arquivo e o
software.
.PP
As rotinas
.I close
podem falhar e setar
.I errno
para qualquer um dos erros especificados para as rotinas de biblioteca
.IR close (2),
.IR read (2),
.IR write (2),
.IR free (3),
ou
.IR fsync (2).
.PP
As rotinas
.IR del ,
.IR get ,
.I put
e
.I seq
podem falhar e setar
.I errno
para qualquer um dos erros especificados para as rotinas de biblioteca
.IR read (2),
.IR write (2),
.IR free (3)
ou
.IR malloc (3).
.PP
As rotinas
.I fd
falharo e setaro
.I errno
para ENOENT nos banco de dados de memria.
.PP
As rotinas
.I sync
podem falhar e setar
.I errno
para qualquer um dos erros especificados para a rotina de biblioteca
.IR fsync (2).
.SH "VEJA TAMBM"
.IR btree (3),
.IR hash (3),
.IR mpool (3),
.IR recno (3)
.sp
.IR "LIBTP: Transaes Portveis e Modulares para UNIX" ,
Margo Seltzer, Michael Olson, procedimentos USENIX, Winter 1992.
.SH BUGS
O tipo definido DBT  um mnemnico para "data base thing" (objeto de banco de dados), e foi usado
porque ningum conseguiu pensar em um nome razovel que ainda no estivesse em uso .
.PP
A interface de descritor de arquivo  um remendo e ser eliminado em uma verso
futura da interface.
.PP
Nenhum dos mtodos de acessp prov qualquer forma de acesso concorrente,
travamento ou transaes.
.SH TRADUO PARA A LNGUA PORTUGUESA
\&\fR\&\f(CWRUBENS DE JESUS NOGUEIRA <darkseid99@usa.net> (traduo)\fR
\&\fR\&\f(CWXXXXXX XX XXXXX XXXXXXXX <xxxxxxxxxx@xxx.xxx> (reviso)\fR