getutent

Purpose

     Accesses utmp file entries.

Library

     Standard C Library (libc.a)

Syntax

     #include <utmp.h>

     struct utmp *getutent ( )                 void pututline (utmp)
                                               struct utmp *utmp;
     struct utmp *getutid (id)
     struct utmp *id;                          void setutent ( )

     struct utmp *getutline (line)             void endutent ( )
     struct utmp *line;
                                               void utmpname (file)
                                               char *file;
     Description

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

       #define ut_name  ut_user
       #define ut_id    ut_line

       struct utmp
       {
          char    ut_user[8|;   /* User name                   */
          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;                /* The exit status of a DEAD_PROCESS */
       time_t     ut_time;      /* Time entry was made */
       };

     The  getutent  subroutine reads  the  next  entry from  a
     utmp-like file.   If the file  is not already  open, this
     subroutine opens it.  If the  end of the file is reached,
     getutent fails.

     If  you specify  type  RUN_LVL,  BOOT_TIME, OLD_TIME,  or
     NEW_TIME  in the  id  parameter,  the getutid  subroutine
     searches forward from the current  point in the utmp file
     until an  entry with a ut_type  matching id"->"ut_type is
     found.

     If   you  specify   one   of   the  types   INIT_PROCESS,
     LOGIN_PROCESS,  USER_PROCESS or  DEAD_PROCESS  in the  id
     parameter, then the getutid  subroutine returns a pointer
     to the  first entry whose type  is one of these  four and
     whose ut_id field matches id"->"ut_id.  If the end of the
     file is  reached without a match,  the getutid subroutine
     fails.

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

     The pututline subroutine writes  the supplied utmp struc-
     ture into  the utmp file.   If you have not  searched for
     the proper place in the file  using one of the getut rou-
     tines,  then the  pututline subroutine  calls getutid  to
     search forward for the proper place.  It is expected that
     normally the  user of  pututline searched for  the proper
     entry  using  one  of  the  getut  subroutines.   If  so,
     pututline does  not search.  If the  pututline subroutine
     does not  find a matching slot  for the entry, it  adds a
     new entry to the end of the file.

     The setutent  subroutine resets  the input stream  to the
     beginning of  the file.  You  should do this  before each
     search for a new entry if  you want to examine the entire
     file.

     The endutent subroutine closes the currently open file.

     The utmpname subroutine  changes the name of  the file to
     be examined from  /etc/utmp to any other  file.  The name
     specified  is usually  /usr/adm/wtmp.   If the  specified
     file does not exist, no indication is given.  You are not
     aware of this fact until  your first attempt to reference
     the  file.  The  utmpname  subroutine does  not open  the
     file.  It closes  the old file, if it  is currently open,
     and saves the new file name.

     The most  current entry is  saved in a  static structure.
     If you desire to make multiple accesses, you must copy or
     use the  structure between each access.   The getutid and
     getutline subroutines examine the static structure first.
     If the contents  of the static structure  match what they
     are  searching  for, they  do  not  read the  utmp  file.
     Therefore, you must fill the static structure with zeroes
     after each  use if you  want to use these  subroutines to
     search for multiple occurrences.

     If pututline finds  that it isn't already  at the correct
     place in  the file,  then the  implicit read  it performs
     does not  overwrite the contents of  the static structure
     returned by  the getutent, getuid, or  getutline routine.
     This allows you to get an entry with one of these subrou-
     tines, modify the structure, and pass the pointer back to
     pututline for writing.

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

     Return Value

     These subroutines  fail and  return a  NULL pointer  if a
     read or  write fails due  to end-of-file or  a permission
     conflict.

     Files

     /etc/utmp
     /usr/adm/wtmp

     Related Information

     In this book:  "ttyslot" and "utmp, wtmp, .ilog."