tcl/doc/puts.n

   1 '\"
   2 '\" Copyright (c) 1993 The Regents of the University of California.
   3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
   4 '\"
   5 '\" See the file "license.terms" for information on usage and redistribution
   6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
   7 '\"
   8 '\" RCS: @(#) $Id$
   9 '\"
  10 .so man.macros
  11 .TH puts n 7.5 Tcl "Tcl Built-In Commands"
  12 .BS
  13 '\" Note:  do not modify the .SH NAME line immediately below!
  14 .SH NAME
  15 puts \- Write to a channel
  16 .SH SYNOPSIS
  17 \fBputs \fR?\fB\-nonewline\fR? ?\fIchannelId\fR? \fIstring\fR
  18 .BE
  19
  20 .SH DESCRIPTION
  21 .PP
  22 Writes the characters given by \fIstring\fR to the channel given
  23 by \fIchannelId\fR.
  24 .PP
  25 .VS
  26 \fIChannelId\fR must be an identifier for an open channel such as a
  27 Tcl standard channel (\fBstdout\fR or \fBstderr\fR), the return
  28 value from an invocation of \fBopen\fR or \fBsocket\fR, or the result
  29 of a channel creation command provided by a Tcl extension. The channel
  30 must have been opened for output.
  31 .VE
  32 .PP
  33 If no \fIchannelId\fR is specified then it defaults to
  34 \fBstdout\fR. \fBPuts\fR normally outputs a newline character after
  35 \fIstring\fR, but this feature may be suppressed by specifying the
  36 \fB\-nonewline\fR switch.
  37 .PP
  38 Newline characters in the output are translated by \fBputs\fR to
  39 platform-specific end-of-line sequences according to the current
  40 value of the \fB\-translation\fR option for the channel (for example,
  41 on PCs newlines are normally replaced with carriage-return-linefeed
  42 sequences;  on Macintoshes newlines are normally replaced with
  43 carriage-returns).
  44 See the \fBfconfigure\fR manual entry for a discussion on ways in
  45 which \fBfconfigure\fR will alter output.
  46 .PP
  47 Tcl buffers output internally, so characters written with \fBputs\fR
  48 may not appear immediately on the output file or device;  Tcl will
  49 normally delay output until the buffer is full or the channel is
  50 closed.
  51 You can force output to appear immediately with the \fBflush\fR
  52 command.
  53 .PP
  54 When the output buffer fills up, the \fBputs\fR command will normally
  55 block until all the buffered data has been accepted for output by the
  56 operating system.
  57 If \fIchannelId\fR is in nonblocking mode then the \fBputs\fR command
  58 will not block even if the operating system cannot accept the data.
  59 Instead, Tcl continues to buffer the data and writes it in the
  60 background as fast as the underlying file or device can accept it.
  61 The application must use the Tcl event loop for nonblocking output
  62 to work;  otherwise Tcl never finds out that the file or device is
  63 ready for more output data.
  64 It is possible for an arbitrarily large amount of data to be
  65 buffered for a channel in nonblocking mode, which could consume a
  66 large amount of memory.
  67 To avoid wasting memory, nonblocking I/O should normally
  68 be used in an event-driven fashion with the \fBfileevent\fR command
  69 (don't invoke \fBputs\fR unless you have recently been notified
  70 via a file event that the channel is ready for more output data).
  71
  72 .SH "SEE ALSO"
  73 file(n), fileevent(n), Tcl_StandardChannels(3)
  74
  75 .SH KEYWORDS
  76 channel, newline, output, write