usr/src/man/man1/echo.1

   1 '\" te
   2 .\" Copyright 1989 AT&T
   3 .\" Copyright (c) 2008, Sun Microsystems, Inc.  All Rights Reserved
   4 .\" Portions Copyright (c) 1992, X/Open Company Limited  All Rights Reserved
   5 .\" Portions Copyright (c) 1982-2007 AT&T Knowledge Ventures
   6 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for permission to reproduce portions of its copyrighted documentation. Original documentation from The Open Group can be obtained online at
   7 .\" http://www.opengroup.org/bookstore/.
   8 .\" The Institute of Electrical and Electronics Engineers and The Open Group, have given us permission to reprint portions of their documentation. In the following statement, the phrase "this text" refers to portions of the system documentation. Portions of this text are reprinted and reproduced in electronic form in the Sun OS Reference Manual, from IEEE Std 1003.1, 2004 Edition, Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2004 by the Institute of Electrical and Electronics Engineers, Inc and The Open Group. In the event of any discrepancy between these versions and the original IEEE and The Open Group Standard, the original IEEE and The Open Group Standard is the referee document. The original Standard can be obtained online at http://www.opengroup.org/unix/online.html.
   9 .\"  This notice shall appear on any product containing this material.
  10 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
  11 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
  12 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
  13 .TH ECHO 1 "Apr 14, 2016"
  14 .SH NAME
  15 echo \- echo arguments
  16 .SH SYNOPSIS
  17 .LP
  18 .nf
  19 \fB/usr/bin/echo\fR [\fIstring\fR]...
  20 .fi
  21
  22 .SH DESCRIPTION
  23 .LP
  24 The \fBecho\fR utility writes its arguments, separated by BLANKs and terminated
  25 by a NEWLINE, to the standard output. If there are no arguments, only the
  26 NEWLINE character is written.
  27 .sp
  28 .LP
  29 \fBecho\fR is useful for producing diagnostics in command files, for sending
  30 known data into a pipe, and for displaying the contents of environment
  31 variables.
  32 .sp
  33 .LP
  34 The C shell, the Korn shell, and the Bourne shell all have \fBecho\fR built-in
  35 commands, which, by default, is invoked if the user calls \fBecho\fR without a
  36 full pathname. See \fBshell_builtins\fR(1). \fBsh\fR's \fBecho\fR, \fBksh\fR's
  37 \fBecho\fR, \fBksh93\fR's \fBecho\fR, and \fB/usr/bin/echo\fR understand the
  38 back-slashed escape characters, except that \fBsh\fR's \fBecho\fR does not
  39 understand \fB\ea\fR as the alert character. In addition, \fBksh\fR's and
  40 \fBksh93\fR's \fBecho\fR does not have an \fB-n\fR option.
  41 \fBcsh\fR's \fBecho\fR and \fB/usr/ucb/echo\fR, on the other hand, have an
  42 \fB-n\fR option, but do not understand the back-slashed escape characters.
  43 \fBsh\fR and \fBksh\fR determine whether \fB/usr/ucb/echo\fR is found first in
  44 the \fBPATH\fR and, if so, they adapt the behavior of the \fBecho\fR builtin to
  45 match \fB/usr/ucb/echo\fR.
  46 .SH OPERANDS
  47 .LP
  48 The following operand is supported:
  49 .sp
  50 .ne 2
  51 .na
  52 \fB\fIstring\fR\fR
  53 .ad
  54 .RS 10n
  55 A string to be written to standard output. If any operand is "\fB-n\fR", it is
  56 treated as a string, not an option. The following character sequences is
  57 recognized within any of the arguments:
  58 .sp
  59 .ne 2
  60 .na
  61 \fB\fB\ea\fR\fR
  62 .ad
  63 .RS 8n
  64 Alert character.
  65 .RE
  66
  67 .sp
  68 .ne 2
  69 .na
  70 \fB\fB\eb\fR\fR
  71 .ad
  72 .RS 8n
  73 Backspace.
  74 .RE
  75
  76 .sp
  77 .ne 2
  78 .na
  79 \fB\fB\ec\fR\fR
  80 .ad
  81 .RS 8n
  82 Print line without new-line. All characters following the \fB\ec\fR in the
  83 argument are ignored.
  84 .RE
  85
  86 .sp
  87 .ne 2
  88 .na
  89 \fB\fB\ef\fR\fR
  90 .ad
  91 .RS 8n
  92 Form-feed.
  93 .RE
  94
  95 .sp
  96 .ne 2
  97 .na
  98 \fB\fB\en\fR\fR
  99 .ad
 100 .RS 8n
 101 New-line.
 102 .RE
 103
 104 .sp
 105 .ne 2
 106 .na
 107 \fB\fB\er\fR\fR
 108 .ad
 109 .RS 8n
 110 Carriage return.
 111 .RE
 112
 113 .sp
 114 .ne 2
 115 .na
 116 \fB\fB\et\fR\fR
 117 .ad
 118 .RS 8n
 119 Tab.
 120 .RE
 121
 122 .sp
 123 .ne 2
 124 .na
 125 \fB\fB\ev\fR\fR
 126 .ad
 127 .RS 8n
 128 Vertical tab.
 129 .RE
 130
 131 .sp
 132 .ne 2
 133 .na
 134 \fB\fB\e\e\fR\fR
 135 .ad
 136 .RS 8n
 137 Backslash.
 138 .RE
 139
 140 .sp
 141 .ne 2
 142 .na
 143 \fB\fB\e0\fR\fIn\fR\fR
 144 .ad
 145 .RS 8n
 146 Where \fIn\fR is the 8-bit character whose \fBASCII\fR code is the 1-, 2- or
 147 3-digit octal number representing that character.
 148 .RE
 149
 150 .RE
 151
 152 .SH USAGE
 153 .LP
 154 Portable applications should not use \fB-n\fR (as the first argument) or escape
 155 sequences.
 156 .sp
 157 .LP
 158 The \fBprintf\fR(1) utility can be used portably to emulate any of the
 159 traditional behaviors of the \fBecho\fR utility as follows:
 160 .RS +4
 161 .TP
 162 .ie t \(bu
 163 .el o
 164 The Solaris 2.6 operating environment or compatible version's
 165 \fB/usr/bin/echo\fR is equivalent to:
 166 .sp
 167 .in +2
 168 .nf
 169 \fBprintf "%b\en" "$*"\fR
 170 .fi
 171 .in -2
 172 .sp
 173
 174 .RE
 175 .RS +4
 176 .TP
 177 .ie t \(bu
 178 .el o
 179 The \fB/usr/ucb/echo\fR is equivalent to:
 180 .sp
 181 .in +2
 182 .nf
 183 if [ "X$1" = "X-n" ]
 184
 185 then
 186
 187         shift
 188
 189         printf "%s" "$*"
 190
 191 else
 192
 193         printf "%s\en" "$*"
 194
 195 fi
 196 .fi
 197 .in -2
 198
 199 .RE
 200 .sp
 201 .LP
 202 New applications are encouraged to use \fBprintf\fR instead of \fBecho\fR.
 203 .SH EXAMPLES
 204 .LP
 205 \fBExample 1 \fRFinding how far below root your current directory is located
 206 .sp
 207 .LP
 208 You can use \fBecho\fR to determine how many subdirectories below the root
 209 directory (\fB/\fR) is your current directory, as follows:
 210
 211 .RS +4
 212 .TP
 213 .ie t \(bu
 214 .el o
 215 Echo your current-working-directory's full pathname.
 216 .RE
 217 .RS +4
 218 .TP
 219 .ie t \(bu
 220 .el o
 221 Pipe the output through \fBtr\fR to translate the path's embedded
 222 slash-characters into space-characters.
 223 .RE
 224 .RS +4
 225 .TP
 226 .ie t \(bu
 227 .el o
 228 Pipe that output through \fBwc\fR \fB-w\fR for a count of the names in your
 229 path.
 230 .sp
 231 .in +2
 232 .nf
 233 example% \fB/usr/bin/echo $PWD | tr '/' ' ' | wc -w\fR
 234 .fi
 235 .in -2
 236 .sp
 237
 238 .RE
 239 .sp
 240 .LP
 241 See \fBtr\fR(1) and \fBwc\fR(1) for their functionality.
 242
 243 .sp
 244 .LP
 245 Below are the different flavors for echoing a string without a NEWLINE:
 246 .LP
 247 \fBExample 2 \fR/usr/bin/echo
 248 .sp
 249 .in +2
 250 .nf
 251 example% \fB/usr/bin/echo "$USER's current directory is $PWD\ec"\fR
 252 .fi
 253 .in -2
 254 .sp
 255
 256 .LP
 257 \fBExample 3 \fRsh/ksh shells
 258 .sp
 259 .in +2
 260 .nf
 261 example$ \fBecho "$USER's current directory is $PWD\ec"\fR
 262 .fi
 263 .in -2
 264 .sp
 265
 266 .LP
 267 \fBExample 4 \fRcsh shell
 268 .sp
 269 .in +2
 270 .nf
 271 example% \fBecho -n "$USER's current directory is $PWD"\fR
 272 .fi
 273 .in -2
 274 .sp
 275
 276 .LP
 277 \fBExample 5 \fR/usr/ucb/echo
 278 .sp
 279 .in +2
 280 .nf
 281 example% \fB/usr/ucb/echo -n "$USER's current directory is $PWD"\fR
 282 .fi
 283 .in -2
 284 .sp
 285
 286 .SH ENVIRONMENT VARIABLES
 287 .LP
 288 See \fBenviron\fR(5) for descriptions of the following environment variables
 289 that affect the execution of \fBecho\fR: \fBLANG\fR, \fBLC_ALL\fR,
 290 \fBLC_CTYPE\fR, \fBLC_MESSAGES\fR, and \fBNLSPATH\fR.
 291
 292 .SH EXIT STATUS
 293 .LP
 294 The following error values are returned:
 295 .sp
 296 .ne 2
 297 .na
 298 \fB\fB0\fR\fR
 299 .ad
 300 .RS 6n
 301 Successful completion.
 302 .RE
 303
 304 .sp
 305 .ne 2
 306 .na
 307 \fB\fB>0\fR\fR
 308 .ad
 309 .RS 6n
 310 An error occurred.
 311 .RE
 312
 313 .SH ATTRIBUTES
 314 .LP
 315 See \fBattributes\fR(5) for descriptions of the following attributes:
 316 .sp
 317
 318 .sp
 319 .TS
 320 box;
 321 c | c
 322 l | l .
 323 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 324 _
 325 CSI     Enabled
 326 _
 327 Interface Stability     Committed
 328 _
 329 Standard        See \fBstandards\fR(5).
 330 .TE
 331
 332 .SH SEE ALSO
 333 .LP
 334 \fBksh93\fR(1), \fBprintf\fR(1), \fBshell_builtins\fR(1), \fBtr\fR(1),
 335 \fBwc\fR(1), \fBecho\fR(1B), \fBascii\fR(5), \fBattributes\fR(5),
 336 \fBenviron\fR(5), \fBstandards\fR(5)
 337 .SH NOTES
 338 .LP
 339 When representing an 8-bit character by using the escape convention
 340 \fB\e0\fR\fIn\fR, the \fIn\fR must \fBalways\fR be preceded by the digit zero
 341 (\fB0\fR).
 342 .sp
 343 .LP
 344 For example, typing: \fBecho 'WARNING:\e\|07'\fR prints the phrase
 345 \fBWARNING:\fR and sounds the "bell" on your terminal. The use of single (or
 346 double) quotes (or two backslashes) is required to protect the "\|\e" that
 347 precedes the "07".
 348 .sp
 349 .LP
 350 Following the \fB\e0\fR, up to three digits are used in constructing the octal
 351 output character. If, following the \fB\e0\fR\fIn\fR, you want to echo
 352 additional digits that are not part of the octal representation, you must use
 353 the full 3-digit \fIn\fR. For example, if you want to echo "ESC 7" you must use
 354 the three digits "033" rather than just the two digits "33" after the
 355 \fB\e\|0\fR\&.
 356 .sp
 357 .in +2
 358 .nf
 359 2 digits         Incorrect:      echo "\e0337" | od -xc
 360                  produces:       df0a                     (hex)
 361                                  337                      (ascii)
 362 3 digits         Correct:        echo "\e00337" | od -xc
 363                  produces:       lb37 0a00                (hex)
 364                                  033 7                    (ascii)
 365 .fi
 366 .in -2
 367 .sp
 368
 369 .sp
 370 .LP
 371 For the octal equivalents of each character, see \fBascii\fR(5).