Current File : //opt/alt/libmaxminddb/usr/share/man/man3/libmaxminddb.3
.\" Automatically generated by Pandoc 1.19.2.4
.\"
.TH "libmaxminddb" "3" "" "" ""
.hy
.SH NAME
.PP
libmaxminddb \- a library for working with MaxMind DB files
.SH SYNOPSIS
.IP "" 4
.nf
\f[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);
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;
\f[]
.fi
.SH DESCRIPTION
.PP
The libmaxminddb library provides functions for working MaxMind DB
files.
See http://maxmind.github.io/MaxMind\-DB/ for the MaxMind DB format
specification.
The database and results are all represented by different data
structures.
Databases are opened by calling \f[C]MMDB_open()\f[].
You can look up IP addresses as a string with
\f[C]MMDB_lookup_string()\f[] or as a pointer to a \f[C]sockaddr\f[]
structure with \f[C]MMDB_lookup_sockaddr()\f[].
.PP
If the lookup finds the IP address in the database, it returns a
\f[C]MMDB_lookup_result_s\f[] 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 \f[C]MMDB_get_value()\f[] and
\f[C]MMDB_get_entry_data_list()\f[].
See the function documentation below for more details.
.PP
When you are done with the database handle you should call
\f[C]MMDB_close()\f[].
.PP
All publicly visible functions, structures, and macros begin with
"MMDB_".
.SH DATA STRUCTURES
.PP
All data structures exported by this library\[aq]s \f[C]maxminddb.h\f[]
header are typedef\[aq]d in the form
\f[C]typedef\ struct\ foo_s\ {\ ...\ }\ foo_s\f[] so you can refer to
them without the \f[C]struct\f[] prefix.
.PP
This library provides the following data structures:
.SS \f[C]MMDB_s\f[]
.PP
This is the handle for a MaxMind DB file.
We only document some of this structure\[aq]s fields intended for public
use.
All other fields are subject to change and are intended only for
internal use.
.IP "" 4
.nf
\f[C]
typedef\ struct\ MMDB_s\ {
\ \ \ \ uint32_t\ flags;
\ \ \ \ const\ char\ *filename;
\ \ \ \ ...
\ \ \ \ MMDB_metadata_s\ metadata;
}\ MMDB_s;
\f[]
.fi
.IP \[bu] 2
\f[C]uint32_t\ flags\f[] \- the flags this database was opened with.
See the \f[C]MMDB_open()\f[] documentation for more details.
.IP \[bu] 2
\f[C]const\ char\ *filename\f[] \- the name of the file which was
opened, as passed to \f[C]MMDB_open()\f[].
.IP \[bu] 2
\f[C]MMDB_metadata_s\ metadata\f[] \- the metadata for the database.
.SS \f[C]MMDB_metadata_s\f[] and \f[C]MMDB_description_s\f[]
.PP
This structure can be retrieved from the \f[C]MMDB_s\f[] structure.
It contains the metadata read from the database file.
Note that you may find it more convenient to access this metadata by
calling \f[C]MMDB_get_metadata_as_entry_data_list()\f[] instead.
.IP "" 4
.nf
\f[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;
typedef\ struct\ MMDB_description_s\ {
\ \ \ \ const\ char\ *language;
\ \ \ \ const\ char\ *description;
}\ MMDB_description_s;
\f[]
.fi
.PP
These structures should be mostly self\-explanatory.
.PP
The \f[C]ip_version\f[] member should always be \f[C]4\f[] or
\f[C]6\f[].
The \f[C]binary_format_major_version\f[] should always be \f[C]2\f[].
.PP
There is no requirement that the database metadata include languages or
descriptions, so the \f[C]count\f[] for these parts of the metadata can
be zero.
All of the other \f[C]MMDB_metadata_s\f[] fields should be populated.
.SS \f[C]MMDB_lookup_result_s\f[]
.PP
This structure is returned as the result of looking up an IP address.
.IP "" 4
.nf
\f[C]
typedef\ struct\ MMDB_lookup_result_s\ {
\ \ \ \ bool\ found_entry;
\ \ \ \ MMDB_entry_s\ entry;
\ \ \ \ uint16_t\ netmask;
}\ MMDB_lookup_result_s;
\f[]
.fi
.PP
If the \f[C]found_entry\f[] member is false then the other members of
this structure do not contain meaningful values.
Always check that \f[C]found_entry\f[] is true first.
.PP
The \f[C]entry\f[] member is used to look up the data associated with
the IP address.
.PP
The \f[C]netmask\f[] member tells you what subnet the IP address belongs
to in this database.
For example, if you look up the address \f[C]1.1.1.1\f[] in an IPv4
database and the returned \f[C]netmask\f[] is 16, then the address is
part of the \f[C]1.1.0.0/16\f[] 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 \f[I]also\f[]
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 \f[C]96\f[] from the
value.
.SS \f[C]MMDB_result_s\f[]
.PP
You don\[aq]t really need to dig around in this structure.
You\[aq]ll get this from a \f[C]MMDB_lookup_result_s\f[] structure and
pass it to various functions.
.SS \f[C]MMDB_entry_data_s\f[]
.PP
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.
.IP "" 4
.nf
\f[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;
\f[]
.fi
.PP
The \f[C]has_data\f[] member is true if data was found for a given
lookup.
See \f[C]MMDB_get_value()\f[] 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
\f[C]type\f[] member.
The \f[C]pointer\f[] member of the union should never be populated in
any data returned by the API.
Pointers should always be resolved internally.
.PP
The \f[C]data_size\f[] member is only relevant for \f[C]utf8_string\f[]
and \f[C]bytes\f[] data.
\f[C]utf8_string\f[] is not null terminated and \f[C]data_size\f[]
\f[I]must\f[] be used to determine its length.
.PP
The \f[C]type\f[] member can be compared to one of the
\f[C]MMDB_DTYPE_*\f[] macros.
.SS 128\-bit Integers
.PP
The handling of \f[C]uint128\f[] 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
\f[C]unsigned\ int\ __attribute__\ ((__mode__\ (TI)))\f[].
With newer versions of GCC (4.6+) and clang (3.2+) we can simply write
"unsigned __int128".
.PP
In order to work around these differences, this library defines an
\f[C]mmdb_uint128_t\f[] type.
This type is defined in the \f[C]maxminddb.h\f[] header so you can use
it in your own code.
.PP
With older compilers, we can\[aq]t use an integer so we instead use a 16
byte array of \f[C]uint8_t\f[] values.
This is the raw data from the database.
.PP
This library provides a public macro \f[C]MMDB_UINT128_IS_BYTE_ARRAY\f[]
macro.
If this is true (1), then \f[C]uint128\f[] values are returned as a byte
array, if it is false then they are returned as a
\f[C]mmdb_uint128_t\f[] integer.
.SS Data Type Macros
.PP
This library provides a macro for every data type defined by the MaxMind
DB spec.
.IP \[bu] 2
\f[C]MMDB_DATA_TYPE_UTF8_STRING\f[]
.IP \[bu] 2
\f[C]MMDB_DATA_TYPE_DOUBLE\f[]
.IP \[bu] 2
\f[C]MMDB_DATA_TYPE_BYTES\f[]
.IP \[bu] 2
\f[C]MMDB_DATA_TYPE_UINT16\f[]
.IP \[bu] 2
\f[C]MMDB_DATA_TYPE_UINT32\f[]
.IP \[bu] 2
\f[C]MMDB_DATA_TYPE_MAP\f[]
.IP \[bu] 2
\f[C]MMDB_DATA_TYPE_INT32\f[]
.IP \[bu] 2
\f[C]MMDB_DATA_TYPE_UINT64\f[]
.IP \[bu] 2
\f[C]MMDB_DATA_TYPE_UINT128\f[]
.IP \[bu] 2
\f[C]MMDB_DATA_TYPE_ARRAY\f[]
.IP \[bu] 2
\f[C]MMDB_DATA_TYPE_BOOLEAN\f[]
.IP \[bu] 2
\f[C]MMDB_DATA_TYPE_FLOAT\f[]
.PP
There are also a few types that are for internal use only:
.IP \[bu] 2
\f[C]MMDB_DATA_TYPE_EXTENDED\f[]
.IP \[bu] 2
\f[C]MMDB_DATA_TYPE_POINTER\f[]
.IP \[bu] 2
\f[C]MMDB_DATA_TYPE_CONTAINER\f[]
.IP \[bu] 2
\f[C]MMDB_DATA_TYPE_END_MARKER\f[]
.PP
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 \f[C]MMDB_close()\f[]
.PP
The \f[C]utf8_string\f[], \f[C]bytes\f[], and (maybe) the
\f[C]uint128\f[] members of this structure are all pointers directly
into the database\[aq]s data section.
This can either be a \f[C]malloc\f[]\[aq]d or \f[C]mmap\f[]\[aq]d block
of memory.
In either case, these pointers will become invalid after
\f[C]MMDB_close()\f[] is called.
.PP
If you need to refer to this data after that time you should copy the
data with an appropriate function (\f[C]strdup\f[], \f[C]memcpy\f[],
etc.).
.SS \f[C]MMDB_entry_data_list_s\f[]
.PP
This structure encapsulates a linked list of \f[C]MMDB_entry_data_s\f[]
structures.
.IP "" 4
.nf
\f[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;
\f[]
.fi
.PP
This structure lets you look at entire map or array data entry by
iterating over the linked list.
.SS \f[C]MMDB_search_node_s\f[]
.PP
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.
.IP "" 4
.nf
\f[C]
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;
\f[]
.fi
.PP
The two record types will take one of the following values:
.IP \[bu] 2
\f[C]MMDB_RECORD_TYPE_SEARCH_NODE\f[] \- The record points to the next
search node.
.IP \[bu] 2
\f[C]MMDB_RECORD_TYPE_EMPTY\f[] \- The record is a placeholder that
indicates there is no data for the IP address.
The search should end here.
.IP \[bu] 2
\f[C]MMDB_RECORD_TYPE_DATA\f[] \- 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.
.IP \[bu] 2
\f[C]MMDB_RECORD_TYPE_INVALID\f[] \- The record is invalid.
Either an invalid node was looked up or the database is corrupt.
.PP
The \f[C]MMDB_entry_s\f[] for the record is only valid if the type is
\f[C]MMDB_RECORD_TYPE_DATA\f[].
Attempts to use an entry for other record types will result in an error
or invalid data.
.SH STATUS CODES
.PP
This library returns (or populates) status codes for many functions.
These status codes are:
.IP \[bu] 2
\f[C]MMDB_SUCCESS\f[] \- everything worked
.IP \[bu] 2
\f[C]MMDB_FILE_OPEN_ERROR\f[] \- there was an error trying to open the
MaxMind DB file.
.IP \[bu] 2
\f[C]MMDB_IO_ERROR\f[] \- an IO operation failed.
Check \f[C]errno\f[] for more details.
.IP \[bu] 2
\f[C]MMDB_CORRUPT_SEARCH_TREE_ERROR\f[] \- 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.
.IP \[bu] 2
\f[C]MMDB_INVALID_METADATA_ERROR\f[] \- something in the database is
wrong.
This includes missing metadata keys as well as impossible values (like
an \f[C]ip_version\f[] of 7).
.IP \[bu] 2
\f[C]MMDB_UNKNOWN_DATABASE_FORMAT_ERROR\f[] \- The database metadata
indicates that it\[aq]s major version is not 2.
This library can only handle major version 2.
.IP \[bu] 2
\f[C]MMDB_OUT_OF_MEMORY_ERROR\f[] \- a memory allocation call
(\f[C]malloc\f[], etc.) failed.
.IP \[bu] 2
\f[C]MMDB_INVALID_DATA_ERROR\f[] \- an entry in the data section
contains invalid data.
For example, a \f[C]uint16\f[] field is claiming to be more than 2 bytes
long.
The database is probably damaged or was generated incorrectly.
.IP \[bu] 2
\f[C]MMDB_INVALID_LOOKUP_PATH_ERROR\f[] \- The lookup path passed to
\f[C]MMDB_get_value\f[], \f[C]MMDB_vget_value\f[], or
\f[C]MMDB_aget_value\f[] contains an array offset that is larger than
LONG_MAX or smaller than LONG_MIN.
.IP \[bu] 2
\f[C]MMDB_LOOKUP_PATH_DOES_NOT_MATCH_DATA_ERROR\f[] \- The lookup path
passed to \f[C]MMDB_get_value\f[],\f[C]MMDB_vget_value\f[], or
\f[C]MMDB_aget_value\f[] 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.
.PP
All status codes should be treated as \f[C]int\f[] values.
.SS \f[C]MMDB_strerror()\f[]
.IP "" 4
.nf
\f[C]
const\ char\ *MMDB_strerror(int\ error_code)
\f[]
.fi
.PP
This function takes a status code and returns an English string
explaining the status.
.SH FUNCTIONS
.PP
This library provides the following exported functions:
.SS \f[C]MMDB_open()\f[]
.IP "" 4
.nf
\f[C]
int\ MMDB_open(
\ \ \ \ const\ char\ *const\ filename,
\ \ \ \ uint32_t\ flags,
\ \ \ \ MMDB_s\ *const\ mmdb);
\f[]
.fi
.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\[aq]s return value.
.IP "" 4
.nf
\f[C]
MMDB_s\ mmdb;
int\ status\ =
\ \ \ \ MMDB_open("/path/to/file.mmdb",\ MMDB_MODE_MMAP,\ &mmdb);
if\ (MMDB_SUCCESS\ !=\ status)\ {\ ...\ }
\&...
MMDB_close(&mmdb);
\f[]
.fi
.PP
\f[C]filename\f[] must be encoded as UTF\-8 on Windows.
.PP
The \f[C]MMDB_s\f[] 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 \f[C]MMDB_close()\f[].
If the status returned is not \f[C]MMDB_SUCCESS\f[] then this library
makes sure that all allocated memory is freed before returning.
.PP
The flags currently provided are:
.IP \[bu] 2
\f[C]MMDB_MODE_MMAP\f[] \- open the database with \f[C]mmap()\f[].
.PP
Passing in other values for \f[C]flags\f[] 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 \f[C]0\f[] as the \f[C]flags\f[] 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 \f[C]MMDB_MODE_MMAP\f[].
.SS \f[C]MMDB_close()\f[]
.IP "" 4
.nf
\f[C]
void\ MMDB_close(MMDB_s\ *const\ mmdb);
\f[]
.fi
.PP
This frees any allocated or mmap\[aq]d memory that is held from the
\f[C]MMDB_s\f[] structure.
\f[I]It does not free the memory allocated for the structure itself!\f[]
If you allocated the structure from the heap then you are responsible
for freeing it.
.SS \f[C]MMDB_lookup_string()\f[]
.IP "" 4
.nf
\f[C]
MMDB_lookup_result_s\ MMDB_lookup_string(
\ \ \ \ MMDB_s\ *const\ mmdb,
\ \ \ \ const\ char\ *const\ ipstr,
\ \ \ \ int\ *const\ gai_error,
\ \ \ \ int\ *const\ mmdb_error);
\f[]
.fi
.PP
This function looks up an IP address that is passed in as a
null\-terminated string.
Internally it calls \f[C]getaddrinfo()\f[] to resolve the address into a
binary form.
It then calls \f[C]MMDB_lookup_sockaddr()\f[] to look the address up in
the database.
If you have already resolved an address you can call
\f[C]MMDB_lookup_sockaddr()\f[] directly, rather than resolving the
address twice.
.IP "" 4
.nf
\f[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)\ {\ ...\ }
\f[]
.fi
.PP
This function always returns an \f[C]MMDB_lookup_result_s\f[] structure,
but you should also check the \f[C]gai_error\f[] and \f[C]mmdb_error\f[]
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
\f[C]found_entry\f[] member in the returned result is true.
If it\[aq]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 \[aq]::xxx.xxx.xxx.xxx\[aq] rather
than being remapped to the \f[C]::ffff:xxx.xxx.xxx.xxx\f[] block
allocated for IPv4\-mapped IPv6 addresses.
.PP
If you pass an IPv6 address to a database with only IPv4 data then the
\f[C]found_entry\f[] member will be false, but the \f[C]mmdb_error\f[]
status will still be \f[C]MMDB_SUCCESS\f[].
.SS \f[C]MMDB_lookup_sockaddr()\f[]
.IP "" 4
.nf
\f[C]
MMDB_lookup_result_s\ MMDB_lookup_sockaddr(
\ \ \ \ MMDB_s\ *const\ mmdb,
\ \ \ \ const\ struct\ sockaddr\ *const\ sockaddr,
\ \ \ \ int\ *const\ mmdb_error);
\f[]
.fi
.PP
This function looks up an IP address that has already been resolved by
\f[C]getaddrinfo()\f[].
.PP
Other than not calling \f[C]getaddrinfo()\f[] itself, this function is
identical to the \f[C]MMDB_lookup_string()\f[] function.
.IP "" 4
.nf
\f[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)\ {\ ...\ }
\f[]
.fi
.SS Data Lookup Functions
.PP
There are three functions for looking up data associated with an IP
address.
.IP "" 4
.nf
\f[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);
\f[]
.fi
.PP
The three functions allow three slightly different calling styles, but
they all do the same thing.
.PP
The first parameter is an \f[C]MMDB_entry_s\f[] value.
In most cases this will come from the \f[C]MMDB_lookup_result_s\f[]
value returned by \f[C]MMDB_lookup_string()\f[] or
\f[C]MMDB_lookup_sockaddr()\f[].
.PP
The second parameter is a reference to an \f[C]MMDB_entry_data_s\f[]
structure.
This will be populated with the data that is being looked up, if any is
found.
If nothing is found, then the \f[C]has_data\f[] member of this structure
will be false.
If \f[C]has_data\f[] is true then you can look at the \f[C]data_type\f[]
member.
.PP
The final parameter is a lookup path.
The path consists of a set of strings representing either map keys (e.g,
"city") or array indexes (e.g., "0", "1", "\-1") to use in the lookup.
.PP
Negative array indexes will be treated as an offset from the end of the
array.
For instance, "\-1" 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:
.IP "" 4
.nf
\f[C]
{
\ \ \ \ "names":\ {
\ \ \ \ \ \ \ \ "en":\ "Germany",
\ \ \ \ \ \ \ \ "de":\ "Deutschland"
\ \ \ \ },
\ \ \ \ "cities":\ [\ "Berlin",\ "Frankfurt"\ ]
}
\f[]
.fi
.PP
We could look up the English name with this code:
.IP "" 4
.nf
\f[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)\ {\ ...\ }
\f[]
.fi
.PP
If we wanted to find the first city the lookup path would be
\f[C]"cities",\ "0"\f[].
If you don\[aq]t provide a lookup path at all, you\[aq]ll get the entry
which corresponds to the top level map.
The lookup path must always end with \f[C]NULL\f[], regardless of which
function you call.
.PP
The \f[C]MMDB_get_value\f[] function takes a variable number of
arguments.
All of the arguments after the \f[C]MMDB_entry_data_s\ *\f[] structure
pointer are the lookup path.
The last argument must be \f[C]NULL\f[].
.PP
The \f[C]MMDB_vget_value\f[] function accepts a \f[C]va_list\f[] as the
lookup path.
The last element retrieved by \f[C]va_arg()\f[] must be \f[C]NULL\f[].
.PP
Finally, the \f[C]MMDB_aget_value\f[] accepts an array of strings as the
lookup path.
The last member of this array must be \f[C]NULL\f[].
.PP
If you want to get all of the entry data at once you can call
\f[C]MMDB_get_entry_data_list()\f[] instead.
.PP
For each of the three functions, the return value is a status code as
defined above.
.SS \f[C]MMDB_get_entry_data_list()\f[]
.IP "" 4
.nf
\f[C]
int\ MMDB_get_entry_data_list(
\ \ \ \ MMDB_entry_s\ *start,
\ \ \ \ MMDB_entry_data_list_s\ **const\ entry_data_list);
\f[]
.fi
.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 \f[C]MMDB_get_value()\f[].
.IP "" 4
.nf
\f[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);
\f[]
.fi
.PP
It\[aq]s up to you to interpret the \f[C]entry_data_list\f[] data
structure.
The list is linked in a depth\-first traversal.
Let\[aq]s use this structure as an example:
.IP "" 4
.nf
\f[C]
{
\ \ \ \ "names":\ {
\ \ \ \ \ \ \ \ "en":\ "Germany",
\ \ \ \ \ \ \ \ "de":\ "Deutschland"
\ \ \ \ },
\ \ \ \ "cities":\ [\ "Berlin",\ "Frankfurt"\ ]
}
\f[]
.fi
.PP
The list will consist of the following items:
.IP " 1." 4
MAP \- top level map
.IP " 2." 4
UTF8_STRING \- "names" key
.IP " 3." 4
MAP \- map for "names" key
.IP " 4." 4
UTF8_STRING \- "en" key
.IP " 5." 4
UTF8_STRING \- value for "en" key
.IP " 6." 4
UTF8_STRING \- "de" key
.IP " 7." 4
UTF8_STRING \- value for "de" key
.IP " 8." 4
UTF8_STRING \- "cities" key
.IP " 9." 4
ARRAY \- value for "cities" key
.IP "10." 4
UTF8_STRING \- array[0]
.IP "11." 4
UTF8_STRING \- array[1]
.PP
The return value of the function is a status code as defined above.
.SS \f[C]MMDB_free_entry_data_list()\f[]
.IP "" 4
.nf
\f[C]
void\ MMDB_free_entry_data_list(
\ \ \ \ MMDB_entry_data_list_s\ *const\ entry_data_list);
\f[]
.fi
.PP
The \f[C]MMDB_get_entry_data_list()\f[] and
\f[C]MMDB_get_metadata_as_entry_data_list()\f[] functions will allocate
the linked list structure from the heap.
Call this function to free the \f[C]MMDB_entry_data_list_s\f[]
structure.
.SS \f[C]MMDB_get_metadata_as_entry_data_list()\f[]
.IP "" 4
.nf
\f[C]
int\ MMDB_get_metadata_as_entry_data_list(
\ \ \ \ MMDB_s\ *const\ mmdb,
\ \ \ \ MMDB_entry_data_list_s\ **const\ entry_data_list);
\f[]
.fi
.PP
This function allows you to retrieve the database metadata as a linked
list of \f[C]MMDB_entry_data_list_s\f[] structures.
This can be a more convenient way to deal with the metadata than using
the metadata structure directly.
.IP "" 4
.nf
\f[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);
\f[]
.fi
.PP
The return value of the function is a status code as defined above.
.SS \f[C]MMDB_dump_entry_data_list()\f[]
.IP "" 4
.nf
\f[C]
int\ MMDB_dump_entry_data_list(
\ \ \ \ FILE\ *const\ stream,
\ \ \ \ MMDB_entry_data_list_s\ *const\ entry_data_list,
\ \ \ \ int\ indent);
\f[]
.fi
.PP
This function takes a linked list of \f[C]MMDB_entry_data_list_s\f[]
structures and stringifies it to the given \f[C]stream\f[].
The \f[C]indent\f[] parameter is the starting indent level for the
generated output.
It is incremented for nested data structures (maps, array, etc.).
.PP
The \f[C]stream\f[] must be a file handle (\f[C]stdout\f[], etc).
If your platform provides something like the GNU
\f[C]open_memstream()\f[] 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
"{}" and "[]" 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 \f[C]MMDB_read_node()\f[]
.IP "" 4
.nf
\f[C]
int\ MMDB_read_node(
\ \ \ \ MMDB_s\ *const\ mmdb,
\ \ \ \ uint32_t\ node_number,
\ \ \ \ MMDB_search_node_s\ *const\ node);
\f[]
.fi
.PP
This reads a specific node in the search tree.
The third argument is a reference to an \f[C]MMDB_search_node_s\f[]
structure that will be populated by this function.
.PP
The return value is a status code.
If you pass a \f[C]node_number\f[] that is greater than the number of
nodes in the database, this function will return
\f[C]MMDB_INVALID_NODE_NUMBER_ERROR\f[], otherwise it will return
\f[C]MMDB_SUCCESS\f[].
.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 \f[C]MMDB_RECORD_TYPE_SEARCH_NODE\f[] then the record
contains an integer for the next node to look up.
.SS \f[C]MMDB_lib_version()\f[]
.IP "" 4
.nf
\f[C]
const\ char\ *MMDB_lib_version(void)
\f[]
.fi
.PP
This function returns the library version as a string, something like
"2.0.0".
.SH EXAMPLE
.IP "" 4
.nf
\f[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\[aq]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);
}
\f[]
.fi
.SH THREAD SAFETY
.PP
This library is thread safe when compiled and linked with a thread\-safe
\f[C]malloc\f[] and \f[C]free\f[] implementation.
.SH INSTALLATION AND SOURCE
.PP
You can download the latest release of libmaxminddb from
GitHub (https://github.com/maxmind/libmaxminddb/releases).
.PP
Our GitHub repo (https://github.com/maxmind/libmaxminddb) is publicly
available.
Please fork it!
.SH BUG REPORTS AND PULL REQUESTS
.PP
Please report all issues to our GitHub issue
tracker (https://github.com/maxmind/libmaxminddb/issues).
We welcome bug reports and pull requests.
Please note that pull requests are greatly preferred over patches.
.SH AUTHORS
.PP
This library was written by Boris Zentner (bzentner\@maxmind.com) and
Dave Rolsky (drolsky\@maxmind.com).
.SH COPYRIGHT AND LICENSE
.PP
Copyright 2013\-2014 MaxMind, Inc.
.PP
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
.IP "" 4
.nf
\f[C]
http://www.apache.org/licenses/LICENSE\-2.0
\f[]
.fi
.PP
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.
.SH SEE ALSO
.PP
mmdblookup(1)
Mini Shell