Date: Wed, 3 Mar 1999 18:32:36 +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.990303183051.18749B-100000@is>
MIME-Version: 1.0
Content-Type: TEXT/PLAIN; charset=US-ASCII
Reply-To: djgpp-workers AT delorie DOT com

Here are the diffs for the docs of chroot and fchroot, after I corrected 
the problems I mentioned in my other mail:

*** /dev/null	Wed Mar  3 17:57:40 1999
--- src/libc/compat/unistd/chroot.txh	Wed Mar  3 17:55:06 1999
***************
*** 0 ****
--- 1,102 ----
+ @node chroot, file system
+ @subheading Syntax
+ 
+ @example
+ #include <unistd.h>
+ 
+ extern unsigned int __chroot_flags;
+ 
+ int chroot(const char *new_root_directory);
+ @end example
+ 
+ @subheading Description
+ 
+ Causes @var{new_root_directory} to become the root directory, or
+ starting point, for path name searches beginning with @file{/} or
+ @file{\}.  The current working directory is unaffected. 
+ 
+ By default, @code{chroot} is set to Unix compatibility or restrictive
+ mode.  In this mode, @var{new_root_directory} can be any existing
+ directory.  In successive calls, @var{new_root_directory} must exist and
+ be relative to the current root directory, or else the call fails.  The
+ only way to reset the root directory is with a call to @code{fchroot}
+ (@pxref{fchroot}).  This mimics the behavior of Unix versions of
+ @code{chroot}.
+ 
+ The other available mode is Bash compatibility or permissive mode. In
+ this mode, @var{new_root_directory} must still exist, but it need not be
+ relative to the current root like in restrictive mode.  This mimics the
+ behavior of the @code{SYSROOT} environment variable in the DJGPP port of
+ Bash 1.14.7.
+ 
+ To allow a child program to inherit the root directory of its parent,
+ @code{chroot} sets the environment variables @code{ROOT} and
+ @code{CHROOT_UNIX}.  If set, @code{ROOT} will contain the root
+ directory.  If @var{CHROOT_UNIX} is not set or is set to @samp{Y},
+ @code{chroot} is set to enforce the restrictive Unix behavior.  If
+ @code{CHROOT_UNIX} is set to anything other than @samp{Y}, then
+ @code{chroot} is set to allow the permissive behavior.  @code{SYSROOT},
+ an environment variable used by the DJGPP port of Bash 1.14.7, is
+ supported in the interest of backward compatibility but its use is
+ discouraged.  If @code{ROOT} is not set, but @code{SYSROOT} is, then
+ @code{SYSROOT} is used to set the root directory, and @code{chroot} is
+ set to permissive mode, and @code{CHROOT_UNIX} is ignored.
+ 
+ The global variable @code{__chroot_flags} can be set to include the
+ following values to control the operation of @code{chroot}:
+ 
+ @table @code
+ 
+ @item __CHROOT_UNIX_MODE_FLAG
+ 
+ If set, @code{chroot} is in Unix compatibility or restrictive mode.  If
+ not set, @code{chroot} is in Bash compatibility or permissive mode.  See
+ the above description for how these two modes differ.
+ 
+ @end table
+ 
+ @subheading Return Value
+ 
+ Zero if successful, else nonzero and @code{errno} set if error.
+ 
+ @subheading Portability
+ 
+ @port-note The variable @code{__chroot_flags} is DJGPP specific.
+ @portability !ansi, !posix
+ 
+ @subheading Example
+ 
+ In our examples, assume 'c:/djgpp' and 'c:/djgpp/bin/gcc.exe' exist.
+ 
+ An example for Unix compatibility or restrictive mode:
+ 
+ @example
+ chroot("c:/djgpp");
+ 
+ /* This call will not succeed. Root will not be changed. */
+ chroot("c:/");
+ 
+ /* Checks c:/djgpp/bin/gcc.exe */
+ if (access("/bin/gcc.exe", R_OK) == 0)
+   printf("gcc.exe found");  
+ 
+ /* Succeeds because 'c:/djgpp/bin' is relative to 'c:/djgpp'.
+    Passing in '/bin' would have also worked. */
+ chroot("c:/djgpp/bin");
+ @end example
+ 
+ An example for Bash compatibility or permissive mode:
+ 
+ @example
+ /* Disable Unix compatibility or restrictive mode. */
+ __chroot_flags = 0;
+ 
+ chroot("c:/djgpp");
+ 
+ /* This will succeed since directory need not be relative
+    to 'c:/djgpp' like in the first example. */
+ chroot("c:/");
+ 
+ chroot("d:/windows");
+ @end example
+ 
*** /dev/null	Wed Mar  3 18:17:40 1999
--- src/libc/compat/unistd/fchroot.txh	Wed Mar  3 18:16:56 1999
***************
*** 0 ****
--- 1,39 ----
+ @node fchroot, file system
+ @subheading Syntax
+ 
+ @example
+ #include <unistd.h>
+ 
+ int fchroot(int file_handle);
+ @end example
+ 
+ @subheading Description
+ 
+ Clears the root directory set by any previous calls to @xref{chroot}.
+ Due to the fact that DOS does not allow you to obtain a file handle to a
+ directory, @var{file_handle} is ignored for non-negative values.  This
+ does introduce an incompatibility with Unix.  However, since
+ @code{fchroot} in Unix is guaranteed to succeed only when changing to
+ the system root, this function should be portable most of the time.
+ 
+ @subheading Return Value
+ 
+ Always returns zero for success, unless @var{file_handle} is less than
+ zero.
+ 
+ @subheading Portability
+ 
+ @portability !ansi, !posix
+ 
+ @subheading Example
+ 
+ @example
+ chroot("c:/djgpp");
+ if (access("/bin/gcc.exe", R_OK) < 0)
+   fprintf(stderr, "gcc.exe not found");  
+ 
+ fchroot(1);
+ 
+ if (access("/bin/gcc.exe", R_OK) < 0)
+   fprintf(stderr, "gcc.exe not found");  
+ @end example