man3/sysconf.3

   1 '\" t
   2 .\" Copyright (c) 1993 by Thomas Koenig (ig25@rz.uni-karlsruhe.de)
   3 .\"
   4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   5 .\"
   6 .\" Modified Sat Jul 24 17:51:42 1993 by Rik Faith (faith@cs.unc.edu)
   7 .\" Modified Tue Aug 17 11:42:20 1999 by Ariel Scolnicov (ariels@compugen.co.il)
   8 .TH sysconf 3 (date) "Linux man-pages (unreleased)"
   9 .SH NAME
  10 sysconf \- get configuration information at run time
  11 .SH LIBRARY
  12 Standard C library
  13 .RI ( libc ", " \-lc )
  14 .SH SYNOPSIS
  15 .nf
  16 .B #include <unistd.h>
  17 .PP
  18 .BI "long sysconf(int " "name" );
  19 .fi
  20 .SH DESCRIPTION
  21 POSIX allows an application to test at compile or run time
  22 whether certain options are supported, or what the value is
  23 of certain configurable constants or limits.
  24 .PP
  25 At compile time this is done by including
  26 .I <unistd.h>
  27 and/or
  28 .I <limits.h>
  29 and testing the value of certain macros.
  30 .PP
  31 At run time, one can ask for numerical values using the present function
  32 .BR sysconf ().
  33 One can ask for numerical values that may depend
  34 on the filesystem in which a file resides using
  35 .BR fpathconf (3)
  36 and
  37 .BR pathconf (3).
  38 One can ask for string values using
  39 .BR confstr (3).
  40 .PP
  41 The values obtained from these functions are system configuration constants.
  42 They do not change during the lifetime of a process.
  43 .\" except that sysconf(_SC_OPEN_MAX) may change answer after a call
  44 .\" to setrlimit( ) which changes the RLIMIT_NOFILE soft limit
  45 .PP
  46 For options, typically, there is a constant
  47 .B _POSIX_FOO
  48 that may be defined in
  49 .IR <unistd.h> .
  50 If it is undefined, one should ask at run time.
  51 If it is defined to \-1, then the option is not supported.
  52 If it is defined to 0, then relevant functions and headers exist,
  53 but one has to ask at run time what degree of support is available.
  54 If it is defined to a value other than \-1 or 0, then the option is
  55 supported.
  56 Usually the value (such as 200112L) indicates the year and month
  57 of the POSIX revision describing the option.
  58 glibc uses the value 1
  59 to indicate support as long as the POSIX revision has not been published yet.
  60 .\" and 999 to indicate support for options no longer present in the latest
  61 .\" standard. (?)
  62 The
  63 .BR sysconf ()
  64 argument will be
  65 .BR _SC_FOO .
  66 For a list of options, see
  67 .BR posixoptions (7).
  68 .PP
  69 For variables or limits, typically, there is a constant
  70 .BR _FOO ,
  71 maybe defined in
  72 .IR <limits.h> ,
  73 or
  74 .BR _POSIX_FOO ,
  75 maybe defined in
  76 .IR <unistd.h> .
  77 The constant will not be defined if the limit is unspecified.
  78 If the constant is defined, it gives a guaranteed value, and
  79 a greater value might actually be supported.
  80 If an application wants to take advantage of values which may change
  81 between systems, a call to
  82 .BR sysconf ()
  83 can be made.
  84 The
  85 .BR sysconf ()
  86 argument will be
  87 .BR _SC_FOO .
  88 .SS POSIX.1 variables
  89 We give the name of the variable, the name of the
  90 .BR sysconf ()
  91 argument used to inquire about its value,
  92 and a short description.
  93 .PP
  94 First, the POSIX.1 compatible values.
  95 .\" [for the moment: only the things that are unconditionally present]
  96 .\" .TP
  97 .\" .BR AIO_LISTIO_MAX " - " _SC_AIO_LISTIO_MAX
  98 .\" (if _POSIX_ASYNCHRONOUS_IO)
  99 .\" Maximum number of I/O operations in a single list I/O call.
 100 .\" Must not be less than _POSIX_AIO_LISTIO_MAX.
 101 .\" .TP
 102 .\" .BR AIO_MAX " - " _SC_AIO_MAX
 103 .\" (if _POSIX_ASYNCHRONOUS_IO)
 104 .\" Maximum number of outstanding asynchronous I/O operations.
 105 .\" Must not be less than _POSIX_AIO_MAX.
 106 .\" .TP
 107 .\" .BR AIO_PRIO_DELTA_MAX " - " _SC_AIO_PRIO_DELTA_MAX
 108 .\" (if _POSIX_ASYNCHRONOUS_IO)
 109 .\" The maximum amount by which a process can decrease its
 110 .\" asynchronous I/O priority level from its own scheduling priority.
 111 .\" Must be nonnegative.
 112 .TP
 113 .BR ARG_MAX " - " _SC_ARG_MAX
 114 The maximum length of the arguments to the
 115 .BR exec (3)
 116 family of functions.
 117 Must not be less than
 118 .B _POSIX_ARG_MAX
 119 (4096).
 120 .TP
 121 .BR CHILD_MAX " - " _SC_CHILD_MAX
 122 The maximum number of simultaneous processes per user ID.
 123 Must not be less than
 124 .B _POSIX_CHILD_MAX
 125 (25).
 126 .TP
 127 .BR HOST_NAME_MAX " - " _SC_HOST_NAME_MAX
 128 Maximum length of a hostname, not including the terminating null byte,
 129 as returned by
 130 .BR gethostname (2).
 131 Must not be less than
 132 .B _POSIX_HOST_NAME_MAX
 133 (255).
 134 .TP
 135 .BR LOGIN_NAME_MAX " - " _SC_LOGIN_NAME_MAX
 136 Maximum length of a login name, including the terminating null byte.
 137 Must not be less than
 138 .B _POSIX_LOGIN_NAME_MAX
 139 (9).
 140 .TP
 141 .BR NGROUPS_MAX " - " _SC_NGROUPS_MAX
 142 Maximum number of supplementary group IDs.
 143 .TP
 144 .BR "" "clock ticks - " _SC_CLK_TCK
 145 The number of clock ticks per second.
 146 The corresponding variable is obsolete.
 147 It was of course called
 148 .BR CLK_TCK .
 149 (Note: the macro
 150 .B CLOCKS_PER_SEC
 151 does not give information: it must equal 1000000.)
 152 .TP
 153 .BR OPEN_MAX " - " _SC_OPEN_MAX
 154 The maximum number of files that a process can have open at any time.
 155 Must not be less than
 156 .B _POSIX_OPEN_MAX
 157 (20).
 158 .TP
 159 .BR PAGESIZE " - " _SC_PAGESIZE
 160 Size of a page in bytes.
 161 Must not be less than 1.
 162 .TP
 163 .BR PAGE_SIZE " - " _SC_PAGE_SIZE
 164 A synonym for
 165 .BR PAGESIZE / _SC_PAGESIZE .
 166 (Both
 167 .B PAGESIZE
 168 and
 169 .B PAGE_SIZE
 170 are specified in POSIX.)
 171 .TP
 172 .BR RE_DUP_MAX " - " _SC_RE_DUP_MAX
 173 The number of repeated occurrences of a BRE permitted by
 174 .BR regexec (3)
 175 and
 176 .BR regcomp (3).
 177 Must not be less than
 178 .B _POSIX2_RE_DUP_MAX
 179 (255).
 180 .TP
 181 .BR STREAM_MAX " - " _SC_STREAM_MAX
 182 The maximum number of streams that a process can have open at any
 183 time.
 184 If defined, it has the same value as the standard C macro
 185 .BR FOPEN_MAX .
 186 Must not be less than
 187 .B _POSIX_STREAM_MAX
 188 (8).
 189 .TP
 190 .BR SYMLOOP_MAX " - " _SC_SYMLOOP_MAX
 191 The maximum number of symbolic links seen in a pathname before resolution
 192 returns
 193 .BR ELOOP .
 194 Must not be less than
 195 .B _POSIX_SYMLOOP_MAX
 196 (8).
 197 .TP
 198 .BR TTY_NAME_MAX " - " _SC_TTY_NAME_MAX
 199 The maximum length of terminal device name,
 200 including the terminating null byte.
 201 Must not be less than
 202 .B _POSIX_TTY_NAME_MAX
 203 (9).
 204 .TP
 205 .BR TZNAME_MAX " - " _SC_TZNAME_MAX
 206 The maximum number of bytes in a timezone name.
 207 Must not be less than
 208 .B _POSIX_TZNAME_MAX
 209 (6).
 210 .TP
 211 .BR _POSIX_VERSION " - " _SC_VERSION
 212 indicates the year and month the POSIX.1 standard was approved in the
 213 format
 214 .BR YYYYMML ;
 215 the value
 216 .B 199009L
 217 indicates the Sept. 1990 revision.
 218 .SS POSIX.2 variables
 219 Next, the POSIX.2 values, giving limits for utilities.
 220 .TP
 221 .BR BC_BASE_MAX " - " _SC_BC_BASE_MAX
 222 indicates the maximum
 223 .I obase
 224 value accepted by the
 225 .BR bc (1)
 226 utility.
 227 .TP
 228 .BR BC_DIM_MAX " - " _SC_BC_DIM_MAX
 229 indicates the maximum value of elements permitted in an array by
 230 .BR bc (1).
 231 .TP
 232 .BR BC_SCALE_MAX " - " _SC_BC_SCALE_MAX
 233 indicates the maximum
 234 .I scale
 235 value allowed by
 236 .BR bc (1).
 237 .TP
 238 .BR BC_STRING_MAX " - " _SC_BC_STRING_MAX
 239 indicates the maximum length of a string accepted by
 240 .BR bc (1).
 241 .TP
 242 .BR COLL_WEIGHTS_MAX " - " _SC_COLL_WEIGHTS_MAX
 243 indicates the maximum numbers of weights that can be assigned to an
 244 entry of the
 245 .B LC_COLLATE order
 246 keyword in the locale definition file.
 247 .TP
 248 .BR EXPR_NEST_MAX " - " _SC_EXPR_NEST_MAX
 249 is the maximum number of expressions which can be nested within
 250 parentheses by
 251 .BR expr (1).
 252 .TP
 253 .BR LINE_MAX " - " _SC_LINE_MAX
 254 The maximum length of a utility's input line, either from
 255 standard input or from a file.
 256 This includes space for a trailing
 257 newline.
 258 .TP
 259 .BR RE_DUP_MAX " - " _SC_RE_DUP_MAX
 260 The maximum number of repeated occurrences of a regular expression when
 261 the interval notation
 262 .B \e{m,n\e}
 263 is used.
 264 .TP
 265 .BR POSIX2_VERSION " - " _SC_2_VERSION
 266 indicates the version of the POSIX.2 standard in the format of
 267 YYYYMML.
 268 .TP
 269 .BR POSIX2_C_DEV " - " _SC_2_C_DEV
 270 indicates whether the POSIX.2 C language development facilities are
 271 supported.
 272 .TP
 273 .BR POSIX2_FORT_DEV " - " _SC_2_FORT_DEV
 274 indicates whether the POSIX.2 FORTRAN development utilities are
 275 supported.
 276 .TP
 277 .BR POSIX2_FORT_RUN " - " _SC_2_FORT_RUN
 278 indicates whether the POSIX.2 FORTRAN run-time utilities are supported.
 279 .TP
 280 .BR _POSIX2_LOCALEDEF " - " _SC_2_LOCALEDEF
 281 indicates whether the POSIX.2 creation of locales via
 282 .BR localedef (1)
 283 is supported.
 284 .TP
 285 .BR POSIX2_SW_DEV " - " _SC_2_SW_DEV
 286 indicates whether the POSIX.2 software development utilities option is
 287 supported.
 288 .PP
 289 These values also exist, but may not be standard.
 290 .TP
 291 .BR "" " - " _SC_PHYS_PAGES
 292 The number of pages of physical memory.
 293 Note that it is possible
 294 for the product of this value and the value of
 295 .B _SC_PAGESIZE
 296 to overflow.
 297 .TP
 298 .BR "" " - " _SC_AVPHYS_PAGES
 299 The number of currently available pages of physical memory.
 300 .TP
 301 .BR "" " - " _SC_NPROCESSORS_CONF
 302 The number of processors configured.
 303 See also
 304 .BR get_nprocs_conf (3).
 305 .TP
 306 .BR "" " - " _SC_NPROCESSORS_ONLN
 307 The number of processors currently online (available).
 308 See also
 309 .BR get_nprocs_conf (3).
 310 .SH RETURN VALUE
 311 The return value of
 312 .BR sysconf ()
 313 is one of the following:
 314 .IP \[bu] 3
 315 On error, \-1 is returned and
 316 .I errno
 317 is set to indicate the error
 318 (for example,
 319 .BR EINVAL ,
 320 indicating that
 321 .I name
 322 is invalid).
 323 .IP \[bu]
 324 If
 325 .I name
 326 corresponds to a maximum or minimum limit, and that limit is indeterminate,
 327 \-1 is returned and
 328 .I errno
 329 is not changed.
 330 (To distinguish an indeterminate limit from an error, set
 331 .I errno
 332 to zero before the call, and then check whether
 333 .I errno
 334 is nonzero when \-1 is returned.)
 335 .IP \[bu]
 336 If
 337 .I name
 338 corresponds to an option,
 339 a positive value is returned if the option is supported,
 340 and \-1 is returned if the option is not supported.
 341 .IP \[bu]
 342 Otherwise,
 343 the current value of the option or limit is returned.
 344 This value will not be more restrictive than
 345 the corresponding value that was described to the application in
 346 .I <unistd.h>
 347 or
 348 .I <limits.h>
 349 when the application was compiled.
 350 .SH ERRORS
 351 .TP
 352 .B EINVAL
 353 .I name
 354 is invalid.
 355 .SH ATTRIBUTES
 356 For an explanation of the terms used in this section, see
 357 .BR attributes (7).
 358 .TS
 359 allbox;
 360 lbx lb lb
 361 l l l.
 362 Interface       Attribute       Value
 363 T{
 364 .na
 365 .nh
 366 .BR sysconf ()
 367 T}      Thread safety   MT-Safe env
 368 .TE
 369 .SH STANDARDS
 370 POSIX.1-2008.
 371 .SH HISTORY
 372 POSIX.1-2001.
 373 .SH BUGS
 374 It is difficult to use
 375 .B ARG_MAX
 376 because it is not specified how much of the argument space for
 377 .BR exec (3)
 378 is consumed by the user's environment variables.
 379 .PP
 380 Some returned values may be huge; they are not suitable for allocating
 381 memory.
 382 .SH SEE ALSO
 383 .BR bc (1),
 384 .BR expr (1),
 385 .BR getconf (1),
 386 .BR locale (1),
 387 .BR confstr (3),
 388 .BR fpathconf (3),
 389 .BR pathconf (3),
 390 .BR posixoptions (7)