rawConnection.Rd 2.1 KB
Newer Older
Radford Neal's avatar
Radford Neal committed
1 2
% File src/library/base/man/rawConnection.Rd
% Part of the R package, http://www.R-project.org
3
% Copyright 1995-2008 R Core Team
Radford Neal's avatar
Radford Neal committed
4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72
% Distributed under GPL 2 or later

\name{rawConnection}
\alias{rawConnection}
\alias{rawConnectionValue}
\title{Raw Connections}
\description{
  Input and output raw connections.
}
\usage{
rawConnection(object, open = "r")

rawConnectionValue(con)
}
\arguments{
  \item{object}{character or raw vector.  A description of the connection. 
    For an input this is an \R raw vector object, and for an output
    connection the name for the connection.
  }
  \item{open}{character.  Any of the standard connection open modes.}
  \item{con}{An output raw connection.}
}
\details{
  An input raw connection is opened and the raw vector is copied
  at the time the connection object is created, and \code{close}
  destroys the copy.

  An output raw connection is opened and creates an \R raw vector
  internally.  The raw vector can be retrieved \emph{via} 
  \code{rawConnectionValue}.

  If a connection is open for both input and output the initial raw
  vector supplied is copied when the connections is open
}

\value{
  For \code{rawConnection}, a connection object of class
  \code{"rawConnection"} which inherits from class \code{"connection"}.

  For \code{rawConnectionValue}, a raw vector.
}

\note{
  As output raw connections keep the internal raw vector up to date
  call-by-call, they are relatively expensive to use (although
  over-allocation is used), and it may be better to use an anonymous
  \code{\link{file}()} connection to collect output.

  On (rare) platforms where \code{vsnprintf} does not return the needed length
  of output there is a 100,000 character limit on the length of line for
  output connections: longer lines will be truncated with a warning.
}
 
\seealso{
  \code{\link{connections}}, \code{\link{showConnections}}.
}

\examples{
zz <- rawConnection(raw(0), "r+") # start with empty raw vector
writeBin(LETTERS, zz)
seek(zz, 0)
readLines(zz) # raw vector has embedded nuls
seek(zz, 0)
writeBin(letters[1:3], zz)
rawConnectionValue(zz)
close(zz)
}
\keyword{file}
\keyword{connection}