getesdvent(3)getesdvent(3)NAME
getesdvent, getesdvnam, setdvagent, enddvagent, putesdvnam, copyesd‐
vent, getdvagent, getdvagnam, putdvagnam, copydvagent - Manipulate
device assignment database entry (Enhanced Security)
SYNOPSIS
#include <sys/types.h> #include <sys/security.h> #include <prot.h>
struct esdev_asg *getesdvent(
void ); struct esdev_asg *getesdvnam(
char *name ); void setdvagent(
void ); void enddvagent(
void ); int putesdvnam(
char *name,
struct esdev_asg *dv ); struct esdev_asg *copyesdvent(
struct esdev_asg *dv );
Note
The getdvagent(), getdvagnam(), putdvagnam(), and copydvagent() rou‐
tines have been replaced by getesdvent(), getesdvnam(), putesdvnam(),
and copyesdvent() 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
A cross-reference to the terminal control database. Contains a device
assignment structure.
DESCRIPTION
The getesdvent(), getesdvnam(), and copyesdvent() functions each return
a pointer to an object with the following structure containing the sep‐
arated-out fields of an entry in the device assignment database. Each
database entry is returned as a esdev_asg structure, declared in the
prot.h header file as follows:
/* Device Assignment Database entry */
struct esdev_field {
char *fd_name; /* external name */
char **fd_devs; /* device list */
mask_t *fd_type; /* tape, printer, terminal */
mand_ir_t *fd_max_sl; /* maximum sensitivity level */
mand_ir_t *fd_min_sl ; /* minimum sensitivity level */
mand_ir_t *fd_cur_sl ; /* currently assigned s.l. */
ilb_ir_t *fd_cur_il ; /* currently assigned info l. */
mask_t *fd_assign; /* single-, multilevel, etc. */
char **fd_users ; /* list of users */ };
struct esdev_flag {
unsigned int
fg_name : 1,
fg_devs : 1,
fg_type : 1,
fg_max_sl : 1,
fg_min_sl : 1,
fg_cur_sl : 1,
fg_cur_il : 1,
fg_assign : 1,
fg_users : 1; };
struct esdev_asg {
AUTH_ESCAP_COMMON
size_t fieldlen;
struct esdev_field *ufld;
struct esdev_flag *uflg;
struct esdev_field *sfld;
struct esdev_flag *sflg; };
Each entry contains a name, which is a cross-reference to the terminal
control database, and a list of devices, each of which is a pathname
that corresponds to that device. The list is a table of character
string pointers, whose last entry is a null pointer.
The fd_type fields are bit masks that can be manipulated with the
ADDBIT(), RMBIT(), and ISBITSET() macros. The fd_users field is a
pointer to a null-terminated table of character string pointers refer‐
ring to user allowed access.
When the getesdvent() function is first called, it returns a pointer to
the first device assignment entry. Thereafter, it returns a pointer to
the next entry, so successive calls can be used to search the database.
The getesdvnam() function searches from the beginning of the database
until an entry with device name matching name is found, and returns a
pointer to that entry. If an end-of-file or an error is encountered on
reading, these functions return a null pointer.
The copyesdvent() function copies dv, and the fields to which it
refers, to a newly allocated data area. Because the getesdvent(),
getesdvnam(), and putesdvent() functions reuse a static structure when
accessing the database, the values of any entry must be saved if the
database routines are used again. The esdev_asg structure returned by
copyesdvent() can be freed using the free() function.
A call to the setdvagent() function has the effect of setting the
device assignment database back to the first entry, to allow repeated
searches of the database. The enddvagent() function frees all memory
and closes all files used to support the database routines.
The putesdvnam() function rewrites or adds an entry to the database. If
there is an entry whose fd_name field matches the name argument, that
entry is replaced with the contents of the dv structure. Otherwise,
that entry is added to the database.
NOTES
Programs using the database routines must be compiled with -lsecurity.
RETURN VALUES
The getesdvent() and getesdvnam() functions return a pointer to a
static structure on success, or a null pointer on failure. This static
structure is overwritten by the getesdvent(), getesdvnam(), and putesd‐
vnam() functions. The putesdvnam() function returns a value of 1 on
success, or a value of 0 (zero) on failure. The copyesdvent() function
returns a pointer to the newly allocated structure on success, or a
null pointer if there was a memory allocation error.
CAUTIONS
Structures returned by the database routines contain pointers to char‐
acter strings and lists rather than being self-contained. The copyesd‐
vent() function must be used rather than doing a structure assignment
to save a returned structure.
The value returned by the getesdvent() and getesdvnam() functions
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 the copyesdvent() function and supply the
modified buffer to the putesdvent() function.
FILES
File containing device assignment entries.
SEE ALSO
Functions: auth_for_terminal_es(3)
Files: authcap(4), devassign(4)
Security
getesdvent(3)