Provided by: manpages-pt-br-dev_4.18.1-1_all 
NOME
dbopen - métodos de acesso a banco de dados
BIBLIOTECA
Biblioteca C Padrão (libc, -lc)
SINOPSE
#include <sys/types.h>
#include <limits.h>
#include <db.h>
#include <fcntl.h>
DB *dbopen(const char *file, int flags, int mode, DBTYPE type,
const void *openinfo);
DESCRIÇÃO
Note well: This page documents interfaces provided up until glibc 2.1. Since glibc 2.2,
glibc no longer provides these interfaces. Probably, you are looking for the APIs
provided by the libdb library instead.
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() opens file for reading and/or writing. Files never intended to be preserved on
disk may be created by setting the file argument to NULL.
The flags and mode arguments are as specified to the open(2) routine, however, only the
O_CREAT, O_EXCL, O_EXLOCK, O_NONBLOCK, O_RDONLY, O_RDWR, O_SHLOCK, and O_TRUNC flags are
meaningful. (Note, opening a database file O_WRONLY is not possible.)
The type argument is of type DBTYPE (as defined in the <db.h> include file) and may be set
to DB_BTREE, DB_HASH, or 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 é NULO, 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 NULO em caso de
erro. A estrutura DB é definida no arquivo 'include' <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, unsigned int flags);
int (*fd)(const DB *db);
int (*get)(const DB *db, DBT *key, DBT *data,
unsigned int flags);
int (*put)(const DB *db, DBT *key, const DBT *data,
unsigned int flags);
int (*sync)(const DB *db, unsigned int flags);
int (*seq)(const DB *db, DBT *key, DBT *data,
unsigned 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
sinalização.
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.
The argument flag may be set to the following value:
R_CURSOR
Apaga o registro referenciado pelo cursor. O cursor precisa ser inicializado
previamente.
Rotinas delete 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.
The argument flag may be set to one of the following values:
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
atual. 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.
Key/data pairs
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 seqüencia de bytes.
size O comprimento da seqüencia de bytes.
Seqüencias 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
seqüencias 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).
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.
VEJA TAMBÉM
btree(3), hash(3), mpool(3), recno(3)
LIBTP: Portable, Modular Transactions for UNIX, Margo Seltzer, Michael Olson, USENIX
proceedings, Winter 1992.
TRADUÇÃO
A tradução para português brasileiro desta página man foi criada por Rubens de Jesus
Nogueira <darkseid99@usa.net> e André Luiz Fassone <lonely_wolf@ig.com.br>
Esta tradução é uma documentação livre; leia a Licença Pública Geral GNU Versão 3
⟨https://www.gnu.org/licenses/gpl-3.0.html⟩ ou posterior para as condições de direitos
autorais. Nenhuma responsabilidade é aceita.
Se você encontrar algum erro na tradução desta página de manual, envie um e-mail para a
lista de discussão de tradutores ⟨debian-l10n-portuguese@lists.debian.org⟩.