sysconf (3p) - Linux Manuals

sysconf: get configurable system variables

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.

NAME

sysconf - get configurable system variables

SYNOPSIS

#include <unistd.h>

long sysconf(int name);

DESCRIPTION

The sysconf() function provides a method for the application to determine the current value of a configurable system limit or option ( variable). The implementation shall support all of the variables listed in the following table and may support others.

The name argument represents the system variable to be queried. The following table lists the minimal set of system variables from <limits.h> or <unistd.h> that can be returned by sysconf(), and the symbolic constants defined in <unistd.h> that are the corresponding values used for name.

VariableValue 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     
Maximum size of getgrgid_r() and_SC_GETGR_R_SIZE_MAX     
getgrnam_r() data buffers      
Maximum size of getpwuid_r() and_SC_GETPW_R_SIZE_MAX     
getpwnam_r() 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 (LEGACY)_SC_XBS5_ILP32_OFF32 (LEGACY    
_XBS5_ILP32_OFFBIG (LEGACY)_SC_XBS5_ILP32_OFFBIG (LEGACY    
_XBS5_LP64_OFF64 (LEGACY)_SC_XBS5_LP64_OFF64 (LEGACY    
_XBS5_LPBIG_OFFBIG (LEGACY)_SC_XBS5_LPBIG_OFFBIG (LEGACY    
_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     

RETURN VALUE

If name is an invalid value, sysconf() shall return -1 and set errno to indicate the error. If the variable corresponding to name has no limit, sysconf() shall return -1 without changing the value of errno. Note that indefinite limits do not imply infinite limits; see <limits.h>.

Otherwise, sysconf() 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 <limits.h> or <unistd.h>. The value shall not change during the lifetime of the calling process,  except that sysconf(_SC_OPEN_MAX) may return different values before and after a call to setrlimit() which changes the RLIMIT_NOFILE soft limit.

ERRORS

The sysconf() function shall fail if:

EINVAL
The value of the name argument is invalid.

The following sections are informative.

EXAMPLES

None.

APPLICATION USAGE

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

If the value of sysconf(_SC_2_VERSION) is not equal to the value of the _POSIX2_VERSION symbolic constant, the utilities available via system() or popen() 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 sysconf(_SC_2_VERSION) reports that the utilities no longer perform as specified.

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 pathconf() and fpathconf().

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 <limits.h> or <unistd.h>.

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.

Two examples are offered:

1.
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 <unistd.h> value published in this volume of IEEE Std 1003.1-2001.

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

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.

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.

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.

Some values apply to the system overall and others vary at the file system or directory level. The latter are described in pathconf() .

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.

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

Similar to pathconf(), 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.

FUTURE DIRECTIONS

None.

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 .

SEE ALSO

confstr(), pathconf(), the Base Definitions volume of IEEE Std 1003.1-2001, <limits.h>, <unistd.h>, the Shell and Utilities volume of IEEE Std 1003.1-2001, getconf