Re: Help text for ld magic number options

[Stephen Casner <casner at acm dot org>]

On Sun, 23 Feb 2020, Fangrui Song wrote:

> On 2020-02-22, Stephen Casner wrote:
> > Thanks, Alan, for addressing bug 25569 more thoroughly than I would be
> > able to do.
> >
> > To all, next I have three proposed changes related to the magic number
> > options for ld on which I solicit your feedback.  First a simple one.
> >
> > The output of ld --help includes the following:
> >
> >  -n, --nmagic     Do not page align data
> >  -N, --omagic     Do not page align data, do not make text readonly
> >  --no-omagic      Page align data, make text readonly
> >
> > The help text for --nmagic is not accurate for the pdp11-aout target
> > and I believe not for others as well.  That option results in setting
> > config.text_read_only = TRUE, and in order to make the text read-only
> > the data must be aligned to a separate page on the PDP11 and I presume
> > for most if not all other computers as well.
> >
> > The references to page alignment really correspond to the setting of
> > config.magic_demand_paged which, when TRUE, selects the ZMAGIC (0413)
> > format in aoutx.h.  That format does require the data to be page
> > aligned, but more significantly it indicates to the runtime system to
> > do demand paging.  The pdp11-aout code in bfd/pdp11.c does not
> > implement the ZMAGIC format (even though there is some stub code for
> > it included when copying from aoutx.h) since demand paging isn't
> > practical on the PDP11 and wasn't implemented for it over the full
> > timespan from Unix v6 through 2.11 BSD.  Thus, for pdp11-aout the
> > options --no-omagic and --nmagic produce the same result.
> >
> > I propose that the help text be changed as follows:
> >
> >  -n, --nmagic     Make text readonly, page align data, no demand paging
> >  -N, --omagic     Do not make text readonly, do not page align data
> >  --no-omagic      Make text readonly, page align data, do demand paging
> >
> > Is that acceptable?  This would have implications for the ld
> > documentation as well.
> >
>
> http://man.cat-v.org/unix_10th/5/a.out
>
>           #define  OMAGIC    0407       /* old impure format */
>           #define  NMAGIC    0410       /* read-only text */
>           #define  ZMAGIC    0413       /* demand load format */
>
> >  -n, --nmagic     Make text readonly, page align data, no demand paging
>
> Should something else be changed, rather than change --nmagic to behave
> differently from other architectures?

In my proposed change above, I'm not suggesting any change in the
behavior of --nmagic.  The current behavior is correct and consistent
with the defines that you referenced.

I'm just pointing out that the help text (and the associated info
documentation) does not match the current behavior.  I mention the
PDP11 architecture because I know the help text is wrong for that
architecture.  I think it is also wrong for all the others, but I'm
ready to be challenged on that belief.

The help text for --nmagic says "Do not page align data" but --nmagic
is supposed to have read-only text, as shown by the comment of the
NMAGIC define you quote.  In order to have read-only text it is
necessary to align the data to a separate page from the text so the
data can be read-write.  So correct help text for --nmagic should
include "Do page align data".

> (Why isn't --no-omagic named --zmagic ? :)

I have no idea.  Is the author of that change still available?

                                                        -- Steve