pcre2sample(3) — Linux manual page

NAME \| PCRE2 SAMPLE PROGRAM \| AUTHOR \| REVISION \| COLOPHON

PCRE2SAMPLE(3)           Library Functions Manual          PCRE2SAMPLE(3)

NAME top

       PCRE2 - Perl-compatible regular expressions (revised API)

PCRE2 SAMPLE PROGRAM top


       A simple, complete demonstration program to get you started with
       using PCRE2 is supplied in the file pcre2demo.c in the src
       directory in the PCRE2 distribution. A listing of this program is
       given in the pcre2demo documentation. If you do not have a copy of
       the PCRE2 distribution, you can save this listing to recreate the
       contents of pcre2demo.c.

       The demonstration program compiles the regular expression that is
       its first argument, and matches it against the subject string in
       its second argument. No PCRE2 options are set, and default
       character tables are used. If matching succeeds, the program
       outputs the portion of the subject that matched, together with the
       contents of any captured substrings.

       If the -g option is given on the command line, the program then
       goes on to check for further matches of the same regular
       expression in the same subject string. The logic is a little bit
       tricky because of the possibility of matching an empty string.
       Comments in the code explain what is going on.

       The code in pcre2demo.c is an 8-bit program that uses the PCRE2
       8-bit library. It handles strings and characters that are stored
       in 8-bit code units.  By default, one character corresponds to one
       code unit, but if the pattern starts with "(*UTF)", both it and
       the subject are treated as UTF-8 strings, where characters may
       occupy multiple code units.

       If PCRE2 is installed in the standard include and library
       directories for your operating system, you should be able to
       compile the demonstration program using a command like this:

         cc -o pcre2demo pcre2demo.c -lpcre2-8

       If PCRE2 is installed elsewhere, you may need to add additional
       options to the command line. For example, on a Unix-like system
       that has PCRE2 installed in /usr/local, you can compile the
       demonstration program using a command like this:

         cc -o pcre2demo -I/usr/local/include pcre2demo.c \
            -L/usr/local/lib -lpcre2-8

       Once you have built the demonstration program, you can run simple
       tests like this:

         ./pcre2demo 'cat|dog' 'the cat sat on the mat'
         ./pcre2demo -g 'cat|dog' 'the dog sat on the cat'
         ./pcre2demo -i 'cat' 'the dog sat on the CAT'

       Note that there is a much more comprehensive test program, called
       pcre2test, which supports many more facilities for testing regular
       expressions using all three PCRE2 libraries (8-bit, 16-bit, and
       32-bit, though not all three need be installed). The pcre2demo
       program is provided as a relatively simple coding example.

       If you try to run pcre2demo when PCRE2 is not installed in the
       standard library directory, you may get an error like this on some
       operating systems (e.g. Solaris):

         ld.so.1: pcre2demo: fatal: libpcre2-8.so.0: open failed: No such
       file or directory

       This is caused by the way shared library support works on those
       systems. You need to add

         -R/usr/local/lib

       (for example) to the compile command to get round this problem.

AUTHOR top


       Philip Hazel
       Retired from University Computing Service
       Cambridge, England.

REVISION top


       Last updated: 14 November 2023
       Copyright (c) 1997-2016 University of Cambridge.

COLOPHON top

       This page is part of the PCRE (Perl Compatible Regular
       Expressions) project.  Information about the project can be found
       at ⟨http://www.pcre.org/⟩.  If you have a bug report for this
       manual page, see
       ⟨http://bugs.exim.org/enter_bug.cgi?product=PCRE⟩.  This page was
       obtained from the tarball fetched from
       ⟨https://github.com/PhilipHazel/pcre2.git⟩ on 2025-08-11.  If you
       discover any rendering problems in this HTML version of the page,
       or you believe there is a better or more up-to-date source for the
       page, or you have corrections or improvements to the information
       in this COLOPHON (which is not part of the original manual page),
       send a mail to man-pages@man7.org

PCRE2 10.46-DEV              14 November 2023              PCRE2SAMPLE(3)

Pages that refer to this page: pcre2api(3)