[ Previous | Next | Contents | Home | Search ]
AIX Version 4.3 Kernel and Subsystems Technical Reference, 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 pinu 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.

Implementation Specifics

The pin kernel service is part of Base Operating System (BOS) Runtime.

Related Information

The unpin kernel service.

Understanding Execution Environments and Memory Kernel Services in AIX Kernel Extensions and Device Support Programming Concepts.

[ Previous | Next | Contents | Home | Search ]