tcl7.6 User Commands - puts






NAME

     puts - Write to a channel


SYNOPSIS

     puts ?-nonewline? ?channelId? string





DESCRIPTION

     Writes the characters given by string to the  channel  given
     by  channelId.   ChannelId must be a channel identifier such
     as returned from a previous invocation of open or socket. It
     must  have been opened for output. If no channelId is speci-
     fied then it defaults to stdout.  Puts  normally  outputs  a
     newline  character  after  string,  but  this feature may be
     suppressed by specifying the -nonewline switch.

     Newline characters in the output are translated by  puts  to
     platform-specific  end-of-line  sequences  according  to the
     current value of the -translation  option  for  the  channel
     (for  example,  on  PCs  newlines are normally replaced with
     carriage-return-linefeed sequences;  on Macintoshes newlines
     are normally replaced with carriage-returns).  See the fcon-
     figure manual entry for a discussion of end-of-line transla-
     tions.

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

     When the output buffer fills up, the 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 puts command will not block even if
     the operating 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 nonblocking out-
     put to work;  otherwise 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  chan-
     nel  in nonblocking mode, which could consume a large amount
     of memory.  To avoid wasting memory, nonblocking I/O  should
     normally  be  used  in  an  event-driven  fashion  with  the
     fileevent  command  (don't  invoke  puts  unless  you   have
     recently  been notified via a file event that the channel is
     ready for more output data).


SEE ALSO

     fileevent(n)



KEYWORDS

     channel, newline, output, write