gumbo.h(3)

📦

version 0.12.1 · 3 versions

0.12.1 · fedora 43 (latest)
0.12.1 · epel 10
0.12.1 · fedora 44

✨ `gumbo.h` ✨

okay so bestie, welcome to gumbo.h(3) from the Gumbo manual. this is the header that runs the whole show, and if you're reading it you're out here writing C and parsing HTML like it's nothing. iconic behaviour honestly. 💅

this page is LONG, so it's split into parts — this is part 1. buckle up, hydrate, we're going in. 🫶

🎀 NAME 🎀

gumbo.h — yeah that's the whole name. the header itself, front and centre, main character energy. no notes. ✨

🌸 SYNOPSIS 🌸

#include <stdbool.h>
#include <stddef.h>
#include 'tag_enum.h'

okay yes, that third include has single quotes doing a little chaos dance instead of angle brackets, and no we are NOT fixing it, because the page says it exactly like that and we respect the source. 🙈✨

💜 Data Structures

the whole lil family of structs you're gonna be meeting:

struct GumboSourcePosition
struct GumboStringPiece
struct GumboVector
struct GumboAttribute
struct GumboDocument
struct GumboText
struct GumboElement
struct GumboNode
struct GumboOptions
struct GumboOutput

🦋 Typedefs

typedef void *(* GumboAllocatorFunction) (void *userdata, size_t size)
typedef void(* GumboDeallocatorFunction) (void *userdata, void *ptr)

🌈 Enumerations

`enum GumboTag`

bestie. sit down. this is the tag list. all of it. every single one. we are NOT skipping any, so here it is in full, character for character, because the vibe changes but the facts do not:

