Date: Wed, 3 Mar 1999 18:30:42 +0200 (IST)
From: Eli Zaretskii <eliz AT is DOT elta DOT co DOT il>
X-Sender: eliz AT is
To: "Mark E." <snowball3 AT usa DOT net>
cc: djgpp-workers AT delorie DOT com
Subject: Re: chroot patches r3
In-Reply-To: <199903011812.SAA19946@out2.ibm.net>
Message-ID: <Pine.SUN.3.91.990303182855.18749A-100000@is>
MIME-Version: 1.0
Content-Type: TEXT/PLAIN; charset=US-ASCII
Reply-To: djgpp-workers AT delorie DOT com


On Mon, 1 Mar 1999, Mark E. wrote:

> Since an attempt to open() a directory will return -1 for a file descriptor, I 
> think for now it might be better to remove that check since it would 
> interfere with the very incompatibility that is being worked around.

I don't see anything wrong with ignoring negative handles.  But if you 
*are* enforcing positive ones, errno should be EBADF.

> Also, I've attached patches for chroot.txh and fchroot.txh, plus patches 
> for crt1.c and a revised patch for c1root.c.

The docs still have some problems, so I corrected them (I'm sending
them in a separate message, which see).

Some comments, for the future, are below.  But first, a word about the
following excerpt from the docs:

> /* Succeeds because 'c:/djgpp/bin' is relative to 'c:/djgpp'.
>    Passing in '/bin' would have also worked. */
> chroot("c:/djgpp/bin");

I'm not sure whether we need such a feature.  I think Unix won't allow
it (can anybody please check this?).  If I'm right, you can simply
require that an argument doesn't begin with a drive letter, unless the
current root is empty.

Here are the comments about the docs:

chroot.txh had some very long lines (I think this was the cause of the
problems when you sent it previously as plain text).  It is never a
good idea to have such long lines in a text file; and it usually
doesn't survive the mail transport.

You shouldn't use quotes inside @file{}.  makeinfo adds the quotes in
the Info output, and TeX typesets the file name in a special font.
You only need to put the file name itself, like in @file{/}.

> The only way to reset the root directory is with a call to
> @xref{fchroot}.

You should avoid such usage of @xref.  First, @xref should only be
used at the beginning of a sentence, because it produces See or Note
with a capital letter.  If you need a reference in the middle of a
sentence, say either "see @ref{foo}" or "(@pxref{foo})", the latter
should be always in parentheses.

More importantly, don't use cross-references both to name the function
and to place a reference to its docs.  Even in the Info output it
looks awkward:

   The only way to reset the root directory is with a call to 
   *Note fchroot::.

And it looks like a downright typo in the printed manual:

   The only way to reset the root directory is with a call to
   See [fchroot], page 1234.

Here's how I suggest to write the above sentence:

   The only way to reset the root directory is with a call to
   @code{fchroot}.  @xref{fchroot}.

> If @var{CHROOT_UNIX) is not set or is set to 'Y'

Anything typed by the user or output by the computer, like `Y' in this
case, should have the @samp{} markup:

   If @var{CHROOT_UNIX) is not set or is set to @samp{Y}

> @example
> In our examples, assume 'c:/djgpp' and 'c:/djgpp/bin/gcc.exe' exist.
>
> An example for Unix compatibility or restrictive mode:
>
> chroot("c:/djgpp");

Don't put descriptive text inside @example.  An @example block should
only include valid C (or other language) code.  If you need
explanations, put them outside the @example block.  There's no
limitation on the number of @example blocks under the Example
subheading, so you could have e.g. two blocks with text before the
first and the second.

Last, but not least, thanks for workin on this.