Provided by: manpages-fr-dev_3.27fr1.4-1_all bug

NOM

       dbopen - Methodes d'acces aux bases de donnees

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);

DESCRIPTION

       dbopen()  est l'interface de bibliotheque pour les fichiers de bases de
       donnees. Les formats de fichiers supportes  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
       <db.h>) 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 <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 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 resulter dans  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
              base  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. Ceci 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.  Ceci  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.

   Paire cl'e/donn'ees
       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.

COLOPHON

       Cette page fait partie de  la  publication  3.27  du  projet  man-pages
       Linux.  Une description du projet et des instructions pour signaler des
       anomalies      peuvent      etre       trouvees       a       l'adresse
       <URL:http://www.kernel.org/doc/man-pages/>.

TRADUCTION

       Depuis  2010,  cette  traduction est maintenue a l'aide de l'outil po4a
       <URL:http://po4a.alioth.debian.org/>   par   l'equipe   de   traduction
       francophone        au        sein        du       projet       perkamon
       <URL:http://perkamon.alioth.debian.org/>.

       Christophe Blaess  <URL:http://www.blaess.fr/christophe/>  (1996-2003),
       Alain  Portal  <URL:http://manpagesfr.free.fr/> (2003-2006).  Florentin
       Duneau et l'equipe francophone de traduction de Debian (2006-2009).

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

       Vous pouvez toujours avoir acces a la version anglaise de  ce  document
       en utilisant la commande << man -L C <section> <page_de_man> >>.