Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
PCRE2GREP(1)		    General Commands Manual		  PCRE2GREP(1)

NAME
       pcre2grep - a grep with Perl-compatible regular expressions.

SYNOPSIS
       pcre2grep [options] [long options] [pattern] [path1 path2 ...]

DESCRIPTION

       pcre2grep  searches  files  for	character patterns, in the same	way as
       other grep commands do, but it uses the PCRE2  regular  expression  li-
       brary  to support patterns that are compatible with the regular expres-
       sions of	Perl 5.	See pcre2syntax(3) for a  quick-reference  summary  of
       pattern syntax, or pcre2pattern(3) for a	full description of the	syntax
       and semantics of	the regular expressions	that PCRE2 supports.

       Patterns, whether supplied on the command line or in a  separate	 file,
       are given without delimiters. For example:

	 pcre2grep Thursday /etc/motd

       If you attempt to use delimiters	(for example, by surrounding a pattern
       with slashes, as	is common in Perl scripts), they  are  interpreted  as
       part  of	 the pattern. Quotes can of course be used to delimit patterns
       on the command line because they	are interpreted	by the shell, and  in-
       deed  quotes  are  required  if a pattern contains white	space or shell
       metacharacters.

       The first argument that follows any option settings is treated  as  the
       single  pattern	to be matched when neither -e nor -f is	present.  Con-
       versely,	when one or both of these options are  used  to	 specify  pat-
       terns, all arguments are	treated	as path	names. At least	one of -e, -f,
       or an argument pattern must be provided.

       If no files are specified, pcre2grep  reads  the	 standard  input.  The
       standard	 input can also	be referenced by a name	consisting of a	single
       hyphen.	For example:

	 pcre2grep some-pattern	file1 -	file3

       Input files are searched	line by	 line.	By  default,  each  line  that
       matches	a  pattern  is	copied to the standard output, and if there is
       more than one file, the file name is output at the start	of each	 line,
       followed	 by  a	colon.	However, there are options that	can change how
       pcre2grep behaves. In particular, the -M	option makes  it  possible  to
       search  for  strings  that  span	 line  boundaries. What	defines	a line
       boundary	is controlled by the -N	(--newline) option.

       The amount of memory used for buffering files that are being scanned is
       controlled  by a	parameter that can be set by the --buffer-size option.
       The default value for this parameter is	specified  when	 pcre2grep  is
       built,  with  the  default  default  being 20K. A block of memory three
       times this size is used (to allow for buffering	"before"  and  "after"
       lines). An error	occurs if a line overflows the buffer.

       Patterns	 can  be  no  longer than 8K or	BUFSIZ bytes, whichever	is the
       greater.	 BUFSIZ	is defined in <stdio.h>. When there is more  than  one
       pattern (specified by the use of	-e and/or -f), each pattern is applied
       to each line in the order in which they are defined,  except  that  all
       the -e patterns are tried before	the -f patterns.

       By  default, as soon as one pattern matches a line, no further patterns
       are considered. However,	if --colour (or	--color) is used to colour the
       matching	 substrings, or	if --only-matching, --file-offsets, or --line-
       offsets is used to output only the part of the line that	 matched  (ei-
       ther  shown  literally,	or as an offset), scanning resumes immediately
       following the match, so that further matches on the same	 line  can  be
       found.  If  there  are multiple patterns, they are all tried on the re-
       mainder of the line, but	patterns that follow the one that matched  are
       not tried on the	earlier	part of	the line.

       This  behaviour	means  that  the  order	in which multiple patterns are
       specified can affect the	output when one	of the above options is	 used.
       This  is	no longer the same behaviour as	GNU grep, which	now manages to
       display earlier matches for later patterns (as  long  as	 there	is  no
       overlap).

       Patterns	 that can match	an empty string	are accepted, but empty	string
       matches	are  never  recognized.	 An  example  is  the  pattern	 "(su-
       per)?(man)?",  in which all components are optional. This pattern finds
       all occurrences of both "super" and  "man";  the	 output	 differs  from
       matching	 with  "super|man" when	only the matching substrings are being
       shown.

       If the LC_ALL or	LC_CTYPE environment variable is set,  pcre2grep  uses
       the value to set	a locale when calling the PCRE2	library.  The --locale
       option can be used to override this.

