libmaxminddb(3)

📦

version 1.14.1 · 9 versions

1.14.1 · arch rolling, fedora 43, fedora 44 (latest)
1.5.2 · centos-stream 9
1.9.1 · alpine 3.22, alpine 3.23, centos-stream 10
1.5.2 · ubuntu jammy
1.12.2 · fedora 43, opensuse-leap 16.0
1.9.1 · ubuntu noble
1.13.3 · alpine 3.24, fedora 44, nixos 26.05, nixpkgs unstable, ubuntu stonking
1.7.1 · debian bookworm
1.12.2 · debian trixie, ubuntu questing, ubuntu resolute

💖 libmaxminddb(3) 💖

okay so bestie, welcome to the Library Functions Manual entry for libmaxminddb(3) — yes the whole thing is literally a library for working with MaxMind DB files, and we're gonna go through it together, no skipping, no skimming, no "tl;dr" (i would never do that to you).

✨ NAME ✨

libmaxminddb — a library for working with MaxMind DB files 🗂️✨

🌸 SYNOPSIS 🌸

#include <maxminddb.h>

int MMDB_open(
    const char *const filename,
    uint32_t flags,
    MMDB_s *const mmdb);
void MMDB_close(MMDB_s *const mmdb);

MMDB_lookup_result_s MMDB_lookup_string(
    const MMDB_s *const mmdb,
    const char *const ipstr,
    int *const gai_error,
    int *const mmdb_error);
MMDB_lookup_result_s MMDB_lookup_sockaddr(
    const MMDB_s *const mmdb,
    const struct sockaddr *const
    sockaddr,
    int *const mmdb_error);

int MMDB_get_value(
    MMDB_entry_s *const start,
    MMDB_entry_data_s *const entry_data,
    ...);
int MMDB_vget_value(
    MMDB_entry_s *const start,
    MMDB_entry_data_s *const entry_data,
    va_list va_path);
int MMDB_aget_value(
    MMDB_entry_s *const start,
    MMDB_entry_data_s *const entry_data,
    const char *const *const path);

int MMDB_get_entry_data_list(
    MMDB_entry_s *start,
    MMDB_entry_data_list_s **const entry_data_list);
void MMDB_free_entry_data_list(
    MMDB_entry_data_list_s *const entry_data_list);
int MMDB_get_metadata_as_entry_data_list(
    const MMDB_s *const mmdb,
    MMDB_entry_data_list_s **const entry_data_list);
int MMDB_dump_entry_data_list(
    FILE *const stream,
    MMDB_entry_data_list_s *const entry_data_list,
    int indent);

int MMDB_read_node(
    const MMDB_s *const mmdb,
    uint32_t node_number,
    MMDB_search_node_s *const node);

const char *MMDB_lib_version(void);
const char *MMDB_strerror(int error_code);

typedef struct MMDB_lookup_result_s {
    bool found_entry;
    MMDB_entry_s entry;
    uint16_t netmask;
} MMDB_lookup_result_s;

typedef struct MMDB_entry_data_s {
    bool has_data;
    union {
        uint32_t pointer;
        const char *utf8_string;
        double double_value;
        const uint8_t *bytes;
        uint16_t uint16;
        uint32_t uint32;
        int32_t int32;
        uint64_t uint64;
        {mmdb_uint128_t or uint8_t[16]} uint128;
        bool boolean;
        float float_value;
    };
    ...
    uint32_t data_size;
    uint32_t type;
} MMDB_entry_data_s;

typedef struct MMDB_entry_data_list_s {
    MMDB_entry_data_s entry_data;
    struct MMDB_entry_data_list_s *next;
} MMDB_entry_data_list_s;

like. look at all those structs. gorgeous. stunning. we love a well-organized header file 💅

🌈 DESCRIPTION 🌈

The libmaxminddb library provides functions for working with MaxMind DB files. 🫶 (if you wanna go read the whole MaxMind DB format specification, it's literally right here: https://maxmind.github.io/MaxMind-DB/ — go, be free, i'll wait.)

The database and results are all represented by different data structures, so like… keep track of which one you're holding, bestie. Databases are opened by calling MMDB_open().

