1 \input texinfo @c -*-texinfo-*-
4 @settitle grep, print lines matching a pattern
7 @c This file has the new style title page commands.
8 @c Run `makeinfo' rather than `texinfo-format-buffer'.
29 * grep: (grep). print lines matching a pattern.
31 This file documents @command{grep}, a pattern matching engine.
34 Published by the Free Software Foundation,
35 59 Temple Place - Suite 330
36 Boston, MA 02111-1307, USA
38 @c man begin COPYRIGHT
39 Copyright @copyright{} 2000, 2001 Free Software Foundation, Inc.
41 Permission is granted to make and distribute verbatim copies of
42 this manual provided the copyright notice and this permission notice
43 are preserved on all copies.
46 Permission is granted to process this file through TeX and print the
47 results, provided the printed document carries a copying permission
48 notice identical to this one except for the removal of this paragraph
49 (this paragraph not being relevant to the printed manual).
52 Permission is granted to copy, distribute and/or modify this document
53 under the terms of the GNU Free Documentation License, Version 1.1 or
54 any later version published by the Free Software Foundation; with the
55 Invariant Sections being ``GNU General Public License'' and ``GNU Free
56 Documentation License'', with no Front-Cover Texts, and with no
57 Back-Cover Texts. A copy of the license is included in the section
58 entitled ``GNU Free Documentation License'' (@pxref{Copying}).
62 @setchapternewpage off
65 @title grep, searching for a pattern
66 @subtitle version @value{VERSION}, @value{UPDATED}
67 @author Alain Magloire et al.
70 @vskip 0pt plus 1filll
71 Copyright @copyright{} 2000, 2001 Free Software Foundation, Inc.
74 Published by the Free Software Foundation, @*
75 59 Temple Place - Suite 330, @*
76 Boston, MA 02111-1307, USA
78 Permission is granted to copy, distribute and/or modify this document
79 under the terms of the GNU Free Documentation License, Version 1.1 or
80 any later version published by the Free Software Foundation; with the
81 Invariant Sections being ``GNU General Public License'' and ``GNU Free
82 Documentation License'', with no Front-Cover Texts, and with no
83 Back-Cover Texts. A copy of the license is included in the section
84 entitled ``GNU Free Documentation License''.
92 @command{grep} searches for lines matching a pattern.
94 This document was produced for version @value{VERSION} of @sc{gnu}
99 * Introduction:: Introduction.
100 * Invoking:: Invoking @command{grep}; description of options.
101 * Diagnostics:: Exit status returned by @command{grep}.
102 * Grep Programs:: @command{grep} programs.
103 * Regular Expressions:: Regular Expressions.
105 * Reporting Bugs:: Reporting Bugs.
106 * Copying:: License terms.
107 * Concept Index:: A menu with all the topics in this manual.
108 * Index:: A menu with all @command{grep} commands
109 and command-line options.
113 @node Introduction, Invoking, Top, Top
114 @chapter Introduction
116 @cindex Searching for a pattern.
118 @command{grep} searches the input files
119 for lines containing a match to a given
120 pattern list. When it finds a match in a line, it copies the line to standard
121 output (by default), or does whatever other sort of output you have requested
124 Though @command{grep} expects to do the matching on text,
125 it has no limits on input line length other than available memory,
126 and it can match arbitrary characters within a line.
127 If the final byte of an input file is not a newline,
128 @command{grep} silently supplies one.
129 Since newline is also a separator for the list of patterns, there
130 is no way to match newline characters in a text.
133 @chapter Invoking @command{grep}
135 @command{grep} comes with a rich set of options from @sc{posix.2} and @sc{gnu}
144 @cindex counting lines
145 Suppress normal output; instead print a count of matching
146 lines for each input file. With the @samp{-v}, @samp{--invert-match} option,
147 count non-matching lines.
149 @item -e @var{pattern}
150 @itemx --regexp=@var{pattern}
152 @opindex --regexp=@var{pattern}
154 Use @var{pattern} as the pattern; useful to protect patterns
155 beginning with a @samp{-}.
158 @itemx --file=@var{file}
161 @cindex pattern from file
162 Obtain patterns from @var{file}, one per line. The empty
163 file contains zero patterns, and therefore matches nothing.
168 @opindex --ignore-case
169 @cindex case insensitive search
170 Ignore case distinctions in both the pattern and the input files.
173 @itemx --files-with-matches
175 @opindex --files-with-matches
176 @cindex names of matching files
177 Suppress normal output; instead print the name of each input
178 file from which output would normally have been printed.
179 The scanning of every file will stop on the first match.
184 @opindex --line-number
185 @cindex line numbering
186 Prefix each line of output with the line number within its input file.
189 @itemx --only-matching
191 @opindex --only-matching
192 @cindex only matching
193 Print only the part of matching lines that actually matches @var{pattern}.
201 @cindex quiet, silent
202 Quiet; do not write anything to standard output. Exit immediately with
203 zero status if any match is found, even if an error was detected. Also
204 see the @samp{-s} or @samp{--no-messages} option.
209 @opindex --no-messages
210 @cindex suppress error messages
211 Suppress error messages about nonexistent or unreadable files.
212 Portability note: unlike @sc{gnu} @command{grep}, traditional
213 @command{grep} did not conform to @sc{posix.2}, because traditional
214 @command{grep} lacked a @samp{-q} option and its @samp{-s} option behaved
215 like @sc{gnu} @command{grep}'s @samp{-q} option. Shell scripts intended
216 to be portable to traditional @command{grep} should avoid both
217 @samp{-q} and @samp{-s} and should redirect
218 output to @file{/dev/null} instead.
221 @itemx --invert-match
223 @opindex --invert-match
224 @cindex invert matching
225 @cindex print non-matching lines
226 Invert the sense of matching, to select non-matching lines.
231 @opindex --line-regexp
232 @cindex match the whole line
233 Select only those matches that exactly match the whole line.
237 @section @sc{gnu} Extensions
242 @itemx --after-context=@var{num}
244 @opindex --after-context
245 @cindex after context
246 @cindex context lines, after match
247 Print @var{num} lines of trailing context after matching lines.
250 @itemx --before-context=@var{num}
252 @opindex --before-context
253 @cindex before context
254 @cindex context lines, before match
255 Print @var{num} lines of leading context before matching lines.
258 @itemx --context=@var{num}
262 Print @var{num} lines of output context.
264 @item --colour[=@var{WHEN}]
265 @itemx --color[=@var{WHEN}]
267 @cindex highlight, color, colour
268 The matching string is surrounded by the marker specify in @var{GREP_COLOR}.
269 @var{WHEN} may be `never', `always', or `auto'.
273 Same as @samp{--context=@var{num}} lines of leading and trailing
274 context. However, grep will never print any given line more than once.
281 @cindex Version, printing
282 Print the version number of @command{grep} to the standard output stream.
283 This version number should be included in all bug reports.
287 @cindex Usage summary, printing
288 Print a usage message briefly summarizing these command-line options
289 and the bug-reporting address, then exit.
291 @itemx --binary-files=@var{type}
292 @opindex --binary-files
294 If the first few bytes of a file indicate that the file contains binary
295 data, assume that the file is of type @var{type}. By default,
296 @var{type} is @samp{binary}, and @command{grep} normally outputs either
297 a one-line message saying that a binary file matches, or no message if
298 there is no match. If @var{type} is @samp{without-match},
299 @command{grep} assumes that a binary file does not match;
300 this is equivalent to the @samp{-I} option. If @var{type}
301 is @samp{text}, @command{grep} processes a binary file as if it were
302 text; this is equivalent to the @samp{-a} option.
303 @emph{Warning:} @samp{--binary-files=text} might output binary garbage,
304 which can have nasty side effects if the output is a terminal and if the
305 terminal driver interprets some of it as commands.
310 @opindex --byte-offset
312 Print the byte offset within the input file before each line of output.
313 When @command{grep} runs on @sc{ms-dos} or MS-Windows, the printed
315 depend on whether the @samp{-u} (@samp{--unix-byte-offsets}) option is
318 @item -D @var{action}
319 @itemx --devices=@var{action}
322 @cindex device search
323 If an input file is a device, FIFO or socket, use @var{action} to process it.
324 By default, @var{action} is @samp{read}, which means that devices are
325 read just as if they were ordinary files.
326 If @var{action} is @samp{skip}, devices, FIFOs and sockets are silently
329 @item -d @var{action}
330 @itemx --directories=@var{action}
332 @opindex --directories
333 @cindex directory search
334 If an input file is a directory, use @var{action} to process it.
335 By default, @var{action} is @samp{read}, which means that directories are
336 read just as if they were ordinary files (some operating systems
337 and filesystems disallow this, and will cause @command{grep} to print error
338 messages for every directory or silently skip them). If @var{action} is
339 @samp{skip}, directories are silently skipped. If @var{action} is
340 @samp{recurse}, @command{grep} reads all files under each directory,
341 recursively; this is equivalent to the @samp{-r} option.
344 @itemx --with-filename
346 @opindex --With-filename
347 @cindex with filename prefix
348 Print the filename for each match.
353 @opindex --no-filename
354 @cindex no filename prefix
355 Suppress the prefixing of filenames on output when multiple files are searched.
357 @item --line-buffered
358 @opindex --line-buffered
359 @cindex line buffering
360 Set the line buffering policy, this can be a performance penality.
362 @item --label=@var{LABEL}
364 @cindex changing name of standard input
365 Displays input actually coming from standard input as input coming from file
366 @var{LABEL}. This is especially useful for tools like zgrep, e.g.
367 @command{gzip -cd foo.gz |grep --label=foo something}
370 @itemx --files-without-match
372 @opindex --files-without-match
373 @cindex files which don't match
374 Suppress normal output; instead print the name of each input
375 file from which no output would normally have been printed.
376 The scanning of every file will stop on the first match.
382 @cindex suppress binary data
384 Process a binary file as if it were text; this is equivalent to the
385 @samp{--binary-files=text} option.
388 Process a binary file as if it did not contain matching data; this is
389 equivalent to the @samp{--binary-files=without-match} option.
394 @opindex --word-regexp
395 @cindex matching whole words
396 Select only those lines containing matches that form
397 whole words. The test is that the matching substring
398 must either be at the beginning of the line, or preceded
399 by a non-word constituent character. Similarly,
400 it must be either at the end of the line or followed by
401 a non-word constituent character. Word-constituent
402 characters are letters, digits, and the underscore.
409 @cindex recursive search
410 @cindex searching directory trees
411 For each directory mentioned in the command line, read and process all
412 files in that directory, recursively. This is the same as the
413 @samp{--directories=recurse} option.
415 @item --include=@var{file_pattern}
417 @cindex include files
418 @cindex searching directory trees
419 When processing directories recursively, only files matching @var{file_pattern}
422 @item --exclude=@var{file_pattern}
424 @cindex exclude files
425 @cindex searching directory trees
426 When processing directories recursively, skip files matching @var{file_pattern}.
429 @itemx --max-count=@var{num}
433 Stop reading a file after @var{num} matching lines. If the input is
434 standard input from a regular file, and @var{num} matching lines are
435 output, @command{grep} ensures that the standard input is positioned to
436 just after the last matching line before exiting, regardless of the
437 presence of trailing context lines. This enables a calling process
438 to resume a search. For example, the following shell script makes use
442 while grep -m 1 PATTERN
448 But the following probably will not work because a pipe is not a regular
452 # This probably will not work.
454 while grep -m 1 PATTERN
460 When @command{grep} stops after NUM matching lines, it outputs
461 any trailing context lines. Since context does not include matching
462 lines, @command{grep} will stop when it encounters another matching line.
463 When the @samp{-c} or @samp{--count} option is also used,
464 @command{grep} does not output a count greater than @var{num}.
465 When the @samp{-v} or @samp{--invert-match} option is
466 also used, @command{grep} stops after outputting @var{num}
471 @cindex case insensitive search, obsolete option
472 Obsolete synonym for @samp{-i}.
478 @cindex DOS/Windows binary files
479 @cindex binary files, DOS/Windows
480 Treat the file(s) as binary. By default, under @sc{ms-dos}
481 and MS-Windows, @command{grep} guesses the file type by looking
482 at the contents of the first 32kB read from the file.
483 If @command{grep} decides the file is a text file, it strips the
484 @code{CR} characters from the original file contents (to make
485 regular expressions with @code{^} and @code{$} work correctly).
486 Specifying @samp{-U} overrules this guesswork, causing all
487 files to be read and passed to the matching mechanism
488 verbatim; if the file is a text file with @code{CR/LF} pairs
489 at the end of each line, this will cause some regular
490 expressions to fail. This option has no effect on platforms other than
491 @sc{ms-dos} and MS-Windows.
494 @itemx --unix-byte-offsets
496 @opindex --unix-byte-offsets
497 @cindex DOS byte offsets
498 @cindex byte offsets, on DOS/Windows
499 Report Unix-style byte offsets. This switch causes
500 @command{grep} to report byte offsets as if the file were Unix style
501 text file, i.e., the byte offsets ignore the @code{CR} characters which were
502 stripped. This will produce results identical to running @command{grep} on
503 a Unix machine. This option has no effect unless @samp{-b}
504 option is also used; it has no effect on platforms other than @sc{ms-dos} and
509 @cindex memory mapped input
510 If possible, use the @code{mmap} system call to read input, instead of
511 the default @code{read} system call. In some situations, @samp{--mmap}
512 yields better performance. However, @samp{--mmap} can cause undefined
513 behavior (including core dumps) if an input file shrinks while
514 @command{grep} is operating, or if an I/O error occurs.
520 @cindex zero-terminated file names
521 Output a zero byte (the @sc{ascii} @code{NUL} character) instead of the
522 character that normally follows a file name. For example, @samp{grep
523 -lZ} outputs a zero byte after each file name instead of the usual
524 newline. This option makes the output unambiguous, even in the presence
525 of file names containing unusual characters like newlines. This option
526 can be used with commands like @samp{find -print0}, @samp{perl -0},
527 @samp{sort -z}, and @samp{xargs -0} to process arbitrary file names,
528 even those that contain newline characters.
534 @cindex zero-terminated lines
535 Treat the input as a set of lines, each terminated by a zero byte (the
536 @sc{ascii} @code{NUL} character) instead of a newline. Like the @samp{-Z}
537 or @samp{--null} option, this option can be used with commands like
538 @samp{sort -z} to process arbitrary file names.
542 Several additional options control which variant of the @command{grep}
543 matching engine is used. @xref{Grep Programs}.
545 @section Environment Variables
547 Grep's behavior is affected by the following environment variables.
549 A locale @code{LC_@var{foo}} is specified by examining the three
550 environment variables @env{LC_ALL}, @env{LC_@var{foo}}, and @env{LANG},
551 in that order. The first of these variables that is set specifies the
552 locale. For example, if @env{LC_ALL} is not set, but @env{LC_MESSAGES}
553 is set to @samp{pt_BR}, then Brazilian Portuguese is used for the
554 @code{LC_MESSAGES} locale. The C locale is used if none of these
555 environment variables are set, or if the locale catalog is not
556 installed, or if @command{grep} was not compiled with national language
559 @cindex environment variables
565 @cindex default options environment variable
566 This variable specifies default options to be placed in front of any
567 explicit options. For example, if @code{GREP_OPTIONS} is
568 @samp{--binary-files=without-match --directories=skip}, @command{grep}
569 behaves as if the two options @samp{--binary-files=without-match} and
570 @samp{--directories=skip} had been specified before
571 any explicit options. Option specifications are separated by
572 whitespace. A backslash escapes the next character, so it can be used to
573 specify an option containing whitespace or a backslash.
577 @cindex highlight markers
578 This variable specifies the surrounding markers use to highlight the matching
579 text. The default is control ascii red.
587 @cindex character type
588 @cindex national language support
590 These variables specify the @code{LC_COLLATE} locale, which determines
591 the collating sequence used to interpret range expressions like
600 @cindex character type
601 @cindex national language support
603 These variables specify the @code{LC_CTYPE} locale, which determines the
604 type of characters, e.g., which characters are whitespace.
612 @cindex language of messages
613 @cindex message language
614 @cindex national language support
616 @cindex translation of message language
617 These variables specify the @code{LC_MESSAGES} locale, which determines
618 the language that @command{grep} uses for messages. The default C
619 locale uses American English messages.
621 @item POSIXLY_CORRECT
622 @vindex POSIXLY_CORRECT
623 If set, @command{grep} behaves as @sc{posix.2} requires; otherwise,
624 @command{grep} behaves more like other @sc{gnu} programs. @sc{posix.2}
625 requires that options that
626 follow file names must be treated as file names; by default, such
627 options are permuted to the front of the operand list and are treated as
628 options. Also, @sc{posix.2} requires that unrecognized options be
630 ``illegal'', but since they are not really against the law the default
631 is to diagnose them as ``invalid''. @code{POSIXLY_CORRECT} also
632 disables @code{_@var{N}_GNU_nonoption_argv_flags_}, described below.
634 @item _@var{N}_GNU_nonoption_argv_flags_
635 @vindex _@var{N}_GNU_nonoption_argv_flags_
636 (Here @code{@var{N}} is @command{grep}'s numeric process ID.) If the
637 @var{i}th character of this environment variable's value is @samp{1}, do
638 not consider the @var{i}th operand of @command{grep} to be an option, even if
639 it appears to be one. A shell can put this variable in the environment
640 for each command it runs, specifying which operands are the results of
641 file name wildcard expansion and therefore should not be treated as
642 options. This behavior is available only with the @sc{gnu} C library, and
643 only when @code{POSIXLY_CORRECT} is not set.
650 Normally, exit status is 0 if selected lines are found and 1 otherwise.
651 But the exit status is 2 if an error occurred, unless the @option{-q} or
652 @option{--quiet} or @option{--silent} option is used and a selected line
656 @chapter @command{grep} programs
658 @command{grep} searches the named input files (or standard input if no
659 files are named, or the file name @file{-} is given) for lines containing
660 a match to the given pattern. By default, @command{grep} prints the
661 matching lines. There are four major variants of @command{grep},
662 controlled by the following options.
667 @itemx --basic-regexp
669 @opindex --basic-regexp
670 @cindex matching basic regular expressions
671 Interpret the pattern as a basic regular expression. This is the default.
674 @itemx --extended-regexp
676 @opindex --extended-regexp
677 @cindex matching extended regular expressions
678 Interpret the pattern as an extended regular expression.
681 @itemx --fixed-strings
683 @opindex --fixed-strings
684 @cindex matching fixed strings
685 Interpret the pattern as a list of fixed strings, separated
686 by newlines, any of which is to be matched.
691 @opindex --perl-regexp
692 @cindex matching Perl regular expressions
693 Interpret the pattern as a Perl regular expression.
697 In addition, two variant programs @sc{egrep} and @sc{fgrep} are available.
698 @sc{egrep} is the same as @samp{grep -E}. @sc{fgrep} is the
699 same as @samp{grep -F}.
701 @node Regular Expressions
702 @chapter Regular Expressions
703 @cindex regular expressions
705 A @dfn{regular expression} is a pattern that describes a set of strings.
706 Regular expressions are constructed analogously to arithmetic expressions,
707 by using various operators to combine smaller expressions.
708 @command{grep} understands two different versions of regular expression
709 syntax: ``basic''(BRE) and ``extended''(ERE). In @sc{gnu} @command{grep},
710 there is no difference in available functionality using either syntax.
711 In other implementations, basic regular expressions are less powerful.
712 The following description applies to extended regular expressions;
713 differences for basic regular expressions are summarized afterwards.
715 The fundamental building blocks are the regular expressions that match
716 a single character. Most characters, including all letters and digits,
717 are regular expressions that match themselves. Any metacharacter
718 with special meaning may be quoted by preceding it with a backslash.
720 A regular expression may be followed by one of several
721 repetition operators:
729 The period @samp{.} matches any single character.
733 @cindex question mark
734 @cindex match sub-expression at most once
735 The preceding item is optional and will be matched at most once.
740 @cindex match sub-expression zero or more times
741 The preceding item will be matched zero or more times.
746 The preceding item will be matched one or more times.
750 @cindex braces, one argument
751 @cindex match sub-expression n times
752 The preceding item is matched exactly @var{n} times.
756 @cindex braces, second argument omitted
757 @cindex match sub-expression n or more times
758 The preceding item is matched n or more times.
760 @item @{@var{n},@var{m}@}
762 @cindex braces, two arguments
763 The preceding item is matched at least @var{n} times, but not more than
768 Two regular expressions may be concatenated; the resulting regular
769 expression matches any string formed by concatenating two substrings
770 that respectively match the concatenated subexpressions.
772 Two regular expressions may be joined by the infix operator @samp{|}; the
773 resulting regular expression matches any string matching either subexpression.
775 Repetition takes precedence over concatenation, which in turn
776 takes precedence over alternation. A whole subexpression may be
777 enclosed in parentheses to override these precedence rules.
779 @section Character Class
781 @cindex bracket expression
782 @cindex character class
783 A @dfn{bracket expression} is a list of characters enclosed by @samp{[} and
784 @samp{]}. It matches any single character in that list; if the first
785 character of the list is the caret @samp{^}, then it matches any character
786 @strong{not} in the list. For example, the regular expression
787 @samp{[0123456789]} matches any single digit.
789 @cindex range expression
790 Within a bracket expression, a @dfn{range expression} consists of two
791 characters separated by a hyphen. It matches any single character that
792 sorts between the two characters, inclusive, using the locale's
793 collating sequence and character set. For example, in the default C
794 locale, @samp{[a-d]} is equivalent to @samp{[abcd]}. Many locales sort
795 characters in dictionary order, and in these locales @samp{[a-d]} is
796 typically not equivalent to @samp{[abcd]}; it might be equivalent to
797 @samp{[aBbCcDd]}, for example. To obtain the traditional interpretation
798 of bracket expressions, you can use the C locale by setting the
799 @env{LC_ALL} environment variable to the value @samp{C}.
801 Finally, certain named classes of characters are predefined within
802 bracket expressions, as follows.
803 Their interpretation depends on the @code{LC_CTYPE} locale; the
804 interpretation below is that of the C locale, which is the default
805 if no @code{LC_CTYPE} locale is specified.
807 @cindex classes of characters
808 @cindex character classes
813 @cindex alphanumeric characters
814 Alphanumeric characters:
815 @samp{[:alpha:]} and @samp{[:digit:]}.
819 @cindex alphabetic characters
820 Alphabetic characters:
821 @samp{[:lower:]} and @samp{[:upper:]}.
825 @cindex blank characters
831 @cindex control characters
832 Control characters. In @sc{ascii}, these characters have octal codes 000
833 through 037, and 177 (@code{DEL}). In other character sets, these are
834 the equivalent characters, if any.
838 @cindex digit characters
839 @cindex numeric characters
840 Digits: @code{0 1 2 3 4 5 6 7 8 9}.
844 @cindex graphic characters
845 Graphical characters:
846 @samp{[:alnum:]} and @samp{[:punct:]}.
850 @cindex lower-case letters
852 @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}.
856 @cindex printable characters
857 Printable characters:
858 @samp{[:alnum:]}, @samp{[:punct:]}, and space.
862 @cindex punctuation characters
863 Punctuation characters:
864 @code{!@: " # $ % & ' ( ) * + , - .@: / : ; < = > ?@: @@ [ \ ] ^ _ ` @{ | @} ~}.
868 @cindex space characters
869 @cindex whitespace characters
871 tab, newline, vertical tab, form feed, carriage return, and space.
875 @cindex upper-case letters
877 @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}.
882 @cindex hexadecimal digits
884 @code{0 1 2 3 4 5 6 7 8 9 A B C D E F a b c d e f}.
887 For example, @samp{[[:alnum:]]} means @samp{[0-9A-Za-z]}, except the latter
888 depends upon the C locale and the @sc{ascii} character
889 encoding, whereas the former is independent of locale and character set.
890 (Note that the brackets in these class names are
891 part of the symbolic names, and must be included in addition to
892 the brackets delimiting the bracket list.)
894 Most metacharacters lose their special meaning inside lists.
898 ends the list if it's not the first list item. So, if you want to make
899 the @samp{]} character a list item, you must put it first.
902 represents the open collating symbol.
905 represents the close collating symbol.
908 represents the open equivalence class.
911 represents the close equivalence class.
914 represents the open character class followed by a valid character class name.
917 represents the close character class followed by a valid character class name.
920 represents the range if it's not first or last in a list or the ending point
924 represents the characters not in the list. If you want to make the @samp{^}
925 character a list item, place it anywhere but first.
929 @section Backslash Character
932 The @samp{\} when followed by certain ordinary characters take a special
938 Match the empty string at the edge of a word.
941 Match the empty string provided it's not at the edge of a word.
944 Match the empty string at the beginning of word.
947 Match the empty string at the end of word.
950 Match word constituent, it is a synonym for @samp{[[:alnum:]]}.
953 Match non word constituent, it is a synonym for @samp{[^[:alnum:]]}.
957 For example , @samp{\brat\b} matches the separate word @samp{rat},
958 @samp{c\Brat\Be} matches @samp{crate}, but @samp{dirty \Brat} doesn't
959 match @samp{dirty rat}.
964 The caret @samp{^} and the dollar sign @samp{$} are metacharacters that
965 respectively match the empty string at the beginning and end of a line.
967 @section Back-reference
968 @cindex back-reference
970 The back-reference @samp{\@var{n}}, where @var{n} is a single digit, matches
971 the substring previously matched by the @var{n}th parenthesized subexpression
972 of the regular expression. For example, @samp{(a)\1} matches @samp{aa}.
973 When use with alternation if the group does not participate in the match, then
974 the back-reference makes the whole match fail. For example, @samp{a(.)|b\1}
975 will not match @samp{ba}. When multiple regular expressions are given with
976 @samp{-e} or from a file @samp{-f file}, the back-referecences are local to
979 @section Basic vs Extended
980 @cindex basic regular expressions
982 In basic regular expressions the metacharacters @samp{?}, @samp{+},
983 @samp{@{}, @samp{|}, @samp{(}, and @samp{)} lose their special meaning;
984 instead use the backslashed versions @samp{\?}, @samp{\+}, @samp{\@{},
985 @samp{\|}, @samp{\(}, and @samp{\)}.
987 @cindex interval specifications
988 Traditional @command{egrep} did not support the @samp{@{} metacharacter,
989 and some @command{egrep} implementations support @samp{\@{} instead, so
990 portable scripts should avoid @samp{@{} in @samp{egrep} patterns and
991 should use @samp{[@{]} to match a literal @samp{@{}.
993 @sc{gnu} @command{egrep} attempts to support traditional usage by
994 assuming that @samp{@{} is not special if it would be the start of an
995 invalid interval specification. For example, the shell command
996 @samp{egrep '@{1'} searches for the two-character string @samp{@{1}
997 instead of reporting a syntax error in the regular expression.
998 @sc{posix.2} allows this behavior as an extension, but portable scripts
1004 @cindex Usage, examples
1005 Here is an example shell command that invokes @sc{gnu} @command{grep}:
1008 grep -i 'hello.*world' menu.h main.c
1012 This lists all lines in the files @file{menu.h} and @file{main.c} that
1013 contain the string @samp{hello} followed by the string @samp{world};
1014 this is because @samp{.*} matches zero or more characters within a line.
1015 @xref{Regular Expressions}. The @samp{-i} option causes @command{grep}
1016 to ignore case, causing it to match the line @samp{Hello, world!}, which
1017 it would not otherwise match. @xref{Invoking}, for more details about
1018 how to invoke @command{grep}.
1020 @cindex Using @command{grep}, Q&A
1021 @cindex FAQ about @command{grep} usage
1022 Here are some common questions and answers about @command{grep} usage.
1027 How can I list just the names of matching files?
1034 lists the names of all C files in the current directory whose contents
1035 mention @samp{main}.
1038 How do I search directories recursively?
1041 grep -r 'hello' /home/gigi
1045 searches for @samp{hello} in all files under the directory
1046 @file{/home/gigi}. For more control of which files are searched, use
1047 @command{find}, @command{grep} and @command{xargs}. For example,
1048 the following command searches only C files:
1051 find /home/gigi -name '*.c' -print | xargs grep 'hello' /dev/null
1054 This differs from the command:
1060 which merely looks for @samp{hello} in all files in the current
1061 directory whose names end in @samp{.c}. Here the @option{-r} is
1062 probably unnecessary, as recursion occurs only in the unlikely event
1063 that one of @samp{.c} files is a directory.
1066 What if a pattern has a leading @samp{-}?
1069 grep -e '--cut here--' *
1073 searches for all lines matching @samp{--cut here--}. Without @samp{-e},
1074 @command{grep} would attempt to parse @samp{--cut here--} as a list of
1078 Suppose I want to search for a whole word, not a part of a word?
1085 searches only for instances of @samp{hello} that are entire words; it
1086 does not match @samp{Othello}. For more control, use @samp{\<} and
1087 @samp{\>} to match the start and end of words. For example:
1094 searches only for words ending in @samp{hello}, so it matches the word
1098 How do I output context around the matching lines?
1105 prints two lines of context around each matching line.
1108 How do I force grep to print the name of the file?
1110 Append @file{/dev/null}:
1113 grep 'eli' /etc/passwd /dev/null
1119 /etc/passwd:eli:DNGUTF58.IMe.:98:11:Eli Smith:/home/do/eli:/bin/bash
1123 Why do people use strange regular expressions on @command{ps} output?
1126 ps -ef | grep '[c]ron'
1129 If the pattern had been written without the square brackets, it would
1130 have matched not only the @command{ps} output line for @command{cron},
1131 but also the @command{ps} output line for @command{grep}.
1132 Note that some platforms @command{ps} limit the ouput to the width
1133 of the screen, grep does not have any limit on the length of a line
1134 except the available memory.
1137 Why does @command{grep} report ``Binary file matches''?
1139 If @command{grep} listed all matching ``lines'' from a binary file, it
1140 would probably generate output that is not useful, and it might even
1141 muck up your display. So @sc{gnu} @command{grep} suppresses output from
1142 files that appear to be binary files. To force @sc{gnu} @command{grep}
1143 to output lines even from files that appear to be binary, use the
1144 @samp{-a} or @samp{--binary-files=text} option. To eliminate the
1145 ``Binary file matches'' messages, use the @samp{-I} or
1146 @samp{--binary-files=without-match} option.
1149 Why doesn't @samp{grep -lv} print nonmatching file names?
1151 @samp{grep -lv} lists the names of all files containing one or more
1152 lines that do not match. To list the names of all files that contain no
1153 matching lines, use the @samp{-L} or @samp{--files-without-match}
1157 I can do @sc{or} with @samp{|}, but what about @sc{and}?
1160 grep 'paul' /etc/motd | grep 'franc,ois'
1164 finds all lines that contain both @samp{paul} and @samp{franc,ois}.
1167 How can I search in both standard input and in files?
1169 Use the special file name @samp{-}:
1172 cat /etc/passwd | grep 'alain' - /etc/motd
1177 How to express palindromes in a regular expression?
1179 It can be done by using the back referecences, for example a palindrome
1180 of 4 chararcters can be written in BRE.
1183 grep -w -e '\(.\)\(.\).\2\1' file
1186 It matches the word "radar" or "civic".
1188 Guglielmo Bondioni proposed a single RE that finds all the palindromes up to 19
1192 egrep -e '^(.?)(.?)(.?)(.?)(.?)(.?)(.?)(.?)(.?).?\9\8\7\6\5\4\3\2\1$' file
1195 Note this is done by using GNU ERE extensions, it might not be portable on
1199 Why are my expressions whith the vertical bar fail?
1202 /bin/echo "ba" | egrep '(a)\1|(b)\1'
1205 The first alternate branch fails then the first group was not in the match
1206 this will make the second alternate branch fails. For example, "aaba" will
1207 match, the first group participate in the match and can be reuse in the
1211 What do @command{grep, fgrep, egrep} stand for ?
1213 grep comes from the way line editing was done on Unix. For example,
1214 @command{ed} uses this syntax to print a list of matching lines on the screen.
1217 global/regular expression/print
1221 @command{fgrep} stands for Fixed @command{grep}, @command{egrep} Extended
1226 @node Reporting Bugs, Copying, Usage, Top
1227 @chapter Reporting bugs
1229 @cindex Bugs, reporting
1230 Email bug reports to @email{bug-gnu-utils@@gnu.org}.
1231 Be sure to include the word ``grep'' somewhere in the ``Subject:'' field.
1233 Large repetition counts in the @samp{@{n,m@}} construct may cause
1234 @command{grep} to use lots of memory. In addition, certain other
1235 obscure regular expressions require exponential time and
1236 space, and may cause grep to run out of memory.
1237 Back-references are very slow, and may require exponential time.
1239 @node Copying, GNU General Public License, Reporting Bugs, Top
1242 GNU grep is licensed under the GNU GPL, which makes it @dfn{free
1245 Please note that ``free'' in ``free software'' refers to liberty, not
1246 price. As some GNU project advocates like to point out, think of ``free
1247 speech'' rather than ``free beer''. The exact and legally binding
1248 distribution terms are spelled out below; in short, you have the right
1249 (freedom) to run and change grep and distribute it to other people, and
1250 even---if you want---charge money for doing either. The important
1251 restriction is that you have to grant your recipients the same rights
1252 and impose the same restrictions.
1254 This method of licensing software is also known as @dfn{open source}
1255 because, among other things, it makes sure that all recipients will
1256 receive the source code along with the program, and be able to improve
1257 it. The GNU project prefers the term ``free software'' for reasons
1259 @url{http://www.gnu.org/philosophy/free-software-for-freedom.html}.
1261 The exact license terms are defined by this paragraph and the GNU
1262 General Public License it refers to:
1265 GNU grep is free software; you can redistribute it and/or modify it
1266 under the terms of the GNU General Public License as published by the
1267 Free Software Foundation; either version 2 of the License, or (at your
1268 option) any later version.
1270 GNU grep is distributed in the hope that it will be useful, but WITHOUT
1271 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
1272 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
1275 A copy of the GNU General Public License is included as part of this
1276 manual; if you did not receive it, write to the Free Software
1277 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
1280 In addition to this, this manual is free in the same sense:
1283 Permission is granted to copy, distribute and/or modify this document
1284 under the terms of the GNU Free Documentation License, Version 1.1 or
1285 any later version published by the Free Software Foundation; with the
1286 Invariant Sections being ``GNU General Public License'' and ``GNU Free
1287 Documentation License'', with no Front-Cover Texts, and with no
1288 Back-Cover Texts. A copy of the license is included in the section
1289 entitled ``GNU Free Documentation License''.
1292 @c #### Maybe we should wrap these licenses in ifinfo? Stallman says
1293 @c that the GFDL needs to be present in the manual, and to me it would
1294 @c suck to include the license for the manual and not the license for
1297 The full texts of the GNU General Public License and of the GNU Free
1298 Documentation License are available below.
1301 * GNU General Public License:: GNU GPL
1302 * GNU Free Documentation License:: GNU FDL
1305 @node GNU General Public License, GNU Free Documentation License, Copying, Copying
1306 @section GNU General Public License
1307 @center Version 2, June 1991
1308 @cindex GPL, GNU General Public License
1311 Copyright @copyright{} 1989, 1991 Free Software Foundation, Inc.
1312 675 Mass Ave, Cambridge, MA 02139, USA
1314 Everyone is permitted to copy and distribute verbatim copies
1315 of this license document, but changing it is not allowed.
1318 @unnumberedsec Preamble
1320 The licenses for most software are designed to take away your
1321 freedom to share and change it. By contrast, the GNU General Public
1322 License is intended to guarantee your freedom to share and change free
1323 software---to make sure the software is free for all its users. This
1324 General Public License applies to most of the Free Software
1325 Foundation's software and to any other program whose authors commit to
1326 using it. (Some other Free Software Foundation software is covered by
1327 the GNU Library General Public License instead.) You can apply it to
1330 When we speak of free software, we are referring to freedom, not
1331 price. Our General Public Licenses are designed to make sure that you
1332 have the freedom to distribute copies of free software (and charge for
1333 this service if you wish), that you receive source code or can get it
1334 if you want it, that you can change the software or use pieces of it
1335 in new free programs; and that you know you can do these things.
1337 To protect your rights, we need to make restrictions that forbid
1338 anyone to deny you these rights or to ask you to surrender the rights.
1339 These restrictions translate to certain responsibilities for you if you
1340 distribute copies of the software, or if you modify it.
1342 For example, if you distribute copies of such a program, whether
1343 gratis or for a fee, you must give the recipients all the rights that
1344 you have. You must make sure that they, too, receive or can get the
1345 source code. And you must show them these terms so they know their
1348 We protect your rights with two steps: (1) copyright the software, and
1349 (2) offer you this license which gives you legal permission to copy,
1350 distribute and/or modify the software.
1352 Also, for each author's protection and ours, we want to make certain
1353 that everyone understands that there is no warranty for this free
1354 software. If the software is modified by someone else and passed on, we
1355 want its recipients to know that what they have is not the original, so
1356 that any problems introduced by others will not reflect on the original
1357 authors' reputations.
1359 Finally, any free program is threatened constantly by software
1360 patents. We wish to avoid the danger that redistributors of a free
1361 program will individually obtain patent licenses, in effect making the
1362 program proprietary. To prevent this, we have made it clear that any
1363 patent must be licensed for everyone's free use or not licensed at all.
1365 The precise terms and conditions for copying, distribution and
1366 modification follow.
1369 @unnumberedsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
1372 @center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
1377 This License applies to any program or other work which contains
1378 a notice placed by the copyright holder saying it may be distributed
1379 under the terms of this General Public License. The ``Program'', below,
1380 refers to any such program or work, and a ``work based on the Program''
1381 means either the Program or any derivative work under copyright law:
1382 that is to say, a work containing the Program or a portion of it,
1383 either verbatim or with modifications and/or translated into another
1384 language. (Hereinafter, translation is included without limitation in
1385 the term ``modification''.) Each licensee is addressed as ``you''.
1387 Activities other than copying, distribution and modification are not
1388 covered by this License; they are outside its scope. The act of
1389 running the Program is not restricted, and the output from the Program
1390 is covered only if its contents constitute a work based on the
1391 Program (independent of having been made by running the Program).
1392 Whether that is true depends on what the Program does.
1395 You may copy and distribute verbatim copies of the Program's
1396 source code as you receive it, in any medium, provided that you
1397 conspicuously and appropriately publish on each copy an appropriate
1398 copyright notice and disclaimer of warranty; keep intact all the
1399 notices that refer to this License and to the absence of any warranty;
1400 and give any other recipients of the Program a copy of this License
1401 along with the Program.
1403 You may charge a fee for the physical act of transferring a copy, and
1404 you may at your option offer warranty protection in exchange for a fee.
1407 You may modify your copy or copies of the Program or any portion
1408 of it, thus forming a work based on the Program, and copy and
1409 distribute such modifications or work under the terms of Section 1
1410 above, provided that you also meet all of these conditions:
1414 You must cause the modified files to carry prominent notices
1415 stating that you changed the files and the date of any change.
1418 You must cause any work that you distribute or publish, that in
1419 whole or in part contains or is derived from the Program or any
1420 part thereof, to be licensed as a whole at no charge to all third
1421 parties under the terms of this License.
1424 If the modified program normally reads commands interactively
1425 when run, you must cause it, when started running for such
1426 interactive use in the most ordinary way, to print or display an
1427 announcement including an appropriate copyright notice and a
1428 notice that there is no warranty (or else, saying that you provide
1429 a warranty) and that users may redistribute the program under
1430 these conditions, and telling the user how to view a copy of this
1431 License. (Exception: if the Program itself is interactive but
1432 does not normally print such an announcement, your work based on
1433 the Program is not required to print an announcement.)
1436 These requirements apply to the modified work as a whole. If
1437 identifiable sections of that work are not derived from the Program,
1438 and can be reasonably considered independent and separate works in
1439 themselves, then this License, and its terms, do not apply to those
1440 sections when you distribute them as separate works. But when you
1441 distribute the same sections as part of a whole which is a work based
1442 on the Program, the distribution of the whole must be on the terms of
1443 this License, whose permissions for other licensees extend to the
1444 entire whole, and thus to each and every part regardless of who wrote it.
1446 Thus, it is not the intent of this section to claim rights or contest
1447 your rights to work written entirely by you; rather, the intent is to
1448 exercise the right to control the distribution of derivative or
1449 collective works based on the Program.
1451 In addition, mere aggregation of another work not based on the Program
1452 with the Program (or with a work based on the Program) on a volume of
1453 a storage or distribution medium does not bring the other work under
1454 the scope of this License.
1457 You may copy and distribute the Program (or a work based on it,
1458 under Section 2) in object code or executable form under the terms of
1459 Sections 1 and 2 above provided that you also do one of the following:
1463 Accompany it with the complete corresponding machine-readable
1464 source code, which must be distributed under the terms of Sections
1465 1 and 2 above on a medium customarily used for software interchange; or,
1468 Accompany it with a written offer, valid for at least three
1469 years, to give any third party, for a charge no more than your
1470 cost of physically performing source distribution, a complete
1471 machine-readable copy of the corresponding source code, to be
1472 distributed under the terms of Sections 1 and 2 above on a medium
1473 customarily used for software interchange; or,
1476 Accompany it with the information you received as to the offer
1477 to distribute corresponding source code. (This alternative is
1478 allowed only for noncommercial distribution and only if you
1479 received the program in object code or executable form with such
1480 an offer, in accord with Subsection b above.)
1483 The source code for a work means the preferred form of the work for
1484 making modifications to it. For an executable work, complete source
1485 code means all the source code for all modules it contains, plus any
1486 associated interface definition files, plus the scripts used to
1487 control compilation and installation of the executable. However, as a
1488 special exception, the source code distributed need not include
1489 anything that is normally distributed (in either source or binary
1490 form) with the major components (compiler, kernel, and so on) of the
1491 operating system on which the executable runs, unless that component
1492 itself accompanies the executable.
1494 If distribution of executable or object code is made by offering
1495 access to copy from a designated place, then offering equivalent
1496 access to copy the source code from the same place counts as
1497 distribution of the source code, even though third parties are not
1498 compelled to copy the source along with the object code.
1501 You may not copy, modify, sublicense, or distribute the Program
1502 except as expressly provided under this License. Any attempt
1503 otherwise to copy, modify, sublicense or distribute the Program is
1504 void, and will automatically terminate your rights under this License.
1505 However, parties who have received copies, or rights, from you under
1506 this License will not have their licenses terminated so long as such
1507 parties remain in full compliance.
1510 You are not required to accept this License, since you have not
1511 signed it. However, nothing else grants you permission to modify or
1512 distribute the Program or its derivative works. These actions are
1513 prohibited by law if you do not accept this License. Therefore, by
1514 modifying or distributing the Program (or any work based on the
1515 Program), you indicate your acceptance of this License to do so, and
1516 all its terms and conditions for copying, distributing or modifying
1517 the Program or works based on it.
1520 Each time you redistribute the Program (or any work based on the
1521 Program), the recipient automatically receives a license from the
1522 original licensor to copy, distribute or modify the Program subject to
1523 these terms and conditions. You may not impose any further
1524 restrictions on the recipients' exercise of the rights granted herein.
1525 You are not responsible for enforcing compliance by third parties to
1529 If, as a consequence of a court judgment or allegation of patent
1530 infringement or for any other reason (not limited to patent issues),
1531 conditions are imposed on you (whether by court order, agreement or
1532 otherwise) that contradict the conditions of this License, they do not
1533 excuse you from the conditions of this License. If you cannot
1534 distribute so as to satisfy simultaneously your obligations under this
1535 License and any other pertinent obligations, then as a consequence you
1536 may not distribute the Program at all. For example, if a patent
1537 license would not permit royalty-free redistribution of the Program by
1538 all those who receive copies directly or indirectly through you, then
1539 the only way you could satisfy both it and this License would be to
1540 refrain entirely from distribution of the Program.
1542 If any portion of this section is held invalid or unenforceable under
1543 any particular circumstance, the balance of the section is intended to
1544 apply and the section as a whole is intended to apply in other
1547 It is not the purpose of this section to induce you to infringe any
1548 patents or other property right claims or to contest validity of any
1549 such claims; this section has the sole purpose of protecting the
1550 integrity of the free software distribution system, which is
1551 implemented by public license practices. Many people have made
1552 generous contributions to the wide range of software distributed
1553 through that system in reliance on consistent application of that
1554 system; it is up to the author/donor to decide if he or she is willing
1555 to distribute software through any other system and a licensee cannot
1558 This section is intended to make thoroughly clear what is believed to
1559 be a consequence of the rest of this License.
1562 If the distribution and/or use of the Program is restricted in
1563 certain countries either by patents or by copyrighted interfaces, the
1564 original copyright holder who places the Program under this License
1565 may add an explicit geographical distribution limitation excluding
1566 those countries, so that distribution is permitted only in or among
1567 countries not thus excluded. In such case, this License incorporates
1568 the limitation as if written in the body of this License.
1571 The Free Software Foundation may publish revised and/or new versions
1572 of the General Public License from time to time. Such new versions will
1573 be similar in spirit to the present version, but may differ in detail to
1574 address new problems or concerns.
1576 Each version is given a distinguishing version number. If the Program
1577 specifies a version number of this License which applies to it and ``any
1578 later version'', you have the option of following the terms and conditions
1579 either of that version or of any later version published by the Free
1580 Software Foundation. If the Program does not specify a version number of
1581 this License, you may choose any version ever published by the Free Software
1585 If you wish to incorporate parts of the Program into other free
1586 programs whose distribution conditions are different, write to the author
1587 to ask for permission. For software which is copyrighted by the Free
1588 Software Foundation, write to the Free Software Foundation; we sometimes
1589 make exceptions for this. Our decision will be guided by the two goals
1590 of preserving the free status of all derivatives of our free software and
1591 of promoting the sharing and reuse of software generally.
1594 @heading NO WARRANTY
1602 BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
1603 FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
1604 OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
1605 PROVIDE THE PROGRAM ``AS IS'' WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
1606 OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
1607 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS
1608 TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
1609 PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
1610 REPAIR OR CORRECTION.
1613 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
1614 WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
1615 REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
1616 INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
1617 OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
1618 TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
1619 YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
1620 PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
1621 POSSIBILITY OF SUCH DAMAGES.
1625 @heading END OF TERMS AND CONDITIONS
1628 @center END OF TERMS AND CONDITIONS
1632 @unnumberedsec How to Apply These Terms to Your New Programs
1634 If you develop a new program, and you want it to be of the greatest
1635 possible use to the public, the best way to achieve this is to make it
1636 free software which everyone can redistribute and change under these terms.
1638 To do so, attach the following notices to the program. It is safest
1639 to attach them to the start of each source file to most effectively
1640 convey the exclusion of warranty; and each file should have at least
1641 the ``copyright'' line and a pointer to where the full notice is found.
1644 @var{one line to give the program's name and an idea of what it does.}
1645 Copyright (C) 19@var{yy} @var{name of author}
1647 This program is free software; you can redistribute it and/or
1648 modify it under the terms of the GNU General Public License
1649 as published by the Free Software Foundation; either version 2
1650 of the License, or (at your option) any later version.
1652 This program is distributed in the hope that it will be useful,
1653 but WITHOUT ANY WARRANTY; without even the implied warranty of
1654 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
1655 GNU General Public License for more details.
1657 You should have received a copy of the GNU General Public License
1658 along with this program; if not, write to the Free Software
1659 Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
1662 Also add information on how to contact you by electronic and paper mail.
1664 If the program is interactive, make it output a short notice like this
1665 when it starts in an interactive mode:
1668 Gnomovision version 69, Copyright (C) 19@var{yy} @var{name of author}
1669 Gnomovision comes with ABSOLUTELY NO WARRANTY; for details
1670 type `show w'. This is free software, and you are welcome
1671 to redistribute it under certain conditions; type `show c'
1675 The hypothetical commands @samp{show w} and @samp{show c} should show
1676 the appropriate parts of the General Public License. Of course, the
1677 commands you use may be called something other than @samp{show w} and
1678 @samp{show c}; they could even be mouse-clicks or menu items---whatever
1681 You should also get your employer (if you work as a programmer) or your
1682 school, if any, to sign a ``copyright disclaimer'' for the program, if
1683 necessary. Here is a sample; alter the names:
1687 Yoyodyne, Inc., hereby disclaims all copyright
1688 interest in the program `Gnomovision'
1689 (which makes passes at compilers) written
1692 @var{signature of Ty Coon}, 1 April 1989
1693 Ty Coon, President of Vice
1697 This General Public License does not permit incorporating your program into
1698 proprietary programs. If your program is a subroutine library, you may
1699 consider it more useful to permit linking proprietary applications with the
1700 library. If this is what you want to do, use the GNU Library General
1701 Public License instead of this License.
1703 @node GNU Free Documentation License, Concept Index, GNU General Public License, Copying
1704 @section GNU Free Documentation License
1705 @center Version 1.1, March 2000
1706 @cindex FDL, GNU Free Documentation License
1709 Copyright (C) 2000 Free Software Foundation, Inc.
1710 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
1712 Everyone is permitted to copy and distribute verbatim copies
1713 of this license document, but changing it is not allowed.
1720 The purpose of this License is to make a manual, textbook, or other
1721 written document ``free'' in the sense of freedom: to assure everyone
1722 the effective freedom to copy and redistribute it, with or without
1723 modifying it, either commercially or noncommercially. Secondarily,
1724 this License preserves for the author and publisher a way to get
1725 credit for their work, while not being considered responsible for
1726 modifications made by others.
1728 This License is a kind of ``copyleft'', which means that derivative
1729 works of the document must themselves be free in the same sense. It
1730 complements the GNU General Public License, which is a copyleft
1731 license designed for free software.
1733 We have designed this License in order to use it for manuals for free
1734 software, because free software needs free documentation: a free
1735 program should come with manuals providing the same freedoms that the
1736 software does. But this License is not limited to software manuals;
1737 it can be used for any textual work, regardless of subject matter or
1738 whether it is published as a printed book. We recommend this License
1739 principally for works whose purpose is instruction or reference.
1743 APPLICABILITY AND DEFINITIONS
1745 This License applies to any manual or other work that contains a
1746 notice placed by the copyright holder saying it can be distributed
1747 under the terms of this License. The ``Document'', below, refers to any
1748 such manual or work. Any member of the public is a licensee, and is
1749 addressed as ``you''.
1751 A ``Modified Version'' of the Document means any work containing the
1752 Document or a portion of it, either copied verbatim, or with
1753 modifications and/or translated into another language.
1755 A ``Secondary Section'' is a named appendix or a front-matter section of
1756 the Document that deals exclusively with the relationship of the
1757 publishers or authors of the Document to the Document's overall subject
1758 (or to related matters) and contains nothing that could fall directly
1759 within that overall subject. (For example, if the Document is in part a
1760 textbook of mathematics, a Secondary Section may not explain any
1761 mathematics.) The relationship could be a matter of historical
1762 connection with the subject or with related matters, or of legal,
1763 commercial, philosophical, ethical or political position regarding
1766 The ``Invariant Sections'' are certain Secondary Sections whose titles
1767 are designated, as being those of Invariant Sections, in the notice
1768 that says that the Document is released under this License.
1770 The ``Cover Texts'' are certain short passages of text that are listed,
1771 as Front-Cover Texts or Back-Cover Texts, in the notice that says that
1772 the Document is released under this License.
1774 A ``Transparent'' copy of the Document means a machine-readable copy,
1775 represented in a format whose specification is available to the
1776 general public, whose contents can be viewed and edited directly and
1777 straightforwardly with generic text editors or (for images composed of
1778 pixels) generic paint programs or (for drawings) some widely available
1779 drawing editor, and that is suitable for input to text formatters or
1780 for automatic translation to a variety of formats suitable for input
1781 to text formatters. A copy made in an otherwise Transparent file
1782 format whose markup has been designed to thwart or discourage
1783 subsequent modification by readers is not Transparent. A copy that is
1784 not ``Transparent'' is called ``Opaque''.
1786 Examples of suitable formats for Transparent copies include plain
1787 ASCII without markup, Texinfo input format, LaTeX input format, SGML
1788 or XML using a publicly available DTD, and standard-conforming simple
1789 HTML designed for human modification. Opaque formats include
1790 PostScript, PDF, proprietary formats that can be read and edited only
1791 by proprietary word processors, SGML or XML for which the DTD and/or
1792 processing tools are not generally available, and the
1793 machine-generated HTML produced by some word processors for output
1796 The ``Title Page'' means, for a printed book, the title page itself,
1797 plus such following pages as are needed to hold, legibly, the material
1798 this License requires to appear in the title page. For works in
1799 formats which do not have any title page as such, ``Title Page'' means
1800 the text near the most prominent appearance of the work's title,
1801 preceding the beginning of the body of the text.
1806 You may copy and distribute the Document in any medium, either
1807 commercially or noncommercially, provided that this License, the
1808 copyright notices, and the license notice saying this License applies
1809 to the Document are reproduced in all copies, and that you add no other
1810 conditions whatsoever to those of this License. You may not use
1811 technical measures to obstruct or control the reading or further
1812 copying of the copies you make or distribute. However, you may accept
1813 compensation in exchange for copies. If you distribute a large enough
1814 number of copies you must also follow the conditions in section 3.
1816 You may also lend copies, under the same conditions stated above, and
1817 you may publicly display copies.
1822 If you publish printed copies of the Document numbering more than 100,
1823 and the Document's license notice requires Cover Texts, you must enclose
1824 the copies in covers that carry, clearly and legibly, all these Cover
1825 Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
1826 the back cover. Both covers must also clearly and legibly identify
1827 you as the publisher of these copies. The front cover must present
1828 the full title with all words of the title equally prominent and
1829 visible. You may add other material on the covers in addition.
1830 Copying with changes limited to the covers, as long as they preserve
1831 the title of the Document and satisfy these conditions, can be treated
1832 as verbatim copying in other respects.
1834 If the required texts for either cover are too voluminous to fit
1835 legibly, you should put the first ones listed (as many as fit
1836 reasonably) on the actual cover, and continue the rest onto adjacent
1839 If you publish or distribute Opaque copies of the Document numbering
1840 more than 100, you must either include a machine-readable Transparent
1841 copy along with each Opaque copy, or state in or with each Opaque copy
1842 a publicly-accessible computer-network location containing a complete
1843 Transparent copy of the Document, free of added material, which the
1844 general network-using public has access to download anonymously at no
1845 charge using public-standard network protocols. If you use the latter
1846 option, you must take reasonably prudent steps, when you begin
1847 distribution of Opaque copies in quantity, to ensure that this
1848 Transparent copy will remain thus accessible at the stated location
1849 until at least one year after the last time you distribute an Opaque
1850 copy (directly or through your agents or retailers) of that edition to
1853 It is requested, but not required, that you contact the authors of the
1854 Document well before redistributing any large number of copies, to give
1855 them a chance to provide you with an updated version of the Document.
1860 You may copy and distribute a Modified Version of the Document under
1861 the conditions of sections 2 and 3 above, provided that you release
1862 the Modified Version under precisely this License, with the Modified
1863 Version filling the role of the Document, thus licensing distribution
1864 and modification of the Modified Version to whoever possesses a copy
1865 of it. In addition, you must do these things in the Modified Version:
1867 A. Use in the Title Page (and on the covers, if any) a title distinct
1868 from that of the Document, and from those of previous versions
1869 (which should, if there were any, be listed in the History section
1870 of the Document). You may use the same title as a previous version
1871 if the original publisher of that version gives permission.@*
1872 B. List on the Title Page, as authors, one or more persons or entities
1873 responsible for authorship of the modifications in the Modified
1874 Version, together with at least five of the principal authors of the
1875 Document (all of its principal authors, if it has less than five).@*
1876 C. State on the Title page the name of the publisher of the
1877 Modified Version, as the publisher.@*
1878 D. Preserve all the copyright notices of the Document.@*
1879 E. Add an appropriate copyright notice for your modifications
1880 adjacent to the other copyright notices.@*
1881 F. Include, immediately after the copyright notices, a license notice
1882 giving the public permission to use the Modified Version under the
1883 terms of this License, in the form shown in the Addendum below.@*
1884 G. Preserve in that license notice the full lists of Invariant Sections
1885 and required Cover Texts given in the Document's license notice.@*
1886 H. Include an unaltered copy of this License.@*
1887 I. Preserve the section entitled ``History'', and its title, and add to
1888 it an item stating at least the title, year, new authors, and
1889 publisher of the Modified Version as given on the Title Page. If
1890 there is no section entitled ``History'' in the Document, create one
1891 stating the title, year, authors, and publisher of the Document as
1892 given on its Title Page, then add an item describing the Modified
1893 Version as stated in the previous sentence.@*
1894 J. Preserve the network location, if any, given in the Document for
1895 public access to a Transparent copy of the Document, and likewise
1896 the network locations given in the Document for previous versions
1897 it was based on. These may be placed in the ``History'' section.
1898 You may omit a network location for a work that was published at
1899 least four years before the Document itself, or if the original
1900 publisher of the version it refers to gives permission.@*
1901 K. In any section entitled ``Acknowledgements'' or ``Dedications'',
1902 preserve the section's title, and preserve in the section all the
1903 substance and tone of each of the contributor acknowledgements
1904 and/or dedications given therein.@*
1905 L. Preserve all the Invariant Sections of the Document,
1906 unaltered in their text and in their titles. Section numbers
1907 or the equivalent are not considered part of the section titles.@*
1908 M. Delete any section entitled ``Endorsements''. Such a section
1909 may not be included in the Modified Version.@*
1910 N. Do not retitle any existing section as ``Endorsements''
1911 or to conflict in title with any Invariant Section.@*
1913 If the Modified Version includes new front-matter sections or
1914 appendices that qualify as Secondary Sections and contain no material
1915 copied from the Document, you may at your option designate some or all
1916 of these sections as invariant. To do this, add their titles to the
1917 list of Invariant Sections in the Modified Version's license notice.
1918 These titles must be distinct from any other section titles.
1920 You may add a section entitled ``Endorsements'', provided it contains
1921 nothing but endorsements of your Modified Version by various
1922 parties--for example, statements of peer review or that the text has
1923 been approved by an organization as the authoritative definition of a
1926 You may add a passage of up to five words as a Front-Cover Text, and a
1927 passage of up to 25 words as a Back-Cover Text, to the end of the list
1928 of Cover Texts in the Modified Version. Only one passage of
1929 Front-Cover Text and one of Back-Cover Text may be added by (or
1930 through arrangements made by) any one entity. If the Document already
1931 includes a cover text for the same cover, previously added by you or
1932 by arrangement made by the same entity you are acting on behalf of,
1933 you may not add another; but you may replace the old one, on explicit
1934 permission from the previous publisher that added the old one.
1936 The author(s) and publisher(s) of the Document do not by this License
1937 give permission to use their names for publicity for or to assert or
1938 imply endorsement of any Modified Version.
1943 You may combine the Document with other documents released under this
1944 License, under the terms defined in section 4 above for modified
1945 versions, provided that you include in the combination all of the
1946 Invariant Sections of all of the original documents, unmodified, and
1947 list them all as Invariant Sections of your combined work in its
1950 The combined work need only contain one copy of this License, and
1951 multiple identical Invariant Sections may be replaced with a single
1952 copy. If there are multiple Invariant Sections with the same name but
1953 different contents, make the title of each such section unique by
1954 adding at the end of it, in parentheses, the name of the original
1955 author or publisher of that section if known, or else a unique number.
1956 Make the same adjustment to the section titles in the list of
1957 Invariant Sections in the license notice of the combined work.
1959 In the combination, you must combine any sections entitled ``History''
1960 in the various original documents, forming one section entitled
1961 ``History''; likewise combine any sections entitled ``Acknowledgements'',
1962 and any sections entitled ``Dedications''. You must delete all sections
1963 entitled ``Endorsements.''
1966 COLLECTIONS OF DOCUMENTS
1968 You may make a collection consisting of the Document and other documents
1969 released under this License, and replace the individual copies of this
1970 License in the various documents with a single copy that is included in
1971 the collection, provided that you follow the rules of this License for
1972 verbatim copying of each of the documents in all other respects.
1974 You may extract a single document from such a collection, and distribute
1975 it individually under this License, provided you insert a copy of this
1976 License into the extracted document, and follow this License in all
1977 other respects regarding verbatim copying of that document.
1980 AGGREGATION WITH INDEPENDENT WORKS
1982 A compilation of the Document or its derivatives with other separate
1983 and independent documents or works, in or on a volume of a storage or
1984 distribution medium, does not as a whole count as a Modified Version
1985 of the Document, provided no compilation copyright is claimed for the
1986 compilation. Such a compilation is called an ``aggregate'', and this
1987 License does not apply to the other self-contained works thus compiled
1988 with the Document, on account of their being thus compiled, if they
1989 are not themselves derivative works of the Document.
1991 If the Cover Text requirement of section 3 is applicable to these
1992 copies of the Document, then if the Document is less than one quarter
1993 of the entire aggregate, the Document's Cover Texts may be placed on
1994 covers that surround only the Document within the aggregate.
1995 Otherwise they must appear on covers around the whole aggregate.
2000 Translation is considered a kind of modification, so you may
2001 distribute translations of the Document under the terms of section 4.
2002 Replacing Invariant Sections with translations requires special
2003 permission from their copyright holders, but you may include
2004 translations of some or all Invariant Sections in addition to the
2005 original versions of these Invariant Sections. You may include a
2006 translation of this License provided that you also include the
2007 original English version of this License. In case of a disagreement
2008 between the translation and the original English version of this
2009 License, the original English version will prevail.
2014 You may not copy, modify, sublicense, or distribute the Document except
2015 as expressly provided for under this License. Any other attempt to
2016 copy, modify, sublicense or distribute the Document is void, and will
2017 automatically terminate your rights under this License. However,
2018 parties who have received copies, or rights, from you under this
2019 License will not have their licenses terminated so long as such
2020 parties remain in full compliance.
2023 FUTURE REVISIONS OF THIS LICENSE
2025 The Free Software Foundation may publish new, revised versions
2026 of the GNU Free Documentation License from time to time. Such new
2027 versions will be similar in spirit to the present version, but may
2028 differ in detail to address new problems or concerns. See
2029 http://www.gnu.org/copyleft/.
2031 Each version of the License is given a distinguishing version number.
2032 If the Document specifies that a particular numbered version of this
2033 License ``or any later version'' applies to it, you have the option of
2034 following the terms and conditions either of that specified version or
2035 of any later version that has been published (not as a draft) by the
2036 Free Software Foundation. If the Document does not specify a version
2037 number of this License, you may choose any version ever published (not
2038 as a draft) by the Free Software Foundation.
2042 @unnumberedsec ADDENDUM: How to use this License for your documents
2044 To use this License in a document you have written, include a copy of
2045 the License in the document and put the following copyright and
2046 license notices just after the title page:
2051 Copyright (C) @var{year} @var{your name}.
2052 Permission is granted to copy, distribute and/or modify this document
2053 under the terms of the GNU Free Documentation License, Version 1.1
2054 or any later version published by the Free Software Foundation;
2055 with the Invariant Sections being @var{list their titles}, with the
2056 Front-Cover Texts being @var{list}, and with the Back-Cover Texts being @var{list}.
2057 A copy of the license is included in the section entitled ``GNU
2058 Free Documentation License''.
2061 If you have no Invariant Sections, write ``with no Invariant Sections''
2062 instead of saying which ones are invariant. If you have no
2063 Front-Cover Texts, write ``no Front-Cover Texts'' instead of
2064 ``Front-Cover Texts being @var{list}''; likewise for Back-Cover Texts.
2066 If your document contains nontrivial examples of program code, we
2067 recommend releasing these examples in parallel under your choice of
2068 free software license, such as the GNU General Public License,
2069 to permit their use in free software.
2072 @node Concept Index, Index, GNU Free Documentation License, Top
2073 @unnumbered Concept Index
2075 This is a general index of all issues discussed in this manual, with the
2076 exception of the @command{grep} commands and command-line options.
2081 @node Index,, Concept Index, Top
2084 This is an alphabetical list of all @command{grep} commands, command-line
2085 options, and environment variables.