Utility API

Structures

ngx_str_t

ngx_str_t
A structure containing a pointer to a character array and the length of the character array
size_t len

The length of the character array

unsigned char *data

A pointer to the character array

ngx_regex_compile_t

ngx_regex_compile_t

A structure to set up the parameters for a regular expression

ngx_str_t pattern

The PCRE style regular expression to compile

ngx_pool_t *pool

A memory pool to use for the regular expression

ngx_int_t options

Options for the regular expression. At the moment the only valid option is NGX_REGEX_CASELESS which does a case-insensitive search.

ngx_str_t err

A pre-allocated section of memory to store errors from the regular expression engine

Functions

ngx_string

ngx_str_t ngx_string(const unsigned char str[])

Returns a ngx_str_t from a given NULL terminated character array.

Note

this does not make a copy of the character array supplied. It also uses sizeof() to calculate length so will not work will dynamically allocated memory.

Parameters:
  • str – The NULL terminated character array to convert
Returns:

A ngx_str_t wrapper around the character string

ngx_null_string

ngx_str_t ngx_null_string(void)

Returns an empty ngx_str_t terminated with NULL.

Returns:A NULL terminated empty ngx_str_t

ngx_str_set

void ngx_str_set(ngx_str_t *str, const unsigned char text[])

Sets a ngx_str_t to a given character array

Note

this does not make a copy of the character array. It also uses sizeof() to calculate length so will not work will dynamically allocated pointers.

Parameters:
  • str – The destination ngx_str_t
  • text – The source character array

ngx_str_null

void ngx_str_null(ngx_str_t *str)

Sets a given ngx_str_t to an empty NULL terminated string.

Parameters:

ngx_tolower

unsigned char ngx_tolower(unsigned char c)

Sets an ASCII ‘A’ to ‘Z’ to lowercase. For other characters it returns the same character.

Parameters:
  • c – The input character
Returns:

A lowercase ‘a’ to ‘z’ or the input character

ngx_toupper

unsigned char ngx_toupper(unsigned char c)

Sets an ASCII ‘a’ to ‘z’ to uppercase. For other characters it returns the same character.

Parameters:
  • c – The input character
Returns:

An uppercase ‘A’ to ‘Z’ or the input character

ngx_strlow

void ngx_strlow(unsigned char *dst, unsigned char *src, size_t n)

Runs ngx_tolower() on an entire string who’s length is given. The destination should be pre-allocated to at least the same length as the source.

Parameters:
  • dst – The destination string
  • src – The source string
  • n – The length of the source string

ngx_strncmp

int ngx_strncmp(const char *s1, const char *s2, size_t n)

An alias to the standard strncmp function

Parameters:
  • s1 – The first string to compare
  • s2 – The second string to compare
  • n – The maximum length to compare
Returns:

0 if the strings are equal, <0 if the first non-matching character in s1 is lower, >0 if the first non-matching character in s2 is higher

ngx_strcmp

int ngx_strcmp(const char *s1, const char *s2)

An alias to the standard strcmp function

Parameters:
  • s1 – The first string to compare
  • s2 – The second string to compare
Returns:

0 if the strings are equal, <0 if the first non-matching character in s1 is lower, >0 if the first non-matching character in s2 is higher

ngx_strlen

size_t ngx_strlen(const char *s)

An alias to the standard strlen function

Parameters:
  • s – The NULL terminated string
Returns:

The length of the string

ngx_strstr

char *ngx_strstr(const char *s1, const char *s2)

An alias to the standard strstr function

Parameters:
  • s1 – The string to search within
  • s2 – The sequence of characters to match
Returns:

A pointer to the first match or NULL on no match

ngx_strchr

char *ngx_strchr(const char *s1, int c)

An alias to the standard strchr function

Parameters:
  • s1 – The string to search within
  • c – The character to find in the string
Returns:

A pointer to first match or NULL on no match

ngx_strlchr

unsigned char *ngx_strlchr(unsigned char *p, unsigned char *last, unsigned char c)

