connection {base} | R Documentation

## Functions to Manipulate Connections

### Description

Functions to create, open, close and position connections.

### Usage

    file(description, open = "", blocking = TRUE)
    pipe(description, open = "")

    open(con, open = "rt", blocking = TRUE)
    close(con, type = "rw")
    seek(con, where = NA, rw = "")

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

### Arguments

`description` | character. A description of the connection. For `file` this is a path to the file to be opened. For a `textConnection` it is an R character vector object.
`open` | character. A description of how to open the connection (if at all). See Details for possible values.
`blocking` | logical. Currently ignored.
`type` | character. Currently ignored.
`where` | integer. A file position, or `NA`.
`rw` | character. Currently ignored.

### Details

The first two functions create connections. By default the connection is not opened, but may be opened by setting a non-empty value of argument `open`.

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

`close` closes and destroys a connection.

`seek` with `where = NA` returns the current byte offset of a connection (from the beginning), and with a positive `where` argument the connection is re-positioned (if possible) to the specified position. `isSeekable` returns whether the connection in principle supports `seek`: currently only file connections do.

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.

These are likely to change. Some connections (e.g. text connections) can only be opened for reading or writing. 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.

### Value

`file` and `pipe` return a connection object which inherits from class `"connection"`.
`seek` returns the current position, as a byte offset, if relevant.
`isOpen` returns a logical value, whether the connection is currently open.
`isIncomplete` returns a logical value, whether last read attempt was blocked (currently always false), ot for an output text connection whether there is unflushed output.

### Note

R's connections are modelled on those in S version 4 (see Chambers, 1998), but the implementation is currently incomplete. In particular:

- Pipes are only implemented on Unix and `Rterm` on Windows. Fifos are not yet implemented. We also envisage having connections to sockets.
- Svr4 has separate read and write positions for files: R does not.
- Svr4 allow an empty description to `file` to indicate an anonymous (temporary) file.

### References

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

### See Also

`textConnection`, `readLines`, `showConnections`, `pushBack`

### 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")

    ## Unix examples of use of pipes

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

    # remove trailing commas. Suppose
    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
    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)