Crate nginx_sys

Expand description

§nginx-sys

The nginx-sys crate provides low-level bindings for the nginx C API, allowing Rust applications to interact with nginx servers and modules.

§Usage

Add nginx-sys as a dependency in your Cargo.toml:

[dependencies]
nginx-sys = "0.5.0"

Set the path to your nginx sources and build directory using the environment variables, or enable the nginx-sys/vendored feature to use a downloaded copy of the nginx sources.

Note that it is recommended to use the exact source and configure arguments of the nginx build you are planning to use in production. configure arguments alter the APIs and the symbols visible to the Rust code, and some OS distributions are known to ship nginx packages with API-breaking patches applied.

§Features

vendored: Enables the build scripts to download and build a copy of nginx source and link against it.

§Input variables

NGINX_SOURCE_DIR, NGINX_BUILD_DIR control paths to an external nginx source tree and a configured build directory. Normally, specifying either of these is sufficient, as the build directory defaults to objs under the source dir.

However, it’s possible to set the latter to any valid path with configure --builddir=<...>, and we need both paths to support such configuration.

The variables above are optional, but take preference when the vendored crate feature is enabled.

§Output variables

Following metadata variables are passed to the build scripts of any direct dependents of the package.

Check the using another sys crate and the links manifest key sections of the Cargo Book for more details about passing metadata between packages.

§`DEP_NGINX_FEATURES`

nginx has various configuration options that may affect the availability of functions, constants and structure fields. This is not something that can be detected at runtime, as an attempt to use a symbol unavailable in the bindings would result in compilation error.

DEP_NGINX_FEATURES_CHECK contains the full list of feature flags supported by nginx-sys, i.e. everything that can be used for feature checks. The most common use for this variable is to specify cargo::rustc-check-cfg.

DEP_NGINX_FEATURES contains the list of features enabled in the version of nginx being built against.

An example of a build script with these variables:

// Specify acceptable values for `ngx_feature`.
println!("cargo::rerun-if-env-changed=DEP_NGINX_FEATURES_CHECK");
println!(
    "cargo::rustc-check-cfg=cfg(ngx_feature, values({}))",
    std::env::var("DEP_NGINX_FEATURES_CHECK").unwrap_or("any()".to_string())
);
// Read feature flags detected by nginx-sys and pass to the compiler.
println!("cargo::rerun-if-env-changed=DEP_NGINX_FEATURES");
if let Ok(features) = std::env::var("DEP_NGINX_FEATURES") {
    for feature in features.split(',').map(str::trim) {
        println!("cargo::rustc-cfg=ngx_feature=\"{}\"", feature);
    }
}

And an usage example:

#[cfg(ngx_feature = "debug")]
println!("this nginx binary was built with debug logging enabled");

§`DEP_NGINX_OS`

Version, as detected by the nginx configuration script.

DEP_NGINX_OS_CHECK contains the full list of supported values, and DEP_NGINX_OS the currently detected one.

Usage examples:

// Specify acceptable values for `ngx_os`
println!("cargo::rerun-if-env-changed=DEP_NGINX_OS_CHECK");
println!(
    "cargo::rustc-check-cfg=cfg(ngx_os, values({}))",
    std::env::var("DEP_NGINX_OS_CHECK").unwrap_or("any()".to_string())
);
// Read operating system detected by nginx-sys and pass to the compiler.
println!("cargo::rerun-if-env-changed=DEP_NGINX_OS");
if let Ok(os) = std::env::var("DEP_NGINX_OS") {
    println!("cargo::rustc-cfg=ngx_os=\"{}\"", os);
}

#[cfg(ngx_os = "freebsd")]
println!("this nginx binary was built on FreeBSD");

§Version and build information

DEP_NGINX_VERSION_NUMBER: a numeric representation with 3 digits for each component: 1026002
DEP_NGINX_VERSION: human-readable string in a product/version format: nginx/1.26.2
DEP_NGINX_BUILD: version string with the optional build name (--build=) included: nginx/1.25.5 (nginx-plus-r32)

