Go to main content

man pages section 1: User Commands

Exit Print View

Updated: Thursday, June 13, 2019
 
 

chan (1t)

Name

chan - Read, write and manipulate channels

Synopsis

chan option ?arg arg ...?

Description

chan(1t)                     Tcl Built-In Commands                    chan(1t)



______________________________________________________________________________

NAME
       chan - Read, write and manipulate channels

SYNOPSIS
       chan option ?arg arg ...?
______________________________________________________________________________

DESCRIPTION
       This  command  provides several operations for reading from, writing to
       and otherwise manipulating open channels (such  as  have  been  created
       with the open and socket commands, or the default named channels stdin,
       stdout or stderr which correspond to the process's standard input, out-
       put  and error streams respectively).  Option indicates what to do with
       the channel; any unique abbreviation for option  is  acceptable.  Valid
       options are:

       chan blocked channelId
              This  tests  whether  the  last  input  operation on the channel
              called channelId failed because it would have  otherwise  caused
              the  process  to  block,  and returns 1 if that was the case. It
              returns 0 otherwise. Note that this only ever returns 1 when the
              channel has been configured to be non-blocking; all Tcl channels
              have blocking turned on by default.

       chan close channelId ?direction?
              Close and destroy the channel called channelId. Note  that  this
              deletes  all existing file-events registered on the channel.  If |
              the direction argument (which must  be  read  or  write  or  any |
              unique  abbreviation  of them) is present, the channel will only |
              be half-closed, so that it  can  go  from  being  read-write  to |
              write-only  or read-only respectively. If a read-only channel is |
              closed for reading, it is the same as if the  channel  is  fully |
              closed,  and respectively similar for write-only channels. With- |
              out the direction argument, the channel is closed for both read- |
              ing  and  writing  (but  only  if those directions are currently |
              open). It is an error to close a read-only channel for  writing, |
              or a write-only channel for reading.

              As  part  of closing the channel, all buffered output is flushed
              to the channel's output device (only if the channel  is  ceasing
              to  be  writable),  any buffered input is discarded (only if the
              channel is ceasing to be  readable),  the  underlying  operating
              system  resource is closed and channelId becomes unavailable for
              future use  (both  only  if  the  channel  is  being  completely
              closed).

              If  the  channel  is  blocking  and the channel is ceasing to be
              writable, the command  does  not  return  until  all  output  is
              flushed.   If the channel is non-blocking and there is unflushed
              output, the channel remains open and the command returns immedi-
              ately;  output will be flushed in the background and the channel
              will be closed when all the flushing is complete.

              If channelId is a blocking channel for a command  pipeline  then
              chan close waits for the child processes to complete.

              If  the  channel is shared between interpreters, then chan close
              makes channelId unavailable in the invoking interpreter but  has
              no  other  effect  until  all  of  the sharing interpreters have
              closed the channel. When the last interpreter in which the chan-
              nel  is  registered  invokes  chan close (or close), the cleanup
              actions described above occur. With half-closing, the half-close
              of the channel only applies to the current interpreter's view of
              the channel until all channels have closed it in that  direction
              (or  completely).   See  the interp command for a description of
              channel sharing.

              Channels are automatically fully closed when an  interpreter  is
              destroyed  and when the process exits.  Channels are switched to
              blocking mode, to ensure that all output  is  correctly  flushed
              before the process exits.

              The  command  returns an empty string, and may generate an error
              if an error occurs while flushing output.  If  a  command  in  a
              command  pipeline created with open returns an error, chan close
              generates an error (similar to the exec command.)

              Note that half-closes of sockets and command pipelines can  have |
              important  side  effects  because they result in a shutdown() or |
              close() of the underlying system resource, which can change  how |
              other processes or systems respond to the Tcl program.

       chan configure channelId ?optionName? ?value? ?optionName value?...
              Query  or  set  the  configuration  options of the channel named
              channelId.

              If no optionName or value arguments are  supplied,  the  command
              returns  a  list  containing alternating option names and values
              for the channel.  If optionName is supplied but  no  value  then
              the  command  returns the current value of the given option.  If
              one or more pairs of optionName and value are supplied, the com-
              mand  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 sup-
              ports. See the manual entry for the command  that  creates  each
              type  of channel for the options supported by that specific type
              of channel. For example, see the manual  entry  for  the  socket
              command for additional options for sockets, and the open command
              for additional options for serial devices.

              -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 non-blocking mode it will affect  the  opera-
                     tion  of the chan gets, chan read, chan puts, chan flush,
                     and chan close commands; see the documentation for  those
                     commands for details.  For non-blocking mode to work cor-
                     rectly, 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  out-
                     put  until  its internal buffer is full or until the chan
                     flush command is invoked. If newValue is line,  then  the
                     I/O  system will automatically flush output for the chan-
                     nel 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 termi-
                     nal-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, subsequently allocated for
                     this channel to store input or output. Newvalue must be a
                     number  of  no more than one million, allowing buffers of
                     up to one million bytes in size.

              -encoding name
                     This option is used to specify the encoding of the  chan-
                     nel  as  one  of the named encodings returned by encoding
                     names or the special value binary, 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  Ja-
                     panese  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  con-
                     verted 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 inter-
                     pretations of the bytes in the stream as well.

                     The  default  encoding  for  newly opened channels is the
                     same platform- and locale-dependent system 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 channels, a two-element
                     list  specifies the end of file marker for input and out-
                     put, 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 -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.  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 repre-
                     sented 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  chan  gets  and  chan
                     read)  the  Tcl  I/O  system automatically translates the
                     external end-of-line representation into newline  charac-
                     ters.  Upon output (i.e., with chan puts), the I/O system
                     translates newlines to the external end-of-line represen-
                     tation.   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 trans-
                     lation  mode  is  the  first element of the list, and the
                     write translation mode is the second element.  As a  con-
                     venience,  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,
                            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)
                            and  sets  the  encoding to binary (which disables
                            encoding  filtering).   See  the  description   of
                            -eofchar and -encoding for more information.

                     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.

                     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 trans-
                            lates newline characters to  carriage-return-line-
                            feed  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.

       chan copy inputChan outputChan ?-size size? ?-command callback?
              Copy data from the  channel  inputChan,  which  must  have  been
              opened  for  reading, to the channel outputChan, which must have
              been opened for writing. The chan  copy  command  leverages  the
              buffering  in  the  Tcl  I/O system to avoid extra copies and to
              avoid buffering too much data in main memory when copying  large
              files to slow destinations like network sockets.

              The chan copy command transfers data from inputChan until end of
              file or size bytes or characters have been transferred; size  is
              in bytes if the two channels are using the same encoding, and is
              in characters otherwise.  If no -size argument  is  given,  then
              the  copy  goes  until  end  of  file.  All  the  data read from
              inputChan is copied to outputChan.  Without the -command option,
              chan copy blocks until the copy is complete and returns the num-
              ber of bytes or characters (using the  same  rules  as  for  the
              -size option) written to outputChan.

              The  -command  argument  makes chan copy work in the background.
              In this case it returns immediately and the callback is  invoked
              later  when the copy completes.  The callback is called with one
              or two additional arguments that indicates how many  bytes  were
              written  to  outputChan.   If an error occurred during the back-
              ground copy, the second argument is the error string  associated
              with  the error.  With a background copy, it is not necessary to
              put inputChan or outputChan into  non-blocking  mode;  the  chan
              copy  command  takes care of that automatically.  However, it is
              necessary to enter the event loop by using the vwait command  or
              by using Tk.

              You are not allowed to do other I/O operations with inputChan or
              outputChan during a background chan copy.  If  either  inputChan
              or outputChan get closed while the copy is in progress, the cur-
              rent copy is stopped and the command callback is not  made.   If
              inputChan is closed, then all data already queued for outputChan
              is written out.

              Note that inputChan can  become  readable  during  a  background
              copy.   You should turn off any chan event or fileevent handlers
              during a background copy so those handlers do not interfere with
              the  copy.   Any I/O attempted by a chan event or fileevent han-
              dler will get a "channel busy" error.

              Chan copy translates end-of-line sequences in inputChan and out-
              putChan  according to the -translation option for these channels
              (see chan configure above).  The translations mean that the num-
              ber  of bytes read from inputChan can be different than the num-
              ber of bytes written to outputChan.  Only the  number  of  bytes
              written to outputChan is reported, either as the return value of
              a synchronous chan copy or as the argument to the  callback  for
              an asynchronous chan copy.

              Chan copy obeys the encodings and character translations config-
              ured for the channels. This means that the  incoming  characters
              are  converted internally first UTF-8 and then into the encoding
              of the channel chan copy writes to (see chan configure above for
              details  on  the -encoding and -translation options). No conver-
              sion is done if both channels are set  to  encoding  binary  and
              have matching translations. If only the output channel is set to
              encoding binary the system will write the internal UTF-8  repre-
              sentation  of the incoming characters. If only the input channel
              is set to encoding binary the system will assume that the incom-
              ing  bytes are valid UTF-8 characters and convert them according
              to the output encoding. The behaviour of the  system  for  bytes
              which are not valid UTF-8 characters is undefined in this case.

       chan create mode cmdPrefix
              This  subcommand  creates  a  new script level channel using the
              command prefix cmdPrefix as its handler.  Any  such  channel  is
              called  a  reflected channel. The specified command prefix, cmd-
              Prefix, must be a non-empty list, and  should  provide  the  API
              described  in  the  refchan  manual  page. The handle of the new
              channel is returned as the result of the  chan  create  command,
              and  the  channel  is  open.  Use  either close or chan close to
              remove the channel.

              The argument mode specifies if the new  channel  is  opened  for
              reading, writing, or both. It has to be a list containing any of
              the strings "read" or "write".  The list must have at least  one
              element,  as  a  channel  you can neither write to nor read from
              makes no sense. The handler command for  the  new  channel  must
              support the chosen mode, or an error is thrown.

              The  command  prefix is executed in the global namespace, at the
              top of call stack,  following  the  appending  of  arguments  as
              described in the refchan manual page. Command resolution happens
              at the time of the call. Renaming the command, or destroying  it
              means  that  the next call of a handler method may fail, causing
              the channel command  invoking  the  handler  to  fail  as  well.
              Depending on the subcommand being invoked, the error message may
              not be able to explain the reason for that failure.

              Every channel created with this subcommand  knows  which  inter-
              preter  it  was  created  in, and only ever executes its handler
              command in that interpreter, even if the channel was shared with
              and/or  was  moved  into a different interpreter. Each reflected
              channel also knows the thread it was created  in,  and  executes
              its handler command only in that thread, even if the channel was
              moved into a different thread. To this end  all  invocations  of
              the handler are forwarded to the original thread by posting spe-
              cial events to it. This means that the original thread (i.e. the
              thread  that  executed  the  chan  create  command) must have an
              active event loop, i.e. it must be able to process such  events.
              Otherwise the thread sending them will block indefinitely. Dead-
              lock may occur.

              Note that this permits the creation of a channel whose two  end-
              points  live  in  two different threads, providing a stream-ori-
              ented bridge between these threads. In other words, we can  pro-
              vide  a  way  for  regular  stream communication between threads
              instead of having to send commands.

              When a thread or interpreter is deleted,  all  channels  created
              with  this subcommand and using this thread/interpreter as their
              computing base are deleted as well,  in  all  interpreters  they
              have been shared with or moved into, and in whatever thread they
              have been transferred to. While this pulls the rug out under the
              other  thread(s)  and/or interpreter(s), this cannot be avoided.
              Trying to use such a channel will cause the generation of a reg-
              ular error about unknown channel handles.

              This  subcommand  is  safe  and  made  accessible to safe inter-
              preters.  While it arranges for the execution of  arbitrary  Tcl
              code the system also makes sure that the code is always executed
              within the safe interpreter.

       chan eof channelId
              Test whether the last input  operation  on  the  channel  called
              channelId failed because the end of the data stream was reached,
              returning 1 if end-of-file was reached, and 0 otherwise.

       chan event channelId event ?script?
              Arrange for the Tcl script script to  be  installed  as  a  file
              event handler to be called whenever the channel called channelId
              enters the state described by event (which must be either  read-
              able  or  writable);  only one such handler may be installed per
              event per channel at a time.  If script is the empty string, the
              current  handler is deleted (this also happens if the channel is
              closed or the interpreter deleted).  If script is  omitted,  the
              currently installed script is returned (or an empty string if no
              such handler is installed).  The callback is only  performed  if
              the event loop is being serviced (e.g. via vwait or update).

              A  file  event  handler  is  a  binding  between a channel and a
              script, such that the script is evaluated whenever  the  channel
              becomes readable or writable.  File event handlers are most com-
              monly used to allow data to be received from another process  on
              an  event-driven  basis,  so  that  the receiver can continue to
              interact with the user or with other channels while waiting  for
              the data to arrive.  If an application invokes chan gets or chan
              read on a blocking channel when there is no  input  data  avail-
              able,  the  process will block; until the input data arrives, it
              will not be able to service other events, so it will  appear  to
              the  user to "freeze up".  With chan event, the process can tell
              when data is present and only invoke chan gets or chan read when
              they will not block.

              A  channel  is considered to be readable if there is unread data
              available on the underlying device.  A channel is  also  consid-
              ered  to be readable if there is unread data in an input buffer,
              except in the special case where the most recent attempt to read
              from the channel was a chan gets call that could not find a com-
              plete line in the input buffer.  This feature allows a  file  to
              be  read  a line at a time in non-blocking mode using events.  A
              channel is also considered to be readable if an end of  file  or
              error condition is present on the underlying file or device.  It
              is important for script to check for these conditions and handle
              them  appropriately;  for  example, if there is no special check
              for end of file, an infinite loop may occur where  script  reads
              no data, returns, and is immediately invoked again.

              A  channel  is considered to be writable if at least one byte of
              data can be written to the underlying  file  or  device  without
              blocking,  or if an error condition is present on the underlying
              file or device.  Note that client sockets opened in asynchronous
              mode  become  writable when they become connected or if the con-
              nection fails.

              Event-driven I/O works best for channels that have  been  placed
              into  non-blocking  mode  with  the  chan configure command.  In
              blocking mode, a chan puts command may block if you give it more
              data  than  the underlying file or device can accept, and a chan
              gets or chan read command will block if you attempt to read more
              data  than  is ready; no events will be processed while the com-
              mands block.  In non-blocking mode chan  puts,  chan  read,  and
              chan gets never block.

              The script for a file event is executed at global level (outside
              the context of any Tcl procedure) in the  interpreter  in  which
              the  chan  event  command was invoked.  If an error occurs while
              executing the script then the  command  registered  with  interp
              bgerror  is  used  to  report  the error.  In addition, the file
              event handler is deleted if it ever returns an  error;  this  is
              done in order to prevent infinite loops due to buggy handlers.

       chan flush channelId
              Ensures that all pending output for the channel called channelId
              is written.

              If the channel is in blocking mode the command does  not  return
              until  all  the buffered output has been flushed to the channel.
              If the channel is in non-blocking mode, the command  may  return
              before  all buffered output has been flushed; the remainder will
              be flushed in the background as fast as the underlying  file  or
              device is able to absorb it.

       chan gets channelId ?varName?
              Reads  the  next line from the channel called channelId. If var-
              Name is not specified, the result of the  command  will  be  the
              line  that  has been read (without a trailing newline character)
              or an empty string upon end-of-file or, in non-blocking mode, if
              the  data  available  is exhausted. If varName is specified, the
              line that has been read will be written to the  variable  called
              varName  and  result  will be the number of characters that have
              been read or -1 if end-of-file was reached or,  in  non-blocking
              mode, if the data available is exhausted.

              If  an end-of-file occurs while part way through reading a line,
              the partial line will be returned  (or  written  into  varName).
              When  varName is not specified, the end-of-file case can be dis-
              tinguished from an empty line using the chan  eof  command,  and
              the partial-line-but-non-blocking case can be distinguished with
              the chan blocked command.

       chan names ?pattern?
              Produces a list of all channel names. If pattern  is  specified,
              only  those  channel names that match it (according to the rules
              of string match) will be returned.

       chan pending mode channelId
              Depending on whether mode is input or output, returns the number
              of  bytes  of  input or output (respectively) currently buffered
              internally for channelId (especially useful in a readable  event
              callback  to  impose  application-specific  limits on input line
              lengths to avoid a potential denial-of-service  attack  where  a
              hostile  user  crafts  an  extremely  long line that exceeds the
              available memory to buffer it).  Returns -1 if the  channel  was
              not opened for the mode in question.

       chan pipe
              Creates  a  standalone  pipe whose read- and write-side channels |
              are returned as a 2-element list, the first  element  being  the |
              read  side  and the second the write side. Can be useful e.g. to |
              redirect separately stderr and stdout from a subprocess.  To  do |
              this,  spawn  with  "2>@" or ">@" redirection operators onto the |
              write side of a pipe, and then immediately close it in the  par- |
              ent.  This  is necessary to get an EOF on the read side once the |
              child has exited or otherwise closed its output.                 |

              Note that the pipe buffering semantics can vary at the operating |
              system  level  substantially;  it  is  not safe to assume that a |
              write performed on the output  side  of  the  pipe  will  appear |
              instantly  to  the  input side. This is a fundamental difference |
              and Tcl cannot conceal it. The overall stream semantics are com- |
              patible,  so  blocking reads and writes will not see most of the |
              differences, but the details of what exactly gets  written  when |
              are not. This is most likely to show up when using pipelines for |
              testing; care should be taken to ensure that  deadlocks  do  not |
              occur and that potential short reads are allowed for.            |

       chan pop channelId
              Removes  the  topmost transformation from the channel channelId, |
              if there is any. If there are no transformations added to  chan- |
              nelId,  this  is  equivalent  to chan close of that channel. The |
              result is normally the empty string, but can be an error in some |
              situations  (i.e.  where  the underlying system stream is closed |
              and that results in an error).

       chan postevent channelId eventSpec
              This subcommand is used by command handlers specified with  chan
              create.  It notifies the channel represented by the handle chan-
              nelId that the event(s) listed in the eventSpec  have  occurred.
              The argument has to be a list containing any of the strings read
              and write. The list must contain at least one element as it does
              not  make  sense to invoke the command if there are no events to
              post.

              Note that this subcommand can only be used with channel  handles
              that were created/opened by chan create. All other channels will
              cause this subcommand to report an error.

              As only the Tcl level of a channel, i.e.  its  command  handler,
              should post events to it we also restrict the usage of this com-
              mand to the interpreter  that  created  the  channel.  In  other
              words, posting events to a reflected channel from an interpreter
              that does  not  contain  it's  implementation  is  not  allowed.
              Attempting  to  post  an  event  from any other interpreter will
              cause this subcommand to report an error.

              Another restriction is that it is not possible  to  post  events
              that  the  I/O core has not registered an interest in. Trying to
              do so will cause the method to throw an error. See  the  command
              handler method watch described in refchan, the document specify-
              ing the API of command handlers for reflected channels.

              This command is safe and made accessible to  safe  interpreters.
              It  can trigger the execution of chan event handlers, whether in
              the current  interpreter  or  in  other  interpreters  or  other
              threads,  even where the event is posted from a safe interpreter
              and listened for by a trusted interpreter. Chan  event  handlers
              are always executed in the interpreter that set them up.

       chan push channelId cmdPrefix
              Adds  a  new transformation on top of the channel channelId. The |
              cmdPrefix argument describes a list of one or more  words  which |
              represent a handler that will be used to implement the transfor- |
              mation. The command prefix must provide the API described in the |
              transchan  manual page.  The result of this subcommand is a han- |
              dle to the transformation. Note that it  is  important  to  make |
              sure  that the transformation is capable of supporting the chan- |
              nel mode that it is used with or this can make the channel  nei- |
              ther readable nor writable.

       chan puts ?-nonewline? ?channelId? string
              Writes  string to the channel named channelId followed by a new-
              line character. A trailing newline character is  written  unless
              the  optional flag -nonewline is given. If channelId is omitted,
              the string is written to the standard output channel, stdout.

              Newline characters in the output are translated by chan puts  to
              platform-specific  end-of-line  sequences  according to the cur-
              rently configured value of the -translation option for the chan-
              nel  (for  example,  on  PCs newlines are normally replaced with
              carriage-return-linefeed sequences; see chan configure above for
              details).

              Tcl  buffers  output internally, so characters written with chan
              puts may not appear immediately on the output  file  or  device;
              Tcl  will  normally delay output until the buffer is full or the
              channel is closed.  You can force output to  appear  immediately
              with the chan flush command.

              When the output buffer fills up, the chan puts command will nor-
              mally block until all the buffered data has  been  accepted  for
              output by the operating system.  If channelId is in non-blocking
              mode then the chan puts command will not block even if the oper-
              ating  system cannot accept the data.  Instead, Tcl continues to
              buffer the data and writes it in the background as fast  as  the
              underlying  file  or device can accept it.  The application must
              use the Tcl event loop for non-blocking output to  work;  other-
              wise  Tcl  never  finds out that the file or device is ready for
              more output data.  It  is  possible  for  an  arbitrarily  large
              amount  of  data  to  be  buffered for a channel in non-blocking
              mode, which could consume a large amount of  memory.   To  avoid
              wasting  memory,  non-blocking I/O should normally be used in an
              event-driven fashion with the chan event command (do not  invoke
              chan  puts  unless  you  have  recently been notified via a file
              event that the channel is ready for more output data).

       chan read channelId ?numChars?

       chan read ?-nonewline? channelId
              In the first form, the result will be the next numChars  charac-
              ters read from the channel named channelId; if numChars is omit-
              ted, all characters up to the point when the channel would  sig-
              nal  a  failure  (whether an end-of-file, blocked or other error
              condition) are read. In the second form (i.e. when numChars  has
              been  omitted) the flag -nonewline may be given to indicate that
              any trailing newline in the string that has been read should  be
              trimmed.

              If  channelId is in non-blocking mode, chan read may not read as
              many characters as requested: once all available input has  been
              read,  the command will return the data that is available rather
              than blocking for more input.  If the channel is  configured  to
              use a multi-byte encoding, then there may actually be some bytes
              remaining in the internal buffers that do not  form  a  complete
              character.   These  bytes  will not be returned until a complete
              character is available or end-of-file is reached.   The  -nonew-
              line  switch  is  ignored if the command returns before reaching
              the end of the file.

              Chan read translates end-of-line sequences  in  the  input  into
              newline  characters according to the -translation option for the
              channel (see chan configure above for a discussion on  the  ways
              in which chan configure will alter input).

              When  reading  from a serial port, most applications should con-
              figure the serial port channel to be non-blocking, like this:

                     chan configure channelId -blocking 0.

              Then chan read behaves much like  described  above.   Note  that
              most  serial ports are comparatively slow; it is entirely possi-
              ble to get a readable event for each character read  from  them.
              Care  must  be  taken  when  using  chan read on blocking serial
              ports:

              chan read channelId numChars
                     In this form chan read blocks until  numChars  have  been
                     received from the serial port.

              chan read channelId
                     In  this form chan read blocks until the reception of the
                     end-of-file character, see chan  configure  -eofchar.  If
                     there  no  end-of-file  character has been configured for
                     the channel, then chan read will block forever.

       chan seek channelId offset ?origin?
              Sets the current access  position  within  the  underlying  data
              stream  for the channel named channelId to be offset bytes rela-
              tive to origin. Offset must be an integer (which  may  be  nega-
              tive) and origin must be one of the following:

              start     The  new access position will be offset bytes from the
                        start of the underlying file or device.

              current   The new access position will be offset bytes from  the
                        current  access  position; a negative offset moves the
                        access position backwards in the  underlying  file  or
                        device.

              end       The  new access position will be offset bytes from the
                        end of the file or device.  A negative  offset  places
                        the access position before the end of file, and a pos-
                        itive offset places the access position after the  end
                        of file.

              The origin argument defaults to start.

              Chan seek flushes all buffered output for the channel before the
              command returns, even if the channel is  in  non-blocking  mode.
              It  also  discards  any buffered and unread input.  This command
              returns an empty string.  An error occurs  if  this  command  is
              applied  to  channels  whose  underlying file or device does not
              support seeking.

              Note that offset values are byte offsets, not character offsets.
              Both  chan  seek  and  chan  tell operate in terms of bytes, not
              characters, unlike chan read.

       chan tell channelId
              Returns a number giving the current access position  within  the
              underlying  data  stream  for  the channel named channelId. This
              value returned is a byte offset that can be passed to chan  seek
              in order to set the channel to a particular position.  Note that
              this value is in terms of bytes, not characters like chan  read.
              The  value returned is -1 for channels that do not support seek-
              ing.

       chan truncate channelId ?length?
              Sets the byte length of the underlying data stream for the chan-
              nel  named channelId to be length (or to the current byte offset
              within the underlying data stream if  length  is  omitted).  The
              channel is flushed before truncation.

