### Install ip2region Golang Binding

Source: https://github.com/lionsoul2014/ip2region/blob/master/binding/golang/README.md

Use 'go get' to install the ip2region Golang binding. This command fetches and installs the package for use in your Go projects.

```bash
go get github.com/lionsoul2014/ip2region/binding/golang
```

--------------------------------

### Complete File-Based Query Example

Source: https://github.com/lionsoul2014/ip2region/blob/master/binding/c/README_zh.md

Provides a full C code example demonstrating how to initialize the xdb searcher, perform a query using an IP string (IPv4 or IPv6), handle results, and clean up resources. Includes initialization of Winsock on Windows.

```APIDOC
## Complete File-Based Query Example

### Description
This example demonstrates a complete workflow for using the ip2region C query client for file-based IP lookups. It covers initializing the searcher, performing queries for both IPv4 and IPv6, handling query results and errors, and proper resource cleanup, including Winsock initialization/cleanup on Windows.

### Code Example

```c
#include <stdio.h>
#include "xdb_api.h"

int main(int argc, char *argv[]) {
    xdb_searcher_t searcher;
    char region_buffer[512] = {'\0'};
    xdb_region_buffer_t region;

    // Initialize region_buffer_t using stack space
    int err = xdb_region_buffer_init(&region, region_buffer, sizeof(region_buffer));
    if (err != 0) {
        printf("failed to init the region buffer with errcode=%d\n", err);
        return 1;
    }

    // Initialize Winsock on Windows systems (call only once)
    err = xdb_init_winsock();
    if (err != 0) {
        printf("failed to init the winsock with errno=%d\n", err);
        return 1;
    }

    // 1. Initialize the xdb query object from the db_path.
    //    Use the db_path and version defined earlier (e.g., for IPv4 or IPv6).
    const char *db_path = "../../data/ip2region.xdb"; // Example path
    xdb_version_t *version = XDB_IPv4; // Example version
    err = xdb_new_with_file_only(version, &searcher, db_path);
    if (err != 0) {
        printf("failed to create xdb searcher from `%s` with errno=%d\n", db_path, err);
        return 1;
    }

    // 2. Call the search API to query. Supports both IPv4 and IPv6.
    const char *ip_string = "1.2.3.4";
    // ip_string = "240e:3b7:3272:d8d0:db09:c067:8d59:539e"; // Example IPv6

    long cost_time = 0, s_time = xdb_now();
    err = xdb_search_by_string(&searcher, ip_string, &region);
    cost_time = (int) (xdb_now() - s_time);
    if (err != 0) {
        printf("failed search(%s) with errno=%d\n", ip_string, err);
    } else {
        printf("{region: %s, took: %d μs}", region.value, cost_time);
    }

    // Free the memory resources for the region. Must be called after each search.
    xdb_region_buffer_free(&region);

    // Note: For concurrent use, each thread must have its own searcher object.

    // 3. Close the xdb searcher.
    xdb_close(&searcher);
    xdb_clean_winsock();    // Call on Windows systems.
    return 0;
}
```
```

--------------------------------

### File-Based Query Example

Source: https://github.com/lionsoul2014/ip2region/blob/master/binding/c/README.md

A complete C code example demonstrating how to initialize the xdb searcher, perform a query using a string IP, and handle the results.

```APIDOC
## File-Based Query Example

### Description
This example demonstrates a full workflow for using the ip2region C library to perform IP address lookups from an xdb file. It covers initialization, querying for both IPv4 and IPv6, result handling, and cleanup.

### Code
```c
#include <stdio.h>
#include "xdb_api.h"

int main(int argc, char *argv[]) {
    xdb_searcher_t searcher;
    char region_buffer[512] = {'\0'};
    xdb_region_buffer_t region;

    // Initialize region_buffer_t using region_buffer from stack space
    int err = xdb_region_buffer_init(&region, region_buffer, sizeof(region_buffer));
    if (err != 0) {
        printf("failed to init the region buffer with errcode=%d\n", err);
        return 1;
    }

    // Initialize winsock when the service starts; no need to call repeatedly, only needed on Windows systems
    err = xdb_init_winsock();
    if (err != 0) {
        printf("failed to init the winsock with errno=%d\n", err);
        return 1;
    }

    // 1. Initialize xdb query object from db_path.
    // @Note: Use the db_path and version described above to create the searcher
    // Example for IPv4:
    const char *db_path  = "../../data/ip2region_v4.xdb";
    xdb_version_t *version = XDB_IPv4;
    // Example for IPv6:
    // const char *db_path  = "../../data/ip2region_v6.xdb";
    // xdb_version_t *version = XDB_IPv6;

    err = xdb_new_with_file_only(version, &searcher, db_path);
    if (err != 0) {
        printf("failed to create xdb searcher from `%s` with errno=%d\n", db_path, err);
        return 1;
    }

    // 2. Call search API to query, both IPv4 and IPv6 are supported.
    const char *ip_string = "1.2.3.4";
    // ip_string = "240e:3b7:3272:d8d0:db09:c067:8d59:539e"; // IPv6 example

    long cost_time = 0, s_time = xdb_now();
    err = xdb_search_by_string(&searcher, ip_string, &region);
    cost_time = (int) (xdb_now() - s_time);
    if (err != 0) {
        printf("failed search(%s) with errno=%d\n", ip_string, err);
    } else {
        printf("{region: %s, took: %d μs}", region.value, cost_time);
    }

    // Clean up memory resources for region info; must be called after every search
    xdb_region_buffer_free(&region);

    // Note: For concurrent use, each thread needs to define and initialize its own searcher query object independently.

    // 3. Close xdb searcher
    xdb_close(&searcher);
    xdb_clean_winsock();    // Call on Windows
    return 0;
}
```

### Key Steps
1.  **Initialize Region Buffer**: Prepare a buffer to store the query results.
2.  **Initialize Winsock (Windows)**: Required on Windows systems before making network-related calls.
3.  **Create Searcher**: Initialize the `xdb_searcher_t` object using the appropriate database path and IP version (IPv4 or IPv6).
4.  **Perform Query**: Use `xdb_search_by_string` (or `xdb_search`) to query the IP address.
5.  **Process Results**: Check for errors and retrieve the region information from the buffer.
6.  **Free Buffer**: Release resources associated with the region buffer after each query.
7.  **Close Searcher**: Clean up the searcher object and Winsock resources when done.
```

