Libc-1272.250.1.tar.gz

[apple/libc.git] / gen / FreeBSD / getcap.3

diff --git a/gen/FreeBSD/getcap.3 b/gen/FreeBSD/getcap.3
index 1980a09a144d33f13ac556a52275b62d61ca0d48..60c383aeb0f0fd393b8b0708597813a04c551516 100644 (file)
--- a/gen/FreeBSD/getcap.3
+++ b/gen/FreeBSD/getcap.3
@@ -12,10 +12,6 @@
 .\" 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.
 .\" 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. All advertising materials mentioning features or use of this software
-.\"    must display the following acknowledgement:
-.\"    This product includes software developed by the University of
-.\"    California, Berkeley and its contributors.

 .\" 4. 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.
 .\" 4. 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.


@@ -33,9 +29,9 @@
 .\" SUCH DAMAGE.
 .\"
 .\"    @(#)getcap.3    8.4 (Berkeley) 5/13/94
 .\" SUCH DAMAGE.
 .\"
 .\"    @(#)getcap.3    8.4 (Berkeley) 5/13/94

-.\" $FreeBSD: src/lib/libc/gen/getcap.3,v 1.23 2002/12/30 21:18:02 schweikh Exp $
+.\" $FreeBSD: src/lib/libc/gen/getcap.3,v 1.30 2007/02/11 18:14:49 maxim Exp $

 .\"
 .\"

-.Dd May 13, 1994
+.Dd March 22, 2002

 .Dt GETCAP 3
 .Os
 .Sh NAME
 .Dt GETCAP 3
 .Os
 .Sh NAME


@@ -55,19 +51,19 @@
 .Sh SYNOPSIS
 .In stdlib.h
 .Ft int
 .Sh SYNOPSIS
 .In stdlib.h
 .Ft int

-.Fn cgetent "char **buf" "char **db_array" "char *name"
+.Fn cgetent "char **buf" "char **db_array" "const char *name"

 .Ft int
 .Ft int

-.Fn cgetset "char *ent"
+.Fn cgetset "const char *ent"

 .Ft int
 .Ft int

-.Fn cgetmatch "char *buf" "char *name"
+.Fn cgetmatch "const char *buf" "const char *name"

 .Ft char *
 .Ft char *

-.Fn cgetcap "char *buf" "char *cap" "int type"
+.Fn cgetcap "char *buf" "const char *cap" "int type"

 .Ft int
 .Ft int

-.Fn cgetnum "char *buf" "char *cap" "long *num"
+.Fn cgetnum "char *buf" "const char *cap" "long *num"

 .Ft int
 .Ft int

-.Fn cgetstr "char *buf" "char *cap" "char **str"
+.Fn cgetstr "char *buf" "const char *cap" "char **str"

 .Ft int
 .Ft int

-.Fn cgetustr "char *buf" "char *cap" "char **str"
+.Fn cgetustr "char *buf" "const char *cap" "char **str"

 .Ft int
 .Fn cgetfirst "char **buf" "char **db_array"
 .Ft int
 .Ft int
 .Fn cgetfirst "char **buf" "char **db_array"
 .Ft int


@@ -110,8 +106,8 @@ On success 0 is returned, 1 if the returned
 record contains an unresolved
 .Ic tc
 expansion,
 record contains an unresolved
 .Ic 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
