Commit Graph

8820 Commits

Author SHA1 Message Date
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 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 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 c2e81ff964 seccomp.2, circleq.3, list.3, malloc_hook.3, slist.3, stailq.3, tailq.3, ip.7, unix.7: tfix
Remove "." at the end of sentence fragments/short single sentences
in comments.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-12-23 14:17:30 +01:00
Alejandro Colomar eaa18d3c44 Various pages: Remove explicit blank lines, replacing them with .PP when appropriate
Rationale:
$ man 7 man-pages 2>/dev/null | sed -n /Paragraphs/,/^$/p
       Paragraphs should be separated by suitable markers (usually
       either .PP or .IP).  Do not separate paragraphs using blank
       lines,  as  this  results  in poor rendering in some output
       formats (such as PostScript and PDF).

Fix:
$ sed -i -e '1,/^\.EX/s/^$/.PP/' -e '/^\.EE/,/^\.EX/s/^$/.PP/' man?/*

And then some manual adjustments.

Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-12-23 13:19:10 +01:00
Peter H. Froehlich 4fce5f5bc8 syscall.2: Update superh syscall convention
I noticed this while working on some silly "hello, world"
programs, see https://git.sr.ht/~phf/hello-again if you're
curious.  Disassembling sh4 code showed trap #31 all over the
place but the syscall(2) man page talked about trap #0x17 and
friends. Checking the kernel sources I got lucky in
arch/sh/kernel/entry-common.S where in commit 3623d138213ae Rich
Felker clarifies the situation.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-12-22 18:14:37 +01:00
Michael Kerrisk c751bb1e0f getrusage.2: Starting in 2.33, glibc no longer provides vtimes()
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-12-22 12:01:31 +01:00
Michael Kerrisk 88a3ec7921 setns.2: tfix
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-12-22 12:00:09 +01:00
Michael Kerrisk ee2379ef31 perf_event_open.2: wfix
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-12-22 12:00:09 +01:00
Michael Kerrisk ff9469c09c statfs.2: tfix (Section number)
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-12-22 12:00:09 +01:00
Michael Kerrisk 9f43659f85 getent.1, access.2, cacheflush.2, chroot.2, clock_getres.2, fcntl.2, getrusage.2, io_cancel.2, io_destroy.2, io_getevents.2, io_setup.2, io_submit.2, link.2, llseek.2, mmap.2, mount.2, readv.2, restart_syscall.2, semctl.2, set_mempolicy.2, set_tid_address.2, shmctl.2, sigaction.2, sigaltstack.2, spu_create.2, statfs.2, subpage_prot.2, syscalls.2, timer_getoverrun.2, uselib.2, INFINITY.3, __ppc_set_ppr_med.3, bstring.3, btree.3, ctime.3, fgetc.3, fopen.3, getcontext.3, gethostbyname.3, getnetent.3, getprotoent.3, getservent.3, inet.3, j0.3, list.3, makecontext.3, nextafter.3, posix_memalign.3, profil.3, pthread_tryjoin_np.3, puts.3, rcmd.3, resolver.3, rtime.3, sigsetops.3, strnlen.3, tailq.3, elf.5, filesystems.5, nscd.conf.5, proc.5, utmp.5, attributes.7, ipv6.7, packet.7, pthreads.7, signal-safety.7, signal.7, spufs.7, system_data_types.7, tcp.7: tstamp
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-12-21 16:19:35 +01:00
Michael Kerrisk adce9485ce cacheflush.2: ffix
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-12-20 21:52:42 +01:00
Alejandro Colomar 08811c1418 cacheflush.2: Document Architecture-specific variants
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-12-20 21:49:49 +01:00
Alejandro Colomar d7e7ab0e34 cacheflush.2: Document __builtin___clear_cache() as a more portable alternative
Reported-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Cc: Martin Sebor <msebor@redhat.com>
Cc: Dave Martin <Dave.Martin@arm.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-12-20 21:47:43 +01:00
Michael Kerrisk ab949f50af setns.2: ffix
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-12-20 11:54:31 +01:00
Michael Kerrisk 300ef55cf2 perf_event_open.2: tfix
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-12-16 15:51:34 +01:00
Arusekk e2e73b468a keyctl.2: tfix
Fixes: fa76da808e

Signed-off-by: Arusekk <arek_koz@o2.pl>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-12-01 20:46:58 +01:00
Alejandro Colomar e115d825c3 subpage_prot.2: SYNOPSIS: Fix return type: s/long/int/
The Linux kernel uses 'int' instead of 'long' for the return type.
As glibc provides no wrapper, use the same type the kernel uses.

......

$ grep -n wrapper man-pages/man2/subpage_prot.2
40:There is no glibc wrapper for this system call; see NOTES.
99:Glibc does not provide a wrapper for this system call; call it using

$ grep -rn SYSCALL_DEFINE.*subpage_prot linux/;
linux/arch/powerpc/mm/book3s64/subpage_prot.c:190:
SYSCALL_DEFINE3(subpage_prot, unsigned long, addr,

$ sed -n /SYSCALL.*subpage_prot/,/^}/p \
  linux/arch/powerpc/mm/book3s64/subpage_prot.c \
  |grep return;
		return -ENOENT;
		return -EINVAL;
		return -EINVAL;
		return 0;
		return -EFAULT;
			return -EFAULT;
	return err;

$ sed -n /SYSCALL.*subpage_prot/,/^}/p \
  linux/arch/powerpc/mm/book3s64/subpage_prot.c \
  |grep '\<err\>';
	int err;
			err = -ENOMEM;
		err = -ENOMEM;
	err = 0;
	return err;

Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-11-28 09:56:37 +01:00
Michael Kerrisk c8efc05e6a spu_create.2: Clarify that spu_create() now has 4 arguments but once had only 3
Reported-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-11-27 11:15:14 +01:00
Michael Kerrisk c15912550f spu_create.2: Relocate paragraph on 'mode' argument
This paragraph is a little bit hidden at the end of DESCRIPTION;
make it a little more prominent.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-11-27 11:05:44 +01:00
Michael Kerrisk 42c7a19c5f spu_create.2: Add kernel version numbers for SPU_CREATE_AFFINITY_SPU/_MEM
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-11-27 11:04:02 +01:00
Michael Kerrisk 7be45add14 spu_run.2: srcfix
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-11-27 10:05:38 +01:00
Michael Kerrisk 61d6b66a58 getpriority.2: wfix
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-11-27 09:29:12 +01:00
Michael Kerrisk fe2764329d getpriority.2: ffix
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-11-27 09:28:11 +01:00
Michael Kerrisk 373a3de56d link.2: ffix
Reported-by: Alejandro Colomar (man-pages) <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-11-26 13:52:15 +01:00
Mathias Rav 336be2e745 link.2: ERRORS: add ENOENT when target is deleted
Linux kernel commit aae8a97d3ec30788790d1720b71d76fd8eb44b73 (part
of kernel release v2.6.39) added a check to disallow creating a
hardlink to an unlinked file.

The manual page already describes the trick of using
AT_SYMLINK_FOLLOW as an alternative to AT_EMPTY_PATH, and for
AT_EMPTY_PATH the manual page already notes that it "will
generally not work if the file has a link count of zero". However,
the precise error (ENOENT) is not mentioned, and the error case
isn't mentioned in the ERRORS section at all.

This makes it easy to overlook the fact that the AT_SYMLINK_FOLLOW
trick on /proc/self/fd/NN won't work on deleted files, as
evidenced by the follow message (which turns up when googling
"linkat deleted ENOENT"):
https://groups.google.com/g/linux.kernel/c/zZO4lqqwp64

Signed-off-by: Mathias Rav <m@git.strova.dk>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-11-26 10:58:54 +01:00
Michael Kerrisk 32a72b3e1b pivot_root.2: tfix
Reported-by: Davide Giorgio <davide@giorgiodavide.it>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-11-26 10:30:35 +01:00
Michael Kerrisk 6e94330a07 getrusage.2: Note that the 'vtimes' symbol exists only up to glibc 2.32
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-11-25 23:42:44 +01:00
Alejandro Colomar 36ded6fe89 set_tid_address.2: SYNOPSIS: Fix set_tid_address() return type
The Linux kernel uses 'pid_t' instead of 'long' for the return type.
As glibc provides no wrapper, use the same types the kernel uses.

$ sed -n 34,36p man-pages/man2/set_tid_address.2
.PP
.IR Note :
There is no glibc wrapper for this system call; see NOTES.

$ grep -rn 'SYSCALL_DEFINE.*set_tid_address' linux/
linux/kernel/fork.c:1632:
SYSCALL_DEFINE1(set_tid_address, int __user *, tidptr)

$ sed -n 1632,1638p linux/kernel/fork.c
SYSCALL_DEFINE1(set_tid_address, int __user *, tidptr)
{
	current->clear_child_tid = tidptr;

	return task_pid_vnr(current);
}

$ grep -rn 'task_pid_vnr(struct' linux/
linux/include/linux/sched.h:1374:
static inline pid_t task_pid_vnr(struct task_struct *tsk)

Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-11-24 10:49:48 +01:00
Alejandro Colomar 701b2272cd restart_syscall.2: SYNOPSIS: Fix restart_syscall() return type
The Linux kernel uses 'long' instead of 'int' for the return type.
As glibc provides no wrapper, use the same types the kernel uses.

$ grep -rn 'SYSCALL_DEFINE.*(restart_syscall'
kernel/signal.c:2891:SYSCALL_DEFINE0(restart_syscall)

$ sed -n 2891,2895p kernel/signal.c
SYSCALL_DEFINE0(restart_syscall)
{
	struct restart_block *restart = &current->restart_block;
	return restart->fn(restart);
}

$ grep -rn 'struct restart_block {'
include/linux/restart_block.h:25:struct restart_block {

$ sed -n 25,56p include/linux/restart_block.h
struct restart_block {
	long (*fn)(struct restart_block *);
	union {
		/* For futex_wait and futex_wait_requeue_pi */
		struct {
			u32 __user *uaddr;
			u32 val;
			u32 flags;
			u32 bitset;
			u64 time;
			u32 __user *uaddr2;
		} futex;
		/* For nanosleep */
		struct {
			clockid_t clockid;
			enum timespec_type type;
			union {
				struct __kernel_timespec __user *rmtp;
				struct old_timespec32 __user *compat_rmtp;
			};
			u64 expires;
		} nanosleep;
		/* For poll */
		struct {
			struct pollfd __user *ufds;
			int nfds;
			int has_timeout;
			unsigned long tv_sec;
			unsigned long tv_nsec;
		} poll;
	};
};

Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-11-23 22:52:30 +01:00
Michael Kerrisk 7c1a416d65 llseek.2: Point the reader to lseek64(3) for info about llseek(3)
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-11-23 07:18:43 +01:00
Michael Kerrisk 48a830d7c8 llseek.2: Note size of 'loff_t' type
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-11-23 07:11:13 +01:00
Michael Kerrisk 940a0979de llseek.2: Some mild rewriting to ease reading of the info in this page
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-11-22 07:34:56 +01:00
Alejandro Colomar e7ff75357d capget.2, execve.2, readv.2, socketpair.2, utime.2, utimensat.2, getloadavg.3, proc.5, mount_namespaces.7, unix.7: ffix
{.IR var [x]} -> {.I var[x]}

