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