path: root/usr/src/man/man1/echo.1

.\"
.\" 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
.\" http://www.opengroup.org/bookstore/.
.\"
.\" 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 SunOS 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.
.\"
.\" This notice shall appear on any product containing this material.
.\"
.\" 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.
.\"
.\" 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.
.\"
.\" 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]
.\"
.\"
.\" Copyright 1989 AT&T
.\" Portions Copyright (c) 1992, X/Open Company Limited  All Rights Reserved
.\" Portions Copyright (c) 1982-2007 AT&T Knowledge Ventures
.\" Copyright (c) 2008, Sun Microsystems, Inc.  All Rights Reserved
.\"
.TH ECHO 1 "Apr 14, 2016"
.SH NAME
echo \- echo arguments
.SH SYNOPSIS
.LP
.nf
\fB/usr/bin/echo\fR [\fIstring\fR]...
.fi

.SH DESCRIPTION
.LP
The \fBecho\fR utility writes its arguments, separated by BLANKs and terminated
by a NEWLINE, to the standard output. If there are no arguments, only the
NEWLINE character is written.
.sp
.LP
\fBecho\fR is useful for producing diagnostics in command files, for sending
known data into a pipe, and for displaying the contents of environment
variables.
.sp
.LP
The C shell, the Korn shell, and the Bourne shell all have \fBecho\fR built-in
commands, which, by default, is invoked if the user calls \fBecho\fR without a
full pathname. See \fBshell_builtins\fR(1). \fBsh\fR's \fBecho\fR, \fBksh\fR's
\fBecho\fR, \fBksh93\fR's \fBecho\fR, and \fB/usr/bin/echo\fR understand the
back-slashed escape characters, except that \fBsh\fR's \fBecho\fR does not
understand \fB\ea\fR as the alert character. In addition, \fBksh\fR's and
\fBksh93\fR's \fBecho\fR does not have an \fB-n\fR option.
\fBcsh\fR's \fBecho\fR and \fB/usr/ucb/echo\fR, on the other hand, have an
\fB-n\fR option, but do not understand the back-slashed escape characters.
\fBsh\fR and \fBksh\fR determine whether \fB/usr/ucb/echo\fR is found first in
the \fBPATH\fR and, if so, they adapt the behavior of the \fBecho\fR builtin to
match \fB/usr/ucb/echo\fR.
.SH OPERANDS
.LP
The following operand is supported:
.sp
.ne 2
.na
\fB\fIstring\fR\fR
.ad
.RS 10n
A string to be written to standard output. If any operand is "\fB-n\fR", it is
treated as a string, not an option. The following character sequences is
recognized within any of the arguments:
.sp
.ne 2
.na
\fB\fB\ea\fR\fR
.ad
.RS 8n
Alert character.
.RE

.sp
.ne 2
.na
\fB\fB\eb\fR\fR
.ad
.RS 8n
Backspace.
.RE

.sp
.ne 2
.na
\fB\fB\ec\fR\fR
.ad
.RS 8n
Print line without new-line. All characters following the \fB\ec\fR in the
argument are ignored.
.RE

.sp
.ne 2
.na
\fB\fB\ef\fR\fR
.ad
.RS 8n
Form-feed.
.RE

.sp
.ne 2
.na
\fB\fB\en\fR\fR
.ad
.RS 8n
New-line.
.RE

.sp
.ne 2
.na
\fB\fB\er\fR\fR
.ad
.RS 8n
Carriage return.
.RE

.sp
.ne 2
.na
\fB\fB\et\fR\fR
.ad
.RS 8n
Tab.
.RE

.sp
.ne 2
.na
\fB\fB\ev\fR\fR
.ad
.RS 8n
Vertical tab.
.RE

.sp
.ne 2
.na
\fB\fB\e\e\fR\fR
.ad
.RS 8n
Backslash.
.RE

.sp
.ne 2
.na
\fB\fB\e0\fR\fIn\fR\fR
.ad
.RS 8n
Where \fIn\fR is the 8-bit character whose \fBASCII\fR code is the 1-, 2- or
3-digit octal number representing that character.
.RE

.RE

