'\" et

.TH SYSCONF "3P" 2013 "IEEE/The Open Group" "POSIX Programmer's Manual"

.SH PROLOG

This manual page is part of the POSIX Programmer's Manual.

The Linux implementation of this interface may differ (consult

the corresponding Linux manual page for details of Linux behavior),

or the interface may not be implemented on Linux.

.SH NAME

sysconf

\(em get configurable system variables

.SH SYNOPSIS

.LP

.nf

#include <unistd.h>

.P

long sysconf(int \fIname\fP);

.fi

.SH DESCRIPTION

The

\fIsysconf\fR()

function provides a method for the application to determine the current

value of a configurable system limit or option (\c

.IR variable ).

The implementation shall support all of the variables listed in the

following table and may support others.

.P

The

.IR name

argument represents the system variable to be queried. The following

table lists the minimal set of system variables from

.IR <limits.h> 

or

.IR <unistd.h> 

that can be returned by

\fIsysconf\fR(),

and the symbolic constants defined in

.IR <unistd.h> 

that are the corresponding values used for

.IR name .

.ad l

.TS

box center tab(@);

cB | cB

lw(2.7i)1e | le.

Variable@Value of Name

_

{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

Initial size of \fIgetgrgid_r\fP\^(\|) and@_SC_GETGR_R_SIZE_MAX

\fIgetgrnam_r\fP\^(\|) data buffers

Initial 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_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_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_SS_REPL_MAX@_SC_SS_REPL_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_ROBUST_PRIO_INHERIT@_SC_THREAD_ROBUST_PRIO_INHERIT

_POSIX_THREAD_ROBUST_PRIO_PROTECT@_SC_THREAD_ROBUST_PRIO_PROTECT

_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_EVENT_NAME_MAX@_SC_TRACE_EVENT_NAME_MAX

_POSIX_TRACE_INHERIT@_SC_TRACE_INHERIT

_POSIX_TRACE_LOG@_SC_TRACE_LOG

_POSIX_TRACE_NAME_MAX@_SC_TRACE_NAME_MAX

_POSIX_TRACE_SYS_MAX@_SC_TRACE_SYS_MAX

_POSIX_TRACE_USER_EVENT_MAX@_SC_TRACE_USER_EVENT_MAX

_POSIX_TYPED_MEMORY_OBJECTS@_SC_TYPED_MEMORY_OBJECTS

_POSIX_VERSION@_SC_VERSION

_POSIX_V7_ILP32_OFF32@_SC_V7_ILP32_OFF32

_POSIX_V7_ILP32_OFFBIG@_SC_V7_ILP32_OFFBIG

_POSIX_V7_LP64_OFF64@_SC_V7_LP64_OFF64

_POSIX_V7_LPBIG_OFFBIG@_SC_V7_LPBIG_OFFBIG

.TE

.ad l

.TS

box center tab(@);

cB | cB

lw(2.6i)1e | le.

Variable@Value of Name

_

_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_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

{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

_XOPEN_CRYPT@_SC_XOPEN_CRYPT

_XOPEN_ENH_I18N@_SC_XOPEN_ENH_I18N

_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_UUCP@_SC_XOPEN_UUCP

_XOPEN_VERSION@_SC_XOPEN_VERSION

.TE

.ad b

.SH "RETURN VALUE"

If

.IR name

is an invalid value,

\fIsysconf\fR()

shall return \(mi1 and set

.IR errno

to indicate the error. If the variable corresponding to

.IR name

is described in

.IR <limits.h> 

as a maximum or minimum value and the variable has no limit,

\fIsysconf\fR()

shall return \(mi1 without changing the value of

.IR errno .

Note that indefinite limits do not imply infinite limits; see

.IR <limits.h> .

.P

Otherwise,

\fIsysconf\fR()

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

.IR <limits.h> 

or

.IR <unistd.h> .

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\fR()

which changes the RLIMIT_NOFILE soft limit.

.P

If the variable corresponding to

.IR name

is dependent on an unsupported option, the results are unspecified.

.SH ERRORS

The

\fIsysconf\fR()

function shall fail if:

.TP

.BR EINVAL

The value of the

.IR name

argument is invalid.

.LP

.IR "The following sections are informative."

.SH EXAMPLES

None.

.SH "APPLICATION USAGE"

As \(mi1 is a permissible return value in a successful situation, an

application wishing to check for error situations should set

.IR errno

to 0, then call

\fIsysconf\fR(),

and, if it returns \(mi1, check to see if

.IR errno

is non-zero.

.P

Application developers should check whether an option, such as

_POSIX_TRACE, is supported prior to obtaining and using values for

related variables, such as _POSIX_TRACE_NAME_MAX.

.SH RATIONALE

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\fR()

and

\fIfpathconf\fR().

.P

Although a conforming application can run on all systems by never

demanding more resources than the minimum values published in this volume of POSIX.1\(hy2008, 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

.IR <limits.h> 

or

.IR <unistd.h> .

.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

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

.IR <unistd.h> 

value published in this volume of POSIX.1\(hy2008.

.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.

.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

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 developer.

.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 POSIX.1\(hy2008 specifies that they shall not change

within the lifetime of the process.

.P

Some values apply to the system overall and others vary at the file

system or directory level. The latter are described in

.IR "\fIfpathconf\fR\^(\|)".

.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

Some values, such as

{PATH_MAX},

are sometimes so large that they must not be used to, say, allocate

arrays. The

\fIsysconf\fR()

function returns a negative value to show that this symbolic constant

is not even defined in this case.

.P

Similar to

\fIpathconf\fR(),

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"

None.

.SH "SEE ALSO"

.IR "\fIconfstr\fR\^(\|)",

.IR "\fIfpathconf\fR\^(\|)"

.P

The Base Definitions volume of POSIX.1\(hy2008,

.IR "\fB<limits.h>\fP",

.IR "\fB<unistd.h>\fP"

.P

The Shell and Utilities volume of POSIX.1\(hy2008,

.IR "\fIgetconf\fR\^"

.SH COPYRIGHT

Portions of this text are reprinted and reproduced in electronic form

from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology

-- Portable Operating System Interface (POSIX), The Open Group Base

Specifications Issue 7, Copyright (C) 2013 by the Institute of

Electrical and Electronics Engineers, Inc and The Open Group.

(This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) 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.unix.org/online.html .

Any typographical or formatting errors that appear

in this page are most likely

to have been introduced during the conversion of the source files to

man page format. To report such errors, see

https://www.kernel.org/doc/man-pages/reporting_bugs.html .