Many pages: Document fixed-width types with ISO C namingman-pages-6.0-rc1
commit2294974b3a1341e457edb682c08c5f4b2d14675e
authorAlejandro Colomar <alx.manpages@gmail.com>
Sun, 21 Aug 2022 22:49:53 +0000 (22 00:49 +0200)
committerAlejandro Colomar <alx.manpages@gmail.com>
Wed, 24 Aug 2022 19:05:25 +0000 (24 21:05 +0200)
tree7181a411ecb3947c9e9d5a65f04a088e3699b88d
parente3ad11c9a4542c83324edf549e548767535cae63
Many pages: Document fixed-width types with ISO C naming

Kernel __u64 and similar types are ABI-compatible, and mostly
API-compatible with ISO C types.  User-space programmers don't
care about kernel details, and should only use libc types.
Document syscalls and structures provided by the Linux kernel as
if they used libc types.

There's work in the kernel to remove this small API
incompatibility, which is only for pointers or printf specifiers.

Since I couldn't find any structure that uses pointers, there
shouldn't be any issues here.  Also, the only pointer I found was
in a syscall parameter, but since syscall(2) doesn't check its
arguments' types, we're also safe there.

This patch doesn't go without controversy.  Check the discussions
in the links below.

Found with:

$ grep -rn '\b_*[su][8136][624]*\b' man* \
  | grep -v -e /bpf-helpers.7 -e /proc.5 -e /epoll_event.3type -e /wcscmp.3 \
            -e /crypt.3 -e /mempcpy.3 -e /memcmp.3 -e /string.3 -e /wcsncmp.3 \
            -e /wcscasecmp.3 -e /wmemcmp.3 -e /strcasecmp.3 -e /bcmp.3 \
            -e /bstring.3 -e /endian.3 -e /strverscmp.3 -e /wcsncasecmp.3 \
            -e /strcoll.3 -e /strcmp.3 \
  | tee /dev/tty \
  | wc -l;

Link: <https://lore.kernel.org/linux-man/20210423230609.13519-1-alx.manpages@gmail.com/T/>
Link: <https://lore.kernel.org/lkml/YZvIlz7J6vOEY+Xu@yuki/T/>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Nacked-by: Alexei Starovoitov <ast@kernel.org>
Nacked-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Nacked-by: Daniel Borkmann <daniel@iogearbox.net>
Acked-by: Zack Weinberg <zackw@panix.com>
Cc: LKML <linux-kernel@vger.kernel.org>
Cc: glibc <libc-alpha@sourceware.org>
Cc: GCC <gcc-patches@gcc.gnu.org>
Cc: bpf <bpf@vger.kernel.org>
Cc: LTP List <ltp@lists.linux.it>
Cc: Linux API <linux-api@vger.kernel.org>
Cc: linux-arch <linux-arch@vger.kernel.org>
Cc: David Laight <David.Laight@ACULAB.COM>
Cc: Joseph Myers <joseph@codesourcery.com>
Cc: Florian Weimer <fweimer@redhat.com>
Cc: Daniel Borkmann <daniel@iogearbox.net>
Cc: Cyril Hrubis <chrubis@suse.cz>
Cc: David Howells <dhowells@redhat.com>
Cc: Arnd Bergmann <arnd@arndb.de>
Cc: Florian Weimer <fweimer@redhat.com>
Cc: Rich Felker <dalias@libc.org>
Cc: Adhemerval Zanella <adhemerval.zanella@linaro.org>
31 files changed:
man2/bpf.2
man2/capget.2
man2/clone.2
man2/getunwind.2
man2/io_submit.2
man2/ioctl_ficlonerange.2
man2/ioctl_fideduperange.2
man2/ioctl_getfsmap.2
man2/ioctl_userfaultfd.2
man2/kcmp.2
man2/keyctl.2
man2/landlock_add_rule.2
man2/landlock_create_ruleset.2
man2/mount_setattr.2
man2/perf_event_open.2
man2/ptrace.2
man2/sched_setattr.2
man2/seccomp.2
man2/seccomp_unotify.2
man2/statx.2
man2/userfaultfd.2
man2type/open_how.2type
man3type/epoll_event.3type
man4/loop.4
man4/random.4
man7/fanotify.7
man7/netdevice.7
man7/netlink.7
man7/packet.7
man7/rtnetlink.7
man7/sock_diag.7