### Install on Ubuntu via PPA

Source: https://github.com/maxmind/libmaxminddb/blob/main/README.md

Add the MaxMind PPA to APT sources and install libmaxminddb packages on Ubuntu.

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

--------------------------------

### Install from Named Release Tarball

Source: https://github.com/maxmind/libmaxminddb/blob/main/README.md

Standard build process for installing from a release tarball. Ensure your compiler supports C99 and POSIX.1-2001.

```bash
./configure
make
make check
sudo make install
sudo ldconfig
```

--------------------------------

### Install on macOS via Homebrew

Source: https://github.com/maxmind/libmaxminddb/blob/main/README.md

Install libmaxminddb on macOS using the Homebrew package manager.

```bash
brew install libmaxminddb
```

--------------------------------

### Complete IP Address Lookup Example

Source: https://github.com/maxmind/libmaxminddb/blob/main/doc/libmaxminddb.md

This C example demonstrates opening a MaxMind DB file, performing an IP address lookup using `MMDB_lookup_string`, handling potential errors from `getaddrinfo` and libmaxminddb, retrieving and printing entry data, and finally closing the database. It requires the filename and IP address as command-line arguments.

```c
#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);
}

```

--------------------------------

### Install on macOS via MacPorts

Source: https://github.com/maxmind/libmaxminddb/blob/main/README.md

Install libmaxminddb on macOS using the MacPorts package manager.

```bash
sudo port install libmaxminddb
```

--------------------------------

### Example JSON Structure

Source: https://github.com/maxmind/libmaxminddb/blob/main/doc/mmdblookup.md

This is an example JSON structure that illustrates how data might be organized within a MaxMind DB file, showing nested maps and arrays.

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

--------------------------------

### C Example: Using MMDB_lookup_sockaddr

Source: https://github.com/maxmind/libmaxminddb/blob/main/doc/libmaxminddb.md

Shows how to use `MMDB_lookup_sockaddr` with a pre-resolved address. Check `mmdb_error` for database errors and `result.found_entry` to see if an entry was found.

```c
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) { ... }

```

--------------------------------

### Get Library Version

Source: https://github.com/maxmind/libmaxminddb/blob/main/doc/libmaxminddb.md

Returns a string representing the version of the libmaxminddb library.

```c
const char *MMDB_lib_version(void);
```

--------------------------------

### Get GPG Fingerprint

Source: https://github.com/maxmind/libmaxminddb/blob/main/README.dev.md

Obtain the fingerprint of your GPG key. This is needed when adding your key to your Launchpad account.

```bash
gpg --fingerprint
```

--------------------------------

### Add Local Library Path

Source: https://github.com/maxmind/libmaxminddb/blob/main/README.md

Add the default local library path to the system's configuration if libmaxminddb.so.0 is not found after installation.

```bash
sudo sh -c "echo /usr/local/lib  >> /etc/ld.so.conf.d/local.conf"
ldconfig
```

--------------------------------

### C Example: Using MMDB_lookup_string

Source: https://github.com/maxmind/libmaxminddb/blob/main/doc/libmaxminddb.md

Demonstrates how to use `MMDB_lookup_string` to look up an IP address and check for errors. Ensure to check `gai_error` first, then `mmdb_error`, and finally `result.found_entry`.

```c
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) { ... }

```

--------------------------------

### Example: Looking up the English name of a city

Source: https://github.com/maxmind/libmaxminddb/blob/main/doc/libmaxminddb.md

Demonstrates how to use MMDB_get_value to retrieve a specific value from a complex data structure using a lookup path. Ensure the lookup path is correctly terminated with NULL.

```c
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) { ... }
```

--------------------------------

### Get the library version

Source: https://github.com/maxmind/libmaxminddb/blob/main/doc/libmaxminddb.md

The `MMDB_lib_version` function returns the current version of the libmaxminddb library as a string.

```c
const char *MMDB_lib_version(void)

```

--------------------------------

### CMake Uninstall Target

Source: https://github.com/maxmind/libmaxminddb/blob/main/README.md

Use the CMake uninstall target to remove installed files.

```bash
cmake --build . --target uninstall
```

--------------------------------

### Get All Entry Data as a List

Source: https://github.com/maxmind/libmaxminddb/blob/main/doc/libmaxminddb.md

Retrieves all data for a complex data structure at once. Use this to avoid repeated calls to MMDB_get_value(). The list is linked in a depth-first traversal.

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

```

```c
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);

```

--------------------------------

### Dump Entry Data List to Stream

Source: https://github.com/maxmind/libmaxminddb/blob/main/doc/libmaxminddb.md

Stringifies a linked list of MMDB_entry_data_list_s structures to a given stream. The indent parameter controls the starting indentation level. Output is JSON-ish and intended for debugging.

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

```

--------------------------------

### Get Metadata as Entry Data List

Source: https://github.com/maxmind/libmaxminddb/blob/main/doc/libmaxminddb.md

