Ubuntu Manpage: dbopen - métodos de acceso a bases de datos

NOMBRE

       dbopen - métodos de acceso a bases de datos

SINOPSIS

       #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);

DESCRIPCIÓN

Note well: 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 libdb library instead.

dbopen 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 btree(3), hash(3) y recno(3).

dbopen abre el fichero file para lectura y/o escritura. Los ficheros destinados a ser
conservados en disco nunca pueden crearse con un parámetro file con valor NULL.

Las opciones, flags, y los argumentos de modo, mode, son los mismos que los indicados para
la rutina open(2), aunque sólo las opciones O_CREAT, O_EXCL, O_EXLOCK, O_NONBLOCK,
O_RDONLY, O_RDWR, O_SHLOCK y O_TRUNC tienen sentido. (Dese cuenta que no es posible abrir
un fichero de base de datos con la opción O_WRONLY).

El argumento type es de tipo DBTYPE (tal y como se define en el fichero cabecera <db.h>) y
puede tener el valor DB_BTREE, DB_HASH o DB_RECNO.

El argumento openinfo 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 openinfo es NULL, cada método de
acceso usará valor por defecto apropiados para el sistema y para el método de acceso.

dbopen devuelve un puntero a una estructura DB en caso de éxito y NULL en caso de error.
La estructura DB se define en el fichero cabecera <db.h> y contiene, al menos, los
siguientes 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;

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 dbopen(), y algunas veces uno o más punteros a estructuras clave/datos y a un valor de
opción.

type El tipo del método de acceso subyacente (y del formato de fichero).

close 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 close o sync puede producir inconsistencias o pérdida de
información. Las rutinas close devuelve -1 en caso de error (asignando un valor a
errno) y 0 en caso de éxito.

del Un puntero a una rutina para eliminar pares clave/datos de la base de datos.

The argument flag may be set to the following value:

R_CURSOR
Borra el registro referenciado por el cursor. El cursor debe haber sido
inicializado previamente.

La rutina delete devuelve -1 en caso de error (asignando un valor a errno), 0 en
caso de éxito y 1 si la clave key no estaba en el fichero.

fd 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 dbopen() con el mismo
nombre fichero file, 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 fcntl(2) y flock(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 fd devuelven -1 en caso de error
(asignando un valor a errno), y el descriptor de fichero en caso de éxito.

get 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, key, se devuelven en la estructura referenciada por data. Las rutinas
get devuelven -1 en caso de error (asignando un valor a errno), 0 e caso de éxito y
1 si la clave key no estaba en el fichero.

put Un puntero a una rutina para almacenar pares clave/datos en la base de datos.

The argument flag may be set to one of the following values:

R_CURSOR
Reemplazar el par clave/datos referenciado por el cursos. El cursor debe
haber sido inicializado previamente.

R_IAFTER
Añadir los datos inmediatamente después de los datos referenciados por key,
creando un nuevo par clave/datos. El número de registro del par clave/datos
añadido se devuelve en la estructura key. (Aplicable sólo al método de
acceso DB_RECNO).

R_IBEFORE
Insertar los datos inmediatamente antes de los datos referenciados por key,
creando un nuevo par clave/datos. El número de registro del par clave/datos
insertado se devuelve en la estructura key. (Aplicable sólo al método de
acceso DB_RECNO).

R_NOOVERWRITE
Introducir el nuevo par clave/datos sólo si la clave no existe ya.

R_SETCURSOR
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
DB_BTREE y DB_RECNO).

R_SETCURSOR sólo está disponible para los métodos de acceso DB_BTREE y DB_RECNO
porque implica que las claves tienen un orden inherente que no cambia.

R_IAFTER y R_IBEFORE sólo están disponibles para el método de acceso DB_RECNO
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.

El comportamiento por defecto de las rutinas put es introducir el nuevo par
clave/datos, reemplazando cualquier clave ya existente.

Las rutinas put devuelven -1 en caso de error (asignando un valor a errno), 0 en
caso de éxito y 1 si se especificó la opción R_NOOVERWRITE en flag y la clave ya
existía en el fichero.

seq 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 key, y la dirección y la longitud de los datos se devuelven en la
esctructura referenciada por data.

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 del,
get, put, o sync. 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.

El valor de la opción debe ser uno de los siguientes valores:

R_CURSOR
Se devolverán los datos asociados con la clave especificada. Esto difiere de
las rutinas get 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 DB_BTREE 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).

R_FIRST
Se devuelve el primer par clave/datos de la base de datos y el cursor se
posiciona o inicializa para referenciarlo.

R_LAST 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 DB_BTREE y DB_RECNO).

R_NEXT 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 R_FIRST.

R_PREV Recupera el par clave/datos inmediatamente antes del cursor. Si el cursor
todavía no está colocado, ésta opción es la misma que R_LAST. (Aplicable
sólo en los métodos de acceso DB_BTREE y DB_RECNO).

R_LAST y R_PREV sólo están disponibles para los métodos DB_BTREE y DB_RECNO yaque
cada una de ellas implica que las claves tienen un orden inherente que no cambia.

Las rutinas seq devuelven -1 en caso de error (asignando un valor a errno), 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 DB_RECNO 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 seq devuelve 2.

sync 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 sync no hace nada y siempre tendrá
éxito.

Al valor de la opción se le debe asignar el siguiente valor:

R_RECNOSYNC
Si se usa el método de acceso DB_RECNO, 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 bfname de la página de manual de recno(3) para más información.)

Las rutinas sync devuelven -1 en caso de error (asignando un valor a errno) y 0 en
caso de éxito.

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:

typedef struct {
void *data;
size_t size;
} DBT;

Los elementos de la estructura DBT se definen como sigue:

data Un puntero a un cadena de bytes.

size La longitud de la cadena de bytes.

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.

ERRORES

       La  rutina dbopen() puede fallar y asignar a errno cualquiera de los errores especificados
       para las rutinas de biblioteca open(2) y malloc(3) o uno de los siguientes:

       EFTYPE Un fichero está incorrectamente formateado.

       EINVAL 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.

       Las  rutinas close pueden fallar y asignar a errno cualquiera de los errores especificados
       para las rutinas de biblioteca close(2), read(2), write(2), free(3) o fsync(2).

       Las rutinas del, get, put y seq pueden fallar y asignar a errno cualquiera de los  errores
       especificados para las rutinas de biblioteca read(2), write(2), free(3) o malloc(3).

       Las  rutinas  fd  pueden  fallar y asignar a errno el valor ENOENT para las bases de datos
       residentes en memoria.

       Las rutinas sync pueden fallar y asignar a errno cualquiera de los  errores  especificados
       para la rutina de biblioteca fsync(2).

ERRORES

       El  typedef  DBT  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.

       La interfaz de descriptores de fichero es un latazo y se eliminará en una  futura  versión
       de la interfaz.

       Ninguno  de los métodos de acceso proporciona ninguna forma de acceso concurrente, bloqueo
       o transacción.

VÉASE TAMBIÉN

       btree(3), hash(3), mpool(3), recno(3)

       LIBTP: Portable, Modular Transactions for  UNIX,  Margo  Seltzer,  Michael  Olson,  USENIX
       proceedings, Winter 1992.

COLOFÓN

       Esta  página es parte de la versión 5.10 del proyecto Linux man-pages. 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/.

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  GNU  General  Public  License  Version  3
       ⟨https://www.gnu.org/licenses/gpl-3.0.html⟩  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 debian-l10n-spanish@lists.debian.org ⟨⟩.