Re: doc access?

[Kevin Ryde]

I wrote:
>
>         * posix.texi (File System): In access?, reword a bit, clarify real
>         versus effective ID handling, add an example of that, and recommend
>         against access tests in library functions.

I toned it down a bit and checked it in,

 - Scheme Procedure: access? path how
 - C Function: scm_access (path, how)
     Test accessibility of a file under the real UID and GID of the
     calling process.  The return is `#t' if PATH exists and the
     permissions requested by HOW are all allowed, or `#f' if not.

     HOW is an integer which is one of the following values, or a
     bitwise-OR (`logior') of multiple values.

      - Variable: R_OK
          Test for read permission.

      - Variable: W_OK
          Test for write permission.

      - Variable: X_OK
          Test for execute permission.

      - Variable: F_OK
          Test for existence of the file.  This is implied by each of
          the other tests, so there's no need to combine it with them.

     It's important to note that `access?' does not simply indicate
     what will happen on attempting to read or write a file.  In normal
     circumstances it does, but in a set-UID or set-GID program it
     doesn't because `access?' tests the real ID, whereas an open or
     execute attempt uses the effective ID.

     A program which will never run set-UID/GID can ignore the
     difference between real and effective IDs, but for maximum
     generality, especially in library functions, it's generally best
     not to use `access?' to predict the result of an open or execute,
     instead simply attempt that and catch any exception.

     The main use for `access?' is to let a set-UID/GID program
     determine what the invoking user would have been allowed to do,
     without the greater (or perhaps lesser) privileges afforded by the
     effective ID.  For more on this, see *Note Testing File Access:
     (libc)Testing File Access.