Collin Funk [Thu, 19 Jun 2025 22:43:49 +0000 (15:43 -0700)]
man/man2/gettimeofday.2: Declare functions with [[deprecated]]
As documented in the STANDARDS section, gettimeofday(2) was deprecated
in POSIX.1-2008 and removed in POSIX.1-2024. Mark it and
settimeofday(2) with [[deprecated]], and mention clock_settime(2) as a
modern and standardized alternative to settimeofday(2).
Collin Funk [Fri, 13 Jun 2025 05:28:50 +0000 (22:28 -0700)]
man/man3/ptsname.3: VERSIONS: Document ptsname_r(3) incompatibility on FreeBSD
The FreeBSD implementation of ptsname_r(2) returns -1 on error and sets
errno, instead of just returning the errno. Document this issue for
programs written with portability in mind.
man/man2/close.2: CAVEATS: Document divergence from POSIX.1-2024
POSIX.1-2024 now mandates a behavior different from what Linux (and many
other implementations) does. It requires that we report EINPROGRESS for
what now is EINTR.
There are no plans to conform to POSIX.1-2024 within the Linux kernel,
so document this divergence. Keep POSIX.1-2008 as the standard to
which we conform in STANDARDS.
Link: <https://sourceware.org/bugzilla/show_bug.cgi?id=14627>
Link: <https://pubs.opengroup.org/onlinepubs/9799919799/functions/close.html> Cc: Jan Kara <jack@suse.cz> Cc: Alexander Viro <viro@zeniv.linux.org.uk> Cc: Christian Brauner <brauner@kernel.org> Cc: Rich Felker <dalias@libc.org> Cc: <linux-fsdevel@vger.kernel.org> Cc: <linux-api@vger.kernel.org> Cc: <libc-alpha@sourceware.org> Signed-off-by: Alejandro Colomar <alx@kernel.org>
ValdikSS [Wed, 15 Oct 2025 21:48:25 +0000 (00:48 +0300)]
man/man7/tcp.7: Add TCP_SAVE_SYN and TCP_SAVED_SYN
Document TCP_SAVE_SYN and TCP_SAVED_SYN options based on git commit
linux.git cd8ae85299d5 (2015-05-05; "tcp: provide SYN headers for
passive connections") which introduced it.
Rename uimaxabs(3) => umaxabs(3). And add a link page.
Keep a link with the old name, so that programmers looking for the old
name are redirected to the new name, so they find what they need.
I've removed documentation for uimaxabs(3), instead of keeping
information in HISTORY, as it has only existed for one glibc version,
to avoid programmers being confused by the old name.
man/man3/pthread_cond_init.3: CAVEATS: Add a note regarding real-time usage
The "old" implementation led to priority inversion and was more or less
easy to trigger. It seems that after the rewrite the issue disappeared
especially since the old workaround does not apply anymore.
Add a note mentioning the old problem and why the issue is not gone
since the rewrite in glibc 2.25 but harder to trigger.
Signed-off-by: Sebastian Andrzej Siewior <bigeasy@linutronix.de> Cc: André Almeida <andrealmeid@igalia.com> Cc: Darren Hart <dvhart@infradead.org> Cc: Davidlohr Bueso <dave@stgolabs.net> Cc: Ingo Molnar <mingo@redhat.com> Cc: Juri Lelli <juri.lelli@redhat.com> Cc: Peter Zijlstra <peterz@infradead.org> Cc: Thomas Gleixner <tglx@linutronix.de> Cc: Valentin Schneider <vschneid@redhat.com> Cc: Waiman Long <longman@redhat.com>
Message-ID: <20250915141305.906440-6-bigeasy@linutronix.de>
[alx: wfix, srcfix] Signed-off-by: Alejandro Colomar <alx@kernel.org>
man/man7/sched.7: SEE ALSO: Update the documentation references
The section refers to .txt files but they have been moved/ renamed to
.rst some time ago. The mentioned sched-rt-group is inconvenient as
people always complained about CONFIG_RT_GROUP_SCHED.
Everything that describes CFS is not wrong but the kernel the kernel
switched to the Earliest Virtual Deadline First (EEVDF) scheduler.
Instead of updating the file links below (and adding new ones), replace
them with a link to the automatically created scheduler documetation
from that folder. This also has some EEVDF bits. :)
Signed-off-by: Sebastian Andrzej Siewior <bigeasy@linutronix.de> Cc: André Almeida <andrealmeid@igalia.com> Cc: Darren Hart <dvhart@infradead.org> Cc: Davidlohr Bueso <dave@stgolabs.net> Cc: Ingo Molnar <mingo@redhat.com> Cc: Juri Lelli <juri.lelli@redhat.com> Cc: Peter Zijlstra <peterz@infradead.org> Cc: Thomas Gleixner <tglx@linutronix.de> Cc: Valentin Schneider <vschneid@redhat.com> Cc: Waiman Long <longman@redhat.com>
Message-ID: <20250915141305.906440-4-bigeasy@linutronix.de>
[alx: ffix] Signed-off-by: Alejandro Colomar <alx@kernel.org>
Update the outdated information:
- The PREEMPT_RT patch is merged. The patch continues to exist (as of
now) but is not mandatory.
- The patch can be still downloaded but most people use the git tree
these days. Add a reference to it.
- CONFIG_PREEMPT_DESKTOP was never thing as far as I remember. It was
always CONFIG_PREEMPT and its description referred to "low latency
desktop".
- Within the PREEMPT-RT patch there was a brief window which introduced
PREEMPT_RT_BASE and PREEMPT_RT_FULL. I am going to ignore this.
- The introduction of PREEMPT_LAZY in 6.13 moved PREEMPT_RT from a
preemption model to an option.
- The mentioned wiki is deprecated. Update the URL to the new one.
Signed-off-by: Sebastian Andrzej Siewior <bigeasy@linutronix.de> Cc: André Almeida <andrealmeid@igalia.com> Cc: Darren Hart <dvhart@infradead.org> Cc: Davidlohr Bueso <dave@stgolabs.net> Cc: Ingo Molnar <mingo@redhat.com> Cc: Juri Lelli <juri.lelli@redhat.com> Cc: Peter Zijlstra <peterz@infradead.org> Cc: Thomas Gleixner <tglx@linutronix.de> Cc: Valentin Schneider <vschneid@redhat.com> Cc: Waiman Long <longman@redhat.com>
Message-ID: <20250915141305.906440-3-bigeasy@linutronix.de>
[alx: minor tweaks] Signed-off-by: Alejandro Colomar <alx@kernel.org>
man/man3/[f]getc.3: Document that getc(3) should not be used
Move getc(3) to a separate manual page, documenting the bugs
of this API, and recommending fgetc(3) instead. While the
relevant standards (ISO C and POSIX) don't deprecate this
API, let's deprecate it here.
A lengthy comment in groff's man(7) package explains why attempts to
meddle with text alignment and adjustment with the `ad` and `na`
requests--outside of tbl(1) text blocks--exhibits contempt for reader
preferences and often comes to grief anyway.
.\" Resetting the adjustment mode is a complicated dance.
.\" 1. Man pages sometimes disable adjustment--when they do, they
.\" often forget to put it back the way it was.
.\" 2. When they do remember to put it back, they often fail to do
.\" so correctly because of the `ad` request's quirky semantics
.\" starting from Seventh Edition Unix troff/nroff. Briefly, the
.\" `ad` request without arguments turns adjustment back on after
.\" an `na` even if the previous adjustment mode was `l` (align to
.\" the left with NO adjustment).
.\" 3. The default adjustment mode historically has not been
.\" predictable; it can depend on nroff vs. troff mode and on the
.\" vendor of the *roff system in use.
.\" 4. It's possible (and portable) to obtain the previous adjustment
.\" mode via the `.j` register so that it can be saved prior to
.\" meddling and restored later, but in practice man page authors
.\" neglect to do so.
.\" 5. groff man(7)'s `AD` string isn't supported everywhere.
.\" 6. We want user preferences, if expressed, to override the page
.\" author's.
.\" 7. Even if we didn't want (6), one page author's can override
.\" another's when formatting multiple man(7) documents in
.\" sequence[.]
Add missing `x` column modifier to the descriptive column of the "VT100
console sequences not implemented on the Linux console" table, making it
format like all the other tables in this man page.
Spell out column heading as "parmeter"; "param" is a false economy given
that one of the entries in the same column is "100..107" (only one en
shorter).
Use a more idiomatic means (than numeral-width horizontal motion escape
sequences `\0`) of setting table entries that are indented with respect
to other entries in the same column.
Use table region continuation (`.T&`) and the `A` column classifier.
Use the dummy character to avoid a table entry consisting only of '=',
which would be interpreted as a table delimiter. We previously had
a white space, but that was worse: it is not visible in the input, and
produces non-ignorable output.
Aleksa Sarai [Wed, 1 Oct 2025 18:07:52 +0000 (20:07 +0200)]
man/man2/: Document new mount API set
Back in 2019, the new mount API was merged[1]. David Howells then set
about writing man pages for these new APIs, and sent some patches back
in 2020[2].
Unfortunately, these patches were never merged, which meant that these
APIs were practically undocumented for many years -- arguably this has
been a contributing factor to the relatively slow adoption of these new
(far better) APIs. For instance, I have often discovered that many
folks are unaware of the read(2)-based message retrieval interface
provided by filesystem context file descriptors.
In 2024, Christian Brauner adapted David Howell's original man pages
into the easier-to-edit Markdown format and published them on GitHub[3].
These have been maintained since, including updated information on new
features added since David Howells's 2020 draft pages (such as
MOVE_MOUNT_BENEATH).
While this was a welcome improvement to the previous status quo (that
had lasted over 6 years), speaking personally my experience is that not
having access to these man pages from the terminal has been a fairly
common painpoint.
So, this is a modern version of the man pages for these APIs, in the
hopes that we can finally (6 years later) get proper documentation for
these APIs in the man-pages project.
One important thing to note is that most of these were re-written by me,
with very minimal copying from the versions available from Christian[2].
The reasons for this are two-fold:
- Both Howells's original version and Christian's maintained versions
contain crucial mistakes that I have been bitten by in the past (the
most obvious being that all of these APIs were merged in Linux 5.2,
but the man pages all claim they were merged in different versions.)
- As the man pages appear to have been written from Howells's
perspective while implementing them, some of the wording is a little
too tied to the implementation (or appears to describe features that
don't really exist in the merged versions of these APIs).
- The original versions of the man-pages lacked bigger-picture
explanations of the reasoning behind the API, which would make it
easier for readers to understand what operations are doing.
I decided that the best way to resolve these issues is to rewrite them
from the perspective of an actual user of these APIs (me), and check
that we do not repeat the mistakes I found in the originals. I have
also done my best to resolve the issues raised by Michael Kerrisk on the
original patchset sent by Howells[1].
In addition, I have also included a man page for open_tree_attr(2) (as a
subsection of the new open_tree(2) man page), which was merged in Linux
6.15.
man/man2/{fsconfig,mount_setattr}.2: NOTES: Add note about attribute-parameter distinction
This was not particularly well documented in mount(8) nor mount(2), and
since this is a fairly notable aspect of the new mount API, we should
probably add some words about it.
man/man2/open_tree{,_attr}.2: Document open_tree_attr(), and add link page
This is a new API added in Linux 6.15, and is effectively just a minor
expansion of open_tree(2) in order to allow for MOUNT_ATTR_IDMAP to be
changed for an existing ID-mapped mount. glibc does not yet have a
wrapper for this.
While working on this man-page, I discovered a bug in open_tree_attr(2)
that accidentally permitted changing MOUNT_ATTR_IDMAP for extant
detached ID-mapped mount objects. This is definitely a bug, but there
is no need to add this to BUGS because the patch to fix this has already
been accepted (slated for 6.18, and will be backported to 6.15+).
This is loosely based on the original documentation written by David
Howells and later maintained by Christian Brauner, but has been
rewritten to be more from a user perspective (as well as fixing a few
critical mistakes).
Co-authored-by: David Howells <dhowells@redhat.com> Signed-off-by: David Howells <dhowells@redhat.com> Co-authored-by: Christian Brauner <brauner@kernel.org> Signed-off-by: Christian Brauner <brauner@kernel.org> Signed-off-by: Aleksa Sarai <cyphar@cyphar.com>
Message-ID: <20250925-new-mount-api-v5-6-028fb88023f2@cyphar.com> Reviewed-by: Askar Safin <safinaskar@gmail.com> Signed-off-by: Alejandro Colomar <alx@kernel.org>
This is loosely based on the original documentation written by David
Howells and later maintained by Christian Brauner, but has been
rewritten to be more from a user perspective (as well as fixing a few
critical mistakes).
Co-authored-by: David Howells <dhowells@redhat.com> Signed-off-by: David Howells <dhowells@redhat.com> Co-authored-by: Christian Brauner <brauner@kernel.org> Signed-off-by: Christian Brauner <brauner@kernel.org> Signed-off-by: Aleksa Sarai <cyphar@cyphar.com>
Message-ID: <20250925-new-mount-api-v5-5-028fb88023f2@cyphar.com> Reviewed-by: Askar Safin <safinaskar@gmail.com>
[alx: ffix] Signed-off-by: Alejandro Colomar <alx@kernel.org>
This is loosely based on the original documentation written by David
Howells and later maintained by Christian Brauner, but has been
rewritten to be more from a user perspective (as well as fixing a few
critical mistakes).
Co-authored-by: David Howells <dhowells@redhat.com> Signed-off-by: David Howells <dhowells@redhat.com> Co-authored-by: Christian Brauner <brauner@kernel.org> Signed-off-by: Christian Brauner <brauner@kernel.org> Signed-off-by: Aleksa Sarai <cyphar@cyphar.com>
Message-ID: <20250925-new-mount-api-v5-4-028fb88023f2@cyphar.com> Reviewed-by: Askar Safin <safinaskar@gmail.com> Signed-off-by: Alejandro Colomar <alx@kernel.org>
This is loosely based on the original documentation written by David
Howells and later maintained by Christian Brauner, but has been
rewritten to be more from a user perspective (as well as fixing a few
critical mistakes).
Co-authored-by: David Howells <dhowells@redhat.com> Signed-off-by: David Howells <dhowells@redhat.com> Co-authored-by: Christian Brauner <brauner@kernel.org> Signed-off-by: Christian Brauner <brauner@kernel.org> Signed-off-by: Aleksa Sarai <cyphar@cyphar.com>
Message-ID: <20250925-new-mount-api-v5-3-028fb88023f2@cyphar.com> Reviewed-by: Askar Safin <safinaskar@gmail.com>
[alx: s/name/key/; ffix] Signed-off-by: Alejandro Colomar <alx@kernel.org>
This is loosely based on the original documentation written by David
Howells and later maintained by Christian Brauner, but has been
rewritten to be more from a user perspective (as well as fixing a few
critical mistakes).
Co-authored-by: David Howells <dhowells@redhat.com> Signed-off-by: David Howells <dhowells@redhat.com> Co-authored-by: Christian Brauner <brauner@kernel.org> Signed-off-by: Christian Brauner <brauner@kernel.org> Signed-off-by: Aleksa Sarai <cyphar@cyphar.com>
Message-ID: <20250925-new-mount-api-v5-2-028fb88023f2@cyphar.com> Reviewed-by: Askar Safin <safinaskar@gmail.com> Signed-off-by: Alejandro Colomar <alx@kernel.org>
This is loosely based on the original documentation written by David
Howells and later maintained by Christian Brauner, but has been
rewritten to be more from a user perspective (as well as fixing a few
critical mistakes).
Co-authored-by: David Howells <dhowells@redhat.com> Signed-off-by: David Howells <dhowells@redhat.com> Co-authored-by: Christian Brauner <brauner@kernel.org> Signed-off-by: Christian Brauner <brauner@kernel.org> Signed-off-by: Aleksa Sarai <cyphar@cyphar.com>
Message-ID: <20250925-new-mount-api-v5-1-028fb88023f2@cyphar.com> Reviewed-by: Askar Safin <safinaskar@gmail.com> Signed-off-by: Alejandro Colomar <alx@kernel.org>
man/man2/mount_setattr.2: Mirror opening sentence from fsopen(2)
All of the other new mount API docs have this lead-in sentence in order
to make this set of APIs feel a little bit more cohesive. Despite being
a bit of a latecomer, mount_setattr(2) is definitely part of this family
of APIs and so deserves the same treatment.
man/man2/mount_setattr.2, man/man2type/mount_attr.2type: Move mount_attr struct to new page mount_attr(2type)
As with open_how(2type), it makes sense to move this to a separate man
page. In addition, future man pages added in this patchset will want to
reference mount_attr(2type).
Within recipes, variables have delayed expansion, which means that we
can't use variables that we've undefined. That's why we need to use
a filter to get the regex file name from the rule prerequisites. This
trick was suggested by Philip.
Cc: Philip Guenther <guenther@gmail.com> Cc: Paul Smith <psmith@gnu.org> Cc: Martin Dorey <Martin.Dorey@hitachivantara.com> Signed-off-by: Alejandro Colomar <alx@kernel.org>
Reported-by: Christoph Anton Mitterer <calestyo@scientia.org> Suggested-by: Christoph Anton Mitterer <calestyo@scientia.org> Signed-off-by: Alejandro Colomar <alx@kernel.org>
projects / thirdparty / man-pages.git / log
