Purpose
Retrieves
multiple file attributes from the privileged file database.
Library
Security
Library (libc.a)
Syntax
#include <usersec.h>
int getpfileattrs(File, Attributes, Count)
char *File;
dbattr_t *Attributes;
int Count;
Description
The getpfileattrs subroutine
reads one or more attributes from the privileged file database (/etc/security/privfiles).
The file specified with the File parameter must include the
full path to the file and exist in the privileged file database. If
the database is not open, this subroutine does an implicit open for
reading.
The Attributes array contains information about each
attribute that is to be read. Each element in the Attributes array
must be examined upon a successful call to the
getpfileattrs subroutine
to determine whether the Attributes array was successfully retrieved.
The
dbattr_t data structure contains the following fields:
| Item |
Description |
|---|
| attr_name |
The name of the desired file
attribute. |
| attr_idx |
This attribute is used internally
by the getpfileattrs subroutine. |
| attr_type |
The type of the target attribute. |
| attr _flag |
The result of the request to
read the target attribute. A value of zero is returned on success;
a nonzero value is returned otherwise. |
| attr_un |
A union containing the returned
values for the requested query. |
Valid privileged file attributes for the
getpfileattrs 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. |
Steeliest |
| 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 |
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. The caller is responsible for freeing this memory. |
| au_int |
Storage
location for attributes of the SEC_INT type. |
| au_long |
Storage
location for attributes of the SEC_LONG type. |
| au_llong |
Storage
location for attributes of the SEC_LLONG type. |
| |
|
If ALL is specified for the File parameter,
the only valid attribute that can appear in the Attribute array is
the S_PRIVFILES attribute. Specifying any other attribute with
a file name of ALL causes the getpfileattrs subroutine
to fail.
Parameters
| Item |
Description |
|---|
| File |
Specifies the file name 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 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 |
r |
Return Values
If
the file specified by the File parameter exists in the privileged
file database, the getpfileattrs subroutine returns zero. On
success, the attr_flag attribute of each element in the Attributes
array must be examined to determine whether it was successfully retrieved.
If the specified file does not exist, a value of -1 is returned and
the errno value is set to indicate the error.
Error Codes
If the
getpfileattrs subroutine
returns -1, one of the following
errno values can be set:
| Item |
Description |
|---|
| EINVAL |
The File parameter is NULL or default. |
| EINVAL |
The File parameter is ALL but
the Attributes entry contains an attribute other than S_PRIVFILES. |
| EINVAL |
The Count parameter is less than zero. |
| EINVAL |
The File parameter is NULL and
the Count parameter is greater than zero. |
| ENOENT |
The file specified in the File parameter
does not exist in the database. |
| EPERM |
Operation is not permitted. |
If the
getpfileattrs subroutine fails to query
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 access to the attribute
specified in the attr_name field. |
| EINVAL |
The attr_name field in the Attributes
entry is not a recognized 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. |
| ENOATTR |
The attr_name field in the Attributes
entry specifies a valid attribute, but no value is defined for this
file. |
| ENOMEM |
Memory cannot be allocated to store the return
value. |