[ RDocumentation ](/)

Moon  [ ](https://github.com/datacamp/rdocumentation-2.0) [ Learn R
](https://www.datacamp.com/learn/r)

Search all packages and functions

[ base  (version  3.6.2  ) ](/packages/base/versions/3.6.2)

#  sink: Send R Output to a File

##  Description

` sink ` diverts  R  output to a connection (and stops such diversions).

` sink.number() ` reports how many diversions are in use.

` sink.number(type = "message") ` reports the number of the connection
currently being used for error messages.

##  Usage

    
    
    sink(file = NULL, append = FALSE, type = c("output", "message"),
         split = FALSE)
    
    sink.number(type = c("output", "message"))

##  Arguments

file

a writable [ connection ](/link/connection?package=base&version=3.6.2) or a
character string naming the file to write to, or ` NULL ` to stop sink-ing.

append

logical. If ` TRUE ` , output will be appended to ` file ` ; otherwise, it
will overwrite the contents of ` file ` .

type

character string. Either the output stream or the messages stream. The name
will be partially matched so can be abbreviated.

split

logical: if ` TRUE ` , output will be sent to the new sink and to the current
output stream, like the Unix program ` tee ` .

##  Value

` sink ` returns ` NULL ` .

For ` sink.number() ` the number (0, 1, 2, …) of diversions of output in
place.

For ` sink.number("message") ` the connection number used for messages, 2 if
no diversion has been used.

##  Warning

Do not use a connection that is open for ` sink ` for any other purpose. The
software will stop you closing one such inadvertently.

Do not sink the messages stream unless you understand the source code
implementing it and hence the pitfalls.

##  Details

` sink ` diverts  R  output to a connection (and must be used again to finish
such a diversion, see below!). If ` file ` is a character string, a file
connection with that name will be established for the duration of the
diversion.

Normal  R  output (to connection ` [ stdout
](/link/stdout?package=base&version=3.6.2) ` ) is diverted by the default `
type = "output" ` . Only prompts and (most) messages continue to appear on the
console. Messages sent to ` [ stderr
](/link/stderr?package=base&version=3.6.2) () ` (including those from ` [
message ](/link/message?package=base&version=3.6.2) ` , ` [ warning
](/link/warning?package=base&version=3.6.2) ` and ` [ stop
](/link/stop?package=base&version=3.6.2) ` ) can be diverted by ` sink(type =
"message") ` (see below).

` sink() ` or ` sink(file = NULL) ` ends the last diversion (of the specified
type). There is a stack of diversions for normal output, so output reverts to
the previous diversion (if there was one). The stack is of up to 21
connections (20 diversions).

If ` file ` is a connection it will be opened if necessary (in ` "wt" ` mode)
and closed once it is removed from the stack of diversions.

` split = TRUE ` only splits  R  output (via ` Rvprintf ` ) and the default
output from ` [ writeLines ](/link/writeLines?package=base&version=3.6.2) ` :
it does not split all output that might be sent to ` [ stdout
](/link/stdout?package=base&version=3.6.2) () ` .

Sink-ing the messages stream should be done only with great care. For that
stream ` file ` must be an already open connection, and there is no stack of
connections.

If ` file ` is a character string, the file will be opened using the current
encoding. If you want a different encoding (e.g., to represent strings which
have been stored in UTF-8), use a ` [ file
](/link/file?package=base&version=3.6.2) ` connection --- but some ways to
produce  R  output will already have converted such strings to the current
encoding.

##  References

Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) _The New S Language_ .
Wadsworth & Brooks/Cole.

Chambers, J. M. (1998) _Programming with Data. A Guide to the S Language_ .
Springer.

##  See Also

` [ capture.output ](/link/capture.output?package=base&version=3.6.2)