getroleattrs Subroutine

Purpose

Retrieves multiple role attributes from the role database.

Library

Security Library (libc.a)

Syntax

#include <usersec.h>

int getroleattrs(Role, Attributes, Count)
    char *Role;
    dbattr_t *Attributes;
    int Count;

Description

The getroleattrs reads one or more attributes from the role database. The role specified with the Role parameter must already exist in the role database. The Attributes parameter contains information about each attribute that is to be read. All attributes specified by the Attributes parameter must be examined on a successful call to the getroleattrs subroutine to determine whether value of the Attributes parameter was successfully retrieved. Attributes of the SEC_CHAR or SEC_LIST type will have their values returned to the allocated memory. Caller need to free this memory. The dbattr_t data structure contains the following fields:
Item Description
attr_name The name of the target role attribute.
attr_idx This attribute is used internally by the getroleattrs subroutine.
attr_type The type of the target attribute.
attr _flag The result of the request to read the target attribute. On successful completion, the value of zero is returned. Otherwise, it returns a value of nonzero.
attr_un A union that contains the returned values for the requested query.
attr_domain The 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 role is found.
The following valid role attributes for the getroleattrs subroutine are defined in the usersec.h file:
Name Description Type
S_AUDITCLASSES Audit classes to which the role belongs. SEC_LIST
S_AUTHORIZATIONS Retrieves all the authorizations that are assigned to the role. SEC_LIST
S_AUTH_MODE The authentication to perform when assuming the role through the swrole command. It contains the following possible values:
NONE
No authentication is required.
INVOKER
This is the default value. Invokers of the swrole command must enter their passwords to assume the role.
SEC_CHAR
S_DFLTMSG The default role description that is used when catalogs are not in use. SEC_CHAR
S_GROUPS The groups that a user is suggested to become a member of. It is for informational purpose only. SEC_LIST
S_HOSTSENABLEDROLE The list of hosts from where the role can be downloaded to the Kernel Role Table. SEC_LIST
S_HOSTSDISABLEDROLE The list of hosts from where the role cannot be downloaded to the Kernel Role Table. SEC_LIST
S_ID The role identifier. SEC_INT
S_MSGCAT The message catalog name that contains the role description. SEC_CHAR
S_MSGSET The message catalog's set number for the role description. SEC_INT
S_MSGNUMBER The message number for the role description. SEC_INT
S_ROLELIST Lists of roles whose authorizations are included in this role. SEC_LIST
S_ROLES Retrieves all the roles that are available on the system. It is valid only when the Role parameter is set to ALL. SEC_LIST
S_SCREENS The SMIT screens that the role can access. SEC_LIST
S_VISIBILITY An integer that determines whether the role is active or not. It contains the following possible values:
-1
The role is disabled.
0
The role is active but not visible from a GUI.
1
The role is active and visible. This is the default value.
 SEC_INT
S_USERS Lists of users that have been assigned this role. SEC_LIST
The following union members correspond to the definitions of the attr_char, attr_int, attr_long and the attr_llong macros in the usersec.h file respectively.
Item Description
au_char The 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 Role parameter, the only valid attribute that can be displayed in the Attribute parameter is the S_ROLES attribute. Specifying any other attribute with a role name of ALL causes the getroleattrs subroutine to fail.

Parameters

Item Description
Role Specifies the role 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 role attributes is defined in the usersec.h header file.
Count The number of attributes specified in the Attributes parameter.

Security

Files Accessed:
File Mode
/etc/security/roles r

Return Values

If the role specified by the Role parameter exists in the role database, the getroleattrs subroutine returns zero. On successful completion, the attr_flag attribute of each attribute that is specified in the Attributes parameter must be examined to determine whether it was successfully retrieved. If the specified role does not exist, a value of -1 is returned and the errno value is set to indicate the error.

Error Codes

If the getroleattrs subroutine returns -1, one of the following errno values is set:
Item Description
EINVAL The Role parameter is NULL.
EINVAL The Count parameter is less than zero.
EINVAL The Role parameter is NULL and the Count parameter is greater than zero.
EINVAL The Role parameter is ALL but the Attributes parameter contains an attribute other than S_ROLES.
ENOENT The role specified in the Role parameter does not exist.
ENOMEM Memory cannot be allocated.
EPERM The operation is not permitted.
EACCES Access permission is denied for the data request.
If the getroleattrs subroutine fails to query an attribute, one of the following errors is returned in the attr_flag field of the corresponding value of the Attributes parameter:
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 parameter is not a recognized role attribute.
EINVAL The attr_type field in the Attributes parameter contains a type that is not valid.
EINVAL The attr_un field in the Attributes parameter does not point to a valid buffer.
ENOATTR The attr_name field in the Attributes parameter specifies a valid attribute, but no value is defined for this role.