Provided by: manpages-es_1.55-10_all 
NOMBRE
dbopen - métodos de acceso a bases de datos
SINOPSIS
#include <sys/types.h>
#include <limits.h>
#include <db.h>
DB *
dbopen(const char *file, int flags, int mode, DBTYPE type,
const void *openinfo);
DESCRIPCIÓN
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, 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;
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.
Al parámetro flag se le pueden asignar el siguiente valor:
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.
Al parámetro flag se le puede asignar uno de los siguientes valores:
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.
PARES CLAVE/DATOS
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).
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.
FALLOS
El typedef DBT es un nemónico para ``base de datos thung'' (data base thung), 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.
4.4 Berkeley Distribution 2 Enero 1994 DBOPEN(3)