1<HTML><HEAD><TITLE>Tcl Built-In Commands - puts manual page</TITLE></HEAD><BODY> 2<H3><A NAME="M2">NAME</A></H3> 3puts - Write to a channel 4<H3><A NAME="M3">SYNOPSIS</A></H3> 5<B>puts </B>?<B>-nonewline</B>? ?<I>channelId</I>? <I>string</I><BR> 6<H3><A NAME="M4">DESCRIPTION</A></H3> 7Writes the characters given by <I>string</I> to the channel given 8by <I>channelId</I>. 9<P> 10<I>ChannelId</I> must be an identifier for an open channel such as a 11Tcl standard channel (<B>stdout</B> or <B>stderr</B>), the return 12value from an invocation of <B><A HREF="../TclCmd/open.htm">open</A></B> or <B><A HREF="../TclCmd/socket.htm">socket</A></B>, or the result 13of a channel creation command provided by a Tcl extension. The channel 14must have been opened for output. 15<P> 16If no <I>channelId</I> is specified then it defaults to 17<B>stdout</B>. <B>Puts</B> normally outputs a newline character after 18<I>string</I>, but this feature may be suppressed by specifying the 19<B>-nonewline</B> switch. 20<P> 21Newline characters in the output are translated by <B>puts</B> to 22platform-specific end-of-line sequences according to the current 23value of the <B>-translation</B> option for the channel (for example, 24on PCs newlines are normally replaced with carriage-return-linefeed 25sequences). 26See the <B><A HREF="../TclCmd/fconfigure.htm">fconfigure</A></B> manual entry for a discussion on ways in 27which <B><A HREF="../TclCmd/fconfigure.htm">fconfigure</A></B> will alter output. 28<P> 29Tcl buffers output internally, so characters written with <B>puts</B> 30may not appear immediately on the output file or device; Tcl will 31normally delay output until the buffer is full or the channel is 32closed. 33You can force output to appear immediately with the <B><A HREF="../TclCmd/flush.htm">flush</A></B> 34command. 35<P> 36When the output buffer fills up, the <B>puts</B> command will normally 37block until all the buffered data has been accepted for output by the 38operating system. 39If <I>channelId</I> is in nonblocking mode then the <B>puts</B> command 40will not block even if the operating system cannot accept the data. 41Instead, Tcl continues to buffer the data and writes it in the 42background as fast as the underlying file or device can accept it. 43The application must use the Tcl event loop for nonblocking output 44to work; otherwise Tcl never finds out that the file or device is 45ready for more output data. 46It is possible for an arbitrarily large amount of data to be 47buffered for a channel in nonblocking mode, which could consume a 48large amount of memory. 49To avoid wasting memory, nonblocking I/O should normally 50be used in an event-driven fashion with the <B><A HREF="../TclCmd/fileevent.htm">fileevent</A></B> command 51(don't invoke <B>puts</B> unless you have recently been notified 52via a file event that the channel is ready for more output data). 53<H3><A NAME="M5">EXAMPLES</A></H3> 54Write a short message to the console (or wherever <B>stdout</B> is 55directed): 56<PRE><B>puts</B> "Hello, World!"</PRE> 57<P> 58Print a message in several parts: 59<PRE><B>puts</B> -nonewline "Hello, " 60<B>puts</B> "World!"</PRE> 61<P> 62Print a message to the standard error channel: 63<PRE><B>puts</B> stderr "Hello, World!"</PRE> 64<P> 65Append a log message to a file: 66<PRE>set chan [open my.log a] 67set timestamp [clock format [clock seconds]] 68<B>puts</B> $chan "$timestamp - Hello, World!" 69close $chan</PRE> 70<H3><A NAME="M6">SEE ALSO</A></H3> 71<B><A HREF="../TclCmd/file.htm">file</A></B>, <B><A HREF="../TclCmd/fileevent.htm">fileevent</A></B>, <B><A HREF="../TclLib/StdChannels.htm">Tcl_StandardChannels</A></B> 72<H3><A NAME="M7">KEYWORDS</A></H3> 73<A href="../Keywords/C.htm#channel">channel</A>, <A href="../Keywords/N.htm#newline">newline</A>, <A href="../Keywords/O.htm#output">output</A>, <A href="../Keywords/W.htm#write">write</A> 74<HR><PRE> 75<A HREF="../copyright.htm">Copyright</A> © 1993 The Regents of the University of California. 76<A HREF="../copyright.htm">Copyright</A> © 1994-1996 Sun Microsystems, Inc. 77<A HREF="../copyright.htm">Copyright</A> © 1995-1997 Roger E. Critchlow Jr.</PRE> 78</BODY></HTML> 79