--------------------------------

### Perform File-Based IP Query

Source: https://github.com/lionsoul2014/ip2region/blob/master/binding/c/README.md

A complete example demonstrating initialization, querying, and resource cleanup for file-based lookups.

```c
#include <stdio.h>
#include "xdb_api.h"

int main(int argc, char *argv[]) {
    xdb_searcher_t searcher;
    char region_buffer[512] = {'\0'};
    xdb_region_buffer_t region;

    // Initialize region_buffer_t using region_buffer from stack space
    int err = xdb_region_buffer_init(&region, region_buffer, sizeof(region_buffer));
    if (err != 0) {
        printf("failed to init the region buffer with errcode=%d\n", err);
        return 1;
    }

    // Initialize winsock when the service starts; no need to call repeatedly, only needed on Windows systems
    err = xdb_init_winsock();
    if (err != 0) {
        printf("failed to init the winsock with errno=%d\n", err);
        return 1;
    }

    // 1. Initialize xdb query object from db_path.
    // @Note: Use the db_path and version described above to create the searcher
    err = xdb_new_with_file_only(version, &searcher, db_path);
    if (err != 0) {
        printf("failed to create xdb searcher from `%s` with errno=%d\n", db_path, err);
        return 1;
    }

    // 2. Call search API to query, both IPv4 and IPv6 are supported.
    const char *ip_string = "1.2.3.4";
    // ip_string = "240e:3b7:3272:d8d0:db09:c067:8d59:539e"; // IPv6

    long cost_time = 0, s_time = xdb_now();
    err = xdb_search_by_string(&searcher, ip_string, &region);
    cost_time = (int) (xdb_now() - s_time);
    if (err != 0) {
        printf("failed search(%s) with errno=%d\n", ip_string, err);
    } else {
        printf("{region: %s, took: %d μs}", region.value, cost_time);
    }

    // Clean up memory resources for region info; must be called after every search
    xdb_region_buffer_free(&region);

    // Note: For concurrent use, each thread needs to define and initialize its own searcher query object independently.

    // 3. Close xdb searcher
    xdb_close(&searcher);
    xdb_clean_winsock();    // Call on Windows
    return 0;
}
```

--------------------------------

### Start interactive search

Source: https://context7.com/lionsoul2014/ip2region/llms.txt

Starts an interactive command-line tool for querying both IPv4 and IPv6 xdb files. Configures cache policies for each.

```bash
./xdb_searcher search \
    --v4-db=../../data/ip2region_v4.xdb \
    --v6-db=../../data/ip2region_v6.xdb \
    --v4-cache-policy=vectorIndex \
    --v6-cache-policy=content
```

--------------------------------

### Run Bench Command

Source: https://github.com/lionsoul2014/ip2region/blob/master/binding/c/README_zh.md

Usage examples for benchmarking performance with IPv4 and IPv6 source files.

```bash
➜  c git:(fr_c_ipv6) ✗ ./xdb_searcher bench                                  
./xdb_searcher bench [command options]
options:
 --db string              ip2region binary xdb file path
 --src string             source ip text file path
 --cache-policy string    cache policy: file/vectorIndex/content
```

```bash
➜  c git:(fr_c_ipv6) ✗ ./xdb_searcher bench --db=../../data/ip2region_v4.xdb --src=../../data/ipv4_source.txt
Bench finished, {cache_policy: vectorIndex, total: 1367686, took: 7.640s, cost: 5 μs/op}
```

```bash
➜  c git:(fr_c_ipv6) ✗ ./xdb_searcher bench --db=../../data/ip2region_v6.xdb --src=../../data/ipv6_source.txt
Bench finished, {cache_policy: vectorIndex, total: 34159862, took: 857.750s, cost: 24 μs/op}
```

--------------------------------

### Benchmark

Source: https://github.com/lionsoul2014/ip2region/blob/master/binding/erlang/README.md

Instructions and output example for running performance benchmarks.

```APIDOC
## Benchmark

Navigate to the benchmarks directory and run the benchmark script:

```bash
$ cd benchmarks/
$ sh xdb-benchmark.sh
```

### Benchmark Results Example

```
search from file:
ip count:683844,
total time: 28.201699s,
search 24248.326315375536 times per second,
use 41.23995969841075 micro second per search

search from cache:
ip count:683844,
total time: 0.671801s,
search 1017926.4395259906 times per second,
use 0.9823892583688677 micro second per search
```
```

