1libmaxminddb(3)                                                libmaxminddb(3)
2
3
4

NAME

6       libmaxminddb - a library for working with MaxMind DB files
7

SYNOPSIS

9
10           #include <maxminddb.h>
11
12           int MMDB_open(
13               const char *const filename,
14               uint32_t flags,
15               MMDB_s *const mmdb);
16           void MMDB_close(MMDB_s *const mmdb);
17
18           MMDB_lookup_result_s MMDB_lookup_string(
19               MMDB_s *const mmdb,
20               const char *const ipstr,
21               int *const gai_error,
22               int *const mmdb_error);
23           MMDB_lookup_result_s MMDB_lookup_sockaddr(
24               MMDB_s *const mmdb,
25               const struct sockaddr *const
26               sockaddr,
27               int *const mmdb_error);
28
29           int MMDB_get_value(
30               MMDB_entry_s *const start,
31               MMDB_entry_data_s *const entry_data,
32               ...);
33           int MMDB_vget_value(
34               MMDB_entry_s *const start,
35               MMDB_entry_data_s *const entry_data,
36               va_list va_path);
37           int MMDB_aget_value(
38               MMDB_entry_s *const start,
39               MMDB_entry_data_s *const entry_data,
40               const char *const *const path);
41
42           int MMDB_get_entry_data_list(
43               MMDB_entry_s *start,
44               MMDB_entry_data_list_s **const entry_data_list);
45           void MMDB_free_entry_data_list(
46               MMDB_entry_data_list_s *const entry_data_list);
47           int MMDB_get_metadata_as_entry_data_list(
48               MMDB_s *const mmdb,
49               MMDB_entry_data_list_s **const entry_data_list);
50           int MMDB_dump_entry_data_list(
51               FILE *const stream,
52               MMDB_entry_data_list_s *const entry_data_list,
53               int indent);
54
55           int MMDB_read_node(
56               MMDB_s *const mmdb,
57               uint32_t node_number,
58               MMDB_search_node_s *const node);
59
60           const char *MMDB_lib_version(void);
61           const char *MMDB_strerror(int error_code);
62
63           typedef struct MMDB_lookup_result_s {
64               bool found_entry;
65               MMDB_entry_s entry;
66               uint16_t netmask;
67           } MMDB_lookup_result_s;
68
69           typedef struct MMDB_entry_data_s {
70               bool has_data;
71               union {
72                   uint32_t pointer;
73                   const char *utf8_string;
74                   double double_value;
75                   const uint8_t *bytes;
76                   uint16_t uint16;
77                   uint32_t uint32;
78                   int32_t int32;
79                   uint64_t uint64;
80                   {mmdb_uint128_t or uint8_t[16]} uint128;
81                   bool boolean;
82                   float float_value;
83               };
84               ...
85               uint32_t data_size;
86               uint32_t type;
87           } MMDB_entry_data_s;
88
89           typedef struct MMDB_entry_data_list_s {
90               MMDB_entry_data_s entry_data;
91               struct MMDB_entry_data_list_s *next;
92           } MMDB_entry_data_list_s;
93

DESCRIPTION

95       The  libmaxminddb  library  provides  functions  for working MaxMind DB
96       files.  See https://maxmind.github.io/MaxMind-DB/ for  the  MaxMind  DB
97       format  specification.  The database and results are all represented by
98       different  data  structures.    Databases   are   opened   by   calling
99       MMDB_open().    You   can  look  up  IP  addresses  as  a  string  with
100       MMDB_lookup_string() or as a  pointer  to  a  sockaddr  structure  with
101       MMDB_lookup_sockaddr().
102
103       If  the  lookup  finds  the  IP  address  in the database, it returns a
104       MMDB_lookup_result_s structure.  If that structure indicates  that  the
105       database  has data for the IP, there are a number of functions that can
106       be used  to  fetch  that  data.   These  include  MMDB_get_value()  and
107       MMDB_get_entry_data_list().   See  the function documentation below for
108       more details.
109
110       When  you  are  done  with  the  database  handle   you   should   call
111       MMDB_close().
112
113       All  publicly  visible  functions,  structures,  and  macros begin with
114       "MMDB_".
115

