From 193f7fb2729c0782ff2808231f5b5dfb9f146415 Mon Sep 17 00:00:00 2001 From: Michael Kerrisk Date: Tue, 31 Mar 2020 09:10:05 +0200 Subject: [PATCH] openat2.2: Place 'resolve' flags in alphabetical order Signed-off-by: Michael Kerrisk --- man2/openat2.2 | 154 ++++++++++++++++++++++++------------------------- 1 file changed, 77 insertions(+), 77 deletions(-) diff --git a/man2/openat2.2 b/man2/openat2.2 index 9cbf38979..e52587180 100644 --- a/man2/openat2.2 +++ b/man2/openat2.2 @@ -195,83 +195,6 @@ The full list of flags is as follows: .RS .TP -.B RESOLVE_NO_XDEV -Disallow traversal of mount points during path resolution (including all bind -mounts). -.IP -Applications that employ -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. -Setting this flag indiscriminately for all uses of -.BR openat2 () -may result in spurious errors on previously-functional systems. -.\" FIXME I find the "previously-functional systems" in the previous -.\" sentence a little odd (since openat2() ia new sysycall), so I would -.\" like to clarify a little... -.\" Are you referring to the scenario where someone might take an -.\" existing application that uses openat() and replaces the uses -.\" of openat() with openat2()? In which case, is it correct to -.\" understand that you mean that one should not just indiscriminately -.\" add the RESOLVE_NO_XDEV flag to all of the openat2() calls? -.\" If I'm not on the right track, could you point me in the right -.\" direction please. -.TP -.B RESOLVE_NO_SYMLINKS -Disallow resolution of symbolic links during path resolution. -This option implies -.BR RESOLVE_NO_MAGICLINKS . -.IP -If the trailing component (i.e., basename) of -.I pathname -is a symbolic link, and -.I how.flags -contains both -.BR O_PATH -and -.BR O_NOFOLLOW , -then an -.B O_PATH -file descriptor referencing the symbolic link will be returned. -.IP -Applications that employ -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. -Setting this flag indiscriminately for all uses of -.BR openat2 () -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 (i.e., basename) of -.I pathname -is a magic link, and -.I how.flags -contains both -.BR O_PATH -and -.BR O_NOFOLLOW , -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 -.IR /proc/[pid]/exe -and -.IR /proc/[pid]/fd/* ). -Due to the potential danger of unknowingly opening these magic links, -it may be -preferable for users to disable their resolution entirely. -.\" FIXME: what specific details in symlink(7) are being referred -.\" by the following sentence? It's not clear. -(See -.BR symlink (7) -for more details.) -.TP .B RESOLVE_BENEATH Do not permit the path resolution to succeed if any component of the resolution is not a descendant of the directory indicated by @@ -340,6 +263,83 @@ However, this may change in the future. Therefore, to ensure that magic links are not resolved, the caller should explicitly specify .BR RESOLVE_NO_MAGICLINKS . +.TP +.B RESOLVE_NO_MAGICLINKS +Disallow all magic-link resolution during path resolution. +.IP +If the trailing component (i.e., basename) of +.I pathname +is a magic link, and +.I how.flags +contains both +.BR O_PATH +and +.BR O_NOFOLLOW , +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 +.IR /proc/[pid]/exe +and +.IR /proc/[pid]/fd/* ). +Due to the potential danger of unknowingly opening these magic links, +it may be +preferable for users to disable their resolution entirely. +.\" FIXME: what specific details in symlink(7) are being referred +.\" by the following sentence? It's not clear. +(See +.BR symlink (7) +for more details.) +.TP +.B RESOLVE_NO_SYMLINKS +Disallow resolution of symbolic links during path resolution. +This option implies +.BR RESOLVE_NO_MAGICLINKS . +.IP +If the trailing component (i.e., basename) of +.I pathname +is a symbolic link, and +.I how.flags +contains both +.BR O_PATH +and +.BR O_NOFOLLOW , +then an +.B O_PATH +file descriptor referencing the symbolic link will be returned. +.IP +Applications that employ +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. +Setting this flag indiscriminately for all uses of +.BR openat2 () +may result in spurious errors on previously-functional systems. +.TP +.B RESOLVE_NO_XDEV +Disallow traversal of mount points during path resolution (including all bind +mounts). +.IP +Applications that employ +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. +Setting this flag indiscriminately for all uses of +.BR openat2 () +may result in spurious errors on previously-functional systems. +.\" FIXME I find the "previously-functional systems" in the previous +.\" sentence a little odd (since openat2() ia new sysycall), so I would +.\" like to clarify a little... +.\" Are you referring to the scenario where someone might take an +.\" existing application that uses openat() and replaces the uses +.\" of openat() with openat2()? In which case, is it correct to +.\" understand that you mean that one should not just indiscriminately +.\" add the RESOLVE_NO_XDEV flag to all of the openat2() calls? +.\" If I'm not on the right track, could you point me in the right +.\" direction please. .RE .IP If any bits other than those listed above are set in