$ opm get GUI/lua-libcidr-ffi

lua-libcidr-ffi

[!Circle CI](https://circleci.com/gh/GUI/lua-libcidr-ffi)

LuaJIT FFI 绑定到 libcidr。提供 IPv4 和 IPv6 的 CIDR 计算。

安装

要使用 lua-libcidr-ffi，首先必须在系统上安装 libcidr。然后可以通过 LuaRocks 或 OPM 安装 lua-libcidr-ffi

通过 LuaRocks

    luarocks install libcidr-ffi

或通过 OPM

    opm get GUI/lua-libcidr-ffi

依赖项

libcidr 必须安装在您的系统上。它可以通过系统软件包（如果可用）安装，也可以从源代码手动构建。

软件包： 如果您的发行版提供二进制软件包（在 Ubuntu 18.04 Bionic 及更高版本或 Debian 10 Buster 及更高版本上可用）

    apt-get install libcidr-dev

源代码： 对于其他发行版，如果未提供二进制软件包，则可以从源代码安装 libcidr

    curl -OL "https://www.over-yonder.net/~fullermd/projects/libcidr/libcidr-1.2.3.tar.xz"
    tar -xf libcidr-1.2.3.tar.xz
    cd libcidr-1.2.3
    make
    sudo make install

用法

    local cidr = require "libcidr-ffi"
    cidr.contains(cidr.from_str("10.10.10.10/8"), cidr.from_str("10.20.30.40")) -- true
    cidr.contains(cidr.from_str("10.10.10.10/16"), cidr.from_str("10.20.30.40")) -- false
    cidr.contains(cidr.from_str("2001:db8::/32"), cidr.from_str("2001:db8:1234::1")) -- true
    cidr.contains(cidr.from_str("2001:db8::/32"), cidr.from_str("2001:db9:1234::1")) -- false

函数

有关函数行为的更详细文档，请参见 libcidr 的文档。目前，此 Lua 库中只提供对 libcidr 中几个函数的绑定，但可以轻松添加其他绑定。

from_str

    struct, err = cidr.from_str(string)

以人类可读的字符串形式接受网络块描述，并从中创建 CIDR 结构。如果失败，则返回 nil 和描述错误的字符串。

to_str

    string, err = cidr.to_str(struct[, flags])

接受一个 CIDR 结构，并生成一个描述网络块的人类可读字符串。如果失败，则返回 nil 和描述错误的字符串。

标志

可选的第二个参数接受用于控制字符串输出格式的标志。每个标志的常量都在 cidr.flags 下提供。多个标志可以组合成位掩码。可用的标志为

• NOFLAGS：当您只想使用默认输出时，这是一个占位符

• NOCOMPACT：不进行 ::-style IPv6 压缩

• VERBOSE：在八位字节中显示前导 0 [仅限 v6]

• USEV6：对 IPv4 地址使用 IPv4 映射地址形式（::ffff:a.b.c.d）

• USEV4COMPAT：使用 IPv4 兼容形式（::a.b.c.d）而不是 IPv4 映射形式（仅在与 CIDR_USEV6 结合使用时才有意义）

• NETMASK：在斜杠后返回标准形式的网络掩码，而不是前缀长度。请注意，网络掩码的形式可以由此修改各种标志，这些标志会改变地址的显示方式。

• ONLYADDR：仅显示地址，不显示前缀/网络掩码

• ONLYPFLEN：仅显示前缀长度（或网络掩码，与 CIDR_NETMASK 结合使用），不显示地址。

• WILDCARD：显示 Cisco 风格的通配符掩码，而不是网络掩码（仅在与 CIDR_NETMASK 结合使用时才有意义）

• FORCEV6：强制将 CIDR 视为 IPv6 地址，无论它实际上是什么。这不会进行任何转换或翻译；只是将原始数据视为 IPv6。

• FORCEV4：强制将 CIDR 视为 IPv4 地址，无论它实际上是什么。这不会进行任何转换或翻译；只是将原始数据视为 IPv4。

• REVERSE：为给定块生成 .in-addr.arpa 或 .ip6.arpa 风格的 PTR 记录名称。请注意，这始终将其仅视为地址；忽略网络掩码。有关此形式的地址表示与网络掩码相关的非对称处理的详细信息，请参见 cidr_from_str() 中的一些说明。

示例

    local cidr = require "libcidr-ffi"
    local bit = require "bit"
    
    cidr.to_str(cidr.from_str("127.0.0.1"))
    -- "127.0.0.1/32"
    
    cidr.to_str(cidr.from_str("127.0.0.1"), cidr.flags.ONLYADDR)
    -- "127.0.0.1"
    
    cidr.to_str(cidr.from_str("127.0.0.1"), cidr.flags.USEV6)
    -- "::ffff:127.0.0.1/128"
    
    cidr.to_str(cidr.from_str("127.0.0.1"), bit.bor(cidr.flags.ONLYADDR, cidr.flags.USEV6))
    -- "::ffff:127.0.0.1"
    
    cidr.to_str(cidr.from_str("2001:db8::2:1"))
    -- "2001:db8::2:1/128"
    
    cidr.to_str(cidr.from_str("2001:db8::2:1"), cidr.flags.VERBOSE)
    -- "2001:0db8::0002:0001/128"

contains

    bool = cidr.contains(big, small)

此函数传递两个描述一对网络块的 CIDR 结构。然后，它确定后者是否完全包含在前者中。如果失败，则返回 nil 和描述错误的字符串。

替代方案

• lua-resty-iputils：OpenResty 中用于 CIDR 比较的纯 Lua 库。提供了一个不错的更高级别的 API，具有内置的缓存功能。目前缺少 IPv6 支持。

故障排除

LuaRocks 安装：找不到库

执行 luarocks install libcidr-ffi 命令时，如果您收到一条错误消息，指示找不到 libcidr 库（Could not find library file for CIDR），则可以使用 CIDR_LIBDIR 参数手动指定包含 libcidr.so 文件的 lib 目录的位置。例如，如果库安装在 /usr/local/lib/libcidr.so 中

    luarocks install libcidr-ffi CIDR_LIBDIR=/usr/local/lib

运行时：找不到库

在 Lua 代码中需要 libcidr-ffi 模块时，如果您收到一条错误消息，指示找不到 libcidr 库（libcidr.so: cannot open shared object file: No such file or directory），则可以使用 LD_LIBRARY_PATH 环境变量手动指定包含 libcidr.so 文件的 lib 目录的位置。例如，如果库安装在 /usr/local/lib/libcidr.so 中

    export LD_LIBRARY_PATH=/usr/local/lib
    luajit -e 'require "libcidr-ffi"'

开发

检出仓库后，可以使用 Docker 运行测试套件

    docker-compose run --rm app make test

发布流程

要将新版本发布到 LuaRocks 和 OPM

• 确保 CHANGELOG.md 已更新。

• 更新 lib/libcidr-ffi.lua 中的 _VERSION。

• 更新 dist.ini 中的 version。

• 将 rockspec 文件移动到新的版本号（git mv libcidr-ffi-X.X.X-1.rockspec libcidr-ffi-X.X.X-1.rockspec），并在 rockspec 文件中更新 version 和 tag 变量。

• 提交并标记发布（git tag -a vX.X.X -m "Tagging vX.X.X" && git push origin vX.X.X）。

• 运行 make release VERSION=X.X.X。