endutent man page on SmartOS

Man page or keyword search:  
man Server   16655 pages
apropos Keyword Search (all sections)
Output format
SmartOS logo
[printable version]

GETUTENT(3C)							  GETUTENT(3C)

NAME
       getutent, getutid, getutline, pututline, setutent, endutent, utmpname -
       user accounting database functions

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
       These functions provide access to the user accounting  database,	 utmp.
       Entries	in  the	 database  are	described  by the definitions and data
       structures in <utmp.h>.

       The utmp structure contains the following members:

	 char		     ut_user[8];   /* user login name */
	 char		     ut_id[4];	   /* /sbin/inittab id */
					   /* (usually line #) */
	 char		     ut_line[12];  /* device name (console, lnxx) */
	 short		     ut_pid;	   /* process id */
	 short		     ut_type;	   /* type of entry */
	 struct exit_status  ut_exit;	   /* exit status of a process */
					   /* marked as DEAD_PROCESS */
	 time_t		     ut_time;	   /* time entry was made */

       The structure exit_status includes the following members:

	 short	 e_termination;	  /* termination status */
	 short	 e_exit;	  /* exit status */

   getutent()
       The getutent() function reads in the next entry from a  utmp  database.
       If  the	database  is not already open, it opens it.  If it reaches the
       end of the database, it fails.

   getutid()
       The getutid() function searches forward from the current point  in  the
       utmp  database  until  it  finds	 an  entry  with  a  ut_type  matching
       id->ut_type if the type specified  is  RUN_LVL,	BOOT_TIME,  DOWN_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 member matches id->ut_id. If the end of database is reached
       without a match, it fails.

   getutline()
       The getutline() function searches forward from the current point in the
       utmp database until it finds an entry  of  the  type  LOGIN_PROCESS  or
       ut_line	string	matching the line->ut_line string. If the end of data‐
       base is reached without a match, it fails.

   pututline()
       The pututline() function writes the supplied utmp  structure  into  the
       utmp  database.	 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 these functions.  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	database.   It
       returns	a  pointer  to	the  utmp structure. When called by a non-root
       user, pututline() invokes a setuid() root program to verify  and	 write
       the  entry,  since the utmp database is normally writable only by root.
       In this event, the ut_name member must correspond to  the  actual  user
       name  associated	 with  the process; the	 ut_type member must be either
       USER_PROCESS or DEAD_PROCESS; and the ut_line member must be  a	device
       special file and be writable by the user.

   setutent()
       The setutent() function resets the input stream to the beginning.  This
       reset should be done before each search	for  a	new  entry  if	it  is
       desired that the entire database be examined.

   endutent()
       The endutent() function closes the currently open database.

   utmpname()
       The utmpname() function allows the user to change the name of the data‐
       base file examined to another file.  If the file does not  exist,  this
       will  not  be apparent until the first attempt to reference the file is
       made.  The utmpname() function does not open the file  but  closes  the
       old file if it is currently open and saves the new file name.

RETURN VALUES
       A  null	pointer	 is returned upon failure to read, whether for permis‐
       sions or having reached the end of file, or upon failure to  write.  If
       the file name given is longer than 79 characters, utmpname() returns 0.
       Otherwise, it returns 1.

USAGE
       These functions use buffered standard I/O for  input,  but  pututline()
       uses  an unbuffered non-standard write to avoid race conditions between
       processes trying to modify the utmp and wtmp databases.

       Applications should not access the utmp and  wtmp  databases  directly,
       but should use these functions to ensure that these databases are main‐
       tained consistently. Using these functions, however, may cause applica‐
       tions to fail if user accounting data cannot be represented properly in
       the utmp structure (for example, on a  system  where  PIDs  can	exceed
       32767).	 Use  the functions described on the getutxent(3C) manual page
       instead.

ATTRIBUTES
       See attributes(5) for descriptions of the following attributes:

       ┌───────────────┬─────────────────┐
       │ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
       ├───────────────┼─────────────────┤
       │MT-Level       │ Unsafe		 │
       └───────────────┴─────────────────┘

SEE ALSO
       getutxent(3C), ttyslot(3C), utmpx(4), attributes(5)

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 function 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.
       For this reason, to use getutline() to search for multiple occurrences,
       it would be necessary to zero out the static area after	each  success,
       or  getutline()	would  just  return  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() functions, if the  user  has  just
       modified those contents and passed the pointer back to pututline().

				 Oct 27, 1998			  GETUTENT(3C)
[top]

List of man pages available for SmartOS

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net