sysconf.html

IEEE 1003.1-2003, Single Unix Specification v3

</tr>

<tr valign="top">
<td align="left">
<p class="tent">{PTHREAD_THREADS_MAX}</p>
</td>
<td align="left">
<p class="tent">_SC_THREAD_THREADS_MAX</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent">{RE_DUP_MAX}</p>
</td>
<td align="left">
<p class="tent">_SC_RE_DUP_MAX</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent">{RTSIG_MAX}</p>
</td>
<td align="left">
<p class="tent">_SC_RTSIG_MAX</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent">{SEM_NSEMS_MAX}</p>
</td>
<td align="left">
<p class="tent">_SC_SEM_NSEMS_MAX</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent">{SEM_VALUE_MAX}</p>
</td>
<td align="left">
<p class="tent">_SC_SEM_VALUE_MAX</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent">{SIGQUEUE_MAX}</p>
</td>
<td align="left">
<p class="tent">_SC_SIGQUEUE_MAX</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent">{STREAM_MAX}</p>
</td>
<td align="left">
<p class="tent">_SC_STREAM_MAX</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent">{SYMLOOP_MAX}</p>
</td>
<td align="left">
<p class="tent">_SC_SYMLOOP_MAX</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent">{TIMER_MAX}</p>
</td>
<td align="left">
<p class="tent">_SC_TIMER_MAX</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent">{TTY_NAME_MAX}</p>
</td>
<td align="left">
<p class="tent">_SC_TTY_NAME_MAX</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent">{TZNAME_MAX}</p>
</td>
<td align="left">
<p class="tent">_SC_TZNAME_MAX</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent">_XBS5_ILP32_OFF32 (<b>LEGACY</b>)</p>
</td>
<td align="left">
<p class="tent">_SC_XBS5_ILP32_OFF32 (<b>LEGACY</b>)</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent">_XBS5_ILP32_OFFBIG (<b>LEGACY</b>)</p>
</td>
<td align="left">
<p class="tent">_SC_XBS5_ILP32_OFFBIG (<b>LEGACY</b>)</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent">_XBS5_LP64_OFF64 (<b>LEGACY</b>)</p>
</td>
<td align="left">
<p class="tent">_SC_XBS5_LP64_OFF64 (<b>LEGACY</b>)</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent">_XBS5_LPBIG_OFFBIG (<b>LEGACY</b>)</p>
</td>
<td align="left">
<p class="tent">_SC_XBS5_LPBIG_OFFBIG (<b>LEGACY</b>)</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent">_XOPEN_CRYPT</p>
</td>
<td align="left">
<p class="tent">_SC_XOPEN_CRYPT</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent">_XOPEN_ENH_I18N</p>
</td>
<td align="left">
<p class="tent">_SC_XOPEN_ENH_I18N</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent">_XOPEN_LEGACY</p>
</td>
<td align="left">
<p class="tent">_SC_XOPEN_LEGACY</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent">_XOPEN_REALTIME</p>
</td>
<td align="left">
<p class="tent">_SC_XOPEN_REALTIME</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent">_XOPEN_REALTIME_THREADS</p>
</td>
<td align="left">
<p class="tent">_SC_XOPEN_REALTIME_THREADS</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent">_XOPEN_SHM</p>
</td>
<td align="left">
<p class="tent">_SC_XOPEN_SHM</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent">_XOPEN_STREAMS</p>
</td>
<td align="left">
<p class="tent">_SC_XOPEN_STREAMS</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent">_XOPEN_UNIX</p>
</td>
<td align="left">
<p class="tent">_SC_XOPEN_UNIX</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent">_XOPEN_VERSION</p>
</td>
<td align="left">
<p class="tent">_SC_XOPEN_VERSION</p>
</td>
</tr>

<tr valign="top">
<td align="left">
<p class="tent">_XOPEN_XCU_VERSION</p>
</td>
<td align="left">
<p class="tent">_SC_XOPEN_XCU_VERSION</p>
</td>
</tr>
</table>
</center>
</blockquote>

