Index for Section 3

Alphabetical listing for G

Bottom of page

getutxent(3)
NAME
  endutxent, getutxent, getutxid, getutxline, pututxline, setutxent - Access
  user accounting database functions

SYNOPSIS
  #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
  Standard C Library (libc)

STANDARDS
  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
  id  Specifies one of the BOOT_TIME, OLD_TIME, NEW_TIME, INIT_PROCESS,
      LOGIN_PROCESS, USER_PROCESS, or DEAD_PROCESS entries.

  line
      Matches a utmpx entry of the type LOGIN_PROCESS or USER_PROCESS such
      that the ut_line member matches line->ut_line.

  utmpx
      Points to a utmpx structure to be placed into the user accounting
      database.

DESCRIPTION
  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
  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
  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
  The pututxline() function may fail and set errno to the corresponding value
  if the following condition occurs:

  [EPERM]
      The process does not have the appropriate privileges.

FILES
  /usr/include/utmpx.h
      Accounting header file that defines the format for the login database
      file.

  /var/adm/utmpx, /var/adm/wtmpx
      The active login/logoff database files.

SEE ALSO
  Standards: standards(5)

Index for Section 3

Alphabetical listing for G

Top of page