dbopen(3) Library Functions Manual dbopen(3) NOM dbopen - Methodes d'acces aux bases de donnees BIBLIOTHEQUE Bibliotheque C standard (libc, -lc) SYNOPSIS #include #include #include #include DB *dbopen(const char *file, int flags, int mode, DBTYPE type, const void *openinfo); DESCRIPTION NOTE : cette page decrit des interfaces fournies jusqu'a la glibc 2.1. Depuis la glibc 2.2, la glibc ne fournit plus ces interfaces. Veuillez consulter les API fournies par la bibliotheque libdb. dbopen() est l'interface de bibliotheque pour les fichiers de bases de donnees. Les formats de fichiers pris en charge sont les arbres binaires (btree), les fichiers haches et les fichiers UNIX. L'arbre binaire est une representation d'une structure equilibree et triee. Les fichiers haches representent des tables de hachage extensibles et dynamiques. Le format de fichier UNIX est un flux d'octets avec des enregistrements de longueur fixe ou variable. Les formats et les informations specifiques aux fichiers sont fournis en detail dans les pages de manuel respectives de btree(3), hash(3) et recno(3). dbopen() ouvre le fichier file en lecture et/ou en ecriture. Les fichiers qui n'ont en aucun cas besoin d'etre sauvegardes sur le disque peuvent etre crees avec le parametre file a NULL. Les arguments flags et mode doivent etre specifies a la routine open(2). Toutefois, seuls les attributs O_CREAT, O_EXCL, O_EXLOCK, O_NONBLOCK, O_RDONLY, O_RDWR, O_SHLOCK et O_TRUNC ont un sens (veuillez noter que l'ouverture d'un fichier d'une base de donnees en mode O_WRONLY n'est pas possible). L'argument type est du type DBTYPE (defini dans le fichier d'en-tete ) et peut prendre les valeurs DB_BTREE, DB_HASH ou DB_RECNO. L'argument openinfo est un pointeur vers une structure specifique a la methode d'acces decrite dans la page de manuel de cette methode d'acces. Si openinfo est NULL, chaque methode d'acces utilisera un comportement par defaut approprie pour le systeme et le type de base de donnees. dbopen() renvoie un pointeur sur une structure DB si elle reussit, ou NULL en cas d'erreur. La structure DB est definie dans le fichier d'en-tete et contient, au moins, les champs suivants : 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; Ces elements decrivent un type de base de donnees et un jeu de fonctions effectuant diverses actions. Ces fonctions recoivent un pointeur sur une structure semblable a celle renvoyee par dbopen(), et parfois un ou plusieurs pointeurs sur des structures cles/donnees et une valeur d'attribut. type Le type de methode d'acces sous-jacent (et le type de fichier). close Un pointeur sur une routine qui vide vers le disque toutes les informations en cache, libere les ressources allouees, et ferme le(s) fichier(s). Comme les paires cles/donnees peuvent etre cachees en memoire, l'oubli de synchronisation du fichier avec les fonctions close() ou sync() peut avoir pour consequence des donnees incoherentes ou perdues. La routine close() renvoie -1 en cas d'erreur (et remplit errno) et 0 si elle reussit. del Un pointeur vers une routine permettant de supprimer des paires cles/donnees de la base de donnees. Le parametre flag peut prendre l'une des valeurs suivantes : R_CURSOR Supprimer l'enregistrement reference par le curseur. Ce curseur doit bien entendu avoir ete precedemment initialise. La routine delete() renvoie 0 si elle reussit, -1 en cas d'erreur (et definit errno), ou 1 si la cle key indiquee n'a pas ete trouvee dans le fichier. fd Un pointeur vers une routine qui renvoie le descripteur du fichier representant la base de donnees. Le meme descripteur de fichier doit etre fourni a tous les processus qui invoquent dbopen() avec le meme nom file. Ce descripteur de fichier doit pouvoir servir d'argument aux fonctions de verrouillage fcntl(2) et flock(2). Le descripteur de fichier n'est pas necessairement associe avec l'un des fichiers sous-jacents utilises par les methodes d'acces. Aucun descripteur n'est disponible pour les bases de donnees en memoire. La routine fd renvoie -1 en cas d'erreur (et definit errno), et le descripteur de fichiers en cas de succes. get Un pointeur vers la routine d'interface de recherche assistee d'une cle dans la base de donnees. L'adresse et la longueur des donnees associees avec la cle key indiquee sont fournies dans une structure referencee par l'argument data. La routine get() renvoie -1 en cas d'erreur (et remplit errno), 0 en cas de reussite, ou 1 si la cle key n'a pas ete trouvee dans le fichier. put Un pointeur vers une routine permettant de stocker les paires cles/donnees dans la base de donnees. Le parametre flag peut prendre l'une des valeurs suivantes : R_CURSOR Remplacer la paire cle/donnee referencee par le curseur. Ce curseur doit avoir ete positionne precedemment. R_IAFTER Ajouter les donnees immediatement apres les donnees referencees par la cle key, creant ainsi une nouvelle paire cle/donnee. Le numero d'enregistrement de la paire ajoutee est renvoye dans la structure key (utilisable uniquement avec la methode d'acces DB_RECNO). R_IBEFORE Ajouter les donnees immediatement avant les donnees referencees par key, creant ainsi une nouvelle paire cle/donnee. Le numero d'enregistrement de la paire inseree est renvoye dans la structure key (utilisable uniquement avec la methode d'acces DB_RECNO). R_NOOVERWRITE N'ajouter la paire cle/donnee que si la cle n'existe pas precedemment. R_SETCURSOR Enregistrer la paire cle/donnee, en positionnant ou initialisant la position du curseur pour la referencer (utilisable uniquement avec les methodes d'acces DB_RECNO et DB_TREE). R_SETCURSOR n'est disponible que pour les methodes DB_BTREE et DB_RECNO car cela implique que les cles ont un ordre inherent immuable. R_IAFTER et R_IBEFORE ne sont disponibles qu'avec la methode DB_RECNO car ils impliquent que la methode d'acces soit capable de creer de nouvelles cles. Cela n'est vrai que si les cles sont ordonnees et independantes, comme des numeros d'enregistrement. Le comportement par defaut de la routine put est de stocker une nouvelle paire cle/donnee, en remplacant toute cle existant precedemment. Les routines put() renvoient -1 en cas d'erreur (et remplissent errno), 0 en cas de succes, ou 1 si l'attribut R_NOOVERWRITE a ete indique dans flag, et si la cle existait deja dans le fichier. seq Un pointeur vers la routine d'interface pour la recherche sequentielle dans la base de donnees. L'adresse et la longueur de la cle sont renvoyees dans une structure referencee par key, et l'adresse et la longueur des donnees dans une structure referencee par data. La rechercher sequentielle de paire cle/donnee peut avoir lieu a tout moment, et la position du << curseur >> n'est pas affectee par les routine del(), get(), put(), ou sync(). Les modifications de la base de donnees durant un balayage sequentiel seront visibles par le balayage, c'est-a-dire que les enregistrements inseres avant le curseur ne seront pas vus, mais les enregistrements inseres apres le curseur seront renvoyes. La valeur de flags doit etre l'une des valeurs suivantes : R_CURSOR La routine renvoie les donnees associees avec la cle indiquee. C'est different du comportement de la routine get() car le curseur est egalement positionne ou initialise. (Veuillez noter que pour la methode d'acces DB_BTREE, la cle renvoyee ne correspond pas necessairement a la cle indiquee. On retourne la plus petite cle superieure ou egale a celle indiquee, ce qui permet des correspondances partielles ou des recherches d'intervalles). R_FIRST On renvoie la premiere paire cle/donnee de la base, et le curseur est initialise ou positionne pour la referencer. R_LAST On renvoie la derniere paire cle/donnee de la base, et le curseur est initialise ou positionne pour la referencer. (Disponible uniquement pour les methodes DB_BTREE et DB_RECNO). R_NEXT Renvoyer la paire cle/donnee immediatement apres le curseur. Si le curseur n'est pas positionne, le comportement est le meme que R_FIRST. R_PREV Renvoyer la paire cle/donnee immediatement avant le curseur. Si le curseur n'est pas positionne, le comportement est le meme que R_LAST. (Disponible uniquement pour les methodes DB_BTREE et DB_RECNO). R_LAST et R_PREV ne sont disponibles que pour les methodes DB_BTREE et DB_RECNO car ils impliquent que les cles aient un ordre inherent immuable. La routine seq() renvoie -1 en cas d'erreur (et remplit errno), 0 en cas de succes, et 1 s'il n'y a pas de paire cle/donnee superieure ou egale a la cle indiquee ou courante. Si on utilise la methode DB_RECNO, si le fichier de base de donnees est un fichier special en mode caracteres, et si aucune paire cle/donnee complete n'est actuellement disponible, la routine seq renvoie 2. sync Un pointeur vers une routine permettant de vider sur disque toutes les informations en cache. Si la base de donnees est uniquement en memoire, la routine sync() n'a pas d'effet et reussira toujours. La valeur de flags peut etre la suivante : R_RECNOSYNC Si on utilise la methode DB_RECNO, ce drapeau oblige la synchronisation a s'appliquer au fichier btree sous-jacent du fichier recno, et non pas a ce dernier. (Consultez le champ bfname de la page de manuel recno(3) pour plus d'informations.) La routine sync() renvoie -1 en cas d'erreur (et remplit errno) ou 0 en cas de reussite. Paires cle/donnees L'acces a tous les types de fichiers est base sur les paires cles/donnees. La structure de donnee suivante represente a la fois les cles et les donnees. typedef struct { void *data; size_t size; } DBT; Les elements de la structure DBT sont definis ainsi : data Un pointeur vers une chaine d'octets. size La longueur de la chaine d'octets. Les chaines d'octets des cles et des donnees peuvent avoir n'importe quelle longueur, avec la limitation que deux quelconques d'entre elles doivent pouvoir tenir simultanement en memoire. Remarquez que les methodes d'acces ne fournissent aucune garantie en ce qui concerne les alignements des chaines d'octets. ERREURS La routine dbopen() peut echouer et placer dans errno n'importe laquelle des erreurs renvoyees par les routines open(2) et malloc(3) ou l'une des erreurs suivantes : EFTYPE Un fichier est mal formate. EINVAL Un parametre indique (par exemple fonction de hachage) est incompatible avec les specifications du fichier actuel, ou n'a pas de sens pour la fonction (par exemple utiliser le curseur sans initialisation prealable). Ou encore, il y a une incompatibilite dans les numeros de version du fichier et du logiciel. Les routines close() peuvent echouer et definir dans errno l'une des erreurs specifiees par les routines de bibliotheque close(2), read(2), write(2), free(3), ou fsync(2). Les routines del, get, put et seq peuvent echouer et definir dans errno l'une des erreurs specifiees par les routines de bibliotheque read(2), write(2), free(3) ou malloc(3). Les routine fd peuvent echouer et definir errno a ENOENT pour les bases de donnees en memoire. Les routines sync peuvent echouer et definir dans errno l'une des erreurs specifiees par la routine de bibliotheque fsync(2). BOGUES Le typedef DBT est un mnemonique pour << data base thang >>, qui a ete choisi car personne n'arrivait a trouver un nom raisonnable et pas encore utilise. L'interface avec les descripteurs de fichier est une bidouille et sera supprimee dans les versions futures de l'interface. Aucune methode d'acces ne fournit de transactions, de verrouillages ou d'acces concurrents. VOIR AUSSI btree(3), hash(3), mpool(3), recno(3) LIBTP: Portable, Modular Transactions for UNIX, Margo Seltzer, Michael Olson, USENIX proceedings, Winter 1992. TRADUCTION La traduction francaise de cette page de manuel a ete creee par Christophe Blaess , Stephan Rafin , Thierry Vignaud , Francois Micaux, Alain Portal , Jean-Philippe Guerard , Jean-Luc Coulon (f5ibh) , Julien Cristau , Thomas Huriaux , Nicolas Francois , Florentin Duneau , Simon Paillard , Denis Barbier et David Prevot Cette traduction est une documentation libre ; veuillez vous reporter a la GNU General Public License version 3 concernant les conditions de copie et de distribution. Il n'y a aucune RESPONSABILITE LEGALE. Si vous decouvrez un bogue dans la traduction de cette page de manuel, veuillez envoyer un message a . 4.4 Berkeley Distribution 31 octobre 2023 dbopen(3)