# man > chpst(8)

---
type: CommandReference
command: chpst
mode: man
section: 8
source: man-pages
---

## Quick Reference

- `chpst -u user prog` — run prog with changed uid/gid
- `chpst -U user prog` — set $UID/$GID environment variables
- `chpst -e dir prog` — import environment variables from files in dir
- `chpst -/ root prog` — chroot to root then run prog
- `chpst -l lock prog` — obtain exclusive lock on lock file, wait if needed
- `chpst -m bytes prog` — limit memory (data+stack+locked+total) to bytes
- `chpst -t seconds prog` — limit CPU time to seconds, send SIGXCPU
- `chpst -b argv0 prog` — run prog with argv0 as argv[0]

## Name

**chpst** — runs a program with a changed process state

## Synopsis

shell
chpst [-vVP012] [-u user] [-U user] [-b argv0] [-e dir] [-/ root] [-n inc] [-l|-L lock] [-m bytes] [-d bytes] [-o n] [-p n] [-f bytes] [-c bytes] [-t seconds] prog
## Options

### Identity and argv0

- `-u user[:group[:group...]]` — set uid and gid to user's uid/gid. If colon and group given, set gid to group's gid (or list of gids). If user prefixed with colon, treat as numeric uid/gid. Removes all supplementary groups.
- `-U user[:group]` — set environment variables `$UID` and `$GID` to user's uid/gid. Numeric prefixes allowed.
- `-b argv0` — run prog with argv0 as the 0th argument.

### Environment

- `-e dir` — for each file `k` in dir, if first line is `v`, set environment variable `k=v`. If file is empty, remove variable `k`. Trailing spaces/tabs removed, nulls become newlines.

### Chroot and Locks

- `-/ root` — chroot to root before starting prog.
- `-l lock` — open lock file for writing, obtain exclusive lock (create if needed), wait if locked.
- `-L lock` — same as `-l` but fail immediately if locked.

### Resource Limits

- `-m bytes` — limit data segment, stack segment, locked physical pages, and total of all segments per process to bytes each.
- `-d bytes` — limit data segment per process to bytes.
- `-o n` — (not documented in original; may be unsupported)
- `-p n` — (not documented in original; may be unsupported)
- `-f bytes` — limit output file size to bytes.
- `-c bytes` — limit core file size to bytes.
- `-t seconds` — limit CPU time to seconds, delivering SIGXCPU.

### Other Options

- `-n inc` — may start with minus or plus (unsupported by system).
- `-v` — unsupported by the system.
- `-V` — (not documented)
- `-P` — (not documented)
- `-0` — (not documented)
- `-1` — (not documented)
- `-2` — (not documented)

## Examples

No examples are provided in the original man page. Common use cases:

shell
# Run a service as a specific user
chpst -u nobody /usr/local/bin/service

# Run with environment variables from a directory
chpst -e /etc/sv/env /usr/local/bin/script

# Chroot and run
chpst -/ /var/chroot /bin/sh

# Limit memory and CPU time
chpst -m 100000000 -t 30 /usr/bin/myprogram

# Obtain a lock before running
chpst -l /tmp/myapp.lock /usr/local/bin/critical
## Exit Codes

- **100** — called with wrong options.
- **111** — error changing process state (trouble).
- Otherwise, exit code is the same as that of prog.

## See Also

- [sv(8)](http://localhost/phpMan.php/man/sv/8/markdown)
- [runsv(8)](http://localhost/phpMan.php/man/runsv/8/markdown)
- [setsid(2)](http://localhost/phpMan.php/man/setsid/2/markdown)
- [runit(8)](http://localhost/phpMan.php/man/runit/8/markdown)
- [runit-init(8)](http://localhost/phpMan.php/man/runit-init/8/markdown)
- [runsvdir(8)](http://localhost/phpMan.php/man/runsvdir/8/markdown)
- [runsvchdir(8)](http://localhost/phpMan.php/man/runsvchdir/8/markdown)
- <http://smarden.org/runit/>
- <http://cr.yp.to/daemontools.html>