<h4><a name="tag_03_755_04"></a>RETURN VALUE</h4>

<blockquote>
<p>If <i>name</i> is an invalid value, <i>sysconf</i>() shall return -1 and set <i>errno</i> to indicate the error. If the variable
corresponding to <i>name</i> has no limit, <i>sysconf</i>() shall return -1 without changing the value of <i>errno</i>. Note that
indefinite limits do not imply infinite limits; see <a href="../basedefs/limits.h.html"><i>&lt;limits.h&gt;</i></a>.</p>

<p>Otherwise, <i>sysconf</i>() shall return the current variable value on the system. The value returned shall not be more
restrictive than the corresponding value described to the application when it was compiled with the implementation's <a href=
"../basedefs/limits.h.html"><i>&lt;limits.h&gt;</i></a> or <a href="../basedefs/unistd.h.html"><i>&lt;unistd.h&gt;</i></a>. The
value shall not change during the lifetime of the calling process, <sup>[<a href="javascript:open_code('XSI')">XSI</a>]</sup> <img
src="../images/opt-start.gif" alt="[Option Start]" border="0"> &nbsp;except that <i>sysconf</i>(_SC_OPEN_MAX) may return different
values before and after a call to <a href="../functions/setrlimit.html"><i>setrlimit</i>()</a> which changes the RLIMIT_NOFILE soft
limit. <img src="../images/opt-end.gif" alt="[Option End]" border="0"></p>
</blockquote>

<h4><a name="tag_03_755_05"></a>ERRORS</h4>

<blockquote>
<p>The <i>sysconf</i>() function shall fail if:</p>

<dl compact>
<dt>[EINVAL]</dt>

<dd>The value of the <i>name</i> argument is invalid.</dd>
</dl>
</blockquote>

<hr>
<div class="box"><em>The following sections are informative.</em></div>

<h4><a name="tag_03_755_06"></a>EXAMPLES</h4>

<blockquote>
<p>None.</p>
</blockquote>

<h4><a name="tag_03_755_07"></a>APPLICATION USAGE</h4>

<blockquote>
<p>As -1 is a permissible return value in a successful situation, an application wishing to check for error situations should set
<i>errno</i> to 0, then call <i>sysconf</i>(), and, if it returns -1, check to see if <i>errno</i> is non-zero.</p>

<p>If the value of <i>sysconf</i>(_SC_2_VERSION) is not equal to the value of the _POSIX2_VERSION symbolic constant, the utilities
available via <a href="../functions/system.html"><i>system</i>()</a> or <a href="../functions/popen.html"><i>popen</i>()</a> might
not behave as described in the Shell and Utilities volume of IEEE&nbsp;Std&nbsp;1003.1-2001. This would mean that the application
is not running in an environment that conforms to the Shell and Utilities volume of IEEE&nbsp;Std&nbsp;1003.1-2001. Some
applications might be able to deal with this, others might not. However, the functions defined in this volume of
IEEE&nbsp;Std&nbsp;1003.1-2001 continue to operate as specified, even if <i>sysconf</i>(_SC_2_VERSION) reports that the utilities
no longer perform as specified.</p>
</blockquote>

<h4><a name="tag_03_755_08"></a>RATIONALE</h4>

<blockquote>
<p>This functionality was added in response to requirements of application developers and of system vendors who deal with many
international system configurations. It is closely related to <a href="../functions/pathconf.html"><i>pathconf</i>()</a> and <a
href="../functions/fpathconf.html"><i>fpathconf</i>()</a>.</p>

<p>Although a conforming application can run on all systems by never demanding more resources than the minimum values published in
this volume of IEEE&nbsp;Std&nbsp;1003.1-2001, it is useful for that application to be able to use the actual value for the
quantity of a resource available on any given system. To do this, the application makes use of the value of a symbolic constant in
<a href="../basedefs/limits.h.html"><i>&lt;limits.h&gt;</i></a> or <a href=
"../basedefs/unistd.h.html"><i>&lt;unistd.h&gt;</i></a>.</p>

