1fconfigure(n) Tcl Built-In Commands fconfigure(n)
2______________________________________________________________________________
6
8 fconfigure - Set and get options on a channel
9
11 fconfigure channelId
12 fconfigure channelId name
13 fconfigure channelId name value ?name value ...?
14______________________________________________________________________________
15
17 The fconfigure command sets and retrieves options for channels.
18 ChannelId identifies the channel for which to set or query an option
20 and must refer to an open channel such as a Tcl standard channel
21 (stdin, stdout, or stderr), the return value from an invocation of open
22 or socket, or the result of a channel creation command provided by a
23 Tcl extension.
24 If no name or value arguments are supplied, the command returns a list
26 containing alternating option names and values for the channel. If
27 name is supplied but no value then the command returns the current
28 value of the given option. If one or more pairs of name and value are
29 supplied, the command sets each of the named options to the correspond‐
30 ing value; in this case the return value is an empty string.
31 The options described below are supported for all channels. In addi‐
33 tion, each channel type may add options that only it supports. See the
34 manual entry for the command that creates each type of channels for the
35 options that that specific type of channel supports. For example, see
36 the manual entry for the socket command for additional options for
37 sockets, and the open command for additional options for serial de‐
38 vices.
39 -blocking boolean
41 The -blocking option determines whether I/O operations on the
42 channel can cause the process to block indefinitely. The value
43 of the option must be a proper boolean value. Channels are nor‐
44 mally in blocking mode; if a channel is placed into nonblocking
45 mode it will affect the operation of the gets, read, puts,
46 flush, and close commands by allowing them to operate asyn‐
47 chronously; see the documentation for those commands for de‐
48 tails. For nonblocking mode to work correctly, the application
49 must be using the Tcl event loop (e.g. by calling Tcl_DoOneEvent
50 or invoking the vwait command).
51 -buffering newValue
53 If newValue is full then the I/O system will buffer output until
54 its internal buffer is full or until the flush command is in‐
55 voked. If newValue is line, then the I/O system will automati‐
56 cally flush output for the channel whenever a newline character
57 is output. If newValue is none, the I/O system will flush auto‐
58 matically after every output operation. The default is for
59 -buffering to be set to full except for channels that connect to
60 terminal-like devices; for these channels the initial setting is
61 line. Additionally, stdin and stdout are initially set to line,
62 and stderr is set to none.
63 -buffersize newSize
65 Newvalue must be an integer; its value is used to set the size
66 of buffers, in bytes, subsequently allocated for this channel to
67 store input or output. Newvalue must be between one and one mil‐
68 lion, allowing buffers of one to one million bytes in size.
69 -encoding name
71 This option is used to specify the encoding of the channel, so
72 that the data can be converted to and from Unicode for use in
73 Tcl. For instance, in order for Tcl to read characters from a
74 Japanese file in shiftjis and properly process and display the
75 contents, the encoding would be set to shiftjis. Thereafter,
76 when reading from the channel, the bytes in the Japanese file
77 would be converted to Unicode as they are read. Writing is also
78 supported - as Tcl strings are written to the channel they will
79 automatically be converted to the specified encoding on output.
80 If a file contains pure binary data (for instance, a JPEG im‐
82 age), the encoding for the channel should be configured to be
83 binary. Tcl will then assign no interpretation to the data in
84 the file and simply read or write raw bytes. The Tcl binary
85 command can be used to manipulate this byte-oriented data. It
86 is usually better to set the -translation option to binary when
87 you want to transfer binary data, as this turns off the other
88 automatic interpretations of the bytes in the stream as well.
89 The default encoding for newly opened channels is the same plat‐
91 form- and locale-dependent system encoding used for interfacing
92 with the operating system, as returned by encoding system.
93 -eofchar char
95 -eofchar {inChar outChar}
97 This option supports DOS file systems that use Control-z (\x1A)
98 as an end of file marker. If char is not an empty string, then
99 this character signals end-of-file when it is encountered during
100 input. For output, the end-of-file character is output when the
101 channel is closed. If char is the empty string, then there is
102 no special end of file character marker. For read-write chan‐
103 nels, a two-element list specifies the end of file marker for
104 input and output, respectively. As a convenience, when setting
105 the end-of-file character for a read-write channel you can spec‐
106 ify a single value that will apply to both reading and writing.
107 When querying the end-of-file character of a read-write channel,
108 a two-element list will always be returned. The default value
109 for -eofchar is the empty string in all cases except for files
110 under Windows. In that case the -eofchar is Control-z (\x1A)
111 for reading and the empty string for writing. The acceptable
112 range for -eofchar values is \x01 - \x7F; attempting to set
113 -eofchar to a value outside of this range will generate an er‐
114 ror.
115 -translation mode
117 -translation {inMode outMode}
119 In Tcl scripts the end of a line is always represented using a
120 single newline character (\n). However, in actual files and de‐
121 vices the end of a line may be represented differently on dif‐
122 ferent platforms, or even for different devices on the same
123 platform. For example, under UNIX newlines are used in files,
124 whereas carriage-return-linefeed sequences are normally used in
125 network connections. On input (i.e., with gets and read) the
126 Tcl I/O system automatically translates the external end-of-line
127 representation into newline characters. Upon output (i.e., with
128 puts), the I/O system translates newlines to the external end-
129 of-line representation. The default translation mode, auto,
130 handles all the common cases automatically, but the -translation
131 option provides explicit control over the end of line transla‐
132 tions.
133 The value associated with -translation is a single item for
135 read-only and write-only channels. The value is a two-element
136 list for read-write channels; the read translation mode is the
137 first element of the list, and the write translation mode is the
138 second element. As a convenience, when setting the translation
139 mode for a read-write channel you can specify a single value
140 that will apply to both reading and writing. When querying the
141 translation mode of a read-write channel, a two-element list
142 will always be returned. The following values are currently
143 supported:
144 auto As the input translation mode, auto treats any of newline
146 (lf), carriage return (cr), or carriage return followed
147 by a newline (crlf) as the end of line representation.
148 The end of line representation can even change from line-
149 to-line, and all cases are translated to a newline. As
150 the output translation mode, auto chooses a platform spe‐
151 cific representation; for sockets on all platforms Tcl
152 chooses crlf, for all Unix flavors, it chooses lf, and
153 for the various flavors of Windows it chooses crlf. The
154 default setting for -translation is auto for both input
155 and output.
156 binary No end-of-line translations are performed. This is
158 nearly identical to lf mode, except that in addition bi‐
159 nary mode also sets the end-of-file character to the
160 empty string (which disables it) and sets the encoding to
161 binary (which disables encoding filtering). See the de‐
162 scription of -eofchar and -encoding for more information.
163 Internally, i.e. when it comes to the actual behaviour of
165 the translator this value is identical to lf and is
166 therefore reported as such when queried. Even if binary
167 was used to set the translation.
168 cr The end of a line in the underlying file or device is
170 represented by a single carriage return character. As
171 the input translation mode, cr mode converts carriage re‐
172 turns to newline characters. As the output translation
173 mode, cr mode translates newline characters to carriage
174 returns.
175 crlf The end of a line in the underlying file or device is
177 represented by a carriage return character followed by a
178 linefeed character. As the input translation mode, crlf
179 mode converts carriage-return-linefeed sequences to new‐
180 line characters. As the output translation mode, crlf
181 mode translates newline characters to carriage-return-
182 linefeed sequences. This mode is typically used on Win‐
183 dows platforms and for network connections.
184 lf The end of a line in the underlying file or device is
186 represented by a single newline (linefeed) character. In
187 this mode no translations occur during either input or
188 output. This mode is typically used on UNIX platforms.
189
191 The Tcl standard channels (stdin, stdout, and stderr) can be configured
192 through this command like every other channel opened by the Tcl li‐
193 brary. Beyond the standard options described above they will also sup‐
194 port any special option according to their current type. If, for exam‐
195 ple, a Tcl application is started by the inet super-server common on
196 Unix system its Tcl standard channels will be sockets and thus support
197 the socket options.
198
200 Instruct Tcl to always send output to stdout immediately, whether or
201 not it is to a terminal:
202 fconfigure stdout -buffering none
204 Open a socket and read lines from it without ever blocking the process‐
206 ing of other events:
207 set s [socket some.where.com 12345]
209 fconfigure $s -blocking 0
210 fileevent $s readable "readMe $s"
211 proc readMe chan {
212 if {[gets $chan line] < 0} {
213 if {[eof $chan]} {
214 close $chan
215 return
216 }
217 # Could not read a complete line this time; Tcl's
218 # internal buffering will hold the partial line for us
219 # until some more data is available over the socket.
220 } else {
221 puts stdout $line
222 }
223 }
224 Read a PPM-format image from a file:
226 # Open the file and put it into Unix ASCII mode
228 set f [open teapot.ppm]
229 fconfigure $f -encoding ascii -translation lf
230 # Get the header
232 if {[gets $f] ne "P6"} {
233 error "not a raw-bits PPM"
234 }
235 # Read lines until we have got non-comment lines
237 # that supply us with three decimal values.
238 set words {}
239 while {[llength $words] < 3} {
240 gets $f line
241 if {[string match "#*" $line]} continue
242 lappend words {*}[join [scan $line %d%d%d]]
243 }
244 # Those words supply the size of the image and its
246 # overall depth per channel. Assign to variables.
247 lassign $words xSize ySize depth
248 # Now switch to binary mode to pull in the data,
250 # one byte per channel (red,green,blue) per pixel.
251 fconfigure $f -translation binary
252 set numDataBytes [expr {3 * $xSize * $ySize}]
253 set data [read $f $numDataBytes]
254 close $f
256
258 close(n), flush(n), gets(n), open(n), puts(n), read(n), socket(n),
259 Tcl_StandardChannels(3)
260
262 blocking, buffering, carriage return, end of line, flushing, linemode,
263 newline, nonblocking, platform, translation, encoding, filter, byte ar‐
264 ray, binary
265Tcl 8.3 fconfigure(n)