Commit Graph

21990 Commits

Author SHA1 Message Date
Michael Kerrisk c7db92b96a Various pages: Use .nf/.fi in SYNOPSIS
The majority of pages use .nf/.fi in SYNOPSIS, but there are
still many that don't and use .br to achieve newlines. Fix many
of those. This brings greater consistency to the pages, which
eases editing and may ease future scripted edits to the pages.

Many of these changes were script-assisted, with some additional
manual edits.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2021-01-03 13:09:47 +01:00
Michael Kerrisk 511bb71b0c Various pages: Further clean-ups after "bring more whitespace consistency in SYNOPSIS"
Yet more clean-ups after commit
15d6565317.

Reported-by: Alejandro Colomar (man-pages) <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2021-01-03 13:09:36 +01:00
Michael Kerrisk ff21c173ea wordexp.3: ffix
Reported-by: "Alejandro Colomar" <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2021-01-02 20:57:59 +01:00
Michael Kerrisk c9eec92c18 getcpu.2: Rewrite page to describe glibc wrapper function
Since glibc 2.29, there is a wrapper for getcpu(2).
The wrapper has only 2 arguments, omitting the unused
third system call argument. Rework the manual page
to reflect this.

Reported-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2021-01-02 09:37:11 +01:00
Alejandro Colomar 771aecbeff Various pages: Consistently use 'unsigned int'
Most pages use 'unsigned int' (and the kernel too).
Make them all do so.

$ find man? -type f \
  | xargs sed -i \
	-e 's/unsigned \*/unsigned int */g'
	-e 's/unsigned "/unsigned int "/g';

Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2021-01-02 08:31:43 +01:00
Michael Kerrisk e878a2de3e get_phys_pages.3: Minor relocation of text
Reported-by: Alejandro Colomar (man-pages) <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2021-01-01 23:38:00 +01:00
Alejandro Colomar 984126f454 off64_t.3: New link to system_data_types(7)
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2021-01-01 23:31:50 +01:00
Alejandro Colomar d6ab4c76a1 system_data_types.7: Add off64_t to system_data_types(7)
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2021-01-01 23:30:49 +01:00
Michael Kerrisk 7b5d39f48f Various pages: clean-ups after "bring more whitespace consistency in SYNOPSIS"
Cleann-ups after commit 15d6565317.

Reported-by: Alejandro Colomar (man-pages) <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2021-01-01 23:28:14 +01:00
Michael Kerrisk 15d6565317 Various pages: bring more whitespace consistency in SYNOPSIS
The use of vertical white space in the SYNOPSIS sections
is rather inconsistent. Make it more consistent, subject to the
following heuristics:

* Prefer no blank lines between function signatures by default.
* Where many functions are defined in the SYNOPSIS, add blank
  lines where needed to improve readability, possibly by using
  blank lines to separate logical groups of functions.

Reported-by: Alejandro Colomar (man-pages) <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2021-01-01 12:40:22 +01:00
Michael Kerrisk 742694e926 gethostbyname.3: Move mention of <sys/socket.h> from SYNOPSIS to DESCRIPTION
The functions are all declared in <netdb.h>. <sys/socket.h> is only
needed for the AF_* constants.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2021-01-01 12:26:47 +01:00
Michael Kerrisk 460aeeb46d puts.3: Reorder functions more logically (group related fuinctions together)
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-12-31 23:38:02 +01:00
Michael Kerrisk cbd813e73c getdirentries.3: tfix
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-12-31 22:50:57 +01:00
Michael Kerrisk d4f9c56ac5 drand48.3: tfix (Oxford comma)
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-12-31 21:19:28 +01:00
Michael Kerrisk 1210ac324b dl_iterate_phdr.3: wsppfix
Reported-by: Alejandro Colomar (man-pages) <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-12-31 21:16:41 +01:00
Michael Kerrisk fb30841679 perfmonctl.2, pidfd_send_signal.2: ffix: Ensure statement about no wrapper function is a new paragraph
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-12-31 15:13:41 +01:00
Alejandro Colomar 76c5631fb4 copy_file_range.2: Document glibc wrapper instead of kernel syscall
Glibc uses 'off64_t' instead of 'loff_t'.

......

Glibc prototype:

$ syscall='copy_file_range';
$ ret='ssize_t';
$ find glibc/ -type f -name '*.h' \
  |xargs pcregrep -Mn "(?s)^[\w\s]*${ret}\s*${syscall}\s*\(.*?;";
glibc/posix/unistd.h:1121:
ssize_t copy_file_range (int __infd, __off64_t *__pinoff,
			 int __outfd, __off64_t *__poutoff,
			 size_t __length, unsigned int __flags);

......

Testing example:

$ man ./man2/copy_file_range.2 \
  |sed -n '/^EXAMPLES/,/^SEE ALSO/p' \
  |head -n -1 \
  |tail -n +2 \
  >copy_file_range.c
