fb7ad473fe6762ad9c3463abe75799d159e3f340
[kopensolaris-gnu/glibc.git] / manual / conf.texi
1 @node System Configuration, Language Features, System Information, Top
2 @chapter System Configuration Parameters
3
4 The functions and macros listed in this chapter give information about
5 configuration parameters of the operating system---for example, capacity
6 limits, presence of optional POSIX features, and the default path for
7 executable files (@pxref{String Parameters}).
8
9 @menu
10 * General Limits::           Constants and functions that describe
11                                 various process-related limits that have
12                                 one uniform value for any given machine.
13 * System Options::           Optional POSIX features.
14 * Version Supported::        Version numbers of POSIX.1 and POSIX.2.
15 * Sysconf::                  Getting specific configuration values
16                                 of general limits and system options.
17 * Minimums::                 Minimum values for general limits.
18
19 * Limits for Files::         Size limitations that pertain to individual files.
20                                 These can vary between file systems
21                                 or even from file to file.
22 * Options for Files::        Optional features that some files may support.
23 * File Minimums::            Minimum values for file limits.
24 * Pathconf::                 Getting the limit values for a particular file.
25
26 * Utility Limits::           Capacity limits of some POSIX.2 utility programs.
27 * Utility Minimums::         Minimum allowable values of those limits.
28
29 * String Parameters::        Getting the default search path.
30 @end menu
31
32 @node General Limits
33 @section General Capacity Limits
34 @cindex POSIX capacity limits
35 @cindex limits, POSIX
36 @cindex capacity limits, POSIX
37
38 The POSIX.1 and POSIX.2 standards specify a number of parameters that
39 describe capacity limitations of the system.  These limits can be fixed
40 constants for a given operating system, or they can vary from machine to
41 machine.  For example, some limit values may be configurable by the
42 system administrator, either at run time or by rebuilding the kernel,
43 and this should not require recompiling application programs.
44
45 @pindex limits.h
46 Each of the following limit parameters has a macro that is defined in
47 @file{limits.h} only if the system has a fixed, uniform limit for the
48 parameter in question.  If the system allows different file systems or
49 files to have different limits, then the macro is undefined; use
50 @code{sysconf} to find out the limit that applies at a particular time
51 on a particular machine.  @xref{Sysconf}.
52 @c !!! pathconf, not 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.
72 @end deftypevr
73
74 @cindex limits, number of open files
75 @comment limits.h
76 @comment POSIX.1
77 @deftypevr Macro int OPEN_MAX
78 If defined, the unvarying maximum number of files that a single process
79 can have open simultaneously.
80 @end deftypevr
81
82 @comment limits.h
83 @comment POSIX.1
84 @deftypevr Macro int STREAM_MAX
85 If defined, the unvarying maximum number of streams that a single
86 process can have open simultaneously.  @xref{Opening Streams}.
87 @end deftypevr
88
89 @cindex limits, time zone name length
90 @comment limits.h
91 @comment POSIX.1
92 @deftypevr Macro int TZNAME_MAX
93 If defined, the unvarying maximum length of a time zone name.
94 @xref{Time Zone Functions}.
95 @end deftypevr
96
97 These limit macros are always defined in @file{limits.h}.
98
99 @cindex limits, number of supplementary group IDs
100 @comment limits.h
101 @comment POSIX.1
102 @deftypevr Macro int NGROUPS_MAX
103 The maximum number of supplementary group IDs that one process can have.
104
105 The value of this macro is actually a lower bound for the maximum.  That
106 is, you can count on being able to have that many supplementary group
107 IDs, but a particular machine might let you have even more.  You can use
108 @code{sysconf} to see whether a particular machine will let you have
109 more (@pxref{Sysconf}).
110 @end deftypevr
111
112 @comment limits.h
113 @comment POSIX.1
114 @deftypevr Macro int SSIZE_MAX
115 The largest value that can fit in an object of type @code{ssize_t}.
116 Effectively, this is the limit on the number of bytes that can be read
117 or written in a single operation.
118
119 This macro is defined in all POSIX systems because this limit is never
120 configurable.
121 @end deftypevr
122
123 @comment limits.h
124 @comment POSIX.2
125 @deftypevr Macro int RE_DUP_MAX
126 The largest number of repetitions you are guaranteed is allowed in the
127 construct @samp{\@{@var{min},@var{max}\@}} in a regular expression.
128
129 The value of this macro is actually a lower bound for the maximum.  That
130 is, you can count on being able to have that many supplementary group
131 IDs, but a particular machine might let you have even more.  You can use
132 @code{sysconf} to see whether a particular machine will let you have
133 more (@pxref{Sysconf}).  And even the value that @code{sysconf} tells
134 you is just a lower bound---larger values might work.
135
136 This macro is defined in all POSIX.2 systems, because POSIX.2 says it
137 should always be defined even if there is no specific imposed limit.
138 @end deftypevr
139
140 @node System Options
141 @section Overall System Options
142 @cindex POSIX optional features
143 @cindex optional POSIX features
144
145 POSIX defines certain system-specific options that not all POSIX systems
146 support.  Since these options are provided in the kernel, not in the
147 library, simply using the GNU C library does not guarantee any of these
148 features is supported; it depends on the system you are using.
149
150 @pindex unistd.h
151 You can test for the availability of a given option using the macros in
152 this section, together with the function @code{sysconf}.  The macros are
153 defined only if you include @file{unistd.h}.
154
155 For the following macros, if the macro is defined in @file{unistd.h},
156 then the option is supported.  Otherwise, the option may or may not be
157 supported; use @code{sysconf} to find out.  @xref{Sysconf}.
158
159 @comment unistd.h
160 @comment POSIX.1
161 @deftypevr Macro int _POSIX_JOB_CONTROL
162 If this symbol is defined, it indicates that the system supports job
163 control.  Otherwise, the implementation behaves as if all processes
164 within a session belong to a single process group.  @xref{Job Control}.
165 @end deftypevr
166
167 @comment unistd.h
168 @comment POSIX.1
169 @deftypevr Macro int _POSIX_SAVED_IDS
170 If this symbol is defined, it indicates that the system remembers the
171 effective user and group IDs of a process before it executes an
172 executable file with the set-user-ID or set-group-ID bits set, and that
173 explicitly changing the effective user or group IDs back to these values
174 is permitted.  If this option is not defined, then if a nonprivileged
175 process changes its effective user or group ID to the real user or group
176 ID of the process, it can't change it back again.  @xref{Enable/Disable
177 Setuid}.
178 @end deftypevr
179
180 For the following macros, if the macro is defined in @file{unistd.h},
181 then its value indicates whether the option is supported.  A value of
182 @code{-1} means no, and any other value means yes.  If the macro is not
183 defined, then the option may or may not be supported; use @code{sysconf}
184 to find out.  @xref{Sysconf}.
185
186 @comment unistd.h
187 @comment POSIX.2
188 @deftypevr Macro int _POSIX2_C_DEV
189 If this symbol is defined, it indicates that the system has the POSIX.2
190 C compiler command, @code{c89}.  The GNU C library always defines this
191 as @code{1}, on the assumption that you would not have installed it if
192 you didn't have a C compiler.
193 @end deftypevr
194
195 @comment unistd.h
196 @comment POSIX.2
197 @deftypevr Macro int _POSIX2_FORT_DEV
198 If this symbol is defined, it indicates that the system has the POSIX.2
199 Fortran compiler command, @code{fort77}.  The GNU C library never
200 defines this, because we don't know what the system has.
201 @end deftypevr
202
203 @comment unistd.h
204 @comment POSIX.2
205 @deftypevr Macro int _POSIX2_FORT_RUN
206 If this symbol is defined, it indicates that the system has the POSIX.2
207 @code{asa} command to interpret Fortran carriage control.  The GNU C
208 library never defines this, because we don't know what the system has.
209 @end deftypevr
210
211 @comment unistd.h
212 @comment POSIX.2
213 @deftypevr Macro int _POSIX2_LOCALEDEF
214 If this symbol is defined, it indicates that the system has the POSIX.2
215 @code{localedef} command.  The GNU C library never defines this, because
216 we don't know what the system has.
217 @end deftypevr
218
219 @comment unistd.h
220 @comment POSIX.2
221 @deftypevr Macro int _POSIX2_SW_DEV
222 If this symbol is defined, it indicates that the system has the POSIX.2
223 commands @code{ar}, @code{make}, and @code{strip}.  The GNU C library
224 always defines this as @code{1}, on the assumption that you had to have
225 @code{ar} and @code{make} to install the library, and it's unlikely that
226 @code{strip} would be absent when those are present.
227 @end deftypevr
228
229 @node Version Supported
230 @section Which Version of POSIX is Supported
231
232 @comment unistd.h
233 @comment POSIX.1
234 @deftypevr Macro {long int} _POSIX_VERSION
235 This constant represents the version of the POSIX.1 standard to which
236 the implementation conforms.  For an implementation conforming to the
237 1990 POSIX.1 standard, the value is the integer @code{199009L}.
238
239 @code{_POSIX_VERSION} is always defined (in @file{unistd.h}) in any
240 POSIX system.
241
242 @strong{Usage Note:} Don't try to test whether the system supports POSIX
243 by including @file{unistd.h} and then checking whether
244 @code{_POSIX_VERSION} is defined.  On a non-POSIX system, this will
245 probably fail because there is no @file{unistd.h}.  We do not know of
246 @emph{any} way you can reliably test at compilation time whether your
247 target system supports POSIX or whether @file{unistd.h} exists.
248
249 The GNU C compiler predefines the symbol @code{__POSIX__} if the target
250 system is a POSIX system.  Provided you do not use any other compilers
251 on POSIX systems, testing @code{defined (__POSIX__)} will reliably
252 detect such systems.
253 @end deftypevr
254
255 @comment unistd.h
256 @comment POSIX.2
257 @deftypevr Macro {long int} _POSIX2_C_VERSION
258 This constant represents the version of the POSIX.2 standard which the
259 library and system kernel support.  We don't know what value this will
260 be for the first version of the POSIX.2 standard, because the value is
261 based on the year and month in which the standard is officially adopted.
262
263 The value of this symbol says nothing about the utilities installed on
264 the system.
265
266 @strong{Usage Note:} You can use this macro to tell whether a POSIX.1
267 system library supports POSIX.2 as well.  Any POSIX.1 system contains
268 @file{unistd.h}, so include that file and then test @code{defined
269 (_POSIX2_C_VERSION)}.
270 @end deftypevr
271
272 @node Sysconf
273 @section Using @code{sysconf}
274
275 When your system has configurable system limits, you can use the
276 @code{sysconf} function to find out the value that applies to any
277 particular machine.  The function and the associated @var{parameter}
278 constants are declared in the header file @file{unistd.h}.
279
280 @menu
281 * Sysconf Definition::        Detailed specifications of @code{sysconf}.
282 * Constants for Sysconf::     The list of parameters @code{sysconf} can read.
283 * Examples of Sysconf::       How to use @code{sysconf} and the parameter
284                                  macros properly together.
285 @end menu
286
287 @node Sysconf Definition
288 @subsection Definition of @code{sysconf}
289
290 @comment unistd.h
291 @comment POSIX.1
292 @deftypefun long int sysconf (int @var{parameter})
293 This function is used to inquire about runtime system parameters.  The
294 @var{parameter} argument should be one of the @samp{_SC_} symbols listed
295 below.
296
297 The normal return value from @code{sysconf} is the value you requested.
298 A value of @code{-1} is returned both if the implementation does not
299 impose a limit, and in case of an error.  
300
301 The following @code{errno} error conditions are defined for this function:
302
303 @table @code
304 @item EINVAL
305 The value of the @var{parameter} is invalid.
306 @end table
307 @end deftypefun
308
309 @node Constants for Sysconf
310 @subsection Constants for @code{sysconf} Parameters
311
312 Here are the symbolic constants for use as the @var{parameter} argument
313 to @code{sysconf}.  The values are all integer constants (more
314 specifically, enumeration type values).
315
316 @table @code
317 @comment unistd.h
318 @comment POSIX.1
319 @item _SC_ARG_MAX
320 Inquire about the parameter corresponding to @code{ARG_MAX}.
321
322 @comment unistd.h
323 @comment POSIX.1
324 @item _SC_CHILD_MAX
325 Inquire about the parameter corresponding to @code{CHILD_MAX}.
326
327 @comment unistd.h
328 @comment POSIX.1
329 @item _SC_OPEN_MAX
330 Inquire about the parameter corresponding to @code{OPEN_MAX}.
331
332 @comment unistd.h
333 @comment POSIX.1
334 @item _SC_STREAM_MAX
335 Inquire about the parameter corresponding to @code{STREAM_MAX}.
336
337 @comment unistd.h
338 @comment POSIX.1
339 @item _SC_TZNAME_MAX
340 Inquire about the parameter corresponding to @code{TZNAME_MAX}.
341
342 @comment unistd.h
343 @comment POSIX.1
344 @item _SC_NGROUPS_MAX
345 Inquire about the parameter corresponding to @code{NGROUPS_MAX}.
346
347 @comment unistd.h
348 @comment POSIX.1
349 @item _SC_JOB_CONTROL
350 Inquire about the parameter corresponding to @code{_POSIX_JOB_CONTROL}.
351
352 @comment unistd.h
353 @comment POSIX.1
354 @item _SC_SAVED_IDS
355 Inquire about the parameter corresponding to @code{_POSIX_SAVED_IDS}.
356
357 @comment unistd.h
358 @comment POSIX.1
359 @item _SC_VERSION
360 Inquire about the parameter corresponding to @code{_POSIX_VERSION}.
361
362 @comment unistd.h
363 @comment POSIX.1
364 @item _SC_CLK_TCK
365 Inquire about the parameter corresponding to @code{CLOCKS_PER_SEC};
366 @pxref{Basic CPU Time}.
367
368 @comment unistd.h
369 @comment POSIX.2
370 @item _SC_2_C_DEV
371 Inquire about whether the system has the POSIX.2 C compiler command,
372 @code{c89}.
373
374 @comment unistd.h
375 @comment POSIX.2
376 @item _SC_2_FORT_DEV
377 Inquire about whether the system has the POSIX.2 Fortran compiler
378 command, @code{fort77}.
379
380 @comment unistd.h
381 @comment POSIX.2
382 @item _SC_2_FORT_RUN
383 Inquire about whether the system has the POSIX.2 @code{asa} command to
384 interpret Fortran carriage control.
385
386 @comment unistd.h
387 @comment POSIX.2
388 @item _SC_2_LOCALEDEF
389 Inquire about whether the system has the POSIX.2 @code{localedef}
390 command.
391
392 @comment unistd.h
393 @comment POSIX.2
394 @item _SC_2_SW_DEV
395 Inquire about whether the system has the POSIX.2 commands @code{ar},
396 @code{make}, and @code{strip}.
397
398 @comment unistd.h
399 @comment POSIX.2
400 @item _SC_BC_BASE_MAX
401 Inquire about the maximum value of @code{obase} in the @code{bc}
402 utility.
403
404 @comment unistd.h
405 @comment POSIX.2
406 @item _SC_BC_DIM_MAX
407 Inquire about the maximum size of an array in the @code{bc}
408 utility.
409
410 @comment unistd.h
411 @comment POSIX.2
412 @item _SC_BC_SCALE_MAX
413 Inquire about the maximum value of @code{scale} in the @code{bc}
414 utility.
415
416 @comment unistd.h
417 @comment POSIX.2
418 @item _SC_BC_STRING_MAX
419 Inquire about the maximum size of a string constant in the
420 @code{bc} utility.
421
422 @comment unistd.h
423 @comment POSIX.2
424 @item _SC_COLL_WEIGHTS_MAX
425 Inquire about the maximum number of weights that can necessarily
426 be used in defining the collating sequence for a locale.
427
428 @comment unistd.h
429 @comment POSIX.2
430 @item _SC_EXPR_NEST_MAX
431 Inquire about the maximum number of expressions nested within
432 parenthesis when using the @code{expr} utility.
433
434 @comment unistd.h
435 @comment POSIX.2
436 @item _SC_LINE_MAX
437 Inquire about the maximum size of a text line that the POSIX.2 text
438 utilities can handle.
439
440 @comment unistd.h
441 @comment POSIX.2
442 @item _SC_VERSION
443 Inquire about the version number of POSIX.1 that the library and kernel
444 support.
445
446 @comment unistd.h
447 @comment POSIX.2
448 @item _SC_2_VERSION
449 Inquire about the version number of POSIX.2 that the system utilities
450 support.
451 @end table
452
453 @node Examples of Sysconf 
454 @subsection Examples of @code{sysconf}
455
456 We recommend that you first test for a macro definition for the
457 parameter you are interested in, and call @code{sysconf} only if the
458 macro is not defined.  For example, here is how to test whether job
459 control is supported:
460
461 @example
462 @group
463 int
464 have_job_control (void)
465 @{
466 #ifdef _POSIX_JOB_CONTROL
467   return 1;
468 #else
469   int value = sysconf (_SC_JOB_CONTROL);
470   if (value < 0)
471     /* @r{If the system is that badly wedged,}
472        @r{there's no use trying to go on.}  */
473     fatal (strerror (errno));
474   return value;
475 #endif
476 @}
477 @end group
478 @end example
479
480 Here is how to get the value of a numeric limit:
481
482 @example
483 int
484 get_child_max ()
485 @{
486 #ifdef CHILD_MAX
487   return CHILD_MAX;
488 #else
489   int value = sysconf (_SC_CHILD_MAX);
490   if (value < 0)
491     fatal (strerror (errno));
492   return value;
493 #endif
494 @}
495 @end example
496
497 @node Minimums
498 @section Minimum Values for General Capacity Limits
499
500 Here are the names for the POSIX minimum upper bounds for the system
501 limit parameters.  The significance of these values is that you can
502 safely push to these limits without checking whether the particular
503 system you are using can go that far.
504
505 @table @code
506 @comment limits.h
507 @comment POSIX.1
508 @item _POSIX_ARG_MAX
509 The value of this macro is the most restrictive limit permitted by POSIX
510 for the maximum combined length of the @var{argv} and @var{environ}
511 arguments that can be passed to the @code{exec} functions.  The value is
512 always @code{4096}.
513
514 @comment limits.h
515 @comment POSIX.1
516 @item _POSIX_CHILD_MAX
517 The value of this macro is the most restrictive limit permitted by POSIX
518 for the maximum number of simultaneous processes per real user ID.  Its
519 value is @code{6}.
520
521 @comment limits.h
522 @comment POSIX.1
523 @item _POSIX_NGROUPS_MAX
524 The value of this macro is the most restrictive limit permitted by POSIX
525 for the maximum number of supplementary group IDs per process.  Its
526 value is @code{0}.
527
528 @comment limits.h
529 @comment POSIX.1
530 @item _POSIX_OPEN_MAX
531 The value of this macro is the most restrictive limit permitted by POSIX
532 for the maximum number of files that a single process can have open
533 simultaneously.  Its value is @code{16}.
534
535 @comment limits.h
536 @comment POSIX.1
537 @item _POSIX_SSIZE_MAX
538 The value of this macro is the most restrictive limit permitted by POSIX
539 for the maximum value that can be stored in an object of type
540 @code{ssize_t}.  Its value is @code{32767}.
541
542 @comment limits.h
543 @comment POSIX.1
544 @item _POSIX_STREAM_MAX
545 The value of this macro is the most restrictive limit permitted by POSIX
546 for the maximum number of streams that a single process can have open
547 simultaneously.  Its value is @code{8}.
548
549 @comment limits.h
550 @comment POSIX.1
551 @item _POSIX_TZNAME_MAX
552 The value of this macro is the most restrictive limit permitted by POSIX
553 for the maximum length of a time zone name.  Its value is @code{3}.
554
555 @comment limits.h
556 @comment POSIX.2
557 @item _POSIX2_RE_DUP_MAX
558 The value of this macro is the most restrictive limit permitted by POSIX
559 for the numbers used in the @samp{\@{@var{min},@var{max}\@}} construct
560 in a regular expression.  Its value is @code{255}.
561 @end table
562
563 @node Limits for Files
564 @section Limits on File System Capacity
565
566 The POSIX.1 standard specifies a number of parameters that describe the
567 limitations of the file system.  It's possible for the system to have a
568 fixed, uniform limit for a parameter, but this isn't the usual case.  On
569 most systems, it's possible for different file systems (and, for some
570 parameters, even different files) to have different maximum limits.  For
571 example, this is very likely if you use NFS to mount some of the file
572 systems from other machines.
573
574 @pindex limits.h
575 Each of the following macros is defined in @file{limits.h} only if the
576 system has a fixed, uniform limit for the parameter in question.  If the
577 system allows different file systems or files to have different limits,
578 then the macro is undefined; use @code{pathconf} or @code{fpathconf} to
579 find out the limit that applies to a particular file.  @xref{Pathconf}.
580
581 Each parameter also has another macro, with a name starting with
582 @samp{_POSIX}, which gives the lowest value that the limit is allowed to
583 have on @emph{any} POSIX system.  @xref{File Minimums}.
584
585 @cindex limits, link count of files
586 @comment limits.h
587 @comment POSIX.1
588 @deftypevr Macro int LINK_MAX
589 The uniform system limit (if any) for the number of names for a given
590 file.  @xref{Hard Links}.
591 @end deftypevr
592
593 @cindex limits, terminal input queue
594 @comment limits.h
595 @comment POSIX.1
596 @deftypevr Macro int MAX_CANON
597 The uniform system limit (if any) for the amount of text in a line of
598 input when input editing is enabled.  @xref{Canonical or Not}.
599 @end deftypevr
600
601 @comment limits.h
602 @comment POSIX.1
603 @deftypevr Macro int MAX_INPUT
604 The uniform system limit (if any) for the total number of characters
605 typed ahead as input.  @xref{I/O Queues}.
606 @end deftypevr
607
608 @cindex limits, file name length
609 @comment limits.h
610 @comment POSIX.1
611 @deftypevr Macro int NAME_MAX
612 The uniform system limit (if any) for the length of a file name component.
613 @end deftypevr
614
615 @comment limits.h
616 @comment POSIX.1
617 @deftypevr Macro int PATH_MAX
618 The uniform system limit (if any) for the length of an entire file name (that
619 is, the argument given to system calls such as @code{open}).
620 @end deftypevr
621
622 @cindex limits, pipe buffer size
623 @comment limits.h
624 @comment POSIX.1
625 @deftypevr Macro int PIPE_BUF
626 The uniform system limit (if any) for the number of bytes that can be
627 written atomically to a pipe.  If multiple processes are writing to the
628 same pipe simultaneously, output from different processes might be
629 interleaved in chunks of this size.  @xref{Pipes and FIFOs}.
630 @end deftypevr
631
632 These are alternative macro names for some of the same information.
633
634 @comment dirent.h
635 @comment BSD
636 @deftypevr Macro int MAXNAMLEN
637 This is the BSD name for @code{NAME_MAX}.  It is defined in
638 @file{dirent.h}.
639 @end deftypevr
640
641 @comment stdio.h
642 @comment ANSI
643 @deftypevr Macro int FILENAME_MAX 
644 The value of this macro is an integer constant expression that
645 represents the maximum length of a file name string.  It is defined in
646 @file{stdio.h}.
647
648 Unlike @code{PATH_MAX}, this macro is defined even if there is no actual
649 limit imposed.  In such a case, its value is typically a very large
650 number.  @strong{This is always the case on the GNU system.}
651
652 @strong{Usage Note:} Don't use @code{FILENAME_MAX} as the size of an
653 array in which to store a file name!  You can't possibly make an array
654 that big!  Use dynamic allocation (@pxref{Memory Allocation}) instead.
655 @end deftypevr
656
657 @node Options for Files
658 @section Optional Features in File Support
659
660 POSIX defines certain system-specific options in the system calls for
661 operating on files.  Some systems support these options and others do
662 not.  Since these options are provided in the kernel, not in the
663 library, simply using the GNU C library does not guarantee any of these
664 features is supported; it depends on the system you are using.
665 @c !!! and can vary between file systems on the same machine.
666
667 @pindex unistd.h
668 This section describes the macros you can test to determine whether a
669 particular option is supported on your machine.  If a given macro is
670 defined in @file{unistd.h}, then its value says whether the
671 corresponding feature is supported.  (A value of @code{-1} indicates no;
672 any other value indicates yes.)  If the macro is undefined, it means
673 particular files may or may not support the feature.
674
675 Since all the machines that support the GNU C library also support NFS,
676 one can never make a general statement about whether all file systems
677 support the @code{_POSIX_CHOWN_RESTRICTED} and @code{_POSIX_NO_TRUNC}
678 features.  So these names are never defined as macros in the GNU C
679 library.
680
681 @comment unistd.h
682 @comment POSIX.1
683 @deftypevr Macro int _POSIX_CHOWN_RESTRICTED
684 If this option is in effect, the @code{chown} function is restricted so
685 that the only changes permitted to nonprivileged processes is to change 
686 the group owner of a file to either be the effective group ID of the
687 process, or one of its supplementary group IDs.  @xref{File Owner}.
688 @end deftypevr
689
690 @comment unistd.h
691 @comment POSIX.1
692 @deftypevr Macro int _POSIX_NO_TRUNC
693 If this option is in effect, file name components longer than
694 @code{NAME_MAX} generate an @code{ENAMETOOLONG} error.  Otherwise, file
695 name components that are too long are silently truncated.
696 @end deftypevr
697
698 @comment unistd.h
699 @comment POSIX.1
700 @deftypevr Macro {unsigned char} _POSIX_VDISABLE
701 This option is only meaningful for files that are terminal devices.
702 If it is enabled, then handling for special control characters can
703 be disabled individually.  @xref{Special Characters}.
704 @end deftypevr
705
706 @pindex unistd.h
707 If one of these macros is undefined, that means that the option might be
708 in effect for some files and not for others.  To inquire about a
709 particular file, call @code{pathconf} or @code{fpathconf}.
710 @xref{Pathconf}.
711
712 @node File Minimums
713 @section Minimum Values for File System Limits
714
715 Here are the names for the POSIX minimum upper bounds for some of the
716 above parameters.  The significance of these values is that you can
717 safely push to these limits without checking whether the particular
718 system you are using can go that far.
719
720 @table @code
721 @comment limits.h
722 @comment POSIX.1
723 @item _POSIX_LINK_MAX
724 The most restrictive limit permitted by POSIX for the maximum value of a
725 file's link count.  The value of this constant is @code{8}; thus, you
726 can always make up to eight names for a file without running into a
727 system limit.
728
729 @comment limits.h
730 @comment POSIX.1
731 @item _POSIX_MAX_CANON
732 The most restrictive limit permitted by POSIX for the maximum number of
733 bytes in a canonical input line from a terminal device.  The value of
734 this constant is @code{255}.
735
736 @comment limits.h
737 @comment POSIX.1
738 @item _POSIX_MAX_INPUT
739 The most restrictive limit permitted by POSIX for the maximum number of
740 bytes in a terminal device input queue (or typeahead buffer).
741 @xref{Input Modes}.  The value of this constant is @code{255}.
742
743 @comment limits.h
744 @comment POSIX.1
745 @item _POSIX_NAME_MAX
746 The most restrictive limit permitted by POSIX for the maximum number of
747 bytes in a file name component.  The value of this constant is
748 @code{14}.
749
750 @comment limits.h
751 @comment POSIX.1
752 @item _POSIX_PATH_MAX
753 The most restrictive limit permitted by POSIX for the maximum number of
754 bytes in a file name.  The value of this constant is @code{255}.
755
756 @comment limits.h
757 @comment POSIX.1
758 @item _POSIX_PIPE_BUF
759 The most restrictive limit permitted by POSIX for the maximum number of
760 bytes that can be written atomically to a pipe.  The value of this
761 constant is @code{512}.
762 @end table
763
764 @node Pathconf
765 @section Using @code{pathconf}
766
767 When your machine allows different files to have different values for a
768 file system parameter, you can use the functions in this section to find
769 out the value that applies to any particular file.
770
771 These functions and the associated constants for the @var{parameter}
772 argument are declared in the header file @file{unistd.h}.
773
774 @comment unistd.h
775 @comment POSIX.1
776 @deftypefun long int pathconf (const char *@var{filename}, int @var{parameter})
777 This function is used to inquire about the limits that apply to
778 the file named @var{filename}.
779
780 The @var{parameter} argument should be one of the @samp{_PC_} constants
781 listed below.
782
783 The normal return value from @code{pathconf} is the value you requested.
784 A value of @code{-1} is returned both if the implementation does not
785 impose a limit, and in case of an error.  In the former case,
786 @code{errno} is not set, while in the latter case, @code{errno} is set
787 to indicate the cause of the problem.  So the only way to use this
788 function robustly is to store @code{0} into @code{errno} just before
789 calling it.
790
791 Besides the usual file name syntax errors (@pxref{File Name Errors}),
792 the following error conditions are defined for this function:
793
794 @table @code
795 @item EINVAL
796 The value of @var{parameter} is invalid, or the implementation doesn't
797 support the @var{parameter} for the specific file.
798 @end table
799 @end deftypefun
800
801 @comment unistd.h
802 @comment POSIX.1
803 @deftypefun long fpathconf (int @var{filedes}, int @var{parameter})
804 This is just like @code{pathconf} except that an open file descriptor
805 is used to specify the file for which information is requested, instead
806 of a file name.
807
808 The following @code{errno} error conditions are defined for this function:
809
810 @table @code
811 @item EBADF
812 The @var{filedes} argument is not a valid file descriptor.
813
814 @item EINVAL
815 The value of @var{parameter} is invalid, or the implementation doesn't
816 support the @var{parameter} for the specific file.
817 @end table
818 @end deftypefun
819
820 Here are the symbolic constants that you can use as the @var{parameter}
821 argument to @code{pathconf} and @code{fpathconf}.  The values are all
822 integer constants.
823
824 @table @code
825 @comment unistd.h
826 @comment POSIX.1
827 @item _PC_LINK_MAX
828 Inquire about the parameter corresponding to @code{LINK_MAX}.
829
830 @comment unistd.h
831 @comment POSIX.1
832 @item _PC_MAX_CANON
833 Inquire about the parameter corresponding to @code{MAX_CANON}.
834
835 @comment unistd.h
836 @comment POSIX.1
837 @item _PC_MAX_INPUT
838 Inquire about the parameter corresponding to @code{MAX_INPUT}.
839
840 @comment unistd.h
841 @comment POSIX.1
842 @item _PC_NAME_MAX
843 Inquire about the parameter corresponding to @code{NAME_MAX}.
844
845 @comment unistd.h
846 @comment POSIX.1
847 @item _PC_PATH_MAX
848 Inquire about the parameter corresponding to @code{PATH_MAX}.
849
850 @comment unistd.h
851 @comment POSIX.1
852 @item _PC_PIPE_BUF
853 Inquire about the parameter corresponding to @code{PIPE_BUF}.
854
855 @comment unistd.h
856 @comment POSIX.1
857 @item _PC_CHOWN_RESTRICTED
858 Inquire about the parameter corresponding to @code{_POSIX_CHOWN_RESTRICTED}.
859
860 @comment unistd.h
861 @comment POSIX.1
862 @item _PC_NO_TRUNC
863 Inquire about the parameter corresponding to @code{_POSIX_NO_TRUNC}.
864
865 @comment unistd.h
866 @comment POSIX.1
867 @item _PC_VDISABLE
868 Inquire about the parameter corresponding to @code{_POSIX_VDISABLE}.
869 @end table
870
871 @node Utility Limits
872 @section Utility Program Capacity Limits
873
874 The POSIX.2 standard specifies certain system limits that you can access
875 through @code{sysconf} that apply to utility behavior rather than the
876 behavior of the library or the operating system.
877
878 The GNU C library defines macros for these limits, and @code{sysconf}
879 returns values for them if you ask; but these values convey no
880 meaningful information.  They are simply the smallest values that
881 POSIX.2 permits.
882
883 @comment limits.h
884 @comment POSIX.2
885 @deftypevr Macro int BC_BASE_MAX
886 The largest value of @code{obase} that the @code{bc} utility is
887 guaranteed to support.
888 @end deftypevr
889
890 @comment limits.h
891 @comment POSIX.2
892 @deftypevr Macro int BC_SCALE_MAX
893 The largest value of @code{scale} that the @code{bc} utility is
894 guaranteed to support.
895 @end deftypevr
896
897 @comment limits.h
898 @comment POSIX.2
899 @deftypevr Macro int BC_DIM_MAX
900 The largest number of elements in one array that the @code{bc} utility
901 is guaranteed to support.
902 @end deftypevr
903
904 @comment limits.h
905 @comment POSIX.2
906 @deftypevr Macro int BC_STRING_MAX
907 The largest number of characters in one string constant that the
908 @code{bc} utility is guaranteed to support.
909 @end deftypevr
910
911 @comment limits.h
912 @comment POSIX.2
913 @deftypevr Macro int BC_DIM_MAX
914 The largest number of elements in one array that the @code{bc} utility
915 is guaranteed to support.
916 @end deftypevr
917
918 @comment limits.h
919 @comment POSIX.2
920 @deftypevr Macro int COLL_WEIGHTS_MAX
921 The largest number of weights that can necessarily be used in defining
922 the collating sequence for a locale.
923 @end deftypevr
924
925 @comment limits.h
926 @comment POSIX.2
927 @deftypevr Macro int EXPR_NEST_MAX
928 The maximum number of expressions that can be nested within parenthesis
929 by the @code{expr} utility.
930 @end deftypevr
931
932 @comment limits.h
933 @comment POSIX.2
934 @deftypevr Macro int LINE_MAX
935 The largest text line that the text-oriented POSIX.2 utilities can
936 support.  (If you are using the GNU versions of these utilities, then
937 there is no actual limit except that imposed by the available virtual
938 memory, but there is no way that the library can tell you this.)
939 @end deftypevr
940
941 @node Utility Minimums
942 @section Minimum Values for Utility Limits
943
944 @table @code
945 @comment limits.h
946 @comment POSIX.2
947 @item _POSIX2_BC_BASE_MAX
948 The most restrictive limit permitted by POSIX.2 for the maximum value of
949 @code{obase} in the @code{bc} utility.  Its value is @code{99}.
950
951 @comment limits.h
952 @comment POSIX.2
953 @item _POSIX2_BC_DIM_MAX
954 The most restrictive limit permitted by POSIX.2 for the maximum size of
955 an array in the @code{bc} utility.  Its value is @code{2048}.
956
957 @comment limits.h
958 @comment POSIX.2
959 @item _POSIX2_BC_SCALE_MAX
960 The most restrictive limit permitted by POSIX.2 for the maximum value of
961 @code{scale} in the @code{bc} utility.  Its value is @code{99}.
962
963 @comment limits.h
964 @comment POSIX.2
965 @item _POSIX2_BC_STRING_MAX
966 The most restrictive limit permitted by POSIX.2 for the maximum size of
967 a string constant in the @code{bc} utility.  Its value is @code{1000}.
968
969 @comment limits.h
970 @comment POSIX.2
971 @item _POSIX2_COLL_WEIGHTS_MAX
972 The most restrictive limit permitted by POSIX.2 for the maximum number
973 of weights that can necessarily be used in defining the collating
974 sequence for a locale.  Its value is @code{2}.
975
976 @comment limits.h
977 @comment POSIX.2
978 @item _POSIX2_EXPR_NEST_MAX
979 The most restrictive limit permitted by POSIX.2 for the maximum number
980 of expressions nested within parenthesis when using the @code{expr} utility.
981 Its value is @code{32}.
982
983 @comment limits.h
984 @comment POSIX.2
985 @item _POSIX2_LINE_MAX
986 The most restrictive limit permitted by POSIX.2 for the maximum size of
987 a text line that the text utilities can handle.  Its value is
988 @code{2048}.
989 @end table
990
991 @node String Parameters
992 @section String-Valued Parameters
993
994 POSIX.2 defines a way to get string-valued parameters from the operating
995 system with the function @code{confstr}:
996
997 @comment unistd.h
998 @comment POSIX.2
999 @deftypefun size_t confstr (int @var{parameter}, char *@var{buf}, size_t @var{len})
1000 This function reads the value of a string-valued system parameter,
1001 storing the string into @var{len} bytes of memory space starting at
1002 @var{buf}.  The @var{parameter} argument should be one of the
1003 @samp{_CS_} symbols listed below.
1004
1005 The normal return value from @code{confstr} is the length of the string
1006 value that you asked for.  If you supply a null pointer for @var{buf},
1007 then @code{confstr} does not try to store the string; it just returns
1008 its length.  A value of @code{0} indicates an error.
1009
1010 If the string you asked for is too long for the buffer (that is, longer
1011 than @code{@var{len} - 1}), then @code{confstr} stores just that much
1012 (leaving room for the terminating null character).  You can tell that
1013 this has happened because @code{confstr} returns a value greater than or
1014 equal to @var{len}.
1015
1016 The following @code{errno} error conditions are defined for this function:
1017
1018 @table @code
1019 @item EINVAL
1020 The value of the @var{parameter} is invalid.
1021 @end table
1022 @end deftypefun
1023
1024 Currently there is just one parameter you can read with @code{confstr}:
1025
1026 @table @code
1027 @comment unistd.h
1028 @comment POSIX.2
1029 @item _CS_PATH
1030 This parameter's value is the recommended default path for searching for
1031 executable files.  This is the path that a user has by default just
1032 after logging in.
1033 @end table
1034
1035 The way to use @code{confstr} without any arbitrary limit on string size
1036 is to call it twice: first call it to get the length, allocate the
1037 buffer accordingly, and then call @code{confstr} again to fill the
1038 buffer, like this:
1039
1040 @example
1041 @group
1042 char *
1043 get_default_path (void)
1044 @{
1045   size_t len = confstr (_CS_PATH, NULL, 0);
1046   char *buffer = (char *) xmalloc (len);
1047
1048   if (confstr (_CS_PATH, buf, len + 1) == 0)
1049     @{
1050       free (buffer);
1051       return 0;
1052     @}
1053
1054   return buffer;
1055 @}
1056 @end group
1057 @end example