SUPPORT	FOR COMPRESSED FILES

       It is possible to compile pcre2grep so that it uses libz	or  libbz2  to
       read  files  whose names	end in .gz or .bz2, respectively. You can find
       out whether your	binary has support for one or both of these file types
       by running it with the --help option. If	the appropriate	support	is not
       present,	files are treated as plain text. The standard input is	always
       so treated.

BINARY FILES

       By  default,  a	file that contains a binary zero byte within the first
       1024 bytes is identified	as a binary file, and is processed  specially.
       (GNU  grep  also	identifies binary files	in this	manner.) See the --bi-
       nary-files option for a means of	changing the way binary	files are han-
       dled.

OPTIONS

       The  order  in  which some of the options appear	can affect the output.
       For example, both the -h	and -l options affect  the  printing  of  file
       names.  Whichever  comes	later in the command line will be the one that
       takes effect. Similarly,	except where noted  below,  if	an  option  is
       given  twice,  the  later setting is used. Numerical values for options
       may be followed by K  or	 M,  to	 signify  multiplication  by  1024  or
       1024*1024 respectively.

       --	 This terminates the list of options. It is useful if the next
		 item on the command line starts with a	hyphen but is  not  an
		 option.  This	allows for the processing of patterns and file
		 names that start with hyphens.

       -A number, --after-context=number
		 Output	number lines of	context	after each matching  line.  If
		 file  names  and/or  line  numbers are	being output, a	hyphen
		 separator is used instead of a	colon for the context lines. A
		 line  containing  "--"	is output between each group of	lines,
		 unless	they are in fact contiguous in	the  input  file.  The
		 value	of number is expected to be relatively small. However,
		 pcre2grep guarantees to have  up  to  8K  of  following  text
		 available for context output.

       -a, --text
		 Treat	binary	files as text. This is equivalent to --binary-
		 files=text.

       -B number, --before-context=number
		 Output	number lines of	context	before each matching line.  If
		 file  names  and/or  line  numbers are	being output, a	hyphen
		 separator is used instead of a	colon for the context lines. A
		 line  containing  "--"	is output between each group of	lines,
		 unless	they are in fact contiguous in	the  input  file.  The
		 value	of number is expected to be relatively small. However,
		 pcre2grep guarantees to have  up  to  8K  of  preceding  text
		 available for context output.

       --binary-files=word
		 Specify  how binary files are to be processed.	If the word is
		 "binary" (the default), pattern matching is performed on  bi-
		 nary  files,  but  the	 only  output  is  "Binary file	<name>
		 matches" when a match succeeds. If the	word is	"text",	 which
		 is  equivalent	 to  the -a or --text option, binary files are
		 processed in the same way as any other	file.  In  this	 case,
		 when  a  match	 succeeds,  the	 output	may be binary garbage,
		 which can have	nasty effects if sent to a  terminal.  If  the
		 word  is  "without-match",  which is equivalent to the	-I op-
		 tion, binary files are	not processed at all; they are assumed
		 not  to  be  of  interest and are skipped without causing any
		 output	or affecting the return	code.

       --buffer-size=number
		 Set the parameter that	controls how much memory is  used  for
		 buffering files that are being	scanned.

       -C number, --context=number
		 Output	 number	 lines	of  context both before	and after each
		 matching line.	 This is equivalent to setting both -A and  -B
		 to the	same value.

       -c, --count
		 Do  not  output  lines	from the files that are	being scanned;
		 instead output	the number of matches (or non-matches if -v is
		 used)	that would otherwise have caused lines to be shown. By
		 default, this count is	the same as the	number	of  suppressed
		 lines,	but if the -M (multiline) option is used (without -v),
		 there may  be	more  suppressed  lines	 than  the  number  of
		 matches.

		 If  no	lines are selected, the	number zero is output. If sev-
		 eral files are	are being scanned, a count is output for  each
		 of  them. However, if the --files-with-matches	option is also
		 used, only those files	whose counts are greater than zero are
		 listed.  When	-c is used, the	-A, -B,	and -C options are ig-
		 nored.

       --colour, --color
		 If this option	is given without any data, it is equivalent to
		 "--colour=auto".   If	data  is required, it must be given in
		 the same shell	item, separated	by an equals sign.

       --colour=value, --color=value
		 This option specifies under what circumstances	the parts of a
		 line that matched a pattern should be coloured	in the output.
		 By default, the output	is not coloured. The value  (which  is
		 optional,  see	above) may be "never", "always", or "auto". In
		 the latter case, colouring happens only if the	standard  out-
		 put  is connected to a	terminal. More resources are used when
		 colouring is enabled, because pcre2grep has to	search for all
		 possible  matches in a	line, not just one, in order to	colour
		 them all.

		 The colour that is used can be	specified by setting the envi-
		 ronment  variable  PCRE2GREP_COLOUR  or  PCRE2GREP_COLOR. The
		 value of this variable	should be a  string  of	 two  numbers,
		 separated  by	a semicolon. They are copied directly into the
		 control string	for setting colour on a	 terminal,  so	it  is
		 your  responsibility  to ensure that they make	sense. If nei-
		 ther of the environment variables  is	set,  the  default  is
		 "1;31", which gives red.

       -D action, --devices=action
		 If  an	 input path is not a regular file or a directory, "ac-
		 tion" specifies how it	is to be processed. Valid  values  are
		 "read"	(the default) or "skip"	(silently skip the path).

       -d action, --directories=action
		 If an input path is a directory, "action" specifies how it is
		 to be processed.  Valid values	are  "read"  (the  default  in
		 non-Windows  environments,  for compatibility with GNU	grep),
		 "recurse" (equivalent to the -r option), or "skip"  (silently
		 skip  the  path, the default in Windows environments).	In the
		 "read"	case, directories are read as if  they	were  ordinary
		 files.	 In some operating systems the effect of reading a di-
		 rectory like this is an immediate end-of-file;	in  others  it
		 may provoke an	error.

       -e pattern, --regex=pattern, --regexp=pattern
		 Specify a pattern to be matched. This option can be used mul-
		 tiple times in	order to specify several patterns. It can also
		 be  used  as a	way of specifying a single pattern that	starts
		 with a	hyphen.	When -e	is used, no argument pattern is	 taken
		 from  the  command  line;  all	 arguments are treated as file
		 names.	There is no limit to the number	of patterns. They  are
		 applied  to  each line	in the order in	which they are defined
		 until one matches.

		 If -f is used with -e,	the command line patterns are  matched
		 first,	followed by the	patterns from the file(s), independent
		 of the	order in which these options are specified. Note  that
		 multiple  use	of -e is not the same as a single pattern with
		 alternatives. For example, X|Y	finds the first	character in a
		 line  that  is	 X or Y, whereas if the	two patterns are given
		 separately, with X first, pcre2grep finds X if	it is present,
		 even if it follows Y in the line. It finds Y only if there is
		 no X in the line. This	matters	only if	you are	 using	-o  or
		 --colo(u)r to show the	part(s)	of the line that matched.

       --exclude=pattern
		 Files (but not	directories) whose names match the pattern are
		 skipped without being processed. This applies to  all	files,
		 whether  listed  on  the  command line, obtained from --file-
		 list, or by scanning a	directory. The pattern is a PCRE2 reg-
		 ular  expression,  and	is matched against the final component
		 of the	file name, not the entire path.	The -F,	-w, and	-x op-
		 tions	do  not	apply to this pattern. The option may be given
		 any number of times in	order to specify multiple patterns. If
		 a  file  name matches both an --include and an	--exclude pat-
		 tern, it is excluded. There is	no short form for this option.

       --exclude-from=filename
		 Treat each non-empty line of the file	as  the	 data  for  an
		 --exclude option. What	constitutes a newline when reading the
		 file is the operating system's	default. The --newline	option
		 has  no  effect on this option. This option may be given more
		 than once in order to specify a number	of files to read.

       --exclude-dir=pattern
		 Directories whose names match the pattern are skipped without
		 being	processed, whatever the	setting	of the --recursive op-
		 tion. This applies to all directories,	whether	listed on  the
		 command  line,	 obtained  from	 --file-list, or by scanning a
		 parent	directory. The pattern is a PCRE2 regular  expression,
		 and  is  matched against the final component of the directory
		 name, not the entire path. The	-F, -w,	and -x options do  not
		 apply	to this	pattern. The option may	be given any number of
		 times in order	to specify more	than one pattern. If a	direc-
		 tory  matches both --include-dir and --exclude-dir, it	is ex-
		 cluded. There is no short form	for this option.

       -F, --fixed-strings
		 Interpret each	data-matching  pattern	as  a  list  of	 fixed
		 strings,  separated  by newlines, instead of as a regular ex-
		 pression. What	constitutes a newline for this purpose is con-
		 trolled by the	--newline option. The -w (match	as a word) and
		 -x (match whole line) options can be used with	-F.  They  ap-
		 ply  to  each of the fixed strings. A line is selected	if any
		 of the	fixed strings are found	in it (subject to -w or	-x, if
		 present).  This  option applies only to the patterns that are
		 matched against the contents of files;	it does	not  apply  to
		 patterns  specified  by any of	the --include or --exclude op-
		 tions.

       -f filename, --file=filename
		 Read patterns from the	file, one per  line,  and  match  them
		 against  each	line of	input. What constitutes	a newline when
		 reading the file  is  the  operating  system's	 default.  The
		 --newline option has no effect	on this	option.	Trailing white
		 space is removed from each line, and blank lines are ignored.
		 An  empty  file  contains  no	patterns and therefore matches
		 nothing. See also the comments	about multiple patterns	versus
		 a  single  pattern with alternatives in the description of -e
		 above.

		 If this option	is given more than  once,  all	the  specified
		 files	are read. A data line is output	if any of the patterns
		 match it. A file name can be given as "-"  to	refer  to  the
		 standard  input.  When	 -f is used, patterns specified	on the
		 command line using -e may also	be present;  they  are	tested
		 before	 the  file's  patterns.	 However,  no other pattern is
		 taken from the	command	line; all arguments are	treated	as the
		 names of paths	to be searched.

       --file-list=filename
		 Read  a  list	of  files  and/or  directories	that are to be
		 scanned from the given	file, one  per	line.  Trailing	 white
		 space is removed from each line, and blank lines are ignored.
		 These paths are processed before any that are listed  on  the
		 command  line.	 The file name can be given as "-" to refer to
		 the standard input.  If --file	and --file-list	are both spec-
		 ified	as  "-",  patterns are read first. This	is useful only
		 when the standard input is a  terminal,  from	which  further
		 lines	(the  list  of files) can be read after	an end-of-file
		 indication. If	this option is given more than once,  all  the
		 specified files are read.

       --file-offsets
		 Instead  of  showing lines or parts of	lines that match, show
		 each match as an offset from the start	 of  the  file	and  a
		 length,  separated  by	 a  comma. In this mode, no context is
		 shown.	That is, the -A, -B, and -C options  are  ignored.  If
		 there is more than one	match in a line, each of them is shown
		 separately. This option is mutually  exclusive	 with  --line-
		 offsets and --only-matching.

       -H, --with-filename
		 Force	the  inclusion of the file name	at the start of	output
		 lines when searching a	single file. By	default, the file name
		 is not	shown in this case.  For matching lines, the file name
		 is followed by	a colon; for context lines, a hyphen separator
		 is  used.  If	a line number is also being output, it follows
		 the file name.	When the -M option causes a pattern  to	 match
		 more  than  one  line,	only the first is preceded by the file
		 name.

       -h, --no-filename
		 Suppress the output file names	when searching multiple	files.
		 By  default,  file  names  are	 shown when multiple files are
		 searched. For matching	lines, the file	name is	followed by  a
		 colon;	 for  context lines, a hyphen separator	is used.  If a
		 line number is	also being output, it follows the file name.

       --help	 Output	a help message,	giving brief details  of  the  command
		 options  and  file type support, and then exit. Anything else
		 on the	command	line is	ignored.

       -I	 Ignore	 binary	 files.	 This  is  equivalent	to   --binary-
		 files=without-match.

       -i, --ignore-case
		 Ignore	upper/lower case distinctions during comparisons.

       --include=pattern
		 If  any --include patterns are	specified, the only files that
		 are processed are those that match one	of the	patterns  (and
		 do  not match an --exclude pattern). This option does not af-
		 fect directories, but it applies to all files,	whether	listed
		 on  the  command line,	obtained from --file-list, or by scan-
		 ning a	directory. The pattern is a PCRE2 regular  expression,
		 and  is matched against the final component of	the file name,
		 not the entire	path. The -F, -w, and -x options do not	 apply
		 to this pattern. The option may be given any number of	times.
		 If a file name	matches	both an	 --include  and	 an  --exclude
		 pattern, it is	excluded.  There is no short form for this op-
		 tion.

       --include-from=filename
		 Treat each non-empty line of the file	as  the	 data  for  an
		 --include option. What	constitutes a newline for this purpose
		 is the	operating system's default. The	--newline  option  has
		 no effect on this option. This	option may be given any	number
		 of times; all the files are read.

       --include-dir=pattern
		 If any	--include-dir patterns are specified, the only	direc-
		 tories	 that  are  processed  are those that match one	of the
		 patterns (and do not match an	--exclude-dir  pattern).  This
		 applies  to  all  directories,	 whether listed	on the command
		 line, obtained	from --file-list, or by	scanning a parent  di-
		 rectory.  The	pattern	 is a PCRE2 regular expression,	and is
		 matched against the final component of	 the  directory	 name,
		 not  the entire path. The -F, -w, and -x options do not apply
		 to this pattern. The option may be given any number of	times.
		 If  a directory matches both --include-dir and	--exclude-dir,
		 it is excluded. There is no short form	for this option.

       -L, --files-without-match
		 Instead of outputting lines from the files, just  output  the
		 names	of  the	files that do not contain any lines that would
		 have been output. Each	file name is output once, on  a	 sepa-
		 rate line.

       -l, --files-with-matches
		 Instead  of  outputting lines from the	files, just output the
		 names of the files containing lines that would	have been out-
		 put.  Each  file  name	 is  output  once, on a	separate line.
		 Searching normally stops as soon as a matching	line is	 found
		 in  a	file.  However,	if the -c (count) option is also used,
		 matching continues in order to	obtain the correct count,  and
		 those	files  that  have  at least one	match are listed along
		 with their counts. Using this option with -c is a way of sup-
		 pressing the listing of files with no matches.

       --label=name
		 This option supplies a	name to	be used	for the	standard input
		 when file names are being output. If not supplied, "(standard
		 input)" is used. There	is no short form for this option.

       --line-buffered
		 When  this  option is given, input is read and	processed line
		 by line, and the output is flushed after each write.  By  de-
		 fault,	 input	is  read in large chunks, unless pcre2grep can
		 determine that	it is reading from a terminal (which  is  cur-
		 rently	 possible  only	 in Unix-like environments). Output to
		 terminal is normally automatically flushed by	the  operating
		 system. This option can be useful when	the input or output is
		 attached to a pipe and	you do not want	pcre2grep to buffer up
		 large	amounts	 of data. However, its use will	affect perfor-
		 mance,	and the	-M (multiline) option ceases to	work.

       --line-offsets
		 Instead of showing lines or parts of lines that  match,  show
		 each match as a line number, the offset from the start	of the
		 line, and a length. The line number is	terminated by a	 colon
		 (as  usual; see the -n	option), and the offset	and length are
		 separated by a	comma. In this	mode,  no  context  is	shown.
		 That  is, the -A, -B, and -C options are ignored. If there is
		 more than one match in	a line,	each of	them  is  shown	 sepa-
		 rately. This option is	mutually exclusive with	--file-offsets
		 and --only-matching.

       --locale=locale-name
		 This option specifies a locale	to be used for pattern	match-
		 ing.  It  overrides the value in the LC_ALL or	LC_CTYPE envi-
		 ronment variables. If no locale is specified, the  PCRE2  li-
		 brary's default (usually the "C" locale) is used. There is no
		 short form for	this option.

       --match-limit=number
		 Processing some regular expression  patterns  can  require  a
		 very  large amount of memory, leading in some cases to	a pro-
		 gram crash if not enough is available.	  Other	 patterns  may
		 take  a  very	long  time to search for all possible matching
		 strings.  The	pcre2_match()  function	 that  is  called   by
		 pcre2grep  to	do  the	 matching  has two parameters that can
		 limit the resources that it uses.

		 The --match-limit option provides a  means  of	 limiting  re-
		 source	 usage	when processing	patterns that are not going to
		 match,	but which have a very large number of possibilities in
		 their	search	trees.	The  classic example is	a pattern that
		 uses nested unlimited repeats.	Internally, PCRE2 uses a func-
		 tion  called match() which it calls repeatedly	(sometimes re-
		 cursively). The limit set by --match-limit is imposed on  the
		 number	of times this function is called during	a match, which
		 has the effect	of limiting the	amount	of  backtracking  that
		 can take place.

		 The --recursion-limit option is similar to --match-limit, but
		 instead of limiting the total number of times that match() is
		 called, it limits the depth of	recursive calls, which in turn
		 limits	the amount of memory that can be used.	The  recursion
		 depth is a smaller number than	the total number of calls, be-
		 cause not all calls to	match()	are recursive. This  limit  is
		 of use	only if	it is set smaller than --match-limit.

		 There	are no short forms for these options. The default set-
		 tings are specified when the PCRE2 library is compiled,  with
		 the default default being 10 million.

       -M, --multiline
		 Allow	patterns to match more than one	line. When this	option
		 is given, patterns may	usefully contain literal newline char-
		 acters	 and  internal	occurrences of ^ and $ characters. The
		 output	for a successful match may consist of  more  than  one
		 line.	The  first is the line in which	the match started, and
		 the last is the line in which the match ended.	If the matched
		 string	 ends  with  a newline sequence	the output ends	at the
		 end of	that line.

		 When this option is set, the PCRE2 library is called in "mul-
		 tiline"  mode.	  However, pcre2grep still processes the input
		 line by line. The difference is that a	matched	string may ex-
		 tend  past the	end of a line and continue on one or more sub-
		 sequent lines.	The newline sequence must be matched  as  part
		 of  the pattern. For example, to find the phrase "regular ex-
		 pression" in a	file where "regular" might be at the end of  a
		 line  and  "expression"  at  the  start of the	next line, you
		 could use this	command:

		   pcre2grep -M	'regular\s+expression' <file>

		 The \s	escape sequence	matches	any white space	character, in-
		 cluding  newlines, and	is followed by + so as to match	trail-
		 ing white space on the	first line as well  as	possibly  han-
		 dling a two-character newline sequence.

		 There	is a limit to the number of lines that can be matched,
		 imposed by the	way that pcre2grep buffers the input  file  as
		 it  scans  it.	 However,  pcre2grep  ensures that at least 8K
		 characters or the rest	of the file (whichever is the shorter)
		 are  available	for forward matching, and similarly the	previ-
		 ous 8K	characters (or all the previous	characters,  if	 fewer
		 than 8K) are guaranteed to be available for lookbehind	asser-
		 tions.	The -M option does not work when input is read line by
		 line (see --line-buffered.)

       -N newline-type,	--newline=newline-type
		 The PCRE2 library supports five different conventions for in-
		 dicating the ends of lines. They are the single-character se-
		 quences CR (carriage return) and LF (linefeed), the two-char-
		 acter sequence	CRLF, an "anycrlf"  convention,	 which	recog-
		 nizes	any of the preceding three types, and an "any" conven-
		 tion, in which	any Unicode line ending	sequence is assumed to
		 end  a	 line.	The  Unicode sequences are the three just men-
		 tioned, plus  VT  (vertical  tab,  U+000B),  FF  (form	 feed,
		 U+000C),   NEL	 (next	line,  U+0085),	 LS  (line  separator,
		 U+2028), and PS (paragraph separator, U+2029).

		 When the PCRE2	library	is built, a  default  line-ending  se-
		 quence	 is specified.	This is	normally the standard sequence
		 for the operating system. Unless otherwise specified by  this
		 option,  pcre2grep  uses the library's	default.  The possible
		 values	for this option	are CR,	LF,  CRLF,  ANYCRLF,  or  ANY.
		 This  makes  it  possible to use pcre2grep to scan files that
		 have come from	other environments without  having  to	modify
		 their	line  endings.	If the data that is being scanned does
		 not agree with	the convention set by this  option,  pcre2grep
		 may  behave  in  strange ways.	Note that this option does not
		 apply to files	specified by the -f, --exclude-from, or	 --in-
		 clude-from  options,  which are expected to use the operating
		 system's standard newline sequence.

       -n, --line-number
		 Precede each output line by its line number in	the file, fol-
		 lowed	by  a colon for	matching lines or a hyphen for context
		 lines.	If the file name is also being output, it precedes the
		 line  number.	When  the  -M option causes a pattern to match
		 more than one line, only the first is preceded	 by  its  line
		 number. This option is	forced if --line-offsets is used.

       --no-jit	 If  the  PCRE2	library	is built with support for just-in-time
		 compiling (which speeds up matching), pcre2grep automatically
		 makes use of this, unless it was explicitly disabled at build
		 time. This option can be used to disable the use  of  JIT  at
		 run  time. It is provided for testing and working round prob-
		 lems.	It should never	be needed in normal use.

       -o, --only-matching
		 Show only the part of the line	that matched a pattern instead
		 of  the  whole	 line. In this mode, no	context	is shown. That
		 is, the -A, -B, and -C	options	are ignored. If	there is  more
		 than  one  match in a line, each of them is shown separately.
		 If -o is combined with	-v (invert the sense of	the  match  to
		 find non-matching lines), no output is	generated, but the re-
		 turn code is set appropriately. If the	matched	portion	of the
		 line is empty,	nothing	is output unless the file name or line
		 number	are being printed, in which case they are shown	on  an
		 otherwise  empty line.	This option is mutually	exclusive with
		 --file-offsets	and --line-offsets.

       -onumber, --only-matching=number
		 Show only the part of the line	 that  matched	the  capturing
		 parentheses of	the given number. Up to	32 capturing parenthe-
		 ses are supported, and	-o0 is equivalent to -o	without	a num-
		 ber.  Because	these options can be given without an argument
		 (see above), if an argument is	present, it must be  given  in
		 the  same  shell item,	for example, -o3 or --only-matching=2.
		 The comments given for	the non-argument case above also apply
		 to  this  case. If the	specified capturing parentheses	do not
		 exist in the pattern, or were not set in the  match,  nothing
		 is  output unless the file name or line number	are being out-
		 put.

		 If this option	is given multiple times,  multiple  substrings
		 are  output, in the order the options are given. For example,
		 -o3 -o1 -o3 causes the	substrings matched by capturing	paren-
		 theses	 3  and	 1  and	then 3 again to	be output. By default,
		 there is no separator (but see	the next option).

       --om-separator=text
		 Specify a separating string for multiple occurrences  of  -o.
		 The  default is an empty string. Separating strings are never
		 coloured.

       -q, --quiet
		 Work quietly, that is,	display	nothing	except error messages.
		 The  exit  status  indicates  whether or not any matches were
		 found.

       -r, --recursive
		 If any	given path is a	directory, recursively scan the	 files
		 it  contains, taking note of any --include and	--exclude set-
		 tings.	By default, a directory	is read	as a normal  file;  in
		 some  operating  systems this gives an	immediate end-of-file.
		 This option is	a shorthand for	setting	the -d option to  "re-
		 curse".

       --recursion-limit=number
		 See --match-limit above.

       -s, --no-messages
		 Suppress  error  messages  about  non-existent	 or unreadable
		 files.	Such files are quietly skipped.	 However,  the	return
		 code is still 2, even if matches were found in	other files.

       -u, --utf-8
		 Operate in UTF-8 mode.	This option is available only if PCRE2
		 has been compiled with	UTF-8 support. All patterns (including
		 those	for  any --exclude and --include options) and all sub-
		 ject lines that are scanned must be valid  strings  of	 UTF-8
		 characters.

       -V, --version
		 Write	the version numbers of pcre2grep and the PCRE2 library
		 to the	standard output	and then exit. Anything	 else  on  the
		 command line is ignored.

       -v, --invert-match
		 Invert	 the  sense  of	 the match, so that lines which	do not
		 match any of the patterns are the ones	that are found.

       -w, --word-regex, --word-regexp
		 Force the patterns to match only whole	words. This is equiva-
		 lent  to  having \b at	the start and end of the pattern. This
		 option	applies	only to	the patterns that are matched  against
		 the  contents	of files; it does not apply to patterns	speci-
		 fied by any of	the --include or --exclude options.

       -x, --line-regex, --line-regexp
		 Force the patterns to be anchored (each must  start  matching
		 at  the beginning of a	line) and in addition, require them to
		 match entire lines. This is equivalent	 to  having  ^	and  $
		 characters at the start and end of each alternative top-level
		 branch	in every pattern. This option applies only to the pat-
		 terns that are	matched	against	the contents of	files; it does
		 not apply to patterns specified by any	of  the	 --include  or
		 --exclude options.

