GETUT(S)                 XENIX System V                  GETUT(S)



     Name
          getutent, getutid, getutline, pututline, setutent, endutent,
          utmpname - Accesses utmp file entry.

     Syntax
          #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
          the following type of structure:

               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;    /*The exit status of a process*/
                    } ut_exit;           /*The exit status of a process*/
                                    /*marked as DEAD_PROCESS.*/
                    time_t    ut_time;   /*Time entry was made*/
               };
          getutent reads the next entry from a utmp-like file.  If the
          file is not already open, getutent opens it; when getutent
          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 ut_type matching id ->
          ut_type if the type specified is RUN_LVL, BOOT_TIME,
          OLD_TIME, or NEW_TIME.  If the type specified in id is
          INIT_PROCESS, LOGIN_PROCESS, USER_PROCESS, or DEAD_PROCESS,



     Page 1                                           (printed 8/7/87)

     GETUT(S)                 XENIX System V                  GETUT(S)



          then getutid returns a pointer to the first entry whose type
          matches one of these four types and whose ut_id matches id
          -> ut_id. If the end of the file is reached without a match,
          getutid fails.

          getutline searches forward from the current point in the
          utmp file until it reaches an entry of the type
          LOGIN_PROCESS or USER_PROCESS which has an ut_line string
          matching the line -> ut_line string.  If the end of the file
          is reached without a match, getutline fails.

          pututline writes out the supplied utmp structure into the
          utmp file.  If pututline finds that it is not already in the
          proper place in the file, it uses getutid to search forward
          for the proper place.  A user of pututline could search for
          the proper place using one of the getut routines. If
          pututline does not find a matching slot for the new entry,
          it adds 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 the user desires that the entire file be examined.

          endutent closes the currently opened file.

          utmpname allows the user to change the name of the file
          examined, from /etc/utmp to any other file.  Generally, this
          other file will be /etc/wtmp.  If this file does not exist,
          it 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 open and saves the new file name.

     Files
          /etc/utmp
          /etc/wtmp

     See Also
          ttyslot(S), utmp(M)

     Diagnostics
          A NULL pointer is returned upon failure to read (either
          because of permissions or the end of the file) or upon
          failure to write.

     Comments
          With these routines, the most current entry is saved in a
          static structure.  Multiple accesses require that the
          structure be copied before further accesses are made.  Each
          call to either getutid or getutline sees the routine examine
          the static structure before performing more I/O.  If the
          contents of the static structure match what the routine is
          searching for, the search stops.  For this reason, to use



     Page 2                                           (printed 8/7/87)

     GETUT(S)                 XENIX System V                  GETUT(S)



          getutline to search for multiple occurrences, the user must
          to remove the static after each success, or getutline will
          just return the same pointer over and over again.

          There is one exception to the rule of removing the structure
          before further reads are done:  the implicit read done by
          pututline (in cases where it finds that it is not already in
          the correct place in the file) will not hurt the contents of
          the static structure returned by getutent, getutid, or
          getutline routines if the user has just modified those
          contents and passed the pointer back to pututline.

          These routines used 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                                           (printed 8/7/87)