1libmaxminddb(3) libmaxminddb(3)
2
6 libmaxminddb - a library for working with MaxMind DB files
7
9 #include <maxminddb.h>
11 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 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 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 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 int MMDB_read_node(
56 MMDB_s *const mmdb,
57 uint32_t node_number,
58 MMDB_search_node_s *const node);
59 const char *MMDB_lib_version(void);
61 const char *MMDB_strerror(int error_code);
62 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 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 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 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 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 When you are done with the database handle you should call
111 MMDB_close().
112 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 re‐
119 fer to them without the struct prefix.
120 This library provides the following data structures:
122 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 typedef struct MMDB_s {
130 uint32_t flags;
131 const char *filename;
132 ...
133 MMDB_metadata_s metadata;
134 } MMDB_s;
135 • uint32_t flags - the flags this database was opened with. See the
137 MMDB_open() documentation for more details.
138 • const char *filename - the name of the file which was opened, as
140 passed to MMDB_open().
141 • MMDB_metadata_s metadata - the metadata for the database.
143 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 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 typedef struct MMDB_description_s {
170 const char *language;
171 const char *description;
172 } MMDB_description_s;
173 These structures should be mostly self-explanatory.
175 The ip_version member should always be 4 or 6. The binary_format_ma‐
177 jor_version should always be 2.
178 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 MMDB_lookup_result_s
184 This structure is returned as the result of looking up an IP address.
185 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 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 The entry member is used to look up the data associated with the IP ad‐
198 dress.
199 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 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 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 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 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 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 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 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 The type member can be compared to one of the MMDB_DATA_TYPE_* macros.
257 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 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 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 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 Data Type Macros
277 This library provides a macro for every data type defined by the Max‐
278 Mind DB spec.
279 • MMDB_DATA_TYPE_UTF8_STRING
281 • MMDB_DATA_TYPE_DOUBLE
283 • MMDB_DATA_TYPE_BYTES
285 • MMDB_DATA_TYPE_UINT16
287 • MMDB_DATA_TYPE_UINT32
289 • MMDB_DATA_TYPE_MAP
291 • MMDB_DATA_TYPE_INT32
293 • MMDB_DATA_TYPE_UINT64
295 • MMDB_DATA_TYPE_UINT128
297 • MMDB_DATA_TYPE_ARRAY
299 • MMDB_DATA_TYPE_BOOLEAN
301 • MMDB_DATA_TYPE_FLOAT
303 There are also a few types that are for internal use only:
305 • MMDB_DATA_TYPE_EXTENDED
307 • MMDB_DATA_TYPE_POINTER
309 • MMDB_DATA_TYPE_CONTAINER
311 • MMDB_DATA_TYPE_END_MARKER
313 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 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 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 MMDB_entry_data_list_s
328 This structure encapsulates a linked list of MMDB_entry_data_s struc‐
329 tures.
330 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 This structure lets you look at entire map or array data entry by iter‐
338 ating over the linked list.
339 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 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 The two record types will take one of the following values:
356 • MMDB_RECORD_TYPE_SEARCH_NODE - The record points to the next search
358 node.
359 • 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 • 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 • MMDB_RECORD_TYPE_INVALID - The record is invalid. Either an invalid
368 node was looked up or the database is corrupt.
369 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
375 This library returns (or populates) status codes for many functions.
376 These status codes are:
377 • MMDB_SUCCESS - everything worked
379 • MMDB_FILE_OPEN_ERROR - there was an error trying to open the MaxMind
381 DB file.
382 • MMDB_IO_ERROR - an IO operation failed. Check errno for more de‐
384 tails.
385 • 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 • 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 • 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 • MMDB_OUT_OF_MEMORY_ERROR - a memory allocation call (malloc, etc.)
399 failed.
400 • 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 • 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 • 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 All status codes should be treated as int values.
420 MMDB_strerror()
422 const char *MMDB_strerror(int error_code)
424 This function takes a status code and returns an English string ex‐
426 plaining the status.
427
429 This library provides the following exported functions:
430 MMDB_open()
432 int MMDB_open(
434 const char *const filename,
435 uint32_t flags,
436 MMDB_s *const mmdb);
437 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 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 filename must be encoded as UTF-8 on Windows.
450 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 The flags currently provided are:
458 • MMDB_MODE_MMAP - open the database with mmap().
460 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 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 MMDB_close()
470 void MMDB_close(MMDB_s *const mmdb);
472 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 MMDB_lookup_string()
479 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 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 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 if (result.found_entry) { ... }
501 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 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 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 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 MMDB_lookup_sockaddr()
520 MMDB_lookup_result_s MMDB_lookup_sockaddr(
522 MMDB_s *const mmdb,
523 const struct sockaddr *const sockaddr,
524 int *const mmdb_error);
525 This function looks up an IP address that has already been resolved by
527 getaddrinfo().
528 Other than not calling getaddrinfo() itself, this function is identical
530 to the MMDB_lookup_string() function.
531 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 if (result.found_entry) { ... }
539 Data Lookup Functions
541 There are three functions for looking up data associated with an IP ad‐
542 dress.
543 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 The three functions allow three slightly different calling styles, but
559 they all do the same thing.
560 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 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 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 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 The lookup path allows you to navigate a complex data structure. For
579 example, given this data:
580 {
583 "names": {
584 "en": "Germany",
585 "de": "Deutschland"
586 },
587 "cities": [ "Berlin", "Frankfurt" ]
588 }
589 We could look up the English name with this code:
591 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 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 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 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 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 If you want to get all of the entry data at once you can call
618 MMDB_get_entry_data_list() instead.
619 For each of the three functions, the return value is a status code as
621 defined above.
622 MMDB_get_entry_data_list()
624 int MMDB_get_entry_data_list(
626 MMDB_entry_s *start,
627 MMDB_entry_data_list_s **const entry_data_list);
628 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 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 while (1) {
644 MMDB_entry_data_list_s *next = entry_data_list = entry_data_list->next;
645 if (NULL == next) {
646 break;
647 }
648 switch (next->entry_data.type) {
650 case MMDB_DATA_TYPE_MAP: { ... }
651 case MMDB_DATA_TYPE_UTF8_STRING: { ... }
652 ...
653 }
654 }
656 MMDB_free_entry_data_list(first);
658 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 {
665 "names": {
666 "en": "Germany",
667 "de": "Deutschland"
668 },
669 "cities": [ "Berlin", "Frankfurt" ]
670 }
671 The list will consist of the following items:
673 1. MAP - top level map
675 2. UTF8_STRING - "names" key
677 3. MAP - map for "names" key
679 4. UTF8_STRING - "en" key
681 5. UTF8_STRING - value for "en" key
683 6. UTF8_STRING - "de" key
685 7. UTF8_STRING - value for "de" key
687 8. UTF8_STRING - "cities" key
689 9. ARRAY - value for "cities" key
691 10. UTF8_STRING - array[0]
693 11. UTF8_STRING - array[1]
695 The return value of the function is a status code as defined above.
697 MMDB_free_entry_data_list()
699 void MMDB_free_entry_data_list(
701 MMDB_entry_data_list_s *const entry_data_list);
702 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 MMDB_get_metadata_as_entry_data_list()
708 int MMDB_get_metadata_as_entry_data_list(
710 MMDB_s *const mmdb,
711 MMDB_entry_data_list_s **const entry_data_list);
712 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 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 The return value of the function is a status code as defined above.
728 MMDB_dump_entry_data_list()
730 int MMDB_dump_entry_data_list(
732 FILE *const stream,
733 MMDB_entry_data_list_s *const entry_data_list,
734 int indent);
735 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 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 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 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 The return value of the function is a status code as defined above.
755 MMDB_read_node()
757 int MMDB_read_node(
759 MMDB_s *const mmdb,
760 uint32_t node_number,
761 MMDB_search_node_s *const node);
762 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 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 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 MMDB_lib_version()
779 const char *MMDB_lib_version(void)
781 This function returns the library version as a string, something like
783 "2.0.0".
784
786 #include <errno.h>
788 #include <maxminddb.h>
789 #include <stdlib.h>
790 #include <string.h>
791 int main(int argc, char **argv)
793 {
794 char *filename = argv[1];
795 char *ip_address = argv[2];
796 MMDB_s mmdb;
798 int status = MMDB_open(filename, MMDB_MODE_MMAP, &mmdb);
799 if (MMDB_SUCCESS != status) {
801 fprintf(stderr, "\n Can't open %s - %s\n",
802 filename, MMDB_strerror(status));
803 if (MMDB_IO_ERROR == status) {
805 fprintf(stderr, " IO error: %s\n", strerror(errno));
806 }
807 exit(1);
808 }
809 int gai_error, mmdb_error;
811 MMDB_lookup_result_s result =
812 MMDB_lookup_string(&mmdb, ip_address, &gai_error, &mmdb_error);
813 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 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 MMDB_entry_data_list_s *entry_data_list = NULL;
829 int exit_code = 0;
831 if (result.found_entry) {
832 int status = MMDB_get_entry_data_list(&result.entry,
833 &entry_data_list);
834 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 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 end:
856 MMDB_free_entry_data_list(entry_data_list);
857 MMDB_close(&mmdb);
858 exit(exit_code);
859 }
860
862 libmaxminddb requires a minimum of POSIX.1-2001 support. If not speci‐
863 fied at compilation time, it defaults to requesting POSIX.1-2008 sup‐
864 port.
865
867 This library is thread safe when compiled and linked with a thread-safe
868 malloc and free implementation.
869
871 You can download the latest release of libmaxminddb from GitHub
872 (https://github.com/maxmind/libmaxminddb/releases).
873 Our GitHub repo (https://github.com/maxmind/libmaxminddb) is publicly
875 available. Please fork it!
876
878 Please report all issues to our GitHub issue tracker
879 (https://github.com/maxmind/libmaxminddb/issues). We welcome bug re‐
880 ports and pull requests. Please note that pull requests are greatly
881 preferred over patches.
882
884 This library was written by Boris Zentner (bzentner@maxmind.com) and
885 Dave Rolsky (drolsky@maxmind.com).
886
888 Copyright 2013-2023 MaxMind, Inc.
889 Licensed under the Apache License, Version 2.0 (the "License"); you may
891 not use this file except in compliance with the License. You may ob‐
892 tain a copy of the License at
893 https://www.apache.org/licenses/LICENSE-2.0
896 Unless required by applicable law or agreed to in writing, software
898 distributed under the License is distributed on an "AS IS" BASIS, WITH‐
899 OUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
900 See the License for the specific language governing permissions and
901 limitations under the License.
902
904 mmdblookup(1)
905 libmaxminddb(3)