fconfigure(n) Tcl Built-In Commands fconfigure(n) _________________________________________________________________ NAME fconfigure - Set and get options on a channel SYNOPSIS fconfigure _c_h_a_n_n_e_l_I_d fconfigure _c_h_a_n_n_e_l_I_d _n_a_m_e fconfigure _c_h_a_n_n_e_l_I_d _n_a_m_e _v_a_l_u_e ?_n_a_m_e _v_a_l_u_e ...? _________________________________________________________________ DESCRIPTION The fconfigure command sets and retrieves options for chan- nels. _C_h_a_n_n_e_l_I_d identifies the channel for which to set or query an option. If no _n_a_m_e or _v_a_l_u_e arguments are sup- plied, the command returns a list containing alternating option names and values for the channel. If _n_a_m_e is sup- plied but no _v_a_l_u_e then the command returns the current value of the given option. If one or more pairs of _n_a_m_e and _v_a_l_u_e are supplied, the command sets each of the named options to the corresponding _v_a_l_u_e; in this case the return value is an empty string. 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 socket command for its additional options. -blocking _b_o_o_l_e_a_n The -blocking option determines whether I/O operations on the channel can cause the process to block indefin- itely. 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 gets, read, puts, flush, and close 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 Tcl_DoOneEvent or invoking the vwait command). -buffering _n_e_w_V_a_l_u_e If _n_e_w_V_a_l_u_e is full then the I/O system will buffer output until its internal buffer is full or until the flush command is invoked. If _n_e_w_V_a_l_u_e is line, then the I/O system will automatically flush output for the channel whenever a newline character is output. If _n_e_w_V_a_l_u_e is none, the I/O system will flush automati- cally after every output operation. The default is for Tcl Last change: 7.5 1 fconfigure(n) Tcl Built-In Commands fconfigure(n) - buffering to be set to full except for channels that connect to terminal-like devices; for these channels the initial setting is line. -buffersize _n_e_w_S_i_z_e _N_e_w_v_a_l_u_e 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. _N_e_w_v_a_l_u_e must be between ten and one million, allowing buffers of ten to one million bytes in size. -eofchar _c_h_a_r -eofchar {_i_n_C_h_a_r _o_u_t_C_h_a_r} This option supports DOS file systems that use Control-z (\x1a) as an end of file marker. If _c_h_a_r 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 _c_h_a_r 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 con- venience, 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 -eofchar is the empty string in all cases except for files under Windows. In that case the - eofchar is Control-z (\x1a) for reading and the empty string for writing. -translation _m_o_d_e -translation {_i_n_M_o_d_e _o_u_t_M_o_d_e} 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 exam- ple, under UNIX newlines are used in files, whereas carriage-return-linefeed sequences are normally used in network connections. On input (i.e., with gets and read) the Tcl I/O system automatically translates the external end-of-line representation into newline char- acters. Upon output (i.e., with puts), the I/O system translates newlines to the external end-of-line representation. The default translation mode, auto, handles all the common cases automatically, but the - translation option provides explicit control over the end of line translations. Tcl Last change: 7.5 2 fconfigure(n) Tcl Built-In Commands fconfigure(n) The value associated with -translation 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: auto As the input translation mode, auto treats any of newline (lf), carriage return (cr), or carriage return followed by a newline (crlf) as the end of line representation. The end of line representa- tion can even change from line-to-line, and all cases are translated to a newline. As the output translation mode, auto chooses a platform specific representation; for sockets on all platforms Tcl chooses crlf, for all Unix flavors, it chooses lf, for the Macintosh platform it chooses cr and for the various flavors of Windows it chooses crlf. The default setting for -translation is auto for both input and output. binary No end-of-line translations are performed. This is nearly identical to lf mode, except that in addition binary mode also sets the end of file character to the empty string, which disables it. See the description of -eofchar for more informa- tion. cr The end of a line in the underlying file or device is represented by a single carriage return charac- ter. As the input translation mode, cr mode con- verts carriage returns to newline characters. As the output translation mode, cr mode translates newline characters to carriage returns. This mode is typically used on Macintosh platforms. crlf The end of a line in the underlying file or device is represented by a carriage return character fol- lowed by a linefeed character. As the input translation mode, crlf mode converts carriage- return-linefeed sequences to newline characters. As the output translation mode, crlf mode translates newline characters to carriage-return- linefeed sequences. This mode is typically used on Windows platforms and for network connections. Tcl Last change: 7.5 3 fconfigure(n) Tcl Built-In Commands fconfigure(n) lf 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 typi- cally used on UNIX platforms. SEE ALSO close(n), flush(n), gets(n), puts(n), read(n), socket(n) KEYWORDS blocking, buffering, carriage return, end of line, flushing, linemode, newline, nonblocking, platform, translation Tcl Last change: 7.5 4