!--
SPDX-FileCopyrightText: Peter Pentchev <roam@ringlet.net>
SPDX-License-Identifier: BSD-2-Clause
-->

# timelimit - limit a process's absolute execution time

\[[Home][ringlet-home] | [Download](download.md) | [GitLab][gitlab] | [ReadTheDocs][readthedocs]\]

## Overview

The `timelimit` crate's `limit()` function executes a command and terminates the spawned process after
a given time with a given signal.
A "warning" signal is sent first, then, after a timeout, a "kill" signal,
similar to the way `init(8)` operates on shutdown.

## Examples

``` rust
use timelimit::Config;

let cfg = Config::builder().build();
let res = smol::block_on(timelimit::limit(cfg, [
    "/usr/local/bin/rsync",
    "rsync://some.host/dir",
    "/opt/mirror",
]));
```

Run the `rsync` program to mirror a WWW or FTP site and kill it if it
runs longer than 1 hour (that is 3600 seconds) with `SIGTERM`.
If the rsync process does not exit after receiving the `SIGTERM`,
`limit()` issues a `SIGKILL` 120 seconds after the `SIGTERM`.

``` rust
use timelimit::{Config, Signal};

let cfg = Config::builder()
    .warntime(600_f32)
    .warnsig(Signal::from_str("QUIT")?)
    .killtime(300_f32)
    .killsig(Signal::from_raw(9_i32)?)
    .build();
let res = smol::block_on(timelimit::limit(cfg, ["/opt/services/chat/stats"]));
```

Invoke an instance of an IRC statistics tool under `/opt/services/chat` and
kill it using a `SIGQUIT` signal after 600 seconds have elapsed.
If the `stats` process is still running after the `SIGQUIT`, it will be killed by
a `SIGKILL` sent 300 seconds later.

## Contact

The `timelimit` crate was written by [Peter Pentchev][roam].
It is developed in [a GitLab repository][gitlab]. This documentation is
hosted at [Ringlet][ringlet-home] with a copy at [ReadTheDocs][readthedocs].

[roam]: mailto:roam@ringlet.net "Peter Pentchev"
[gitlab]: https://gitlab.com/timelimit/timelimit "The timelimit GitLab repository"
[readthedocs]: https://timelimit.readthedocs.io/ "The timelimit ReadTheDocs page"
[ringlet-home]: https://devel.ringlet.net/sysutils/timelimit/ "The Ringlet timelimit homepage"
