mirror/guile
mirror/guile
1
Fork 0
mirror of https://git.savannah.gnu.org/git/guile.git synced 2025-05-20 11:40:18 +02:00
Code Activity

(scm_access): Update docstring per manual.

Browse source
This commit is contained in:
Kevin Ryde 2004-09-07 00:26:48 +00:00
parent 9268038891
commit 20e0b1661a
1 changed files with 31 additions and 14 deletions
Download patch file Download diff file Expand all files Collapse all files

45
libguile/posix.c
View file

@ -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;