getauthattrs Subroutine

Purpose

Retrieves multiple authorization attributes from the authorization database.

Library

Security Library (libc.a)

Syntax

#include <usersec.h>

int getauthattrs(Auth, Attributes, Count)
    char *Auth;
    dbattr_t *Attributes;
    int Count;

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.