You can look up IP addresses as a string with MMDB_lookup_string() or as a pointer to a sockaddr structure with MMDB_lookup_sockaddr(). pick your fighter, both are valid. ✨

If the lookup finds the IP address in the database, it returns a MMDB_lookup_result_s structure. And if that structure indicates that the database has data for the IP, there are a number of functions that can be used to fetch that data. These include MMDB_get_value() and MMDB_get_entry_data_list(). See the function documentation below for more details — yes, below below, we're getting there, patience my love 😌

When you are done with the database handle you should call MMDB_close(). please do not forget this one, it's giving cleanup era and honestly it's the polite thing to do.

And the little naming convention that keeps us all sane: all publicly visible functions, structures, and macros begin with "MMDB_". every single one. no stragglers. periodt. 👑

✨ DATA STRUCTURES ✨

Okay bestie, so every single data structure this library exports in the maxminddb.h header is typedef'd like typedef struct foo_s { ... } foo_s so you can just say the cute short name without dragging struct around everywhere. Obsessed. 💅

This library provides the following data structures:

🌸 MMDB_s 🌸

This is the handle for a MaxMind DB file. We only document some of this structure's fields intended for public use. All the other fields are subject to change and are intended only for internal use — so don't get attached to them, bestie.

typedef struct MMDB_s {
    uint32_t flags;
    const char *filename;
    ...
    MMDB_metadata_s metadata;
} MMDB_s;

uint32_t flags — the flags this database was opened with. See the MMDB_open() documentation for more details.
const char *filename — the name of the file which was opened, as passed to MMDB_open().
MMDB_metadata_s metadata — the metadata for the database.

🌈 MMDB_metadata_s and MMDB_description_s 🌈

This structure can be retrieved from the MMDB_s structure. It contains the metadata read from the database file. Note that you may find it more convenient to access this metadata by calling MMDB_get_metadata_as_entry_data_list() instead. (Lowkey a glow-up move, fr fr.)

typedef struct MMDB_metadata_s {
    uint32_t node_count;
    uint16_t record_size;
    uint16_t ip_version;
    const char *database_type;
    struct {
        size_t count;
        const char **names;
    } languages;
    uint16_t binary_format_major_version;
    uint16_t binary_format_minor_version;
    uint64_t build_epoch;
    struct {
        size_t count;
        MMDB_description_s **descriptions;
    } description;
} MMDB_metadata_s;

typedef struct MMDB_description_s {
    const char *language;
    const char *description;
} MMDB_description_s;

These structures should be mostly self-explanatory. 💖

The ip_version member should always be 4 or 6. The binary_format_major_version should always be 2. Periodt.

There is no requirement that the database metadata include languages or descriptions, so the count for these parts of the metadata can be zero. All of the other MMDB_metadata_s fields should be populated.

🦋 MMDB_lookup_result_s 🦋

This structure is returned as the result of looking up an IP address.

typedef struct MMDB_lookup_result_s {
    bool found_entry;
    MMDB_entry_s entry;
    uint16_t netmask;
} MMDB_lookup_result_s;

If the found_entry member is false then the other members of this structure do not contain meaningful values. Always check that found_entry is true first. No cap. 🫶

The entry member is used to look up the data associated with the IP address.

The netmask member tells you what subnet the IP address belongs to in this database. For example, if you look up the address 1.1.1.1 in an IPv4 database and the returned netmask is 16, then the address is part of the 1.1.0.0/16 subnet. It's giving subnet realness.

If the database is an IPv6 database, the returned netmask is always an IPv6 prefix length (from 0-128), even if that database also contains IPv4 networks. If you look up an IPv4 address and would like to turn the netmask into an IPv4 netmask value, you can simply subtract 96 from the value. Math is math, bestie. ✨

🎀 MMDB_entry_s 🎀

You don't really need to dig around in this structure. You'll get this from a MMDB_lookup_result_s structure and pass it to various functions. It's basically a lil messenger. 💌

💜 MMDB_entry_data_s 💜

This structure is used to return a single data section entry for an IP. These entries can in turn point to other entries, as is the case for things like maps and arrays. Some members of this structure are not documented as they are only for internal use. (Not me ignoring the private fields 💀)

