diff options
Diffstat (limited to 'man-pages-posix-2017/man1p/grep.1p')
| -rw-r--r-- | man-pages-posix-2017/man1p/grep.1p | 540 |
1 files changed, 540 insertions, 0 deletions
diff --git a/man-pages-posix-2017/man1p/grep.1p b/man-pages-posix-2017/man1p/grep.1p new file mode 100644 index 0000000..2ce37c5 --- /dev/null +++ b/man-pages-posix-2017/man1p/grep.1p @@ -0,0 +1,540 @@ +'\" et +.TH GREP "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 +grep +\(em search a file for a pattern +.SH SYNOPSIS +.LP +.nf +grep \fB[\fR-E|-F\fB] [\fR-c|-l|-q\fB] [\fR-insvx\fB] \fR-e \fIpattern_list + \fB[\fR-e \fIpattern_list\fB]\fR... \fB[\fR-f \fIpattern_file\fB]\fR... \fB[\fIfile\fR...\fB]\fR +.P +grep \fB[\fR-E|-F\fB] [\fR-c|-l|-q\fB] [\fR-insvx\fB] [\fR-e \fIpattern_list\fB]... + \fR-f \fIpattern_file \fB[\fR-f \fIpattern_file\fB]\fR... \fB[\fIfile\fR...\fB]\fR +.P +grep \fB[\fR-E|-F\fB] [\fR-c|-l|-q\fB] [\fR-insvx\fB] \fIpattern_list\fB [\fIfile\fR...\fB]\fR +.fi +.SH DESCRIPTION +The +.IR grep +utility shall search the input files, selecting lines matching one or +more patterns; the types of patterns are controlled by the options +specified. The patterns are specified by the +.BR \-e +option, +.BR \-f +option, or the +.IR pattern_list +operand. The +.IR pattern_list 's +value shall consist of one or more patterns separated by +<newline> +characters; the +.IR pattern_file 's +contents shall consist of one or more patterns terminated by a +<newline> +character. By default, an input line shall be selected if any +pattern, treated as an entire basic regular expression (BRE) as +described in the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 9.3" ", " "Basic Regular Expressions", +matches any part of the line excluding the terminating +<newline>; +a null BRE shall match every line. By default, each selected input +line shall be written to the standard output. +.P +Regular expression matching shall be based on text lines. Since a +<newline> +separates or terminates patterns (see the +.BR \-e +and +.BR \-f +options below), regular expressions cannot contain a +<newline>. +Similarly, since patterns are matched against individual lines +(excluding the terminating +<newline> +characters) of the input, there is no way for a pattern to match a +<newline> +found in the input. +.SH OPTIONS +The +.IR grep +utility shall conform to the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 12.2" ", " "Utility Syntax Guidelines". +.P +The following options shall be supported: +.IP "\fB\-E\fP" 10 +Match using extended regular expressions. +Treat each pattern specified as an ERE, as described in the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 9.4" ", " "Extended Regular Expressions". +If any entire ERE pattern matches some part of an input line excluding +the terminating +<newline>, +the line shall be matched. A null ERE shall match every line. +.IP "\fB\-F\fP" 10 +Match using fixed strings. Treat each pattern specified as a string +instead of a regular expression. If an input line contains any of the +patterns as a contiguous sequence of bytes, the line shall be matched. +A null string shall match every line. +.IP "\fB\-c\fP" 10 +Write only a count of selected lines to standard output. +.IP "\fB\-e\ \fIpattern_list\fR" 10 +.br +Specify one or more patterns to be used during the search for input. +The application shall ensure that patterns in +.IR pattern_list +are separated by a +<newline>. +A null pattern can be specified by two adjacent +<newline> +characters in +.IR pattern_list . +Unless the +.BR \-E +or +.BR \-F +option is also specified, each pattern shall be treated as a BRE, as +described in the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 9.3" ", " "Basic Regular Expressions". +Multiple +.BR \-e +and +.BR \-f +options shall be accepted by the +.IR grep +utility. All of the specified patterns shall be used when matching +lines, but the order of evaluation is unspecified. +.IP "\fB\-f\ \fIpattern_file\fR" 10 +.br +Read one or more patterns from the file named by the pathname +.IR pattern_file . +Patterns in +.IR pattern_file +shall be terminated by a +<newline>. +A null pattern can be specified by an empty line in +.IR pattern_file . +Unless the +.BR \-E +or +.BR \-F +option is also specified, each pattern shall be treated as a BRE, as +described in the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 9.3" ", " "Basic Regular Expressions". +.IP "\fB\-i\fP" 10 +Perform pattern matching in searches without regard to case; see the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 9.2" ", " "Regular Expression General Requirements". +.IP "\fB\-l\fP" 10 +(The letter ell.) Write only the names of files containing selected +lines to standard output. Pathnames shall be written once per file +searched. If the standard input is searched, a pathname of +.BR \(dq(standard input)\(dq +shall be written, in the POSIX locale. In other locales, +.BR \(dqstandard input\(dq +may be replaced by something more appropriate in those locales. +.IP "\fB\-n\fP" 10 +Precede each output line by its relative line number in the file, each +file starting at line 1. The line number counter shall be reset for +each file processed. +.IP "\fB\-q\fP" 10 +Quiet. Nothing shall be written to the standard output, regardless of +matching lines. Exit with zero status if an input line is selected. +.IP "\fB\-s\fP" 10 +Suppress the error messages ordinarily written for nonexistent or +unreadable files. Other error messages shall not be suppressed. +.IP "\fB\-v\fP" 10 +Select lines not matching any of the specified patterns. If the +.BR \-v +option is not specified, selected lines shall be those that match any +of the specified patterns. +.IP "\fB\-x\fP" 10 +Consider only input lines that use all characters in the line excluding +the terminating +<newline> +to match an entire fixed string or regular expression to be matching +lines. +.SH OPERANDS +The following operands shall be supported: +.IP "\fIpattern_list\fR" 10 +Specify one or more patterns to be used during the search for input. +This operand shall be treated as if it were specified as +.BR \-e +.IR pattern_list . +.IP "\fIfile\fR" 10 +A pathname of a file to be searched for the patterns. If no +.IR file +operands are specified, the standard input shall be used. +.SH STDIN +The standard input shall be used if no +.IR file +operands are specified, and shall be used if a +.IR file +operand is +.BR '\-' +and the implementation treats the +.BR '\-' +as meaning standard input. +Otherwise, the standard input shall not be used. +See the INPUT FILES section. +.SH "INPUT FILES" +The input files shall be text files. +.SH "ENVIRONMENT VARIABLES" +The following environment variables shall affect the execution of +.IR grep : +.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_COLLATE\fP" 10 +.br +Determine the locale for the behavior of ranges, equivalence classes, +and multi-character collating elements within regular expressions. +.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 and input files) and the behavior of +character classes within regular expressions. +.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 . +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +If the +.BR \-l +option is in effect, the following shall be written for each file +containing at least one selected input line: +.sp +.RS 4 +.nf + +"%s\en", <\fIfile\fR> +.fi +.P +.RE +.P +Otherwise, if more than one +.IR file +argument appears, and +.BR \-q +is not specified, the +.IR grep +utility shall prefix each output line by: +.sp +.RS 4 +.nf + +"%s:", <\fIfile\fR> +.fi +.P +.RE +.P +The remainder of each output line shall depend on the other options +specified: +.IP " *" 4 +If the +.BR \-c +option is in effect, the remainder of each output line shall contain: +.RS 4 +.sp +.RS 4 +.nf + +"%d\en", <\fIcount\fR> +.fi +.P +.RE +.RE +.IP " *" 4 +Otherwise, if +.BR \-c +is not in effect and the +.BR \-n +option is in effect, the following shall be written to standard +output: +.RS 4 +.sp +.RS 4 +.nf + +"%d:", <\fIline number\fR> +.fi +.P +.RE +.RE +.IP " *" 4 +Finally, the following shall be written to standard output: +.RS 4 +.sp +.RS 4 +.nf + +"%s", <\fIselected-line contents\fR> +.fi +.P +.RE +.RE +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +The following exit values shall be returned: +.IP "\00" 6 +One or more lines were selected. +.IP "\01" 6 +No lines were selected. +.IP >1 6 +An error occurred. +.SH "CONSEQUENCES OF ERRORS" +If the +.BR \-q +option is specified, the exit status shall be zero if an input line is +selected, even if an error was detected. Otherwise, default actions +shall be performed. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Care should be taken when using characters in +.IR pattern_list +that may also be meaningful to the command interpreter. It is safest +to enclose the entire +.IR pattern_list +argument in single-quotes: +.sp +.RS 4 +.nf + +\&\(aq...\(aq +.fi +.P +.RE +.P +The +.BR \-e +.IR pattern_list +option has the same effect as the +.IR pattern_list +operand, but is useful when +.IR pattern_list +begins with the +<hyphen-minus> +delimiter. It is also useful when it is more convenient to provide +multiple patterns as separate arguments. +.P +Multiple +.BR \-e +and +.BR \-f +options are accepted and +.IR grep +uses all of the patterns it is given while matching input text lines. +(Note that the order of evaluation is not specified. If an +implementation finds a null string as a pattern, it is allowed to use +that pattern first, matching every line, and effectively ignore any +other patterns.) +.P +The +.BR \-q +option provides a means of easily determining whether or not a pattern +(or string) exists in a group of files. When searching several files, +it provides a performance improvement (because it can quit as soon as +it finds the first match) and requires less care by the user in +choosing the set of files to supply as arguments (because it exits zero +if it finds a match even if +.IR grep +detected an access or read error on earlier +.IR file +operands). +.P +When using +.IR grep +to process pathnames, it is recommended that LC_ALL, or at least +LC_CTYPE and LC_COLLATE, are set to POSIX or C in the environment, +since pathnames can contain byte sequences that do not form valid +characters in some locales, in which case the utility's behavior would +be undefined. In the POSIX locale each byte is a valid single-byte +character, and therefore this problem is avoided. +.SH EXAMPLES +.IP " 1." 4 +To find all uses of the word +.BR \(dqPosix\(dq +(in any case) in file +.BR text.mm +and write with line numbers: +.RS 4 +.sp +.RS 4 +.nf + +grep -i -n posix text.mm +.fi +.P +.RE +.RE +.IP " 2." 4 +To find all empty lines in the standard input: +.RS 4 +.sp +.RS 4 +.nf + +grep \(ha$ +.fi +.P +.RE +.P +or: +.sp +.RS 4 +.nf + +grep -v . +.fi +.P +.RE +.RE +.IP " 3." 4 +Both of the following commands print all lines containing strings +.BR \(dqabc\(dq +or +.BR \(dqdef\(dq +or both: +.RS 4 +.sp +.RS 4 +.nf + +grep -E \(aqabc|def\(aq +.P +grep -F \(aqabc +def\(aq +.fi +.P +.RE +.RE +.IP " 4." 4 +Both of the following commands print all lines matching exactly +.BR \(dqabc\(dq +or +.BR \(dqdef\(dq : +.RS 4 +.sp +.RS 4 +.nf + +grep -E \(aq\(haabc$|\(hadef$\(aq +.P +grep -F -x \(aqabc +def\(aq +.fi +.P +.RE +.RE +.SH RATIONALE +This +.IR grep +has been enhanced in an upwards-compatible way to provide the exact +functionality of the historical +.IR egrep +and +.IR fgrep +commands as well. It was the clear intention of the standard +developers to consolidate the three +.IR grep s +into a single command. +.P +The old +.IR egrep +and +.IR fgrep +commands are likely to be supported for many years to come as +implementation extensions, allowing historical applications to operate +unmodified. +.P +Historical implementations usually silently ignored all but one of +multiply-specified +.BR \-e +and +.BR \-f +options, but were not consistent as to which specification was actually +used. +.P +The +.BR \-b +option was omitted from the OPTIONS section because block numbers are +implementation-defined. +.P +The System V restriction on using +.BR \- +to mean standard input was omitted. +.P +A definition of action taken when given a null BRE or ERE is specified. +This is an error condition in some historical implementations. +.P +The +.BR \-l +option previously indicated that its use was undefined when no files +were explicitly named. This behavior was historical and placed an +unnecessary restriction on future implementations. It has been +removed. +.P +The historical BSD +.IR grep +.BR \-s +option practice is easily duplicated by redirecting standard output to +.BR /dev/null . +The +.BR \-s +option required here is from System V. +.P +The +.BR \-x +option, historically available only with +.IR fgrep , +is available here for all of the non-obsolescent versions. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "\fIsed\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Chapter 8" ", " "Environment Variables", +.IR "Chapter 9" ", " "Regular Expressions", +.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 . |