190 lines
12 KiB
HTML
190 lines
12 KiB
HTML
<HTML><HEAD><TITLE>Tcl Built-In Commands - fconfigure manual page</TITLE></HEAD><BODY>
|
|
<DL>
|
|
<DD><A HREF="fconfigure.htm#M2" NAME="L290">NAME</A>
|
|
<DL><DD>fconfigure - Set and get options on a channel</DL>
|
|
<DD><A HREF="fconfigure.htm#M3" NAME="L291">SYNOPSIS</A>
|
|
<DL>
|
|
<DD><B>fconfigure </B><I>channelId</I>
|
|
<DD><B>fconfigure </B><I>channelId</I> <I>name</I>
|
|
<DD><B>fconfigure </B><I>channelId</I> <I>name value </I>?<I>name value ...</I>?
|
|
</DL>
|
|
<DD><A HREF="fconfigure.htm#M4" NAME="L292">DESCRIPTION</A>
|
|
<DL>
|
|
<DD><A HREF="fconfigure.htm#M5" NAME="L293"><B>-blocking</B> <I>boolean</I></A>
|
|
<DD><A HREF="fconfigure.htm#M6" NAME="L294"><B>-buffering</B> <I>newValue</I></A>
|
|
<DD><A HREF="fconfigure.htm#M7" NAME="L295"><B>-buffersize</B> <I>newSize</I></A>
|
|
<DD><A HREF="fconfigure.htm#M8" NAME="L296"><B>-encoding</B> <I>name</I></A>
|
|
<DD><A HREF="fconfigure.htm#M9" NAME="L297"><B>-eofchar</B> <I>char</I></A>
|
|
<DD><A HREF="fconfigure.htm#M10" NAME="L298"><B>-eofchar</B> <B>{</B><I>inChar outChar</I><B>}</B></A>
|
|
<DD><A HREF="fconfigure.htm#M11" NAME="L299"><B>-translation</B> <I>mode</I></A>
|
|
<DD><A HREF="fconfigure.htm#M12" NAME="L300"><B>-translation</B> <B>{</B><I>inMode outMode</I><B>}</B></A>
|
|
<DL>
|
|
<DD><A HREF="fconfigure.htm#M13" NAME="L301"><B>auto</B></A>
|
|
<DD><A HREF="fconfigure.htm#M14" NAME="L302"><B>binary</B></A>
|
|
<DD><A HREF="fconfigure.htm#M15" NAME="L303"><B>cr</B></A>
|
|
<DD><A HREF="fconfigure.htm#M16" NAME="L304"><B>crlf</B></A>
|
|
<DD><A HREF="fconfigure.htm#M17" NAME="L305"><B>lf</B></A>
|
|
</DL>
|
|
</DL>
|
|
<DD><A HREF="fconfigure.htm#M18" NAME="L306">SEE ALSO</A>
|
|
<DD><A HREF="fconfigure.htm#M19" NAME="L307">KEYWORDS</A>
|
|
</DL><HR>
|
|
<H3><A NAME="M2">NAME</A></H3>
|
|
fconfigure - Set and get options on a channel
|
|
<H3><A NAME="M3">SYNOPSIS</A></H3>
|
|
<B>fconfigure </B><I>channelId</I><BR>
|
|
<B>fconfigure </B><I>channelId</I> <I>name</I><BR>
|
|
<B>fconfigure </B><I>channelId</I> <I>name value </I>?<I>name value ...</I>?<BR>
|
|
<H3><A NAME="M4">DESCRIPTION</A></H3>
|
|
The <B>fconfigure</B> command sets and retrieves options for channels.
|
|
<I>ChannelId</I> identifies the channel for which to set or query an option.
|
|
If no <I>name</I> or <I>value</I> arguments are supplied, the command
|
|
returns a list containing alternating option names and values for the channel.
|
|
If <I>name</I> is supplied but no <I>value</I> then the command returns
|
|
the current value of the given option.
|
|
If one or more pairs of <I>name</I> and <I>value</I> are supplied, the
|
|
command sets each of the named options to the corresponding <I>value</I>;
|
|
in this case the return value is an empty string.
|
|
<P>
|
|
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 <B><A HREF="../TkCmd/socket.htm">socket</A></B> command for its additional options.
|
|
<P>
|
|
<DL>
|
|
<P><DT><A NAME="M5"><B>-blocking</B> <I>boolean</I></A><DD>
|
|
The <B>-blocking</B> 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 <B><A HREF="../TkCmd/gets.htm">gets</A></B>,
|
|
<B><A HREF="../TkCmd/read.htm">read</A></B>, <B><A HREF="../TkCmd/puts.htm">puts</A></B>, <B><A HREF="../TkCmd/flush.htm">flush</A></B>, and <B><A HREF="../TkCmd/close.htm">close</A></B> 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 <B><A HREF="../TkLib/DoOneEvent.htm">Tcl_DoOneEvent</A></B> or
|
|
invoking the <B><A HREF="../TkCmd/vwait.htm">vwait</A></B> command).
|
|
<P><DT><A NAME="M6"><B>-buffering</B> <I>newValue</I></A><DD>
|
|
If <I>newValue</I> is <B>full</B> then the I/O system will buffer output
|
|
until its internal buffer is full or until the <B><A HREF="../TkCmd/flush.htm">flush</A></B> command is
|
|
invoked. If <I>newValue</I> is <B>line</B>, then the I/O system will
|
|
automatically flush output for the channel whenever a newline character
|
|
is output. If <I>newValue</I> is <B>none</B>, the I/O system will flush
|
|
automatically after every output operation. The default is for
|
|
<B>-buffering</B> to be set to <B>full</B> except for channels that
|
|
connect to terminal-like devices; for these channels the initial setting
|
|
is <B>line</B>. Additionally, <B>stdin</B> and <B>stdout</B> are
|
|
intially set to <B>line</B>, and <B>stderr</B> is set to <B>none</B>.
|
|
<P><DT><A NAME="M7"><B>-buffersize</B> <I>newSize</I></A><DD>
|
|
<I>Newvalue</I> 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. <I>Newvalue</I> must be between ten and one million, allowing
|
|
buffers of ten to one million bytes in size.
|
|
<P><DT><A NAME="M8"><B>-encoding</B> <I>name</I></A><DD>
|
|
This option is used to specify the encoding of the channel, so that the data
|
|
can be converted to and from Unicode for use in Tcl. For instance, in
|
|
order for Tcl to read characters from a Japanese file in <B>shiftjis</B>
|
|
and properly process and display the contents, the encoding would be set
|
|
to <B>shiftjis</B>. Thereafter, when reading from the channel, the bytes in
|
|
the Japanese file would be converted to Unicode as they are read.
|
|
Writing is also supported - as Tcl strings are written to the channel they
|
|
will automatically be converted to the specified encoding on output.
|
|
<P>
|
|
If a file contains pure binary data (for instance, a JPEG image), the
|
|
encoding for the channel should be configured to be <B><A HREF="../TkCmd/binary.htm">binary</A></B>. Tcl
|
|
will then assign no interpretation to the data in the file and simply read or
|
|
write raw bytes. The Tcl <B><A HREF="../TkCmd/binary.htm">binary</A></B> command can be used to manipulate this
|
|
byte-oriented data.
|
|
<P>The default encoding for newly opened channels is the same platform- and
|
|
locale-dependent system encoding used for interfacing with the operating
|
|
system.
|
|
<P><DT><A NAME="M9"><B>-eofchar</B> <I>char</I></A><DD>
|
|
<P><DT><A NAME="M10"><B>-eofchar</B> <B>{</B><I>inChar outChar</I><B>}</B></A><DD>
|
|
This option supports DOS file systems that use Control-z (\x1a) as an
|
|
end of file marker. If <I>char</I> 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 <I>char</I> 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 <B>-eofchar</B> is the empty string in all cases except for files
|
|
under Windows. In that case the <B>-eofchar</B> is Control-z (\x1a) for
|
|
reading and the empty string for writing.
|
|
<P><DT><A NAME="M11"><B>-translation</B> <I>mode</I></A><DD>
|
|
<P><DT><A NAME="M12"><B>-translation</B> <B>{</B><I>inMode outMode</I><B>}</B></A><DD>
|
|
In Tcl scripts the end of a line is always represented using a single
|
|
newline character (\n). 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 <B><A HREF="../TkCmd/gets.htm">gets</A></B>
|
|
and <B><A HREF="../TkCmd/read.htm">read</A></B>) the Tcl I/O system automatically translates the external
|
|
end-of-line representation into newline characters. Upon output (i.e.,
|
|
with <B><A HREF="../TkCmd/puts.htm">puts</A></B>), the I/O system translates newlines to the external
|
|
end-of-line representation. The default translation mode, <B>auto</B>,
|
|
handles all the common cases automatically, but the <B>-translation</B>
|
|
option provides explicit control over the end of line translations.
|
|
<P>
|
|
The value associated with <B>-translation</B> 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:
|
|
<P>
|
|
<DL>
|
|
<P><DT><A NAME="M13"><B>auto</B></A><DD>
|
|
As the input translation mode, <B>auto</B> treats any of newline
|
|
(<B>lf</B>), carriage return (<B>cr</B>), or carriage return followed by a
|
|
newline (<B>crlf</B>) 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, <B>auto</B>
|
|
chooses a platform specific representation; for sockets on all platforms
|
|
Tcl chooses <B>crlf</B>, for all Unix flavors, it chooses <B>lf</B>, for the
|
|
Macintosh platform it chooses <B>cr</B> and for the various flavors of
|
|
Windows it chooses <B>crlf</B>. The default setting for
|
|
<B>-translation</B> is <B>auto</B> for both input and output.
|
|
<P><DT><A NAME="M14"><B>binary</B></A><DD>
|
|
No end-of-line translations are performed. This is nearly identical to
|
|
<B>lf</B> mode, except that in addition <B><A HREF="../TkCmd/binary.htm">binary</A></B> mode also sets the
|
|
end-of-file character to the empty string (which disables it) and sets the
|
|
encoding to <B><A HREF="../TkCmd/binary.htm">binary</A></B> (which disables encoding filtering). See the
|
|
description of <B>-eofchar</B> and <B>-encoding</B> for more information.
|
|
<P><DT><A NAME="M15"><B>cr</B></A><DD>
|
|
The end of a line in the underlying file or device is represented by a
|
|
single carriage return character. As the input translation mode,
|
|
<B>cr</B> mode converts carriage returns to newline characters. As the
|
|
output translation mode, <B>cr</B> mode translates newline characters to
|
|
carriage returns. This mode is typically used on Macintosh platforms.
|
|
<P><DT><A NAME="M16"><B>crlf</B></A><DD>
|
|
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, <B>crlf</B> mode converts carriage-return-linefeed
|
|
sequences to newline characters. As the output translation mode,
|
|
<B>crlf</B> mode translates newline characters to carriage-return-linefeed
|
|
sequences. This mode is typically used on Windows platforms and for
|
|
network connections.
|
|
<P><DT><A NAME="M17"><B>lf</B></A><DD>
|
|
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.
|
|
<P></DL>
|
|
<P></DL>
|
|
<P>
|
|
<H3><A NAME="M18">SEE ALSO</A></H3>
|
|
<B><A HREF="../TkCmd/close.htm">close</A></B>, <B><A HREF="../TkCmd/flush.htm">flush</A></B>, <B><A HREF="../TkCmd/gets.htm">gets</A></B>, <B><A HREF="../TkCmd/puts.htm">puts</A></B>, <B><A HREF="../TkCmd/read.htm">read</A></B>, <B><A HREF="../TkCmd/socket.htm">socket</A></B>
|
|
<H3><A NAME="M19">KEYWORDS</A></H3>
|
|
<A href="../Keywords/B.htm#blocking">blocking</A>, <A href="../Keywords/B.htm#buffering">buffering</A>, <A href="../Keywords/C.htm#carriage return">carriage return</A>, <A href="../Keywords/E.htm#end of line">end of line</A>, <A href="../Keywords/F.htm#flushing">flushing</A>, <A href="../Keywords/L.htm#linemode">linemode</A>, <A href="../Keywords/N.htm#newline">newline</A>, <A href="../Keywords/N.htm#nonblocking">nonblocking</A>, <A href="../Keywords/P.htm#platform">platform</A>, <A href="../Keywords/T.htm#translation">translation</A>, <A href="../Keywords/E.htm#encoding">encoding</A>, <A href="../Keywords/F.htm#filter">filter</A>, <A href="../Keywords/B.htm#byte array">byte array</A>, <A href="../Keywords/B.htm#binary">binary</A>
|
|
<HR><PRE>
|
|
<A HREF="../copyright.htm">Copyright</A> © 1995-1996 Sun Microsystems, Inc.
|
|
<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE>
|
|
</BODY></HTML>
|