unix: Support for UNIX-like systems

Table of Content:

Introduction

The unix: module provides access to features that only make sense on UNIX-like operating systems, such as Linux, FreeBSD, and macOS.

On non-UNIX operating systems, such as MS Windows, this namespace does not exist and use unix will fail. Use the $platform:is-unix variable to determine if this namespace is usable.

Variables

$unix:rlimits

A map describing resource limits of the current process.

Each key is a string corresponds to a resource, and each value is a map with keys &cur and &max, describing the soft and hard limits of that resource. A missing &cur key means that there is no soft limit; a missing &max key means that there is no hard limit.

The following resources are supported, some only present on certain OSes:

Key Resource Unit OS
core Core file bytes all
cpu CPU time seconds all
data Data segment bytes all
fsize File size bytes all
memlock Locked memory bytes all
nofile File descriptors number all
nproc Processes number all
rss Resident set size bytes all
stack Stack segment bytes all
as Address space bytes Linux, Free/NetBSD
nthr Threads number NetBSD
sbsize Socket buffers bytes NetBSD
locks File locks number Linux
msgqueue Message queues bytes Linux
nice 20 - nice value Linux
rtprio Real-time priority Linux
rttime Real-time CPU time seconds Linux
sigpending Signals queued number Linux

For the exact semantics of each resource, see the man page of getrlimit: Linux, macOS, FreeBSD, NetBSD, OpenBSD. A key foo in the Elvish API corresponds to RLIMIT_FOO in the C API.

Examples:

~> put $unix:rlimits
▶ [&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=[&]]
~> # mimic Bash's "ulimit -a"
~> 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 "%-7v %-9v %-9v\n" $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
~> # Decrease the soft limit on file descriptors
~> set unix:rlimits[nofile][cur] = 100
~> put $unix:rlimits[nofile]
▶ [&cur=(num 100)]
~> # Remove the soft limit on file descriptors
~> del unix:rlimits[nofile][cur]
~> put $unix:rlimits[nofile]
▶ [&]

$unix:umask

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 $number.

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: set unix:umask = 027 and set unix:umask = 0o27. You can also assign to it a float64 data type that has no fractional component. The assigned value must be within the range [0 … 0o777], otherwise the assignment will throw an exception.

You can do a temporary assignment to affect a single command; e.g. umask=077 touch a_file. After the command completes the old umask will be restored. Warning: 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 peach command.