{
    "content": [
        {
            "type": "text",
            "text": "# libnftables (man)\n\n## NAME\n\nlibnftables - nftables frontend library\n\n## DESCRIPTION\n\nThis library was designed with nftables integration into applications in mind. Its API is\ntherefore kept as simple as possible, which somewhat limits its flexibility. Due to support\nfor JSON markup of input and output though, convenience in constructing and parsing of input\nand output data may be achieved by using a third-party library such as libjansson.\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS** (1 subsections)\n- **DESCRIPTION** (1 subsections)\n- **EXAMPLE**\n- **SEE ALSO**\n- **AUTHOR**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n"
        }
    ],
    "structuredContent": {
        "command": "libnftables",
        "section": "",
        "mode": "man",
        "summary": "libnftables - nftables frontend library",
        "synopsis": "",
        "tldr_summary": null,
        "tldr_examples": [],
        "tldr_source": null,
        "flags": [],
        "examples": [
            "#include <stdio.h>",
            "#include <string.h>",
            "#include <nftables/libnftables.h>",
            "int main(void)",
            "char *listcmd = \"list ruleset\";",
            "struct nftctx *nft;",
            "const char *output, *p;",
            "char buf[256];",
            "int rc = 0;",
            "nft = nftctxnew(NFTCTXDEFAULT);",
            "if (!nft)",
            "return 1;",
            "while (1) {",
            "if (nftctxbufferoutput(nft) ||",
            "nftruncmdfrombuffer(nft, listcmd)) {",
            "rc = 1;",
            "break;",
            "output = nftctxgetoutputbuffer(nft);",
            "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\");",
            "nftctxunbufferoutput(nft);",
            "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 (nftruncmdfrombuffer(nft, buf)) {",
            "rc = 1;",
            "break;",
            "nftctxfree(nft);",
            "return rc;"
        ],
        "see_also": [
            {
                "name": "libnftables-json",
                "section": "5",
                "url": "https://www.chedong.com/phpMan.php/man/libnftables-json/5/json"
            },
            {
                "name": "nft",
                "section": "8",
                "url": "https://www.chedong.com/phpMan.php/man/nft/8/json"
            }
        ],
        "section_outline": [
            {
                "name": "NAME",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "SYNOPSIS",
                "lines": 1,
                "subsections": [
                    {
                        "name": "#include <nftables/libnftables.h>",
                        "lines": 31
                    }
                ]
            },
            {
                "name": "DESCRIPTION",
                "lines": 151,
                "subsections": [
                    {
                        "name": "Controlling library standard and error output",
                        "lines": 50
                    }
                ]
            },
            {
                "name": "EXAMPLE",
                "lines": 56,
                "subsections": []
            },
            {
                "name": "SEE ALSO",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "AUTHOR",
                "lines": 6,
                "subsections": []
            }
        ],
        "sections": {
            "NAME": {
                "content": "libnftables - nftables frontend library\n",
                "subsections": []
            },
            "SYNOPSIS": {
                "content": "",
                "subsections": [
                    {
                        "name": "#include <nftables/libnftables.h>",
                        "content": "struct nftctx *nftctxnew(uint32t flags);\nvoid nftctxfree(struct nftctx *ctx);\n\nbool nftctxgetdryrun(struct nftctx *ctx);\nvoid nftctxsetdryrun(struct nftctx *ctx, bool dry);\n\nunsigned int nftctxoutputgetflags(struct nftctx *ctx);\nvoid nftctxoutputsetflags(struct nftctx *ctx, unsigned int flags);\n\nunsigned int nftctxoutputgetdebug(struct nftctx *ctx);\nvoid nftctxoutputsetdebug(struct nftctx *ctx, unsigned int mask);\n\nFILE *nftctxsetoutput(struct nftctx *ctx, FILE *fp);\nint nftctxbufferoutput(struct nftctx *ctx);\nint nftctxunbufferoutput(struct nftctx *ctx);\nconst char *nftctxgetoutputbuffer(struct nftctx *ctx);\n\nFILE *nftctxseterror(struct nftctx *ctx, FILE *fp);\nint nftctxbuffererror(struct nftctx *ctx);\nint nftctxunbuffererror(struct nftctx *ctx);\nconst char *nftctxgeterrorbuffer(struct nftctx *ctx);\n\nint nftctxaddincludepath(struct nftctx *ctx, const char *path);\nvoid nftctxclearincludepaths(struct nftctx *ctx);\n\nint nftruncmdfrombuffer(struct nftctx *nft, const char *buf);\nint nftruncmdfromfilename(struct nftctx *nft,\nconst char *filename);\n\nLink with -lnftables.\n"
                    }
                ]
            },
            "DESCRIPTION": {
                "content": "This library was designed with nftables integration into applications in mind. Its API is\ntherefore kept as simple as possible, which somewhat limits its flexibility. Due to support\nfor JSON markup of input and output though, convenience in constructing and parsing of input\nand output data may be achieved by using a third-party library such as libjansson.\n\nAt the very basic level, one has to allocate a new object of type struct nftctx using\nnftctxnew() function, then pass commands via nftruncmdfrombuffer() or\nnftruncmdfromfilename() functions. By default, any output is written to stdout (or stderr\nfor error messages). These file pointers may be changed using nftctxsetoutput() and\nnftctxseterror() functions. On top of that, it is possible to have any output buffered by\nthe library for later retrieval as a static buffer. See nftctxbufferoutput() and\nnftctxbuffererror() functions for details.\n\nnftctxnew() and nftctxfree()\nThese functions aid in nft context management. In order to make use of the library, at least\none context object has to be allocated. The context holds temporary data such as caches,\nlibrary configuration and (if enabled) output and error buffers.\n\nThe nftctxnew() function allocates and returns a new context object. The parameter flags is\nunused at this point and should be set to zero. For convenience, the macro NFTCTXDEFAULT is\ndefined to that value.\n\nThe nftctxfree() function frees the context object pointed to by ctx, including any caches\nor buffers it may hold.\n\nnftctxgetdryrun() and nftctxsetdryrun()\nDry-run setting controls whether ruleset changes are actually committed on kernel side or\nnot. It allows to check whether a given operation would succeed without making actual changes\nto the ruleset. The default setting is false.\n\nThe nftctxgetdryrun() function returns the dry-run setting’s value contained in ctx.\n\nThe nftctxsetdryrun() function sets the dry-run setting in ctx to the value of dry.\n\nnftctxoutputgetflags() and nftctxoutputsetflags()\nThe flags setting controls the output format.\n\nenum {\nNFTCTXOUTPUTREVERSEDNS     = (1 << 0),\nNFTCTXOUTPUTSERVICE        = (1 << 1),\nNFTCTXOUTPUTSTATELESS      = (1 << 2),\nNFTCTXOUTPUTHANDLE         = (1 << 3),\nNFTCTXOUTPUTJSON           = (1 << 4),\nNFTCTXOUTPUTECHO           = (1 << 5),\nNFTCTXOUTPUTGUID           = (1 << 6),\nNFTCTXOUTPUTNUMERICPROTO  = (1 << 7),\nNFTCTXOUTPUTNUMERICPRIO   = (1 << 8),\nNFTCTXOUTPUTNUMERICSYMBOL = (1 << 9),\nNFTCTXOUTPUTNUMERICTIME   = (1 << 10),\nNFTCTXOUTPUTNUMERICALL    = (NFTCTXOUTPUTNUMERICPROTO |\nNFTCTXOUTPUTNUMERICPRIO  |\nNFTCTXOUTPUTNUMERICSYMBOL |\nNFTCTXOUTPUTNUMERICTIME),\nNFTCTXOUTPUTTERSE          = (1 << 11),\n};\n\nNFTCTXOUTPUTREVERSEDNS\nReverse DNS lookups are performed for IP addresses when printing. Note that this may add\nsignificant delay to list commands depending on DNS resolver speed.\n\nNFTCTXOUTPUTSERVICE\nPrint port numbers as services as described in the /etc/services file.\n\nNFTCTXOUTPUTSTATELESS\nIf stateless output has been requested, then stateful data is not printed. Stateful data\nrefers to those objects that carry run-time data, e.g. the counter statement holds packet\nand byte counter values, making it stateful.\n\nNFTCTXOUTPUTHANDLE\nUpon insertion into the ruleset, some elements are assigned a unique handle for\nidentification purposes. For example, when deleting a table or chain, it may be\nidentified either by name or handle. Rules on the other hand must be deleted by handle,\nbecause there is no other way to uniquely identify them. This flag makes ruleset listings\ninclude handle values.\n\nNFTCTXOUTPUTJSON\nIf enabled at compile-time, libnftables accepts input in JSON format and is able to print\noutput in JSON format as well. See libnftables-json(5) for a description of the supported\nschema. This flag controls JSON output format, input is auto-detected.\n\nNFTCTXOUTPUTECHO\nThe echo setting makes libnftables print the changes once they are committed to the\nkernel, just like a running instance of nft monitor would. Amongst other things, this\nallows to retrieve an added rule’s handle atomically.\n\nNFTCTXOUTPUTGUID\nDisplay UID and GID as described in the /etc/passwd and /etc/group files.\n\nNFTCTXOUTPUTNUMERICPROTO\nDisplay layer 4 protocol numerically.\n\nNFTCTXOUTPUTNUMERICPRIO\nDisplay base chain priority numerically.\n\nNFTCTXOUTPUTNUMERICSYMBOL\nDisplay expression datatype as numeric value.\n\nNFTCTXOUTPUTNUMERICTIME\nDisplay time, day and hour values in numeric format.\n\nNFTCTXOUTPUTNUMERICALL\nDisplay all numerically.\n\nNFTCTXOUTPUTTERSE\nIf terse output has been requested, then the contents of sets are not printed.\n\nThe nftctxoutputgetflags() function returns the output flags setting’s value in ctx.\n\nThe nftctxoutputsetflags() function sets the output flags setting in ctx to the value of\nval.\n\nnftctxoutputgetdebug() and nftctxoutputsetdebug()\nLibnftables supports separate debugging of different parts of its internals. To facilitate\nthis, debugging output is controlled via a bit mask. The bits are defined as such:\n\nenum nftdebuglevel {\nNFTDEBUGSCANNER               = 0x1,\nNFTDEBUGPARSER                = 0x2,\nNFTDEBUGEVALUATION            = 0x4,\nNFTDEBUGNETLINK               = 0x8,\nNFTDEBUGMNL                   = 0x10,\nNFTDEBUGPROTOCTX             = 0x20,\nNFTDEBUGSEGTREE               = 0x40,\n};\n\nNFTDEBUGSCANNER\nPrint LEX debug output.\n\nNFTDEBUGPARSER\nPrint YACC debug output.\n\nNFTDEBUGEVALUATION\nPrint debug information about evaluation phase.\n\nNFTDEBUGNETLINK\nPrint netlink debug output.\n\nNFTDEBUGMNL\nPrint libmnl debug output.\n\nNFTDEBUGPROTOCTX\nPrint protocol context debug output.\n\nNFTDEBUGSEGTREE\nPrint segtree (i.e. interval sets) debug output.\n\nThe nftctxoutputgetdebug() function returns the debug output setting’s value in ctx.\n\nThe nftctxoutputsetdebug() function sets the debug output setting in ctx to the value of\nmask.\n",
                "subsections": [
                    {
                        "name": "Controlling library standard and error output",
                        "content": "By default, any output from the library (e.g., after a list command) is written to stdout and\nany error messages are written to stderr. To give applications control over them, there are\nfunctions to assign custom file pointers as well as having the library buffer what would be\nwritten for later retrieval in a static buffer. This buffer is guaranteed to be\nnull-terminated and must not be freed. Note that the retrieval functions rewind the buffer\nposition indicator. Further library output will probably overwrite the buffer content and\npotentially render it invalid (due to reallocation).\n\nThe nftctxsetoutput() and nftctxseterror() functions set the output or error file\npointer in ctx to the value of fp. They return the previous value to aid in temporary file\npointer overrides. On error, these functions return NULL. This happens only if fp is NULL or\ninvalid (tested using ferror() function).\n\nThe nftctxbufferoutput() and nftctxbuffererror() functions enable library standard or\nerror output buffering. The functions return zero on success, non-zero otherwise. This may\nhappen if the internal call to fopencookie() failed.\n\nThe nftctxunbufferoutput() and nftctxunbuffererror() functions disable library standard\nor error output buffering. On failure, the functions return non-zero which may only happen if\nbuffering was not enabled at the time the function was called.\n\nThe nftctxgetoutputbuffer() and nftctxgeterrorbuffer() functions return a pointer to\nthe buffered output (which may be empty).\n\nnftctxaddincludepath() and nftctxclearincludepath()\nThe include command in nftables rulesets allows to outsource parts of the ruleset into a\ndifferent file. The include path defines where these files are searched for. Libnftables\nallows to have a list of those paths which are searched in order. The default include path\nlist contains a single compile-time defined entry (typically /etc/).\n\nThe nftctxaddincludepath() function extends the list of include paths in ctx by the one\ngiven in path. The function returns zero on success or non-zero if memory allocation failed.\n\nThe nftctxclearincludepaths() function removes all include paths, even the built-in\ndefault one.\n\nnftruncmdfrombuffer() and nftruncmdfromfilename()\nThese functions perform the actual work of parsing user input into nftables commands and\nexecuting them.\n\nThe nftruncmdfrombuffer() function passes the command(s) contained in buf (which must be\nnull-terminated) to the library, respecting settings and state in nft.\n\nThe nftruncmdfromfilename() function passes the content of filename to the library,\nrespecting settings and state in nft.\n\nBoth functions return zero on success. A non-zero return code indicates an error while\nparsing or executing the command. This event should be accompanied by an error message\nwritten to library error output.\n"
                    }
                ]
            },
            "EXAMPLE": {
                "content": "#include <stdio.h>\n#include <string.h>\n#include <nftables/libnftables.h>\n\nint main(void)\n{\nchar *listcmd = \"list ruleset\";\nstruct nftctx *nft;\nconst char *output, *p;\nchar buf[256];\nint rc = 0;\n\nnft = nftctxnew(NFTCTXDEFAULT);\nif (!nft)\nreturn 1;\n\nwhile (1) {\nif (nftctxbufferoutput(nft) ||\nnftruncmdfrombuffer(nft, listcmd)) {\nrc = 1;\nbreak;\n}\noutput = nftctxgetoutputbuffer(nft);\nif (strlen(output)) {\nprintf(\"\\nThis is the current ruleset:\\n| \");\nfor (p = output; *(p + 1); p++) {\nif (*p == '\\n')\nprintf(\"\\n| \");\nelse\nputchar(*p);\n}\nputchar('\\n');\n} else {\nprintf(\"\\nCurrent ruleset is empty.\\n\");\n}\nnftctxunbufferoutput(nft);\n\nprintf(\"\\nEnter command ('q' to quit): \");\nfflush(stdout);\nfgets(buf, 256, stdin);\nif (strlen(buf))\nbuf[strlen(buf) - 1] = '\\0';\n\nif (buf[0] == 'q' && buf[1] == '\\0')\nbreak;\n\nif (nftruncmdfrombuffer(nft, buf)) {\nrc = 1;\nbreak;\n}\n}\n\nnftctxfree(nft);\nreturn rc;\n}\n",
                "subsections": []
            },
            "SEE ALSO": {
                "content": "libnftables-json(5), nft(8)\n",
                "subsections": []
            },
            "AUTHOR": {
                "content": "Phil Sutter <phil@nwl.cc>\nAuthor.\n\n\n\n02/24/2026                               LIBNFTABLES(3)",
                "subsections": []
            }
        }
    }
}