<?xml version="1.0" encoding="UTF-8"?>
<!-- **************************************************************************
.... For copyright and licensing terms, see the file named COPYING.
.... **************************************************************************
.-->
<?xml-stylesheet href="docbook-xml.css" type="text/css"?>

<refentry id="ulimit">

<refmeta xmlns:xi="http://www.w3.org/2001/XInclude">
<refentrytitle>ulimit</refentrytitle>
<manvolnum>1</manvolnum>
<refmiscinfo class="manual">user commands</refmiscinfo>
<refmiscinfo class="source">nosh</refmiscinfo>
<xi:include href="version.xml" />
</refmeta>

<refnamediv>
<refname>ulimit</refname>
<refpurpose>change resource limit then chain</refpurpose>
</refnamediv>

<refsynopsisdiv>
<cmdsynopsis>
<command>ulimit</command>
<arg choice='opt'>-H</arg>
<arg choice='opt'>-S</arg>
<arg choice='opt' rep='repeat'><replaceable>limits</replaceable></arg>
<arg choice='req'><replaceable>next-prog</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>

<refsection><title>Note</title>

<para>
Most shells have a built-in <command>ulimit</command> command that does not chain and that has additional interactive functionality.
See the manual for each individual shell for its built-in command.
This command is more commonly used with <citerefentry><refentrytitle>exec</refentrytitle><manvolnum>1</manvolnum></citerefentry> and <citerefentry><refentrytitle>nosh</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
Whilst it is built in to them, it is an external command as far as shells are concerned.
</para>

</refsection><refsection><title>Description</title>

<para>
<command>ulimit</command> is a chain-loading utility that changes its resource limits and then chain loads to <replaceable>next-prog</replaceable> with the <citerefentry><refentrytitle>execvp</refentrytitle><manvolnum>3</manvolnum></citerefentry> function.
</para>

<para>
<replaceable>next-prog</replaceable> may contain its own command line options, which <command>ulimit</command> will ignore.
</para>

<para>
If the <arg choice='plain'>-H</arg> command line option is used, <command>ulimit</command> will set the hard resource limits.
If the <arg choice='plain'>-S</arg> option is used as well, <command>ulimit</command> will set both the hard and the soft resource limits.
Otherwise, <command>ulimit</command> will set just the soft resource limits.
</para>
<note>
The behaviours when neither command-line option is specified or both are do not match the behaviours of (some) shells.
However, note that even shells do not agree with one another on what to do in those two cases.
For script clarity, the recommended use is to explicitly use <arg choice='plain'>-H</arg> for hard only and <arg choice='plain'>-S</arg> for soft only in separate invocations of the command, and avoid <arg choice='plain'>-H</arg> <arg choice='plain'>-S</arg> combined in a single invocation.
This not only prevents misunderstanding by shell script programmers, it also clarifies the order in which limits are being set.
</note>

<refsection><title>Limit options</title>

<para>
The following limit options are available:
</para>

<variablelist>

<varlistentry><term>
<arg>-a <replaceable>KiB</replaceable></arg></term><listitem><para>sets <code>RLIMIT_AS</code>, <code>RLIMIT_DATA</code>, <code>RLIMIT_MEMLOCK</code>, and <code>RLIMIT_STACK</code>
</para></listitem></varlistentry>

<varlistentry><term>
<arg>-c <replaceable>blocks</replaceable></arg></term><listitem><para>sets <code>RLIMIT_CORE</code>
</para></listitem></varlistentry>

<varlistentry><term>
<arg>-d <replaceable>KiB</replaceable></arg></term><listitem><para>sets <code>RLIMIT_DATA</code>
</para></listitem></varlistentry>

<varlistentry><term>
<arg>-e <replaceable>number</replaceable></arg></term><listitem><para>sets <code>RLIMIT_NICE</code> (only on some operating systems)
</para></listitem></varlistentry>

<varlistentry><term>
<arg>-f <replaceable>blocks</replaceable></arg></term><listitem><para>sets <code>RLIMIT_FSIZE</code>
</para></listitem></varlistentry>

<varlistentry><term>
<arg>-i <replaceable>n</replaceable></arg></term><listitem><para>sets <code>RLIMIT_SIGPENDING</code> (only on some operating systems)
</para></listitem></varlistentry>

<varlistentry><term>
<arg>-l <replaceable>KiB</replaceable></arg></term><listitem><para>sets <code>RLIMIT_MEMLOCK</code>
</para></listitem></varlistentry>

<varlistentry><term>
<arg>-m <replaceable>KiB</replaceable></arg></term><listitem><para>sets <code>RLIMIT_RSS</code>
</para></listitem></varlistentry>

<varlistentry><term>
<arg>-n <replaceable>n</replaceable></arg></term><listitem><para>sets <code>RLIMIT_NOFILE</code>
</para></listitem></varlistentry>

<varlistentry><term>
<arg>-p <replaceable>count</replaceable></arg></term><listitem><para>sets <code>RLIMIT_PIPE</code> (only on some operating systems)
</para></listitem></varlistentry>

<varlistentry><term>
<arg>-q <replaceable>count</replaceable></arg></term><listitem><para>sets <code>RLIMIT_MSGQUEUE</code> (only on some operating systems)
</para></listitem></varlistentry>

<varlistentry><term>
<arg>-s <replaceable>KiB</replaceable></arg></term><listitem><para>sets <code>RLIMIT_STACK</code>
</para></listitem></varlistentry>

<varlistentry><term>
<arg>-t <replaceable>seconds</replaceable></arg></term><listitem><para>sets <code>RLIMIT_CPU</code>
</para></listitem></varlistentry>

<varlistentry><term>
<arg>-u <replaceable>n</replaceable></arg></term><listitem><para>sets <code>RLIMIT_NPROC</code>
</para></listitem></varlistentry>

<varlistentry><term>
<arg>-v <replaceable>KiB</replaceable></arg></term><listitem><para>sets <code>RLIMIT_AS</code>
</para></listitem></varlistentry>

<varlistentry><term>
<arg>-x <replaceable>n</replaceable></arg></term><listitem><para>sets <code>RLIMIT_LOCKS</code> (only on some operating systems)
</para></listitem></varlistentry>

</variablelist>

<para>
See <citerefentry><refentrytitle>setrlimit</refentrytitle><manvolnum>2</manvolnum></citerefentry> for an explanation of the effects of these limits and the privileges that are sometimes required.
</para>

</refsection>

<para>
To set an "infinite" limit, use the text <code>unlimited</code> for the limit value.
Similarly, the text <code>=</code> or <code>hard</code> will use the current value of the hard limit as the value.
(This is particularly useful when setting soft limits, as it provides a simple means of setting the soft limit to the hard limit ceiling without knowing its current value.)
</para>

<para>
Special treatment is given to the <arg choice='plain'>-a</arg> option because it sets multiple limits at once.
An attempt to set any one soft limit greater than the matching hard limit will be silently converted into an attempt to set the soft limit equal to the hard limit.
</para>

<para>
Some limits are set in units of kilobinarybytes and blocks.
For commands with finer granularity, see <citerefentry><refentrytitle>softlimit</refentrytitle><manvolnum>1</manvolnum></citerefentry> and <citerefentry><refentrytitle>hardlimit</refentrytitle><manvolnum>1</manvolnum></citerefentry>.
</para>

</refsection><refsection><title>Author</title>
<para><author><personname><firstname>Jonathan</firstname> <surname>de Boyne Pollard</surname></personname></author></para>
</refsection>

</refentry>
