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 "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 (see
  92 .BR fcntl (2)
  93 with
  94 .B F_ADD_SEALS
  95 and
  96 .BR F_GET_SEALS )
  97 on this file.
  98 The initial set of seals is empty.
  99 If this flag is not set, the initial set of seals will be
 100 .BR F_SEAL_SEAL ,
 101 meaning that no other seals can be set on the file.
 102 .\" FIXME Why is the MFD_ALLOW_SEALING behavior not simply the default?
 103 .\"       Is it worth adding some text explaining this?
 104 .PP
 105 Unused bits in
 106 .I flags
 107 must be 0.
 108
 109 As its return value,
 110 .BR memfd_create ()
 111 returns a new file descriptor that can be used to refer to the file.
 112 This file descriptor is opened for both reading and writing
 113 .RB ( O_RDWR )
 114 and
 115 .B O_LARGEFILE
 116 is set for the descriptor.
 117
 118 With respect to
 119 .BR fork (2)
 120 and
 121 .BR execve (2),
 122 the usual semantics apply for the file descriptor created by
 123 .BR memfd_create ().
 124 A copy of the file descriptor is inherited by the child produced by
 125 .BR fork (2)
 126 and refers to the same file.
 127 The file descriptor is preserved across
 128 .BR execve (2),
 129 unless the close-on-exec flag has been set.
 130 .SH RETURN VALUE
 131 On success,
 132 .BR memfd_create ()
 133 returns a new file descriptor.
 134 On error, \-1 is returned and
 135 .I errno
 136 is set to indicate the error.
 137 .SH ERRORS
 138 .TP
 139 .B EFAULT
 140 The address in
 141 .IR name
 142 points to invalid memory.
 143 .TP
 144 .B EINVAL
 145 An unsupported value was specified in one of the arguments:
 146 .I flags
 147 included unknown bits, or
 148 .I name
 149 was too long.
 150 .TP
 151 .B EMFILE
 152 The per-process limit on open file descriptors has been reached.
 153 .TP
 154 .B ENFILE
 155 The system-wide limit on the total number of open files has been reached.
 156 .TP
 157 .B ENOMEM
 158 There was insufficient memory to create a new anonymous file.
 159 .SH VERSIONS
 160 The
 161 .BR memfd_create ()
 162 system call first appeared in Linux 3.17.
 163 .\" FIXME . When glibc support appears, update the following sentence:
 164 Support in the GNU C library is pending.
 165 .SH CONFORMING TO
 166 The
 167 .BR memfd_create ()
 168 system call is Linux-specific.
 169 .\" FIXME I added the NOTES section below. Please review.
 170 .SH NOTES
 171 .\" See also http://lwn.net/Articles/593918/
 172 .\" and http://lwn.net/Articles/594919/ and http://lwn.net/Articles/591108/
 173 The
 174 .BR memfd_create ()
 175 system call provides a simple alternative to manually mounting a
 176 .I tmpfs
 177 filesystem and creating and opening a file in that filesystem.
 178 The primary purpose of
 179 .BR memfd_create ()
 180 is to create files and associated file descriptors that are
 181 used with the file-sealing APIs provided by
 182 .BR fcntl (2).
 183 .SS File sealing
 184 In the absence of file sealing,
 185 processes that communicate via shared memory must either trust each other,
 186 or take measures to deal with the possibility that an untrusted peer
 187 may manipulate the shared memory region in problematics ways.
 188 For example, an untrusted peer might modify the contents of the
 189 shared memory at any time, or shrink the shared memory region.
 190 The former possibility leaves the local process vulnerable to
 191 time-of-check-to-time-of-use race conditions
 192 (typically dealt with by copying data from
 193 the shared memory region before checking and using it).
 194 The latter possibility leaves the local process vulnerable to
 195 .BR SIGBUS
 196 signals when an attempt is made to access a now-nonexistent
 197 location in the shared memory region.
 198 (Dealing with this possibility necessitates the use of a handler for the
 199 .BR SIGBUS
 200 signal.)
 201
 202 Dealing with untrusted peers imposes extra complexity on
 203 code that employs shared memory.
 204 Memory sealing enables that extra complexity to be eliminated,
 205 by allowing a process to operate secure in the knowledge that
 206 its peer can't modify the shared memory in an undesired fashion.
 207
 208 An example of the usage of the sealing mechanism is as follows:
 209
 210 .IP 1. 3
 211 The first process creates a
 212 .I tmpfs
 213 file using
 214 .BR memfd_create ().
 215 The call yields a file descriptor used in subsequent steps.
 216 .IP 2.
 217 The first process
 218 sizes the file created in the previous step using
 219 .BR ftruncate (2),
 220 maps it using
 221 .BR mmap (2),
 222 and populates the shared memory with the desired data.
 223 .IP 3.
 224 The first process uses the
 225 .BR fcntl (2)
 226 .B F_ADD_SEALS
 227 operation to place one or more seals on the file,
 228 in order to restrict further modifications on the file.
 229 (If placing the seal
 230 .BR F_SEAL_WRITE ,
 231 then it will be necessary to first unmap the shared writable mapping
 232 created in the previous step.)
 233 .IP 4.
 234 A second process obtains a file descriptor for the
 235 .I tmpfs
 236 file and maps it.
 237 This could happen in one of two ways:
 238 .RS
 239 .IP * 3
 240 The second process is created via
 241 .BR fork (2)
 242 and thus automatically inherits the file descriptor and mapping.
 243 .IP *
 244 The second process opens the file
 245 .IR /proc/<pd>/fd/<fd> ,
 246 where
 247 .I <pid>
 248 is the PID of the first process (the one that called
 249 .BR memfd_create ()),
 250 and
 251 .I <fd>
 252 is the number of the file descriptor returned by the call to
 253 .BR memfd_create ()
 254 in that process.
 255 The second process then maps the file using
 256 .BR mmap (2).
 257 .RE
 258 .IP 5.
 259 The second process uses the
 260 .BR fcntl (2)
 261 .B F_GET_SEALS
 262 operation to retrieve the set of seals that has been applied to the file.
 263 This set can be inspected in order to determine what kinds of restrictions
 264 have been placed on file modifications.
 265 If desired, the second process can apply further seals
 266 to impose additional restrictions (so long as the
 267 .BR F_SEAL_SEAL
 268 seal has not yet been applied).
 269 .\"
 270 .\" FIXME Do we have any nice example program that could go in the man page?
 271 .SH SEE ALSO
 272 .BR fcntl (2),
 273 .\" FIXME Why the reference to shmget(2) in particular (and not,
 274 .\"       e.g., shm_open(3), mmap(2))?
 275 .BR shmget (2)