[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Changes to grep/doc/grep.texi,v
|
From: |
Bernhard Rosenkraenzer |
|
Subject: |
Changes to grep/doc/grep.texi,v |
|
Date: |
Fri, 18 Aug 2006 21:27:05 -0000 |
CVSROOT: /sources/grep
Module name: grep
Changes by: Bernhard Rosenkraenzer <bero> 06/08/18 21:26:54
Index: grep.texi
===================================================================
RCS file: /sources/grep/grep/doc/grep.texi,v
retrieving revision 1.59
retrieving revision 1.60
diff -u -b -r1.59 -r1.60
--- grep.texi 9 Nov 2005 20:04:41 -0000 1.59
+++ grep.texi 18 Aug 2006 21:26:54 -0000 1.60
@@ -32,11 +32,11 @@
Published by the Free Software Foundation,
-51 Franklin Street - Fifth Floor
-Boston, MA 02110-1301, USA
+51 Franklin Street -- Fifth Floor
+Boston, MA 02110--1301, USA
@c man begin COPYRIGHT
-Copyright @copyright{} 2000, 2001 Free Software Foundation, Inc.
+Copyright @copyright{} 1999, 2000, 2001, 2002, 2005 Free Software Foundation,
Inc.
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
@@ -62,18 +62,18 @@
@setchapternewpage off
@titlepage
address@hidden grep, searching for a pattern
address@hidden @command{grep}, print lines matching a pattern
@subtitle version @value{VERSION}, @value{UPDATED}
@author Alain Magloire et al.
@page
@vskip 0pt plus 1filll
-Copyright @copyright{} 2000, 2001 Free Software Foundation, Inc.
+Copyright @copyright{} 1999, 2000, 2001, 2002, 2005 Free Software Foundation,
Inc.
@sp 2
Published by the Free Software Foundation, @*
-51 Franklin Street - Fifth Floor, @*
-Boston, MA 02110-1301, USA
+51 Franklin Street -- Fifth Floor, @*
+Boston, MA 02110--1301, USA
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
@@ -89,24 +89,24 @@
@node Top
@top grep
-The @command{grep} command searches for lines matching a pattern.
address@hidden searches for lines matching a pattern.
-This document was produced for version @value{VERSION} of @sc{gnu}
address@hidden
+This document was produced
+for version @value{VERSION}
+of @sc{gnu} @command{grep}.
@end ifnottex
@menu
* Introduction:: Introduction.
* Invoking:: Invoking @command{grep}; description of
options.
-* Diagnostics:: Exit status returned by @command{grep}.
+* Exit Status:: Exit status returned by @command{grep}.
* grep Programs:: @command{grep} programs.
* Regular Expressions:: Regular Expressions.
* Usage:: Examples.
* Reporting Bugs:: Reporting Bugs.
* Copying:: License terms.
-* Concept Index:: A menu with all the topics in this manual.
-* Index:: A menu with all @command{grep} commands
- and command-line options.
+* Concept Index:: Topics covered in this manual.
+* Index:: Options, environment variables, and constructs.
@end menu
@@ -115,83 +115,264 @@
@cindex Searching for a pattern.
-The @command{grep} command searches the input files
-for lines containing a match to a given
-pattern list. When it finds a match in a line, it copies the line to standard
-output (by default), or does whatever other sort of output you have requested
-with options.
address@hidden searches the input files
+for lines containing a match to a given pattern list.
+When it finds a match in a line,
+it copies the line to standard output (by default),
+or does whatever other sort of output you have requested with options.
Though @command{grep} expects to do the matching on text,
it has no limits on input line length other than available memory,
and it can match arbitrary characters within a line.
If the final byte of an input file is not a newline,
@command{grep} silently supplies one.
-Since newline is also a separator for the list of patterns, there
-is no way to match newline characters in a text.
+Since newline is also a separator for the list of patterns,
+there is no way to match newline characters in a text.
@node Invoking
@chapter Invoking @command{grep}
address@hidden comes with a rich set of options from @sc{posix.2} and @sc{gnu}
-extensions.
+The general synopsis of a @command{grep} command line is
+
address@hidden
+grep @var{options} @var{pattern} @var{input_file_names}
address@hidden example
+
address@hidden
+There can be zero or more @var{options}.
address@hidden will only be seen as such
+(and not as an @var{input_file_name})
+if it wasn't already specified within @var{options}
+(by using the @samp{-e@ @var{pattern}}
+or @samp{-f@ @var{file}} options).
+and there can be zero or more @var{input_file_names}.
+
address@hidden
+* Command-line Options:: Short and long names, grouped by category.
+* Environment Variables:: POSIX, GNU generic, and GNU grep specific.
address@hidden menu
+
address@hidden Command-line Options
address@hidden Command-line Options
+
address@hidden comes with a rich set of options:
+some from @sc{posix.2} and some being @sc{gnu} extensions.
+Long option names are always a @sc{gnu} extension,
+even for options that are from @sc{posix} specifications.
+Options that are specified by @sc{posix},
+under their short names,
+are explicitly marked as such
+to facilitate @sc{posix}-portable programming.
+A few option names are provided
+for compatibility with older or more exotic implementations.
+
address@hidden
+* Generic Program Information::
+* Matching Control::
+* General Output Control::
+* Output Line Prefix Control::
+* Context Line Control::
+* File and Directory Selection::
+* Other Options::
address@hidden menu
+
+Several additional options control
+which variant of the @command{grep} matching engine is used.
address@hidden Programs}.
+
address@hidden Generic Program Information
address@hidden Generic Program Information
@table @samp
address@hidden -c
address@hidden --count
address@hidden -c
address@hidden --count
address@hidden counting lines
-Suppress normal output; instead print a count of matching
-lines for each input file. With the @samp{-v}, @samp{--invert-match} option,
-count non-matching lines.
address@hidden --help
address@hidden --help
address@hidden Usage summary, printing
+Print a usage message briefly summarizing these command-line options
+and the bug-reporting address, then exit.
+
address@hidden -V
address@hidden --version
address@hidden -V
address@hidden --version
address@hidden Version, printing
+Print the version number of @command{grep} to the standard output stream.
+This version number should be included in all bug reports.
+
address@hidden table
+
address@hidden Matching Control
address@hidden Matching Control
+
address@hidden @samp
@item -e @var{pattern}
@itemx address@hidden
@opindex -e
@opindex address@hidden
@cindex pattern list
-Use @var{pattern} as the pattern; useful to protect patterns
-beginning with a @samp{-}.
+Use @var{pattern} as the pattern;
+useful to protect patterns beginning with a @samp{-}.
+(@samp{-e} is specified by @sc{posix}.)
@item -f @var{file}
@itemx address@hidden
@opindex -f
@opindex --file
@cindex pattern from file
-Obtain patterns from @var{file}, one per line. The empty
-file contains zero patterns, and therefore matches nothing.
+Obtain patterns from @var{file}, one per line.
+The empty file contains zero patterns, and therefore matches nothing.
+(@samp{-f} is specified by @sc{posix}.)
@item -i
address@hidden -y
@itemx --ignore-case
@opindex -i
address@hidden -y
@opindex --ignore-case
@cindex case insensitive search
Ignore case distinctions in both the pattern and the input files.
address@hidden is an obsolete synonym that is provided for compatibility.
+(@samp{-i} is specified by @sc{posix}.)
+
address@hidden -v
address@hidden --invert-match
address@hidden -v
address@hidden --invert-match
address@hidden invert matching
address@hidden print non-matching lines
+Invert the sense of matching, to select non-matching lines.
+(@samp{-v} is specified by @sc{posix}.)
+
address@hidden -w
address@hidden --word-regexp
address@hidden -w
address@hidden --word-regexp
address@hidden matching whole words
+Select only those lines containing matches that form whole words.
+The test is that the matching substring must either
+be at the beginning of the line,
+or preceded by a non-word constituent character.
+Similarly,
+it must be either at the end of the line
+or followed by a non-word constituent character.
+Word-constituent characters are letters, digits, and the underscore.
+
address@hidden -x
address@hidden --line-regexp
address@hidden -x
address@hidden --line-regexp
address@hidden match the whole line
+Select only those matches that exactly match the whole line.
+(@samp{-x} is specified by @sc{posix}.)
+
address@hidden table
+
address@hidden General Output Control
address@hidden General Output Control
+
address@hidden @samp
+
address@hidden -c
address@hidden --count
address@hidden -c
address@hidden --count
address@hidden counting lines
+Suppress normal output;
+instead print a count of matching lines for each input file.
+With the @samp{-v}, @samp{--invert-match} option,
+count non-matching lines.
+(@samp{-c} is specified by @sc{posix}.)
+
address@hidden address@hidden
address@hidden address@hidden
address@hidden --color
address@hidden --colour
address@hidden highlight, color, colour
+Surround the matched (non-empty) strings, matching lines, context lines,
+file names, line numbers, byte offsets, and separators (for fields and
+groups of context lines) with escape sequences to display them in color
+on the terminal.
+The colors are defined by the environment variable @var{GREP_COLORS}
+and default to @samp{ms=01;31:mc=01;31:sl=:cx=:fn=35:ln=32:bn=32:se=36}
+for bold red matched text, magenta file names, green line numbers,
+green byte offsets, cyan separators, and default terminal colors otherwise.
+The deprecated environment variable @var{GREP_COLOR} is still supported,
+but its setting does not have priority;
+it defaults to `01;31' (bold red)
+which only covers the color for matched text.
address@hidden is @samp{never}, @samp{always}, or @samp{auto}.
+
address@hidden -L
address@hidden --files-without-match
address@hidden -L
address@hidden --files-without-match
address@hidden files which don't match
+Suppress normal output;
+instead print the name of each input file from which
+no output would normally have been printed.
+The scanning of every file will stop on the first match.
@item -l
@itemx --files-with-matches
@opindex -l
@opindex --files-with-matches
@cindex names of matching files
-Suppress normal output; instead print the name of each input
-file from which output would normally have been printed.
+Suppress normal output;
+instead print the name of each input file from which
+output would normally have been printed.
The scanning of every file will stop on the first match.
+(@samp{-l} is specified by @sc{posix}.)
address@hidden -n
address@hidden --line-number
address@hidden -n
address@hidden --line-number
address@hidden line numbering
-Prefix each line of output with the line number within its input file.
address@hidden -m @var{num}
address@hidden address@hidden
address@hidden -m
address@hidden --max-count
address@hidden max-count
+Stop reading a file after @var{num} matching lines.
+If the input is standard input from a regular file,
+and @var{num} matching lines are output,
address@hidden ensures that the standard input is positioned
+just after the last matching line before exiting,
+regardless of the presence of trailing context lines.
+This enables a calling process to resume a search.
+For example, the following shell script makes use of it:
+
address@hidden
+while grep -m 1 PATTERN
+do
+ echo xxxx
+done < FILE
address@hidden example
+
+But the following probably will not work because a pipe is not a regular
+file:
+
address@hidden
+# This probably will not work.
+cat FILE |
+while grep -m 1 PATTERN
+do
+ echo xxxx
+done
address@hidden example
+
+When @command{grep} stops after @var{num} matching lines,
+it outputs any trailing context lines.
+Since context does not include matching lines,
address@hidden will stop when it encounters another matching line.
+When the @samp{-c} or @samp{--count} option is also used,
address@hidden does not output a count greater than @var{num}.
+When the @samp{-v} or @samp{--invert-match} option is also used,
address@hidden stops after outputting @var{num} non-matching lines.
@item -o
@itemx --only-matching
@opindex -o
@opindex --only-matching
@cindex only matching
-Print only the non-empty parts of matching lines
-that actually match @var{pattern}.
+Print only the matched (non-empty) parts of matching lines,
+with each such part on a separate output line.
@item -q
@itemx --quiet
@@ -200,9 +381,11 @@
@opindex --quiet
@opindex --silent
@cindex quiet, silent
-Quiet; do not write anything to standard output. Exit immediately with
-zero status if any match is found, even if an error was detected. Also
-see the @samp{-s} or @samp{--no-messages} option.
+Quiet; do not write anything to standard output.
+Exit immediately with zero status if any match is found,
+even if an error was detected.
+Also see the @samp{-s} or @samp{--no-messages} option.
+(@samp{-q} is specified by @sc{posix}.)
@item -s
@itemx --no-messages
@@ -210,33 +393,136 @@
@opindex --no-messages
@cindex suppress error messages
Suppress error messages about nonexistent or unreadable files.
-Portability note: unlike @sc{gnu} @command{grep}, 7th Edition Unix
address@hidden did not conform to @sc{posix}, because it
-lacked @samp{-q} and its @samp{-s} option behaved like @sc{gnu}
address@hidden's @samp{-q} option. @sc{usg}-style @command{grep}
-also lacked @samp{-q} but its @samp{-s} option behaved like
address@hidden @command{grep}. Portable shell scripts should avoid both
+Portability note:
+unlike @sc{gnu} @command{grep},
+7th Edition Unix @command{grep} did not conform to @sc{posix},
+because it lacked @samp{-q}
+and its @samp{-s} option behaved like
address@hidden @command{grep}'s @samp{-q} option.
address@hidden @command{grep} also lacked @samp{-q}
+but its @samp{-s} option behaved like @sc{gnu} @command{grep}.
+Portable shell scripts should avoid both
@samp{-q} and @samp{-s} and should redirect
standard and error output to @file{/dev/null} instead.
+(@samp{-s} is specified by @sc{posix}.)
address@hidden -v
address@hidden --invert-match
address@hidden -v
address@hidden --invert-match
address@hidden invert matching
address@hidden print non-matching lines
-Invert the sense of matching, to select non-matching lines.
address@hidden table
address@hidden -x
address@hidden --line-regexp
address@hidden -x
address@hidden --line-regexp
address@hidden match the whole line
-Select only those matches that exactly match the whole line.
address@hidden Output Line Prefix Control
address@hidden Output Line Prefix Control
+
+When several prefix fields are to be output,
+the order is always file name, line number, and byte offset,
+regardless of the order in which these options were specified.
+
address@hidden @samp
+
address@hidden -b
address@hidden --byte-offset
address@hidden -b
address@hidden --byte-offset
address@hidden byte offset
+Print the 0-based byte offset within the input file
+before each line of output.
+If @samp{-o} (@samp{--only-matching}) is specified,
+print the offset of the matching part itself.
+When @command{grep} runs on @sc{ms-dos} or @sc{ms}-Windows,
+the printed byte offsets depend on whether
+the @samp{-u} (@samp{--unix-byte-offsets}) option is used;
+see below.
+
address@hidden -H
address@hidden --with-filename
address@hidden -H
address@hidden --with-filename
address@hidden with filename prefix
+Print the file name for each match.
+This is the default when there is more than one file to search.
+
address@hidden -h
address@hidden --no-filename
address@hidden -h
address@hidden --no-filename
address@hidden no filename prefix
+Suppress the prefixing of file names on output.
+This is the default when there is only one file
+(or only standard input) to search.
+
address@hidden address@hidden
address@hidden --label
address@hidden changing name of standard input
+Display input actually coming from standard input
+as input coming from file @var{LABEL}.
+This is especially useful for tools like @command{zgrep};
+e.g.:
+
address@hidden
+gzip -cd foo.gz | grep --label=foo something
address@hidden example
+
address@hidden -n
address@hidden --line-number
address@hidden -n
address@hidden --line-number
address@hidden line numbering
+Prefix each line of output with the 1-based line number within its input file.
+(@samp{-n} is specified by @sc{posix}.)
+
address@hidden -T
address@hidden --initial-tab
address@hidden -T
address@hidden --initial-tab
address@hidden tab-aligned content lines
+Make sure that the first character of actual line content lies on a tab stop,
+so that the alignment of tabs looks normal.
+This is useful with options that prefix their output to the actual content:
address@hidden, @samp{-n}, and @samp{-b}.
+In order to improve the probability that lines
+from a single file will all start at the same column,
+this also causes the line number and byte offset (if present)
+to be printed in a minimum size field width.
+
address@hidden -u
address@hidden --unix-byte-offsets
address@hidden -u
address@hidden --unix-byte-offsets
address@hidden @sc{ms-dos}/@sc{ms}-Windows byte offsets
address@hidden byte offsets, on @sc{ms-dos}/@sc{ms}-Windows
+Report Unix-style byte offsets.
+This option causes @command{grep} to report byte offsets
+as if the file were a Unix-style text file,
+i.e., the byte offsets ignore the @code{CR} characters that were stripped.
+This will produce results identical
+to running @command{grep} on a Unix machine.
+This option has no effect unless @samp{-b} option is also used;
+it has no effect on platforms other than @sc{ms-dos} and @sc{ms}-Windows.
+
address@hidden -Z
address@hidden --null
address@hidden -Z
address@hidden --null
address@hidden zero-terminated file names
+Output a zero byte (the @sc{ascii} @code{NUL} character)
+instead of the character that normally follows a file name.
+For example,
address@hidden -lZ} outputs a zero byte after each file name
+instead of the usual newline.
+This option makes the output unambiguous,
+even in the presence of file names containing unusual characters like newlines.
+This option can be used with commands like
address@hidden -print0}, @samp{perl -0}, @samp{sort -z}, and @samp{xargs -0}
+to process arbitrary file names,
+even those that contain newline characters.
@end table
address@hidden @sc{gnu} Extensions
address@hidden Context Line Control
address@hidden Context Line Control
+
+Regardless of how these options are set,
address@hidden will never print any given line more than once.
+If the @samp{-o} or @samp{--only-matching} option is specified,
+these options have no effect and a warning is given upon their use.
@table @samp
@@ -257,86 +543,75 @@
Print @var{num} lines of leading context before matching lines.
@item -C @var{num}
address@hidden address@hidden
@itemx address@hidden
@opindex -C
@opindex --context
address@hidden address@hidden
@cindex context
-Print @var{num} lines of output context.
+Print @var{num} lines of leading and trailing output context.
address@hidden address@hidden
address@hidden address@hidden
address@hidden --color
address@hidden --colour
address@hidden highlight, color, colour
-Surround the matching non-empty strings, matching lines, context lines,
-file names, line numbers, octet offsets, and separators (for fields and
-groups of context lines) with escape sequences to display them in color
-on the terminal.
-The colors are defined by the environment variable @var{GREP_COLORS}
-and default to `mt=01;31:ml=:cx=:fn=35:ln=32:bn=32:se=36' for bold red
-matched text, magenta file names, green line numbers, green octet offsets,
-cyan separators, and default terminal colors otherwise.
-The deprecated environment variable @var{GREP_COLOR} is still supported,
-but its setting does not have priority; it defaults to `01;31' (bold red)
-which only covers the color for matched text.
address@hidden is `never', `always', or `auto'.
address@hidden table
address@hidden address@hidden
address@hidden -NUM
-Same as @address@hidden lines of leading and trailing
-context. However, grep will never print any given line more than once.
+Matching lines normally use @samp{:} as a separator
+between prefix fields and actual line content.
+Context (i.e., non-matching) lines use @samp{-} instead.
+When no context is specified,
+matching lines are simply output one right after another.
+When nonzero context is specified,
+lines that are adjacent in the input form a group
+and are output one right after another,
+but disjoint groups of lines are separated by a @samp{--}
+without any prefix and on a line of its own.
+Each group may contain several matching lines
+when they are close enough to each other
+that two otherwise adjacent but divided groups connect
+and can just merge into a single contiguous one.
address@hidden -V
address@hidden --version
address@hidden -V
address@hidden --version
address@hidden Version, printing
-Print the version number of @command{grep} to the standard output stream.
-This version number should be included in all bug reports.
address@hidden File and Directory Selection
address@hidden File and Directory Selection
address@hidden --help
address@hidden --help
address@hidden Usage summary, printing
-Print a usage message briefly summarizing these command-line options
-and the bug-reporting address, then exit.
address@hidden @samp
+
address@hidden -a
address@hidden --text
address@hidden -a
address@hidden --text
address@hidden suppress binary data
address@hidden binary files
+Process a binary file as if it were text;
+this is equivalent to the @samp{--binary-files=text} option.
@itemx address@hidden
@opindex --binary-files
@cindex binary files
-If the first few bytes of a file indicate that the file contains binary
-data, assume that the file is of type @var{type}. By default,
address@hidden is @samp{binary}, and @command{grep} normally outputs either
-a one-line message saying that a binary file matches, or no message if
-there is no match. If @var{type} is @samp{without-match},
+If the first few bytes of a file indicate that the file contains binary data,
+assume that the file is of type @var{type}.
+By default, @var{type} is @samp{binary},
+and @command{grep} normally outputs either
+a one-line message saying that a binary file matches,
+or no message if there is no match.
+If @var{type} is @samp{without-match},
@command{grep} assumes that a binary file does not match;
-this is equivalent to the @samp{-I} option. If @var{type}
-is @samp{text}, @command{grep} processes a binary file as if it were
-text; this is equivalent to the @samp{-a} option.
+this is equivalent to the @samp{-I} option.
+If @var{type} is @samp{text},
address@hidden processes a binary file as if it were text;
+this is equivalent to the @samp{-a} option.
@emph{Warning:} @samp{--binary-files=text} might output binary garbage,
-which can have nasty side effects if the output is a terminal and if the
-terminal driver interprets some of it as commands.
-
address@hidden -b
address@hidden --byte-offset
address@hidden -b
address@hidden --byte-offset
address@hidden byte offset
-Print the byte offset within the input file before each line of output.
-When @command{grep} runs on @sc{ms-dos} or MS-Windows, the printed
-byte offsets
-depend on whether the @samp{-u} (@samp{--unix-byte-offsets}) option is
-used; see below.
+which can have nasty side effects
+if the output is a terminal and
+if the terminal driver interprets some of it as commands.
@item -D @var{action}
@itemx address@hidden
@opindex -D
@opindex --devices
@cindex device search
-If an input file is a device, FIFO or socket, use @var{action} to process it.
-By default, @var{action} is @samp{read}, which means that devices are
-read just as if they were ordinary files.
-If @var{action} is @samp{skip}, devices, FIFOs and sockets are silently
-skipped.
+If an input file is a device, FIFO, or socket, use @var{action} to process it.
+By default, @var{action} is @samp{read},
+which means that devices are read just as if they were ordinary files.
+If @var{action} is @samp{skip},
+devices, FIFOs, and sockets are silently skipped.
@item -d @var{action}
@itemx address@hidden
@@ -344,74 +619,44 @@
@opindex --directories
@cindex directory search
If an input file is a directory, use @var{action} to process it.
-By default, @var{action} is @samp{read}, which means that directories are
-read just as if they were ordinary files (some operating systems
-and filesystems disallow this, and will cause @command{grep} to print error
-messages for every directory or silently skip them). If @var{action} is
address@hidden, directories are silently skipped. If @var{action} is
address@hidden, @command{grep} reads all files under each directory,
-recursively; this is equivalent to the @samp{-r} option.
+By default, @var{action} is @samp{read},
+which means that directories are read just as if they were ordinary files
+(some operating systems and file systems disallow this,
+and will cause @command{grep}
+to print error messages for every directory or silently skip them).
+If @var{action} is @samp{skip}, directories are silently skipped.
+If @var{action} is @samp{recurse},
address@hidden reads all files under each directory, recursively;
+this is equivalent to the @samp{-r} option.
address@hidden -H
address@hidden --with-filename
address@hidden -H
address@hidden --With-filename
address@hidden with filename prefix
-Print the filename for each match.
-
address@hidden -h
address@hidden --no-filename
address@hidden -h
address@hidden --no-filename
address@hidden no filename prefix
-Suppress the prefixing of filenames on output when multiple files are searched.
-
address@hidden --line-buffered
address@hidden --line-buffered
address@hidden line buffering
-Set the line buffering policy, this can be a performance penalty.
-
address@hidden address@hidden
address@hidden --label
address@hidden changing name of standard input
-Display input actually coming from standard input as input coming from file
address@hidden This is especially useful for tools like @command{zgrep}, e.g.,
address@hidden -cd foo.gz | grep --label=foo something}
-
address@hidden -L
address@hidden --files-without-match
address@hidden -L
address@hidden --files-without-match
address@hidden files which don't match
-Suppress normal output; instead print the name of each input
-file from which no output would normally have been printed.
-The scanning of every file will stop on the first match.
address@hidden address@hidden
address@hidden --exclude
address@hidden exclude files
address@hidden searching directory trees
+Skip files whose base name matches @var{glob}
+(using wildcard matching).
+A file-name glob can use
address@hidden, @samp{?}, and @address@hidden as wildcards,
+and @code{\} to quote a wildcard or backslash character literally.
address@hidden -a
address@hidden --text
address@hidden -a
address@hidden --text
address@hidden suppress binary data
address@hidden binary files
-Process a binary file as if it were text; this is equivalent to the
address@hidden option.
address@hidden address@hidden
address@hidden --exclude-from
address@hidden exclude files
address@hidden searching directory trees
+Skip files @emph{and directories} whose base name matches
+any of the file-name globs read from @var{file}
+(using wildcard matching as described under @samp{--exclude}).
@item -I
-Process a binary file as if it did not contain matching data; this is
-equivalent to the @samp{--binary-files=without-match} option.
+Process a binary file as if it did not contain matching data;
+this is equivalent to the @samp{--binary-files=without-match} option.
address@hidden -w
address@hidden --word-regexp
address@hidden -w
address@hidden --word-regexp
address@hidden matching whole words
-Select only those lines containing matches that form
-whole words. The test is that the matching substring
-must either be at the beginning of the line, or preceded
-by a non-word constituent character. Similarly,
-it must be either at the end of the line or followed by
-a non-word constituent character. Word-constituent
-characters are letters, digits, and the underscore.
address@hidden address@hidden
address@hidden --include
address@hidden include files
address@hidden searching directory trees
+Search only files whose base name matches @var{glob}
+(using wildcard matching as described under @samp{--exclude}).
@item -r
@itemx -R
@@ -420,139 +665,52 @@
@opindex --recursive
@cindex recursive search
@cindex searching directory trees
-For each directory mentioned in the command line, read and process all
-files in that directory, recursively. This is the same as the
address@hidden option.
+For each directory mentioned in the command line,
+read and process all files in that directory, recursively.
+This is the same as the @samp{--directories=recurse} option.
address@hidden address@hidden
address@hidden --include
address@hidden include files
address@hidden searching directory trees
-Search only files matching @var{file_pattern}.
-
address@hidden address@hidden
address@hidden --exclude
address@hidden exclude files
address@hidden searching directory trees
-Skip files @emph{and directories} matching @var{file_pattern}.
-
address@hidden -m @var{num}
address@hidden address@hidden
address@hidden -m
address@hidden --max-count
address@hidden max-count
-Stop reading a file after @var{num} matching lines. If the input is
-standard input from a regular file, and @var{num} matching lines are
-output, @command{grep} ensures that the standard input is positioned to
-just after the last matching line before exiting, regardless of the
-presence of trailing context lines. This enables a calling process
-to resume a search. For example, the following shell script makes use
-of it:
-
address@hidden
-while grep -m 1 PATTERN
-do
- echo xxxx
-done < FILE
address@hidden example
address@hidden table
-But the following probably will not work because a pipe is not a regular
-file:
address@hidden Other Options
address@hidden Other Options
address@hidden
-# This probably will not work.
-cat FILE |
-while grep -m 1 PATTERN
-do
- echo xxxx
-done
address@hidden example
address@hidden @samp
-When @command{grep} stops after NUM matching lines, it outputs
-any trailing context lines. Since context does not include matching
-lines, @command{grep} will stop when it encounters another matching line.
-When the @samp{-c} or @samp{--count} option is also used,
address@hidden does not output a count greater than @var{num}.
-When the @samp{-v} or @samp{--invert-match} option is
-also used, @command{grep} stops after outputting @var{num}
-non-matching lines.
address@hidden --line-buffered
address@hidden --line-buffered
address@hidden line buffering
+Use line buffering on output.
+This can cause a performance penalty.
address@hidden -y
address@hidden -y
address@hidden case insensitive search, obsolete option
-Obsolete synonym for @samp{-i}.
address@hidden --mmap
address@hidden --mmap
address@hidden memory mapped input
+If possible, use the @code{mmap} system call to read input,
+instead of the default @code{read} system call.
+In some situations, @samp{--mmap} yields better performance.
+However, @samp{--mmap} can cause undefined behavior (including core dumps)
+if an input file shrinks while @command{grep} is operating,
+or if an I/O error occurs.
@item -U
@itemx --binary
@opindex -U
@opindex --binary
address@hidden DOS/Windows binary files
address@hidden binary files, DOS/Windows
-Treat the file(s) as binary. By default, under @sc{ms-dos}
-and MS-Windows, @command{grep} guesses the file type by looking
-at the contents of the first 32kB read from the file.
-If @command{grep} decides the file is a text file, it strips the
address@hidden characters from the original file contents (to make
-regular expressions with @code{^} and @code{$} work correctly).
-Specifying @samp{-U} overrules this guesswork, causing all
-files to be read and passed to the matching mechanism
-verbatim; if the file is a text file with @code{CR/LF} pairs
-at the end of each line, this will cause some regular
-expressions to fail. This option has no effect on platforms other than
address@hidden and MS-Windows.
-
address@hidden -u
address@hidden --unix-byte-offsets
address@hidden -u
address@hidden --unix-byte-offsets
address@hidden DOS byte offsets
address@hidden byte offsets, on DOS/Windows
-Report Unix-style byte offsets. This switch causes
address@hidden to report byte offsets as if the file were Unix style
-text file, i.e., the byte offsets ignore the @code{CR} characters which were
-stripped. This will produce results identical to running @command{grep} on
-a Unix machine. This option has no effect unless @samp{-b}
-option is also used; it has no effect on platforms other than @sc{ms-dos} and
-MS-Windows.
-
address@hidden --mmap
address@hidden --mmap
address@hidden memory mapped input
-If possible, use the @code{mmap} system call to read input, instead of
-the default @code{read} system call. In some situations, @samp{--mmap}
-yields better performance. However, @samp{--mmap} can cause undefined
-behavior (including core dumps) if an input file shrinks while
address@hidden is operating, or if an I/O error occurs.
-
address@hidden -T
address@hidden --initial-tab
address@hidden -T
address@hidden --initial-tab
address@hidden tab-aligned content lines
-Makes sure that the first character of actual line content lies on a
-tab stop, so that the alignment of tabs looks normal.
-This is useful when combined with @samp{-H} (which is implicit when
-there is more than one file to search), @samp{-n}, and @samp{-b};
-these options prepend their output at the beginning of the displayed
-line, before the actual content.
-In order to improve the probability that all matched or context lines
-from a single file will all start at the same column, this also causes
-the line number and octet offset (if present) to be printed in a minimum
-size field width.
-
address@hidden -Z
address@hidden --null
address@hidden -Z
address@hidden --null
address@hidden zero-terminated file names
-Output a zero byte (the @sc{ascii} @code{NUL} character) instead of the
-character that normally follows a file name. For example, @samp{grep
--lZ} outputs a zero byte after each file name instead of the usual
-newline. This option makes the output unambiguous, even in the presence
-of file names containing unusual characters like newlines. This option
-can be used with commands like @samp{find -print0}, @samp{perl -0},
address@hidden -z}, and @samp{xargs -0} to process arbitrary file names,
-even those that contain newline characters.
address@hidden @sc{ms-dos}/@sc{ms}-Windows binary files
address@hidden binary files, @sc{ms-dos}/@sc{ms}-Windows
+Treat the file(s) as binary.
+By default, under @sc{ms-dos} and @sc{ms}-Windows,
address@hidden guesses the file type
+by looking at the contents of the first 32kB read from the file.
+If @command{grep} decides the file is a text file,
+it strips the @code{CR} characters from the original file contents
+(to make regular expressions with @code{^} and @code{$} work correctly).
+Specifying @samp{-U} overrules this guesswork,
+causing all files to be read and passed to the matching mechanism verbatim;
+if the file is a text file with @code{CR/LF} pairs at the end of each line,
+this will cause some regular expressions to fail.
+This option has no effect
+on platforms other than @sc{ms-dos} and @sc{ms}-Windows.
@item -z
@itemx --null-data
@@ -560,150 +718,272 @@
@opindex --null-data
@cindex zero-terminated lines
Treat the input as a set of lines, each terminated by a zero byte (the
address@hidden @code{NUL} character) instead of a newline. Like the @samp{-Z}
-or @samp{--null} option, this option can be used with commands like
address@hidden @code{NUL} character) instead of a newline.
+Like the @samp{-Z} or @samp{--null} option,
+this option can be used with commands like
@samp{sort -z} to process arbitrary file names.
@end table
-Several additional options control which variant of the @command{grep}
-matching engine is used. @xref{grep Programs}.
-
address@hidden Environment Variables
@section Environment Variables
The behavior of @command{grep} is affected
by the following environment variables.
-A locale @address@hidden is specified by examining the three
-environment variables @env{LC_ALL}, @address@hidden, and @env{LANG},
-in that order. The first of these variables that is set specifies the
-locale. For example, if @env{LC_ALL} is not set, but @env{LC_MESSAGES}
-is set to @samp{pt_BR}, then Brazilian Portuguese is used for the
address@hidden locale. The C locale is used if none of these
-environment variables are set, or if the locale catalog is not
-installed, or if @command{grep} was not compiled with national language
-support (@sc{nls}).
+The locale for category @address@hidden@var{foo}}}
+is specified by examining the three environment variables
address@hidden, @address@hidden@var{foo}}}, and @env{LANG},
+in that order.
+The first of these variables that is set specifies the locale.
+For example, if @env{LC_ALL} is not set,
+but @env{LC_MESSAGES} is set to @samp{pt_BR},
+then the Brazilian Portuguese locale is used
+for the @code{LC_MESSAGES} category.
+The @samp{C} locale is used if none of these environment variables are set,
+if the locale catalog is not installed,
+or if @command{grep} was not compiled
+with national language support (@sc{nls}).
@cindex environment variables
@table @env
@item GREP_OPTIONS
address@hidden GREP_OPTIONS
address@hidden GREP_OPTIONS @r{environment variable}
@cindex default options environment variable
This variable specifies default options to be placed in front of any
-explicit options. For example, if @code{GREP_OPTIONS} is
+explicit options.
+For example, if @code{GREP_OPTIONS} is
@samp{--binary-files=without-match --directories=skip}, @command{grep}
behaves as if the two options @samp{--binary-files=without-match} and
@samp{--directories=skip} had been specified before
-any explicit options. Option specifications are separated by
-whitespace. A backslash escapes the next character, so it can be used to
+any explicit options.
+Option specifications are separated by
+whitespace.
+A backslash escapes the next character, so it can be used to
specify an option containing whitespace or a backslash.
@item GREP_COLOR
address@hidden GREP_COLOR
address@hidden GREP_COLOR @r{environment variable}
@cindex highlight markers
-This variable is deprecated but still supported; its setting does not
-have priority over that of @code{GREP_COLORS}.
-It specifies the color used to highlight the matching non-empty text.
-The default is `01;31' which means bold red text on the default
-background.
+This variable specifies the color used to highlight matched (non-empty) text.
+It is deprecated in favor of @code{GREP_COLORS}, but still supported.
+The @samp{mt}, @samp{ms}, and @samp{mc} capabilities of @code{GREP_COLORS}
+have priority over it.
+It can only specify the color used to highlight
+the matching non-empty text in any matching line
+(a selected line when the @samp{-v} command-line option is omitted,
+or a context line when @samp{-v} is specified).
+The default is @samp{01;31},
+which means a bold red foreground text on the terminal's default background.
@item GREP_COLORS
address@hidden GREP_COLORS
address@hidden GREP_COLORS @r{environment variable}
@cindex highlight markers
-This variable specifies the colors used to highlight
-the matching non-empty text (mt), matching lines (ml), context lines (cx),
-file names (fn), line numbers (ln), octet offsets (bn),
-and separators (se, for fields and groups of context lines).
-It is a colon-separated list of color specification assignments.
-The default is `mt=01;31:ml=:cx=:fn=35:ln=32:bn=32:se=36' which means
-bold red, default, default, magenta, green, green, and cyan, all text
-foregrounds on the default background.
-Note that the `ml' setting, if any, remains in effect just before the
-`mt' setting kicks in.
-See the Select Graphic Rendition (SGR, for character attributes)
-section in the documentation of the text terminal that is used
-for permissible values (semicolon-separated lists of integers)
-and their meaning.
address@hidden also supports a boolean `ne' capability (with no
-`=...' part) to not clear to the end of line using Erase in Line (EL)
-to Right (`\33[K') each time a colorized item ends (needed on terminals
-on which EL is not supported; otherwise useful on terminals where the
address@hidden (@code{bce}) boolean terminfo capability is not
-specified, when the chosen highlight colors do not affect the background,
-or when EL is too slow to bother doing or causes too much flicker).
+This variable specifies the colors and other attributes
+used to highlight various parts of the output.
+Its value is a colon-separated list of capabilities
+that defaults to @samp{ms=01;31:mc=01;31:sl=:cx=:fn=35:ln=32:bn=32:se=36}
+with the @samp{rv} and @samp{ne} boolean capabilities omitted (i.e., false).
+Supported capabilities are as follows.
+
address@hidden @code
address@hidden sl=
address@hidden sl GREP_COLORS @r{capability}
+SGR substring for whole selected lines
+(i.e.,
+matching lines when the @samp{-v} command-line option is omitted,
+or non-matching lines when @samp{-v} is specified).
+If however the boolean @samp{rv} capability
+and the @samp{-v} command-line option are both specified,
+it applies to context matching lines instead.
+The default is empty (i.e., the terminal's default color pair).
+
address@hidden cx=
address@hidden cx GREP_COLORS @r{capability}
+SGR substring for whole context lines
+(i.e.,
+non-matching lines when the @samp{-v} command-line option is omitted,
+or matching lines when @samp{-v} is specified).
+If however the boolean @samp{rv} capability
+and the @samp{-v} command-line option are both specified,
+it applies to selected non-matching lines instead.
+The default is empty (i.e., the terminal's default color pair).
+
address@hidden rv
address@hidden rv GREP_COLORS @r{capability}
+Boolean value that reverses (swaps) the meanings of
+the @samp{sl=} and @samp{cx=} capabilities
+when the @samp{-v} command-line option is specified.
+The default is false (i.e., the capability is omitted).
+
address@hidden mt=01;31
address@hidden mt GREP_COLORS @r{capability}
+SGR substring for matching non-empty text in any matching line
+(i.e.,
+a selected line when the @samp{-v} command-line option is omitted,
+or a context line when @samp{-v} is specified).
+Setting this is equivalent to setting both @samp{ms=} and @samp{mc=}
+at once to the same value.
+The default is a bold red text foreground over the current line background.
+
address@hidden ms=01;31
address@hidden ms GREP_COLORS @r{capability}
+SGR substring for matching non-empty text in a selected line.
+(This is only used when the @samp{-v} command-line option is omitted.)
+The effect of the @samp{sl=} (or @samp{cx=} if @samp{rv}) capability
+remains active when this kicks in.
+The default is a bold red text foreground over the current line background.
+
address@hidden mc=01;31
address@hidden mc GREP_COLORS @r{capability}
+SGR substring for matching non-empty text in a context line.
+(This is only used when the @samp{-v} command-line option is specified.)
+The effect of the @samp{cx=} (or @samp{sl=} if @samp{rv}) capability
+remains active when this kicks in.
+The default is a bold red text foreground over the current line background.
+
address@hidden fn=35
address@hidden fn GREP_COLORS @r{capability}
+SGR substring for file names prefixing any content line.
+The default is a magenta text foreground over the terminal's default
background.
+
address@hidden ln=32
address@hidden ln GREP_COLORS @r{capability}
+SGR substring for line numbers prefixing any content line.
+The default is a green text foreground over the terminal's default background.
+
address@hidden bn=32
address@hidden bn GREP_COLORS @r{capability}
+SGR substring for byte offsets prefixing any content line.
+The default is a green text foreground over the terminal's default background.
+
address@hidden se=36
address@hidden fn GREP_COLORS @r{capability}
+SGR substring for separators that are inserted
+between selected line fields (@samp{:}),
+between context line fields (@samp{-}),
+and between groups of adjacent lines
+when nonzero context is specified (@samp{--}).
+The default is a cyan text foreground over the terminal's default background.
+
address@hidden ne
address@hidden ne GREP_COLORS @r{capability}
+Boolean value that prevents clearing to the end of line
+using Erase in Line (EL) to Right (@samp{\33[K})
+each time a colorized item ends.
+This is needed on terminals on which EL is not supported.
+It is otherwise useful on terminals
+for which the @code{back_color_erase}
+(@code{bce}) boolean terminfo capability does not apply,
+when the chosen highlight colors do not affect the background,
+or when EL is too slow or causes too much flicker.
+The default is false (i.e., the capability is omitted).
address@hidden table
+
+Note that boolean capabilities have no @samp{=}... part.
+They are omitted (i.e., false) by default and become true when specified.
+
+See the Select Graphic Rendition (SGR) section
+in the documentation of the text terminal that is used
+for permitted values and their meaning as character attributes.
+These substring values are integers in decimal representation
+and can be concatenated with semicolons.
address@hidden takes care of assembling the result
+into a complete SGR sequence (@address@hidden).
+Common values to concatenate include
address@hidden for bold,
address@hidden for underline,
address@hidden for blink,
address@hidden for inverse,
address@hidden for default foreground color,
address@hidden to @samp{37} for foreground colors,
address@hidden to @samp{97} for 16-color mode foreground colors,
address@hidden;5;0} to @samp{38;5;255}
+for 88-color and 256-color modes foreground colors,
address@hidden for default background color,
address@hidden to @samp{47} for background colors,
address@hidden to @samp{107} for 16-color mode background colors,
+and @samp{48;5;0} to @samp{48;5;255}
+for 88-color and 256-color modes background colors.
@item LC_ALL
@itemx LC_COLLATE
@itemx LANG
address@hidden LC_ALL
address@hidden LC_COLLATE
address@hidden LANG
address@hidden LC_ALL @r{environment variable}
address@hidden LC_COLLATE @r{environment variable}
address@hidden LANG @r{environment variable}
@cindex character type
@cindex national language support
@cindex NLS
-These variables specify the @code{LC_COLLATE} locale, which determines
-the collating sequence used to interpret range expressions like
address@hidden
+These variables specify the locale for the @code{LC_COLLATE} category,
+which determines the collating sequence
+used to interpret range expressions like @samp{[a-z]}.
@item LC_ALL
@itemx LC_CTYPE
@itemx LANG
address@hidden LC_ALL
address@hidden LC_CTYPE
address@hidden LANG
address@hidden LC_ALL @r{environment variable}
address@hidden LC_CTYPE @r{environment variable}
address@hidden LANG @r{environment variable}
@cindex character type
@cindex national language support
@cindex NLS
-These variables specify the @code{LC_CTYPE} locale, which determines the
-type of characters, e.g., which characters are whitespace.
+These variables specify the locale for the @code{LC_CTYPE} category,
+which determines the type of characters,
+e.g., which characters are whitespace.
@item LC_ALL
@itemx LC_MESSAGES
@itemx LANG
address@hidden LC_ALL
address@hidden LC_MESSAGES
address@hidden LANG
address@hidden LC_ALL @r{environment variable}
address@hidden LC_MESSAGES @r{environment variable}
address@hidden LANG @r{environment variable}
@cindex language of messages
@cindex message language
@cindex national language support
@cindex NLS
@cindex translation of message language
-These variables specify the @code{LC_MESSAGES} locale, which determines
-the language that @command{grep} uses for messages. The default C
-locale uses American English messages.
+These variables specify the locale for the @code{LC_MESSAGES} category,
+which determines the language that @command{grep} uses for messages.
+The default @samp{C} locale uses American English messages.
@item POSIXLY_CORRECT
address@hidden POSIXLY_CORRECT
address@hidden POSIXLY_CORRECT @r{environment variable}
If set, @command{grep} behaves as @sc{posix.2} requires; otherwise,
address@hidden behaves more like other @sc{gnu} programs. @sc{posix.2}
address@hidden behaves more like other @sc{gnu} programs.
address@hidden
requires that options that
-follow file names must be treated as file names; by default, such
-options are permuted to the front of the operand list and are treated as
-options. Also, @sc{posix.2} requires that unrecognized options be
-diagnosed as
-``illegal'', but since they are not really against the law the default
-is to diagnose them as ``invalid''. @code{POSIXLY_CORRECT} also
-disables @address@hidden, described below.
+follow file names must be treated as file names;
+by default,
+such options are permuted to the front of the operand list
+and are treated as options.
+Also,
address@hidden requires that unrecognized options be diagnosed as ``illegal'',
+but since they are not really against the law the default
+is to diagnose them as ``invalid''.
address@hidden also disables @address@hidden,
+described below.
@item address@hidden
address@hidden address@hidden
-(Here @address@hidden is @command{grep}'s numeric process ID.) If the
address@hidden character of this environment variable's value is @samp{1}, do
-not consider the @var{i}th operand of @command{grep} to be an option, even if
-it appears to be one. A shell can put this variable in the environment
-for each command it runs, specifying which operands are the results of
-file name wildcard expansion and therefore should not be treated as
-options. This behavior is available only with the @sc{gnu} C library, and
-only when @code{POSIXLY_CORRECT} is not set.
address@hidden address@hidden @r{environment variable}
+(Here @address@hidden is @command{grep}'s numeric process ID.)
+If the @var{i}th character of this environment variable's value is @samp{1},
+do not consider the @var{i}th operand of @command{grep} to be an option,
+even if it appears to be one.
+A shell can put this variable in the environment for each command it runs,
+specifying which operands are the results of file name wildcard expansion
+and therefore should not be treated as options.
+This behavior is available only with the @sc{gnu} C library,
+and only when @code{POSIXLY_CORRECT} is not set.
@end table
address@hidden Diagnostics
address@hidden Diagnostics
address@hidden Exit Status
address@hidden Exit Status
-Normally, exit status is 0 if selected lines are found and 1 otherwise.
+Normally, the exit status is 0 if selected lines are found and 1 otherwise.
But the exit status is 2 if an error occurred, unless the @option{-q} or
@option{--quiet} or @option{--silent} option is used and a selected line
is found.
@@ -712,12 +992,12 @@
that the exit status in case of error be greater than 1;
it is therefore advisable, for the sake of portability,
to use logic that tests for this general condition
-instead of strict equality with 2.
+instead of strict equality with@ 2.
@node grep Programs
@chapter @command{grep} programs
-The @command{grep} command searches the named input files
address@hidden searches the named input files
(or standard input if no files are named,
or the file name @file{-} is given)
for lines containing a match to the given pattern.
@@ -732,14 +1012,16 @@
@opindex -G
@opindex --basic-regexp
@cindex matching basic regular expressions
-Interpret the pattern as a basic regular expression. This is the default.
+Interpret the pattern as a basic regular expression (BRE).
+This is the default.
@item -E
@itemx --extended-regexp
@opindex -E
@opindex --extended-regexp
@cindex matching extended regular expressions
-Interpret the pattern as an extended regular expression.
+Interpret the pattern as an extended regular expression (ERE).
+(@samp{-E} is specified by @sc{posix}.)
@item -F
@itemx --fixed-strings
@@ -748,6 +1030,7 @@
@cindex matching fixed strings
Interpret the pattern as a list of fixed strings, separated
by newlines, any of which is to be matched.
+(@samp{-F} is specified by @sc{posix}.)
@item -P
@itemx --perl-regexp
@@ -755,6 +1038,8 @@
@opindex --perl-regexp
@cindex matching Perl regular expressions
Interpret the pattern as a Perl regular expression.
+This is highly experimental and
address@hidden@ -P} may warn of unimplemented features.
@end table
@@ -774,16 +1059,32 @@
A @dfn{regular expression} is a pattern that describes a set of strings.
Regular expressions are constructed analogously to arithmetic expressions,
by using various operators to combine smaller expressions.
address@hidden understands two different versions of regular expression
-syntax: ``basic''(BRE) and ``extended''(ERE). In @sc{gnu} @command{grep},
address@hidden understands
+two different versions of regular expression syntax:
+``basic''(BRE) and ``extended''(ERE).
+In @sc{gnu} @command{grep},
there is no difference in available functionality using either syntax.
In other implementations, basic regular expressions are less powerful.
The following description applies to extended regular expressions;
differences for basic regular expressions are summarized afterwards.
address@hidden
+* Fundamental Structure::
+* Character Classes and Bracket Expressions::
+* The Backslash Character and Special Expressions::
+* Anchoring::
+* Back-references and Subexpressions::
+* Basic vs Extended::
address@hidden menu
+
address@hidden Fundamental Structure
address@hidden Fundamental Structure
+
The fundamental building blocks are the regular expressions that match
-a single character. Most characters, including all letters and digits,
-are regular expressions that match themselves. Any metacharacter
+a single character.
+Most characters, including all letters and digits,
+are regular expressions that match themselves.
+Any meta-character
with special meaning may be quoted by preceding it with a backslash.
A regular expression may be followed by one of several
@@ -800,153 +1101,173 @@
@item ?
@opindex ?
@cindex question mark
address@hidden match sub-expression at most once
address@hidden match expression at most once
The preceding item is optional and will be matched at most once.
@item *
@opindex *
@cindex asterisk
address@hidden match sub-expression zero or more times
address@hidden match expression zero or more times
The preceding item will be matched zero or more times.
@item +
@opindex +
@cindex plus sign
address@hidden match expression one or more times
The preceding item will be matched one or more times.
@item @address@hidden@}
address@hidden @address@hidden
address@hidden @address@hidden@}
@cindex braces, one argument
address@hidden match sub-expression n times
address@hidden match expression @var{n} times
The preceding item is matched exactly @var{n} times.
@item @address@hidden,@}
address@hidden @{n,@}
address@hidden @address@hidden,@}
@cindex braces, second argument omitted
address@hidden match sub-expression n or more times
-The preceding item is matched n or more times.
address@hidden match expression @var{n} or more times
+The preceding item is matched @var{n} or more times.
+
address@hidden @{,@address@hidden
address@hidden @{,@address@hidden
address@hidden braces, first argument omitted
address@hidden match expression at most @var{m} times
+The preceding item is matched at most @var{m} times.
@item @address@hidden,@address@hidden
address@hidden @{n,address@hidden
address@hidden @address@hidden,@address@hidden
@cindex braces, two arguments
address@hidden match expression from @var{n} to @var{m} times
The preceding item is matched at least @var{n} times, but not more than
@var{m} times.
@end table
-Two regular expressions may be concatenated; the resulting regular
-expression matches any string formed by concatenating two substrings
-that respectively match the concatenated subexpressions.
-
-Two regular expressions may be joined by the infix operator @samp{|}; the
-resulting regular expression matches any string matching either subexpression.
-
-Repetition takes precedence over concatenation, which in turn
-takes precedence over alternation. A whole subexpression may be
-enclosed in parentheses to override these precedence rules.
+Two regular expressions may be concatenated;
+the resulting regular expression
+matches any string formed by concatenating two substrings
+that respectively match the concatenated expressions.
+
+Two regular expressions may be joined by the infix operator @samp{|};
+the resulting regular expression
+matches any string matching either alternalte expression.
+
+Repetition takes precedence over concatenation,
+which in turn takes precedence over alternation.
+A whole expression may be enclosed in parentheses
+to override these precedence rules and form a subexpression.
address@hidden Character Class
address@hidden Character Classes and Bracket Expressions
address@hidden Character Classes and Bracket Expressions
@cindex bracket expression
@cindex character class
A @dfn{bracket expression} is a list of characters enclosed by @samp{[} and
address@hidden It matches any single character in that list; if the first
-character of the list is the caret @samp{^}, then it matches any character
address@hidden in the list. For example, the regular expression
address@hidden
+It matches any single character in that list;
+if the first character of the list is the caret @samp{^},
+then it matches any character @strong{not} in the list.
+For example, the regular expression
@samp{[0123456789]} matches any single digit.
@cindex range expression
Within a bracket expression, a @dfn{range expression} consists of two
-characters separated by a hyphen. It matches any single character that
+characters separated by a hyphen.
+It matches any single character that
sorts between the two characters, inclusive, using the locale's
-collating sequence and character set. For example, in the default C
-locale, @samp{[a-d]} is equivalent to @samp{[abcd]}. Many locales sort
+collating sequence and character set.
+For example, in the default C
+locale, @samp{[a-d]} is equivalent to @samp{[abcd]}.
+Many locales sort
characters in dictionary order, and in these locales @samp{[a-d]} is
-typically not equivalent to @samp{[abcd]}; it might be equivalent to
address@hidden, for example. To obtain the traditional interpretation
-of bracket expressions, you can use the C locale by setting the
+typically not equivalent to @samp{[abcd]};
+it might be equivalent to @samp{[aBbCcDd]}, for example.
+To obtain the traditional interpretation
+of bracket expressions, you can use the @samp{C} locale by setting the
@env{LC_ALL} environment variable to the value @samp{C}.
Finally, certain named classes of characters are predefined within
bracket expressions, as follows.
-Their interpretation depends on the @code{LC_CTYPE} locale; the
-interpretation below is that of the C locale, which is the default
-if no @code{LC_CTYPE} locale is specified.
+Their interpretation depends on the @code{LC_CTYPE} locale;
+the interpretation below is that of the @samp{C} locale,
+which is the default if no @code{LC_CTYPE} locale is specified.
@cindex classes of characters
@cindex character classes
@table @samp
@item [:alnum:]
address@hidden alnum
address@hidden alnum @r{character class}
@cindex alphanumeric characters
Alphanumeric characters:
@samp{[:alpha:]} and @samp{[:digit:]}.
@item [:alpha:]
address@hidden alpha
address@hidden alpha @r{character class}
@cindex alphabetic characters
Alphabetic characters:
@samp{[:lower:]} and @samp{[:upper:]}.
@item [:blank:]
address@hidden blank
address@hidden blank @r{character class}
@cindex blank characters
Blank characters:
space and tab.
@item [:cntrl:]
address@hidden cntrl
address@hidden cntrl @r{character class}
@cindex control characters
-Control characters. In @sc{ascii}, these characters have octal codes 000
-through 037, and 177 (@code{DEL}). In other character sets, these are
+Control characters.
+In @sc{ascii}, these characters have octal codes 000
+through 037, and 177 (@code{DEL}).
+In other character sets, these are
the equivalent characters, if any.
@item [:digit:]
address@hidden digit
address@hidden digit @r{character class}
@cindex digit characters
@cindex numeric characters
Digits: @code{0 1 2 3 4 5 6 7 8 9}.
@item [:graph:]
address@hidden graph
address@hidden graph @r{character class}
@cindex graphic characters
Graphical characters:
@samp{[:alnum:]} and @samp{[:punct:]}.
@item [:lower:]
address@hidden lower
address@hidden lower @r{character class}
@cindex lower-case letters
Lower-case letters:
@code{a b c d e f g h i j k l m n o p q r s t u v w x y z}.
@item [:print:]
address@hidden print
address@hidden print @r{character class}
@cindex printable characters
Printable characters:
@samp{[:alnum:]}, @samp{[:punct:]}, and space.
@item [:punct:]
address@hidden punct
address@hidden punct @r{character class}
@cindex punctuation characters
Punctuation characters:
@code{!@: " # $ % & ' ( ) * + , - .@: / : ; < = > ?@: @@ [ \ ] ^ _ ` @{ | @}
~}.
@item [:space:]
address@hidden space
address@hidden space @r{character class}
@cindex space characters
@cindex whitespace characters
Space characters:
tab, newline, vertical tab, form feed, carriage return, and space.
@item [:upper:]
address@hidden upper
address@hidden upper @r{character class}
@cindex upper-case letters
Upper-case letters:
@code{A B C D E F G H I J K L M N O P Q R S T U V W X Y Z}.
@item [:xdigit:]
address@hidden xdigit
address@hidden xdigit @r{character class}
@cindex xdigit class
@cindex hexadecimal digits
Hexadecimal digits:
@@ -954,18 +1275,19 @@
@end table
For example, @samp{[[:alnum:]]} means @samp{[0-9A-Za-z]}, except the latter
-depends upon the C locale and the @sc{ascii} character
+depends upon the @samp{C} locale and the @sc{ascii} character
encoding, whereas the former is independent of locale and character set.
(Note that the brackets in these class names are
part of the symbolic names, and must be included in addition to
-the brackets delimiting the bracket list.)
+the brackets delimiting the bracket expression.)
-Most metacharacters lose their special meaning inside lists.
+Most meta-characters lose their special meaning inside bracket expressions.
@table @samp
@item ]
-ends the list if it's not the first list item. So, if you want to make
-the @samp{]} character a list item, you must put it first.
+ends the bracket expression if it's not the first list item.
+So, if you want to make the @samp{]} character a list item,
+you must put it first.
@item [.
represents the open collating symbol.
@@ -990,16 +1312,19 @@
of a range.
@item ^
-represents the characters not in the list. If you want to make the @samp{^}
+represents the characters not in the list.
+If you want to make the @samp{^}
character a list item, place it anywhere but first.
@end table
address@hidden Backslash Character
address@hidden The Backslash Character and Special Expressions
address@hidden The Backslash Character and Special Expressions
@cindex backslash
-The @samp{\} when followed by certain ordinary characters take a special
-meaning :
+The @samp{\} character,
+when followed by certain ordinary characters,
+takes a special meaning:
@table @samp
@@ -1019,49 +1344,56 @@
Match word constituent, it is a synonym for @samp{[[:alnum:]]}.
@item @samp{\W}
-Match non word constituent, it is a synonym for @samp{[^[:alnum:]]}.
+Match non-word constituent, it is a synonym for @samp{[^[:alnum:]]}.
@end table
-For example , @samp{\brat\b} matches the separate word @samp{rat},
address@hidden matches @samp{crate}, but @samp{dirty \Brat} doesn't
-match @samp{dirty rat}.
+For example, @samp{\brat\b} matches the separate word @samp{rat},
address@hidden matches @samp{crate} but not @samp{furry rat}.
address@hidden Anchoring
@section Anchoring
@cindex anchoring
-The caret @samp{^} and the dollar sign @samp{$} are metacharacters that
+The caret @samp{^} and the dollar sign @samp{$} are meta-characters that
respectively match the empty string at the beginning and end of a line.
address@hidden Back-reference
address@hidden Back-references and Subexpressions
address@hidden Back-references and Subexpressions
address@hidden subexpression
@cindex back-reference
The back-reference @address@hidden, where @var{n} is a single digit, matches
the substring previously matched by the @var{n}th parenthesized subexpression
-of the regular expression. For example, @samp{(a)\1} matches @samp{aa}.
-When use with alternation if the group does not participate in the match, then
-the back-reference makes the whole match fail. For example, @samp{a(.)|b\1}
-will not match @samp{ba}. When multiple regular expressions are given with
address@hidden or from a file @samp{-f file}, the back-referecences are local to
-each expression.
+of the regular expression.
+For example, @samp{(a)\1} matches @samp{aa}.
+When used with alternation, if the group does not participate in the match then
+the back-reference makes the whole match fail.
+For example, @samp{a(.)|b\1}
+will not match @samp{ba}.
+When multiple regular expressions are given with
address@hidden or from a file (@samp{-f file}),
+back-references are local to each expression.
address@hidden Basic vs Extended
address@hidden Basic vs Extended
address@hidden Basic vs Extended Regular Expressions
@cindex basic regular expressions
-In basic regular expressions the metacharacters @samp{?}, @samp{+},
+In basic regular expressions the meta-characters @samp{?}, @samp{+},
@address@hidden, @samp{|}, @samp{(}, and @samp{)} lose their special meaning;
instead use the backslashed versions @samp{\?}, @samp{\+}, @address@hidden,
@samp{\|}, @samp{\(}, and @samp{\)}.
@cindex interval specifications
-Traditional @command{egrep} did not support the @address@hidden metacharacter,
+Traditional @command{egrep} did not support the @address@hidden meta-character,
and some @command{egrep} implementations support @address@hidden instead, so
portable scripts should avoid @address@hidden in @samp{grep@ -E} patterns and
should use @address@hidden to match a literal @address@hidden
@sc{gnu} @command{grep@ -E} attempts to support traditional usage by
assuming that @address@hidden is not special if it would be the start of an
-invalid interval specification. For example, the shell command
+invalid interval specification.
+For example, the command
@samp{grep@ -E@ '@{1'} searches for the two-character string @address@hidden
instead of reporting a syntax error in the regular expression.
@sc{posix.2} allows this behavior as an extension, but portable scripts
@@ -1071,7 +1403,7 @@
@chapter Usage
@cindex Usage, examples
-Here is an example shell command that invokes @sc{gnu} @command{grep}:
+Here is an example command that invokes @sc{gnu} @command{grep}:
@example
grep -i 'hello.*world' menu.h main.c
@@ -1081,9 +1413,11 @@
This lists all lines in the files @file{menu.h} and @file{main.c} that
contain the string @samp{hello} followed by the string @samp{world};
this is because @samp{.*} matches zero or more characters within a line.
address@hidden Expressions}. The @samp{-i} option causes @command{grep}
address@hidden Expressions}.
+The @samp{-i} option causes @command{grep}
to ignore case, causing it to match the line @samp{Hello, world!}, which
-it would not otherwise match. @xref{Invoking}, for more details about
+it would not otherwise match.
address@hidden, for more details about
how to invoke @command{grep}.
@cindex Using @command{grep}, Q&A
@@ -1111,25 +1445,32 @@
@end example
@noindent
-searches for @samp{hello} in all files under the directory
address@hidden/home/gigi}. For more control of which files are searched, use
address@hidden, @command{grep} and @command{xargs}. For example,
-the following command searches only C files:
+searches for @samp{hello} in all files
+under the @file{/home/gigi} directory.
+For more control over which files are searched,
+use @command{find}, @command{grep}, and @command{xargs}.
+For example, the following command searches only C files:
address@hidden
-find /home/gigi -name '*.c' -print | xargs grep 'hello' /dev/null
address@hidden smallexample
address@hidden
+find /home/gigi -name '*.c' -print0 | xargs -0r grep -H 'hello'
address@hidden example
This differs from the command:
@example
-grep -r 'hello' *.c
+grep -rH 'hello' *.c
@end example
which merely looks for @samp{hello} in all files in the current
-directory whose names end in @samp{.c}. Here the @option{-r} is
+directory whose names end in @samp{.c}.
+Here the @option{-r} is
probably unnecessary, as recursion occurs only in the unlikely event
that one of @samp{.c} files is a directory.
+The @samp{find ...} command line above is more similar to the command:
+
address@hidden
+grep -rH --include='*.c' 'hello' /home/gigi
address@hidden example
@item
What if a pattern has a leading @samp{-}?
@@ -1139,7 +1480,8 @@
@end example
@noindent
-searches for all lines matching @samp{--cut here--}. Without @samp{-e},
+searches for all lines matching @samp{--cut here--}.
+Without @samp{-e},
@command{grep} would attempt to parse @samp{--cut here--} as a list of
options.
@@ -1151,9 +1493,11 @@
@end example
@noindent
-searches only for instances of @samp{hello} that are entire words; it
-does not match @samp{Othello}. For more control, use @samp{\<} and
address@hidden>} to match the start and end of words. For example:
+searches only for instances of @samp{hello} that are entire words;
+it does not match @samp{Othello}.
+For more control, use @samp{\<} and
address@hidden>} to match the start and end of words.
+For example:
@example
grep 'hello\>' *
@@ -1174,7 +1518,7 @@
prints two lines of context around each matching line.
@item
-How do I force grep to print the name of the file?
+How do I force @command{grep} to print the name of the file?
Append @file{/dev/null}:
@@ -1184,9 +1528,15 @@
gets you:
address@hidden
-/etc/passwd:eli:DNGUTF58.IMe.:98:11:Eli Smith:/home/do/eli:/bin/bash
address@hidden smallexample
address@hidden
+/etc/passwd:eli:x:2098:1000:Eli Smith:/home/eli:/bin/bash
address@hidden example
+
+Alternatively, use @samp{-H}, which is a @sc{gnu} extension:
+
address@hidden
+grep -H 'eli' /etc/passwd
address@hidden example
@item
Why do people use strange regular expressions on @command{ps} output?
@@ -1198,8 +1548,9 @@
If the pattern had been written without the square brackets, it would
have matched not only the @command{ps} output line for @command{cron},
but also the @command{ps} output line for @command{grep}.
-Note that some platforms @command{ps} limit the ouput to the width
-of the screen, grep does not have any limit on the length of a line
+Note that on some platforms,
address@hidden limits the output to the width of the screen;
address@hidden does not have any limit on the length of a line
except the available memory.
@item
@@ -1207,18 +1558,22 @@
If @command{grep} listed all matching ``lines'' from a binary file, it
would probably generate output that is not useful, and it might even
-muck up your display. So @sc{gnu} @command{grep} suppresses output from
-files that appear to be binary files. To force @sc{gnu} @command{grep}
+muck up your display.
+So @sc{gnu} @command{grep} suppresses output from
+files that appear to be binary files.
+To force @sc{gnu} @command{grep}
to output lines even from files that appear to be binary, use the
address@hidden or @samp{--binary-files=text} option. To eliminate the
address@hidden or @samp{--binary-files=text} option.
+To eliminate the
``Binary file matches'' messages, use the @samp{-I} or
@samp{--binary-files=without-match} option.
@item
-Why doesn't @samp{grep -lv} print nonmatching file names?
+Why doesn't @samp{grep -lv} print non-matching file names?
@samp{grep -lv} lists the names of all files containing one or more
-lines that do not match. To list the names of all files that contain no
+lines that do not match.
+To list the names of all files that contain no
matching lines, use the @samp{-L} or @samp{--files-without-match}
option.
@@ -1245,8 +1600,9 @@
@cindex palindromes
How to express palindromes in a regular expression?
-It can be done by using the back referecences, for example a palindrome
-of 4 chararcters can be written in BRE.
+It can be done by using back-references;
+for example,
+a palindrome of 4 characters can be written with a BRE:
@example
grep -w -e '\(.\)\(.\).\2\1' file
@@ -1254,15 +1610,16 @@
It matches the word "radar" or "civic".
-Guglielmo Bondioni proposed a single RE that finds all the palindromes up to 19
-characters long.
+Guglielmo Bondioni proposed a single RE
+that finds all palindromes up to 19 characters long
+using @w{9 subexpressions} and @w{9 back-references}:
address@hidden
address@hidden
grep -E -e '^(.?)(.?)(.?)(.?)(.?)(.?)(.?)(.?)(.?).?\9\8\7\6\5\4\3\2\1$' file
address@hidden example
address@hidden smallexample
-Note this is done by using GNU ERE extensions, it might not be portable on
-other greps.
+Note this is done by using @sc{gnu} ERE extensions;
+it might not be portable to other implementations of @command{grep}.
@item
Why is this back-reference failing?
@@ -1273,16 +1630,17 @@
This gives no output, because the first alternate @samp{(a)\1} does not match,
as there is no @samp{aa} in the input, so the @samp{\1} in the second alternate
-has nothing to refer back to, meaning it will never match anything. (The
-second alternate in this example can only match if the first alternate has
-matched -- making the second one superfluous.)
+has nothing to refer back to, meaning it will never match anything.
+(The second alternate in this example can only match
+if the first alternate has matched -- making the second one superfluous.)
@item
What do @command{grep}, @command{fgrep}, and @command{egrep} stand for?
-The name @command{grep} comes from the way line editing was done on Unix. For
-example, @command{ed} uses the following syntax to print a list of matching
-lines on the screen:
+The name @command{grep} comes from the way line editing was done on Unix.
+For example,
address@hidden uses the following syntax
+to print a list of matching lines on the screen:
@example
global/regular expression/print
@@ -1298,12 +1656,21 @@
@chapter Reporting bugs
@cindex Bugs, reporting
-Email bug reports to @email{bug-grep@@gnu.org}.
+Email bug reports to @email{bug-grep@@gnu.org},
+a mailing list whose web page is
address@hidden://lists.gnu.org/mailman/listinfo/bug-grep}.
+The Savannah bug tracker for @command{grep} is located at
address@hidden://savannah.gnu.org/bugs/?group=grep}.
+
address@hidden Known Bugs
address@hidden Bugs, known
Large repetition counts in the @address@hidden,address@hidden construct may
cause
address@hidden to use lots of memory. In addition, certain other
address@hidden to use lots of memory.
+In addition, certain other
obscure regular expressions require exponential time and
-space, and may cause grep to run out of memory.
+space, and may cause @command{grep} to run out of memory.
+
Back-references are very slow, and may require exponential time.
@node Copying, GNU General Public License, Reporting Bugs, Top
@@ -1385,7 +1752,7 @@
of this license document, but changing it is not allowed.
@end display
address@hidden Preamble
address@hidden Preamble
The licenses for most software are designed to take away your
freedom to share and change it. By contrast, the GNU General Public
@@ -1436,7 +1803,7 @@
modification follow.
@iftex
address@hidden TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
address@hidden TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
@end iftex
@ifinfo
@center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
@@ -1699,7 +2066,7 @@
@end ifinfo
@page
address@hidden How to Apply These Terms to Your New Programs
address@hidden How to Apply These Terms to Your New Programs
If you develop a new program, and you want it to be of the greatest
possible use to the public, the best way to achieve this is to make it
@@ -2109,7 +2476,7 @@
@end enumerate
address@hidden ADDENDUM: How to use this License for your documents
address@hidden ADDENDUM: How to use this License for your documents
To use this License in a document you have written, include a copy of
the License in the document and put the following copyright and
@@ -2142,8 +2509,13 @@
@node Concept Index, Index, GNU Free Documentation License, Top
@unnumbered Concept Index
-This is a general index of all issues discussed in this manual, with the
-exception of the @command{grep} commands and command-line options.
+This is a general index of all issues discussed in this manual,
+with the exception of all specific @command{grep}
+command-line options,
+environment variables,
+color capabilities,
+and regular expression constructs,
+which are covered in their own index.
@printindex cp
@@ -2151,8 +2523,11 @@
@node Index,, Concept Index, Top
@unnumbered Index
-This is an alphabetical list of all @command{grep} commands, command-line
-options, and environment variables.
+This is an lexicographical list of all @command{grep}
+command-line options,
+environment variables,
+color capabilities,
+and regular expression constructs.
@printindex fn
- Changes to grep/doc/grep.texi,v,
Bernhard Rosenkraenzer <=