--------------------------------

### Build ip2region Example Searcher

Source: https://github.com/lionsoul2014/ip2region/blob/master/binding/rust/README_zh.md

Compile the ip2region example searcher program in release mode. The executable will be located in `binding/rust/target/release/searcher`.

```bash
cd binding/rust/example
cargo build -r
```

--------------------------------

### Install ip2region.js via npm

Source: https://github.com/lionsoul2014/ip2region/blob/master/binding/javascript/README.md

Install the ip2region.js package using npm. This is the first step before using the library.

```bash
npm install ip2region.js --save 
```

--------------------------------

### Installation

Source: https://github.com/lionsoul2014/ip2region/blob/master/binding/python/README.md

Install the py-ip2region library using pip.

```APIDOC
## Install py-ip2region

```bash
pip3 install py-ip2region
```
```

--------------------------------

### Add Dependency and Start Application

Source: https://github.com/lionsoul2014/ip2region/blob/master/binding/erlang/README.md

Steps to include the dependency in rebar.config and initialize the application.

```erlang
{deps, [
  ip2region
]}.
```

```erlang
......

application:ensure_started(ip2region),

......
```

--------------------------------

### Install IP2Region.Net via NuGet

Source: https://github.com/lionsoul2014/ip2region/blob/master/binding/csharp/README.md

Use the NuGet package manager console to add the library to your project.

```bash
Install-Package IP2Region.Net
```

--------------------------------

### Compile and Install Default Extension

Source: https://github.com/lionsoul2014/ip2region/blob/master/binding/lua_c/README.md

Commands to compile and install the default Lua 5.4 version of the extension.

```bash
# cd to the root directory of lua_c binding
make
sudo make install
```

--------------------------------

### Interactive query: IPv6 (Example 1)

Source: https://context7.com/lionsoul2014/ip2region/llms.txt

Example of querying an IPv6 address in the interactive search session, showing the region and query time.

```bash
ip2region>> 240e:3b7:3272:d8d0:db09:c067:8d59:539e
```

--------------------------------

### Perform IP Query Using XDB File

Source: https://github.com/lionsoul2014/ip2region/blob/master/binding/c/README_zh.md

This example demonstrates how to initialize a searcher using an xdb file and perform an IP address query. It includes initializing the region buffer, handling potential errors during searcher creation and query execution, and cleaning up resources. Note that each thread requires its own searcher instance for concurrent use.

```c
#include <stdio.h>
#include "xdb_api.h"

int main(int argc, char *argv[]) {
    xdb_searcher_t searcher;
    char region_buffer[512] = {'\0'};
    xdb_region_buffer_t region;

    // 使用栈空间的 region_buffer 初始化 region_buffer_t
    int err = xdb_region_buffer_init(&region, region_buffer, sizeof(region_buffer));
    if (err != 0) {
        printf("failed to init the region buffer with errcode=%d\n", err);
        return 1;
    }

    // 在服务启动的时候初始化 winsock，不需要重复调用，只需要在 windows 系统下调用
    err = xdb_init_winsock();
    if (err != 0) {
        printf("failed to init the winsock with errno=%d\n", err);
        return 1;
    }

    // 1、从 db_path 初始化 xdb 查询对象. 
    // @Note: 使用顶部描述的 db_path 和 version 来创建 searcher
    err = xdb_new_with_file_only(version, &searcher, db_path);
    if (err != 0) {
        printf("failed to create xdb searcher from `%s` with errno=%d\n", db_path, err);
        return 1;
    }

    // 2、调用 search API 查询，IPv4 和 IPv6 都支持.
    const char *ip_string = "1.2.3.4";
    // ip_string = "240e:3b7:3272:d8d0:db09:c067:8d59:539e"; // IPv6

    long cost_time = 0, s_time = xdb_now();
    err = xdb_search_by_string(&searcher, ip_string, &region);
    cost_time = (int) (xdb_now() - s_time);
    if (err != 0) {
        printf("failed search(%s) with errno=%d\n", ip_string, err);
    } else {
        printf("{region: %s, took: %d μs}", region.value, cost_time);
    }

    // 清理 region 信息的内存资源，每次 search 之后都得调用
    xdb_region_buffer_free(&region);

    // 备注：并发使用，每一个线程需要单独定义并且初始化一个 searcher 查询对象。

    // 3、关闭 xdb 查询器
    xdb_close(&searcher);
    xdb_clean_winsock();    // windows 下调用
    return 0;
}
```

--------------------------------

### Interactive query: IPv6 (Example 2)

Source: https://context7.com/lionsoul2014/ip2region/llms.txt

Another example of querying a different IPv6 address in the interactive search session, showing the region and query time.

```bash
ip2region>> 2604:a840:3::a04d
```

--------------------------------

### Start xdb editor

Source: https://context7.com/lionsoul2014/ip2region/llms.txt

Starts the built-in editor tool to modify raw IP source data. Use 'put', 'put_file', 'save', 'list', and 'quit' commands.

```bash
./xdb_maker edit --src=../../data/ipv4_source.txt --version=ipv4
```

--------------------------------

### IPv6 Bench Test with bench_test.php

Source: https://github.com/lionsoul2014/ip2region/blob/master/binding/php/README_zh.md

Example of running an IPv6 performance benchmark. This command uses a specific IPv6 xdb file and a corresponding source IP file.

