'\" t
.\" Automatically generated by Pandoc 2.17.1.1
.\"
.\" Define V font for inline verbatim, using C font in formats
.\" that render this, and otherwise B font.
.ie "\f[CB]x\f[]"x" \{\
. ftr V B
. ftr VI BI
. ftr VB B
. ftr VBI BI
.\}
.el \{\
. ftr V CR
. ftr VI CI
. ftr VB CB
. ftr VBI CBI
.\}
.TH "elvish-unix" "7" "Feb 25, 2023" "Elvish 0.18.0" "Miscellaneous Information Manual"
.hy
.PP
.SH Introduction
.PP
The \f[V]unix:\f[R] module provides access to features that only make
sense on UNIX-like operating systems, such as Linux, FreeBSD, and macOS.
.PP
On non-UNIX operating systems, such as MS Windows, this namespace does
not exist and \f[V]use unix\f[R] will fail.
Use the \f[V]$platform:is-unix\f[R] variable to determine if this
namespace is usable.
.SH Variables
.PP
.SS $unix:rlimits {#unix:rlimits}
.PP
A map describing resource limits of the current process.
.PP
Each key is a string corresponds to a resource, and each value is a map
with keys \f[V]&cur\f[R] and \f[V]&max\f[R], describing the soft and
hard limits of that resource.
A missing \f[V]&cur\f[R] key means that there is no soft limit; a
missing \f[V]&max\f[R] key means that there is no hard limit.
.PP
The following resources are supported, some only present on certain
OSes:
.PP
.TS
tab(@);
l l l l.
T{
Key
T}@T{
Resource
T}@T{
Unit
T}@T{
OS
T}
_
T{
\f[V]core\f[R]
T}@T{
Core file
T}@T{
bytes
T}@T{
all
T}
T{
\f[V]cpu\f[R]
T}@T{
CPU time
T}@T{
seconds
T}@T{
all
T}
T{
\f[V]data\f[R]
T}@T{
Data segment
T}@T{
bytes
T}@T{
all
T}
T{
\f[V]fsize\f[R]
T}@T{
File size
T}@T{
bytes
T}@T{
all
T}
T{
\f[V]memlock\f[R]
T}@T{
Locked memory
T}@T{
bytes
T}@T{
all
T}
T{
\f[V]nofile\f[R]
T}@T{
File descriptors
T}@T{
number
T}@T{
all
T}
T{
\f[V]nproc\f[R]
T}@T{
Processes
T}@T{
number
T}@T{
all
T}
T{
\f[V]rss\f[R]
T}@T{
Resident set size
T}@T{
bytes
T}@T{
all
T}
T{
\f[V]stack\f[R]
T}@T{
Stack segment
T}@T{
bytes
T}@T{
all
T}
T{
\f[V]as\f[R]
T}@T{
Address space
T}@T{
bytes
T}@T{
Linux, Free/NetBSD
T}
T{
\f[V]nthr\f[R]
T}@T{
Threads
T}@T{
number
T}@T{
NetBSD
T}
T{
\f[V]sbsize\f[R]
T}@T{
Socket buffers
T}@T{
bytes
T}@T{
NetBSD
T}
T{
\f[V]locks\f[R]
T}@T{
File locks
T}@T{
number
T}@T{
Linux
T}
T{
\f[V]msgqueue\f[R]
T}@T{
Message queues
T}@T{
bytes
T}@T{
Linux
T}
T{
\f[V]nice\f[R]
T}@T{
20 - nice value
T}@T{
T}@T{
Linux
T}
T{
\f[V]rtprio\f[R]
T}@T{
Real-time priority
T}@T{
T}@T{
Linux
T}
T{
\f[V]rttime\f[R]
T}@T{
Real-time CPU time
T}@T{
seconds
T}@T{
Linux
T}
T{
\f[V]sigpending\f[R]
T}@T{
Signals queued
T}@T{
number
T}@T{
Linux
T}
.TE
.PP
For the exact semantics of each resource, see the man page of
\f[V]getrlimit\f[R]:
Linux (https://man7.org/linux/man-pages/man2/setrlimit.2.html),
macOS (https://developer.apple.com/library/archive/documentation/System/Conceptual/ManPages_iPhoneOS/man2/getrlimit.2.html),
FreeBSD (https://www.freebsd.org/cgi/man.cgi?query=getrlimit),
NetBSD (https://man.netbsd.org/getrlimit.2),
OpenBSD (https://man.openbsd.org/getrlimit.2).
A key \f[V]foo\f[R] in the Elvish API corresponds to
\f[V]RLIMIT_FOO\f[R] in the C API.
.PP
Examples:
.IP
.nf
\f[C]
\[ti]> put $unix:rlimits
\[u25B6] [&nofile=[&cur=(num 256)] &fsize=[&] &nproc=[&max=(num 2666) &cur=(num 2666)] &memlock=[&] &cpu=[&] &core=[&cur=(num 0)] &stack=[&max=(num 67092480) &cur=(num 8372224)] &rss=[&] &data=[&]]
\[ti]> # mimic Bash\[aq]s \[dq]ulimit -a\[dq]
\[ti]> keys $unix:rlimits | order | each {|key|
     var m = $unix:rlimits[$key]
     fn get {|k| if (has-key $m $k) { put $m[$k] } else { put unlimited } }
     printf \[dq]%-7v %-9v %-9v\[rs]n\[dq] $key (get cur) (get max)
   }
core    0         unlimited
cpu     unlimited unlimited
data    unlimited unlimited
fsize   unlimited unlimited
memlock unlimited unlimited
nofile  256       unlimited
nproc   2666      2666
rss     unlimited unlimited
stack   8372224   67092480
\[ti]> # Decrease the soft limit on file descriptors
\[ti]> set unix:rlimits[nofile][cur] = 100
\[ti]> put $unix:rlimits[nofile]
\[u25B6] [&cur=(num 100)]
\[ti]> # Remove the soft limit on file descriptors
\[ti]> del unix:rlimits[nofile][cur]
\[ti]> put $unix:rlimits[nofile]
\[u25B6] [&]
\f[R]
.fi
.PP
.SS $unix:umask {#unix:umask}
.PP
The file mode creation mask.
Its value is a string in Elvish octal representation; e.g.
0o027.
This makes it possible to use it in any context that expects a
\f[V]$number\f[R].
.PP
When assigning a new value a string is implicitly treated as an octal
number.
If that fails the usual rules for interpreting numbers are used.
The following are equivalent: \f[V]set unix:umask = 027\f[R] and
\f[V]set unix:umask = 0o27\f[R].
You can also assign to it a \f[V]float64\f[R] data type that has no
fractional component.
The assigned value must be within the range [0 \&...
0o777], otherwise the assignment will throw an exception.
.PP
You can do a temporary assignment to affect a single command; e.g.
\f[V]umask=077 touch a_file\f[R].
After the command completes the old umask will be restored.
\f[B]Warning\f[R]: Since the umask applies to the entire process, not
individual threads, changing it temporarily in this manner is dangerous
if you are doing anything in parallel, such as via the \f[V]peach\f[R]
command.