Configuration Variables API

Configuration Variables API

Structures

ngx_http_variable_value_t

The structure containing the details of a variable’s value.

unsigned len:28

The length of the data parameter (a 28bit number)

unsigned valid:1

A boolean to determine whether or not a cached value is valid

unsigned no_cacheable:1

A boolean to determine whether or not the value is cachable

unsigned not_found:1

A boolean stating whether or not the requested variable was found

unsigned char *data

The value of the variable

ngx_http_variable_t

A structure to hold details about a configuration variable

ngx_int_t (*ngx_http_get_variable_pt)(ngx_http_request_t *r, ngx_http_variable_value_t *v, uintptr_t data)

A callback to execute when retrieving a value of variable

void (*ngx_http_set_variable_pt)(ngx_http_request_t *r, ngx_http_variable_value_t *v, uintptr_t data)

A callback to execute when setting a value of a variable

uintptr_t data

A pointer to data for use with the get/set callback functions

Functions

ngx_http_add_variable

ngx_http_variable_t *ngx_http_add_variable(ngx_conf_t *cf, ngx_str_t *name, ngx_uint_t flags)

Adds a variable to a configuration. This should be called from the pre-configuration hook of ngx_http_module_t

Flag Description
NGX_HTTP_VAR_CHANGEABLE Enables the setting of the variable in the configuration file
NGX_HTTP_VAR_NOCACHEABLE The variable should not be cached
NGX_HTTP_VAR_NOHASH An optimistaition which removes the ability to use ngx_http_get_variable() on a variable
Parameters:
  • cf – The configuration object to add the variable to
  • name – The name of the variable
  • flags – Flags for the variable
Returns:

A pointer to a newly created variable

ngx_http_get_variable_index

ngx_int_t ngx_http_get_variable_index(ngx_conf_t *cf, ngx_str_t *name)

Get the index of variable based on its name

Parameters:
  • cf – The configuration object to search
  • name – The configuration name to search for
Returns:

The index ID of the variable or NGX_ERROR upon error

ngx_http_get_indexed_variable

ngx_http_variable_value_t *ngx_http_get_indexed_variable(ngx_http_request_t *r, ngx_uint_t index)

Get the current value for a variable

Parameters:
  • r – The request object requiring the variable
  • index – The index for the variable
Returns:

A pointer to the structure containing the variable

ngx_http_get_flushed_variable

ngx_http_variable_value_t *ngx_http_get_flushed_variable(ngx_http_request_t *r, ngx_uint_t index)

Flush the cache of a variable and get a new value for it

Parameters:
  • r – The request object requiring the variable
  • index – The index for the variable
Returns:

A pointer to the structure containing the variable

ngx_http_get_variable

ngx_http_variable_value_t *ngx_http_get_variable(ngx_http_request_t *r, ngx_str_t *name, ngx_uint_t key)

Gets a variable based on a hash lookup of the variable name. Does not work on variables that were initialized NGX_HTTP_VAR_NOHASH flag enabled.

The hash can be generated using ngx_hash_strlow(). For example:

key = ngx_hash_strlow(var.data, var.data, var.len);
vv = ngx_http_get_variable(r, &var, key);
Parameters:
  • r – The request object requiring the variable
  • name – The name of the requested variable
  • key – The hash of the variable name
Returns:

A pointer to the structure containing the variable