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 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 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_DTYPE_* 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 malloc'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 negative integer or an integer larger than LONG_MAX.
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. It
415 can also happen when the path expects to find a map or array where
416 none exist.
417 All status codes should be treated as int values.
419 MMDB_strerror()
421 const char *MMDB_strerror(int error_code)
423 This function takes a status code and returns an English string ex‐
425 plaining the status.
426
428 This library provides the following exported functions:
429 MMDB_open()
431 int MMDB_open(
433 const char *const filename,
434 uint32_t flags,
435 MMDB_s *const mmdb);
436 This function opens a handle to a MaxMind DB file. Its return value is
438 a status code as defined above. Always check this call's return value.
439 MMDB_s mmdb;
442 int status =
443 MMDB_open("/path/to/file.mmdb", MMDB_MODE_MMAP, &mmdb);
444 if (MMDB_SUCCESS != status) { ... }
445 ...
446 MMDB_close(&mmdb);
447 The MMDB_s structure you pass in can be on the stack or allocated from
449 the heap. However, if the open is successful it will contain heap-al‐
450 located data, so you need to close it with MMDB_close(). If the status
451 returned is not MMDB_SUCCESS then this library makes sure that all al‐
452 located memory is freed before returning.
453 The flags currently provided are:
455 · MMDB_MODE_MMAP - open the database with mmap().
457 Passing in other values for flags may yield unpredictable results. In
459 the future we may add additional flags that you can bitwise-or together
460 with the mode, as well as additional modes.
461 You can also pass 0 as the flags value in which case the database will
463 be opened with the default flags. However, these defaults may change
464 in future releases. The current default is MMDB_MODE_MMAP.
465 MMDB_close()
467 void MMDB_close(MMDB_s *const mmdb);
469 This frees any allocated or mmap'd memory that is held from the MMDB_s
471 structure. It does not free the memory allocated for the structure it‐
472 self! If you allocated the structure from the heap then you are re‐
473 sponsible for freeing it.
474 MMDB_lookup_string()
476 MMDB_lookup_result_s MMDB_lookup_string(
478 MMDB_s *const mmdb,
479 const char *const ipstr,
480 int *const gai_error,
481 int *const mmdb_error);
482 This function looks up an IP address that is passed in as a null-termi‐
484 nated string. Internally it calls getaddrinfo() to resolve the address
485 into a binary form. It then calls MMDB_lookup_sockaddr() to look the
486 address up in the database. If you have already resolved an address
487 you can call MMDB_lookup_sockaddr() directly, rather than resolving the
488 address twice.
489 int gai_error, mmdb_error;
492 MMDB_lookup_result_s result =
493 MMDB_lookup_string(&mmdb, "1.2.3.4", &gai_error, &mmdb_error);
494 if (0 != gai_error) { ... }
495 if (MMDB_SUCCESS != mmdb_error) { ... }
496 if (result.found_entry) { ... }
498 This function always returns an MMDB_lookup_result_s structure, but you
500 should also check the gai_error and mmdb_error parameters. If either
501 of these indicates an error then the returned structure is meaningless.
502 If no error occurred you still need to make sure that the found_entry
504 member in the returned result is true. If it's not, this means that
505 the IP address does not have an entry in the database.
506 This function will work with IPv4 addresses even when the database con‐
508 tains data for both IPv4 and IPv6 addresses. The IPv4 address will be
509 looked up as '::xxx.xxx.xxx.xxx' rather than being remapped to the
510 ::ffff:xxx.xxx.xxx.xxx block allocated for IPv4-mapped IPv6 addresses.
511 If you pass an IPv6 address to a database with only IPv4 data then the
513 found_entry member will be false, but the mmdb_error status will still
514 be MMDB_SUCCESS.
515 MMDB_lookup_sockaddr()
517 MMDB_lookup_result_s MMDB_lookup_sockaddr(
519 MMDB_s *const mmdb,
520 const struct sockaddr *const sockaddr,
521 int *const mmdb_error);
522 This function looks up an IP address that has already been resolved by
524 getaddrinfo().
525 Other than not calling getaddrinfo() itself, this function is identical
527 to the MMDB_lookup_string() function.
528 int mmdb_error;
531 MMDB_lookup_result_s result =
532 MMDB_lookup_sockaddr(&mmdb, address->ai_addr, &mmdb_error);
533 if (MMDB_SUCCESS != mmdb_error) { ... }
534 if (result.found_entry) { ... }
536 Data Lookup Functions
538 There are three functions for looking up data associated with an IP ad‐
539 dress.
540 int MMDB_get_value(
543 MMDB_entry_s *const start,
544 MMDB_entry_data_s *const entry_data,
545 ...);
546 int MMDB_vget_value(
547 MMDB_entry_s *const start,
548 MMDB_entry_data_s *const entry_data,
549 va_list va_path);
550 int MMDB_aget_value(
551 MMDB_entry_s *const start,
552 MMDB_entry_data_s *const entry_data,
553 const char *const *const path);
554 The three functions allow three slightly different calling styles, but
556 they all do the same thing.
557 The first parameter is an MMDB_entry_s value. In most cases this will
559 come from the MMDB_lookup_result_s value returned by
560 MMDB_lookup_string() or MMDB_lookup_sockaddr().
561 The second parameter is a reference to an MMDB_entry_data_s structure.
563 This will be populated with the data that is being looked up, if any is
564 found. If nothing is found, then the has_data member of this structure
565 will be false. If has_data is true then you can look at the data_type
566 member.
567 The final parameter is a lookup path. The path consists of a set of
569 strings representing either map keys (e.g, "city") or array indexes
570 (e.g., "0", "1") to use in the lookup. This allow you to navigate a
571 complex data structure. For example, given this example:
572 {
575 "names": {
576 "en": "Germany",
577 "de": "Deutschland"
578 },
579 "cities": [ "Berlin", "Frankfurt" ]
580 }
581 We could look up the English name with this code:
583 MMDB_lookup_result_s result =
586 MMDB_lookup_sockaddr(&mmdb, address->ai_addr, &mmdb_error);
587 MMDB_entry_data_s entry_data;
588 int status =
589 MMDB_get_value(&result.entry, &entry_data,
590 "names", "en", NULL);
591 if (MMDB_SUCCESS != status) { ... }
592 if (entry_data.has_data) { ... }
593 If we wanted to find the first city the lookup path would be
595 "cities", "0". If you don't provide a lookup path at all, you'll get
596 the entry which corresponds to the top level map. The lookup path must
597 always end with NULL, regardless of which function you call.
598 The MMDB_get_value function takes a variable number of arguments. All
600 of the arguments after the MMDB_entry_data_s * structure pointer are
601 the lookup path. The last argument must be NULL.
602 The MMDB_vget_value function accepts a va_list as the lookup path. The
604 last element retrieved by va_arg() must be NULL.
605 Finally, the MMDB_aget_value accepts an array of strings as the lookup
607 path. The last member of this array must be NULL.
608 If you want to get all of the entry data at once you can call
610 MMDB_get_entry_data_list() instead.
611 For each of the three functions, the return value is a status code as
613 defined above.
614 MMDB_get_entry_data_list()
616 int MMDB_get_entry_data_list(
618 MMDB_entry_s *start,
619 MMDB_entry_data_list_s **const entry_data_list);
620 This function allows you to get all of the data for a complex data
622 structure at once, rather than looking up each piece using repeated
623 calls to MMDB_get_value().
624 MMDB_lookup_result_s result =
627 MMDB_lookup_sockaddr(&mmdb, address->ai_addr, &mmdb_error);
628 MMDB_entry_data_list_s *entry_data_list, *first;
629 int status =
630 MMDB_get_entry_data_list(&result.entry, &entry_data_list);
631 if (MMDB_SUCCESS != status) { ... }
632 // save this so we can free this data later
633 first = entry_data_list;
634 while (1) {
636 MMDB_entry_data_list_s *next = entry_data_list = entry_data_list->next;
637 if (NULL == next) {
638 break;
639 }
640 switch (next->entry_data.type) {
642 case MMDB_DATA_TYPE_MAP: { ... }
643 case MMDB_DATA_TYPE_UTF8_STRING: { ... }
644 ...
645 }
646 }
648 MMDB_free_entry_data_list(first);
650 It's up to you to interpret the entry_data_list data structure. The
652 list is linked in a depth-first traversal. Let's use this structure as
653 an example:
654 {
657 "names": {
658 "en": "Germany",
659 "de": "Deutschland"
660 },
661 "cities": [ "Berlin", "Frankfurt" ]
662 }
663 The list will consist of the following items:
665 1. MAP - top level map
667 2. UTF8_STRING - "names" key
669 3. MAP - map for "names" key
671 4. UTF8_STRING - "en" key
673 5. UTF8_STRING - value for "en" key
675 6. UTF8_STRING - "de" key
677 7. UTF8_STRING - value for "de" key
679 8. UTF8_STRING - "cities" key
681 9. ARRAY - value for "cities" key
683 10. UTF8_STRING - array[0]
685 11. UTF8_STRING - array[1]
687 The return value of the function is a status code as defined above.
689 MMDB_free_entry_data_list()
691 void MMDB_free_entry_data_list(
693 MMDB_entry_data_list_s *const entry_data_list);
694 The MMDB_get_entry_data_list() and MMDB_get_metadata_as_entry_da‐
696 ta_list() functions will allocate the linked list structure from the
697 heap. Call this function to free the MMDB_entry_data_list_s structure.
698 MMDB_get_metadata_as_entry_data_list()
700 int MMDB_get_metadata_as_entry_data_list(
702 MMDB_s *const mmdb,
703 MMDB_entry_data_list_s **const entry_data_list);
704 This function allows you to retrieve the database metadata as a linked
706 list of MMDB_entry_data_list_s structures. This can be a more conve‐
707 nient way to deal with the metadata than using the metadata structure
708 directly.
709 MMDB_entry_data_list_s *entry_data_list, *first;
712 int status =
713 MMDB_get_metadata_as_entry_data_list(&mmdb, &entry_data_list);
714 if (MMDB_SUCCESS != status) { ... }
715 first = entry_data_list;
716 ... // do something with the data
717 MMDB_free_entry_data_list(first);
718 The return value of the function is a status code as defined above.
720 MMDB_dump_entry_data_list()
722 int MMDB_dump_entry_data_list(
724 FILE *const stream,
725 MMDB_entry_data_list_s *const entry_data_list,
726 int indent);
727 This function takes a linked list of MMDB_entry_data_list_s structures
729 and stringifies it to the given stream. The indent parameter is the
730 starting indent level for the generated output. It is incremented for
731 nested data structures (maps, array, etc.).
732 The stream must be a file handle (stdout, etc). If your platform pro‐
734 vides something like the GNU open_memstream() you can use that to cap‐
735 ture the output as a string.
736 The output is formatted in a JSON-ish fashion, but values are marked
738 with their data type (except for maps and arrays which are shown with
739 "{}" and "[]" respectively).
740 The specific output format may change in future releases, so you should
742 not rely on the specific formatting produced by this function. It is
743 intended to be used to show data to users in a readable way and for de‐
744 bugging purposes.
745 The return value of the function is a status code as defined above.
747 MMDB_read_node()
749 int MMDB_read_node(
751 MMDB_s *const mmdb,
752 uint32_t node_number,
753 MMDB_search_node_s *const node);
754 This reads a specific node in the search tree. The third argument is a
756 reference to an MMDB_search_node_s structure that will be populated by
757 this function.
758 The return value is a status code. If you pass a node_number that is
760 greater than the number of nodes in the database, this function will
761 return MMDB_INVALID_NODE_NUMBER_ERROR, otherwise it will return
762 MMDB_SUCCESS.
763 The first node in the search tree is always node 0. If you wanted to
765 iterate over the whole search tree, you would start by reading node 0
766 and then following the the records that make up this node, based on the
767 type of each record. If the type is MMDB_RECORD_TYPE_SEARCH_NODE then
768 the record contains an integer for the next node to look up.
769 MMDB_lib_version()
771 const char *MMDB_lib_version(void)
773 This function returns the library version as a string, something like
775 "2.0.0".
776
778 #include <errno.h>
780 #include <maxminddb.h>
781 #include <stdlib.h>
782 #include <string.h>
783 int main(int argc, char **argv)
785 {
786 char *filename = argv[1];
787 char *ip_address = argv[2];
788 MMDB_s mmdb;
790 int status = MMDB_open(filename, MMDB_MODE_MMAP, &mmdb);
791 if (MMDB_SUCCESS != status) {
793 fprintf(stderr, "\n Can't open %s - %s\n",
794 filename, MMDB_strerror(status));
795 if (MMDB_IO_ERROR == status) {
797 fprintf(stderr, " IO error: %s\n", strerror(errno));
798 }
799 exit(1);
800 }
801 int gai_error, mmdb_error;
803 MMDB_lookup_result_s result =
804 MMDB_lookup_string(&mmdb, ip_address, &gai_error, &mmdb_error);
805 if (0 != gai_error) {
807 fprintf(stderr,
808 "\n Error from getaddrinfo for %s - %s\n\n",
809 ip_address, gai_strerror(gai_error));
810 exit(2);
811 }
812 if (MMDB_SUCCESS != mmdb_error) {
814 fprintf(stderr,
815 "\n Got an error from libmaxminddb: %s\n\n",
816 MMDB_strerror(mmdb_error));
817 exit(3);
818 }
819 MMDB_entry_data_list_s *entry_data_list = NULL;
821 int exit_code = 0;
823 if (result.found_entry) {
824 int status = MMDB_get_entry_data_list(&result.entry,
825 &entry_data_list);
826 if (MMDB_SUCCESS != status) {
828 fprintf(
829 stderr,
830 "Got an error looking up the entry data - %s\n",
831 MMDB_strerror(status));
832 exit_code = 4;
833 goto end;
834 }
835 if (NULL != entry_data_list) {
837 MMDB_dump_entry_data_list(stdout, entry_data_list, 2);
838 }
839 } else {
840 fprintf(
841 stderr,
842 "\n No entry for this IP address (%s) was found\n\n",
843 ip_address);
844 exit_code = 5;
845 }
846 end:
848 MMDB_free_entry_data_list(entry_data_list);
849 MMDB_close(&mmdb);
850 exit(exit_code);
851 }
852
854 This library is thread safe when compiled and linked with a thread-safe
855 malloc and free implementation.
856
858 You can download the latest release of libmaxminddb from GitHub
859 (https://github.com/maxmind/libmaxminddb/releases).
860 Our GitHub repo (https://github.com/maxmind/libmaxminddb) is publicly
862 available. Please fork it!
863
865 Please report all issues to our GitHub issue tracker
866 (https://github.com/maxmind/libmaxminddb/issues). We welcome bug re‐
867 ports and pull requests. Please note that pull requests are greatly
868 preferred over patches.
869
871 This library was written by Boris Zentner (bzentner@maxmind.com) and
872 Dave Rolsky (drolsky@maxmind.com).
873
875 Copyright 2013-2014 MaxMind, Inc.
876 Licensed under the Apache License, Version 2.0 (the "License"); you may
878 not use this file except in compliance with the License. You may ob‐
879 tain a copy of the License at
880 http://www.apache.org/licenses/LICENSE-2.0
883 Unless required by applicable law or agreed to in writing, software
885 distributed under the License is distributed on an "AS IS" BASIS, WITH‐
886 OUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
887 See the License for the specific language governing permissions and
888 limitations under the License.
889
891 mmdblookup(1)
892 libmaxminddb(3)