Subversion Repositories or1k

'\"

'\" 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.

'\"

'\" RCS: @(#) $Id: fconfigure.n,v 1.1.1.1 2002-01-16 10:25:24 markom Exp $

'\"

.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