DATA STRUCTURES

117       All data structures exported by this library's maxminddb.h  header  are
118       typedef'd in the form typedef struct foo_s { ... } foo_s so you can re‐
119       fer to them without the struct prefix.
120
121       This library provides the following data structures:
122
123   MMDB_s
124       This is the handle for a MaxMind DB file.  We  only  document  some  of
125       this  structure's fields intended for public use.  All other fields are
126       subject to change and are intended only for internal use.
127
128
129           typedef struct MMDB_s {
130               uint32_t flags;
131               const char *filename;
132               ...
133               MMDB_metadata_s metadata;
134           } MMDB_s;
135
136       • uint32_t flags - the flags this database was opened  with.   See  the
137         MMDB_open() documentation for more details.
138
139       • const  char  *filename  -  the  name of the file which was opened, as
140         passed to MMDB_open().
141
142       • MMDB_metadata_s metadata - the metadata for the database.
143
144   MMDB_metadata_s and MMDB_description_s
145       This structure can be retrieved from the MMDB_s structure.  It contains
146       the  metadata  read  from the database file.  Note that you may find it
147       more convenient to access this  metadata  by  calling  MMDB_get_metada‐
148       ta_as_entry_data_list() instead.
149
150
151           typedef struct MMDB_metadata_s {
152               uint32_t node_count;
153               uint16_t record_size;
154               uint16_t ip_version;
155               const char *database_type;
156               struct {
157                   size_t count;
158                   const char **names;
159               } languages;
160               uint16_t binary_format_major_version;
161               uint16_t binary_format_minor_version;
162               uint64_t build_epoch;
163               struct {
164                   size_t count;
165                   MMDB_description_s **descriptions;
166               } description;
167           } MMDB_metadata_s;
168
169           typedef struct MMDB_description_s {
170               const char *language;
171               const char *description;
172           } MMDB_description_s;
173
174       These structures should be mostly self-explanatory.
175
176       The  ip_version  member should always be 4 or 6.  The binary_format_ma‐
177       jor_version should always be 2.
178
179       There is no requirement that the database metadata include languages or
180       descriptions, so the count for these parts of the metadata can be zero.
181       All of the other MMDB_metadata_s fields should be populated.
182
183   MMDB_lookup_result_s
184       This structure is returned as the result of looking up an IP address.
185
186
187           typedef struct MMDB_lookup_result_s {
188               bool found_entry;
189               MMDB_entry_s entry;
190               uint16_t netmask;
191           } MMDB_lookup_result_s;
192
193       If the found_entry member is false  then  the  other  members  of  this
194       structure   do  not  contain  meaningful  values.   Always  check  that
195       found_entry is true first.
196
197       The entry member is used to look up the data associated with the IP ad‐
198       dress.
199
200       The  netmask  member tells you what subnet the IP address belongs to in
201       this database.  For example, if you look up the address 1.1.1.1  in  an
202       IPv4  database and the returned netmask is 16, then the address is part
203       of the 1.1.0.0/16 subnet.
204
205       If the database is an IPv6 database, the returned netmask is always  an
206       IPv6  prefix  length  (from 0-128), even if that database also contains
207       IPv4 networks.  If you look up an IPv4 address and would like  to  turn
208       the netmask into an IPv4 netmask value, you can simply subtract 96 from
209       the value.
210
211   MMDB_result_s
212       You don't really need to dig around in this structure.  You'll get this
213       from a MMDB_lookup_result_s structure and pass it to various functions.
214
215   MMDB_entry_data_s
216       This structure is used to return a single data section entry for an IP.
217       These entries can in turn point to other entries, as is  the  case  for
218       things  like  maps  and arrays.  Some members of this structure are not
219       documented as they are only for internal use.
220
221
222           typedef struct MMDB_entry_data_s {
223               bool has_data;
224               union {
225                   uint32_t pointer;
226                   const char *utf8_string;
227                   double double_value;
228                   const uint8_t *bytes;
229                   uint16_t uint16;
230                   uint32_t uint32;
231                   int32_t int32;
232                   uint64_t uint64;
233                   {mmdb_uint128_t or uint8_t[16]} uint128;
234                   bool boolean;
235                   float float_value;
236               };
237               ...
238               uint32_t data_size;
239               uint32_t type;
240           } MMDB_entry_data_s;
241
242       The has_data member is true if data was found for a given lookup.   See
243       MMDB_get_value()  for  more details.  If this member is false then none
244       of the other values in the structure are meaningful.
245
246       The union at the beginning of the structure defines  the  actual  data.
247       To  determine  which  union  member is populated you should look at the
248       type member.  The pointer member of the union should never be populated
249       in  any  data  returned by the API.  Pointers should always be resolved
250       internally.
251
252       The data_size member is only relevant for utf8_string and  bytes  data.
253       utf8_string is not null terminated and data_size must be used to deter‐
254       mine its length.
255
256       The type member can be compared to one of the MMDB_DATA_TYPE_* macros.
257
258   128-bit Integers
259       The handling of uint128 data depends  on  how  your  platform  supports
260       128-bit  integers,  if  it does so at all.  With GCC 4.4 and 4.5 we can
261       write unsigned int __attribute__ ((__mode__ (TI))).   With  newer  ver‐
262       sions  of  GCC  (4.6+)  and  clang (3.2+) we can simply write "unsigned
263       __int128".
264
265       In order to work around these  differences,  this  library  defines  an
266       mmdb_uint128_t type.  This type is defined in the maxminddb.h header so
267       you can use it in your own code.
268
269       With older compilers, we can't use an integer so we instead  use  a  16
270       byte array of uint8_t values.  This is the raw data from the database.
271
272       This  library provides a public macro MMDB_UINT128_IS_BYTE_ARRAY macro.
273       If this is true (1), then uint128 values are returned as a byte  array,
274       if it is false then they are returned as a mmdb_uint128_t integer.
275
276   Data Type Macros
277       This  library  provides a macro for every data type defined by the Max‐
278       Mind DB spec.
279
280       • MMDB_DATA_TYPE_UTF8_STRING
281
282       • MMDB_DATA_TYPE_DOUBLE
283
284       • MMDB_DATA_TYPE_BYTES
285
286       • MMDB_DATA_TYPE_UINT16
287
288       • MMDB_DATA_TYPE_UINT32
289
290       • MMDB_DATA_TYPE_MAP
291
292       • MMDB_DATA_TYPE_INT32
293
294       • MMDB_DATA_TYPE_UINT64
295
296       • MMDB_DATA_TYPE_UINT128
297
298       • MMDB_DATA_TYPE_ARRAY
299
300       • MMDB_DATA_TYPE_BOOLEAN
301
302       • MMDB_DATA_TYPE_FLOAT
303
304       There are also a few types that are for internal use only:
305
306       • MMDB_DATA_TYPE_EXTENDED
307
308       • MMDB_DATA_TYPE_POINTER
309
310       • MMDB_DATA_TYPE_CONTAINER
311
312       • MMDB_DATA_TYPE_END_MARKER
313
314       If you see one of these in returned data then something has  gone  very
315       wrong.   The  database is damaged or was generated incorrectly or there
316       is a bug in the libmaxminddb code.
317
318   Pointer Values and MMDB_close()
319       The utf8_string, bytes, and (maybe) the uint128 members of this  struc‐
320       ture  are all pointers directly into the database's data section.  This
321       can either be a calloc'd or mmap'd block of memory.   In  either  case,
322       these pointers will become invalid after MMDB_close() is called.
323
324       If  you  need to refer to this data after that time you should copy the
325       data with an appropriate function (strdup, memcpy, etc.).
326
327   MMDB_entry_data_list_s
328       This structure encapsulates a linked list of  MMDB_entry_data_s  struc‐
329       tures.
330
331
332           typedef struct MMDB_entry_data_list_s {
333               MMDB_entry_data_s entry_data;
334               struct MMDB_entry_data_list_s *next;
335           } MMDB_entry_data_list_s;
336
337       This structure lets you look at entire map or array data entry by iter‐
338       ating over the linked list.
339
340   MMDB_search_node_s
341       This structure encapsulates the two records in a search node.  This  is
342       really only useful if you want to write code that iterates over the en‐
343       tire search tree as opposed to looking up a specific IP address.
344
345
346           typedef struct MMDB_search_node_s {
347               uint64_t left_record;
348               uint64_t right_record;
349               uint8_t left_record_type;
350               uint8_t right_record_type;
351               MMDB_entry_s left_record_entry;
352               MMDB_entry_s right_record_entry;
353           } MMDB_search_node_s;
354
355       The two record types will take one of the following values:
356
357       • MMDB_RECORD_TYPE_SEARCH_NODE - The record points to the  next  search
358         node.
359
360       • MMDB_RECORD_TYPE_EMPTY  -  The record is a placeholder that indicates
361         there is no data for the IP address.  The search should end here.
362
363       • MMDB_RECORD_TYPE_DATA - The record is for data in the data section of
364         the  database.  Use the entry for the record when looking up the data
365         for the record.
366
367       • MMDB_RECORD_TYPE_INVALID - The record is invalid.  Either an  invalid
368         node was looked up or the database is corrupt.
369
370       The  MMDB_entry_s  for  the  record  is  only  valid  if  the  type  is
371       MMDB_RECORD_TYPE_DATA.  Attempts to use an entry for other record types
372       will result in an error or invalid data.
373

