getut(3C) DG/UX R4.11MU05 getut(3C)
NAME
getut: getutent, getutid, getutline, pututline, setutent, endutent,
utmpname - access utmp file entry
SYNOPSIS
#include <utmp.h>
struct utmp *getutent (void);
struct utmp *getutid (const struct utmp *id);
struct utmp *getutline (const struct utmp *line);
struct utmp *pututline (const struct utmp *utmp);
void setutent (void);
void endutent (void);
int utmpname (const char *file);
DESCRIPTION
getutent, getutid, getutline, and pututline each return a pointer to
a utmp structure (See utmp(4)).
DG/UX for 88K
getutent reads in the next entry from UTMP_FILE. If the file is not
already open, getutent calls setutent to open it. If it reaches the
end of the file, it fails.
getutid searches forward from the current point in UTMP_FILE until it
finds an entry with a ut_type matching id->ut_type if the type
specified is RUN_LVL, BOOT_TIME, OLD_TIME, or NEW_TIME. If the type
specified in id is INIT_PROCESS, LOGIN_PROCESS, USER_PROCESS, or
DEAD_PROCESS, then getutid will return a pointer to the first entry
whose type is one of these four and whose ut_id field matches,
character by character, id->ut_id . If the end of file is reached
without a match, it fails.
getutline searches forward from the current point in UTMP_FILE until
it finds an entry of the type LOGIN_PROCESS or USER_PROCESS that also
has a ut_line string matching the line->ut_line string. If the end
of file is reached without a match, it fails.
pututline writes the supplied utmp structure into UTMP_FILE. It uses
getutid to search forward for the proper place if it finds that it is
not already at the proper place. It is expected that normally the
user of pututline will have searched for the proper entry using one
of the getut routines. If so, pututline will not search. If
pututline does not find a matching slot for the new entry, it will
add a new entry to the end of the file. It returns a pointer to the
utmp structure.
setutent resets the input stream to the beginning of the file. This
reset should be done before each search for a new entry if it is
desired that the entire file be examined. If the file is not
currently open, setutent will open it.
endutent closes the currently open file.
utmpname allows the user to change the name of the file being
examined by the getut interfaces, from UTMP_FILE to any other file.
The other file is usually WTMP_FILE. If the file does not exist,
this is not apparent until the application first attempts to
reference the file. utmpname does not open the file. It just closes
the old file if it is currently open and saves the new file name. If
the file name given is longer than 79 characters, utmpname returns 0
and does not change the filename. Otherwise, it returns 1.
UTMPX_FILE is defined to be /var/adm/utmp.
WTMPX_FILE is defined to be /var/adm/wtmp.
UTMP_FILE is defined to be /var/adm/utmp.
WTMP_FILE is defined to be /var/adm/wtmp.
DG/UX for Intel
getutent calls getutxent, converting the utmpx entry returned by
getutxent into a utmp entry. getutent then returns a pointer to the
utmp entry. If getutxent fails, getutent fails.
getutid converts id from a utmp record to a utmpx record. It then
calls getutxid, passing the converted utmpx entry as an argument.
The resulting value from getutxid is converted back to a utmp entry.
getutid then returns a pointer to the utmp entry. If getutxid fails,
getutid fails.
getutline converts line from a utmp record to a utmpx record. It
then calls getutxline, passing the converted utmpx entry as an
argument. The resulting value from getutxline is converted back to a
utmp entry. getutline then returns a pointer to the utmp entry. If
getutxline fails, getutline fails.
pututline converts utmp from a utmp record to a utmpx record. It
then calls pututxline, passing the converted utmpx entry as an
argument. The resulting value from pututxline is converted back to a
utmp entry. pututline then returns a pointer to the utmp entry. If
pututxline fails, pututline fails.
setutent calls setutxent.
endutent calls endutxent.
utmpname, if necessary, appends an ``x'' character to file. It then
calls utmpxname, passing the new filename as an argument. If
utmpxname fails, then utmpname fails.
UTMPX_FILE is defined to be /var/adm/utmpx.
WTMPX_FILE is defined to be /var/adm/wtmpx.
UTMP_FILE is defined to be /var/adm/utmpx.
WTMP_FILE is defined to be /var/adm/wtmpx.
Considerations for Threads Programming
+----------+-----------------------------+
| | async- |
|function | reentrant cancel cancel |
| | point safe |
+----------+-----------------------------+
|endutent | N - - |
|getutent | N - - |
|getutid | N - - |
|getutline | N - - |
|pututline | N - - |
|setutent | N - - |
|utmpname | N - - |
+----------+-----------------------------+
FILES
/var/adm/utmp /var/adm/utmpx
/var/adm/wtmp /var/adm/wtmpx
SEE ALSO
reentrant(3), getutx(3C), ttyslot(3C), utmpx(4), utmp(4).
DIAGNOSTICS
A null pointer is returned upon failure to read, whether for
permissions or having reached the end of file, or upon failure to
write.
NOTES
The most current entry is saved in a static structure. Multiple
accesses require that it be copied before further accesses are made.
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 is searching for, it looks no further.
Therefore, to use getutline to search for multiple occurrences, you
must zero out the static area after each success, or getutline just
returns the same structure over and over again. There is 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 is not already at the correct place in the file) will not
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.
Licensed material--property of copyright holder(s)