\HeaderA{files}{File and Directory Manipulation}{files}
\aliasA{dir.create}{files}{dir.create}
\aliasA{file.append}{files}{file.append}
\aliasA{file.copy}{files}{file.copy}
\aliasA{file.create}{files}{file.create}
\aliasA{file.exists}{files}{file.exists}
\aliasA{file.remove}{files}{file.remove}
\aliasA{file.rename}{files}{file.rename}
\aliasA{file.symlink}{files}{file.symlink}
\aliasA{Sys.chmod}{files}{Sys.chmod}
\aliasA{Sys.umask}{files}{Sys.umask}
\keyword{file}{files}
\begin{Description}\relax
These functions provide a low-level interface to the computer's
file system.
\end{Description}
\begin{Usage}
\begin{verbatim}
file.create(..., showWarnings = TRUE)
file.exists(...)
file.remove(...)
file.rename(from, to)
file.append(file1, file2)
file.copy(from, to, overwrite = FALSE)
file.symlink(from, to)
dir.create(path, showWarnings = TRUE, recursive = FALSE,
           mode = "0777")
Sys.chmod(paths, mode = "0777")
Sys.umask(mode = "0000")
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{..., file1, file2, from, to, paths}] character vectors,
containing file names or paths.
\item[\code{path}] a character vector containing a single path name.
\item[\code{overwrite}] logical; should the destination files be overwritten?
\item[\code{showWarnings}] logical; should the warnings on failure be shown?
\item[\code{recursive}] logical: should elements of the path other than the
last be created?  If true, like Unix's \code{mkdir -p}.
\item[\code{mode}] the file mode to be used on Unix-alikes: it will be
coerced by \code{\LinkA{as.octmode}{as.octmode}}.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
The \code{...} arguments are concatenated to form one character
string: you can specify the files separately or as one vector.
All of these functions expand path names: see \code{\LinkA{path.expand}{path.expand}}.

\code{file.create} creates files with the given names if they do not
already exist and truncates them if they do.  They are created with the
maximal permissions allowed by the \code{umask} setting.

\code{file.exists} returns a logical vector indicating whether
the files named by its argument exist.  (Here \sQuote{exists} is in the
sense of the system's \code{stat} call: a file will be reported as
existing only if you have the permissions needed by \code{stat}.
Existence can also be checked by \code{\LinkA{file.access}{file.access}}, which
might use different permissions and so obtain a different result.
Note that the existence of a file does not imply that it is readable:
for that use \code{\LinkA{file.access}{file.access}}.)

\code{file.remove} attempts to remove the files named in its
argument.
On most platforms \sQuote{file} includes \emph{empty} directories,
symbolic links, fifos and sockets.

\code{file.rename} attempts to rename a single file.

\code{file.append} attempts to append the files named by its
second argument to those named by its first.  The \R{} subscript
recycling rule is used to align names given in vectors
of different lengths.

\code{file.copy} works in a similar way to \code{file.append} but with
the arguments in the natural order for copying.  Copying to existing
destination files is skipped unless \code{overwrite = TRUE}.
The \code{to} argument can specify a single existing directory.

\code{file.symlink} makes symbolic links on those Unix-like platforms
which support them.  The \code{to} argument can specify a single
existing directory.

\code{dir.create} creates the last element of the path, unless
\code{recursive = TRUE}.  Trailing path separators are removed.
The mode will be modified by the \code{umask} setting in the same way
as for the system function \code{mkdir}.  What modes can be set is
OS-dependent, and it is unsafe to assume that more than three octal
digits will be used.  For more details see your OS's documentation on the
system call \code{mkdir} (and not that on the command-line utility of
that name). 

\code{Sys.chmod} sets the file permissions of one or more files.
It may not be supported (when a warning is issued).
See the comments for \code{dir.create} for how modes are interpreted.
Changing mode on a symbolic link is unlikely to work (nor be
necessary).  For more details see your OS's documentation on the
system call \code{chmod} (and not that on the command-line utility of
that name). 

\code{Sys.umask} sets the \code{umask}.
It may not be supported (when a warning is issued and \code{"0000"}
returned).  For more details see your OS's documentation on the
system call \code{umask}.
\end{Details}
\begin{Value}
\code{dir.create} and \code{file.rename} return a logical,
true for success.

\code{Sys.umask} returns the previous value of the \code{umask},
invisibly, as a length-one object of class \code{"octmode"}.

The remaining functions return a logical vector indicating which
operation succeeded for each of the files attempted.

\code{dir.create} will return failure if the directory already exists.

If \code{showWarnings = TRUE}, \code{file.create} and
\code{dir.create} will give a warning for an unexpected failure
(e.g. not for a missing value nor for an already existing component for
\code{dir.create(recursive = TRUE)}).

Using a missing value for a file or path name will always be regarded
as a failure.
\end{Value}
\begin{Author}\relax
Ross Ihaka, Brian Ripley
\end{Author}
\begin{SeeAlso}\relax
\code{\LinkA{file.info}{file.info}}, \code{\LinkA{file.access}{file.access}}, \code{\LinkA{file.path}{file.path}},
\code{\LinkA{file.show}{file.show}}, \code{\LinkA{list.files}{list.files}},
\code{\LinkA{unlink}{unlink}}, \code{\LinkA{basename}{basename}}, \code{\LinkA{path.expand}{path.expand}}.

\code{\LinkA{file\_test}{file.Rul.test}}.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
cat("file A\n", file="A")
cat("file B\n", file="B")
file.append("A", "B")
file.create("A")
file.append("A", rep("B", 10))
if(interactive()) file.show("A")
file.copy("A", "C")
dir.create("tmp")
file.copy(c("A", "B"), "tmp")
list.files("tmp")
setwd("tmp")
file.remove("B")
file.symlink(file.path("..", c("A", "B")), ".")
setwd("..")
unlink("tmp", recursive=TRUE)
file.remove("A", "B", "C")
\end{ExampleCode}
\end{Examples}

