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>
There are currently three of these forward references (two in
DESCRIPTION, one in ERRORS). This is a little redundant.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Rather than trying to merge the new syscall documentation into
open.2 (which would probably result in the man-page being
incomprehensible), instead the new syscall gets its own dedicated
page with links between open(2) and openat2(2) to avoid
duplicating information such as the list of O_* flags or common
errors.
In addition to describing all of the key flags, information about
the extensibility design is provided so that users can better
understand why they need to pass sizeof(struct open_how) and how
their programs will work across kernels. After some discussions
with David Laight, I also included explicit instructions to zero
the structure to avoid issues when recompiling with new headers.
Signed-off-by: Aleksa Sarai <cyphar@cyphar.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>