STATUS CODES

375       This  library  returns  (or populates) status codes for many functions.
376       These status codes are:
377
378       • MMDB_SUCCESS - everything worked
379
380       • MMDB_FILE_OPEN_ERROR - there was an error trying to open the  MaxMind
381         DB file.
382
383       • MMDB_IO_ERROR  -  an  IO  operation failed.  Check errno for more de‐
384         tails.
385
386       • MMDB_CORRUPT_SEARCH_TREE_ERROR - looking up  an  IP  address  in  the
387         search tree gave us an impossible result.  The database is damaged or
388         was generated incorrectly or there is a bug in the libmaxminddb code.
389
390       • MMDB_INVALID_METADATA_ERROR - something in  the  database  is  wrong.
391         This  includes  missing  metadata  keys  as well as impossible values
392         (like an ip_version of 7).
393
394       • MMDB_UNKNOWN_DATABASE_FORMAT_ERROR - The database metadata  indicates
395         that it's major version is not 2.  This library can only handle major
396         version 2.
397
398       • MMDB_OUT_OF_MEMORY_ERROR - a memory allocation  call  (malloc,  etc.)
399         failed.
400
401       • MMDB_INVALID_DATA_ERROR  -  an entry in the data section contains in‐
402         valid data.  For example, a uint16 field is claiming to be more  than
403         2  bytes long.  The database is probably damaged or was generated in‐
404         correctly.
405
406       • MMDB_INVALID_LOOKUP_PATH_ERROR  -   The   lookup   path   passed   to
407         MMDB_get_value, MMDB_vget_value, or MMDB_aget_value contains an array
408         offset that is larger than LONG_MAX or smaller than LONG_MIN.
409
410       • MMDB_LOOKUP_PATH_DOES_NOT_MATCH_DATA_ERROR - The lookup  path  passed
411         to  MMDB_get_value,MMDB_vget_value, or MMDB_aget_value does not match
412         the data structure for the entry.  There are number of  reasons  this
413         can  happen.   The lookup path could include a key not in a map.  The
414         lookup path could include an array index  larger  than  an  array  or
415         smaller than the minimum offset from the end of an array.  It can al‐
416         so happen when the path expects to find a map or array where none ex‐
417         ist.
418
419       All status codes should be treated as int values.
420
421   MMDB_strerror()
422
423           const char *MMDB_strerror(int error_code)
424
425       This  function  takes  a  status code and returns an English string ex‐
426       plaining the status.
427

