Purpose
Retrieves
multiple authorization attributes from the authorization database.
Library
Security
Library (libc.a)
Description
The getauthattrs subroutine
reads one or more attributes from the authorization database. The getauthattrs subroutine
can retrieve authorization definitions from both the user-defined
authorization database and the system-defined authorization table.
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
getauthattrs subroutine,
to determine whether the
Attributes array
was successfully retrieved. The attributes of the
SEC_CHAR or
SEC_LIST type
will have their values returned to allocated memory. The caller need
to free this memory. The
dbattr_t data structure contains the
following fields:
Item |
Description |
attr_name |
The name of the target authorization attribute. |
attr_idx |
This attribute is used internally by the getauthattrs subroutine. |
attr_type |
The type of a target attribute. |
attr _flag |
The result of the request to read the target
attribute. On successful completion, a value of zero is returned.
Otherwise, a value of nonzero is returned. |
attr_un |
A union that contains the returned values for
the requested query. |
attr_domain |
The getauthattrs 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 authorization
is found. |
The following valid authorization attributes for the
getauthattrs subroutine
are defined in the
usersec.h file:
Name |
Description |
Type |
S_AUTHORIZATIONS |
A list of all available
authorizations on the system. It is valid only when the Auth parameter
is set to the ALL variable. |
SEC_LIST |
S_AUTH_CHILDREN |
A list of all authorizations
that exist in the authorization hierarchy under the authorization
that is specified by the Auth parameter. |
SEC_LIST |
S_DFLTMSG |
The default authorization
description that is used when catalogs are not in use. |
SEC_CHAR |
S_ID |
A unique integer that
is used to identify the authorization. |
SEC_INT |
S_MSGCAT |
The message catalog name
that contains the authorization description. |
SEC_CHAR |
S_MSGSET |
The message catalog set
number of the authorization description. |
SEC_INT |
S_MSGNUMBER |
The message number of
the authorization description. |
SEC_INT |
S_ROLES |
A list of roles that
contain the authorization in their authorization set. |
SEC_LIST |
The following union members correspond to the definitions
of the
attr_char,
attr_int,
attr_long and
attr_llong macros
in the
usersec.h file:
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 |
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 Auth parameter,
the only valid attribute that can be displayed in the Attribute array
is the S_AUTHORIZATIONS attribute. Specifying any other attribute
with an authorization name of ALL causes the getauthattrs subroutine
to fail.
Parameters
Item |
Description |
Auth |
Specifies the authorization name for the Attributes array
to read. |
Attributes |
A pointer to an array of zero or more elements
of the dbattr_t type. The list of authorization 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/authorizations |
r |
Return Values
If
the authorization that is specified by the Auth parameter exists
in the authorization database, the getauthattrs subroutine
returns the value of zero. On successful completion, the attr_flag attribute
of each element in the Attributes array
must be examined to determine whether it was successfully retrieved.
If the specified authorization does not exist, a value of -1 is returned
and the errno value is set to indicate the error.
Error Codes
If the
getauthattrs subroutine
returns -1, one of the following
errno values is set:
Item |
Description |
EINVAL |
The Auth parameter is NULL, default,
ALLOW_OWNER, ALLOW_GROUP, or ALLOW_ALL. |
EINVAL |
The Count parameter is less than zero. |
EINVAL |
The Attributes array is NULL and
the Count parameter is greater than zero. |
EINVAL |
The Auth parameter is ALL but
the Attributes entry contains an attribute other than S_AUTHORIZATIONS. |
ENOENT |
The authorization specified in the Auth parameter
does not exist. |
ENOMEM |
Memory cannot be allocated. |
EPERM |
Operation is not permitted. |
EACCES |
Access permission is denied for the data request. |
If the
getauthattrs 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 entry
is not a recognized authorization 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. |
ENOATTR |
The attr_name field in the Attributes entry
specifies a valid attribute, but no value is defined for this authorization. |