getdvagent(S) 6 January 1993 getdvagent(S) Name getdvagent, getdvagnam, setdvagent, enddvagent, putdvagnam, copydvagent - manipulate device assignment database entry Syntax cc . . . -lprot -lx #include <sys/types.h> #include <sys/security.h> #include <sys/audit.h> #include <prot.h> struct dev_asg *getdvagent() struct dev_asg *getdvagnam (name) char *name; void setdvagent() void enddvagent() int putdvagnam (name, dv) char *name; struct dev_asg *dv; struct dev_asg *copydvagent(dv) struct dev_asg *dv; Description The getdvagent, getdvagnam, and copydvagent routines return pointers to an object with the following structure containing the broken-out fields of an entry in the device assignment database. Each database entry is returned as a pointer to a devasg structure, declared in the <prot.h> header file: struct dev_asg { struct dev_field ufld; struct dev_flag uflg; struct dev_field sfld; struct dev_flag sflg; }; struct dev_field { char *fd_name; /* external name */ char **fd_devs; /* device list */ mask_t fd_type[AUTH_DEV_TYPE_SIZE]; /* tape, printer, terminal */ char **fd_users; /* list of users */ }; /* bit offsets for fd_type: */ #define AUTH_DEV_PRINTER 0 /* device is a printer (lp) */ #define AUTH_DEV_TERMINAL 1 /* device is a terminal (login) */ #define AUTH_DEV_TAPE 2 /* device can import/export data */ /* this structure tells which of the corresponding /* /* fields in dev_field are valid (filled). */ struct dev_flag { unsigned fg_name : 1, fg_devs : 1, fg_type : 1, fg_users: 1; }; The device assignment database stores the relationship between device pathnames and real devices. 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. Device drivers typically use different minor device numbers to correspond to different options on the same device, for example, modem control on terminals or densities on tape drives. This list allows the device assignment soft- ware of the security management program (SMP) to invalidate all refer- ences to a device when reassigning it. The list is a table of character string pointers, whose last entry is a NULL pointer. When first called, the getdvagent routine returns a pointer to the first device assignment entry. Thereafter, it returns a pointer to the next entry in the database. So, successive calls can be used to search the database. The getdvagnam routine searches from the beginning of the database until an entry with a device whose name matches the argument name is found, and returns a pointer to that entry. The copydvagent routine copies a device assignment structure and the fields to which it refers to a newly allocated data area. The devasg structure returned by copydvagent may be freed using free (see malloc(S)). A call to the setdvagent routine sets the device assignment database back to the first entry, to allow repeated searches of the database. The enddvagent routine frees all memory and closes all files used to support these routines. The putdvagnam routine rewrites or adds an entry to the database. If there is an entry whose fdname field matches the name argument, that entry is replaced with the contents of the dv structure. Otherwise, that entry is added to the end of the database. Return value getdvagent and getdvagnam return a pointer to a static structure on suc- cess, or a NULL pointer on failure This static structure is overwritten by getdvagent, getdvagnam, and putdvagnam. putdvagnam returns 1 on suc- cess, or 0 on failure. copydvagent returns a pointer to the newly allo- cated structure on success, or a NULL pointer if there was a memory allo- cation error. There are no return values or errors defined for either the setdvagent or the enddvagent routines. Note Since the getdvagent, getdvagnam, and putdvagnam routines reuse a static structure when accessing the database, the values of any entry must be saved if these routines are used again. Files /etc/auth/system/devassign Standards conformance getdvagent is not part of any currently supported standard; it is an extension of AT&T System V provided by the Santa Cruz Operation.