ukey_enable Subroutine

Purpose

Enables user-keys in a process.

Library

Standard C library (libc.a)

Syntax

#include <sys/ukeys.h>

int ukey_enable (void)

Description

The ukey_enable subroutine allows a process access to the user-keys memory protection facilities. A process must make a successful call to the ukey_enable subroutine to enable user-keys before attempting other user-key specific APIs. The following are necessary conditions for enabling user-keys for a process:
  1. Running with the 64-bit kernel. User-keys are not supported on the 32-bit kernel.
  2. Running on hardware that supports storage-keys and user-keys have not been explicitly disabled. By default, user-keys are enabled if the platform supports it. The sysconf (_SC_AIX_UKEYS) subroutine returns the number of available user-keys.
  3. If multi-threaded, the process must be running in system-scope such as 1:1 mode.
  4. Process is not checkpointable for Load Leveler dispatched jobs.

All threads of a user-key enabled process are initially set-up with an active user-key-set that only allows both read and write access to memory pages that have been assigned to the UKEY_PUBLIC, the default user-key. Individual threads can modify their active user-key-set by calling user-key APIs to construct and activate user-key-sets.

Signal Context for User-Key-Enabled processes:

The default signal context for a user-key-enabled process is modified for any future signals that are received. The ucontext_t structure is extended to include the active user-key-set of the interrupted thread. This is provided to signal handlers.

Note: Although signal handlers take a pointer to the sigcontext_t as per the documentation for thesigaction subroutine, the actual structure constructed on the stack is the ucontext_t structure, which is a superset of the sigcontext_t and matches it in its initial portion. By pointing at the signal context with an ucontext_t pointer, signal handlers might access the extended data.

The following fields are set:

ucontext_t.__extctx.__flags |= __EXTCTX_UKEYS 	 
ucontext_t.__extctx.__ukeys[2] = active user-key-set

The user-key extended context is independent of VMX context and is built for all processes that are user-key-enabled.

Additionally, if a storage key exception is taken, the exception type field is set to indicate this in the extended context:

ucontext_t.uc_mcontext.jmp_context.excp_type = EXCEPT_SKEY.

See the sys/context.h header file for a more detailed layout of the extended context information.

Return Values

When successful, the ukey_enable subroutine returns the number of available user-keys. Otherwise, it returns a value of -1 and sets the errno global variable to indicate the error.

Errors Codes

Item Description
ENOSYS User-keys are not supported.

Related Information

The ukey_setjmp subroutine.

The ukeyset_init subroutine.

The ukeyset_add_key, ukeyset_remove_key, ukeyset_add_set, ukeyset_remove_set subroutine.

The ukeyset_activate subroutine.

The ukeyset_ismember subroutine.

The pthread_attr_getukeyset_np or pthread_attr_setukeyset_np subroutine.

AIX® Vector Programming inGeneral Programming Concepts: Writing and Debugging Programs .