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 http://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
119       refer 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_meta‐
148       data_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_for‐
177       mat_major_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
198       address.
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   MMDB_result_s
206       You don't really need to dig around in this structure.  You'll get this
207       from a MMDB_lookup_result_s structure and pass it to various functions.
208
209   MMDB_entry_data_s
210       This structure is used to return a single data section entry for an IP.
211       These entries can in turn point to other entries, as is  the  case  for
212       things  like  maps  and arrays.  Some members of this structure are not
213       documented as they are only for internal use.
214
215
216           typedef struct MMDB_entry_data_s {
217               bool has_data;
218               union {
219                   uint32_t pointer;
220                   const char *utf8_string;
221                   double double_value;
222                   const uint8_t *bytes;
223                   uint16_t uint16;
224                   uint32_t uint32;
225                   int32_t int32;
226                   uint64_t uint64;
227                   {mmdb_uint128_t or uint8_t[16]} uint128;
228                   bool boolean;
229                   float float_value;
230               };
231               ...
232               uint32_t data_size;
233               uint32_t type;
234           } MMDB_entry_data_s;
235
236       The has_data member is true if data was found for a given lookup.   See
237       MMDB_get_value()  for  more details.  If this member is false then none
238       of the other values in the structure are meaningful.
239
240       The union at the beginning of the structure defines  the  actual  data.
241       To  determine  which  union  member is populated you should look at the
242       type member.  The pointer member of the union should never be populated
243       in  any  data  returned by the API.  Pointers should always be resolved
244       internally.
245
246       The data_size member is only relevant for utf8_string and  bytes  data.
247       utf8_string is not null terminated and data_size must be used to deter‐
248       mine its length.
249
250       The type member can be compared to one of the MMDB_DTYPE_* macros.
251
252   128-bit Integers
253       The handling of uint128 data depends  on  how  your  platform  supports
254       128-bit  integers,  if  it does so at all.  With GCC 4.4 and 4.5 we can
255       write unsigned int __attribute__ ((__mode__ (TI))).   With  newer  ver‐
256       sions  of  GCC  (4.6+)  and  clang (3.2+) we can simply write "unsigned
257       __int128".
258
259       In order to work around these  differences,  this  library  defines  an
260       mmdb_uint128_t type.  This type is defined in the maxminddb.h header so
261       you can use it in your own code.
262
263       With older compilers, we can't use an integer so we instead  use  a  16
264       byte array of uint8_t values.  This is the raw data from the database.
265
266       This  library provides a public macro MMDB_UINT128_IS_BYTE_ARRAY macro.
267       If this is true (1), then uint128 values are returned as a byte  array,
268       if it is false then they are returned as a mmdb_uint128_t integer.
269
270   Data Type Macros
271       This  library  provides a macro for every data type defined by the Max‐
272       Mind DB spec.
273
274       · MMDB_DATA_TYPE_UTF8_STRING
275
276       · MMDB_DATA_TYPE_DOUBLE
277
278       · MMDB_DATA_TYPE_BYTES
279
280       · MMDB_DATA_TYPE_UINT16
281
282       · MMDB_DATA_TYPE_UINT32
283
284       · MMDB_DATA_TYPE_MAP
285
286       · MMDB_DATA_TYPE_INT32
287
288       · MMDB_DATA_TYPE_UINT64
289
290       · MMDB_DATA_TYPE_UINT128
291
292       · MMDB_DATA_TYPE_ARRAY
293
294       · MMDB_DATA_TYPE_BOOLEAN
295
296       · MMDB_DATA_TYPE_FLOAT
297
298       There are also a few types that are for internal use only:
299
300       · MMDB_DATA_TYPE_EXTENDED
301
302       · MMDB_DATA_TYPE_POINTER
303
304       · MMDB_DATA_TYPE_CONTAINER
305
306       · MMDB_DATA_TYPE_END_MARKER
307
308       If you see one of these in returned data then something has  gone  very
309       wrong.   The  database is damaged or was generated incorrectly or there
310       is a bug in the libmaxminddb code.
311
312   Pointer Values and MMDB_close()
313       The utf8_string, bytes, and (maybe) the uint128 members of this  struc‐
314       ture  are all pointers directly into the database's data section.  This
315       can either be a malloc'd or mmap'd block of memory.   In  either  case,
316       these pointers will become invalid after MMDB_close() is called.
317
318       If  you  need to refer to this data after that time you should copy the
319       data with an appropriate function (strdup, memcpy, etc.).
320
321   MMDB_entry_data_list_s
322       This structure encapsulates a linked list of  MMDB_entry_data_s  struc‐
323       tures.
324
325
326           typedef struct MMDB_entry_data_list_s {
327               MMDB_entry_data_s entry_data;
328               struct MMDB_entry_data_list_s *next;
329           } MMDB_entry_data_list_s;
330
331       This structure lets you look at entire map or array data entry by iter‐
332       ating over the linked list.
333
334   MMDB_search_node_s
335       This structure encapsulates the two records in a search node.  This  is
336       really  only  useful  if  you want to write code that iterates over the
337       entire search tree as opposed to looking up a specific IP address.
338
339
340           typedef struct MMDB_search_node_s {
341               uint64_t left_record;
342               uint64_t right_record;
343               uint8_t left_record_type;
344               uint8_t right_record_type;
345               MMDB_entry_s left_record_entry;
346               MMDB_entry_s right_record_entry;
347           } MMDB_search_node_s;
348
349       The two record types will take one of the following values:
350
351       · MMDB_RECORD_TYPE_SEARCH_NODE - The record points to the  next  search
352         node.
353
354       · MMDB_RECORD_TYPE_EMPTY  -  The record is a placeholder that indicates
355         there is no data for the IP address.  The search should end here.
356
357       · MMDB_RECORD_TYPE_DATA - The record is for data in the data section of
358         the  database.  Use the entry for the record when looking up the data
359         for the record.
360
361       · MMDB_RECORD_TYPE_INVALID - The record is invalid.  Either an  invalid
362         node was looked up or the database is corrupt.
363
364       The  MMDB_entry_s  for  the  record  is  only  valid  if  the  type  is
365       MMDB_RECORD_TYPE_DATA.  Attempts to use an entry for other record types
366       will result in an error or invalid data.
367