Searches a string based on the pointer to the beginning and end of the string for a given character. Returns a pointer to the first match of that character.

Parameters:
  • p – A pointer to the start of the string
  • last – A pointer to the end of the string
  • c – The character to find in the string
Returns:

A pointer to the first match or NULL on no match

ngx_memzero

void ngx_memzero(void *buf, size_t n)

Sets every byte of a given section of memory to zero

Parameters:
  • buf – The pointer to the memory
  • n – The length of the memory to set to zero

ngx_memset

void ngx_memset(void *buf, int c, size_t n)

An alias for the standard memset function

Parameters:
  • buf – The pointer to the memory
  • c – The character to fill the memory with
  • n – The length of the memory

ngx_memcpy

void ngx_memcpy(void *dst, const void *src, size_t n)

An alias for the standard memcpy function but does not return the pointer to the destination

Parameters:
  • dst – The destination memory pointer
  • src – The source memory pointer
  • n – The amount of bytes to copy

ngx_copy

void *ngx_copy(void *dst, const void *src, size_t n)

A wrapper for the standard memcpy function which returns the pointer of the destination after the copy (dst + n)

Parameters:
  • dst – The destination memory pointer
  • src – The source memory pointer
  • n – The amount of bytes to copy
Returns:

The pointer of dst + n

ngx_memmove

void *ngx_memmove(void *dst, const void *src, size_t n)

An alias for the standard memmove function but does not return the pointer to the destination

Parameters:
  • dst – The destination memory pointer
  • src – The source memory pointer
  • n – The number of bytes to move

ngx_movemem

void *ngx_movemem(void *dst, const void *src, size_t n)

A wrapper for the standard memmove function which returns the pointer of the destination after the copy (dst + n)

Parameters:
  • dst – The destination memory pointer
  • src – The source memory pointer
  • n – The number of bytes to move
Returns:

The pointer of dst + n

ngx_memcmp

int ngx_memcmp(const void *s1, const void *s2, size_t n)

An alias for the standard memcmp function.

Parameters:
  • s1 – The first string to compare
  • s2 – The second string to compare
Returns:

0 if the strings are equal, <0 if the first non-matching character in s1 is lower, >0 if the first non-matching character in s2 is higher

ngx_cpystrn

unsigned char *ngx_cpystrn(unsigned char *dst, unsigned char *src, size_t n)

Copies information from one memory location to another. Stops when n bytes are copied or a NULL terminator is hit. Returns the pointer pointer of dst at the point where the copy has finished.

Parameters:
  • dst – The destination memory pointer
  • src – The source memory pointer
  • n – The number of bytes to copy
Returns:

The pointer of dst plus the number of bytes copied

ngx_pstrdup

unsigned char *ngx_pstrdup(ngx_pool_t *pool, ngx_str_t *src)

Creates a copy of a string into a newly allocated string in a memory pool created with ngx_create_pool()

Parameters:
  • pool – The memory pool to use
  • src – The source string
Returns:

A pointer to the copy of the string

ngx_sprintf

unsigned char *ngx_sprintf(unsigned char *buf, const char *fmt, ...)

An sprintf style wrapper around ngx_vslprintf()

Parameters:
  • buf – The destination pointer
  • fmt – The text and format description to use
Returns:

A pointer to the destination

ngx_snprintf

unsigned char *ngx_snprintf(unsigned char *buf, size_t max, const char *fmt, ...)

An snprintf style wrapper around ngx_vslprintf()

Parameters:
  • buf – The destination pointer
  • max – The maximum size of the destination
  • fmt – The text and format description to use
Returns:

A pointer to the destination

ngx_slprintf

unsigned char *ngx_slprintf(unsigned char *buf, unsigned char *last, const char *fmt, ...)

A wrapper around ngx_vslprintf() similar to snprintf but instead of a maximum length specifier it takes a pointer to the end of the destination memory buffer.

Parameters:
  • buf – The destination pointer
  • last – A pointer to the end of the destination buffer
  • fmt – The text and format description to use
Returns:

A pointer to the destination

