From 586fe0c704ee9032f503ff72c3455437a75b44c8 Mon Sep 17 00:00:00 2001 From: Giuliano Bellini s294739 Date: Thu, 14 Mar 2024 10:18:12 +0100 Subject: [PATCH] update docs --- README.md | 18 ++++++++---------- src/lib.rs | 2 ++ src/main.rs | 1 + src/platform/bsd/mod.rs | 8 +++++--- src/platform/linux/mod.rs | 25 +++++++++++++++++++++++++ src/platform/macos/mod.rs | 25 +++++++++++++++++++++++++ src/platform/windows/mod.rs | 25 +++++++++++++++++++++++++ 7 files changed, 91 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 814c3a0..93843db 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# Listene***rs*** +# Listene*rs* [![Crates](https://img.shields.io/crates/v/listeners?&logo=rust)](https://crates.io/crates/listeners) [![Docs](https://docs.rs/listeners/badge.svg)](https://docs.rs/listeners/latest/) @@ -9,19 +9,17 @@ ## Motivation Despite some Rust libraries to get process information already exist, -none of them satisfies my need to get process ID and name of TCP listeners in a cross-platform way. +none of them satisfies the need to get process ID and name of TCP listeners in a cross-platform way. Some examples of existing libraries: - [netstat2](https://crates.io/crates/netstat2): doesn't provide the process name (and it's unmaintained) - [libproc](https://crates.io/crates/libproc): only for Linux and macOS - [sysinfo](https://crates.io/crates/sysinfo): doesn't expose the sockets used by each process -This library wants to fill this gap . - -It aims to be: -- **Cross-platform**: it currently works on Windows, Linux and macOS -- **Performant**: it uses low-level system APIs -- **Simple**: it provides a single function to get all the listening processes +This library wants to fill this gap, and it aims to be: +- **Cross-platform**: it currently supports Windows, Linux and macOS +- **Performant**: it internally uses low-level system APIs +- **Simple**: it exposes a single API to get all the listening processes - **Lightweight**: it has only the strictly necessary dependencies ## Roadmap @@ -43,7 +41,7 @@ Add this to your `Cargo.toml`: listeners = "0.1" ``` -Get the listener processes: +Get the listening processes: ``` rust let listeners = listeners::get_all().unwrap(); @@ -56,7 +54,7 @@ for l in listeners { Output: ``` text -PID: 1088 Process name: rustrover Socket: 127.0.0.1:63342 +PID: 1088 Process name: rustrover Socket: [::7f00:1]:63342 PID: 609 Process name: Microsoft SharePoint Socket: [::1]:42050 PID: 160 Process name: mysqld Socket: [::]:33060 PID: 160 Process name: mysqld Socket: [::]:3306 diff --git a/src/lib.rs b/src/lib.rs index d6eb195..b31bc1c 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,3 +1,5 @@ +#![doc = include_str!("../README.md")] + use std::fmt::Display; use std::net::SocketAddr; diff --git a/src/main.rs b/src/main.rs index da3f5a3..4325539 100644 --- a/src/main.rs +++ b/src/main.rs @@ -1,5 +1,6 @@ fn main() { let listeners = listeners::get_all().unwrap(); + for l in listeners { println!("{l}"); } diff --git a/src/platform/bsd/mod.rs b/src/platform/bsd/mod.rs index 97c7a2f..bf89a8b 100644 --- a/src/platform/bsd/mod.rs +++ b/src/platform/bsd/mod.rs @@ -1,7 +1,9 @@ -use bsd_kvm::{Access, KernProc, Kvm}; +use std::collections::HashSet; +// use bsd_kvm::{Access, KernProc, Kvm}; +use crate::Listener; -pub fn get_all() { - todo!("Implement get_all for BSD"); +pub fn get_all() -> crate::Result> { + Err("Not implemented yet".into()) // let mut kvm = Kvm::open::<&str>(None, None, Access::ReadOnly).unwrap(); // let procs = kvm.get_process(KernProc::All, 0); // for p in procs { diff --git a/src/platform/linux/mod.rs b/src/platform/linux/mod.rs index bc3c6d1..8662056 100644 --- a/src/platform/linux/mod.rs +++ b/src/platform/linux/mod.rs @@ -12,6 +12,31 @@ mod proc_info; mod statics; mod tcp_listener; +/// Returns the list of all processes listening on a TCP port. +/// +/// # Errors +/// +/// This function returns an error if it fails to get the list of processes for the current platform. +/// +/// # Example +/// +/// ``` rust +/// let listeners = listeners::get_all().unwrap(); +/// +/// for l in listeners { +/// println!("{l}"); +/// } +/// ``` +/// +/// Output: +/// ``` text +/// PID: 1088 Process name: rustrover Socket: [::7f00:1]:63342 +/// PID: 609 Process name: Microsoft SharePoint Socket: [::1]:42050 +/// PID: 160 Process name: mysqld Socket: [::]:33060 +/// PID: 160 Process name: mysqld Socket: [::]:3306 +/// PID: 460 Process name: rapportd Socket: 0.0.0.0:50928 +/// PID: 460 Process name: rapportd Socket: [::]:50928 +/// ``` pub fn get_all() -> crate::Result> { let mut listeners = HashSet::new(); diff --git a/src/platform/macos/mod.rs b/src/platform/macos/mod.rs index 82b52e8..69f1cc0 100644 --- a/src/platform/macos/mod.rs +++ b/src/platform/macos/mod.rs @@ -16,6 +16,31 @@ mod socket_fd; mod statics; mod tcp_listener; +/// Returns the list of all processes listening on a TCP port. +/// +/// # Errors +/// +/// This function returns an error if it fails to get the list of processes for the current platform. +/// +/// # Example +/// +/// ``` rust +/// let listeners = listeners::get_all().unwrap(); +/// +/// for l in listeners { +/// println!("{l}"); +/// } +/// ``` +/// +/// Output: +/// ``` text +/// PID: 1088 Process name: rustrover Socket: [::7f00:1]:63342 +/// PID: 609 Process name: Microsoft SharePoint Socket: [::1]:42050 +/// PID: 160 Process name: mysqld Socket: [::]:33060 +/// PID: 160 Process name: mysqld Socket: [::]:3306 +/// PID: 460 Process name: rapportd Socket: 0.0.0.0:50928 +/// PID: 460 Process name: rapportd Socket: [::]:50928 +/// ``` pub fn get_all() -> crate::Result> { let mut listeners = HashSet::new(); diff --git a/src/platform/windows/mod.rs b/src/platform/windows/mod.rs index e7040f3..e231f50 100644 --- a/src/platform/windows/mod.rs +++ b/src/platform/windows/mod.rs @@ -9,6 +9,31 @@ mod tcp6_table; mod tcp_listener; mod tcp_table; +/// Returns the list of all processes listening on a TCP port. +/// +/// # Errors +/// +/// This function returns an error if it fails to get the list of processes for the current platform. +/// +/// # Example +/// +/// ``` rust +/// let listeners = listeners::get_all().unwrap(); +/// +/// for l in listeners { +/// println!("{l}"); +/// } +/// ``` +/// +/// Output: +/// ``` text +/// PID: 1088 Process name: rustrover Socket: [::7f00:1]:63342 +/// PID: 609 Process name: Microsoft SharePoint Socket: [::1]:42050 +/// PID: 160 Process name: mysqld Socket: [::]:33060 +/// PID: 160 Process name: mysqld Socket: [::]:3306 +/// PID: 460 Process name: rapportd Socket: 0.0.0.0:50928 +/// PID: 460 Process name: rapportd Socket: [::]:50928 +/// ``` pub fn get_all() -> crate::Result> { let mut listeners = HashSet::new();