```bash
php bench_test.php --db=../../data/ip2region_v6.xdb --src=../../data/ipv6_source.txt
```

--------------------------------

### Run Search Command

Source: https://github.com/lionsoul2014/ip2region/blob/master/binding/c/README_zh.md

Usage examples for the search command, including IPv4 and IPv6 queries.

```bash
➜  c git:(fr_c_ipv6) ✗ ./xdb_searcher search
./xdb_searcher search [command options]
options:
 --db string              ip2region binary xdb file path
 --cache-policy string    cache policy: file/vectorIndex/content
```

```bash
➜  c git:(fr_c_ipv6) ✗ ./xdb_searcher search --db=../../data/ip2region_v4.xdb
ip2region xdb searcher test program
source xdb: ../../data/ip2region_v4.xdb (IPv4, vectorIndex)
type 'quit' to exit
ip2region>> 1.2.3.4
{region: Australia|Queensland|Brisbane|0|AU, io_count: 5, took: 39 μs}
ip2region>> 120.229.45.2
{region: 中国|广东省|深圳市|移动|CN, io_count: 3, took: 13 μs}
```

```bash
➜  c git:(fr_c_ipv6) ✗ ./xdb_searcher search --db=../../data/ip2region_v6.xdb
ip2region xdb searcher test program
source xdb: ../../data/ip2region_v6.xdb (IPv6, vectorIndex)
type 'quit' to exit
ip2region>> ::
{region: , io_count: 1, took: 38 μs}
ip2region>> 2604:bc80:8001:11a4:ffff:ffff:ffff:ffff
{region: United States|Florida|Miami|velia.net Internetdienste GmbH|US, io_count: 14, took: 76 μs}
ip2region>> 240e:3b7:3272:d8d0:db09:c067:8d59:539e
{region: 中国|广东省|深圳市|电信|CN, io_count: 8, took: 42 μs}
```

--------------------------------

### Usage Example

Source: https://github.com/lionsoul2014/ip2region/blob/master/binding/erlang/README.md

How to add the ip2region dependency and use the search function in your Erlang project.

```APIDOC
## Usage

* Add the dependency in `rebar.config`:

```erlang
{deps, [
  ip2region
]}.
```

* Start the ip2region Application:

```erlang
application:ensure_started(ip2region).
```

* Call the `xdb:search/1` interface to query IP information:

```erlang
ip2region:search("1.0.8.0").
```
```

--------------------------------

### IPv4 Bench Test with bench_test.php

Source: https://github.com/lionsoul2014/ip2region/blob/master/binding/php/README_zh.md

Example of running an IPv4 performance benchmark. This command uses a specific IPv4 xdb file and a corresponding source IP file.

```bash
php bench_test.php --db=../../data/ip2region_v4.xdb --src=../../data/ipv4_source.txt
```

--------------------------------

### IPv4 and IPv6 Query Setup

Source: https://github.com/lionsoul2014/ip2region/blob/master/binding/lua_c/README_zh.md

Configure the xdb path and version for querying IPv4 or IPv6 addresses. Ensure the xdb file version matches the specified IP version to avoid runtime errors.

```lua
-- Import the xdb searcher extension
local xdb = require("xdb_searcher")

-- For IPv4: Set xdb path to v4 xdb file, specify version as IPv4
local db_path  = "../../data/ip2region_v4.xdb"  -- Or your ipv4 xdb path
local version = xdb.IPv4

-- For IPv6: Set xdb path to v6 xdb file, specify version as IPv6
local db_path  = "../../data/ip2region_v6.xdb";  -- Or your ipv6 xdb path
local version = xdb.IPv6

-- The IP version of the xdb specified by db_path must match the version specified by version, otherwise a runtime error will occur.
-- Note: The following demonstrates direct use of db_path and version variables
```

--------------------------------

### Run ip2region xdb maker

Source: https://github.com/lionsoul2014/ip2region/blob/master/maker/python/README.md

Navigate to the Python maker root directory and execute the main script to start the ip2region xdb maker. Use the 'gen' command to generate the binary db file.

```bash
# cd to the python maker root directory
> python main.py
ip2region xdb maker
main.py [command] [command options]
Command:
  gen      generate the binary db file
```

--------------------------------

### Configure IPv4 and IPv6 Search

Source: https://github.com/lionsoul2014/ip2region/blob/master/binding/lua_c/README.md

Setup code for defining the database path and IP version for queries.

```lua
-- Import xdb searcher extension
local xdb = require("xdb_searcher")

-- For IPv4: Set xdb path to v4 xdb file, specify IP version as IPv4
local db_path  = "../../data/ip2region_v4.xdb"  -- or your ipv4 xdb path
local version = xdb.IPv4

-- For IPv6: Set xdb path to v6 xdb file, specify IP version as IPv6
local db_path  = "../../data/ip2region_v6.xdb";  -- or your ipv6 xdb path
local version = xdb.IPv6

-- The IP version of the xdb specified by db_path must match the version specified, otherwise an error will occur during query execution
-- Note: The following demonstration directly uses the db_path and version variables
```

--------------------------------

### Configure IPv4 and IPv6 Searchers

Source: https://github.com/lionsoul2014/ip2region/blob/master/binding/lua/README.md

Setup the database path and version constant for either IPv4 or IPv6 xdb files.