enum GumboTag { GUMBO_TAG_HTML, GUMBO_TAG_HEAD, GUMBO_TAG_TITLE,
    GUMBO_TAG_BASE, GUMBO_TAG_LINK, GUMBO_TAG_META, GUMBO_TAG_STYLE,
    GUMBO_TAG_SCRIPT, GUMBO_TAG_NOSCRIPT, GUMBO_TAG_TEMPLATE,
    GUMBO_TAG_BODY, GUMBO_TAG_ARTICLE, GUMBO_TAG_SECTION, GUMBO_TAG_NAV,
    GUMBO_TAG_ASIDE, GUMBO_TAG_H1, GUMBO_TAG_H2, GUMBO_TAG_H3,
    GUMBO_TAG_H4, GUMBO_TAG_H5, GUMBO_TAG_H6, GUMBO_TAG_HGROUP,
    GUMBO_TAG_HEADER, GUMBO_TAG_FOOTER, GUMBO_TAG_ADDRESS, GUMBO_TAG_P,
    GUMBO_TAG_HR, GUMBO_TAG_PRE, GUMBO_TAG_BLOCKQUOTE, GUMBO_TAG_OL,
    GUMBO_TAG_UL, GUMBO_TAG_LI, GUMBO_TAG_DL, GUMBO_TAG_DT,
    GUMBO_TAG_DD, GUMBO_TAG_FIGURE, GUMBO_TAG_FIGCAPTION,
    GUMBO_TAG_MAIN, GUMBO_TAG_DIV, GUMBO_TAG_A, GUMBO_TAG_EM,
    GUMBO_TAG_STRONG, GUMBO_TAG_SMALL, GUMBO_TAG_S, GUMBO_TAG_CITE,
    GUMBO_TAG_Q, GUMBO_TAG_DFN, GUMBO_TAG_ABBR, GUMBO_TAG_DATA,
    GUMBO_TAG_TIME, GUMBO_TAG_CODE, GUMBO_TAG_VAR, GUMBO_TAG_SAMP,
    GUMBO_TAG_KBD, GUMBO_TAG_SUB, GUMBO_TAG_SUP, GUMBO_TAG_I,
    GUMBO_TAG_B, GUMBO_TAG_U, GUMBO_TAG_MARK, GUMBO_TAG_RUBY,
    GUMBO_TAG_RT, GUMBO_TAG_RP, GUMBO_TAG_BDI, GUMBO_TAG_BDO,
    GUMBO_TAG_SPAN, GUMBO_TAG_BR, GUMBO_TAG_WBR, GUMBO_TAG_INS,
    GUMBO_TAG_DEL, GUMBO_TAG_IMAGE, GUMBO_TAG_IMG, GUMBO_TAG_PICTURE,
    GUMBO_TAG_IFRAME, GUMBO_TAG_EMBED, GUMBO_TAG_OBJECT,
    GUMBO_TAG_PARAM, GUMBO_TAG_VIDEO, GUMBO_TAG_AUDIO, GUMBO_TAG_SOURCE,
    GUMBO_TAG_TRACK, GUMBO_TAG_CANVAS, GUMBO_TAG_MAP, GUMBO_TAG_AREA,
    GUMBO_TAG_MATH, GUMBO_TAG_MI, GUMBO_TAG_MO, GUMBO_TAG_MN,
    GUMBO_TAG_MS, GUMBO_TAG_MTEXT, GUMBO_TAG_MGLYPH,
    GUMBO_TAG_MALIGNMARK, GUMBO_TAG_ANNOTATION_XML, GUMBO_TAG_SVG,
    GUMBO_TAG_FOREIGNOBJECT, GUMBO_TAG_DESC, GUMBO_TAG_TABLE,
    GUMBO_TAG_CAPTION, GUMBO_TAG_COLGROUP, GUMBO_TAG_COL,
    GUMBO_TAG_TBODY, GUMBO_TAG_THEAD, GUMBO_TAG_TFOOT, GUMBO_TAG_TR,
    GUMBO_TAG_TD, GUMBO_TAG_TH, GUMBO_TAG_FORM, GUMBO_TAG_FIELDSET,
    GUMBO_TAG_LEGEND, GUMBO_TAG_LABEL, GUMBO_TAG_INPUT,
    GUMBO_TAG_BUTTON, GUMBO_TAG_SELECT, GUMBO_TAG_DATALIST,
    GUMBO_TAG_OPTGROUP, GUMBO_TAG_OPTION, GUMBO_TAG_TEXTAREA,
    GUMBO_TAG_KEYGEN, GUMBO_TAG_OUTPUT, GUMBO_TAG_PROGRESS,
    GUMBO_TAG_METER, GUMBO_TAG_DETAILS, GUMBO_TAG_SUMMARY,
    GUMBO_TAG_MENU, GUMBO_TAG_MENUITEM, GUMBO_TAG_APPLET,
    GUMBO_TAG_ACRONYM, GUMBO_TAG_BGSOUND, GUMBO_TAG_DIR,
    GUMBO_TAG_FRAME, GUMBO_TAG_FRAMESET, GUMBO_TAG_NOFRAMES,
    GUMBO_TAG_ISINDEX, GUMBO_TAG_LISTING, GUMBO_TAG_XMP,
    GUMBO_TAG_NEXTID, GUMBO_TAG_NOEMBED, GUMBO_TAG_PLAINTEXT,
    GUMBO_TAG_RB, GUMBO_TAG_STRIKE, GUMBO_TAG_BASEFONT, GUMBO_TAG_BIG,
    GUMBO_TAG_BLINK, GUMBO_TAG_CENTER, GUMBO_TAG_FONT,
    GUMBO_TAG_MARQUEE, GUMBO_TAG_MULTICOL, GUMBO_TAG_NOBR,
    GUMBO_TAG_SPACER, GUMBO_TAG_DIALOG, GUMBO_TAG_TT, GUMBO_TAG_RTC,
    GUMBO_TAG_UNKNOWN, GUMBO_TAG_LAST }

and there you have it. every single tag, from GUMBO_TAG_HTML all the way down to GUMBO_TAG_UNKNOWN and GUMBO_TAG_LAST just vibing at the end of the list. the range? unmatched. 💀

`enum GumboAttributeNamespaceEnum`

enum GumboAttributeNamespaceEnum { GUMBO_ATTR_NAMESPACE_NONE,
    GUMBO_ATTR_NAMESPACE_XLINK, GUMBO_ATTR_NAMESPACE_XML,
    GUMBO_ATTR_NAMESPACE_XMLNS }

four lil namespace options, cute, concise, slay. 🎀

`enum GumboNodeType`

enum GumboNodeType { GUMBO_NODE_DOCUMENT, GUMBO_NODE_ELEMENT,
    GUMBO_NODE_TEXT, GUMBO_NODE_CDATA, GUMBO_NODE_COMMENT,
    GUMBO_NODE_WHITESPACE, GUMBO_NODE_TEMPLATE }

