242 lines
12 KiB
HTML
242 lines
12 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<html>
|
|
<head>
|
|
<meta name="generator" content="HTML Tidy, see www.w3.org">
|
|
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
|
<link type="text/css" rel="stylesheet" href="style.css"><!-- Generated by The Open Group's rhtm tool v1.2.1 -->
|
|
<!-- Copyright (c) 2001 The Open Group, All Rights Reserved -->
|
|
<title>dbm_clearerr</title>
|
|
</head>
|
|
<body bgcolor="white">
|
|
<script type="text/javascript" language="JavaScript" src="../jscript/codes.js">
|
|
</script>
|
|
|
|
<basefont size="3"> <a name="dbm_clearerr"></a> <a name="tag_03_105"></a><!-- dbm_clearerr -->
|
|
<!--header start-->
|
|
<center><font size="2">The Open Group Base Specifications Issue 6<br>
|
|
IEEE Std 1003.1-2001<br>
|
|
Copyright © 2001 The IEEE and The Open Group, All Rights reserved.</font></center>
|
|
|
|
<!--header end-->
|
|
<hr size="2" noshade>
|
|
<h4><a name="tag_03_105_01"></a>NAME</h4>
|
|
|
|
<blockquote>dbm_clearerr, dbm_close, dbm_delete, dbm_error, dbm_fetch, dbm_firstkey, dbm_nextkey, dbm_open, dbm_store - database
|
|
functions</blockquote>
|
|
|
|
<h4><a name="tag_03_105_02"></a>SYNOPSIS</h4>
|
|
|
|
<blockquote class="synopsis">
|
|
<div class="box"><code><tt><sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img src="../images/opt-start.gif" alt=
|
|
"[Option Start]" border="0"> #include <<a href="../basedefs/ndbm.h.html">ndbm.h</a>><br>
|
|
<br>
|
|
int dbm_clearerr(DBM *</tt><i>db</i><tt>);<br>
|
|
void dbm_close(DBM *</tt><i>db</i><tt>);<br>
|
|
int dbm_delete(DBM *</tt><i>db</i><tt>, datum</tt> <i>key</i><tt>);<br>
|
|
int dbm_error(DBM *</tt><i>db</i><tt>);<br>
|
|
datum dbm_fetch(DBM *</tt><i>db</i><tt>, datum</tt> <i>key</i><tt>);<br>
|
|
datum dbm_firstkey(DBM *</tt><i>db</i><tt>);<br>
|
|
datum dbm_nextkey(DBM *</tt><i>db</i><tt>);<br>
|
|
DBM *dbm_open(const char *</tt><i>file</i><tt>, int</tt> <i>open_flags</i><tt>, mode_t</tt> <i>file_mode</i><tt>);<br>
|
|
int dbm_store(DBM *</tt><i>db</i><tt>, datum</tt> <i>key</i><tt>, datum</tt> <i>content</i><tt>, int</tt>
|
|
<i>store_mode</i><tt>);<br>
|
|
<img src="../images/opt-end.gif" alt="[Option End]" border="0"></tt></code></div>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_105_03"></a>DESCRIPTION</h4>
|
|
|
|
<blockquote>
|
|
<p>These functions create, access, and modify a database.</p>
|
|
|
|
<p>A <b>datum</b> consists of at least two members, <i>dptr</i> and <i>dsize</i>. The <i>dptr</i> member points to an object that
|
|
is <i>dsize</i> bytes in length. Arbitrary binary data, as well as character strings, may be stored in the object pointed to by
|
|
<i>dptr</i>.</p>
|
|
|
|
<p>The database is stored in two files. One file is a directory containing a bitmap of keys and has <b>.dir</b> as its suffix. The
|
|
second file contains all data and has <b>.pag</b> as its suffix.</p>
|
|
|
|
<p>The <i>dbm_open</i>() function shall open a database. The <i>file</i> argument to the function is the pathname of the database.
|
|
The function opens two files named <i>file</i><b>.dir</b> and <i>file</i><b>.pag</b>. The <i>open_flags</i> argument has the same
|
|
meaning as the <i>flags</i> argument of <a href="../functions/open.html"><i>open</i>()</a> except that a database opened for
|
|
write-only access opens the files for read and write access and the behavior of the O_APPEND flag is unspecified. The
|
|
<i>file_mode</i> argument has the same meaning as the third argument of <a href="../functions/open.html"><i>open</i>()</a>.</p>
|
|
|
|
<p>The <i>dbm_close</i>() function shall close a database. The application shall ensure that argument <i>db</i> is a pointer to a
|
|
<b>dbm</b> structure that has been returned from a call to <i>dbm_open</i>().</p>
|
|
|
|
<p>These database functions shall support an internal block size large enough to support key/content pairs of at least 1023
|
|
bytes.</p>
|
|
|
|
<p>The <i>dbm_fetch</i>() function shall read a record from a database. The argument <i>db</i> is a pointer to a database structure
|
|
that has been returned from a call to <i>dbm_open</i>(). The argument <i>key</i> is a <b>datum</b> that has been initialized by the
|
|
application to the value of the key that matches the key of the record the program is fetching.</p>
|
|
|
|
<p>The <i>dbm_store</i>() function shall write a record to a database. The argument <i>db</i> is a pointer to a database structure
|
|
that has been returned from a call to <i>dbm_open</i>(). The argument <i>key</i> is a <b>datum</b> that has been initialized by the
|
|
application to the value of the key that identifies (for subsequent reading, writing, or deleting) the record the application is
|
|
writing. The argument <i>content</i> is a <b>datum</b> that has been initialized by the application to the value of the record the
|
|
program is writing. The argument <i>store_mode</i> controls whether <i>dbm_store</i>() replaces any pre-existing record that has
|
|
the same key that is specified by the <i>key</i> argument. The application shall set <i>store_mode</i> to either DBM_INSERT or
|
|
DBM_REPLACE. If the database contains a record that matches the <i>key</i> argument and <i>store_mode</i> is DBM_REPLACE, the
|
|
existing record shall be replaced with the new record. If the database contains a record that matches the <i>key</i> argument and
|
|
<i>store_mode</i> is DBM_INSERT, the existing record shall be left unchanged and the new record ignored. If the database does not
|
|
contain a record that matches the <i>key</i> argument and <i>store_mode</i> is either DBM_INSERT or DBM_REPLACE, the new record
|
|
shall be inserted in the database.</p>
|
|
|
|
<p>If the sum of a key/content pair exceeds the internal block size, the result is unspecified. Moreover, the application shall
|
|
ensure that all key/content pairs that hash together fit on a single block. The <i>dbm_store</i>() function shall return an error
|
|
in the event that a disk block fills with inseparable data.</p>
|
|
|
|
<p>The <i>dbm_delete</i>() function shall delete a record and its key from the database. The argument <i>db</i> is a pointer to a
|
|
database structure that has been returned from a call to <i>dbm_open</i>(). The argument <i>key</i> is a <b>datum</b> that has been
|
|
initialized by the application to the value of the key that identifies the record the program is deleting.</p>
|
|
|
|
<p>The <i>dbm_firstkey</i>() function shall return the first key in the database. The argument <i>db</i> is a pointer to a database
|
|
structure that has been returned from a call to <i>dbm_open</i>().</p>
|
|
|
|
<p>The <i>dbm_nextkey</i>() function shall return the next key in the database. The argument <i>db</i> is a pointer to a database
|
|
structure that has been returned from a call to <i>dbm_open</i>(). The application shall ensure that the <i>dbm_firstkey</i>()
|
|
function is called before calling <i>dbm_nextkey</i>(). Subsequent calls to <i>dbm_nextkey</i>() return the next key until all of
|
|
the keys in the database have been returned.</p>
|
|
|
|
<p>The <i>dbm_error</i>() function shall return the error condition of the database. The argument <i>db</i> is a pointer to a
|
|
database structure that has been returned from a call to <i>dbm_open</i>().</p>
|
|
|
|
<p>The <i>dbm_clearerr</i>() function shall clear the error condition of the database. The argument <i>db</i> is a pointer to a
|
|
database structure that has been returned from a call to <i>dbm_open</i>().</p>
|
|
|
|
<p>The <i>dptr</i> pointers returned by these functions may point into static storage that may be changed by subsequent calls.</p>
|
|
|
|
<p>These functions need not be reentrant. A function that is not required to be reentrant is not required to be thread-safe.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_105_04"></a>RETURN VALUE</h4>
|
|
|
|
<blockquote>
|
|
<p>The <i>dbm_store</i>() and <i>dbm_delete</i>() functions shall return 0 when they succeed and a negative value when they
|
|
fail.</p>
|
|
|
|
<p>The <i>dbm_store</i>() function shall return 1 if it is called with a <i>flags</i> value of DBM_INSERT and the function finds an
|
|
existing record with the same key.</p>
|
|
|
|
<p>The <i>dbm_error</i>() function shall return 0 if the error condition is not set and return a non-zero value if the error
|
|
condition is set.</p>
|
|
|
|
<p>The return value of <i>dbm_clearerr</i>() is unspecified.</p>
|
|
|
|
<p>The <i>dbm_firstkey</i>() and <i>dbm_nextkey</i>() functions shall return a key <b>datum</b>. When the end of the database is
|
|
reached, the <i>dptr</i> member of the key is a null pointer. If an error is detected, the <i>dptr</i> member of the key shall be a
|
|
null pointer and the error condition of the database shall be set.</p>
|
|
|
|
<p>The <i>dbm_fetch</i>() function shall return a content <b>datum</b>. If no record in the database matches the key or if an error
|
|
condition has been detected in the database, the <i>dptr</i> member of the content shall be a null pointer.</p>
|
|
|
|
<p>The <i>dbm_open</i>() function shall return a pointer to a database structure. If an error is detected during the operation,
|
|
<i>dbm_open</i>() shall return a ( <b>DBM *</b>)0.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_105_05"></a>ERRORS</h4>
|
|
|
|
<blockquote>
|
|
<p>No errors are defined.</p>
|
|
</blockquote>
|
|
|
|
<hr>
|
|
<div class="box"><em>The following sections are informative.</em></div>
|
|
|
|
<h4><a name="tag_03_105_06"></a>EXAMPLES</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_105_07"></a>APPLICATION USAGE</h4>
|
|
|
|
<blockquote>
|
|
<p>The following code can be used to traverse the database:</p>
|
|
|
|
<pre>
|
|
<tt>for(key = dbm_firstkey(db); key.dptr != NULL; key = dbm_nextkey(db))
|
|
</tt>
|
|
</pre>
|
|
|
|
<p>The <i>dbm_</i>* functions provided in this library should not be confused in any way with those of a general-purpose database
|
|
management system. These functions do not provide for multiple search keys per entry, they do not protect against multi-user access
|
|
(in other words they do not lock records or files), and they do not provide the many other useful database functions that are found
|
|
in more robust database management systems. Creating and updating databases by use of these functions is relatively slow because of
|
|
data copies that occur upon hash collisions. These functions are useful for applications requiring fast lookup of relatively static
|
|
information that is to be indexed by a single key.</p>
|
|
|
|
<p>Note that a strictly conforming application is extremely limited by these functions: since there is no way to determine that the
|
|
keys in use do not all hash to the same value (although that would be rare), a strictly conforming application cannot be guaranteed
|
|
that it can store more than one block's worth of data in the database. As long as a key collision does not occur, additional data
|
|
may be stored, but because there is no way to determine whether an error is due to a key collision or some other error condition (
|
|
<i>dbm_error</i>() being effectively a Boolean), once an error is detected, the application is effectively limited to guessing what
|
|
the error might be if it wishes to continue using these functions.</p>
|
|
|
|
<p>The <i>dbm_delete</i>() function need not physically reclaim file space, although it does make it available for reuse by the
|
|
database.</p>
|
|
|
|
<p>After calling <i>dbm_store</i>() or <i>dbm_delete</i>() during a pass through the keys by <i>dbm_firstkey</i>() and
|
|
<i>dbm_nextkey</i>(), the application should reset the database by calling <i>dbm_firstkey</i>() before again calling
|
|
<i>dbm_nextkey</i>(). The contents of these files are unspecified and may not be portable.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_105_08"></a>RATIONALE</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_105_09"></a>FUTURE DIRECTIONS</h4>
|
|
|
|
<blockquote>
|
|
<p>None.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_105_10"></a>SEE ALSO</h4>
|
|
|
|
<blockquote>
|
|
<p><a href="open.html"><i>open</i>()</a> , the Base Definitions volume of IEEE Std 1003.1-2001, <a href=
|
|
"../basedefs/ndbm.h.html"><i><ndbm.h></i></a></p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_105_11"></a>CHANGE HISTORY</h4>
|
|
|
|
<blockquote>
|
|
<p>First released in Issue 4, Version 2.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_105_12"></a>Issue 5</h4>
|
|
|
|
<blockquote>
|
|
<p>Moved from X/OPEN UNIX extension to BASE.</p>
|
|
|
|
<p>Normative text previously in the APPLICATION USAGE section is moved to the DESCRIPTION.</p>
|
|
|
|
<p>A note indicating that these functions need not be reentrant is added to the DESCRIPTION.</p>
|
|
</blockquote>
|
|
|
|
<h4><a name="tag_03_105_13"></a>Issue 6</h4>
|
|
|
|
<blockquote>
|
|
<p>The DESCRIPTION is updated to avoid use of the term "must" for application requirements.</p>
|
|
</blockquote>
|
|
|
|
<div class="box"><em>End of informative text.</em></div>
|
|
|
|
<hr>
|
|
<hr size="2" noshade>
|
|
<center><font size="2"><!--footer start-->
|
|
UNIX ® is a registered Trademark of The Open Group.<br>
|
|
POSIX ® is a registered Trademark of The IEEE.<br>
|
|
[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href=
|
|
"../utilities/contents.html">XCU</a> | <a href="../functions/contents.html">XSH</a> | <a href="../xrat/contents.html">XRAT</a>
|
|
]</font></center>
|
|
|
|
<!--footer end-->
|
|
<hr size="2" noshade>
|
|
</body>
|
|
</html>
|
|
|