```lua
local xdb = require("xdb_searcher")

-- For IPv4: Set xdb path to the v4 xdb file, specify IP version as Version.IPv4
local dbPath  = "../../data/ip2region_v4.xdb"  -- or your ipv4 xdb path
local version = xdb.IPv4

-- For IPv6: Set xdb path to the v6 xdb file, specify IP version as Version.IPv6
local dbPath  = "../../data/ip2region_v6.xdb"  -- or your ipv6 xdb path
local version = xdb.IPv6

-- The IP version of the xdb specified by dbPath must match the version specified, otherwise an error will occur during query execution
-- Note: The following demonstration directly uses the dbPath and version variables
```

--------------------------------

### Initialize and Query IP2Region in C#

Source: https://context7.com/lionsoul2014/ip2region/llms.txt

Provides examples for .NET applications, including dependency injection for ASP.NET Core and cache policy selection.

```csharp
using IP2Region.Net.Abstractions;
using IP2Region.Net.XDB;

// Create searcher with cache policy
ISearcher searcher = new Searcher(CachePolicy.Content, "/path/to/ip2region_v4.xdb");
// CachePolicy options: Content (fastest), VectorIndex (balanced), File (minimal memory)

// Query IP
string region = searcher.Search("1.2.3.4");
Console.WriteLine($"{{region: {region}}}");
// Output: {region: Australia|Queensland|Brisbane|0|AU}

// IPv6 query
ISearcher v6Searcher = new Searcher(CachePolicy.Content, "/path/to/ip2region_v6.xdb");
region = v6Searcher.Search("240e:3b7:3272:d8d0:db09:c067:8d59:539e");
Console.WriteLine($"{{region: {region}}}");
// Output: {region: 中国|广东省|深圳市|电信|CN}

// ASP.NET Core dependency injection
services.AddIP2RegionService("/path/to/ip2region_v4.xdb", cachePolicy: CachePolicy.Content);

// Resolve service
var searcher = provider.GetRequiredService<ISearcher>();
// NET8+ keyed service: provider.GetRequiredKeyedService<ISearcher>("IP2Region.Net");
```

--------------------------------

### C++ Example: Search IP Address

Source: https://github.com/lionsoul2014/ip2region/blob/master/binding/cpp/README.md

This C++ code demonstrates how to use the ip2region library to search for IP address information. It supports both IPv4 and IPv6, with options for different caching policies (no cache, partial cache, full cache). Ensure the correct xdb file path and IP version are specified.

```cpp
#include "src/search.h"

// IP Version: xdb::ipv4 xdb::ipv6
//    Policy: xdb::policy_file xdb::policy_vector xdb::policy_content
//               No cache           Partial cache        Full cache
int main() {
    std::string xdb_name = "../../data/ip2region_v6.xdb";
    int         version  = xdb::ipv6;
    int         policy   = xdb::policy_content;
    std::string ip       = "2001:200:124::";

    xdb::search_t s(xdb_name, version, policy);
    std::cout << s.search(ip) << std::endl;
    return 0;
}

// $ g++ src/*.cc 1.cc --- Compile
// $ ./a.out ------------- Test
// Japan|Tokyo|Asagaya-minami|WIDE Project|JP
```

--------------------------------

### Search IP Address with C++ Client

Source: https://github.com/lionsoul2014/ip2region/blob/master/binding/cpp/README_zh.md

Example of how to use the C++ search functionality. Include 'src/search.h', specify IP version, caching policy, and the xdb file path. Compile with g++ and run the executable.

```cpp
#include "src/search.h"

// IP 版本: xdb::ipv4 xdb::ipv6
//    策略: xdb::policy_file xdb::policy_vector xdb::policy_content
//               不缓存           部分缓存           全部缓存
int main() {
    std::string xdb_name = "../../data/ip2region_v6.xdb";
    int         version  = xdb::ipv6;
    int         policy   = xdb::policy_content;
    std::string ip       = "2001:200:124::";

    xdb::search_t s(xdb_name, version, policy);
    std::cout << s.search(ip) << std::endl;
    return 0;
}

// $ g++ src/*.cc 1.cc --- 编译
// $ ./a.out ------------- 测试
// Japan|Tokyo|Asagaya-minami|WIDE Project|JP
```

--------------------------------

### Create and Use Searcher in Java

Source: https://context7.com/lionsoul2014/ip2region/llms.txt

Demonstrates initializing a searcher with various caching policies and performing an IP lookup in Java.

```java
import org.lionsoul.ip2region.xdb.Searcher;
import org.lionsoul.ip2region.xdb.Version;

// File-only query
Searcher searcher = Searcher.newWithFileOnly(Version.IPv4, "/path/to/ip2region_v4.xdb");

// VectorIndex caching
byte[] vIndex = Searcher.loadVectorIndexFromFile("/path/to/ip2region_v4.xdb");
Searcher searcher = Searcher.newWithVectorIndex(Version.IPv4, "/path/to/ip2region_v4.xdb", vIndex);

// Full content caching (concurrency-safe)
LongByteArray cBuff = Searcher.loadContentFromFile("/path/to/ip2region_v4.xdb");
Searcher searcher = Searcher.newWithBuffer(Version.IPv4, cBuff);

// Query IP
String region = searcher.search("1.2.3.4");
System.out.printf("{region: %s, ioCount: %d}\n", region, searcher.getIOCount());
// Output: {region: Australia|Queensland|Brisbane|0|AU, ioCount: 0}

searcher.close();
```

