NGINX 开发指南

#include <ngx_http.h>

邮件模块的代码应该包含：

#include <ngx_mail.h>

Stream模块的代码应该包含：

#include <ngx_stream.h>

baishancloud

翻译于 2017/06/06 17:01

其它翻译版本 (1)

加载中

整数

一般情况下，nginx代码使用如下两个整数类型：ngx_int_t和ngx_uint_tstrchr函数，分别用typedef定义成了intptr_t和uintptr_t。

baishancloud

翻译于 2017/06/06 17:01

常用返回值

nginx中的大多数函数使用如下类型的返回值：

baishancloud

翻译于 2017/06/06 17:01

错误处理

为了获取最近一次系统错误码，nginx提供了ngx_errno宏。该宏被映射到了POSIX平台的errno变量上，而在Windows平台中，则变为对GetLastError()的函数调用。为了获取最近一次socket错误码，nginx提供了ngx_socket_errno宏。同样，在POSIX平台上该宏被映射为errno变量，而在Windows环境中则是对WSAGetLastError()进行调用。考虑到对性能的影响，ngx_errno和ngx_socket_errno不应该被连续访问。如果有连续、频繁访问的需要，则应该将错误码的值存储到类型为ngx_err_t的本地变量中，然后使用本地变量进行访问。如果需要设置错误码，可以使用ngx_set_errno(errno)和ngx_set_socket_errno(errno)这两个宏。

ngx_errno和ngx_socket_errno变量可以在调用日志相关函数ngx_log_error()和ngx_log_debugX()的时候使用，这样具体的错误文本就会被添加到日志输出中。

一个使用ngx_errno的例子：

void
ngx_my_kill(ngx_pid_t pid, ngx_log_t *log, int signo)
{
    ngx_err_t  err;
    if (kill(pid, signo) == -1) {
        err = ngx_errno;
        ngx_log_error(NGX_LOG_ALERT, log, err, "kill(%P, %d) failed", pid, signo);
        if (err == NGX_ESRCH) {
            return 2;
        }
        return 1;
    }
    return 0;
}

baishancloud

翻译于 2017/06/06 17:02

字符串概述

nginx使用无符号的char类型指针来表示C字符串：u_char *。

nginx字符串类型ngx_str_t的定义如下所示：

typedef struct {
    size_t      len;
    u_char     *data;
} ngx_str_t;

查找任何一个不包含在strcharset串中的字符 (字符串结束符null除外) 在string串中首次出现的位置指针. 返回一个指针, 指向非strcharset中的字符在string中首次出现的位置.。在strtoken 串中查找下一个标记, strdelimit字符集则指定了在当前查找调用中可能遇到的分界符. 返回一个指针, 指向在strtoken中找到的下一个标记. 如果找不到标记, 就返回null值. 每次调用都会修改strtoken内容, 用null字符替换遇到的每个分界符.。这样的形式时，其实是:由于在定义这个变量的时候，是作为一个指针而定义的，则p指向的是 value的地址，当p当做一个数组被引入是，它其实存放的是value的地址，而并非指向value，导致调用出现错误。

nginx提供了一系列关于字符串处理的函数。它们在src/core/ngx_string.h文件中定义。其中的一部分就是对C库中字符串函数的封装：

还有一些nginx特有的字符串函数：

最后是一些大小写转换和字符串比较的函数：

baishancloud

翻译于 2017/06/06 17:02

格式化

nginx提供了一些格式化字符串的函数。以下这些函数支持nginx特有的类型：

这些函数支持的全部格式化选项定义在src/core/ngx_string.c文件中，以下是其中的一部分：

%O — off_t
%T — time_t
%z — size_t
%i — ngx_int_t
%p — void *
%V — ngx_str_t *
%s — u_char * (null-terminated)
%*s — size_t + u_char *

'u'修饰符将类型指明为无符号，'X'和'x'则将输出转换为16进制。

例如：

u_char     buf[NGX_INT_T_LEN];
size_t     len;
ngx_int_t  n;
/* set n here */
len = ngx_sprintf(buf, "%ui", n) — buf;

baishancloud

翻译于 2017/06/06 17:03

数值转换

nginx实现了若干用于数值转换的函数：

baishancloud

翻译于 2017/06/06 17:03

正则表达式

nginx中的正则表达式接口是对PCRE库的封装。相关的头文件是src/core/ngx_regex.h。

要使用正则表达式进行字符串匹配，首先需要对正则表达式进行编译，这通常是在配置解析阶段处理的。需要注意的是strchr函数，因为PCRE的支持是可选的，因此所有使用正则相关接口的代码都需要用NGX_PCRE括起来：

#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

编译成功之后，结构体ngx_regex_compile_t的captures和named_captures成员分别会被填上正则表达式中全部以及命名捕获的数量。

然后，编译过的正则表达式就可以用来进行字符串匹配：

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);
}

ngx_regex_exec()的参数有：编译了的正则表达式re，待匹配的字符串s，可选的用于存放发现的捕获和其大小的整数数组。捕获数组的大小必须是3的倍数，这是PCRE库的API要求的。在上面例子中，该数组的大小是通过总捕获数加上字符串自身来计算得出的。

现在，如果成功匹配，则可以对捕获进行访问：

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];
}

ngx_regex_exec_array()函数接受ngx_regex_elt_t元素的数组（其实就是多个编译好的正则表达式以及对应的名字），一个待匹配字符串以及一个log。该函数会对待匹配字符串逐一应用数组中的正则表达式，直到匹配成功或者无一匹配。存在成功的匹配则返回NGX_OK，否则返回NGX_DECLINED，出错返回NGX_ERROR。

baishancloud

翻译于 2017/06/06 17:03

本文来自电脑杂谈，转载请注明本文网址：
https://www.pc-fly.com/a/jisuanjixue/article-118075-1.html