mirror of https://github.com/mkerrisk/man-pages
309 lines
12 KiB
Plaintext
309 lines
12 KiB
Plaintext
|
.\" 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 .
|