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 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) ; 45 46/** 47 * regex_version 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) ; 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) ; 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) ; 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) ; 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 * @arg regex_compiled Set to true if a precompiled pattern was loaded 102 * into regex, otherwise set to false to indicate later 103 * compilation must occur 104 * 105 * @retval 0 on success 106 * @retval -1 on error 107 */ 108int regex_load_mmap(struct mmap_area *map_area, 109 struct regex_data **regex, 110 int do_load_precompregex, 111 bool *regex_compiled) ; 112/** 113 * This function stores a precompiled regular expression to a file. 114 * In the case of PCRE, it just dumps the binary representation of the 115 * precomplied pattern into a file. In the case of PCRE2, it uses the 116 * serialization function provided by the library. 117 * 118 * @arg regex The precomplied regular expression data. 119 * @arg fp A file stream specifying the output file. 120 * @arg do_write_precompregex If non-zero precompiled patterns are written to 121 * the output file (ignored by PCRE1 back-end). 122 */ 123int regex_writef(struct regex_data *regex, FILE *fp, 124 int do_write_precompregex) ; 125/** 126 * This function applies a precompiled pattern to a subject string and 127 * returns whether or not a match was found. 128 * 129 * @arg regex The precompiled pattern. 130 * @arg subject The subject string. 131 * @arg partial Boolean indicating if partial matches are wanted. A nonzero 132 * value is equivalent to specifying PCRE[2]_PARTIAL_SOFT as 133 * option to pcre_exec of pcre2_match. 134 * @retval REGEX_MATCH if a match was found 135 * @retval REGEX_MATCH_PARTIAL if a partial match was found 136 * @retval REGEX_NO_MATCH if no match was found 137 * @retval REGEX_ERROR if an error was encountered during the execution of the 138 * regular expression 139 */ 140int regex_match(struct regex_data *regex, char const *subject, 141 int partial) ; 142/** 143 * This function compares two compiled regular expressions (regex1 and regex2). 144 * It compares the binary representations of the compiled patterns. It is a very 145 * crude approximation because the binary representation holds data like 146 * reference counters, that has nothing to do with the actual state machine. 147 * 148 * @retval SELABEL_EQUAL if the pattern's binary representations are exactly 149 * the same 150 * @retval SELABEL_INCOMPARABLE otherwise 151 */ 152int regex_cmp(struct regex_data *regex1, struct regex_data *regex2) ; 153/** 154 * This function takes the error data returned by regex_prepare_data and turns 155 * it in to a human readable error message. 156 * If the buffer given to hold the error message is to small it truncates the 157 * message and indicates the truncation with an ellipsis ("...") at the end of 158 * the buffer. 159 * 160 * @arg error_data Error data as returned by regex_prepare_data. 161 * @arg buffer String buffer to hold the formatted error string. 162 * @arg buf_size Total size of the given buffer in bytes. 163 */ 164void regex_format_error(struct regex_error_data const *error_data, char *buffer, 165 size_t buf_size) ; 166#endif /* SRC_REGEX_H_ */ 167