.\" Hey Emacs! This file is -*- nroff -*- source.
.\"
-.\" Copyright (C) 2001 David Gez <davidge@jazzfree.com>
+.\" 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
.\"
.\" Based on comments from mm/filemap.c. Last modified on 10-06-2001
.\" Modified, 25 Feb 2002, Michael Kerrisk, <mtk.manpages@gmail.com>
-.\" Added notes on MADV_DONTNEED
-.\" FIXME
-.\" 2.6.32 added MADV_HWPOISON, MADV_MERGEABLE, and MADV_UNMERGEABLE
-.\" 2.6.33 added MADV_SOFT_OFFLINE
+.\" Added notes on MADV_DONTNEED
+.\" 2010-06-19, mtk, Added documentation of MADV_MERGEABLE and
+.\" MADV_UNMERGEABLE
+.\" 2010-06-15, Andi Kleen, Add documentation of MADV_HWPOISON.
+.\" 2010-06-19, Andi Kleen, Add documentation of MADV_SOFT_OFFLINE.
+.\" 2011-09-18, Doug Goldstein <cardoe@cardoe.com>
+.\" Document MADV_HUGEPAGE and MADV_NOHUGEPAGE
.\"
-.\" Japanese Version Copyright (c) 2001 NAKANO Takeo all rights reserved.
-.\" Translated Thu Aug 16 2001 by NAKANO Takeo <nakano@apm.seikei.ac.jp>
-.\" Updated Tue 8 Oct 2002 by NAKANO Takeo
-.\" Updated 2007-01-08, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>, LDP v2.43
+.\"*******************************************************************
.\"
-.TH MADVISE 2 2008-04-22 "Linux" "Linux Programmer's Manual"
+.\" This file was generated with po4a. Translate the source file.
+.\"
+.\"*******************************************************************
+.TH MADVISE 2 2011\-09\-18 Linux "Linux Programmer's Manual"
.SH 名前
madvise \- メモリ利用に関するアドバイスを与える
.SH 書式
-.B #include <sys/mman.h>
+\fB#include <sys/mman.h>\fP
.sp
-.BI "int madvise(void *" addr ", size_t " length ", int " advice );
+\fBint madvise(void *\fP\fIaddr\fP\fB, size_t \fP\fIlength\fP\fB, int \fP\fIadvice\fP\fB);\fP
.sp
.in -4n
-glibc 向けの機能検査マクロの要件
-.RB ( feature_test_macros (7)
-参照):
+glibc 向けの機能検査マクロの要件 (\fBfeature_test_macros\fP(7) 参照):
.in
.sp
-.BR madvise ():
-_BSD_SOURCE
+\fBmadvise\fP(): _BSD_SOURCE
.SH 説明
-.BR madvise ()
-システムコールは、アドレス
-.I addr
-からはじまる
-.I length
-バイトのメモリブロックのページング入出力をどう扱えば良いか、
-カーネルにアドバイスする。
-これを用いると、
-アプリケーションからカーネルに、
-マップされたメモリや共有メモリをどのように扱ってほしいか伝えることができ、
-カーネルはそれに応じて先読みやキャッシュなどの適切な手法を選択できる。
-このコールはアプリケーションの動作そのものには影響しない
-.RB ( MADV_DONTNEED
-の場合は別) が、
-性能には影響しうる。
+\fBmadvise\fP() システムコールは、アドレス \fIaddr\fP からはじまる \fIlength\fP
+バイトのメモリブロックのページング入出力をどう扱えば良いか、 カーネルにアドバイスする。 これを用いると、 アプリケーションからカーネルに、
+マップされたメモリや共有メモリをどのように扱ってほしいか伝えることができ、 カーネルはそれに応じて先読みやキャッシュなどの適切な手法を選択できる。
+このコールはアプリケーションの動作そのものには影響しない (\fBMADV_DONTNEED\fP の場合は別) が、 性能には影響しうる。
なおこのアドバイスを受け入れるかどうかはカーネルに任される。
.LP
-アドバイスは引き数
-.I advice
-によって与える。以下のいずれかを指定できる。
-.TP
-.B MADV_NORMAL
+アドバイスは引き数 \fIadvice\fP によって与える。以下のいずれかを指定できる。
+.TP
+\fBMADV_NORMAL\fP
特別な扱いは行わない。これがデフォルトである。
-.TP
-.B MADV_RANDOM
-ページ参照はランダムな順序で行われそうだ。
-(したがって、先読みはあまり効果がなさそうだ。)
-.TP
-.B MADV_SEQUENTIAL
-ページ参照はシーケンシャルな順序で行われそうだ。
-(したがって与えた範囲のページは積極的に先読みしておくと良いだろう。
+.TP
+\fBMADV_RANDOM\fP
+ページ参照はランダムな順序で行われそうだ。 (したがって、先読みはあまり効果がなさそうだ。)
+.TP
+\fBMADV_SEQUENTIAL\fP
+ページ参照はシーケンシャルな順序で行われそうだ。 (したがって与えた範囲のページは積極的に先読みしておくと良いだろう。
またアクセスが終わったら速やかに解放して良い。)
-.TP
-.B MADV_WILLNEED
-近い将来にアクセスされそうだ。
-(したがってこれらのページを今のうちに先読みしておくといいだろう。)
-.TP
-.B MADV_DONTNEED
-しばらくアクセスはなさそうだ。
-(現時点でアプリケーションは与えた範囲の処理を終えている。
-したがってカーネルはこれに関連するリソースを解放して良い。)
-これ以降この範囲のページへのアクセスがあると、
-成功はするが、メモリの内容をマップ元のファイルからロードし直すことになる
-.RB ( mmap (2)
-を見よ) か、
-または元ファイルがないマップページでは
-アクセスがあったときに 0 埋めが行われることになる。
-.TP
-.BR MADV_REMOVE " (Linux 2.6.16 以降)"
-指定された範囲のページと関連するバッキングストアを解放する。
-現在のところ、
+.TP
+\fBMADV_WILLNEED\fP
+近い将来にアクセスされそうだ。 (したがってこれらのページを今のうちに先読みしておくといいだろう。)
+.TP
+\fBMADV_DONTNEED\fP
+しばらくアクセスはなさそうだ。 (現時点でアプリケーションは与えた範囲の処理を終えている。 したがってカーネルはこれに関連するリソースを解放して良い。)
+これ以降この範囲のページへのアクセスがあると、 成功はするが、メモリの内容をマップ元のファイルからロードし直すことになる (\fBmmap\fP(2)
+を見よ) か、 または元ファイルがないマップページでは アクセスがあったときに 0 埋めが行われることになる。
+.TP
+\fBMADV_REMOVE\fP (Linux 2.6.16 以降)
.\" 2.6.18-rc5
-shmfs/tmpfs だけがこれに対応している。
-他のファイルシステムでは
-.B ENOSYS
-が返される。
.\" Databases want to use this feature to drop a section of their
.\" bufferpool (shared memory segments) - without writing back to
-.\" disk/swap space. This feature is also useful for supporting
+.\" disk/swap space. This feature is also useful for supporting
.\" hot-plug memory on UML.
-.TP
-.BR MADV_DONTFORK " (Linux 2.6.16 以降)"
+指定された範囲のページと関連するバッキングストアを解放する。 現在のところ、 shmfs/tmpfs だけがこれに対応している。
+他のファイルシステムでは \fBENOSYS\fP が返される。
+.TP
+\fBMADV_DONTFORK\fP (Linux 2.6.16 以降)
.\" See http://lwn.net/Articles/171941/
-.BR fork (2)
-が行われた後、指定された範囲のページを子プロセスが利用できないようにする。
-この機能は、書き込み時コピー (copy-on-write) 方式で、
-.BR fork (2)
-の後で親プロセスがページに書き込みを行った場合に
-ページの物理位置が変化しないようにするのに有効である
-(ページの再配置はハードウェアがそのページに DMA 転送を行うような場合に
-問題を起こすことがある)。
.\" [PATCH] madvise MADV_DONTFORK/MADV_DOFORK
.\" Currently, copy-on-write may change the physical address of
.\" a page even if the user requested that the page is pinned in
-.\" memory (either by mlock or by get_user_pages). This happens
+.\" memory (either by mlock or by get_user_pages). This happens
.\" if the process forks meanwhile, and the parent writes to that
.\" page. As a result, the page is orphaned: in case of
.\" get_user_pages, the application will never see any data hardware
.\"
.\" SEE ALSO: http://lwn.net/Articles/171941/
.\" "Tweaks to madvise() and posix_fadvise()", 14 Feb 2006
-.TP
-.BR MADV_DOFORK " (Linux 2.6.16 以降)"
-.B MADV_DONTFORK
-の影響を取り消し、デフォルトの動作に戻す。
-つまり、
-.BR fork (2)
+\fBfork\fP(2) が行われた後、指定された範囲のページを子プロセスが利用できないようにする。 この機能は、書き込み時コピー
+(copy\-on\-write) 方式で、 \fBfork\fP(2) の後で親プロセスがページに書き込みを行った場合に
+ページの物理位置が変化しないようにするのに有効である (ページの再配置はハードウェアがそのページに DMA 転送を行うような場合に
+問題を起こすことがある)。
+.TP
+\fBMADV_DOFORK\fP (Linux 2.6.16 以降)
+\fBMADV_DONTFORK\fP の影響を取り消し、デフォルトの動作に戻す。 つまり、 \fBfork\fP(2)
の前後でマッピングは継承されるようになる。
+.TP
+\fBMADV_HWPOISON\fP (Linux 2.6.32 以降)
+Poison a page and handle it like a hardware memory corruption. This
+operation is only available for privileged (\fBCAP_SYS_ADMIN\fP) processes.
+This operation may result in the calling process receiving a \fBSIGBUS\fP and
+the page being unmapped. This feature is intended for testing of memory
+error\-handling code; it is only available if the kernel was configured with
+\fBCONFIG_MEMORY_FAILURE\fP.
+.TP
+\fBMADV_SOFT_OFFLINE\fP (Linux 2.6.33 以降)
+Soft offline the pages in the range specified by \fIaddr\fP and \fIlength\fP. The
+memory of each page in the specified range is preserved (i.e., when next
+accessed, the same content will be visible, but in a new physical page
+frame), and the original page is offlined (i.e., no longer used, and taken
+out of normal memory management). The effect of the \fBMADV_SOFT_OFFLINE\fP
+operation is invisible to (i.e., does not change the semantics of) the
+calling process. This feature is intended for testing of memory
+error\-handling code; it is only available if the kernel was configured with
+\fBCONFIG_MEMORY_FAILURE\fP.
+.TP
+\fBMADV_MERGEABLE\fP (Linux 2.6.32 以降)
+Enable Kernel Samepage Merging (KSM) for the pages in the range specified by
+\fIaddr\fP and \fIlength\fP. The kernel regularly scans those areas of user
+memory that have been marked as mergeable, looking for pages with identical
+content. These are replaced by a single write\-protected page (which is
+automatically copied if a process later wants to update the content of the
+page). KSM only merges private anonymous pages (see \fBmmap\fP(2)). The KSM
+feature is intended for applications that generate many instances of the
+same data (e.g., virtualization systems such as KVM). It can consume a lot
+of processing power; use with care. See the kernel source file
+\fIDocumentation/vm/ksm.txt\fP for more details. The \fBMADV_MERGEABLE\fP and
+\fBMADV_UNMERGEABLE\fP operations are only available if the kernel was
+configured with \fBCONFIG_KSM\fP.
+.TP
+\fBMADV_UNMERGEABLE\fP (Linux 2.6.32 以降)
+Undo the effect of an earlier \fBMADV_MERGEABLE\fP operation on the specified
+address range; KSM unmerges whatever pages it had merged in the address
+range specified by \fIaddr\fP and \fIlength\fP.
+.TP
+\fBMADV_HUGEPAGE\fP (Linux 2.6.38 以降)
+.\" http://lwn.net/Articles/358904/
+.\" https://lwn.net/Articles/423584/
+Enables Transparent Huge Pages (THP) for pages in the range specified by
+\fIaddr\fP and \fIlength\fP. Currently, Transparent Huge Pages only work with
+private anonymous pages (see \fBmmap\fP(2)). The kernel will regularly scan
+the areas marked as huge page candidates to replace them with huge pages.
+The kernel will also allocate huge pages directly when the region is
+naturally aligned to the huge page size (see \fBposix_memalign\fP(2)). This
+feature is primarily aimed at applications that use large mappings of data
+and access large regions of that memory at a time (e.g. virtualization
+systems such as QEMU). It can very easily waste memory (e.g. a 2MB mapping
+that only ever accesses 1 byte will result in 2MB of wired memory instead of
+one 4KB page). See the kernel source file \fIDocumentation/vm/transhuge.txt\fP
+for more details. The \fBMADV_HUGEPAGE\fP and \fBMADV_NOHUGEPAGE\fP operations
+are only available if the kernel was configured with
+\fBCONFIG_TRANSPARENT_HUGEPAGE\fP.
+.TP
+\fBMADV_NOHUGEPAGE\fP (Linux 2.6.38 以降)
+Ensures that memory in the address range specified by \fIaddr\fP and \fIlength\fP
+will not be collapsed into huge pages.
.SH 返り値
-.BR madvise ()
-は成功すると 0 を返す。
-エラーが起こると \-1 を返し、
-.I errno
-を適切な値に設定する。
+\fBmadvise\fP() は成功すると 0 を返す。 エラーが起こると \-1 を返し、 \fIerrno\fP を適切な値に設定する。
.SH エラー
-.TP
-.B EAGAIN
+.TP
+\fBEAGAIN\fP
何らかのカーネルリソースが一時的に利用できなかった。
-.TP
-.B EBADF
+.TP
+\fBEBADF\fP
指定したマップは存在するが、ファイルではないところをマップしている。
-.TP
-.B EINVAL
+.TP
+\fBEINVAL\fP
+This error can occur for the following reasons:
+.RS
+.IP * 3
.\" .I len
.\" is zero,
-.I len
-の値が負、
-.I addr
-がページ境界でない、
-.I advice
-が正しい値でない、
-アプリケーションがロックされたページや共有ページを
-.RB ( MADV_DONTNEED
-で) 解放しようとしている、など。
-.TP
-.B EIO
-.RB ( MADV_WILLNEED
-の場合) この範囲のページングを行うと、
-プロセスの RSS (resident set size) の最大値を越えてしまう。
-.\"nakano RSS は訳語がありましたっけ?
-.TP
-.B ENOMEM
-.RB ( MADV_WILLNEED
-の場合) メモリが足りず、ページングに失敗した。
-.TP
-.B ENOMEM
-指定した範囲のアドレスが、現在マップされていない。
-あるいはプロセスのアドレス空間の内部にない。
+\fIlen\fP が負の値である。
+.IP *
+\fIaddr\fP is not page\-aligned.
+.IP *
+\fIadvice\fP が有効な値でない。
+.IP *
+アプリケーションがロックされたページや共有ページを (\fBMADV_DONTNEED\fP で) 解放
+しようとしている。
+.IP *
+\fBMADV_MERGEABLE\fP or \fBMADV_UNMERGEABLE\fP was specified in \fIadvice\fP, but the
+kernel was not configured with \fBCONFIG_KSM\fP.
+.RE
+.TP
+\fBEIO\fP
+(\fBMADV_WILLNEED\fP の場合) この範囲のページングを行うと、 プロセスの RSS (resident set size)
+の最大値を越えてしまう。
+.TP
+\fBENOMEM\fP
+(\fBMADV_WILLNEED\fP の場合) メモリが足りず、ページングに失敗した。
+.TP
+\fBENOMEM\fP
+指定した範囲のアドレスが、現在マップされていない。 あるいはプロセスのアドレス空間の内部にない。
.SH 準拠
-POSIX.1b.
-POSIX.1-2001 では、
-.BR posix_madvise (3)
.\" FIXME . Write a posix_fadvise(3) page.
-を
-.B POSIX_MADV_NORMAL
-などの定数とともに記述していた
-(それぞれの振る舞いはここで述べたものに近い)。
-ファイルアクセスに対しても
-.BR posix_fadvise (2)
+POSIX.1b. POSIX.1\-2001 では、 \fBposix_madvise\fP(3) を \fBPOSIX_MADV_NORMAL\fP
+などの定数とともに記述していた (それぞれの振る舞いはここで述べたものに近い)。 ファイルアクセスに対しても \fBposix_fadvise\fP(2)
という類似の関数が存在する。
-.BR MADV_REMOVE ,
-.BR MADV_DONTFORK ,
-.B MADV_DOFORK
-は Linux 固有である。
+\fBMADV_REMOVE\fP, \fBMADV_DONTFORK\fP, \fBMADV_DOFORK\fP, \fBMADV_HWPOISON\fP,
+\fBMADV_MERGEABLE\fP, \fBMADV_UNMERGEABLE\fP は Linux 固有である。
.SH 注意
.SS "Linux での注意"
-現在の Linux の実装 (2.4.0) では、
-このシステムコールをアドバイスというよりは命令と見ている。
-したがってこのアドバイスに対して通常行われる動作が不可能な場合は、
-エラーを返すことがある (上記の エラー の記述を参照)。
+.LP
+現在の Linux の実装 (2.4.0) では、 このシステムコールをアドバイスというよりは命令と見ている。
+したがってこのアドバイスに対して通常行われる動作が不可能な場合は、 エラーを返すことがある (上記の エラー の記述を参照)。
この振舞いは標準とは異なる。
.LP
-Linux の実装では
-.I addr
-のアドレスはページ境界の値でなければならない。また
-.I length
-は 0 であっても構わない。
-また Linux 版の
-.BR madvise ()
-では、指定されたアドレス範囲にマップされていない部分があると、
-これらを無視して残りの部分にアドバイスを適用する
-(しかしシステムコールに対してはちゃんと
-.B ENOMEM
-を返す)。
-.\" .SH 歴史
+.\" .SH HISTORY
+.\" The
.\" .BR madvise ()
-.\" 関数は 4.4BSD で最初に登場した。
+.\" function first appeared in 4.4BSD.
+Linux の実装では \fIaddr\fP のアドレスはページ境界の値でなければならない。また \fIlength\fP は 0 であっても構わない。 また
+Linux 版の \fBmadvise\fP() では、指定されたアドレス範囲にマップされていない部分があると、
+これらを無視して残りの部分にアドバイスを適用する (しかしシステムコールに対してはちゃんと \fBENOMEM\fP を返す)。
.SH 関連項目
-.BR getrlimit (2),
-.BR mincore (2),
-.BR mmap (2),
-.BR mprotect (2),
-.BR msync (2),
-.BR munmap (2)
+\fBgetrlimit\fP(2), \fBmincore\fP(2), \fBmmap\fP(2), \fBmprotect\fP(2), \fBmsync\fP(2),
+\fBmunmap\fP(2)
+.SH この文書について
+この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.40 の一部
+である。プロジェクトの説明とバグ報告に関する情報は
+http://www.kernel.org/doc/man\-pages/ に書かれている。
OSDN Git Service
