pub use of mods (#126)

* pub use mods of libproc to clean up the API

* Re-exports and restructuring of docs for re-exported modules

* Re-exports and restructuring of docs for re-exported modules

* Re-exports and restructuring of docs for re-exported modules

Author: andrewdavidmackenzie

Makefile

@@ -3,7 +3,7 @@ all: clippy run-tests build-docs
 
 .PHONY: clippy
 clippy:
-	cargo clippy --all --tests --all-targets --all-features -- --warn clippy::pedantic -D warnings
+	cargo clippy --all --tests --no-deps --all-targets --all-features -- --warn clippy::pedantic -D warnings
 
 .PHONY: configure-coverage
 configure-coverage:

examples/dmesg.rs

@@ -1,19 +1,17 @@
-//! A `dmesg` command that is a simple demonstration program for using the [`libproc`](../libproc/index.html) library
+//! A `dmesg` command that is a simple demonstration program for using
+//! the `libproc` library
 //!
 //! Usage
 //! =
 //!
 //! `> dmesg`
 //!
 
-extern crate libproc;
-extern crate libc;
-
-use crate::libproc::libproc::kmesg_buffer;
+use libproc::kmesg_buffer;
 
 fn main() {
     match kmesg_buffer::kmsgbuf() {
         Ok(message) => print!("{message}"),
-        Err(e) => eprintln!("{e}")
+        Err(e) => eprintln!("{e}"),
     }
-}
+}

examples/procinfo.rs

@@ -1,5 +1,4 @@
-//! `procinfo` is a simple program to demonstrate the use of the [`libproc`](../libproc/index.html)
-//! library functions.
+//! `procinfo` is a simple program to demonstrate the use of the `libproc` library.
 //!
 //! It prints out info about a process specified by its pid, or the current process if no pid
 //! specified.
@@ -23,54 +22,39 @@
 //! ...
 //! ```
 
-extern crate libproc;
-extern crate libc;
-
+use libproc::pid_rusage::{pidrusage, RUsageInfoV0};
+use libproc::proc_pid;
+use libproc::processes;
 use std::env;
 use std::io::Write;
-use libproc::libproc::proc_pid;
-use libproc::libproc::pid_rusage::{pidrusage, RUsageInfoV0};
-use libproc::processes;
-
-mod c {
-    extern crate libc;
-    extern {
-        pub fn getpid() -> libc::pid_t;
-    }
-}
-
-fn getpid() -> i32 {
-    unsafe {
-        c::getpid()
-    }
-}
+use std::process;
 
 fn procinfo(pid: i32) {
     match proc_pid::libversion() {
         Ok((major, minor)) => println!("Libversion: {major}.{minor}"),
-        Err(err) => writeln!(&mut std::io::stderr(), "Error: {err}").unwrap()
+        Err(err) => writeln!(&mut std::io::stderr(), "Error: {err}").unwrap(),
     }
 
     println!("Pid: {pid}");
 
     match proc_pid::pidpath(pid) {
         Ok(path) => println!("Path: {path}"),
-        Err(err) => writeln!(&mut std::io::stderr(), "Error: {err}").unwrap()
+        Err(err) => writeln!(&mut std::io::stderr(), "Error: {err}").unwrap(),
     }
 
     match pidrusage::<RUsageInfoV0>(pid) {
         Ok(resource_usage) => println!("Memory Used: {} Bytes", resource_usage.ri_resident_size),
-        Err(err) => writeln!(&mut std::io::stderr(), "Error: {err}").unwrap()
+        Err(err) => writeln!(&mut std::io::stderr(), "Error: {err}").unwrap(),
     }
 
     match proc_pid::name(pid) {
         Ok(name) => println!("Name: {name}"),
-        Err(err) => writeln!(&mut std::io::stderr(), "Error: {err}").unwrap()
+        Err(err) => writeln!(&mut std::io::stderr(), "Error: {err}").unwrap(),
     }
 
     match proc_pid::regionfilename(pid, 0) {
         Ok(regionfilename) => println!("Region Filename (at address 0): {regionfilename}"),
-        Err(err) => writeln!(&mut std::io::stderr(), "Error: {err}").unwrap()
+        Err(err) => writeln!(&mut std::io::stderr(), "Error: {err}").unwrap(),
     }
 
     match processes::pids_by_type(processes::ProcFilter::All) {
@@ -79,19 +63,22 @@ fn procinfo(pid: i32) {
             for pid in pids {
                 println!("{pid}");
             }
-        },
-        Err(err) => writeln!(&mut std::io::stderr(), "Error: {err}").unwrap()
+        }
+        Err(err) => writeln!(&mut std::io::stderr(), "Error: {err}").unwrap(),
     }
 }
 
