]> git.saurik.com Git - apple/xnu.git/blame - bsd/man/man2/madvise.2
xnu-1228.7.58.tar.gz
[apple/xnu.git] / bsd / man / man2 / madvise.2
CommitLineData
9bccf70c
A
1.\" $NetBSD: madvise.2,v 1.7 1995/12/27 21:17:02 jtc Exp $
2.\"
3.\" Copyright (c) 1991, 1993
4.\" The Regents of the University of California. All rights reserved.
5.\"
6.\" Redistribution and use in source and binary forms, with or without
7.\" modification, are permitted provided that the following conditions
8.\" are met:
9.\" 1. Redistributions of source code must retain the above copyright
10.\" notice, this list of conditions and the following disclaimer.
11.\" 2. Redistributions in binary form must reproduce the above copyright
12.\" notice, this list of conditions and the following disclaimer in the
13.\" documentation and/or other materials provided with the distribution.
14.\" 3. All advertising materials mentioning features or use of this software
15.\" must display the following acknowledgement:
16.\" This product includes software developed by the University of
17.\" California, Berkeley and its contributors.
18.\" 4. Neither the name of the University nor the names of its contributors
19.\" may be used to endorse or promote products derived from this software
20.\" without specific prior written permission.
21.\"
22.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
23.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
24.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
25.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
26.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
27.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
28.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
29.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
30.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
31.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32.\" SUCH DAMAGE.
33.\"
34.\" @(#)madvise.2 8.1 (Berkeley) 6/9/93
35.\"
36.Dd June 9, 1993
37.Dt MADVISE 2
38.Os
39.Sh NAME
2d21ac55
A
40.Nm madvise ,
41.Nm posix_madvise
9bccf70c
A
42.Nd give advice about use of memory
43.Sh SYNOPSIS
9bccf70c
A
44.Fd #include <sys/mman.h>
45.Ft int
2d21ac55
A
46.Fo madvise
47.Fa "void *addr"
48.Fa "size_t len"
49.Fa "int advice"
50.Fc
9bccf70c 51.Ft int
2d21ac55
A
52.Fo posix_madvise
53.Fa "void *addr"
54.Fa "size_t len"
55.Fa "int advice"
56.Fc
9bccf70c
A
57.Sh DESCRIPTION
58The
59.Fn madvise
2d21ac55
A
60system call allows a process that has knowledge of its memory behavior
61to describe it to the system.
62The advice passed in may be used by the system
63to alter its virtual memory paging strategy.
64This advice may improve application and system performance.
65The behavior specified in
66.Fa advice
9bccf70c
A
67can only be one of the following values:
68.Pp
69.Bl -tag -width MADV_SEQUENTIAL
70.It Dv MADV_NORMAL
2d21ac55
A
71Indicates that the application has no advice to give on its behavior
72in the specified address range.
73This is the system default behavior.
74This is used with
9bccf70c
A
75.Fn madvise
76system call.
77.It Dv POSIX_MADV_NORMAL
78Same as MADV_NORMAL but used with
79.Fn posix_madvise
80system call.
81.It Dv MADV_SEQUENTIAL
2d21ac55
A
82Indicates that the application expects to access this address range
83in a sequential manner.
84This is used with
9bccf70c
A
85.Fn madvise
86system call.
87.It Dv POSIX_MADV_SEQUENTIAL
88Same as MADV_SEQUENTIAL but used with
89.Fn posix_madvise
90system call.
91.It Dv MADV_RANDOM
2d21ac55
A
92Indicates that the application expects to access this address range
93in a random manner.
94This is used with
9bccf70c
A
95.Fn madvise
96system call.
97.It Dv POSIX_MADV_RANDOM
98Same as MADV_RANDOM but used with
99.Fn posix_madvise
100system call.
101.It Dv MADV_WILLNEED
2d21ac55
A
102Indicates that the application expects to access this address range soon.
103This is used with
9bccf70c
A
104.Fn madvise
105system call.
106.It Dv POSIX_MADV_WILLNEED
107Same as MADV_WILLNEED but used with
108.Fn posix_madvise
109system call.
110.It Dv MADV_DONTNEED
2d21ac55
A
111Indicates that the application is not expecting
112to access this address range soon.
113This is used with
9bccf70c
A
114.Fn madvise
115system call.
116.It Dv POSIX_MADV_DONTNEED
117Same as MADV_DONTNEED but used with
118.Fn posix_madvise
119system call.
120.It Dv MADV_FREE
2d21ac55
A
121Indicates that the application will not need the information contained
122in this address range, so the pages may be reused right away.
123The address range will remain valid.
124This is used with
9bccf70c
A
125.Fn madvise
126system call.
127.El
91447636 128.Pp
9bccf70c
A
129The
130.Fn posix_madvise
131behaves same as
132.Fn madvise
133except that it uses values with POSIX_ prefix for the
2d21ac55 134.Fa advice
9bccf70c
A
135system call argument.
136.Sh RETURN VALUES
137Upon successful completion,
138a value of 0 is returned.
139Otherwise, a value of -1 is returned and
140.Va errno
141is set to indicate the error.
142.Sh ERRORS
143.Fn madvise
144fails if one or more of the following are true:
145.Bl -tag -width Er
2d21ac55 146.\" ==========
9bccf70c
A
147.It Bq Er EINVAL
148The value of
2d21ac55 149.Fa advice
9bccf70c 150is incorrect.
2d21ac55
A
151.\" ==========
152.It Bq Er EINVAL
153The address range includes unallocated regions.
154.\" ==========
9bccf70c
A
155.It Bq Er ENOMEM
156The virtual address range specified by the
157.Fa addr
158and
159.Fa len
160are outside the range allowed for the address space.
9bccf70c 161.El
2d21ac55
A
162.Sh LEGACY SYNOPSIS
163.Fd #include <sys/types.h>
164.Fd #include <sys/mman.h>
165.Pp
166.Ft int
167.br
168.Fo madvise
169.Fa "caddr_t addr"
170.Fa "size_t len"
171.Fa "int advice"
172.Fc ;
173.Pp
174.Ft int
175.br
176.Fo posix_madvise
177.Fa "caddr_t addr"
178.Fa "size_t len"
179.Fa "int advice"
180.Fc ;
181.Pp
182The include file
183.In sys/types.h
184is necessary.
185The type of
186.Fa addr
187has changed.
9bccf70c
A
188.Sh SEE ALSO
189.Xr mincore 2 ,
190.Xr minherit 2 ,
191.Xr mprotect 2 ,
192.Xr msync 2 ,
2d21ac55
A
193.Xr munmap 2 ,
194.Xr compat 5
9bccf70c
A
195.Sh HISTORY
196The
197.Nm madvise
198function first appeared in 4.4BSD.
199The
200.Nm posix_madvise
2d21ac55
A
201function is part of IEEE 1003.1-2001
202and was first implemented in Mac OS X 10.2.