--------------------------------

### Install py-ip2region

Source: https://github.com/lionsoul2014/ip2region/blob/master/binding/python/README_zh.md

Install the py-ip2region package using pip.

```bash
pip3 install py-ip2region
```

--------------------------------

### View maker help documentation

Source: https://github.com/lionsoul2014/ip2region/blob/master/maker/rust/README.md

Display the command-line options and usage instructions for the generated executable.

```bash
# CWD ip2region/maker/rust/maker
$ ./target/release/maker --help
```

--------------------------------

### Bench Command Help

Source: https://github.com/lionsoul2014/ip2region/blob/master/binding/java/README_zh.md

Display the help menu for the bench command to evaluate query performance.

```bash
➜  java git:(fr_java_ipv6) ✗ java -jar target/ip2region-3.1.0.jar bench                                  
java -jar ip2region-{version}.jar bench [command options]
options:
 --db string              ip2region binary xdb file path
 --src string             source ip text file path
 --cache-policy string    cache policy: file/vectorIndex/content
```

--------------------------------

### View IP2RegionMaker Help

Source: https://github.com/lionsoul2014/ip2region/blob/master/maker/csharp/README.md

Display command-line options for the xdb maker tool.

```bash
➜  csharp git:(master) ✗ dotnet IP2RegionMaker.dll
ip2region xdb maker
dotnet IP2RegionMaker.dll [command options]
--src string    source ip text file path
--dst string    destination binary xdb file path
```

--------------------------------

### Initialize and Query IP2Region in C

Source: https://context7.com/lionsoul2014/ip2region/llms.txt

Demonstrates low-level integration in C, including buffer management, winsock initialization for Windows, and various caching strategies.

```c
#include <stdio.h>
#include "xdb_api.h"

int main(int argc, char *argv[]) {
    xdb_searcher_t searcher;
    xdb_region_buffer_t region;
    char region_buffer[512] = {'\0'};

    // Initialize region buffer (stack-allocated or auto-managed)
    xdb_region_buffer_init(&region, region_buffer, sizeof(region_buffer));
    // Or: xdb_region_buffer_init(&region, NULL, 0);  // auto-allocate

    // Initialize winsock (Windows only)
    xdb_init_winsock();

    // File-only query
    int err = xdb_new_with_file_only(XDB_IPv4, &searcher, "/path/to/ip2region_v4.xdb");

    // VectorIndex caching
    xdb_vector_index_t *v_index = xdb_load_vector_index_from_file("/path/to/ip2region_v4.xdb");
    err = xdb_new_with_vector_index(XDB_IPv4, &searcher, "/path/to/ip2region_v4.xdb", v_index);

    // Full content caching
    xdb_content_t *c_buffer = xdb_load_content_from_file("/path/to/ip2region_v4.xdb");
    err = xdb_new_with_buffer(XDB_IPv4, &searcher, c_buffer);

    // Query IP
    long s_time = xdb_now();
    err = xdb_search_by_string(&searcher, "1.2.3.4", &region);
    long cost = xdb_now() - s_time;

    if (err == 0) {
        printf("{region: %s, took: %ld μs}\n", region.value, cost);
        // Output: {region: Australia|Queensland|Brisbane|0|AU, took: 39 μs}
    }

    xdb_region_buffer_free(&region);
    xdb_close(&searcher);
    xdb_close_content(c_buffer);
    xdb_clean_winsock();
    return 0;
}
```

--------------------------------

### ip2region Bench Command Help

Source: https://github.com/lionsoul2014/ip2region/blob/master/binding/golang/README.md

Displays available options for the `xdb_searcher bench` command, including paths to the database and source files, and cache policy options.

```bash
./xdb_searcher bench [command options]
options:
 --db string              ip2region binary xdb file path
 --src string             source ip text file path
 --cache-policy string    cache policy: file/vectorIndex/content
```

--------------------------------

### View Bench Test Help

Source: https://github.com/lionsoul2014/ip2region/blob/master/binding/lua/README.md

Displays the available command-line options for the bench_test.lua script.

```bash
➜  lua git:(fr_lua_ipv6) ✗ lua bench_test.lua                                                                                              
lua bench_test.lua [command options]
options: 
 --db string             ip2region binary xdb file path
 --src string            source ip text file path
 --cache-policy string   cache policy: file/vectorIndex/content
```

--------------------------------

### Access Log Sample

Source: https://github.com/lionsoul2014/ip2region/blob/master/binding/nginx/README_zh.md

Example of an Nginx access log entry with ip2region data.

```APIDOC
## Nginx Access Log Sample

An example of an Nginx access log entry formatted to include IP region information obtained via the ip2region module.

### Log Format Example

```log
{"remote_addr": "127.0.0.1", "region": "Reserved|Reserved|Reserved|0|0", "http_x_forwarded_for": ""}
{"remote_addr": "127.0.0.1", "region": "Reserved|Reserved|Reserved|0|0", "http_x_forwarded_for": ""}
```
```

--------------------------------

### Run Bench Test Help

Source: https://github.com/lionsoul2014/ip2region/blob/master/binding/lua_c/README.md

Displays command options for the bench_test.lua script.

```bash
➜  lua_c git:(fr_lua_c_ipv6) ✗ lua ./bench_test.lua 
lua bench_test.lua [command options]
options: 
 --db string             ip2region binary xdb file path
 --src string            source ip text file path
 --cache-policy string   cache policy: file/vectorIndex/content
```

