diff options
Diffstat (limited to 'doc/fconfigure.n')
| -rw-r--r-- | doc/fconfigure.n | 178 |
1 files changed, 178 insertions, 0 deletions
diff --git a/doc/fconfigure.n b/doc/fconfigure.n new file mode 100644 index 0000000..1c187ac --- /dev/null +++ b/doc/fconfigure.n @@ -0,0 +1,178 @@ +'\" +'\" Copyright (c) 1995-1996 Sun Microsystems, Inc. +'\" +'\" See the file "license.terms" for information on usage and redistribution +'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES. +'\" +'\" SCCS: @(#) fconfigure.n 1.23 96/04/16 08:20:07 +'\" +.so man.macros +.TH fconfigure n 7.5 Tcl "Tcl Built-In Commands" +.BS +'\" Note: do not modify the .SH NAME line immediately below! +.SH NAME +fconfigure \- Set and get options on a channel +.SH SYNOPSIS +.nf +\fBfconfigure \fIchannelId\fR +\fBfconfigure \fIchannelId\fR \fIname\fR +\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. +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 +the current value of the given option. +If one or more pairs of \fIname\fR and \fIvalue\fR are supplied, the +command sets each of the named options to the corresponding \fIvalue\fR; +in this case the return value is an empty string. +.PP +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. +.TP +\fB\-blocking\fR \fIboolean\fR +The \fB\-blocking\fR option determines whether I/O operations on the +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; +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 +invoking the \fBvwait\fR command). +.TP +\fB\-buffering\fR \fInewValue\fR +If \fInewValue\fR is \fBfull\fR then the I/O system will buffer output +until its internal buffer is full or until the \fBflush\fR command is +invoked. If \fInewValue\fR is \fBline\fR, then the I/O system will +automatically flush output for the channel whenever a newline character +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. +.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. +.TP +\fB\-eofchar\fR \fIchar\fR +.TP +\fB\-eofchar\fR \fB{\fIinChar outChar\fB}\fR +This option supports DOS file systems that use Control-z (\ex1a) as +an end of file marker. +If \fIchar\fR is not an empty string, then this character signals +end of file when it is encountered during input. +For output, the end of file character is output when +the channel is closed. +If \fIchar\fR is the empty string, then there is no special +end of file character marker. +For read-write channels, a two-element list specifies +the end of file marker for input and output, respectively. +As a convenience, when setting the end-of-file character +for a read-write channel +you can specify a single value that will apply to both reading and writing. +When querying the end-of-file character of a read-write 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. +.TP +\fB\-translation\fR \fImode\fR +.TP +\fB\-translation\fR \fB{\fIinMode outMode\fB}\fR +In Tcl scripts the end of a line is always represented using a +single 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 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, handles all the common +cases automatically, but the \fB\-translation\fR option provides +explicit control over the end of line translations. +.RS +.PP +The value associated with \fB\-translation\fR is a single item for +read-only and write-only channels. +The value is a two-element list for read-write channels; +the read translation mode is the first element of the list, +and the write translation mode is the second element. +As a convenience, when setting the translation mode for a read-write channel +you can specify a single value that will apply to both reading and writing. +When querying the translation mode of a read-write channel, +a two-element list will always be returned. +The following values are currently supported: +.TP +\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 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. +.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 +end of file character to the empty string, which disables it. +See the description of +\fB\-eofchar\fP for more information. +.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. +.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 sequences +to newline characters. +As the output translation mode, \fBcrlf\fP mode +translates newline characters to +carriage-return-linefeed sequences. +This mode is typically used on Windows platforms and for network +connections. +.TP +\fBlf\fR +The end of a line in the underlying file or device is represented +by a single newline (linefeed) character. +In this mode no translations occur during either input or output. +This mode is typically used on UNIX platforms. +.RE +.PP + +.SH "SEE ALSO" +close(n), flush(n), gets(n), puts(n), read(n), socket(n) + +.SH KEYWORDS +blocking, buffering, carriage return, end of line, flushing, linemode, +newline, nonblocking, platform, translation |