HP-UX Reference (11i v2 04/09) - 3 Library Functions A-M (vol 6)

g
getdvagent(3) getdvagent(3)
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
getdvagent 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.
getdvagnam
searches from the beginning of the database until an entry with a 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 func-
tions return a
NULL pointer. copydvagent copies a device assignment structure and the fields to
which it refers to a newly-allocated data area. Since
getdvagent,
getdvagnam, and putdvagent
re-use a static structure when accessing the database, the values of any entry must be saved if these rou-
tines are used again. The dev_asg structure returned by
copydvagent can be freed using free (see
malloc(3C)).
A call to
setdvagent has the effect of setting the device assignment database back to the first entry to
allow repeated searches of the database. enddvagent frees all memory and closes all files used to sup-
port these routines.
putdvagnam 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.
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
getdvagent and getdvagnam return a pointer to a static structure on success, or a NULL pointer on
failure. This static structure is overwritten by getdvagent, getdvagnam, and putdvagnam.
putdvagnam returns 1 on success, or 0 on failure.
copydvagent 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.
copydvagent must be used instead of structure assignments to save a returned struc-
ture.
The value returned by
getdvagent and getdvagnam 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
copydvagent and supply the modified buffer to putdvagent.
NOTES
Programs using this routine must be compiled with
-lsec.
FILES
/tcb/files/devassign Device assignment database
SEE ALSO
authcap(4).
HP-UX 11i Version 2: September 2004 − 2 − Hewlett-Packard Company Section 3−−379