madvise man page

["David Gómez " <davidge@jazzfree.com>]

[-- Attachment #1: Type: TEXT/PLAIN, Size: 347 bytes --]


Hi, 

I've written a first version of madvise system call man page, based on
the comments in filemap.c. I've already sent it to Andries Brouwer, but
please take a look it and tell me if there is something wrong or i forgot
something. By the way, what standards ,besides posix.1b, is madvise
conforming to, SuS maybe?


David Gómez



[-- Attachment #2: Type: TEXT/PLAIN, Size: 3755 bytes --]

.\" Hey Emacs! This file is -*- nroff -*- source.
.\"
.\" Copyright (C) 2001 David Gómez <davidge@jazzfree.com>
.\"
.\" 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.
.\"
.\" Based on comments from mm/filemap.c. Last modified on 10-06-2001
.\"
.TH MADVISE 2 2001-06-10 "Linux 2.4.5" "Linux Programmer's Manual"
.SH NAME
madvise \- advise about how to handle page I/O in a VM area
.SH SYNOPSIS
.br
.B #include <sys/mman.h>
.sp
.BI "int madvise(void *" start ", size_t " length ", int " behavior " );
.SH DESCRIPTION
The
.I madvise
system call advises the kernel about how to handle paging input/output in an 
address range beggining at address
.I start
and with size
.I length
bytes, allowing an application to inform about how will use in the future
some mapped or shared memory areas. This call only advises the kernel
to choose appropiate read-ahead and caching techniques, but it's up to the
kernel to follow the advise or to ignore it, without affecting the current
running application.
.sp
Address
.I start
must be page-aligned to success on the call to
.I madvise.
If there are some parts of the specified address range that are not mapped,
.I madvise
ignore them but returns 
.B ENOMEM 
at the end.
The advise is indicated in the 
.I behavior
parameter which can be

.TP
.B MADV_NORMAL 
the default behavior is to read clusters.  This
results in some read-ahead and read-behind.
.TP
.B MADV_RANDOM 
the system should read the minimum amount of data
on any access, since it is unlikely that the appli-
cation will need more than what it asks for.
.TP
.B MADV_SEQUENTIAL 
pages in the given range will probably be accessed
once, so they can be aggressively read ahead, and
can be freed soon after they are accessed.
.TP
.B MADV_WILLNEED 
the application is notifying the system to read
some pages ahead.
.TP 
.B MADV_DONTNEED 
the application is finished with the given range,
so the kernel can free resources associated with it.
 

.SH "RETURN VALUE"
On sucess 
.B madvise
return zero. On error , it returns -1 and
.B errno
is set appropiately.
.SH "ERRORS"
.TP
.B EINVAL 
the value 
.B start
+
.B len
is negative, start is not page-aligned,
.B behavior 
is not a valid value, or application
is attempting to release locked or shared pages.
.TP 
.B ENOMEM 
addresses in the specified range are not currently
mapped, or are outside the address space of the process.
.TP
.B EIO 
an I/O error occurred while paging in data.
.TP
.B EBADF
map exists, but area maps something that isn't a file.
.TP
.B EAGAIN 
a kernel resource was temporarily unavailable.

.SH "CONFORMING TO"
POSIX.1b (POSIX.4)
.SH "SEE ALSO"
.BR mmap (2)
.BR mincore (2)