tcl7.6 User Commands - fconfigure






NAME

     fconfigure - Set and get options on a channel


SYNOPSIS

     fconfigure channelId
     fconfigure channelId name
     fconfigure channelId name value ?name value ...?





DESCRIPTION

     The fconfigure command sets and retrieves options for  chan-
     nels.   ChannelId identifies the channel for which to set or
     query an option.  If no name or  value  arguments  are  sup-
     plied,  the  command  returns  a list containing alternating
     option names and values for the channel.  If  name  is  sup-
     plied  but  no  value  then  the command returns the current
     value of the given option.  If one or more pairs of name and
     value  are  supplied,  the  command  sets  each of the named
     options to the corresponding value; 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 boolean
          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 newValue
          If newValue is full then the  I/O  system  will  buffer
          output  until  its internal buffer is full or until the
          flush command is invoked. If newValue is line, then the
          I/O  system  will  automatically  flush  output for the
          channel whenever a  newline  character  is  output.  If
          newValue  is  none, the I/O system will flush automati-
          cally after every output operation.  The default is for
          - buffering  to be set to full except for channels that
          connect to terminal-like devices;  for  these  channels
          the initial setting is line.

     -buffersize newSize
          Newvalue 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.  Newvalue
          must  be  between ten and one million, allowing buffers
          of ten to one million bytes in size.

     -eofchar char

     -eofchar {inChar outChar}
          This  option  supports  DOS  file  systems   that   use
          Control-z  (\x1a) as an end of file marker.  If char 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 char 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 mode

     -translation {inMode outMode}
          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.
          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.

          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