logo

oasis-root

Compiled tree of Oasis Linux based on own branch at <https://hacktivis.me/git/oasis/> git clone https://anongit.hacktivis.me/git/oasis-root.git

grep.1p (14386B)


  1. '\" et
  2. .TH GREP "1P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
  3. .\"
  4. .SH PROLOG
  5. This manual page is part of the POSIX Programmer's Manual.
  6. The Linux implementation of this interface may differ (consult
  7. the corresponding Linux manual page for details of Linux behavior),
  8. or the interface may not be implemented on Linux.
  9. .\"
  10. .SH NAME
  11. grep
  12. \(em search a file for a pattern
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. grep \fB[\fR-E|-F\fB] [\fR-c|-l|-q\fB] [\fR-insvx\fB] \fR-e \fIpattern_list
  17. \fB[\fR-e \fIpattern_list\fB]\fR... \fB[\fR-f \fIpattern_file\fB]\fR... \fB[\fIfile\fR...\fB]\fR
  18. .P
  19. grep \fB[\fR-E|-F\fB] [\fR-c|-l|-q\fB] [\fR-insvx\fB] [\fR-e \fIpattern_list\fB]...
  20. \fR-f \fIpattern_file \fB[\fR-f \fIpattern_file\fB]\fR... \fB[\fIfile\fR...\fB]\fR
  21. .P
  22. grep \fB[\fR-E|-F\fB] [\fR-c|-l|-q\fB] [\fR-insvx\fB] \fIpattern_list\fB [\fIfile\fR...\fB]\fR
  23. .fi
  24. .SH DESCRIPTION
  25. The
  26. .IR grep
  27. utility shall search the input files, selecting lines matching one or
  28. more patterns; the types of patterns are controlled by the options
  29. specified. The patterns are specified by the
  30. .BR \-e
  31. option,
  32. .BR \-f
  33. option, or the
  34. .IR pattern_list
  35. operand. The
  36. .IR pattern_list 's
  37. value shall consist of one or more patterns separated by
  38. <newline>
  39. characters; the
  40. .IR pattern_file 's
  41. contents shall consist of one or more patterns terminated by a
  42. <newline>
  43. character. By default, an input line shall be selected if any
  44. pattern, treated as an entire basic regular expression (BRE) as
  45. described in the Base Definitions volume of POSIX.1\(hy2017,
  46. .IR "Section 9.3" ", " "Basic Regular Expressions",
  47. matches any part of the line excluding the terminating
  48. <newline>;
  49. a null BRE shall match every line. By default, each selected input
  50. line shall be written to the standard output.
  51. .P
  52. Regular expression matching shall be based on text lines. Since a
  53. <newline>
  54. separates or terminates patterns (see the
  55. .BR \-e
  56. and
  57. .BR \-f
  58. options below), regular expressions cannot contain a
  59. <newline>.
  60. Similarly, since patterns are matched against individual lines
  61. (excluding the terminating
  62. <newline>
  63. characters) of the input, there is no way for a pattern to match a
  64. <newline>
  65. found in the input.
  66. .SH OPTIONS
  67. The
  68. .IR grep
  69. utility shall conform to the Base Definitions volume of POSIX.1\(hy2017,
  70. .IR "Section 12.2" ", " "Utility Syntax Guidelines".
  71. .P
  72. The following options shall be supported:
  73. .IP "\fB\-E\fP" 10
  74. Match using extended regular expressions.
  75. Treat each pattern specified as an ERE, as described in the Base Definitions volume of POSIX.1\(hy2017,
  76. .IR "Section 9.4" ", " "Extended Regular Expressions".
  77. If any entire ERE pattern matches some part of an input line excluding
  78. the terminating
  79. <newline>,
  80. the line shall be matched. A null ERE shall match every line.
  81. .IP "\fB\-F\fP" 10
  82. Match using fixed strings. Treat each pattern specified as a string
  83. instead of a regular expression. If an input line contains any of the
  84. patterns as a contiguous sequence of bytes, the line shall be matched.
  85. A null string shall match every line.
  86. .IP "\fB\-c\fP" 10
  87. Write only a count of selected lines to standard output.
  88. .IP "\fB\-e\ \fIpattern_list\fR" 10
  89. .br
  90. Specify one or more patterns to be used during the search for input.
  91. The application shall ensure that patterns in
  92. .IR pattern_list
  93. are separated by a
  94. <newline>.
  95. A null pattern can be specified by two adjacent
  96. <newline>
  97. characters in
  98. .IR pattern_list .
  99. Unless the
  100. .BR \-E
  101. or
  102. .BR \-F
  103. option is also specified, each pattern shall be treated as a BRE, as
  104. described in the Base Definitions volume of POSIX.1\(hy2017,
  105. .IR "Section 9.3" ", " "Basic Regular Expressions".
  106. Multiple
  107. .BR \-e
  108. and
  109. .BR \-f
  110. options shall be accepted by the
  111. .IR grep
  112. utility. All of the specified patterns shall be used when matching
  113. lines, but the order of evaluation is unspecified.
  114. .IP "\fB\-f\ \fIpattern_file\fR" 10
  115. .br
  116. Read one or more patterns from the file named by the pathname
  117. .IR pattern_file .
  118. Patterns in
  119. .IR pattern_file
  120. shall be terminated by a
  121. <newline>.
  122. A null pattern can be specified by an empty line in
  123. .IR pattern_file .
  124. Unless the
  125. .BR \-E
  126. or
  127. .BR \-F
  128. option is also specified, each pattern shall be treated as a BRE, as
  129. described in the Base Definitions volume of POSIX.1\(hy2017,
  130. .IR "Section 9.3" ", " "Basic Regular Expressions".
  131. .IP "\fB\-i\fP" 10
  132. Perform pattern matching in searches without regard to case; see the Base Definitions volume of POSIX.1\(hy2017,
  133. .IR "Section 9.2" ", " "Regular Expression General Requirements".
  134. .IP "\fB\-l\fP" 10
  135. (The letter ell.) Write only the names of files containing selected
  136. lines to standard output. Pathnames shall be written once per file
  137. searched. If the standard input is searched, a pathname of
  138. .BR \(dq(standard input)\(dq
  139. shall be written, in the POSIX locale. In other locales,
  140. .BR \(dqstandard input\(dq
  141. may be replaced by something more appropriate in those locales.
  142. .IP "\fB\-n\fP" 10
  143. Precede each output line by its relative line number in the file, each
  144. file starting at line 1. The line number counter shall be reset for
  145. each file processed.
  146. .IP "\fB\-q\fP" 10
  147. Quiet. Nothing shall be written to the standard output, regardless of
  148. matching lines. Exit with zero status if an input line is selected.
  149. .IP "\fB\-s\fP" 10
  150. Suppress the error messages ordinarily written for nonexistent or
  151. unreadable files. Other error messages shall not be suppressed.
  152. .IP "\fB\-v\fP" 10
  153. Select lines not matching any of the specified patterns. If the
  154. .BR \-v
  155. option is not specified, selected lines shall be those that match any
  156. of the specified patterns.
  157. .IP "\fB\-x\fP" 10
  158. Consider only input lines that use all characters in the line excluding
  159. the terminating
  160. <newline>
  161. to match an entire fixed string or regular expression to be matching
  162. lines.
  163. .SH OPERANDS
  164. The following operands shall be supported:
  165. .IP "\fIpattern_list\fR" 10
  166. Specify one or more patterns to be used during the search for input.
  167. This operand shall be treated as if it were specified as
  168. .BR \-e
  169. .IR pattern_list .
  170. .IP "\fIfile\fR" 10
  171. A pathname of a file to be searched for the patterns. If no
  172. .IR file
  173. operands are specified, the standard input shall be used.
  174. .SH STDIN
  175. The standard input shall be used if no
  176. .IR file
  177. operands are specified, and shall be used if a
  178. .IR file
  179. operand is
  180. .BR '\-'
  181. and the implementation treats the
  182. .BR '\-'
  183. as meaning standard input.
  184. Otherwise, the standard input shall not be used.
  185. See the INPUT FILES section.
  186. .SH "INPUT FILES"
  187. The input files shall be text files.
  188. .SH "ENVIRONMENT VARIABLES"
  189. The following environment variables shall affect the execution of
  190. .IR grep :
  191. .IP "\fILANG\fP" 10
  192. Provide a default value for the internationalization variables that are
  193. unset or null. (See the Base Definitions volume of POSIX.1\(hy2017,
  194. .IR "Section 8.2" ", " "Internationalization Variables"
  195. for the precedence of internationalization variables used to determine
  196. the values of locale categories.)
  197. .IP "\fILC_ALL\fP" 10
  198. If set to a non-empty string value, override the values of all the
  199. other internationalization variables.
  200. .IP "\fILC_COLLATE\fP" 10
  201. .br
  202. Determine the locale for the behavior of ranges, equivalence classes,
  203. and multi-character collating elements within regular expressions.
  204. .IP "\fILC_CTYPE\fP" 10
  205. Determine the locale for the interpretation of sequences of bytes of
  206. text data as characters (for example, single-byte as opposed to
  207. multi-byte characters in arguments and input files) and the behavior of
  208. character classes within regular expressions.
  209. .IP "\fILC_MESSAGES\fP" 10
  210. .br
  211. Determine the locale that should be used to affect the format and
  212. contents of diagnostic messages written to standard error.
  213. .IP "\fINLSPATH\fP" 10
  214. Determine the location of message catalogs for the processing of
  215. .IR LC_MESSAGES .
  216. .SH "ASYNCHRONOUS EVENTS"
  217. Default.
  218. .SH STDOUT
  219. If the
  220. .BR \-l
  221. option is in effect, the following shall be written for each file
  222. containing at least one selected input line:
  223. .sp
  224. .RS 4
  225. .nf
  226. "%s\en", <\fIfile\fR>
  227. .fi
  228. .P
  229. .RE
  230. .P
  231. Otherwise, if more than one
  232. .IR file
  233. argument appears, and
  234. .BR \-q
  235. is not specified, the
  236. .IR grep
  237. utility shall prefix each output line by:
  238. .sp
  239. .RS 4
  240. .nf
  241. "%s:", <\fIfile\fR>
  242. .fi
  243. .P
  244. .RE
  245. .P
  246. The remainder of each output line shall depend on the other options
  247. specified:
  248. .IP " *" 4
  249. If the
  250. .BR \-c
  251. option is in effect, the remainder of each output line shall contain:
  252. .RS 4
  253. .sp
  254. .RS 4
  255. .nf
  256. "%d\en", <\fIcount\fR>
  257. .fi
  258. .P
  259. .RE
  260. .RE
  261. .IP " *" 4
  262. Otherwise, if
  263. .BR \-c
  264. is not in effect and the
  265. .BR \-n
  266. option is in effect, the following shall be written to standard
  267. output:
  268. .RS 4
  269. .sp
  270. .RS 4
  271. .nf
  272. "%d:", <\fIline number\fR>
  273. .fi
  274. .P
  275. .RE
  276. .RE
  277. .IP " *" 4
  278. Finally, the following shall be written to standard output:
  279. .RS 4
  280. .sp
  281. .RS 4
  282. .nf
  283. "%s", <\fIselected-line contents\fR>
  284. .fi
  285. .P
  286. .RE
  287. .RE
  288. .SH STDERR
  289. The standard error shall be used only for diagnostic messages.
  290. .SH "OUTPUT FILES"
  291. None.
  292. .SH "EXTENDED DESCRIPTION"
  293. None.
  294. .SH "EXIT STATUS"
  295. The following exit values shall be returned:
  296. .IP "\00" 6
  297. One or more lines were selected.
  298. .IP "\01" 6
  299. No lines were selected.
  300. .IP >1 6
  301. An error occurred.
  302. .SH "CONSEQUENCES OF ERRORS"
  303. If the
  304. .BR \-q
  305. option is specified, the exit status shall be zero if an input line is
  306. selected, even if an error was detected. Otherwise, default actions
  307. shall be performed.
  308. .LP
  309. .IR "The following sections are informative."
  310. .SH "APPLICATION USAGE"
  311. Care should be taken when using characters in
  312. .IR pattern_list
  313. that may also be meaningful to the command interpreter. It is safest
  314. to enclose the entire
  315. .IR pattern_list
  316. argument in single-quotes:
  317. .sp
  318. .RS 4
  319. .nf
  320. \&\(aq...\(aq
  321. .fi
  322. .P
  323. .RE
  324. .P
  325. The
  326. .BR \-e
  327. .IR pattern_list
  328. option has the same effect as the
  329. .IR pattern_list
  330. operand, but is useful when
  331. .IR pattern_list
  332. begins with the
  333. <hyphen-minus>
  334. delimiter. It is also useful when it is more convenient to provide
  335. multiple patterns as separate arguments.
  336. .P
  337. Multiple
  338. .BR \-e
  339. and
  340. .BR \-f
  341. options are accepted and
  342. .IR grep
  343. uses all of the patterns it is given while matching input text lines.
  344. (Note that the order of evaluation is not specified. If an
  345. implementation finds a null string as a pattern, it is allowed to use
  346. that pattern first, matching every line, and effectively ignore any
  347. other patterns.)
  348. .P
  349. The
  350. .BR \-q
  351. option provides a means of easily determining whether or not a pattern
  352. (or string) exists in a group of files. When searching several files,
  353. it provides a performance improvement (because it can quit as soon as
  354. it finds the first match) and requires less care by the user in
  355. choosing the set of files to supply as arguments (because it exits zero
  356. if it finds a match even if
  357. .IR grep
  358. detected an access or read error on earlier
  359. .IR file
  360. operands).
  361. .P
  362. When using
  363. .IR grep
  364. to process pathnames, it is recommended that LC_ALL, or at least
  365. LC_CTYPE and LC_COLLATE, are set to POSIX or C in the environment,
  366. since pathnames can contain byte sequences that do not form valid
  367. characters in some locales, in which case the utility's behavior would
  368. be undefined. In the POSIX locale each byte is a valid single-byte
  369. character, and therefore this problem is avoided.
  370. .SH EXAMPLES
  371. .IP " 1." 4
  372. To find all uses of the word
  373. .BR \(dqPosix\(dq
  374. (in any case) in file
  375. .BR text.mm
  376. and write with line numbers:
  377. .RS 4
  378. .sp
  379. .RS 4
  380. .nf
  381. grep -i -n posix text.mm
  382. .fi
  383. .P
  384. .RE
  385. .RE
  386. .IP " 2." 4
  387. To find all empty lines in the standard input:
  388. .RS 4
  389. .sp
  390. .RS 4
  391. .nf
  392. grep \(ha$
  393. .fi
  394. .P
  395. .RE
  396. .P
  397. or:
  398. .sp
  399. .RS 4
  400. .nf
  401. grep -v .
  402. .fi
  403. .P
  404. .RE
  405. .RE
  406. .IP " 3." 4
  407. Both of the following commands print all lines containing strings
  408. .BR \(dqabc\(dq
  409. or
  410. .BR \(dqdef\(dq
  411. or both:
  412. .RS 4
  413. .sp
  414. .RS 4
  415. .nf
  416. grep -E \(aqabc|def\(aq
  417. .P
  418. grep -F \(aqabc
  419. def\(aq
  420. .fi
  421. .P
  422. .RE
  423. .RE
  424. .IP " 4." 4
  425. Both of the following commands print all lines matching exactly
  426. .BR \(dqabc\(dq
  427. or
  428. .BR \(dqdef\(dq :
  429. .RS 4
  430. .sp
  431. .RS 4
  432. .nf
  433. grep -E \(aq\(haabc$|\(hadef$\(aq
  434. .P
  435. grep -F -x \(aqabc
  436. def\(aq
  437. .fi
  438. .P
  439. .RE
  440. .RE
  441. .SH RATIONALE
  442. This
  443. .IR grep
  444. has been enhanced in an upwards-compatible way to provide the exact
  445. functionality of the historical
  446. .IR egrep
  447. and
  448. .IR fgrep
  449. commands as well. It was the clear intention of the standard
  450. developers to consolidate the three
  451. .IR grep s
  452. into a single command.
  453. .P
  454. The old
  455. .IR egrep
  456. and
  457. .IR fgrep
  458. commands are likely to be supported for many years to come as
  459. implementation extensions, allowing historical applications to operate
  460. unmodified.
  461. .P
  462. Historical implementations usually silently ignored all but one of
  463. multiply-specified
  464. .BR \-e
  465. and
  466. .BR \-f
  467. options, but were not consistent as to which specification was actually
  468. used.
  469. .P
  470. The
  471. .BR \-b
  472. option was omitted from the OPTIONS section because block numbers are
  473. implementation-defined.
  474. .P
  475. The System V restriction on using
  476. .BR \-
  477. to mean standard input was omitted.
  478. .P
  479. A definition of action taken when given a null BRE or ERE is specified.
  480. This is an error condition in some historical implementations.
  481. .P
  482. The
  483. .BR \-l
  484. option previously indicated that its use was undefined when no files
  485. were explicitly named. This behavior was historical and placed an
  486. unnecessary restriction on future implementations. It has been
  487. removed.
  488. .P
  489. The historical BSD
  490. .IR grep
  491. .BR \-s
  492. option practice is easily duplicated by redirecting standard output to
  493. .BR /dev/null .
  494. The
  495. .BR \-s
  496. option required here is from System V.
  497. .P
  498. The
  499. .BR \-x
  500. option, historically available only with
  501. .IR fgrep ,
  502. is available here for all of the non-obsolescent versions.
  503. .SH "FUTURE DIRECTIONS"
  504. None.
  505. .SH "SEE ALSO"
  506. .IR "\fIsed\fR\^"
  507. .P
  508. The Base Definitions volume of POSIX.1\(hy2017,
  509. .IR "Chapter 8" ", " "Environment Variables",
  510. .IR "Chapter 9" ", " "Regular Expressions",
  511. .IR "Section 12.2" ", " "Utility Syntax Guidelines"
  512. .\"
  513. .SH COPYRIGHT
  514. Portions of this text are reprinted and reproduced in electronic form
  515. from IEEE Std 1003.1-2017, Standard for Information Technology
  516. -- Portable Operating System Interface (POSIX), The Open Group Base
  517. Specifications Issue 7, 2018 Edition,
  518. Copyright (C) 2018 by the Institute of
  519. Electrical and Electronics Engineers, Inc and The Open Group.
  520. In the event of any discrepancy between this version and the original IEEE and
  521. The Open Group Standard, the original IEEE and The Open Group Standard
  522. is the referee document. The original Standard can be obtained online at
  523. http://www.opengroup.org/unix/online.html .
  524. .PP
  525. Any typographical or formatting errors that appear
  526. in this page are most likely
  527. to have been introduced during the conversion of the source files to
  528. man page format. To report such errors, see
  529. https://www.kernel.org/doc/man-pages/reporting_bugs.html .