1<!--$Id: hsearch.so,v 10.28 2004/09/28 15:04:20 bostic Exp $--> 2<!--Copyright (c) 1997,2008 Oracle. All rights reserved.--> 3<!--See the file LICENSE for redistribution information.--> 4<html> 5<head> 6<title>Berkeley DB: hsearch</title> 7<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit."> 8<meta name="keywords" content="embedded,database,programmatic,toolkit,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,Java,C,C++"> 9</head> 10<body bgcolor=white> 11<table width="100%"><tr valign=top> 12<td> 13<b>hsearch</b> 14</td> 15<td align=right> 16<a href="../api_c/api_core.html"><img src="../images/api.gif" alt="API"></a> 17<a href="../ref/toc.html"><img src="../images/ref.gif" alt="Ref"></a></td> 18</tr></table> 19<hr size=1 noshade> 20<tt> 21<b><pre> 22#define DB_DBM_HSEARCH 1 23#include <db.h> 24<p> 25typedef enum { 26 FIND, ENTER 27} ACTION; 28<p> 29typedef struct entry { 30 char *key; 31 void *data; 32} ENTRY; 33<p> 34ENTRY * 35hsearch(ENTRY item, ACTION action); 36<p> 37int 38hcreate(size_t nelem); 39<p> 40void 41hdestroy(void); 42</pre></b> 43<hr size=1 noshade> 44<b>Description: hsearch</b> 45<p>The hsearch functions are intended to provide a high-performance 46implementation and source code compatibility for applications written 47to the historic hsearch interface. It is not recommended for any other 48purpose.</p> 49<p>To compile hsearch applications, replace the application's 50<b>#include</b> of the hsearch include 51file (for example, <b>#include <search.h></b>) 52with the following two lines:</p> 53<blockquote><pre>#define DB_DBM_HSEARCH 1 54#include <db.h></pre></blockquote> 55<p>and recompile.</p> 56<p>The hcreate function creates an in-memory database. The 57<b>nelem</b> parameter is an estimation of the maximum number of key/data 58pairs that will be stored in the database.</p> 59<p>The <b>hdestroy</b> function discards the database.</p> 60<p>Database elements are structures of type <b>ENTRY</b>, which contain at 61least two fields: <b>key</b> and <b>data</b>. The field <b>key</b> is 62declared to be of type <b>char *</b>, and is the key used for storage 63and retrieval. The field <b>data</b> is declared to be of type 64<b>void *</b>, and is its associated data.</p> 65<p>The hsearch function retrieves key/data pairs from, and stores 66key/data pairs into the database.</p> 67<p>The <b>action</b> parameter must be set to one of two values:</p> 68<br> 69<b>ENTER</b><ul compact><li>If the key does not already appear in the database, insert the key/data 70pair into the database. If the key already appears in the database, 71return a reference to an <b>ENTRY</b> structure which refers to the 72existing key and its associated data element.</ul> 73<b>FIND</b><ul compact><li>Retrieve the specified key/data pair from the database.</ul> 74<br> 75<b>Compatibility Notes</b> 76<p>Historically, hsearch required applications to maintain the keys 77and data in the application's memory for as long as the <b>hsearch</b> 78database existed. Because Berkeley DB handles key and data management 79internally, there is no requirement that applications maintain local 80copies of key and data items, although the only effect of doing so 81should be the allocation of additional memory.</p> 82<b>Hsearch Diagnostics</b> 83<p>The <b>hcreate</b> function returns 0 on failure, setting 84<b>errno</b>, and non-zero on success.</p> 85<p>The <b>hsearch</b> function returns a pointer to an ENTRY structure on 86success, and NULL, setting <b>errno</b>, if the <b>action</b> 87specified was FIND and the item did not appear in the database.</p> 88<br><b>Errors</b> 89<p>The <b>hsearch</b> function will fail, setting <b>errno</b> to 0, 90if the <b>action</b> specified was FIND and the item did not appear in 91the database.</p> 92<p>In addition, the hcreate, hsearch and hdestroy functions may fail and 93return an error for errors specified for other Berkeley DB and C library or 94system functions.</p> 95</tt> 96<table width="100%"><tr><td><br></td><td align=right> 97<a href="../api_c/api_core.html"><img src="../images/api.gif" alt="API"></a><a href="../ref/toc.html"><img src="../images/ref.gif" alt="Ref"></a> 98</td></tr></table> 99<p><font size=1>Copyright (c) 1996,2008 Oracle. All rights reserved.</font> 100</body> 101</html> 102