Retrieves the database metadata as a linked list of entry data. The list is allocated and must be freed using MMDB_free_entry_data_list.

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

--------------------------------

### Get Value from Entry (Path Array)

Source: https://github.com/maxmind/libmaxminddb/blob/main/doc/libmaxminddb.md

Retrieves a value from a MaxMind DB entry using a NULL-terminated array of strings for the path. The result is stored in entry_data.

```c
int MMDB_aget_value(
    MMDB_entry_s *const start,
    MMDB_entry_data_s *const entry_data,
    const char *const *const path);
```

--------------------------------

### Get Value from Entry (va_list)

Source: https://github.com/maxmind/libmaxminddb/blob/main/doc/libmaxminddb.md

Retrieves a value from a MaxMind DB entry using a va_list for the path. The result is stored in entry_data.

```c
int MMDB_vget_value(
    MMDB_entry_s *const start,
    MMDB_entry_data_s *const entry_data,
    va_list va_path);
```

--------------------------------

### Get Metadata as Entry Data List

Source: https://github.com/maxmind/libmaxminddb/blob/main/doc/libmaxminddb.md

Retrieves the database metadata as a linked list of MMDB_entry_data_list_s structures. This provides a convenient way to handle metadata compared to the direct structure.

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

```

```c
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);

```

--------------------------------

### Get Error String

Source: https://github.com/maxmind/libmaxminddb/blob/main/doc/libmaxminddb.md

Converts an error code returned by libmaxminddb functions into a human-readable error string.

```c
const char *MMDB_strerror(int error_code);
```

--------------------------------

### Get Entry Data List

Source: https://github.com/maxmind/libmaxminddb/blob/main/doc/libmaxminddb.md

Retrieves all entry data associated with an entry as a linked list. The list is allocated and must be freed using MMDB_free_entry_data_list.

```c
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);
```

--------------------------------

### Get Value from Entry

Source: https://github.com/maxmind/libmaxminddb/blob/main/doc/libmaxminddb.md

Retrieves a value from a MaxMind DB entry using a variable argument list for the path. The result is stored in entry_data.

```c
int MMDB_get_value(
    MMDB_entry_s *const start,
    MMDB_entry_data_s *const entry_data,
    ...);
```

--------------------------------

### Update Homebrew Formula SHA256

Source: https://github.com/maxmind/libmaxminddb/blob/main/README.dev.md

Update the tarball URL and SHA256 checksum in the Homebrew formula for libmaxminddb. Use `sha256sum` to get the checksum.

```bash
sha256sum
```

--------------------------------

### Send GPG Key to Ubuntu Keyserver

Source: https://github.com/maxmind/libmaxminddb/blob/main/README.dev.md

Publish your GPG key to the Ubuntu keyserver. This is a required step for PPA releases.

```bash
gpg --keyserver keyserver.ubuntu.com --send-keys KEYID
```

--------------------------------

### Run the fuzzer

Source: https://github.com/maxmind/libmaxminddb/blob/main/README.fuzzing.md

Prepare the seed corpus and execute the fuzzer binary.

```shell
$ mkdir -p fuzz_mmdb_seed fuzz_mmdb_seed_corpus
$ find ../t/maxmind-db/test-data/ -type f -size -4k -exec cp {} ./fuzz_mmdb_seed_corpus/ \;
$ ./t/fuzz_mmdb fuzz_mmdb_seed/ fuzz_mmdb_seed_corpus/
```

--------------------------------

### Clone and Build from Git Repository

Source: https://github.com/maxmind/libmaxminddb/blob/main/README.md

Steps to clone the libmaxminddb repository and build it using Autotools. Requires automake, autoconf, and libtool.

```bash
git clone --recursive https://github.com/maxmind/libmaxminddb
cd libmaxminddb/
./bootstrap
```

--------------------------------

### Import GPG Secret Key

Source: https://github.com/maxmind/libmaxminddb/blob/main/README.dev.md

Import your GPG secret key into your system. Ensure the key is suitable for signing releases.

```bash
gpg --import /path/to/key
```

--------------------------------

### Build with CMake

Source: https://github.com/maxmind/libmaxminddb/blob/main/README.md

Build the library using CMake. This method is primarily targeted at Windows users but can be used elsewhere.

```bash
cmake -B build
cd build/
cmake --build .
ctest -V .
cmake --build . --target install
```

--------------------------------

### List Secret Keys

Source: https://github.com/maxmind/libmaxminddb/blob/main/README.dev.md

Verify that your GPG secret key is listed and accessible on your system.

```bash
gpg --list-secret-keys
```

--------------------------------

### Export environment variables for fuzzing

Source: https://github.com/maxmind/libmaxminddb/blob/main/README.fuzzing.md

Set the compiler and flags to enable AddressSanitizer and libFuzzer instrumentation.

```shell
$ 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"
```

--------------------------------

### Create Release Tarball

Source: https://github.com/maxmind/libmaxminddb/blob/main/README.md

Use 'make safedist' to check the integrity of the generated release tarball.

```bash
make safedist
```

--------------------------------

### Build libmaxminddb for fuzzing

Source: https://github.com/maxmind/libmaxminddb/blob/main/README.fuzzing.md

Configure and compile the project with the fuzzing build option enabled.

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

--------------------------------

### Build Test Executables

Source: https://github.com/maxmind/libmaxminddb/blob/main/t/CMakeLists.txt

Iterates through the defined test targets to create executables. It sets include directories, links libraries, and defines package versions.

```cmake
foreach(TEST_TARGET_NAME ${TEST_TARGET_NAMES})
  add_executable(${TEST_TARGET_NAME} ${TEST_TARGET_NAME}.c maxminddb_test_helper.c)
  target_include_directories(${TEST_TARGET_NAME} PRIVATE ../src)
  target_link_libraries(${TEST_TARGET_NAME} maxminddb tap)
  target_compile_definitions(${TEST_TARGET_NAME} PRIVATE PACKAGE_VERSION="${PROJECT_VERSION}")

  if(UNIX)
    target_link_libraries(${TEST_TARGET_NAME} m)
  endif()

  if (UNIX)
    target_link_libraries(${TEST_TARGET_NAME} ${CMAKE_THREAD_LIBS_INIT})
  endif()

  add_test( NAME ${TEST_TARGET_NAME} COMMAND ${TEST_TARGET_NAME} WORKING_DIRECTORY ${PROJECT_SOURCE_DIR}/t)
