Provided by: manpages-es_1.55-8_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.