NAME    [Toc]    [Back]

       endutxent,  getutxent,  getutxid,  getutxline, pututxline,
       setutxent - Access user accounting database functions

SYNOPSIS    [Toc]    [Back]

       #include <utmpx.h>

       void endutxent(
               void ); struct utmpx *getutxent(
               void ); struct utmpx *getutxid(
               const struct utmpx *id );  struct  utmpx  *getutxline(

               const  struct utmpx *line ); struct utmpx *pututxline(

               const struct utmpx *utmpx ); void setutxent(
               void );

LIBRARY    [Toc]    [Back]

       Standard C Library (libc)

STANDARDS    [Toc]    [Back]

       Interfaces documented on this reference  page  conform  to
       industry standards as follows:

       endutxent(),    getutxent(),   getutxid(),   getutxline(),
       pututxline(), setutxent():  XPG4-UNIX

       Refer to the standards(5) reference page for more information
 about industry standards and associated tags.

PARAMETERS    [Toc]    [Back]

       Specifies   one  of  the  BOOT_TIME,  OLD_TIME,  NEW_TIME,
       INIT_PROCESS, LOGIN_PROCESS, USER_PROCESS, or DEAD_PROCESS
       entries.   Matches a utmpx entry of the type LOGIN_PROCESS
       or USER_PROCESS  such  that  the  ut_line  member  matches
       line->ut_line.   Points  to a utmpx structure to be placed
       into the user accounting database.

DESCRIPTION    [Toc]    [Back]

       These functions provide  access  to  the  user  accounting
       database.

       The  getutxent()  function  reads  the next entry from the
       user accounting database. If the database is  not  already
       open,  getutxent() opens it. If the end of the database is
       reached, getutxent fails.

       The getutxid() function searches forward from the  current
       point  in  the database. If the ut_type value of the utmpx
       structure pointed to by the  id  parameter  is  BOOT_TIME,
       OLD_TIME,  or NEW_TIME, the getutxid() function stops when
       an entry with a matching ut_type value is found.

       If  the  ut_type  value  is  INIT_PROCESS,  LOGIN_PROCESS,
       USER_PROCESS,  or  DEAD_PROCESS,  the  getutxid() function
       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  database  is  reached  without  a  match,  the
       getutxid() function fails.

       The  getutxline()  function searches forward from the current
 point in the database until it finds an entry of  the
       type  LOGIN_PROCESS  or  USER_PROCESS  which  also  has  a
       ut_line value that matches the value in the  utmpx  structure
  pointed to by the line parameter.  If the end of the
       database is reached  without  a  match,  the  getutxline()
       function fails.

       If  the  process  has  appropriate privileges, the pututxline()
 function writes out the  structure  into  the  user
       accounting  database.   The  pututxline()  function  calls
       getutxid() to search  for  a  record  that  satisfies  the
       request.  If  this search succeeds, the entry is replaced.
       Otherwise, a new entry is made at  the  end  of  the  user
       accounting database.

       The  setutxent()  function  resets the input stream to the
       beginning of the database. This should be done before each
       search  for  a new entry if you want to examine the entire
       database.

       The  endutxent()  function  closes  the  user   accounting
       database.

NOTES    [Toc]    [Back]

       The  most  current  entry  is  saved  in a thread-specific
       structure, which is overwritten by a  subsequent  call  to
       getutxid()  or  getutxline()  by  the same thread. To make
       multiple accesses, you must  copy  or  use  the  structure
       between each access. The getutxid() and getutxline() functions
 examine the thread-specific structure first. If  the
       contents  of  this structure match what they are searching
       for, they do not read the database.  Therefore,  you  must
       fill  the  thread-specific structure with zeros after each
       use if you want to use these  subroutines  to  search  for
       multiple occurrences.

       If  the pututxline() function finds that it is not already
       at the correct place in the user accounting database,  the
       implicit  read it performs does not overwrite the contents
       of the thread-specific structure returned by  the  getutxent(),
  getutxid(), or getutxline() functions. This allows
       you to get an entry with one of these subroutines,  modify
       the  structure,  and  pass the pointer back to the pututxline()
 function for writing.

       These functions use buffered standard I/O for  input,  but
       the  pututxline()  function  uses  an  unbuffered write to
       avoid race conditions between processes trying  to  modify
       the utmpx and wtmpx files.

RETURN VALUES    [Toc]    [Back]

       Upon  successful  completion, the getutxent(), getutxid(),
       and getutxline() functions  return  pointers  to  a  utmpx
       structure  containing a copy of the requested entry in the
       user accounting database. Otherwise,  a  null  pointer  is
       returned.

       Upon  successful  completion,  the  pututxline()  function
       returns a pointer to a utmpx structure containing  a  copy
       of the entry added to the user accounting database. Otherwise,
 a null pointer is returned.

ERRORS    [Toc]    [Back]

       The pututxline() function may fail and set  errno  to  the
       corresponding value if the following condition occurs: The
       process does not have the appropriate privileges.

FILES    [Toc]    [Back]

       Accounting header file that defines  the  format  for  the
       login  database  file.   The  active login/logoff database
       files.

SEE ALSO    [Toc]    [Back]

       Standards: standards(5)



                                                     getutxent(3)