typedef struct MMDB_entry_data_s {
    bool has_data;
    union {
        uint32_t pointer;
        const char *utf8_string;
        double double_value;
        const uint8_t *bytes;
        uint16_t uint16;
        uint32_t uint32;
        int32_t int32;
        uint64_t uint64;
        {mmdb_uint128_t or uint8_t[16]} uint128;
        bool boolean;
        float float_value;
    };
    ...
    uint32_t data_size;
    uint32_t type;
} MMDB_entry_data_s;

The has_data member is true if data was found for a given lookup. See MMDB_get_value() for more details. If this member is false then none of the other values in the structure are meaningful. So like, vibe check that first. 🙈

The union at the beginning of the structure defines the actual data. To determine which union member is populated you should look at the type member. The pointer member of the union should never be populated in any data returned by the API. Pointers should always be resolved internally. Don't touch that pointer, bestie, it's not for you. 🚫

The data_size member is only relevant for utf8_string and bytes data. utf8_string is not null terminated and data_size must be used to determine its length. This is the way. ✨

The type member can be compared to one of the MMDB_DATA_TYPE_* macros. When type is MMDB_DATA_TYPE_MAP or MMDB_DATA_TYPE_ARRAY, the entry represents a collection. To access individual items within the collection, use MMDB_get_value() with the appropriate lookup path from the original entry. To iterate over all items, use MMDB_get_entry_data_list().

🧚 128-bit Integers 🧚

The handling of uint128 data depends on how your platform supports 128-bit integers, if it does so at all. With GCC 4.4 and 4.5 we can write unsigned int __attribute__ ((__mode__ (TI))). With newer versions of GCC (4.6+) and clang (3.2+) we can simply write "unsigned __int128". (Compiler lore, iykyk. 💅)

In order to work around these differences, this library defines an mmdb_uint128_t type. This type is defined in the maxminddb.h header so you can use it in your own code.

With older compilers, we can't use an integer so we instead use a 16 byte array of uint8_t values. This is the raw data from the database.

This library provides a public macro MMDB_UINT128_IS_BYTE_ARRAY macro. If this is true (1), then uint128 values are returned as a byte array, if it is false then they are returned as a mmdb_uint128_t integer.

🌟 Data Type Macros 🌟

This library provides a macro for every data type defined by the MaxMind DB spec. So many icons. 👑

MMDB_DATA_TYPE_UTF8_STRING
MMDB_DATA_TYPE_DOUBLE
MMDB_DATA_TYPE_BYTES
MMDB_DATA_TYPE_UINT16
MMDB_DATA_TYPE_UINT32
MMDB_DATA_TYPE_MAP
MMDB_DATA_TYPE_INT32
MMDB_DATA_TYPE_UINT64
MMDB_DATA_TYPE_UINT128
MMDB_DATA_TYPE_ARRAY
MMDB_DATA_TYPE_BOOLEAN
MMDB_DATA_TYPE_FLOAT

There are also a few types that are for internal use only:

MMDB_DATA_TYPE_EXTENDED
MMDB_DATA_TYPE_POINTER
MMDB_DATA_TYPE_CONTAINER
MMDB_DATA_TYPE_END_MARKER

If you see one of these in returned data then something has gone very wrong. The database is damaged or was generated incorrectly or there is a bug in the libmaxminddb code. It's giving corrupted. 😭

🍓 Pointer Values and MMDB_close() 🍓

The utf8_string, bytes, and (maybe) the uint128 members of this structure are all pointers directly into the database's data section. This can either be a calloc'd or mmap'd block of memory. In either case, these pointers will become invalid after MMDB_close() is called. Poof, gone. 💨

If you need to refer to this data after that time you should copy the data with an appropriate function (strdup, memcpy, etc.). Save it for later, bestie.

🌈 MMDB_entry_data_list_s 🌈

This structure encapsulates a linked list of MMDB_entry_data_s structures.

typedef struct MMDB_entry_data_list_s {
    MMDB_entry_data_s entry_data;
    struct MMDB_entry_data_list_s *next;
} MMDB_entry_data_list_s;

This structure lets you look at entire map or array data entry by iterating over the linked list. Slay. ✨

👑 MMDB_search_node_s 👑

