diff options
Diffstat (limited to 'man1p/echo.1p')
| -rw-r--r-- | man1p/echo.1p | 246 |
1 files changed, 246 insertions, 0 deletions
diff --git a/man1p/echo.1p b/man1p/echo.1p new file mode 100644 index 000000000..4a371bf1b --- /dev/null +++ b/man1p/echo.1p @@ -0,0 +1,246 @@ +.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved +.TH "ECHO" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" echo +.SH NAME +echo \- write arguments to standard output +.SH SYNOPSIS +.LP +\fBecho\fP \fB[\fP\fIstring\fP \fB...\fP\fB]\fP +.SH DESCRIPTION +.LP +The \fIecho\fP utility writes its arguments to standard output, followed +by a <newline>. If there are no arguments, only +the <newline> is written. +.SH OPTIONS +.LP +The \fIecho\fP utility shall not recognize the \fB"--"\fP argument +in the manner specified by Guideline 10 of the Base +Definitions volume of IEEE\ Std\ 1003.1-2001, Section 12.2, Utility +Syntax +Guidelines; \fB"--"\fP shall be recognized as a string operand. +.LP +Implementations shall not support any options. +.SH OPERANDS +.LP +The following operands shall be supported: +.TP 7 +\fIstring\fP +A string to be written to standard output. If the first operand is +\fB-n\fP, or if any of the operands contain a backslash ( +\fB'\\'\fP ) character, the results are implementation-defined. +.LP +On XSI-conformant systems, if the first operand is \fB-n\fP, it shall +be treated as a string, not an option. The following +character sequences shall be recognized on XSI-conformant systems +within any of the arguments: +.TP 7 +\fB\\a\fP +.RS +Write an <alert>. +.RE +.TP 7 +\fB\\b\fP +.RS +Write a <backspace>. +.RE +.TP 7 +\fB\\c\fP +.RS +Suppress the <newline> that otherwise follows the final argument in +the output. All characters following the +\fB'\\c'\fP in the arguments shall be ignored. +.RE +.TP 7 +\fB\\f\fP +.RS +Write a <form-feed>. +.RE +.TP 7 +\fB\\n\fP +.RS +Write a <newline>. +.RE +.TP 7 +\fB\\r\fP +.RS +Write a <carriage-return>. +.RE +.TP 7 +\fB\\t\fP +.RS +Write a <tab>. +.RE +.TP 7 +\fB\\v\fP +.RS +Write a <vertical-tab>. +.RE +.TP 7 +\fB\\\\\fP +.RS +Write a backslash character. +.RE +.TP 7 +\fB\\0\fP\fInum\fP +.RS +Write an 8-bit value that is the zero, one, two, or three-digit octal +number \fInum\fP. +.RE +.sp +.sp +.SH STDIN +.LP +Not used. +.SH INPUT FILES +.LP +None. +.SH ENVIRONMENT VARIABLES +.LP +The following environment variables shall affect the execution of +\fIecho\fP: +.TP 7 +\fILANG\fP +Provide a default value for the internationalization variables that +are unset or null. (See the Base Definitions volume of +IEEE\ Std\ 1003.1-2001, Section 8.2, Internationalization Variables +for +the precedence of internationalization variables used to determine +the values of locale categories.) +.TP 7 +\fILC_ALL\fP +If set to a non-empty string value, override the values of all the +other internationalization variables. +.TP 7 +\fILC_CTYPE\fP +Determine the locale for the interpretation of sequences of bytes +of text data as characters (for example, single-byte as opposed +to multi-byte characters in arguments). +.TP 7 +\fILC_MESSAGES\fP +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard +error. +.TP 7 +\fINLSPATH\fP +Determine the location of message catalogs for the processing of \fILC_MESSAGES +\&.\fP +.sp +.SH ASYNCHRONOUS EVENTS +.LP +Default. +.SH STDOUT +.LP +The \fIecho\fP utility arguments shall be separated by single <space>s +and a <newline> shall follow the last +argument. \ Output transformations shall occur based on the escape +sequences in the input. See the OPERANDS section. +.SH STDERR +.LP +The standard error shall be used only for diagnostic messages. +.SH OUTPUT FILES +.LP +None. +.SH EXTENDED DESCRIPTION +.LP +None. +.SH EXIT STATUS +.LP +The following exit values shall be returned: +.TP 7 +\ 0 +Successful completion. +.TP 7 +>0 +An error occurred. +.sp +.SH CONSEQUENCES OF ERRORS +.LP +Default. +.LP +\fIThe following sections are informative.\fP +.SH APPLICATION USAGE +.LP +It is not possible to use \fIecho\fP portably across all POSIX systems +unless both \fB-n\fP (as the first argument) and escape +sequences are omitted. +.LP +The \fIprintf\fP utility can be used portably to emulate any of the +traditional +behaviors of the \fIecho\fP utility as follows (assuming that \fIIFS\fP +has its standard value or is unset): +.IP " *" 3 +The historic System V \fIecho\fP and the requirements on XSI implementations +in this volume of IEEE\ Std\ 1003.1-2001 +are equivalent to: +.sp +.RS +.nf + +\fBprintf "%b\\n" "$*" +\fP +.fi +.RE +.LP +.IP " *" 3 +The BSD \fIecho\fP is equivalent to: +.sp +.RS +.nf + +\fBif [ "X$1" = "X-n" ] +then + shift + printf "%s" "$*" +else + printf "%s\\n" "$*" +fi +\fP +.fi +.RE +.LP +.LP +New applications are encouraged to use \fIprintf\fP instead of \fIecho\fP. +.SH EXAMPLES +.LP +None. +.SH RATIONALE +.LP +The \fIecho\fP utility has not been made obsolescent because of its +extremely widespread use in historical applications. +Conforming applications that wish to do prompting without <newline>s +or that could possibly be expecting to echo a \fB-n\fP, +should use the \fIprintf\fP utility derived from the Ninth Edition +system. +.LP +As specified, \fIecho\fP writes its arguments in the simplest of ways. +The two different historical versions of \fIecho\fP +vary in fatally incompatible ways. +.LP +The BSD \fIecho\fP checks the first argument for the string \fB-n\fP +which causes it to suppress the <newline> that +would otherwise follow the final argument in the output. +.LP +The System V \fIecho\fP does not support any options, but allows escape +sequences within its operands, as described for XSI +implementations in the OPERANDS section. +.LP +The \fIecho\fP utility does not support Utility Syntax Guideline 10 +because historical applications depend on \fIecho\fP to +echo \fIall\fP of its arguments, except for the \fB-n\fP option in +the BSD version. +.SH FUTURE DIRECTIONS +.LP +None. +.SH SEE ALSO +.LP +\fIprintf\fP +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of +Electrical and Electronics Engineers, Inc and The Open Group. In the +event of any discrepancy between this version 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 . |