docs: Added All NetBSD Manuals

1 files changed, 373 insertions, 0 deletions

diff --git a/static/netbsd/man3/cgetcap.3 b/static/netbsd/man3/cgetcap.3
new file mode 100644
index 00000000..152d7afa
--- /dev/null
+++ b/static/netbsd/man3/cgetcap.3
@@ -0,0 +1,373 @@
+.\"	$NetBSD: cgetcap.3,v 1.10 2022/12/04 01:29:32 uwe 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 5, 2012
+.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 ,
+.Nm csetexpandtc
+.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"
+.Ft void
+.Fn csetexpandtc "int expandtc"
+.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 \&: .
+See
+.Xr capfile 5
+for a description of the capability 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 SEMANTICS
+Capability records describe a set of (name, value) bindings.
+Names may have multiple values bound to them.
+Different values for a name are distinguished by their
+.Fa types .
+.Fn cgetcap
+will return a pointer to a value of a name given the capability name and
+the type of the value.
+.Pp
+The types
+.Sq #
+and
+.Sq =
+are conventionally used to denote numeric and
+string typed values, but no restriction on those types is enforced.
+The functions
+.Fn cgetnum
+and
+.Fn cgetstr
+can be used to implement the traditional syntax and semantics of
+.Sq #
+and
+.Sq = .
+Typeless capabilities are typically used to denote boolean objects with
+presence or absence indicating truth and false values respectively.
+This interpretation is conveniently represented by:
+.Pp
+.Dl "(getcap(buf, name, ':') != NULL)"
+.Pp
+A special capability,
+.Qq tc=name ,
+is used to indicate that the record specified by
+.Fa name
+should be substituted for the
+.Qq tc
+capability.
+.Qq tc
+capabilities may interpolate records which also contain
+.Qq tc
+capabilities and more than one
+.Qq tc
+capability may be used in a record.
+A
+.Qq tc
+expansion scope (i.e. where the argument is searched for) contains the
+file in which the
+.Qq tc
+is declared and all subsequent files in the file array.
+.Pp
+.Fn csetexpandtc
+can be used to control if
+.Qq tc
+expansion is performed or not.
+.Sh RETURN VALUES
+.Fn cgetent ,
+.Fn cgetset ,
+.Fn cgetmatch ,
+.Fn cgetnum ,
+.Fn cgetstr ,
+.Fn cgetustr ,
+.Fn cgetfirst ,
+and
+.Fn cgetnext
+return a value greater than or equal to 0 on success and a value less
+than 0 on failure.
+.Fn cgetcap
+returns a character pointer on success and a
+.Dv NULL
+on failure.
+.Pp
+.Fn cgetclose ,
+.Fn cgetent ,
+.Fn cgetfirst ,
+and
+.Fn cgetnext
+may fail and set
+.Va errno
+for any of the errors specified for the library functions:
+.Xr fopen 3 ,
+.Xr fclose 3 ,
+.Xr open 2 ,
+and
+.Xr close 2 .
+.Pp
+.Fn cgetent ,
+.Fn cgetset ,
+.Fn cgetstr ,
+and
+.Fn cgetustr
+may fail and set
+.Va errno
+as follows:
+.Bl -tag -width Er
+.It Bq Er ENOMEM
+No memory to allocate.
+.El
+.Sh SEE ALSO
+.Xr cap_mkdb 1 ,
+.Xr malloc 3 ,
+.Xr capfile 5
+.Sh BUGS
+There are no checks for
+.Qq tc=name
+loops in
+.Fn cgetent .
+.Pp
+The buffer added to the database by a call to
+.Fn cgetset
+is not unique to the database but is rather prepended to any database used.