--------------------------------

### Compile and Run Erlang Node

Source: https://github.com/lionsoul2014/ip2region/blob/master/binding/erlang/README.md

Commands to compile the project and start the Erlang shell.

```bash
$ rebar3 compile
```

```bash
$ rebar3 shell
```

--------------------------------

### Configure Nginx for ip2region

Source: https://github.com/lionsoul2014/ip2region/blob/master/binding/nginx/README.md

Example configuration for the http block in nginx.conf to enable ip2region logging.

```nginx
...
http {

    log_format main escape=json '{
                                "remote_addr": "$remote_addr", 
                                "region": "$ip2region", 
                                "http_x_forwarded_for": "$http_x_forwarded_for"
                                }';

    access_log logs/access.log main;

    # set xdb file path
    ip2region_db ip2region.xdb;
    # ip2region_db ip2region.xdb vectorIndex;
    # ip2region_db ip2region.xdb file;
    # ip2region_db ip2region.xdb content;

    server {
        listen 80;
        server_name localhost;

        location / {
            root html;
            index index.html index.htm;
        }
    }
}
```

--------------------------------

### Display xdb maker help

Source: https://github.com/lionsoul2014/ip2region/blob/master/maker/java/README_zh.md

Run the JAR file without arguments to view available command options.

```bash
➜  java git:(master) java -jar target/ip2region-maker-3.0.0.jar 
ip2region xdb maker
java -jar ip2region-maker-{version}.jar [command options]
options:
 --src string           source ip text file path
 --dst string           destination binary xdb file path
 --version string       IP version, options: ipv4/ipv6, specify this flag so you don't get confused
 --field-list string    field index list imploded with ',' eg: 0,1,2,3-6,7
 --log-level string     set the log level, options: debug/info/warn/error
```

--------------------------------

### Build Go Maker and Generate xdb Files

Source: https://github.com/lionsoul2014/ip2region/blob/master/maker/rust/README_zh.md

Build the Go maker program and then use it to generate IPv4 and IPv6 xdb files. The generated files will be placed in the specified destination paths.

```bash
cd maker/golang
make
./xdb_maker gen --src=../../data/ipv4_source.txt --dst=./ip2region_v4.xdb --version=ipv4
```

```bash
./xdb_maker gen --src=../../data/ipv6_source.txt --dst=./ip2region_v6.xdb --version=ipv6
```

--------------------------------

### Query IP Information Programmatically

Source: https://github.com/lionsoul2014/ip2region/blob/master/binding/erlang/README.md

Example of calling the search interface within application code.

```erlang
......

ip2region:search("1.0.8.0"),

......
```

--------------------------------

### Run Query Test

Source: https://github.com/lionsoul2014/ip2region/blob/master/binding/lua_c/README.md

Example of running a search test using a specific Lua version.

```bash
# Compile extension using lua 5.1
make LuaVersion=5.1

# Run query test using lua5.1
lua5.1 search_test.py --db=../../data/ip2region_v4.xdb
```

--------------------------------

### Compile and Run

Source: https://github.com/lionsoul2014/ip2region/blob/master/binding/erlang/README.md

Instructions for compiling the Erlang client and running it with the xdb file.

```APIDOC
## Compile and Run

### Compile

```bash
$ rebar3 compile
```

### Run

Place the xdb file in the `priv` directory, then start the Erlang node:

```bash
$ rebar3 shell
```

Call the `xdb:search/1` interface in the Erlang shell to query IP address information. This interface supports IP addresses represented as list strings, binary strings, tuples, and integers.
```

--------------------------------

### Interactive query: IPv4

Source: https://context7.com/lionsoul2014/ip2region/llms.txt

Example of querying an IPv4 address in the interactive search session, showing the region and query time.

```bash
ip2region>> 1.2.3.4
```

--------------------------------

### Run Search Demo

Source: https://github.com/lionsoul2014/ip2region/blob/master/binding/java/README_zh.md

Execute an interactive search session to query IP addresses against the xdb files.

```bash
➜  java git:(java_app_with_ip2region_service) ✗ java -jar target/ip2region-3.3.0.jar search       
ip2region search service test program
+-v4 xdb: /data01/code/c/ip2region/data/ip2region_v4.xdb (vectorIndex)
+-v6 xdb: /data01/code/c/ip2region/data/ip2region_v6.xdb (vectorIndex)
type 'quit' to exit
ip2region>> 1.2.3.4
{region: Australia|Queensland|Brisbane|0|AU, took: 140 μs}
ip2region>> 240e:3b7:3272:d8d0:db09:c067:8d59:539e
{region: 中国|广东省|深圳市|电信|CN, took: 391 μs}
ip2region>> 2604:a840:3::a04d
{region: United States|California|San Jose|xTom|US, took: 503 μs}
```

--------------------------------

### Query IP Information in Erlang Shell

Source: https://github.com/lionsoul2014/ip2region/blob/master/binding/erlang/README.md

Examples of using the xdb:search/1 interface with different IP address formats.

```erlang
1> xdb:search("1.0.8.0").
[20013,22269,124,48,124,24191,19996,30465,124,24191,24030,
 24066,124,30005,20449]
2>
3> io:format("~ts~n", [xdb:search("1.0.8.0")]).
中国|0|广东省|广州市|电信
io:format("~ts~n", [xdb:search(<<"1.0.8.0">>) ]).
中国|0|广东省|广州市|电信
4> io:format("~ts~n", [xdb:search({1,0,8,0})]).
中国|0|广东省|广州市|电信
6> io:format("~ts~n", [xdb:search(16779264)]).
中国|0|广东省|广州市|电信
```

