master
1/* Declarations for System V style searching functions.
2 Copyright (C) 1995-2025 Free Software Foundation, Inc.
3 This file is part of the GNU C Library.
4
5 The GNU C Library is free software; you can redistribute it and/or
6 modify it under the terms of the GNU Lesser General Public
7 License as published by the Free Software Foundation; either
8 version 2.1 of the License, or (at your option) any later version.
9
10 The GNU C Library is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 Lesser General Public License for more details.
14
15 You should have received a copy of the GNU Lesser General Public
16 License along with the GNU C Library; if not, see
17 <https://www.gnu.org/licenses/>. */
18
19#ifndef _SEARCH_H
20#define _SEARCH_H 1
21
22#include <features.h>
23
24#define __need_size_t
25#include <stddef.h>
26
27__BEGIN_DECLS
28
29#if defined __USE_MISC || defined __USE_XOPEN_EXTENDED
30/* Prototype structure for a linked-list data structure.
31 This is the type used by the `insque' and `remque' functions. */
32
33# ifdef __USE_GNU
34struct qelem
35 {
36 struct qelem *q_forw;
37 struct qelem *q_back;
38 char q_data[1];
39 };
40# endif
41
42
43/* Insert ELEM into a doubly-linked list, after PREV. */
44extern void insque (void *__elem, void *__prev) __THROW;
45
46/* Unlink ELEM from the doubly-linked list that it is in. */
47extern void remque (void *__elem) __THROW;
48#endif
49
50
51/* For use with hsearch(3). */
52#ifndef __COMPAR_FN_T
53# define __COMPAR_FN_T
54typedef int (*__compar_fn_t) (const void *, const void *);
55
56# ifdef __USE_GNU
57typedef __compar_fn_t comparison_fn_t;
58# endif
59#endif
60
61/* Action which shall be performed in the call the hsearch. */
62typedef enum
63 {
64 FIND,
65 ENTER
66 }
67ACTION;
68
69typedef struct entry
70 {
71 char *key;
72 void *data;
73 }
74ENTRY;
75
76/* Opaque type for internal use. */
77struct _ENTRY;
78
79/* Family of hash table handling functions. The functions also
80 have reentrant counterparts ending with _r. The non-reentrant
81 functions all work on a single internal hashing table. */
82
83/* Search for entry matching ITEM.key in internal hash table. If
84 ACTION is `FIND' return found entry or signal error by returning
85 NULL. If ACTION is `ENTER' replace existing data (if any) with
86 ITEM.data. */
87extern ENTRY *hsearch (ENTRY __item, ACTION __action) __THROW;
88
89/* Create a new hashing table which will at most contain NEL elements. */
90extern int hcreate (size_t __nel) __THROW;
91
92/* Destroy current internal hashing table. */
93extern void hdestroy (void) __THROW;
94
95#ifdef __USE_GNU
96/* Data type for reentrant functions. */
97struct hsearch_data
98 {
99 struct _ENTRY *table;
100 unsigned int size;
101 unsigned int filled;
102 };
103
104/* Reentrant versions which can handle multiple hashing tables at the
105 same time. */
106extern int hsearch_r (ENTRY __item, ACTION __action, ENTRY **__retval,
107 struct hsearch_data *__htab) __THROW;
108extern int hcreate_r (size_t __nel, struct hsearch_data *__htab) __THROW;
109extern void hdestroy_r (struct hsearch_data *__htab) __THROW;
110#endif
111
112
113/* The tsearch routines are very interesting. They make many
114 assumptions about the compiler. It assumes that the first field
115 in node must be the "key" field, which points to the datum.
116 Everything depends on that. */
117/* For tsearch */
118typedef enum
119{
120 preorder,
121 postorder,
122 endorder,
123 leaf
124}
125VISIT;
126
127/* Search for an entry matching the given KEY in the tree pointed to
128 by *ROOTP and insert a new element if not found. */
129extern void *tsearch (const void *__key, void **__rootp,
130 __compar_fn_t __compar);
131
132/* Search for an entry matching the given KEY in the tree pointed to
133 by *ROOTP. If no matching entry is available return NULL. */
134extern void *tfind (const void *__key, void *const *__rootp,
135 __compar_fn_t __compar);
136
137/* Remove the element matching KEY from the tree pointed to by *ROOTP. */
138extern void *tdelete (const void *__restrict __key,
139 void **__restrict __rootp,
140 __compar_fn_t __compar);
141
142#ifndef __ACTION_FN_T
143# define __ACTION_FN_T
144typedef void (*__action_fn_t) (const void *__nodep, VISIT __value,
145 int __level);
146#endif
147
148/* Walk through the whole tree and call the ACTION callback for every node
149 or leaf. */
150extern void twalk (const void *__root, __action_fn_t __action);
151
152#ifdef __USE_GNU
153/* Like twalk, but pass down a closure parameter instead of the
154 level. */
155extern void twalk_r (const void *__root,
156 void (*) (const void *__nodep, VISIT __value,
157 void *__closure),
158 void *__closure);
159
160/* Callback type for function to free a tree node. If the keys are atomic
161 data this function should do nothing. */
162typedef void (*__free_fn_t) (void *__nodep);
163
164/* Destroy the whole tree, call FREEFCT for each node or leaf. */
165extern void tdestroy (void *__root, __free_fn_t __freefct);
166#endif
167
168
169/* Perform linear search for KEY by comparing by COMPAR in an array
170 [BASE,BASE+NMEMB*SIZE). */
171extern void *lfind (const void *__key, const void *__base,
172 size_t *__nmemb, size_t __size, __compar_fn_t __compar);
173
174/* Perform linear search for KEY by comparing by COMPAR function in
175 array [BASE,BASE+NMEMB*SIZE) and insert entry if not found. */
176extern void *lsearch (const void *__key, void *__base,
177 size_t *__nmemb, size_t __size, __compar_fn_t __compar);
178
179__END_DECLS
180
181#endif /* search.h */