src/lib/libc/gen/getcap.3 - diff

Return to getcap.3 CVS log

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

.\" @(#)getcap.3 8.4 (Berkeley) 5/13/94

.\"

.Dd May 13, 1994

.Dt GETCAP 3

.Os

.Sh NAME

.Nm cgetent ,

Line 76

.Ft int

.Fn cgetclose "void"

.Sh DESCRIPTION

.Fn Cgetent

.Fn cgetent

extracts the capability

.Fa name

from the database specified by the

Line 86 terminated file array

and returns a pointer to a

.Xr malloc 3 Ns \&'d

copy of it in

.Fa buf .

.Nm Cgetent

.Fn cgetent

will first look for files ending in

.Nm .db

.Pa .db

(see

.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

.Fn cgetmatch ,

.Fn cgetcap ,

Line 103 and

Line 106 and

.Fn cgetustr ,

but may then be

.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 ,

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

record entry to the capability database.

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 .

.Fn cgetent .

The entry is passed in

.Fa ent .

.Fa ent

.Dv NULL ,

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

.Nm cgetnext

.Fn cgetnext

), or be directly preceded by a

.Pc ,

.Nm cgetclose

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

\-1 if not.

not.

.Pp

.Nm Cgetcap

.Fn cgetcap

searches the capability record

.Fa buf

for the capability

Line 159 with type

Line 164 with type

.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 buf

is returned on success,

.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

.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

Line 182 The numeric value is returned in the

Line 188 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

0 is returned on success,

be found.

\-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

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

failure).

.Pp

.Nm Cgetustr

.Fn cgetustr

is identical to

.Nm cgetstr

.Fn cgetstr

except that it does not expand special characters, but rather returns each

character of the capability string literally.

.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

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

.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

.Xr malloc 3 Ns \&'d

copy pointed to by

.Fa buf .

.Ic Tc

.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

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=

.Qq tc=name

comments below).

Upon completion of database (0 return) the database is closed.

.Pp

.Nm Cgetclose

.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

being used.

.Nm cgetset .

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

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'.

.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.

.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:"

Line 293 has value

Line 303 has value

does not exist

.El

.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

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 .

.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

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

functions

The functions

.Nm cgetnum

.Fn cgetnum

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

presence or absence indicating truth and false values respectively.

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)"

.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

.Qq tc

capability may be used in a record. A

capability may be used in a record.

.Ic tc

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

.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

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

.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.

Line 369 example\||\|an example of binding multip

Line 383 example\||\|an example of binding multip

:tc=more:

.Ed

.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

being defined in the capability record more.

.Pp

Line 384 file2:

Line 408 file2:

.Ed

.Pp

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

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

.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

Line 408 has value

Line 460 has value

.Em number

.It Em name No = Em string Ta "string capability"

.Em name

has value

.Em string

.It Em name No \&#@ Ta "the numeric capability"

.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.

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:

Line 449 of escape sequences:

Line 502 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

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

.Dv NUL .

.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

.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 ,

.Fn cgetent ,

and

.Nm cgetseq

.Fn cgetseq

may fail and set

.Va errno

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 ,

and

.Xr close 2 .

.Pp

.Nm Cgetent ,

.Fn cgetent ,

.Nm cgetset ,

.Fn cgetset ,

.Nm cgetstr ,

.Fn cgetstr ,

and

.Nm cgetustr

.Fn cgetustr

may fail and set

.Va errno

as follows:

.Bl -tag -width Er

.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.

.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

.Fn cgetset

is not unique to the database but is rather prepended to any database used.

CVSweb <webmaster@jp.NetBSD.org>