Provided by:
manpages-fr_1.67.0-1_all 
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.