2004-11-03 13:51:07 +00:00
|
|
|
.\" Hey Emacs! This file is -*- nroff -*- source.
|
|
|
|
.\"
|
|
|
|
.\" Copyright (C) 2001 Bert Hubert <ahu@ds9a.nl>
|
2007-01-07 21:26:24 +00:00
|
|
|
.\" and Copyright (C) 2007 Michael Kerrisk <mtk-manpages@gmx.net>
|
2004-11-03 13:51:07 +00:00
|
|
|
.\"
|
|
|
|
.\" Permission is granted to make and distribute verbatim copies of this
|
|
|
|
.\" manual provided the copyright notice and this permission notice are
|
|
|
|
.\" preserved on all copies.
|
|
|
|
.\"
|
|
|
|
.\" Permission is granted to copy and distribute modified versions of this
|
|
|
|
.\" manual under the conditions for verbatim copying, provided that the
|
|
|
|
.\" entire resulting derived work is distributed under the terms of a
|
|
|
|
.\" permission notice identical to this one.
|
|
|
|
.\"
|
|
|
|
.\" Since the Linux kernel and libraries are constantly changing, this
|
|
|
|
.\" manual page may be incorrect or out-of-date. The author(s) assume no
|
|
|
|
.\" responsibility for errors or omissions, or for damages resulting from
|
|
|
|
.\" the use of the information contained herein. The author(s) may not
|
|
|
|
.\" have taken the same level of care in the production of this manual,
|
|
|
|
.\" which is licensed free of charge, as they might when working
|
|
|
|
.\" professionally.
|
|
|
|
.\"
|
|
|
|
.\" Formatted or processed versions of this manual, if unaccompanied by
|
|
|
|
.\" the source, must acknowledge the copyright and authors of this work.
|
|
|
|
.\"
|
|
|
|
.\" Created Sun Jun 3 17:23:32 2001 by bert hubert <ahu@ds9a.nl>
|
|
|
|
.\" Slightly adapted, following comments by Hugh Dickins, aeb, 2001-06-04.
|
2004-11-03 14:43:40 +00:00
|
|
|
.\" Modified, 20 May 2003, Michael Kerrisk <mtk-manpages@gmx.net>
|
|
|
|
.\" Modified, 30 Apr 2004, Michael Kerrisk <mtk-manpages@gmx.net>
|
2005-04-06 12:59:19 +00:00
|
|
|
.\" 2005-04-05 mtk, Fixed error descriptions
|
2005-04-05 17:01:47 +00:00
|
|
|
.\" after message from <gordon.jin@intel.com>
|
2007-01-07 21:26:24 +00:00
|
|
|
.\" 2007-01-08 mtk, rewrote various parts
|
2004-11-03 13:51:07 +00:00
|
|
|
.\"
|
2007-01-07 21:26:24 +00:00
|
|
|
.TH MINCORE 2 2007-01-08 "Linux 2.6.5" "Linux Programmer's Manual"
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH NAME
|
2007-01-07 21:26:24 +00:00
|
|
|
mincore \- determine whether pages are resident in memory
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH SYNOPSIS
|
|
|
|
.B #include <unistd.h>
|
|
|
|
.br
|
|
|
|
.B #include <sys/mman.h>
|
|
|
|
.sp
|
|
|
|
.BI "int mincore(void *" start ", size_t " length ", unsigned char *" vec );
|
|
|
|
.SH DESCRIPTION
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR mincore ()
|
2007-01-07 21:26:24 +00:00
|
|
|
returns a vector that indicates whether pages
|
|
|
|
of the calling process's virtual memory are resident in core (RAM),
|
|
|
|
and so will not cause a disk access (page fault) if referenced.
|
|
|
|
The kernel returns residency information about the pages
|
|
|
|
starting at the address
|
|
|
|
.IR start ,
|
|
|
|
and continuing for
|
2004-11-03 13:51:07 +00:00
|
|
|
.I length
|
2007-01-07 21:26:24 +00:00
|
|
|
bytes.
|
2004-11-03 13:51:07 +00:00
|
|
|
|
2007-01-07 21:26:24 +00:00
|
|
|
The
|
2004-11-03 13:51:07 +00:00
|
|
|
.I start
|
2007-01-07 21:26:24 +00:00
|
|
|
argument must be a multiple of the system page size.
|
|
|
|
The
|
2004-11-03 13:51:07 +00:00
|
|
|
.I length
|
2007-01-07 21:26:24 +00:00
|
|
|
argument need not be a multiple of the page size,
|
|
|
|
but since residency information is returned for whole pages,
|
|
|
|
.I length
|
|
|
|
is effectively rounded up to the next multiple of the page size.
|
|
|
|
One may obtain the page size (PAGE_SIZE) using
|
|
|
|
.IR sysconf(_SC_PAGESIZE) .
|
2004-11-03 13:51:07 +00:00
|
|
|
|
2007-01-07 21:26:24 +00:00
|
|
|
The
|
|
|
|
.I vec
|
|
|
|
argument must point to an array containing at least
|
|
|
|
(length+PAGE_SIZE-1) / PAGE_SIZE bytes.
|
|
|
|
On return,
|
|
|
|
the least significant bit of each byte will be set if
|
|
|
|
the corresponding page is currently resident in memory,
|
|
|
|
and be clear otherwise.
|
|
|
|
(The settings of the other bits in each byte are undefined;
|
|
|
|
these bits are reserved for possible later use.)
|
|
|
|
Of course the information returned in
|
|
|
|
.I vec
|
|
|
|
is only a snapshot: pages that are not
|
|
|
|
locked in memory can come and go at any moment, and the contents of
|
|
|
|
.I vec
|
|
|
|
may already be stale by the time this call returns.
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH "RETURN VALUE"
|
|
|
|
On success,
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR mincore ()
|
2004-11-03 13:51:07 +00:00
|
|
|
returns zero.
|
|
|
|
On error, \-1 is returned, and
|
|
|
|
.I errno
|
|
|
|
is set appropriately.
|
|
|
|
.SH ERRORS
|
|
|
|
.B EAGAIN
|
2007-01-07 21:26:24 +00:00
|
|
|
kernel is temporarily out of resources.
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP
|
|
|
|
.B EFAULT
|
|
|
|
.I vec
|
2007-01-07 21:26:24 +00:00
|
|
|
points to an invalid address.
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP
|
|
|
|
.B EINVAL
|
|
|
|
.I start
|
2005-04-06 12:59:19 +00:00
|
|
|
is not a multiple of the page size.
|
|
|
|
.TP
|
|
|
|
.B ENOMEM
|
2004-11-03 13:51:07 +00:00
|
|
|
.I len
|
2005-04-05 17:01:47 +00:00
|
|
|
is greater than
|
2005-07-06 06:54:27 +00:00
|
|
|
.RI ( TASK_SIZE " \- " start ).
|
2005-04-06 12:59:19 +00:00
|
|
|
(This could occur if a negative value is specified for
|
2005-04-05 17:01:47 +00:00
|
|
|
.IR len ,
|
2005-04-06 12:59:19 +00:00
|
|
|
since that value will be interpreted as a large
|
|
|
|
unsigned integer.)
|
|
|
|
In Linux 2.6.11 and earlier, the error
|
|
|
|
.B EINVAL
|
|
|
|
was returned for this condition.
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP
|
|
|
|
.B ENOMEM
|
|
|
|
.I address
|
|
|
|
to
|
|
|
|
.I address
|
|
|
|
+
|
|
|
|
.I length
|
|
|
|
contained unmapped memory, or memory not part of a file.
|
|
|
|
.SH BUGS
|
2007-01-07 21:26:24 +00:00
|
|
|
.\" FIXME: mincore() went through some rewrites in 2.6.20-rc;
|
|
|
|
.\" has this affected any of the bugs?
|
2004-11-03 13:51:07 +00:00
|
|
|
Up to now (Linux 2.6.5),
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR mincore ()
|
2004-11-03 13:51:07 +00:00
|
|
|
does not return correct information for MAP_PRIVATE mappings.
|
|
|
|
.\" Linux (up to now, 2.6.5),
|
|
|
|
.\" .B mincore
|
|
|
|
.\" does not return correct information for MAP_PRIVATE mappings:
|
|
|
|
.\" for a MAP_PRIVATE file mapping,
|
|
|
|
.\" .B mincore
|
|
|
|
.\" returns the residency of the file pages, rather than any
|
|
|
|
.\" modified process-private pages that have been copied on write;
|
|
|
|
.\" for a MAP_PRIVATE mapping of
|
|
|
|
.\" .IR /dev/zero ,
|
|
|
|
.\" .B mincore
|
|
|
|
.\" always reports pages as non-resident;
|
|
|
|
.\" and for a MAP_PRIVATE, MAP_ANONYMOUS mapping,
|
|
|
|
.\" .B mincore
|
|
|
|
.\" always fails with the error
|
|
|
|
.\" .BR ENOMEM .
|
|
|
|
.SH "CONFORMING TO"
|
2005-10-19 06:54:38 +00:00
|
|
|
.BR mincore ()
|
2005-04-05 17:01:47 +00:00
|
|
|
is not specified in POSIX.1-2001,
|
|
|
|
and it is not available on all Unix implementations.
|
2007-01-07 21:26:24 +00:00
|
|
|
.\" It is on at least NetBSD, FreeBSD, OpenBSD, Solaris 8,
|
|
|
|
.\" AIX 5.1, SunOS 4.1
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH HISTORY
|
2005-10-19 14:48:35 +00:00
|
|
|
The
|
|
|
|
.BR mincore ()
|
|
|
|
function first appeared in 4.4BSD.
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH AVAILABILITY
|
|
|
|
Since Linux 2.3.99pre1 and glibc 2.2.
|
|
|
|
.SH "SEE ALSO"
|
|
|
|
.BR mlock (2),
|
|
|
|
.BR mmap (2)
|