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.
Vincent Lefevre [Thu, 8 Aug 2024 11:56:10 +0000 (13:56 +0200)]
nextup.3: wfix + tfix
The current "If x is 0" condition is a bit misleading because "is"
is not the equality test (just like when saying "x is NaN") and 0
as a FP number stands for +0, while this condition should apply to
both -0 and +0.
Replace this condition by "If x is +0 or -0".
Replace "Nan" by "NaN" (typography used everywhere else).
Cc: Dave Kemper <saint.snit@gmail.com> Cc: "G. Branden Robinson" <branden@debian.org> Cc: Damian McGuckin <damianm@esi.com.au> Cc: John Gardner <gardnerjohng@gmail.com> Signed-off-by: Vincent Lefevre <vincent@vinc17.net>
Message-ID: <20240808115610.GC2669@cventin.lip.ens-lyon.fr> Signed-off-by: Alejandro Colomar <alx@kernel.org>
Mikołaj Kołek [Wed, 7 Aug 2024 13:58:32 +0000 (15:58 +0200)]
sigaction.2: Improve wording and add an example in the BUGS section
This patch clears up the wording of the first part of the BUGS section
of the sigaction(2) manual page. Currently, it is very unclear when
exactly the bug can occur, and there is no example, which I aim to
fix. The text of the patch is partially based on the BUGS section of
the signal(2) manual page.
I also attach a C program that, when run on an x86 Linux computer,
shows that my example behaves like I say it does. The code runs the
int instruction for each value from 0 to 255 with all registers set to
0 to show that all fields of the siginfo_t besides si_signo and
si_code equal zero. The program is based on the attachment to bug
205831 on the kernel bugtracker which first dealt with this issue,
which you can find here:
<https://bugzilla.kernel.org/show_bug.cgi?id=205831>. This is the code
of the test program:
// skip the faulting instruction
if(*pc == 0xCC || *pc == 0xF1)
uc->uc_mcontext.gregs[REG_RIP] += 1;
else if(*pc == 0xCD)
uc->uc_mcontext.gregs[REG_RIP] += 2;
else
; //assume the PC has already been advanced over the fault
}
Andy Pan [Thu, 1 Aug 2024 11:38:38 +0000 (11:38 +0000)]
epoll.7: Clarify the event distribution under edge-triggered mode
For the moment, the edge-triggered epoll generates an event for each
receipt of a chunk of data, that is to say, epoll_wait() will return
and tell us a monitored file descriptor is ready whenever there is a
new activity on that FD since we were last informed about that FD.
This is not a real _edge_ implementation for epoll, but it's been
working this way for years and plenty of projects are relying on it
to eliminate the overhead of one system call of read(2) per wakeup event.
There are several renowned open-source projects relying on this feature
for notification function (with eventfd): register eventfd with EPOLLET
and avoid calling read(2) on the eventfd when there is wakeup event (eventfd being written).
Examples: nginx [1], netty [2], tokio [3], libevent [4], ect. [5]
These projects are widely used in today's Internet infrastructures.
Thus, changing this behavior of epoll ET will fundamentally break them
and cause a significant negative impact.
Linux has changed it for pipe before [6], breaking some Android libraries,
which had got "reverted" somehow. [7] [8]
Nevertheless, the paragraph in the manual pages describing this
characteristic of epoll ET seems ambiguous, I think a more explict
sentence should be used to clarify it. We're improving the notification
mechanism for libuv recently by exploiting this feature with eventfd,
which brings us a significant performance boost. [9]
Therefore, we (as well as the maintainers of nginx, netty, tokio, etc.)
would have a sense of security to build an enhanced notification function
based on this feature if there is a guarantee of retaining this implementation
of epoll ET for the backward compatibility in the man pages.
landlock.7, landlock_*.2: Document Landlock ABI version 4
Landlock ABI 4 restricts bind(2) and connect(2) on TCP port numbers.
The intent is to bring the man pages mostly in line with the kernel
documentation again. I intentionally did not add networking support to the
usage example in landlock.7 - I feel that in the long run, we would be better
advised to maintain longer example code in the kernel samples.
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-syscall-table-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/
share/mk/: Reduce the work of 'make && make install'
Distros expect 'make' to build only what they need. While we want to
build more stuff upstream, for various reasons (mainly, for extra
diagnostics), packagers only want what they'll use, and don't want to
waste CPU time with that.
Also, distros expect 'make install' to only install what they'll use,
which is just the manual pages.
For that, repurpose the build and install targets to do precisely that,
and add build-all and install-all targets that do all that can be done.
Reported-by: Sam James <sam@gentoo.org> Signed-off-by: Alejandro Colomar <alx@kernel.org>
Cherry-picked-from: liba2i.git 791f163b1a72 (2024-07-18, "share/mk/: Reduce the work of 'make && make install'") Signed-off-by: Alejandro Colomar <alx@kernel.org>
projects / thirdparty / man-pages.git / log
