getestcent(3)						     Library Functions Manual						     getestcent(3)

NAME

       getestcent, getestcnam, setprtcent, endprtcent, putestcnam, getprtcent, getprtcnam, putprtcnam - Manipulate terminal control database entry
       (Enhanced Security)

LIBRARY

       Security Library (libsecurity.so)

       NOTE: In order to quickstart a program, the program must be linked as follows:

	    -lsecurity -ldb -laud -lm

       See the shared library discussion in the Programmer's Guide for more information about using the quickstarting feature.

SYNOPSIS

       #include <sys/types.h>
       #include <sys/security.h>
       #include <prot.h>
       struct es_term *getestcent(void);
       struct es_term *getestcnam(
	    char *name);
       void setprtcent(void);
       void endprtcent(void);
       int putestcnam(
	    char *name,
	    struct es_term *pr);

       NOTE:  The getprtcent(), getprtcnam(), and getprtcnam() routines have been replaced by  getestcent(),  getestcnam(),  putestcnam()  respec-
       tively.

PARAMETERS

       Specifies a terminal control database entry name.  Specifies a terminal control database control entry structure.

DESCRIPTION

       The  getestcent()  and  getestcnam() functions both return a pointer to an object with the following structure containing the separated-out
       fields of an entry in the terminal control database.  Each entry in the database contains a  es_term  structure,  declared  in  the  prot.h
       header file as follows: /*  Terminal Control Database Entry  */

       struct  estc_field  {
	       char    *fd_devname;    /* Device/host name */
	       uid_t   fd_uid;	       /* uid of last successful login */
	       time_t  fd_slogin;      /* time stamp of   "	   " */
	       uid_t   fd_uuid;        /* uid of last unsuccessful login */
	       time_t  fd_ulogin;      /* time stamp of  "	     " */
	       uid_t   fd_loutuid;     /* uid of last logout */
	       time_t  fd_louttime;    /* time stamp of   "    */
	       int     fd_nlogins;     /* consecutive failed attempts */
	       int     fd_max_tries;   /* maximum unsuc login tries allowed */
	       time_t  fd_logdelay;    /* delay between login tries */
	      time_t  fd_unlockint;    /* delay before clearing t_failures */
	       char    fd_lock;        /* terminal locked? */
	       char    fd_xdisp;       /* this entry is for X display (xdm) */
	       time_t  fd_login_timeout ;   /* login timeout in seconds */ };

       struct  estc_flag  {
	       unsigned int
		       fg_devname:1,	     /* Is fd_devname set? */
		       fg_uid:1,	     /* Is fd_uid set? */
		       fg_slogin:1,	     /* Is fd_stime set? */
		       fg_uuid:1,	     /* Is fd_uuid set? */
		       fg_ulogin:1,	     /* Is fd_ftime set? */
		       fg_loutuid:1,	     /* Is fd_loutuid set? */
		       fg_louttime:1,	     /* Is fd_louttime set? */
		       fg_nlogins:1,	     /* Is fd_nlogins set? */
		       fg_max_tries:1,	     /* Is fd_max_tries set? */
		       fg_logdelay:1,	     /* Is fd_logdelay set? */
		       fg_lock:1,	     /* Is fd_lock set? */
		       fg_unlockint:1,	     /* Is fd_unlockint set? */
		       fg_login_timeout : 1, /* is fd_login_timeout valid? */
		       fg_xdisp : 1	     /* Is fd_xdisp valid ? */
		       ; };

       struct  es_term	{
	       AUTH_ESCAP_COMMON
	       size_t		       fieldlen;
	       struct estc_field       *ufld;
	       struct estc_flag        *uflg;
	       struct estc_field       *sfld;
	       struct estc_flag        *sflg; };

       Note  that  in  the previous example ufld and uflg refer to user-specific entries, and sfld and sflg refer to the system default values For
       more information on the system default values, see the default(4) reference page.

       The value returned by the getestcent() or getestcnam() function refers to a structure that is overwritten by calls to these  functions.	To
       retrieve an entry, modify it, and replace it in the database, you must copy the entry using copyestcent() and supply the modified buffer to
       putestcnam().

       The getestcent() function returns a pointer to the first terminal es_term structure in the  database  when  first  called.  Thereafter,	it
       returns	a pointer to the next es_term structure in the database, so successive calls can be used to search the database.  The getestcnam()
       function searches from the beginning of the database until a terminal name matching name is found, and returns a pointer to the	particular
       structure in which it was found.  If an end-of-file or an error is encountered on reading, these functions return a null pointer.

       A call to setprtcent() has the effect of rewinding the terminal control database to allow repeated searches.  The endprtcent() function can
       be called to close the terminal control database when processing is complete.

       The putestcnam() function puts a new or replaced terminal control entry pr with key name into the database.  If the uflg->fg_devname  field
       is  0  (zero),  the  requested  entry  is deleted from the terminal control database.  The putestcnam() function locks the database for all
       update operations, and calls the endprtcent() function after the update or failed attempt.

NOTES

       Structures returned by the database routines contain pointers to character strings and lists rather than being  self-contained.	 The  copy
       function must be used rather than doing a structure assignment to save a returned structure.

       Programs using these functions must be compiled with -lsecurity.

       The  sfld  and sflg structures are filled from corresponding fields in the system default database.  Thus, a program can easily extract the
       user-specific or system-wide parameters for each database field (see the getespwent(3) and getesdvent(3) reference pages).

RETURN VALUES

       The getestcent() and getestcnam() functions return null pointers on EOF or an error.  The putestcnam() function returns a value of 0 (zero)
       if it cannot add or update the entry.

FILES

       Terminal control database.  System defaults database.  General security include file.

RELATED INFORMATION

       Functions: getesdfent(3), getespwent(3), getesdvent(3)

       Files: authcap(4), ttys(4)

       Security delim off

																     getestcent(3)