dg_paging_info(2) DG/UX R4.11MU05 dg_paging_info(2)
NAME
dgpaginginfo - determine residency of memory pages
SYNOPSIS
#include <sys/dgpaginginfo.h>
int dgpaginginfo(int version, pidt pid,
struct dgpaginginfo *paginginfo);
where:
version Desired version of the function interface
pid Process id of the process whose address space is to be
queried
paginginfo Pointer to a structure which further describes the
queried memory region and the array used for reporting
paging status
DESCRIPTION
The dgpaginginfo() function returns the primary memory residency
status for pages in a region of the address space specified by pid.
The version parameter must have the value DGPAGINGINFOVERSION1,
as this is the only supported version of the function interface.
The pid parameter must be either a legal process id value, to query
the address space of the process with that process id, or one of two
special values:
DGPAGINGINFOKERNELSPACEPID
Query a region of the kernel address space.
DGPAGINGINFOCALLINGPROCESSPID
Query a region of the caller's address
space.
Upon invocation of dgpaginginfo(), the members of the structure
given by paginginfo further define the query:
dpiflags This member is reserved for future use and
must be 0.
dpistartaddress This member defines the lower bound within
the queried address space for which the
caller is requesting paging info; its value
must be a page aligned address. (The
system page size is available by calling
getpagesize(2) or sysconf(2) with the
SCPAGESIZE parameter; both calls return
identical values.)
dpibytecount This member contains the maximum number of
bytes of address space for which the caller
is requesting paging info. In the event
that the value is not a multiple of the
system page size, it will be treated as if
it were rounded up to the next page size
multiple.
dpibitmapbitsperpage This member contains the number of bits of
paging info requested by the caller for
each page of the queried address space.
The legal values for this member are 1, 8,
and 16. In all cases, the low order bit of
paging info recorded for each page
indicates whether it is resident in primary
memory (a bit value of 1 represents a
resident page). In the case of one bit per
page, the pages with lower addresses are
represented in the higher order bits within
each byte. In the case of sixteen bits per
page, other bits designate various
attributes of the page. The bit masks
identifying these attributes are defined in
<sys/dg_paging_info.h>.
dpibitmapptr This member specifies the location within
the caller's address space of the bitmap to
contain the recorded paging info for the
queried address space. The caller's
address space must be writable starting at
the specified address, for the number of
bits of paging info requested. (This
number of bits can be computed by
multiplying the number of pages implied by
dpibytecount times the value of
dpibitmapbitsperpage.)
The function will report on the first contiguous range of mapped
pages at or above address dpistartaddress within the queried
address space, up to the maximum number of pages implied by
dpibytecount.
Upon successful return from dgpaginginfo, the following members of
the paginginfo structure will be updated to reflect what status
information has been reported:
dpistartaddress This member contains the address of the
first mapped page within the queried
address space which has an address greater
than or equal to the requested start
address. This page's status is also
represented by the first element in the
bitmap at dpibitmapptr.
dpibytecount This member contains the actual number of
bytes of address space for which paging
info has been reported in the bitmap. This
value will be identical to its value upon
invocation unless the memory segment
starting at dpistartaddress (as returned)
is smaller than the value of dpibytecount
specified upon invocation. If
dpibytecount is 0 on return, then there
were no mapped pages in the queried address
space at or above dpistartaddress.
The dgpaginginfo() function returns residency information that is
accurate at a different instant in time for each page. Because the
system may frequently adjust the set of pages in memory, this
information may quickly be outdated, not necessarily even self-
consistent.
Pages which are direct mapped to a memory-mapped device will be
reported by dgpaginginfo() to be memory resident.
ACCESS CONTROL
If the queried address space is that of a process, then the caller's
real user id or saved set user id must equal the real user id or
saved set user id of the queried process. Failing that, the calling
process must have appropriate privilege. For systems supporting the
DG/UX Capability Option, appropriate privilege is defined as having
one or more specific capabilities enabled in the effective capability
set of the calling process. See capdefaults(5) for the default
capability for this system call.
On systems without the DG/UX Capability Option, appropriate privilege
means that the process has an effective UID of root. See the
appropriateprivilege(5) man page for more information.
If the queried address space is the kernel address space, then the
calling process must have appropriate privilege.
RETURN VALUE
Upon successful completion, dgpaginginfo() returns a value of 0.
Otherwise, it returns the value -1, and sets errno to indicate the
error.
DIAGNOSTICS
Under the following conditions, dgpaginginfo() fails and sets errno
to:
EACCES if the calling process lacks access to query the
address space specified by pid.
EFAULT if some portion of the structure pointed to by
paginginfo is not mapped in the caller's address
space or lacks write access.
EFAULT if some portion of the bitmap pointed to by
dpibitmapptr is not mapped in the caller's address
space or lacks write access.
EINVAL if version is not DGPAGINGINFOVERSION1.
EINVAL if dpiflags is not 0.
EINVAL if dpistartaddress is not a page aligned address.
EINVAL if dpibytecount is 0.
EINVAL if dpibitmapbitsperpage is not 1, 8, or 16.
ESRCH if no process was found with a process id matching
pid.
SEE ALSO
getpagesize(2), mincore(2), sysconf(2), appropriateprivilege(5).
capdefaults(5).
Licensed material--property of copyright holder(s)