putdevattrs Subroutine

Purpose

Modifies multiple device attributes in the privileged device database.

Library

Security Library (libc.a)

Syntax

#include <usersec.h>

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

Description

The putdevattrs subroutine modifies one or more attributes from the privileged device database. If the database is not open, this subroutine does an implicit open for reading and writing. The device that is specified by the Device parameter must include the full path to the device and exist in the privileged device database.

The putdevattrs subroutine is only used to modify attributes of existing devices in the database. To create or remove device entries, use the putdevattr subroutine instead. Data that is changed by the putdevattrs subroutine must be explicitly committed by calling the putdevattr subroutine with a Type parameter specifying SEC_COMMIT. Until all the data is committed, only the getdevattr and getdevattrs subroutines within the process return the modified data. Changes made to the privileged device database do not impact security considerations until the entire database is sent to the Kernel Security Tables by using the setkst device.

The Attributes parameter contains information about each attribute that is to be updated. Each value that is specified in the Attributes parameter must be examined on a successful call to the putdevattrs subroutine to determine whether the Attributes parameter was successfully written. The

dbattr_t
data

structure contains the following fields:

Table 1. `dbattr_t data` structure Fields
Item	Description
attr_name	The name of the device attribute to update.
attr_idx	This attribute is used internally by the putdevattrs subroutine.
attr_type	The type of the attribute being updated.
attr _flag	The result of the request to update the desired attribute. On success, a value of zero is returned. Otherwise, a nonzero value is returned.
attr_un	A union containing the value to update the requested attribute with.
attr_domain	This field is ignored by the putdevattrs subroutine.

The following valid privileged device attributes for the putdevattrs subroutine are defined in the usersec.h file:

Table 2. putdevattrs subroutine valid privileged device attributes
Name	Description	Type
`S_READPRIVS`	Privileges 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`	Privileges 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 union members that follows correspond to the definitions of the

attr_char, attr_int,
attr_long

and attr_llong macros in the usersec.h file respectively.

Table 3. Union members
Item	Description
au_char	A character pointer to the value to be written for attributes of the `SEC_CHAR` and `SEC_LIST` types.
au_int	Integer value to be written for attributes of the `SEC_INT` type.
au_long	Long value to be written for attributes of the `SEC_LONG` type.
au_llong	Long long value to be written for attributes of the `SEC_LLONG` type.

Parameters

Table 4. Parameters
Item	Description
`Device`	Specifies the device name for which the attributes are to be updated.
`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

Table 5. File Accessed
File	Mode
/etc/security/privdevs	`rw`

Return Values

If the device specified by the Device parameter exists in the privileged device database, the putdevattrs subroutine returns zero, even in the case when no attributes in the Attributes parameter were successfully updated. On success, the attr_flag attribute of each element in the Attributes parameter must be examined to determine whether it was successfully updated. On failure, a value of -1 is returned and the errno value is set to indicate the error.

Error Codes

If the putdevattrs subroutine returns -1, one of the following errno values can be set:

Table 6. Error Codes if the putdevattrs subroutine returns -1
Item	Description
`EINVAL`	The `Device` parameter is `NULL`, `default` or `ALL`.
`EINVAL`	The `Count` parameter is less than zero.
`EINVAL`	The `Attributes` parameter is `NULL` and the `Count` parameter is greater than zero.
`EINVAL`	The `Attributes` parameter does not point to valid data for the requested attribute.
`ENOENT`	The device that is specified in the `Device` parameter does not exist.
`EPERM`	The operation is not permitted.

If the putdevattrs subroutine fails to update an attribute, one of the following errors is returned in the attr_flag field of the corresponding to the value specified by the Attributes entry:

Table 7. Error codes if the putdevattrs subroutine fails
Item	Description
`EACCES`	The invoker does not have write access to the privileged device database.
`EINVAL`	The attr_name field in the `Attributes` entry is not a recognized privileged device attribute.
`EINVAL`	The attr_type field in the `Attributes` entry contains a type that is not valid.
`EINVAL`	The attr_un field in the `Attributes` entry does not point to a valid buffer or to valid data for this type of attribute.