diff options
Diffstat (limited to '')
| -rw-r--r-- | upstream/mageia-cauldron/man1p/read.1p | 275 |
1 files changed, 275 insertions, 0 deletions
diff --git a/upstream/mageia-cauldron/man1p/read.1p b/upstream/mageia-cauldron/man1p/read.1p new file mode 100644 index 00000000..e09b896d --- /dev/null +++ b/upstream/mageia-cauldron/man1p/read.1p @@ -0,0 +1,275 @@ +'\" et +.TH READ "1P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +read +\(em read from standard input into shell variables +.SH SYNOPSIS +.LP +.nf +read \fB[\fR-r\fB] \fIvar\fR... +.fi +.SH DESCRIPTION +The +.IR read +utility shall read a single logical line from standard input into one +or more shell variables. +.P +By default, unless the +.BR \-r +option is specified, +<backslash> +shall act as an escape character. An unescaped +<backslash> +shall preserve the literal value of the following character, with the +exception of a +<newline>. +If a +<newline> +follows the +<backslash>, +the +.IR read +utility shall interpret this as line continuation. The +<backslash> +and +<newline> +shall be removed before splitting the input into fields. All other +unescaped +<backslash> +characters shall be removed after splitting the input into fields. +.P +If standard input is a terminal device and the invoking shell is +interactive, +.IR read +shall prompt for a continuation line when it reads an input line ending +with a +<backslash> +<newline>, +unless the +.BR \-r +option is specified. +.P +The terminating +<newline> +(if any) shall be removed from the input and the results shall be split +into fields as in the shell for the results of parameter expansion (see +.IR "Section 2.6.5" ", " "Field Splitting"); +the first field shall be assigned to the first variable +.IR var , +the second field to the second variable +.IR var , +and so on. If there are fewer fields than there are +.IR var +operands, the remaining +.IR var s +shall be set to empty strings. If there are fewer +.IR var s +than fields, the last +.IR var +shall be set to a value comprising the following elements: +.IP " *" 4 +The field that corresponds to the last +.IR var +in the normal assignment sequence described above +.IP " *" 4 +The delimiter(s) that follow the field corresponding to the last +.IR var +.IP " *" 4 +The remaining fields and their delimiters, with trailing +.IR IFS +white space ignored +.P +The setting of variables specified by the +.IR var +operands shall affect the current shell execution environment; see +.IR "Section 2.12" ", " "Shell Execution Environment". +If it is called in a subshell or separate utility execution +environment, such as one of the following: +.sp +.RS 4 +.nf + +(read foo) +nohup read ... +find . -exec read ... \e; +.fi +.P +.RE +.P +it shall not affect the shell variables in the caller's environment. +.SH OPTIONS +The +.IR read +utility shall conform to the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following option is supported: +.IP "\fB\-r\fP" 10 +Do not treat a +<backslash> +character in any special way. Consider each +<backslash> +to be part of the input line. +.SH OPERANDS +The following operand shall be supported: +.IP "\fIvar\fR" 10 +The name of an existing or nonexisting shell variable. +.SH STDIN +The standard input shall be a text file. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR read : +.IP "\fIIFS\fP" 10 +Determine the internal field separators used to delimit fields; see +.IR "Section 2.5.3" ", " "Shell Variables". +.IP "\fILANG\fP" 10 +Provide a default value for the internationalization variables that are +unset or null. (See the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 8.2" ", " "Internationalization Variables" +for the precedence of internationalization variables used to determine +the values of locale categories.) +.IP "\fILC_ALL\fP" 10 +If set to a non-empty string value, override the values of all the +other internationalization variables. +.IP "\fILC_CTYPE\fP" 10 +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). +.IP "\fILC_MESSAGES\fP" 10 +.br +Determine the locale that should be used to affect the format and +contents of diagnostic messages written to standard error. +.IP "\fINLSPATH\fP" 10 +Determine the location of message catalogs for the processing of +.IR LC_MESSAGES . +.IP "\fIPS2\fP" 10 +Provide the prompt string that an interactive shell shall write to +standard error when a line ending with a +<backslash> +<newline> +is read and the +.BR \-r +option was not specified. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +Not used. +.SH STDERR +The standard error shall be used for diagnostic messages and +prompts for continued input. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +Successful completion. +.IP >0 6 +End-of-file was detected or an error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +The +.BR \-r +option is included to enable +.IR read +to subsume the purpose of the +.IR line +utility, which is not included in POSIX.1\(hy2008. +.SH EXAMPLES +The following command: +.sp +.RS 4 +.nf + +while read -r xx yy +do + printf "%s %s\en$yy$xx" +done < \fIinput_file\fR +.fi +.P +.RE +.P +prints a file with the first field of each line moved to the end of the +line. +.SH RATIONALE +The +.IR read +utility historically has been a shell built-in. It was separated off +into its own utility to take advantage of the richer description of +functionality introduced by this volume of POSIX.1\(hy2017. +.P +Since +.IR read +affects the current shell execution environment, +it is generally provided as a shell regular built-in. If it is called +in a subshell or separate utility execution environment, such as one of +the following: +.sp +.RS 4 +.nf + +(read foo) +nohup read ... +find . -exec read ... \e; +.fi +.P +.RE +.P +it does not affect the shell variables in the environment of the +caller. +.P +Although the standard input is required to be a text file, and +therefore will always end with a +<newline> +(unless it is an empty file), the processing of continuation lines +when the +.BR \-r +option is not used can result in the input not ending with a +<newline>. +This occurs if the last line of the input file ends with a +<backslash> +<newline>. +It is for this reason that ``if any'' is used in ``The terminating +<newline> +(if any) shall be removed from the input'' in the description. +It is not a relaxation of the requirement for standard input to +be a text file. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Chapter 2" ", " "Shell Command Language" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 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 . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . |