connections {base} | R Documentation

## Functions to Manipulate Connections

### Description

Functions to create, open and close connections.

### Usage

    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)

### Arguments

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

### Details

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"` or `"rt"`
  Open for reading in text mode.
`"w"` or `"wt"`
  Open for writing in text mode.
`"a"` or `"at"`
  Open for appending in text mode.
`"rb"`
  Open for reading in binary mode.
`"wb"`
  Open for writing in binary mode.
`"ab"`
  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. In this form the path is relative to the root of the filesystem, not a Windows concept. The standard form is `file://d:/R/repos`: for compatibility with earlier versions of R and Unix versions, any other form is parsed as R as `file://` plus `/path/to/file`. Also, backslashes are accepted within the path even though RFC1738 does not allow them. Also, no attempt is made to decode an encoded URL: call `URLdecode` if necessary.

### Value

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

### Encoding

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.

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 (including that used on Windows) will handle BOMs using encoding `"UCS2"` but many (including that in `glibc`) 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`.

### Blocking

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.

### Fifos

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()`.

### Clipboard

`file` can also be used with `description = "clipboard"` in modes `"r"` and `"w"` only.

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

When writing to the clipboard, the output is copied to the clipboard only when the connection is closed or flushed. There is a 32Kb limit on the text to be written to the clipboard. This can be raised by using e.g. `file("clipboard-128")` on NT-based versions of Windows, to give 128Kb.

At least on NT-based versions of Windows the clipboard works in Unicode wide characters, so encodings are likely not to work as one might expect.

### Note

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.

### References

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

### See Also

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

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

To flush output to the console, see `flush.console`.

### Examples

    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)

[Package base version 2.3.1 Index]