+/// Print out some information about the current process (if no arguments provided)
+/// or a particular process (by passing that process's PID as the first argument
 fn main() {
     let args: Vec<String> = env::args().collect();
 
     let pid = if args.len() == 1 {
-       getpid()
+        process::id()
     } else {
-        args[1].clone().parse::<i32>().unwrap()
+        args[1].clone().parse::<u32>().unwrap()
     };
 
-    procinfo(pid);
-}
+    #[allow(clippy::cast_possible_wrap)]
+    procinfo(pid as i32);
+}

src/lib.rs

@@ -5,54 +5,62 @@
 //!
 //! Not all methods are available on both Operating Systems yet, but more will be made
 //! cross-platform over time.
+//!
+//! Get information (such as name, path, process info, fd) about running processes by pid, process type, etc.
+//!
+//! At the moment these methods have been implemented, most of which have examples in their docs:
+//!
 
-extern crate errno;
-extern crate libc;
-
-/// Get information (such as name, path, process info, fd) about running processes by pid, process type, etc.
-/// At the moment these methods have been implemented, most of which have examples in their docs:
-///
-/// # `libproc::libproc` (names that way for bad, historical reasons!)
-/// ## Process / PID related
-/// `pub fn listpids(proc_types: ProcType) -> Result<Vec<u32>, String> (macos) (linux)`
-///
-///  `pub fn listpidspath(proc_types: ProcType, path: &str) -> Result<Vec<u32>, String> (macos) (linux)`
-///
-///  `pub fn pidinfo<T: PIDInfo>(pid : i32, arg: u64) -> Result<T, String> (macos)`
-///
-///  `pub fn regionfilename(pid: i32, address: u64) -> Result<String, String> (macos)`
-///
-///  `pub fn pidpath(pid : i32) -> Result<String, String> (macos) (linux)`
-///
-///  `pub fn libversion() -> Result<(i32, i32), String> (macos)`
-///
-///  `pub fn name(pid: i32) -> Result<String, String> (linux) (macos)`
-///
-///  `pub fn listpidinfo<T: ListPIDInfo>(pid : i32, max_len: usize) -> Result<Vec<T::Item>, String> (macos)`
-///
-///  `pub fn pidcwd(pid: pid_t) -> Result<PathBuf, String> (linux)`
-///
-///  `pub fn cwdself() -> Result<PathBuf, String> (linux)`
-///
-///  ## File and FileDescriptor related
-///  `pub fn pidfdinfo<T: PIDFDInfo>(pid : i32, fd: i32) -> Result<T, String> (macos)`
-///
-///  ## PID Resource Usage related
-///  (Added in Mac OS X 10.9 - under "macosx_10_9" feature)
-///  `pub fn pidrusage<T: PIDRUsage>(pid : i32) -> Result<T, String> (macos)`
-///
-///  ## Kernel Message Buffer - kmsgbuf
-///  `pub fn kmsgbuf() -> Result<String, String>`
-pub mod libproc;
 /// List processes by type, path or by type and path.
-///
-///  `pub fn pids_by_type(filter: ProcFilter)` (macos) (linux)
-///
-///  `pub fn pids_by_path(path: &Path, is_volume: bool, exclude_event_only: bool)` (macos)
-///
-///  `pub fn pids_by_type_and_path(filter: ProcFilter, path: &Path, is_volume: bool, exclude_event_only: bool)` (macos)
 pub mod processes;
 
