endutent(3C)




NAME

     getutent, getutid, getutline, pututline, setutent, endutent,
     utmpname - user accounting database functions


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

     These functions provide access to the user accounting  data-
     base,  utmp.  Entries  in  the database are described by the
     definitions and data structures in <utmp.h>.

     The utmp structure contains the following members:

     char                ut_user[8];   /* user login name */
     char                ut_id[4];     /* /sbin/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  ut_exit;      /* exit status of a process */
                                       /* marked as DEAD_PROCESS */
     time_t              ut_time;      /* time entry was made */

     The structure exit_status includes the following members:

     short   e_termination;   /* termination status */
     short   e_exit;          /* exit status */

  getutent()
     The getutent() function reads in the next entry from a  utmp
     database.  If the database is not already open, it opens it.
     If it reaches the end of the database, it fails.

  getutid()
     The getutid() function searches  forward  from  the  current
     point  in  the  utmp database 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, then getutid() will return a
     pointer to the first entry whose type is one of  these  four
     and  whose  ut_id  member  matches  id->ut_id. If the end of
     database is reached without a match, it fails.

  getutline()
     The getutline() function searches forward from  the  current
     point  in  the  utmp database until it finds an entry of the
     type LOGIN_PROCESS or  ut_line  string  matching  the  line-
     >ut_line  string.  If the end of database is reached without
     a match, it fails.

  pututline()
     The pututline() function writes the supplied utmp  structure
     into the utmp database.  It uses getutid() to search forward
     for the proper place if it finds that it is not  already  at
     the  proper place.  It is expected that normally the user of
     pututline() will have searched for the  proper  entry  using
     one  of  the  these  functions.  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
     database.
      It returns a pointer to the utmp structure. When called  by
     a non-root user, pututline() invokes a setuid() root program
     to verify and write the entry, since the  utmp  database  is
     normally  writable only by root.  In this event, the ut_name
     member must correspond to the actual  user  name  associated
     with  the  process;  the   ut_type  member  must  be  either
     USER_PROCESS or DEAD_PROCESS; and the ut_line member must be
     a device special file and be writable by the user.

  setutent()
     The setutent() function  resets  the  input  stream  to  the
     beginning.  This reset should be done before each search for
     a new entry if it is desired that  the  entire  database  be
     examined.

  endutent()
     The endutent() function closes the currently open database.

  utmpname()
     The utmpname() function allows the user to change  the  name
     of  the database file examined to another file.  If the file
     does not exist, this will not be apparent  until  the  first
     attempt to reference the file is made.  The utmpname() func-
     tion does not open the file but closes the old file if it is
     currently open and saves the new file name.


RETURN VALUES

     A null pointer is returned upon failure to read, whether for
     permissions  or  having  reached  the  end  of file, or upon
     failure to write. If the file name given is longer  than  79
     characters, utmpname() returns 0.  Otherwise, it returns 1.


USAGE

     These functions 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 databases.

     Applications should not access the utmp and  wtmp  databases
     directly,  but  should  use  these  functions to ensure that
     these databases are  maintained  consistently.  Using  these
     functions,  however,  may cause applications to fail if user
     accounting data cannot be represented properly in  the  utmp
     structure  (for  example,  on a system where PIDs can exceed
     32767).  Use the functions described  on  the  getutxent(3C)
     manual page instead.


ATTRIBUTES

     See attributes(5) for descriptions of the  following  attri-
     butes:

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | MT-Level                    | Unsafe                      |
    |_____________________________|_____________________________|


SEE ALSO

     getutxent(3C), ttyslot(3C), utmpx(4), attributes(5)


NOTES

     The most current entry is saved in a static structure.  Mul-
     tiple  accesses  require  that  it  be copied before further
     accesses are made. On  each  call  to  either  getutid()  or
     getutline(),  the  function  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, to use getutline() 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 implicit read done by putut-
     line() (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  getut-
     line()  functions,  if the user has just modified those con-
     tents and passed the pointer back to pututline().


Man(1) output converted with man2html