man2/memfd_create.2

   1 .\" Copyright (C) 2014 David Herrmann <dh.herrmann@gmail.com>
   2 .\" and Copyright (C) 2014 Michael Kerrisk <mtk.manpages@gmail.com>
   3 .\"
   4 .\" %%%LICENSE_START(GPLv2+_SW_3_PARA)
   5 .\"
   6 .\" FIXME What is _SW_3_PARA?
   7 .\"
   8 .\" This program is free software; you can redistribute it and/or modify
   9 .\" it under the terms of the GNU General Public License as published by
  10 .\" the Free Software Foundation; either version 2 of the License, or
  11 .\" (at your option) any later version.
  12 .\"
  13 .\" This program is distributed in the hope that it will be useful,
  14 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  15 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  16 .\" GNU General Public License for more details.
  17 .\"
  18 .\" You should have received a copy of the GNU General Public
  19 .\" License along with this manual; if not, see
  20 .\" <http://www.gnu.org/licenses/>.
  21 .\" %%%LICENSE_END
  22 .\"
  23 .TH MEMFD_CREATE 2 2014-07-08 Linux "Linux Programmer's Manual"
  24 .SH NAME
  25 memfd_create \- create an anonymous file
  26 .SH SYNOPSIS
  27 .B #include <sys/memfd.h>
  28 .sp
  29 .BI "int memfd_create(const char *" name ", unsigned int " flags ");"
  30 .SH DESCRIPTION
  31 .BR memfd_create ()
  32 creates an anonymous file and returns a file descriptor that refers to it.
  33 The file behaves like a regular file, and so can be modified,
  34 truncated, memory-mapped, and so on.
  35 However, unlike a regular file,
  36 it lives in RAM and has a volatile backing storage.
  37 .\" FIXME In the following sentence I changed "released" to
  38 .\"       "destroyed". Okay?
  39 Once all references to the file are dropped, it is automatically released.
  40 Anonymous memory is used for all backing pages of the file.
  41 .\" FIXME In the following sentence I changed "they" to
  42 .\"       "files created by memfd_create()". Okay?
  43 Therefore, files created by
  44 .BR memfd_create ()
  45 are subject to the same restrictions as other anonymous
  46 .\" FIXME Can you give some examples of some of the restrictions please.
  47 memory allocations such as those allocated using
  48 .BR mmap (2)
  49 with the
  50 .BR MAP_ANONYMOUS
  51 flag.
  52
  53 The initial size of the file is set to 0.
  54 .\" FIXME I added the following sentence. Please review.
  55 Following the call, the file size should be set using
  56 .BR ftruncate (2).
  57
  58 The name supplied in
  59 .I name
  60 is used as an internal filename and will be displayed
  61 .\" FIXME What does "internal" in the previous line mean?
  62 as the target of the corresponding symbolic link in the directory
  63 .\" FIXME I added the previous line. Is it correct?
  64 .IR /proc/self/fd/ .
  65 .\" FIXME In the next line, I added "as displayed in that
  66 The displayed name is always prefixed with
  67 .IR memfd:
  68 and serves only for debugging purposes.
  69 Names do not affect the behavior of the memfd,
  70 .\" FIXME The term "memfd" appears here without having previously been
  71 .\"       defined. Would the correct definition of "the memfd" be
  72 .\"       "the file descriptor created by memfd_create"?
  73 and as such multiple files can have the same name without any side effects.
  74
  75 The following values may be bitwise ORed in
  76 .IR flags
  77 to change the behaviour of
  78 .BR memfd_create ():
  79 .TP
  80 .BR MFD_CLOEXEC
  81 Set the close-on-exec
  82 .RB ( FD_CLOEXEC )
  83 flag on the new file descriptor.
  84 See the description of the
  85 .B O_CLOEXEC
  86 flag in
  87 .BR open (2)
  88 for reasons why this may be useful.
  89 .TP
  90 .BR MFD_ALLOW_SEALING
  91 Allow sealing operations on this file.
  92 See
  93 .BR fcntl (2)
  94 with
  95 .B F_ADD_SEALS
  96 and
  97 .BR F_GET_SEALS ,
  98 and also NOTES, below.
  99 The initial set of seals is empty.
 100 If this flag is not set, the initial set of seals will be
 101 .BR F_SEAL_SEAL ,
 102 meaning that no other seals can be set on the file.
 103 .\" FIXME Why is the MFD_ALLOW_SEALING behavior not simply the default?
 104 .\"       Is it worth adding some text explaining this?
 105 .PP
 106 Unused bits in
 107 .I flags
 108 must be 0.
 109
 110 As its return value,
 111 .BR memfd_create ()
 112 returns a new file descriptor that can be used to refer to the file.
 113 This file descriptor is opened for both reading and writing
 114 .RB ( O_RDWR )
 115 and
 116 .B O_LARGEFILE
 117 is set for the descriptor.
 118
 119 With respect to
 120 .BR fork (2)
 121 and
 122 .BR execve (2),
 123 the usual semantics apply for the file descriptor created by
 124 .BR memfd_create ().
 125 A copy of the file descriptor is inherited by the child produced by
 126 .BR fork (2)
 127 and refers to the same file.
 128 The file descriptor is preserved across
 129 .BR execve (2),
 130 unless the close-on-exec flag has been set.
 131 .SH RETURN VALUE
 132 On success,
 133 .BR memfd_create ()
 134 returns a new file descriptor.
 135 On error, \-1 is returned and
 136 .I errno
 137 is set to indicate the error.
 138 .SH ERRORS
 139 .TP
 140 .B EFAULT
 141 The address in
 142 .IR name
 143 points to invalid memory.
 144 .TP
 145 .B EINVAL
 146 An unsupported value was specified in one of the arguments:
 147 .I flags
 148 included unknown bits, or
 149 .I name
 150 was too long.
 151 .TP
 152 .B EMFILE
 153 The per-process limit on open file descriptors has been reached.
 154 .TP
 155 .B ENFILE
 156 The system-wide limit on the total number of open files has been reached.
 157 .TP
 158 .B ENOMEM
 159 There was insufficient memory to create a new anonymous file.
 160 .SH VERSIONS
 161 The
 162 .BR memfd_create ()
 163 system call first appeared in Linux 3.17.
 164 .\" FIXME . When glibc support appears, update the following sentence:
 165 Support in the GNU C library is pending.
 166 .SH CONFORMING TO
 167 The
 168 .BR memfd_create ()
 169 system call is Linux-specific.
 170 .\" FIXME I added the NOTES section below. Please review.
 171 .SH NOTES
 172 .\" See also http://lwn.net/Articles/593918/
 173 .\" and http://lwn.net/Articles/594919/ and http://lwn.net/Articles/591108/
 174 The
 175 .BR memfd_create ()
 176 system call provides a simple alternative to manually mounting a
 177 .I tmpfs
 178 filesystem and creating and opening a file in that filesystem.
 179 The primary purpose of
 180 .BR memfd_create ()
 181 is to create files and associated file descriptors that are
 182 used with the file-sealing APIs provided by
 183 .BR fcntl (2).
 184 .SS File sealing
 185 In the absence of file sealing,
 186 processes that communicate via shared memory must either trust each other,
 187 or take measures to deal with the possibility that an untrusted peer
 188 may manipulate the shared memory region in problematics ways.
 189 For example, an untrusted peer might modify the contents of the
 190 shared memory at any time, or shrink the shared memory region.
 191 The former possibility leaves the local process vulnerable to
 192 time-of-check-to-time-of-use race conditions
 193 (typically dealt with by copying data from
 194 the shared memory region before checking and using it).
 195 The latter possibility leaves the local process vulnerable to
 196 .BR SIGBUS
 197 signals when an attempt is made to access a now-nonexistent
 198 location in the shared memory region.
 199 (Dealing with this possibility necessitates the use of a handler for the
 200 .BR SIGBUS
 201 signal.)
 202
 203 Dealing with untrusted peers imposes extra complexity on
 204 code that employs shared memory.
 205 Memory sealing enables that extra complexity to be eliminated,
 206 by allowing a process to operate secure in the knowledge that
 207 its peer can't modify the shared memory in an undesired fashion.
 208
 209 An example of the usage of the sealing mechanism is as follows:
 210
 211 .IP 1. 3
 212 The first process creates a
 213 .I tmpfs
 214 file using
 215 .BR memfd_create ().
 216 The call yields a file descriptor used in subsequent steps.
 217 .IP 2.
 218 The first process
 219 sizes the file created in the previous step using
 220 .BR ftruncate (2),
 221 maps it using
 222 .BR mmap (2),
 223 and populates the shared memory with the desired data.
 224 .IP 3.
 225 The first process uses the
 226 .BR fcntl (2)
 227 .B F_ADD_SEALS
 228 operation to place one or more seals on the file,
 229 in order to restrict further modifications on the file.
 230 (If placing the seal
 231 .BR F_SEAL_WRITE ,
 232 then it will be necessary to first unmap the shared writable mapping
 233 created in the previous step.)
 234 .IP 4.
 235 A second process obtains a file descriptor for the
 236 .I tmpfs
 237 file and maps it.
 238 This could happen in one of two ways:
 239 .RS
 240 .IP * 3
 241 The second process is created via
 242 .BR fork (2)
 243 and thus automatically inherits the file descriptor and mapping.
 244 .IP *
 245 The second process opens the file
 246 .IR /proc/<pd>/fd/<fd> ,
 247 where
 248 .I <pid>
 249 is the PID of the first process (the one that called
 250 .BR memfd_create ()),
 251 and
 252 .I <fd>
 253 is the number of the file descriptor returned by the call to
 254 .BR memfd_create ()
 255 in that process.
 256 The second process then maps the file using
 257 .BR mmap (2).
 258 .RE
 259 .IP 5.
 260 The second process uses the
 261 .BR fcntl (2)
 262 .B F_GET_SEALS
 263 operation to retrieve the bit mask of seals
 264 that has been applied to the file.
 265 This bit mask can be inspected in order to determine
 266 what kinds of restrictions have been placed on file modifications.
 267 If desired, the second process can apply further seals
 268 to impose additional restrictions (so long as the
 269 .BR F_SEAL_SEAL
 270 seal has not yet been applied).
 271 .\"
 272 .\" FIXME Do we have any nice example program that could go in the man page?
 273 .SH SEE ALSO
 274 .BR fcntl (2),
 275 .BR ftruncate (2),
 276 .BR mmap (2),
 277 .\" FIXME Why the reference to shmget(2) in particular (and not,
 278 .\"       e.g., shm_open(3))?
 279 .BR shmget (2)