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 limits
  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 (ie. it is one of sh, csh, bash, tcsh, ksh,
 103 pdksh or rc),
 104 .Nm limits
 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 limits
 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 limits
 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 Selects 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 Selects 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 Selects 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 Selects "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 limits
 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 Selects or sets (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 Selects or sets (if 'limit' is specified) the
 186 .Em datasize
 187 resource limit.
 188 .It Fl f Op Ar limit
 189 Selects or sets the
 190 .Em filesize
 191 resource limit.
 192 .It Fl l Op Ar limit
 193 Selects or sets the
 194 .Em memorylocked
 195 resource limit.
 196 .It Fl m Op Ar limit
 197 Selects or sets the
 198 .Em memoryuse
 199 size limit.
 200 .It Fl n Op Ar limit
 201 Selects or sets 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 Selects or sets the
 210 .Em stacksize
 211 resource limit.
 212 .It Fl t Op Ar limit
 213 Selects or sets the
 214 .Em cputime
 215 resource limit.
 216 .It Fl u Op Ar limit
 217 Selects or sets 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 'limit' in the above set of flags consist of either the
 226 string 'infinity' or 'inf' for an infinite (or kernel-defined maximum)
 227 limit, or a numeric value maybe followed by a suffix.
 228 Values which relate to size default to a value in bytes, or one of the
 229 following suffixes may be used as a multiplier:
 230 .Pp
 231 .Bl -tag -offset indent -width "xxxx" -compact
 232 .It b
 233 512 byte blocks.
 234 .It k
 235 kilobytes (1024 bytes).
 236 .It m
 237 megabytes (1024*1024 bytes).
 238 .It g
 239 gigabytes.
 240 .It t
 241 terabytes.
 242 .El
 243 .Pp
 244 The
 245 .Em cputime
 246 resource defaults to a number of seconds, but a multiplier may be
 247 used, and as with size values, multiple values separated by a valid
 248 suffix are added together:
 249 .Bl -tag -offset indent -width "xxxx" -compact
 250 .It s
 251 seconds.
 252 .It m
 253 minutes.
 254 .It h
 255 hours.
 256 .It d
 257 days.
 258 .It w
 259 weeks.
 260 .It y
 261 365 day years.
 262 .El
 263 .Pp
 264 .It Fl E
 265 The option
 266 .Sq Fl E
 267 causes
 268 .Nm limits
 269 to completely ignore the environment it inherits.
 270 .It Fl a
 271 This option forces all resource settings to be displayed even if
 272 other specific resource settings have been specified.
 273 For example, if you wish to disable core dumps when starting up
 274 the usenet news system, but wish to set all other resource settings
 275 as well that apply to the 'news' account, you might use:
 276 .Pp
 277 .Dl eval `limits -U news -aBec 0`
 278 .Pp
 279 As with the
 280 .Xr setrlimit 2
 281 call, only the superuser may raise process "hard" resource limits.
 282 Non-root users may, however, lower them or change "soft" resource limits
 283 within to any value below the hard limit.
 284 When invoked to execute a program, the failure of
 285 .Nm limits
 286 to raise a hard limit is considered a fatal error.
 287 .El
 288 .Sh DIAGNOSTICS
 289 .Nm Limits
 290 exits with EXIT_FAILURE if usage is incorrect in any way; ie. an invalid
 291 option, or set/display options are selected in the same invocation,
 292 .Fl e
 293 is used when running a program, etc.
 294 When run in display or eval mode,
 295 .Nm limits
 296 exits with a status of EXIT_SUCCESS.
 297 When run in command mode and execution of the command succeeds, the exit status
 298 will be whatever the executed program returns.
 299 .Sh SEE ALSO
 300 .Xr csh 1 ,
 301 .Xr env 1 ,
 302 .Xr limit 1 ,
 303 .Xr sh 1 ,
 304 .Xr getrlimit 2 ,
 305 .Xr setrlimit 2 ,
 306 .Xr login_cap 3 ,
 307 .Xr login.conf 5 ,
 308 .Xr sysctl 8
 309 .Sh BUGS
 310 .Nm Limits
 311 does not handle commands with equal (``='') signs in their
 312 names, for obvious reasons.
 313 .Pp
 314 When eval output is selected, the /proc filesystem must be installed
 315 and mounted for the shell to be correctly determined, and therefore
 316 output syntax correct for the running shell.
 317 The default output is valid for /bin/sh, so this means that any
 318 usage of
 319 .Nm limits
 320 in eval mode prior mounting /proc may only occur in standard bourne
 321 shell scripts.
 322 .Pp
 323 .Nm Limits
 324 makes no effort to ensure that resource settings emitted or displayed
 325 are valid and settable by the current user.
 326 Only a superuser account may raise hard limits, and when doing so
 327 the FreeBSD kernel will silently lower limits to values less than
 328 specified if the values given are too high.