Anyone can create a tarball from a release tag, and it should be
identical to the release tarball, so that the PGP signature made at the
release matches. This is useful for distributors.
fts.3: Note fts_open() behaviour with empty strings
This is undocumented in BSD, too, and present in the original SCCS
check-in (5.1 (Berkeley) 12/30/89).
This is very surprising, since in most other cases FTS is rather quite
sane about error reporting, but /any/ empty string in the input vector
blows out the creation entirely.
When running 'make dist' from a tarball (so we don't have git), we'll
see tons of errors saying we're not in a git tree. However, that's not
meaningful, because that command is a no-op in such a scenario: the
(date) placeholder is not there anymore to be replaced. Let's hide the
errors, unless V=1.
RELEASE, dist.mk: Use make(1)'s -B to force recreation of the dist files
Using FORCE unnecessarily restarts the entire build, even if we _know_
nothing changed. That's boring. Trust ourselves, and write the
commands in the RELEASE file as using '-B', to remind ourselves.
Forgetting to use -B will result in incorrect timestamps or versioning
in the distributed pages, so don't forget it ;).
While we're at it, let's also use -j4 directly, so I don't read the
paragraph reminding me to use -j _after_ I've already run it. Let's
write -j4 instead of -j so that we don't crash some innocent's system.
- Add "History" section, with a link to aeb's website with
man-pages-1.* tarballs.
- Move "Maintainers" to a subsection in the new "History" section.
- Organize "Versions" into subsections ("Tarballs", "Git", and
"Online pages").
- Add links to the cgit websites of the git repositories.
- Add link to the PDF online man-pages book.
- wsfix in mtk's entry.
Modelled after tmpfs(5) ‒ there's a listing of mount options, and a
summary of limitations. The feature flags are described in mkfs.erofs,
and they're versioned and maintained upstream quite well there, so no
need to duplicate those, since you only care on image creation.
The real value add is the mount options, but I cannot figure out how
device_id and fsid interact with the system at large, so I just noted
they're there.
State as of Linux 6.3-rc5.
Also, remove explicit .TP indent in filesystems.5 since we're already
touching this hunk: all entries sans iso9660 and Reiserfs fall within
the default prevailing indent, so no need to specify a wide one.
Settle on "no effect", concretify vaguely-described behaviours;
both [to be documented]s replaced with documentation
(these match my 6.2 checkout, if there were subtleties in the history
they got lost).
Added the full system names to the PER_s that lacked them.
Didn't validate or chase down the versions except for PER_RISCOS.
Having these be sorted instead of in the original enumeration order is
really more trouble than it's worth.
PER_LINUX is a base personality, PER_LINUX_{32BIT,FDPIC} are
PER_LINUX|ADDR_LIMIT_32BIT and PER_LINUX|FDPIC_FUNCPTRS, resp.
PER_BSD is a base personality, PER_SUNOS is PER_BSD|STICKY_TIMEOUTS.
PER_LINUX32 is a base personality, PER_LINUX32_3GB is
PER_LINUX32|ADDR_LIMIT_3GB.
I updated these all to be "Same as {base personality},
but implies {...}.". PER_SCOSVR3 has an "also", since it's the only one
where the base case PER_OSR5 has a list.
malloc_usable_size.3: The returned value should not be trusted
It might very well return a value larger than the actual usable size, so
writing to the excess bytes is Undefined Behavior. There's absolutely
no promise about the value, except that it is no less than the size
that was once passed to malloc(3).
Link: <https://github.com/systemd/systemd/issues/22801#issuecomment-1343041481>
Link: <https://inbox.sourceware.org/libc-alpha/20221124213258.305192-1-siddhesh@gotplt.org/T/> Reported-by: Mingye Wang <arthur200126@gmail.com> Reported-by: Siddhesh Poyarekar <siddhesh@gotplt.org> Cc: DJ Delorie <dj@redhat.com> Cc: Sam James <sam@gentoo.org> Cc: Florian Weimer <fweimer@redhat.com> Cc: Andreas Schwab <schwab@linux-m68k.org> Cc: Zack Weinberg <zack@owlfolio.org> Cc: Wilco Dijkstra <Wilco.Dijkstra@arm.com> Signed-off-by: Alejandro Colomar <alx@kernel.org>
mandoc(1) renders pages much faster than groff(1), which is itself much
faster than using man(1). This might seem irrelevant for a single page,
but this function is called in a loop in man_lsfunc() and man_lsvar(),
where this brings times down considerably. For comparison,
`time man_lsfunc man*` took around 55 s (on my system) before this
change. With groff(1), it would take around 14 s, and with mandoc(1)
(this patch), it takes 4 s.
Cc: Ingo Schwarze <schwarze@openbsd.org> Cc: "G. Branden Robinson" <g.branden.robinson@gmail.com> Cc: Gavin Smith <gavinsmith0123@gmail.com> Cc: Dirk Gouders <dirk@gouders.net> Cc: Colin Watson <cjwatson@debian.org> Cc: Eli Zaretskii <eliz@gnu.org> Cc: Larry McVoy <lm@mcvoy.com> Signed-off-by: Alejandro Colomar <alx@kernel.org>
It is unnecessary to let readers believe it's const. Keep it as a
detail in VERSIONS, which will only be found by those who need it. It
is better to believe it's non-const, and rarely will one need to know
that it isn't true.
While '$(V).SILENT:' is a common idiom in make, it may be more explicit
to put '.SILENT:' inside a conditional. Since we already used the
conditional for something else, it's not a big change. As a nice side
effect, vim now recognizes it and highlights it as a special target.
With the old code, GNU Make 4.4 reported a warning about undefined
variables:
I should have removed this in the previous commit, but somehow I forgot,
and my initial tests didn't reveal the bug. After trying to check a
specific page as a contributor would do, I noticed the problem.
*.mk, CONTRIBUTING, INSTALL: lint, build, check: Reorganize some targets
Some targets which were under lint-* were really building cat pages, so
let's call it build-catman, since it's what it is. As part of the
build, it will report warnings, of course, as any other build system, so
nothing really changed, except for the target names, and the path in the
build tree where the cat pages (and intermediate files) are placed,
which is now directly under <.tmp/man/*>.
Some other targets were checking that the cat pages were correct after
the build, so those targets have been moved to check-* targets.
Document that contributors should run both the 'lint' and 'check'
targets to check the correctness of their patches.
`make all`, a.k.a. `make build`, now builds _all_ that can be built,
including cat pages, and C programs.
Implementation detail: $LINTMAN has been renamed, since now it's used
also for things that are not linters. Call it $NONSO_MAN, since it's a
list of the non-'.so' man pages, which are the ones we want to lint,
build, and check.
Future directions:
I plan to implement 'build-html' using groff(1), which will reuse part
of the build-catman pipeline. That will produce much higher quality
HTML manual pages.
наб [Fri, 31 Mar 2023 22:04:52 +0000 (00:04 +0200)]
proc.5: NAME: Add "system information, and sysctl"
procfs hosts a whole host of information about the system, as well as
sysctls; proc(5) hosts a description of a lot of sysctls, and at present
there's no way to find that out.
user_namespaces.7: Add note about PR_SET_DUMPABLE on nested userns
In order to create a nested user namespace, we need to re-set the
PR_SET_DUMPABLE attribute after switching the effective UID/GID. Clarify
this in the section about nested user namespaces.
Having this note would have saved me some time debugging.
Younes Manton [Tue, 17 Jan 2023 18:03:36 +0000 (10:03 -0800)]
proc.5: Fix caps needed to read map_files contents
imachug@yandex.ru testing CRIU noticed that the documentation for proc's
map_files directory with respect to CAP_CHECKPOINT_RESTORE and
namespaces appears to be wrong. The text reads:
> since Linux 5.9, the reading process must have
> either CAP_SYS_ADMIN or CAP_CHECKPOINT_RESTORE in the user
> namespace where it resides.
The reporter noted that the user actually needs the capabilities in the
initial user namespace, not in the namespace the process resides in. As
far as I can tell this appears to be the case.
Günther Noack [Fri, 24 Mar 2023 17:24:17 +0000 (18:24 +0100)]
landlock.7: Document Landlock ABI v2 (file reparenting; Linux 5.19)
* Add the description for LANDLOCK_ACCESS_FS_REFER,
in line with recent update to the uapi headers:
https://lore.kernel.org/linux-security-module/20230202204623.10345-1-gnoack3000@gmail.com/T/
* VERSIONS: Add a table of Landlock versions and their changes.
Briefly talk about how to probe ABI levels and warn users about the
special semantics of the LANDLOCK_ACCESS_FS_REFER right.
* Add LANDLOCK_ACCESS_FS_REFER to the code example.
Code review threads for the "refer" feature:
* https://git.kernel.org/torvalds/c/cb44e4f061e16be65b8a16505e121490c66d30d0
* https://lore.kernel.org/all/20230221165205.4231-1-gnoack3000@gmail.com/ (documentation update)
- Add a new HISTORY section that covers the history of an API, both
regarding implementations and regarding old standards. This was
previously covered in VERSIONS, and in some cases in STANDARDS.
- Repurpose VERSIONS to cover differing implementations in _current_
systems.
- STANDARDS is reduced to only cover current versions of standards.
That basically means only C11 (C99 has been superseeded by C11; C17
is just a bugfix of C11, so not really a new version), and
POSIX.1-2008 (*-2001 was superseeded by *-2008; *-2017 was just a
bugfix for *-2008). The section also mentions for example 'Linux',
'GNU' or 'BSD' when a non-standard API is Linux- or GNU-only or if
it's (de-facto) standard in the BSDs.
- In some cases content that should go into one of these sections was
in NOTES. Move it from there to where it corresponds.
- In the SYNOPSIS, I added [[deprecated]] in some functions that I
found are deprecated by the relevant standards.
man2/, man3/, man-pages.7: Move VERSIONS next to STANDARDS
VERSIONS and STANDARDS are closely related (and often the distinction is
not so clear). Now that we're going to add another section, HISTORY,
that is related to both, it makes sense to have the three together.
As a curiosity, the list in man-pages(7) that detailed what each section
should contain had them by accident(?) in the order that we're moving
to, instead of the order that was used elsewhere.
INADDR_ANY has nothing to do with the IP_MULTICAST_ALL option.
It does not matter if the interface is bound to all interfaces
or a particular interface for the functionality of IP_MULTICAST_ALL.
Multicast datagrams are addressed to a multicast IP address and will enter
the network stack via a particular interface. The application can choose
from which interface it will receive multicast data by binding the socket
to an IP address. It can then use the IP_MULTICAST_ALL option to
restrict the multicast groups that the IP stack will deliver via the
socket.
Signed-off-by: Christoph Lameter <cl@linux.com> Signed-off-by: Alejandro Colomar <alx@kernel.org>
This removal caused inconveniences to some programmers. We've agreed to
keep the information about C89, since there's an easy way to keep it
correct by checking against a plain-text copy of the standard itself:
We will also do a split of the information in STANDARDS, since now it's
a mix of what a proper STANDARDS section would be plus a HISTORY section
commonly-found in other manual pages. C89 will go into HISTORY.
Link: <https://lore.kernel.org/linux-man/b73a9636-1a17-36f3-3718-d9ca3b9293ed@gmail.com/T/>
Link: <https://port70.net/~nsz/c/c89/c89-draft.txt> Reported-by: Oskari Pirhonen <xxc3ncoredxx@gmail.com> Reported-by: Matt Jolly <Matt.Jolly@footclan.ninja> Cc: Brian Inglis <Brian.Inglis@Shaw.ca> Signed-off-by: Alejandro Colomar <alx@kernel.org>
*.mk: Remove unnecessary '.' after directory names (but keep the '/')
I used it for some reason I don't remember, probably because I did
something wrong, and didn't know how to do it right. I've tried now
without it, and it's working, so let's just remove it.
While we don't want trailing slashes in directory variables, we want
them in targets, so we can distinguish directory targets.
eqn(1) could theoretically write _only_ newlines to standard error.
That's unlikely, but I'm still worried that someone (even me) might copy
this trick around, and use it in situations where that might actually
happen. Let's be more precise, and fail when there's literally anything
on standard error.
Reported-by: Ralph Corderoy <ralph@inputplus.co.uk> Signed-off-by: Alejandro Colomar <alx@kernel.org>
Without .DELETE_ON_ERROR, if a command fails, but has written to a file
(e.g., with '>'), the file will still exist, and successive make(1)
invocations will think it previously succeeded.
projects / thirdparty / man-pages.git / log