this is the "what kind of node am i looking at" enum and it has a case for GUMBO_NODE_WHITESPACE, which is honestly so real of it. 🫶

`enum GumboQuirksModeEnum`

enum GumboQuirksModeEnum { GUMBO_DOCTYPE_NO_QUIRKS,
    GUMBO_DOCTYPE_QUIRKS, GUMBO_DOCTYPE_LIMITED_QUIRKS }

three flavours of doctype quirk energy: none, full, and limited. a whole spectrum. 🌈

`enum GumboNamespaceEnum`

enum GumboNamespaceEnum { GUMBO_NAMESPACE_HTML, GUMBO_NAMESPACE_SVG,
    GUMBO_NAMESPACE_MATHML }

`enum GumboParseFlags`

enum GumboParseFlags { GUMBO_INSERTION_NORMAL = 0,
    GUMBO_INSERTION_BY_PARSER = 1 << 0, GUMBO_INSERTION_IMPLICIT_END_TAG
    = 1 << 1, GUMBO_INSERTION_IMPLIED = 1 << 3,
    GUMBO_INSERTION_CONVERTED_FROM_END_TAG = 1 << 4,
    GUMBO_INSERTION_FROM_ISINDEX = 1 << 5, GUMBO_INSERTION_FROM_IMAGE =
    1 << 6, GUMBO_INSERTION_RECONSTRUCTED_FORMATTING_ELEMENT = 1 << 7,
    GUMBO_INSERTION_ADOPTION_AGENCY_CLONED = 1 << 8,
    GUMBO_INSERTION_ADOPTION_AGENCY_MOVED = 1 << 9,
    GUMBO_INSERTION_FOSTER_PARENTED = 1 << 10 }

bit shifts, bit shifts, bit shifts. and not me noticing there's no 1 << 2 in there 🙈 — the list just goes 1 << 1 then straight to 1 << 3, and we are reporting it exactly as written, no editing, no inventing. periodt. 💅

🔥 Functions

every function in the header, listed exactly, no cap:

bool gumbo_string_equals (const GumboStringPiece *str1, const GumboStringPiece *str2)
bool gumbo_string_equals_ignore_case (const GumboStringPiece *str1, const GumboStringPiece *str2)
int gumbo_vector_index_of (GumboVector *vector, const void *element)
const char * gumbo_normalized_tagname (GumboTag tag)
void gumbo_tag_from_original_text (GumboStringPiece *text)
const char * gumbo_normalize_svg_tagname (const GumboStringPiece *tagname)
GumboTag gumbo_tag_enum (const char *tagname)
GumboTag gumbo_tagn_enum (const char *tagname, unsigned int length)
GumboAttribute * gumbo_get_attribute (const GumboVector *attrs, const char *name)
GumboOutput * gumbo_parse (const char *buffer)
GumboOutput * gumbo_parse_with_options (const GumboOptions *options, const char *buffer, size_t buffer_length)
void gumbo_destroy_output (const GumboOptions *options, GumboOutput *output)

⭐ Variables

the pre-made, ready-to-go constants. they're giving "already prepared for you, bestie":

const GumboSourcePosition kGumboEmptySourcePosition
const GumboStringPiece kGumboEmptyString
const GumboVector kGumboEmptyVector
const GumboOptions kGumboDefaultOptions

🧚 Typedef Documentation 🧚

`typedef void ( GumboAllocatorFunction) (void *userdata, size_t size)`

so this is the type for an allocator function. 🛠️ it takes the 'userdata' member of the GumboParser struct as its first argument.

the semantics should be the same as malloc, meaning: return a block of size_t bytes on success, or NULL on failure. and allocating a block of 0 bytes behaves as per malloc.

lowkey important: same rules as malloc, so don't go making up your own rules and then acting surprised. 🫶

`typedef void(* GumboDeallocatorFunction) (void userdata, void ptr)`

and this one is the type for a deallocator function. it takes the 'userdata' member of the GumboParser struct as its first argument. that's the whole deal. clean, simple, iconic. ✨

okay and that's where part 1 wraps up — there's MORE coming, bestie, so don't go anywhere, the struct docs are literally right there waiting for you 💖

