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. |