This structure encapsulates the two records in a search node. This is really only useful if you want to write code that iterates over the entire search tree as opposed to looking up a specific IP address. Main character energy for the tree-walkers. 🌳

typedef struct MMDB_search_node_s {
    uint64_t left_record;
    uint64_t right_record;
    uint8_t left_record_type;
    uint8_t right_record_type;
    MMDB_entry_s left_record_entry;
    MMDB_entry_s right_record_entry;
} MMDB_search_node_s;

The two record types will take one of the following values:

MMDB_RECORD_TYPE_SEARCH_NODE — The record points to the next search node.
MMDB_RECORD_TYPE_EMPTY — The record is a placeholder that indicates there is no data for the IP address. The search should end here.
MMDB_RECORD_TYPE_DATA — The record is for data in the data section of the database. Use the entry for the record when looking up the data for the record.
MMDB_RECORD_TYPE_INVALID — The record is invalid. Either an invalid node was looked up or the database is corrupt.

The MMDB_entry_s for the record is only valid if the type is MMDB_RECORD_TYPE_DATA. Attempts to use an entry for other record types will result in an error or invalid data. So like, read the type first, bestie. 🫶

✨ STATUS CODES ✨

So like, this library hands you (or fills in) status codes for a bunch of functions, bestie. Here's the whole roster:

MMDB_SUCCESS — everything worked 💖 literally the dream.
MMDB_FILE_OPEN_ERROR — it tried to open the MaxMind DB file and… nope, error. 🙈
MMDB_IO_ERROR — an IO operation flopped. Check errno for the deets.
MMDB_CORRUPT_SEARCH_TREE_ERROR — looking up an IP in the search tree gave back an impossible result. Either the database is damaged, was generated wrong, or there's a bug in the libmaxminddb code itself. 💀
MMDB_INVALID_METADATA_ERROR — something in the database is wrong. This covers missing metadata keys and impossible values (like an ip_version of 7 😭).
MMDB_UNKNOWN_DATABASE_FORMAT_ERROR — the metadata says its major version isn't 2. This library can only handle major version 2, periodt.
MMDB_OUT_OF_MEMORY_ERROR — a memory allocation call (malloc, etc.) failed. 🫠
MMDB_INVALID_DATA_ERROR — an entry in the data section has invalid data. Example: a uint16 field claiming to be more than 2 bytes long. The database is probably damaged or was generated incorrectly.
MMDB_INVALID_LOOKUP_PATH_ERROR — the lookup path you passed to MMDB_get_value, MMDB_vget_value, or MMDB_aget_value contains an array offset bigger than LONGMAX or smaller than LONGMIN.
MMDB_LOOKUP_PATH_DOES_NOT_MATCH_DATA_ERROR — the lookup path you passed to MMDB_get_value, MMDB_vget_value, or MMDB_aget_value doesn't match the data structure for the entry. There are a bunch of reasons this can happen: the path could include a key that's not in a map, or an array index bigger than the array or smaller than the minimum offset from the end of the array. It can also happen when the path expects to find a map or array where none exist.
MMDB_INVALID_NETWORK_ADDRESS_ERROR — MMDB_lookup_sockaddr() got a sockaddr whose family is neither AF_INET nor AF_INET6. not the vibe.
MMDB_DECODER_LIMIT_ERROR — decoding a data structure would blow past the configured nesting depth, value-count, or string/bytes payload limit. The structure may still be valid MaxMind DB data, for the record.

All status codes should be treated as int values. no cap.

MMDB_strerror()

const char *MMDB_strerror(int error_code)

This one takes a status code and returns an English string explaining what that status actually means. so you're never left guessing. ✨

🎀 FUNCTIONS 🎀

Here's every exported function this library serves up, bestie:

MMDB_open()

int MMDB_open(
    const char *const filename,
    uint32_t flags,
    MMDB_s *const mmdb);

This opens a handle to a MaxMind DB file. Its return value is a status code as defined above. Always check this call's return value. like, always always.

MMDB_s mmdb;
int status =
    MMDB_open("/path/to/file.mmdb", MMDB_MODE_MMAP, &mmdb);
