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