- 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>
Many times, this page use the terminology "mount point", where
"mount" would be better. A "mount point" is the location at which
a mount is attached. A "mount" is an association between a
filesystem and a mount point.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
projects / thirdparty / man-pages.git / log
