https://github.com/laserpants/mbs
:hourglass_flowing_sand: Command line tool to help keeping a tab on data usage.
https://github.com/laserpants/mbs
c c99 cli-tool linux networking
Last synced: about 2 months ago
JSON representation
:hourglass_flowing_sand: Command line tool to help keeping a tab on data usage.
- Host: GitHub
- URL: https://github.com/laserpants/mbs
- Owner: laserpants
- License: bsd-3-clause
- Created: 2017-12-04T06:49:58.000Z (over 8 years ago)
- Default Branch: master
- Last Pushed: 2019-12-24T22:11:42.000Z (over 6 years ago)
- Last Synced: 2025-02-10T08:29:50.199Z (over 1 year ago)
- Topics: c, c99, cli-tool, linux, networking
- Language: C
- Homepage: https://laserpants.github.io/mbs
- Size: 655 KB
- Stars: 4
- Watchers: 2
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# mbs [](https://travis-ci.org/laserpants/mbs)
A command line tool to keep track of the amount of data sent and received over
a network interface. This can be convenient for monitoring data usage against a
pre-paid bundle or some other fixed usage limit.
### Building
1. Install [ncurses](https://www.gnu.org/software/ncurses/). For Linux systems,
see [this page](https://www.cyberciti.biz/faq/linux-install-ncurses-library-headers-on-debian-ubuntu-centos-fedora/).
2. Clone this repo. **Note:** The `--recursive` flag (to download git submodules) is required.
```bash
git clone --recursive https://github.com/laserpants/mbs/
```
3. To build and install the command:
```bash
cd build
cmake ..
make
```
Use `sudo make install` to install the executable, or `make test` to run the tests.
```bash
$ mbs --version
mbs version 0.1.2
```
### Usage
```
mbs [-vkp] [--help] [--version] [--ascii] [-a ] [--statsfile=] []
```
If no `` is given, the program will try to automatically find an
active network interface (excluding `lo`).
#### Examples
Set the amount of data available using the `--available` (`-a`) flag to run
the command in *countdown* mode. The following example specifies a data limit
of 300 KB.
```
mbs -a 300K
```
To tell the command to monitor the network interface `wlan0`:
```
mbs -a 300K wlan0
```
By default, the command will exit once the usage limit is reached, or if the
connection is lost. Use the `--keep-running` flag to modify this behavior.
```
mbs -a 10K --keep-running
```
You can also omit the `--available` flag, in which case the command will
run indefinitely – showing the amount of data used since it started.
If the `--ascii` flag is provided, only characters in the (extended) ASCII
character set are used in the interface:
#### Persistent sessions
When the command is run with the `--persistent` (`-p`) flag, it will try to
resume from where the last session ended. It does so by reading the last
saved state (sent and received bytes count) from a *stats* file. Note that this
will not work if the kernel's TX/RX counters were reset since the last time the
command was run (e.g., after a system reboot).
The stats file's location can be set using the `--statsfile=` flag. If
this flag is not provided, then `$HOME/.mbs` is used as a default.
### Flags
| Flag | Short option | Description |
|------------------|----------------|-----------------------------------------|
| `--help` | | Display help and exit. |
| `--version` | | Display version info and exit. |
| `--verbose` | `-v` | Render verbose output. |
| `--ascii` | | Disable non-ascii Unicode characters. |
| `--keep-running` | `-k` | Do not exit when data limit is exceeded or connection is lost. |
| `--persistent` | `-p` | Continue from where last session ended. (See [Persistent sessions](https://github.com/laserpants/mbs#persistent-sessions).) |
| `--available` | `-a` | Amount of data available to use in your subscription plan or budget. |
| `--statsfile` | | Override default stats file path. (See [Persistent sessions](https://github.com/laserpants/mbs#persistent-sessions).) |
The `--available` argument accepts the following suffixes:
| Suffix | Unit | Size |
|----------------------------|------------------------|------------------|
| **B**, **b**, or no suffix | Bytes | 1 |
| **kB**, or **k** | Kilobyte | 1000 |
| **KB**, **K**, or **KiB** | Kibibyte† | 210 |
| **mB**, or **m** | Megabyte | 10002 |
| **MB**, **M**, or **MiB** | Mebibyte† | 220 |
| **gB**, or **g** | Gigabyte | 10003 |
| **GB**, **G**, or **GiB** | Gibibyte† | 230 |
†) Defined by the International Electrotechnical Commission (IEC).
A decimal point can also be used; e.g., `mbs -a 100.5M`.
### Third-party libraries
This repository includes [Argtable3](http://www.argtable.org/) as a git submodule. The Argtable3 library is copyright (c) 1998-2001, 2003-2011 Stewart Heitmann and licensed under the 3-Clause BSD License.