.\" -*- coding: UTF-8 -*- .\" Copyright (c) 1990, 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" SPDX-License-Identifier: BSD-4-Clause-UC .\" .\" @(#)dbopen.3 8.5 (Berkeley) 1/2/94 .\" .\"******************************************************************* .\" .\" This file was generated with po4a. Translate the source file. .\" .\"******************************************************************* .TH dbopen 3 "4 dezembro 2022" "Linux man\-pages 6.05.01" .UC 7 .SH NOME dbopen \- métodos de acesso a banco de dados .SH BIBLIOTECA Biblioteca C Padrão (\fIlibc\fP, \fI\-lc\fP) .SH SINOPSE .nf \fB#include \fP \fB#include \fP \fB#include \fP \fB#include \fP .PP \fBDB *dbopen(const char *\fP\fIfile\fP\fB, int \fP\fIflags\fP\fB, int \fP\fImode\fP\fB, DBTYPE \fP\fItype\fP\fB,\fP \fB const void *\fP\fIopeninfo\fP\fB);\fP .fi .SH DESCRIÇÃO \fINote well\fP: 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 \fIlibdb\fP library instead. .PP \fIdbopen\fP() é 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 \fBbtree\fP(3), \fBhash\fP(3) e \fBrecno\fP(3). .PP \fBdbopen\fP() opens \fIfile\fP for reading and/or writing. Files never intended to be preserved on disk may be created by setting the \fIfile\fP argument to NULL. .PP .\"Three additional options may be specified by ORing .\"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. The \fIflags\fP and \fImode\fP arguments are as specified to the \fBopen\fP(2) routine, however, only the \fBO_CREAT\fP, \fBO_EXCL\fP, \fBO_EXLOCK\fP, \fBO_NONBLOCK\fP, \fBO_RDONLY\fP, \fBO_RDWR\fP, \fBO_SHLOCK\fP, and \fBO_TRUNC\fP flags are meaningful. (Note, opening a database file \fBO_WRONLY\fP is not possible.) .PP The \fItype\fP argument is of type \fIDBTYPE\fP (as defined in the \fI\fP include file) and may be set to \fBDB_BTREE\fP, \fBDB_HASH\fP, or \fBDB_RECNO\fP. .PP O argumento \fIopeninfo\fP é um ponteiro para uma estrutura de método de acesso específica, descrita na página de manual do método de acesso. Se \fIopeninfo\fP é NULO, cada método de acesso usará padrões adequados para o sistema e o método de acesso. .PP \fBdbopen\fP() retorna um ponteiro para uma estrutura \fIDB\fP se for bem\-sucedido, e NULO em caso de erro. A estrutura \fIDB\fP é definida no arquivo 'include' \fI\fP, é contém pelo menos os seguintes campos: .PP .in +4n .EX 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; .EE .in .PP 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 \fBdbopen\fP(), e às vezes um ou mais ponteiros para estruturas chave/dados e um valor de sinalização. .TP \fItype\fP O tipo de método\-base de acesso (e formato de arquivo). .TP \fIclose\fP 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 \fIclose\fP ou \fIsync\fP pode resultar em inconsistência ou perda de informação. Rotinas \fIclose\fP retornam \-1 em caso de erro (configurando \fBerrno\fP), e 0 em caso de sucesso. .TP \fIdel\fP Um ponteiro para uma rotina que remove pares chave/dados do banco de dados. .IP The argument \fIflag\fP may be set to the following value: .RS .TP \fBR_CURSOR\fP Apaga o registro referenciado pelo cursor. O cursor precisa ser inicializado previamente. .RE .IP Rotinas \fIdelete\fP retornam \-1 em caso de erro (configurando \fBerrno\fP), 0 em caso de sucesso, e 1 se a \fIchave\fP especificada não estiver no arquivo. .TP \fIfd\fP 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 \fBdbopen\fP() com o mesmo nome de \fIarquivo\fP. Este descritor de arquivo pode ser usado com segurança como um argumento para as funções de travamento \fBfcntl\fP(2) e \fBflock\fP(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 \fIfd\fP retornam \-1 em caso de erro (configurando \fBerrno\fP), e o descritor de arquivo em caso de sucesso. .TP \fIget\fP 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 \fIchave\fP específica na estrutura referenciada pelos \fIdados\fP. Rotinas \fIget\fP retornam \-1 em caso de erro (configurando \fBerrno\fP), 0 em caso de sucesso, e 1 se a \fIchave\fP não estava no arquivo. .TP \fIput\fP Um ponteiro para uma rotina que armazena pares chave/dados no banco de dados. .IP The argument \fIflag\fP may be set to one of the following values: .RS .TP \fBR_CURSOR\fP Substitui os pares chave/dados referenciados pelo cursor. O cursor deve ser inicializado previamente. .TP \fBR_IAFTER\fP Acrescenta o dado imediatamente após o dado referenciado pela \fIchave\fP, criando um novo par chave/dado. O número de registro do par chave/dado acrescentado é retornado na estrutura \fIchave\fP. (Aplicável somente para o método de acesso \fBDB_RECNO\fP.) .TP \fBR_IBEFORE\fP Insere o dado imediatamente antes do dado referenciado pela \fIchave\fP, criando um novo par chave/dado. O número de registro do par chave/dado é retornado na estrutura \fIchave\fP. (Aplicável somente para o método de acesso \fBDB_RECNO\fP.) .TP \fBR_NOOVERWRITE\fP Entra o novo par chave/dado somente se a chave não existe anteriormente. .TP \fBR_SETCURSOR\fP 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 \fBDB_BTREE\fP e \fBDB_RECNO\fP.) .RE .IP \fBR_SETCURSOR\fP está disponível somente para os métodos de acesso \fBDB_BTREE\fP e \fBDB_RECNO\fP, porque ele implica que as chaves têm uma ordem inerente que não se altera. .IP \fBR_IAFTER\fP e \fBR_IBEFORE\fP estão disponíveis somente para o método de acesso \fBDB_RECNO\fP 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. .IP O comportamento padrão das rotinas \fIput\fP é entrar o novo par chave/dado, substituindo qualquer chave existente anteriormente. .IP Rotinas \fIput\fP retornam \-1 em caso de erro (configurando \fBerrno\fP), 0 em caso de sucesso, e 1 se a \fIflag\fP \fBR_NOOVERWRITE\fP foi setada e a chave já existe no arquivo. .TP \fIseq\fP 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 \fIchave\fP, e o endereço e o comprimento dos dados são retornados na estrutura referenciada pelo \fIdado\fP. .IP Pares chave/dado sequenciais recuperados podem começar a qualquer tempo, e a posição do 'cursor' não é afetada pela chamada das rotinas \fIdel\fP, \fIget\fP, \fIput\fP, ou \fIsync\fP. 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. .IP O valor da flag \fBprecisa\fP ser setado para um dos seguintes valores: .RS .TP \fBR_CURSOR\fP São retornados os dados asscociados com a chave especificada. Isto difere das rotinas \fIget\fP pelo fato de ela setar ou inicializar o cursor para o local da chave também. (Note, para o método de acesso \fBDB_BTREE\fP, 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.) .TP \fBR_FIRST\fP É retornado o primeiro par chave/dado do banco de dados, e o cursor é setado ou inicializado para referenciá\-lo. .TP \fBR_LAST\fP É 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 \fBDB_BTREE\fP e \fBDB_RECNO\fP.) .TP \fBR_NEXT\fP Recupera o par chave/dado imediatamente após o cursor. Se o cursor ainda não estiver setado, este é o mesmo que o flag \fBR_FIRST\fP. .TP \fBR_PREV\fP Recupera o par chave/dado imediatamente antes do cursor. Se o cursor ainda não estiver setado, este é o mesmo que o flag \fBR_LAST\fP. (Aplicável somente para os métodos de acesso \fBDB_BTREE\fP e \fBDB_RECNO\fP.) .RE .IP \fBR_LAST\fP e \fBR_PREV\fP estão disponíveis somente para os métodos de acesso \fBDB_BTREE\fP e \fBDB_RECNO\fP, porque eles implicam que as chaves têm uma ordem inerente que não se altera. .IP Rotinas \fIseq\fP retornam \-1 em caso de erro (configurando \fBerrno\fP), 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 \fBDB_RECNO\fP 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 \fIseq\fP retornam 2. .TP \fIsync\fP 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 \fIsync\fP não tem efeito e sempre será bem\-sucedida. .IP O valor da flag será setada para os seguintes valores: .RS .TP \fBR_RECNOSYNC\fP Se o método de acesso \fBDB_RECNO\fP 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 \fIbfname\fP da página de manual \fBrecno\fP(3) para mais informações.) .RE .IP Rotinas \fIsync\fP retornam \-1 em caso de erro (configurando \fBerrno\fP), e 0 em caso de sucesso. .SS "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: .PP .in +4n .EX typedef struct { void *data; size_t size; } DBT; .EE .in .PP Os elementos da estrutura \fIDBT\fP são definidos como segue: .TP \fIdata\fP Um ponteiro para uma seqüencia de bytes. .TP \fIsize\fP O comprimento da seqüencia de bytes. .PP 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. .SH ERROS A rotina \fBdbopen\fP() pode falhar e setar \fIerrno\fP para qualquer um dos erros especificados para as rotinas de biblioteca \fBopen\fP(2) e \fBmalloc\fP(3), ou o seguinte: .TP \fBEFTYPE\fP Um arquivo foi formatado incorretamente. .TP \fBEINVAL\fP 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. .PP As rotinas \fIclose\fP podem falhar e setar \fIerrno\fP para qualquer um dos erros especificados para as rotinas de biblioteca \fBclose\fP(2), \fBread\fP(2), \fBwrite\fP(2), \fBfree\fP(3) ou \fBfsync\fP(2). .PP As rotinas \fIdel\fP, \fIget\fP, \fIput\fP e \fIseq\fP podem falhar e setar \fIerrno\fP para qualquer um dos erros especificados para as rotinas de biblioteca \fBread\fP(2), \fBwrite\fP(2), \fBfree\fP(3) ou \fBmalloc\fP(3). .PP As rotinas \fIfd\fP falharão e setarão \fIerrno\fP para \fBENOENT\fP nos banco de dados de memória. .PP As rotinas \fIsync\fP podem falhar e setar \fIerrno\fP para qualquer um dos erros especificados para a rotina de biblioteca \fBfsync\fP(2). .SH BUGS O tipo definido \fIDBT\fP é 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. .PP A interface de descritor de arquivo é um remendo e será eliminado em uma versão futura da interface. .PP Nenhum dos métodos de acessp provê qualquer forma de acesso concorrente, travamento ou transações. .SH "VEJA TAMBÉM" \fBbtree\fP(3), \fBhash\fP(3), \fBmpool\fP(3), \fBrecno\fP(3) .PP \fILIBTP: Portable, Modular Transactions for UNIX\fP, Margo Seltzer, Michael Olson, USENIX proceedings, Winter 1992. .PP .SH TRADUÇÃO A tradução para português brasileiro desta página man foi criada por Rubens de Jesus Nogueira e André Luiz Fassone . .PP Esta tradução é uma documentação livre; leia a .UR https://www.gnu.org/licenses/gpl-3.0.html Licença Pública Geral GNU Versão 3 .UE ou posterior para as condições de direitos autorais. Nenhuma responsabilidade é aceita. .PP Se você encontrar algum erro na tradução desta página de manual, envie um e-mail para .MT debian-l10n-portuguese@lists.debian.org a lista de discussão de tradutores .ME .