.\" -*- coding: UTF-8 -*-
'\" t
.\" Copyright 1993 Ulrich Drepper (drepper@karlsruhe.gmd.de)
.\" and Copyright 2008, Linux Foundation, written by Michael Kerrisk
.\"     <mtk.manpages@gmail.com>
.\"
.\" SPDX-License-Identifier: GPL-2.0-or-later
.\"
.\" References consulted:
.\"     SunOS 4.1.1 man pages
.\" Modified Sat Sep 30 21:52:01 1995 by Jim Van Zandt <jrv@vanzandt.mv.com>
.\" Remarks from dhw@gamgee.acad.emich.edu Fri Jun 19 06:46:31 1998
.\" Modified 2001-12-26, 2003-11-28, 2004-05-20, aeb
.\" 2008-09-02, mtk: various additions and rewrites
.\" 2008-09-03, mtk, restructured somewhat, in part after suggestions from
.\"     Timothy S. Nelson <wayland@wayland.id.au>
.\"
.\"*******************************************************************
.\"
.\" This file was generated with po4a. Translate the source file.
.\"
.\"*******************************************************************
.TH hsearch 3 "15 juin 2024" "Pages du manuel de Linux 6.9.1" 
.SH NOM
hcreate, hdestroy, hsearch, hcreate_r, hdestroy_r, hsearch_r \- Gestion de
table de hachage
.SH BIBLIOTHÈQUE
Bibliothèque C standard (\fIlibc\fP, \fI\-lc\fP)
.SH SYNOPSIS
.nf
\fB#include <search.h>\fP
.P
\fBint hcreate(size_t \fP\fInel\fP\fB);\fP
\fBvoid hdestroy(void);\fP
.P
\fBENTRY *hsearch(ENTRY \fP\fIitem\fP\fB, ACTION \fP\fIaction\fP\fB);\fP
.P
\fB#define _GNU_SOURCE\fP         /* Consultez feature_test_macros(7) */
\fB#include <search.h>\fP
.P
\fBint hcreate_r(size_t \fP\fInel\fP\fB, struct hsearch_data *\fP\fIhtab\fP\fB);\fP
\fBvoid hdestroy_r(struct hsearch_data *\fP\fIhtab\fP\fB);\fP
.P
\fBint hsearch_r(ENTRY \fP\fIitem\fP\fB, ACTION \fP\fIaction\fP\fB, ENTRY **\fP\fIretval\fP\fB,\fP
\fB              struct hsearch_data *\fP\fIhtab\fP\fB);\fP
.fi
.SH DESCRIPTION
Les trois fonctions \fBhcreate\fP(), \fBhsearch\fP() et \fBhdestroy\fP() permettent à
l'utilisateur de créer et de gérer une table de hachage qui associe une clé
(une chaîne de caractères) avec des données quelconques. Une seule table de
hachage peut être utilisée à la fois avec ces fonctions.
.P
Les fonctions \fBhcreate_r\fP(), \fBhsearch_r\fP() et \fBhdestroy_r\fP() sont des
versions réentrantes qui permettent d'utiliser plusieurs tables en même
temps. Le dernier argument \fIhtab\fP pointe vers une structure qui identifie
la table à utiliser. Le programmeur doit traiter la structure comme opaque
(par exemple, il est impossible d'accéder ou de modifier la table de hachage
depuis cette structure).
.P
.\" e.g., in glibc it is raised to the next higher prime number
La table doit d'abord être créée avec \fBhcreate\fP(). L'argument \fInel\fP est le
nombre maximal d'éléments de la table (le maximum ne peut pas être changé
pas la suite). L'implémentation peut décider d'augmenter cette valeur, afin
d'améliorer les performances de la table de hachage.
.P
\fBhcreate_r\fP() effectue la même tâche que \fBhcreate\fP() mais pour les tables
décrites par la structure \fI*htab\fP. La structure pointée par \fIhtab\fP doit
être initialisée avec des zéros avant le premier appel à \fBhcreate_r\fP().
.P
La fonction \fBhdestroy\fP() libère la mémoire occupée par la table de hachage
créée par \fBhcreate\fP(). Après un appel à \fBhdestroy\fP(), une nouvelle table
de hachage peut être créée avec \fBhcreate\fP(). La fonction \fBhdestroy_r\fP()
effectue la même tâche pour une table de hachage décrite par \fI*htab\fP, qui a
été préalablement créée par \fBhcreate_r\fP().
.P
\fBhsearch\fP() cherche dans la table de hachage un élément dont la clé est la
même que \fIitem\fP (au sens de \fBstrcmp\fP(3)), et retourne un pointeur sur cet
élément si la recherche réussit.
.P
L'argument \fIitem\fP est du type \fIENTRY\fP, qui est défini dans
\fI<search.h>\fP ainsi\ :
.P
.in +4n
.EX
typedef struct entry {
    char *key;
    void *data;
} ENTRY;
.EE
.in
.P
Le champ \fIkey\fP pointe vers une chaîne terminée par un caractère nul qui est
la clé cherchée. Le champ \fIdata\fP pointe vers les données associées à la
clé.
.P
Le paramètre \fIaction\fP détermine ce que doit faire \fBhsearch\fP() après une
recherche infructueuse. Si \fIaction\fP est égal à \fBENTER\fP, alors une copie de
\fIitem\fP est insérée et un pointeur sur ce nouvel élément est renvoyé. Si
\fIaction\fP est égal à \fBFIND\fP, NULL est renvoyé et \fIdata\fP est ignoré.
.P
\fBhsearch_r\fP() est similaire à \fBhsearch\fP(), mais elle opère sur la table de
hachage décrite par \fI*htab\fP, et le pointeur de l'objet trouvé est renvoyé
dans \fI*retval\fP et non dans la valeur de retour de la fonction.
.SH "VALEUR RENVOYÉE"
\fBhcreate\fP() et \fBhcreate_r\fP() renvoient une valeur non nulle en cas de
succès. En cas d'erreur, \fB0\fP est renvoyé et \fIerrno\fP est positionné pour
indiquer l'erreur.
.P
En cas de succès, \fBhsearch\fP renvoie un pointeur vers une entrée de la table
de hachage. Elle renvoie NULL en cas d'erreur, à savoir si \fIaction\fP est
égal à \fBENTER\fP et la table de hachage pleine, ou si \fIaction\fP est égal à
\fBFIND\fP et \fIitem\fP ne peut pas être trouvé. \fBhsearch_r\fP() renvoie une
valeur non nulle en cas de succès et zéro en cas d'erreur. En cas d'erreur,
ces fonctions positionnent \fIerrno\fP pour indiquer l'erreur.
.SH ERREURS
\fBhcreate_r\fP() et \fBhdestroy_r\fP() peuvent échouer pour les raisons
suivantes\ :
.TP 
\fBEINVAL\fP
\fIhtab\fP est NULL.
.P
\fBhsearch\fP et \fBhsearch_r\fP peuvent échouer pour les raisons suivantes\ :
.TP 
\fBENOMEM\fP
\fIaction\fP est \fBENTER\fP, \fIkey\fP n'a pas été trouvé dans la table, et il n'y a
plus de place dans la table pour ajouter un nouvel élément.
.TP 
\fBESRCH\fP
\fIaction\fP vaut \fBFIND\fP et \fIkey\fP n'a pas été trouvé dans la table.
.P
.\" PROX.1-2001, POSIX.1-2008
POSIX.1 spécifie seulement l'erreur \fBENOMEM\fP.
.SH ATTRIBUTS
Pour une explication des termes utilisés dans cette section, consulter
\fBattributes\fP(7).
.TS
allbox;
lbx lb lb
l l l.
Interface	Attribut	Valeur
T{
.na
.nh
\fBhcreate\fP(),
\fBhsearch\fP(),
\fBhdestroy\fP()
T}	Sécurité des threads	MT\-Unsafe race:hsearch
T{
.na
.nh
\fBhcreate_r\fP(),
\fBhsearch_r\fP(),
\fBhdestroy_r\fP()
T}	Sécurité des threads	MT\-Safe race:htab
.TE
.SH STANDARDS
.TP 
\fBhcreate\fP()
.TQ
\fBhsearch\fP()
.TQ
\fBhdestroy\fP()
POSIX.1\-2008.
.TP 
\fBhcreate_r\fP()
.TQ
\fBhsearch_r\fP()
.TQ
\fBhdestroy_r\fP()
GNU.
.SH HISTORIQUE
.TP 
\fBhcreate\fP()
.TQ
\fBhsearch\fP()
.TQ
\fBhdestroy\fP()
SVr4, POSIX.1\-2001.
.TP 
\fBhcreate_r\fP()
.TQ
\fBhsearch_r\fP()
.TQ
\fBhdestroy_r\fP()
GNU.
.SH NOTES
L'implémentation des tables de hachage est généralement plus efficace
lorsque la table possède assez d'espace libre pour minimiser les
collisions. Typiquement, cela signifie que \fInel\fP devrait être 25\ % plus
large que le nombre maximal d'éléments que l'on souhaite enregistrer dans la
table.
.P
Les fonctions \fBhdestroy\fP() et \fBhdestroy_r\fP() ne libèrent pas les tampons
pointés par les éléments \fIkey\fP et \fIdata\fP de la table de hachage. Elles ne
peuvent pas le faire car elles ne savent pas où ces tampons ont été alloués
dynamiquement. Si ces tampons doivent être libérés (peut\-être car le
programme crée et supprime des tables de hachage de façon répétitive, au
lieu de créer un seule table pour toute la vie du programme), alors le
programme doit maintenir la liste des tampons libérables.
.SH BOGUES
SVr4 et POSIX.1\-2001 précisent que \fIaction\fP n'est significatif que pour les
recherches infructueuses\ ; ainsi \fBENTER\fP ne devrait avoir aucune influence
pour une recherche réussie. Les implémentations libc et glibc (antérieure à
la 2.3) ne suivaient pas les spécifications car elles mettaient à jour les
données \fIdata\fP de la clé \fIkey\fP dans ce cas.
.P
Les entrées ne peuvent être qu'ajoutées dans la table, on ne peut pas les
supprimer individuellement.
.SH EXEMPLES
Le programme suivant insère 24 éléments dans une table de hachage, puis
affiche quelques\-uns d'entre eux.
.P
.\" SRC BEGIN (hsearch.c)
.EX
#include <search.h>
#include <stdio.h>
#include <stdlib.h>
\&
static char *data[] = { "alpha", "bravo", "charlie", "delta",
     "echo", "foxtrot", "golf", "hotel", "india", "juliet",
     "kilo", "lima", "mike", "november", "oscar", "papa",
     "quebec", "romeo", "sierra", "tango", "uniform",
     "victor", "whisky", "x\-ray", "yankee", "zulu"
};
\&
int
main(void)
{
    ENTRY e;
    ENTRY *ep;
\&
    hcreate(30);
\&
    for (size_t i = 0; i < 24; i++) {
        e.key = data[i];
        /* data is just an integer, instead of a
           pointer to something */
        e.data = (void *) i;
        ep = hsearch(e, ENTER);
        /* there should be no failures */
        if (ep == NULL) {
            fprintf(stderr, "entry failed\[rs]n");
            exit(EXIT_FAILURE);
        }
    }
\&
    for (size_t i = 22; i < 26; i++) {
        /* print two entries from the table, and
           show that two are not in the table */
        e.key = data[i];
        ep = hsearch(e, FIND);
        printf("%9.9s \-> %9.9s:%d\[rs]n", e.key,
               ep ? ep\->key : "NULL", ep ? (int)(ep\->data) : 0);
    }
    hdestroy();
    exit(EXIT_SUCCESS);
}
.EE
.\" SRC END
.SH "VOIR AUSSI"
\fBbsearch\fP(3), \fBlsearch\fP(3), \fBmalloc\fP(3), \fBtsearch\fP(3)
.PP
.SH 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>,
David Prévot <david@tilapin.org>,
Jean-Baptiste Holcroft <jean-baptiste@holcroft.fr>,
Grégoire Scano <gregoire.scano@malloc.fr>
et
Jean-Philippe MENGUAL <jpmengual@debian.org>
.
.PP
Cette traduction est une documentation libre ; veuillez vous reporter à la
.UR https://www.gnu.org/licenses/gpl-3.0.html
GNU General Public License version 3
.UE
concernant les conditions de copie et 
de distribution. Il n'y a aucune RESPONSABILITÉ LÉGALE.
.PP
Si vous découvrez un bogue dans la traduction de cette page de manuel, 
veuillez envoyer un message à
.MT debian-l10n-french@lists.debian.org
.ME .