Provided by: manpages-fr-dev_3.57d1p1-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>
       #include <fcntl.h>

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

DESCRIPTION

       NOTE:  cette  page  décrit des interfaces founies par la glibc jusque dans sa version 2.1.
       Depuis la version 2.2, la glibc ne fournit plus ces interfaces. Veuillez consulter les API
       fournies par la bibliothèque libdb.

       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.  Cela
              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. C'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. (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
              réussite.

   Paires 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.57 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

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

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

       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> ».