2 '\" Copyright (c) 1995-1996 Sun Microsystems, Inc.
4 '\" See the file "license.terms" for information on usage and redistribution
5 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
7 '\" RCS: @(#) $Id: fconfigure.n,v 1.4 1999/07/07 18:59:52 stanton Exp $
9 '\" The definitions below are for supplemental macros used in Tcl/Tk
12 '\" .AP type name in/out ?indent?
13 '\" Start paragraph describing an argument to a library procedure.
14 '\" type is type of argument (int, etc.), in/out is either "in", "out",
15 '\" or "in/out" to describe whether procedure reads or modifies arg,
16 '\" and indent is equivalent to second arg of .IP (shouldn't ever be
17 '\" needed; use .AS below instead)
20 '\" Give maximum sizes of arguments for setting tab stops. Type and
21 '\" name are examples of largest possible arguments that will be passed
22 '\" to .AP later. If args are omitted, default tab stops are used.
25 '\" Start box enclosure. From here until next .BE, everything will be
26 '\" enclosed in one large box.
29 '\" End of box enclosure.
32 '\" Begin code excerpt.
37 '\" .VS ?version? ?br?
38 '\" Begin vertical sidebar, for use in marking newly-changed parts
39 '\" of man pages. The first argument is ignored and used for recording
40 '\" the version when the .VS was added, so that the sidebars can be
41 '\" found and removed when they reach a certain age. If another argument
42 '\" is present, then a line break is forced before starting the sidebar.
45 '\" End of vertical sidebar.
48 '\" Begin an indented unfilled display.
51 '\" End of indented unfilled display.
54 '\" Start of list of standard options for a Tk widget. The
55 '\" options follow on successive lines, in four columns separated
59 '\" End of list of standard options for a Tk widget.
61 '\" .OP cmdName dbName dbClass
62 '\" Start of description of a specific option. cmdName gives the
63 '\" option's name as specified in the class command, dbName gives
64 '\" the option's name in the option database, and dbClass gives
65 '\" the option's class in the option database.
68 '\" Print arg1 underlined, then print arg2 normally.
70 '\" RCS: @(#) $Id: man.macros,v 1.3 1999/04/16 00:46:35 stanton Exp $
72 '\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
76 '\" # Start an argument description
80 . ie !"\\$2"" .TP \\n()Cu
85 \&\\$1 \\fI\\$2\\fP (\\$3)
98 '\" # define tabbing values for .AP
101 .if !"\\$1"" .nr )A \\w'\\$1'u+3n
104 .if !"\\$2"" .nr )B \\w'\\$2'u+\\n()Au+3n
105 .nr )C \\n()Bu+\\w'(in/out)'u+2n
107 .AS Tcl_Interp Tcl_CreateInterp in/out
108 '\" # BS - start boxed text
109 '\" # ^y = starting y location
117 .if n \l'\\n(.lu\(ul'
120 '\" # BE - end boxed text (draw box now)
125 .ie n \l'\\n(^lu\(ul'
127 .\" Draw four-sided box normally, but don't draw top of
128 .\" box if the box started on an earlier page.
130 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
133 \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\l'|0u-1.5n\(ul'
140 '\" # VS - start vertical sidebar
141 '\" # ^Y = starting y location
142 '\" # ^v = 1 (for troff; for nroff this doesn't matter)
146 .ie n 'mc \s12\(br\s0
149 '\" # VE - end of vertical sidebar
157 \h'|\\n(^lu+3n'\L'|\\n(^Yu-1v\(bv'\v'\\n(^tu+1v-\\n(^Yu'\h'-|\\n(^lu+3n'
164 '\" # Special macro to handle page bottom: finish off current
165 '\" # box/sidebar if in box/sidebar mode, then invoked standard
166 '\" # page bottom macro.
173 .\" Draw three-sided box if this is the box's first page,
174 .\" draw two sides but no top otherwise.
175 .ie !\\n(^b-1 \h'-1.5n'\L'|\\n(^yu-1v'\l'\\n(^lu+3n\(ul'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
176 .el \h'-1.5n'\L'|\\n(^yu-1v'\h'\\n(^lu+3n'\L'\\n(^tu+1v-\\n(^yu'\h'|0u'\c
179 .nr ^x \\n(^tu+1v-\\n(^Yu
180 \kx\h'-\\nxu'\h'|\\n(^lu+3n'\ky\L'-\\n(^xu'\v'\\n(^xu'\h'|0u'\c
193 '\" # DS - begin display
199 '\" # DE - end display
205 '\" # SO - start of list of standard options
207 .SH "STANDARD OPTIONS"
213 '\" # SE - end of list of standard options
218 See the \\fBoptions\\fR manual entry for details on the standard options.
220 '\" # OP - start of full description for a single option
225 Command-Line Name: \\fB\\$1\\fR
226 Database Name: \\fB\\$2\\fR
227 Database Class: \\fB\\$3\\fR
231 '\" # CS - begin code excerpt
237 '\" # CE - end code excerpt
245 .TH fconfigure n 8.1 Tcl "Tcl Built-In Commands"
247 '\" Note: do not modify the .SH NAME line immediately below!
249 fconfigure \- Set and get options on a channel
252 \fBfconfigure \fIchannelId\fR
253 \fBfconfigure \fIchannelId\fR \fIname\fR
254 \fBfconfigure \fIchannelId\fR \fIname value \fR?\fIname value ...\fR?
260 The \fBfconfigure\fR command sets and retrieves options for channels.
261 \fIChannelId\fR identifies the channel for which to set or query an option.
262 If no \fIname\fR or \fIvalue\fR arguments are supplied, the command
263 returns a list containing alternating option names and values for the channel.
264 If \fIname\fR is supplied but no \fIvalue\fR then the command returns
265 the current value of the given option.
266 If one or more pairs of \fIname\fR and \fIvalue\fR are supplied, the
267 command sets each of the named options to the corresponding \fIvalue\fR;
268 in this case the return value is an empty string.
270 The options described below are supported for all channels. In addition,
271 each channel type may add options that only it supports. See the manual
272 entry for the command that creates each type of channels for the options
273 that that specific type of channel supports. For example, see the manual
274 entry for the \fBsocket\fR command for its additional options.
276 \fB\-blocking\fR \fIboolean\fR
277 The \fB\-blocking\fR option determines whether I/O operations on the
278 channel can cause the process to block indefinitely.
279 The value of the option must be a proper boolean value.
280 Channels are normally in blocking mode; if a channel is placed into
281 nonblocking mode it will affect the operation of the \fBgets\fR,
282 \fBread\fR, \fBputs\fR, \fBflush\fR, and \fBclose\fR commands;
283 see the documentation for those commands for details.
284 For nonblocking mode to work correctly, the application must be
285 using the Tcl event loop (e.g. by calling \fBTcl_DoOneEvent\fR or
286 invoking the \fBvwait\fR command).
288 \fB\-buffering\fR \fInewValue\fR
290 If \fInewValue\fR is \fBfull\fR then the I/O system will buffer output
291 until its internal buffer is full or until the \fBflush\fR command is
292 invoked. If \fInewValue\fR is \fBline\fR, then the I/O system will
293 automatically flush output for the channel whenever a newline character
294 is output. If \fInewValue\fR is \fBnone\fR, the I/O system will flush
295 automatically after every output operation. The default is for
296 \fB\-buffering\fR to be set to \fBfull\fR except for channels that
297 connect to terminal-like devices; for these channels the initial setting
298 is \fBline\fR. Additionally, \fBstdin\fR and \fBstdout\fR are
299 intially set to \fBline\fR, and \fBstderr\fR is set to \fBnone\fR.
301 \fB\-buffersize\fR \fInewSize\fR
303 \fINewvalue\fR must be an integer; its value is used to set the size of
304 buffers, in bytes, subsequently allocated for this channel to store input
305 or output. \fINewvalue\fR must be between ten and one million, allowing
306 buffers of ten to one million bytes in size.
309 \fB\-encoding\fR \fIname\fR
311 This option is used to specify the encoding of the channel, so that the data
312 can be converted to and from Unicode for use in Tcl. For instance, in
313 order for Tcl to read characters from a Japanese file in \fBshiftjis\fR
314 and properly process and display the contents, the encoding would be set
315 to \fBshiftjis\fR. Thereafter, when reading from the channel, the bytes in
316 the Japanese file would be converted to Unicode as they are read.
317 Writing is also supported \- as Tcl strings are written to the channel they
318 will automatically be converted to the specified encoding on output.
321 If a file contains pure binary data (for instance, a JPEG image), the
322 encoding for the channel should be configured to be \fBbinary\fR. Tcl
323 will then assign no interpretation to the data in the file and simply read or
324 write raw bytes. The Tcl \fBbinary\fR command can be used to manipulate this
327 The default encoding for newly opened channels is the same platform- and
328 locale-dependent system encoding used for interfacing with the operating
333 \fB\-eofchar\fR \fIchar\fR
335 \fB\-eofchar\fR \fB{\fIinChar outChar\fB}\fR
337 This option supports DOS file systems that use Control-z (\ex1a) as an
338 end of file marker. If \fIchar\fR is not an empty string, then this
339 character signals end-of-file when it is encountered during input. For
340 output, the end-of-file character is output when the channel is closed.
341 If \fIchar\fR is the empty string, then there is no special end of file
342 character marker. For read-write channels, a two-element list specifies
343 the end of file marker for input and output, respectively. As a
344 convenience, when setting the end-of-file character for a read-write
345 channel you can specify a single value that will apply to both reading
346 and writing. When querying the end-of-file character of a read-write
347 channel, a two-element list will always be returned. The default value
348 for \fB\-eofchar\fR is the empty string in all cases except for files
349 under Windows. In that case the \fB\-eofchar\fR is Control-z (\ex1a) for
350 reading and the empty string for writing.
352 \fB\-translation\fR \fImode\fR
354 \fB\-translation\fR \fB{\fIinMode outMode\fB}\fR
356 In Tcl scripts the end of a line is always represented using a single
357 newline character (\en). However, in actual files and devices the end of
358 a line may be represented differently on different platforms, or even for
359 different devices on the same platform. For example, under UNIX newlines
360 are used in files, whereas carriage-return-linefeed sequences are
361 normally used in network connections. On input (i.e., with \fBgets\fP
362 and \fBread\fP) the Tcl I/O system automatically translates the external
363 end-of-line representation into newline characters. Upon output (i.e.,
364 with \fBputs\fP), the I/O system translates newlines to the external
365 end-of-line representation. The default translation mode, \fBauto\fP,
366 handles all the common cases automatically, but the \fB\-translation\fR
367 option provides explicit control over the end of line translations.
370 The value associated with \fB\-translation\fR is a single item for
371 read-only and write-only channels. The value is a two-element list for
372 read-write channels; the read translation mode is the first element of
373 the list, and the write translation mode is the second element. As a
374 convenience, when setting the translation mode for a read-write channel
375 you can specify a single value that will apply to both reading and
376 writing. When querying the translation mode of a read-write channel, a
377 two-element list will always be returned. The following values are
382 As the input translation mode, \fBauto\fR treats any of newline
383 (\fBlf\fP), carriage return (\fBcr\fP), or carriage return followed by a
384 newline (\fBcrlf\fP) as the end of line representation. The end of line
385 representation can even change from line-to-line, and all cases are
386 translated to a newline. As the output translation mode, \fBauto\fR
387 chooses a platform specific representation; for sockets on all platforms
388 Tcl chooses \fBcrlf\fR, for all Unix flavors, it chooses \fBlf\fR, for the
389 Macintosh platform it chooses \fBcr\fR and for the various flavors of
390 Windows it chooses \fBcrlf\fR. The default setting for
391 \fB\-translation\fR is \fBauto\fR for both input and output.
396 No end-of-line translations are performed. This is nearly identical to
397 \fBlf\fP mode, except that in addition \fBbinary\fP mode also sets the
398 end-of-file character to the empty string (which disables it) and sets the
399 encoding to \fBbinary\fR (which disables encoding filtering). See the
400 description of \fB\-eofchar\fR and \fB\-encoding\fR for more information.
405 The end of a line in the underlying file or device is represented by a
406 single carriage return character. As the input translation mode,
407 \fBcr\fP mode converts carriage returns to newline characters. As the
408 output translation mode, \fBcr\fP mode translates newline characters to
409 carriage returns. This mode is typically used on Macintosh platforms.
413 The end of a line in the underlying file or device is represented by a
414 carriage return character followed by a linefeed character. As the input
415 translation mode, \fBcrlf\fP mode converts carriage-return-linefeed
416 sequences to newline characters. As the output translation mode,
417 \fBcrlf\fP mode translates newline characters to carriage-return-linefeed
418 sequences. This mode is typically used on Windows platforms and for
423 The end of a line in the underlying file or device is represented by a
424 single newline (linefeed) character. In this mode no translations occur
425 during either input or output. This mode is typically used on UNIX
431 close(n), flush(n), gets(n), puts(n), read(n), socket(n)
434 blocking, buffering, carriage return, end of line, flushing, linemode,
435 newline, nonblocking, platform, translation, encoding, filter, byte array,
OSDN Git Service
