DBOPEN
Section : Manuel du programmeur Linux (
3)
Mise à jour de la version anglaise : 2 janvier 1994
Index
Menu principal
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 (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
en lecture et/ou en é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 à 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 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'entê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'entê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é,
unsigned int flags);
int (*fd)(const DB *db);
int (*get)(const DB *db, DBT *clé, DBT *data,
unsigned int flags);
int (*put)(const DB *db, DBT *clé, const DBT *data,
unsigned int flags);
int (*sync)(const DB *db, unsigned int flags);
int (*seq)(const DB *db, DBT *clé, 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-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) sous-jacent(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 renseigne
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 bases de données en mémoire.
La routine
fd
renvoie -1 en cas d'erreur (et renseigne
errno),
ou le descripteur de fichier 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é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.
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 routines
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é.
(Veuillez noter 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 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
attributs
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 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és/données
L'accès à tous les types de fichiers est basé
sur les paires clés/données.
La structure de données 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 fournir dans
errno
l'une 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 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 des erreurs indiqué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.
TRADUCTION
Ce document est une traduction réalisée par Christophe Blaess
<http://www.blaess.fr/christophe/> le 6 mai 1999
et révisée le 17 juillet 2008.
L'équipe de traduction a fait le maximum pour réaliser une adaptation
française de qualité. La version anglaise la plus à jour de ce document est
toujours consultable via la commande : « LANG=C man 3 dbopen ».
N'hésitez pas à signaler à l'auteur ou au traducteur, selon le cas, toute
erreur dans cette page de manuel.
Index
- NOM
-
- SYNOPSIS
-
- DESCRIPTION
-
- Paires clés/données
-
- ERREURS
-
- BOGUES
-
- VOIR AUSSI
-
- TRADUCTION
-
Dernière mise à jour : 17 juillet 2008