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