наб [Fri, 31 Mar 2023 22:04:52 +0000 (00:04 +0200)]
proc.5: NAME: Add "system information, and sysctl"
procfs hosts a whole host of information about the system, as well as
sysctls; proc(5) hosts a description of a lot of sysctls, and at present
there's no way to find that out.
user_namespaces.7: Add note about PR_SET_DUMPABLE on nested userns
In order to create a nested user namespace, we need to re-set the
PR_SET_DUMPABLE attribute after switching the effective UID/GID. Clarify
this in the section about nested user namespaces.
Having this note would have saved me some time debugging.
Younes Manton [Tue, 17 Jan 2023 18:03:36 +0000 (10:03 -0800)]
proc.5: Fix caps needed to read map_files contents
imachug@yandex.ru testing CRIU noticed that the documentation for proc's
map_files directory with respect to CAP_CHECKPOINT_RESTORE and
namespaces appears to be wrong. The text reads:
> since Linux 5.9, the reading process must have
> either CAP_SYS_ADMIN or CAP_CHECKPOINT_RESTORE in the user
> namespace where it resides.
The reporter noted that the user actually needs the capabilities in the
initial user namespace, not in the namespace the process resides in. As
far as I can tell this appears to be the case.
Günther Noack [Fri, 24 Mar 2023 17:24:17 +0000 (18:24 +0100)]
landlock.7: Document Landlock ABI v2 (file reparenting; Linux 5.19)
* Add the description for LANDLOCK_ACCESS_FS_REFER,
in line with recent update to the uapi headers:
https://lore.kernel.org/linux-security-module/20230202204623.10345-1-gnoack3000@gmail.com/T/
* VERSIONS: Add a table of Landlock versions and their changes.
Briefly talk about how to probe ABI levels and warn users about the
special semantics of the LANDLOCK_ACCESS_FS_REFER right.
* Add LANDLOCK_ACCESS_FS_REFER to the code example.
Code review threads for the "refer" feature:
* https://git.kernel.org/torvalds/c/cb44e4f061e16be65b8a16505e121490c66d30d0
* https://lore.kernel.org/all/20230221165205.4231-1-gnoack3000@gmail.com/ (documentation update)
- Add a new HISTORY section that covers the history of an API, both
regarding implementations and regarding old standards. This was
previously covered in VERSIONS, and in some cases in STANDARDS.
- Repurpose VERSIONS to cover differing implementations in _current_
systems.
- STANDARDS is reduced to only cover current versions of standards.
That basically means only C11 (C99 has been superseeded by C11; C17
is just a bugfix of C11, so not really a new version), and
POSIX.1-2008 (*-2001 was superseeded by *-2008; *-2017 was just a
bugfix for *-2008). The section also mentions for example 'Linux',
'GNU' or 'BSD' when a non-standard API is Linux- or GNU-only or if
it's (de-facto) standard in the BSDs.
- In some cases content that should go into one of these sections was
in NOTES. Move it from there to where it corresponds.
- In the SYNOPSIS, I added [[deprecated]] in some functions that I
found are deprecated by the relevant standards.
man2/, man3/, man-pages.7: Move VERSIONS next to STANDARDS
VERSIONS and STANDARDS are closely related (and often the distinction is
not so clear). Now that we're going to add another section, HISTORY,
that is related to both, it makes sense to have the three together.
As a curiosity, the list in man-pages(7) that detailed what each section
should contain had them by accident(?) in the order that we're moving
to, instead of the order that was used elsewhere.
INADDR_ANY has nothing to do with the IP_MULTICAST_ALL option.
It does not matter if the interface is bound to all interfaces
or a particular interface for the functionality of IP_MULTICAST_ALL.
Multicast datagrams are addressed to a multicast IP address and will enter
the network stack via a particular interface. The application can choose
from which interface it will receive multicast data by binding the socket
to an IP address. It can then use the IP_MULTICAST_ALL option to
restrict the multicast groups that the IP stack will deliver via the
socket.
Signed-off-by: Christoph Lameter <cl@linux.com> Signed-off-by: Alejandro Colomar <alx@kernel.org>
This removal caused inconveniences to some programmers. We've agreed to
keep the information about C89, since there's an easy way to keep it
correct by checking against a plain-text copy of the standard itself:
We will also do a split of the information in STANDARDS, since now it's
a mix of what a proper STANDARDS section would be plus a HISTORY section
commonly-found in other manual pages. C89 will go into HISTORY.
Link: <https://lore.kernel.org/linux-man/b73a9636-1a17-36f3-3718-d9ca3b9293ed@gmail.com/T/>
Link: <https://port70.net/~nsz/c/c89/c89-draft.txt> Reported-by: Oskari Pirhonen <xxc3ncoredxx@gmail.com> Reported-by: Matt Jolly <Matt.Jolly@footclan.ninja> Cc: Brian Inglis <Brian.Inglis@Shaw.ca> Signed-off-by: Alejandro Colomar <alx@kernel.org>
*.mk: Remove unnecessary '.' after directory names (but keep the '/')
I used it for some reason I don't remember, probably because I did
something wrong, and didn't know how to do it right. I've tried now
without it, and it's working, so let's just remove it.
While we don't want trailing slashes in directory variables, we want
them in targets, so we can distinguish directory targets.
eqn(1) could theoretically write _only_ newlines to standard error.
That's unlikely, but I'm still worried that someone (even me) might copy
this trick around, and use it in situations where that might actually
happen. Let's be more precise, and fail when there's literally anything
on standard error.
Reported-by: Ralph Corderoy <ralph@inputplus.co.uk> Signed-off-by: Alejandro Colomar <alx@kernel.org>
Without .DELETE_ON_ERROR, if a command fails, but has written to a file
(e.g., with '>'), the file will still exist, and successive make(1)
invocations will think it previously succeeded.
Makefile, lint-man.mk: lint-man-groff-col, lint-man-groff-grep: Split targets from lint-man-groff
Allow running col(1) and grep(1) separately, which allows more granular
testing, and also inspecting the output of col(1), which can be useful
for debugging the pages.
Makefile, lint-man.mk: lint-man-groff-grotty: Split target from lint-man-groff
Allow running grotty(1) separately, which allows more granular testing,
and also inspecting the output of grotty(1), which can be useful for
debugging the pages.
Makefile, lint-man.mk: lint-man-groff-troff: Split target from lint-man-groff
Allow running troff(1) separately, which allows more granular testing,
and also inspecting the output of troff(1), which can be useful for
debugging the pages.
Makefile, lint-man.mk: lint-man-groff-eqn: Split target from lint-man-groff
Allow running eqn(1) separately, which allows more granular testing, and
also inspecting the output of eqn(1), which can be useful for debugging
the pages.
INSTALL, cmd.mk, install-man.mk: Support installing compressed pages
Distributions usually install compressed (.gz) pages to reduce space.
Let's support this in our build system, as a command-line variable "Z",
which is empty by default, but can be set to a file extension to append
to the page names (and the appropriate compression program will be
used). For now, the only compression supported is ".gz".
Example:
$ make install Z=.gz
This can be combined with LINK_PAGES, to produce compressed pages and
use symbolic links for the link pages:
cmd.mk, install-man.mk: Allow installing link pages as symlinks
We keep them as .so "includes" in our source code, but if some
distribution wants to have them as symlinks in their filesystem, make it
easy for them to install as such, by specifying 'LINK_PAGES=symlink'.
Rodrigo Campos [Wed, 8 Mar 2023 15:22:18 +0000 (16:22 +0100)]
CONTRIBUTING: Fix typo, there is one active maintainer
On commit "CONTRIBUTING, README, lsm: Remove mtk as maintainer"
(06e72cb1) we changed to mail only one maintainer, but the doc still
says "both maintainers".
When submitting a patch, I was confused by that fact and thought Michael
address was missing. But after checking, it seems we just need to send
it to Alejandro, so clarify the text to match that.
Paul Eggert [Wed, 8 Mar 2023 05:11:38 +0000 (21:11 -0800)]
tzfile.5, tzselect.8: sync from tzdb upstream
This makes tzfile.5 and tzselect.8 a copy of the tzdb develoment
version (commit 12b48faf10c265ee3ea1aad8cdb5c8239eea65a0), except that
man-pages boilerplate surrounds the copyright notice, and the .TH line
uses man-pages format.
Kernel source has example code in tools/testing/selftests/net/udpgro*
Per https://www.kernel.org/doc/man-pages/patches.html,
"Describe how you obtained the information in your patch":
I reviewed the relevant UDP_GRO patches.
Signed-off-by: Willem de Bruijn <willemb@google.com> Reviewed-by: Simon Horman <simon.horman@corigine.com> Cc: <pabeni@redhat.com> Cc: <netdev@vger.kernel.org>
[ alx: srcfix ] Signed-off-by: Alejandro Colomar <alx@kernel.org>
Kernel source has example code in tools/testing/selftests/net/udpgso*
Per https://www.kernel.org/doc/man-pages/patches.html,
"Describe how you obtained the information in your patch":
I am the author of the above commit and follow-ons.
Signed-off-by: Willem de Bruijn <willemb@google.com> Reviewed-by: Simon Horman <simon.horman@corigine.com> Cc: <pabeni@redhat.com> Cc: <netdev@vger.kernel.org>
[ alx: srcfix + use interval notation ] Signed-off-by: Alejandro Colomar <alx@kernel.org>
recv.2: Mention SOCK_SEQPACKET in MSG_TRUNC flag description
unix_seqpacket_recvmsg() calls unix_dgram_recvmsg() which handles
MSG_TRUNC. This has been the case since the handling was added in 9f6f9af7694ede6314bed281eec74d588ba9474f; see net/unix/af_unix.c:
install-man.mk, src.mk: Respect user-specified man dirs
If a user specifies man3dir=/.../man3c, respect it and install there.
Currently, we were transforming link pages to use that dir name, but the
install location itself was still being calculated, which generated
inconsistently installed pages.
install-man.mk: Fix link pages when installing in different mandirs
If downstream wants to put pages in different places (e.g., Debian uses
man2/ and man3/, rather than man2type/ and man3const/, man3head/, and
man3type/), make it easy for them. Link pages need to be fixed
according to the dirname where the pages are actually being installed.
ptrace.2: Add details about usage of PTRACE_GET_SYSCALL_INFO
Document the role of PTRACE_O_TRACESYSGOOD option in connection with
PTRACE_GET_SYSCALL_INFO.
Came upon this after writing a test program using
PTRACE_GET_SYSCALL_INFO. After failing to find what's wrong I posted a
StackOverflow question which you can find right here:
<https://stackoverflow.com/questions/72410182/ptrace-get-syscall-info-always-returns-info-op-as-ptrace-syscall-info-none>
Nate Eldredge found out what happens by looking into the kernel's source
code, here is a link to the relevant part
<https://github.com/torvalds/linux/blob/8291eaafed36f575f23951f3ce18407f480e9ecf/kernel/ptrace.c#L1018>
In the code it can be seen that in case of system call entry or exit
stops, the union is filled if and only if the signal matches
`SIGTRAP | 0x80`, a signal which is only sent if the
PTRACE_O_TRACESYSGOOD option is set. You can read about that in the
PTRACE_O_TRACESYSGOOD section of ptrace(2)'s manual.
malloc.3: EXAMPLES: Add example program with mallocarray() and macros
mallocarray() is safer than malloc(3), since it checks for overflow; it
should be preferred almost always (with the exception of non-arrays
maybe).
The macros like MALLOCARRAY() --and MALLOC()-- that perform automatic
casting and sizeof() are also safer than calling the functions directly:
- The type of the allocated object (not the pointer) is specified as an
argument, which improves readability:
- It is directly obvious what is the type of the object just by
reading the macro call.
- It allows grepping for all allocations of a given type.
This is admittedly similar to using sizeof() to get the size of the
object, but we'll see why this is better.
- In the case of reallocation macros, an extra check is performed to
make sure that the previous pointer was compatible with the allocated
type, which can avoid some mistakes.
- The cast is performed automatically, with a pointer type derived from
the type of the object. This is the best point of this macro, since
it does an automatic cast, where there's no chance of typos.
Usually, programmers have to decide whether to cast or not the result
of malloc(3). Casts usually hide warnings, so are to be avoided.
However, these functions already return a void *, so a cast doesn't
really add much danger. Moreover, a cast can even add warnings in
this exceptional case, if the type of the cast is different than the
type of the assigned pointer. Performing a manual cast is still not
perfect, since there are chances that a mistake will be done, and
even ignoring accidents, they clutter code, hurting readability.
And now we have a cast that is synced with sizeof.
- Whenever the type of the object changes, since we perform an explicit
cast to the old type, there will be a warning due to type mismatch in
the assignment, so we'll be able to see all lines that are affected
by such a change. This is especially important, since changing the
type of a variable and missing to update an allocation call far away
from the declaration is easy, and the consequences can be quite bad
Apart from those benefits, there are other minor style benefits:
- Consistency in getting the size of the object from sizeof(type),
instead of a mix of sizeof(type) sometimes and sizeof(*p) other
times.
- More readable code: no casts, and no sizeof(), so also shorter lines
that we don't need to cut.
- Consistency in using array allocation calls for allocations of arrays
of objects, even when the object size is 1.
Casting sockaddr structures is just a symptom that these APIs were
seriously misdesigned. In GNU C, there's already a better way to handle
this (see [[gnu::transparent_union]]). ISO C should be fixed. Let's
not promote this kind of code.
projects / thirdparty / man-pages.git / log
