getutent, getutid, getutline, pututline, setutent, endutent, or utmpname Subroutine

Purpose

Accesses utmp file entries.

Library

Standard C Library (libc.a)

Syntax

#include <utmp.h>

Description

The getutent, getutid, and getutline subroutines return a pointer to a structure of the following type:

struct utmp
> {
>     char ut_user[256];           /* User name */
>     char ut_id[14];              /* /etc/inittab ID */
>     char ut_line[64];            /* Device name (console, lnxx) */
>     pid_t ut_pid;                /* Process ID */
>     short ut_type;               /* Type of entry */
>         int __time_t_space;      /* for 32vs64-bit time_t PPC */
>         time_t ut_time;          /* time entry was made */
>         struct exit_status
>         {
>             short e_termination; /* Process termination status */
>             short e_exit;        /* Process exit status */
>         }
>         ut_exit;                 /* The exit status of a process
>                                  /* marked as DEAD_PROCESS. */
>         char ut_host[256];       /* host name */
>         int __dbl_word_pad;      /* for double word alignment */
>         int __reservedA[2];
>         int __reservedV[6];
> };

The getutent subroutine reads the next entry from a utmp-like file. If the file is not open, this subroutine opens it. If the end of the file is reached, the getutent subroutine fails.

The pututline subroutine writes the supplied Utmp parameter structure into the utmp file. It is assumed that the user of the pututline subroutine has searched for the proper entry point using one of the getut subroutines. If not, the pututline subroutine calls getutid to search forward for the proper place. If so, pututline does not search. If the pututline subroutine does not find a matching slot for the entry, it adds a new entry to the end of the file.

The setutent subroutine resets the input stream to the beginning of the file. Issue a setuid call before each search for a new entry if you want to examine the entire file.

The endutent subroutine closes the file currently open.

The utmpname subroutine changes the name of a file to be examined from /etc/utmp to any other file. The name specified is usually /var/adm/wtmp. If the specified file does not exist, no indication is given. You are not aware of this fact until your first attempt to reference the file. The utmpname subroutine does not open the file. It closes the old file, if currently open, and saves the new file name.

The most current entry is saved in a static structure. To make multiple accesses, you must copy or use the structure between each access. The getutid and getutline subroutines examine the static structure first. If the contents of the static structure match what they are searching for, they do not read the utmp file. Therefore, you must fill the static structure with zeros after each use if you want to use these subroutines to search for multiple occurrences.

If the pututline subroutine finds that it is not already at the correct place in the file, the implicit read it performs does not overwrite the contents of the static structure returned by the getutent subroutine, the getuid subroutine, or the getutline subroutine. This allows you to get an entry with one of these subroutines, modify the structure, and pass the pointer back to the pututline subroutine for writing.

These subroutines use buffered standard I/O for input. However, the pututline subroutine uses an unbuffered nonstandard write to avoid race conditions between processes trying to modify the utmp and wtmp files.

Parameters

Return Values

These subroutines fail and return a null pointer if a read or write fails due to a permission conflict or because the end of the file is reached.

Files