libmaxminddb Documentation

The MMDB_lookup_result_s structure contains the results of an IP lookup:

• found_entry: A boolean indicating if the IP was found in the database. Always check this first.
• entry: An MMDB_entry_s used to retrieve the actual data associated with the IP.
• netmask: The subnet mask for the IP.
  • For IPv4 databases, this is the prefix length (e.g., 16 for 1.1.0.0/16).
  • For IPv6 databases, this is the prefix length (0-128). If you need to convert an IPv6 netmask to an IPv4 netmask, subtract 96 from the value.

The MMDB_entry_data_s structure represents a single piece of data returned from a lookup.

• has_data: A boolean that is true if data was successfully found. If false, other members are invalid.
• type: An integer that should be compared against MMDB_DATA_TYPE_* macros to determine which member of the union to access.
• data_size: Only relevant for utf8_string and bytes.
  • Note: utf8_string is not null-terminated; you must use data_size to determine its length.
• union: Contains the actual value (e.g., uint32, double, bool, utf8_string, etc.).

Warning: The pointer member of the union should never be used directly; pointers are resolved internally by the library.

Requirements

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

Thread Safety

This library is thread safe provided it is compiled and linked with a thread-safe malloc and free implementation.

The library provides an mmdb_uint128_t type to handle 128-bit integers across different platforms and compilers.

Because compiler support for __int128 varies, the library uses the MMDB_UINT128_IS_BYTE_ARRAY macro to indicate how to access the data:

• If MMDB_UINT128_IS_BYTE_ARRAY is true (1): The uint128 value is returned as a 16-byte array of uint8_t.
• If MMDB_UINT128_IS_BYTE_ARRAY is false: The uint128 value is returned as an mmdb_uint128_t integer.

To build the fuzzer, you must export specific compiler and flag settings. Use clang and clang++ as the compilers. The flags must include -DFUZZING_BUILD_MODE_UNSAFE_FOR_PRODUCTION and appropriate sanitizers.

Commonly used sanitizers include:

• AddressSanitizer
• ThreadSanitizer
• MemorySanitizer
• UndefinedBehaviorSanitizer
• LeakSanitizer

$ export CC=clang
$ export CXX=clang++
$ export CFLAGS="-g -DFUZZING_BUILD_MODE_UNSAFE_FOR_PRODUCTION -fsanitize=address,undefined -fsanitize=fuzzer-no-link"
$ export CXXFLAGS="-g -DFUZZING_BUILD_MODE_UNSAFE_FOR_PRODUCTION -fsanitize=address,undefined -fsanitize=fuzzer-no-link"
$ export LIB_FUZZING_ENGINE="-fsanitize=fuzzer"

For recent Ubuntu versions, you can use the MaxMind PPA to install the library, development headers, and the mmdb-bin utility via apt.

sudo add-apt-repository ppa:maxmind/ppa
sudo apt update
sudo apt install libmaxminddb0 libmaxminddb-dev mmdb-bin

Installing from a GitHub source archive or a git clone requires manual dependency resolution. You must have automake, autoconf, and libtool installed in addition to make and a compiler.

First, clone the repository recursively, then run the bootstrap script before proceeding with the standard Autotools installation steps.

git clone --recursive https://github.com/maxmind/libmaxminddb
# After cloning:
./bootstrap
# Then follow the standard ./configure, make, make install steps

The mmdblookup utility allows you to query a MaxMind DB file for information associated with a specific IP address.

Important Note on Output Format: The output uses {} for maps and [] for arrays, with type annotations following values. This output is not JSON. If your workflow requires JSON, use mmdbinspect instead.

To perform a full lookup, provide the database file and the IP address. To drill down into specific parts of a record (maps or arrays), append a lookup path to the command.

# Full lookup
mmdblookup --file [FILE PATH] --ip [IP ADDRESS]

# Lookup a specific map key (e.g., English name)
mmdblookup --file [FILE PATH] --ip [IP ADDRESS] names en

# Lookup a specific array index (e.g., the second city, index 1)
mmdblookup --file [FILE PATH] --ip [IP ADDRESS] cities 1

The CMake build script is primarily intended for Windows users but can be used as an alternative to Autotools.

For Windows users building with Visual Studio who require a multithreaded (MT/MTd) runtime library, use the MSVC_STATIC_RUNTIME setting. The project also provides a CMake uninstall target.

# Standard CMake build
cmake -B build
cd build/
cmake --build .
ctest -V .
cmake --build . --target install

# Windows: Build with MSVC static runtime
cmake -DMSVC_STATIC_RUNTIME=ON -DBUILD_SHARED_LIBS=OFF ..

# Uninstall
cmake --build . --target uninstall

To install from a pre-compiled .tar.gz release (e.g., libmaxminddb-*.tar.gz), use the Autotools build system. This method works with GCC 4.4+, clang 3.2+, or any compiler supporting C99, POSIX.1-2001, and the -fms-extensions flag.

If you encounter a missing libmaxminddb.so.0 error after installation, you may need to add the installation prefix's lib directory to your library path. For the default /usr/local prefix, add /usr/local/lib to /etc/ld.so.conf.d/local.conf and run ldconfig.

./configure
make
make check
sudo make install
sudo ldconfig

To work with MaxMind DB files, you must first open the database using MMDB_open(), which returns an MMDB_s handle. After performing your lookups, you must call MMDB_close() to release the database handle and prevent memory leaks.

Note that many data structures returned by the API (like utf8_string or bytes) contain pointers directly into the database's memory-mapped or allocated block. These pointers become invalid once MMDB_close() is called. If you need to persist this data, you must copy it using functions like strdup or memcpy before closing the database.

#include <maxminddb.h>

MMDB_s mmdb;
int status = MMDB_open("example.mmdb", 0, &mmdb);
if (status == MMDB_SUCCESS) {
    // ... perform lookups ...
    MMDB_close(&mmdb);
}

After exporting the necessary environment variables, create a build directory and run CMake with the BUILD_FUZZING=ON flag to enable the fuzzer target.

$ mkdir -p build && cd build
$ cmake -DBUILD_FUZZING=ON ../.
$ cmake --build . -j$(nproc)