+ + +The regular expressions interface in nginx is a wrapper around +the PCRE +library. +The corresponding header file is src/core/ngx_regex.h. + + + +To use a regular expression for string matching, first, it needs to be +compiled, this is usually done at configuration phase. +Note that since PCRE support is optional, all code using the interface must +be protected by the surrounding NGX_PCRE macro: + +#if (NGX_PCRE) +ngx_regex_t *re; +ngx_regex_compile_t rc; + +u_char errstr[NGX_MAX_CONF_ERRSTR]; + +ngx_str_t value = ngx_string("message (\\d\\d\\d).*Codeword is '(?<cw>\\w+)'"); + +ngx_memzero(&rc, sizeof(ngx_regex_compile_t)); + +rc.pattern = value; +rc.pool = cf->pool; +rc.err.len = NGX_MAX_CONF_ERRSTR; +rc.err.data = errstr; +/* rc.options are passed as is to pcre_compile() */ + +if (ngx_regex_compile(&rc) != NGX_OK) { + ngx_conf_log_error(NGX_LOG_EMERG, cf, 0, "%V", &rc.err); + return NGX_CONF_ERROR; +} + +re = rc.regex; +#endif + +After successful compilation, ngx_regex_compile_t structure +fields captures and named_captures +are filled with count of all and named captures respectively found in the +regular expression. + + + +Later, the compiled regular expression may be used to match strings against it: + +ngx_int_t n; +int captures[(1 + rc.captures) * 3]; + +ngx_str_t input = ngx_string("This is message 123. Codeword is 'foobar'."); + +n = ngx_regex_exec(re, &input, captures, (1 + rc.captures) * 3); +if (n >= 0) { + /* string matches expression */ + +} else if (n == NGX_REGEX_NO_MATCHED) { + /* no match was found */ + +} else { + /* some error */ + ngx_log_error(NGX_LOG_ALERT, log, 0, ngx_regex_exec_n " failed: %i", n); +} + +The arguments of ngx_regex_exec() are: the compiled regular +expression re, string to match s, +optional array of integers to hold found captures +and its size. +The captures array size must be a multiple of three, +per requirements of the +PCRE API. +In the example, its size is calculated from a total number of captures plus +one for the matched string itself. + + + +Now, if there are matches, captures may be accessed: + +u_char *p; +size_t size; +ngx_str_t name, value; + +/* all captures */ +for (i = 0; i < n * 2; i += 2) { + value.data = input.data + captures[i]; + value.len = captures[i + 1] - captures[i]; +} + +/* accessing named captures */ + +size = rc.name_size; +p = rc.names; + +for (i = 0; i < rc.named_captures; i++, p += size) { + + /* capture name */ + name.data = &p[2]; + name.len = ngx_strlen(name.data); + + n = 2 * ((p[0] << 8) + p[1]); + + /* captured value */ + value.data = &input.data[captures[n]]; + value.len = captures[n + 1] - captures[n]; +} + + + + +The ngx_regex_exec_array() function accepts the array of +ngx_regex_elt_t elements (which are just compiled regular +expressions with associated names), a string to match and a log. +The function will apply expressions from the array to the string until +the match is found or no more expressions are left. +The return value is NGX_OK in case of match and +NGX_DECLINED otherwise, or NGX_ERROR +in case of error. + + +