Страницы справочника OS X

Эта страница руководства для  версии 10.9 Mac OS X

Читать страницы руководства

fconfigure(n)                               Tcl Built-In Commands                              fconfigure(n)



____________________________________________________________________________________________________________

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 channels.

       ChannelId  identifies the channel for which to set or query an option and must refer to an open chan-nel channel
       nel such as a Tcl standard channel (stdin, stdout, or stderr), the return value from an invocation of
       open or socket, or the result of a channel creation command provided by a Tcl extension.

       If  no name or value arguments are supplied, the command returns a list containing alternating option
       names and values for the channel.  If name is supplied but no value then the command returns the cur-rent current
       rent  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  chan-nels channels
       nels  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  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 gets, read, puts, flush, and close commands by allowing them to operate asyn-chronously; asynchronously;
              chronously; 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 automati-cally automatically
              cally flush output for the channel whenever a newline character  is  output.  If  newValue  is
              none,  the  I/O  system will flush automatically 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.  Additionally, stdin and stdout are initially
              set to line, and stderr is set to none.

       -buffersize newSize
              Newvalue must be an integer; its value is used to set the size of buffers,  in  bytes,  subse-quently subsequently
              quently  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.

       -encoding name
              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 shiftjis and properly process and display the contents, the encoding would be
              set  to  shiftjis.   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.

              If a file contains pure binary data (for instance, a JPEG image), the encoding for the channel
              should  be configured to be binary.  Tcl will then assign no interpretation to the data in the
              file and simply read or write raw bytes.  The Tcl binary command can  be  used  to  manipulate
              this  byte-oriented  data.  It is usually better to set the -translation option to binary when
              you want to transfer binary data, as this turns off the other automatic interpretations of the
              bytes in the stream as well.

              The default encoding for newly opened channels is the same platform- and locale-dependent sys-tem system
              tem encoding used for interfacing with the operating system, as returned by encoding system.

       -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 readwrite
              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 chan-nel channel
              nel 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  Win-dows. Windows.
              dows.   In  that  case  the  -eofchar is Control-z (\x1a) for reading and the empty string for
              writing.  The acceptable range for -eofchar values is \x01 - \x7f; attempting to set  -eofchar
              to a value outside of this range will generate an error.

       -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  dif-ferent different
              ferent 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 gets and read) the Tcl I/O system automatically
              translates the external end-of-line  representation  into  newline  characters.   Upon  output
              (i.e.,  with puts), the I/O system translates newlines to the external end-of-line representa-tion. representation.
              tion.  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 conve-nience, convenience,
              nience, 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 cur-rently currently
              rently 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 representation can even change from line-to-line, and all cases are trans-lated translated
                     lated 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, and for the various flavors of Windows it chooses crlf.  The  default  set-ting setting
                     ting 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)  and sets the encoding to binary (which disables encoding filter-ing). filtering).
                     ing).  See the description of -eofchar and -encoding for more information.

                     Internally, i.e. when it comes to the actual behaviour of the translator this value  is
                     identical to lf and is therefore reported as such when queried. Even if binary was used
                     to set the translation.

              cr     The end of a line in the underlying file or device is represented by a single  carriage
                     return  character.  As the input translation mode, cr mode converts carriage returns to
                     newline characters.  As the output translation mode, cr mode translates newline charac-ters characters
                     ters to carriage returns.

              crlf   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,  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 connec-tions. connections.
                     tions.

              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 out-put. output.
                     put.  This mode is typically used on UNIX platforms.


STANDARD CHANNELS
       The Tcl standard channels (stdin, stdout, and stderr) can be configured  through  this  command  like
       every  other channel opened by the Tcl library. Beyond the standard options described above they will
       also support any special option according to their current type.  If, for example, a Tcl  application
       is  started  by the inet super-server common on Unix system its Tcl standard channels will be sockets
       and thus support the socket options.

EXAMPLES
       Instruct Tcl to always send output to stdout immediately, whether or not it is to a terminal:
              fconfigure stdout -buffering none

       Open a socket and read lines from it without ever blocking the processing of other events:
              set s [socket some.where.com 12345]
              fconfigure $s -blocking 0
              fileevent $s readable "readMe $s"
              proc readMe chan {
                 if {[gets $chan line] < 0} {
                    if {[eof $chan]} {
                       close $chan
                       return
                    }
                    # Could not read a complete line this time; Tcl's
                    # internal buffering will hold the partial line for us
                    # until some more data is available over the socket.
                 } else {
                    puts stdout $line
                 }
              }

       Read a PPM-format image from a file:
              # Open the file and put it into Unix ASCII mode
              set f [open teapot.ppm]
              fconfigure $f -encoding ascii -translation lf

              # Get the header
              if {[gets $f] ne "P6"} {
                 error "not a raw-bits PPM"
              }

              # Read lines until we have got non-comment lines
              # that supply us with three decimal values.
              set words {}
              while {[llength $words] < 3} {
                 gets $f line
                 if {[string match "#*" $line]} continue
                 lappend words {*}[join [scan $line %d%d%d]]
              }

              # Those words supply the size of the image and its
              # overall depth per channel. Assign to variables.
              lassign $words xSize ySize depth

              # Now switch to binary mode to pull in the data,
              # one byte per channel (red,green,blue) per pixel.
              fconfigure $f -translation binary
              set numDataBytes [expr {3 * $xSize * $ySize}]
              set data [read $f $numDataBytes]

              close $f


SEE ALSO
       close(n), flush(n), gets(n), open(n), puts(n), read(n), socket(n), Tcl_StandardChannels(3)


KEYWORDS
       blocking, buffering, carriage return, end of line, flushing, linemode,  newline,  nonblocking,  plat-
       form, translation, encoding, filter, byte array, binary



Tcl                                                  8.3                                       fconfigure(n)