docs: improve setarch(8) manual page

Add more information when and why one might want to use various options.

Reviewed-by: Dmitry V. Levin <ldv@altlinux.org>
Signed-off-by: Sami Kerola <kerolasa@iki.fi>

sys-utils/setarch.8

@@ -1,4 +1,4 @@
-.TH SETARCH 8 "December 2014" "util-linux" "System Administration"
+.TH SETARCH 8 "December 2017" "util-linux" "System Administration"
 .SH NAME
 setarch \- change reported architecture in new program environment and set personality flags
 .SH SYNOPSIS
@@ -30,41 +30,73 @@ can actually set each of these architectures depends on the running kernel.
 .TP
 .B \-\-uname\-2.6
 Causes the \fIprogram\fR to see a kernel version number beginning with 2.6.
+Turns on UNAME26.
 .TP
 .BR \-v , " \-\-verbose"
 Be verbose.
 .TP
 \fB\-3\fR, \fB\-\-3gb\fR
-Specifies that processes should use a maximum of 3GB of address space on systems where it is supported (ADDR_LIMIT_3GB).
+Specifies
+.I program
+should use a maximum of 3GB of address space.  Supported on x86.  Turns on
+ADDR_LIMIT_3GB.
 .TP
 \fB\-\-4gb\fR
-Ignored (for backward compatibility only).
+This option has no effect.  It is retained for backward compatibility only,
+and may be removed in future releases.
 .TP
 \fB\-B\fR, \fB\-\-32bit\fR
-Turns on ADDR_LIMIT_32BIT.
+Limit the address space to 32 bits to emulate hardware.  Supported on ARM
+and Alpha.  Turns on ADDR_LIMIT_32BIT.
 .TP
 \fB\-F\fR, \fB\-\-fdpic\-funcptrs\fR
-Userspace function pointers point to descriptors (turns on FDPIC_FUNCPTRS).
+Treat user-space function pointers to signal handlers as pointers to address
+descriptors.  This option has no effect on architectures that do not support
+FDPIC ELF binaries.  In kernel v4.14 support is limited to ARM, Blackfin,
+Fujitsu FR-V, and SuperH CPU architectures.
 .TP
 \fB\-I\fR, \fB\-\-short\-inode\fR
-Turns on SHORT_INODE.
+Obsolete bug emulation flag.  Turns on SHORT_INODE.
 .TP
 \fB\-L\fR, \fB\-\-addr\-compat\-layout\fR
-Changes the way virtual memory is allocated (turns on the ADDR_COMPAT_LAYOUT).
+Provide legacy virtual address space layout.  Use when the
+.I program
+binary does not have PT_GNU_STACK ELF header.  Turns on
+ADDR_COMPAT_LAYOUT.
 .TP
 \fB\-R\fR, \fB\-\-addr\-no\-randomize\fR
-Disables randomization of the virtual address space (turns on ADDR_NO_RANDOMIZE).
+Disables randomization of the virtual address space.  Turns on
+ADDR_NO_RANDOMIZE.
 .TP
 \fB\-S\fR, \fB\-\-whole\-seconds\fR
-Turns on WHOLE_SECONDS.
+Obsolete bug emulation flag.  Turns on WHOLE_SECONDS.
 .TP
 \fB\-T\fR, \fB\-\-sticky\-timeouts\fR
-Turns on STICKY_TIMEOUTS.
+This makes
+.BR select (2),
+.BR pselect (2),
+and
+.BR ppoll (2)
+system calls preserve the timeout value instead of modifying it to reflect
+the amount of time not slept when interrupted by a signal handler.  Use when
+.I program
+depends on this behavior.  For more details see the timeout description in
+.BR select (2)
+manual page.  Turns on STICKY_TIMEOUTS.
 .TP
 \fB\-X\fR, \fB\-\-read\-implies\-exec\fR
-Turns on READ_IMPLIES_EXEC.
+If this is set then
+.BR mmap (3)
+PROT_READ will also add the PROT_EXEC bit - as expected by legacy x86
+binaries.  Notice that the ELF loader will automatically set this bit when
+it encounters a legacy binary.  Turns on READ_IMPLIES_EXEC.
 .TP
 \fB\-Z\fR, \fB\-\-mmap\-page\-zero\fR
+SVr4 bug emulation that will set
+.BR mmap (3)
+page zero as read-only.  Use when
+.I program
+depends on this behavior, and the source code is not available to be fixed.
 Turns on MMAP_PAGE_ZERO.
 .TP
 .BR \-V , " \-\-version"
@@ -86,6 +118,9 @@ Elliot Lee
 .MT jnovy@redhat.com
 Jindrich Novy
 .ME
+.SH "SEE ALSO"
+.BR personality (2),
+.BR select (2)
 .SH AVAILABILITY
 The setarch command is part of the util-linux package and is available from
 .UR https://\:www.kernel.org\:/pub\:/linux\:/utils\:/util-linux/