--------------------------------

### Initialize xdb_region_buffer_t

Source: https://github.com/lionsoul2014/ip2region/blob/master/binding/c/README_zh.md

Demonstrates manual memory allocation for known region lengths versus automatic allocation by passing NULL.

```c
// 1, 通过指定一块内存来创建 region_buffer
char buffer[512];
xdb_region_buffer_t region;
int err = xdb_region_buffer_init(&region, buffer, sizeof(buffer));
if (err != 0) {
    // 初始化失败
    printf("failed to init region buffer width errcode=%d", err);
    return;
}

// 2，通过指定 NULL 来创建 region_buffer，让其自动按需分配内存
xdb_region_buffer_t region;
int err = xdb_region_buffer_init(&region, NULL, 0);
if (err != 0) {
    // 初始化失败
    printf("failed to init region buffer width errcode=%d", err);
    return;
}


// 备注：在每次调用 search 完成 IP 定位信息的查询后，你需要手动调用函数来释放内存 .
// search 函数使用未经清理的 region 信息会报错。
xdb_region_buffer_free(&region);
```

--------------------------------

### Configure Cargo.toml for ip2region

Source: https://github.com/lionsoul2014/ip2region/blob/master/binding/rust/README_zh.md

Add the ip2region crate to your project's dependencies in Cargo.toml. This example uses a git dependency pointing to the master branch.

```toml
[dependencies]
ip2region = { git = "https://github.com/lionsoul2014/ip2region.git", branch = "master" }
```

--------------------------------

### Basic xdb Bench Command Usage

Source: https://github.com/lionsoul2014/ip2region/blob/master/binding/c/README.md

Shows the available options for the `xdb_searcher bench` command. Use this to understand the parameters for bench testing the xdb file.

```bash
#!/bin/bash
./xdb_searcher bench [command options]
options:
 --db string              ip2region binary xdb file path
 --src string             source ip text file path
 --cache-policy string    cache policy: file/vectorIndex/content
```

--------------------------------

### Compile the Rust maker

Source: https://github.com/lionsoul2014/ip2region/blob/master/maker/rust/README.md

Navigate to the maker directory and build the project in release mode.

```bash
$ cd maker/rust/maker
$ cargo build -r
```

--------------------------------

### IPv4 Query Test with search_test.php

Source: https://github.com/lionsoul2014/ip2region/blob/master/binding/php/README_zh.md

Example of using `search_test.php` to query IPv4 addresses. This command uses the default IPv4 xdb file and demonstrates interactive lookups.

```bash
php search_test.php --db=../../data/ip2region_v4.xdb
```

```text
ip2region xdb searcher test program
source xdb file: ../../data/ip2region_v4.xdb (IPv4, vectorIndex)
type 'quit' to exit
ip2region>> 1.2.3.4
{region: Australia|Queensland|Brisbane|0|AU, ioCount: 5, took: 0.12695 ms}
ip2region>> 120.229.45.2
{region: 中国|广东省|深圳市|移动|CN, ioCount: 3, took: 0.07397 ms}
```

--------------------------------

### Compare xdb File Differences

Source: https://github.com/lionsoul2014/ip2region/blob/master/maker/rust/README_zh.md

Generate xdb files using both Rust and Go makers, then use `vbindiff` to compare them. Differences should primarily be in creation time.

```bash
cd maker/rust/maker
./target/release/maker --src=../../../data/ipv4.xdb --dst=./target/ipv4.xdb --ip-version v4
```

```bash
./target/release/maker --src=../../../data/ipv6.xdb --dst=./target/ipv6.xdb --ip-version v6
```

```bash
vbindiff ./ipv4.xdb ../../golang/ip2region_v4.xdb
```

```bash
vbindiff ./ipv6.xdb ../../golang/ip2region_v6.xdb
```

--------------------------------

### Compile Default Lua 5.4 Extension

Source: https://github.com/lionsoul2014/ip2region/blob/master/binding/lua_c/README_zh.md

Compile and install the default Lua 5.4 version of the ip2region Lua C extension. Ensure you are in the root directory of the lua_c binding.

```bash
cd to the lua_c binding root directory
make
sudo make install
```

--------------------------------

### IPv6 Query Test with search_test.php

Source: https://github.com/lionsoul2014/ip2region/blob/master/binding/php/README_zh.md

Example of using `search_test.php` to query IPv6 addresses. This command uses the default IPv6 xdb file and demonstrates interactive lookups for IPv6 addresses.

```bash
php ./search_test.php --db=../../data/ip2region_v6.xdb
```

```text
ip2region xdb searcher test program
source xdb file: ../../data/ip2region_v6.xdb (IPv6, vectorIndex)
type 'quit' to exit
ip2region>> ::
{region: , ioCount: 1, took: 0.08887 ms}
ip2region>> 240e:3b7:3272:d8d0:db09:c067:8d59:539e
{region: 中国|广东省|深圳市|电信|CN, ioCount: 8, took: 0.10303 ms}
ip2region>> 2604:a840:3::a04d
{region: United States|California|San Jose|xTom|US, ioCount: 13, took: 0.04614 ms}
```