{"id":18714177,"url":"https://github.com/pfultz2/pcre","last_synced_at":"2025-07-04T21:34:34.582Z","repository":{"id":143674693,"uuid":"425087870","full_name":"pfultz2/pcre","owner":"pfultz2","description":null,"archived":false,"fork":false,"pushed_at":"2021-11-05T21:30:09.000Z","size":2091,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-12-28T09:20:38.780Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pfultz2.png","metadata":{"files":{"readme":"README","changelog":"ChangeLog","contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS","dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-11-05T21:23:50.000Z","updated_at":"2022-04-20T13:50:41.000Z","dependencies_parsed_at":null,"dependency_job_id":"e4515fa7-11f4-4042-aa92-b9510e0cd150","html_url":"https://github.com/pfultz2/pcre","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pfultz2%2Fpcre","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pfultz2%2Fpcre/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pfultz2%2Fpcre/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pfultz2%2Fpcre/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pfultz2","download_url":"https://codeload.github.com/pfultz2/pcre/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239576790,"owners_count":19662114,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-07T12:51:38.728Z","updated_at":"2025-02-19T01:16:04.636Z","avatar_url":"https://github.com/pfultz2.png","language":"C","readme":"README file for PCRE (Perl-compatible regular expression library)\n-----------------------------------------------------------------\n\nNOTE: This set of files relates to PCRE releases that use the original API,\nwith library names libpcre, libpcre16, and libpcre32. January 2015 saw the\nfirst release of a new API, known as PCRE2, with release numbers starting at\n10.00 and library names libpcre2-8, libpcre2-16, and libpcre2-32. The old\nlibraries (now called PCRE1) are now at end of life, and 8.45 is the final\nrelease. New projects are advised to use the new PCRE2 libraries.\n\n\nThe latest release of PCRE1 is always available in three alternative formats\nfrom:\n\n  https://ftp.pcre.org/pub/pcre/pcre-x.xx.tar.gz\n  https://ftp.pcre.org/pub/pcre/pcre-x.xx.tar.bz2\n  https://ftp.pcre.org/pub/pcre/pcre-x.xx.tar.zip\n\n\nThere is a mailing list for discussion about the development of PCRE at\npcre-dev@exim.org. You can access the archives and subscribe or manage your\nsubscription here:\n\n   https://lists.exim.org/mailman/listinfo/pcre-dev\n\nPlease read the NEWS file if you are upgrading from a previous release.\nThe contents of this README file are:\n\n  The PCRE APIs\n  Documentation for PCRE\n  Contributions by users of PCRE\n  Building PCRE on non-Unix-like systems\n  Building PCRE without using autotools\n  Building PCRE using autotools\n  Retrieving configuration information\n  Shared libraries\n  Cross-compiling using autotools\n  Using HP's ANSI C++ compiler (aCC)\n  Compiling in Tru64 using native compilers\n  Using Sun's compilers for Solaris\n  Using PCRE from MySQL\n  Making new tarballs\n  Testing PCRE\n  Character tables\n  File manifest\n\n\nThe PCRE APIs\n-------------\n\nPCRE is written in C, and it has its own API. There are three sets of\nfunctions, one for the 8-bit library, which processes strings of bytes, one for\nthe 16-bit library, which processes strings of 16-bit values, and one for the\n32-bit library, which processes strings of 32-bit values. The distribution also\nincludes a set of C++ wrapper functions (see the pcrecpp man page for details),\ncourtesy of Google Inc., which can be used to call the 8-bit PCRE library from\nC++. Other C++ wrappers have been created from time to time. See, for example:\nhttps://github.com/YasserAsmi/regexp, which aims to be simple and similar in\nstyle to the C API.\n\nThe distribution also contains a set of C wrapper functions (again, just for\nthe 8-bit library) that are based on the POSIX regular expression API (see the\npcreposix man page). These end up in the library called libpcreposix. Note that\nthis just provides a POSIX calling interface to PCRE; the regular expressions\nthemselves still follow Perl syntax and semantics. The POSIX API is restricted,\nand does not give full access to all of PCRE's facilities.\n\nThe header file for the POSIX-style functions is called pcreposix.h. The\nofficial POSIX name is regex.h, but I did not want to risk possible problems\nwith existing files of that name by distributing it that way. To use PCRE with\nan existing program that uses the POSIX API, pcreposix.h will have to be\nrenamed or pointed at by a link.\n\nIf you are using the POSIX interface to PCRE and there is already a POSIX regex\nlibrary installed on your system, as well as worrying about the regex.h header\nfile (as mentioned above), you must also take care when linking programs to\nensure that they link with PCRE's libpcreposix library. Otherwise they may pick\nup the POSIX functions of the same name from the other library.\n\nOne way of avoiding this confusion is to compile PCRE with the addition of\n-Dregcomp=PCREregcomp (and similarly for the other POSIX functions) to the\ncompiler flags (CFLAGS if you are using \"configure\" -- see below). This has the\neffect of renaming the functions so that the names no longer clash. Of course,\nyou have to do the same thing for your applications, or write them using the\nnew names.\n\n\nDocumentation for PCRE\n----------------------\n\nIf you install PCRE in the normal way on a Unix-like system, you will end up\nwith a set of man pages whose names all start with \"pcre\". The one that is just\ncalled \"pcre\" lists all the others. In addition to these man pages, the PCRE\ndocumentation is supplied in two other forms:\n\n  1. There are files called doc/pcre.txt, doc/pcregrep.txt, and\n     doc/pcretest.txt in the source distribution. The first of these is a\n     concatenation of the text forms of all the section 3 man pages except\n     the listing of pcredemo.c and those that summarize individual functions.\n     The other two are the text forms of the section 1 man pages for the\n     pcregrep and pcretest commands. These text forms are provided for ease of\n     scanning with text editors or similar tools. They are installed in\n     \u003cprefix\u003e/share/doc/pcre, where \u003cprefix\u003e is the installation prefix\n     (defaulting to /usr/local).\n\n  2. A set of files containing all the documentation in HTML form, hyperlinked\n     in various ways, and rooted in a file called index.html, is distributed in\n     doc/html and installed in \u003cprefix\u003e/share/doc/pcre/html.\n\nUsers of PCRE have contributed files containing the documentation for various\nreleases in CHM format. These can be found in the Contrib directory of the FTP\nsite (see next section).\n\n\nContributions by users of PCRE\n------------------------------\n\nYou can find contributions from PCRE users in the directory\n\n  ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre/Contrib\n\nThere is a README file giving brief descriptions of what they are. Some are\ncomplete in themselves; others are pointers to URLs containing relevant files.\nSome of this material is likely to be well out-of-date. Several of the earlier\ncontributions provided support for compiling PCRE on various flavours of\nWindows (I myself do not use Windows). Nowadays there is more Windows support\nin the standard distribution, so these contibutions have been archived.\n\nA PCRE user maintains downloadable Windows binaries of the pcregrep and\npcretest programs here:\n\n  http://www.rexegg.com/pcregrep-pcretest.html\n\n\nBuilding PCRE on non-Unix-like systems\n--------------------------------------\n\nFor a non-Unix-like system, please read the comments in the file\nNON-AUTOTOOLS-BUILD, though if your system supports the use of \"configure\" and\n\"make\" you may be able to build PCRE using autotools in the same way as for\nmany Unix-like systems.\n\nPCRE can also be configured using the GUI facility provided by CMake's\ncmake-gui command. This creates Makefiles, solution files, etc. The file\nNON-AUTOTOOLS-BUILD has information about CMake.\n\nPCRE has been compiled on many different operating systems. It should be\nstraightforward to build PCRE on any system that has a Standard C compiler and\nlibrary, because it uses only Standard C functions.\n\n\nBuilding PCRE without using autotools\n-------------------------------------\n\nThe use of autotools (in particular, libtool) is problematic in some\nenvironments, even some that are Unix or Unix-like. See the NON-AUTOTOOLS-BUILD\nfile for ways of building PCRE without using autotools.\n\n\nBuilding PCRE using autotools\n-----------------------------\n\nIf you are using HP's ANSI C++ compiler (aCC), please see the special note\nin the section entitled \"Using HP's ANSI C++ compiler (aCC)\" below.\n\nThe following instructions assume the use of the widely used \"configure; make;\nmake install\" (autotools) process.\n\nTo build PCRE on system that supports autotools, first run the \"configure\"\ncommand from the PCRE distribution directory, with your current directory set\nto the directory where you want the files to be created. This command is a\nstandard GNU \"autoconf\" configuration script, for which generic instructions\nare supplied in the file INSTALL.\n\nMost commonly, people build PCRE within its own distribution directory, and in\nthis case, on many systems, just running \"./configure\" is sufficient. However,\nthe usual methods of changing standard defaults are available. For example:\n\nCFLAGS='-O2 -Wall' ./configure --prefix=/opt/local\n\nThis command specifies that the C compiler should be run with the flags '-O2\n-Wall' instead of the default, and that \"make install\" should install PCRE\nunder /opt/local instead of the default /usr/local.\n\nIf you want to build in a different directory, just run \"configure\" with that\ndirectory as current. For example, suppose you have unpacked the PCRE source\ninto /source/pcre/pcre-xxx, but you want to build it in /build/pcre/pcre-xxx:\n\ncd /build/pcre/pcre-xxx\n/source/pcre/pcre-xxx/configure\n\nPCRE is written in C and is normally compiled as a C library. However, it is\npossible to build it as a C++ library, though the provided building apparatus\ndoes not have any features to support this.\n\nThere are some optional features that can be included or omitted from the PCRE\nlibrary. They are also documented in the pcrebuild man page.\n\n. By default, both shared and static libraries are built. You can change this\n  by adding one of these options to the \"configure\" command:\n\n  --disable-shared\n  --disable-static\n\n  (See also \"Shared libraries on Unix-like systems\" below.)\n\n. By default, only the 8-bit library is built. If you add --enable-pcre16 to\n  the \"configure\" command, the 16-bit library is also built. If you add\n  --enable-pcre32 to the \"configure\" command, the 32-bit library is also built.\n  If you want only the 16-bit or 32-bit library, use --disable-pcre8 to disable\n  building the 8-bit library.\n\n. If you are building the 8-bit library and want to suppress the building of\n  the C++ wrapper library, you can add --disable-cpp to the \"configure\"\n  command. Otherwise, when \"configure\" is run without --disable-pcre8, it will\n  try to find a C++ compiler and C++ header files, and if it succeeds, it will\n  try to build the C++ wrapper.\n\n. If you want to include support for just-in-time compiling, which can give\n  large performance improvements on certain platforms, add --enable-jit to the\n  \"configure\" command. This support is available only for certain hardware\n  architectures. If you try to enable it on an unsupported architecture, there\n  will be a compile time error.\n\n. When JIT support is enabled, pcregrep automatically makes use of it, unless\n  you add --disable-pcregrep-jit to the \"configure\" command.\n\n. If you want to make use of the support for UTF-8 Unicode character strings in\n  the 8-bit library, or UTF-16 Unicode character strings in the 16-bit library,\n  or UTF-32 Unicode character strings in the 32-bit library, you must add\n  --enable-utf to the \"configure\" command. Without it, the code for handling\n  UTF-8, UTF-16 and UTF-8 is not included in the relevant library. Even\n  when --enable-utf is included, the use of a UTF encoding still has to be\n  enabled by an option at run time. When PCRE is compiled with this option, its\n  input can only either be ASCII or UTF-8/16/32, even when running on EBCDIC\n  platforms. It is not possible to use both --enable-utf and --enable-ebcdic at\n  the same time.\n\n. There are no separate options for enabling UTF-8, UTF-16 and UTF-32\n  independently because that would allow ridiculous settings such as requesting\n  UTF-16 support while building only the 8-bit library. However, the option\n  --enable-utf8 is retained for backwards compatibility with earlier releases\n  that did not support 16-bit or 32-bit character strings. It is synonymous with\n  --enable-utf. It is not possible to configure one library with UTF support\n  and the other without in the same configuration.\n\n. If, in addition to support for UTF-8/16/32 character strings, you want to\n  include support for the \\P, \\p, and \\X sequences that recognize Unicode\n  character properties, you must add --enable-unicode-properties to the\n  \"configure\" command. This adds about 30K to the size of the library (in the\n  form of a property table); only the basic two-letter properties such as Lu\n  are supported.\n\n. You can build PCRE to recognize either CR or LF or the sequence CRLF or any\n  of the preceding, or any of the Unicode newline sequences as indicating the\n  end of a line. Whatever you specify at build time is the default; the caller\n  of PCRE can change the selection at run time. The default newline indicator\n  is a single LF character (the Unix standard). You can specify the default\n  newline indicator by adding --enable-newline-is-cr or --enable-newline-is-lf\n  or --enable-newline-is-crlf or --enable-newline-is-anycrlf or\n  --enable-newline-is-any to the \"configure\" command, respectively.\n\n  If you specify --enable-newline-is-cr or --enable-newline-is-crlf, some of\n  the standard tests will fail, because the lines in the test files end with\n  LF. Even if the files are edited to change the line endings, there are likely\n  to be some failures. With --enable-newline-is-anycrlf or\n  --enable-newline-is-any, many tests should succeed, but there may be some\n  failures.\n\n. By default, the sequence \\R in a pattern matches any Unicode line ending\n  sequence. This is independent of the option specifying what PCRE considers to\n  be the end of a line (see above). However, the caller of PCRE can restrict \\R\n  to match only CR, LF, or CRLF. You can make this the default by adding\n  --enable-bsr-anycrlf to the \"configure\" command (bsr = \"backslash R\").\n\n. When called via the POSIX interface, PCRE uses malloc() to get additional\n  storage for processing capturing parentheses if there are more than 10 of\n  them in a pattern. You can increase this threshold by setting, for example,\n\n  --with-posix-malloc-threshold=20\n\n  on the \"configure\" command.\n\n. PCRE has a counter that limits the depth of nesting of parentheses in a\n  pattern. This limits the amount of system stack that a pattern uses when it\n  is compiled. The default is 250, but you can change it by setting, for\n  example,\n\n  --with-parens-nest-limit=500\n\n. PCRE has a counter that can be set to limit the amount of resources it uses\n  when matching a pattern. If the limit is exceeded during a match, the match\n  fails. The default is ten million. You can change the default by setting, for\n  example,\n\n  --with-match-limit=500000\n\n  on the \"configure\" command. This is just the default; individual calls to\n  pcre_exec() can supply their own value. There is more discussion on the\n  pcreapi man page.\n\n. There is a separate counter that limits the depth of recursive function calls\n  during a matching process. This also has a default of ten million, which is\n  essentially \"unlimited\". You can change the default by setting, for example,\n\n  --with-match-limit-recursion=500000\n\n  Recursive function calls use up the runtime stack; running out of stack can\n  cause programs to crash in strange ways. There is a discussion about stack\n  sizes in the pcrestack man page.\n\n. The default maximum compiled pattern size is around 64K. You can increase\n  this by adding --with-link-size=3 to the \"configure\" command. In the 8-bit\n  library, PCRE then uses three bytes instead of two for offsets to different\n  parts of the compiled pattern. In the 16-bit library, --with-link-size=3 is\n  the same as --with-link-size=4, which (in both libraries) uses four-byte\n  offsets. Increasing the internal link size reduces performance. In the 32-bit\n  library, the only supported link size is 4.\n\n. You can build PCRE so that its internal match() function that is called from\n  pcre_exec() does not call itself recursively. Instead, it uses memory blocks\n  obtained from the heap via the special functions pcre_stack_malloc() and\n  pcre_stack_free() to save data that would otherwise be saved on the stack. To\n  build PCRE like this, use\n\n  --disable-stack-for-recursion\n\n  on the \"configure\" command. PCRE runs more slowly in this mode, but it may be\n  necessary in environments with limited stack sizes. This applies only to the\n  normal execution of the pcre_exec() function; if JIT support is being\n  successfully used, it is not relevant. Equally, it does not apply to\n  pcre_dfa_exec(), which does not use deeply nested recursion. There is a\n  discussion about stack sizes in the pcrestack man page.\n\n. For speed, PCRE uses four tables for manipulating and identifying characters\n  whose code point values are less than 256. By default, it uses a set of\n  tables for ASCII encoding that is part of the distribution. If you specify\n\n  --enable-rebuild-chartables\n\n  a program called dftables is compiled and run in the default C locale when\n  you obey \"make\". It builds a source file called pcre_chartables.c. If you do\n  not specify this option, pcre_chartables.c is created as a copy of\n  pcre_chartables.c.dist. See \"Character tables\" below for further information.\n\n. It is possible to compile PCRE for use on systems that use EBCDIC as their\n  character code (as opposed to ASCII/Unicode) by specifying\n\n  --enable-ebcdic\n\n  This automatically implies --enable-rebuild-chartables (see above). However,\n  when PCRE is built this way, it always operates in EBCDIC. It cannot support\n  both EBCDIC and UTF-8/16/32. There is a second option, --enable-ebcdic-nl25,\n  which specifies that the code value for the EBCDIC NL character is 0x25\n  instead of the default 0x15.\n\n. In environments where valgrind is installed, if you specify\n\n  --enable-valgrind\n\n  PCRE will use valgrind annotations to mark certain memory regions as\n  unaddressable. This allows it to detect invalid memory accesses, and is\n  mostly useful for debugging PCRE itself.\n\n. In environments where the gcc compiler is used and lcov version 1.6 or above\n  is installed, if you specify\n\n  --enable-coverage\n\n  the build process implements a code coverage report for the test suite. The\n  report is generated by running \"make coverage\". If ccache is installed on\n  your system, it must be disabled when building PCRE for coverage reporting.\n  You can do this by setting the environment variable CCACHE_DISABLE=1 before\n  running \"make\" to build PCRE. There is more information about coverage\n  reporting in the \"pcrebuild\" documentation.\n\n. The pcregrep program currently supports only 8-bit data files, and so\n  requires the 8-bit PCRE library. It is possible to compile pcregrep to use\n  libz and/or libbz2, in order to read .gz and .bz2 files (respectively), by\n  specifying one or both of\n\n  --enable-pcregrep-libz\n  --enable-pcregrep-libbz2\n\n  Of course, the relevant libraries must be installed on your system.\n\n. The default size (in bytes) of the internal buffer used by pcregrep can be\n  set by, for example:\n\n  --with-pcregrep-bufsize=51200\n\n  The value must be a plain integer. The default is 20480.\n\n. It is possible to compile pcretest so that it links with the libreadline\n  or libedit libraries, by specifying, respectively,\n\n  --enable-pcretest-libreadline or --enable-pcretest-libedit\n\n  If this is done, when pcretest's input is from a terminal, it reads it using\n  the readline() function. This provides line-editing and history facilities.\n  Note that libreadline is GPL-licenced, so if you distribute a binary of\n  pcretest linked in this way, there may be licensing issues. These can be\n  avoided by linking with libedit (which has a BSD licence) instead.\n\n  Enabling libreadline causes the -lreadline option to be added to the pcretest\n  build. In many operating environments with a sytem-installed readline\n  library this is sufficient. However, in some environments (e.g. if an\n  unmodified distribution version of readline is in use), it may be necessary\n  to specify something like LIBS=\"-lncurses\" as well. This is because, to quote\n  the readline INSTALL, \"Readline uses the termcap functions, but does not link\n  with the termcap or curses library itself, allowing applications which link\n  with readline the to choose an appropriate library.\" If you get error\n  messages about missing functions tgetstr, tgetent, tputs, tgetflag, or tgoto,\n  this is the problem, and linking with the ncurses library should fix it.\n\nThe \"configure\" script builds the following files for the basic C library:\n\n. Makefile             the makefile that builds the library\n. config.h             build-time configuration options for the library\n. pcre.h               the public PCRE header file\n. pcre-config          script that shows the building settings such as CFLAGS\n                         that were set for \"configure\"\n. libpcre.pc         ) data for the pkg-config command\n. libpcre16.pc       )\n. libpcre32.pc       )\n. libpcreposix.pc    )\n. libtool              script that builds shared and/or static libraries\n\nVersions of config.h and pcre.h are distributed in the PCRE tarballs under the\nnames config.h.generic and pcre.h.generic. These are provided for those who\nhave to built PCRE without using \"configure\" or CMake. If you use \"configure\"\nor CMake, the .generic versions are not used.\n\nWhen building the 8-bit library, if a C++ compiler is found, the following\nfiles are also built:\n\n. libpcrecpp.pc        data for the pkg-config command\n. pcrecpparg.h         header file for calling PCRE via the C++ wrapper\n. pcre_stringpiece.h   header for the C++ \"stringpiece\" functions\n\nThe \"configure\" script also creates config.status, which is an executable\nscript that can be run to recreate the configuration, and config.log, which\ncontains compiler output from tests that \"configure\" runs.\n\nOnce \"configure\" has run, you can run \"make\". This builds the the libraries\nlibpcre, libpcre16 and/or libpcre32, and a test program called pcretest. If you\nenabled JIT support with --enable-jit, a test program called pcre_jit_test is\nbuilt as well.\n\nIf the 8-bit library is built, libpcreposix and the pcregrep command are also\nbuilt, and if a C++ compiler was found on your system, and you did not disable\nit with --disable-cpp, \"make\" builds the C++ wrapper library, which is called\nlibpcrecpp, as well as some test programs called pcrecpp_unittest,\npcre_scanner_unittest, and pcre_stringpiece_unittest.\n\nThe command \"make check\" runs all the appropriate tests. Details of the PCRE\ntests are given below in a separate section of this document.\n\nYou can use \"make install\" to install PCRE into live directories on your\nsystem. The following are installed (file names are all relative to the\n\u003cprefix\u003e that is set when \"configure\" is run):\n\n  Commands (bin):\n    pcretest\n    pcregrep (if 8-bit support is enabled)\n    pcre-config\n\n  Libraries (lib):\n    libpcre16     (if 16-bit support is enabled)\n    libpcre32     (if 32-bit support is enabled)\n    libpcre       (if 8-bit support is enabled)\n    libpcreposix  (if 8-bit support is enabled)\n    libpcrecpp    (if 8-bit and C++ support is enabled)\n\n  Configuration information (lib/pkgconfig):\n    libpcre16.pc\n    libpcre32.pc\n    libpcre.pc\n    libpcreposix.pc\n    libpcrecpp.pc (if C++ support is enabled)\n\n  Header files (include):\n    pcre.h\n    pcreposix.h\n    pcre_scanner.h      )\n    pcre_stringpiece.h  ) if C++ support is enabled\n    pcrecpp.h           )\n    pcrecpparg.h        )\n\n  Man pages (share/man/man{1,3}):\n    pcregrep.1\n    pcretest.1\n    pcre-config.1\n    pcre.3\n    pcre*.3 (lots more pages, all starting \"pcre\")\n\n  HTML documentation (share/doc/pcre/html):\n    index.html\n    *.html (lots more pages, hyperlinked from index.html)\n\n  Text file documentation (share/doc/pcre):\n    AUTHORS\n    COPYING\n    ChangeLog\n    LICENCE\n    NEWS\n    README\n    pcre.txt         (a concatenation of the man(3) pages)\n    pcretest.txt     the pcretest man page\n    pcregrep.txt     the pcregrep man page\n    pcre-config.txt  the pcre-config man page\n\nIf you want to remove PCRE from your system, you can run \"make uninstall\".\nThis removes all the files that \"make install\" installed. However, it does not\nremove any directories, because these are often shared with other programs.\n\n\nRetrieving configuration information\n------------------------------------\n\nRunning \"make install\" installs the command pcre-config, which can be used to\nrecall information about the PCRE configuration and installation. For example:\n\n  pcre-config --version\n\nprints the version number, and\n\n  pcre-config --libs\n\noutputs information about where the library is installed. This command can be\nincluded in makefiles for programs that use PCRE, saving the programmer from\nhaving to remember too many details.\n\nThe pkg-config command is another system for saving and retrieving information\nabout installed libraries. Instead of separate commands for each library, a\nsingle command is used. For example:\n\n  pkg-config --cflags pcre\n\nThe data is held in *.pc files that are installed in a directory called\n\u003cprefix\u003e/lib/pkgconfig.\n\n\nShared libraries\n----------------\n\nThe default distribution builds PCRE as shared libraries and static libraries,\nas long as the operating system supports shared libraries. Shared library\nsupport relies on the \"libtool\" script which is built as part of the\n\"configure\" process.\n\nThe libtool script is used to compile and link both shared and static\nlibraries. They are placed in a subdirectory called .libs when they are newly\nbuilt. The programs pcretest and pcregrep are built to use these uninstalled\nlibraries (by means of wrapper scripts in the case of shared libraries). When\nyou use \"make install\" to install shared libraries, pcregrep and pcretest are\nautomatically re-built to use the newly installed shared libraries before being\ninstalled themselves. However, the versions left in the build directory still\nuse the uninstalled libraries.\n\nTo build PCRE using static libraries only you must use --disable-shared when\nconfiguring it. For example:\n\n./configure --prefix=/usr/gnu --disable-shared\n\nThen run \"make\" in the usual way. Similarly, you can use --disable-static to\nbuild only shared libraries.\n\n\nCross-compiling using autotools\n-------------------------------\n\nYou can specify CC and CFLAGS in the normal way to the \"configure\" command, in\norder to cross-compile PCRE for some other host. However, you should NOT\nspecify --enable-rebuild-chartables, because if you do, the dftables.c source\nfile is compiled and run on the local host, in order to generate the inbuilt\ncharacter tables (the pcre_chartables.c file). This will probably not work,\nbecause dftables.c needs to be compiled with the local compiler, not the cross\ncompiler.\n\nWhen --enable-rebuild-chartables is not specified, pcre_chartables.c is created\nby making a copy of pcre_chartables.c.dist, which is a default set of tables\nthat assumes ASCII code. Cross-compiling with the default tables should not be\na problem.\n\nIf you need to modify the character tables when cross-compiling, you should\nmove pcre_chartables.c.dist out of the way, then compile dftables.c by hand and\nrun it on the local host to make a new version of pcre_chartables.c.dist.\nThen when you cross-compile PCRE this new version of the tables will be used.\n\n\nUsing HP's ANSI C++ compiler (aCC)\n----------------------------------\n\nUnless C++ support is disabled by specifying the \"--disable-cpp\" option of the\n\"configure\" script, you must include the \"-AA\" option in the CXXFLAGS\nenvironment variable in order for the C++ components to compile correctly.\n\nAlso, note that the aCC compiler on PA-RISC platforms may have a defect whereby\nneeded libraries fail to get included when specifying the \"-AA\" compiler\noption. If you experience unresolved symbols when linking the C++ programs,\nuse the workaround of specifying the following environment variable prior to\nrunning the \"configure\" script:\n\n  CXXLDFLAGS=\"-lstd_v2 -lCsup_v2\"\n\n\nCompiling in Tru64 using native compilers\n-----------------------------------------\n\nThe following error may occur when compiling with native compilers in the Tru64\noperating system:\n\n  CXX    libpcrecpp_la-pcrecpp.lo\ncxx: Error: /usr/lib/cmplrs/cxx/V7.1-006/include/cxx/iosfwd, line 58: #error\n          directive: \"cannot include iosfwd -- define __USE_STD_IOSTREAM to\n          override default - see section 7.1.2 of the C++ Using Guide\"\n#error \"cannot include iosfwd -- define __USE_STD_IOSTREAM to override default\n- see section 7.1.2 of the C++ Using Guide\"\n\nThis may be followed by other errors, complaining that 'namespace \"std\" has no\nmember'. The solution to this is to add the line\n\n#define __USE_STD_IOSTREAM 1\n\nto the config.h file.\n\n\nUsing Sun's compilers for Solaris\n---------------------------------\n\nA user reports that the following configurations work on Solaris 9 sparcv9 and\nSolaris 9 x86 (32-bit):\n\n  Solaris 9 sparcv9: ./configure --disable-cpp CC=/bin/cc CFLAGS=\"-m64 -g\"\n  Solaris 9 x86:     ./configure --disable-cpp CC=/bin/cc CFLAGS=\"-g\"\n\n\nUsing PCRE from MySQL\n---------------------\n\nOn systems where both PCRE and MySQL are installed, it is possible to make use\nof PCRE from within MySQL, as an alternative to the built-in pattern matching.\nThere is a web page that tells you how to do this:\n\n  http://www.mysqludf.org/lib_mysqludf_preg/index.php\n\n\nMaking new tarballs\n-------------------\n\nThe command \"make dist\" creates three PCRE tarballs, in tar.gz, tar.bz2, and\nzip formats. The command \"make distcheck\" does the same, but then does a trial\nbuild of the new distribution to ensure that it works.\n\nIf you have modified any of the man page sources in the doc directory, you\nshould first run the PrepareRelease script before making a distribution. This\nscript creates the .txt and HTML forms of the documentation from the man pages.\n\n\nTesting PCRE\n------------\n\nTo test the basic PCRE library on a Unix-like system, run the RunTest script.\nThere is another script called RunGrepTest that tests the options of the\npcregrep command. If the C++ wrapper library is built, three test programs\ncalled pcrecpp_unittest, pcre_scanner_unittest, and pcre_stringpiece_unittest\nare also built. When JIT support is enabled, another test program called\npcre_jit_test is built.\n\nBoth the scripts and all the program tests are run if you obey \"make check\" or\n\"make test\". For other environments, see the instructions in\nNON-AUTOTOOLS-BUILD.\n\nThe RunTest script runs the pcretest test program (which is documented in its\nown man page) on each of the relevant testinput files in the testdata\ndirectory, and compares the output with the contents of the corresponding\ntestoutput files. RunTest uses a file called testtry to hold the main output\nfrom pcretest. Other files whose names begin with \"test\" are used as working\nfiles in some tests.\n\nSome tests are relevant only when certain build-time options were selected. For\nexample, the tests for UTF-8/16/32 support are run only if --enable-utf was\nused. RunTest outputs a comment when it skips a test.\n\nMany of the tests that are not skipped are run up to three times. The second\nrun forces pcre_study() to be called for all patterns except for a few in some\ntests that are marked \"never study\" (see the pcretest program for how this is\ndone). If JIT support is available, the non-DFA tests are run a third time,\nthis time with a forced pcre_study() with the PCRE_STUDY_JIT_COMPILE option.\nThis testing can be suppressed by putting \"nojit\" on the RunTest command line.\n\nThe entire set of tests is run once for each of the 8-bit, 16-bit and 32-bit\nlibraries that are enabled. If you want to run just one set of tests, call\nRunTest with either the -8, -16 or -32 option.\n\nIf valgrind is installed, you can run the tests under it by putting \"valgrind\"\non the RunTest command line. To run pcretest on just one or more specific test\nfiles, give their numbers as arguments to RunTest, for example:\n\n  RunTest 2 7 11\n\nYou can also specify ranges of tests such as 3-6 or 3- (meaning 3 to the\nend), or a number preceded by ~ to exclude a test. For example:\n\n  Runtest 3-15 ~10\n\nThis runs tests 3 to 15, excluding test 10, and just ~13 runs all the tests\nexcept test 13. Whatever order the arguments are in, the tests are always run\nin numerical order.\n\nYou can also call RunTest with the single argument \"list\" to cause it to output\na list of tests.\n\nThe first test file can be fed directly into the perltest.pl script to check\nthat Perl gives the same results. The only difference you should see is in the\nfirst few lines, where the Perl version is given instead of the PCRE version.\n\nThe second set of tests check pcre_fullinfo(), pcre_study(),\npcre_copy_substring(), pcre_get_substring(), pcre_get_substring_list(), error\ndetection, and run-time flags that are specific to PCRE, as well as the POSIX\nwrapper API. It also uses the debugging flags to check some of the internals of\npcre_compile().\n\nIf you build PCRE with a locale setting that is not the standard C locale, the\ncharacter tables may be different (see next paragraph). In some cases, this may\ncause failures in the second set of tests. For example, in a locale where the\nisprint() function yields TRUE for characters in the range 128-255, the use of\n[:isascii:] inside a character class defines a different set of characters, and\nthis shows up in this test as a difference in the compiled code, which is being\nlisted for checking. Where the comparison test output contains [\\x00-\\x7f] the\ntest will contain [\\x00-\\xff], and similarly in some other cases. This is not a\nbug in PCRE.\n\nThe third set of tests checks pcre_maketables(), the facility for building a\nset of character tables for a specific locale and using them instead of the\ndefault tables. The tests make use of the \"fr_FR\" (French) locale. Before\nrunning the test, the script checks for the presence of this locale by running\nthe \"locale\" command. If that command fails, or if it doesn't include \"fr_FR\"\nin the list of available locales, the third test cannot be run, and a comment\nis output to say why. If running this test produces instances of the error\n\n  ** Failed to set locale \"fr_FR\"\n\nin the comparison output, it means that locale is not available on your system,\ndespite being listed by \"locale\". This does not mean that PCRE is broken.\n\n[If you are trying to run this test on Windows, you may be able to get it to\nwork by changing \"fr_FR\" to \"french\" everywhere it occurs. Alternatively, use\nRunTest.bat. The version of RunTest.bat included with PCRE 7.4 and above uses\nWindows versions of test 2. More info on using RunTest.bat is included in the\ndocument entitled NON-UNIX-USE.]\n\nThe fourth and fifth tests check the UTF-8/16/32 support and error handling and\ninternal UTF features of PCRE that are not relevant to Perl, respectively. The\nsixth and seventh tests do the same for Unicode character properties support.\n\nThe eighth, ninth, and tenth tests check the pcre_dfa_exec() alternative\nmatching function, in non-UTF-8/16/32 mode, UTF-8/16/32 mode, and UTF-8/16/32\nmode with Unicode property support, respectively.\n\nThe eleventh test checks some internal offsets and code size features; it is\nrun only when the default \"link size\" of 2 is set (in other cases the sizes\nchange) and when Unicode property support is enabled.\n\nThe twelfth test is run only when JIT support is available, and the thirteenth\ntest is run only when JIT support is not available. They test some JIT-specific\nfeatures such as information output from pcretest about JIT compilation.\n\nThe fourteenth, fifteenth, and sixteenth tests are run only in 8-bit mode, and\nthe seventeenth, eighteenth, and nineteenth tests are run only in 16/32-bit\nmode. These are tests that generate different output in the two modes. They are\nfor general cases, UTF-8/16/32 support, and Unicode property support,\nrespectively.\n\nThe twentieth test is run only in 16/32-bit mode. It tests some specific\n16/32-bit features of the DFA matching engine.\n\nThe twenty-first and twenty-second tests are run only in 16/32-bit mode, when\nthe link size is set to 2 for the 16-bit library. They test reloading\npre-compiled patterns.\n\nThe twenty-third and twenty-fourth tests are run only in 16-bit mode. They are\nfor general cases, and UTF-16 support, respectively.\n\nThe twenty-fifth and twenty-sixth tests are run only in 32-bit mode. They are\nfor general cases, and UTF-32 support, respectively.\n\n\nCharacter tables\n----------------\n\nFor speed, PCRE uses four tables for manipulating and identifying characters\nwhose code point values are less than 256. The final argument of the\npcre_compile() function is a pointer to a block of memory containing the\nconcatenated tables. A call to pcre_maketables() can be used to generate a set\nof tables in the current locale. If the final argument for pcre_compile() is\npassed as NULL, a set of default tables that is built into the binary is used.\n\nThe source file called pcre_chartables.c contains the default set of tables. By\ndefault, this is created as a copy of pcre_chartables.c.dist, which contains\ntables for ASCII coding. However, if --enable-rebuild-chartables is specified\nfor ./configure, a different version of pcre_chartables.c is built by the\nprogram dftables (compiled from dftables.c), which uses the ANSI C character\nhandling functions such as isalnum(), isalpha(), isupper(), islower(), etc. to\nbuild the table sources. This means that the default C locale which is set for\nyour system will control the contents of these default tables. You can change\nthe default tables by editing pcre_chartables.c and then re-building PCRE. If\nyou do this, you should take care to ensure that the file does not get\nautomatically re-generated. The best way to do this is to move\npcre_chartables.c.dist out of the way and replace it with your customized\ntables.\n\nWhen the dftables program is run as a result of --enable-rebuild-chartables,\nit uses the default C locale that is set on your system. It does not pay\nattention to the LC_xxx environment variables. In other words, it uses the\nsystem's default locale rather than whatever the compiling user happens to have\nset. If you really do want to build a source set of character tables in a\nlocale that is specified by the LC_xxx variables, you can run the dftables\nprogram by hand with the -L option. For example:\n\n  ./dftables -L pcre_chartables.c.special\n\nThe first two 256-byte tables provide lower casing and case flipping functions,\nrespectively. The next table consists of three 32-byte bit maps which identify\ndigits, \"word\" characters, and white space, respectively. These are used when\nbuilding 32-byte bit maps that represent character classes for code points less\nthan 256.\n\nThe final 256-byte table has bits indicating various character types, as\nfollows:\n\n    1   white space character\n    2   letter\n    4   decimal digit\n    8   hexadecimal digit\n   16   alphanumeric or '_'\n  128   regular expression metacharacter or binary zero\n\nYou should not alter the set of characters that contain the 128 bit, as that\nwill cause PCRE to malfunction.\n\n\nFile manifest\n-------------\n\nThe distribution should contain the files listed below. Where a file name is\ngiven as pcre[16|32]_xxx it means that there are three files, one with the name\npcre_xxx, one with the name pcre16_xx, and a third with the name pcre32_xxx.\n\n(A) Source files of the PCRE library functions and their headers:\n\n  dftables.c              auxiliary program for building pcre_chartables.c\n                          when --enable-rebuild-chartables is specified\n\n  pcre_chartables.c.dist  a default set of character tables that assume ASCII\n                          coding; used, unless --enable-rebuild-chartables is\n                          specified, by copying to pcre[16]_chartables.c\n\n  pcreposix.c                )\n  pcre[16|32]_byte_order.c   )\n  pcre[16|32]_compile.c      )\n  pcre[16|32]_config.c       )\n  pcre[16|32]_dfa_exec.c     )\n  pcre[16|32]_exec.c         )\n  pcre[16|32]_fullinfo.c     )\n  pcre[16|32]_get.c          ) sources for the functions in the library,\n  pcre[16|32]_globals.c      )   and some internal functions that they use\n  pcre[16|32]_jit_compile.c  )\n  pcre[16|32]_maketables.c   )\n  pcre[16|32]_newline.c      )\n  pcre[16|32]_refcount.c     )\n  pcre[16|32]_string_utils.c )\n  pcre[16|32]_study.c        )\n  pcre[16|32]_tables.c       )\n  pcre[16|32]_ucd.c          )\n  pcre[16|32]_version.c      )\n  pcre[16|32]_xclass.c       )\n  pcre_ord2utf8.c            )\n  pcre_valid_utf8.c          )\n  pcre16_ord2utf16.c         )\n  pcre16_utf16_utils.c       )\n  pcre16_valid_utf16.c       )\n  pcre32_utf32_utils.c       )\n  pcre32_valid_utf32.c       )\n\n  pcre[16|32]_printint.c     ) debugging function that is used by pcretest,\n                             )   and can also be #included in pcre_compile()\n\n  pcre.h.in               template for pcre.h when built by \"configure\"\n  pcreposix.h             header for the external POSIX wrapper API\n  pcre_internal.h         header for internal use\n  sljit/*                 16 files that make up the JIT compiler\n  ucp.h                   header for Unicode property handling\n\n  config.h.in             template for config.h, which is built by \"configure\"\n\n  pcrecpp.h               public header file for the C++ wrapper\n  pcrecpparg.h.in         template for another C++ header file\n  pcre_scanner.h          public header file for C++ scanner functions\n  pcrecpp.cc              )\n  pcre_scanner.cc         ) source for the C++ wrapper library\n\n  pcre_stringpiece.h.in   template for pcre_stringpiece.h, the header for the\n                            C++ stringpiece functions\n  pcre_stringpiece.cc     source for the C++ stringpiece functions\n\n(B) Source files for programs that use PCRE:\n\n  pcredemo.c              simple demonstration of coding calls to PCRE\n  pcregrep.c              source of a grep utility that uses PCRE\n  pcretest.c              comprehensive test program\n\n(C) Auxiliary files:\n\n  132html                 script to turn \"man\" pages into HTML\n  AUTHORS                 information about the author of PCRE\n  ChangeLog               log of changes to the code\n  CleanTxt                script to clean nroff output for txt man pages\n  Detrail                 script to remove trailing spaces\n  HACKING                 some notes about the internals of PCRE\n  INSTALL                 generic installation instructions\n  LICENCE                 conditions for the use of PCRE\n  COPYING                 the same, using GNU's standard name\n  Makefile.in             ) template for Unix Makefile, which is built by\n                          )   \"configure\"\n  Makefile.am             ) the automake input that was used to create\n                          )   Makefile.in\n  NEWS                    important changes in this release\n  NON-UNIX-USE            the previous name for NON-AUTOTOOLS-BUILD\n  NON-AUTOTOOLS-BUILD     notes on building PCRE without using autotools\n  PrepareRelease          script to make preparations for \"make dist\"\n  README                  this file\n  RunTest                 a Unix shell script for running tests\n  RunGrepTest             a Unix shell script for pcregrep tests\n  aclocal.m4              m4 macros (generated by \"aclocal\")\n  config.guess            ) files used by libtool,\n  config.sub              )   used only when building a shared library\n  configure               a configuring shell script (built by autoconf)\n  configure.ac            ) the autoconf input that was used to build\n                          )   \"configure\" and config.h\n  depcomp                 ) script to find program dependencies, generated by\n                          )   automake\n  doc/*.3                 man page sources for PCRE\n  doc/*.1                 man page sources for pcregrep and pcretest\n  doc/index.html.src      the base HTML page\n  doc/html/*              HTML documentation\n  doc/pcre.txt            plain text version of the man pages\n  doc/pcretest.txt        plain text documentation of test program\n  doc/perltest.txt        plain text documentation of Perl test program\n  install-sh              a shell script for installing files\n  libpcre16.pc.in         template for libpcre16.pc for pkg-config\n  libpcre32.pc.in         template for libpcre32.pc for pkg-config\n  libpcre.pc.in           template for libpcre.pc for pkg-config\n  libpcreposix.pc.in      template for libpcreposix.pc for pkg-config\n  libpcrecpp.pc.in        template for libpcrecpp.pc for pkg-config\n  ltmain.sh               file used to build a libtool script\n  missing                 ) common stub for a few missing GNU programs while\n                          )   installing, generated by automake\n  mkinstalldirs           script for making install directories\n  perltest.pl             Perl test program\n  pcre-config.in          source of script which retains PCRE information\n  pcre_jit_test.c         test program for the JIT compiler\n  pcrecpp_unittest.cc          )\n  pcre_scanner_unittest.cc     ) test programs for the C++ wrapper\n  pcre_stringpiece_unittest.cc )\n  testdata/testinput*     test data for main library tests\n  testdata/testoutput*    expected test results\n  testdata/grep*          input and output for pcregrep tests\n  testdata/*              other supporting test files\n\n(D) Auxiliary files for cmake support\n\n  cmake/COPYING-CMAKE-SCRIPTS\n  cmake/FindPackageHandleStandardArgs.cmake\n  cmake/FindEditline.cmake\n  cmake/FindReadline.cmake\n  CMakeLists.txt\n  config-cmake.h.in\n\n(E) Auxiliary files for VPASCAL\n\n  makevp.bat\n  makevp_c.txt\n  makevp_l.txt\n  pcregexp.pas\n\n(F) Auxiliary files for building PCRE \"by hand\"\n\n  pcre.h.generic          ) a version of the public PCRE header file\n                          )   for use in non-\"configure\" environments\n  config.h.generic        ) a version of config.h for use in non-\"configure\"\n                          )   environments\n\n(F) Miscellaneous\n\n  RunTest.bat            a script for running tests under Windows\n\nPhilip Hazel\nEmail local part: Philip.Hazel\nEmail domain: gmail.com\nLast updated: 15 June 2021\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpfultz2%2Fpcre","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpfultz2%2Fpcre","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpfultz2%2Fpcre/lists"}