.\" -*- coding: UTF-8 -*-
.\" Copyright (c) 1990, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" %%%LICENSE_START(BSD_4_CLAUSE_UCB)
.\" 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.
.\" %%%LICENSE_END
.\"
.\"	@(#)dbopen.3	8.5 (Berkeley) 1/2/94
.\"
.\"*******************************************************************
.\"
.\" This file was generated with po4a. Translate the source file.
.\"
.\"*******************************************************************
.TH DBOPEN 3 "15 Septiembre 2017" "" "Manual del Programador de Linux"
.UC 7
.SH NOMBRE
dbopen \- métodos de acceso a bases de datos
.SH SINOPSIS
.nf
\fB#include <sys/types.h>\fP
\fB#include <limits.h>\fP
\fB#include <db.h>\fP
\fB#include <fcntl.h>\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 DESCRIPCIÓN
\fINote well\fP: This page documents interfaces provided in glibc up until
version 2.1.  Since version 2.2, glibc no longer provides these interfaces.
Probably, you are looking for the APIs provided by the \fIlibdb\fP library
instead.
.PP
\fBdbopen\fP es la interfaz de biblioteca para los ficheros de bases de
datos. Los formatos de fichero soportados son árbolB, dispersión y ficheros
orientados a UNIX. El formato árbolB es una representación de una estructura
de árbol balanceada y ordenada. El formato disperso es un esquema de
dispersión dinámico y extensible. El formato fichero plano es un fichero de
flujo de bytes con registros de longitud fija o variable. Los formatos y la
información específica de los formatos de los ficheros se describen en
detalle en sus páginas de manual respectivas \fBbtree\fP(3), \fBhash\fP(3) y
\fBrecno\fP(3).
.PP
\fBdbopen\fP abre el fichero \fIfile\fP para lectura y/o escritura. Los ficheros
destinados a ser conservados en disco nunca pueden crearse con un parámetro
\fIfile\fP con valor 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.
Las opciones, \fIflags\fP, y los argumentos de modo, \fImode\fP, son los mismos
que los indicados para la rutina \fBopen\fP(2), aunque sólo las opciones
\fBO_CREAT\fP, \fBO_EXCL\fP, \fBO_EXLOCK\fP, \fBO_NONBLOCK\fP, \fBO_RDONLY\fP, \fBO_RDWR\fP,
\fBO_SHLOCK\fP y \fBO_TRUNC\fP tienen sentido. (Dese cuenta que no es posible
abrir un fichero de base de datos con la opción \fBO_WRONLY\fP).
.PP
El argumento \fItype\fP es de tipo \fBDBTYPE\fP (tal y como se define en el
fichero cabecera \fI<db.h>\fP) y puede tener el valor \fBDB_BTREE\fP,
\fBDB_HASH\fP o \fBDB_RECNO\fP.
.PP
El argumento \fIopeninfo\fP es un puntero a una estructura específica del
método de acceso y descrita en la página de manual del método de acceso. Si
\fIopeninfo\fP es NULL, cada método de acceso usará valor por defecto
apropiados para el sistema y para el método de acceso.
.PP
\fBdbopen\fP devuelve un puntero a una estructura \fIDB\fP en caso de éxito y NULL
en caso de error. La estructura \fIDB\fP se define en el fichero cabecera
\fI<db.h>\fP y contiene, al menos, los siguientes 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
Estos elementos describen un tipo de base de datos y un conjunto de
funciones que realizan diversas acciones. Estas funciones toman un puntero a
una estructura como las devueltas por \fBdbopen\fP(), y algunas veces uno o más
punteros a estructuras clave/datos y a un valor de opción.
.TP 
\fItype\fP
El tipo del método de acceso subyacente (y del formato de fichero).
.TP 
\fIclose\fP
Un puntero a una rutina para vaciar a disco cualquier información en caché,
liberar cualquier recurso reservado y cerrar el(los) fichero(s)
subyacentes. Puesto que los pares clave/datos pueden estar en la memoria
caché, el dejar de sincronizar el fichero con las funciones \fIclose\fP o
\fIsync\fP puede producir inconsistencias o pérdida de información. Las rutinas
\fIclose\fP devuelve \-1 en caso de error (asignando un valor a \fIerrno\fP) y 0 en
caso de éxito.
.TP 
\fIdel\fP
Un puntero a una rutina para eliminar pares clave/datos de la base de datos.
.IP
The argument \fIflag\fP may be set to the following value:
.RS
.TP 
\fBR_CURSOR\fP
Borra el registro referenciado por el cursor. El cursor debe haber sido
inicializado previamente.
.RE
.IP
La rutina \fIdelete\fP devuelve \-1 en caso de error (asignando un valor a
\fIerrno\fP), 0 en caso de éxito y 1 si la clave \fIkey\fP no estaba en el
fichero.
.TP 
\fIfd\fP
Un puntero a una rutina que devuelve un descriptor de fichero representante
de la base de datos subyacente. A todos los procesos que llamen a
\fBdbopen\fP() con el mismo nombre fichero \fIfile\fP, se les devolverá un
descriptor de fichero referenciando al mismo fichero. El descriptor de
fichero se puede usar de forma segura como argumento de las funciones de
bloqueo \fBfcntl\fP(2) y \fBflock\fP(2). El descriptor de fichero no está asociado
necesariamente con ninguno de los ficheros subyacentes usados por el método
de acceso. No se dispone de ningún descriptor de fichero para las bases de
datos residentes en memoria. Las rutinas \fIfd\fP devuelven \-1 en caso de error
(asignando un valor a \fIerrno\fP), y el descriptor de fichero en caso de
éxito.
.TP 
\fIget\fP
Un puntero a una rutina que es la interfaz para la recuperación por clave de
la base de datos. La dirección y longitud de los datos asociados con la
clave especificada, \fIkey\fP, se devuelven en la estructura referenciada por
\fIdata\fP. Las rutinas \fIget\fP devuelven \-1 en caso de error (asignando un
valor a \fIerrno\fP), 0 e caso de éxito y 1 si la clave \fIkey\fP no estaba en el
fichero.
.TP 
\fIput\fP
Un puntero a una rutina para almacenar pares clave/datos en la base de
datos.
.IP
The argument \fIflag\fP may be set to one of the following values:
.RS
.TP 
\fBR_CURSOR\fP
Reemplazar el par clave/datos referenciado por el cursos. El cursor debe
haber sido inicializado previamente.
.TP 
\fBR_IAFTER\fP
Añadir los datos inmediatamente después de los datos referenciados por
\fIkey\fP, creando un nuevo par clave/datos. El número de registro del par
clave/datos añadido se devuelve en la estructura \fIkey\fP. (Aplicable sólo al
método de acceso \fBDB_RECNO\fP).
.TP 
\fBR_IBEFORE\fP
Insertar los datos inmediatamente antes de los datos referenciados por
\fIkey\fP, creando un nuevo par clave/datos. El número de registro del par
clave/datos insertado se devuelve en la estructura \fIkey\fP. (Aplicable sólo
al método de acceso \fBDB_RECNO\fP).
.TP 
\fBR_NOOVERWRITE\fP
Introducir el nuevo par clave/datos sólo si la clave no existe ya.
.TP 
\fBR_SETCURSOR\fP
Almacenar el par clave/datos, poniendo o inicializando la posición del
cursor para que lo referencie. (Aplicable sólo a los métodos de acceso
\fBDB_BTREE\fP y \fBDB_RECNO\fP).
.RE
.IP
\fBR_SETCURSOR\fP sólo está disponible para los métodos de acceso \fBDB_BTREE\fP y
\fBDB_RECNO\fP porque implica que las claves tienen un orden inherente que no
cambia.
.IP
\fBR_IAFTER\fP y \fBR_IBEFORE\fP sólo están disponibles para el método de acceso
\fBDB_RECNO\fP porque cada una de ellas implica que el método de acceso es
capaz de crear nuevas claves. Esto sólo es cierto si las claves están
ordenadas y son independientes, por ejemplo, los números de registro.
.IP
El comportamiento por defecto de las rutinas \fIput\fP es introducir el nuevo
par clave/datos, reemplazando cualquier clave ya existente.
.IP
Las rutinas \fIput\fP devuelven \-1 en caso de error (asignando un valor a
\fIerrno\fP), 0 en caso de éxito y 1 si se especificó la opción
\fBR_NOOVERWRITE\fP en \fIflag\fP y la clave ya existía en el fichero.
.TP 
\fIseq\fP
Un puntero a una rutina que es la interfaz para la recuperación secuencial
de la base de datos. La dirección y longitud de la clave se devuelven en la
estructura referenciada por \fIkey\fP, y la dirección y la longitud de los
datos se devuelven en la esctructura referenciada por \fIdata\fP.
.IP
La recuperación secuencial de pares clave/datos pueden empezar en cualquier
momento y la posición del "cursor" no se ve afectada por las llamadas a las
rutinas \fIdel\fP, \fIget\fP, \fIput\fP, o \fIsync\fP. Las modificaciones a la base de
datos durante el recorrido secuencial se reflejarán en el recorrido, es
decir, no se devolverán los registros insertados detrás del cursos mientras
que los registros insertados delante del cursor sí se devolverán.
.IP
El valor de la opción \fBdebe\fP ser uno de los siguientes valores:
.RS
.TP 
\fBR_CURSOR\fP
Se devolverán los datos asociados con la clave especificada. Esto difiere de
las rutinas \fIget\fP en las que también se posiciona o inicializa el cursor a
las posición de la clave. (Dése cuenta que para el método de acceso
\fBDB_BTREE\fP la clave devuelta no es necesariamente una coincidencia exacta
de la clave especificada. La clave devuelta es la clave más pequeña mayor o
igual que la clave especificada, permitiendo así las coincidencias parciales
de claves y las búsquedas dentro de un intervalo).
.TP 
\fBR_FIRST\fP
Se devuelve el primer par clave/datos de la base de datos y el cursor se
posiciona o inicializa para referenciarlo.
.TP 
\fBR_LAST\fP
Se devuelve el último par clave/datos de la base de datos y el cursor se
posiciona o inicializa para referenciarlo. (Aplicable sólo en los métodos de
acceso \fBDB_BTREE\fP y \fBDB_RECNO\fP).
.TP 
\fBR_NEXT\fP
Recupera el par clave/datos inmediatamente después del cursor. Si el cursor
todavía no está colocado, ésta opción es la misma que \fBR_FIRST\fP.
.TP 
\fBR_PREV\fP
Recupera el par clave/datos inmediatamente antes del cursor. Si el cursor
todavía no está colocado, ésta opción es la misma que \fBR_LAST\fP. (Aplicable
sólo en los métodos de acceso \fBDB_BTREE\fP y \fBDB_RECNO\fP).
.RE
.IP
\fBR_LAST\fP y \fBR_PREV\fP sólo están disponibles para los métodos \fBDB_BTREE\fP y
\fBDB_RECNO\fP yaque cada una de ellas implica que las claves tienen un orden
inherente que no cambia.
.IP
Las rutinas \fIseq\fP devuelven \-1 en caso de error (asignando un valor a
\fIerrno\fP), 0 en caso de éxito y 1 si no existen pares clave/datos menores o
mayores que la clave especificada o actual. Si se usa el método de acceso
\fBDB_RECNO\fP y si el fichero de la base de datos es un fichero especial de
caracteres y no se dispone actualmente de pares clave/datos completos, la
rutina \fIseq\fP devuelve 2.
.TP 
\fIsync\fP
Un puntero a una rutina para vaciar a disco cualquier información en
caché. Si la base de datos está sólo en memoria, la rutina \fIsync\fP no hace
nada y siempre tendrá éxito.
.IP
Al valor de la opción se le debe asignar el siguiente valor:
.RS
.TP 
\fBR_RECNOSYNC\fP
Si se usa el método de acceso \fBDB_RECNO\fP, esta opción hace que la rutina de
sincronización se aplique al fichero árbolB que subyace al fichero de
registros numerados, no al propio fichero de registros numerados. (Véase el
campo \fIbfname\fP de la página de manual de \fBrecno\fP(3) para más información.)
.RE
.IP
Las rutinas \fIsync\fP devuelven \-1 en caso de error (asignando un valor a
\fIerrno\fP) y 0 en caso de éxito.
.SS "Key/data pairs"
El acceso a todos los tipos de fichero se basa en los pares
clave/datos. Tanto las claves como los datos se representan mediante la
siguiente estructura de datos:
.PP
.in +4n
.EX
typedef struct {
    void  *data;
    size_t size;
} DBT;
.EE
.in
.PP
Los elementos de la estructura \fIDBT\fP se definen como sigue:
.TP 
\fIdata\fP
Un puntero a un cadena de bytes.
.TP 
\fIsize\fP
La longitud de la cadena de bytes.
.PP
Las cadenas de bytes de claves y datos pueden referenciar a cadenas de,
esencialmente, longitudes ilimitadas aunque cualesquiera dos de ellas deben
caber en memoria al mismo tiempo. Debe darse cuenta que los métodos de
acceso no garantizan la alineación de las cadenas de bytes.
.SH ERRORES
La rutina \fBdbopen\fP() puede fallar y asignar a \fIerrno\fP cualquiera de los
errores especificados para las rutinas de biblioteca \fBopen\fP(2) y
\fBmalloc\fP(3) o uno de los siguientes:
.TP 
\fBEFTYPE\fP
Un fichero está incorrectamente formateado.
.TP 
\fBEINVAL\fP
Se ha especificado un parámetro (función de dispersión, byte de relleno,
etc.) que es incompatible con la especificación actual del fichero o que no
tiene sentido para la función (por ejemplo, el uso del cursor sin una
inicialización previa) o lo números de versión del fichero y del software no
coinciden.
.PP
Las rutinas \fIclose\fP pueden fallar y asignar a \fIerrno\fP cualquiera de los
errores especificados para las rutinas de biblioteca \fBclose\fP(2),
\fBread\fP(2), \fBwrite\fP(2), \fBfree\fP(3) o \fBfsync\fP(2).
.PP
Las rutinas \fIdel\fP, \fIget\fP, \fIput\fP y \fIseq\fP pueden fallar y asignar a
\fIerrno\fP cualquiera de los errores especificados para las rutinas de
biblioteca \fBread\fP(2), \fBwrite\fP(2), \fBfree\fP(3) o \fBmalloc\fP(3).
.PP
Las rutinas \fIfd\fP pueden fallar y asignar a \fIerrno\fP el valor \fBENOENT\fP para
las bases de datos residentes en memoria.
.PP
Las rutinas \fIsync\fP pueden fallar y asignar a \fIerrno\fP cualquiera de los
errores especificados para la rutina de biblioteca \fBfsync\fP(2).
.SH ERRORES
El typedef \fIDBT\fP es un nemónico para "base de datos thang" (data base
thang), y se usó porque nadie pudo pensar en un nombre razonable que no
exisitiera ya.
.PP
La interfaz de descriptores de fichero es un latazo y se eliminará en una
futura versión de la interfaz.
.PP
Ninguno de los métodos de acceso proporciona ninguna forma de acceso
concurrente, bloqueo o transacción.
.SH "VÉASE TAMBIÉN"
\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.
.SH COLOFÓN
Esta página es parte de la versión 5.10 del proyecto Linux
\fIman\-pages\fP. Puede encontrar una descripción del proyecto, información
sobre cómo informar errores y la última versión de esta página en
\%https://www.kernel.org/doc/man\-pages/.

.SH TRADUCCIÓN
La traducción al español de esta página del manual fue creada por
Juan Piernas <piernas@ditec.um.es>
.

Esta traducción es documentación libre; lea la
.UR https://www.gnu.org/licenses/gpl-3.0.html
GNU General Public License Version 3
.UE
o posterior con respecto a las condiciones de copyright.
No existe NINGUNA RESPONSABILIDAD.

Si encuentra algún error en la traducción de esta página del manual, envíe un
correo electrónico a
.MT
debian-l10n-spanish@lists.debian.org>.
.ME .