DBOPEN(3) Manuel du programmeur Linux DBOPEN(3) NOM dbopen - Mthodes d'accs aux bases de donnes. SYNOPSIS #include <sys/types.h> #include <limits.h> #include <db.h> DB * dbopen(const char *fichier, int attributs, int mode, DBTYPE type_base, const void *openinfo); DESCRIPTION Dbopen est l'interface de bibliothque pour les fichiers de bases de donnes. Les formats de fichiers supports sont les arbres binaires, les fichiers hachs et les fichiers UNIX. L'arbre binaire est une reprsentation d'une structure quilibre et trie. Les fichiers hachs reprsentent 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 spcifiques aux fichiers sont fournis en dtail dans les pages de manuel respectives btree(3), hash(3) et recno(3). Dbopen ouvre le fichier en lecture et/ou criture. Les fichiers qui n'ont en aucun cas besoin d'tre sauvegards sur disque peuvent tre crs avec le paramtre de fichier NULL. Les arguments attribut et mode doivent tre spcifis pour la rou- tine open(2,3,n)(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. (Notez que l'ouverture d'un fichier de base de donnes en mode O_WRONLY n'est pas possible.) Le type_base est un argument ayant le type DBTYPE (dfini dans le fichier d'en-tte <db.h>) et peut prendre les valeurs DB_BTREE, DB_HASH ou DB_RECNO. L'argument openinfo est un pointeur vers une structure spcifique la mthode d'accs dcrite dans la page de manuel de cette mthode d'accs. Si openinfo est NULL, chaque mthode d'accs utilisera un comportement par dfaut appropri pour le systme et le type de base de donnes. Dbopen renvoie un pointeur sur une structure DB s'il russit, ou NULL en cas d'erreur. La structure DB est dfinie dans le fichier d'en- tte <db.h> et contient, au moins, les champs suivants : typedef struct { DBTYPE type; int (*close(2,7,n))(const DB *db); int (*del)(const DB *db, const DBT *cl, u_int flags); int (*fd)(const DB *db); int (*get)(const DB *db, DBT *cl, DBT *data, u_int flags); int (*put)(const DB *db, DBT *cl, const DBT *data, u_int flags); int (*sync(1,2,8))(const DB *db, u_int flags); int (*seq)(const DB *db, DBT *cl, DBT *data, u_int flags); } DB; Ces lments dcrivent un type de base de donnes et un jeu de fonctions effectuant diverses actions. Ces fonctions reoivent un pointeur sur une structure semblable celle renvoye par dbopen, et parfois un ou plusieurs pointeurs sur des structures cls/donnes et une valeur d'attribut. type Le type de mthode d'accs sous-jacente (et le type de fichier). close(2,7,n) Un pointeur sur une routine qui vide vers le disque toutes les informations en cache, libre les ressources alloues, et ferme le(s) fichier(s) de support. Comme les paires cls/donnes peuvent tre caches en mmoire, l'oubli de synchronisation du fichier avec les fonctions close(2,7,n) ou sync(1,2,8) peut rsulter dans des donnes incohrentes ou perdues. La rou- tine close(2,7,n) renvoie -1 en cas d'erreur (et remplit errno) et 0 si elle russit. del Un pointeur vers une routine permettant de supprimer des paires cls/donnes de la base de donnes. Le paramtre flag peut prendre l'une des valeurs suivantes: R_CURSOR Supprimer l'enregistrement rfrenc par le curseur. Ce curseur doit bien entendu avoir t prcdemment positionn. La routine delete renvoie 0 si elle russit, -1 en cas d'erreur (et remplit errno), ou 1 si la cl indique n'a pas t trouve dans le fichier. fd Un pointeur vers une routine qui renvoie le descripteur du fichier reprsentant la base de donnes. Le mme descripteur de fichier doit tre fourni tous les processus qui invoquent dbopen avec le mme nom de fichier. Ce descripteur de fichier doit pouvoir servir d'argument aux fonctions de verrouillage fcntl(2) et flock(1,2)(2). Le descripteur de fichier n'est pas ncessairement associ avec l'un des fichiers sous-jacents utiliss par les mthodes d'accs. Aucun descripteur n'est disponible pour les base de donnes en mmoire. La routine fd renvoie -1 en cas d'erreur (et remplit errno), ou le descripteur de fichiers en cas de succs. get Un pointeur vers la routine d'interface de recherche assiste d'une cl dans la base de donnes. L'adresse et la longueur des donnes associes avec la cl indique sont fournies dans une structure rfrence par l'argument data. La rou- tine get renvoie -1 en cas d'erreur (et remplit errno), 0 en cas de russite, ou 1 si la cl n'a pas t trouve dans le fichier. put Un pointeur vers une routine permettant de stocker les paires cls/donnes dans la base de donnes. Le paramtre flag peut prendre l'une des valeurs suivantes : R_CURSOR Remplacer la paire cl/donne rfrence par le curseur. Ce curseur doit avoir t positionn prcdemment. R_IAFTER Ajouter les donnes immdiatement aprs les donnes rfrences par la cl, crant ainsi une nouvelle paire cl/donne. Le numro d'enregistrement de la paire ajoute est renvoy dans la structure cl. (Utilisable uniquement avec la mthode d'accs DB_RECNO) R_IBEFORE Ajouter les donnes immdiatement avant les donnes rfrences par la cl, crant ainsi une nouvelle paire cl/donne. Le numro d'enregistrement de la paire insre est renvoy dans la structure cl. (Utilisable uniquement avec la mthode d'accs DB_RECNO) R_NOOVERWRITE N'ajouter la paire cl/donne que si la cl n'existe pas prcdement. R_SETCURSOR Enregistrer la paire cl/donne, en positionnant ou initialisant la position du curseur pour la rfrencer. (Utilisable uniquement avec les mthodes d'accs DB_RECNO et DB_TREE) R_SETCURSOR n'est disponible que pour les mthodes DB_BTREE et DB_RECNO car cela implique que les cls ont un ordre inhrent immuable. R_IAFTER et R_IBEFORE ne sont disponibles qu'avec la mthode DB_RECNO car ils impliquent que la mthode d'accs soit capa- ble de crer de nouvelles cls. Ceci n'est vrai que si les cls sont ordonnes et indpendantes, comme des numros d'enregistrement. Le comportement par dfaut de la routine put est de stocker une nouvelle paire cl/donne, en remplaant toute cl existant prcdemment. Les routines put renvoient -1 en cas d'erreur (et remplissent errno), 0 en cas de succs, ou 1 si l'attribut R_NOOVERWRITE a t indiqu dans flag, et si la cl existait dj dans le fichier. seq Un pointeur vers la routine d'interface pour la recherche squentielle dans la base de donnes. L'adresse et la longueur de la cl sont renvoyes dans une structure rfrence par cl, et l'adresse et la longueur des donnes dans une struc- ture rfrence par data. La rechercher squentielle de paire cl/donne peut avoir lieu tout moment, et la position du ``curseur'' n'est pas affecte par les routine del, get, put, ou sync(1,2,8). Les modifica- tions de la base de donnes durant un balayage squentiel seront visibles par le balayage, c'est dire que les enreg- istrements insrs avant le curseur ne seront pas vus, mais les enregistrements insrs aprs le curseur seront ren- voys. La valeur de flag doit tre l'une des valeurs suivantes : R_CURSOR La routine renvoie les donnes associes avec la cl indique. Ceci est diffrent du comportement de la rou- tine get car le curseur est galement positionn ou initialis. (Notez que pour la mthode d'accs DB_BTRE, la cl renvoye ne correspond pas ncessaire- ment la cl indique. On retourne la plus petite cl suprieure ou gale celle indique, ce qui permet des correspondances partielles ou des recherches d'intervalles). R_FIRST On renvoie la premire paire cl/donne de la base, et le curseur est initialis ou positionn pour la rfrencer. R_LAST On renvoie la dernire paire cl/donne de la base, et le curseur est initialis ou positionn pour la rfrencer. (Disponible uniquement pour les mthodes DB_TREE et DB_RECNO). R_NEXT Renvoyer la paire cl/donne immdiatement aprs le curseur. Si le curseur n'est pas positionn, le com- portement est le mme que R_FIRST. R_PREV Renvoyer la paire cl/donne immdiatement avant le curseur. Si le curseur n'est pas positionn, le com- portement est le mme que R_LAST. (Disponible unique- ment pour les mthodes DB_TREE et DB_RECNO). R_LAST et R_PREV ne sont disponibles que pour les mthodes DB_BTREE et DB_RECNO car ils impliquent que les cls aient un ordre inhrent immuable. La routine seq renvoie -1 en cas d'erreur (et remplit errno), 0 en cas de succs, et 1 s'il n'y a pas de paire cl/donne suprieure ou gale la cl indique ou courante. Si on tuilise la mthode DB_RECNO, si le fichier de base de donnes est un fichier spcial en mode caractres, et si aucune paire cl/donne complte n'est actuellement disponible, la routine seq renvoie 2. sync(1,2,8) Un pointeur vers une routine permettant de vider sur disque toutes les informations en cache. Si la base de donnes est uniquement en mmoire, la routine sync(1,2,8) n'a pas d'effet, et russira toujours. La valeur de flag peut tre la suivante : R_RECNOSYNC Si on utilise la mthode DB_RECNO, cet attribut oblige la synchronisation s'appliquer au fichier B-Tree sous- jacent au fichier RecNo, et non pas ce dernier. (voir le champs bfname de la page de manuel recno(3) pour plus d'informations.) La routine sync(1,2,8) renvoie -1 en cas d'erreur (et remplit errno) ou 0 en cas de russite. PAIRES CLS/DONNES L'accs tous les types de fichiers est bas sur les paires cls/donnes. La structure de donne suivante reprsente la fois les cls et les donnes. typedef struct { void *data; size_t size; } DBT; Les lments de la structure DBT sont dfinis ainsi : data Un pointeur vers une chane d'octets. size La longueur de la chane d'octets Les chanes d'octets des cls et des donnes peuvent avoir n'importe quelle longueur, avec la limitation que deux quelconques d'entre-elles doivent pouvoir tenir simultanment en mmoire. Remarquez que les mthodes d'accs ne fournissent aucune garantie en ce qui concerne les alignements des chanes d'octets. ERREURS La routine dbopen peut chouer et placer dans errno n'importe laquelle des erreurs renvoyes par les routines open(2,3,n)(2) et malloc(3) ou l'une des erreurs suivantes : [EFTYPE] Un fichier est mal formatt. [EINVAL] Un paramtre indiqu (par exemple fonction de hachage) est incompatible avec les spcifications du fichier actuel, ou n'a pas de sens pour la fonction (par exemple utiliser le curseur sans initialisation pralable). Ou encore, il y a une incompat- ibilit dans les numros de version(1,3,5) du fichier et du logiciel. Les routines close(2,7,n) peuvent chouer et fournir dans errno l'une quel- conque des erreurs indiques par les routines de bibliothque close(2,7,n)(2), read(2,n,1 builtins)(2), write(1,2)(2), free(3), ou fsync(2). Les routines del, get, put et seq peuvent chouer et fournir dans errno l'une quelconque des erreurs indiques par les routines de bib- liothque read(2,n,1 builtins)(2), write(1,2)(2), free(3) ou malloc(3). Les routine fd peuvent chouer et remplir errno avec l'erreur ENOENT pour les bases de donnes en mmoire. Les routines sync(1,2,8) peuvent chouer et fournir dans errno l'une quel- conque des erreurs indiques par la routine de bibliothque fsync(2). VOIR AUSSI btree(3), hash(3), mpool(3), recno(3) LIBTP: Portable, Modular Transactions for UNIX, Margo Seltzer, Michael Olson, USENIX proceedings, Winter 1992. BOGUES Le typedef DBT est un mnmonique pour ``data base thang'', qui a t choisi car personne n'arrivait trouver un nom raisonnable et pas encore utilis. L'interface avec les descripteurs de fichiers est une bidouille et sera supprime dans les versions futures de l'interface. Aucune mthode d'accs ne fournit de transactions, de verrouillages ou d'accs concurrents. TRADUCTION Christophe Blaess, 1999-2003. LDP 21 juillet 2003 DBOPEN(3)