seek                  package:base                  R Documentation

_F_u_n_c_t_i_o_n_s _t_o _R_e_p_o_s_i_t_i_o_n _C_o_n_n_e_c_t_i_o_n_s

_D_e_s_c_r_i_p_t_i_o_n:

     Functions to re-position connections.

_U_s_a_g_e:

     seek(con, ...)
     ## S3 method for class 'connection':
     seek(con, where = NA, origin = "start", rw = "", ...)

     isSeekable(con)

     truncate(con, ...)

_A_r_g_u_m_e_n_t_s:

     con: a connection.

   where: numeric.  A file position (relative to the origin specified
          by 'origin'), or 'NA'.

      rw: character.  Empty or '"read"' or '"write"', partial matches
          allowed.

  origin: character.  One of '"start"', '"current"', '"end"': see
          'Details'.

     ...: further arguments passed to or from other methods.

_D_e_t_a_i_l_s:

     'seek' with 'where = NA' returns the current byte offset of a
     connection (from the beginning), and with a non-missing 'where'
     argument the connection is re-positioned (if possible) to the
     specified position. 'isSeekable' returns whether the connection in
     principle supports 'seek': currently only (possibly gz-compressed)
     file connections do.  'gzfile' connections do not support 'origin
     = "end"'; the file position they use is that of the uncompressed
     file.

     '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 '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
     'seek' refers to can be set by its '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 '"r+"' and '"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 'seek' is called with a non-'NA' value of 'where', any pushback
     on a text-mode connection is discarded.

     'truncate' truncates a file opened for writing at its current
     position.  It works only for 'file' connections, and is not
     implemented on all platforms: on others (including Windows) it
     will not work for large (> 2Gb) files.

_V_a_l_u_e:

     'seek' returns the current position (before any move), as a
     (numeric) byte offset from the origin, if relevant, or '0' if not.
      Note that the position can exceed the largest representable
     number in an R 'integer' on 64-bit OSes, and on some 32-bit OSes.

     'truncate' returns 'NULL': it stops with an error if it fails (or
     is not implemented).

     'isSeekable' returns a logical value, whether the connection
     supports 'seek'.

_S_e_e _A_l_s_o:

     'connections'