STATUS CODES

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

FUNCTIONS

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

EXAMPLE

767
768           #include <maxminddb.h>
769
770           int main(int argc, char **argv)
771           {
772               MMDB_s mmdb;
773               int status = MMDB_open(fname, MMDB_MODE_MMAP, &mmdb);
774
775               if (MMDB_SUCCESS != status) {
776                   fprintf(stderr, "\n  Can't open %s - %s\n",
777                           fname, MMDB_strerror(status));
778
779                   if (MMDB_IO_ERROR == status) {
780                       fprintf(stderr, "    IO error: %s\n", strerror(errno));
781                   }
782                   exit(1);
783               }
784
785               int gai_error, mmdb_error;
786               MMDB_lookup_result_s result =
787                   MMDB_lookup_string(mmdb, ipstr, &gai_error, &mmdb_error);
788
789               if (0 != gai_error) {
790                   fprintf(stderr,
791                           "\n  Error from getaddrinfo for %s - %s\n\n",
792                           ipstr, gai_strerror(gai_error));
793                   exit(2);
794               }
795
796               if (MMDB_SUCCESS != mmdb_error) {
797                   fprintf(stderr,
798                           "\n  Got an error from libmaxminddb: %s\n\n",
799                           MMDB_strerror(mmdb_error));
800                   exit(3);
801               }
802
803               MMDB_entry_data_list_s *entry_data_list = NULL;
804
805               int exit_code = 0;
806               if (result.found_entry) {
807                   int status = MMDB_get_entry_data_list(&result.entry,
808                                                         &entry_data_list);
809
810                   if (MMDB_SUCCESS != status) {
811                       fprintf(
812                           stderr,
813                           "Got an error looking up the entry data - %s\n",
814                           MMDB_strerror(status));
815                       exit_code = 4;
816                       goto end;
817                   }
818
819                   if (NULL != entry_data_list) {
820                       MMDB_dump_entry_data_list(stdout, entry_data_list, 2);
821                   }
822               } else {
823                   fprintf(
824                       stderr,
825                       "\n  No entry for this IP address (%s) was found\n\n",
826                       ip_address);
827                   exit_code = 5;
828               }
829
830               end:
831                   MMDB_free_entry_data_list(entry_data_list);
832                   MMDB_close(&mmdb);
833                   exit(exit_code);
834           }
835

THREAD SAFETY

837       This library is thread safe when compiled and linked with a thread-safe
838       malloc and free implementation.
839

INSTALLATION AND SOURCE

841       You can  download  the  latest  release  of  libmaxminddb  from  GitHub
842       (https://github.com/maxmind/libmaxminddb/releases).
843
844       Our  GitHub  repo (https://github.com/maxmind/libmaxminddb) is publicly
845       available.  Please fork it!
846

BUG REPORTS AND PULL REQUESTS

848       Please   report   all   issues   to   our    GitHub    issue    tracker
849       (https://github.com/maxmind/libmaxminddb/issues).    We   welcome   bug
850       reports and pull requests.  Please note that pull requests are  greatly
851       preferred over patches.
852

AUTHORS

854       This  library  was  written by Boris Zentner (bzentner@maxmind.com) and
855       Dave Rolsky (drolsky@maxmind.com).
856
858       Copyright 2013-2014 MaxMind, Inc.
859
860       Licensed under the Apache License, Version 2.0 (the "License"); you may
861       not  use  this  file  except  in  compliance with the License.  You may
862       obtain a copy of the License at
863
864
865           http://www.apache.org/licenses/LICENSE-2.0
866
867       Unless required by applicable law or agreed  to  in  writing,  software
868       distributed under the License is distributed on an "AS IS" BASIS, WITH‐
869       OUT WARRANTIES OR CONDITIONS OF ANY KIND, either  express  or  implied.
870       See  the  License  for  the specific language governing permissions and
871       limitations under the License.
872

SEE ALSO

874       mmdblookup(1)
875
876
877
878                                                               libmaxminddb(3)
Impressum