diff options
Diffstat (limited to 'man3p/sysconf.3p')
| -rw-r--r-- | man3p/sysconf.3p | 308 |
1 files changed, 308 insertions, 0 deletions
diff --git a/man3p/sysconf.3p b/man3p/sysconf.3p new file mode 100644 index 000000000..a75cb6c8e --- /dev/null +++ b/man3p/sysconf.3p @@ -0,0 +1,308 @@ +.\" 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 . |