[src/netbsd-3-0]: src/lib/libc/gen Pull up following revision(s) (requested b...

[bouyer <bouyer%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/4fe89ba7bec4
branches:  netbsd-3-0
changeset: 579439:4fe89ba7bec4
user:      bouyer <bouyer%NetBSD.org@localhost>
date:      Sun Aug 26 20:03:26 2007 +0000

description:
Pull up following revision(s) (requested by bad in ticket #1821):
        lib/libc/gen/cgetcap.3: revisions 1.1 - 1.3
        lib/libc/gen/Makefile.inc: revision 1.143
        lib/libc/gen/getcap.3: file removal
Both libcurses and libc installed a getcap(3) manpage, and both used it
as target for a bunch of MLINKS. This had the effect that whatever came
last in install overwrote everything from the other camp.
Solve this by renaming the libc page -- this makes sense because no
function is really named "getcap" here.

diffstat:

 lib/libc/gen/Makefile.inc |   12 +-
 lib/libc/gen/cgetcap.3    |  615 ++++++++++++++++++++++++++++++++++++++++++++++
 lib/libc/gen/getcap.3     |  564 ------------------------------------------
 3 files changed, 621 insertions(+), 570 deletions(-)

diffs (truncated from 1220 to 300 lines):

diff -r d830ff99f942 -r 4fe89ba7bec4 lib/libc/gen/Makefile.inc
--- a/lib/libc/gen/Makefile.inc Sun Aug 26 19:55:21 2007 +0000
+++ b/lib/libc/gen/Makefile.inc Sun Aug 26 20:03:26 2007 +0000
@@ -1,4 +1,4 @@
-#      $NetBSD: Makefile.inc,v 1.140 2005/01/06 15:29:35 lukem Exp $
+#      $NetBSD: Makefile.inc,v 1.140.4.1 2007/08/26 20:03:26 bouyer Exp $
 #      from: @(#)Makefile.inc  8.6 (Berkeley) 5/4/95
 
 # gen sources
@@ -48,7 +48,7 @@
        endutxent.3 err.3 exec.3 extattr.3 \
        fmtcheck.3 fmtmsg.3 fnmatch.3 fpclassify.3 fpgetmask.3 frexp.3 \
        ftok.3 fts.3 \
-       getbsize.3 getcap.3 getcwd.3 getdevmajor.3 \
+       getbsize.3 cgetcap.3 getcwd.3 getdevmajor.3 \
        getdomainname.3 getdiskbyname.3 getfsent.3 \
        getgrent.3 getgrouplist.3 gethostname.3 getlastlogx.3 getloadavg.3 \
        getmntinfo.3 getnetgrent.3 getpagesize.3 getpass.3 \
@@ -86,10 +86,10 @@
        fpgetmask.3 fpsetsticky.3
 MLINKS+=fts.3 fts_open.3 fts.3 fts_read.3 fts.3 fts_children.3 \
        fts.3 fts_set.3 fts.3 fts_close.3
-MLINKS+=getcap.3 cgetcap.3 getcap.3 cgetclose.3 getcap.3 cgetent.3 \
-       getcap.3 cgetfirst.3 getcap.3 cgetmatch.3 getcap.3 cgetnext.3 \
-       getcap.3 cgetnum.3 getcap.3 cgetset.3 getcap.3 cgetstr.3 \
-       getcap.3 cgetustr.3
+MLINKS+=cgetcap.3 cgetclose.3 cgetcap.3 cgetent.3 \
+       cgetcap.3 cgetfirst.3 cgetcap.3 cgetmatch.3 cgetcap.3 cgetnext.3 \
+       cgetcap.3 cgetnum.3 cgetcap.3 cgetset.3 cgetcap.3 cgetstr.3 \
+       cgetcap.3 cgetustr.3
 MLINKS+=getcwd.3 getwd.3
 MLINKS+=getdiskbyname.3 setdisktab.3
 MLINKS+=getdomainname.3 setdomainname.3
diff -r d830ff99f942 -r 4fe89ba7bec4 lib/libc/gen/cgetcap.3
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/lib/libc/gen/cgetcap.3    Sun Aug 26 20:03:26 2007 +0000
@@ -0,0 +1,615 @@
+.\"    $NetBSD: cgetcap.3,v 1.3.14.2 2007/08/26 20:03:26 bouyer Exp $
+.\"
+.\" Copyright (c) 1992, 1993
+.\"    The Regents of the University of California.  All rights reserved.
+.\"
+.\" This code is derived from software contributed to Berkeley by
+.\" Casey Leedom of Lawrence Livermore National Laboratory.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\" 3. Neither the name of the University nor the names of its contributors
+.\"    may be used to endorse or promote products derived from this software
+.\"    without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS 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 REGENTS 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.
+.\"
+.\"    @(#)getcap.3    8.4 (Berkeley) 5/13/94
+.\"
+.Dd April 23, 2004
+.Dt CGETCAP 3
+.Os
+.Sh NAME
+.Nm cgetent ,
+.Nm cgetset ,
+.Nm cgetmatch ,
+.Nm cgetcap ,
+.Nm cgetnum ,
+.Nm cgetstr ,
+.Nm cgetustr ,
+.Nm cgetfirst ,
+.Nm cgetnext ,
+.Nm cgetclose
+.Nd capability database access routines
+.Sh LIBRARY
+.Lb libc
+.Sh SYNOPSIS
+.In stdlib.h
+.Ft int
+.Fn cgetent "char **buf" "const char * const *db_array" "const char *name"
+.Ft int
+.Fn cgetset "const char *ent"
+.Ft int
+.Fn cgetmatch "const char *buf" "const char *name"
+.Ft char *
+.Fn cgetcap "char *buf" "const char *cap" "int type"
+.Ft int
+.Fn cgetnum "char *buf" "const char *cap" "long *num"
+.Ft int
+.Fn cgetstr "char *buf" "const char *cap" "char **str"
+.Ft int
+.Fn cgetustr "char *buf" "const char *cap" "char **str"
+.Ft int
+.Fn cgetfirst "char **buf" "const char * const *db_array"
+.Ft int
+.Fn cgetnext "char **buf" "const char * const *db_array"
+.Ft int
+.Fn cgetclose "void"
+.Sh DESCRIPTION
+.Fn cgetent
+extracts the capability
+.Fa name
+from the database specified by the
+.Dv NULL
+terminated file array
+.Fa db_array
+and returns a pointer to a
+.Xr malloc 3 Ap d
+copy of it in
+.Fa buf .
+.Fn cgetent
+will first look for files ending in
+.Pa .db
+(see
+.Xr cap_mkdb 1 )
+before accessing the
+.Tn ASCII
+file.
+.Pp
+.Fa buf
+must be retained through all subsequent calls to
+.Fn cgetmatch ,
+.Fn cgetcap ,
+.Fn cgetnum ,
+.Fn cgetstr ,
+and
+.Fn cgetustr ,
+but may then be
+.Xr free 3 Ap d .
+.Pp
+On success 0 is returned, 1 if the returned record contains an unresolved
+.Qq tc
+expansion, \-1 if the requested record couldn't be found, \-2 if
+a system error was encountered (couldn't open/read a file, etc.)
+also setting
+.Va errno ,
+and \-3 if a potential reference loop is detected (see
+.Qq tc=name
+comments below).
+.Pp
+.Fn cgetset
+enables the addition of a character buffer containing a single capability
+record entry to the capability database.
+Conceptually, the entry is added as the first
+.Dq file
+in the database, and
+is therefore searched first on the call to
+.Fn cgetent .
+The entry is passed in
+.Fa ent .
+If
+.Fa ent
+is
+.Dv NULL ,
+the current entry is removed from the database.
+.Pp
+.Fn cgetset
+must precede the database traversal.
+It must be called before the
+.Fn cgetent
+call.
+If a sequential access is being performed (see below), it must be called
+before the first sequential access call
+.Po
+.Fn cgetfirst
+or
+.Fn cgetnext
+.Pc ,
+or be directly preceded by a
+.Fn cgetclose
+call.
+On success 0 is returned and \-1 on failure.
+.Pp
+.Fn cgetmatch
+will return 0 if
+.Fa name
+is one of the names of the capability record
+.Fa buf ,
+\-1 if not.
+.Pp
+.Fn cgetcap
+searches the capability record
+.Fa buf
+for the capability
+.Fa cap
+with type
+.Fa type .
+A
+.Fa type
+is specified using any single character.
+If a colon
+.Pq Sq \&:
+is used, an untyped capability will be searched
+for (see below for explanation of types).
+A pointer to the value of
+.Fa cap
+in
+.Fa buf
+is returned on success,
+.Dv NULL
+if the requested capability couldn't be found.
+The end of the capability value is signaled by a
+.Sq \&:
+or
+.Tn ASCII
+.Dv NUL
+(see below for capability database syntax).
+.Pp
+.Fn cgetnum
+retrieves the value of the numeric capability
+.Fa cap
+from the capability record pointed to by
+.Fa buf .
+The numeric value is returned in the
+.Ft long
+pointed to by
+.Fa num .
+0 is returned on success,
+\-1 if the requested numeric capability couldn't be found.
+.Pp
+.Fn cgetstr
+retrieves the value of the string capability
+.Fa cap
+from the capability record pointed to by
+.Fa buf .
+A pointer to a decoded,
+.Dv NUL
+terminated,
+.Xr malloc 3 Ap d
+copy of the string is returned in the
+.Ft char *
+pointed to by
+.Fa str .
+The number of characters in the decoded string not including the trailing
+.Dv NUL
+is returned on success, \-1 if the requested string capability couldn't
+be found, \-2 if a system error was encountered (storage allocation
+failure).
+.Pp
+.Fn cgetustr
+is identical to
+.Fn cgetstr
+except that it does not expand special characters, but rather returns each
+character of the capability string literally.
+.Pp
+.Fn cgetfirst ,
+.Fn cgetnext ,
+comprise a function group that provides for sequential access of the
+.Dv NULL
+pointer terminated array of file names,
+.Fa db_array .
+.Fn cgetfirst
+returns the first record in the database and resets the access
+to the first record.
+.Fn cgetnext
+returns the next record in the database with respect to the
+record returned by the previous
+.Fn cgetfirst
+or
+.Fn cgetnext
+call.
+If there is no such previous call,
+the first record in the database is returned.
+Each record is returned in a
+.Xr malloc 3 Ap d
+copy pointed to by
+.Fa buf .
+.Qq tc
+expansion is done (see
+.Qq tc=name
+comments below).
+.Pp
+Upon completion of the database 0 is returned,  1 is returned upon successful
+return of record with possibly more remaining (we haven't reached the end of
+the database yet), 2 is returned if the record contains an unresolved
+.Qq tc
+expansion, \-1 is returned if an system error occurred, and \-2
+is returned if a potential reference loop is detected (see
+.Qq tc=name
+comments below).
+Upon completion of database (0 return) the database is closed.
+.Pp
+.Fn cgetclose
+closes the sequential access and frees any memory and file descriptors
+being used.
+Note that it does not erase the buffer pushed by a call to
+.Fn cgetset .
+.Sh CAPABILITY DATABASE SYNTAX