$ gcc -Wall -Wextra -Werror -pedantic
copy_file_range.c -o copy_file_range
$ ./copy_file_range
Usage: ./copy_file_range <source> <destination>
$ tee a >/dev/null
asdf
$ tee b >/dev/null
qwerty
zxcvbn
$ ./copy_file_range a b
$ cat a
asdf
$ cat b
asdf

Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-12-31 15:01:18 +01:00
Michael Kerrisk 9834f61da2 wait4.2, endian.3, isalpha.3, unlocked_stdio.3: Minor consistency fix for Feature Test Macro info
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-12-31 11:05:26 +01:00
Michael Kerrisk ea40ab1199 strsignal.3: ffix
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-12-31 11:05:26 +01:00
Michael Kerrisk 7d8d2f0941 Various pages: s/Glibc versions </Glibc </ in Feature Test Macro discussions
Use a more compact notation that will render less wide
on the terminal.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-12-31 11:05:22 +01:00
Michael Kerrisk 38c1dbe910 pread.2, rename.2, syscall.2, utimensat.2, gethostid.3, rcmd.3, seekdir.3, setnetgrent.3, strerror.3, strsignal.3: ffix: Various tweaks for greater consistency in Feature Test Macros
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-12-31 10:48:51 +01:00
Michael Kerrisk 0129eef26c chown.2, ffs.3, fpclassify.3, gamma.3, getgrent.3, ilogb.3, strdup.3: ffix
Bring a bit more consistency to Feature Test Macro information
(mainly .PP between differnt FTM lists).

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-12-31 10:27:24 +01:00
Michael Kerrisk 58e93595b9 Changes.old: tfix
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-12-31 10:07:18 +01:00
Michael Kerrisk 98c9347c15 Various pages: Formatting fix
Use .PP (which gives a bit of vertical white space) rather than
.br to separate functions in Feature Test Macro requirement lists.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-12-31 09:55:48 +01:00
Michael Kerrisk 1faebd253c Various pages: srcfix: remove redundant .br
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-12-31 09:55:48 +01:00
Michael Kerrisk e111e485ed recv.2: srcfix
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-12-31 09:24:56 +01:00
Alejandro Colomar a6f73f75e6 get_phys_pages.3: glibc gets the info from sysinfo(2) since 2.23
See glibc's commit: 0ce657c576bf1b24
https://sourceware.org/git/?p=glibc.git;a=commitdiff;h=0ce657c576bf1b24

Reported-by: Jakub Wilk <jwilk@jwilk.net>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-12-31 09:18:04 +01:00
Alejandro Colomar 00d3eabb53 keyctl.2: SYNOPSIS: Fix prototype parameter types
The Linux kernel uses 'unsigned long'.
There's no reason to use the typedef '__kernel_ulong_t'.

......

$ syscall='keyctl';
$ find linux/ -type f -name '*.c' \
  |xargs pcregrep -Mn "(?s)^[\w_]*SYSCALL_DEFINE.\(${syscall},.*?\)";
linux/security/keys/keyctl.c:1869:
SYSCALL_DEFINE5(keyctl, int, option, unsigned long, arg2, unsigned long, arg3,
		unsigned long, arg4, unsigned long, arg5)
linux/security/keys/compat.c:17:
COMPAT_SYSCALL_DEFINE5(keyctl, u32, option,
		       u32, arg2, u32, arg3, u32, arg4, u32, arg5)

Cc: Eugene Syromyatnikov <evgsyr@gmail.com>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-12-30 23:37:05 +01:00
Alejandro Colomar 7eee650211 delete_module.2: SYNOPSIS: Fix prototype parameter types
The Linux kernel uses 'unsigned int' instead of 'int' for the
'flags' parameter.  As glibc provides no wrapper, use the same
type the kernel uses.

......

$ syscall='delete_module';
$ find linux/ -type f -name '*.c' \
  |xargs pcregrep -Mn "(?s)^[\w_]*SYSCALL_DEFINE.\(${syscall},.*?\)";
linux/kernel/module.c:977:
SYSCALL_DEFINE2(delete_module, const char __user *, name_user,
		unsigned int, flags)

Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-12-30 23:35:35 +01:00
Michael Kerrisk 40c502d623 kexec_load.2: wfix
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-12-30 17:02:42 +01:00
Ganimedes Colomar 16cc03ca92 Various pages: Normalize NOTES about nonexistent glibc wrappers
See previous commit.

This commit normalizes texts under sections other than SYNOPSIS
(most of them in NOTES).

