[BACK]Return to getcap.3 CVS log [TXT][DIR] Up to [cvs.NetBSD.org] / src / lib / libc / gen

Please note that diffs are not public domain; they are subject to the copyright notices on the relevant files.

Diff for /src/lib/libc/gen/Attic/getcap.3 between version 1.9 and 1.10

version 1.9, 1998/04/28 20:11:34 version 1.10, 1998/04/29 19:12:09
Line 37 
Line 37 
 .\"     @(#)getcap.3    8.4 (Berkeley) 5/13/94  .\"     @(#)getcap.3    8.4 (Berkeley) 5/13/94
 .\"  .\"
 .Dd May 13, 1994  .Dd May 13, 1994
 .Dt GETCAP 3  .Dt GETCAP 3
 .Os  .Os
 .Sh NAME  .Sh NAME
 .Nm cgetent ,  .Nm cgetent ,
Line 76 
Line 76 
 .Ft int  .Ft int
 .Fn cgetclose "void"  .Fn cgetclose "void"
 .Sh DESCRIPTION  .Sh DESCRIPTION
 .Fn Cgetent  .Fn cgetent
 extracts the capability  extracts the capability
 .Fa name  .Fa name
 from the database specified by the  from the database specified by the
Line 86  terminated file array
Line 86  terminated file array
 and returns a pointer to a  and returns a pointer to a
 .Xr malloc 3 Ns \&'d  .Xr malloc 3 Ns \&'d
 copy of it in  copy of it in
 .Fa buf .  .Fa buf .
 .Nm Cgetent  .Fn cgetent
 will first look for files ending in  will first look for files ending in
 .Nm .db  .Pa .db
 (see  (see
 .Xr cap_mkdb 1 )  .Xr cap_mkdb 1 )
 before accessing the ASCII file.  before accessing the
 .Fa Buf  .Tn ASCII
   file.
   .Pp
   .Fa buf
 must be retained through all subsequent calls to  must be retained through all subsequent calls to
 .Fn cgetmatch ,  .Fn cgetmatch ,
 .Fn cgetcap ,  .Fn cgetcap ,