ENVIRONMENT VARIABLES

       The environment variables LC_ALL	and LC_CTYPE are examined, in that or-
       der, for	a locale. The first one	that is	set is used. This can be over-
       ridden by the --locale option. If no locale is set, the PCRE2 library's
       default (usually	the "C"	locale)	is used.

NEWLINES

       The -N (--newline) option allows	pcre2grep to scan files	with different
       newline conventions from	the default. Any parts of the input files that
       are written to the standard output are copied identically,  with	 what-
       ever  newline sequences they have in the	input. However,	the setting of
       this option does	not affect the interpretation of  files	 specified  by
       the -f, --exclude-from, or --include-from options, which	are assumed to
       use the operating system's standard newline sequence, nor does  it  af-
       fect  the  way  in which	pcre2grep writes informational messages	to the
       standard	error and output streams. For these it uses the	string "\n" to
       indicate	 newlines,  relying on the C I/O library to convert this to an
       appropriate sequence.

OPTIONS	COMPATIBILITY

       Many of the short and long forms	of pcre2grep's options are the same as
       in  the GNU grep	program. Any long option of the	form --xxx-regexp (GNU
       terminology) is also available as --xxx-regex (PCRE2 terminology). How-
       ever,  the  --file-list,	--file-offsets,	--include-dir, --line-offsets,
       --locale, --match-limit,	-M, --multiline, -N,  --newline,  --om-separa-
       tor,  --recursion-limit,	 -u,  and  --utf-8  options  are  specific  to
       pcre2grep, as is	the use	of the --only-matching option with a capturing
       parentheses number.

       Although	 most  of the common options work the same way,	a few are dif-
       ferent in pcre2grep. For	example, the --include option's	argument is  a
       glob  for GNU grep, but a regular expression for	pcre2grep. If both the
       -c and -l options are given, GNU	grep lists only	 file  names,  without
       counts, but pcre2grep gives the counts as well.

