1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
|
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<title>hsearch</title>
<link rel="stylesheet" href="apiReference.css" type="text/css" />
<meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
<link rel="start" href="index.html" title="Berkeley DB C API Reference" />
<link rel="up" href="historic.html" title="Appendix B. Historic Interfaces" />
<link rel="prev" href="dbm.html" title="dbm/ndbm" />
<link rel="next" href="setfunc.html" title="Appendix C. Berkeley DB Application Space Static Functions" />
</head>
<body>
<div xmlns="" class="navheader">
<div class="libver">
<p>Library Version 12.1.6.1</p>
</div>
<table width="100%" summary="Navigation header">
<tr>
<th colspan="3" align="center">hsearch</th>
</tr>
<tr>
<td width="20%" align="left"><a accesskey="p" href="dbm.html">Prev</a> </td>
<th width="60%" align="center">Appendix B.
Historic Interfaces
</th>
<td width="20%" align="right"> <a accesskey="n" href="setfunc.html">Next</a></td>
</tr>
</table>
<hr />
</div>
<div class="sect1" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h2 class="title" style="clear: both"><a id="hsearch"></a>hsearch</h2>
</div>
</div>
</div>
<pre class="programlisting">#define DB_DBM_HSEARCH 1
#include <db.h>
typedef enum {
FIND, ENTER
} ACTION;
typedef struct entry {
char *key;
void *data;
} ENTRY;
ENTRY *
hsearch(ENTRY item, ACTION action);
int
hcreate(size_t nelem);
void
hdestroy(void); </pre>
<p>
The hsearch functions are intended to provide a high-performance
implementation and source code compatibility for applications written
to the historic hsearch interface. It is not recommended for any
other purpose.
</p>
<p>
To compile hsearch applications, replace the application's <span class="bold"><strong>#include</strong></span> of the hsearch include file (for
example, <span class="bold"><strong>#include <search.h></strong></span>)
with the following two lines:
</p>
<pre class="programlisting">#define DB_DBM_HSEARCH 1
#include <db.h></pre>
<p>
and recompile.
</p>
<p>
The hcreate function creates an in-memory database. The <span class="bold"><strong>nelem</strong></span> parameter is an estimation of the maximum
number of key/data pairs that will be stored in the database.
</p>
<p>
The <span class="bold"><strong>hdestroy</strong></span> function discards the
database.
</p>
<p>
Database elements are structures of type <span class="bold"><strong>ENTRY</strong></span>, which contain at least two fields:
<span class="bold"><strong>key</strong></span> and <span class="bold"><strong>data</strong></span>. The field <span class="bold"><strong>key</strong></span> is declared to be of type <span class="bold"><strong>char *</strong></span>, and is the key used for storage and
retrieval. The field <span class="bold"><strong>data</strong></span> is
declared to be of type <span class="bold"><strong>void *</strong></span>, and is
its associated data.
</p>
<p>
The hsearch function retrieves key/data pairs from, and stores
key/data pairs into the database.
</p>
<p>
The <span class="bold"><strong>action</strong></span> parameter must be set to
one of two values:
</p>
<div class="itemizedlist">
<ul type="disc">
<li>
<p>
<span class="bold"><strong>ENTER</strong></span>
</p>
<p>
If the key does not already appear in the database, insert the
key/data pair into the database. If the key already appears in the
database, return a reference to an <span class="bold"><strong>ENTRY</strong></span> structure which refers to the existing
key and its associated data element.
</p>
</li>
<li>
<p>
<span class="bold"><strong>FIND</strong></span>
</p>
<p>
Retrieve the specified key/data pair from the database.
</p>
</li>
</ul>
</div>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="hsearch_compatnotes"></a>Compatibility Notes</h3>
</div>
</div>
</div>
<p>
Historically, hsearch required applications to maintain the keys and
data in the application's memory for as long as the <span class="bold"><strong>hsearch</strong></span> database existed. Because Berkeley DB
handles key and data management internally, there is no requirement
that applications maintain local copies of key and data items,
although the only effect of doing so should be the allocation of
additional memory.
</p>
</div>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="hsearch_diagnostics"></a>Hsearch Diagnostics</h3>
</div>
</div>
</div>
<p>
The <span class="bold"><strong>hcreate</strong></span> function returns 0 on
failure, setting <span class="bold"><strong>errno</strong></span>, and non-zero
on success.
</p>
<p>
The <span class="bold"><strong>hsearch</strong></span> function returns a
pointer to an ENTRY structure on success, and NULL, setting <span class="bold"><strong>errno</strong></span>, if the <span class="bold"><strong>action</strong></span> specified was FIND and the item did not
appear in the database.
</p>
</div>
<div class="sect2" lang="en" xml:lang="en">
<div class="titlepage">
<div>
<div>
<h3 class="title"><a id="hsearch_errors"></a>Hsearch Errors</h3>
</div>
</div>
</div>
<p>
The <span class="bold"><strong>hsearch</strong></span> function will fail,
setting <span class="bold"><strong>errno</strong></span> to 0, if the <span class="bold"><strong>action</strong></span> specified was FIND and the item did not
appear in the database.
</p>
<p>
In addition, the hcreate, hsearch and hdestroy functions may fail and
return an error for errors specified for other Berkeley DB and C
library or system functions.
</p>
</div>
</div>
<div class="navfooter">
<hr />
<table width="100%" summary="Navigation footer">
<tr>
<td width="40%" align="left"><a accesskey="p" href="dbm.html">Prev</a> </td>
<td width="20%" align="center">
<a accesskey="u" href="historic.html">Up</a>
</td>
<td width="40%" align="right"> <a accesskey="n" href="setfunc.html">Next</a></td>
</tr>
<tr>
<td width="40%" align="left" valign="top">dbm/ndbm </td>
<td width="20%" align="center">
<a accesskey="h" href="index.html">Home</a>
</td>
<td width="40%" align="right" valign="top"> Appendix C.
Berkeley DB Application Space Static Functions
</td>
</tr>
</table>
</div>
</body>
</html>
|
