Changes to grep/manual/html_node/Usage.html,v

[Jim Meyering]

CVSROOT:        /webcvs/grep
Module name:    grep
Changes by:     Jim Meyering <meyering> 22/09/03 15:33:15

Index: html_node/Usage.html
===================================================================
RCS file: /webcvs/grep/grep/manual/html_node/Usage.html,v
retrieving revision 1.32
retrieving revision 1.33
diff -u -b -r1.32 -r1.33
--- html_node/Usage.html        14 Aug 2021 20:46:41 -0000      1.32
+++ html_node/Usage.html        3 Sep 2022 19:33:14 -0000       1.33
@@ -5,7 +5,7 @@
 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
 <!-- This manual is for grep, a pattern matching engine.
 
-Copyright (C) 1999-2002, 2005, 2008-2021 Free Software Foundation,
+Copyright (C) 1999-2002, 2005, 2008-2022 Free Software Foundation,
 Inc.
 
 Permission is granted to copy, distribute and/or modify this document
@@ -14,10 +14,10 @@
 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
 Texts.  A copy of the license is included in the section entitled
 "GNU Free Documentation License". -->
-<title>Usage (GNU Grep 3.7)</title>
+<title>Usage (GNU Grep 3.8)</title>
 
-<meta name="description" content="Usage (GNU Grep 3.7)">
-<meta name="keywords" content="Usage (GNU Grep 3.7)">
+<meta name="description" content="Usage (GNU Grep 3.8)">
+<meta name="keywords" content="Usage (GNU Grep 3.8)">
 <meta name="resource-type" content="document">
 <meta name="distribution" content="global">
 <meta name="Generator" content="makeinfo">
@@ -144,24 +144,36 @@
 </pre></div>
 
 </li><li> What if a pattern or file has a leading &lsquo;<samp>-</samp>&rsquo;?
+For example:
 
 <div class="example">
-<pre class="example">grep -- '--cut here--' *
+<pre class="example">grep &quot;$pattern&quot; *
 </pre></div>
 
-<p>searches for all lines matching &lsquo;<samp>--cut here--</samp>&rsquo;.
-Without <samp>--</samp>,
-<code>grep</code> would attempt to parse &lsquo;<samp>--cut 
here--</samp>&rsquo; as a list of
-options, and there would be similar problems with any file names
-beginning with &lsquo;<samp>-</samp>&rsquo;.
+<p>can behave unexpectedly if the value of &lsquo;<samp>pattern</samp>&rsquo; 
begins with &lsquo;<samp>-</samp>&rsquo;,
+or if the &lsquo;<samp>*</samp>&rsquo; expands to a file name with leading 
&lsquo;<samp>-</samp>&rsquo;.
+To avoid the problem, you can use <samp>-e</samp> for patterns and leading
+&lsquo;<samp>./</samp>&rsquo; for files:
 </p>
