usr.bin/limits/limits.1

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