.\" -*- mode: troff; coding: utf-8 -*-
.TH "libmaxminddb" "3" ""
.SH NAME
libmaxminddb - a library for working with MaxMind DB files
.SH SYNOPSIS
.LP
.EX
#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(
    MMDB_s *const mmdb,
    const char *const ipstr,
    int *const gai_error,
    int *const mmdb_error);
MMDB_lookup_result_s MMDB_lookup_sockaddr(
    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(
    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(
    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;
.EE
.SH DESCRIPTION
The libmaxminddb library provides functions for working MaxMind DB files. See
\fIhttp://maxmind.github.io/MaxMind-DB/\fR for the MaxMind DB format specification.
The database and results are all represented by different data structures.
Databases are opened by calling \fCMMDB_open()\fR. You can look up IP addresses as
a string with \fCMMDB_lookup_string()\fR or as a pointer to a \fCsockaddr\fR
structure with \fCMMDB_lookup_sockaddr()\fR.
.PP
If the lookup finds the IP address in the database, it returns a
\fCMMDB_lookup_result_s\fR structure. 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 \fCMMDB_get_value()\fR and \fCMMDB_get_entry_data_list()\fR.
See the function documentation below for more details.
.PP
When you are done with the database handle you should call \fCMMDB_close()\fR.
.PP
All publicly visible functions, structures, and macros begin with \(dqMMDB_\(dq.
.SH DATA STRUCTURES
All data structures exported by this library's \fCmaxminddb.h\fR header are
typedef'd in the form \fCtypedef struct foo_s { ... } foo_s\fR so you can refer to
them without the \fCstruct\fR prefix.
.PP
This library provides the following data structures:
.SS \fCMMDB_s\fR
This is the handle for a MaxMind DB file. We only document some of this
structure's fields intended for public use. All other fields are subject to
change and are intended only for internal use.
.LP
.EX
typedef struct MMDB_s {
    uint32_t flags;
    const char *filename;
    ...
    MMDB_metadata_s metadata;
} MMDB_s;
.EE
.IP "\(bu" 2
\fCuint32_t flags\fR - the flags this database was opened with. See the
\fCMMDB_open()\fR documentation for more details.
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 2
\fCconst char *filename\fR - the name of the file which was opened, as passed to
\fCMMDB_open()\fR.
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 2
\fCMMDB_metadata_s metadata\fR - the metadata for the database.
.SS \fCMMDB_metadata_s\fR and \fCMMDB_description_s\fR
This structure can be retrieved from the \fCMMDB_s\fR structure. It contains the
metadata read from the database file. Note that you may find it more convenient
to access this metadata by calling \fCMMDB_get_metadata_as_entry_data_list()\fR
instead.
.LP
.EX
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;
.EE
.PP
These structures should be mostly self-explanatory.
.PP
The \fCip_version\fR member should always be \fC4\fR or \fC6\fR. The
\fCbinary_format_major_version\fR should always be \fC2\fR.
.PP
There is no requirement that the database metadata include languages or
descriptions, so the \fCcount\fR for these parts of the metadata can be zero. All
of the other \fCMMDB_metadata_s\fR fields should be populated.
.SS \fCMMDB_lookup_result_s\fR
This structure is returned as the result of looking up an IP address.
.LP
.EX
typedef struct MMDB_lookup_result_s {
    bool found_entry;
    MMDB_entry_s entry;
    uint16_t netmask;
} MMDB_lookup_result_s;
.EE
.PP
If the \fCfound_entry\fR member is false then the other members of this structure
do not contain meaningful values. Always check that \fCfound_entry\fR is true
first.
.PP
The \fCentry\fR member is used to look up the data associated with the IP address.
.PP
The \fCnetmask\fR member tells you what subnet the IP address belongs to in this
database. For example, if you look up the address \fC1.1.1.1\fR in an IPv4 database
and the returned \fCnetmask\fR is 16, then the address is part of the \fC1.1.0.0/16\fR
subnet.
.PP
If the database is an IPv6 database, the returned netmask is always an IPv6
prefix length (from 0-128), even if that database \fIalso\fR 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 \fC96\fR from the value.
.SS \fCMMDB_result_s\fR
You don't really need to dig around in this structure. You'll get this from a
\fCMMDB_lookup_result_s\fR structure and pass it to various functions.
.SS \fCMMDB_entry_data_s\fR
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.
.LP
.EX
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;
.EE
.PP
The \fChas_data\fR member is true if data was found for a given lookup. See
\fCMMDB_get_value()\fR for more details. If this member is false then none of the
other values in the structure are meaningful.
.PP
The union at the beginning of the structure defines the actual data. To
determine which union member is populated you should look at the \fCtype\fR member.
The \fCpointer\fR member of the union should never be populated in any data
returned by the API. Pointers should always be resolved internally.
.PP
The \fCdata_size\fR member is only relevant for \fCutf8_string\fR and \fCbytes\fR data.
\fCutf8_string\fR is not null terminated and \fCdata_size\fR \fImust\fR be used to
determine its length.
.PP
The \fCtype\fR member can be compared to one of the \fCMMDB_DATA_TYPE_*\fR macros.
.SS 128-bit Integers
The handling of \fCuint128\fR 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 \fCunsigned
int __attribute__ ((__mode__ (TI)))\fR. With newer versions of GCC (4.6+) and
clang (3.2+) we can simply write \(dqunsigned __int128\(dq.
.PP
In order to work around these differences, this library defines an
\fCmmdb_uint128_t\fR type. This type is defined in the \fCmaxminddb.h\fR header so you
can use it in your own code.
.PP
With older compilers, we can't use an integer so we instead use a 16 byte
array of \fCuint8_t\fR values. This is the raw data from the database.
.PP
This library provides a public macro \fCMMDB_UINT128_IS_BYTE_ARRAY\fR macro. If
this is true (1), then \fCuint128\fR values are returned as a byte array, if it is
false then they are returned as a \fCmmdb_uint128_t\fR integer.
.SS Data Type Macros
This library provides a macro for every data type defined by the MaxMind DB
spec.
.IP "\(bu" 2
\fCMMDB_DATA_TYPE_UTF8_STRING\fR
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 2
\fCMMDB_DATA_TYPE_DOUBLE\fR
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 2
\fCMMDB_DATA_TYPE_BYTES\fR
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 2
\fCMMDB_DATA_TYPE_UINT16\fR
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 2
\fCMMDB_DATA_TYPE_UINT32\fR
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 2
\fCMMDB_DATA_TYPE_MAP\fR
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 2
\fCMMDB_DATA_TYPE_INT32\fR
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 2
\fCMMDB_DATA_TYPE_UINT64\fR
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 2
\fCMMDB_DATA_TYPE_UINT128\fR
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 2
\fCMMDB_DATA_TYPE_ARRAY\fR
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 2
\fCMMDB_DATA_TYPE_BOOLEAN\fR
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 2
\fCMMDB_DATA_TYPE_FLOAT\fR
.LP
There are also a few types that are for internal use only:
.IP "\(bu" 2
\fCMMDB_DATA_TYPE_EXTENDED\fR
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 2
\fCMMDB_DATA_TYPE_POINTER\fR
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 2
\fCMMDB_DATA_TYPE_CONTAINER\fR
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 2
\fCMMDB_DATA_TYPE_END_MARKER\fR
.LP
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.
.SS Pointer Values and \fCMMDB_close()\fR
The \fCutf8_string\fR, \fCbytes\fR, and (maybe) the \fCuint128\fR members of this structure
are all pointers directly into the database's data section. This can either be
a \fCcalloc\fR'd or \fCmmap\fR'd block of memory. In either case, these pointers will
become invalid after \fCMMDB_close()\fR is called.
.PP
If you need to refer to this data after that time you should copy the data
with an appropriate function (\fCstrdup\fR, \fCmemcpy\fR, etc.).
.SS \fCMMDB_entry_data_list_s\fR
This structure encapsulates a linked list of \fCMMDB_entry_data_s\fR structures.
.LP
.EX
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;
.EE
.PP
This structure lets you look at entire map or array data entry by iterating
over the linked list.
.SS \fCMMDB_search_node_s\fR
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.
.LP
.EX
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;
.EE
.PP
The two record types will take one of the following values:
.IP "\(bu" 2
\fCMMDB_RECORD_TYPE_SEARCH_NODE\fR - The record points to the next search node.
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 2
\fCMMDB_RECORD_TYPE_EMPTY\fR - The record is a placeholder that indicates there
is no data for the IP address. The search should end here.
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 2
\fCMMDB_RECORD_TYPE_DATA\fR - 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.
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 2
\fCMMDB_RECORD_TYPE_INVALID\fR - The record is invalid. Either an invalid node
was looked up or the database is corrupt.
.LP
The \fCMMDB_entry_s\fR for the record is only valid if the type is
\fCMMDB_RECORD_TYPE_DATA\fR. Attempts to use an entry for other record types will
result in an error or invalid data.
.SH STATUS CODES
This library returns (or populates) status codes for many functions. These
status codes are:
.IP "\(bu" 2
\fCMMDB_SUCCESS\fR - everything worked
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 2
\fCMMDB_FILE_OPEN_ERROR\fR - there was an error trying to open the MaxMind DB
file.
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 2
\fCMMDB_IO_ERROR\fR - an IO operation failed. Check \fCerrno\fR for more details.
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 2
\fCMMDB_CORRUPT_SEARCH_TREE_ERROR\fR - looking up an IP address in the search
tree gave us an impossible result. The database is damaged or was generated
incorrectly or there is a bug in the libmaxminddb code.
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 2
\fCMMDB_INVALID_METADATA_ERROR\fR - something in the database is wrong. This
includes missing metadata keys as well as impossible values (like an
\fCip_version\fR of 7).
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 2
\fCMMDB_UNKNOWN_DATABASE_FORMAT_ERROR\fR - The database metadata indicates that
it's major version is not 2. This library can only handle major version 2.
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 2
\fCMMDB_OUT_OF_MEMORY_ERROR\fR - a memory allocation call (\fCmalloc\fR, etc.)
failed.
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 2
\fCMMDB_INVALID_DATA_ERROR\fR - an entry in the data section contains invalid
data. For example, a \fCuint16\fR field is claiming to be more than 2 bytes long.
The database is probably damaged or was generated incorrectly.
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 2
\fCMMDB_INVALID_LOOKUP_PATH_ERROR\fR - The lookup path passed to
\fCMMDB_get_value\fR, \fCMMDB_vget_value\fR, or \fCMMDB_aget_value\fR contains an array
offset that is larger than LONG\fIMAX or smaller than LONG\fRMIN.
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "\(bu" 2
\fCMMDB_LOOKUP_PATH_DOES_NOT_MATCH_DATA_ERROR\fR - The lookup path passed to
\fCMMDB_get_value\fR,\fCMMDB_vget_value\fR, or \fCMMDB_aget_value\fR does not match the
data structure for the entry. There are number of reasons this can
happen. The lookup path could include a key not in a map. The lookup path
could include an array index larger than an array or smaller than the
minimum offset from the end of an array. It can also happen when the path
expects to find a map or array where none exist.
.LP
All status codes should be treated as \fCint\fR values.
.SS \fCMMDB_strerror()\fR
.LP
.EX
const char *MMDB_strerror(int error_code)
.EE
.PP
This function takes a status code and returns an English string explaining the
status.
.SH FUNCTIONS
This library provides the following exported functions:
.SS \fCMMDB_open()\fR
.LP
.EX
int MMDB_open(
    const char *const filename,
    uint32_t flags,
    MMDB_s *const mmdb);
.EE
.PP
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.
.LP
.EX
MMDB_s mmdb;
int status =
    MMDB_open(\(dq/path/to/file.mmdb\(dq, MMDB_MODE_MMAP, &mmdb);
if (MMDB_SUCCESS != status) { ... }
\&...
MMDB_close(&mmdb);
.EE
.PP
\fCfilename\fR must be encoded as UTF-8 on Windows.
.PP
The \fCMMDB_s\fR 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 \fCMMDB_close()\fR. If the status returned is not
\fCMMDB_SUCCESS\fR then this library makes sure that all allocated memory is freed
before returning.
.PP
The flags currently provided are:
.IP "\(bu" 2
\fCMMDB_MODE_MMAP\fR - open the database with \fCmmap()\fR.
.LP
Passing in other values for \fCflags\fR 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.
.PP
You can also pass \fC0\fR as the \fCflags\fR 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 \fCMMDB_MODE_MMAP\fR.
.SS \fCMMDB_close()\fR
.LP
.EX
void MMDB_close(MMDB_s *const mmdb);
.EE
.PP
This frees any allocated or mmap'd memory that is held from the \fCMMDB_s\fR
structure. \fIIt does not free the memory allocated for the structure itself!\fR
If you allocated the structure from the heap then you are responsible for
freeing it.
.SS \fCMMDB_lookup_string()\fR
.LP
.EX
MMDB_lookup_result_s MMDB_lookup_string(
    MMDB_s *const mmdb,
    const char *const ipstr,
    int *const gai_error,
    int *const mmdb_error);
.EE
.PP
This function looks up an IP address that is passed in as a null-terminated
string. Internally it calls \fCgetaddrinfo()\fR to resolve the address into a
binary form. It then calls \fCMMDB_lookup_sockaddr()\fR to look the address up in
the database. If you have already resolved an address you can call
\fCMMDB_lookup_sockaddr()\fR directly, rather than resolving the address twice.
.LP
.EX
int gai_error, mmdb_error;
MMDB_lookup_result_s result =
    MMDB_lookup_string(&mmdb, \(dq1.2.3.4\(dq, &gai_error, &mmdb_error);
if (0 != gai_error) { ... }
if (MMDB_SUCCESS != mmdb_error) { ... }

if (result.found_entry) { ... }
.EE
.PP
This function always returns an \fCMMDB_lookup_result_s\fR structure, but you
should also check the \fCgai_error\fR and \fCmmdb_error\fR parameters. If either of
these indicates an error then the returned structure is meaningless.
.PP
If no error occurred you still need to make sure that the \fCfound_entry\fR member
in the returned result is true. If it's not, this means that the IP address
does not have an entry in the database.
.PP
This function will work with IPv4 addresses even when the database contains
data for both IPv4 and IPv6 addresses. The IPv4 address will be looked up as
\&'::xxx.xxx.xxx.xxx' rather than being remapped to the \fC::ffff:xxx.xxx.xxx.xxx\fR
block allocated for IPv4-mapped IPv6 addresses.
.PP
If you pass an IPv6 address to a database with only IPv4 data then the
\fCfound_entry\fR member will be false, but the \fCmmdb_error\fR status will still be
\fCMMDB_SUCCESS\fR.
.SS \fCMMDB_lookup_sockaddr()\fR
.LP
.EX
MMDB_lookup_result_s MMDB_lookup_sockaddr(
    MMDB_s *const mmdb,
    const struct sockaddr *const sockaddr,
    int *const mmdb_error);
.EE
.PP
This function looks up an IP address that has already been resolved by
\fCgetaddrinfo()\fR.
.PP
Other than not calling \fCgetaddrinfo()\fR itself, this function is identical to
the \fCMMDB_lookup_string()\fR function.
.LP
.EX
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) { ... }
.EE
.SS Data Lookup Functions
There are three functions for looking up data associated with an IP address.
.LP
.EX
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);
.EE
.PP
The three functions allow three slightly different calling styles, but they
all do the same thing.
.PP
The first parameter is an \fCMMDB_entry_s\fR value. In most cases this will come
from the \fCMMDB_lookup_result_s\fR value returned by \fCMMDB_lookup_string()\fR or
\fCMMDB_lookup_sockaddr()\fR.
.PP
The second parameter is a reference to an \fCMMDB_entry_data_s\fR structure. This
will be populated with the data that is being looked up, if any is found. If
nothing is found, then the \fChas_data\fR member of this structure will be false.
If \fChas_data\fR is true then you can look at the \fCdata_type\fR member.
.PP
The final parameter is a lookup path. The path consists of a set of strings
representing either map keys (e.g, \(dqcity\(dq) or array indexes (e.g., \(dq0\(dq, \(dq1\(dq,
\(dq-1\(dq) to use in the lookup.
.PP
Negative array indexes will be treated as an offset from the end of the array.
For instance, \(dq-1\(dq refers to the last element of the array.
.PP
The lookup path allows you to navigate a complex data structure. For example,
given this data:
.LP
.EX
{
    \(dqnames\(dq: {
        \(dqen\(dq: \(dqGermany\(dq,
        \(dqde\(dq: \(dqDeutschland\(dq
    },
    \(dqcities\(dq: [ \(dqBerlin\(dq, \(dqFrankfurt\(dq ]
}
.EE
.PP
We could look up the English name with this code:
.LP
.EX
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,
                   \(dqnames\(dq, \(dqen\(dq, NULL);
if (MMDB_SUCCESS != status) { ... }
if (entry_data.has_data) { ... }
.EE
.PP
If we wanted to find the first city the lookup path would be \fC\(dqcities\(dq,
\(dq0\(dq\fR. If you don't provide a lookup path at all, you'll get the entry which
corresponds to the top level map. The lookup path must always end with \fCNULL\fR,
regardless of which function you call.
.PP
The \fCMMDB_get_value\fR function takes a variable number of arguments. All of the
arguments after the \fCMMDB_entry_data_s *\fR structure pointer are the lookup
path. The last argument must be \fCNULL\fR.
.PP
The \fCMMDB_vget_value\fR function accepts a \fCva_list\fR as the lookup path. The
last element retrieved by \fCva_arg()\fR must be \fCNULL\fR.
.PP
Finally, the \fCMMDB_aget_value\fR accepts an array of strings as the lookup
path. The last member of this array must be \fCNULL\fR.
.PP
If you want to get all of the entry data at once you can call
\fCMMDB_get_entry_data_list()\fR instead.
.PP
For each of the three functions, the return value is a status code as
defined above.
.SS \fCMMDB_get_entry_data_list()\fR
.LP
.EX
int MMDB_get_entry_data_list(
    MMDB_entry_s *start,
    MMDB_entry_data_list_s **const entry_data_list);
.EE
.PP
This function allows you to get all of the data for a complex data structure
at once, rather than looking up each piece using repeated calls to
\fCMMDB_get_value()\fR.
.LP
.EX
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);
.EE
.PP
It's up to you to interpret the \fCentry_data_list\fR data structure. The list is
linked in a depth-first traversal. Let's use this structure as an example:
.LP
.EX
{
    \(dqnames\(dq: {
        \(dqen\(dq: \(dqGermany\(dq,
        \(dqde\(dq: \(dqDeutschland\(dq
    },
    \(dqcities\(dq: [ \(dqBerlin\(dq, \(dqFrankfurt\(dq ]
}
.EE
.PP
The list will consist of the following items:
.IP "1.  "
MAP - top level map
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "2.  "
UTF8_STRING - \(dqnames\(dq key
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "3.  "
MAP - map for \(dqnames\(dq key
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "4.  "
UTF8_STRING - \(dqen\(dq key
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "5.  "
UTF8_STRING - value for \(dqen\(dq key
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "6.  "
UTF8_STRING - \(dqde\(dq key
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "7.  "
UTF8_STRING - value for \(dqde\(dq key
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "8.  "
UTF8_STRING - \(dqcities\(dq key
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "9.  "
ARRAY - value for \(dqcities\(dq key
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "10.  "
UTF8_STRING - array[0]
.if n \
.sp -1
.if t \
.sp -0.25v
.IP "11.  "
UTF8_STRING - array[1]
.LP
The return value of the function is a status code as defined above.
.SS \fCMMDB_free_entry_data_list()\fR
.LP
.EX
void MMDB_free_entry_data_list(
    MMDB_entry_data_list_s *const entry_data_list);
.EE
.PP
The \fCMMDB_get_entry_data_list()\fR and \fCMMDB_get_metadata_as_entry_data_list()\fR
functions will allocate the linked list structure from the heap. Call this
function to free the \fCMMDB_entry_data_list_s\fR structure.
.SS \fCMMDB_get_metadata_as_entry_data_list()\fR
.LP
.EX
int MMDB_get_metadata_as_entry_data_list(
    MMDB_s *const mmdb,
    MMDB_entry_data_list_s **const entry_data_list);
.EE
.PP
This function allows you to retrieve the database metadata as a linked list of
\fCMMDB_entry_data_list_s\fR structures. This can be a more convenient way to deal
with the metadata than using the metadata structure directly.
.LP
.EX
    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);
.EE
.PP
The return value of the function is a status code as defined above.
.SS \fCMMDB_dump_entry_data_list()\fR
.LP
.EX
int MMDB_dump_entry_data_list(
    FILE *const stream,
    MMDB_entry_data_list_s *const entry_data_list,
    int indent);
.EE
.PP
This function takes a linked list of \fCMMDB_entry_data_list_s\fR structures and
stringifies it to the given \fCstream\fR. The \fCindent\fR parameter is the starting
indent level for the generated output. It is incremented for nested data
structures (maps, array, etc.).
.PP
The \fCstream\fR must be a file handle (\fCstdout\fR, etc). If your platform provides
something like the GNU \fCopen_memstream()\fR you can use that to capture the
output as a string.
.PP
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 \(dq{}\(dq and \(dq[]\(dq
respectively).
.PP
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.
.PP
The return value of the function is a status code as defined above.
.SS \fCMMDB_read_node()\fR
.LP
.EX
int MMDB_read_node(
    MMDB_s *const mmdb,
    uint32_t node_number,
    MMDB_search_node_s *const node);
.EE
.PP
This reads a specific node in the search tree. The third argument is a
reference to an \fCMMDB_search_node_s\fR structure that will be populated by this
function.
.PP
The return value is a status code. If you pass a \fCnode_number\fR that is greater
than the number of nodes in the database, this function will return
\fCMMDB_INVALID_NODE_NUMBER_ERROR\fR, otherwise it will return \fCMMDB_SUCCESS\fR.
.PP
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 the records that make up this node, based on the type of each
record. If the type is \fCMMDB_RECORD_TYPE_SEARCH_NODE\fR then the record contains
an integer for the next node to look up.
.SS \fCMMDB_lib_version()\fR
.LP
.EX
const char *MMDB_lib_version(void)
.EE
.PP
This function returns the library version as a string, something like \(dq2.0.0\(dq.
.SH EXAMPLE
.LP
.EX
#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, \(dq\en  Can't open %s - %s\en\(dq,
                filename, MMDB_strerror(status));

        if (MMDB_IO_ERROR == status) {
            fprintf(stderr, \(dq    IO error: %s\en\(dq, 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,
                \(dq\en  Error from getaddrinfo for %s - %s\en\en\(dq,
                ip_address, gai_strerror(gai_error));
        exit(2);
    }

    if (MMDB_SUCCESS != mmdb_error) {
        fprintf(stderr,
                \(dq\en  Got an error from libmaxminddb: %s\en\en\(dq,
                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,
                \(dqGot an error looking up the entry data - %s\en\(dq,
                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,
            \(dq\en  No entry for this IP address (%s) was found\en\en\(dq,
            ip_address);
        exit_code = 5;
    }

    end:
        MMDB_free_entry_data_list(entry_data_list);
        MMDB_close(&mmdb);
        exit(exit_code);
}
.EE
.SH THREAD SAFETY
This library is thread safe when compiled and linked with a thread-safe
\fCmalloc\fR and \fCfree\fR implementation.
.SH INSTALLATION AND SOURCE
You can download the latest release of libmaxminddb
\fBfrom GitHub\fR (\fIhttps://github.com/maxmind/libmaxminddb/releases\fR).
.PP
\fBOur GitHub repo\fR (\fIhttps://github.com/maxmind/libmaxminddb\fR) is publicly
available. Please fork it!
.SH BUG REPORTS AND PULL REQUESTS
Please report all issues to
\fBour GitHub issue tracker\fR (\fIhttps://github.com/maxmind/libmaxminddb/issues\fR). We
welcome bug reports and pull requests. Please note that pull requests are
greatly preferred over patches.
.SH AUTHORS
This library was written by Boris Zentner (\fIbzentner@maxmind.com\fR) and Dave
Rolsky (\fIdrolsky@maxmind.com\fR).
.SH COPYRIGHT AND LICENSE
Copyright 2013-2014 MaxMind, Inc.
.PP
Licensed under the Apache License, Version 2.0 (the \(dqLicense\(dq);
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
.LP
.EX
http://www.apache.org/licenses/LICENSE-2.0
.EE
.PP
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an \(dqAS IS\(dq 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.
.SH SEE ALSO
mmdblookup(1)