# getutent

## NAME



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


## LIBRARY



           Standard C library (_libc_ , _-lc_)
    


## SYNOPSIS



           **#include <utmp.h>**
    
           **struct utmp *getutent(void);**
           **struct utmp *getutid(const struct utmp ***_ut_**);**
           **struct utmp *getutline(const struct utmp ***_ut_**);**
    
           **struct utmp *pututline(const struct utmp ***_ut_**);**
    
           **void setutent(void);**
           **void endutent(void);**
    
           **int utmpname(const char ***_path_**);**
    


## DESCRIPTION



           New applications should use the POSIX.1-specified "utmpx" versions
           of these functions; see STANDARDS.
    
           **utmpname**() sets the pathname of the utmp-format file for the other
           utmp functions to access.  If **utmpname**() is not used to set the
           pathname 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 functions.
    
           **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.  The definition of this structure is shown in
           utmp(5).
    
           **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_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 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**(), and **getutline**() return a pointer to a
           _struct utmp_ on success, and NULL on failure (which includes the
           "record not found" case).  This _struct utmp_ is allocated in static
           storage, and may be overwritten by subsequent calls.
    
           On success **pututline**() returns _ut_ ; on failure, it returns NULL.
    
           **utmpname**() returns 0 if the new name was successfully stored, or
           -1 on failure.
    
           On failure, these functions _errno_ set to indicate the error.
    


## ERRORS



           **ENOMEM** Out of memory.
    
           **ESRCH** Record not found.
    
           **setutent**(), **pututline**(), and the **getut***() functions can also fail
           for the reasons described in open(2).
    


## FILES



           _/var/run/utmp_
                  database of currently logged-in users
    
           _/var/log/wtmp_
                  database of past user logins
    


## ATTRIBUTES



           For an explanation of the terms used in this section, see
           attributes(7).
           ┌─────────────┬───────────────┬──────────────────────────────────┐
           │ **Interface** │ **Attribute** │ **Value** │
           ├─────────────┼───────────────┼──────────────────────────────────┤
           │ **getutent**()  │ Thread safety │ MT-Unsafe init race:utent        │
           │             │               │ race:utentbuf sig:ALRM timer     │
           ├─────────────┼───────────────┼──────────────────────────────────┤
           │ **getutid**(),  │ Thread safety │ MT-Unsafe init race:utent        │
           │ **getutline**() │               │ sig:ALRM timer                   │
           ├─────────────┼───────────────┼──────────────────────────────────┤
           │ **pututline**() │ Thread safety │ MT-Unsafe race:utent sig:ALRM    │
           │             │               │ timer                            │
           ├─────────────┼───────────────┼──────────────────────────────────┤
           │ **setutent**(), │ Thread safety │ MT-Unsafe race:utent             │
           │ **endutent**(), │               │                                  │
           │ **utmpname**()  │               │                                  │
           └─────────────┴───────────────┴──────────────────────────────────┘
    
           In the above table, _utent_ in _race:utent_ signifies that if any of
           the functions **setutent**(), **getutent**(), **getutid**(), **getutline**(),
           **pututline**(), **utmpname**(), or **endutent**() are used in parallel in
           different threads of a program, then data races could occur.
    


## STANDARDS



           None.
    


## NOTES



       **glibc notes**
           The above functions are not thread-safe.  glibc adds reentrant
           versions
    
           **#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_**);**
    
           Feature Test Macro Requirements for glibc (see
           feature_test_macros(7)):
    
           **getutent_r**(), **getutid_r**(), **getutline_r**():
               _GNU_SOURCE
                   || /* Since glibc 2.19: */ _DEFAULT_SOURCE
                   || /* glibc <= 2.19: */    _SVID_SOURCE || _BSD_SOURCE
    
           These functions are GNU extensions, analogs of the functions of
           the same name without the _r suffix.  The _ubuf_ argument gives
           these functions 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.  There are no utmpx equivalents
           of the above functions.  (POSIX.1 does not specify such
           functions.)
    


## EXAMPLES



           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(3) and
           ttyname(3).
    
           #include <err.h>
           #include <pwd.h>
           #include <stdlib.h>
           #include <string.h>
           #include <time.h>
           #include <unistd.h>
           #include <utmp.h>
    
           int
           main(void)
           {
               struct utmp entry;
    
               if (system("echo before adding entry:;who") == -1)
                   err(EXIT_FAILURE, "system");
    
               entry.ut_type = USER_PROCESS;
               entry.ut_pid = getpid();
               strcpy(entry.ut_line, ttyname(STDIN_FILENO) + strlen("/dev/"));
               /* only correct for ptys named /dev/tty[pqr][0-9a-z] */
               strcpy(entry.ut_id, ttyname(STDIN_FILENO) + strlen("/dev/tty"));
               entry.ut_time = time(NULL);
               strcpy(entry.ut_user, getpwuid(getuid())->pw_name);
               memset(entry.ut_host, 0, UT_HOSTSIZE);
               entry.ut_addr = 0;
               setutent();
               if (pututline(&entry) == NULL)
                   err(EXIT_FAILURE, "pututline");
    
               if (system("echo after adding entry:;who") == -1)
                   err(EXIT_FAILURE, "system");
    
               entry.ut_type = DEAD_PROCESS;
               memset(entry.ut_line, 0, UT_LINESIZE);
               entry.ut_time = 0;
               memset(entry.ut_user, 0, UT_NAMESIZE);
               setutent();
               if (pututline(&entry) == NULL)
                   err(EXIT_FAILURE, "pututline");
    
               if (system("echo after removing entry:;who") == -1)
                   err(EXIT_FAILURE, "system");
    
               endutent();
               exit(EXIT_SUCCESS);
           }
    


* * *