other versions
- jessie-backports 1.2.0-1~bpo8+1
- stretch 1.2.0-1+b1
- testing 1.3.2-1
- unstable 1.3.2-1
libmaxminddb(3) | libmaxminddb(3) |
NAME¶
libmaxminddb - a library for working with MaxMind DB filesSYNOPSIS¶
-
#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;
DESCRIPTION¶
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 MMDB_open(). You can look up IP addresses as a string with MMDB_lookup_string() or as a pointer to a sockaddr structure with MMDB_lookup_sockaddr(). If the lookup finds the IP address in the database, it returns a MMDB_lookup_result_s 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 MMDB_get_value() and MMDB_get_entry_data_list(). See the function documentation below for more details. When you are done with the database handle you should call MMDB_close(). All publicly visible functions, structures, and macros begin with "MMDB_".DATA STRUCTURES¶
All data structures exported by this library's maxminddb.h header are typedef'd in the form typedef struct foo_s { ... } foo_s so you can refer to them without the struct prefix. This library provides the following data structures:MMDB_s¶
This is the handle for a MaxMind DB file. We only document some of this structure's fields intended for public use. All other fields are subject to change and are intended only for internal use.-
typedef struct MMDB_s { uint32_t flags; const char *filename; ... MMDB_metadata_s metadata; } MMDB_s;
- •
- uint32_t flags - the flags this database was opened with. See the MMDB_open() documentation for more details.
- •
- const char *filename - the name of the file which was opened, as passed to MMDB_open().
- •
- MMDB_metadata_s metadata - the metadata for the database.
MMDB_metadata_s and MMDB_description_s¶
This structure can be retrieved from the MMDB_s structure. It contains the metadata read from the database file. Note that you may find it more convenient to access this metadata by calling MMDB_get_metadata_as_entry_data_list() instead.-
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;
MMDB_lookup_result_s¶
This structure is returned as the result of looking up an IP address.-
typedef struct MMDB_lookup_result_s { bool found_entry; MMDB_entry_s entry; uint16_t netmask; } MMDB_lookup_result_s;
MMDB_result_s¶
You don't really need to dig around in this structure. You'll get this from a MMDB_lookup_result_s structure and pass it to various functions.MMDB_entry_data_s¶
This structure is used to return a single data section entry for an IP. These entries can in turn point to other entries, as is the case for things like maps and arrays. Some members of this structure are not documented as they are only for internal use.-
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;
128-bit Integers¶
The handling of uint128 data depends on how your platform supports 128-bit integers, if it does so at all. With GCC 4.4 and 4.5 we can write unsigned int __attribute__ ((__mode__ (TI))). With newer versions of GCC (4.6+) and clang (3.2+) we can simply write "unsigned __int128". In order to work around these differences, this library defines an mmdb_uint128_t type. This type is defined in the maxminddb.h header so you can use it in your own code. With older compilers, we can't use an integer so we instead use a 16 byte array of uint8_t values. This is the raw data from the database. This library provides a public macro MMDB_UINT128_IS_BYTE_ARRAY macro. If this is true (1), then uint128 values are returned as a byte array, if it is false then they are returned as a mmdb_uint128_t integer.Data Type Macros¶
This library provides a macro for every data type defined by the MaxMind DB spec.- •
- MMDB_DATA_TYPE_UTF8_STRING
- •
- MMDB_DATA_TYPE_DOUBLE
- •
- MMDB_DATA_TYPE_BYTES
- •
- MMDB_DATA_TYPE_UINT16
- •
- MMDB_DATA_TYPE_UINT32
- •
- MMDB_DATA_TYPE_MAP
- •
- MMDB_DATA_TYPE_INT32
- •
- MMDB_DATA_TYPE_UINT64
- •
- MMDB_DATA_TYPE_UINT128
- •
- MMDB_DATA_TYPE_ARRAY
- •
- MMDB_DATA_TYPE_BOOLEAN
- •
- MMDB_DATA_TYPE_FLOAT
- •
- MMDB_DATA_TYPE_EXTENDED
- •
- MMDB_DATA_TYPE_POINTER
- •
- MMDB_DATA_TYPE_CONTAINER
- •
- MMDB_DATA_TYPE_END_MARKER
Pointer Values and MMDB_close()¶
The utf8_string, bytes, and (maybe) the uint128 members of this structure are all pointers directly into the database's data section. This can either be a malloc'd or mmap'd block of memory. In either case, these pointers will become invalid after MMDB_close() is called. If you need to refer to this data after that time you should copy the data with an appropriate function (strdup, memcpy, etc.).MMDB_entry_data_list_s¶
This structure encapsulates a linked list of MMDB_entry_data_s structures.-
typedef struct MMDB_entry_data_list_s { MMDB_entry_data_s entry_data; struct MMDB_entry_data_list_s *next; } MMDB_entry_data_list_s;
MMDB_search_node_s¶
This structure encapsulates the two records in a search node. This is really only useful if you want to write code that iterates over the entire search tree as opposed to looking up a specific IP address.-
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;
- •
- MMDB_RECORD_TYPE_SEARCH_NODE - The record points to the next search node.
- •
- MMDB_RECORD_TYPE_EMPTY - The record is a placeholder that indicates there is no data for the IP address. The search should end here.
- •
- MMDB_RECORD_TYPE_DATA - The record is for data in the data section of the database. Use the entry for the record when looking up the data for the record.
- •
- MMDB_RECORD_TYPE_INVALID - The record is invalid. Either an invalid node was looked up or the database is corrupt.
STATUS CODES¶
This library returns (or populates) status codes for many functions. These status codes are:- •
- MMDB_SUCCESS - everything worked
- •
- MMDB_FILE_OPEN_ERROR - there was an error trying to open the MaxMind DB file.
- •
- MMDB_IO_ERROR - an IO operation failed. Check errno for more details.
- •
- MMDB_CORRUPT_SEARCH_TREE_ERROR - 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.
- •
- MMDB_INVALID_METADATA_ERROR - something in the database is wrong. This includes missing metadata keys as well as impossible values (like an ip_version of 7).
- •
- MMDB_UNKNOWN_DATABASE_FORMAT_ERROR - The database metadata indicates that it's major version is not 2. This library can only handle major version 2.
- •
- MMDB_OUT_OF_MEMORY_ERROR - a memory allocation call (malloc, etc.) failed.
- •
- MMDB_INVALID_DATA_ERROR - an entry in the data section contains invalid data. For example, a uint16 field is claiming to be more than 2 bytes long. The database is probably damaged or was generated incorrectly.
- •
- MMDB_INVALID_LOOKUP_PATH_ERROR - The lookup path passed to MMDB_get_value, MMDB_vget_value, or MMDB_aget_value contains an array offset that is negative integer or an integer larger than LONG_MAX.
- •
- MMDB_LOOKUP_PATH_DOES_NOT_MATCH_DATA_ERROR - The lookup path passed to MMDB_get_value,MMDB_vget_value, or MMDB_aget_value 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. It can also happen when the path expects to find a map or array where none exist.
MMDB_strerror()¶
-
const char *MMDB_strerror(int error_code)
FUNCTIONS¶
This library provides the following exported functions:MMDB_open()¶
-
int MMDB_open( const char *const filename, uint32_t flags, MMDB_s *const mmdb);
-
MMDB_s mmdb; int status = MMDB_open("/path/to/file.mmdb", MMDB_MODE_MMAP, &mmdb); if (MMDB_SUCCESS != status) { ... } ... MMDB_close(&mmdb);
- •
- MMDB_MODE_MMAP - open the database with mmap().
MMDB_close()¶
-
void MMDB_close(MMDB_s *const mmdb);
MMDB_lookup_string()¶
-
MMDB_lookup_result_s MMDB_lookup_string( MMDB_s *const mmdb, const char *const ipstr, int *const gai_error, int *const mmdb_error);
-
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) { ... }
MMDB_lookup_sockaddr()¶
-
MMDB_lookup_result_s MMDB_lookup_sockaddr( MMDB_s *const mmdb, const struct sockaddr *const sockaddr, int *const mmdb_error);
-
int mmdb_error; MMDB_lookup_result_s result = MMDB_lookup_sockaddr(mmdb, address->ai_addr, &mmdb_error); if (MMDB_SUCCESS != mmdb_error) { ... } if (result.found_entry) { ... }
Data Lookup Functions¶
There are three functions for looking up data associated with an IP address.-
int MMDB_get_value( MMDB_entry_s *const start, MMDB_entry_data_s *const entry_data, ...); int MMDB_vget_value( MMDB_entry_s *const start, MMDB_entry_data_s *const entry_data, va_list va_path); int MMDB_aget_value( MMDB_entry_s *const start, MMDB_entry_data_s *const entry_data, const char *const *const path);
-
{ "names": { "en": "Germany", "de": "Deutschland" }, "cities": [ "Berlin", "Frankfurt" ] }
-
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) { ... }
MMDB_get_entry_data_list()¶
-
int MMDB_get_entry_data_list( MMDB_entry_s *start, MMDB_entry_data_list_s **const entry_data_list);
-
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);
-
{ "names": { "en": "Germany", "de": "Deutschland" }, "cities": [ "Berlin", "Frankfurt" ] }
- 1.
- MAP - top level map
- 2.
- UTF8_STRING - "names" key
- 3.
- MAP - map for "names" key
- 4.
- UTF8_STRING - "en" key
- 5.
- UTF8_STRING - value for "en" key
- 6.
- UTF8_STRING - "de" key
- 7.
- UTF8_STRING - value for "de" key
- 8.
- UTF8_STRING - "cities" key
- 9.
- ARRAY - value for "cities" key
- 10.
- UTF8_STRING - array[0]
- 11.
- UTF8_STRING - array[1]
MMDB_free_entry_data_list()¶
-
void MMDB_free_entry_data_list( MMDB_entry_data_list_s *const entry_data_list);
MMDB_get_metadata_as_entry_data_list()¶
-
int MMDB_get_metadata_as_entry_data_list( MMDB_s *const mmdb, MMDB_entry_data_list_s **const entry_data_list);
-
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);
MMDB_dump_entry_data_list()¶
-
int MMDB_dump_entry_data_list( FILE *const stream, MMDB_entry_data_list_s *const entry_data_list, int indent);
MMDB_read_node()¶
-
int MMDB_read_node( MMDB_s *const mmdb, uint32_t node_number, MMDB_search_node_s *const node);
MMDB_lib_version()¶
-
const char *MMDB_lib_version(void)
EXAMPLE¶
-
#include <maxminddb.h> int main(int argc, char **argv) { MMDB_s mmdb; int status = MMDB_open(fname, MMDB_MODE_MMAP, &mmdb); if (MMDB_SUCCESS != status) { fprintf(stderr, "\n Can't open %s - %s\n", fname, 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, ipstr, &gai_error, &mmdb_error); if (0 != gai_error) { fprintf(stderr, "\n Error from getaddrinfo for %s - %s\n\n", ipstr, 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); }