[apple/xnu.git] / bsd / man / man2 / madvise.2

.\"	$NetBSD: madvise.2,v 1.7 1995/12/27 21:17:02 jtc Exp $
.\"
.\" Copyright (c) 1991, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"	@(#)madvise.2	8.1 (Berkeley) 6/9/93
.\"
.Dd June 9, 1993
.Dt MADVISE 2
.Os
.Sh NAME
.Nm madvise
.Nd give advice about use of memory
.Sh SYNOPSIS
.Fd #include <sys/types.h>
.Fd #include <sys/mman.h>
.Ft int
.Fn madvise "caddr_t addr" "size_t len" "int behav"
.Ft int
.Fn posix_madvise "caddr_t addr" "size_t len" "int behav"
.Sh DESCRIPTION
The
.Fn madvise
system call allows a process that has knowledge of its memory behavior to describe it to the system. The advice passed in may be used by the system to alter its virtual memory paging strategy. This advice may improve application and system performance. The behavior specified in
.Fa behav
can only be one of the following values:
.Pp
.Bl -tag -width MADV_SEQUENTIAL
.It Dv  MADV_NORMAL
Indicates that the application has no advice to give on its behavior in the specifed address range. This is the system default behavior. This is used with 
.Fn madvise
system call.
.It Dv POSIX_MADV_NORMAL
Same as MADV_NORMAL but used with 
.Fn posix_madvise
system call.
.It Dv MADV_SEQUENTIAL
Indicates that the application expects to access this address range in a sequential manner. This is used with
.Fn madvise
system call.
.It Dv POSIX_MADV_SEQUENTIAL
Same as MADV_SEQUENTIAL but used with 
.Fn posix_madvise
system call.
.It Dv MADV_RANDOM
Indicates that the application expects to access this address range in a random manner. This is used with
.Fn madvise
system call.
.It Dv POSIX_MADV_RANDOM
Same as MADV_RANDOM but used with 
.Fn posix_madvise
system call.
.It Dv MADV_WILLNEED
Indicates that the application expects to access this address range soon. This is used with
.Fn madvise
system call.
.It Dv POSIX_MADV_WILLNEED
Same as MADV_WILLNEED but used with 
.Fn posix_madvise
system call.
.It Dv MADV_DONTNEED
Indicates that the application is not expecting to access this address range soon. This is used with
.Fn madvise
system call.
.It Dv POSIX_MADV_DONTNEED
Same as MADV_DONTNEED but used with 
.Fn posix_madvise
system call.
.It Dv MADV_FREE
Indicates that the application will not need the information contained in this address range so the pages may be reused right away. The address range will remain valid. This is used with
.Fn madvise
system call.
.El
.Pp
The
.Fn posix_madvise
behaves same as 
.Fn madvise
except that it uses values with POSIX_ prefix for the 
.Fa behav
system call argument.
.Sh RETURN VALUES
Upon successful completion,
a value of 0 is returned.
Otherwise, a value of -1 is returned and
.Va errno
is set to indicate the error.
.Sh ERRORS
.Fn madvise
fails if one or more of the following are true:
.Bl -tag -width Er
.It Bq Er EINVAL
The value of 
.Fa behav 
is incorrect.
.It Bq Er ENOMEM
The virtual address range specified by the 
.Fa addr
and
.Fa len
are outside the range allowed for the address space.
.It Bq Er EINVAL
The address range includes unallocated regions.
.El
.Sh SEE ALSO
.Xr mincore 2 ,
.Xr minherit 2 ,
.Xr mprotect 2 , 
.Xr msync 2 ,
.Xr munmap 2
.Sh HISTORY
The
.Nm madvise
function first appeared in 4.4BSD.
The
.Nm posix_madvise
function is part of IEEE 1003.1-2001 and was first implemented in Mac OS X 10.2.
Commit	Line	Data
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
	40	.Nm madvise
	41	.Nd give advice about use of memory
	42	.Sh SYNOPSIS
	43	.Fd #include <sys/types.h>
	44	.Fd #include <sys/mman.h>
	45	.Ft int
	46	.Fn madvise "caddr_t addr" "size_t len" "int behav"
	47	.Ft int
	48	.Fn posix_madvise "caddr_t addr" "size_t len" "int behav"
	49	.Sh DESCRIPTION
	50	The
	51	.Fn madvise
	52	system call allows a process that has knowledge of its memory behavior to describe it to the system. The advice passed in may be used by the system to alter its virtual memory paging strategy. This advice may improve application and system performance. The behavior specified in
	53	.Fa behav
	54	can only be one of the following values:
	55	.Pp
	56	.Bl -tag -width MADV_SEQUENTIAL
	57	.It Dv MADV_NORMAL
	58	Indicates that the application has no advice to give on its behavior in the specifed address range. This is the system default behavior. This is used with
	59	.Fn madvise
	60	system call.
	61	.It Dv POSIX_MADV_NORMAL
	62	Same as MADV_NORMAL but used with
	63	.Fn posix_madvise
	64	system call.
65	.It Dv MADV_SEQUENTIAL
66	Indicates that the application expects to access this address range in a sequential manner. This is used with
67	.Fn madvise
68	system call.
69	.It Dv POSIX_MADV_SEQUENTIAL
70	Same as MADV_SEQUENTIAL but used with
71	.Fn posix_madvise
72	system call.
73	.It Dv MADV_RANDOM
74	Indicates that the application expects to access this address range in a random manner. This is used with
75	.Fn madvise
76	system call.
77	.It Dv POSIX_MADV_RANDOM
78	Same as MADV_RANDOM but used with
79	.Fn posix_madvise
80	system call.
81	.It Dv MADV_WILLNEED
82	Indicates that the application expects to access this address range soon. This is used with
83	.Fn madvise
84	system call.
85	.It Dv POSIX_MADV_WILLNEED
86	Same as MADV_WILLNEED but used with
87	.Fn posix_madvise
88	system call.
89	.It Dv MADV_DONTNEED
90	Indicates that the application is not expecting to access this address range soon. This is used with
91	.Fn madvise
92	system call.
93	.It Dv POSIX_MADV_DONTNEED
94	Same as MADV_DONTNEED but used with
95	.Fn posix_madvise
96	system call.
97	.It Dv MADV_FREE
98	Indicates that the application will not need the information contained in this address range so the pages may be reused right away. The address range will remain valid. This is used with
99	.Fn madvise
100	system call.
101	.El
91447636	102	.Pp
9bccf70c A	103	The
	104	.Fn posix_madvise
	105	behaves same as
	106	.Fn madvise
	107	except that it uses values with POSIX_ prefix for the
	108	.Fa behav
	109	system call argument.
	110	.Sh RETURN VALUES
	111	Upon successful completion,
	112	a value of 0 is returned.
	113	Otherwise, a value of -1 is returned and
	114	.Va errno
	115	is set to indicate the error.
	116	.Sh ERRORS
	117	.Fn madvise
	118	fails if one or more of the following are true:
	119	.Bl -tag -width Er
	120	.It Bq Er EINVAL
	121	The value of
	122	.Fa behav
	123	is incorrect.
	124	.It Bq Er ENOMEM
	125	The virtual address range specified by the
	126	.Fa addr
	127	and
	128	.Fa len
	129	are outside the range allowed for the address space.
	130	.It Bq Er EINVAL
	131	The address range includes unallocated regions.
	132	.El
	133	.Sh SEE ALSO
	134	.Xr mincore 2 ,
	135	.Xr minherit 2 ,
	136	.Xr mprotect 2 ,
	137	.Xr msync 2 ,
	138	.Xr munmap 2
	139	.Sh HISTORY
	140	The
	141	.Nm madvise
	142	function first appeared in 4.4BSD.
	143	The
	144	.Nm posix_madvise
	145	function is part of IEEE 1003.1-2001 and was first implemented in Mac OS X 10.2.