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