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