authcap(S)                     6 January 1993                     authcap(S)


 Name

    authcap - get information from the authentication database

 Syntax


    cc  . . .  -lprot -lx


    #include  <sys/types.h>
    #include  <sys/security.h>
    #include  <sys/audit.h>
    #include  <prot.h>

    int agetcommand (filepos, fd)
    long *filepos;
    int fd;

    int agetdefault (filepos, fd)
    long *filepos;
    int fd;

    int agetfile (filepos, fd)
    long *filepos;
    int fd;

    int agetflag (id)
    char *id;

    int agettty (filepos, fd)
    long *filepos;
    int fd;

    char *agetstr (id, area)
    char *id;
    char **area;

    int agetuser (user)
    char *user;

    void asetdefaults (new_defaults)
    int new_defaults;


 Description

    These routines manage ASCII database files in hierarchies as described in
    authcap(F).  All program references to the database should use these rou-
    tines.  Also, these routines are the ones that understand the authcap
    format and are guaranteed to provide the same interface, even if the
    database format or name designations change.

    agetuser finds the entry associated with the user name argument.
    agetcommand finds the next command entry in the file described by fd
    starting at the file position filepos within the file.  filepos should
    point to the beginning of a valid entry or at the end of the file.  aget-
    file finds the next file entry in the file in the same way as agetcom-
    mand.  Similarly, agettty finds the next tty entry in the file in the
    same way as agetcommand.  Tty names are the components without the /dev
    part.  Example tty names in the database are console, and tty3.  agetde-
    fault finds the next default entry in the file in the same way as
    agetcommand.

    Each of the above routines returns a status indicator.  A return value of
    ``1'' means the entry was found.  A return value of 0 means the entry was
    not found in the file.  The calls with the filepos argument may update
    the position referenced by filepos.

    Once one of the above routines obtains an entry, the next three routines
    obtain capabilities from that most recently chosen entry.  agetstr
    returns the string associated with the id argument.  The place the string
    goes is referenced by the area argument.  Not the area argument is a
    pointer to an allocated string, not merely a string.  The 0 pointer
    ((char *) 0) is returned when the capability cannot be found.  A null
    string is returned as an empty string (**area == '\0').  agetflag returns
    the flag associated with the id argument.  If the flag is set, ``1'' is
    returned.  If the flag is not set (the ``@'' attribute appears with the
    id in the file), ``0'' is returned.  If the capability flag cannot be
    found at all (different from not set), ``-1'' is returned.

    asetdefaults changes the database used to find system defaults.  It can
    be set to one of the following values for all system references to the
    database until it is reset again by asetdefaults.  Initially it is NOR-
    MAL, where system values are found in the site-selectable part of the
    database.  The value WEAK uses an insecure version, while the value
    STRONG uses a secure version of the system-wide values.  When none of
    these values is used, the value STRONG is used.

 Notes

    agetuser, agetcommand, agetfile, agettty and agetdefault make use of
    static areas for an entry.  Successive calls to any of these routines
    overwrites data that is used by later calls to agetstr and agetflag.

 See also

    authcap(F), fields(S), getprfient(S), getprpwent(S), getprtcent(S)

 Standards conformance

    authcap is an extension of AT&T System V provided by the Santa Cruz
    Operation.