sink                  package:base                  R Documentation

_S_e_n_d _R _O_u_t_p_u_t _t_o _a _F_i_l_e

_D_e_s_c_r_i_p_t_i_o_n:

     'sink' diverts R output to a connection.

     '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.

_U_s_a_g_e:

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

     sink.number(type = c("output", "message"))

_A_r_g_u_m_e_n_t_s:

    file: a writable connection 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.  Either the output stream or the messages stream.

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

_D_e_t_a_i_l_s:

     'sink' diverts R output to a connection.  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))' is diverted by the
     default 'type = "output"'.  Only prompts and (most) messages
     continue to appear on the console.  Messages sent to 'stderr()'
     (including those from 'message', 'warning' and 'stop') 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': it does not split all output
     that might be sent to 'stdout()'.

     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.

_V_a_l_u_e:

     '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.

_W_a_r_n_i_n_g:

     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.

_N_o_t_e:

     'sink(split = TRUE)' is only available on systems which support
     the C99 function 'va_copy' (or under the name '__va_copy'), but we
     know of no current systems which do not.

_R_e_f_e_r_e_n_c_e_s:

     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.

_S_e_e _A_l_s_o:

     'capture.output'

_E_x_a_m_p_l_e_s:

     sink("sink-examp.txt")
     i <- 1:10
     outer(i, i, "*")
     sink()
     unlink("sink-examp.txt")
     ## Not run: 
     ## capture all the output to a file.
     zz <- file("all.Rout", open="wt")
     sink(zz)
     sink(zz, type="message")
     try(log("a"))
     ## back to the console
     sink(type="message")
     sink()
     try(log("a"))
     ## End(Not run)