path: root/man3p/sysconf.3p

.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved 
.TH "SYSCONF" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
.\" sysconf 
.SH NAME
sysconf \- get configurable system variables
.SH SYNOPSIS
.LP
\fB#include <unistd.h>
.br
.sp
long sysconf(int\fP \fIname\fP\fB);
.br
\fP
.SH DESCRIPTION
.LP
The \fIsysconf\fP() function provides a method for the application
to determine the current value of a configurable system
limit or option ( \fIvariable\fP). The implementation shall support
all of the variables listed in the following table and may
support others.
.LP
The \fIname\fP argument represents the system variable to be queried.
The following table lists the minimal set of system
variables from \fI<limits.h>\fP or \fI<unistd.h>\fP that can be returned
by \fIsysconf\fP(), and the symbolic constants
defined in \fI<unistd.h>\fP that are the corresponding values used
for
\fIname\fP.
.TS C
center; l1 l.
\fBVariable\fP	\fBValue of Name\fP
{AIO_LISTIO_MAX}	_SC_AIO_LISTIO_MAX
{AIO_MAX}	_SC_AIO_MAX
{AIO_PRIO_DELTA_MAX}	_SC_AIO_PRIO_DELTA_MAX
{ARG_MAX}	_SC_ARG_MAX
{ATEXIT_MAX}	_SC_ATEXIT_MAX
{BC_BASE_MAX}	_SC_BC_BASE_MAX
{BC_DIM_MAX}	_SC_BC_DIM_MAX
{BC_SCALE_MAX}	_SC_BC_SCALE_MAX
{BC_STRING_MAX}	_SC_BC_STRING_MAX
{CHILD_MAX}	_SC_CHILD_MAX
Clock ticks/second	_SC_CLK_TCK
{COLL_WEIGHTS_MAX}	_SC_COLL_WEIGHTS_MAX
{DELAYTIMER_MAX}	_SC_DELAYTIMER_MAX
{EXPR_NEST_MAX}	_SC_EXPR_NEST_MAX
{HOST_NAME_MAX}	_SC_HOST_NAME_MAX
{IOV_MAX}	_SC_IOV_MAX
{LINE_MAX}	_SC_LINE_MAX
{LOGIN_NAME_MAX}	_SC_LOGIN_NAME_MAX
{NGROUPS_MAX}	_SC_NGROUPS_MAX
Maximum size of \fIgetgrgid_r\fP() and	_SC_GETGR_R_SIZE_MAX
\fIgetgrnam_r\fP() data buffers	\ 
Maximum size of \fIgetpwuid_r\fP() and	_SC_GETPW_R_SIZE_MAX
\fIgetpwnam_r\fP() data buffers	\ 
{MQ_OPEN_MAX}	_SC_MQ_OPEN_MAX
{MQ_PRIO_MAX}	_SC_MQ_PRIO_MAX
{OPEN_MAX}	_SC_OPEN_MAX
_POSIX_ADVISORY_INFO	_SC_ADVISORY_INFO
_POSIX_BARRIERS	_SC_BARRIERS
_POSIX_ASYNCHRONOUS_IO	_SC_ASYNCHRONOUS_IO
_POSIX_CLOCK_SELECTION	_SC_CLOCK_SELECTION
_POSIX_CPUTIME	_SC_CPUTIME
_POSIX_FILE_LOCKING	_SC_FILE_LOCKING
_POSIX_FSYNC	_SC_FSYNC
_POSIX_IPV6	_SC_IPV6
_POSIX_JOB_CONTROL	_SC_JOB_CONTROL
_POSIX_MAPPED_FILES	_SC_MAPPED_FILES
_POSIX_MEMLOCK	_SC_MEMLOCK
_POSIX_MEMLOCK_RANGE	_SC_MEMLOCK_RANGE
_POSIX_MEMORY_PROTECTION	_SC_MEMORY_PROTECTION
_POSIX_MESSAGE_PASSING	_SC_MESSAGE_PASSING
_POSIX_MONOTONIC_CLOCK	_SC_MONOTONIC_CLOCK
_POSIX_MULTI_PROCESS	_SC_MULTI_PROCESS
_POSIX_PRIORITIZED_IO	_SC_PRIORITIZED_IO
_POSIX_PRIORITY_SCHEDULING	_SC_PRIORITY_SCHEDULING
_POSIX_RAW_SOCKETS	_SC_RAW_SOCKETS
_POSIX_READER_WRITER_LOCKS	_SC_READER_WRITER_LOCKS
_POSIX_REALTIME_SIGNALS	_SC_REALTIME_SIGNALS
_POSIX_REGEXP	_SC_REGEXP
_POSIX_SAVED_IDS	_SC_SAVED_IDS
_POSIX_SEMAPHORES	_SC_SEMAPHORES
_POSIX_SHARED_MEMORY_OBJECTS	_SC_SHARED_MEMORY_OBJECTS
_POSIX_SHELL	_SC_SHELL
_POSIX_SPAWN	_SC_SPAWN
_POSIX_SPIN_LOCKS	_SC_SPIN_LOCKS
_POSIX_SPORADIC_SERVER	_SC_SPORADIC_SERVER
_POSIX_SYMLOOP_MAX	_SC_SYMLOOP_MAX
_POSIX_SYNCHRONIZED_IO	_SC_SYNCHRONIZED_IO
_POSIX_THREAD_ATTR_STACKADDR	_SC_THREAD_ATTR_STACKADDR
_POSIX_THREAD_ATTR_STACKSIZE	_SC_THREAD_ATTR_STACKSIZE
_POSIX_THREAD_CPUTIME	_SC_THREAD_CPUTIME
_POSIX_THREAD_PRIO_INHERIT	_SC_THREAD_PRIO_INHERIT
_POSIX_THREAD_PRIO_PROTECT	_SC_THREAD_PRIO_PROTECT
_POSIX_THREAD_PRIORITY_SCHEDULING	_SC_THREAD_PRIORITY_SCHEDULING
_POSIX_THREAD_PROCESS_SHARED	_SC_THREAD_PROCESS_SHARED
_POSIX_THREAD_SAFE_FUNCTIONS	_SC_THREAD_SAFE_FUNCTIONS
_POSIX_THREAD_SPORADIC_SERVER	_SC_THREAD_SPORADIC_SERVER
_POSIX_THREADS	_SC_THREADS
_POSIX_TIMEOUTS	_SC_TIMEOUTS
_POSIX_TIMERS	_SC_TIMERS
_POSIX_TRACE	_SC_TRACE
_POSIX_TRACE_EVENT_FILTER	_SC_TRACE_EVENT_FILTER
_POSIX_TRACE_INHERIT	_SC_TRACE_INHERIT
_POSIX_TRACE_LOG	_SC_TRACE_LOG
_POSIX_TYPED_MEMORY_OBJECTS	_SC_TYPED_MEMORY_OBJECTS
_POSIX_VERSION	_SC_VERSION
_POSIX_V6_ILP32_OFF32	_SC_V6_ILP32_OFF32
_POSIX_V6_ILP32_OFFBIG	_SC_V6_ILP32_OFFBIG
_POSIX_V6_LP64_OFF64	_SC_V6_LP64_OFF64
_POSIX_V6_LPBIG_OFFBIG	_SC_V6_LPBIG_OFFBIG
_POSIX2_C_BIND	_SC_2_C_BIND
_POSIX2_C_DEV	_SC_2_C_DEV
_POSIX2_C_VERSION	_SC_2_C_VERSION
_POSIX2_CHAR_TERM	_SC_2_CHAR_TERM
_POSIX2_FORT_DEV	_SC_2_FORT_DEV
_POSIX2_FORT_RUN	_SC_2_FORT_RUN
_POSIX2_LOCALEDEF	_SC_2_LOCALEDEF
_POSIX2_PBS	_SC_2_PBS
_POSIX2_PBS_ACCOUNTING	_SC_2_PBS_ACCOUNTING
_POSIX2_PBS_CHECKPOINT	_SC_2_PBS_CHECKPOINT
_POSIX2_PBS_LOCATE	_SC_2_PBS_LOCATE
_POSIX2_PBS_MESSAGE	_SC_2_PBS_MESSAGE
_POSIX2_PBS_TRACK	_SC_2_PBS_TRACK
_POSIX2_SW_DEV	_SC_2_SW_DEV
_POSIX2_UPE	_SC_2_UPE
_POSIX2_VERSION	_SC_2_VERSION
_REGEX_VERSION	_SC_REGEX_VERSION
{PAGE_SIZE}	_SC_PAGE_SIZE
{PAGESIZE}	_SC_PAGESIZE
{PTHREAD_DESTRUCTOR_ITERATIONS}	_SC_THREAD_DESTRUCTOR_ITERATIONS
{PTHREAD_KEYS_MAX}	_SC_THREAD_KEYS_MAX
{PTHREAD_STACK_MIN}	_SC_THREAD_STACK_MIN
{PTHREAD_THREADS_MAX}	_SC_THREAD_THREADS_MAX
{RE_DUP_MAX}	_SC_RE_DUP_MAX
{RTSIG_MAX}	_SC_RTSIG_MAX
{SEM_NSEMS_MAX}	_SC_SEM_NSEMS_MAX
{SEM_VALUE_MAX}	_SC_SEM_VALUE_MAX
{SIGQUEUE_MAX}	_SC_SIGQUEUE_MAX
{STREAM_MAX}	_SC_STREAM_MAX
{SYMLOOP_MAX}	_SC_SYMLOOP_MAX
{TIMER_MAX}	_SC_TIMER_MAX
{TTY_NAME_MAX}	_SC_TTY_NAME_MAX
{TZNAME_MAX}	_SC_TZNAME_MAX
_XBS5_ILP32_OFF32 (\fBLEGACY\fP)	_SC_XBS5_ILP32_OFF32 (\fBLEGACY\fP)
_XBS5_ILP32_OFFBIG (\fBLEGACY\fP)	_SC_XBS5_ILP32_OFFBIG (\fBLEGACY\fP)
_XBS5_LP64_OFF64 (\fBLEGACY\fP)	_SC_XBS5_LP64_OFF64 (\fBLEGACY\fP)
_XBS5_LPBIG_OFFBIG (\fBLEGACY\fP)	_SC_XBS5_LPBIG_OFFBIG (\fBLEGACY\fP)
_XOPEN_CRYPT	_SC_XOPEN_CRYPT
_XOPEN_ENH_I18N	_SC_XOPEN_ENH_I18N
_XOPEN_LEGACY	_SC_XOPEN_LEGACY
_XOPEN_REALTIME	_SC_XOPEN_REALTIME
_XOPEN_REALTIME_THREADS	_SC_XOPEN_REALTIME_THREADS
_XOPEN_SHM	_SC_XOPEN_SHM
_XOPEN_STREAMS	_SC_XOPEN_STREAMS
_XOPEN_UNIX	_SC_XOPEN_UNIX
_XOPEN_VERSION	_SC_XOPEN_VERSION
_XOPEN_XCU_VERSION	_SC_XOPEN_XCU_VERSION
.TE
.SH RETURN VALUE
.LP
If \fIname\fP is an invalid value, \fIsysconf\fP() shall return -1
and set \fIerrno\fP to indicate the error. If the variable
corresponding to \fIname\fP has no limit, \fIsysconf\fP() shall return
-1 without changing the value of \fIerrno\fP. Note that
indefinite limits do not imply infinite limits; see \fI<limits.h>\fP.
.LP
Otherwise, \fIsysconf\fP() 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 \fI<limits.h>\fP or
\fI<unistd.h>\fP. The
value shall not change during the lifetime of the calling process,
\ except that \fIsysconf\fP(_SC_OPEN_MAX) may return different
values before and after a call to \fIsetrlimit\fP() which changes
the RLIMIT_NOFILE soft
limit. 
.SH ERRORS
.LP
The \fIsysconf\fP() function shall fail if:
.TP 7
.B EINVAL
The value of the \fIname\fP argument is invalid.
.sp
.LP
\fIThe following sections are informative.\fP
.SH EXAMPLES
.LP
None.
.SH APPLICATION USAGE
.LP
As -1 is a permissible return value in a successful situation, an
application wishing to check for error situations should set
\fIerrno\fP to 0, then call \fIsysconf\fP(), and, if it returns -1,
check to see if \fIerrno\fP is non-zero.
.LP
If the value of \fIsysconf\fP(_SC_2_VERSION) is not equal to the value
of the _POSIX2_VERSION symbolic constant, the utilities
available via \fIsystem\fP() or \fIpopen\fP() might
not behave as described in the Shell and Utilities volume of IEEE\ Std\ 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\ Std\ 1003.1-2001. Some
applications might be able to deal with this, others might not. However,
the functions defined in this volume of
IEEE\ Std\ 1003.1-2001 continue to operate as specified, even if \fIsysconf\fP(_SC_2_VERSION)
reports that the utilities
no longer perform as specified.
.SH RATIONALE
.LP
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 \fIpathconf\fP()
and \fIfpathconf\fP().
.LP
Although a conforming application can run on all systems by never
demanding more resources than the minimum values published in
this volume of IEEE\ Std\ 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
\fI<limits.h>\fP or \fI<unistd.h>\fP.
.LP
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.
.LP
Two examples are offered:
.IP " 1." 4
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 \fI<unistd.h>\fP value published
in this volume of
IEEE\ Std\ 1003.1-2001.
.LP
.IP " 2." 4
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.
.LP
.LP
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.
.LP
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.
.LP
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\ Std\ 1003.1-2001
specifies that they shall not change within the
lifetime of the process.
.LP
Some values apply to the system overall and others vary at the file
system or directory level. The latter are described in \fIpathconf\fP()
\&.
.LP
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.
.LP
Some values, such as {PATH_MAX}, are sometimes so large that they
must not be used to, say, allocate arrays. The
\fIsysconf\fP() function returns a negative value to show that this
symbolic constant is not even defined in this case.
.LP
Similar to \fIpathconf\fP(), 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.
.SH FUTURE DIRECTIONS
.LP
None.
.SH SEE ALSO
.LP
\fIconfstr\fP() , \fIpathconf\fP() , the Base Definitions volume of
IEEE\ Std\ 1003.1-2001, \fI<limits.h>\fP, \fI<unistd.h>\fP, the Shell
and Utilities volume of IEEE\ Std\ 1003.1-2001, \fIgetconf\fP
.SH COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
Electrical and Electronics Engineers, Inc and The Open Group. In the
event of any discrepancy between this version 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 .