endforeach()
```

--------------------------------

### Open MaxMind DB File

Source: https://github.com/maxmind/libmaxminddb/blob/main/doc/libmaxminddb.md

Opens a handle to a MaxMind DB file. Always check the return value for MMDB_SUCCESS. The database can be opened using mmap.

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

--------------------------------

### Add Library

Source: https://github.com/maxmind/libmaxminddb/blob/main/t/CMakeLists.txt

Adds the libtap library to the build. This is a common step for including external libraries.

```cmake
add_library(tap
  libtap/tap.c
)
```

--------------------------------

### Configure CMake Uninstall Target

Source: https://github.com/maxmind/libmaxminddb/blob/main/CMakeLists.txt

Defines a custom uninstall target by configuring a template file and adding a custom command to execute it.

```cmake
if(NOT TARGET uninstall)
  configure_file(
    "${CMAKE_CURRENT_SOURCE_DIR}/cmake_uninstall.cmake.in"
    "${CMAKE_CURRENT_BINARY_DIR}/cmake_uninstall.cmake"
    IMMEDIATE @ONLY)

  add_custom_target(uninstall
    COMMAND ${CMAKE_COMMAND} -P ${CMAKE_CURRENT_BINARY_DIR}/cmake_uninstall.cmake)
endif()
```

--------------------------------

### MMDB_open

Source: https://github.com/maxmind/libmaxminddb/blob/main/doc/libmaxminddb.md

Opens a MaxMind DB file for reading. This function initializes a database handle that can be used for subsequent lookups.

```APIDOC
## MMDB_open

### Description
Opens a MaxMind DB file for reading. This function initializes a database handle that can be used for subsequent lookups.

### Function Signature
```c
int MMDB_open(const char *const filename, uint32_t flags, MMDB_s *const mmdb);
```

### Parameters
- **filename** (const char *const) - The path to the MaxMind DB file.
- **flags** (uint32_t) - Flags to control the opening behavior. See documentation for `MMDB_open()` for details.
- **mmdb** (MMDB_s *const) - A pointer to an `MMDB_s` structure that will be populated with the database handle.

### Return Value
Returns 0 on success, or an error code on failure.
```

--------------------------------

### MMDB_lookup_string()

Source: https://github.com/maxmind/libmaxminddb/blob/main/doc/libmaxminddb.md

Looks up an IP address provided as a null-terminated string. It internally calls getaddrinfo() to resolve the address and then MMDB_lookup_sockaddr() to query the database. It returns an MMDB_lookup_result_s structure and populates error parameters for getaddrinfo() and database errors.

```APIDOC
## `MMDB_lookup_string()`

### Description
Looks up an IP address that is passed in as a null-terminated string. Internally, it calls `getaddrinfo()` to resolve the address into a binary form and then `MMDB_lookup_sockaddr()` to look the address up in the database. This function is useful if you have the IP address as a string and haven't resolved it yet.

### Signature
```c
MMDB_lookup_result_s MMDB_lookup_string(
    const MMDB_s *const mmdb,
    const char *const ipstr,
    int *const gai_error,
    int *const mmdb_error);
```

### Parameters
- **mmdb** (const MMDB_s *const) - A pointer to the MMDB database structure.
- **ipstr** (const char *const) - A null-terminated string representing the IP address to look up.
- **gai_error** (int *const) - A pointer to an integer that will store the error code from `getaddrinfo()` if it fails. If `getaddrinfo()` succeeds, this will be set to `MMDB_SUCCESS`.
- **mmdb_error** (int *const) - A pointer to an integer that will store the error code from the MaxMind DB library. If no database error occurred, this will be set to `MMDB_SUCCESS`.