EXAMPLES
       This  opens a file using a known encoding (CP1252, a very common encod-
       ing on Windows), searches for a string, rewrites that part,  and  trun-
       cates the file after a further two lines.

              set f [open somefile.txt r+]
              chan configure $f -encoding cp1252
              set offset 0

              # Search for string "FOOBAR" in the file
              while {[chan gets $f line] >= 0} {
                  set idx [string first FOOBAR $line]
                  if {$idx > -1} {
                      # Found it; rewrite line

                      chan seek $f [expr {$offset + $idx}]
                      chan puts -nonewline $f BARFOO

                      # Skip to end of following line, and truncate
                      chan gets $f
                      chan gets $f
                      chan truncate $f

                      # Stop searching the file now
                      break
                  }

                  # Save offset of start of next line for later
                  set offset [chan tell $f]
              }
              chan close $f

       A  network  server  that does echoing of its input line-by-line without
       preventing servicing of other connections at the same time.

              # This is a very simple logger...
              proc log {message} {
                  chan puts stdout $message
              }

              # This is called whenever a new client connects to the server
              proc connect {chan host port} {
                  set clientName [format <%s:%d> $host $port]
                  log "connection from $clientName"
                  chan configure $chan -blocking 0 -buffering line
                  chan event $chan readable [list echoLine $chan $clientName]
              }

              # This is called whenever either at least one byte of input
              # data is available, or the channel was closed by the client.
              proc echoLine {chan clientName} {
                  chan gets $chan line
                  if {[chan eof $chan]} {
                      log "finishing connection from $clientName"
                      chan close $chan
                  } elseif {![chan blocked $chan]} {
                      # Didn't block waiting for end-of-line
                      log "$clientName - $line"
                      chan puts $chan $line
                  }
              }

              # Create the server socket and enter the event-loop to wait
              # for incoming connections...
              socket -server connect 12345
              vwait forever


ATTRIBUTES
       See attributes(7) for descriptions of the following attributes:


       +---------------+------------------+
       |ATTRIBUTE TYPE | ATTRIBUTE VALUE  |
       +---------------+------------------+
       |Availability   | runtime/tcl-8    |
       +---------------+------------------+
       |Stability      | Uncommitted      |
       +---------------+------------------+
SEE ALSO
       close(n),  eof(n),  fblocked(n),  fconfigure(n),   fcopy(n),   file(n),
       fileevent(n),  flush(n),  gets(n),  open(n), puts(n), read(n), seek(n),
       socket(n), tell(n), refchan(n), transchan(n)

KEYWORDS
       channel, input, output, events, offset



NOTES
       This    software    was    built    from    source     available     at
       https://github.com/oracle/solaris-userland.    The  original  community
       source was downloaded from  http://prdownloads.sourceforge.net/tcl/tcl-
       core8.6.7-src.tar.gz

       Further information about this software can be found on the open source
       community website at https://www.tcl.tk/.



Tcl                                   8.5                             chan(1t)