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.
* Stop manipulating adjustment and hyphenation around a table.
* These could be safely done within the text block, but even that is not
necessary, since what is in the next block is a single word, so no
adjustment will take place, and to prevent hyphenation of a single
word, \% is cheap and straightforward. So do that.
Signed-off-by: G. Branden Robinson <g.branden.robinson@gmail.com> Signed-off-by: Alejandro Colomar <alx@kernel.org>
Forcibly re-enabling adjustment to both margins after the synopsis does
not respect user configuration of adjustment. There _is_ a portable way
to save the adjustment mode, via the .j register and a copy of it, but
doing so requires even more usage of low-level requests that are
discouraged in man page writing.
The latter is incorrect for use with groff(1) since '.hy' does not
restore the previous hyphenation mode but sets it to 1, which is not
appropriate for the English-language hyphenation patterns groff uses.
(Also, AT&T man(7) used a hyphenation mode of 14.)
Neither of these requests is respectful of user configuration of
adjustment or hyphenation enablement. Features in the forthcoming
groff 1.23 will make these easier for users to manipulate to their
preference.
(mandoc(1) does not support configurable adjustment or hyphenation, so
all of these requests are no-ops for it.)
Signed-off-by: G. Branden Robinson <g.branden.robinson@gmail.com> Signed-off-by: Alejandro Colomar <alx@kernel.org>
Remove unportable hack to put a dot at the beginning of an input line.
Use the idiomatic means of doing this instead: the roff dummy character
escape sequence.
Signed-off-by: G. Branden Robinson <g.branden.robinson@gmail.com> Signed-off-by: Alejandro Colomar <alx@kernel.org>
Elliott Hughes [Mon, 30 Jan 2023 21:46:09 +0000 (21:46 +0000)]
vdso.7: Fix risc-v symbol names.
The kernel git history says the names have always been "__vdso_" rather
than "__kernel_", so I assume this was a copy & paste mistake from a
different architecture.
Luckily, the path to the kernel source that lets you confirm/deny this
_is_ correct :-)
projects / thirdparty / man-pages.git / log
