ukey_protect Subroutine

Purpose

Modifies memory’s user-key protection.

Syntax

#include <sys/ukeys.h> int ukey_protect (void * addr, size_t len, ukey_t ukey)

Description

Setting user-keys is available with the ukey_protect(addr,len,prot) protect settings. Attempts to set user-keys with the ukey_protect subroutine fail if keys are not implemented, or the specified user-key is not available. The sysconf(_SC_AIX_UKEYS) must be used to test for the number and presence of user-keys.

One user-key can be associated with a virtual page. The supported values are the UKEY_PUBLIC and UKEY_PRIVATE1-31 values. A successful call to the ukey_protect() subroutine replaces the region's previous user-key(s) with the value specified by ukey.

A user-key can be set on shared memory regions (shmat()) and applications default data and stack region. When using the ukey_protect subroutine on shared memory regions, the region must have write access to the shared memory object (process with the appropriate privileges an effective user ID that matches shm_perm.uid or shm_perm.cuid). User-keys cannot be altered on files mapped with shmat(), application text, or library regions.

When using the ukey_protect subroutine to place a private key on memory that is acquired by the malloc subroutine, the memory must always be reset to the UKEY_PUBLIC key before it is freed.

Parameters

Item	Description
addr	Specifies the address of the region to be modified. Must be a multiple of the page size returned by the vmgetinfo subroutine using the VM_PAGE_INFO command.
len	Specifies the length, in bytes, of the region to be modified. If the len parameter is not a multiple of the page size returned by the sysconf subroutine using the _SC_PAGE_SIZE value for the Name parameter, an error is returned.
ukey	Specifies the user-key value to associate with the address range.

Return Values

When successful, the ukey_protect subroutine returns a value of 0. Otherwise, it returns a value of -1 and sets the errno global variable to indicate the error.

Error Codes

Attention: If the ukey_protect subroutine is unsuccessful because of a condition other than that specified by the EINVAL error code, the access protection for some pages in the (addr, addr + len) range might have been changed. If the ukey_protect subroutine is unsuccessful, the errno global variable might be set to one of the following values:

Item	Description
EPERM	The caller does not have sufficient authority to set a user-key on target memory.
ENOSYS	User-keys are not supported.
EINVAL	The ukey parameter is not valid, or the addr parameter is not a multiple of the page size as returned by the sysconf subroutine using the _SC_PAGE_SIZE value for the Name parameter.
EFAULT	Address is not valid for the address space of the process.

Related Information

The ukey_getkey Subroutine.