diff --git a/man2/openat2.2 b/man2/openat2.2 index c7b1a4c4f..195b7c8ca 100644 --- a/man2/openat2.2 +++ b/man2/openat2.2 @@ -119,10 +119,8 @@ the for more detail on why this is necessary.) .PP The meaning of each field is as follows: -.RS - +.TP .I flags -.RS The file creation and status flags to use for this operation. All of the .B O_* @@ -131,22 +129,20 @@ flags defined for are valid .BR openat2 () flag values. - +.IP Unlike .BR openat (2), it is an error to provide .BR openat2 () unknown or conflicting flags in .IR flags . -.RE - -.IR mode -.RS +.TP +.I mode File mode for the new file, with identical semantics to the .I mode argument to .BR openat (2). - +.IP Unlike .BR openat (2), it is an error to provide @@ -161,10 +157,8 @@ a non-zero .IR mode " if " flags does not contain .BR O_CREAT " or " O_TMPFILE . -.RE - +.TP .I resolve -.RS Change how .B all components of @@ -177,11 +171,12 @@ how untrusted paths (or paths inside untrusted directories) are resolved. The full list of .I resolve flags is given below. +.RS .TP .B RESOLVE_NO_XDEV Disallow traversal of mount points during path resolution (including all bind mounts). - +.IP Users of this flag are encouraged to make its use configurable (unless it is used for a specific security purpose), as bind mounts are very widely used by end-users. @@ -193,7 +188,7 @@ may result in spurious errors on previously-functional systems. Disallow resolution of symbolic links during path resolution. This option implies .BR RESOLVE_NO_MAGICLINKS . - +.IP If the trailing component is a symbolic link, and .I flags contains both @@ -201,7 +196,7 @@ contains both then an .B O_PATH file descriptor referencing the symbolic link will be returned. - +.IP Users of this flag are encouraged to make its use configurable (unless it is used for a specific security purpose), as symbolic links are very widely used by end-users. @@ -211,7 +206,7 @@ may result in spurious errors on previously-functional systems. .TP .B RESOLVE_NO_MAGICLINKS Disallow all magic link resolution during path resolution. - +.IP If the trailing component is a magic link, and .I flags contains both @@ -219,7 +214,7 @@ contains both then an .B O_PATH file descriptor referencing the magic link will be returned. - +.IP Magic-links are symbolic link-like objects that are most notably found in .BR proc (5) (examples include @@ -237,7 +232,7 @@ is not a descendant of the directory indicated by This results in absolute symbolic links (and absolute values of .IR pathname ) to be rejected. - +.IP Currently, this flag also disables magic link resolution. However, this may change in the future. The caller should explicitly specify @@ -260,7 +255,7 @@ If .I pathname is an absolute path, it is also treated relative to .IR dirfd . - +.IP However, unlike .BR chroot (2) (which changes the filesystem root permanently for a process), @@ -272,19 +267,18 @@ It also has several hardening features (such detecting escape attempts during resolution) which .BR chroot (2) does not. - +.IP Currently, this flag also disables magic link resolution. However, this may change in the future. The caller should explicitly specify .B RESOLVE_NO_MAGICLINKS to ensure that magic links are not resolved. +.RE .PP It is an error to provide .BR openat2 () unknown flags in .IR resolve . -.RE -.RE .SH RETURN VALUE On success, a new file descriptor is returned. On error, -1 is returned, and @@ -359,7 +353,7 @@ and one of the path components was a magic link. first appeared in Linux 5.6. .SH CONFORMING TO This system call is Linux-specific. - +.PP The semantics of .B RESOLVE_BENEATH were modeled after FreeBSD's @@ -384,7 +378,7 @@ acting as an implicit version number (because new extension fields will always be appended, the size will always increase.) This extensibility design is very similar to other system calls such as .BR perf_setattr "(2), " perf_event_open "(2), and " clone (3). - +.PP If we let .I usize be the size of the structure according to userspace and