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