← Back to branch summary

~ubuntu-branches/ubuntu/maverick/evolution-data-server/maverick-proposed

« back to all changes in this revision

Viewing changes to libdb/docs/api_c/hsearch.html

  • Committer: Bazaar Package Importer
  • Author(s): Didier Roche
  • Date: 2010-05-17 17:02:06 UTC
  • mfrom: (1.1.79 upstream) (1.6.12 experimental)
  • Revision ID: james.westby@ubuntu.com-20100517170206-4ufr52vwrhh26yh0
Tags: 2.30.1-1ubuntu1
https://launchpad.net/bugs/42199
https://launchpad.net/bugs/229669
https://launchpad.net/bugs/173703
https://launchpad.net/bugs/360344
https://launchpad.net/bugs/508494
* Merge from debian experimental. Remaining change:
  (LP: #42199, #229669, #173703, #360344, #508494)
  + debian/control:
    - add Vcs-Bzr tag
    - don't use libgnome
    - Use Breaks instead of Conflicts against evolution 2.25 and earlier.
  + debian/evolution-data-server.install,
    debian/patches/45_libcamel_providers_version.patch:
    - use the upstream versioning, not a Debian-specific one 
  + debian/libedata-book1.2-dev.install, debian/libebackend-1.2-dev.install,
    debian/libcamel1.2-dev.install, debian/libedataserverui1.2-dev.install:
    - install html documentation
  + debian/rules:
    - don't build documentation it's shipped with the tarball

Show diffs side-by-side

added added

removed removed

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