getut(3C) getut(3C)
NAME
getut: getutent(), getutid(), getutline(), pututline(), _pututline(), setutent(), endutent(), utmpname() - access utmp file entry
SYNOPSIS
Obsolescent Interfaces
DESCRIPTION
and each return a pointer to a structure of the following type:
struct utmp {
char ut_user[8]; /* User login name */
char ut_id[4]; /* /etc/inittab id (usually line #) */
char ut_line[12]; /* device name (console, lnxx) */
pid_t ut_pid; /* process id */
short ut_type; /* type of entry */
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. */
unsigned short ut_reserved1; /* Reserved for future use */
time_t ut_time; /* time entry was made */
char ut_host[16]; /* host name, if remote;NOTSUPPORTED*/
unsigned long ut_addr; /* Internet addr of host, if remote */
};
Reads in the next entry from a
file. If the file is not already open, opens it. If it reaches the end of the file, fails.
Searches forward from the current point in the
file until it finds an entry with a matching if the type specified is or If the type specified in id is or returns a
pointer to the first entry whose type is one of these four, and whose field matches If end-of-file is reached without a
match, fails.
Searches forward from the current point in the
file until it finds an entry of type or that also has a string matching the string. If end-of-file is reached without
a match, fails.
Writes out the supplied
structure into the file, translates the supplied structure into a structure and writes it to a file. uses to search
forward for the proper location if it is not already there. It is normally expected that the application program has
already searched for the proper entry by using one of the routines before calling If the search as already been made,
does not repeat it. If does not find a matching slot for the new entry, it adds a new entry to the end of the file.
Performs the same actions as
except that it returns a value useful for error checking.
Resets the input stream to the beginning of the file.
This should be done before each search for a new entry if it is desired that the entire file be examined.
Closes the currently open file.
Allows the user to change the name of the file being examined from
and to any other files. In this case, the name provided to will be used for the functions. An will be appended to
this name, and will be used by the getutx(3C) functions. The one exception to this are the and functions as they
access both files in an attempt to keep the and files in sync. The other files are usually and If the files do not
exist, the absence is not discovered until the first subsequent attempt to reference the file. does not open the file;
it merely closes the old file if it is currently open, and saves the new file name.
The most current entry is saved in a static structure. Multiple accesses require that the structure be copied before further accesses are
made. During each call to either or the static structure is examined before performing more I/O. If the contents of the static structure
match what the routine is searching for, no additional searching is done. Therefore, if you are using to search for multiple occurrences,
it is necessary to zero out the static structure after each success; otherwise, simply returns the same pointer over and over again. There
is one exception to the rule about removing the structure before a new read: the implicit read done by (if it finds that it is not already
at the correct place in the file) does not alter the contents of the static structure returned by or if the user has just modified those
contents and passed the pointer back to
Obsolescent Interfaces
access utmp file entry.
RETURN VALUE
These functions return a NULL pointer upon failure to read (whether for permissions or having reached end-of-file), or upon failure to
write. They also return a NULL pointer if the size of the file is not an integral multiple of
behaves the same as except that it returns a pointer to a static location containing the most current entry if the call succeeds. The con-
tents of this structure is identical to the contents of the supplied structure if successful. If fails upon writing to it returns a NULL
pointer. If is successful in writing to the file and fails in writing to the file, then will behave as if it succeeded. Please note that
the file and the file may not be in sync due to the above behavior. and are only guaranteed to have written to the file upon successful
completion.
Reentrant Interfaces
Upon successful completion, and return Otherwise, they all return and set
ERRORS
Reentrant Interfaces
The utmp or ud parameter is equal to NULL.
WARNINGS
and are obsolescent interfaces supported only for compatibility with existing DCE applications. New multithreaded applications should use
use the getutx(3C) functions that provide equivalent functionality.
Some vendors' versions of erase the file if the file exists but is not an integral multiple of Given the possibility of user error in pro-
viding a name to utmpname (such as giving improper arguments to who(1)), HP-UX does not do this, but instead returns an error indication.
For portability, getutx(3C) functions are preferred over these functions.
FILES
SEE ALSO
utmpd(1M), getuts(3C), getutx(3C), pututxline(3C), ttyslot(3C), utmp(4), thread_safety(5).
STANDARDS CONFORMANCE
TO BE OBSOLETED getut(3C)