Technical Reference: Kernel and Subsystems, Volume 1

pinu Kernel Service

Purpose

Pins the specified address range in user or system memory.

Syntax

#include <sys/types.h>
#include <sys/errno.h>
#include <sys/uio.h>

int pinu ( base, len, segflg) caddr_t base; int len; short segflg;

Parameters

base	Specifies the address of the first byte to pin.
len	Indicates the number of bytes to pin.
segflg	Specifies whether the data to pin is in user space or system space. The values for this flag are defined in the /usr/include/sys/uio.h file. This value can be one of the following: UIO_SYSSPACE Indicates the region is mapped into the kernel address space. UIO_USERSPACE Indicates the region is mapped into the user address space.

Description

The pinu kernel service is used to pin pages backing a specified memory region which is defined in either system or user address space. Pinning a memory region prohibits the pager from stealing pages from the pages backing the pinned memory region. Once a memory region is pinned, accessing that region does not result in a page fault until the region is subsequently unpinned.

The pinu kernel service will not work on a mapped file.

If the caller has a valid cross-memory descriptor for the address range, the xmempin and xmemunpin kernel services can be used instead of pinu and unpinu, and result in less pathlength.

Note

The pinu kernel service is not supported on the 64-bit kernel.

Execution Environment

The pinu kernel service can be called from the process environment only.

Return Values

0	Indicates successful completion.
EFAULT	Indicates that the memory region as specified by the base and len parameters is not within the address space specified by the segflg parameter.

EINVAL	Indicates that the value of the length parameter is negative or 0. Otherwise, the area of memory beginning at the byte specified by the base parameter and extending for the number of bytes specified by the len parameter is not defined.
ENOMEM	Indicates that the pinu service is unable to pin the region due to insufficient real memory or because it has exceeded the systemwide pin count.

Related Information

The pin kernel service, unpinu kernel service, xmempin kernel service, xmemunpin kernel service.

Understanding Execution Environments and Memory Kernel Services in AIX 5L Version 5.2 Kernel Extensions and Device Support Programming Concepts.