getdvagent(3)						     Library Functions Manual						     getdvagent(3)

NAME

       getdvagent(),  getdvagnam(),  setdvagent(),  enddvagent(),  putdvagnam(), copydvagent() - manipulate device assignment database entry for a
       trusted system

SYNOPSIS

DESCRIPTION

       and each return a pointer 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 structure, declared in the header file:

	      struct dev_field {
		   char      *fd_name;	      /* external name */
		   char      **fd_devs;       /* device list */
		   mask_t    fd_type[1];      /* tape, printer, terminal */
		   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_MAX_DEV_TYPE       3
	      #define AUTH_DEV_TYPE_SIZE      (WORD_OF_BIT (AUTH_MAX_DEV_TYPE) + 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_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 user authorizations and 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
       corresponding  to  that	device.   This	list allows the device assignment software of the trusted system to invalidate all references to a
       device when re-assigning it.  The list is a table of character string pointers, whose last entry is a NULL pointer.

       fd_users is a pointer to a null-terminated table of character string pointers referring to user allowed access.

       For trusted 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 zeroes.  For example, a host with Internet address 129.75.0.3
       has device name 814b00030000.  The trailing four zeroes are for compatibility with ports on terminal concentrators.  The SAM API's supports
       conversion of host name to device name.	Thus, sensitivity level ranges and user authorization lists can be enforced on hosts as well as on
       directly connected terminals.

       When 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.  searches from the beginning of the database until an entry with a device name match-
       ing 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.	copies a device assignment structure and the fields to which it refers to a newly-allocated data area.	Since and re-use a
       static structure when accessing the database, the values of any entry must be saved if these routines are used again.  The  dev_asg  struc-
       ture returned by can be freed using free (see malloc(3C)).

       A  call	to  has  the  effect of setting the device assignment database back to the first entry to allow repeated searches of the database.
       frees all memory and closes all files used to support these routines.

       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 this routine must be compiled with

APPLICATION USAGE

       In  a  multithreaded  application,  these  routines  are safe to be called only from one dedicated thread.  These routines are not POSIX.1c
       async-cancel safe nor async-signal safe.

RETURN VALUE

       and return a pointer to a static structure on success, or a NULL pointer on failure.  This static structure is overwritten by and

       returns 1 on success, or 0 on failure.

       returns a pointer to the newly-allocated structure on success, or a NULL pointer if there was a memory allocation error.

WARNINGS

       The structure returned by this routine contains pointers to character strings and lists rather than being  self-contained.   must  be  used
       instead of structure assignments to save a returned structure.

       The  value  returned  by  and  refers  to a structure that is overwritten by calls to these routines.  To retrieve an entry, modify it, and
       replace it in the database, copy the entry using and supply the modified buffer to

       HP-UX 11i Version 3 is the last release to support trusted systems functionality.

FILES

       Device assignment database

SEE ALSO

       authcap(4).

								  TO BE OBSOLETED						     getdvagent(3)