Add an empty double-colon rule that targets the makefiles, to instruct
make(1) to not remake makefiles. This improves (considerably reduces)
the output of 'make -d'.
Xi Ruoyao [Sun, 16 Jul 2023 01:51:25 +0000 (09:51 +0800)]
crypt.3, encrypt.3: Fix library name and description
libcrypt is the password hashing library, and libcrypto is a completely
different library (OpenSSL cryptography library). While the encrypt()
function can "encrypt" things, it uses a broken algorithm so let's not
call libcrypt an "encryption" library at all. In crypt.3, also replace
"encrypt" with "hash" except several places where it really means
"encrypt".
Signed-off-by: Xi Ruoyao <xry111@xry111.site> Signed-off-by: Alejandro Colomar <alx@kernel.org>
Which don't behave like you may expect them to;
unprimed, I expected the natural extension of either:
files (being a filesystem object), always returning 0 if no data, or
sockets (being an IPC mechanism), always EAGAINing if no data.
The pipe semantics make sense of course ‒ pipes can be modelled as
sockets if there aren't writers, but files if there are; indeed,
this makes sense as the writer continuously appending a sliding
"window" over a file ‒ but they're unique amongst the UNIX file types,
but arriving at that specific interaction table is non-obvious,
especially to a user.
Quoth Issue 8 Draft 3:
60746 When attempting to read from an empty pipe or FIFO:
60747 • If no process has the pipe open for writing, read( ) shall return 0 to indicate end-of-file.
60748 • If some process has the pipe open for writing and O_NONBLOCK is set, read( ) shall return
60749 −1 and set errno to [EAGAIN].
60750 • If some process has the pipe open for writing and O_NONBLOCK is clear, read( ) shall
60751 block the calling thread until some data is written or the pipe is closed by all processes that
60752 had the pipe open for writing.
Paul Eggert [Sun, 9 Jul 2023 06:07:55 +0000 (23:07 -0700)]
man*/: Prefer off_t over off64_t for splice(2), etc.
For the few functions that come only in 64-bit off_t flavors,
document their APIs as using off_t instead of off64_t,
and say also that code should #define _FILE_OFFSET_BITS 64.
This documents what user code is (and should be) doing anyway,
if it needs to work on traditional x86 and ARM Linux.
Reported-by: Rich Felker <dalias@libc.org> Fixes: 9bebb17e5b57 ("splice.2: Use 'off64_t' instead of 'loff_t'") Fixes: 76c5631fb442 ("copy_file_range.2: Document glibc wrapper instead of kernel syscall") Fixes: 5cabfa06b407 ("man-pages 1.68") Fixes: 3ca974e3988a ("New page for sync_file_range(2), new in kernel 2.6.17.") Fixes: 9bebb17e5b57 ("sync_file_range.2: Document the architecture-specific sync_file_range2() system call") Fixes: 79bf8cdcf36a ("Document fopencookie(3), a library function that allows custom implementation of a stdio stream.") Signed-off-by: Paul Eggert <eggert@cs.ucla.edu> Reviewed-by: Sam James <sam@gentoo.org> Cc: Jonathan Wakely <jwakely@redhat.com> Cc: Szabolcs Nagy <nsz@port70.net> Cc: Jakub Wilk <jwilk@jwilk.net> Cc: A. Wilcox <AWilcox@wilcox-tech.com> Signed-off-by: Alejandro Colomar <alx@kernel.org>
On 2023-07-08 22:14, Martin (Joey) Schulze wrote:
> For the record,
>
> I would like to re-license dir_colors(5) under the GPLv2+
>
> Please adjust the manpage source accordingly.
>
> .\" Copyright (c) 2001 Martin Schulze <joey@infodrom.org>
> .\"
> .\" This is free documentation; you can redistribute it and/or
> .\" modify it under the terms of the GNU General Public License as
> .\" published by the Free Software Foundation; either version 2 of
> .\" the License, or (at your option) any later version.
> .\"
> .\" The GNU General Public License's references to "object code"
> .\" and "executables" are to be interpreted as the output of any
> .\" document formatting or typesetting system, including
> .\" intermediate and printed output.
> .\"
> .\" This manual is distributed in the hope that it will be useful,
> .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
> .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
> .\" GNU General Public License for more details.
> .\"
> .\" You should have received a copy of the GNU General Public
> .\" License along with this manual; if not, write to the Free
> .\" Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139,
> .\" USA.
>
> This should help keep the manpage free and a version in Fedora.
Link: <https://gitlab.com/fedora/legal/fedora-license-data/-/issues/211> Reported-by: Adam Dobes <adobes@redhat.com> Cc: Brian Inglis <Brian.Inglis@Shaw.ca> Cc: Martin (Joey) Schulze <joey@infodrom.org> Signed-off-by: Alejandro Colomar <alx@kernel.org>
Quoting myself from #musl:
01:59:40 hm, I think this was just invented for symmetry with bfree/bavail
02:00:46 FFS has minfree for space but nothing equivalent for inodes
02:32:31 (this is mirrored in ext4;
a global grep over DragonFlyBSD and the illumos gate
showed just NFSv3 forwarding from the server;
OpenBSD always sets it to the same thing as f_ffree;
oddly, NetBSD /does/ calculate it differently
for LFS and FFS but due to queued writes or
w/e not because of root reservation;
and as expected a lot of "/* what to put in here? */"
and "// XXX same??")
Paul E. McKenney [Fri, 30 Jun 2023 23:33:28 +0000 (16:33 -0700)]
proc.5: Clarify that boot arguments can be embedded in image
With the advent of the CONFIG_BOOT_CONFIG Kconfig option, kernel boot
arguments can now be embedded in the kernel image, either attached
to the end of initramfs or embedded in the kernel itself. Document
this possibility in the /proc/cmdline entry of proc.5.
Signed-off-by: Paul E. McKenney <paulmck@kernel.org> Cc: Michael Kerrisk <mtk.manpages@gmail.com> Cc: Jonathan Corbet <corbet@lwn.net> Cc: Andrew Morton <akpm@linux-foundation.org> Cc: Nick Desaulniers <ndesaulniers@google.com> Cc: Vlastimil Babka <vbabka@suse.cz> Cc: Johannes Weiner <hannes@cmpxchg.org> Reviewed-by: Masami Hiramatsu <mhiramat@kernel.org> Signed-off-by: Alejandro Colomar <alx@kernel.org>
inotify.7: wds are in the range [1, INT_MAX], not [0,
Naturally, the first inotify_add_watch() returns 1,
but also fs/notify/inotify.c:inotify_add_to_idr() allocates them with
idr_alloc_cyclic(idr, i_mark, start=1, end=0, GFP_NOWAIT);
(start inclusive, end exclusive).
(From SYSCALL_DEFINE3(inotify_add_watch, ...),
from inotify_update_watch(),
from inotify_new_watch()).
наб [Sat, 24 Jun 2023 12:13:29 +0000 (14:13 +0200)]
poll.2: explicitly say what happens for regular files &c.
Naively, one may consider being "ready" to mean, for example,
lseek(0, 0, SEEK_END); poll({.fd = 0, .events = POLLIN}, 0);
to be able to say whether new data has appeared at the end of the file.
This is not the case, and poll() is only meaningful as
"will a read or a write sleep": regular files and block devices are
always ready to return an empty read in this case, for example,
and you need to use inotify to achieve this.
Under Linux this is governed by DEFAULT_POLLMASK
(EPOLLIN | EPOLLOUT | EPOLLRDNORM | EPOLLWRNORM)
being returned if no explicit poll operation is defined for the file.
As contrast, unpollables like the above are refused by epoll_ctl(ADD).
I explicitly hit the two keywords I searched for (regular, block)
before just writing a test program to confirm that poll() behaved as
expected and is not a good fit for my use-case.
This behaviour is guaranteed by POSIX (Issue 8 Draft 3):
51381 The poll( ) and ppoll( ) functions shall support regular files, terminal and pseudo-terminal
51382 devices, FIFOs, pipes, and sockets. The behavior of poll( ) and ppoll( ) on elements of fds that refer
51383 to other types of file is unspecified.
51384 Regular files shall always poll TRUE for reading and writing.
51385 A file descriptor for a socket that is listening for connections shall indicate that it is ready for
51386 reading, once connections are available. A file descriptor for a socket that is connecting
51387 asynchronously shall indicate that it is ready for writing, once a connection has been established.
On 6/18/23 22:05, Oskari Pirhonen wrote:
> On Sat, Jun 17, 2023 at 13:11:29 +0200, Helge Kreutzmann wrote:
>> Hello Alejandro,
>> On Sun, Mar 12, 2023 at 12:31:37AM +0100, Alejandro Colomar wrote:
>>> On 3/11/23 18:13, Helge Kreutzmann wrote:
>>>> Without further ado, the following was found:
>>>>
>>>> Issue: This is true only on x86 and Lilo is probably not much
>>>> used anymore; also systemd has its own (?) bootloader
>>
>> Lilo has just been removed from Debian, so to my knowledge only
>> Mageia ships it.
>>
>
> FWIW, Gentoo still has LILO in the repos. This doesn't change the
> fact that it probably does not see much use anymore. Definitely not
> enough to warrant being mentioned as "is often". Maybe a historical
> note, if anything.
Bruno Haible [Sun, 21 May 2023 11:05:29 +0000 (13:05 +0200)]
List a fifth condition when iconv(3) may stop.
The wording regarding transliteration is vague, because this man page is not
the right place for going into the details of the transliteration.
Here are the details:
GNU libc and GNU libiconv support transliteration, for example, of "½" to "1/2",
or of "å" to "aa" in a Danish locale. The transliteration maps a multibyte
character of the input encoding to zero or more characters in the output.
There are two kinds of transliteration rules:
- Those that are valid regardless of locale. Typically this means that the
original and the transliterated character have similar glyphs, such as
in the case "½" to "1/2".
In GNU libc, these are collected in the files
glibc/localedata/locales/translit_*.
- Those that are valid in a single locale only. Often such a rule
reflects similar pronounciation of the original and the transliterated
characters. Some locales have script-based transliteration, for example
from the Cyrillic script to the Latin script.
In GNU libc, these are collected in the file
glibc/localedata/locales/<locale>.
In GNU libiconv, transliterations of this kind are not supported.
наб [Tue, 23 May 2023 20:17:31 +0000 (22:17 +0200)]
putenv.3: Originated in SysVr2; in 4.3BSD-Reno; fixed on modern systems
Fixed in:
NetBSD 6 src lib/libc/stdlib/putenv.c 1.13
FreeBSD 7 putenv(3) says so
OpenBSD 4.6 src lib/libc/stdlib/setenv.c 1.10
and is correct under current(?) MacOS as well
The current wording implies that all of 4.4BSD's descenants also carry
this bug (at least it did to me): they did until like 2009 but they're
fine now
bash_aliases: Increase robustness of sed_rm_ccomments()
Thanks to perl(1), we can use a non-greedy match to remove several
C89-style comments in the same line. And by splitting (and slightly
modifying) the other sed(1) call, we can handle multi-line comments that
start in the same line that the previous one ends.
Now the only remaining issue is nested comments, but that's rare, so
let's ignore it for now.
$ cat com.c
/* let's see */ int foo/*how about here?*/; // meh
int bar; /* Let's see
how this
behaves */ int baz; /* like this?
like that! */ int qwe; // asdasd
$ sed_rm_ccomments <com.c
int foo;
int bar;
int baz;
int qwe;
open.2, prctl.2: SYNOPSIS: Document these as variadic functions
I remember I discussed this with Michael Kerrisk a long ago and we
agreed to apply this fix, as I felt that using overload syntax was
confusing (especially since C doesn't allow overloads), but then I
didn't feel urged to write a patch. Florian confirmed recently that
this is confusing to more programmers, so let's do it.
*.mk: Use -wbreak in TROFFFLAGS, and -ww in NROFFFLAGS
We don't need to see all warnings everywhere we call troff(1). Instead,
put all warnings in nroff mode, which we only run for the warnings, and
then only ask for warnings that depend on the output in other
invocations of troff(1).
-wbreak happens to enable only and all so-called "output warnings". It
is an implementation detail of groff(1), but that's the best we can do
now. If groff(1) changes their warnings organization, we'll need to
adapt to it.
sched_yield.2: Rename NOTES to CAVEATS, and reorder contents
Put the last paragraph at the top of the CAVEATS section, since it's
probably the most important for readers. This system call is likely not
the right one for most programs; let's discourage its use.
Link: <https://www.realworldtech.com/forum/?threadid=189711&curpostid=189752> Cc: Andrew Clayton <a.clayton@nginx.com> Signed-off-by: Alejandro Colomar <alx@nginx.com>
*.mk: build-catman-troff: Silence warnings about using UC
We have some pages that come from UCB, and therefore need that macro.
It's not like we're going to accidentally use that macro, so let's
ignore the warning.
*.mk: build-catman-troff: Silence warnings about blank lines in input
Ideally, we want this warning, but it has false positives in the example
programs, so let's disable it for now. Hopefully, groff will split
those two, and then we'll be able to re-enable the one we want.
*.mk: build-catman-troff: Silence warnings about missing fifth argument
This happens when the second argument is a subsection, and the warning
is right because the page ends up with no section title, but let's
forget about it for now.
Some projects don't store their source manual pages in a directory
structure resembling $MANPATH. Allow such a directory structure so that
we can for example lint groff's source manual pages:
There's no need; we can leave empty dirs on 'make uninstall', and it
allows some simplifications. We don't need the FORCE target anymore,
and don't need some directory variables either. While at it, I found
some unused variable that should have been removed a long time ago:
$installdirs_manX
Since make(1) uses ':' as a special character in rules, it needs to be
handled carefully. A way to make it work is to escape it with '\:'. We
can use sed(1) to do that right when we get the pathnames. The only
problem with ':' is in rules' targets and prerequisites: everywhere else
it's fine; so let's discuss what needs to be done in those places:
- In the targets, it's as easy as escaping.
- In prerequisites, we can't second-expand variables containing such
pathnames, as the '\' would not be used by make(1) to escape the ':',
but it would be interpreted as part of the pathname. This means we
need to expand rules written using second expansion into several
rules that only expand their variables once.
- $(wildcard ...) also performs the escape, so after using it the
pathnames are not escaped. If we used those variables in targets, we
would need to escape the ':'s again, but since we don't we can skip
that. The trick to make this work is to second-expand these
variables.
Link: <https://stackoverflow.com/a/76096683/6872717> Cc: GNU Make <bug-make@gnu.org> Signed-off-by: Alejandro Colomar <alx@kernel.org>
The @: dummy recipe was there to avoid having rules without recipes.
Rules without recipes can be confusing, as the reader can't know if a
recipe is being defined somewhere else. Also, implicit rules might
apply (in general, but we disable all implicit stuff).
However, @: is also problematic, since make really needs to run that
command, which is unnecessary overhead. But okay, :(1) (really called
true(1), but wouldn't it be a nice man page name?) that's not meaningful
overhead.
And the bigger problem: having a recipe hides the usual:
make: Nothing to be done for 'all'.
We already disable it by using .SILENCE:, but the message can be seen
when using V=1 (after this patch; prior to this patch, it was impossible
to find that message). It is good to be able to know that make(1)
says there's nothing to be done, as a confirmation.
We used it for transforming groff_man(7)'s CHECKSTYLE into errors, but
we already do that with grep(1). Moreover, the tmac was hiding
troff(1)'s warnings.
We don't have a recursive make, so this flag is not used. Moreover, if
ever, for some rare reason, make traverses directories, it would be good
to know.
Other directories in $builddir are created with $MKDIR, but since these
should be as if installed, it makes sense to use the same command as
when installing.
There are no race conditions, contrary to what some sources say.
Previously, we had each directory depend on its parent directory, so
that only a few parent-most directories would be created with parents,
and all others would be created when their parents exist. That was due
to FUD about TOCTOU race conditions with mkdir -p and parallel make, but
it was just FUD.
This patch makes it so that each directory is directly created with
parents without specifying any dependency. This simplifies the makefile
at some cost: calling mkdir -p so many times is a bit slower. However,
it's only about 5%, so we can live with it, since we're talking about
hundreds of a second for creating all the directories that this build
system knows about.
projects / thirdparty / man-pages.git / log
