doc access?

doc access?

[Kevin Ryde]

        * 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.


 - 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 can be one of the following or a
     bitwise-OR (`logior') of more than one.

      - 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.

     The way the calling process's real ID is used by `access?' means
     that a set-UID or set-GID program will test the invoking user's
     permissions, rather than anything extra the effective ID might make
     possible.

     Consider a database import program which is set-UID so it can
     write to a shared database.  When copying from a file to the
     database the set-UID might make it possible to read files the
     invoking user cannot normally read.  `access?' can be called to
     guard against that.

     In normal circumstances of course the real and effective IDs are
     the same, so `access?' simply indicates what the process will be
     able to do.

     Most library functions are best off not testing with `access?',
     but instead simply attempting their operations.  This ensures they
     can utilize extra permissions obtained from an effective ID.


_______________________________________________
Guile-devel mailing list
Guile-devel@gnu.org
http://mail.gnu.org/mailman/listinfo/guile-devel

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.


_______________________________________________
Guile-devel mailing list
Guile-devel@gnu.org
http://mail.gnu.org/mailman/listinfo/guile-devel