Technical Reference: Kernel and Subsystems, Volume 1

pin Kernel Service

Purpose

Pins the address range in the system (kernel) space.

Syntax

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

int pin ( addr, length) caddr_t addr; int length;

Parameters

addr	Specifies the address of the first byte to pin.
length	Specifies the number of bytes to pin.

Description

The pin service pins the real memory pages touched by the address range specified by the addr and length parameters in the system (kernel) address space. It pins the real-memory pages to ensure that page faults do not occur for memory references in this address range. The pin service increments the pin count for each real-memory page. While the pin count is nonzero, the page cannot be paged out of real memory.

The pin routine pins either the entire address range or none of it. Only a limited number of pages can be pinned in the system. If there are not enough unpinned pages in the system, the pin service returns an error code.

Note

If the requested range is not aligned on a page boundary, then memory outside this range is also pinned. This is because the operating system pins only whole pages at a time.

The pin service can only be called for addresses within the system (kernel) address space. The xmempin service should be used for addresses within kernel or user space.

Execution Environment

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

Return Values

0	Indicates successful completion.
EINVAL	Indicates that the value of the length parameter is negative or 0. Otherwise, the area of memory beginning at the address of the first byte to pin (the addr parameter) and extending for the number of bytes specified by the length parameter is not defined.
EIO	Indicates that a permanent I/O error occurred while referencing data.
ENOMEM	Indicates that the pin service was unable to pin due to insufficient real memory or exceeding the systemwide pin count.
ENOSPC	Indicates insufficient file system or paging space.

Related Information

The xmempin and xmemunpin kernel services.

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