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 \fIChannelId\fR must be a channel identifier such as returned from a
  25 previous invocation of \fBopen\fR or \fBsocket\fR. It must have been opened
  26 for output. If no \fIchannelId\fR is specified then it defaults to
  27 \fBstdout\fR. \fBPuts\fR normally outputs a newline character after
  28 \fIstring\fR, but this feature may be suppressed by specifying the
  29 \fB\-nonewline\fR switch.
  30 .PP
  31 Newline characters in the output are translated by \fBputs\fR to
  32 platform-specific end-of-line sequences according to the current
  33 value of the \fB\-translation\fR option for the channel (for example,
  34 on PCs newlines are normally replaced with carriage-return-linefeed
  35 sequences;  on Macintoshes newlines are normally replaced with
  36 carriage-returns).
  37 See the \fBfconfigure\fR manual entry for a discussion of end-of-line
  38 translations.
  39 .PP
  40 Tcl buffers output internally, so characters written with \fBputs\fR
  41 may not appear immediately on the output file or device;  Tcl will
  42 normally delay output until the buffer is full or the channel is
  43 closed.
  44 You can force output to appear immediately with the \fBflush\fR
  45 command.
  46 .PP
  47 When the output buffer fills up, the \fBputs\fR command will normally
  48 block until all the buffered data has been accepted for output by the
  49 operating system.
  50 If \fIchannelId\fR is in nonblocking mode then the \fBputs\fR command
  51 will not block even if the operating system cannot accept the data.
  52 Instead, Tcl continues to buffer the data and writes it in the
  53 background as fast as the underlying file or device can accept it.
  54 The application must use the Tcl event loop for nonblocking output
  55 to work;  otherwise Tcl never finds out that the file or device is
  56 ready for more output data.
  57 It is possible for an arbitrarily large amount of data to be
  58 buffered for a channel in nonblocking mode, which could consume a
  59 large amount of memory.
  60 To avoid wasting memory, nonblocking I/O should normally
  61 be used in an event-driven fashion with the \fBfileevent\fR command
  62 (don't invoke \fBputs\fR unless you have recently been notified
  63 via a file event that the channel is ready for more output data).
  64
  65 .SH "SEE ALSO"
  66 fileevent(n)
  67
  68 .SH KEYWORDS
  69 channel, newline, output, write