DBOPEN(3) Manuel du programmeur Linux DBOPEN(3)
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 fichier 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 pour y lire et/ou écrire. 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 pos
sible.)
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 {
Linux 06 Mai 1999 1
DBOPEN(3) Manuel du programmeur Linux DBOPEN(3)
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 fonc
tions 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 sup
primer 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 fonc
tions de verrouillage fcntl(2) et flock(2). Le
Linux 06 Mai 1999 2
DBOPEN(3) Manuel du programmeur Linux DBOPEN(3)
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 descrip
teur 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é posi
tionné 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 posi
tionnant 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)
Linux 06 Mai 1999 3
DBOPEN(3) Manuel du programmeur Linux DBOPEN(3)
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 rem
plaç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 visi
bles par le balayage, c'est à dire que les enreg
istrements 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 suiv
antes :
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 ini
tialisé. (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).
Linux 06 Mai 1999 4
DBOPEN(3) Manuel du programmeur Linux DBOPEN(3)
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 rem
plit 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 rou
tine 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 rem
plit errno) ou 0 en cas de réussite.
Linux 06 Mai 1999 5
DBOPEN(3) Manuel du programmeur Linux DBOPEN(3)
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 simul
tané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 fonc
tion (par exemple utiliser le curseur sans initial
isation préalable). Ou encore, il y a une incompat
ibilité 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
Linux 06 Mai 1999 6
DBOPEN(3) Manuel du programmeur Linux DBOPEN(3)
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.
BUGS
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 fournir de transactions, de ver
rouillages ou d'accès concurrents.
TRADUCTION
Christophe Blaess, 1999.
Linux 06 Mai 1999 7