From owner-freebsd-doc Wed Jul 7 17:40:10 1999 Delivered-To: freebsd-doc@freebsd.org Received: from freefall.freebsd.org (freefall.FreeBSD.ORG [204.216.27.21]) by hub.freebsd.org (Postfix) with ESMTP id 4741D1512D for ; Wed, 7 Jul 1999 17:40:01 -0700 (PDT) (envelope-from gnats@FreeBSD.org) Received: (from gnats@localhost) by freefall.freebsd.org (8.9.3/8.9.2) id RAA69622; Wed, 7 Jul 1999 17:40:02 -0700 (PDT) (envelope-from gnats@FreeBSD.org) Received: from talon.gsfc.nasa.gov (talon.gsfc.nasa.gov [128.183.221.175]) by hub.freebsd.org (Postfix) with ESMTP id 63F0115055 for ; Wed, 7 Jul 1999 17:37:53 -0700 (PDT) (envelope-from tsingle@talon.gsfc.nasa.gov) Received: (from tsingle@localhost) by talon.gsfc.nasa.gov (8.9.3/8.9.3) id UAA93629; Wed, 7 Jul 1999 20:38:37 -0400 (EDT) (envelope-from tsingle) Message-Id: <199907080038.UAA93629@talon.gsfc.nasa.gov> Date: Wed, 7 Jul 1999 20:38:37 -0400 (EDT) From: tsingle@triana.gsfc.nasa.gov Reply-To: tsingle@triana.gsfc.nasa.gov To: FreeBSD-gnats-submit@freebsd.org X-Send-Pr-Version: 3.2 Subject: docs/12557: no dbm_* man pages Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.org >Number: 12557 >Category: docs >Synopsis: There are no man pages for the widely used dbm_* functions in libc >Confidential: yes >Severity: serious >Priority: medium >Responsible: freebsd-doc >State: open >Quarter: >Keywords: >Date-Required: >Class: doc-bug >Submitter-Id: current-users >Arrival-Date: Wed Jul 7 17:40:01 PDT 1999 >Closed-Date: >Last-Modified: >Originator: Tim Singletary >Release: FreeBSD 3.2-RELEASE i386 >Organization: >Environment: >Description: There are no man pages for the widely used dbm_* functions in libc >How-To-Repeat: >Fix: Apply the following patch to src/lib/libc/db/man: diff -cP org/Makefile.inc new/Makefile.inc *** org/Makefile.inc Wed Jul 7 18:11:34 1999 --- new/Makefile.inc Wed Jul 7 18:13:28 1999 *************** *** 4,10 **** .PATH: ${.CURDIR}/../libc/db/man .if ${LIB} == "c" ! MAN3+= btree.3 dbopen.3 hash.3 mpool.3 recno.3 MLINKS+= dbopen.3 db.3 .endif --- 4,20 ---- .PATH: ${.CURDIR}/../libc/db/man .if ${LIB} == "c" ! 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 -cP org/dbm.3 new/dbm.3 *** org/dbm.3 Wed Dec 31 19:00:00 1969 --- new/dbm.3 Wed Jul 7 18:11:51 1999 *************** *** 0 **** --- 1,198 ---- + .\" 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. + .\" + .\" 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 + .Fd #include + .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. + + >Release-Note: >Audit-Trail: >Unformatted: To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message