From: Michael Kerrisk Date: Sun, 7 Jan 2007 21:26:24 +0000 (+0000) Subject: Substantial rewrites to make clearer. X-Git-Tag: man-pages-2.44~39 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=182d66226751b6a6801466fd558010236e8bae5b;p=thirdparty%2Fman-pages.git Substantial rewrites to make clearer. --- diff --git a/man2/mincore.2 b/man2/mincore.2 index bdf9bb3c10..f98688da97 100644 --- a/man2/mincore.2 +++ b/man2/mincore.2 @@ -1,6 +1,7 @@ .\" Hey Emacs! This file is -*- nroff -*- source. .\" .\" Copyright (C) 2001 Bert Hubert +.\" and Copyright (C) 2007 Michael Kerrisk .\" .\" Permission is granted to make and distribute verbatim copies of this .\" manual provided the copyright notice and this permission notice are @@ -28,10 +29,11 @@ .\" Modified, 30 Apr 2004, Michael Kerrisk .\" 2005-04-05 mtk, Fixed error descriptions .\" after message from +.\" 2007-01-08 mtk, rewrote various parts .\" -.TH MINCORE 2 2004-04-30 "Linux 2.6.5" "Linux Programmer's Manual" +.TH MINCORE 2 2007-01-08 "Linux 2.6.5" "Linux Programmer's Manual" .SH NAME -mincore \- get information on whether pages are in core +mincore \- determine whether pages are resident in memory .SH SYNOPSIS .B #include .br @@ -39,36 +41,45 @@ mincore \- get information on whether pages are in core .sp .BI "int mincore(void *" start ", size_t " length ", unsigned char *" vec ); .SH DESCRIPTION -The .BR mincore () -function requests a vector describing which pages of a file are in core and -can be read without disk access. The kernel will supply data for +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 .I length -bytes following the -.I start -address. On return, the kernel will have filled -.I vec -with bytes, of which the least significant bit indicates if a page is -core resident. (The other bits are undefined, reserved for possible -later use.) -Of course this is only a snapshot: pages that are not -locked in core can come and go any moment, and the contents of -.I vec -may be stale already when this call returns. +bytes. -For -.BR mincore () -to return successfully, +The .I start -must lie on a page boundary. It is the caller's responsibility to -round up to the nearest page. The +argument must be a multiple of the system page size. +The .I length -parameter need not be a multiple of the page size. The vector -.I vec -must be large enough to contain (length+PAGE_SIZE-1) / PAGE_SIZE bytes. -One may obtain the page size from -.BR getpagesize (2). +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) . +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. .SH "RETURN VALUE" On success, .BR mincore () @@ -78,11 +89,11 @@ On error, \-1 is returned, and is set appropriately. .SH ERRORS .B EAGAIN -kernel is temporarily out of resources +kernel is temporarily out of resources. .TP .B EFAULT .I vec -points to an invalid address +points to an invalid address. .TP .B EINVAL .I start @@ -108,10 +119,11 @@ to .I length contained unmapped memory, or memory not part of a file. .SH BUGS +.\" FIXME: mincore() went through some rewrites in 2.6.20-rc; +.\" has this affected any of the bugs? Up to now (Linux 2.6.5), .BR mincore () 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: @@ -131,6 +143,8 @@ does not return correct information for MAP_PRIVATE mappings. .BR mincore () is not specified in POSIX.1-2001, and it is not available on all Unix implementations. +.\" It is on at least NetBSD, FreeBSD, OpenBSD, Solaris 8, +.\" AIX 5.1, SunOS 4.1 .SH HISTORY The .BR mincore () @@ -138,6 +152,5 @@ function first appeared in 4.4BSD. .SH AVAILABILITY Since Linux 2.3.99pre1 and glibc 2.2. .SH "SEE ALSO" -.BR getpagesize (2), .BR mlock (2), .BR mmap (2)