pututxline() — Write entry to utmpx database

Standards

Standards / Extensions C or C++ Dependencies

XPG4.2
Single UNIX Specification, Version 3

 both  

Format

#define _XOPEN_SOURCE_EXTENDED 1
#include <utmpx.h>

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

General description

The pututxline() function writes out the structure into the utmpx database, when the calling process has appropriate privileges. The pututxline() function uses getutxid() to search for a record that satisfies the request. If the getutxid() search succeeds, then the entry is replaced. Otherwise, a new entry is made at the end of the database. If the utmpx database does not already exist, then pututxline() creates the utmpx database with file permissions 0644. (See the __utmpxname() function for information on the utmpx structure.)

If the ut_type field in the entry being added is EMPTY, it is always placed at the start of the utmpx database. For this reason, pututxline() should not be used to place EMPTY entries in the utmpx database.

The pututxline() function obtains an exclusive lock in the utmpx database on the byte range of the record which is ready to write and releases the lock before returning to its caller. The functions getutxent(), getutxid(), and getutxline() might continue to read and are not affected by pututxline().

Because the pututxline() function processes thread-specific data the pututxline() function can be used safely from a multithreaded application. If multiple threads in the same process open the database, then each thread opens the database with a different file descriptor. The thread's database file descriptor is closed when the calling thread terminates or the endutxent() function is called by the calling thread.

The name of the database file defaults to /etc/utmpx. To process a different database file name use the __utmpxname() function.

pututxline() is not supported when all of the following conditions are true:
  • The security environment for the current address space has the trusted attribute.
  • Either the effective UID is different than the real UID, or the effective GID is different than the real GID.
  • The effective UID is not 0.
  • The utmpx file is not writable by normal (non-trusted) processes with the current effective UID and GID.
  • pututxline() is called after getutxline(), getutxid(), or getutxent(), with no intervening calls to endutxent() or __utmpxname().
For all entries that match a request, the ut_type member indicates the type of the entry. Other members of the entry will contain meaningful data based on the value of the ut_type member as follows:
EMPTY
No other members have meaningful data.
BOOT_TIME
ut_tv is meaningful.
__RUN_LVL
ut_tv and ut_line are meaningful
OLD_TIME
ut_tv is meaningful.
NEW_TIME
ut_tv is meaningful.
USER_PROCESS
ut_id, ut_user (login name of the user), ut_line, ut_pid, and ut_tv are meaningful.
INIT_PROCESS
ut_id, ut_pid, and ut_tv are meaningful.
LOGIN_PROCESS
ut_id, ut_user (implementation-specific name of the login process), ut_pid, and ut_tv are meaningful.
DEAD_PROCESS
ut_id, ut_pid, and ut_tv are meaningful.

Returned value

If successful, pututxline() returns a pointer to a utmpx structure containing a copy of the entry written to the database.

If unsuccessful, pututxline() returns a NULL pointer.

pututxline() may fail if the process does not have appropriate privileges.

Related information

Parent topic: Library functions