mqrs/README.md

# mqrs
`mqrs` is a small cli application to handle POSIX message queues.

## Installation
To build `mqrs` a rust toolchain is necessary.

### Install Rust
Install the Rust toolchain from [rustup.rs](https://rustup.rs).

### Build `mqrs`
`mqrs` can be built for development:
```sh
cargo b
```

or for releasing:
```sh
cargo b --release
```

### Build the `mqrs` Debian package
For that [`cargo-deb`](https://github.com/mmstick/cargo-deb) is
required, which can be installed with:
```sh
cargo install cargo-deb
```

A Debian package can be built with:
```sh
cargo deb
```

### Install `mqrs`
When a Rust toolchain installed you can also install `mqrs`
directly without cloning it manually:
``` sh
cargo install --git https://git.onders.org/finga/mqrs.git mqrs
```

or from within the project:
```sh
cargo install mqrs
```

### Run `mqrs`
`mqrs` can either be run from the project directory with:
```sh
cargo b
```

or you can copy the produced binary somewhere else or link to them
from `target/{debug,release}/mqrs` depending on which one you built.

## Using `mqrs`
Depending on which backend you want to use there are different subsets
of subcommands. Following backends are supported:
- `posix`: Uses POSIX message queues
- `sysv`: Uses SysV IPC message queues

If a command is clearly distinguishable from all the others,
it does not have to be completed further.

### POSIX message queues
The POSIX backend supports six commands: `create`, `info`, `list`,
`unlink`, `send` and `recv`.

#### Create a message queue
Use the `create` command to create a new POSIX message queue. Following
optional arguments are supported:
- `-c`, `--capacity`: Maximum number of messages in the queue
- `-p`, `--permissions`: Permissions (octal) to create the queue with
- `-s`, `--msgsize`: Message size in bytes

#### Print information about a message queue
Use the `info` command to print further information about a message
queue.

#### List all message queues
Use the `list` command to print a list of all message
queues. Following option argument is supported:
- `-a`, `--all`: Print all available information

#### Delete a message queue
Use the `unlink` command to delete a message queue.

#### Send a message to a queue
Use the `send` command to send a message to a message queue. Following
optional arguments are supported:
- `-n`, `--non-blocking`: Do not block
- `-d`, `--deadline <deadline>`: Deadline until messages are sent
  (format: `%Y-%m-%d %H:%M:%S`)
- `-p`, `--priority <priority>`: Set a different priority than
  default, priority >= 0 [default: 0]
- `-o`, `--timeout <timeout>`: As for example in "5h 23min 42ms"

#### Receive a message from a queue
Use the `recv` command to receive one or more messages from a message
queue. Following optional arguments are supported:
- `-f`, `--follow`: Print messages as they are received
- `-n`, `--non-blocking`: Do not block
- `-t`, `--timestamp`: Print a timestamp before each message
- `-d`, `--deadline <deadline>`: Deadline until messages are received
  (format: `%Y-%m-%d %H:%M:%S`)
- `-o,` `--timeout <timeout>`: As for example in "5h 23min 42ms"

### SysV IPC message queues
The SysV IPC backend supports no commands yet.