\HeaderA{seek}{Functions to Reposition Connections}{seek}
\aliasA{isSeekable}{seek}{isSeekable}
\methaliasA{seek.connection}{seek}{seek.connection}
\aliasA{truncate}{seek}{truncate}
\methaliasA{truncate.connection}{seek}{truncate.connection}
\keyword{file}{seek}
\keyword{connection}{seek}
\begin{Description}\relax
Functions to re-position connections.
\end{Description}
\begin{Usage}
\begin{verbatim}
seek(con, ...)
## S3 method for class 'connection':
seek(con, where = NA, origin = "start", rw = "", ...)

isSeekable(con)

truncate(con, ...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{con}] a connection.
\item[\code{where}] numeric.  A file position (relative to the origin
specified by \code{origin}), or \code{NA}.
\item[\code{rw}] character.  Empty or \code{"read"} or \code{"write"},
partial matches allowed.
\item[\code{origin}] character.  One of \code{"start"}, \code{"current"},
\code{"end"}: see \sQuote{Details}.
\item[\code{...}] further arguments passed to or from other methods.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
\code{seek} with \code{where = NA} returns the current byte offset
of a connection (from the beginning), and with a non-missing \code{where}
argument the connection is re-positioned (if possible) to the
specified position. \code{isSeekable} returns whether the connection
in principle supports \code{seek}: currently only (possibly
gz-compressed) file connections do.  \code{gzfile} connections do not
support \code{origin = "end"}; the file position they use is that
of the uncompressed file.

\code{where} is stored as a real but should represent an integer:
non-integer values are likely to be truncated.  Note that the possible
values can exceed the largest representable number in an \R{}
\code{integer} on 64-bit OSes, and on some 32-bit OSes.


File connections can be open for both writing/appending, in which case
\R{} keeps separate positions for reading and writing.  Which \code{seek}
refers to can be set by its \code{rw} argument: the default is the
last mode (reading or writing) which was used.  Most files are
only opened for reading or writing and so default to that state.  If a
file is open for both reading and writing but has not been used, the
default is to give the reading position (0).

The initial file position for reading is always at the beginning.
The initial position for writing is at the beginning of the file
for modes \code{"r+"} and \code{"r+b"}, otherwise at the end of the
file.  Some platforms only allow writing at the end of the file in
the append modes.  (The reported write position for a file opened in
an append mode will typically be unreliable until the file has been
written to.)

If \code{seek} is called with a non-\code{NA} value of \code{where},
any pushback on a text-mode connection is discarded.

\code{truncate} truncates a file opened for writing at its current
position.  It works only for \code{file} connections, and is not
implemented on all platforms: on others (including Windows) it will
not work for large (> 2Gb) files.
\end{Details}
\begin{Value}
\code{seek} returns the current position (before any move), as a
(numeric) byte offset from the origin, if relevant, or \code{0} if
not.  Note that the position can exceed the largest representable
number in an \R{} \code{integer} on 64-bit OSes, and on some 32-bit
OSes.

\code{truncate} returns \code{NULL}: it stops with an error if
it fails (or is not implemented).

\code{isSeekable} returns a logical value, whether the connection
supports \code{seek}.
\end{Value}
\begin{SeeAlso}\relax
\code{\LinkA{connections}{connections}}
\end{SeeAlso}

