diff options
| -rw-r--r-- | doc/chan.n | 44 | ||||
| -rw-r--r-- | doc/close.n | 1 | ||||
| -rw-r--r-- | doc/seek.n | 66 | ||||
| -rw-r--r-- | doc/tell.n | 30 |
4 files changed, 46 insertions, 95 deletions
@@ -814,7 +814,44 @@ set data [chan read $f $numDataBytes] close $f .CE - +.SS "FILE SEEK EXAMPLES" +.PP +Read a file twice: +.PP +.CS +set f [open file.txt] +set data1 [chan read $f] +\fBchan seek\fR $f 0 +set data2 [chan read $f] +chan close $f +# $data1 eq $data2 if the file wasn't updated +.CE +.PP +Read the last 10 bytes from a file: +.PP +.CS +set f [open file.data] +# This is guaranteed to work with binary data but +# may fail with other encodings... +chan configure $f -translation binary +\fBchan seek\fR $f -10 end +set data [chan read $f 10] +chan close $f +.CE +.PP +Read a line from a file channel only if it starts with \fBfoobar\fR: +.PP +.CS +# Save the offset in case we need to undo the read... +set offset [\fBtell\fR $chan] +if {[read $chan 6] eq "foobar"} { + gets $chan line +} else { + set line {} + # Undo the read... + seek $chan $offset +} +.CE .SS "ENCODING ERROR EXAMPLES" .PP The example below illustrates handling of an encoding error encountered @@ -980,10 +1017,11 @@ vwait done .SH "SEE ALSO" close(n), eof(n), fblocked(n), fconfigure(n), fcopy(n), file(n), fileevent(n), flush(n), gets(n), open(n), puts(n), read(n), seek(n), -socket(n), tell(n), refchan(n), transchan(n) +socket(n), tell(n), refchan(n), transchan(n), +Tcl_StandardChannels(3) .SH KEYWORDS blocking, channel, end of file, events, input, non-blocking, -offset, output, readable, writable +offset, output, readable, seek, stdio, tell, writable '\" Local Variables: '\" mode: nroff '\" End: diff --git a/doc/close.n b/doc/close.n index 900679e..0851608 100644 --- a/doc/close.n +++ b/doc/close.n @@ -15,6 +15,7 @@ close \- Close an open channel \fBclose \fIchannelId\fR ?\fBr\fR(\fBead\fR)|\fBw\fR(\fBrite\fR)? .BE .SH DESCRIPTION +.PP The \fBclose\fR command has been superceded by the \fBchan close\fR command and supports the same syntax and options. .SH "SEE ALSO" @@ -16,70 +16,10 @@ seek \- Change the access position for an open channel .BE .SH DESCRIPTION .PP -Changes the current access position for \fIchannelId\fR. -.PP -\fIChannelId\fR must be an identifier for an open channel such as a -Tcl standard channel (\fBstdin\fR, \fBstdout\fR, or \fBstderr\fR), -the return value from an invocation of \fBopen\fR or \fBsocket\fR, or -the result of a channel creation command provided by a Tcl extension. -.PP -The \fIoffset\fR and \fIorigin\fR -arguments specify the position at which the next read or write will occur -for \fIchannelId\fR. \fIOffset\fR must be an integer (which may be -negative) and \fIorigin\fR must be one of the following: -.IP \fBstart\fR 10 -The new access position will be \fIoffset\fR bytes from the start -of the underlying file or device. -.IP \fBcurrent\fR 10 -The new access position will be \fIoffset\fR bytes from the current -access position; a negative \fIoffset\fR moves the access position -backwards in the underlying file or device. -.IP \fBend\fR 10 -The new access position will be \fIoffset\fR bytes from the end of -the file or device. A negative \fIoffset\fR places the access position -before the end of file, and a positive \fIoffset\fR places the access -position after the end of file. -.PP -The \fIorigin\fR argument defaults to \fBstart\fR. -.PP -The command flushes all buffered output for the channel before the command -returns, even if the channel is in non-blocking mode. -It also discards any buffered and unread input. -This command returns an empty string. -An error occurs if this command is applied to channels whose underlying -file or device does not support seeking. -.PP -Note that \fIoffset\fR values are byte offsets, not character -offsets. Both \fBseek\fR and \fBtell\fR operate in terms of bytes, -not characters, unlike \fBread\fR. -.SH EXAMPLES -.PP -Read a file twice: -.PP -.CS -set f [open file.txt] -set data1 [read $f] -\fBseek\fR $f 0 -set data2 [read $f] -close $f -# $data1 eq $data2 if the file wasn't updated -.CE -.PP -Read the last 10 bytes from a file: -.PP -.CS -set f [open file.data] -# This is guaranteed to work with binary data but -# may fail with other encodings... -fconfigure $f -translation binary -\fBseek\fR $f -10 end -set data [read $f 10] -close $f -.CE +The \fBseek\fR command has been superceded by the \fBchan seek\fR +command and supports the same syntax and options. .SH "SEE ALSO" -file(n), open(n), close(n), gets(n), tell(n), Tcl_StandardChannels(3) -.SH KEYWORDS -access position, file, seek +chan(n) '\" Local Variables: '\" mode: nroff '\" fill-column: 78 @@ -16,36 +16,8 @@ tell \- Return current access position for an open channel .BE .SH DESCRIPTION .PP -Returns an integer giving the current access position in -\fIchannelId\fR. This value returned is a byte offset that can be passed to -\fBseek\fR in order to set the channel to a particular position. Note -that this value is in terms of bytes, not characters like \fBread\fR. -The value returned is -1 for channels that do not support -seeking. -.PP -\fIChannelId\fR must be an identifier for an open channel such as a -Tcl standard channel (\fBstdin\fR, \fBstdout\fR, or \fBstderr\fR), -the return value from an invocation of \fBopen\fR or \fBsocket\fR, or -the result of a channel creation command provided by a Tcl extension. -.SH EXAMPLE -.PP -Read a line from a file channel only if it starts with \fBfoobar\fR: -.PP -.CS -# Save the offset in case we need to undo the read... -set offset [\fBtell\fR $chan] -if {[read $chan 6] eq "foobar"} { - gets $chan line -} else { - set line {} - # Undo the read... - seek $chan $offset -} -.CE .SH "SEE ALSO" -file(n), open(n), close(n), gets(n), seek(n), Tcl_StandardChannels(3) -.SH KEYWORDS -access position, channel, seeking +chan(n) '\" Local Variables: '\" mode: nroff '\" fill-column: 78 |