if (MMDB_SUCCESS != status) { ... }
...
MMDB_close(&mmdb);

filename must be encoded as UTF-8 on Windows. 🪟

The MMDB_s structure you pass in can live on the stack or be allocated from the heap. BUT — if the open is successful it'll contain heap-allocated data, so you need to close it with MMDB_close(). If the status returned isn't MMDB_SUCCESS then this library makes sure all the allocated memory gets freed before returning. considerate king behavior. 👑

The flags currently provided are:

MMDB_MODE_MMAP — open the database with mmap().

Passing in other values for flags may yield unpredictable results. In the future they might add extra flags you can bitwise-or together with the mode, plus more modes. iykyk.

You can also pass 0 as the flags value, in which case the database opens with the default flags. However — these defaults may change in future releases. The current default is MMDB_MODE_MMAP.

If metadata processing exceeds one of the decoder resource limits described under MMDB_get_entry_data_list(), this function returns MMDB_INVALID_METADATA_ERROR.

MMDB_close()

void MMDB_close(MMDB_s *const mmdb);

This frees any allocated or mmap'd memory held by the MMDB_s structure. It does not free the memory allocated for the structure itself! So if you allocated the structure from the heap, you're the one responsible for freeing it. 🙈 don't forget, bestie.

MMDB_lookup_string()

MMDB_lookup_result_s MMDB_lookup_string(
    const MMDB_s *const mmdb,
    const char *const ipstr,
    int *const gai_error,
    int *const mmdb_error);

This looks up an IP address passed in as a null-terminated string. Internally it calls getaddrinfo() to resolve the address into binary form. Then it calls MMDB_lookup_sockaddr() to look the address up in the database. If you've already resolved an address you can call MMDB_lookup_sockaddr() directly instead of resolving it twice. efficiency queen 💅

int gai_error, mmdb_error;
MMDB_lookup_result_s result =
    MMDB_lookup_string(&mmdb, "1.2.3.4", &gai_error, &mmdb_error);
if (0 != gai_error) { ... }
if (MMDB_SUCCESS != mmdb_error) { ... }

if (result.found_entry) { ... }

This function always returns an MMDB_lookup_result_s structure, but you should also check the gai_error and mmdb_error parameters. If either one says there's an error, then the returned structure is meaningless. 🫠

When *gai_error is non-zero (i.e., getaddrinfo() failed), *mmdb_error is set to MMDB_SUCCESS because no database error occurred. You should always check *gai_error first.

If no error occurred, you still need to make sure the found_entry member in the returned result is true. If it's not, that means the IP address doesn't have an entry in the database.

This function will work with IPv4 addresses even when the database contains data for both IPv4 and IPv6 addresses. The IPv4 address gets looked up as '::xxx.xxx.xxx.xxx' rather than being remapped to the ::ffff:xxx.xxx.xxx.xxx block allocated for IPv4-mapped IPv6 addresses. she's specific like that ✨

If you pass an IPv6 address to a database with only IPv4 data, then the found_entry member will be false — but the mmdb_error status will still be MMDB_SUCCESS.

MMDB_lookup_sockaddr()

MMDB_lookup_result_s MMDB_lookup_sockaddr(
    const MMDB_s *const mmdb,
    const struct sockaddr *const sockaddr,
    int *const mmdb_error);

This looks up an IP address that's already been resolved by getaddrinfo(). The sockaddr you pass in must be an AF_INET or AF_INET6 address.

Other than not calling getaddrinfo() itself, this function is identical to MMDB_lookup_string(). twins fr fr.

int mmdb_error;
MMDB_lookup_result_s result =
    MMDB_lookup_sockaddr(&mmdb, address->ai_addr, &mmdb_error);
if (MMDB_SUCCESS != mmdb_error) { ... }

if (result.found_entry) { ... }

Data Lookup Functions

There are three functions for looking up data associated with an IP address:

int MMDB_get_value(
    MMDB_entry_s *const start,
    MMDB_entry_data_s *const entry_data,
    ...);
int MMDB_vget_value(
    MMDB_entry_s *const start,
    MMDB_entry_data_s *const entry_data,
    va_list va_path);
int MMDB_aget_value(
    MMDB_entry_s *const start,
    MMDB_entry_data_s *const entry_data,
    const char *const *const path);