Signed-off-by: Ganimedes Colomar <gacoan.linux@gmail.com>
Cowritten-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-12-30 16:56:38 +01:00
Ganimedes Colomar 632d115294 Various pages: Normalize SYNOPSIS notes about nonexistent glibc wrappers
To easily distinguish documentation about glibc wrappers from
documentation about kernel syscalls, let's have a normalized
'Note' in the SYNOPSIS, and a further explanation in the page body
(NOTES in most of them), as already happened in many (but not all)
of the manual pages for syscalls without a wrapper.  Furthermore,
let's normalize the messages, following membarrier.2 (because it's
already quite extended), so that it's easy to use grep to find
those pages.

To find these pages, we used:
$ grep -rn wrapper man? | sort -V
and
$ grep -rni support.*glibc | sort -V

delete_module.2, init_module.2:  glibc 2.23 is no longer
  maintained, so we changed the notes about wrappers, to say that
  there are no glibc wrappers for these system calls; see NOTES.

We didn't fix some obsolete pages such as create_module.2.

Signed-off-by: Ganimedes Colomar <gacoan.linux@gmail.com>
Cowritten-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-12-30 16:55:39 +01:00
Michael Kerrisk 3c8813156d syscalls.2: Add epoll_pwait2()
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-12-30 15:18:54 +01:00
Michael Kerrisk ab4001e286 readlink.2: Emphasize that the returned buffer is not null-terminated
Reported-by: Jonny Grant <jg@jguk.org>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-12-30 14:55:38 +01:00
Jakub Wilk 5bd94cbd31 filesystems.5: tfix
Signed-off-by: Jakub Wilk <jwilk@jwilk.net>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-12-30 09:30:34 +01:00
Jakub Wilk 704b5ab54c ftime.3: tfix
Signed-off-by: Jakub Wilk <jwilk@jwilk.net>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-12-30 09:30:17 +01:00
Jakub Wilk 6a0aa2ecb1 cgroups.7: tfix
Signed-off-by: Jakub Wilk <jwilk@jwilk.net>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-12-30 09:30:10 +01:00
Jakub Wilk 0580884cc7 signal.7: tfix
Signed-off-by: Jakub Wilk <jwilk@jwilk.net>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-12-30 09:29:46 +01:00
Michael Kerrisk c55f66855e pkeys.7: srcfix: remove redundant .PP
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-12-27 12:40:30 +01:00
Michael Kerrisk c65f02bae3 user_namespaces.7: srcfix: remove redundant .PP after .SS
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-12-27 12:40:30 +01:00
Michael Kerrisk 312b0eb182 userfaultfd.2, posix_spawn.3: srcfix: remove redundant .PP
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-12-27 12:40:30 +01:00
Michael Kerrisk 0421538981 pthread_mutexattr_setrobust.3: wfix: remove redundant comments
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-12-27 12:40:30 +01:00
Michael Kerrisk ae12e0e0f9 bind.2: wfix: remove redundant comment
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-12-27 12:40:30 +01:00
Michael Kerrisk d5d83905a1 spu_run.2: Minor fix-ups for comments
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-12-27 12:40:30 +01:00
Michael Kerrisk a8114045ab fanotify.7, inotify.7: wfix: Tweak location of tag comments
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-12-27 12:40:25 +01:00
Michael Kerrisk 46b20ca1bb ioctl_ns.2, keyctl.2, memfd_create.2, pidfd_send_signal.2, poll.2, seccomp.2, signalfd.2, timerfd_create.2, unshare.2, dlinfo.3, duplocale.3, fopencookie.3, getgrouplist.3, getifaddrs.3, getprotoent_r.3, getservent_r.3, insque.3, printf.3, pthread_attr_init.3, pthread_cancel.3, pthread_create.3, pthread_mutexattr_setrobust.3, pthread_setaffinity_np.3, qsort.3, sem_wait.3, core.5, elf.5, aio.7, epoll.7, pkeys.7, system_data_types.7, unix.7: Use periods more consistently inside code comments
In general, complete sentences in free-standing comments
should be terminated by periods.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-12-27 12:32:44 +01:00
Michael Kerrisk c6beb8a167 bind.2, clone.2, dup.2, futex.2, mprotect.2, open_by_handle_at.2, pivot_root.2, select_tut.2, shmop.2, timer_create.2, userfaultfd.2, getaddrinfo.3, getaddrinfo_a.3, inet_net_pton.3, malloc_info.3, mbstowcs.3, newlocale.3, posix_spawn.3, pthread_sigmask.3, shm_open.3, strtol.3, inotify.7, user_namespaces.7: Add periods at end of sentences in comments
Try to bring a little more consistency on the use of periods
in comments in example code.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-12-27 12:32:44 +01:00
Michael Kerrisk f18f9c4095 man-pages.7: Add some notes on comments in example code
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-12-27 12:32:44 +01:00
Michael Kerrisk 1297239d41 slist.3: tfix
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-12-23 14:24:43 +01:00
Michael Kerrisk c5127de6ff stailq.3: ffix
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-12-23 14:23:39 +01:00