{"id":36965264,"url":"https://github.com/bkataru/niza","last_synced_at":"2026-01-13T19:56:24.504Z","repository":{"id":324304717,"uuid":"1096781543","full_name":"bkataru/niza","owner":"bkataru","description":"Cross-Platform Network Interface Library \u0026 CLI for Zig","archived":false,"fork":false,"pushed_at":"2025-12-14T23:06:27.000Z","size":33,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-17T12:10:34.913Z","etag":null,"topics":["cli","cross-platform","library","linux","macos","network","network-interface","network-interfaces","networking","windows","zig"],"latest_commit_sha":null,"homepage":"","language":"Zig","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bkataru.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-15T00:01:34.000Z","updated_at":"2025-12-14T23:07:57.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/bkataru/niza","commit_stats":null,"previous_names":["dirmacs/niza","bkataru/niza"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/bkataru/niza","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bkataru%2Fniza","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bkataru%2Fniza/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bkataru%2Fniza/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bkataru%2Fniza/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bkataru","download_url":"https://codeload.github.com/bkataru/niza/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bkataru%2Fniza/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28398439,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-13T14:36:09.778Z","status":"ssl_error","status_checked_at":"2026-01-13T14:35:19.697Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","cross-platform","library","linux","macos","network","network-interface","network-interfaces","networking","windows","zig"],"created_at":"2026-01-13T19:56:23.672Z","updated_at":"2026-01-13T19:56:24.495Z","avatar_url":"https://github.com/bkataru.png","language":"Zig","funding_links":[],"categories":[],"sub_categories":[],"readme":"# niza\n\n**Cross-Platform Network Interface Library \u0026 CLI for Zig**\n\n[![Zig](https://img.shields.io/badge/Zig-0.15.2-orange)](https://ziglang.org/)\n[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](LICENSE)\n\nNiza is a pure Zig library and command-line tool for retrieving network interface information. It uses native OS APIs—no subprocess spawning—for fast, reliable interface enumeration across Linux, Windows, macOS, and BSD systems.\n\n## Features\n\n- 🚀 **Native OS APIs** - No subprocess spawning (no `ifconfig`/`ipconfig` calls)\n- 🌍 **Cross-Platform** - Linux, Windows, macOS, FreeBSD, NetBSD, OpenBSD, DragonFlyBSD\n- 📦 **Dual-Purpose** - Use as a library in your Zig projects or as a CLI tool\n- 🎨 **Beautiful CLI** - Colorized output with multiple display modes\n- 📋 **JSON Output** - Machine-readable output for scripting\n- 🔒 **Zero Dependencies** - Pure Zig, no external Zig/C libraries required\n- 🧪 **Well Tested** - Comprehensive unit and integration tests across platforms\n\n## Installation\n\n### As a Zig Package Dependency\n\nAdd niza to your `build.zig.zon`:\n\n```zig\n.dependencies = .{\n    .niza = .{\n        .url = \"https://github.com/bkataru/niza/archive/refs/tags/v0.1.0.tar.gz\",\n        .hash = \"...\",\n    },\n},\n```\n\nAlternatively, you can also add niza using `zig fetch`\n```shell\nzig fetch --save git+https://github.com/bkataru/niza.git\n```\n\nThen in your `build.zig`:\n\n```zig\nconst niza = b.dependency(\"niza\", .{\n    .target = target,\n    .optimize = optimize,\n});\n\nexe.root_module.addImport(\"niza\", niza.module(\"niza\"));\n```\n\n### Building from Source\n\n```bash\n# Clone the repository\ngit clone https://github.com/bkataru/niza.git\ncd niza\n\n# Build the CLI\nzig build\n\n# Run tests\nzig build test\n\n# Install to zig-out/bin\nzig build -Doptimize=ReleaseFast\n```\n\n## CLI Usage\n\n```\nniza [OPTIONS]\n\nOPTIONS:\n    -h, --help      Show help message\n    -a, --all       Show all interfaces (including inactive)\n    -6, --ipv6      Show IPv6 addresses\n    -m, --mac       Show MAC addresses\n    -j, --json      Output in JSON format\n    -q, --quiet     Quiet mode (minimal output)\n    -v, --version   Show version information\n    --no-color      Disable colored output\n```\n\n### Examples\n\n```bash\n# Show active interfaces with IPv4 addresses\nniza\n\n# Show all interfaces including inactive ones\nniza --all\n\n# Show all details including IPv6 and MAC addresses\nniza -a -6 -m\n\n# Output as JSON for scripting\nniza --json\n\n# Quiet mode - just interface names and IPs\nniza -q\n\n# Pipe to other tools\nniza --json | jq '.interfaces[] | select(.status == \"up\")'\n```\n\n### Sample Output\n\n```\n╔══════════════════════════════════════════╗\n║     niza - Network Interface Info        ║\n╚══════════════════════════════════════════╝\n\n● eth0 [up]\n  IPv4:  192.168.1.100\n\n● wlan0 [up]\n  IPv4:  192.168.1.101\n\n○ docker0 [down]\n  IPv4:  172.17.0.1\n\n─────────────────────────────────────────────\nDisplayed 3 interface(s), 2 active\n```\n\n### JSON Output\n\n```json\n{\n  \"interfaces\": [\n    {\n      \"name\": \"eth0\",\n      \"index\": 2,\n      \"status\": \"up\",\n      \"is_loopback\": false,\n      \"ipv4\": \"192.168.1.100\",\n      \"ipv6\": \"2001:db8::1\",\n      \"mac\": \"00:1a:2b:3c:4d:5e\",\n      \"netmask\": null\n    }\n  ],\n  \"count\": 1\n}\n```\n\n## Library Usage\n\n### Basic Example\n\n```zig\nconst std = @import(\"std\");\nconst niza = @import(\"niza\");\n\npub fn main() !void {\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    defer _ = gpa.deinit();\n    const allocator = gpa.allocator();\n\n    // Get all network interfaces\n    const interfaces = try niza.getNetworkInterfaces(allocator);\n    defer niza.freeNetworkInterfaces(allocator, interfaces);\n\n    for (interfaces) |iface| {\n        std.debug.print(\"Interface: {s}\\n\", .{iface.name});\n        std.debug.print(\"  Status: {s}\\n\", .{iface.status.toString()});\n        \n        if (iface.ipv4) |ip| {\n            std.debug.print(\"  IPv4: {s}\\n\", .{ip});\n        }\n        \n        if (iface.ipv6) |ip| {\n            std.debug.print(\"  IPv6: {s}\\n\", .{ip});\n        }\n        \n        if (iface.mac) |mac| {\n            std.debug.print(\"  MAC: {s}\\n\", .{mac});\n        }\n    }\n}\n```\n\n### API Reference\n\n#### Types\n\n##### `NetworkInterface`\n\nRepresents a network interface with its associated addresses and status.\n\n```zig\npub const NetworkInterface = struct {\n    /// Name of the interface (e.g., \"eth0\", \"wlan0\", \"Ethernet\")\n    name: []const u8,\n    \n    /// IPv4 address in dotted-decimal notation, or null if not assigned\n    ipv4: ?[]const u8,\n    \n    /// IPv6 address in colon-separated notation, or null if not assigned\n    ipv6: ?[]const u8,\n    \n    /// MAC/hardware address in colon-separated notation, or null if not available\n    mac: ?[]const u8,\n    \n    /// Subnet mask in dotted-decimal notation, or null if not available\n    netmask: ?[]const u8,\n    \n    /// Operational status of the interface\n    status: InterfaceStatus,\n    \n    /// Interface index (platform-specific identifier)\n    index: u32,\n    \n    /// Whether this is a loopback interface\n    is_loopback: bool,\n};\n```\n\n##### `InterfaceStatus`\n\n```zig\npub const InterfaceStatus = enum {\n    up,      // Interface is active and operational\n    down,    // Interface is down or not operational\n    unknown, // Status could not be determined\n    \n    pub fn toString(self: InterfaceStatus) []const u8;\n};\n```\n\n##### `NetworkError`\n\n```zig\npub const NetworkError = error{\n    SocketCreationFailed,\n    IoctlFailed,\n    AllocationFailed,\n    InvalidData,\n    UnsupportedPlatform,\n    NetlinkSendFailed,\n    NetlinkRecvFailed,\n    WindowsApiError,\n    SystemError,\n    OutOfMemory,\n};\n```\n\n#### Functions\n\n##### `getNetworkInterfaces`\n\n```zig\npub fn getNetworkInterfaces(allocator: Allocator) NetworkError![]NetworkInterface\n```\n\nRetrieves all network interfaces on the system using native OS APIs.\n\n**Returns:** A slice of `NetworkInterface` structs that must be freed with `freeNetworkInterfaces`.\n\n**Errors:**\n- `SocketCreationFailed`: Could not create socket for querying\n- `UnsupportedPlatform`: Current OS is not supported\n- `OutOfMemory`: Memory allocation failed\n\n##### `freeNetworkInterfaces`\n\n```zig\npub fn freeNetworkInterfaces(allocator: Allocator, interfaces: []NetworkInterface) void\n```\n\nFrees a slice of network interfaces previously allocated by `getNetworkInterfaces`.\n\n#### Utility Functions\n\n```zig\n/// Formats an IPv4 address from 4 bytes to a string\npub fn formatIpv4Address(allocator: Allocator, addr: [4]u8) ![]const u8\n\n/// Formats an IPv6 address from 16 bytes to a string\npub fn formatIpv6Address(allocator: Allocator, addr: [16]u8) ![]const u8\n\n/// Formats a MAC address from 6 bytes to a colon-separated string\npub fn formatMacAddress(allocator: Allocator, addr: [6]u8) ![]const u8\n\n/// Checks if an IPv4 address is a loopback address (127.x.x.x)\npub fn isLoopbackIpv4(addr: [4]u8) bool\n\n/// Checks if an IPv6 address is the loopback address (::1)\npub fn isLoopbackIpv6(addr: [16]u8) bool\n\n/// Checks if an IPv6 address is link-local (fe80::)\npub fn isLinkLocalIpv6(addr: [16]u8) bool\n```\n\n## Platform-Specific Implementation Details\n\n### Linux\n\nUses **Netlink sockets** (`NETLINK_ROUTE`) with `RTM_GETLINK` and `RTM_GETADDR` messages to enumerate interfaces and addresses. This is the most reliable and efficient method on Linux.\n\n### Windows\n\nUses the **IP Helper API** (`GetAdaptersAddresses` from `iphlpapi.dll`) to enumerate network adapters and their addresses. Supports both IPv4 and IPv6.\n\n### macOS / BSD\n\nUses the **`getifaddrs()`** system call via libc to enumerate interfaces. This works on macOS, FreeBSD, NetBSD, OpenBSD, and DragonFlyBSD.\n\n## Building for Different Platforms\n\n```bash\n# Native build\nzig build\n\n# Cross-compile for Linux x86_64\nzig build -Dtarget=x86_64-linux\n\n# Cross-compile for Windows x86_64\nzig build -Dtarget=x86_64-windows\n\n# Cross-compile for macOS ARM64\nzig build -Dtarget=aarch64-macos\n\n# Release build with optimizations\nzig build -Doptimize=ReleaseFast\n```\n\n## Running Tests\n\n```bash\n# Run all tests\nzig build test\n\n# Run tests with verbose output\nzig build test -- --verbose\n\n# Run only library tests\nzig test src/root.zig\n\n# Run only CLI tests\nzig test src/main.zig\n```\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add some amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## License\n\nThis project is licensed under the GNU General Public License - see the [LICENSE](LICENSE) file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbkataru%2Fniza","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbkataru%2Fniza","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbkataru%2Fniza/lists"}