fanotify.7: fix outdated description

Reviewed-by: Jan Kara <jack@suse.cz>
Signed-off-by: Amir Goldstein <amir73il@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

pivot_root.2: tfix

Reported-by: Davide Giorgio <davide@giorgiodavide.it>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

getrusage.2: Note that the 'vtimes' symbol exists only up to glibc 2.32

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

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>

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>

attributes.7: SEE ALSO: add signal-safety(7)

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

lseek64.3: tfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

pthread_tryjoin_np.3: Note that pthread_timedjoin_np() uses CLOCK_REALTIME, but there's a bug

Learned from an email converasation with Mike Crowe, and
verified by experiment.

Reported-by: Mike Crowe <mac@mcrowe.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

standards.7: Add LFS (Large File Summit)

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

lseek64.3: NOTES: describe the origin of lseek64() in LFS

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

lseek64.3: Remove sentence saying lseek64() is an alias for llseek()

As far as I can see, it is instead simply an alias for a
wrapper that calls _llseek(). Saying it's an alias for "llseek()"
seems confusing.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

lseek64.3: Remove section numbers from interface list

We're talking of a mix of wrapper functions and system calls
in this page. lseek() is both a system and a wrapper function,
and this page is mostly describing the wrapper

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

lseek64.3: wfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

lseek64.3: Minor clarifications

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

lseek64.3: srcfix: add some comments to remind myself of some details

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

llseek.2: Point the reader to lseek64(3) for info about llseek(3)

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

llseek.2: Note size of 'loff_t' type

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

lseek64.3: ffix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

getnameinfo.3: tfix

Reported-by: Sebastian Kirmayer <man-pages@kirmayer.eu>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

lseek64.3: srcfix: Add a lore link to some background on these APIs

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

getnameinfo.3: tfix

Reported-by: Sebastian Kirmayer <sebastian@kirmayer.de>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

llseek.2: Some mild rewriting to ease reading of the info in this page

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

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>

utmp.5: Oxford comma

Found using:
$ grep -rn '\\f., [^ ]*\\f. and' man?

I also updated the markup in that paragraph: \f -> .

Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

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>

standards.7: Relocate the discussion on POSIX manual pages

Rather than mention these pages under the discussion of one
version of the standard, move that text to the end of the page,
where it is probably a little more obvious.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

standards.7: Add URL for POSIX.1-2008/SUSv4

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

standards.7: Fix some URLs for locations of the standards

Reported-by: Rob Landley <rob@landley.net>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

clock_getres.2: Plae ERRORS in alphabetical order

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

socket.7: ffix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

socket.7: tfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

arch_prctl.2: wfix: "current thread" ==> "calling thread"

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

perf_event_open.2: tfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

perf_event_open.2: Minor tweaks

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

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>

signal.7: Add pidfd_send_signal() to list of APIs for sending signals

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

signal.7: ffix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

signal.7: Fixes and additions to text on execution of signal handlers

After comments from Dave Martin.

Reported-by: Dave Martin <Dave.Martin@arm.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

sigaction.2: Add a cross-reference to signal(7) for further info on 'ucontext_t'

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

signal.7: Mention 'ucontext_t' in the discussion of signal handler execution

Linking up the info presented on this page with the discussion
in getcontext(3) helps the reader.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

makecontext.3: Minor rewording

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

signal.7: Fixes to the text of "Execution of signals handlers"

See https://lore.kernel.org/linux-man/3fac10ea-7fed-739b-4974-09845f34867f@gmail.com/

Reported-by: Dave Martin <Dave.Martin@arm.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

getcontext.3, signal.7: tfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

getcontext.3: SEE ALSO: add signal(7)

The signal(7) manual page has some useful info related
to ucontext_t.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

getcontext.3: Mention SA_SIGINFO flag when talking about 3-argument signal handler

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

getcontext.3: wfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

Add script to get modified pages for commit messages

The script can be used this way:

git commit -sm "$(./scripts/modified_pages.sh): Short commit msg"

And then maybe --amend and add a longer message.

This is especially useful for changes to many pages at once,
usually when running a script to apply some global changes.

Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

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>

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>

cciss.4: ffix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

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>

man-pages.7: ffix: use a table rather .nf/.fi

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

MAINTAINER_NOTES: Add a file with some notes for maintainers

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

scandir.3: srcfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

check_unbalanced_macros.sh: A script to look for unbalanced *roff/man macro pairs

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

queue.7: tfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

kernel_lockdown.7: Remove unneeded quotes

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

nextafter.3: Remove duplicate "BUGS" section heading

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

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>

CIRCLEQ_EMPTY.3, CIRCLEQ_FIRST.3, CIRCLEQ_FOREACH.3, CIRCLEQ_FOREACH_REVERSE.3, CIRCLEQ_HEAD_INITIALIZER.3, CIRCLEQ_LAST.3, CIRCLEQ_LOOP_NEXT.3, CIRCLEQ_LOOP_PREV.3, CIRCLEQ_NEXT.3, CIRCLEQ_PREV.3: Add missing links to circleq.3

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

