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 .\"
  22 .Dd January 15, 1996
  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
  31 .Op Fl SHB
  32 .Op Fl ea
  33 .Op Fl cdflmnstuv Op val
  34 .Nm
  35 .Op Fl C Ar class
  36 .Op Fl SHB
  37 .Op Fl cdflmnstuv Op val
  38 .Op Fl E
  39 .Op Ar name Ns = Ns Ar value ...
  40 .Op Ar command
  41 .Nm
  42 .Op Fl U Ar user
  43 .Op Fl SHB
  44 .Op Fl ea
  45 .Op Fl cdflmnstuv Op val
  46 .Nm
  47 .Op Fl U Ar user
  48 .Op Fl SHB
  49 .Op Fl cdflmnstuv Op val
  50 .Op Fl E
  51 .Op Ar name Ns = Ns Ar value ...
  52 .Op Ar command
  53 .Sh DESCRIPTION
  54 The
  55 .Nm
  56 utility either prints or sets kernel resource limits, and may optionally set
  57 environment variables like
  58 .Xr env 1
  59 and run a program with the selected resources.
  60 Three uses of the
  61 .Nm
  62 command are possible:
  63 .Pp
  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 .Pp
 140 .Bl -tag -width "-d [limit]"
 141 .It Fl C Ar class
 142 Use current resource values, modified by the resource entries applicable
 143 for the login class "class".
 144 .It Fl U Ar user
 145 Use current resource values, modified by the resource entries applicable
 146 to the login class which "user" belongs to.
 147 If the user does not belong to a class, then the resource capabilities
 148 for the "default" class are used, if it exists, or the "root" class if
 149 the user is a superuser account.
 150 .It Fl S
 151 Select display or setting of "soft" (or current) resource limits.
 152 If specific limits settings follow this switch, only soft limits are
 153 affected unless overridden later with either the
 154 .Fl H
 155 or
 156 .Fl B
 157 flags.
 158 .It Fl H
 159 Select display or setting of "hard" (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 flags.
 166 .It Fl B
 167 Select display or setting of both "soft" (current) or "hard" (maximum)
 168 resource limits.
 169 If specific limits settings follow this switch, both soft and hard
 170 limits are affected until overridden later with either the
 171 .Fl S
 172 or
 173 .Fl H
 174 flags.
 175 .Fl e
 176 Select "eval mode" formatting for output.
 177 This is valid only on display mode and cannot be used when running a
 178 command.
 179 The exact syntax used for output depends upon the type of shell from
 180 which
 181 .Nm
 182 is invoked.
 183 .It Fl b Op Ar limit
 184 Selects or sets the
 185 .Em sbsize
 186 resource limit.
 187 .It Fl c Op Ar limit
 188 Select or set (if 'limit' is specified) the
 189 .Em coredumpsize
 190 resource limit.
 191 A value of 0 disables core dumps.
 192 .It Fl d Op Ar limit
 193 Select or set (if 'limit' is specified) the
 194 .Em datasize
 195 resource limit.
 196 .It Fl f Op Ar limit
 197 Select or set the
 198 .Em filesize
 199 resource limit.
 200 .It Fl l Op Ar limit
 201 Select or set the
 202 .Em memorylocked
 203 resource limit.
 204 .It Fl m Op Ar limit
 205 Select or set the
 206 .Em memoryuse
 207 size limit.
 208 .It Fl n Op Ar limit
 209 Select or set the
 210 .Em openfiles
 211 resource limit.  The system-wide limit on the maximum number of
 212 open files per process can be viewed using the 'sysctl kern.maxfilesperproc'
 213 command.  The total number of simultaneously open files in the entire
 214 system is limited to the value displayed by the 'sysctl kern.maxfiles'
 215 command.
 216 .It Fl s Op Ar limit
 217 Select or set the
 218 .Em stacksize
 219 resource limit.
 220 .It Fl t Op Ar limit
 221 Select or set the
 222 .Em cputime
 223 resource limit.
 224 .It Fl u Op Ar limit
 225 Select or set the
 226 .Em maxproc
 227 resource limit.  The system-wide limit on the maximum number of processes
 228 allowed per UID can be viewed using the 'sysctl kern.maxprocperuid' command.
 229 The maximum number of processes that can be running simultaneously
 230 in the entire system is limited to the value given by
 231 the 'sysctl kern.maxproc' command.
 232 .It Fl v Op Ar limit
 233 Select or set the
 234 .Em virtualmem
 235 resource limit.
 236 This limit encompasses the entire VM space for the user process
 237 and is inclusive of text, data, bss, stack,
 238 .Xr brk 2 ,
 239 .Xr sbrk 2
 240 and
 241 .Xr mmap 2 Ns 'd
 242 space.
 243 .El
 244 .Pp
 245 Valid values for
 246 .Ar val
 247 in the above set of options consist of either the
 248 string
 249 .Dq Li infinity ,
 250 .Dq Li inf ,
 251 .Dq Li unlimited
 252 or
 253 .Dq Li unlimit
 254 for an infinite (or kernel-defined maximum)
 255 limit, or a numeric value optionally followed by a suffix.
 256 Values which relate to size default to a value in bytes, or one of the
 257 following suffixes may be used as a multiplier:
 258 .Pp
 259 .Bl -tag -offset indent -width 4n -compact
 260 .It Li b
 261 512 byte blocks.
 262 .It Li k
 263 kilobytes (1024 bytes).
 264 .It Li m
 265 megabytes (1024*1024 bytes).
 266 .It Li g
 267 gigabytes.
 268 .It Li t
 269 terabytes.
 270 .El
 271 .Pp
 272 The
 273 .Va cputime
 274 resource defaults to a number of seconds, but a multiplier may be
 275 used, and as with size values, multiple values separated by a valid
 276 suffix are added together:
 277 .Pp
 278 .Bl -tag -offset indent -width 4n -compact
 279 .It Li s
 280 seconds.
 281 .It Li m
 282 minutes.
 283 .It Li h
 284 hours.
 285 .It Li d
 286 days.
 287 .It Li w
 288 weeks.
 289 .It Li y
 290 365 day years.
 291 .El
 292 .Bl -tag -width ".Fl C Ar class"
 293 .It Fl E
 294 Cause
 295 .Nm
 296 to completely ignore the environment it inherits.
 297 .It Fl a
 298 Force all resource settings to be displayed even if
 299 other specific resource settings have been specified.
 300 For example, if you wish to disable core dumps when starting up
 301 the Usenet News system, but wish to set all other resource settings
 302 as well that apply to the
 303 .Dq Li news
 304 account, you might use:
 305 .Pp
 306 .Dl "eval `limits -U news -aBec 0`"
 307 .Pp
 308 As with the
 309 .Xr setrlimit 2
 310 call, only the superuser may raise process
 311 .Dq hard
 312 resource limits.
 313 Non-root users may, however, lower them or change
 314 .Dq soft
 315 resource limits
 316 within to any value below the hard limit.
 317 When invoked to execute a program, the failure of
 318 .Nm
 319 to raise a hard limit is considered a fatal error.
 320 .El
 321 .Sh DIAGNOSTICS
 322 The
 323 .Nm
 324 utility
 325 exits with EXIT_FAILURE if usage is incorrect in any way; i.e. an invalid
 326 option, or set/display options are selected in the same invocation,
 327 .Fl e
 328 is used when running a program, etc.
 329 When run in display or eval mode,
 330 .Nm
 331 exits with a status of EXIT_SUCCESS.
 332 When run in command mode and execution of the command succeeds, the exit status
 333 will be whatever the executed program returns.
 334 .Sh SEE ALSO
 335 .Xr csh 1 ,
 336 .Xr env 1 ,
 337 .Xr limit 1 ,
 338 .Xr sh 1 ,
 339 .Xr getrlimit 2 ,
 340 .Xr setrlimit 2 ,
 341 .Xr login_cap 3 ,
 342 .Xr login.conf 5 ,
 343 .Xr sysctl 8
 344 .Sh BUGS
 345 The
 346 .Nm
 347 utility does not handle commands with equal (``='') signs in their
 348 names, for obvious reasons.
 349 .Pp
 350 When eval output is selected, the
 351 .Pa /proc
 352 filesystem must be installed
 353 and mounted for the shell to be correctly determined, and therefore
 354 output syntax correct for the running shell.
 355 The default output is valid for
 356 .Xr sh 1 ,
 357 so this means that any
 358 usage of
 359 .Nm
 360 in eval mode prior mounting
 361 .Pa /proc
 362 may only occur in standard bourne
 363 shell scripts.
 364 .Pp
 365 The
 366 .Nm
 367 utility makes no effort to ensure that resource settings emitted or displayed
 368 are valid and settable by the current user.
 369 Only a superuser account may raise hard limits, and when doing so
 370 the
 371 .Fx
 372 kernel will silently lower limits to values less than
 373 specified if the values given are too high.