Use 'length' for the lenght of a string.
Use 'n' for the number of elements.
Use 'size' for the number of bytes. (And in wide-character string
functions, 'size' also refers to the number of wide characters.)
The change is quite large, and I might have made some mistakes.
But overall, this should improve consistency in use of these terms.
Ken Pizzini [Fri, 15 Nov 2024 22:11:04 +0000 (14:11 -0800)]
printf.3: wfix
Improve description of %a format.
The description of the %a/%A specifiers in the printf(3) man page
could stand some improvement. In particular, it is not clear from the
current document what base is used for the "p±d" part of the format.
It can be inferred from the nature of %a that the base should be a power
of two. And it can be further inferred from the nature of hexadecimal
floating-point literals in C (as specified by C99 and later) that the
base must exactly be the number two, but it would be helpful for the
printf(3) man page to state this explicitly. My first expectation when
reading the man page was that the exponent would be taken in base 16;
after experimentation my second thought was that it would be base
FLT_RADIX (which is 2 on IEEE 754 floating-point systems, but 16 on
S/390). Only by going back to the standard [1] could I determine that
the exponent in p-notation must always be taken from a base of 2.
Link: [1] POSIX.1-2024 <https://pubs.opengroup.org/onlinepubs/9799919799/functions/printf.html> Cc: Jonathan Wakely <jwakely@redhat.com> Signed-off-by: Ken Pizzini <ken@gnu.org>
Message-ID: <b932f13642502e063ef139d57b8f3c496023bf4a.1731707666.git.ken@gnu.org> Signed-off-by: Alejandro Colomar <alx@kernel.org>
Ken Pizzini [Fri, 15 Nov 2024 08:23:05 +0000 (00:23 -0800)]
printf.3: wfix
Improve terminology in %a description
The term "decimal point" does not technically apply when using bases
other than 10; the more generic term is "radix point". Update the
description of the a/A conversion specifier (i.e., for hexadecimal
floating point output) in printf(3) to use this terminology.
I do note that POSIX.1-2024 [1] does use the term "decimal-point
character" here, but I still maintain that using "radix point" is a
better term for that object in the %a description. (Confusingly, POSIX
does refer to "radix character" in the descriptions of %f and %e, where
reference to "decimal" instead of "radix" would actually make sense.)
Amir Goldstein [Tue, 5 Nov 2024 14:49:39 +0000 (15:49 +0100)]
fanotify_mark.2, fanotify.7: Update documentation of fanotify w.r.t fsid
Clarify the conditions for getting the -EXDEV and -ENODEV errors.
Signed-off-by: Amir Goldstein <amir73il@gmail.com> Reviewed-by: Jan Kara <jack@suse.cz>
Message-ID: <20241105144939.181820-1-amir73il@gmail.com> Signed-off-by: Alejandro Colomar <alx@kernel.org>
scripts/bash_aliases: man_gitstaged(): Trim the dirname(1) only for files within man/
I changed the behavior at some point to trim the dirname(1) for every
file. However, that was mainly due to the inconvenience of not having a
man/ directory. Also, I haven't been consistent with that behavior, and
have been manually adding back the dirname(1), so let's bring back the
old behavior --which is BTW still what the comment says it does--.
===
In src/bin/mansect line 23:
-e '(?s)^\.SH ('"$s"')$(?:(?!^\.(lf 1|TH|SH) ).)*';
^-- SC2250 (style): Prefer putting braces around variable references even when not strictly required.
===
This triggers false positives with trivial PCRE2 regexes.
===
In src/bin/mansect line 23:
-e '(?s)^\.SH ('"$s"')$(?:(?!^\.(lf 1|TH|SH) ).)*';
^----------------------------^ SC2016 (info): Expressions don't expand in single quotes, use double quotes for that.
===
We don't want to support arbitrary manual-page file names.
===
In src/bin/mansect line 17:
find -H "$@" -not -type d \
^-----------------------^ SC2038 (warning): Use -print0/-0 or -exec + to allow for non-alphanumeric filenames.
===
src/bin/mansect, mansect.1: Add program and its manual page
Preprocess with preconv(1). This doesn't process the pages in a
significant way, and has the benefit that it writes the name of the
pages in the output.
Vincent Lefevre [Tue, 24 Sep 2024 11:54:46 +0000 (13:54 +0200)]
signal.7: Better description for SIGFPE
SIGFPE has comment "Floating-point exception", which corresponds to
the FPE acronym. But this is misleading as this signal may also be
generated by an integer division by 0.
Change it to "Erroneous arithmetic operation" from POSIX.
Note: the GNU C Library manual says "fatal arithmetic error".
Levi Zim [Fri, 27 Sep 2024 06:52:29 +0000 (14:52 +0800)]
dup.2: ERRORS: Add ENOMEM
dup2(2) could return ENOMEM under extreme condition. For example, when
sysctl fs.nr_open=2147483584, and RLIMIT_NOFILE is also 2147483584.
The following program fails with ENOMEM:
int
main(void)
{
if (dup2(0, 2000000000) == -1)
err(1, "dup2");
return 0;
}
This ENOMEM comes from an allocation error here:
<https://elixir.bootlin.com/linux/v6.1/source/mm/util.c#L596>
bind.2: ERRORS: Document possible errors from protocol
When looking through the errors of socket(2) I noticed that it specifies
the selected underlying protocol may extend the potential errors
returned. For example, using AF_PACKET and SOCK_RAW can return EPERM if
the user does not have CAP_NET_RAW or uid 0 (this is all fully
documented).
However, AF_PACKET and SOCK_RAW extend the potential errors returned
from bind(2) as well. For example, calling bind(2) with an invalid
sll_ifindex set on the sock_addr passed in will return ENODEV.
While this possibility is documented in the raw(7) manual page, the
bind(2) manual page does not mention that its potential set of errors
can be extended by the underlying protocol. This patch simply
duplicates the relevant language from the socket(2) manual page to the
bind(2) manual page.
It is possible further extensions for send(2), recv(2), setsockopt(2),
etc. are also undocumented, but I have not yet verified this.
Migrate man page cross references in "SEE ALSO" section from using font
selection escape sequences to font alternation macros to set man page
cross references.
This is an oddball case where `\-` appears in the man page title and,
for no obvious reason, a nonbreaking space escape sequence was applied
between list items. (I can _guess_ why: someone was trying to defeat
line adjustment, and didn't notice that they were trying to do so right
before a paragraph break, so adjustment wouldn't have happened anyway.)
Migrate man page cross references in table rows from using font
selection escape sequences to font alternation macros to set man page
cross references.
These are a handful of cases that made a sed(1)-scripted migration
ordering-dependent with its substitution ('s') commands.
Migrate man page cross references in unfilled examples from using font
selection escape sequences to font alternation macros to set man page
cross references.
Convert from unfilled text using `nf` and `fi` requests to `IP` macro
calls and tbl(1) tables.
This change increases the item indentation slightly, as I elected not to
specify one in the `IP` calls. The content still fits easily in an
80-column terminal.
The reason for this change is to make the man page cross references
susceptible to scripted rewriting (and ultimately to make them
hyperlinkable). See, e.g.,
<https://lore.kernel.org/linux-man/20240831182027.b6pduwkthk5b3tcf@illithid/>.
Use *roff requests to shut off adjustment and hyphenation for the
rightmost column of the table, which uses text blocks. (In man pages,
use of such requests _outside_ of tbl(1) text blocks remains discouraged
by groff(1) and mandoc(1) developers.)
Put a paragraph break above the table to ensure separation from the
preceding paragraph with the man(7) macros from groff >= 1.23 and
forthcoming mandoc(1) release.
Explicitly set the width of certain table columns so that they don't
change or cause "can't break line" warnings from troff(1) when the rows
are converted to use text blocks.
Migrate table entries from using font selection escape sequences to font
alternation macros to set man page cross references.
This change was automatically driven by the following sed(1) script.
$ cat fix-man-page-refs-in-tbl-tables-2.sed
# Rewrite man page cross references on tbl(1) rows that
# precede text blocks to themselves use text blocks,
# and convert them to use man(7) macros
# instead of troff(1) font selection escape sequences
# (which cannot be done outside a text block).
/^\.\\"/b
/^\\fB[^\\]*\\fP([0-9][a-z]*).*T{/s/\\fB\([^\\]*\)\\fP\(([0-9][a-z]*)\)\(.*\)/T{\
.BR \1 \2\
T}\3/
DJ Delorie [Fri, 30 Aug 2024 01:10:32 +0000 (21:10 -0400)]
ctime.3: CAVEATS: Add note about tm_isdst handling in mktime(3)
Handling of "invalid" values for tm_isdst is not clearly specified
in any standard, and implementations vary as to how they react when you
(for example) pass tm_isdst=1 at a time when DST is not in effect.
Add a note about this, and a suggestion for a workaround.
I go into further detail about this in the link below.
Link: <https://www.redhat.com/en/blog/brief-history-mktime> Cc: Paul Eggert <eggert@cs.ucla.edu> Cc: Carlos O'Donell <carlos@redhat.com> Signed-off-by: DJ Delorie <dj@redhat.com>
Message-ID: <xncylqiznb.fsf@greed.delorie.com> Signed-off-by: Alejandro Colomar <alx@kernel.org>
share/mk/: build-pdf-book: Rename book to "GNU/Linux Programmer's Manual"
The manual pages in this project had historically used the 5th argument
to TH, with the string "Linux Programmer's Manual". This was showed as
the center-top title of the pages. This was incidentally consistent
with the UNIX Programmer's Manual.
A few years ago, I removed the 5th argument to TH to use the default
string, to follow conventions. At the same time, I put the project name
and version in the 4th argument to TH: "Linux man-pages X.Y".
When we added the scripts written by Deri to produce a PDF book, the
title of the book was "The Linux Manpage Book", and the front page said
"GNU/Linux\nTHE MAN PAGES BOOK". For consistency with the project name,
I changed those some time ago to be title: "The Linux man-pages Book"
and front: "GNU/Linux\nTHE MAN-PAGES BOOK".
However, for consistency with the UNIX Programmer's Manual, and with the
old title used within the project, I'm now (partially) restoring the
title of the book and its front page to be both:
"GNU/Linux Programmer's Manual".
(It's not fully restorative, because it has GNU/Linux where the old
title had just Linux, but half of our documentation is for glibc, so I
think it's deserved.)
(I was never convinced by the old front text: why should it have the
word "book"?)
Cc: Douglas McIlroy <douglas.mcilroy@dartmouth.edu> Cc: "G. Branden Robinson" <branden@debian.org> Cc: Deri James <deri@chuzzlewit.myzen.co.uk> Cc: "Michael T. Kerrisk" <mtk.manpages@gmail.com> Signed-off-by: Alejandro Colomar <alx@kernel.org>
ctime.3: Document how to check errors from mktime(3)
-1 is a valid successful time_t, for one second before the Epoch. And
mktime(3) is allowed (like most libc calls) to set errno on success.
This makes it impossible to determine errors from the return value or
errno.
ISO C specifies that tp->tm_wday is unmodified after a failed call, and
puts an example where this is used to determine errors. It is indeed
the only way to check for errors from this call.
Document this detail in the RETURN VALUE section, add a CAVEATS section
that warns about this, and write an example program that shows how to
properly call this function.
Most code I've been able to find in several search engines either
doesn't check for errors after mktime(3), or checks them incorrectly, so
this documentation should help fix those.
This is guaranteed since ISO C23 and POSIX.1-2024. Prior to those
standards, there was no standard way to check for errors. However,
there are no known implementations that do not conform to this.
Link: <https://lore.kernel.org/linux-man/20240823131024.GD2713@cventin.lip.ens-lyon.fr/T/#t>
Link: <https://lore.kernel.org/linux-man/6un6baaq5tez23irtycuvzqtuh7a4sdrf2px7tnyb3y6iqoxmq@2ofln4cd27ep/T/#t>
Link: <https://www.open-std.org/jtc1/sc22/wg14/www/docs/n3147.txt>
Link: <https://www.open-std.org/jtc1/sc22/wg14/www/docs/n3148.doc>
Link: <https://austingroupbugs.net/view.php?id=1614>
Link: <https://www.open-std.org/jtc1/sc22/wg14/www/docs/n3220.pdf#subsubsection.7.29.2.3> Reported-by: Paul Eggert <eggert@cs.ucla.edu> Cc: Vincent Lefevre <vincent@vinc17.net> Cc: DJ Delorie <dj@redhat.com> Cc: Carlos O'Donell <carlos@redhat.com> Cc: Xi Ruoyao <xry111@xry111.site> Cc: Brian Inglis <Brian.Inglis@SystematicSW.ab.ca> Cc: "Robert C. Seacord" <rcseacord@gmail.com> Cc: Jens Gustedt <jens.gustedt@inria.fr> Cc: Robert Elz <kre@munnari.oz.au> Cc: Andrew Josey <ajosey@opengroup.org> Cc: Geoff Clare <gwc@opengroup.org> Cc: Hans Åberg <haberg-1@telia.com> Cc: GNU C Library <libc-alpha@sourceware.org> Cc: Austin Group <austin-group-l@opengroup.org> Signed-off-by: Alejandro Colomar <alx@kernel.org>
projects / thirdparty / man-pages.git / log
