Click this button to go to the index for this section.

getprtcent(3)
NAME
  getprtcent, getprtcnam, putprtcnam - Manipulate terminal control database
  entry (Enhanced Security)

LIBRARY
  Security Library (libsecurity.a)

SYNOPSIS
  #include <sys/types.h>
  #include <sys/security.h>
  #include <prot.h>
  struct pr_term *getprtcent(void);
  struct pr_term *getprtcnam(
	  char *name);
  void setprtcent(void);
  void endprtcent(void);
  int putprtcnam(
	  char *name,
	  struct pr_term *pr);

PARAMETERS
  name	    Specifies a terminal control database entry name.

  pr	    Specifies a terminal control database control entry structure.

DESCRIPTION
  The getprtcent() and getprtcnam() 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 pr_term structure, declared in the prot.h header file as
  follows:

       struct	t_field	 {
	       char    fd_devname[14]; /* terminal (or host) name */
	       uid_t   fd_uid;	       /* uid of last successful login */
	       time_t  fd_slogin;      /* time stamp of successful login */
	       uid_t   fd_uuid;	       /* uid of last unsuccessful login */
	       time_t  fd_ulogin;      /* time stamp of unsuccessful login */
	       uid_t   fd_loutuid;     /* uid of last logout */
	       time_t  fd_louttime;    /* time stamp of logout */
	       ushort  fd_nlogins;     /* consecutive failed attempts */
	       ushort  fd_max_tries;   /* max 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;       /* entry for an X display (xdm) */
	       ushort  fd_login_timeout;      /* login timeout in seconds */
       };

       struct  t_flag  {
	       unsigned short
		       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_login_timeout:1      /* fd_login_timeout valid? */
		       ;
       };

       struct  pr_term	{
	       struct t_field ufld;
	       struct t_flag uflg;
	       struct t_field sfld;
	       struct t_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 getprtcent() or getprtcnam() 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 structure assignment and supply the modified buffer to putprtcnam().

  The getprtcent() function returns a pointer to the first terminal pr_term
  structure in the database when first called. Thereafter, it returns a
  pointer to the next pr_term structure in the database, so successive calls
  can be used to search the database.  The getprtcnam() 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 putprtcnam() function puts a new or replaced terminal control entry pr
  with key name into the database.  If the fg_devname field is 0 (zero), the
  requested entry is deleted from the terminal control database.  The
  putprtcnam() function locks the database for all update operations, and
  calls the endprtcent() function after the update or failed attempt.

NOTES
  The fd_devname field, on systems supporting connections, may refer to the
  ASCII representation of a host name. This can be determined by using the
  getdvagnam() function to interrogate the device assignment database as to
  the type of the device, passing in the fd_devname field of the terminal
  control structure as an argument. This allows a lockout by machine, instead
  of the device (typically, a pseudo terminal) on which the session
  originated.

  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
  getprpwent() and getdvagent() reference pages).


RETURN VALUES
  The getprtcent() and getprtcnam() functions return null pointers on EOF or
  an error.  The putprtcnam() function returns a value of 0 (zero) if it
  cannot add or update the entry.

FILES
  /etc/auth/system/ttys
		      Terminal control database.

  /etc/auth/system/default
		      System defaults database.

  /usr/include/prot.h General security databases file.

RELATED INFORMATION
  Functions: getprdfent(3).

  Files: authcap(4), ttys(4).