Ready for 5.00

[thirdparty/man-pages.git] / man2 / mbind.2

.\" Copyright 2003,2004 Andi Kleen, SuSE Labs.
.\" and Copyright 2007 Lee Schermerhorn, Hewlett Packard
.\"
.\" %%%LICENSE_START(VERBATIM_PROF)
.\" 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.
.\"
.\" Formatted or processed versions of this manual, if unaccompanied by
.\" the source, must acknowledge the copyright and authors of this work.
.\" %%%LICENSE_END
.\"
.\" 2006-02-03, mtk, substantial wording changes and other improvements
.\" 2007-08-27, Lee Schermerhorn <Lee.Schermerhorn@hp.com>
.\"	more precise specification of behavior.
.\"
.\" FIXME
.\" Linux 3.8 added MPOL_MF_LAZY, which needs to be documented.
.\" Does it also apply for move_pages()?
.\"
.\"                commit b24f53a0bea38b266d219ee651b22dba727c44ae
.\"                Author: Lee Schermerhorn <lee.schermerhorn@hp.com>
.\"                Date:   Thu Oct 25 14:16:32 2012 +0200
.\"
.TH MBIND 2 2017-09-15 Linux "Linux Programmer's Manual"
.SH NAME
mbind \- set memory policy for a memory range
.SH SYNOPSIS
.nf
.B "#include <numaif.h>"
.PP
.BI "long mbind(void *" addr ", unsigned long " len  ", int " mode ,
.BI "           const unsigned long *" nodemask  ", unsigned long " maxnode ,
.BI "           unsigned " flags );
.PP
Link with \fI\-lnuma\fP.
.fi
.SH DESCRIPTION
.BR mbind ()
sets the NUMA memory policy,
which consists of a policy mode and zero or more nodes,
for the memory range starting with
.I addr
and continuing for
.I len
bytes.
The memory policy defines from which node memory is allocated.
.PP
If the memory range specified by the
.IR addr " and " len
arguments includes an "anonymous" region of memory\(emthat is
a region of memory created using the
.BR mmap (2)
system call with the
.BR MAP_ANONYMOUS \(emor
a memory-mapped file, mapped using the
.BR mmap (2)
system call with the
.B MAP_PRIVATE
flag, pages will be allocated only according to the specified
policy when the application writes (stores) to the page.
For anonymous regions, an initial read access will use a shared
page in the kernel containing all zeros.
For a file mapped with
.BR MAP_PRIVATE ,
an initial read access will allocate pages according to the
memory policy of the thread that causes the page to be allocated.
This may not be the thread that called
.BR mbind ().
.PP
The specified policy will be ignored for any
.B MAP_SHARED
mappings in the specified memory range.
Rather the pages will be allocated according to the memory policy
of the thread that caused the page to be allocated.
Again, this may not be the thread that called
.BR mbind ().
.PP
If the specified memory range includes a shared memory region
created using the
.BR shmget (2)
system call and attached using the
.BR shmat (2)
system call,
pages allocated for the anonymous or shared memory region will
be allocated according to the policy specified, regardless of which
process attached to the shared memory segment causes the allocation.
If, however, the shared memory region was created with the
.B SHM_HUGETLB
flag,
the huge pages will be allocated according to the policy specified
only if the page allocation is caused by the process that calls
.BR mbind ()
for that region.
.PP
By default,
.BR mbind ()
has an effect only for new allocations; if the pages inside
the range have been already touched before setting the policy,
then the policy has no effect.
This default behavior may be overridden by the
.B MPOL_MF_MOVE
and
.B MPOL_MF_MOVE_ALL
flags described below.
.PP
The
.I mode
argument must specify one of
.BR MPOL_DEFAULT ,
.BR MPOL_BIND ,
.BR MPOL_INTERLEAVE ,
.BR MPOL_PREFERRED ,
or
.BR MPOL_LOCAL
(which are described in detail below).
All policy modes except
.B MPOL_DEFAULT
require the caller to specify the node or nodes to which the mode applies,
via the
.I nodemask
argument.
.PP
The
.I mode
argument may also include an optional
.IR "mode flag" .
The supported
.I "mode flags"
are:
.TP
.BR MPOL_F_STATIC_NODES " (since Linux-2.6.26)"
A nonempty
.I nodemask
specifies physical node IDs.