| connections {base} | R Documentation |
Functions to create, open and close connections.
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)
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. |
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’: such connections can
only be binary.
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""w" or "wt""a" or "at""rb""wb""ab""r+", "r+b""w+", "w+b""a+", "a+b"
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.
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.
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.
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 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().
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
(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.
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.
Chambers, J. M. (1998) Programming with Data. A Guide to the S Language. Springer.
textConnection, seek, readLines,
readBin, writeLines, writeBin,
showConnections, pushBack.
capabilities to see if url,
fifo and socketConnection are supported by this build of R.
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)