connections               package:base               R Documentation

_F_u_n_c_t_i_o_n_s _t_o _M_a_n_i_p_u_l_a_t_e _C_o_n_n_e_c_t_i_o_n_s

_D_e_s_c_r_i_p_t_i_o_n:

     Functions to create, open and close connections.

_U_s_a_g_e:

     file(description = "", open = "", blocking = TRUE,
          encoding = getOption("encoding"))

     pipe(description, open = "", encoding = getOption("encoding"))

     fifo(description = "", open = "", blocking = FALSE,
          encoding = getOption("encoding"))

     gzfile(description, open = "", encoding = getOption("encoding"),
            compression = 6)

     unz(description, filename, open = "",
         encoding = getOption("encoding"))

     bzfile(description, open = "", encoding = getOption("encoding"))

     url(description, open = "", blocking = TRUE,
         encoding = getOption("encoding"))

     socketConnection(host = "localhost", port, server = FALSE,
                      blocking = FALSE, open = "a+",
                      encoding = getOption("encoding"))

     open(con, ...)
     ## S3 method for class 'connection':
     open(con, open = "r", blocking = TRUE, ...)

     close(con, ...)
     ## S3 method for class 'connection':
     close(con, type = "rw", ...)

     flush(con)

     isOpen(con, rw = "")
     isIncomplete(con)

_A_r_g_u_m_e_n_t_s:

description: character. A description of the connection. For 'file' and
          'pipe' this is a path to the file to be opened. For 'url' it
          is a complete URL, including schemes ('http://', 'ftp://' or
          'file://' - see Details). 'file' also accepts complete URLs. 

filename: a filename within a zip file.

     con: a connection.

    host: character.  Host name for port.

    port: integer.  The TCP port number.

  server: logical.  Should the socket be a client or a server?

    open: character.  A description of how to open the connection (if
          at all).  See Details for possible values.

blocking: logical.  See the 'Blocking' section below.

encoding: The name of the encoding to be used.  See the 'Encoding'
          section below.

compression: integer in 0-9.  The amount of compression to be applied
          when writing, from none to maximal.  The default is a good
          space/time compromise.

    type: character. Currently ignored.

      rw: character.  Empty or '"read"' or '"write"', partial matches
          allowed.

     ...: arguments passed to or from other methods.

_D_e_t_a_i_l_s:

     The first eight functions create connections.  By default the
     connection is not opened (except for 'socketConnection'), but may
     be opened by setting a non-empty value of argument 'open'.

     'gzfile' applies to files compressed by 'gzip', and 'bzfile' to
     those compressed by 'bzip2'.  'gzfile' can also open uncompressed
     files.  In each case the actual file is opened in binary mode and
     so no translations are done if the original file was a text file.

     'unz' reads (only) single files within zip files, in binary mode.
     The description is the full path, with '.zip' extension if
     required.

     All platforms support 'file', 'gzfile', 'bzfile', 'unz' and
     'url("file://")' connections.  The other types may be partially
     implemented or not implemented at all.  (They do work on most Unix
     platforms, and all but 'fifo' on Windows.)

     Proxies can be specified for 'url' connections: see
     'download.file'.

     'open', 'close' and 'seek' are generic functions: the following
     applies to the methods relevant to connections.

     'open' opens a connection.  In general functions using connections
     will open them if they are not open, but then close them again, so
     to leave a connection open call 'open' explicitly.

     Possible values for the mode 'open' to open a connection are

     '"_r"' _o_r '"_r_t"' Open for reading in text mode.

     '"_w"' _o_r '"_w_t"' Open for writing in text mode.

     '"_a"' _o_r '"_a_t"' Open for appending in text mode.

     '"_r_b"' Open for reading in binary mode.

     '"_w_b"' Open for writing in binary mode.

     '"_a_b"' Open for appending in binary mode.

     '"_r+"', '"_r+_b"' Open for reading and writing.

     '"_w+"', '"_w+_b"' Open for reading and writing, truncating file
          initially.

     '"_a+"', '"_a+_b"' Open for reading and appending.

     Not all modes are applicable to all connections: for example URLs
     can only be opened for reading.  Only file and socket connections
     can be opened for reading and writing/appending. For many
     connections there is little or no difference between text and
     binary modes, but there is for file-like connections on Windows,
     and 'pushBack' is text-oriented and is only allowed on connections
     open for reading in text mode.

     'close' closes and destroys a connection.

     'flush' flushes the output stream of a connection open for
     write/append (where implemented).

     If for a 'file' connection the description is '""', the file is
     immediately opened (in '"w+"' mode unless 'open="w+b"' is
     specified) and unlinked from the file system.  This provides a
     temporary file to write to and then read from.

     A note on 'file://' URLs.  The most general form (from RFC1738) is
     'file://host/path/to/file', but R only accepts the form with an
     empty 'host' field referring to the local machine. This is then
     'file:///path/to/file', where 'path/to/file' is relative to '/'. 
     So although the third slash is strictly part of the specification
     not part of the path, this can be regarded as a way to specify the
     file '/path/to/file'.  It is not possible to specify a relative
     path using a file URL. Also, no attempt is made to decode an
     encoded URL: call 'URLdecode' if necessary.

