\HeaderA{save}{Save R Objects}{save}
\methaliasA{save.image}{save}{save.image}
\keyword{file}{save}
\begin{Description}\relax
\code{save} writes an external representation of \R{} objects to the
specified file.  The objects can be read back from the file at a later
date by using the function \code{load} (or \code{data} in some cases).

\code{save.image()} is just a short-cut for \sQuote{save my current
workspace},
i.e., \code{save(list = ls(all=TRUE), file = ".RData")}.  It is also what
happens with \code{\LinkA{q}{q}("yes")}.
\end{Description}
\begin{Usage}
\begin{verbatim}
save(..., list = character(0),
     file = stop("'file' must be specified"),
     ascii = FALSE, version = NULL, envir = parent.frame(),
     compress = !ascii, eval.promises = TRUE, precheck = TRUE)

save.image(file = ".RData", version = NULL, ascii = FALSE,
           compress = !ascii, safe = TRUE)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{...}] the names of the objects to be saved (as symbols or
character strings).
\item[\code{list}] A character vector containing the names of objects to be
saved.
\item[\code{file}] a connection or the name of the file where the data will be
saved.  Must be a file name for workspace format version 1.
\item[\code{ascii}] if \code{TRUE}, an ASCII representation of the data is
written.  The default value of \code{ascii} is \code{FALSE} which
leads to a more compact binary file being written.
\item[\code{version}] the workspace format version to use.  \code{NULL}
specifies the current default format.  The version used from \R{}
0.99.0 to \R{} 1.3.1 was version 1.  The default format as from \R{}
1.4.0 is version 2.
\item[\code{envir}] environment to search for objects to be saved.
\item[\code{compress}] logical specifying whether saving to a named file is to
use compression.  Ignored when \code{file} is a connection and for
workspace format version 1.
\item[\code{eval.promises}] logical: should objects which are promises be
forced before saving?
\item[\code{precheck}] logical: should the existence of the objects be
checked before starting to save (and in particular before opening
the file/connection)?  Does not apply to version 1 saves.
\item[\code{safe}] logical.  If \code{TRUE}, a temporary file is used for
creating the saved workspace.  The temporary file is renamed to
\code{file} if the save succeeds.  This preserves an existing
workspace \code{file} if the save fails, but at the cost of using
extra disk space during the save.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
The names of the objects specified either as symbols (or character
strings) in \code{...} or as a character vector in \code{list} are
used to look up the objects from environment \code{envir}.  By default
\LinkA{promises}{promises} are evaluated, but if \code{eval.promises = FALSE}
promises are saved (together with their evaluation environments).
(Promises embedded in objects are always saved unevaluated.)

All \R{} platforms use the XDR (bigendian) representation of C ints and
doubles in binary save-d files, and these are portable across all \R{}
platforms. (ASCII saves used to be useful for moving data between
platforms but are now mainly of historical interest.)

Default values for the \code{ascii}, \code{compress}, \code{safe} and
\code{version} arguments can be modified with the \code{save.defaults}
option (used both by \code{save} and \code{save.image}), see also the
example section below.  If a \code{save.image.defaults} option is set
it overrides \code{save.defaults} for function \code{save.image}
(which allows this to have different defaults).

It is possible to compress later (with \code{gzip}) a file saved with
\code{compress = FALSE}: the effect is the same as saving with
\code{compress = TRUE}.
\end{Details}
\begin{Section}{Warnings}
The \code{...} arguments only give the \emph{names} of the objects
to be saved: they are searched for in the environment given by the
\code{envir} argument, and the actual objects given as arguments need
not be those found.

Saved \R{} objects are binary files, even those saved with
\code{ascii = TRUE}, so ensure that they are transferred without
conversion of end of line markers and of 8-bit characters.  The lines
are delimited by LF on all platforms.

Although the default version has not changed since \R{} 1.4.0, this
does not mean that saved files are necessarily backwards compatible.
You will be able to load a saved image into an earlier version of \R{}
unless use is made of later additions (for example, raw vectors or
external pointers).
\end{Section}
\begin{Note}\relax
The most common reason for failure is lack of write permission in the
current directory.  For \code{save.image} and for saving at the end of
a session this will shown by messages like
\begin{alltt}
    Error in gzfile(file, "wb") : unable to open connection
    In addition: Warning message:
    In gzfile(file, "wb") :
      cannot open compressed file '.RDataTmp',
      probable reason 'Permission denied'
\end{alltt}

The defaults were changed to use compressed saves for \code{save} in
2.3.0 and for \code{save.image} in 2.4.0.  Any recent version of \R{}
can read compressed save files, and a compressed file can be
uncompressed (by \code{gzip -d}) for use with very old versions of \R.
\end{Note}
\begin{SeeAlso}\relax
\code{\LinkA{dput}{dput}}, \code{\LinkA{dump}{dump}}, \code{\LinkA{load}{load}},
\code{\LinkA{data}{data}}.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
x <- stats::runif(20)
y <- list(a = 1, b = TRUE, c = "oops")
save(x, y, file = "xy.Rdata")
save.image()
unlink("xy.Rdata")
unlink(".RData")

# set save defaults using option:
options(save.defaults=list(ascii=TRUE, safe=FALSE))
save.image()
unlink(".RData")
\end{ExampleCode}
\end{Examples}

