Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
MaxMind::DB::Reader(3)User Contributed Perl DocumentatioMaxMind::DB::Reader(3)

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

VERSION
       version 1.000013

SYNOPSIS
	   my $reader =	MaxMind::DB::Reader->new( file => 'path/to/database.mmdb' );

	   my $record =	$reader->record_for_address('1.2.3.4');

DESCRIPTION
       This module provides a low-level	interface to the MaxMind DB file
       format <http://maxmind.github.io/MaxMind-DB/>.

       If you are looking for an interface to MaxMind's	GeoIP2 or GeoLite2
       downloadable databases <http://dev.maxmind.com/geoip/>, you should also
       check out the GeoIP2 distribution. That distribution provides a higher
       level OO	interface to those databases.

       This API	will work with any MaxMind DB databases, regardless of whether
       it is a GeoIP2 database or not. In addition, if speed is	critical, this
       API will	always be faster than the GeoIP2 modules, since	it returns
       results as a raw	Perl data structure rather than	as an object.

PURE PERL VERSUS XS
       The MaxMind-DB-Reader distribution ships	with a single pure Perl
       implementation of the Reader API. There is a separate distribution on
       CPAN, MaxMind::DB::Reader::XS, that provides an XS implementation which
       links against libmaxminddb <http://maxmind.github.io/libmaxminddb/>.

       The XS implementation is	approximately 100 times	faster than the	pure
       Perl implementation, so if speed	is important to	you, we	highly
       recommend that you install it!

       If you install the XS implementation it will be automatically loaded.
       You do not need to change your code to take advantage of	it.

API
       This module provides the	following API:

   MaxMind::DB::Reader->new( file => $path )
       This method returns a new reader	object.	Note that the class of the
       object returned will actually be	either MaxMind::DB::Reader::PP or
       MaxMind::DB::Reader::XS.

       If you need to check that an object is a	valid reader, you should check
       that the	object does the	"MaxMind::DB::Reader::Role::Reader" role.

       The "file" parameter is a required attribute for	the constructor. It
       must be a string	containing a path to a file. The constructor will die
       if the file provided is not readable.

       You can also pass an additional parameter, "data_source", which must be
       a valid filehandle. This	is useful in testing. For example, you can
       have the	reader read from a filehandle opened to	a scalar reference.
       Under normal usage, the reader simply opens the provided	file to	read
       from.

   $reader->record_for_address($ip_address)
       This method takes an IPv4 or IPv6 address as a string. This can be
       either a	dotted quad (1.2.3.4) or any valid IPv6	format ("abcd::1234",
       "::1.2.3.4", etc.).

       This method will	die if the address is not a valid IP address.

       The method returns the data associated with the IP address. Depending
       on the contents of the database,	this can be a scalar or	a reference to
       an array	or hash.

   $reader->iterate_search_tree( $data_callback, $node_callback	)
       This method iterates over the entire search tree, calling the callbacks
       you provided for	each data record and node in the tree.

       Both callbacks are optional (although calling this with neither will do
       a lot of	work for no good reason).

       The node	callback is called for every node in the database's search
       tree. This callback is called with three	arguments. These are the
       node's number (which is based on	its position in	the file) and the
       values of its left and right records. These values are themselves
       numbers.	See the	MaxMind	DB spec	<http://maxmind.github.io/MaxMind-DB/>
       for more	details	on what	node record values mean.

       The data	callback is called for records that point to the database's
       data section. The first two arguments identify the network that the
       data record applies to. The first argument is an	IP address as an
       integer and the second is a network mask	length.	The final argument is
       the data	associated with	the network.

   $reader->metadata()
       This method returns a MaxMind::DB::Metadata object for the database.

   $reader->file()
       This method returns the file path passed	to the constructor.

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

SUPPORT
       Please report all issues	with this code using the GitHub	issue tracker
       at <https://github.com/maxmind/MaxMind-DB-Reader-perl/issues>.

       Bugs may	be submitted through
       <https://github.com/maxmind/MaxMind-DB-Reader-perl/issues>.

AUTHORS
       o   Dave	Rolsky <drolsky@maxmind.com>

       o   Olaf	Alders <oalders@maxmind.com>

CONTRIBUTORS
       o   Greg	Oschwald <goschwald@maxmind.com>

       o   Mateu X Hunter <mhunter@maxmind.com>

       o   Ran Eilam <reilam@maxmind.com>

       o   William Stevenson <skyblue@skybluecircles.com>

COPYRIGHT AND LICENSE
       This software is	Copyright (c) 2017 by MaxMind, Inc.

       This is free software, licensed under:

	 The Artistic License 2.0 (GPL Compatible)

perl v5.24.1			  2017-02-02		MaxMind::DB::Reader(3)

NAME | VERSION | SYNOPSIS | DESCRIPTION | PURE PERL VERSUS XS | API | VERSIONING POLICY | SUPPORT | AUTHORS | CONTRIBUTORS | COPYRIGHT AND LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=MaxMind::DB::Reader&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help