putpfileattrs Subroutine

Purpose

Updates multiple file attributes in the privileged files database.

Library

Security Library (libc.a)

Syntax

#include <usersec.h>

int putpfileattrs(File, Attributes, Count)
    char *File;
    dbattr_t *Attributes;
    int Count;

Description

The putpfileattrs subroutine modifies one or more attributes from the privileged files database (/etc/security/privfiles). If the database is not open, this subroutine opens the database implicitly for reading and writing. The file specified by the File parameter must include the full path to the file and exist in the privileged file database.

The putpfileattrs subroutine is only used to modify attributes of existing files in the database. To create or remove file entries, use the putpfileattr subroutine instead. Data changed by the putpfileattrs subroutine must be explicitly committed by calling the putpfileattr subroutine with a Type parameter specifying SEC_COMMIT. Until all the data is committed, only the getpfileattr and getpfileattrs subroutines within the process return the modified data.

The Attributes array contains information about each attribute that is to be updated. Each element in the Attributes array must be examined on a successful call to the putpfileattrs subroutine to determine if the Attributes array was successfully written. The dbattr_t data structure contains the following fields:
Item Description
attr_name The name of the file attribute to update.
attr_idx This attribute is used internally by the putpfileattrs 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.
Valid privileged file attributes for the putpfileattrs subroutine defined in the usersec.h file are:
Name Description Type
S_PRIVFILES Retrieves all the files in the privileged file database. It is valid only when the File parameter is ALL. SEC_LIST
S_READAUTHS Read authorization. It is a null separated list of authorization names. A total of eight authorizations can be specified. A user with any one of the authorizations is allowed to read the file using the privileged editor /usr/bin/pvi. SEC_LIST
S_WRITEAUTHS Write authorization. It is a null separated list of authorization names. A total of eight authorizations can be specified. A user with any one of the authorizations is allowed to write the file using the privileged editor /usr/bin/pvi. SEC_LIST
The union members that follow correspond to the definitions of the attr_char, attr_int, attr_long and attr_llong macros in the usersec.h file respectively.
Item Description
au_char A character pointer to the value to be written for attributes of the SEC_CHAR and SEC_LIST types. If the pointer is to the allocated memory, the caller is responsible for freeing the memory.
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

Item Description
File Specifies the file name for which the attributes are to be updated.
Attributes A pointer to an array of none or more than one element of the dbattr_t type. The list of file attributes is defined in the usersec.h header file.
Count The number of array elements in the Attributes array.

Security

Files Accessed:
File Mode
/etc/security/privfiles rw

Return Values

If the file specified by the File parameter exists in the privileged file database, the putpfileattrs subroutine returns a value of zero, even when no attributes in the Attributes array were successfully updated. On success, the attr_flag attribute of each element in the Attributes array must be examined to determine if it was successfully updated. If the specified file does not exist in the database, a value of -1 is returned and the errno value is set to indicate the error.

Error Codes

If the putpfileattrs subroutine returns -1, one of the following errno values can be set:
Item Description
EINVAL The File 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 file specified in the File parameter does not exist.
EPERM The operation is not permitted.
If the putpfileattrs subroutine fails to update an attribute, one of the following errors is returned in the attr_flag field of the corresponding Attributes element:
Item Description
EACCES The invoker does not have write access to the privileged file database.
EINVAL The attr_name field in the Attributes entry is not a recognized privileged file attribute.
EINVAL The attr_type field in the Attributes entry contains an invalid type.
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.