--- embedaddon/pcre/doc/pcregrep.txt 2012/02/21 23:05:51 1.1.1.1 +++ embedaddon/pcre/doc/pcregrep.txt 2012/10/09 09:19:17 1.1.1.2 @@ -98,6 +98,15 @@ SUPPORT FOR COMPRESSED FILES 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 + --binary-files option for a means of changing the way binary files are + handled. + + OPTIONS The order in which some of the options appear can affect the output. @@ -121,167 +130,198 @@ OPTIONS pcregrep guarantees to have up to 8K of following text avail- able 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 + Output number lines of context before each matching line. If filenames and/or line numbers are being output, a hyphen sep- - arator 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, + arator 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, pcregrep guarantees to have up to 8K of preceding text avail- able 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 + binary files, but the only output is "Binary file + 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 + option, binary files are not processed at all; they are + assumed not to be of interest. + --buffer-size=number - Set the parameter that controls how much memory is used for + 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 + 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 individual lines from the files that are being + Do not output individual lines from the files that are being scanned; instead output the number of lines that would other- - wise have been shown. If no lines are selected, the number - zero is output. If several 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 + wise have been shown. If no lines are selected, the number + zero is output. If several 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 ignored. --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 + "--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 pcregrep has to search for all - possible matches in a line, not just one, in order to colour + 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 pcregrep 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 PCREGREP_COLOUR or PCREGREP_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 neither of - the environment variables is set, the default is "1;31", + 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 neither 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, - "action" specifies how it is to be processed. Valid values + If an input path is not a regular file or a directory, + "action" 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), - "recurse" (equivalent to the -r option), or "skip" (silently - skip the path). In the default case, directories are read as - if they were ordinary files. In some operating systems the - effect of reading a directory like this is an immediate end- + to be processed. Valid values are "read" (the default), + "recurse" (equivalent to the -r option), or "skip" (silently + skip the path). In the default case, directories are read as + if they were ordinary files. In some operating systems the + effect of reading a directory like this is an immediate end- of-file. -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 an overall maximum of 100 patterns. They are - applied to each line in the order in which they are defined + 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 an overall maximum of 100 patterns. They are + applied to each line in the order in which they are defined until one matches (or fails to match if -v is used). If -f is - used with -e, the command line patterns are matched first, - followed by the patterns from the file, independent of the - order in which these options are specified. Note that multi- + used with -e, the command line patterns are matched first, + followed by the patterns from the file, independent of the + order in which these options are specified. Note that multi- ple use of -e is not the same as a single pattern with alter- natives. For example, X|Y finds the first character in a line - that is X or Y, whereas if the two patterns are given sepa- + that is X or Y, whereas if the two patterns are given sepa- rately, pcregrep 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 really matters only if you are using -o to show the + Y in the line. It finds Y only if there is no X in the line. + This really matters only if you are using -o to show the part(s) of the line that matched. --exclude=pattern When pcregrep is searching the files in a directory as a con- - sequence of the -r (recursive search) option, any regular + sequence of the -r (recursive search) option, any regular files whose names match the pattern are excluded. Subdirecto- - ries are not excluded by this option; they are searched - recursively, subject to the --exclude-dir and --include_dir - options. The pattern is a PCRE regular expression, and is + ries are not excluded by this option; they are searched + recursively, subject to the --exclude-dir and --include_dir + options. The pattern is a PCRE regular expression, and is matched against the final component of the file name (not the - entire path). If a file name matches both --include and - --exclude, it is excluded. There is no short form for this + entire path). If a file name matches both --include and + --exclude, it is excluded. There is no short form for this option. --exclude-dir=pattern - When pcregrep is searching the contents of a directory as a - consequence of the -r (recursive search) option, any subdi- - rectories whose names match the pattern are excluded. (Note - that the --exclude option does not affect subdirectories.) - The pattern is a PCRE regular expression, and is matched - against the final component of the name (not the entire - path). If a subdirectory name matches both --include-dir and - --exclude-dir, it is excluded. There is no short form for + When pcregrep is searching the contents of a directory as a + consequence of the -r (recursive search) option, any subdi- + rectories whose names match the pattern are excluded. (Note + that the --exclude option does not affect subdirectories.) + The pattern is a PCRE regular expression, and is matched + against the final component of the name (not the entire + path). If a subdirectory name matches both --include-dir and + --exclude-dir, it is excluded. There is no short form for this option. -F, --fixed-strings - Interpret each pattern as a list of fixed strings, separated - by newlines, instead of as a regular expression. The -w - (match as a word) and -x (match whole line) options can be + Interpret each pattern as a list of fixed strings, separated + by newlines, instead of as a regular expression. The -w + (match as a word) and -x (match whole line) options can be used with -F. They apply to each of the fixed strings. A line is selected if any of the fixed strings are found in it (sub- ject to -w or -x, if present). -f filename, --file=filename - Read a number of patterns from the file, one per line, and - match them against each line of input. A data line is output + Read a number of patterns from the file, one per line, and + match them against each line of input. A data line is output if any of the patterns match it. The filename 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; + 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 file names. There is an overall maximum of 100 - patterns. 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. + pattern is taken from the command line; all arguments are + treated as the names of paths to be searched. There is an + overall maximum of 100 patterns. 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. + --file-list=filename + Read a list of files to be searched from the given file, one + per line. Trailing white space is removed from each line, and + blank lines are ignored. These files are searched before any + others that may be listed on the command line. The filename + can be given as "-" to refer to the standard input. If --file + and --file-list are both specified as "-", patterns are read + first. This is useful only when the standard input is a ter- + minal, from which further lines (the list of files) can be + read after an end-of-file indication. + --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 + 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- + separately. This option is mutually exclusive with --line- offsets and --only-matching. -H, --with-filename - Force the inclusion of the filename at the start of output - lines when searching a single file. By default, the filename - is not shown in this case. For matching lines, the filename + Force the inclusion of the filename at the start of output + lines when searching a single file. By default, the filename + is not shown in this case. For matching lines, the filename is followed by a colon; for context lines, a hyphen separator - is used. If a line number is also being output, it follows + is used. If a line number is also being output, it follows the file name. -h, --no-filename - Suppress the output filenames when searching multiple files. - By default, filenames are shown when multiple files are - searched. For matching lines, the filename is followed by a - colon; for context lines, a hyphen separator is used. If a + Suppress the output filenames when searching multiple files. + By default, filenames are shown when multiple files are + searched. For matching lines, the filename 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 + --help Output a help message, giving brief details of the command options and file type support, and then exit. + -I Treat binary files as never matching. This is equivalent to + --binary-files=without-match. + -i, --ignore-case Ignore upper/lower case distinctions during comparisons. @@ -540,12 +580,12 @@ NEWLINES OPTIONS COMPATIBILITY Many of the short and long forms of pcregrep's options are the same as - in the GNU grep program (version 2.5.4). Any long option of the form - --xxx-regexp (GNU terminology) is also available as --xxx-regex (PCRE - terminology). However, the --file-offsets, --include-dir, --line-off- - sets, --locale, --match-limit, -M, --multiline, -N, --newline, --recur- - sion-limit, -u, and --utf-8 options are specific to pcregrep, as is the - use of the --only-matching option with a capturing parentheses number. + in the GNU grep program. Any long option of the form --xxx-regexp (GNU + terminology) is also available as --xxx-regex (PCRE terminology). How- + ever, the --file-list, --file-offsets, --include-dir, --line-offsets, + --locale, --match-limit, -M, --multiline, -N, --newline, --recursion- + limit, -u, and --utf-8 options are specific to pcregrep, 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 pcregrep. For example, the --include option's argument is a @@ -626,5 +666,5 @@ AUTHOR REVISION - Last updated: 06 September 2011 - Copyright (c) 1997-2011 University of Cambridge. + Last updated: 04 March 2012 + Copyright (c) 1997-2012 University of Cambridge.