### Return Value
Returns an `MMDB_lookup_result_s` structure containing the lookup result. The `found_entry` member indicates if an entry was found for the IP address.

### Error Handling
- Always check `*gai_error` first. If it is non-zero, `getaddrinfo()` failed, and the returned structure is meaningless. `*mmdb_error` will be `MMDB_SUCCESS` in this case.
- If `*gai_error` is `MMDB_SUCCESS`, check `*mmdb_error`. If it is not `MMDB_SUCCESS`, a database error occurred.
- If both error parameters indicate success, check the `found_entry` member of the returned `MMDB_lookup_result_s`. If `found_entry` is false, the IP address does not have an entry in the database.

### Example
```c
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) {
    // Handle getaddrinfo error
} 
if (MMDB_SUCCESS != mmdb_error) {
    // Handle MMDB error
}

if (result.found_entry) {
    // Entry found, process result
} else {
    // No entry found for the IP address
}
```
```

--------------------------------

### Define Test Targets

Source: https://github.com/maxmind/libmaxminddb/blob/main/t/CMakeLists.txt

Initializes a list of test target names for the project. This is a standard CMake practice for managing multiple executables.

```cmake
set(TEST_TARGET_NAMES
  bad_pointers_t
  bad_search_tree_t
  basic_lookup_t
  data_entry_list_t
  data-pool-t
  data_types_t
  double_close_t
  dump_t
  gai_error_t
  get_value_pointer_bug_t
  get_value_t
  ipv4_start_cache_t
  ipv6_lookup_in_ipv4_t
  metadata_marker_t
  metadata_pointers_t
  metadata_t
  no_map_get_value_t
  overflow_bounds_t
  read_node_t
  version_t
)
```

--------------------------------

### Edit GPG Key

Source: https://github.com/maxmind/libmaxminddb/blob/main/README.dev.md

Edit your GPG key to trust it ultimately. This is necessary for signing releases.

```bash
gpg --edit-key KEYID
```

--------------------------------

### MMDB_open

Source: https://github.com/maxmind/libmaxminddb/blob/main/doc/libmaxminddb.md

Opens a handle to a MaxMind DB file, returning a status code indicating success or failure. Always check the return value.

```APIDOC
## MMDB_open()

### Description
This function 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.

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

The `MMDB_s` structure you pass in can be on the stack or allocated from the heap. However, if the open is successful it will contain heap-allocated data, so you need to close it with `MMDB_close()`. If the status returned is not `MMDB_SUCCESS` then this library makes sure that all allocated memory is freed before returning.

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 we may add additional flags that you can bitwise-or together with the mode, as well as additional modes.

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

### Signature
```c
int MMDB_open(
    const char *const filename,
    uint32_t flags,
    MMDB_s *const mmdb);
```

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

--------------------------------

### Windows Specific Definitions

Source: https://github.com/maxmind/libmaxminddb/blob/main/t/CMakeLists.txt

Adds compiler definitions to suppress specific warnings on Windows. This is useful for maintaining a clean build output on different platforms.

```cmake
if(WIN32)
  # 4244, 4267 - libtap causes a significant number of conversion warning in
  #              our tests on Windows.
  # 4996 - vsprintf used by libtap is unsafe.
  add_definitions("/wd4244 /wd4267 /wd4996")
endif(WIN32)
```

--------------------------------

### CMake Build with Static Runtime and Shared Libraries Disabled

Source: https://github.com/maxmind/libmaxminddb/blob/main/README.md

Configure CMake to build a multithreaded static runtime library and disable shared libraries, typically for Visual Studio.

```bash
cmake -DMSVC_STATIC_RUNTIME=ON -DBUILD_SHARED_LIBS=OFF ..

```

--------------------------------

### MMDB_lib_version

Source: https://github.com/maxmind/libmaxminddb/blob/main/doc/libmaxminddb.md

Returns the version string of the libmaxminddb library.

```APIDOC
## MMDB_lib_version

### Description
Returns the version string of the libmaxminddb library.

### Function Signature
```c
const char *MMDB_lib_version(void);
```

### Return Value
Returns a pointer to a null-terminated string containing the library version.
```

--------------------------------

### Dump Entry Data List to Stream

Source: https://github.com/maxmind/libmaxminddb/blob/main/doc/libmaxminddb.md

Dumps the contents of an entry data list to a specified file stream with optional indentation. Useful for debugging.

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

--------------------------------

### MMDB_dump_entry_data_list

Source: https://github.com/maxmind/libmaxminddb/blob/main/doc/libmaxminddb.md

Stringifies a linked list of `MMDB_entry_data_list_s` structures to a specified file stream. The output is formatted in a JSON-like manner, with data types indicated, and is intended for user readability and debugging.

