diff options
Diffstat (limited to 'doc/fconfigure.n')
| -rw-r--r-- | doc/fconfigure.n | 157 |
1 files changed, 123 insertions, 34 deletions
diff --git a/doc/fconfigure.n b/doc/fconfigure.n index e2479e8a..ca23314 100644 --- a/doc/fconfigure.n +++ b/doc/fconfigure.n @@ -4,10 +4,8 @@ '\" See the file "license.terms" for information on usage and redistribution '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '\" -'\" RCS: @(#) $Id: fconfigure.n,v 1.3 1999/04/16 00:46:34 stanton Exp $ -'\" +.TH fconfigure n 8.3 Tcl "Tcl Built-In Commands" .so man.macros -.TH fconfigure n 8.1 Tcl "Tcl Built-In Commands" .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME @@ -19,11 +17,16 @@ fconfigure \- Set and get options on a channel \fBfconfigure \fIchannelId\fR \fIname value \fR?\fIname value ...\fR? .fi .BE - .SH DESCRIPTION .PP The \fBfconfigure\fR command sets and retrieves options for channels. -\fIChannelId\fR identifies the channel for which to set or query an option. +.PP +\fIChannelId\fR identifies the channel for which to set or query an +option and must refer to 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 If no \fIname\fR or \fIvalue\fR arguments are supplied, the command returns a list containing alternating option names and values for the channel. If \fIname\fR is supplied but no \fIvalue\fR then the command returns @@ -36,7 +39,8 @@ The options described below are supported for all channels. In addition, each channel type may add options that only it supports. See the manual entry for the command that creates each type of channels for the options that that specific type of channel supports. For example, see the manual -entry for the \fBsocket\fR command for its additional options. +entry for the \fBsocket\fR command for additional options for sockets, and +the \fBopen\fR command for additional options for serial devices. .TP \fB\-blocking\fR \fIboolean\fR The \fB\-blocking\fR option determines whether I/O operations on the @@ -44,7 +48,8 @@ channel can cause the process to block indefinitely. The value of the option must be a proper boolean value. Channels are normally in blocking mode; if a channel is placed into nonblocking mode it will affect the operation of the \fBgets\fR, -\fBread\fR, \fBputs\fR, \fBflush\fR, and \fBclose\fR commands; +\fBread\fR, \fBputs\fR, \fBflush\fR, and \fBclose\fR commands by +allowing them to operate asynchronously; see the documentation for those commands for details. For nonblocking mode to work correctly, the application must be using the Tcl event loop (e.g. by calling \fBTcl_DoOneEvent\fR or @@ -60,15 +65,15 @@ is output. If \fInewValue\fR is \fBnone\fR, the I/O system will flush automatically after every output operation. The default is for \fB\-buffering\fR to be set to \fBfull\fR except for channels that connect to terminal-like devices; for these channels the initial setting -is \fBline\fR. +is \fBline\fR. Additionally, \fBstdin\fR and \fBstdout\fR are +initially set to \fBline\fR, and \fBstderr\fR is set to \fBnone\fR. .TP \fB\-buffersize\fR \fInewSize\fR . \fINewvalue\fR must be an integer; its value is used to set the size of buffers, in bytes, subsequently allocated for this channel to store input -or output. \fINewvalue\fR must be between ten and one million, allowing -buffers of ten to one million bytes in size. -.VS 8.1 br +or output. \fINewvalue\fR must be between one and one million, allowing +buffers of one to one million bytes in size. .TP \fB\-encoding\fR \fIname\fR . @@ -86,13 +91,15 @@ If a file contains pure binary data (for instance, a JPEG image), the encoding for the channel should be configured to be \fBbinary\fR. Tcl will then assign no interpretation to the data in the file and simply read or write raw bytes. The Tcl \fBbinary\fR command can be used to manipulate this -byte-oriented data. +byte-oriented data. It is usually better to set the +\fB\-translation\fR option to \fBbinary\fR when you want to transfer +binary data, as this turns off the other automatic interpretations of +the bytes in the stream as well. .PP The default encoding for newly opened channels is the same platform- and locale-dependent system encoding used for interfacing with the operating -system. +system, as returned by \fBencoding system\fR. .RE -.VE .TP \fB\-eofchar\fR \fIchar\fR .TP @@ -112,6 +119,9 @@ channel, a two-element list will always be returned. The default value for \fB\-eofchar\fR is the empty string in all cases except for files under Windows. In that case the \fB\-eofchar\fR is Control-z (\ex1a) for reading and the empty string for writing. +The acceptable range for \fB\-eofchar\fR values is \ex01 - \ex7f; +attempting to set \fB\-eofchar\fR to a value outside of this range will +generate an error. .TP \fB\-translation\fR \fImode\fR .TP @@ -122,11 +132,11 @@ newline character (\en). However, in actual files and devices the end of a line may be represented differently on different platforms, or even for different devices on the same platform. For example, under UNIX newlines are used in files, whereas carriage-return-linefeed sequences are -normally used in network connections. On input (i.e., with \fBgets\fP -and \fBread\fP) the Tcl I/O system automatically translates the external +normally used in network connections. On input (i.e., with \fBgets\fR +and \fBread\fR) the Tcl I/O system automatically translates the external end-of-line representation into newline characters. Upon output (i.e., -with \fBputs\fP), the I/O system translates newlines to the external -end-of-line representation. The default translation mode, \fBauto\fP, +with \fBputs\fR), the I/O system translates newlines to the external +end-of-line representation. The default translation mode, \fBauto\fR, handles all the common cases automatically, but the \fB\-translation\fR option provides explicit control over the end of line translations. .RS @@ -144,41 +154,45 @@ currently supported: \fBauto\fR . As the input translation mode, \fBauto\fR treats any of newline -(\fBlf\fP), carriage return (\fBcr\fP), or carriage return followed by a -newline (\fBcrlf\fP) as the end of line representation. The end of line +(\fBlf\fR), carriage return (\fBcr\fR), or carriage return followed by a +newline (\fBcrlf\fR) as the end of line representation. The end of line representation can even change from line-to-line, and all cases are translated to a newline. As the output translation mode, \fBauto\fR chooses a platform specific representation; for sockets on all platforms -Tcl chooses \fBcrlf\fR, for all Unix flavors, it chooses \fBlf\fR, for the -Macintosh platform it chooses \fBcr\fR and for the various flavors of -Windows it chooses \fBcrlf\fR. The default setting for -\fB\-translation\fR is \fBauto\fR for both input and output. -.VS 8.1 br +Tcl chooses \fBcrlf\fR, for all Unix flavors, it chooses \fBlf\fR, and +for the various flavors of Windows it chooses \fBcrlf\fR. The default +setting for \fB\-translation\fR is \fBauto\fR for both input and output. .TP \fBbinary\fR . No end-of-line translations are performed. This is nearly identical to -\fBlf\fP mode, except that in addition \fBbinary\fP mode also sets the +\fBlf\fR mode, except that in addition \fBbinary\fR mode also sets the end-of-file character to the empty string (which disables it) and sets the encoding to \fBbinary\fR (which disables encoding filtering). See the description of \fB\-eofchar\fR and \fB\-encoding\fR for more information. -.VE +.RS +.PP +Internally, i.e. when it comes to the actual behaviour of the +translator this value \fBis\fR identical to \fBlf\fR and is therefore +reported as such when queried. Even if \fBbinary\fR was used to set +the translation. +.RE .TP \fBcr\fR . The end of a line in the underlying file or device is represented by a single carriage return character. As the input translation mode, -\fBcr\fP mode converts carriage returns to newline characters. As the -output translation mode, \fBcr\fP mode translates newline characters to -carriage returns. This mode is typically used on Macintosh platforms. +\fBcr\fR mode converts carriage returns to newline characters. As the +output translation mode, \fBcr\fR mode translates newline characters to +carriage returns. .TP \fBcrlf\fR . The end of a line in the underlying file or device is represented by a carriage return character followed by a linefeed character. As the input -translation mode, \fBcrlf\fP mode converts carriage-return-linefeed +translation mode, \fBcrlf\fR mode converts carriage-return-linefeed sequences to newline characters. As the output translation mode, -\fBcrlf\fP mode translates newline characters to carriage-return-linefeed +\fBcrlf\fR mode translates newline characters to carriage-return-linefeed sequences. This mode is typically used on Windows platforms and for network connections. .TP @@ -190,11 +204,86 @@ during either input or output. This mode is typically used on UNIX platforms. .RE .PP +.SH "STANDARD CHANNELS" +.PP +The Tcl standard channels (\fBstdin\fR, \fBstdout\fR, and \fBstderr\fR) +can be configured through this command like every other channel opened +by the Tcl library. Beyond the standard options described above they +will also support any special option according to their current type. +If, for example, a Tcl application is started by the \fBinet\fR +super-server common on Unix system its Tcl standard channels will be +sockets and thus support the socket options. +.SH EXAMPLES +.PP +Instruct Tcl to always send output to \fBstdout\fR immediately, +whether or not it is to a terminal: +.PP +.CS +\fBfconfigure\fR stdout -buffering none +.CE +.PP +Open a socket and read lines from it without ever blocking the +processing of other events: +.PP +.CS +set s [socket some.where.com 12345] +\fBfconfigure\fR $s -blocking 0 +fileevent $s readable "readMe $s" +proc readMe chan { + if {[gets $chan line] < 0} { + if {[eof $chan]} { + close $chan + return + } + # Could not read a complete line this time; Tcl's + # internal buffering will hold the partial line for us + # until some more data is available over the socket. + } else { + puts stdout $line + } +} +.CE +.PP +Read a PPM-format image from a file: +.PP +.CS +# Open the file and put it into Unix ASCII mode +set f [open teapot.ppm] +\fBfconfigure\fR $f \-encoding ascii \-translation lf -.SH "SEE ALSO" -close(n), flush(n), gets(n), puts(n), read(n), socket(n) +# Get the header +if {[gets $f] ne "P6"} { + error "not a raw\-bits PPM" +} +# Read lines until we have got non-comment lines +# that supply us with three decimal values. +set words {} +while {[llength $words] < 3} { + gets $f line + if {[string match "#*" $line]} continue + lappend words {*}[join [scan $line %d%d%d]] +} + +# Those words supply the size of the image and its +# overall depth per channel. Assign to variables. +lassign $words xSize ySize depth + +# Now switch to binary mode to pull in the data, +# one byte per channel (red,green,blue) per pixel. +\fBfconfigure\fR $f \-translation binary +set numDataBytes [expr {3 * $xSize * $ySize}] +set data [read $f $numDataBytes] + +close $f +.CE +.SH "SEE ALSO" +close(n), flush(n), gets(n), open(n), puts(n), read(n), socket(n), +Tcl_StandardChannels(3) .SH KEYWORDS blocking, buffering, carriage return, end of line, flushing, linemode, newline, nonblocking, platform, translation, encoding, filter, byte array, binary +'\" Local Variables: +'\" mode: nroff +'\" End: |