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 {
} 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: Transações Portáveis 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)