(scm_access): Update docstring per manual.

diff --git a/libguile/posix.c b/libguile/posix.c
index 35f6103..3c16b37 100644 (file)
--- a/libguile/posix.c
+++ b/libguile/posix.c
@@ -1194,29 +1194,46 @@ SCM_DEFINE (scm_utime, "utime", 1, 2, 0,
 
 SCM_DEFINE (scm_access, "access?", 2, 0, 0,
             (SCM path, SCM how),
-           "Return @code{#t} if @var{path} corresponds to an existing file\n"
-           "and the current process has the type of access specified by\n"
-           "@var{how}, otherwise @code{#f}.  @var{how} should be specified\n"
-           "using the values of the variables listed below.  Multiple\n"
-           "values can be combined using a bitwise or, in which case\n"
-           "@code{#t} will only be returned if all accesses are granted.\n"
+           "Test accessibility of a file under the real UID and GID of the\n"
+           "calling process.  The return is @code{#t} if @var{path} exists\n"
+           "and the permissions requested by @var{how} are all allowed, or\n"
+           "@code{#f} if not.\n"
            "\n"
-           "Permissions are checked using the real id of the current\n"
-           "process, not the effective id, although it's the effective id\n"
-           "which determines whether the access would actually be granted.\n"
+           "@var{how} is an integer which is one of the following values,\n"
+           "or a bitwise-OR (@code{logior}) of multiple values.\n"
            "\n"
            "@defvar R_OK\n"
-           "test for read permission.\n"
+           "Test for read permission.\n"
            "@end defvar\n"
            "@defvar W_OK\n"
-           "test for write permission.\n"
+           "Test for write permission.\n"
            "@end defvar\n"
            "@defvar X_OK\n"
-           "test for execute permission.\n"
+           "Test for execute permission.\n"
            "@end defvar\n"
            "@defvar F_OK\n"
-           "test for existence of the file.\n"
-           "@end defvar")
+           "Test for existence of the file.  This is implied by each of the\n"
+           "other tests, so there's no need to combine it with them.\n"
+           "@end defvar\n"
+           "\n"
+           "It's important to note that @code{access?} does not simply\n"
+           "indicate what will happen on attempting to read or write a\n"
+           "file.  In normal circumstances it does, but in a set-UID or\n"
+           "set-GID program it doesn't because @code{access?} tests the\n"
+           "real ID, whereas an open or execute attempt uses the effective\n"
+           "ID.\n"
+           "\n"
+           "A program which will never run set-UID/GID can ignore the\n"
+           "difference between real and effective IDs, but for maximum\n"
+           "generality, especially in library functions, it's best not to\n"
+           "use @code{access?} to predict the result of an open or execute,\n"
+           "instead simply attempt that and catch any exception.\n"
+           "\n"
+           "The main use for @code{access?} is to let a set-UID/GID program\n"
+           "determine what the invoking user would have been allowed to do,\n"
+           "without the greater (or perhaps lesser) privileges afforded by\n"
+           "the effective ID.  For more on this, see ``Testing File\n"
+           "Access'' in The GNU C Library Reference Manual.")
 #define FUNC_NAME s_scm_access
 {
   int rv;