man3p/getrlimit.3p

   1 .\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
   2 .TH "GETRLIMIT" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
   3 .\" getrlimit
   4 .SH NAME
   5 getrlimit, setrlimit \- control maximum resource consumption
   6 .SH SYNOPSIS
   7 .LP
   8 \fB#include <sys/resource.h>
   9 .br
  10 .sp
  11 int getrlimit(int\fP \fIresource\fP\fB, struct rlimit *\fP\fIrlp\fP\fB);
  12 .br
  13 int setrlimit(int\fP \fIresource\fP\fB, const struct rlimit *\fP\fIrlp\fP\fB);
  14 \fP
  15 \fB
  16 .br
  17 \fP
  18 .SH DESCRIPTION
  19 .LP
  20 The \fIgetrlimit\fP() function shall get, and the \fIsetrlimit\fP()
  21 function shall set, limits on the consumption of a variety
  22 of resources.
  23 .LP
  24 Each call to either \fIgetrlimit\fP() or \fIsetrlimit\fP() identifies
  25 a specific resource to be operated upon as well as a
  26 resource limit. A resource limit is represented by an \fBrlimit\fP
  27 structure. The \fIrlim_cur\fP member specifies the current or
  28 soft limit and the \fIrlim_max\fP member specifies the maximum or
  29 hard limit. Soft limits may be changed by a process to any value
  30 that is less than or equal to the hard limit. A process may (irreversibly)
  31 lower its hard limit to any value that is greater than
  32 or equal to the soft limit. Only a process with appropriate privileges
  33 can raise a hard limit. Both hard and soft limits can be
  34 changed in a single call to \fIsetrlimit\fP() subject to the constraints
  35 described above.
  36 .LP
  37 The value RLIM_INFINITY, defined in \fI<sys/resource.h>\fP, shall
  38 be
  39 considered to be larger than any other limit value. If a call to \fIgetrlimit\fP()
  40 returns RLIM_INFINITY for a resource, it means
  41 the implementation shall not enforce limits on that resource. Specifying
  42 RLIM_INFINITY as any resource limit value on a successful
  43 call to \fIsetrlimit\fP() shall inhibit enforcement of that resource
  44 limit.
  45 .LP
  46 The following resources are defined:
  47 .TP 7
  48 RLIMIT_CORE
  49 This is the maximum size of a \fBcore\fP file, in bytes, that may
  50 be created by a process. A limit of 0 shall prevent the
  51 creation of a \fBcore\fP file. If this limit is exceeded, the writing
  52 of a \fBcore\fP file shall terminate at this size.
  53 .TP 7
  54 RLIMIT_CPU
  55 This is the maximum amount of CPU time, in seconds, used by a process.
  56 If this limit is exceeded, SIGXCPU shall be generated
  57 for the process. If the process is catching or ignoring SIGXCPU, or
  58 all threads belonging to that process are blocking SIGXCPU, the
  59 behavior is unspecified.
  60 .TP 7
  61 RLIMIT_DATA
  62 This is the maximum size of a process' data segment, in bytes. If
  63 this limit is exceeded, the \fImalloc\fP() function shall fail with
  64 \fIerrno\fP set to [ENOMEM].
  65 .TP 7
  66 RLIMIT_FSIZE
  67 This is the maximum size of a file, in bytes, that may be created
  68 by a process. If a write or truncate operation would cause
  69 this limit to be exceeded, SIGXFSZ shall be generated for the thread.
  70 If the thread is blocking, or the process is catching or
  71 ignoring SIGXFSZ, continued attempts to increase the size of a file
  72 from end-of-file to beyond the limit shall fail with
  73 \fIerrno\fP set to [EFBIG].
  74 .TP 7
  75 RLIMIT_NOFILE
  76 This is a number one greater than the maximum value that the system
  77 may assign to a newly-created descriptor. If this limit is
  78 exceeded, functions that allocate a file descriptor shall fail with
  79 \fIerrno\fP set to [EMFILE]. This limit constrains the number
  80 of file descriptors that a process may allocate.
  81 .TP 7
  82 RLIMIT_STACK
  83 This is the maximum size of a process' stack, in bytes. The implementation
  84 does not automatically grow the stack beyond this
  85 limit. If this limit is exceeded, SIGSEGV shall be generated for the
  86 thread. If the thread is blocking SIGSEGV, or the process is
  87 ignoring or catching SIGSEGV and has not made arrangements to use
  88 an alternate stack, the disposition of SIGSEGV shall be set to
  89 SIG_DFL before it is generated.
  90 .TP 7
  91 RLIMIT_AS
  92 This is the maximum size of a process' total available memory, in
  93 bytes. If this limit is exceeded, the \fImalloc\fP() and \fImmap\fP()
  94 functions shall fail with
  95 \fIerrno\fP set to [ENOMEM]. In addition, the automatic stack growth
  96 fails with the effects outlined above.
  97 .sp
  98 .LP
  99 When using the \fIgetrlimit\fP() function, if a resource limit can
 100 be represented correctly in an object of type \fBrlim_t\fP,
 101 then its representation is returned; otherwise, if the value of the
 102 resource limit is equal to that of the corresponding saved hard
 103 limit, the value returned shall be RLIM_SAVED_MAX; otherwise, the
 104 value returned shall be RLIM_SAVED_CUR.
 105 .LP
 106 When using the \fIsetrlimit\fP() function, if the requested new limit
 107 is RLIM_INFINITY, the new limit shall be "no limit'';
 108 otherwise, if the requested new limit is RLIM_SAVED_MAX, the new limit
 109 shall be the corresponding saved hard limit; otherwise, if
 110 the requested new limit is RLIM_SAVED_CUR, the new limit shall be
 111 the corresponding saved soft limit; otherwise, the new limit
 112 shall be the requested value. In addition, if the corresponding saved
 113 limit can be represented correctly in an object of type
 114 \fBrlim_t\fP then it shall be overwritten with the new limit.
 115 .LP
 116 The result of setting a limit to RLIM_SAVED_MAX or RLIM_SAVED_CUR
 117 is unspecified unless a previous call to \fIgetrlimit\fP()
 118 returned that value as the soft or hard limit for the corresponding
 119 resource limit.
 120 .LP
 121 The determination of whether a limit can be correctly represented
 122 in an object of type \fBrlim_t\fP is implementation-defined.
 123 For example, some implementations permit a limit whose value is greater
 124 than RLIM_INFINITY and others do not.
 125 .LP
 126 The \fIexec\fP family of functions shall cause resource limits to
 127 be saved.
 128 .SH RETURN VALUE
 129 .LP
 130 Upon successful completion, \fIgetrlimit\fP() and \fIsetrlimit\fP()
 131 shall return 0. Otherwise, these functions shall return -1
 132 and set \fIerrno\fP to indicate the error.
 133 .SH ERRORS
 134 .LP
 135 The \fIgetrlimit\fP() and \fIsetrlimit\fP() functions shall fail if:
 136 .TP 7
 137 .B EINVAL
 138 An invalid \fIresource\fP was specified; or in a \fIsetrlimit\fP()
 139 call, the new \fIrlim_cur\fP exceeds the new
 140 \fIrlim_max\fP.
 141 .TP 7
 142 .B EPERM
 143 The limit specified to \fIsetrlimit\fP() would have raised the maximum
 144 limit value, and the calling process does not have
 145 appropriate privileges.
 146 .sp
 147 .LP
 148 The \fIsetrlimit\fP() function may fail if:
 149 .TP 7
 150 .B EINVAL
 151 The limit specified cannot be lowered because current usage is already
 152 higher than the limit.
 153 .sp
 154 .LP
 155 \fIThe following sections are informative.\fP
 156 .SH EXAMPLES
 157 .LP
 158 None.
 159 .SH APPLICATION USAGE
 160 .LP
 161 If a process attempts to set the hard limit or soft limit for RLIMIT_NOFILE
 162 to less than the value of {_POSIX_OPEN_MAX} from \fI<limits.h>\fP,
 163 unexpected behavior may occur.
 164 .LP
 165 If a process attempts to set the hard limit or soft limit for RLIMIT_NOFILE
 166 to less than the highest currently open file
 167 descriptor +1, unexpected behavior may occur.
 168 .SH RATIONALE
 169 .LP
 170 None.
 171 .SH FUTURE DIRECTIONS
 172 .LP
 173 None.
 174 .SH SEE ALSO
 175 .LP
 176 \fIexec\fP() , \fIfork\fP() , \fImalloc\fP() , \fIopen\fP() , \fIsigaltstack\fP()
 177 ,
 178 \fIsysconf\fP() , \fIulimit\fP() , the Base Definitions volume of
 179 IEEE\ Std\ 1003.1-2001, \fI<stropts.h>\fP, \fI<sys/resource.h>\fP
 180 .SH COPYRIGHT
 181 Portions of this text are reprinted and reproduced in electronic form
 182 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
 183 -- Portable Operating System Interface (POSIX), The Open Group Base
 184 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
 185 Electrical and Electronics Engineers, Inc and The Open Group. In the
 186 event of any discrepancy between this version and the original IEEE and
 187 The Open Group Standard, the original IEEE and The Open Group Standard
 188 is the referee document. The original Standard can be obtained online at
 189 http://www.opengroup.org/unix/online.html .