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