FUNCTIONS

429       This library provides the following exported functions:
430
431   MMDB_open()
432
433           int MMDB_open(
434               const char *const filename,
435               uint32_t flags,
436               MMDB_s *const mmdb);
437
438       This function opens a handle to a MaxMind DB file.  Its return value is
439       a status code as defined above.  Always check this call's return value.
440
441
442           MMDB_s mmdb;
443           int status =
444               MMDB_open("/path/to/file.mmdb", MMDB_MODE_MMAP, &mmdb);
445           if (MMDB_SUCCESS != status) { ... }
446           ...
447           MMDB_close(&mmdb);
448
449       filename must be encoded as UTF-8 on Windows.
450
451       The  MMDB_s structure you pass in can be on the stack or allocated from
452       the heap.  However, if the open is successful it will contain  heap-al‐
453       located data, so you need to close it with MMDB_close().  If the status
454       returned is not MMDB_SUCCESS then this library makes sure that all  al‐
455       located memory is freed before returning.
456
457       The flags currently provided are:
458
459       • MMDB_MODE_MMAP - open the database with mmap().
460
461       Passing  in other values for flags may yield unpredictable results.  In
462       the future we may add additional flags that you can bitwise-or together
463       with the mode, as well as additional modes.
464
465       You  can also pass 0 as the flags value in which case the database will
466       be opened with the default flags.  However, these defaults  may  change
467       in future releases.  The current default is MMDB_MODE_MMAP.
468
469   MMDB_close()
470
471           void MMDB_close(MMDB_s *const mmdb);
472
473       This  frees any allocated or mmap'd memory that is held from the MMDB_s
474       structure.  It does not free the memory allocated for the structure it‐
475       self! If you allocated the structure from the heap then you are respon‐
476       sible for freeing it.
477
478   MMDB_lookup_string()
479
480           MMDB_lookup_result_s MMDB_lookup_string(
481               MMDB_s *const mmdb,
482               const char *const ipstr,
483               int *const gai_error,
484               int *const mmdb_error);
485
486       This function looks up an IP address that is passed in as a null-termi‐
487       nated string.  Internally it calls getaddrinfo() to resolve the address
488       into a binary form.  It then calls MMDB_lookup_sockaddr() to  look  the
489       address  up  in  the database.  If you have already resolved an address
490       you can call MMDB_lookup_sockaddr() directly, rather than resolving the
491       address twice.
492
493
494           int gai_error, mmdb_error;
495           MMDB_lookup_result_s result =
496               MMDB_lookup_string(&mmdb, "1.2.3.4", &gai_error, &mmdb_error);
497           if (0 != gai_error) { ... }
498           if (MMDB_SUCCESS != mmdb_error) { ... }
499
500           if (result.found_entry) { ... }
501
502       This function always returns an MMDB_lookup_result_s structure, but you
503       should also check the gai_error and mmdb_error parameters.   If  either
504       of these indicates an error then the returned structure is meaningless.
505
506       If  no  error occurred you still need to make sure that the found_entry
507       member in the returned result is true.  If it's not,  this  means  that
508       the IP address does not have an entry in the database.
509
510       This function will work with IPv4 addresses even when the database con‐
511       tains data for both IPv4 and IPv6 addresses.  The IPv4 address will  be
512       looked  up  as  '::xxx.xxx.xxx.xxx'  rather  than being remapped to the
513       ::ffff:xxx.xxx.xxx.xxx block allocated for IPv4-mapped IPv6 addresses.
514
515       If you pass an IPv6 address to a database with only IPv4 data then  the
516       found_entry  member will be false, but the mmdb_error status will still
517       be MMDB_SUCCESS.
518
519   MMDB_lookup_sockaddr()
520
521           MMDB_lookup_result_s MMDB_lookup_sockaddr(
522               MMDB_s *const mmdb,
523               const struct sockaddr *const sockaddr,
524               int *const mmdb_error);
525
526       This function looks up an IP address that has already been resolved  by
527       getaddrinfo().
528
529       Other than not calling getaddrinfo() itself, this function is identical
530       to the MMDB_lookup_string() function.
531
532
533           int mmdb_error;
534           MMDB_lookup_result_s result =
535               MMDB_lookup_sockaddr(&mmdb, address->ai_addr, &mmdb_error);
536           if (MMDB_SUCCESS != mmdb_error) { ... }
537
538           if (result.found_entry) { ... }
539
540   Data Lookup Functions
541       There are three functions for looking up data associated with an IP ad‐
542       dress.
543
544
545           int MMDB_get_value(
546               MMDB_entry_s *const start,
547               MMDB_entry_data_s *const entry_data,
548               ...);
549           int MMDB_vget_value(
550               MMDB_entry_s *const start,
551               MMDB_entry_data_s *const entry_data,
552               va_list va_path);
553           int MMDB_aget_value(
554               MMDB_entry_s *const start,
555               MMDB_entry_data_s *const entry_data,
556               const char *const *const path);
557
558       The  three functions allow three slightly different calling styles, but
559       they all do the same thing.
560
561       The first parameter is an MMDB_entry_s value.  In most cases this  will
562       come     from    the    MMDB_lookup_result_s    value    returned    by
563       MMDB_lookup_string() or MMDB_lookup_sockaddr().
564
565       The second parameter is a reference to an MMDB_entry_data_s  structure.
566       This will be populated with the data that is being looked up, if any is
567       found.  If nothing is found, then the has_data member of this structure
568       will  be false.  If has_data is true then you can look at the data_type
569       member.
570
571       The final parameter is a lookup path.  The path consists of  a  set  of
572       strings  representing  either  map  keys (e.g, "city") or array indexes
573       (e.g., "0", "1", "-1") to use in the lookup.
574
575       Negative array indexes will be treated as an offset from the end of the
576       array.  For instance, "-1" refers to the last element of the array.
577
578       The  lookup  path allows you to navigate a complex data structure.  For
579       example, given this data:
580
581
582           {
583               "names": {
584                   "en": "Germany",
585                   "de": "Deutschland"
586               },
587               "cities": [ "Berlin", "Frankfurt" ]
588           }
589
590       We could look up the English name with this code:
591
592
593           MMDB_lookup_result_s result =
594               MMDB_lookup_sockaddr(&mmdb, address->ai_addr, &mmdb_error);
595           MMDB_entry_data_s entry_data;
596           int status =
597               MMDB_get_value(&result.entry, &entry_data,
598                              "names", "en", NULL);
599           if (MMDB_SUCCESS != status) { ... }
600           if (entry_data.has_data) { ... }
601
602       If we wanted to find the first city the lookup path would be  "cities",
603       "0".   If  you don't provide a lookup path at all, you'll get the entry
604       which corresponds to the top level map.  The lookup  path  must  always
605       end with NULL, regardless of which function you call.
606
607       The  MMDB_get_value function takes a variable number of arguments.  All
608       of the arguments after the MMDB_entry_data_s *  structure  pointer  are
609       the lookup path.  The last argument must be NULL.
610
611       The MMDB_vget_value function accepts a va_list as the lookup path.  The
612       last element retrieved by va_arg() must be NULL.
613
614       Finally, the MMDB_aget_value accepts an array of strings as the  lookup
615       path.  The last member of this array must be NULL.
616
617       If  you  want  to  get  all  of  the  entry  data  at once you can call
618       MMDB_get_entry_data_list() instead.
619
620       For each of the three functions, the return value is a status  code  as
621       defined above.
622
623   MMDB_get_entry_data_list()
624
625           int MMDB_get_entry_data_list(
626               MMDB_entry_s *start,
627               MMDB_entry_data_list_s **const entry_data_list);
628
629       This  function  allows  you  to  get all of the data for a complex data
630       structure at once, rather than looking up  each  piece  using  repeated
631       calls to MMDB_get_value().
632
633
634           MMDB_lookup_result_s result =
635               MMDB_lookup_sockaddr(&mmdb, address->ai_addr, &mmdb_error);
636           MMDB_entry_data_list_s *entry_data_list, *first;
637           int status =
638               MMDB_get_entry_data_list(&result.entry, &entry_data_list);
639           if (MMDB_SUCCESS != status) { ... }
640           // save this so we can free this data later
641           first = entry_data_list;
642
643           while (1) {
644               MMDB_entry_data_list_s *next = entry_data_list = entry_data_list->next;
645               if (NULL == next) {
646                   break;
647               }
648
649               switch (next->entry_data.type) {
650                   case MMDB_DATA_TYPE_MAP: { ... }
651                   case MMDB_DATA_TYPE_UTF8_STRING: { ... }
652                   ...
653               }
654
655           }
656
657           MMDB_free_entry_data_list(first);
658
659       It's  up  to  you to interpret the entry_data_list data structure.  The
660       list is linked in a depth-first traversal.  Let's use this structure as
661       an example:
662
663
664           {
665               "names": {
666                   "en": "Germany",
667                   "de": "Deutschland"
668               },
669               "cities": [ "Berlin", "Frankfurt" ]
670           }
671
672       The list will consist of the following items:
673
674        1. MAP - top level map
675
676        2. UTF8_STRING - "names" key
677
678        3. MAP - map for "names" key
679
680        4. UTF8_STRING - "en" key
681
682        5. UTF8_STRING - value for "en" key
683
684        6. UTF8_STRING - "de" key
685
686        7. UTF8_STRING - value for "de" key
687
688        8. UTF8_STRING - "cities" key
689
690        9. ARRAY - value for "cities" key
691
692       10. UTF8_STRING - array[0]
693
694       11. UTF8_STRING - array[1]
695
696       The return value of the function is a status code as defined above.
697
698   MMDB_free_entry_data_list()
699
700           void MMDB_free_entry_data_list(
701               MMDB_entry_data_list_s *const entry_data_list);
702
703       The   MMDB_get_entry_data_list()   and   MMDB_get_metadata_as_entry_da‐
704       ta_list() functions will allocate the linked list  structure  from  the
705       heap.  Call this function to free the MMDB_entry_data_list_s structure.
706
707   MMDB_get_metadata_as_entry_data_list()
708
709           int MMDB_get_metadata_as_entry_data_list(
710               MMDB_s *const mmdb,
711               MMDB_entry_data_list_s **const entry_data_list);
712
713       This  function allows you to retrieve the database metadata as a linked
714       list of MMDB_entry_data_list_s structures.  This can be a  more  conve‐
715       nient  way  to deal with the metadata than using the metadata structure
716       directly.
717
718
719               MMDB_entry_data_list_s *entry_data_list, *first;
720               int status =
721                   MMDB_get_metadata_as_entry_data_list(&mmdb, &entry_data_list);
722               if (MMDB_SUCCESS != status) { ... }
723               first = entry_data_list;
724               ... // do something with the data
725               MMDB_free_entry_data_list(first);
726
727       The return value of the function is a status code as defined above.
728
729   MMDB_dump_entry_data_list()
730
731           int MMDB_dump_entry_data_list(
732               FILE *const stream,
733               MMDB_entry_data_list_s *const entry_data_list,
734               int indent);
735
736       This function takes a linked list of MMDB_entry_data_list_s  structures
737       and  stringifies  it  to the given stream.  The indent parameter is the
738       starting indent level for the generated output.  It is incremented  for
739       nested data structures (maps, array, etc.).
740
741       The  stream must be a file handle (stdout, etc).  If your platform pro‐
742       vides something like the GNU open_memstream() you can use that to  cap‐
743       ture the output as a string.
744
745       The  output  is  formatted in a JSON-ish fashion, but values are marked
746       with their data type (except for maps and arrays which are  shown  with
747       "{}" and "[]" respectively).
748
749       The specific output format may change in future releases, so you should
750       not rely on the specific formatting produced by this function.   It  is
751       intended to be used to show data to users in a readable way and for de‐
752       bugging purposes.
753
754       The return value of the function is a status code as defined above.
755
756   MMDB_read_node()
757
758           int MMDB_read_node(
759               MMDB_s *const mmdb,
760               uint32_t node_number,
761               MMDB_search_node_s *const node);
762
763       This reads a specific node in the search tree.  The third argument is a
764       reference  to an MMDB_search_node_s structure that will be populated by
765       this function.
766
767       The return value is a status code.  If you pass a node_number  that  is
768       greater  than  the  number of nodes in the database, this function will
769       return  MMDB_INVALID_NODE_NUMBER_ERROR,  otherwise   it   will   return
770       MMDB_SUCCESS.
771
772       The  first  node in the search tree is always node 0.  If you wanted to
773       iterate over the whole search tree, you would start by reading  node  0
774       and then following the the records that make up this node, based on the
775       type of each record.  If the type is MMDB_RECORD_TYPE_SEARCH_NODE  then
776       the record contains an integer for the next node to look up.
777
778   MMDB_lib_version()
779
780           const char *MMDB_lib_version(void)
781
782       This  function  returns the library version as a string, something like
783       "2.0.0".
784

