Provided by: manpages-es_1.55-10_all bug

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.