```APIDOC
## `MMDB_dump_entry_data_list()`

### Description
Stringifies a linked list of `MMDB_entry_data_list_s` structures to a specified file stream. The output is formatted in a JSON-like manner, with data types indicated, and is intended for user readability and debugging. The specific output format may change in future releases.

### Signature
```c
int MMDB_dump_entry_data_list(
    FILE *const stream,
    MMDB_entry_data_list_s *const entry_data_list,
    int indent);
```

### Parameters
- **stream** (`FILE *const`) - A file handle (e.g., `stdout`) to which the stringified data will be written.
- **entry_data_list** (`MMDB_entry_data_list_s *const`) - A pointer to the head of the `MMDB_entry_data_list_s` structure to be dumped.
- **indent** (`int`) - The starting indentation level for the output. This is incremented for nested data structures.

### Return Value
A status code indicating success or failure.
```

--------------------------------

### Open and Close MaxMind DB

Source: https://github.com/maxmind/libmaxminddb/blob/main/doc/libmaxminddb.md

Opens a MaxMind DB file for reading and closes it when done. Ensure to call MMDB_close to release resources.

```c
#include <maxminddb.h>

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

--------------------------------

### Lookup IP Address by String

Source: https://github.com/maxmind/libmaxminddb/blob/main/doc/libmaxminddb.md

Looks up an IP address provided as a string in the MaxMind DB. Returns a lookup result structure. Error codes are returned via gai_error and mmdb_error.

```c
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_get_metadata_as_entry_data_list

Source: https://github.com/maxmind/libmaxminddb/blob/main/doc/libmaxminddb.md

Retrieves the database metadata as a linked list of `MMDB_entry_data_list_s` structures. This provides a more convenient way to access metadata compared to using the metadata structure directly.

```APIDOC
## `MMDB_get_metadata_as_entry_data_list()`

### Description
Retrieves the database metadata as a linked list of `MMDB_entry_data_list_s` structures. This provides a more convenient way to access metadata compared to using the metadata structure directly.

### Signature
```c
int MMDB_get_metadata_as_entry_data_list(
    const MMDB_s *const mmdb,
    MMDB_entry_data_list_s **const entry_data_list);
```

### Parameters
- **mmdb** (`const MMDB_s *const`) - A pointer to the `MMDB_s` database structure.
- **entry_data_list** (`MMDB_entry_data_list_s **const`) - A pointer to a pointer that will be populated with the head of a linked list of `MMDB_entry_data_list_s` structures representing the metadata.

### Return Value
A status code indicating success or failure. `MMDB_SUCCESS` on success.
```

--------------------------------

### Lookup English Name in MaxMind DB

Source: https://github.com/maxmind/libmaxminddb/blob/main/doc/mmdblookup.md

Use this command to retrieve a specific value from a map within the MaxMind DB record. The path 'names en' targets the English name from the 'names' map.

```bash
mmdblookup --file ... --ip ... names en
```

--------------------------------

### Build Fuzzing Target

Source: https://github.com/maxmind/libmaxminddb/blob/main/t/CMakeLists.txt

Creates a fuzzing executable if BUILD_FUZZING is enabled. This includes linking against the main library and the fuzzing engine.

```cmake
if(BUILD_FUZZING)
  add_executable(fuzz_mmdb fuzz_mmdb.c)
  target_include_directories(fuzz_mmdb PRIVATE ../src)
  target_link_libraries(fuzz_mmdb maxminddb $ENV{LIB_FUZZING_ENGINE})
endif()
```

--------------------------------

### Configure mmdblookup executable in CMake

Source: https://github.com/maxmind/libmaxminddb/blob/main/bin/CMakeLists.txt

Defines the mmdblookup executable target, sets compiler definitions, and links necessary libraries for non-MSVC environments.

```cmake
if(NOT MSVC)
  add_executable(mmdblookup
    mmdblookup.c
  )

# Otherwise 'undefined reference to WinMain' linker error happen due to wmain()
  if(MINGW)
    target_link_options(mmdblookup PRIVATE "-municode")
  endif()

  target_compile_definitions(mmdblookup PRIVATE PACKAGE_VERSION="${PROJECT_VERSION}")

  target_link_libraries(mmdblookup maxminddb pthread)

  if (MAXMINDDB_INSTALL)
    install(
      TARGETS mmdblookup
      DESTINATION ${CMAKE_INSTALL_BINDIR}
    )
  endif()
endif()
```

--------------------------------

### MMDB_lib_version

Source: https://github.com/maxmind/libmaxminddb/blob/main/doc/libmaxminddb.md

Retrieves the version of the libmaxminddb library as a string. This is useful for checking compatibility or logging.

```APIDOC
## MMDB_lib_version

### Description
This function returns the library version as a string, something like "2.0.0".

### Parameters
None

### Return Value
- **const char ":** A string representing the library version.
```

--------------------------------