EXAMPLE

786
787           #include <errno.h>
788           #include <maxminddb.h>
789           #include <stdlib.h>
790           #include <string.h>
791
792           int main(int argc, char **argv)
793           {
794               char *filename = argv[1];
795               char *ip_address = argv[2];
796
797               MMDB_s mmdb;
798               int status = MMDB_open(filename, MMDB_MODE_MMAP, &mmdb);
799
800               if (MMDB_SUCCESS != status) {
801                   fprintf(stderr, "\n  Can't open %s - %s\n",
802                           filename, MMDB_strerror(status));
803
804                   if (MMDB_IO_ERROR == status) {
805                       fprintf(stderr, "    IO error: %s\n", strerror(errno));
806                   }
807                   exit(1);
808               }
809
810               int gai_error, mmdb_error;
811               MMDB_lookup_result_s result =
812                   MMDB_lookup_string(&mmdb, ip_address, &gai_error, &mmdb_error);
813
814               if (0 != gai_error) {
815                   fprintf(stderr,
816                           "\n  Error from getaddrinfo for %s - %s\n\n",
817                           ip_address, gai_strerror(gai_error));
818                   exit(2);
819               }
820
821               if (MMDB_SUCCESS != mmdb_error) {
822                   fprintf(stderr,
823                           "\n  Got an error from libmaxminddb: %s\n\n",
824                           MMDB_strerror(mmdb_error));
825                   exit(3);
826               }
827
828               MMDB_entry_data_list_s *entry_data_list = NULL;
829
830               int exit_code = 0;
831               if (result.found_entry) {
832                   int status = MMDB_get_entry_data_list(&result.entry,
833                                                         &entry_data_list);
834
835                   if (MMDB_SUCCESS != status) {
836                       fprintf(
837                           stderr,
838                           "Got an error looking up the entry data - %s\n",
839                           MMDB_strerror(status));
840                       exit_code = 4;
841                       goto end;
842                   }
843
844                   if (NULL != entry_data_list) {
845                       MMDB_dump_entry_data_list(stdout, entry_data_list, 2);
846                   }
847               } else {
848                   fprintf(
849                       stderr,
850                       "\n  No entry for this IP address (%s) was found\n\n",
851                       ip_address);
852                   exit_code = 5;
853               }
854
855               end:
856                   MMDB_free_entry_data_list(entry_data_list);
857                   MMDB_close(&mmdb);
858                   exit(exit_code);
859           }
860

