[unix-history] / usr / src / usr.bin / grep / grep.1

.TH GREP 1 "1988 December 13" "GNU Project"
.UC 4
.SH NAME
grep, egrep \- print lines matching a regular expression
.SH SYNOPSIS
.B grep
[
.B \-CVbchilnsvwx
] [
.BI \- num
] [
.B \-AB
.I num
] [ [
.B \-e
]
.I expr
|
.B \-f
.I file
] [
.I "files ..."
]
.SH DESCRIPTION
.I Grep
searches the files listed in the arguments (or standard
input if no files are given) for all lines that contain a match for
the given
.IR expr .
If any lines match, they are printed.
.PP
Also, if any matches were found,
.I grep
will exit with a status of 0, but if no matches were found it will exit
with a status of 1.  This is useful for building shell scripts that
use
.I grep
as a condition for, for example, the
.I if
statement.
.PP
When invoked as
.I egrep
the syntax of the
.I expr
is slightly different; See below.
.br
.SH "REGULAR EXPRESSIONS"
.RS 2.5i
.ta 1i; 2i
.sp
.ti -2.0i
(grep)	(egrep)		(explanation)
.sp
.ti -2.0i
\fIc\fP	\fIc\fP	a single (non-meta) character matches itself.
.sp
.ti -2.0i
\&.	.	matches any single character except newline.
.sp
.ti -2.0i
\\?	?	postfix operator; preceeding item is optional.
.sp
.ti -2.0i
\(**	\(**	postfix operator; preceeding item 0 or
more times.
.sp
.ti -2.0i
\\+	+	postfix operator; preceeding item 1 or
more times.
.sp
.ti -2.0i
\\|	|	infix operator; matches either
argument.
.sp
.ti -2.0i
^	^	matches the empty string at the beginning of a line.
.sp
.ti -2.0i
$	$	matches the empty string at the end of a line.
.sp
.ti -2.0i
\\<	\\<	matches the empty string at the beginning of a word.
.sp
.ti -2.0i
\\>	\\>	matches the empty string at the end of a word.
.sp
.ti -2.0i
[\fIchars\fP]	[\fIchars\fP]	match any character in the given class; if the
first character after [ is ^, match any character
not in the given class; a range of characters may
be specified by \fIfirst\-last\fP; for example, \\W
(below) is equivalent to the class [^A\-Za\-z0\-9]
.sp
.ti -2.0i
\\( \\)	( )	parentheses are used to override operator precedence.
.sp
.ti -2.0i
\\\fIdigit\fP	\\\fIdigit\fP	\\\fIn\fP matches a repeat of the text
matched earlier in the regexp by the subexpression inside the nth
opening parenthesis.
.sp
.ti -2.0i
\\	\\	any special character may be preceded
by a backslash to match it literally.
.sp
.ti -2.0i
(the following are for compatibility with GNU Emacs)
.sp
.ti -2.0i
\\b	\\b	matches the empty string at the edge of a word.
.sp
.ti -2.0i
\\B	\\B	matches the empty string if not at the edge of a word.
.sp
.ti -2.0i
\\w	\\w	matches word-constituent characters (letters & digits).
.sp
.ti -2.0i
\\W	\\W	matches characters that are not word-constituent.
.RE
.PP
Operator precedence is (highest to lowest) ?, \(**, and +, concatenation,
and finally |.  All other constructs are syntactically identical to
normal characters.  For the truly interested, the file dfa.c describes
(and implements) the exact grammar understood by the parser.
.SH OPTIONS
.TP
.BI \-A " num"
print <num> lines of context after every matching line
.TP
.BI \-B " num"
print
.I num
lines of context before every matching line
.TP
.B \-C
print 2 lines of context on each side of every match
.TP
.BI \- num
print
.I num
lines of context on each side of every match
.TP
.B \-V
print the version number on the diagnostic output
.TP
.B \-b
print every match preceded by its byte offset
.TP
.B \-c
print a total count of matching lines only
.TP
.BI \-e " expr"
search for
.IR expr ;
useful if
.I expr
begins with \-
.TP
.BI \-f " file"
search for the expression contained in
.I file
.TP
.B \-h
don't display filenames on matches
.TP
.B \-i
ignore case difference when comparing strings
.TP
.B \-l
list files containing matches only
.TP
.B \-n
print each match preceded by its line number
.TP
.B \-s
run silently producing no output except error messages
.TP
.B \-v
print only lines that contain no matches for the <expr>
.TP
.B \-w
print only lines where the match is a complete word
.TP
.B \-x
print only lines where the match is a whole line
.SH "SEE ALSO"
emacs(1), ed(1), sh(1),
.I "GNU Emacs Manual"
.SH INCOMPATIBILITIES
The following incompatibilities with UNIX
.I grep
exist:
.PP
.RS 0.5i
The context-dependent meaning of \(** is not quite the same (grep only).
.PP
.B \-b
prints a byte offset instead of a block offset.
.PP
The {\fIm,n\fP} construct of System V grep is not implemented.
.PP
.SH BUGS
GNU \fIe?grep\fP has been thoroughly debugged and tested by several people
over a period of several months; we think it's a reliable beast or we
wouldn't distribute it.  If by some fluke of the universe you discover
a bug, send a detailed description (including options, regular
expressions, and a copy of an input file that can reproduce it) to me,
mike@wheaties.ai.mit.edu.
.PP
There is also a newsgroup, gnu.utils.bug, for reporting FSF utility
programs' bugs and fixes; but before reporting something as a bug,
please try to be sure that it really is a bug, not a misunderstanding
or a deliberate feature.  Also, include the version number of the
utility program you are running in \fIevery\fR bug report that you
send in.  Please do not send anything but bug reports to this
newsgroup.
.PP
.SH AVAILABILITY
.PP
GNU
.I grep
is free; anyone may redistribute copies of 
.I grep
to
anyone under the terms stated in the 
GNU General Public License,
a copy of which may be found in each copy of 
.IR "GNU Emacs" .
See also the comment at the beginning of the source code file grep.c.
.PP
Copies of GNU
.I grep
may sometimes be received packaged with distributions of Unix systems,
but it is never included in the scope of any license covering those
systems.  Such inclusion violates the terms on which distribution
is permitted.  In fact, the primary purpose of the General Public
License is to prohibit anyone from attaching any other restrictions
to redistribution of any of the Free Software Foundation programs.
.SH AUTHORS
Mike Haertel wrote the deterministic regexp code and the bulk
of the program.
.PP
James A. Woods is responsible for the hybridized search strategy
of using Boyer-Moore-Gosper fixed-string search as a filter
before calling the general regexp matcher.
.PP
Arthur David Olson contributed code that finds fixed strings for
the aforementioned BMG search for a large class of regexps.
.PP
Richard Stallman wrote the backtracking regexp matcher that is
used for \\\fIdigit\fP backreferences, as well as the getopt that
is provided for 4.2BSD sites.  The backtracking matcher was
originally written for GNU Emacs.
.PP
D. A. Gwyn wrote the C alloca emulation that is provided so
System V machines can run this program.  (Alloca is used only
by RMS' backtracking matcher, and then only rarely, so there
is no loss if your machine doesn't have a "real" alloca.)
.PP
Scott Anderson and Henry Spencer designed the regression tests
used in the "regress" script.
.PP
Paul Placeway wrote the original version of this manual page.
Commit	Line	Data
da92d036 WJ	1	.TH GREP 1 "1988 December 13" "GNU Project"
	2	.UC 4
	3	.SH NAME
	4	grep, egrep \- print lines matching a regular expression
	5	.SH SYNOPSIS
	6	.B grep
	7	[
	8	.B \-CVbchilnsvwx
	9	] [
	10	.BI \- num
	11	] [
	12	.B \-AB
	13	.I num
	14	] [ [
	15	.B \-e
	16	]
	17	.I expr
	18	\|
	19	.B \-f
	20	.I file
	21	] [
	22	.I "files ..."
	23	]
	24	.SH DESCRIPTION
	25	.I Grep
	26	searches the files listed in the arguments (or standard
	27	input if no files are given) for all lines that contain a match for
	28	the given
	29	.IR expr .
	30	If any lines match, they are printed.
	31	.PP
	32	Also, if any matches were found,
	33	.I grep
	34	will exit with a status of 0, but if no matches were found it will exit
	35	with a status of 1. This is useful for building shell scripts that
	36	use
	37	.I grep
	38	as a condition for, for example, the
	39	.I if
	40	statement.
	41	.PP
	42	When invoked as
	43	.I egrep
	44	the syntax of the
	45	.I expr
	46	is slightly different; See below.
	47	.br
	48	.SH "REGULAR EXPRESSIONS"
	49	.RS 2.5i
	50	.ta 1i; 2i
	51	.sp
	52	.ti -2.0i
	53	(grep) (egrep) (explanation)
	54	.sp
	55	.ti -2.0i
	56	\fIc\fP \fIc\fP a single (non-meta) character matches itself.
	57	.sp
	58	.ti -2.0i
	59	\&. . matches any single character except newline.
	60	.sp
	61	.ti -2.0i
	62	\\? ? postfix operator; preceeding item is optional.
	63	.sp
	64	.ti -2.0i
65	\( \( postfix operator; preceeding item 0 or
66	more times.
67	.sp
68	.ti -2.0i
69	\\+ + postfix operator; preceeding item 1 or
70	more times.
71	.sp
72	.ti -2.0i
73	\\\| \| infix operator; matches either
74	argument.
75	.sp
76	.ti -2.0i
77	^ ^ matches the empty string at the beginning of a line.
78	.sp
79	.ti -2.0i
80	$ $ matches the empty string at the end of a line.
81	.sp
82	.ti -2.0i
83	\\< \\< matches the empty string at the beginning of a word.
84	.sp
85	.ti -2.0i
86	\\> \\> matches the empty string at the end of a word.
87	.sp
88	.ti -2.0i
89	[\fIchars\fP] [\fIchars\fP] match any character in the given class; if the
90	first character after [ is ^, match any character
91	not in the given class; a range of characters may
92	be specified by \fIfirst\-last\fP; for example, \\W
93	(below) is equivalent to the class [^A\-Za\-z0\-9]
94	.sp
95	.ti -2.0i
96	\\( \\) ( ) parentheses are used to override operator precedence.
97	.sp
98	.ti -2.0i
99	\\\fIdigit\fP \\\fIdigit\fP \\\fIn\fP matches a repeat of the text
100	matched earlier in the regexp by the subexpression inside the nth
101	opening parenthesis.
102	.sp
103	.ti -2.0i
104	\\ \\ any special character may be preceded
105	by a backslash to match it literally.
106	.sp
107	.ti -2.0i
108	(the following are for compatibility with GNU Emacs)
109	.sp
110	.ti -2.0i
111	\\b \\b matches the empty string at the edge of a word.
112	.sp
113	.ti -2.0i
114	\\B \\B matches the empty string if not at the edge of a word.
115	.sp
116	.ti -2.0i
117	\\w \\w matches word-constituent characters (letters & digits).
118	.sp
119	.ti -2.0i
120	\\W \\W matches characters that are not word-constituent.
121	.RE
122	.PP
123	Operator precedence is (highest to lowest) ?, \(**, and +, concatenation,
124	and finally \|. All other constructs are syntactically identical to
125	normal characters. For the truly interested, the file dfa.c describes
126	(and implements) the exact grammar understood by the parser.
127	.SH OPTIONS
128	.TP
129	.BI \-A " num"
130	print <num> lines of context after every matching line
131	.TP
132	.BI \-B " num"
133	print
134	.I num
135	lines of context before every matching line
136	.TP
137	.B \-C
138	print 2 lines of context on each side of every match
139	.TP
140	.BI \- num
141	print
142	.I num
143	lines of context on each side of every match
144	.TP
145	.B \-V
146	print the version number on the diagnostic output
147	.TP
148	.B \-b
149	print every match preceded by its byte offset
150	.TP
151	.B \-c
152	print a total count of matching lines only
153	.TP
154	.BI \-e " expr"
155	search for
156	.IR expr ;
157	useful if
158	.I expr
159	begins with \-
160	.TP
161	.BI \-f " file"
162	search for the expression contained in
163	.I file
164	.TP
165	.B \-h
166	don't display filenames on matches
167	.TP
168	.B \-i
169	ignore case difference when comparing strings
170	.TP
171	.B \-l
172	list files containing matches only
173	.TP
174	.B \-n
175	print each match preceded by its line number
176	.TP
177	.B \-s
178	run silently producing no output except error messages
179	.TP
180	.B \-v
181	print only lines that contain no matches for the <expr>
182	.TP
183	.B \-w
184	print only lines where the match is a complete word
185	.TP
186	.B \-x
187	print only lines where the match is a whole line
188	.SH "SEE ALSO"
189	emacs(1), ed(1), sh(1),
190	.I "GNU Emacs Manual"
191	.SH INCOMPATIBILITIES
192	The following incompatibilities with UNIX
193	.I grep
194	exist:
195	.PP
196	.RS 0.5i
197	The context-dependent meaning of \(** is not quite the same (grep only).
198	.PP
199	.B \-b
200	prints a byte offset instead of a block offset.
201	.PP
202	The {\fIm,n\fP} construct of System V grep is not implemented.
203	.PP
204	.SH BUGS
205	GNU \fIe?grep\fP has been thoroughly debugged and tested by several people
206	over a period of several months; we think it's a reliable beast or we
207	wouldn't distribute it. If by some fluke of the universe you discover
208	a bug, send a detailed description (including options, regular
209	expressions, and a copy of an input file that can reproduce it) to me,
210	mike@wheaties.ai.mit.edu.
211	.PP
212	There is also a newsgroup, gnu.utils.bug, for reporting FSF utility
213	programs' bugs and fixes; but before reporting something as a bug,
214	please try to be sure that it really is a bug, not a misunderstanding
215	or a deliberate feature. Also, include the version number of the
216	utility program you are running in \fIevery\fR bug report that you
217	send in. Please do not send anything but bug reports to this
218	newsgroup.
219	.PP
220	.SH AVAILABILITY
221	.PP
222	GNU
223	.I grep
224	is free; anyone may redistribute copies of
225	.I grep
226	to
227	anyone under the terms stated in the
228	GNU General Public License,
229	a copy of which may be found in each copy of
230	.IR "GNU Emacs" .
231	See also the comment at the beginning of the source code file grep.c.
232	.PP
233	Copies of GNU
234	.I grep
235	may sometimes be received packaged with distributions of Unix systems,
236	but it is never included in the scope of any license covering those
237	systems. Such inclusion violates the terms on which distribution
238	is permitted. In fact, the primary purpose of the General Public
239	License is to prohibit anyone from attaching any other restrictions
240	to redistribution of any of the Free Software Foundation programs.
241	.SH AUTHORS
242	Mike Haertel wrote the deterministic regexp code and the bulk
243	of the program.
244	.PP
245	James A. Woods is responsible for the hybridized search strategy
246	of using Boyer-Moore-Gosper fixed-string search as a filter
247	before calling the general regexp matcher.
248	.PP
249	Arthur David Olson contributed code that finds fixed strings for
250	the aforementioned BMG search for a large class of regexps.
251	.PP
252	Richard Stallman wrote the backtracking regexp matcher that is
253	used for \\\fIdigit\fP backreferences, as well as the getopt that
254	is provided for 4.2BSD sites. The backtracking matcher was
255	originally written for GNU Emacs.
256	.PP
257	D. A. Gwyn wrote the C alloca emulation that is provided so
258	System V machines can run this program. (Alloca is used only
259	by RMS' backtracking matcher, and then only rarely, so there
260	is no loss if your machine doesn't have a "real" alloca.)
261	.PP
262	Scott Anderson and Henry Spencer designed the regression tests
263	used in the "regress" script.
264	.PP
265	Paul Placeway wrote the original version of this manual page.