Put a @table around @include summary.out.
[kopensolaris-gnu/glibc.git] / manual / conf.texi
1 @node System Configuration Limits
2 @chapter System Configuration Limits
3
4 The functions and macros listed in this chapter describe various operating
5 system limits.
6
7 @iftex
8 @itemize @bullet
9
10 @item
11 @ref{File System Parameters}, contains informations about constants and 
12 functions that describe various file system limits, such as the maximum
13 length of a file name.
14
15 @item
16 @ref{System Parameters}, contains information about constants and functions
17 that describe various process-related limits (such as the maximum number
18 of processes that can belong to a single user) and optional features supported
19 by the operating system.
20
21 @item
22 @ref{String-Valued Parameters}, contains information about additional
23 constants and functions for string-valued system parameters.
24 @end itemize
25 @end iftex
26
27 @menu
28 * File System Parameters::      Constants and functions that describe
29                                  various file system limits.
30
31 * System Parameters::           Constants and functions that describe
32                                  various process-related limits.
33
34 * String-Valued Parameters::    Constants and functions that describe
35                                  string-valued limits.
36 @end menu
37
38
39 @node File System Parameters
40 @section File System Parameters
41
42 The POSIX.1 standard specifies a number of symbolic constants that
43 represent the values for certain limits related to the file system, such
44 as the maximum length of a file name component.  However, some of these
45 limits might not really be constants in a given implementation.  For
46 example, in a nonhomogeneous networked environment, files mounted from
47 different hosts might be subject to different sets of limitations.
48
49 In order to deal with the problem of variable limits, for most of these
50 parameters there is one symbolic constant that defines the most
51 restrictive limit permissible by the POSIX standard.  If the actual
52 limit placed by a particular implementation for that parameter is a
53 constant, then it defines another constant to represent it.  Otherwise,
54 the actual limit that applies to a particular file can be requested at
55 runtime by calling @code{pathconf} or @code{fpathconf}.
56
57 Except for @code{FILENAME_MAX}, which is defined in @file{stdio.h},
58 definitions for the following symbolic constants appear in the header
59 file @file{limits.h}.  All of these macros expand into integer
60 constant values.
61 @pindex limits.h
62 @pindex stdio.h
63
64 @strong{Incomplete:}  What does the GNU system do?
65
66 @cindex limits, link count of files
67 @comment limits.h
68 @comment POSIX.1
69 @deftypevr Macro int _POSIX_LINK_MAX
70 This macro represents the most restrictive limit permitted by POSIX
71 for the maximum value of a file's link count.  The value of this
72 constant is @code{8}.
73 @end deftypevr
74
75 @comment limits.h
76 @comment POSIX.1
77 @deftypevr Macro int LINK_MAX
78 This is the actual implementation limit corresponding to
79 @code{_POSIX_LINK_MAX}, but is defined only if the limit for the
80 particular implementation is constant for all files.
81 @end deftypevr
82
83 @cindex limits, terminal input queue
84 @comment limits.h
85 @comment POSIX.1
86 @deftypevr Macro int _POSIX_MAX_CANON
87 This macro represents the most restrictive limit permitted by POSIX
88 for the maximum number of bytes in a canonical input line from a
89 terminal device.  The value of this constant is @code{255}.
90 @end deftypevr
91
92 @comment limits.h
93 @comment POSIX.1
94 @deftypevr Macro int MAX_CANON
95 This is the actual implementation limit corresponding to
96 @code{_POSIX_MAX_CANON}, but is defined only if the limit for the
97 particular implementation is constant for all files.
98 @end deftypevr
99
100 @comment limits.h
101 @comment POSIX.1
102 @deftypevr Macro int _POSIX_MAX_INPUT
103 This macro represents the most restrictive limit permitted by POSIX for
104 the maximum number of bytes in a terminal device input queue (or
105 typeahead buffer).  @xref{Input Modes}.  The value of this constant is
106 @code{255}.
107 @end deftypevr
108
109 @comment limits.h
110 @comment POSIX.1
111 @deftypevr Macro int MAX_INPUT
112 This is the actual implementation limit corresponding to
113 @code{_POSIX_MAX_INPUT}, but is defined only if the limit for the
114 particular implementation is a constant for all files.
115 @end deftypevr
116
117 @cindex limits, file name length
118 @comment limits.h
119 @comment POSIX.1
120 @deftypevr Macro int _POSIX_NAME_MAX
121 This macro represents the most restrictive limit permitted by POSIX for
122 the maximum number of bytes in a file name component.  The value of this
123 constant is @code{14}.
124 @end deftypevr
125
126 @comment limits.h
127 @comment POSIX.1
128 @deftypevr Macro int NAME_MAX
129 This is the actual implementation limit corresponding to
130 @code{_POSIX_NAME_MAX}, but is defined only if the limit for the
131 particular implementation is a constant for all files.
132 @end deftypevr
133
134 @comment dirent.h
135 @comment BSD, GNU
136 @deftypevr Macro int MAXNAMLEN
137 This is the BSD name for @code{NAME_MAX}.
138 @end deftypevr
139
140 @comment limits.h
141 @comment POSIX.1
142 @deftypevr Macro int _POSIX_PATH_MAX
143 This macro represents the most restrictive limit permitted by POSIX for
144 the maximum number of bytes in a file name.  The value of this constant
145 is @code{255}.
146 @end deftypevr
147
148 @comment limits.h
149 @comment POSIX.1
150 @deftypevr Macro int PATH_MAX
151 This is the actual implementation limit corresponding to
152 @code{_POSIX_PATH_MAX}, but is defined only if the limit for the
153 particular implementation is a constant for all files.
154 @end deftypevr
155
156 @comment stdio.h
157 @comment ANSI
158 @deftypevr Macro int FILENAME_MAX 
159 The value of this macro is an integer constant expression that
160 represents the maximum length of a file name string.
161
162 Unlike @code{PATH_MAX}, this macro is defined even if there is no actual
163 limit imposed.  In such a case, its value is typically a very large
164 number.  Don't try to use @code{FILENAME_MAX} as the size of an
165 array in which to store a file name!  Use dynamic allocation
166 (@pxref{Memory Allocation}) instead.
167 @end deftypevr
168
169 @cindex limits, pipe buffer size
170 @comment limits.h
171 @comment POSIX.1
172 @deftypevr Macro int _POSIX_PIPE_BUF
173 This macro represents the most restrictive limit permitted by POSIX for
174 the maximum number of bytes that can be written atomically to a pipe.
175 If multiple processes are writing to the same pipe simultaneously,
176 output from different processes might appear in interleaved chunks of
177 this size.  The value of this constant is @code{512}.
178 @end deftypevr
179
180 @comment limits.h
181 @comment POSIX.1
182 @deftypevr Macro int _PIPE_BUF
183 This is the actual implementation limit corresponding to
184 @code{_POSIX_PIPE_BUF}, but is defined only if the limit for the
185 particular implementation is a constant for all pipes and FIFO files.
186 @end deftypevr
187
188
189 There are also these macros which may be defined in @file{unistd.h} to
190 describe additional characteristics of the file system.  If any of these
191 macros are not defined at all, then the corresponding parameter depends
192 on the file to which it is applied, and you must use the @code{pathconf}
193 function at runtime to determine the parameter value.  If the value is
194 defined to be @code{-1}, then the option does not apply to any file.
195 Otherwise, the option applies to all files.
196 @pindex unistd.h
197
198 @comment unistd.h
199 @comment POSIX.1
200 @deftypevr Macro int _POSIX_CHOWN_RESTRICTED
201 If this option is enabled, the @code{chown} function is restricted so
202 that the only changes permitted to nonprivileged processes is to change 
203 the group owner of a file to either be the effective group ID of the
204 process, or one of its supplementary group IDs.  @xref{File Owner}.
205 @end deftypevr
206
207 @comment unistd.h
208 @comment POSIX.1
209 @deftypevr Macro int _POSIX_NO_TRUNC
210 If this option is enabled, file name components longer than @code{NAME_MAX}
211 generate an @code{ENAMETOOLONG} error.  Otherwise, file name components
212 that are too long are silently truncated.
213 @end deftypevr
214
215 @comment unistd.h
216 @comment POSIX.1
217 @deftypevr Macro {unsigned char} _POSIX_VDISABLE
218 This option is only meaningful for files that are terminal devices.
219 If it is enabled, then handling for special control characters can
220 be disabled individually.  @xref{Special Characters}.
221 @end deftypevr
222
223 For each of the above parameters, if the value is not a constant
224 for all files, you can request the value that applies to a particular
225 file using the @code{pathconf} or @code{fpathconf}.  These functions 
226 and the associated @var{parameter} constants are declared in the
227 header file @file{unistd.h}.
228 @pindex unistd.h
229
230 @comment unistd.h
231 @comment POSIX.1
232 @deftypefun long pathconf (const char *@var{filename}, int @var{parameter})
233 This function is used to inquire about the limits that apply to
234 the file named @var{filename}.
235
236 The @var{parameter} argument should be one of the @samp{_PC_} constants
237 listed below.
238
239 The normal return value from @code{pathconf} is the value you requested.
240 A value of @code{-1} is returned both if the implementation does not
241 impose a limit, and in case of an error.  In the former case, @code{errno}
242 is not set, while in the latter case, @code{errno} is set to indicate
243 the cause of the problem.  Besides the usual file name syntax errors
244 (@pxref{File Name Errors}), the following error conditions are defined
245 for this function:
246
247 @table @code
248 @item EINVAL
249 The value of @var{parameter} is invalid, or the implementation doesn't
250 support the @var{parameter} for the specific file.
251 @end table
252 @end deftypefun
253
254 @comment unistd.h
255 @comment POSIX.1
256 @deftypefun long fpathconf (int @var{filedes}, int @var{parameter})
257 This is just like @code{pathconf} except that an open file descriptor
258 is used to specify the file for which information is requested, instead
259 of a file name.
260
261 The following @code{errno} error conditions are defined for this function:
262
263 @table @code
264 @item EBADF
265 The @var{filedes} argument is not a valid file descriptor.
266
267 @item EINVAL
268 The value of @var{parameter} is invalid, or the implementation doesn't
269 support the @var{parameter} for the specific file.
270 @end table
271 @end deftypefun
272
273 These symbolic constants are defined for use as the @var{parameter}
274 argument to @code{pathconf} and @code{fpathconf}.  The values are
275 all integer constants.
276
277 @comment unistd.h
278 @comment POSIX.1
279 @deftypevr Macro int _PC_LINK_MAX
280 Inquire about the parameter corresponding to @code{LINK_MAX}.
281 @end deftypevr
282
283 @comment unistd.h
284 @comment POSIX.1
285 @deftypevr Macro int _PC_MAX_CANON
286 Inquire about the parameter corresponding to @code{MAX_CANON}.
287 @end deftypevr
288
289 @comment unistd.h
290 @comment POSIX.1
291 @deftypevr Macro int _PC_MAX_INPUT
292 Inquire about the parameter corresponding to @code{MAX_INPUT}.
293 @end deftypevr
294
295 @comment unistd.h
296 @comment POSIX.1
297 @deftypevr Macro int _PC_NAME_MAX
298 Inquire about the parameter corresponding to @code{NAME_MAX}.
299 @end deftypevr
300
301 @comment unistd.h
302 @comment POSIX.1
303 @deftypevr Macro int _PC_PATH_MAX
304 Inquire about the parameter corresponding to @code{PATH_MAX}.
305 @end deftypevr
306
307 @comment unistd.h
308 @comment POSIX.1
309 @deftypevr Macro int _PC_PIPE_BUF
310 Inquire about the parameter corresponding to @code{PIPE_BUF}.
311 @end deftypevr
312
313 @comment unistd.h
314 @comment POSIX.1
315 @deftypevr Macro int _PC_CHOWN_RESTRICTED
316 Inquire about the parameter corresponding to @code{_POSIX_CHOWN_RESTRICTED}.
317 @end deftypevr
318
319 @comment unistd.h
320 @comment POSIX.1
321 @deftypevr Macro int _PC_NO_TRUNC
322 Inquire about the parameter corresponding to @code{_POSIX_NO_TRUNC}.
323 @end deftypevr
324
325 @comment unistd.h
326 @comment POSIX.1
327 @deftypevr Macro int _PC_VDISABLE
328 Inquire about the parameter corresponding to @code{_POSIX_VDISABLE}.
329 @end deftypevr
330
331
332 @node System Parameters
333 @section System Parameters
334
335 The POSIX.1 and POSIX.2 standards specify a number of symbolic constants that
336 represent the values for certain system limits, such as the maximum
337 number of simultaneous processes per user.  However, some of these
338 limits might not really be constant in a given implementation.  In a
339 typical Unix environment, for example, the values are determined from a
340 configuration file used in building the operating system kernel, and can
341 be changed without invalidating already-compiled programs by rebooting
342 the machine with a different kernel.  Other parameters might depend on
343 the amount of memory available.
344
345 In order to deal with the problem of variable limits, for most of these
346 parameters there is one symbolic constant that defines the most
347 restrictive limit permissible by the POSIX standard.  If the actual
348 limit placed by a particular implementation for that parameter is a
349 constant, then it defines another symbolic constant to represent it.
350 Otherwise, the actual limit can be requested at runtime by calling the
351 @code{sysconf} function.
352
353 Definitions for the following macros appear in the header file
354 @file{limits.h}.  The values of the macros are all integer constants.
355 @pindex limits.h
356
357 @strong{Incomplete:}  What does the GNU system do for the 
358 implementation-defined macros?
359
360 @cindex limits, program argument size
361 @comment limits.h
362 @comment POSIX.1
363 @deftypevr Macro int _POSIX_ARG_MAX
364 The value of this macro is the most restrictive limit permitted by POSIX
365 for the maximum combined length of the @var{argv} and @var{environ}
366 arguments that can be passed to the @code{exec} functions.  The value of
367 this constant is @code{4096}.
368 @end deftypevr
369
370 @comment limits.h
371 @comment POSIX.1
372 @deftypevr Macro int ARG_MAX
373 This is the actual implementation limit corresponding to
374 @code{_POSIX_ARG_MAX}, but is defined only if the limit for the
375 particular implementation is a constant.
376 @end deftypevr
377
378 @cindex limits, number of processes
379 @comment limits.h
380 @comment POSIX.1
381 @deftypevr Macro int _POSIX_CHILD_MAX
382 The value of this macro is the most restrictive limit permitted by POSIX
383 for the maximum number of simultaneous processes per real user ID.  Its
384 value is @code{6}.
385 @end deftypevr
386
387 @comment limits.h
388 @comment POSIX.1
389 @deftypevr Macro int CHILD_MAX
390 This is the actual implementation limit corresponding to
391 @code{_POSIX_CHILD_MAX}, but is defined only if the limit for the
392 particular implementation is a constant.
393 @end deftypevr
394
395 @cindex limits, number of open files
396 @comment limits.h
397 @comment POSIX.1
398 @deftypevr Macro int _POSIX_OPEN_MAX
399 The value of this macro is the most restrictive limit permitted by POSIX
400 for the maximum number of files that a single process can have open
401 simultaneously.  The value of this constant is @code{16}.
402 @end deftypevr
403
404 @comment limits.h
405 @comment POSIX.1
406 @deftypevr Macro int OPEN_MAX
407 This is the actual implementation limit corresponding to
408 @code{_POSIX_OPEN_MAX}, but is defined only if the limit for the
409 particular implementation is a constant.
410 @end deftypevr
411
412 @comment limits.h
413 @comment POSIX.1
414 @deftypevr Macro int _POSIX_STREAM_MAX
415 The value of this macro is the most restrictive limit permitted by POSIX
416 for the maximum number of streams that a single process can have open
417 simultaneously.  The value of this constant is @code{8}.
418 @end deftypevr
419
420 @comment limits.h
421 @comment POSIX.1
422 @deftypevr Macro int STREAM_MAX
423 This is the actual implementation limit corresponding to
424 @code{_POSIX_STREAM_MAX}, but is defined only if the limit for the
425 particular implementation is a constant.
426 @end deftypevr
427
428 @cindex limits, time zone name length
429 @comment limits.h
430 @comment POSIX.1
431 @deftypevr Macro int _POSIX_TZNAME_MAX
432 The value of this macro is the most restrictive limit permitted by POSIX
433 for the maximum length of a time zone name.  The value of this constant
434 is @code{3}.
435 @end deftypevr
436
437 @comment limits.h
438 @comment POSIX.1
439 @deftypevr Macro int TZNAME_MAX
440 This is the actual implementation limit corresponding to
441 @code{_POSIX_TZNAME_MAX}, but is defined only if the limit for the
442 particular implementation is a constant.
443 @end deftypevr
444
445 @cindex limits, number of supplementary group IDs
446 @comment limits.h
447 @comment POSIX.1
448 @deftypevr Macro int _POSIX_NGROUPS_MAX
449 The value of this macro is the most restrictive limit permitted by POSIX
450 for the maximum number of supplementary group IDs per process.  The
451 value of the constant is @code{0}.
452 @end deftypevr
453
454 @comment limits.h
455 @comment POSIX.1
456 @deftypevr Macro int NGROUPS_MAX
457 This corresponds to @code{_POSIX_NGROUPS_MAX}, but represents the
458 minimum value guaranteed by the implementation.  This macro is defined
459 even if the limit for the particular implementation is not a constant.
460 (The actual maximum might be larger, and can be accessed with the
461 @code{sysconf} function.)
462 @end deftypevr
463
464 @comment limits.h
465 @comment POSIX.1
466 @deftypevr Macro int _POSIX_SSIZE_MAX
467 The value of this macro is the most restrictive limit permitted by POSIX
468 for the maximum value that can be stored in an object of type @code{ssize_t}.
469 (Effectively, this is the limit on the number of bytes that can be read
470 or written in a single operation.  The value of this constant is
471 @code{32767}.
472 @end deftypevr
473
474 @comment limits.h
475 @comment POSIX.1
476 @deftypevr Macro int SSIZE_MAX
477 This is the actual implementation limit corresponding to
478 @code{_POSIX_SSIZE_MAX}.  This macro is always defined and its value is
479 a constant within a given implementation.
480 @end deftypevr
481
482 @strong{Incomplete:}  There are some more constants from the POSIX.2
483 standard that go here.  But, what's specified in draft 11 doesn't
484 agree with what is currently implemented.
485
486
487 Definitions for these additional macros that describe system parameters
488 appear in the header file @file{unistd.h}.
489 @pindex unistd.h
490
491 @comment unistd.h
492 @comment POSIX.1
493 @deftypevr Macro int _POSIX_JOB_CONTROL
494 If this symbol is defined, it indicates that the system supports job
495 control.  Otherwise, the implementation behaves as if all processes
496 within a session belong to a single process group.  @xref{Job Control}.
497 @end deftypevr
498
499 @comment unistd.h
500 @comment POSIX.1
501 @deftypevr Macro int _POSIX_SAVED_IDS
502 If this symbol is defined, it indicates that the system remembers the
503 effective user and group IDs of an executable file with the set-user-ID
504 or set-group-ID bits set, and that explicitly changing the effective
505 user or group IDs back to these values is permitted.  If this option is
506 not defined, then if a nonprivileged process changes its effective user
507 or group ID to the real user or group ID of the process, it can't change
508 it back again.  @xref{User/Group IDs of a Process}.
509 @end deftypevr
510
511 @comment unistd.h
512 @comment POSIX.1
513 @deftypevr Macro {long int} _POSIX_VERSION
514 This constant represents the version of the POSIX.1 standard to which
515 the implementation conforms.  For an implementation conforming to the
516 1990 POSIX.1 standard, the value is the integer @code{199009L}.
517 @end deftypevr
518
519 @strong{Incomplete:}  There are some more constants from the POSIX.2
520 standard that go here.  But, what's specified in draft 11 doesn't
521 agree with what is currently implemented.
522
523 You can request the actual runtime values of these parameters using the
524 @code{sysconf} function.  This function and the macros for use as its
525 @var{parameter} argument are declared in the header file
526 @file{unistd.h}.
527 @pindex unistd.h
528
529 @comment unistd.h
530 @comment POSIX.1
531 @deftypefun long sysconf (int @var{parameter})
532 This function is used to inquire about runtime system parameters.
533 The @var{parameter} argument should be one of the @samp{_SC_} macros
534 listed below.
535
536 The normal return value from @code{sysconf} is the value you requested.
537 A value of @code{-1} is returned both if the implementation does not
538 impose a limit, and in case of an error.  
539
540 The following @code{errno} error conditions are defined for this function:
541 @table @code
542 @item EINVAL
543 The value of the @var{parameter} is invalid.
544 @end table
545 @end deftypefun
546
547 These symbolic constants are defined for use as the @var{parameter}
548 argument to @code{sysconf}.  The values are all integer constants.
549
550 @comment unistd.h
551 @comment POSIX.1
552 @deftypevr Macro int _SC_ARG_MAX
553 Inquire about the parameter corresponding to @code{ARG_MAX}.
554 @end deftypevr
555
556 @comment unistd.h
557 @comment POSIX.1
558 @deftypevr Macro int _SC_CHILD_MAX
559 Inquire about the parameter corresponding to @code{CHILD_MAX}.
560 @end deftypevr
561
562 @comment unistd.h
563 @comment POSIX.1
564 @deftypevr Macro int _SC_OPEN_MAX
565 Inquire about the parameter corresponding to @code{OPEN_MAX}.
566 @end deftypevr
567
568 @comment unistd.h
569 @comment POSIX.1
570 @deftypevr Macro int _SC_STREAM_MAX
571 Inquire about the parameter corresponding to @code{STREAM_MAX}.
572 @end deftypevr
573
574 @comment unistd.h
575 @comment POSIX.1
576 @deftypevr Macro int _SC_TZNAME_MAX
577 Inquire about the parameter corresponding to @code{TZNAME_MAX}.
578 @end deftypevr
579
580 @comment unistd.h
581 @comment POSIX.1
582 @deftypevr Macro int _SC_NGROUPS_MAX
583 Inquire about the parameter corresponding to @code{NGROUPS_MAX}.
584 @end deftypevr
585
586 @comment unistd.h
587 @comment POSIX.1
588 @deftypevr Macro int _SC_JOB_CONTROL
589 Inquire about the parameter corresponding to @code{_POSIX_JOB_CONTROL}.
590 @end deftypevr
591
592 @comment unistd.h
593 @comment POSIX.1
594 @deftypevr Macro int _SC_SAVED_IDS
595 Inquire about the parameter corresponding to @code{_POSIX_SAVED_IDS}.
596 @end deftypevr
597
598 @comment unistd.h
599 @comment POSIX.1
600 @deftypevr Macro int _SC_VERSION
601 Inquire about the parameter corresponding to @code{_POSIX_VERSION}.
602 @end deftypevr
603
604 @comment unistd.h
605 @comment POSIX.1
606 @deftypevr Macro int _SC_CLK_TCK
607 Inquire about the parameter corresponding to @code{CLOCKS_PER_SEC};
608 @pxref{Basic CPU Time}.
609 @end deftypevr
610
611 @strong{Incomplete:}  There are also a bunch of symbols for POSIX.2
612 features listed in @file{unistd.h}.
613
614
615 @node String-Valued Parameters
616 @section String-Valued Parameters
617
618 @strong{Incomplete:}  The POSIX.2 @code{confstr} function goes here.