ukeyset_add_key, ukeyset_remove_key, ukeyset_add_set or ukeyset_remove_set Subroutine

Purpose

Operates on and modifies a user-key-set.

Library

Standard C library (libc.a)

Syntax

#include <sys/ukeys.h> int ukeyset_add_key (uset, key, flags) ukeyset_t * uset; ukey_t key; unsigned int flags; int ukeyset_remove_key (uset, key, flags) ukeyset_t * uset; ukey_t key; unsigned int flags; int ukeyset_add_set (uset, aset) ukeyset_t * uset; ukeyset_t aset; int ukeyset_remove_set (uset, rset) ukeyset_t * uset; ukeyset_t rset;

Description

These subroutines operate on and modify user-key-sets. The user-key-set must have been originally initialized with the ukeyset_init subroutine.

Individual or groups (sets) of user-keys can be added or removed . When adding or removing an individual key, the accesses (read or write, or both read and write) being added or removed must be specified through the flags parameter. When adding or removing user-key-sets, specification is not required, because a key-set contains not only information on what keys are enabled, but also information on which specific access permissions are enabled for each one of those keys.

The ukeyset_add_key subroutine adds the user-key specified by the key parameter with accesses as specified by the flags parameter to the user-key-set specified by the uset parameter. The ukeyset_remove_key subroutine removes the accesses specified by the flags parameter of the key specified by the key parameter from the user-key-set specified by the uset parameter. The ukeyset_add_set subroutine adds the keys and accesses specified by the aset key-set parameter to the user-key-set specified by the uset parameter. The ukeyset_remove_set subroutine removes the keys and accesses specified by the rset key-set parameter from the user-key-set specified by the uset parameter.

Note: An add operation of a key (or key-set) and then a subsequent remove operation of the same key (or key-set) might not result in the original key-set. For example, if a key already exists in a key-set, adding the same key has no effect on the key-set, but then a subsequent remove key operation results in a new key-set minus the removed key.

Attempting to remove a defined user-key that does not exist in the source key-set is ignored silently in a manner similar to the signal set services.

These subroutines will fail unless the ukey_enable subroutine has already been successfully executed by a thread in the process. Refer to the Storage Protect Keys article for more details.

Parameters

Item	Description
uset	User-key-set to be modified.
rset	User-key-set to remove.
aset	User-key-set to add.
key	User-key to add or remove from a key-set. This parameter is combined with read or write flags when performing add or remove operations.
flags	The following flags are defined for the ukeyset_add_key() and ukeyset_remove_key() services: UK_READ - Specifies that the read access for a key is to be added or removed. UK_WRITE - Specifies that the write access for a key is to be added or removed. UK_RW - Specifies that read and write access are to be added or removed.

Return Values

If successful, the user-key-set subroutines return a value of 0. Otherwise, they return a value of -1 and set the errno global variable to indicate the error.

Errors Codes

The ukeyset_add_key and ukeyset_remove_key subroutines are unsuccessful if the following are true:

Item	Description
EINVAL	Invalid flags parameter, invalid key-set specified in uset parameter or invalid (undefined) keys specified in the key parameter.
ENOSYS	Unconfigured (unavailable) private key specified in the key parameter or process is not user-key enabled.

The ukeyset_add_set, ukeyset_remove_set, ukeyset_add_set and ukeyset_remove_set subroutines are unsuccessful if the following are true:

Item	Description
EINVAL	Invalid key-set specified in uset , rset or aset parameter.
ENOSYS	Process is not user-key enabled.

Only the subroutines that take keys (instead of keysets) to add or remove can fail because of invalid or unused key number or invalid access flags.