| blob | 21af178d0d9ffd019a8cf4bc10eede3574ca61b5 |
1 .\"
2 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
3 .\" permission to reproduce portions of its copyrighted documentation.
4 .\" Original documentation from The Open Group can be obtained online at
5 .\" http://www.opengroup.org/bookstore/.
6 .\"
7 .\" The Institute of Electrical and Electronics Engineers and The Open
8 .\" Group, have given us permission to reprint portions of their
9 .\" documentation.
10 .\"
11 .\" In the following statement, the phrase ``this text'' refers to portions
12 .\" of the system documentation.
13 .\"
14 .\" Portions of this text are reprinted and reproduced in electronic form
15 .\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
16 .\" Standard for Information Technology -- Portable Operating System
17 .\" Interface (POSIX), The Open Group Base Specifications Issue 6,
18 .\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
19 .\" Engineers, Inc and The Open Group. In the event of any discrepancy
20 .\" between these versions and the original IEEE and The Open Group
21 .\" Standard, the original IEEE and The Open Group Standard is the referee
22 .\" document. The original Standard can be obtained online at
23 .\" http://www.opengroup.org/unix/online.html.
24 .\"
25 .\" This notice shall appear on any product containing this material.
26 .\"
27 .\" The contents of this file are subject to the terms of the
28 .\" Common Development and Distribution License (the "License").
29 .\" You may not use this file except in compliance with the License.
30 .\"
31 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
32 .\" or http://www.opensolaris.org/os/licensing.
33 .\" See the License for the specific language governing permissions
34 .\" and limitations under the License.
35 .\"
36 .\" When distributing Covered Code, include this CDDL HEADER in each
37 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
38 .\" If applicable, add the following below this CDDL HEADER, with the
39 .\" fields enclosed by brackets "[]" replaced with your own identifying
40 .\" information: Portions Copyright [yyyy] [name of copyright owner]
41 .\"
42 .\"
43 .\" Copyright 1989 AT&T
44 .\" Portions Copyright (c) 1994, X/Open Company Limited. All Rights Reserved.
45 .\" Copyright (c) 2006, Sun Microsystems, Inc. All Rights Reserved.
46 .\"
47 .TH GETRLIMIT 2 "Aug 21, 2006"
48 .SH NAME
49 getrlimit, setrlimit \- control maximum system resource consumption
50 .SH SYNOPSIS
51 .LP
52 .nf
53 #include <sys/resource.h>
55 \fBint\fR \fBgetrlimit\fR(\fBint\fR \fIresource\fR, \fBstruct rlimit *\fR\fIrlp\fR);
56 .fi
58 .LP
59 .nf
60 \fBint\fR \fBsetrlimit\fR(\fBint\fR \fIresource\fR, \fBconst struct rlimit *\fR\fIrlp\fR);
61 .fi
63 .SH DESCRIPTION
64 .sp
65 .LP
66 Limits on the consumption of a variety of system resources by a process and
67 each process it creates may be obtained with the \fBgetrlimit()\fR and set with
68 \fBsetrlimit()\fR functions.
69 .sp
70 .LP
71 Each call to either \fBgetrlimit()\fR or \fBsetrlimit()\fR identifies a
72 specific resource to be operated upon as well as a resource limit. A resource
73 limit is a pair of values: one specifying the current (soft) limit, the other
74 a maximum (hard) limit. Soft limits may be changed by a process to any value
75 that is less than or equal to the hard limit. A process may (irreversibly)
76 lower its hard limit to any value that is greater than or equal to the soft
77 limit. Only a process with {\fBPRIV_SYS_RESOURCE\fR} asserted in the effective
78 set can raise a hard limit. Both hard and soft limits can be changed in a
79 single call to \fBsetrlimit()\fR subject to the constraints described above.
80 Limits may have an "infinite" value of \fBRLIM_INFINITY\fR. The \fIrlp\fR
81 argument is a pointer to \fBstruct\fR \fBrlimit\fR that includes the following
82 members:
83 .sp
84 .in +2
85 .nf
86 rlim_t rlim_cur; /* current (soft) limit */
87 rlim_t rlim_max; /* hard limit */
88 .fi
89 .in -2
91 .sp
92 .LP
93 The type \fBrlim_t\fR is an arithmetic data type to which objects of type
94 \fBint\fR, \fBsize_t\fR, and \fBoff_t\fR can be cast without loss of
95 information.
96 .sp
97 .LP
98 The possible resources, their descriptions, and the actions taken when the
99 current limit is exceeded are summarized as follows:
100 .sp
101 .ne 2
102 .na
103 \fB\fBRLIMIT_CORE\fR\fR
104 .ad
105 .RS 17n
106 The maximum size of a core file in bytes that may be created by a process. A
107 limit of \fB0\fR will prevent the creation of a core file. The writing of a
108 core file will terminate at this size.
109 .RE
111 .sp
112 .ne 2
113 .na
114 \fB\fBRLIMIT_CPU\fR\fR
115 .ad
116 .RS 17n
117 The maximum amount of CPU time in seconds used by a process. This is a soft
118 limit only. The \fBSIGXCPU\fR signal is sent to the process. If the process is
119 holding or ignoring \fBSIGXCPU\fR, the behavior is scheduling class defined.
120 .RE
122 .sp
123 .ne 2
124 .na
125 \fB\fBRLIMIT_DATA\fR\fR
126 .ad
127 .RS 17n
128 The maximum size of a process's heap in bytes. The \fBbrk\fR(2) function will
129 fail with \fBerrno\fR set to \fBENOMEM\fR.
130 .RE
132 .sp
133 .ne 2
134 .na
135 \fB\fBRLIMIT_FSIZE\fR\fR
136 .ad
137 .RS 17n
138 The maximum size of a file in bytes that may be created by a process. A limit
139 of \fB0\fR will prevent the creation of a file. The \fBSIGXFSZ\fR signal is
140 sent to the process. If the process is holding or ignoring \fBSIGXFSZ\fR,
141 continued attempts to increase the size of a file beyond the limit will fail
142 with \fBerrno\fR set to \fBEFBIG\fR.
143 .RE
145 .sp
146 .ne 2
147 .na
148 \fB\fBRLIMIT_NOFILE\fR\fR
149 .ad
150 .RS 17n
151 One more than the maximum value that the system may assign to a newly created
152 descriptor. This limit constrains the number of file descriptors that a process
153 may create.
154 .RE
156 .sp
157 .ne 2
158 .na
159 \fB\fBRLIMIT_STACK\fR\fR
160 .ad
161 .RS 17n
162 The maximum size of a process's stack in bytes. The system will not
163 automatically grow the stack beyond this limit.
164 .sp
165 Within a process, \fBsetrlimit()\fR will increase the limit on the size of your
166 stack, but will not move current memory segments to allow for that growth. To
167 guarantee that the process stack can grow to the limit, the limit must be
168 altered prior to the execution of the process in which the new stack size is to
169 be used.
170 .sp
171 Within a multithreaded process, \fBsetrlimit()\fR has no impact on the stack
172 size limit for the calling thread if the calling thread is not the main thread.
173 A call to \fBsetrlimit()\fR for \fBRLIMIT_STACK\fR impacts only the main
174 thread's stack, and should be made only from the main thread, if at all.
175 .sp
176 The \fBSIGSEGV\fR signal is sent to the process. If the process is holding or
177 ignoring \fBSIGSEGV\fR, or is catching \fBSIGSEGV\fR and has not made
178 arrangements to use an alternate stack (see \fBsigaltstack\fR(2)), the
179 disposition of \fBSIGSEGV\fR will be set to \fBSIG_DFL\fR before it is sent.
180 .RE
182 .sp
183 .ne 2
184 .na
185 \fB\fBRLIMIT_VMEM\fR\fR
186 .ad
187 .RS 17n
188 The maximum size of a process's mapped address space in bytes. If this limit
189 is exceeded, the \fBbrk\fR(2) and \fBmmap\fR(2) functions will fail with
190 \fBerrno\fR set to \fBENOMEM\fR. In addition, the automatic stack growth will
191 fail with the effects outlined above.
192 .RE
194 .sp
195 .ne 2
196 .na
197 \fB\fBRLIMIT_AS\fR\fR
198 .ad
199 .RS 17n
200 This is the maximum size of a process's total available memory, in bytes. If
201 this limit is exceeded, the \fBbrk\fR(2), \fBmalloc\fR(3C), \fBmmap\fR(2) and
202 \fBsbrk\fR(2) functions will fail with \fBerrno\fR set to \fBENOMEM\fR. In
203 addition, the automatic stack growth will fail with the effects outlined above.
204 .RE
206 .sp
207 .LP
208 Because limit information is stored in the per-process information, the shell
209 builtin \fBulimit\fR command must directly execute this system call if it is to
210 affect all future processes created by the shell.
211 .sp
212 .LP
213 The value of the current limit of the following resources affect these
214 implementation defined parameters:
215 .sp
217 .sp
218 .TS
219 c c
220 l l .
221 Limit Implementation Defined Constant
222 \fBRLIMIT_FSIZE\fR \fBFCHR_MAX\fR
223 \fBRLIMIT_NOFILE\fR \fBOPEN_MAX\fR
224 .TE
226 .sp
227 .LP
228 When using the \fBgetrlimit()\fR function, if a resource limit can be
229 represented correctly in an object of type \fBrlim_t\fR, then its
230 representation is returned; otherwise, if the value of the resource limit is
231 equal to that of the corresponding saved hard limit, the value returned is
232 \fBRLIM_SAVED_MAX\fR; otherwise the value returned is \fBRLIM_SAVED_CUR\fR.
233 .sp
234 .LP
235 When using the \fBsetrlimit()\fR function, if the requested new limit is
236 \fBRLIM_INFINITY\fR, the new limit will be "no limit"; otherwise if the
237 requested new limit is \fBRLIM_SAVED_MAX\fR, the new limit will be the
238 corresponding saved hard limit; otherwise, if the requested new limit is
239 \fBRLIM_SAVED_CUR\fR, the new limit will be the corresponding saved soft limit;
240 otherwise, the new limit will be the requested value. In addition, if the
241 corresponding saved limit can be represented correctly in an object of type
242 \fBrlim_t\fR, then it will be overwritten with the new limit.
243 .sp
244 .LP
245 The result of setting a limit to \fBRLIM_SAVED_MAX\fR or \fBRLIM_SAVED_CUR\fR
246 is unspecified unless a previous call to \fBgetrlimit()\fR returned that value
247 as the soft or hard limit for the corresponding resource limit.
248 .sp
249 .LP
250 A limit whose value is greater than \fBRLIM_INFINITY\fR is permitted.
251 .sp
252 .LP
253 The \fBexec\fR family of functions also cause resource limits to be saved. See
254 \fBexec\fR(2).
255 .SH RETURN VALUES
256 .sp
257 .LP
258 Upon successful completion, \fBgetrlimit()\fR and \fBsetrlimit()\fR return
259 \fB0\fR. Otherwise, these functions return \fB\(mi1\fR and set \fBerrno\fR to
260 indicate the error.
261 .SH ERRORS
262 .sp
263 .LP
264 The \fBgetrlimit()\fR and \fBsetrlimit()\fR functions will fail if:
265 .sp
266 .ne 2
267 .na
268 \fB\fBEFAULT\fR\fR
269 .ad
270 .RS 10n
271 The \fIrlp\fR argument points to an illegal address.
272 .RE
274 .sp
275 .ne 2
276 .na
277 \fB\fBEINVAL\fR\fR
278 .ad
279 .RS 10n
280 An invalid \fIresource\fR was specified; or in a \fBsetrlimit()\fR call, the
281 new \fBrlim_cur\fR exceeds the new \fBrlim_max\fR.
282 .RE
284 .sp
285 .ne 2
286 .na
287 \fB\fBEPERM\fR\fR
288 .ad
289 .RS 10n
290 The limit specified to \fBsetrlimit()\fR would have raised the maximum limit
291 value and {\fBPRIV_SYS_RESOURCE\fR} is not asserted in the effective set of the
292 current process.
293 .RE
295 .sp
296 .LP
297 The \fBsetrlimit()\fR function may fail if:
298 .sp
299 .ne 2
300 .na
301 \fB\fBEINVAL\fR\fR
302 .ad
303 .RS 10n
304 The limit specified cannot be lowered because current usage is already higher
305 than the limit.
306 .RE
308 .sp
309 .LP
310 The rlimit functionality is now provided by the more general resource control
311 facility described on the \fBsetrctl\fR(2) manual page. The actions associated
312 with the resource limits described above are true at system boot, but an
313 administrator can modify the local configuration to modify signal delivery or
314 type. Application authors that utilize rlimits for the purposes of resource
315 awareness should investigate the resource controls facility.
316 .SH ATTRIBUTES
317 .sp
318 .LP
319 See \fBattributes\fR(5) for descriptions of the following attributes:
320 .sp
322 .sp
323 .TS
324 box;
325 c | c
326 l | l .
327 ATTRIBUTE TYPE ATTRIBUTE VALUE
328 _
329 Interface Stability Standard
330 .TE
332 .SH SEE ALSO
333 .sp
334 .LP
335 \fBrctladm\fR(8), \fBbrk\fR(2), \fBexec\fR(2), \fBfork\fR(2), \fBopen\fR(2),
336 \fBsetrctl\fR(2), \fBsigaltstack\fR(2), \fBulimit\fR(2),
337 \fBgetdtablesize\fR(3C), \fBmalloc\fR(3C), \fBsignal\fR(3C),
338 \fBsignal.h\fR(3HEAD), \fBsysconf\fR(3C), \fBattributes\fR(5),
339 \fBprivileges\fR(5), \fBresource_controls\fR(5), \fBstandards\fR(5)