[25] | 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: puts.n,v 1.13 2007/12/13 15:22:33 dgp Exp $ |
---|
| 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 | \fIChannelId\fR must be an identifier for an open channel such as a |
---|
| 26 | Tcl standard channel (\fBstdout\fR or \fBstderr\fR), the return |
---|
| 27 | value from an invocation of \fBopen\fR or \fBsocket\fR, or the result |
---|
| 28 | of a channel creation command provided by a Tcl extension. The channel |
---|
| 29 | must have been opened for output. |
---|
| 30 | .PP |
---|
| 31 | If no \fIchannelId\fR is specified then it defaults to |
---|
| 32 | \fBstdout\fR. \fBPuts\fR normally outputs a newline character after |
---|
| 33 | \fIstring\fR, but this feature may be suppressed by specifying the |
---|
| 34 | \fB\-nonewline\fR switch. |
---|
| 35 | .PP |
---|
| 36 | Newline characters in the output are translated by \fBputs\fR to |
---|
| 37 | platform-specific end-of-line sequences according to the current |
---|
| 38 | value of the \fB\-translation\fR option for the channel (for example, |
---|
| 39 | on PCs newlines are normally replaced with carriage-return-linefeed |
---|
| 40 | sequences. |
---|
| 41 | See the \fBfconfigure\fR manual entry for a discussion on ways in |
---|
| 42 | which \fBfconfigure\fR will alter output. |
---|
| 43 | .PP |
---|
| 44 | Tcl buffers output internally, so characters written with \fBputs\fR |
---|
| 45 | may not appear immediately on the output file or device; Tcl will |
---|
| 46 | normally delay output until the buffer is full or the channel is |
---|
| 47 | closed. |
---|
| 48 | You can force output to appear immediately with the \fBflush\fR |
---|
| 49 | command. |
---|
| 50 | .PP |
---|
| 51 | When the output buffer fills up, the \fBputs\fR command will normally |
---|
| 52 | block until all the buffered data has been accepted for output by the |
---|
| 53 | operating system. |
---|
| 54 | If \fIchannelId\fR is in nonblocking mode then the \fBputs\fR command |
---|
| 55 | will not block even if the operating system cannot accept the data. |
---|
| 56 | Instead, Tcl continues to buffer the data and writes it in the |
---|
| 57 | background as fast as the underlying file or device can accept it. |
---|
| 58 | The application must use the Tcl event loop for nonblocking output |
---|
| 59 | to work; otherwise Tcl never finds out that the file or device is |
---|
| 60 | ready for more output data. |
---|
| 61 | It is possible for an arbitrarily large amount of data to be |
---|
| 62 | buffered for a channel in nonblocking mode, which could consume a |
---|
| 63 | large amount of memory. |
---|
| 64 | To avoid wasting memory, nonblocking I/O should normally |
---|
| 65 | be used in an event-driven fashion with the \fBfileevent\fR command |
---|
| 66 | (do not invoke \fBputs\fR unless you have recently been notified |
---|
| 67 | via a file event that the channel is ready for more output data). |
---|
| 68 | .SH EXAMPLES |
---|
| 69 | Write a short message to the console (or wherever \fBstdout\fR is |
---|
| 70 | directed): |
---|
| 71 | .CS |
---|
| 72 | \fBputs\fR "Hello, World!" |
---|
| 73 | .CE |
---|
| 74 | .PP |
---|
| 75 | Print a message in several parts: |
---|
| 76 | .CS |
---|
| 77 | \fBputs\fR -nonewline "Hello, " |
---|
| 78 | \fBputs\fR "World!" |
---|
| 79 | .CE |
---|
| 80 | .PP |
---|
| 81 | Print a message to the standard error channel: |
---|
| 82 | .CS |
---|
| 83 | \fBputs\fR stderr "Hello, World!" |
---|
| 84 | .CE |
---|
| 85 | .PP |
---|
| 86 | Append a log message to a file: |
---|
| 87 | .CS |
---|
| 88 | set chan [open my.log a] |
---|
| 89 | set timestamp [clock format [clock seconds]] |
---|
| 90 | \fBputs\fR $chan "$timestamp - Hello, World!" |
---|
| 91 | close $chan |
---|
| 92 | .CE |
---|
| 93 | |
---|
| 94 | .SH "SEE ALSO" |
---|
| 95 | file(n), fileevent(n), Tcl_StandardChannels(3) |
---|
| 96 | |
---|
| 97 | .SH KEYWORDS |
---|
| 98 | channel, newline, output, write |
---|