Provided by:
manpages-fr-dev_3.27fr1.4-1_all 
NOM
dbopen - Methodes d'acces aux bases de donnees
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
dbopen() est l'interface de bibliotheque pour les fichiers de bases de
donnees. Les formats de fichiers supportes sont les arbres binaires
(btree), les fichiers haches et les fichiers UNIX. L'arbre binaire est
une representation d'une structure equilibree et triee. Les fichiers
haches representent 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 specifiques
aux fichiers sont fournis en detail dans les pages de manuel
respectives de btree(3), hash(3) et recno(3).
dbopen() ouvre le fichier file en lecture et/ou en ecriture. Les
fichiers qui n'ont en aucun cas besoin d'etre sauvegardes sur le disque
peuvent etre crees avec le parametre file a NULL.
Les arguments flags et mode doivent etre specifies a 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 donnees en mode
O_WRONLY n'est pas possible).
L'argument type est du type DBTYPE (defini dans le fichier d'en-tete
<db.h>) et peut prendre les valeurs DB_BTREE, DB_HASH ou DB_RECNO.
L'argument openinfo est un pointeur vers une structure specifique a la
methode d'acces decrite dans la page de manuel de cette methode
d'acces. Si openinfo est NULL, chaque methode d'acces utilisera un
comportement par defaut approprie pour le systeme et le type de base de
donnees.
dbopen() renvoie un pointeur sur une structure DB si elle reussit, ou
NULL en cas d'erreur. La structure DB est definie dans le fichier
d'en-tete <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 elements decrivent un type de base de donnees et un jeu de
fonctions effectuant diverses actions. Ces fonctions recoivent un
pointeur sur une structure semblable a celle renvoyee par dbopen(), et
parfois un ou plusieurs pointeurs sur des structures cles/donnees et
une valeur d'attribut.
type Le type de methode d'acces sous-jacent (et le type de fichier).
close Un pointeur sur une routine qui vide vers le disque toutes les
informations en cache, libere les ressources allouees, et ferme
le(s) fichier(s). Comme les paires cles/donnees peuvent etre
cachees en memoire, l'oubli de synchronisation du fichier avec
les fonctions close() ou sync() peut resulter dans des donnees
incoherentes ou perdues. La routine close() renvoie -1 en cas
d'erreur (et remplit errno) et 0 si elle reussit.
del Un pointeur vers une routine permettant de supprimer des paires
cles/donnees de la base de donnees.
Le parametre flag peut prendre l'une des valeurs suivantes :
R_CURSOR
Supprimer l'enregistrement reference par le curseur. Ce
curseur doit bien entendu avoir ete precedemment
initialise.
La routine delete() renvoie 0 si elle reussit, -1 en cas
d'erreur (et definit errno), ou 1 si la cle key indiquee n'a pas
ete trouvee dans le fichier.
fd Un pointeur vers une routine qui renvoie le descripteur du
fichier representant la base de donnees. Le meme descripteur de
fichier doit etre fourni a tous les processus qui invoquent
dbopen() avec le meme 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 necessairement
associe avec l'un des fichiers sous-jacents utilises par les
methodes d'acces. Aucun descripteur n'est disponible pour les
base de donnees en memoire. La routine fd renvoie -1 en cas
d'erreur (et definit errno), et le descripteur de fichiers en
cas de succes.
get Un pointeur vers la routine d'interface de recherche assistee
d'une cle dans la base de donnees. L'adresse et la longueur des
donnees associees avec la cle key indiquee sont fournies dans
une structure referencee par l'argument data. La routine get()
renvoie -1 en cas d'erreur (et remplit errno), 0 en cas de
reussite, ou 1 si la cle key n'a pas ete trouvee dans le
fichier.
put Un pointeur vers une routine permettant de stocker les paires
cles/donnees dans la base de donnees.
Le parametre flag peut prendre l'une des valeurs suivantes :
R_CURSOR
Remplacer la paire cle/donnee referencee par le curseur.
Ce curseur doit avoir ete positionne precedemment.
R_IAFTER
Ajouter les donnees immediatement apres les donnees
referencees par la cle key, creant ainsi une nouvelle
paire cle/donnee. Le numero d'enregistrement de la paire
ajoutee est renvoye dans la structure key (utilisable
uniquement avec la methode d'acces DB_RECNO).
R_IBEFORE
Ajouter les donnees immediatement avant les donnees
referencees par key, creant ainsi une nouvelle paire
cle/donnee. Le numero d'enregistrement de la paire
inseree est renvoye dans la structure key (utilisable
uniquement avec la methode d'acces DB_RECNO).
R_NOOVERWRITE
N'ajouter la paire cle/donnee que si la cle n'existe pas
precedemment.
R_SETCURSOR
Enregistrer la paire cle/donnee, en positionnant ou
initialisant la position du curseur pour la referencer
(utilisable uniquement avec les methodes d'acces DB_RECNO
et DB_TREE).
R_SETCURSOR n'est disponible que pour les methodes DB_BTREE et
DB_RECNO car cela implique que les cles ont un ordre inherent
immuable.
R_IAFTER et R_IBEFORE ne sont disponibles qu'avec la methode
DB_RECNO car ils impliquent que la methode d'acces soit capable
de creer de nouvelles cles. Ceci n'est vrai que si les cles sont
ordonnees et independantes, comme des numeros d'enregistrement.
Le comportement par defaut de la routine put est de stocker une
nouvelle paire cle/donnee, en remplacant toute cle existant
precedemment.
Les routines put() renvoient -1 en cas d'erreur (et remplissent
errno), 0 en cas de succes, ou 1 si l'attribut R_NOOVERWRITE a
ete indique dans flag, et si la cle existait deja dans le
fichier.
seq Un pointeur vers la routine d'interface pour la recherche
sequentielle dans la base de donnees. L'adresse et la longueur
de la cle sont renvoyees dans une structure referencee par key,
et l'adresse et la longueur des donnees dans une structure
referencee par data.
La rechercher sequentielle de paire cle/donnee peut avoir lieu a
tout moment, et la position du << curseur >> n'est pas affectee
par les routine del(), get(), put(), ou sync(). Les
modifications de la base de donnees durant un balayage
sequentiel seront visibles par le balayage, c'est-a-dire que les
enregistrements inseres avant le curseur ne seront pas vus, mais
les enregistrements inseres apres le curseur seront renvoyes.
La valeur de flags doit etre l'une des valeurs suivantes :
R_CURSOR
La routine renvoie les donnees associees avec la cle
indiquee. Ceci est different du comportement de la
routine get() car le curseur est egalement positionne ou
initialise. (Veuillez noter que pour la methode d'acces
DB_BTREE, la cle renvoyee ne correspond pas
necessairement a la cle indiquee. On retourne la plus
petite cle superieure ou egale a celle indiquee, ce qui
permet des correspondances partielles ou des recherches
d'intervalles).
R_FIRST
On renvoie la premiere paire cle/donnee de la base, et le
curseur est initialise ou positionne pour la referencer.
R_LAST On renvoie la derniere paire cle/donnee de la base, et le
curseur est initialise ou positionne pour la referencer.
(Disponible uniquement pour les methodes DB_BTREE et
DB_RECNO).
R_NEXT Renvoyer la paire cle/donnee immediatement apres le
curseur. Si le curseur n'est pas positionne, le
comportement est le meme que R_FIRST.
R_PREV Renvoyer la paire cle/donnee immediatement avant le
curseur. Si le curseur n'est pas positionne, le
comportement est le meme que R_LAST. (Disponible
uniquement pour les methodes DB_BTREE et DB_RECNO).
R_LAST et R_PREV ne sont disponibles que pour les methodes
DB_BTREE et DB_RECNO car ils impliquent que les cles aient un
ordre inherent immuable.
La routine seq() renvoie -1 en cas d'erreur (et remplit errno),
0 en cas de succes, et 1 s'il n'y a pas de paire cle/donnee
superieure ou egale a la cle indiquee ou courante. Si on utilise
la methode DB_RECNO, si le fichier de base de donnees est un
fichier special en mode caracteres, et si aucune paire
cle/donnee complete 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 donnees est
uniquement en memoire, la routine sync() n'a pas d'effet, et
reussira toujours.
La valeur de flags peut etre la suivante :
R_RECNOSYNC
Si on utilise la methode DB_RECNO, ce drapeau oblige la
synchronisation a s'appliquer au fichier btree
sous-jacent du fichier recno, et non pas a 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 reussite.
Paire cl'e/donn'ees
L'acces a tous les types de fichiers est base sur les paires
cles/donnees. La structure de donnee suivante represente a la fois les
cles et les donnees.
typedef struct {
void *data;
size_t size;
} DBT;
Les elements de la structure DBT sont definis ainsi :
data Un pointeur vers une chaine d'octets.
size La longueur de la chaine d'octets.
Les chaines d'octets des cles et des donnees peuvent avoir n'importe
quelle longueur, avec la limitation que deux quelconques d'entre elles
doivent pouvoir tenir simultanement en memoire. Remarquez que les
methodes d'acces ne fournissent aucune garantie en ce qui concerne les
alignements des chaines d'octets.
ERREURS
La routine dbopen() peut echouer et placer dans errno n'importe
laquelle des erreurs renvoyees par les routines open(2) et malloc(3) ou
l'une des erreurs suivantes :
EFTYPE Un fichier est mal formate.
EINVAL Un parametre indique (par exemple fonction de hachage) est
incompatible avec les specifications du fichier actuel, ou n'a
pas de sens pour la fonction (par exemple utiliser le curseur
sans initialisation prealable). Ou encore, il y a une
incompatibilite dans les numeros de version du fichier et du
logiciel.
Les routines close() peuvent echouer et definir dans errno l'une des
erreurs specifiees par les routines de bibliotheque close(2), read(2),
write(2), free(3), ou fsync(2).
Les routines del, get, put et seq peuvent echouer et definir dans errno
l'une des erreurs specifiees par les routines de bibliotheque read(2),
write(2), free(3) ou malloc(3).
Les routine fd peuvent echouer et definir errno a ENOENT pour les bases
de donnees en memoire.
Les routines sync peuvent echouer et definir dans errno l'une des
erreurs specifiees par la routine de bibliotheque fsync(2).
BOGUES
Le typedef DBT est un mnemonique pour << data base thang >>, qui a ete
choisi car personne n'arrivait a trouver un nom raisonnable et pas
encore utilise.
L'interface avec les descripteurs de fichier est une bidouille et sera
supprimee dans les versions futures de l'interface.
Aucune methode d'acces ne fournit de transactions, de verrouillages ou
d'acces 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.27 du projet man-pages
Linux. Une description du projet et des instructions pour signaler des
anomalies peuvent etre trouvees a l'adresse
<URL:http://www.kernel.org/doc/man-pages/>.
TRADUCTION
Depuis 2010, cette traduction est maintenue a l'aide de l'outil po4a
<URL:http://po4a.alioth.debian.org/> par l'equipe de traduction
francophone au sein du projet perkamon
<URL:http://perkamon.alioth.debian.org/>.
Christophe Blaess <URL:http://www.blaess.fr/christophe/> (1996-2003),
Alain Portal <URL:http://manpagesfr.free.fr/> (2003-2006). Florentin
Duneau et l'equipe francophone de traduction de Debian (2006-2009).
Veuillez signaler toute erreur de traduction en ecrivant a
<debian-l10n-french@lists.debian.org> ou par un rapport de bogue sur le
paquet manpages-fr.
Vous pouvez toujours avoir acces a la version anglaise de ce document
en utilisant la commande << man -L C <section> <page_de_man> >>.