dbopen(3) Library Functions Manual dbopen(3)
NOM
dbopen - Méthodes d'accès aux bases de données
BIBLIOTHÈQUE
Bibliothèque C standard (libc, -lc)
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 jusqu'à la glibc 2.1.
Depuis la glibc 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 bi-
naires (btree), les fichiers hachés et les fichiers UNIX. L'arbre bi-
naire est une représentation d'une structure équilibrée et triée. Les
fichiers hachés représentent des tables de hachage extensibles et dyna-
miques. Le format de fichier UNIX est un flux d'octets avec des enre-
gistrements de longueur fixe ou variable. Les formats et les informa-
tions 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 fi-
chiers 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'ac-
cès. Si openinfo est NULL, chaque méthode d'accès utilisera un compor-
tement par défaut approprié pour le système et le type de base de don-
né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 fonc-
tions 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 ca-
chées en mémoire, l'oubli de synchronisation du fichier avec les
fonctions close() ou sync() peut avoir pour conséquence des don-
né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 initia-
lisé.
La routine delete() renvoie 0 si elle réussit, -1 en cas d'er-
reur (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 fi-
chier représentant la base de données. Le même descripteur de
fichier doit être fourni à tous les processus qui invoquent dbo-
pen() avec le même nom file. Ce descripteur de fichier doit pou-
voir servir d'argument aux fonctions de verrouillage fcntl(2) et
flock(2). Le descripteur de fichier n'est pas nécessairement as-
socié 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éus-
site, 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 ajou-
tée est renvoyé dans la structure key (utilisable unique-
ment 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é/don-
né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 ini-
tialisant la position du curseur pour la référencer (uti-
lisable 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 fi-
chier.
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éren-
cé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 modifica-
tions 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 enregistre-
ments 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é in-
diquée. C'est différent du comportement de la routine
get() car le curseur est également positionné ou initia-
lisé. (Veuillez noter que pour la méthode d'accès
DB_BTREE, la clé renvoyée ne correspond pas nécessaire-
ment à 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'inter-
valles).
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 cur-
seur. 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 cur-
seur. 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 su-
pé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 fi-
chier spécial en mode caractères, et si aucune paire clé/donnée
complète n'est actuellement disponible, la routine seq ren-
voie 2.
sync Un pointeur vers une routine permettant de vider sur disque
toutes les informations en cache. Si la base de données est uni-
quement en mémoire, la routine sync() n'a pas d'effet et réus-
sira 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-ja-
cent du fichier recno, et non pas à ce dernier. (Consul-
tez 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/don-
né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 la-
quelle 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 in-
compatible 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 er-
reurs 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 en-
core 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
La traduction française de cette page de manuel a été créée par Chris-
tophe Blaess <https://www.blaess.fr/christophe/>, Stéphan Rafin <ste-
phan.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.cou-
lon@wanadoo.fr>, Julien Cristau <jcristau@debian.org>, Thomas Huriaux
<thomas.huriaux@gmail.com>, Nicolas François <nicolas.francois@centra-
liens.net>, Florentin Duneau <fduneau@gmail.com>, Simon Paillard <si-
mon.paillard@resel.enst-bretagne.fr>, Denis Barbier <barbier@de-
bian.org> et David Prévot <david@tilapin.org>
Cette traduction est une documentation libre ; veuillez vous reporter à
la GNU General Public License version 3
⟨https://www.gnu.org/licenses/gpl-3.0.html⟩ 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 4 décembre 2022 dbopen(3)
Generated by dwww version 1.15 on Sat Jun 29 00:26:31 CEST 2024.