0.2.0 (#2)

- Refactor `IfNet` and add `Ifv4Net`, `Ifv6Net`, `IfAddr`, `Ifv4Addr` and `Ifv6Addr`
- Add `interface_addrs`, `interface_ipv4_addrs`, `interface_ipv6_addrs`, `interface_addrs_by_filter`, `interface_ipv4_addrs_by_filter`, and `interface_ipv6_addrs_by_filter`
- Add `interface_multicast_addrs`, `interface_multicast_ipv4_addrs`, `interface_multicast_ipv6_addrs`, `interface_multicast_addrs_by_filter`, `interface_multcast_ipv4_addrs_by_filter` and `interface_multcast_ipv6_addrs_by_filter`
- Add `gateway_addrs`, `gateway_ipv4_addrs`, `gateway_ipv6_addrs`, `gateway_addrs_by_filter`, `gateway_ipv4_addrs_by_filter` and `gateway_ipv6_addrs_by_filter`
- Add `local_addrs`, `local_ipv4_addrs`, `local_ipv6_addrs`, `local_addrs_by_filter`, `local_ipv4_addrs_by_filter` and `local_ipv6_addrs_by_filter`
- Add `private_addrs`, `private_ipv4_addrs`, `private_ipv6_addrs`, `private_addrs_by_filter`, `private_ipv4_addrs_by_filter`, `private_ipv6_addrs_by_filter`
- Add `public_addrs`, `public_ipv4_addrs`, `public_ipv6_addrs`, `public_addrs_by_filter`, `public_ipv4_addrs_by_filter`, and `public_ipv6_addrs_by_filter`
- Add `ifindex_to_name` and `ifname_to_index`

Author: al8n

.codecov.yml

@@ -5,6 +5,9 @@ ignore:
   - src/tests
   - src/tests.rs
   - tests
+  - src/bsd_like # Ignore becasue cargo-tarpaulin does not support BSD-like OSes
+  - src/bsd_like.rs # Ignore becasue cargo-tarpaulin does not support BSD-like OSes
+  - examples/
 
 coverage:
   status:

.github/workflows/coverage.yml

@@ -46,7 +46,7 @@ jobs:
       - name: Run Coverage and Generate Report
         run: |
           mkdir -p coverage
-          cargo tarpaulin --tests --avoid-cfg-tarpaulin --skip-clean --exclude-files "target/*" --out xml --output-dir coverage/${{ matrix.os }} -j 1
+          cargo tarpaulin --run-types Doctests --run-types Tests --run-types Lib --out xml --output-dir coverage/${{ matrix.os }} -j 1
         continue-on-error: true
       - name: Upload Coverage Report as Artifact
         uses: actions/upload-artifact@v4

CHANGELOG.md

@@ -1,7 +1,12 @@
-# UNRELEASED
-
-# 0.1.2 (January 6th, 2022)
-
-FEATURES
-
-
+# RELEASED
+
+## 0.2.0 (January 19th, 2025)
+
+- Refactor `IfNet` and add `Ifv4Net`, `Ifv6Net`, `IfAddr`, `Ifv4Addr` and `Ifv6Addr`
+- Add `interface_addrs`, `interface_ipv4_addrs`, `interface_ipv6_addrs`, `interface_addrs_by_filter`, `interface_ipv4_addrs_by_filter`, and `interface_ipv6_addrs_by_filter`
+- Add `interface_multicast_addrs`, `interface_multicast_ipv4_addrs`, `interface_multicast_ipv6_addrs`, `interface_multicast_addrs_by_filter`, `interface_multcast_ipv4_addrs_by_filter` and `interface_multcast_ipv6_addrs_by_filter`
+- Add `gateway_addrs`, `gateway_ipv4_addrs`, `gateway_ipv6_addrs`, `gateway_addrs_by_filter`, `gateway_ipv4_addrs_by_filter` and `gateway_ipv6_addrs_by_filter`
+- Add `local_addrs`, `local_ipv4_addrs`, `local_ipv6_addrs`, `local_addrs_by_filter`, `local_ipv4_addrs_by_filter` and `local_ipv6_addrs_by_filter`
+- Add `private_addrs`, `private_ipv4_addrs`, `private_ipv6_addrs`, `private_addrs_by_filter`, `private_ipv4_addrs_by_filter`, `private_ipv6_addrs_by_filter`
+- Add `public_addrs`, `public_ipv4_addrs`, `public_ipv6_addrs`, `public_addrs_by_filter`, `public_ipv4_addrs_by_filter`, and `public_ipv6_addrs_by_filter`
+- Add `ifindex_to_name` and `ifname_to_index`

Cargo.toml

@@ -5,15 +5,25 @@ edition = "2021"
 repository = "https://github.com/al8n/getifs"
 homepage = "https://github.com/al8n/getifs"
 documentation = "https://docs.rs/getifs"
-description = "Get network interfaces information (including MTU) in a fast way (say bye to `libc::getifaddrs`)."
+description = "Cross-platform network tools, a bunch of network tools for fetching interfaces, multicast addresses, local ip addresses, private ip addresses, public ip addresses and etc."
 license = "MIT OR Apache-2.0"
 rust-version = "1.57.0"
 keywords = ["ifaddrs", "interface", "network-interface", "mtu", "getifaddrs"]
 categories = ["network-programming"]
 
 [[bench]]
-path = "benches/bench.rs"
-name = "bench"
+path = "benches/interfaces.rs"
+name = "interfaces"
+harness = false
+
+[[bench]]
+path = "benches/local_ip_address.rs"
+name = "local_ip_address"
+harness = false
+
+[[bench]]
+path = "benches/gateway.rs"
+name = "gateway"
 harness = false
 
 [features]
@@ -25,9 +35,13 @@ bitflags = "2"
 either = "1"
 hardware-address = "0.1"
 iprobe = "0.1"
+ipnet = "2"
+iprfc = "0.2"
+paste = "1"
 smol_str = "0.3"
 smallvec-wrapper = "0.2"
-ipnet = "2"
+triomphe = "0.1"
+
 
 # serde = { version = "1", features = ["derive"], optional = true }
 
@@ -44,6 +58,7 @@ widestring = "1"
 [dev-dependencies]
 criterion = "0.5"
 network-interface = "2"
+local-ip-address = "0.6"
 which = "7"
 scopeguard = "1"
 

README.md

@@ -1,9 +1,9 @@
 <div align="center">
-<h1>Get Interfaces</h1>
+<h1>GetIfs</h1>
 </div>
 <div align="center">
 
-Get network interfaces information (including MTU) in a fast way (say bye to `libc::getifaddrs`).
+Cross-platform network tools, a bunch of network tools for fetching interfaces, multicast addresses, local ip addresses, private ip addresses, public ip addresses and etc.
 
 [<img alt="github" src="https://img.shields.io/badge/github-al8n/getifs-8da0cb?style=for-the-badge&logo=Github" height="22">][Github-url]
 <img alt="LoC" src="https://img.shields.io/endpoint?url=https%3A%2F%2Fgist.githubusercontent.com%2Fal8n%2F327b2a8aef9003246e45c6e47fe63937%2Fraw%2Fgetifs" height="22">
@@ -17,26 +17,47 @@ Get network interfaces information (including MTU) in a fast way (say bye to `li
 
 </div>
 
+## Introduction
+
+Cross-platform network tools, a bunch of network tools for fetching interfaces, multicast addresses, local ip addresses, private ip addresses, public ip addresses and etc.
+
 ## Installation
 
 ```toml
 [dependencies]
-getifs = "0.1"
+getifs = "0.2"
 ```
 
+## Examples
+
+- Fetching all interfaces: [examples/interfaces.rs](./examples/interfaces.rs)
+- Fetching all interface addresses (excluding multicast addrs): [examples/addrs.rs](./examples/addrs.rs)
+- Fetching all interface multicast addresses: [exampels/multicast_addrs.rs](./examples/multicast_addrs.rs)
+- Fetching gateway addresses: [examples/gateway.rs](./examples/gateway.rs)
+- Fetching local ip addresses: [examples/local_ip_addrs.rs](./examples/local_ip_addrs.rs)
+- Fetching ip addresses by RFC: [examples/filter_by_rfc.rs](./examples/filter_by_rfc.rs)
+
 ## Details
 
 OS | Approach
 --- | ---
 Linux | `socket(AF_NETLINK, SOCK_RAW \| SOCK_CLOEXEC, NETLINK_ROUTE)`
-BSD-based | Uses of `sysctl` to retrieve network interfaces
+BSD-like | `sysctl`
 Windows | `GetAdaptersAddresses`
 
 ## Why a new network interfaces crate?
 
 Because all of current network interfaces crates do not support fetching `MTU`, and almost all of them are using `libc::getifaddrs`. This crate
 tries to avoid unneeded allocation and use more underlying method to achieve the same functionalities.
 
+## Roadmap
+
+- [ ] Support fetching routing tables (0.3.0)
+
+## Pedigree
+
+- The code in this crate is inspired by Golang's `interface.go` and [HashiCorp's go-sockaddr](https://github.com/hashicorp/go-sockaddr).
+
 #### License
 
 `getifs` is under the terms of both the MIT license and the
@@ -51,4 +72,3 @@ Copyright (c) 2025 Al Liu.
 [doc-url]: https://docs.rs/getifs
 [crates-url]: https://crates.io/crates/getifs
 [codecov-url]: https://app.codecov.io/gh/al8n/getifs/
-[zh-cn-url]: https://github.com/al8n/getifs/tree/main/README-zh_CN.md

benches/gateway.rs

@@ -0,0 +1,25 @@
+use criterion::*;
+
+fn bench_getifs_gateway_ipv4(c: &mut Criterion) {
+  c.bench_function("getifs::gateway_ipv4_addrs", |b| {
+    b.iter(|| {
+      getifs::gateway_ipv4_addrs().unwrap();
+    })
+  });
+}
+
+fn bench_getifs_gateway_ipv6(c: &mut Criterion) {
+  c.bench_function("getifs::gateway_ipv6_addrs", |b| {
+    b.iter(|| {
+      getifs::gateway_ipv6_addrs().unwrap();
+    })
+  });
+}
+
+criterion_group!(
+  benches,
+  bench_getifs_gateway_ipv4,
+  bench_getifs_gateway_ipv6,
+);
+
+criterion_main!(benches);

benches/bench.rs renamed to benches/interfaces.rs

@@ -0,0 +1,43 @@
+use criterion::*;
+
+fn bench_getifs_local_ipv4(c: &mut Criterion) {
+  c.bench_function("getifs::local_ipv4_addrs", |b| {
+    b.iter(|| {
+      getifs::local_ipv4_addrs().unwrap();
+    })
+  });
+}
+
+fn bench_getifs_local_ipv6(c: &mut Criterion) {
+  c.bench_function("getifs::local_ipv6_addrs", |b| {
+    b.iter(|| {
+      getifs::local_ipv6_addrs().unwrap();
+    })
+  });
+}
+
+fn bench_local_ip_address_local_ipv4(c: &mut Criterion) {
+  c.bench_function("local_ip_address::local_ip", |b| {
+    b.iter(|| {
+      local_ip_address::local_ip().unwrap();
+    })
+  });
+}
+
+fn bench_local_ip_address_local_ipv6(c: &mut Criterion) {
+  c.bench_function("local_ip_address::local_ipv6", |b| {
+    b.iter(|| {
+      local_ip_address::local_ipv6().unwrap();
+    })
+  });
+}
+
+criterion_group!(
+  benches,
+  bench_getifs_local_ipv4,
+  bench_getifs_local_ipv6,
+  bench_local_ip_address_local_ipv4,
+  bench_local_ip_address_local_ipv6,
+);
+
+criterion_main!(benches);

benches/local_ip_address.rs

@@ -0,0 +1,8 @@
+use getifs::interface_addrs;
+
+fn main() {
+  let addrs = interface_addrs().unwrap();
+  for addr in addrs {
+    println!("IP addr: {}", addr);
+  }
+}

ci/miri_sb.sh

@@ -0,0 +1,8 @@
+use getifs::{interface_addrs_by_filter, rfc};
+
+fn main() {
+  let addrs = interface_addrs_by_filter(|addr| rfc::RFC3330.contains(addr)).unwrap();
+  for addr in addrs {
+    println!("RFC3330 IP addr: {}", addr);
+  }
+}

ci/miri_tb.sh

@@ -0,0 +1,8 @@
+use getifs::gateway_addrs;
+
+fn main() {
+  let gateways = gateway_addrs().unwrap();
+  for gw in gateways {
+    println!("Gateway: {}", gw);
+  }
+}

examples/addrs.rs

@@ -0,0 +1,8 @@
+use getifs::interfaces;
+
+fn main() {
+  let ift = interfaces().unwrap();
+  for ifi in ift {
+    println!("{:?}", ifi);
+  }
+}

examples/filter_by_rfc.rs

@@ -0,0 +1,8 @@
+use getifs::local_addrs;
+
+fn main() {
+  let addrs = local_addrs().unwrap();
+  for addr in addrs {
+    println!("Local IP addr: {}", addr);
+  }
+}

examples/foo.rs

@@ -0,0 +1,8 @@
+use getifs::interface_multicast_addrs;
+
+fn main() {
+  let ift = interface_multicast_addrs().unwrap();
+  for ifa in ift {
+    println!("{}", ifa);
+  }
+}