_V_a_l_u_e:

     'file', 'pipe', 'fifo', 'url', 'gzfile', 'bzfile', 'unz' and
     'socketConnection' return a connection object which inherits from
     class '"connection"' and has a first more specific class.

     'isOpen' returns a logical value, whether the connection is
     currently open.

     'isIncomplete' returns a logical value, whether last read attempt
     was blocked, or for an output text connection whether there is
     unflushed output.

_E_n_c_o_d_i_n_g:

     *Note:* prior to R 2.1.0 there was a byte-by-byte encoding option
     applied to input only.  This has been replaced by a more
     comprehensive scheme.

     The encoding of the input/output stream of a connection in _text_
     mode can be specified by name, in the same way as it would be
     given to 'iconv': see that help page for how to find out what
     names are recognized on your platform.  Additionally, '""' and
     '"native.enc"' both mean the 'native' encoding, that is the
     internal encoding of the current locale and hence no translation
     is done. Not all builds of R support this, and if yours does not,
     specifying a non-default encoding will give an error when the
     connection is opened.

     Re-encoding only works for connections in text mode.

     The encoding '"UCS-2LE"' is treated specially, as it is the
     appropriate value for Windows 'Unicode' text files.  If the first
     two bytes are the Byte Order Mark '0xFFFE' then these are removed
     as most implementations of 'iconv' do not accept BOMs.  Note that
     some implementations will handle BOMs using encoding '"UCS2"' but
     many will not.

     Exactly what happens when the requested translation cannot be done
     is in general undocumented.  Requesting a conversion that is not
     supported is an error, reported when the connection is opened.  On
     output the result is likely to be that up to the error, with a
     warning.  On input, it will most likely be all or some of the
     input up to the error.

     The encoding for 'stdin' when redirected from a file can be set by
     the command-line flag '--encoding'.

_B_l_o_c_k_i_n_g:

     The default condition for all but fifo and socket connections is
     to be in blocking mode.  In that mode, functions do not return to
     the R evaluator until they are complete.   In non-blocking mode,
     operations return as soon as possible, so on input they will
     return with whatever input is available (possibly none) and for
     output they will return whether or not the write succeeded.

     The function 'readLines' behaves differently in respect of
     incomplete last lines in the two modes: see its help page.

     Even when a connection is in blocking mode, attempts are made to
     ensure that it does not block the event loop and hence the
     operation of GUI parts of R.  These do not always succeed, and the
     whole process will be blocked during a DNS lookup on Unix, for
     example.

     Most blocking operations on URLs and sockets are subject to the
     timeout set by 'options("timeout")'.  Note that this is a timeout
     for no response at all, not for the whole operation.

_F_i_f_o_s:

     Fifos default to non-blocking.  That follows Svr4 and it probably
     most natural, but it does have some implications. In particular,
     opening a non-blocking fifo connection for writing (only) will
     fail unless some other process is reading on the fifo.

     Opening a fifo for both reading and writing (in any mode: one can
     only append to fifos) connects both sides of the fifo to the R
     process, and provides an similar facility to 'file()'.

_C_l_i_p_b_o_a_r_d:

     'file' can also be used with 'description = "clipboard"' in mode
     '"r"' only.  It reads the X11 primary selection, which can also be
     specified as '"X11_primary"' and the secondary selection as
     '"X11_secondary"'.

     When the clipboard is opened for reading, the contents are
     immediately copied to internal storage in the connection.

     Unix users wishing to _write_ to the primary selection may be able
     to do so via 'xclip' (<URL:
     http://people.debian.org/~kims/xclip/>), for example by
     'pipe("xclip -i", "w")'.

     MacOS X users can use 'pipe("pbpaste")' and 'pipe("pbcopy", "w")'
     to read from and write to that system's clipboard.

_N_o_t_e:

     R's connections are modelled on those in S version 4 (see
     Chambers, 1998).  However R goes well beyond the Svr4 model, for
     example in output text connections and URL, 'gzfile', 'bzfile' and
     socket connections.

     The default mode in R is '"r"' except for socket connections. This
     differs from Svr4, where it is the equivalent of '"r+"', known as
     '"*"'.

     On platforms where 'vsnprintf' does not return the needed length
     of output (e.g., Windows) there is a 100,000 character output
     limit on the length of line for 'fifo', 'gzfile' and 'bzfile'
     connections: longer lines will be truncated with a warning.

