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