dbopen(3) Library Functions Manual dbopen(3) NOMBRE dbopen - metodos de acceso a bases de datos BIBLIOTECA Biblioteca Estandar C (libc, -lc) SINOPSIS #include #include #include #include DB *dbopen(const char *file, int flags, int mode, DBTYPE type, const void *openinfo); DESCRIPCION 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 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 ) 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 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 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. 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 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. 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 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. Key/data pairs 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). 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). ERRORES El typedef DBT es un nemonico para "base de datos thang" (data base thang), 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. VEASE TAMBIEN btree(3), hash(3), mpool(3), recno(3) LIBTP: Portable, Modular Transactions for UNIX, Margo Seltzer, Michael Olson, USENIX proceedings, Winter 1992. TRADUCCION La traduccion al espanol de esta pagina del manual fue creada por Juan Piernas Esta traduccion es documentacion libre; lea la GNU General Public License Version 3 o posterior con respecto a las condiciones de copyright. No existe NINGUNA RESPONSABILIDAD. Si encuentra algun error en la traduccion de esta pagina del manual, envie un correo electronico a . 4.4 Berkeley Distribution 31 Octubre 2023 dbopen(3)