That note against using useconds_t if portability is important was
probably true before POSIX, but since POSIX specifies the type in
<sys/types.h>, as recently documented in useconds_t(3), the type
should be fine to use portably. Moreover, using it helps document
the code, so we better completely remove that warning.
aiocb-struct.3, lconv-struct.3, sigevent-struct.3, sigval-union.3, sockaddr-struct.3, timespec-struct.3, timeval-struct.3: Rename some links to system_data_types.7 to add -{struct,union} suffix
This avoids shadowing other pages, and clearly differentiates
function pages from type pages (both are in man3).
Do this for struct/union types, and not for typedefs. This makes
sense because typedefs in C are in the same namespace as function
identifiers, but struct and union (and enum) tags are in a
different one, and can have the same name as a function.
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com> Cc: G. Branden Robinson <g.branden.robinson@gmail.com>
packet.7: add description of zero protocol for socket
According to packet(7), whenever raw packet is created by
socket(), it's immediately running, meaning that internal
packet_rcv() handler will be triggered and socket buffer will
begin allocation of sk_buff until sk_rcvbuf limit is reached.
However, by examination of kernel's internal handler
packet_create() it looks that kernel handles case of zero protocol
in a special manner. When packet_create() is called with arg
protocol = 0, __register_prot_hook is not executed, meaning
running state is still 0 and most notably, packet handler is not
added to kernel list (vide dev_add_pack).
I found this behavior invaluable for solving a subtle issue. When
process creates raw packet socket to listen for (let's say) all
protocols, but limited to a single network interface, then while
this interface can set by bind, it may to be too late due to
preemption (e.g. if real-time scheduling is used) and/or high-rate
of packets on other interfaces, meaning that undesired packets
(any count) may be pulled into the socket buffer.
The idea is that protocol zero means no packets on receive and an
optional call to bind with nonzero sll_procol will act "as if" the
originating socket API was called with this (nonzero) protocol.
The call to bind(2) is optional. As an example, if user intends
to treat the socket as Tx-only, then bind(2) may be skipped.
Reported-by: Grzegorz Szpetkowski <gszpetkowski@gmail.com>
Link: linux-man@ <https://lore.kernel.org/linux-man/CAMW=dumhWDu6LdhaQCJMskA4yNRBtOHs4iyrG6TP7xRv28AVWA@mail.gmail.com/> Cowritten-by: Alejandro Colomar <alx.manpages@gmail.com> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by Grzegorz Szpetkowski <gszpetkowski@gmail.com>:
Kir Kolyshkin [Fri, 4 Feb 2022 21:00:21 +0000 (13:00 -0800)]
capabilities.7: improve internal references
Trying to make this man page easier to navigate.
Fix a few cases of "see above/below" without a specific reference to a
subsection by quoting the subsection name (making it easier to look it up).
Use the same formatting rule as used by some of the other existing
references, i.e. italicise it.
For uniformity, remove words such as "the subsection" and "under", using
"(see|described in) <subsection title> (above|below)" template.
Signed-off-by: Kir Kolyshkin <kolyshkin@gmail.com> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
swapon.2: CONFIG_DEVICE_PRIVATE decreases number of available swap files by 4
[Aleksander]:
I noticed that swapon docs are missing some newer information
about CONFIG_DEVICE_PRIVATE that decreases the number of available
swap files. When it comes to kernel versions that I used
<https://elixir.bootlin.com/linux/v5.14/source/include/linux/swap.h>
and
<https://elixir.bootlin.com/linux/v4.14/source/include/linux/swap.h>
to check when the changes were introduced.
Reported-by: Aleksander Baranowski <alex@euro-linux.com> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Simon Branch [Sat, 1 Jan 2022 22:55:23 +0000 (14:55 -0800)]
termios.3: Clarify ONLRET
While perusing various termios(3) and termios(4) manpages, I
noticed the following inconsistency for ONLRET. FreeBSD and
NetBSD say this:
If ONLRET is set, the NL character is assumed to do the
carriage-return function; the column pointer will be set to 0.
OpenBSD says this:
If ONLRET is set, NL also performs CR on output, and reset
current column to 0.
POSIX says this:
NL performs CR function.
The current Linux manpage says this (!):
Don't output CR.
Here's a snippet that demonstrates Linux's behavior (tl;dr it's
just like the other operating systems):
$ stty -icanon -onlcr -icrnl -echo onlret onocr; cat
this is some text (^J pressed)
and some more (^M pressed before additional text)
The first flags (-icanon -onlcr -icrnl -echo), combined with cat,
ensure that our keys are sent directly back to the terminal
emulator without any translation or buffering. The last two
(ONLRET and ONOCR) are the important ones: ONLRET makes Linux
think that the cursor is at column 0 after the ^J, and ONOCR makes
Linux ignore the following ^M.
наб [Mon, 24 Jan 2022 22:43:17 +0000 (23:43 +0100)]
strsep.3: port strtok(3) example
Each time I use strsep I want something like this;
this serves to snappily highlight the programming model,
esp. in contrast to strtok_r ‒ I elided the long
(and, frankly, gratuitous, even there) argv explanation
‒ if you need it, you can read the original
(or the usage string, or the seven-line main)
Based on OpenBSD's and FreeBSD's sysexits(3) manual pages,
and on the <sysexits.h> file itself.
Relevant differences from those manual pages:
- Rewritten using man(7) macros.
- Since this documents a header file (similar to <limits.h>), use
section 0, as the man-pages-posix project does (limits.h(0p)).
- Remove a statement that these error codes are non-portable
and should not be used. Instead, it's more clarifying to say
that these are not in POSIX, but are on the BSDs. Let users
decide what to do based on that. Probably, it's portable enough
these days.
наб [Tue, 11 Jan 2022 18:28:27 +0000 (19:28 +0100)]
glob.3: srcfix
For consistency: this is the only non-false-positive for ", and",
which now reads:
$ git grep '", and"'
man2/ioctl_tty.2:.BR "#include <termios.h>" " /* Definition of " CLOCAL ", and"
наб [Mon, 10 Jan 2022 18:53:42 +0000 (19:53 +0100)]
personality.2: WHOLE_SECONDS never did anything
git log -SWHOLE_SECONDS on a unified pre-2.6 linux repository
reveals the following three releases:
Author: Andrew Morton <akpm@osdl.org>
Date: Sun Aug 31 04:30:04 2003 -0700
- Christoph Hellwig: clean up personality handling a bit
- Robert Love: update sysctl/vm documentation
- make the three-argument (that everybody hates) "min()" be "min_t()",
and introduce a type-anal "min()" that complains about arguments of
different types.
1.1.14 adds personality.h:
diff --git a/include/linux/personality.h b/include/linux/personality.h
new file mode 100644
index 0000000000..714a5a66b5
--- /dev/null
+++ b/include/linux/personality.h
@@ -0,0 +1,12 @@
+/* Flags for bug emulation. These occupy the top three bytes. */
+#define STICKY_TIMEOUTS 0x8000000
+#define WHOLE_SECONDS 0x4000000
+
+/* Personality types. These go in the low byte. */
+#define PER_MASK (0x00ff)
+#define PER_LINUX (0x0000)
+#define PER_SVR4 (0x0001 | STICKY_TIMEOUTS)
+#define PER_SVR3 (0x0002 | STICKY_TIMEOUTS)
+#define PER_SCOSVR3 (0x0003 | STICKY_TIMEOUTS | WHOLE_SECONDS)
+#define PER_WYSEV386 (0x0004 | STICKY_TIMEOUTS)
+#define PER_ISCR4 (0x0005 | STICKY_TIMEOUTS)
2.4.9.8 shuffles it around with no substantial changes
(hunk enhanced to show texture):
diff --git a/include/linux/personality.h b/include/linux/personality.h
index 58cab509e3..230d394603 100644
--- a/include/linux/personality.h
+++ b/include/linux/personality.h
@@ -1,68 +1,126 @@
-/* Flags for bug emulation. These occupy the top three bytes. */
-#define STICKY_TIMEOUTS 0x4000000
-#define WHOLE_SECONDS 0x2000000
-#define ADDR_LIMIT_32BIT 0x0800000
-/* Personality types. These go in the low byte. Avoid using the top bit,
- * it will conflict with error returns.
+/*
+ * Flags for bug emulation.
+ *
+ * These occupy the top three bytes.
*/
-#define PER_MASK (0x00ff)
-#define PER_LINUX (0x0000)
-#define PER_LINUX_32BIT (0x0000 | ADDR_LIMIT_32BIT)
-#define PER_SVR4 (0x0001 | STICKY_TIMEOUTS)
-#define PER_SVR3 (0x0002 | STICKY_TIMEOUTS)
-#define PER_SCOSVR3 (0x0003 | STICKY_TIMEOUTS | WHOLE_SECONDS)
-#define PER_WYSEV386 (0x0004 | STICKY_TIMEOUTS)
-#define PER_ISCR4 (0x0005 | STICKY_TIMEOUTS)
-#define PER_BSD (0x0006)
-#define PER_SUNOS (PER_BSD | STICKY_TIMEOUTS)
-#define PER_XENIX (0x0007 | STICKY_TIMEOUTS)
-#define PER_LINUX32 (0x0008)
-#define PER_IRIX32 (0x0009 | STICKY_TIMEOUTS) /* IRIX5 32-bit */
-#define PER_IRIXN32 (0x000a | STICKY_TIMEOUTS) /* IRIX6 new 32-bit */
-#define PER_IRIX64 (0x000b | STICKY_TIMEOUTS) /* IRIX6 64-bit */
-#define PER_RISCOS (0x000c)
-#define PER_SOLARIS (0x000d | STICKY_TIMEOUTS)
-
-/* Description of an execution domain - personality range supported,
- * lcall7 syscall handler, start up / shut down functions etc.
- * N.B. The name and lcall7 handler must be where they are since the
- * offset of the handler is hard coded in kernel/sys_call.S.
+enum {
+ MMAP_PAGE_ZERO = 0x0100000,
+ ADDR_LIMIT_32BIT = 0x0800000,
+ SHORT_INODE = 0x1000000,
+ WHOLE_SECONDS = 0x2000000,
+ STICKY_TIMEOUTS = 0x4000000,
+};
+
+/*
+ * Personality types.
+ *
+ * These go in the low byte. Avoid using the top bit, it will
+ * conflict with error returns.
+ */
+enum {
+ PER_LINUX = 0x0000,
+ PER_LINUX_32BIT = 0x0000 | ADDR_LIMIT_32BIT,
+ PER_SVR4 = 0x0001 | STICKY_TIMEOUTS | MMAP_PAGE_ZERO,
+ PER_SVR3 = 0x0002 | STICKY_TIMEOUTS | SHORT_INODE,
+ PER_SCOSVR3 = 0x0003 | STICKY_TIMEOUTS |
+ WHOLE_SECONDS | SHORT_INODE,
+ PER_OSR5 = 0x0003 | STICKY_TIMEOUTS | WHOLE_SECONDS,
+ PER_WYSEV386 = 0x0004 | STICKY_TIMEOUTS | SHORT_INODE,
+ PER_ISCR4 = 0x0005 | STICKY_TIMEOUTS,
+ PER_BSD = 0x0006,
+ PER_SUNOS = 0x0006 | STICKY_TIMEOUTS,
+ PER_XENIX = 0x0007 | STICKY_TIMEOUTS | SHORT_INODE,
+ PER_LINUX32 = 0x0008,
+ PER_IRIX32 = 0x0009 | STICKY_TIMEOUTS,/* IRIX5 32-bit */
+ PER_IRIXN32 = 0x000a | STICKY_TIMEOUTS,/* IRIX6 new 32-bit */
+ PER_IRIX64 = 0x000b | STICKY_TIMEOUTS,/* IRIX6 64-bit */
+ PER_RISCOS = 0x000c,
+ PER_SOLARIS = 0x000d | STICKY_TIMEOUTS,
+ PER_UW7 = 0x000e | STICKY_TIMEOUTS | MMAP_PAGE_ZERO,
+ PER_UW7 = 0x000e | STICKY_TIMEOUTS | MMAP_PAGE_ZERO,
+ PER_MASK = 0x00ff,
+};
And the ABI doc creates Documentation/sysctl/abi.txt, noting
+defhandler_coff:
+defined value :
+PER_SCOSVR3
+0x0003 | STICKY_TIMEOUTS | WHOLE_SECONDS | SHORT_INODE
The same log of mainline reveals, apart from the original 2.6.12-rc2
import:
1. 607ca46e97a1b6594b29647d98a32d545c24bdff ("UAPI: (Scripted)
Disintegrate include/linux") ‒ include/linux/{=> uapi/}personality.h
2. 53b9537509654a6267c3f56b4d2e7409b9089686 ("docs: sysctl: convert to
ReST") ‒ Documentation/sysctl/abi.{rst => txt}
3. 9f35cf8bd7e3347b0679c3f9b5e0bc5493925a1f ("docs: rewrite
admin-guide/sysctl/abi.rst") ‒ rewrites
Documentation/admin-guide/sysctl/abi.rst entirely, removing all
personality bits ("all the existing entries are no longer present,
so this removes them;")
Stephen Kitt [Sat, 8 Jan 2022 15:43:04 +0000 (16:43 +0100)]
strtok.3: Fix j/str1 declaration
for (int j = 1, str1 = argv[1]; ...
declares two variables of type int, j and str1; the pre-existing
char * str1 isn't used. This causes compiler warnings. Declaring j
outside the loop fixes everything.
Signed-off-by: Stephen Kitt <steve@sk2.org> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Stephen Kitt [Sat, 8 Jan 2022 15:43:03 +0000 (16:43 +0100)]
pkeys.7: Rely on the glibc implementations
glibc 2.27 added implementations of pkey_set(), pkey_mprotect(),
pkey_alloc(), and pkey_free(); rely on those instead of defining them
in the example. wrpkru() is only used in pkey_set() and can be removed
too (it's the internal-use-only pkey_write() in glibc).
Signed-off-by: Stephen Kitt <steve@sk2.org> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Stephen Kitt [Sat, 8 Jan 2022 15:43:02 +0000 (16:43 +0100)]
pkeys.7: Update the example to match glibc
glibc 2.27 introduced support for the pkeys functions, but the glibc
versions don't match those declared in the example. Update the example
to match glibc, and avoid declaring the functions if glibc is new
enough.
Signed-off-by: Stephen Kitt <steve@sk2.org> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Stephen Kitt [Fri, 7 Jan 2022 16:46:18 +0000 (17:46 +0100)]
newlocale.3: Use LC_GLOBAL_LOCALE, not ..._HANDLE
LC_GLOBAL_HANDLE has never existed; the locale object handle to use to
refer to the global locale determined by setlocale(3) is
LC_GLOBAL_LOCALE. See uselocale(3) for details.
[Jakub]:
$ cc -Wall newlocale-example.c
newlocale-example.c: In function 'main':
newlocale-example.c:67:15: error: 'LC_GLOBAL_HANDLE' undeclared (first use in this function); did you mean 'LC_GLOBAL_LOCALE'?
67 | uselocale(LC_GLOBAL_HANDLE); /* So 'loc' is no longer in use */
| ^~~~~~~~~~~~~~~~
| LC_GLOBAL_LOCALE
newlocale-example.c:67:15: note: each undeclared identifier is reported only once for each function it appears in
Signed-off-by: Stephen Kitt <steve@sk2.org> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com> Cc: Jakub Wilk <jwilk@jwilk.net>
Stephen Kitt [Fri, 7 Jan 2022 16:46:14 +0000 (17:46 +0100)]
seccomp.2: Use syscall() in the example code
Since seccomp() doesn't exist in glibc, avoid relying on it, and use
syscall() instead. This updates the example program to match the
documentation, which was updated in commit 5945cd7bd3c3 ("seccomp.2:
Use syscall(SYS_...); for system calls without a wrapper").
Signed-off-by: Stephen Kitt <steve@sk2.org> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
наб [Mon, 6 Dec 2021 23:31:38 +0000 (00:31 +0100)]
system_data_types.7: note struct timespec::tv_nsec type for x32 and portability
There are three files that govern userspace struct timespec on glibc:
1. bits/wordsize.h, defining:
(a) __WORDSIZE to 32 on ILP32 and 64 on LP64
(b) on x32: __SYSCALL_WORDSIZE to 64
2. bits/timesize.h, defining
(a) __TIMESIZE to __WORDSIZE, except on x32 where it's 64
3. bits/types/struct_timespec.h, declaring struct timespec as:
struct timespec
{
__time_t tv_sec; /* Seconds. */
#if __WORDSIZE == 64 \
|| (defined __SYSCALL_WORDSIZE && __SYSCALL_WORDSIZE == 64) \
|| __TIMESIZE == 32
__syscall_slong_t tv_nsec; /* Nanoseconds. */
#else
# if __BYTE_ORDER == __BIG_ENDIAN
int: 32; /* Padding. */
long int tv_nsec; /* Nanoseconds. */
# else
long int tv_nsec; /* Nanoseconds. */
int: 32; /* Padding. */
# endif
#endif
};
this has two side-effects: struct timespec
(a) is always sizeof==time_t+8, and
(b) has tv_nsec as __syscall_slong_t
*and* !is_same<__syscall_slong_t, long>
if using LP64 syscalls on an ILP32 system, i.e. on x32.
This means, that the simplified
struct timespec {
time_t tv_sec; /* Seconds */
long tv_nsec; /* Nanoseconds [0 .. 999999999] */
};
declaration is *invalid* for x32,
where struct timespec::tv_nsec is an int64_t (long long).
If a file/directory has the immutable flag set, access/faccessat
will return EPERM if write access is requested. This is not
currently documented, presumably because it is Linux-specific
(though BSD has similar behavior that is documented). Perhaps
something like the following in the ERRORS section.
EPERM Write permission was requested and pathname has the
immutable flag set. (See also ioctl_iflags(2).)
Also perhaps add ioctl_iflags(2) to the SEE ALSO section.
This came up in reference to:
<https://github.com/sudo-project/sudo/issues/122>
Reported-by: "Todd C. Miller" <Todd.Miller@sudo.ws> Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Jann Horn [Wed, 8 Dec 2021 23:44:33 +0000 (00:44 +0100)]
kcmp.2: still depends on kconfig
The manpage claims that kcmp() is now available unconditionally. That's
not true; from kernel/Makefile:
obj-$(CONFIG_KCMP) += kcmp.o
This new Kconfig flag is forced on by CONFIG_CHECKPOINT_RESTORE as
before, but also by CONFIG_DRM, which means that pretty much any kernel
built to support desktop systems will implicitly have it available.
But if you compiled some kind of server/embedded kernel without DRM and
without CHECKPOINT_RESTORE, you'd have to flip on the expert config
option to get KCMP.
Yang Xu [Tue, 23 Nov 2021 00:59:09 +0000 (08:59 +0800)]
init_module.2: Add ETXTBSY error for finit_module
Since kernel commit[1], finit_module fails with ETXTBSY error if fd has write permission.
Since kernel commit[2], finit_module fails with EBADF error if fd doesn't have read permission.
So we can use read-write permission to trigger ETXTBSY error all the time since linux 4.7.
Elliott Hughes [Tue, 9 Nov 2021 22:20:32 +0000 (14:20 -0800)]
pthread_atfork.3: wfix.
Clarify that the pthread_atfork() callback list is a global, not
per-thread.
The use of "this thread" implied to some readers that pthread_atfork()
maintained per-thread lists of callbacks. Given that the next sentence
already explains that the callbacks are run in the context of the thread
that calls fork(), I actually think it would be fine not to mention
threads at all in the earlier sentence, but for now I've gone with what
I think was intended to be written.
This patch also attempts to clarify other references to "thread",
and fixes a trivial typo "form" instead of "fork".
projects / thirdparty / man-pages.git / log