✨ ENUMERATION TYPE DOCUMENTATION 🎀

`enum GumboTag`

okay so this is the enum for every single tag defined in the HTML5 standard, and the constants correspond to the tag names themselves, fr fr. here's the tea tho: enum constants only exist for tags that actually appear in the spec itself (or for tags with special handling in the SVG and MathML namespaces). anything else? it shows up as GUMBO_TAG_UNKNOWN, and you gotta grab the real tag name through original_tag. 💅

ngl it's mostly a convenience thing for us API girlies — so clients of this library don't have to do a whole strcasecmp just to find the normalized tag name. it's also lowkey an efficiency slay, because the parser gets to work with enums instead of strings. iconic behavior, honestly. ✨

`enum GumboAttributeNamespaceEnum`

attribute namespaces, bestie. HTML has special handling for the XLink, XML, and XMLNS namespaces on attributes, and everything else goes in the generic "NONE" namespace. that's it, that's the whole vibe. 🎀

`enum GumboNodeType`

this one denotes the type of node — it's literally what determines the type of the node.v union. so like, the main character energy of the whole tree. 🦋

Enumerator

GUMBO_NODE_DOCUMENT — document node. v will be a GumboDocument.
GUMBO_NODE_ELEMENT — element node. v will be a GumboElement.
GUMBO_NODE_TEXT — text node. v will be a GumboText.
GUMBO_NODE_CDATA — CDATA node. v will be a GumboText.
GUMBO_NODE_COMMENT — comment node. v will be a GumboText, excluding the comment delimiters (so no  crumbs, we keep it clean).
GUMBO_NODE_WHITESPACE — text node where all the contents is whitespace. v will be a GumboText.
GUMBO_NODE_TEMPLATE — template node. now this one is separate from GUMBO_NODE_ELEMENT for a reason: lots of client libraries are gonna want to ignore the contents of template nodes, just like the spec suggests. recursing on GUMBO_NODE_ELEMENT will do the right thing here, but if you're a client that does want the template contents, you also gotta check for GUMBO_NODE_TEMPLATE. v will be a GumboElement.

`enum GumboQuirksModeEnum`

the whole documentation for this one is a link, no cap:

http://www.whatwg.org/specs/web-apps/current-work/complete/dom.html#quirks-mode

that's it. she said read the spec. 💀

`enum GumboNamespaceEnum`

namespaces!! and here's the plot twist: unlike in X(HT)ML, namespaces in HTML5 are not denoted by a prefix. instead, anything inside an <svg> tag lives in the SVG namespace, anything inside the <math> tag lives in the MathML namespace, and literally everything else is chillin' in the HTML namespace. no other namespaces are supported, which is exactly why this can be an enum only. simple, effective, ate. 🔥

`enum GumboParseFlags`

parse flags! so we track the reasons the parser inserted nodes and stash them in a bitvector in the node itself. why? so client code can optimize out nodes that are implied by the HTML structure of the document, or flag constructs that a style guide might not allow, or just track how much incorrect/tricky HTML code is out there in the wild. very main character of the parser honestly. 👑

Enumerator

GUMBO_INSERTION_NORMAL — a normal node: both the start and end tags appear in the source, and nothing has been reparented. the well-adjusted one. 🌸
GUMBO_INSERTION_BY_PARSER — a node the parser inserted to fulfill some implicit insertion rule. this is usually set in addition to some other flag giving a more specific insertion reason; it's the generic catch-all term meaning "The start tag forthis node did not appear in the document source". (yes the forthis is in the source. we keep it. no we will not be fixing it. 💀)
GUMBO_INSERTION_IMPLICIT_END_TAG — a flag saying the end tag for this node did not appear in the document source. but WAIT, plot twist: in some cases you can still have parser-inserted nodes with an explicit end tag. for example, "Text</html>" has GUMBO_INSERTED_BY_PARSER set on the <html> node, but GUMBO_INSERTED_END_TAG_IMPLICITLY is unset, because the </html> tag actually exists. this flag gets set only if the end tag is completely missing — in some cases the end tag might just be misplaced (eg. a </body> tag with text afterwards), which leaves this flag unset and makes clients inspect the parse errors for that case. so annoying but that's the rules. 🫶
GUMBO_INSERTION_IMPLIED — a flag for nodes inserted because their presence is implied by other tags, eg. <html>, <head>, <body>, , etc. (there's a lil gap in the source text right there between the commas — the tag that should be there got eaten by the doc generator, and we're not out here inventing tags 🙈).
GUMBO_INSERTION_CONVERTED_FROM_END_TAG — a flag for nodes converted from their end tag equivalents. for example:

