Purpose
Retrieves
multiple device attributes from the privileged device database.
Library
Security
Library (libc.a)
Description
The getdevattrs subroutine
reads one or more attributes from the privileged device database.
The device specified with the Device parameter must include
the full path to the device and exist in the privileged device database.
If the database is not open, this subroutine does an implicit open
for reading.
The
Attributes parameter
contains information about each attribute that is to be read. Each
element in the
Attributes parameter must
be examined on a successful call to the
getdevattrs subroutine
to determine whether the
Attributes parameter
was successfully retrieved. The values of the
SEC_CHAR or
SEC_LIST attributes
that are successfully returned are in the allocated memory. Caller
need to free this memory after use. The
dbattr_t data structure
contains the following fields:
Item |
Description |
attr_name |
The name of the target device
attribute. |
attr_idx |
This attribute is used internally
by the getdevattrs subroutine. |
attr_type |
The type of the target attribute. |
attr _flag |
The result of the request to
read the target attribute. On successful completion, the value of
zero is returned. Otherwise, a nonzero value is returned. |
attr_un |
A union that contains the returned
values for the requested query. |
attr_domain |
The subroutine ignores any
input to this field. If this field is set to null, the subroutine
sets this field to the name of the domain where the device is found. |
The following valid privileged device attributes for
the
getdevattrs subroutine are defined in the
usersec.h file:
Name |
Description |
Type |
S_PRIVDEVS |
Retrieves
all the devices in the privileged device database. It is valid only
when the Device parameter is set to ALL. |
SEC_LIST |
S_READPRIVS |
The privileges
that are required to read from the device. Eight privileges can be
defined. A process with any of the read privileges is allowed to read
from the device. |
SEC_LIST |
S_WRITEPRIVS |
The privileges
that are required to write to the device. Eight privileges can be
defined. A process with any of the write privileges is allowed to
write to the device. |
SEC_LIST |
The following union members correspond to the definitions
of the
attr_char,
attr_init,
attr_long and the
attr_llong macros
in the
usersec.h file respectively.
Item |
Description |
au_char |
The attributes
of the SEC_CHAR and SEC_LIST types store a pointer to
the returned value in this member when the attributes are successfully
retrieved. Caller need to free this memory. |
au_int |
The storage
location for attributes of the SEC_INT type. |
au_long |
The storage
location for attributes of the SEC_LONG type. |
au_llong |
The storage
location for attributes of the SEC_LLONG type. |
If ALL is specified for the Device parameter,
the S_PRIVDEVS attribute is the only valid attribute that is
displayed in the Attribute parameter. Specifying
any other attribute with a device name of ALL causes the getdevattrs subroutine
to fail.
Parameters
Item |
Description |
Device |
Specifies the device for which the attributes
are to be read. |
Attributes |
A pointer to an array of zero or more elements
of the dbattr_t type. The list of device attributes is defined
in the usersec.h header file. |
Count |
The number of array elements in the Attributes parameter. |
Security
Files
Accessed: File |
Mode |
/etc/security/privdevs |
r |
Return Values
If
the device that is specified by the Device parameter exists
in the privileged device database, the getdevattrs subroutine
returns zero. On successful completion, the attr_flag attribute
of each element in the Attributes parameter
must be examined to determine whether it was successfully retrieved.
On failure, a value of -1 is returned and the errno value is
set to indicate the error.
Error Codes
If the
getdevattrs subroutine
returns -1, one of the following
errno values is set:
Item |
Description |
EINVAL |
The Device parameter is NULL or default. |
EINVAL |
The Device parameter is ALL,
but the Attributes parameter contains an
attribute other than S_PRIVDEVS. |
EINVAL |
The Count parameter is less than zero. |
EINVAL |
The Device parameter is NULL and
the Count parameter is greater than zero. |
ENOENT |
The device specified in the Device parameter
does not exist. |
EPERM |
The operation is not permitted. |
If the
getdevattrs subroutine fails to query
an attribute, one of the following errors is returned to the
attr_flag field
of the corresponding
Attributes element:
Item |
Description |
EACCES |
The invoker does not have access to the attribute
specified in the attr_name field. |
EINVAL |
The attr_name field in the Attributes parameter
is not a recognized device attribute. |
EINVAL |
The attr_type field in the Attributes parameter
contains a type that is not valid. |
EINVAL |
The attr_un field in the Attributes parameter
does not point to a valid buffer. |
ENOATTR |
The attr_name field in the Attributes parameter
specifies a valid attribute, but no value is defined for this device. |
ENOMEM |
Memory cannot be allocated to store the return
value. |