Provided by: manpages-fr-dev_3.65d1p1-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>
#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 par la glibc jusque dans sa version 2.1.
Depuis la version 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 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 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 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 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 base 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.
COLOPHON
Cette page fait partie de la publication 3.65 du projet man-pages Linux. Une description
du projet et des instructions pour signaler des anomalies peuvent être trouvées à
l'adresse http://www.kernel.org/doc/man-pages/.
TRADUCTION
Depuis 2010, cette traduction est maintenue à l'aide de l'outil po4a
<http://po4a.alioth.debian.org/> par l'équipe de traduction francophone au sein du projet
perkamon <http://perkamon.alioth.debian.org/>.
Christophe Blaess <http://www.blaess.fr/christophe/> (1996-2003), Alain Portal
<http://manpagesfr.free.fr/> (2003-2006). Florentin Duneau et l'équipe francophone de
traduction de Debian (2006-2009).
Veuillez signaler toute erreur de traduction en écrivant à
<debian-l10n-french@lists.debian.org> ou par un rapport de bogue sur le paquet
manpages-fr.
Vous pouvez toujours avoir accès à la version anglaise de ce document en utilisant la
commande « man -L C <section> <page_de_man> ».