Revision: 923
http://www.exim.org/viewvc/pcre2?view=rev&revision=923
Author: ph10
Date: 2018-02-25 18:00:56 +0000 (Sun, 25 Feb 2018)
Log Message:
-----------
Update HTML and derived documentation.
Modified Paths:
--------------
code/trunk/doc/html/README.txt
code/trunk/doc/html/pcre2build.html
code/trunk/doc/html/pcre2grep.html
code/trunk/doc/pcre2.txt
code/trunk/doc/pcre2grep.txt
Modified: code/trunk/doc/html/README.txt
===================================================================
--- code/trunk/doc/html/README.txt 2018-02-25 18:00:29 UTC (rev 922)
+++ code/trunk/doc/html/README.txt 2018-02-25 18:00:56 UTC (rev 923)
@@ -171,11 +171,13 @@
give large performance improvements on certain platforms, add --enable-jit to
the "configure" command. This support is available only for certain hardware
architectures. If you try to enable it on an unsupported architecture, there
- will be a compile time error. If you are running under SELinux you may also
- want to add --enable-jit-sealloc, which enables the use of an execmem
- allocator in JIT that is compatible with SELinux. This has no effect if JIT
- is not enabled.
+ will be a compile time error. If in doubt, use --enable-jit=auto, which
+ enables JIT only if the current hardware is supported.
+. If you are enabling JIT under SELinux you may also want to add
+ --enable-jit-sealloc, which enables the use of an execmem allocator in JIT
+ that is compatible with SELinux. This has no effect if JIT is not enabled.
+
. If you do not want to make use of the default support for UTF-8 Unicode
character strings in the 8-bit library, UTF-16 Unicode character strings in
the 16-bit library, or UTF-32 Unicode character strings in the 32-bit
@@ -883,4 +885,4 @@
Philip Hazel
Email local part: ph10
Email domain: cam.ac.uk
-Last updated: 12 September 2017
+Last updated: 25 February 2018
Modified: code/trunk/doc/html/pcre2build.html
===================================================================
--- code/trunk/doc/html/pcre2build.html 2018-02-25 18:00:29 UTC (rev 922)
+++ code/trunk/doc/html/pcre2build.html 2018-02-25 18:00:56 UTC (rev 923)
@@ -82,7 +82,8 @@
begin with --enable or --disable. Because of the way that <b>configure</b>
works, --enable and --disable always come in pairs, so the complementary option
always exists as well, but as it specifies the default, it is not described.
-Options that specify values have names that start with --with.
+Options that specify values have names that start with --with. At the end of a
+<b>configure</b> run, a summary of the configuration is output.
</P>
<br><a name="SEC3" href="#TOC1">BUILDING 8-BIT, 16-BIT AND 32-BIT LIBRARIES</a><br>
<P>
@@ -170,9 +171,16 @@
--enable-jit
</pre>
This support is available only for certain hardware architectures. If this
-option is set for an unsupported architecture, a building error occurs. If you
-are running under SELinux you may also want to add
+option is set for an unsupported architecture, a building error occurs.
+If in doubt, use
<pre>
+ --enable-jit=auto
+</pre>
+which enables JIT only if the current hardware is supported. You can check
+if JIT is enabled in the configuration summary that is output at the end of a
+<b>configure</b> run. If you are enabling JIT under SELinux you may also want to
+add
+<pre>
--enable-jit-sealloc
</pre>
which enables the use of an execmem allocator in JIT that is compatible with
@@ -565,9 +573,9 @@
</P>
<br><a name="SEC25" href="#TOC1">REVISION</a><br>
<P>
-Last updated: 18 July 2017
+Last updated: 25 February 2018
<br>
-Copyright © 1997-2017 University of Cambridge.
+Copyright © 1997-2018 University of Cambridge.
<br>
<p>
Return to the <a href="index.html">PCRE2 index page</a>.
Modified: code/trunk/doc/html/pcre2grep.html
===================================================================
--- code/trunk/doc/html/pcre2grep.html 2018-02-25 18:00:29 UTC (rev 922)
+++ code/trunk/doc/html/pcre2grep.html 2018-02-25 18:00:56 UTC (rev 923)
@@ -17,17 +17,18 @@
<li><a name="TOC2" href="#SEC2">DESCRIPTION</a>
<li><a name="TOC3" href="#SEC3">SUPPORT FOR COMPRESSED FILES</a>
<li><a name="TOC4" href="#SEC4">BINARY FILES</a>
-<li><a name="TOC5" href="#SEC5">OPTIONS</a>
-<li><a name="TOC6" href="#SEC6">ENVIRONMENT VARIABLES</a>
-<li><a name="TOC7" href="#SEC7">NEWLINES</a>
-<li><a name="TOC8" href="#SEC8">OPTIONS COMPATIBILITY</a>
-<li><a name="TOC9" href="#SEC9">OPTIONS WITH DATA</a>
-<li><a name="TOC10" href="#SEC10">USING PCRE2'S CALLOUT FACILITY</a>
-<li><a name="TOC11" href="#SEC11">MATCHING ERRORS</a>
-<li><a name="TOC12" href="#SEC12">DIAGNOSTICS</a>
-<li><a name="TOC13" href="#SEC13">SEE ALSO</a>
-<li><a name="TOC14" href="#SEC14">AUTHOR</a>
-<li><a name="TOC15" href="#SEC15">REVISION</a>
+<li><a name="TOC5" href="#SEC5">BINARY ZEROS IN PATTERNS</a>
+<li><a name="TOC6" href="#SEC6">OPTIONS</a>
+<li><a name="TOC7" href="#SEC7">ENVIRONMENT VARIABLES</a>
+<li><a name="TOC8" href="#SEC8">NEWLINES</a>
+<li><a name="TOC9" href="#SEC9">OPTIONS COMPATIBILITY</a>
+<li><a name="TOC10" href="#SEC10">OPTIONS WITH DATA</a>
+<li><a name="TOC11" href="#SEC11">USING PCRE2'S CALLOUT FACILITY</a>
+<li><a name="TOC12" href="#SEC12">MATCHING ERRORS</a>
+<li><a name="TOC13" href="#SEC13">DIAGNOSTICS</a>
+<li><a name="TOC14" href="#SEC14">SEE ALSO</a>
+<li><a name="TOC15" href="#SEC15">AUTHOR</a>
+<li><a name="TOC16" href="#SEC16">REVISION</a>
</ul>
<br><a name="SEC1" href="#TOC1">SYNOPSIS</a><br>
<P>
@@ -150,8 +151,14 @@
a binary file is not applied. See the <b>--binary-files</b> option for a means
of changing the way binary files are handled.
</P>
-<br><a name="SEC5" href="#TOC1">OPTIONS</a><br>
+<br><a name="SEC5" href="#TOC1">BINARY ZEROS IN PATTERNS</a><br>
<P>
+Patterns passed from the command line are strings that are terminated by a
+binary zero, so cannot contain internal zeros. However, patterns that are read
+from a file via the <b>-f</b> option may contain binary zeros.
+</P>
+<br><a name="SEC6" href="#TOC1">OPTIONS</a><br>
+<P>
The order in which some of the options appear can affect the output. For
example, both the <b>-H</b> and <b>-l</b> options affect the printing of file
names. Whichever comes later in the command line will be the one that takes
@@ -355,12 +362,15 @@
<P>
<b>-f</b> <i>filename</i>, <b>--file=</b><i>filename</i>
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 <b>--newline</b> 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 <b>-e</b> above.
+input. As is the case with patterns on the command line, no delimiters should
+be used. What constitutes a newline when reading the file is the operating
+system's default interpretation of \n. The <b>--newline</b> 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. Patterns read from a file in this way may contain binary
+zeros, which are treated as ordinary data characters. See also the comments
+about multiple patterns versus a single pattern with alternatives in the
+description of <b>-e</b> above.
<br>
<br>
If this option is given more than once, all the specified files are read. A
@@ -373,14 +383,15 @@
<P>
<b>--file-list</b>=<i>filename</i>
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 <b>--file</b> and <b>--file-list</b> are both specified 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, one per line. What constitutes a newline when reading the file is the
+operating system's default. 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 <b>--file</b> and <b>--file-list</b> are both specified 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.
</P>
<P>
<b>--file-offsets</b>
@@ -764,7 +775,7 @@
matched against the contents of files; it does not apply to patterns specified
by any of the <b>--include</b> or <b>--exclude</b> options.
</P>
-<br><a name="SEC6" href="#TOC1">ENVIRONMENT VARIABLES</a><br>
+<br><a name="SEC7" href="#TOC1">ENVIRONMENT VARIABLES</a><br>
<P>
The environment variables <b>LC_ALL</b> and <b>LC_CTYPE</b> are examined, in that
order, for a locale. The first one that is set is used. This can be overridden
@@ -771,20 +782,21 @@
by the <b>--locale</b> option. If no locale is set, the PCRE2 library's default
(usually the "C" locale) is used.
</P>
-<br><a name="SEC7" href="#TOC1">NEWLINES</a><br>
+<br><a name="SEC8" href="#TOC1">NEWLINES</a><br>
<P>
The <b>-N</b> (<b>--newline</b>) option allows <b>pcre2grep</b> 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 whatever
newline sequences they have in the input. However, the setting of this option
-does not affect the interpretation of files specified by the <b>-f</b>,
-<b>--exclude-from</b>, or <b>--include-from</b> options, which are assumed to use
-the operating system's standard newline sequence, nor does it affect the way in
-which <b>pcre2grep</b> 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.
+affects only the way scanned files are processed. It does not affect the
+interpretation of files specified by the <b>-f</b>, <b>--file-list</b>,
+<b>--exclude-from</b>, or <b>--include-from</b> options, nor does it affect the
+way in which <b>pcre2grep</b> 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.
</P>
-<br><a name="SEC8" href="#TOC1">OPTIONS COMPATIBILITY</a><br>
+<br><a name="SEC9" href="#TOC1">OPTIONS COMPATIBILITY</a><br>
<P>
Many of the short and long forms of <b>pcre2grep</b>'s options are the same
as in the GNU <b>grep</b> program. Any long option of the form
@@ -804,7 +816,7 @@
<b>-c</b> and <b>-l</b> options are given, GNU grep lists only file names,
without counts, but <b>pcre2grep</b> gives the counts as well.
</P>
-<br><a name="SEC9" href="#TOC1">OPTIONS WITH DATA</a><br>
+<br><a name="SEC10" href="#TOC1">OPTIONS WITH DATA</a><br>
<P>
There are four different ways in which an option with data can be specified.
If a short form option is used, the data may follow immediately, or (with one
@@ -836,7 +848,7 @@
options does have data, it must be given in the first form, using an equals
character. Otherwise <b>pcre2grep</b> will assume that it has no data.
</P>
-<br><a name="SEC10" href="#TOC1">USING PCRE2'S CALLOUT FACILITY</a><br>
+<br><a name="SEC11" href="#TOC1">USING PCRE2'S CALLOUT FACILITY</a><br>
<P>
<b>pcre2grep</b> has, by default, support for calling external programs or
scripts or echoing specific strings during matching by making use of PCRE2's
@@ -906,7 +918,7 @@
the callout output but not any output from an actual match, you should end the
relevant pattern with (*FAIL).
</P>
-<br><a name="SEC11" href="#TOC1">MATCHING ERRORS</a><br>
+<br><a name="SEC12" href="#TOC1">MATCHING ERRORS</a><br>
<P>
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
@@ -922,7 +934,7 @@
memory used during matching; see the discussion of <b>--heap-limit</b> and
<b>--depth-limit</b> above.
</P>
-<br><a name="SEC12" href="#TOC1">DIAGNOSTICS</a><br>
+<br><a name="SEC13" href="#TOC1">DIAGNOSTICS</a><br>
<P>
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
@@ -934,11 +946,11 @@
When run under VMS, the return code is placed in the symbol PCRE2GREP_RC
because VMS does not distinguish between exit(0) and exit(1).
</P>
-<br><a name="SEC13" href="#TOC1">SEE ALSO</a><br>
+<br><a name="SEC14" href="#TOC1">SEE ALSO</a><br>
<P>
<b>pcre2pattern</b>(3), <b>pcre2syntax</b>(3), <b>pcre2callout</b>(3).
</P>
-<br><a name="SEC14" href="#TOC1">AUTHOR</a><br>
+<br><a name="SEC15" href="#TOC1">AUTHOR</a><br>
<P>
Philip Hazel
<br>
@@ -947,11 +959,11 @@
Cambridge, England.
<br>
</P>
-<br><a name="SEC15" href="#TOC1">REVISION</a><br>
+<br><a name="SEC16" href="#TOC1">REVISION</a><br>
<P>
-Last updated: 13 November 2017
+Last updated: 24 February 2018
<br>
-Copyright © 1997-2017 University of Cambridge.
+Copyright © 1997-2018 University of Cambridge.
<br>
<p>
Return to the <a href="index.html">PCRE2 index page</a>.
Modified: code/trunk/doc/pcre2.txt
===================================================================
--- code/trunk/doc/pcre2.txt 2018-02-25 18:00:29 UTC (rev 922)
+++ code/trunk/doc/pcre2.txt 2018-02-25 18:00:56 UTC (rev 923)
@@ -170,8 +170,8 @@
Last updated: 01 April 2017
Copyright (c) 1997-2017 University of Cambridge.
------------------------------------------------------------------------------
-
-
+
+
PCRE2API(3) Library Functions Manual PCRE2API(3)
@@ -3477,8 +3477,8 @@
Last updated: 31 December 2017
Copyright (c) 1997-2017 University of Cambridge.
------------------------------------------------------------------------------
-
-
+
+
PCRE2BUILD(3) Library Functions Manual PCRE2BUILD(3)
@@ -3526,18 +3526,19 @@
ure works, --enable and --disable always come in pairs, so the comple-
mentary option always exists as well, but as it specifies the default,
it is not described. Options that specify values have names that start
- with --with.
+ with --with. At the end of a configure run, a summary of the configura-
+ tion is output.
BUILDING 8-BIT, 16-BIT AND 32-BIT LIBRARIES
- By default, a library called libpcre2-8 is built, containing functions
- that take string arguments contained in arrays of bytes, interpreted
- either as single-byte characters, or UTF-8 strings. You can also build
- two other libraries, called libpcre2-16 and libpcre2-32, which process
- strings that are contained in arrays of 16-bit and 32-bit code units,
+ By default, a library called libpcre2-8 is built, containing functions
+ that take string arguments contained in arrays of bytes, interpreted
+ either as single-byte characters, or UTF-8 strings. You can also build
+ two other libraries, called libpcre2-16 and libpcre2-32, which process
+ strings that are contained in arrays of 16-bit and 32-bit code units,
respectively. These can be interpreted either as single-unit characters
- or UTF-16/UTF-32 strings. To build these additional libraries, add one
+ or UTF-16/UTF-32 strings. To build these additional libraries, add one
or both of the following to the configure command:
--enable-pcre2-16
@@ -3547,16 +3548,16 @@
--disable-pcre2-8
- as well. At least one of the three libraries must be built. Note that
- the POSIX wrapper is for the 8-bit library only, and that pcre2grep is
- an 8-bit program. Neither of these are built if you select only the
+ as well. At least one of the three libraries must be built. Note that
+ the POSIX wrapper is for the 8-bit library only, and that pcre2grep is
+ an 8-bit program. Neither of these are built if you select only the
16-bit or 32-bit libraries.
BUILDING SHARED AND STATIC LIBRARIES
- The Autotools PCRE2 building process uses libtool to build both shared
- and static libraries by default. You can suppress an unwanted library
+ The Autotools PCRE2 building process uses libtool to build both shared
+ and static libraries by default. You can suppress an unwanted library
by adding one of
--disable-shared
@@ -3567,31 +3568,31 @@
UNICODE AND UTF SUPPORT
- By default, PCRE2 is built with support for Unicode and UTF character
+ By default, PCRE2 is built with support for Unicode and UTF character
strings. To build it without Unicode support, add
--disable-unicode
- to the configure command. This setting applies to all three libraries.
- It is not possible to build one library with Unicode support, and
+ to the configure command. This setting applies to all three libraries.
+ It is not possible to build one library with Unicode support, and
another without, in the same configuration.
- Of itself, Unicode support does not make PCRE2 treat strings as UTF-8,
+ Of itself, Unicode support does not make PCRE2 treat strings as UTF-8,
UTF-16 or UTF-32. To do that, applications that use the library can set
- the PCRE2_UTF option when they call pcre2_compile() to compile a pat-
- tern. Alternatively, patterns may be started with (*UTF) unless the
+ the PCRE2_UTF option when they call pcre2_compile() to compile a pat-
+ tern. Alternatively, patterns may be started with (*UTF) unless the
application has locked this out by setting PCRE2_NEVER_UTF.
UTF support allows the libraries to process character code points up to
- 0x10ffff in the strings that they handle. Unicode support also gives
- access to the Unicode properties of characters, using pattern escapes
+ 0x10ffff in the strings that they handle. Unicode support also gives
+ access to the Unicode properties of characters, using pattern escapes
such as \P, \p, and \X. Only the general category properties such as Lu
- and Nd are supported. Details are given in the pcre2pattern documenta-
+ and Nd are supported. Details are given in the pcre2pattern documenta-
tion.
Pattern escapes such as \d and \w do not by default make use of Unicode
- properties. The application can request that they do by setting the
- PCRE2_UCP option. Unless the application has set PCRE2_NEVER_UCP, a
+ properties. The application can request that they do by setting the
+ PCRE2_UCP option. Unless the application has set PCRE2_NEVER_UCP, a
pattern may also request this by starting with (*UCP).
@@ -3598,9 +3599,9 @@
DISABLING THE USE OF \C
The \C escape sequence, which matches a single code unit, even in a UTF
- mode, can cause unpredictable behaviour because it may leave the cur-
- rent matching point in the middle of a multi-code-unit character. The
- application can lock it out by setting the PCRE2_NEVER_BACKSLASH_C
+ mode, can cause unpredictable behaviour because it may leave the cur-
+ rent matching point in the middle of a multi-code-unit character. The
+ application can lock it out by setting the PCRE2_NEVER_BACKSLASH_C
option when calling pcre2_compile(). There is also a build-time option
--enable-never-backslash-C
@@ -3610,15 +3611,22 @@
JUST-IN-TIME COMPILER SUPPORT
- Just-in-time (JIT) compiler support is included in the build by speci-
+ Just-in-time (JIT) compiler support is included in the build by speci-
fying
--enable-jit
- This support is available only for certain hardware architectures. If
- this option is set for an unsupported architecture, a building error
- occurs. If you are running under SELinux you may also want to add
+ This support is available only for certain hardware architectures. If
+ this option is set for an unsupported architecture, a building error
+ occurs. If in doubt, use
+ --enable-jit=auto
+
+ which enables JIT only if the current hardware is supported. You can
+ check if JIT is enabled in the configuration summary that is output at
+ the end of a configure run. If you are enabling JIT under SELinux you
+ may also want to add
+
--enable-jit-sealloc
which enables the use of an execmem allocator in JIT that is compatible
@@ -4020,11 +4028,11 @@
REVISION
- Last updated: 18 July 2017
- Copyright (c) 1997-2017 University of Cambridge.
+ Last updated: 25 February 2018
+ Copyright (c) 1997-2018 University of Cambridge.
------------------------------------------------------------------------------
-
-
+
+
PCRE2CALLOUT(3) Library Functions Manual PCRE2CALLOUT(3)
@@ -4447,8 +4455,8 @@
Last updated: 22 December 2017
Copyright (c) 1997-2017 University of Cambridge.
------------------------------------------------------------------------------
-
-
+
+
PCRE2COMPAT(3) Library Functions Manual PCRE2COMPAT(3)
@@ -4645,8 +4653,8 @@
Last updated: 18 April 2017
Copyright (c) 1997-2017 University of Cambridge.
------------------------------------------------------------------------------
-
-
+
+
PCRE2JIT(3) Library Functions Manual PCRE2JIT(3)
@@ -5039,8 +5047,8 @@
Last updated: 31 March 2017
Copyright (c) 1997-2017 University of Cambridge.
------------------------------------------------------------------------------
-
-
+
+
PCRE2LIMITS(3) Library Functions Manual PCRE2LIMITS(3)
@@ -5110,8 +5118,8 @@
Last updated: 30 March 2017
Copyright (c) 1997-2017 University of Cambridge.
------------------------------------------------------------------------------
-
-
+
+
PCRE2MATCHING(3) Library Functions Manual PCRE2MATCHING(3)
@@ -5329,8 +5337,8 @@
Last updated: 29 September 2014
Copyright (c) 1997-2014 University of Cambridge.
------------------------------------------------------------------------------
-
-
+
+
PCRE2PARTIAL(3) Library Functions Manual PCRE2PARTIAL(3)
@@ -5769,8 +5777,8 @@
Last updated: 22 December 2014
Copyright (c) 1997-2014 University of Cambridge.
------------------------------------------------------------------------------
-
-
+
+
PCRE2PATTERN(3) Library Functions Manual PCRE2PATTERN(3)
@@ -8880,8 +8888,8 @@
Last updated: 12 September 2017
Copyright (c) 1997-2017 University of Cambridge.
------------------------------------------------------------------------------
-
-
+
+
PCRE2PERFORM(3) Library Functions Manual PCRE2PERFORM(3)
@@ -9108,8 +9116,8 @@
Last updated: 08 April 2017
Copyright (c) 1997-2017 University of Cambridge.
------------------------------------------------------------------------------
-
-
+
+
PCRE2POSIX(3) Library Functions Manual PCRE2POSIX(3)
@@ -9416,8 +9424,8 @@
Last updated: 15 June 2017
Copyright (c) 1997-2017 University of Cambridge.
------------------------------------------------------------------------------
-
-
+
+
PCRE2SAMPLE(3) Library Functions Manual PCRE2SAMPLE(3)
@@ -9685,8 +9693,8 @@
Last updated: 21 March 2017
Copyright (c) 1997-2017 University of Cambridge.
------------------------------------------------------------------------------
-
-
+
+
PCRE2SYNTAX(3) Library Functions Manual PCRE2SYNTAX(3)
@@ -10133,8 +10141,8 @@
Last updated: 17 June 2017
Copyright (c) 1997-2017 University of Cambridge.
------------------------------------------------------------------------------
-
-
+
+
PCRE2UNICODE(3) Library Functions Manual PCRE2UNICODE(3)
@@ -10390,5 +10398,5 @@
Last updated: 17 May 2017
Copyright (c) 1997-2017 University of Cambridge.
------------------------------------------------------------------------------
-
-
+
+
Modified: code/trunk/doc/pcre2grep.txt
===================================================================
--- code/trunk/doc/pcre2grep.txt 2018-02-25 18:00:29 UTC (rev 922)
+++ code/trunk/doc/pcre2grep.txt 2018-02-25 18:00:56 UTC (rev 923)
@@ -122,6 +122,13 @@
handled.
+BINARY ZEROS IN PATTERNS
+
+ Patterns passed from the command line are strings that are terminated
+ by a binary zero, so cannot contain internal zeros. However, patterns
+ that are read from a file via the -f option may contain binary zeros.
+
+
OPTIONS
The order in which some of the options appear can affect the output.
@@ -329,36 +336,40 @@
-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 pat-
- terns versus a single pattern with alternatives in the
- description of -e above.
+ against each line of input. As is the case with patterns on
+ the command line, no delimiters should be used. What consti-
+ tutes a newline when reading the file is the operating sys-
+ tem's default interpretation of \n. 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. Patterns
+ read from a file in this way may contain binary zeros, which
+ are treated as ordinary data characters. See also the com-
+ ments 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
+ 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.
+ Read a list of files and/or directories that are to be
+ scanned from the given file, one per line. What constitutes a
+ newline when reading the file is the operating system's
+ default. 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 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. 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
@@ -758,13 +769,13 @@
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
- affect 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.
+ this option affects only the way scanned files are processed. It does
+ not affect the interpretation of files specified by the -f, --file-
+ list, --exclude-from, or --include-from options, nor does it affect 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 appropri-
+ ate sequence.
OPTIONS COMPATIBILITY
@@ -929,5 +940,5 @@
REVISION
- Last updated: 13 November 2017
- Copyright (c) 1997-2017 University of Cambridge.
+ Last updated: 24 February 2018
+ Copyright (c) 1997-2018 University of Cambridge.