when no paragraph is open implies that the parser should create a tag and immediately close it, while means the same thing as .

(again: those blanks are blanks in the original, the tag names got stripped out somewhere in the doc pipeline. bestie we report what's on the page. 🧚)

GUMBO_INSERTION_FROM_ISINDEX — a flag for nodes converted from the parse of an <isindex> tag. throwback tag, honestly.
GUMBO_INSERTION_FROM_IMAGE — a flag for <image> tags that are rewritten as . (and yes, another lil blank where the replacement tag should be. the doc generator really said "mystery flavor" on that one. 😭)
GUMBO_INSERTION_RECONSTRUCTED_FORMATTING_ELEMENT — a flag for nodes cloned as a result of the reconstruction of active formatting elements. important: this is set only on the clone — the initial portion of the formatting run is a NORMAL node with an IMPLICIT_END_TAG. iykyk. 💜
GUMBO_INSERTION_ADOPTION_AGENCY_CLONED — a flag for nodes cloned by the adoption agency algorithm. yes that's the real name, yes it's dramatic, yes it's iconic.
GUMBO_INSERTION_ADOPTION_AGENCY_MOVED — a flag for nodes moved by the adoption agency algorithm. one got cloned, one got moved, they're different besties.
GUMBO_INSERTION_FOSTER_PARENTED — a flag for nodes that have been foster-parented out of a table (or should've been foster-parented, if verbatim mode is set). go little guy, go live with a new family. 🦋

💖 FUNCTION DOCUMENTATION 💖

bool gumbo_string_equals(const GumboStringPiece *str1, const GumboStringPiece *str2) — compares two GumboStringPieces and returns true if they're equal, false otherwise. simple. clean. slay.
bool gumbo_string_equals_ignore_case(const GumboStringPiece *str1, const GumboStringPiece *str2) — same thing but it ignores case: true if they're equal, false otherwise. the chill version of the one above.
int gumbo_vector_index_of(GumboVector *vector, const void *element) — returns the first index at which an element appears in this vector (tested by pointer equality, so it's the exact pointer, not a deep comparison bestie), or -1 if it never does. not me getting ghosted by -1. 💀
const char * gumbo_normalized_tagname(GumboTag tag) — returns the normalized tag name for a GumboTag enum. usually all-lowercased, except for foreign content — those get to keep their vibe. the return value is static data owned by the library, so don't you dare free it. 🎀
void gumbo_tag_from_original_text(GumboStringPiece *text) — extracts the tag name from the original_text field of an element or token by stripping off the </> characters and the attributes, and adjusting the passed-in GumboStringPiece appropriately. the tag name comes out in the original case and shares a buffer with the original text, which simplifies memory management (very thoughtful of her honestly). behavior is undefined if you pass in a string-piece that doesn't represent an HTML tag (<tagname> or </tagname>) — so don't do that, bestie, it's giving chaos. and if the string piece is completely empty (a NULL data pointer), then this function exits successfully as a no-op. cute.
const char * gumbo_normalize_svg_tagname(const GumboStringPiece *tagname) — fixes the case of SVG elements that aren't all lowercase:

http://www.whatwg.org/specs/web-apps/current-work/multipage/tree-construction.html#parsing-main-inforeign

and ngl, this is not done at parse time because there's literally nowhere to store a mutated tag name. tag_name is an enum (which will be TAG_UNKNOWN for most SVG tags without special handling), while original_tag_name is just a pointer into the original buffer. so instead, we hand you this helper function and you can rename SVG tags as appropriate yourself. returns the case-normalized SVG tagname if a replacement is found, or NULL if no normalization is called for. the return value is static data and owned by the library. 🫶

GumboTag gumbo_tag_enum(const char *tagname) — converts a tag name string (which may be in upper or mixed case) to a tag enum. the tag version expects tagname to be NULL-terminated. periodt.
GumboAttribute * gumbo_get_attribute(const GumboVector *attrs, const char *name) — give it a vector of GumboAttributes and it looks up the one with the specified name and returns it, or NULL if no such attribute exists. it uses a case-insensitive match, because HTML is case-insensitive. matching energy. ✨
GumboOutput * gumbo_parse(const char *buffer) — parses a buffer of UTF8 text into a GumboNode parse tree. ⚠️ important: the buffer must live at least as long as the parse tree, because some fields (eg. original_text) point directly into that original buffer. do not free it early, i am begging you.

also: this doesn't support buffers longer than 4 gigabytes. so if you were planning a casual 5GB HTML file... no. 🌸

GumboOutput * gumbo_parse_with_options(const GumboOptions *options, const char *buffer, size_t buffer_length) — the extended version of gumbo_parse that takes an explicit options structure, buffer, and length. the deluxe edition. 👑
void gumbo_destroy_output(const GumboOptions *options, GumboOutput *output) — releases the memory used for the parse tree & parse errors. clean up after yourself bestie, we love a tidy queen. 🎀

🌈 VARIABLE DOCUMENTATION 🌈

const GumboSourcePosition kGumboEmptySourcePosition [extern] — a SourcePosition used for elements that have no source position, i.e. parser-inserted elements. they didn't come from anywhere in the file so we give them the empty one. 🦋
const GumboStringPiece kGumboEmptyString [extern] — a constant to represent a 0-length null string. literally the empty girlie.
const GumboVector kGumboEmptyVector [extern] — an empty GumboVector: 0-length, 0-capacity. she contains nothing and she's at peace with that. 💜
const GumboOptions kGumboDefaultOptions [extern] — the default options struct! use this with gumbo_parse_with_options. the go-to, the standard, the main character of the options world. ⭐

✍️ AUTHOR ✍️

Generated automatically by Doxygen for Gumbo from the source code. (so if the vibes are immaculate, thank Doxygen. if there's a weird blank where a tag should be... also thank Doxygen. 🙈)

and that's a wrap on gumbo.h(3), bestie!! this was Version 0.12.1, dated Fri Sep 19 2025 00:00:00 — straight from the source code, no cap. go parse something gorgeous. 💖✨🎀🦋🌸

📦 where this page comes from

fedora 43: gumbo-parser-devel 1:0.12.1-7.fc43 · Apache-2.0
fedora 43: gumbo-parser-devel 1:0.12.1-7.fc43 · Apache-2.0
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms

gumbo.h(3)

✨ gumbo.h ✨

🎀 NAME 🎀

🌸 SYNOPSIS 🌸

💜 Data Structures

🦋 Typedefs

🌈 Enumerations

enum GumboTag

enum GumboAttributeNamespaceEnum

enum GumboNodeType

enum GumboQuirksModeEnum

enum GumboNamespaceEnum

enum GumboParseFlags

🔥 Functions

⭐ Variables

🧚 Typedef Documentation 🧚

typedef void *(* GumboAllocatorFunction) (void *userdata, size_t size)

typedef void(* GumboDeallocatorFunction) (void *userdata, void *ptr)

✨ ENUMERATION TYPE DOCUMENTATION 🎀

enum GumboTag

enum GumboAttributeNamespaceEnum

enum GumboNodeType

Enumerator

enum GumboQuirksModeEnum

enum GumboNamespaceEnum

enum GumboParseFlags

Enumerator

💖 FUNCTION DOCUMENTATION 💖

🌈 VARIABLE DOCUMENTATION 🌈

✍️ AUTHOR ✍️

✨ `gumbo.h` ✨

`enum GumboTag`

`enum GumboAttributeNamespaceEnum`

`enum GumboNodeType`

`enum GumboQuirksModeEnum`

`enum GumboNamespaceEnum`

`enum GumboParseFlags`

`typedef void ( GumboAllocatorFunction) (void *userdata, size_t size)`

`typedef void(* GumboDeallocatorFunction) (void userdata, void ptr)`

`enum GumboTag`

`enum GumboAttributeNamespaceEnum`

`enum GumboNodeType`

`enum GumboQuirksModeEnum`

`enum GumboNamespaceEnum`

`enum GumboParseFlags`