ngx_vslprintf

unsigned char *ngx_vslprintf(unsigned char *buf, unsigned char *last, const char *fmt, va_list args)

A function similar to the standard vsnprintf but has additional possible format specifiers. It also takes a pointer to the end of the destination memory buffer instead of a length specifier.

Specifier Description
%P The contents of a ngx_pid_t
%M The contents of a ngx_msec_t
%V The data of a ngx_str_t
%v The data of a ngx_http_variable_value_t
Parameters:
  • buf – The destination pointer
  • max – The maximum size of the destination
  • fmt – The text and format description to use
  • args – A variable arguments list

ngx_vsnprintf

unsigned char *ngx_vsnprintf(unsigned char *buf, size_t max, const char *fmt, va_list args)

A function similar to the standard vsnprintf which is implemented as a wrapper around ngx_vslprintf()

Parameters:
  • buf – The destination pointer
  • last – A pointer to the end of the destination buffer
  • fmt – The text and format description to use
  • args – A variable arguments list

ngx_strcasecmp

ngx_int_t ngx_strcasecmp(unsigned char *s1, unsigned char *s2)

An optimised function similar to the standard strcasecmp

Parameters:
  • s1 – The first string to compare
  • s2 – The second string to compare
Returns:

0 if the strings are equal, <0 if the first non-matching character in s1 is lower, >0 if the first non-matching character in s2 is higher

ngx_strncasecmp

ngx_int_t ngx_strncasecmp(unsigned char *s1, unsigned char *s2, size_t n)

An optimised function similar to the standard strncasecmp

Parameters:
  • s1 – The first string to compare
  • s2 – The second string to compare
  • n – The maximum number of characters to compare
Returns:

0 if the strings are equal, <0 if the first non-matching character in s1 is lower, >0 if the first non-matching character in s2 is higher

ngx_strnstr

unsigned char *ngx_strnstr(unsigned char *s1, char *s2, size_t n)

A function similar to the standard strstr but with a maximum search length.

Parameters:
  • s1 – The string to search within
  • s2 – The sequence of characters to match
  • n – The maximum number of characters to search in s1
Returns:

A pointer to the first match or NULL on no match

ngx_strstrn

unsigned char *ngx_strstrn(unsigned char *s1, char *s2, size_t n)

A function similar to the standard strstr but with a length specifier for the s2 parameter.

Parameters:
  • s1 – The string to search within
  • s2 – The sequence of characters to match
  • n – The length of the s2 parameter
Returns:

A pointer to the first match or NULL on no match

ngx_strcasestrn

unsigned char *ngx_strcasestrn(unsigned char *s1, char *s2, size_t n)

A function similar to the standard strcasestr but with a length specifier for the s2 parameter.

Parameters:
  • s1 – The string to search within
  • s2 – The sequence of characters to match
  • n – The length of the s2 parameter
Returns:

A pointer to the first match or NULL on no match

ngx_strlcasestrn

unsigned char *ngx_strlcasestrn(unsigned char *s1, unsigned char *last, unsigned char *s2, size_t n)

A function similar to the standard strcasestr but with a pointer to the last character in the search string and a length specifier for the s2 parameter.

Parameters:
  • s1 – The string to search within
  • last – A pointer to the last character in the s1 string
  • s2 – The sequence of characters to match
  • n – The length of the s2 parameter
Returns:

A pointer to the first match or NULL on no match

ngx_rstrncmp

ngx_int_t ngx_rstrncmp(unsigned char *s1, unsigned char *s2, size_t n)

A function similar to the standard strncmp but starts at the end of the string.

Parameters:
  • s1 – The first string to compare
  • s2 – The second string to compare
  • n – The maximum length to compare
Returns:

0 if the strings are equal, <0 if the first non-matching character in s1 is lower, >0 if the first non-matching character in s2 is higher

ngx_rstrncasecmp

ngx_int_t ngx_rstrncasecmp(unsigned char *s1, unsigned char *s2, size_t n)

A function similar to the standard strncasecmp but starts at the end of the string.

