Seth Woolley's Man Viewer

getutent(3) - endutent, getutent, getutid, getutline, pututline, setutent, utmpname, endutent, getutent, getutid, getutline, pututline, setutent, utmpname - access utmp file entries - man 3 getutent

([section] manual, -k keyword, -K [section] search, -f whatis)
man plain no title

GETUTENT(3)                    Library functions                   GETUTENT(3)



NAME
       getutent, getutid, getutline, pututline, setutent, endutent, utmpname -
       access(2,5) utmp file(1,n) 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(1,n));

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

       setutent()  rewinds the file(1,n) 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(1,n) with the other functions.

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

       getutid() searches forward from the current file(1,n) position in(1,8)  the  utmp
       file(1,n)  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_PROCESS, 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(1,n) position in(1,8) 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(1,8) the file(1,n) 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(1,8) 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(1,8) *ubufp.  On error(8,n) 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(1,8) 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(1,3x,1 builtins) 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(5,8) /dev/tty(1,4)[pqr][0-9a-z] */
         strcpy(entry.ut_id,ttyname(0)+strlen("/dev/tty(1,4)"));
         time(1,2,n)(&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(1,3x,1 builtins) 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(1,3x,1 builtins) after removing entry:;who");

         endutent();
         return 0;
       }

FILES
       /var/run/utmp  database of currently logged-in users(1,5)
       /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 prototype
       given above for pututline() (also found in(1,8) 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)

References for this manual (incoming links)