| % File src/library/base/man/seek.Rd |
| % Part of the R package, https://www.R-project.org |
| % Copyright 1995-2015 R Core Team |
| % Distributed under GPL 2 or later |
| |
| \name{seek} |
| \alias{seek} |
| \alias{seek.connection} |
| \alias{truncate} |
| \alias{truncate.connection} |
| \alias{isSeekable} |
| \title{Functions to Reposition Connections} |
| \description{ |
| Functions to re-position connections. |
| } |
| \usage{ |
| seek(con, \dots) |
| \method{seek}{connection}(con, where = NA, origin = "start", rw = "", \dots) |
| |
| isSeekable(con) |
| |
| truncate(con, \dots) |
| } |
| \arguments{ |
| \item{con}{a \link{connection}.} |
| \item{where}{numeric. A file position (relative to the origin |
| specified by \code{origin}), or \code{NA}.} |
| \item{rw}{character string. Empty or \code{"read"} or \code{"write"}, |
| partial matches allowed.} |
| \item{origin}{character string. One of \code{"start"}, \code{"current"}, |
| \code{"end"}: see \sQuote{Details}.} |
| \item{\dots}{further arguments passed to or from other methods.} |
| } |
| \details{ |
| \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{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 builds, and on some 32-bit builds. |
| |
| 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.) |
| |
| \code{gzfile} connections support \code{seek} with a number of |
| limitations, using the file position of the uncompressed file. |
| They do not support \code{origin = "end"}. When writing, seeking is |
| only possible forwards: when reading seeking backwards is supported by |
| rewinding the file and re-reading from its start. |
| |
| 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. |
| |
| None of these should be expected to work on text-mode connections with |
| re-encoding selected. |
| } |
| \section{Warning}{ |
| Use of \code{seek} on Windows is discouraged. We have found so many |
| errors in the Windows implementation of file positioning that users |
| are advised to use it only at their own risk, and asked not to waste |
| the \R developers' time with bug reports on Windows' deficiencies. |
| } |
| \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 builds, and on some 32-bit |
| builds. |
| |
| \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}. |
| } |
| \seealso{ |
| \code{\link{connections}} |
| } |
| \keyword{file} |
| \keyword{connection} |