Nginx基本數據結構之ngx

nginx的作者為追求極致的高效，自己實現了很多頗具特色的nginx風格的數據結構以及公共函數。比如，nginx提供了帶長度的字元串，根據編譯器選項優化過的字元串拷貝函數ngx_copy等。所以，在我們寫nginx模塊時，應該盡量調用nginx提供的api，儘管有些api只是對glibc的宏定義。本節，我們介紹string、list、buffer、chain等一系列最基本的數據結構及相關api的使用技巧以及注意事項。

ngx_str_t(100%)

在nginx源碼目錄的src/core下面的ngx_string.h|c裡面，包含了字元串的封裝以及字元串相關操作的api。nginx提供了一個帶長度的字元串結構ngx_str_t，它的原型如下：

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

從結構體當中，data指向字元串數據的第一個字元，字元串的結束用長度來表示，而不是由』』來表示結束。所以，在寫nginx代碼時，處理字元串的方法跟我們平時使用有很大的不一樣，但要時刻記住，字元串不以』』結束，盡量使用nginx提供的字元串操作的api來操作字元串。 那麼，nginx這樣做有什麼好處呢？首先，通過長度來表示字元串長度，減少計算字元串長度的次數。其次，nginx可以重複引用一段字元串內存，data可以指向任意內存，長度表示結束，而不用去copy一份自己的字元串(因為如果要以』』結束，而不能更改原字元串，所以勢必要copy一段字元串)。我們在ngx_http_request_t結構體的成員中，可以找到很多字元串引用一段內存的例子，比如request_line、uri、args等等，這些字元串的data部分，都是指向在接收數據時創建buffer所指向的內存中，uri，args就沒有必要copy一份出來。這樣的話，減少了很多不必要的內存分配與拷貝。 正是基於此特性，在nginx中，必須謹慎的去修改一個字元串。在修改字元串時需要認真的去考慮：是否可以修改該字元串；字元串修改後，是否會對其它的引用造成影響。在後面介紹ngx_unescape_uri函數的時候，就會看到這一點。但是，使用nginx的字元串會產生一些問題，glibc提供的很多系統api函數大多是通過』』來表示字元串的結束，所以我們在調用系統api時，就不能直接傳入str->data了。此時，通常的做法是創建一段str->len 1大小的內存，然後copy字元串，最後一個位元組置為』』。比較hack的做法是，將字元串最後一個字元的後一個字元backup一個，然後設置為』』，在做完調用後，再由backup改回來，但前提條件是，你得確定這個字元是可以修改的，而且是有內存分配，不會越界，但一般不建議這麼做。 接下來，看看nginx提供的操作字元串相關的api。

#define ngx_string(str) { sizeof(str) - 1, (u_char *) str }

ngx_string(str)是一個宏，它通過一個以』』結尾的普通字元串str構造一個nginx的字元串，鑒於其中採用sizeof操作符計算字元串長度，因此參數必須是一個常量字元串。

#define ngx_null_string { 0, NULL }

定義變數時，使用ngx_null_string初始化字元串為空字元串，符串的長度為0，data為NULL。

#define ngx_str_set(str, text) (str)->len = sizeof(text) - 1; (str)->data = (u_char *) text

ngx_str_set用於設置字元串str為text，由於使用sizeof計算長度，故text必須為常量字元串。

#define ngx_str_null(str) (str)->len = 0; (str)->data = NULL

ngx_str_null用於設置字元串str為空串，長度為0，data為NULL。

上面這四個函數，使用時一定要小心，ngx_string與ngx_null_string是「{，}」格式的，故只能用於賦值時初始化，如：

ngx_str_t str = ngx_string("hello world");ngx_str_t str1 = ngx_null_string();

如果向下面這樣使用，就會有問題，這裡涉及到c語言中對結構體變數賦值操作的語法規則，在此不做介紹。

ngx_str_t str, str1;str = ngx_string("hello world"); // 編譯出錯str1 = ngx_null_string; // 編譯出錯

這種情況，可以調用ngx_str_set與ngx_str_null這兩個函數來做:

ngx_str_t str, str1;ngx_str_set(&str, "hello world");ngx_str_null(&str1);

按照C99標準，您也可以這麼做：

ngx_str_t str, str1;str = (ngx_str_t) ngx_string("hello world");str1 = (ngx_str_t) ngx_null_string;

另外要注意的是，ngx_string與ngx_str_set在調用時，傳進去的字元串一定是常量字元串，否則會得到意想不到的錯誤(因為ngx_str_set內部使用了sizeof()，如果傳入的是u_char*，那麼計算的是這個指針的長度，而不是字元串的長度)。如：

ngx_str_t str;u_char *a = "hello world";ngx_str_set(&str, a); // 問題產生

此外，值得注意的是，由於ngx_str_set與ngx_str_null實際上是兩行語句，故在if/for/while等語句中單獨使用需要用花括弧括起來，例如：

ngx_str_t str;if (cond) ngx_str_set(&str, "true"); // 問題產生else ngx_str_set(&str, "false"); // 問題產生void ngx_strlow(u_char *dst, u_char *src, size_t n);

