# phpman > man > LIBNFTABLES(3) [LIBNFTABLES(3)](https://www.chedong.com/phpMan.php/man/LIBNFTABLES/3/markdown) [LIBNFTABLES(3)](https://www.chedong.com/phpMan.php/man/LIBNFTABLES/3/markdown) ## NAME libnftables - nftables frontend library ## SYNOPSIS ### #include **struct** **nft**___**ctx** ***nft**___**ctx**___**new(uint32**___**t** _flags_**);** **void** **nft**___**ctx**___**free(struct** **nft**___**ctx** _*ctx_**);** **bool** **nft**___**ctx**___**get**___**dry**___**run(struct** **nft**___**ctx** _*ctx_**);** **void** **nft**___**ctx**___**set**___**dry**___**run(struct** **nft**___**ctx** _*ctx_**,** **bool** _dry_**);** **unsigned** **int** **nft**___**ctx**___**output**___**get**___**flags(struct** **nft**___**ctx** _*ctx_**);** **void** **nft**___**ctx**___**output**___**set**___**flags(struct** **nft**___**ctx** _*ctx_**,** **unsigned** **int** _flags_**);** **unsigned** **int** **nft**___**ctx**___**output**___**get**___**debug(struct** **nft**___**ctx** _*ctx_**);** **void** **nft**___**ctx**___**output**___**set**___**debug(struct** **nft**___**ctx** _*ctx_**,** **unsigned** **int** _mask_**);** **FILE** ***nft**___**ctx**___**set**___**output(struct** **nft**___**ctx** _*ctx_**,** **FILE** _*fp_**);** **int** **nft**___**ctx**___**buffer**___**output(struct** **nft**___**ctx** _*ctx_**);** **int** **nft**___**ctx**___**unbuffer**___**output(struct** **nft**___**ctx** _*ctx_**);** **const** **char** ***nft**___**ctx**___**get**___**output**___**buffer(struct** **nft**___**ctx** _*ctx_**);** **FILE** ***nft**___**ctx**___**set**___**error(struct** **nft**___**ctx** _*ctx_**,** **FILE** _*fp_**);** **int** **nft**___**ctx**___**buffer**___**error(struct** **nft**___**ctx** _*ctx_**);** **int** **nft**___**ctx**___**unbuffer**___**error(struct** **nft**___**ctx** _*ctx_**);** **const** **char** ***nft**___**ctx**___**get**___**error**___**buffer(struct** **nft**___**ctx** _*ctx_**);** **int** **nft**___**ctx**___**add**___**include**___**path(struct** **nft**___**ctx** _*ctx_**,** **const** **char** _*path_**);** **void** **nft**___**ctx**___**clear**___**include**___**paths(struct** **nft**___**ctx** _*ctx_**);** **int** **nft**___**run**___**cmd**___**from**___**buffer(struct** **nft**___**ctx** _*nft_**,** **const** **char** _*buf_**);** **int** **nft**___**run**___**cmd**___**from**___**filename(struct** **nft**___**ctx** _*nft_**,** **const** **char** _*filename_**);** Link with _-lnftables_. ## DESCRIPTION This library was designed with nftables integration into applications in mind. Its API is therefore kept as simple as possible, which somewhat limits its flexibility. Due to support for JSON markup of input and output though, convenience in constructing and parsing of input and output data may be achieved by using a third-party library such as **libjansson**. At the very basic level, one has to allocate a new object of type **struct** **nft**___**ctx** using **nft**___**ctx**___**new**() function, then pass commands via **nft**___**run**___**cmd**___**from**___**buffer**() or **nft**___**run**___**cmd**___**from**___**filename**() functions. By default, any output is written to **stdout** (or **stderr** for error messages). These file pointers may be changed using **nft**___**ctx**___**set**___**output**() and **nft**___**ctx**___**set**___**error**() functions. On top of that, it is possible to have any output buffered by the library for later retrieval as a static buffer. See **nft**___**ctx**___**buffer**___**output**() and **nft**___**ctx**___**buffer**___**error**() functions for details. **nft**___**ctx**___**new()** **and** **nft**___**ctx**___**free()** These functions aid in nft context management. In order to make use of the library, at least one context object has to be allocated. The context holds temporary data such as caches, library configuration and (if enabled) output and error buffers. The **nft**___**ctx**___**new**() function allocates and returns a new context object. The parameter _flags_ is unused at this point and should be set to zero. For convenience, the macro **NFT**___**CTX**___**DEFAULT** is defined to that value. The **nft**___**ctx**___**free**() function frees the context object pointed to by _ctx_, including any caches or buffers it may hold. **nft**___**ctx**___**get**___**dry**___**run()** **and** **nft**___**ctx**___**set**___**dry**___**run()** Dry-run setting controls whether ruleset changes are actually committed on kernel side or not. It allows to check whether a given operation would succeed without making actual changes to the ruleset. The default setting is **false**. The **nft**___**ctx**___**get**___**dry**___**run**() function returns the dry-run setting’s value contained in _ctx_. The **nft**___**ctx**___**set**___**dry**___**run**() function sets the dry-run setting in _ctx_ to the value of _dry_. **nft**___**ctx**___**output**___**get**___**flags()** **and** **nft**___**ctx**___**output**___**set**___**flags()** The flags setting controls the output format. enum { NFT_CTX_OUTPUT_REVERSEDNS = (1 << 0), NFT_CTX_OUTPUT_SERVICE = (1 << 1), NFT_CTX_OUTPUT_STATELESS = (1 << 2), NFT_CTX_OUTPUT_HANDLE = (1 << 3), NFT_CTX_OUTPUT_JSON = (1 << 4), NFT_CTX_OUTPUT_ECHO = (1 << 5), NFT_CTX_OUTPUT_GUID = (1 << 6), NFT_CTX_OUTPUT_NUMERIC_PROTO = (1 << 7), NFT_CTX_OUTPUT_NUMERIC_PRIO = (1 << 8), NFT_CTX_OUTPUT_NUMERIC_SYMBOL = (1 << 9), NFT_CTX_OUTPUT_NUMERIC_TIME = (1 << 10), NFT_CTX_OUTPUT_NUMERIC_ALL = (NFT_CTX_OUTPUT_NUMERIC_PROTO | NFT_CTX_OUTPUT_NUMERIC_PRIO | NFT_CTX_OUTPUT_NUMERIC_SYMBOL | NFT_CTX_OUTPUT_NUMERIC_TIME), NFT_CTX_OUTPUT_TERSE = (1 << 11), }; NFT_CTX_OUTPUT_REVERSEDNS Reverse DNS lookups are performed for IP addresses when printing. Note that this may add significant delay to **list** commands depending on DNS resolver speed. NFT_CTX_OUTPUT_SERVICE Print port numbers as services as described in the /etc/services file. NFT_CTX_OUTPUT_STATELESS If stateless output has been requested, then stateful data is not printed. Stateful data refers to those objects that carry run-time data, e.g. the **counter** statement holds packet and byte counter values, making it stateful. NFT_CTX_OUTPUT_HANDLE Upon insertion into the ruleset, some elements are assigned a unique handle for identification purposes. For example, when deleting a table or chain, it may be identified either by name or handle. Rules on the other hand must be deleted by handle, because there is no other way to uniquely identify them. This flag makes ruleset listings include handle values. NFT_CTX_OUTPUT_JSON If enabled at compile-time, libnftables accepts input in JSON format and is able to print output in JSON format as well. See [**libnftables-json**(5)](https://www.chedong.com/phpMan.php/man/libnftables-json/5/markdown) for a description of the supported schema. This flag controls JSON output format, input is auto-detected. NFT_CTX_OUTPUT_ECHO The echo setting makes libnftables print the changes once they are committed to the kernel, just like a running instance of **nft** **monitor** would. Amongst other things, this allows to retrieve an added rule’s handle atomically. NFT_CTX_OUTPUT_GUID Display UID and GID as described in the /etc/passwd and /etc/group files. NFT_CTX_OUTPUT_NUMERIC_PROTO Display layer 4 protocol numerically. NFT_CTX_OUTPUT_NUMERIC_PRIO Display base chain priority numerically. NFT_CTX_OUTPUT_NUMERIC_SYMBOL Display expression datatype as numeric value. NFT_CTX_OUTPUT_NUMERIC_TIME Display time, day and hour values in numeric format. NFT_CTX_OUTPUT_NUMERIC_ALL Display all numerically. NFT_CTX_OUTPUT_TERSE If terse output has been requested, then the contents of sets are not printed. The **nft**___**ctx**___**output**___**get**___**flags**() function returns the output flags setting’s value in _ctx_. The **nft**___**ctx**___**output**___**set**___**flags**() function sets the output flags setting in _ctx_ to the value of _val_. **nft**___**ctx**___**output**___**get**___**debug()** **and** **nft**___**ctx**___**output**___**set**___**debug()** Libnftables supports separate debugging of different parts of its internals. To facilitate this, debugging output is controlled via a bit mask. The bits are defined as such: enum nft_debug_level { NFT_DEBUG_SCANNER = 0x1, NFT_DEBUG_PARSER = 0x2, NFT_DEBUG_EVALUATION = 0x4, NFT_DEBUG_NETLINK = 0x8, NFT_DEBUG_MNL = 0x10, NFT_DEBUG_PROTO_CTX = 0x20, NFT_DEBUG_SEGTREE = 0x40, }; NFT_DEBUG_SCANNER Print LEX debug output. NFT_DEBUG_PARSER Print YACC debug output. NFT_DEBUG_EVALUATION Print debug information about evaluation phase. NFT_DEBUG_NETLINK Print netlink debug output. NFT_DEBUG_MNL Print libmnl debug output. NFT_DEBUG_PROTO_CTX Print protocol context debug output. NFT_DEBUG_SEGTREE Print segtree (i.e. interval sets) debug output. The **nft**___**ctx**___**output**___**get**___**debug**() function returns the debug output setting’s value in _ctx_. The **nft**___**ctx**___**output**___**set**___**debug**() function sets the debug output setting in _ctx_ to the value of _mask_. ### Controlling library standard and error output By default, any output from the library (e.g., after a **list** command) is written to _stdout_ and any error messages are written to _stderr_. To give applications control over them, there are functions to assign custom file pointers as well as having the library buffer what would be written for later retrieval in a static buffer. This buffer is guaranteed to be null-terminated and must not be freed. Note that the retrieval functions rewind the buffer position indicator. Further library output will probably overwrite the buffer content and potentially render it invalid (due to reallocation). The **nft**___**ctx**___**set**___**output**() and **nft**___**ctx**___**set**___**error**() functions set the output or error file pointer in _ctx_ to the value of _fp_. They return the previous value to aid in temporary file pointer overrides. On error, these functions return NULL. This happens only if _fp_ is NULL or invalid (tested using **ferror**() function). The **nft**___**ctx**___**buffer**___**output**() and **nft**___**ctx**___**buffer**___**error**() functions enable library standard or error output buffering. The functions return zero on success, non-zero otherwise. This may happen if the internal call to **fopencookie**() failed. The **nft**___**ctx**___**unbuffer**___**output**() and **nft**___**ctx**___**unbuffer**___**error**() functions disable library standard or error output buffering. On failure, the functions return non-zero which may only happen if buffering was not enabled at the time the function was called. The **nft**___**ctx**___**get**___**output**___**buffer**() and **nft**___**ctx**___**get**___**error**___**buffer**() functions return a pointer to the buffered output (which may be empty). **nft**___**ctx**___**add**___**include**___**path()** **and** **nft**___**ctx**___**clear**___**include**___**path()** The **include** command in nftables rulesets allows to outsource parts of the ruleset into a different file. The include path defines where these files are searched for. Libnftables allows to have a list of those paths which are searched in order. The default include path list contains a single compile-time defined entry (typically _/etc/_). The **nft**___**ctx**___**add**___**include**___**path**() function extends the list of include paths in _ctx_ by the one given in _path_. The function returns zero on success or non-zero if memory allocation failed. The **nft**___**ctx**___**clear**___**include**___**paths**() function removes all include paths, even the built-in default one. **nft**___**run**___**cmd**___**from**___**buffer()** **and** **nft**___**run**___**cmd**___**from**___**filename()** These functions perform the actual work of parsing user input into nftables commands and executing them. The **nft**___**run**___**cmd**___**from**___**buffer**() function passes the command(s) contained in _buf_ (which must be null-terminated) to the library, respecting settings and state in _nft_. The **nft**___**run**___**cmd**___**from**___**filename**() function passes the content of _filename_ to the library, respecting settings and state in _nft_. Both functions return zero on success. A non-zero return code indicates an error while parsing or executing the command. This event should be accompanied by an error message written to library error output. ## EXAMPLE #include #include #include int main(void) { char *list_cmd = "list ruleset"; struct nft_ctx *nft; const char *output, *p; char buf[256]; int rc = 0; nft = nft_ctx_new(NFT_CTX_DEFAULT); if (!nft) return 1; while (1) { if ([nft_ctx_buffer_output(nft)](https://www.chedong.com/phpMan.php/man/nftctxbufferoutput/nft/markdown) || nft_run_cmd_from_buffer(nft, list_cmd)) { rc = 1; break; } output = [nft_ctx_get_output_buffer(nft)](https://www.chedong.com/phpMan.php/man/nftctxgetoutputbuffer/nft/markdown); if (strlen(output)) { printf("\nThis is the current ruleset:\n| "); for (p = output; *(p + 1); p++) { if (*p == '\n') printf("\n| "); else putchar(*p); } putchar('\n'); } else { printf("\nCurrent ruleset is empty.\n"); } [nft_ctx_unbuffer_output(nft)](https://www.chedong.com/phpMan.php/man/nftctxunbufferoutput/nft/markdown); printf("\nEnter command ('q' to quit): "); fflush(stdout); fgets(buf, 256, stdin); if (strlen(buf)) buf[strlen(buf) - 1] = '\0'; if (buf[0] == 'q' && buf[1] == '\0') break; if (nft_run_cmd_from_buffer(nft, buf)) { rc = 1; break; } } [nft_ctx_free(nft)](https://www.chedong.com/phpMan.php/man/nftctxfree/nft/markdown); return rc; } ## SEE ALSO [**libnftables-json**(5)](https://www.chedong.com/phpMan.php/man/libnftables-json/5/markdown), [**nft**(8)](https://www.chedong.com/phpMan.php/man/nft/8/markdown) ## AUTHOR **Phil** **Sutter** <> Author. 02/24/2026 [LIBNFTABLES(3)](https://www.chedong.com/phpMan.php/man/LIBNFTABLES/3/markdown)