Provided by: manpages-fr_1.67.0-1_all bug

NOM

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

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 bibliothèque pour les fichiers de bases de
       données.  Les formats de fichiers supportés sont les  arbres  binaires,
       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 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 sauvegardés sur  disque  peuvent  être
       créés avec le paramètre de fichier à NULL.

       Les  arguments  attribut et mode doivent être spécifiés pour 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.  (Notez
       que l’ouverture d’un fichier de base de données en mode O_WRONLY  n’est
       pas possible.)

       Le  type_base  est  un  argument  ayant  le 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 s’il 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 *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)(const DB *db, u_int flags);
              int (*seq)(const DB *db, DBT *clé, DBT *data, u_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-jacente (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) de  support.   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
                     positionné.

              La  routine delete renvoie 0 si elle réussit, -1 en cas d’erreur
              (et remplit errno), ou 1 si la cl 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 de fichier.  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 remplit errno), ou 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 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 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, créant ainsi une nouvelle paire
                     clé/donnée.   Le  numéro  d’enregistrement  de  la  paire
                     ajoutée  est  renvoyé dans la structure cl.  (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  la cl, 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 cl.  (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édement.

              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 cl,
              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 flag 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é.  (Notez que pour la méthode d’accès  DB_BTRE,
                     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_TREE  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_TREE 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 tuilise
              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 flag peut être la suivante :

              R_RECNOSYNC
                     Si on utilise la méthode 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 renvoie -1 en cas d’erreur (et remplit errno) ou
              0 en cas de réussite.

PAIRES CLÉS/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 formatté.

       [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  fournir  dans  errno  l’une
       quelconque des erreurs  indiqué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 fournir dans errno
       l’une quelconque des erreurs indiquées par les routines de bibliothèque
       read(2), write(2), free(3) ou malloc(3).

       Les  routine  fd  peuvent échouer et remplir errno avec l’erreur ENOENT
       pour les bases de données en mémoire.

       Les  routines  sync  peuvent  échouer  et  fournir  dans  errno   l’une
       quelconque  des  erreurs  indiquées  par  la  routine  de  bibliothèque
       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 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 fichiers 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.

TRADUCTION

       Christophe Blaess, 1999-2003.