+\-1 if the requested record could not be found,
+\-2 if a system error was encountered (could not open/read a file, etc.) also

 setting
 .Va errno ,
 and \-3 if a potential reference loop is detected (see
 setting
 .Va errno ,
 and \-3 if a potential reference loop is detected (see


@@ -135,9 +131,11 @@ is
 the current entry is removed from the database.
 A call to
 .Fn cgetset
 the current entry is removed from the database.
 A call to
 .Fn cgetset

-must precede the database traversal.  It must be called before the
+must precede the database traversal.
+It must be called before the

 .Fn cgetent
 .Fn cgetent

-call. If a sequential access is being performed (see below), it must be called
+call.
+If a sequential access is being performed (see below), it must be called

 before the first sequential access call
 .Fn ( cgetfirst
 or
 before the first sequential access call
 .Fn ( cgetfirst
 or


@@ -166,16 +164,19 @@ with type
 .Fa type .
 A
 .Fa type
 .Fa type .
 A
 .Fa type

-is specified using any single character.  If a colon (`:') is used, an
+is specified using any single character.
+If a colon (`:') is used, an

 untyped capability will be searched for (see below for explanation of
 untyped capability will be searched for (see below for explanation of

-types).  A pointer to the value of
+types).
+A pointer to the value of

 .Fa cap
 in
 .Fa buf
 is returned on success,
 .Dv NULL
 .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 `:' or
+if the requested capability could not be
+found.
+The end of the capability value is signaled by a `:' or

 .Tn ASCII
 .Dv NUL
 (see below for capability database syntax).
 .Tn ASCII
 .Dv NUL
 (see below for capability database syntax).


@@ -190,7 +191,7 @@ The numeric value is returned in the
 .Ft long
 pointed to by
 .Fa num .
 .Ft long
 pointed to by
 .Fa num .

-0 is returned on success, \-1 if the requested numeric capability couldn't
+0 is returned on success, \-1 if the requested numeric capability could not

 be found.
 .Pp
 The
 be found.
 .Pp
 The


@@ -209,7 +210,7 @@ pointed to by
 .Fa str .
 The number of characters in the decoded string not including the trailing
 .Dv NUL
 .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
+is returned on success, \-1 if the requested string capability could not

 be found, \-2 if a system error was encountered (storage allocation
 failure).
 .Pp
 be found, \-2 if a system error was encountered (storage allocation
 failure).
 .Pp


@@ -240,7 +241,8 @@ record returned by the previous
 .Fn cgetfirst
 or
 .Fn cgetnext
 .Fn cgetfirst
 or
 .Fn cgetnext

-call.  If there is no such previous call, the first record in the database is
+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 Ns \&'d
 returned.
 Each record is returned in a
 .Xr malloc 3 Ns \&'d


@@ -250,8 +252,8 @@ copy pointed to by
 expansion is done (see
 .Ic tc=
 comments below).
 expansion is done (see
 .Ic tc=
 comments below).

-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
+Upon completion of the database 0 is returned, 1 is returned upon successful
+return of record with possibly more remaining (we have not reached the end of

 the database yet), 2 is returned if the record contains an unresolved
 .Ic tc
 expansion, \-1 is returned if a system error occurred, and \-2
 the database yet), 2 is returned if the record contains an unresolved
 .Ic tc
 expansion, \-1 is returned if a system error occurred, and \-2


@@ -263,27 +265,35 @@ Upon completion of database (0 return) the database is closed.
 The
 .Fn cgetclose
 function closes the sequential access and frees any memory and file descriptors
 The
 .Fn cgetclose
 function 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
+being used.
+Note that it does not erase the buffer pushed by a call to

 .Fn cgetset .
 .Sh CAPABILITY DATABASE SYNTAX
 Capability databases are normally
 .Tn ASCII
 and may be edited with standard
 .Fn cgetset .
 .Sh CAPABILITY DATABASE SYNTAX
 Capability databases are normally
 .Tn ASCII
 and may be edited with standard

-text editors.  Blank lines and lines beginning with a `#' are comments
-and are ignored.  Lines ending with a `\|\e' indicate that the next line
+text editors.
+Blank lines and lines beginning with a `#' are comments
+and are ignored.
+Lines ending with a `\|\e' indicate that the next line

 is a continuation of the current line; the `\|\e' and following newline
 is a continuation of the current line; the `\|\e' and following newline

-are ignored.  Long lines are usually continued onto several physical
+are ignored.
+Long lines are usually continued onto several physical

 lines by ending each line except the last with a `\|\e'.
 .Pp
 Capability databases consist of a series of records, one per logical
 lines by ending each line except the last with a `\|\e'.
 .Pp
 Capability databases consist of a series of records, one per logical

-line.  Each record contains a variable number of `:'-separated fields
-(capabilities).  Empty fields consisting entirely of white space
+line.
+Each record contains a variable number of `:'-separated fields
+(capabilities).
+Empty fields consisting entirely of white space

 characters (spaces and tabs) are ignored.
 .Pp
 The first capability of each record specifies its names, separated by `|'
 characters (spaces and tabs) are ignored.
 .Pp
 The first capability of each record specifies its names, separated by `|'

-characters.  These names are used to reference records in the database.
+characters.
+These names are used to reference records in the database.

 By convention, the last name is usually a comment and is not intended as
 By convention, the last name is usually a comment and is not intended as

-a lookup tag.  For example, the
+a lookup tag.
+For example, the

 .Em vt100
 record from the
 .Xr termcap 5
 .Em vt100
 record from the
 .Xr termcap 5


@@ -308,16 +318,22 @@ has value
 does not exist
 .El
 .Pp
 does not exist
 .El
 .Pp

-Names consist of one or more characters.  Names may contain any character
-except `:', but it's usually best to restrict them to the printable
-characters and avoid use of graphics like `#', `=', `%', `@', etc.  Types
+Names consist of one or more characters.
+Names may contain any character
+except `:', but it is usually best to restrict them to the printable
+characters and avoid use of graphics like `#', `=', `%', `@', etc.
+Types

 are single characters used to separate capability names from their
 are single characters used to separate capability names from their

-associated typed values.  Types may be any character except a `:'.
-Typically, graphics like `#', `=', `%', etc. are used.  Values may be any
+associated typed values.
+Types may be any character except a `:'.
+Typically, graphics like `#', `=', `%', etc.\& are used.
+Values may be any

 number of characters and may contain any character except `:'.
 .Sh CAPABILITY DATABASE SEMANTICS
 number of characters and may contain any character except `:'.
 .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
+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 .
 The
 distinguished by their
 .Fa types .
 The


@@ -326,7 +342,8 @@ function will return a pointer to a value of a name given the capability
 name and the type of the value.
 .Pp
 The types `#' and `=' are conventionally used to denote numeric and
 name and the type of the value.
 .Pp
 The types `#' and `=' are conventionally used to denote numeric and

-string typed values, but no restriction on those types is enforced.  The
+string typed values, but no restriction on those types is enforced.
+The

 functions
 .Fn cgetnum
 and
 functions
 .Fn cgetnum
 and


@@ -351,7 +368,8 @@ capabilities may interpolate records which also contain
 .Ic tc
 capabilities and more than one
 .Ic tc
 .Ic tc
 capabilities and more than one
 .Ic tc

-capability may be used in a record.  A
+capability may be used in a record.
+A

 .Ic tc
 expansion scope (i.e., where the argument is searched for) contains the
 file in which the
 .Ic tc
 expansion scope (i.e., where the argument is searched for) contains the
 file in which the


@@ -359,7 +377,8 @@ file in which the
 is declared and all subsequent files in the file array.
 .Pp
 When a database is searched for a capability record, the first matching
 is declared and all subsequent files in the file array.
 .Pp
 When a database is searched for a capability record, the first matching

-record in the search is returned.  When a record is scanned for a
+record in the search is returned.
+When a record is scanned for a

 capability, the first matching capability is returned; the capability
 .Ic :nameT@:
 will hide any following definition of a value of type
 capability, the first matching capability is returned; the capability
 .Ic :nameT@:
 will hide any following definition of a value of type


@@ -386,7 +405,8 @@ example\||\|an example of binding multiple values to names:\e
 .Ed
 .Pp
 The capability foo has two values bound to it (bar of type `%' and blah of
 .Ed
 .Pp
 The capability foo has two values bound to it (bar of type `%' and blah of

-type `^') and any other value bindings are hidden.  The capability abc
+type `^') and any other value bindings are hidden.
+The capability abc

 also has two values bound but only a value of type `$' is prevented from
 being defined in the capability record more.
 .Pp
 also has two values bound but only a value of type `$' is prevented from
 being defined in the capability record more.
 .Pp


@@ -408,7 +428,8 @@ who-cares@ prevents the definition of any who-cares definitions in old
 from being seen, glork#200 is inherited from old, and blah and anything
 defined by the record extensions is added to those definitions in old.
 Note that the position of the fript=bar and who-cares@ definitions before
 from being seen, glork#200 is inherited from old, and blah and anything
 defined by the record extensions is added to those definitions in old.
 Note that the position of the fript=bar and who-cares@ definitions before

-tc=old is important here.  If they were after, the definitions in old
+tc=old is important here.
+If they were after, the definitions in old

 would take precedence.
 .Sh CGETNUM AND CGETSTR SYNTAX AND SEMANTICS
 Two types are predefined by
 would take precedence.
 .Sh CGETNUM AND CGETSTR SYNTAX AND SEMANTICS
 Two types are predefined by


@@ -453,7 +474,8 @@ Otherwise, if the number starts with a
 it is interpreted as an octal number.
 Otherwise the number is interpreted as a decimal number.
 .Pp
 it is interpreted as an octal number.
 Otherwise the number is interpreted as a decimal number.
 .Pp

-String capability values may contain any character.  Non-printable
+String capability values may contain any character.
+Non-printable

 .Dv ASCII
 codes, new lines, and colons may be conveniently represented by the use
 of escape sequences:
 .Dv ASCII
 codes, new lines, and colons may be conveniently represented by the use
 of escape sequences:


@@ -472,7 +494,8 @@ of escape sequences:
 .El
 .Pp
 A `\|\e' may be followed by up to three octal digits directly specifies
 .El
 .Pp
 A `\|\e' may be followed by up to three octal digits directly specifies

-the numeric code for a character.  The use of
+the numeric code for a character.
+The use of

 .Tn ASCII
 .Dv NUL Ns s ,
 while easily
 .Tn ASCII
 .Dv NUL Ns s ,
 while easily


@@ -504,7 +527,7 @@ on failure.
 The
 .Fn cgetent ,
 and
 The
 .Fn cgetent ,
 and

-.Fn cgetseq
+.Fn cgetset

 functions may fail and set
 .Va errno
 for any of the errors specified for the library functions:
 functions may fail and set
 .Va errno
 for any of the errors specified for the library functions:


@@ -532,7 +555,7 @@ No memory to allocate.
 .Xr cap_mkdb 1 ,
 .Xr malloc 3
 .Sh BUGS
 .Xr cap_mkdb 1 ,
 .Xr malloc 3
 .Sh BUGS

-Colons (`:') can't be used in names, types, or values.
+Colons (`:') cannot be used in names, types, or values.

 .Pp
 There are no checks for
 .Ic tc Ns = Ns Ic name
 .Pp
 There are no checks for
 .Ic tc Ns = Ns Ic name