Line 103  and
Line 106  and
 .Fn cgetustr ,  .Fn cgetustr ,
 but may then be  but may then be
 .Xr free 3 Ns \&'d.  .Xr free 3 Ns \&'d.
 On success 0 is returned, 1 if the returned  .Pp
 record contains an unresolved  On success 0 is returned, 1 if the returned record contains an unresolved
 .Nm tc  .Qq tc
 expansion,  expansion, \-1 if the requested record couldn't be found, \-2 if
 \-1 if the requested record couldn't be found,  a system error was encountered (couldn't open/read a file, etc.)
 \-2 if a system error was encountered (couldn't open/read a file, etc.) also  also setting
 setting  .Va errno ,
 .Va errno ,  
 and \-3 if a potential reference loop is detected (see  and \-3 if a potential reference loop is detected (see
 .Ic tc=  .Qq tc=name
 comments below).  comments below).
 .Pp  .Pp
 .Nm Cgetset  .Fn cgetset
 enables the addition of a character buffer containing a single capability  enables the addition of a character buffer containing a single capability
 record entry  record entry to the capability database.
 to the capability database.  
 Conceptually, the entry is added as the first ``file'' in the database, and  Conceptually, the entry is added as the first ``file'' in the database, and
 is therefore searched first on the call to  is therefore searched first on the call to
 .Nm cgetent .  .Fn cgetent .
 The entry is passed in  The entry is passed in
 .Fa ent .  .Fa ent .
 If  If
 .Fa ent  .Fa ent
 is  is
 .Dv NULL ,  .Dv NULL ,
 the current entry is removed from the database.  the current entry is removed from the database.
 .Nm Cgetset  .Pp
 must precede the database traversal.  It must be called before the  .Fn cgetset
 .Nm cgetent  must precede the database traversal.
 call. If a sequential access is being performed (see below), it must be called  It must be called before the
 before the first sequential access call (  .Fn cgetent
 .Nm cgetfirst  call.
   If a sequential access is being performed (see below), it must be called
   before the first sequential access call
   .Po
   .Fn cgetfirst
 or  or
 .Nm cgetnext  .Fn cgetnext
 ), or be directly preceded by a  .Pc ,
 .Nm cgetclose  or be directly preceded by a
   .Fn cgetclose
 call.  call.
 On success 0 is returned and \-1 on failure.  On success 0 is returned and \-1 on failure.
 .Pp  .Pp
 .Nm Cgetmatch  .Fn cgetmatch
 will return 0 if  will return 0 if
 .Fa name  .Fa name
 is one of the names of the capability record  is one of the names of the capability record
 .Fa buf ,  .Fa buf ,
 \-1 if  \-1 if not.
 not.  
 .Pp  .Pp
 .Nm Cgetcap  .Fn cgetcap
 searches the capability record  searches the capability record
 .Fa buf  .Fa buf
 for the capability  for the capability
Line 159  with type
Line 164  with type
 .Fa type .  .Fa type .
 A  A
 .Fa type  .Fa type
 is specified using any single character.  If a colon (`:') is used, an  is specified using any single character.
 untyped capability will be searched for (see below for explanation of  If a colon (`:') is used, an untyped capability will be searched
 types).  A pointer to the value of  for (see below for explanation of types).
   A pointer to the value of
 .Fa cap  .Fa cap
 in  in
 .Fa buf  .Fa buf
 is returned on success,  is returned on success,
 .Dv NULL  .Dv NULL
 if the requested capability couldn't be  if the requested capability couldn't be found.
 found.  The end of the capability value is signaled by a `:' or  The end of the capability value is signaled by a `:' or
 .Tn ASCII  .Tn ASCII
 .Dv NUL  .Dv NUL
 (see below for capability database syntax).  (see below for capability database syntax).
 .Pp  .Pp
 .Nm Cgetnum  .Fn cgetnum
 retrieves the value of the numeric capability  retrieves the value of the numeric capability
 .Fa cap  .Fa cap
 from the capability record pointed to by  from the capability record pointed to by
Line 182  The numeric value is returned in the
Line 188  The numeric value is returned in the
 .Ft long  .Ft long
 pointed to by  pointed to by
 .Fa num .  .Fa num .
 0 is returned on success, \-1 if the requested numeric capability couldn't  0 is returned on success,
 be found.  \-1 if the requested numeric capability couldn't be found.
 .Pp  .Pp
 .Nm Cgetstr  .Fn cgetstr
 retrieves the value of the string capability  retrieves the value of the string capability
 .Fa cap  .Fa cap
 from the capability record pointed to by  from the capability record pointed to by
Line 204  is returned on success, \-1 if the reque
Line 210  is returned on success, \-1 if the reque
 be found, \-2 if a system error was encountered (storage allocation  be found, \-2 if a system error was encountered (storage allocation
 failure).  failure).
 .Pp  .Pp
 .Nm Cgetustr  .Fn cgetustr
 is identical to  is identical to
 .Nm cgetstr  .Fn cgetstr
 except that it does not expand special characters, but rather returns each  except that it does not expand special characters, but rather returns each
 character of the capability string literally.  character of the capability string literally.
 .Pp  .Pp
 .Nm Cgetfirst ,  .Fn cgetfirst ,
 .Nm cgetnext ,  .Fn cgetnext ,
 comprise a function group that provides for sequential  comprise a function group that provides for sequential access of the
 access of the  
 .Dv NULL  .Dv NULL
 pointer terminated array of file names,  pointer terminated array of file names,
 .Fa db_array .  .Fa db_array .
 .Nm Cgetfirst  .Fn cgetfirst
 returns the first record in the database and resets the access  returns the first record in the database and resets the access
 to the first record.  to the first record.
 .Nm Cgetnext  .Fn cgetnext
 returns the next record in the database with respect to the  returns the next record in the database with respect to the
 record returned by the previous  record returned by the previous
 .Nm cgetfirst  .Fn cgetfirst
 or  or
 .Nm cgetnext  .Fn cgetnext
 call.  If there is no such previous call, the first record in the database is  call.
 returned.  If there is no such previous call,
   the first record in the database is returned.
 Each record is returned in a  Each record is returned in a
 .Xr malloc 3 Ns \&'d  .Xr malloc 3 Ns \&'d
 copy pointed to by  copy pointed to by
 .Fa buf .  .Fa buf .
 .Ic Tc  .Qq tc
 expansion is done (see  expansion is done (see
 .Ic tc=  .Qq tc=name
 comments below).  comments below).
   .Pp
 Upon completion of the database 0 is returned,  1 is returned upon successful  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  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  expansion, \-1 is returned if an system error occurred, and \-2
 is returned if a potential reference loop is detected (see  is returned if a potential reference loop is detected (see
 .Ic tc=  .Qq tc=name
 comments below).  comments below).
 Upon completion of database (0 return) the database is closed.  Upon completion of database (0 return) the database is closed.
 .Pp  .Pp
 .Nm Cgetclose  .Fn cgetclose
 closes the sequential access and frees any memory and file descriptors  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.
 .Nm cgetset .  Note that it does not erase the buffer pushed by a call to
   .Fn cgetset .
 .Sh CAPABILITY DATABASE SYNTAX  .Sh CAPABILITY DATABASE SYNTAX
 Capability databases are normally  Capability databases are normally
 .Tn ASCII  .Tn ASCII
 and may be edited with standard  and may be edited with standard text editors.
 text editors.  Blank lines and lines beginning with a `#' are comments  Blank lines and lines beginning with a `#' are comments and are ignored.
 and are ignored.  Lines ending with a `\|\e' indicate that the next line  Lines ending with a `\|\e' indicate that the next line is a continuation
 is a continuation of the current line; the `\|\e' and following newline  of the current line; the `\|\e' and following newline are ignored.
 are ignored.  Long lines are usually continued onto several physical  Long lines are usually continued onto several physical
 lines by ending each line except the last with a `\|\e'.  lines by ending each line except the last with a `\|\e'.
 .Pp  .Pp
 Capability databases consist of a series of records, one per logical  Capability databases consist of a series of records, one per logical line.
 line.  Each record contains a variable number of `:'-separated fields  Each record contains a variable number of `:'-separated fields (capabilities).
 (capabilities).  Empty fields consisting entirely of white space  Empty fields consisting entirely of white space
 characters (spaces and tabs) are ignored.  characters (spaces and tabs) are ignored.
 .Pp  .Pp
 The first capability of each record specifies its names, separated by `|'  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  .Em vt100
 record from the  record from the
 .Nm termcap  .Pa termcap
 database begins:  database begins:
 .Pp  .Pp
 .Dl "d0\||\|vt100\||\|vt100-am\||\|vt100am\||\|dec vt100:"  .Dl "d0\||\|vt100\||\|vt100-am\||\|vt100am\||\|dec vt100:"
Line 293  has value
Line 303  has value
 does not exist  does not exist
 .El  .El
 .Pp  .Pp
 Names consist of one or more characters.  Names may contain any character  Names consist of one or more characters.
 except `:', but it's usually best to restrict them to the printable  Names may contain any character except `:', but it's usually best
 characters and avoid use of graphics like `#', `=', `%', `@', etc.  Types  to restrict them to the printable characters and avoid use of
 are single characters used to separate capability names from their  graphics like `#', `=', `%', `@', etc.
 associated typed values.  Types may be any character except a `:'.  .Pp
 Typically, graphics like `#', `=', `%', etc. are used.  Values may be any  Types are single characters used to separate capability names from
 number of characters and may contain any character except `:'.  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  .Sh CAPABILITY DATABASE SEMANTICS
 Capability records describe a set of (name, value) bindings.  Names may  Capability records describe a set of (name, value) bindings.
 have multiple values bound to them.  Different values for a name are  Names may have multiple values bound to them.
 distinguished by their  Different values for a name are distinguished by their
 .Fa types .  .Fa types .
 .Nm Cgetcap  .Fn cgetcap
 will return a pointer to a value of a name given the capability name and  will return a pointer to a value of a name given the capability name and
 the type of the value.  the type of the value.
 .Pp  .Pp
 The types `#' and `=' are conventionally used to denote numeric and  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.
 functions  The functions
 .Nm cgetnum  .Fn cgetnum
 and  and
 .Nm cgetstr  .Fn cgetstr
 can be used to implement the traditional syntax and semantics of `#'  can be used to implement the traditional syntax and semantics of `#' and `='.
 and `='.  
 Typeless capabilities are typically used to denote boolean objects with  Typeless capabilities are typically used to denote boolean objects with
 presence or absence indicating truth and false values respectively.  presence or absence indicating truth and false values respectively.
 This interpretation is conveniently represented by:  This interpretation is conveniently represented by:
Line 324  This interpretation is conveniently repr
Line 336  This interpretation is conveniently repr
 .Dl "(getcap(buf, name, ':') != NULL)"  .Dl "(getcap(buf, name, ':') != NULL)"
 .Pp  .Pp
 A special capability,  A special capability,
 .Ic tc= name ,  .Qq tc=name ,
 is used to indicate that the record specified by  is used to indicate that the record specified by
 .Fa name  .Fa name
 should be substituted for the  should be substituted for the
 .Ic tc  .Qq tc
 capability.  capability.
 .Ic Tc  .Qq tc
 capabilities may interpolate records which also contain  capabilities may interpolate records which also contain
 .Ic tc  .Qq tc
 capabilities and more than one  capabilities and more than one
 .Ic tc  .Qq tc
 capability may be used in a record.  A  capability may be used in a record.
 .Ic tc  A
 expansion scope (i.e., where the argument is searched for) contains the  .Qq tc
   expansion scope (i.e. where the argument is searched for) contains the
 file in which the  file in which the
 .Ic tc  .Qq tc
 is declared and all subsequent files in the file array.  is declared and all subsequent files in the file array.
 .Pp  .Pp
 When a database is searched for a capability record, the first matching  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.
 capability, the first matching capability is returned; the capability  When a record is scanned for a capability, the first matching
 .Ic :nameT@:  capability is returned; the capability
   .Qq :nameT@:
 will hide any following definition of a value of type  will hide any following definition of a value of type
 .Em T  .Em T
 for  for
 .Fa name ;  .Fa name ;
 and the capability  and the capability
 .Ic :name@:  .Qq :name@:
 will prevent any following values of  will prevent any following values of
 .Fa name  .Fa name
 from being seen.  from being seen.
 .Pp  .Pp
 These features combined with  These features combined with
 .Ic tc  .Qq tc
 capabilities can be used to generate variations of other databases and  capabilities can be used to generate variations of other databases and
 records by either adding new capabilities, overriding definitions with new  records by either adding new capabilities, overriding definitions with new
 definitions, or hiding following definitions via `@' capabilities.  definitions, or hiding following definitions via `@' capabilities.
Line 369  example\||\|an example of binding multip
Line 383  example\||\|an example of binding multip
         :tc=more:          :tc=more:
 .Ed  .Ed
 .Pp  .Pp
 The capability foo has two values bound to it (bar of type `%' and blah of  The capability
 type `^') and any other value bindings are hidden.  The capability abc  .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  also has two values bound but only a value of type `$' is prevented from
 being defined in the capability record more.  being defined in the capability record more.
 .Pp  .Pp
Line 384  file2:
Line 408  file2:
 .Ed  .Ed
 .Pp  .Pp
 The records are extracted by calling  The records are extracted by calling
 .Nm cgetent  .Fn cgetent
 with file1 preceding file2.  with
 In the capability record new in file1, fript=bar overrides the definition  .Fa file1
 of fript=foo interpolated from the capability record old in file2,  preceding
 who-cares@ prevents the definition of any who-cares definitions in old  .Fa file2 .
 from being seen, glork#200 is inherited from old, and blah and anything  In the capability record
 defined by the record extensions is added to those definitions in old.  .Em new
 Note that the position of the fript=bar and who-cares@ definitions before  in
 tc=old is important here.  If they were after, the definitions in old  .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.  would take precedence.
 .Sh CGETNUM AND CGETSTR SYNTAX AND SEMANTICS  .Sh CGETNUM AND CGETSTR SYNTAX AND SEMANTICS
 Two types are predefined by  Two types are predefined by
 .Nm cgetnum  .Fn cgetnum
 and  and
 .Nm cgetstr :  .Fn cgetstr :
 .Bl -column "nameXnumber"  .Bl -column "nameXnumber"
 .Sm off  .Sm off
 .It Em name No \&# Em number Ta numeric  .It Em name No \&# Em number Ta numeric
Line 408  has value
Line 460  has value
 .Em number  .Em number
 .It Em name No = Em string Ta "string capability"  .It Em name No = Em string Ta "string capability"
 .Em name  .Em name
 has value  has value
 .Em string  .Em string
 .It Em name No \&#@ Ta "the numeric capability"  .It Em name No \&#@ Ta "the numeric capability"
 .Em name  .Em name
Line 430  Otherwise, if the number starts with a
Line 482  Otherwise, if the number starts with a
 it is interpreted as an octal number.  it is interpreted as an octal number.
 Otherwise the number is interpreted as a decimal number.  Otherwise the number is interpreted as a decimal number.
 .Pp  .Pp
 String capability values may contain any character.  Non-printable  String capability values may contain any character.
   Non-printable
 .Dv ASCII  .Dv ASCII
 codes, new lines, and colons may be conveniently represented by the use  codes, new lines, and colons may be conveniently represented by the use
 of escape sequences:  of escape sequences:
Line 449  of escape sequences:
Line 502  of escape sequences:
 .El  .El
 .Pp  .Pp
 A `\|\e' may be followed by up to three octal digits directly specifies  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  .Tn ASCII
 .Dv NUL Ns s ,  .Dv NUL Ns s ,
 while easily  while easily
Line 459  are typically used to denote the end of 
Line 513  are typically used to denote the end of 
 use `\e\|200' to represent a  use `\e\|200' to represent a
 .Dv NUL .  .Dv NUL .
 .Sh DIAGNOSTICS  .Sh DIAGNOSTICS
 .Nm Cgetent ,  .Fn cgetent ,
 .Nm cgetset ,  .Fn cgetset ,
 .Nm cgetmatch ,  .Fn cgetmatch ,
 .Nm cgetnum ,  .Fn cgetnum ,
 .Nm cgetstr ,  .Fn cgetstr ,
 .Nm cgetustr ,  .Fn cgetustr ,
 .Nm cgetfirst ,  .Fn cgetfirst ,
 and  and
 .Nm cgetnext  .Fn cgetnext
 return a value greater than or equal to 0 on success and a value less  return a value greater than or equal to 0 on success and a value less
 than 0 on failure.  than 0 on failure.
 .Nm Cgetcap  .Fn cgetcap
 returns a character pointer on success and a  returns a character pointer on success and a
 .Dv NULL  .Dv NULL
 on failure.  on failure.
 .Pp  .Pp
 .Nm Cgetent ,  .Fn cgetent ,
 and  and
 .Nm cgetseq  .Fn cgetseq
 may fail and set  may fail and set
 .Va errno  .Va errno
 for any of the errors specified for the library functions:  for any of the errors specified for the library functions:
 .Xr fopen 2 ,  .Xr fopen 3 ,
 .Xr fclose 2 ,  .Xr fclose 3 ,
 .Xr open 2 ,  .Xr open 2 ,
 and  and
 .Xr close 2 .  .Xr close 2 .
 .Pp  .Pp
 .Nm Cgetent ,  .Fn cgetent ,
 .Nm cgetset ,  .Fn cgetset ,
 .Nm cgetstr ,  .Fn cgetstr ,
 and  and
 .Nm cgetustr  .Fn cgetustr
 may fail and set  may fail and set
 .Va errno  .Va errno
 as follows:  as follows:
 .Bl -tag -width Er  .Bl -tag -width Er
 .It Bq Er ENOMEM  .It Bq Er ENOMEM
Line 506  No memory to allocate.
Line 560  No memory to allocate.
 Colons (`:') can't be used in names, types, or values.  Colons (`:') can't be used in names, types, or values.
 .Pp  .Pp
 There are no checks for  There are no checks for
 .Ic tc= name  .Qq tc=name
 loops in  loops in
 .Nm cgetent .  .Fn cgetent .
 .Pp  .Pp
 The buffer added to the database by a call to  The buffer added to the database by a call to
 .Nm cgetset  .Fn cgetset
 is not unique to the database but is rather prepended to any database used.  is not unique to the database but is rather prepended to any database used.

Legend:
Removed from v.1.9  
changed lines
  Added in v.1.10

CVSweb <webmaster@jp.NetBSD.org>