Usage example:

println!("cargo::rustc-check-cfg=cfg(nginx1_27_0)");
println!("cargo::rerun-if-env-changed=DEP_NGINX_VERSION_NUMBER");
if let Ok(version) = std::env::var("DEP_NGINX_VERSION_NUMBER") {
    let version: u64 = version.parse().unwrap();

    if version >= 1_027_000 {
        println!("cargo::rustc-cfg=nginx1_27_0");
    }
}

§Examples

§Get nginx Version

This example demonstrates how to retrieve the version of the nginx server.

use nginx_sys::nginx_version;

println!("nginx version: {}", nginx_version);

Modules§

detail: Implementation details shared between nginx-sys and ngx.

Macros§

ngx_queue_data: Get a reference to the beginning of a queue node data structure, considering the queue field offset in it.
ngx_rbtree_data: Get a reference to the beginning of a tree element data structure, considering the link field offset in it.

Constants§

NGX_ALIGNMENT: Default alignment for pool allocations.
NGX_HTTP_LOC_CONF_OFFSET: The offset of the loc_conf field in the ngx_http_conf_ctx_t struct.
NGX_HTTP_MAIN_CONF_OFFSET: The offset of the main_conf field in the ngx_http_conf_ctx_t struct.
NGX_HTTP_SRV_CONF_OFFSET: The offset of the srv_conf field in the ngx_http_conf_ctx_t struct.
NGX_STREAM_MAIN_CONF_OFFSET: The offset of the main_conf field in the ngx_stream_conf_ctx_t struct.
NGX_STREAM_SRV_CONF_OFFSET: The offset of the srv_conf field in the ngx_stream_conf_ctx_t struct.

Functions§

add_to_ngx_table^⚠: Add a key-value pair to an nginx table entry (ngx_table_elt_t) in the given nginx memory pool.
ngx_add_timer^⚠: Sets a timeout for an event.
ngx_del_timer^⚠: Deletes a previously set timeout.
ngx_delete_posted_event^⚠: Deletes the event ev from the queue it’s currently posted in.
ngx_errno: Returns the error code of the last failed operation (errno).
ngx_list_init^⚠: Initialize a list, using a pool for the backing memory, with capacity to store the given number of elements and element size.
ngx_post_event^⚠: Post the event ev to the post queue q.
ngx_queue_add^⚠: Adds a second queue to the first queue.
ngx_queue_empty^⚠: Returns true if the queue contains no elements.
ngx_queue_init^⚠: Initializes the queue head before use.
ngx_queue_insert_after^⚠: Inserts a new node after the current.
ngx_queue_insert_before^⚠: Inserts a new node before the current.
ngx_queue_remove^⚠: Removes a node from the queue.
ngx_queue_split^⚠: Splits a queue at a node, returning the queue tail in a separate queue.
ngx_random: Returns a non cryptograhpically-secure pseudo-random integer.
ngx_rbt_black^⚠: Marks the tree node as black.
ngx_rbt_red^⚠: Marks the tree node as red.
ngx_rbtree_init^⚠: Initializes the RbTree with specified sentinel and insert function.
ngx_rbtree_min^⚠: Returns the least (leftmost) node of the tree.
ngx_rbtree_sentinel_init^⚠: Initializes the sentinel node.
ngx_sched_yield: Causes the calling thread to relinquish the CPU.
ngx_set_errno: Sets the error code (errno).
ngx_set_socket_errno: Sets the error code of the sockets operation.
ngx_socket_errno: Returns the error code of the last failed sockets operation.
ngx_time: Returns cached timestamp in seconds, updated at the start of the event loop iteration.
ngx_timeofday: Returns cached time, updated at the start of the event loop iteration.

Crate nginx_sysCopy item path