getroleattr, nextrole or putroleattr Subroutine

Purpose

Accesses the role information in the roles database.

Library

Security Library (libc.a)

Syntax

#include <usersec.h>

int getroleattr(Role, Attribute, Value, Type)
char *Role;
char *Attribute;
void *Value;
int Type;

char *nextrole(void)
int putroleattr(Role, Attribute, Value, Type)
char *Role;
char *Attribute;
void *Value;
int Type;

Description

The getroleattr subroutine reads a specified attribute from the role database. If the database is not already open, this subroutine does an implicit open for reading.

Similarly, the putroleattr subroutine writes a specified attribute into the role database. If the database is not already open, this subroutine does an implicit open for reading and writing. Data changed by the putroleattr subroutine must be explicitly committed by calling the putroleattr subroutine with a Type parameter specifying SEC_COMMIT. Until all the data is committed, only the getroleattr subroutine within the process returns written data.

The nextrole subroutine returns the next role in a linear search of the role database. The consistency of consecutive searches depends upon the underlying storage-access mechanism and is not guaranteed by this subroutine.

The setroledb and endroledb subroutines should be used to open and close the role database.

Parameters

Item Description
Attribute Specifies which attribute is read. The following possible attributes are defined in the usersec.h file:
S_AUDITCLASSES
Audit classes to which the role belongs. The attribute type is SEC_LIST.
S_ROLELIST
List of roles included by this role. The attribute type is SEC_LIST.
S_AUTHORIZATIONS
List of authorizations included by this role. The attribute type is SEC_LIST.
S_GROUPS
List of groups required for this role. The attribute type is SEC_LIST.
S_SCREENS
List of SMIT screens required for this role. The attribute type is SEC_LIST.
S_VISIBILITY
Number value stating the visibility of the role. The attribute type is SEC_INT.
S_MSGCAT
Message catalog file name. The attribute type is SEC_CHAR.
S_MSGNUMBER
Message number within the catalog. The attribute type is SEC_INT.
S_MSGSET
Message catalog set number. The attribute type is SEC_INT.
S_ID
Role identifier. The attribute type is SEC_INT.
S_DFLTMSG
Default role description string used when catalogs are not in use. The attribute type is SEC_CHAR.
S_USERS
List of users that have been assigned this role. This attribute is a read only attribute and cannot be modified through the putroleattr subroutine. The attribute type is SEC_LIST.
S_AUTH_MODE
The authentication to use when assuming the role through the swrole command. Valid values are NONE and INVOKER. The attribute type is SEC_CHAR.
Type Specifies the type of attribute expected. Valid types are defined in the usersec.h file and include:
SEC_INT
The format of the attribute is an integer.

For the getroleattr subroutine, the user should supply a pointer to a defined integer variable.

For the putroleattr subroutine, the user should supply an integer.

SEC_CHAR
The format of the attribute is a null-terminated character string.

For the getroleattr subroutine, the user should supply a pointer to a defined character pointer variable. For the putroleattr subroutine, the user should supply a character pointer.

SEC_LIST
The format of the attribute is a series of concatenated strings, each null-terminated. The last string in the series must be an empty (zero character count) string.

For the getroleattr subroutine, the user should supply a pointer to a defined character pointer variable. For the putroleattr subroutine, the user should supply a character pointer.

SEC_COMMIT
For the putroleattr subroutine, this value specified by itself indicates that changes to the named role are to be committed to permanent storage. The Attribute and Value parameters are ignored. If no role is specified, the changes to all modified roles are committed to permanent storage.
SEC_DELETE
The corresponding attribute is deleted from the database.
SEC_NEW
Updates the role database file with the new role name when using the putroleattr subroutine.
Value Specifies a buffer, a pointer to a buffer, or a pointer to a pointer depending on the Attribute and Type parameters. See the Type parameter for more details.

Return Values

If successful, the getroleattr returns 0. Otherwise, a value of -1 is returned and the errno global variables is set to indicate the error.

Error Codes

Possible return codes are:

Item Description
EACCES Access permission is denied for the data request.
ENOENT The specified Role parameter does not exist.
ENOATTR The specified role attribute does not exist for this role.
EINVAL The Attribute parameter does not contain one of the defined attributes or null.
EINVAL The Value parameter does not point to a valid buffer or to valid data for this type of attribute.
EPERM Operation is not permitted.