Parameters:
  • s1 – The first string to compare
  • s2 – The second string to compare
  • n – The maximum length to compare
Returns:

0 if the strings are equal, <0 if the first non-matching character in s1 is lower, >0 if the first non-matching character in s2 is higher

ngx_memn2cmp

ngx_int_t ngx_memn2cmp(unsigned char *s1, unsigned char *s2, size_t n1, size_t n2)

Compares two length specified segments of memory.

Parameters:
  • s1 – The first memory location to compare
  • s2 – The second memory location to compare
  • n1 – The length of the first memory location
  • n2 – The length of the second memory location
Returns:

0 if the strings are equal, <0 if the first non-matching character in s1 is lower, >0 if the first non-matching character in s2 is higher

ngx_dns_str_cmp

ngx_int_t ngx_dns_strcmp(unsigned char *s1, unsigned char *s2)

A function similar to ngx_strcmp() but compares two DNS entries.

Parameters:
  • s1 – The first string to compare
  • s2 – The second string to compare
Returns:

0 if the strings are equal, <0 if the first non-matching character in s1 is lower, >0 if the first non-matching character in s2 is higher

ngx_filename_cmp

ngx_int_t ngx_filename_cmp(unsigned char *s1, unsigned char *s2, size_t n)

A function similar to ngx_strncmp() but compares two paths

Parameters:
  • s1 – The first path to compare
  • s2 – The second path to compare
  • n – The number of bytes to compare
Returns:

0 if the strings are equal, <0 if the first non-matching character in s1 is lower, >0 if the first non-matching character in s2 is higher

ngx_atoi

ngx_int_t ngx_atoi(unsigned char *line, size_t n)

A function similar to atoi but has a string length specifier

Parameters:
  • line – The text to convert
  • n – The length of line
Returns:

An integer representation of the input

ngx_atofp

ngx_int_t ngx_atofp(unsigned char *line, size_t n, size_t point)

Converts a floating point number in a string to an integer representation. For example: ngx_atofp("10.2", 4, 2) returns 1020

Parameters:
  • line – The text to convert
  • n – The length of line
  • point – The number of decimal places to convert
Returns:

An integer representing the input

ngx_atosz

ssize_t ngx_atosz(unsigned char *line, size_t n)

Converts a number in a text string to a ssize_t

Parameters:
  • line – The text to convert
  • n – The length of line
Returns:

A ssize_t representation of the input

ngx_atoof

off_t ngx_atoof(unsigned char *line, size_t n)

Converts a number in a text string to an off_t

Parameters:
  • line – The text to convert
  • n – The length of line
Returns:

A off_t representation of the input

ngx_atotm

time_t ngx_atotm(unsigned char *line, size_t n)

Converts a number in a text string to a time_t

Parameters:
  • line – The text to convert
  • n – The length of line
Returns:

A time_t representation of the input

ngx_hextoi

ngx_int_t ngx_hextoi(unsigned char *line, size_t n)

Converts a hexadecimal number in a text string to an integer

Parameters:
  • line – The text to convert
  • n – The length of line
Returns:

An integer representation of the hexadecimal input

ngx_hex_dump

unsigned char *ngx_hex_dump(unsigned char *dst, unsigned char *src, size_t len)

Converts binary data to a printable hexadecimal representation of the string

Note

dst should be allocated to 2*len. dst will not be NULL terminated by this function.

Parameters:
  • dst – The destination string
  • src – The source binary data
  • len – The length of src
Returns:

A pointer to dst + (2*len)

ngx_base64_encoded_length

int ngx_base64_encoded_length(int len)

A macro to calculate the base64 encoded length of a string. Evaluates to (((len + 2) / 3) * 4). Any int type can be used.

Parameters:
  • len – The input length
Returns:

The output length

ngx_base64_decoded_length

int ngx_base64_decoded_length(int len)

A macro to calculate the base64 decoded length of a string. Evaluates to (((len + 3) / 4) * 3). Any int type can be used.

Parameters:
  • len – The input length
Returns:

The output length