### Lookup Second City in MaxMind DB Array

Source: https://github.com/maxmind/libmaxminddb/blob/main/doc/mmdblookup.md

Use this command to access an element within an array in the MaxMind DB record. The path 'cities 1' retrieves the second item (index 1) from the 'cities' array.

```bash
mmdblookup --file ... --ip ... cities 1
```

--------------------------------

### C Function Signature: MMDB_lookup_sockaddr

Source: https://github.com/maxmind/libmaxminddb/blob/main/doc/libmaxminddb.md

Defines the signature for the `MMDB_lookup_sockaddr` function, which takes a database handle, a sockaddr structure, and an error pointer.

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

```

--------------------------------

### MMDB_s Structure Definition

Source: https://github.com/maxmind/libmaxminddb/blob/main/doc/libmaxminddb.md

Defines the main handle structure for a MaxMind DB file, including flags, filename, and metadata. Note that some fields are for internal use only.

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

--------------------------------

### MMDB_get_metadata_as_entry_data_list

Source: https://github.com/maxmind/libmaxminddb/blob/main/doc/libmaxminddb.md

Retrieves the database metadata as a linked list of MMDB_entry_data_s structures.

```APIDOC
## MMDB_get_metadata_as_entry_data_list

### Description
Retrieves the database metadata as a linked list of `MMDB_entry_data_s` structures.

### Function Signature
```c
int MMDB_get_metadata_as_entry_data_list(const MMDB_s *const mmdb, MMDB_entry_data_list_s **const entry_data_list);
```

### Parameters
- **mmdb** (const MMDB_s *const) - A pointer to the `MMDB_s` database handle.
- **entry_data_list** (MMDB_entry_data_list_s **const) - A pointer to a pointer that will be populated with the head of the linked list of metadata.

### Return Value
Returns 0 on success, or an error code on failure.
```

--------------------------------

### libmaxminddb Data Lookup Function Signatures

Source: https://github.com/maxmind/libmaxminddb/blob/main/doc/libmaxminddb.md

These are the three functions available for looking up data. They offer different calling styles but perform the same core functionality.

```c
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);
```

--------------------------------

### Lookup IP Address by Sockaddr

Source: https://github.com/maxmind/libmaxminddb/blob/main/doc/libmaxminddb.md

Looks up an IP address from a sockaddr structure in the MaxMind DB. Returns a lookup result structure. Error codes are returned via mmdb_error.

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

--------------------------------

### MMDB_get_entry_data_list

Source: https://github.com/maxmind/libmaxminddb/blob/main/doc/libmaxminddb.md

Retrieves all data for an entry as a linked list of MMDB_entry_data_s structures.

```APIDOC
## MMDB_get_entry_data_list

### Description
Retrieves all data for an entry as a linked list of `MMDB_entry_data_s` structures.

### Function Signature
```c
int MMDB_get_entry_data_list(MMDB_entry_s *start, MMDB_entry_data_list_s **const entry_data_list);
```

### Parameters
- **start** (MMDB_entry_s *) - The starting entry, typically obtained from a lookup result.
- **entry_data_list** (MMDB_entry_data_list_s **const) - A pointer to a pointer that will be populated with the head of the linked list of entry data.

### Return Value
Returns 0 on success, or an error code on failure.
```

--------------------------------

### C Function Signature: MMDB_lookup_string

Source: https://github.com/maxmind/libmaxminddb/blob/main/doc/libmaxminddb.md

Defines the signature for the `MMDB_lookup_string` function, which takes a database handle, an IP address string, and error pointers.

```c
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_sockaddr()

Source: https://github.com/maxmind/libmaxminddb/blob/main/doc/libmaxminddb.md

Looks up an IP address that has already been resolved into a sockaddr structure. This function is more efficient if the address has already been resolved by getaddrinfo() as it avoids redundant resolution. It returns an MMDB_lookup_result_s structure and populates an error parameter for database errors.

```APIDOC
## `MMDB_lookup_sockaddr()`

### Description
Looks up an IP address that has already been resolved by `getaddrinfo()` and is provided as a `struct sockaddr`. This function is identical to `MMDB_lookup_string()` except that it does not call `getaddrinfo()` internally, making it more efficient if the address resolution has already been performed.

### Signature
```c
MMDB_lookup_result_s MMDB_lookup_sockaddr(
    const MMDB_s *const mmdb,
    const struct sockaddr *const sockaddr,
    int *const mmdb_error);
