Connection Objects

USAGE:

file(description, open="", blocking=T)
pipe(description, open="", blocking=T)
fifo(description, open="", blocking=F)
textConnection(object, open="")
open(object, ...)
close(con, type="rw")
stdin(); stdout(); stderr(); clipboardConnection(open="")

ARGUMENTS:

description
A character string describing the desired connection. For a file, this is a path; for a pipe, it is a shell command; for a fifo (a.k.a. a named pipe), it is a path name to be used as a pipe.

For files and fifos, description may be missing. This is the recommended way to create unnamed files or fifos, when communication is only needed within the S process. What actually happens is that an unused path name is generated (by tempfile()), and opened. On exit from file() or fifo(), the file is unlinked, but the opened connection remains available throughout the S session. Unnamed connections are only useful if they can be both written on and read from, so the mode is assumed to be "rw".
open
should the connection be opened, and optionally a mode to describe how it is to be used. By default, the connection object is created but not opened. This causes S functions that do reading or writing to open the connection and then to close it again on exit. If open is TRUE, S opens the connection in a standard way: for both read and write if the user has permissions to do so, or for read-only if the user does not have write permission. In the case of a file or fifo, any data on the file is preserved. The newly opened connection is positioned at the beginning for reading and at the end for writing (but seek() can be used on files to change either position). This argument can also be supplied as a string (see "Posix modes" below), if you want to force other behavior (e.g., to only allow reading or to open in binary mode).
blocking
Should input or output on the connection be blocking; that is, when pread() or pwrite() is called, should the S process block until the desired input or output is complete.
object
For textConnection(), any S object to be treated as a character vector, equivalently to reading each element of the character vector as a line of input; otherwise, a connection object.
con
A connection object.
...
Optional arguments to open() are interpreted as the open mode and blocking arguments to file(), etc., depending on the class of the connection object. If no second argument is given, open() opens the connection in the default mode (read/write if allowed, otherwise read).

VALUE:

The first four functions create a connection object corresponding to the description (or in the case of textConnection(), the object) given and, optionally, open the connection for input and/or output. If the open argument is supplied, it should be a logical value to say whether to open the connection, or a character string if some non-default mode is needed (see "Posix modes" below). Connections need not be opened when they are created. The generic function open() can be used to open a connection later on, or the connection object can be handed unopened to basic input/output functions. The general rule followed by these functions is that an unopened connection will be opened by the function as required and closed again when the function exits. If the connection is already opened, it will be left open. The function close() closes the connection explicitly. Programming with explicitly opened connections should always arrange to close the connections, typically by a use of on.exit(). Connections use up operating system resources (streams) of which there is a non-trivially finite number.

The functions stdin(), stdout(), stderr() and clipboardConnection() return the connection objects associated with standard input, standard output, standard error (all in the Unix sense), and the system clipboard, for the S process. These are best thought of as constants (although sink() changes the interpretation of the standard output as a connection).

DETAILS:

The clipboard connection allows read and write access of the system clipboard; it is currently only implemented on Windows, but is reserved for future use on Unix. With a few exceptions, when any S function references the clipboard, it acts as if the clipboard were opened at the beginning of the top-level expression (the command issued at the S prompt) and closed at the end of the top-level expression. That is, reading starts with the first character on the clipboard, and writing discards any previously existing clipboard data; also, the entire contents of the clipboard are read at once, and are not re-read unless a seek(rw="r") to a previous position (or position 0) is made. The exceptions are readLines(), which reads from the current read position, and writeLines() and cat(append=T), which always append to existing clipboard data. When passed as an argument to a function expecting a connection, "clipboard" can be specified instead of clipboardConnection().

Posix modes:
The open argument can be specified as a string. The default corresponds to "*" (thought of as meaning "anything I'm allowed to do"). Other strings correspond to various read and write permissions: the string "r" opens the connection for read-only, "w" opens it for writing, and "rw" opens it for both reading and writing. In both the latter two cases, the file is truncated if it already existed. To always append to the existing file on writes, use "a" in place of "w" in either case. Notice that this differs from the default "*" in that you can not use seek() to move back and overwrite existing data. Adding "b" to the end of the mode string means to open the file in binary mode so that on Windows newlines are not converted to newline-returns. This is required if you going to use readRaw or writeRaw on the connection.

NOTES:

read.table() generally has problems with connection objects, mainly because it reads a file twice (once to count the number of fields in each line and once to get the data).

SEE ALSO:

Functions to use connections include: , , , , , , , . For more on manipulating connections, see and .

EXAMPLES:

### parse an expression from a file, then read some data starting 
### at the next line of the file 
con <- file("mydata", "r") 
expr <- parse(con, 1) 
data <- scan(con) 
close(con) 
### clear the clipboard, then wait until another process writes to the clipboard
cat("", file=clipboardConnection())
while(length(readLines(clipboardConnection())) == 0) {
        sleep(1)
        seek(clipboardConnection(), 0, "r")
}
### Create an unnamed fifo object to be used for reading 
### and writing. 
myFifo <- fifo() 
setReader(myFifo, function(con) ## read data and do something.. 
 ...