tcl/doc/seek.n

   1 '\"
   2 '\" Copyright (c) 1993 The Regents of the University of California.
   3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
   4 '\"
   5 '\" See the file "license.terms" for information on usage and redistribution
   6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
   7 '\"
   8 '\" RCS: @(#) $Id$
   9 '\"
  10 .so man.macros
  11 .TH seek n 8.1 Tcl "Tcl Built-In Commands"
  12 .BS
  13 '\" Note:  do not modify the .SH NAME line immediately below!
  14 .SH NAME
  15 seek \- Change the access position for an open channel
  16 .SH SYNOPSIS
  17 \fBseek \fIchannelId offset \fR?\fIorigin\fR?
  18 .BE
  19
  20 .SH DESCRIPTION
  21 .PP
  22 Changes the current access position for \fIchannelId\fR.
  23 .PP
  24 .VS
  25 \fIChannelId\fR must be an identifier for an open channel such as a
  26 Tcl standard channel (\fBstdin\fR, \fBstdout\fR, or \fBstderr\fR),
  27 the return value from an invocation of \fBopen\fR or \fBsocket\fR, or
  28 the result of a channel creation command provided by a Tcl extension.
  29 .VE
  30 .PP
  31 The \fIoffset\fR and \fIorigin\fR
  32 arguments specify the position at which the next read or write will occur
  33 for \fIchannelId\fR. \fIOffset\fR must be an integer (which may be
  34 negative) and \fIorigin\fR must be one of the following:
  35 .TP 10
  36 \fBstart\fR
  37 The new access position will be \fIoffset\fR bytes from the start
  38 of the underlying file or device.
  39 .TP 10
  40 \fBcurrent\fR
  41 The new access position will be \fIoffset\fR bytes from the current
  42 access position; a negative \fIoffset\fR moves the access position
  43 backwards in the underlying file or device.
  44 .TP 10
  45 \fBend\fR
  46 The new access position will be \fIoffset\fR bytes from the end of
  47 the file or device.  A negative \fIoffset\fR places the access position
  48 before the end of file, and a positive \fIoffset\fR places the access
  49 position after the end of file.
  50 .LP
  51 The \fIorigin\fR argument defaults to \fBstart\fR.
  52 .PP
  53 The command flushes all buffered output for the channel before the command
  54 returns, even if the channel is in nonblocking mode.
  55 It also discards any buffered and unread input.
  56 This command returns an empty string.
  57 An error occurs if this command is applied to channels whose underlying
  58 file or device does not support seeking.
  59 .PP
  60 .VS 8.1
  61 Note that \fIoffset\fR values are byte offsets, not character
  62 offsets.  Both \fBseek\fR and \fBtell\fR operate in terms of bytes,
  63 not characters, unlike \fBread\fR.
  64 .VE 8.1
  65
  66 .SH "SEE ALSO"
  67 file(n), open(n), close(n), gets(n), tell(n), Tcl_StandardChannels(3)
  68
  69 .SH KEYWORDS
  70 access position, file, seek