.\" Process this file with
.\" groff -man -Tascii $file
.\"
.TH geoip 3 "April 2007" "Tcl extension" "Version 0.2"
.SH NAME
geoip \- A Tcl extension for geographic or organisational lookup of IP addresses 
and hostnames.
.SH SYNOPSIS
.B geoip open [-type 
.I TYPE
] [-flags 
.I FLAG
]
.br
.B geoip open [-file 
.I PATH
] [-flags 
.I FLAG
]
.br
.B geoip [COMMAND]
.br
.B geoip [QUERY]
.I arg1
.SH DESCRIPTION
This Tcl extension encapsulates most of GeoIP C API functions into tcl commands.

.SH OPEN OPTIONS
open takes either a file path and a set of flags, or a type and a set of flags.
Supported types and flags are described below.

.IP TYPE 
Looks under the standard installation share directory, eg /usr/local/share/GeoIP/ for a GeoIP
database according to type.
.IP PATH 
Absolute/relative path to GeoIP database.
.IP FLAG
Flags seperated by ':', eg memory_cache:memory_check

.SH COMMAND
Individual singular commands can be one of:
.IP close 
Close the currently open database.
.IP db_info 
Get information about the current database.
.IP db_edition
Returns edition of opened database.
.IP db_avail
Test the availability of databases in your system in known locations. e.g db_avail country_edition

.SH QUERY
Commands that query the database. All commands return N/A if a result 
cannot be found. If none already open, a command will attempt to open a suitable
database. country commands will open a country_edition database. region commands
will open a region_edition_rev1 one. name commands 
will open an org_edition one, and the record_edition will open a 
city_edition_rev1 database. The commands are:
.IP country_code_by_addr 
Takes an IP address and returns the ISO-3166-1 Alpha-2 code of 
the country.
.IP country_code3_by_addr 
Takes an IP address and returns the ISO-3166-1 Alpha-3 code the country.
.IP country_code_by_name
Takes a hostname and returns the ISO-3166-1 Alpha-2 code the country.
.IP country_code3_by_name
Takes a hostname and returns the ISO-3166-1 Alpha-3 code the country.
.IP country_name_by_addr 
Takes an IP address and returns the country name.
.IP country_name_by_name
Takes a hostname and returns the country name.
.IP name_by_addr
Takes an IP address and returns the organisation name (or ISP/ASnum according
to the opened database)
.IP name_by_name
Takes a hostname and returns the organisation name.
.IP region_by_addr
Takes an IP address and returns these region attributes as in an associative
array: country, region
.IP region_by_name
Takes a hostname and returns the region attributes.
.IP record_by_addr
Takes an IP address and returns these record attributes as in an associative array:
code, code3, region, country, city, postcode, latitude, longitude, dma(dma code),
and area (area code)
.IP record_by_name
Takes a hostname and returns the record attributes.

.SH TYPES
Relevant types of databases are:
country_edition,
org_edition,
isp_edition,
city_edition_rev1,
region_edition_rev1,
geoip_asnum_edition. "open -type" will accept their unambiguous abbreviations.

.SH FLAGS
Valid flags are: standard, memory_cache, check_cache, index_cache.

.SH FILES
.IP ./share/GeoIP.dat
GeoIP country_edition database.
.IP ./share/GeoIPOrg.dat
GeoIP org_edition database.
.IP ./share/GeoIPCity.dat
GeoIP region_city_rev1 database.
.IP ./share/GeoIPRegion.dat
GeoIP region_edition_rev1 database.
.IP ./share/GeoIPASNum.dat
GeoIP asnum_edition database.

.SH BUGS
Please report to author.
.SH AUTHOR
Djihed Afifi <djihed@gmail.com>.
.SH "SEE ALSO"
GeoIP C API documentation <www.maxmind.com>