ukeyset_activate Subroutine

Purpose

Activates a user-key-set and returns the previously active user-key-set.

Library

Standard C library (libc.a)

Syntax

#include <sys/ukeys.h>

ukeyset_t ukeyset_activate (set, command)
ukeyset_t set;
int command;

Description

The ukeyset_activate subroutine changes the currently active user-key-set and returns the previously active user-key-set. The UKEY_PUBLIC is always enabled for both read and write.

In POWER6® systems, the ukeyset_activate subroutine is implemented through a special linkage. The linkage also executes a fast-path system call. A consequence of running a fast-path system call is that the errno global variable is not updated for errors. Instead, the subroutine ignores some errors. For example, attempts to remove or add the UKEY_PUBLIC value are ignored, and if it is not ignored, the subroutine returns the UKSET_INVALID value.

In POWER7® systems, the ukeyset_activate subroutine is handled through a low memory millicode as the Authority Mask Register (AMR) is accessible in the user mode. There is no change in the way the errno global variable and errors are handled.

Attention: Calling this subroutine in a system that does not support storage keys or has user keys disabled results in a SIGILL signal.

Parameters

Item Description
set User-key-set.
command One of the following:
  • UKA_REPLACE_KEYS - Replaces key-set with the specified key-set.
  • UKA_ADD_KEYS - Adds the specified key-set to the current key-set.
  • UKA_REMOVE_KEYS - Removes the specified key-set from the active key-set.
  • UKA_GET_KEYS - Reads the current key-set value without updating the current key-set. The input key-set is ignored.

Return Values

Upon success, the ukeyset_activate subroutine returns the previously active user-key-set. If called with the UKA_GET_KEYS command, this will also be the current active key-set. If unsuccessful, the ukeyset_activate key-set returns a value of the UKSET_INVALID.

Errors Codes

The ukeyset_activate subroutine does not update errno if unsuccessful.

Related Information

The ukey_enable subroutine.