getdevattrs Subroutine

Purpose

Retrieves multiple device attributes from the privileged device database.

Library

Security Library (libc.a)

Syntax

#include <usersec.h>

int getdevattrs(Device, Attributes, Count)
    char *Device;
    dbattr_t *Attributes;
    int Count;

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.