Fix off-by-one in nscd getservbyport call
[glibc.git] / manual / conf.texi
blobc720063b8352aa6d1887116deb79c0ba1f2c5f1f
1 @node System Configuration, Cryptographic Functions, System Management, Top
2 @c %MENU% Parameters describing operating system limits
3 @chapter System Configuration Parameters
5 The functions and macros listed in this chapter give information about
6 configuration parameters of the operating system---for example, capacity
7 limits, presence of optional POSIX features, and the default path for
8 executable files (@pxref{String Parameters}).
10 @menu
11 * General Limits::           Constants and functions that describe
12                                 various process-related limits that have
13                                 one uniform value for any given machine.
14 * System Options::           Optional POSIX features.
15 * Version Supported::        Version numbers of POSIX.1 and POSIX.2.
16 * Sysconf::                  Getting specific configuration values
17                                 of general limits and system options.
18 * Minimums::                 Minimum values for general limits.
20 * Limits for Files::         Size limitations that pertain to individual files.
21                                 These can vary between file systems
22                                 or even from file to file.
23 * Options for Files::        Optional features that some files may support.
24 * File Minimums::            Minimum values for file limits.
25 * Pathconf::                 Getting the limit values for a particular file.
27 * Utility Limits::           Capacity limits of some POSIX.2 utility programs.
28 * Utility Minimums::         Minimum allowable values of those limits.
30 * String Parameters::        Getting the default search path.
31 @end menu
33 @node General Limits
34 @section General Capacity Limits
35 @cindex POSIX capacity limits
36 @cindex limits, POSIX
37 @cindex capacity limits, POSIX
39 The POSIX.1 and POSIX.2 standards specify a number of parameters that
40 describe capacity limitations of the system.  These limits can be fixed
41 constants for a given operating system, or they can vary from machine to
42 machine.  For example, some limit values may be configurable by the
43 system administrator, either at run time or by rebuilding the kernel,
44 and this should not require recompiling application programs.
46 @pindex limits.h
47 Each of the following limit parameters has a macro that is defined in
48 @file{limits.h} only if the system has a fixed, uniform limit for the
49 parameter in question.  If the system allows different file systems or
50 files to have different limits, then the macro is undefined; use
51 @code{sysconf} to find out the limit that applies at a particular time
52 on a particular machine.  @xref{Sysconf}.
54 Each of these parameters also has another macro, with a name starting
55 with @samp{_POSIX}, which gives the lowest value that the limit is
56 allowed to have on @emph{any} POSIX system.  @xref{Minimums}.
58 @cindex limits, program argument size
59 @comment limits.h
60 @comment POSIX.1
61 @deftypevr Macro int ARG_MAX
62 If defined, the unvarying maximum combined length of the @var{argv} and
63 @var{environ} arguments that can be passed to the @code{exec} functions.
64 @end deftypevr
66 @cindex limits, number of processes
67 @comment limits.h
68 @comment POSIX.1
69 @deftypevr Macro int CHILD_MAX
70 If defined, the unvarying maximum number of processes that can exist
71 with the same real user ID at any one time.  In BSD and GNU, this is
72 controlled by the @code{RLIMIT_NPROC} resource limit; @pxref{Limits on
73 Resources}.
74 @end deftypevr
76 @cindex limits, number of open files
77 @comment limits.h
78 @comment POSIX.1
79 @deftypevr Macro int OPEN_MAX
80 If defined, the unvarying maximum number of files that a single process
81 can have open simultaneously.  In BSD and GNU, this is controlled
82 by the @code{RLIMIT_NOFILE} resource limit; @pxref{Limits on Resources}.
83 @end deftypevr
85 @comment limits.h
86 @comment POSIX.1
87 @deftypevr Macro int STREAM_MAX
88 If defined, the unvarying maximum number of streams that a single
89 process can have open simultaneously.  @xref{Opening Streams}.
90 @end deftypevr
92 @cindex limits, time zone name length
93 @comment limits.h
94 @comment POSIX.1
95 @deftypevr Macro int TZNAME_MAX
96 If defined, the unvarying maximum length of a time zone name.
97 @xref{Time Zone Functions}.
98 @end deftypevr
100 These limit macros are always defined in @file{limits.h}.
102 @cindex limits, number of supplementary group IDs
103 @comment limits.h
104 @comment POSIX.1
105 @deftypevr Macro int NGROUPS_MAX
106 The maximum number of supplementary group IDs that one process can have.
108 The value of this macro is actually a lower bound for the maximum.  That
109 is, you can count on being able to have that many supplementary group
110 IDs, but a particular machine might let you have even more.  You can use
111 @code{sysconf} to see whether a particular machine will let you have
112 more (@pxref{Sysconf}).
113 @end deftypevr
115 @comment limits.h
116 @comment POSIX.1
117 @deftypevr Macro ssize_t SSIZE_MAX
118 The largest value that can fit in an object of type @code{ssize_t}.
119 Effectively, this is the limit on the number of bytes that can be read
120 or written in a single operation.
122 This macro is defined in all POSIX systems because this limit is never
123 configurable.
124 @end deftypevr
126 @comment limits.h
127 @comment POSIX.2
128 @deftypevr Macro int RE_DUP_MAX
129 The largest number of repetitions you are guaranteed is allowed in the
130 construct @samp{\@{@var{min},@var{max}\@}} in a regular expression.
132 The value of this macro is actually a lower bound for the maximum.  That
133 is, you can count on being able to have that many repetitions, but a
134 particular machine might let you have even more.  You can use
135 @code{sysconf} to see whether a particular machine will let you have
136 more (@pxref{Sysconf}).  And even the value that @code{sysconf} tells
137 you is just a lower bound---larger values might work.
139 This macro is defined in all POSIX.2 systems, because POSIX.2 says it
140 should always be defined even if there is no specific imposed limit.
141 @end deftypevr
143 @node System Options
144 @section Overall System Options
145 @cindex POSIX optional features
146 @cindex optional POSIX features
148 POSIX defines certain system-specific options that not all POSIX systems
149 support.  Since these options are provided in the kernel, not in the
150 library, simply using @theglibc{} does not guarantee any of these
151 features is supported; it depends on the system you are using.
153 @pindex unistd.h
154 You can test for the availability of a given option using the macros in
155 this section, together with the function @code{sysconf}.  The macros are
156 defined only if you include @file{unistd.h}.
158 For the following macros, if the macro is defined in @file{unistd.h},
159 then the option is supported.  Otherwise, the option may or may not be
160 supported; use @code{sysconf} to find out.  @xref{Sysconf}.
162 @comment unistd.h
163 @comment POSIX.1
164 @deftypevr Macro int _POSIX_JOB_CONTROL
165 If this symbol is defined, it indicates that the system supports job
166 control.  Otherwise, the implementation behaves as if all processes
167 within a session belong to a single process group.  @xref{Job Control}.
168 @end deftypevr
170 @comment unistd.h
171 @comment POSIX.1
172 @deftypevr Macro int _POSIX_SAVED_IDS
173 If this symbol is defined, it indicates that the system remembers the
174 effective user and group IDs of a process before it executes an
175 executable file with the set-user-ID or set-group-ID bits set, and that
176 explicitly changing the effective user or group IDs back to these values
177 is permitted.  If this option is not defined, then if a nonprivileged
178 process changes its effective user or group ID to the real user or group
179 ID of the process, it can't change it back again.  @xref{Enable/Disable
180 Setuid}.
181 @end deftypevr
183 For the following macros, if the macro is defined in @file{unistd.h},
184 then its value indicates whether the option is supported.  A value of
185 @code{-1} means no, and any other value means yes.  If the macro is not
186 defined, then the option may or may not be supported; use @code{sysconf}
187 to find out.  @xref{Sysconf}.
189 @comment unistd.h
190 @comment POSIX.2
191 @deftypevr Macro int _POSIX2_C_DEV
192 If this symbol is defined, it indicates that the system has the POSIX.2
193 C compiler command, @code{c89}.  @Theglibc{} always defines this
194 as @code{1}, on the assumption that you would not have installed it if
195 you didn't have a C compiler.
196 @end deftypevr
198 @comment unistd.h
199 @comment POSIX.2
200 @deftypevr Macro int _POSIX2_FORT_DEV
201 If this symbol is defined, it indicates that the system has the POSIX.2
202 Fortran compiler command, @code{fort77}.  @Theglibc{} never
203 defines this, because we don't know what the system has.
204 @end deftypevr
206 @comment unistd.h
207 @comment POSIX.2
208 @deftypevr Macro int _POSIX2_FORT_RUN
209 If this symbol is defined, it indicates that the system has the POSIX.2
210 @code{asa} command to interpret Fortran carriage control.  @Theglibc{}
211 never defines this, because we don't know what the system has.
212 @end deftypevr
214 @comment unistd.h
215 @comment POSIX.2
216 @deftypevr Macro int _POSIX2_LOCALEDEF
217 If this symbol is defined, it indicates that the system has the POSIX.2
218 @code{localedef} command.  @Theglibc{} never defines this, because
219 we don't know what the system has.
220 @end deftypevr
222 @comment unistd.h
223 @comment POSIX.2
224 @deftypevr Macro int _POSIX2_SW_DEV
225 If this symbol is defined, it indicates that the system has the POSIX.2
226 commands @code{ar}, @code{make}, and @code{strip}.  @Theglibc{}
227 always defines this as @code{1}, on the assumption that you had to have
228 @code{ar} and @code{make} to install the library, and it's unlikely that
229 @code{strip} would be absent when those are present.
230 @end deftypevr
232 @node Version Supported
233 @section Which Version of POSIX is Supported
235 @comment unistd.h
236 @comment POSIX.1
237 @deftypevr Macro {long int} _POSIX_VERSION
238 This constant represents the version of the POSIX.1 standard to which
239 the implementation conforms.  For an implementation conforming to the
240 1995 POSIX.1 standard, the value is the integer @code{199506L}.
242 @code{_POSIX_VERSION} is always defined (in @file{unistd.h}) in any
243 POSIX system.
245 @strong{Usage Note:} Don't try to test whether the system supports POSIX
246 by including @file{unistd.h} and then checking whether
247 @code{_POSIX_VERSION} is defined.  On a non-POSIX system, this will
248 probably fail because there is no @file{unistd.h}.  We do not know of
249 @emph{any} way you can reliably test at compilation time whether your
250 target system supports POSIX or whether @file{unistd.h} exists.
251 @end deftypevr
253 @comment unistd.h
254 @comment POSIX.2
255 @deftypevr Macro {long int} _POSIX2_C_VERSION
256 This constant represents the version of the POSIX.2 standard which the
257 library and system kernel support.  We don't know what value this will
258 be for the first version of the POSIX.2 standard, because the value is
259 based on the year and month in which the standard is officially adopted.
261 The value of this symbol says nothing about the utilities installed on
262 the system.
264 @strong{Usage Note:} You can use this macro to tell whether a POSIX.1
265 system library supports POSIX.2 as well.  Any POSIX.1 system contains
266 @file{unistd.h}, so include that file and then test @code{defined
267 (_POSIX2_C_VERSION)}.
268 @end deftypevr
270 @node Sysconf
271 @section Using @code{sysconf}
273 When your system has configurable system limits, you can use the
274 @code{sysconf} function to find out the value that applies to any
275 particular machine.  The function and the associated @var{parameter}
276 constants are declared in the header file @file{unistd.h}.
278 @menu
279 * Sysconf Definition::        Detailed specifications of @code{sysconf}.
280 * Constants for Sysconf::     The list of parameters @code{sysconf} can read.
281 * Examples of Sysconf::       How to use @code{sysconf} and the parameter
282                                  macros properly together.
283 @end menu
285 @node Sysconf Definition
286 @subsection Definition of @code{sysconf}
288 @comment unistd.h
289 @comment POSIX.1
290 @deftypefun {long int} sysconf (int @var{parameter})
291 This function is used to inquire about runtime system parameters.  The
292 @var{parameter} argument should be one of the @samp{_SC_} symbols listed
293 below.
295 The normal return value from @code{sysconf} is the value you requested.
296 A value of @code{-1} is returned both if the implementation does not
297 impose a limit, and in case of an error.
299 The following @code{errno} error conditions are defined for this function:
301 @table @code
302 @item EINVAL
303 The value of the @var{parameter} is invalid.
304 @end table
305 @end deftypefun
307 @node Constants for Sysconf
308 @subsection Constants for @code{sysconf} Parameters
310 Here are the symbolic constants for use as the @var{parameter} argument
311 to @code{sysconf}.  The values are all integer constants (more
312 specifically, enumeration type values).
314 @vtable @code
315 @comment unistd.h
316 @comment POSIX.1
317 @item _SC_ARG_MAX
318 Inquire about the parameter corresponding to @code{ARG_MAX}.
320 @comment unistd.h
321 @comment POSIX.1
322 @item _SC_CHILD_MAX
323 Inquire about the parameter corresponding to @code{CHILD_MAX}.
325 @comment unistd.h
326 @comment POSIX.1
327 @item _SC_OPEN_MAX
328 Inquire about the parameter corresponding to @code{OPEN_MAX}.
330 @comment unistd.h
331 @comment POSIX.1
332 @item _SC_STREAM_MAX
333 Inquire about the parameter corresponding to @code{STREAM_MAX}.
335 @comment unistd.h
336 @comment POSIX.1
337 @item _SC_TZNAME_MAX
338 Inquire about the parameter corresponding to @code{TZNAME_MAX}.
340 @comment unistd.h
341 @comment POSIX.1
342 @item _SC_NGROUPS_MAX
343 Inquire about the parameter corresponding to @code{NGROUPS_MAX}.
345 @comment unistd.h
346 @comment POSIX.1
347 @item _SC_JOB_CONTROL
348 Inquire about the parameter corresponding to @code{_POSIX_JOB_CONTROL}.
350 @comment unistd.h
351 @comment POSIX.1
352 @item _SC_SAVED_IDS
353 Inquire about the parameter corresponding to @code{_POSIX_SAVED_IDS}.
355 @comment unistd.h
356 @comment POSIX.1
357 @item _SC_VERSION
358 Inquire about the parameter corresponding to @code{_POSIX_VERSION}.
360 @comment unistd.h
361 @comment POSIX.1
362 @item _SC_CLK_TCK
363 Inquire about the number of clock ticks per second; @pxref{CPU Time}.
364 The corresponding parameter @code{CLK_TCK} is obsolete.
366 @comment unistd.h
367 @comment GNU
368 @item _SC_CHARCLASS_NAME_MAX
369 Inquire about the parameter corresponding to maximal length allowed for
370 a character class name in an extended locale specification.  These
371 extensions are not yet standardized and so this option is not standardized
372 as well.
374 @comment unistdh.h
375 @comment POSIX.1
376 @item _SC_REALTIME_SIGNALS
377 Inquire about the parameter corresponding to @code{_POSIX_REALTIME_SIGNALS}.
379 @comment unistd.h
380 @comment POSIX.1
381 @item _SC_PRIORITY_SCHEDULING
382 Inquire about the parameter corresponding to @code{_POSIX_PRIORITY_SCHEDULING}.
384 @comment unistd.h
385 @comment POSIX.1
386 @item _SC_TIMERS
387 Inquire about the parameter corresponding to @code{_POSIX_TIMERS}.
389 @comment unistd.h
390 @comment POSIX.1
391 @item _SC_ASYNCHRONOUS_IO
392 Inquire about the parameter corresponding to @code{_POSIX_ASYNCHRONOUS_IO}.
394 @comment unistd.h
395 @comment POSIX.1
396 @item _SC_PRIORITIZED_IO
397 Inquire about the parameter corresponding to @code{_POSIX_PRIORITIZED_IO}.
399 @comment unistd.h
400 @comment POSIX.1
401 @item _SC_SYNCHRONIZED_IO
402 Inquire about the parameter corresponding to @code{_POSIX_SYNCHRONIZED_IO}.
404 @comment unistd.h
405 @comment POSIX.1
406 @item _SC_FSYNC
407 Inquire about the parameter corresponding to @code{_POSIX_FSYNC}.
409 @comment unistd.h
410 @comment POSIX.1
411 @item _SC_MAPPED_FILES
412 Inquire about the parameter corresponding to @code{_POSIX_MAPPED_FILES}.
414 @comment unistd.h
415 @comment POSIX.1
416 @item _SC_MEMLOCK
417 Inquire about the parameter corresponding to @code{_POSIX_MEMLOCK}.
419 @comment unistd.h
420 @comment POSIX.1
421 @item _SC_MEMLOCK_RANGE
422 Inquire about the parameter corresponding to @code{_POSIX_MEMLOCK_RANGE}.
424 @comment unistd.h
425 @comment POSIX.1
426 @item _SC_MEMORY_PROTECTION
427 Inquire about the parameter corresponding to @code{_POSIX_MEMORY_PROTECTION}.
429 @comment unistd.h
430 @comment POSIX.1
431 @item _SC_MESSAGE_PASSING
432 Inquire about the parameter corresponding to @code{_POSIX_MESSAGE_PASSING}.
434 @comment unistd.h
435 @comment POSIX.1
436 @item _SC_SEMAPHORES
437 Inquire about the parameter corresponding to @code{_POSIX_SEMAPHORES}.
439 @comment unistd.h
440 @comment POSIX.1
441 @item _SC_SHARED_MEMORY_OBJECTS
442 Inquire about the parameter corresponding to@*
443 @code{_POSIX_SHARED_MEMORY_OBJECTS}.
445 @comment unistd.h
446 @comment POSIX.1
447 @item _SC_AIO_LISTIO_MAX
448 Inquire about the parameter corresponding to @code{_POSIX_AIO_LISTIO_MAX}.
450 @comment unistd.h
451 @comment POSIX.1
452 @item _SC_AIO_MAX
453 Inquire about the parameter corresponding to @code{_POSIX_AIO_MAX}.
455 @comment unistd.h
456 @comment POSIX.1
457 @item _SC_AIO_PRIO_DELTA_MAX
458 Inquire the value by which a process can decrease its asynchronous I/O
459 priority level from its own scheduling priority.  This corresponds to the
460 run-time invariant value @code{AIO_PRIO_DELTA_MAX}.
462 @comment unistd.h
463 @comment POSIX.1
464 @item _SC_DELAYTIMER_MAX
465 Inquire about the parameter corresponding to @code{_POSIX_DELAYTIMER_MAX}.
467 @comment unistd.h
468 @comment POSIX.1
469 @item _SC_MQ_OPEN_MAX
470 Inquire about the parameter corresponding to @code{_POSIX_MQ_OPEN_MAX}.
472 @comment unistd.h
473 @comment POSIX.1
474 @item _SC_MQ_PRIO_MAX
475 Inquire about the parameter corresponding to @code{_POSIX_MQ_PRIO_MAX}.
477 @comment unistd.h
478 @comment POSIX.1
479 @item _SC_RTSIG_MAX
480 Inquire about the parameter corresponding to @code{_POSIX_RTSIG_MAX}.
482 @comment unistd.h
483 @comment POSIX.1
484 @item _SC_SEM_NSEMS_MAX
485 Inquire about the parameter corresponding to @code{_POSIX_SEM_NSEMS_MAX}.
487 @comment unistd.h
488 @comment POSIX.1
489 @item _SC_SEM_VALUE_MAX
490 Inquire about the parameter corresponding to @code{_POSIX_SEM_VALUE_MAX}.
492 @comment unistd.h
493 @comment POSIX.1
494 @item _SC_SIGQUEUE_MAX
495 Inquire about the parameter corresponding to @code{_POSIX_SIGQUEUE_MAX}.
497 @comment unistd.h
498 @comment POSIX.1
499 @item _SC_TIMER_MAX
500 Inquire about the parameter corresponding to @code{_POSIX_TIMER_MAX}.
502 @comment unistd.h
503 @comment POSIX.1g
504 @item _SC_PII
505 Inquire about the parameter corresponding to @code{_POSIX_PII}.
507 @comment unistd.h
508 @comment POSIX.1g
509 @item _SC_PII_XTI
510 Inquire about the parameter corresponding to @code{_POSIX_PII_XTI}.
512 @comment unistd.h
513 @comment POSIX.1g
514 @item _SC_PII_SOCKET
515 Inquire about the parameter corresponding to @code{_POSIX_PII_SOCKET}.
517 @comment unistd.h
518 @comment POSIX.1g
519 @item _SC_PII_INTERNET
520 Inquire about the parameter corresponding to @code{_POSIX_PII_INTERNET}.
522 @comment unistd.h
523 @comment POSIX.1g
524 @item _SC_PII_OSI
525 Inquire about the parameter corresponding to @code{_POSIX_PII_OSI}.
527 @comment unistd.h
528 @comment POSIX.1g
529 @item _SC_SELECT
530 Inquire about the parameter corresponding to @code{_POSIX_SELECT}.
532 @comment unistd.h
533 @comment POSIX.1g
534 @item _SC_UIO_MAXIOV
535 Inquire about the parameter corresponding to @code{_POSIX_UIO_MAXIOV}.
537 @comment unistd.h
538 @comment POSIX.1g
539 @item _SC_PII_INTERNET_STREAM
540 Inquire about the parameter corresponding to @code{_POSIX_PII_INTERNET_STREAM}.
542 @comment unistd.h
543 @comment POSIX.1g
544 @item _SC_PII_INTERNET_DGRAM
545 Inquire about the parameter corresponding to @code{_POSIX_PII_INTERNET_DGRAM}.
547 @comment unistd.h
548 @comment POSIX.1g
549 @item _SC_PII_OSI_COTS
550 Inquire about the parameter corresponding to @code{_POSIX_PII_OSI_COTS}.
552 @comment unistd.h
553 @comment POSIX.1g
554 @item _SC_PII_OSI_CLTS
555 Inquire about the parameter corresponding to @code{_POSIX_PII_OSI_CLTS}.
557 @comment unistd.h
558 @comment POSIX.1g
559 @item _SC_PII_OSI_M
560 Inquire about the parameter corresponding to @code{_POSIX_PII_OSI_M}.
562 @comment unistd.h
563 @comment POSIX.1g
564 @item _SC_T_IOV_MAX
565 Inquire the value of the value associated with the @code{T_IOV_MAX}
566 variable.
568 @comment unistd.h
569 @comment POSIX.1
570 @item _SC_THREADS
571 Inquire about the parameter corresponding to @code{_POSIX_THREADS}.
573 @comment unistd.h
574 @comment POSIX.1
575 @item _SC_THREAD_SAFE_FUNCTIONS
576 Inquire about the parameter corresponding to@*
577 @code{_POSIX_THREAD_SAFE_FUNCTIONS}.
579 @comment unistd.h
580 @comment POSIX.1
581 @item _SC_GETGR_R_SIZE_MAX
582 Inquire about the parameter corresponding to @code{_POSIX_GETGR_R_SIZE_MAX}.
584 @comment unistd.h
585 @comment POSIX.1
586 @item _SC_GETPW_R_SIZE_MAX
587 Inquire about the parameter corresponding to @code{_POSIX_GETPW_R_SIZE_MAX}.
589 @comment unistd.h
590 @comment POSIX.1
591 @item _SC_LOGIN_NAME_MAX
592 Inquire about the parameter corresponding to @code{_POSIX_LOGIN_NAME_MAX}.
594 @comment unistd.h
595 @comment POSIX.1
596 @item _SC_TTY_NAME_MAX
597 Inquire about the parameter corresponding to @code{_POSIX_TTY_NAME_MAX}.
599 @comment unistd.h
600 @comment POSIX.1
601 @item _SC_THREAD_DESTRUCTOR_ITERATIONS
602 Inquire about the parameter corresponding to
603 @code{_POSIX_THREAD_DESTRUCTOR_ITERATIONS}.
605 @comment unistd.h
606 @comment POSIX.1
607 @item _SC_THREAD_KEYS_MAX
608 Inquire about the parameter corresponding to @code{_POSIX_THREAD_KEYS_MAX}.
610 @comment unistd.h
611 @comment POSIX.1
612 @item _SC_THREAD_STACK_MIN
613 Inquire about the parameter corresponding to @code{_POSIX_THREAD_STACK_MIN}.
615 @comment unistd.h
616 @comment POSIX.1
617 @item _SC_THREAD_THREADS_MAX
618 Inquire about the parameter corresponding to @code{_POSIX_THREAD_THREADS_MAX}.
620 @comment unistd.h
621 @comment POSIX.1
622 @item _SC_THREAD_ATTR_STACKADDR
623 Inquire about the parameter corresponding to@*a
624 @code{_POSIX_THREAD_ATTR_STACKADDR}.
626 @comment unistd.h
627 @comment POSIX.1
628 @item _SC_THREAD_ATTR_STACKSIZE
629 Inquire about the parameter corresponding to@*
630 @code{_POSIX_THREAD_ATTR_STACKSIZE}.
632 @comment unistd.h
633 @comment POSIX.1
634 @item _SC_THREAD_PRIORITY_SCHEDULING
635 Inquire about the parameter corresponding to
636 @code{_POSIX_THREAD_PRIORITY_SCHEDULING}.
638 @comment unistd.h
639 @comment POSIX.1
640 @item _SC_THREAD_PRIO_INHERIT
641 Inquire about the parameter corresponding to @code{_POSIX_THREAD_PRIO_INHERIT}.
643 @comment unistd.h
644 @comment POSIX.1
645 @item _SC_THREAD_PRIO_PROTECT
646 Inquire about the parameter corresponding to @code{_POSIX_THREAD_PRIO_PROTECT}.
648 @comment unistd.h
649 @comment POSIX.1
650 @item _SC_THREAD_PROCESS_SHARED
651 Inquire about the parameter corresponding to
652 @code{_POSIX_THREAD_PROCESS_SHARED}.
654 @comment unistd.h
655 @comment POSIX.2
656 @item _SC_2_C_DEV
657 Inquire about whether the system has the POSIX.2 C compiler command,
658 @code{c89}.
660 @comment unistd.h
661 @comment POSIX.2
662 @item _SC_2_FORT_DEV
663 Inquire about whether the system has the POSIX.2 Fortran compiler
664 command, @code{fort77}.
666 @comment unistd.h
667 @comment POSIX.2
668 @item _SC_2_FORT_RUN
669 Inquire about whether the system has the POSIX.2 @code{asa} command to
670 interpret Fortran carriage control.
672 @comment unistd.h
673 @comment POSIX.2
674 @item _SC_2_LOCALEDEF
675 Inquire about whether the system has the POSIX.2 @code{localedef}
676 command.
678 @comment unistd.h
679 @comment POSIX.2
680 @item _SC_2_SW_DEV
681 Inquire about whether the system has the POSIX.2 commands @code{ar},
682 @code{make}, and @code{strip}.
684 @comment unistd.h
685 @comment POSIX.2
686 @item _SC_BC_BASE_MAX
687 Inquire about the maximum value of @code{obase} in the @code{bc}
688 utility.
690 @comment unistd.h
691 @comment POSIX.2
692 @item _SC_BC_DIM_MAX
693 Inquire about the maximum size of an array in the @code{bc}
694 utility.
696 @comment unistd.h
697 @comment POSIX.2
698 @item _SC_BC_SCALE_MAX
699 Inquire about the maximum value of @code{scale} in the @code{bc}
700 utility.
702 @comment unistd.h
703 @comment POSIX.2
704 @item _SC_BC_STRING_MAX
705 Inquire about the maximum size of a string constant in the
706 @code{bc} utility.
708 @comment unistd.h
709 @comment POSIX.2
710 @item _SC_COLL_WEIGHTS_MAX
711 Inquire about the maximum number of weights that can necessarily
712 be used in defining the collating sequence for a locale.
714 @comment unistd.h
715 @comment POSIX.2
716 @item _SC_EXPR_NEST_MAX
717 Inquire about the maximum number of expressions nested within
718 parentheses when using the @code{expr} utility.
720 @comment unistd.h
721 @comment POSIX.2
722 @item _SC_LINE_MAX
723 Inquire about the maximum size of a text line that the POSIX.2 text
724 utilities can handle.
726 @comment unistd.h
727 @comment POSIX.2
728 @item _SC_EQUIV_CLASS_MAX
729 Inquire about the maximum number of weights that can be assigned to an
730 entry of the @code{LC_COLLATE} category @samp{order} keyword in a locale
731 definition.  @Theglibc{} does not presently support locale
732 definitions.
734 @comment unistd.h
735 @comment POSIX.2
736 @item _SC_VERSION
737 Inquire about the version number of POSIX.1 that the library and kernel
738 support.
740 @comment unistd.h
741 @comment POSIX.2
742 @item _SC_2_VERSION
743 Inquire about the version number of POSIX.2 that the system utilities
744 support.
746 @comment unistd.h
747 @comment GNU
748 @item _SC_PAGESIZE
749 Inquire about the virtual memory page size of the machine.
750 @code{getpagesize} returns the same value (@pxref{Query Memory Parameters}).
752 @comment unistd.h
753 @comment GNU
754 @item _SC_NPROCESSORS_CONF
755 Inquire about the number of configured processors.
757 @comment unistd.h
758 @comment GNU
759 @item _SC_NPROCESSORS_ONLN
760 Inquire about the number of processors online.
762 @comment unistd.h
763 @comment GNU
764 @item _SC_PHYS_PAGES
765 Inquire about the number of physical pages in the system.
767 @comment unistd.h
768 @comment GNU
769 @item _SC_AVPHYS_PAGES
770 Inquire about the number of available physical pages in the system.
772 @comment unistd.h
773 @comment GNU
774 @item _SC_ATEXIT_MAX
775 Inquire about the number of functions which can be registered as termination
776 functions for @code{atexit}; @pxref{Cleanups on Exit}.
778 @comment unistd.h
779 @comment X/Open
780 @item _SC_XOPEN_VERSION
781 Inquire about the parameter corresponding to @code{_XOPEN_VERSION}.
783 @comment unistd.h
784 @comment X/Open
785 @item _SC_XOPEN_XCU_VERSION
786 Inquire about the parameter corresponding to @code{_XOPEN_XCU_VERSION}.
788 @comment unistd.h
789 @comment X/Open
790 @item _SC_XOPEN_UNIX
791 Inquire about the parameter corresponding to @code{_XOPEN_UNIX}.
793 @comment unistd.h
794 @comment X/Open
795 @item _SC_XOPEN_REALTIME
796 Inquire about the parameter corresponding to @code{_XOPEN_REALTIME}.
798 @comment unistd.h
799 @comment X/Open
800 @item _SC_XOPEN_REALTIME_THREADS
801 Inquire about the parameter corresponding to @code{_XOPEN_REALTIME_THREADS}.
803 @comment unistd.h
804 @comment X/Open
805 @item _SC_XOPEN_LEGACY
806 Inquire about the parameter corresponding to @code{_XOPEN_LEGACY}.
808 @comment unistd.h
809 @comment X/Open
810 @item _SC_XOPEN_CRYPT
811 Inquire about the parameter corresponding to @code{_XOPEN_CRYPT}.
813 @comment unistd.h
814 @comment X/Open
815 @item _SC_XOPEN_ENH_I18N
816 Inquire about the parameter corresponding to @code{_XOPEN_ENH_I18N}.
818 @comment unistd.h
819 @comment X/Open
820 @item _SC_XOPEN_SHM
821 Inquire about the parameter corresponding to @code{_XOPEN_SHM}.
823 @comment unistd.h
824 @comment X/Open
825 @item _SC_XOPEN_XPG2
826 Inquire about the parameter corresponding to @code{_XOPEN_XPG2}.
828 @comment unistd.h
829 @comment X/Open
830 @item _SC_XOPEN_XPG3
831 Inquire about the parameter corresponding to @code{_XOPEN_XPG3}.
833 @comment unistd.h
834 @comment X/Open
835 @item _SC_XOPEN_XPG4
836 Inquire about the parameter corresponding to @code{_XOPEN_XPG4}.
838 @comment unistd.h
839 @comment X/Open
840 @item _SC_CHAR_BIT
841 Inquire about the number of bits in a variable of type @code{char}.
843 @comment unistd.h
844 @comment X/Open
845 @item _SC_CHAR_MAX
846 Inquire about the maximum value which can be stored in a variable of type
847 @code{char}.
849 @comment unistd.h
850 @comment X/Open
851 @item _SC_CHAR_MIN
852 Inquire about the minimum value which can be stored in a variable of type
853 @code{char}.
855 @comment unistd.h
856 @comment X/Open
857 @item _SC_INT_MAX
858 Inquire about the maximum value which can be stored in a variable of type
859 @code{int}.
861 @comment unistd.h
862 @comment X/Open
863 @item _SC_INT_MIN
864 Inquire about the minimum value which can be stored in a variable of type
865 @code{int}.
867 @comment unistd.h
868 @comment X/Open
869 @item _SC_LONG_BIT
870 Inquire about the number of bits in a variable of type @code{long int}.
872 @comment unistd.h
873 @comment X/Open
874 @item _SC_WORD_BIT
875 Inquire about the number of bits in a variable of a register word.
877 @comment unistd.h
878 @comment X/Open
879 @item _SC_MB_LEN_MAX
880 Inquire the maximum length of a multi-byte representation of a wide
881 character value.
883 @comment unistd.h
884 @comment X/Open
885 @item _SC_NZERO
886 Inquire about the value used to internally represent the zero priority level for
887 the process execution.
889 @comment unistd.h
890 @comment X/Open
891 @item SC_SSIZE_MAX
892 Inquire about the maximum value which can be stored in a variable of type
893 @code{ssize_t}.
895 @comment unistd.h
896 @comment X/Open
897 @item _SC_SCHAR_MAX
898 Inquire about the maximum value which can be stored in a variable of type
899 @code{signed char}.
901 @comment unistd.h
902 @comment X/Open
903 @item _SC_SCHAR_MIN
904 Inquire about the minimum value which can be stored in a variable of type
905 @code{signed char}.
907 @comment unistd.h
908 @comment X/Open
909 @item _SC_SHRT_MAX
910 Inquire about the maximum value which can be stored in a variable of type
911 @code{short int}.
913 @comment unistd.h
914 @comment X/Open
915 @item _SC_SHRT_MIN
916 Inquire about the minimum value which can be stored in a variable of type
917 @code{short int}.
919 @comment unistd.h
920 @comment X/Open
921 @item _SC_UCHAR_MAX
922 Inquire about the maximum value which can be stored in a variable of type
923 @code{unsigned char}.
925 @comment unistd.h
926 @comment X/Open
927 @item _SC_UINT_MAX
928 Inquire about the maximum value which can be stored in a variable of type
929 @code{unsigned int}.
931 @comment unistd.h
932 @comment X/Open
933 @item _SC_ULONG_MAX
934 Inquire about the maximum value which can be stored in a variable of type
935 @code{unsigned long int}.
937 @comment unistd.h
938 @comment X/Open
939 @item _SC_USHRT_MAX
940 Inquire about the maximum value which can be stored in a variable of type
941 @code{unsigned short int}.
943 @comment unistd.h
944 @comment X/Open
945 @item _SC_NL_ARGMAX
946 Inquire about the parameter corresponding to @code{NL_ARGMAX}.
948 @comment unistd.h
949 @comment X/Open
950 @item _SC_NL_LANGMAX
951 Inquire about the parameter corresponding to @code{NL_LANGMAX}.
953 @comment unistd.h
954 @comment X/Open
955 @item _SC_NL_MSGMAX
956 Inquire about the parameter corresponding to @code{NL_MSGMAX}.
958 @comment unistd.h
959 @comment X/Open
960 @item _SC_NL_NMAX
961 Inquire about  the parameter corresponding to @code{NL_NMAX}.
963 @comment unistd.h
964 @comment X/Open
965 @item _SC_NL_SETMAX
966 Inquire about the parameter corresponding to @code{NL_SETMAX}.
968 @comment unistd.h
969 @comment X/Open
970 @item _SC_NL_TEXTMAX
971 Inquire about the parameter corresponding to @code{NL_TEXTMAX}.
972 @end vtable
974 @node Examples of Sysconf
975 @subsection Examples of @code{sysconf}
977 We recommend that you first test for a macro definition for the
978 parameter you are interested in, and call @code{sysconf} only if the
979 macro is not defined.  For example, here is how to test whether job
980 control is supported:
982 @smallexample
983 @group
985 have_job_control (void)
987 #ifdef _POSIX_JOB_CONTROL
988   return 1;
989 #else
990   int value = sysconf (_SC_JOB_CONTROL);
991   if (value < 0)
992     /* @r{If the system is that badly wedged,}
993        @r{there's no use trying to go on.}  */
994     fatal (strerror (errno));
995   return value;
996 #endif
998 @end group
999 @end smallexample
1001 Here is how to get the value of a numeric limit:
1003 @smallexample
1005 get_child_max ()
1007 #ifdef CHILD_MAX
1008   return CHILD_MAX;
1009 #else
1010   int value = sysconf (_SC_CHILD_MAX);
1011   if (value < 0)
1012     fatal (strerror (errno));
1013   return value;
1014 #endif
1016 @end smallexample
1018 @node Minimums
1019 @section Minimum Values for General Capacity Limits
1021 Here are the names for the POSIX minimum upper bounds for the system
1022 limit parameters.  The significance of these values is that you can
1023 safely push to these limits without checking whether the particular
1024 system you are using can go that far.
1026 @table @code
1027 @comment limits.h
1028 @comment POSIX.1
1029 @item _POSIX_AIO_LISTIO_MAX
1030 The most restrictive limit permitted by POSIX for the maximum number of
1031 I/O operations that can be specified in a list I/O call.  The value of
1032 this constant is @code{2}; thus you can add up to two new entries
1033 of the list of outstanding operations.
1035 @comment limits.h
1036 @comment POSIX.1
1037 @item _POSIX_AIO_MAX
1038 The most restrictive limit permitted by POSIX for the maximum number of
1039 outstanding asynchronous I/O operations.  The value of this constant is
1040 @code{1}.  So you cannot expect that you can issue more than one
1041 operation and immediately continue with the normal work, receiving the
1042 notifications asynchronously.
1044 @comment limits.h
1045 @comment POSIX.1
1046 @item _POSIX_ARG_MAX
1047 The value of this macro is the most restrictive limit permitted by POSIX
1048 for the maximum combined length of the @var{argv} and @var{environ}
1049 arguments that can be passed to the @code{exec} functions.
1050 Its value is @code{4096}.
1052 @comment limits.h
1053 @comment POSIX.1
1054 @item _POSIX_CHILD_MAX
1055 The value of this macro is the most restrictive limit permitted by POSIX
1056 for the maximum number of simultaneous processes per real user ID.  Its
1057 value is @code{6}.
1059 @comment limits.h
1060 @comment POSIX.1
1061 @item _POSIX_NGROUPS_MAX
1062 The value of this macro is the most restrictive limit permitted by POSIX
1063 for the maximum number of supplementary group IDs per process.  Its
1064 value is @code{0}.
1066 @comment limits.h
1067 @comment POSIX.1
1068 @item _POSIX_OPEN_MAX
1069 The value of this macro is the most restrictive limit permitted by POSIX
1070 for the maximum number of files that a single process can have open
1071 simultaneously.  Its value is @code{16}.
1073 @comment limits.h
1074 @comment POSIX.1
1075 @item _POSIX_SSIZE_MAX
1076 The value of this macro is the most restrictive limit permitted by POSIX
1077 for the maximum value that can be stored in an object of type
1078 @code{ssize_t}.  Its value is @code{32767}.
1080 @comment limits.h
1081 @comment POSIX.1
1082 @item _POSIX_STREAM_MAX
1083 The value of this macro is the most restrictive limit permitted by POSIX
1084 for the maximum number of streams that a single process can have open
1085 simultaneously.  Its value is @code{8}.
1087 @comment limits.h
1088 @comment POSIX.1
1089 @item _POSIX_TZNAME_MAX
1090 The value of this macro is the most restrictive limit permitted by POSIX
1091 for the maximum length of a time zone name.  Its value is @code{3}.
1093 @comment limits.h
1094 @comment POSIX.2
1095 @item _POSIX2_RE_DUP_MAX
1096 The value of this macro is the most restrictive limit permitted by POSIX
1097 for the numbers used in the @samp{\@{@var{min},@var{max}\@}} construct
1098 in a regular expression.  Its value is @code{255}.
1099 @end table
1101 @node Limits for Files
1102 @section Limits on File System Capacity
1104 The POSIX.1 standard specifies a number of parameters that describe the
1105 limitations of the file system.  It's possible for the system to have a
1106 fixed, uniform limit for a parameter, but this isn't the usual case.  On
1107 most systems, it's possible for different file systems (and, for some
1108 parameters, even different files) to have different maximum limits.  For
1109 example, this is very likely if you use NFS to mount some of the file
1110 systems from other machines.
1112 @pindex limits.h
1113 Each of the following macros is defined in @file{limits.h} only if the
1114 system has a fixed, uniform limit for the parameter in question.  If the
1115 system allows different file systems or files to have different limits,
1116 then the macro is undefined; use @code{pathconf} or @code{fpathconf} to
1117 find out the limit that applies to a particular file.  @xref{Pathconf}.
1119 Each parameter also has another macro, with a name starting with
1120 @samp{_POSIX}, which gives the lowest value that the limit is allowed to
1121 have on @emph{any} POSIX system.  @xref{File Minimums}.
1123 @cindex limits, link count of files
1124 @comment limits.h (optional)
1125 @comment POSIX.1
1126 @deftypevr Macro int LINK_MAX
1127 The uniform system limit (if any) for the number of names for a given
1128 file.  @xref{Hard Links}.
1129 @end deftypevr
1131 @cindex limits, terminal input queue
1132 @comment limits.h
1133 @comment POSIX.1
1134 @deftypevr Macro int MAX_CANON
1135 The uniform system limit (if any) for the amount of text in a line of
1136 input when input editing is enabled.  @xref{Canonical or Not}.
1137 @end deftypevr
1139 @comment limits.h
1140 @comment POSIX.1
1141 @deftypevr Macro int MAX_INPUT
1142 The uniform system limit (if any) for the total number of characters
1143 typed ahead as input.  @xref{I/O Queues}.
1144 @end deftypevr
1146 @cindex limits, file name length
1147 @comment limits.h
1148 @comment POSIX.1
1149 @deftypevr Macro int NAME_MAX
1150 The uniform system limit (if any) for the length of a file name component, not
1151 including the terminating null character.
1153 @strong{Portability Note:} On some systems, @theglibc{} defines
1154 @code{NAME_MAX}, but does not actually enforce this limit.
1155 @end deftypevr
1157 @comment limits.h
1158 @comment POSIX.1
1159 @deftypevr Macro int PATH_MAX
1160 The uniform system limit (if any) for the length of an entire file name (that
1161 is, the argument given to system calls such as @code{open}), including the
1162 terminating null character.
1164 @strong{Portability Note:} @Theglibc{} does not enforce this limit
1165 even if @code{PATH_MAX} is defined.
1166 @end deftypevr
1168 @cindex limits, pipe buffer size
1169 @comment limits.h
1170 @comment POSIX.1
1171 @deftypevr Macro int PIPE_BUF
1172 The uniform system limit (if any) for the number of bytes that can be
1173 written atomically to a pipe.  If multiple processes are writing to the
1174 same pipe simultaneously, output from different processes might be
1175 interleaved in chunks of this size.  @xref{Pipes and FIFOs}.
1176 @end deftypevr
1178 These are alternative macro names for some of the same information.
1180 @comment dirent.h
1181 @comment BSD
1182 @deftypevr Macro int MAXNAMLEN
1183 This is the BSD name for @code{NAME_MAX}.  It is defined in
1184 @file{dirent.h}.
1185 @end deftypevr
1187 @comment stdio.h
1188 @comment ISO
1189 @deftypevr Macro int FILENAME_MAX
1190 The value of this macro is an integer constant expression that
1191 represents the maximum length of a file name string.  It is defined in
1192 @file{stdio.h}.
1194 Unlike @code{PATH_MAX}, this macro is defined even if there is no actual
1195 limit imposed.  In such a case, its value is typically a very large
1196 number.  @strong{This is always the case on @gnuhurdsystems{}.}
1198 @strong{Usage Note:} Don't use @code{FILENAME_MAX} as the size of an
1199 array in which to store a file name!  You can't possibly make an array
1200 that big!  Use dynamic allocation (@pxref{Memory Allocation}) instead.
1201 @end deftypevr
1203 @node Options for Files
1204 @section Optional Features in File Support
1206 POSIX defines certain system-specific options in the system calls for
1207 operating on files.  Some systems support these options and others do
1208 not.  Since these options are provided in the kernel, not in the
1209 library, simply using @theglibc{} does not guarantee that any of these
1210 features is supported; it depends on the system you are using.  They can
1211 also vary between file systems on a single machine.
1213 @pindex unistd.h
1214 This section describes the macros you can test to determine whether a
1215 particular option is supported on your machine.  If a given macro is
1216 defined in @file{unistd.h}, then its value says whether the
1217 corresponding feature is supported.  (A value of @code{-1} indicates no;
1218 any other value indicates yes.)  If the macro is undefined, it means
1219 particular files may or may not support the feature.
1221 Since all the machines that support @theglibc{} also support NFS,
1222 one can never make a general statement about whether all file systems
1223 support the @code{_POSIX_CHOWN_RESTRICTED} and @code{_POSIX_NO_TRUNC}
1224 features.  So these names are never defined as macros in @theglibc{}.
1226 @comment unistd.h
1227 @comment POSIX.1
1228 @deftypevr Macro int _POSIX_CHOWN_RESTRICTED
1229 If this option is in effect, the @code{chown} function is restricted so
1230 that the only changes permitted to nonprivileged processes is to change
1231 the group owner of a file to either be the effective group ID of the
1232 process, or one of its supplementary group IDs.  @xref{File Owner}.
1233 @end deftypevr
1235 @comment unistd.h
1236 @comment POSIX.1
1237 @deftypevr Macro int _POSIX_NO_TRUNC
1238 If this option is in effect, file name components longer than
1239 @code{NAME_MAX} generate an @code{ENAMETOOLONG} error.  Otherwise, file
1240 name components that are too long are silently truncated.
1241 @end deftypevr
1243 @comment unistd.h
1244 @comment POSIX.1
1245 @deftypevr Macro {unsigned char} _POSIX_VDISABLE
1246 This option is only meaningful for files that are terminal devices.
1247 If it is enabled, then handling for special control characters can
1248 be disabled individually.  @xref{Special Characters}.
1249 @end deftypevr
1251 @pindex unistd.h
1252 If one of these macros is undefined, that means that the option might be
1253 in effect for some files and not for others.  To inquire about a
1254 particular file, call @code{pathconf} or @code{fpathconf}.
1255 @xref{Pathconf}.
1257 @node File Minimums
1258 @section Minimum Values for File System Limits
1260 Here are the names for the POSIX minimum upper bounds for some of the
1261 above parameters.  The significance of these values is that you can
1262 safely push to these limits without checking whether the particular
1263 system you are using can go that far.  In most cases @gnusystems{} do not
1264 have these strict limitations.  The actual limit should be requested if
1265 necessary.
1267 @table @code
1268 @comment limits.h
1269 @comment POSIX.1
1270 @item _POSIX_LINK_MAX
1271 The most restrictive limit permitted by POSIX for the maximum value of a
1272 file's link count.  The value of this constant is @code{8}; thus, you
1273 can always make up to eight names for a file without running into a
1274 system limit.
1276 @comment limits.h
1277 @comment POSIX.1
1278 @item _POSIX_MAX_CANON
1279 The most restrictive limit permitted by POSIX for the maximum number of
1280 bytes in a canonical input line from a terminal device.  The value of
1281 this constant is @code{255}.
1283 @comment limits.h
1284 @comment POSIX.1
1285 @item _POSIX_MAX_INPUT
1286 The most restrictive limit permitted by POSIX for the maximum number of
1287 bytes in a terminal device input queue (or typeahead buffer).
1288 @xref{Input Modes}.  The value of this constant is @code{255}.
1290 @comment limits.h
1291 @comment POSIX.1
1292 @item _POSIX_NAME_MAX
1293 The most restrictive limit permitted by POSIX for the maximum number of
1294 bytes in a file name component.  The value of this constant is
1295 @code{14}.
1297 @comment limits.h
1298 @comment POSIX.1
1299 @item _POSIX_PATH_MAX
1300 The most restrictive limit permitted by POSIX for the maximum number of
1301 bytes in a file name.  The value of this constant is @code{256}.
1303 @comment limits.h
1304 @comment POSIX.1
1305 @item _POSIX_PIPE_BUF
1306 The most restrictive limit permitted by POSIX for the maximum number of
1307 bytes that can be written atomically to a pipe.  The value of this
1308 constant is @code{512}.
1310 @comment limits.h
1311 @comment POSIX.1
1312 @item SYMLINK_MAX
1313 Maximum number of bytes in a symbolic link.
1315 @comment limits.h
1316 @comment POSIX.1
1317 @item POSIX_REC_INCR_XFER_SIZE
1318 Recommended increment for file transfer sizes between the
1319 @code{POSIX_REC_MIN_XFER_SIZE} and @code{POSIX_REC_MAX_XFER_SIZE}
1320 values.
1322 @comment limits.h
1323 @comment POSIX.1
1324 @item POSIX_REC_MAX_XFER_SIZE
1325 Maximum recommended file transfer size.
1327 @comment limits.h
1328 @comment POSIX.1
1329 @item POSIX_REC_MIN_XFER_SIZE
1330 Minimum recommended file transfer size.
1332 @comment limits.h
1333 @comment POSIX.1
1334 @item POSIX_REC_XFER_ALIGN
1335 Recommended file transfer buffer alignment.
1336 @end table
1338 @node Pathconf
1339 @section Using @code{pathconf}
1341 When your machine allows different files to have different values for a
1342 file system parameter, you can use the functions in this section to find
1343 out the value that applies to any particular file.
1345 These functions and the associated constants for the @var{parameter}
1346 argument are declared in the header file @file{unistd.h}.
1348 @comment unistd.h
1349 @comment POSIX.1
1350 @deftypefun {long int} pathconf (const char *@var{filename}, int @var{parameter})
1351 This function is used to inquire about the limits that apply to
1352 the file named @var{filename}.
1354 The @var{parameter} argument should be one of the @samp{_PC_} constants
1355 listed below.
1357 The normal return value from @code{pathconf} is the value you requested.
1358 A value of @code{-1} is returned both if the implementation does not
1359 impose a limit, and in case of an error.  In the former case,
1360 @code{errno} is not set, while in the latter case, @code{errno} is set
1361 to indicate the cause of the problem.  So the only way to use this
1362 function robustly is to store @code{0} into @code{errno} just before
1363 calling it.
1365 Besides the usual file name errors (@pxref{File Name Errors}),
1366 the following error condition is defined for this function:
1368 @table @code
1369 @item EINVAL
1370 The value of @var{parameter} is invalid, or the implementation doesn't
1371 support the @var{parameter} for the specific file.
1372 @end table
1373 @end deftypefun
1375 @comment unistd.h
1376 @comment POSIX.1
1377 @deftypefun {long int} fpathconf (int @var{filedes}, int @var{parameter})
1378 This is just like @code{pathconf} except that an open file descriptor
1379 is used to specify the file for which information is requested, instead
1380 of a file name.
1382 The following @code{errno} error conditions are defined for this function:
1384 @table @code
1385 @item EBADF
1386 The @var{filedes} argument is not a valid file descriptor.
1388 @item EINVAL
1389 The value of @var{parameter} is invalid, or the implementation doesn't
1390 support the @var{parameter} for the specific file.
1391 @end table
1392 @end deftypefun
1394 Here are the symbolic constants that you can use as the @var{parameter}
1395 argument to @code{pathconf} and @code{fpathconf}.  The values are all
1396 integer constants.
1398 @table @code
1399 @comment unistd.h
1400 @comment POSIX.1
1401 @item _PC_LINK_MAX
1402 Inquire about the value of @code{LINK_MAX}.
1404 @comment unistd.h
1405 @comment POSIX.1
1406 @item _PC_MAX_CANON
1407 Inquire about the value of @code{MAX_CANON}.
1409 @comment unistd.h
1410 @comment POSIX.1
1411 @item _PC_MAX_INPUT
1412 Inquire about the value of @code{MAX_INPUT}.
1414 @comment unistd.h
1415 @comment POSIX.1
1416 @item _PC_NAME_MAX
1417 Inquire about the value of @code{NAME_MAX}.
1419 @comment unistd.h
1420 @comment POSIX.1
1421 @item _PC_PATH_MAX
1422 Inquire about the value of @code{PATH_MAX}.
1424 @comment unistd.h
1425 @comment POSIX.1
1426 @item _PC_PIPE_BUF
1427 Inquire about the value of @code{PIPE_BUF}.
1429 @comment unistd.h
1430 @comment POSIX.1
1431 @item _PC_CHOWN_RESTRICTED
1432 Inquire about the value of @code{_POSIX_CHOWN_RESTRICTED}.
1434 @comment unistd.h
1435 @comment POSIX.1
1436 @item _PC_NO_TRUNC
1437 Inquire about the value of @code{_POSIX_NO_TRUNC}.
1439 @comment unistd.h
1440 @comment POSIX.1
1441 @item _PC_VDISABLE
1442 Inquire about the value of @code{_POSIX_VDISABLE}.
1444 @comment unistd.h
1445 @comment POSIX.1
1446 @item _PC_SYNC_IO
1447 Inquire about the value of @code{_POSIX_SYNC_IO}.
1449 @comment unistd.h
1450 @comment POSIX.1
1451 @item _PC_ASYNC_IO
1452 Inquire about the value of @code{_POSIX_ASYNC_IO}.
1454 @comment unistd.h
1455 @comment POSIX.1
1456 @item _PC_PRIO_IO
1457 Inquire about the value of @code{_POSIX_PRIO_IO}.
1459 @comment unistd.h
1460 @comment LFS
1461 @item _PC_FILESIZEBITS
1462 Inquire about the availability of large files on the filesystem.
1464 @comment unistd.h
1465 @comment POSIX.1
1466 @item _PC_REC_INCR_XFER_SIZE
1467 Inquire about the value of @code{POSIX_REC_INCR_XFER_SIZE}.
1469 @comment unistd.h
1470 @comment POSIX.1
1471 @item _PC_REC_MAX_XFER_SIZE
1472 Inquire about the value of @code{POSIX_REC_MAX_XFER_SIZE}.
1474 @comment unistd.h
1475 @comment POSIX.1
1476 @item _PC_REC_MIN_XFER_SIZE
1477 Inquire about the value of @code{POSIX_REC_MIN_XFER_SIZE}.
1479 @comment unistd.h
1480 @comment POSIX.1
1481 @item _PC_REC_XFER_ALIGN
1482 Inquire about the value of @code{POSIX_REC_XFER_ALIGN}.
1483 @end table
1485 @strong{Portability Note:} On some systems, @theglibc{} does not
1486 enforce @code{_PC_NAME_MAX} or @code{_PC_PATH_MAX} limits.
1488 @node Utility Limits
1489 @section Utility Program Capacity Limits
1491 The POSIX.2 standard specifies certain system limits that you can access
1492 through @code{sysconf} that apply to utility behavior rather than the
1493 behavior of the library or the operating system.
1495 @Theglibc{} defines macros for these limits, and @code{sysconf}
1496 returns values for them if you ask; but these values convey no
1497 meaningful information.  They are simply the smallest values that
1498 POSIX.2 permits.
1500 @comment limits.h
1501 @comment POSIX.2
1502 @deftypevr Macro int BC_BASE_MAX
1503 The largest value of @code{obase} that the @code{bc} utility is
1504 guaranteed to support.
1505 @end deftypevr
1507 @comment limits.h
1508 @comment POSIX.2
1509 @deftypevr Macro int BC_DIM_MAX
1510 The largest number of elements in one array that the @code{bc} utility
1511 is guaranteed to support.
1512 @end deftypevr
1514 @comment limits.h
1515 @comment POSIX.2
1516 @deftypevr Macro int BC_SCALE_MAX
1517 The largest value of @code{scale} that the @code{bc} utility is
1518 guaranteed to support.
1519 @end deftypevr
1521 @comment limits.h
1522 @comment POSIX.2
1523 @deftypevr Macro int BC_STRING_MAX
1524 The largest number of characters in one string constant that the
1525 @code{bc} utility is guaranteed to support.
1526 @end deftypevr
1528 @comment limits.h
1529 @comment POSIX.2
1530 @deftypevr Macro int COLL_WEIGHTS_MAX
1531 The largest number of weights that can necessarily be used in defining
1532 the collating sequence for a locale.
1533 @end deftypevr
1535 @comment limits.h
1536 @comment POSIX.2
1537 @deftypevr Macro int EXPR_NEST_MAX
1538 The maximum number of expressions that can be nested within parenthesis
1539 by the @code{expr} utility.
1540 @end deftypevr
1542 @comment limits.h
1543 @comment POSIX.2
1544 @deftypevr Macro int LINE_MAX
1545 The largest text line that the text-oriented POSIX.2 utilities can
1546 support.  (If you are using the GNU versions of these utilities, then
1547 there is no actual limit except that imposed by the available virtual
1548 memory, but there is no way that the library can tell you this.)
1549 @end deftypevr
1551 @comment limits.h
1552 @comment POSIX.2
1553 @deftypevr Macro int EQUIV_CLASS_MAX
1554 The maximum number of weights that can be assigned to an entry of the
1555 @code{LC_COLLATE} category @samp{order} keyword in a locale definition.
1556 @Theglibc{} does not presently support locale definitions.
1557 @end deftypevr
1559 @node Utility Minimums
1560 @section Minimum Values for Utility Limits
1562 @table @code
1563 @comment limits.h
1564 @comment POSIX.2
1565 @item _POSIX2_BC_BASE_MAX
1566 The most restrictive limit permitted by POSIX.2 for the maximum value of
1567 @code{obase} in the @code{bc} utility.  Its value is @code{99}.
1569 @comment limits.h
1570 @comment POSIX.2
1571 @item _POSIX2_BC_DIM_MAX
1572 The most restrictive limit permitted by POSIX.2 for the maximum size of
1573 an array in the @code{bc} utility.  Its value is @code{2048}.
1575 @comment limits.h
1576 @comment POSIX.2
1577 @item _POSIX2_BC_SCALE_MAX
1578 The most restrictive limit permitted by POSIX.2 for the maximum value of
1579 @code{scale} in the @code{bc} utility.  Its value is @code{99}.
1581 @comment limits.h
1582 @comment POSIX.2
1583 @item _POSIX2_BC_STRING_MAX
1584 The most restrictive limit permitted by POSIX.2 for the maximum size of
1585 a string constant in the @code{bc} utility.  Its value is @code{1000}.
1587 @comment limits.h
1588 @comment POSIX.2
1589 @item _POSIX2_COLL_WEIGHTS_MAX
1590 The most restrictive limit permitted by POSIX.2 for the maximum number
1591 of weights that can necessarily be used in defining the collating
1592 sequence for a locale.  Its value is @code{2}.
1594 @comment limits.h
1595 @comment POSIX.2
1596 @item _POSIX2_EXPR_NEST_MAX
1597 The most restrictive limit permitted by POSIX.2 for the maximum number
1598 of expressions nested within parenthesis when using the @code{expr} utility.
1599 Its value is @code{32}.
1601 @comment limits.h
1602 @comment POSIX.2
1603 @item _POSIX2_LINE_MAX
1604 The most restrictive limit permitted by POSIX.2 for the maximum size of
1605 a text line that the text utilities can handle.  Its value is
1606 @code{2048}.
1608 @comment limits.h
1609 @comment POSIX.2
1610 @item _POSIX2_EQUIV_CLASS_MAX
1611 The most restrictive limit permitted by POSIX.2 for the maximum number
1612 of weights that can be assigned to an entry of the @code{LC_COLLATE}
1613 category @samp{order} keyword in a locale definition.  Its value is
1614 @code{2}.  @Theglibc{} does not presently support locale
1615 definitions.
1616 @end table
1618 @node String Parameters
1619 @section String-Valued Parameters
1621 POSIX.2 defines a way to get string-valued parameters from the operating
1622 system with the function @code{confstr}:
1624 @comment unistd.h
1625 @comment POSIX.2
1626 @deftypefun size_t confstr (int @var{parameter}, char *@var{buf}, size_t @var{len})
1627 This function reads the value of a string-valued system parameter,
1628 storing the string into @var{len} bytes of memory space starting at
1629 @var{buf}.  The @var{parameter} argument should be one of the
1630 @samp{_CS_} symbols listed below.
1632 The normal return value from @code{confstr} is the length of the string
1633 value that you asked for.  If you supply a null pointer for @var{buf},
1634 then @code{confstr} does not try to store the string; it just returns
1635 its length.  A value of @code{0} indicates an error.
1637 If the string you asked for is too long for the buffer (that is, longer
1638 than @code{@var{len} - 1}), then @code{confstr} stores just that much
1639 (leaving room for the terminating null character).  You can tell that
1640 this has happened because @code{confstr} returns a value greater than or
1641 equal to @var{len}.
1643 The following @code{errno} error conditions are defined for this function:
1645 @table @code
1646 @item EINVAL
1647 The value of the @var{parameter} is invalid.
1648 @end table
1649 @end deftypefun
1651 Currently there is just one parameter you can read with @code{confstr}:
1653 @table @code
1654 @comment unistd.h
1655 @comment POSIX.2
1656 @item _CS_PATH
1657 This parameter's value is the recommended default path for searching for
1658 executable files.  This is the path that a user has by default just
1659 after logging in.
1661 @comment unistd.h
1662 @comment Unix98
1663 @item _CS_LFS_CFLAGS
1664 The returned string specifies which additional flags must be given to
1665 the C compiler if a source is compiled using the
1666 @code{_LARGEFILE_SOURCE} feature select macro; @pxref{Feature Test Macros}.
1668 @comment unistd.h
1669 @comment Unix98
1670 @item _CS_LFS_LDFLAGS
1671 The returned string specifies which additional flags must be given to
1672 the linker if a source is compiled using the
1673 @code{_LARGEFILE_SOURCE} feature select macro; @pxref{Feature Test Macros}.
1675 @comment unistd.h
1676 @comment Unix98
1677 @item _CS_LFS_LIBS
1678 The returned string specifies which additional libraries must be linked
1679 to the application if a source is compiled using the
1680 @code{_LARGEFILE_SOURCE} feature select macro; @pxref{Feature Test Macros}.
1682 @comment unistd.h
1683 @comment Unix98
1684 @item _CS_LFS_LINTFLAGS
1685 The returned string specifies which additional flags must be given to
1686 the lint tool if a source is compiled using the
1687 @code{_LARGEFILE_SOURCE} feature select macro; @pxref{Feature Test Macros}.
1689 @comment unistd.h
1690 @comment Unix98
1691 @item _CS_LFS64_CFLAGS
1692 The returned string specifies which additional flags must be given to
1693 the C compiler if a source is compiled using the
1694 @code{_LARGEFILE64_SOURCE} feature select macro; @pxref{Feature Test Macros}.
1696 @comment unistd.h
1697 @comment Unix98
1698 @item _CS_LFS64_LDFLAGS
1699 The returned string specifies which additional flags must be given to
1700 the linker if a source is compiled using the
1701 @code{_LARGEFILE64_SOURCE} feature select macro; @pxref{Feature Test Macros}.
1703 @comment unistd.h
1704 @comment Unix98
1705 @item _CS_LFS64_LIBS
1706 The returned string specifies which additional libraries must be linked
1707 to the application if a source is compiled using the
1708 @code{_LARGEFILE64_SOURCE} feature select macro; @pxref{Feature Test Macros}.
1710 @comment unistd.h
1711 @comment Unix98
1712 @item _CS_LFS64_LINTFLAGS
1713 The returned string specifies which additional flags must be given to
1714 the lint tool if a source is compiled using the
1715 @code{_LARGEFILE64_SOURCE} feature select macro; @pxref{Feature Test Macros}.
1716 @end table
1718 The way to use @code{confstr} without any arbitrary limit on string size
1719 is to call it twice: first call it to get the length, allocate the
1720 buffer accordingly, and then call @code{confstr} again to fill the
1721 buffer, like this:
1723 @smallexample
1724 @group
1725 char *
1726 get_default_path (void)
1728   size_t len = confstr (_CS_PATH, NULL, 0);
1729   char *buffer = (char *) xmalloc (len);
1731   if (confstr (_CS_PATH, buf, len + 1) == 0)
1732     @{
1733       free (buffer);
1734       return NULL;
1735     @}
1737   return buffer;
1739 @end group
1740 @end smallexample