man2/openat2.2

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