man3/sysconf.3

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