OPTIONS	WITH DATA

       There are four different	ways in	which an option	with data can be spec-
       ified.  If a short form option is used, the  data  may  follow  immedi-
       ately, or (with one exception) in the next command line item. For exam-
       ple:

	 -f/some/file
	 -f /some/file

       The exception is	the -o option, which may appear	with or	without	 data.
       Because	of this, if data is present, it	must follow immediately	in the
       same item, for example -o3.

       If a long form option is	used, the data may appear in the same  command
       line  item,  separated by an equals character, or (with two exceptions)
       it may appear in	the next command line item. For	example:

	 --file=/some/file
	 --file	/some/file

       Note, however, that if you want to supply a file	name beginning with  ~
       as  data	 in a shell command, and have the shell	expand ~ to a home di-
       rectory,	you must separate the file name	from the option,  because  the
       shell does not treat ~ specially	unless it is at	the start of an	item.

       The  exceptions	to the above are the --colour (or --color) and --only-
       matching	options, for which the data is optional. If one	of  these  op-
       tions  does  have  data,	 it  must be given in the first	form, using an
       equals character. Otherwise pcre2grep will assume that it has no	data.

MATCHING ERRORS

       It is possible to supply	a regular expression that takes	 a  very  long
       time  to	 fail  to  match certain lines.	Such patterns normally involve
       nested indefinite repeats, for example: (a+)*\d when matched against  a
       line  of	a's with no final digit. The PCRE2 matching function has a re-
       source limit that causes	it to abort in these  circumstances.  If  this
       happens,	 pcre2grep  outputs  an	error message and the line that	caused
       the problem to the standard error stream. If there  are	more  than  20
       such errors, pcre2grep gives up.

       The  --match-limit  option  of pcre2grep	can be used to set the overall
       resource	limit; there is	a second option	called --recursion-limit  that
       sets  a limit on	the amount of memory (usually stack) that is used (see
       the discussion of these options above).

DIAGNOSTICS

       Exit status is 0	if any matches were found, 1 if	no matches were	found,
       and  2  for syntax errors, overlong lines, non-existent or inaccessible
       files (even if matches were found in other files) or too	many  matching
       errors. Using the -s option to suppress error messages about inaccessi-
       ble files does not affect the return code.

SEE ALSO

       pcre2pattern(3),	pcre2syntax(3).

AUTHOR

       Philip Hazel
       University Computing Service
       Cambridge, England.

REVISION

       Last updated: 03	January	2015
       Copyright (c) 1997-2015 University of Cambridge.

PCRE2 10.00			03 January 2015			  PCRE2GREP(1)

NAME | SYNOPSIS | DESCRIPTION | SUPPORT FOR COMPRESSED FILES | BINARY FILES | OPTIONS | ENVIRONMENT VARIABLES | NEWLINES | OPTIONS COMPATIBILITY | OPTIONS WITH DATA | MATCHING ERRORS | DIAGNOSTICS | SEE ALSO | AUTHOR | REVISION

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=pcre2grep&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help