Ubuntu Manpage: dbopen - Méthodes d'accès aux bases de données

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 fournies 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
pris en charge 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 avoir
pour conséquence 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 bases 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 5.10 du projet man-pages Linux. Une description du projet et des
       instructions  pour  signaler  des  anomalies et la dernière version de cette page peuvent être trouvées à
       l'adresse https://www.kernel.org/doc/man-pages/.

TRADUCTION

       La  traduction  française   de   cette   page   de   manuel   a   été   créée   par   Christophe   Blaess
       <https://www.blaess.fr/christophe/>,   Stéphan   Rafin   <stephan.rafin@laposte.net>,   Thierry   Vignaud
       <tvignaud@mandriva.com>, François Micaux, Alain Portal  <aportal@univ-montp2.fr>,  Jean-Philippe  Guérard
       <fevrier@tigreraye.org>,   Jean-Luc   Coulon   (f5ibh)   <jean-luc.coulon@wanadoo.fr>,   Julien   Cristau
       <jcristau@debian.org>,     Thomas     Huriaux      <thomas.huriaux@gmail.com>,      Nicolas      François
       <nicolas.francois@centraliens.net>,     Florentin     Duneau    <fduneau@gmail.com>,    Simon    Paillard
       <simon.paillard@resel.enst-bretagne.fr>,   Denis   Barbier   <barbier@debian.org>   et    David    Prévot
       <david@tilapin.org>

       Cette  traduction  est  une  documentation libre ; veuillez vous reporter à la GNU General Public License
       version 3 concernant les conditions de copie et de distribution. Il n'y a aucune RESPONSABILITÉ LÉGALE.

       Si vous découvrez un bogue dans la traduction de cette page de manuel,  veuillez  envoyer  un  message  à
       debian-l10n-french@lists.debian.org.

4.4 Berkeley Distribution                       15 septembre 2017                                      DBOPEN(3)