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