There were around 15 entries of the former,
and around 360 of the latter.

Found using:
$ grep -rn '^\.I[ |R].* \[.*\]' |sort

Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-11-21 23:33:07 +01:00
Jing Peng e2c751049c futex.2: tfix
In the comment of the example program, the peer blocks on fwait()
rather than fpost().

Signed-off-by: Jing Peng <pj.hades@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-11-21 22:25:21 +01:00
Michael Kerrisk 19b2538d4b clock_getres.2: Plae ERRORS in alphabetical order
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-11-21 06:49:25 +01:00
Michael Kerrisk 6b3561b8e4 arch_prctl.2: wfix: "current thread" ==> "calling thread"
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-11-19 10:20:31 +01:00
Michael Kerrisk 7533c83d88 perf_event_open.2: tfix
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-11-18 23:39:00 +01:00
Michael Kerrisk 5ae2634dba perf_event_open.2: Minor tweaks
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-11-18 23:39:00 +01:00
Namhyung Kim 1e554f3e32 perf_event_open.2: Update man page with recent kernel changes
Signed-off-by: Namhyung Kim <namhyung@gmail.com>
[alx: ffix + tfix]
Cowritten-by:  Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>

Cc: Arnaldo Carvalho de Melo <acme@kernel.org>
Cc: Jiri Olsa <jolsa@redhat.com>
Cc: Ingo Molnar <mingo@kernel.org>
Cc: Peter Zijlstra <peterz@infradead.org>
Cc: Mark Rutland <mark.rutland@arm.com>
Cc: Alexander Shishkin <alexander.shishkin@linux.intel.com>
Cc: Stephane Eranian <eranian@google.com>
Cc: Ian Rogers <irogers@google.com>
Cc: Adrian Hunter <adrian.hunter@intel.com>
Cc: Song Liu <songliubraving@fb.com>
Cc: Kan Liang <kan.liang@linux.intel.com>
Cc: Andi Kleen <ak@linux.intel.com>
Cc: Vince Weaver <vincent.weaver@maine.edu>

Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-11-18 22:58:20 +01:00
Michael Kerrisk a3727934a0 sigaction.2: Add a cross-reference to signal(7) for further info on 'ucontext_t'
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-11-17 13:18:09 +01:00
Michael Kerrisk ebf47ac9da uselib.2, posix_memalign.3, profil.3, rtime.3: Remove some text about libc/libc5
With this change, there remain almost no vestiges of information
about the long defunct Linux libc.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-11-16 12:29:42 +01:00
Michael Kerrisk d678063436 ioctl_tty.2, matherr.3, cciss.4, sk98lin.4: ffix: use proper table for formatting, not .nf/.fi
This gives better PDF rendering.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-11-16 11:26:23 +01:00
Michael Kerrisk 30dd9882b0 pidfd_open.2, pidfd_send_signal.2, poll.2, semget.2: ffix: EXAMPLES: use .EX/.EE instead of .nf/.fi
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-11-16 11:26:23 +01:00
Michael Kerrisk ce7ba00b76 bpf.2: Place EXAMPLES section in correct location
As per section ordering rules given in man-pages(7).

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-11-16 08:23:00 +01:00
Michael Kerrisk 71103ce878 prctl.2, setns.2: tfix: remove section number from API documented in this page
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-11-16 08:22:50 +01:00
Michael Kerrisk 7a92eea0de chroot.2, memfd_create.2, tailq.3: Fix unbalanced .nf/.fi
Reported-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-11-15 23:33:33 +01:00
Michael Kerrisk 678f71707e uname.2, feature_test_macros.7: ffix
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2020-11-15 22:30:17 +01:00