(strncmp): Fix pastos from wcscmp description.
[kopensolaris-gnu/glibc.git] / manual / conf.texi
1 @node System Configuration, Cryptographic Functions, System Management, Top
2 @c %MENU% Parameters describing operating system limits
3 @chapter System Configuration Parameters
4
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}).
9
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.
19
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.
26
27 * Utility Limits::           Capacity limits of some POSIX.2 utility programs.
28 * Utility Minimums::         Minimum allowable values of those limits.
29
30 * String Parameters::        Getting the default search path.
31 @end menu
32
33 @node General Limits
34 @section General Capacity Limits
35 @cindex POSIX capacity limits
36 @cindex limits, POSIX
37 @cindex capacity limits, POSIX
38
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.
45
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}.
53
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}.
57
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
65
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
75
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
84
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
91
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
99
100 These limit macros are always defined in @file{limits.h}.
101
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.
107
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
114
115 @comment limits.h
116 @comment POSIX.1
117 @deftypevr Macro int 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.
121
122 This macro is defined in all POSIX systems because this limit is never
123 configurable.
124 @end deftypevr
125
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.
131
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.
138
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
142
143 @node System Options
144 @section Overall System Options
145 @cindex POSIX optional features
146 @cindex optional POSIX features
147
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 the GNU C library does not guarantee any of these
151 features is supported; it depends on the system you are using.
152
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}.
157
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}.
161
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
169
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
182
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}.
188
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}.  The GNU C library 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
197
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}.  The GNU C library never
203 defines this, because we don't know what the system has.
204 @end deftypevr
205
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.  The GNU C
211 library never defines this, because we don't know what the system has.
212 @end deftypevr
213
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.  The GNU C library never defines this, because
219 we don't know what the system has.
220 @end deftypevr
221
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}.  The GNU C library
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
231
232 @node Version Supported
233 @section Which Version of POSIX is Supported
234
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}.
241
242 @code{_POSIX_VERSION} is always defined (in @file{unistd.h}) in any
243 POSIX system.
244
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
252 The GNU C compiler predefines the symbol @code{__POSIX__} if the target
253 system is a POSIX system.  Provided you do not use any other compilers
254 on POSIX systems, testing @code{defined (__POSIX__)} will reliably
255 detect such systems.
256 @end deftypevr
257
258 @comment unistd.h
259 @comment POSIX.2
260 @deftypevr Macro {long int} _POSIX2_C_VERSION
261 This constant represents the version of the POSIX.2 standard which the
262 library and system kernel support.  We don't know what value this will
263 be for the first version of the POSIX.2 standard, because the value is
264 based on the year and month in which the standard is officially adopted.
265
266 The value of this symbol says nothing about the utilities installed on
267 the system.
268
269 @strong{Usage Note:} You can use this macro to tell whether a POSIX.1
270 system library supports POSIX.2 as well.  Any POSIX.1 system contains
271 @file{unistd.h}, so include that file and then test @code{defined
272 (_POSIX2_C_VERSION)}.
273 @end deftypevr
274
275 @node Sysconf
276 @section Using @code{sysconf}
277
278 When your system has configurable system limits, you can use the
279 @code{sysconf} function to find out the value that applies to any
280 particular machine.  The function and the associated @var{parameter}
281 constants are declared in the header file @file{unistd.h}.
282
283 @menu
284 * Sysconf Definition::        Detailed specifications of @code{sysconf}.
285 * Constants for Sysconf::     The list of parameters @code{sysconf} can read.
286 * Examples of Sysconf::       How to use @code{sysconf} and the parameter
287                                  macros properly together.
288 @end menu
289
290 @node Sysconf Definition
291 @subsection Definition of @code{sysconf}
292
293 @comment unistd.h
294 @comment POSIX.1
295 @deftypefun {long int} sysconf (int @var{parameter})
296 This function is used to inquire about runtime system parameters.  The
297 @var{parameter} argument should be one of the @samp{_SC_} symbols listed
298 below.
299
300 The normal return value from @code{sysconf} is the value you requested.
301 A value of @code{-1} is returned both if the implementation does not
302 impose a limit, and in case of an error.
303
304 The following @code{errno} error conditions are defined for this function:
305
306 @table @code
307 @item EINVAL
308 The value of the @var{parameter} is invalid.
309 @end table
310 @end deftypefun
311
312 @node Constants for Sysconf
313 @subsection Constants for @code{sysconf} Parameters
314
315 Here are the symbolic constants for use as the @var{parameter} argument
316 to @code{sysconf}.  The values are all integer constants (more
317 specifically, enumeration type values).
318
319 @vtable @code
320 @comment unistd.h
321 @comment POSIX.1
322 @item _SC_ARG_MAX
323 Inquire about the parameter corresponding to @code{ARG_MAX}.
324
325 @comment unistd.h
326 @comment POSIX.1
327 @item _SC_CHILD_MAX
328 Inquire about the parameter corresponding to @code{CHILD_MAX}.
329
330 @comment unistd.h
331 @comment POSIX.1
332 @item _SC_OPEN_MAX
333 Inquire about the parameter corresponding to @code{OPEN_MAX}.
334
335 @comment unistd.h
336 @comment POSIX.1
337 @item _SC_STREAM_MAX
338 Inquire about the parameter corresponding to @code{STREAM_MAX}.
339
340 @comment unistd.h
341 @comment POSIX.1
342 @item _SC_TZNAME_MAX
343 Inquire about the parameter corresponding to @code{TZNAME_MAX}.
344
345 @comment unistd.h
346 @comment POSIX.1
347 @item _SC_NGROUPS_MAX
348 Inquire about the parameter corresponding to @code{NGROUPS_MAX}.
349
350 @comment unistd.h
351 @comment POSIX.1
352 @item _SC_JOB_CONTROL
353 Inquire about the parameter corresponding to @code{_POSIX_JOB_CONTROL}.
354
355 @comment unistd.h
356 @comment POSIX.1
357 @item _SC_SAVED_IDS
358 Inquire about the parameter corresponding to @code{_POSIX_SAVED_IDS}.
359
360 @comment unistd.h
361 @comment POSIX.1
362 @item _SC_VERSION
363 Inquire about the parameter corresponding to @code{_POSIX_VERSION}.
364
365 @comment unistd.h
366 @comment POSIX.1
367 @item _SC_CLK_TCK
368 Inquire about the parameter corresponding to @code{CLOCKS_PER_SEC};
369 @pxref{CPU Time}.
370
371 @comment unistd.h
372 @comment GNU
373 @item _SC_CHARCLASS_NAME_MAX
374 Inquire about the parameter corresponding to maximal length allowed for
375 a character class name in an extended locale specification.  These
376 extensions are not yet standardized and so this option is not standardized
377 as well.
378
379 @comment unistdh.h
380 @comment POSIX.1
381 @item _SC_REALTIME_SIGNALS
382 Inquire about the parameter corresponding to @code{_POSIX_REALTIME_SIGNALS}.
383
384 @comment unistd.h
385 @comment POSIX.1
386 @item _SC_PRIORITY_SCHEDULING
387 Inquire about the parameter corresponding to @code{_POSIX_PRIORITY_SCHEDULING}.
388
389 @comment unistd.h
390 @comment POSIX.1
391 @item _SC_TIMERS
392 Inquire about the parameter corresponding to @code{_POSIX_TIMERS}.
393
394 @comment unistd.h
395 @comment POSIX.1
396 @item _SC_ASYNCHRONOUS_IO
397 Inquire about the parameter corresponding to @code{_POSIX_ASYNCHRONOUS_IO}.
398
399 @comment unistd.h
400 @comment POSIX.1
401 @item _SC_PRIORITIZED_IO
402 Inquire about the parameter corresponding to @code{_POSIX_PRIORITIZED_IO}.
403
404 @comment unistd.h
405 @comment POSIX.1
406 @item _SC_SYNCHRONIZED_IO
407 Inquire about the parameter corresponding to @code{_POSIX_SYNCHRONIZED_IO}.
408
409 @comment unistd.h
410 @comment POSIX.1
411 @item _SC_FSYNC
412 Inquire about the parameter corresponding to @code{_POSIX_FSYNC}.
413
414 @comment unistd.h
415 @comment POSIX.1
416 @item _SC_MAPPED_FILES
417 Inquire about the parameter corresponding to @code{_POSIX_MAPPED_FILES}.
418
419 @comment unistd.h
420 @comment POSIX.1
421 @item _SC_MEMLOCK
422 Inquire about the parameter corresponding to @code{_POSIX_MEMLOCK}.
423
424 @comment unistd.h
425 @comment POSIX.1
426 @item _SC_MEMLOCK_RANGE
427 Inquire about the parameter corresponding to @code{_POSIX_MEMLOCK_RANGE}.
428
429 @comment unistd.h
430 @comment POSIX.1
431 @item _SC_MEMORY_PROTECTION
432 Inquire about the parameter corresponding to @code{_POSIX_MEMORY_PROTECTION}.
433
434 @comment unistd.h
435 @comment POSIX.1
436 @item _SC_MESSAGE_PASSING
437 Inquire about the parameter corresponding to @code{_POSIX_MESSAGE_PASSING}.
438
439 @comment unistd.h
440 @comment POSIX.1
441 @item _SC_SEMAPHORES
442 Inquire about the parameter corresponding to @code{_POSIX_SEMAPHORES}.
443
444 @comment unistd.h
445 @comment POSIX.1
446 @item _SC_SHARED_MEMORY_OBJECTS
447 Inquire about the parameter corresponding to@*
448 @code{_POSIX_SHARED_MEMORY_OBJECTS}.
449
450 @comment unistd.h
451 @comment POSIX.1
452 @item _SC_AIO_LISTIO_MAX
453 Inquire about the parameter corresponding to @code{_POSIX_AIO_LISTIO_MAX}.
454
455 @comment unistd.h
456 @comment POSIX.1
457 @item _SC_AIO_MAX
458 Inquire about the parameter corresponding to @code{_POSIX_AIO_MAX}.
459
460 @comment unistd.h
461 @comment POSIX.1
462 @item _SC_AIO_PRIO_DELTA_MAX
463 Inquire the value by which a process can decrease its asynchronous I/O
464 priority level from its own scheduling priority.  This corresponds to the
465 run-time invariant value @code{AIO_PRIO_DELTA_MAX}.
466
467 @comment unistd.h
468 @comment POSIX.1
469 @item _SC_DELAYTIMER_MAX
470 Inquire about the parameter corresponding to @code{_POSIX_DELAYTIMER_MAX}.
471
472 @comment unistd.h
473 @comment POSIX.1
474 @item _SC_MQ_OPEN_MAX
475 Inquire about the parameter corresponding to @code{_POSIX_MQ_OPEN_MAX}.
476
477 @comment unistd.h
478 @comment POSIX.1
479 @item _SC_MQ_PRIO_MAX
480 Inquire about the parameter corresponding to @code{_POSIX_MQ_PRIO_MAX}.
481
482 @comment unistd.h
483 @comment POSIX.1
484 @item _SC_RTSIG_MAX
485 Inquire about the parameter corresponding to @code{_POSIX_RTSIG_MAX}.
486
487 @comment unistd.h
488 @comment POSIX.1
489 @item _SC_SEM_NSEMS_MAX
490 Inquire about the parameter corresponding to @code{_POSIX_SEM_NSEMS_MAX}.
491
492 @comment unistd.h
493 @comment POSIX.1
494 @item _SC_SEM_VALUE_MAX
495 Inquire about the parameter corresponding to @code{_POSIX_SEM_VALUE_MAX}.
496
497 @comment unistd.h
498 @comment POSIX.1
499 @item _SC_SIGQUEUE_MAX
500 Inquire about the parameter corresponding to @code{_POSIX_SIGQUEUE_MAX}.
501
502 @comment unistd.h
503 @comment POSIX.1
504 @item _SC_TIMER_MAX
505 Inquire about the parameter corresponding to @code{_POSIX_TIMER_MAX}.
506
507 @comment unistd.h
508 @comment POSIX.1g
509 @item _SC_PII
510 Inquire about the parameter corresponding to @code{_POSIX_PII}.
511
512 @comment unistd.h
513 @comment POSIX.1g
514 @item _SC_PII_XTI
515 Inquire about the parameter corresponding to @code{_POSIX_PII_XTI}.
516
517 @comment unistd.h
518 @comment POSIX.1g
519 @item _SC_PII_SOCKET
520 Inquire about the parameter corresponding to @code{_POSIX_PII_SOCKET}.
521
522 @comment unistd.h
523 @comment POSIX.1g
524 @item _SC_PII_INTERNET
525 Inquire about the parameter corresponding to @code{_POSIX_PII_INTERNET}.
526
527 @comment unistd.h
528 @comment POSIX.1g
529 @item _SC_PII_OSI
530 Inquire about the parameter corresponding to @code{_POSIX_PII_OSI}.
531
532 @comment unistd.h
533 @comment POSIX.1g
534 @item _SC_SELECT
535 Inquire about the parameter corresponding to @code{_POSIX_SELECT}.
536
537 @comment unistd.h
538 @comment POSIX.1g
539 @item _SC_UIO_MAXIOV
540 Inquire about the parameter corresponding to @code{_POSIX_UIO_MAXIOV}.
541
542 @comment unistd.h
543 @comment POSIX.1g
544 @item _SC_PII_INTERNET_STREAM
545 Inquire about the parameter corresponding to @code{_POSIX_PII_INTERNET_STREAM}.
546
547 @comment unistd.h
548 @comment POSIX.1g
549 @item _SC_PII_INTERNET_DGRAM
550 Inquire about the parameter corresponding to @code{_POSIX_PII_INTERNET_DGRAM}.
551
552 @comment unistd.h
553 @comment POSIX.1g
554 @item _SC_PII_OSI_COTS
555 Inquire about the parameter corresponding to @code{_POSIX_PII_OSI_COTS}.
556
557 @comment unistd.h
558 @comment POSIX.1g
559 @item _SC_PII_OSI_CLTS
560 Inquire about the parameter corresponding to @code{_POSIX_PII_OSI_CLTS}.
561
562 @comment unistd.h
563 @comment POSIX.1g
564 @item _SC_PII_OSI_M
565 Inquire about the parameter corresponding to @code{_POSIX_PII_OSI_M}.
566
567 @comment unistd.h
568 @comment POSIX.1g
569 @item _SC_T_IOV_MAX
570 Inquire the value of the value associated with the @code{T_IOV_MAX}
571 variable.
572
573 @comment unistd.h
574 @comment POSIX.1
575 @item _SC_THREADS
576 Inquire about the parameter corresponding to @code{_POSIX_THREADS}.
577
578 @comment unistd.h
579 @comment POSIX.1
580 @item _SC_THREAD_SAFE_FUNCTIONS
581 Inquire about the parameter corresponding to@*
582 @code{_POSIX_THREAD_SAFE_FUNCTIONS}.
583
584 @comment unistd.h
585 @comment POSIX.1
586 @item _SC_GETGR_R_SIZE_MAX
587 Inquire about the parameter corresponding to @code{_POSIX_GETGR_R_SIZE_MAX}.
588
589 @comment unistd.h
590 @comment POSIX.1
591 @item _SC_GETPW_R_SIZE_MAX
592 Inquire about the parameter corresponding to @code{_POSIX_GETPW_R_SIZE_MAX}.
593
594 @comment unistd.h
595 @comment POSIX.1
596 @item _SC_LOGIN_NAME_MAX
597 Inquire about the parameter corresponding to @code{_POSIX_LOGIN_NAME_MAX}.
598
599 @comment unistd.h
600 @comment POSIX.1
601 @item _SC_TTY_NAME_MAX
602 Inquire about the parameter corresponding to @code{_POSIX_TTY_NAME_MAX}.
603
604 @comment unistd.h
605 @comment POSIX.1
606 @item _SC_THREAD_DESTRUCTOR_ITERATIONS
607 Inquire about the parameter corresponding to
608 @code{_POSIX_THREAD_DESTRUCTOR_ITERATIONS}.
609
610 @comment unistd.h
611 @comment POSIX.1
612 @item _SC_THREAD_KEYS_MAX
613 Inquire about the parameter corresponding to @code{_POSIX_THREAD_KEYS_MAX}.
614
615 @comment unistd.h
616 @comment POSIX.1
617 @item _SC_THREAD_STACK_MIN
618 Inquire about the parameter corresponding to @code{_POSIX_THREAD_STACK_MIN}.
619
620 @comment unistd.h
621 @comment POSIX.1
622 @item _SC_THREAD_THREADS_MAX
623 Inquire about the parameter corresponding to @code{_POSIX_THREAD_THREADS_MAX}.
624
625 @comment unistd.h
626 @comment POSIX.1
627 @item _SC_THREAD_ATTR_STACKADDR
628 Inquire about the parameter corresponding to@*a
629 @code{_POSIX_THREAD_ATTR_STACKADDR}.
630
631 @comment unistd.h
632 @comment POSIX.1
633 @item _SC_THREAD_ATTR_STACKSIZE
634 Inquire about the parameter corresponding to@*
635 @code{_POSIX_THREAD_ATTR_STACKSIZE}.
636
637 @comment unistd.h
638 @comment POSIX.1
639 @item _SC_THREAD_PRIORITY_SCHEDULING
640 Inquire about the parameter corresponding to
641 @code{_POSIX_THREAD_PRIORITY_SCHEDULING}.
642
643 @comment unistd.h
644 @comment POSIX.1
645 @item _SC_THREAD_PRIO_INHERIT
646 Inquire about the parameter corresponding to @code{_POSIX_THREAD_PRIO_INHERIT}.
647
648 @comment unistd.h
649 @comment POSIX.1
650 @item _SC_THREAD_PRIO_PROTECT
651 Inquire about the parameter corresponding to @code{_POSIX_THREAD_PRIO_PROTECT}.
652
653 @comment unistd.h
654 @comment POSIX.1
655 @item _SC_THREAD_PROCESS_SHARED
656 Inquire about the parameter corresponding to
657 @code{_POSIX_THREAD_PROCESS_SHARED}.
658
659 @comment unistd.h
660 @comment POSIX.2
661 @item _SC_2_C_DEV
662 Inquire about whether the system has the POSIX.2 C compiler command,
663 @code{c89}.
664
665 @comment unistd.h
666 @comment POSIX.2
667 @item _SC_2_FORT_DEV
668 Inquire about whether the system has the POSIX.2 Fortran compiler
669 command, @code{fort77}.
670
671 @comment unistd.h
672 @comment POSIX.2
673 @item _SC_2_FORT_RUN
674 Inquire about whether the system has the POSIX.2 @code{asa} command to
675 interpret Fortran carriage control.
676
677 @comment unistd.h
678 @comment POSIX.2
679 @item _SC_2_LOCALEDEF
680 Inquire about whether the system has the POSIX.2 @code{localedef}
681 command.
682
683 @comment unistd.h
684 @comment POSIX.2
685 @item _SC_2_SW_DEV
686 Inquire about whether the system has the POSIX.2 commands @code{ar},
687 @code{make}, and @code{strip}.
688
689 @comment unistd.h
690 @comment POSIX.2
691 @item _SC_BC_BASE_MAX
692 Inquire about the maximum value of @code{obase} in the @code{bc}
693 utility.
694
695 @comment unistd.h
696 @comment POSIX.2
697 @item _SC_BC_DIM_MAX
698 Inquire about the maximum size of an array in the @code{bc}
699 utility.
700
701 @comment unistd.h
702 @comment POSIX.2
703 @item _SC_BC_SCALE_MAX
704 Inquire about the maximum value of @code{scale} in the @code{bc}
705 utility.
706
707 @comment unistd.h
708 @comment POSIX.2
709 @item _SC_BC_STRING_MAX
710 Inquire about the maximum size of a string constant in the
711 @code{bc} utility.
712
713 @comment unistd.h
714 @comment POSIX.2
715 @item _SC_COLL_WEIGHTS_MAX
716 Inquire about the maximum number of weights that can necessarily
717 be used in defining the collating sequence for a locale.
718
719 @comment unistd.h
720 @comment POSIX.2
721 @item _SC_EXPR_NEST_MAX
722 Inquire about the maximum number of expressions nested within
723 parentheses when using the @code{expr} utility.
724
725 @comment unistd.h
726 @comment POSIX.2
727 @item _SC_LINE_MAX
728 Inquire about the maximum size of a text line that the POSIX.2 text
729 utilities can handle.
730
731 @comment unistd.h
732 @comment POSIX.2
733 @item _SC_EQUIV_CLASS_MAX
734 Inquire about the maximum number of weights that can be assigned to an
735 entry of the @code{LC_COLLATE} category @samp{order} keyword in a locale
736 definition.  The GNU C library does not presently support locale
737 definitions.
738
739 @comment unistd.h
740 @comment POSIX.2
741 @item _SC_VERSION
742 Inquire about the version number of POSIX.1 that the library and kernel
743 support.
744
745 @comment unistd.h
746 @comment POSIX.2
747 @item _SC_2_VERSION
748 Inquire about the version number of POSIX.2 that the system utilities
749 support.
750
751 @comment unistd.h
752 @comment GNU
753 @item _SC_PAGESIZE
754 Inquire about the virtual memory page size of the machine.
755 @code{getpagesize} returns the same value (@pxref{Query Memory Parameters}).
756
757 @comment unistd.h
758 @comment GNU
759 @item _SC_NPROCESSORS_CONF
760 Inquire about the number of configured processors.
761
762 @comment unistd.h
763 @comment GNU
764 @item _SC_NPROCESSORS_ONLN
765 Inquire about the number of processors online.
766
767 @comment unistd.h
768 @comment GNU
769 @item _SC_PHYS_PAGES
770 Inquire about the number of physical pages in the system.
771
772 @comment unistd.h
773 @comment GNU
774 @item _SC_AVPHYS_PAGES
775 Inquire about the number of available physical pages in the system.
776
777 @comment unistd.h
778 @comment GNU
779 @item _SC_ATEXIT_MAX
780 Inquire about the number of functions which can be registered as termination
781 functions for @code{atexit}; @pxref{Cleanups on Exit}.
782
783 @comment unistd.h
784 @comment X/Open
785 @item _SC_XOPEN_VERSION
786 Inquire about the parameter corresponding to @code{_XOPEN_VERSION}.
787
788 @comment unistd.h
789 @comment X/Open
790 @item _SC_XOPEN_XCU_VERSION
791 Inquire about the parameter corresponding to @code{_XOPEN_XCU_VERSION}.
792
793 @comment unistd.h
794 @comment X/Open
795 @item _SC_XOPEN_UNIX
796 Inquire about the parameter corresponding to @code{_XOPEN_UNIX}.
797
798 @comment unistd.h
799 @comment X/Open
800 @item _SC_XOPEN_REALTIME
801 Inquire about the parameter corresponding to @code{_XOPEN_REALTIME}.
802
803 @comment unistd.h
804 @comment X/Open
805 @item _SC_XOPEN_REALTIME_THREADS
806 Inquire about the parameter corresponding to @code{_XOPEN_REALTIME_THREADS}.
807
808 @comment unistd.h
809 @comment X/Open
810 @item _SC_XOPEN_LEGACY
811 Inquire about the parameter corresponding to @code{_XOPEN_LEGACY}.
812
813 @comment unistd.h
814 @comment X/Open
815 @item _SC_XOPEN_CRYPT
816 Inquire about the parameter corresponding to @code{_XOPEN_CRYPT}.
817
818 @comment unistd.h
819 @comment X/Open
820 @item _SC_XOPEN_ENH_I18N
821 Inquire about the parameter corresponding to @code{_XOPEN_ENH_I18N}.
822
823 @comment unistd.h
824 @comment X/Open
825 @item _SC_XOPEN_SHM
826 Inquire about the parameter corresponding to @code{_XOPEN_SHM}.
827
828 @comment unistd.h
829 @comment X/Open
830 @item _SC_XOPEN_XPG2
831 Inquire about the parameter corresponding to @code{_XOPEN_XPG2}.
832
833 @comment unistd.h
834 @comment X/Open
835 @item _SC_XOPEN_XPG3
836 Inquire about the parameter corresponding to @code{_XOPEN_XPG3}.
837
838 @comment unistd.h
839 @comment X/Open
840 @item _SC_XOPEN_XPG4
841 Inquire about the parameter corresponding to @code{_XOPEN_XPG4}.
842
843 @comment unistd.h
844 @comment X/Open
845 @item _SC_CHAR_BIT
846 Inquire about the number of bits in a variable of type @code{char}.
847
848 @comment unistd.h
849 @comment X/Open
850 @item _SC_CHAR_MAX
851 Inquire about the maximum value which can be stored in a variable of type
852 @code{char}.
853
854 @comment unistd.h
855 @comment X/Open
856 @item _SC_CHAR_MIN
857 Inquire about the minimum value which can be stored in a variable of type
858 @code{char}.
859
860 @comment unistd.h
861 @comment X/Open
862 @item _SC_INT_MAX
863 Inquire about the maximum value which can be stored in a variable of type
864 @code{int}.
865
866 @comment unistd.h
867 @comment X/Open
868 @item _SC_INT_MIN
869 Inquire about the minimum value which can be stored in a variable of type
870 @code{int}.
871
872 @comment unistd.h
873 @comment X/Open
874 @item _SC_LONG_BIT
875 Inquire about the number of bits in a variable of type @code{long int}.
876
877 @comment unistd.h
878 @comment X/Open
879 @item _SC_WORD_BIT
880 Inquire about the number of bits in a variable of a register word.
881
882 @comment unistd.h
883 @comment X/Open
884 @item _SC_MB_LEN_MAX
885 Inquire the maximum length of a multi-byte representation of a wide
886 character value.
887
888 @comment unistd.h
889 @comment X/Open
890 @item _SC_NZERO
891 Inquire about the value used to internally represent the zero priority level for
892 the process execution.
893
894 @comment unistd.h
895 @comment X/Open
896 @item SC_SSIZE_MAX
897 Inquire about the maximum value which can be stored in a variable of type
898 @code{ssize_t}.
899
900 @comment unistd.h
901 @comment X/Open
902 @item _SC_SCHAR_MAX
903 Inquire about the maximum value which can be stored in a variable of type
904 @code{signed char}.
905
906 @comment unistd.h
907 @comment X/Open
908 @item _SC_SCHAR_MIN
909 Inquire about the minimum value which can be stored in a variable of type
910 @code{signed char}.
911
912 @comment unistd.h
913 @comment X/Open
914 @item _SC_SHRT_MAX
915 Inquire about the maximum value which can be stored in a variable of type
916 @code{short int}.
917
918 @comment unistd.h
919 @comment X/Open
920 @item _SC_SHRT_MIN
921 Inquire about the minimum value which can be stored in a variable of type
922 @code{short int}.
923
924 @comment unistd.h
925 @comment X/Open
926 @item _SC_UCHAR_MAX
927 Inquire about the maximum value which can be stored in a variable of type
928 @code{unsigned char}.
929
930 @comment unistd.h
931 @comment X/Open
932 @item _SC_UINT_MAX
933 Inquire about the maximum value which can be stored in a variable of type
934 @code{unsigned int}.
935
936 @comment unistd.h
937 @comment X/Open
938 @item _SC_ULONG_MAX
939 Inquire about the maximum value which can be stored in a variable of type
940 @code{unsigned long int}.
941
942 @comment unistd.h
943 @comment X/Open
944 @item _SC_USHRT_MAX
945 Inquire about the maximum value which can be stored in a variable of type
946 @code{unsigned short int}.
947
948 @comment unistd.h
949 @comment X/Open
950 @item _SC_NL_ARGMAX
951 Inquire about the parameter corresponding to @code{NL_ARGMAX}.
952
953 @comment unistd.h
954 @comment X/Open
955 @item _SC_NL_LANGMAX
956 Inquire about the parameter corresponding to @code{NL_LANGMAX}.
957
958 @comment unistd.h
959 @comment X/Open
960 @item _SC_NL_MSGMAX
961 Inquire about the parameter corresponding to @code{NL_MSGMAX}.
962
963 @comment unistd.h
964 @comment X/Open
965 @item _SC_NL_NMAX
966 Inquire about  the parameter corresponding to @code{NL_NMAX}.
967
968 @comment unistd.h
969 @comment X/Open
970 @item _SC_NL_SETMAX
971 Inquire about the parameter corresponding to @code{NL_SETMAX}.
972
973 @comment unistd.h
974 @comment X/Open
975 @item _SC_NL_TEXTMAX
976 Inquire about the parameter corresponding to @code{NL_TEXTMAX}.
977 @end vtable
978
979 @node Examples of Sysconf
980 @subsection Examples of @code{sysconf}
981
982 We recommend that you first test for a macro definition for the
983 parameter you are interested in, and call @code{sysconf} only if the
984 macro is not defined.  For example, here is how to test whether job
985 control is supported:
986
987 @smallexample
988 @group
989 int
990 have_job_control (void)
991 @{
992 #ifdef _POSIX_JOB_CONTROL
993   return 1;
994 #else
995   int value = sysconf (_SC_JOB_CONTROL);
996   if (value < 0)
997     /* @r{If the system is that badly wedged,}
998        @r{there's no use trying to go on.}  */
999     fatal (strerror (errno));
1000   return value;
1001 #endif
1002 @}
1003 @end group
1004 @end smallexample
1005
1006 Here is how to get the value of a numeric limit:
1007
1008 @smallexample
1009 int
1010 get_child_max ()
1011 @{
1012 #ifdef CHILD_MAX
1013   return CHILD_MAX;
1014 #else
1015   int value = sysconf (_SC_CHILD_MAX);
1016   if (value < 0)
1017     fatal (strerror (errno));
1018   return value;
1019 #endif
1020 @}
1021 @end smallexample
1022
1023 @node Minimums
1024 @section Minimum Values for General Capacity Limits
1025
1026 Here are the names for the POSIX minimum upper bounds for the system
1027 limit parameters.  The significance of these values is that you can
1028 safely push to these limits without checking whether the particular
1029 system you are using can go that far.
1030
1031 @table @code
1032 @comment limits.h
1033 @comment POSIX.1
1034 @item _POSIX_AIO_LISTIO_MAX
1035 The most restrictive limit permitted by POSIX for the maximum number of
1036 I/O operations that can be specified in a list I/O call.  The value of
1037 this constant is @code{2}; thus you can add up to two new entries
1038 of the list of outstanding operations.
1039
1040 @comment limits.h
1041 @comment POSIX.1
1042 @item _POSIX_AIO_MAX
1043 The most restrictive limit permitted by POSIX for the maximum number of
1044 outstanding asynchronous I/O operations.  The value of this constant is
1045 @code{1}.  So you cannot expect that you can issue more than one
1046 operation and immediately continue with the normal work, receiving the
1047 notifications asynchronously.
1048
1049 @comment limits.h
1050 @comment POSIX.1
1051 @item _POSIX_ARG_MAX
1052 The value of this macro is the most restrictive limit permitted by POSIX
1053 for the maximum combined length of the @var{argv} and @var{environ}
1054 arguments that can be passed to the @code{exec} functions.
1055 Its value is @code{4096}.
1056
1057 @comment limits.h
1058 @comment POSIX.1
1059 @item _POSIX_CHILD_MAX
1060 The value of this macro is the most restrictive limit permitted by POSIX
1061 for the maximum number of simultaneous processes per real user ID.  Its
1062 value is @code{6}.
1063
1064 @comment limits.h
1065 @comment POSIX.1
1066 @item _POSIX_NGROUPS_MAX
1067 The value of this macro is the most restrictive limit permitted by POSIX
1068 for the maximum number of supplementary group IDs per process.  Its
1069 value is @code{0}.
1070
1071 @comment limits.h
1072 @comment POSIX.1
1073 @item _POSIX_OPEN_MAX
1074 The value of this macro is the most restrictive limit permitted by POSIX
1075 for the maximum number of files that a single process can have open
1076 simultaneously.  Its value is @code{16}.
1077
1078 @comment limits.h
1079 @comment POSIX.1
1080 @item _POSIX_SSIZE_MAX
1081 The value of this macro is the most restrictive limit permitted by POSIX
1082 for the maximum value that can be stored in an object of type
1083 @code{ssize_t}.  Its value is @code{32767}.
1084
1085 @comment limits.h
1086 @comment POSIX.1
1087 @item _POSIX_STREAM_MAX
1088 The value of this macro is the most restrictive limit permitted by POSIX
1089 for the maximum number of streams that a single process can have open
1090 simultaneously.  Its value is @code{8}.
1091
1092 @comment limits.h
1093 @comment POSIX.1
1094 @item _POSIX_TZNAME_MAX
1095 The value of this macro is the most restrictive limit permitted by POSIX
1096 for the maximum length of a time zone name.  Its value is @code{3}.
1097
1098 @comment limits.h
1099 @comment POSIX.2
1100 @item _POSIX2_RE_DUP_MAX
1101 The value of this macro is the most restrictive limit permitted by POSIX
1102 for the numbers used in the @samp{\@{@var{min},@var{max}\@}} construct
1103 in a regular expression.  Its value is @code{255}.
1104 @end table
1105
1106 @node Limits for Files
1107 @section Limits on File System Capacity
1108
1109 The POSIX.1 standard specifies a number of parameters that describe the
1110 limitations of the file system.  It's possible for the system to have a
1111 fixed, uniform limit for a parameter, but this isn't the usual case.  On
1112 most systems, it's possible for different file systems (and, for some
1113 parameters, even different files) to have different maximum limits.  For
1114 example, this is very likely if you use NFS to mount some of the file
1115 systems from other machines.
1116
1117 @pindex limits.h
1118 Each of the following macros is defined in @file{limits.h} only if the
1119 system has a fixed, uniform limit for the parameter in question.  If the
1120 system allows different file systems or files to have different limits,
1121 then the macro is undefined; use @code{pathconf} or @code{fpathconf} to
1122 find out the limit that applies to a particular file.  @xref{Pathconf}.
1123
1124 Each parameter also has another macro, with a name starting with
1125 @samp{_POSIX}, which gives the lowest value that the limit is allowed to
1126 have on @emph{any} POSIX system.  @xref{File Minimums}.
1127
1128 @cindex limits, link count of files
1129 @comment limits.h
1130 @comment POSIX.1
1131 @deftypevr Macro int LINK_MAX
1132 The uniform system limit (if any) for the number of names for a given
1133 file.  @xref{Hard Links}.
1134 @end deftypevr
1135
1136 @cindex limits, terminal input queue
1137 @comment limits.h
1138 @comment POSIX.1
1139 @deftypevr Macro int MAX_CANON
1140 The uniform system limit (if any) for the amount of text in a line of
1141 input when input editing is enabled.  @xref{Canonical or Not}.
1142 @end deftypevr
1143
1144 @comment limits.h
1145 @comment POSIX.1
1146 @deftypevr Macro int MAX_INPUT
1147 The uniform system limit (if any) for the total number of characters
1148 typed ahead as input.  @xref{I/O Queues}.
1149 @end deftypevr
1150
1151 @cindex limits, file name length
1152 @comment limits.h
1153 @comment POSIX.1
1154 @deftypevr Macro int NAME_MAX
1155 The uniform system limit (if any) for the length of a file name component.
1156 @end deftypevr
1157
1158 @comment limits.h
1159 @comment POSIX.1
1160 @deftypevr Macro int PATH_MAX
1161 The uniform system limit (if any) for the length of an entire file name (that
1162 is, the argument given to system calls such as @code{open}).
1163 @end deftypevr
1164
1165 @cindex limits, pipe buffer size
1166 @comment limits.h
1167 @comment POSIX.1
1168 @deftypevr Macro int PIPE_BUF
1169 The uniform system limit (if any) for the number of bytes that can be
1170 written atomically to a pipe.  If multiple processes are writing to the
1171 same pipe simultaneously, output from different processes might be
1172 interleaved in chunks of this size.  @xref{Pipes and FIFOs}.
1173 @end deftypevr
1174
1175 These are alternative macro names for some of the same information.
1176
1177 @comment dirent.h
1178 @comment BSD
1179 @deftypevr Macro int MAXNAMLEN
1180 This is the BSD name for @code{NAME_MAX}.  It is defined in
1181 @file{dirent.h}.
1182 @end deftypevr
1183
1184 @comment stdio.h
1185 @comment ISO
1186 @deftypevr Macro int FILENAME_MAX
1187 The value of this macro is an integer constant expression that
1188 represents the maximum length of a file name string.  It is defined in
1189 @file{stdio.h}.
1190
1191 Unlike @code{PATH_MAX}, this macro is defined even if there is no actual
1192 limit imposed.  In such a case, its value is typically a very large
1193 number.  @strong{This is always the case on the GNU system.}
1194
1195 @strong{Usage Note:} Don't use @code{FILENAME_MAX} as the size of an
1196 array in which to store a file name!  You can't possibly make an array
1197 that big!  Use dynamic allocation (@pxref{Memory Allocation}) instead.
1198 @end deftypevr
1199
1200 @node Options for Files
1201 @section Optional Features in File Support
1202
1203 POSIX defines certain system-specific options in the system calls for
1204 operating on files.  Some systems support these options and others do
1205 not.  Since these options are provided in the kernel, not in the
1206 library, simply using the GNU C library does not guarantee that any of these
1207 features is supported; it depends on the system you are using.  They can
1208 also vary between file systems on a single machine.
1209
1210 @pindex unistd.h
1211 This section describes the macros you can test to determine whether a
1212 particular option is supported on your machine.  If a given macro is
1213 defined in @file{unistd.h}, then its value says whether the
1214 corresponding feature is supported.  (A value of @code{-1} indicates no;
1215 any other value indicates yes.)  If the macro is undefined, it means
1216 particular files may or may not support the feature.
1217
1218 Since all the machines that support the GNU C library also support NFS,
1219 one can never make a general statement about whether all file systems
1220 support the @code{_POSIX_CHOWN_RESTRICTED} and @code{_POSIX_NO_TRUNC}
1221 features.  So these names are never defined as macros in the GNU C
1222 library.
1223
1224 @comment unistd.h
1225 @comment POSIX.1
1226 @deftypevr Macro int _POSIX_CHOWN_RESTRICTED
1227 If this option is in effect, the @code{chown} function is restricted so
1228 that the only changes permitted to nonprivileged processes is to change
1229 the group owner of a file to either be the effective group ID of the
1230 process, or one of its supplementary group IDs.  @xref{File Owner}.
1231 @end deftypevr
1232
1233 @comment unistd.h
1234 @comment POSIX.1
1235 @deftypevr Macro int _POSIX_NO_TRUNC
1236 If this option is in effect, file name components longer than
1237 @code{NAME_MAX} generate an @code{ENAMETOOLONG} error.  Otherwise, file
1238 name components that are too long are silently truncated.
1239 @end deftypevr
1240
1241 @comment unistd.h
1242 @comment POSIX.1
1243 @deftypevr Macro {unsigned char} _POSIX_VDISABLE
1244 This option is only meaningful for files that are terminal devices.
1245 If it is enabled, then handling for special control characters can
1246 be disabled individually.  @xref{Special Characters}.
1247 @end deftypevr
1248
1249 @pindex unistd.h
1250 If one of these macros is undefined, that means that the option might be
1251 in effect for some files and not for others.  To inquire about a
1252 particular file, call @code{pathconf} or @code{fpathconf}.
1253 @xref{Pathconf}.
1254
1255 @node File Minimums
1256 @section Minimum Values for File System Limits
1257
1258 Here are the names for the POSIX minimum upper bounds for some of the
1259 above parameters.  The significance of these values is that you can
1260 safely push to these limits without checking whether the particular
1261 system you are using can go that far.  In most cases GNU systems do not
1262 have these strict limitations.  The actual limit should be requested if
1263 necessary.
1264
1265 @table @code
1266 @comment limits.h
1267 @comment POSIX.1
1268 @item _POSIX_LINK_MAX
1269 The most restrictive limit permitted by POSIX for the maximum value of a
1270 file's link count.  The value of this constant is @code{8}; thus, you
1271 can always make up to eight names for a file without running into a
1272 system limit.
1273
1274 @comment limits.h
1275 @comment POSIX.1
1276 @item _POSIX_MAX_CANON
1277 The most restrictive limit permitted by POSIX for the maximum number of
1278 bytes in a canonical input line from a terminal device.  The value of
1279 this constant is @code{255}.
1280
1281 @comment limits.h
1282 @comment POSIX.1
1283 @item _POSIX_MAX_INPUT
1284 The most restrictive limit permitted by POSIX for the maximum number of
1285 bytes in a terminal device input queue (or typeahead buffer).
1286 @xref{Input Modes}.  The value of this constant is @code{255}.
1287
1288 @comment limits.h
1289 @comment POSIX.1
1290 @item _POSIX_NAME_MAX
1291 The most restrictive limit permitted by POSIX for the maximum number of
1292 bytes in a file name component.  The value of this constant is
1293 @code{14}.
1294
1295 @comment limits.h
1296 @comment POSIX.1
1297 @item _POSIX_PATH_MAX
1298 The most restrictive limit permitted by POSIX for the maximum number of
1299 bytes in a file name.  The value of this constant is @code{256}.
1300
1301 @comment limits.h
1302 @comment POSIX.1
1303 @item _POSIX_PIPE_BUF
1304 The most restrictive limit permitted by POSIX for the maximum number of
1305 bytes that can be written atomically to a pipe.  The value of this
1306 constant is @code{512}.
1307
1308 @comment limits.h
1309 @comment POSIX.1
1310 @item SYMLINK_MAX
1311 Maximum number of bytes in a symbolic link.
1312
1313 @comment limits.h
1314 @comment POSIX.1
1315 @item POSIX_REC_INCR_XFER_SIZE
1316 Recommended increment for file transfer sizes between the
1317 @code{POSIX_REC_MIN_XFER_SIZE} and @code{POSIX_REC_MAX_XFER_SIZE}
1318 values.
1319
1320 @comment limits.h
1321 @comment POSIX.1
1322 @item POSIX_REC_MAX_XFER_SIZE
1323 Maximum recommended file transfer size.
1324
1325 @comment limits.h
1326 @comment POSIX.1
1327 @item POSIX_REC_MIN_XFER_SIZE
1328 Minimum recommended file transfer size.
1329
1330 @comment limits.h
1331 @comment POSIX.1
1332 @item POSIX_REC_XFER_ALIGN
1333 Recommended file transfer buffer alignment.
1334 @end table
1335
1336 @node Pathconf
1337 @section Using @code{pathconf}
1338
1339 When your machine allows different files to have different values for a
1340 file system parameter, you can use the functions in this section to find
1341 out the value that applies to any particular file.
1342
1343 These functions and the associated constants for the @var{parameter}
1344 argument are declared in the header file @file{unistd.h}.
1345
1346 @comment unistd.h
1347 @comment POSIX.1
1348 @deftypefun {long int} pathconf (const char *@var{filename}, int @var{parameter})
1349 This function is used to inquire about the limits that apply to
1350 the file named @var{filename}.
1351
1352 The @var{parameter} argument should be one of the @samp{_PC_} constants
1353 listed below.
1354
1355 The normal return value from @code{pathconf} is the value you requested.
1356 A value of @code{-1} is returned both if the implementation does not
1357 impose a limit, and in case of an error.  In the former case,
1358 @code{errno} is not set, while in the latter case, @code{errno} is set
1359 to indicate the cause of the problem.  So the only way to use this
1360 function robustly is to store @code{0} into @code{errno} just before
1361 calling it.
1362
1363 Besides the usual file name errors (@pxref{File Name Errors}),
1364 the following error condition is defined for this function:
1365
1366 @table @code
1367 @item EINVAL
1368 The value of @var{parameter} is invalid, or the implementation doesn't
1369 support the @var{parameter} for the specific file.
1370 @end table
1371 @end deftypefun
1372
1373 @comment unistd.h
1374 @comment POSIX.1
1375 @deftypefun {long int} fpathconf (int @var{filedes}, int @var{parameter})
1376 This is just like @code{pathconf} except that an open file descriptor
1377 is used to specify the file for which information is requested, instead
1378 of a file name.
1379
1380 The following @code{errno} error conditions are defined for this function:
1381
1382 @table @code
1383 @item EBADF
1384 The @var{filedes} argument is not a valid file descriptor.
1385
1386 @item EINVAL
1387 The value of @var{parameter} is invalid, or the implementation doesn't
1388 support the @var{parameter} for the specific file.
1389 @end table
1390 @end deftypefun
1391
1392 Here are the symbolic constants that you can use as the @var{parameter}
1393 argument to @code{pathconf} and @code{fpathconf}.  The values are all
1394 integer constants.
1395
1396 @table @code
1397 @comment unistd.h
1398 @comment POSIX.1
1399 @item _PC_LINK_MAX
1400 Inquire about the value of @code{LINK_MAX}.
1401
1402 @comment unistd.h
1403 @comment POSIX.1
1404 @item _PC_MAX_CANON
1405 Inquire about the value of @code{MAX_CANON}.
1406
1407 @comment unistd.h
1408 @comment POSIX.1
1409 @item _PC_MAX_INPUT
1410 Inquire about the value of @code{MAX_INPUT}.
1411
1412 @comment unistd.h
1413 @comment POSIX.1
1414 @item _PC_NAME_MAX
1415 Inquire about the value of @code{NAME_MAX}.
1416
1417 @comment unistd.h
1418 @comment POSIX.1
1419 @item _PC_PATH_MAX
1420 Inquire about the value of @code{PATH_MAX}.
1421
1422 @comment unistd.h
1423 @comment POSIX.1
1424 @item _PC_PIPE_BUF
1425 Inquire about the value of @code{PIPE_BUF}.
1426
1427 @comment unistd.h
1428 @comment POSIX.1
1429 @item _PC_CHOWN_RESTRICTED
1430 Inquire about the value of @code{_POSIX_CHOWN_RESTRICTED}.
1431
1432 @comment unistd.h
1433 @comment POSIX.1
1434 @item _PC_NO_TRUNC
1435 Inquire about the value of @code{_POSIX_NO_TRUNC}.
1436
1437 @comment unistd.h
1438 @comment POSIX.1
1439 @item _PC_VDISABLE
1440 Inquire about the value of @code{_POSIX_VDISABLE}.
1441
1442 @comment unistd.h
1443 @comment POSIX.1
1444 @item _PC_SYNC_IO
1445 Inquire about the value of @code{_POSIX_SYNC_IO}.
1446
1447 @comment unistd.h
1448 @comment POSIX.1
1449 @item _PC_ASYNC_IO
1450 Inquire about the value of @code{_POSIX_ASYNC_IO}.
1451
1452 @comment unistd.h
1453 @comment POSIX.1
1454 @item _PC_PRIO_IO
1455 Inquire about the value of @code{_POSIX_PRIO_IO}.
1456
1457 @comment unistd.h
1458 @comment LFS
1459 @item _PC_FILESIZEBITS
1460 Inquire about the availability of large files on the filesystem.
1461
1462 @comment unistd.h
1463 @comment POSIX.1
1464 @item _PC_REC_INCR_XFER_SIZE
1465 Inquire about the value of @code{POSIX_REC_INCR_XFER_SIZE}.
1466
1467 @comment unistd.h
1468 @comment POSIX.1
1469 @item _PC_REC_MAX_XFER_SIZE
1470 Inquire about the value of @code{POSIX_REC_MAX_XFER_SIZE}.
1471
1472 @comment unistd.h
1473 @comment POSIX.1
1474 @item _PC_REC_MIN_XFER_SIZE
1475 Inquire about the value of @code{POSIX_REC_MIN_XFER_SIZE}.
1476
1477 @comment unistd.h
1478 @comment POSIX.1
1479 @item _PC_REC_XFER_ALIGN
1480 Inquire about the value of @code{POSIX_REC_XFER_ALIGN}.
1481 @end table
1482
1483 @node Utility Limits
1484 @section Utility Program Capacity Limits
1485
1486 The POSIX.2 standard specifies certain system limits that you can access
1487 through @code{sysconf} that apply to utility behavior rather than the
1488 behavior of the library or the operating system.
1489
1490 The GNU C library defines macros for these limits, and @code{sysconf}
1491 returns values for them if you ask; but these values convey no
1492 meaningful information.  They are simply the smallest values that
1493 POSIX.2 permits.
1494
1495 @comment limits.h
1496 @comment POSIX.2
1497 @deftypevr Macro int BC_BASE_MAX
1498 The largest value of @code{obase} that the @code{bc} utility is
1499 guaranteed to support.
1500 @end deftypevr
1501
1502 @comment limits.h
1503 @comment POSIX.2
1504 @deftypevr Macro int BC_DIM_MAX
1505 The largest number of elements in one array that the @code{bc} utility
1506 is guaranteed to support.
1507 @end deftypevr
1508
1509 @comment limits.h
1510 @comment POSIX.2
1511 @deftypevr Macro int BC_SCALE_MAX
1512 The largest value of @code{scale} that the @code{bc} utility is
1513 guaranteed to support.
1514 @end deftypevr
1515
1516 @comment limits.h
1517 @comment POSIX.2
1518 @deftypevr Macro int BC_STRING_MAX
1519 The largest number of characters in one string constant that the
1520 @code{bc} utility is guaranteed to support.
1521 @end deftypevr
1522
1523 @comment limits.h
1524 @comment POSIX.2
1525 @deftypevr Macro int COLL_WEIGHTS_MAX
1526 The largest number of weights that can necessarily be used in defining
1527 the collating sequence for a locale.
1528 @end deftypevr
1529
1530 @comment limits.h
1531 @comment POSIX.2
1532 @deftypevr Macro int EXPR_NEST_MAX
1533 The maximum number of expressions that can be nested within parenthesis
1534 by the @code{expr} utility.
1535 @end deftypevr
1536
1537 @comment limits.h
1538 @comment POSIX.2
1539 @deftypevr Macro int LINE_MAX
1540 The largest text line that the text-oriented POSIX.2 utilities can
1541 support.  (If you are using the GNU versions of these utilities, then
1542 there is no actual limit except that imposed by the available virtual
1543 memory, but there is no way that the library can tell you this.)
1544 @end deftypevr
1545
1546 @comment limits.h
1547 @comment POSIX.2
1548 @deftypevr Macro int EQUIV_CLASS_MAX
1549 The maximum number of weights that can be assigned to an entry of the
1550 @code{LC_COLLATE} category @samp{order} keyword in a locale definition.
1551 The GNU C library does not presently support locale definitions.
1552 @end deftypevr
1553
1554 @node Utility Minimums
1555 @section Minimum Values for Utility Limits
1556
1557 @table @code
1558 @comment limits.h
1559 @comment POSIX.2
1560 @item _POSIX2_BC_BASE_MAX
1561 The most restrictive limit permitted by POSIX.2 for the maximum value of
1562 @code{obase} in the @code{bc} utility.  Its value is @code{99}.
1563
1564 @comment limits.h
1565 @comment POSIX.2
1566 @item _POSIX2_BC_DIM_MAX
1567 The most restrictive limit permitted by POSIX.2 for the maximum size of
1568 an array in the @code{bc} utility.  Its value is @code{2048}.
1569
1570 @comment limits.h
1571 @comment POSIX.2
1572 @item _POSIX2_BC_SCALE_MAX
1573 The most restrictive limit permitted by POSIX.2 for the maximum value of
1574 @code{scale} in the @code{bc} utility.  Its value is @code{99}.
1575
1576 @comment limits.h
1577 @comment POSIX.2
1578 @item _POSIX2_BC_STRING_MAX
1579 The most restrictive limit permitted by POSIX.2 for the maximum size of
1580 a string constant in the @code{bc} utility.  Its value is @code{1000}.
1581
1582 @comment limits.h
1583 @comment POSIX.2
1584 @item _POSIX2_COLL_WEIGHTS_MAX
1585 The most restrictive limit permitted by POSIX.2 for the maximum number
1586 of weights that can necessarily be used in defining the collating
1587 sequence for a locale.  Its value is @code{2}.
1588
1589 @comment limits.h
1590 @comment POSIX.2
1591 @item _POSIX2_EXPR_NEST_MAX
1592 The most restrictive limit permitted by POSIX.2 for the maximum number
1593 of expressions nested within parenthesis when using the @code{expr} utility.
1594 Its value is @code{32}.
1595
1596 @comment limits.h
1597 @comment POSIX.2
1598 @item _POSIX2_LINE_MAX
1599 The most restrictive limit permitted by POSIX.2 for the maximum size of
1600 a text line that the text utilities can handle.  Its value is
1601 @code{2048}.
1602
1603 @comment limits.h
1604 @comment POSIX.2
1605 @item _POSIX2_EQUIV_CLASS_MAX
1606 The most restrictive limit permitted by POSIX.2 for the maximum number
1607 of weights that can be assigned to an entry of the @code{LC_COLLATE}
1608 category @samp{order} keyword in a locale definition.  Its value is
1609 @code{2}.  The GNU C library does not presently support locale
1610 definitions.
1611 @end table
1612
1613 @node String Parameters
1614 @section String-Valued Parameters
1615
1616 POSIX.2 defines a way to get string-valued parameters from the operating
1617 system with the function @code{confstr}:
1618
1619 @comment unistd.h
1620 @comment POSIX.2
1621 @deftypefun size_t confstr (int @var{parameter}, char *@var{buf}, size_t @var{len})
1622 This function reads the value of a string-valued system parameter,
1623 storing the string into @var{len} bytes of memory space starting at
1624 @var{buf}.  The @var{parameter} argument should be one of the
1625 @samp{_CS_} symbols listed below.
1626
1627 The normal return value from @code{confstr} is the length of the string
1628 value that you asked for.  If you supply a null pointer for @var{buf},
1629 then @code{confstr} does not try to store the string; it just returns
1630 its length.  A value of @code{0} indicates an error.
1631
1632 If the string you asked for is too long for the buffer (that is, longer
1633 than @code{@var{len} - 1}), then @code{confstr} stores just that much
1634 (leaving room for the terminating null character).  You can tell that
1635 this has happened because @code{confstr} returns a value greater than or
1636 equal to @var{len}.
1637
1638 The following @code{errno} error conditions are defined for this function:
1639
1640 @table @code
1641 @item EINVAL
1642 The value of the @var{parameter} is invalid.
1643 @end table
1644 @end deftypefun
1645
1646 Currently there is just one parameter you can read with @code{confstr}:
1647
1648 @table @code
1649 @comment unistd.h
1650 @comment POSIX.2
1651 @item _CS_PATH
1652 This parameter's value is the recommended default path for searching for
1653 executable files.  This is the path that a user has by default just
1654 after logging in.
1655
1656 @comment unistd.h
1657 @comment Unix98
1658 @item _CS_LFS_CFLAGS
1659 The returned string specifies which additional flags must be given to
1660 the C compiler if a source is compiled using the
1661 @code{_LARGEFILE_SOURCE} feature select macro; @pxref{Feature Test Macros}.
1662
1663 @comment unistd.h
1664 @comment Unix98
1665 @item _CS_LFS_LDFLAGS
1666 The returned string specifies which additional flags must be given to
1667 the linker if a source is compiled using the
1668 @code{_LARGEFILE_SOURCE} feature select macro; @pxref{Feature Test Macros}.
1669
1670 @comment unistd.h
1671 @comment Unix98
1672 @item _CS_LFS_LIBS
1673 The returned string specifies which additional libraries must be linked
1674 to the application if a source is compiled using the
1675 @code{_LARGEFILE_SOURCE} feature select macro; @pxref{Feature Test Macros}.
1676
1677 @comment unistd.h
1678 @comment Unix98
1679 @item _CS_LFS_LINTFLAGS
1680 The returned string specifies which additional flags must be given to
1681 the lint tool if a source is compiled using the
1682 @code{_LARGEFILE_SOURCE} feature select macro; @pxref{Feature Test Macros}.
1683
1684 @comment unistd.h
1685 @comment Unix98
1686 @item _CS_LFS64_CFLAGS
1687 The returned string specifies which additional flags must be given to
1688 the C compiler if a source is compiled using the
1689 @code{_LARGEFILE64_SOURCE} feature select macro; @pxref{Feature Test Macros}.
1690
1691 @comment unistd.h
1692 @comment Unix98
1693 @item _CS_LFS64_LDFLAGS
1694 The returned string specifies which additional flags must be given to
1695 the linker if a source is compiled using the
1696 @code{_LARGEFILE64_SOURCE} feature select macro; @pxref{Feature Test Macros}.
1697
1698 @comment unistd.h
1699 @comment Unix98
1700 @item _CS_LFS64_LIBS
1701 The returned string specifies which additional libraries must be linked
1702 to the application if a source is compiled using the
1703 @code{_LARGEFILE64_SOURCE} feature select macro; @pxref{Feature Test Macros}.
1704
1705 @comment unistd.h
1706 @comment Unix98
1707 @item _CS_LFS64_LINTFLAGS
1708 The returned string specifies which additional flags must be given to
1709 the lint tool if a source is compiled using the
1710 @code{_LARGEFILE64_SOURCE} feature select macro; @pxref{Feature Test Macros}.
1711 @end table
1712
1713 The way to use @code{confstr} without any arbitrary limit on string size
1714 is to call it twice: first call it to get the length, allocate the
1715 buffer accordingly, and then call @code{confstr} again to fill the
1716 buffer, like this:
1717
1718 @smallexample
1719 @group
1720 char *
1721 get_default_path (void)
1722 @{
1723   size_t len = confstr (_CS_PATH, NULL, 0);
1724   char *buffer = (char *) xmalloc (len);
1725
1726   if (confstr (_CS_PATH, buf, len + 1) == 0)
1727     @{
1728       free (buffer);
1729       return NULL;
1730     @}
1731
1732   return buffer;
1733 @}
1734 @end group
1735 @end smallexample