These three allow three slightly different calling styles, but they all do the exact same thing. same energy, different font. 💖

The first parameter is a pointer to an MMDB_entry_s struct. In most cases this'll be a pointer to the entry field of the MMDB_lookup_result_s value returned by MMDB_lookup_string() or MMDB_lookup_sockaddr().

The second parameter is a reference to an MMDB_entry_data_s structure. This gets populated with the data being looked up, if any is found. If nothing's found, then the has_data member of this structure will be false. If has_data is true, then you can look at the type member. 👀

The final parameter is a lookup path. The path is a set of strings representing either map keys (e.g, "city") or array indexes (e.g., "0", "1", "-1") to use in the lookup.

Negative array indexes get treated as an offset from the end of the array. For instance, "-1" refers to the last element of the array. 🎀

The lookup path lets you navigate a complex data structure. For example, given this data:

{
    "names": {
        "en": "Germany",
        "de": "Deutschland"
    },
    "cities": [ "Berlin", "Frankfurt" ]
}

We could look up the English name with this code:

MMDB_lookup_result_s result =
    MMDB_lookup_sockaddr(&mmdb, address->ai_addr, &mmdb_error);
MMDB_entry_data_s entry_data;
int status =
    MMDB_get_value(&result.entry, &entry_data,
                   "names", "en", NULL);
if (MMDB_SUCCESS != status) { ... }
if (entry_data.has_data) { ... }

If we wanted to find the first city, the lookup path would be "cities", "0". If you don't provide a lookup path at all, you'll get the entry corresponding to the top level map. The lookup path must always end with NULL, no matter which function you call.

The MMDB_get_value function takes a variable number of arguments. All the arguments after the MMDB_entry_data_s * structure pointer are the lookup path. The last argument must be NULL.

The MMDB_vget_value function accepts a va_list as the lookup path. The last element retrieved by va_arg() must be NULL.

Finally, the MMDB_aget_value accepts an array of strings as the lookup path. The last member of this array must be NULL.

To look up multiple keys within the same map, use the full lookup path for each key. For example, to get both the en and de values from the names map, make separate calls with "names", "en", NULL and "names", "de", NULL. If you need all the data from a complex structure rather than specific values, MMDB_get_entry_data_list() is more efficient than making a ton of individual calls. 💡

For each of the three functions, the return value is a status code as defined above.

MMDB_get_entry_data_list()

int MMDB_get_entry_data_list(
    MMDB_entry_s *start,
    MMDB_entry_data_list_s **const entry_data_list);

The start parameter is a pointer to an MMDB_entry_s struct. In most cases this'll be a pointer to the entry field of the MMDB_lookup_result_s value returned by MMDB_lookup_string() or MMDB_lookup_sockaddr().

This function lets you grab all the data for a complex data structure at once, instead of looking up each piece with repeated calls to MMDB_get_value(). one call, whole vibe. ✨

okay bestie, so a crafted database can make a full decode expensive, which is giving main character energy but in a bad way 😭. So this function bounds the work and the caller-visible payload. Each call decodes at most 65,536 list values and 2 MiB of UTF-8 string and bytes payload. A structure exactly at either limit is accepted. The recursive-decoder depth limit of 512 also applies. Exceeding any limit returns MMDB_DECODER_LIMIT_ERROR and sets entry_data_list to NULL. 💅

The limits are per call and can be changed when rebuilding libmaxminddb by defining the positive integer macros MAXIMUM_DATA_STRUCTURE_DEPTH, MAXIMUM_DATA_STRUCTURE_VALUES, and MAXIMUM_DATA_STRUCTURE_BYTES. For example, pass -DMAXIMUM_DATA_STRUCTURE_BYTES=3145728 in the library's compiler flags. Use an integer constant rather than an expression. A bare shift such as 1<<31 is evaluated as int and does not express a 2 GiB limit. The depth value must fit in int, the value count in size_t, and the byte count in uint64_t. This requires rebuilding the library itself. Defining a macro only while building an application does not change a packaged shared library. periodt ✨