-<p>Alternatively, you can prevent misinterpretation of leading 
&lsquo;<samp>-</samp>&rsquo;
-by using <samp>-e</samp> for patterns and leading 
&lsquo;<samp>./</samp>&rsquo; for files:
+<div class="example">
+<pre class="example">grep -e &quot;$pattern&quot; ./*
+</pre></div>
+
+<p>searches for all lines matching the pattern in all the working
+directory&rsquo;s files whose names do not begin with 
&lsquo;<samp>.</samp>&rsquo;.
+Without the <samp>-e</samp>, <code>grep</code> might treat the pattern as an
+option if it begins with &lsquo;<samp>-</samp>&rsquo;.  Without the 
&lsquo;<samp>./</samp>&rsquo;, there might
+be similar problems with file names beginning with 
&lsquo;<samp>-</samp>&rsquo;.
+</p>
+<p>Alternatively, you can use &lsquo;<samp>--</samp>&rsquo; before the pattern 
and file names:
 </p>
 <div class="example">
-<pre class="example">grep -e '--cut here--' ./*
+<pre class="example">grep -- &quot;$pattern&quot; *
 </pre></div>
 
+<p>This also fixes the problem, except that if there is a file named 
&lsquo;<samp>-</samp>&rsquo;,
+<code>grep</code> misinterprets the &lsquo;<samp>-</samp>&rsquo; as standard 
input.
+</p>
 </li><li> Suppose I want to search for a whole word, not a part of a word?
 
 <div class="example">
@@ -235,8 +247,7 @@
 <samp>-a</samp> or &lsquo;<samp>--binary-files=text</samp>&rsquo; option.
 To eliminate the
 &ldquo;Binary file matches&rdquo; messages, use the <samp>-I</samp> or
-&lsquo;<samp>--binary-files=without-match</samp>&rsquo; option,
-or the <samp>-s</samp> or <samp>--no-messages</samp> option.
+&lsquo;<samp>--binary-files=without-match</samp>&rsquo; option.
 </p>
 </li><li> Why doesn&rsquo;t &lsquo;<samp>grep -lv</samp>&rsquo; print 
non-matching file names?
 
@@ -264,7 +275,10 @@
 </p>
 <p>To match empty lines, use the pattern &lsquo;<samp>^$</samp>&rsquo;.  To 
match blank
 lines, use the pattern &lsquo;<samp>^[[:blank:]]*$</samp>&rsquo;.  To match no 
lines at
-all, use the command &lsquo;<samp>grep -f /dev/null</samp>&rsquo;.
+all, use an extended regular expression like &lsquo;<samp>a^</samp>&rsquo; or 
&lsquo;<samp>$a</samp>&rsquo;.
+To match every line, a portable script should use a pattern like
+&lsquo;<samp>^</samp>&rsquo; instead of the empty pattern, as POSIX does not 
specify the
+behavior of the empty pattern.
 </p>
 </li><li> How can I search in both standard input and in files?
 
@@ -274,6 +288,21 @@
 <pre class="example">cat /etc/passwd | grep 'alain' - /etc/motd
 </pre></div>
 
+</li><li> Why can&rsquo;t I combine the shell&rsquo;s &lsquo;<samp>set 
-e</samp>&rsquo; with <code>grep</code>?
+
+<p>The <code>grep</code> command follows the convention of programs like
+<code>cmp</code> and <code>diff</code> where an exit status of 1 is not an
+error.  The shell command &lsquo;<samp>set -e</samp>&rsquo; causes the shell 
to exit if
+any subcommand exits with nonzero status, and this will cause the
+shell to exit merely because <code>grep</code> selected no lines,
+which is ordinarily not what you want.
+</p>
+<p>There is a related problem with Bash&rsquo;s <code>set -e -o 
pipefail</code>.
+Since <code>grep</code> does not always read all its input, a command
+outputting to a pipe read by <code>grep</code> can fail when
+<code>grep</code> exits before reading all its input, and the command&rsquo;s
+failure can cause Bash to exit.
+</p>
 </li><li> Why is this back-reference failing?
 
 <div class="example">
@@ -304,7 +333,7 @@
 <code>sed</code>, <code>perl</code>, or many other utilities that are
 designed to operate across lines.
 </p>
-</li><li> What do <code>grep</code>, <code>fgrep</code>, and 
<code>egrep</code> stand for?
+</li><li> What do <code>grep</code>, <samp>-E</samp>, and <samp>-F</samp> 
stand for?
 
 <p>The name <code>grep</code> comes from the way line editing was done on Unix.
 For example,
@@ -316,9 +345,29 @@
 g/re/p
 </pre></div>
 
-<p><code>fgrep</code> stands for Fixed <code>grep</code>;
-<code>egrep</code> stands for Extended <code>grep</code>.
+<p>The <samp>-E</samp> option stands for Extended <code>grep</code>.
+The <samp>-F</samp> option stands for Fixed <code>grep</code>;
+</p>
+</li><li> What happened to <code>egrep</code> and <code>fgrep</code>?
+
+<p>7th Edition Unix had commands <code>egrep</code> and <code>fgrep</code>
+that were the counterparts of the modern &lsquo;<samp>grep -E</samp>&rsquo; 
and &lsquo;<samp>grep -F</samp>&rsquo;.
+Although breaking up <code>grep</code> into three programs was perhaps
+useful on the small computers of the 1970s, <code>egrep</code> and
+<code>fgrep</code> were not standardized by POSIX and are no longer needed.
+In the current GNU implementation, <code>egrep</code> and <code>fgrep</code>
+issue a warning and then act like their modern counterparts;
+eventually, they are planned to be removed entirely.
+</p>
+<p>If you prefer the old names, you can use use your own substitutes,
+such as a shell script named <code>egrep</code> with the following
+contents:
 </p>
+<div class="example">
+<pre class="example">#!/bin/sh
+exec grep -E &quot;$@&quot;
+</pre></div>
+
 </li></ol>