===
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>
наб [Fri, 16 Aug 2024 22:35:27 +0000 (00:35 +0200)]
bdflush.2, syscalls.2: bdflush was removed
There's no point documenting this syscall at any point in time,
because it changed constantly. A post-mortem summary I believe to be
comprehensive is included below.
The #include <sys/kdaemon.h> was removed in glibc 2.23:
commit eed3e1eb79bcfa9b52609fd875fa2d522e2d6bce
Author: Joseph Myers <joseph@codesourcery.com>
Date: Mon Dec 14 22:52:15 2015 +0000
Make obsolete syscall wrappers into compat symbols (bug 18472).
* bdflush: in Linux 2.6, does nothing if present.
[...]
generated for such aliases. Those five syscalls are then made into
compat symbols (obsoleted in glibc 2.23, so future ports won't have
these symbols at all), with the header <sys/kdaemon.h> declaring
bdflush being removed. When we move to 3.2 as minimum kernel version,
the same can be done for nfsservctl (removed in Linux 3.1) as well.
[...]
Appears in 1.1.3
(func=0 turns the calling process into the bdflush daemon,
func=1 return sync_old_buffers();,
func>=2 is parameters):
Author: Linus Torvalds <torvalds@linuxfoundation.org>
Import 1.1.3
+/* This is the interface to bdflush. As we get more sophisticated, we can
+ * pass tuning parameters to this "process", to adjust how it behaves. If you
+ * invoke this again after you have done this once, you would simply modify
+ * the tuning parameters. We would want to verify each parameter, however,
+ * to make sure that it is reasonable. */
+
+asmlinkage int sys_bdflush(int func, int data)
+{
bdflush() is just a kernel thread, and func 0 is just return 0; since 1.3.50:
Author: Linus Torvalds <torvalds@linuxfoundation.org>
Import 1.3.50
- /* Basically func 0 means start, 1 means read param 1, 2 means write param 1, etc */
+ /* Basically func 1 means read param 1, 2 means write param 1, etc */
if (func >= 2) {
i = (func-2) >> 1;
if (i < 0 || i >= N_PARAM)
@@ -1930,13 +1845,32 @@ asmlinkage int sys_bdflush(int func, long data)
bdf_prm.data[i] = data;
return 0;
};
+
+ /* Having func 0 used to launch the actual bdflush and then never
+ return (unless explicitly killed). We return zero here to
+ remain semi-compatible with present update(8) programs. */
+
+ return 0;
+}
+
+/* This is the actual bdflush daemon itself. It used to be started from
+ * the syscall above, but now we launch it ourselves internally with
+ * kernel_thread(...) directly after the first thread in init/main.c */
+
+int bdflush(void * unused) {
func 1 is actually exit(0) since 2.3.23pre1:
Author: Linus Torvalds <torvalds@linuxfoundation.org>
Import 2.3.23pre1
if (func == 1) {
+ /* do_exit directly and let kupdate to do its work alone. */
+ do_exit(0);
+#if 0 /* left here as it's the only example of lazy-mm-stuff used from
+ a syscall that doesn't care about the current mm context. */
fund!=0 is a return 0 since 2.5.12:
Author: Andrew Morton <akpm@zip.com.au>
Date: Mon Apr 29 23:52:10 2002 -0700
[PATCH] writeback from address spaces
[ I reversed the order in which writeback walks the superblock's
dirty inodes. It sped up dbench's unlink phase greatly. I'm
such a sleaze ]
The core writeback patch. Switches file writeback from the dirty
buffer LRU over to address_space.dirty_pages.
- The buffer LRU is removed
- The buffer hash is removed (uses blockdev pagecache lookups)
- The bdflush and kupdate functions are implemented against
address_spaces, via pdflush.
[...]
Deprecated since 2.5.52:
Author: Andrew Morton <akpm@digeo.com>
Date: Sat Dec 14 03:16:29 2002 -0800
[PATCH] deprecate use of bdflush()
Patch from Robert Love <rml@tech9.net>
We can never get rid of it if we do not deprecate it - so do so and
print a stern warning to those who still run bdflush daemons.
Removed outright in 5.15-rc1:
commit b48c7236b13cb5ef1b5fdf744aa8841df0f7b43a
Author: Eric W. Biederman <ebiederm@xmission.com>
Date: Tue Jun 29 15:11:44 2021 -0500
exit/bdflush: Remove the deprecated bdflush system call
The bdflush system call has been deprecated for a very long time.
Recently Michael Schmitz tested[1] and found that the last known
caller of of the bdflush system call is unaffected by it's removal.
projects / thirdparty / man-pages.git / log
