Annotation of src/usr.bin/grep/grep.1, Revision 1.1
1.1 ! deraadt 1: .\" $OpenBSD$
! 2: .\"
! 3: .\" Copyright (c) 2000 Carson Harding. All rights reserved.
! 4: .\" This code was written and contributed to OpenBSD by Carson Harding.
! 5: .\"
! 6: .\" Redistribution and use in source and binary forms, with or without
! 7: .\" modification, are permitted provided that the following conditions
! 8: .\" are met:
! 9: .\" 1. Redistributions of source code must retain the above copyright
! 10: .\" notice, this list of conditions and the following disclaimer.
! 11: .\" 2. Redistributions in binary form must reproduce the above copyright
! 12: .\" notice, this list of conditions and the following disclaimer in the
! 13: .\" documentation and/or other materials provided with the distribution.
! 14: .\" 3. Neither the name of the author, or the names of contributors may be
! 15: .\" used to endorse or promote products derived from this software without
! 16: .\" specific prior written permission.
! 17: .\"
! 18: .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
! 19: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
! 20: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
! 21: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
! 22: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
! 23: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
! 24: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
! 25: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
! 26: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
! 27: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
! 28: .\" SUCH DAMAGE.
! 29: .\"
! 30: .Dd May 10, 2001
! 31: .Dt GREP 1
! 32: .Os
! 33: .Sh NAME
! 34: .Nm grep , egrep , fgrep
! 35: .Nd print lines matching a pattern
! 36: .Sh SYNOPSIS
! 37: .Nm grep
! 38: .Op Fl E | Fl F
! 39: .Op Fl bchilnqsvwxz
! 40: .Oo
! 41: .Fl RXH
! 42: .Op Fl L | Fl P
! 43: .Oc
! 44: .Op Fl e Ar pattern_list
! 45: .Op Fl f Ar pattern_file
! 46: .Op Ar pattern
! 47: .Op Ar file
! 48: .Ar ...
! 49: .Sh DESCRIPTION
! 50: The
! 51: .Nm
! 52: utility searches for lines that contain the specified pattern
! 53: or patterns. By default
! 54: .Nm
! 55: prints lines containing matches to the standard output. If no input files
! 56: are specified,
! 57: .Nm
! 58: expects to read its input from the standard input.
! 59: .Pp
! 60: .Nm egrep
! 61: is equivalent to
! 62: .Nm grep
! 63: .Fl E ;
! 64: .Nm fgrep
! 65: is equivalent to
! 66: .Nm grep
! 67: .Fl F .
! 68: .Pp
! 69: The patterns are regular expressions, or in the case of
! 70: .Nm fgrep ,
! 71: fixed strings. More than one pattern may be specified on the
! 72: command-line, either by repeated use of the
! 73: .Fl e
! 74: flag, or by separating patterns with newlines:
! 75:
! 76: .Nm grep
! 77: \'Ishmael
! 78: Ahab' mobydick.txt
! 79:
! 80: is the same as:
! 81:
! 82: .Nm
! 83: -e Ishmael -e Ahab mobydick.txt
! 84:
! 85: Note that many regular expression special characters also have special
! 86: meaning to the shell. It is best to enclose the regular expression
! 87: in quotation marks. Note also that a null pattern ("" or a newline alone)
! 88: matches all input.
! 89: .Sh OPTIONS
! 90: .Pp
! 91: The options available are:
! 92: .Bl -tag -width file Ds
! 93: .It Fl E
! 94: Use extended regular expressions, as if the program was invoked as
! 95: .Nm egrep.
! 96: .It Fl F
! 97: Patterns are fixed strings, not regular expressions, as if the
! 98: program was invoked as
! 99: .Nm fgrep.
! 100: .It Fl a
! 101: Does nothing. In other greps this flag tells grep to treat the input
! 102: as ascii and turns off attempts to determine whether the input file is a
! 103: binary file. This
! 104: .Nm grep
! 105: does not (yet) do that check, so behaves as if
! 106: .Fl a
! 107: is always specified.
! 108: .It Fl b
! 109: Prepend the byte-offset of the beginning of the line containing the match.
! 110: .It Fl c
! 111: Print only a count of the matches found.
! 112: .It Fl e Ar pattern_list
! 113: The argument to
! 114: .Fl e
! 115: is a list of patterns to search for.
! 116: .Fl e
! 117: may be used multiple times, each instance of which may have
! 118: one or more patterns separated by new-lines.
! 119: .It Fl f Ar pattern_file
! 120: The argument to
! 121: .Fl f
! 122: is the name of a file from which to read patterns.
! 123: .Fl f
! 124: may be more than once.
! 125: .It Fl h
! 126: Suppress the prefixing of file names to matching lines when multiple
! 127: files are searched.
! 128: .It Fl i
! 129: Ignore case in comparisons.
! 130: .It Fl l
! 131: Print only a list of the names of files in which matches were found.
! 132: If the input is the standard input,
! 133: .Nm
! 134: prints "(standard input)".
! 135: .It Fl n
! 136: Prefix matching lines with their line number in the file in which
! 137: they occur.
! 138: .It Fl q
! 139: Be quiet about errors accessing files, only return program status.
! 140: The status returned is 0 if there was a match, 1 if there were no
! 141: matches, even if there were errors accessing files. (Without the
! 142: .Fl q
! 143: flag, if there was an error
! 144: accessing a file
! 145: .Nm
! 146: would return a status of 2 even
! 147: if it found matches.)
! 148: .It Fl s
! 149: Suppress errors about accessing files. Note that unlike
! 150: .Fl q
! 151: the program is not quiet: matches are still output.
! 152: .It Fl v
! 153: Invert the sense of the match: return all lines that do not
! 154: contain the pattern.
! 155: .It Fl w
! 156: The pattern is considered a word. A matching pattern in a line must not
! 157: be immediately bordered by a letter, a number, or an underscore ('_').
! 158: .It Fl x
! 159: Match the line exactly. If a regular expression (invoked as
! 160: .Nm grep ,
! 161: or
! 162: .Nm egrep )
! 163: the pattern must match the whole line (as if
! 164: the pattern was enclosed in ^ and $). If invoked as
! 165: .Nm fgrep,
! 166: the string must match the entire line.
! 167: .It Fl z
! 168: When the
! 169: .Fl l
! 170: flag is also specified, print an ASCII NUL character (0) following
! 171: the file name, rather than a newline. Like the
! 172: .Fl print0
! 173: option to
! 174: .Nm find ,
! 175: this may be used to pass file names containing unusual characters
! 176: to programs such as
! 177: .Nm xargs
! 178: with the
! 179: .Fl 0
! 180: flag.
! 181: .El
! 182: .Sh FILESYSTEM TRAVERSAL OPTIONS
! 183: .Pp
! 184: The following options control recursive searchs:
! 185: .Bl -tag -width file Ds
! 186: .It Fl R
! 187: Recursively descend through any specified directory arguments.
! 188: .It Fl H
! 189: If the
! 190: .Fl R
! 191: option is also specified, symbolic links on the command
! 192: line are followed. (Symbolic links encountered in the tree
! 193: traversal are not followed.)
! 194: .It Fl L
! 195: If the
! 196: .Fl R
! 197: option is also specified, all symbolic links are followed.
! 198: .It Fl P
! 199: If the
! 200: .Fl R
! 201: option is also specified, no symbolic links are followed.
! 202: .It Fl X
! 203: If the
! 204: .Fl R
! 205: option is also specified, searches are confined to the device on
! 206: which the search started (file system mount points are not crossed).
! 207: .El
! 208: .Sh EXAMPLES
! 209: .Pp
! 210: To print all occurrences of the word Ishmael in mobydick.txt:
! 211: .Dl grep Ishmael mobydick.txt
! 212: .Pp
! 213: To merely count all the lines in which the word Ishmael occurs:
! 214: .Dl grep -c Ishmael mobydick.txt
! 215: .Pp
! 216: To print all occurrences of either of the words Ishmael or Ahab in
! 217: mobydick.txt:
! 218: .Dl grep 'Ishmael|Ahab' mobydick.txt
! 219: .Pp
! 220: To print all occurrences of the word whale in mobydick.txt, whether
! 221: or not it is capitalised, and where it appears alone and not as part
! 222: of a compound:
! 223: .Dl grep -iw whale mobydick.txt
! 224: .Pp
! 225: To find all the empty lines and print the line numbers for where they occur:
! 226: .Dl grep -nv \&. mobydick.txt
! 227: .Sh DIAGNOSTICS
! 228: .Pp
! 229: The
! 230: .Nm
! 231: utility exits with one of the following values:
! 232: .Pp
! 233: .Bl -tag -width flag -compact
! 234: .It 0
! 235: One or more matching lines was found.
! 236: .It 1
! 237: No matches were found.
! 238: .It 2
! 239: An error occurred (whether or not matches were found).
! 240: .Pp
! 241: Note that when the
! 242: .Fl q
! 243: flag is used, file access errors do not cause an exit value of 2,
! 244: and in the absence of other errors (a bad regular expression)
! 245: the exit value is determined only by whether or not matches
! 246: were found. (XX Should -s do the same??)
! 247: .Sh SEE ALSO
! 248: .Xr re_format 7 ,
! 249: .Xr regex 3 ,
! 250: .Sh HISTORY
! 251: A
! 252: .Nm grep
! 253: command appeared in
! 254: .At v6 .
! 255: This version is a re-implementation from the POSIX specification and
! 256: inspection of the operation of several implementations of
! 257: .Nm grep .
! 258: .Sh NOTES
! 259: .Nm grep
! 260: has no limits on input line length (other than imposed by available
! 261: memory).
![[BACK]](/icons/back.gif){kind=icon}
Return to grep.1 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / src / usr.bin / grep