xref: /dragonfly/usr.bin/limits/limits.1 (revision 1de703da)
1.\" Copyright (c) 1996 David Nugent <davidn@blaze.net.au>
2.\" All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, is permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\"    notice immediately at the beginning of the file, without modification,
9.\"    this list of conditions, and the following disclaimer.
10.\" 2. Redistributions in binary form must reproduce the above copyright
11.\"    notice, this list of conditions and the following disclaimer in the
12.\"    documentation and/or other materials provided with the distribution.
13.\" 3. This work was done expressly for inclusion into FreeBSD.  Other use
14.\"    is permitted provided this notation is included.
15.\" 4. Absolutely no warranty of function or purpose is made by the author
16.\"    David Nugent.
17.\" 5. Modifications may be freely made to this file providing the above
18.\"    conditions are met.
19.\"
20.\" $FreeBSD: src/usr.bin/limits/limits.1,v 1.14.2.10 2003/02/25 20:31:18 trhodes Exp $
21.\" $DragonFly: src/usr.bin/limits/limits.1,v 1.2 2003/06/17 04:29:28 dillon Exp $
22.\"
23.Dd January 15, 1996
24.Dt LIMITS 1
25.Os
26.Sh NAME
27.Nm limits
28.Nd set or display process resource limits
29.Sh SYNOPSIS
30.Nm
31.Op Fl C Ar class
32.Op Fl SHB
33.Op Fl ea
34.Op Fl cdflmnstuv Op val
35.Nm
36.Op Fl C Ar class
37.Op Fl SHB
38.Op Fl cdflmnstuv Op val
39.Op Fl E
40.Op Ar name Ns = Ns Ar value ...
41.Op Ar command
42.Nm
43.Op Fl U Ar user
44.Op Fl SHB
45.Op Fl ea
46.Op Fl cdflmnstuv Op val
47.Nm
48.Op Fl U Ar user
49.Op Fl SHB
50.Op Fl cdflmnstuv Op val
51.Op Fl E
52.Op Ar name Ns = Ns Ar value ...
53.Op Ar command
54.Sh DESCRIPTION
55The
56.Nm
57utility either prints or sets kernel resource limits, and may optionally set
58environment variables like
59.Xr env 1
60and run a program with the selected resources.
61Three uses of the
62.Nm
63command are possible:
64.Pp
65.Bl -tag -width indent
66.It Xo
67.Nm
68.Op Ar limitflags
69.Op Ar name Ns = Ns Ar value
70.Ar command
71.Xc
72This usage sets limits according to
73.Ar limitflags ,
74optionally sets environment variables given as
75.Ar name Ns = Ns Ar value
76pairs, and then runs the specified command.
77.It Xo
78.Nm
79.Op Ar limitflags
80.Xc
81This usage determines values of resource settings according to
82.Ar limitflags ,
83does not attempt to set them and outputs these values to
84standard output.
85By default, this will output the current kernel resource settings
86active for the calling process.
87Using the
88.Fl C Ar class
89or
90.Fl U Ar user
91flags, you may also display the current resource settings modified
92by the appropriate login class resource limit entries from
93the
94.Xr login.conf 5
95login capabilities database.
96.It Xo
97.Nm
98.Fl e Op Ar limitflags
99.Xc
100This usage determines values of resource settings according to
101.Ar limitflags ,
102but does not set them itself.
103Like the previous usage it outputs these values to standard
104output, except that it will emit them in
105.Em eval
106format, suitable for the calling shell.
107The calling shell is determined by examining the entries in the
108.Pa /proc
109filesystem for the parent process.
110If the shell is known (i.e. it is one of sh, csh, bash, tcsh, ksh,
111pdksh or rc),
112.Nm
113emits 'limit' or 'ulimit' commands in the format understood by
114that shell.
115If the name of the shell cannot be determined, then the 'ulimit'
116format used by
117.Xr sh 1
118is used.
119.Pp
120This is very useful for setting limits used by scripts, or prior
121launching of daemons and other background tasks with specific
122resource limit settings, and provides the benefit of allowing
123global configuration of maximum resource usage by maintaining a
124central database of settings in the login class database.
125.Pp
126Within a shell script,
127.Nm
128will normally be used with eval within backticks as follows:
129.Pp
130.Dl eval `limits -e -C daemon`
131.Pp
132which causes the output of
133.Nm
134to be evaluated and set by the current shell.
135.El
136.Pp
137The value of
138.Ar limitflags
139specified in the above contains one or more of the following options:
140.Pp
141.Bl -tag -width "-d [limit]"
142.It Fl C Ar class
143Use current resource values, modified by the resource entries applicable
144for the login class "class".
145.It Fl U Ar user
146Use current resource values, modified by the resource entries applicable
147to the login class which "user" belongs to.
148If the user does not belong to a class, then the resource capabilities
149for the "default" class are used, if it exists, or the "root" class if
150the user is a superuser account.
151.It Fl S
152Select display or setting of "soft" (or current) resource limits.
153If specific limits settings follow this switch, only soft limits are
154affected unless overridden later with either the
155.Fl H
156or
157.Fl B
158flags.
159.It Fl H
160Select display or setting of "hard" (or maximum) resource limits.
161If specific limits settings follow this switch, only hard limits are
162affected until overridden later with either the
163.Fl S
164or
165.Fl B
166flags.
167.It Fl B
168Select display or setting of both "soft" (current) or "hard" (maximum)
169resource limits.
170If specific limits settings follow this switch, both soft and hard
171limits are affected until overridden later with either the
172.Fl S
173or
174.Fl H
175flags.
176.Fl e
177Select "eval mode" formatting for output.
178This is valid only on display mode and cannot be used when running a
179command.
180The exact syntax used for output depends upon the type of shell from
181which
182.Nm
183is invoked.
184.It Fl b Op Ar limit
185Selects or sets the
186.Em sbsize
187resource limit.
188.It Fl c Op Ar limit
189Select or set (if 'limit' is specified) the
190.Em coredumpsize
191resource limit.
192A value of 0 disables core dumps.
193.It Fl d Op Ar limit
194Select or set (if 'limit' is specified) the
195.Em datasize
196resource limit.
197.It Fl f Op Ar limit
198Select or set the
199.Em filesize
200resource limit.
201.It Fl l Op Ar limit
202Select or set the
203.Em memorylocked
204resource limit.
205.It Fl m Op Ar limit
206Select or set the
207.Em memoryuse
208size limit.
209.It Fl n Op Ar limit
210Select or set the
211.Em openfiles
212resource limit.  The system-wide limit on the maximum number of
213open files per process can be viewed using the 'sysctl kern.maxfilesperproc'
214command.  The total number of simultaneously open files in the entire
215system is limited to the value displayed by the 'sysctl kern.maxfiles'
216command.
217.It Fl s Op Ar limit
218Select or set the
219.Em stacksize
220resource limit.
221.It Fl t Op Ar limit
222Select or set the
223.Em cputime
224resource limit.
225.It Fl u Op Ar limit
226Select or set the
227.Em maxproc
228resource limit.  The system-wide limit on the maximum number of processes
229allowed per UID can be viewed using the 'sysctl kern.maxprocperuid' command.
230The maximum number of processes that can be running simultaneously
231in the entire system is limited to the value given by
232the 'sysctl kern.maxproc' command.
233.It Fl v Op Ar limit
234Select or set the
235.Em virtualmem
236resource limit.
237This limit encompasses the entire VM space for the user process
238and is inclusive of text, data, bss, stack,
239.Xr brk 2 ,
240.Xr sbrk 2
241and
242.Xr mmap 2 Ns 'd
243space.
244.El
245.Pp
246Valid values for
247.Ar val
248in the above set of options consist of either the
249string
250.Dq Li infinity ,
251.Dq Li inf ,
252.Dq Li unlimited
253or
254.Dq Li unlimit
255for an infinite (or kernel-defined maximum)
256limit, or a numeric value optionally followed by a suffix.
257Values which relate to size default to a value in bytes, or one of the
258following suffixes may be used as a multiplier:
259.Pp
260.Bl -tag -offset indent -width 4n -compact
261.It Li b
262512 byte blocks.
263.It Li k
264kilobytes (1024 bytes).
265.It Li m
266megabytes (1024*1024 bytes).
267.It Li g
268gigabytes.
269.It Li t
270terabytes.
271.El
272.Pp
273The
274.Va cputime
275resource defaults to a number of seconds, but a multiplier may be
276used, and as with size values, multiple values separated by a valid
277suffix are added together:
278.Pp
279.Bl -tag -offset indent -width 4n -compact
280.It Li s
281seconds.
282.It Li m
283minutes.
284.It Li h
285hours.
286.It Li d
287days.
288.It Li w
289weeks.
290.It Li y
291365 day years.
292.El
293.Bl -tag -width ".Fl C Ar class"
294.It Fl E
295Cause
296.Nm
297to completely ignore the environment it inherits.
298.It Fl a
299Force all resource settings to be displayed even if
300other specific resource settings have been specified.
301For example, if you wish to disable core dumps when starting up
302the Usenet News system, but wish to set all other resource settings
303as well that apply to the
304.Dq Li news
305account, you might use:
306.Pp
307.Dl "eval `limits -U news -aBec 0`"
308.Pp
309As with the
310.Xr setrlimit 2
311call, only the superuser may raise process
312.Dq hard
313resource limits.
314Non-root users may, however, lower them or change
315.Dq soft
316resource limits
317within to any value below the hard limit.
318When invoked to execute a program, the failure of
319.Nm
320to raise a hard limit is considered a fatal error.
321.El
322.Sh DIAGNOSTICS
323The
324.Nm
325utility
326exits with EXIT_FAILURE if usage is incorrect in any way; i.e. an invalid
327option, or set/display options are selected in the same invocation,
328.Fl e
329is used when running a program, etc.
330When run in display or eval mode,
331.Nm
332exits with a status of EXIT_SUCCESS.
333When run in command mode and execution of the command succeeds, the exit status
334will be whatever the executed program returns.
335.Sh SEE ALSO
336.Xr csh 1 ,
337.Xr env 1 ,
338.Xr limit 1 ,
339.Xr sh 1 ,
340.Xr getrlimit 2 ,
341.Xr setrlimit 2 ,
342.Xr login_cap 3 ,
343.Xr login.conf 5 ,
344.Xr sysctl 8
345.Sh BUGS
346The
347.Nm
348utility does not handle commands with equal (``='') signs in their
349names, for obvious reasons.
350.Pp
351When eval output is selected, the
352.Pa /proc
353filesystem must be installed
354and mounted for the shell to be correctly determined, and therefore
355output syntax correct for the running shell.
356The default output is valid for
357.Xr sh 1 ,
358so this means that any
359usage of
360.Nm
361in eval mode prior mounting
362.Pa /proc
363may only occur in standard bourne
364shell scripts.
365.Pp
366The
367.Nm
368utility makes no effort to ensure that resource settings emitted or displayed
369are valid and settable by the current user.
370Only a superuser account may raise hard limits, and when doing so
371the
372.Fx
373kernel will silently lower limits to values less than
374specified if the values given are too high.
375