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