diff --git a/libguile/posix.c b/libguile/posix.c
index 35f61037e..3c16b37f1 100644
--- 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;