OSDN Git Service

509b155a3bcd0ecb271f1834811cf6ec6e254d9a
[linuxjm/LDP_man-pages.git] / draft / man2 / process_vm_readv.2
1 .\" Copyright (C) 2011 Christopher Yeoh <cyeoh@au1.ibm.com>
2 .\" and Copyright (C) 2012 Mike Frysinger <vapier@gentoo.org>
3 .\" and Copyright (C) 2012 Michael Kerrisk <mtk.man-pages@gmail.com>
4 .\"
5 .\" %%%LICENSE_START(VERBATIM)
6 .\" Permission is granted to make and distribute verbatim copies of this
7 .\" manual provided the copyright notice and this permission notice are
8 .\" preserved on all copies.
9 .\"
10 .\" Permission is granted to copy and distribute modified versions of this
11 .\" manual under the conditions for verbatim copying, provided that the
12 .\" entire resulting derived work is distributed under the terms of a
13 .\" permission notice identical to this one.
14 .\"
15 .\" Since the Linux kernel and libraries are constantly changing, this
16 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
17 .\" responsibility for errors or omissions, or for damages resulting from
18 .\" the use of the information contained herein.  The author(s) may not
19 .\" have taken the same level of care in the production of this manual,
20 .\" which is licensed free of charge, as they might when working
21 .\" professionally.
22 .\"
23 .\" Formatted or processed versions of this manual, if unaccompanied by
24 .\" the source, must acknowledge the copyright and authors of this work.
25 .\" %%%LICENSE_END
26 .\"
27 .\" Commit fcf634098c00dd9cd247447368495f0b79be12d1
28 .\"*******************************************************************
29 .\"
30 .\" This file was generated with po4a. Translate the source file.
31 .\"
32 .\"*******************************************************************
33 .TH PROCESS_VM_READV 2 2014\-08\-19 Linux "Linux Programmer's Manual"
34 .SH 名前
35 process_vm_readv, process_vm_writev \- プロセスのアドレス空間間でデータを転送する
36 .SH 書式
37 .nf
38 \fB#include <sys/uio.h>\fP
39
40 \fBssize_t process_vm_readv(pid_t \fP\fIpid\fP\fB,\fP
41 \fB                         const struct iovec *\fP\fIlocal_iov\fP\fB,\fP
42 \fB                         unsigned long \fP\fIliovcnt\fP\fB,\fP
43 \fB                         const struct iovec *\fP\fIremote_iov\fP\fB,\fP
44 \fB                         unsigned long \fP\fIriovcnt\fP\fB,\fP
45 \fB                         unsigned long \fP\fIflags\fP\fB);\fP
46
47 \fBssize_t process_vm_writev(pid_t \fP\fIpid\fP\fB,\fP
48 \fB                          const struct iovec *\fP\fIlocal_iov\fP\fB,\fP
49 \fB                          unsigned long \fP\fIliovcnt\fP\fB,\fP
50 \fB                          const struct iovec *\fP\fIremote_iov\fP\fB,\fP
51 \fB                          unsigned long \fP\fIriovcnt\fP\fB,\fP
52 \fB                          unsigned long \fP\fIflags\fP\fB);\fP
53 .fi
54 .sp
55 .in -4n
56 glibc 向けの機能検査マクロの要件 (\fBfeature_test_macros\fP(7) 参照):
57 .in
58 .sp
59 \fBprocess_vm_readv\fP(), \fBprocess_vm_writev\fP():
60 .PD 0
61 .ad l
62 .RS 4
63 \fB_GNU_SOURCE\fP
64 .RE
65 .ad
66 .PD
67 .fi
68 .SH 説明
69 これらのシステムコールは、 呼び出し元プロセス (「ローカルプロセス」) と \fIpid\fP で指定されるプロセス (「リモートプロセス」)
70 のアドレス空間間でデータを転送する。 データの移動は、 カーネル空間を経由することなく、 2 つのプロセスのアドレス空間間で直接行われる。
71
72 \fBprocess_vm_readv\fP() システムコールは、 リモートプロセスからローカルプロセスへデータを転送する。 転送対象のデータは
73 \fIremote_iov\fP と \fIriovcnt\fP で指定される。 \fIremote_iov\fP はプロセス \fIpid\fP
74 におけるアドレス範囲を指定する配列へのポインターで、 \fIriovcnt\fP は \fIremote_iov\fP の要素数を指定する。 データは
75 \fIlocal_iov\fP と \fIliovcnt\fP で指定された場所に転送される。 \fIlocal_iov\fP
76 は呼び出し元プロセスにおけるアドレス範囲を指定する配列で、 \fIliovcnt\fP は \fIlocal_iov\fP の要素数を指定する。
77
78 \fBprocess_vm_writev\fP() システムコールは \fBprocess_vm_readv\fP() の逆で、
79 ローカルプロセスからリモートプロセスにデータを転送する。 転送の方向が違う以外は、 引き数 \fIliovcnt\fP, \fIlocal_iov\fP,
80 \fIriovcnt\fP, \fIremote_iov\fP は \fBprocess_vm_readv\fP() と同じ意味を持つ。
81
82 引き数 \fIlocal_iov\fP と \fIremote_iov\fP は \fIiovec\fP 構造体の配列へのポイン
83 タである。 \fIiovec\fP 構造体は \fI<sys/uio.h>\fP で以下のように定義
84 されている:
85
86 .in +4n
87 .nf
88 struct iovec {
89     void  *iov_base;    /* Starting address */
90     size_t iov_len;     /* Number of bytes to transfer */
91 };
92 .fi
93 .in
94
95 バッファーは配列の順序で処理される。 つまり、 \fBprocess_vm_readv\fP() は \fIlocal_iov\fP[0]
96 が一杯になるまでデータを詰めてから、 \fIlocal_iov\fP[1] に進むことを意味する。 同様に、 \fIremote_iov\fP[0]
97 を全部読み出してから \fIremote_iov\fP[1] に進み、 以降も同様である。
98
99 同様に、 \fBprocess_vm_writev\fP() は \fIlocal_iov[0]\fP の内容を全部読み出してから \fIlocal_iov[1]\fP
100 に進み、 書き込み先でも \fIremote_iov[0]\fP が一杯になってから \fIremote_iov[1]\fP に進む。
101
102 長さ \fIremote_iov[i].iov_len\fP と \fIlocal_iov[i].iov_len\fP は同じである必要はない。 したがって、
103 ローカル側で 1 つのバッファーのデータがリモート側で複数のバッファーに分割されることがあるし、 その逆も起こりえる。
104
105 \fIflags\fP 引き数は現在使用されておらず、 0 を設定しなければならない。
106
107 .\" In time, glibc might provide a wrapper that works around this limit,
108 .\" as is done for readv()/writev()
109 \fIliovcnt\fP と \fIriovcnt\fP で指定される値は \fBIOV_MAX\fP 以下でなければならない (\fBIOV_MAX\fP は
110 \fI<limits.h>\fP で定義されており、 \fIsysconf(_SC_IOV_MAX)\fP の呼び出しでも入手できる)。
111
112 要素数引き数と \fIlocal_iov\fP のチェックは、 すべてのデータ転送に先立って行われる。 要素数が大きすぎる場合や \fIlocal_iov\fP
113 が無効な場合、 アドレスがローカルプロセスがアクセスできない領域を参照している場合は、 配列のどの要素も処理されず、 すぐにエラーが返される。
114
115 ただし、 これらのシステムコールは、 実際に読み出し/書き込みを行う直前までリモートプロセスのメモリー領域のチェックを行わない点に注意すること。
116 結果として、 \fIremote_iov\fP の要素の一つがリモートプロセスで無効なメモリー領域を参照している場合、 部分的な読み出し/書き込み
117 (「返り値」の節を参照) が行われることになる。 これ以降は読み出し/書き込みは行われない。 リモートプロセスから長さ不明のデータ (例えば NULL
118 終端された C 文字列) を読み出す際で、 リモート側の一つの \fIiovec\fP 要素が複数のメモリーページ (通常は 4KiB)
119 にまたがらないようにしている場合は、 この点に注意が必要である。
120 (リモートからの読み出しを 2 つの \fIremote_iov\fP 要素に分割し、 1 つの \fIlocal_iov\fP
121 要素への書き込みにマージすればよい。 最初の読み出しでページ境界まで読み出し、 次の読み出しを次のページ境界から行う。)
122
123 他のプロセスからの読み出しや他のプロセスへの書き込みを行うには、 呼び出し元がケーパビリティ \fBCAP_SYS_PTRACE\fP
124 を持っていなければならない、もしくは、 リモートプロセスの実ユーザー ID、 実効ユーザー ID、 保存 set\-user\-ID
125 が呼び出し元の実ユーザー ID と一致し、 かつリモートプロセスの実グループ ID、 実効グループ ID、 保存 set\-group\-ID
126 が呼び出し元の実グループ ID と一致していなければならない。 (ここで必要なアクセス許可は、 リモートプロセスに対して \fBptrace\fP(2) の
127 \fBPTRACE_ATTACH\fP を実行するのに必要な許可と全く同じである。)
128 .SH 返り値
129 成功すると、 \fBprocess_vm_readv\fP() は読み出したバイト数を返し、 \fBprocess_vm_writev\fP()
130 は書き込んだバイト数を返す。 この返り値は、 読み出し/書き込みが部分的に行われた場合には、 要求された総バイト数よりも小さくなることがある
131 (部分的な転送は \fIiovec\fP 要素単位に行われ、 これらのシステムコールが一つの \fIiovec\fP 要素の一部だけが転送されることはない)。
132 呼び出し元は返り値を検査して、 部分的な読み出し/書き込みが起こったかどうかを判定できる。
133
134 エラーの場合は \-1 が返され、 \fIerrno\fP が適切に設定される。
135 .SH エラー
136 .TP 
137 \fBEINVAL\fP
138 \fIlocal_iov\fP か \fIremote_iov\fP のいずれかの \fIiov_len\fP の合計値が \fIssize_t\fP
139 で表現できる値を超えている。
140 .TP 
141 \fBEINVAL\fP
142 \fIflags\fP が 0 でない。
143 .TP 
144 \fBEINVAL\fP
145 \fIliovcnt\fP か \fIriovcnt\fP が大きすぎる。
146 .TP 
147 \fBEFAULT\fP
148 \fIlocal_iov\fP で指定されたメモリーが呼び出し元がアクセス可能なアドレス空間の外にある。
149 .TP 
150 \fBEFAULT\fP
151 \fIremote_iov\fP で指定されたメモリーがプロセス \fIpid\fP がアクセス可能なアドレス空間の外にある。
152 .TP 
153 \fBENOMEM\fP
154 \fIiovec\fP 構造体の内部コピーのためのメモリーを割り当てできなかった。
155 .TP 
156 \fBEPERM\fP
157 呼び出し側がプロセス \fIpid\fP のアドレス空間に対するアクセス許可を
158 持っていない。
159 .TP 
160 \fBESRCH\fP
161 ID が \fIpid\fP のプロセスが存在しない。
162 .SH バージョン
163 これらのシステムコールは Linux 3.2 で追加された。ライブラリによる
164 サポートは glibc バージョン 2.15 以降で提供されている。
165 .SH 準拠
166 これらのシステムコールは非標準で Linux による拡張である。
167 .SH 注意
168 \fBprocess_vm_readv\fP() と \fBprocess_vm_writev\fP() により実行されるデータ転送をどのように行ったとしても、
169 これらがアトミックに行われる保証はない。
170
171 .\" Original user is MPI, http://www.mcs.anl.gov/research/projects/mpi/
172 .\" See also some benchmarks at http://lwn.net/Articles/405284/
173 .\" and http://marc.info/?l=linux-mm&m=130105930902915&w=2
174 これらのシステムコールは、 (共有メモリーやパイプなどを使った場合に必要となる 2 回のコピーではなく)
175 1 回のコピー処理でメッセージの交換を許すことで、 高速なメッセージ送信をできるようにするために設計された。
176 .SH 例
177 以下のサンプルコードは \fBprocess_vm_readv\fP() の使用例を示すものである。 このコードは PID 10 のプロセスのアドレス
178 0x10000 から 20 バイトを読み取り、 最初の 10 バイトを \fIbuf1\fP に、 残りの 10 バイトを \fIbuf2\fP に書き込む。
179 .sp
180 .nf
181 #include <sys/uio.h>
182
183 int
184 main(void)
185 {
186     struct iovec local[2];
187     struct iovec remote[1];
188     char buf1[10];
189     char buf2[10];
190     ssize_t nread;
191     pid_t pid = 10;             /* PID of remote process */
192
193     local[0].iov_base = buf1;
194     local[0].iov_len = 10;
195     local[1].iov_base = buf2;
196     local[1].iov_len = 10;
197     remote[0].iov_base = (void *) 0x10000;
198     remote[0].iov_len = 20;
199
200     nread = process_vm_readv(pid, local, 2, remote, 1, 0);
201     if (nread != 20)
202         return 1;
203     else
204         return 0;
205 }
206 .fi
207 .SH 関連項目
208 \fBreadv\fP(2), \fBwritev\fP(2)
209 .SH この文書について
210 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.78 の一部
211 である。プロジェクトの説明とバグ報告に関する情報は
212 http://www.kernel.org/doc/man\-pages/ に書かれている。