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

_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 is diverted by the default 'type = "output"'. Only
     prompts and warning/error messages continue to appear on the
     terminal. The latter can diverted by 'type = "message"' (see
     below).

     'sink()' or 'sink(file=NULL)' ends the last diversion (of the
     specified type).  As from R version 1.3.0 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 if will be opened if necessary.

     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:

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

_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)

