1libmaxminddb(3) libmaxminddb(3)
2
3
4
6 libmaxminddb - a library for working with MaxMind DB files
7
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
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
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
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
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
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
837 This library is thread safe when compiled and linked with a thread-safe
838 malloc and free implementation.
839
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
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
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
874 mmdblookup(1)
875
876
877
878 libmaxminddb(3)