Clarified documentation for os.access().

Based on patch contributed by Sean Reifschneider.
Closes SF patch #570618.

diff --git a/Doc/lib/libos.tex b/Doc/lib/libos.tex
index d40aa076b1fce31b370c83ff335cb6831b003c3c..b699f2afad8c10be09445b833aebde1c994cd9e5 100644 (file)
--- a/Doc/lib/libos.tex
+++ b/Doc/lib/libos.tex
@@ -532,11 +532,13 @@ Availability: Macintosh, Windows.
 \subsection{Files and Directories \label{os-file-dir}}
 
 \begin{funcdesc}{access}{path, mode}
-Check read/write/execute permissions for this process or existence of
-file \var{path}.  \var{mode} should be \constant{F_OK} to test the
-existence of \var{path}, or it can be the inclusive OR of one or more
-of \constant{R_OK}, \constant{W_OK}, and \constant{X_OK} to test
-permissions.  Return \code{1} if access is allowed, \code{0} if not.
+Use the real uid/gid to test for access to \var{path}.  Note that most
+operations will use the effective uid/gid, therefore this routine can
+be used in a suid/sgid environment to test if the invoking user has the
+specified access to \var{path}.  \var{mode} should be \constant{F_OK}
+to test the existence of \var{path}, or it can be the inclusive OR of
+one or more of \constant{R_OK}, \constant{W_OK}, and \constant{X_OK} to
+test permissions.  Return \code{1} if access is allowed, \code{0} if not.
 See the \UNIX{} man page \manpage{access}{2} for more information.
 Availability: \UNIX{}, Windows.
 \end{funcdesc}

diff --git a/Modules/posixmodule.c b/Modules/posixmodule.c
index f491c47aad9cd27d61c0b4b5ea0d83c8cdb2a90d..2fe9e0c4e0a4707bd8edd7556e0bcdd205186f5a 100644 (file)
--- a/Modules/posixmodule.c
+++ b/Modules/posixmodule.c
@@ -596,7 +596,11 @@ posix_do_stat(PyObject *self, PyObject *args, char *format,
 
 static char posix_access__doc__[] =
 "access(path, mode) -> 1 if granted, 0 otherwise\n\
-Test for access to a file.";
+Use the real uid/gid to test for access to a path.  Note that most
+operations will use the effective uid/gid, therefore this routine can
+be used in a suid/sgid environment to test if the invoking user has the
+specified access to the path.  The mode argument can be F_OK to test
+existance, or the inclusive-OR of R_OK, W_OK, and X_OK.";
 
 static PyObject *
 posix_access(PyObject *self, PyObject *args)