release/man2/memfd_create.2

   1 .\" Copyright (C) 2014 Michael Kerrisk <mtk.manpages@gmail.com>
   2 .\" and Copyright (C) 2014 David Herrmann <dh.herrmann@gmail.com>
   3 .\"
   4 .\" %%%LICENSE_START(GPLv2+)
   5 .\" This program is free software; you can redistribute it and/or modify
   6 .\" it under the terms of the GNU General Public License as published by
   7 .\" the Free Software Foundation; either version 2 of the License, or
   8 .\" (at your option) any later version.
   9 .\"
  10 .\" This program is distributed in the hope that it will be useful,
  11 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  12 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  13 .\" GNU General Public License for more details.
  14 .\"
  15 .\" You should have received a copy of the GNU General Public
  16 .\" License along with this manual; if not, see
  17 .\" <http://www.gnu.org/licenses/>.
  18 .\" %%%LICENSE_END
  19 .\"
  20 .\"*******************************************************************
  21 .\"
  22 .\" This file was generated with po4a. Translate the source file.
  23 .\"
  24 .\"*******************************************************************
  25 .TH MEMFD_CREATE 2 2014\-07\-08 Linux "Linux Programmer's Manual"
  26 .SH 名前
  27 memfd_create \- 無名ファイル (anonymous file) を作成する
  28 .SH 書式
  29 \fB#include <sys/memfd.h>\fP
  30 .sp
  31 \fBint memfd_create(const char *\fP\fIname\fP\fB, unsigned int \fP\fIflags\fP\fB);\fP
  32 .SH 説明
  33 .\" David Herrmann:
  34 .\"     memfd uses VM_NORESERVE so each page is accounted on first access.
  35 .\"     This means, the overcommit-limits (see __vm_enough_memory()) and the
  36 .\"     memory-cgroup limits (mem_cgroup_try_charge()) are applied. Note that
  37 .\"     those are accounted on "current" and "current->mm", that is, the
  38 .\"     process doing the first page access.
  39 \fBmemfd_create\fP() は、 無名ファイル (anonymous file) を作成し、
  40 そのファイルを参照するファイルディスクリプターを返す。 このファイルは通常のファイルと同様に振る舞い、 変更、切り詰め (truncate)、
  41 メモリーマップなどを行うことができる。 しかし、 通常のファイルとは違い、 このファイルは RAM 上に置かれ、 格納されるストレージは揮発性である。
  42 このファイルへの参照がすべてなくなると、 ファイルは自動的に解放される。 このファイルが置かれるページには無名メモリー (anonymous
  43 memory) が使用される。 したがって、 \fBmemfd_create\fP() で作成されたフィアルは、 他の無名メモリーの割り当て
  44 (\fBMAP_ANONYMOUS\fP フラグ付きの \fBmmap\fP(2) を使って割り当てられた無名メモリーなど) と同じ動作をする。
  45
  46 ファイルの初期サイズは 0 に設定される。 呼び出しの後に、 \fBftruncate\fP(2) を使ってファイルサイズを設定すべきである (代わりに、
  47 \fBwrite\fP(2) や同様の関数を呼び出してファイルにデータを書き込むこともできる)。
  48
  49 \fIname\fP に指定された名前はファイル名として使用され、 ディレクトリ \fI/proc/self/fd/\fP
  50 で対応するシンボリックリンクのリンク先として表示される。 表示される名前の前には常に \fImemfd:\fP が付き、
  51 この名前はデバッグ用途としてのみ機能する。 名前はファイルディスクリプターの動作には影響せず、 複数のファイルが同じ名前を持っても副作用はない。
  52
  53 以下の値をビット論理和で \fIflags\fP に指定して、 \fBmemfd_create\fP() の動作を変更できる。
  54 .TP
  55 \fBMFD_CLOEXEC\fP
  56 新しいファイルディスクリプターに close\-on\-exec (\fBFD_CLOEXEC\fP) フラグをセットする。 これが有用な理由については
  57 \fBopen\fP(2) の \fBO_CLOEXEC\fP フラグの説明を参照のこと。
  58 .TP
  59 \fBMFD_ALLOW_SEALING\fP
  60 .\" FIXME Why is the MFD_ALLOW_SEALING behavior not simply the default?
  61 .\"       Is it worth adding some text explaining this?
  62 このファイルに対して sealing 操作を許可する。 \fBfcntl\fP(2) の \fBF_ADD_SEALS\fP と \fBF_GET_SEALS\fP
  63 操作の議論を参照。 下記の「注意」も参照。 初期の seal 集合は空となる。 このフラグを指定しなかった場合、 初期の seal 集合は
  64 \fBF_SEAL_SEAL\fP となり、 これはこのファイルには他の seal をセットできないことということである。
  65 .PP
  66 \fIflags\fP の未使用のビットは 0 でなければならない。
  67
  68 返り値として \fBmemfd_create\fP() は、 作成したファイルを参照するのに使用できる新しいファイルディスクリプターを返す。
  69 このファイルディスクリプターは読み書き両用 (\fBO_RDWR\fP) でオープンされ、 \fBO_LARGEFILE\fP
  70 がこのファイルディスクリプターにセットされる。
  71
  72 \fBfork\fP(2) と \fBexecve\fP(2) に関しては、 \fBmemfd_create\fP()
  73 で作成したファイルディスクリプターについても通常の動作が適用される。 ファイルディスクリプターのコピーは \fBfork\fP(2)
  74 で生成される子プロセスに継承され、 同じファイルを参照する。 close\-on\-exec フラグがセットされていない限り、 \fBexecve\fP(2)
  75 の前後でファイルディスクリプターは保持される。
  76 .SH 返り値
  77 成功の場合、 \fBmemfd_create\fP() は新しいファイルディスクリプターを返す。 エラーの場合、\-1 を返し、 \fIerrno\fP
  78 にエラーを示す値を設定する。
  79 .SH エラー
  80 .TP
  81 \fBEFAULT\fP
  82 \fIname\fP のアドレスが無効なメモリーを指している。
  83 .TP
  84 \fBEINVAL\fP
  85 サポートされていない値がいずれかの引き数で指定された。 \fIflags\fP に未知のビットが含まれていたか、 \fIname\fP が長過ぎた。
  86 .TP
  87 \fBEMFILE\fP
  88 オープンされているファイルディスクリプターのプロセス単位の上限に達した。
  89 .TP
  90 \fBENFILE\fP
  91 システム全体でオープンされているファイルの総数が上限に達した。
  92 .TP
  93 \fBENOMEM\fP
  94 新しい無名ファイルを作成するのに十分なメモリがなかった。
  95 .SH バージョン
  96 .\" FIXME . When glibc support appears, update the following sentence:
  97 \fBmemfd_create\fP() システムコールは Linux 3.17 で初めて登場した。 GNU C ライブラリでのサポートは検討中である。
  98 .SH 準拠
  99 \fBmemfd_create\fP()  システムコールは Linux 固有である。
 100 .SH 注意
 101 .\" See also http://lwn.net/Articles/593918/
 102 .\" and http://lwn.net/Articles/594919/ and http://lwn.net/Articles/591108/
 103 \fBmemfd_create\fP() システムコールは、 手動で \fItmpfs\fP ファイルシステムをマウントして、
 104 そのファイルシステムにファイルをオープンするという操作の、 簡単な代替手段を提供している。 \fBmemfd_create\fP() の主な目的は、
 105 \fBfcntl\fP(2) が提供する file\-sealing API で使用できる、
 106 ファイルとそれに関連付けられるファイルディスクリプターを作成することである。
 107
 108 \fBmemfd_create\fP() システムコールは、 file sealing なしでも用途がある (これが明示的に
 109 \fBMFD_ALLOW_SEALING\fP フラグが要求されない限り、 file\-sealing が無効になる理由である)。 特に、
 110 ファイルシステムに実際にファイルを残す意図がない場合、 \fItmp\fP にファイルを作成したり \fBopen\fP(2) \fBO_TMPFILE\fP
 111 を使ったりする際の代替手段として使用できる。
 112 .SS "file sealing"
 113 file sealing がない場合、 共有メモリ経由で通信するプロセスは、 互いに信頼するか、
 114 信頼していない相手が共有メモリ領域を問題がある方法で操作する可能性に対処するための対策を講じなければならない。
 115 例えば、 信頼していない相手は、 いつでも共有メモリの内容を変更したり、 共有メモリ領域を縮小したりする可能性がある。 前者の場合は、
 116 ローカルプロセスでは、 データの確認時点と使用時点の競合条件の問題が起こり得る
 117 (通常はこの問題への対処は共有メモリ領域からデータをこぴーしてからデータを確認、使用することである)。 後者の場合は、 ローカルプロセスでは、
 118 共有メモリ領域の存在しなくなった場所にアクセスしようとした際にシグナル \fBSIGBUS\fP が発生する可能性がある (この可能性に対処するにはシグナル
 119 \fBSIGBUS\fP に対してハンドラーを使用する必要がある)。
 120
 121 信頼していない相手への対処により、 共有メモリを利用するコードに余計な複雑性が増すことになる。 メモリー sealing
 122 により余計な複雑性をなくすことができる。 相手が望まない方法で共有メモリを変更できないことを知っていることで、 プロセスは安全に動作できるようになる。
 123
 124 sealing 機構の使い方の例は以下のとおりである。
 125
 126 .IP 1. 3
 127 最初のプロセスは \fBmemfd_create\fP() を使って \fItmpfs\fP ファイルを作成する。 \fBmemfd_create\fP()
 128 はこれ以降のステップで使用するファイルディスクリプターを返す。
 129 .IP 2.
 130 最初のプロセスは \fBftruncate\fP(2) を使って直前のステップで作成したファイルのサイズを変更し、 \fBmmap\fP(2)
 131 を使ってそのファイルをマッピングし、 共有メモリに所望のデータを配置する。
 132 .IP 3.
 133 最初のプロセスは、 このファイルに対する今後の変更を制限するために、 \fBfcntl\fP(2) の \fBF_ADD_SEALS\fP 操作を使って、
 134 そのファイルに seal をいくつか設定する。 (seal \fBF_SEAL_WRITE\fP を設定する場合、
 135 直前のステップで作成した書き込み可能な共有マッピングをまずアンマップする必要が出てくる。)
 136 .IP 4.
 137 二つ目のプロセスは \fItmpfs\fP ファイルのファイルディスクリプターを入手し、 そのファイルをマップする。 以下に示す方法を使用することができる。
 138 .RS
 139 .IP * 3
 140 \fBmemfd_create\fP() を呼び出したプロセスは、 得られたファイルディスクリプターを二つ目のプロセスに UNIX
 141 ドメインソケット経由で渡すことができる (\fBunix\fP(7) と \fBcmsg\fP(3) を参照)。 それから、二つ目のプロセスは \fBmmap\fP(2)
 142 を使ってファイルをマップする。
 143 .IP *
 144 二つ目のプロセスを \fBfork\fP(2) を使って作成する。 そうすると、 自動的にファイルディスクリプターとマッピングが継承される。
 145 (この方法と次の方法では、 二つのプロセス間で自然な信頼関係が存在することになる。 なぜなら、 二つのプロセスは同じユーザー ID。
 146 の元で実行されているからである。 したがって、 file sealing は通常は不要であろう。)
 147 .IP *
 148 二つ目のプロセスは \fI/proc/<pd>/fd/<fd>\fP をオープンする。 \fI<pid>\fP
 149 は最初のプロセス (\fBmemfd_create\fP() を呼び出したプロセス) の PID で、 \fI<fd>\fP は最初のプロセスでの
 150 \fBmemfd_create\fP() の呼び出しで返されたファイルディスクリプター番号である。 それからこのファイルを \fBmmap\fP(2)
 151 を使ってマッピングする。
 152 .RE
 153 .IP 5.
 154 二つ目のプロセスは \fBfcntl\fP(2) の \fBF_GET_SEALS\fP 操作を使って、 そのファイルに適用されている seal
 155 のビットマスクを取得する。 このビットマスクを調べて、 ファイルの変更に関してどのような制限が適用されているかを知ることができる。
 156 (\fBF_SEAL_SEAL\fP seal がそれまでに適用されていない限りは) 必要であれば、 二つ目のプロセスはさらに seal
 157 を設定して追加の制限をかけることができる。
 158 .SH 例
 159 以下では \fBmemfd_create\fP() と file sealing API の使用例を示すサンプルプログラムを 2 つとりあげる。
 160
 161 最初のプログラム \fIt_memfd_create.c\fP は、 \fBmemfd_create\fP() を使って \fItmpfs\fP ファイルを作成し、
 162 そのファイルのサイズを設定し、 メモリにマッピングし、 要求された場合にはそのファイルに seal を設定する。 このプログラムは最大で 3
 163 つのコマンドライン引き数を取り、 最初の 2 つは必須である。 最初の引き数はファイルに関連付けられる名前で、 2
 164 番目の引き数はファイルに設定されるサイズである。 省略可能な 3 番目の引き数は、 このファイルに設定する seal を指定する文字列である。
 165
 166 2 つめのプログラム \fIt_get_seals.c\fP を使うと、 \fBmemfd_create\fP() を使って作成された既存のファイルをオープンし、
 167 そのファイルに適用されている seal の集合を調査できる。
 168
 169 以下のシェルのセッションはこれらのプログラムの使用例を示したものである。 まず \fItmpfs\fP ファイルを作成し、そのファイルに seal
 170 をいくつか設定している。
 171
 172 .in +4n
 173 .nf
 174 $ \fB./t_memfd_create my_memfd_file 4096 sw &\fP
 175 [1] 11775
 176 PID: 11775; fd: 3; /proc/11775/fd/3
 177 .fi
 178 .in
 179
 180 この時点では、 \fIt_memfd_create\fP プログラムはバックグラウンドで動作し続ける。 もう一つのプログラムから、
 181 \fBmemfd_create\fP() がオープンしたディスクリプターに対応する \fI/proc/PID/fd\fP ファイルをオープンすることで、
 182 \fBmemfd_create\fP() で作成されたファイルのファイルディスクリプターを取得できる。
 183 そのパス名を使って、 \fI/proc/PID/fd\fP シンボリックリンクの内容を調査し、 \fIt_get_seals\fP
 184 プログラムを使ってそのファイルに設定されている seal を見ることができる。
 185
 186 .in +4n
 187 .nf
 188 $ \fBreadlink /proc/11775/fd/3\fP
 189 /memfd:my_memfd_file (deleted)
 190 $ \fB./t_get_seals /proc/11775/fd/3\fP
 191 Existing seals: WRITE SHRINK
 192 .fi
 193 .in
 194 .SS "プログラムのソース: t_memfd_create.c"
 195 \&
 196 .nf
 197 #include <sys/memfd.h>
 198 #include <fcntl.h>
 199 #include <stdlib.h>
 200 #include <unistd.h>
 201 #include <string.h>
 202 #include <stdio.h>
 203
 204 #define errExit(msg)    do { perror(msg); exit(EXIT_FAILURE); \e
 205                         } while (0)
 206
 207 int
 208 main(int argc, char *argv[])
 209 {
 210     int fd;
 211     unsigned int seals;
 212     char *addr;
 213     char *name, *seals_arg;
 214     ssize_t len;
 215
 216     if (argc < 3) {
 217         fprintf(stderr, "%s name size [seals]\en", argv[0]);
 218         fprintf(stderr, "\et\(aqseals\(aq can contain any of the "
 219                 "following characters:\en");
 220         fprintf(stderr, "\et\etg \- F_SEAL_GROW\en");
 221         fprintf(stderr, "\et\ets \- F_SEAL_SHRINK\en");
 222         fprintf(stderr, "\et\etw \- F_SEAL_WRITE\en");
 223         fprintf(stderr, "\et\etS \- F_SEAL_SEAL\en");
 224         exit(EXIT_FAILURE);
 225     }
 226
 227     name = argv[1];
 228     len = atoi(argv[2]);
 229     seals_arg = argv[3];
 230
 231     /* Create an anonymous file in tmpfs; allow seals to be
 232        placed on the file */
 233
 234     fd = memfd_create(name, MFD_ALLOW_SEALING);
 235     if (fd == \-1)
 236         errExit("memfd_create");
 237
 238     /* Size the file as specified on the command line */
 239
 240     if (ftruncate(fd, len) == \-1)
 241         errExit("truncate");
 242
 243     printf("PID: %ld; fd: %d; /proc/%ld/fd/%d\en",
 244             (long) getpid(), fd, (long) getpid(), fd);
 245
 246     /* Code to map the file and populate the mapping with data
 247        omitted */
 248
 249     /* If a \(aqseals\(aq command\-line argument was supplied, set some
 250        seals on the file */
 251
 252     if (seals_arg != NULL) {
 253         seals = 0;
 254
 255         if (strchr(seals_arg, \(aqg\(aq) != NULL)
 256             seals |= F_SEAL_GROW;
 257         if (strchr(seals_arg, \(aqs\(aq) != NULL)
 258             seals |= F_SEAL_SHRINK;
 259         if (strchr(seals_arg, \(aqw\(aq) != NULL)
 260             seals |= F_SEAL_WRITE;
 261         if (strchr(seals_arg, \(aqS\(aq) != NULL)
 262             seals |= F_SEAL_SEAL;
 263
 264         if (fcntl(fd, F_ADD_SEALS, seals) == \-1)
 265             errExit("fcntl");
 266     }
 267
 268     /* Keep running, so that the file created by memfd_create()
 269        continues to exist */
 270
 271     pause();
 272
 273     exit(EXIT_SUCCESS);
 274 }
 275 .fi
 276 .SS "プログラムのソース: t_get_seals.c"
 277 \&
 278 .nf
 279 #include <sys/memfd.h>
 280 #include <fcntl.h>
 281 #include <unistd.h>
 282 #include <stdlib.h>
 283 #include <string.h>
 284 #include <stdio.h>
 285
 286 #define errExit(msg)    do { perror(msg); exit(EXIT_FAILURE); \e
 287                         } while (0)
 288
 289 int
 290 main(int argc, char *argv[])
 291 {
 292     int fd;
 293     unsigned int seals;
 294
 295     if (argc != 2) {
 296         fprintf(stderr, "%s /proc/PID/fd/FD\en", argv[0]);
 297         exit(EXIT_FAILURE);
 298     }
 299
 300     fd = open(argv[1], O_RDWR);
 301     if (fd == \-1)
 302         errExit("open");
 303
 304     seals = fcntl(fd, F_GET_SEALS);
 305     if (seals == \-1)
 306         errExit("fcntl");
 307
 308     printf("Existing seals:");
 309     if (seals & F_SEAL_SEAL)
 310         printf(" SEAL");
 311     if (seals & F_SEAL_GROW)
 312         printf(" GROW");
 313     if (seals & F_SEAL_WRITE)
 314         printf(" WRITE");
 315     if (seals & F_SEAL_SHRINK)
 316         printf(" SHRINK");
 317     printf("\en");
 318
 319     /* Code to map the file and access the contents of the
 320        resulting mapping omitted */
 321
 322     exit(EXIT_SUCCESS);
 323 }
 324 .fi
 325 .SH 関連項目
 326 \fBfcntl\fP(2), \fBftruncate\fP(2), \fBmmap\fP(2), \fBshmget\fP(2), \fBshm_open\fP(3)