Document the limited fanotify functionality that will be available for
unprivileged users from kernel v5.13.
Signed-off-by: Matthew Bobrowski <mbobrowski@mbobrowski.org> Signed-off-by: Amir Goldstein <amir73il@gmail.com> Reviewed-by: Jan Kara <jack@suse.cz> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Using grep first to reduce the files on which pcregrep is run
optimizes considerably the performance of these functions.
If a file doesn't contain the name of a function,
which can easily be checked with grep,
it won't possibly contain the function prototype or definition,
which is much slower to search,
since it implies multiline pcregrep search.
Most documents go through several versions
(always more than you expected)
before they are finally finished.
Accordingly,
you should do whatever possible
to make the job of changing them easy.
First,
when you do the purely mechanical operations of typing,
type so subsequent editing will be easy.
Start each sentence on a new line.
Make lines short,
and break lines at natural places,
such as after commas and semicolons,
rather than randomly.
Since most people change documents
by rewriting phrases and
adding, deleting and rearranging sentences,
these precautions simplify any editing you have to do later.
]
He mentioned phrases,
and they are indeed commonly the operands of patches
(see this patch's changes (the second part) as an example),
so they make for a much better breaking point than random
within a clause that is too long to fit a line.
The downside is that they are more difficult to automatically spot
than clause breaks (which tend to have associated punctuation).
But we are humans writing patches,
not machines,
and therefore we should be able to decide and detect them better.
* Advise usage of \~ escape instead of \SPACE; the former, a groff
extension from circa 1990, has been supported by Heirloom Doctools
troff since 2005 and by mandoc since 2019. The advantage is that
\~ is an _adjustable_ non-breaking space, so it will typeset
non-jarringly both in .EX/.EE examples when filling is off, and in
normal running text (which is filled).
See linux-man@ list discussion at
<https://lore.kernel.org/linux-man/\ 20210729115508.pt6btsqd7g5tuhg6@localhost.localdomain/> and follow-ups.
Signed-off-by: G. Branden Robinson <g.branden.robinson@gmail.com> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
- wsfix
- Boldface literals (see groff_man(7)).
- Replace '\ ' by \~, per Branden's advise.
- Use phrasal semantic newlines.
- Put '...' in a C comment, to avoid interfering with groff.
It has the side effect that the code example is pure C now.
- Remove incorrect trailing '.IP'.
Cc: Wei Wang <weiwan@google.com> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Jeremy Kerr [Thu, 11 Nov 2021 02:03:07 +0000 (10:03 +0800)]
man7: unify socket examples
The udp, tcp and x25 man pages' synopses list the socket() example as
all bold, but the socket varname should be italicised. This change
unifies these with the example in socket.7
Signed-off-by: Jeremy Kerr <jk@codeconstruct.com.au> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
landlock_add_rule.2, landlock_create_ruleset.2, landlock_restrict_self.2, landlock.7: Minor tweaks to Mickaël's patches
- exit(EXIT_FAILURE) instead of return 1, for consistency with the
rest of the manual pages.
- Use old declarations: variables defined at the top, separate
from code. Initialization other than zero doesn't belong there.
- Don't break URIs in weird ways (a trailing slash on a new line
would be weird).
- Break URIs after the slash; not before. Per Branden's advise.
- Use uint32_t instead of __u32 in prototypes.
- tfix
- A few semantic newline improvements.
- ffix
Mickaël Salaün [Wed, 18 Aug 2021 15:59:28 +0000 (17:59 +0200)]
landlock.7: Add a new page to introduce Landlock
From the user point of view, Landlock is a set of system calls enabling
to build and enforce a set of access-control rules. A ruleset can be
created with landlock_create_ruleset(2), populated with
landlock_add_rule(2) and enforced with landlock_restrict_self(2). This
man page gives an overview of the whole mechanism. Details of these
system calls are documented in their respective man pages.
This is an adaptation of
https://www.kernel.org/doc/html/v5.13/userspace-api/landlock.html
pow.3: RETURN VALUE: Clarify that -0.0 is a valid underflow result
The standards are a bit unclear (or I couldn't find it), but
Joseph confirmed that glibc documents this behavior, and
M. Welinder tested that Solaris also behaves in the same way.
Reported-by: M. Welinder <mwelinder@gmail.com>
Bug: 214815 <https://bugzilla.kernel.org/show_bug.cgi?id=214815> Cc: Joseph Myers <joseph@codesourcery.com> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
pow.3: RETURN VALUE: Reorder special cases as in the standard
Use the following order:
- Success
- Over/Underflow
- Special cases specified by the standard (in the same order)
- Other special cases not specified by the standard.
This way it's easier to compare this document against the standard
to check for any mistakes or differences.
I also added a comment at the beginning of each case, to more
clearly delimit special cases, with a syntax that is easy to read
(a mix of C, mathematical language, ...). We may want to use
those as tagged paragraphs.
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com> Cc: M. Welinder <mwelinder@gmail.com>
When creating UNIX domain sockets, the kernel used to return -ENOMEM on
error where it should return -ENFILE. The behaviour has been wrong since
2.2.4 and fixed in the recent commit f4bd73b5a950 ("af_unix: Return errno
instead of NULL in unix_create1().").
madvise.2: Document MADV_POPULATE_READ and MADV_POPULATE_WRITE
MADV_POPULATE_READ and MADV_POPULATE_WRITE have been merged into
upstream Linux via commit 4ca9b3859dac ("mm/madvise: introduce
MADV_POPULATE_(READ|WRITE) to prefault page tables"), part of v5.14-rc1.
Further, commit eb2faa513c24 ("mm/madvise: report SIGBUS as -EFAULT for
MADV_POPULATE_(READ|WRITE)"), part of v5.14-rc6, made sure that SIGBUS is
converted to -EFAULT instead of -EINVAL.
Let's document the behavior and error conditions of these new madvise()
options.
Acked-by: Pankaj Gupta <pankaj.gupta@ionos.com> Cc: Michael Kerrisk <mtk.manpages@gmail.com> Cc: Andrew Morton <akpm@linux-foundation.org> Cc: Michal Hocko <mhocko@suse.com> Cc: Oscar Salvador <osalvador@suse.de> Cc: Jann Horn <jannh@google.com> Cc: Mike Rapoport <rppt@kernel.org> Cc: Linux API <linux-api@vger.kernel.org> Cc: linux-mm@kvack.org Signed-off-by: David Hildenbrand <david@redhat.com> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
наб [Sat, 2 Oct 2021 12:18:44 +0000 (14:18 +0200)]
rpmatch.3: clarify first-character-only FUD
It's plain not true as-written ‒ locales can and do provide longer matches
(Aramaic has a "አዎን" alternative, for example) ‒ but it's important to
note that (a) this may be an issue and (b) nonetheless this is the right
way to process this
packet.7: Describe SOCK_PACKET netif name length issues and workarounds.
Describe the issues with SOCK_PACKET possibly truncating network interface
names in results, solutions and possible workarounds.
While the issue is known for a long time it appears to have never been
properly documented is has started to bite software antiques including
the AX.25 userland badly since the introduction of Predictable Network
Interface Names. So let's document it.
Chunks of glibc headers have no place in documenting an interface,
and (__builtin_)alloca() is an intrinsic, not code; those days are,
thankfully, long gone
Also, clarify standards behaviour (and remove the (outdated!)
list of cc(1) switches) regarding when alloca() is allowed to not be
ODR-usable
alloca.3: clarify reasoning for no error return in BUGS
A stack lasts from some high point until it runs off the back
of the pages allocated, making detecting errors impossible,
save for actually trying to access said unallocated page
alloca() is supported by PWB/UNIX[1] (V6) and UNIX/32V[2] (V7),
for the PDP-11 and VAX, respectively; the former trickles into
UNIX System III[3], and the latter into 3BSD[4] and later[5]
str[n]dupa() are available on every modern compiler platform,
incl. Clang, ICC, &c.
By shortening the third paragraph, it now reads
strdupa() and strndupa() are similar,
but use alloca(3) to allocate the buffer.
pointing squarely to alloca(3), which is scary enough,
so drop the extraneous warning, too ‒ this clearly points to
"see alloca(3) for the limitations of that allocator".
Plus, it's not like malloc(3) doesn't have its problems, too,
but I don't see those being touted in the first paragraph;
reducing these to the bare minimum,
strdup() copies into malloc(3) and you can free it with free(3),
strndup() likewise, but up to n, and
str[n]dupa() use alloca(3) instead ‒ be wary of what alloca(3) does!
doesn't really make sense ‒ it's obvious that, ex definitione,
alloca(3) suffers from alloca(3) problems and input limits,
just like malloc(3) from the malloc(3) suite's.
Greg Banks [Wed, 4 Aug 2021 13:17:39 +0000 (06:17 -0700)]
nscd.conf.5: describe reloading, clarifications
- Added a subsection of NOTES describing nscd's reloading behavior
and providing advice on how to configure it.
- Clarifications for the threads, reload-count, positive-time-to-live,
check-files, and shared attributes.
Derived by reading the nscd, libresolv and glibc source and some
painful experience.
Pali Rohár [Tue, 31 Aug 2021 20:28:09 +0000 (22:28 +0200)]
ioctl_tty.2: Fix information about header include file
Header file termios.h contains incompatible definitions for linux ioctl
calls. Correct definitions are exported by header file linux/termios.h but
this file conflicts with sys/ioctl.h header file (required for ioctl()
call). Therefore include direct asm header file asm/termbits.h which
contains compatible definitions and structures for ioctl calls.
clone.2: ERRORS: Add EACCESS with CLONE_INTO_CGROUP + clone3
[Andrew]:
I noticed that clone3 can send the EACCES errno after I wrote a
program that used clone3 with the CLONE_INTO_CGROUP flag.
To me, it's important to know what kind of failure occurred if the
clone3() fails, so I was glad that a unique errno is set for
this case, but it wasn't documented on the clone man page.
[Christian]:
In essence, any error that could occur during regular fs-based migration
at write-time can also occur during CLONE_INTO_CGROUP. The clone3()
manpage just has the inverse of that above statement:
"Note that all of the usual restrictions (described in cgroups(7)) on
placing a process into a version 2 cgroup apply."
Reported-by: Andrew Wock <ajwock@gmail.com> Acked-by: Christian Brauner <christian.brauner@ubuntu.com> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Pali Rohár [Tue, 10 Aug 2021 19:49:28 +0000 (21:49 +0200)]
ioctl_tty.2: Add example how to get or set baudrate on the serial port
Setting custom baudrate for which is not defined Bnnn constant is possible
via BOTHER flag and then filling speed in c_ospeed and c_ispeed fields.
These two fields are either in struct termios or struct termios2. Former
belongs to TCGETS/TCSETS ioctls, latter to TCGETS2/TCSETS2 ioctls.
BOTHER flag with these two fields and new struct termios2 is not supported
by older versions of include header files.
Some architectures (e.g. amd64) provide both struct termios and struct
termios2, but c_ospeed and c_ispeed are only in struct termios2.
Some other architectures (e.g. alpha) provide both struct termios and struct
termios2 and both have c_ospeed and c_ispeed fields.
And some other architectures (e.g. powerpc) provide only struct termios
(no struct termios2) and it has c_ospeed and c_ispeed fields.
So basically to support all architectures it is needed to use
struct termios2 when TCGETS2/TCSETS2 is supported. Otherwise it is needed
to use struct termios with TCGETS/TCSETS (case for e.g. powerpc).
Michael Kerrisk [Wed, 1 Sep 2021 22:07:23 +0000 (00:07 +0200)]
prctl.2: Rewrite the description of PR_SET_SECCOMP to defer to seccomp(2)
There is a lot of unnecessary duplication of content of the seccomp
material in prctl(2) and seccomp(2). Trevor Woerner also noted that
there is an error in prctl(2), where it says that the filters
"are run in order until the first non-allow result is seen", which
contradicts the correct statement in seccomp(2) that *all* filters
are executed.
So, rewrite the seccomp material in prctl(2) to strip out most of
the content duplicated in seccomp(2), and replace the removed
text with statements deferring to to seccomp(2).
Reported-by: Trevor Woerner <twoerner@gmail.com> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Paul Eggert [Tue, 10 Aug 2021 19:37:07 +0000 (12:37 -0700)]
malloc.3: Modernize for glibc 2.34
glibc has tightened up its rules for replacing the memory
allocator. I went through the malloc man page and looked for how
it documented malloc() and related functions, and fixed
discrepancies with glibc malloc() documentation and/or
implementation. I also reorganized the portability discussion so
that portability issues can be seen more clearly.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Unary operators are mentioned in C11::6.5.3, and casts are in
C11::6.5.4 (they are mentioned in order of precedence).
And from note 85 (in section 6.5) in that same C11 standard, major
subsections 6.5.X are sorted by precedence.
As an example (from Jakub), `sizeof(int)+1` is interpreted as
`(sizeof(int))+1`, and not `sizeof((int)+1)`.
I used C11 and not C18 (the latest) because at least in the draft
copy of C18 that I have, there are a few important typos in that
section, while the draft copy of C11 that I have is free of those
typos. And C11 and C18 are almost identical, with no major
changes to the language.
Reported-by: David Sletten <david.paul.sletten@gmail.com> Cc: Jakub Wilk <jwilk@jwilk.net> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
Michael Kerrisk [Mon, 30 Aug 2021 21:42:16 +0000 (23:42 +0200)]
exit_group.2: Remove a confusing reference to _exit(2) in DESCRIPTION
As noted by Jakub:
BTW, the exit_group.2 man page could use an update (possibly
by merging it into exit.2): it says that the "system
call is is equivalent to _exit(2) except that it terminates
not only the calling thread, but all threads in the calling
process's thread group", which isn't helpful these days.
Reported-by: Jakub Wilk <jwilk@jwilk.net> Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
projects / thirdparty / man-pages.git / log
