\HeaderA{file.access}{Ascertain File Accessibility}{file.access}
\keyword{file}{file.access}
\begin{Description}\relax
Utility function to access information about files on the user's
file systems.
\end{Description}
\begin{Usage}
\begin{verbatim}
file.access(names, mode = 0)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{names}] character vector containing file names.
\item[\code{mode}] integer specifying access mode required.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
Tilde-expansion is done on \code{names}: see \code{\LinkA{path.expand}{path.expand}}.

The \code{mode} value can be the exclusive or of the following values
\describe{
\item[0] test for existence.
\item[1] test for execute permission.
\item[2] test for write permission.
\item[4] test for read permission.
}
Permission will be computed for real user ID and real group ID (rather
than the effective IDs).

Please note that it is not good to use this function to test before
trying to open a file.  On a multi-tasking system, it is possible that
the accessibility of a file will change between the time you call
\code{file.access()} and the time you try to open the file.  It is
better to wrap file open attempts in \code{\LinkA{try}{try}}.
\end{Details}
\begin{Value}
An integer vector with values \code{0} for success and \code{-1} for failure.
\end{Value}
\begin{Note}\relax
This is intended as a replacement for the S-PLUS function
\code{access}, a wrapper for the C function of the same name, which
explains the return value encoding.  Note that
the return value is \bold{false} for \bold{success}.
\end{Note}
\begin{SeeAlso}\relax
\code{\LinkA{file.info}{file.info}} for more details on permissions,
\code{\LinkA{Sys.chmod}{Sys.chmod}} to change permissions, and
\code{\LinkA{try}{try}} for a \sQuote{test it and see} approach.

\code{\LinkA{file\_test}{file.Rul.test}} for shell-style file tests.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
fa <- file.access(dir("."))
table(fa) # count successes & failures
\end{ExampleCode}
\end{Examples}

