1 # SOME DESCRIPTIVE TITLE
2 # Copyright (C) YEAR Free Software Foundation, Inc.
3 # This file is distributed under the same license as the PACKAGE package.
4 # FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
9 "Project-Id-Version: PACKAGE VERSION\n"
10 "POT-Creation-Date: 2014-06-08 01:29+0900\n"
11 "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
12 "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
13 "Language-Team: LANGUAGE <LL@li.org>\n"
16 "Content-Type: text/plain; charset=UTF-8\n"
17 "Content-Transfer-Encoding: 8bit\n"
20 #: build/C/man7/feature_test_macros.7:25
22 msgid "FEATURE_TEST_MACROS"
26 #: build/C/man7/feature_test_macros.7:25
32 #: build/C/man7/feature_test_macros.7:25 build/C/man1/intro.1:28 build/C/man2/intro.2:29 build/C/man3/intro.3:26 build/C/man4/intro.4:26 build/C/man5/intro.5:27 build/C/man6/intro.6:26 build/C/man7/intro.7:28 build/C/man8/intro.8:29 build/C/man7/libc.7:26 build/C/man7/mailaddr.7:27 build/C/man7/man-pages.7:30 build/C/man7/man.7:34 build/C/man7/mdoc.7:44 build/C/man7/operator.7:40 build/C/man5/proc.5:62 build/C/man7/standards.7:24 build/C/man7/suffixes.7:39 build/C/man3/undocumented.3:29 build/C/man2/unimplemented.2:26 build/C/man7/units.7:26
38 #: build/C/man7/feature_test_macros.7:25 build/C/man2/intro.2:29 build/C/man3/intro.3:26 build/C/man4/intro.4:26 build/C/man5/intro.5:27 build/C/man6/intro.6:26 build/C/man7/intro.7:28 build/C/man8/intro.8:29 build/C/man7/libc.7:26 build/C/man7/man-pages.7:30 build/C/man7/man.7:34 build/C/man7/operator.7:40 build/C/man7/posixoptions.7:24 build/C/man5/proc.5:62 build/C/man7/standards.7:24 build/C/man7/suffixes.7:39 build/C/man3/undocumented.3:29 build/C/man2/unimplemented.2:26 build/C/man7/units.7:26
40 msgid "Linux Programmer's Manual"
44 #: build/C/man7/feature_test_macros.7:26 build/C/man1/intro.1:29 build/C/man2/intro.2:30 build/C/man3/intro.3:27 build/C/man4/intro.4:27 build/C/man5/intro.5:28 build/C/man6/intro.6:27 build/C/man7/intro.7:29 build/C/man8/intro.8:30 build/C/man7/libc.7:27 build/C/man7/mailaddr.7:29 build/C/man7/man-pages.7:31 build/C/man7/man.7:35 build/C/man7/mdoc.7:45 build/C/man7/operator.7:41 build/C/man7/posixoptions.7:25 build/C/man5/proc.5:63 build/C/man7/standards.7:25 build/C/man7/suffixes.7:40 build/C/man3/undocumented.3:30 build/C/man2/unimplemented.2:27 build/C/man7/units.7:27 build/C/man7/mdoc.samples.7:46
50 #: build/C/man7/feature_test_macros.7:28
51 msgid "feature_test_macros - feature test macros"
55 #: build/C/man7/feature_test_macros.7:28 build/C/man7/man-pages.7:33 build/C/man7/man.7:37 build/C/man7/mdoc.7:50 build/C/man3/undocumented.3:32 build/C/man2/unimplemented.2:31 build/C/man7/mdoc.samples.7:52
61 #: build/C/man7/feature_test_macros.7:31
63 msgid "B<#include E<lt>features.hE<gt>>\n"
67 #: build/C/man7/feature_test_macros.7:32 build/C/man1/intro.1:31 build/C/man2/intro.2:32 build/C/man3/intro.3:29 build/C/man4/intro.4:29 build/C/man5/intro.5:30 build/C/man6/intro.6:29 build/C/man7/intro.7:31 build/C/man8/intro.8:32 build/C/man7/libc.7:29 build/C/man7/mailaddr.7:31 build/C/man7/man-pages.7:37 build/C/man7/man.7:49 build/C/man7/mdoc.7:54 build/C/man7/operator.7:43 build/C/man7/posixoptions.7:27 build/C/man5/proc.5:65 build/C/man7/standards.7:27 build/C/man7/suffixes.7:42 build/C/man3/undocumented.3:34 build/C/man2/unimplemented.2:33 build/C/man7/units.7:29 build/C/man7/mdoc.samples.7:54
73 #: build/C/man7/feature_test_macros.7:35
75 "Feature test macros allow the programmer to control the definitions that are "
76 "exposed by system header files when a program is compiled."
80 #: build/C/man7/feature_test_macros.7:43
82 "B<NOTE:> In order to be effective, a feature test macro I<must be defined "
83 "before including any header files>. This can be done either in the "
84 "compilation command (I<cc -DMACRO=value>) or by defining the macro within "
85 "the source code before including any headers."
89 #: build/C/man7/feature_test_macros.7:52
91 "Some feature test macros are useful for creating portable applications, by "
92 "preventing nonstandard definitions from being exposed. Other macros can be "
93 "used to expose nonstandard definitions that are not exposed by default. The "
94 "precise effects of each of the feature test macros described below can be "
95 "ascertained by inspecting the I<E<lt>features.hE<gt>> header file."
99 #: build/C/man7/feature_test_macros.7:52
101 msgid "Specification of feature test macro requirements in manual pages"
105 #: build/C/man7/feature_test_macros.7:58
107 "When a function requires that a feature test macro is defined, the manual "
108 "page SYNOPSIS typically includes a note of the following form (this example "
109 "from the B<acct>(2) manual page):"
113 #: build/C/man7/feature_test_macros.7:61
114 msgid "B<#include E<lt>unistd.hE<gt>>"
118 #: build/C/man7/feature_test_macros.7:63
119 msgid "B<int acct(const char *>I<filename>B<);>"
123 #: build/C/man7/feature_test_macros.7:68
126 "Feature Test Macro Requirements for glibc (see\n"
127 "B<feature_test_macros>(7)):\n"
131 #: build/C/man7/feature_test_macros.7:73
132 msgid "B<acct>(): _BSD_SOURCE || (_XOPEN_SOURCE && _XOPEN_SOURCE\\ E<lt>\\ 500)"
136 #: build/C/man7/feature_test_macros.7:84
138 "The B<||> means that in order to obtain the declaration of B<acct>(2) from "
139 "I<E<lt>unistd.hE<gt>>, I<either> of the following macro definitions must be "
140 "made before including any header files:"
144 #: build/C/man7/feature_test_macros.7:89
147 "#define _BSD_SOURCE\n"
148 "#define _XOPEN_SOURCE /* or any value E<lt> 500 */\n"
152 #: build/C/man7/feature_test_macros.7:94
154 "Alternatively, equivalent definitions can be included in the compilation "
159 #: build/C/man7/feature_test_macros.7:99
163 "cc -D_XOPEN_SOURCE # Or any value E<lt> 500\n"
167 #: build/C/man7/feature_test_macros.7:107
169 "Note that, as described below, B<some feature test macros are defined by "
170 "default>, so that it may not always be necessary to explicitly specify the "
171 "feature test macro(s) shown in the SYNOPSIS."
175 #: build/C/man7/feature_test_macros.7:111
177 "In a few cases, manual pages use a shorthand for expressing the feature test "
178 "macro requirements (this example from B<readahead>(2)):"
182 #: build/C/man7/feature_test_macros.7:116
185 "B<#define _GNU_SOURCE>\n"
186 "B<#include E<lt>fcntl.hE<gt>>\n"
190 #: build/C/man7/feature_test_macros.7:118
193 "B<ssize_t readahead(int >I<fd>B<, off64_t *>I<offset>B<, size_t "
198 #: build/C/man7/feature_test_macros.7:124
200 "This format is employed in cases where only a single feature test macro can "
201 "be used to expose the function declaration, and that macro is not defined by "
206 #: build/C/man7/feature_test_macros.7:124
208 msgid "Feature test macros understood by glibc"
211 #. The details in glibc 2.0 are simpler, but combining a
212 #. a description of them with the details in later glibc versions
213 #. would make for a complicated description.
215 #: build/C/man7/feature_test_macros.7:132
217 "The following paragraphs explain how feature test macros are handled in "
218 "Linux glibc 2.I<x>, I<x> E<gt> 0."
222 #: build/C/man7/feature_test_macros.7:134
223 msgid "Linux glibc understands the following feature test macros:"
227 #: build/C/man7/feature_test_macros.7:134
229 msgid "B<__STRICT_ANSI__>"
233 #: build/C/man7/feature_test_macros.7:144
235 "ISO Standard C. This macro is implicitly defined by B<gcc>(1) when invoked "
236 "with, for example, the I<-std=c99> or I<-ansi> flag."
240 #: build/C/man7/feature_test_macros.7:144
242 msgid "B<_POSIX_C_SOURCE>"
246 #: build/C/man7/feature_test_macros.7:147 build/C/man7/feature_test_macros.7:180
247 msgid "Defining this macro causes header files to expose definitions as follows:"
251 #: build/C/man7/feature_test_macros.7:148 build/C/man7/feature_test_macros.7:151 build/C/man7/feature_test_macros.7:154 build/C/man7/feature_test_macros.7:158 build/C/man7/feature_test_macros.7:161 build/C/man7/feature_test_macros.7:167 build/C/man7/feature_test_macros.7:181 build/C/man7/feature_test_macros.7:184 build/C/man7/feature_test_macros.7:187 build/C/man7/feature_test_macros.7:191 build/C/man7/feature_test_macros.7:210 build/C/man7/feature_test_macros.7:213 build/C/man7/feature_test_macros.7:543 build/C/man7/feature_test_macros.7:548 build/C/man7/feature_test_macros.7:554 build/C/man7/feature_test_macros.7:559 build/C/man7/feature_test_macros.7:565 build/C/man7/feature_test_macros.7:570 build/C/man5/proc.5:2862 build/C/man5/proc.5:2864 build/C/man5/proc.5:2866 build/C/man5/proc.5:2869
257 #: build/C/man7/feature_test_macros.7:151
258 msgid "The value 1 exposes definitions conforming to POSIX.1-1990 and ISO C (1990)."
262 #: build/C/man7/feature_test_macros.7:154
263 msgid "The value 2 or greater additionally exposes definitions for POSIX.2-1992."
266 #. 199506L functionality is available only since glibc 2.1
268 #: build/C/man7/feature_test_macros.7:158
270 "The value 199309L or greater additionally exposes definitions for POSIX.1b "
271 "(real-time extensions)."
275 #: build/C/man7/feature_test_macros.7:161
277 "The value 199506L or greater additionally exposes definitions for POSIX.1c "
282 #: build/C/man7/feature_test_macros.7:167
284 "(Since glibc 2.3.3) The value 200112L or greater additionally exposes "
285 "definitions corresponding to the POSIX.1-2001 base specification (excluding "
286 "the XSI extension) and also causes C95 (since glibc 2.12) and C99 (since "
287 "glibc 2.10) features to be exposed."
291 #: build/C/man7/feature_test_macros.7:171
293 "(Since glibc 2.10) The value 200809L or greater additionally exposes "
294 "definitions corresponding to the POSIX.1-2008 base specification (excluding "
295 "the XSI extension)."
299 #: build/C/man7/feature_test_macros.7:172
301 msgid "B<_POSIX_SOURCE>"
305 #: build/C/man7/feature_test_macros.7:177
307 "Defining this obsolete macro with any value is equivalent to defining "
308 "B<_POSIX_C_SOURCE> with the value 1."
312 #: build/C/man7/feature_test_macros.7:177
314 msgid "B<_XOPEN_SOURCE>"
318 #: build/C/man7/feature_test_macros.7:184
320 "Defining with any value exposes definitions conforming to POSIX.1, POSIX.2, "
325 #: build/C/man7/feature_test_macros.7:187
327 "The value 500 or greater additionally exposes definitions for SUSv2 (UNIX "
332 #: build/C/man7/feature_test_macros.7:191
334 "(Since glibc 2.2) The value 600 or greater additionally exposes definitions "
335 "for SUSv3 (UNIX 03; i.e., the POSIX.1-2001 base specification plus the XSI "
336 "extension) and C99 definitions."
340 #: build/C/man7/feature_test_macros.7:195
342 "(Since glibc 2.10) The value 700 or greater additionally exposes definitions "
343 "for SUSv4 (i.e., the POSIX.1-2008 base specification plus the XSI "
348 #: build/C/man7/feature_test_macros.7:209
350 "If B<__STRICT_ANSI__> is not defined, or B<_XOPEN_SOURCE> is defined with a "
351 "value greater than or equal to 500 I<and> neither B<_POSIX_SOURCE> not "
352 "B<_POSIX_C_SOURCE> is explicitly defined, then the following macros are "
353 "implicitly defined:"
357 #: build/C/man7/feature_test_macros.7:213
358 msgid "B<_POSIX_SOURCE> is defined with the value 1."
362 #: build/C/man7/feature_test_macros.7:217
363 msgid "B<_POSIX_C_SOURCE> is defined, according to the value of B<_XOPEN_SOURCE>:"
367 #: build/C/man7/feature_test_macros.7:218
369 msgid "B<_XOPEN_SOURCE> E<lt> 500"
373 #: build/C/man7/feature_test_macros.7:222
374 msgid "B<_POSIX_C_SOURCE> is defined with the value 2."
378 #: build/C/man7/feature_test_macros.7:222
380 msgid "500 E<lt>= B<_XOPEN_SOURCE> E<lt> 600"
384 #: build/C/man7/feature_test_macros.7:226
385 msgid "B<_POSIX_C_SOURCE> is defined with the value 199506L."
389 #: build/C/man7/feature_test_macros.7:226
391 msgid "600 E<lt>= B<_XOPEN_SOURCE> E<lt> 700"
395 #: build/C/man7/feature_test_macros.7:230
396 msgid "B<_POSIX_C_SOURCE> is defined with the value 200112L."
400 #: build/C/man7/feature_test_macros.7:230
402 msgid "700 E<lt>= B<_XOPEN_SOURCE> (since glibc 2.10)"
406 #: build/C/man7/feature_test_macros.7:234
407 msgid "B<_POSIX_C_SOURCE> is defined with the value 200809L."
411 #: build/C/man7/feature_test_macros.7:236
413 msgid "B<_XOPEN_SOURCE_EXTENDED>"
417 #: build/C/man7/feature_test_macros.7:245
419 "If this macro is defined, and B<_XOPEN_SOURCE> is defined, then expose "
420 "definitions corresponding to the XPG4v2 (SUSv1) UNIX extensions (UNIX 95). "
421 "This macro is also implicitly defined if B<_XOPEN_SOURCE> is defined with a "
422 "value of 500 or more."
426 #: build/C/man7/feature_test_macros.7:245
428 msgid "B<_ISOC99_SOURCE> (since glibc 2.1.3)"
432 #: build/C/man7/feature_test_macros.7:248
433 msgid "Exposes declarations consistent with the ISO C99 standard."
437 #: build/C/man7/feature_test_macros.7:254
439 "Earlier glibc 2.1.x versions recognized an equivalent macro named "
440 "B<_ISOC9X_SOURCE> (because the C99 standard had not then been finalized). "
441 "Although the use of this macro is obsolete, glibc continues to recognize it "
442 "for backward compatibility."
446 #: build/C/man7/feature_test_macros.7:259
448 "Defining B<_ISOC99_SOURCE> also exposes ISO C (1990) Amendment 1 (\"C95\") "
449 "definitions. (The primary change in C95 was support for international "
454 #: build/C/man7/feature_test_macros.7:259
456 msgid "B<_ISOC11_SOURCE> (since glibc 2.16)"
460 #: build/C/man7/feature_test_macros.7:264
462 "Exposes declarations consistent with the ISO C11 standard. Defining this "
463 "macro also enables C99 and C95 features (like B<_ISOC99_SOURCE>)."
467 #: build/C/man7/feature_test_macros.7:264
469 msgid "B<_LARGEFILE64_SOURCE>"
473 #: build/C/man7/feature_test_macros.7:285
475 "Expose definitions for the alternative API specified by the LFS (Large File "
476 "Summit) as a \"transitional extension\" to the Single UNIX Specification. "
477 "(See E<.UR http:\\:/\\:/opengroup.org\\:/platform\\:/lfs.html> E<.UE .)> The "
478 "alternative API consists of a set of new objects (i.e., functions and types) "
479 "whose names are suffixed with \"64\" (e.g., I<off64_t> versus I<off_t>, "
480 "B<lseek64>() versus B<lseek>(), etc.). New programs should not employ this "
481 "macro; instead I<_FILE_OFFSET_BITS=64> should be employed."
485 #: build/C/man7/feature_test_macros.7:285
487 msgid "B<_LARGEFILE_SOURCE>"
491 #: build/C/man7/feature_test_macros.7:307
493 "This macro was historically used to expose certain functions (specifically "
494 "B<fseeko>(3) and B<ftello>(3)) that address limitations of earlier APIs "
495 "(B<feek>(3) and B<ftell>(3)) that use I<long int> for file offsets. This "
496 "macro is implicitly defined if B<_XOPEN_SOURCE> is defined with a value "
497 "greater than or equal to 500. New programs should not employ this macro; "
498 "defining B<_XOPEN_SOURCE> as just described or defining B<_FILE_OFFSET_BITS> "
499 "with the value 64 is the preferred mechanism to achieve the same result."
503 #: build/C/man7/feature_test_macros.7:307
505 msgid "B<_FILE_OFFSET_BITS>"
509 #: build/C/man7/feature_test_macros.7:317
511 "Defining this macro with the value 64 automatically converts references to "
512 "32-bit functions and data types related to file I/O and filesystem "
513 "operations into references to their 64-bit counterparts. This is useful for "
514 "performing I/O on large files (E<gt> 2 Gigabytes) on 32-bit systems. "
515 "(Defining this macro permits correctly written programs to use large files "
516 "with only a recompilation being required.)"
520 #: build/C/man7/feature_test_macros.7:320
522 "64-bit systems naturally permit file sizes greater than 2 Gigabytes, and on "
523 "those systems this macro has no effect."
527 #: build/C/man7/feature_test_macros.7:320
529 msgid "B<_BSD_SOURCE> (deprecated since glibc 2.20)"
533 #: build/C/man7/feature_test_macros.7:324
535 "Defining this macro with any value causes header files to expose BSD-derived "
540 #: build/C/man7/feature_test_macros.7:339
542 "In glibc versions up to and including 2.18, defining this macro also causes "
543 "BSD definitions to be preferred in some situations where standards conflict, "
544 "unless one or more of B<_SVID_SOURCE>, B<_POSIX_SOURCE>, B<_POSIX_C_SOURCE>, "
545 "B<_XOPEN_SOURCE>, B<_XOPEN_SOURCE_EXTENDED>, or B<_GNU_SOURCE> is defined, "
546 "in which case BSD definitions are disfavored. Since glibc 2.19, "
547 "B<_BSD_SOURCE> no longer causes BSD definitions to be preferred in case of "
551 #. commit c941736c92fa3a319221f65f6755659b2a5e0a20
552 #. commit 498afc54dfee41d33ba519f496e96480badace8e
553 #. commit acd7f096d79c181866d56d4aaf3b043e741f1e2c
554 #. commit ade40b10ff5fa59a318cf55b9d8414b758e8df78
556 #: build/C/man7/feature_test_macros.7:362
558 "Since glibc 2.20, this macro is deprecated. It now has the same effect as "
559 "defining B<_DEFAULT_SOURCE>, but generates a compile-time warning (unless "
560 "B<_DEFAULT_SOURCE> is also defined). Use B<_DEFAULT_SOURCE> instead. To "
561 "allow code that requires B<_BSD_SOURCE> in glibc 2.19 and earlier and "
562 "B<_DEFAULT_SOURCE> in glibc 2.20 and later to compile without warnings, "
563 "define I<both> B<_BSD_SOURCE> and B<_DEFAULT_SOURCE>."
567 #: build/C/man7/feature_test_macros.7:362
569 msgid "B<_SVID_SOURCE> (deprecated since glibc 2.20)"
573 #: build/C/man7/feature_test_macros.7:368
575 "Defining this macro with any value causes header files to expose System "
576 "V-derived definitions. (SVID == System V Interface Definition; see "
581 #: build/C/man7/feature_test_macros.7:371
583 "Since glibc 2.20, this macro is deprecated in the same fashion as "
588 #: build/C/man7/feature_test_macros.7:371
590 msgid "B<_DEFAULT_SOURCE> (since glibc 2.19)"
594 #: build/C/man7/feature_test_macros.7:383
596 "This macro can be defined to ensure that the \"default\" definitions are "
597 "provided even when the defaults would otherwise be disabled, as happens when "
598 "individual macros are explicitly defined, or the compiler is invoked in one "
599 "of its \"standard\" modes (e.g., I<cc\\ -std=c99>). Defining "
600 "B<_DEFAULT_SOURCE> without defining other individual macros or invoking the "
601 "compiler in one of its \"standard\" modes has no effect."
605 #: build/C/man7/feature_test_macros.7:388
607 "The \"default\" definitions comprise those required by POSIX.1-2008 as well "
608 "as various definitions derived from BSD and System V. On glibc 2.19 and "
609 "earlier, these defaults were approximately equivalent to explicitly defining "
614 #: build/C/man7/feature_test_macros.7:390
616 msgid " cc -D_BSD_SOURCE -D_SVID_SOURCE -D_POSIX_C_SOURCE=200809\n"
620 #: build/C/man7/feature_test_macros.7:391
622 msgid "B<_ATFILE_SOURCE> (since glibc 2.4)"
626 #: build/C/man7/feature_test_macros.7:400
628 "Defining this macro with any value causes header files to expose "
629 "declarations of a range of functions with the suffix \"at\"; see "
630 "B<openat>(2). Since glibc 2.10, this macro is also implicitly defined if "
631 "B<_POSIX_C_SOURCE> is defined with a value greater than or equal to 200809L."
635 #: build/C/man7/feature_test_macros.7:400
637 msgid "B<_GNU_SOURCE>"
641 #: build/C/man7/feature_test_macros.7:419
643 "Defining this macro (with any value) implicitly defines B<_ATFILE_SOURCE>, "
644 "B<_LARGEFILE64_SOURCE>, B<_ISOC99_SOURCE>, B<_XOPEN_SOURCE_EXTENDED>, "
645 "B<_POSIX_SOURCE>, B<_POSIX_C_SOURCE> with the value 200809L (200112L in "
646 "glibc versions before 2.10; 199506L in glibc versions before 2.5; 199309L in "
647 "glibc versions before 2.1) and B<_XOPEN_SOURCE> with the value 700 (600 in "
648 "glibc versions before 2.10; 500 in glibc versions before 2.2). In addition, "
649 "various GNU-specific extensions are also exposed."
653 #: build/C/man7/feature_test_macros.7:430
655 "Since glibc 2.19, defining B<_GNU_SOURCE> also has the effect of implicitly "
656 "defining B<_DEFAULT_SOURCE>. In glibc versions before 2.20, defining "
657 "B<_GNU_SOURCE> also had the effect of implicitly defining B<_BSD_SOURCE> and "
662 #: build/C/man7/feature_test_macros.7:430
664 msgid "B<_REENTRANT>"
668 #: build/C/man7/feature_test_macros.7:436
670 "Defining this macro exposes definitions of certain reentrant functions. For "
671 "multithreaded programs, use I<cc\\ -pthread> instead."
675 #: build/C/man7/feature_test_macros.7:436
677 msgid "B<_THREAD_SAFE>"
681 #: build/C/man7/feature_test_macros.7:441
683 "Synonym for B<_REENTRANT>, provided for compatibility with some other "
688 #: build/C/man7/feature_test_macros.7:441
690 msgid "B<_FORTIFY_SOURCE> (since glibc 2.3.4)"
693 #. For more detail, see:
694 #. http://gcc.gnu.org/ml/gcc-patches/2004-09/msg02055.html
695 #. [PATCH] Object size checking to prevent (some) buffer overflows
696 #. * From: Jakub Jelinek <jakub at redhat dot com>
697 #. * To: gcc-patches at gcc dot gnu dot org
698 #. * Date: Tue, 21 Sep 2004 04:16:40 -0400
700 #: build/C/man7/feature_test_macros.7:453
702 "Defining this macro causes some lightweight checks to be performed to detect "
703 "some buffer overflow errors when employing various string and memory "
704 "manipulation functions. Not all buffer overflows are detected, just some "
709 #: build/C/man7/feature_test_macros.7:471
711 "In the current implementation, checks are added for calls to B<memcpy>(3), "
712 "B<mempcpy>(3), B<memmove>(3), B<memset>(3), B<stpcpy>(3), B<strcpy>(3), "
713 "B<strncpy>(3), B<strcat>(3), B<strncat>(3), B<sprintf>(3), B<snprintf>(3), "
714 "B<vsprintf>(3), B<vsnprintf>(3), and B<gets>(3)."
718 #: build/C/man7/feature_test_macros.7:486
720 "If B<_FORTIFY_SOURCE> is set to 1, with compiler optimization level 1 "
721 "(I<gcc\\ -O1>) and above, checks that shouldn't change the behavior of "
722 "conforming programs are performed. With B<_FORTIFY_SOURCE> set to 2 some "
723 "more checking is added, but some conforming programs might fail. Some of "
724 "the checks can be performed at compile time, and result in compiler "
725 "warnings; other checks take place at run time, and result in a run-time "
726 "error if the check fails."
730 #: build/C/man7/feature_test_macros.7:490
732 "Use of this macro requires compiler support, available with B<gcc>(1) since "
737 #: build/C/man7/feature_test_macros.7:490
739 msgid "Default definitions, implicit definitions, and combining definitions"
743 #: build/C/man7/feature_test_macros.7:506
745 "If no feature test macros are explicitly defined, then the following feature "
746 "test macros are defined by default: B<_BSD_SOURCE> (in glibc 2.19 and "
747 "earlier), B<_SVID_SOURCE> (in glibc 2.19 and earlier), B<_DEFAULT_SOURCE> "
748 "(since glibc 2.19), B<_POSIX_SOURCE>, and B<_POSIX_C_SOURCE>=200809L "
749 "(200112L in glibc versions before 2.10; 199506L in glibc versions before "
750 "2.4; 199309L in glibc versions before 2.1)."
754 #: build/C/man7/feature_test_macros.7:525
756 "If any of B<__STRICT_ANSI__>, B<_ISOC99_SOURCE>, B<_POSIX_SOURCE>, "
757 "B<_POSIX_C_SOURCE>, B<_XOPEN_SOURCE>, B<_XOPEN_SOURCE_EXTENDED>, "
758 "B<_BSD_SOURCE> (in glibc 2.19 and earlier), or B<_SVID_SOURCE> (in glibc "
759 "2.19 and earlier) is explicitly defined, then B<_BSD_SOURCE>, "
760 "B<_SVID_SOURCE>, and B<_DEFAULT_SOURCE> are not defined by default."
764 #: build/C/man7/feature_test_macros.7:536
766 "If B<_POSIX_SOURCE> and B<_POSIX_C_SOURCE> are not explicitly defined, and "
767 "either B<__STRICT_ANSI__> is not defined or B<_XOPEN_SOURCE> is defined with "
768 "a value of 500 or more, then"
772 #: build/C/man7/feature_test_macros.7:536 build/C/man7/feature_test_macros.7:539 build/C/man2/intro.2:44 build/C/man2/intro.2:47 build/C/man2/intro.2:50 build/C/man7/man-pages.7:358 build/C/man7/man-pages.7:360 build/C/man7/man-pages.7:362 build/C/man7/man-pages.7:570 build/C/man7/man-pages.7:820 build/C/man7/man-pages.7:822 build/C/man7/man-pages.7:828 build/C/man7/man-pages.7:831 build/C/man7/man-pages.7:834 build/C/man7/man-pages.7:837 build/C/man7/man-pages.7:842 build/C/man7/man-pages.7:846 build/C/man7/man-pages.7:857 build/C/man7/man-pages.7:870 build/C/man7/man-pages.7:872 build/C/man7/man-pages.7:874 build/C/man5/proc.5:907 build/C/man5/proc.5:911 build/C/man5/proc.5:914 build/C/man5/proc.5:916 build/C/man5/proc.5:919 build/C/man5/proc.5:1461 build/C/man5/proc.5:1464 build/C/man5/proc.5:1476 build/C/man5/proc.5:1479 build/C/man5/proc.5:1483 build/C/man5/proc.5:1486 build/C/man5/proc.5:1489 build/C/man5/proc.5:1492 build/C/man5/proc.5:1495 build/C/man5/proc.5:1498 build/C/man5/proc.5:1501 build/C/man5/proc.5:1504 build/C/man5/proc.5:1508 build/C/man5/proc.5:1511 build/C/man5/proc.5:1514 build/C/man5/proc.5:1517 build/C/man5/proc.5:1520 build/C/man5/proc.5:1523 build/C/man5/proc.5:1526 build/C/man5/proc.5:1537 build/C/man5/proc.5:1543 build/C/man5/proc.5:1547 build/C/man5/proc.5:1552 build/C/man5/proc.5:1557 build/C/man5/proc.5:1562 build/C/man5/proc.5:1567 build/C/man5/proc.5:1572 build/C/man5/proc.5:1577 build/C/man5/proc.5:2643 build/C/man5/proc.5:2647 build/C/man5/proc.5:2650 build/C/man5/proc.5:2655 build/C/man5/proc.5:2849 build/C/man5/proc.5:2853 build/C/man5/proc.5:2859 build/C/man5/proc.5:2898 build/C/man5/proc.5:2904 build/C/man5/proc.5:2906 build/C/man5/proc.5:3796 build/C/man5/proc.5:3801 build/C/man5/proc.5:3803 build/C/man5/proc.5:3805 build/C/man5/proc.5:3807
778 #: build/C/man7/feature_test_macros.7:539
779 msgid "B<_POSIX_SOURCE> is defined with the value 1; and"
783 #: build/C/man7/feature_test_macros.7:542
784 msgid "B<_POSIX_C_SOURCE> is defined with one of the following values:"
788 #: build/C/man7/feature_test_macros.7:548
789 msgid "2, if B<_XOPEN_SOURCE> is defined with a value less than 500;"
793 #: build/C/man7/feature_test_macros.7:554
795 "199506L, if B<_XOPEN_SOURCE> is defined with a value greater than or equal "
796 "to 500 and less than 600; or"
800 #: build/C/man7/feature_test_macros.7:559
802 "(since glibc 2.4) 200112L, if B<_XOPEN_SOURCE> is defined with a value "
803 "greater than or equal to 600 and less than 700."
807 #: build/C/man7/feature_test_macros.7:565
809 "(Since glibc 2.10) 200809L, if B<_XOPEN_SOURCE> is defined with a value "
810 "greater than or equal to 700."
814 #: build/C/man7/feature_test_macros.7:570
816 "Older versions of glibc do not know about the values 200112L and 200809L for "
817 "B<_POSIX_C_SOURCE>, and the setting of this macro will depend on the glibc "
822 #: build/C/man7/feature_test_macros.7:579
824 "If B<_XOPEN_SOURCE> is undefined, then the setting of B<_POSIX_C_SOURCE> "
825 "depends on the glibc version: 199506L, in glibc versions before 2.4; "
826 "200112L, in glibc 2.4 to 2.9; and 200809L, since glibc 2.10."
830 #: build/C/man7/feature_test_macros.7:582
831 msgid "Multiple macros can be defined; the results are additive."
835 #: build/C/man7/feature_test_macros.7:582 build/C/man2/intro.2:93 build/C/man3/intro.3:87 build/C/man7/suffixes.7:276
837 msgid "CONFORMING TO"
841 #: build/C/man7/feature_test_macros.7:590
843 "POSIX.1 specifies B<_POSIX_C_SOURCE>, B<_POSIX_SOURCE>, and "
844 "B<_XOPEN_SOURCE>. B<_XOPEN_SOURCE_EXTENDED> was specified by XPG4v2 (aka "
849 #: build/C/man7/feature_test_macros.7:594
851 "B<_FILE_OFFSET_BITS> is not specified by any standard, but is employed on "
852 "some other implementations."
856 #: build/C/man7/feature_test_macros.7:605
858 "B<_BSD_SOURCE>, B<_SVID_SOURCE>, B<_DEFAULT_SOURCE>, B<_ATFILE_SOURCE>, "
859 "B<_GNU_SOURCE>, B<_FORTIFY_SOURCE>, B<_REENTRANT>, and B<_THREAD_SAFE> are "
860 "specific to Linux (glibc)."
864 #: build/C/man7/feature_test_macros.7:605 build/C/man1/intro.1:48 build/C/man2/intro.2:98 build/C/man3/intro.3:92 build/C/man4/intro.4:33 build/C/man5/intro.5:33 build/C/man6/intro.6:32 build/C/man7/intro.7:36 build/C/man8/intro.8:44 build/C/man7/man.7:479 build/C/man5/proc.5:3851 build/C/man2/unimplemented.2:40
870 #: build/C/man7/feature_test_macros.7:612
872 "I<E<lt>features.hE<gt>> is a Linux/glibc-specific header file. Other "
873 "systems have an analogous file, but typically with a different name. This "
874 "header file is automatically included by other header files as required: it "
875 "is not necessary to explicitly include it in order to employ feature test "
880 #: build/C/man7/feature_test_macros.7:624
882 "According to which of the above feature test macros are defined, "
883 "I<E<lt>features.hE<gt>> internally defines various other macros that are "
884 "checked by other glibc header files. These macros have names prefixed by "
885 "two underscores (e.g., B<__USE_MISC>). Programs should I<never> define "
886 "these macros directly: instead, the appropriate feature test macro(s) from "
887 "the list above should be employed."
891 #: build/C/man7/feature_test_macros.7:624 build/C/man7/man-pages.7:882
897 #: build/C/man7/feature_test_macros.7:630
899 "The program below can be used to explore how the various feature test macros "
900 "are set depending on the glibc version and what feature test macros are "
901 "explicitly set. The following shell session, on a system with glibc 2.10, "
902 "shows some examples of what we would see:"
906 #: build/C/man7/feature_test_macros.7:657
911 "_POSIX_SOURCE defined\n"
912 "_POSIX_C_SOURCE defined: 200809L\n"
913 "_BSD_SOURCE defined\n"
914 "_SVID_SOURCE defined\n"
915 "_ATFILE_SOURCE defined\n"
916 "$ B<cc -D_XOPEN_SOURCE=500 ftm.c>\n"
918 "_POSIX_SOURCE defined\n"
919 "_POSIX_C_SOURCE defined: 199506L\n"
920 "_XOPEN_SOURCE defined: 500\n"
921 "$ B<cc -D_GNU_SOURCE ftm.c>\n"
923 "_POSIX_SOURCE defined\n"
924 "_POSIX_C_SOURCE defined: 200809L\n"
925 "_ISOC99_SOURCE defined\n"
926 "_XOPEN_SOURCE defined: 700\n"
927 "_XOPEN_SOURCE_EXTENDED defined\n"
928 "_LARGEFILE64_SOURCE defined\n"
929 "_BSD_SOURCE defined\n"
930 "_SVID_SOURCE defined\n"
931 "_ATFILE_SOURCE defined\n"
932 "_GNU_SOURCE defined\n"
936 #: build/C/man7/feature_test_macros.7:659
938 msgid "Program source"
942 #: build/C/man7/feature_test_macros.7:663
944 msgid "/* ftm.c */\n"
948 #: build/C/man7/feature_test_macros.7:667
951 "#include E<lt>stdio.hE<gt>\n"
952 "#include E<lt>unistd.hE<gt>\n"
953 "#include E<lt>stdlib.hE<gt>\n"
957 #: build/C/man7/feature_test_macros.7:674
961 "main(int argc, char *argv[])\n"
963 "#ifdef _POSIX_SOURCE\n"
964 " printf(\"_POSIX_SOURCE defined\\en\");\n"
969 #: build/C/man7/feature_test_macros.7:678
972 "#ifdef _POSIX_C_SOURCE\n"
973 " printf(\"_POSIX_C_SOURCE defined: %ldL\\en\", (long) _POSIX_C_SOURCE);\n"
978 #: build/C/man7/feature_test_macros.7:682
981 "#ifdef _ISOC99_SOURCE\n"
982 " printf(\"_ISOC99_SOURCE defined\\en\");\n"
987 #: build/C/man7/feature_test_macros.7:686
990 "#ifdef _ISOC11_SOURCE\n"
991 " printf(\"_ISOC11_SOURCE defined\\en\");\n"
996 #: build/C/man7/feature_test_macros.7:690
999 "#ifdef _XOPEN_SOURCE\n"
1000 " printf(\"_XOPEN_SOURCE defined: %d\\en\", _XOPEN_SOURCE);\n"
1005 #: build/C/man7/feature_test_macros.7:694
1008 "#ifdef _XOPEN_SOURCE_EXTENDED\n"
1009 " printf(\"_XOPEN_SOURCE_EXTENDED defined\\en\");\n"
1014 #: build/C/man7/feature_test_macros.7:698
1017 "#ifdef _LARGEFILE64_SOURCE\n"
1018 " printf(\"_LARGEFILE64_SOURCE defined\\en\");\n"
1023 #: build/C/man7/feature_test_macros.7:702
1026 "#ifdef _FILE_OFFSET_BITS\n"
1027 " printf(\"_FILE_OFFSET_BITS defined: %d\\en\", _FILE_OFFSET_BITS);\n"
1032 #: build/C/man7/feature_test_macros.7:706
1035 "#ifdef _BSD_SOURCE\n"
1036 " printf(\"_BSD_SOURCE defined\\en\");\n"
1041 #: build/C/man7/feature_test_macros.7:710
1044 "#ifdef _SVID_SOURCE\n"
1045 " printf(\"_SVID_SOURCE defined\\en\");\n"
1050 #: build/C/man7/feature_test_macros.7:714
1053 "#ifdef _DEFAULT_SOURCE\n"
1054 " printf(\"_DEFAULT_SOURCE defined\\en\");\n"
1059 #: build/C/man7/feature_test_macros.7:718
1062 "#ifdef _ATFILE_SOURCE\n"
1063 " printf(\"_ATFILE_SOURCE defined\\en\");\n"
1068 #: build/C/man7/feature_test_macros.7:722
1071 "#ifdef _GNU_SOURCE\n"
1072 " printf(\"_GNU_SOURCE defined\\en\");\n"
1077 #: build/C/man7/feature_test_macros.7:726
1080 "#ifdef _REENTRANT\n"
1081 " printf(\"_REENTRANT defined\\en\");\n"
1086 #: build/C/man7/feature_test_macros.7:730
1089 "#ifdef _THREAD_SAFE\n"
1090 " printf(\"_THREAD_SAFE defined\\en\");\n"
1095 #: build/C/man7/feature_test_macros.7:734
1098 "#ifdef _FORTIFY_SOURCE\n"
1099 " printf(\"_FORTIFY_SOURCE defined\\en\");\n"
1104 #: build/C/man7/feature_test_macros.7:737
1107 " exit(EXIT_SUCCESS);\n"
1112 #: build/C/man7/feature_test_macros.7:738 build/C/man1/intro.1:302 build/C/man2/intro.2:112 build/C/man3/intro.3:97 build/C/man4/intro.4:38 build/C/man5/intro.5:38 build/C/man7/intro.7:41 build/C/man7/libc.7:104 build/C/man7/mailaddr.7:117 build/C/man7/man-pages.7:889 build/C/man7/man.7:560 build/C/man7/mdoc.7:428 build/C/man7/posixoptions.7:854 build/C/man5/proc.5:3864 build/C/man7/standards.7:277 build/C/man7/suffixes.7:280 build/C/man2/unimplemented.2:64 build/C/man7/mdoc.samples.7:2952
1118 #: build/C/man7/feature_test_macros.7:741
1119 msgid "B<libc>(7), B<standards>(7)"
1122 #. But beware: the info libc document is out of date (Jul 07, mtk)
1124 #: build/C/man7/feature_test_macros.7:745
1125 msgid "The section \"Feature Test Macros\" under I<info libc>."
1129 #: build/C/man7/feature_test_macros.7:747
1130 msgid "I</usr/include/features.h>"
1134 #: build/C/man7/feature_test_macros.7:747 build/C/man1/intro.1:304 build/C/man2/intro.2:135 build/C/man3/intro.3:110 build/C/man4/intro.4:40 build/C/man5/intro.5:40 build/C/man6/intro.6:37 build/C/man7/intro.7:43 build/C/man8/intro.8:49 build/C/man7/libc.7:112 build/C/man7/mailaddr.7:127 build/C/man7/man-pages.7:896 build/C/man7/man.7:572 build/C/man7/mdoc.7:433 build/C/man7/operator.7:65 build/C/man7/posixoptions.7:857 build/C/man5/proc.5:3898 build/C/man7/standards.7:281 build/C/man7/suffixes.7:283 build/C/man3/undocumented.3:183 build/C/man2/unimplemented.2:66 build/C/man7/units.7:130 build/C/man7/mdoc.samples.7:2957
1140 #: build/C/man7/feature_test_macros.7:755 build/C/man1/intro.1:312 build/C/man2/intro.2:143 build/C/man3/intro.3:118 build/C/man4/intro.4:48 build/C/man5/intro.5:48 build/C/man6/intro.6:45 build/C/man7/intro.7:51 build/C/man8/intro.8:57 build/C/man7/libc.7:120 build/C/man7/mailaddr.7:135 build/C/man7/man-pages.7:904 build/C/man7/man.7:580 build/C/man7/operator.7:73 build/C/man7/posixoptions.7:865 build/C/man5/proc.5:3906 build/C/man7/standards.7:289 build/C/man7/suffixes.7:291 build/C/man3/undocumented.3:191 build/C/man2/unimplemented.2:74 build/C/man7/units.7:138
1142 "This page is part of release 3.68 of the Linux I<man-pages> project. A "
1143 "description of the project, information about reporting bugs, and the latest "
1144 "version of this page, can be found at "
1145 "\\%http://www.kernel.org/doc/man-pages/."
1149 #: build/C/man1/intro.1:28 build/C/man2/intro.2:29 build/C/man3/intro.3:26 build/C/man4/intro.4:26 build/C/man5/intro.5:27 build/C/man6/intro.6:26 build/C/man7/intro.7:28 build/C/man8/intro.8:29
1155 #: build/C/man1/intro.1:28
1161 #: build/C/man1/intro.1:28 build/C/man7/mailaddr.7:27
1163 msgid "Linux User's Manual"
1167 #: build/C/man1/intro.1:31
1168 msgid "intro - introduction to user commands"
1172 #: build/C/man1/intro.1:35
1174 "Section 1 of the manual describes user commands and tools, for example, file "
1175 "manipulation tools, shells, compilers, web browsers, file and image viewers "
1176 "and editors, and so on."
1180 #: build/C/man1/intro.1:48
1182 "All commands yield a status value on termination. This value can be tested "
1183 "(e.g., in most shells the variable I<$?> contains the status of the last "
1184 "executed command) to see whether the command completed successfully. A "
1185 "zero exit status is conventionally used to indicate success, and a nonzero "
1186 "status means that the command was unsuccessful. (Details of the exit status "
1187 "can be found in B<wait>(2).) A nonzero exit status can be in the range 1 to "
1188 "255, and some commands use different nonzero status values to indicate the "
1189 "reason why the command failed."
1193 #: build/C/man1/intro.1:52
1195 "Linux is a flavor of UNIX, and as a first approximation all user commands "
1196 "under UNIX work precisely the same under Linux (and FreeBSD and lots of "
1197 "other UNIX-like systems)."
1201 #: build/C/man1/intro.1:62
1203 "Under Linux there are GUIs (graphical user interfaces), where you can point "
1204 "and click and drag, and hopefully get work done without first reading lots "
1205 "of documentation. The traditional UNIX environment is a CLI (command line "
1206 "interface), where you type commands to tell the computer what to do. That "
1207 "is faster and more powerful, but requires finding out what the commands "
1208 "are. Below a bare minimum, to get started."
1212 #: build/C/man1/intro.1:62
1218 #: build/C/man1/intro.1:76
1220 "In order to start working, you probably first have to login, that is, give "
1221 "your username and password. See also B<login>(1). The program I<login> now "
1222 "starts a I<shell> (command interpreter) for you. In case of a graphical "
1223 "login, you get a screen with menus or icons and a mouse click will start a "
1224 "shell in a window. See also B<xterm>(1)."
1228 #: build/C/man1/intro.1:76
1234 #: build/C/man1/intro.1:91
1236 "One types commands to the I<shell>, the command interpreter. It is not "
1237 "built-in, but is just a program and you can change your shell. Everybody "
1238 "has her own favorite one. The standard one is called I<sh>. See also "
1239 "B<ash>(1), B<bash>(1), B<csh>(1), B<zsh>(1), B<chsh>(1)."
1243 #: build/C/man1/intro.1:93
1244 msgid "A session might go like"
1248 #: build/C/man1/intro.1:108
1251 "B<knuth login: >I<aeb>\n"
1252 "B<Password: >I<********>\n"
1254 "Tue Aug 6 23:50:44 CEST 2002\n"
1257 "Su Mo Tu We Th Fr Sa\n"
1260 "11 12 13 14 15 16 17\n"
1261 "18 19 20 21 22 23 24\n"
1262 "25 26 27 28 29 30 31\n"
1266 #: build/C/man1/intro.1:135
1273 "drwxrwxr-x 2 aeb 1024 Aug 6 23:51 bin\n"
1274 "-rw-rw-r-- 1 aeb 37 Aug 6 23:52 tel\n"
1276 "maja 0501-1136285\n"
1277 "peter 0136-7399214\n"
1278 "B<% >I<cp tel tel2>\n"
1281 "drwxr-xr-x 2 aeb 1024 Aug 6 23:51 bin\n"
1282 "-rw-r--r-- 1 aeb 37 Aug 6 23:52 tel\n"
1283 "-rw-r--r-- 1 aeb 37 Aug 6 23:53 tel2\n"
1284 "B<% >I<mv tel tel1>\n"
1287 "drwxr-xr-x 2 aeb 1024 Aug 6 23:51 bin\n"
1288 "-rw-r--r-- 1 aeb 37 Aug 6 23:52 tel1\n"
1289 "-rw-r--r-- 1 aeb 37 Aug 6 23:53 tel2\n"
1290 "B<% >I<diff tel1 tel2>\n"
1292 "B<% >I<grep maja tel2>\n"
1293 "maja 0501-1136285\n"
1298 #: build/C/man1/intro.1:147
1300 "and here typing Control-D ended the session. The B<% > here was the command "
1301 "prompt\\(emit is the shell's way of indicating that it is ready for the next "
1302 "command. The prompt can be customized in lots of ways, and one might "
1303 "include stuff like username, machine name, current directory, time, and so "
1304 "on. An assignment PS1=\"What next, master? \" would change the prompt as "
1309 #: build/C/man1/intro.1:153
1311 "We see that there are commands I<date> (that gives date and time), and "
1312 "I<cal> (that gives a calendar)."
1316 #: build/C/man1/intro.1:169
1318 "The command I<ls> lists the contents of the current directory\\(emit tells "
1319 "you what files you have. With a I<-l> option it gives a long listing, that "
1320 "includes the owner and size and date of the file, and the permissions people "
1321 "have for reading and/or changing the file. For example, the file \"tel\" "
1322 "here is 37 bytes long, owned by aeb and the owner can read and write it, "
1323 "others can only read it. Owner and permissions can be changed by the "
1324 "commands I<chown> and I<chmod>."
1328 #: build/C/man1/intro.1:176
1330 "The command I<cat> will show the contents of a file. (The name is from "
1331 "\"concatenate and print\": all files given as parameters are concatenated "
1332 "and sent to \"standard output\", here the terminal screen.)"
1336 #: build/C/man1/intro.1:183
1338 "The command I<cp> (from \"copy\") will copy a file. On the other hand, the "
1339 "command I<mv> (from \"move\") only renames it."
1343 #: build/C/man1/intro.1:188
1345 "The command I<diff> lists the differences between two files. Here there was "
1346 "no output because there were no differences."
1350 #: build/C/man1/intro.1:194
1352 "The command I<rm> (from \"remove\") deletes the file, and be careful! it is "
1353 "gone. No wastepaper basket or anything. Deleted means lost."
1357 #: build/C/man1/intro.1:199
1359 "The command I<grep> (from \"g/re/p\") finds occurrences of a string in one "
1360 "or more files. Here it finds Maja's telephone number."
1364 #: build/C/man1/intro.1:199
1366 msgid "Pathnames and the current directory"
1370 #: build/C/man1/intro.1:211
1372 "Files live in a large tree, the file hierarchy. Each has a I<pathname> "
1373 "describing the path from the root of the tree (which is called /) to the "
1374 "file. For example, such a full pathname might be /home/aeb/tel. Always "
1375 "using full pathnames would be inconvenient, and the name of a file in the "
1376 "current directory may be abbreviated by giving only the last component. "
1377 "That is why \"/home/aeb/tel\" can be abbreviated to \"tel\" when the current "
1378 "directory is \"/home/aeb\"."
1382 #: build/C/man1/intro.1:215
1383 msgid "The command I<pwd> prints the current directory."
1387 #: build/C/man1/intro.1:220
1389 "The command I<cd> changes the current directory. Try \"cd /\" and \"pwd\" "
1390 "and \"cd\" and \"pwd\"."
1394 #: build/C/man1/intro.1:220
1400 #: build/C/man1/intro.1:224
1401 msgid "The command I<mkdir> makes a new directory."
1405 #: build/C/man1/intro.1:228
1407 "The command I<rmdir> removes a directory if it is empty, and complains "
1412 #: build/C/man1/intro.1:240
1414 "The command I<find> (with a rather baroque syntax) will find files with "
1415 "given name or other properties. For example, \"find . -name tel\" would "
1416 "find the file \"tel\" starting in the present directory (which is called "
1417 "\".\"). And \"find / -name tel\" would do the same, but starting at the "
1418 "root of the tree. Large searches on a multi-GB disk will be time-consuming, "
1419 "and it may be better to use B<locate>(1)."
1423 #: build/C/man1/intro.1:240
1425 msgid "Disks and filesystems"
1429 #: build/C/man1/intro.1:251
1431 "The command I<mount> will attach the filesystem found on some disk (or "
1432 "floppy, or CDROM or so) to the big filesystem hierarchy. And I<umount> "
1433 "detaches it again. The command I<df> will tell you how much of your disk is "
1438 #: build/C/man1/intro.1:251
1444 #: build/C/man1/intro.1:269
1446 "On a UNIX system many user and system processes run simultaneously. The one "
1447 "you are talking to runs in the I<foreground>, the others in the "
1448 "I<background>. The command I<ps> will show you which processes are active "
1449 "and what numbers these processes have. The command I<kill> allows you to "
1450 "get rid of them. Without option this is a friendly request: please go "
1451 "away. And \"kill -9\" followed by the number of the process is an immediate "
1452 "kill. Foreground processes can often be killed by typing Control-C."
1456 #: build/C/man1/intro.1:269
1458 msgid "Getting information"
1462 #: build/C/man1/intro.1:282
1464 "There are thousands of commands, each with many options. Traditionally "
1465 "commands are documented on I<man pages>, (like this one), so that the "
1466 "command \"man kill\" will document the use of the command \"kill\" (and "
1467 "\"man man\" document the command \"man\"). The program I<man> sends the "
1468 "text through some I<pager>, usually I<less>. Hit the space bar to get the "
1469 "next page, hit q to quit."
1473 #: build/C/man1/intro.1:290
1475 "In documentation it is customary to refer to man pages by giving the name "
1476 "and section number, as in B<man>(1). Man pages are terse, and allow you to "
1477 "find quickly some forgotten detail. For newcomers an introductory text with "
1478 "more examples and explanations is useful."
1482 #: build/C/man1/intro.1:294
1484 "A lot of GNU/FSF software is provided with info files. Type \"info info\" "
1485 "for an introduction on the use of the program \"info\"."
1489 #. Actual examples? Separate section for each of cat, cp, ...?
1490 #. gzip, bzip2, tar, rpm
1492 #: build/C/man1/intro.1:302
1494 "Special topics are often treated in HOWTOs. Look in "
1495 "I</usr/share/doc/howto/en> and use a browser if you find HTML files there."
1499 #: build/C/man1/intro.1:304 build/C/man4/intro.4:40 build/C/man5/intro.5:40 build/C/man7/intro.7:43
1500 msgid "B<standards>(7)"
1504 #: build/C/man2/intro.2:29
1510 #: build/C/man2/intro.2:32
1511 msgid "intro - introduction to system calls"
1515 #: build/C/man2/intro.2:42
1517 "Section 2 of the manual describes the Linux system calls. A system call is "
1518 "an entry point into the Linux kernel. Usually, system calls are not invoked "
1519 "directly: instead, most system calls have corresponding C library wrapper "
1520 "functions which perform the steps required (e.g., trapping to kernel mode) "
1521 "in order to invoke the system call. Thus, making a system call looks the "
1522 "same as invoking a normal library function."
1526 #: build/C/man2/intro.2:44
1527 msgid "In many cases, the C library wrapper function does nothing more than:"
1531 #: build/C/man2/intro.2:47
1533 "copying arguments and the unique system call number to the registers where "
1534 "the kernel expects them;"
1538 #: build/C/man2/intro.2:50
1540 "trapping to kernel mode, at which point the kernel does the real work of the "
1545 #: build/C/man2/intro.2:55
1547 "setting I<errno> if the system call returns an error number when the kernel "
1548 "returns the CPU to user mode."
1552 #: build/C/man2/intro.2:65
1554 "However, in a few cases, a wrapper function may do rather more than this, "
1555 "for example, performing some preprocessing of the arguments of arguments "
1556 "before trapping to kernel mode, or postprocessing of values returned by the "
1557 "system call. Where this is the case, the manual pages in Section 2 "
1558 "generally try to note the details of both the (usually GNU) C library API "
1559 "interface and the raw system call. Most commonly, the main DESCRIPTION will "
1560 "focus on the C library interface, and differences for the system call are "
1561 "covered in the NOTES section."
1565 #: build/C/man2/intro.2:68
1566 msgid "For a list of the Linux system calls, see B<syscalls>(2)."
1570 #: build/C/man2/intro.2:68 build/C/man2/unimplemented.2:35
1572 msgid "RETURN VALUE"
1576 #: build/C/man2/intro.2:77
1578 "On error, most system calls return a negative error number (i.e., the "
1579 "negated value of one of the constants described in B<errno>(3)). The C "
1580 "library wrapper hides this detail from the caller: when a system call "
1581 "returns a negative value, the wrapper copies the absolute value into the "
1582 "I<errno> variable, and returns -1 as the return value of the wrapper."
1586 #: build/C/man2/intro.2:82
1588 "The value returned by a successful system call depends on the call. Many "
1589 "system calls return 0 on success, but some can return nonzero values from a "
1590 "successful call. The details are described in the individual manual pages."
1594 #: build/C/man2/intro.2:93
1596 "In some cases, the programmer must define a feature test macro in order to "
1597 "obtain the declaration of a system call from the header file specified in "
1598 "the man page SYNOPSIS section. (Where required, these feature test macros "
1599 "must be defined before including I<any> header files.) In such cases, the "
1600 "required macro is described in the man page. For further information on "
1601 "feature test macros, see B<feature_test_macros>(7)."
1605 #: build/C/man2/intro.2:98 build/C/man3/intro.3:92
1607 "Certain terms and abbreviations are used to indicate UNIX variants and "
1608 "standards to which calls in this section conform. See B<standards>(7)."
1612 #: build/C/man2/intro.2:99
1614 msgid "Calling directly"
1618 #: build/C/man2/intro.2:108
1620 "In most cases, it is unnecessary to invoke a system call directly, but there "
1621 "are times when the Standard C library does not implement a nice wrapper "
1622 "function for you. In this case, the programmer must manually invoke the "
1623 "system call using B<syscall>(2). Historically, this was also possible using "
1624 "one of the _syscall macros described in B<_syscall>(2)."
1628 #: build/C/man2/intro.2:108 build/C/man3/intro.3:93 build/C/man4/intro.4:34 build/C/man5/intro.5:34 build/C/man6/intro.6:33 build/C/man7/intro.7:37 build/C/man8/intro.8:45
1630 msgid "Authors and copyright conditions"
1634 #: build/C/man2/intro.2:112 build/C/man3/intro.3:97 build/C/man4/intro.4:38 build/C/man5/intro.5:38 build/C/man6/intro.6:37 build/C/man7/intro.7:41 build/C/man8/intro.8:49
1636 "Look at the header of the manual page source for the author(s) and copyright "
1637 "conditions. Note that these can be different from page to page!"
1641 #: build/C/man2/intro.2:135
1643 "B<_syscall>(2), B<syscall>(2), B<syscalls>(2), B<errno>(3), B<intro>(3), "
1644 "B<capabilities>(7), B<credentials>(7), B<feature_test_macros>(7), "
1645 "B<mq_overview>(7), B<path_resolution>(7), B<pipe>(7), B<pty>(7), "
1646 "B<sem_overview>(7), B<shm_overview>(7), B<signal>(7), B<socket>(7), "
1647 "B<standards>(7), B<svipc>(7), B<symlink>(7), B<time>(7)"
1651 #: build/C/man3/intro.3:26
1657 #: build/C/man3/intro.3:29
1658 msgid "intro - introduction to library functions"
1662 #: build/C/man3/intro.3:33
1664 "Section 3 of the manual describes all library functions excluding the "
1665 "library functions (system call wrappers) described in Section 2, which "
1666 "implement system calls."
1670 #: build/C/man3/intro.3:50
1672 "Many of the functions described in the section are part of the Standard C "
1673 "Library (I<libc>). Some functions are part of other libraries (e.g., the "
1674 "math library, I<libm>, or the real-time library, I<librt>) in which case "
1675 "the manual page will indicate the linker option needed to link against the "
1676 "required library (e.g., I<-lm> and I<-lrt>, respectively, for the "
1677 "aforementioned libraries)."
1682 #. are various function groups which can be identified by a letter which
1683 #. is appended to the chapter number:
1685 #. These functions, the functions from chapter 2 and from chapter 3S are
1686 #. contained in the C standard library libc, which will be used by
1690 #. These functions are parts of the
1692 #. library. They are contained in the standard C library libc.
1694 #. These functions are contained in the arithmetic library libm. They are
1697 #. FORTRAN compiler by default, but not by the
1699 #. C compiler, which needs the option \fI\-lm\fP.
1701 #. These functions are part of the FORTRAN library libF77. There are no
1702 #. special compiler flags needed to use these functions.
1704 #. Various special libraries. The manual pages documenting their functions
1705 #. specify the library names.
1707 #: build/C/man3/intro.3:87
1709 "In some cases, the programmer must define a feature test macro in order to "
1710 "obtain the declaration of a function from the header file specified in the "
1711 "man page SYNOPSIS section. (Where required, these feature test macros must "
1712 "be defined before including I<any> header files.) In such cases, the "
1713 "required macro is described in the man page. For further information on "
1714 "feature test macros, see B<feature_test_macros>(7)."
1718 #: build/C/man3/intro.3:110
1720 "B<intro>(2), B<errno>(3), B<capabilities>(7), B<credentials>(7), "
1721 "B<environ>(7), B<feature_test_macros>(7), B<libc>(7), B<math_error>(7), "
1722 "B<path_resolution>(7), B<pthreads>(7), B<signal>(7), B<standards>(7)"
1726 #: build/C/man4/intro.4:26 build/C/man5/intro.5:27 build/C/man6/intro.6:26 build/C/man7/intro.7:28 build/C/man8/intro.8:29
1732 #: build/C/man4/intro.4:29
1733 msgid "intro - introduction to special files"
1737 #: build/C/man4/intro.4:31
1738 msgid "Section 4 of the manual describes special files (devices)."
1742 #: build/C/man4/intro.4:31 build/C/man7/mailaddr.7:113 build/C/man7/man.7:475 build/C/man7/mdoc.7:411 build/C/man7/mdoc.samples.7:2874
1748 #: build/C/man4/intro.4:33
1749 msgid "/dev/* \\(em device files"
1753 #: build/C/man5/intro.5:30
1754 msgid "intro - introduction to file formats"
1758 #: build/C/man5/intro.5:33
1760 "Section 5 of the manual describes various file formats and protocols, and "
1761 "the corresponding C structures, if any."
1765 #: build/C/man6/intro.6:29
1766 msgid "intro - introduction to games"
1770 #: build/C/man6/intro.6:32
1772 "Section 6 of the manual describes all the games and funny little programs "
1773 "available on the system."
1777 #: build/C/man7/intro.7:31
1778 msgid "intro - introduction to overview, conventions, and miscellany section"
1782 #: build/C/man7/intro.7:36
1784 "Section 7 of the manual provides overviews on various topics, and describes "
1785 "conventions and protocols, character set standards, the standard filesystem "
1786 "layout, and miscellaneous other things."
1790 #: build/C/man8/intro.8:32
1791 msgid "intro - introduction to administration and privileged commands"
1795 #: build/C/man8/intro.8:37
1797 "Section 8 of the manual describes commands which either can be or are used "
1798 "only by the superuser, like system-administration commands, daemons, and "
1799 "hardware-related commands."
1803 #: build/C/man8/intro.8:44
1805 "As with the commands in described Section 1, the commands described in this "
1806 "section terminate with an exit status that indicates whether the command "
1807 "succeeded or failed. See B<intro>(1) for more information."
1811 #: build/C/man7/libc.7:26
1817 #: build/C/man7/libc.7:26
1823 #: build/C/man7/libc.7:29
1824 msgid "libc - overview of standard C libraries on Linux"
1828 #: build/C/man7/libc.7:36
1830 "The term \"libc\" is commonly used as a shorthand for the \"standard C "
1831 "library\", a library of standard functions that can be used by all C "
1832 "programs (and sometimes by programs in other languages). Because of some "
1833 "history (see below), use of the term \"libc\" to refer to the standard C "
1834 "library is somewhat ambiguous on Linux."
1838 #: build/C/man7/libc.7:36
1844 #: build/C/man7/libc.7:54
1846 "By far the most widely used C library on Linux is the GNU C Library E<.UR "
1847 "http://www.gnu.org\\:/software\\:/libc/> E<.UE ,> often referred to as "
1848 "I<glibc>. This is the C library that is nowadays used in all major Linux "
1849 "distributions. It is also the C library whose details are documented in the "
1850 "relevant pages of the I<man-pages> project (primarily in Section 3 of the "
1851 "manual). Documentation of glibc is also available in the glibc manual, "
1852 "available via the command I<info libc>. Release 1.0 of glibc was made in "
1853 "September 1992. (There were earlier 0.x releases.) The next major release "
1854 "of glibc was 2.0, at the beginning of 1997."
1858 #: build/C/man7/libc.7:61
1860 "The pathname I</lib/libc.so.6> (or something similar) is normally a symbolic "
1861 "link that points to the location of the glibc library, and executing this "
1862 "pathname will cause glibc to display various information about the version "
1863 "installed on your system."
1867 #: build/C/man7/libc.7:61
1873 #: build/C/man7/libc.7:84
1875 "In the early to mid 1990s, there was for a while I<Linux libc>, a fork of "
1876 "glibc 1.x created by Linux developers who felt that glibc development at the "
1877 "time was not sufficing for the needs of Linux. Often, this library was "
1878 "referred to (ambiguously) as just \"libc\". Linux libc released major "
1879 "versions 2, 3, 4, and 5 (as well as many minor versions of those releases). "
1880 "For a while, Linux libc was the standard C library in many Linux "
1881 "distributions. However, notwithstanding the original motivations of the "
1882 "Linux libc effort, by the time glibc 2.0 was released, it was clearly "
1883 "superior to Linux libc, and all major Linux distributions that had been "
1884 "using Linux libc soon switched back to glibc. (Since this switch occurred "
1885 "over a decade ago, I<man-pages> no longer takes care to document Linux libc "
1886 "details. Nevertheless, the history is visible in vestiges of information "
1887 "about Linux libc that remain in some manual pages, in particular, references "
1888 "to I<libc4> and I<libc5>.)"
1892 #: build/C/man7/libc.7:84
1894 msgid "Other C libraries"
1898 #: build/C/man7/libc.7:104
1900 "There are various other less widely used C libraries for Linux. These "
1901 "libraries are generally smaller than glibc, both in terms of features and "
1902 "memory footprint, and often intended for building small binaries, perhaps "
1903 "targeted at development for embedded Linux systems. Among such libraries "
1904 "are E<.UR http://www.uclibc.org/> I<uClibc> E<.UE ,> E<.UR "
1905 "http://www.fefe.de/dietlibc/> I<dietlibc> E<.UE ,> and E<.UR "
1906 "http://www.musl-libc.org/> I<musl libc> E<.UE .> Details of these libraries "
1907 "are generally not covered by the I<man-pages> project."
1911 #: build/C/man7/libc.7:112
1913 "B<syscalls>(2), B<getauxval>(3), B<proc>(5), B<feature_test_macros>(7), "
1914 "B<man-pages>(7), B<standards>(7), B<vdso>(7)"
1918 #: build/C/man7/mailaddr.7:27
1924 #: build/C/man7/mailaddr.7:27
1930 #: build/C/man7/mailaddr.7:31
1931 msgid "mailaddr - mail addressing description"
1935 #: build/C/man7/mailaddr.7:36
1937 "This manual page gives a brief introduction to SMTP mail addresses, as used "
1938 "on the Internet. These addresses are in the general format"
1942 #: build/C/man7/mailaddr.7:38
1943 msgid " user@domain"
1947 #: build/C/man7/mailaddr.7:41
1949 "where a domain is a hierarchical dot-separated list of subdomains. These "
1950 "examples are valid forms of the same address:"
1954 #: build/C/man7/mailaddr.7:43
1955 msgid " eric@monet.berkeley.edu"
1959 #: build/C/man7/mailaddr.7:45
1960 msgid " Eric Allman E<lt>eric@monet.berkeley.eduE<gt>"
1964 #: build/C/man7/mailaddr.7:47
1966 msgid " eric@monet.berkeley.edu (Eric Allman)\n"
1970 #: build/C/man7/mailaddr.7:51
1972 "The domain part (\"monet.berkeley.edu\") is a mail-accepting domain. It can "
1973 "be a host and in the past it usually was, but it doesn't have to be. The "
1974 "domain part is not case sensitive."
1978 #: build/C/man7/mailaddr.7:59
1980 "The local part (\"eric\") is often a username, but its meaning is defined by "
1981 "the local software. Sometimes it is case sensitive, although that is "
1982 "unusual. If you see a local-part that looks like garbage, it is usually "
1983 "because of a gateway between an internal e-mail system and the net, here are "
1988 #: build/C/man7/mailaddr.7:61
1989 msgid " \"surname/admd=telemail/c=us/o=hp/prmd=hp\"@some.where"
1993 #: build/C/man7/mailaddr.7:63
1994 msgid " USER%SOMETHING@some.where"
1998 #: build/C/man7/mailaddr.7:65
1999 msgid " machine!machine!name@some.where"
2003 #: build/C/man7/mailaddr.7:67
2004 msgid " I2461572@some.where"
2008 #: build/C/man7/mailaddr.7:71
2010 "(These are, respectively, an X.400 gateway, a gateway to an arbitrary "
2011 "internal mail system that lacks proper internet support, an UUCP gateway, "
2012 "and the last one is just boring username policy.)"
2016 #: build/C/man7/mailaddr.7:77
2018 "The real-name part (\"Eric Allman\") can either be placed before E<lt>E<gt>, "
2019 "or in () at the end. (Strictly speaking the two aren't the same, but the "
2020 "difference is beyond the scope of this page.) The name may have to be "
2021 "quoted using \"\", for example, if it contains \".\":"
2025 #: build/C/man7/mailaddr.7:79
2026 msgid " \"Eric P. Allman\" E<lt>eric@monet.berkeley.eduE<gt>"
2030 #: build/C/man7/mailaddr.7:79
2032 msgid "Abbreviation."
2036 #: build/C/man7/mailaddr.7:87
2038 "Many mail systems let users abbreviate the domain name. For instance, users "
2039 "at berkeley.edu may get away with \"eric@monet\" to send mail to Eric "
2040 "Allman. I<This behavior is deprecated.> Sometimes it works, but you should "
2045 #: build/C/man7/mailaddr.7:87
2047 msgid "Route-addrs."
2051 #: build/C/man7/mailaddr.7:94
2053 "In the past, sometimes one had to route a message through several hosts to "
2054 "get it to its final destination. Addresses which show these relays are "
2055 "termed \"route-addrs\". These use the syntax:"
2059 #: build/C/man7/mailaddr.7:96
2060 msgid " E<lt>@hosta,@hostb:user@hostcE<gt>"
2064 #: build/C/man7/mailaddr.7:101
2066 "This specifies that the message should be sent to hosta, from there to "
2067 "hostb, and finally to hostc. Many hosts disregard route-addrs and send "
2068 "directly to hostc."
2072 #: build/C/man7/mailaddr.7:107
2074 "Route-addrs are very unusual now. They occur sometimes in old mail "
2075 "archives. It is generally possible to ignore all but the \"user@hostc\" "
2076 "part of the address to determine the actual address."
2080 #: build/C/man7/mailaddr.7:107
2086 #: build/C/man7/mailaddr.7:113
2088 "Every site is required to have a user or user alias designated "
2089 "\"postmaster\" to which problems with the mail system may be addressed. The "
2090 "\"postmaster\" address is not case sensitive."
2094 #: build/C/man7/mailaddr.7:115
2095 msgid "I</etc/aliases>"
2099 #: build/C/man7/mailaddr.7:117
2100 msgid "I<~/.forward>"
2104 #: build/C/man7/mailaddr.7:125
2106 "B<binmail>(1), B<mail>(1), B<mconnect>(1), B<aliases>(5), B<forward>(5), "
2107 "B<sendmail>(8), B<vrfy>(8)"
2111 #: build/C/man7/mailaddr.7:127
2112 msgid "RFC\\ 2822 (Internet Message Format)"
2116 #: build/C/man7/man-pages.7:30
2122 #: build/C/man7/man-pages.7:30
2128 #: build/C/man7/man-pages.7:33
2129 msgid "man-pages - conventions for writing Linux man pages"
2133 #: build/C/man7/man-pages.7:37 build/C/man7/man.7:49
2134 msgid "B<man> [I<section>] I<title>"
2138 #: build/C/man7/man-pages.7:47
2140 "This page describes the conventions that should be employed when writing man "
2141 "pages for the Linux I<man-pages> project, which documents the user-space API "
2142 "provided by the Linux kernel and the GNU C library. The project thus "
2143 "provides most of the pages in Section 2, as well as many of the pages that "
2144 "appear in Sections 3, 4, 5, and 7 of the man pages on a Linux system. The "
2145 "conventions described on this page may also be useful for authors writing "
2146 "man pages for other projects."
2150 #: build/C/man7/man-pages.7:47
2152 msgid "Sections of the manual pages"
2156 #: build/C/man7/man-pages.7:50
2157 msgid "The manual Sections are traditionally defined as follows:"
2161 #: build/C/man7/man-pages.7:50
2163 msgid "B<1 Commands (Programs)>"
2167 #: build/C/man7/man-pages.7:54
2168 msgid "Those commands that can be executed by the user from within a shell."
2172 #: build/C/man7/man-pages.7:54
2174 msgid "B<2 System calls>"
2178 #: build/C/man7/man-pages.7:57
2179 msgid "Those functions which must be performed by the kernel."
2183 #: build/C/man7/man-pages.7:57
2185 msgid "B<3 Library calls>"
2189 #: build/C/man7/man-pages.7:62
2190 msgid "Most of the I<libc> functions."
2194 #: build/C/man7/man-pages.7:62
2196 msgid "B<4 Special files (devices)>"
2200 #: build/C/man7/man-pages.7:66
2201 msgid "Files found in I</dev>."
2205 #: build/C/man7/man-pages.7:66
2207 msgid "B<5 File formats and conventions>"
2211 #: build/C/man7/man-pages.7:71
2212 msgid "The format for I</etc/passwd> and other human-readable files."
2216 #: build/C/man7/man-pages.7:71
2222 #: build/C/man7/man-pages.7:73
2224 msgid "B<7 Overview, conventions, and miscellaneous>"
2228 #: build/C/man7/man-pages.7:77
2230 "Overviews of various topics, conventions and protocols, character set "
2231 "standards, and miscellaneous other things."
2235 #: build/C/man7/man-pages.7:77
2237 msgid "B<8 System management commands>"
2241 #. .B 9 Kernel routines
2242 #. This is an obsolete manual section.
2243 #. Once it was thought a good idea to document the Linux kernel here,
2244 #. but in fact very little has been documented, and the documentation
2245 #. that exists is outdated already.
2246 #. There are better sources of
2247 #. information for kernel developers.
2249 #: build/C/man7/man-pages.7:90
2250 msgid "Commands like B<mount>(8), many of which only root can execute."
2254 #: build/C/man7/man-pages.7:90
2256 msgid "Macro package"
2260 #: build/C/man7/man-pages.7:97
2262 "New manual pages should be marked up using the B<groff an.tmac> package "
2263 "described in B<man>(7). This choice is mainly for consistency: the vast "
2264 "majority of existing Linux manual pages are marked up using these macros."
2268 #: build/C/man7/man-pages.7:97
2270 msgid "Conventions for source file layout"
2274 #: build/C/man7/man-pages.7:102
2276 "Please limit source code line length to no more than about 75 characters "
2277 "wherever possible. This helps avoid line-wrapping in some mail clients when "
2278 "patches are submitted inline."
2282 #: build/C/man7/man-pages.7:106
2284 "New sentences should be started on new lines. This makes it easier to see "
2285 "the effect of patches, which often operate at the level of individual "
2290 #: build/C/man7/man-pages.7:106 build/C/man7/man.7:78
2296 #: build/C/man7/man-pages.7:110
2297 msgid "The first command in a man page should be a B<TH> command:"
2301 #: build/C/man7/man-pages.7:114 build/C/man7/man.7:85
2302 msgid "B<\\&.TH> I<title section date source manual>"
2306 #: build/C/man7/man-pages.7:117
2311 #: build/C/man7/man-pages.7:118
2317 #: build/C/man7/man-pages.7:122
2318 msgid "The title of the man page, written in all caps (e.g., I<MAN-PAGES>)."
2322 #: build/C/man7/man-pages.7:122
2328 #: build/C/man7/man-pages.7:126
2329 msgid "The section number in which the man page should be placed (e.g., I<7>)."
2333 #: build/C/man7/man-pages.7:126
2339 #: build/C/man7/man-pages.7:131
2341 "The date of the last revision\\(emremember to change this every time a "
2342 "nontrivial change is made to the man page. Dates should be written in the "
2347 #: build/C/man7/man-pages.7:131
2353 #: build/C/man7/man-pages.7:134
2354 msgid "The source of the command, function, or system call."
2358 #: build/C/man7/man-pages.7:138
2360 "For those few I<man-pages> pages in Sections 1 and 8, probably you just want "
2365 #: build/C/man7/man-pages.7:146
2367 "For system calls, just write I<Linux>. (An earlier practice was to write "
2368 "the version number of the kernel from which the manual page was being "
2369 "written/checked. However, this was never done consistently, and so was "
2370 "probably worse than including no version number. Henceforth, avoid "
2371 "including a version number.)"
2375 #: build/C/man7/man-pages.7:151
2377 "For library calls that are part of glibc or one of the other common GNU "
2378 "libraries, just use I<GNU C Library>, I<GNU>, or an empty string."
2382 #: build/C/man7/man-pages.7:154
2383 msgid "For Section 4 pages, use I<Linux>."
2387 #: build/C/man7/man-pages.7:157
2388 msgid "In cases of doubt, just write I<Linux>, or I<GNU>."
2392 #: build/C/man7/man-pages.7:157
2398 #: build/C/man7/man-pages.7:162
2400 "The title of the manual (e.g., for Section 2 and 3 pages in the I<man-pages> "
2401 "package, use I<Linux Programmer's Manual>)."
2405 #: build/C/man7/man-pages.7:163
2407 msgid "Sections within a manual page"
2411 #: build/C/man7/man-pages.7:170
2413 "The list below shows conventional or suggested sections. Most manual pages "
2414 "should include at least the B<highlighted> sections. Arrange a new manual "
2415 "page so that sections are placed in the order shown in the list."
2418 #. May 07: Few current man pages have an ERROR HANDLING section,,,
2420 #. May 07: Almost no current man pages have a USAGE section,,,
2423 #. May 07: Almost no current man pages have a SECURITY section,,,
2425 #. AUTHORS sections are discouraged
2426 #. AUTHORS [Discouraged]
2428 #: build/C/man7/man-pages.7:199
2433 "CONFIGURATION [Normally only in Section 4]\n"
2435 "OPTIONS [Normally only in Sections 1, 8]\n"
2436 "EXIT STATUS [Normally only in Sections 1, 8]\n"
2437 "RETURN VALUE [Normally only in Sections 2, 3]\n"
2438 "ERRORS [Typically only in Sections 2, 3]\n"
2441 "VERSIONS [Normally only in Sections 2, 3]\n"
2442 "ATTRIBUTES [Normally only in Sections 2, 3]\n"
2451 #: build/C/man7/man-pages.7:210
2453 "I<Where a traditional heading would apply>, I<please use it>; this kind of "
2454 "consistency can make the information easier to understand. If you must, you "
2455 "can create your own headings if they make things easier to understand (this "
2456 "can be especially useful for pages in Sections 4 and 5). However, before "
2457 "doing this, consider whether you could use the traditional headings, with "
2458 "some subsections (I<.SS>) within those sections."
2462 #: build/C/man7/man-pages.7:213
2463 msgid "The following list elaborates on the contents of each of the above sections."
2467 #: build/C/man7/man-pages.7:213
2473 #: build/C/man7/man-pages.7:224
2475 "The name of this manual page. See B<man>(7) for important details of the "
2476 "line(s) that should follow the B<.SH NAME> command. All words in this line "
2477 "(including the word immediately following the \"\\e-\") should be in "
2478 "lowercase, except where English or technical terminological convention "
2479 "dictates otherwise."
2483 #: build/C/man7/man-pages.7:224
2489 #: build/C/man7/man-pages.7:236
2491 "briefly describes the command or function's interface. For commands, this "
2492 "shows the syntax of the command and its arguments (including options); "
2493 "boldface is used for as-is text and italics are used to indicate replaceable "
2494 "arguments. Brackets ([]) surround optional arguments, vertical bars (|) "
2495 "separate choices, and ellipses (\\&...) can be repeated. For functions, it "
2496 "shows any required data declarations or B<#include> directives, followed by "
2497 "the function declaration."
2500 #. FIXME . Say something here about compiler options
2502 #: build/C/man7/man-pages.7:242
2504 "Where a feature test macro must be defined in order to obtain the "
2505 "declaration of a function (or a variable) from a header file, then the "
2506 "SYNOPSIS should indicate this, as described in B<feature_test_macros>(7)."
2510 #: build/C/man7/man-pages.7:242
2512 msgid "B<CONFIGURATION>"
2516 #: build/C/man7/man-pages.7:246
2518 "Configuration details for a device. This section normally appears only in "
2523 #: build/C/man7/man-pages.7:246
2525 msgid "B<DESCRIPTION>"
2528 #. If there is some kind of input grammar or complex set of subcommands,
2529 #. consider describing them in a separate
2531 #. section (and just place an overview in the
2535 #: build/C/man7/man-pages.7:263
2537 "gives an explanation of what the program, function, or format does. Discuss "
2538 "how it interacts with files and standard input, and what it produces on "
2539 "standard output or standard error. Omit internals and implementation "
2540 "details unless they're critical for understanding the interface. Describe "
2541 "the usual case; for information on command-line options of a program use the "
2542 "B<OPTIONS> section."
2546 #: build/C/man7/man-pages.7:271
2548 "When describing new behavior or new flags for a system call or library "
2549 "function, be careful to note the kernel or C library version that introduced "
2550 "the change. The preferred method of noting this information for flags is as "
2551 "part of a B<.TP> list, in the following form (here, for a new system call "
2556 #: build/C/man7/man-pages.7:272
2558 msgid "B<XYZ_FLAG> (since Linux 3.7)"
2562 #: build/C/man7/man-pages.7:275
2563 msgid "Description of flag..."
2567 #: build/C/man7/man-pages.7:280
2569 "Including version information is especially useful to users who are "
2570 "constrained to using older kernel or C library versions (which is typical in "
2571 "embedded systems, for example)."
2575 #: build/C/man7/man-pages.7:280
2582 #. describes the grammar of any sublanguage this implements.
2584 #: build/C/man7/man-pages.7:288
2586 "describes the command-line options accepted by a program and how they change "
2587 "its behavior. This section should appear only for Section 1 and 8 manual "
2592 #: build/C/man7/man-pages.7:288
2594 msgid "B<EXIT STATUS>"
2598 #: build/C/man7/man-pages.7:293
2600 "lists the possible exit status values of a program and the conditions that "
2601 "cause these values to be returned. This section should appear only for "
2602 "Section 1 and 8 manual pages."
2606 #: build/C/man7/man-pages.7:293
2608 msgid "B<RETURN VALUE>"
2612 #: build/C/man7/man-pages.7:298
2614 "For Section 2 and 3 pages, this section gives a list of the values the "
2615 "library routine will return to the caller and the conditions that cause "
2616 "these values to be returned."
2620 #: build/C/man7/man-pages.7:298
2626 #: build/C/man7/man-pages.7:306
2628 "For Section 2 and 3 manual pages, this is a list of the values that may be "
2629 "placed in I<errno> in the event of an error, along with information about "
2630 "the cause of the errors. I<The error list should be in alphabetical order>."
2634 #: build/C/man7/man-pages.7:306
2636 msgid "B<ENVIRONMENT>"
2640 #: build/C/man7/man-pages.7:310
2642 "lists all environment variables that affect the program or function and how "
2647 #: build/C/man7/man-pages.7:310
2652 #. May 07: Almost no current man pages have a DIAGNOSTICS section;
2653 #. "RETURN VALUE" or "EXIT STATUS" is preferred.
2656 #. gives an overview of the most common error messages and how to
2658 #. You don't need to explain system error messages
2659 #. or fatal signals that can appear during execution of any program
2660 #. unless they're special in some way to the program.
2662 #. May 07: Almost no current man pages have a SECURITY section.
2665 #. discusses security issues and implications.
2666 #. Warn about configurations or environments that should be avoided,
2667 #. commands that may have security implications, and so on, especially
2668 #. if they aren't obvious.
2669 #. Discussing security in a separate section isn't necessary;
2670 #. if it's easier to understand, place security information in the
2671 #. other sections (such as the
2676 #. However, please include security information somewhere!
2678 #: build/C/man7/man-pages.7:347
2680 "lists the files the program or function uses, such as configuration files, "
2681 "startup files, and files the program directly operates on. Give the full "
2682 "pathname of these files, and use the installation process to modify the "
2683 "directory part to match user preferences. For many programs, the default "
2684 "installation location is in I</usr/local>, so your base manual page should "
2685 "use I</usr/local> as the base."
2689 #: build/C/man7/man-pages.7:347
2691 msgid "B<ATTRIBUTES>"
2695 #: build/C/man7/man-pages.7:352
2697 "A summary of various attributes of the function(s) documented on this page, "
2698 "broken into subsections. The following subsections are defined:"
2702 #: build/C/man7/man-pages.7:354
2704 msgid "B<Multithreading (see pthreads(7))>"
2708 #: build/C/man7/man-pages.7:357
2709 msgid "This subsection notes attributes relating to multithreaded applications:"
2713 #: build/C/man7/man-pages.7:360
2714 msgid "Whether the function is thread-safe."
2718 #: build/C/man7/man-pages.7:362
2719 msgid "Whether the function is a cancellation point."
2723 #: build/C/man7/man-pages.7:364
2724 msgid "Whether the function is async-cancel-safe."
2728 #: build/C/man7/man-pages.7:368
2729 msgid "Details of these attributes can be found in B<pthreads>(7)."
2733 #: build/C/man7/man-pages.7:369
2739 #: build/C/man7/man-pages.7:386
2741 "A brief summary of the Linux kernel or glibc versions where a system call or "
2742 "library function appeared, or changed significantly in its operation. As a "
2743 "general rule, every new interface should include a VERSIONS section in its "
2744 "manual page. Unfortunately, many existing manual pages don't include this "
2745 "information (since there was no policy to do so when they were written). "
2746 "Patches to remedy this are welcome, but, from the perspective of programmers "
2747 "writing new code, this information probably matters only in the case of "
2748 "kernel interfaces that have been added in Linux 2.4 or later (i.e., changes "
2749 "since kernel 2.2), and library functions that have been added to glibc since "
2750 "version 2.1 (i.e., changes since glibc 2.0)."
2754 #: build/C/man7/man-pages.7:391
2756 "The B<syscalls>(2) manual page also provides information about kernel "
2757 "versions in which various system calls first appeared."
2761 #: build/C/man7/man-pages.7:391
2763 msgid "B<CONFORMING TO>"
2767 #: build/C/man7/man-pages.7:408
2769 "describes any standards or conventions that relate to the function or "
2770 "command described by the manual page. The preferred terms to use for the "
2771 "various standards are listed as headings in B<standards>(7). For a page in "
2772 "Section 2 or 3, this section should note the POSIX.1 version(s) that the "
2773 "call conforms to, and also whether the call is specified in C99. (Don't "
2774 "worry too much about other standards like SUS, SUSv2, and XPG, or the SVr4 "
2775 "and 4.xBSD implementation standards, unless the call was specified in those "
2776 "standards, but isn't in the current version of POSIX.1.) (See "
2781 #: build/C/man7/man-pages.7:412
2783 "If the call is not governed by any standards but commonly exists on other "
2784 "systems, note them. If the call is Linux-specific, note this."
2788 #: build/C/man7/man-pages.7:416
2790 "If this section consists of just a list of standards (which it commonly "
2791 "does), terminate the list with a period (\\(aq.\\(aq)."
2795 #: build/C/man7/man-pages.7:416
2801 #: build/C/man7/man-pages.7:421
2803 "provides miscellaneous notes. For Section 2 and 3 man pages you may find it "
2804 "useful to include subsections (B<SS>) named I<Linux Notes> and I<Glibc "
2809 #: build/C/man7/man-pages.7:421
2815 #: build/C/man7/man-pages.7:425
2817 "lists limitations, known defects or inconveniences, and other questionable "
2822 #: build/C/man7/man-pages.7:425
2828 #: build/C/man7/man-pages.7:431
2830 "provides one or more examples describing how this function, file or command "
2831 "is used. For details on writing example programs, see I<Example Programs> "
2836 #: build/C/man7/man-pages.7:431
2842 #: build/C/man7/man-pages.7:441
2844 "lists authors of the documentation or program. B<Use of an AUTHORS section "
2845 "is strongly discouraged>. Generally, it is better not to clutter every page "
2846 "with a list of (over time potentially numerous) authors; if you write or "
2847 "significantly amend a page, add a copyright notice as a comment in the "
2848 "source file. If you are the author of a device driver and want to include "
2849 "an address for reporting bugs, place this under the BUGS section."
2853 #: build/C/man7/man-pages.7:441
2859 #: build/C/man7/man-pages.7:448
2861 "provides a comma-separated list of related man pages, ordered by section "
2862 "number and then alphabetically by name, possibly followed by other related "
2863 "pages or documents. Do not terminate this with a period."
2867 #: build/C/man7/man-pages.7:459
2869 "Where the SEE ALSO list contains many long manual page names, to improve the "
2870 "visual result of the output, it may be useful to employ the I<.ad l> (don't "
2871 "right justify) and I<.nh> (don't hyphenate) directives. Hyphenation of "
2872 "individual page names can be prevented by preceding words with the string "
2877 #: build/C/man7/man-pages.7:459
2883 #: build/C/man7/man-pages.7:466
2885 "The following subsections describe the preferred style for the I<man-pages> "
2886 "project. For details not covered below, the Chicago Manual of Style is "
2887 "usually a good source; try also grepping for preexisting usage in the "
2888 "project source tree."
2892 #: build/C/man7/man-pages.7:466
2894 msgid "Use of gender-neutral language"
2898 #: build/C/man7/man-pages.7:471
2900 "As far as possible, use gender-neutral language in the text of man pages. "
2901 "Use of \"they\" (\"them\", \"themself\", \"their\") as a gender-neutral "
2902 "singular pronoun is acceptable."
2906 #: build/C/man7/man-pages.7:471
2908 msgid "Font conventions"
2912 #: build/C/man7/man-pages.7:476
2914 "For functions, the arguments are always specified using italics, I<even in "
2915 "the SYNOPSIS section>, where the rest of the function is specified in bold:"
2919 #: build/C/man7/man-pages.7:478
2920 msgid "B< int myfunction(int >I<argc>B<, char **>I<argv>B<);>"
2924 #: build/C/man7/man-pages.7:480
2925 msgid "Variable names should, like argument names, be specified in italics."
2929 #: build/C/man7/man-pages.7:490
2931 "Filenames (whether pathnames, or references to header files) are always in "
2932 "italics (e.g., I<E<lt>stdio.hE<gt>>), except in the SYNOPSIS section, where "
2933 "included files are in bold (e.g., B<#include E<lt>stdio.hE<gt>>). When "
2934 "referring to a standard header file include, specify the header file "
2935 "surrounded by angle brackets, in the usual C way (e.g., "
2936 "I<E<lt>stdio.hE<gt>>)."
2940 #: build/C/man7/man-pages.7:494
2942 "Special macros, which are usually in uppercase, are in bold (e.g., "
2943 "B<MAXINT>). Exception: don't boldface NULL."
2947 #: build/C/man7/man-pages.7:499
2949 "When enumerating a list of error codes, the codes are in bold (this list "
2950 "usually uses the B<\\&.TP> macro)."
2954 #: build/C/man7/man-pages.7:503
2956 "Complete commands should, if long, be written as an indented line on their "
2957 "own, with a blank line before and after the command, for example"
2961 #: build/C/man7/man-pages.7:507
2963 msgid "man 7 man-pages\n"
2967 #: build/C/man7/man-pages.7:517
2969 "If the command is short, then it can be included inline in the text, in "
2970 "italic format, for example, I<man 7 man-pages>. In this case, it may be "
2971 "worth using nonbreaking spaces (\"\\e\\ \") at suitable places in the "
2972 "command. Command options should be written in italics (e.g., I<-l>)."
2976 #: build/C/man7/man-pages.7:522
2978 "Expressions, if not written on a separate indented line, should be specified "
2979 "in italics. Again, the use of nonbreaking spaces may be appropriate if the "
2980 "expression is inlined with normal text."
2984 #: build/C/man7/man-pages.7:533
2986 "Any reference to the subject of the current manual page should be written "
2987 "with the name in bold. If the subject is a function (i.e., this is a "
2988 "Section 2 or 3 page), then the name should be followed by a pair of "
2989 "parentheses in Roman (normal) font. For example, in the B<fcntl>(2) man "
2990 "page, references to the subject of the page would be written as: "
2991 "B<fcntl>(). The preferred way to write this in the source file is:"
2995 #: build/C/man7/man-pages.7:536
2997 msgid " .BR fcntl ()\n"
3001 #: build/C/man7/man-pages.7:540
3003 "(Using this format, rather than the use of \"\\efB...\\efP()\" makes it "
3004 "easier to write tools that parse man page source files.)"
3008 #: build/C/man7/man-pages.7:549
3010 "Any reference to another man page should be written with the name in bold, "
3011 "I<always> followed by the section number, formatted in Roman (normal) font, "
3012 "without any separating spaces (e.g., B<intro>(2)). The preferred way to "
3013 "write this in the source file is:"
3017 #: build/C/man7/man-pages.7:552
3019 msgid " .BR intro (2)\n"
3023 #: build/C/man7/man-pages.7:557
3025 "(Including the section number in cross references lets tools like "
3026 "B<man2html>(1) create properly hyperlinked pages.)"
3030 #: build/C/man7/man-pages.7:561
3032 "Control characters should be written in bold face, with no quotes; for "
3037 #: build/C/man7/man-pages.7:561
3043 #: build/C/man7/man-pages.7:567
3045 "Starting with release 2.59, I<man-pages> follows American spelling "
3046 "conventions (previously, there was a random mix of British and American "
3047 "spellings); please write all new pages and patches according to these "
3052 #: build/C/man7/man-pages.7:570
3054 "Aside from the well-known spelling differences, there are a few other "
3055 "subtleties to watch for:"
3059 #: build/C/man7/man-pages.7:574
3061 "American English tends to use the forms \"backward\", \"upward\", "
3062 "\"toward\", and so on rather than the British forms \"backwards\", "
3063 "\"upwards\", \"towards\", and so on."
3067 #: build/C/man7/man-pages.7:574
3069 msgid "BSD version numbers"
3073 #: build/C/man7/man-pages.7:582
3075 "The classical scheme for writing BSD version numbers is I<x.yBSD>, where "
3076 "I<x.y> is the version number (e.g., 4.2BSD). Avoid forms such as I<BSD "
3081 #: build/C/man7/man-pages.7:582
3083 msgid "Capitalization"
3087 #: build/C/man7/man-pages.7:588
3089 "In subsection (\"SS\") headings, capitalize the first word in the heading, "
3090 "but otherwise use lowercase, except where English usage (e.g., proper nouns) "
3091 "or programming language requirements (e.g., identifier names) dictate "
3092 "otherwise. For example:"
3096 #: build/C/man7/man-pages.7:590
3097 msgid ".SS Unicode under Linux"
3101 #: build/C/man7/man-pages.7:591
3103 msgid "Indentation of structure definitions, shell session logs, and so on"
3107 #: build/C/man7/man-pages.7:597
3109 "When structure definitions, shell session logs, and so on are included in "
3110 "running text, indent them by 4 spaces (i.e., a block enclosed by I<.in\\ "
3115 #: build/C/man7/man-pages.7:597
3117 msgid "Preferred terms"
3121 #: build/C/man7/man-pages.7:600
3123 "The following table lists some preferred terms to use in man pages, mainly "
3124 "to ensure consistency across pages."
3128 #: build/C/man7/man-pages.7:604
3130 msgid "Term\tAvoid using\tNotes\n"
3134 #: build/C/man7/man-pages.7:606
3136 msgid "bit mask\tbitmask\n"
3140 #: build/C/man7/man-pages.7:607
3142 msgid "built-in\tbuiltin\n"
3146 #: build/C/man7/man-pages.7:608
3148 msgid "Epoch\tepoch\tT{\n"
3152 #: build/C/man7/man-pages.7:609
3154 msgid "For the UNIX Epoch (00:00:00, 1 Jan 1970 UTC)\n"
3158 #: build/C/man7/man-pages.7:610 build/C/man7/man-pages.7:621 build/C/man7/man-pages.7:625 build/C/man7/man-pages.7:630 build/C/man7/man-pages.7:634 build/C/man7/man-pages.7:640 build/C/man7/man-pages.7:644 build/C/man7/man-pages.7:669 build/C/man7/man-pages.7:672 build/C/man7/man-pages.7:675
3164 #: build/C/man7/man-pages.7:611
3166 msgid "filename\tfile name\n"
3170 #: build/C/man7/man-pages.7:612
3172 msgid "filesystem\tfile system\n"
3176 #: build/C/man7/man-pages.7:613
3178 msgid "hostname\thost name\n"
3182 #: build/C/man7/man-pages.7:614
3184 msgid "inode\ti-node\n"
3188 #: build/C/man7/man-pages.7:615
3190 msgid "lowercase\tlower case, lower-case\n"
3194 #: build/C/man7/man-pages.7:616
3196 msgid "pathname\tpath name\n"
3200 #: build/C/man7/man-pages.7:617
3202 msgid "pseudoterminal\tpseudo-terminal\n"
3206 #: build/C/man7/man-pages.7:618
3208 msgid "privileged port\tT{\n"
3212 #: build/C/man7/man-pages.7:619
3214 msgid "reserved port,\n"
3218 #: build/C/man7/man-pages.7:620
3220 msgid "system port\n"
3224 #: build/C/man7/man-pages.7:622
3226 msgid "real-time\tT{\n"
3230 #: build/C/man7/man-pages.7:623
3236 #: build/C/man7/man-pages.7:624
3242 #: build/C/man7/man-pages.7:626
3244 msgid "run time\truntime\n"
3248 #: build/C/man7/man-pages.7:627
3250 msgid "saved set-group-ID\tT{\n"
3254 #: build/C/man7/man-pages.7:628
3256 msgid "saved group ID,\n"
3260 #: build/C/man7/man-pages.7:629
3262 msgid "saved set-GID\n"
3266 #: build/C/man7/man-pages.7:631
3268 msgid "saved set-user-ID\tT{\n"
3272 #: build/C/man7/man-pages.7:632
3274 msgid "saved user ID,\n"
3278 #: build/C/man7/man-pages.7:633
3280 msgid "saved set-UID\n"
3284 #: build/C/man7/man-pages.7:635
3286 msgid "set-group-ID\tset-GID, setgid\n"
3290 #: build/C/man7/man-pages.7:636
3292 msgid "set-user-ID\tset-UID, setuid\n"
3296 #: build/C/man7/man-pages.7:637
3298 msgid "superuser\tT{\n"
3302 #: build/C/man7/man-pages.7:638
3304 msgid "super user,\n"
3308 #: build/C/man7/man-pages.7:639
3310 msgid "super-user\n"
3314 #: build/C/man7/man-pages.7:641
3316 msgid "superblock\tT{\n"
3320 #: build/C/man7/man-pages.7:642
3322 msgid "super block,\n"
3326 #: build/C/man7/man-pages.7:643
3328 msgid "super-block\n"
3332 #: build/C/man7/man-pages.7:645
3334 msgid "timestamp\ttime stamp\n"
3338 #: build/C/man7/man-pages.7:646
3340 msgid "timezone\ttime zone\n"
3344 #: build/C/man7/man-pages.7:647
3346 msgid "uppercase\tupper case, upper-case\n"
3350 #: build/C/man7/man-pages.7:648
3352 msgid "usable\tuseable\n"
3356 #: build/C/man7/man-pages.7:649
3358 msgid "user space\tuserspace\n"
3362 #: build/C/man7/man-pages.7:650
3364 msgid "username\tuser name\n"
3368 #: build/C/man7/man-pages.7:651
3370 msgid "zeros\tzeroes\n"
3374 #: build/C/man7/man-pages.7:657
3375 msgid "See also the discussion I<Hyphenation of attributive compounds> below."
3379 #: build/C/man7/man-pages.7:657
3381 msgid "Terms to avoid"
3385 #: build/C/man7/man-pages.7:661
3387 "The following table lists some terms to avoid using in man pages, along with "
3388 "some suggested alternatives, mainly to ensure consistency across pages."
3392 #: build/C/man7/man-pages.7:665
3394 msgid "Avoid\tUse instead\tNotes\n"
3398 #: build/C/man7/man-pages.7:667
3400 msgid "32bit\t32-bit\tT{\n"
3404 #: build/C/man7/man-pages.7:668
3406 msgid "same for 8-bit, 16-bit, etc.\n"
3410 #: build/C/man7/man-pages.7:670
3412 msgid "current process\tcalling process\tT{\n"
3416 #: build/C/man7/man-pages.7:671
3418 msgid "A common mistake made by kernel programmers when writing man pages\n"
3422 #: build/C/man7/man-pages.7:673
3424 msgid "manpage\tT{\n"
3428 #: build/C/man7/man-pages.7:674
3430 msgid "man page, manual page\n"
3434 #: build/C/man7/man-pages.7:676
3436 msgid "minus infinity\tnegative infinity\n"
3440 #: build/C/man7/man-pages.7:677
3442 msgid "non-root\tunprivileged user\n"
3446 #: build/C/man7/man-pages.7:678
3448 msgid "non-superuser\tunprivileged user\n"
3452 #: build/C/man7/man-pages.7:679
3454 msgid "nonprivileged\tunprivileged\n"
3458 #: build/C/man7/man-pages.7:680
3460 msgid "OS\toperating system\n"
3464 #: build/C/man7/man-pages.7:681
3466 msgid "plus infinity\tpositive infinity\n"
3470 #: build/C/man7/man-pages.7:682
3472 msgid "pty\tpseudoterminal\n"
3476 #: build/C/man7/man-pages.7:683
3478 msgid "tty\tterminal\n"
3482 #: build/C/man7/man-pages.7:684
3484 msgid "Unices\tUNIX systems\n"
3488 #: build/C/man7/man-pages.7:685
3490 msgid "Unixes\tUNIX systems\n"
3494 #: build/C/man7/man-pages.7:687
3500 #: build/C/man7/man-pages.7:691
3502 "Use the correct spelling and case for trademarks. The following is a list "
3503 "of the correct spellings of various relevant trademarks that are sometimes "
3508 #: build/C/man7/man-pages.7:696
3518 #: build/C/man7/man-pages.7:696
3520 msgid "NULL, NUL, null pointer, and null character"
3524 #: build/C/man7/man-pages.7:708
3526 "A I<null pointer> is a pointer that points to nothing, and is normally "
3527 "indicated by the constant I<NULL>. On the other hand, I<NUL> is the I<null "
3528 "byte>, a byte with the value 0, represented in C via the character constant "
3529 "I<\\(aq\\e0\\(aq>."
3533 #: build/C/man7/man-pages.7:711
3535 "The preferred term for the pointer is \"null pointer\" or simply \"NULL\"; "
3536 "avoid writing \"NULL pointer\"."
3540 #: build/C/man7/man-pages.7:719
3542 "The preferred term for the byte is \"null byte\". Avoid writing \"NUL\", "
3543 "since it is too easily confused with \"NULL\". Avoid also the terms \"zero "
3544 "byte\" and \"null character\". The byte that terminates a C string should "
3545 "be described as \"the terminating null byte\"; strings may be described as "
3546 "\"null-terminated\", but avoid the use of \"NUL-terminated\"."
3550 #: build/C/man7/man-pages.7:719
3556 #: build/C/man7/man-pages.7:727
3558 "For hyperlinks, use the I<.UR>/I<.UE> macro pair (see B<groff_man>(7)). "
3559 "This produces proper hyperlinks that can be used in a web browser, when "
3560 "rendering a page with, say:"
3564 #: build/C/man7/man-pages.7:729
3566 msgid " BROWSER=firefox man -H pagename\n"
3570 #: build/C/man7/man-pages.7:729
3572 msgid "Use of e.g., i.e., etc., a.k.a., and similar"
3576 #: build/C/man7/man-pages.7:733
3578 "In general, the use of abbreviations such as \"e.g.\", \"i.e.\", \"etc.\", "
3579 "\"a.k.a.\" should be avoided, in favor of suitable full wordings (\"for "
3580 "example\", \"that is\", \"and so on\", \"also known as\")."
3584 #: build/C/man7/man-pages.7:737
3586 "The only place where such abbreviations may be acceptable is in I<short> "
3587 "parenthetical asides (e.g., like this one)."
3591 #: build/C/man7/man-pages.7:740
3593 "Always include periods in such abbreviations, as shown here. In addition, "
3594 "\"e.g.\" and \"i.e.\" should always be followed by a comma."
3598 #: build/C/man7/man-pages.7:740
3604 #: build/C/man7/man-pages.7:748
3606 "The way to write an em-dash\\(emthe glyph that appears at either end of this "
3607 "subphrase\\(emin *roff is with the macro \"\\e(em\". (On an ASCII terminal, "
3608 "an em-dash typically renders as two hyphens, but in other typographical "
3609 "contexts it renders as a long dash.) Em-dashes should be written I<without> "
3610 "surrounding spaces."
3614 #: build/C/man7/man-pages.7:748
3616 msgid "Hyphenation of attributive compounds"
3620 #: build/C/man7/man-pages.7:751
3622 "Compound terms should be hyphenated when used attributively (i.e., to "
3623 "qualify a following noun). Some examples:"
3627 #: build/C/man7/man-pages.7:758
3631 " command-line argument\n"
3632 " floating-point number\n"
3634 " user-space function\n"
3635 " wide-character string\n"
3639 #: build/C/man7/man-pages.7:758
3641 msgid "Hyphenation with multi, non, pre, re, sub, and so on"
3645 #: build/C/man7/man-pages.7:764
3647 "The general tendency in modern English is not to hyphenate after prefixes "
3648 "such as \"multi\", \"non\", \"pre\", \"re\", \"sub\", and so on. Manual "
3649 "pages should generally follow this rule when these prefixes are used in "
3650 "natural English constructions with simple suffixes. The following list "
3651 "gives some examples of the preferred forms:"
3655 #: build/C/man7/man-pages.7:785
3681 #: build/C/man7/man-pages.7:789
3683 "Hyphens should be retained when the prefixes are used in nonstandard English "
3684 "words, with trademarks, proper nouns, acronyms, or compound terms. Some "
3689 #: build/C/man7/man-pages.7:794
3699 #: build/C/man7/man-pages.7:797
3701 "Finally, note that \"re-create\" and \"recreate\" are two different verbs, "
3702 "and the former is probably what you want."
3706 #: build/C/man7/man-pages.7:797
3708 msgid "Real minus character"
3712 #: build/C/man7/man-pages.7:802
3714 "Where a real minus character is required (e.g., for numbers such as -1, or "
3715 "when writing options that have a leading dash, such as in I<ls\\ -l>), use "
3716 "the following form in the man page source:"
3720 #: build/C/man7/man-pages.7:804
3726 #: build/C/man7/man-pages.7:806
3727 msgid "This guideline applies also to code examples."
3731 #: build/C/man7/man-pages.7:806
3733 msgid "Character constants"
3737 #: build/C/man7/man-pages.7:809
3739 "To produce single quotes that render well in both ASCII and UTF-8, use the "
3740 "following form for character constants in the man page source:"
3744 #: build/C/man7/man-pages.7:811
3746 msgid " \\e(aqC\\e(aq\n"
3750 #: build/C/man7/man-pages.7:816
3752 "where I<C> is the quoted character. This guideline applies also to "
3753 "character constants used in code examples."
3757 #: build/C/man7/man-pages.7:816
3759 msgid "Example programs and shell sessions"
3763 #: build/C/man7/man-pages.7:820
3765 "Manual pages may include example programs demonstrating how to use a system "
3766 "call or library function. However, note the following:"
3770 #: build/C/man7/man-pages.7:822
3771 msgid "Example programs should be written in C."
3775 #: build/C/man7/man-pages.7:828
3777 "An example program is necessary and useful only if it demonstrates something "
3778 "beyond what can easily be provided in a textual description of the "
3779 "interface. An example program that does nothing other than call an "
3780 "interface usually serves little purpose."
3784 #: build/C/man7/man-pages.7:831
3786 "Example programs should be fairly short (preferably less than 100 lines; "
3787 "ideally less than 50 lines)."
3791 #: build/C/man7/man-pages.7:834
3793 "Example programs should do error checking after system calls and library "
3798 #: build/C/man7/man-pages.7:837
3800 "Example programs should be complete, and compile without warnings when "
3801 "compiled with I<cc\\ -Wall>."
3805 #: build/C/man7/man-pages.7:842
3807 "Where possible and appropriate, example programs should allow "
3808 "experimentation, by varying their behavior based on inputs (ideally from "
3809 "command-line arguments, or alternatively, via input read by the program)."
3813 #: build/C/man7/man-pages.7:846
3815 "Example programs should be laid out according to Kernighan and Ritchie "
3816 "style, with 4-space indents. (Avoid the use of TAB characters in source "
3821 #: build/C/man7/man-pages.7:848
3822 msgid "For consistency, all example programs should terminate using either of:"
3826 #: build/C/man7/man-pages.7:851
3829 " exit(EXIT_SUCCESS);\n"
3830 " exit(EXIT_FAILURE);\n"
3834 #: build/C/man7/man-pages.7:853
3835 msgid "Avoid using the following forms to terminate a program:"
3839 #: build/C/man7/man-pages.7:857
3848 #: build/C/man7/man-pages.7:863
3850 "If there is extensive explanatory text before the program source code, mark "
3851 "off the source code with a subsection heading I<Program source>, as in:"
3855 #: build/C/man7/man-pages.7:865
3856 msgid ".SS Program source"
3860 #: build/C/man7/man-pages.7:867
3861 msgid "Always do this if the explanatory text includes a shell session log."
3865 #: build/C/man7/man-pages.7:870
3867 "If you include a shell session log demonstrating the use of a program or "
3868 "other system feature:"
3872 #: build/C/man7/man-pages.7:872
3873 msgid "Place the session log above the source code listing"
3877 #: build/C/man7/man-pages.7:874
3878 msgid "Indent the session log by four spaces."
3882 #: build/C/man7/man-pages.7:877
3884 "Boldface the user input text, to distinguish it from output produced by the "
3889 #: build/C/man7/man-pages.7:882
3891 "For some examples of what example programs should look like, see B<wait>(2) "
3896 #: build/C/man7/man-pages.7:889
3898 "For canonical examples of how man pages in the I<man-pages> package should "
3899 "look, see B<pipe>(2) and B<fcntl>(2)."
3903 #: build/C/man7/man-pages.7:896
3905 "B<man>(1), B<man2html>(1), B<groff>(7), B<groff_man>(7), B<man>(7), "
3910 #: build/C/man7/man.7:34
3916 #: build/C/man7/man.7:34 build/C/man7/units.7:26
3922 #: build/C/man7/man.7:37
3923 msgid "man - macros to format man pages"
3927 #: build/C/man7/man.7:41
3928 msgid "B<groff -Tascii -man> I<file> \\&..."
3932 #: build/C/man7/man.7:45
3933 msgid "B<groff -Tps -man> I<file> \\&..."
3937 #: build/C/man7/man.7:62
3939 "This manual page explains the B<groff an.tmac> macro package (often called "
3940 "the B<man> macro package). This macro package should be used by developers "
3941 "when writing or porting man pages for Linux. It is fairly compatible with "
3942 "other versions of this macro package, so porting man pages should not be a "
3943 "major problem (exceptions include the NET-2 BSD release, which uses a "
3944 "totally different macro package called mdoc; see B<mdoc>(7))."
3948 #: build/C/man7/man.7:74
3950 "Note that NET-2 BSD mdoc man pages can be used with B<groff> simply by "
3951 "specifying the B<-mdoc> option instead of the B<-man> option. Using the "
3952 "B<-mandoc> option is, however, recommended, since this will automatically "
3953 "detect which macro package is in use."
3957 #: build/C/man7/man.7:78
3959 "For conventions that should be employed when writing man pages for the Linux "
3960 "I<man-pages> package, see B<man-pages>(7)."
3964 #: build/C/man7/man.7:81
3966 "The first command in a man page (after comment lines, that is, lines that "
3967 "start with B<.\\e\">) should be"
3971 #: build/C/man7/man.7:91
3973 "For details of the arguments that should be supplied to the B<TH> command, "
3974 "see B<man-pages>(7)."
3978 #: build/C/man7/man.7:97
3980 "Note that BSD mdoc-formatted pages begin with the B<Dd> command, not the "
3985 #: build/C/man7/man.7:97
3990 #. The following doesn't seem to be required (see Debian bug 411303),
3991 #. If the name contains spaces and appears
3992 #. on the same line as
3994 #. then place the heading in double quotes.
3996 #: build/C/man7/man.7:106
3997 msgid "Sections are started with B<\\&.SH> followed by the heading name."
4001 #: build/C/man7/man.7:109
4003 "The only mandatory heading is NAME, which should be the first section and be "
4004 "followed on the next line by a one-line description of the program:"
4008 #: build/C/man7/man.7:112
4013 #: build/C/man7/man.7:114
4014 msgid "item \\e- description"
4018 #: build/C/man7/man.7:128
4020 "It is extremely important that this format is followed, and that there is a "
4021 "backslash before the single dash which follows the item name. This syntax "
4022 "is used by the B<mandb>(8) program to create a database of short "
4023 "descriptions for the B<whatis>(1) and B<apropos>(1) commands. (See "
4024 "B<lexgrog>(1) for further details on the syntax of the NAME section.)"
4028 #: build/C/man7/man.7:131
4030 "For a list of other sections that might appear in a manual page, see "
4035 #: build/C/man7/man.7:131
4041 #: build/C/man7/man.7:133
4042 msgid "The commands to select the type face are:"
4046 #: build/C/man7/man.7:133
4052 #: build/C/man7/man.7:136
4057 #: build/C/man7/man.7:136
4063 #: build/C/man7/man.7:140
4065 "Bold alternating with italics (especially useful for function "
4070 #: build/C/man7/man.7:140
4076 #: build/C/man7/man.7:145
4078 "Bold alternating with Roman (especially useful for referring to other manual "
4083 #: build/C/man7/man.7:145
4089 #: build/C/man7/man.7:148
4094 #: build/C/man7/man.7:148
4100 #: build/C/man7/man.7:151
4101 msgid "Italics alternating with bold"
4105 #: build/C/man7/man.7:151
4111 #: build/C/man7/man.7:154
4112 msgid "Italics alternating with Roman"
4116 #: build/C/man7/man.7:154
4122 #: build/C/man7/man.7:157
4123 msgid "Roman alternating with bold"
4127 #: build/C/man7/man.7:157
4133 #: build/C/man7/man.7:160
4134 msgid "Roman alternating with italics"
4138 #: build/C/man7/man.7:160
4144 #: build/C/man7/man.7:163
4145 msgid "Small alternating with bold"
4149 #: build/C/man7/man.7:163
4155 #: build/C/man7/man.7:166
4156 msgid "Small (useful for acronyms)"
4160 #: build/C/man7/man.7:179
4162 "Traditionally, each command can have up to six arguments, but the GNU "
4163 "implementation removes this limitation (you might still want to limit "
4164 "yourself to 6 arguments for portability's sake). Arguments are delimited by "
4165 "spaces. Double quotes can be used to specify an argument which contains "
4166 "spaces. All of the arguments will be printed next to each other without "
4167 "intervening spaces, so that the B<\\&.BR> command can be used to specify a "
4168 "word in bold followed by a mark of punctuation in Roman. If no arguments "
4169 "are given, the command is applied to the following line of text."
4173 #: build/C/man7/man.7:179
4175 msgid "Other macros and strings"
4179 #: build/C/man7/man.7:199
4181 "Below are other relevant macros and predefined strings. Unless noted "
4182 "otherwise, all macros cause a break (end the current line of text). Many of "
4183 "these macros set or use the \"prevailing indent.\" The \"prevailing indent\" "
4184 "value is set by any macro with the parameter I<i> below; macros may omit "
4185 "I<i> in which case the current prevailing indent will be used. As a result, "
4186 "successive indented paragraphs can use the same indent without respecifying "
4187 "the indent value. A normal (nonindented) paragraph resets the prevailing "
4188 "indent value to its default value (0.5 inches). By default a given indent "
4189 "is measured in ens; try to use ens or ems as units for indents, since these "
4190 "will automatically adjust to font size changes. The other key macro "
4195 #: build/C/man7/man.7:199
4197 msgid "Normal paragraphs"
4201 #: build/C/man7/man.7:200
4207 #: build/C/man7/man.7:205 build/C/man7/man.7:210
4208 msgid "Same as B<\\&.PP> (begin a new paragraph)."
4212 #: build/C/man7/man.7:205
4218 #: build/C/man7/man.7:210
4224 #: build/C/man7/man.7:213
4225 msgid "Begin a new paragraph and reset prevailing indent."
4229 #: build/C/man7/man.7:213
4231 msgid "Relative margin indent"
4235 #: build/C/man7/man.7:214
4237 msgid "B<\\&.RS>I< i>"
4241 #: build/C/man7/man.7:225
4243 "Start relative margin indent: moves the left margin I<i> to the right (if "
4244 "I<i> is omitted, the prevailing indent value is used). A new prevailing "
4245 "indent is set to 0.5 inches. As a result, all following paragraph(s) will "
4246 "be indented until the corresponding B<\\&.RE>."
4250 #: build/C/man7/man.7:225
4256 #: build/C/man7/man.7:229
4258 "End relative margin indent and restores the previous value of the prevailing "
4263 #: build/C/man7/man.7:229
4265 msgid "Indented paragraph macros"
4269 #: build/C/man7/man.7:230
4271 msgid "B<\\&.HP>I< i>"
4275 #: build/C/man7/man.7:235
4277 "Begin paragraph with a hanging indent (the first line of the paragraph is at "
4278 "the left margin of normal paragraphs, and the rest of the paragraph's lines "
4283 #: build/C/man7/man.7:235
4285 msgid "B<\\&.IP>I< x i>"
4289 #: build/C/man7/man.7:256
4291 "Indented paragraph with optional hanging tag. If the tag I<x> is omitted, "
4292 "the entire following paragraph is indented by I<i>. If the tag I<x> is "
4293 "provided, it is hung at the left margin before the following indented "
4294 "paragraph (this is just like B<\\&.TP> except the tag is included with the "
4295 "command instead of being on the following line). If the tag is too long, "
4296 "the text after the tag will be moved down to the next line (text will not be "
4297 "lost or garbled). For bulleted lists, use this macro with \\e(bu (bullet) "
4298 "or \\e(em (em dash) as the tag, and for numbered lists, use the number or "
4299 "letter followed by a period as the tag; this simplifies translation to other "
4304 #: build/C/man7/man.7:256
4306 msgid "B<\\&.TP>I< i>"
4310 #: build/C/man7/man.7:263
4312 "Begin paragraph with hanging tag. The tag is given on the next line, but "
4313 "its results are like those of the B<\\&.IP> command."
4317 #: build/C/man7/man.7:263
4319 msgid "Hypertext link macros"
4323 #: build/C/man7/man.7:273
4325 "(Feature supported with B<groff> only.) In order to use hypertext link "
4326 "macros, it is necessary to load the B<www.tmac> macro package. Use the "
4327 "request B<.mso www.tmac> to do this."
4331 #: build/C/man7/man.7:273
4333 msgid "B<\\&.URL>I< url link trailer>"
4336 #. The following is a kludge to get a paragraph into the listing.
4338 #: build/C/man7/man.7:286
4340 "Inserts a hypertext link to the URI (URL) I<url>, with I<link> as the text "
4341 "of the link. The I<trailer> will be printed immediately afterward. When "
4342 "generating HTML this should translate into the HTML command B<E<lt>A "
4343 "HREF=\">I<url>B<\"E<gt>>I<link>B<E<lt>/AE<gt>>I<trailer>B<.>"
4346 #. The following is a kludge to get a paragraph into the listing.
4348 #: build/C/man7/man.7:293
4350 "This and other related macros are new, and many tools won't do anything with "
4351 "them, but since many tools (including troff) will simply ignore undefined "
4352 "macros (or at worst insert their text) these are safe to insert."
4355 #. The following is a kludge to get a paragraph into the listing.
4357 #: build/C/man7/man.7:302
4359 "It can be useful to define your own B<URL> macro in manual pages for the "
4360 "benefit of those viewing it with a roff viewer other than B<groff>. That "
4361 "way, the URL, link text, and trailer text (if any) are still visible."
4365 #: build/C/man7/man.7:305
4366 msgid "Here's an example:"
4370 #: build/C/man7/man.7:307
4375 #: build/C/man7/man.7:309
4376 msgid "\\e\\e$2 \\e(laURL: \\e\\e$1 \\e(ra\\e\\e$3"
4380 #: build/C/man7/man.7:311
4385 #: build/C/man7/man.7:313
4386 msgid "\\&.if \\en[.g] .mso www.tmac"
4390 #: build/C/man7/man.7:316
4391 msgid "\\&.TH I<...>"
4395 #: build/C/man7/man.7:318
4396 msgid "I<(later in the page)>"
4400 #: build/C/man7/man.7:320
4401 msgid "This software comes from the"
4405 #: build/C/man7/man.7:322
4406 msgid "\\&.URL \"http://www.gnu.org/\" \"GNU Project\" \" of the\""
4410 #: build/C/man7/man.7:324
4411 msgid "\\&.URL \"http://www.fsf.org/\" \"Free Software Foundation\" ."
4415 #: build/C/man7/man.7:334
4417 "In the above, if B<groff> is being used, the B<www.tmac> macro package's "
4418 "definition of the URL macro will supersede the locally defined one."
4422 #: build/C/man7/man.7:339
4424 "A number of other link macros are available. See B<groff_www>(7) for more "
4429 #: build/C/man7/man.7:339
4431 msgid "Miscellaneous macros"
4435 #: build/C/man7/man.7:340
4441 #: build/C/man7/man.7:344
4442 msgid "Reset tabs to default tab values (every 0.5 inches); does not cause a break."
4446 #: build/C/man7/man.7:344
4448 msgid "B<\\&.PD>I< d>"
4452 #: build/C/man7/man.7:349
4454 "Set inter-paragraph vertical distance to d (if omitted, d=0.4v); does not "
4459 #: build/C/man7/man.7:349
4461 msgid "B<\\&.SS>I< t>"
4465 #: build/C/man7/man.7:356
4467 "Subheading I<t> (like B<\\&.SH>, but used for a subsection inside a "
4472 #: build/C/man7/man.7:356
4474 msgid "Predefined strings"
4478 #: build/C/man7/man.7:360
4479 msgid "The B<man> package has the following predefined strings:"
4483 #: build/C/man7/man.7:360
4489 #: build/C/man7/man.7:362
4490 msgid "Registration Symbol: \\*R"
4494 #: build/C/man7/man.7:362
4500 #: build/C/man7/man.7:364
4501 msgid "Change to default font size"
4505 #: build/C/man7/man.7:364
4511 #: build/C/man7/man.7:366
4512 msgid "Trademark Symbol: \\*(Tm"
4516 #: build/C/man7/man.7:366
4522 #: build/C/man7/man.7:368
4523 msgid "Left angled double quote: ``"
4527 #: build/C/man7/man.7:368
4533 #: build/C/man7/man.7:370
4534 msgid "Right angled double quote: ''"
4538 #: build/C/man7/man.7:370
4544 #: build/C/man7/man.7:414
4546 "Although technically B<man> is a troff macro package, in reality a large "
4547 "number of other tools process man page files that don't implement all of "
4548 "troff's abilities. Thus, it's best to avoid some of troff's more exotic "
4549 "abilities where possible to permit these other tools to work correctly. "
4550 "Avoid using the various troff preprocessors (if you must, go ahead and use "
4551 "B<tbl>(1), but try to use the B<IP> and B<TP> commands instead for "
4552 "two-column tables). Avoid using computations; most other tools can't "
4553 "process them. Use simple commands that are easy to translate to other "
4554 "formats. The following troff macros are believed to be safe (though in many "
4555 "cases they will be ignored by translators): B<\\e\">, B<.>, B<ad>, B<bp>, "
4556 "B<br>, B<ce>, B<de>, B<ds>, B<el>, B<ie>, B<if>, B<fi>, B<ft>, B<hy>, B<ig>, "
4557 "B<in>, B<na>, B<ne>, B<nf>, B<nh>, B<ps>, B<so>, B<sp>, B<ti>, B<tr>."
4561 #: build/C/man7/man.7:437
4563 "You may also use many troff escape sequences (those sequences beginning with "
4564 "\\e). When you need to include the backslash character as normal text, use "
4565 "\\ee. Other sequences you may use, where x or xx are any characters and N "
4566 "is any digit, include: B<\\e'>, B<\\e`>, B<\\e->, B<\\e.>, B<\\e\">, "
4567 "B<\\e%>, B<\\e*x>, B<\\e*(xx>, B<\\e(xx>, B<\\e$N>, B<\\enx>, B<\\en(xx>, "
4568 "B<\\efx>, and B<\\ef(xx>. Avoid using the escape sequences for drawing "
4573 #: build/C/man7/man.7:468
4575 "Do not use the optional parameter for B<bp> (break page). Use only positive "
4576 "values for B<sp> (vertical space). Don't define a macro (B<de>) with the "
4577 "same name as a macro in this or the mdoc macro package with a different "
4578 "meaning; it's likely that such redefinitions will be ignored. Every "
4579 "positive indent (B<in>) should be paired with a matching negative indent "
4580 "(although you should be using the B<RS> and B<RE> macros instead). The "
4581 "condition test (B<if,ie>) should only have \\(aqt\\(aq or \\(aqn\\(aq as "
4582 "the condition. Only translations (B<tr>) that can be ignored should be "
4583 "used. Font changes (B<ft> and the B<\\ef> escape sequence) should only "
4584 "have the values 1, 2, 3, 4, R, I, B, P, or CW (the ft command may also have "
4589 #: build/C/man7/man.7:475
4591 "If you use capabilities beyond these, check the results carefully on several "
4592 "tools. Once you've confirmed that the additional capability is safe, let "
4593 "the maintainer of this document know about the safe command or sequence that "
4594 "should be added to this list."
4598 #: build/C/man7/man.7:477
4599 msgid "I</usr/share/groff/>[*/]I<tmac/an.tmac>"
4603 #: build/C/man7/man.7:479
4604 msgid "I</usr/man/whatis>"
4608 #: build/C/man7/man.7:493
4610 "By all means include full URLs (or URIs) in the text itself; some tools such "
4611 "as B<man2html>(1) can automatically turn them into hypertext links. You "
4612 "can also use the new B<URL> macro to identify links to related information. "
4613 "If you include URLs, use the full URL (e.g., E<.UR "
4614 "http://www.kernelnotes.org> E<.UE )> to ensure that tools can automatically "
4619 #: build/C/man7/man.7:502
4621 "Tools processing these files should open the file and examine the first "
4622 "nonwhitespace character. A period (.) or single quote (') at the beginning "
4623 "of a line indicates a troff-based file (such as man or mdoc). A left angle "
4624 "bracket (E<lt>) indicates an SGML/XML-based file (such as HTML or Docbook). "
4625 "Anything else suggests simple ASCII text (e.g., a \"catman\" result)."
4629 #: build/C/man7/man.7:513
4631 "Many man pages begin with B<\\'\\e\"> followed by a space and a list of "
4632 "characters, indicating how the page is to be preprocessed. For "
4633 "portability's sake to non-troff translators we recommend that you avoid "
4634 "using anything other than B<tbl>(1), and Linux can detect that "
4635 "automatically. However, you might want to include this information so your "
4636 "man page can be handled by other (less capable) systems. Here are the "
4637 "definitions of the preprocessors invoked by these characters:"
4641 #: build/C/man7/man.7:513
4647 #: build/C/man7/man.7:516
4652 #: build/C/man7/man.7:516
4658 #: build/C/man7/man.7:519
4663 #: build/C/man7/man.7:519
4669 #: build/C/man7/man.7:522
4674 #: build/C/man7/man.7:522
4680 #: build/C/man7/man.7:525
4685 #: build/C/man7/man.7:525
4691 #: build/C/man7/man.7:528
4696 #: build/C/man7/man.7:528
4702 #: build/C/man7/man.7:531
4707 #: build/C/man7/man.7:531 build/C/man7/suffixes.7:278 build/C/man7/mdoc.samples.7:2883
4713 #: build/C/man7/man.7:544
4715 "Most of the macros describe formatting (e.g., font type and spacing) instead "
4716 "of marking semantic content (e.g., this text is a reference to another "
4717 "page), compared to formats like mdoc and DocBook (even HTML has more "
4718 "semantic markings). This situation makes it harder to vary the B<man> "
4719 "format for different media, to make the formatting consistent for a given "
4720 "media, and to automatically insert cross-references. By sticking to the "
4721 "safe subset described above, it should be easier to automate transitioning "
4722 "to a different reference page format in the future."
4727 #. James Clark (jjc@jclark.com) wrote the implementation of the macro package.
4729 #. Rickard E. Faith (faith@cs.unc.edu) wrote the initial version of
4730 #. this manual page.
4732 #. Jens Schweikhardt (schweikh@noc.fdn.de) wrote the Linux Man-Page Mini-HOWTO
4733 #. (which influenced this manual page).
4735 #. David A. Wheeler (dwheeler@ida.org) heavily modified this
4736 #. manual page, such as adding detailed information on sections and macros.
4738 #: build/C/man7/man.7:560
4739 msgid "The Sun macro B<TX> is not implemented."
4743 #: build/C/man7/man.7:572
4745 "B<apropos>(1), B<groff>(1), B<lexgrog>(1), B<man>(1), B<man2html>(1), "
4746 "B<whatis>(1), B<groff_man>(7), B<groff_www>(7), B<man-pages>(7), B<mdoc>(7), "
4747 "B<mdoc.samples>(7)"
4751 #: build/C/man7/mdoc.7:42
4753 msgid "July 11, 1999"
4757 #: build/C/man7/mdoc.7:43
4763 #: build/C/man7/mdoc.7:47
4768 #: build/C/man7/mdoc.7:47
4770 msgid "quick reference guide for the"
4774 #: build/C/man7/mdoc.7:50
4775 msgid "E<.Nm \\-mdoc> macro package"
4779 #: build/C/man7/mdoc.7:54
4780 msgid "E<.Nm groff> E<.Fl m Ns Ar doc> E<.Ar files ...>"
4784 #: build/C/man7/mdoc.7:66
4786 "The E<.Nm \\-mdoc> package is a set of content-based and domain-based macros "
4787 "used to format the E<.Bx> man pages. The macro names and their meanings are "
4788 "listed below for quick reference; for a detailed explanation on using the "
4789 "package, see the tutorial sampler E<.Xr mdoc.samples 7>."
4793 #: build/C/man7/mdoc.7:71
4795 "Note that this is not the usual macro package for Linux documentation, "
4796 "although it is used for documentation of several widely used programs; see "
4801 #: build/C/man7/mdoc.7:80
4803 "The macros are described in two groups, the first includes the structural "
4804 "and physical page layout macros. The second contains the manual and general "
4805 "text domain macros which differentiate the E<.Nm \\-mdoc> package from other "
4806 "E<.Xr troff> formatting packages."
4810 #: build/C/man7/mdoc.7:80 build/C/man7/mdoc.samples.7:1811
4812 msgid "PAGE STRUCTURE DOMAIN"
4816 #: build/C/man7/mdoc.7:81
4818 msgid "Title Macros"
4822 #: build/C/man7/mdoc.7:84
4824 "To create a valid manual page, these three macros, in this order, are "
4829 #: build/C/man7/mdoc.7:85
4831 msgid "Li \"\\&.Dd \" Ar \"Month day, year\""
4835 #: build/C/man7/mdoc.7:87
4836 msgid "Document date."
4840 #: build/C/man7/mdoc.7:87
4842 msgid "Li \"\\&.Dt \" Ar \"DOCUMENT_TITLE [section] [volume]\""
4846 #: build/C/man7/mdoc.7:89
4847 msgid "Title, in uppercase."
4851 #: build/C/man7/mdoc.7:89
4853 msgid "Li \"\\&.Os \" Ar \"OPERATING_SYSTEM [version/release]\""
4857 #: build/C/man7/mdoc.7:92
4858 msgid "Operating system E<.Pq Tn BSD>."
4862 #: build/C/man7/mdoc.7:93
4864 msgid "Page Layout Macros"
4868 #: build/C/man7/mdoc.7:95
4869 msgid "Section headers, paragraph breaks, lists and displays."
4873 #: build/C/man7/mdoc.7:96
4879 #: build/C/man7/mdoc.7:99
4880 msgid "Section Headers. Valid headers, in the order of presentation:"
4884 #: build/C/man7/mdoc.7:100
4890 #: build/C/man7/mdoc.7:108
4892 "Name section, should include the E<.Ql \\&.Nm> or E<.Ql \\&.Fn> and the "
4893 "E<.Ql \\&.Nd> macros."
4897 #: build/C/man7/mdoc.7:108
4903 #: build/C/man7/mdoc.7:110
4908 #: build/C/man7/mdoc.7:110
4910 msgid "Ar DESCRIPTION"
4914 #: build/C/man7/mdoc.7:113
4915 msgid "General description, should include options and parameters."
4919 #: build/C/man7/mdoc.7:113
4921 msgid "Ar RETURN VALUE"
4925 #: build/C/man7/mdoc.7:115
4926 msgid "Sections two and three function calls."
4930 #: build/C/man7/mdoc.7:115
4932 msgid "Ar ENVIRONMENT"
4936 #: build/C/man7/mdoc.7:117
4937 msgid "Describe environment variables."
4941 #: build/C/man7/mdoc.7:117
4947 #: build/C/man7/mdoc.7:119
4948 msgid "Files associated with the subject."
4952 #: build/C/man7/mdoc.7:119
4958 #: build/C/man7/mdoc.7:121
4959 msgid "Examples and suggestions."
4963 #: build/C/man7/mdoc.7:121
4965 msgid "Ar DIAGNOSTICS"
4969 #: build/C/man7/mdoc.7:123
4970 msgid "Normally used for section four device interface diagnostics."
4974 #: build/C/man7/mdoc.7:123
4980 #: build/C/man7/mdoc.7:126
4981 msgid "Sections two and three error and signal handling."
4985 #: build/C/man7/mdoc.7:126
4991 #: build/C/man7/mdoc.7:128
4992 msgid "Cross references and citations."
4996 #: build/C/man7/mdoc.7:128
4998 msgid "Ar CONFORMING TO"
5002 #: build/C/man7/mdoc.7:130
5003 msgid "Conformance to standards if applicable."
5007 #: build/C/man7/mdoc.7:130
5013 #: build/C/man7/mdoc.7:133
5014 msgid "If a standard is not applicable, the history of the subject should be given."
5018 #: build/C/man7/mdoc.7:133
5024 #: build/C/man7/mdoc.7:135
5025 msgid "Gotchas and caveats."
5029 #: build/C/man7/mdoc.7:135
5035 #: build/C/man7/mdoc.7:138
5036 msgid "Customized headers may be added at the authors discretion."
5040 #: build/C/man7/mdoc.7:139
5046 #: build/C/man7/mdoc.7:141
5047 msgid "Subsection Headers."
5051 #: build/C/man7/mdoc.7:141
5057 #: build/C/man7/mdoc.7:144
5058 msgid "Paragraph Break. Vertical space (one line)."
5062 #: build/C/man7/mdoc.7:144 build/C/man7/mdoc.samples.7:2200
5068 #: build/C/man7/mdoc.7:147
5069 msgid "(D-one) Display-one Indent and display one text line."
5073 #: build/C/man7/mdoc.7:147 build/C/man7/mdoc.samples.7:2208
5079 #: build/C/man7/mdoc.7:150
5080 msgid "(D-ell) Display-one literal. Indent and display one line of literal text."
5084 #: build/C/man7/mdoc.7:150 build/C/man7/mdoc.samples.7:2228
5090 #: build/C/man7/mdoc.7:153
5091 msgid "Begin-display block. Display options:"
5095 #: build/C/man7/mdoc.7:154 build/C/man7/mdoc.samples.7:2248
5101 #: build/C/man7/mdoc.7:156
5102 msgid "Unjustified (ragged edges)."
5106 #: build/C/man7/mdoc.7:156 build/C/man7/mdoc.samples.7:2251
5112 #: build/C/man7/mdoc.7:158
5117 #: build/C/man7/mdoc.7:158 build/C/man7/mdoc.samples.7:2255
5123 #: build/C/man7/mdoc.7:160
5124 msgid "Literal text or code."
5128 #: build/C/man7/mdoc.7:160
5130 msgid "Fl file Ar name"
5134 #: build/C/man7/mdoc.7:164
5135 msgid "Read in named E<.Ar file> and display."
5139 #: build/C/man7/mdoc.7:164 build/C/man7/mdoc.samples.7:2267
5141 msgid "Fl offset Ar string"
5145 #: build/C/man7/mdoc.7:169
5146 msgid "Offset display. Acceptable E<.Ar string> values:"
5150 #: build/C/man7/mdoc.7:170 build/C/man7/mdoc.samples.7:2275
5156 #: build/C/man7/mdoc.7:172
5157 msgid "Align block on left (default)."
5161 #: build/C/man7/mdoc.7:172 build/C/man7/mdoc.samples.7:2279
5167 #: build/C/man7/mdoc.7:174
5168 msgid "Approximate center margin."
5172 #: build/C/man7/mdoc.7:174 build/C/man7/mdoc.samples.7:2284
5178 #: build/C/man7/mdoc.7:176
5179 msgid "Six constant width spaces (a tab)."
5183 #: build/C/man7/mdoc.7:176 build/C/man7/mdoc.samples.7:2293
5185 msgid "Ar indent-two"
5189 #: build/C/man7/mdoc.7:178
5194 #: build/C/man7/mdoc.7:178 build/C/man7/mdoc.samples.7:2295
5200 #: build/C/man7/mdoc.7:181
5201 msgid "Left aligns block 2 inches from right."
5205 #: build/C/man7/mdoc.7:181
5207 msgid "Ar xx Ns Cm n"
5211 #: build/C/man7/mdoc.7:188
5213 "Where E<.Ar xx> is a number from E<.No \\&4 Ns Cm n> to E<.No \\&9\\&9 Ns Cm "
5218 #: build/C/man7/mdoc.7:188
5224 #: build/C/man7/mdoc.7:192
5225 msgid "Where E<.Ar Aa> is a callable macro name."
5229 #: build/C/man7/mdoc.7:192
5235 #: build/C/man7/mdoc.7:196
5236 msgid "The width of E<.Ar string> is used."
5240 #: build/C/man7/mdoc.7:198
5246 #: build/C/man7/mdoc.7:200
5247 msgid "End-display (matches \\&.Bd)."
5251 #: build/C/man7/mdoc.7:200
5257 #: build/C/man7/mdoc.7:204
5258 msgid "Begin-list. Create lists or columns. Options:"
5262 #: build/C/man7/mdoc.7:205
5264 msgid "Ar List-types"
5268 #: build/C/man7/mdoc.7:207
5270 msgid "Fl bullet Ta \"Bullet Item List\""
5274 #: build/C/man7/mdoc.7:208
5276 msgid "Fl item Ta \"Unlabeled List\""
5280 #: build/C/man7/mdoc.7:209
5282 msgid "Fl enum Ta \"Enumerated List\""
5286 #: build/C/man7/mdoc.7:210
5288 msgid "Fl tag Ta \"Tag Labeled List\""
5292 #: build/C/man7/mdoc.7:211
5294 msgid "Fl diag Ta \"Diagnostic List\""
5298 #: build/C/man7/mdoc.7:212
5300 msgid "Fl hang Ta \"Hanging Labeled List\""
5304 #: build/C/man7/mdoc.7:213
5306 msgid "Fl ohang Ta \"Overhanging Labeled List\""
5310 #: build/C/man7/mdoc.7:214
5312 msgid "Fl inset Ta \"Inset or Run-on Labeled List\""
5316 #: build/C/man7/mdoc.7:216
5318 msgid "List-parameters"
5322 #: build/C/man7/mdoc.7:218
5328 #: build/C/man7/mdoc.7:222
5329 msgid "(All lists.) See E<.Ql \\&.Bd> begin-display above."
5333 #: build/C/man7/mdoc.7:222
5339 #: build/C/man7/mdoc.7:229
5340 msgid "E<.Pf ( Fl tag> and E<.Fl hang> lists only.) See E<.Ql \\&.Bd>."
5344 #: build/C/man7/mdoc.7:229
5350 #: build/C/man7/mdoc.7:232
5351 msgid "(All lists.) Suppresses blank lines."
5355 #: build/C/man7/mdoc.7:234
5361 #: build/C/man7/mdoc.7:236
5366 #: build/C/man7/mdoc.7:236
5372 #: build/C/man7/mdoc.7:238
5377 #: build/C/man7/mdoc.7:239
5379 msgid "MANUAL AND GENERAL TEXT DOMAIN MACROS"
5383 #: build/C/man7/mdoc.7:243
5385 "The manual and general text domain macros are special in that most of them "
5386 "are parsed for callable macros for example:"
5390 #: build/C/man7/mdoc.7:244
5392 msgid "Li \"\\&.Op Fl s Ar file\""
5396 #: build/C/man7/mdoc.7:247
5397 msgid "Produces E<.Op Fl s Ar file>"
5401 #: build/C/man7/mdoc.7:265
5403 "In this example, the option enclosure macro E<.Ql \\&.Op> is parsed, and "
5404 "calls the callable content macro E<.Ql \\&Fl> which operates on the argument "
5405 "E<.Ql s> and then calls the callable content macro E<.Ql \\&Ar> which "
5406 "operates on the argument E<.Ql file>. Some macros may be callable, but are "
5407 "not parsed and vice versa. These macros are indicated in the E<.Em parsed> "
5408 "and E<.Em callable> columns below."
5412 #: build/C/man7/mdoc.7:267
5413 msgid "Unless stated, manual domain macros share a common syntax:"
5417 #: build/C/man7/mdoc.7:268
5419 msgid "\\&.Va argument [\\ .\\ ,\\ ;\\ :\\ (\\ )\\ [\\ ]\\ argument ...\\ ]"
5423 #: build/C/man7/mdoc.7:288
5425 "E<.Sy Note>: Opening and closing punctuation characters are recognized as "
5426 "such only if they are presented one at a time. The string E<.Ql \"),\"> is "
5427 "not recognized as punctuation and will be output with a leading white space "
5428 "and in what ever font the calling macro uses. The argument list E<.Ql \"] ) "
5429 ",\"> is recognized as three sequential closing punctuation characters and a "
5430 "leading white space is not output between the characters and the previous "
5431 "argument (if any). The special meaning of a punctuation character may be "
5432 "escaped with the string E<.Ql \\e&>. For example the following string,"
5436 #: build/C/man7/mdoc.7:289
5438 msgid "Li \"\\&.Ar file1\\ , file2\\ , file3\\ )\\ .\""
5442 #: build/C/man7/mdoc.7:292
5443 msgid "Produces E<.Ar file1 , file2 , file3>)."
5447 #: build/C/man7/mdoc.7:294
5449 msgid "Manual Domain Macros"
5453 #: build/C/man7/mdoc.7:296 build/C/man7/mdoc.7:321
5455 msgid "Em \"Name\tParsed\tCallable\tDescription\""
5459 #: build/C/man7/mdoc.7:297
5461 msgid "Li \\&Ad Ta Yes Ta Yes Ta \"Address. (This macro may be deprecated.)\""
5465 #: build/C/man7/mdoc.7:298
5467 msgid "Li \\&An Ta Yes Ta Yes Ta \"Author name.\""
5471 #: build/C/man7/mdoc.7:299
5473 msgid "Li \\&Ar Ta Yes Ta Yes Ta \"Command-line argument.\""
5477 #: build/C/man7/mdoc.7:300
5480 "Li \\&Cd Ta \\&No Ta \\&No Ta \"Configuration declaration (section four "
5485 #: build/C/man7/mdoc.7:301
5487 msgid "Li \\&Cm Ta Yes Ta Yes Ta \"Command-line argument modifier.\""
5491 #: build/C/man7/mdoc.7:302
5493 msgid "Li \\&Dv Ta Yes Ta Yes Ta \"Defined variable (source code).\""
5497 #: build/C/man7/mdoc.7:303
5499 msgid "Li \\&Er Ta Yes Ta Yes Ta \"Error number (source code).\""
5503 #: build/C/man7/mdoc.7:304
5505 msgid "Li \\&Ev Ta Yes Ta Yes Ta \"Environment variable.\""
5509 #: build/C/man7/mdoc.7:305
5511 msgid "Li \\&Fa Ta Yes Ta Yes Ta \"Function argument.\""
5515 #: build/C/man7/mdoc.7:306
5517 msgid "Li \\&Fd Ta Yes Ta Yes Ta \"Function declaration.\""
5521 #: build/C/man7/mdoc.7:307
5523 msgid "Li \\&Fn Ta Yes Ta Yes Ta \"Function call (also .Fo and .Fc).\""
5527 #: build/C/man7/mdoc.7:308
5529 msgid "Li \\&Ic Ta Yes Ta Yes Ta \"Interactive command.\""
5533 #: build/C/man7/mdoc.7:309
5535 msgid "Li \\&Li Ta Yes Ta Yes Ta \"Literal text.\""
5539 #: build/C/man7/mdoc.7:310
5541 msgid "Li \\&Nm Ta Yes Ta Yes Ta \"Command name.\""
5545 #: build/C/man7/mdoc.7:311
5547 msgid "Li \\&Op Ta Yes Ta Yes Ta \"Option (also .Oo and .Oc).\""
5551 #: build/C/man7/mdoc.7:312
5553 msgid "Li \\&Ot Ta Yes Ta Yes Ta \"Old style function type (Fortran only).\""
5557 #: build/C/man7/mdoc.7:313
5559 msgid "Li \\&Pa Ta Yes Ta Yes Ta \"Pathname or filename.\""
5563 #: build/C/man7/mdoc.7:314
5565 msgid "Li \\&St Ta Yes Ta Yes Ta \"Standards (\\-p1003.2, \\-p1003.1 or \\-ansiC)\""
5569 #: build/C/man7/mdoc.7:315
5571 msgid "Li \\&Va Ta Yes Ta Yes Ta \"Variable name.\""
5575 #: build/C/man7/mdoc.7:316
5577 msgid "Li \\&Vt Ta Yes Ta Yes Ta \"Variable type (Fortran only).\""
5581 #: build/C/man7/mdoc.7:317
5583 msgid "Li \\&Xr Ta Yes Ta Yes Ta \"Manual Page Cross Reference.\""
5587 #: build/C/man7/mdoc.7:319
5589 msgid "General Text Domain Macros"
5593 #: build/C/man7/mdoc.7:322
5595 msgid "Li \\&%A Ta Yes Ta \\&No Ta \"Reference author.\""
5599 #: build/C/man7/mdoc.7:323
5601 msgid "Li \\&%B Ta Yes Ta Yes Ta \"Reference book title.\""
5605 #: build/C/man7/mdoc.7:324
5607 msgid "Li \\&%\\&C Ta \\&No Ta \\&No Ta \"Reference place of publishing (city).\""
5611 #: build/C/man7/mdoc.7:325
5613 msgid "Li \\&%\\&D Ta \\&No Ta \\&No Ta \"Reference date.\""
5617 #: build/C/man7/mdoc.7:326
5619 msgid "Li \\&%J Ta Yes Ta Yes Ta \"Reference journal title.\""
5623 #: build/C/man7/mdoc.7:327
5625 msgid "Li \\&%N Ta \\&No Ta \\&No Ta \"Reference issue number.\""
5629 #: build/C/man7/mdoc.7:328
5631 msgid "Li \\&%\\&O Ta \\&No Ta \\&No Ta \"Reference optional information.\""
5635 #: build/C/man7/mdoc.7:329
5637 msgid "Li \\&%P Ta \\&No Ta \\&No Ta \"Reference page number(s).\""
5641 #: build/C/man7/mdoc.7:330
5643 msgid "Li \\&%R Ta \\&No Ta \\&No Ta \"Reference report Name.\""
5647 #: build/C/man7/mdoc.7:331
5649 msgid "Li \\&%T Ta Yes Ta Yes Ta \"Reference article title.\""
5653 #: build/C/man7/mdoc.7:332
5655 msgid "Li \\&%V Ta \\&No Ta \\&No Ta \"Reference volume.\""
5659 #: build/C/man7/mdoc.7:333
5661 msgid "Li \\&Ac Ta Yes Ta Yes Ta \"Angle close quote.\""
5665 #: build/C/man7/mdoc.7:334
5667 msgid "Li \\&Ao Ta Yes Ta Yes Ta \"Angle open quote.\""
5671 #: build/C/man7/mdoc.7:335
5673 msgid "Li \\&Ap Ta Yes Ta Yes Ta Apostrophe."
5677 #: build/C/man7/mdoc.7:336
5679 msgid "Li \\&Aq Ta Yes Ta Yes Ta \"Angle quote.\""
5683 #: build/C/man7/mdoc.7:337
5685 msgid "Li \\&At Ta \\&No Ta \\&No Ta Tn \"AT&T UNIX\""
5689 #: build/C/man7/mdoc.7:338
5691 msgid "Li \\&Bc Ta Yes Ta Yes Ta \"Bracket close quote.\""
5695 #: build/C/man7/mdoc.7:339
5697 msgid "Li \\&Bf Ta \\&No Ta \\&No Ta \"Begin font mode.\""
5701 #: build/C/man7/mdoc.7:340
5703 msgid "Li \\&Bo Ta Yes Ta Yes Ta \"Bracket open quote.\""
5707 #: build/C/man7/mdoc.7:341
5709 msgid "Li \\&Bq Ta Yes Ta Yes Ta \"Bracket quote.\""
5713 #: build/C/man7/mdoc.7:342
5715 msgid "Li \\&Bx Ta Yes Ta Yes Ta Bx ."
5719 #: build/C/man7/mdoc.7:343
5721 msgid "Li \\&Db Ta \\&No Ta \\&No Ta \"Debug (default is \\*qoff\\*q)\""
5725 #: build/C/man7/mdoc.7:344
5727 msgid "Li \\&Dc Ta Yes Ta Yes Ta \"Double close quote.\""
5731 #: build/C/man7/mdoc.7:345
5733 msgid "Li \\&Do Ta Yes Ta Yes Ta \"Double open quote.\""
5737 #: build/C/man7/mdoc.7:346
5739 msgid "Li \\&Dq Ta Yes Ta Yes Ta \"Double quote.\""
5743 #: build/C/man7/mdoc.7:347
5745 msgid "Li \\&Ec Ta Yes Ta Yes Ta \"Enclose string close quote.\""
5749 #: build/C/man7/mdoc.7:348
5751 msgid "Li \\&Ef Ta \\&No Ta \\&No Ta \"End font mode.\""
5755 #: build/C/man7/mdoc.7:349
5757 msgid "Li \\&Em Ta Yes Ta Yes Ta \"Emphasis (traditional English).\""
5761 #: build/C/man7/mdoc.7:350
5763 msgid "Li \\&Eo Ta Yes Ta Yes Ta \"Enclose string open quote.\""
5767 #: build/C/man7/mdoc.7:351
5769 msgid "Li \\&Fx Ta \\&No Ta \\&No Ta Tn \"FreeBSD operating system\""
5773 #: build/C/man7/mdoc.7:352
5775 msgid "Li \\&No Ta Yes Ta Yes Ta \"Normal text (no-op).\""
5779 #: build/C/man7/mdoc.7:353
5781 msgid "Li \\&Ns Ta Yes Ta Yes Ta \"No space.\""
5785 #: build/C/man7/mdoc.7:354
5787 msgid "Li \\&Pc Ta Yes Ta Yes Ta \"Parenthesis close quote.\""
5791 #: build/C/man7/mdoc.7:355
5793 msgid "Li \\&Pf Ta Yes Ta \\&No Ta \"Prefix string.\""
5797 #: build/C/man7/mdoc.7:356
5799 msgid "Li \\&Po Ta Yes Ta Yes Ta \"Parenthesis open quote.\""
5803 #: build/C/man7/mdoc.7:357
5805 msgid "Li \\&Pq Ta Yes Ta Yes Ta \"Parentheses quote.\""
5809 #: build/C/man7/mdoc.7:358
5811 msgid "Li \\&Qc Ta Yes Ta Yes Ta \"Straight Double close quote.\""
5815 #: build/C/man7/mdoc.7:359
5817 msgid "Li \\&Ql Ta Yes Ta Yes Ta \"Quoted literal.\""
5821 #: build/C/man7/mdoc.7:360
5823 msgid "Li \\&Qo Ta Yes Ta Yes Ta \"Straight Double open quote.\""
5827 #: build/C/man7/mdoc.7:361
5829 msgid "Li \\&Qq Ta Yes Ta Yes Ta \"Straight Double quote.\""
5833 #: build/C/man7/mdoc.7:362
5835 msgid "Li \\&Re Ta \\&No Ta \\&No Ta \"Reference end.\""
5839 #: build/C/man7/mdoc.7:363
5841 msgid "Li \\&Rs Ta \\&No Ta \\&No Ta \"Reference start.\""
5845 #: build/C/man7/mdoc.7:364
5848 "Li \\&Rv Ta \\&No Ta \\&No Ta \"Return values (sections two and three "
5853 #: build/C/man7/mdoc.7:365
5855 msgid "Li \\&Sc Ta Yes Ta Yes Ta \"Single close quote.\""
5859 #: build/C/man7/mdoc.7:366
5861 msgid "Li \\&So Ta Yes Ta Yes Ta \"Single open quote.\""
5865 #: build/C/man7/mdoc.7:367
5867 msgid "Li \\&Sq Ta Yes Ta Yes Ta \"Single quote.\""
5871 #: build/C/man7/mdoc.7:368
5873 msgid "Li \\&Sm Ta \\&No Ta \\&No Ta \"Space mode (default is \\*qon\\*q)\""
5877 #: build/C/man7/mdoc.7:369
5879 msgid "Li \\&Sx Ta Yes Ta Yes Ta \"Section Cross Reference.\""
5883 #: build/C/man7/mdoc.7:370
5885 msgid "Li \\&Sy Ta Yes Ta Yes Ta \"Symbolic (traditional English).\""
5889 #: build/C/man7/mdoc.7:371
5891 msgid "Li \\&Tn Ta Yes Ta Yes Ta \"Trade or type name (small Caps).\""
5895 #: build/C/man7/mdoc.7:372
5897 msgid "Li \\&Ux Ta Yes Ta Yes Ta Ux"
5901 #: build/C/man7/mdoc.7:373
5903 msgid "Li \\&Xc Ta Yes Ta Yes Ta \"Extend argument list close.\""
5907 #: build/C/man7/mdoc.7:374
5909 msgid "Li \\&Xo Ta Yes Ta Yes Ta \"Extend argument list open.\""
5913 #: build/C/man7/mdoc.7:388
5915 "Macro names ending in E<.Ql q> quote remaining items on the argument list. "
5916 "Macro names ending in E<.Ql o> begin a quote which may span more than one "
5917 "line of input and are close quoted with the matching macro name ending in "
5918 "E<.Ql c>. Enclosure macros may be nested and are limited to eight "
5923 #: build/C/man7/mdoc.7:400
5925 "Note: the extended argument list macros E<.Pf ( Ql \\&.Xo>, E<.Ql \\&.Xc>) "
5926 "and the function enclosure macros E<.Pf ( Ql \\&.Fo>, E<.Ql \\&.Fc>) are "
5927 "irregular. The extended list macros are used when the number of macro "
5928 "arguments would exceed the E<.Xr troff> limitation of nine arguments."
5931 #. The following does not apply on Linux:
5932 #. .Sh CONFIGURATION
5933 #. For site specific configuration of the macro package,
5935 #. .Pa /usr/src/share/tmac/README .
5937 #: build/C/man7/mdoc.7:411
5939 "The macros UR (starting a URI/URL hypertext reference), UE (ending one), and "
5940 "UN (identifying a target for a reference) are also available. See E<.Xr man "
5941 "7> for more information on these macros."
5945 #: build/C/man7/mdoc.7:413
5951 #: build/C/man7/mdoc.7:415
5952 msgid "Manual and general text domain macros."
5956 #: build/C/man7/mdoc.7:415
5958 msgid "Pa tmac/doc-common"
5962 #: build/C/man7/mdoc.7:417
5963 msgid "Common structural macros and definitions."
5967 #: build/C/man7/mdoc.7:417
5969 msgid "Pa tmac/doc-nroff"
5973 #: build/C/man7/mdoc.7:421
5974 msgid "Site dependent E<.Xr nroff> style file."
5978 #: build/C/man7/mdoc.7:421
5980 msgid "Pa tmac/doc-ditroff"
5984 #: build/C/man7/mdoc.7:425
5985 msgid "Site dependent E<.Xr troff> style file."
5989 #: build/C/man7/mdoc.7:425
5991 msgid "Pa tmac/doc-syms"
5995 #: build/C/man7/mdoc.7:427
5996 msgid "Special defines (such as the standards macro)."
6000 #: build/C/man7/mdoc.7:433
6001 msgid "E<.Xr groff_mdoc 7>, E<.Xr mdoc.samples 7>, E<.Xr man 7>, E<.Xr man-pages 7>"
6005 #: build/C/man7/mdoc.7:441 build/C/man7/mdoc.samples.7:2965
6007 "This page is part of release 3.68 of the Linux E<.Em man-pages> project. A "
6008 "description of the project, information about reporting bugs, and the latest "
6009 "version of this page, can be found at "
6010 "\\%http://www.kernel.org/doc/man\\-pages/."
6014 #: build/C/man7/operator.7:40
6020 #: build/C/man7/operator.7:40
6026 #: build/C/man7/operator.7:43
6027 msgid "operator - C operator precedence and order of evaluation"
6031 #: build/C/man7/operator.7:45
6032 msgid "This manual page lists C operators and their precedence in evaluation."
6036 #: build/C/man7/operator.7:63
6039 "B<Operator Associativity>\n"
6040 "() [] -E<gt> . left to right\n"
6041 "! ~ ++ -- + - (type) * & sizeof right to left\n"
6042 "* / % left to right\n"
6043 "+ - left to right\n"
6044 "E<lt>E<lt> E<gt>E<gt> left to right\n"
6045 "E<lt> E<lt>= E<gt> E<gt>= left to right\n"
6046 "== != left to right\n"
6050 "&& left to right\n"
6051 "|| left to right\n"
6052 "?: right to left\n"
6053 "= += -= *= /= %= E<lt>E<lt>= E<gt>E<gt>= &= ^= |= right to left\n"
6058 #: build/C/man7/posixoptions.7:24
6060 msgid "POSIXOPTIONS"
6064 #: build/C/man7/posixoptions.7:24
6070 #: build/C/man7/posixoptions.7:27
6071 msgid "posixoptions - optional parts of the POSIX standard"
6075 #: build/C/man7/posixoptions.7:41
6077 "The POSIX standard (the information below is from POSIX.1-2001) describes a "
6078 "set of behaviors and interfaces for a compliant system. However, many "
6079 "interfaces are optional and there are feature test macros to test the "
6080 "availability of interfaces at compile time, and functions B<sysconf>(3), "
6081 "B<fpathconf>(3), B<pathconf>(3), B<confstr>(3) to do this at run time. "
6082 "From shell scripts one can use B<getconf>(1). For more detail, see "
6087 #: build/C/man7/posixoptions.7:48
6089 "We give the name of the POSIX abbreviation, the option, the name of the "
6090 "B<sysconf>(3) parameter used to inquire about the option, and possibly a "
6091 "very short description. Much more precise detail can be found in the POSIX "
6092 "standard itself, versions of which can nowadays be accessed freely on the "
6097 #: build/C/man7/posixoptions.7:48
6099 msgid "ADV - _POSIX_ADVISORY_INFO - _SC_ADVISORY_INFO"
6103 #: build/C/man7/posixoptions.7:50
6104 msgid "The following advisory functions are present:"
6108 #: build/C/man7/posixoptions.7:58
6111 "I<posix_fadvise>(),\n"
6112 "I<posix_fallocate>(),\n"
6113 "I<posix_memalign>(),\n"
6114 "I<posix_madvise>().\n"
6118 #: build/C/man7/posixoptions.7:61
6120 msgid "AIO - _POSIX_ASYNCHRONOUS_IO - _SC_ASYNCHRONOUS_IO"
6124 #: build/C/man7/posixoptions.7:66
6126 "The header I<E<lt>aio.hE<gt>> is present. The following functions are "
6131 #: build/C/man7/posixoptions.7:78
6134 "I<aio_cancel>(),\n"
6138 "I<aio_return>(),\n"
6139 "I<aio_suspend>(),\n"
6141 "I<lio_listio>().\n"
6145 #: build/C/man7/posixoptions.7:81
6147 msgid "BAR - _POSIX_BARRIERS - _SC_BARRIERS"
6151 #: build/C/man7/posixoptions.7:88 build/C/man7/posixoptions.7:458
6153 "This option implies the B<_POSIX_THREADS> and "
6154 "B<_POSIX_THREAD_SAFE_FUNCTIONS> options. The following functions are "
6159 #: build/C/man7/posixoptions.7:97
6162 "I<pthread_barrier_destroy>(),\n"
6163 "I<pthread_barrier_init>(),\n"
6164 "I<pthread_barrier_wait>(),\n"
6165 "I<pthread_barrierattr_destroy>(),\n"
6166 "I<pthread_barrierattr_init>().\n"
6170 #. Batch environment.
6174 #: build/C/man7/posixoptions.7:104
6176 msgid "--- - POSIX_CHOWN_RESTRICTED"
6179 #. What about lchown() ?
6181 #: build/C/man7/posixoptions.7:112
6183 "If this option is in effect (as it always is under POSIX.1-2001), then only "
6184 "root may change the owner of a file, and nonroot can set the group of a file "
6185 "only to one of the groups it belongs to. This affects the functions "
6186 "I<chown>(), I<fchown>()."
6190 #: build/C/man7/posixoptions.7:112
6192 msgid "CS - _POSIX_CLOCK_SELECTION - _SC_CLOCK_SELECTION"
6196 #: build/C/man7/posixoptions.7:117
6198 "This option implies the B<_POSIX_TIMERS> option. The following functions "
6203 #: build/C/man7/posixoptions.7:124
6206 "I<pthread_condattr_getclock>(),\n"
6207 "I<pthread_condattr_setclock>(),\n"
6208 "I<clock_nanosleep>().\n"
6212 #: build/C/man7/posixoptions.7:132
6214 "If B<CLOCK_REALTIME> is changed by the function I<clock_settime>(), then "
6215 "this affects all timers set for an absolute time."
6219 #: build/C/man7/posixoptions.7:132
6221 msgid "CPT - _POSIX_CPUTIME - _SC_CPUTIME"
6225 #. Fortran development
6229 #: build/C/man7/posixoptions.7:145
6231 "The clockID CLOCK_PROCESS_CPUTIME_ID is supported. The initial value of "
6232 "this clock is 0 for each process. This option implies the B<_POSIX_TIMERS> "
6233 "option. The function I<clock_getcpuclockid>() is present."
6237 #: build/C/man7/posixoptions.7:145
6239 msgid "--- - _POSIX_FILE_LOCKING - _SC_FILE_LOCKING"
6243 #. IEC 60559 Floating-Point Option.
6245 #: build/C/man7/posixoptions.7:148 build/C/man7/posixoptions.7:238
6246 msgid "This option has been deleted. Not in final XPG6."
6250 #: build/C/man7/posixoptions.7:148
6252 msgid "FSC - _POSIX_FSYNC - _SC_FSYNC"
6256 #: build/C/man7/posixoptions.7:152
6257 msgid "The function I<fsync>() is present."
6261 #: build/C/man7/posixoptions.7:152
6263 msgid "IP6 - _POSIX_IPV6 - _SC_IPV6"
6267 #: build/C/man7/posixoptions.7:154
6268 msgid "Internet Protocol Version 6 is supported."
6272 #: build/C/man7/posixoptions.7:154
6274 msgid "--- - _POSIX_JOB_CONTROL - _SC_JOB_CONTROL"
6278 #: build/C/man7/posixoptions.7:158
6280 "If this option is in effect (as it always is under POSIX.1-2001), then the "
6281 "system implements POSIX-style job control, and the following functions are "
6286 #: build/C/man7/posixoptions.7:169
6293 "I<tcsendbreak>(),\n"
6299 #: build/C/man7/posixoptions.7:171
6301 msgid "MF - _POSIX_MAPPED_FILES - _SC_MAPPED_FILES"
6305 #: build/C/man7/posixoptions.7:180
6307 "Shared memory is supported. The include file I<E<lt>sys/mman.hE<gt>> is "
6308 "present. The following functions are present: I<mmap>(), I<msync>(), "
6313 #: build/C/man7/posixoptions.7:180
6315 msgid "ML - _POSIX_MEMLOCK - _SC_MEMLOCK"
6319 #: build/C/man7/posixoptions.7:186
6321 "Shared memory can be locked into core. The functions I<mlockall>(), "
6322 "I<munlockall>() are present."
6326 #: build/C/man7/posixoptions.7:186
6328 msgid "MR/MLR - _POSIX_MEMLOCK_RANGE - _SC_MEMLOCK_RANGE"
6332 #: build/C/man7/posixoptions.7:192
6334 "More precisely, ranges can be locked into core. The functions I<mlock>(), "
6335 "I<munlock>() are present."
6339 #: build/C/man7/posixoptions.7:192
6341 msgid "MPR - _POSIX_MEMORY_PROTECTION - _SC_MEMORY_PROTECTION"
6345 #: build/C/man7/posixoptions.7:196
6346 msgid "The function I<mprotect>() is present."
6350 #: build/C/man7/posixoptions.7:196
6352 msgid "MSG - _POSIX_MESSAGE_PASSING - _SC_MESSAGE_PASSING"
6356 #: build/C/man7/posixoptions.7:201
6358 "The include file I<E<lt>mqueue.hE<gt>> is present. The following functions "
6363 #: build/C/man7/posixoptions.7:213
6367 "I<mq_getattr>(),\n"
6370 "I<mq_receive>(),\n"
6372 "I<mq_setattr>(),\n"
6377 #: build/C/man7/posixoptions.7:216
6379 msgid "MON - _POSIX_MONOTONIC_CLOCK - _SC_MONOTONIC_CLOCK"
6383 #: build/C/man7/posixoptions.7:223
6385 "B<CLOCK_MONOTONIC> is supported. This option implies the B<_POSIX_TIMERS> "
6386 "option. Affected functions are"
6390 #: build/C/man7/posixoptions.7:231
6393 "I<aio_suspend>(),\n"
6394 "I<clock_getres>(),\n"
6395 "I<clock_gettime>(),\n"
6396 "I<clock_settime>(),\n"
6397 "I<timer_create>().\n"
6401 #: build/C/man7/posixoptions.7:233
6403 msgid "--- - _POSIX_MULTI_PROCESS - _SC_MULTI_PROCESS"
6407 #: build/C/man7/posixoptions.7:238
6409 msgid "--- - _POSIX_NO_TRUNC"
6413 #: build/C/man7/posixoptions.7:245
6415 "If this option is in effect (as it always is under POSIX.1-2001) then "
6416 "pathname components longer than B<NAME_MAX> are not truncated, but give an "
6417 "error. This property may be dependent on the path prefix of the component."
6421 #: build/C/man7/posixoptions.7:245
6423 msgid "PIO - _POSIX_PRIORITIZED_IO - _SC_PRIORITIZED_IO"
6427 #: build/C/man7/posixoptions.7:248
6429 "This option says that one can specify priorities for asynchronous I/O. This "
6430 "affects the functions"
6434 #: build/C/man7/posixoptions.7:254
6442 #: build/C/man7/posixoptions.7:256
6444 msgid "PS - _POSIX_PRIORITY_SCHEDULING - _SC_PRIORITY_SCHEDULING"
6448 #: build/C/man7/posixoptions.7:261
6450 "The include file I<E<lt>sched.hE<gt>> is present. The following functions "
6455 #: build/C/man7/posixoptions.7:273
6458 "I<sched_get_priority_max>(),\n"
6459 "I<sched_get_priority_min>(),\n"
6460 "I<sched_getparam>(),\n"
6461 "I<sched_getscheduler>(),\n"
6462 "I<sched_rr_get_interval>(),\n"
6463 "I<sched_setparam>(),\n"
6464 "I<sched_setscheduler>(),\n"
6465 "I<sched_yield>().\n"
6469 #: build/C/man7/posixoptions.7:279
6471 "If also B<_POSIX_SPAWN> is in effect, then the following functions are "
6476 #: build/C/man7/posixoptions.7:287 build/C/man7/posixoptions.7:449
6479 "I<posix_spawnattr_getschedparam>(),\n"
6480 "I<posix_spawnattr_getschedpolicy>(),\n"
6481 "I<posix_spawnattr_setschedparam>(),\n"
6482 "I<posix_spawnattr_setschedpolicy>().\n"
6486 #: build/C/man7/posixoptions.7:289
6488 msgid "RS - _POSIX_RAW_SOCKETS"
6492 #: build/C/man7/posixoptions.7:294
6494 "Raw sockets are supported. Affected functions are I<getsockopt>(), "
6499 #: build/C/man7/posixoptions.7:294
6501 msgid "--- - _POSIX_READER_WRITER_LOCKS - _SC_READER_WRITER_LOCKS"
6505 #: build/C/man7/posixoptions.7:302
6507 "This option implies the B<_POSIX_THREADS> option. Conversely, under "
6508 "POSIX.1-2001 the B<_POSIX_THREADS> option implies this option."
6512 #: build/C/man7/posixoptions.7:304
6514 msgid "The following functions are present:\n"
6518 #: build/C/man7/posixoptions.7:315
6521 "I<pthread_rwlock_destroy>(),\n"
6522 "I<pthread_rwlock_init>(),\n"
6523 "I<pthread_rwlock_rdlock>(),\n"
6524 "I<pthread_rwlock_tryrdlock>(),\n"
6525 "I<pthread_rwlock_trywrlock>(),\n"
6526 "I<pthread_rwlock_unlock>(),\n"
6527 "I<pthread_rwlock_wrlock>(),\n"
6528 "I<pthread_rwlockattr_destroy>(),\n"
6529 "I<pthread_rwlockattr_init>().\n"
6533 #: build/C/man7/posixoptions.7:317
6535 msgid "RTS - _POSIX_REALTIME_SIGNALS - _SC_REALTIME_SIGNALS"
6539 #: build/C/man7/posixoptions.7:320
6540 msgid "Realtime signals are supported. The following functions are present:"
6544 #: build/C/man7/posixoptions.7:327
6548 "I<sigtimedwait>(),\n"
6549 "I<sigwaitinfo>().\n"
6553 #: build/C/man7/posixoptions.7:330
6555 msgid "--- - _POSIX_REGEXP - _SC_REGEXP"
6559 #: build/C/man7/posixoptions.7:334
6561 "If this option is in effect (as it always is under POSIX.1-2001) then POSIX "
6562 "regular expressions are supported and the following functions are present:"
6566 #: build/C/man7/posixoptions.7:342
6576 #: build/C/man7/posixoptions.7:345
6578 msgid "--- - _POSIX_SAVED_IDS - _SC_SAVED_IDS"
6582 #: build/C/man7/posixoptions.7:349
6584 "If this option is in effect (as it always is under POSIX.1-2001), then a "
6585 "process has a saved set-user-ID and a saved set-group-ID. Affected "
6590 #: build/C/man7/posixoptions.7:359
6602 #. Software development
6604 #: build/C/man7/posixoptions.7:364
6606 msgid "SEM - _POSIX_SEMAPHORES - _SC_SEMAPHORES"
6610 #: build/C/man7/posixoptions.7:369
6612 "The include file I<E<lt>semaphore.hE<gt>> is present. The following "
6613 "functions are present:"
6617 #: build/C/man7/posixoptions.7:382
6621 "I<sem_destroy>(),\n"
6622 "I<sem_getvalue>(),\n"
6626 "I<sem_trywait>(),\n"
6627 "I<sem_unlink>(),\n"
6632 #: build/C/man7/posixoptions.7:385
6634 msgid "SHM - _POSIX_SHARED_MEMORY_OBJECTS - _SC_SHARED_MEMORY_OBJECTS"
6638 #: build/C/man7/posixoptions.7:387 build/C/man7/posixoptions.7:703 build/C/man7/posixoptions.7:719 build/C/man7/posixoptions.7:833
6639 msgid "The following functions are present:"
6643 #: build/C/man7/posixoptions.7:395
6649 "I<shm_unlink>().\n"
6653 #: build/C/man7/posixoptions.7:398
6655 msgid "--- - _POSIX_SHELL - _SC_SHELL"
6659 #: build/C/man7/posixoptions.7:403
6661 "If this option is in effect (as it always is under POSIX.1-2001), the "
6662 "function I<system>() is present."
6666 #: build/C/man7/posixoptions.7:403
6668 msgid "SPN - _POSIX_SPAWN - _SC_SPAWN"
6672 #: build/C/man7/posixoptions.7:413
6674 "This option describes support for process creation in a context where it is "
6675 "difficult or impossible to use I<fork>(), for example, because no MMU is "
6676 "present. If B<_POSIX_SPAWN> is in effect, then the include file "
6677 "I<E<lt>spawn.hE<gt>> and the following functions are present:"
6681 #: build/C/man7/posixoptions.7:434
6684 "I<posix_spawn>(),\n"
6685 "I<posix_spawn_file_actions_addclose>(),\n"
6686 "I<posix_spawn_file_actions_adddup2>(),\n"
6687 "I<posix_spawn_file_actions_addopen>(),\n"
6688 "I<posix_spawn_file_actions_destroy>(),\n"
6689 "I<posix_spawn_file_actions_init>(),\n"
6690 "I<posix_spawnattr_destroy>(),\n"
6691 "I<posix_spawnattr_getsigdefault>(),\n"
6692 "I<posix_spawnattr_getflags>(),\n"
6693 "I<posix_spawnattr_getpgroup>(),\n"
6694 "I<posix_spawnattr_getsigmask>(),\n"
6695 "I<posix_spawnattr_init>(),\n"
6696 "I<posix_spawnattr_setsigdefault>(),\n"
6697 "I<posix_spawnattr_setflags>(),\n"
6698 "I<posix_spawnattr_setpgroup>(),\n"
6699 "I<posix_spawnattr_setsigmask>(),\n"
6700 "I<posix_spawnp>().\n"
6704 #: build/C/man7/posixoptions.7:441
6706 "If also B<_POSIX_PRIORITY_SCHEDULING> is in effect, then the following "
6707 "functions are present:"
6711 #: build/C/man7/posixoptions.7:451
6713 msgid "SPI - _POSIX_SPIN_LOCKS - _SC_SPIN_LOCKS"
6717 #: build/C/man7/posixoptions.7:467
6720 "I<pthread_spin_destroy>(),\n"
6721 "I<pthread_spin_init>(),\n"
6722 "I<pthread_spin_lock>(),\n"
6723 "I<pthread_spin_trylock>(),\n"
6724 "I<pthread_spin_unlock>().\n"
6728 #: build/C/man7/posixoptions.7:470
6730 msgid "SS - _POSIX_SPORADIC_SERVER - _SC_SPORADIC_SERVER"
6734 #: build/C/man7/posixoptions.7:478
6736 "The scheduling policy B<SCHED_SPORADIC> is supported. This option implies "
6737 "the B<_POSIX_PRIORITY_SCHEDULING> option. Affected functions are"
6741 #: build/C/man7/posixoptions.7:484
6744 "I<sched_setparam>(),\n"
6745 "I<sched_setscheduler>().\n"
6749 #: build/C/man7/posixoptions.7:487
6751 msgid "SIO - _POSIX_SYNCHRONIZED_IO - _SC_SYNCHRONIZED_IO"
6755 #: build/C/man7/posixoptions.7:493
6756 msgid "Affected functions are I<open>(), I<msync>(), I<fsync>(), I<fdatasync>()."
6760 #: build/C/man7/posixoptions.7:493
6762 msgid "TSA - _POSIX_THREAD_ATTR_STACKADDR - _SC_THREAD_ATTR_STACKADDR"
6766 #: build/C/man7/posixoptions.7:495 build/C/man7/posixoptions.7:508 build/C/man7/posixoptions.7:539 build/C/man7/posixoptions.7:550 build/C/man7/posixoptions.7:585 build/C/man7/posixoptions.7:602
6767 msgid "Affected functions are"
6771 #: build/C/man7/posixoptions.7:503
6774 "I<pthread_attr_getstack>(),\n"
6775 "I<pthread_attr_getstackaddr>(),\n"
6776 "I<pthread_attr_setstack>(),\n"
6777 "I<pthread_attr_setstackaddr>().\n"
6781 #: build/C/man7/posixoptions.7:506
6783 msgid "TSS - _POSIX_THREAD_ATTR_STACKSIZE - _SC_THREAD_ATTR_STACKSIZE"
6787 #: build/C/man7/posixoptions.7:516
6790 "I<pthread_attr_getstack>(),\n"
6791 "I<pthread_attr_getstacksize>(),\n"
6792 "I<pthread_attr_setstack>(),\n"
6793 "I<pthread_attr_setstacksize>().\n"
6797 #: build/C/man7/posixoptions.7:519
6799 msgid "TCT - _POSIX_THREAD_CPUTIME - _SC_THREAD_CPUTIME"
6803 #: build/C/man7/posixoptions.7:525
6805 "The clockID CLOCK_THREAD_CPUTIME_ID is supported. This option implies the "
6806 "B<_POSIX_TIMERS> option. Affected functions are"
6810 #: build/C/man7/posixoptions.7:534
6813 "I<pthread_getcpuclockid>(),\n"
6814 "I<clock_getres>(),\n"
6815 "I<clock_gettime>(),\n"
6816 "I<clock_settime>(),\n"
6817 "I<timer_create>().\n"
6821 #: build/C/man7/posixoptions.7:537
6823 msgid "TPI - _POSIX_THREAD_PRIO_INHERIT - _SC_THREAD_PRIO_INHERIT"
6827 #: build/C/man7/posixoptions.7:545
6830 "I<pthread_mutexattr_getprotocol>(),\n"
6831 "I<pthread_mutexattr_setprotocol>().\n"
6835 #: build/C/man7/posixoptions.7:548
6837 msgid "TPP - _POSIX_THREAD_PRIO_PROTECT - _SC_THREAD_PRIO_PROTECT"
6841 #: build/C/man7/posixoptions.7:560
6844 "I<pthread_mutex_getprioceiling>(),\n"
6845 "I<pthread_mutex_setprioceiling>(),\n"
6846 "I<pthread_mutexattr_getprioceiling>(),\n"
6847 "I<pthread_mutexattr_getprotocol>(),\n"
6848 "I<pthread_mutexattr_setprioceiling>(),\n"
6849 "I<pthread_mutexattr_setprotocol>().\n"
6853 #: build/C/man7/posixoptions.7:563
6855 msgid "TPS - _POSIX_THREAD_PRIORITY_SCHEDULING - _SC_THREAD_PRIORITY_SCHEDULING"
6859 #: build/C/man7/posixoptions.7:567
6861 "If this option is in effect, the different threads inside a process can run "
6862 "with different priorities and/or different schedulers. Affected functions "
6867 #: build/C/man7/posixoptions.7:580
6870 "I<pthread_attr_getinheritsched>(),\n"
6871 "I<pthread_attr_getschedpolicy>(),\n"
6872 "I<pthread_attr_getscope>(),\n"
6873 "I<pthread_attr_setinheritsched>(),\n"
6874 "I<pthread_attr_setschedpolicy>(),\n"
6875 "I<pthread_attr_setscope>(),\n"
6876 "I<pthread_getschedparam>(),\n"
6877 "I<pthread_setschedparam>(),\n"
6878 "I<pthread_setschedprio>().\n"
6882 #: build/C/man7/posixoptions.7:583
6884 msgid "TSH - _POSIX_THREAD_PROCESS_SHARED - _SC_THREAD_PROCESS_SHARED"
6888 #: build/C/man7/posixoptions.7:597
6891 "I<pthread_barrierattr_getpshared>(),\n"
6892 "I<pthread_barrierattr_setpshared>(),\n"
6893 "I<pthread_condattr_getpshared>(),\n"
6894 "I<pthread_condattr_setpshared>(),\n"
6895 "I<pthread_mutexattr_getpshared>(),\n"
6896 "I<pthread_mutexattr_setpshared>(),\n"
6897 "I<pthread_rwlockattr_getpshared>(),\n"
6898 "I<pthread_rwlockattr_setpshared>().\n"
6902 #: build/C/man7/posixoptions.7:600
6904 msgid "TSF - _POSIX_THREAD_SAFE_FUNCTIONS - _SC_THREAD_SAFE_FUNCTIONS"
6908 #: build/C/man7/posixoptions.7:625
6912 "I<getgrgid_r>(),\n"
6913 "I<getgrnam_r>(),\n"
6914 "I<getpwnam_r>(),\n"
6915 "I<getpwuid_r>(),\n"
6917 "I<ftrylockfile>(),\n"
6918 "I<funlockfile>(),\n"
6919 "I<getc_unlocked>(),\n"
6920 "I<getchar_unlocked>(),\n"
6921 "I<putc_unlocked>(),\n"
6922 "I<putchar_unlocked>(),\n"
6924 "I<strerror_r>(),\n"
6929 "I<localtime_r>().\n"
6933 #: build/C/man7/posixoptions.7:628
6935 msgid "TSP - _POSIX_THREAD_SPORADIC_SERVER - _SC_THREAD_SPORADIC_SERVER"
6939 #: build/C/man7/posixoptions.7:633
6941 "This option implies the B<_POSIX_THREAD_PRIORITY_SCHEDULING> option. "
6942 "Affected functions are"
6946 #: build/C/man7/posixoptions.7:640
6949 "I<sched_getparam>(),\n"
6950 "I<sched_setparam>(),\n"
6951 "I<sched_setscheduler>().\n"
6955 #: build/C/man7/posixoptions.7:643
6957 msgid "THR - _POSIX_THREADS - _SC_THREADS"
6961 #: build/C/man7/posixoptions.7:646
6963 "Basic support for POSIX threads is available. The following functions are "
6968 #: build/C/man7/posixoptions.7:698
6971 "I<pthread_atfork>(),\n"
6972 "I<pthread_attr_destroy>(),\n"
6973 "I<pthread_attr_getdetachstate>(),\n"
6974 "I<pthread_attr_getschedparam>(),\n"
6975 "I<pthread_attr_init>(),\n"
6976 "I<pthread_attr_setdetachstate>(),\n"
6977 "I<pthread_attr_setschedparam>(),\n"
6978 "I<pthread_cancel>(),\n"
6979 "I<pthread_cleanup_push>(),\n"
6980 "I<pthread_cleanup_pop>(),\n"
6981 "I<pthread_cond_broadcast>(),\n"
6982 "I<pthread_cond_destroy>(),\n"
6983 "I<pthread_cond_init>(),\n"
6984 "I<pthread_cond_signal>(),\n"
6985 "I<pthread_cond_timedwait>(),\n"
6986 "I<pthread_cond_wait>(),\n"
6987 "I<pthread_condattr_destroy>(),\n"
6988 "I<pthread_condattr_init>(),\n"
6989 "I<pthread_create>(),\n"
6990 "I<pthread_detach>(),\n"
6991 "I<pthread_equal>(),\n"
6992 "I<pthread_exit>(),\n"
6993 "I<pthread_getspecific>(),\n"
6994 "I<pthread_join>(),\n"
6995 "I<pthread_key_create>(),\n"
6996 "I<pthread_key_delete>(),\n"
6997 "I<pthread_mutex_destroy>(),\n"
6998 "I<pthread_mutex_init>(),\n"
6999 "I<pthread_mutex_lock>(),\n"
7000 "I<pthread_mutex_trylock>(),\n"
7001 "I<pthread_mutex_unlock>(),\n"
7002 "I<pthread_mutexattr_destroy>(),\n"
7003 "I<pthread_mutexattr_init>(),\n"
7004 "I<pthread_once>(),\n"
7005 "I<pthread_rwlock_destroy>(),\n"
7006 "I<pthread_rwlock_init>(),\n"
7007 "I<pthread_rwlock_rdlock>(),\n"
7008 "I<pthread_rwlock_tryrdlock>(),\n"
7009 "I<pthread_rwlock_trywrlock>(),\n"
7010 "I<pthread_rwlock_unlock>(),\n"
7011 "I<pthread_rwlock_wrlock>(),\n"
7012 "I<pthread_rwlockattr_destroy>(),\n"
7013 "I<pthread_rwlockattr_init>(),\n"
7014 "I<pthread_self>(),\n"
7015 "I<pthread_setcancelstate>(),\n"
7016 "I<pthread_setcanceltype>(),\n"
7017 "I<pthread_setspecific>(),\n"
7018 "I<pthread_testcancel>().\n"
7022 #: build/C/man7/posixoptions.7:701
7024 msgid "TMO - _POSIX_TIMEOUTS - _SC_TIMEOUTS"
7028 #: build/C/man7/posixoptions.7:714
7031 "I<mq_timedreceive>(),\n"
7032 "I<mq_timedsend>(),\n"
7033 "I<pthread_mutex_timedlock>(),\n"
7034 "I<pthread_rwlock_timedrdlock>(),\n"
7035 "I<pthread_rwlock_timedwrlock>(),\n"
7036 "I<sem_timedwait>(),\n"
7037 "I<posix_trace_timedgetnext_event>().\n"
7041 #: build/C/man7/posixoptions.7:717
7043 msgid "TMR - _POSIX_TIMERS - _SC_TIMERS"
7047 #: build/C/man7/posixoptions.7:732
7050 "I<clock_getres>(),\n"
7051 "I<clock_gettime>(),\n"
7052 "I<clock_settime>(),\n"
7054 "I<timer_create>(),\n"
7055 "I<timer_delete>(),\n"
7056 "I<timer_gettime>(),\n"
7057 "I<timer_getoverrun>(),\n"
7058 "I<timer_settime>().\n"
7062 #: build/C/man7/posixoptions.7:735
7064 msgid "TRC - _POSIX_TRACE - _SC_TRACE"
7068 #: build/C/man7/posixoptions.7:738
7069 msgid "POSIX tracing is available. The following functions are present:"
7073 #: build/C/man7/posixoptions.7:773
7076 "I<posix_trace_attr_destroy>(),\n"
7077 "I<posix_trace_attr_getclockres>(),\n"
7078 "I<posix_trace_attr_getcreatetime>(),\n"
7079 "I<posix_trace_attr_getgenversion>(),\n"
7080 "I<posix_trace_attr_getmaxdatasize>(),\n"
7081 "I<posix_trace_attr_getmaxsystemeventsize>(),\n"
7082 "I<posix_trace_attr_getmaxusereventsize>(),\n"
7083 "I<posix_trace_attr_getname>(),\n"
7084 "I<posix_trace_attr_getstreamfullpolicy>(),\n"
7085 "I<posix_trace_attr_getstreamsize>(),\n"
7086 "I<posix_trace_attr_init>(),\n"
7087 "I<posix_trace_attr_setmaxdatasize>(),\n"
7088 "I<posix_trace_attr_setname>(),\n"
7089 "I<posix_trace_attr_setstreamsize>(),\n"
7090 "I<posix_trace_attr_setstreamfullpolicy>(),\n"
7091 "I<posix_trace_clear>(),\n"
7092 "I<posix_trace_create>(),\n"
7093 "I<posix_trace_event>(),\n"
7094 "I<posix_trace_eventid_equal>(),\n"
7095 "I<posix_trace_eventid_get_name>(),\n"
7096 "I<posix_trace_eventid_open>(),\n"
7097 "I<posix_trace_eventtypelist_getnext_id>(),\n"
7098 "I<posix_trace_eventtypelist_rewind>(),\n"
7099 "I<posix_trace_flush>(),\n"
7100 "I<posix_trace_get_attr>(),\n"
7101 "I<posix_trace_get_status>(),\n"
7102 "I<posix_trace_getnext_event>(),\n"
7103 "I<posix_trace_shutdown>(),\n"
7104 "I<posix_trace_start>(),\n"
7105 "I<posix_trace_stop>(),\n"
7106 "I<posix_trace_trygetnext_event>().\n"
7110 #: build/C/man7/posixoptions.7:776
7112 msgid "TEF - _POSIX_TRACE_EVENT_FILTER - _SC_TRACE_EVENT_FILTER"
7116 #: build/C/man7/posixoptions.7:781 build/C/man7/posixoptions.7:816
7118 "This option implies the B<_POSIX_TRACE> option. The following functions are "
7123 #: build/C/man7/posixoptions.7:793
7126 "I<posix_trace_eventset_add>(),\n"
7127 "I<posix_trace_eventset_del>(),\n"
7128 "I<posix_trace_eventset_empty>(),\n"
7129 "I<posix_trace_eventset_fill>(),\n"
7130 "I<posix_trace_eventset_ismember>(),\n"
7131 "I<posix_trace_get_filter>(),\n"
7132 "I<posix_trace_set_filter>(),\n"
7133 "I<posix_trace_trid_eventid_open>().\n"
7137 #: build/C/man7/posixoptions.7:796
7139 msgid "TRI - _POSIX_TRACE_INHERIT - _SC_TRACE_INHERIT"
7143 #: build/C/man7/posixoptions.7:802
7145 "Tracing children of the traced process is supported. This option implies "
7146 "the B<_POSIX_TRACE> option. The following functions are present:"
7150 #: build/C/man7/posixoptions.7:808
7153 "I<posix_trace_attr_getinherited>(),\n"
7154 "I<posix_trace_attr_setinherited>().\n"
7158 #: build/C/man7/posixoptions.7:811
7160 msgid "TRL - _POSIX_TRACE_LOG - _SC_TRACE_LOG"
7164 #: build/C/man7/posixoptions.7:828
7167 "I<posix_trace_attr_getlogfullpolicy>(),\n"
7168 "I<posix_trace_attr_getlogsize>(),\n"
7169 "I<posix_trace_attr_setlogfullpolicy>(),\n"
7170 "I<posix_trace_attr_setlogsize>(),\n"
7171 "I<posix_trace_close>(),\n"
7172 "I<posix_trace_create_withlog>(),\n"
7173 "I<posix_trace_open>(),\n"
7174 "I<posix_trace_rewind>().\n"
7178 #: build/C/man7/posixoptions.7:831
7180 msgid "TYM - _POSIX_TYPED_MEMORY_OBJECTS - _SC_TYPED_MEMORY_OBJECT"
7184 #: build/C/man7/posixoptions.7:840
7187 "I<posix_mem_offset>(),\n"
7188 "I<posix_typed_mem_get_info>(),\n"
7189 "I<posix_typed_mem_open>().\n"
7193 #: build/C/man7/posixoptions.7:843
7195 msgid "--- - _POSIX_VDISABLE"
7199 #: build/C/man7/posixoptions.7:847
7201 "Always present (probably 0). Value to set a changeable special control "
7202 "character to indicate that it is disabled."
7206 #: build/C/man7/posixoptions.7:847
7208 msgid "XOPEN EXTENSIONS"
7213 #: build/C/man7/posixoptions.7:854
7215 "B<_XOPEN_CRYPT>, B<_XOPEN_LEGACY>, B<_XOPEN_REALTIME>, "
7216 "B<_XOPEN_REALTIME_THREADS>, B<_XOPEN_UNIX>."
7220 #: build/C/man7/posixoptions.7:857
7221 msgid "B<sysconf>(3), B<standards>(7)"
7225 #: build/C/man5/proc.5:62
7231 #: build/C/man5/proc.5:62
7237 #: build/C/man5/proc.5:65
7238 msgid "proc - process information pseudo-filesystem"
7242 #: build/C/man5/proc.5:74
7244 "The I<proc> filesystem is a pseudo-filesystem which provides an interface to "
7245 "kernel data structures. It is commonly mounted at I</proc>. Most of it is "
7246 "read-only, but some files allow kernel variables to be changed."
7250 #: build/C/man5/proc.5:78
7252 "The following list describes many of the files and directories under the "
7253 "I</proc> hierarchy."
7257 #: build/C/man5/proc.5:79
7259 msgid "I</proc/[pid]>"
7262 #. FIXME Describe /proc/[pid]/attr and
7263 #. /proc/[pid]/task/[tid]/attr
7264 #. This is a directory
7268 #: build/C/man5/proc.5:91
7270 "There is a numerical subdirectory for each running process; the subdirectory "
7271 "is named by the process ID. Each such subdirectory contains the following "
7272 "pseudo-files and directories."
7276 #: build/C/man5/proc.5:91
7278 msgid "I</proc/[pid]/auxv> (since 2.6.0-test7)"
7282 #: build/C/man5/proc.5:98
7284 "This contains the contents of the ELF interpreter information passed to the "
7285 "process at exec time. The format is one I<unsigned long> ID plus one "
7286 "I<unsigned long> value for each entry. The last entry contains two zeros."
7290 #: build/C/man5/proc.5:98
7292 msgid "I</proc/[pid]/cgroup> (since Linux 2.6.24)"
7295 #. Info in Documentation/cgroups/cgroups.txt
7297 #: build/C/man5/proc.5:104
7299 "This file describes control groups to which the process/task belongs. For "
7300 "each cgroup hierarchy there is one entry containing colon-separated fields "
7305 #: build/C/man5/proc.5:108
7307 msgid "CW< 5:cpuacct,cpu,cpuset:/daemons>\n"
7311 #: build/C/man5/proc.5:112
7312 msgid "The colon-separated fields are, from left to right:"
7316 #: build/C/man5/proc.5:113
7322 #: build/C/man5/proc.5:115
7323 msgid "hierarchy ID number"
7327 #: build/C/man5/proc.5:115
7333 #: build/C/man5/proc.5:117
7334 msgid "set of subsystems bound to the hierarchy"
7338 #: build/C/man5/proc.5:117
7344 #: build/C/man5/proc.5:119
7345 msgid "control group in the hierarchy to which the process belongs"
7349 #: build/C/man5/proc.5:124
7351 "This file is present only if the B<CONFIG_CGROUPS> kernel configuration "
7352 "option is enabled."
7356 #: build/C/man5/proc.5:124
7358 msgid "I</proc/[pid]/clear_refs> (since Linux 2.6.22)"
7361 #. commit b813e931b4c8235bb42e301096ea97dbdee3e8fe (2.6.22)
7362 #. commit 398499d5f3613c47f2143b8c54a04efb5d7a6da9 (2.6.32)
7363 #. commit 040fa02077de01c7e08fa75be6125e4ca5636011 (3.11)
7365 #. "Clears page referenced bits shown in smaps output"
7366 #. write-only, writable only by the owner of the process
7368 #: build/C/man5/proc.5:134
7369 msgid "This is a write-only file, writable only by owner of the process."
7373 #: build/C/man5/proc.5:136
7374 msgid "The following values may be written to the file:"
7378 #: build/C/man5/proc.5:137
7380 msgid "1 (since Linux 2.6.22)"
7383 #. Internally: CLEAR_REFS_ALL
7385 #: build/C/man5/proc.5:144
7387 "Reset the PG_Referenced and ACCESSED/YOUNG bits for all the pages associated "
7388 "with the process. (Before kernel 2.6.32, writing any nonzero value to this "
7389 "file had this effect.)"
7393 #: build/C/man5/proc.5:144
7395 msgid "2 (since Linux 2.6.32)"
7398 #. Internally: CLEAR_REFS_ANON
7400 #: build/C/man5/proc.5:149
7402 "Reset the PG_Referenced and ACCESSED/YOUNG bits for all anonymous pages "
7403 "associated with the process."
7407 #: build/C/man5/proc.5:149
7409 msgid "3 (since Linux 2.6.32)"
7412 #. Internally: CLEAR_REFS_MAPPED
7414 #: build/C/man5/proc.5:154
7416 "Reset the PG_Referenced and ACCESSED/YOUNG bits for all file-mapped pages "
7417 "associated with the process."
7421 #: build/C/man5/proc.5:170
7423 "Clearing the PG_Referenced and ACCESSED/YOUNG bits provides a method to "
7424 "measure approximately how much memory a process is using. One first "
7425 "inspects the values in the \"Referenced\" fields for the VMAs shown in "
7426 "I</proc/[pid]/smaps> to get an idea of the memory footprint of the process. "
7427 "One then clears the PG_Referenced and ACCESSED/YOUNG bits and, after some "
7428 "measured time interval, once again inspects the values in the \"Referenced\" "
7429 "fields to get an idea of the change in memory footprint of the process "
7430 "during the measured interval. If one is interested only in inspecting the "
7431 "selected mapping types, then the value 2 or 3 can be used instead of 1."
7435 #: build/C/man5/proc.5:172
7436 msgid "A further value can be written to affect a different bit:"
7440 #: build/C/man5/proc.5:173
7442 msgid "4 (since Linux 3.11)"
7445 #. Internally: CLEAR_REFS_SOFT_DIRTY
7447 #: build/C/man5/proc.5:183
7449 "Clear the soft-dirty bit for all the pages associated with the process. "
7450 "This is used (in conjunction with I</proc/[pid]/pagemap>) by the "
7451 "check-point restore system to discover which pages of a process have been "
7452 "dirtied since the file I</proc/[pid]/clear_refs> was written to."
7456 #: build/C/man5/proc.5:188
7458 "Writing any value to I</proc/[pid]/clear_refs> other than those listed above "
7463 #: build/C/man5/proc.5:194
7465 "The I</proc/[pid]/clear_refs> file is present only if the "
7466 "B<CONFIG_PROC_PAGE_MONITOR> kernel configuration option is enabled."
7470 #: build/C/man5/proc.5:194
7472 msgid "I</proc/[pid]/cmdline>"
7475 #. In 2.3.26, this also used to be true if the process was swapped out.
7477 #: build/C/man5/proc.5:204
7479 "This holds the complete command line for the process, unless the process is "
7480 "a zombie. In the latter case, there is nothing in this file: that is, a "
7481 "read on this file will return 0 characters. The command-line arguments "
7482 "appear in this file as a set of strings separated by null bytes "
7483 "(\\(aq\\e0\\(aq), with a further null byte after the last string."
7487 #: build/C/man5/proc.5:204
7489 msgid "I</proc/[pid]/coredump_filter> (since kernel 2.6.23)"
7493 #: build/C/man5/proc.5:208 build/C/man5/proc.5:3026 build/C/man5/proc.5:3030
7494 msgid "See B<core>(5)."
7498 #: build/C/man5/proc.5:208
7500 msgid "I</proc/[pid]/cpuset> (since kernel 2.6.12)"
7503 #. and/proc/[pid]/task/[tid]/cpuset
7505 #: build/C/man5/proc.5:213
7506 msgid "See B<cpuset>(7)."
7510 #: build/C/man5/proc.5:213
7512 msgid "I</proc/[pid]/cwd>"
7516 #: build/C/man5/proc.5:218
7518 "This is a symbolic link to the current working directory of the process. To "
7519 "find out the current working directory of process 20, for instance, you can "
7524 #: build/C/man5/proc.5:222
7526 msgid "$B< cd /proc/20/cwd; /bin/pwd>\n"
7530 #: build/C/man5/proc.5:233
7532 "Note that the I<pwd> command is often a shell built-in, and might not work "
7533 "properly. In B<bash>(1), you may use I<pwd\\ -P>."
7536 #. The following was still true as at kernel 2.6.13
7537 #. FIXME Describe /proc/[pid]/seccomp
7539 #. FIXME Describe /proc/[pid]/sessionid
7540 #. Added in 2.6.25; read-only; only readable by real UID
7541 #. CONFIG_AUDITSYSCALL
7542 #. FIXME Describe /proc/[pid]/sched
7544 #. CONFIG_SCHED_DEBUG, and additional fields if CONFIG_SCHEDSTATS
7545 #. Displays various scheduling parameters
7546 #. This file can be written, to reset stats
7547 #. FIXME Describe /proc/[pid]/schedstats and
7548 #. /proc/[pid]/task/[tid]/schedstats
7550 #. CONFIG_SCHEDSTATS
7552 #: build/C/man5/proc.5:239 build/C/man5/proc.5:1034
7554 "In a multithreaded process, the contents of this symbolic link are not "
7555 "available if the main thread has already terminated (typically by calling "
7556 "B<pthread_exit>(3))."
7560 #: build/C/man5/proc.5:239
7562 msgid "I</proc/[pid]/environ>"
7566 #: build/C/man5/proc.5:245
7568 "This file contains the environment for the process. The entries are "
7569 "separated by null bytes (\\(aq\\e0\\(aq), and there may be a null byte at "
7570 "the end. Thus, to print out the environment of process 1, you would do:"
7574 #: build/C/man5/proc.5:250
7576 msgid "$B< strings /proc/1/environ>\n"
7580 #: build/C/man5/proc.5:253
7582 msgid "I</proc/[pid]/exe>"
7585 #. The following was still true as at kernel 2.6.13
7587 #: build/C/man5/proc.5:268
7589 "Under Linux 2.2 and later, this file is a symbolic link containing the "
7590 "actual pathname of the executed command. This symbolic link can be "
7591 "dereferenced normally; attempting to open it will open the executable. You "
7592 "can even type I</proc/[pid]/exe> to run another copy of the same executable "
7593 "as is being run by process [pid]. In a multithreaded process, the contents "
7594 "of this symbolic link are not available if the main thread has already "
7595 "terminated (typically by calling B<pthread_exit>(3))."
7599 #: build/C/man5/proc.5:276
7601 "Under Linux 2.0 and earlier I</proc/[pid]/exe> is a pointer to the binary "
7602 "which was executed, and appears as a symbolic link. A B<readlink>(2) call "
7603 "on this file under Linux 2.0 returns a string in the format:"
7607 #: build/C/man5/proc.5:278
7609 msgid " [device]:inode\n"
7613 #: build/C/man5/proc.5:281
7615 "For example, [0301]:1502 would be inode 1502 on device major 03 (IDE, MFM, "
7616 "etc. drives) minor 01 (first partition on the first drive)."
7620 #: build/C/man5/proc.5:286
7621 msgid "B<find>(1) with the I<-inum> option can be used to locate the file."
7625 #: build/C/man5/proc.5:286
7627 msgid "I</proc/[pid]/fd/>"
7631 #: build/C/man5/proc.5:292
7633 "This is a subdirectory containing one entry for each file which the process "
7634 "has open, named by its file descriptor, and which is a symbolic link to the "
7635 "actual file. Thus, 0 is standard input, 1 standard output, 2 standard "
7640 #: build/C/man5/proc.5:299
7642 "For file descriptors for pipes and sockets, the entries will be symbolic "
7643 "links whose content is the file type with the inode. A B<readlink>(2) call "
7644 "on this file returns a string in the format:"
7648 #: build/C/man5/proc.5:301
7650 msgid " type:[inode]\n"
7654 #: build/C/man5/proc.5:308
7656 "For example, I<socket:[2248868]> will be a socket and its inode is 2248868. "
7657 "For sockets, that inode can be used to find more information in one of the "
7658 "files under I</proc/net/>."
7662 #: build/C/man5/proc.5:318
7664 "For file descriptors that have no corresponding inode (e.g., file "
7665 "descriptors produced by B<epoll_create>(2), B<eventfd>(2), "
7666 "B<inotify_init>(2), B<signalfd>(2), and B<timerfd>(2)), the entry will be a "
7667 "symbolic link with contents of the form"
7671 #: build/C/man5/proc.5:320
7673 msgid " anon_inode:E<lt>file-typeE<gt>\n"
7677 #: build/C/man5/proc.5:324
7678 msgid "In some cases, the I<file-type> is surrounded by square brackets."
7682 #: build/C/man5/proc.5:328
7684 "For example, an epoll file descriptor will have a symbolic link whose "
7685 "content is the string I<anon_inode:[eventpoll]>."
7688 #. The following was still true as at kernel 2.6.13
7690 #: build/C/man5/proc.5:334
7692 "In a multithreaded process, the contents of this directory are not available "
7693 "if the main thread has already terminated (typically by calling "
7694 "B<pthread_exit>(3))."
7698 #: build/C/man5/proc.5:347
7700 "Programs that will take a filename as a command-line argument, but will not "
7701 "take input from standard input if no argument is supplied, or that write to "
7702 "a file named as a command-line argument, but will not send their output to "
7703 "standard output if no argument is supplied, can nevertheless be made to use "
7704 "standard input or standard out using I</proc/[pid]/fd>. For example, "
7705 "assuming that I<-i> is the flag designating an input file and I<-o> is the "
7706 "flag designating an output file:"
7710 #: build/C/man5/proc.5:351
7712 msgid "$B< foobar -i /proc/self/fd/0 -o /proc/self/fd/1 ...>\n"
7715 #. The following is not true in my tests (MTK):
7716 #. Note that this will not work for
7717 #. programs that seek on their files, as the files in the fd directory
7718 #. are not seekable.
7720 #: build/C/man5/proc.5:359
7721 msgid "and you have a working filter."
7725 #: build/C/man5/proc.5:369
7727 "I</proc/self/fd/N> is approximately the same as I</dev/fd/N> in some UNIX "
7728 "and UNIX-like systems. Most Linux MAKEDEV scripts symbolically link "
7729 "I</dev/fd> to I</proc/self/fd>, in fact."
7733 #: build/C/man5/proc.5:383
7735 "Most systems provide symbolic links I</dev/stdin>, I</dev/stdout>, and "
7736 "I</dev/stderr>, which respectively link to the files I<0>, I<1>, and I<2> in "
7737 "I</proc/self/fd>. Thus the example command above could be written as:"
7741 #: build/C/man5/proc.5:387
7743 msgid "$B< foobar -i /dev/stdin -o /dev/stdout ...>\n"
7747 #: build/C/man5/proc.5:392
7749 msgid "I</proc/[pid]/fdinfo/> (since kernel 2.6.22)"
7753 #: build/C/man5/proc.5:398
7755 "This is a subdirectory containing one entry for each file which the process "
7756 "has open, named by its file descriptor. The contents of each file can be "
7757 "read to obtain information about the corresponding file descriptor, for "
7762 #: build/C/man5/proc.5:404
7765 "$B< cat /proc/12015/fdinfo/4>\n"
7771 #: build/C/man5/proc.5:415
7773 "The I<pos> field is a decimal number showing the current file offset. The "
7774 "I<flags> field is an octal number that displays the file access mode and "
7775 "file status flags (see B<open>(2))."
7779 #. Certain file types include additional info; see
7780 #. Documentation/filesystems/proc.txt
7782 #. Especially interesting is this:
7784 #. commit ab49bdecc3ebb46ab661f5f05d5c5ea9606406c6
7785 #. Author: Cyrill Gorcunov <gorcunov@openvz.org>
7786 #. Date: Mon Dec 17 16:05:06 2012 -0800
7788 #. Basically, the /proc/PID/fdinfo/ entry for an inotify FD
7789 #. includes the file handles for all watched FDs
7791 #: build/C/man5/proc.5:430
7792 msgid "The files in this directory are readable only by the owner of the process."
7796 #: build/C/man5/proc.5:430
7798 msgid "I</proc/[pid]/io> (since kernel 2.6.20)"
7801 #. commit 7c3ab7381e79dfc7db14a67c6f4f3285664e1ec2
7803 #: build/C/man5/proc.5:434
7804 msgid "This file contains I/O statistics for the process, for example:"
7808 #: build/C/man5/proc.5:445
7811 "#B< cat /proc/3828/io>\n"
7812 "rchar: 323934931\n"
7813 "wchar: 323929600\n"
7817 "write_bytes: 323932160\n"
7818 "cancelled_write_bytes: 0\n"
7822 #: build/C/man5/proc.5:449 build/C/man5/proc.5:1460
7823 msgid "The fields are as follows:"
7827 #: build/C/man5/proc.5:450
7829 msgid "I<rchar>: characters read"
7833 #: build/C/man5/proc.5:460
7835 "The number of bytes which this task has caused to be read from storage. "
7836 "This is simply the sum of bytes which this process passed to B<read>(2) and "
7837 "similar system calls. It includes things such as terminal I/O and is "
7838 "unaffected by whether or not actual physical disk I/O was required (the read "
7839 "might have been satisfied from pagecache)."
7843 #: build/C/man5/proc.5:460
7845 msgid "I<wchar>: characters written"
7849 #: build/C/man5/proc.5:466
7851 "The number of bytes which this task has caused, or shall cause to be written "
7852 "to disk. Similar caveats apply here as with I<rchar>."
7856 #: build/C/man5/proc.5:466
7858 msgid "I<syscr>: read syscalls"
7862 #: build/C/man5/proc.5:473
7864 "Attempt to count the number of read I/O operations\\(emthat is, system calls "
7865 "such as B<read>(2) and B<pread>(2)."
7869 #: build/C/man5/proc.5:473
7871 msgid "I<syscw>: write syscalls"
7875 #: build/C/man5/proc.5:480
7877 "Attempt to count the number of write I/O operations\\(emthat is, system "
7878 "calls such as B<write>(2) and B<pwrite>(2)."
7882 #: build/C/man5/proc.5:480
7884 msgid "I<read_bytes>: bytes read"
7888 #: build/C/man5/proc.5:485
7890 "Attempt to count the number of bytes which this process really did cause to "
7891 "be fetched from the storage layer. This is accurate for block-backed "
7896 #: build/C/man5/proc.5:485
7898 msgid "I<write_bytes>: bytes written"
7902 #: build/C/man5/proc.5:489
7904 "Attempt to count the number of bytes which this process caused to be sent to "
7905 "the storage layer."
7909 #: build/C/man5/proc.5:489
7911 msgid "I<cancelled_write_bytes>:"
7915 #: build/C/man5/proc.5:503
7917 "The big inaccuracy here is truncate. If a process writes 1MB to a file and "
7918 "then deletes the file, it will in fact perform no writeout. But it will "
7919 "have been accounted as having caused 1MB of write. In other words: this "
7920 "field represents the number of bytes which this process caused to not "
7921 "happen, by truncating pagecache. A task can cause \"negative\" I/O too. If "
7922 "this task truncates some dirty pagecache, some I/O which another task has "
7923 "been accounted for (in its I<write_bytes>) will not be happening."
7927 #: build/C/man5/proc.5:511
7929 "I<Note>: In the current implementation, things are a bit racy on 32-bit "
7930 "systems: if process A reads process B's I</proc/[pid]/io> while process B is "
7931 "updating one of these 64-bit counters, process A could see an intermediate "
7936 #: build/C/man5/proc.5:511
7938 msgid "I</proc/[pid]/limits> (since kernel 2.6.24)"
7941 #. commit 3036e7b490bf7878c6dae952eec5fb87b1106589
7943 #: build/C/man5/proc.5:521
7945 "This file displays the soft limit, hard limit, and units of measurement for "
7946 "each of the process's resource limits (see B<getrlimit>(2)). Up to and "
7947 "including Linux 2.6.35, this file is protected to allow reading only by the "
7948 "real UID of the process. Since Linux 2.6.36, this file is readable by all "
7949 "users on the system."
7953 #: build/C/man5/proc.5:521
7955 msgid "I</proc/[pid]/map_files/> (since kernel 3.3)"
7958 #. commit 640708a2cff7f81e246243b0073c66e6ece7e53e
7960 #: build/C/man5/proc.5:531
7962 "This subdirectory contains entries corresponding to memory-mapped files (see "
7963 "B<mmap>(2)). Entries are named by memory region start and end address pair "
7964 "(expressed as hexadecimal numbers), and are symbolic links to the mapped "
7965 "files themselves. Here is an example, with the output wrapped and "
7966 "reformatted to fit on an 80-column display:"
7970 #: build/C/man5/proc.5:538
7973 "$B< ls -l /proc/self/map_files/>\n"
7974 "lr--------. 1 root root 64 Apr 16 21:31\n"
7975 " 3252e00000-3252e20000 -E<gt> /usr/lib64/ld-2.15.so\n"
7980 #: build/C/man5/proc.5:552
7982 "Although these entries are present for memory regions that were mapped with "
7983 "the B<MAP_FILE> flag, the way anonymous shared memory (regions created with "
7984 "the B<MAP_ANON | MAP_SHARED> flags) is implemented in Linux means that such "
7985 "regions also appear on this directory. Here is an example where the target "
7986 "file is the deleted I</dev/zero> one:"
7990 #: build/C/man5/proc.5:558
7993 "lrw-------. 1 root root 64 Apr 16 21:33\n"
7994 " 7fc075d2f000-7fc075e6f000 -E<gt> /dev/zero (deleted)\n"
7998 #: build/C/man5/proc.5:564
8000 "This directory appears only if the B<CONFIG_CHECKPOINT_RESTORE> kernel "
8001 "configuration option is enabled."
8005 #: build/C/man5/proc.5:564
8007 msgid "I</proc/[pid]/maps>"
8011 #: build/C/man5/proc.5:571
8013 "A file containing the currently mapped memory regions and their access "
8014 "permissions. See B<mmap>(2) for some further information about memory "
8019 #: build/C/man5/proc.5:573
8020 msgid "The format of the file is:"
8024 #: build/C/man5/proc.5:598
8027 "I<address perms offset dev inode pathname>\n"
8028 "00400000-00452000 r-xp 00000000 08:02 173521 /usr/bin/dbus-daemon\n"
8029 "00651000-00652000 r--p 00051000 08:02 173521 /usr/bin/dbus-daemon\n"
8030 "00652000-00655000 rw-p 00052000 08:02 173521 /usr/bin/dbus-daemon\n"
8031 "00e03000-00e24000 rw-p 00000000 00:00 0 [heap]\n"
8032 "00e24000-011f7000 rw-p 00000000 00:00 0 [heap]\n"
8034 "35b1800000-35b1820000 r-xp 00000000 08:02 135522 /usr/lib64/ld-2.15.so\n"
8035 "35b1a1f000-35b1a20000 r--p 0001f000 08:02 135522 /usr/lib64/ld-2.15.so\n"
8036 "35b1a20000-35b1a21000 rw-p 00020000 08:02 135522 /usr/lib64/ld-2.15.so\n"
8037 "35b1a21000-35b1a22000 rw-p 00000000 00:00 0\n"
8038 "35b1c00000-35b1dac000 r-xp 00000000 08:02 135870 /usr/lib64/libc-2.15.so\n"
8039 "35b1dac000-35b1fac000 ---p 001ac000 08:02 135870 /usr/lib64/libc-2.15.so\n"
8040 "35b1fac000-35b1fb0000 r--p 001ac000 08:02 135870 /usr/lib64/libc-2.15.so\n"
8041 "35b1fb0000-35b1fb2000 rw-p 001b0000 08:02 135870 /usr/lib64/libc-2.15.so\n"
8043 "f2c6ff8c000-7f2c7078c000 rw-p 00000000 00:00 0 [stack:986]\n"
8045 "7fffb2c0d000-7fffb2c2e000 rw-p 00000000 00:00 0 [stack]\n"
8046 "7fffb2d48000-7fffb2d49000 r-xp 00000000 00:00 0 [vdso]\n"
8050 #: build/C/man5/proc.5:607
8052 "The I<address> field is the address space in the process that the mapping "
8053 "occupies. The I<perms> field is a set of permissions:"
8057 #: build/C/man5/proc.5:615
8064 "p = private (copy on write)\n"
8068 #: build/C/man5/proc.5:628
8070 "The I<offset> field is the offset into the file/whatever; I<dev> is the "
8071 "device (major:minor); I<inode> is the inode on that device. 0 indicates "
8072 "that no inode is associated with the memory region, as would be the case "
8073 "with BSS (uninitialized data)."
8077 #: build/C/man5/proc.5:638
8079 "The I<pathname> field will usually be the file that is backing the mapping. "
8080 "For ELF files, you can easily coordinate with the I<offset> field by looking "
8081 "at the Offset field in the ELF program headers (I<readelf\\ -l>)."
8085 #: build/C/man5/proc.5:640
8086 msgid "There are additional helpful pseudo-paths:"
8090 #: build/C/man5/proc.5:641
8096 #: build/C/man5/proc.5:644
8097 msgid "The initial process's (also known as the main thread's) stack."
8101 #: build/C/man5/proc.5:644
8103 msgid "I<[stack:E<lt>tidE<gt>]> (since Linux 3.4)"
8106 #. commit b76437579d1344b612cf1851ae610c636cec7db0
8108 #: build/C/man5/proc.5:653
8110 "A thread's stack (where the I<E<lt>tidE<gt>> is a thread ID). It "
8111 "corresponds to the I</proc/[pid]/task/[tid]/> path."
8115 #: build/C/man5/proc.5:653
8121 #: build/C/man5/proc.5:656
8122 msgid "The virtual dynamically linked shared object."
8126 #: build/C/man5/proc.5:656
8132 #: build/C/man5/proc.5:659
8133 msgid "The process's heap."
8137 #: build/C/man5/proc.5:673
8139 "If the I<pathname> field is blank, this is an anonymous mapping as obtained "
8140 "via the B<mmap>(2) function. There is no easy way to coordinate this back "
8141 "to a process's source, short of running it through B<gdb>(1), B<strace>(1), "
8146 #: build/C/man5/proc.5:675
8147 msgid "Under Linux 2.0 there is no field giving pathname."
8151 #: build/C/man5/proc.5:675
8153 msgid "I</proc/[pid]/mem>"
8157 #: build/C/man5/proc.5:682
8159 "This file can be used to access the pages of a process's memory through "
8160 "B<open>(2), B<read>(2), and B<lseek>(2)."
8164 #: build/C/man5/proc.5:682
8166 msgid "I</proc/[pid]/mountinfo> (since Linux 2.6.26)"
8169 #. This info adapted from Documentation/filesystems/proc.txt
8171 #: build/C/man5/proc.5:687
8173 "This file contains information about mount points. It contains lines of the "
8178 #: build/C/man5/proc.5:692
8181 "CW<36 35 98:0 /mnt1 /mnt2 rw,noatime master:1 - ext3 /dev/root "
8182 "rw,errors=continue\n"
8183 "(1)(2)(3) (4) (5) (6) (7) (8) (9) (10) (11)>\n"
8187 #: build/C/man5/proc.5:696
8188 msgid "The numbers in parentheses are labels for the descriptions below:"
8192 #: build/C/man5/proc.5:697 build/C/man5/proc.5:790
8198 #: build/C/man5/proc.5:701
8199 msgid "mount ID: unique identifier of the mount (may be reused after B<umount>(2))."
8203 #: build/C/man5/proc.5:701 build/C/man5/proc.5:794
8209 #: build/C/man5/proc.5:704
8210 msgid "parent ID: ID of parent mount (or of self for the top of the mount tree)."
8214 #: build/C/man5/proc.5:704 build/C/man5/proc.5:797
8220 #: build/C/man5/proc.5:710
8221 msgid "major:minor: value of I<st_dev> for files on filesystem (see B<stat>(2))."
8225 #: build/C/man5/proc.5:710 build/C/man5/proc.5:800
8231 #: build/C/man5/proc.5:713
8232 msgid "root: root of the mount within the filesystem."
8236 #: build/C/man5/proc.5:713
8242 #: build/C/man5/proc.5:716
8243 msgid "mount point: mount point relative to the process's root."
8247 #: build/C/man5/proc.5:716
8253 #: build/C/man5/proc.5:719
8254 msgid "mount options: per-mount options."
8258 #: build/C/man5/proc.5:719
8264 #: build/C/man5/proc.5:722
8265 msgid "optional fields: zero or more fields of the form \"tag[:value]\"."
8269 #: build/C/man5/proc.5:722
8275 #: build/C/man5/proc.5:725
8276 msgid "separator: marks the end of the optional fields."
8280 #: build/C/man5/proc.5:725
8286 #: build/C/man5/proc.5:728
8287 msgid "filesystem type: name of filesystem in the form \"type[.subtype]\"."
8291 #: build/C/man5/proc.5:728
8297 #: build/C/man5/proc.5:731
8298 msgid "mount source: filesystem-specific information or \"none\"."
8302 #: build/C/man5/proc.5:731
8308 #: build/C/man5/proc.5:734
8309 msgid "super options: per-superblock options."
8313 #: build/C/man5/proc.5:738
8315 "Parsers should ignore all unrecognized optional fields. Currently the "
8316 "possible optional fields are:"
8320 #: build/C/man5/proc.5:739
8326 #: build/C/man5/proc.5:742
8327 msgid "mount is shared in peer group X"
8331 #: build/C/man5/proc.5:742
8337 #: build/C/man5/proc.5:745
8338 msgid "mount is slave to peer group X"
8342 #: build/C/man5/proc.5:745
8344 msgid "propagate_from:X"
8348 #: build/C/man5/proc.5:748
8349 msgid "mount is slave and receives propagation from peer group X (*)"
8353 #: build/C/man5/proc.5:748
8359 #: build/C/man5/proc.5:751
8360 msgid "mount is unbindable"
8364 #: build/C/man5/proc.5:758
8366 "(*) X is the closest dominant peer group under the process's root. If X is "
8367 "the immediate master of the mount, or if there is no dominant peer group "
8368 "under the same root, then only the \"master:X\" field is present and not the "
8369 "\"propagate_from:X\" field."
8373 #: build/C/man5/proc.5:762
8375 "For more information on mount propagation see: "
8376 "I<Documentation/filesystems/sharedsubtree.txt> in the Linux kernel source "
8381 #: build/C/man5/proc.5:762
8383 msgid "I</proc/[pid]/mounts> (since Linux 2.4.19)"
8387 #: build/C/man5/proc.5:777
8389 "This is a list of all the filesystems currently mounted in the process's "
8390 "mount namespace. The format of this file is documented in B<fstab>(5). "
8391 "Since kernel version 2.6.15, this file is pollable: after opening the file "
8392 "for reading, a change in this file (i.e., a filesystem mount or unmount) "
8393 "causes B<select>(2) to mark the file descriptor as readable, and B<poll>(2) "
8394 "and B<epoll_wait>(2) mark the file as having an error condition."
8398 #: build/C/man5/proc.5:777
8400 msgid "I</proc/[pid]/mountstats> (since Linux 2.6.17)"
8404 #: build/C/man5/proc.5:782
8406 "This file exports information (statistics, configuration information) about "
8407 "the mount points in the process's name space. Lines in this file have the "
8412 #: build/C/man5/proc.5:786
8415 "device /dev/sda7 mounted on /home with fstype ext3 [statistics]\n"
8416 "( 1 ) ( 2 ) (3 ) (4)\n"
8420 #: build/C/man5/proc.5:789
8421 msgid "The fields in each line are:"
8425 #: build/C/man5/proc.5:794
8427 "The name of the mounted device (or \"nodevice\" if there is no corresponding "
8432 #: build/C/man5/proc.5:797
8433 msgid "The mount point within the filesystem tree."
8437 #: build/C/man5/proc.5:800
8438 msgid "The filesystem type."
8442 #: build/C/man5/proc.5:805
8444 "Optional statistics and configuration information. Currently (as at Linux "
8445 "2.6.26), only NFS filesystems export information via this field."
8449 #: build/C/man5/proc.5:808
8450 msgid "This file is readable only by the owner of the process."
8454 #: build/C/man5/proc.5:808
8456 msgid "I</proc/[pid]/ns/> (since Linux 3.0)"
8459 #. See commit 6b4e306aa3dc94a0545eb9279475b1ab6209a31f
8461 #: build/C/man5/proc.5:816
8463 "This is a subdirectory containing one entry for each namespace that supports "
8464 "being manipulated by B<setns>(2). For information about namespaces, see "
8469 #: build/C/man5/proc.5:816
8471 msgid "I</proc/[pid]/ns/ipc> (since Linux 3.0)"
8475 #: build/C/man5/proc.5:824
8477 "Bind mounting this file (see B<mount>(2)) to somewhere else in the "
8478 "filesystem keeps the IPC namespace of the process specified by I<pid> alive "
8479 "even if all processes currently in the namespace terminate."
8483 #: build/C/man5/proc.5:833
8485 "Opening this file returns a file handle for the IPC namespace of the process "
8486 "specified by I<pid>. As long as this file descriptor remains open, the IPC "
8487 "namespace will remain alive, even if all processes in the namespace "
8488 "terminate. The file descriptor can be passed to B<setns>(2)."
8492 #: build/C/man5/proc.5:833
8494 msgid "I</proc/[pid]/ns/net> (since Linux 3.0)"
8498 #: build/C/man5/proc.5:841
8500 "Bind mounting this file (see B<mount>(2)) to somewhere else in the "
8501 "filesystem keeps the network namespace of the process specified by I<pid> "
8502 "alive even if all processes in the namespace terminate."
8506 #: build/C/man5/proc.5:850
8508 "Opening this file returns a file handle for the network namespace of the "
8509 "process specified by I<pid>. As long as this file descriptor remains open, "
8510 "the network namespace will remain alive, even if all processes in the "
8511 "namespace terminate. The file descriptor can be passed to B<setns>(2)."
8515 #: build/C/man5/proc.5:850
8517 msgid "I</proc/[pid]/ns/uts> (since Linux 3.0)"
8521 #: build/C/man5/proc.5:858
8523 "Bind mounting this file (see B<mount>(2)) to somewhere else in the "
8524 "filesystem keeps the UTS namespace of the process specified by I<pid> alive "
8525 "even if all processes currently in the namespace terminate."
8529 #: build/C/man5/proc.5:867
8531 "Opening this file returns a file handle for the UTS namespace of the process "
8532 "specified by I<pid>. As long as this file descriptor remains open, the UTS "
8533 "namespace will remain alive, even if all processes in the namespace "
8534 "terminate. The file descriptor can be passed to B<setns>(2)."
8538 #: build/C/man5/proc.5:867
8540 msgid "I</proc/[pid]/numa_maps> (since Linux 2.6.14)"
8544 #: build/C/man5/proc.5:871
8545 msgid "See B<numa>(7)."
8549 #: build/C/man5/proc.5:871
8551 msgid "I</proc/[pid]/oom_adj> (since Linux 2.6.11)"
8555 #: build/C/man5/proc.5:884
8557 "This file can be used to adjust the score used to select which process "
8558 "should be killed in an out-of-memory (OOM) situation. The kernel uses this "
8559 "value for a bit-shift operation of the process's I<oom_score> value: valid "
8560 "values are in the range -16 to +15, plus the special value -17, which "
8561 "disables OOM-killing altogether for this process. A positive score "
8562 "increases the likelihood of this process being killed by the OOM-killer; a "
8563 "negative score decreases the likelihood."
8567 #: build/C/man5/proc.5:892
8569 "The default value for this file is 0; a new process inherits its parent's "
8570 "I<oom_adj> setting. A process must be privileged (B<CAP_SYS_RESOURCE>) to "
8575 #: build/C/man5/proc.5:895
8577 "Since Linux 2.6.36, use of this file is deprecated in favor of "
8578 "I</proc/[pid]/oom_score_adj>."
8582 #: build/C/man5/proc.5:895
8584 msgid "I</proc/[pid]/oom_score> (since Linux 2.6.11)"
8587 #. See mm/oom_kill.c::badness() in the 2.6.25 sources
8588 #. See mm/oom_kill.c::badness() in the 2.6.25 sources
8590 #: build/C/man5/proc.5:906
8592 "This file displays the current score that the kernel gives to this process "
8593 "for the purpose of selecting a process for the OOM-killer. A higher score "
8594 "means that the process is more likely to be selected by the OOM-killer. The "
8595 "basis for this score is the amount of memory used by the process, with "
8596 "increases (+) or decreases (-) for factors including:"
8600 #: build/C/man5/proc.5:911
8601 msgid "whether the process creates a lot of children using B<fork>(2) (+);"
8605 #: build/C/man5/proc.5:914
8607 "whether the process has been running a long time, or has used a lot of CPU "
8612 #: build/C/man5/proc.5:916
8613 msgid "whether the process has a low nice value (i.e., E<gt> 0) (+);"
8616 #. More precisely, if it has CAP_SYS_ADMIN or CAP_SYS_RESOURCE
8618 #: build/C/man5/proc.5:919
8619 msgid "whether the process is privileged (-); and"
8622 #. More precisely, if it has CAP_SYS_RAWIO
8624 #: build/C/man5/proc.5:922
8625 msgid "whether the process is making direct hardware access (-)."
8629 #: build/C/man5/proc.5:931
8631 "The I<oom_score> also reflects the adjustment specified by the "
8632 "I<oom_score_adj> or I<oom_adj> setting for the process."
8636 #: build/C/man5/proc.5:931
8638 msgid "I</proc/[pid]/oom_score_adj> (since Linux 2.6.36)"
8641 #. Text taken from 3.7 Documentation/filesystems/proc.txt
8643 #: build/C/man5/proc.5:936
8645 "This file can be used to adjust the badness heuristic used to select which "
8646 "process gets killed in out-of-memory conditions."
8650 #: build/C/man5/proc.5:945
8652 "The badness heuristic assigns a value to each candidate task ranging from 0 "
8653 "(never kill) to 1000 (always kill) to determine which process is targeted. "
8654 "The units are roughly a proportion along that range of allowed memory the "
8655 "process may allocate from, based on an estimation of its current memory and "
8656 "swap use. For example, if a task is using all allowed memory, its badness "
8657 "score will be 1000. If it is using half of its allowed memory, its score "
8662 #: build/C/man5/proc.5:948
8664 "There is an additional factor included in the badness score: root processes "
8665 "are given 3% extra memory over other tasks."
8669 #: build/C/man5/proc.5:962
8671 "The amount of \"allowed\" memory depends on the context in which the "
8672 "OOM-killer was called. If it is due to the memory assigned to the "
8673 "allocating task's cpuset being exhausted, the allowed memory represents the "
8674 "set of mems assigned to that cpuset (see B<cpuset>(7)). If it is due to a "
8675 "mempolicy's node(s) being exhausted, the allowed memory represents the set "
8676 "of mempolicy nodes. If it is due to a memory limit (or swap limit) being "
8677 "reached, the allowed memory is that configured limit. Finally, if it is due "
8678 "to the entire system being out of memory, the allowed memory represents all "
8679 "allocatable resources."
8683 #: build/C/man5/proc.5:975
8685 "The value of I<oom_score_adj> is added to the badness score before it is "
8686 "used to determine which task to kill. Acceptable values range from -1000 "
8687 "(OOM_SCORE_ADJ_MIN) to +1000 (OOM_SCORE_ADJ_MAX). This allows user space to "
8688 "control the preference for OOM-killing, ranging from always preferring a "
8689 "certain task or completely disabling it from OOM-killing. The lowest "
8690 "possible value, -1000, is equivalent to disabling OOM-killing entirely for "
8691 "that task, since it will always report a badness score of 0."
8695 #: build/C/man5/proc.5:987
8697 "Consequently, it is very simple for user space to define the amount of "
8698 "memory to consider for each task. Setting a I<oom_score_adj> value of +500, "
8699 "for example, is roughly equivalent to allowing the remainder of tasks "
8700 "sharing the same system, cpuset, mempolicy, or memory controller resources "
8701 "to use at least 50% more memory. A value of -500, on the other hand, would "
8702 "be roughly equivalent to discounting 50% of the task's allowed memory from "
8703 "being considered as scoring against the task."
8707 #: build/C/man5/proc.5:994
8709 "For backward compatibility with previous kernels, I</proc/[pid]/oom_adj> can "
8710 "still be used to tune the badness score. Its value is scaled linearly with "
8714 #. FIXME Describe /proc/[pid]/pagemap
8716 #. CONFIG_PROC_PAGE_MONITOR
8718 #: build/C/man5/proc.5:1003
8720 "Writing to I</proc/[pid]/oom_score_adj> or I</proc/[pid]/oom_adj> will "
8721 "change the other with its scaled value."
8725 #: build/C/man5/proc.5:1003
8727 msgid "I</proc/[pid]/root>"
8731 #: build/C/man5/proc.5:1014
8733 "UNIX and Linux support the idea of a per-process root of the filesystem, set "
8734 "by the B<chroot>(2) system call. This file is a symbolic link that points "
8735 "to the process's root directory, and behaves in the same way as I<exe>, and "
8740 #: build/C/man5/proc.5:1034
8742 msgid "I</proc/[pid]/smaps> (since Linux 2.6.14)"
8746 #: build/C/man5/proc.5:1038
8748 "This file shows memory consumption for each of the process's mappings. For "
8749 "each mapping there is a series of lines such as the following:"
8753 #: build/C/man5/proc.5:1056
8756 "00400000-0048a000 r-xp 00000000 fd:03 960637 /bin/bash\n"
8760 "Shared_Clean: 452 kB\n"
8761 "Shared_Dirty: 0 kB\n"
8762 "Private_Clean: 8 kB\n"
8763 "Private_Dirty: 0 kB\n"
8764 "Referenced: 460 kB\n"
8766 "AnonHugePages: 0 kB\n"
8768 "KernelPageSize: 4 kB\n"
8769 "MMUPageSize: 4 kB\n"
8774 #: build/C/man5/proc.5:1073
8776 "The first of these lines shows the same information as is displayed for the "
8777 "mapping in I</proc/[pid]/maps>. The remaining lines show the size of the "
8778 "mapping, the amount of the mapping that is currently resident in RAM "
8779 "(\"Rss\"), the process' proportional share of this mapping (\"Pss\"), the "
8780 "number of clean and dirty shared pages in the mapping, and the number of "
8781 "clean and dirty private pages in the mapping. \"Referenced\" indicates the "
8782 "amount of memory currently marked as referenced or accessed. \"Anonymous\" "
8783 "shows the amount of memory that does not belong to any file. \"Swap\" shows "
8784 "how much would-be-anonymous memory is also used, but out on swap."
8788 #: build/C/man5/proc.5:1081
8790 "The \"KernelPageSize\" entry is the page size used by the kernel to back a "
8791 "VMA. This matches the size used by the MMU in the majority of cases. "
8792 "However, one counter-example occurs on PPC64 kernels whereby a kernel using "
8793 "64K as a base page size may still use 4K pages for the MMU on older "
8794 "processors. To distinguish, this patch reports \"MMUPageSize\" as the page "
8795 "size used by the MMU."
8799 #: build/C/man5/proc.5:1084
8800 msgid "The \"Locked\" indicates whether the mapping is locked in memory or not."
8804 #: build/C/man5/proc.5:1088
8806 "\"VmFlags\" field represents the kernel flags associated with the particular "
8807 "virtual memory area in two letter encoded manner. The codes are the "
8812 #: build/C/man5/proc.5:1117
8817 " ex - executable\n"
8821 " me - may execute\n"
8823 " gd - stack segment grows down\n"
8824 " pf - pure PFN range\n"
8825 " dw - disabled write to the mapped file\n"
8826 " lo - pages are locked in memory\n"
8827 " io - memory mapped I/O area\n"
8828 " sr - sequential read advise provided\n"
8829 " rr - random read advise provided\n"
8830 " dc - do not copy area on fork\n"
8831 " de - do not expand area on remapping\n"
8832 " ac - area is accountable\n"
8833 " nr - swap space is not reserved for the area\n"
8834 " ht - area uses huge tlb pages\n"
8835 " nl - non-linear mapping\n"
8836 " ar - architecture specific flag\n"
8837 " dd - do not include area into core dump\n"
8838 " sd - soft-dirty flag\n"
8839 " mm - mixed map area\n"
8840 " hg - huge page advise flag\n"
8841 " nh - no-huge page advise flag\n"
8842 " mg - mergeable advise flag\n"
8846 #: build/C/man5/proc.5:1123
8848 "The I</proc/[pid]/smaps> file is present only if the "
8849 "B<CONFIG_PROC_PAGE_MONITOR> kernel configuration option is enabled."
8853 #: build/C/man5/proc.5:1123
8855 msgid "I</proc/[pid]/stack> (since Linux 2.6.29)"
8858 #. 2ec220e27f5040aec1e88901c1b6ea3d135787ad
8860 #: build/C/man5/proc.5:1131
8862 "This file provides a symbolic trace of the function calls in this process's "
8863 "kernel stack. This file is provided only if the kernel was built with the "
8864 "B<CONFIG_STACKTRACE> configuration option."
8868 #: build/C/man5/proc.5:1131
8870 msgid "I</proc/[pid]/stat>"
8874 #: build/C/man5/proc.5:1138
8876 "Status information about the process. This is used by B<ps>(1). It is "
8877 "defined in I</usr/src/linux/fs/proc/array.c>."
8881 #: build/C/man5/proc.5:1142
8882 msgid "The fields, in order, with their proper B<scanf>(3) format specifiers, are:"
8886 #: build/C/man5/proc.5:1143
8892 #: build/C/man5/proc.5:1146
8893 msgid "(1) The process ID."
8897 #: build/C/man5/proc.5:1146
8903 #: build/C/man5/proc.5:1150
8905 "(2) The filename of the executable, in parentheses. This is visible whether "
8906 "or not the executable is swapped out."
8910 #: build/C/man5/proc.5:1150
8916 #: build/C/man5/proc.5:1156
8918 "(3) One character from the string \"RSDZTW\" where R is running, S is "
8919 "sleeping in an interruptible wait, D is waiting in uninterruptible disk "
8920 "sleep, Z is zombie, T is traced or stopped (on a signal), and W is paging."
8924 #: build/C/man5/proc.5:1156
8930 #: build/C/man5/proc.5:1159
8931 msgid "(4) The PID of the parent."
8935 #: build/C/man5/proc.5:1159
8941 #: build/C/man5/proc.5:1162
8942 msgid "(5) The process group ID of the process."
8946 #: build/C/man5/proc.5:1162
8948 msgid "I<session> %d"
8952 #: build/C/man5/proc.5:1165
8953 msgid "(6) The session ID of the process."
8957 #: build/C/man5/proc.5:1165
8959 msgid "I<tty_nr> %d"
8963 #: build/C/man5/proc.5:1171
8965 "(7) The controlling terminal of the process. (The minor device number is "
8966 "contained in the combination of bits 31 to 20 and 7 to 0; the major device "
8967 "number is in bits 15 to 8.)"
8971 #: build/C/man5/proc.5:1171
8976 #. This field and following, up to and including wchan added 0.99.1
8978 #: build/C/man5/proc.5:1176
8980 "(8) The ID of the foreground process group of the controlling terminal of "
8985 #: build/C/man5/proc.5:1176
8987 msgid "I<flags> %u (%lu before Linux 2.6.22)"
8991 #: build/C/man5/proc.5:1183
8993 "(9) The kernel flags word of the process. For bit meanings, see the PF_* "
8994 "defines in the Linux kernel source file I<include/linux/sched.h>. Details "
8995 "depend on the kernel version."
8999 #: build/C/man5/proc.5:1183
9001 msgid "I<minflt> %lu"
9005 #: build/C/man5/proc.5:1187
9007 "(10) The number of minor faults the process has made which have not required "
9008 "loading a memory page from disk."
9012 #: build/C/man5/proc.5:1187
9014 msgid "I<cminflt> %lu"
9018 #: build/C/man5/proc.5:1191
9020 "(11) The number of minor faults that the process's waited-for children have "
9025 #: build/C/man5/proc.5:1191
9027 msgid "I<majflt> %lu"
9031 #: build/C/man5/proc.5:1195
9033 "(12) The number of major faults the process has made which have required "
9034 "loading a memory page from disk."
9038 #: build/C/man5/proc.5:1195
9040 msgid "I<cmajflt> %lu"
9044 #: build/C/man5/proc.5:1199
9046 "(13) The number of major faults that the process's waited-for children have "
9051 #: build/C/man5/proc.5:1199
9053 msgid "I<utime> %lu"
9057 #: build/C/man5/proc.5:1208
9059 "(14) Amount of time that this process has been scheduled in user mode, "
9060 "measured in clock ticks (divide by I<sysconf(_SC_CLK_TCK)>). This includes "
9061 "guest time, I<guest_time> (time spent running a virtual CPU, see below), so "
9062 "that applications that are not aware of the guest time field do not lose "
9063 "that time from their calculations."
9067 #: build/C/man5/proc.5:1208
9069 msgid "I<stime> %lu"
9073 #: build/C/man5/proc.5:1213
9075 "(15) Amount of time that this process has been scheduled in kernel mode, "
9076 "measured in clock ticks (divide by I<sysconf(_SC_CLK_TCK)>)."
9080 #: build/C/man5/proc.5:1213
9082 msgid "I<cutime> %ld"
9086 #: build/C/man5/proc.5:1223
9088 "(16) Amount of time that this process's waited-for children have been "
9089 "scheduled in user mode, measured in clock ticks (divide by "
9090 "I<sysconf(_SC_CLK_TCK)>). (See also B<times>(2).) This includes guest "
9091 "time, I<cguest_time> (time spent running a virtual CPU, see below)."
9095 #: build/C/man5/proc.5:1223
9097 msgid "I<cstime> %ld"
9101 #: build/C/man5/proc.5:1229
9103 "(17) Amount of time that this process's waited-for children have been "
9104 "scheduled in kernel mode, measured in clock ticks (divide by "
9105 "I<sysconf(_SC_CLK_TCK)>)."
9109 #: build/C/man5/proc.5:1229
9111 msgid "I<priority> %ld"
9115 #: build/C/man5/proc.5:1246
9117 "(18) (Explanation for Linux 2.6) For processes running a real-time "
9118 "scheduling policy (I<policy> below; see B<sched_setscheduler>(2)), this is "
9119 "the negated scheduling priority, minus one; that is, a number in the range "
9120 "-2 to -100, corresponding to real-time priorities 1 to 99. For processes "
9121 "running under a non-real-time scheduling policy, this is the raw nice value "
9122 "(B<setpriority>(2)) as represented in the kernel. The kernel stores nice "
9123 "values as numbers in the range 0 (high) to 39 (low), corresponding to the "
9124 "user-visible nice range of -20 to 19."
9127 #. And back in kernel 1.2 days things were different again.
9129 #: build/C/man5/proc.5:1250
9131 "Before Linux 2.6, this was a scaled value based on the scheduler weighting "
9132 "given to this process."
9136 #: build/C/man5/proc.5:1250
9141 #. Back in kernel 1.2 days things were different.
9143 #. \fIcounter\fP %ld
9144 #. The current maximum size in jiffies of the process's next timeslice,
9145 #. or what is currently left of its current timeslice, if it is the
9146 #. currently running process.
9149 #. The time in jiffies of the process's next timeout.
9150 #. timeout was removed sometime around 2.1/2.2
9152 #: build/C/man5/proc.5:1265
9154 "(19) The nice value (see B<setpriority>(2)), a value in the range 19 (low "
9155 "priority) to -20 (high priority)."
9159 #: build/C/man5/proc.5:1265
9161 msgid "I<num_threads> %ld"
9165 #: build/C/man5/proc.5:1270
9167 "(20) Number of threads in this process (since Linux 2.6). Before kernel "
9168 "2.6, this field was hard coded to 0 as a placeholder for an earlier removed "
9173 #: build/C/man5/proc.5:1270
9175 msgid "I<itrealvalue> %ld"
9179 #: build/C/man5/proc.5:1277
9181 "(21) The time in jiffies before the next B<SIGALRM> is sent to the process "
9182 "due to an interval timer. Since kernel 2.6.17, this field is no longer "
9183 "maintained, and is hard coded as 0."
9187 #: build/C/man5/proc.5:1277
9189 msgid "I<starttime> %llu (was %lu before Linux 2.6)"
9193 #: build/C/man5/proc.5:1283
9195 "(22) The time the process started after system boot. In kernels before "
9196 "Linux 2.6, this value was expressed in jiffies. Since Linux 2.6, the value "
9197 "is expressed in clock ticks (divide by I<sysconf(_SC_CLK_TCK)>)."
9201 #: build/C/man5/proc.5:1283
9203 msgid "I<vsize> %lu"
9207 #: build/C/man5/proc.5:1286
9208 msgid "(23) Virtual memory size in bytes."
9212 #: build/C/man5/proc.5:1286
9218 #: build/C/man5/proc.5:1293
9220 "(24) Resident Set Size: number of pages the process has in real memory. "
9221 "This is just the pages which count toward text, data, or stack space. This "
9222 "does not include pages which have not been demand-loaded in, or which are "
9227 #: build/C/man5/proc.5:1293
9229 msgid "I<rsslim> %lu"
9233 #: build/C/man5/proc.5:1300
9235 "(25) Current soft limit in bytes on the rss of the process; see the "
9236 "description of B<RLIMIT_RSS> in B<getrlimit>(2)."
9240 #: build/C/man5/proc.5:1300
9242 msgid "I<startcode> %lu"
9246 #: build/C/man5/proc.5:1303
9247 msgid "(26) The address above which program text can run."
9251 #: build/C/man5/proc.5:1303
9253 msgid "I<endcode> %lu"
9257 #: build/C/man5/proc.5:1306
9258 msgid "(27) The address below which program text can run."
9262 #: build/C/man5/proc.5:1306
9264 msgid "I<startstack> %lu"
9268 #: build/C/man5/proc.5:1309
9269 msgid "(28) The address of the start (i.e., bottom) of the stack."
9273 #: build/C/man5/proc.5:1309
9275 msgid "I<kstkesp> %lu"
9279 #: build/C/man5/proc.5:1313
9281 "(29) The current value of ESP (stack pointer), as found in the kernel stack "
9282 "page for the process."
9286 #: build/C/man5/proc.5:1313
9288 msgid "I<kstkeip> %lu"
9292 #: build/C/man5/proc.5:1316
9293 msgid "(30) The current EIP (instruction pointer)."
9297 #: build/C/man5/proc.5:1316
9299 msgid "I<signal> %lu"
9303 #: build/C/man5/proc.5:1322
9305 "(31) The bitmap of pending signals, displayed as a decimal number. "
9306 "Obsolete, because it does not provide information on real-time signals; use "
9307 "I</proc/[pid]/status> instead."
9311 #: build/C/man5/proc.5:1322
9313 msgid "I<blocked> %lu"
9317 #: build/C/man5/proc.5:1328
9319 "(32) The bitmap of blocked signals, displayed as a decimal number. "
9320 "Obsolete, because it does not provide information on real-time signals; use "
9321 "I</proc/[pid]/status> instead."
9325 #: build/C/man5/proc.5:1328
9327 msgid "I<sigignore> %lu"
9331 #: build/C/man5/proc.5:1334
9333 "(33) The bitmap of ignored signals, displayed as a decimal number. "
9334 "Obsolete, because it does not provide information on real-time signals; use "
9335 "I</proc/[pid]/status> instead."
9339 #: build/C/man5/proc.5:1334
9341 msgid "I<sigcatch> %lu"
9345 #: build/C/man5/proc.5:1340
9347 "(34) The bitmap of caught signals, displayed as a decimal number. Obsolete, "
9348 "because it does not provide information on real-time signals; use "
9349 "I</proc/[pid]/status> instead."
9353 #: build/C/man5/proc.5:1340
9355 msgid "I<wchan> %lu"
9359 #: build/C/man5/proc.5:1346
9361 "(35) This is the \"channel\" in which the process is waiting. It is the "
9362 "address of a location in the kernel where the process is sleeping. The "
9363 "corresponding symbolic name can be found in I</proc/[pid]/wchan>."
9367 #: build/C/man5/proc.5:1346
9369 msgid "I<nswap> %lu"
9372 #. nswap was added in 2.0
9374 #: build/C/man5/proc.5:1351
9375 msgid "(36) Number of pages swapped (not maintained)."
9379 #: build/C/man5/proc.5:1351
9381 msgid "I<cnswap> %lu"
9384 #. cnswap was added in 2.0
9386 #: build/C/man5/proc.5:1356
9387 msgid "(37) Cumulative I<nswap> for child processes (not maintained)."
9391 #: build/C/man5/proc.5:1356
9393 msgid "I<exit_signal> %d (since Linux 2.1.22)"
9397 #: build/C/man5/proc.5:1359
9398 msgid "(38) Signal to be sent to parent when we die."
9402 #: build/C/man5/proc.5:1359
9404 msgid "I<processor> %d (since Linux 2.2.8)"
9408 #: build/C/man5/proc.5:1362
9409 msgid "(39) CPU number last executed on."
9413 #: build/C/man5/proc.5:1362
9415 msgid "I<rt_priority> %u (since Linux 2.5.19; was %lu before Linux 2.6.22)"
9419 #: build/C/man5/proc.5:1368
9421 "(40) Real-time scheduling priority, a number in the range 1 to 99 for "
9422 "processes scheduled under a real-time policy, or 0, for non-real-time "
9423 "processes (see B<sched_setscheduler>(2))."
9427 #: build/C/man5/proc.5:1368
9429 msgid "I<policy> %u (since Linux 2.5.19; was %lu before Linux 2.6.22)"
9433 #: build/C/man5/proc.5:1374
9435 "(41) Scheduling policy (see B<sched_setscheduler>(2)). Decode using the "
9436 "SCHED_* constants in I<linux/sched.h>."
9440 #: build/C/man5/proc.5:1374
9442 msgid "I<delayacct_blkio_ticks> %llu (since Linux 2.6.18)"
9446 #: build/C/man5/proc.5:1377
9447 msgid "(42) Aggregated block I/O delays, measured in clock ticks (centiseconds)."
9451 #: build/C/man5/proc.5:1377
9453 msgid "I<guest_time> %lu (since Linux 2.6.24)"
9457 #: build/C/man5/proc.5:1382
9459 "(43) Guest time of the process (time spent running a virtual CPU for a guest "
9460 "operating system), measured in clock ticks (divide by "
9461 "I<sysconf(_SC_CLK_TCK)>)."
9465 #: build/C/man5/proc.5:1382
9467 msgid "I<cguest_time> %ld (since Linux 2.6.24)"
9471 #: build/C/man5/proc.5:1386
9473 "(44) Guest time of the process's children, measured in clock ticks (divide "
9474 "by I<sysconf(_SC_CLK_TCK)>)."
9478 #: build/C/man5/proc.5:1387
9480 msgid "I</proc/[pid]/statm>"
9484 #: build/C/man5/proc.5:1391
9486 "Provides information about memory usage, measured in pages. The columns "
9490 #. (not including libs; broken, includes data segment)
9491 #. (including libs; broken, includes library text)
9493 #: build/C/man5/proc.5:1405
9496 "size (1) total program size\n"
9497 " (same as VmSize in I</proc/[pid]/status>)\n"
9498 "resident (2) resident set size\n"
9499 " (same as VmRSS in I</proc/[pid]/status>)\n"
9500 "share (3) shared pages (i.e., backed by a file)\n"
9501 "text (4) text (code)\n"
9502 "lib (5) library (unused in Linux 2.6)\n"
9503 "data (6) data + stack\n"
9504 "dt (7) dirty pages (unused in Linux 2.6)\n"
9508 #: build/C/man5/proc.5:1407
9510 msgid "I</proc/[pid]/status>"
9514 #: build/C/man5/proc.5:1415
9516 "Provides much of the information in I</proc/[pid]/stat> and "
9517 "I</proc/[pid]/statm> in a format that's easier for humans to parse. Here's "
9522 #: build/C/man5/proc.5:1456
9525 "$B< cat /proc/$$/status>\n"
9527 "State: S (sleeping)\n"
9532 "Uid: 1000 1000 1000 1000\n"
9533 "Gid: 100 100 100 100\n"
9535 "Groups: 16 33 100\n"
9548 "SigPnd: 0000000000000000\n"
9549 "ShdPnd: 0000000000000000\n"
9550 "SigBlk: 0000000000010000\n"
9551 "SigIgn: 0000000000384004\n"
9552 "SigCgt: 000000004b813efb\n"
9553 "CapInh: 0000000000000000\n"
9554 "CapPrm: 0000000000000000\n"
9555 "CapEff: 0000000000000000\n"
9556 "CapBnd: ffffffffffffffff\n"
9557 "Cpus_allowed: 00000001\n"
9558 "Cpus_allowed_list: 0\n"
9560 "Mems_allowed_list: 0\n"
9561 "voluntary_ctxt_switches: 150\n"
9562 "nonvoluntary_ctxt_switches: 545\n"
9566 #: build/C/man5/proc.5:1464
9567 msgid "I<Name>: Command run by this process."
9571 #: build/C/man5/proc.5:1476
9573 "I<State>: Current state of the process. One of \"R (running)\", \"S "
9574 "(sleeping)\", \"D (disk sleep)\", \"T (stopped)\", \"T (tracing stop)\", \"Z "
9575 "(zombie)\", or \"X (dead)\"."
9579 #: build/C/man5/proc.5:1479
9580 msgid "I<Tgid>: Thread group ID (i.e., Process ID)."
9584 #: build/C/man5/proc.5:1483
9585 msgid "I<Pid>: Thread ID (see B<gettid>(2))."
9589 #: build/C/man5/proc.5:1486
9590 msgid "I<PPid>: PID of parent process."
9594 #: build/C/man5/proc.5:1489
9595 msgid "I<TracerPid>: PID of process tracing this process (0 if not being traced)."
9599 #: build/C/man5/proc.5:1492
9600 msgid "I<Uid>, I<Gid>: Real, effective, saved set, and filesystem UIDs (GIDs)."
9604 #: build/C/man5/proc.5:1495
9605 msgid "I<FDSize>: Number of file descriptor slots currently allocated."
9609 #: build/C/man5/proc.5:1498
9610 msgid "I<Groups>: Supplementary group list."
9614 #: build/C/man5/proc.5:1501
9615 msgid "I<VmPeak>: Peak virtual memory size."
9619 #: build/C/man5/proc.5:1504
9620 msgid "I<VmSize>: Virtual memory size."
9624 #: build/C/man5/proc.5:1508
9625 msgid "I<VmLck>: Locked memory size (see B<mlock>(3))."
9629 #: build/C/man5/proc.5:1511
9630 msgid "I<VmHWM>: Peak resident set size (\"high water mark\")."
9634 #: build/C/man5/proc.5:1514
9635 msgid "I<VmRSS>: Resident set size."
9639 #: build/C/man5/proc.5:1517
9640 msgid "I<VmData>, I<VmStk>, I<VmExe>: Size of data, stack, and text segments."
9644 #: build/C/man5/proc.5:1520
9645 msgid "I<VmLib>: Shared library code size."
9649 #: build/C/man5/proc.5:1523
9650 msgid "I<VmPTE>: Page table entries size (since Linux 2.6.10)."
9654 #: build/C/man5/proc.5:1526
9655 msgid "I<Threads>: Number of threads in process containing this thread."
9659 #: build/C/man5/proc.5:1537
9661 "I<SigQ>: This field contains two slash-separated numbers that relate to "
9662 "queued signals for the real user ID of this process. The first of these is "
9663 "the number of currently queued signals for this real user ID, and the second "
9664 "is the resource limit on the number of queued signals for this process (see "
9665 "the description of B<RLIMIT_SIGPENDING> in B<getrlimit>(2))."
9669 #: build/C/man5/proc.5:1543
9671 "I<SigPnd>, I<ShdPnd>: Number of signals pending for thread and for process "
9672 "as a whole (see B<pthreads>(7) and B<signal>(7))."
9676 #: build/C/man5/proc.5:1547
9678 "I<SigBlk>, I<SigIgn>, I<SigCgt>: Masks indicating signals being blocked, "
9679 "ignored, and caught (see B<signal>(7))."
9683 #: build/C/man5/proc.5:1552
9685 "I<CapInh>, I<CapPrm>, I<CapEff>: Masks of capabilities enabled in "
9686 "inheritable, permitted, and effective sets (see B<capabilities>(7))."
9690 #: build/C/man5/proc.5:1557
9692 "I<CapBnd>: Capability Bounding set (since kernel 2.6.26, see "
9693 "B<capabilities>(7))."
9697 #: build/C/man5/proc.5:1562
9699 "I<Cpus_allowed>: Mask of CPUs on which this process may run (since Linux "
9700 "2.6.24, see B<cpuset>(7))."
9704 #: build/C/man5/proc.5:1567
9706 "I<Cpus_allowed_list>: Same as previous, but in \"list format\" (since Linux "
9707 "2.6.26, see B<cpuset>(7))."
9711 #: build/C/man5/proc.5:1572
9713 "I<Mems_allowed>: Mask of memory nodes allowed to this process (since Linux "
9714 "2.6.24, see B<cpuset>(7))."
9718 #: build/C/man5/proc.5:1577
9720 "I<Mems_allowed_list>: Same as previous, but in \"list format\" (since Linux "
9721 "2.6.26, see B<cpuset>(7))."
9725 #: build/C/man5/proc.5:1580
9727 "I<voluntary_context_switches>, I<nonvoluntary_context_switches>: Number of "
9728 "voluntary and involuntary context switches (since Linux 2.6.23)."
9732 #: build/C/man5/proc.5:1581
9734 msgid "I</proc/[pid]/task> (since Linux 2.6.0-test6)"
9738 #: build/C/man5/proc.5:1612
9740 "This is a directory that contains one subdirectory for each thread in the "
9741 "process. The name of each subdirectory is the numerical thread ID "
9742 "(I<[tid]>) of the thread (see B<gettid>(2)). Within each of these "
9743 "subdirectories, there is a set of files with the same names and contents as "
9744 "under the I</proc/[pid]> directories. For attributes that are shared by all "
9745 "threads, the contents for each of the files under the I<task/[tid]> "
9746 "subdirectories will be the same as in the corresponding file in the parent "
9747 "I</proc/[pid]> directory (e.g., in a multithreaded process, all of the "
9748 "I<task/[tid]/cwd> files will have the same value as the I</proc/[pid]/cwd> "
9749 "file in the parent directory, since all of the threads in a process share a "
9750 "working directory). For attributes that are distinct for each thread, the "
9751 "corresponding files under I<task/[tid]> may have different values (e.g., "
9752 "various fields in each of the I<task/[tid]/status> files may be different "
9756 #. The following was still true as at kernel 2.6.13
9758 #: build/C/man5/proc.5:1619
9760 "In a multithreaded process, the contents of the I</proc/[pid]/task> "
9761 "directory are not available if the main thread has already terminated "
9762 "(typically by calling B<pthread_exit>(3))."
9766 #: build/C/man5/proc.5:1619
9768 msgid "I</proc/[pid]/wchan> (since Linux 2.6.0)"
9772 #: build/C/man5/proc.5:1623
9774 "The symbolic name corresponding to the location in the kernel where the "
9775 "process is sleeping."
9779 #: build/C/man5/proc.5:1623
9781 msgid "I</proc/apm>"
9785 #: build/C/man5/proc.5:1628
9787 "Advanced power management version and battery information when B<CONFIG_APM> "
9788 "is defined at kernel compilation time."
9792 #: build/C/man5/proc.5:1628
9794 msgid "I</proc/bus>"
9798 #: build/C/man5/proc.5:1631
9799 msgid "Contains subdirectories for installed busses."
9803 #: build/C/man5/proc.5:1631
9805 msgid "I</proc/bus/pccard>"
9809 #: build/C/man5/proc.5:1636
9811 "Subdirectory for PCMCIA devices when B<CONFIG_PCMCIA> is set at kernel "
9816 #: build/C/man5/proc.5:1636
9818 msgid "I</proc/[pid]/timers> (since Linux 3.10)"
9821 #. commit 5ed67f05f66c41e39880a6d61358438a25f9fee5
9822 #. commit 48f6a7a511ef8823fdff39afee0320092d43a8a0
9824 #: build/C/man5/proc.5:1643
9826 "A list of the POSIX timers for this process. Each timer is listed with a "
9827 "line that started with the string \"ID:\". For example:"
9831 #: build/C/man5/proc.5:1654
9835 "signal: 60/00007fff86e452a8\n"
9836 "notify: signal/pid.2634\n"
9839 "signal: 60/00007fff86e452a8\n"
9840 "notify: signal/pid.2634\n"
9845 #: build/C/man5/proc.5:1658
9846 msgid "The lines shown for each timer have the following meanings:"
9850 #: build/C/man5/proc.5:1659
9856 #: build/C/man5/proc.5:1670
9858 "The ID for this timer. This is not the same as the timer ID returned by "
9859 "B<timer_create>(2); rather, it is the same kernel-internal ID that is "
9860 "available via the I<si_timerid> field of the I<siginfo_t> structure (see "
9865 #: build/C/man5/proc.5:1670
9871 #: build/C/man5/proc.5:1677
9873 "This is the signal number that this timer uses to deliver notifications "
9874 "followed by a slash, and then the I<sigev_value.sival_ptr> value supplied to "
9875 "the signal handler. Valid only for timers that notify via a signal."
9879 #: build/C/man5/proc.5:1677
9885 #: build/C/man5/proc.5:1688
9887 "The part before the slash specifies the mechanism that this timer uses to "
9888 "deliver notifications, and is one of \"thread\", \"signal\", or \"none\". "
9889 "Immediately following the slash is either the string \"tid\" for timers with "
9890 "B<SIGEV_THREAD_ID> notification, or \"pid\" for timers that notify by other "
9891 "mechanisms. Following the \".\" is the PID of the process that will be "
9892 "delivered a signal if the timer delivers notifications via a signal."
9896 #: build/C/man5/proc.5:1688
9902 #: build/C/man5/proc.5:1701
9904 "This field identifies the clock that the timer uses for measuring time. For "
9905 "most clocks, this is a number that matches one of the user-space B<CLOCK_*> "
9906 "constants exposed via I<E<lt>time.hE<gt>>. B<CLOCK_PROCESS_CPUTIME_ID> "
9907 "timers display with a value of -6 in this field. B<CLOCK_THREAD_CPUTIME_ID> "
9908 "timers display with a value of -2 in this field."
9912 #: build/C/man5/proc.5:1702
9914 msgid "I</proc/bus/pccard/drivers>"
9918 #: build/C/man5/proc.5:1704
9920 msgid "I</proc/bus/pci>"
9924 #: build/C/man5/proc.5:1710
9926 "Contains various bus subdirectories and pseudo-files containing information "
9927 "about PCI busses, installed devices, and device drivers. Some of these "
9928 "files are not ASCII."
9932 #: build/C/man5/proc.5:1710
9934 msgid "I</proc/bus/pci/devices>"
9938 #: build/C/man5/proc.5:1717
9940 "Information about PCI devices. They may be accessed through B<lspci>(8) "
9945 #: build/C/man5/proc.5:1717
9947 msgid "I</proc/cmdline>"
9951 #: build/C/man5/proc.5:1724
9953 "Arguments passed to the Linux kernel at boot time. Often done via a boot "
9954 "manager such as B<lilo>(8) or B<grub>(8)."
9958 #: build/C/man5/proc.5:1724
9960 msgid "I</proc/config.gz> (since Linux 2.6)"
9964 #: build/C/man5/proc.5:1742
9966 "This file exposes the configuration options that were used to build the "
9967 "currently running kernel, in the same format as they would be shown in the "
9968 "I<.config> file that resulted when configuring the kernel (using I<make "
9969 "xconfig>, I<make config>, or similar). The file contents are compressed; "
9970 "view or search them using B<zcat>(1) and B<zgrep>(1). As long as no "
9971 "changes have been made to the following file, the contents of "
9972 "I</proc/config.gz> are the same as those provided by :"
9976 #: build/C/man5/proc.5:1746
9978 msgid "cat /lib/modules/$(uname -r)/build/.config\n"
9982 #: build/C/man5/proc.5:1752
9984 "I</proc/config.gz> is provided only if the kernel is configured with "
9985 "B<CONFIG_IKCONFIG_PROC>."
9989 #: build/C/man5/proc.5:1752
9991 msgid "I</proc/cpuinfo>"
9995 #: build/C/man5/proc.5:1764
9997 "This is a collection of CPU and system architecture dependent items, for "
9998 "each supported architecture a different list. Two common entries are "
9999 "I<processor> which gives CPU number and I<bogomips>; a system constant that "
10000 "is calculated during kernel initialization. SMP machines have information "
10001 "for each CPU. The B<lscpu>(1) command gathers its information from this "
10006 #: build/C/man5/proc.5:1764
10008 msgid "I</proc/devices>"
10011 #. type: Plain text
10012 #: build/C/man5/proc.5:1768
10014 "Text listing of major numbers and device groups. This can be used by "
10015 "MAKEDEV scripts for consistency with the kernel."
10019 #: build/C/man5/proc.5:1768
10021 msgid "I</proc/diskstats> (since Linux 2.5.69)"
10024 #. type: Plain text
10025 #: build/C/man5/proc.5:1774
10027 "This file contains disk I/O statistics for each disk device. See the Linux "
10028 "kernel source file I<Documentation/iostats.txt> for further information."
10032 #: build/C/man5/proc.5:1774
10034 msgid "I</proc/dma>"
10037 #. type: Plain text
10038 #: build/C/man5/proc.5:1778
10040 "This is a list of the registered I<ISA> DMA (direct memory access) channels "
10045 #: build/C/man5/proc.5:1778
10047 msgid "I</proc/driver>"
10050 #. type: Plain text
10051 #: build/C/man5/proc.5:1781 build/C/man5/proc.5:1809
10052 msgid "Empty subdirectory."
10056 #: build/C/man5/proc.5:1781
10058 msgid "I</proc/execdomains>"
10061 #. type: Plain text
10062 #: build/C/man5/proc.5:1784
10063 msgid "List of the execution domains (ABI personalities)."
10067 #: build/C/man5/proc.5:1784
10069 msgid "I</proc/fb>"
10072 #. type: Plain text
10073 #: build/C/man5/proc.5:1789
10075 "Frame buffer information when B<CONFIG_FB> is defined during kernel "
10080 #: build/C/man5/proc.5:1789
10082 msgid "I</proc/filesystems>"
10085 #. type: Plain text
10086 #: build/C/man5/proc.5:1799
10088 "A text listing of the filesystems which are supported by the kernel, namely "
10089 "filesystems which were compiled into the kernel or whose kernel modules are "
10090 "currently loaded. (See also B<filesystems>(5).) If a filesystem is marked "
10091 "with \"nodev\", this means that it does not require a block device to be "
10092 "mounted (e.g., virtual filesystem, network filesystem)."
10095 #. type: Plain text
10096 #: build/C/man5/proc.5:1806
10098 "Incidentally, this file may be used by B<mount>(8) when no filesystem is "
10099 "specified and it didn't manage to determine the filesystem type. Then "
10100 "filesystems contained in this file are tried (excepted those that are marked "
10105 #: build/C/man5/proc.5:1806
10107 msgid "I</proc/fs>"
10111 #: build/C/man5/proc.5:1809
10113 msgid "I</proc/ide>"
10116 #. type: Plain text
10117 #: build/C/man5/proc.5:1815
10119 "This directory exists on systems with the IDE bus. There are directories "
10120 "for each IDE channel and attached device. Files include:"
10123 #. type: Plain text
10124 #: build/C/man5/proc.5:1828
10127 "cache buffer size in KB\n"
10128 "capacity number of sectors\n"
10129 "driver driver version\n"
10130 "geometry physical and logical geometry\n"
10131 "identify in hexadecimal\n"
10132 "media media type\n"
10133 "model manufacturer's model number\n"
10134 "settings drive settings\n"
10135 "smart_thresholds in hexadecimal\n"
10136 "smart_values in hexadecimal\n"
10139 #. type: Plain text
10140 #: build/C/man5/proc.5:1834
10142 "The B<hdparm>(8) utility provides access to this information in a friendly "
10147 #: build/C/man5/proc.5:1834
10149 msgid "I</proc/interrupts>"
10152 #. type: Plain text
10153 #: build/C/man5/proc.5:1844
10155 "This is used to record the number of interrupts per CPU per IO device. "
10156 "Since Linux 2.6.24, for the i386 and x86_64 architectures, at least, this "
10157 "also includes interrupts internal to the system (that is, not associated "
10158 "with a device as such), such as NMI (nonmaskable interrupt), LOC (local "
10159 "timer interrupt), and for SMP systems, TLB (TLB flush interrupt), RES "
10160 "(rescheduling interrupt), CAL (remote function call interrupt), and possibly "
10161 "others. Very easy to read formatting, done in ASCII."
10165 #: build/C/man5/proc.5:1844
10167 msgid "I</proc/iomem>"
10170 #. type: Plain text
10171 #: build/C/man5/proc.5:1847
10172 msgid "I/O memory map in Linux 2.4."
10176 #: build/C/man5/proc.5:1847
10178 msgid "I</proc/ioports>"
10181 #. type: Plain text
10182 #: build/C/man5/proc.5:1851
10184 "This is a list of currently registered Input-Output port regions that are in "
10189 #: build/C/man5/proc.5:1851
10191 msgid "I</proc/kallsyms> (since Linux 2.5.71)"
10194 #. type: Plain text
10195 #: build/C/man5/proc.5:1859
10197 "This holds the kernel exported symbol definitions used by the B<modules>(X) "
10198 "tools to dynamically link and bind loadable modules. In Linux 2.5.47 and "
10199 "earlier, a similar file with slightly different syntax was named I<ksyms>."
10203 #: build/C/man5/proc.5:1859
10205 msgid "I</proc/kcore>"
10208 #. type: Plain text
10209 #: build/C/man5/proc.5:1868
10211 "This file represents the physical memory of the system and is stored in the "
10212 "ELF core file format. With this pseudo-file, and an unstripped kernel "
10213 "(I</usr/src/linux/vmlinux>) binary, GDB can be used to examine the current "
10214 "state of any kernel data structures."
10217 #. type: Plain text
10218 #: build/C/man5/proc.5:1871
10219 msgid "The total length of the file is the size of physical memory (RAM) plus 4KB."
10223 #: build/C/man5/proc.5:1871
10225 msgid "I</proc/kmsg>"
10228 #. type: Plain text
10229 #: build/C/man5/proc.5:1883
10231 "This file can be used instead of the B<syslog>(2) system call to read "
10232 "kernel messages. A process must have superuser privileges to read this "
10233 "file, and only one process should read this file. This file should not be "
10234 "read if a syslog process is running which uses the B<syslog>(2) system call "
10235 "facility to log kernel messages."
10238 #. type: Plain text
10239 #: build/C/man5/proc.5:1887
10240 msgid "Information in this file is retrieved with the B<dmesg>(1) program."
10244 #: build/C/man5/proc.5:1887
10246 msgid "I</proc/ksyms> (Linux 1.1.23-2.5.47)"
10249 #. type: Plain text
10250 #: build/C/man5/proc.5:1891
10251 msgid "See I</proc/kallsyms>."
10255 #: build/C/man5/proc.5:1891
10257 msgid "I</proc/loadavg>"
10260 #. type: Plain text
10261 #: build/C/man5/proc.5:1906
10263 "The first three fields in this file are load average figures giving the "
10264 "number of jobs in the run queue (state R) or waiting for disk I/O (state D) "
10265 "averaged over 1, 5, and 15 minutes. They are the same as the load average "
10266 "numbers given by B<uptime>(1) and other programs. The fourth field "
10267 "consists of two numbers separated by a slash (/). The first of these is the "
10268 "number of currently runnable kernel scheduling entities (processes, "
10269 "threads). The value after the slash is the number of kernel scheduling "
10270 "entities that currently exist on the system. The fifth field is the PID of "
10271 "the process that was most recently created on the system."
10275 #: build/C/man5/proc.5:1906
10277 msgid "I</proc/locks>"
10280 #. type: Plain text
10281 #: build/C/man5/proc.5:1912
10283 "This file shows current file locks (B<flock>(2) and B<fcntl>(2)) and leases "
10288 #: build/C/man5/proc.5:1912
10290 msgid "I</proc/malloc> (only up to and including Linux 2.2)"
10293 #. It looks like this only ever did something back in 1.0 days
10294 #. type: Plain text
10295 #: build/C/man5/proc.5:1918
10297 "This file is present only if B<CONFIG_DEBUG_MALLOC> was defined during "
10302 #: build/C/man5/proc.5:1918
10304 msgid "I</proc/meminfo>"
10307 #. type: Plain text
10308 #: build/C/man5/proc.5:1934
10310 "This file reports statistics about memory usage on the system. It is used "
10311 "by B<free>(1) to report the amount of free and used memory (both physical "
10312 "and swap) on the system as well as the shared memory and buffers used by "
10313 "the kernel. Each line of the file consists of a parameter name, followed by "
10314 "a colon, the value of the parameter, and an option unit of measurement "
10315 "(e.g., \"kB\"). The list below describes the parameter names and the format "
10316 "specifier required to read the field value. Except as noted below, all of "
10317 "the fields have been present since at least Linux 2.6.0. Some fields are "
10318 "displayed only if the kernel was configured with various options; those "
10319 "dependencies are noted in the list."
10323 #: build/C/man5/proc.5:1935
10325 msgid "I<MemTotal> %lu"
10328 #. type: Plain text
10329 #: build/C/man5/proc.5:1939
10331 "Total usable RAM (i.e., physical RAM minus a few reserved bits and the "
10332 "kernel binary code)."
10336 #: build/C/man5/proc.5:1939
10338 msgid "I<MemFree> %lu"
10341 #. type: Plain text
10342 #: build/C/man5/proc.5:1943
10343 msgid "The sum of I<LowFree>+I<HighFree>."
10347 #: build/C/man5/proc.5:1943
10349 msgid "I<Buffers> %lu"
10352 #. type: Plain text
10353 #: build/C/man5/proc.5:1947
10355 "Relatively temporary storage for raw disk blocks that shouldn't get "
10356 "tremendously large (20MB or so)."
10360 #: build/C/man5/proc.5:1947
10362 msgid "I<Cached> %lu"
10365 #. type: Plain text
10366 #: build/C/man5/proc.5:1952
10368 "In-memory cache for files read from the disk (the page cache). Doesn't "
10369 "include I<SwapCached>."
10373 #: build/C/man5/proc.5:1952
10375 msgid "I<SwapCached> %lu"
10378 #. type: Plain text
10379 #: build/C/man5/proc.5:1960
10381 "Memory that once was swapped out, is swapped back in but still also is in "
10382 "the swap file. (If memory pressure is high, these pages don't need to be "
10383 "swapped out again because they are already in the swap file. This saves "
10388 #: build/C/man5/proc.5:1960
10390 msgid "I<Active> %lu"
10393 #. type: Plain text
10394 #: build/C/man5/proc.5:1964
10396 "Memory that has been used more recently and usually not reclaimed unless "
10397 "absolutely necessary."
10401 #: build/C/man5/proc.5:1964
10403 msgid "I<Inactive> %lu"
10406 #. type: Plain text
10407 #: build/C/man5/proc.5:1968
10409 "Memory which has been less recently used. It is more eligible to be "
10410 "reclaimed for other purposes."
10414 #: build/C/man5/proc.5:1968
10416 msgid "I<Active(anon)> %lu (since Linux 2.6.28)"
10419 #. type: Plain text
10420 #: build/C/man5/proc.5:1971 build/C/man5/proc.5:1974 build/C/man5/proc.5:1977 build/C/man5/proc.5:1980 build/C/man5/proc.5:2047
10421 msgid "[To be documented.]"
10425 #: build/C/man5/proc.5:1971
10427 msgid "I<Inactive(anon)> %lu (since Linux 2.6.28)"
10431 #: build/C/man5/proc.5:1974
10433 msgid "I<Active(file)> %lu (since Linux 2.6.28)"
10437 #: build/C/man5/proc.5:1977
10439 msgid "I<Inactive(file)> %lu (since Linux 2.6.28)"
10443 #: build/C/man5/proc.5:1980
10445 msgid "I<Unevictable> %lu (since Linux 2.6.28)"
10448 #. type: Plain text
10449 #: build/C/man5/proc.5:1985 build/C/man5/proc.5:1990
10451 "(From Linux 2.6.28 to 2.6.30, B<CONFIG_UNEVICTABLE_LRU> was required.) [To "
10456 #: build/C/man5/proc.5:1985
10458 msgid "I<Mlocked> %lu (since Linux 2.6.28)"
10462 #: build/C/man5/proc.5:1990
10464 msgid "I<HighTotal> %lu"
10467 #. type: Plain text
10468 #: build/C/man5/proc.5:1999
10470 "(Starting with Linux 2.6.19, B<CONFIG_HIGHMEM> is required.) Total amount "
10471 "of highmem. Highmem is all memory above ~860MB of physical memory. Highmem "
10472 "areas are for use by user-space programs, or for the page cache. The kernel "
10473 "must use tricks to access this memory, making it slower to access than "
10478 #: build/C/man5/proc.5:1999
10480 msgid "I<HighFree> %lu"
10483 #. type: Plain text
10484 #: build/C/man5/proc.5:2003
10486 "(Starting with Linux 2.6.19, B<CONFIG_HIGHMEM> is required.) Amount of free "
10491 #: build/C/man5/proc.5:2003
10493 msgid "I<LowTotal> %lu"
10496 #. type: Plain text
10497 #: build/C/man5/proc.5:2015
10499 "(Starting with Linux 2.6.19, B<CONFIG_HIGHMEM> is required.) Total amount "
10500 "of lowmem. Lowmem is memory which can be used for everything that highmem "
10501 "can be used for, but it is also available for the kernel's use for its own "
10502 "data structures. Among many other things, it is where everything from "
10503 "I<Slab> is allocated. Bad things happen when you're out of lowmem."
10507 #: build/C/man5/proc.5:2015
10509 msgid "I<LowFree> %lu"
10512 #. type: Plain text
10513 #: build/C/man5/proc.5:2019
10515 "(Starting with Linux 2.6.19, B<CONFIG_HIGHMEM> is required.) Amount of free "
10520 #: build/C/man5/proc.5:2019
10522 msgid "I<MmapCopy> %lu (since Linux 2.6.29)"
10525 #. type: Plain text
10526 #: build/C/man5/proc.5:2024
10527 msgid "(B<CONFIG_MMU> is required.) [To be documented.]"
10531 #: build/C/man5/proc.5:2024
10533 msgid "I<SwapTotal> %lu"
10536 #. type: Plain text
10537 #: build/C/man5/proc.5:2027
10538 msgid "Total amount of swap space available."
10542 #: build/C/man5/proc.5:2027
10544 msgid "I<SwapFree> %lu"
10547 #. type: Plain text
10548 #: build/C/man5/proc.5:2030
10549 msgid "Amount of swap space that is currently unused."
10553 #: build/C/man5/proc.5:2030
10555 msgid "I<Dirty> %lu"
10558 #. type: Plain text
10559 #: build/C/man5/proc.5:2033
10560 msgid "Memory which is waiting to get written back to the disk."
10564 #: build/C/man5/proc.5:2033
10566 msgid "I<Writeback> %lu"
10569 #. type: Plain text
10570 #: build/C/man5/proc.5:2036
10571 msgid "Memory which is actively being written back to the disk."
10575 #: build/C/man5/proc.5:2036
10577 msgid "I<AnonPages> %lu (since Linux 2.6.18)"
10580 #. type: Plain text
10581 #: build/C/man5/proc.5:2039
10582 msgid "Non-file backed pages mapped into user-space page tables."
10586 #: build/C/man5/proc.5:2039
10588 msgid "I<Mapped> %lu"
10591 #. type: Plain text
10592 #: build/C/man5/proc.5:2044
10594 "Files which have been mapped into memory (with B<mmap>(2)), such as "
10599 #: build/C/man5/proc.5:2044
10601 msgid "I<Shmem> %lu (since Linux 2.6.32)"
10605 #: build/C/man5/proc.5:2047
10607 msgid "I<Slab> %lu"
10610 #. type: Plain text
10611 #: build/C/man5/proc.5:2050
10612 msgid "In-kernel data structures cache."
10616 #: build/C/man5/proc.5:2050
10618 msgid "I<SReclaimable> %lu (since Linux 2.6.19)"
10621 #. type: Plain text
10622 #: build/C/man5/proc.5:2055
10623 msgid "Part of I<Slab>, that might be reclaimed, such as caches."
10627 #: build/C/man5/proc.5:2055
10629 msgid "I<SUnreclaim> %lu (since Linux 2.6.19)"
10632 #. type: Plain text
10633 #: build/C/man5/proc.5:2060
10634 msgid "Part of I<Slab>, that cannot be reclaimed on memory pressure."
10638 #: build/C/man5/proc.5:2060
10640 msgid "I<KernelStack> %lu (since Linux 2.6.32)"
10643 #. type: Plain text
10644 #: build/C/man5/proc.5:2063
10645 msgid "Amount of memory allocated to kernel stacks."
10649 #: build/C/man5/proc.5:2063
10651 msgid "I<PageTables> %lu (since Linux 2.6.18)"
10654 #. type: Plain text
10655 #: build/C/man5/proc.5:2066
10656 msgid "Amount of memory dedicated to the lowest level of page tables."
10660 #: build/C/man5/proc.5:2066
10662 msgid "I<Quicklists> %lu (since Linux 2.6.27)"
10665 #. type: Plain text
10666 #: build/C/man5/proc.5:2070
10667 msgid "(B<CONFIG_QUICKLIST> is required.) [To be documented.]"
10671 #: build/C/man5/proc.5:2070
10673 msgid "I<NFS_Unstable> %lu (since Linux 2.6.18)"
10676 #. type: Plain text
10677 #: build/C/man5/proc.5:2073
10678 msgid "NFS pages sent to the server, but not yet committed to stable storage."
10682 #: build/C/man5/proc.5:2073
10684 msgid "I<Bounce> %lu (since Linux 2.6.18)"
10687 #. type: Plain text
10688 #: build/C/man5/proc.5:2076
10689 msgid "Memory used for block device \"bounce buffers\"."
10693 #: build/C/man5/proc.5:2076
10695 msgid "I<WritebackTmp> %lu (since Linux 2.6.26)"
10698 #. type: Plain text
10699 #: build/C/man5/proc.5:2079
10700 msgid "Memory used by FUSE for temporary writeback buffers."
10704 #: build/C/man5/proc.5:2079
10706 msgid "I<CommitLimit> %lu (since Linux 2.6.10)"
10709 #. type: Plain text
10710 #: build/C/man5/proc.5:2090
10712 "Based on the overcommit ratio ('vm.overcommit_ratio'), this is the total "
10713 "amount of memory currently available to be allocated on the system. This "
10714 "limit is adhered to only if strict overcommit accounting is enabled (mode 2 "
10715 "in I</proc/sys/vm/overcommit_ratio>). The I<CommitLimit> is calculated "
10716 "using the following formula:"
10719 #. type: Plain text
10720 #: build/C/man5/proc.5:2094
10724 " ([total RAM pages] - [total huge TLB pages]) *\n"
10725 " overcommit_ratio / 100 + [total swap pages]\n"
10728 #. type: Plain text
10729 #: build/C/man5/proc.5:2104
10731 "For example, on a system with 1GB of physical RAM and 7GB of swap with a "
10732 "I<overcommit_ratio> of 30, this formula yields a I<CommitLimit> of 7.3GB. "
10733 "For more details, see the memory overcommit documentation in the kernel "
10734 "source file I<Documentation/vm/overcommit-accounting>."
10738 #: build/C/man5/proc.5:2104
10740 msgid "I<Committed_AS> %lu"
10743 #. type: Plain text
10744 #: build/C/man5/proc.5:2124
10746 "The amount of memory presently allocated on the system. The committed "
10747 "memory is a sum of all of the memory which has been allocated by processes, "
10748 "even if it has not been \"used\" by them as of yet. A process which "
10749 "allocates 1GB of memory (using B<malloc>(3) or similar), but touches only "
10750 "300MB of that memory will show up as using only 300MB of memory even if it "
10751 "has the address space allocated for the entire 1GB. This 1GB is memory "
10752 "which has been \"committed\" to by the VM and can be used at any time by the "
10753 "allocating application. With strict overcommit enabled on the system (mode "
10754 "2 I</proc/sys/vm/overcommit_memory>), allocations which would exceed the "
10755 "I<CommitLimit> (detailed above) will not be permitted. This is useful if "
10756 "one needs to guarantee that processes will not fail due to lack of memory "
10757 "once that memory has been successfully allocated."
10761 #: build/C/man5/proc.5:2124
10763 msgid "I<VmallocTotal> %lu"
10766 #. type: Plain text
10767 #: build/C/man5/proc.5:2127
10768 msgid "Total size of vmalloc memory area."
10772 #: build/C/man5/proc.5:2127
10774 msgid "I<VmallocUsed> %lu"
10777 #. type: Plain text
10778 #: build/C/man5/proc.5:2130
10779 msgid "Amount of vmalloc area which is used."
10783 #: build/C/man5/proc.5:2130
10785 msgid "I<VmallocChunk> %lu"
10788 #. type: Plain text
10789 #: build/C/man5/proc.5:2133
10790 msgid "Largest contiguous block of vmalloc area which is free."
10794 #: build/C/man5/proc.5:2133
10796 msgid "I<HardwareCorrupted> %lu (since Linux 2.6.32)"
10799 #. type: Plain text
10800 #: build/C/man5/proc.5:2137
10801 msgid "(B<CONFIG_MEMORY_FAILURE> is required.) [To be documented.]"
10805 #: build/C/man5/proc.5:2137
10807 msgid "I<AnonHugePages> %lu (since Linux 2.6.38)"
10810 #. type: Plain text
10811 #: build/C/man5/proc.5:2141
10813 "(B<CONFIG_TRANSPARENT_HUGEPAGE> is required.) Non-file backed huge pages "
10814 "mapped into user-space page tables."
10818 #: build/C/man5/proc.5:2141
10820 msgid "I<HugePages_Total> %lu"
10823 #. type: Plain text
10824 #: build/C/man5/proc.5:2145
10825 msgid "(B<CONFIG_HUGETLB_PAGE> is required.) The size of the pool of huge pages."
10829 #: build/C/man5/proc.5:2145
10831 msgid "I<HugePages_Free> %lu"
10834 #. type: Plain text
10835 #: build/C/man5/proc.5:2149
10837 "(B<CONFIG_HUGETLB_PAGE> is required.) The number of huge pages in the pool "
10838 "that are not yet allocated."
10842 #: build/C/man5/proc.5:2149
10844 msgid "I<HugePages_Rsvd> %lu (since Linux 2.6.17)"
10847 #. type: Plain text
10848 #: build/C/man5/proc.5:2158
10850 "(B<CONFIG_HUGETLB_PAGE> is required.) This is the number of huge pages for "
10851 "which a commitment to allocate from the pool has been made, but no "
10852 "allocation has yet been made. These reserved huge pages guarantee that an "
10853 "application will be able to allocate a huge page from the pool of huge pages "
10858 #: build/C/man5/proc.5:2158
10860 msgid "I<HugePages_Surp> %lu (since Linux 2.6.24)"
10863 #. type: Plain text
10864 #: build/C/man5/proc.5:2166
10866 "(B<CONFIG_HUGETLB_PAGE> is required.) This is the number of huge pages in "
10867 "the pool above the value in I</proc/sys/vm/nr_hugepages>. The maximum "
10868 "number of surplus huge pages is controlled by "
10869 "I</proc/sys/vm/nr_overcommit_hugepages>."
10873 #: build/C/man5/proc.5:2166
10875 msgid "I<Hugepagesize> %lu"
10878 #. type: Plain text
10879 #: build/C/man5/proc.5:2170
10880 msgid "(B<CONFIG_HUGETLB_PAGE> is required.) The size of huge pages."
10884 #: build/C/man5/proc.5:2171
10886 msgid "I</proc/modules>"
10889 #. type: Plain text
10890 #: build/C/man5/proc.5:2176
10892 "A text list of the modules that have been loaded by the system. See also "
10897 #: build/C/man5/proc.5:2176
10899 msgid "I</proc/mounts>"
10902 #. type: Plain text
10903 #: build/C/man5/proc.5:2186
10905 "Before kernel 2.4.19, this file was a list of all the filesystems currently "
10906 "mounted on the system. With the introduction of per-process mount "
10907 "namespaces in Linux 2.4.19, this file became a link to I</proc/self/mounts>, "
10908 "which lists the mount points of the process's own mount namespace. The "
10909 "format of this file is documented in B<fstab>(5)."
10913 #: build/C/man5/proc.5:2186
10915 msgid "I</proc/mtrr>"
10918 #. type: Plain text
10919 #: build/C/man5/proc.5:2192
10921 "Memory Type Range Registers. See the Linux kernel source file "
10922 "I<Documentation/mtrr.txt> for details."
10926 #: build/C/man5/proc.5:2192
10928 msgid "I</proc/net>"
10931 #. type: Plain text
10932 #: build/C/man5/proc.5:2202
10934 "various net pseudo-files, all of which give the status of some part of the "
10935 "networking layer. These files contain ASCII structures and are, therefore, "
10936 "readable with B<cat>(1). However, the standard B<netstat>(8) suite "
10937 "provides much cleaner access to these files."
10941 #: build/C/man5/proc.5:2202
10943 msgid "I</proc/net/arp>"
10946 #. type: Plain text
10947 #: build/C/man5/proc.5:2208
10949 "This holds an ASCII readable dump of the kernel ARP table used for address "
10950 "resolutions. It will show both dynamically learned and preprogrammed ARP "
10951 "entries. The format is:"
10954 #. type: Plain text
10955 #: build/C/man5/proc.5:2215
10958 "CW<IP address HW type Flags HW address Mask Device\n"
10959 "192.168.0.50 0x1 0x2 00:50:BF:25:68:F3 * eth0\n"
10960 "192.168.0.250 0x1 0xc 00:00:00:00:00:00 * eth0>\n"
10963 #. type: Plain text
10964 #: build/C/man5/proc.5:2227
10966 "Here \"IP address\" is the IPv4 address of the machine and the \"HW type\" "
10967 "is the hardware type of the address from RFC\\ 826. The flags are the "
10968 "internal flags of the ARP structure (as defined in "
10969 "I</usr/include/linux/if_arp.h>) and the \"HW address\" is the data link "
10970 "layer mapping for that IP address if it is known."
10974 #: build/C/man5/proc.5:2227
10976 msgid "I</proc/net/dev>"
10979 #. type: Plain text
10980 #: build/C/man5/proc.5:2238
10982 "The dev pseudo-file contains network device status information. This gives "
10983 "the number of received and sent packets, the number of errors and collisions "
10984 "and other basic statistics. These are used by the B<ifconfig>(8) program "
10985 "to report device status. The format is:"
10988 #. type: Plain text
10989 #: build/C/man5/proc.5:2248
10992 "CW<Inter-| Receive | "
10994 " face |bytes packets errs drop fifo frame compressed multicast|bytes "
10995 "packets errs drop fifo colls carrier compressed\n"
10996 " lo: 2776770 11307 0 0 0 0 0 0 2776770 "
10997 "11307 0 0 0 0 0 0\n"
10998 " eth0: 1215645 2751 0 0 0 0 0 0 1782404 "
10999 "4324 0 0 0 427 0 0\n"
11000 " ppp0: 1622270 5552 1 0 0 0 0 0 354130 "
11001 "5669 0 0 0 0 0 0\n"
11002 " tap0: 7714 81 0 0 0 0 0 0 7714 "
11003 "81 0 0 0 0 0 0>\n"
11007 #: build/C/man5/proc.5:2257
11009 msgid "I</proc/net/dev_mcast>"
11012 #. type: Plain text
11013 #: build/C/man5/proc.5:2261
11014 msgid "Defined in I</usr/src/linux/net/core/dev_mcast.c>:"
11017 #. type: Plain text
11018 #: build/C/man5/proc.5:2267
11021 "indx interface_name dmi_u dmi_g dmi_address\n"
11022 "2 eth0 1 0 01005e000001\n"
11023 "3 eth1 1 0 01005e000001\n"
11024 "4 eth2 1 0 01005e000001\n"
11028 #: build/C/man5/proc.5:2269
11030 msgid "I</proc/net/igmp>"
11033 #. type: Plain text
11034 #: build/C/man5/proc.5:2274
11036 "Internet Group Management Protocol. Defined in "
11037 "I</usr/src/linux/net/core/igmp.c>."
11041 #: build/C/man5/proc.5:2274
11043 msgid "I</proc/net/rarp>"
11046 #. type: Plain text
11047 #: build/C/man5/proc.5:2284
11049 "This file uses the same format as the I<arp> file and contains the current "
11050 "reverse mapping database used to provide B<rarp>(8) reverse address lookup "
11051 "services. If RARP is not configured into the kernel, this file will not be "
11056 #: build/C/man5/proc.5:2284
11058 msgid "I</proc/net/raw>"
11062 #. .I /proc/net/route
11063 #. No information, but looks similar to
11065 #. type: Plain text
11066 #: build/C/man5/proc.5:2304
11068 "Holds a dump of the RAW socket table. Much of the information is not of use "
11069 "apart from debugging. The \"sl\" value is the kernel hash slot for the "
11070 "socket, the \"local_address\" is the local address and protocol number "
11071 "pair. \\&\"St\" is the internal status of the socket. The \"tx_queue\" and "
11072 "\"rx_queue\" are the outgoing and incoming data queue in terms of kernel "
11073 "memory usage. The \"tr\", \"tm-E<gt>when\", and \"rexmits\" fields are not "
11074 "used by RAW. The \"uid\" field holds the effective UID of the creator of "
11079 #: build/C/man5/proc.5:2304
11081 msgid "I</proc/net/snmp>"
11084 #. type: Plain text
11085 #: build/C/man5/proc.5:2309
11087 "This file holds the ASCII data needed for the IP, ICMP, TCP, and UDP "
11088 "management information bases for an SNMP agent."
11092 #: build/C/man5/proc.5:2309
11094 msgid "I</proc/net/tcp>"
11097 #. type: Plain text
11098 #: build/C/man5/proc.5:2325
11100 "Holds a dump of the TCP socket table. Much of the information is not of use "
11101 "apart from debugging. The \"sl\" value is the kernel hash slot for the "
11102 "socket, the \"local_address\" is the local address and port number pair. "
11103 "The \"rem_address\" is the remote address and port number pair (if "
11104 "connected). \\&\"St\" is the internal status of the socket. The "
11105 "\"tx_queue\" and \"rx_queue\" are the outgoing and incoming data queue in "
11106 "terms of kernel memory usage. The \"tr\", \"tm-E<gt>when\", and \"rexmits\" "
11107 "fields hold internal information of the kernel socket state and are only "
11108 "useful for debugging. The \"uid\" field holds the effective UID of the "
11109 "creator of the socket."
11113 #: build/C/man5/proc.5:2325
11115 msgid "I</proc/net/udp>"
11118 #. type: Plain text
11119 #: build/C/man5/proc.5:2341
11121 "Holds a dump of the UDP socket table. Much of the information is not of use "
11122 "apart from debugging. The \"sl\" value is the kernel hash slot for the "
11123 "socket, the \"local_address\" is the local address and port number pair. "
11124 "The \"rem_address\" is the remote address and port number pair (if "
11125 "connected). \"St\" is the internal status of the socket. The \"tx_queue\" "
11126 "and \"rx_queue\" are the outgoing and incoming data queue in terms of kernel "
11127 "memory usage. The \"tr\", \"tm-E<gt>when\", and \"rexmits\" fields are not "
11128 "used by UDP. The \"uid\" field holds the effective UID of the creator of "
11129 "the socket. The format is:"
11132 #. type: Plain text
11133 #: build/C/man5/proc.5:2349
11136 "CW<sl local_address rem_address st tx_queue rx_queue tr rexmits "
11137 "tm-E<gt>when uid\n"
11138 " 1: 01642C89:0201 0C642C89:03FF 01 00000000:00000001 01:000071BA 00000000 "
11140 " 1: 00000000:0801 00000000:0000 0A 00000000:00000000 00:00000000 6F000100 "
11142 " 1: 00000000:0201 00000000:0000 0A 00000000:00000000 00:00000000 00000000 "
11147 #: build/C/man5/proc.5:2352
11149 msgid "I</proc/net/unix>"
11152 #. type: Plain text
11153 #: build/C/man5/proc.5:2357
11155 "Lists the UNIX domain sockets present within the system and their status. "
11159 #. type: Plain text
11160 #: build/C/man5/proc.5:2363
11163 "CW<Num RefCount Protocol Flags Type St Path\n"
11164 " 0: 00000002 00000000 00000000 0001 03\n"
11165 " 1: 00000001 00000000 00010000 0001 01 /dev/printer>\n"
11168 #. type: Plain text
11169 #: build/C/man5/proc.5:2375
11171 "Here \"Num\" is the kernel table slot number, \"RefCount\" is the number of "
11172 "users of the socket, \"Protocol\" is currently always 0, \"Flags\" represent "
11173 "the internal kernel flags holding the status of the socket. Currently, type "
11174 "is always \"1\" (UNIX domain datagram sockets are not yet supported in the "
11175 "kernel). \\&\"St\" is the internal state of the socket and Path is the "
11176 "bound path (if any) of the socket."
11180 #: build/C/man5/proc.5:2375
11182 msgid "I</proc/partitions>"
11185 #. type: Plain text
11186 #: build/C/man5/proc.5:2379
11188 "Contains the major and minor numbers of each partition as well as the number "
11189 "of 1024-byte blocks and the partition name."
11193 #: build/C/man5/proc.5:2379
11195 msgid "I</proc/pci>"
11198 #. type: Plain text
11199 #: build/C/man5/proc.5:2383
11201 "This is a listing of all PCI devices found during kernel initialization and "
11202 "their configuration."
11205 #. FIXME /proc/sched_debug
11207 #. .IR /proc/sched_debug " (since Linux 2.6.23)"
11208 #. See also /proc/[pid]/sched
11209 #. type: Plain text
11210 #: build/C/man5/proc.5:2399
11212 "This file has been deprecated in favor of a new I</proc> interface for PCI "
11213 "(I</proc/bus/pci>). It became optional in Linux 2.2 (available with "
11214 "B<CONFIG_PCI_OLD_PROC> set at kernel compilation). It became once more "
11215 "nonoptionally enabled in Linux 2.4. Next, it was deprecated in Linux 2.6 "
11216 "(still available with B<CONFIG_PCI_LEGACY_PROC> set), and finally removed "
11217 "altogether since Linux 2.6.17."
11221 #: build/C/man5/proc.5:2399
11223 msgid "I</proc/profile> (since Linux 2.4)"
11226 #. type: Plain text
11227 #: build/C/man5/proc.5:2411
11229 "This file is present only if the kernel was booted with the I<profile=1> "
11230 "command-line option. It exposes kernel profiling information in a binary "
11231 "format for use by B<readprofile>(1). Writing (e.g., an empty string) to "
11232 "this file resets the profiling counters; on some architectures, writing a "
11233 "binary integer \"profiling multiplier\" of size I<sizeof(int)> sets the "
11234 "profiling interrupt frequency."
11238 #: build/C/man5/proc.5:2411
11240 msgid "I</proc/scsi>"
11243 #. type: Plain text
11244 #: build/C/man5/proc.5:2421
11246 "A directory with the I<scsi> mid-level pseudo-file and various SCSI "
11247 "low-level driver directories, which contain a file for each SCSI host in "
11248 "this system, all of which give the status of some part of the SCSI IO "
11249 "subsystem. These files contain ASCII structures and are, therefore, "
11250 "readable with B<cat>(1)."
11253 #. type: Plain text
11254 #: build/C/man5/proc.5:2424
11256 "You can also write to some of the files to reconfigure the subsystem or "
11257 "switch certain features on or off."
11261 #: build/C/man5/proc.5:2424
11263 msgid "I</proc/scsi/scsi>"
11266 #. type: Plain text
11267 #: build/C/man5/proc.5:2430
11269 "This is a listing of all SCSI devices known to the kernel. The listing is "
11270 "similar to the one seen during bootup. scsi currently supports only the "
11271 "I<add-single-device> command which allows root to add a hotplugged device to "
11272 "the list of known devices."
11275 #. type: Plain text
11276 #: build/C/man5/proc.5:2432
11277 msgid "The command"
11280 #. type: Plain text
11281 #: build/C/man5/proc.5:2436
11283 msgid "echo \\(aqscsi add-single-device 1 0 5 0\\(aq E<gt> /proc/scsi/scsi\n"
11286 #. type: Plain text
11287 #: build/C/man5/proc.5:2444
11289 "will cause host scsi1 to scan on SCSI channel 0 for a device on ID 5 LUN 0. "
11290 "If there is already a device known on this address or the address is "
11291 "invalid, an error will be returned."
11295 #: build/C/man5/proc.5:2444
11297 msgid "I</proc/scsi/[drivername]>"
11300 #. type: Plain text
11301 #: build/C/man5/proc.5:2454
11303 "I<[drivername]> can currently be NCR53c7xx, aha152x, aha1542, aha1740, "
11304 "aic7xxx, buslogic, eata_dma, eata_pio, fdomain, in2000, pas16, qlogic, "
11305 "scsi_debug, seagate, t128, u15-24f, ultrastore, or wd7000. These "
11306 "directories show up for all drivers that registered at least one SCSI HBA. "
11307 "Every directory contains one file per registered host. Every host-file is "
11308 "named after the number the host was assigned during initialization."
11311 #. type: Plain text
11312 #: build/C/man5/proc.5:2457
11314 "Reading these files will usually show driver and host configuration, "
11315 "statistics, and so on."
11318 #. type: Plain text
11319 #: build/C/man5/proc.5:2464
11321 "Writing to these files allows different things on different hosts. For "
11322 "example, with the I<latency> and I<nolatency> commands, root can switch on "
11323 "and off command latency measurement code in the eata_dma driver. With the "
11324 "I<lockup> and I<unlock> commands, root can control bus lockups simulated by "
11325 "the scsi_debug driver."
11329 #: build/C/man5/proc.5:2464
11331 msgid "I</proc/self>"
11334 #. type: Plain text
11335 #: build/C/man5/proc.5:2472
11337 "This directory refers to the process accessing the I</proc> filesystem, and "
11338 "is identical to the I</proc> directory named by the process ID of the same "
11343 #: build/C/man5/proc.5:2472
11345 msgid "I</proc/slabinfo>"
11348 #. type: Plain text
11349 #: build/C/man5/proc.5:2481
11351 "Information about kernel caches. Since Linux 2.6.16 this file is present "
11352 "only if the B<CONFIG_SLAB> kernel configuration option is enabled. The "
11353 "columns in I</proc/slabinfo> are:"
11356 #. type: Plain text
11357 #: build/C/man5/proc.5:2491
11361 "num-active-objs\n"
11364 "num-active-slabs\n"
11366 "num-pages-per-slab\n"
11369 #. type: Plain text
11370 #: build/C/man5/proc.5:2497
11371 msgid "See B<slabinfo>(5) for details."
11375 #: build/C/man5/proc.5:2497
11377 msgid "I</proc/stat>"
11380 #. type: Plain text
11381 #: build/C/man5/proc.5:2503
11383 "kernel/system statistics. Varies with architecture. Common entries "
11388 #: build/C/man5/proc.5:2504
11390 msgid "I<cpu 3357 0 4313 1362393>"
11393 #. 1024 on Alpha and ia64
11394 #. type: Plain text
11395 #: build/C/man5/proc.5:2512
11397 "The amount of time, measured in units of USER_HZ (1/100ths of a second on "
11398 "most architectures, use I<sysconf(_SC_CLK_TCK)> to obtain the right value), "
11399 "that the system spent in various states:"
11403 #: build/C/man5/proc.5:2513
11408 #. type: Plain text
11409 #: build/C/man5/proc.5:2516
11410 msgid "(1) Time spent in user mode."
11414 #: build/C/man5/proc.5:2516
11419 #. type: Plain text
11420 #: build/C/man5/proc.5:2519
11421 msgid "(2) Time spent in user mode with low priority (nice)."
11425 #: build/C/man5/proc.5:2519
11430 #. type: Plain text
11431 #: build/C/man5/proc.5:2522
11432 msgid "(3) Time spent in system mode."
11436 #: build/C/man5/proc.5:2522
11441 #. FIXME Actually, the following info about the /proc/stat 'cpu' field
11442 #. does not seem to be quite right (at least in 2.6.12 or 3.6):
11443 #. the idle time in /proc/uptime does not quite match this value
11444 #. type: Plain text
11445 #: build/C/man5/proc.5:2532
11447 "(4) Time spent in the idle task. This value should be USER_HZ times the "
11448 "second entry in the I</proc/uptime> pseudo-file."
11452 #: build/C/man5/proc.5:2532
11454 msgid "I<iowait> (since Linux 2.5.41)"
11457 #. type: Plain text
11458 #: build/C/man5/proc.5:2535
11459 msgid "(5) Time waiting for I/O to complete."
11463 #: build/C/man5/proc.5:2535
11465 msgid "I<irq> (since Linux 2.6.0-test4)"
11468 #. type: Plain text
11469 #: build/C/man5/proc.5:2538
11470 msgid "(6) Time servicing interrupts."
11474 #: build/C/man5/proc.5:2538
11476 msgid "I<softirq> (since Linux 2.6.0-test4)"
11479 #. type: Plain text
11480 #: build/C/man5/proc.5:2541
11481 msgid "(7) Time servicing softirqs."
11485 #: build/C/man5/proc.5:2541
11487 msgid "I<steal> (since Linux 2.6.11)"
11490 #. type: Plain text
11491 #: build/C/man5/proc.5:2545
11493 "(8) Stolen time, which is the time spent in other operating systems when "
11494 "running in a virtualized environment"
11498 #: build/C/man5/proc.5:2545
11500 msgid "I<guest> (since Linux 2.6.24)"
11503 #. See Changelog entry for 5e84cfde51cf303d368fcb48f22059f37b3872de
11504 #. type: Plain text
11505 #: build/C/man5/proc.5:2550
11507 "(9) Time spent running a virtual CPU for guest operating systems under the "
11508 "control of the Linux kernel."
11512 #: build/C/man5/proc.5:2550
11514 msgid "I<guest_nice> (since Linux 2.6.33)"
11517 #. commit ce0e7b28fb75cb003cfc8d0238613aaf1c55e797
11518 #. type: Plain text
11519 #: build/C/man5/proc.5:2555
11521 "(10) Time spent running a niced guest (virtual CPU for guest operating "
11522 "systems under the control of the Linux kernel)."
11526 #: build/C/man5/proc.5:2556
11528 msgid "I<page 5741 1808>"
11531 #. type: Plain text
11532 #: build/C/man5/proc.5:2560
11534 "The number of pages the system paged in and the number that were paged out "
11539 #: build/C/man5/proc.5:2560
11541 msgid "I<swap 1 0>"
11544 #. type: Plain text
11545 #: build/C/man5/proc.5:2563
11546 msgid "The number of swap pages that have been brought in and out."
11549 #. FIXME The following is not the full picture for the 'intr' of
11550 #. /proc/stat on 2.6:
11552 #: build/C/man5/proc.5:2563
11554 msgid "I<intr 1462898>"
11557 #. type: Plain text
11558 #: build/C/man5/proc.5:2573
11560 "This line shows counts of interrupts serviced since boot time, for each of "
11561 "the possible system interrupts. The first column is the total of all "
11562 "interrupts serviced including unnumbered architecture specific interrupts; "
11563 "each subsequent column is the total for that particular numbered interrupt. "
11564 "Unnumbered interrupts are not shown, only summed into the total."
11568 #: build/C/man5/proc.5:2573
11570 msgid "I<disk_io: (2,0):(31,30,5764,1,2) (3,0):>..."
11573 #. type: Plain text
11574 #: build/C/man5/proc.5:2576
11576 "(major,disk_idx):(noinfo, read_io_ops, blks_read, write_io_ops, "
11580 #. type: Plain text
11581 #: build/C/man5/proc.5:2578
11582 msgid "(Linux 2.4 only)"
11586 #: build/C/man5/proc.5:2578
11588 msgid "I<ctxt 115315>"
11591 #. type: Plain text
11592 #: build/C/man5/proc.5:2581
11593 msgid "The number of context switches that the system underwent."
11597 #: build/C/man5/proc.5:2581
11599 msgid "I<btime 769041601>"
11602 #. type: Plain text
11603 #: build/C/man5/proc.5:2584
11604 msgid "boot time, in seconds since the Epoch, 1970-01-01 00:00:00 +0000 (UTC)."
11608 #: build/C/man5/proc.5:2584
11610 msgid "I<processes 86031>"
11613 #. type: Plain text
11614 #: build/C/man5/proc.5:2587
11615 msgid "Number of forks since boot."
11619 #: build/C/man5/proc.5:2587
11621 msgid "I<procs_running 6>"
11624 #. type: Plain text
11625 #: build/C/man5/proc.5:2591
11626 msgid "Number of processes in runnable state. (Linux 2.5.45 onward.)"
11630 #: build/C/man5/proc.5:2591
11632 msgid "I<procs_blocked 2>"
11635 #. type: Plain text
11636 #: build/C/man5/proc.5:2595
11638 "Number of processes blocked waiting for I/O to complete. (Linux 2.5.45 "
11643 #: build/C/man5/proc.5:2596
11645 msgid "I</proc/swaps>"
11648 #. type: Plain text
11649 #: build/C/man5/proc.5:2601
11650 msgid "Swap areas in use. See also B<swapon>(8)."
11654 #: build/C/man5/proc.5:2601
11656 msgid "I</proc/sys>"
11659 #. type: Plain text
11660 #: build/C/man5/proc.5:2609
11662 "This directory (present since 1.3.57) contains a number of files and "
11663 "subdirectories corresponding to kernel variables. These variables can be "
11664 "read and sometimes modified using the I</proc> filesystem, and the "
11665 "(deprecated) B<sysctl>(2) system call."
11669 #: build/C/man5/proc.5:2609
11671 msgid "I</proc/sys/abi> (since Linux 2.4.10)"
11674 #. On some systems, it is not present.
11675 #. type: Plain text
11676 #: build/C/man5/proc.5:2616
11678 "This directory may contain files with application binary information. See "
11679 "the Linux kernel source file I<Documentation/sysctl/abi.txt> for more "
11684 #: build/C/man5/proc.5:2616
11686 msgid "I</proc/sys/debug>"
11689 #. type: Plain text
11690 #: build/C/man5/proc.5:2619 build/C/man5/proc.5:3475
11691 msgid "This directory may be empty."
11695 #: build/C/man5/proc.5:2619
11697 msgid "I</proc/sys/dev>"
11700 #. type: Plain text
11701 #: build/C/man5/proc.5:2625
11703 "This directory contains device-specific information (e.g., "
11704 "I<dev/cdrom/info>). On some systems, it may be empty."
11708 #: build/C/man5/proc.5:2625
11710 msgid "I</proc/sys/fs>"
11713 #. type: Plain text
11714 #: build/C/man5/proc.5:2629
11716 "This directory contains the files and subdirectories for kernel variables "
11717 "related to filesystems."
11721 #: build/C/man5/proc.5:2629
11723 msgid "I</proc/sys/fs/binfmt_misc>"
11726 #. type: Plain text
11727 #: build/C/man5/proc.5:2634
11729 "Documentation for files in this directory can be found in the Linux kernel "
11730 "sources in I<Documentation/binfmt_misc.txt>."
11734 #: build/C/man5/proc.5:2634
11736 msgid "I</proc/sys/fs/dentry-state> (since Linux 2.2)"
11739 #. type: Plain text
11740 #: build/C/man5/proc.5:2642
11742 "This file contains information about the status of the directory cache "
11743 "(dcache). The file contains six numbers, I<nr_dentry>, I<nr_unused>, "
11744 "I<age_limit> (age in seconds), I<want_pages> (pages requested by system) and "
11745 "two dummy values."
11748 #. type: Plain text
11749 #: build/C/man5/proc.5:2647
11751 "I<nr_dentry> is the number of allocated dentries (dcache entries). This "
11752 "field is unused in Linux 2.2."
11755 #. type: Plain text
11756 #: build/C/man5/proc.5:2650
11757 msgid "I<nr_unused> is the number of unused dentries."
11760 #. looks like this is unused in kernels 2.2 to 2.6
11761 #. type: Plain text
11762 #: build/C/man5/proc.5:2655
11764 "I<age_limit> is the age in seconds after which dcache entries can be "
11765 "reclaimed when memory is short."
11768 #. looks like this is unused in kernels 2.2 to 2.6
11769 #. type: Plain text
11770 #: build/C/man5/proc.5:2660
11772 "I<want_pages> is nonzero when the kernel has called shrink_dcache_pages() "
11773 "and the dcache isn't pruned yet."
11777 #: build/C/man5/proc.5:2661
11779 msgid "I</proc/sys/fs/dir-notify-enable>"
11782 #. type: Plain text
11783 #: build/C/man5/proc.5:2670
11785 "This file can be used to disable or enable the I<dnotify> interface "
11786 "described in B<fcntl>(2) on a system-wide basis. A value of 0 in this file "
11787 "disables the interface, and a value of 1 enables it."
11791 #: build/C/man5/proc.5:2670
11793 msgid "I</proc/sys/fs/dquot-max>"
11796 #. type: Plain text
11797 #: build/C/man5/proc.5:2677
11799 "This file shows the maximum number of cached disk quota entries. On some "
11800 "(2.4) systems, it is not present. If the number of free cached disk quota "
11801 "entries is very low and you have some awesome number of simultaneous system "
11802 "users, you might want to raise the limit."
11806 #: build/C/man5/proc.5:2677
11808 msgid "I</proc/sys/fs/dquot-nr>"
11811 #. type: Plain text
11812 #: build/C/man5/proc.5:2681
11814 "This file shows the number of allocated disk quota entries and the number of "
11815 "free disk quota entries."
11819 #: build/C/man5/proc.5:2681
11821 msgid "I</proc/sys/fs/epoll> (since Linux 2.6.28)"
11824 #. type: Plain text
11825 #: build/C/man5/proc.5:2690
11827 "This directory contains the file I<max_user_watches>, which can be used to "
11828 "limit the amount of kernel memory consumed by the I<epoll> interface. For "
11829 "further details, see B<epoll>(7)."
11833 #: build/C/man5/proc.5:2690
11835 msgid "I</proc/sys/fs/file-max>"
11838 #. type: Plain text
11839 #: build/C/man5/proc.5:2703
11841 "This file defines a system-wide limit on the number of open files for all "
11842 "processes. (See also B<setrlimit>(2), which can be used by a process to set "
11843 "the per-process limit, B<RLIMIT_NOFILE>, on the number of files it may "
11844 "open.) If you get lots of error messages in the kernel log about running "
11845 "out of file handles (look for \"VFS: file-max limit E<lt>numberE<gt> "
11846 "reached\"), try increasing this value:"
11849 #. type: Plain text
11850 #: build/C/man5/proc.5:2709
11852 msgid "CW< echo 100000 E<gt> /proc/sys/fs/file-max>\n"
11855 #. type: Plain text
11856 #: build/C/man5/proc.5:2716
11858 "The kernel constant B<NR_OPEN> imposes an upper limit on the value that may "
11859 "be placed in I<file-max>."
11862 #. type: Plain text
11863 #: build/C/man5/proc.5:2722
11864 msgid "Privileged processes (B<CAP_SYS_ADMIN>) can override the I<file-max> limit."
11868 #: build/C/man5/proc.5:2722
11870 msgid "I</proc/sys/fs/file-nr>"
11873 #. type: Plain text
11874 #: build/C/man5/proc.5:2741
11876 "This (read-only) file contains three numbers: the number of allocated file "
11877 "handles (i.e., the number of files presently opened); the number of free "
11878 "file handles; and the maximum number of file handles (i.e., the same value "
11879 "as I</proc/sys/fs/file-max>). If the number of allocated file handles is "
11880 "close to the maximum, you should consider increasing the maximum. Before "
11881 "Linux 2.6, the kernel allocated file handles dynamically, but it didn't free "
11882 "them again. Instead the free file handles were kept in a list for "
11883 "reallocation; the \"free file handles\" value indicates the size of that "
11884 "list. A large number of free file handles indicates that there was a past "
11885 "peak in the usage of open file handles. Since Linux 2.6, the kernel does "
11886 "deallocate freed file handles, and the \"free file handles\" value is always "
11891 #: build/C/man5/proc.5:2741
11893 msgid "I</proc/sys/fs/inode-max> (only present until Linux 2.2)"
11896 #. type: Plain text
11897 #: build/C/man5/proc.5:2750
11899 "This file contains the maximum number of in-memory inodes. This value "
11900 "should be 3-4 times larger than the value in I<file-max>, since I<stdin>, "
11901 "I<stdout> and network sockets also need an inode to handle them. When you "
11902 "regularly run out of inodes, you need to increase this value."
11905 #. type: Plain text
11906 #: build/C/man5/proc.5:2754
11908 "Starting with Linux 2.4, there is no longer a static limit on the number of "
11909 "inodes, and this file is removed."
11913 #: build/C/man5/proc.5:2754
11915 msgid "I</proc/sys/fs/inode-nr>"
11918 #. type: Plain text
11919 #: build/C/man5/proc.5:2758
11920 msgid "This file contains the first two values from I<inode-state>."
11924 #: build/C/man5/proc.5:2758
11926 msgid "I</proc/sys/fs/inode-state>"
11929 #. type: Plain text
11930 #: build/C/man5/proc.5:2766
11932 "This file contains seven numbers: I<nr_inodes>, I<nr_free_inodes>, "
11933 "I<preshrink>, and four dummy values (always zero)."
11936 #. This can be slightly more than
11938 #. because Linux allocates them one page full at a time.
11939 #. type: Plain text
11940 #: build/C/man5/proc.5:2774
11942 "I<nr_inodes> is the number of inodes the system has allocated. "
11943 "I<nr_free_inodes> represents the number of free inodes."
11946 #. type: Plain text
11947 #: build/C/man5/proc.5:2782
11949 "I<preshrink> is nonzero when the I<nr_inodes> E<gt> I<inode-max> and the "
11950 "system needs to prune the inode list instead of allocating more; since Linux "
11951 "2.4, this field is a dummy value (always zero)."
11955 #: build/C/man5/proc.5:2782
11957 msgid "I</proc/sys/fs/inotify> (since Linux 2.6.13)"
11960 #. type: Plain text
11961 #: build/C/man5/proc.5:2791
11963 "This directory contains files I<max_queued_events>, I<max_user_instances>, "
11964 "and I<max_user_watches>, that can be used to limit the amount of kernel "
11965 "memory consumed by the I<inotify> interface. For further details, see "
11970 #: build/C/man5/proc.5:2791
11972 msgid "I</proc/sys/fs/lease-break-time>"
11975 #. type: Plain text
11976 #: build/C/man5/proc.5:2800
11978 "This file specifies the grace period that the kernel grants to a process "
11979 "holding a file lease (B<fcntl>(2)) after it has sent a signal to that "
11980 "process notifying it that another process is waiting to open the file. If "
11981 "the lease holder does not remove or downgrade the lease within this grace "
11982 "period, the kernel forcibly breaks the lease."
11986 #: build/C/man5/proc.5:2800
11988 msgid "I</proc/sys/fs/leases-enable>"
11991 #. type: Plain text
11992 #: build/C/man5/proc.5:2807
11994 "This file can be used to enable or disable file leases (B<fcntl>(2)) on a "
11995 "system-wide basis. If this file contains the value 0, leases are disabled. "
11996 "A nonzero value enables leases."
12000 #: build/C/man5/proc.5:2807
12002 msgid "I</proc/sys/fs/mqueue> (since Linux 2.6.6)"
12005 #. type: Plain text
12006 #: build/C/man5/proc.5:2815
12008 "This directory contains files I<msg_max>, I<msgsize_max>, and I<queues_max>, "
12009 "controlling the resources used by POSIX message queues. See "
12010 "B<mq_overview>(7) for details."
12014 #: build/C/man5/proc.5:2815
12016 msgid "I</proc/sys/fs/overflowgid> and I</proc/sys/fs/overflowuid>"
12019 #. type: Plain text
12020 #: build/C/man5/proc.5:2825
12022 "These files allow you to change the value of the fixed UID and GID. The "
12023 "default is 65534. Some filesystems support only 16-bit UIDs and GIDs, "
12024 "although in Linux UIDs and GIDs are 32 bits. When one of these filesystems "
12025 "is mounted with writes enabled, any UID or GID that would exceed 65535 is "
12026 "translated to the overflow value before being written to disk."
12030 #: build/C/man5/proc.5:2825
12032 msgid "I</proc/sys/fs/pipe-max-size> (since Linux 2.6.35)"
12035 #. type: Plain text
12036 #: build/C/man5/proc.5:2839
12038 "The value in this file defines an upper limit for raising the capacity of a "
12039 "pipe using the B<fcntl>(2) B<F_SETPIPE_SZ> operation. This limit applies "
12040 "only to unprivileged processes. The default value for this file is "
12041 "1,048,576. The value assigned to this file may be rounded upward, to "
12042 "reflect the value actually employed for a convenient implementation. To "
12043 "determine the rounded-up value, display the contents of this file after "
12044 "assigning a value to it. The minimum value that can be assigned to this "
12045 "file is the system page size."
12049 #: build/C/man5/proc.5:2839
12051 msgid "I</proc/sys/fs/protected_hardlinks> (since Linux 3.6)"
12054 #. commit 800179c9b8a1e796e441674776d11cd4c05d61d7
12055 #. type: Plain text
12056 #: build/C/man5/proc.5:2848
12058 "When the value in this file is 0, no restrictions are placed on the creation "
12059 "of hard links (i.e., this is the historical behaviour before Linux 3.6). "
12060 "When the value in this file is 1, a hard link can be created to a target "
12061 "file only if one of the following conditions is true:"
12064 #. type: Plain text
12065 #: build/C/man5/proc.5:2853
12066 msgid "The caller has the B<CAP_FOWNER> capability."
12069 #. type: Plain text
12070 #: build/C/man5/proc.5:2859
12072 "The filesystem UID of the process creating the link matches the owner (UID) "
12073 "of the target file (as described in B<credentials>(7), a process's "
12074 "filesystem UID is normally the same as its effective UID)."
12077 #. type: Plain text
12078 #: build/C/man5/proc.5:2861
12079 msgid "All of the following conditions are true:"
12082 #. type: Plain text
12083 #: build/C/man5/proc.5:2864
12084 msgid "the target is a regular file;"
12087 #. type: Plain text
12088 #: build/C/man5/proc.5:2866
12089 msgid "the target file does not have its set-user-ID permission bit enabled;"
12092 #. type: Plain text
12093 #: build/C/man5/proc.5:2869
12095 "the target file does not have both its set-group-ID and group-executable "
12096 "permission bits enabled; and"
12099 #. type: Plain text
12100 #: build/C/man5/proc.5:2873
12102 "the caller has permission to read and write the target file (either via the "
12103 "file's permissions mask or because it has suitable capabilities)."
12106 #. type: Plain text
12107 #: build/C/man5/proc.5:2889
12109 "The default value in this file is 0. Setting the value to 1 prevents a "
12110 "longstanding class of security issues caused by hard-link-based "
12111 "time-of-check, time-of-use races, most commonly seen in world-writable "
12112 "directories such as I</tmp>. The common method of exploiting this flaw is "
12113 "to cross privilege boundaries when following a given hard link (i.e., a root "
12114 "process follows a hard link created by another user). Additionally, on "
12115 "systems without separated partitions, this stops unauthorized users from "
12116 "\"pinning\" vulnerable set-user-ID and set-group-ID files against being "
12117 "upgraded by the administrator, or linking to special files."
12121 #: build/C/man5/proc.5:2889
12123 msgid "I</proc/sys/fs/protected_symlinks> (since Linux 3.6)"
12126 #. commit 800179c9b8a1e796e441674776d11cd4c05d61d7
12127 #. type: Plain text
12128 #: build/C/man5/proc.5:2897
12130 "When the value in this file is 0, no restrictions are placed on following "
12131 "symbolic links (i.e., this is the historical behaviour before Linux 3.6). "
12132 "When the value in this file is 1, symbolic links are followed only in the "
12133 "following circumstances:"
12136 #. type: Plain text
12137 #: build/C/man5/proc.5:2904
12139 "the filesystem UID of the process following the link matches the owner (UID) "
12140 "of the symbolic link (as described in B<credentials>(7), a process's "
12141 "filesystem UID is normally the same as its effective UID);"
12144 #. type: Plain text
12145 #: build/C/man5/proc.5:2906
12146 msgid "the link is not in a sticky world-writable directory; or"
12149 #. type: Plain text
12150 #: build/C/man5/proc.5:2908
12151 msgid "the symbolic link and its parent directory have the same owner (UID)"
12154 #. type: Plain text
12155 #: build/C/man5/proc.5:2915
12157 "A system call that fails to follow a symbolic link because of the above "
12158 "restrictions returns the error B<EACCES> in I<errno>."
12161 #. type: Plain text
12162 #: build/C/man5/proc.5:2919
12164 "The default value in this file is 0. Setting the value to 1 avoids a "
12165 "longstanding class of security issues based on time-of-check, time-of-use "
12166 "races when accessing symbolic links."
12170 #: build/C/man5/proc.5:2919
12172 msgid "I</proc/sys/fs/suid_dumpable> (since Linux 2.6.13)"
12175 #. The following is based on text from Documentation/sysctl/kernel.txt
12176 #. type: Plain text
12177 #: build/C/man5/proc.5:2925
12179 "The value in this file determines whether core dump files are produced for "
12180 "set-user-ID or otherwise protected/tainted binaries. Three different "
12181 "integer values can be specified:"
12185 #: build/C/man5/proc.5:2926
12187 msgid "I<0\\ (default)>"
12190 #. type: Plain text
12191 #: build/C/man5/proc.5:2935
12193 "This provides the traditional (pre-Linux 2.6.13) behavior. A core dump will "
12194 "not be produced for a process which has changed credentials (by calling "
12195 "B<seteuid>(2), B<setgid>(2), or similar, or by executing a set-user-ID or "
12196 "set-group-ID program) or whose binary does not have read permission "
12201 #: build/C/man5/proc.5:2935
12203 msgid "I<1\\ (\"debug\")>"
12206 #. type: Plain text
12207 #: build/C/man5/proc.5:2942
12209 "All processes dump core when possible. The core dump is owned by the "
12210 "filesystem user ID of the dumping process and no security is applied. This "
12211 "is intended for system debugging situations only. Ptrace is unchecked."
12215 #: build/C/man5/proc.5:2942
12217 msgid "I<2\\ (\"suidsafe\")>"
12220 #. type: Plain text
12221 #: build/C/man5/proc.5:2951
12223 "Any binary which normally would not be dumped (see \"0\" above) is dumped "
12224 "readable by root only. This allows the user to remove the core dump file "
12225 "but not to read it. For security reasons core dumps in this mode will not "
12226 "overwrite one another or other files. This mode is appropriate when "
12227 "administrators are attempting to debug problems in a normal environment."
12230 #. 9520628e8ceb69fa9a4aee6b57f22675d9e1b709
12231 #. 54b501992dd2a839e94e76aa392c392b55080ce8
12232 #. type: Plain text
12233 #: build/C/man5/proc.5:2962
12235 "Additionally, since Linux 3.6, I</proc/sys/kernel/core_pattern> must either "
12236 "be an absolute pathname or a pipe command, as detailed in B<core>(5). "
12237 "Warnings will be written to the kernel log if I<core_pattern> does not "
12238 "follow these rules, and no core dump will be produced."
12242 #: build/C/man5/proc.5:2963
12244 msgid "I</proc/sys/fs/super-max>"
12247 #. type: Plain text
12248 #: build/C/man5/proc.5:2974
12250 "This file controls the maximum number of superblocks, and thus the maximum "
12251 "number of mounted filesystems the kernel can have. You need increase only "
12252 "I<super-max> if you need to mount more filesystems than the current value in "
12253 "I<super-max> allows you to."
12257 #: build/C/man5/proc.5:2974
12259 msgid "I</proc/sys/fs/super-nr>"
12262 #. type: Plain text
12263 #: build/C/man5/proc.5:2978
12264 msgid "This file contains the number of filesystems currently mounted."
12268 #: build/C/man5/proc.5:2978
12270 msgid "I</proc/sys/kernel>"
12273 #. type: Plain text
12274 #: build/C/man5/proc.5:2982
12276 "This directory contains files controlling a range of kernel parameters, as "
12281 #: build/C/man5/proc.5:2982
12283 msgid "I</proc/sys/kernel/acct>"
12286 #. type: Plain text
12287 #: build/C/man5/proc.5:3006
12289 "This file contains three numbers: I<highwater>, I<lowwater>, and "
12290 "I<frequency>. If BSD-style process accounting is enabled, these values "
12291 "control its behavior. If free space on filesystem where the log lives goes "
12292 "below I<lowwater> percent, accounting suspends. If free space gets above "
12293 "I<highwater> percent, accounting resumes. I<frequency> determines how often "
12294 "the kernel checks the amount of free space (value is in seconds). Default "
12295 "values are 4, 2 and 30. That is, suspend accounting if 2% or less space is "
12296 "free; resume it if 4% or more space is free; consider information about "
12297 "amount of free space valid for 30 seconds."
12301 #: build/C/man5/proc.5:3006
12303 msgid "I</proc/sys/kernel/cap_last_cap> (since Linux 3.2)"
12306 #. type: Plain text
12307 #: build/C/man5/proc.5:3010
12308 msgid "See B<capabilities>(7)."
12312 #: build/C/man5/proc.5:3010
12314 msgid "I</proc/sys/kernel/cap-bound> (from Linux 2.2 to 2.6.24)"
12317 #. type: Plain text
12318 #: build/C/man5/proc.5:3022
12320 "This file holds the value of the kernel I<capability bounding set> "
12321 "(expressed as a signed decimal number). This set is ANDed against the "
12322 "capabilities permitted to a process during B<execve>(2). Starting with "
12323 "Linux 2.6.25, the system-wide capability bounding set disappeared, and was "
12324 "replaced by a per-thread bounding set; see B<capabilities>(7)."
12328 #: build/C/man5/proc.5:3022
12330 msgid "I</proc/sys/kernel/core_pattern>"
12334 #: build/C/man5/proc.5:3026
12336 msgid "I</proc/sys/kernel/core_uses_pid>"
12340 #: build/C/man5/proc.5:3030
12342 msgid "I</proc/sys/kernel/ctrl-alt-del>"
12345 #. type: Plain text
12346 #: build/C/man5/proc.5:3045
12348 "This file controls the handling of Ctrl-Alt-Del from the keyboard. When the "
12349 "value in this file is 0, Ctrl-Alt-Del is trapped and sent to the B<init>(8) "
12350 "program to handle a graceful restart. When the value is greater than zero, "
12351 "Linux's reaction to a Vulcan Nerve Pinch (tm) will be an immediate reboot, "
12352 "without even syncing its dirty buffers. Note: when a program (like dosemu) "
12353 "has the keyboard in \"raw\" mode, the ctrl-alt-del is intercepted by the "
12354 "program before it ever reaches the kernel tty layer, and it's up to the "
12355 "program to decide what to do with it."
12359 #: build/C/man5/proc.5:3045
12361 msgid "I</proc/sys/kernel/dmesg_restrict> (since Linux 2.6.37)"
12364 #. commit 620f6e8e855d6d447688a5f67a4e176944a084e8
12365 #. type: Plain text
12366 #: build/C/man5/proc.5:3058
12368 "The value in this file determines who can see kernel syslog contents. A "
12369 "value of 0 in this file imposes no restrictions. If the value is 1, only "
12370 "privileged users can read the kernel syslog. (See B<syslog>(2) for more "
12371 "details.) Since Linux 3.4, only users with the B<CAP_SYS_ADMIN> capability "
12372 "may change the value in this file."
12376 #: build/C/man5/proc.5:3058
12378 msgid "I</proc/sys/kernel/domainname> and I</proc/sys/kernel/hostname>"
12381 #. type: Plain text
12382 #: build/C/man5/proc.5:3066
12384 "can be used to set the NIS/YP domainname and the hostname of your box in "
12385 "exactly the same way as the commands B<domainname>(1) and B<hostname>(1), "
12389 #. type: Plain text
12390 #: build/C/man5/proc.5:3071
12393 "#B< echo \\(aqdarkstar\\(aq E<gt> /proc/sys/kernel/hostname>\n"
12394 "#B< echo \\(aqmydomain\\(aq E<gt> /proc/sys/kernel/domainname>\n"
12397 #. type: Plain text
12398 #: build/C/man5/proc.5:3075
12399 msgid "has the same effect as"
12402 #. type: Plain text
12403 #: build/C/man5/proc.5:3080
12406 "#B< hostname \\(aqdarkstar\\(aq>\n"
12407 "#B< domainname \\(aqmydomain\\(aq>\n"
12410 #. type: Plain text
12411 #: build/C/man5/proc.5:3093
12413 "Note, however, that the classic darkstar.frop.org has the hostname "
12414 "\"darkstar\" and DNS (Internet Domain Name Server) domainname \"frop.org\", "
12415 "not to be confused with the NIS (Network Information Service) or YP (Yellow "
12416 "Pages) domainname. These two domain names are in general different. For a "
12417 "detailed discussion see the B<hostname>(1) man page."
12421 #: build/C/man5/proc.5:3093
12423 msgid "I</proc/sys/kernel/hotplug>"
12426 #. type: Plain text
12427 #: build/C/man5/proc.5:3099
12429 "This file contains the path for the hotplug policy agent. The default value "
12430 "in this file is I</sbin/hotplug>."
12434 #: build/C/man5/proc.5:3099
12436 msgid "I</proc/sys/kernel/htab-reclaim>"
12439 #. type: Plain text
12440 #: build/C/man5/proc.5:3107
12442 "(PowerPC only) If this file is set to a nonzero value, the PowerPC htab (see "
12443 "kernel file I<Documentation/powerpc/ppc_htab.txt>) is pruned each time the "
12444 "system hits the idle loop."
12448 #: build/C/man5/proc.5:3107
12450 msgid "I</proc/sys/kernel/kptr_restrict> (since Linux 2.6.38)"
12453 #. 455cd5ab305c90ffc422dd2e0fb634730942b257
12454 #. commit 411f05f123cbd7f8aa1edcae86970755a6e2a9d9
12455 #. commit 620f6e8e855d6d447688a5f67a4e176944a084e8
12456 #. type: Plain text
12457 #: build/C/man5/proc.5:3132
12459 "The value in this file determines whether kernel addresses are exposed via "
12460 "I</proc> files and other interfaces. A value of 0 in this file imposes no "
12461 "restrictions. If the value is 1, kernel pointers printed using the I<%pK> "
12462 "format specifier will be replaced with zeros unless the user has the "
12463 "B<CAP_SYSLOG> capability. If the value is 2, kernel pointers printed using "
12464 "the I<%pK> format specifier will be replaced with zeros regardless of the "
12465 "user's capabilities. The initial default value for this file was 1, but the "
12466 "default was changed to 0 in Linux 2.6.39. Since Linux 3.4, only users with "
12467 "the B<CAP_SYS_ADMIN> capability can change the value in this file."
12471 #: build/C/man5/proc.5:3132
12473 msgid "I</proc/sys/kernel/l2cr>"
12476 #. type: Plain text
12477 #: build/C/man5/proc.5:3139
12479 "(PowerPC only) This file contains a flag that controls the L2 cache of G3 "
12480 "processor boards. If 0, the cache is disabled. Enabled if nonzero."
12484 #: build/C/man5/proc.5:3139
12486 msgid "I</proc/sys/kernel/modprobe>"
12489 #. type: Plain text
12490 #: build/C/man5/proc.5:3152
12492 "This file contains the path for the kernel module loader. The default value "
12493 "is I</sbin/modprobe>. The file is present only if the kernel is built with "
12494 "the B<CONFIG_MODULES> (B<CONFIG_KMOD> in Linux 2.6.26 and earlier) option "
12495 "enabled. It is described by the Linux kernel source file "
12496 "I<Documentation/kmod.txt> (present only in kernel 2.4 and earlier)."
12500 #: build/C/man5/proc.5:3152
12502 msgid "I</proc/sys/kernel/modules_disabled> (since Linux 2.6.31)"
12505 #. 3d43321b7015387cfebbe26436d0e9d299162ea1
12506 #. From Documentation/sysctl/kernel.txt
12507 #. type: Plain text
12508 #: build/C/man5/proc.5:3164
12510 "A toggle value indicating if modules are allowed to be loaded in an "
12511 "otherwise modular kernel. This toggle defaults to off (0), but can be set "
12512 "true (1). Once true, modules can be neither loaded nor unloaded, and the "
12513 "toggle cannot be set back to false. The file is present only if the kernel "
12514 "is built with the B<CONFIG_MODULES> option enabled."
12518 #: build/C/man5/proc.5:3164
12520 msgid "I</proc/sys/kernel/msgmax> (since Linux 2.2)"
12523 #. type: Plain text
12524 #: build/C/man5/proc.5:3169
12526 "This file defines a system-wide limit specifying the maximum number of bytes "
12527 "in a single message written on a System V message queue."
12531 #: build/C/man5/proc.5:3169
12533 msgid "I</proc/sys/kernel/msgmni> (since Linux 2.4)"
12536 #. type: Plain text
12537 #: build/C/man5/proc.5:3173
12539 "This file defines the system-wide limit on the number of message queue "
12544 #: build/C/man5/proc.5:3173
12546 msgid "I</proc/sys/kernel/msgmnb> (since Linux 2.2)"
12549 #. type: Plain text
12550 #: build/C/man5/proc.5:3182
12552 "This file defines a system-wide parameter used to initialize the "
12553 "I<msg_qbytes> setting for subsequently created message queues. The "
12554 "I<msg_qbytes> setting specifies the maximum number of bytes that may be "
12555 "written to the message queue."
12559 #: build/C/man5/proc.5:3182
12561 msgid "I</proc/sys/kernel/ngroups_max> (since Linux 2.6.4)"
12564 #. type: Plain text
12565 #: build/C/man5/proc.5:3186
12567 "This is a read-only file that displays the upper limit on the number of a "
12568 "process's group memberships."
12572 #: build/C/man5/proc.5:3186
12574 msgid "I</proc/sys/kernel/ostype> and I</proc/sys/kernel/osrelease>"
12577 #. type: Plain text
12578 #: build/C/man5/proc.5:3191
12579 msgid "These files give substrings of I</proc/version>."
12583 #: build/C/man5/proc.5:3191
12585 msgid "I</proc/sys/kernel/overflowgid> and I</proc/sys/kernel/overflowuid>"
12588 #. type: Plain text
12589 #: build/C/man5/proc.5:3197
12591 "These files duplicate the files I</proc/sys/fs/overflowgid> and "
12592 "I</proc/sys/fs/overflowuid>."
12596 #: build/C/man5/proc.5:3197
12598 msgid "I</proc/sys/kernel/panic>"
12601 #. type: Plain text
12602 #: build/C/man5/proc.5:3206
12604 "This file gives read/write access to the kernel variable I<panic_timeout>. "
12605 "If this is zero, the kernel will loop on a panic; if nonzero, it indicates "
12606 "that the kernel should autoreboot after this number of seconds. When you "
12607 "use the software watchdog device driver, the recommended setting is 60."
12611 #: build/C/man5/proc.5:3206
12613 msgid "I</proc/sys/kernel/panic_on_oops> (since Linux 2.5.68)"
12616 #. type: Plain text
12617 #: build/C/man5/proc.5:3218
12619 "This file controls the kernel's behavior when an oops or BUG is "
12620 "encountered. If this file contains 0, then the system tries to continue "
12621 "operation. If it contains 1, then the system delays a few seconds (to give "
12622 "klogd time to record the oops output) and then panics. If the "
12623 "I</proc/sys/kernel/panic> file is also nonzero, then the machine will be "
12628 #: build/C/man5/proc.5:3218
12630 msgid "I</proc/sys/kernel/pid_max> (since Linux 2.5.34)"
12633 #. Prior to 2.6.10, pid_max could also be raised above 32768 on 32-bit
12634 #. platforms, but this broke /proc/[pid]
12635 #. See http://marc.theaimsgroup.com/?l=linux-kernel&m=109513010926152&w=2
12636 #. type: Plain text
12637 #: build/C/man5/proc.5:3237
12639 "This file specifies the value at which PIDs wrap around (i.e., the value in "
12640 "this file is one greater than the maximum PID). PIDs greater than this "
12641 "value not allocated; thus, the value in this file also acts as a system-wide "
12642 "limit on the total number of processes and threads. The default value for "
12643 "this file, 32768, results in the same range of PIDs as on earlier kernels. "
12644 "On 32-bit platforms, 32768 is the maximum value for I<pid_max>. On 64-bit "
12645 "systems, I<pid_max> can be set to any value up to 2^22 (B<PID_MAX_LIMIT>, "
12646 "approximately 4 million)."
12650 #: build/C/man5/proc.5:3237
12652 msgid "I</proc/sys/kernel/powersave-nap> (PowerPC only)"
12655 #. type: Plain text
12656 #: build/C/man5/proc.5:3243
12658 "This file contains a flag. If set, Linux-PPC will use the \"nap\" mode of "
12659 "powersaving, otherwise the \"doze\" mode will be used."
12663 #: build/C/man5/proc.5:3243
12665 msgid "I</proc/sys/kernel/printk>"
12668 #. type: Plain text
12669 #: build/C/man5/proc.5:3269
12671 "The four values in this file are I<console_loglevel>, "
12672 "I<default_message_loglevel>, I<minimum_console_level>, and "
12673 "I<default_console_loglevel>. These values influence I<printk()> behavior "
12674 "when printing or logging error messages. See B<syslog>(2) for more info on "
12675 "the different loglevels. Messages with a higher priority than "
12676 "I<console_loglevel> will be printed to the console. Messages without an "
12677 "explicit priority will be printed with priority I<default_message_level>. "
12678 "I<minimum_console_loglevel> is the minimum (highest) value to which "
12679 "I<console_loglevel> can be set. I<default_console_loglevel> is the default "
12680 "value for I<console_loglevel>."
12684 #: build/C/man5/proc.5:3269
12686 msgid "I</proc/sys/kernel/pty> (since Linux 2.6.4)"
12689 #. type: Plain text
12690 #: build/C/man5/proc.5:3275
12692 "This directory contains two files relating to the number of UNIX 98 "
12693 "pseudoterminals (see B<pts>(4)) on the system."
12697 #: build/C/man5/proc.5:3275
12699 msgid "I</proc/sys/kernel/pty/max>"
12702 #. type: Plain text
12703 #: build/C/man5/proc.5:3278
12704 msgid "This file defines the maximum number of pseudoterminals."
12708 #: build/C/man5/proc.5:3278
12710 msgid "I</proc/sys/kernel/pty/nr>"
12713 #. type: Plain text
12714 #: build/C/man5/proc.5:3282
12715 msgid "This read-only file indicates how many pseudoterminals are currently in use."
12719 #: build/C/man5/proc.5:3282
12721 msgid "I</proc/sys/kernel/random>"
12724 #. type: Plain text
12725 #: build/C/man5/proc.5:3290
12727 "This directory contains various parameters controlling the operation of the "
12728 "file I</dev/random>. See B<random>(4) for further information."
12732 #: build/C/man5/proc.5:3290
12734 msgid "I</proc/sys/kernel/random/uuid> (since Linux 2.4)"
12737 #. type: Plain text
12738 #: build/C/man5/proc.5:3294
12740 "Each read from this read-only file returns a randomly generated 128-bit "
12741 "UUID, as a string in the standard UUID format."
12745 #: build/C/man5/proc.5:3294
12747 msgid "I</proc/sys/kernel/real-root-dev>"
12750 #. type: Plain text
12751 #: build/C/man5/proc.5:3298
12753 "This file is documented in the Linux kernel source file "
12754 "I<Documentation/initrd.txt>."
12758 #: build/C/man5/proc.5:3298
12760 msgid "I</proc/sys/kernel/reboot-cmd> (Sparc only) "
12763 #. type: Plain text
12764 #: build/C/man5/proc.5:3304
12766 "This file seems to be a way to give an argument to the SPARC ROM/Flash boot "
12767 "loader. Maybe to tell it what to do after rebooting?"
12771 #: build/C/man5/proc.5:3304
12773 msgid "I</proc/sys/kernel/rtsig-max>"
12776 #. type: Plain text
12777 #: build/C/man5/proc.5:3311
12779 "(Only in kernels up to and including 2.6.7; see B<setrlimit>(2)) This file "
12780 "can be used to tune the maximum number of POSIX real-time (queued) signals "
12781 "that can be outstanding in the system."
12785 #: build/C/man5/proc.5:3311
12787 msgid "I</proc/sys/kernel/rtsig-nr>"
12790 #. type: Plain text
12791 #: build/C/man5/proc.5:3315
12793 "(Only in kernels up to and including 2.6.7.) This file shows the number "
12794 "POSIX real-time signals currently queued."
12798 #: build/C/man5/proc.5:3315
12800 msgid "I</proc/sys/kernel/sched_rr_timeslice_ms> (since Linux 3.9)"
12803 #. type: Plain text
12804 #: build/C/man5/proc.5:3319
12805 msgid "See B<sched_rr_get_interval>(2)."
12809 #: build/C/man5/proc.5:3319
12811 msgid "I</proc/sys/kernel/sched_rt_period_us> (Since Linux 2.6.25)"
12814 #. type: Plain text
12815 #: build/C/man5/proc.5:3323 build/C/man5/proc.5:3327
12816 msgid "See B<sched>(7)."
12820 #: build/C/man5/proc.5:3323
12822 msgid "I</proc/sys/kernel/sched_rt_runtime_us> (Since Linux 2.6.25)"
12826 #: build/C/man5/proc.5:3327
12828 msgid "I</proc/sys/kernel/sem> (since Linux 2.4)"
12831 #. type: Plain text
12832 #: build/C/man5/proc.5:3331
12834 "This file contains 4 numbers defining limits for System V IPC semaphores. "
12835 "These fields are, in order:"
12839 #: build/C/man5/proc.5:3332
12844 #. type: Plain text
12845 #: build/C/man5/proc.5:3334
12846 msgid "The maximum semaphores per semaphore set."
12850 #: build/C/man5/proc.5:3334
12855 #. type: Plain text
12856 #: build/C/man5/proc.5:3336
12857 msgid "A system-wide limit on the number of semaphores in all semaphore sets."
12861 #: build/C/man5/proc.5:3336
12866 #. type: Plain text
12867 #: build/C/man5/proc.5:3340
12869 "The maximum number of operations that may be specified in a B<semop>(2) "
12874 #: build/C/man5/proc.5:3340
12879 #. type: Plain text
12880 #: build/C/man5/proc.5:3342
12881 msgid "A system-wide limit on the maximum number of semaphore identifiers."
12885 #: build/C/man5/proc.5:3343
12887 msgid "I</proc/sys/kernel/sg-big-buff>"
12890 #. type: Plain text
12891 #: build/C/man5/proc.5:3354
12893 "This file shows the size of the generic SCSI device (sg) buffer. You can't "
12894 "tune it just yet, but you could change it at compile time by editing "
12895 "I<include/scsi/sg.h> and changing the value of B<SG_BIG_BUFF>. However, "
12896 "there shouldn't be any reason to change this value."
12900 #: build/C/man5/proc.5:3354
12902 msgid "I</proc/sys/kernel/shm_rmid_forced> (since Linux 3.1)"
12905 #. commit b34a6b1da371ed8af1221459a18c67970f7e3d53
12906 #. See also Documentation/sysctl/kernel.txt
12907 #. type: Plain text
12908 #: build/C/man5/proc.5:3363
12910 "If this file is set to 1, all System V shared memory segments will be marked "
12911 "for destruction as soon as the number of attached processes falls to zero; "
12912 "in other words, it is no longer possible to create shared memory segments "
12913 "that exist independently of any attached process."
12916 #. type: Plain text
12917 #: build/C/man5/proc.5:3375
12919 "The effect is as though a B<shmctl>(2) B<IPC_RMID> is performed on all "
12920 "existing segments as well as all segments created in the future (until this "
12921 "file is reset to 0). Note that existing segments that are attached to no "
12922 "process will be immediately destroyed when this file is set to 1. Setting "
12923 "this option will also destroy segments that were created, but never "
12924 "attached, upon termination of the process that created the segment with "
12928 #. type: Plain text
12929 #: build/C/man5/proc.5:3383
12931 "Setting this file to 1 provides a way of ensuring that all System V shared "
12932 "memory segments are counted against the resource usage and resource limits "
12933 "(see the description of B<RLIMIT_AS> in B<getrlimit>(2)) of at least one "
12937 #. type: Plain text
12938 #: build/C/man5/proc.5:3390
12940 "Because setting this file to 1 produces behavior that is nonstandard and "
12941 "could also break existing applications, the default value in this file is "
12942 "0. Only set this file to 1 if you have a good understanding of the "
12943 "semantics of the applications using System V shared memory on your system."
12947 #: build/C/man5/proc.5:3390
12949 msgid "I</proc/sys/kernel/shmall> (since Linux 2.2)"
12952 #. type: Plain text
12953 #: build/C/man5/proc.5:3395
12955 "This file contains the system-wide limit on the total number of pages of "
12956 "System V shared memory."
12960 #: build/C/man5/proc.5:3395
12962 msgid "I</proc/sys/kernel/shmmax> (since Linux 2.2)"
12965 #. type: Plain text
12966 #: build/C/man5/proc.5:3405
12968 "This file can be used to query and set the run-time limit on the maximum "
12969 "(System V IPC) shared memory segment size that can be created. Shared "
12970 "memory segments up to 1GB are now supported in the kernel. This value "
12971 "defaults to B<SHMMAX>."
12975 #: build/C/man5/proc.5:3405
12977 msgid "I</proc/sys/kernel/shmmni> (since Linux 2.4)"
12980 #. type: Plain text
12981 #: build/C/man5/proc.5:3410
12983 "This file specifies the system-wide maximum number of System V shared memory "
12984 "segments that can be created."
12988 #: build/C/man5/proc.5:3410
12990 msgid "I</proc/sys/kernel/sysrq>"
12993 #. type: Plain text
12994 #: build/C/man5/proc.5:3419
12996 "This file controls the functions allowed to be invoked by the SysRq key. By "
12997 "default, the file contains 1 meaning that every possible SysRq request is "
12998 "allowed (in older kernel versions, SysRq was disabled by default, and you "
12999 "were required to specifically enable it at run-time, but this is not the "
13000 "case any more). Possible values in this file are:"
13003 #. type: Plain text
13004 #: build/C/man5/proc.5:3431
13007 " 0 - disable sysrq completely\n"
13008 " 1 - enable all functions of sysrq\n"
13009 " E<gt>1 - bit mask of allowed sysrq functions, as follows:\n"
13010 " 2 - enable control of console logging level\n"
13011 " 4 - enable control of keyboard (SAK, unraw)\n"
13012 " 8 - enable debugging dumps of processes etc.\n"
13013 " 16 - enable sync command\n"
13014 " 32 - enable remount read-only\n"
13015 " 64 - enable signaling of processes (term, kill, oom-kill)\n"
13016 " 128 - allow reboot/poweroff\n"
13017 " 256 - allow nicing of all real-time tasks\n"
13020 #. type: Plain text
13021 #: build/C/man5/proc.5:3437
13023 "This file is present only if the B<CONFIG_MAGIC_SYSRQ> kernel configuration "
13024 "option is enabled. For further details see the Linux kernel source file "
13025 "I<Documentation/sysrq.txt>."
13029 #: build/C/man5/proc.5:3437
13031 msgid "I</proc/sys/kernel/version>"
13034 #. type: Plain text
13035 #: build/C/man5/proc.5:3440
13036 msgid "This file contains a string like:"
13039 #. type: Plain text
13040 #: build/C/man5/proc.5:3442
13042 msgid " #5 Wed Feb 25 21:49:24 MET 1998\n"
13045 #. type: Plain text
13046 #: build/C/man5/proc.5:3446
13048 "The \"#5\" means that this is the fifth kernel built from this source base "
13049 "and the date behind it indicates the time the kernel was built."
13053 #: build/C/man5/proc.5:3446
13055 msgid "I</proc/sys/kernel/threads-max> (since Linux 2.3.11)"
13058 #. type: Plain text
13059 #: build/C/man5/proc.5:3450
13061 "This file specifies the system-wide limit on the number of threads (tasks) "
13062 "that can be created on the system."
13066 #: build/C/man5/proc.5:3450
13068 msgid "I</proc/sys/kernel/zero-paged> (PowerPC only) "
13071 #. type: Plain text
13072 #: build/C/man5/proc.5:3456
13074 "This file contains a flag. When enabled (nonzero), Linux-PPC will pre-zero "
13075 "pages in the idle loop, possibly speeding up get_free_pages."
13079 #: build/C/man5/proc.5:3456
13081 msgid "I</proc/sys/net>"
13084 #. type: Plain text
13085 #: build/C/man5/proc.5:3463
13087 "This directory contains networking stuff. Explanations for some of the "
13088 "files under this directory can be found in B<tcp>(7) and B<ip>(7)."
13092 #: build/C/man5/proc.5:3463
13094 msgid "I</proc/sys/net/core/somaxconn>"
13097 #. type: Plain text
13098 #: build/C/man5/proc.5:3472
13100 "This file defines a ceiling value for the I<backlog> argument of "
13101 "B<listen>(2); see the B<listen>(2) manual page for details."
13105 #: build/C/man5/proc.5:3472
13107 msgid "I</proc/sys/proc>"
13111 #: build/C/man5/proc.5:3475
13113 msgid "I</proc/sys/sunrpc>"
13116 #. type: Plain text
13117 #: build/C/man5/proc.5:3480
13119 "This directory supports Sun remote procedure call for network filesystem "
13120 "(NFS). On some systems, it is not present."
13124 #: build/C/man5/proc.5:3480
13126 msgid "I</proc/sys/vm>"
13129 #. type: Plain text
13130 #: build/C/man5/proc.5:3484
13132 "This directory contains files for memory management tuning, buffer and cache "
13137 #: build/C/man5/proc.5:3484
13139 msgid "I</proc/sys/vm/drop_caches> (since Linux 2.6.16)"
13142 #. type: Plain text
13143 #: build/C/man5/proc.5:3492
13145 "Writing to this file causes the kernel to drop clean caches, dentries, and "
13146 "inodes from memory, causing that memory to become free. This can be useful "
13147 "for memory management testing and performing reproducible filesystem "
13148 "benchmarks. Because writing to this file causes the benefits of caching to "
13149 "be lost, it can degrade overall system performance."
13152 #. type: Plain text
13153 #: build/C/man5/proc.5:3494
13154 msgid "To free pagecache, use:"
13157 #. type: Plain text
13158 #: build/C/man5/proc.5:3496
13160 msgid " echo 1 E<gt> /proc/sys/vm/drop_caches\n"
13163 #. type: Plain text
13164 #: build/C/man5/proc.5:3498
13165 msgid "To free dentries and inodes, use:"
13168 #. type: Plain text
13169 #: build/C/man5/proc.5:3500
13171 msgid " echo 2 E<gt> /proc/sys/vm/drop_caches\n"
13174 #. type: Plain text
13175 #: build/C/man5/proc.5:3502
13176 msgid "To free pagecache, dentries and inodes, use:"
13179 #. type: Plain text
13180 #: build/C/man5/proc.5:3504
13182 msgid " echo 3 E<gt> /proc/sys/vm/drop_caches\n"
13185 #. type: Plain text
13186 #: build/C/man5/proc.5:3510
13188 "Because writing to this file is a nondestructive operation and dirty objects "
13189 "are not freeable, the user should run B<sync>(8) first."
13193 #: build/C/man5/proc.5:3510
13195 msgid "I</proc/sys/vm/legacy_va_layout> (since Linux 2.6.9)"
13198 #. The following is from Documentation/filesystems/proc.txt
13199 #. type: Plain text
13200 #: build/C/man5/proc.5:3515
13202 "If nonzero, this disables the new 32-bit memory-mapping layout; the kernel "
13203 "will use the legacy (2.4) layout for all processes."
13207 #: build/C/man5/proc.5:3515
13209 msgid "I</proc/sys/vm/memory_failure_early_kill> (since Linux 2.6.32)"
13212 #. The following is based on the text in Documentation/sysctl/vm.txt
13213 #. type: Plain text
13214 #: build/C/man5/proc.5:3527
13216 "Control how to kill processes when an uncorrected memory error (typically a "
13217 "2-bit error in a memory module) that cannot be handled by the kernel is "
13218 "detected in the background by hardware. In some cases (like the page still "
13219 "having a valid copy on disk), the kernel will handle the failure "
13220 "transparently without affecting any applications. But if there is no other "
13221 "up-to-date copy of the data, it will kill processes to prevent any data "
13222 "corruptions from propagating."
13225 #. type: Plain text
13226 #: build/C/man5/proc.5:3529
13227 msgid "The file has one of the following values:"
13231 #: build/C/man5/proc.5:3530 build/C/man5/proc.5:3567
13236 #. type: Plain text
13237 #: build/C/man5/proc.5:3535
13239 "Kill all processes that have the corrupted-and-not-reloadable page mapped as "
13240 "soon as the corruption is detected. Note this is not supported for a few "
13241 "types of pages, like kernel internally allocated data or the swap cache, but "
13242 "works for the majority of user pages."
13246 #: build/C/man5/proc.5:3535 build/C/man5/proc.5:3569
13251 #. type: Plain text
13252 #: build/C/man5/proc.5:3538
13254 "Only unmap the corrupted page from all processes and kill only a process "
13255 "that tries to access it."
13258 #. type: Plain text
13259 #: build/C/man5/proc.5:3549
13261 "The kill is performed using a B<SIGBUS> signal with I<si_code> set to "
13262 "B<BUS_MCEERR_AO>. Processes can handle this if they want to; see "
13263 "B<sigaction>(2) for more details."
13266 #. type: Plain text
13267 #: build/C/man5/proc.5:3552
13269 "This feature is active only on architectures/platforms with advanced machine "
13270 "check handling and depends on the hardware capabilities."
13273 #. type: Plain text
13274 #: build/C/man5/proc.5:3559
13276 "Applications can override the I<memory_failure_early_kill> setting "
13277 "individually with the B<prctl>(2) B<PR_MCE_KILL> operation."
13280 #. type: Plain text
13281 #: build/C/man5/proc.5:3562 build/C/man5/proc.5:3575
13282 msgid "Only present if the kernel was configured with B<CONFIG_MEMORY_FAILURE>."
13286 #: build/C/man5/proc.5:3562
13288 msgid "I</proc/sys/vm/memory_failure_recovery> (since Linux 2.6.32)"
13291 #. The following is based on the text in Documentation/sysctl/vm.txt
13292 #. type: Plain text
13293 #: build/C/man5/proc.5:3566
13294 msgid "Enable memory failure recovery (when supported by the platform)"
13297 #. type: Plain text
13298 #: build/C/man5/proc.5:3569
13299 msgid "Attempt recovery."
13302 #. type: Plain text
13303 #: build/C/man5/proc.5:3571
13304 msgid "Always panic on a memory failure."
13308 #: build/C/man5/proc.5:3575
13310 msgid "I</proc/sys/vm/oom_dump_tasks> (since Linux 2.6.25)"
13313 #. The following is from Documentation/sysctl/vm.txt
13314 #. type: Plain text
13315 #: build/C/man5/proc.5:3590
13317 "Enables a system-wide task dump (excluding kernel threads) to be produced "
13318 "when the kernel performs an OOM-killing. The dump includes the following "
13319 "information for each task (thread, process): thread ID, real user ID, thread "
13320 "group ID (process ID), virtual memory size, resident set size, the CPU that "
13321 "the task is scheduled on, oom_adj score (see the description of "
13322 "I</proc/[pid]/oom_adj>), and command name. This is helpful to determine why "
13323 "the OOM-killer was invoked and to identify the rogue task that caused it."
13326 #. type: Plain text
13327 #: build/C/man5/proc.5:3596
13329 "If this contains the value zero, this information is suppressed. On very "
13330 "large systems with thousands of tasks, it may not be feasible to dump the "
13331 "memory state information for each one. Such systems should not be forced to "
13332 "incur a performance penalty in OOM situations when the information may not "
13336 #. type: Plain text
13337 #: build/C/man5/proc.5:3599
13339 "If this is set to nonzero, this information is shown whenever the OOM-killer "
13340 "actually kills a memory-hogging task."
13343 #. type: Plain text
13344 #: build/C/man5/proc.5:3601 build/C/man5/proc.5:3622
13345 msgid "The default value is 0."
13349 #: build/C/man5/proc.5:3601
13351 msgid "I</proc/sys/vm/oom_kill_allocating_task> (since Linux 2.6.24)"
13354 #. The following is from Documentation/sysctl/vm.txt
13355 #. type: Plain text
13356 #: build/C/man5/proc.5:3606
13358 "This enables or disables killing the OOM-triggering task in out-of-memory "
13362 #. type: Plain text
13363 #: build/C/man5/proc.5:3611
13365 "If this is set to zero, the OOM-killer will scan through the entire tasklist "
13366 "and select a task based on heuristics to kill. This normally selects a "
13367 "rogue memory-hogging task that frees up a large amount of memory when "
13371 #. type: Plain text
13372 #: build/C/man5/proc.5:3615
13374 "If this is set to nonzero, the OOM-killer simply kills the task that "
13375 "triggered the out-of-memory condition. This avoids a possibly expensive "
13379 #. type: Plain text
13380 #: build/C/man5/proc.5:3620
13382 "If I</proc/sys/vm/panic_on_oom> is nonzero, it takes precedence over "
13383 "whatever value is used in I</proc/sys/vm/oom_kill_allocating_task>."
13387 #: build/C/man5/proc.5:3622
13389 msgid "I</proc/sys/vm/overcommit_memory>"
13392 #. type: Plain text
13393 #: build/C/man5/proc.5:3626
13394 msgid "This file contains the kernel virtual memory accounting mode. Values are:"
13397 #. type: Plain text
13398 #: build/C/man5/proc.5:3629
13399 msgid "0: heuristic overcommit (this is the default)"
13402 #. type: Plain text
13403 #: build/C/man5/proc.5:3631
13404 msgid "1: always overcommit, never check"
13407 #. type: Plain text
13408 #: build/C/man5/proc.5:3633
13409 msgid "2: always check, never overcommit"
13412 #. type: Plain text
13413 #: build/C/man5/proc.5:3647
13415 "In mode 0, calls of B<mmap>(2) with B<MAP_NORESERVE> are not checked, and "
13416 "the default check is very weak, leading to the risk of getting a process "
13417 "\"OOM-killed\". Under Linux 2.4 any nonzero value implies mode 1. In mode "
13418 "2 (available since Linux 2.6), the total virtual address space on the system "
13419 "is limited to (SS + RAM*(r/100)), where SS is the size of the swap space, "
13420 "and RAM is the size of the physical memory, and r is the contents of the "
13421 "file I</proc/sys/vm/overcommit_ratio>."
13425 #: build/C/man5/proc.5:3647
13427 msgid "I</proc/sys/vm/overcommit_ratio>"
13430 #. type: Plain text
13431 #: build/C/man5/proc.5:3651
13432 msgid "See the description of I</proc/sys/vm/overcommit_memory>."
13436 #: build/C/man5/proc.5:3651
13438 msgid "I</proc/sys/vm/panic_on_oom> (since Linux 2.6.18)"
13441 #. The following is adapted from Documentation/sysctl/vm.txt
13442 #. type: Plain text
13443 #: build/C/man5/proc.5:3656
13444 msgid "This enables or disables a kernel panic in an out-of-memory situation."
13447 #. type: Plain text
13448 #: build/C/man5/proc.5:3661
13450 "If this file is set to the value 0, the kernel's OOM-killer will kill some "
13451 "rogue process. Usually, the OOM-killer is able to kill a rogue process and "
13452 "the system will survive."
13455 #. type: Plain text
13456 #: build/C/man5/proc.5:3676
13458 "If this file is set to the value 1, then the kernel normally panics when "
13459 "out-of-memory happens. However, if a process limits allocations to certain "
13460 "nodes using memory policies (B<mbind>(2) B<MPOL_BIND>) or cpusets "
13461 "(B<cpuset>(7)) and those nodes reach memory exhaustion status, one process "
13462 "may be killed by the OOM-killer. No panic occurs in this case: because "
13463 "other nodes' memory may be free, this means the system as a whole may not "
13464 "have reached an out-of-memory situation yet."
13467 #. type: Plain text
13468 #: build/C/man5/proc.5:3679
13470 "If this file is set to the value 2, the kernel always panics when an "
13471 "out-of-memory condition occurs."
13474 #. type: Plain text
13475 #: build/C/man5/proc.5:3683
13477 "The default value is 0. 1 and 2 are for failover of clustering. Select "
13478 "either according to your policy of failover."
13482 #: build/C/man5/proc.5:3683
13484 msgid "I</proc/sys/vm/swappiness>"
13487 #. The following is from Documentation/sysctl/vm.txt
13488 #. type: Plain text
13489 #: build/C/man5/proc.5:3691
13491 "The value in this file controls how aggressively the kernel will swap memory "
13492 "pages. Higher values increase aggressiveness, lower values decrease "
13493 "aggressiveness. The default value is 60."
13497 #: build/C/man5/proc.5:3691
13499 msgid "I</proc/sysrq-trigger> (since Linux 2.4.21)"
13502 #. type: Plain text
13503 #: build/C/man5/proc.5:3700
13505 "Writing a character to this file triggers the same SysRq function as typing "
13506 "ALT-SysRq-E<lt>characterE<gt> (see the description of "
13507 "I</proc/sys/kernel/sysrq>). This file is normally writable only by "
13508 "I<root>. For further details see the Linux kernel source file "
13509 "I<Documentation/sysrq.txt>."
13513 #: build/C/man5/proc.5:3700
13515 msgid "I</proc/sysvipc>"
13518 #. type: Plain text
13519 #: build/C/man5/proc.5:3713
13521 "Subdirectory containing the pseudo-files I<msg>, I<sem> and I<shm>. These "
13522 "files list the System V Interprocess Communication (IPC) objects "
13523 "(respectively: message queues, semaphores, and shared memory) that "
13524 "currently exist on the system, providing similar information to that "
13525 "available via B<ipcs>(1). These files have headers and are formatted (one "
13526 "IPC object per line) for easy understanding. B<svipc>(7) provides further "
13527 "background on the information shown by these files."
13531 #: build/C/man5/proc.5:3713
13533 msgid "I</proc/timer_list> (since Linux 2.6.21)"
13536 #. commit 289f480af87e45f7a6de6ba9b4c061c2e259fe98
13537 #. type: Plain text
13538 #: build/C/man5/proc.5:3719
13540 "This read-only file exposes a list of all currently pending "
13541 "(high-resolution) timers, all clock-event sources, and their parameters in a "
13542 "human-readable form."
13546 #: build/C/man5/proc.5:3719
13548 msgid "I</proc/timer_stats> (since Linux 2.6.21)"
13551 #. commit 82f67cd9fca8c8762c15ba7ed0d5747588c1e221
13552 #. Date: Fri Feb 16 01:28:13 2007 -0800
13553 #. Text largely derived from Documentation/timers/timer_stats.txt
13554 #. type: Plain text
13555 #: build/C/man5/proc.5:3730
13557 "This is a debugging facility to make timer (ab)use in a Linux system visible "
13558 "to kernel and user-space developers. It can be used by kernel and "
13559 "user-space developers to verify that their code does not make undue use of "
13560 "timers. The goal is to avoid unnecessary wakeups, thereby optimizing power "
13564 #. type: Plain text
13565 #: build/C/man5/proc.5:3738
13567 "If enabled in the kernel (B<CONFIG_TIMER_STATS>), but not used, it has "
13568 "almost zero runtime overhead and a relatively small data-structure "
13569 "overhead. Even if collection is enabled at runtime, overhead is low: all "
13570 "the locking is per-CPU and lookup is hashed."
13573 #. type: Plain text
13574 #: build/C/man5/proc.5:3743
13576 "The I</proc/timer_stats> file is used both to control sampling facility and "
13577 "to read out the sampled information."
13580 #. type: Plain text
13581 #: build/C/man5/proc.5:3746
13583 "timer_stats collects information about the timer events which are fired in a "
13584 "Linux system over a sample period:"
13587 #. type: Plain text
13588 #: build/C/man5/proc.5:3752
13590 "- the pid of the task(process) which initialized the timer - the name of the "
13591 "process which initialized the timer - the function where the timer was "
13592 "initialized - the callback function which is associated to the timer - the "
13593 "number of events (callbacks)"
13596 #. type: Plain text
13597 #: build/C/man5/proc.5:3755
13599 "The timer_stats functionality is inactive on bootup. A sampling period can "
13600 "be started using the following command:"
13603 #. type: Plain text
13604 #: build/C/man5/proc.5:3757
13606 msgid " # echo 1 E<gt> /proc/timer_stats\n"
13609 #. type: Plain text
13610 #: build/C/man5/proc.5:3759
13611 msgid "The following command stops a sampling period:"
13614 #. type: Plain text
13615 #: build/C/man5/proc.5:3761
13617 msgid " # echo 0 E<gt> /proc/timer_stats\n"
13620 #. type: Plain text
13621 #: build/C/man5/proc.5:3763
13622 msgid "The statistics can be retrieved by:"
13625 #. type: Plain text
13626 #: build/C/man5/proc.5:3765
13628 msgid " $ cat /proc/timer_stats\n"
13631 #. type: Plain text
13632 #: build/C/man5/proc.5:3771
13634 "While sampling is enabled, each readout from /proc/timer_stats will see "
13635 "newly updated statistics. Once sampling is disabled, the sampled "
13636 "information is kept until a new sample period is started. This allows "
13637 "multiple readouts."
13640 #. type: Plain text
13641 #: build/C/man5/proc.5:3774
13642 msgid "Sample output from I</proc/timer_stats>:"
13645 #. type: Plain text
13646 #: build/C/man5/proc.5:3790
13649 "$B< cat /proc/timer_stats>\n"
13650 "Timer Stats Version: v0.3\n"
13651 "Sample period: 1.764 s\n"
13652 "Collection: active\n"
13653 " 255, 0 swapper/3 hrtimer_start_range_ns (tick_sched_timer)\n"
13654 " 71, 0 swapper/1 hrtimer_start_range_ns (tick_sched_timer)\n"
13655 " 58, 0 swapper/0 hrtimer_start_range_ns (tick_sched_timer)\n"
13656 " 4, 1694 gnome-shell mod_delayed_work_on (delayed_work_timer_fn)\n"
13657 " 17, 7 rcu_sched rcu_gp_kthread (process_timeout)\n"
13659 " 1, 4911 kworker/u16:0 mod_delayed_work_on (delayed_work_timer_fn)\n"
13660 " 1D, 2522 kworker/0:0 queue_delayed_work_on "
13661 "(delayed_work_timer_fn)\n"
13662 "1029 total events, 583.333 events/sec\n"
13665 #. type: Plain text
13666 #: build/C/man5/proc.5:3795
13667 msgid "The output columns are:"
13670 #. commit c5c061b8f9726bc2c25e19dec227933a13d1e6b7 deferrable timers
13671 #. type: Plain text
13672 #: build/C/man5/proc.5:3801
13674 "a count of the number of events, optionally (since Linux 2.6.23) followed by "
13675 "the letter \\(aqD\\(aq if this is a deferrable timer;"
13678 #. type: Plain text
13679 #: build/C/man5/proc.5:3803
13680 msgid "the PID of the process that initialized the timer;"
13683 #. type: Plain text
13684 #: build/C/man5/proc.5:3805
13685 msgid "the name of the process that initialized the timer;"
13688 #. type: Plain text
13689 #: build/C/man5/proc.5:3807
13690 msgid "the function where the timer was initialized; and"
13693 #. type: Plain text
13694 #: build/C/man5/proc.5:3810
13695 msgid "(in parentheses) the callback function that is associated with the timer."
13699 #: build/C/man5/proc.5:3811
13701 msgid "I</proc/tty>"
13704 #. type: Plain text
13705 #: build/C/man5/proc.5:3815
13707 "Subdirectory containing the pseudo-files and subdirectories for tty drivers "
13708 "and line disciplines."
13712 #: build/C/man5/proc.5:3815
13714 msgid "I</proc/uptime>"
13717 #. type: Plain text
13718 #: build/C/man5/proc.5:3819
13720 "This file contains two numbers: the uptime of the system (seconds), and the "
13721 "amount of time spent in idle process (seconds)."
13725 #: build/C/man5/proc.5:3819
13727 msgid "I</proc/version>"
13730 #. type: Plain text
13731 #: build/C/man5/proc.5:3828
13733 "This string identifies the kernel version that is currently running. It "
13734 "includes the contents of I</proc/sys/kernel/ostype>, "
13735 "I</proc/sys/kernel/osrelease> and I</proc/sys/kernel/version>. For example:"
13738 #. type: Plain text
13739 #: build/C/man5/proc.5:3832
13741 msgid "CW<Linux version 1.0.9 (quinlan@phaze) #1 Sat May 14 01:51:54 EDT 1994>\n"
13745 #: build/C/man5/proc.5:3843
13747 msgid "I</proc/vmstat> (since Linux 2.6)"
13750 #. type: Plain text
13751 #: build/C/man5/proc.5:3846
13752 msgid "This file displays various virtual memory statistics."
13756 #: build/C/man5/proc.5:3846
13758 msgid "I</proc/zoneinfo> (since Linux 2.6.13)"
13761 #. FIXME more should be said about /proc/zoneinfo
13762 #. type: Plain text
13763 #: build/C/man5/proc.5:3851
13765 "This file display information about memory zones. This is useful for "
13766 "analyzing virtual memory behavior."
13769 #. type: Plain text
13770 #: build/C/man5/proc.5:3858
13772 "Many strings (i.e., the environment and command line) are in the internal "
13773 "format, with subfields terminated by null bytes (\\(aq\\e0\\(aq), so you may "
13774 "find that things are more readable if you use I<od -c> or I<tr \"\\e000\" "
13775 "\"\\en\"> to read them. Alternatively, I<echo \\`cat E<lt>fileE<gt>\\`> "
13779 #. .SH ACKNOWLEDGEMENTS
13780 #. The material on /proc/sys/fs and /proc/sys/kernel is closely based on
13781 #. kernel source documentation files written by Rik van Riel.
13782 #. type: Plain text
13783 #: build/C/man5/proc.5:3864
13785 "This manual page is incomplete, possibly inaccurate, and is the kind of "
13786 "thing that needs to be updated very often."
13789 #. type: Plain text
13790 #: build/C/man5/proc.5:3890
13792 "B<cat>(1), B<dmesg>(1), B<find>(1), B<free>(1), B<ps>(1), B<tr>(1), "
13793 "B<uptime>(1), B<chroot>(2), B<mmap>(2), B<readlink>(2), B<syslog>(2), "
13794 "B<slabinfo>(5), B<hier>(7), B<time>(7), B<arp>(8), B<hdparm>(8), "
13795 "B<ifconfig>(8), B<init>(8), B<lsmod>(8), B<lspci>(8), B<mount>(8), "
13796 "B<netstat>(8), B<procinfo>(8), B<route>(8), B<sysctl>(8)"
13799 #. type: Plain text
13800 #: build/C/man5/proc.5:3898
13802 "The Linux kernel source files: I<Documentation/filesystems/proc.txt> "
13803 "I<Documentation/sysctl/fs.txt>, I<Documentation/sysctl/kernel.txt>, "
13804 "I<Documentation/sysctl/net.txt>, and I<Documentation/sysctl/vm.txt>."
13808 #: build/C/man7/standards.7:24
13814 #: build/C/man7/standards.7:24
13819 #. type: Plain text
13820 #: build/C/man7/standards.7:27
13821 msgid "standards - C and UNIX Standards"
13824 #. type: Plain text
13825 #: build/C/man7/standards.7:31
13827 "The CONFORMING TO section that appears in many manual pages identifies "
13828 "various standards to which the documented interface conforms. The following "
13829 "list briefly describes these standards."
13833 #: build/C/man7/standards.7:31
13838 #. type: Plain text
13839 #: build/C/man7/standards.7:37
13841 "Version 7 (also known as Seventh Edition) UNIX, released by AT&T/Bell Labs "
13842 "in 1979. After this point, UNIX systems diverged into two main dialects: "
13843 "BSD and System V."
13847 #: build/C/man7/standards.7:37
13852 #. type: Plain text
13853 #: build/C/man7/standards.7:46
13855 "This is an implementation standard defined by the 4.2 release of the "
13856 "I<Berkeley Software Distribution>, released by the University of California "
13857 "at Berkeley. This was the first Berkeley release that contained a TCP/IP "
13858 "stack and the sockets API. 4.2BSD was released in 1983."
13861 #. type: Plain text
13862 #: build/C/man7/standards.7:55
13864 "Earlier major BSD releases included I<3BSD> (1980), I<4BSD> (1980), and "
13865 "I<4.1BSD> (1981)."
13869 #: build/C/man7/standards.7:55
13874 #. type: Plain text
13875 #: build/C/man7/standards.7:58
13876 msgid "The successor to 4.2BSD, released in 1986."
13880 #: build/C/man7/standards.7:58
13885 #. type: Plain text
13886 #: build/C/man7/standards.7:62
13888 "The successor to 4.3BSD, released in 1993. This was the last major Berkeley "
13893 #: build/C/man7/standards.7:62
13895 msgid "B<System V>"
13898 #. type: Plain text
13899 #: build/C/man7/standards.7:69
13901 "This is an implementation standard defined by AT&T's milestone 1983 release "
13902 "of its commercial System V (five) release. The previous major AT&T release "
13903 "was I<System III>, released in 1981."
13907 #: build/C/man7/standards.7:69
13909 msgid "B<System V release 2 (SVr2)>"
13912 #. type: Plain text
13913 #: build/C/man7/standards.7:76
13915 "This was the next System V release, made in 1985. The SVr2 was formally "
13916 "described in the I<System V Interface Definition version 1> (I<SVID 1>) "
13917 "published in 1985."
13921 #: build/C/man7/standards.7:76
13923 msgid "B<System V release 3 (SVr3)>"
13926 #. type: Plain text
13927 #: build/C/man7/standards.7:82
13929 "This was the successor to SVr2, released in 1986. This release was formally "
13930 "described in the I<System V Interface Definition version 2> (I<SVID 2>)."
13934 #: build/C/man7/standards.7:82
13936 msgid "B<System V release 4 (SVr4)>"
13939 #. type: Plain text
13940 #: build/C/man7/standards.7:92
13942 "This was the successor to SVr3, released in 1989. This version of System V "
13943 "is described in the \"Programmer's Reference Manual: Operating System API "
13944 "(Intel processors)\" (Prentice-Hall 1992, ISBN 0-13-951294-2) This release "
13945 "was formally described in the I<System V Interface Definition version 3> "
13946 "(I<SVID 3>), and is considered the definitive System V release."
13950 #: build/C/man7/standards.7:92
13955 #. type: Plain text
13956 #: build/C/man7/standards.7:98
13958 "System V Interface Definition version 4, issued in 1995. Available online "
13959 "at E<.UR http://www.sco.com\\:/developers\\:/devspecs/> E<.UE .>"
13963 #: build/C/man7/standards.7:98
13968 #. type: Plain text
13969 #: build/C/man7/standards.7:112
13971 "This was the first C language standard, ratified by ANSI (American National "
13972 "Standards Institute) in 1989 (I<X3.159-1989>). Sometimes this is known as "
13973 "I<ANSI C>, but since C99 is also an ANSI standard, this term is ambiguous. "
13974 "This standard was also ratified by ISO (International Standards "
13975 "Organization) in 1990 (I<ISO/IEC 9899:1990>), and is thus occasionally "
13976 "referred to as I<ISO C90>."
13980 #: build/C/man7/standards.7:112
13985 #. type: Plain text
13986 #: build/C/man7/standards.7:119
13988 "This revision of the C language standard was ratified by ISO in 1999 "
13989 "(I<ISO/IEC 9899:1999>). Available online at E<.UR "
13990 "http://www.open-std.org\\:/jtc1\\:/sc22\\:/wg14\\:/www\\:/standards> E<.UE "
13995 #: build/C/man7/standards.7:119
14000 #. type: Plain text
14001 #: build/C/man7/standards.7:123
14003 "This revision of the C language standard was ratified by ISO in 2011 "
14004 "(I<ISO/IEC 9899:2011>)."
14008 #: build/C/man7/standards.7:123
14010 msgid "B<POSIX.1-1990>"
14013 #. type: Plain text
14014 #: build/C/man7/standards.7:129
14016 "\"Portable Operating System Interface for Computing Environments\". IEEE "
14017 "1003.1-1990 part 1, ratified by ISO in 1990 (I<ISO/IEC 9945-1:1990>). The "
14018 "term \"POSIX\" was coined by Richard Stallman."
14022 #: build/C/man7/standards.7:129
14027 #. type: Plain text
14028 #: build/C/man7/standards.7:134
14030 "IEEE Std 1003.2-1992, describing commands and utilities, ratified by ISO in "
14031 "1993 (I<ISO/IEC 9945-2:1993>)."
14035 #: build/C/man7/standards.7:134
14037 msgid "B<POSIX.1b> (formerly known as I<POSIX.4>)"
14040 #. type: Plain text
14041 #: build/C/man7/standards.7:140
14043 "IEEE Std 1003.1b-1993, describing real-time facilities for portable "
14044 "operating systems, ratified by ISO in 1996 (I<ISO/IEC 9945-1:1996>)."
14048 #: build/C/man7/standards.7:140
14050 msgid "B<POSIX.1c>"
14053 #. type: Plain text
14054 #: build/C/man7/standards.7:143
14055 msgid "IEEE Std 1003.1c-1995, which describes the POSIX threads interfaces."
14059 #: build/C/man7/standards.7:143
14061 msgid "B<POSIX.1d>"
14064 #. type: Plain text
14065 #: build/C/man7/standards.7:146
14066 msgid "IEEE Std 1003.1c-1999, which describes additional real-time extensions."
14070 #: build/C/man7/standards.7:146
14072 msgid "B<POSIX.1g>"
14075 #. type: Plain text
14076 #: build/C/man7/standards.7:149
14077 msgid "IEEE Std 1003.1g-2000, which describes networking APIs (including sockets)."
14081 #: build/C/man7/standards.7:149
14083 msgid "B<POSIX.1j>"
14086 #. type: Plain text
14087 #: build/C/man7/standards.7:152
14088 msgid "IEEE Std 1003.1j-2000, which describes advanced real-time extensions."
14092 #: build/C/man7/standards.7:152
14094 msgid "B<POSIX.1-1996>"
14097 #. type: Plain text
14098 #: build/C/man7/standards.7:155
14099 msgid "A 1996 revision of POSIX.1 which incorporated POSIX.1b and POSIX.1c."
14103 #: build/C/man7/standards.7:155
14108 #. type: Plain text
14109 #: build/C/man7/standards.7:162
14111 "Released in 1989, this was the first significant release of the I<X/Open "
14112 "Portability Guide>, produced by the X/Open Company, a multivendor "
14113 "consortium. This multivolume guide was based on the POSIX standards."
14117 #: build/C/man7/standards.7:162
14122 #. type: Plain text
14123 #: build/C/man7/standards.7:165
14124 msgid "A revision of the X/Open Portability Guide, released in 1992."
14128 #: build/C/man7/standards.7:165
14133 #. type: Plain text
14134 #: build/C/man7/standards.7:172
14136 "A 1994 revision of XPG4. This is also referred to as I<Spec 1170>, where "
14137 "1170 referred to the number of interfaces defined by this standard."
14141 #: build/C/man7/standards.7:172
14143 msgid "B<SUS (SUSv1)>"
14146 #. type: Plain text
14147 #: build/C/man7/standards.7:180
14149 "Single UNIX Specification. This was a repackaging of XPG4v2 and other "
14150 "X/Open standards (X/Open Curses Issue 4 version 2, X/Open Networking Service "
14151 "(XNS) Issue 4). Systems conforming to this standard can be branded I<UNIX "
14156 #: build/C/man7/standards.7:180
14161 #. type: Plain text
14162 #: build/C/man7/standards.7:191
14164 "Single UNIX Specification version 2. Sometimes also referred to as "
14165 "I<XPG5>. This standard appeared in 1997. Systems conforming to this "
14166 "standard can be branded I<UNIX 98>. See also E<.UR "
14167 "http://www.UNIX-systems.org\\:/version2/> E<.UE .)>"
14171 #: build/C/man7/standards.7:191
14173 msgid "B<POSIX.1-2001, SUSv3>"
14176 #. type: Plain text
14177 #: build/C/man7/standards.7:203
14179 "This was a 2001 revision and consolidation of the POSIX.1, POSIX.2, and SUS "
14180 "standards into a single document, conducted under the auspices of the Austin "
14181 "group E<.UR http://www.opengroup.org\\:/austin/> E<.UE .> The standard is "
14182 "available online at E<.UR http://www.unix-systems.org\\:/version3/> E<.UE ,> "
14183 "and the interfaces that it describes are also available in the Linux manual "
14184 "pages package under sections 1p and 3p (e.g., \"man 3p open\")."
14187 #. type: Plain text
14188 #: build/C/man7/standards.7:216
14190 "The standard defines two levels of conformance: I<POSIX conformance>, which "
14191 "is a baseline set of interfaces required of a conforming system; and I<XSI "
14192 "Conformance>, which additionally mandates a set of interfaces (the \"XSI "
14193 "extension\") which are only optional for POSIX conformance. XSI-conformant "
14194 "systems can be branded I<UNIX 03>. (XSI conformance constitutes the "
14195 "I<Single UNIX Specification version 3> (I<SUSv3>).)"
14198 #. type: Plain text
14199 #: build/C/man7/standards.7:218
14200 msgid "The POSIX.1-2001 document is broken into four parts:"
14203 #. type: Plain text
14204 #: build/C/man7/standards.7:221
14205 msgid "B<XBD>: Definitions, terms and concepts, header file specifications."
14208 #. type: Plain text
14209 #: build/C/man7/standards.7:225
14211 "B<XSH>: Specifications of functions (i.e., system calls and library "
14212 "functions in actual implementations)."
14215 #. type: Plain text
14216 #: build/C/man7/standards.7:229
14218 "B<XCU>: Specifications of commands and utilities (i.e., the area formerly "
14219 "described by POSIX.2)."
14222 #. type: Plain text
14223 #: build/C/man7/standards.7:232
14224 msgid "B<XRAT>: Informative text on the other parts of the standard."
14227 #. type: Plain text
14228 #: build/C/man7/standards.7:236
14230 "POSIX.1-2001 is aligned with C99, so that all of the library functions "
14231 "standardized in C99 are also standardized in POSIX.1-2001."
14234 #. type: Plain text
14235 #: build/C/man7/standards.7:243
14237 "Two Technical Corrigenda (minor fixes and improvements) of the original "
14238 "2001 standard have occurred: TC1 in 2003 (referred to as I<POSIX.1-2003>), "
14239 "and TC2 in 2004 (referred to as I<POSIX.1-2004>)."
14243 #: build/C/man7/standards.7:243
14245 msgid "B<POSIX.1-2008, SUSv4>"
14248 #. type: Plain text
14249 #: build/C/man7/standards.7:247
14250 msgid "Work on the next revision of POSIX.1/SUS was completed and ratified in 2008."
14253 #. type: Plain text
14254 #: build/C/man7/standards.7:256
14256 "The changes in this revision are not as large as those that occurred for "
14257 "POSIX.1-2001/SUSv3, but a number of new interfaces are added and various "
14258 "details of existing specifications are modified. Many of the interfaces "
14259 "that were optional in POSIX.1-2001 become mandatory in the 2008 revision of "
14260 "the standard. A few interfaces that are present in POSIX.1-2001 are marked "
14261 "as obsolete in POSIX.1-2008, or removed from the standard altogether."
14264 #. type: Plain text
14265 #: build/C/man7/standards.7:264
14267 "The revised standard is broken into the same four parts as POSIX.1-2001, and "
14268 "again there are two levels of conformance: the baseline I<POSIX "
14269 "Conformance>, and I<XSI Conformance>, which mandates an additional set of "
14270 "interfaces beyond those in the base specification."
14273 #. type: Plain text
14274 #: build/C/man7/standards.7:268
14276 "In general, where the CONFORMING TO section of a manual page lists "
14277 "POSIX.1-2001, it can be assumed that the interface also conforms to "
14278 "POSIX.1-2008, unless otherwise noted."
14281 #. type: Plain text
14282 #: build/C/man7/standards.7:273
14284 "Technical Corrigendum 1 (minor fixes and improvements) of this standard was "
14285 "released in 2013 (referred to as I<POSIX.1-2013>)."
14288 #. type: Plain text
14289 #: build/C/man7/standards.7:277
14291 "Further information can be found on the Austin group web site, E<.UR "
14292 "http://www.opengroup.org\\:/austin/> E<.UE .>"
14295 #. type: Plain text
14296 #: build/C/man7/standards.7:281
14297 msgid "B<feature_test_macros>(7), B<libc>(7), B<posixoptions>(7)"
14301 #: build/C/man7/suffixes.7:39
14307 #: build/C/man7/suffixes.7:39
14312 #. type: Plain text
14313 #: build/C/man7/suffixes.7:42
14314 msgid "suffixes - list of file suffixes"
14317 #. type: Plain text
14318 #: build/C/man7/suffixes.7:50
14320 "It is customary to indicate the contents of a file with the file suffix, "
14321 "which consists of a period, followed by one or more letters. Many standard "
14322 "utilities, such as compilers, use this to recognize the type of file they "
14323 "are dealing with. The B<make>(1) utility is driven by rules based on file "
14327 #. type: Plain text
14328 #: build/C/man7/suffixes.7:53
14330 "Following is a list of suffixes which are likely to be found on a Linux "
14335 #: build/C/man7/suffixes.7:58
14337 msgid "Suffix\tFile type\n"
14341 #: build/C/man7/suffixes.7:59
14343 msgid " ,v\tfiles for RCS (Revision Control System)\n"
14347 #: build/C/man7/suffixes.7:60
14349 msgid " -\tbackup file\n"
14353 #: build/C/man7/suffixes.7:61
14355 msgid " .C\tC++ source code, equivalent to I<.cc>\n"
14359 #: build/C/man7/suffixes.7:62
14361 msgid " .F\tFortran source with B<cpp>(1) directives\n"
14365 #: build/C/man7/suffixes.7:63
14367 msgid "\tor file compressed using freeze\n"
14371 #: build/C/man7/suffixes.7:64
14373 msgid " .S\tassembler source with B<cpp>(1) directives\n"
14377 #: build/C/man7/suffixes.7:65
14379 msgid " .Y\tfile compressed using yabba\n"
14383 #: build/C/man7/suffixes.7:66
14385 msgid " .Z\tfile compressed using B<compress>(1)\n"
14389 #: build/C/man7/suffixes.7:67
14391 msgid " .[0-9]+gf\tTeX generic font files\n"
14395 #: build/C/man7/suffixes.7:68
14397 msgid " .[0-9]+pk\tTeX packed font files\n"
14401 #: build/C/man7/suffixes.7:69
14403 msgid " .[1-9]\tmanual page for the corresponding section\n"
14407 #: build/C/man7/suffixes.7:70
14409 msgid " .[1-9][a-z]\tmanual page for section plus subsection\n"
14413 #: build/C/man7/suffixes.7:71
14415 msgid " .a\tstatic object code library\n"
14419 #: build/C/man7/suffixes.7:72
14421 msgid " .ad\tX application default resource file\n"
14425 #: build/C/man7/suffixes.7:73
14427 msgid " .ada\tAda source (may be body, spec, or combination)\n"
14431 #: build/C/man7/suffixes.7:74
14433 msgid " .adb\tAda body source\n"
14437 #: build/C/man7/suffixes.7:75
14439 msgid " .ads\tAda spec source\n"
14443 #: build/C/man7/suffixes.7:76
14445 msgid " .afm\tPostScript font metrics\n"
14449 #: build/C/man7/suffixes.7:77
14451 msgid " .al\tPerl autoload file\n"
14455 #: build/C/man7/suffixes.7:78
14457 msgid " .am\tB<automake>(1) input file\n"
14461 #: build/C/man7/suffixes.7:79
14463 msgid " .arc\tB<arc>(1) archive\n"
14467 #: build/C/man7/suffixes.7:80
14469 msgid " .arj\tB<arj>(1) archive\n"
14473 #: build/C/man7/suffixes.7:81
14475 msgid " .asc\tPGP ASCII-armored data\n"
14479 #: build/C/man7/suffixes.7:82
14481 msgid " .asm\t(GNU) assembler source file\n"
14485 #: build/C/man7/suffixes.7:83
14487 msgid " .au\tAudio sound file\n"
14491 #: build/C/man7/suffixes.7:84
14493 msgid " .aux\tLaTeX auxiliary file\n"
14497 #: build/C/man7/suffixes.7:85
14499 msgid " .avi\t(msvideo) movie\n"
14503 #: build/C/man7/suffixes.7:86
14505 msgid " .awk\tAWK language program\n"
14509 #: build/C/man7/suffixes.7:87
14511 msgid " .b\tLILO boot loader image\n"
14515 #: build/C/man7/suffixes.7:88
14517 msgid " .bak\tbackup file\n"
14521 #: build/C/man7/suffixes.7:89
14523 msgid " .bash\tB<bash>(1) shell script\n"
14527 #: build/C/man7/suffixes.7:90
14529 msgid " .bb\tbasic block list data produced by\n"
14533 #: build/C/man7/suffixes.7:91 build/C/man7/suffixes.7:93
14535 msgid "\tgcc -ftest-coverage\n"
14539 #: build/C/man7/suffixes.7:92
14541 msgid " .bbg\tbasic block graph data produced by\n"
14545 #: build/C/man7/suffixes.7:94
14547 msgid " .bbl\tBibTeX output\n"
14551 #: build/C/man7/suffixes.7:95
14553 msgid " .bdf\tX font file\n"
14557 #: build/C/man7/suffixes.7:96
14559 msgid " .bib\tTeX bibliographic database, BibTeX input\n"
14563 #: build/C/man7/suffixes.7:97
14565 msgid " .bm\tbitmap source\n"
14569 #: build/C/man7/suffixes.7:98
14571 msgid " .bmp\tbitmap\n"
14575 #: build/C/man7/suffixes.7:99
14577 msgid " .bz2\tfile compressed using B<bzip2>(1)\n"
14581 #: build/C/man7/suffixes.7:100
14583 msgid " .c\tC source\n"
14587 #: build/C/man7/suffixes.7:101
14589 msgid " .cat\tmessage catalog files\n"
14593 #: build/C/man7/suffixes.7:102
14595 msgid " .cc\tC++ source\n"
14599 #: build/C/man7/suffixes.7:103
14601 msgid " .cf\tconfiguration file\n"
14605 #: build/C/man7/suffixes.7:104
14607 msgid " .cfg\tconfiguration file\n"
14611 #: build/C/man7/suffixes.7:105
14613 msgid " .cgi\tWWW content generating script or program\n"
14617 #: build/C/man7/suffixes.7:106
14619 msgid " .cls\tLaTeX Class definition\n"
14623 #: build/C/man7/suffixes.7:107
14625 msgid " .class\tJava compiled byte-code\n"
14629 #: build/C/man7/suffixes.7:108
14631 msgid " .conf\tconfiguration file\n"
14635 #: build/C/man7/suffixes.7:109
14637 msgid " .config\tconfiguration file\n"
14641 #: build/C/man7/suffixes.7:110
14643 msgid " .cpp\tequivalent to I<.cc>\n"
14647 #: build/C/man7/suffixes.7:111
14649 msgid " .csh\tB<csh>(1) shell script\n"
14653 #: build/C/man7/suffixes.7:112
14655 msgid " .cxx\tequivalent to I<.cc>\n"
14659 #: build/C/man7/suffixes.7:113
14661 msgid " .dat\tdata file\n"
14665 #: build/C/man7/suffixes.7:114
14667 msgid " .deb\tDebian software package\n"
14671 #: build/C/man7/suffixes.7:115
14673 msgid " .def\tModula-2 source for definition modules\n"
14677 #: build/C/man7/suffixes.7:116
14679 msgid " .def\tother definition files\n"
14683 #: build/C/man7/suffixes.7:117
14685 msgid " .desc\tinitial part of mail message unpacked with\n"
14689 #: build/C/man7/suffixes.7:118
14691 msgid "\tB<munpack>(1)\n"
14695 #: build/C/man7/suffixes.7:119
14697 msgid " .diff\tfile differences (B<diff>(1) command output)\n"
14701 #: build/C/man7/suffixes.7:120
14703 msgid " .dir\tdbm data base directory file\n"
14707 #: build/C/man7/suffixes.7:121
14709 msgid " .doc\tdocumentation file\n"
14713 #: build/C/man7/suffixes.7:122
14715 msgid " .dsc\tDebian Source Control (source package)\n"
14719 #: build/C/man7/suffixes.7:123
14721 msgid " .dtx\tLaTeX package source file\n"
14725 #: build/C/man7/suffixes.7:124
14727 msgid " .dvi\tTeX's device independent output\n"
14731 #: build/C/man7/suffixes.7:125
14733 msgid " .el\tEmacs-Lisp source\n"
14737 #: build/C/man7/suffixes.7:126
14739 msgid " .elc\tcompiled Emacs-Lisp source\n"
14743 #: build/C/man7/suffixes.7:127
14745 msgid " .eps\tencapsulated PostScript\n"
14749 #: build/C/man7/suffixes.7:128
14751 msgid " .exp\tExpect source code\n"
14755 #: build/C/man7/suffixes.7:129
14757 msgid " .f\tFortran source\n"
14761 #: build/C/man7/suffixes.7:130
14763 msgid " .f77\tFortran 77 source\n"
14767 #: build/C/man7/suffixes.7:131
14769 msgid " .f90\tFortran 90 source\n"
14773 #: build/C/man7/suffixes.7:132
14775 msgid " .fas\tprecompiled Common-Lisp\n"
14779 #: build/C/man7/suffixes.7:133
14781 msgid " .fi\tFortran include files\n"
14785 #: build/C/man7/suffixes.7:134
14787 msgid " .fig\tFIG image file (used by B<xfig>(1))\n"
14791 #: build/C/man7/suffixes.7:135
14793 msgid " .fmt\tTeX format file\n"
14797 #: build/C/man7/suffixes.7:136
14799 msgid " .gif\tCompuserve Graphics Image File format\n"
14803 #: build/C/man7/suffixes.7:137
14805 msgid " .gmo\tGNU format message catalog\n"
14809 #: build/C/man7/suffixes.7:138
14811 msgid " .gsf\tGhostscript fonts\n"
14815 #: build/C/man7/suffixes.7:139
14817 msgid " .gz\tfile compressed using B<gzip>(1)\n"
14821 #: build/C/man7/suffixes.7:140
14823 msgid " .h\tC or C++ header files\n"
14827 #: build/C/man7/suffixes.7:141
14829 msgid " .help\thelp file\n"
14833 #: build/C/man7/suffixes.7:142
14835 msgid " .hf\tequivalent to I<.help>\n"
14839 #: build/C/man7/suffixes.7:143
14841 msgid " .hlp\tequivalent to I<.help>\n"
14845 #: build/C/man7/suffixes.7:144
14847 msgid " .htm\tpoor man's I<.html>\n"
14851 #: build/C/man7/suffixes.7:145
14853 msgid " .html\tHTML document used with the World Wide Web\n"
14857 #: build/C/man7/suffixes.7:146
14859 msgid " .hqx\t7-bit encoded Macintosh file\n"
14863 #: build/C/man7/suffixes.7:147
14865 msgid " .i\tC source after preprocessing\n"
14869 #: build/C/man7/suffixes.7:148
14871 msgid " .icon\tbitmap source\n"
14875 #: build/C/man7/suffixes.7:149
14877 msgid " .idx\treference or datum-index file for hypertext\n"
14881 #: build/C/man7/suffixes.7:150
14883 msgid "\tor database system\n"
14887 #: build/C/man7/suffixes.7:151
14889 msgid " .image\tbitmap source\n"
14893 #: build/C/man7/suffixes.7:152
14895 msgid " .in\tconfiguration template, especially for GNU Autoconf\n"
14899 #: build/C/man7/suffixes.7:153
14901 msgid " .info\tfiles for the Emacs info browser\n"
14905 #: build/C/man7/suffixes.7:154
14907 msgid " .info-[0-9]+\tsplit info files\n"
14911 #: build/C/man7/suffixes.7:155
14913 msgid " .ins\tLaTeX package install file for docstrip\n"
14917 #: build/C/man7/suffixes.7:156
14919 msgid " .itcl\titcl source code;\n"
14923 #: build/C/man7/suffixes.7:157
14925 msgid "\titcl ([incr Tcl]) is an OO extension of tcl\n"
14929 #: build/C/man7/suffixes.7:158
14931 msgid " .java\ta Java source file\n"
14935 #: build/C/man7/suffixes.7:159
14937 msgid " .jpeg\tJoint Photographic Experts Group format\n"
14941 #: build/C/man7/suffixes.7:160
14943 msgid " .jpg\tpoor man's I<.jpeg>\n"
14947 #: build/C/man7/suffixes.7:161
14949 msgid " .kmap\tB<lyx>(1) keymap\n"
14953 #: build/C/man7/suffixes.7:162
14955 msgid " .l\tequivalent to I<.lex> or I<.lisp>\n"
14959 #: build/C/man7/suffixes.7:163
14961 msgid " .lex\tB<lex>(1) or B<flex>(1) files\n"
14965 #: build/C/man7/suffixes.7:164
14967 msgid " .lha\tlharc archive\n"
14971 #: build/C/man7/suffixes.7:165
14973 msgid " .lib\tCommon-Lisp library\n"
14977 #: build/C/man7/suffixes.7:166
14979 msgid " .lisp\tLisp source\n"
14983 #: build/C/man7/suffixes.7:167
14985 msgid " .ln\tfiles for use with B<lint>(1)\n"
14989 #: build/C/man7/suffixes.7:168
14991 msgid " .log\tlog file, in particular produced by TeX\n"
14995 #: build/C/man7/suffixes.7:169
14997 msgid " .lsm\tLinux Software Map entry\n"
15001 #: build/C/man7/suffixes.7:170
15003 msgid " .lsp\tCommon-Lisp source\n"
15007 #: build/C/man7/suffixes.7:171
15009 msgid " .lzh\tlharc archive\n"
15013 #: build/C/man7/suffixes.7:172
15015 msgid " .m\tObjective-C source code\n"
15019 #: build/C/man7/suffixes.7:173
15021 msgid " .m4\tB<m4>(1) source\n"
15025 #: build/C/man7/suffixes.7:174
15027 msgid " .mac\tmacro files for various programs\n"
15031 #: build/C/man7/suffixes.7:175
15033 msgid " .man\tmanual page (usually source rather than formatted)\n"
15037 #: build/C/man7/suffixes.7:176
15039 msgid " .map\tmap files for various programs\n"
15043 #: build/C/man7/suffixes.7:177
15045 msgid " .me\tNroff source using the me macro package\n"
15049 #: build/C/man7/suffixes.7:178
15051 msgid " .mf\tMetafont (font generator for TeX) source\n"
15055 #: build/C/man7/suffixes.7:179
15057 msgid " .mgp\tMagicPoint file\n"
15061 #: build/C/man7/suffixes.7:180
15063 msgid " .mm\tsources for B<groff>(1) in mm - format\n"
15067 #: build/C/man7/suffixes.7:181
15069 msgid " .mo\tMessage catalog binary file\n"
15073 #: build/C/man7/suffixes.7:182
15075 msgid " .mod\tModula-2 source for implementation modules\n"
15079 #: build/C/man7/suffixes.7:183
15081 msgid " .mov\t(quicktime) movie\n"
15085 #: build/C/man7/suffixes.7:184
15087 msgid " .mp\tMetapost source\n"
15091 #: build/C/man7/suffixes.7:185
15093 msgid " .mp2\tMPEG Layer 2 (audio) file\n"
15097 #: build/C/man7/suffixes.7:186
15099 msgid " .mp3\tMPEG Layer 3 (audio) file\n"
15103 #: build/C/man7/suffixes.7:187
15105 msgid " .mpeg\tmovie file\n"
15109 #: build/C/man7/suffixes.7:188
15111 msgid " .o\tobject file\n"
15115 #: build/C/man7/suffixes.7:189
15117 msgid " .old\told or backup file\n"
15121 #: build/C/man7/suffixes.7:190
15123 msgid " .orig\tbackup (original) version of a file, from B<patch>(1)\n"
15127 #: build/C/man7/suffixes.7:191
15129 msgid " .out\toutput file, often executable program (a.out)\n"
15133 #: build/C/man7/suffixes.7:192
15135 msgid " .p\tPascal source\n"
15139 #: build/C/man7/suffixes.7:193
15141 msgid " .pag\tdbm data base data file\n"
15145 #: build/C/man7/suffixes.7:194
15147 msgid " .patch\tfile differences for B<patch>(1)\n"
15151 #: build/C/man7/suffixes.7:195
15153 msgid " .pbm\tportable bitmap format\n"
15157 #: build/C/man7/suffixes.7:196
15159 msgid " .pcf\tX11 font files\n"
15163 #: build/C/man7/suffixes.7:197
15165 msgid " .pdf\tAdobe Portable Data Format\n"
15169 #: build/C/man7/suffixes.7:198
15171 msgid "\t(use Acrobat/B<acroread> or B<xpdf>)\n"
15175 #: build/C/man7/suffixes.7:199
15177 msgid " .perl\tPerl source (see .ph, .pl and .pm)\n"
15181 #: build/C/man7/suffixes.7:200
15183 msgid " .pfa\tPostScript font definition files, ASCII format\n"
15187 #: build/C/man7/suffixes.7:201
15189 msgid " .pfb\tPostScript font definition files, binary format\n"
15193 #: build/C/man7/suffixes.7:202
15195 msgid " .pgm\tportable greymap format\n"
15199 #: build/C/man7/suffixes.7:203
15201 msgid " .pgp\tPGP binary data\n"
15205 #: build/C/man7/suffixes.7:204
15207 msgid " .ph\tPerl header file\n"
15211 #: build/C/man7/suffixes.7:205
15213 msgid " .php\tPHP program file\n"
15217 #: build/C/man7/suffixes.7:206
15219 msgid " .php3\tPHP3 program file\n"
15223 #: build/C/man7/suffixes.7:207
15225 msgid " .pid\tFile to store daemon PID (e.g., crond.pid)\n"
15229 #: build/C/man7/suffixes.7:208
15231 msgid " .pl\tTeX property list file or Perl library file\n"
15235 #: build/C/man7/suffixes.7:209
15237 msgid " .pm\tPerl module\n"
15241 #: build/C/man7/suffixes.7:210
15243 msgid " .png\tPortable Network Graphics file\n"
15247 #: build/C/man7/suffixes.7:211
15249 msgid " .po\tMessage catalog source\n"
15253 #: build/C/man7/suffixes.7:212
15255 msgid " .pod\tB<perldoc>(1) file\n"
15259 #: build/C/man7/suffixes.7:213
15261 msgid " .ppm\tportable pixmap format\n"
15265 #: build/C/man7/suffixes.7:214
15267 msgid " .pr\tbitmap source\n"
15271 #: build/C/man7/suffixes.7:215
15273 msgid " .ps\tPostScript file\n"
15277 #: build/C/man7/suffixes.7:216
15279 msgid " .py\tPython source\n"
15283 #: build/C/man7/suffixes.7:217
15285 msgid " .pyc\tcompiled python\n"
15289 #: build/C/man7/suffixes.7:218
15291 msgid " .qt\tquicktime movie\n"
15295 #: build/C/man7/suffixes.7:219
15297 msgid " .r\tRATFOR source (obsolete)\n"
15301 #: build/C/man7/suffixes.7:220
15303 msgid " .rej\tpatches that B<patch>(1) couldn't apply\n"
15307 #: build/C/man7/suffixes.7:221
15309 msgid " .rpm\tRPM software package\n"
15313 #: build/C/man7/suffixes.7:222
15315 msgid " .rtf\tRich Text Format file\n"
15319 #: build/C/man7/suffixes.7:223
15321 msgid " .rules\trules for something\n"
15325 #: build/C/man7/suffixes.7:224
15327 msgid " .s\tassembler source\n"
15331 #: build/C/man7/suffixes.7:225
15333 msgid " .sa\tstub libraries for a.out shared libraries\n"
15337 #: build/C/man7/suffixes.7:226
15339 msgid " .sc\tB<sc>(1) spreadsheet commands\n"
15343 #: build/C/man7/suffixes.7:227
15345 msgid " .scm\tScheme source code\n"
15349 #: build/C/man7/suffixes.7:228
15351 msgid " .sed\tsed source file\n"
15355 #: build/C/man7/suffixes.7:229
15357 msgid " .sgml\tSGML source file\n"
15361 #: build/C/man7/suffixes.7:230
15363 msgid " .sh\tB<sh>(1) scripts\n"
15367 #: build/C/man7/suffixes.7:231
15369 msgid " .shar\tarchive created by the B<shar>(1) utility\n"
15373 #: build/C/man7/suffixes.7:232
15375 msgid " .so\tShared library or dynamically loadable object\n"
15379 #: build/C/man7/suffixes.7:233
15381 msgid " .sql\tSQL source\n"
15385 #: build/C/man7/suffixes.7:234
15387 msgid " .sqml\tSQML schema or query program\n"
15391 #: build/C/man7/suffixes.7:235
15393 msgid " .sty\tLaTeX style files\n"
15397 #: build/C/man7/suffixes.7:236
15399 msgid " .sym\tModula-2 compiled definition modules\n"
15403 #: build/C/man7/suffixes.7:237
15405 msgid " .tar\tarchive created by the B<tar>(1) utility\n"
15409 #: build/C/man7/suffixes.7:238
15411 msgid " .tar.Z\ttar(1) archive compressed with B<compress>(1)\n"
15415 #: build/C/man7/suffixes.7:239
15417 msgid " .tar.bz2\ttar(1) archive compressed with B<bzip2>(1)\n"
15421 #: build/C/man7/suffixes.7:240
15423 msgid " .tar.gz\ttar(1) archive compressed with B<gzip>(1)\n"
15427 #: build/C/man7/suffixes.7:241
15429 msgid " .taz\ttar(1) archive compressed with B<compress>(1)\n"
15433 #: build/C/man7/suffixes.7:242
15435 msgid " .tcl\ttcl source code\n"
15439 #: build/C/man7/suffixes.7:243
15441 msgid " .tex\tTeX or LaTeX source\n"
15445 #: build/C/man7/suffixes.7:244
15447 msgid " .texi\tequivalent to I<.texinfo>\n"
15451 #: build/C/man7/suffixes.7:245
15453 msgid " .texinfo\tTexinfo documentation source\n"
15457 #: build/C/man7/suffixes.7:246
15459 msgid " .text\ttext file\n"
15463 #: build/C/man7/suffixes.7:247
15465 msgid " .tfm\tTeX font metric file\n"
15469 #: build/C/man7/suffixes.7:248
15471 msgid " .tgz\ttar archive compressed with B<gzip>(1)\n"
15475 #: build/C/man7/suffixes.7:249
15477 msgid " .tif\tpoor man's I<.tiff>\n"
15481 #: build/C/man7/suffixes.7:250
15483 msgid " .tiff\tTagged Image File Format\n"
15487 #: build/C/man7/suffixes.7:251
15489 msgid " .tk\ttcl/tk script\n"
15493 #: build/C/man7/suffixes.7:252
15495 msgid " .tmp\ttemporary file\n"
15499 #: build/C/man7/suffixes.7:253
15501 msgid " .tmpl\ttemplate files\n"
15505 #: build/C/man7/suffixes.7:254
15507 msgid " .txt\tequivalent to I<.text>\n"
15511 #: build/C/man7/suffixes.7:255
15513 msgid " .uu\tequivalent to I<.uue>\n"
15517 #: build/C/man7/suffixes.7:256
15519 msgid " .uue\tbinary file encoded with B<uuencode>(1)\n"
15523 #: build/C/man7/suffixes.7:257
15525 msgid " .vf\tTeX virtual font file\n"
15529 #: build/C/man7/suffixes.7:258
15531 msgid " .vpl\tTeX virtual property list file\n"
15535 #: build/C/man7/suffixes.7:259
15537 msgid " .w\tSilvio Levi's CWEB\n"
15541 #: build/C/man7/suffixes.7:260
15543 msgid " .wav\twave sound file\n"
15547 #: build/C/man7/suffixes.7:261
15549 msgid " .web\tDonald Knuth's WEB\n"
15553 #: build/C/man7/suffixes.7:262
15555 msgid " .wml\tSource file for Web Meta Language\n"
15559 #: build/C/man7/suffixes.7:263
15561 msgid " .xbm\tX11 bitmap source\n"
15565 #: build/C/man7/suffixes.7:264
15567 msgid " .xcf\tGIMP graphic\n"
15571 #: build/C/man7/suffixes.7:265
15573 msgid " .xml\teXtended Markup Language file\n"
15577 #: build/C/man7/suffixes.7:266
15579 msgid " .xpm\tX11 pixmap source\n"
15583 #: build/C/man7/suffixes.7:267
15585 msgid " .xs\tPerl xsub file produced by h2xs\n"
15589 #: build/C/man7/suffixes.7:268
15591 msgid " .xsl\tXSL stylesheet\n"
15595 #: build/C/man7/suffixes.7:269
15597 msgid " .y\tB<yacc>(1) or B<bison>(1) (parser generator) files\n"
15601 #: build/C/man7/suffixes.7:270
15603 msgid " .z\tFile compressed using B<pack>(1) (or an old B<gzip>(1))\n"
15607 #: build/C/man7/suffixes.7:271
15609 msgid " .zip\tB<zip>(1) archive\n"
15613 #: build/C/man7/suffixes.7:272
15615 msgid " .zoo\tB<zoo>(1) archive\n"
15619 #: build/C/man7/suffixes.7:273
15621 msgid " ~\tEmacs or B<patch>(1) backup file\n"
15625 #: build/C/man7/suffixes.7:274
15627 msgid " rc\tstartup (`run control') file, e.g., I<.newsrc>\n"
15630 #. type: Plain text
15631 #: build/C/man7/suffixes.7:278
15632 msgid "General UNIX conventions."
15635 #. type: Plain text
15636 #: build/C/man7/suffixes.7:280
15637 msgid "This list is not exhaustive."
15640 #. type: Plain text
15641 #: build/C/man7/suffixes.7:283
15642 msgid "B<file>(1), B<make>(1)"
15646 #: build/C/man3/undocumented.3:29
15648 msgid "UNDOCUMENTED"
15652 #: build/C/man3/undocumented.3:29
15657 #. type: Plain text
15658 #: build/C/man3/undocumented.3:32
15659 msgid "none - undocumented library functions"
15662 #. type: Plain text
15663 #: build/C/man3/undocumented.3:34
15664 msgid "Undocumented library functions"
15667 #. type: Plain text
15668 #: build/C/man3/undocumented.3:37
15670 "This man page mentions those library functions which are implemented in the "
15671 "standard libraries but not yet documented in man pages."
15675 #: build/C/man3/undocumented.3:37
15677 msgid "Solicitation"
15680 #. type: Plain text
15681 #: build/C/man3/undocumented.3:43
15683 "If you have information about these functions, please look in the source "
15684 "code, write a man page (using a style similar to that of the other Linux "
15685 "section 3 man pages), and send it to B<mtk.manpages@gmail.com> for inclusion "
15686 "in the next man page release."
15690 #: build/C/man3/undocumented.3:43
15695 #. .BR chflags (3),
15696 #. .BR fattach (3),
15697 #. .BR fchflags (3),
15699 #. .BR fdetach (3),
15700 #. .BR obstack stuff (3),
15701 #. type: Plain text
15702 #: build/C/man3/undocumented.3:183
15704 "B<authdes_create>(3), B<authdes_getucred>(3), B<authdes_pk_create>(3), "
15705 "B<clntunix_create>(3), B<creat64>(3), B<dn_skipname>(3), B<fcrypt>(3), "
15706 "B<fp_nquery>(3), B<fp_query>(3), B<fp_resstat>(3), B<freading>(3), "
15707 "B<freopen64>(3), B<fseeko64>(3), B<ftello64>(3), B<ftw64>(3), B<fwscanf>(3), "
15708 "B<get_avphys_pages>(3), B<getdirentries64>(3), B<getmsg>(3), "
15709 "B<getnetname>(3), B<get_nprocs>(3), B<get_nprocs_conf>(3), "
15710 "B<get_phys_pages>(3), B<getpublickey>(3), B<getsecretkey>(3), "
15711 "B<h_errlist>(3), B<host2netname>(3), B<hostalias>(3), B<inet_nsap_addr>(3), "
15712 "B<inet_nsap_ntoa>(3), B<init_des>(3), B<libc_nls_init>(3), B<lio_listio>(3), "
15713 "B<mstats>(3), B<netname2host>(3), B<netname2user>(3), B<nlist>(3), "
15714 "B<obstack_free>(3), B<parse_printf_format>(3), B<p_cdname>(3), "
15715 "B<p_cdnname>(3), B<p_class>(3), B<p_fqname>(3), B<p_option>(3), "
15716 "B<p_query>(3), B<printf_size>(3), B<printf_size_info>(3), B<p_rr>(3), "
15717 "B<p_time>(3), B<p_type>(3), B<putlong>(3), B<putshort>(3), "
15718 "B<re_compile_fastmap>(3), B<re_compile_pattern>(3), "
15719 "B<register_printf_function>(3), B<re_match>(3), B<re_match_2>(3), "
15720 "B<re_rx_search>(3), B<re_search>(3), B<re_search_2>(3), "
15721 "B<re_set_registers>(3), B<re_set_syntax>(3), B<res_send_setqhook>(3), "
15722 "B<res_send_setrhook>(3), B<ruserpass>(3), B<setfileno>(3), "
15723 "B<sethostfile>(3), B<svc_exit>(3), B<svcudp_enablecache>(3), B<tell>(3), "
15724 "B<tr_break>(3), B<tzsetwall>(3), B<ufc_dofinalperm>(3), B<ufc_doit>(3), "
15725 "B<user2netname>(3), B<vlimit>(3), B<vtimes>(3), B<wcschrnul>(3), "
15726 "B<wcsftime>(3), B<wscanf>(3), B<xdr_authdes_cred>(3), "
15727 "B<xdr_authdes_verf>(3), B<xdr_cryptkeyarg>(3), B<xdr_cryptkeyres>(3), "
15728 "B<xdr_datum>(3), B<xdr_des_block>(3), B<xdr_domainname>(3), "
15729 "B<xdr_getcredres>(3), B<xdr_keybuf>(3), B<xdr_keystatus>(3), "
15730 "B<xdr_mapname>(3), B<xdr_netnamestr>(3), B<xdr_netobj>(3), B<xdr_passwd>(3), "
15731 "B<xdr_peername>(3), B<xdr_rmtcall_args>(3), B<xdr_rmtcallres>(3), "
15732 "B<xdr_unixcred>(3), B<xdr_yp_buf>(3), B<xdr_yp_inaddr>(3), "
15733 "B<xdr_ypbind_binding>(3), B<xdr_ypbind_resp>(3), B<xdr_ypbind_resptype>(3), "
15734 "B<xdr_ypbind_setdom>(3), B<xdr_ypdelete_args>(3), B<xdr_ypmaplist>(3), "
15735 "B<xdr_ypmaplist_str>(3), B<xdr_yppasswd>(3), B<xdr_ypreq_key>(3), "
15736 "B<xdr_ypreq_nokey>(3), B<xdr_ypresp_all>(3), B<xdr_ypresp_all_seq>(3), "
15737 "B<xdr_ypresp_key_val>(3), B<xdr_ypresp_maplist>(3), B<xdr_ypresp_master>(3), "
15738 "B<xdr_ypresp_order>(3), B<xdr_ypresp_val>(3), B<xdr_ypstat>(3), "
15739 "B<xdr_ypupdate_args>(3), B<yp_all>(3), B<yp_bind>(3), B<yperr_string>(3), "
15740 "B<yp_first>(3), B<yp_get_default_domain>(3), B<yp_maplist>(3), "
15741 "B<yp_master>(3), B<yp_match>(3), B<yp_next>(3), B<yp_order>(3), "
15742 "B<ypprot_err>(3), B<yp_unbind>(3), B<yp_update>(3)"
15746 #: build/C/man2/unimplemented.2:26
15748 msgid "UNIMPLEMENTED"
15752 #: build/C/man2/unimplemented.2:26
15757 #. type: Plain text
15758 #: build/C/man2/unimplemented.2:31
15760 "afs_syscall, break, fattach, fdetach, ftime, getmsg, getpmsg, gtty, "
15761 "isastream, lock, madvise1, mpx, prof, profil, putmsg, putpmsg, security, "
15762 "stty, tuxcall, ulimit, vserver - unimplemented system calls"
15765 #. type: Plain text
15766 #: build/C/man2/unimplemented.2:33
15767 msgid "Unimplemented system calls."
15770 #. type: Plain text
15771 #: build/C/man2/unimplemented.2:35
15772 msgid "These system calls are not implemented in the Linux kernel."
15775 #. type: Plain text
15776 #: build/C/man2/unimplemented.2:40
15777 msgid "These system calls always return -1 and set I<errno> to B<ENOSYS>."
15780 #. type: Plain text
15781 #: build/C/man2/unimplemented.2:47
15783 "Note that B<ftime>(3), B<profil>(3) and B<ulimit>(3) are implemented as "
15784 "library functions."
15787 #. type: Plain text
15788 #: build/C/man2/unimplemented.2:56
15790 "Some system calls, like B<alloc_hugepages>(2), B<free_hugepages>(2), "
15791 "B<ioperm>(2), B<iopl>(2), and B<vm86>(2) exist only on certain "
15795 #. type: Plain text
15796 #: build/C/man2/unimplemented.2:64
15798 "Some system calls, like B<ipc>(2), B<create_module>(2), B<init_module>(2), "
15799 "and B<delete_module>(2) exist only when the Linux kernel was built with "
15800 "support for them."
15803 #. type: Plain text
15804 #: build/C/man2/unimplemented.2:66
15805 msgid "B<syscalls>(2)"
15809 #: build/C/man7/units.7:26
15814 #. type: Plain text
15815 #: build/C/man7/units.7:29
15816 msgid "units, kilo, kibi, mega, mebi, giga, gibi - decimal and binary prefixes"
15820 #: build/C/man7/units.7:30
15822 msgid "Decimal prefixes"
15825 #. type: Plain text
15826 #: build/C/man7/units.7:34
15828 "The SI system of units uses prefixes that indicate powers of ten. A "
15829 "kilometer is 1000 meter, and a megawatt is 1000000 watt. Below the standard "
15834 #: build/C/man7/units.7:37 build/C/man7/units.7:79
15836 msgid "Prefix\tName\tValue\n"
15840 #: build/C/man7/units.7:38
15842 msgid "y\tyocto\t10^-24 = 0.000000000000000000000001\n"
15846 #: build/C/man7/units.7:39
15848 msgid "z\tzepto\t10^-21 = 0.000000000000000000001\n"
15852 #: build/C/man7/units.7:40
15854 msgid "a\tatto\t10^-18 = 0.000000000000000001\n"
15858 #: build/C/man7/units.7:41
15860 msgid "f\tfemto\t10^-15 = 0.000000000000001\n"
15864 #: build/C/man7/units.7:42
15866 msgid "p\tpico\t10^-12 = 0.000000000001\n"
15870 #: build/C/man7/units.7:43
15872 msgid "n\tnano\t10^-9 = 0.000000001\n"
15876 #: build/C/man7/units.7:44
15878 msgid "\\(mc\tmicro\t10^-6 = 0.000001\n"
15882 #: build/C/man7/units.7:45
15884 msgid "m\tmilli\t10^-3 = 0.001\n"
15888 #: build/C/man7/units.7:46
15890 msgid "c\tcenti\t10^-2 = 0.01\n"
15894 #: build/C/man7/units.7:47
15896 msgid "d\tdeci\t10^-1 = 0.1\n"
15900 #: build/C/man7/units.7:48
15902 msgid "da\tdeka\t10^ 1 = 10\n"
15906 #: build/C/man7/units.7:49
15908 msgid "h\thecto\t10^ 2 = 100\n"
15912 #: build/C/man7/units.7:50
15914 msgid "k\tkilo\t10^ 3 = 1000\n"
15918 #: build/C/man7/units.7:51
15920 msgid "M\tmega\t10^ 6 = 1000000\n"
15924 #: build/C/man7/units.7:52
15926 msgid "G\tgiga\t10^ 9 = 1000000000\n"
15930 #: build/C/man7/units.7:53
15932 msgid "T\ttera\t10^12 = 1000000000000\n"
15936 #: build/C/man7/units.7:54
15938 msgid "P\tpeta\t10^15 = 1000000000000000\n"
15942 #: build/C/man7/units.7:55
15944 msgid "E\texa\t10^18 = 1000000000000000000\n"
15948 #: build/C/man7/units.7:56
15950 msgid "Z\tzetta\t10^21 = 1000000000000000000000\n"
15954 #: build/C/man7/units.7:57
15956 msgid "Y\tyotta\t10^24 = 1000000000000000000000000\n"
15959 #. type: Plain text
15960 #: build/C/man7/units.7:64
15962 "The symbol for micro is the Greek letter mu, often written u in an ASCII "
15963 "context where this Greek letter is not available. See also"
15966 #. type: Plain text
15967 #: build/C/man7/units.7:68
15968 msgid "E<.UR http://physics.nist.gov\\:/cuu\\:/Units\\:/prefixes.html> E<.UE>"
15972 #: build/C/man7/units.7:69
15974 msgid "Binary prefixes"
15977 #. type: Plain text
15978 #: build/C/man7/units.7:76
15980 "The binary prefixes resemble the decimal ones, but have an additional "
15981 "\\(aqi\\(aq (and \"Ki\" starts with a capital \\(aqK\\(aq). The names are "
15982 "formed by taking the first syllable of the names of the decimal prefix with "
15983 "roughly the same size, followed by \"bi\" for \"binary\"."
15987 #: build/C/man7/units.7:80
15989 msgid "Ki\tkibi\t2^10 = 1024\n"
15993 #: build/C/man7/units.7:81
15995 msgid "Mi\tmebi\t2^20 = 1048576\n"
15999 #: build/C/man7/units.7:82
16001 msgid "Gi\tgibi\t2^30 = 1073741824\n"
16005 #: build/C/man7/units.7:83
16007 msgid "Ti\ttebi\t2^40 = 1099511627776\n"
16011 #: build/C/man7/units.7:84
16013 msgid "Pi\tpebi\t2^50 = 1125899906842624\n"
16017 #: build/C/man7/units.7:85
16019 msgid "Ei\texbi\t2^60 = 1152921504606846976\n"
16022 #. type: Plain text
16023 #: build/C/man7/units.7:90
16027 #. type: Plain text
16028 #: build/C/man7/units.7:93
16029 msgid "E<.UR http://physics.nist.gov\\:/cuu\\:/Units\\:/binary.html> E<.UE>"
16033 #: build/C/man7/units.7:93
16038 #. type: Plain text
16039 #: build/C/man7/units.7:98
16041 "Before these binary prefixes were introduced, it was fairly common to use "
16042 "k=1000 and K=1024, just like b=bit, B=byte. Unfortunately, the M is capital "
16043 "already, and cannot be capitalized to indicate binary-ness."
16046 #. type: Plain text
16047 #: build/C/man7/units.7:109
16049 "At first that didn't matter too much, since memory modules and disks came in "
16050 "sizes that were powers of two, so everyone knew that in such contexts "
16051 "\"kilobyte\" and \"megabyte\" meant 1024 and 1048576 bytes, respectively. "
16052 "What originally was a sloppy use of the prefixes \"kilo\" and \"mega\" "
16053 "started to become regarded as the \"real true meaning\" when computers were "
16054 "involved. But then disk technology changed, and disk sizes became arbitrary "
16055 "numbers. After a period of uncertainty all disk manufacturers settled on "
16056 "the standard, namely k=1000, M=1000k, G=1000M."
16059 #. also common: 14.4k modem
16060 #. type: Plain text
16061 #: build/C/man7/units.7:116
16063 "The situation was messy: in the 14k4 modems, k=1000; in the 1.44MB "
16064 "diskettes, M=1024000; and so on. In 1998 the IEC approved the standard that "
16065 "defines the binary prefixes given above, enabling people to be precise and "
16069 #. type: Plain text
16070 #: build/C/man7/units.7:118
16071 msgid "Thus, today, MB = 1000000B and MiB = 1048576B."
16074 #. type: Plain text
16075 #: build/C/man7/units.7:122
16077 "In the free software world programs are slowly being changed to conform. "
16078 "When the Linux kernel boots and says"
16081 #. type: Plain text
16082 #: build/C/man7/units.7:126
16084 msgid "hda: 120064896 sectors (61473 MB) w/2048KiB Cache\n"
16087 #. type: Plain text
16088 #: build/C/man7/units.7:130
16089 msgid "the MB are megabytes and the KiB are kibibytes."
16092 #. Copyright (c) 1990, 1993
16093 #. The Regents of the University of California. All rights reserved.
16095 #. %%%LICENSE_START(BSD_4_CLAUSE_UCB)
16096 #. Redistribution and use in source and binary forms, with or without
16097 #. modification, are permitted provided that the following conditions
16099 #. 1. Redistributions of source code must retain the above copyright
16100 #. notice, this list of conditions and the following disclaimer.
16101 #. 2. Redistributions in binary form must reproduce the above copyright
16102 #. notice, this list of conditions and the following disclaimer in the
16103 #. documentation and/or other materials provided with the distribution.
16104 #. 3. All advertising materials mentioning features or use of this software
16105 #. must display the following acknowledgement:
16106 #. This product includes software developed by the University of
16107 #. California, Berkeley and its contributors.
16108 #. 4. Neither the name of the University nor the names of its contributors
16109 #. may be used to endorse or promote products derived from this software
16110 #. without specific prior written permission.
16112 #. THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
16113 #. ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16114 #. IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16115 #. ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
16116 #. FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
16117 #. DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
16118 #. OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
16119 #. HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
16120 #. LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
16121 #. OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
16125 #. @(#)mdoc.samples.7 8.2 (Berkeley) 12/30/93
16126 #. $Id: mdoc.samples.7,v 1.17 1998/12/03 03:38:45 jkoshy Exp $
16128 #. This tutorial sampler invokes every macro in the package several
16129 #. times and is guaranteed to give a worst case performance
16130 #. for an already extremely slow package.
16132 #. String \*(Pu was not defined, probably means punctuation
16134 #: build/C/man7/mdoc.samples.7:42
16136 msgid "[ .,:;()[]?! ]"
16140 #: build/C/man7/mdoc.samples.7:43
16142 msgid "December 30, 1993"
16146 #: build/C/man7/mdoc.samples.7:45
16148 msgid "MDOC.SAMPLES 7"
16151 #. type: Plain text
16152 #: build/C/man7/mdoc.samples.7:48
16153 msgid "E<.Nm mdoc.samples>"
16157 #: build/C/man7/mdoc.samples.7:48
16159 msgid "tutorial sampler for writing"
16162 #. type: Plain text
16163 #: build/C/man7/mdoc.samples.7:52
16164 msgid "E<.Bx> manuals with E<.Nm \\-mdoc>"
16167 #. type: Plain text
16168 #: build/C/man7/mdoc.samples.7:54
16169 msgid "E<.Nm man mdoc.samples>"
16172 #. type: Plain text
16173 #: build/C/man7/mdoc.samples.7:100
16175 "A tutorial sampler for writing E<.Bx> manual pages with the E<.Nm \\-mdoc> "
16176 "macro package, a E<.Em content Ns \\-based> and E<.Em domain Ns \\-based> "
16177 "formatting package for E<.Xr troff 1>. Its predecessor, the E<.Xr \\-man 7> "
16178 "package, addressed page layout leaving the manipulation of fonts and other "
16179 "typesetting details to the individual author. In E<.Nm \\-mdoc>, page "
16180 "layout macros make up the E<.Em \"page structure domain\"> which consists of "
16181 "macros for titles, section headers, displays and lists. Essentially items "
16182 "which affect the physical position of text on a formatted page. In addition "
16183 "to the page structure domain, there are two more domains, the manual domain "
16184 "and the general text domain. The general text domain is defined as macros "
16185 "which perform tasks such as quoting or emphasizing pieces of text. The "
16186 "manual domain is defined as macros that are a subset of the day to day "
16187 "informal language used to describe commands, routines and related E<.Bx> "
16188 "files. Macros in the manual domain handle command names, command-line "
16189 "arguments and options, function names, function parameters, pathnames, "
16190 "variables, cross references to other manual pages, and so on. These domain "
16191 "items have value for both the author and the future user of the manual "
16192 "page. It is hoped the consistency gained across the manual set will provide "
16193 "easier translation to future documentation tools."
16196 #. type: Plain text
16197 #: build/C/man7/mdoc.samples.7:107
16199 "Throughout the E<.Ux> manual pages, a manual entry is simply referred to as "
16200 "a man page, regardless of actual length and without sexist intention."
16204 #: build/C/man7/mdoc.samples.7:107
16206 msgid "GETTING STARTED"
16209 #. type: Plain text
16210 #: build/C/man7/mdoc.samples.7:113
16212 "Since a tutorial document is normally read when a person desires to use the "
16213 "material immediately, the assumption has been made that the user of this "
16214 "document may be impatient. The material presented in the remained of this "
16215 "document is outlined as follows:"
16218 #. type: Plain text
16219 #: build/C/man7/mdoc.samples.7:116
16220 msgid "E<.Tn \"TROFF IDIOSYNCRASIES\">"
16224 #: build/C/man7/mdoc.samples.7:117
16226 msgid "\"Macro Usage\" ."
16230 #: build/C/man7/mdoc.samples.7:118
16232 msgid "\"Passing Space Characters in an Argument\" ."
16236 #: build/C/man7/mdoc.samples.7:119
16238 msgid "\"Trailing Blank Space Characters (a warning)\" ."
16242 #: build/C/man7/mdoc.samples.7:120
16244 msgid "\"Escaping Special Characters\" ."
16247 #. type: Plain text
16248 #: build/C/man7/mdoc.samples.7:124
16249 msgid "E<.Tn \"THE ANATOMY OF A MAN PAGE\">"
16253 #: build/C/man7/mdoc.samples.7:125
16255 msgid "\"A manual page template\" ."
16258 #. type: Plain text
16259 #: build/C/man7/mdoc.samples.7:129
16260 msgid "E<.Tn \"TITLE MACROS\">."
16263 #. type: Plain text
16264 #: build/C/man7/mdoc.samples.7:131
16265 msgid "E<.Tn \"INTRODUCTION OF MANUAL AND GENERAL TEXT DOMAINS\">."
16269 #: build/C/man7/mdoc.samples.7:132
16271 msgid "\"What's in a name...\" ."
16275 #: build/C/man7/mdoc.samples.7:133
16277 msgid "\"General Syntax\" ."
16280 #. type: Plain text
16281 #: build/C/man7/mdoc.samples.7:137
16282 msgid "E<.Tn \"MANUAL DOMAIN\">"
16286 #: build/C/man7/mdoc.samples.7:138
16288 msgid "Addresses ."
16292 #: build/C/man7/mdoc.samples.7:139
16294 msgid "\"Author name\" ."
16298 #: build/C/man7/mdoc.samples.7:140
16300 msgid "Arguments ."
16304 #: build/C/man7/mdoc.samples.7:141
16306 msgid "\"Configuration Declarations (section four only)\" ."
16310 #: build/C/man7/mdoc.samples.7:142
16312 msgid "\"Command Modifier\" ."
16316 #: build/C/man7/mdoc.samples.7:143
16318 msgid "\"Defined Variables\" ."
16322 #: build/C/man7/mdoc.samples.7:144
16324 msgid "\"Errno's (Section two only)\" ."
16328 #: build/C/man7/mdoc.samples.7:145
16330 msgid "\"Environment Variables\" ."
16334 #: build/C/man7/mdoc.samples.7:146
16336 msgid "\"Function Argument\" ."
16340 #: build/C/man7/mdoc.samples.7:147
16342 msgid "\"Function Declaration\" ."
16346 #: build/C/man7/mdoc.samples.7:148
16352 #: build/C/man7/mdoc.samples.7:149
16354 msgid "\"Functions (library routines)\" ."
16358 #: build/C/man7/mdoc.samples.7:150
16360 msgid "\"Function Types\" ."
16363 #. .It "Header File (including source code)" .
16365 #: build/C/man7/mdoc.samples.7:152
16367 msgid "\"Interactive Commands\" ."
16371 #: build/C/man7/mdoc.samples.7:153
16377 #: build/C/man7/mdoc.samples.7:154
16383 #: build/C/man7/mdoc.samples.7:155
16385 msgid "Pathnames ."
16389 #: build/C/man7/mdoc.samples.7:156
16391 msgid "Variables ."
16395 #: build/C/man7/mdoc.samples.7:157
16397 msgid "\"Cross References\" ."
16400 #. type: Plain text
16401 #: build/C/man7/mdoc.samples.7:161
16402 msgid "E<.Tn \"GENERAL TEXT DOMAIN\">"
16406 #: build/C/man7/mdoc.samples.7:162
16408 msgid "\"AT&T Macro\" ."
16412 #: build/C/man7/mdoc.samples.7:163
16414 msgid "\"BSD Macro\" ."
16418 #: build/C/man7/mdoc.samples.7:164
16420 msgid "\"FreeBSD Macro\" ."
16424 #: build/C/man7/mdoc.samples.7:165
16426 msgid "\"UNIX Macro\" ."
16430 #: build/C/man7/mdoc.samples.7:166
16432 msgid "Enclosure/Quoting Macros"
16436 #: build/C/man7/mdoc.samples.7:168
16438 msgid "\"Angle Bracket Quote/Enclosure\" ."
16442 #: build/C/man7/mdoc.samples.7:169
16444 msgid "\"Bracket Quotes/Enclosure\" ."
16448 #: build/C/man7/mdoc.samples.7:170
16450 msgid "\"Double Quote macro/Enclosure\" ."
16454 #: build/C/man7/mdoc.samples.7:171
16456 msgid "\"Parenthesis Quote/Enclosure\" ."
16460 #: build/C/man7/mdoc.samples.7:172
16462 msgid "\"Single Quotes/Enclosure\" ."
16466 #: build/C/man7/mdoc.samples.7:173
16468 msgid "\"Prefix Macro\" ."
16472 #: build/C/man7/mdoc.samples.7:175
16474 msgid "\"No\\-Op or Normal Text Macro\" ."
16478 #: build/C/man7/mdoc.samples.7:176
16480 msgid "\"No Space Macro\" ."
16484 #: build/C/man7/mdoc.samples.7:177
16486 msgid "\"Section Cross References\" ."
16490 #: build/C/man7/mdoc.samples.7:178
16492 msgid "\"References and Citations\" ."
16496 #: build/C/man7/mdoc.samples.7:179
16498 msgid "Return Values (sections two and three only)"
16502 #: build/C/man7/mdoc.samples.7:180
16504 msgid "\"Trade Names (Acronyms and Type Names)\" ."
16508 #: build/C/man7/mdoc.samples.7:181
16510 msgid "\"Extended Arguments\" ."
16513 #. type: Plain text
16514 #: build/C/man7/mdoc.samples.7:185
16515 msgid "E<.Tn \"PAGE STRUCTURE DOMAIN\">"
16519 #: build/C/man7/mdoc.samples.7:186
16521 msgid "\"Section Headers\" ."
16525 #: build/C/man7/mdoc.samples.7:187
16527 msgid "\"Paragraphs and Line Spacing\" ."
16531 #: build/C/man7/mdoc.samples.7:188
16537 #: build/C/man7/mdoc.samples.7:189
16543 #: build/C/man7/mdoc.samples.7:190
16545 msgid "\"Font Modes (Emphasis, Literal, and Symbolic)\" ."
16549 #: build/C/man7/mdoc.samples.7:191
16551 msgid "\"Lists and Columns\" ."
16554 #. type: Plain text
16555 #: build/C/man7/mdoc.samples.7:195
16556 msgid "E<.Tn \"PREDEFINED STRINGS\">"
16559 #. type: Plain text
16560 #: build/C/man7/mdoc.samples.7:197
16561 msgid "E<.Tn \"DIAGNOSTICS\">"
16564 #. type: Plain text
16565 #: build/C/man7/mdoc.samples.7:199
16566 msgid "E<.Tn \"FORMATTING WITH GROFF, TROFF AND NROFF\">"
16569 #. type: Plain text
16570 #: build/C/man7/mdoc.samples.7:201
16571 msgid "E<.Tn \"BUGS\">"
16575 #: build/C/man7/mdoc.samples.7:203
16577 msgid "TROFF IDIOSYNCRASIES"
16580 #. type: Plain text
16581 #: build/C/man7/mdoc.samples.7:217
16583 "The E<.Nm \\-mdoc> package attempts to simplify the process of writing a man "
16584 "page. Theoretically, one should not have to learn the dirty details of "
16585 "E<.Xr troff 1> to use E<.Nm \\-mdoc>; however, there are a few limitations "
16586 "which are unavoidable and best gotten out of the way. And, too, be "
16587 "forewarned, this package is E<.Em not> fast."
16591 #: build/C/man7/mdoc.samples.7:217
16593 msgid "Macro Usage"
16596 #. type: Plain text
16597 #: build/C/man7/mdoc.samples.7:242
16599 "As in E<.Xr troff 1>, a macro is called by placing a E<.Ql \\&.> (dot "
16600 "character) at the beginning of a line followed by the two character name "
16601 "for the macro. Arguments may follow the macro separated by spaces. It is "
16602 "the dot character at the beginning of the line which causes E<.Xr troff 1> "
16603 "to interpret the next two characters as a macro name. To place a E<.Ql "
16604 "\\&.> (dot character) at the beginning of a line in some context other than "
16605 "a macro invocation, precede the E<.Ql \\&.> (dot) with the E<.Ql \\e&> "
16606 "escape sequence. The E<.Ql \\e&> translates literally to a zero width "
16607 "space, and is never displayed in the output."
16610 #. type: Plain text
16611 #: build/C/man7/mdoc.samples.7:257
16613 "In general, E<.Xr troff 1> macros accept up to nine arguments, any extra "
16614 "arguments are ignored. Most macros in E<.Nm \\-mdoc> accept nine arguments "
16615 "and, in limited cases, arguments may be continued or extended on the next "
16616 "line (See E<.Sx Extensions>). A few macros handle quoted arguments (see "
16617 "E<.Sx Passing Space Characters in an Argument> below)."
16620 #. type: Plain text
16621 #: build/C/man7/mdoc.samples.7:284
16623 "Most of the E<.Nm \\-mdoc> general text domain and manual domain macros are "
16624 "special in that their argument lists are E<.Em parsed> for callable macro "
16625 "names. This means an argument on the argument list which matches a general "
16626 "text or manual domain macro name and is determined to be callable will be "
16627 "executed or called when it is processed. In this case, the argument, "
16628 "although the name of a macro, is not preceded by a E<.Ql \\&.> (dot). It is "
16629 "in this manner that many macros are nested; for example the option macro, "
16630 "E<.Ql \\&.Op>, may E<.Em call> the flag and argument macros, E<.Ql \\&Fl> "
16631 "and E<.Ql \\&Ar>, to specify an optional flag with an argument:"
16635 #: build/C/man7/mdoc.samples.7:285
16637 msgid "Op Fl s Ar bytes"
16640 #. type: Plain text
16641 #: build/C/man7/mdoc.samples.7:288
16642 msgid "is produced by E<.Li \\&.Op \\&Fl s \\&Ar bytes>"
16645 #. type: Plain text
16646 #: build/C/man7/mdoc.samples.7:295
16648 "To prevent a two character string from being interpreted as a macro name, "
16649 "precede the string with the escape sequence E<.Ql \\e&>:"
16653 #: build/C/man7/mdoc.samples.7:296
16655 msgid "Op \\&Fl s \\&Ar bytes"
16658 #. type: Plain text
16659 #: build/C/man7/mdoc.samples.7:299
16660 msgid "is produced by E<.Li \\&.Op \\e&Fl s \\e&Ar bytes>"
16663 #. type: Plain text
16664 #: build/C/man7/mdoc.samples.7:320
16666 "Here the strings E<.Ql \\&Fl> and E<.Ql \\&Ar> are not interpreted as "
16667 "macros. Macros whose argument lists are parsed for callable arguments are "
16668 "referred to as parsed and macros which may be called from an argument list "
16669 "are referred to as callable throughout this document and in the companion "
16670 "quick reference manual E<.Xr mdoc 7>. This is a technical E<.Em faux pas> "
16671 "as almost all of the macros in E<.Nm \\-mdoc> are parsed, but as it was "
16672 "cumbersome to constantly refer to macros as being callable and being able to "
16673 "call other macros, the term parsed has been used."
16677 #: build/C/man7/mdoc.samples.7:320
16679 msgid "Passing Space Characters in an Argument"
16682 #. type: Plain text
16683 #: build/C/man7/mdoc.samples.7:338
16685 "Sometimes it is desirable to give as one argument a string containing one or "
16686 "more blank space characters. This may be necessary to defeat the nine "
16687 "argument limit or to specify arguments to macros which expect particular "
16688 "arrangement of items in the argument list. For example, the function macro "
16689 "E<.Ql \\&.Fn> expects the first argument to be the name of a function and "
16690 "any remaining arguments to be function parameters. As E<.Tn \"ANSI C\"> "
16691 "stipulates the declaration of function parameters in the parenthesized "
16692 "parameter list, each parameter is guaranteed to be at minimum a two word "
16693 "string. For example, E<.Fa int foo>."
16696 #. type: Plain text
16697 #: build/C/man7/mdoc.samples.7:353
16699 "There are two possible ways to pass an argument which contains an embedded "
16700 "space. E<.Em Implementation note>: Unfortunately, the most convenient way "
16701 "of passing spaces in between quotes by reassigning individual arguments "
16702 "before parsing was fairly expensive speed wise and space wise to implement "
16703 "in all the macros for E<.Tn AT&T> E<.Xr troff>. It is not expensive for "
16704 "E<.Xr groff> but for the sake of portability, has been limited to the "
16705 "following macros which need it the most:"
16709 #: build/C/man7/mdoc.samples.7:355
16714 #. type: Plain text
16715 #: build/C/man7/mdoc.samples.7:358
16716 msgid "Configuration declaration (section 4 E<.Sx SYNOPSIS>)"
16720 #: build/C/man7/mdoc.samples.7:358
16725 #. type: Plain text
16726 #: build/C/man7/mdoc.samples.7:360
16727 msgid "Begin list (for the width specifier)."
16731 #: build/C/man7/mdoc.samples.7:360
16736 #. type: Plain text
16737 #: build/C/man7/mdoc.samples.7:362
16738 msgid "Emphasized text."
16742 #: build/C/man7/mdoc.samples.7:362
16747 #. type: Plain text
16748 #: build/C/man7/mdoc.samples.7:364
16749 msgid "Functions (sections two and four)."
16753 #: build/C/man7/mdoc.samples.7:364
16758 #. type: Plain text
16759 #: build/C/man7/mdoc.samples.7:366
16760 msgid "List items."
16764 #: build/C/man7/mdoc.samples.7:366
16769 #. type: Plain text
16770 #: build/C/man7/mdoc.samples.7:368
16771 msgid "Literal text."
16775 #: build/C/man7/mdoc.samples.7:368
16780 #. type: Plain text
16781 #: build/C/man7/mdoc.samples.7:370
16782 msgid "Symbolic text."
16786 #: build/C/man7/mdoc.samples.7:370
16791 #. type: Plain text
16792 #: build/C/man7/mdoc.samples.7:372
16793 msgid "Book titles."
16797 #: build/C/man7/mdoc.samples.7:372
16802 #. type: Plain text
16803 #: build/C/man7/mdoc.samples.7:374
16804 msgid "Journal names."
16808 #: build/C/man7/mdoc.samples.7:374
16813 #. type: Plain text
16814 #: build/C/man7/mdoc.samples.7:376
16815 msgid "Optional notes for a reference."
16819 #: build/C/man7/mdoc.samples.7:376
16824 #. type: Plain text
16825 #: build/C/man7/mdoc.samples.7:378
16826 msgid "Report title (in a reference)."
16830 #: build/C/man7/mdoc.samples.7:378
16835 #. type: Plain text
16836 #: build/C/man7/mdoc.samples.7:380
16837 msgid "Title of article in a book or journal."
16840 #. type: Plain text
16841 #: build/C/man7/mdoc.samples.7:397
16843 "One way of passing a string containing blank spaces is to use the hard or "
16844 "unpaddable space character E<.Ql \\e\\ >, that is, a blank space preceded by "
16845 "the escape character E<.Ql \\e>. This method may be used with any macro but "
16846 "has the side effect of interfering with the adjustment of text over the "
16847 "length of a line. E<.Xr Troff> sees the hard space as if it were any other "
16848 "printable character and cannot split the string into blank or newline "
16849 "separated pieces as one would expect. The method is useful for strings "
16850 "which are not expected to overlap a line boundary. For example:"
16854 #: build/C/man7/mdoc.samples.7:398
16856 msgid "Fn fetch char\\ *str"
16859 #. type: Plain text
16860 #: build/C/man7/mdoc.samples.7:401
16861 msgid "is created by E<.Ql \\&.Fn fetch char\\e *str>"
16865 #: build/C/man7/mdoc.samples.7:401
16867 msgid "Fn fetch \"char *str\""
16870 #. type: Plain text
16871 #: build/C/man7/mdoc.samples.7:404
16872 msgid "can also be created by E<.Ql \\&.Fn fetch \"\\*qchar *str\\*q\">"
16875 #. type: Plain text
16876 #: build/C/man7/mdoc.samples.7:413
16878 "If the E<.Ql \\e> or quotes were omitted, E<.Ql \\&.Fn> would see three "
16879 "arguments and the result would be:"
16883 #: build/C/man7/mdoc.samples.7:414
16885 msgid "Fn fetch char *str"
16888 #. type: Plain text
16889 #: build/C/man7/mdoc.samples.7:420
16891 "For an example of what happens when the parameter list overlaps a newline "
16892 "boundary, see the E<.Sx BUGS> section."
16896 #: build/C/man7/mdoc.samples.7:420
16898 msgid "Trailing Blank Space Characters"
16901 #. type: Plain text
16902 #: build/C/man7/mdoc.samples.7:433
16904 "E<.Xr Troff> can be confused by blank space characters at the end of a "
16905 "line. It is a wise preventive measure to globally remove all blank spaces "
16906 "from E<lt>blank-spaceE<gt>E<lt>end-of-lineE<gt> character sequences. Should "
16907 "the need arise to force a blank character at the end of a line, it may be "
16908 "forced with an unpaddable space and the E<.Ql \\e&> escape character. For "
16909 "example, E<.Ql string\\e\\ \\e&>."
16913 #: build/C/man7/mdoc.samples.7:433
16915 msgid "Escaping Special Characters"
16918 #. type: Plain text
16919 #: build/C/man7/mdoc.samples.7:445
16921 "Special characters like the newline character E<.Ql \\en>, are handled by "
16922 "replacing the E<.Ql \\e> with E<.Ql \\ee> (e.g., E<.Ql \\een>) to preserve "
16927 #: build/C/man7/mdoc.samples.7:445
16929 msgid "THE ANATOMY OF A MAN PAGE"
16932 #. type: Plain text
16933 #: build/C/man7/mdoc.samples.7:452
16935 "The body of a man page is easily constructed from a basic template found in "
16936 "the file E<.Pa /usr/share/misc/mdoc.template>. Several example man pages "
16937 "can also be found in E<.Pa /usr/share/examples/mdoc>."
16941 #: build/C/man7/mdoc.samples.7:453
16943 msgid "A manual page template"
16946 #. type: Plain text
16947 #: build/C/man7/mdoc.samples.7:484
16950 "\\&.\\e\" The following requests are required for all man pages.\n"
16951 "\\&.Dd Month day, year\n"
16952 "\\&.Os OPERATING_SYSTEM [version/release]\n"
16953 "\\&.Dt DOCUMENT_TITLE [section number] [volume]\n"
16956 "\\&.Nd one line description of name\n"
16957 "\\&.Sh SYNOPSIS\n"
16958 "\\&.Sh DESCRIPTION\n"
16959 "\\&.\\e\" The following requests should be uncommented and\n"
16960 "\\&.\\e\" used where appropriate. This next request is\n"
16961 "\\&.\\e\" for sections 2 and 3 function return values only.\n"
16962 "\\&.\\e\" .Sh RETURN VALUE\n"
16963 "\\&.\\e\" This next request is for sections 1, 6, 7 & 8 only\n"
16964 "\\&.\\e\" .Sh ENVIRONMENT\n"
16965 "\\&.\\e\" .Sh FILES\n"
16966 "\\&.\\e\" .Sh EXAMPLES\n"
16967 "\\&.\\e\" This next request is for sections 1, 6, 7 & 8 only\n"
16968 "\\&.\\e\" (command return values (to shell) and\n"
16969 "\\&.\\e\"\t fprintf/stderr type diagnostics)\n"
16970 "\\&.\\e\" .Sh DIAGNOSTICS\n"
16971 "\\&.\\e\" The next request is for sections 2 and 3 error\n"
16972 "\\&.\\e\" and signal handling only.\n"
16973 "\\&.\\e\" .Sh ERRORS\n"
16974 "\\&.\\e\" .Sh SEE ALSO\n"
16975 "\\&.\\e\" .Sh CONFORMING TO\n"
16976 "\\&.\\e\" .Sh HISTORY\n"
16977 "\\&.\\e\" .Sh AUTHORS\n"
16978 "\\&.\\e\" .Sh BUGS\n"
16981 #. type: Plain text
16982 #: build/C/man7/mdoc.samples.7:498
16984 "The first items in the template are the macros E<.Pq Li \\&.Dd , \\&.Os , "
16985 "\\&.Dt>; the document date, the operating system the man page or subject "
16986 "source is developed or modified for, and the man page title E<.Pq Em in "
16987 "uppercase> along with the section of the manual the page belongs in. These "
16988 "macros identify the page, and are discussed below in E<.Sx TITLE MACROS>."
16991 #. type: Plain text
16992 #: build/C/man7/mdoc.samples.7:517
16994 "The remaining items in the template are section headers E<.Pq Li \\&.Sh>; of "
16995 "which E<.Sx NAME>, E<.Sx SYNOPSIS> and E<.Sx DESCRIPTION> are mandatory. "
16996 "The headers are discussed in E<.Sx PAGE STRUCTURE DOMAIN>, after "
16997 "presentation of E<.Sx MANUAL DOMAIN>. Several content macros are used to "
16998 "demonstrate page layout macros; reading about content macros before page "
16999 "layout macros is recommended."
17003 #: build/C/man7/mdoc.samples.7:517
17005 msgid "TITLE MACROS"
17008 #. type: Plain text
17009 #: build/C/man7/mdoc.samples.7:526
17011 "The title macros are the first portion of the page structure domain, but are "
17012 "presented first and separate for someone who wishes to start writing a man "
17013 "page yesterday. Three header macros designate the document title or manual "
17014 "page title, the operating system, and the date of authorship. These macros "
17015 "are one called once at the very beginning of the document and are used to "
17016 "construct the headers and footers only."
17020 #: build/C/man7/mdoc.samples.7:527
17022 msgid "Li \\&.Dt DOCUMENT_TITLE section# [volume]"
17026 #. USD UNIX User's Supplementary Documents
17028 #. PS1 UNIX Programmer's Supplementary Documents
17029 #. type: Plain text
17030 #: build/C/man7/mdoc.samples.7:541
17032 "The document title is the subject of the man page and must be in E<.Tn "
17033 "CAPITALS> due to troff limitations. The section number may be 1,\\ ...,\\ "
17034 "8, and if it is specified, the volume title may be omitted. A volume title "
17035 "may be arbitrary or one of the following:"
17039 #: build/C/man7/mdoc.samples.7:543
17041 msgid "Li \"AMD\tUNIX Ancestral Manual Documents\""
17045 #: build/C/man7/mdoc.samples.7:544
17047 msgid "Li \"SMM\tUNIX System Manager's Manual\""
17051 #: build/C/man7/mdoc.samples.7:545
17053 msgid "Li \"URM\tUNIX Reference Manual\""
17057 #: build/C/man7/mdoc.samples.7:546
17059 msgid "Li \"PRM\tUNIX Programmer's Manual\""
17063 #. MMI UNIX Manual Master Index
17065 #. CON UNIX Contributed Software Manual
17067 #. LOC UNIX Local Manual
17068 #. type: Plain text
17069 #: build/C/man7/mdoc.samples.7:562
17071 "The default volume labeling is E<.Li URM> for sections 1, 6, and 7; E<.Li "
17072 "SMM> for section 8; E<.Li PRM> for sections 2, 3, 4, and 5."
17076 #: build/C/man7/mdoc.samples.7:562
17078 msgid "Li \\&.Os operating_system release#"
17081 #. type: Plain text
17082 #: build/C/man7/mdoc.samples.7:575
17084 "The name of the operating system should be the common acronym, for example, "
17085 "E<.Tn BSD> or E<.Tn FreeBSD> or E<.Tn ATT>. The release should be the "
17086 "standard release nomenclature for the system specified, for example, 4.3, "
17087 "4.3+Tahoe, V.3, V.4. Unrecognized arguments are displayed as given in the "
17088 "page footer. For instance, a typical footer might be:"
17092 #: build/C/man7/mdoc.samples.7:576
17094 msgid "\\&.Os 4.3BSD"
17097 #. type: Plain text
17098 #: build/C/man7/mdoc.samples.7:579
17103 #: build/C/man7/mdoc.samples.7:579
17105 msgid "\\&.Os FreeBSD 2.2"
17108 #. type: Plain text
17109 #: build/C/man7/mdoc.samples.7:582
17110 msgid "or for a locally produced set"
17114 #: build/C/man7/mdoc.samples.7:583
17116 msgid "\\&.Os CS Department"
17119 #. type: Plain text
17120 #: build/C/man7/mdoc.samples.7:598
17122 "The Berkeley default, E<.Ql \\&.Os> without an argument, has been defined as "
17123 "E<.Tn BSD> in the site-specific file E<.Pa "
17124 "/usr/share/tmac/mdoc/doc-common>. It really should default to E<.Tn "
17125 "LOCAL>. Note, if the E<.Ql \\&.Os> macro is not present, the bottom left "
17126 "corner of the page will be ugly."
17130 #: build/C/man7/mdoc.samples.7:598
17132 msgid "Li \\&.Dd month day, year"
17135 #. type: Plain text
17136 #: build/C/man7/mdoc.samples.7:600
17137 msgid "The date should be written formally:"
17141 #: build/C/man7/mdoc.samples.7:602
17143 msgid "January 25, 1989"
17147 #: build/C/man7/mdoc.samples.7:604
17149 msgid "INTRODUCTION OF MANUAL AND GENERAL TEXT DOMAINS"
17153 #: build/C/man7/mdoc.samples.7:605
17155 msgid "What's in a name..."
17158 #. type: Plain text
17159 #: build/C/man7/mdoc.samples.7:622
17161 "The manual domain macro names are derived from the day to day informal "
17162 "language used to describe commands, subroutines and related files. Slightly "
17163 "different variations of this language are used to describe the three "
17164 "different aspects of writing a man page. First, there is the description of "
17165 "E<.Nm \\-mdoc> macro request usage. Second is the description of a E<.Ux> "
17166 "command E<.Em with> E<.Nm \\-mdoc> macros and third, the description of a "
17167 "command to a user in the verbal sense; that is, discussion of a command in "
17168 "the text of a man page."
17171 #. type: Plain text
17172 #: build/C/man7/mdoc.samples.7:627
17174 "In the first case, E<.Xr troff 1> macros are themselves a type of command; "
17175 "the general syntax for a troff command is:"
17178 #. type: Plain text
17179 #: build/C/man7/mdoc.samples.7:629
17181 msgid "\\&.Va argument1 argument2 ... argument9\n"
17184 #. type: Plain text
17185 #: build/C/man7/mdoc.samples.7:643
17187 "The E<.Ql \\&.Va> is a macro command or request, and anything following it "
17188 "is an argument to be processed. In the second case, the description of a "
17189 "E<.Ux> command using the content macros is a bit more involved; a typical "
17190 "E<.Sx SYNOPSIS> command line might be displayed as:"
17193 #. type: Plain text
17194 #: build/C/man7/mdoc.samples.7:647
17199 "E<.Ar infile outfile>\n"
17202 #. type: Plain text
17203 #: build/C/man7/mdoc.samples.7:667
17205 "Here, E<.Nm filter> is the command name and the bracketed string E<.Fl flag> "
17206 "is a E<.Em flag> argument designated as optional by the option brackets. In "
17207 "E<.Nm \\-mdoc> terms, E<.Ar infile> and E<.Ar outfile> are called E<.Em "
17208 "arguments>. The macros which formatted the above example:"
17211 #. type: Plain text
17212 #: build/C/man7/mdoc.samples.7:671
17216 "\\&.Op \\&Fl flag\n"
17217 "\\&.Ar infile outfile\n"
17220 #. type: Plain text
17221 #: build/C/man7/mdoc.samples.7:685
17223 "In the third case, discussion of commands and command syntax includes both "
17224 "examples above, but may add more detail. The arguments E<.Ar infile> and "
17225 "E<.Ar outfile> from the example above might be referred to as E<.Em "
17226 "operands> or E<.Em file arguments>. Some command-line argument lists are "
17231 #: build/C/man7/mdoc.samples.7:686
17236 #. type: Plain text
17237 #: build/C/man7/mdoc.samples.7:699
17239 "E<.Op Fl eiknqrstv> E<.Op Fl D Ar variable> E<.Op Fl d Ar flags> E<.Op Fl f "
17240 "Ar makefile> E<.Bk -words> E<.Op Fl I Ar directory> E<.Ek> E<.Op Fl j Ar "
17241 "max_jobs> E<.Op Ar variable=value> E<.Bk -words> E<.Op Ar target ...> E<.Ek>"
17244 #. type: Plain text
17245 #: build/C/man7/mdoc.samples.7:725
17247 "Here one might talk about the command E<.Nm make> and qualify the argument "
17248 "E<.Ar makefile>, as an argument to the flag, E<.Fl f>, or discuss the "
17249 "optional file operand E<.Ar target>. In the verbal context, such detail can "
17250 "prevent confusion, however the E<.Nm \\-mdoc> package does not have a macro "
17251 "for an argument E<.Em to> a flag. Instead the E<.Ql \\&Ar> argument macro "
17252 "is used for an operand or file argument like E<.Ar target> as well as an "
17253 "argument to a flag like E<.Ar variable>. The make command line was produced "
17257 #. type: Plain text
17258 #: build/C/man7/mdoc.samples.7:737
17262 "\\&.Op Fl eiknqrstv\n"
17263 "\\&.Op Fl D Ar variable\n"
17264 "\\&.Op Fl d Ar flags\n"
17265 "\\&.Op Fl f Ar makefile\n"
17266 "\\&.Op Fl I Ar directory\n"
17267 "\\&.Op Fl j Ar max_jobs\n"
17268 "\\&.Op Ar variable=value\n"
17270 "\\&.Op Ar target ...\n"
17274 #. type: Plain text
17275 #: build/C/man7/mdoc.samples.7:745
17276 msgid "The E<.Ql \\&.Bk> and E<.Ql \\&.Ek> macros are explained in E<.Sx Keeps>."
17280 #: build/C/man7/mdoc.samples.7:745
17282 msgid "General Syntax"
17285 #. type: Plain text
17286 #: build/C/man7/mdoc.samples.7:768
17288 "The manual domain and general text domain macros share a similar syntax with "
17289 "a few minor deviations: E<.Ql \\&.Ar>, E<.Ql \\&.Fl>, E<.Ql \\&.Nm>, and "
17290 "E<.Ql \\&.Pa> differ only when called without arguments; E<.Ql \\&.Fn> and "
17291 "E<.Ql \\&.Xr> impose an order on their argument lists and the E<.Ql \\&.Op> "
17292 "and E<.Ql \\&.Fn> macros have nesting limitations. All content macros are "
17293 "capable of recognizing and properly handling punctuation, provided each "
17294 "punctuation character is separated by a leading space. If a request is "
17299 #: build/C/man7/mdoc.samples.7:769
17301 msgid "\\&.Li sptr, ptr),"
17304 #. type: Plain text
17305 #: build/C/man7/mdoc.samples.7:772 build/C/man7/mdoc.samples.7:782
17306 msgid "The result is:"
17310 #: build/C/man7/mdoc.samples.7:773
17312 msgid "Li sptr, ptr),"
17315 #. type: Plain text
17316 #: build/C/man7/mdoc.samples.7:778
17318 "The punctuation is not recognized and all is output in the literal font. If "
17319 "the punctuation is separated by a leading white space:"
17323 #: build/C/man7/mdoc.samples.7:779
17325 msgid "\\&.Li \"sptr , ptr ) ,\""
17329 #: build/C/man7/mdoc.samples.7:783
17331 msgid "Li sptr , ptr ) ,"
17334 #. type: Plain text
17335 #: build/C/man7/mdoc.samples.7:787
17337 "The punctuation is now recognized and is output in the default font "
17338 "distinguishing it from the strings in literal font."
17341 #. type: Plain text
17342 #: build/C/man7/mdoc.samples.7:796
17344 "To remove the special meaning from a punctuation character escape it with "
17345 "E<.Ql \\e&>. E<.Xr Troff> is limited as a macro language, and has "
17346 "difficulty when presented with a string containing a member of the "
17347 "mathematical, logical or quotation set:"
17350 #. type: Plain text
17351 #: build/C/man7/mdoc.samples.7:798
17353 msgid "\\&{+,\\-,/,*,\\&%,E<lt>,E<gt>,E<lt>=,E<gt>=,=,==,&,`,',\"}\n"
17356 #. type: Plain text
17357 #: build/C/man7/mdoc.samples.7:810
17359 "The problem is that E<.Xr troff> may assume it is supposed to actually "
17360 "perform the operation or evaluation suggested by the characters. To prevent "
17361 "the accidental evaluation of these characters, escape them with E<.Ql "
17362 "\\e&>. Typical syntax is shown in the first content macro displayed below, "
17367 #: build/C/man7/mdoc.samples.7:810
17369 msgid "MANUAL DOMAIN"
17373 #: build/C/man7/mdoc.samples.7:811
17375 msgid "Address Macro"
17378 #. type: Plain text
17379 #: build/C/man7/mdoc.samples.7:814
17381 "The address macro identifies an address construct of the form "
17382 "addr1[,addr2[,addr3]]."
17386 #: build/C/man7/mdoc.samples.7:815
17388 msgid "Usage: .Ad address ... \\*(Pu"
17392 #: build/C/man7/mdoc.samples.7:817
17394 msgid "Li \\&.Ad addr1"
17397 #. type: Plain text
17398 #: build/C/man7/mdoc.samples.7:819
17399 msgid "E<.Ad addr1>"
17403 #: build/C/man7/mdoc.samples.7:819
17405 msgid "Li \\&.Ad addr1\\ ."
17408 #. type: Plain text
17409 #: build/C/man7/mdoc.samples.7:821
17410 msgid "E<.Ad addr1>."
17414 #: build/C/man7/mdoc.samples.7:821
17416 msgid "Li \\&.Ad addr1\\ , file2"
17419 #. type: Plain text
17420 #: build/C/man7/mdoc.samples.7:823
17421 msgid "E<.Ad addr1 , file2>"
17425 #: build/C/man7/mdoc.samples.7:823
17427 msgid "Li \\&.Ad f1\\ , f2\\ , f3\\ :"
17430 #. type: Plain text
17431 #: build/C/man7/mdoc.samples.7:825
17432 msgid "E<.Ad f1 , f2 , f3>:"
17436 #: build/C/man7/mdoc.samples.7:825
17438 msgid "Li \\&.Ad addr\\ )\\ )\\ ,"
17441 #. type: Plain text
17442 #: build/C/man7/mdoc.samples.7:827
17443 msgid "E<.Ad addr>)),"
17446 #. type: Plain text
17447 #: build/C/man7/mdoc.samples.7:834
17449 "It is an error to call E<.Ql \\&.Ad> without arguments. E<.Ql \\&.Ad> is "
17450 "callable by other macros and is parsed."
17454 #: build/C/man7/mdoc.samples.7:834
17456 msgid "Author Name"
17459 #. type: Plain text
17460 #: build/C/man7/mdoc.samples.7:841
17462 "The E<.Ql \\&.An> macro is used to specify the name of the author of the "
17463 "item being documented, or the name of the author of the actual manual page. "
17464 "Any remaining arguments after the name information are assumed to be "
17469 #: build/C/man7/mdoc.samples.7:842
17471 msgid "Usage: .An author_name \\*(Pu"
17475 #: build/C/man7/mdoc.samples.7:844
17477 msgid "Li \\&.An Joe\\ Author"
17480 #. type: Plain text
17481 #: build/C/man7/mdoc.samples.7:846
17482 msgid "E<.An Joe Author>"
17486 #: build/C/man7/mdoc.samples.7:846
17488 msgid "Li \\&.An Joe\\ Author\\ ,"
17491 #. type: Plain text
17492 #: build/C/man7/mdoc.samples.7:848
17493 msgid "E<.An Joe\\ Author>,"
17497 #: build/C/man7/mdoc.samples.7:848
17499 msgid "Li \\&.An Joe\\ Author\\ \\&Aq\\ nobody@FreeBSD.ORG"
17502 #. type: Plain text
17503 #: build/C/man7/mdoc.samples.7:850
17504 msgid "E<.An Joe Author Aq nobody@FreeBSD.ORG>"
17508 #: build/C/man7/mdoc.samples.7:850
17510 msgid "Li \\&.An Joe\\ Author\\ )\\ )\\ ,"
17513 #. type: Plain text
17514 #: build/C/man7/mdoc.samples.7:852
17515 msgid "E<.An Joe Author>)),"
17518 #. type: Plain text
17519 #: build/C/man7/mdoc.samples.7:861
17521 "The E<.Ql \\&.An> macro is parsed and is callable. It is an error to call "
17522 "E<.Ql \\&.An> without any arguments."
17526 #: build/C/man7/mdoc.samples.7:861
17528 msgid "Argument Macro"
17531 #. type: Plain text
17532 #: build/C/man7/mdoc.samples.7:866
17534 "The E<.Ql \\&.Ar> argument macro may be used whenever a command-line "
17535 "argument is referenced."
17539 #: build/C/man7/mdoc.samples.7:867
17541 msgid "Usage: .Ar argument ... \\*(Pu"
17545 #: build/C/man7/mdoc.samples.7:869
17550 #. type: Plain text
17551 #: build/C/man7/mdoc.samples.7:871
17556 #: build/C/man7/mdoc.samples.7:871
17558 msgid "Li \\&.Ar file1"
17561 #. type: Plain text
17562 #: build/C/man7/mdoc.samples.7:873
17563 msgid "E<.Ar file1>"
17567 #: build/C/man7/mdoc.samples.7:873
17569 msgid "Li \\&.Ar file1\\ ."
17572 #. type: Plain text
17573 #: build/C/man7/mdoc.samples.7:875
17574 msgid "E<.Ar file1>."
17578 #: build/C/man7/mdoc.samples.7:875
17580 msgid "Li \\&.Ar file1 file2"
17583 #. type: Plain text
17584 #: build/C/man7/mdoc.samples.7:877
17585 msgid "E<.Ar file1 file2>"
17589 #: build/C/man7/mdoc.samples.7:877
17591 msgid "Li \\&.Ar f1 f2 f3\\ :"
17594 #. type: Plain text
17595 #: build/C/man7/mdoc.samples.7:879
17596 msgid "E<.Ar f1 f2 f3>:"
17600 #: build/C/man7/mdoc.samples.7:879
17602 msgid "Li \\&.Ar file\\ )\\ )\\ ,"
17605 #. type: Plain text
17606 #: build/C/man7/mdoc.samples.7:881
17607 msgid "E<.Ar file>)),"
17610 #. type: Plain text
17611 #: build/C/man7/mdoc.samples.7:891
17613 "If E<.Ql \\&.Ar> is called without arguments, E<.Ql \\&Ar> is assumed. The "
17614 "E<.Ql \\&.Ar> macro is parsed and is callable."
17618 #: build/C/man7/mdoc.samples.7:891
17620 msgid "Configuration Declaration (section four only)"
17623 #. type: Plain text
17624 #: build/C/man7/mdoc.samples.7:898
17626 "The E<.Ql \\&.Cd> macro is used to demonstrate a E<.Xr config 8> declaration "
17627 "for a device interface in a section four manual. This macro accepts quoted "
17628 "arguments (double quotes only)."
17632 #: build/C/man7/mdoc.samples.7:900
17634 msgid "Cd \"device le0 at scode?\""
17637 #. type: Plain text
17638 #: build/C/man7/mdoc.samples.7:903
17639 msgid "produced by: E<.Ql \".Cd device le0 at scode?\">."
17643 #: build/C/man7/mdoc.samples.7:904
17645 msgid "Command Modifier"
17648 #. type: Plain text
17649 #: build/C/man7/mdoc.samples.7:918
17651 "The command modifier is identical to the E<.Ql \\&.Fl> (flag) command with "
17652 "the exception the E<.Ql \\&.Cm> macro does not assert a dash in front of "
17653 "every argument. Traditionally flags are marked by the preceding dash, some "
17654 "commands or subsets of commands do not use them. Command modifiers may also "
17655 "be specified in conjunction with interactive commands such as editor "
17656 "commands. See E<.Sx Flags>."
17660 #: build/C/man7/mdoc.samples.7:918
17662 msgid "Defined Variables"
17665 #. type: Plain text
17666 #: build/C/man7/mdoc.samples.7:922
17668 "A variable which is defined in an include file is specified by the macro "
17673 #: build/C/man7/mdoc.samples.7:923
17675 msgid "Usage: .Dv defined_variable ... \\*(Pu"
17679 #: build/C/man7/mdoc.samples.7:925
17681 msgid "Li \".Dv MAXHOSTNAMELEN\""
17684 #. type: Plain text
17685 #: build/C/man7/mdoc.samples.7:927
17686 msgid "E<.Dv MAXHOSTNAMELEN>"
17690 #: build/C/man7/mdoc.samples.7:927
17692 msgid "Li \".Dv TIOCGPGRP )\""
17695 #. type: Plain text
17696 #: build/C/man7/mdoc.samples.7:929
17697 msgid "E<.Dv TIOCGPGRP>)"
17700 #. type: Plain text
17701 #: build/C/man7/mdoc.samples.7:936
17703 "It is an error to call E<.Ql \\&.Dv> without arguments. E<.Ql \\&.Dv> is "
17704 "parsed and is callable."
17708 #: build/C/man7/mdoc.samples.7:936
17710 msgid "Errno's (Section two only)"
17713 #. type: Plain text
17714 #: build/C/man7/mdoc.samples.7:948
17716 "The E<.Ql \\&.Er> errno macro specifies the error return value for section "
17717 "two library routines. The second example below shows E<.Ql \\&.Er> used "
17718 "with the E<.Ql \\&.Bq> general text domain macro, as it would be used in a "
17719 "section two manual page."
17723 #: build/C/man7/mdoc.samples.7:949
17725 msgid "Usage: .Er ERRNOTYPE ... \\*(Pu"
17729 #: build/C/man7/mdoc.samples.7:951
17731 msgid "Li \\&.Er ENOENT"
17734 #. type: Plain text
17735 #: build/C/man7/mdoc.samples.7:953
17736 msgid "E<.Er ENOENT>"
17740 #: build/C/man7/mdoc.samples.7:953
17742 msgid "Li \\&.Er ENOENT\\ )\\ ;"
17745 #. type: Plain text
17746 #: build/C/man7/mdoc.samples.7:955
17747 msgid "E<.Er ENOENT>);"
17751 #: build/C/man7/mdoc.samples.7:955
17753 msgid "Li \\&.Bq \\&Er ENOTDIR"
17756 #. type: Plain text
17757 #: build/C/man7/mdoc.samples.7:957
17758 msgid "E<.Bq Er ENOTDIR>"
17761 #. type: Plain text
17762 #: build/C/man7/mdoc.samples.7:965
17764 "It is an error to call E<.Ql \\&.Er> without arguments. The E<.Ql \\&.Er> "
17765 "macro is parsed and is callable."
17769 #: build/C/man7/mdoc.samples.7:965
17771 msgid "Environment Variables"
17774 #. type: Plain text
17775 #: build/C/man7/mdoc.samples.7:969
17776 msgid "The E<.Ql \\&.Ev> macro specifies an environment variable."
17780 #: build/C/man7/mdoc.samples.7:970
17782 msgid "Usage: .Ev argument ... \\*(Pu"
17786 #: build/C/man7/mdoc.samples.7:972
17788 msgid "Li \\&.Ev DISPLAY"
17791 #. type: Plain text
17792 #: build/C/man7/mdoc.samples.7:974
17793 msgid "E<.Ev DISPLAY>"
17797 #: build/C/man7/mdoc.samples.7:974
17799 msgid "Li \\&.Ev PATH\\ ."
17802 #. type: Plain text
17803 #: build/C/man7/mdoc.samples.7:976
17804 msgid "E<.Ev PATH>."
17808 #: build/C/man7/mdoc.samples.7:976
17810 msgid "Li \\&.Ev PRINTER\\ )\\ )\\ ,"
17813 #. type: Plain text
17814 #: build/C/man7/mdoc.samples.7:978
17815 msgid "E<.Ev PRINTER>)),"
17818 #. type: Plain text
17819 #: build/C/man7/mdoc.samples.7:986
17821 "It is an error to call E<.Ql \\&.Ev> without arguments. The E<.Ql \\&.Ev> "
17822 "macro is parsed and is callable."
17826 #: build/C/man7/mdoc.samples.7:986
17828 msgid "Function Argument"
17831 #. type: Plain text
17832 #: build/C/man7/mdoc.samples.7:1005
17834 "The E<.Ql \\&.Fa> macro is used to refer to function arguments (parameters) "
17835 "outside of the E<.Sx SYNOPSIS> section of the manual or inside the E<.Sx "
17836 "SYNOPSIS> section should a parameter list be too long for the E<.Ql \\&.Fn> "
17837 "macro and the enclosure macros E<.Ql \\&.Fo> and E<.Ql \\&.Fc> must be "
17838 "used. E<.Ql \\&.Fa> may also be used to refer to structure members."
17842 #: build/C/man7/mdoc.samples.7:1006
17844 msgid "Usage: .Fa function_argument ... \\*(Pu"
17848 #: build/C/man7/mdoc.samples.7:1008
17850 msgid "Li \\&.Fa d_namlen\\ )\\ )\\ ,"
17853 #. type: Plain text
17854 #: build/C/man7/mdoc.samples.7:1010
17855 msgid "E<.Fa d_namlen>)),"
17859 #: build/C/man7/mdoc.samples.7:1010
17861 msgid "Li \\&.Fa iov_len"
17864 #. type: Plain text
17865 #: build/C/man7/mdoc.samples.7:1012
17866 msgid "E<.Fa iov_len>"
17869 #. type: Plain text
17870 #: build/C/man7/mdoc.samples.7:1019
17872 "It is an error to call E<.Ql \\&.Fa> without arguments. E<.Ql \\&.Fa> is "
17873 "parsed and is callable."
17877 #: build/C/man7/mdoc.samples.7:1019
17879 msgid "Function Declaration"
17882 #. type: Plain text
17883 #: build/C/man7/mdoc.samples.7:1030
17885 "The E<.Ql \\&.Fd> macro is used in the E<.Sx SYNOPSIS> section with section "
17886 "two or three functions. The E<.Ql \\&.Fd> macro does not call other macros "
17887 "and is not callable by other macros."
17891 #: build/C/man7/mdoc.samples.7:1031
17893 msgid "Usage: .Fd include_file (or defined variable)"
17896 #. type: Plain text
17897 #: build/C/man7/mdoc.samples.7:1042
17899 "In the E<.Sx SYNOPSIS> section a E<.Ql \\&.Fd> request causes a line break "
17900 "if a function has already been presented and a break has not occurred. This "
17901 "leaves a nice vertical space in between the previous function call and the "
17902 "declaration for the next function."
17906 #: build/C/man7/mdoc.samples.7:1042
17911 #. type: Plain text
17912 #: build/C/man7/mdoc.samples.7:1055
17914 "The E<.Ql \\&.Fl> macro handles command-line flags. It prepends a dash, "
17915 "E<.Ql \\->, to the flag. For interactive command flags, which are not "
17916 "prepended with a dash, the E<.Ql \\&.Cm> (command modifier) macro is "
17917 "identical, but without the dash."
17921 #: build/C/man7/mdoc.samples.7:1056
17923 msgid "Usage: .Fl argument ... \\*(Pu"
17927 #: build/C/man7/mdoc.samples.7:1058
17932 #. type: Plain text
17933 #: build/C/man7/mdoc.samples.7:1060
17938 #: build/C/man7/mdoc.samples.7:1060
17940 msgid "Li \\&.Fl cfv"
17943 #. type: Plain text
17944 #: build/C/man7/mdoc.samples.7:1062
17949 #: build/C/man7/mdoc.samples.7:1062
17951 msgid "Li \\&.Fl cfv\\ ."
17954 #. type: Plain text
17955 #: build/C/man7/mdoc.samples.7:1064
17956 msgid "E<.Fl cfv>."
17960 #: build/C/man7/mdoc.samples.7:1064
17962 msgid "Li \\&.Fl s v t"
17965 #. type: Plain text
17966 #: build/C/man7/mdoc.samples.7:1066
17967 msgid "E<.Fl s v t>"
17971 #: build/C/man7/mdoc.samples.7:1066
17973 msgid "Li \\&.Fl -\\ ,"
17976 #. type: Plain text
17977 #: build/C/man7/mdoc.samples.7:1068
17982 #: build/C/man7/mdoc.samples.7:1068
17984 msgid "Li \\&.Fl xyz\\ )\\ ,"
17987 #. type: Plain text
17988 #: build/C/man7/mdoc.samples.7:1070
17989 msgid "E<.Fl xyz>),"
17992 #. type: Plain text
17993 #: build/C/man7/mdoc.samples.7:1082
17995 "The E<.Ql \\&.Fl> macro without any arguments results in a dash representing "
17996 "I<stdin>/I<stdout>. Note that giving E<.Ql \\&.Fl> a single dash, will "
17997 "result in two dashes. The E<.Ql \\&.Fl> macro is parsed and is callable."
18001 #: build/C/man7/mdoc.samples.7:1082
18003 msgid "Functions (library routines)"
18006 #. type: Plain text
18007 #: build/C/man7/mdoc.samples.7:1084
18008 msgid "The .Fn macro is modeled on ANSI C conventions."
18011 #. type: Plain text
18012 #: build/C/man7/mdoc.samples.7:1086
18014 msgid "Usage: .Fn [type] function [[type] parameters ... \\*(Pu]\n"
18018 #: build/C/man7/mdoc.samples.7:1088
18020 msgid "Li \"\\&.Fn getchar\""
18023 #. type: Plain text
18024 #: build/C/man7/mdoc.samples.7:1090
18025 msgid "E<.Fn getchar>"
18029 #: build/C/man7/mdoc.samples.7:1090
18031 msgid "Li \"\\&.Fn strlen ) ,\""
18034 #. type: Plain text
18035 #: build/C/man7/mdoc.samples.7:1092
18036 msgid "E<.Fn strlen>),"
18040 #: build/C/man7/mdoc.samples.7:1092
18042 msgid "Li \\&.Fn \"\\*qint align\\*q\" \"\\*qconst * char *sptrs\\*q\" ,"
18045 #. type: Plain text
18046 #: build/C/man7/mdoc.samples.7:1094
18047 msgid "E<.Fn \"int align\" \"const * char *sptrs\">,"
18050 #. type: Plain text
18051 #: build/C/man7/mdoc.samples.7:1107
18053 "It is an error to call E<.Ql \\&.Fn> without any arguments. The E<.Ql "
18054 "\\&.Fn> macro is parsed and is callable, note that any call to another macro "
18055 "signals the end of the E<.Ql \\&.Fn> call (it will close-parenthesis at that "
18059 #. type: Plain text
18060 #: build/C/man7/mdoc.samples.7:1121
18062 "For functions that have more than eight parameters (and this is rare), the "
18063 "macros E<.Ql \\&.Fo> (function open) and E<.Ql \\&.Fc> (function close) "
18064 "may be used with E<.Ql \\&.Fa> (function argument) to get around the "
18065 "limitation. For example:"
18068 #. type: Plain text
18069 #: build/C/man7/mdoc.samples.7:1133
18072 "\\&.Fo \"int res_mkquery\"\n"
18073 "\\&.Fa \"int op\"\n"
18074 "\\&.Fa \"char *dname\"\n"
18075 "\\&.Fa \"int class\"\n"
18076 "\\&.Fa \"int type\"\n"
18077 "\\&.Fa \"char *data\"\n"
18078 "\\&.Fa \"int datalen\"\n"
18079 "\\&.Fa \"struct rrec *newrr\"\n"
18080 "\\&.Fa \"char *buf\"\n"
18081 "\\&.Fa \"int buflen\"\n"
18085 #. type: Plain text
18086 #: build/C/man7/mdoc.samples.7:1136 build/C/man7/mdoc.samples.7:2480
18090 #. type: Plain text
18091 #: build/C/man7/mdoc.samples.7:1148
18094 "E<.Fo \"int res_mkquery\">\n"
18095 "E<.Fa \"int op\">\n"
18096 "E<.Fa \"char *dname\">\n"
18097 "E<.Fa \"int class\">\n"
18098 "E<.Fa \"int type\">\n"
18099 "E<.Fa \"char *data\">\n"
18100 "E<.Fa \"int datalen\">\n"
18101 "E<.Fa \"struct rrec *newrr\">\n"
18102 "E<.Fa \"char *buf\">\n"
18103 "E<.Fa \"int buflen\">\n"
18107 #. type: Plain text
18108 #: build/C/man7/mdoc.samples.7:1171
18110 "The E<.Ql \\&.Fo> and E<.Ql \\&.Fc> macros are parsed and are callable. In "
18111 "the E<.Sx SYNOPSIS> section, the function will always begin at the beginning "
18112 "of line. If there is more than one function presented in the E<.Sx "
18113 "SYNOPSIS> section and a function type has not been given, a line break will "
18114 "occur, leaving a nice vertical space between the current function name and "
18115 "the one prior. At the moment, E<.Ql \\&.Fn> does not check its word "
18116 "boundaries against troff line lengths and may split across a newline "
18117 "ungracefully. This will be fixed in the near future."
18121 #: build/C/man7/mdoc.samples.7:1171
18123 msgid "Function Type"
18126 #. type: Plain text
18127 #: build/C/man7/mdoc.samples.7:1182
18129 "This macro is intended for the E<.Sx SYNOPSIS> section. It may be used "
18130 "anywhere else in the man page without problems, but its main purpose is to "
18131 "present the function type in kernel normal form for the E<.Sx SYNOPSIS> of "
18132 "sections two and three (it causes a line break allowing the function name to "
18133 "appear on the next line)."
18137 #: build/C/man7/mdoc.samples.7:1183
18139 msgid "Usage: .Ft type ... \\*(Pu"
18143 #: build/C/man7/mdoc.samples.7:1185
18145 msgid "Li \\&.Ft struct stat"
18148 #. type: Plain text
18149 #: build/C/man7/mdoc.samples.7:1187
18150 msgid "E<.Ft struct stat>"
18153 #. type: Plain text
18154 #: build/C/man7/mdoc.samples.7:1192
18155 msgid "The E<.Ql \\&.Ft> request is not callable by other macros."
18159 #: build/C/man7/mdoc.samples.7:1192
18161 msgid "Interactive Commands"
18164 #. type: Plain text
18165 #: build/C/man7/mdoc.samples.7:1196
18166 msgid "The E<.Ql \\&.Ic> macro designates an interactive or internal command."
18170 #: build/C/man7/mdoc.samples.7:1197
18172 msgid "Usage: .Ic argument ... \\*(Pu"
18176 #: build/C/man7/mdoc.samples.7:1199
18178 msgid "Li \\&.Ic :wq"
18181 #. type: Plain text
18182 #: build/C/man7/mdoc.samples.7:1201
18187 #: build/C/man7/mdoc.samples.7:1201
18189 msgid "Li \\&.Ic do while {...}"
18192 #. type: Plain text
18193 #: build/C/man7/mdoc.samples.7:1203
18194 msgid "E<.Ic do while {...}>"
18198 #: build/C/man7/mdoc.samples.7:1203
18200 msgid "Li \\&.Ic setenv\\ , unsetenv"
18203 #. type: Plain text
18204 #: build/C/man7/mdoc.samples.7:1205
18205 msgid "E<.Ic setenv , unsetenv>"
18208 #. type: Plain text
18209 #: build/C/man7/mdoc.samples.7:1213
18211 "It is an error to call E<.Ql \\&.Ic> without arguments. The E<.Ql \\&.Ic> "
18212 "macro is parsed and is callable."
18216 #: build/C/man7/mdoc.samples.7:1213
18221 #. type: Plain text
18222 #: build/C/man7/mdoc.samples.7:1249
18224 "The E<.Ql \\&.Nm> macro is used for the document title or subject name. It "
18225 "has the peculiarity of remembering the first argument it was called with, "
18226 "which should always be the subject name of the page. When called without "
18227 "arguments, E<.Ql \\&.Nm> regurgitates this initial name for the sole purpose "
18228 "of making less work for the author. Note: a section two or three document "
18229 "function name is addressed with the E<.Ql \\&.Nm> in the E<.Sx NAME> "
18230 "section, and with E<.Ql \\&.Fn> in the E<.Sx SYNOPSIS> and remaining "
18231 "sections. For interactive commands, such as the E<.Ql while> command "
18232 "keyword in E<.Xr csh 1>, the E<.Ql \\&.Ic> macro should be used. While the "
18233 "E<.Ql \\&.Ic> is nearly identical to E<.Ql \\&.Nm>, it can not recall the "
18234 "first argument it was invoked with."
18238 #: build/C/man7/mdoc.samples.7:1250
18240 msgid "Usage: .Nm argument ... \\*(Pu"
18244 #: build/C/man7/mdoc.samples.7:1252
18246 msgid "Li \\&.Nm mdoc.sample"
18249 #. type: Plain text
18250 #: build/C/man7/mdoc.samples.7:1254
18251 msgid "E<.Nm mdoc.sample>"
18255 #: build/C/man7/mdoc.samples.7:1254
18257 msgid "Li \\&.Nm \\e-mdoc"
18260 #. type: Plain text
18261 #: build/C/man7/mdoc.samples.7:1256
18262 msgid "E<.Nm \\-mdoc>."
18266 #: build/C/man7/mdoc.samples.7:1256
18268 msgid "Li \\&.Nm foo\\ )\\ )\\ ,"
18271 #. type: Plain text
18272 #: build/C/man7/mdoc.samples.7:1258
18273 msgid "E<.Nm foo>)),"
18277 #: build/C/man7/mdoc.samples.7:1258
18282 #. type: Plain text
18283 #: build/C/man7/mdoc.samples.7:1260
18287 #. type: Plain text
18288 #: build/C/man7/mdoc.samples.7:1265
18289 msgid "The E<.Ql \\&.Nm> macro is parsed and is callable."
18293 #: build/C/man7/mdoc.samples.7:1265
18298 #. type: Plain text
18299 #: build/C/man7/mdoc.samples.7:1277
18301 "The E<.Ql \\&.Op> macro places option brackets around the any remaining "
18302 "arguments on the command line, and places any trailing punctuation outside "
18303 "the brackets. The macros E<.Ql \\&.Oc> and E<.Ql \\&.Oo> may be used across "
18304 "one or more lines."
18308 #: build/C/man7/mdoc.samples.7:1278
18310 msgid "Usage: .Op options ... \\*(Pu"
18314 #: build/C/man7/mdoc.samples.7:1280
18319 #. type: Plain text
18320 #: build/C/man7/mdoc.samples.7:1282
18325 #: build/C/man7/mdoc.samples.7:1282
18327 msgid "Li \".Op Fl k\""
18330 #. type: Plain text
18331 #: build/C/man7/mdoc.samples.7:1284
18332 msgid "E<.Op Fl k>"
18336 #: build/C/man7/mdoc.samples.7:1284
18338 msgid "Li \".Op Fl k ) .\""
18341 #. type: Plain text
18342 #: build/C/man7/mdoc.samples.7:1286
18343 msgid "E<.Op Fl k>)."
18347 #: build/C/man7/mdoc.samples.7:1286
18349 msgid "Li \".Op Fl k Ar kookfile\""
18352 #. type: Plain text
18353 #: build/C/man7/mdoc.samples.7:1288
18354 msgid "E<.Op Fl k Ar kookfile>"
18358 #: build/C/man7/mdoc.samples.7:1288
18360 msgid "Li \".Op Fl k Ar kookfile ,\""
18363 #. type: Plain text
18364 #: build/C/man7/mdoc.samples.7:1290
18365 msgid "E<.Op Fl k Ar kookfile>,"
18369 #: build/C/man7/mdoc.samples.7:1290
18371 msgid "Li \".Op Ar objfil Op Ar corfil\""
18374 #. type: Plain text
18375 #: build/C/man7/mdoc.samples.7:1292
18376 msgid "E<.Op Ar objfil Op Ar corfil>"
18380 #: build/C/man7/mdoc.samples.7:1292
18382 msgid "Li \".Op Fl c Ar objfil Op Ar corfil ,\""
18385 #. type: Plain text
18386 #: build/C/man7/mdoc.samples.7:1294
18387 msgid "E<.Op Fl c Ar objfil Op Ar corfil>,"
18391 #: build/C/man7/mdoc.samples.7:1294
18393 msgid "Li \\&.Op word1 word2"
18396 #. type: Plain text
18397 #: build/C/man7/mdoc.samples.7:1296
18398 msgid "E<.Op word1 word2>"
18401 #. type: Plain text
18402 #: build/C/man7/mdoc.samples.7:1303
18403 msgid "The E<.Ql \\&.Oc> and E<.Ql \\&.Oo> macros:"
18406 #. type: Plain text
18407 #: build/C/man7/mdoc.samples.7:1309
18411 "\\&.Op \\&Fl k \\&Ar kilobytes\n"
18412 "\\&.Op \\&Fl i \\&Ar interval\n"
18413 "\\&.Op \\&Fl c \\&Ar count\n"
18417 #. type: Plain text
18418 #: build/C/man7/mdoc.samples.7:1317
18420 "Produce: E<.Oo> E<.Op Fl k Ar kilobytes> E<.Op Fl i Ar interval> E<.Op Fl c "
18424 #. type: Plain text
18425 #: build/C/man7/mdoc.samples.7:1324
18427 "The macros E<.Ql \\&.Op>, E<.Ql \\&.Oc> and E<.Ql \\&.Oo> are parsed and are "
18432 #: build/C/man7/mdoc.samples.7:1324
18437 #. type: Plain text
18438 #: build/C/man7/mdoc.samples.7:1328
18439 msgid "The E<.Ql \\&.Pa> macro formats pathnames or filenames."
18443 #: build/C/man7/mdoc.samples.7:1329
18445 msgid "Usage: .Pa pathname \\*(Pu"
18449 #: build/C/man7/mdoc.samples.7:1331
18451 msgid "Li \\&.Pa /usr/share"
18454 #. type: Plain text
18455 #: build/C/man7/mdoc.samples.7:1333
18456 msgid "E<.Pa /usr/share>"
18460 #: build/C/man7/mdoc.samples.7:1333
18462 msgid "Li \\&.Pa /tmp/fooXXXXX\\ )\\ ."
18465 #. type: Plain text
18466 #: build/C/man7/mdoc.samples.7:1335
18467 msgid "E<.Pa /tmp/fooXXXXX>)."
18470 #. type: Plain text
18471 #: build/C/man7/mdoc.samples.7:1340
18472 msgid "The E<.Ql \\&.Pa> macro is parsed and is callable."
18476 #: build/C/man7/mdoc.samples.7:1340
18481 #. type: Plain text
18482 #: build/C/man7/mdoc.samples.7:1342
18483 msgid "Generic variable reference:"
18487 #: build/C/man7/mdoc.samples.7:1343
18489 msgid "Usage: .Va variable ... \\*(Pu"
18493 #: build/C/man7/mdoc.samples.7:1345
18495 msgid "Li \\&.Va count"
18498 #. type: Plain text
18499 #: build/C/man7/mdoc.samples.7:1347
18500 msgid "E<.Va count>"
18504 #: build/C/man7/mdoc.samples.7:1347
18506 msgid "Li \\&.Va settimer ,"
18509 #. type: Plain text
18510 #: build/C/man7/mdoc.samples.7:1349
18511 msgid "E<.Va settimer>,"
18515 #: build/C/man7/mdoc.samples.7:1349
18517 msgid "Li \\&.Va int\\ *prt\\ )\\ :"
18520 #. type: Plain text
18521 #: build/C/man7/mdoc.samples.7:1351
18522 msgid "E<.Va int\\ *prt>):"
18526 #: build/C/man7/mdoc.samples.7:1351
18528 msgid "Li \\&.Va char\\ s\\ ]\\ )\\ )\\ ,"
18531 #. type: Plain text
18532 #: build/C/man7/mdoc.samples.7:1353
18533 msgid "E<.Va char\\ s>])),"
18536 #. type: Plain text
18537 #: build/C/man7/mdoc.samples.7:1361
18539 "It is an error to call E<.Ql \\&.Va> without any arguments. The E<.Ql "
18540 "\\&.Va> macro is parsed and is callable."
18544 #: build/C/man7/mdoc.samples.7:1361
18546 msgid "Manual Page Cross References"
18549 #. type: Plain text
18550 #: build/C/man7/mdoc.samples.7:1369
18552 "The E<.Ql \\&.Xr> macro expects the first argument to be a manual page name, "
18553 "and the second argument, if it exists, to be either a section page number or "
18554 "punctuation. Any remaining arguments are assumed to be punctuation."
18558 #: build/C/man7/mdoc.samples.7:1370
18560 msgid "Usage: .Xr man_page [1,...,8] \\*(Pu"
18564 #: build/C/man7/mdoc.samples.7:1372
18566 msgid "Li \\&.Xr mdoc"
18569 #. type: Plain text
18570 #: build/C/man7/mdoc.samples.7:1374
18571 msgid "E<.Xr mdoc>"
18575 #: build/C/man7/mdoc.samples.7:1374
18577 msgid "Li \\&.Xr mdoc\\ ,"
18580 #. type: Plain text
18581 #: build/C/man7/mdoc.samples.7:1376
18582 msgid "E<.Xr mdoc>,"
18586 #: build/C/man7/mdoc.samples.7:1376
18588 msgid "Li \\&.Xr mdoc 7"
18591 #. type: Plain text
18592 #: build/C/man7/mdoc.samples.7:1378
18593 msgid "E<.Xr mdoc 7>"
18597 #: build/C/man7/mdoc.samples.7:1378
18599 msgid "Li \\&.Xr mdoc 7\\ )\\ )\\ ,"
18602 #. type: Plain text
18603 #: build/C/man7/mdoc.samples.7:1380
18604 msgid "E<.Xr mdoc 7>)),"
18607 #. type: Plain text
18608 #: build/C/man7/mdoc.samples.7:1389
18610 "The E<.Ql \\&.Xr> macro is parsed and is callable. It is an error to call "
18611 "E<.Ql \\&.Xr> without any arguments."
18615 #: build/C/man7/mdoc.samples.7:1389
18617 msgid "GENERAL TEXT DOMAIN"
18621 #: build/C/man7/mdoc.samples.7:1390
18626 #. type: Plain text
18627 #: build/C/man7/mdoc.samples.7:1393
18629 msgid "Usage: .At [v6 | v7 | 32v | V.1 | V.4] ... \\*(Pu\n"
18633 #: build/C/man7/mdoc.samples.7:1395
18638 #. type: Plain text
18639 #: build/C/man7/mdoc.samples.7:1397
18644 #: build/C/man7/mdoc.samples.7:1397
18646 msgid "Li \".At v6 .\""
18649 #. type: Plain text
18650 #: build/C/man7/mdoc.samples.7:1399
18654 #. type: Plain text
18655 #: build/C/man7/mdoc.samples.7:1409
18657 "The E<.Ql \\&.At> macro is E<.Em not> parsed and E<.Em not> callable It "
18658 "accepts at most two arguments."
18662 #: build/C/man7/mdoc.samples.7:1409
18668 #: build/C/man7/mdoc.samples.7:1410
18670 msgid "Usage: .Bx [Version/release] ... \\*(Pu"
18674 #: build/C/man7/mdoc.samples.7:1412
18679 #. type: Plain text
18680 #: build/C/man7/mdoc.samples.7:1414
18685 #: build/C/man7/mdoc.samples.7:1414
18687 msgid "Li \".Bx 4.3 .\""
18690 #. type: Plain text
18691 #: build/C/man7/mdoc.samples.7:1416
18692 msgid "E<.Bx 4.3>."
18695 #. type: Plain text
18696 #: build/C/man7/mdoc.samples.7:1421
18697 msgid "The E<.Ql \\&.Bx> macro is parsed and is callable."
18701 #: build/C/man7/mdoc.samples.7:1421
18703 msgid "FreeBSD Macro"
18706 #. type: Plain text
18707 #: build/C/man7/mdoc.samples.7:1424
18709 msgid "Usage: .Fx Version.release ... \\*(Pu\n"
18713 #: build/C/man7/mdoc.samples.7:1426
18715 msgid "Li \".Fx 2.2 .\""
18718 #. type: Plain text
18719 #: build/C/man7/mdoc.samples.7:1428
18720 msgid "E<.Fx 2.2>."
18723 #. type: Plain text
18724 #: build/C/man7/mdoc.samples.7:1438
18726 "The E<.Ql \\&.Fx> macro is E<.Em not> parsed and E<.Em not> callable It "
18727 "accepts at most two arguments."
18731 #: build/C/man7/mdoc.samples.7:1438
18737 #: build/C/man7/mdoc.samples.7:1439
18739 msgid "Usage: .Ux ... \\*(Pu"
18743 #: build/C/man7/mdoc.samples.7:1441
18748 #. type: Plain text
18749 #: build/C/man7/mdoc.samples.7:1443
18753 #. type: Plain text
18754 #: build/C/man7/mdoc.samples.7:1448
18755 msgid "The E<.Ql \\&.Ux> macro is parsed and is callable."
18759 #: build/C/man7/mdoc.samples.7:1448
18761 msgid "Enclosure and Quoting Macros"
18764 #. type: Plain text
18765 #: build/C/man7/mdoc.samples.7:1470
18767 "The concept of enclosure is similar to quoting. The object being to enclose "
18768 "one or more strings between a pair of characters like quotes or "
18769 "parentheses. The terms quoting and enclosure are used interchangeably "
18770 "throughout this document. Most of the one line enclosure macros end in "
18771 "small letter E<.Ql q> to give a hint of quoting, but there are a few "
18772 "irregularities. For each enclosure macro there is also a pair of open and "
18773 "close macros which end in small letters E<.Ql o> and E<.Ql c> respectively. "
18774 "These can be used across one or more lines of text and while they have "
18775 "nesting limitations, the one line quote macros can be used inside of them."
18778 #. type: Plain text
18779 #: build/C/man7/mdoc.samples.7:1483
18782 "E<.Em \" Quote\t Close\t Open\tFunction\tResult\">\n"
18783 "\\&.Aq\t.Ac\t.Ao\tAngle Bracket Enclosure\tE<lt>stringE<gt>\n"
18784 "\\&.Bq\t.Bc\t.Bo\tBracket Enclosure\t[string]\n"
18785 "\\&.Dq\t.Dc\t.Do\tDouble Quote\t``string''\n"
18786 "\t.Ec\t.Eo\tEnclose String (in XX)\tXXstringXX\n"
18787 "\\&.Pq\t.Pc\t.Po\tParenthesis Enclosure\t(string)\n"
18788 "\\&.Ql\t\t\tQuoted Literal\t`st' or string\n"
18789 "\\&.Qq\t.Qc\t.Qo\tStraight Double Quote\t\"string\"\n"
18790 "\\&.Sq\t.Sc\t.So\tSingle Quote\t`string'\n"
18793 #. type: Plain text
18794 #: build/C/man7/mdoc.samples.7:1494
18796 "Except for the irregular macros noted below, all of the quoting macros are "
18797 "parsed and callable. All handle punctuation properly, as long as it is "
18798 "presented one character at a time and separated by spaces. The quoting "
18799 "macros examine opening and closing punctuation to determine whether it comes "
18800 "before or after the enclosing string This makes some nesting possible."
18804 #: build/C/man7/mdoc.samples.7:1495
18806 msgid "Li \\&.Ec , \\&.Eo"
18809 #. type: Plain text
18810 #: build/C/man7/mdoc.samples.7:1498
18812 "These macros expect the first argument to be the opening and closing strings "
18817 #: build/C/man7/mdoc.samples.7:1498
18822 #. type: Plain text
18823 #: build/C/man7/mdoc.samples.7:1511
18825 "The quoted literal macro behaves differently for E<.Xr troff> than E<.Xr "
18826 "nroff>. If formatted with E<.Xr nroff>, a quoted literal is always quoted. "
18827 "If formatted with troff, an item is quoted only if the width of the item is "
18828 "less than three constant width characters. This is to make short strings "
18829 "more visible where the font change to literal (constant width) is less "
18834 #: build/C/man7/mdoc.samples.7:1511
18839 #. type: Plain text
18840 #: build/C/man7/mdoc.samples.7:1513
18841 msgid "The prefix macro is not callable, but it is parsed:"
18845 #: build/C/man7/mdoc.samples.7:1514
18847 msgid "Li \".Pf ( Fa name2\""
18850 #. type: Plain text
18851 #: build/C/man7/mdoc.samples.7:1517
18852 msgid "becomes E<.Pf ( Fa name2>."
18855 #. type: Plain text
18856 #: build/C/man7/mdoc.samples.7:1522
18857 msgid "The E<.Ql \\&.Ns> (no space) macro performs the analogous suffix function."
18860 #. type: Plain text
18861 #: build/C/man7/mdoc.samples.7:1526
18862 msgid "Examples of quoting:"
18866 #: build/C/man7/mdoc.samples.7:1527
18871 #. type: Plain text
18872 #: build/C/man7/mdoc.samples.7:1529
18877 #: build/C/man7/mdoc.samples.7:1529
18879 msgid "Li \\&.Aq \\&Ar ctype.h\\ )\\ ,"
18882 #. type: Plain text
18883 #: build/C/man7/mdoc.samples.7:1531
18884 msgid "E<.Aq Ar ctype.h>),"
18888 #: build/C/man7/mdoc.samples.7:1531
18893 #. type: Plain text
18894 #: build/C/man7/mdoc.samples.7:1533
18899 #: build/C/man7/mdoc.samples.7:1533
18901 msgid "Li \\&.Bq \\&Em Greek \\&, French \\&."
18904 #. type: Plain text
18905 #: build/C/man7/mdoc.samples.7:1535
18906 msgid "E<.Bq Em Greek , French>."
18910 #: build/C/man7/mdoc.samples.7:1535
18915 #. type: Plain text
18916 #: build/C/man7/mdoc.samples.7:1537
18921 #: build/C/man7/mdoc.samples.7:1537
18923 msgid "Li \".Dq string abc .\""
18926 #. type: Plain text
18927 #: build/C/man7/mdoc.samples.7:1539
18928 msgid "E<.Dq string abc>."
18932 #: build/C/man7/mdoc.samples.7:1539
18934 msgid "Li \".Dq \\'^[A-Z]\\'\""
18937 #. type: Plain text
18938 #: build/C/man7/mdoc.samples.7:1541
18939 msgid "E<.Dq \\'^[A-Z]\\'>"
18943 #: build/C/man7/mdoc.samples.7:1541
18945 msgid "Li \"\\&.Ql man mdoc\""
18948 #. type: Plain text
18949 #: build/C/man7/mdoc.samples.7:1543
18950 msgid "E<.Ql man mdoc>"
18954 #: build/C/man7/mdoc.samples.7:1543
18959 #. type: Plain text
18960 #: build/C/man7/mdoc.samples.7:1545
18965 #: build/C/man7/mdoc.samples.7:1545
18967 msgid "Li \"\\&.Qq string ) ,\""
18970 #. type: Plain text
18971 #: build/C/man7/mdoc.samples.7:1547
18972 msgid "E<.Qq string>),"
18976 #: build/C/man7/mdoc.samples.7:1547
18978 msgid "Li \"\\&.Qq string Ns ),\""
18981 #. type: Plain text
18982 #: build/C/man7/mdoc.samples.7:1549
18983 msgid "E<.Qq string Ns ),>"
18987 #: build/C/man7/mdoc.samples.7:1549
18992 #. type: Plain text
18993 #: build/C/man7/mdoc.samples.7:1551
18998 #: build/C/man7/mdoc.samples.7:1551
19000 msgid "Li \"\\&.Sq string\""
19003 #. type: Plain text
19004 #: build/C/man7/mdoc.samples.7:1553
19005 msgid "E<.Sq string>"
19008 #. type: Plain text
19009 #: build/C/man7/mdoc.samples.7:1570
19011 "For a good example of nested enclosure macros, see the E<.Ql \\&.Op> option "
19012 "macro. It was created from the same underlying enclosure macros as those "
19013 "presented in the list above. The E<.Ql \\&.Xo> and E<.Ql \\&.Xc> extended "
19014 "argument list macros were also built from the same underlying routines and "
19015 "are a good example of E<.Nm \\-mdoc> macro usage at its worst."
19019 #: build/C/man7/mdoc.samples.7:1570
19021 msgid "No\\-Op or Normal Text Macro"
19024 #. type: Plain text
19025 #: build/C/man7/mdoc.samples.7:1578
19027 "The macro E<.Ql \\&.No> is a hack for words in a macro command line which "
19028 "should E<.Em not> be formatted and follows the conventional syntax for "
19033 #: build/C/man7/mdoc.samples.7:1578
19035 msgid "No Space Macro"
19038 #. type: Plain text
19039 #: build/C/man7/mdoc.samples.7:1584
19041 "The E<.Ql \\&.Ns> macro eliminates unwanted spaces in between macro "
19042 "requests. It is useful for old style argument lists where there is no space "
19043 "between the flag and argument:"
19047 #: build/C/man7/mdoc.samples.7:1585
19049 msgid "Li \".Op Fl I Ns Ar directory\""
19052 #. type: Plain text
19053 #: build/C/man7/mdoc.samples.7:1588
19054 msgid "produces E<.Op Fl I Ns Ar directory>"
19057 #. type: Plain text
19058 #: build/C/man7/mdoc.samples.7:1599
19060 "Note: the E<.Ql \\&.Ns> macro always invokes the E<.Ql \\&.No> macro after "
19061 "eliminating the space unless another macro name follows it. The macro E<.Ql "
19062 "\\&.Ns> is parsed and is callable."
19066 #: build/C/man7/mdoc.samples.7:1599
19068 msgid "Section Cross References"
19071 #. type: Plain text
19072 #: build/C/man7/mdoc.samples.7:1605
19074 "The E<.Ql \\&.Sx> macro designates a reference to a section header within "
19075 "the same document. It is parsed and is callable."
19079 #: build/C/man7/mdoc.samples.7:1607
19081 msgid "Li \\&.Sx FILES"
19084 #. type: Plain text
19085 #: build/C/man7/mdoc.samples.7:1609
19086 msgid "E<.Sx FILES>"
19090 #: build/C/man7/mdoc.samples.7:1610
19092 msgid "References and Citations"
19095 #. type: Plain text
19096 #: build/C/man7/mdoc.samples.7:1614
19098 "The following macros make a modest attempt to handle references. At best, "
19099 "the macros make it convenient to manually drop in a subset of refer style "
19104 #: build/C/man7/mdoc.samples.7:1616
19109 #. type: Plain text
19110 #: build/C/man7/mdoc.samples.7:1621
19112 "Reference Start. Causes a line break and begins collection of reference "
19113 "information until the reference end macro is read."
19117 #: build/C/man7/mdoc.samples.7:1621
19122 #. type: Plain text
19123 #: build/C/man7/mdoc.samples.7:1624
19124 msgid "Reference End. The reference is printed."
19128 #: build/C/man7/mdoc.samples.7:1624
19133 #. type: Plain text
19134 #: build/C/man7/mdoc.samples.7:1626
19135 msgid "Reference author name, one name per invocation."
19139 #: build/C/man7/mdoc.samples.7:1626
19144 #. type: Plain text
19145 #: build/C/man7/mdoc.samples.7:1628
19146 msgid "Book title."
19150 #: build/C/man7/mdoc.samples.7:1628
19155 #. type: Plain text
19156 #: build/C/man7/mdoc.samples.7:1630
19157 msgid "City/place."
19161 #: build/C/man7/mdoc.samples.7:1630
19166 #. type: Plain text
19167 #: build/C/man7/mdoc.samples.7:1632
19172 #: build/C/man7/mdoc.samples.7:1632
19177 #. type: Plain text
19178 #: build/C/man7/mdoc.samples.7:1634
19179 msgid "Journal name."
19183 #: build/C/man7/mdoc.samples.7:1634
19188 #. type: Plain text
19189 #: build/C/man7/mdoc.samples.7:1636
19190 msgid "Issue number."
19194 #: build/C/man7/mdoc.samples.7:1636
19199 #. type: Plain text
19200 #: build/C/man7/mdoc.samples.7:1638
19201 msgid "Optional information."
19205 #: build/C/man7/mdoc.samples.7:1638
19210 #. type: Plain text
19211 #: build/C/man7/mdoc.samples.7:1640
19212 msgid "Page number."
19216 #: build/C/man7/mdoc.samples.7:1640
19221 #. type: Plain text
19222 #: build/C/man7/mdoc.samples.7:1642
19223 msgid "Report name."
19227 #: build/C/man7/mdoc.samples.7:1642
19232 #. type: Plain text
19233 #: build/C/man7/mdoc.samples.7:1644
19234 msgid "Title of article."
19238 #: build/C/man7/mdoc.samples.7:1644
19243 #. type: Plain text
19244 #: build/C/man7/mdoc.samples.7:1646
19248 #. type: Plain text
19249 #: build/C/man7/mdoc.samples.7:1657
19251 "The macros beginning with E<.Ql %> are not callable, and are parsed only for "
19252 "the trade name macro which returns to its caller. (And not very predictably "
19253 "at the moment either.) The purpose is to allow trade names to be pretty "
19254 "printed in E<.Xr troff Ns / Ns Xr ditroff> output."
19258 #: build/C/man7/mdoc.samples.7:1657
19260 msgid "Return Values"
19263 #. type: Plain text
19264 #: build/C/man7/mdoc.samples.7:1663
19266 "The E<.Ql \\&.Rv> macro generates text for use in the E<.Sx RETURN VALUE> "
19271 #: build/C/man7/mdoc.samples.7:1664
19273 msgid "Usage: .Rv [-std function]"
19276 #. type: Plain text
19277 #: build/C/man7/mdoc.samples.7:1668
19278 msgid "E<.Ql \\&.Rv -std atexit> will generate the following text:"
19281 #. fake section 3 to avoid error message from Rv
19283 #. type: ds section
19284 #: build/C/man7/mdoc.samples.7:1671
19289 #. and back to 7 again
19291 #. type: Plain text
19292 #: build/C/man7/mdoc.samples.7:1675
19293 msgid "E<.Rv -std atexit>"
19296 #. type: ds section
19297 #: build/C/man7/mdoc.samples.7:1675
19302 #. type: Plain text
19303 #: build/C/man7/mdoc.samples.7:1680
19304 msgid "The E<.Fl std> option is valid only for manual page sections 2 and 3."
19308 #: build/C/man7/mdoc.samples.7:1680
19310 msgid "Trade Names (or Acronyms and Type Names)"
19313 #. type: Plain text
19314 #: build/C/man7/mdoc.samples.7:1683
19316 "The trade name macro is generally a small caps macro for all uppercase words "
19317 "longer than two characters."
19321 #: build/C/man7/mdoc.samples.7:1684
19323 msgid "Usage: .Tn symbol ... \\*(Pu"
19327 #: build/C/man7/mdoc.samples.7:1686
19329 msgid "Li \\&.Tn DEC"
19332 #. type: Plain text
19333 #: build/C/man7/mdoc.samples.7:1688
19338 #: build/C/man7/mdoc.samples.7:1688
19340 msgid "Li \\&.Tn ASCII"
19343 #. type: Plain text
19344 #: build/C/man7/mdoc.samples.7:1690
19345 msgid "E<.Tn ASCII>"
19348 #. type: Plain text
19349 #: build/C/man7/mdoc.samples.7:1696
19350 msgid "The E<.Ql \\&.Tn> macro is parsed and is callable by other macros."
19354 #: build/C/man7/mdoc.samples.7:1696
19356 msgid "Extended Arguments"
19359 #. type: Plain text
19360 #: build/C/man7/mdoc.samples.7:1708
19362 "The E<.Ql \\&.Xo> and E<.Ql \\&.Xc> macros allow one to extend an argument "
19363 "list on a macro boundary. Argument lists cannot be extended within a macro "
19364 "which expects all of its arguments on one line such as E<.Ql \\&.Op>."
19367 #. type: Plain text
19368 #: build/C/man7/mdoc.samples.7:1712
19370 "Here is an example of E<.Ql \\&.Xo> using the space mode macro to turn "
19374 #. type: Plain text
19375 #: build/C/man7/mdoc.samples.7:1718
19379 "\\&.It Xo Sy I Ar operation\n"
19380 "\\&.No \\een Ar count No \\een\n"
19385 #. type: Plain text
19386 #: build/C/man7/mdoc.samples.7:1721 build/C/man7/mdoc.samples.7:1742 build/C/man7/mdoc.samples.7:1766
19390 #. type: Plain text
19391 #: build/C/man7/mdoc.samples.7:1724 build/C/man7/mdoc.samples.7:1745
19393 msgid "E<.Sm off>\n"
19397 #: build/C/man7/mdoc.samples.7:1724
19399 msgid "Xo Sy I Ar operation"
19402 #. type: Plain text
19403 #: build/C/man7/mdoc.samples.7:1728
19406 "E<.No \\en Ar count No \\en>\n"
19411 #. type: Plain text
19412 #: build/C/man7/mdoc.samples.7:1732
19413 msgid "Another one:"
19416 #. type: Plain text
19417 #: build/C/man7/mdoc.samples.7:1739
19421 "\\&.It Cm S No \\&/ Ar old_pattern Xo\n"
19422 "\\&.No \\&/ Ar new_pattern\n"
19423 "\\&.No \\&/ Op Cm g\n"
19429 #: build/C/man7/mdoc.samples.7:1745
19431 msgid "Cm S No \\&/ Ar old_pattern Xo"
19434 #. type: Plain text
19435 #: build/C/man7/mdoc.samples.7:1750
19438 "E<.No \\&/ Ar new_pattern>\n"
19439 "E<.No \\&/ Op Cm g>\n"
19444 #. type: Plain text
19445 #: build/C/man7/mdoc.samples.7:1757
19447 "Another example of E<.Ql \\&.Xo> and using enclosure macros: Test the value "
19451 #. type: Plain text
19452 #: build/C/man7/mdoc.samples.7:1763
19457 "\\&.Oo \\e&! Oc Ns Ar variable\n"
19458 "\\&.Op Ar operator variable ...\n"
19463 #: build/C/man7/mdoc.samples.7:1768
19468 #. type: Plain text
19469 #: build/C/man7/mdoc.samples.7:1773
19473 "E<.Oo \\&! Oc Ns Ar variable>\n"
19474 "E<.Op Ar operator variable ...>\n"
19478 #. type: Plain text
19479 #: build/C/man7/mdoc.samples.7:1811
19481 "All of the above examples have used the E<.Ql \\&.Xo> macro on the argument "
19482 "list of the E<.Ql \\&.It> (list-item) macro. The extend macros are not "
19483 "used very often, and when they are it is usually to extend the list-item "
19484 "argument list. Unfortunately, this is also where the extend macros are the "
19485 "most finicky. In the first two examples, spacing was turned off; in the "
19486 "third, spacing was desired in part of the output but not all of it. To make "
19487 "these macros work in this situation make sure the E<.Ql \\&.Xo> and E<.Ql "
19488 "\\&.Xc> macros are placed as shown in the third example. If the E<.Ql "
19489 "\\&.Xo> macro is not alone on the E<.Ql \\&.It> argument list, spacing will "
19490 "be unpredictable. The E<.Ql \\&.Ns> (no space macro) must not occur as the "
19491 "first or last macro on a line in this situation. Out of 900 manual pages "
19492 "(about 1500 actual pages) currently released with E<.Bx> only fifteen use "
19493 "the E<.Ql \\&.Xo> macro."
19497 #: build/C/man7/mdoc.samples.7:1812
19499 msgid "Section Headers"
19502 #. type: Plain text
19503 #: build/C/man7/mdoc.samples.7:1825
19505 "The first three E<.Ql \\&.Sh> section header macros list below are required "
19506 "in every man page. The remaining section headers are recommended at the "
19507 "discretion of the author writing the manual page. The E<.Ql \\&.Sh> macro "
19508 "can take up to nine arguments. It is parsed and but is not callable."
19512 #: build/C/man7/mdoc.samples.7:1826
19514 msgid "\\&.Sh NAME"
19517 #. type: Plain text
19518 #: build/C/man7/mdoc.samples.7:1846
19520 "The E<.Ql \\&.Sh NAME> macro is mandatory. If not specified, the headers, "
19521 "footers and page layout defaults will not be set and things will be rather "
19522 "unpleasant. The E<.Sx NAME> section consists of at least three items. The "
19523 "first is the E<.Ql \\&.Nm> name macro naming the subject of the man page. "
19524 "The second is the Name Description macro, E<.Ql \\&.Nd>, which separates the "
19525 "subject name from the third item, which is the description. The description "
19526 "should be the most terse and lucid possible, as the space available is "
19531 #: build/C/man7/mdoc.samples.7:1846
19533 msgid "\\&.Sh SYNOPSIS"
19536 #. type: Plain text
19537 #: build/C/man7/mdoc.samples.7:1878
19539 "The E<.Sx SYNOPSIS> section describes the typical usage of the subject of a "
19540 "man page. The macros required are either E<.Ql \".Nm\">, E<.Ql \".Cd\">, "
19541 "E<.Ql \".Fn\">, (and possibly E<.Ql \".Fo\">, E<.Ql \".Fc\">, E<.Ql "
19542 "\".Fd\">, E<.Ql \".Ft\"> macros). The function name macro E<.Ql \".Fn\"> is "
19543 "required for manual page sections 2 and 3, the command and general name "
19544 "macro E<.Ql \\&.Nm> is required for sections 1, 5, 6, 7, 8. Section 4 "
19545 "manuals require a E<.Ql \".Nm\">, E<.Ql \".Fd\"> or a E<.Ql \".Cd\"> "
19546 "configuration device usage macro. Several other macros may be necessary to "
19547 "produce the synopsis line as shown below:"
19550 #. type: Plain text
19551 #: build/C/man7/mdoc.samples.7:1885
19555 "E<.Op Fl benstuv>\n"
19560 #. type: Plain text
19561 #: build/C/man7/mdoc.samples.7:1888
19562 msgid "The following macros were used:"
19566 #: build/C/man7/mdoc.samples.7:1889
19572 #: build/C/man7/mdoc.samples.7:1890
19574 msgid "\\&.Op \\&Fl benstuv"
19578 #: build/C/man7/mdoc.samples.7:1891
19580 msgid "\\&.Op \\&Fl"
19584 #: build/C/man7/mdoc.samples.7:1892
19589 #. type: Plain text
19590 #: build/C/man7/mdoc.samples.7:1903
19592 "E<.Sy Note>: The macros E<.Ql \\&.Op>, E<.Ql \\&.Fl>, and E<.Ql \\&.Ar> "
19593 "recognize the pipe bar character E<.Ql \\*(Ba>, so a command line such as:"
19597 #: build/C/man7/mdoc.samples.7:1904
19599 msgid ".Op Fl a | Fl b"
19602 #. type: Plain text
19603 #: build/C/man7/mdoc.samples.7:1913
19605 "will not go orbital. E<.Xr Troff> normally interprets a \\*(Ba as a special "
19606 "operator. See E<.Sx PREDEFINED STRINGS> for a usable \\*(Ba character in "
19607 "other situations."
19611 #: build/C/man7/mdoc.samples.7:1914
19613 msgid "\\&.Sh DESCRIPTION"
19616 #. type: Plain text
19617 #: build/C/man7/mdoc.samples.7:1931
19619 "In most cases the first text in the E<.Sx DESCRIPTION> section is a brief "
19620 "paragraph on the command, function or file, followed by a lexical list of "
19621 "options and respective explanations. To create such a list, the E<.Ql "
19622 "\\&.Bl> begin-list, E<.Ql \\&.It> list-item and E<.Ql \\&.El> end-list "
19623 "macros are used (see E<.Sx Lists and Columns> below)."
19626 #. type: Plain text
19627 #: build/C/man7/mdoc.samples.7:1940
19629 "The following E<.Ql \\&.Sh> section headers are part of the preferred manual "
19630 "page layout and must be used appropriately to maintain consistency. They "
19631 "are listed in the order in which they would be used."
19635 #: build/C/man7/mdoc.samples.7:1941
19637 msgid "\\&.Sh ENVIRONMENT"
19640 #. type: Plain text
19641 #: build/C/man7/mdoc.samples.7:1947
19643 "The E<.Sx ENVIRONMENT> section should reveal any related environment "
19644 "variables and clues to their behavior and/or usage."
19648 #: build/C/man7/mdoc.samples.7:1947
19650 msgid "\\&.Sh EXAMPLES"
19653 #. type: Plain text
19654 #: build/C/man7/mdoc.samples.7:1954
19656 "There are several ways to create examples. See the E<.Sx EXAMPLES> section "
19657 "below for details."
19661 #: build/C/man7/mdoc.samples.7:1954
19663 msgid "\\&.Sh FILES"
19666 #. type: Plain text
19667 #: build/C/man7/mdoc.samples.7:1961
19669 "Files which are used or created by the man page subject should be listed via "
19670 "the E<.Ql \\&.Pa> macro in the E<.Sx FILES> section."
19674 #: build/C/man7/mdoc.samples.7:1961
19676 msgid "\\&.Sh SEE ALSO"
19679 #. type: Plain text
19680 #: build/C/man7/mdoc.samples.7:1975
19682 "References to other material on the man page topic and cross references to "
19683 "other relevant man pages should be placed in the E<.Sx SEE ALSO> section. "
19684 "Cross references are specified using the E<.Ql \\&.Xr> macro. Cross "
19685 "references in the E<.Sx SEE ALSO> section should be sorted by section "
19686 "number, and then placed in alphabetical order and comma separated. For "
19690 #. type: Plain text
19691 #: build/C/man7/mdoc.samples.7:1980
19692 msgid "E<.Xr ls 1>, E<.Xr ps 1>, E<.Xr group 5>, E<.Xr passwd 5>."
19695 #. type: Plain text
19696 #: build/C/man7/mdoc.samples.7:1984
19697 msgid "At this time E<.Xr refer 1> style references are not accommodated."
19701 #: build/C/man7/mdoc.samples.7:1984
19703 msgid "\\&.Sh CONFORMING TO"
19706 #. type: Plain text
19707 #: build/C/man7/mdoc.samples.7:1996
19709 "If the command, library function or file adheres to a specific "
19710 "implementation such as E<.St -p1003.2> or E<.St -ansiC> this should be noted "
19711 "here. If the command does not adhere to any standard, its history should be "
19712 "noted in the E<.Sx HISTORY> section."
19716 #: build/C/man7/mdoc.samples.7:1996
19718 msgid "\\&.Sh HISTORY"
19721 #. type: Plain text
19722 #: build/C/man7/mdoc.samples.7:1999
19724 "Any command which does not adhere to any specific standards should be "
19725 "outlined historically in this section."
19729 #: build/C/man7/mdoc.samples.7:1999
19731 msgid "\\&.Sh AUTHORS"
19734 #. type: Plain text
19735 #: build/C/man7/mdoc.samples.7:2001
19736 msgid "Credits, if need be, should be placed here."
19740 #: build/C/man7/mdoc.samples.7:2001
19742 msgid "\\&.Sh DIAGNOSTICS"
19745 #. type: Plain text
19746 #: build/C/man7/mdoc.samples.7:2003
19747 msgid "Diagnostics from a command should be placed in this section."
19751 #: build/C/man7/mdoc.samples.7:2003
19753 msgid "\\&.Sh ERRORS"
19756 #. type: Plain text
19757 #: build/C/man7/mdoc.samples.7:2009
19759 "Specific error handling, especially from library functions (man page "
19760 "sections 2 and 3) should go here. The E<.Ql \\&.Er> macro is used to "
19761 "specify an errno."
19765 #: build/C/man7/mdoc.samples.7:2009
19767 msgid "\\&.Sh BUGS"
19770 #. type: Plain text
19771 #: build/C/man7/mdoc.samples.7:2011
19772 msgid "Blatant problems with the topic go here..."
19775 #. type: Plain text
19776 #: build/C/man7/mdoc.samples.7:2017
19778 "User specified E<.Ql \\&.Sh> sections may be added, for example, this "
19779 "section was set with:"
19782 #. type: Plain text
19783 #: build/C/man7/mdoc.samples.7:2019
19785 msgid "\\&.Sh PAGE STRUCTURE DOMAIN\n"
19789 #: build/C/man7/mdoc.samples.7:2020
19791 msgid "Paragraphs and Line Spacing."
19795 #: build/C/man7/mdoc.samples.7:2022
19800 #. type: Plain text
19801 #: build/C/man7/mdoc.samples.7:2038
19803 "The E<.Ql \\&.Pp> paragraph command may be used to specify a line space "
19804 "where necessary. The macro is not necessary after a E<.Ql \\&.Sh> or E<.Ql "
19805 "\\&.Ss> macro or before a E<.Ql \\&.Bl> macro. (The E<.Ql \\&.Bl> macro "
19806 "asserts a vertical distance unless the -compact flag is given)."
19809 #. This worked with version one, need to redo for version three
19812 #. .Cw (ax+bx+c) \ is\ produced\ by\ \&
19813 #. .\".Cw (ax+bx+c) \&.Va_by_) \&_and_\& \&[?/]m_b1_e1_f1[?/]\&
19830 #. .Em is produced by
19846 #. This example shows the same equation in a different format.
19850 #. signs were forced with
19854 #. .Cw (ax\ +\ bx\ +\ c) \ is\ produced\ by\ \&
19855 #. .\".Cw (ax+bx+c) \&.Va_by_) \&_and_\& \&[?/]m_b1_e1_f1[?/]\&
19866 #. .Li \&.Cx \e\ +\e\ \e&
19877 #. .Em is produced by
19885 #. .Li \&.Cx \e\ +\e\ \e&
19896 #. The incantation below was
19902 #. .Cw \&[?/]m_b1_e1_f1[?/]\& is\ produced\ by
19904 #. .Li \&.Cx Op Sy ?/
19914 #. .Em is produced by
19916 #. .Li \&.Ar \e\ b1 e1 f1
19928 #: build/C/man7/mdoc.samples.7:2157
19933 #. type: Plain text
19934 #: build/C/man7/mdoc.samples.7:2186
19936 "The only keep that is implemented at this time is for words. The macros are "
19937 "E<.Ql \\&.Bk> (begin-keep) and E<.Ql \\&.Ek> (end-keep). The only option "
19938 "that E<.Ql \\&.Bk> accepts is E<.Fl words> and is useful for preventing line "
19939 "breaks in the middle of options. In the example for the make command-line "
19940 "arguments (see E<.Sx What's in a name>), the keep prevented E<.Xr nroff> "
19941 "from placing up the flag and the argument on separate lines. (Actually, the "
19942 "option macro used to prevent this from occurring, but was dropped when the "
19943 "decision (religious) was made to force right justified margins in E<.Xr "
19944 "troff> as options in general look atrocious when spread across a sparse "
19945 "line. More work needs to be done with the keep macros, a E<.Fl line> option "
19946 "needs to be added.)"
19950 #: build/C/man7/mdoc.samples.7:2186
19952 msgid "Examples and Displays"
19955 #. type: Plain text
19956 #: build/C/man7/mdoc.samples.7:2198
19958 "There are five types of displays, a quickie one line indented display E<.Ql "
19959 "\\&.D1>, a quickie one line literal display E<.Ql \\&.Dl>, and a block "
19960 "literal, block filled and block ragged which use the E<.Ql \\&.Bd> "
19961 "begin-display and E<.Ql \\&.Ed> end-display macros."
19964 #. type: Plain text
19965 #: build/C/man7/mdoc.samples.7:2203
19967 "(D-one) Display one line of indented text. This macro is parsed, but it is "
19972 #: build/C/man7/mdoc.samples.7:2204
19974 msgid "Fl ldghfstru"
19977 #. type: Plain text
19978 #: build/C/man7/mdoc.samples.7:2208
19979 msgid "The above was produced by: E<.Li \\&.Dl Fl ldghfstru>."
19982 #. type: Plain text
19983 #: build/C/man7/mdoc.samples.7:2223
19985 "(D-ell) Display one line of indented E<.Em literal> text. The E<.Ql "
19986 "\\&.Dl> example macro has been used throughout this file. It allows the "
19987 "indent (display) of one line of text. Its default font is set to constant "
19988 "width (literal) however it is parsed and will recognized other macros. It "
19989 "is not callable however."
19993 #: build/C/man7/mdoc.samples.7:2224
19995 msgid "% ls -ldg /usr/local/bin"
19998 #. type: Plain text
19999 #: build/C/man7/mdoc.samples.7:2228
20000 msgid "The above was produced by E<.Li \\&.Dl % ls -ldg /usr/local/bin>."
20003 #. type: Plain text
20004 #: build/C/man7/mdoc.samples.7:2239
20006 "Begin-display. The E<.Ql \\&.Bd> display must be ended with the E<.Ql "
20007 "\\&.Ed> macro. Displays may be nested within displays and lists. E<.Ql "
20008 "\\&.Bd> has the following syntax:"
20012 #: build/C/man7/mdoc.samples.7:2240
20014 msgid ".Bd display-type [-offset offset_value] [-compact]"
20017 #. type: Plain text
20018 #: build/C/man7/mdoc.samples.7:2245
20020 "The display-type must be one of the following four types and may have an "
20021 "offset specifier for indentation: E<.Ql \\&.Bd>."
20024 #. type: Plain text
20025 #: build/C/man7/mdoc.samples.7:2251
20027 "Display a block of text as typed, right (and left) margin edges are left "
20031 #. type: Plain text
20032 #: build/C/man7/mdoc.samples.7:2255
20034 "Display a filled (formatted) block. The block of text is formatted (the "
20035 "edges are filled \\- not left unjustified)."
20038 #. type: Plain text
20039 #: build/C/man7/mdoc.samples.7:2258
20041 "Display a literal block, useful for source code or simple tabbed or spaced "
20046 #: build/C/man7/mdoc.samples.7:2258
20048 msgid "Fl file Ar file_name"
20051 #. type: Plain text
20052 #: build/C/man7/mdoc.samples.7:2267
20054 "The filename following the E<.Fl file> flag is read and displayed. Literal "
20055 "mode is asserted and tabs are set at 8 constant width character intervals, "
20056 "however any E<.Xr troff/ Ns Nm \\-mdoc> commands in file will be processed."
20059 #. type: Plain text
20060 #: build/C/man7/mdoc.samples.7:2273
20062 "If E<.Fl offset> is specified with one of the following strings, the string "
20063 "is interpreted to indicate the level of indentation for the forthcoming "
20067 #. type: Plain text
20068 #: build/C/man7/mdoc.samples.7:2279
20070 "Align block on the current left margin, this is the default mode of E<.Ql "
20074 #. type: Plain text
20075 #: build/C/man7/mdoc.samples.7:2284
20077 "Supposedly center the block. At this time unfortunately, the block merely "
20078 "gets left aligned about an imaginary center margin."
20081 #. type: Plain text
20082 #: build/C/man7/mdoc.samples.7:2293
20084 "Indents by one default indent value or tab. The default indent value is "
20085 "also used for the E<.Ql \\&.D1> display so one is guaranteed the two types "
20086 "of displays will line up. This indent is normally set to 6n or about two "
20087 "thirds of an inch (six constant width characters)."
20090 #. type: Plain text
20091 #: build/C/man7/mdoc.samples.7:2295
20092 msgid "Indents two times the default indent value."
20095 #. type: Plain text
20096 #: build/C/man7/mdoc.samples.7:2303
20098 "This E<.Em left> aligns the block about two inches from the right side of "
20099 "the page. This macro needs work and perhaps may never do the right thing by "
20104 #: build/C/man7/mdoc.samples.7:2304
20109 #. type: Plain text
20110 #: build/C/man7/mdoc.samples.7:2306
20111 msgid "End-display."
20115 #: build/C/man7/mdoc.samples.7:2307
20120 #. type: Plain text
20121 #: build/C/man7/mdoc.samples.7:2309
20122 msgid "There are five macros for changing the appearance of the manual page text:"
20126 #: build/C/man7/mdoc.samples.7:2310
20131 #. type: Plain text
20132 #: build/C/man7/mdoc.samples.7:2315
20134 "Text may be stressed or emphasized with the E<.Ql \\&.Em> macro. The usual "
20135 "font for emphasis is italic."
20139 #: build/C/man7/mdoc.samples.7:2316
20141 msgid "Usage: .Em argument ... \\*(Pu"
20145 #: build/C/man7/mdoc.samples.7:2318
20147 msgid "Li \".Em does not\""
20150 #. type: Plain text
20151 #: build/C/man7/mdoc.samples.7:2320
20152 msgid "E<.Em does not>"
20156 #: build/C/man7/mdoc.samples.7:2320
20158 msgid "Li \".Em exceed 1024 .\""
20161 #. type: Plain text
20162 #: build/C/man7/mdoc.samples.7:2322
20163 msgid "E<.Em exceed 1024>."
20167 #: build/C/man7/mdoc.samples.7:2322
20169 msgid "Li \".Em vide infra ) ) ,\""
20172 #. type: Plain text
20173 #: build/C/man7/mdoc.samples.7:2324
20174 msgid "E<.Em vide infra>)),"
20177 #. type: Plain text
20178 #: build/C/man7/mdoc.samples.7:2332
20180 "The E<.Ql \\&.Em> macro is parsed and is callable. It is an error to call "
20181 "E<.Ql \\&.Em> without arguments."
20185 #: build/C/man7/mdoc.samples.7:2332
20190 #. type: Plain text
20191 #: build/C/man7/mdoc.samples.7:2338
20193 "The E<.Ql \\&.Li> literal macro may be used for special characters, variable "
20194 "constants, anything which should be displayed as it would be typed."
20198 #: build/C/man7/mdoc.samples.7:2339
20200 msgid "Usage: .Li argument ... \\*(Pu"
20204 #: build/C/man7/mdoc.samples.7:2341
20206 msgid "Li \\&.Li \\een"
20209 #. type: Plain text
20210 #: build/C/man7/mdoc.samples.7:2343
20211 msgid "E<.Li \\en>"
20215 #: build/C/man7/mdoc.samples.7:2343
20217 msgid "Li \\&.Li M1 M2 M3\\ ;"
20220 #. type: Plain text
20221 #: build/C/man7/mdoc.samples.7:2345
20222 msgid "E<.Li M1 M2 M3>;"
20226 #: build/C/man7/mdoc.samples.7:2345
20228 msgid "Li \\&.Li cntrl-D\\ )\\ ,"
20231 #. type: Plain text
20232 #: build/C/man7/mdoc.samples.7:2347
20233 msgid "E<.Li cntrl-D>),"
20237 #: build/C/man7/mdoc.samples.7:2347
20239 msgid "Li \\&.Li 1024\\ ..."
20242 #. type: Plain text
20243 #: build/C/man7/mdoc.samples.7:2349
20244 msgid "E<.Li 1024 ...>"
20247 #. type: Plain text
20248 #: build/C/man7/mdoc.samples.7:2354
20249 msgid "The E<.Ql \\&.Li> macro is parsed and is callable."
20253 #: build/C/man7/mdoc.samples.7:2354
20258 #. type: Plain text
20259 #: build/C/man7/mdoc.samples.7:2357
20261 "The symbolic emphasis macro is generally a boldface macro in either the "
20262 "symbolic sense or the traditional English usage."
20266 #: build/C/man7/mdoc.samples.7:2358
20268 msgid "Usage: .Sy symbol ... \\*(Pu"
20272 #: build/C/man7/mdoc.samples.7:2360
20274 msgid "Li \\&.Sy Important Notice"
20277 #. type: Plain text
20278 #: build/C/man7/mdoc.samples.7:2362
20279 msgid "E<.Sy Important Notice>"
20282 #. type: Plain text
20283 #: build/C/man7/mdoc.samples.7:2369
20285 "The E<.Ql \\&.Sy> macro is parsed and is callable. Arguments to E<.Ql "
20286 "\\&.Sy> may be quoted."
20290 #: build/C/man7/mdoc.samples.7:2370
20295 #. type: Plain text
20296 #: build/C/man7/mdoc.samples.7:2380
20298 "Begin font mode. The E<.Ql \\&.Bf> font mode must be ended with the E<.Ql "
20299 "\\&.Ef> macro. Font modes may be nested within other font modes. E<.Ql "
20300 "\\&.Bf> has the following syntax:"
20304 #: build/C/man7/mdoc.samples.7:2381
20306 msgid ".Bf font-mode"
20309 #. type: Plain text
20310 #: build/C/man7/mdoc.samples.7:2385
20311 msgid "The font-mode must be one of the following three types: E<.Ql \\&.Bf>."
20315 #: build/C/man7/mdoc.samples.7:2387
20317 msgid "Sy \\&Em | Fl emphasis"
20320 #. type: Plain text
20321 #: build/C/man7/mdoc.samples.7:2391
20322 msgid "Same as if the E<.Ql \\&.Em> macro was used for the entire block of text."
20326 #: build/C/man7/mdoc.samples.7:2391
20328 msgid "Sy \\&Li | Fl literal"
20331 #. type: Plain text
20332 #: build/C/man7/mdoc.samples.7:2395
20333 msgid "Same as if the E<.Ql \\&.Li> macro was used for the entire block of text."
20337 #: build/C/man7/mdoc.samples.7:2395
20339 msgid "Sy \\&Sy | Fl symbolic"
20342 #. type: Plain text
20343 #: build/C/man7/mdoc.samples.7:2399
20344 msgid "Same as if the E<.Ql \\&.Sy> macro was used for the entire block of text."
20348 #: build/C/man7/mdoc.samples.7:2400
20353 #. type: Plain text
20354 #: build/C/man7/mdoc.samples.7:2402
20355 msgid "End font mode."
20359 #: build/C/man7/mdoc.samples.7:2403
20361 msgid "Tagged Lists and Columns"
20364 #. type: Plain text
20365 #: build/C/man7/mdoc.samples.7:2417
20367 "There are several types of lists which may be initiated with the E<.Ql "
20368 "\".Bl\"> begin-list macro. Items within the list are specified with the "
20369 "E<.Ql \".It\"> item macro and each list must end with the E<.Ql \".El\"> "
20370 "macro. Lists may be nested within themselves and within displays. Columns "
20371 "may be used inside of lists, but lists are unproven inside of columns."
20374 #. type: Plain text
20375 #: build/C/man7/mdoc.samples.7:2432
20377 "In addition, several list attributes may be specified such as the width of a "
20378 "tag, the list offset, and compactness (blank lines between items allowed or "
20379 "disallowed). Most of this document has been formatted with a tag style list "
20380 "E<.Pq Fl tag>. For a change of pace, the list-type used to present the "
20381 "list-types is an over-hanging list E<.Pq Fl ohang>. This type of list is "
20382 "quite popular with E<.Tn TeX> users, but might look a bit funny after having "
20383 "read many pages of tagged lists. The following list types are accepted by "
20388 #: build/C/man7/mdoc.samples.7:2434
20394 #: build/C/man7/mdoc.samples.7:2435
20400 #: build/C/man7/mdoc.samples.7:2436
20405 #. type: Plain text
20406 #: build/C/man7/mdoc.samples.7:2446
20408 "These three are the simplest types of lists. Once the E<.Ql \".Bl\"> macro "
20409 "has been given, items in the list are merely indicated by a line consisting "
20410 "solely of the E<.Ql \".It\"> macro. For example, the source text for a "
20411 "simple enumerated list would look like:"
20414 #. type: Plain text
20415 #: build/C/man7/mdoc.samples.7:2455
20418 "\\&.Bl -enum -compact\n"
20420 "\\&Item one goes here.\n"
20422 "\\&And item two here.\n"
20424 "\\&Lastly item three goes here.\n"
20428 #. type: Plain text
20429 #: build/C/man7/mdoc.samples.7:2459
20430 msgid "The results:"
20433 #. type: Plain text
20434 #: build/C/man7/mdoc.samples.7:2463
20435 msgid "Item one goes here."
20438 #. type: Plain text
20439 #: build/C/man7/mdoc.samples.7:2465
20440 msgid "And item two here."
20443 #. type: Plain text
20444 #: build/C/man7/mdoc.samples.7:2467
20445 msgid "Lastly item three goes here."
20448 #. type: Plain text
20449 #: build/C/man7/mdoc.samples.7:2470
20450 msgid "A simple bullet list construction:"
20453 #. type: Plain text
20454 #: build/C/man7/mdoc.samples.7:2477
20457 "\\&.Bl -bullet -compact\n"
20459 "\\&Bullet one goes here.\n"
20461 "\\&Bullet two here.\n"
20465 #. type: Plain text
20466 #: build/C/man7/mdoc.samples.7:2483
20467 msgid "Bullet one goes here."
20470 #. type: Plain text
20471 #: build/C/man7/mdoc.samples.7:2485
20472 msgid "Bullet two here."
20476 #: build/C/man7/mdoc.samples.7:2488
20482 #: build/C/man7/mdoc.samples.7:2489
20488 #: build/C/man7/mdoc.samples.7:2490
20494 #: build/C/man7/mdoc.samples.7:2491
20500 #: build/C/man7/mdoc.samples.7:2492
20505 #. type: Plain text
20506 #: build/C/man7/mdoc.samples.7:2512
20508 "These list-types collect arguments specified with the E<.Ql \\&.It> macro "
20509 "and create a label which may be E<.Em inset> into the forthcoming text, "
20510 "E<.Em hanged> from the forthcoming text, E<.Em overhanged> from above and "
20511 "not indented or E<.Em tagged>. This list was constructed with the E<.Ql "
20512 "\\&Fl ohang> list-type. The E<.Ql \\&.It> macro is parsed only for the "
20513 "inset, hang and tag list-types and is not callable. Here is an example of "
20518 #: build/C/man7/mdoc.samples.7:2514
20523 #. type: Plain text
20524 #: build/C/man7/mdoc.samples.7:2517
20526 "The tagged list (also called a tagged paragraph) is the most common type of "
20527 "list used in the Berkeley manuals."
20531 #: build/C/man7/mdoc.samples.7:2517
20536 #. type: Plain text
20537 #: build/C/man7/mdoc.samples.7:2521
20539 "Diag lists create section four diagnostic lists and are similar to inset "
20540 "lists except callable macros are ignored."
20544 #: build/C/man7/mdoc.samples.7:2521
20549 #. type: Plain text
20550 #: build/C/man7/mdoc.samples.7:2523
20551 msgid "Hanged labels are a matter of taste."
20555 #: build/C/man7/mdoc.samples.7:2523
20560 #. type: Plain text
20561 #: build/C/man7/mdoc.samples.7:2525
20562 msgid "Overhanging labels are nice when space is constrained."
20566 #: build/C/man7/mdoc.samples.7:2525
20571 #. type: Plain text
20572 #: build/C/man7/mdoc.samples.7:2530
20574 "Inset labels are useful for controlling blocks of paragraphs and are "
20575 "valuable for converting E<.Nm \\-mdoc> manuals to other formats."
20578 #. type: Plain text
20579 #: build/C/man7/mdoc.samples.7:2533
20580 msgid "Here is the source text which produced the above example:"
20583 #. type: Plain text
20584 #: build/C/man7/mdoc.samples.7:2552
20587 "\\&.Bl -inset -offset indent\n"
20589 "\\&The tagged list (also called a tagged paragraph) is the\n"
20590 "\\&most common type of list used in the Berkeley manuals.\n"
20592 "\\&Diag lists create section four diagnostic lists\n"
20593 "\\&and are similar to inset lists except callable\n"
20594 "\\¯os are ignored.\n"
20596 "\\&Hanged labels are a matter of taste.\n"
20597 "\\&.It Em Ohang\n"
20598 "\\&Overhanging labels are nice when space is constrained.\n"
20599 "\\&.It Em Inset\n"
20600 "\\&Inset labels are useful for controlling blocks of\n"
20601 "\\¶graphs and are valuable for converting\n"
20603 "\\&manuals to other formats.\n"
20607 #. type: Plain text
20608 #: build/C/man7/mdoc.samples.7:2555
20609 msgid "Here is a hanged list with two items:"
20613 #: build/C/man7/mdoc.samples.7:2556
20618 #. type: Plain text
20619 #: build/C/man7/mdoc.samples.7:2559
20621 "labels appear similar to tagged lists when the label is smaller than the "
20626 #: build/C/man7/mdoc.samples.7:2559
20628 msgid "Em Longer hanged list labels"
20631 #. type: Plain text
20632 #: build/C/man7/mdoc.samples.7:2562
20633 msgid "blend in to the paragraph unlike tagged paragraph labels."
20636 #. type: Plain text
20637 #: build/C/man7/mdoc.samples.7:2565
20638 msgid "And the unformatted text which created it:"
20641 #. type: Plain text
20642 #: build/C/man7/mdoc.samples.7:2574
20645 "\\&.Bl -hang -offset indent\n"
20646 "\\&.It Em Hanged\n"
20647 "\\&labels appear similar to tagged lists when the\n"
20648 "\\&label is smaller than the label width.\n"
20649 "\\&.It Em Longer hanged list labels\n"
20650 "\\&blend in to the paragraph unlike\n"
20651 "\\&tagged paragraph labels.\n"
20655 #. type: Plain text
20656 #: build/C/man7/mdoc.samples.7:2578
20658 "The tagged list which follows uses an optional width specifier to control "
20659 "the width of the tag."
20663 #: build/C/man7/mdoc.samples.7:2580
20668 #. type: Plain text
20669 #: build/C/man7/mdoc.samples.7:2582
20670 msgid "sleep time of the process (seconds blocked)"
20674 #: build/C/man7/mdoc.samples.7:2582
20679 #. type: Plain text
20680 #: build/C/man7/mdoc.samples.7:2587
20682 "number of disk E<.Tn I/O Ns 's> resulting from references by the process to "
20683 "pages not loaded in core."
20687 #: build/C/man7/mdoc.samples.7:2587
20692 #. type: Plain text
20693 #: build/C/man7/mdoc.samples.7:2589
20694 msgid "numerical user-id of process owner"
20698 #: build/C/man7/mdoc.samples.7:2589
20703 #. type: Plain text
20704 #: build/C/man7/mdoc.samples.7:2592
20706 "numerical ID of parent of process process priority (nonpositive when in "
20707 "noninterruptible wait)"
20710 #. type: Plain text
20711 #: build/C/man7/mdoc.samples.7:2595
20712 msgid "The raw text:"
20715 #. type: Plain text
20716 #: build/C/man7/mdoc.samples.7:2610
20719 "\\&.Bl -tag -width \"PAGEIN\" -compact -offset indent\n"
20721 "\\&sleep time of the process (seconds blocked)\n"
20723 "\\&number of disk\n"
20724 "\\&.Tn I/O Ns 's\n"
20725 "\\&resulting from references\n"
20726 "\\&by the process to pages not loaded in core.\n"
20728 "\\&numerical user ID of process owner\n"
20730 "\\&numerical ID of parent of process process priority\n"
20731 "\\&(nonpositive when in noninterruptible wait)\n"
20735 #. type: Plain text
20736 #: build/C/man7/mdoc.samples.7:2613
20737 msgid "Acceptable width specifiers:"
20741 #: build/C/man7/mdoc.samples.7:2614
20743 msgid "Fl width Ar \\&Fl"
20746 #. type: Plain text
20747 #: build/C/man7/mdoc.samples.7:2623
20749 "sets the width to the default width for a flag. All callable macros have a "
20750 "default width value. The E<.Ql \\&.Fl>, value is presently set to ten "
20751 "constant width characters or about five sixth of an inch."
20755 #: build/C/man7/mdoc.samples.7:2623
20757 msgid "Fl width Ar 24n"
20760 #. type: Plain text
20761 #: build/C/man7/mdoc.samples.7:2629
20763 "sets the width to 24 constant width characters or about two inches. The "
20764 "E<.Ql n> is absolutely necessary for the scaling to work correctly."
20768 #: build/C/man7/mdoc.samples.7:2629
20770 msgid "Fl width Ar ENAMETOOLONG"
20773 #. type: Plain text
20774 #: build/C/man7/mdoc.samples.7:2632
20775 msgid "sets width to the constant width length of the string given."
20779 #: build/C/man7/mdoc.samples.7:2632
20781 msgid "Fl width Ar \"\\*qint mkfifo\\*q\""
20784 #. type: Plain text
20785 #: build/C/man7/mdoc.samples.7:2635
20786 msgid "again, the width is set to the constant width of the string given."
20789 #. type: Plain text
20790 #: build/C/man7/mdoc.samples.7:2649
20792 "If a width is not specified for the tag list type, the first time E<.Ql "
20793 "\\&.It> is invoked, an attempt is made to determine an appropriate width. "
20794 "If the first argument to E<.Ql \".It\"> is a callable macro, the default "
20795 "width for that macro will be used as if the macro name had been supplied as "
20796 "the width. However, if another item in the list is given with a different "
20797 "callable macro name, a new and nested list is assumed."
20801 #: build/C/man7/mdoc.samples.7:2649
20803 msgid "PREDEFINED STRINGS"
20806 #. type: Plain text
20807 #: build/C/man7/mdoc.samples.7:2661
20809 "The following strings are predefined as may be used by preceding with the "
20810 "troff string interpreting sequence E<.Ql \\&\\e*(xx> where E<.Em xx> is the "
20811 "name of the defined string or as E<.Ql \\&\\e*x> where E<.Em x> is the name "
20812 "of the string. The interpreting sequence may be used any where in the text."
20816 #: build/C/man7/mdoc.samples.7:2663
20818 msgid "Sy \"String\tNroff\tTroff\""
20822 #: build/C/man7/mdoc.samples.7:2664
20824 msgid "Li E<lt>= Ta \\&E<lt>\\&= Ta \\*(E<lt>="
20828 #: build/C/man7/mdoc.samples.7:2665
20830 msgid "Li E<gt>= Ta \\&E<gt>\\&= Ta \\*(E<gt>="
20834 #: build/C/man7/mdoc.samples.7:2666
20836 msgid "Li Rq Ta '' Ta \\*(Rq"
20840 #: build/C/man7/mdoc.samples.7:2667
20842 msgid "Li Lq Ta `` Ta \\*(Lq"
20846 #: build/C/man7/mdoc.samples.7:2668
20848 msgid "Li ua Ta ^ Ta \\*(ua"
20852 #: build/C/man7/mdoc.samples.7:2669
20854 msgid "Li aa Ta ' Ta \\*(aa"
20858 #: build/C/man7/mdoc.samples.7:2670
20860 msgid "Li ga Ta \\` Ta \\*(ga"
20863 #. .It Li "sL" Ta ` Ta \*(sL
20864 #. .It Li "sR" Ta ' Ta \*(sR
20866 #: build/C/man7/mdoc.samples.7:2673
20868 msgid "Li q Ta \\(dq Ta \\*q"
20872 #: build/C/man7/mdoc.samples.7:2674
20874 msgid "Li Pi Ta pi Ta \\*(Pi"
20878 #: build/C/man7/mdoc.samples.7:2675
20880 msgid "Li Ne Ta != Ta \\*(Ne"
20884 #: build/C/man7/mdoc.samples.7:2676
20886 msgid "Li Le Ta E<lt>= Ta \\*(Le"
20890 #: build/C/man7/mdoc.samples.7:2677
20892 msgid "Li Ge Ta E<gt>= Ta \\*(Ge"
20896 #: build/C/man7/mdoc.samples.7:2678
20898 msgid "Li Lt Ta E<lt> Ta \\*(Gt"
20902 #: build/C/man7/mdoc.samples.7:2679
20904 msgid "Li Gt Ta E<gt> Ta \\*(Lt"
20908 #: build/C/man7/mdoc.samples.7:2680
20910 msgid "Li Pm Ta +- Ta \\*(Pm"
20914 #: build/C/man7/mdoc.samples.7:2681
20916 msgid "Li If Ta infinity Ta \\*(If"
20920 #: build/C/man7/mdoc.samples.7:2682
20922 msgid "Li Na Ta I<NaN> Ta \\*(Na"
20926 #: build/C/man7/mdoc.samples.7:2683
20928 msgid "Li Ba Ta \\&| Ta \\*(Ba"
20931 #. type: Plain text
20932 #: build/C/man7/mdoc.samples.7:2692
20934 "E<.Sy Note>: The string named E<.Ql q> should be written as E<.Ql \\e*q> "
20935 "since it is only one char."
20939 #: build/C/man7/mdoc.samples.7:2692
20941 msgid "DIAGNOSTICS"
20944 #. type: Plain text
20945 #: build/C/man7/mdoc.samples.7:2725
20947 "The debugging facilities for E<.Nm \\-mdoc> are limited, but can help detect "
20948 "subtle errors such as the collision of an argument name with an internal "
20949 "register or macro name. (A what?) A register is an arithmetic storage "
20950 "class for E<.Xr troff> with a one or two character name. All registers "
20951 "internal to E<.Nm \\-mdoc> for E<.Xr troff> and E<.Xr ditroff> are two "
20952 "characters and of the form E<lt>upper_caseE<gt>E<lt>lower_caseE<gt> such as "
20953 "E<.Ql \\&Ar>, E<lt>lower_caseE<gt>E<lt>upper_caseE<gt> as E<.Ql \\&aR> or "
20954 "E<lt>upper or lower letterE<gt>E<lt>digitE<gt> as E<.Ql \\&C\\&1>. And "
20955 "adding to the muddle, E<.Xr troff> has its own internal registers all of "
20956 "which are either two lowercase characters or a dot plus a letter or "
20957 "metacharacter character. In one of the introduction examples, it was shown "
20958 "how to prevent the interpretation of a macro name with the escape sequence "
20959 "E<.Ql \\e&>. This is sufficient for the internal register names also."
20962 #. Every callable macro name has a corresponding register
20963 #. of the same name (<upper_case><lower_case>).
20964 #. There are also specific registers which have
20965 #. been used for stacks and arrays and are listed in the
20967 #. .Bd -ragged -offset 4n
20968 #. [A-Z][a-z] registers corresponding to macro names (example ``Ar'')
20969 #. [a-z][A-Z] registers corresponding to macro names (example ``aR'')
20970 #. C[0-9] argument types (example C1)
20971 #. O[0-9] offset stack (displays)
20972 #. h[0-9] horizontal spacing stack (lists)
20973 #. o[0-9] offset (stack) (lists)
20974 #. t[0-9] tag stack (lists)
20975 #. v[0-9] vertical spacing stack (lists)
20976 #. w[0-9] width tag/label stack
20979 #. type: Plain text
20980 #: build/C/man7/mdoc.samples.7:2764
20982 "If a nonescaped register name is given in the argument list of a request, "
20983 "unpredictable behavior will occur. In general, any time huge portions of "
20984 "text do not appear where expected in the output, or small strings such as "
20985 "list tags disappear, chances are there is a misunderstanding about an "
20986 "argument type in the argument list. Your mother never intended for you to "
20987 "remember this evil stuff - so here is a way to find out whether or not your "
20988 "arguments are valid: The E<.Ql \\&.Db> (debug) macro displays the "
20989 "interpretation of the argument list for most macros. Macros such as the "
20990 "E<.Ql \\&.Pp> (paragraph) macro do not contain debugging information. All "
20991 "of the callable macros do, and it is strongly advised whenever in doubt, "
20992 "turn on the E<.Ql \\&.Db> macro."
20996 #: build/C/man7/mdoc.samples.7:2765
20998 msgid "Usage: \\&.Db [on | off]"
21001 #. type: Plain text
21002 #: build/C/man7/mdoc.samples.7:2774
21004 "An example of a portion of text with the debug macro placed above and below "
21005 "an artificially created problem (a flag argument E<.Ql \\&aC> which should "
21006 "be E<.Ql \\e&aC> in order to work):"
21009 #. type: Plain text
21010 #: build/C/man7/mdoc.samples.7:2778
21014 "\\&.Op Fl aC Ar file )\n"
21018 #. type: Plain text
21019 #: build/C/man7/mdoc.samples.7:2781
21020 msgid "The resulting output:"
21023 #. type: Plain text
21024 #: build/C/man7/mdoc.samples.7:2796
21028 "DEBUG(argv) MACRO: `.Op' Line #: 2\n"
21029 "\tArgc: 1 Argv: `Fl' Length: 2\n"
21030 "\tSpace: `' Class: Executable\n"
21031 "\tArgc: 2 Argv: `aC' Length: 2\n"
21032 "\tSpace: `' Class: Executable\n"
21033 "\tArgc: 3 Argv: `Ar' Length: 2\n"
21034 "\tSpace: `' Class: Executable\n"
21035 "\tArgc: 4 Argv: `file' Length: 4\n"
21036 "\tSpace: ` ' Class: String\n"
21037 "\tArgc: 5 Argv: `)' Length: 1\n"
21038 "\tSpace: ` ' Class: Closing Punctuation or suffix\n"
21039 "\tMACRO REQUEST: .Op Fl aC Ar file )\n"
21043 #. type: Plain text
21044 #: build/C/man7/mdoc.samples.7:2823
21046 "The first line of information tells the name of the calling macro, here "
21047 "E<.Ql \\&.Op>, and the line number it appears on. If one or more files are "
21048 "involved (especially if text from another file is included), the line number "
21049 "may be bogus. If there is only one file, it should be accurate. The second "
21050 "line gives the argument count, the argument E<.Pq Ql \\&Fl> and its length. "
21051 "If the length of an argument is two characters, the argument is tested to "
21052 "see if it is executable (unfortunately, any register which contains a "
21053 "nonzero value appears executable). The third line gives the space allotted "
21054 "for a class, and the class type. The problem here is the argument aC should "
21055 "not be executable. The four types of classes are string, executable, "
21056 "closing punctuation and opening punctuation. The last line shows the entire "
21057 "argument list as it was read. In this next example, the offending E<.Ql "
21058 "\\&aC> is escaped:"
21061 #. type: Plain text
21062 #: build/C/man7/mdoc.samples.7:2827
21066 "\\&.Em An escaped \\e&aC\n"
21070 #. type: Plain text
21071 #: build/C/man7/mdoc.samples.7:2839
21075 "DEBUG(fargv) MACRO: `.Em' Line #: 2\n"
21076 "\tArgc: 1 Argv: `An' Length: 2\n"
21077 "\tSpace: ` ' Class: String\n"
21078 "\tArgc: 2 Argv: `escaped' Length: 7\n"
21079 "\tSpace: ` ' Class: String\n"
21080 "\tArgc: 3 Argv: `aC' Length: 2\n"
21081 "\tSpace: ` ' Class: String\n"
21082 "\tMACRO REQUEST: .Em An escaped &aC\n"
21086 #. type: Plain text
21087 #: build/C/man7/mdoc.samples.7:2849
21089 "The argument E<.Ql \\e&aC> shows up with the same length of 2 as the E<.Ql "
21090 "\\e&> sequence produces a zero width, but a register named E<.Ql \\e&aC> was "
21091 "not found and the type classified as string."
21094 #. type: Plain text
21095 #: build/C/man7/mdoc.samples.7:2851
21096 msgid "Other diagnostics consist of usage statements and are self explanatory."
21100 #: build/C/man7/mdoc.samples.7:2851
21102 msgid "GROFF, TROFF AND NROFF"
21105 #. type: Plain text
21106 #: build/C/man7/mdoc.samples.7:2856
21108 "The E<.Nm \\-mdoc> package does not need compatibility mode with E<.Xr "
21112 #. type: Plain text
21113 #: build/C/man7/mdoc.samples.7:2874
21115 "The package inhibits page breaks, and the headers and footers which normally "
21116 "occur at those breaks with E<.Xr nroff>, to make the manual more efficient "
21117 "for viewing on-line. At the moment, E<.Xr groff> with E<.Fl T Ns Ar ascii> "
21118 "does eject the imaginary remainder of the page at end of file. The "
21119 "inhibiting of the page breaks makes E<.Xr nroff Ns 'd> files unsuitable for "
21120 "hardcopy. There is a register named E<.Ql \\&cR> which can be set to zero "
21121 "in the site dependent style file E<.Pa /usr/src/share/tmac/doc-nroff> to "
21122 "restore the old style behavior."
21126 #: build/C/man7/mdoc.samples.7:2876
21128 msgid "Pa /usr/share/tmac/doc.tmac"
21131 #. type: Plain text
21132 #: build/C/man7/mdoc.samples.7:2878
21133 msgid "manual macro package"
21137 #: build/C/man7/mdoc.samples.7:2878
21139 msgid "Pa /usr/share/misc/mdoc.template"
21142 #. type: Plain text
21143 #: build/C/man7/mdoc.samples.7:2880
21144 msgid "template for writing a man page"
21148 #: build/C/man7/mdoc.samples.7:2880
21150 msgid "Pa /usr/share/examples/mdoc/*"
21153 #. type: Plain text
21154 #: build/C/man7/mdoc.samples.7:2882
21155 msgid "several example man pages"
21158 #. type: Plain text
21159 #: build/C/man7/mdoc.samples.7:2890
21161 "Undesirable hyphenation on the dash of a flag argument is not yet resolved, "
21162 "and causes occasional mishaps in the E<.Sx DESCRIPTION> section. (line "
21163 "break on the hyphen)."
21166 #. type: Plain text
21167 #: build/C/man7/mdoc.samples.7:2892
21168 msgid "Predefined strings are not declared in documentation."
21171 #. type: Plain text
21172 #: build/C/man7/mdoc.samples.7:2894
21173 msgid "Section 3f has not been added to the header routines."
21176 #. type: Plain text
21177 #: build/C/man7/mdoc.samples.7:2899
21178 msgid "E<.Ql \\&.Nm> font should be changed in E<.Sx NAME> section."
21181 #. type: Plain text
21182 #: build/C/man7/mdoc.samples.7:2906
21184 "E<.Ql \\&.Fn> needs to have a check to prevent splitting up if the line "
21185 "length is too short. Occasionally it separates the last parenthesis, and "
21186 "sometimes looks ridiculous if a line is in fill mode."
21189 #. type: Plain text
21190 #: build/C/man7/mdoc.samples.7:2911
21192 "The method used to prevent header and footer page breaks (other than the "
21193 "initial header and footer) when using nroff occasionally places an unsightly "
21194 "partially filled line (blank) at the would be bottom of the page."
21197 #. Note what happens if the parameter list overlaps a newline
21199 #. to make sure a line boundary is crossed:
21201 #. \&.Fn struct\e\ dictionarytable\e\ *dictionarylookup struct\e\ dictionarytable\e\ *tab[]
21204 #. produces, nudge nudge,
21205 #. .Fn struct\ dictionarytable\ *dictionarylookup char\ *h struct\ dictionarytable\ *tab[] ,
21206 #. .Fn struct\ dictionarytable\ *dictionarylookup char\ *h struct\ dictionarytable\ *tab[] ,
21208 #. .Fn struct\ dictionarytable\ *dictionarylookup char\ *h struct\ dictionarytable\ *tab[] .
21210 #. If double quotes are used, for example:
21212 #. \&.Fn \*qstruct dictionarytable *dictionarylookup\*q \*qchar *h\*q \*qstruct dictionarytable *tab[]\*q
21215 #. produces, nudge nudge,
21216 #. .Fn "struct dictionarytable *dictionarylookup" "char *h" "struct dictionarytable *tab[]" ,
21218 #. .Fn "struct dictionarytable *dictionarylookup" "char *h" "struct dictionarytable *tab[]" ,
21220 #. .Fn "struct dictionarytable *dictionarylookup" "char *h" "struct dictionarytable *tab[]" .
21222 #. Not a pretty sight...
21223 #. In a paragraph, a long parameter containing unpaddable spaces as
21224 #. in the former example will cause
21226 #. to break the line and spread
21227 #. the remaining words out.
21228 #. The latter example will adjust nicely to
21229 #. justified margins, but may break in between an argument and its
21233 #. the right margin adjustment is normally ragged and the problem is
21235 #. type: Plain text
21236 #: build/C/man7/mdoc.samples.7:2952
21238 "The list and display macros to not do any keeps and certainly should be able "
21242 #. type: Plain text
21243 #: build/C/man7/mdoc.samples.7:2957
21244 msgid "E<.Xr man 1>, E<.Xr troff 1>, E<.Xr groff_mdoc 7>, E<.Xr mdoc 7>"