_R_e_f_e_r_e_n_c_e_s:

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

_S_e_e _A_l_s_o:

     'textConnection', 'seek', 'readLines', 'readBin', 'writeLines',
     'writeBin', 'showConnections', 'pushBack'.

     'capabilities' to see if 'url', 'fifo' and 'socketConnection' are
     supported by this build of R.

_E_x_a_m_p_l_e_s:

     zz <- file("ex.data", "w")  # open an output file connection
     cat("TITLE extra line", "2 3 5 7", "", "11 13 17", file = zz, sep = "\n")
     cat("One more line\n", file = zz)
     close(zz)
     readLines("ex.data")
     unlink("ex.data")

     zz <- gzfile("ex.gz", "w")  # compressed file
     cat("TITLE extra line", "2 3 5 7", "", "11 13 17", file = zz, sep = "\n")
     close(zz)
     readLines(gzfile("ex.gz"))
     unlink("ex.gz")

     zz <- bzfile("ex.bz2", "w")  # bzip2-ed file
     cat("TITLE extra line", "2 3 5 7", "", "11 13 17", file = zz, sep = "\n")
     close(zz)
     print(readLines(bzfile("ex.bz2")))
     unlink("ex.bz2")

     ## An example of a file open for reading and writing
     Tfile <- file("test1", "w+")
     c(isOpen(Tfile, "r"), isOpen(Tfile, "w")) # both TRUE
     cat("abc\ndef\n", file=Tfile)
     readLines(Tfile)
     seek(Tfile, 0, rw="r") # reset to beginning
     readLines(Tfile)
     cat("ghi\n", file=Tfile)
     readLines(Tfile)
     close(Tfile)
     unlink("test1")

     ## We can do the same thing with an anonymous file.
     Tfile <- file()
     cat("abc\ndef\n", file=Tfile)
     readLines(Tfile)
     close(Tfile)

     if(capabilities("fifo")) {
       zz <- fifo("foo", "w+")
       writeLines("abc", zz)
       print(readLines(zz))
       close(zz)
       unlink("foo")
     }

     ## Not run: ## Unix examples of use of pipes

     # read listing of current directory
     readLines(pipe("ls -1"))

     # remove trailing commas. Suppose
     % cat data2
     450, 390, 467, 654,  30, 542, 334, 432, 421,
     357, 497, 493, 550, 549, 467, 575, 578, 342,
     446, 547, 534, 495, 979, 479
     # Then read this by
     scan(pipe("sed -e s/,$// data2"), sep=",")

     # convert decimal point to comma in output
     # both R strings and (probably) the shell need \ doubled
     zz <- pipe(paste("sed s/\\\\./,/ >", "outfile"), "w")
     cat(format(round(rnorm(100), 4)), sep = "\n", file = zz)
     close(zz)
     file.show("outfile", delete.file=TRUE)## End(Not run)

     ## Not run: ## example for Unix machine running a finger daemon

     con <- socketConnection(port = 79, blocking = TRUE)
     writeLines(paste(system("whoami", intern=TRUE), "\r", sep=""), con)
     gsub(" *$", "", readLines(con))
     close(con)## End(Not run)

     ## Not run: ## two R processes communicating via non-blocking sockets
     # R process 1
     con1 <- socketConnection(port = 6011, server=TRUE)
     writeLines(LETTERS, con1)
     close(con1)

     # R process 2
     con2 <- socketConnection(Sys.info()["nodename"], port = 6011)
     # as non-blocking, may need to loop for input
     readLines(con2)
     while(isIncomplete(con2)) {Sys.sleep(1); readLines(con2)}
     close(con2)
     ## End(Not run)

     ## Not run: 
      ## examples of use of encodings
     cat(x, file = file("foo", "w", encoding="UTF-8"))
     # read a 'Windows Unicode' file including names
     A <- read.table(file("students", encoding="UCS-2LE"))
     ## End(Not run)