.SH USAGE
.LP
Portable applications should not use \fB-n\fR (as the first argument) or escape
sequences.
.sp
.LP
The \fBprintf\fR(1) utility can be used portably to emulate any of the
traditional behaviors of the \fBecho\fR utility as follows:
.RS +4
.TP
.ie t \(bu
.el o
The Solaris 2.6 operating environment or compatible version's
\fB/usr/bin/echo\fR is equivalent to:
.sp
.in +2
.nf
\fBprintf "%b\en" "$*"\fR
.fi
.in -2
.sp

.RE
.RS +4
.TP
.ie t \(bu
.el o
The \fB/usr/ucb/echo\fR is equivalent to:
.sp
.in +2
.nf
if [ "X$1" = "X-n" ]

then

        shift

        printf "%s" "$*"

else

        printf "%s\en" "$*"

fi
.fi
.in -2

.RE
.sp
.LP
New applications are encouraged to use \fBprintf\fR instead of \fBecho\fR.
.SH EXAMPLES
.LP
\fBExample 1 \fRFinding how far below root your current directory is located
.sp
.LP
You can use \fBecho\fR to determine how many subdirectories below the root
directory (\fB/\fR) is your current directory, as follows:

.RS +4
.TP
.ie t \(bu
.el o
Echo your current-working-directory's full pathname.
.RE
.RS +4
.TP
.ie t \(bu
.el o
Pipe the output through \fBtr\fR to translate the path's embedded
slash-characters into space-characters.
.RE
.RS +4
.TP
.ie t \(bu
.el o
Pipe that output through \fBwc\fR \fB-w\fR for a count of the names in your
path.
.sp
.in +2
.nf
example% \fB/usr/bin/echo $PWD | tr '/' ' ' | wc -w\fR
.fi
.in -2
.sp

.RE
.sp
.LP
See \fBtr\fR(1) and \fBwc\fR(1) for their functionality.

.sp
.LP
Below are the different flavors for echoing a string without a NEWLINE:
.LP
\fBExample 2 \fR/usr/bin/echo
.sp
.in +2
.nf
example% \fB/usr/bin/echo "$USER's current directory is $PWD\ec"\fR
.fi
.in -2
.sp

.LP
\fBExample 3 \fRsh/ksh shells
.sp
.in +2
.nf
example$ \fBecho "$USER's current directory is $PWD\ec"\fR
.fi
.in -2
.sp

.LP
\fBExample 4 \fRcsh shell
.sp
.in +2
.nf
example% \fBecho -n "$USER's current directory is $PWD"\fR
.fi
.in -2
.sp

.LP
\fBExample 5 \fR/usr/ucb/echo
.sp
.in +2
.nf
example% \fB/usr/ucb/echo -n "$USER's current directory is $PWD"\fR
.fi
.in -2
.sp

.SH ENVIRONMENT VARIABLES
.LP
See \fBenviron\fR(7) for descriptions of the following environment variables
that affect the execution of \fBecho\fR: \fBLANG\fR, \fBLC_ALL\fR,
\fBLC_CTYPE\fR, \fBLC_MESSAGES\fR, and \fBNLSPATH\fR.

.SH EXIT STATUS
.LP
The following error values are returned:
.sp
.ne 2
.na
\fB\fB0\fR\fR
.ad
.RS 6n
Successful completion.
.RE

.sp
.ne 2
.na
\fB\fB>0\fR\fR
.ad
.RS 6n
An error occurred.
.RE

.SH ATTRIBUTES
.LP
See \fBattributes\fR(7) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
CSI	Enabled
_
Interface Stability	Committed
_
Standard	See \fBstandards\fR(7).
.TE

.SH SEE ALSO
.LP
.BR ksh93 (1),
.BR printf (1),
.BR shell_builtins (1),
.BR tr (1),
.BR wc (1),
.BR echo (1B),
.BR ascii (7),
.BR attributes (7),
.BR environ (7),
.BR standards (7)
.SH NOTES
.LP
When representing an 8-bit character by using the escape convention
\fB\e0\fR\fIn\fR, the \fIn\fR must \fBalways\fR be preceded by the digit zero
(\fB0\fR).
.sp
.LP
For example, typing: \fBecho 'WARNING:\e\|07'\fR prints the phrase
\fBWARNING:\fR and sounds the "bell" on your terminal. The use of single (or
double) quotes (or two backslashes) is required to protect the "\|\e" that
precedes the "07".
.sp
.LP
Following the \fB\e0\fR, up to three digits are used in constructing the octal
output character. If, following the \fB\e0\fR\fIn\fR, you want to echo
additional digits that are not part of the octal representation, you must use
the full 3-digit \fIn\fR. For example, if you want to echo "ESC 7" you must use
the three digits "033" rather than just the two digits "33" after the
\fB\e\|0\fR\&.
.sp
.in +2
.nf
2 digits         Incorrect:      echo "\e0337" | od -xc
                 produces:       df0a                     (hex)
                                 337                      (ascii)
3 digits         Correct:        echo "\e00337" | od -xc
                 produces:       lb37 0a00                (hex)
                                 033 7                    (ascii)
.fi
.in -2
.sp

.sp
.LP
For the octal equivalents of each character, see \fBascii\fR(7).