Loading

NOM

       dbopen - Méthodes d’accès aux bases de données

SYNOPSIS

       #include <sys/types.h>
       #include <limits.h>
       #include <db.h>
       #include <fcntl.h>

       DB *dbopen(const char *file, int flags, int mode, DBTYPE type,
                  const void *openinfo);

       dbopen()  est l’interface de bibliothèque pour les fichiers de bases de
       données. Les formats de fichiers supportés  sont  les  arbres  binaires
       (btree),  les fichiers hachés et les fichiers UNIX. L’arbre binaire est
       une représentation d’une structure équilibrée et  triée.  Les  fichiers
       hachés représentent 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 spécifiques
       aux  fichiers  sont  fournis  en  détail  dans  les  pages  de   manuel
       respectives de btree(3), hash(3) et recno(3).

       dbopen()  ouvre  le  fichier  file  en  lecture  et/ou en écriture. Les
       fichiers qui n’ont en aucun cas besoin d’être sauvegardés sur le disque
       peuvent être créés avec le paramètre file à NULL.

       Les  arguments  flags  et  mode  doivent  être  spécifiés  à 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  données  en  mode
       O_WRONLY n’est pas possible).

       L’argument  type  est  du type DBTYPE (défini dans le fichier d’en-tête
       <db.h>) et peut prendre les valeurs DB_BTREE, DB_HASH ou DB_RECNO.

       L’argument openinfo est un pointeur vers une structure spécifique à  la
       méthode  d’accès  décrite  dans  la  page  de  manuel  de cette méthode
       d’accès. Si openinfo est NULL,  chaque  méthode  d’accès  utilisera  un
       comportement par défaut approprié pour le système et le type de base de
       données.

       dbopen() renvoie un pointeur sur une structure DB si elle  réussit,  ou
       NULL  en  cas  d’erreur.  La  structure  DB est définie dans le fichier
       d’en-tête <db.h> 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 éléments décrivent un  type  de  base  de  données  et  un  jeu  de
       fonctions  effectuant  diverses  actions.  Ces  fonctions  reçoivent un
       pointeur sur une structure semblable à celle renvoyée par dbopen(),  et
       parfois  un  ou  plusieurs pointeurs sur des structures clés/données et
       une valeur d’attribut.

       type   Le type de méthode d’accès sous-jacent (et le type de  fichier).

       close  Un  pointeur  sur une routine qui vide vers le disque toutes les
              informations en cache, libère les ressources allouées, et  ferme
              le(s)  fichier(s).  Comme  les  paires clés/données peuvent être
              cachées en mémoire, l’oubli de synchronisation du  fichier  avec
              les  fonctions  close() ou sync() peut résulter dans des données
              incohérentes ou perdues. La routine close() renvoie  -1  en  cas
              d’erreur (et remplit errno)  et 0 si elle réussit.

       del    Un  pointeur vers une routine permettant de supprimer des paires
              clés/données de la base de données.

              Le paramètre flag peut prendre l’une des valeurs suivantes :

              R_CURSOR
                     Supprimer l’enregistrement référencé par le  curseur.  Ce
                     curseur   doit   bien   entendu  avoir  été  précédemment
                     initialisé.

              La routine delete()  renvoie  0  si  elle  réussit,  -1  en  cas
              d’erreur (et définit errno), ou 1 si la clé key indiquée n’a pas
              été trouvée dans le fichier.

       fd     Un pointeur vers une  routine  qui  renvoie  le  descripteur  du
              fichier  représentant la base de données. Le même descripteur de
              fichier doit être fourni à  tous  les  processus  qui  invoquent
              dbopen()  avec  le même 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 nécessairement
              associé avec l’un des fichiers  sous-jacents  utilisés  par  les
              méthodes  d’accès.  Aucun  descripteur n’est disponible pour les
              base de données en mémoire. La routine  fd  renvoie  -1  en  cas
              d’erreur  (et  définit  errno), et le descripteur de fichiers en
              cas de succès.

       get    Un pointeur vers la routine d’interface  de  recherche  assistée
              d’une  clé dans la base de données. L’adresse et la longueur des
              données associées avec la clé key indiquée  sont  fournies  dans
              une  structure  référencée par l’argument data. La routine get()
              renvoie -1 en cas d’erreur (et  remplit  errno),  0  en  cas  de
              réussite,  ou  1  si  la  clé  key  n’a  pas été trouvée dans le
              fichier.

       put    Un pointeur vers une routine permettant de  stocker  les  paires
              clés/données dans la base de données.

              Le paramètre flag peut prendre l’une des valeurs suivantes :

              R_CURSOR
                     Remplacer  la paire clé/donnée référencée par le curseur.
                     Ce curseur doit avoir été positionné précédemment.

              R_IAFTER
                     Ajouter  les  données  immédiatement  après  les  données
                     référencées  par  la  clé  key, créant ainsi une nouvelle
                     paire clé/donnée. Le numéro d’enregistrement de la  paire
                     ajoutée  est  renvoyé  dans  la structure key (utilisable
                     uniquement avec la méthode d’accès DB_RECNO).

              R_IBEFORE
                     Ajouter  les  données  immédiatement  avant  les  données
                     référencées  par  key,  créant  ainsi  une nouvelle paire
                     clé/donnée.  Le  numéro  d’enregistrement  de  la   paire
                     insérée  est  renvoyé  dans  la structure key (utilisable
                     uniquement avec la méthode d’accès DB_RECNO).

              R_NOOVERWRITE
                     N’ajouter la paire clé/donnée que si la clé n’existe  pas
                     précédemment.

              R_SETCURSOR
                     Enregistrer  la  paire  clé/donnée,  en  positionnant  ou
                     initialisant la position du curseur  pour  la  référencer
                     (utilisable uniquement avec les méthodes d’accès DB_RECNO
                     et DB_TREE).

              R_SETCURSOR n’est disponible que pour les méthodes  DB_BTREE  et
              DB_RECNO  car  cela  implique que les clés ont un ordre inhérent
              immuable.

              R_IAFTER et R_IBEFORE ne sont  disponibles  qu’avec  la  méthode
              DB_RECNO  car ils impliquent que la méthode d’accès soit capable
              de créer de nouvelles clés. Ceci n’est vrai que si les clés sont
              ordonnées  et indépendantes, comme des numéros d’enregistrement.

              Le comportement par défaut de la routine put est de stocker  une
              nouvelle  paire  clé/donnée,  en  remplaçant  toute clé existant
              précédemment.

              Les routines put() renvoient -1 en cas d’erreur (et  remplissent
              errno),  0  en cas de succès, ou 1 si l’attribut R_NOOVERWRITE a
              été indiqué dans flag, et  si  la  clé  existait  déjà  dans  le
              fichier.

       seq    Un  pointeur  vers  la  routine  d’interface  pour  la recherche
              séquentielle dans la base de données. L’adresse et  la  longueur
              de  la clé sont renvoyées dans une structure référencée par key,
              et l’adresse et la  longueur  des  données  dans  une  structure
              référencée par data.

              La rechercher séquentielle de paire clé/donnée peut avoir lieu à
              tout moment, et la position du « curseur »  n’est  pas  affectée
              par   les   routine   del(),   get(),   put(),  ou  sync().  Les
              modifications  de  la  base  de  données  durant   un   balayage
              séquentiel seront visibles par le balayage, c’est-à-dire que les
              enregistrements insérés avant le curseur ne seront pas vus, mais
              les enregistrements insérés après le curseur seront renvoyés.

              La valeur de flags doit être l’une des valeurs suivantes :

              R_CURSOR
                     La  routine  renvoie  les  données  associées avec la clé
                     indiquée.  Ceci  est  différent  du  comportement  de  la
                     routine  get() car le curseur est également positionné ou
                     initialisé. (Veuillez noter que pour la  méthode  d’accès
                     DB_BTREE,    la    clé   renvoyée   ne   correspond   pas
                     nécessairement à la clé indiquée.  On  retourne  la  plus
                     petite  clé  supérieure ou égale à celle indiquée, ce qui
                     permet des correspondances partielles ou  des  recherches
                     d’intervalles).

              R_FIRST
                     On renvoie la première paire clé/donnée de la base, et le
                     curseur est initialisé ou positionné pour la  référencer.

              R_LAST On renvoie la dernière paire clé/donnée de la base, et le
                     curseur est initialisé ou positionné pour la  référencer.
                     (Disponible  uniquement  pour  les  méthodes  DB_BTREE et
                     DB_RECNO).

              R_NEXT Renvoyer  la  paire  clé/donnée  immédiatement  après  le
                     curseur.   Si   le   curseur  n’est  pas  positionné,  le
                     comportement est le même que R_FIRST.

              R_PREV Renvoyer  la  paire  clé/donnée  immédiatement  avant  le
                     curseur.   Si   le   curseur  n’est  pas  positionné,  le
                     comportement  est  le  même   que   R_LAST.   (Disponible
                     uniquement pour les méthodes DB_BTREE et DB_RECNO).

              R_LAST  et  R_PREV  ne  sont  disponibles  que pour les méthodes
              DB_BTREE et DB_RECNO car ils impliquent que les  clés  aient  un
              ordre inhérent immuable.

              La  routine seq() renvoie -1 en cas d’erreur (et remplit errno),
              0 en cas de succès, et 1 s’il n’y  a  pas  de  paire  clé/donnée
              supérieure ou égale à la clé indiquée ou courante. Si on utilise
              la méthode DB_RECNO, si le fichier de base  de  données  est  un
              fichier   spécial   en  mode  caractères,  et  si  aucune  paire
              clé/donnée complète 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  données  est
              uniquement  en  mémoire,  la  routine sync() n’a pas d’effet, et
              réussira toujours.

              La valeur de flags peut être la suivante :

              R_RECNOSYNC
                     Si on utilise la méthode DB_RECNO, ce drapeau  oblige  la
                     synchronisation    à   s’appliquer   au   fichier   btree
                     sous-jacent du fichier recno, et non pas  à  ce  dernier.
                     (Voyez 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 réussite.

   Paire clé/données
       L’accès  à  tous  les  types  de  fichiers  est  basé  sur  les  paires
       clés/données. La structure de donnée suivante représente à la fois  les
       clés et les données.

           typedef struct {
               void  *data;
               size_t size;
           } DBT;

       Les éléments de la structure DBT sont définis ainsi :

       data   Un pointeur vers une chaîne d’octets.

       size   La longueur de la chaîne d’octets.

       Les  chaînes  d’octets  des clés et des données peuvent avoir n’importe
       quelle longueur, avec la limitation que deux quelconques d’entre  elles
       doivent  pouvoir  tenir  simultanément  en  mémoire.  Remarquez que les
       méthodes d’accès ne fournissent aucune garantie en ce qui concerne  les
       alignements des chaînes d’octets.

ERREURS

       La  routine  dbopen()  peut  échouer  et  placer  dans  errno n’importe
       laquelle des erreurs renvoyées par les routines open(2) et malloc(3) ou
       l’une des erreurs suivantes :

       EFTYPE Un fichier est mal formaté.

       EINVAL Un  paramètre  indiqué  (par  exemple  fonction  de hachage) est
              incompatible avec les spécifications du fichier actuel,  ou  n’a
              pas  de  sens  pour la fonction (par exemple utiliser le curseur
              sans  initialisation  préalable).  Ou  encore,  il   y   a   une
              incompatibilité  dans  les  numéros  de version du fichier et du
              logiciel.

       Les routines close() peuvent échouer et définir dans  errno  l’une  des
       erreurs  spécifiées par les routines de bibliothèque close(2), read(2),
       write(2), free(3), ou fsync(2).

       Les routines del, get, put et seq peuvent échouer et définir dans errno
       l’une  des erreurs spécifiées par les routines de bibliothèque read(2),
       write(2), free(3) ou malloc(3).

       Les routine fd peuvent échouer et définir errno à ENOENT pour les bases
       de données en mémoire.

       Les  routines  sync  peuvent  échouer  et  définir dans errno l’une des
       erreurs spécifiées par la routine de bibliothèque fsync(2).

BOGUES

       Le typedef DBT est un mnémonique 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 fichier est une bidouille et  sera
       supprimée dans les versions futures de l’interface.

       Aucune  méthode d’accès ne fournit de transactions, de verrouillages ou
       d’accès 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.

COLOPHON

       Cette  page  fait  partie  de  la  publication 3.23 du projet man-pages
       Linux. Une description du projet et des instructions pour signaler  des
       anomalies       peuvent       être       trouvées      à      l’adresse
       http://www.kernel.org/doc/man-pages/.

TRADUCTION

       Cette page de manuel a été traduite  et  mise  à  jour  par  Christophe
       Blaess  <http://www.blaess.fr/christophe/> entre 1996 et 2003, puis par
       Alain Portal <aportal AT univ-montp2 DOT fr> jusqu’en 2006, et  mise  à
       disposition sur http://manpagesfr.free.fr/.

       Les mises à jour et corrections de la version présente dans Debian sont
       directement gérées par Florentin Duneau <fduneau@gmail.com> et l’équipe
       francophone de traduction de Debian.

       Veuillez   signaler   toute   erreur   de   traduction  en  écrivant  à
       <debian-l10n-french@lists.debian.org> ou par un rapport de bogue sur le
       paquet manpages-fr.

       Vous  pouvez  toujours avoir accès à la version anglaise de ce document
       en utilisant la commande « man -L C <section> <page_de_man> ».