ngx_encode_base64

void ngx_encode_base64(ngx_str_t *dst, ngx_str_t *src)

Base64 encodes a given input text.

Note

ngx_base64_encoded_length() should be used to calculate how much memory should be allocated for dst

Parameters:
  • dst – The destination buffer
  • src – The source data

ngx_encode_base64url

void ngx_encode_base64url(ngx_str_t *dst, ngx_str_t *src)

Base64 encodes a given input URL

Note

ngx_base64_encoded_length() should be used to calculate how much memory should be allocated for dst

Parameters:
  • dst – The destination buffer
  • src – The source data

ngx_decode_base64

ngx_int_t ngx_decode_base64(ngx_str_t *dst, ngx_str_t *src)

Base64 decodes a given input

Note

ngx_base64_decoded_length() should be used to calculate how much memory should be allocated for dst

Parameters:
  • dst – The destination buffer
  • src – The source data
Returns:

NGX_OK on success, NGX_ERROR on failure

ngx_decode_base64url

ngx_int_t ngx_decode_base64url(ngx_str_t *dst, ngx_str_t *src)

Base64 decodes a given input URL

Note

ngx_base64_decoded_length() should be used to calculate how much memory should be allocated for dst

Parameters:
  • dst – The destination buffer
  • src – The source data
Returns:

NGX_OK on success, NGX_ERROR on failure

ngx_utf8_decode

uint32_t ngx_utf8_decode(unsigned char **p, size_t n)

Validates a UTF8 character. The character pointer pointed to with p is moved to the end of the character. The following table shows the return values:

Value Meaning
0x80 - 0x10ffff valid character
0x110000 - 0xfffffffd invalid sequence
0xfffffffe incomplete sequence
0xffffffff error
Parameters:
  • p – A pointer to a pointer for the UTF8 sequence
  • n – The length of the sequence
Returns:

The status in the table above

ngx_utf8_length

size_t ngx_utf8_length(unsigned char *p, size_t n)

Returns the number of UTF8 characters in a given string.

Parameters:
  • p – The character string to count
  • n – The length of the string
Returns:

The number of UTF8 characters in the string or an error from ngx_utf8_decode()

ngx_utf8_cpystrn

unsigned char *ngx_utf8_cpystrn(unsigned char *dst, unsigned char *src, size_t n, size_t len)

Copies a valid UTF8 sequence from one string to another, ignoring invalid characters

Parameters:
  • dst – The destination string
  • src – The source string
  • n – The maximum length of dst
  • len – The length of the src
Returns:

The position of dst plus the characters copied

ngx_escape_uri

uintptr_t ngx_escape_uri(unsigned char *dst, unsigned char *src, size_t size, ngx_uint_t type)

Escapes a URI. Different types use slightly different escape algorithms. A dst of NULL will return the number of characters that would be escaped. Otherwise a pointer to the end of data in dst is returned.

Type Definition
NGX_ESCAPE_URI Escape a standard URI
NGX_ESCAPE_ARGS Escape query arguments
NGX_ESCAPE_URI_COMPONENT Escape the URI after the domain
NGX_ESCAPE_HTML Escape a URI for an SSI include
NGX_ESCAPE_REFRESH Escape a URI in a refresh header
NGX_ESCAPE_MEMCACHED Escape a memcached URI
NGX_ESCAPE_MAIL_AUTH Escape a mail authentication URI
Parameters:
  • dst – A destination memory location, or NULL for a length count
  • src – The source string
  • size – The length of the source string
  • type – The type of escape algorithm to use
Returns:

A pointer to the end of the used dst or the count of escaped characters if dst is NULL

ngx_unescape_uri

void ngx_unescape_uri(unsigned char **dst, unsigned char **src, size_t size, ngx_uint_t type)

Unescapes a URI. Different types use slightly different unescape algorithms.

Type Definition
NGX_UNESCAPE_URI Unescape a standard URI
NGX_UNESCAPE_REDIRECT Unescape a redirect URI
Parameters:
  • dst – A destination memory location
  • src – The source string
  • size – The length of the source string
  • type – The type of escape algorithm to use

