1#ifndef SRC_REGEX_H_
2#define SRC_REGEX_H_
3
4#include <stdio.h>
5
6#ifdef USE_PCRE2
7#include <pcre2.h>
8#else
9#include <pcre.h>
10#endif
11
12#include "dso.h"
13
14enum { REGEX_MATCH,
15       REGEX_MATCH_PARTIAL,
16       REGEX_NO_MATCH,
17       REGEX_ERROR = -1,
18};
19
20struct regex_data;
21
22#ifdef USE_PCRE2
23struct regex_error_data {
24	int error_code;
25	PCRE2_SIZE error_offset;
26};
27#else
28struct regex_error_data {
29	char const *error_buffer;
30	int error_offset;
31};
32#endif
33
34struct mmap_area;
35
36/**
37 * regex_arch_string return a string that represents the pointer width, the
38 * width of what the backend considers a size type, and the endianness of the
39 * system that this library was build for. (e.g. for x86_64: "8-8-el").
40 * This is required when loading stored regular espressions. PCRE2 regular
41 * expressions are not portable across architectures that do not have a
42 * matching arch-string.
43 */
44char const *regex_arch_string(void) hidden;
45
46/**
47 * regex_verison returns the version string of the underlying regular
48 * regular expressions library. In the case of PCRE it just returns the
49 * result of pcre_version(). In the case of PCRE2, the very first time this
50 * function is called it allocates a buffer large enough to hold the version
51 * string and reads the PCRE2_CONFIG_VERSION option to fill the buffer.
52 * The allocated buffer will linger in memory until the calling process is being
53 * reaped.
54 *
55 * It may return NULL on error.
56 */
57char const *regex_version(void) hidden;
58/**
59 * This constructor function allocates a buffer for a regex_data structure.
60 * The buffer is being initialized with zeroes.
61 */
62struct regex_data *regex_data_create(void) hidden;
63/**
64 * This complementary destructor function frees the a given regex_data buffer.
65 * It also frees any non NULL member pointers with the appropriate pcreX_X_free
66 * function. For PCRE this function respects the extra_owned field and frees
67 * the pcre_extra data conditionally. Calling this function on a NULL pointer is
68 * save.
69 */
70void regex_data_free(struct regex_data *regex) hidden;
71/**
72 * This function compiles the regular expression. Additionally, it prepares
73 * data structures required by the different underlying engines. For PCRE
74 * it calls pcre_study to generate optional data required for optimized
75 * execution of the compiled pattern. In the case of PCRE2, it allocates
76 * a pcre2_match_data structure of appropriate size to hold all possible
77 * matches created by the pattern.
78 *
79 * @arg regex If successful, the structure returned through *regex was allocated
80 *            with regex_data_create and must be freed with regex_data_free.
81 * @arg pattern_string The pattern string that is to be compiled.
82 * @arg errordata A pointer to a regex_error_data structure must be passed
83 *                to this function. This structure depends on the underlying
84 *                implementation. It can be passed to regex_format_error
85 *                to generate a human readable error message.
86 * @retval 0 on success
87 * @retval -1 on error
88 */
89int regex_prepare_data(struct regex_data **regex, char const *pattern_string,
90		       struct regex_error_data *errordata) hidden;
91/**
92 * This function loads a serialized precompiled pattern from a contiguous
93 * data region given by map_area.
94 *
95 * @arg map_area Description of the memory region holding a serialized
96 *               representation of the precompiled pattern.
97 * @arg regex If successful, the structure returned through *regex was allocated
98 *            with regex_data_create and must be freed with regex_data_free.
99 * @arg do_load_precompregex If non-zero precompiled patterns get loaded from
100 *			     the mmap region (ignored by PCRE1 back-end).
101 *
102 * @retval 0 on success
103 * @retval -1 on error
104 */
105int regex_load_mmap(struct mmap_area *map_area,
106		    struct regex_data **regex,
107		    int do_load_precompregex) hidden;
108/**
109 * This function stores a precompiled regular expression to a file.
110 * In the case of PCRE, it just dumps the binary representation of the
111 * precomplied pattern into a file. In the case of PCRE2, it uses the
112 * serialization function provided by the library.
113 *
114 * @arg regex The precomplied regular expression data.
115 * @arg fp A file stream specifying the output file.
116 * @arg do_write_precompregex If non-zero precompiled patterns are written to
117 *			      the output file (ignored by PCRE1 back-end).
118 */
119int regex_writef(struct regex_data *regex, FILE *fp,
120		 int do_write_precompregex) hidden;
121/**
122 * This function applies a precompiled pattern to a subject string and
123 * returns whether or not a match was found.
124 *
125 * @arg regex The precompiled pattern.
126 * @arg subject The subject string.
127 * @arg partial Boolean indicating if partial matches are wanted. A nonzero
128 *              value is equivalent to specifying PCRE[2]_PARTIAL_SOFT as
129 *              option to pcre_exec of pcre2_match.
130 * @retval REGEX_MATCH if a match was found
131 * @retval REGEX_MATCH_PARTIAL if a partial match was found
132 * @retval REGEX_NO_MATCH if no match was found
133 * @retval REGEX_ERROR if an error was encountered during the execution of the
134 *                     regular expression
135 */
136int regex_match(struct regex_data *regex, char const *subject,
137		int partial) hidden;
138/**
139 * This function compares two compiled regular expressions (regex1 and regex2).
140 * It compares the binary representations of the compiled patterns. It is a very
141 * crude approximation because the binary representation holds data like
142 * reference counters, that has nothing to do with the actual state machine.
143 *
144 * @retval SELABEL_EQUAL if the pattern's binary representations are exactly
145 *                       the same
146 * @retval SELABEL_INCOMPARABLE otherwise
147 */
148int regex_cmp(struct regex_data *regex1, struct regex_data *regex2) hidden;
149/**
150 * This function takes the error data returned by regex_prepare_data and turns
151 * it in to a human readable error message.
152 * If the buffer given to hold the error message is to small it truncates the
153 * message and indicates the truncation with an ellipsis ("...") at the end of
154 * the buffer.
155 *
156 * @arg error_data Error data as returned by regex_prepare_data.
157 * @arg buffer String buffer to hold the formated error string.
158 * @arg buf_size Total size of the given bufer in bytes.
159 */
160void regex_format_error(struct regex_error_data const *error_data, char *buffer,
161			size_t buf_size) hidden;
162#endif /* SRC_REGEX_H_ */
163