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

Item	Description
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

Item	Description
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.