endutent

GETUTENT(3)		      Library functions			  GETUTENT(3)



NAME
       getutent,  getutid, getutline, pututline, setutent, endutent, utmpname
       - access utmp file entries

SYNOPSIS
       #include <utmp.h>

       struct utmp *getutent(void);
       struct utmp *getutid(struct utmp *ut);
       struct utmp *getutline(struct utmp *ut);

       struct utmp *pututline(struct utmp *ut);

       void setutent(void);
       void endutent(void);

       void utmpname(const char *file);

DESCRIPTION
       utmpname() sets the name of the utmp-format file for  the  other	 utmp
       functions  to  access.	If utmpname() is not used to set the filename
       before the other	 functions  are	 used,	they  assume  _PATH_UTMP,  as
       defined in <paths.h>.

       setutent() rewinds the file pointer to the beginning of the utmp file.
       It is generally a Good Idea to call it before any of the	 other	func-
       tions.

       endutent()  closes  the	utmp file.  It should be called when the user
       code is done accessing the file with the other functions.

       getutent() reads a line from the current file  position	in  the	 utmp
       file.   It  returns  a pointer to a structure containing the fields of
       the line.

       getutid() searches forward from the current file position in the	 utmp
       file  based  upon  ut.	If  ut->ut_type is one of RUN_LVL, BOOT_TIME,
       NEW_TIME, or OLD_TIME, getutid()	 will  find  the  first	 entry	whose
       ut_type field matches ut->ut_type.  If ut->ut_type is one of INIT_PRO-
       CESS, LOGIN_PROCESS, USER_PROCESS,  or  DEAD_PROCESS,  getutid()	 will
       find the first entry whose ut_id field matches ut->ut_id.

       getutline()  searches  forward  from  the current file position in the
       utmp  file.   It	 scans	entries	 whose	ut_type	 is  USER_PROCESS  or
       LOGIN_PROCESS  and  returns  the first one whose ut_line field matches
       ut->ut_line.

       pututline() writes the utmp structure ut into the utmp file.  It	 uses
       getutid() to search for the proper place in the file to insert the new
       entry.  If it cannot find an appropriate slot for ut, pututline() will
       append the new entry to the end of the file.

RETURN VALUE
       getutent(), getutid(), getutline() and pututline() return a pointer to
       a struct utmp on success, and NULL on failure.  This  struct  utmp  is
       allocated  in  static  storage,	and  may be overwritten by subsequent
       calls.

REENTRANT VERSIONS
       These above functions are not thread-safe. Glibc adds  reentrant	 ver-
       sions

       #define _GNU_SOURCE    /* or _SVID_SOURCE or _BSD_SOURCE */
       #include <utmp.h>

       int getutent_r(struct utmp *ubuf, struct utmp **ubufp);

       int getutid_r(struct utmp *ut,
		     struct utmp *ubuf, struct utmp **ubufp);

       int getutline_r(struct utmp *ut,
		       struct utmp *ubuf, struct utmp **ubufp);

       These  functions	 are  GNU extensions, analogs of the functions of the
       same name without the _r suffix. The ubuf parameter gives these	func-
       tions  a place to store their result.  On success they return 0, and a
       pointer to the result is written in *ubufp.  On error these  functions
       return -1.

EXAMPLE
       The  following  example adds and removes a utmp record, assuming it is
       run from within a pseudo terminal.  For usage in a  real	 application,
       you should check the return values of getpwuid() and ttyname().

       #include <string.h>
       #include <stdlib.h>
       #include <pwd.h>
       #include <unistd.h>
       #include <utmp.h>

       int main(int argc, char *argv[])
       {
	 struct utmp entry;

	 system("echo before adding entry:;who");

	 entry.ut_type=USER_PROCESS;
	 entry.ut_pid=getpid();
	 strcpy(entry.ut_line,ttyname(0)+strlen("/dev/"));
	 /* only correct for ptys named /dev/tty[pqr][0-9a-z] */
	 strcpy(entry.ut_id,ttyname(0)+strlen("/dev/tty"));
	 time(&entry.ut_time);
	 strcpy(entry.ut_user,getpwuid(getuid())->pw_name);
	 memset(entry.ut_host,0,UT_HOSTSIZE);
	 entry.ut_addr=0;
	 setutent();
	 pututline(&entry);

	 system("echo after adding entry:;who");

	 entry.ut_type=DEAD_PROCESS;
	 memset(entry.ut_line,0,UT_LINESIZE);
	 entry.ut_time=0;
	 memset(entry.ut_user,0,UT_NAMESIZE);
	 setutent();
	 pututline(&entry);

	 system("echo after removing entry:;who");

	 endutent();
	 return 0;
       }

FILES
       /var/run/utmp  database of currently logged-in users
       /var/log/wtmp  database of past user logins

CONFORMING TO
       XPG 2, SVID 2, Linux FSSTND 1.2

       In  XPG2	 and  SVID2  the function pututline() is documented to return
       void, and that is what it does  on  many	 systems  (AIX,	 HPUX,	Linux
       libc5).	 HPUX  introduces a new function _pututline() with the proto-
       type given above for pututline() (also found in Linux libc5).

       All these functions are obsolete	 now  on  non-Linux  systems.	POSIX
       1003.1-2001,  following	XPG4.2, does not have any of these functions,
       but instead uses

       #include <utmpx.h>

       struct utmpx *getutxent(void);
       struct utmpx *getutxid(const struct utmpx *);
       struct utmpx *getutxline(const struct utmpx *);
       struct utmpx *pututxline(const struct utmpx *);
       void setutxent(void);
       void endutxent(void);

       The utmpx structure is a superset of the utmp  structure,  with	addi-
       tional fields, and larger versions of the existing fields.  The corre-
       sponding files are often /var/*/utmpx and /var/*/wtmpx.

       Linux glibc on the other hand does not use utmpx since its utmp struc-
       ture is already large enough. The functions getutxent etc. are aliases
       for getutent etc.

SEE ALSO
       utmp(5)



				  1996-07-25			  GETUTENT(3)