From tsingle@talon.gsfc.nasa.gov Wed Jul  7 17:38:04 1999
Return-Path: <tsingle@talon.gsfc.nasa.gov>
Received: from talon.gsfc.nasa.gov (talon.gsfc.nasa.gov [128.183.221.175])
	by hub.freebsd.org (Postfix) with ESMTP id 63F0115055
	for <FreeBSD-gnats-submit@freebsd.org>; 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
Sender: tsingle@talon.gsfc.nasa.gov
Reply-To: tsingle@triana.gsfc.nasa.gov
To: FreeBSD-gnats-submit@freebsd.org
Subject: no dbm_* man pages
X-Send-Pr-Version: 3.2

>Number:         12557
>Category:       docs
>Synopsis:       There are no man pages for the widely used dbm_* functions in libc
>Confidential:   no
>Severity:       serious
>Priority:       medium
>Responsible:    nik
>State:          closed
>Quarter:        
>Keywords:       
>Date-Required:  
>Class:          doc-bug
>Submitter-Id:   current-users
>Arrival-Date:   Wed Jul  7 17:40:01 PDT 1999
>Closed-Date:    Sun Feb 11 09:24:24 PST 2001
>Last-Modified:  Sun Feb 11 09:27:07 PST 2001
>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 <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.  
+ 
+ 



>Release-Note:
>Audit-Trail:

From: Nik Clayton <nik@nothing-going-on.demon.co.uk>
To: tsingle@triana.gsfc.nasa.gov
Cc: FreeBSD-gnats-submit@freebsd.org
Subject: Re: docs/12557: no dbm_* man pages
Date: Thu, 8 Jul 1999 22:23:51 +0100

 Tim,
 
 On Wed, Jul 07, 1999 at 08:38:37PM -0400, tsingle@triana.gsfc.nasa.gov wrote:
 > >Synopsis:       There are no man pages for the widely used dbm_* functions in libc
 
 <snip>
 
 > >Fix:
 
 <snip>
 
 Thanks.  I've just send a message to hackers@freebsd.org asking interested
 parties who know something about DBM to take a look at these and give them
 the once over.  When that's done I'll commit them ASAP.
 
 Cheers,
 
 N
 -- 
  [intentional self-reference] can be easily accommodated using a blessed,
  non-self-referential dummy head-node whose own object destructor severs
  the links.
     -- Tom Christiansen in <375143b5@cs.colorado.edu>
 
Responsible-Changed-From-To: freebsd-doc->nik 
Responsible-Changed-By: sheldonh 
Responsible-Changed-When: Fri Jul 9 05:15:06 PDT 1999 
Responsible-Changed-Why:  
Nik's taken this one. 

From: Alexander Langer <alex@big.endian.de>
To: FreeBSD-gnats-submit@freebsd.org
Cc:  
Subject: Re: docs/12557: no dbm_* man pages
Date: Wed, 24 May 2000 17:15:12 +0200

 I just took a look at the manpage, and it seems fine (from the
 technical part)
 
 However, the manpage itself should be reworked, imo.
 
 * "normally" appears quite often
 * return values shouldn#t be in the DESCRIPTION
 
 Also, more detailed descriptions for the functions and its arguments
 could be useful.
 
 Alex
 -- 
 I need a new ~/.sig.
 
State-Changed-From-To: open->closed 
State-Changed-By: nik 
State-Changed-When: Sun Feb 11 09:24:24 PST 2001 
State-Changed-Why:  
Committed, thanks (better late than never, and all that). 

http://www.freebsd.org/cgi/query-pr.cgi?pr=12557 
>Unformatted:
