1MaxMind::DB::Reader(3)User Contributed Perl DocumentationMaxMind::DB::Reader(3)
2
3
4

NAME

6       MaxMind::DB::Reader - Read MaxMind DB files and look up IP addresses
7

VERSION

9       version 1.000014
10

SYNOPSIS

12           my $reader = MaxMind::DB::Reader->new( file => 'path/to/database.mmdb' );
13
14           my $record = $reader->record_for_address('1.2.3.4');
15

DESCRIPTION

17       This module provides a low-level interface to the MaxMind DB file
18       format <http://maxmind.github.io/MaxMind-DB/>.
19
20       If you are looking for an interface to MaxMind's GeoIP2 or GeoLite2
21       downloadable databases <http://dev.maxmind.com/geoip/>, you should also
22       check out the GeoIP2 distribution. That distribution provides a higher
23       level OO interface to those databases.
24
25       This API will work with any MaxMind DB databases, regardless of whether
26       it is a GeoIP2 database or not. In addition, if speed is critical, this
27       API will always be faster than the GeoIP2 modules, since it returns
28       results as a raw Perl data structure rather than as an object.
29

PURE PERL VERSUS XS

31       The MaxMind-DB-Reader distribution ships with a single pure Perl
32       implementation of the Reader API. There is a separate distribution on
33       CPAN, MaxMind::DB::Reader::XS, that provides an XS implementation which
34       links against libmaxminddb <http://maxmind.github.io/libmaxminddb/>.
35
36       The XS implementation is approximately 100 times faster than the pure
37       Perl implementation, so if speed is important to you, we highly
38       recommend that you install it!
39
40       If you install the XS implementation it will be automatically loaded.
41       You do not need to change your code to take advantage of it.
42

API

44       This module provides the following API:
45
46   MaxMind::DB::Reader->new( file => $path )
47       This method returns a new reader object. Note that the class of the
48       object returned will actually be either MaxMind::DB::Reader::PP or
49       MaxMind::DB::Reader::XS.
50
51       If you need to check that an object is a valid reader, you should check
52       that the object does the "MaxMind::DB::Reader::Role::Reader" role.
53
54       The "file" parameter is a required attribute for the constructor. It
55       must be a string containing a path to a file. The constructor will die
56       if the file provided is not readable.
57
58       You can also pass an additional parameter, "data_source", which must be
59       a valid filehandle. This is useful in testing. For example, you can
60       have the reader read from a filehandle opened to a scalar reference.
61       Under normal usage, the reader simply opens the provided file to read
62       from.
63
64   $reader->record_for_address($ip_address)
65       This method takes an IPv4 or IPv6 address as a string. This can be
66       either a dotted quad (1.2.3.4) or any valid IPv6 format ("abcd::1234",
67       "::1.2.3.4", etc.).
68
69       This method will die if the address is not a valid IP address.
70
71       The method returns the data associated with the IP address. Depending
72       on the contents of the database, this can be a scalar or a reference to
73       an array or hash.
74
75   $reader->iterate_search_tree( $data_callback, $node_callback )
76       This method iterates over the entire search tree, calling the callbacks
77       you provided for each data record and node in the tree.
78
79       Both callbacks are optional (although calling this with neither will do
80       a lot of work for no good reason).
81
82       The node callback is called for every node in the database's search
83       tree. This callback is called with three arguments. These are the
84       node's number (which is based on its position in the file) and the
85       values of its left and right records. These values are themselves
86       numbers. See the MaxMind DB spec <http://maxmind.github.io/MaxMind-DB/>
87       for more details on what node record values mean.
88
89       The data callback is called for records that point to the database's
90       data section. The first two arguments identify the network that the
91       data record applies to. The first argument is an IP address as an
92       integer and the second is a network mask length. The final argument is
93       the data associated with the network.
94
95   $reader->metadata()
96       This method returns a MaxMind::DB::Metadata object for the database.
97
98   $reader->file()
99       This method returns the file path passed to the constructor.
100

VERSIONING POLICY

102       This module uses semantic versioning as described by
103       <http://semver.org/>. Version numbers can be read as X.YYYZZZ, where X
104       is the major number, YYY is the minor number, and ZZZ is the patch
105       number.
106

SUPPORT

108       This module is deprecated and will only receive fixes for major bugs
109       and security vulnerabilities. New features and functionality will not
110       be added.
111
112       Please report all issues with this code using the GitHub issue tracker
113       at <https://github.com/maxmind/MaxMind-DB-Reader-perl/issues>.
114
115       Bugs may be submitted through
116       <https://github.com/maxmind/MaxMind-DB-Reader-perl/issues>.
117

AUTHORS

119       •   Dave Rolsky <drolsky@maxmind.com>
120
121       •   Olaf Alders <oalders@maxmind.com>
122

CONTRIBUTORS

124       •   Greg Oschwald <goschwald@maxmind.com>
125
126       •   Mark Fowler <mark@twoshortplanks.com>
127
128       •   Mateu X Hunter <mhunter@maxmind.com>
129
130       •   Ran Eilam <reilam@maxmind.com>
131
132       •   William Stevenson <skyblue@skybluecircles.com>
133
134       •   Will Storey <wstorey@maxmind.com>
135
137       This software is Copyright (c) 2019 by MaxMind, Inc.
138
139       This is free software, licensed under:
140
141         The Artistic License 2.0 (GPL Compatible)
142
143
144
145perl v5.34.0                      2021-07-22            MaxMind::DB::Reader(3)
Impressum