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 14 enum { REGEX_MATCH, 15 REGEX_MATCH_PARTIAL, 16 REGEX_NO_MATCH, 17 REGEX_ERROR = -1, 18 }; 19 20 struct regex_data; 21 22 #ifdef USE_PCRE2 23 struct regex_error_data { 24 int error_code; 25 PCRE2_SIZE error_offset; 26 }; 27 #else 28 struct regex_error_data { 29 char const *error_buffer; 30 int error_offset; 31 }; 32 #endif 33 34 struct 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 */ 44 char 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 */ 57 char 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 */ 62 struct 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 */ 70 void 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 */ 89 int 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 */ 105 int 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 */ 119 int 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 */ 136 int 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 */ 148 int 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 */ 160 void regex_format_error(struct regex_error_data const *error_data, char *buffer, 161 size_t buf_size) hidden; 162 #endif /* SRC_REGEX_H_ */ 163
