102 lines
4.1 KiB
HTML
102 lines
4.1 KiB
HTML
<!--$Id: hsearch.html 63573 2008-05-23 21:43:21Z trent.nelson $-->
|
|
<!--Copyright (c) 1997,2008 Oracle. All rights reserved.-->
|
|
<!--See the file LICENSE for redistribution information.-->
|
|
<html>
|
|
<head>
|
|
<title>Berkeley DB: hsearch</title>
|
|
<meta name="description" content="Berkeley DB: An embedded database programmatic toolkit.">
|
|
<meta name="keywords" content="embedded,database,programmatic,toolkit,btree,hash,hashing,transaction,transactions,locking,logging,access method,access methods,Java,C,C++">
|
|
</head>
|
|
<body bgcolor=white>
|
|
<table width="100%"><tr valign=top>
|
|
<td>
|
|
<b>hsearch</b>
|
|
</td>
|
|
<td align=right>
|
|
<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></td>
|
|
</tr></table>
|
|
<hr size=1 noshade>
|
|
<tt>
|
|
<b><pre>
|
|
#define DB_DBM_HSEARCH 1
|
|
#include <db.h>
|
|
<p>
|
|
typedef enum {
|
|
FIND, ENTER
|
|
} ACTION;
|
|
<p>
|
|
typedef struct entry {
|
|
char *key;
|
|
void *data;
|
|
} ENTRY;
|
|
<p>
|
|
ENTRY *
|
|
hsearch(ENTRY item, ACTION action);
|
|
<p>
|
|
int
|
|
hcreate(size_t nelem);
|
|
<p>
|
|
void
|
|
hdestroy(void);
|
|
</pre></b>
|
|
<hr size=1 noshade>
|
|
<b>Description: hsearch</b>
|
|
<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
|
|
<b>#include</b> of the hsearch include
|
|
file (for example, <b>#include <search.h></b>)
|
|
with the following two lines:</p>
|
|
<blockquote><pre>#define DB_DBM_HSEARCH 1
|
|
#include <db.h></pre></blockquote>
|
|
<p>and recompile.</p>
|
|
<p>The hcreate function creates an in-memory database. The
|
|
<b>nelem</b> parameter is an estimation of the maximum number of key/data
|
|
pairs that will be stored in the database.</p>
|
|
<p>The <b>hdestroy</b> function discards the database.</p>
|
|
<p>Database elements are structures of type <b>ENTRY</b>, which contain at
|
|
least two fields: <b>key</b> and <b>data</b>. The field <b>key</b> is
|
|
declared to be of type <b>char *</b>, and is the key used for storage
|
|
and retrieval. The field <b>data</b> is declared to be of type
|
|
<b>void *</b>, 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 <b>action</b> parameter must be set to one of two values:</p>
|
|
<br>
|
|
<b>ENTER</b><ul compact><li>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 <b>ENTRY</b> structure which refers to the
|
|
existing key and its associated data element.</ul>
|
|
<b>FIND</b><ul compact><li>Retrieve the specified key/data pair from the database.</ul>
|
|
<br>
|
|
<b>Compatibility Notes</b>
|
|
<p>Historically, hsearch required applications to maintain the keys
|
|
and data in the application's memory for as long as the <b>hsearch</b>
|
|
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>
|
|
<b>Hsearch Diagnostics</b>
|
|
<p>The <b>hcreate</b> function returns 0 on failure, setting
|
|
<b>errno</b>, and non-zero on success.</p>
|
|
<p>The <b>hsearch</b> function returns a pointer to an ENTRY structure on
|
|
success, and NULL, setting <b>errno</b>, if the <b>action</b>
|
|
specified was FIND and the item did not appear in the database.</p>
|
|
<br><b>Errors</b>
|
|
<p>The <b>hsearch</b> function will fail, setting <b>errno</b> to 0,
|
|
if the <b>action</b> 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>
|
|
</tt>
|
|
<table width="100%"><tr><td><br></td><td align=right>
|
|
<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>
|
|
</td></tr></table>
|
|
<p><font size=1>Copyright (c) 1996,2008 Oracle. All rights reserved.</font>
|
|
</body>
|
|
</html>
|