man2/openat2.2

   1 .\" Copyright (C) 2019 Aleksa Sarai <cyphar@cyphar.com>
   2 .\"
   3 .\" %%%LICENSE_START(VERBATIM)
   4 .\" Permission is granted to make and distribute verbatim copies of this
   5 .\" manual provided the copyright notice and this permission notice are
   6 .\" preserved on all copies.
   7 .\"
   8 .\" Permission is granted to copy and distribute modified versions of this
   9 .\" manual under the conditions for verbatim copying, provided that the
  10 .\" entire resulting derived work is distributed under the terms of a
  11 .\" permission notice identical to this one.
  12 .\"
  13 .\" Since the Linux kernel and libraries are constantly changing, this
  14 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  15 .\" responsibility for errors or omissions, or for damages resulting from
  16 .\" the use of the information contained herein.  The author(s) may not
  17 .\" have taken the same level of care in the production of this manual,
  18 .\" which is licensed free of charge, as they might when working
  19 .\" professionally.
  20 .\"
  21 .\" Formatted or processed versions of this manual, if unaccompanied by
  22 .\" the source, must acknowledge the copyright and authors of this work.
  23 .\" %%%LICENSE_END
  24 .TH OPENAT2 2 2020-11-01 "Linux" "Linux Programmer's Manual"
  25 .SH NAME
  26 openat2 \- open and possibly create a file (extended)
  27 .SH SYNOPSIS
  28 .nf
  29 .B #include <sys/stat.h>
  30 .B #include <fcntl.h>
  31 .B #include <linux/openat2.h>
  32 .PP
  33 .BI "long openat2(int " dirfd ", const char *" pathname ,
  34 .BI "            struct open_how *" how ", size_t " size );
  35 .fi
  36 .PP
  37 .IR Note :
  38 There is no glibc wrapper for this system call; see NOTES.
  39 .SH DESCRIPTION
  40 The
  41 .BR openat2 ()
  42 system call is an extension of
  43 .BR openat (2)
  44 and provides a superset of its functionality.
  45 .PP
  46 The
  47 .BR openat2 ()
  48 system call opens the file specified by
  49 .IR pathname .
  50 If the specified file does not exist, it may optionally (if
  51 .B O_CREAT
  52 is specified in
  53 .IR how.flags )
  54 be created.
  55 .PP
  56 As with
  57 .BR openat (2),
  58 if
  59 .I pathname
  60 is a relative pathname, then it is interpreted relative to the
  61 directory referred to by the file descriptor
  62 .I dirfd
  63 (or the current working directory of the calling process, if
  64 .I dirfd
  65 is the special value
  66 .BR AT_FDCWD ).
  67 If
  68 .I pathname
  69 is an absolute pathname, then
  70 .I dirfd
  71 is ignored (unless
  72 .I how.resolve
  73 contains
  74 .BR RESOLVE_IN_ROOT ,
  75 in which case
  76 .I pathname
  77 is resolved relative to
  78 .IR dirfd ).
  79 .PP
  80 Rather than taking a single
  81 .I flags
  82 argument, an extensible structure (\fIhow\fP) is passed to allow for
  83 future extensions.
  84 The
  85 .I size
  86 argument must be specified as
  87 .IR "sizeof(struct open_how)" .
  88 .\"
  89 .SS The open_how structure
  90 The
  91 .I how
  92 argument specifies how
  93 .I pathname
  94 should be opened, and acts as a superset of the
  95 .IR flags
  96 and
  97 .IR mode
  98 arguments to
  99 .BR openat (2).
 100 This argument is a pointer to a structure of the following form:
 101 .PP
 102 .in +4n
 103 .EX
 104 struct open_how {
 105     u64 flags;    /* O_* flags */
 106     u64 mode;     /* Mode for O_{CREAT,TMPFILE} */
 107     u64 resolve;  /* RESOLVE_* flags */
 108     /* ... */
 109 };
 110 .EE
 111 .in
 112 .PP
 113 Any future extensions to
 114 .BR openat2 ()
 115 will be implemented as new fields appended to the above structure,
 116 with a zero value in a new field resulting in the kernel behaving
 117 as though that extension field was not present.
 118 Therefore, the caller
 119 .I must
 120 zero-fill this structure on
 121 initialization.
 122 (See the "Extensibility" section of the
 123 .B NOTES
 124 for more detail on why this is necessary.)
 125 .PP
 126 The fields of the
 127 .I open_how
 128 structure are as follows:
 129 .TP
 130 .I flags
 131 This field specifies
 132 the file creation and file status flags to use when opening the file.
 133 All of the
 134 .B O_*
 135 flags defined for
 136 .BR openat (2)
 137 are valid
 138 .BR openat2 ()
 139 flag values.
 140 .IP
 141 Whereas
 142 .BR openat (2)
 143 ignores unknown bits in its
 144 .I flags
 145 argument,
 146 .BR openat2 ()
 147 returns an error if unknown or conflicting flags are specified in
 148 .IR how.flags .
 149 .TP
 150 .I mode
 151 This field specifies the
 152 mode for the new file, with identical semantics to the
 153 .I mode
 154 argument of
 155 .BR openat (2).
 156 .IP
 157 Whereas
 158 .BR openat (2)
 159 ignores bits other than those in the range
 160 .I 07777
 161 in its
 162 .I mode
 163 argument,
 164 .BR openat2 ()
 165 returns an error if
 166 .I how.mode
 167 contains bits other than
 168 .IR 07777 .
 169 Similarly, an error is returned if
 170 .BR openat2 ()
 171 is called with a nonzero
 172 .IR how.mode
 173 and
 174 .IR how.flags
 175 does not contain
 176 .BR O_CREAT
 177 or
 178 .BR O_TMPFILE .
 179 .TP
 180 .I resolve
 181 This is a bit-mask of flags that modify the way in which
 182 .B all
 183 components of
 184 .I pathname
 185 will be resolved.
 186 (See
 187 .BR path_resolution (7)
 188 for background information.)
 189 .IP
 190 The primary use case for these flags is to allow trusted programs to restrict
 191 how untrusted paths (or paths inside untrusted directories) are resolved.
 192 The full list of
 193 .I resolve
 194 flags is as follows:
 195 .RS
 196 .TP
 197 .B RESOLVE_BENEATH
 198 .\" commit adb21d2b526f7f196b2f3fdca97d80ba05dd14a0
 199 Do not permit the path resolution to succeed if any component of the resolution
 200 is not a descendant of the directory indicated by
 201 .IR dirfd .
 202 This causes absolute symbolic links (and absolute values of
 203 .IR pathname )
 204 to be rejected.
 205 .IP
 206 Currently, this flag also disables magic-link resolution (see below).
 207 However, this may change in the future.
 208 Therefore, to ensure that magic links are not resolved,
 209 the caller should explicitly specify
 210 .BR RESOLVE_NO_MAGICLINKS .
 211 .TP
 212 .B RESOLVE_IN_ROOT
 213 .\" commit 8db52c7e7ee1bd861b6096fcafc0fe7d0f24a994
 214 Treat the directory referred to by
 215 .I dirfd
 216 as the root directory while resolving
 217 .IR pathname .
 218 Absolute symbolic links are interpreted relative to
 219 .IR dirfd .
 220 If a prefix component of
 221 .I pathname
 222 equates to
 223 .IR dirfd ,
 224 then an immediately following
 225 .IR ..\&
 226 component likewise equates to
 227 .IR dirfd
 228 (just as
 229 .I /..\&
 230 is traditionally equivalent to
 231 .IR / ).
 232 If
 233 .I pathname
 234 is an absolute path, it is also interpreted relative to
 235 .IR dirfd .
 236 .IP
 237 The effect of this flag is as though the calling process had used
 238 .BR chroot (2)
 239 to (temporarily) modify its root directory (to the directory
 240 referred to by
 241 .IR dirfd ).
 242 However, unlike
 243 .BR chroot (2)
 244 (which changes the filesystem root permanently for a process),
 245 .B RESOLVE_IN_ROOT
 246 allows a program to efficiently restrict path resolution on a per-open basis.
 247 .IP
 248 Currently, this flag also disables magic-link resolution.
 249 However, this may change in the future.
 250 Therefore, to ensure that magic links are not resolved,
 251 the caller should explicitly specify
 252 .BR RESOLVE_NO_MAGICLINKS .
 253 .TP
 254 .B RESOLVE_NO_MAGICLINKS
 255 .\" commit 278121417a72d87fb29dd8c48801f80821e8f75a
 256 Disallow all magic-link resolution during path resolution.
 257 .IP
 258 Magic links are symbolic link-like objects that are most notably found in
 259 .BR proc (5);
 260 examples include
 261 .IR /proc/[pid]/exe
 262 and
 263 .IR /proc/[pid]/fd/* .
 264 (See
 265 .BR symlink (7)
 266 for more details.)
 267 .IP
 268 Unknowingly opening magic links can be risky for some applications.
 269 Examples of such risks include the following:
 270 .RS
 271 .IP \(bu 2
 272 If the process opening a pathname is a controlling process that
 273 currently has no controlling terminal (see
 274 .BR credentials (7)),
 275 then opening a magic link inside
 276 .IR /proc/[pid]/fd
 277 that happens to refer to a terminal
 278 would cause the process to acquire a controlling terminal.
 279 .IP \(bu
 280 .\" From https://lwn.net/Articles/796868/:
 281 .\"     The presence of this flag will prevent a path lookup operation
 282 .\"     from traversing through one of these magic links, thus blocking
 283 .\"     (for example) attempts to escape from a container via a /proc
 284 .\"     entry for an open file descriptor.
 285 In a containerized environment,
 286 a magic link inside
 287 .I /proc
 288 may refer to an object outside the container,
 289 and thus may provide a means to escape from the container.
 290 .RE
 291 .IP
 292 Because of such risks,
 293 an application may prefer to disable magic link resolution using the
 294 .BR RESOLVE_NO_MAGICLINKS
 295 flag.
 296 .IP
 297 If the trailing component (i.e., basename) of
 298 .I pathname
 299 is a magic link,
 300 .I how.resolve
 301 contains
 302 .BR RESOLVE_NO_MAGICLINKS ,
 303 and
 304 .I how.flags
 305 contains both
 306 .BR O_PATH
 307 and
 308 .BR O_NOFOLLOW ,
 309 then an
 310 .B O_PATH
 311 file descriptor referencing the magic link will be returned.
 312 .TP
 313 .B RESOLVE_NO_SYMLINKS
 314 .\" commit 278121417a72d87fb29dd8c48801f80821e8f75a
 315 Disallow resolution of symbolic links during path resolution.
 316 This option implies
 317 .BR RESOLVE_NO_MAGICLINKS .
 318 .IP
 319 If the trailing component (i.e., basename) of
 320 .I pathname
 321 is a symbolic link,
 322 .I how.resolve
 323 contains
 324 .BR RESOLVE_NO_SYMLINKS ,
 325 and
 326 .I how.flags
 327 contains both
 328 .BR O_PATH
 329 and
 330 .BR O_NOFOLLOW ,
 331 then an
 332 .B O_PATH
 333 file descriptor referencing the symbolic link will be returned.
 334 .IP
 335 Note that the effect of the
 336 .BR RESOLVE_NO_SYMLINKS
 337 flag,
 338 which affects the treatment of symbolic links in all of the components of
 339 .IR pathname ,
 340 differs from the effect of the
 341 .BR O_NOFOLLOW
 342 file creation flag (in
 343 .IR how.flags ),
 344 which affects the handling of symbolic links only in the final component of
 345 .IR pathname .
 346 .IP
 347 Applications that employ the
 348 .BR RESOLVE_NO_SYMLINKS
 349 flag are encouraged to make its use configurable
 350 (unless it is used for a specific security purpose),
 351 as symbolic links are very widely used by end-users.
 352 Setting this flag indiscriminately\(emi.e.,
 353 for purposes not specifically related to security\(emfor all uses of
 354 .BR openat2 ()
 355 may result in spurious errors on previously functional systems.
 356 This may occur if, for example,
 357 a system pathname that is used by an application is modified
 358 (e.g., in a new distribution release)
 359 so that a pathname component (now) contains a symbolic link.
 360 .TP
 361 .B RESOLVE_NO_XDEV
 362 .\" commit 72ba29297e1439efaa54d9125b866ae9d15df339
 363 Disallow traversal of mount points during path resolution (including all bind
 364 mounts).
 365 Consequently,
 366 .I pathname
 367 must either be on the same mount as the directory referred to by
 368 .IR dirfd ,
 369 or on the same mount as the current working directory if
 370 .I dirfd
 371 is specified as
 372 .BR AT_FDCWD .
 373 .IP
 374 Applications that employ the
 375 .B RESOLVE_NO_XDEV
 376 flag are encouraged to make its use configurable (unless it is
 377 used for a specific security purpose),
 378 as bind mounts are widely used by end-users.
 379 Setting this flag indiscriminately\(emi.e.,
 380 for purposes not specifically related to security\(emfor all uses of
 381 .BR openat2 ()
 382 may result in spurious errors on previously functional systems.
 383 This may occur if, for example,
 384 a system pathname that is used by an application is modified
 385 (e.g., in a new distribution release)
 386 so that a pathname component (now) contains a bind mount.
 387 .TP
 388 .B RESOLVE_CACHED
 389 Make the open operation fail unless all path components are already present
 390 in the kernel's lookup cache.
 391 If any kind of revalidation or I/O is needed to satisfy the lookup,
 392 .BR openat2 ()
 393 fails with the error
 394 .B EAGAIN .
 395 This is useful in providing a fast-path open that can be performed without
 396 resorting to thread offload, or other mechanisms that an application might
 397 use to offload slower operations.
 398 .RE
 399 .IP
 400 If any bits other than those listed above are set in
 401 .IR how.resolve ,
 402 an error is returned.
 403 .SH RETURN VALUE
 404 On success, a new file descriptor is returned.
 405 On error, \-1 is returned, and
 406 .I errno
 407 is set to indicate the error.
 408 .SH ERRORS
 409 The set of errors returned by
 410 .BR openat2 ()
 411 includes all of the errors returned by
 412 .BR openat (2),
 413 as well as the following additional errors:
 414 .TP
 415 .B E2BIG
 416 An extension that this kernel does not support was specified in
 417 .IR how .
 418 (See the "Extensibility" section of
 419 .B NOTES
 420 for more detail on how extensions are handled.)
 421 .TP
 422 .B EAGAIN
 423 .I how.resolve
 424 contains either
 425 .BR RESOLVE_IN_ROOT
 426 or
 427 .BR RESOLVE_BENEATH ,
 428 and the kernel could not ensure that a ".." component didn't escape (due to a
 429 race condition or potential attack).
 430 The caller may choose to retry the
 431 .BR openat2 ()
 432 call.
 433 .TP
 434 .B EAGAIN
 435 .BR RESOLVE_CACHED
 436 was set, and the open operation cannot be performed using only cached
 437 information. The caller should retry without
 438 .B RESOLVE_CACHED
 439 set in
 440 .I how.resolve .
 441 .TP
 442 .B EINVAL
 443 An unknown flag or invalid value was specified in
 444 .IR how .
 445 .TP
 446 .B EINVAL
 447 .I mode
 448 is nonzero, but
 449 .I how.flags
 450 does not contain
 451 .BR O_CREAT
 452 or
 453 .BR O_TMPFILE .
 454 .TP
 455 .B EINVAL
 456 .I size
 457 was smaller than any known version of
 458 .IR "struct open_how" .
 459 .TP
 460 .B ELOOP
 461 .I how.resolve
 462 contains
 463 .BR RESOLVE_NO_SYMLINKS ,
 464 and one of the path components was a symbolic link (or magic link).
 465 .TP
 466 .B ELOOP
 467 .I how.resolve
 468 contains
 469 .BR RESOLVE_NO_MAGICLINKS ,
 470 and one of the path components was a magic link.
 471 .TP
 472 .B EXDEV
 473 .I how.resolve
 474 contains either
 475 .BR RESOLVE_IN_ROOT
 476 or
 477 .BR RESOLVE_BENEATH ,
 478 and an escape from the root during path resolution was detected.
 479 .TP
 480 .B EXDEV
 481 .I how.resolve
 482 contains
 483 .BR RESOLVE_NO_XDEV ,
 484 and a path component crosses a mount point.
 485 .SH VERSIONS
 486 .BR openat2 ()
 487 first appeared in Linux 5.6.
 488 .\" commit fddb5d430ad9fa91b49b1d34d0202ffe2fa0e179
 489 .SH CONFORMING TO
 490 This system call is Linux-specific.
 491 .PP
 492 The semantics of
 493 .B RESOLVE_BENEATH
 494 were modeled after FreeBSD's
 495 .BR O_BENEATH .
 496 .SH NOTES
 497 Glibc does not provide a wrapper for this system call; call it using
 498 .BR syscall (2).
 499 .\"
 500 .SS Extensibility
 501 In order to allow for future extensibility,
 502 .BR openat2 ()
 503 requires the user-space application to specify the size of the
 504 .I open_how
 505 structure that it is passing.
 506 By providing this information, it is possible for
 507 .BR openat2 ()
 508 to provide both forwards- and backwards-compatibility, with
 509 .I size
 510 acting as an implicit version number.
 511 (Because new extension fields will always
 512 be appended, the structure size will always increase.)
 513 This extensibility design is very similar to other system calls such as
 514 .BR sched_setattr (2),
 515 .BR perf_event_open (2),
 516 and
 517 .BR clone3 (2).
 518 .PP
 519 If we let
 520 .I usize
 521 be the size of the structure as specified by the user-space application, and
 522 .I ksize
 523 be the size of the structure which the kernel supports, then there are
 524 three cases to consider:
 525 .IP \(bu 2
 526 If
 527 .IR ksize
 528 equals
 529 .IR usize ,
 530 then there is no version mismatch and
 531 .I how
 532 can be used verbatim.
 533 .IP \(bu
 534 If
 535 .IR ksize
 536 is larger than
 537 .IR usize ,
 538 then there are some extension fields that the kernel supports
 539 which the user-space application
 540 is unaware of.
 541 Because a zero value in any added extension field signifies a no-op,
 542 the kernel
 543 treats all of the extension fields not provided by the user-space application
 544 as having zero values.
 545 This provides backwards-compatibility.
 546 .IP \(bu
 547 If
 548 .IR ksize
 549 is smaller than
 550 .IR usize ,
 551 then there are some extension fields which the user-space application
 552 is aware of but which the kernel does not support.
 553 Because any extension field must have its zero values signify a no-op,
 554 the kernel can
 555 safely ignore the unsupported extension fields if they are all-zero.
 556 If any unsupported extension fields are nonzero, then \-1 is returned and
 557 .I errno
 558 is set to
 559 .BR E2BIG .
 560 This provides forwards-compatibility.
 561 .PP
 562 Because the definition of
 563 .I struct open_how
 564 may change in the future (with new fields being added when system headers are
 565 updated), user-space applications should zero-fill
 566 .I struct open_how
 567 to ensure that recompiling the program with new headers will not result in
 568 spurious errors at runtime.
 569 The simplest way is to use a designated
 570 initializer:
 571 .PP
 572 .in +4n
 573 .EX
 574 struct open_how how = { .flags = O_RDWR,
 575                         .resolve = RESOLVE_IN_ROOT };
 576 .EE
 577 .in
 578 .PP
 579 or explicitly using
 580 .BR memset (3)
 581 or similar:
 582 .PP
 583 .in +4n
 584 .EX
 585 struct open_how how;
 586 memset(&how, 0, sizeof(how));
 587 how.flags = O_RDWR;
 588 how.resolve = RESOLVE_IN_ROOT;
 589 .EE
 590 .in
 591 .PP
 592 A user-space application that wishes to determine which extensions
 593 the running kernel supports can do so by conducting a binary search on
 594 .IR size
 595 with a structure which has every byte nonzero (to find the largest value
 596 which doesn't produce an error of
 597 .BR E2BIG ).
 598 .SH SEE ALSO
 599 .BR openat (2),
 600 .BR path_resolution (7),
 601 .BR symlink (7)