```

### Parameters
- **mmdb** (const MMDB_s *const) - A pointer to the MMDB database structure.
- **sockaddr** (const struct sockaddr *const) - A pointer to a `struct sockaddr` representing the IP address (AF_INET or AF_INET6) to look up.
- **mmdb_error** (int *const) - A pointer to an integer that will store the error code from the MaxMind DB library. If no database error occurred, this will be set to `MMDB_SUCCESS`.

### Return Value
Returns an `MMDB_lookup_result_s` structure containing the lookup result. The `found_entry` member indicates if an entry was found for the IP address.

### Error Handling
- Check the `*mmdb_error` parameter. If it is not `MMDB_SUCCESS`, a database error occurred.
- If `*mmdb_error` is `MMDB_SUCCESS`, check the `found_entry` member of the returned `MMDB_lookup_result_s`. If `found_entry` is false, the IP address does not have an entry in the database.

### Example
```c
int mmdb_error;
MMDB_lookup_result_s result = MMDB_lookup_sockaddr(&mmdb, address->ai_addr, &mmdb_error);
if (MMDB_SUCCESS != mmdb_error) {
    // Handle MMDB error
}

if (result.found_entry) {
    // Entry found, process result
} else {
    // No entry found for the IP address
}
```
```

--------------------------------

### MMDB_lookup_string

Source: https://github.com/maxmind/libmaxminddb/blob/main/doc/libmaxminddb.md

Looks up an IP address provided as a string in the MaxMind DB database.

```APIDOC
## MMDB_lookup_string

### Description
Looks up an IP address provided as a string in the MaxMind DB database.

### Function Signature
```c
MMDB_lookup_result_s MMDB_lookup_string(const char *const ipstr, int *const gai_error, int *const mmdb_error);
```

### Parameters
- **ipstr** (const char *const) - The IP address string to look up.
- **gai_error** (int *const) - A pointer to an integer that will store any getaddrinfo error code.
- **mmdb_error** (int *const) - A pointer to an integer that will store any libmaxminddb error code.

### Return Value
Returns a `MMDB_lookup_result_s` structure containing the lookup result. The `found_entry` field indicates if an entry was found for the IP address.
```

--------------------------------

### MMDB_lookup_sockaddr

Source: https://github.com/maxmind/libmaxminddb/blob/main/doc/libmaxminddb.md

Looks up an IP address provided as a sockaddr structure in the MaxMind DB database.

```APIDOC
## MMDB_lookup_sockaddr

### Description
Looks up an IP address provided as a sockaddr structure in the MaxMind DB database.

### Function Signature
```c
MMDB_lookup_result_s MMDB_lookup_sockaddr(const struct sockaddr *const sockaddr, int *const mmdb_error);
```

### Parameters
- **sockaddr** (const struct sockaddr *const) - A pointer to the `sockaddr` structure representing the IP address.
- **mmdb_error** (int *const) - A pointer to an integer that will store any libmaxminddb error code.

### Return Value
Returns a `MMDB_lookup_result_s` structure containing the lookup result. The `found_entry` field indicates if an entry was found for the IP address.
```

--------------------------------

### MMDB_dump_entry_data_list

Source: https://github.com/maxmind/libmaxminddb/blob/main/doc/libmaxminddb.md

Dumps the contents of an MMDB_entry_data_list_s linked list to a file stream.

```APIDOC
## MMDB_dump_entry_data_list

### Description
Dumps the contents of an `MMDB_entry_data_list_s` linked list to a file stream.

### Function Signature
```c
int MMDB_dump_entry_data_list(FILE *const stream, MMDB_entry_data_list_s *const entry_data_list, int indent);
```

### Parameters
- **stream** (FILE *const) - The file stream to write to.
- **entry_data_list** (MMDB_entry_data_list_s *const) - The head of the linked list to dump.
- **indent** (int) - The indentation level for pretty-printing.

### Return Value
Returns 0 on success, or an error code on failure.
```

--------------------------------

### Conditionally Add Unix Test Targets

Source: https://github.com/maxmind/libmaxminddb/blob/main/t/CMakeLists.txt

Appends additional test targets to the list if the system is Unix-based. This allows for platform-specific test suites.

```cmake
if(UNIX)  # or if (NOT WIN32)
  list(APPEND TEST_TARGET_NAMES
    bad_databases_t
    bad_data_size_t
    bad_epoch_t
    bad_indent_t
    empty_container_metadata_t
    invalid_sockaddr_t
    max_depth_t
    threads_t
  )
  find_package(Threads)
endif()
```

--------------------------------

### MMDB_metadata_s Structure Definition

Source: https://github.com/maxmind/libmaxminddb/blob/main/doc/libmaxminddb.md

Defines the structure for holding metadata read from a MaxMind DB file, including node count, record size, IP version, database type, languages, and build information.

```c
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;
```

--------------------------------

### Read Node from Database

Source: https://github.com/maxmind/libmaxminddb/blob/main/doc/libmaxminddb.md

Reads a specific node from the MaxMind DB file based on its node number. The node data is populated into the provided MMDB_search_node_s structure.

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

--------------------------------

### Free Entry Data List Memory

Source: https://github.com/maxmind/libmaxminddb/blob/main/doc/libmaxminddb.md

Frees the memory allocated by MMDB_get_entry_data_list() and MMDB_get_metadata_as_entry_data_list(). Call this after you are done with the data structure.