<p>However, once compiled, the application must still be able to cope if the amount of resource available is increased. To that
end, an application may need a means of determining the quantity of a resource, or the presence of an option, at execution
time.</p>

<p>Two examples are offered:</p>

<ol>
<li>
<p>Applications may wish to act differently on systems with or without job control. Applications vendors who wish to distribute
only a single binary package to all instances of a computer architecture would be forced to assume job control is never available
if it were to rely solely on the <a href="../basedefs/unistd.h.html"><i>&lt;unistd.h&gt;</i></a> value published in this volume of
IEEE&nbsp;Std&nbsp;1003.1-2001.</p>
</li>

<li>
<p>International applications vendors occasionally require knowledge of the number of clock ticks per second. Without these
facilities, they would be required to either distribute their applications partially in source form or to have 50 Hz and 60 Hz
versions for the various countries in which they operate.</p>
</li>
</ol>

<p>It is the knowledge that many applications are actually distributed widely in executable form that leads to this facility. If
limited to the most restrictive values in the headers, such applications would have to be prepared to accept the most limited
environments offered by the smallest microcomputers. Although this is entirely portable, there was a consensus that they should be
able to take advantage of the facilities offered by large systems, without the restrictions associated with source and object
distributions.</p>

<p>During the discussions of this feature, it was pointed out that it is almost always possible for an application to discern what
a value might be at runtime by suitably testing the various functions themselves. And, in any event, it could always be written to
adequately deal with error returns from the various functions. In the end, it was felt that this imposed an unreasonable level of
complication and sophistication on the application writer.</p>

<p>This runtime facility is not meant to provide ever-changing values that applications have to check multiple times. The values
are seen as changing no more frequently than once per system initialization, such as by a system administrator or operator with an
automatic configuration program. This volume of IEEE&nbsp;Std&nbsp;1003.1-2001 specifies that they shall not change within the
lifetime of the process.</p>

<p>Some values apply to the system overall and others vary at the file system or directory level. The latter are described in <a
href="pathconf.html"><i>pathconf</i>()</a> .</p>

<p>Note that all values returned must be expressible as integers. String values were considered, but the additional flexibility of
this approach was rejected due to its added complexity of implementation and use.</p>

<p>Some values, such as {PATH_MAX}, are sometimes so large that they must not be used to, say, allocate arrays. The
<i>sysconf</i>() function returns a negative value to show that this symbolic constant is not even defined in this case.</p>

<p>Similar to <a href="../functions/pathconf.html"><i>pathconf</i>()</a>, this permits the implementation not to have a limit. When
one resource is infinite, returning an error indicating that some other resource limit has been reached is conforming behavior.</p>
</blockquote>

<h4><a name="tag_03_755_09"></a>FUTURE DIRECTIONS</h4>

<blockquote>
<p>None.</p>
</blockquote>

<h4><a name="tag_03_755_10"></a>SEE ALSO</h4>

<blockquote>
<p><a href="confstr.html"><i>confstr</i>()</a> , <a href="pathconf.html"><i>pathconf</i>()</a> , the Base Definitions volume of
IEEE&nbsp;Std&nbsp;1003.1-2001, <a href="../basedefs/limits.h.html"><i>&lt;limits.h&gt;</i></a>, <a href=
"../basedefs/unistd.h.html"><i>&lt;unistd.h&gt;</i></a>, the Shell and Utilities volume of IEEE&nbsp;Std&nbsp;1003.1-2001, <a href=
"../utilities/getconf.html"><i>getconf</i></a></p>
</blockquote>

<h4><a name="tag_03_755_11"></a>CHANGE HISTORY</h4>

<blockquote>
<p>First released in Issue 3. Included for alignment with the POSIX.1-1988 standard.</p>
</blockquote>

<h4><a name="tag_03_755_12"></a>Issue 5</h4>

<blockquote>
<p>The DESCRIPTION is updated for alignment with the POSIX Realtime Extension and the POSIX Threads Extension.</p>

<p>The _XBS_ variables and name values are added to the table of system variables in the DESCRIPTION. These are all marked EX.</p>
</blockquote>

<h4><a name="tag_03_755_13"></a>Issue 6</h4>

