Initial revision

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