pututline()

Write an entry in the user-information file

Synopsis:

#include <utmp.h>

void pututline( struct utmp * __utmp );

Arguments:

__utmp

A pointer to the utmp structure for the entry that you want to add.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

---

This function is in libc.a, but not in libc.so (in order to save space).

---

Description:

The pututline() function writes out the supplied utmp structure into the utmp file.

It uses getutid() to search forward for the proper place if it finds that it isn't already there. Normally, you should search for the proper entry by calling getutent(), getutid(), or getutline(), If so, pututline() doesn't search. If pututline() doesn't find a matching slot for the new entry, it adds a new entry to the end of the file.

When called by a non-root user, pututline() invokes a setuid() root program to verify and write the entry, since the file specified in _PATH_UTMP is normally writable only by root. In this event, the ut_name field must correspond to the actual user name associated with the process; the ut_type field must be either USER_PROCESS or DEAD_PROCESS; the ut_line field must be a device-special file and be writable by the user.

Returns:

A pointer to the utmp structure.

Files:

_PATH_UTMP

Specifies the user information file.

Classification:

Unix

Caveats:

The most current entry is saved in a static structure. Copy it before making further accesses.

On each call to either getutid() or getutline(), the routine examines the static structure before performing more I/O. If the contents of the static structure match what it's searching for, the function looks no further. For this reason, to use getutline() to search for multiple occurrences, zero out the static area after each success, or getutline() will return the same structure over and over again.

There's one exception to the rule about emptying the structure before further reads are done: the implicit read done by pututline() (if it finds that it isn't already at the correct place in the file) doesn't hurt the contents of the static structure returned by the getutent(), getutid() or getutline() routines, if the user has just modified those contents and passed the pointer back to pututline().

These routines 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.

See also:

endutent(), getutent(), getutid(), getutline(), setutent(), utmp, utmpname()

login in the Utilities Reference