 |
Index for Section 3 |
|
 |
Alphabetical listing for G |
|
getdvagent(3)
NAME
getdvagent, getdvagnam, putdvagnam, copydvagent - Manipulate device
assignment database entry (Enhanced Security)
LIBRARY
Security Library (libsecurity.a)
SYNOPSIS
#include <sys/types.h>
#include <sys/security.h>
#include <prot.h>
struct dev_asg *getdvagent(void);
struct dev_asg *getdvagnam(
char *name);
void setdvagent(void);
void enddvagent(void);
int putdvagnam(
char *name,
struct dev_asg *dv);
struct dev_asg *copydvagent(
struct dev_asg *dv);
PARAMETERS
name A cross-reference to the terminal control database.
dv Contains a device assignment structure.
DESCRIPTION
The getdvagent(), getdvagnam(), and copydvagent() functions each return a
pointer to an object with the following structure containing the
separated-out fields of an entry in the device assignment database. Each
database entry is returned as a dev_asg structure, declared in the prot.h
header file as follows:
struct dev_field {
char *fd_name; /* external name */
char **fd_devs; /* device list */
mask_t fd_type[1]; /* tape, printer, terminal */
mask_t fd_assign[1]; /* single-lvl, multlvl, etc. */
char **fd_users; /* authorized user list */
};
/* Device Assignment Database entry */
#define AUTH_DEV_TYPE "device type"
#define AUTH_DEV_PRINTER 0
#define AUTH_DEV_TERMINAL 1
#define AUTH_DEV_TAPE 2
#define AUTH_DEV_REMOTE 3
#define AUTH_DEV_XDISPLAY 4
#define AUTH_MAX_DEV_TYPE 4
#define AUTH_DEV_TYPE_SIZE (WORD_OF_BIT (AUTH_MAX_DEV_TYPE) + 1)
#define AUTH_DEV_ASSIGN "device assignment"
#define AUTH_DEV_IMPORT 4 /* enabled for import */
#define AUTH_DEV_EXPORT 5 /* enabled for export */
#define AUTH_DEV_PASS 6 /* *internal* to mltape */
#define AUTH_MAX_DEV_ASSIGN 6
#define AUTH_DEV_ASSIGN_SIZE (WORD_OF_BIT (AUTH_MAX_DEV_ASSIGN) + 1)
/* this structure tells which of the corresponding fields in dev_field
* are valid (filled).
*/
struct dev_flag {
unsigned short
fg_name : 1,
fg_devs : 1,
fg_type : 1,
fg_assign : 1,
fg_users : 1,
;
};
struct dev_asg {
struct dev_field ufld;
struct dev_flag uflg;
struct dev_field sfld;
struct dev_flag sflg;
};
The device assignment database stores device characteristics that are
related to synonyms. On systems supporting network connections, the device
assignment database stores information about hosts initiating connections.
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. This list allows the device assignment
software to invalidate all references to a device when reassigning it. 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 referring to user allowed
access.
For system versions supporting network connections, the device name can be
a 12 character host name, where the first 8 characters are the ASCII hex
address of the device, and the last 4 characters are ASCII zeros. For
example, a host with Internet address 129.75.0.3 has device name
814b00030000. The trailing four zeros are for compatibility with ports on
terminal concentrators.
When the getdvagent() 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
getdvagnam() 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 copydvagent() function copies dv, and the fields to which it refers, to
a newly allocated data area. Because the getdvagent(), getdvagnam(), and
putdvagent() 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 dev_asg structure returned by copydvagent() 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 putdvagnam() 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.
CAUTIONS
Structures returned by the database routines contain pointers to character
strings and lists rather than being self-contained. The copydvagent()
function must be used rather than doing a structure assignment to save a
returned structure.
The value returned by the getdvagent() and getdvagnam() 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 copydvagent() function and supply the modified buffer to the
putdvagent() function.
RETURN VALUES
The getdvagent() and getdvagnam() functions return a pointer to a static
structure on success, or a null pointer on failure. This static structure
is overwritten by the getdvagent(), getdvagnam(), and putdvagnam()
functions. The putdvagnam() function returns a value of 1 on success, or a
value of 0 (zero) on failure. The copydvagent() function returns a pointer
to the newly allocated structure on success, or a null pointer if there was
a memory allocation error.
FILES
/etc/auth/system/devassign
File containing device assignment entries.
RELATED INFORMATION
Files: authcap(4).