將src的前n個字元轉換成小寫存放在dst字元串當中，調用者需要保證dst指向的空間大於等於n，且指向的空間必須可寫。操作不會對原字元串產生變動。如要更改原字元串，可以：

ngx_strlow(str->data, str->data, str->len);ngx_strncmp(s1, s2, n)

區分大小寫的字元串比較，只比較前n個字元。

ngx_strcmp(s1, s2)

區分大小寫的不帶長度的字元串比較。

ngx_int_t ngx_strcasecmp(u_char *s1, u_char *s2);

不區分大小寫的不帶長度的字元串比較。

ngx_int_t ngx_strncasecmp(u_char *s1, u_char *s2, size_t n);

不區分大小寫的帶長度的字元串比較，只比較前n個字元。

u_char * ngx_cdecl ngx_sprintf(u_char *buf, const char *fmt, ...);u_char * ngx_cdecl ngx_snprintf(u_char *buf, size_t max, const char *fmt, ...);u_char * ngx_cdecl ngx_slprintf(u_char *buf, u_char *last, const char *fmt, ...);

上面這三個函數用於字元串格式化，ngx_snprintf的第二個參數max指明buf的空間大小，ngx_slprintf則通過last來指明buf空間的大小。推薦使用第二個或第三個函數來格式化字元串，ngx_sprintf函數還是比較危險的，容易產生緩衝區溢出漏洞。在這一系列函數中，nginx在兼容glibc中格式化字元串的形式之外，還添加了一些方便格式化nginx類型的一些轉義字元，比如%V用于格式化ngx_str_t結構。在nginx源文件的ngx_string.c中有說明：

/* * supported formats: * %[0][width][x][X]O off_t * %[0][width]T time_t * %[0][width][u][x|X]z ssize_t/size_t * %[0][width][u][x|X]d int/u_int * %[0][width][u][x|X]l long * %[0][width|m][u][x|X]i ngx_int_t/ngx_uint_t * %[0][width][u][x|X]D int32_t/uint32_t * %[0][width][u][x|X]L int64_t/uint64_t * %[0][width|m][u][x|X]A ngx_atomic_int_t/ngx_atomic_uint_t * %[0][width][.width]f double, max valid number fits to %18.15f * %P ngx_pid_t * %M ngx_msec_t * %r rlim_t * %p void * * %V ngx_str_t * * %v ngx_variable_value_t * * %s null-terminated string * %*s length and string * %Z "" * %N "
" * %c char * %% % * * reserved: * %t ptrdiff_t * %S null-terminated wchar string * %C wchar */

這裡特別要提醒的是，我們最常用于格式化ngx_str_t結構，其對應的轉義符是%V，傳給函數的一定要是指針類型，否則程序就會coredump掉。這也是我們最容易犯的錯。比如：

ngx_str_t str = ngx_string("hello world");char buffer[1024];ngx_snprintf(buffer, 1024, "%V", &str); // 注意，str取地址void ngx_encode_base64(ngx_str_t *dst, ngx_str_t *src);ngx_int_t ngx_decode_base64(ngx_str_t *dst, ngx_str_t *src);

這兩個函數用於對str進行base64編碼與解碼，調用前，需要保證dst中有足夠的空間來存放結果，如果不知道具體大小，可先調用ngx_base64_encoded_length與ngx_base64_decoded_length來預估最大佔用空間。

uintptr_t ngx_escape_uri(u_char *dst, u_char *src, size_t size, ngx_uint_t type);

對src進行編碼，根據type來按不同的方式進行編碼，如果dst為NULL，則返回需要轉義的字元的數量，由此可得到需要的空間大小。type的類型可以是：

#define NGX_ESCAPE_URI 0#define NGX_ESCAPE_ARGS 1#define NGX_ESCAPE_HTML 2#define NGX_ESCAPE_REFRESH 3#define NGX_ESCAPE_MEMCACHED 4#define NGX_ESCAPE_MAIL_AUTH 5void ngx_unescape_uri(u_char **dst, u_char **src, size_t size, ngx_uint_t type);

對src進行反編碼，type可以是0、NGX_UNESCAPE_URI、NGX_UNESCAPE_REDIRECT這三個值。如果是0，則表示src中的所有字元都要進行轉碼。如果是NGX_UNESCAPE_URI與NGX_UNESCAPE_REDIRECT，則遇到』?』後就結束了，後面的字元就不管了。而NGX_UNESCAPE_URI與NGX_UNESCAPE_REDIRECT之間的區別是NGX_UNESCAPE_URI對於遇到的需要轉碼的字元，都會轉碼，而NGX_UNESCAPE_REDIRECT則只會對非可見字元進行轉碼。

uintptr_t ngx_escape_html(u_char *dst, u_char *src, size_t size);

對html標籤進行編碼。

當然，我這裡只介紹了一些常用的api的使用，大家可以先熟悉一下，在實際使用過程中，遇到不明白的，最快最直接的方法就是去看源碼，看api的實現或看nginx自身調用api的地方是怎麼做的，代碼就是最好的文檔。

推薦閱讀：