dbopen - métodos de acceso a bases de datos
Biblioteca Estándar C (libc, -lc)
#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);
Note well: 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 libdb library
instead.
dbopen() is the library interface to database files. The
supported file formats are btree, hashed, and UNIX file oriented. The btree
format is a representation of a sorted, balanced tree structure. The hashed
format is an extensible, dynamic hashing scheme. The flat-file format is a
byte stream file with fixed or variable length records. The formats and
file-format-specific information are described in detail in their respective
manual pages btree(3), hash(3), and 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.
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.
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).
The del, get, put, and seq routines
may fail and set errno for any of the errors specified for the
library routines read(2), write(2), free(3), or
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).
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.
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 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.