MMDB_get_value(), MMDB_vget_value(), and MMDB_aget_value() do not expand a complete structure and therefore do not charge the value-count or payload budgets. When they skip an unselected map or array, the depth limit applies to that subtree and may return MMDB_DECODER_LIMIT_ERROR; it does not bound the selected lookup path itself. Applications that cannot rebuild a packaged library can use those functions to retrieve a specific field from an otherwise over-limit record. iykyk 🫶

MMDB_lookup_result_s result =
    MMDB_lookup_sockaddr(&mmdb, address->ai_addr, &mmdb_error);
MMDB_entry_data_list_s *entry_data_list, *first;
int status =
    MMDB_get_entry_data_list(&result.entry, &entry_data_list);
if (MMDB_SUCCESS != status) { ... }
// save this so we can free this data later
first = entry_data_list;

while (1) {
    MMDB_entry_data_list_s *next = entry_data_list = entry_data_list->next;
    if (NULL == next) {
        break;
    }

    switch (next->entry_data.type) {
        case MMDB_DATA_TYPE_MAP: { ... }
        case MMDB_DATA_TYPE_UTF8_STRING: { ... }
        ...
    }

}

MMDB_free_entry_data_list(first);

It's up to you to interpret the entry_data_list data structure. The list is linked in a depth-first traversal. Let's use this structure as an example:

{
    "names": {
        "en": "Germany",
        "de": "Deutschland"
    },
    "cities": [ "Berlin", "Frankfurt" ]
}

The list will consist of the following items:

MAP - top level map
UTF8_STRING - "names" key
MAP - map for "names" key
UTF8_STRING - "en" key
UTF8_STRING - value for "en" key
UTF8_STRING - "de" key
UTF8_STRING - value for "de" key
UTF8_STRING - "cities" key
ARRAY - value for "cities" key
UTF8_STRING - array[0]
UTF8_STRING - array[1]

The return value of the function is a status code as defined above. 💖

MMDB_free_entry_data_list() 🎀

void MMDB_free_entry_data_list(
    MMDB_entry_data_list_s *const entry_data_list);

The MMDB_get_entry_data_list() and MMDB_get_metadata_as_entry_data_list() functions will allocate the linked list structure from the heap. Call this function to free the MMDB_entry_data_list_s structure. no leaks bestie 🧚

MMDB_get_metadata_as_entry_data_list() 🌸

int MMDB_get_metadata_as_entry_data_list(
    const MMDB_s *const mmdb,
    MMDB_entry_data_list_s **const entry_data_list);

This function allows you to retrieve the database metadata as a linked list of MMDB_entry_data_list_s structures. This can be a more convenient way to deal with the metadata than using the metadata structure directly. It uses the same per-call limits as MMDB_get_entry_data_list() and returns MMDB_DECODER_LIMIT_ERROR if the complete metadata list exceeds any of them. obsessed with a tidy API 💜

MMDB_entry_data_list_s *entry_data_list, *first;
int status =
    MMDB_get_metadata_as_entry_data_list(&mmdb, &entry_data_list);
if (MMDB_SUCCESS != status) { ... }
first = entry_data_list;
... // do something with the data
MMDB_free_entry_data_list(first);

The return value of the function is a status code as defined above. ✨

MMDB_dump_entry_data_list() 🦋

int MMDB_dump_entry_data_list(
    FILE *const stream,
    MMDB_entry_data_list_s *const entry_data_list,
    int indent);

This function takes a linked list of MMDB_entry_data_list_s structures and stringifies it to the given stream. The indent parameter is the starting indent level for the generated output. It is incremented for nested data structures (maps, array, etc.). pretty printing is self-care 💅

The stream must be a file handle (stdout, etc). If your platform provides something like the GNU open_memstream() you can use that to capture the output as a string.

The output is formatted in a JSON-ish fashion, but values are marked with their data type (except for maps and arrays which are shown with "{}" and "[]" respectively). iykyk

The specific output format may change in future releases, so you should not rely on the specific formatting produced by this function. It is intended to be used to show data to users in a readable way and for debugging purposes. don't hardcode this output, bestie 😭

The return value of the function is a status code as defined above. 🫶

MMDB_read_node() 🌈

int MMDB_read_node(
    const MMDB_s *const mmdb,
    uint32_t node_number,
    MMDB_search_node_s *const node);

