From 0047adf48c858145aea2880678554a056cdfcf93 Mon Sep 17 00:00:00 2001 From: fair Date: Wed, 29 Apr 1998 19:12:09 +0000 Subject: [PATCH] Fix a few bad .Xr's. Nuke rampant abuse of .Nm. Clarify examples through the judicious use of .Qq and .Em. --- lib/libc/gen/getcap.3 | 372 ++++++++++++++++++++++++------------------ 1 file changed, 213 insertions(+), 159 deletions(-) diff --git a/lib/libc/gen/getcap.3 b/lib/libc/gen/getcap.3 index 2a45de3ed201..b84d41038be6 100644 --- a/lib/libc/gen/getcap.3 +++ b/lib/libc/gen/getcap.3 @@ -1,4 +1,4 @@ -.\" $NetBSD: getcap.3,v 1.9 1998/04/28 20:11:34 fair Exp $ +.\" $NetBSD: getcap.3,v 1.10 1998/04/29 19:12:09 fair Exp $ .\" .\" Copyright (c) 1992, 1993 .\" The Regents of the University of California. All rights reserved. @@ -37,7 +37,7 @@ .\" @(#)getcap.3 8.4 (Berkeley) 5/13/94 .\" .Dd May 13, 1994 -.Dt GETCAP 3 +.Dt GETCAP 3 .Os .Sh NAME .Nm cgetent , @@ -76,7 +76,7 @@ .Ft int .Fn cgetclose "void" .Sh DESCRIPTION -.Fn Cgetent +.Fn cgetent extracts the capability .Fa name from the database specified by the @@ -86,14 +86,17 @@ terminated file array and returns a pointer to a .Xr malloc 3 Ns \&'d copy of it in -.Fa buf . -.Nm Cgetent -will first look for files ending in -.Nm .db +.Fa buf . +.Fn cgetent +will first look for files ending in +.Pa .db (see .Xr cap_mkdb 1 ) -before accessing the ASCII file. -.Fa Buf +before accessing the +.Tn ASCII +file. +.Pp +.Fa buf must be retained through all subsequent calls to .Fn cgetmatch , .Fn cgetcap , @@ -103,54 +106,56 @@ and .Fn cgetustr , but may then be .Xr free 3 Ns \&'d. -On success 0 is returned, 1 if the returned -record contains an unresolved -.Nm 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 , +.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 -.Ic tc= +.Qq tc=name comments below). .Pp -.Nm Cgetset +.Fn cgetset enables the addition of a character buffer containing a single capability -record entry -to the capability database. +record entry to the capability database. Conceptually, the entry is added as the first ``file'' in the database, and -is therefore searched first on the call to -.Nm cgetent . -The entry is passed in +is therefore searched first on the call to +.Fn cgetent . +The entry is passed in .Fa ent . -If -.Fa ent +If +.Fa ent is .Dv NULL , -the current entry is removed from the database. -.Nm Cgetset -must precede the database traversal. It must be called before the -.Nm cgetent -call. If a sequential access is being performed (see below), it must be called -before the first sequential access call ( -.Nm cgetfirst +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 -.Nm cgetnext -), or be directly preceded by a -.Nm cgetclose +.Fn cgetnext +.Pc , +or be directly preceded by a +.Fn cgetclose call. On success 0 is returned and \-1 on failure. .Pp -.Nm Cgetmatch +.Fn cgetmatch will return 0 if .Fa name is one of the names of the capability record .Fa buf , -\-1 if -not. +\-1 if not. .Pp -.Nm Cgetcap +.Fn cgetcap searches the capability record .Fa buf for the capability @@ -159,21 +164,22 @@ with type .Fa type . A .Fa type -is specified using any single character. If a colon (`:') is used, an -untyped capability will be searched for (see below for explanation of -types). A pointer to the value of +is specified using any single character. +If a colon (`:') 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 `:' or +if the requested capability couldn't be found. +The end of the capability value is signaled by a `:' or .Tn ASCII .Dv NUL (see below for capability database syntax). .Pp -.Nm Cgetnum +.Fn cgetnum retrieves the value of the numeric capability .Fa cap from the capability record pointed to by @@ -182,10 +188,10 @@ 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. +0 is returned on success, +\-1 if the requested numeric capability couldn't be found. .Pp -.Nm Cgetstr +.Fn cgetstr retrieves the value of the string capability .Fa cap from the capability record pointed to by @@ -204,74 +210,78 @@ 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 -.Nm Cgetustr -is identical to -.Nm cgetstr +.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 -.Nm Cgetfirst , -.Nm cgetnext , -comprise a function group that provides for sequential -access of the +.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 . -.Nm Cgetfirst +.Fn cgetfirst returns the first record in the database and resets the access to the first record. -.Nm Cgetnext +.Fn cgetnext returns the next record in the database with respect to the record returned by the previous -.Nm cgetfirst +.Fn cgetfirst or -.Nm cgetnext -call. If there is no such previous call, the first record in the database is -returned. +.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 Ns \&'d -copy pointed to by -.Fa buf . -.Ic Tc +.Xr malloc 3 Ns \&'d +copy pointed to by +.Fa buf . +.Qq tc expansion is done (see -.Ic tc= +.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 +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 -.Nm tc +.Qq tc expansion, \-1 is returned if an system error occurred, and \-2 -is returned if a potential reference loop is detected (see -.Ic tc= +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 -.Nm 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 -.Nm cgetset . +.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 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 -is a continuation of the current line; the `\|\e' and following newline -are ignored. Long lines are usually continued onto several physical +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 is a continuation +of the current line; the `\|\e' and following newline 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 -line. Each record contains a variable number of `:'-separated fields -(capabilities). Empty fields consisting entirely of white space +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 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 -a lookup tag. For example, the +a lookup tag. +For example, the .Em vt100 record from the -.Nm termcap +.Pa termcap database begins: .Pp .Dl "d0\||\|vt100\||\|vt100-am\||\|vt100am\||\|dec vt100:" @@ -293,30 +303,32 @@ has value 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 -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 -number of characters and may contain any character except `:'. +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. +.Pp +Types 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 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 -distinguished by their +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 . -.Nm Cgetcap +.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 `#' and `=' are conventionally used to denote numeric and -string typed values, but no restriction on those types is enforced. The -functions -.Nm cgetnum +string typed values, but no restriction on those types is enforced. +The functions +.Fn cgetnum and -.Nm cgetstr -can be used to implement the traditional syntax and semantics of `#' -and `='. +.Fn cgetstr +can be used to implement the traditional syntax and semantics of `#' and `='. 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: @@ -324,40 +336,42 @@ This interpretation is conveniently represented by: .Dl "(getcap(buf, name, ':') != NULL)" .Pp A special capability, -.Ic tc= name , +.Qq tc=name , is used to indicate that the record specified by .Fa name should be substituted for the -.Ic tc +.Qq tc capability. -.Ic Tc +.Qq tc capabilities may interpolate records which also contain -.Ic tc +.Qq tc capabilities and more than one -.Ic tc -capability may be used in a record. A -.Ic tc -expansion scope (i.e., where the argument is searched for) contains the +.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 -.Ic tc +.Qq tc 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 -capability, the first matching capability is returned; the capability -.Ic :nameT@: +record in the search is returned. +When a record is scanned for a capability, the first matching +capability is returned; the capability +.Qq :nameT@: will hide any following definition of a value of type .Em T for .Fa name ; and the capability -.Ic :name@: +.Qq :name@: will prevent any following values of .Fa name from being seen. .Pp These features combined with -.Ic tc +.Qq tc capabilities can be used to generate variations of other databases and records by either adding new capabilities, overriding definitions with new definitions, or hiding following definitions via `@' capabilities. @@ -369,8 +383,18 @@ example\||\|an example of binding multiple values to names:\e :tc=more: .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 +The capability +.Em foo +has two values bound to it +.Po +.Em bar +of type `%' and +.Em blah +of type `^' +.Pc +and any other value bindings are hidden. +The capability +.Em abc also has two values bound but only a value of type `$' is prevented from being defined in the capability record more. .Pp @@ -384,21 +408,49 @@ file2: .Ed .Pp The records are extracted by calling -.Nm cgetent -with file1 preceding file2. -In the capability record new in file1, fript=bar overrides the definition -of fript=foo interpolated from the capability record old in file2, -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 -tc=old is important here. If they were after, the definitions in old +.Fn cgetent +with +.Fa file1 +preceding +.Fa file2 . +In the capability record +.Em new +in +.Fa file1 , +.Qq fript=bar +overrides the definition of +.Qq fript=foo +interpolated from the capability record +.Em old +in +.Fa file2, +.Qq who-cares@ +prevents the definition of any who-cares definitions in +.Em old +from being seen, +.Qq glork#200 +is inherited from +.Em old , +and +.Em blah +and anything defined by the record extensions is added to those +definitions in +.Em old . +Note that the position of the +.Qq fript=bar +and +.Qq who-cares@ +definitions before +.Qq tc=old +is important here. +If they were after, the definitions in +.Em old would take precedence. .Sh CGETNUM AND CGETSTR SYNTAX AND SEMANTICS Two types are predefined by -.Nm cgetnum +.Fn cgetnum and -.Nm cgetstr : +.Fn cgetstr : .Bl -column "nameXnumber" .Sm off .It Em name No \&# Em number Ta numeric @@ -408,7 +460,7 @@ has value .Em number .It Em name No = Em string Ta "string capability" .Em name -has value +has value .Em string .It Em name No \&#@ Ta "the numeric capability" .Em name @@ -430,7 +482,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 -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: @@ -449,7 +502,8 @@ of escape sequences: .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 @@ -459,41 +513,41 @@ are typically used to denote the end of strings; many applications use `\e\|200' to represent a .Dv NUL . .Sh DIAGNOSTICS -.Nm Cgetent , -.Nm cgetset , -.Nm cgetmatch , -.Nm cgetnum , -.Nm cgetstr , -.Nm cgetustr , -.Nm cgetfirst , +.Fn cgetent , +.Fn cgetset , +.Fn cgetmatch , +.Fn cgetnum , +.Fn cgetstr , +.Fn cgetustr , +.Fn cgetfirst , and -.Nm cgetnext +.Fn cgetnext return a value greater than or equal to 0 on success and a value less than 0 on failure. -.Nm Cgetcap +.Fn cgetcap returns a character pointer on success and a .Dv NULL on failure. .Pp -.Nm Cgetent , -and -.Nm cgetseq -may fail and set +.Fn cgetent , +and +.Fn cgetseq +may fail and set .Va errno for any of the errors specified for the library functions: -.Xr fopen 2 , -.Xr fclose 2 , +.Xr fopen 3 , +.Xr fclose 3 , .Xr open 2 , -and +and .Xr close 2 . .Pp -.Nm Cgetent , -.Nm cgetset , -.Nm cgetstr , +.Fn cgetent , +.Fn cgetset , +.Fn cgetstr , and -.Nm cgetustr -may fail and set -.Va errno +.Fn cgetustr +may fail and set +.Va errno as follows: .Bl -tag -width Er .It Bq Er ENOMEM @@ -506,10 +560,10 @@ No memory to allocate. Colons (`:') can't be used in names, types, or values. .Pp There are no checks for -.Ic tc= name +.Qq tc=name loops in -.Nm cgetent . +.Fn cgetent . .Pp -The buffer added to the database by a call to -.Nm cgetset +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.