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