dbopen
Section: C Library Functions (3)
Updated: 4 décembre 2022
Index
Return to Main Contents
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 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.
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 à
Index
- NOM
-
- BIBLIOTHÈQUE
-
- SYNOPSIS
-
- DESCRIPTION
-
- Paires clé/données
-
- ERREURS
-
- BOGUES
-
- VOIR AUSSI
-
- TRADUCTION
-
This document was created by
man2html,
using the manual pages.
Time: 06:03:17 GMT, May 18, 2024