vendor/sysinfo/README.md

   1 # sysinfo ![img_github_ci] [![][img_crates]][crates] [![][img_doc]][doc]
   2
   3 `sysinfo` is a crate used to get a system's information.
   4
   5 ## Supported Oses
   6
   7 It currently supports the following OSes (alphabetically sorted):
   8
   9  * Android
  10  * FreeBSD
  11  * iOS
  12  * Linux
  13  * macOS
  14  * Raspberry Pi
  15  * Windows
  16
  17 You can still use `sysinfo` on non-supported OSes, it'll simply do nothing and always return
  18 empty values. You can check in your program directly if an OS is supported by checking the
  19 [`SystemExt::IS_SUPPORTED`] constant.
  20
  21 The minimum-supported version of `rustc` is **1.54**.
  22
  23 ## Usage
  24
  25 ⚠️ Before any attempt to read the different structs' information, you need to update them to
  26 get up-to-date information because for most of them, it works on diff between the current value
  27 and the old one.
  28
  29 Which is why, it's much better to keep the same instance of [`System`] around instead of
  30 recreating it multiple times.
  31
  32 You have an example into the `examples` folder. You can run it with `cargo run --example simple`.
  33
  34 Otherwise, here is a little code sample:
  35
  36 ```rust
  37 use sysinfo::{NetworkExt, NetworksExt, ProcessExt, System, SystemExt};
  38
  39 // Please note that we use "new_all" to ensure that all list of
  40 // components, network interfaces, disks and users are already
  41 // filled!
  42 let mut sys = System::new_all();
  43
  44 // First we update all information of our `System` struct.
  45 sys.refresh_all();
  46
  47 // We display all disks' information:
  48 println!("=> disks:");
  49 for disk in sys.disks() {
  50     println!("{:?}", disk);
  51 }
  52
  53 // Network interfaces name, data received and data transmitted:
  54 println!("=> networks:");
  55 for (interface_name, data) in sys.networks() {
  56     println!("{}: {}/{} B", interface_name, data.received(), data.transmitted());
  57 }
  58
  59 // Components temperature:
  60 println!("=> components:");
  61 for component in sys.components() {
  62     println!("{:?}", component);
  63 }
  64
  65 println!("=> system:");
  66 // RAM and swap information:
  67 println!("total memory: {} KB", sys.total_memory());
  68 println!("used memory : {} KB", sys.used_memory());
  69 println!("total swap  : {} KB", sys.total_swap());
  70 println!("used swap   : {} KB", sys.used_swap());
  71
  72 // Display system information:
  73 println!("System name:             {:?}", sys.name());
  74 println!("System kernel version:   {:?}", sys.kernel_version());
  75 println!("System OS version:       {:?}", sys.os_version());
  76 println!("System host name:        {:?}", sys.host_name());
  77
  78 // Number of CPUs:
  79 println!("NB CPUs: {}", sys.cpus().len());
  80
  81 // Display processes ID, name na disk usage:
  82 for (pid, process) in sys.processes() {
  83     println!("[{}] {} {:?}", pid, process.name(), process.disk_usage());
  84 }
  85
  86 ```
  87
  88 By default, `sysinfo` uses multiple threads. However, this can increase the memory usage on some
  89 platforms (macOS for example). The behavior can be disabled by setting `default-features = false`
  90 in `Cargo.toml` (which disables the `multithread` cargo feature).
  91
  92 ### Running on Raspberry Pi
  93
  94 It'll be difficult to build on Raspberry Pi. A good way-around is to cross-build, then send the
  95 executable to your Raspberry Pi.
  96
  97 First install the arm toolchain, for example on Ubuntu:
  98
  99 ```bash
 100 > sudo apt-get install gcc-multilib-arm-linux-gnueabihf
 101 ```
 102
 103 Then configure cargo to use the corresponding toolchain:
 104
 105 ```bash
 106 cat << EOF > ~/.cargo/config
 107 [target.armv7-unknown-linux-gnueabihf]
 108 linker = "arm-linux-gnueabihf-gcc"
 109 EOF
 110 ```
 111
 112 Finally, cross compile:
 113
 114 ```bash
 115 rustup target add armv7-unknown-linux-gnueabihf
 116 cargo build --target=armv7-unknown-linux-gnueabihf
 117 ```
 118
 119 ### Linux on Docker & Windows Subsystem for Linux (WSL)
 120
 121 Virtual Linux systems, such as those run through Docker and Windows Subsystem for Linux (WSL), do
 122 not receive host hardware information via `/sys/class/hwmon` or `/sys/class/thermal`. As such,
 123 querying for components may return no results (or unexpected results) when using this library on
 124 virtual systems.
 125
 126 ### Use in binaries running inside the macOS or iOS Sandbox/stores
 127
 128 Apple has restrictions as to which APIs can be linked into binaries that are distributed through the app store.
 129 By default, `sysinfo` is not compatible with these restrictions. You can use the `apple-app-store`
 130 feature flag to disable the Apple prohibited features. This also enables the `apple-sandbox` feature.
 131 In the case of applications using the sandbox outside of the app store, the `apple-sandbox` feature
 132 can be used alone to avoid causing policy violations at runtime.
 133
 134 ### How it works
 135
 136 I wrote a blog post you can find [here][sysinfo-blog] which explains how `sysinfo` extracts information
 137 on the diffent systems.
 138
 139 [sysinfo-blog]: https://blog.guillaume-gomez.fr/articles/2021-09-06+sysinfo%3A+how+to+extract+systems%27+information
 140
 141 ### C interface
 142
 143 It's possible to use this crate directly from C. Take a look at the `Makefile` and at the
 144 `examples/simple.c` file.
 145
 146 To build the C example, just run:
 147
 148 ```bash
 149 > make
 150 > ./simple
 151 # If needed:
 152 > LD_LIBRARY_PATH=target/release/ ./simple
 153 ```
 154
 155 ### Benchmarks
 156
 157 You can run the benchmarks locally with rust **nightly** by doing:
 158
 159 ```bash
 160 > cargo bench
 161 ```
 162
 163 ## Donations
 164
 165 If you appreciate my work and want to support me, you can do it with
 166 [github sponsors](https://github.com/sponsors/GuillaumeGomez) or with
 167 [patreon](https://www.patreon.com/GuillaumeGomez).
 168
 169 [img_github_ci]: https://github.com/GuillaumeGomez/sysinfo/workflows/CI/badge.svg
 170 [img_crates]: https://img.shields.io/crates/v/sysinfo.svg
 171 [img_doc]: https://img.shields.io/badge/rust-documentation-blue.svg
 172
 173 [crates]: https://crates.io/crates/sysinfo
 174 [doc]: https://docs.rs/sysinfo/