getestcent(3)getestcent(3)NAME
getestcent, getestcnam, setprtcent, endprtcent, putestcnam, getprtcent,
getprtcnam, putprtcnam, copyestcent - Manipulate terminal control data‐
base entry (Enhanced Security)
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 ); struct es_term *copyestcent(
struct es_term *pr );
Note
The getprtcent(), getprtcnam(), and getprtcnam() routines have been
replaced by getestcent(), getestcnam(), putestcnam() respectively.
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.
PARAMETERS
Specifies a terminal control database entry name. Specifies a terminal
control database control entry structure.
DESCRIPTION
The getestcent(), getestcnam(), and copyestcent() functions return a
pointer to an object with the following structure containing the sepa‐
rated-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.
The copyestcent() function copies pr, and the fields to which it
refers, to a newly allocated data area. Because the getescent() and
putescent() functions reuse a static structure when accessing the data‐
base, the values of any entry must be saved if the database routines
are used again. The es_term structure returned by getestcent() can be
freed using the free() function.
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 com‐
plete.
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 data‐
base. The putestcnam() function locks the database for all update oper‐
ations, and calls the endprtcent() function after the update or failed
attempt.
NOTES
Structures returned by the database routines contain pointers to char‐
acter 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).
CAUTIONS
Structures returned by the database routines contain pointers to char‐
acter strings and lists rather than being self-contained. The copyest‐
cent() function must be used rather than doing a structure assignment
to save a returned structure.
The value returned by the getestcent() and getestcnam() functions
refers to a structure that is overwritten by calls to the function. To
retrieve an entry, modify it, and replace it in the database, you must
copy the entry using the copyestcent() function and supply the modified
buffer to the putestcent() function.
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.
The copyestcent() function returns a pointer, or NULL on (allocation)
error.
FILES
Terminal control database. System defaults database. General security
include file.
SEE ALSO
Functions: getesdfent(3), getespwent(3), getesdvent(3)
Files: authcap(4), ttys(4)
Security
getestcent(3)