ngx_escape_html

uintptr_t ngx_escape_html(unsigned char *dst, unsigned char *src, size_t size)

Escapes HTML entities <, >, & and ". A dst of NULL will return the number of characters that would fill dst. Otherwise a pointer to the end of data in dst is returned.

Parameters:
  • dst – A destination memory location, or NULL for a length count
  • src – The source string
  • size – The length of the source string
Returns:

A pointer to the end of the used dst or the output count if dst is NULL

ngx_escape_json

uintptr_t ngx_escape_json(unsigned char *dst, unsigned char *src, size_t size)

Escapes the JSON entites \, ", 0x1f. Additional escape sequences \n, \r, \t, \b and \f are also escaped. A dst of NULL will return the number of characters that would fill dst. Otherwise a pointer to the end of data in dst is returned.

Parameters:
  • dst – A destination memory location, or NULL for a length count
  • src – The source string
  • size – The length of the source string
Returns:

A pointer to the end of the used dst or the output count if dst is NULL

ngx_sort

void ngx_sort(void *base, size_t n, size_t size, ngx_int_t (*cmp)(const void *, const void *))

An insertion sort algorithm with a template similar to the standard C qsort function. Sorts fixed-length data based on the results of a comparitor callback cmp. cmp should return -1 to left, 1 to shift right and 0 to not shift.

Parameters:
  • base – The pointer to an array of pointers to be sorted
  • n – The number of elements in base to be sorted
  • size – The size of each element in base
  • cmp – The callback executed on each compare

ngx_qsort

void ngx_qsort(void* base, size_t num, size_t size, int (*compar)(const void*,const void*))

An alias to the standard qsort function

Parameters:
  • base – The pointer to an array of pointers to be sorted
  • num – The number of elements in base to be sorted
  • size – The size of each element in base
  • compar – The callback executed on each compare

ngx_hash

ngx_uint_t ngx_hash(ngx_uint_t key, unsigned char c)

A macro that generates a hash of a single character. Defined as:

((ngx_uint_t) key * 31 + c)

It is designed to be run over an entire string to generate a full hash

Parameters:
  • key – The key to update with the hash of a new character
  • c – The character to add to the hash
Returns:

An updated key

ngx_hash_strlow

ngx_uint_t ngx_hash_strlow(unsigned char *dst, unsigned char *src, size_t n)

Sets a given string to lowercase using ngx_tolower() on every character, stores it in dst and generates a hash from that string using ngx_hash()

Parameters:
  • dst – The destination of the lowercase string
  • src – The source string
  • n – The length of the source string
Returns:

A hash key based on the dst

ngx_regex_init

ngx_int_t ngx_regex_compile(ngx_regex_compile_t *rc)

Compile a regular expression based on a pre-definied ngx_regex_compile_t structure.

Parameters:
  • rc – The regular expression to compile
Returns:

NGX_OK on success, NGX_ERROR on failure

ngx_regex_exec

int ngx_regex_exec(ngx_regex_compile_t *re, ngx_str_t *s, int *captures, int size)

A macro wrapper around pcre_exec to execute the regular expression

Parameters:
  • rc – A regular expression compiled with ngx_regex_compile()
  • s – A string to execute the regular expression against
  • captures – A pre-allocated array of integers that will be used to identify the captured strings in s
  • size – The number of elements allocated for captures
Result:

0 on success, NGX_REGEX_NOMATCH if there are no matches, < -1 on error

ngx_regex_exec_array

ngx_int_t ngx_regex_exec_array(ngx_array_t *a, ngx_str_t *s, ngx_log_t *log)

Execute an array of regular expressions against a string. This only returns whether or not there is a match, no details of the match

Parameters:
  • a – The array of ngx_regex_compile_t regular expressions
  • s – A string to execute the regular expressions against
  • log – The log object to send error messages to
Returns:

NGX_OK on a match found, NGX_DECLINED if no match is found, NGX_ERROR if an error occurred.