src/library/base/man/on.exit.Rd

% File src/library/base/man/on.exit.Rd
% Part of the R package, https://www.R-project.org
% Copyright 1995-2014 R Core Team
% Distributed under GPL 2 or later

\name{on.exit}
\alias{on.exit}
\title{Function Exit Code}
\description{
  \code{on.exit} records the expression given as its argument as needing
  to be executed when the current function exits (either naturally or as
  the result of an error).  This is useful for resetting graphical
  parameters or performing other cleanup actions.

  If no expression is provided, i.e., the call is \code{on.exit()}, then
  the current \code{on.exit} code is removed.
}
\usage{
on.exit(expr = NULL, add = FALSE, after = TRUE)
}
\arguments{
  \item{expr}{an expression to be executed.}
  \item{add}{if TRUE, add \code{expr} to be executed after any previously
    set expressions (or before if \code{after} is FALSE); otherwise (the
    default) \code{expr} will overwrite any previously set expressions.}
  \item{after}{if \code{add} is TRUE and \code{after} is FALSE, then
    \code{expr} will be added on top of the expressions that were already
    registered. The resulting last in first out order is useful for freeing
    or closing resources in reverse order.}
}
\details{
  The \code{expr} argument passed to \code{on.exit} is recorded without
  evaluation.  If it is not subsequently removed/replaced by another
  \code{on.exit} call in the same function, it is evaluated in the
  evaluation frame of the function when it exits (including during
  standard error handling).  Thus any functions or variables in the
  expression will be looked for in the function and its environment at
  the time of exit: to capture the current value in \code{expr} use
  \code{\link{substitute}} or similar.

  If multiple \code{on.exit} expressions are set using \code{add = TRUE}
  then all expressions will be run even if one signals an error.

  This is a \sQuote{special} \link{primitive} function: it only
  evaluates the argument \code{add}.
}
\value{
  Invisible \code{NULL}.
}
\references{
  Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988)
  \emph{The New S Language}.
  Wadsworth & Brooks/Cole.
}
\seealso{
  \code{\link{sys.on.exit}} which returns the expression stored for use
  by \code{on.exit()} in the function in which \code{sys.on.exit()} is
  evaluated.
}
\examples{
require(graphics)

opar <- par(mai = c(1,1,1,1))
on.exit(par(opar))
\dontshow{par(opar)}
}
\keyword{programming}