+#[doc(inline)]
+/// Get information about processes using mainly the `pid`
+pub use libproc::proc_pid;
+
+#[doc(inline)]
+/// Read messages from the Kernel Message Buffer
+pub use libproc::kmesg_buffer;
+
+#[doc(inline)]
+/// Get information about resource usage of processes
+pub use libproc::pid_rusage;
+
+#[cfg(any(target_os = "macos", doc))]
+#[doc(inline)]
+/// Get information specific to BSD/Darwin on macos
+pub use libproc::bsd_info;
+
+#[cfg(any(target_os = "macos", doc))]
+#[doc(inline)]
+/// Get information about a process's use of different types of file descriptors
+pub use libproc::file_info;
+
+#[cfg(any(target_os = "macos", doc))]
+#[doc(inline)]
+/// Get information about a processes use of network, sockets etc.
+pub use libproc::net_info;
+
+#[cfg(any(target_os = "macos", doc))]
+#[doc(inline)]
+/// Get information about a process's BSD Tasks
+pub use libproc::task_info;
+
+#[cfg(any(target_os = "macos", doc))]
+#[doc(inline)]
+/// Get information about threads within a process
+pub use libproc::thread_info;
+
+#[cfg(any(target_os = "macos", doc))]
+#[doc(inline)]
+/// Get information about Work Queues
+pub use libproc::work_queue_info;
+
+// Not documenting this as this export is legacy, and replaced by all the re-exports of
+// sub-modules above
+#[doc(hidden)]
+pub mod libproc;
+
 #[cfg(target_os = "macos")]
 #[allow(warnings, missing_docs)]
 mod osx_libproc_bindings {

src/libproc/bsd_info.rs

@@ -1,6 +1,10 @@
 use crate::libproc::proc_pid::{PIDInfo, PidInfoFlavor};
+#[cfg(target_os = "macos")]
 pub use crate::osx_libproc_bindings::proc_bsdinfo as BSDInfo;
 
+#[cfg(target_os = "macos")]
 impl PIDInfo for BSDInfo {
-    fn flavor() -> PidInfoFlavor { PidInfoFlavor::TBSDInfo }
+    fn flavor() -> PidInfoFlavor {
+        PidInfoFlavor::TBSDInfo
+    }
 }

src/libproc/file_info.rs

@@ -1,14 +1,11 @@
-extern crate libc;
-
-use std::mem;
-
 use crate::libproc::helpers;
 use crate::libproc::proc_pid::{ListPIDInfo, PidInfoFlavor};
+use std::mem;
 
-#[cfg(target_os = "macos")]
-use self::libc::c_void;
 #[cfg(target_os = "macos")]
 use crate::osx_libproc_bindings::proc_pidfdinfo;
+#[cfg(target_os = "macos")]
+use libc::c_void;
 
 /// Flavor of Pid `FileDescriptor` info for different types of File Descriptors
 pub enum PIDFDInfoFlavor {

src/libproc/helpers.rs

@@ -1,4 +1,4 @@
-use crate::errno::errno;
+use errno::errno;
 #[cfg(any(target_os = "linux", target_os = "redox", target_os = "android"))]
 use std::fs::File;
 #[cfg(any(target_os = "linux", target_os = "redox", target_os = "android"))]
@@ -87,7 +87,7 @@ pub fn parse_memory_string(line: &str) -> Result<u64, String> {
 #[cfg(test)]
 mod test {
     use super::check_errno;
-    use crate::errno::{set_errno, Errno};
+    use errno::{set_errno, Errno};
 
     #[cfg(any(target_os = "linux", target_os = "redox", target_os = "android"))]
     mod linux {

src/libproc/kmesg_buffer.rs

@@ -1,11 +1,8 @@
-extern crate errno;
-extern crate libc;
-
 #[cfg(target_os = "macos")]
 use std::str;
 
 #[cfg(target_os = "macos")]
-use self::libc::c_void;
+use libc::c_void;
 
 #[cfg(any(target_os = "linux", target_os = "redox", target_os = "android"))]
 use std::fs::File;
@@ -21,16 +18,23 @@ use std::{thread, time};
 #[cfg(target_os = "macos")]
 use crate::osx_libproc_bindings::{proc_kmsgbuf, MAXBSIZE as MAX_MSG_BSIZE};
 
-/// Get the contents of the kernel message buffer
+#[cfg(any(target_os = "macos", doc))]
+/// Read messages from the kernel message buffer
 ///
 /// Entries are in the format:
 /// faclev,seqnum,timestamp[optional, ...];message\n
 ///  TAGNAME=value (0 or more Tags)
 /// See <http://opensource.apple.com//source/system_cmds/system_cmds-336.6/dmesg.tproj/dmesg.c>
 ///
+/// On linux:
+/// Turns out that reading to the end of an "infinite file" like "/dev/kmsg" with standard file
+/// reading methods will block at the end of file, so a workaround is required. Do the blocking
+/// reads on a thread that sends lines read back through a channel, and then return when the thread
+/// has blocked and can't send anymore. Returning will end the thread and the channel.
+///
 /// # Errors
 ///
-/// Will return an `Err` if Darwin's method `proc_kmsgbuf` returns an empty message buffer
+/// An `Err` will be returned if `/dev/kmsg` device cannot be read
 #[cfg(target_os = "macos")]
 pub fn kmsgbuf() -> Result<String, String> {
     let mut message_buffer: Vec<u8> = Vec::with_capacity(MAX_MSG_BSIZE as _);
@@ -60,16 +64,6 @@ pub fn kmsgbuf() -> Result<String, String> {
     }
 }
 
-/// Get a message (String) from the kernel message ring buffer
-/// Turns out that reading to the end of an "infinite file" like "/dev/kmsg" with standard file
-/// reading methods will block at the end of file, so a workaround is required. Do the blocking
-/// reads on a thread that sends lines read back through a channel, and then return when the thread
-/// has blocked and can't send anymore. Returning will end the thread and the channel.
-///
-/// # Errors
-///
-/// An `Err` will be returned if `/dev/kmsg` device cannot be read
-///
 #[cfg(any(target_os = "linux", target_os = "redox", target_os = "android"))]
 pub fn kmsgbuf() -> Result<String, String> {
     let mut file = File::open("/dev/kmsg");