THREAD SAFETY

862       This library is thread safe when compiled and linked with a thread-safe
863       malloc and free implementation.
864

INSTALLATION AND SOURCE

866       You  can  download  the  latest  release  of  libmaxminddb  from GitHub
867       (https://github.com/maxmind/libmaxminddb/releases).
868
869       Our GitHub repo (https://github.com/maxmind/libmaxminddb)  is  publicly
870       available.  Please fork it!
871

BUG REPORTS AND PULL REQUESTS

873       Please    report    all    issues   to   our   GitHub   issue   tracker
874       (https://github.com/maxmind/libmaxminddb/issues).  We welcome  bug  re‐
875       ports  and  pull  requests.  Please note that pull requests are greatly
876       preferred over patches.
877

AUTHORS

879       This library was written by Boris  Zentner  (bzentner@maxmind.com)  and
880       Dave Rolsky (drolsky@maxmind.com).
881
883       Copyright 2013-2022 MaxMind, Inc.
884
885       Licensed under the Apache License, Version 2.0 (the "License"); you may
886       not use this file except in compliance with the License.  You  may  ob‐
887       tain a copy of the License at
888
889
890           https://www.apache.org/licenses/LICENSE-2.0
891
892       Unless  required  by  applicable  law or agreed to in writing, software
893       distributed under the License is distributed on an "AS IS" BASIS, WITH‐
894       OUT  WARRANTIES  OR  CONDITIONS OF ANY KIND, either express or implied.
895       See the License for the specific  language  governing  permissions  and
896       limitations under the License.
897

SEE ALSO

899       mmdblookup(1)
900
901
902
903                                                               libmaxminddb(3)
Impressum