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

NOMBRE

       dbopen - metodos 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'ON

       Dbopen  es  la  interfaz  de  biblioteca  para los ficheros de bases de
       datos.  Los formatos de fichero soportados  son  arbolB,  dispersion  y
       ficheros orientados a UNIX.  El formato arbolB es una representacion de
       una estructura de arbol balanceada y ordenada.  El formato disperso  es
       un  esquema  de  dispersion  dinamico y extensible.  El formato fichero
       plano es un fichero de flujo de bytes con registros de longitud fija  o
       variable.   Los formatos y la informacion especifica de los formatos de
       los  ficheros  se  describen  en  detalle  en  sus  paginas  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
       parametro 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 solo 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 opcion 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  especifica  del
       metodo  de  acceso  y  descrita  en  la  pagina de manual del metodo de
       acceso.  Si openinfo es NULL, cada metodo de  acceso  usara  valor  por
       defecto apropiados para el sistema y para el metodo de acceso.

       Dbopen  devuelve un puntero a una estructura DB en caso de exito 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 mas punteros a estructuras clave/datos y a un valor de opcion.

       type   El tipo del metodo  de  acceso  subyacente  (y  del  formato  de
              fichero).

       close  Un   puntero   a  una  rutina  para  vaciar  a  disco  cualquier
              informacion en cache,  liberar  cualquier  recurso  reservado  y
              cerrar  el(los)  fichero(s)  subyacentes.   Puesto que los pares
              clave/datos pueden estar  en  la  memoria  cache,  el  dejar  de
              sincronizar  el  fichero  con  las  funciones close o sync puede
              producir inconsistencias o perdida de informacion.  Las  rutinas
              close  devuelve -1 en caso de error (asignando un valor a errno)
              y 0 en caso de exito.

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

              Al parametro 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 exito 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 devolvera 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  esta  asociado  necesariamente  con
              ninguno  de  los  ficheros  subyacentes  usados por el metodo de
              acceso.  No se dispone de ningun 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 exito.

       get    Un  puntero a una rutina que es la interfaz para la recuperacion
              por clave de la base de datos.  La direccion 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
              exito 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  parametro  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
                     Anadir  los  datos  inmediatamente  despues  de los datos
                     referenciados por key, creando un nuevo par  clave/datos.
                     El  numero  de  registro  del  par clave/datos anadido se
                     devuelve en la estructura key.  (Aplicable solo al metodo
                     de acceso DB_RECNO).

              R_IBEFORE
                     Insertar  los  datos  inmediatamente  antes  de los datos
                     referenciados por key, creando un nuevo par  clave/datos.
                     El  numero  de  registro del par clave/datos insertado se
                     devuelve en la estructura key.  (Aplicable solo al metodo
                     de acceso DB_RECNO).

              R_NOOVERWRITE
                     Introducir  el  nuevo par clave/datos solo si la clave no
                     existe ya.

              R_SETCURSOR
                     Almacenar el par clave/datos, poniendo o inicializando la
                     posicion  del  cursor para que lo referencie.  (Aplicable
                     solo a los metodos de acceso DB_BTREE y DB_RECNO).

              R_SETCURSOR solo esta disponible  para  los  metodos  de  acceso
              DB_BTREE  y  DB_RECNO  porque  implica  que las claves tienen un
              orden inherente que no cambia.

              R_IAFTER y R_IBEFORE solo estan disponibles para  el  metodo  de
              acceso  DB_RECNO  porque cada una de ellas implica que el metodo
              de acceso es capaz de crear nuevas claves.  Esto solo es  cierto
              si las claves estan ordenadas y son independientes, por ejemplo,
              los numeros 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 exito y 1 si se especifico la
              opcion R_NOOVERWRITE en  flag  y  la  clave  ya  existia  en  el
              fichero.

       seq    Un  puntero a una rutina que es la interfaz para la recuperacion
              secuencial de la base de datos.  La direccion y longitud  de  la
              clave  se  devuelven en la estructura referenciada por key, y la
              direccion y  la  longitud  de  los  datos  se  devuelven  en  la
              esctructura referenciada por data.

              La  recuperacion  secuencial de pares clave/datos pueden empezar
              en cualquier momento y la  posicion  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  reflejaran  en  el  recorrido,  es  decir, no se
              devolveran los registros insertados detras del  cursos  mientras
              que   los   registros   insertados  delante  del  cursor  si  se
              devolveran.

              El valor de la opcion debe ser uno de los siguientes valores:

              R_CURSOR
                     Se  devolveran  los  datos   asociados   con   la   clave
                     especificada.  Esto difiere de las rutinas get en las que
                     tambien  se  posiciona  o  inicializa  el  cursor  a  las
                     posicion de la clave.  (Dese cuenta que para el metodo de
                     acceso DB_BTREE la clave devuelta  no  es  necesariamente
                     una  coincidencia  exacta  de  la clave especificada.  La
                     clave devuelta es la clave mas pequena mayor o igual  que
                     la  clave especificada, permitiendo asi las coincidencias
                     parciales  de  claves  y  las  busquedas  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 ultimo par clave/datos de la base de datos
                     y el cursor se posiciona o inicializa para referenciarlo.
                     (Aplicable solo en  los  metodos  de  acceso  DB_BTREE  y
                     DB_RECNO).

              R_NEXT Recupera  el  par  clave/datos inmediatamente despues del
                     cursor.  Si el cursor  todavia  no  esta  colocado,  esta
                     opcion es la misma que R_FIRST.

              R_PREV Recupera  el  par  clave/datos  inmediatamente  antes del
                     cursor.  Si el cursor  todavia  no  esta  colocado,  esta
                     opcion  es  la  misma que R_LAST.  (Aplicable solo en los
                     metodos de acceso DB_BTREE y DB_RECNO).

              R_LAST y R_PREV solo estan disponibles para los metodos 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 exito y 1 si no existen pares
              clave/datos menores  o  mayores  que  la  clave  especificada  o
              actual.   Si se usa el metodo 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
              informacion en cache.  Si la base de datos esta solo en memoria,
              la rutina sync no hace nada y siempre tendra exito.

              Al valor de la opcion se le debe asignar el siguiente valor:

              R_RECNOSYNC
                     Si se usa el metodo de acceso DB_RECNO, esta opcion  hace
                     que  la  rutina  de  sincronizacion se aplique al fichero
                     arbolB que subyace al fichero de registros numerados,  no
                     al  propio  fichero  de  registros  numerados.  (Vease el
                     campo bfname de la pagina de manual de recno(3) para  mas
                     informacion.)

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

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
       metodos de acceso no garantizan la alineacion 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 esta incorrectamente formateado.

       [EINVAL]
              Se  ha especificado un parametro (funcion de dispersion, byte de
              relleno, etc.) que es incompatible con la especificacion  actual
              del fichero o que no tiene sentido para la funcion (por ejemplo,
              el uso del cursor sin una inicializacion previa) o lo numeros de
              version 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'EASE TAMBI'EN

       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 nemonico para ``base de datos thung''  (data  base
       thung), y se uso porque nadie pudo pensar en un nombre razonable que no
       exisitiera ya.

       La interfaz de descriptores de fichero es un latazo y se  eliminara  en
       una futura version de la interfaz.

       Ninguno  de  los  metodos de acceso proporciona ninguna forma de acceso
       concurrente, bloqueo o transaccion.