getut(3C)                                               getut(3C)



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

     SYNOPSIS
          #include <sys/types.h>
          #include <utmp.h>

          struct utmp *getutent ( )

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

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

          void pututline (utmp)
          struct utmp *utmp;

          void setutent ( )

          void endutent ( )

          void utmpname (file )
          char *file;

     DESCRIPTION
          getutent, getutid, and getutline each return a pointer to a
          structure of the following type:

          struct utmp {
               char    ut_user[8];       /*User login name*/
               char    ut_id[4];         /*/etc/inittab id (usually line#)*/
               char    ut_line[12];      /*device name (console, lnxx)*/
               short   ut_pid;           /*process id*/
               short   ut_type;          /*type of entry*/
               struct  exit_status {
               short   e_termination;    /*Process termination status*/
               short   e_exit;           /*Process exit status*/
              } ut_exit;                 /*Exit status of a process
                                         /*marked as DEAD_PROCESS.*/
               time_t  ut_time;          /*time entry was made*/
               char    ut_host[16];      /* host name, if remote*/
          };

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

          getutid searches forward from the current point in the utmp
          file until it finds an entry with a matching if the type
          specified is RUNLVL, BOOTTIME, OLDTIME, or NEWTIME. If



     Page 1                                        (last mod. 1/15/87)

     getut(3C)                                               getut(3C)



          the type specified in id is INITPROCESS, LOGINPROCESS,
          USERPROCESS, or DEADPROCESS, getutid will return a pointer
          to the first entry whose type is one of these four and whose
          utid field matches id->utid.  getutid fails if the end of
          file is reached without a match.

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

          pututline writes out the supplied utmp structure into the
          utmp file.  It uses getutid to search forward for the proper
          place if it finds that it is not already at the proper
          place.  It is assumed that the user of pututline has
          searched for the proper entry using one of the getut
          routines.  If this has been done, 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.

          setutent resets the input stream to the beginning of the
          file.  This should be done before each search for a new
          entry if it is desired that the entire file be examined.

          endutent closes the currently open file.

          utmpname allows the user to change the name of the file
          examined from /etc/utmp to any other filename.  It is
          expected that most often this other file will be /etc/wtmp.
          If the file doesn't 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.

     FILES
          /etc/utmp
          /etc/wtmp

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

     DIAGNOSTICS
          A NULL pointer is returned upon failure to read or write.
          Failure to read may be due to permissions or because end-
          of-file has been reached.

     COMMENTS
          The most current entry is saved in a static structure.
          Multiple accesses require that it be copied before further
          accesses are made.  Each call to either getutid or getutline
          sees the routine examine the static structure before



     Page 2                                        (last mod. 1/15/87)

     getut(3C)                                               getut(3C)



          performing more I/O.  If the search of the static structure
          results in a match, no further search is performed.  To use
          getutline to search for multiple occurences, zero out the
          static structure after each success; otherwise getutline
          will just return the same pointer over and over again.
          There is one exception to the rule about removing the
          structure before further reads are done.  If the implicit
          read done by pututline finds that it isn't already at the
          correct place in the file, the contents of the static
          structure returned by the getutent, getutid, or getutline
          routines are not harmed, 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 3                                        (last mod. 1/15/87)