.\" Copyright (c) 1990, 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" %%%LICENSE_START(BSD_4_CLAUSE_UCB) .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. All advertising materials mentioning features or use of this software .\" must display the following acknowledgement: .\" This product includes software developed by the University of .\" California, Berkeley and its contributors. .\" 4. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" %%%LICENSE_END .\" .\" @(#)dbopen.3 8.5 (Berkeley) 1/2/94 .\" .\"******************************************************************* .\" .\" This file was generated with po4a. Translate the source file. .\" .\"******************************************************************* .TH DBOPEN 3 "4 mai 2012" "" "Manuel du programmeur Linux" .UC 7 .SH NOM dbopen \- Méthodes d'accès aux bases de données .SH SYNOPSIS .nf \fB#include \fP \fB#include \fP \fB#include \fP \fB#include \fP \fBDB *dbopen(const char *\fP\fIfile\fP\fB, int \fP\fIflags\fP\fB, int \fP\fImode\fP\fB, DBTYPE \fP\fItype\fP\fB,\fP \fB const void *\fP\fIopeninfo\fP\fB);\fP .fi .SH DESCRIPTION \fINOTE\fP: 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 \fIlibdb\fP. \fBdbopen\fP() 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 \fBbtree\fP(3), \fBhash\fP(3) et \fBrecno\fP(3). .PP \fBdbopen\fP() ouvre le fichier \fIfile\fP 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 \fIfile\fP à NULL. .PP .\"Three additional options may be specified by ORing .\"them into the .\".I flags .\"argument. .\".TP .\"DB_LOCK .\"Do the necessary locking in the database to support concurrent access. .\"If concurrent access isn't needed or the database is read-only this .\"flag should not be set, as it tends to have an associated performance .\"penalty. .\".TP .\"DB_SHMEM .\"Place the underlying memory pool used by the database in shared .\"memory. .\"Necessary for concurrent access. .\".TP .\"DB_TXN .\"Support transactions in the database. .\"The DB_LOCK and DB_SHMEM flags must be set as well. Les arguments \fIflags\fP et \fImode\fP doivent être spécifiés à la routine \fBopen\fP(2). Toutefois, seuls les attributs \fBO_CREAT\fP, \fBO_EXCL\fP, \fBO_EXLOCK\fP, \fBO_NONBLOCK\fP, \fBO_RDONLY\fP, \fBO_RDWR\fP, \fBO_SHLOCK\fP et \fBO_TRUNC\fP ont un sens (veuillez noter que l'ouverture d'un fichier d'une base de données en mode \fBO_WRONLY\fP n'est pas possible). .PP L'argument \fItype\fP est du type \fIDBTYPE\fP (défini dans le fichier d'en\-tête \fI\fP) et peut prendre les valeurs \fBDB_BTREE\fP, \fBDB_HASH\fP ou \fBDB_RECNO\fP. .PP L'argument \fIopeninfo\fP 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 \fIopeninfo\fP 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. .PP \fBdbopen\fP() renvoie un pointeur sur une structure \fIDB\fP si elle réussit, ou NULL en cas d'erreur. La structure \fIDB\fP est définie dans le fichier d'en\-tête \fI\fP et contient, au moins, les champs suivants\ : .sp .in +4n .nf 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; .fi .in .PP 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 \fBdbopen\fP(), et parfois un ou plusieurs pointeurs sur des structures clés/données et une valeur d'attribut. .TP \fItype\fP Le type de méthode d'accès sous\-jacent (et le type de fichier). .TP \fIclose\fP 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 \fIclose\fP() ou \fIsync\fP() peut résulter dans des données incohérentes ou perdues. La routine \fIclose\fP() renvoie \-1 en cas d'erreur (et remplit \fIerrno\fP) et 0 si elle réussit. .TP \fIdel\fP Un pointeur vers une routine permettant de supprimer des paires clés/données de la base de données. .IP Le paramètre \fIflag\fP peut prendre l'une des valeurs suivantes\ : .RS .TP \fBR_CURSOR\fP Supprimer l'enregistrement référencé par le curseur. Ce curseur doit bien entendu avoir été précédemment initialisé. .RE .IP La routine \fIdelete\fP() renvoie 0 si elle réussit, \-1 en cas d'erreur (et définit \fIerrno\fP), ou 1 si la clé \fIkey\fP indiquée n'a pas été trouvée dans le fichier. .TP \fIfd\fP 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 \fBdbopen\fP() avec le même nom \fIfile\fP. Ce descripteur de fichier doit pouvoir servir d'argument aux fonctions de verrouillage \fBfcntl\fP(2) et \fBflock\fP(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 \fIfd\fP renvoie \-1 en cas d'erreur (et définit \fIerrno\fP), et le descripteur de fichiers en cas de succès. .TP \fIget\fP 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é \fIkey\fP indiquée sont fournies dans une structure référencée par l'argument \fIdata\fP. La routine \fIget\fP() renvoie \-1 en cas d'erreur (et remplit \fIerrno\fP), 0 en cas de réussite, ou 1 si la clé \fIkey\fP n'a pas été trouvée dans le fichier. .TP \fIput\fP Un pointeur vers une routine permettant de stocker les paires clés/données dans la base de données. .IP Le paramètre \fIflag\fP peut prendre l'une des valeurs suivantes\ : .RS .TP \fBR_CURSOR\fP Remplacer la paire clé/donnée référencée par le curseur. Ce curseur doit avoir été positionné précédemment. .TP \fBR_IAFTER\fP Ajouter les données immédiatement après les données référencées par la clé \fIkey\fP, créant ainsi une nouvelle paire clé/donnée. Le numéro d'enregistrement de la paire ajoutée est renvoyé dans la structure \fIkey\fP (utilisable uniquement avec la méthode d'accès \fBDB_RECNO\fP). .TP \fBR_IBEFORE\fP Ajouter les données immédiatement avant les données référencées par \fIkey\fP, 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 \fIkey\fP (utilisable uniquement avec la méthode d'accès \fBDB_RECNO\fP). .TP \fBR_NOOVERWRITE\fP N'ajouter la paire clé/donnée que si la clé n'existe pas précédemment. .TP \fBR_SETCURSOR\fP 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 \fBDB_RECNO\fP et \fBDB_TREE\fP). .RE .IP \fBR_SETCURSOR\fP n'est disponible que pour les méthodes \fBDB_BTREE\fP et \fBDB_RECNO\fP car cela implique que les clés ont un ordre inhérent immuable. .IP \fBR_IAFTER\fP et \fBR_IBEFORE\fP ne sont disponibles qu'avec la méthode \fBDB_RECNO\fP 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. .IP Le comportement par défaut de la routine \fIput\fP est de stocker une nouvelle paire clé/donnée, en remplaçant toute clé existant précédemment. .IP Les routines \fIput\fP() renvoient \-1 en cas d'erreur (et remplissent \fIerrno\fP), 0 en cas de succès, ou 1 si l'attribut \fBR_NOOVERWRITE\fP a été indiqué dans \fIflag\fP, et si la clé existait déjà dans le fichier. .TP \fIseq\fP 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 \fIkey\fP, et l'adresse et la longueur des données dans une structure référencée par \fIdata\fP. .IP 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 \fIdel\fP(), \fIget\fP(), \fIput\fP(), ou \fIsync\fP(). 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. .IP La valeur de \fIflags\fP \fBdoit\fP être l'une des valeurs suivantes\ : .RS .TP \fBR_CURSOR\fP La routine renvoie les données associées avec la clé indiquée. C'est différent du comportement de la routine \fIget\fP() car le curseur est également positionné ou initialisé. (Veuillez noter que pour la méthode d'accès \fBDB_BTREE\fP, 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). .TP \fBR_FIRST\fP On renvoie la première paire clé/donnée de la base, et le curseur est initialisé ou positionné pour la référencer. .TP \fBR_LAST\fP 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 \fBDB_BTREE\fP et \fBDB_RECNO\fP). .TP \fBR_NEXT\fP 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 \fBR_FIRST\fP. .TP \fBR_PREV\fP 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 \fBR_LAST\fP. (Disponible uniquement pour les méthodes \fBDB_BTREE\fP et \fBDB_RECNO\fP). .RE .IP \fBR_LAST\fP et \fBR_PREV\fP ne sont disponibles que pour les méthodes \fBDB_BTREE\fP et \fBDB_RECNO\fP car ils impliquent que les clés aient un ordre inhérent immuable. .IP La routine \fIseq\fP() renvoie \-1 en cas d'erreur (et remplit \fIerrno\fP), 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 \fBDB_RECNO\fP, 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 \fIseq\fP renvoie 2. .TP \fIsync\fP 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 \fIsync\fP() n'a pas d'effet, et réussira toujours. .IP La valeur de \fIflags\fP peut être la suivante\ : .RS .TP \fBR_RECNOSYNC\fP Si on utilise la méthode \fBDB_RECNO\fP, ce drapeau oblige la synchronisation à s'appliquer au fichier btree sous\-jacent du fichier recno, et non pas à ce dernier. (Consultez le champ \fIbfname\fP de la page de manuel \fBrecno\fP(3) pour plus d'informations.) .RE .IP La routine \fIsync\fP() renvoie \-\1 en cas d'erreur (et remplit \fIerrno\fP) ou 0 en cas de réussite. .SS "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. .in +4n .nf typedef struct { void *data; size_t size; } DBT; .fi .in .PP Les éléments de la structure \fIDBT\fP sont définis ainsi\ : .TP \fIdata\fP Un pointeur vers une chaîne d'octets. .TP \fIsize\fP La longueur de la chaîne d'octets. .PP 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. .SH ERREURS La routine \fBdbopen\fP() peut échouer et placer dans \fIerrno\fP n'importe laquelle des erreurs renvoyées par les routines \fBopen\fP(2) et \fBmalloc\fP(3) ou l'une des erreurs suivantes\ : .TP \fBEFTYPE\fP Un fichier est mal formaté. .TP \fBEINVAL\fP 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. .PP Les routines \fIclose\fP() peuvent échouer et définir dans \fIerrno\fP l'une des erreurs spécifiées par les routines de bibliothèque \fBclose\fP(2), \fBread\fP(2), \fBwrite\fP(2), \fBfree\fP(3), ou \fBfsync\fP(2). .PP Les routines \fIdel\fP, \fIget\fP, \fIput\fP et \fIseq\fP peuvent échouer et définir dans \fIerrno\fP l'une des erreurs spécifiées par les routines de bibliothèque \fBread\fP(2), \fBwrite\fP(2), \fBfree\fP(3) ou \fBmalloc\fP(3). .PP Les routine \fIfd\fP peuvent échouer et définir \fIerrno\fP à \fBENOENT\fP pour les bases de données en mémoire. .PP Les routines \fIsync\fP peuvent échouer et définir dans \fIerrno\fP l'une des erreurs spécifiées par la routine de bibliothèque \fBfsync\fP(2). .SH BOGUES Le typedef \fIDBT\fP est un mnémonique pour «\ data base thang\ », qui a été choisi car personne n'arrivait à trouver un nom raisonnable et pas encore utilisé. .PP L'interface avec les descripteurs de fichier est une bidouille et sera supprimée dans les versions futures de l'interface. .PP Aucune méthode d'accès ne fournit de transactions, de verrouillages ou d'accès concurrents. .SH "VOIR AUSSI" \fBbtree\fP(3), \fBhash\fP(3), \fBmpool\fP(3), \fBrecno\fP(3) \fILIBTP: Portable, Modular Transactions for UNIX\fP, Margo Seltzer, Michael Olson, USENIX proceedings, Winter 1992. .SH COLOPHON Cette page fait partie de la publication 3.65 du projet \fIman\-pages\fP 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/. .SH TRADUCTION Depuis 2010, cette traduction est maintenue à l'aide de l'outil po4a par l'équipe de traduction francophone au sein du projet perkamon . .PP Christophe Blaess (1996-2003), Alain Portal (2003-2006). Florentin Duneau et l'équipe francophone de traduction de Debian\ (2006-2009). .PP Veuillez signaler toute erreur de traduction en écrivant à ou par un rapport de bogue sur le paquet \fBmanpages\-fr\fR. .PP Vous pouvez toujours avoir accès à la version anglaise de ce document en utilisant la commande «\ \fBman\ \-L C\fR \fI
\fR\ \fI\fR\ ».