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