list.3: NAME: remove LIST_PREV, which is not documented in this page

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

pthread_attr_getsigmask_np.3: New link to pthread_attr_setsigmask_np.3

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

prctl.2, setns.2: tfix: remove section number from API documented in this page

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

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>

uname.2, feature_test_macros.7: ffix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

getutent.3: srcfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

getent.1, fanotify_mark.2, fcntl.2, futex.2, membarrier.2, mmap.2, mount.2, msgctl.2, readv.2, semctl.2, set_mempolicy.2, shmctl.2, syscalls.2, abs.3, bstring.3, btree.3, ctime.3, drand48.3, fgetc.3, fopen.3, gethostbyname.3, getnetent.3, getprotoent.3, getservent.3, INFINITY.3, __ppc_set_ppr_med.3, inet.3, j0.3, makecontext.3, printf.3, puts.3, resolver.3, sigsetops.3, elf.5, nscd.conf.5, proc.5, inotify.7, ipv6.7, spufs.7, system_data_types.7: Use Oxford comma

Found using:
pcregrep -rnM "^\.[B|I]R .*,\n\.[B|I].*[^,]\nand" man? |grep ^man |sort

Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

locale.5, ipv6.7: ffix

[.B XX_*] is the most extended form in the pages.

Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

faccessat2.2: New link to access.2

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

access.2: Document faccessat2()

faccessat2() was added in Linux 5.8 and enables a fix to
longstanding bugs in the faccessat() wrapper function.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

access.2: BUGS: note that faccessat() wrapper function emulation ignores ACLs

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

openat.2: Fix include path, should be linux/openat2.h

The include path is linux/openat2, so fix the manual to reference
this correct path.

Signed-off-by: Colin Ian King <colin.king@canonical.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

shmctl.2: wfix (for consistency with other *ctl.2 pages)

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

msgctl.2, semctl.2, shmctl.2: Minor fix

Break text into more paragraphs to ease readability

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

msgctl.2: Make comments in 'msqid_ds' definition more compact

The comments do not need to be so verbose, since the main text
provides the full details.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

msgctl.2: Add description of 'msg_cbytes' field

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

msgctl.2: Use field name "msg_cbytes" rather than "__msg_cbytes"

The shorter name is provided by default (i.e., if _DEFAULT_SOURCE
is defined).

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

msgctl.2: Place list of field descriptions in same order as structure definition

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

shmctl.2: Place list of field descriptions in same order as structure definition

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

semctl.2: ffix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

sigaction.2: tfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

signal-safety.7: Note async-signal-safety details for errno

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

sigaction.2: Minor wording improvements

Restructure the sa_handler description as a list, for easier
reading.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

sigaction.2: Clarify description of SA_NODEFER

Clarify description of SA_NODEFER, and note interaction with
act.sa_mask.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

sigaction.2: ffix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

sigaction.2: wfix

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

perf_event_open.2: srcfix

Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

signal.7: Minor tweaks to new "Execution of signal handlers" subsection

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

io_setup.2: SYNOPSIS: return long

The Linux kernel uses a long as the return type for this syscall.
As glibc provides no wrapper, use the same types the kernel uses.

Signed-off-by: Alejandro Colomar <colomar.6.4.3@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

signal.7: Relocate the new "Execution of signal handlers" subsection

It is probably more sensible to place this section after
the subsection "Signal mask and pending signals".

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

perf_event_open.2: Assign calculated value explicitly to 'config'

Signed-off-by: Alejandro Colomar <alx.manpages@gmail.com>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

signal.7: Minor tweaks to the test on execution of signal handlers

Reported-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

signal.7: Add some details on the execution of signal handlers

Add a "big picture" of what happens when a signal handler
is invoked.

Reported-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

sigaltstack.2: Clarify that the alternate signal stack is per-thread

Clarify that the alternate signal stack is per-thread (rather
than process-wide).

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

clone.2, sigaltstack.2: clone(CLONE_VM) disdables the alternate signal stack

In the kernel sources (kernel/fork.c::copy_process()), we have:

        /*
         * sigaltstack should be cleared when sharing the same VM
         */
        if ((clone_flags & (CLONE_VM|CLONE_VFORK)) == CLONE_VM)
                sas_ss_reset(p);

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

signal.7: SEE ALSO: add swapcontext(3)

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

sigaction.2: Further clarify the effect of the SA_NODEFER flag

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

getrlimit.2: State more precisely the range of kernel versions that had RLIMIT_LOCKS

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

timer_getoverrun.2: timer_getoverrun() now clamps the overrun count to DELAYTIMER_MAX

See https://bugzilla.kernel.org/show_bug.cgi?id=12665.
The fix by Thomas Gleixner was in kernel commit
78c9c4dfbf8c04883941445a195276bb4bb92c76.

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

signal.2: wfix: Make the warning against the use of signal() even more obvious

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>