Re: [PATCH 3/4] docs: improve setarch(8) manual page

["Dmitry V. Levin" <ldv@altlinux.org>]

[-- Attachment #1: Type: text/plain, Size: 2427 bytes --]

On Mon, Dec 04, 2017 at 01:20:01PM +0000, Sami Kerola wrote:
> On 4 December 2017 at 12:04, Karel Zak wrote:
> > On Sun, Dec 03, 2017 at 12:51:16PM +0000, Sami Kerola wrote:
[...]
> >>  \fB\-\-4gb\fR
> >> -Ignored (for backward compatibility only).
> >> +Ignored for backward compatibility only.
> >
> > Dmitry is right, the old version is better.
> 
> How about text:
> 
> This option is no-op compatibility with an old Debian setarch
> implementation. Please do not use.

Let's add a description that is informative but without giving advice.
For example,

"This option has no effect.  It is retained for backward compatibility only,
and may be removed in future releases."

or

"This option has no effect.  It is retained for compatibility with ...,
and may be removed in future releases."

> >> +This makes
> >> +.BR select (2),
> >> +.BR pselect (2),
> >> +and
> >> +.BR ppoll (2)
> >> +system calls preserve the timeout value instead of storing the unslept time
> >> +when interrupted by a signal handler.  Use when
> >> +.I program
> >> +depends on this behavior, and the source code is not available to be fixed.
> >
> > See Dmitry's note ;-)
> 
> How about this:
> 
> -- snip
> This makes
> .BR select (2),
> .BR pselect (2),
> and
> .BR ppoll (2)
> system calls preserve the timeout value instead of storing the unslept time

I'm not sure about "unslept time" phrase.  Wouldn't a more formal
description be better, .e.g.

This makes
...
system calls preserve the timeout value instead of modifying it to reflect
the amount of time not slept when interrupted by a signal handler.
...

> when interrupted by a signal handler. Use when
> .I program
> depends on this behavior. For more details see the timeout description from

s/from/in/

> .BR select (2)
> manual page. Turns on STICKY_TIMEOUTS.
> -- snip

On the whole, this looks much better.

> My remote git has the latest.
> 
> https://github.com/kerolasa/lelux-utiliteetit/blob/2017wk48/sys-utils/setarch.8
> 
> And that branch also has FIXME item near FDPIC_FUNCPTRS description.
> Proposal(s) welcome how to make that text understandable.

What about this text:

"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.  Turns on FDPIC_FUNCPTRS."


-- 
ldv

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 801 bytes --]