```c
void MMDB_free_entry_data_list(
    MMDB_entry_data_list_s *const entry_data_list);

```

--------------------------------

### MMDB_vget_value

Source: https://github.com/maxmind/libmaxminddb/blob/main/doc/libmaxminddb.md

Retrieves a specific value from a MaxMind DB entry using a va_list for the path.

```APIDOC
## MMDB_vget_value

### Description
Retrieves a specific value from a MaxMind DB entry using a va_list for the path.

### Function Signature
```c
int MMDB_vget_value(MMDB_entry_s *const start, MMDB_entry_data_s *const entry_data, va_list va_path);
```

### Parameters
- **start** (MMDB_entry_s *const) - The starting entry, typically obtained from a lookup result.
- **entry_data** (MMDB_entry_data_s *const) - A pointer to an `MMDB_entry_data_s` structure to store the retrieved data.
- **va_path** (va_list) - A `va_list` containing the path to the desired value within the entry.

### Return Value
Returns 0 on success, or an error code on failure.
```

--------------------------------

### MMDB_strerror

Source: https://github.com/maxmind/libmaxminddb/blob/main/doc/libmaxminddb.md

Converts a libmaxminddb status code into a human-readable English string.

```APIDOC
## MMDB_strerror()

### Description
This function takes a status code and returns an English string explaining the status.

### Signature
```c
const char *MMDB_strerror(int error_code)
```
```

--------------------------------

### MMDB_entry_data_list_s Structure Definition

Source: https://github.com/maxmind/libmaxminddb/blob/main/doc/libmaxminddb.md

Represents a node in a linked list of entry data. Each node contains an MMDB_entry_data_s and a pointer to the next node.

```c
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;
```

--------------------------------

### MMDB_entry_data_s Structure Definition

Source: https://github.com/maxmind/libmaxminddb/blob/main/doc/libmaxminddb.md

Holds data for a MaxMind DB entry, including its type, size, and the actual data in a union. Indicates if data is present.

```c
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;
```

--------------------------------

### MMDB_free_entry_data_list

Source: https://github.com/maxmind/libmaxminddb/blob/main/doc/libmaxminddb.md

Frees the memory allocated for a linked list of `MMDB_entry_data_list_s` structures. This function should be called to release resources obtained from `MMDB_get_entry_data_list()` and `MMDB_get_metadata_as_entry_data_list()`.

```APIDOC
## `MMDB_free_entry_data_list()`

### Description
Frees the memory allocated for a linked list of `MMDB_entry_data_list_s` structures. This function should be called to release resources obtained from `MMDB_get_entry_data_list()` and `MMDB_get_metadata_as_entry_data_list()`.

### Signature
```c
void MMDB_free_entry_data_list(
    MMDB_entry_data_list_s *const entry_data_list);
```

### Parameters
- **entry_data_list** (`MMDB_entry_data_list_s *const`) - A pointer to the head of the `MMDB_entry_data_list_s` structure to be freed.
```

--------------------------------

### MMDB_get_entry_data_list

Source: https://github.com/maxmind/libmaxminddb/blob/main/doc/libmaxminddb.md

Retrieves all data for a complex data structure associated with a MaxMind DB entry. This function allows fetching an entire data structure at once, avoiding repeated calls to `MMDB_get_value()`.

```APIDOC
## `MMDB_get_entry_data_list()`

### Description
Retrieves all data for a complex data structure associated with a MaxMind DB entry. This function allows fetching an entire data structure at once, avoiding repeated calls to `MMDB_get_value()`.

### Signature
```c
int MMDB_get_entry_data_list(
    MMDB_entry_s *start,
    MMDB_entry_data_list_s **const entry_data_list);
```

### Parameters
- **start** (`MMDB_entry_s *`) - A pointer to an `MMDB_entry_s` struct, typically obtained from `MMDB_lookup_result_s.entry`.
- **entry_data_list** (`MMDB_entry_data_list_s **const`) - A pointer to a pointer that will be populated with the head of a linked list of `MMDB_entry_data_list_s` structures representing the entry's data.

### Return Value
A status code indicating success or failure. `MMDB_SUCCESS` on success.
```

--------------------------------

### MMDB_description_s Structure Definition

Source: https://github.com/maxmind/libmaxminddb/blob/main/doc/libmaxminddb.md

Defines the structure for holding language and description pairs within the database metadata.

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

--------------------------------

### MMDB_free_entry_data_list

Source: https://github.com/maxmind/libmaxminddb/blob/main/doc/libmaxminddb.md

Frees the memory allocated for an MMDB_entry_data_list_s linked list.

```APIDOC
## MMDB_free_entry_data_list

### Description
Frees the memory allocated for an `MMDB_entry_data_list_s` linked list.

### Function Signature
```c
void MMDB_free_entry_data_list(MMDB_entry_data_list_s *const entry_data_list);
```

### Parameters
- **entry_data_list** (MMDB_entry_data_list_s *const) - The head of the linked list to free.
```