getut(3C)                                                         getut(3C)

NAME
     getut: getutent, getutid, getutline, pututline, setutent, endutent,
     utmpname - access utmp file entry

SYNOPSIS
     #include <utmp.h>

     struct utmp *getutent(void);

     struct utmp *getutid(const struct utmp *id);

     struct utmp *getutline(const struct utmp *line);

     struct utmp *pututline(const struct utmp *utmp);

     void setutent(void);

     void endutent(void);

     int utmpname(const char *file);

DESCRIPTION
     getutent(), getutid(), getutline(), and pututline() each return a
     pointer to a structure with the following members:

        char    utuser[8];       /* user login name */
        char    utid[4];         /* /sbin/inittab id (usually line #) */
        char    utline[12];      /* device name (console, lnxx) */
        short   utpid;           /* process id */
        short   uttype;          /* type of entry */
        struct  exitstatus {
        } utexit;                /* exit status of a process */
                                  /* marked as DEADPROCESS */
        timet    uttime;        /* time entry was made */

     The structure exitstatus includes the following members:

        short   etermination;    /* termination status */
        short   eexit;           /* exit status */

     getutent() reads in the next entry from a utmp-like file. If the file
     is not already open, the command opens it. If the end of the file is
     reached, getutent() fails.

     getutid() searches forward from the current point in the utmp file
     until it finds an entry with a uttype matching id->uttype if the
     type specified is RUNLVL, BOOTTIME, OLDTIME, or NEWTIME. If the
     type specified in id is INITPROCESS, LOGINPROCESS, USERPROCESS, or
     DEADPROCESS, then getutid() will return a pointer to the first entry
     whose type is one of these four and whose utid field matches
     id->utid. If the end of file is reached without a match, it fails.




Page 1                       Reliant UNIX 5.44                Printed 11/98

getut(3C)                                                         getut(3C)

     getutline() searches forward from the current point in the utmp file
     until it finds an entry of the type LOGINPROCESS or USERPROCESS that
     also has a utline string matching the line->utline string. If the
     end of file is reached without a matching entry being found, the com-
     mand fails.

     pututline() writes out the supplied utmp structure into the utmp file.
     It uses getutid() to search forward for the proper place. It is
     expected that normally the user of pututline() will have searched for
     the proper entry using one of the getut() routines. If so, pututline()
     will not search. If pututline() does not find a matching slot for the
     new entry, it will add a new entry to the end of the file. It returns
     a pointer to the utmp structure.

     If the entire file is to be checked, then before starting the search
     for an entry the file pointer must be reset to the beginning of the
     file. This reset should be done before each search for a new entry if
     it is desired that the entire file be examined.

     endutent() closes the open file.

     utmpname() allows the user to change the name of the file examined,
     from /var/adm/utmp to any other file. It is most often expected that
     this other file will be /var/adm/wtmp. If the file does not exist,
     this will not be apparent until the first attempt to reference the
     file is made. utmpname() does not open the file. It just closes the
     old file if it is currently open and saves the new filename.

RESULT
     A null pointer is returned upon failure to read, whether for permis-
     sions or having reached the end of file, or upon failure to write.

NOTES
     The most current entry is saved in a static structure. If a file is to
     be accessed repeatedly, the entries must be copied before further
     accesses are made. On each call to either getutid() or getutline(),
     the routine examines the static structure before performing more I/O.
     If the contents of the static structure match what it is searching
     for, it looks no further. For this reason, if getutline() is to search
     for multiple occurrences, it would be necessary to zero out the static
     area after each success, or getutline() would just return the same
     structure over and over again. There is one exception to the rule
     about emptying the structure before further reads are done. The impli-
     cit read done by pututline() (if it finds that it is not already at
     the correct place in the file) will not hurt the contents of the
     static structure returned by the getutent(), getutid() or getutline()
     routines, if the user has just modified those contents and passed the
     pointer back to pututline().

     These routines use buffered standard I/O for input, but pututline()
     uses an unbuffered non-standard write to avoid race conditions between
     processes trying to modify the utmp and wtmp files.


Page 2                       Reliant UNIX 5.44                Printed 11/98

getut(3C)                                                         getut(3C)

FILES
     /var/adm/utmp

     /var/adm/wtmp

SEE ALSO
     ttyslot(3C), utmp(4).















































Page 3                       Reliant UNIX 5.44                Printed 11/98