This reads a specific node in the search tree. The third argument is a reference to an MMDB_search_node_s structure that will be populated by this function. main character node energy 👑

The return value is a status code. If you pass a node_number that is greater than or equal to the number of nodes in the database, this function will return MMDB_INVALID_NODE_NUMBER_ERROR. If the node's child records are invalid or point outside the search tree or data section, it will return MMDB_CORRUPT_SEARCH_TREE_ERROR. Otherwise it will return MMDB_SUCCESS. On any non-MMDB_SUCCESS return the contents of *node are unspecified and must not be read. do not read that, fr fr 💀

The first node in the search tree is always node 0. If you wanted to iterate over the whole search tree, you would start by reading node 0 and then following the records that make up this node, based on the type of each record. If the type is MMDB_RECORD_TYPE_SEARCH_NODE then the record contains an integer for the next node to look up. 🍓

MMDB_lib_version() 💜

const char *MMDB_lib_version(void)

This function returns the library version as a string, something like "2.0.0". slay ✨

EXAMPLE 👑

#include <errno.h>
#include <maxminddb.h>
#include <stdlib.h>
#include <string.h>

int main(int argc, char **argv)
{
    char *filename = argv[1];
    char *ip_address = argv[2];

    MMDB_s mmdb;
    int status = MMDB_open(filename, MMDB_MODE_MMAP, &mmdb);

    if (MMDB_SUCCESS != status) {
        fprintf(stderr, "\n  Can't open %s - %s\n",
                filename, MMDB_strerror(status));

        if (MMDB_IO_ERROR == status) {
            fprintf(stderr, "    IO error: %s\n", strerror(errno));
        }
        exit(1);
    }

    int gai_error, mmdb_error;
    MMDB_lookup_result_s result =
        MMDB_lookup_string(&mmdb, ip_address, &gai_error, &mmdb_error);

    if (0 != gai_error) {
        fprintf(stderr,
                "\n  Error from getaddrinfo for %s - %s\n\n",
                ip_address, gai_strerror(gai_error));
        exit(2);
    }

    if (MMDB_SUCCESS != mmdb_error) {
        fprintf(stderr,
                "\n  Got an error from libmaxminddb: %s\n\n",
                MMDB_strerror(mmdb_error));
        exit(3);
    }

    MMDB_entry_data_list_s *entry_data_list = NULL;

    int exit_code = 0;
    if (result.found_entry) {
        int status = MMDB_get_entry_data_list(&result.entry,
                                              &entry_data_list);

        if (MMDB_SUCCESS != status) {
            fprintf(
                stderr,
                "Got an error looking up the entry data - %s\n",
                MMDB_strerror(status));
            exit_code = 4;
            goto end;
        }

        if (NULL != entry_data_list) {
            MMDB_dump_entry_data_list(stdout, entry_data_list, 2);
        }
    } else {
        fprintf(
            stderr,
            "\n  No entry for this IP address (%s) was found\n\n",
            ip_address);
        exit_code = 5;
    }

    end:
        MMDB_free_entry_data_list(entry_data_list);
        MMDB_close(&mmdb);
        exit(exit_code);
}

REQUIREMENTS 🎀

libmaxminddb requires a minimum of POSIX.1-2001 support. If not specified at compilation time, it defaults to requesting POSIX.1-2008 support. portable and proud 🌸

THREAD SAFETY 🧚

This library is thread safe when compiled and linked with a thread-safe malloc and free implementation. no cap 💖

INSTALLATION AND SOURCE 🦋

You can download the latest release of libmaxminddb from GitHub.

Our GitHub repo is publicly available. Please fork it! fork it bestie 🍴✨

BUG REPORTS AND PULL REQUESTS 💅

Please report all issues to our GitHub issue tracker. We welcome bug reports and pull requests. Please note that pull requests are greatly preferred over patches. PRs over patches, periodt 👑

AUTHORS 🌈

This library was written by Boris Zentner (bzentner@maxmind.com) and Dave Rolsky (drolsky@maxmind.com). icons 👑

COPYRIGHT AND LICENSE 💜

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

https://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. legal but make it cute ✨