<blockquote>
<p>The symbol CLK_TCK is obsolescent and removed. It is replaced with the phrase &quot;clock ticks per second&quot;.</p>

<p>The symbol {PASS_MAX} is removed.</p>

<p>The following changes were made to align with the IEEE&nbsp;P1003.1a draft standard:</p>

<ul>
<li>
<p>Table entries are added for the following variables: _SC_REGEXP, _SC_SHELL, _SC_REGEX_VERSION, _SC_SYMLOOP_MAX.</p>
</li>
</ul>

<p>The following <i>sysconf</i>() variables and their associated names are added for alignment with
IEEE&nbsp;Std&nbsp;1003.1d-1999:</p>

<blockquote>
<pre>
_POSIX_ADVISORY_INFO
_POSIX_CPUTIME
_POSIX_SPAWN
_POSIX_SPORADIC_SERVER
_POSIX_THREAD_CPUTIME
_POSIX_THREAD_SPORADIC_SERVER
_POSIX_TIMEOUTS
</pre>
</blockquote>

<p>The following changes are made to the DESCRIPTION for alignment with IEEE&nbsp;Std&nbsp;1003.1j-2000:</p>

<ul>
<li>
<p>A statement expressing the dependency of support for some system variables on implementation options is added.</p>
</li>

<li>
<p>The following system variables are added:</p>

<blockquote>
<pre>
_POSIX_BARRIERS
_POSIX_CLOCK_SELECTION
_POSIX_MONOTONIC_CLOCK
_POSIX_READER_WRITER_LOCKS
_POSIX_SPIN_LOCKS
_POSIX_TYPED_MEMORY_OBJECTS
</pre>
</blockquote>
</li>
</ul>

<p>The following system variables are added for alignment with IEEE&nbsp;Std&nbsp;1003.2d-1994:</p>

<blockquote>
<pre>
_POSIX2_PBS
_POSIX2_PBS_ACCOUNTING
_POSIX2_PBS_LOCATE
_POSIX2_PBS_MESSAGE
_POSIX2_PBS_TRACK
</pre>
</blockquote>

<p>The following <i>sysconf</i>() variables and their associated names are added for alignment with
IEEE&nbsp;Std&nbsp;1003.1q-2000:</p>

<blockquote>
<pre>
_POSIX_TRACE
_POSIX_TRACE_EVENT_FILTER
_POSIX_TRACE_INHERIT
_POSIX_TRACE_LOG
</pre>
</blockquote>

<p>The macros associated with the <i>c89</i> programming models are marked LEGACY, and new equivalent macros associated with <a
href="../utilities/c99.html"><i>c99</i></a> are introduced.</p>

<p>IEEE&nbsp;Std 1003.1-2001/Cor&nbsp;1-2002, item XSH/TC1/D6/62 is applied, updating the DESCRIPTION to denote that the _PC* and
_SC* symbols are now required to be supported. A corresponding change has been made in the Base Definitions volume of
IEEE&nbsp;Std&nbsp;1003.1-2001. The deletion in the second paragraph removes some duplicated text. Additional symbols that were
erroneously omitted from this reference been added.</p>

<p>IEEE&nbsp;Std 1003.1-2001/Cor&nbsp;1-2002, item XSH/TC1/D6/63 is applied, making it clear in the RETURN VALUE section that the
value returned for <i>sysconf</i>(_SC_OPEN_MAX) may change if a call to <a href=
"../functions/setrlimit.html"><i>setrlimit</i>()</a> adjusts the RLIMIT_NOFILE soft limit.</p>
</blockquote>

<div class="box"><em>End of informative text.</em></div>

<hr>
<hr size="2" noshade>
<center><font size="2"><!--footer start-->
UNIX &reg; is a registered Trademark of The Open Group.<br>
POSIX &reg; is a registered Trademark of The IEEE.<br>
[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href=
"../utilities/contents.html">XCU</a> | <a href="../functions/contents.html">XSH</a> | <a href="../xrat/contents.html">XRAT</a>
]</font></center>

<!--footer end-->
<hr size="2" noshade>
</body>
</html>