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