Seth Woolley's Man Viewer

dbopen(3) - dbopen, dbopen - Méthodes d'accès aux bases de données - man 3 dbopen

([section] manual, -k keyword, -K [section] search, -f whatis)
man plain no title

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)

References for this manual (incoming links)