mirror of https://github.com/mkerrisk/man-pages
openat2.2: srcfix: Disfavor multiargument .BR and .IR usage
For me, source lines such as: .BR perf_setattr "(2), " perf_event_open "(2), and " clone3 (2). is harder to read than: .BR perf_setattr (2), .BR perf_event_open (2), and .BR clone3 (2). Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
This commit is contained in:
parent
d144dc36b8
commit
a424f7c064
|
@ -93,7 +93,9 @@ The
|
|||
argument specifies how
|
||||
.I pathname
|
||||
should be opened, and acts as a superset of the
|
||||
.IR flags " and " mode
|
||||
.IR flags
|
||||
and
|
||||
.IR mode
|
||||
arguments to
|
||||
.BR openat (2).
|
||||
This argument is a pointer to a structure of the following form:
|
||||
|
@ -166,9 +168,13 @@ contains bits other than
|
|||
Similarly, an error is returned if
|
||||
.BR openat2 ()
|
||||
is called with a non-zero
|
||||
.IR how.mode " and " how.flags
|
||||
.IR how.mode
|
||||
and
|
||||
.IR how.flags
|
||||
does not contain
|
||||
.BR O_CREAT " or " O_TMPFILE .
|
||||
.BR O_CREAT
|
||||
or
|
||||
.BR O_TMPFILE .
|
||||
.TP
|
||||
.I resolve
|
||||
This is a bit-mask of flags that modify the way in which
|
||||
|
@ -209,7 +215,9 @@ If the trailing component (i.e., basename) of
|
|||
is a symbolic link, and
|
||||
.I how.flags
|
||||
contains both
|
||||
.BR O_PATH " and " O_NOFOLLOW ","
|
||||
.BR O_PATH
|
||||
and
|
||||
.BR O_NOFOLLOW ,
|
||||
then an
|
||||
.B O_PATH
|
||||
file descriptor referencing the symbolic link will be returned.
|
||||
|
@ -230,7 +238,9 @@ If the trailing component (i.e., basename) of
|
|||
is a magic link, and
|
||||
.I how.flags
|
||||
contains both
|
||||
.BR O_PATH " and " O_NOFOLLOW ","
|
||||
.BR O_PATH
|
||||
and
|
||||
.BR O_NOFOLLOW ,
|
||||
then an
|
||||
.B O_PATH
|
||||
file descriptor referencing the magic link will be returned.
|
||||
|
@ -238,7 +248,9 @@ file descriptor referencing the magic link will be returned.
|
|||
Magic-links are symbolic link-like objects that are most notably found in
|
||||
.BR proc (5)
|
||||
(examples include
|
||||
.IR /proc/[pid]/exe " and " /proc/[pid]/fd/* ).
|
||||
.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.
|
||||
|
@ -329,7 +341,9 @@ for more detail on how extensions are handled.)
|
|||
.B EAGAIN
|
||||
.I how.resolve
|
||||
contains either
|
||||
.BR RESOLVE_IN_ROOT " or " RESOLVE_BENEATH ,
|
||||
.BR RESOLVE_IN_ROOT
|
||||
or
|
||||
.BR RESOLVE_BENEATH ,
|
||||
and the kernel could not ensure that a ".." component didn't escape (due to a
|
||||
race condition or potential attack).
|
||||
The caller may choose to retry the
|
||||
|
@ -345,7 +359,9 @@ An unknown flag or invalid value was specified in
|
|||
is non-zero, but
|
||||
.I how.flags
|
||||
does not contain
|
||||
.BR O_CREAT " or " O_TMPFILE .
|
||||
.BR O_CREAT
|
||||
or
|
||||
.BR O_TMPFILE .
|
||||
.TP
|
||||
.B EINVAL
|
||||
.I size
|
||||
|
@ -367,7 +383,9 @@ and one of the path components was a magic link.
|
|||
.B EXDEV
|
||||
.I how.resolve
|
||||
contains either
|
||||
.BR RESOLVE_IN_ROOT " or " RESOLVE_BENEATH ,
|
||||
.BR RESOLVE_IN_ROOT
|
||||
or
|
||||
.BR RESOLVE_BENEATH ,
|
||||
and an escape from the root during path resolution was detected.
|
||||
.TP
|
||||
.B EXDEV
|
||||
|
@ -403,7 +421,10 @@ acting as an implicit version number.
|
|||
(Because new extension fields will always
|
||||
be appended, the structure 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 " clone3 (2).
|
||||
.BR perf_setattr (2),
|
||||
.BR perf_event_open (2),
|
||||
and
|
||||
.BR clone3 (2).
|
||||
.PP
|
||||
If we let
|
||||
.I usize
|
||||
|
@ -413,13 +434,17 @@ be the size of the structure which the kernel supports, then there are
|
|||
three cases to consider:
|
||||
.IP \(bu 2
|
||||
If
|
||||
.IR ksize " equals " usize ,
|
||||
.IR ksize
|
||||
equals
|
||||
.IR usize ,
|
||||
then there is no version mismatch and
|
||||
.I how
|
||||
can be used verbatim.
|
||||
.IP \(bu
|
||||
If
|
||||
.IR ksize " is larger than " usize ,
|
||||
.IR ksize
|
||||
is larger than
|
||||
.IR usize ,
|
||||
then there are some extension fields that the kernel supports
|
||||
which the user-space application
|
||||
is unaware of.
|
||||
|
@ -430,7 +455,9 @@ as having zero values.
|
|||
This provides backwards-compatibility.
|
||||
.IP \(bu
|
||||
If
|
||||
.IR ksize " is smaller than " usize ,
|
||||
.IR ksize
|
||||
is smaller than
|
||||
.IR usize ,
|
||||
then there are some extension fields which the user-space application
|
||||
is aware of but which the kernel does not support.
|
||||
Because any extension field must have its zero values signify a no-op,
|
||||
|
|
Loading…
Reference in New Issue