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 its additional options.
37 -blocking boolean
39 The -blocking option determines whether I/O operations on the
40 channel can cause the process to block indefinitely. The value
41 of the option must be a proper boolean value. Channels are nor‐
42 mally in blocking mode; if a channel is placed into nonblocking
43 mode it will affect the operation of the gets, read, puts,
44 flush, and close commands; see the documentation for those com‐
45 mands for details. For nonblocking mode to work correctly, the
46 application must be using the Tcl event loop (e.g. by calling
47 Tcl_DoOneEvent or invoking the vwait command).
48 -buffering newValue
50 If newValue is full then the I/O system will buffer output until
51 its internal buffer is full or until the flush command is
52 invoked. If newValue is line, then the I/O system will automati‐
53 cally flush output for the channel whenever a newline character
54 is output. If newValue is none, the I/O system will flush auto‐
55 matically after every output operation. The default is for
56 -buffering to be set to full except for channels that connect to
57 terminal-like devices; for these channels the initial setting is
58 line. Additionally, stdin and stdout are initially set to line,
59 and stderr is set to none.
60 -buffersize newSize
62 Newvalue must be an integer; its value is used to set the size
63 of buffers, in bytes, subsequently allocated for this channel to
64 store input or output. Newvalue must be between ten and one mil‐
65 lion, allowing buffers of ten to one million bytes in size.
66 -encoding name
68 This option is used to specify the encoding of the channel, so
69 that the data can be converted to and from Unicode for use in
70 Tcl. For instance, in order for Tcl to read characters from a
71 Japanese file in shiftjis and properly process and display the
72 contents, the encoding would be set to shiftjis. Thereafter,
73 when reading from the channel, the bytes in the Japanese file
74 would be converted to Unicode as they are read. Writing is also
75 supported - as Tcl strings are written to the channel they will
76 automatically be converted to the specified encoding on output.
77 If a file contains pure binary data (for instance, a JPEG
79 image), the encoding for the channel should be configured to be
80 binary. Tcl will then assign no interpretation to the data in
81 the file and simply read or write raw bytes. The Tcl binary
82 command can be used to manipulate this byte-oriented data.
83 The default encoding for newly opened channels is the same plat‐
85 form- and locale-dependent system encoding used for interfacing
86 with the operating system.
87 -eofchar char
89 -eofchar {inChar outChar}
91 This option supports DOS file systems that use Control-z (\x1a)
92 as an end of file marker. If char is not an empty string, then
93 this character signals end-of-file when it is encountered during
94 input. For output, the end-of-file character is output when the
95 channel is closed. If char is the empty string, then there is
96 no special end of file character marker. For read-write chan‐
97 nels, a two-element list specifies the end of file marker for
98 input and output, respectively. As a convenience, when setting
99 the end-of-file character for a read-write channel you can spec‐
100 ify a single value that will apply to both reading and writing.
101 When querying the end-of-file character of a read-write channel,
102 a two-element list will always be returned. The default value
103 for -eofchar is the empty string in all cases except for files
104 under Windows. In that case the -eofchar is Control-z (\x1a)
105 for reading and the empty string for writing.
106 -translation mode
108 -translation {inMode outMode}
110 In Tcl scripts the end of a line is always represented using a
111 single newline character (\n). However, in actual files and
112 devices the end of a line may be represented differently on dif‐
113 ferent platforms, or even for different devices on the same
114 platform. For example, under UNIX newlines are used in files,
115 whereas carriage-return-linefeed sequences are normally used in
116 network connections. On input (i.e., with gets and read) the
117 Tcl I/O system automatically translates the external end-of-line
118 representation into newline characters. Upon output (i.e., with
119 puts), the I/O system translates newlines to the external end-
120 of-line representation. The default translation mode, auto,
121 handles all the common cases automatically, but the -translation
122 option provides explicit control over the end of line transla‐
123 tions.
124 The value associated with -translation is a single item for
126 read-only and write-only channels. The value is a two-element
127 list for read-write channels; the read translation mode is the
128 first element of the list, and the write translation mode is the
129 second element. As a convenience, when setting the translation
130 mode for a read-write channel you can specify a single value
131 that will apply to both reading and writing. When querying the
132 translation mode of a read-write channel, a two-element list
133 will always be returned. The following values are currently
134 supported:
135 auto As the input translation mode, auto treats any of newline
137 (lf), carriage return (cr), or carriage return followed
138 by a newline (crlf) as the end of line representation.
139 The end of line representation can even change from line-
140 to-line, and all cases are translated to a newline. As
141 the output translation mode, auto chooses a platform spe‐
142 cific representation; for sockets on all platforms Tcl
143 chooses crlf, for all Unix flavors, it chooses lf, for
144 the Macintosh platform it chooses cr and for the various
145 flavors of Windows it chooses crlf. The default setting
146 for -translation is auto for both input and output.
147 binary No end-of-line translations are performed. This is
149 nearly identical to lf mode, except that in addition
150 binary mode also sets the end-of-file character to the
151 empty string (which disables it) and sets the encoding to
152 binary (which disables encoding filtering). See the
153 description of -eofchar and -encoding for more informa‐
154 tion.
155 Internally, i.e. when it comes to the actual behaviour of
157 the translator this value is identical to lf and is
158 therefore reported as such when queried. Even if binary
159 was used to set the translation.
160 cr The end of a line in the underlying file or device is
162 represented by a single carriage return character. As
163 the input translation mode, cr mode converts carriage
164 returns to newline characters. As the output translation
165 mode, cr mode translates newline characters to carriage
166 returns. This mode is typically used on Macintosh plat‐
167 forms.
168 crlf The end of a line in the underlying file or device is
170 represented by a carriage return character followed by a
171 linefeed character. As the input translation mode, crlf
172 mode converts carriage-return-linefeed sequences to new‐
173 line characters. As the output translation mode, crlf
174 mode translates newline characters to carriage-return-
175 linefeed sequences. This mode is typically used on Win‐
176 dows platforms and for network connections.
177 lf The end of a line in the underlying file or device is
179 represented by a single newline (linefeed) character. In
180 this mode no translations occur during either input or
181 output. This mode is typically used on UNIX platforms.
182
184 The Tcl standard channels (stdin, stdout, and stderr) can be configured
185 through this command like every other channel opened by the Tcl
186 library. Beyond the standard options described above they will also
187 support any special option according to their current type. If, for
188 example, a Tcl application is started by the inet super-server common
189 on Unix system its Tcl standard channels will be sockets and thus sup‐
190 port the socket options.
191
193 Instruct Tcl to always send output to stdout immediately, whether or
194 not it is to a terminal:
195 fconfigure stdout -buffering none
196 Open a socket and read lines from it without ever blocking the process‐
198 ing of other events:
199 set s [socket some.where.com 12345]
200 fconfigure $s -blocking 0
201 fileevent $s readable "readMe $s"
202 proc readMe chan {
203 if {[gets $chan line] < 0} {
204 if {[eof $chan]} {
205 close $chan
206 return
207 }
208 # Could not read a complete line this time; Tcl's
209 # internal buffering will hold the partial line for us
210 # until some more data is available over the socket.
211 } else {
212 puts stdout $line
213 }
214 }
215 Read a PPM-format image from a file:
217 # Open the file and put it into Unix ASCII mode
218 set f [open teapot.ppm]
219 fconfigure $f -encoding ascii -translation lf
220 # Get the header
222 if {[gets $f] ne "P6"} {
223 error "not a raw-bits PPM"
224 }
225 # Read lines until we have got non-comment lines
227 # that supply us with three decimal values.
228 set words {}
229 while {[llength $words] < 3} {
230 gets $f line
231 if {[string match "#*" $line]} continue
232 lappend words [eval concat [scan $line %d%d%d]]
233 }
234 # Those words supply the size of the image and its
236 # overall depth per channel. Assign to variables.
237 foreach {xSize ySize depth} $words {break}
238 # Now switch to binary mode to pull in the data,
240 # one byte per channel (red,green,blue) per pixel.
241 fconfigure $f -translation binary
242 set numDataBytes [expr {3 * $xSize * $ySize}]
243 set data [read $f $numDataBytes]
244 close $f
246
249 close(n), flush(n), gets(n), open(n), puts(n), read(n), socket(n),
250 Tcl_StandardChannels(3)
251
254 blocking, buffering, carriage return, end of line, flushing, linemode,
255 newline, nonblocking, platform, translation, encoding, filter, byte
256 array, binary
257Tcl 8.3 fconfigure(n)