diff options
author | nik <nik@FreeBSD.org> | 2001-02-11 17:24:25 +0000 |
---|---|---|
committer | nik <nik@FreeBSD.org> | 2001-02-11 17:24:25 +0000 |
commit | f75d644ef5d91dd0e940835d381ab68f557c582c (patch) | |
tree | a1dfd5b5eb69ba647406997836b68fd3cfffa591 /lib/libc/db/man | |
parent | ea5e661a0c8897c76720c291763c1873f300514d (diff) | |
download | FreeBSD-src-f75d644ef5d91dd0e940835d381ab68f557c582c.zip FreeBSD-src-f75d644ef5d91dd0e940835d381ab68f557c582c.tar.gz |
Add a man page for the dbm_* functions, and update the Makefile to link
it in.
Some review from -hackers (some time ago), and I think the best way to
get this improved (if it needs improving) or updating, is to bring it in.
PR: docs/12557
Submitted by: Tim Singletary <tsingle@triana.gsfc.nasa.gov>
Diffstat (limited to 'lib/libc/db/man')
-rw-r--r-- | lib/libc/db/man/Makefile.inc | 12 | ||||
-rw-r--r-- | lib/libc/db/man/dbm.3 | 200 |
2 files changed, 211 insertions, 1 deletions
diff --git a/lib/libc/db/man/Makefile.inc b/lib/libc/db/man/Makefile.inc index 1498413..8ccef0a 100644 --- a/lib/libc/db/man/Makefile.inc +++ b/lib/libc/db/man/Makefile.inc @@ -4,7 +4,17 @@ .PATH: ${.CURDIR}/../libc/db/man .if ${LIB} == "c" -MAN3+= btree.3 dbopen.3 hash.3 mpool.3 recno.3 +MAN3+= btree.3 dbm.3 dbopen.3 hash.3 mpool.3 recno.3 +MLINKS+= dbm.3 dbm_clearerr.3 +MLINKS+= dbm.3 dbm_close.3 +MLINKS+= dbm.3 dbm_delete.3 +MLINKS+= dbm.3 dbm_dirnfo.3 +MLINKS+= dbm.3 dbm_error.3 +MLINKS+= dbm.3 dbm_fetch.3 +MLINKS+= dbm.3 dbm_firstkey.3 +MLINKS+= dbm.3 dbm_nextkey.3 +MLINKS+= dbm.3 dbm_open.3 +MLINKS+= dbm.3 dbm_store.3 MLINKS+= dbopen.3 db.3 .endif diff --git a/lib/libc/db/man/dbm.3 b/lib/libc/db/man/dbm.3 new file mode 100644 index 0000000..b34f71e --- /dev/null +++ b/lib/libc/db/man/dbm.3 @@ -0,0 +1,200 @@ +.\" Copyright (c) 1999 Tim Singletary +.\" No copyright is claimed. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.\" Note: The date here should be updated whenever a non-trivial +.\" change is made to the manual page. +.Dd July 7, 1999 +.Dt dbm 3 +.Sh NAME +.Nm dbm_clearerr Ns No , +.Nm dbm_close Ns No , +.Nm dbm_delete Ns No , +.Nm dbm_dirfno Ns No , +.Nm dbm_error Ns No , +.Nm dbm_fetch Ns No , +.Nm dbm_firstkey Ns No , +.Nm dbm_nextkey Ns No , +.Nm dbm_open Ns No , +.Nm dbm_store +.Nd database access functions +.Sh SYNOPSIS +.Fd #include <fcntl.h> +.Fd #include <ndbm.h> +.Ft DBM * +.Fn dbm_open "const char *base" "int flags" "int mode" +.Ft void +.Fn dbm_close "DBM *db" +.Ft int +.Fn dbm_store "DBM *db" "datum key" "datum data" "int flags" +.Ft datum +.Fn dbm_fetch "DBM *db" "datum key" +.Ft int +.Fn dbm_delete "DBM *db" "datum key" +.Ft datum +.Fn dbm_firstkey "DBM *db" +.Ft datum +.Fn dbm_nextkey "DBM *db" +.Ft int +.Fn dbm_error "DBM *db" +.Ft int +.Fn dbm_clearerr "DBM *db" +.Ft int +.Fn dbm_dirfno "DBM *db" + +.Sh DESCRIPTION +Database access functions. +These functions are implemented using +.Fn dbopen +(see +.Xr dbopen 3 Ns No ) +with a +.Nm hash +(see +.Xr hash 3 Ns No ) +database. + +.Fa datum +is declared in +.Pa ndbm.h Ns No : +.Bd -literal +typedef struct { + char *dptr; + int dsize; +} datum; +.Ed + + +.Fn dbm_open base flags mode +opens or creates a database. +.Fa base No is the basename of the file containing +the database; the actual database has a +.Sq .db +suffix. I.e., if +.Fa base +is +.Pa /home/me/mystuff +then the actual database is in the file +.Pa /home/me/mystuff.db Ns No . +.Fa flags No and +.Fa mode No are passed to +.Fn open No (see +.Xr open 2 Ns No ). +.Li O_RDWR | O_CREAT +is a typical value for +.Fa flags Ns No ; +.Li 0660 +is a typical value for +.Fa mode Ns No . +.Li O_WRONLY +is not allowed in +.Fa flags Ns No . +The pointer returned by +.Fn dbm_open +identifies the database and is the +.Fa db +argument to the other functions. +.Fn dbm_open +returns +.Li NULL +and sets +.Va errno +if there are any errors. + +.Fn dbm_close db +closes the database. +.Fn dbm_close +normally returns zero. + +.Fn dbm_store db key data flags +inserts or replaces an entry in the database. +.Fa flags No is either +.Li DBM_INSERT +or +.Li DBM_REPLACE Ns No . +If +.Fa flags +is +.Li DBM_INSERT +and the database already contains an entry for +.Fa key Ns No , +that entry is not replaced. Otherwise the entry is replaced or inserted. +.Fn dbm_store +normally returns returns zero but returns 1 if the entry could not be +inserted (because +.Fa flags +is +.Li DBM_INSERT +and an entry with +.Fa key +already exists) or returns -1 and sets +.Va errno +if there were any errors. + +.Fn dbm_fetch db key +returns +.Li NULL +or the +.Fa data +corresponding to +.Fa key Ns No . + +.Fn dbm_delete db key +deletes the entry for +.Fa key Ns No . +.Fn dbm_delete +normally returns zero but returns 1 if there was no entry with +.Fa key +in the database or returns -1 and sets +.Va errno +if there were any errors. + +.Fn dbm_firstkey db +returns the first key in the database. +.Fn dbm_nextkey db +returns subsequent keys. +.Fn db_firstkey +must be called before +.Fn dbm_nextkey. +The order in which keys are returned is unspecified and may appear +random. +.Fn dbm_nextkey +returns +.Li NULL +after all keys have been returned. + +.Fn dbm_error db +returns the +.Va errno +value of the most recent error. +.Fn dbm_clearerr db +resets this value to 0 and returns 0. + +.Fn dbm_dirfno db +returns the file descriptor to the database. + + +.Sh SEE ALSO +.Xr dbopen 3 Ns , +.Xr hash 3 Ns , +.Xr open 2 + +.Sh STANDARDS +These functions (except +.Fn dbm_dirfno Ns No ) +are included in the Single Unix Specification for Unix 98. + + |