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: 2012-05-28 07:16+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:26 build/C/man2/intro.2:27 build/C/man3/intro.3:24 build/C/man4/intro.4:25 build/C/man5/intro.5:26 build/C/man6/intro.6:25 build/C/man7/intro.7:27 build/C/man8/intro.8:28 build/C/man7/libc.7:24 build/C/man7/mailaddr.7:26 build/C/man7/man-pages.7:28 build/C/man7/man.7:32 build/C/man7/mdoc.7:42 build/C/man7/operator.7:38 build/C/man5/proc.5:61 build/C/man7/standards.7:25 build/C/man7/suffixes.7:38 build/C/man3/undocumented.3:29 build/C/man2/unimplemented.2:27 build/C/man7/units.7:24
38 #: build/C/man7/feature_test_macros.7:25 build/C/man2/intro.2:27 build/C/man3/intro.3:24 build/C/man4/intro.4:25 build/C/man5/intro.5:26 build/C/man6/intro.6:25 build/C/man7/intro.7:27 build/C/man8/intro.8:28 build/C/man7/libc.7:24 build/C/man7/man-pages.7:28 build/C/man7/man.7:32 build/C/man7/operator.7:38 build/C/man7/posixoptions.7:23 build/C/man5/proc.5:61 build/C/man7/standards.7:25 build/C/man7/suffixes.7:38 build/C/man3/undocumented.3:29 build/C/man2/unimplemented.2:27 build/C/man7/units.7:24
40 msgid "Linux Programmer's Manual"
44 #: build/C/man7/feature_test_macros.7:26 build/C/man1/intro.1:27 build/C/man2/intro.2:28 build/C/man3/intro.3:25 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:25 build/C/man7/mailaddr.7:28 build/C/man7/man-pages.7:29 build/C/man7/man.7:33 build/C/man7/mdoc.7:43 build/C/man7/operator.7:39 build/C/man7/posixoptions.7:24 build/C/man5/proc.5:62 build/C/man7/standards.7:26 build/C/man7/suffixes.7:39 build/C/man3/undocumented.3:30 build/C/man2/unimplemented.2:28 build/C/man7/units.7:25 build/C/man7/mdoc.samples.7:42
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:31 build/C/man7/man.7:35 build/C/man7/mdoc.7:48 build/C/man3/undocumented.3:32 build/C/man2/unimplemented.2:31 build/C/man7/mdoc.samples.7:48
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:29 build/C/man2/intro.2:30 build/C/man3/intro.3:27 build/C/man4/intro.4:28 build/C/man5/intro.5:29 build/C/man6/intro.6:28 build/C/man7/intro.7:30 build/C/man8/intro.8:31 build/C/man7/libc.7:27 build/C/man7/mailaddr.7:30 build/C/man7/man-pages.7:35 build/C/man7/man.7:47 build/C/man7/mdoc.7:52 build/C/man7/operator.7:41 build/C/man7/posixoptions.7:26 build/C/man5/proc.5:64 build/C/man7/standards.7:28 build/C/man7/suffixes.7:41 build/C/man3/undocumented.3:34 build/C/man2/unimplemented.2:33 build/C/man7/units.7:27 build/C/man7/mdoc.samples.7:50
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:81
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:86
147 "#define _BSD_SOURCE\n"
148 "#define _XOPEN_SOURCE /* or any value E<lt> 500 */\n"
152 #: build/C/man7/feature_test_macros.7:91
154 "Alternatively, equivalent definitions can be included in the compilation "
159 #: build/C/man7/feature_test_macros.7:96
163 "cc -D_XOPEN_SOURCE # Or any value E<lt> 500\n"
167 #: build/C/man7/feature_test_macros.7:104
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:108
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:113
185 "B<#define _GNU_SOURCE>\n"
186 "B<#include E<lt>fcntl.hE<gt>>\n"
190 #: build/C/man7/feature_test_macros.7:115
193 "B<ssize_t readahead(int >I<fd>B<, off64_t *>I<offset>B<, size_t "
198 #: build/C/man7/feature_test_macros.7:121
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:121
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:127
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:129
223 msgid "Linux glibc understands the following feature test macros:"
227 #: build/C/man7/feature_test_macros.7:129
229 msgid "B<__STRICT_ANSI__>"
233 #: build/C/man7/feature_test_macros.7:139
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:139
242 msgid "B<_POSIX_C_SOURCE>"
246 #: build/C/man7/feature_test_macros.7:142 build/C/man7/feature_test_macros.7:173
247 msgid "Defining this macro causes header files to expose definitions as follows:"
251 #: build/C/man7/feature_test_macros.7:143 build/C/man7/feature_test_macros.7:146 build/C/man7/feature_test_macros.7:149 build/C/man7/feature_test_macros.7:153 build/C/man7/feature_test_macros.7:156 build/C/man7/feature_test_macros.7:160 build/C/man7/feature_test_macros.7:174 build/C/man7/feature_test_macros.7:177 build/C/man7/feature_test_macros.7:180 build/C/man7/feature_test_macros.7:184 build/C/man7/feature_test_macros.7:407 build/C/man7/feature_test_macros.7:412 build/C/man7/feature_test_macros.7:418 build/C/man7/feature_test_macros.7:423 build/C/man7/feature_test_macros.7:429 build/C/man7/feature_test_macros.7:434
257 #: build/C/man7/feature_test_macros.7:146
258 msgid "The value 1 exposes definitions conforming to POSIX.1-1990 and ISO C (1990)."
262 #: build/C/man7/feature_test_macros.7:149
263 msgid "The value 2 or greater additionally exposes definitions for POSIX.2-1992."
266 #. 199506L functionality is only available since glibc 2.1
268 #: build/C/man7/feature_test_macros.7:153
270 "The value 199309L or greater additionally exposes definitions for POSIX.1b "
271 "(real-time extensions)."
275 #: build/C/man7/feature_test_macros.7:156
277 "The value 199506L or greater additionally exposes definitions for POSIX.1c "
282 #: build/C/man7/feature_test_macros.7:160
284 "(Since glibc 2.3.3) The value 200112L or greater exposes definitions "
285 "corresponding to the POSIX.1-2001 base specification (excluding the XSI "
290 #: build/C/man7/feature_test_macros.7:164
292 "(Since glibc 2.10) The value 200809L or greater exposes definitions "
293 "corresponding to the POSIX.1-2008 base specification (excluding the XSI "
298 #: build/C/man7/feature_test_macros.7:165
300 msgid "B<_POSIX_SOURCE>"
304 #: build/C/man7/feature_test_macros.7:170
306 "Defining this obsolete macro with any value is equivalent to defining "
307 "B<_POSIX_C_SOURCE> with the value 1."
311 #: build/C/man7/feature_test_macros.7:170
313 msgid "B<_XOPEN_SOURCE>"
317 #: build/C/man7/feature_test_macros.7:177
319 "Defining with any value exposes definitions conforming to POSIX.1, POSIX.2, "
324 #: build/C/man7/feature_test_macros.7:180
326 "The value 500 or greater additionally exposes definitions for SUSv2 (UNIX "
331 #: build/C/man7/feature_test_macros.7:184
333 "(Since glibc 2.2) The value 600 or greater additionally exposes definitions "
334 "for SUSv3 (UNIX 03; i.e., the POSIX.1-2001 base specification plus the XSI "
335 "extension) and C99 definitions."
339 #: build/C/man7/feature_test_macros.7:188
341 "(Since glibc 2.10) The value 700 or greater additionally exposes definitions "
342 "for SUSv4 (i.e., the POSIX.1-2008 base specification plus the XSI "
347 #: build/C/man7/feature_test_macros.7:189
349 msgid "B<_XOPEN_SOURCE_EXTENDED>"
353 #: build/C/man7/feature_test_macros.7:198
355 "If this macro is defined, and B<_XOPEN_SOURCE> is defined, then expose "
356 "definitions corresponding to the XPG4v2 (SUSv1) UNIX extensions (UNIX 95). "
357 "This macro is also implicitly defined if B<_XOPEN_SOURCE> is defined with a "
358 "value of 500 or more."
362 #: build/C/man7/feature_test_macros.7:198
364 msgid "B<_ISOC95_SOURCE>"
368 #: build/C/man7/feature_test_macros.7:208
370 "Exposes ISO C (1990) Amendment 1 definitions (also known as C95). This "
371 "macro is recognized since glibc 2.12. The primary change in C95 was support "
372 "for international character sets. The C95 changes were included in the "
373 "subsequent C99 standard (in other words, B<_ISOC99_SOURCE> implies "
374 "B<_ISOC95_SOURCE>)."
378 #: build/C/man7/feature_test_macros.7:208
380 msgid "B<_ISOC99_SOURCE>"
384 #: build/C/man7/feature_test_macros.7:217
386 "Exposes C99 extensions to ISO C (1990). This macro is recognized since "
387 "glibc 2.1.3; earlier glibc 2.1.x versions recognized an equivalent macro "
388 "named B<_ISOC9X_SOURCE> (because the C99 standard had not then been "
389 "finalized). Although the use of the latter macro is obsolete, glibc "
390 "continues to recognize it for backward compatibility."
394 #: build/C/man7/feature_test_macros.7:217
396 msgid "B<_ISOC11_SOURCE>"
400 #: build/C/man7/feature_test_macros.7:221
402 "Exposes declarations consistent with the ISO C11 standard. This macro is "
403 "recognized since glibc 2.16."
407 #: build/C/man7/feature_test_macros.7:221
409 msgid "B<_LARGEFILE64_SOURCE>"
413 #: build/C/man7/feature_test_macros.7:240
415 "Expose definitions for the alternative API specified by the LFS (Large File "
416 "Summit) as a \"transitional extension\" to the Single UNIX Specification. "
417 "(See http://opengroup.org/platform/lfs.html.) The alternative API consists "
418 "of a set of new objects (i.e., functions and types) whose names are suffixed "
419 "with \"64\" (e.g., I<off64_t> versus I<off_t>, B<lseek64>() versus "
420 "B<lseek>(), etc.). New programs should not employ this interface; instead "
421 "I<_FILE_OFFSET_BITS=64> should be employed."
425 #: build/C/man7/feature_test_macros.7:240
427 msgid "B<_FILE_OFFSET_BITS>"
431 #: build/C/man7/feature_test_macros.7:252
433 "Defining this macro with the value 64 automatically converts references to "
434 "32-bit functions and data types related to file I/O and file system "
435 "operations into references to their 64-bit counterparts. This is useful for "
436 "performing I/O on large files (E<gt> 2 Gigabytes) on 32-bit systems. "
437 "(Defining this macro permits correctly written programs to use large files "
438 "with only a recompilation being required.) 64-bit systems naturally permit "
439 "file sizes greater than 2 Gigabytes, and on those systems this macro has no "
444 #: build/C/man7/feature_test_macros.7:252
446 msgid "B<_BSD_SOURCE>"
450 #: build/C/man7/feature_test_macros.7:266
452 "Defining this macro with any value causes header files to expose BSD-derived "
453 "definitions. Defining this macro also causes BSD definitions to be "
454 "preferred in some situations where standards conflict, unless one or more of "
455 "B<_SVID_SOURCE>, B<_POSIX_SOURCE>, B<_POSIX_C_SOURCE>, B<_XOPEN_SOURCE>, "
456 "B<_XOPEN_SOURCE_EXTENDED>, or B<_GNU_SOURCE> is defined, in which case BSD "
457 "definitions are disfavored."
461 #: build/C/man7/feature_test_macros.7:266
463 msgid "B<_SVID_SOURCE>"
467 #: build/C/man7/feature_test_macros.7:272
469 "Defining this macro with any value causes header files to expose System "
470 "V-derived definitions. (SVID == System V Interface Definition; see "
475 #: build/C/man7/feature_test_macros.7:272
477 msgid "B<_ATFILE_SOURCE> (since glibc 2.4)"
481 #: build/C/man7/feature_test_macros.7:281
483 "Defining this macro with any value causes header files to expose "
484 "declarations of a range of functions with the suffix \"at\"; see "
485 "B<openat>(2). Since glibc 2.10, this macro is also implicitly defined if "
486 "B<_POSIX_C_SOURCE> is defined with a value greater than or equal to 200809L."
490 #: build/C/man7/feature_test_macros.7:281
492 msgid "B<_GNU_SOURCE>"
496 #: build/C/man7/feature_test_macros.7:303
498 "Defining this macro (with any value) is equivalent to defining "
499 "B<_BSD_SOURCE>, B<_SVID_SOURCE>, B<_ATFILE_SOURCE>, B<_LARGEFILE64_SOURCE>, "
500 "B<_ISOC99_SOURCE>, B<_XOPEN_SOURCE_EXTENDED>, B<_POSIX_SOURCE>, "
501 "B<_POSIX_C_SOURCE> with the value 200809L (200112L in glibc versions before "
502 "2.10; 199506L in glibc versions before 2.5; 199309L in glibc versions before "
503 "2.1) and B<_XOPEN_SOURCE> with the value 700 (600 in glibc versions before "
504 "2.10; 500 in glibc versions before 2.2). In addition, various GNU-specific "
505 "extensions are also exposed. Where standards conflict, BSD definitions are "
510 #: build/C/man7/feature_test_macros.7:303
512 msgid "B<_REENTRANT>"
516 #: build/C/man7/feature_test_macros.7:309
518 "Defining this macro exposes definitions of certain reentrant functions. For "
519 "multithreaded programs, use I<cc\\ -pthread> instead."
523 #: build/C/man7/feature_test_macros.7:309
525 msgid "B<_THREAD_SAFE>"
529 #: build/C/man7/feature_test_macros.7:314
531 "Synonym for B<_REENTRANT>, provided for compatibility with some other "
536 #: build/C/man7/feature_test_macros.7:314
538 msgid "B<_FORTIFY_SOURCE> (since glibc 2.3.4)"
541 #. For more detail, see:
542 #. http://gcc.gnu.org/ml/gcc-patches/2004-09/msg02055.html
543 #. [PATCH] Object size checking to prevent (some) buffer overflows
544 #. * From: Jakub Jelinek <jakub at redhat dot com>
545 #. * To: gcc-patches at gcc dot gnu dot org
546 #. * Date: Tue, 21 Sep 2004 04:16:40 -0400
548 #: build/C/man7/feature_test_macros.7:360
550 "Defining this macro causes some lightweight checks to be performed to detect "
551 "some buffer overflow errors when employing various string and memory "
552 "manipulation functions. Not all buffer overflows are detected, just some "
553 "common cases. In the current implementation checks are added for calls to "
554 "B<memcpy>(3), B<mempcpy>(3), B<memmove>(3), B<memset>(3), B<stpcpy>(3), "
555 "B<strcpy>(3), B<strncpy>(3), B<strcat>(3), B<strncat>(3), B<sprintf>(3), "
556 "B<snprintf>(3), B<vsprintf>(3), B<vsnprintf>(3), and B<gets>(3). If "
557 "B<_FORTIFY_SOURCE> is set to 1, with compiler optimization level 1 (I<gcc\\ "
558 "-O1>) and above, checks that shouldn't change the behavior of conforming "
559 "programs are performed. With B<_FORTIFY_SOURCE> set to 2 some more checking "
560 "is added, but some conforming programs might fail. Some of the checks can "
561 "be performed at compile time, and result in compiler warnings; other checks "
562 "take place at run time, and result in a run-time error if the check fails. "
563 "Use of this macro requires compiler support, available with B<gcc>(1) since "
568 #: build/C/man7/feature_test_macros.7:360
570 msgid "Default definitions, implicit definitions, and combining definitions"
574 #: build/C/man7/feature_test_macros.7:372
576 "If no feature test macros are explicitly defined, then the following feature "
577 "test macros are defined by default: B<_BSD_SOURCE>, B<_SVID_SOURCE>, "
578 "B<_POSIX_SOURCE>, and B<_POSIX_C_SOURCE>=200809L (200112L in glibc versions "
579 "before 2.10; 199506L in glibc versions before 2.4; 199309L in glibc versions "
584 #: build/C/man7/feature_test_macros.7:388
586 "If any of B<__STRICT_ANSI__>, B<_ISOC99_SOURCE>, B<_POSIX_SOURCE>, "
587 "B<_POSIX_C_SOURCE>, B<_XOPEN_SOURCE>, B<_XOPEN_SOURCE_EXTENDED>, "
588 "B<_BSD_SOURCE>, or B<_SVID_SOURCE> is explicitly defined, then "
589 "B<_BSD_SOURCE>, and B<_SVID_SOURCE> are not defined by default."
593 #: build/C/man7/feature_test_macros.7:399
595 "If B<_POSIX_SOURCE> and B<_POSIX_C_SOURCE> are not explicitly defined, and "
596 "either B<__STRICT_ANSI__> is not defined or B<_XOPEN_SOURCE> is defined with "
597 "a value of 500 or more, then"
601 #: build/C/man7/feature_test_macros.7:400 build/C/man7/feature_test_macros.7:403 build/C/man7/man-pages.7:490 build/C/man7/man-pages.7:493 build/C/man7/man-pages.7:500 build/C/man7/man-pages.7:504 build/C/man7/man-pages.7:508 build/C/man7/man-pages.7:512 build/C/man7/man-pages.7:518 build/C/man5/proc.5:594 build/C/man5/proc.5:598 build/C/man5/proc.5:601 build/C/man5/proc.5:603 build/C/man5/proc.5:606 build/C/man5/proc.5:1010 build/C/man5/proc.5:1013 build/C/man5/proc.5:1025 build/C/man5/proc.5:1028 build/C/man5/proc.5:1032 build/C/man5/proc.5:1035 build/C/man5/proc.5:1038 build/C/man5/proc.5:1041 build/C/man5/proc.5:1044 build/C/man5/proc.5:1047 build/C/man5/proc.5:1050 build/C/man5/proc.5:1053 build/C/man5/proc.5:1057 build/C/man5/proc.5:1060 build/C/man5/proc.5:1063 build/C/man5/proc.5:1066 build/C/man5/proc.5:1069 build/C/man5/proc.5:1072 build/C/man5/proc.5:1075 build/C/man5/proc.5:1086 build/C/man5/proc.5:1092 build/C/man5/proc.5:1096 build/C/man5/proc.5:1101 build/C/man5/proc.5:1106 build/C/man5/proc.5:1111 build/C/man5/proc.5:1116 build/C/man5/proc.5:1121 build/C/man5/proc.5:1126 build/C/man5/proc.5:1841 build/C/man5/proc.5:1845 build/C/man5/proc.5:1848 build/C/man5/proc.5:1853
607 #: build/C/man7/feature_test_macros.7:403
608 msgid "B<_POSIX_SOURCE> is defined with the value 1; and"
612 #: build/C/man7/feature_test_macros.7:406
613 msgid "B<_POSIX_C_SOURCE> is defined with one of the following values:"
617 #: build/C/man7/feature_test_macros.7:412
618 msgid "2, if B<XOPEN_SOURCE> is defined with a value less than 500;"
622 #: build/C/man7/feature_test_macros.7:418
624 "199506L, if B<XOPEN_SOURCE> is defined with a value greater than or equal to "
625 "500 and less than 600; or"
629 #: build/C/man7/feature_test_macros.7:423
631 "(since glibc 2.4) 200112L, if B<XOPEN_SOURCE> is defined with a value "
632 "greater than or equal to 600 and less than 700."
636 #: build/C/man7/feature_test_macros.7:429
638 "(Since glibc 2.10) 200809L, if B<XOPEN_SOURCE> is defined with a value "
639 "greater than or equal to 700."
643 #: build/C/man7/feature_test_macros.7:434
645 "Older versions of glibc do not know about the values 200112L and 200809L for "
646 "B<_POSIX_C_SOURCE>, and the setting of this macro will depend on the glibc "
651 #: build/C/man7/feature_test_macros.7:443
653 "If B<_XOPEN_SOURCE> is undefined, then the setting of B<_POSIX_C_SOURCE> "
654 "depends on the glibc version: 199506L, in glibc versions before 2.4; "
655 "200112L, in glibc 2.4 to 2.9; and 200809L, since glibc 2.10."
659 #: build/C/man7/feature_test_macros.7:447
660 msgid "Multiple macros can be defined; the results are additive."
664 #: build/C/man7/feature_test_macros.7:447 build/C/man2/intro.2:68 build/C/man3/intro.3:85 build/C/man7/suffixes.7:275
666 msgid "CONFORMING TO"
670 #: build/C/man7/feature_test_macros.7:455
672 "POSIX.1 specifies B<_POSIX_C_SOURCE>, B<_POSIX_SOURCE>, and "
673 "B<_XOPEN_SOURCE>. B<_XOPEN_SOURCE_EXTENDED> was specified by XPG4v2 (aka "
678 #: build/C/man7/feature_test_macros.7:459
680 "B<_FILE_OFFSET_BITS> is not specified by any standard, but is employed on "
681 "some other implementations."
685 #: build/C/man7/feature_test_macros.7:469
687 "B<_BSD_SOURCE>, B<_SVID_SOURCE>, B<_ATFILE_SOURCE>, B<_GNU_SOURCE>, "
688 "B<_FORTIFY_SOURCE>, B<_REENTRANT>, and B<_THREAD_SAFE> are specific to Linux "
693 #: build/C/man7/feature_test_macros.7:469 build/C/man1/intro.1:46 build/C/man2/intro.2:73 build/C/man3/intro.3:90 build/C/man4/intro.4:32 build/C/man5/intro.5:32 build/C/man6/intro.6:31 build/C/man7/intro.7:35 build/C/man8/intro.8:43 build/C/man7/man.7:476 build/C/man5/proc.5:2731 build/C/man2/unimplemented.2:40
699 #: build/C/man7/feature_test_macros.7:476
701 "I<E<lt>features.hE<gt>> is a Linux/glibc-specific header file. Other "
702 "systems have an analogous file, but typically with a different name. This "
703 "header file is automatically included by other header files as required: it "
704 "is not necessary to explicitly include it in order to employ feature test "
709 #: build/C/man7/feature_test_macros.7:486
711 "According to which of the above feature test macros are defined, "
712 "I<E<lt>features.hE<gt>> internally defines various other macros that are "
713 "checked by other glibc header files. These macros have names prefixed by "
714 "two underscores (e.g., B<__USE_MISC>). Programs should I<never> define "
715 "these macros directly: instead, the appropriate feature test macro(s) from "
716 "the list above should be employed."
720 #: build/C/man7/feature_test_macros.7:486 build/C/man7/man-pages.7:538
726 #: build/C/man7/feature_test_macros.7:492
728 "The program below can be used to explore how the various feature test macros "
729 "are set depending on the glibc version and what feature test macros are "
730 "explicitly set. The following shell session, on a system with glibc 2.10, "
731 "shows some examples of what we would see:"
735 #: build/C/man7/feature_test_macros.7:519
740 "_POSIX_SOURCE defined\n"
741 "_POSIX_C_SOURCE defined: 200809L\n"
742 "_BSD_SOURCE defined\n"
743 "_SVID_SOURCE defined\n"
744 "_ATFILE_SOURCE defined\n"
745 "$ B<cc -D_XOPEN_SOURCE=500 ftm.c>\n"
747 "_POSIX_SOURCE defined\n"
748 "_POSIX_C_SOURCE defined: 199506L\n"
749 "_XOPEN_SOURCE defined: 500\n"
750 "$ B<cc -D_GNU_SOURCE ftm.c>\n"
752 "_POSIX_SOURCE defined\n"
753 "_POSIX_C_SOURCE defined: 200809L\n"
754 "_ISOC99_SOURCE defined\n"
755 "_XOPEN_SOURCE defined: 700\n"
756 "_XOPEN_SOURCE_EXTENDED defined\n"
757 "_LARGEFILE64_SOURCE defined\n"
758 "_BSD_SOURCE defined\n"
759 "_SVID_SOURCE defined\n"
760 "_ATFILE_SOURCE defined\n"
761 "_GNU_SOURCE defined\n"
765 #: build/C/man7/feature_test_macros.7:521
767 msgid "Program source"
771 #: build/C/man7/feature_test_macros.7:525
773 msgid "/* ftm.c */\n"
777 #: build/C/man7/feature_test_macros.7:529
780 "#include E<lt>stdio.hE<gt>\n"
781 "#include E<lt>unistd.hE<gt>\n"
782 "#include E<lt>stdlib.hE<gt>\n"
786 #: build/C/man7/feature_test_macros.7:536
790 "main(int argc, char *argv[])\n"
792 "#ifdef _POSIX_SOURCE\n"
793 " printf(\"_POSIX_SOURCE defined\\en\");\n"
798 #: build/C/man7/feature_test_macros.7:540
801 "#ifdef _POSIX_C_SOURCE\n"
802 " printf(\"_POSIX_C_SOURCE defined: %ldL\\en\", (long) _POSIX_C_SOURCE);\n"
807 #: build/C/man7/feature_test_macros.7:544
810 "#ifdef _ISOC99_SOURCE\n"
811 " printf(\"_ISOC99_SOURCE defined\\en\");\n"
816 #: build/C/man7/feature_test_macros.7:548
819 "#ifdef _XOPEN_SOURCE\n"
820 " printf(\"_XOPEN_SOURCE defined: %d\\en\", _XOPEN_SOURCE);\n"
825 #: build/C/man7/feature_test_macros.7:552
828 "#ifdef _XOPEN_SOURCE_EXTENDED\n"
829 " printf(\"_XOPEN_SOURCE_EXTENDED defined\\en\");\n"
834 #: build/C/man7/feature_test_macros.7:556
837 "#ifdef _LARGEFILE64_SOURCE\n"
838 " printf(\"_LARGEFILE64_SOURCE defined\\en\");\n"
843 #: build/C/man7/feature_test_macros.7:560
846 "#ifdef _FILE_OFFSET_BITS\n"
847 " printf(\"_FILE_OFFSET_BITS defined: %d\\en\", _FILE_OFFSET_BITS);\n"
852 #: build/C/man7/feature_test_macros.7:564
855 "#ifdef _BSD_SOURCE\n"
856 " printf(\"_BSD_SOURCE defined\\en\");\n"
861 #: build/C/man7/feature_test_macros.7:568
864 "#ifdef _SVID_SOURCE\n"
865 " printf(\"_SVID_SOURCE defined\\en\");\n"
870 #: build/C/man7/feature_test_macros.7:572
873 "#ifdef _ATFILE_SOURCE\n"
874 " printf(\"_ATFILE_SOURCE defined\\en\");\n"
879 #: build/C/man7/feature_test_macros.7:576
882 "#ifdef _GNU_SOURCE\n"
883 " printf(\"_GNU_SOURCE defined\\en\");\n"
888 #: build/C/man7/feature_test_macros.7:580
891 "#ifdef _REENTRANT\n"
892 " printf(\"_REENTRANT defined\\en\");\n"
897 #: build/C/man7/feature_test_macros.7:584
900 "#ifdef _THREAD_SAFE\n"
901 " printf(\"_THREAD_SAFE defined\\en\");\n"
906 #: build/C/man7/feature_test_macros.7:588
909 "#ifdef _FORTIFY_SOURCE\n"
910 " printf(\"_FORTIFY_SOURCE defined\\en\");\n"
915 #: build/C/man7/feature_test_macros.7:591
918 " exit(EXIT_SUCCESS);\n"
923 #: build/C/man7/feature_test_macros.7:592 build/C/man1/intro.1:300 build/C/man2/intro.2:87 build/C/man3/intro.3:95 build/C/man4/intro.4:37 build/C/man5/intro.5:37 build/C/man7/intro.7:40 build/C/man7/libc.7:96 build/C/man7/mailaddr.7:116 build/C/man7/man-pages.7:545 build/C/man7/man.7:555 build/C/man7/mdoc.7:426 build/C/man7/posixoptions.7:853 build/C/man5/proc.5:2744 build/C/man7/standards.7:253 build/C/man7/suffixes.7:279 build/C/man2/unimplemented.2:64 build/C/man7/mdoc.samples.7:2942
929 #: build/C/man7/feature_test_macros.7:595
930 msgid "B<libc>(7), B<standards>(7)"
933 #. But beware: the info libc document is out of date (Jul 07, mtk)
935 #: build/C/man7/feature_test_macros.7:599
936 msgid "The section \"Feature Test Macros\" under I<info libc>."
940 #: build/C/man7/feature_test_macros.7:601
941 msgid "I</usr/include/features.h>"
945 #: build/C/man7/feature_test_macros.7:601 build/C/man1/intro.1:302 build/C/man2/intro.2:110 build/C/man3/intro.3:108 build/C/man4/intro.4:39 build/C/man5/intro.5:39 build/C/man6/intro.6:36 build/C/man7/intro.7:42 build/C/man8/intro.8:48 build/C/man7/libc.7:101 build/C/man7/mailaddr.7:126 build/C/man7/man-pages.7:552 build/C/man7/man.7:567 build/C/man7/mdoc.7:431 build/C/man7/operator.7:63 build/C/man7/posixoptions.7:856 build/C/man5/proc.5:2773 build/C/man7/standards.7:257 build/C/man7/suffixes.7:282 build/C/man3/undocumented.3:187 build/C/man2/unimplemented.2:66 build/C/man7/units.7:128 build/C/man7/mdoc.samples.7:2947
951 #: build/C/man7/feature_test_macros.7:608 build/C/man1/intro.1:309 build/C/man2/intro.2:117 build/C/man3/intro.3:115 build/C/man4/intro.4:46 build/C/man5/intro.5:46 build/C/man6/intro.6:43 build/C/man7/intro.7:49 build/C/man8/intro.8:55 build/C/man7/libc.7:108 build/C/man7/mailaddr.7:133 build/C/man7/man-pages.7:559 build/C/man7/man.7:574 build/C/man7/operator.7:70 build/C/man7/posixoptions.7:863 build/C/man5/proc.5:2780 build/C/man7/standards.7:264 build/C/man7/suffixes.7:289 build/C/man3/undocumented.3:194 build/C/man2/unimplemented.2:73 build/C/man7/units.7:135
953 "This page is part of release 3.41 of the Linux I<man-pages> project. A "
954 "description of the project, and information about reporting bugs, can be "
955 "found at http://www.kernel.org/doc/man-pages/."
959 #: build/C/man1/intro.1:26 build/C/man2/intro.2:27 build/C/man3/intro.3:24 build/C/man4/intro.4:25 build/C/man5/intro.5:26 build/C/man6/intro.6:25 build/C/man7/intro.7:27 build/C/man8/intro.8:28
965 #: build/C/man1/intro.1:26
971 #: build/C/man1/intro.1:26 build/C/man7/mailaddr.7:26
973 msgid "Linux User's Manual"
977 #: build/C/man1/intro.1:29
978 msgid "intro - Introduction to user commands"
982 #: build/C/man1/intro.1:33
984 "Section 1 of the manual describes user commands and tools, for example, file "
985 "manipulation tools, shells, compilers, web browsers, file and image viewers "
986 "and editors, and so on."
990 #: build/C/man1/intro.1:46
992 "All commands yield a status value on termination. This value can be tested "
993 "(e.g., in most shells the variable I<$?> contains the status of the last "
994 "executed command) to see whether the command completed successfully. A "
995 "zero exit status is conventionally used to indicate success, and a nonzero "
996 "status means that the command was unsuccessful. (Details of the exit status "
997 "can be found in B<wait>(2).) A nonzero exit status can be in the range 1 to "
998 "255, and some commands use different nonzero status values to indicate the "
999 "reason why the command failed."
1003 #: build/C/man1/intro.1:50
1005 "Linux is a flavor of UNIX, and as a first approximation all user commands "
1006 "under UNIX work precisely the same under Linux (and FreeBSD and lots of "
1007 "other UNIX-like systems)."
1011 #: build/C/man1/intro.1:60
1013 "Under Linux there are GUIs (graphical user interfaces), where you can point "
1014 "and click and drag, and hopefully get work done without first reading lots "
1015 "of documentation. The traditional UNIX environment is a CLI (command line "
1016 "interface), where you type commands to tell the computer what to do. That "
1017 "is faster and more powerful, but requires finding out what the commands "
1018 "are. Below a bare minimum, to get started."
1022 #: build/C/man1/intro.1:60
1028 #: build/C/man1/intro.1:74
1030 "In order to start working, you probably first have to login, that is, give "
1031 "your username and password. See also B<login>(1). The program I<login> now "
1032 "starts a I<shell> (command interpreter) for you. In case of a graphical "
1033 "login, you get a screen with menus or icons and a mouse click will start a "
1034 "shell in a window. See also B<xterm>(1)."
1038 #: build/C/man1/intro.1:74
1044 #: build/C/man1/intro.1:89
1046 "One types commands to the I<shell>, the command interpreter. It is not "
1047 "built-in, but is just a program and you can change your shell. Everybody "
1048 "has her own favorite one. The standard one is called I<sh>. See also "
1049 "B<ash>(1), B<bash>(1), B<csh>(1), B<zsh>(1), B<chsh>(1)."
1053 #: build/C/man1/intro.1:91
1054 msgid "A session might go like"
1058 #: build/C/man1/intro.1:106
1061 "B<knuth login: >I<aeb>\n"
1062 "B<Password: >I<********>\n"
1064 "Tue Aug 6 23:50:44 CEST 2002\n"
1067 "Su Mo Tu We Th Fr Sa\n"
1070 "11 12 13 14 15 16 17\n"
1071 "18 19 20 21 22 23 24\n"
1072 "25 26 27 28 29 30 31\n"
1076 #: build/C/man1/intro.1:133
1083 "drwxrwxr-x 2 aeb 1024 Aug 6 23:51 bin\n"
1084 "-rw-rw-r-- 1 aeb 37 Aug 6 23:52 tel\n"
1086 "maja 0501-1136285\n"
1087 "peter 0136-7399214\n"
1088 "B<% >I<cp tel tel2>\n"
1091 "drwxr-xr-x 2 aeb 1024 Aug 6 23:51 bin\n"
1092 "-rw-r--r-- 1 aeb 37 Aug 6 23:52 tel\n"
1093 "-rw-r--r-- 1 aeb 37 Aug 6 23:53 tel2\n"
1094 "B<% >I<mv tel tel1>\n"
1097 "drwxr-xr-x 2 aeb 1024 Aug 6 23:51 bin\n"
1098 "-rw-r--r-- 1 aeb 37 Aug 6 23:52 tel1\n"
1099 "-rw-r--r-- 1 aeb 37 Aug 6 23:53 tel2\n"
1100 "B<% >I<diff tel1 tel2>\n"
1102 "B<% >I<grep maja tel2>\n"
1103 "maja 0501-1136285\n"
1108 #: build/C/man1/intro.1:145
1110 "and here typing Control-D ended the session. The B<% > here was the command "
1111 "prompt\\(emit is the shell's way of indicating that it is ready for the next "
1112 "command. The prompt can be customized in lots of ways, and one might "
1113 "include stuff like username, machine name, current directory, time, and so "
1114 "on. An assignment PS1=\"What next, master? \" would change the prompt as "
1119 #: build/C/man1/intro.1:151
1121 "We see that there are commands I<date> (that gives date and time), and "
1122 "I<cal> (that gives a calendar)."
1126 #: build/C/man1/intro.1:167
1128 "The command I<ls> lists the contents of the current directory\\(emit tells "
1129 "you what files you have. With a I<-l> option it gives a long listing, that "
1130 "includes the owner and size and date of the file, and the permissions people "
1131 "have for reading and/or changing the file. For example, the file \"tel\" "
1132 "here is 37 bytes long, owned by aeb and the owner can read and write it, "
1133 "others can only read it. Owner and permissions can be changed by the "
1134 "commands I<chown> and I<chmod>."
1138 #: build/C/man1/intro.1:174
1140 "The command I<cat> will show the contents of a file. (The name is from "
1141 "\"concatenate and print\": all files given as parameters are concatenated "
1142 "and sent to \"standard output\", here the terminal screen.)"
1146 #: build/C/man1/intro.1:181
1148 "The command I<cp> (from \"copy\") will copy a file. On the other hand, the "
1149 "command I<mv> (from \"move\") only renames it."
1153 #: build/C/man1/intro.1:186
1155 "The command I<diff> lists the differences between two files. Here there was "
1156 "no output because there were no differences."
1160 #: build/C/man1/intro.1:192
1162 "The command I<rm> (from \"remove\") deletes the file, and be careful! it is "
1163 "gone. No wastepaper basket or anything. Deleted means lost."
1167 #: build/C/man1/intro.1:197
1169 "The command I<grep> (from \"g/re/p\") finds occurrences of a string in one "
1170 "or more files. Here it finds Maja's telephone number."
1174 #: build/C/man1/intro.1:197
1176 msgid "Pathnames and the current directory"
1180 #: build/C/man1/intro.1:209
1182 "Files live in a large tree, the file hierarchy. Each has a I<pathname> "
1183 "describing the path from the root of the tree (which is called /) to the "
1184 "file. For example, such a full pathname might be /home/aeb/tel. Always "
1185 "using full pathnames would be inconvenient, and the name of a file in the "
1186 "current directory may be abbreviated by only giving the last component. "
1187 "That is why \"/home/aeb/tel\" can be abbreviated to \"tel\" when the current "
1188 "directory is \"/home/aeb\"."
1192 #: build/C/man1/intro.1:213
1193 msgid "The command I<pwd> prints the current directory."
1197 #: build/C/man1/intro.1:218
1199 "The command I<cd> changes the current directory. Try \"cd /\" and \"pwd\" "
1200 "and \"cd\" and \"pwd\"."
1204 #: build/C/man1/intro.1:218
1210 #: build/C/man1/intro.1:222
1211 msgid "The command I<mkdir> makes a new directory."
1215 #: build/C/man1/intro.1:226
1217 "The command I<rmdir> removes a directory if it is empty, and complains "
1222 #: build/C/man1/intro.1:238
1224 "The command I<find> (with a rather baroque syntax) will find files with "
1225 "given name or other properties. For example, \"find . -name tel\" would "
1226 "find the file \"tel\" starting in the present directory (which is called "
1227 "\".\"). And \"find / -name tel\" would do the same, but starting at the "
1228 "root of the tree. Large searches on a multi-GB disk will be time-consuming, "
1229 "and it may be better to use B<locate>(1)."
1233 #: build/C/man1/intro.1:238
1235 msgid "Disks and Filesystems"
1239 #: build/C/man1/intro.1:249
1241 "The command I<mount> will attach the file system found on some disk (or "
1242 "floppy, or CDROM or so) to the big file system hierarchy. And I<umount> "
1243 "detaches it again. The command I<df> will tell you how much of your disk is "
1248 #: build/C/man1/intro.1:249
1254 #: build/C/man1/intro.1:267
1256 "On a UNIX system many user and system processes run simultaneously. The one "
1257 "you are talking to runs in the I<foreground>, the others in the "
1258 "I<background>. The command I<ps> will show you which processes are active "
1259 "and what numbers these processes have. The command I<kill> allows you to "
1260 "get rid of them. Without option this is a friendly request: please go "
1261 "away. And \"kill -9\" followed by the number of the process is an immediate "
1262 "kill. Foreground processes can often be killed by typing Control-C."
1266 #: build/C/man1/intro.1:267
1268 msgid "Getting information"
1272 #: build/C/man1/intro.1:280
1274 "There are thousands of commands, each with many options. Traditionally "
1275 "commands are documented on I<man pages>, (like this one), so that the "
1276 "command \"man kill\" will document the use of the command \"kill\" (and "
1277 "\"man man\" document the command \"man\"). The program I<man> sends the "
1278 "text through some I<pager>, usually I<less>. Hit the space bar to get the "
1279 "next page, hit q to quit."
1283 #: build/C/man1/intro.1:288
1285 "In documentation it is customary to refer to man pages by giving the name "
1286 "and section number, as in B<man>(1). Man pages are terse, and allow you to "
1287 "find quickly some forgotten detail. For newcomers an introductory text with "
1288 "more examples and explanations is useful."
1292 #: build/C/man1/intro.1:292
1294 "A lot of GNU/FSF software is provided with info files. Type \"info info\" "
1295 "for an introduction on the use of the program \"info\"."
1299 #. Actual examples? Separate section for each of cat, cp, ...?
1300 #. gzip, bzip2, tar, rpm
1302 #: build/C/man1/intro.1:300
1304 "Special topics are often treated in HOWTOs. Look in "
1305 "I</usr/share/doc/howto/en> and use a browser if you find HTML files there."
1309 #: build/C/man1/intro.1:302 build/C/man4/intro.4:39 build/C/man5/intro.5:39 build/C/man7/intro.7:42
1310 msgid "B<standards>(7)"
1314 #: build/C/man2/intro.2:27 build/C/man3/intro.3:24
1320 #: build/C/man2/intro.2:30
1321 msgid "intro - Introduction to system calls"
1325 #: build/C/man2/intro.2:40
1327 "Section 2 of the manual describes the Linux system calls. A system call is "
1328 "an entry point into the Linux kernel. Usually, system calls are not invoked "
1329 "directly: instead, most system calls have corresponding C library wrapper "
1330 "functions which perform the steps required (e.g., trapping to kernel mode) "
1331 "in order to invoke the system call. Thus, making a system call looks the "
1332 "same as invoking a normal library function."
1336 #: build/C/man2/intro.2:43
1337 msgid "For a list of the Linux system calls, see B<syscalls>(2)."
1341 #: build/C/man2/intro.2:43 build/C/man2/unimplemented.2:35
1343 msgid "RETURN VALUE"
1347 #: build/C/man2/intro.2:52
1349 "On error, most system calls return a negative error number (i.e., the "
1350 "negated value of one of the constants described in B<errno>(3)). The C "
1351 "library wrapper hides this detail from the caller: when a system call "
1352 "returns a negative value, the wrapper copies the absolute value into the "
1353 "I<errno> variable, and returns -1 as the return value of the wrapper."
1357 #: build/C/man2/intro.2:57
1359 "The value returned by a successful system call depends on the call. Many "
1360 "system calls return 0 on success, but some can return nonzero values from a "
1361 "successful call. The details are described in the individual manual pages."
1365 #: build/C/man2/intro.2:68
1367 "In some cases, the programmer must define a feature test macro in order to "
1368 "obtain the declaration of a system call from the header file specified in "
1369 "the man page SYNOPSIS section. (Where required, these feature test macros "
1370 "must be defined before including I<any> header files.) In such cases, the "
1371 "required macro is described in the man page. For further information on "
1372 "feature test macros, see B<feature_test_macros>(7)."
1376 #: build/C/man2/intro.2:73 build/C/man3/intro.3:90
1378 "Certain terms and abbreviations are used to indicate UNIX variants and "
1379 "standards to which calls in this section conform. See B<standards>(7)."
1383 #: build/C/man2/intro.2:74
1385 msgid "Calling Directly"
1389 #: build/C/man2/intro.2:83
1391 "In most cases, it is unnecessary to invoke a system call directly, but there "
1392 "are times when the Standard C library does not implement a nice wrapper "
1393 "function for you. In this case, the programmer must manually invoke the "
1394 "system call using B<syscall>(2). Historically, this was also possible using "
1395 "one of the _syscall macros described in B<_syscall>(2)."
1399 #: build/C/man2/intro.2:83 build/C/man3/intro.3:91 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
1401 msgid "Authors and Copyright Conditions"
1405 #: build/C/man2/intro.2:87 build/C/man3/intro.3:95 build/C/man4/intro.4:37 build/C/man5/intro.5:37 build/C/man6/intro.6:36 build/C/man7/intro.7:40 build/C/man8/intro.8:48
1407 "Look at the header of the manual page source for the author(s) and copyright "
1408 "conditions. Note that these can be different from page to page!"
1412 #: build/C/man2/intro.2:110
1414 "B<_syscall>(2), B<syscall>(2), B<syscalls>(2), B<errno>(3), B<intro>(3), "
1415 "B<capabilities>(7), B<credentials>(7), B<feature_test_macros>(7), "
1416 "B<mq_overview>(7), B<path_resolution>(7), B<pipe>(7), B<pty>(7), "
1417 "B<sem_overview>(7), B<shm_overview>(7), B<signal>(7), B<socket>(7), "
1418 "B<standards>(7), B<svipc>(7), B<symlink>(7), B<time>(7)"
1422 #: build/C/man3/intro.3:27
1423 msgid "intro - Introduction to library functions"
1427 #: build/C/man3/intro.3:31
1429 "Section 3 of the manual describes all library functions excluding the "
1430 "library functions (system call wrappers) described in section 2, which "
1431 "implement system calls."
1435 #: build/C/man3/intro.3:48
1437 "Many of the functions described in the section are part of the Standard C "
1438 "Library (I<libc>). Some functions are part of other libraries (e.g., the "
1439 "math library, I<libm>, or the real-time library, I<librt>) in which case "
1440 "the manual page will indicate the linker option needed to link against the "
1441 "required library (e.g., I<-lm> and I<-lrt>, respectively, for the "
1442 "aforementioned libraries)."
1447 #. are various function groups which can be identified by a letter which
1448 #. is appended to the chapter number:
1450 #. These functions, the functions from chapter 2 and from chapter 3S are
1451 #. contained in the C standard library libc, which will be used by
1455 #. These functions are parts of the
1457 #. library. They are contained in the standard C library libc.
1459 #. These functions are contained in the arithmetic library libm. They are
1462 #. FORTRAN compiler by default, but not by the
1464 #. C compiler, which needs the option \fI\-lm\fP.
1466 #. These functions are part of the FORTRAN library libF77. There are no
1467 #. special compiler flags needed to use these functions.
1469 #. Various special libraries. The manual pages documenting their functions
1470 #. specify the library names.
1472 #: build/C/man3/intro.3:85
1474 "In some cases, the programmer must define a feature test macro in order to "
1475 "obtain the declaration of a function from the header file specified in the "
1476 "man page SYNOPSIS section. (Where required, these feature test macros must "
1477 "be defined before including I<any> header files.) In such cases, the "
1478 "required macro is described in the man page. For further information on "
1479 "feature test macros, see B<feature_test_macros>(7)."
1483 #: build/C/man3/intro.3:108
1485 "B<intro>(2), B<errno>(3), B<capabilities>(7), B<credentials>(7), "
1486 "B<environ>(7), B<feature_test_macros>(7), B<libc>(7), B<math_error>(7), "
1487 "B<path_resolution>(7), B<pthreads>(7), B<signal>(7), B<standards>(7)"
1491 #: build/C/man4/intro.4:25 build/C/man5/intro.5:26 build/C/man6/intro.6:25 build/C/man7/intro.7:27 build/C/man8/intro.8:28
1497 #: build/C/man4/intro.4:28
1498 msgid "intro - Introduction to special files"
1502 #: build/C/man4/intro.4:30
1503 msgid "Section 4 of the manual describes special files (devices)."
1507 #: build/C/man4/intro.4:30 build/C/man7/mailaddr.7:112 build/C/man7/man.7:472 build/C/man7/mdoc.7:409 build/C/man7/mdoc.samples.7:2864
1513 #: build/C/man4/intro.4:32
1514 msgid "/dev/* \\(em device files"
1518 #: build/C/man5/intro.5:29
1519 msgid "intro - Introduction to file formats"
1523 #: build/C/man5/intro.5:32
1525 "Section 5 of the manual describes various file formats and protocols, and "
1526 "the corresponding C structures, if any."
1530 #: build/C/man6/intro.6:28
1531 msgid "intro - Introduction to games"
1535 #: build/C/man6/intro.6:31
1537 "Section 6 of the manual describes all the games and funny little programs "
1538 "available on the system."
1542 #: build/C/man7/intro.7:30
1543 msgid "intro - Introduction to overview, conventions, and miscellany section"
1547 #: build/C/man7/intro.7:35
1549 "Section 7 of the manual provides overviews on various topics, and describes "
1550 "conventions and protocols, character set standards, the standard file system "
1551 "layout, and miscellaneous other things."
1555 #: build/C/man8/intro.8:31
1556 msgid "intro - Introduction to administration and privileged commands"
1560 #: build/C/man8/intro.8:36
1562 "Section 8 of the manual describes commands which either can be or are only "
1563 "used by the superuser, like system-administration commands, daemons, and "
1564 "hardware-related commands."
1568 #: build/C/man8/intro.8:43
1570 "As with the commands in described section 1, the commands described in this "
1571 "section terminate with an exit status that indicates whether the command "
1572 "succeeded or failed. See B<intro>(1) for more information."
1576 #: build/C/man7/libc.7:24
1582 #: build/C/man7/libc.7:24
1588 #: build/C/man7/libc.7:27
1589 msgid "libc - Overview of standard C libraries on Linux"
1593 #: build/C/man7/libc.7:34
1595 "The term \"libc\" is commonly used as a shorthand for the \"standard C "
1596 "library\", a library of standard functions that can be used by all C "
1597 "programs (and sometimes by programs in other languages). Because of some "
1598 "history (see below), use of the term \"libc\" to refer to the standard C "
1599 "library is somewhat ambiguous on Linux."
1603 #: build/C/man7/libc.7:34
1609 #: build/C/man7/libc.7:51
1611 "By far the most widely used C library on Linux is the GNU C Library "
1612 "(I<http://www.gnu.org/software/libc/>), often referred to as I<glibc>. This "
1613 "is the C library that is nowadays used in all major Linux distributions. It "
1614 "is also the C library whose details are documented in the relevant pages of "
1615 "the I<man-pages> project (primarily in Section 3 of the manual). "
1616 "Documentation of glibc is also available in the glibc manual, available via "
1617 "the command I<info libc>. Release 1.0 of glibc was made in September 1992. "
1618 "(There were earlier 0.x releases.) The next major release of glibc was 2.0, "
1619 "at the beginning of 1997."
1623 #: build/C/man7/libc.7:58
1625 "The pathname I</lib/libc.so.6> (or something similar) is normally a symbolic "
1626 "link that points to the location of the glibc library, and executing this "
1627 "pathname will cause glibc to display various information about the version "
1628 "installed on your system."
1632 #: build/C/man7/libc.7:58
1638 #: build/C/man7/libc.7:81
1640 "In the early to mid 1990s, there was for a while I<Linux libc>, a fork of "
1641 "glibc 1.x created by Linux developers who felt that glibc development at the "
1642 "time was not sufficing for the needs of Linux. Often, this library was "
1643 "referred to (ambiguously) as just \"libc\". Linux libc released major "
1644 "versions 2, 3, 4, and 5 (as well as many minor versions of those releases). "
1645 "For a while, Linux libc was the standard C library in many Linux "
1646 "distributions. However, notwithstanding the original motivations of the "
1647 "Linux libc effort, by the time glibc 2.0 was released, it was clearly "
1648 "superior to Linux libc, and all major Linux distributions that had been "
1649 "using Linux libc soon switched back to glibc. (Since this switch occurred "
1650 "over a decade ago, I<man-pages> no longer takes care to document Linux libc "
1651 "details. Nevertheless, the history is visible in vestiges of information "
1652 "about Linux libc that remain in some manual pages, in particular, references "
1653 "to I<libc4> and I<libc5>.)"
1657 #: build/C/man7/libc.7:81
1659 msgid "Other C libraries"
1663 #: build/C/man7/libc.7:96
1665 "There are various other less widely used C libraries for Linux. These "
1666 "libraries are generally smaller than glibc, both in terms of features and "
1667 "memory footprint, and often intended for building small binaries, perhaps "
1668 "targeted at development for embedded Linux systems. Among such libraries "
1669 "are I<uClibc> (I<http://www.uclibc.org/>) and I<dietlibc> "
1670 "(I<http://www.fefe.de/dietlibc/>). Details of these libraries are generally "
1671 "not covered by the I<man-pages> project."
1675 #: build/C/man7/libc.7:101
1676 msgid "B<syscalls>(2), B<feature_test_macros>(7), B<man-pages>(7), B<standards>(7)"
1680 #: build/C/man7/mailaddr.7:26
1686 #: build/C/man7/mailaddr.7:26
1692 #: build/C/man7/mailaddr.7:30
1693 msgid "mailaddr - mail addressing description"
1697 #: build/C/man7/mailaddr.7:35
1699 "This manual page gives a brief introduction to SMTP mail addresses, as used "
1700 "on the Internet. These addresses are in the general format"
1704 #: build/C/man7/mailaddr.7:37
1705 msgid " user@domain"
1709 #: build/C/man7/mailaddr.7:40
1711 "where a domain is a hierarchical dot-separated list of subdomains. These "
1712 "examples are valid forms of the same address:"
1716 #: build/C/man7/mailaddr.7:42
1717 msgid " eric@monet.berkeley.edu"
1721 #: build/C/man7/mailaddr.7:44
1722 msgid " Eric Allman E<lt>eric@monet.berkeley.eduE<gt>"
1726 #: build/C/man7/mailaddr.7:46
1727 msgid " eric@monet.berkeley.edu (Eric Allman)"
1731 #: build/C/man7/mailaddr.7:50
1733 "The domain part (\"monet.berkeley.edu\") is a mail-accepting domain. It can "
1734 "be a host and in the past it usually was, but it doesn't have to be. The "
1735 "domain part is not case sensitive."
1739 #: build/C/man7/mailaddr.7:58
1741 "The local part (\"eric\") is often a username, but its meaning is defined by "
1742 "the local software. Sometimes it is case sensitive, although that is "
1743 "unusual. If you see a local-part that looks like garbage, it is usually "
1744 "because of a gateway between an internal e-mail system and the net, here are "
1749 #: build/C/man7/mailaddr.7:60
1750 msgid " \"surname/admd=telemail/c=us/o=hp/prmd=hp\"@some.where"
1754 #: build/C/man7/mailaddr.7:62
1755 msgid " USER%SOMETHING@some.where"
1759 #: build/C/man7/mailaddr.7:64
1760 msgid " machine!machine!name@some.where"
1764 #: build/C/man7/mailaddr.7:66
1765 msgid " I2461572@some.where"
1769 #: build/C/man7/mailaddr.7:70
1771 "(These are, respectively, an X.400 gateway, a gateway to an arbitrary "
1772 "internal mail system that lacks proper internet support, an UUCP gateway, "
1773 "and the last one is just boring username policy.)"
1777 #: build/C/man7/mailaddr.7:76
1779 "The real-name part (\"Eric Allman\") can either be placed before E<lt>E<gt>, "
1780 "or in () at the end. (Strictly speaking the two aren't the same, but the "
1781 "difference is beyond the scope of this page.) The name may have to be "
1782 "quoted using \"\", for example, if it contains \".\":"
1786 #: build/C/man7/mailaddr.7:78
1787 msgid " \"Eric P. Allman\" E<lt>eric@monet.berkeley.eduE<gt>"
1791 #: build/C/man7/mailaddr.7:78
1793 msgid "Abbreviation."
1797 #: build/C/man7/mailaddr.7:86
1799 "Many mail systems let users abbreviate the domain name. For instance, users "
1800 "at berkeley.edu may get away with \"eric@monet\" to send mail to Eric "
1801 "Allman. I<This behavior is deprecated.> Sometimes it works, but you should "
1806 #: build/C/man7/mailaddr.7:86
1808 msgid "Route-addrs."
1812 #: build/C/man7/mailaddr.7:93
1814 "In the past, sometimes one had to route a message through several hosts to "
1815 "get it to its final destination. Addresses which show these relays are "
1816 "termed \"route-addrs\". These use the syntax:"
1820 #: build/C/man7/mailaddr.7:95
1821 msgid " E<lt>@hosta,@hostb:user@hostcE<gt>"
1825 #: build/C/man7/mailaddr.7:100
1827 "This specifies that the message should be sent to hosta, from there to "
1828 "hostb, and finally to hostc. Many hosts disregard route-addrs and send "
1829 "directly to hostc."
1833 #: build/C/man7/mailaddr.7:106
1835 "Route-addrs are very unusual now. They occur sometimes in old mail "
1836 "archives. It is generally possible to ignore all but the \"user@hostc\" "
1837 "part of the address to determine the actual address."
1841 #: build/C/man7/mailaddr.7:106
1847 #: build/C/man7/mailaddr.7:112
1849 "Every site is required to have a user or user alias designated "
1850 "\"postmaster\" to which problems with the mail system may be addressed. The "
1851 "\"postmaster\" address is not case sensitive."
1855 #: build/C/man7/mailaddr.7:114
1856 msgid "I</etc/aliases>"
1860 #: build/C/man7/mailaddr.7:116
1861 msgid "I<~/.forward>"
1865 #: build/C/man7/mailaddr.7:124
1867 "B<binmail>(1), B<mail>(1), B<mconnect>(1), B<aliases>(5), B<forward>(5), "
1868 "B<sendmail>(8), B<vrfy>(8)"
1872 #: build/C/man7/mailaddr.7:126
1873 msgid "RFC\\ 2822 (Internet Message Format)"
1877 #: build/C/man7/man-pages.7:28
1883 #: build/C/man7/man-pages.7:28
1889 #: build/C/man7/man-pages.7:31
1890 msgid "man-pages - conventions for writing Linux man pages"
1894 #: build/C/man7/man-pages.7:35 build/C/man7/man.7:47
1895 msgid "B<man> [I<section>] I<title>"
1899 #: build/C/man7/man-pages.7:41
1901 "This page describes the conventions that should be employed when writing man "
1902 "pages for the Linux I<man-pages> project, which comprises Sections 2, 3, 4, "
1903 "5, and 7 of the Linux manual pages. The conventions described on this page "
1904 "may also be useful for authors writing man pages for other projects."
1908 #: build/C/man7/man-pages.7:41
1910 msgid "Sections of the Manual Pages"
1914 #: build/C/man7/man-pages.7:44
1915 msgid "The manual Sections are traditionally defined as follows:"
1919 #: build/C/man7/man-pages.7:44
1921 msgid "B<1 Commands (Programs)>"
1925 #: build/C/man7/man-pages.7:48
1926 msgid "Those commands that can be executed by the user from within a shell."
1930 #: build/C/man7/man-pages.7:48
1932 msgid "B<2 System calls>"
1936 #: build/C/man7/man-pages.7:51
1937 msgid "Those functions which must be performed by the kernel."
1941 #: build/C/man7/man-pages.7:51
1943 msgid "B<3 Library calls>"
1947 #: build/C/man7/man-pages.7:56
1948 msgid "Most of the I<libc> functions."
1952 #: build/C/man7/man-pages.7:56
1954 msgid "B<4 Special files (devices)>"
1958 #: build/C/man7/man-pages.7:60
1959 msgid "Files found in I</dev>."
1963 #: build/C/man7/man-pages.7:60
1965 msgid "B<5 File formats and conventions>"
1969 #: build/C/man7/man-pages.7:65
1970 msgid "The format for I</etc/passwd> and other human-readable files."
1974 #: build/C/man7/man-pages.7:65
1980 #: build/C/man7/man-pages.7:67
1982 msgid "B<7 Conventions and miscellaneous>"
1986 #: build/C/man7/man-pages.7:71
1988 "Overviews of various topics, conventions and protocols, character set "
1989 "standards, and miscellaneous other things."
1993 #: build/C/man7/man-pages.7:71
1995 msgid "B<8 System management commands>"
1999 #. .B 9 Kernel routines
2000 #. This is an obsolete manual section.
2001 #. Once it was thought a good idea to document the Linux kernel here,
2002 #. but in fact very little has been documented, and the documentation
2003 #. that exists is outdated already.
2004 #. There are better sources of
2005 #. information for kernel developers.
2007 #: build/C/man7/man-pages.7:84
2008 msgid "Commands like B<mount>(8), many of which only root can execute."
2012 #: build/C/man7/man-pages.7:84
2014 msgid "Macro package"
2018 #: build/C/man7/man-pages.7:91
2020 "New manual pages should be marked up using the B<groff an.tmac> package "
2021 "described in B<man>(7). This choice is mainly for consistency: the vast "
2022 "majority of existing Linux manual pages are marked up using these macros."
2026 #: build/C/man7/man-pages.7:91
2028 msgid "Conventions for source file layout"
2032 #: build/C/man7/man-pages.7:96
2034 "Please limit source code line length to no more than about 75 characters "
2035 "wherever possible. This helps avoid line-wrapping in some mail clients when "
2036 "patches are submitted inline."
2040 #: build/C/man7/man-pages.7:100
2042 "New sentences should be started on new lines. This makes it easier to see "
2043 "the effect of patches, which often operate at the level of individual "
2048 #: build/C/man7/man-pages.7:100 build/C/man7/man.7:76
2054 #: build/C/man7/man-pages.7:102
2055 msgid "The first command in a man page should be a B<TH> command:"
2059 #: build/C/man7/man-pages.7:106 build/C/man7/man.7:83
2060 msgid "B<\\&.TH> I<title section date source manual>"
2064 #: build/C/man7/man-pages.7:109
2069 #: build/C/man7/man-pages.7:110
2075 #: build/C/man7/man-pages.7:114
2076 msgid "The title of the man page, written in all caps (e.g., I<MAN-PAGES>)."
2080 #: build/C/man7/man-pages.7:114
2086 #: build/C/man7/man-pages.7:118
2087 msgid "The section number in which the man page should be placed (e.g., I<7>)."
2091 #: build/C/man7/man-pages.7:118
2097 #: build/C/man7/man-pages.7:124
2099 "The date of the last revision\\(emremember to change this every time a "
2100 "change is made to the man page, since this is the most general way of doing "
2101 "version control. Dates should be written in the form YYYY-MM-DD."
2105 #: build/C/man7/man-pages.7:124
2111 #: build/C/man7/man-pages.7:127
2112 msgid "The source of the command, function, or system call."
2116 #: build/C/man7/man-pages.7:131
2118 "For those few I<man-pages> pages in Sections 1 and 8, probably you just want "
2123 #: build/C/man7/man-pages.7:139
2125 "For system calls, just write I<Linux>. (An earlier practice was to write "
2126 "the version number of the kernel from which the manual page was being "
2127 "written/checked. However, this was never done consistently, and so was "
2128 "probably worse than including no version number. Henceforth, avoid "
2129 "including a version number.)"
2133 #: build/C/man7/man-pages.7:144
2135 "For library calls that are part of glibc or one of the other common GNU "
2136 "libraries, just use I<GNU C Library>, I<GNU>, or an empty string."
2140 #: build/C/man7/man-pages.7:147
2141 msgid "For Section 4 pages, use I<Linux>."
2145 #: build/C/man7/man-pages.7:150
2146 msgid "In cases of doubt, just write I<Linux>, or I<GNU>."
2150 #: build/C/man7/man-pages.7:150
2156 #: build/C/man7/man-pages.7:155
2158 "The title of the manual (e.g., for Section 2 and 3 pages in the I<man-pages> "
2159 "package, use I<Linux Programmer's Manual>)."
2163 #: build/C/man7/man-pages.7:156
2165 msgid "Sections within a manual page"
2169 #: build/C/man7/man-pages.7:163
2171 "The list below shows conventional or suggested sections. Most manual pages "
2172 "should include at least the B<highlighted> sections. Arrange a new manual "
2173 "page so that sections are placed in the order shown in the list."
2176 #. May 07: Few current man pages have an ERROR HANDLING section,,,
2178 #. May 07: Almost no current man pages have a USAGE section,,,
2181 #. May 07: Almost no current man pages have a SECURITY section,,,
2183 #. AUTHORS sections are discouraged
2184 #. AUTHORS [Discouraged]
2186 #: build/C/man7/man-pages.7:191
2191 "CONFIGURATION [Normally only in Section 4]\n"
2193 "OPTIONS [Normally only in Sections 1, 8]\n"
2194 "EXIT STATUS [Normally only in Sections 1, 8]\n"
2195 "RETURN VALUE [Normally only in Sections 2, 3]\n"
2196 "ERRORS [Typically only in Sections 2, 3]\n"
2199 "VERSIONS [Normally only in Sections 2, 3]\n"
2208 #: build/C/man7/man-pages.7:202
2210 "I<Where a traditional heading would apply>, I<please use it>; this kind of "
2211 "consistency can make the information easier to understand. If you must, you "
2212 "can create your own headings if they make things easier to understand (this "
2213 "can be especially useful for pages in Sections 4 and 5). However, before "
2214 "doing this, consider whether you could use the traditional headings, with "
2215 "some subsections (I<.SS>) within those sections."
2219 #: build/C/man7/man-pages.7:205
2220 msgid "The following list elaborates on the contents of each of the above sections."
2224 #: build/C/man7/man-pages.7:205
2230 #: build/C/man7/man-pages.7:212
2232 "The name of this manual page. See B<man>(7) for important details of the "
2233 "line(s) that should follow the B<.SH NAME> command."
2237 #: build/C/man7/man-pages.7:212
2243 #: build/C/man7/man-pages.7:224
2245 "briefly describes the command or function's interface. For commands, this "
2246 "shows the syntax of the command and its arguments (including options); "
2247 "boldface is used for as-is text and italics are used to indicate replaceable "
2248 "arguments. Brackets ([]) surround optional arguments, vertical bars (|) "
2249 "separate choices, and ellipses (\\&...) can be repeated. For functions, it "
2250 "shows any required data declarations or B<#include> directives, followed by "
2251 "the function declaration."
2254 #. FIXME . Say something here about compiler options
2256 #: build/C/man7/man-pages.7:230
2258 "Where a feature test macro must be defined in order to obtain the "
2259 "declaration of a function (or a variable) from a header file, then the "
2260 "SYNOPSIS should indicate this, as described in B<feature_test_macros>(7)."
2264 #: build/C/man7/man-pages.7:230
2266 msgid "B<CONFIGURATION>"
2270 #: build/C/man7/man-pages.7:234
2272 "Configuration details for a device. This section normally only appears in "
2277 #: build/C/man7/man-pages.7:234
2279 msgid "B<DESCRIPTION>"
2282 #. If there is some kind of input grammar or complex set of subcommands,
2283 #. consider describing them in a separate
2285 #. section (and just place an overview in the
2289 #: build/C/man7/man-pages.7:251
2291 "gives an explanation of what the program, function, or format does. Discuss "
2292 "how it interacts with files and standard input, and what it produces on "
2293 "standard output or standard error. Omit internals and implementation "
2294 "details unless they're critical for understanding the interface. Describe "
2295 "the usual case; for information on command-line options of a program use the "
2296 "B<OPTIONS> section."
2300 #: build/C/man7/man-pages.7:251
2307 #. describes the grammar of any sublanguage this implements.
2309 #: build/C/man7/man-pages.7:259
2311 "describes the command-line options accepted by a program and how they change "
2312 "its behavior. This section should only appear for Section 1 and 8 manual "
2317 #: build/C/man7/man-pages.7:259
2319 msgid "B<EXIT STATUS>"
2323 #: build/C/man7/man-pages.7:264
2325 "lists the possible exit status values of a program and the conditions that "
2326 "cause these values to be returned. This section should only appear for "
2327 "Section 1 and 8 manual pages."
2331 #: build/C/man7/man-pages.7:264
2333 msgid "B<RETURN VALUE>"
2337 #: build/C/man7/man-pages.7:269
2339 "For Section 2 and 3 pages, this section gives a list of the values the "
2340 "library routine will return to the caller and the conditions that cause "
2341 "these values to be returned."
2345 #: build/C/man7/man-pages.7:269
2351 #: build/C/man7/man-pages.7:277
2353 "For Section 2 and 3 manual pages, this is a list of the values that may be "
2354 "placed in I<errno> in the event of an error, along with information about "
2355 "the cause of the errors. I<The error list should be in alphabetical order>."
2359 #: build/C/man7/man-pages.7:277
2361 msgid "B<ENVIRONMENT>"
2365 #: build/C/man7/man-pages.7:281
2367 "lists all environment variables that affect the program or function and how "
2372 #: build/C/man7/man-pages.7:281
2377 #. May 07: Almost no current man pages have a DIAGNOSTICS section;
2378 #. "RETURN VALUE" or "EXIT STATUS" is preferred.
2381 #. gives an overview of the most common error messages and how to
2383 #. You don't need to explain system error messages
2384 #. or fatal signals that can appear during execution of any program
2385 #. unless they're special in some way to the program.
2387 #. May 07: Almost no current man pages have a SECURITY section.
2390 #. discusses security issues and implications.
2391 #. Warn about configurations or environments that should be avoided,
2392 #. commands that may have security implications, and so on, especially
2393 #. if they aren't obvious.
2394 #. Discussing security in a separate section isn't necessary;
2395 #. if it's easier to understand, place security information in the
2396 #. other sections (such as the
2401 #. However, please include security information somewhere!
2403 #: build/C/man7/man-pages.7:318
2405 "lists the files the program or function uses, such as configuration files, "
2406 "startup files, and files the program directly operates on. Give the full "
2407 "pathname of these files, and use the installation process to modify the "
2408 "directory part to match user preferences. For many programs, the default "
2409 "installation location is in I</usr/local>, so your base manual page should "
2410 "use I</usr/local> as the base."
2414 #: build/C/man7/man-pages.7:318
2420 #: build/C/man7/man-pages.7:335
2422 "A brief summary of the Linux kernel or glibc versions where a system call or "
2423 "library function appeared, or changed significantly in its operation. As a "
2424 "general rule, every new interface should include a VERSIONS section in its "
2425 "manual page. Unfortunately, many existing manual pages don't include this "
2426 "information (since there was no policy to do so when they were written). "
2427 "Patches to remedy this are welcome, but, from the perspective of programmers "
2428 "writing new code, this information probably only matters in the case of "
2429 "kernel interfaces that have been added in Linux 2.4 or later (i.e., changes "
2430 "since kernel 2.2), and library functions that have been added to glibc since "
2431 "version 2.1 (i.e., changes since glibc 2.0)."
2435 #: build/C/man7/man-pages.7:340
2437 "The B<syscalls>(2) manual page also provides information about kernel "
2438 "versions in which various system calls first appeared."
2442 #: build/C/man7/man-pages.7:340
2444 msgid "B<CONFORMING TO>"
2448 #: build/C/man7/man-pages.7:354
2450 "describes any standards or conventions that relate to the function or "
2451 "command described by the manual page. For a page in Section 2 or 3, this "
2452 "section should note the POSIX.1 version(s) that the call conforms to, and "
2453 "also whether the call is specified in C99. (Don't worry too much about "
2454 "other standards like SUS, SUSv2, and XPG, or the SVr4 and 4.xBSD "
2455 "implementation standards, unless the call was specified in those standards, "
2456 "but isn't in the current version of POSIX.1.) (See B<standards>(7).)"
2460 #: build/C/man7/man-pages.7:358
2462 "If the call is not governed by any standards but commonly exists on other "
2463 "systems, note them. If the call is Linux-specific, note this."
2467 #: build/C/man7/man-pages.7:362
2469 "If this section consists of just a list of standards (which it commonly "
2470 "does), terminate the list with a period (\\(aq.\\(aq)."
2474 #: build/C/man7/man-pages.7:362
2480 #: build/C/man7/man-pages.7:367
2482 "provides miscellaneous notes. For Section 2 and 3 man pages you may find it "
2483 "useful to include subsections (B<SS>) named I<Linux Notes> and I<Glibc "
2488 #: build/C/man7/man-pages.7:367
2494 #: build/C/man7/man-pages.7:371
2496 "lists limitations, known defects or inconveniences, and other questionable "
2501 #: build/C/man7/man-pages.7:371
2507 #: build/C/man7/man-pages.7:377
2509 "provides one or more examples describing how this function, file or command "
2510 "is used. For details on writing example programs, see I<Example Programs> "
2515 #: build/C/man7/man-pages.7:377
2521 #: build/C/man7/man-pages.7:387
2523 "lists authors of the documentation or program. B<Use of an AUTHORS section "
2524 "is strongly discouraged>. Generally, it is better not to clutter every page "
2525 "with a list of (over time potentially numerous) authors; if you write or "
2526 "significantly amend a page, add a copyright notice as a comment in the "
2527 "source file. If you are the author of a device driver and want to include "
2528 "an address for reporting bugs, place this under the BUGS section."
2532 #: build/C/man7/man-pages.7:387
2538 #: build/C/man7/man-pages.7:394
2540 "provides a comma-separated list of related man pages, ordered by section "
2541 "number and then alphabetically by name, possibly followed by other related "
2542 "pages or documents. Do not terminate this with a period."
2546 #: build/C/man7/man-pages.7:394
2548 msgid "Font conventions"
2552 #: build/C/man7/man-pages.7:399
2554 "For functions, the arguments are always specified using italics, I<even in "
2555 "the SYNOPSIS section>, where the rest of the function is specified in bold:"
2559 #: build/C/man7/man-pages.7:401
2560 msgid "B< int myfunction(int >I<argc>B<, char **>I<argv>B<);>"
2564 #: build/C/man7/man-pages.7:403
2565 msgid "Variable names should, like argument names, be specified in italics."
2569 #: build/C/man7/man-pages.7:416
2571 "Filenames (whether pathnames, or references to files in the I</usr/include> "
2572 "directory) are always in italics (e.g., I<E<lt>stdio.hE<gt>>), except in "
2573 "the SYNOPSIS section, where included files are in bold (e.g., B<#include "
2574 "E<lt>stdio.hE<gt>>). When referring to a standard include file under "
2575 "I</usr/include>, specify the header file surrounded by angle brackets, in "
2576 "the usual C way (e.g., I<E<lt>stdio.hE<gt>>)."
2580 #: build/C/man7/man-pages.7:420
2582 "Special macros, which are usually in upper case, are in bold (e.g., "
2583 "B<MAXINT>). Exception: don't boldface NULL."
2587 #: build/C/man7/man-pages.7:425
2589 "When enumerating a list of error codes, the codes are in bold (this list "
2590 "usually uses the B<\\&.TP> macro)."
2594 #: build/C/man7/man-pages.7:428
2596 "Complete commands should, if long, be written as in an indented line on "
2597 "their own, for example"
2601 #: build/C/man7/man-pages.7:432
2603 msgid "man 7 man-pages\n"
2607 #: build/C/man7/man-pages.7:442
2609 "If the command is short, then it can be included inline in the text, in "
2610 "italic format, for example, I<man 7 man-pages>. In this case, it may be "
2611 "worth using nonbreaking spaces (\"\\e\\ \") at suitable places in the "
2612 "command. Command options should be written in italics, e.g., I<-l>."
2616 #: build/C/man7/man-pages.7:447
2618 "Expressions, if not written on a separate indented line, should be specified "
2619 "in italics. Again, the use of nonbreaking spaces may be appropriate if the "
2620 "expression is inlined with normal text."
2624 #: build/C/man7/man-pages.7:458
2626 "Any reference to the subject of the current manual page should be written "
2627 "with the name in bold. If the subject is a function (i.e., this is a "
2628 "Section 2 or 3 page), then the name should be followed by a pair of "
2629 "parentheses in Roman (normal) font. For example, in the B<fcntl>(2) man "
2630 "page, references to the subject of the page would be written as: "
2631 "B<fcntl>(). The preferred way to write this in the source file is:"
2635 #: build/C/man7/man-pages.7:461
2637 msgid " .BR fcntl ()\n"
2641 #: build/C/man7/man-pages.7:465
2643 "(Using this format, rather than the use of \"\\efB...\\efP()\" makes it "
2644 "easier to write tools that parse man page source files.)"
2648 #: build/C/man7/man-pages.7:473
2650 "Any reference to another man page should be written with the name in bold, "
2651 "I<always> followed by the section number, formatted in Roman (normal) font, "
2652 "without any separating spaces (e.g., B<intro>(2)). The preferred way to "
2653 "write this in the source file is:"
2657 #: build/C/man7/man-pages.7:476
2659 msgid " .BR intro (2)\n"
2663 #: build/C/man7/man-pages.7:481
2665 "(Including the section number in cross references lets tools like "
2666 "B<man2html>(1) create properly hyperlinked pages.)"
2670 #: build/C/man7/man-pages.7:481
2676 #: build/C/man7/man-pages.7:486
2678 "Starting with release 2.59, I<man-pages> follows American spelling "
2679 "conventions; please write all new pages and patches according to these "
2684 #: build/C/man7/man-pages.7:486
2686 msgid "Example Programs and Shell Sessions"
2690 #: build/C/man7/man-pages.7:490
2692 "Manual pages can include example programs demonstrating how to use a system "
2693 "call or library function. However, note the following:"
2697 #: build/C/man7/man-pages.7:493
2698 msgid "Example programs should be written in C."
2702 #: build/C/man7/man-pages.7:500
2704 "An example program is only necessary and useful if it demonstrates something "
2705 "beyond what can easily be provided in a textual description of the "
2706 "interface. An example program that does nothing other than call an "
2707 "interface usually serves little purpose."
2711 #: build/C/man7/man-pages.7:504
2713 "Example programs should be fairly short (preferably less than 100 lines; "
2714 "ideally less than 50 lines)."
2718 #: build/C/man7/man-pages.7:508
2720 "Example programs should do error checking after system calls and library "
2725 #: build/C/man7/man-pages.7:512
2727 "Example programs should be complete, and compile without warnings when "
2728 "compiled with I<cc\\ -Wall>."
2732 #: build/C/man7/man-pages.7:518
2734 "Where possible and appropriate, example programs should allow "
2735 "experimentation, by varying their behavior based on inputs (ideally from "
2736 "command-line arguments, or alternatively, via input read by the program)."
2740 #: build/C/man7/man-pages.7:523
2742 "Example programs should be laid out according to Kernighan and Ritchie "
2743 "style, with 4-space indents. (Avoid the use of TAB characters in source "
2748 #: build/C/man7/man-pages.7:528
2750 "For some examples of what example programs should look like, see B<wait>(2) "
2755 #: build/C/man7/man-pages.7:532
2757 "If you include a shell session demonstrating the use of a program or other "
2758 "system feature, boldface the user input text, to distinguish it from output "
2759 "produced by the system."
2763 #: build/C/man7/man-pages.7:532
2765 msgid "Indentation of structure definitions, shell session logs, etc."
2769 #: build/C/man7/man-pages.7:538
2771 "When structure definitions, shell session logs, and so on are included in "
2772 "running text, indent them by 4 spaces (i.e., a block enclosed by I<.in\\ "
2777 #: build/C/man7/man-pages.7:545
2779 "For canonical examples of how man pages in the I<man-pages> package should "
2780 "look, see B<pipe>(2) and B<fcntl>(2)."
2784 #: build/C/man7/man-pages.7:552
2786 "B<man>(1), B<man2html>(1), B<groff>(7), B<groff_man>(7), B<man>(7), "
2791 #: build/C/man7/man.7:32
2797 #: build/C/man7/man.7:32
2803 #: build/C/man7/man.7:35
2804 msgid "man - macros to format man pages"
2808 #: build/C/man7/man.7:39
2809 msgid "B<groff -Tascii -man> I<file> \\&..."
2813 #: build/C/man7/man.7:43
2814 msgid "B<groff -Tps -man> I<file> \\&..."
2818 #: build/C/man7/man.7:60
2820 "This manual page explains the B<groff an.tmac> macro package (often called "
2821 "the B<man> macro package). This macro package should be used by developers "
2822 "when writing or porting man pages for Linux. It is fairly compatible with "
2823 "other versions of this macro package, so porting man pages should not be a "
2824 "major problem (exceptions include the NET-2 BSD release, which uses a "
2825 "totally different macro package called mdoc; see B<mdoc>(7))."
2829 #: build/C/man7/man.7:72
2831 "Note that NET-2 BSD mdoc man pages can be used with B<groff> simply by "
2832 "specifying the B<-mdoc> option instead of the B<-man> option. Using the "
2833 "B<-mandoc> option is, however, recommended, since this will automatically "
2834 "detect which macro package is in use."
2838 #: build/C/man7/man.7:76
2840 "For conventions that should be employed when writing man pages for the Linux "
2841 "I<man-pages> package, see B<man-pages>(7)."
2845 #: build/C/man7/man.7:79
2847 "The first command in a man page (after comment lines, that is, lines that "
2848 "start with B<.\\e\">) should be"
2852 #: build/C/man7/man.7:88
2854 "For details of the arguments that should be supplied to the B<TH> command, "
2855 "see B<man-pages>(7)."
2859 #: build/C/man7/man.7:94
2861 "Note that BSD mdoc-formatted pages begin with the B<Dd> command, not the "
2866 #: build/C/man7/man.7:94
2871 #. The following doesn't seem to be required (see Debian bug 411303),
2872 #. If the name contains spaces and appears
2873 #. on the same line as
2875 #. then place the heading in double quotes.
2877 #: build/C/man7/man.7:103
2878 msgid "Sections are started with B<\\&.SH> followed by the heading name."
2882 #: build/C/man7/man.7:106
2884 "The only mandatory heading is NAME, which should be the first section and be "
2885 "followed on the next line by a one-line description of the program:"
2889 #: build/C/man7/man.7:109
2894 #: build/C/man7/man.7:111
2895 msgid "item \\e- description"
2899 #: build/C/man7/man.7:125
2901 "It is extremely important that this format is followed, and that there is a "
2902 "backslash before the single dash which follows the item name. This syntax "
2903 "is used by the B<mandb>(8) program to create a database of short "
2904 "descriptions for the B<whatis>(1) and B<apropos>(1) commands. (See "
2905 "B<lexgrog>(1) for further details on the syntax of the NAME section.)"
2909 #: build/C/man7/man.7:128
2911 "For a list of other sections that might appear in a manual page, see "
2916 #: build/C/man7/man.7:128
2922 #: build/C/man7/man.7:130
2923 msgid "The commands to select the type face are:"
2927 #: build/C/man7/man.7:130
2933 #: build/C/man7/man.7:133
2938 #: build/C/man7/man.7:133
2944 #: build/C/man7/man.7:137
2946 "Bold alternating with italics (especially useful for function "
2951 #: build/C/man7/man.7:137
2957 #: build/C/man7/man.7:142
2959 "Bold alternating with Roman (especially useful for referring to other manual "
2964 #: build/C/man7/man.7:142
2970 #: build/C/man7/man.7:145
2975 #: build/C/man7/man.7:145
2981 #: build/C/man7/man.7:148
2982 msgid "Italics alternating with bold"
2986 #: build/C/man7/man.7:148
2992 #: build/C/man7/man.7:151
2993 msgid "Italics alternating with Roman"
2997 #: build/C/man7/man.7:151
3003 #: build/C/man7/man.7:154
3004 msgid "Roman alternating with bold"
3008 #: build/C/man7/man.7:154
3014 #: build/C/man7/man.7:157
3015 msgid "Roman alternating with italics"
3019 #: build/C/man7/man.7:157
3025 #: build/C/man7/man.7:160
3026 msgid "Small alternating with bold"
3030 #: build/C/man7/man.7:160
3036 #: build/C/man7/man.7:163
3037 msgid "Small (useful for acronyms)"
3041 #: build/C/man7/man.7:176
3043 "Traditionally, each command can have up to six arguments, but the GNU "
3044 "implementation removes this limitation (you might still want to limit "
3045 "yourself to 6 arguments for portability's sake). Arguments are delimited by "
3046 "spaces. Double quotes can be used to specify an argument which contains "
3047 "spaces. All of the arguments will be printed next to each other without "
3048 "intervening spaces, so that the B<\\&.BR> command can be used to specify a "
3049 "word in bold followed by a mark of punctuation in Roman. If no arguments "
3050 "are given, the command is applied to the following line of text."
3054 #: build/C/man7/man.7:176
3056 msgid "Other Macros and Strings"
3060 #: build/C/man7/man.7:196
3062 "Below are other relevant macros and predefined strings. Unless noted "
3063 "otherwise, all macros cause a break (end the current line of text). Many of "
3064 "these macros set or use the \"prevailing indent.\" The \"prevailing indent\" "
3065 "value is set by any macro with the parameter I<i> below; macros may omit "
3066 "I<i> in which case the current prevailing indent will be used. As a result, "
3067 "successive indented paragraphs can use the same indent without respecifying "
3068 "the indent value. A normal (nonindented) paragraph resets the prevailing "
3069 "indent value to its default value (0.5 inches). By default a given indent "
3070 "is measured in ens; try to use ens or ems as units for indents, since these "
3071 "will automatically adjust to font size changes. The other key macro "
3076 #: build/C/man7/man.7:196
3078 msgid "Normal Paragraphs"
3082 #: build/C/man7/man.7:197
3088 #: build/C/man7/man.7:202 build/C/man7/man.7:207
3089 msgid "Same as B<\\&.PP> (begin a new paragraph)."
3093 #: build/C/man7/man.7:202
3099 #: build/C/man7/man.7:207
3105 #: build/C/man7/man.7:210
3106 msgid "Begin a new paragraph and reset prevailing indent."
3110 #: build/C/man7/man.7:210
3112 msgid "Relative Margin Indent"
3116 #: build/C/man7/man.7:211
3118 msgid "B<\\&.RS>I< i>"
3122 #: build/C/man7/man.7:222
3124 "Start relative margin indent: moves the left margin I<i> to the right (if "
3125 "I<i> is omitted, the prevailing indent value is used). A new prevailing "
3126 "indent is set to 0.5 inches. As a result, all following paragraph(s) will "
3127 "be indented until the corresponding B<\\&.RE>."
3131 #: build/C/man7/man.7:222
3137 #: build/C/man7/man.7:226
3139 "End relative margin indent and restores the previous value of the prevailing "
3144 #: build/C/man7/man.7:226
3146 msgid "Indented Paragraph Macros"
3150 #: build/C/man7/man.7:227
3152 msgid "B<\\&.HP>I< i>"
3156 #: build/C/man7/man.7:232
3158 "Begin paragraph with a hanging indent (the first line of the paragraph is at "
3159 "the left margin of normal paragraphs, and the rest of the paragraph's lines "
3164 #: build/C/man7/man.7:232
3166 msgid "B<\\&.IP>I< x i>"
3170 #: build/C/man7/man.7:253
3172 "Indented paragraph with optional hanging tag. If the tag I<x> is omitted, "
3173 "the entire following paragraph is indented by I<i>. If the tag I<x> is "
3174 "provided, it is hung at the left margin before the following indented "
3175 "paragraph (this is just like B<\\&.TP> except the tag is included with the "
3176 "command instead of being on the following line). If the tag is too long, "
3177 "the text after the tag will be moved down to the next line (text will not be "
3178 "lost or garbled). For bulleted lists, use this macro with \\e(bu (bullet) "
3179 "or \\e(em (em dash) as the tag, and for numbered lists, use the number or "
3180 "letter followed by a period as the tag; this simplifies translation to other "
3185 #: build/C/man7/man.7:253
3187 msgid "B<\\&.TP>I< i>"
3191 #: build/C/man7/man.7:260
3193 "Begin paragraph with hanging tag. The tag is given on the next line, but "
3194 "its results are like those of the B<\\&.IP> command."
3198 #: build/C/man7/man.7:260
3200 msgid "Hypertext Link Macros"
3204 #: build/C/man7/man.7:270
3206 "(Feature supported with B<groff> only.) In order to use hypertext link "
3207 "macros, it is necessary to load the B<www.tmac> macro package. Use the "
3208 "request B<.mso www.tmac> to do this."
3212 #: build/C/man7/man.7:270
3214 msgid "B<\\&.URL>I< url link trailer>"
3217 #. The following is a kludge to get a paragraph into the listing.
3219 #: build/C/man7/man.7:283
3221 "Inserts a hypertext link to the URI (URL) I<url>, with I<link> as the text "
3222 "of the link. The I<trailer> will be printed immediately afterward. When "
3223 "generating HTML this should translate into the HTML command B<E<lt>A "
3224 "HREF=\">I<url>B<\"E<gt>>I<link>B<E<lt>/AE<gt>>I<trailer>B<.>"
3227 #. The following is a kludge to get a paragraph into the listing.
3229 #: build/C/man7/man.7:290
3231 "This and other related macros are new, and many tools won't do anything with "
3232 "them, but since many tools (including troff) will simply ignore undefined "
3233 "macros (or at worst insert their text) these are safe to insert."
3236 #. The following is a kludge to get a paragraph into the listing.
3238 #: build/C/man7/man.7:299
3240 "It can be useful to define your own B<URL> macro in manual pages for the "
3241 "benefit of those viewing it with a roff viewer other than B<groff>. That "
3242 "way, the URL, link text, and trailer text (if any) are still visible."
3246 #: build/C/man7/man.7:302
3247 msgid "Here's an example:"
3251 #: build/C/man7/man.7:304
3256 #: build/C/man7/man.7:306
3257 msgid "\\e\\e$2 \\e(laURL: \\e\\e$1 \\e(ra\\e\\e$3"
3261 #: build/C/man7/man.7:308
3266 #: build/C/man7/man.7:310
3267 msgid "\\&.if \\en[.g] .mso www.tmac"
3271 #: build/C/man7/man.7:313
3272 msgid "\\&.TH I<...>"
3276 #: build/C/man7/man.7:315
3277 msgid "I<(later in the page)>"
3281 #: build/C/man7/man.7:317
3282 msgid "This software comes from the"
3286 #: build/C/man7/man.7:319
3287 msgid "\\&.URL \"http://www.gnu.org/\" \"GNU Project\" \" of the\""
3291 #: build/C/man7/man.7:321
3292 msgid "\\&.URL \"http://www.fsf.org/\" \"Free Software Foundation\" ."
3296 #: build/C/man7/man.7:331
3298 "In the above, if B<groff> is being used, the B<www.tmac> macro package's "
3299 "definition of the URL macro will supersede the locally defined one."
3303 #: build/C/man7/man.7:336
3305 "A number of other link macros are available. See B<groff_www>(7) for more "
3310 #: build/C/man7/man.7:336
3312 msgid "Miscellaneous Macros"
3316 #: build/C/man7/man.7:337
3322 #: build/C/man7/man.7:341
3323 msgid "Reset tabs to default tab values (every 0.5 inches); does not cause a break."
3327 #: build/C/man7/man.7:341
3329 msgid "B<\\&.PD>I< d>"
3333 #: build/C/man7/man.7:346
3335 "Set inter-paragraph vertical distance to d (if omitted, d=0.4v); does not "
3340 #: build/C/man7/man.7:346
3342 msgid "B<\\&.SS>I< t>"
3346 #: build/C/man7/man.7:353
3348 "Subheading I<t> (like B<\\&.SH>, but used for a subsection inside a "
3353 #: build/C/man7/man.7:353
3355 msgid "Predefined Strings"
3359 #: build/C/man7/man.7:357
3360 msgid "The B<man> package has the following predefined strings:"
3364 #: build/C/man7/man.7:357
3370 #: build/C/man7/man.7:359
3371 msgid "Registration Symbol: \\*R"
3375 #: build/C/man7/man.7:359
3381 #: build/C/man7/man.7:361
3382 msgid "Change to default font size"
3386 #: build/C/man7/man.7:361
3392 #: build/C/man7/man.7:363
3393 msgid "Trademark Symbol: \\*(Tm"
3397 #: build/C/man7/man.7:363
3403 #: build/C/man7/man.7:365
3404 msgid "Left angled double quote: ``"
3408 #: build/C/man7/man.7:365
3414 #: build/C/man7/man.7:367
3415 msgid "Right angled double quote: ''"
3419 #: build/C/man7/man.7:367
3425 #: build/C/man7/man.7:411
3427 "Although technically B<man> is a troff macro package, in reality a large "
3428 "number of other tools process man page files that don't implement all of "
3429 "troff's abilities. Thus, it's best to avoid some of troff's more exotic "
3430 "abilities where possible to permit these other tools to work correctly. "
3431 "Avoid using the various troff preprocessors (if you must, go ahead and use "
3432 "B<tbl>(1), but try to use the B<IP> and B<TP> commands instead for "
3433 "two-column tables). Avoid using computations; most other tools can't "
3434 "process them. Use simple commands that are easy to translate to other "
3435 "formats. The following troff macros are believed to be safe (though in many "
3436 "cases they will be ignored by translators): B<\\e\">, B<.>, B<ad>, B<bp>, "
3437 "B<br>, B<ce>, B<de>, B<ds>, B<el>, B<ie>, B<if>, B<fi>, B<ft>, B<hy>, B<ig>, "
3438 "B<in>, B<na>, B<ne>, B<nf>, B<nh>, B<ps>, B<so>, B<sp>, B<ti>, B<tr>."
3442 #: build/C/man7/man.7:434
3444 "You may also use many troff escape sequences (those sequences beginning with "
3445 "\\e). When you need to include the backslash character as normal text, use "
3446 "\\ee. Other sequences you may use, where x or xx are any characters and N "
3447 "is any digit, include: B<\\e'>, B<\\e`>, B<\\e->, B<\\e.>, B<\\e\">, "
3448 "B<\\e%>, B<\\e*x>, B<\\e*(xx>, B<\\e(xx>, B<\\e$N>, B<\\enx>, B<\\en(xx>, "
3449 "B<\\efx>, and B<\\ef(xx>. Avoid using the escape sequences for drawing "
3454 #: build/C/man7/man.7:465
3456 "Do not use the optional parameter for B<bp> (break page). Use only positive "
3457 "values for B<sp> (vertical space). Don't define a macro (B<de>) with the "
3458 "same name as a macro in this or the mdoc macro package with a different "
3459 "meaning; it's likely that such redefinitions will be ignored. Every "
3460 "positive indent (B<in>) should be paired with a matching negative indent "
3461 "(although you should be using the B<RS> and B<RE> macros instead). The "
3462 "condition test (B<if,ie>) should only have \\(aqt\\(aq or \\(aqn\\(aq as "
3463 "the condition. Only translations (B<tr>) that can be ignored should be "
3464 "used. Font changes (B<ft> and the B<\\ef> escape sequence) should only "
3465 "have the values 1, 2, 3, 4, R, I, B, P, or CW (the ft command may also have "
3470 #: build/C/man7/man.7:472
3472 "If you use capabilities beyond these, check the results carefully on several "
3473 "tools. Once you've confirmed that the additional capability is safe, let "
3474 "the maintainer of this document know about the safe command or sequence that "
3475 "should be added to this list."
3479 #: build/C/man7/man.7:474
3480 msgid "I</usr/share/groff/>[*/]I<tmac/an.tmac>"
3484 #: build/C/man7/man.7:476
3485 msgid "I</usr/man/whatis>"
3489 #: build/C/man7/man.7:488
3491 "By all means include full URLs (or URIs) in the text itself; some tools such "
3492 "as B<man2html>(1) can automatically turn them into hypertext links. You "
3493 "can also use the new B<URL> macro to identify links to related information. "
3494 "If you include URLs, use the full URL (e.g., "
3495 "E<lt>http://www.kernelnotes.orgE<gt>) to ensure that tools can automatically "
3500 #: build/C/man7/man.7:497
3502 "Tools processing these files should open the file and examine the first "
3503 "nonwhitespace character. A period (.) or single quote (') at the beginning "
3504 "of a line indicates a troff-based file (such as man or mdoc). A left angle "
3505 "bracket (E<lt>) indicates an SGML/XML-based file (such as HTML or Docbook). "
3506 "Anything else suggests simple ASCII text (e.g., a \"catman\" result)."
3510 #: build/C/man7/man.7:508
3512 "Many man pages begin with B<\\'\\e\"> followed by a space and a list of "
3513 "characters, indicating how the page is to be preprocessed. For "
3514 "portability's sake to non-troff translators we recommend that you avoid "
3515 "using anything other than B<tbl>(1), and Linux can detect that "
3516 "automatically. However, you might want to include this information so your "
3517 "man page can be handled by other (less capable) systems. Here are the "
3518 "definitions of the preprocessors invoked by these characters:"
3522 #: build/C/man7/man.7:508
3528 #: build/C/man7/man.7:511
3533 #: build/C/man7/man.7:511
3539 #: build/C/man7/man.7:514
3544 #: build/C/man7/man.7:514
3550 #: build/C/man7/man.7:517
3555 #: build/C/man7/man.7:517
3561 #: build/C/man7/man.7:520
3566 #: build/C/man7/man.7:520
3572 #: build/C/man7/man.7:523
3577 #: build/C/man7/man.7:523
3583 #: build/C/man7/man.7:526
3588 #: build/C/man7/man.7:526 build/C/man7/suffixes.7:277 build/C/man7/mdoc.samples.7:2873
3594 #: build/C/man7/man.7:539
3596 "Most of the macros describe formatting (e.g., font type and spacing) instead "
3597 "of marking semantic content (e.g., this text is a reference to another "
3598 "page), compared to formats like mdoc and DocBook (even HTML has more "
3599 "semantic markings). This situation makes it harder to vary the B<man> "
3600 "format for different media, to make the formatting consistent for a given "
3601 "media, and to automatically insert cross-references. By sticking to the "
3602 "safe subset described above, it should be easier to automate transitioning "
3603 "to a different reference page format in the future."
3608 #. James Clark (jjc@jclark.com) wrote the implementation of the macro package.
3610 #. Rickard E. Faith (faith@cs.unc.edu) wrote the initial version of
3611 #. this manual page.
3613 #. Jens Schweikhardt (schweikh@noc.fdn.de) wrote the Linux Man-Page Mini-HOWTO
3614 #. (which influenced this manual page).
3616 #. David A. Wheeler (dwheeler@ida.org) heavily modified this
3617 #. manual page, such as adding detailed information on sections and macros.
3619 #: build/C/man7/man.7:555
3620 msgid "The Sun macro B<TX> is not implemented."
3624 #: build/C/man7/man.7:567
3626 "B<apropos>(1), B<groff>(1), B<lexgrog>(1), B<man>(1), B<man2html>(1), "
3627 "B<whatis>(1), B<groff_man>(7), B<groff_www>(7), B<man-pages>(7), B<mdoc>(7), "
3628 "B<mdoc.samples>(7)"
3632 #: build/C/man7/mdoc.7:40
3634 msgid "July 11, 1999"
3638 #: build/C/man7/mdoc.7:41
3644 #: build/C/man7/mdoc.7:45
3649 #: build/C/man7/mdoc.7:45
3651 msgid "quick reference guide for the"
3655 #: build/C/man7/mdoc.7:48
3656 msgid "E<.Nm \\-mdoc> macro package"
3660 #: build/C/man7/mdoc.7:52
3661 msgid "E<.Nm groff> E<.Fl m Ns Ar doc> E<.Ar files ...>"
3665 #: build/C/man7/mdoc.7:64
3667 "The E<.Nm \\-mdoc> package is a set of content-based and domain-based macros "
3668 "used to format the E<.Bx> man pages. The macro names and their meanings are "
3669 "listed below for quick reference; for a detailed explanation on using the "
3670 "package, see the tutorial sampler E<.Xr mdoc.samples 7>."
3674 #: build/C/man7/mdoc.7:69
3676 "Note that this is not the usual macro package for Linux documentation, "
3677 "although it is used for documentation of several widely used programs; see "
3682 #: build/C/man7/mdoc.7:78
3684 "The macros are described in two groups, the first includes the structural "
3685 "and physical page layout macros. The second contains the manual and general "
3686 "text domain macros which differentiate the E<.Nm \\-mdoc> package from other "
3687 "E<.Xr troff> formatting packages."
3691 #: build/C/man7/mdoc.7:78 build/C/man7/mdoc.samples.7:1805
3693 msgid "PAGE STRUCTURE DOMAIN"
3697 #: build/C/man7/mdoc.7:79
3699 msgid "Title Macros"
3703 #: build/C/man7/mdoc.7:82
3705 "To create a valid manual page, these three macros, in this order, are "
3710 #: build/C/man7/mdoc.7:83
3712 msgid "Li \"\\&.Dd \" Ar \"Month day, year\""
3716 #: build/C/man7/mdoc.7:85
3717 msgid "Document date."
3721 #: build/C/man7/mdoc.7:85
3723 msgid "Li \"\\&.Dt \" Ar \"DOCUMENT_TITLE [section] [volume]\""
3727 #: build/C/man7/mdoc.7:87
3728 msgid "Title, in upper case."
3732 #: build/C/man7/mdoc.7:87
3734 msgid "Li \"\\&.Os \" Ar \"OPERATING_SYSTEM [version/release]\""
3738 #: build/C/man7/mdoc.7:90
3739 msgid "Operating system E<.Pq Tn BSD>."
3743 #: build/C/man7/mdoc.7:91
3745 msgid "Page Layout Macros"
3749 #: build/C/man7/mdoc.7:93
3750 msgid "Section headers, paragraph breaks, lists and displays."
3754 #: build/C/man7/mdoc.7:94
3760 #: build/C/man7/mdoc.7:97
3761 msgid "Section Headers. Valid headers, in the order of presentation:"
3765 #: build/C/man7/mdoc.7:98
3771 #: build/C/man7/mdoc.7:106
3773 "Name section, should include the E<.Ql \\&.Nm> or E<.Ql \\&.Fn> and the "
3774 "E<.Ql \\&.Nd> macros."
3778 #: build/C/man7/mdoc.7:106
3784 #: build/C/man7/mdoc.7:108
3789 #: build/C/man7/mdoc.7:108
3791 msgid "Ar DESCRIPTION"
3795 #: build/C/man7/mdoc.7:111
3796 msgid "General description, should include options and parameters."
3800 #: build/C/man7/mdoc.7:111
3802 msgid "Ar RETURN VALUE"
3806 #: build/C/man7/mdoc.7:113
3807 msgid "Sections two and three function calls."
3811 #: build/C/man7/mdoc.7:113
3813 msgid "Ar ENVIRONMENT"
3817 #: build/C/man7/mdoc.7:115
3818 msgid "Describe environment variables."
3822 #: build/C/man7/mdoc.7:115
3828 #: build/C/man7/mdoc.7:117
3829 msgid "Files associated with the subject."
3833 #: build/C/man7/mdoc.7:117
3839 #: build/C/man7/mdoc.7:119
3840 msgid "Examples and suggestions."
3844 #: build/C/man7/mdoc.7:119
3846 msgid "Ar DIAGNOSTICS"
3850 #: build/C/man7/mdoc.7:121
3851 msgid "Normally used for section four device interface diagnostics."
3855 #: build/C/man7/mdoc.7:121
3861 #: build/C/man7/mdoc.7:124
3862 msgid "Sections two and three error and signal handling."
3866 #: build/C/man7/mdoc.7:124
3872 #: build/C/man7/mdoc.7:126
3873 msgid "Cross references and citations."
3877 #: build/C/man7/mdoc.7:126
3879 msgid "Ar CONFORMING TO"
3883 #: build/C/man7/mdoc.7:128
3884 msgid "Conformance to standards if applicable."
3888 #: build/C/man7/mdoc.7:128
3894 #: build/C/man7/mdoc.7:131
3895 msgid "If a standard is not applicable, the history of the subject should be given."
3899 #: build/C/man7/mdoc.7:131
3905 #: build/C/man7/mdoc.7:133
3906 msgid "Gotchas and caveats."
3910 #: build/C/man7/mdoc.7:133
3916 #: build/C/man7/mdoc.7:136
3917 msgid "Customized headers may be added at the authors discretion."
3921 #: build/C/man7/mdoc.7:137
3927 #: build/C/man7/mdoc.7:139
3928 msgid "Subsection Headers."
3932 #: build/C/man7/mdoc.7:139
3938 #: build/C/man7/mdoc.7:142
3939 msgid "Paragraph Break. Vertical space (one line)."
3943 #: build/C/man7/mdoc.7:142 build/C/man7/mdoc.samples.7:2192
3949 #: build/C/man7/mdoc.7:145
3950 msgid "(D-one) Display-one Indent and display one text line."
3954 #: build/C/man7/mdoc.7:145 build/C/man7/mdoc.samples.7:2200
3960 #: build/C/man7/mdoc.7:148
3961 msgid "(D-ell) Display-one literal. Indent and display one line of literal text."
3965 #: build/C/man7/mdoc.7:148 build/C/man7/mdoc.samples.7:2220
3971 #: build/C/man7/mdoc.7:151
3972 msgid "Begin-display block. Display options:"
3976 #: build/C/man7/mdoc.7:152 build/C/man7/mdoc.samples.7:2239
3982 #: build/C/man7/mdoc.7:154
3983 msgid "Unjustified (ragged edges)."
3987 #: build/C/man7/mdoc.7:154 build/C/man7/mdoc.samples.7:2242
3993 #: build/C/man7/mdoc.7:156
3998 #: build/C/man7/mdoc.7:156 build/C/man7/mdoc.samples.7:2246
4004 #: build/C/man7/mdoc.7:158
4005 msgid "Literal text or code."
4009 #: build/C/man7/mdoc.7:158
4011 msgid "Fl file Ar name"
4015 #: build/C/man7/mdoc.7:162
4016 msgid "Read in named E<.Ar file> and display."
4020 #: build/C/man7/mdoc.7:162 build/C/man7/mdoc.samples.7:2258
4022 msgid "Fl offset Ar string"
4026 #: build/C/man7/mdoc.7:167
4027 msgid "Offset display. Acceptable E<.Ar string> values:"
4031 #: build/C/man7/mdoc.7:168 build/C/man7/mdoc.samples.7:2266
4037 #: build/C/man7/mdoc.7:170
4038 msgid "Align block on left (default)."
4042 #: build/C/man7/mdoc.7:170 build/C/man7/mdoc.samples.7:2270
4048 #: build/C/man7/mdoc.7:172
4049 msgid "Approximate center margin."
4053 #: build/C/man7/mdoc.7:172 build/C/man7/mdoc.samples.7:2275
4059 #: build/C/man7/mdoc.7:174
4060 msgid "Six constant width spaces (a tab)."
4064 #: build/C/man7/mdoc.7:174 build/C/man7/mdoc.samples.7:2284
4066 msgid "Ar indent-two"
4070 #: build/C/man7/mdoc.7:176
4075 #: build/C/man7/mdoc.7:176 build/C/man7/mdoc.samples.7:2286
4081 #: build/C/man7/mdoc.7:179
4082 msgid "Left aligns block 2 inches from right."
4086 #: build/C/man7/mdoc.7:179
4088 msgid "Ar xx Ns Cm n"
4092 #: build/C/man7/mdoc.7:186
4094 "Where E<.Ar xx> is a number from E<.No \\&4 Ns Cm n> to E<.No \\&9\\&9 Ns Cm "
4099 #: build/C/man7/mdoc.7:186
4105 #: build/C/man7/mdoc.7:190
4106 msgid "Where E<.Ar Aa> is a callable macro name."
4110 #: build/C/man7/mdoc.7:190
4116 #: build/C/man7/mdoc.7:194
4117 msgid "The width of E<.Ar string> is used."
4121 #: build/C/man7/mdoc.7:196
4127 #: build/C/man7/mdoc.7:198
4128 msgid "End-display (matches \\&.Bd)."
4132 #: build/C/man7/mdoc.7:198
4138 #: build/C/man7/mdoc.7:202
4139 msgid "Begin-list. Create lists or columns. Options:"
4143 #: build/C/man7/mdoc.7:203
4145 msgid "Ar List-types"
4149 #: build/C/man7/mdoc.7:205
4151 msgid "Fl bullet Ta \"Bullet Item List\""
4155 #: build/C/man7/mdoc.7:206
4157 msgid "Fl item Ta \"Unlabeled List\""
4161 #: build/C/man7/mdoc.7:207
4163 msgid "Fl enum Ta \"Enumerated List\""
4167 #: build/C/man7/mdoc.7:208
4169 msgid "Fl tag Ta \"Tag Labeled List\""
4173 #: build/C/man7/mdoc.7:209
4175 msgid "Fl diag Ta \"Diagnostic List\""
4179 #: build/C/man7/mdoc.7:210
4181 msgid "Fl hang Ta \"Hanging Labeled List\""
4185 #: build/C/man7/mdoc.7:211
4187 msgid "Fl ohang Ta \"Overhanging Labeled List\""
4191 #: build/C/man7/mdoc.7:212
4193 msgid "Fl inset Ta \"Inset or Run-on Labeled List\""
4197 #: build/C/man7/mdoc.7:214
4199 msgid "List-parameters"
4203 #: build/C/man7/mdoc.7:216
4209 #: build/C/man7/mdoc.7:220
4210 msgid "(All lists.) See E<.Ql \\&.Bd> begin-display above."
4214 #: build/C/man7/mdoc.7:220
4220 #: build/C/man7/mdoc.7:227
4221 msgid "E<.Pf ( Fl tag> and E<.Fl hang> lists only.) See E<.Ql \\&.Bd>."
4225 #: build/C/man7/mdoc.7:227
4231 #: build/C/man7/mdoc.7:230
4232 msgid "(All lists.) Suppresses blank lines."
4236 #: build/C/man7/mdoc.7:232
4242 #: build/C/man7/mdoc.7:234
4247 #: build/C/man7/mdoc.7:234
4253 #: build/C/man7/mdoc.7:236
4258 #: build/C/man7/mdoc.7:237
4260 msgid "MANUAL AND GENERAL TEXT DOMAIN MACROS"
4264 #: build/C/man7/mdoc.7:241
4266 "The manual and general text domain macros are special in that most of them "
4267 "are parsed for callable macros for example:"
4271 #: build/C/man7/mdoc.7:242
4273 msgid "Li \"\\&.Op Fl s Ar file\""
4277 #: build/C/man7/mdoc.7:245
4278 msgid "Produces E<.Op Fl s Ar file>"
4282 #: build/C/man7/mdoc.7:263
4284 "In this example, the option enclosure macro E<.Ql \\&.Op> is parsed, and "
4285 "calls the callable content macro E<.Ql \\&Fl> which operates on the argument "
4286 "E<.Ql s> and then calls the callable content macro E<.Ql \\&Ar> which "
4287 "operates on the argument E<.Ql file>. Some macros may be callable, but are "
4288 "not parsed and vice versa. These macros are indicated in the E<.Em parsed> "
4289 "and E<.Em callable> columns below."
4293 #: build/C/man7/mdoc.7:265
4294 msgid "Unless stated, manual domain macros share a common syntax:"
4298 #: build/C/man7/mdoc.7:266
4300 msgid "\\&.Va argument [\\ .\\ ,\\ ;\\ :\\ (\\ )\\ [\\ ]\\ argument ...\\ ]"
4304 #: build/C/man7/mdoc.7:286
4306 "E<.Sy Note>: Opening and closing punctuation characters are only recognized "
4307 "as such if they are presented one at a time. The string E<.Ql \"),\"> is "
4308 "not recognized as punctuation and will be output with a leading white space "
4309 "and in what ever font the calling macro uses. The argument list E<.Ql \"] ) "
4310 ",\"> is recognized as three sequential closing punctuation characters and a "
4311 "leading white space is not output between the characters and the previous "
4312 "argument (if any). The special meaning of a punctuation character may be "
4313 "escaped with the string E<.Ql \\e&>. For example the following string,"
4317 #: build/C/man7/mdoc.7:287
4319 msgid "Li \"\\&.Ar file1\\ , file2\\ , file3\\ )\\ .\""
4323 #: build/C/man7/mdoc.7:290
4324 msgid "Produces E<.Ar file1 , file2 , file3>)."
4328 #: build/C/man7/mdoc.7:292
4330 msgid "Manual Domain Macros"
4334 #: build/C/man7/mdoc.7:294 build/C/man7/mdoc.7:319
4336 msgid "Em \"Name\tParsed\tCallable\tDescription\""
4340 #: build/C/man7/mdoc.7:295
4342 msgid "Li \\&Ad Ta Yes Ta Yes Ta \"Address. (This macro may be deprecated.)\""
4346 #: build/C/man7/mdoc.7:296
4348 msgid "Li \\&An Ta Yes Ta Yes Ta \"Author name.\""
4352 #: build/C/man7/mdoc.7:297
4354 msgid "Li \\&Ar Ta Yes Ta Yes Ta \"Command-line argument.\""
4358 #: build/C/man7/mdoc.7:298
4361 "Li \\&Cd Ta \\&No Ta \\&No Ta \"Configuration declaration (section four "
4366 #: build/C/man7/mdoc.7:299
4368 msgid "Li \\&Cm Ta Yes Ta Yes Ta \"Command-line argument modifier.\""
4372 #: build/C/man7/mdoc.7:300
4374 msgid "Li \\&Dv Ta Yes Ta Yes Ta \"Defined variable (source code).\""
4378 #: build/C/man7/mdoc.7:301
4380 msgid "Li \\&Er Ta Yes Ta Yes Ta \"Error number (source code).\""
4384 #: build/C/man7/mdoc.7:302
4386 msgid "Li \\&Ev Ta Yes Ta Yes Ta \"Environment variable.\""
4390 #: build/C/man7/mdoc.7:303
4392 msgid "Li \\&Fa Ta Yes Ta Yes Ta \"Function argument.\""
4396 #: build/C/man7/mdoc.7:304
4398 msgid "Li \\&Fd Ta Yes Ta Yes Ta \"Function declaration.\""
4402 #: build/C/man7/mdoc.7:305
4404 msgid "Li \\&Fn Ta Yes Ta Yes Ta \"Function call (also .Fo and .Fc).\""
4408 #: build/C/man7/mdoc.7:306
4410 msgid "Li \\&Ic Ta Yes Ta Yes Ta \"Interactive command.\""
4414 #: build/C/man7/mdoc.7:307
4416 msgid "Li \\&Li Ta Yes Ta Yes Ta \"Literal text.\""
4420 #: build/C/man7/mdoc.7:308
4422 msgid "Li \\&Nm Ta Yes Ta Yes Ta \"Command name.\""
4426 #: build/C/man7/mdoc.7:309
4428 msgid "Li \\&Op Ta Yes Ta Yes Ta \"Option (also .Oo and .Oc).\""
4432 #: build/C/man7/mdoc.7:310
4434 msgid "Li \\&Ot Ta Yes Ta Yes Ta \"Old style function type (Fortran only).\""
4438 #: build/C/man7/mdoc.7:311
4440 msgid "Li \\&Pa Ta Yes Ta Yes Ta \"Pathname or filename.\""
4444 #: build/C/man7/mdoc.7:312
4446 msgid "Li \\&St Ta Yes Ta Yes Ta \"Standards (\\-p1003.2, \\-p1003.1 or \\-ansiC)\""
4450 #: build/C/man7/mdoc.7:313
4452 msgid "Li \\&Va Ta Yes Ta Yes Ta \"Variable name.\""
4456 #: build/C/man7/mdoc.7:314
4458 msgid "Li \\&Vt Ta Yes Ta Yes Ta \"Variable type (Fortran only).\""
4462 #: build/C/man7/mdoc.7:315
4464 msgid "Li \\&Xr Ta Yes Ta Yes Ta \"Manual Page Cross Reference.\""
4468 #: build/C/man7/mdoc.7:317
4470 msgid "General Text Domain Macros"
4474 #: build/C/man7/mdoc.7:320
4476 msgid "Li \\&%A Ta Yes Ta \\&No Ta \"Reference author.\""
4480 #: build/C/man7/mdoc.7:321
4482 msgid "Li \\&%B Ta Yes Ta Yes Ta \"Reference book title.\""
4486 #: build/C/man7/mdoc.7:322
4488 msgid "Li \\&%\\&C Ta \\&No Ta \\&No Ta \"Reference place of publishing (city).\""
4492 #: build/C/man7/mdoc.7:323
4494 msgid "Li \\&%\\&D Ta \\&No Ta \\&No Ta \"Reference date.\""
4498 #: build/C/man7/mdoc.7:324
4500 msgid "Li \\&%J Ta Yes Ta Yes Ta \"Reference journal title.\""
4504 #: build/C/man7/mdoc.7:325
4506 msgid "Li \\&%N Ta \\&No Ta \\&No Ta \"Reference issue number.\""
4510 #: build/C/man7/mdoc.7:326
4512 msgid "Li \\&%\\&O Ta \\&No Ta \\&No Ta \"Reference optional information.\""
4516 #: build/C/man7/mdoc.7:327
4518 msgid "Li \\&%P Ta \\&No Ta \\&No Ta \"Reference page number(s).\""
4522 #: build/C/man7/mdoc.7:328
4524 msgid "Li \\&%R Ta \\&No Ta \\&No Ta \"Reference report Name.\""
4528 #: build/C/man7/mdoc.7:329
4530 msgid "Li \\&%T Ta Yes Ta Yes Ta \"Reference article title.\""
4534 #: build/C/man7/mdoc.7:330
4536 msgid "Li \\&%V Ta \\&No Ta \\&No Ta \"Reference volume.\""
4540 #: build/C/man7/mdoc.7:331
4542 msgid "Li \\&Ac Ta Yes Ta Yes Ta \"Angle close quote.\""
4546 #: build/C/man7/mdoc.7:332
4548 msgid "Li \\&Ao Ta Yes Ta Yes Ta \"Angle open quote.\""
4552 #: build/C/man7/mdoc.7:333
4554 msgid "Li \\&Ap Ta Yes Ta Yes Ta Apostrophe."
4558 #: build/C/man7/mdoc.7:334
4560 msgid "Li \\&Aq Ta Yes Ta Yes Ta \"Angle quote.\""
4564 #: build/C/man7/mdoc.7:335
4566 msgid "Li \\&At Ta \\&No Ta \\&No Ta Tn \"AT&T UNIX\""
4570 #: build/C/man7/mdoc.7:336
4572 msgid "Li \\&Bc Ta Yes Ta Yes Ta \"Bracket close quote.\""
4576 #: build/C/man7/mdoc.7:337
4578 msgid "Li \\&Bf Ta \\&No Ta \\&No Ta \"Begin font mode.\""
4582 #: build/C/man7/mdoc.7:338
4584 msgid "Li \\&Bo Ta Yes Ta Yes Ta \"Bracket open quote.\""
4588 #: build/C/man7/mdoc.7:339
4590 msgid "Li \\&Bq Ta Yes Ta Yes Ta \"Bracket quote.\""
4594 #: build/C/man7/mdoc.7:340
4596 msgid "Li \\&Bx Ta Yes Ta Yes Ta Bx ."
4600 #: build/C/man7/mdoc.7:341
4602 msgid "Li \\&Db Ta \\&No Ta \\&No Ta \"Debug (default is \\*qoff\\*q)\""
4606 #: build/C/man7/mdoc.7:342
4608 msgid "Li \\&Dc Ta Yes Ta Yes Ta \"Double close quote.\""
4612 #: build/C/man7/mdoc.7:343
4614 msgid "Li \\&Do Ta Yes Ta Yes Ta \"Double open quote.\""
4618 #: build/C/man7/mdoc.7:344
4620 msgid "Li \\&Dq Ta Yes Ta Yes Ta \"Double quote.\""
4624 #: build/C/man7/mdoc.7:345
4626 msgid "Li \\&Ec Ta Yes Ta Yes Ta \"Enclose string close quote.\""
4630 #: build/C/man7/mdoc.7:346
4632 msgid "Li \\&Ef Ta \\&No Ta \\&No Ta \"End font mode.\""
4636 #: build/C/man7/mdoc.7:347
4638 msgid "Li \\&Em Ta Yes Ta Yes Ta \"Emphasis (traditional English).\""
4642 #: build/C/man7/mdoc.7:348
4644 msgid "Li \\&Eo Ta Yes Ta Yes Ta \"Enclose string open quote.\""
4648 #: build/C/man7/mdoc.7:349
4650 msgid "Li \\&Fx Ta \\&No Ta \\&No Ta Tn \"FreeBSD operating system\""
4654 #: build/C/man7/mdoc.7:350
4656 msgid "Li \\&No Ta Yes Ta Yes Ta \"Normal text (no-op).\""
4660 #: build/C/man7/mdoc.7:351
4662 msgid "Li \\&Ns Ta Yes Ta Yes Ta \"No space.\""
4666 #: build/C/man7/mdoc.7:352
4668 msgid "Li \\&Pc Ta Yes Ta Yes Ta \"Parenthesis close quote.\""
4672 #: build/C/man7/mdoc.7:353
4674 msgid "Li \\&Pf Ta Yes Ta \\&No Ta \"Prefix string.\""
4678 #: build/C/man7/mdoc.7:354
4680 msgid "Li \\&Po Ta Yes Ta Yes Ta \"Parenthesis open quote.\""
4684 #: build/C/man7/mdoc.7:355
4686 msgid "Li \\&Pq Ta Yes Ta Yes Ta \"Parentheses quote.\""
4690 #: build/C/man7/mdoc.7:356
4692 msgid "Li \\&Qc Ta Yes Ta Yes Ta \"Straight Double close quote.\""
4696 #: build/C/man7/mdoc.7:357
4698 msgid "Li \\&Ql Ta Yes Ta Yes Ta \"Quoted literal.\""
4702 #: build/C/man7/mdoc.7:358
4704 msgid "Li \\&Qo Ta Yes Ta Yes Ta \"Straight Double open quote.\""
4708 #: build/C/man7/mdoc.7:359
4710 msgid "Li \\&Qq Ta Yes Ta Yes Ta \"Straight Double quote.\""
4714 #: build/C/man7/mdoc.7:360
4716 msgid "Li \\&Re Ta \\&No Ta \\&No Ta \"Reference end.\""
4720 #: build/C/man7/mdoc.7:361
4722 msgid "Li \\&Rs Ta \\&No Ta \\&No Ta \"Reference start.\""
4726 #: build/C/man7/mdoc.7:362
4729 "Li \\&Rv Ta \\&No Ta \\&No Ta \"Return values (sections two and three "
4734 #: build/C/man7/mdoc.7:363
4736 msgid "Li \\&Sc Ta Yes Ta Yes Ta \"Single close quote.\""
4740 #: build/C/man7/mdoc.7:364
4742 msgid "Li \\&So Ta Yes Ta Yes Ta \"Single open quote.\""
4746 #: build/C/man7/mdoc.7:365
4748 msgid "Li \\&Sq Ta Yes Ta Yes Ta \"Single quote.\""
4752 #: build/C/man7/mdoc.7:366
4754 msgid "Li \\&Sm Ta \\&No Ta \\&No Ta \"Space mode (default is \\*qon\\*q)\""
4758 #: build/C/man7/mdoc.7:367
4760 msgid "Li \\&Sx Ta Yes Ta Yes Ta \"Section Cross Reference.\""
4764 #: build/C/man7/mdoc.7:368
4766 msgid "Li \\&Sy Ta Yes Ta Yes Ta \"Symbolic (traditional English).\""
4770 #: build/C/man7/mdoc.7:369
4772 msgid "Li \\&Tn Ta Yes Ta Yes Ta \"Trade or type name (small Caps).\""
4776 #: build/C/man7/mdoc.7:370
4778 msgid "Li \\&Ux Ta Yes Ta Yes Ta Ux"
4782 #: build/C/man7/mdoc.7:371
4784 msgid "Li \\&Xc Ta Yes Ta Yes Ta \"Extend argument list close.\""
4788 #: build/C/man7/mdoc.7:372
4790 msgid "Li \\&Xo Ta Yes Ta Yes Ta \"Extend argument list open.\""
4794 #: build/C/man7/mdoc.7:386
4796 "Macro names ending in E<.Ql q> quote remaining items on the argument list. "
4797 "Macro names ending in E<.Ql o> begin a quote which may span more than one "
4798 "line of input and are close quoted with the matching macro name ending in "
4799 "E<.Ql c>. Enclosure macros may be nested and are limited to eight "
4804 #: build/C/man7/mdoc.7:398
4806 "Note: the extended argument list macros E<.Pf ( Ql \\&.Xo>, E<.Ql \\&.Xc>) "
4807 "and the function enclosure macros E<.Pf ( Ql \\&.Fo>, E<.Ql \\&.Fc>) are "
4808 "irregular. The extended list macros are used when the number of macro "
4809 "arguments would exceed the E<.Xr troff> limitation of nine arguments."
4812 #. The following does not apply on Linux:
4813 #. .Sh CONFIGURATION
4814 #. For site specific configuration of the macro package,
4816 #. .Pa /usr/src/share/tmac/README .
4818 #: build/C/man7/mdoc.7:409
4820 "The macros UR (starting a URI/URL hypertext reference), UE (ending one), and "
4821 "UN (identifying a target for a reference) are also available. See E<.Xr man "
4822 "7> for more information on these macros."
4826 #: build/C/man7/mdoc.7:411
4832 #: build/C/man7/mdoc.7:413
4833 msgid "Manual and general text domain macros."
4837 #: build/C/man7/mdoc.7:413
4839 msgid "Pa tmac/doc-common"
4843 #: build/C/man7/mdoc.7:415
4844 msgid "Common structural macros and definitions."
4848 #: build/C/man7/mdoc.7:415
4850 msgid "Pa tmac/doc-nroff"
4854 #: build/C/man7/mdoc.7:419
4855 msgid "Site dependent E<.Xr nroff> style file."
4859 #: build/C/man7/mdoc.7:419
4861 msgid "Pa tmac/doc-ditroff"
4865 #: build/C/man7/mdoc.7:423
4866 msgid "Site dependent E<.Xr troff> style file."
4870 #: build/C/man7/mdoc.7:423
4872 msgid "Pa tmac/doc-syms"
4876 #: build/C/man7/mdoc.7:425
4877 msgid "Special defines (such as the standards macro)."
4881 #: build/C/man7/mdoc.7:431
4882 msgid "E<.Xr groff_mdoc 7>, E<.Xr mdoc.samples 7>, E<.Xr man 7>, E<.Xr man-pages 7>"
4886 #: build/C/man7/mdoc.7:438 build/C/man7/mdoc.samples.7:2954
4888 "This page is part of release 3.41 of the Linux E<.Em man-pages> project. A "
4889 "description of the project, and information about reporting bugs, can be "
4890 "found at http://www.kernel.org/doc/man-pages/."
4894 #: build/C/man7/operator.7:38
4900 #: build/C/man7/operator.7:38
4906 #: build/C/man7/operator.7:41
4907 msgid "operator - C operator precedence and order of evaluation"
4911 #: build/C/man7/operator.7:43
4912 msgid "This manual page lists C operators and their precedence in evaluation."
4916 #: build/C/man7/operator.7:61
4919 "B<Operator Associativity>\n"
4920 "() [] -E<gt> . left to right\n"
4921 "! ~ ++ -- + - (type) * & sizeof right to left\n"
4922 "* / % left to right\n"
4923 "+ - left to right\n"
4924 "E<lt>E<lt> E<gt>E<gt> left to right\n"
4925 "E<lt> E<lt>= E<gt> E<gt>= left to right\n"
4926 "== != left to right\n"
4930 "&& left to right\n"
4931 "|| left to right\n"
4932 "?: right to left\n"
4933 "= += -= *= /= %= E<lt>E<lt>= E<gt>E<gt>= &= ^= |= right to left\n"
4938 #: build/C/man7/posixoptions.7:23
4940 msgid "POSIXOPTIONS"
4944 #: build/C/man7/posixoptions.7:23
4950 #: build/C/man7/posixoptions.7:26
4951 msgid "posixoptions - optional parts of the POSIX standard"
4955 #: build/C/man7/posixoptions.7:40
4957 "The POSIX standard (the information below is from POSIX.1-2001) describes a "
4958 "set of behaviors and interfaces for a compliant system. However, many "
4959 "interfaces are optional and there are feature test macros to test the "
4960 "availability of interfaces at compile time, and functions B<sysconf>(3), "
4961 "B<fpathconf>(3), B<pathconf>(3), B<confstr>(3) to do this at run time. "
4962 "From shell scripts one can use B<getconf>(1). For more detail, see "
4967 #: build/C/man7/posixoptions.7:47
4969 "We give the name of the POSIX abbreviation, the option, the name of the "
4970 "B<sysconf>(3) parameter used to inquire about the option, and possibly a "
4971 "very short description. Much more precise detail can be found in the POSIX "
4972 "standard itself, versions of which can nowadays be accessed freely on the "
4977 #: build/C/man7/posixoptions.7:47
4979 msgid "ADV - _POSIX_ADVISORY_INFO - _SC_ADVISORY_INFO"
4983 #: build/C/man7/posixoptions.7:49
4984 msgid "The following advisory functions are present:"
4988 #: build/C/man7/posixoptions.7:57
4991 "I<posix_fadvise>(),\n"
4992 "I<posix_fallocate>(),\n"
4993 "I<posix_memalign>(),\n"
4994 "I<posix_madvise>().\n"
4998 #: build/C/man7/posixoptions.7:60
5000 msgid "AIO - _POSIX_ASYNCHRONOUS_IO - _SC_ASYNCHRONOUS_IO"
5004 #: build/C/man7/posixoptions.7:65
5006 "The header I<E<lt>aio.hE<gt>> is present. The following functions are "
5011 #: build/C/man7/posixoptions.7:77
5014 "I<aio_cancel>(),\n"
5018 "I<aio_return>(),\n"
5019 "I<aio_suspend>(),\n"
5021 "I<lio_listio>().\n"
5025 #: build/C/man7/posixoptions.7:80
5027 msgid "BAR - _POSIX_BARRIERS - _SC_BARRIERS"
5031 #: build/C/man7/posixoptions.7:87 build/C/man7/posixoptions.7:457
5033 "This option implies the B<_POSIX_THREADS> and "
5034 "B<_POSIX_THREAD_SAFE_FUNCTIONS> options. The following functions are "
5039 #: build/C/man7/posixoptions.7:96
5042 "I<pthread_barrier_destroy>(),\n"
5043 "I<pthread_barrier_init>(),\n"
5044 "I<pthread_barrier_wait>(),\n"
5045 "I<pthread_barrierattr_destroy>(),\n"
5046 "I<pthread_barrierattr_init>().\n"
5050 #. Batch environment.
5054 #: build/C/man7/posixoptions.7:103
5056 msgid "--- - POSIX_CHOWN_RESTRICTED"
5059 #. What about lchown() ?
5061 #: build/C/man7/posixoptions.7:111
5063 "If this option is in effect (as it always is under POSIX.1-2001) then only "
5064 "root may change the owner of a file, and nonroot can only set the group of a "
5065 "file to one of the groups it belongs to. This affects the functions "
5066 "I<chown>(), I<fchown>()."
5070 #: build/C/man7/posixoptions.7:111
5072 msgid "CS - _POSIX_CLOCK_SELECTION - _SC_CLOCK_SELECTION"
5076 #: build/C/man7/posixoptions.7:116
5078 "This option implies the B<_POSIX_TIMERS> option. The following functions "
5083 #: build/C/man7/posixoptions.7:123
5086 "I<pthread_condattr_getclock>(),\n"
5087 "I<pthread_condattr_setclock>(),\n"
5088 "I<clock_nanosleep>().\n"
5092 #: build/C/man7/posixoptions.7:131
5094 "If B<CLOCK_REALTIME> is changed by the function I<clock_settime>(), then "
5095 "this affects all timers set for an absolute time."
5099 #: build/C/man7/posixoptions.7:131
5101 msgid "CPT - _POSIX_CPUTIME - _SC_CPUTIME"
5105 #. Fortran development
5109 #: build/C/man7/posixoptions.7:144
5111 "The clockID CLOCK_PROCESS_CPUTIME_ID is supported. The initial value of "
5112 "this clock is 0 for each process. This option implies the B<_POSIX_TIMERS> "
5113 "option. The function I<clock_getcpuclockid>() is present."
5117 #: build/C/man7/posixoptions.7:144
5119 msgid "--- - _POSIX_FILE_LOCKING - _SC_FILE_LOCKING"
5123 #. IEC 60559 Floating-Point Option.
5125 #: build/C/man7/posixoptions.7:147 build/C/man7/posixoptions.7:237
5126 msgid "This option has been deleted. Not in final XPG6."
5130 #: build/C/man7/posixoptions.7:147
5132 msgid "FSC - _POSIX_FSYNC - _SC_FSYNC "
5136 #: build/C/man7/posixoptions.7:151
5137 msgid "The function I<fsync>() is present."
5141 #: build/C/man7/posixoptions.7:151
5143 msgid "IP6 - _POSIX_IPV6 - _SC_IPV6"
5147 #: build/C/man7/posixoptions.7:153
5148 msgid "Internet Protocol Version 6 is supported."
5152 #: build/C/man7/posixoptions.7:153
5154 msgid "--- - _POSIX_JOB_CONTROL - _SC_JOB_CONTROL"
5158 #: build/C/man7/posixoptions.7:157
5160 "If this option is in effect (as it always is under POSIX.1-2001) then the "
5161 "system implements POSIX-style job control, and the following functions are "
5166 #: build/C/man7/posixoptions.7:168
5173 "I<tcsendbreak>(),\n"
5179 #: build/C/man7/posixoptions.7:170
5181 msgid "MF - _POSIX_MAPPED_FILES - _SC_MAPPED_FILES"
5185 #: build/C/man7/posixoptions.7:179
5187 "Shared memory is supported. The include file I<E<lt>sys/mman.hE<gt>> is "
5188 "present. The following functions are present: I<mmap>(), I<msync>(), "
5193 #: build/C/man7/posixoptions.7:179
5195 msgid "ML - _POSIX_MEMLOCK - _SC_MEMLOCK"
5199 #: build/C/man7/posixoptions.7:185
5201 "Shared memory can be locked into core. The functions I<mlockall>(), "
5202 "I<munlockall>() are present."
5206 #: build/C/man7/posixoptions.7:185
5208 msgid "MR/MLR - _POSIX_MEMLOCK_RANGE - _SC_MEMLOCK_RANGE"
5212 #: build/C/man7/posixoptions.7:191
5214 "More precisely, ranges can be locked into core. The functions I<mlock>(), "
5215 "I<munlock>() are present."
5219 #: build/C/man7/posixoptions.7:191
5221 msgid "MPR - _POSIX_MEMORY_PROTECTION - _SC_MEMORY_PROTECTION"
5225 #: build/C/man7/posixoptions.7:195
5226 msgid "The function I<mprotect>() is present."
5230 #: build/C/man7/posixoptions.7:195
5232 msgid "MSG - _POSIX_MESSAGE_PASSING - _SC_MESSAGE_PASSING"
5236 #: build/C/man7/posixoptions.7:200
5238 "The include file I<E<lt>mqueue.hE<gt>> is present. The following functions "
5243 #: build/C/man7/posixoptions.7:212
5247 "I<mq_getattr>(),\n"
5250 "I<mq_receive>(),\n"
5252 "I<mq_setattr>(),\n"
5257 #: build/C/man7/posixoptions.7:215
5259 msgid "MON - _POSIX_MONOTONIC_CLOCK - _SC_MONOTONIC_CLOCK"
5263 #: build/C/man7/posixoptions.7:222
5265 "B<CLOCK_MONOTONIC> is supported. This option implies the B<_POSIX_TIMERS> "
5266 "option. Affected functions are"
5270 #: build/C/man7/posixoptions.7:230
5273 "I<aio_suspend>(),\n"
5274 "I<clock_getres>(),\n"
5275 "I<clock_gettime>(),\n"
5276 "I<clock_settime>(),\n"
5277 "I<timer_create>().\n"
5281 #: build/C/man7/posixoptions.7:232
5283 msgid "--- - _POSIX_MULTI_PROCESS - _SC_MULTI_PROCESS"
5287 #: build/C/man7/posixoptions.7:237
5289 msgid "--- - _POSIX_NO_TRUNC"
5293 #: build/C/man7/posixoptions.7:244
5295 "If this option is in effect (as it always is under POSIX.1-2001) then "
5296 "pathname components longer than B<NAME_MAX> are not truncated, but give an "
5297 "error. This property may be dependent on the path prefix of the component."
5301 #: build/C/man7/posixoptions.7:244
5303 msgid "PIO - _POSIX_PRIORITIZED_IO - _SC_PRIORITIZED_IO"
5307 #: build/C/man7/posixoptions.7:247
5309 "This option says that one can specify priorities for asynchronous I/O. This "
5310 "affects the functions"
5314 #: build/C/man7/posixoptions.7:253
5322 #: build/C/man7/posixoptions.7:255
5324 msgid "PS - _POSIX_PRIORITY_SCHEDULING - _SC_PRIORITY_SCHEDULING"
5328 #: build/C/man7/posixoptions.7:260
5330 "The include file I<E<lt>sched.hE<gt>> is present. The following functions "
5335 #: build/C/man7/posixoptions.7:272
5338 "I<sched_get_priority_max>(),\n"
5339 "I<sched_get_priority_min>(),\n"
5340 "I<sched_getparam>(),\n"
5341 "I<sched_getscheduler>(),\n"
5342 "I<sched_rr_get_interval>(),\n"
5343 "I<sched_setparam>(),\n"
5344 "I<sched_setscheduler>(),\n"
5345 "I<sched_yield>().\n"
5349 #: build/C/man7/posixoptions.7:278
5351 "If also B<_POSIX_SPAWN> is in effect, then the following functions are "
5356 #: build/C/man7/posixoptions.7:286 build/C/man7/posixoptions.7:448
5359 "I<posix_spawnattr_getschedparam>(),\n"
5360 "I<posix_spawnattr_getschedpolicy>(),\n"
5361 "I<posix_spawnattr_setschedparam>(),\n"
5362 "I<posix_spawnattr_setschedpolicy>().\n"
5366 #: build/C/man7/posixoptions.7:288
5368 msgid "RS - _POSIX_RAW_SOCKETS"
5372 #: build/C/man7/posixoptions.7:293
5374 "Raw sockets are supported. Affected functions are I<getsockopt>(), "
5379 #: build/C/man7/posixoptions.7:293
5381 msgid "--- - _POSIX_READER_WRITER_LOCKS - _SC_READER_WRITER_LOCKS"
5385 #: build/C/man7/posixoptions.7:301
5387 "This option implies the B<_POSIX_THREADS> option. Conversely, under "
5388 "POSIX.1-2001 the B<_POSIX_THREADS> option implies this option."
5392 #: build/C/man7/posixoptions.7:303
5394 msgid "The following functions are present:\n"
5398 #: build/C/man7/posixoptions.7:314
5401 "I<pthread_rwlock_destroy>(),\n"
5402 "I<pthread_rwlock_init>(),\n"
5403 "I<pthread_rwlock_rdlock>(),\n"
5404 "I<pthread_rwlock_tryrdlock>(),\n"
5405 "I<pthread_rwlock_trywrlock>(),\n"
5406 "I<pthread_rwlock_unlock>(),\n"
5407 "I<pthread_rwlock_wrlock>(),\n"
5408 "I<pthread_rwlockattr_destroy>(),\n"
5409 "I<pthread_rwlockattr_init>().\n"
5413 #: build/C/man7/posixoptions.7:316
5415 msgid "RTS - _POSIX_REALTIME_SIGNALS - _SC_REALTIME_SIGNALS"
5419 #: build/C/man7/posixoptions.7:319
5420 msgid "Realtime signals are supported. The following functions are present:"
5424 #: build/C/man7/posixoptions.7:326
5428 "I<sigtimedwait>(),\n"
5429 "I<sigwaitinfo>().\n"
5433 #: build/C/man7/posixoptions.7:329
5435 msgid "--- - _POSIX_REGEXP - _SC_REGEXP"
5439 #: build/C/man7/posixoptions.7:333
5441 "If this option is in effect (as it always is under POSIX.1-2001) then POSIX "
5442 "regular expressions are supported and the following functions are present:"
5446 #: build/C/man7/posixoptions.7:341
5456 #: build/C/man7/posixoptions.7:344
5458 msgid "--- - _POSIX_SAVED_IDS - _SC_SAVED_IDS"
5462 #: build/C/man7/posixoptions.7:348
5464 "If this option is in effect (as it always is under POSIX.1-2001) then a "
5465 "process has a saved set-user-ID and a saved set-group-ID. Affected "
5470 #: build/C/man7/posixoptions.7:358
5482 #. Software development
5484 #: build/C/man7/posixoptions.7:363
5486 msgid "SEM - _POSIX_SEMAPHORES - _SC_SEMAPHORES"
5490 #: build/C/man7/posixoptions.7:368
5492 "The include file I<E<lt>semaphore.hE<gt>> is present. The following "
5493 "functions are present:"
5497 #: build/C/man7/posixoptions.7:381
5501 "I<sem_destroy>(),\n"
5502 "I<sem_getvalue>(),\n"
5506 "I<sem_trywait>(),\n"
5507 "I<sem_unlink>(),\n"
5512 #: build/C/man7/posixoptions.7:384
5514 msgid "SHM - _POSIX_SHARED_MEMORY_OBJECTS - _SC_SHARED_MEMORY_OBJECTS"
5518 #: build/C/man7/posixoptions.7:386 build/C/man7/posixoptions.7:702 build/C/man7/posixoptions.7:718 build/C/man7/posixoptions.7:832
5519 msgid "The following functions are present:"
5523 #: build/C/man7/posixoptions.7:394
5529 "I<shm_unlink>().\n"
5533 #: build/C/man7/posixoptions.7:397
5535 msgid "--- - _POSIX_SHELL - _SC_SHELL"
5539 #: build/C/man7/posixoptions.7:402
5541 "If this option is in effect (as it always is under POSIX.1-2001), the "
5542 "function I<system>() is present."
5546 #: build/C/man7/posixoptions.7:402
5548 msgid "SPN - _POSIX_SPAWN - _SC_SPAWN"
5552 #: build/C/man7/posixoptions.7:412
5554 "This option describes support for process creation in a context where it is "
5555 "difficult or impossible to use I<fork>(), for example, because no MMU is "
5556 "present. If B<_POSIX_SPAWN> is in effect, then the include file "
5557 "I<E<lt>spawn.hE<gt>> and the following functions are present:"
5561 #: build/C/man7/posixoptions.7:433
5564 "I<posix_spawn>(),\n"
5565 "I<posix_spawn_file_actions_addclose>(),\n"
5566 "I<posix_spawn_file_actions_adddup2>(),\n"
5567 "I<posix_spawn_file_actions_addopen>(),\n"
5568 "I<posix_spawn_file_actions_destroy>(),\n"
5569 "I<posix_spawn_file_actions_init>(),\n"
5570 "I<posix_spawnattr_destroy>(),\n"
5571 "I<posix_spawnattr_getsigdefault>(),\n"
5572 "I<posix_spawnattr_getflags>(),\n"
5573 "I<posix_spawnattr_getpgroup>(),\n"
5574 "I<posix_spawnattr_getsigmask>(),\n"
5575 "I<posix_spawnattr_init>(),\n"
5576 "I<posix_spawnattr_setsigdefault>(),\n"
5577 "I<posix_spawnattr_setflags>(),\n"
5578 "I<posix_spawnattr_setpgroup>(),\n"
5579 "I<posix_spawnattr_setsigmask>(),\n"
5580 "I<posix_spawnp>().\n"
5584 #: build/C/man7/posixoptions.7:440
5586 "If also B<_POSIX_PRIORITY_SCHEDULING> is in effect, then the following "
5587 "functions are present:"
5591 #: build/C/man7/posixoptions.7:450
5593 msgid "SPI - _POSIX_SPIN_LOCKS - _SC_SPIN_LOCKS"
5597 #: build/C/man7/posixoptions.7:466
5600 "I<pthread_spin_destroy>(),\n"
5601 "I<pthread_spin_init>(),\n"
5602 "I<pthread_spin_lock>(),\n"
5603 "I<pthread_spin_trylock>(),\n"
5604 "I<pthread_spin_unlock>().\n"
5608 #: build/C/man7/posixoptions.7:469
5610 msgid "SS - _POSIX_SPORADIC_SERVER - _SC_SPORADIC_SERVER"
5614 #: build/C/man7/posixoptions.7:477
5616 "The scheduling policy B<SCHED_SPORADIC> is supported. This option implies "
5617 "the B<_POSIX_PRIORITY_SCHEDULING> option. Affected functions are"
5621 #: build/C/man7/posixoptions.7:483
5624 "I<sched_setparam>(),\n"
5625 "I<sched_setscheduler>().\n"
5629 #: build/C/man7/posixoptions.7:486
5631 msgid "SIO - _POSIX_SYNCHRONIZED_IO - _SC_SYNCHRONIZED_IO"
5635 #: build/C/man7/posixoptions.7:492
5636 msgid "Affected functions are I<open>(), I<msync>(), I<fsync>(), I<fdatasync>()."
5640 #: build/C/man7/posixoptions.7:492
5642 msgid "TSA - _POSIX_THREAD_ATTR_STACKADDR - _SC_THREAD_ATTR_STACKADDR"
5646 #: build/C/man7/posixoptions.7:494 build/C/man7/posixoptions.7:507 build/C/man7/posixoptions.7:538 build/C/man7/posixoptions.7:549 build/C/man7/posixoptions.7:584 build/C/man7/posixoptions.7:601
5647 msgid "Affected functions are"
5651 #: build/C/man7/posixoptions.7:502
5654 "I<pthread_attr_getstack>(),\n"
5655 "I<pthread_attr_getstackaddr>(),\n"
5656 "I<pthread_attr_setstack>(),\n"
5657 "I<pthread_attr_setstackaddr>().\n"
5661 #: build/C/man7/posixoptions.7:505
5663 msgid "TSS - _POSIX_THREAD_ATTR_STACKSIZE - _SC_THREAD_ATTR_STACKSIZE"
5667 #: build/C/man7/posixoptions.7:515
5670 "I<pthread_attr_getstack>(),\n"
5671 "I<pthread_attr_getstacksize>(),\n"
5672 "I<pthread_attr_setstack>(),\n"
5673 "I<pthread_attr_setstacksize>().\n"
5677 #: build/C/man7/posixoptions.7:518
5679 msgid "TCT - _POSIX_THREAD_CPUTIME - _SC_THREAD_CPUTIME"
5683 #: build/C/man7/posixoptions.7:524
5685 "The clockID CLOCK_THREAD_CPUTIME_ID is supported. This option implies the "
5686 "B<_POSIX_TIMERS> option. Affected functions are"
5690 #: build/C/man7/posixoptions.7:533
5693 "I<pthread_getcpuclockid>(),\n"
5694 "I<clock_getres>(),\n"
5695 "I<clock_gettime>(),\n"
5696 "I<clock_settime>(),\n"
5697 "I<timer_create>().\n"
5701 #: build/C/man7/posixoptions.7:536
5703 msgid "TPI - _POSIX_THREAD_PRIO_INHERIT - _SC_THREAD_PRIO_INHERIT"
5707 #: build/C/man7/posixoptions.7:544
5710 "I<pthread_mutexattr_getprotocol>(),\n"
5711 "I<pthread_mutexattr_setprotocol>().\n"
5715 #: build/C/man7/posixoptions.7:547
5717 msgid "TPP - _POSIX_THREAD_PRIO_PROTECT - _SC_THREAD_PRIO_PROTECT"
5721 #: build/C/man7/posixoptions.7:559
5724 "I<pthread_mutex_getprioceiling>(),\n"
5725 "I<pthread_mutex_setprioceiling>(),\n"
5726 "I<pthread_mutexattr_getprioceiling>(),\n"
5727 "I<pthread_mutexattr_getprotocol>(),\n"
5728 "I<pthread_mutexattr_setprioceiling>(),\n"
5729 "I<pthread_mutexattr_setprotocol>().\n"
5733 #: build/C/man7/posixoptions.7:562
5735 msgid "TPS - _POSIX_THREAD_PRIORITY_SCHEDULING - _SC_THREAD_PRIORITY_SCHEDULING"
5739 #: build/C/man7/posixoptions.7:566
5741 "If this option is in effect, the different threads inside a process can run "
5742 "with different priorities and/or different schedulers. Affected functions "
5747 #: build/C/man7/posixoptions.7:579
5750 "I<pthread_attr_getinheritsched>(),\n"
5751 "I<pthread_attr_getschedpolicy>(),\n"
5752 "I<pthread_attr_getscope>(),\n"
5753 "I<pthread_attr_setinheritsched>(),\n"
5754 "I<pthread_attr_setschedpolicy>(),\n"
5755 "I<pthread_attr_setscope>(),\n"
5756 "I<pthread_getschedparam>(),\n"
5757 "I<pthread_setschedparam>(),\n"
5758 "I<pthread_setschedprio>().\n"
5762 #: build/C/man7/posixoptions.7:582
5764 msgid "TSH - _POSIX_THREAD_PROCESS_SHARED - _SC_THREAD_PROCESS_SHARED"
5768 #: build/C/man7/posixoptions.7:596
5771 "I<pthread_barrierattr_getpshared>(),\n"
5772 "I<pthread_barrierattr_setpshared>(),\n"
5773 "I<pthread_condattr_getpshared>(),\n"
5774 "I<pthread_condattr_setpshared>(),\n"
5775 "I<pthread_mutexattr_getpshared>(),\n"
5776 "I<pthread_mutexattr_setpshared>(),\n"
5777 "I<pthread_rwlockattr_getpshared>(),\n"
5778 "I<pthread_rwlockattr_setpshared>().\n"
5782 #: build/C/man7/posixoptions.7:599
5784 msgid "TSF - _POSIX_THREAD_SAFE_FUNCTIONS - _SC_THREAD_SAFE_FUNCTIONS"
5788 #: build/C/man7/posixoptions.7:624
5792 "I<getgrgid_r>(),\n"
5793 "I<getgrnam_r>(),\n"
5794 "I<getpwnam_r>(),\n"
5795 "I<getpwuid_r>(),\n"
5797 "I<ftrylockfile>(),\n"
5798 "I<funlockfile>(),\n"
5799 "I<getc_unlocked>(),\n"
5800 "I<getchar_unlocked>(),\n"
5801 "I<putc_unlocked>(),\n"
5802 "I<putchar_unlocked>(),\n"
5804 "I<strerror_r>(),\n"
5809 "I<localtime_r>().\n"
5813 #: build/C/man7/posixoptions.7:627
5815 msgid "TSP - _POSIX_THREAD_SPORADIC_SERVER - _SC_THREAD_SPORADIC_SERVER"
5819 #: build/C/man7/posixoptions.7:632
5821 "This option implies the B<_POSIX_THREAD_PRIORITY_SCHEDULING> option. "
5822 "Affected functions are"
5826 #: build/C/man7/posixoptions.7:639
5829 "I<sched_getparam>(),\n"
5830 "I<sched_setparam>(),\n"
5831 "I<sched_setscheduler>().\n"
5835 #: build/C/man7/posixoptions.7:642
5837 msgid "THR - _POSIX_THREADS - _SC_THREADS"
5841 #: build/C/man7/posixoptions.7:645
5843 "Basic support for POSIX threads is available. The following functions are "
5848 #: build/C/man7/posixoptions.7:697
5851 "I<pthread_atfork>(),\n"
5852 "I<pthread_attr_destroy>(),\n"
5853 "I<pthread_attr_getdetachstate>(),\n"
5854 "I<pthread_attr_getschedparam>(),\n"
5855 "I<pthread_attr_init>(),\n"
5856 "I<pthread_attr_setdetachstate>(),\n"
5857 "I<pthread_attr_setschedparam>(),\n"
5858 "I<pthread_cancel>(),\n"
5859 "I<pthread_cleanup_push>(),\n"
5860 "I<pthread_cleanup_pop>(),\n"
5861 "I<pthread_cond_broadcast>(),\n"
5862 "I<pthread_cond_destroy>(),\n"
5863 "I<pthread_cond_init>(),\n"
5864 "I<pthread_cond_signal>(),\n"
5865 "I<pthread_cond_timedwait>(),\n"
5866 "I<pthread_cond_wait>(),\n"
5867 "I<pthread_condattr_destroy>(),\n"
5868 "I<pthread_condattr_init>(),\n"
5869 "I<pthread_create>(),\n"
5870 "I<pthread_detach>(),\n"
5871 "I<pthread_equal>(),\n"
5872 "I<pthread_exit>(),\n"
5873 "I<pthread_getspecific>(),\n"
5874 "I<pthread_join>(),\n"
5875 "I<pthread_key_create>(),\n"
5876 "I<pthread_key_delete>(),\n"
5877 "I<pthread_mutex_destroy>(),\n"
5878 "I<pthread_mutex_init>(),\n"
5879 "I<pthread_mutex_lock>(),\n"
5880 "I<pthread_mutex_trylock>(),\n"
5881 "I<pthread_mutex_unlock>(),\n"
5882 "I<pthread_mutexattr_destroy>(),\n"
5883 "I<pthread_mutexattr_init>(),\n"
5884 "I<pthread_once>(),\n"
5885 "I<pthread_rwlock_destroy>(),\n"
5886 "I<pthread_rwlock_init>(),\n"
5887 "I<pthread_rwlock_rdlock>(),\n"
5888 "I<pthread_rwlock_tryrdlock>(),\n"
5889 "I<pthread_rwlock_trywrlock>(),\n"
5890 "I<pthread_rwlock_unlock>(),\n"
5891 "I<pthread_rwlock_wrlock>(),\n"
5892 "I<pthread_rwlockattr_destroy>(),\n"
5893 "I<pthread_rwlockattr_init>(),\n"
5894 "I<pthread_self>(),\n"
5895 "I<pthread_setcancelstate>(),\n"
5896 "I<pthread_setcanceltype>(),\n"
5897 "I<pthread_setspecific>(),\n"
5898 "I<pthread_testcancel>().\n"
5902 #: build/C/man7/posixoptions.7:700
5904 msgid "TMO - _POSIX_TIMEOUTS - _SC_TIMEOUTS"
5908 #: build/C/man7/posixoptions.7:713
5911 "I<mq_timedreceive>(),\n"
5912 "I<mq_timedsend>(),\n"
5913 "I<pthread_mutex_timedlock>(),\n"
5914 "I<pthread_rwlock_timedrdlock>(),\n"
5915 "I<pthread_rwlock_timedwrlock>(),\n"
5916 "I<sem_timedwait>(),\n"
5917 "I<posix_trace_timedgetnext_event>().\n"
5921 #: build/C/man7/posixoptions.7:716
5923 msgid "TMR - _POSIX_TIMERS - _SC_TIMERS"
5927 #: build/C/man7/posixoptions.7:731
5930 "I<clock_getres>(),\n"
5931 "I<clock_gettime>(),\n"
5932 "I<clock_settime>(),\n"
5934 "I<timer_create>(),\n"
5935 "I<timer_delete>(),\n"
5936 "I<timer_gettime>(),\n"
5937 "I<timer_getoverrun>(),\n"
5938 "I<timer_settime>().\n"
5942 #: build/C/man7/posixoptions.7:734
5944 msgid "TRC - _POSIX_TRACE - _SC_TRACE"
5948 #: build/C/man7/posixoptions.7:737
5949 msgid "POSIX tracing is available. The following functions are present:"
5953 #: build/C/man7/posixoptions.7:772
5956 "I<posix_trace_attr_destroy>(),\n"
5957 "I<posix_trace_attr_getclockres>(),\n"
5958 "I<posix_trace_attr_getcreatetime>(),\n"
5959 "I<posix_trace_attr_getgenversion>(),\n"
5960 "I<posix_trace_attr_getmaxdatasize>(),\n"
5961 "I<posix_trace_attr_getmaxsystemeventsize>(),\n"
5962 "I<posix_trace_attr_getmaxusereventsize>(),\n"
5963 "I<posix_trace_attr_getname>(),\n"
5964 "I<posix_trace_attr_getstreamfullpolicy>(),\n"
5965 "I<posix_trace_attr_getstreamsize>(),\n"
5966 "I<posix_trace_attr_init>(),\n"
5967 "I<posix_trace_attr_setmaxdatasize>(),\n"
5968 "I<posix_trace_attr_setname>(),\n"
5969 "I<posix_trace_attr_setstreamsize>(),\n"
5970 "I<posix_trace_attr_setstreamfullpolicy>(),\n"
5971 "I<posix_trace_clear>(),\n"
5972 "I<posix_trace_create>(),\n"
5973 "I<posix_trace_event>(),\n"
5974 "I<posix_trace_eventid_equal>(),\n"
5975 "I<posix_trace_eventid_get_name>(),\n"
5976 "I<posix_trace_eventid_open>(),\n"
5977 "I<posix_trace_eventtypelist_getnext_id>(),\n"
5978 "I<posix_trace_eventtypelist_rewind>(),\n"
5979 "I<posix_trace_flush>(),\n"
5980 "I<posix_trace_get_attr>(),\n"
5981 "I<posix_trace_get_status>(),\n"
5982 "I<posix_trace_getnext_event>(),\n"
5983 "I<posix_trace_shutdown>(),\n"
5984 "I<posix_trace_start>(),\n"
5985 "I<posix_trace_stop>(),\n"
5986 "I<posix_trace_trygetnext_event>().\n"
5990 #: build/C/man7/posixoptions.7:775
5992 msgid "TEF - _POSIX_TRACE_EVENT_FILTER - _SC_TRACE_EVENT_FILTER"
5996 #: build/C/man7/posixoptions.7:780 build/C/man7/posixoptions.7:815
5998 "This option implies the B<_POSIX_TRACE> option. The following functions are "
6003 #: build/C/man7/posixoptions.7:792
6006 "I<posix_trace_eventset_add>(),\n"
6007 "I<posix_trace_eventset_del>(),\n"
6008 "I<posix_trace_eventset_empty>(),\n"
6009 "I<posix_trace_eventset_fill>(),\n"
6010 "I<posix_trace_eventset_ismember>(),\n"
6011 "I<posix_trace_get_filter>(),\n"
6012 "I<posix_trace_set_filter>(),\n"
6013 "I<posix_trace_trid_eventid_open>().\n"
6017 #: build/C/man7/posixoptions.7:795
6019 msgid "TRI - _POSIX_TRACE_INHERIT - _SC_TRACE_INHERIT"
6023 #: build/C/man7/posixoptions.7:801
6025 "Tracing children of the traced process is supported. This option implies "
6026 "the B<_POSIX_TRACE> option. The following functions are present:"
6030 #: build/C/man7/posixoptions.7:807
6033 "I<posix_trace_attr_getinherited>(),\n"
6034 "I<posix_trace_attr_setinherited>().\n"
6038 #: build/C/man7/posixoptions.7:810
6040 msgid "TRL - _POSIX_TRACE_LOG - _SC_TRACE_LOG"
6044 #: build/C/man7/posixoptions.7:827
6047 "I<posix_trace_attr_getlogfullpolicy>(),\n"
6048 "I<posix_trace_attr_getlogsize>(),\n"
6049 "I<posix_trace_attr_setlogfullpolicy>(),\n"
6050 "I<posix_trace_attr_setlogsize>(),\n"
6051 "I<posix_trace_close>(),\n"
6052 "I<posix_trace_create_withlog>(),\n"
6053 "I<posix_trace_open>(),\n"
6054 "I<posix_trace_rewind>().\n"
6058 #: build/C/man7/posixoptions.7:830
6060 msgid "TYM - _POSIX_TYPED_MEMORY_OBJECTS - _SC_TYPED_MEMORY_OBJECT"
6064 #: build/C/man7/posixoptions.7:839
6067 "I<posix_mem_offset>(),\n"
6068 "I<posix_typed_mem_get_info>(),\n"
6069 "I<posix_typed_mem_open>().\n"
6073 #: build/C/man7/posixoptions.7:842
6075 msgid "--- - _POSIX_VDISABLE"
6079 #: build/C/man7/posixoptions.7:846
6081 "Always present (probably 0). Value to set a changeable special control "
6082 "character to indicate that it is disabled."
6086 #: build/C/man7/posixoptions.7:846
6088 msgid "XOPEN EXTENSIONS"
6093 #: build/C/man7/posixoptions.7:853
6095 "B<_XOPEN_CRYPT>, B<_XOPEN_LEGACY>, B<_XOPEN_REALTIME>, "
6096 "B<_XOPEN_REALTIME_THREADS>, B<_XOPEN_UNIX>."
6100 #: build/C/man7/posixoptions.7:856
6101 msgid "B<sysconf>(3), B<standards>(7)"
6105 #: build/C/man5/proc.5:61
6111 #: build/C/man5/proc.5:61
6117 #: build/C/man5/proc.5:64
6118 msgid "proc - process information pseudo-file system"
6122 #: build/C/man5/proc.5:73
6124 "The I<proc> file system is a pseudo-file system which is used as an "
6125 "interface to kernel data structures. It is commonly mounted at I</proc>. "
6126 "Most of it is read-only, but some files allow kernel variables to be "
6131 #: build/C/man5/proc.5:77
6132 msgid "The following outline gives a quick tour through the I</proc> hierarchy."
6136 #: build/C/man5/proc.5:78
6138 msgid "I</proc/[pid]>"
6141 #. FIXME Describe /proc/[pid]/attr and
6142 #. /proc/[pid]/task/[tid]/attr
6143 #. This is a directory
6147 #: build/C/man5/proc.5:90
6149 "There is a numerical subdirectory for each running process; the subdirectory "
6150 "is named by the process ID. Each such subdirectory contains the following "
6151 "pseudo-files and directories."
6155 #: build/C/man5/proc.5:90
6157 msgid "I</proc/[pid]/auxv> (since 2.6.0-test7)"
6161 #: build/C/man5/proc.5:97
6163 "This contains the contents of the ELF interpreter information passed to the "
6164 "process at exec time. The format is one I<unsigned long> ID plus one "
6165 "I<unsigned long> value for each entry. The last entry contains two zeros."
6169 #: build/C/man5/proc.5:97
6171 msgid "I</proc/[pid]/cgroup> (since Linux 2.6.24)"
6174 #. Info in Documentation/cgroups/cgroups.txt
6176 #: build/C/man5/proc.5:103
6178 "This file describes control groups to which the process/task belongs. For "
6179 "each cgroup hierarchy there is one entry containing colon-separated fields "
6184 #: build/C/man5/proc.5:107
6186 msgid "CW< 5:cpuacct,cpu,cpuset:/daemons>\n"
6190 #: build/C/man5/proc.5:111
6191 msgid "The colon-separated fields are, from left to right:"
6195 #: build/C/man5/proc.5:112
6201 #: build/C/man5/proc.5:114
6202 msgid "hierarchy ID number"
6206 #: build/C/man5/proc.5:114
6212 #: build/C/man5/proc.5:116
6213 msgid "set of subsystems bound to the hierarchy"
6217 #: build/C/man5/proc.5:116
6223 #: build/C/man5/proc.5:118
6224 msgid "control group in the hierarchy to which the process belongs"
6228 #. FIXME Describe /proc/[pid]/clear_refs
6230 #. "Clears page referenced bits shown in smaps output"
6232 #. CONFIG_PROC_PAGE_MONITOR
6234 #: build/C/man5/proc.5:129
6236 "This file is only present if the B<CONFIG_CGROUPS> kernel configuration "
6237 "option is enabled."
6241 #: build/C/man5/proc.5:129
6243 msgid "I</proc/[pid]/cmdline>"
6246 #. In 2.3.26, this also used to be true if the process was swapped out.
6248 #: build/C/man5/proc.5:139
6250 "This holds the complete command line for the process, unless the process is "
6251 "a zombie. In the latter case, there is nothing in this file: that is, a "
6252 "read on this file will return 0 characters. The command-line arguments "
6253 "appear in this file as a set of strings separated by null bytes "
6254 "(\\(aq\\e0\\(aq), with a further null byte after the last string."
6258 #: build/C/man5/proc.5:139
6260 msgid "I</proc/[pid]/coredump_filter> (since kernel 2.6.23)"
6264 #: build/C/man5/proc.5:143 build/C/man5/proc.5:2122 build/C/man5/proc.5:2126
6265 msgid "See B<core>(5)."
6269 #: build/C/man5/proc.5:143
6271 msgid "I</proc/[pid]/cpuset> (since kernel 2.6.12)"
6274 #. and/proc/[pid]/task/[tid]/cpuset
6276 #: build/C/man5/proc.5:148
6277 msgid "See B<cpuset>(7)."
6281 #: build/C/man5/proc.5:148
6283 msgid "I</proc/[pid]/cwd>"
6287 #: build/C/man5/proc.5:153
6289 "This is a symbolic link to the current working directory of the process. To "
6290 "find out the current working directory of process 20, for instance, you can "
6295 #: build/C/man5/proc.5:157
6297 msgid "$B< cd /proc/20/cwd; /bin/pwd>\n"
6301 #: build/C/man5/proc.5:168
6303 "Note that the I<pwd> command is often a shell built-in, and might not work "
6304 "properly. In B<bash>(1), you may use I<pwd\\ -P>."
6307 #. The following was still true as at kernel 2.6.13
6308 #. FIXME Describe /proc/[pid]/seccomp
6310 #. FIXME Describe /proc/[pid]/sessionid
6311 #. Added in 2.6.25; read-only; only readable by real UID
6312 #. CONFIG_AUDITSYSCALL
6313 #. FIXME Describe /proc/[pid]/sched
6315 #. CONFIG_SCHED_DEBUG, and additional fields if CONFIG_SCHEDSTATS
6316 #. Displays various scheduling parameters
6317 #. This file can be written, to reset stats
6318 #. FIXME Describe /proc/[pid]/schedstats and
6319 #. /proc/[pid]/task/[tid]/schedstats
6321 #. CONFIG_SCHEDSTATS
6323 #: build/C/man5/proc.5:174 build/C/man5/proc.5:647
6325 "In a multithreaded process, the contents of this symbolic link are not "
6326 "available if the main thread has already terminated (typically by calling "
6327 "B<pthread_exit>(3))."
6331 #: build/C/man5/proc.5:174
6333 msgid "I</proc/[pid]/environ>"
6337 #: build/C/man5/proc.5:180
6339 "This file contains the environment for the process. The entries are "
6340 "separated by null bytes (\\(aq\\e0\\(aq), and there may be a null byte at "
6341 "the end. Thus, to print out the environment of process 1, you would do:"
6345 #: build/C/man5/proc.5:185
6347 msgid "$B< (cat /proc/1/environ; echo) | tr \\(aq\\e000\\(aq \\(aq\\en\\(aq>\n"
6351 #: build/C/man5/proc.5:188
6353 msgid "I</proc/[pid]/exe>"
6356 #. The following was still true as at kernel 2.6.13
6358 #: build/C/man5/proc.5:203
6360 "Under Linux 2.2 and later, this file is a symbolic link containing the "
6361 "actual pathname of the executed command. This symbolic link can be "
6362 "dereferenced normally; attempting to open it will open the executable. You "
6363 "can even type I</proc/[pid]/exe> to run another copy of the same executable "
6364 "as is being run by process [pid]. In a multithreaded process, the contents "
6365 "of this symbolic link are not available if the main thread has already "
6366 "terminated (typically by calling B<pthread_exit>(3))."
6370 #: build/C/man5/proc.5:211
6372 "Under Linux 2.0 and earlier I</proc/[pid]/exe> is a pointer to the binary "
6373 "which was executed, and appears as a symbolic link. A B<readlink>(2) call "
6374 "on this file under Linux 2.0 returns a string in the format:"
6378 #: build/C/man5/proc.5:213
6380 msgid " [device]:inode\n"
6384 #: build/C/man5/proc.5:216
6386 "For example, [0301]:1502 would be inode 1502 on device major 03 (IDE, MFM, "
6387 "etc. drives) minor 01 (first partition on the first drive)."
6391 #: build/C/man5/proc.5:221
6392 msgid "B<find>(1) with the I<-inum> option can be used to locate the file."
6396 #: build/C/man5/proc.5:221
6398 msgid "I</proc/[pid]/fd>"
6402 #: build/C/man5/proc.5:227
6404 "This is a subdirectory containing one entry for each file which the process "
6405 "has open, named by its file descriptor, and which is a symbolic link to the "
6406 "actual file. Thus, 0 is standard input, 1 standard output, 2 standard "
6410 #. The following was still true as at kernel 2.6.13
6412 #: build/C/man5/proc.5:233
6414 "In a multithreaded process, the contents of this directory are not available "
6415 "if the main thread has already terminated (typically by calling "
6416 "B<pthread_exit>(3))."
6420 #: build/C/man5/proc.5:246
6422 "Programs that will take a filename as a command-line argument, but will not "
6423 "take input from standard input if no argument is supplied, or that write to "
6424 "a file named as a command-line argument, but will not send their output to "
6425 "standard output if no argument is supplied, can nevertheless be made to use "
6426 "standard input or standard out using I</proc/[pid]/fd>. For example, "
6427 "assuming that I<-i> is the flag designating an input file and I<-o> is the "
6428 "flag designating an output file:"
6432 #: build/C/man5/proc.5:250
6434 msgid "$B< foobar -i /proc/self/fd/0 -o /proc/self/fd/1 ...>\n"
6437 #. The following is not true in my tests (MTK):
6438 #. Note that this will not work for
6439 #. programs that seek on their files, as the files in the fd directory
6440 #. are not seekable.
6442 #: build/C/man5/proc.5:258
6443 msgid "and you have a working filter."
6447 #: build/C/man5/proc.5:268
6449 "I</proc/self/fd/N> is approximately the same as I</dev/fd/N> in some UNIX "
6450 "and UNIX-like systems. Most Linux MAKEDEV scripts symbolically link "
6451 "I</dev/fd> to I</proc/self/fd>, in fact."
6455 #: build/C/man5/proc.5:282
6457 "Most systems provide symbolic links I</dev/stdin>, I</dev/stdout>, and "
6458 "I</dev/stderr>, which respectively link to the files I<0>, I<1>, and I<2> in "
6459 "I</proc/self/fd>. Thus the example command above could be written as:"
6463 #: build/C/man5/proc.5:286
6465 msgid "$B< foobar -i /dev/stdin -o /dev/stdout ...>\n"
6469 #: build/C/man5/proc.5:291
6471 msgid "I</proc/[pid]/fdinfo/> (since kernel 2.6.22)"
6475 #: build/C/man5/proc.5:297
6477 "This is a subdirectory containing one entry for each file which the process "
6478 "has open, named by its file descriptor. The contents of each file can be "
6479 "read to obtain information about the corresponding file descriptor, for "
6484 #: build/C/man5/proc.5:303
6487 "$B< cat /proc/12015/fdinfo/4>\n"
6493 #: build/C/man5/proc.5:314
6495 "The I<pos> field is a decimal number showing the current file offset. The "
6496 "I<flags> field is an octal number that displays the file access mode and "
6497 "file status flags (see B<open>(2))."
6500 #. FIXME document /proc/[pid]/io
6502 #. .IR /proc/[pid]/io " (since kernel 2.6.20)"
6504 #: build/C/man5/proc.5:319
6505 msgid "The files in this directory are readable only by the owner of the process."
6509 #: build/C/man5/proc.5:319
6511 msgid "I</proc/[pid]/limits> (since kernel 2.6.24)"
6515 #: build/C/man5/proc.5:325
6517 "This file displays the soft limit, hard limit, and units of measurement for "
6518 "each of the process's resource limits (see B<getrlimit>(2)). The file is "
6519 "protected to only allow reading by the real UID of the process."
6523 #: build/C/man5/proc.5:325
6525 msgid "I</proc/[pid]/maps>"
6529 #: build/C/man5/proc.5:329
6531 "A file containing the currently mapped memory regions and their access "
6536 #: build/C/man5/proc.5:331
6537 msgid "The format is:"
6541 #: build/C/man5/proc.5:344
6544 "CW<address perms offset dev inode pathname\n"
6545 "08048000-08056000 r-xp 00000000 03:0c 64593 /usr/sbin/gpm\n"
6546 "08056000-08058000 rw-p 0000d000 03:0c 64593 /usr/sbin/gpm\n"
6547 "08058000-0805b000 rwxp 00000000 00:00 0\n"
6548 "40000000-40013000 r-xp 00000000 03:0c 4165 /lib/ld-2.2.4.so\n"
6549 "40013000-40015000 rw-p 00012000 03:0c 4165 /lib/ld-2.2.4.so\n"
6550 "4001f000-40135000 r-xp 00000000 03:0c 45494 /lib/libc-2.2.4.so\n"
6551 "40135000-4013e000 rw-p 00115000 03:0c 45494 /lib/libc-2.2.4.so\n"
6552 "4013e000-40142000 rw-p 00000000 00:00 0\n"
6553 "bffff000-c0000000 rwxp 00000000 00:00 0>\n"
6557 #: build/C/man5/proc.5:349
6559 "where \"address\" is the address space in the process that it occupies, "
6560 "\"perms\" is a set of permissions:"
6564 #: build/C/man5/proc.5:357
6571 "p = private (copy on write)\n"
6575 #: build/C/man5/proc.5:364
6577 "\"offset\" is the offset into the file/whatever, \"dev\" is the device "
6578 "(major:minor), and \"inode\" is the inode on that device. 0 indicates that "
6579 "no inode is associated with the memory region, as the case would be with BSS "
6580 "(uninitialized data)."
6584 #: build/C/man5/proc.5:366
6585 msgid "Under Linux 2.0 there is no field giving pathname."
6589 #: build/C/man5/proc.5:366
6591 msgid "I</proc/[pid]/mem>"
6595 #: build/C/man5/proc.5:373
6597 "This file can be used to access the pages of a process's memory through "
6598 "B<open>(2), B<read>(2), and B<lseek>(2)."
6602 #: build/C/man5/proc.5:373
6604 msgid "I</proc/[pid]/mountinfo> (since Linux 2.6.26)"
6607 #. This info adapted from Documentation/filesystems/proc.txt
6609 #: build/C/man5/proc.5:378
6611 "This file contains information about mount points. It contains lines of the "
6616 #: build/C/man5/proc.5:383
6619 "CW<36 35 98:0 /mnt1 /mnt2 rw,noatime master:1 - ext3 /dev/root "
6620 "rw,errors=continue\n"
6621 "(1)(2)(3) (4) (5) (6) (7) (8) (9) (10) (11)>\n"
6625 #: build/C/man5/proc.5:387
6626 msgid "The numbers in parentheses are labels for the descriptions below:"
6630 #: build/C/man5/proc.5:388 build/C/man5/proc.5:481
6636 #: build/C/man5/proc.5:392
6637 msgid "mount ID: unique identifier of the mount (may be reused after B<umount>(2))."
6641 #: build/C/man5/proc.5:392 build/C/man5/proc.5:485
6647 #: build/C/man5/proc.5:395
6648 msgid "parent ID: ID of parent mount (or of self for the top of the mount tree)."
6652 #: build/C/man5/proc.5:395 build/C/man5/proc.5:488
6658 #: build/C/man5/proc.5:401
6659 msgid "major:minor: value of I<st_dev> for files on file system (see B<stat>(2))."
6663 #: build/C/man5/proc.5:401 build/C/man5/proc.5:491
6669 #: build/C/man5/proc.5:404
6670 msgid "root: root of the mount within the file system."
6674 #: build/C/man5/proc.5:404
6680 #: build/C/man5/proc.5:407
6681 msgid "mount point: mount point relative to the process's root."
6685 #: build/C/man5/proc.5:407
6691 #: build/C/man5/proc.5:410
6692 msgid "mount options: per-mount options."
6696 #: build/C/man5/proc.5:410
6702 #: build/C/man5/proc.5:413
6703 msgid "optional fields: zero or more fields of the form \"tag[:value]\"."
6707 #: build/C/man5/proc.5:413
6713 #: build/C/man5/proc.5:416
6714 msgid "separator: marks the end of the optional fields."
6718 #: build/C/man5/proc.5:416
6724 #: build/C/man5/proc.5:419
6725 msgid "file system type: name of file system in the form \"type[.subtype]\"."
6729 #: build/C/man5/proc.5:419
6735 #: build/C/man5/proc.5:422
6736 msgid "mount source: file system-specific information or \"none\"."
6740 #: build/C/man5/proc.5:422
6746 #: build/C/man5/proc.5:425
6747 msgid "super options: per-super block options."
6751 #: build/C/man5/proc.5:429
6753 "Parsers should ignore all unrecognized optional fields. Currently the "
6754 "possible optional fields are:"
6758 #: build/C/man5/proc.5:430
6764 #: build/C/man5/proc.5:433
6765 msgid "mount is shared in peer group X"
6769 #: build/C/man5/proc.5:433
6775 #: build/C/man5/proc.5:436
6776 msgid "mount is slave to peer group X"
6780 #: build/C/man5/proc.5:436
6782 msgid "propagate_from:X"
6786 #: build/C/man5/proc.5:439
6787 msgid "mount is slave and receives propagation from peer group X (*)"
6791 #: build/C/man5/proc.5:439
6797 #: build/C/man5/proc.5:442
6798 msgid "mount is unbindable"
6802 #: build/C/man5/proc.5:449
6804 "(*) X is the closest dominant peer group under the process's root. If X is "
6805 "the immediate master of the mount, or if there is no dominant peer group "
6806 "under the same root, then only the \"master:X\" field is present and not the "
6807 "\"propagate_from:X\" field."
6811 #: build/C/man5/proc.5:453
6813 "For more information on mount propagation see: "
6814 "I<Documentation/filesystems/sharedsubtree.txt> in the kernel source tree."
6818 #: build/C/man5/proc.5:453
6820 msgid "I</proc/[pid]/mounts> (since Linux 2.4.19)"
6824 #: build/C/man5/proc.5:468
6826 "This is a list of all the file systems currently mounted in the process's "
6827 "mount namespace. The format of this file is documented in B<fstab>(5). "
6828 "Since kernel version 2.6.15, this file is pollable: after opening the file "
6829 "for reading, a change in this file (i.e., a file system mount or unmount) "
6830 "causes B<select>(2) to mark the file descriptor as readable, and B<poll>(2) "
6831 "and B<epoll_wait>(2) mark the file as having an error condition."
6835 #: build/C/man5/proc.5:468
6837 msgid "I</proc/[pid]/mountstats> (since Linux 2.6.17)"
6841 #: build/C/man5/proc.5:473
6843 "This file exports information (statistics, configuration information) about "
6844 "the mount points in the process's name space. Lines in this file have the "
6849 #: build/C/man5/proc.5:477
6852 "device /dev/sda7 mounted on /home with fstype ext3 [statistics]\n"
6853 "( 1 ) ( 2 ) (3 ) (4)\n"
6857 #: build/C/man5/proc.5:480
6858 msgid "The fields in each line are:"
6862 #: build/C/man5/proc.5:485
6864 "The name of the mounted device (or \"nodevice\" if there is no corresponding "
6869 #: build/C/man5/proc.5:488
6870 msgid "The mount point within the file system tree."
6874 #: build/C/man5/proc.5:491
6875 msgid "The file system type."
6879 #: build/C/man5/proc.5:496
6881 "Optional statistics and configuration information. Currently (as at Linux "
6882 "2.6.26), only NFS file systems export information via this field."
6886 #: build/C/man5/proc.5:499
6887 msgid "This file is only readable by the owner of the process."
6891 #: build/C/man5/proc.5:499
6893 msgid "I</proc/[pid]/ns/> (since Linux 3.0)"
6896 #. See commit 6b4e306aa3dc94a0545eb9279475b1ab6209a31f
6898 #: build/C/man5/proc.5:507
6900 "This is a subdirectory containing one entry for each namespace that supports "
6901 "being manipulated by B<setns>(2). For information about namespaces, see "
6906 #: build/C/man5/proc.5:507
6908 msgid "I</proc/[pid]/ns/ipc> (since Linux 3.0)"
6912 #: build/C/man5/proc.5:515
6914 "Bind mounting this file (see B<mount>(2)) to somewhere else in the "
6915 "filesystem keeps the IPC namespace of the process specified by I<pid> alive "
6916 "even if all processes currently in the namespace terminate."
6920 #: build/C/man5/proc.5:524
6922 "Opening this file returns a file handle for the IPC namespace of the process "
6923 "specified by I<pid>. As long as this file descriptor remains open, the IPC "
6924 "namespace will remain alive, even if all processes in the namespace "
6925 "terminate. The file descriptor can be passed to B<setns>(2)."
6929 #: build/C/man5/proc.5:524
6931 msgid "I</proc/[pid]/ns/net> (since Linux 3.0)"
6935 #: build/C/man5/proc.5:532
6937 "Bind mounting this file (see B<mount>(2)) to somewhere else in the "
6938 "filesystem keeps the network namespace of the process specified by I<pid> "
6939 "alive even if all processes in the namespace terminate."
6943 #: build/C/man5/proc.5:541
6945 "Opening this file returns a file handle for the network namespace of the "
6946 "process specified by I<pid>. As long as this file descriptor remains open, "
6947 "the network namespace will remain alive, even if all processes in the "
6948 "namespace terminate. The file descriptor can be passed to B<setns>(2)."
6952 #: build/C/man5/proc.5:541
6954 msgid "I</proc/[pid]/ns/uts> (since Linux 3.0)"
6958 #: build/C/man5/proc.5:549
6960 "Bind mounting this file (see B<mount>(2)) to somewhere else in the "
6961 "filesystem keeps the UTS namespace of the process specified by I<pid> alive "
6962 "even if all processes currently in the namespace terminate."
6966 #: build/C/man5/proc.5:558
6968 "Opening this file returns a file handle for the UTS namespace of the process "
6969 "specified by I<pid>. As long as this file descriptor remains open, the UTS "
6970 "namespace will remain alive, even if all processes in the namespace "
6971 "terminate. The file descriptor can be passed to B<setns>(2)."
6975 #: build/C/man5/proc.5:558
6977 msgid "I</proc/[pid]/numa_maps> (since Linux 2.6.14)"
6981 #: build/C/man5/proc.5:562
6982 msgid "See B<numa>(7)."
6986 #: build/C/man5/proc.5:562
6988 msgid "I</proc/[pid]/oom_adj> (since Linux 2.6.11)"
6992 #: build/C/man5/proc.5:582
6994 "This file can be used to adjust the score used to select which process "
6995 "should be killed in an out-of-memory (OOM) situation. The kernel uses this "
6996 "value for a bit-shift operation of the process's I<oom_score> value: valid "
6997 "values are in the range -16 to +15, plus the special value -17, which "
6998 "disables OOM-killing altogether for this process. A positive score "
6999 "increases the likelihood of this process being killed by the OOM-killer; a "
7000 "negative score decreases the likelihood. The default value for this file is "
7001 "0; a new process inherits its parent's I<oom_adj> setting. A process must "
7002 "be privileged (B<CAP_SYS_RESOURCE>) to update this file."
7006 #: build/C/man5/proc.5:582
7008 msgid "I</proc/[pid]/oom_score> (since Linux 2.6.11)"
7011 #. See mm/oom_kill.c::badness() in the 2.6.25 sources
7012 #. See mm/oom_kill.c::badness() in the 2.6.25 sources
7014 #: build/C/man5/proc.5:593
7016 "This file displays the current score that the kernel gives to this process "
7017 "for the purpose of selecting a process for the OOM-killer. A higher score "
7018 "means that the process is more likely to be selected by the OOM-killer. The "
7019 "basis for this score is the amount of memory used by the process, with "
7020 "increases (+) or decreases (-) for factors including:"
7024 #: build/C/man5/proc.5:598
7025 msgid "whether the process creates a lot of children using B<fork>(2) (+);"
7029 #: build/C/man5/proc.5:601
7031 "whether the process has been running a long time, or has used a lot of CPU "
7036 #: build/C/man5/proc.5:603
7037 msgid "whether the process has a low nice value (i.e., E<gt> 0) (+);"
7040 #. More precisely, if it has CAP_SYS_ADMIN or CAP_SYS_RESOURCE
7042 #: build/C/man5/proc.5:606
7043 msgid "whether the process is privileged (-); and"
7046 #. More precisely, if it has CAP_SYS_RAWIO
7048 #: build/C/man5/proc.5:609
7049 msgid "whether the process is making direct hardware access (-)."
7052 #. FIXME Describe /proc/[pid]/pagemap
7054 #. CONFIG_PROC_PAGE_MONITOR
7056 #: build/C/man5/proc.5:619
7058 "The I<oom_score> also reflects the bit-shift adjustment specified by the "
7059 "I<oom_adj> setting for the process."
7063 #: build/C/man5/proc.5:619
7065 msgid "I</proc/[pid]/root>"
7069 #: build/C/man5/proc.5:627
7071 "UNIX and Linux support the idea of a per-process root of the file system, "
7072 "set by the B<chroot>(2) system call. This file is a symbolic link that "
7073 "points to the process's root directory, and behaves as exe, fd/*, etc. do."
7077 #: build/C/man5/proc.5:647
7079 msgid "I</proc/[pid]/smaps> (since Linux 2.6.14)"
7082 #. CONFIG_PROC_PAGE_MONITOR
7084 #: build/C/man5/proc.5:652
7086 "This file shows memory consumption for each of the process's mappings. For "
7087 "each of mappings there is a series of lines such as the following:"
7091 #: build/C/man5/proc.5:662
7094 "08048000-080bc000 r-xp 00000000 03:02 13130 /bin/bash\n"
7097 "Shared_Clean: 424 kB\n"
7098 "Shared_Dirty: 0 kB\n"
7099 "Private_Clean: 0 kB\n"
7100 "Private_Dirty: 0 kB\n"
7104 #: build/C/man5/proc.5:672
7106 "The first of these lines shows the same information as is displayed for the "
7107 "mapping in I</proc/[pid]/maps>. The remaining lines show the size of the "
7108 "mapping, the amount of the mapping that is currently resident in RAM, the "
7109 "number of clean and dirty shared pages in the mapping, and the number of "
7110 "clean and dirty private pages in the mapping."
7114 #: build/C/man5/proc.5:677
7116 "This file is only present if the B<CONFIG_MMU> kernel configuration option "
7121 #: build/C/man5/proc.5:677
7123 msgid "I</proc/[pid]/stat>"
7127 #: build/C/man5/proc.5:684
7129 "Status information about the process. This is used by B<ps>(1). It is "
7130 "defined in I</usr/src/linux/fs/proc/array.c>."
7134 #: build/C/man5/proc.5:688
7135 msgid "The fields, in order, with their proper B<scanf>(3) format specifiers, are:"
7139 #: build/C/man5/proc.5:689
7145 #: build/C/man5/proc.5:692
7146 msgid "The process ID."
7150 #: build/C/man5/proc.5:692
7156 #: build/C/man5/proc.5:696
7158 "The filename of the executable, in parentheses. This is visible whether or "
7159 "not the executable is swapped out."
7163 #: build/C/man5/proc.5:696
7169 #: build/C/man5/proc.5:702
7171 "One character from the string \"RSDZTW\" where R is running, S is sleeping "
7172 "in an interruptible wait, D is waiting in uninterruptible disk sleep, Z is "
7173 "zombie, T is traced or stopped (on a signal), and W is paging."
7177 #: build/C/man5/proc.5:702
7183 #: build/C/man5/proc.5:705
7184 msgid "The PID of the parent."
7188 #: build/C/man5/proc.5:705
7194 #: build/C/man5/proc.5:708
7195 msgid "The process group ID of the process."
7199 #: build/C/man5/proc.5:708
7201 msgid "I<session> %d"
7205 #: build/C/man5/proc.5:711
7206 msgid "The session ID of the process."
7210 #: build/C/man5/proc.5:711
7212 msgid "I<tty_nr> %d"
7216 #: build/C/man5/proc.5:717
7218 "The controlling terminal of the process. (The minor device number is "
7219 "contained in the combination of bits 31 to 20 and 7 to 0; the major device "
7220 "number is in bits 15 to 8.)"
7224 #: build/C/man5/proc.5:717
7229 #. This field and following, up to and including wchan added 0.99.1
7231 #: build/C/man5/proc.5:722
7233 "The ID of the foreground process group of the controlling terminal of the "
7238 #: build/C/man5/proc.5:722
7240 msgid "I<flags> %u (%lu before Linux 2.6.22)"
7244 #: build/C/man5/proc.5:729
7246 "The kernel flags word of the process. For bit meanings, see the PF_* "
7247 "defines in I<E<lt>linux/sched.hE<gt>>. Details depend on the kernel "
7252 #: build/C/man5/proc.5:729
7254 msgid "I<minflt> %lu"
7258 #: build/C/man5/proc.5:733
7260 "The number of minor faults the process has made which have not required "
7261 "loading a memory page from disk."
7266 #: build/C/man5/proc.5:733
7268 msgid "I<cminflt> %lu"
7272 #: build/C/man5/proc.5:738
7273 msgid "The number of minor faults that the process's waited-for children have made."
7277 #: build/C/man5/proc.5:738
7279 msgid "I<majflt> %lu"
7283 #: build/C/man5/proc.5:742
7285 "The number of major faults the process has made which have required loading "
7286 "a memory page from disk."
7290 #: build/C/man5/proc.5:742
7292 msgid "I<cmajflt> %lu"
7296 #: build/C/man5/proc.5:746
7297 msgid "The number of major faults that the process's waited-for children have made."
7301 #: build/C/man5/proc.5:746
7303 msgid "I<utime> %lu"
7307 #: build/C/man5/proc.5:755
7309 "Amount of time that this process has been scheduled in user mode, measured "
7310 "in clock ticks (divide by I<sysconf(_SC_CLK_TCK)>. This includes guest "
7311 "time, I<guest_time> (time spent running a virtual CPU, see below), so that "
7312 "applications that are not aware of the guest time field do not lose that "
7313 "time from their calculations."
7317 #: build/C/man5/proc.5:755
7319 msgid "I<stime> %lu"
7323 #: build/C/man5/proc.5:760
7325 "Amount of time that this process has been scheduled in kernel mode, measured "
7326 "in clock ticks (divide by I<sysconf(_SC_CLK_TCK)>."
7330 #: build/C/man5/proc.5:760
7332 msgid "I<cutime> %ld"
7336 #: build/C/man5/proc.5:770
7338 "Amount of time that this process's waited-for children have been scheduled "
7339 "in user mode, measured in clock ticks (divide by I<sysconf(_SC_CLK_TCK)>. "
7340 "(See also B<times>(2).) This includes guest time, I<cguest_time> (time "
7341 "spent running a virtual CPU, see below)."
7345 #: build/C/man5/proc.5:770
7347 msgid "I<cstime> %ld"
7351 #: build/C/man5/proc.5:776
7353 "Amount of time that this process's waited-for children have been scheduled "
7354 "in kernel mode, measured in clock ticks (divide by I<sysconf(_SC_CLK_TCK)>."
7358 #: build/C/man5/proc.5:776
7360 msgid "I<priority> %ld"
7364 #: build/C/man5/proc.5:793
7366 "(Explanation for Linux 2.6) For processes running a real-time scheduling "
7367 "policy (I<policy> below; see B<sched_setscheduler>(2)), this is the negated "
7368 "scheduling priority, minus one; that is, a number in the range -2 to -100, "
7369 "corresponding to real-time priorities 1 to 99. For processes running under "
7370 "a non-real-time scheduling policy, this is the raw nice value "
7371 "(B<setpriority>(2)) as represented in the kernel. The kernel stores nice "
7372 "values as numbers in the range 0 (high) to 39 (low), corresponding to the "
7373 "user-visible nice range of -20 to 19."
7376 #. And back in kernel 1.2 days things were different again.
7378 #: build/C/man5/proc.5:797
7380 "Before Linux 2.6, this was a scaled value based on the scheduler weighting "
7381 "given to this process."
7385 #: build/C/man5/proc.5:797
7390 #. Back in kernel 1.2 days things were different.
7392 #: build/C/man5/proc.5:803
7394 "The nice value (see B<setpriority>(2)), a value in the range 19 (low "
7395 "priority) to -20 (high priority)."
7399 #. \fIcounter\fP %ld
7400 #. The current maximum size in jiffies of the process's next timeslice,
7401 #. or what is currently left of its current timeslice, if it is the
7402 #. currently running process.
7405 #. The time in jiffies of the process's next timeout.
7406 #. timeout was removed sometime around 2.1/2.2
7408 #: build/C/man5/proc.5:803
7410 msgid "I<num_threads> %ld"
7414 #: build/C/man5/proc.5:817
7416 "Number of threads in this process (since Linux 2.6). Before kernel 2.6, "
7417 "this field was hard coded to 0 as a placeholder for an earlier removed "
7423 #: build/C/man5/proc.5:817
7425 msgid "I<itrealvalue> %ld"
7429 #: build/C/man5/proc.5:825
7431 "The time in jiffies before the next B<SIGALRM> is sent to the process due to "
7432 "an interval timer. Since kernel 2.6.17, this field is no longer maintained, "
7433 "and is hard coded as 0."
7437 #: build/C/man5/proc.5:825
7439 msgid "I<starttime> %llu (was %lu before Linux 2.6)"
7443 #: build/C/man5/proc.5:828
7444 msgid "The time in jiffies the process started after system boot."
7448 #: build/C/man5/proc.5:828
7450 msgid "I<vsize> %lu"
7454 #: build/C/man5/proc.5:831
7455 msgid "Virtual memory size in bytes."
7459 #: build/C/man5/proc.5:831
7465 #: build/C/man5/proc.5:838
7467 "Resident Set Size: number of pages the process has in real memory. This is "
7468 "just the pages which count toward text, data, or stack space. This does not "
7469 "include pages which have not been demand-loaded in, or which are swapped "
7474 #: build/C/man5/proc.5:838
7476 msgid "I<rsslim> %lu"
7480 #: build/C/man5/proc.5:845
7482 "Current soft limit in bytes on the rss of the process; see the description "
7483 "of B<RLIMIT_RSS> in B<getpriority>(2)."
7487 #: build/C/man5/proc.5:845
7489 msgid "I<startcode> %lu"
7493 #: build/C/man5/proc.5:848
7494 msgid "The address above which program text can run."
7498 #: build/C/man5/proc.5:848
7500 msgid "I<endcode> %lu"
7504 #: build/C/man5/proc.5:851
7505 msgid "The address below which program text can run."
7509 #: build/C/man5/proc.5:851
7511 msgid "I<startstack> %lu"
7515 #: build/C/man5/proc.5:854
7516 msgid "The address of the start (i.e., bottom) of the stack."
7520 #: build/C/man5/proc.5:854
7522 msgid "I<kstkesp> %lu"
7526 #: build/C/man5/proc.5:858
7528 "The current value of ESP (stack pointer), as found in the kernel stack page "
7533 #: build/C/man5/proc.5:858
7535 msgid "I<kstkeip> %lu"
7539 #: build/C/man5/proc.5:861
7540 msgid "The current EIP (instruction pointer)."
7545 #: build/C/man5/proc.5:861
7547 msgid "I<signal> %lu"
7551 #: build/C/man5/proc.5:868
7553 "The bitmap of pending signals, displayed as a decimal number. Obsolete, "
7554 "because it does not provide information on real-time signals; use "
7555 "I</proc/[pid]/status> instead."
7559 #: build/C/man5/proc.5:868
7561 msgid "I<blocked> %lu"
7565 #: build/C/man5/proc.5:874
7567 "The bitmap of blocked signals, displayed as a decimal number. Obsolete, "
7568 "because it does not provide information on real-time signals; use "
7569 "I</proc/[pid]/status> instead."
7573 #: build/C/man5/proc.5:874
7575 msgid "I<sigignore> %lu"
7579 #: build/C/man5/proc.5:880
7581 "The bitmap of ignored signals, displayed as a decimal number. Obsolete, "
7582 "because it does not provide information on real-time signals; use "
7583 "I</proc/[pid]/status> instead."
7587 #: build/C/man5/proc.5:880
7589 msgid "I<sigcatch> %lu"
7593 #: build/C/man5/proc.5:886
7595 "The bitmap of caught signals, displayed as a decimal number. Obsolete, "
7596 "because it does not provide information on real-time signals; use "
7597 "I</proc/[pid]/status> instead."
7601 #: build/C/man5/proc.5:886
7603 msgid "I<wchan> %lu"
7607 #: build/C/man5/proc.5:896
7609 "This is the \"channel\" in which the process is waiting. It is the address "
7610 "of a system call, and can be looked up in a namelist if you need a textual "
7611 "name. (If you have an up-to-date I</etc/psdatabase>, then try I<ps -l> to "
7612 "see the WCHAN field in action.)"
7616 #: build/C/man5/proc.5:896
7618 msgid "I<nswap> %lu"
7621 #. nswap was added in 2.0
7623 #: build/C/man5/proc.5:900
7624 msgid "Number of pages swapped (not maintained)."
7628 #: build/C/man5/proc.5:900
7630 msgid "I<cnswap> %lu"
7633 #. cnswap was added in 2.0
7635 #: build/C/man5/proc.5:904
7636 msgid "Cumulative I<nswap> for child processes (not maintained)."
7640 #: build/C/man5/proc.5:904
7642 msgid "I<exit_signal> %d (since Linux 2.1.22)"
7646 #: build/C/man5/proc.5:907
7647 msgid "Signal to be sent to parent when we die."
7651 #: build/C/man5/proc.5:907
7653 msgid "I<processor> %d (since Linux 2.2.8)"
7657 #: build/C/man5/proc.5:910
7658 msgid "CPU number last executed on."
7662 #: build/C/man5/proc.5:910
7664 msgid "I<rt_priority> %u (since Linux 2.5.19; was %lu before Linux 2.6.22)"
7668 #: build/C/man5/proc.5:916
7670 "Real-time scheduling priority, a number in the range 1 to 99 for processes "
7671 "scheduled under a real-time policy, or 0, for non-real-time processes (see "
7672 "B<sched_setscheduler>(2))."
7677 #: build/C/man5/proc.5:916
7679 msgid "I<policy> %u (since Linux 2.5.19; was %lu before Linux 2.6.22)"
7683 #: build/C/man5/proc.5:923
7685 "Scheduling policy (see B<sched_setscheduler>(2)). Decode using the SCHED_* "
7686 "constants in I<linux/sched.h>."
7690 #: build/C/man5/proc.5:923
7692 msgid "I<delayacct_blkio_ticks> %llu (since Linux 2.6.18)"
7696 #: build/C/man5/proc.5:926
7697 msgid "Aggregated block I/O delays, measured in clock ticks (centiseconds)."
7701 #: build/C/man5/proc.5:926
7703 msgid "I<guest_time> %lu (since Linux 2.6.24)"
7707 #: build/C/man5/proc.5:931
7709 "Guest time of the process (time spent running a virtual CPU for a guest "
7710 "operating system), measured in clock ticks (divide by "
7711 "I<sysconf(_SC_CLK_TCK)>."
7715 #: build/C/man5/proc.5:931
7717 msgid "I<cguest_time> %ld (since Linux 2.6.24)"
7721 #: build/C/man5/proc.5:935
7723 "Guest time of the process's children, measured in clock ticks (divide by "
7724 "I<sysconf(_SC_CLK_TCK)>."
7728 #: build/C/man5/proc.5:936
7730 msgid "I</proc/[pid]/statm>"
7734 #: build/C/man5/proc.5:940
7736 "Provides information about memory usage, measured in pages. The columns "
7740 #. (not including libs; broken, includes data segment)
7741 #. (including libs; broken, includes library text)
7743 #: build/C/man5/proc.5:954
7746 "size total program size\n"
7747 " (same as VmSize in I</proc/[pid]/status>)\n"
7748 "resident resident set size\n"
7749 " (same as VmRSS in I</proc/[pid]/status>)\n"
7750 "share shared pages (from shared mappings)\n"
7751 "text text (code)\n"
7752 "lib library (unused in Linux 2.6)\n"
7753 "data data + stack\n"
7754 "dt dirty pages (unused in Linux 2.6)\n"
7758 #: build/C/man5/proc.5:956
7760 msgid "I</proc/[pid]/status>"
7764 #: build/C/man5/proc.5:964
7766 "Provides much of the information in I</proc/[pid]/stat> and "
7767 "I</proc/[pid]/statm> in a format that's easier for humans to parse. Here's "
7772 #: build/C/man5/proc.5:1005
7775 "$B< cat /proc/$$/status>\n"
7777 "State: S (sleeping)\n"
7782 "Uid: 1000 1000 1000 1000\n"
7783 "Gid: 100 100 100 100\n"
7785 "Groups: 16 33 100\n"
7798 "SigPnd: 0000000000000000\n"
7799 "ShdPnd: 0000000000000000\n"
7800 "SigBlk: 0000000000010000\n"
7801 "SigIgn: 0000000000384004\n"
7802 "SigCgt: 000000004b813efb\n"
7803 "CapInh: 0000000000000000\n"
7804 "CapPrm: 0000000000000000\n"
7805 "CapEff: 0000000000000000\n"
7806 "CapBnd: ffffffffffffffff\n"
7807 "Cpus_allowed: 00000001\n"
7808 "Cpus_allowed_list: 0\n"
7810 "Mems_allowed_list: 0\n"
7811 "voluntary_ctxt_switches: 150\n"
7812 "nonvoluntary_ctxt_switches: 545\n"
7816 #: build/C/man5/proc.5:1009
7817 msgid "The fields are as follows:"
7821 #: build/C/man5/proc.5:1013
7822 msgid "I<Name>: Command run by this process."
7826 #: build/C/man5/proc.5:1025
7828 "I<State>: Current state of the process. One of \"R (running)\", \"S "
7829 "(sleeping)\", \"D (disk sleep)\", \"T (stopped)\", \"T (tracing stop)\", \"Z "
7830 "(zombie)\", or \"X (dead)\"."
7834 #: build/C/man5/proc.5:1028
7835 msgid "I<Tgid>: Thread group ID (i.e., Process ID)."
7839 #: build/C/man5/proc.5:1032
7840 msgid "I<Pid>: Thread ID (see B<gettid>(2))."
7844 #: build/C/man5/proc.5:1035
7845 msgid "I<PPid>: PID of parent process."
7849 #: build/C/man5/proc.5:1038
7850 msgid "I<TracerPid>: PID of process tracing this process (0 if not being traced)."
7854 #: build/C/man5/proc.5:1041
7855 msgid "I<Uid>, I<Gid>: Real, effective, saved set, and file system UIDs (GIDs)."
7859 #: build/C/man5/proc.5:1044
7860 msgid "I<FDSize>: Number of file descriptor slots currently allocated."
7864 #: build/C/man5/proc.5:1047
7865 msgid "I<Groups>: Supplementary group list."
7869 #: build/C/man5/proc.5:1050
7870 msgid "I<VmPeak>: Peak virtual memory size."
7874 #: build/C/man5/proc.5:1053
7875 msgid "I<VmSize>: Virtual memory size."
7879 #: build/C/man5/proc.5:1057
7880 msgid "I<VmLck>: Locked memory size (see B<mlock>(3))."
7884 #: build/C/man5/proc.5:1060
7885 msgid "I<VmHWM>: Peak resident set size (\"high water mark\")."
7889 #: build/C/man5/proc.5:1063
7890 msgid "I<VmRSS>: Resident set size."
7894 #: build/C/man5/proc.5:1066
7895 msgid "I<VmData>, I<VmStk>, I<VmExe>: Size of data, stack, and text segments."
7899 #: build/C/man5/proc.5:1069
7900 msgid "I<VmLib>: Shared library code size."
7904 #: build/C/man5/proc.5:1072
7905 msgid "I<VmPTE>: Page table entries size (since Linux 2.6.10)."
7909 #: build/C/man5/proc.5:1075
7910 msgid "I<Threads>: Number of threads in process containing this thread."
7914 #: build/C/man5/proc.5:1086
7916 "I<SigQ>: This field contains two slash-separated numbers that relate to "
7917 "queued signals for the real user ID of this process. The first of these is "
7918 "the number of currently queued signals for this real user ID, and the second "
7919 "is the resource limit on the number of queued signals for this process (see "
7920 "the description of B<RLIMIT_SIGPENDING> in B<getrlimit>(2))."
7924 #: build/C/man5/proc.5:1092
7926 "I<SigPnd>, I<ShdPnd>: Number of signals pending for thread and for process "
7927 "as a whole (see B<pthreads>(7) and B<signal>(7))."
7931 #: build/C/man5/proc.5:1096
7933 "I<SigBlk>, I<SigIgn>, I<SigCgt>: Masks indicating signals being blocked, "
7934 "ignored, and caught (see B<signal>(7))."
7938 #: build/C/man5/proc.5:1101
7940 "I<CapInh>, I<CapPrm>, I<CapEff>: Masks of capabilities enabled in "
7941 "inheritable, permitted, and effective sets (see B<capabilities>(7))."
7945 #: build/C/man5/proc.5:1106
7947 "I<CapBnd>: Capability Bounding set (since kernel 2.6.26, see "
7948 "B<capabilities>(7))."
7952 #: build/C/man5/proc.5:1111
7954 "I<Cpus_allowed>: Mask of CPUs on which this process may run (since Linux "
7955 "2.6.24, see B<cpuset>(7))."
7959 #: build/C/man5/proc.5:1116
7961 "I<Cpus_allowed_list>: Same as previous, but in \"list format\" (since Linux "
7962 "2.6.26, see B<cpuset>(7))."
7966 #: build/C/man5/proc.5:1121
7968 "I<Mems_allowed>: Mask of memory nodes allowed to this process (since Linux "
7969 "2.6.24, see B<cpuset>(7))."
7973 #: build/C/man5/proc.5:1126
7975 "I<Mems_allowed_list>: Same as previous, but in \"list format\" (since Linux "
7976 "2.6.26, see B<cpuset>(7))."
7980 #: build/C/man5/proc.5:1129
7982 "I<voluntary_context_switches>, I<nonvoluntary_context_switches>: Number of "
7983 "voluntary and involuntary context switches (since Linux 2.6.23)."
7987 #: build/C/man5/proc.5:1130
7989 msgid "I</proc/[pid]/task> (since Linux 2.6.0-test6)"
7993 #: build/C/man5/proc.5:1161
7995 "This is a directory that contains one subdirectory for each thread in the "
7996 "process. The name of each subdirectory is the numerical thread ID "
7997 "(I<[tid]>) of the thread (see B<gettid>(2)). Within each of these "
7998 "subdirectories, there is a set of files with the same names and contents as "
7999 "under the I</proc/[pid]> directories. For attributes that are shared by all "
8000 "threads, the contents for each of the files under the I<task/[tid]> "
8001 "subdirectories will be the same as in the corresponding file in the parent "
8002 "I</proc/[pid]> directory (e.g., in a multithreaded process, all of the "
8003 "I<task/[tid]/cwd> files will have the same value as the I</proc/[pid]/cwd> "
8004 "file in the parent directory, since all of the threads in a process share a "
8005 "working directory). For attributes that are distinct for each thread, the "
8006 "corresponding files under I<task/[tid]> may have different values (e.g., "
8007 "various fields in each of the I<task/[tid]/status> files may be different "
8011 #. The following was still true as at kernel 2.6.13
8013 #: build/C/man5/proc.5:1168
8015 "In a multithreaded process, the contents of the I</proc/[pid]/task> "
8016 "directory are not available if the main thread has already terminated "
8017 "(typically by calling B<pthread_exit>(3))."
8021 #: build/C/man5/proc.5:1168
8023 msgid "I</proc/apm>"
8027 #: build/C/man5/proc.5:1173
8029 "Advanced power management version and battery information when B<CONFIG_APM> "
8030 "is defined at kernel compilation time."
8034 #: build/C/man5/proc.5:1173
8036 msgid "I</proc/bus>"
8040 #: build/C/man5/proc.5:1176
8041 msgid "Contains subdirectories for installed busses."
8045 #: build/C/man5/proc.5:1176
8047 msgid "I</proc/bus/pccard>"
8051 #: build/C/man5/proc.5:1181
8053 "Subdirectory for PCMCIA devices when B<CONFIG_PCMCIA> is set at kernel "
8058 #: build/C/man5/proc.5:1181
8060 msgid "I</proc/bus/pccard/drivers>"
8064 #: build/C/man5/proc.5:1183
8066 msgid "I</proc/bus/pci>"
8070 #: build/C/man5/proc.5:1189
8072 "Contains various bus subdirectories and pseudo-files containing information "
8073 "about PCI busses, installed devices, and device drivers. Some of these "
8074 "files are not ASCII."
8078 #: build/C/man5/proc.5:1189
8080 msgid "I</proc/bus/pci/devices>"
8084 #: build/C/man5/proc.5:1196
8086 "Information about PCI devices. They may be accessed through B<lspci>(8) "
8091 #: build/C/man5/proc.5:1196
8093 msgid "I</proc/cmdline>"
8097 #: build/C/man5/proc.5:1203
8099 "Arguments passed to the Linux kernel at boot time. Often done via a boot "
8100 "manager such as B<lilo>(8) or B<grub>(8)."
8104 #: build/C/man5/proc.5:1203
8106 msgid "I</proc/config.gz> (since Linux 2.6)"
8110 #: build/C/man5/proc.5:1221
8112 "This file exposes the configuration options that were used to build the "
8113 "currently running kernel, in the same format as they would be shown in the "
8114 "I<.config> file that resulted when configuring the kernel (using I<make "
8115 "xconfig>, I<make config>, or similar). The file contents are compressed; "
8116 "view or search them using B<zcat>(1), B<zgrep>(1), etc. As long as no "
8117 "changes have been made to the following file, the contents of "
8118 "I</proc/config.gz> are the same as those provided by :"
8122 #: build/C/man5/proc.5:1225
8124 msgid "cat /lib/modules/$(uname -r)/build/.config\n"
8128 #: build/C/man5/proc.5:1231
8130 "I</proc/config.gz> is only provided if the kernel is configured with "
8131 "B<CONFIG_IKCONFIG_PROC>."
8135 #: build/C/man5/proc.5:1231
8137 msgid "I</proc/cpuinfo>"
8141 #: build/C/man5/proc.5:1240
8143 "This is a collection of CPU and system architecture dependent items, for "
8144 "each supported architecture a different list. Two common entries are "
8145 "I<processor> which gives CPU number and I<bogomips>; a system constant that "
8146 "is calculated during kernel initialization. SMP machines have information "
8151 #: build/C/man5/proc.5:1240
8153 msgid "I</proc/devices>"
8157 #: build/C/man5/proc.5:1244
8159 "Text listing of major numbers and device groups. This can be used by "
8160 "MAKEDEV scripts for consistency with the kernel."
8164 #: build/C/man5/proc.5:1244
8166 msgid "I</proc/diskstats> (since Linux 2.5.69)"
8170 #: build/C/man5/proc.5:1250
8172 "This file contains disk I/O statistics for each disk device. See the kernel "
8173 "source file I<Documentation/iostats.txt> for further information."
8177 #: build/C/man5/proc.5:1250
8179 msgid "I</proc/dma>"
8183 #: build/C/man5/proc.5:1254
8185 "This is a list of the registered I<ISA> DMA (direct memory access) channels "
8190 #: build/C/man5/proc.5:1254
8192 msgid "I</proc/driver>"
8196 #: build/C/man5/proc.5:1257 build/C/man5/proc.5:1285
8197 msgid "Empty subdirectory."
8201 #: build/C/man5/proc.5:1257
8203 msgid "I</proc/execdomains>"
8207 #: build/C/man5/proc.5:1260
8208 msgid "List of the execution domains (ABI personalities)."
8212 #: build/C/man5/proc.5:1260
8218 #: build/C/man5/proc.5:1265
8220 "Frame buffer information when B<CONFIG_FB> is defined during kernel "
8225 #: build/C/man5/proc.5:1265
8227 msgid "I</proc/filesystems>"
8231 #: build/C/man5/proc.5:1275
8233 "A text listing of the file systems which are supported by the kernel, namely "
8234 "file systems which were compiled into the kernel or whose kernel modules are "
8235 "currently loaded. (See also B<filesystems>(5).) If a file system is marked "
8236 "with \"nodev\", this means that it does not require a block device to be "
8237 "mounted (e.g., virtual file system, network file system)."
8241 #: build/C/man5/proc.5:1282
8243 "Incidentally, this file may be used by B<mount>(8) when no file system is "
8244 "specified and it didn't manage to determine the file system type. Then file "
8245 "systems contained in this file are tried (excepted those that are marked "
8250 #: build/C/man5/proc.5:1282
8256 #: build/C/man5/proc.5:1285
8258 msgid "I</proc/ide>"
8262 #: build/C/man5/proc.5:1291
8264 "This directory exists on systems with the IDE bus. There are directories "
8265 "for each IDE channel and attached device. Files include:"
8269 #: build/C/man5/proc.5:1304
8272 "cache buffer size in KB\n"
8273 "capacity number of sectors\n"
8274 "driver driver version\n"
8275 "geometry physical and logical geometry\n"
8276 "identify in hexadecimal\n"
8277 "media media type\n"
8278 "model manufacturer's model number\n"
8279 "settings drive settings\n"
8280 "smart_thresholds in hexadecimal\n"
8281 "smart_values in hexadecimal\n"
8285 #: build/C/man5/proc.5:1310
8287 "The B<hdparm>(8) utility provides access to this information in a friendly "
8292 #: build/C/man5/proc.5:1310
8294 msgid "I</proc/interrupts>"
8298 #: build/C/man5/proc.5:1320
8300 "This is used to record the number of interrupts per CPU per IO device. "
8301 "Since Linux 2.6.24, for the i386 and x86_64 architectures, at least, this "
8302 "also includes interrupts internal to the system (that is, not associated "
8303 "with a device as such), such as NMI (nonmaskable interrupt), LOC (local "
8304 "timer interrupt), and for SMP systems, TLB (TLB flush interrupt), RES "
8305 "(rescheduling interrupt), CAL (remote function call interrupt), and possibly "
8306 "others. Very easy to read formatting, done in ASCII."
8310 #: build/C/man5/proc.5:1320
8312 msgid "I</proc/iomem>"
8316 #: build/C/man5/proc.5:1323
8317 msgid "I/O memory map in Linux 2.4."
8321 #: build/C/man5/proc.5:1323
8323 msgid "I</proc/ioports>"
8327 #: build/C/man5/proc.5:1327
8329 "This is a list of currently registered Input-Output port regions that are in "
8334 #: build/C/man5/proc.5:1327
8336 msgid "I</proc/kallsyms> (since Linux 2.5.71)"
8340 #: build/C/man5/proc.5:1335
8342 "This holds the kernel exported symbol definitions used by the B<modules>(X) "
8343 "tools to dynamically link and bind loadable modules. In Linux 2.5.47 and "
8344 "earlier, a similar file with slightly different syntax was named I<ksyms>."
8348 #: build/C/man5/proc.5:1335
8350 msgid "I</proc/kcore>"
8354 #: build/C/man5/proc.5:1344
8356 "This file represents the physical memory of the system and is stored in the "
8357 "ELF core file format. With this pseudo-file, and an unstripped kernel "
8358 "(I</usr/src/linux/vmlinux>) binary, GDB can be used to examine the current "
8359 "state of any kernel data structures."
8363 #: build/C/man5/proc.5:1347
8364 msgid "The total length of the file is the size of physical memory (RAM) plus 4KB."
8368 #: build/C/man5/proc.5:1347
8370 msgid "I</proc/kmsg>"
8374 #: build/C/man5/proc.5:1359
8376 "This file can be used instead of the B<syslog>(2) system call to read "
8377 "kernel messages. A process must have superuser privileges to read this "
8378 "file, and only one process should read this file. This file should not be "
8379 "read if a syslog process is running which uses the B<syslog>(2) system call "
8380 "facility to log kernel messages."
8384 #: build/C/man5/proc.5:1363
8385 msgid "Information in this file is retrieved with the B<dmesg>(1) program."
8389 #: build/C/man5/proc.5:1363
8391 msgid "I</proc/ksyms> (Linux 1.1.23-2.5.47)"
8395 #: build/C/man5/proc.5:1367
8396 msgid "See I</proc/kallsyms>."
8400 #: build/C/man5/proc.5:1367
8402 msgid "I</proc/loadavg>"
8406 #: build/C/man5/proc.5:1382
8408 "The first three fields in this file are load average figures giving the "
8409 "number of jobs in the run queue (state R) or waiting for disk I/O (state D) "
8410 "averaged over 1, 5, and 15 minutes. They are the same as the load average "
8411 "numbers given by B<uptime>(1) and other programs. The fourth field "
8412 "consists of two numbers separated by a slash (/). The first of these is the "
8413 "number of currently runnable kernel scheduling entities (processes, "
8414 "threads). The value after the slash is the number of kernel scheduling "
8415 "entities that currently exist on the system. The fifth field is the PID of "
8416 "the process that was most recently created on the system."
8420 #: build/C/man5/proc.5:1382
8422 msgid "I</proc/locks>"
8426 #: build/C/man5/proc.5:1388
8428 "This file shows current file locks (B<flock>(2) and B<fcntl>(2)) and leases "
8433 #: build/C/man5/proc.5:1388
8435 msgid "I</proc/malloc> (only up to and including Linux 2.2)"
8438 #. It looks like this only ever did something back in 1.0 days
8440 #: build/C/man5/proc.5:1394
8442 "This file is only present if B<CONFIG_DEBUG_MALLOC> was defined during "
8447 #: build/C/man5/proc.5:1394
8449 msgid "I</proc/meminfo>"
8453 #: build/C/man5/proc.5:1402
8455 "This file reports statistics about memory usage on the system. It is used "
8456 "by B<free>(1) to report the amount of free and used memory (both physical "
8457 "and swap) on the system as well as the shared memory and buffers used by "
8462 #: build/C/man5/proc.5:1402
8464 msgid "I</proc/modules>"
8468 #: build/C/man5/proc.5:1407
8470 "A text list of the modules that have been loaded by the system. See also "
8475 #: build/C/man5/proc.5:1407
8477 msgid "I</proc/mounts>"
8481 #: build/C/man5/proc.5:1417
8483 "Before kernel 2.4.19, this file was a list of all the file systems currently "
8484 "mounted on the system. With the introduction of per-process mount "
8485 "namespaces in Linux 2.4.19, this file became a link to I</proc/self/mounts>, "
8486 "which lists the mount points of the process's own mount namespace. The "
8487 "format of this file is documented in B<fstab>(5)."
8491 #: build/C/man5/proc.5:1417
8493 msgid "I</proc/mtrr>"
8497 #: build/C/man5/proc.5:1423
8499 "Memory Type Range Registers. See the kernel source file "
8500 "I<Documentation/mtrr.txt> for details."
8504 #: build/C/man5/proc.5:1423
8506 msgid "I</proc/net>"
8510 #: build/C/man5/proc.5:1433
8512 "various net pseudo-files, all of which give the status of some part of the "
8513 "networking layer. These files contain ASCII structures and are, therefore, "
8514 "readable with B<cat>(1). However, the standard B<netstat>(8) suite "
8515 "provides much cleaner access to these files."
8519 #: build/C/man5/proc.5:1433
8521 msgid "I</proc/net/arp>"
8525 #: build/C/man5/proc.5:1439
8527 "This holds an ASCII readable dump of the kernel ARP table used for address "
8528 "resolutions. It will show both dynamically learned and preprogrammed ARP "
8529 "entries. The format is:"
8533 #: build/C/man5/proc.5:1446
8536 "CW<IP address HW type Flags HW address Mask Device\n"
8537 "192.168.0.50 0x1 0x2 00:50:BF:25:68:F3 * eth0\n"
8538 "192.168.0.250 0x1 0xc 00:00:00:00:00:00 * eth0>\n"
8542 #: build/C/man5/proc.5:1458
8544 "Here \"IP address\" is the IPv4 address of the machine and the \"HW type\" "
8545 "is the hardware type of the address from RFC\\ 826. The flags are the "
8546 "internal flags of the ARP structure (as defined in "
8547 "I</usr/include/linux/if_arp.h>) and the \"HW address\" is the data link "
8548 "layer mapping for that IP address if it is known."
8552 #: build/C/man5/proc.5:1458
8554 msgid "I</proc/net/dev>"
8558 #: build/C/man5/proc.5:1469
8560 "The dev pseudo-file contains network device status information. This gives "
8561 "the number of received and sent packets, the number of errors and collisions "
8562 "and other basic statistics. These are used by the B<ifconfig>(8) program "
8563 "to report device status. The format is:"
8567 #: build/C/man5/proc.5:1479
8570 "CW<Inter-| Receive | "
8572 " face |bytes packets errs drop fifo frame compressed multicast|bytes "
8573 "packets errs drop fifo colls carrier compressed\n"
8574 " lo: 2776770 11307 0 0 0 0 0 0 2776770 "
8575 "11307 0 0 0 0 0 0\n"
8576 " eth0: 1215645 2751 0 0 0 0 0 0 1782404 "
8577 "4324 0 0 0 427 0 0\n"
8578 " ppp0: 1622270 5552 1 0 0 0 0 0 354130 "
8579 "5669 0 0 0 0 0 0\n"
8580 " tap0: 7714 81 0 0 0 0 0 0 7714 "
8585 #: build/C/man5/proc.5:1488
8587 msgid "I</proc/net/dev_mcast>"
8591 #: build/C/man5/proc.5:1492
8592 msgid "Defined in I</usr/src/linux/net/core/dev_mcast.c>:"
8596 #: build/C/man5/proc.5:1498
8599 "indx interface_name dmi_u dmi_g dmi_address\n"
8600 "2 eth0 1 0 01005e000001\n"
8601 "3 eth1 1 0 01005e000001\n"
8602 "4 eth2 1 0 01005e000001\n"
8606 #: build/C/man5/proc.5:1500
8608 msgid "I</proc/net/igmp>"
8612 #: build/C/man5/proc.5:1505
8614 "Internet Group Management Protocol. Defined in "
8615 "I</usr/src/linux/net/core/igmp.c>."
8619 #: build/C/man5/proc.5:1505
8621 msgid "I</proc/net/rarp>"
8625 #: build/C/man5/proc.5:1515
8627 "This file uses the same format as the I<arp> file and contains the current "
8628 "reverse mapping database used to provide B<rarp>(8) reverse address lookup "
8629 "services. If RARP is not configured into the kernel, this file will not be "
8634 #: build/C/man5/proc.5:1515
8636 msgid "I</proc/net/raw>"
8640 #. .I /proc/net/route
8641 #. No information, but looks similar to
8644 #: build/C/man5/proc.5:1535
8646 "Holds a dump of the RAW socket table. Much of the information is not of use "
8647 "apart from debugging. The \"sl\" value is the kernel hash slot for the "
8648 "socket, the \"local_address\" is the local address and protocol number "
8649 "pair. \\&\"St\" is the internal status of the socket. The \"tx_queue\" and "
8650 "\"rx_queue\" are the outgoing and incoming data queue in terms of kernel "
8651 "memory usage. The \"tr\", \"tm-E<gt>when\", and \"rexmits\" fields are not "
8652 "used by RAW. The \"uid\" field holds the effective UID of the creator of "
8657 #: build/C/man5/proc.5:1535
8659 msgid "I</proc/net/snmp>"
8663 #: build/C/man5/proc.5:1540
8665 "This file holds the ASCII data needed for the IP, ICMP, TCP, and UDP "
8666 "management information bases for an SNMP agent."
8670 #: build/C/man5/proc.5:1540
8672 msgid "I</proc/net/tcp>"
8676 #: build/C/man5/proc.5:1556
8678 "Holds a dump of the TCP socket table. Much of the information is not of use "
8679 "apart from debugging. The \"sl\" value is the kernel hash slot for the "
8680 "socket, the \"local_address\" is the local address and port number pair. "
8681 "The \"rem_address\" is the remote address and port number pair (if "
8682 "connected). \\&\"St\" is the internal status of the socket. The "
8683 "\"tx_queue\" and \"rx_queue\" are the outgoing and incoming data queue in "
8684 "terms of kernel memory usage. The \"tr\", \"tm-E<gt>when\", and \"rexmits\" "
8685 "fields hold internal information of the kernel socket state and are only "
8686 "useful for debugging. The \"uid\" field holds the effective UID of the "
8687 "creator of the socket."
8691 #: build/C/man5/proc.5:1556
8693 msgid "I</proc/net/udp>"
8697 #: build/C/man5/proc.5:1572
8699 "Holds a dump of the UDP socket table. Much of the information is not of use "
8700 "apart from debugging. The \"sl\" value is the kernel hash slot for the "
8701 "socket, the \"local_address\" is the local address and port number pair. "
8702 "The \"rem_address\" is the remote address and port number pair (if "
8703 "connected). \"St\" is the internal status of the socket. The \"tx_queue\" "
8704 "and \"rx_queue\" are the outgoing and incoming data queue in terms of kernel "
8705 "memory usage. The \"tr\", \"tm-E<gt>when\", and \"rexmits\" fields are not "
8706 "used by UDP. The \"uid\" field holds the effective UID of the creator of "
8707 "the socket. The format is:"
8711 #: build/C/man5/proc.5:1580
8714 "CW<sl local_address rem_address st tx_queue rx_queue tr rexmits "
8715 "tm-E<gt>when uid\n"
8716 " 1: 01642C89:0201 0C642C89:03FF 01 00000000:00000001 01:000071BA 00000000 "
8718 " 1: 00000000:0801 00000000:0000 0A 00000000:00000000 00:00000000 6F000100 "
8720 " 1: 00000000:0201 00000000:0000 0A 00000000:00000000 00:00000000 00000000 "
8725 #: build/C/man5/proc.5:1583
8727 msgid "I</proc/net/unix>"
8731 #: build/C/man5/proc.5:1588
8733 "Lists the UNIX domain sockets present within the system and their status. "
8738 #: build/C/man5/proc.5:1594
8741 "CW<Num RefCount Protocol Flags Type St Path\n"
8742 " 0: 00000002 00000000 00000000 0001 03\n"
8743 " 1: 00000001 00000000 00010000 0001 01 /dev/printer>\n"
8747 #: build/C/man5/proc.5:1606
8749 "Here \"Num\" is the kernel table slot number, \"RefCount\" is the number of "
8750 "users of the socket, \"Protocol\" is currently always 0, \"Flags\" represent "
8751 "the internal kernel flags holding the status of the socket. Currently, type "
8752 "is always \"1\" (UNIX domain datagram sockets are not yet supported in the "
8753 "kernel). \\&\"St\" is the internal state of the socket and Path is the "
8754 "bound path (if any) of the socket."
8758 #: build/C/man5/proc.5:1606
8760 msgid "I</proc/partitions>"
8764 #: build/C/man5/proc.5:1610
8766 "Contains major and minor numbers of each partition as well as number of "
8767 "blocks and partition name."
8771 #: build/C/man5/proc.5:1610
8773 msgid "I</proc/pci>"
8777 #: build/C/man5/proc.5:1614
8779 "This is a listing of all PCI devices found during kernel initialization and "
8780 "their configuration."
8783 #. FIXME /proc/sched_debug
8785 #. .IR /proc/sched_debug " (since Linux 2.6.23)"
8786 #. See also /proc/[pid]/sched
8788 #: build/C/man5/proc.5:1630
8790 "This file has been deprecated in favor of a new I</proc> interface for PCI "
8791 "(I</proc/bus/pci>). It became optional in Linux 2.2 (available with "
8792 "B<CONFIG_PCI_OLD_PROC> set at kernel compilation). It became once more "
8793 "nonoptionally enabled in Linux 2.4. Next, it was deprecated in Linux 2.6 "
8794 "(still available with B<CONFIG_PCI_LEGACY_PROC> set), and finally removed "
8795 "altogether since Linux 2.6.17."
8799 #: build/C/man5/proc.5:1630
8801 msgid "I</proc/scsi>"
8805 #: build/C/man5/proc.5:1640
8807 "A directory with the I<scsi> mid-level pseudo-file and various SCSI "
8808 "low-level driver directories, which contain a file for each SCSI host in "
8809 "this system, all of which give the status of some part of the SCSI IO "
8810 "subsystem. These files contain ASCII structures and are, therefore, "
8811 "readable with B<cat>(1)."
8815 #: build/C/man5/proc.5:1643
8817 "You can also write to some of the files to reconfigure the subsystem or "
8818 "switch certain features on or off."
8822 #: build/C/man5/proc.5:1643
8824 msgid "I</proc/scsi/scsi>"
8828 #: build/C/man5/proc.5:1649
8830 "This is a listing of all SCSI devices known to the kernel. The listing is "
8831 "similar to the one seen during bootup. scsi currently supports only the "
8832 "I<add-single-device> command which allows root to add a hotplugged device to "
8833 "the list of known devices."
8837 #: build/C/man5/proc.5:1651
8842 #: build/C/man5/proc.5:1655
8844 msgid "echo \\(aqscsi add-single-device 1 0 5 0\\(aq E<gt> /proc/scsi/scsi\n"
8848 #: build/C/man5/proc.5:1663
8850 "will cause host scsi1 to scan on SCSI channel 0 for a device on ID 5 LUN 0. "
8851 "If there is already a device known on this address or the address is "
8852 "invalid, an error will be returned."
8856 #: build/C/man5/proc.5:1663
8858 msgid "I</proc/scsi/[drivername]>"
8862 #: build/C/man5/proc.5:1673
8864 "I<[drivername]> can currently be NCR53c7xx, aha152x, aha1542, aha1740, "
8865 "aic7xxx, buslogic, eata_dma, eata_pio, fdomain, in2000, pas16, qlogic, "
8866 "scsi_debug, seagate, t128, u15-24f, ultrastore, or wd7000. These "
8867 "directories show up for all drivers that registered at least one SCSI HBA. "
8868 "Every directory contains one file per registered host. Every host-file is "
8869 "named after the number the host was assigned during initialization."
8873 #: build/C/man5/proc.5:1676
8875 "Reading these files will usually show driver and host configuration, "
8880 #: build/C/man5/proc.5:1683
8882 "Writing to these files allows different things on different hosts. For "
8883 "example, with the I<latency> and I<nolatency> commands, root can switch on "
8884 "and off command latency measurement code in the eata_dma driver. With the "
8885 "I<lockup> and I<unlock> commands, root can control bus lockups simulated by "
8886 "the scsi_debug driver."
8890 #: build/C/man5/proc.5:1683
8892 msgid "I</proc/self>"
8896 #: build/C/man5/proc.5:1691
8898 "This directory refers to the process accessing the I</proc> file system, and "
8899 "is identical to the I</proc> directory named by the process ID of the same "
8904 #: build/C/man5/proc.5:1691
8906 msgid "I</proc/slabinfo>"
8910 #: build/C/man5/proc.5:1700
8912 "Information about kernel caches. Since Linux 2.6.16 this file is only "
8913 "present if the B<CONFIG_SLAB> kernel configuration option is enabled. The "
8914 "columns in I</proc/slabinfo> are:"
8918 #: build/C/man5/proc.5:1710
8925 "num-active-slabs\n"
8927 "num-pages-per-slab\n"
8931 #: build/C/man5/proc.5:1716
8932 msgid "See B<slabinfo>(5) for details."
8936 #: build/C/man5/proc.5:1716
8938 msgid "I</proc/stat>"
8942 #: build/C/man5/proc.5:1722
8944 "kernel/system statistics. Varies with architecture. Common entries "
8949 #: build/C/man5/proc.5:1723
8951 msgid "I<cpu 3357 0 4313 1362393>"
8954 #. 1024 on Alpha and ia64
8955 #. FIXME Actually, the following info about the /proc/stat 'cpu' field
8956 #. does not seem to be quite right (at least in 2.6.12)
8958 #: build/C/man5/proc.5:1737
8960 "The amount of time, measured in units of USER_HZ (1/100ths of a second on "
8961 "most architectures, use I<sysconf(_SC_CLK_TCK)> to obtain the right value), "
8962 "that the system spent in user mode, user mode with low priority (nice), "
8963 "system mode, and the idle task, respectively. The last value should be "
8964 "USER_HZ times the second entry in the uptime pseudo-file."
8968 #: build/C/man5/proc.5:1745
8970 "In Linux 2.6 this line includes three additional columns: I<iowait> - time "
8971 "waiting for I/O to complete (since 2.5.41); I<irq> - time servicing "
8972 "interrupts (since 2.6.0-test4); I<softirq> - time servicing softirqs (since "
8977 #: build/C/man5/proc.5:1750
8979 "Since Linux 2.6.11, there is an eighth column, I<steal> - stolen time, which "
8980 "is the time spent in other operating systems when running in a virtualized "
8984 #. See Changelog entry for 5e84cfde51cf303d368fcb48f22059f37b3872de
8986 #: build/C/man5/proc.5:1756
8988 "Since Linux 2.6.24, there is a ninth column, I<guest>, which is the time "
8989 "spent running a virtual CPU for guest operating systems under the control of "
8994 #: build/C/man5/proc.5:1756
8996 msgid "I<page 5741 1808>"
9000 #: build/C/man5/proc.5:1760
9002 "The number of pages the system paged in and the number that were paged out "
9007 #: build/C/man5/proc.5:1760
9013 #: build/C/man5/proc.5:1763
9014 msgid "The number of swap pages that have been brought in and out."
9017 #. FIXME The following is not the full picture for the 'intr' of
9018 #. /proc/stat on 2.6:
9020 #: build/C/man5/proc.5:1763
9022 msgid "I<intr 1462898>"
9026 #: build/C/man5/proc.5:1771
9028 "This line shows counts of interrupts serviced since boot time, for each of "
9029 "the possible system interrupts. The first column is the total of all "
9030 "interrupts serviced; each subsequent column is the total for a particular "
9035 #: build/C/man5/proc.5:1771
9037 msgid "I<disk_io: (2,0):(31,30,5764,1,2) (3,0):>..."
9041 #: build/C/man5/proc.5:1774
9043 "(major,disk_idx):(noinfo, read_io_ops, blks_read, write_io_ops, "
9048 #: build/C/man5/proc.5:1776
9049 msgid "(Linux 2.4 only)"
9053 #: build/C/man5/proc.5:1776
9055 msgid "I<ctxt 115315>"
9059 #: build/C/man5/proc.5:1779
9060 msgid "The number of context switches that the system underwent."
9064 #: build/C/man5/proc.5:1779
9066 msgid "I<btime 769041601>"
9070 #: build/C/man5/proc.5:1782
9071 msgid "boot time, in seconds since the Epoch, 1970-01-01 00:00:00 +0000 (UTC)."
9075 #: build/C/man5/proc.5:1782
9077 msgid "I<processes 86031>"
9081 #: build/C/man5/proc.5:1785
9082 msgid "Number of forks since boot."
9086 #: build/C/man5/proc.5:1785
9088 msgid "I<procs_running 6>"
9092 #: build/C/man5/proc.5:1789
9093 msgid "Number of processes in runnable state. (Linux 2.5.45 onward.)"
9097 #: build/C/man5/proc.5:1789
9099 msgid "I<procs_blocked 2>"
9103 #: build/C/man5/proc.5:1793
9105 "Number of processes blocked waiting for I/O to complete. (Linux 2.5.45 "
9110 #: build/C/man5/proc.5:1794
9112 msgid "I</proc/swaps>"
9116 #: build/C/man5/proc.5:1799
9117 msgid "Swap areas in use. See also B<swapon>(8)."
9121 #: build/C/man5/proc.5:1799
9123 msgid "I</proc/sys>"
9127 #: build/C/man5/proc.5:1807
9129 "This directory (present since 1.3.57) contains a number of files and "
9130 "subdirectories corresponding to kernel variables. These variables can be "
9131 "read and sometimes modified using the I</proc> file system, and the "
9132 "(deprecated) B<sysctl>(2) system call."
9136 #: build/C/man5/proc.5:1807
9138 msgid "I</proc/sys/abi> (since Linux 2.4.10)"
9141 #. On some systems, it is not present.
9143 #: build/C/man5/proc.5:1814
9145 "This directory may contain files with application binary information. See "
9146 "the kernel source file I<Documentation/sysctl/abi.txt> for more information."
9150 #: build/C/man5/proc.5:1814
9152 msgid "I</proc/sys/debug>"
9156 #: build/C/man5/proc.5:1817 build/C/man5/proc.5:2462
9157 msgid "This directory may be empty."
9161 #: build/C/man5/proc.5:1817
9163 msgid "I</proc/sys/dev>"
9167 #: build/C/man5/proc.5:1823
9169 "This directory contains device-specific information (e.g., "
9170 "I<dev/cdrom/info>). On some systems, it may be empty."
9174 #: build/C/man5/proc.5:1823
9176 msgid "I</proc/sys/fs>"
9180 #: build/C/man5/proc.5:1827
9182 "This directory contains the files and subdirectories for kernel variables "
9183 "related to file systems."
9187 #: build/C/man5/proc.5:1827
9189 msgid "I</proc/sys/fs/binfmt_misc>"
9193 #: build/C/man5/proc.5:1832
9195 "Documentation for files in this directory can be found in the kernel sources "
9196 "in I<Documentation/binfmt_misc.txt>."
9200 #: build/C/man5/proc.5:1832
9202 msgid "I</proc/sys/fs/dentry-state> (since Linux 2.2)"
9206 #: build/C/man5/proc.5:1840
9208 "This file contains information about the status of the directory cache "
9209 "(dcache). The file contains six numbers, I<nr_dentry>, I<nr_unused>, "
9210 "I<age_limit> (age in seconds), I<want_pages> (pages requested by system) and "
9215 #: build/C/man5/proc.5:1845
9217 "I<nr_dentry> is the number of allocated dentries (dcache entries). This "
9218 "field is unused in Linux 2.2."
9222 #: build/C/man5/proc.5:1848
9223 msgid "I<nr_unused> is the number of unused dentries."
9226 #. looks like this is unused in kernels 2.2 to 2.6
9228 #: build/C/man5/proc.5:1853
9230 "I<age_limit> is the age in seconds after which dcache entries can be "
9231 "reclaimed when memory is short."
9234 #. looks like this is unused in kernels 2.2 to 2.6
9236 #: build/C/man5/proc.5:1858
9238 "I<want_pages> is nonzero when the kernel has called shrink_dcache_pages() "
9239 "and the dcache isn't pruned yet."
9243 #: build/C/man5/proc.5:1859
9245 msgid "I</proc/sys/fs/dir-notify-enable>"
9249 #: build/C/man5/proc.5:1868
9251 "This file can be used to disable or enable the I<dnotify> interface "
9252 "described in B<fcntl>(2) on a system-wide basis. A value of 0 in this file "
9253 "disables the interface, and a value of 1 enables it."
9257 #: build/C/man5/proc.5:1868
9259 msgid "I</proc/sys/fs/dquot-max>"
9263 #: build/C/man5/proc.5:1875
9265 "This file shows the maximum number of cached disk quota entries. On some "
9266 "(2.4) systems, it is not present. If the number of free cached disk quota "
9267 "entries is very low and you have some awesome number of simultaneous system "
9268 "users, you might want to raise the limit."
9272 #: build/C/man5/proc.5:1875
9274 msgid "I</proc/sys/fs/dquot-nr>"
9278 #: build/C/man5/proc.5:1879
9280 "This file shows the number of allocated disk quota entries and the number of "
9281 "free disk quota entries."
9285 #: build/C/man5/proc.5:1879
9287 msgid "I</proc/sys/fs/epoll> (since Linux 2.6.28)"
9291 #: build/C/man5/proc.5:1888
9293 "This directory contains the file I<max_user_watches>, which can be used to "
9294 "limit the amount of kernel memory consumed by the I<epoll> interface. For "
9295 "further details, see B<epoll>(7)."
9299 #: build/C/man5/proc.5:1888
9301 msgid "I</proc/sys/fs/file-max>"
9305 #: build/C/man5/proc.5:1900
9307 "This file defines a system-wide limit on the number of open files for all "
9308 "processes. (See also B<setrlimit>(2), which can be used by a process to set "
9309 "the per-process limit, B<RLIMIT_NOFILE>, on the number of files it may "
9310 "open.) If you get lots of error messages about running out of file handles, "
9311 "try increasing this value:"
9315 #: build/C/man5/proc.5:1906
9317 msgid "CW< echo 100000 E<gt> /proc/sys/fs/file-max>\n"
9321 #: build/C/man5/proc.5:1913
9323 "The kernel constant B<NR_OPEN> imposes an upper limit on the value that may "
9324 "be placed in I<file-max>."
9328 #: build/C/man5/proc.5:1922
9330 "If you increase I</proc/sys/fs/file-max>, be sure to increase "
9331 "I</proc/sys/fs/inode-max> to 3-4 times the new value of "
9332 "I</proc/sys/fs/file-max>, or you will run out of inodes."
9336 #: build/C/man5/proc.5:1928
9337 msgid "Privileged processes (B<CAP_SYS_ADMIN>) can override the I<file-max> limit."
9341 #: build/C/man5/proc.5:1928
9343 msgid "I</proc/sys/fs/file-nr>"
9347 #: build/C/man5/proc.5:1940
9349 "This (read-only) file gives the number of files presently opened. It "
9350 "contains three numbers: the number of allocated file handles; the number of "
9351 "free file handles; and the maximum number of file handles. The kernel "
9352 "allocates file handles dynamically, but it doesn't free them again. If the "
9353 "number of allocated files is close to the maximum, you should consider "
9354 "increasing the maximum. When the number of free file handles is large, "
9355 "you've encountered a peak in your usage of file handles and you probably "
9356 "don't need to increase the maximum."
9360 #: build/C/man5/proc.5:1940
9362 msgid "I</proc/sys/fs/inode-max>"
9366 #: build/C/man5/proc.5:1950
9368 "This file contains the maximum number of in-memory inodes. On some (2.4) "
9369 "systems, it may not be present. This value should be 3-4 times larger than "
9370 "the value in I<file-max>, since I<stdin>, I<stdout> and network sockets also "
9371 "need an inode to handle them. When you regularly run out of inodes, you "
9372 "need to increase this value."
9376 #: build/C/man5/proc.5:1950
9378 msgid "I</proc/sys/fs/inode-nr>"
9382 #: build/C/man5/proc.5:1954
9383 msgid "This file contains the first two values from I<inode-state>."
9387 #: build/C/man5/proc.5:1954
9389 msgid "I</proc/sys/fs/inode-state>"
9393 #: build/C/man5/proc.5:1975
9395 "This file contains seven numbers: I<nr_inodes>, I<nr_free_inodes>, "
9396 "I<preshrink>, and four dummy values. I<nr_inodes> is the number of inodes "
9397 "the system has allocated. This can be slightly more than I<inode-max> "
9398 "because Linux allocates them one page full at a time. I<nr_free_inodes> "
9399 "represents the number of free inodes. I<preshrink> is nonzero when the "
9400 "I<nr_inodes> E<gt> I<inode-max> and the system needs to prune the inode list "
9401 "instead of allocating more."
9405 #: build/C/man5/proc.5:1975
9407 msgid "I</proc/sys/fs/inotify> (since Linux 2.6.13)"
9411 #: build/C/man5/proc.5:1984
9413 "This directory contains files I<max_queued_events>, I<max_user_instances>, "
9414 "and I<max_user_watches>, that can be used to limit the amount of kernel "
9415 "memory consumed by the I<inotify> interface. For further details, see "
9420 #: build/C/man5/proc.5:1984
9422 msgid "I</proc/sys/fs/lease-break-time>"
9426 #: build/C/man5/proc.5:1993
9428 "This file specifies the grace period that the kernel grants to a process "
9429 "holding a file lease (B<fcntl>(2)) after it has sent a signal to that "
9430 "process notifying it that another process is waiting to open the file. If "
9431 "the lease holder does not remove or downgrade the lease within this grace "
9432 "period, the kernel forcibly breaks the lease."
9436 #: build/C/man5/proc.5:1993
9438 msgid "I</proc/sys/fs/leases-enable>"
9442 #: build/C/man5/proc.5:2000
9444 "This file can be used to enable or disable file leases (B<fcntl>(2)) on a "
9445 "system-wide basis. If this file contains the value 0, leases are disabled. "
9446 "A nonzero value enables leases."
9450 #: build/C/man5/proc.5:2000
9452 msgid "I</proc/sys/fs/mqueue> (since Linux 2.6.6)"
9456 #: build/C/man5/proc.5:2008
9458 "This directory contains files I<msg_max>, I<msgsize_max>, and I<queues_max>, "
9459 "controlling the resources used by POSIX message queues. See "
9460 "B<mq_overview>(7) for details."
9464 #: build/C/man5/proc.5:2008
9466 msgid "I</proc/sys/fs/overflowgid> and I</proc/sys/fs/overflowuid>"
9470 #: build/C/man5/proc.5:2018
9472 "These files allow you to change the value of the fixed UID and GID. The "
9473 "default is 65534. Some file systems only support 16-bit UIDs and GIDs, "
9474 "although in Linux UIDs and GIDs are 32 bits. When one of these file systems "
9475 "is mounted with writes enabled, any UID or GID that would exceed 65535 is "
9476 "translated to the overflow value before being written to disk."
9480 #: build/C/man5/proc.5:2018
9482 msgid "I</proc/sys/fs/pipe-max-size> (since Linux 2.6.35)"
9486 #: build/C/man5/proc.5:2032
9488 "The value in this file defines an upper limit for raising the capacity of a "
9489 "pipe using the B<fcntl>(2) B<F_SETPIPE_SZ> operation. This limit applies "
9490 "only to unprivileged processes. The default value for this file is "
9491 "1,048,576. The value assigned to this file may be rounded upward, to "
9492 "reflect the value actually employed for a convenient implementation. To "
9493 "determine the rounded-up value, display the contents of this file after "
9494 "assigning a value to it. The minimum value that can be assigned to this "
9495 "file is the system page size."
9499 #: build/C/man5/proc.5:2032
9501 msgid "I</proc/sys/fs/suid_dumpable> (since Linux 2.6.13)"
9504 #. The following is based on text from Documentation/sysctl/kernel.txt
9506 #: build/C/man5/proc.5:2038
9508 "The value in this file determines whether core dump files are produced for "
9509 "set-user-ID or otherwise protected/tainted binaries. Three different "
9510 "integer values can be specified:"
9514 #: build/C/man5/proc.5:2047
9516 "I<0\\ (default)> This provides the traditional (pre-Linux 2.6.13) behavior. "
9517 "A core dump will not be produced for a process which has changed credentials "
9518 "(by calling B<seteuid>(2), B<setgid>(2), or similar, or by executing a "
9519 "set-user-ID or set-group-ID program) or whose binary does not have read "
9520 "permission enabled."
9524 #: build/C/man5/proc.5:2054
9526 "I<1\\ (\"debug\")> All processes dump core when possible. The core dump is "
9527 "owned by the file system user ID of the dumping process and no security is "
9528 "applied. This is intended for system debugging situations only. Ptrace is "
9533 #: build/C/man5/proc.5:2063
9535 "I<2\\ (\"suidsafe\")> Any binary which normally would not be dumped (see "
9536 "\"0\" above) is dumped readable by root only. This allows the user to "
9537 "remove the core dump file but not to read it. For security reasons core "
9538 "dumps in this mode will not overwrite one another or other files. This mode "
9539 "is appropriate when administrators are attempting to debug problems in a "
9540 "normal environment."
9544 #: build/C/man5/proc.5:2063
9546 msgid "I</proc/sys/fs/super-max>"
9550 #: build/C/man5/proc.5:2074
9552 "This file controls the maximum number of superblocks, and thus the maximum "
9553 "number of mounted file systems the kernel can have. You only need to "
9554 "increase I<super-max> if you need to mount more file systems than the "
9555 "current value in I<super-max> allows you to."
9559 #: build/C/man5/proc.5:2074
9561 msgid "I</proc/sys/fs/super-nr>"
9565 #: build/C/man5/proc.5:2078
9566 msgid "This file contains the number of file systems currently mounted."
9570 #: build/C/man5/proc.5:2078
9572 msgid "I</proc/sys/kernel>"
9576 #: build/C/man5/proc.5:2082
9578 "This directory contains files controlling a range of kernel parameters, as "
9583 #: build/C/man5/proc.5:2082
9585 msgid "I</proc/sys/kernel/acct>"
9589 #: build/C/man5/proc.5:2106
9591 "This file contains three numbers: I<highwater>, I<lowwater>, and "
9592 "I<frequency>. If BSD-style process accounting is enabled these values "
9593 "control its behavior. If free space on file system where the log lives goes "
9594 "below I<lowwater> percent accounting suspends. If free space gets above "
9595 "I<highwater> percent accounting resumes. I<frequency> determines how often "
9596 "the kernel checks the amount of free space (value is in seconds). Default "
9597 "values are 4, 2 and 30. That is, suspend accounting if 2% or less space is "
9598 "free; resume it if 4% or more space is free; consider information about "
9599 "amount of free space valid for 30 seconds."
9603 #: build/C/man5/proc.5:2106
9605 msgid "I</proc/sys/kernel/cap-bound> (from Linux 2.2 to 2.6.24)"
9609 #: build/C/man5/proc.5:2118
9611 "This file holds the value of the kernel I<capability bounding set> "
9612 "(expressed as a signed decimal number). This set is ANDed against the "
9613 "capabilities permitted to a process during B<execve>(2). Starting with "
9614 "Linux 2.6.25, the system-wide capability bounding set disappeared, and was "
9615 "replaced by a per-thread bounding set; see B<capabilities>(7)."
9619 #: build/C/man5/proc.5:2118
9621 msgid "I</proc/sys/kernel/core_pattern>"
9625 #: build/C/man5/proc.5:2122
9627 msgid "I</proc/sys/kernel/core_uses_pid>"
9631 #: build/C/man5/proc.5:2126
9633 msgid "I</proc/sys/kernel/ctrl-alt-del>"
9637 #: build/C/man5/proc.5:2141
9639 "This file controls the handling of Ctrl-Alt-Del from the keyboard. When the "
9640 "value in this file is 0, Ctrl-Alt-Del is trapped and sent to the B<init>(8) "
9641 "program to handle a graceful restart. When the value is greater than zero, "
9642 "Linux's reaction to a Vulcan Nerve Pinch (tm) will be an immediate reboot, "
9643 "without even syncing its dirty buffers. Note: when a program (like dosemu) "
9644 "has the keyboard in \"raw\" mode, the ctrl-alt-del is intercepted by the "
9645 "program before it ever reaches the kernel tty layer, and it's up to the "
9646 "program to decide what to do with it."
9650 #: build/C/man5/proc.5:2141
9652 msgid "I</proc/sys/kernel/hotplug>"
9656 #: build/C/man5/proc.5:2147
9658 "This file contains the path for the hotplug policy agent. The default value "
9659 "in this file is I</sbin/hotplug>."
9663 #: build/C/man5/proc.5:2147
9665 msgid "I</proc/sys/kernel/domainname> and I</proc/sys/kernel/hostname>"
9669 #: build/C/man5/proc.5:2155
9671 "can be used to set the NIS/YP domainname and the hostname of your box in "
9672 "exactly the same way as the commands B<domainname>(1) and B<hostname>(1), "
9677 #: build/C/man5/proc.5:2160
9680 "#B< echo \\(aqdarkstar\\(aq E<gt> /proc/sys/kernel/hostname>\n"
9681 "#B< echo \\(aqmydomain\\(aq E<gt> /proc/sys/kernel/domainname>\n"
9685 #: build/C/man5/proc.5:2164
9686 msgid "has the same effect as"
9690 #: build/C/man5/proc.5:2169
9693 "#B< hostname \\(aqdarkstar\\(aq>\n"
9694 "#B< domainname \\(aqmydomain\\(aq>\n"
9698 #: build/C/man5/proc.5:2182
9700 "Note, however, that the classic darkstar.frop.org has the hostname "
9701 "\"darkstar\" and DNS (Internet Domain Name Server) domainname \"frop.org\", "
9702 "not to be confused with the NIS (Network Information Service) or YP (Yellow "
9703 "Pages) domainname. These two domain names are in general different. For a "
9704 "detailed discussion see the B<hostname>(1) man page."
9708 #: build/C/man5/proc.5:2182
9710 msgid "I</proc/sys/kernel/htab-reclaim>"
9714 #: build/C/man5/proc.5:2190
9716 "(PowerPC only) If this file is set to a nonzero value, the PowerPC htab (see "
9717 "kernel file I<Documentation/powerpc/ppc_htab.txt>) is pruned each time the "
9718 "system hits the idle loop."
9722 #: build/C/man5/proc.5:2190
9724 msgid "I</proc/sys/kernel/l2cr>"
9728 #: build/C/man5/proc.5:2197
9730 "(PowerPC only) This file contains a flag that controls the L2 cache of G3 "
9731 "processor boards. If 0, the cache is disabled. Enabled if nonzero."
9735 #: build/C/man5/proc.5:2197
9737 msgid "I</proc/sys/kernel/modprobe>"
9741 #: build/C/man5/proc.5:2208
9743 "This file contains the path for the kernel module loader. The default value "
9744 "is I</sbin/modprobe>. The file is only present if the kernel is built with "
9745 "the B<CONFIG_KMOD> option enabled. It is described by the kernel source "
9746 "file I<Documentation/kmod.txt> (only present in kernel 2.4 and earlier)."
9750 #: build/C/man5/proc.5:2208
9752 msgid "I</proc/sys/kernel/msgmax>"
9756 #: build/C/man5/proc.5:2213
9758 "This file defines a system-wide limit specifying the maximum number of bytes "
9759 "in a single message written on a System V message queue."
9763 #: build/C/man5/proc.5:2213
9765 msgid "I</proc/sys/kernel/msgmni>"
9769 #: build/C/man5/proc.5:2218
9771 "This file defines the system-wide limit on the number of message queue "
9772 "identifiers. (This file is only present in Linux 2.4 onward.)"
9776 #: build/C/man5/proc.5:2218
9778 msgid "I</proc/sys/kernel/msgmnb>"
9782 #: build/C/man5/proc.5:2227
9784 "This file defines a system-wide parameter used to initialize the "
9785 "I<msg_qbytes> setting for subsequently created message queues. The "
9786 "I<msg_qbytes> setting specifies the maximum number of bytes that may be "
9787 "written to the message queue."
9791 #: build/C/man5/proc.5:2227
9793 msgid "I</proc/sys/kernel/ostype> and I</proc/sys/kernel/osrelease>"
9797 #: build/C/man5/proc.5:2232
9798 msgid "These files give substrings of I</proc/version>."
9802 #: build/C/man5/proc.5:2232
9804 msgid "I</proc/sys/kernel/overflowgid> and I</proc/sys/kernel/overflowuid>"
9808 #: build/C/man5/proc.5:2238
9810 "These files duplicate the files I</proc/sys/fs/overflowgid> and "
9811 "I</proc/sys/fs/overflowuid>."
9815 #: build/C/man5/proc.5:2238
9817 msgid "I</proc/sys/kernel/panic>"
9821 #: build/C/man5/proc.5:2247
9823 "This file gives read/write access to the kernel variable I<panic_timeout>. "
9824 "If this is zero, the kernel will loop on a panic; if nonzero it indicates "
9825 "that the kernel should autoreboot after this number of seconds. When you "
9826 "use the software watchdog device driver, the recommended setting is 60."
9830 #: build/C/man5/proc.5:2247
9832 msgid "I</proc/sys/kernel/panic_on_oops> (since Linux 2.5.68)"
9836 #: build/C/man5/proc.5:2259
9838 "This file controls the kernel's behavior when an oops or BUG is "
9839 "encountered. If this file contains 0, then the system tries to continue "
9840 "operation. If it contains 1, then the system delays a few seconds (to give "
9841 "klogd time to record the oops output) and then panics. If the "
9842 "I</proc/sys/kernel/panic> file is also nonzero then the machine will be "
9847 #: build/C/man5/proc.5:2259
9849 msgid "I</proc/sys/kernel/pid_max> (since Linux 2.5.34)"
9852 #. Prior to 2.6.10, pid_max could also be raised above 32768 on 32-bit
9853 #. platforms, but this broke /proc/[pid]
9854 #. See http://marc.theaimsgroup.com/?l=linux-kernel&m=109513010926152&w=2
9856 #: build/C/man5/proc.5:2275
9858 "This file specifies the value at which PIDs wrap around (i.e., the value in "
9859 "this file is one greater than the maximum PID). The default value for this "
9860 "file, 32768, results in the same range of PIDs as on earlier kernels. On "
9861 "32-bit platforms, 32768 is the maximum value for I<pid_max>. On 64-bit "
9862 "systems, I<pid_max> can be set to any value up to 2^22 (B<PID_MAX_LIMIT>, "
9863 "approximately 4 million)."
9867 #: build/C/man5/proc.5:2275
9869 msgid "I</proc/sys/kernel/powersave-nap> (PowerPC only)"
9873 #: build/C/man5/proc.5:2281
9875 "This file contains a flag. If set, Linux-PPC will use the \"nap\" mode of "
9876 "powersaving, otherwise the \"doze\" mode will be used."
9880 #: build/C/man5/proc.5:2281
9882 msgid "I</proc/sys/kernel/printk>"
9886 #: build/C/man5/proc.5:2307
9888 "The four values in this file are I<console_loglevel>, "
9889 "I<default_message_loglevel>, I<minimum_console_level>, and "
9890 "I<default_console_loglevel>. These values influence I<printk()> behavior "
9891 "when printing or logging error messages. See B<syslog>(2) for more info on "
9892 "the different loglevels. Messages with a higher priority than "
9893 "I<console_loglevel> will be printed to the console. Messages without an "
9894 "explicit priority will be printed with priority I<default_message_level>. "
9895 "I<minimum_console_loglevel> is the minimum (highest) value to which "
9896 "I<console_loglevel> can be set. I<default_console_loglevel> is the default "
9897 "value for I<console_loglevel>."
9901 #: build/C/man5/proc.5:2307
9903 msgid "I</proc/sys/kernel/pty> (since Linux 2.6.4)"
9907 #: build/C/man5/proc.5:2313
9909 "This directory contains two files relating to the number of UNIX 98 "
9910 "pseudoterminals (see B<pts>(4)) on the system."
9914 #: build/C/man5/proc.5:2313
9916 msgid "I</proc/sys/kernel/pty/max>"
9920 #: build/C/man5/proc.5:2316
9921 msgid "This file defines the maximum number of pseudoterminals."
9925 #: build/C/man5/proc.5:2316
9927 msgid "I</proc/sys/kernel/pty/nr>"
9931 #: build/C/man5/proc.5:2320
9932 msgid "This read-only file indicates how many pseudoterminals are currently in use."
9936 #: build/C/man5/proc.5:2320
9938 msgid "I</proc/sys/kernel/random>"
9942 #: build/C/man5/proc.5:2328
9944 "This directory contains various parameters controlling the operation of the "
9945 "file I</dev/random>. See B<random>(4) for further information."
9949 #: build/C/man5/proc.5:2328
9951 msgid "I</proc/sys/kernel/real-root-dev>"
9955 #: build/C/man5/proc.5:2332
9957 "This file is documented in the kernel source file "
9958 "I<Documentation/initrd.txt>."
9962 #: build/C/man5/proc.5:2332
9964 msgid "I</proc/sys/kernel/reboot-cmd> (Sparc only) "
9968 #: build/C/man5/proc.5:2338
9970 "This file seems to be a way to give an argument to the SPARC ROM/Flash boot "
9971 "loader. Maybe to tell it what to do after rebooting?"
9975 #: build/C/man5/proc.5:2338
9977 msgid "I</proc/sys/kernel/rtsig-max>"
9981 #: build/C/man5/proc.5:2345
9983 "(Only in kernels up to and including 2.6.7; see B<setrlimit>(2)) This file "
9984 "can be used to tune the maximum number of POSIX real-time (queued) signals "
9985 "that can be outstanding in the system."
9989 #: build/C/man5/proc.5:2345
9991 msgid "I</proc/sys/kernel/rtsig-nr>"
9995 #: build/C/man5/proc.5:2349
9997 "(Only in kernels up to and including 2.6.7.) This file shows the number "
9998 "POSIX real-time signals currently queued."
10002 #: build/C/man5/proc.5:2349
10004 msgid "I</proc/sys/kernel/sem> (since Linux 2.4)"
10007 #. type: Plain text
10008 #: build/C/man5/proc.5:2353
10010 "This file contains 4 numbers defining limits for System V IPC semaphores. "
10011 "These fields are, in order:"
10015 #: build/C/man5/proc.5:2354
10020 #. type: Plain text
10021 #: build/C/man5/proc.5:2356
10022 msgid "The maximum semaphores per semaphore set."
10026 #: build/C/man5/proc.5:2356
10031 #. type: Plain text
10032 #: build/C/man5/proc.5:2358
10033 msgid "A system-wide limit on the number of semaphores in all semaphore sets."
10037 #: build/C/man5/proc.5:2358
10042 #. type: Plain text
10043 #: build/C/man5/proc.5:2362
10045 "The maximum number of operations that may be specified in a B<semop>(2) "
10050 #: build/C/man5/proc.5:2362
10055 #. type: Plain text
10056 #: build/C/man5/proc.5:2364
10057 msgid "A system-wide limit on the maximum number of semaphore identifiers."
10061 #: build/C/man5/proc.5:2365
10063 msgid "I</proc/sys/kernel/sg-big-buff>"
10066 #. type: Plain text
10067 #: build/C/man5/proc.5:2376
10069 "This file shows the size of the generic SCSI device (sg) buffer. You can't "
10070 "tune it just yet, but you could change it at compile time by editing "
10071 "I<include/scsi/sg.h> and changing the value of B<SG_BIG_BUFF>. However, "
10072 "there shouldn't be any reason to change this value."
10076 #: build/C/man5/proc.5:2376
10078 msgid "I</proc/sys/kernel/shmall>"
10081 #. type: Plain text
10082 #: build/C/man5/proc.5:2381
10084 "This file contains the system-wide limit on the total number of pages of "
10085 "System V shared memory."
10089 #: build/C/man5/proc.5:2381
10091 msgid "I</proc/sys/kernel/shmmax>"
10094 #. type: Plain text
10095 #: build/C/man5/proc.5:2391
10097 "This file can be used to query and set the run-time limit on the maximum "
10098 "(System V IPC) shared memory segment size that can be created. Shared "
10099 "memory segments up to 1GB are now supported in the kernel. This value "
10100 "defaults to B<SHMMAX>."
10104 #: build/C/man5/proc.5:2391
10106 msgid "I</proc/sys/kernel/shmmni>"
10109 #. type: Plain text
10110 #: build/C/man5/proc.5:2397
10112 "(available in Linux 2.4 and onward) This file specifies the system-wide "
10113 "maximum number of System V shared memory segments that can be created."
10117 #: build/C/man5/proc.5:2397
10119 msgid "I</proc/sys/kernel/sysrq>"
10122 #. type: Plain text
10123 #: build/C/man5/proc.5:2406
10125 "This file controls the functions allowed to be invoked by the SysRq key. By "
10126 "default, the file contains 1 meaning that every possible SysRq request is "
10127 "allowed (in older kernel versions, SysRq was disabled by default, and you "
10128 "were required to specifically enable it at run-time, but this is not the "
10129 "case any more). Possible values in this file are:"
10132 #. type: Plain text
10133 #: build/C/man5/proc.5:2418
10136 " 0 - disable sysrq completely\n"
10137 " 1 - enable all functions of sysrq\n"
10138 " E<gt>1 - bitmask of allowed sysrq functions, as follows:\n"
10139 " 2 - enable control of console logging level\n"
10140 " 4 - enable control of keyboard (SAK, unraw)\n"
10141 " 8 - enable debugging dumps of processes etc.\n"
10142 " 16 - enable sync command\n"
10143 " 32 - enable remount read-only\n"
10144 " 64 - enable signalling of processes (term, kill, oom-kill)\n"
10145 " 128 - allow reboot/poweroff\n"
10146 " 256 - allow nicing of all real-time tasks\n"
10149 #. type: Plain text
10150 #: build/C/man5/proc.5:2424
10152 "This file is only present if the B<CONFIG_MAGIC_SYSRQ> kernel configuration "
10153 "option is enabled. For further details see the kernel source file "
10154 "I<Documentation/sysrq.txt>."
10158 #: build/C/man5/proc.5:2424
10160 msgid "I</proc/sys/kernel/version>"
10163 #. type: Plain text
10164 #: build/C/man5/proc.5:2427
10165 msgid "This file contains a string like:"
10168 #. type: Plain text
10169 #: build/C/man5/proc.5:2429
10171 msgid " #5 Wed Feb 25 21:49:24 MET 1998\n"
10174 #. type: Plain text
10175 #: build/C/man5/proc.5:2433
10177 "The \"#5\" means that this is the fifth kernel built from this source base "
10178 "and the date behind it indicates the time the kernel was built."
10182 #: build/C/man5/proc.5:2433
10184 msgid "I</proc/sys/kernel/threads-max> (since Linux 2.3.11)"
10187 #. type: Plain text
10188 #: build/C/man5/proc.5:2437
10190 "This file specifies the system-wide limit on the number of threads (tasks) "
10191 "that can be created on the system."
10195 #: build/C/man5/proc.5:2437
10197 msgid "I</proc/sys/kernel/zero-paged> (PowerPC only) "
10200 #. type: Plain text
10201 #: build/C/man5/proc.5:2443
10203 "This file contains a flag. When enabled (nonzero), Linux-PPC will pre-zero "
10204 "pages in the idle loop, possibly speeding up get_free_pages."
10208 #: build/C/man5/proc.5:2443
10210 msgid "I</proc/sys/net>"
10213 #. type: Plain text
10214 #: build/C/man5/proc.5:2450
10216 "This directory contains networking stuff. Explanations for some of the "
10217 "files under this directory can be found in B<tcp>(7) and B<ip>(7)."
10221 #: build/C/man5/proc.5:2450
10223 msgid "I</proc/sys/net/core/somaxconn>"
10226 #. type: Plain text
10227 #: build/C/man5/proc.5:2459
10229 "This file defines a ceiling value for the I<backlog> argument of "
10230 "B<listen>(2); see the B<listen>(2) manual page for details."
10234 #: build/C/man5/proc.5:2459
10236 msgid "I</proc/sys/proc>"
10240 #: build/C/man5/proc.5:2462
10242 msgid "I</proc/sys/sunrpc>"
10245 #. type: Plain text
10246 #: build/C/man5/proc.5:2467
10248 "This directory supports Sun remote procedure call for network file system "
10249 "(NFS). On some systems, it is not present."
10253 #: build/C/man5/proc.5:2467
10255 msgid "I</proc/sys/vm>"
10258 #. type: Plain text
10259 #: build/C/man5/proc.5:2471
10261 "This directory contains files for memory management tuning, buffer and cache "
10266 #: build/C/man5/proc.5:2471
10268 msgid "I</proc/sys/vm/drop_caches> (since Linux 2.6.16)"
10271 #. type: Plain text
10272 #: build/C/man5/proc.5:2475
10274 "Writing to this file causes the kernel to drop clean caches, dentries and "
10275 "inodes from memory, causing that memory to become free."
10278 #. type: Plain text
10279 #: build/C/man5/proc.5:2482
10281 "To free pagecache, use I<echo 1 E<gt> /proc/sys/vm/drop_caches>; to free "
10282 "dentries and inodes, use I<echo 2 E<gt> /proc/sys/vm/drop_caches>; to free "
10283 "pagecache, dentries and inodes, use I<echo 3 E<gt> "
10284 "/proc/sys/vm/drop_caches>."
10287 #. type: Plain text
10288 #: build/C/man5/proc.5:2488
10290 "Because this is a nondestructive operation and dirty objects are not "
10291 "freeable, the user should run B<sync>(8) first."
10295 #: build/C/man5/proc.5:2488
10297 msgid "I</proc/sys/vm/legacy_va_layout> (since Linux 2.6.9)"
10300 #. The following is from Documentation/filesystems/proc.txt
10301 #. type: Plain text
10302 #: build/C/man5/proc.5:2493
10304 "If nonzero, this disables the new 32-bit memory-mapping layout; the kernel "
10305 "will use the legacy (2.4) layout for all processes."
10309 #: build/C/man5/proc.5:2493
10311 msgid "I</proc/sys/vm/memory_failure_early_kill> (since Linux 2.6.32)"
10314 #. The following is based on the text in Documentation/sysctl/vm.txt
10315 #. type: Plain text
10316 #: build/C/man5/proc.5:2505
10318 "Control how to kill processes when an uncorrected memory error (typically a "
10319 "2-bit error in a memory module) that cannot be handled by the kernel is "
10320 "detected in the background by hardware. In some cases (like the page still "
10321 "having a valid copy on disk), the kernel will handle the failure "
10322 "transparently without affecting any applications. But if there is no other "
10323 "up-to-date copy of the data, it will kill processes to prevent any data "
10324 "corruptions from propagating."
10327 #. type: Plain text
10328 #: build/C/man5/proc.5:2507
10329 msgid "The file has one of the following values:"
10333 #: build/C/man5/proc.5:2508 build/C/man5/proc.5:2545
10338 #. type: Plain text
10339 #: build/C/man5/proc.5:2513
10341 "Kill all processes that have the corrupted-and-not-reloadable page mapped as "
10342 "soon as the corruption is detected. Note this is not supported for a few "
10343 "types of pages, like kernel internally allocated data or the swap cache, but "
10344 "works for the majority of user pages."
10348 #: build/C/man5/proc.5:2513 build/C/man5/proc.5:2547
10353 #. type: Plain text
10354 #: build/C/man5/proc.5:2516
10356 "Only unmap the corrupted page from all processes and only kill a process who "
10357 "tries to access it."
10360 #. type: Plain text
10361 #: build/C/man5/proc.5:2527
10363 "The kill is performed using a B<SIGBUS> signal with I<si_code> set to "
10364 "B<BUS_MCEERR_AO>. Processes can handle this if they want to; see "
10365 "B<sigaction>(2) for more details."
10368 #. type: Plain text
10369 #: build/C/man5/proc.5:2530
10371 "This feature is only active on architectures/platforms with advanced machine "
10372 "check handling and depends on the hardware capabilities."
10375 #. type: Plain text
10376 #: build/C/man5/proc.5:2537
10378 "Applications can override the I<memory_failure_early_kill> setting "
10379 "individually with the B<prctl>(2) B<PR_MCE_KILL> operation."
10382 #. type: Plain text
10383 #: build/C/man5/proc.5:2540 build/C/man5/proc.5:2553
10384 msgid "Only present if the kernel was configured with B<CONFIG_MEMORY_FAILURE>."
10388 #: build/C/man5/proc.5:2540
10390 msgid "I</proc/sys/vm/memory_failure_recovery> (since Linux 2.6.32)"
10393 #. The following is based on the text in Documentation/sysctl/vm.txt
10394 #. type: Plain text
10395 #: build/C/man5/proc.5:2544
10396 msgid "Enable memory failure recovery (when supported by the platform)"
10399 #. type: Plain text
10400 #: build/C/man5/proc.5:2547
10401 msgid "Attempt recovery."
10404 #. type: Plain text
10405 #: build/C/man5/proc.5:2549
10406 msgid "Always panic on a memory failure."
10410 #: build/C/man5/proc.5:2553
10412 msgid "I</proc/sys/vm/oom_dump_tasks> (since Linux 2.6.25)"
10415 #. The following is from Documentation/sysctl/vm.txt
10416 #. type: Plain text
10417 #: build/C/man5/proc.5:2568
10419 "Enables a system-wide task dump (excluding kernel threads) to be produced "
10420 "when the kernel performs an OOM-killing. The dump includes the following "
10421 "information for each task (thread, process): thread ID, real user ID, thread "
10422 "group ID (process ID), virtual memory size, resident set size, the CPU that "
10423 "the task is scheduled on, oom_adj score (see the description of "
10424 "I</proc/[pid]/oom_adj>), and command name. This is helpful to determine why "
10425 "the OOM-killer was invoked and to identify the rogue task that caused it."
10428 #. type: Plain text
10429 #: build/C/man5/proc.5:2574
10431 "If this contains the value zero, this information is suppressed. On very "
10432 "large systems with thousands of tasks, it may not be feasible to dump the "
10433 "memory state information for each one. Such systems should not be forced to "
10434 "incur a performance penalty in OOM situations when the information may not "
10438 #. type: Plain text
10439 #: build/C/man5/proc.5:2577
10441 "If this is set to nonzero, this information is shown whenever the OOM-killer "
10442 "actually kills a memory-hogging task."
10445 #. type: Plain text
10446 #: build/C/man5/proc.5:2579 build/C/man5/proc.5:2600
10447 msgid "The default value is 0."
10451 #: build/C/man5/proc.5:2579
10453 msgid "I</proc/sys/vm/oom_kill_allocating_task> (since Linux 2.6.24)"
10456 #. The following is from Documentation/sysctl/vm.txt
10457 #. type: Plain text
10458 #: build/C/man5/proc.5:2584
10460 "This enables or disables killing the OOM-triggering task in out-of-memory "
10464 #. type: Plain text
10465 #: build/C/man5/proc.5:2589
10467 "If this is set to zero, the OOM-killer will scan through the entire tasklist "
10468 "and select a task based on heuristics to kill. This normally selects a "
10469 "rogue memory-hogging task that frees up a large amount of memory when "
10473 #. type: Plain text
10474 #: build/C/man5/proc.5:2593
10476 "If this is set to nonzero, the OOM-killer simply kills the task that "
10477 "triggered the out-of-memory condition. This avoids a possibly expensive "
10481 #. type: Plain text
10482 #: build/C/man5/proc.5:2598
10484 "If I</proc/sys/vm/panic_on_oom> is nonzero, it takes precedence over "
10485 "whatever value is used in I</proc/sys/vm/oom_kill_allocating_task>."
10489 #: build/C/man5/proc.5:2600
10491 msgid "I</proc/sys/vm/overcommit_memory>"
10494 #. type: Plain text
10495 #: build/C/man5/proc.5:2604
10496 msgid "This file contains the kernel virtual memory accounting mode. Values are:"
10499 #. type: Plain text
10500 #: build/C/man5/proc.5:2607
10501 msgid "0: heuristic overcommit (this is the default)"
10504 #. type: Plain text
10505 #: build/C/man5/proc.5:2609
10506 msgid "1: always overcommit, never check"
10509 #. type: Plain text
10510 #: build/C/man5/proc.5:2611
10511 msgid "2: always check, never overcommit"
10514 #. type: Plain text
10515 #: build/C/man5/proc.5:2625
10517 "In mode 0, calls of B<mmap>(2) with B<MAP_NORESERVE> are not checked, and "
10518 "the default check is very weak, leading to the risk of getting a process "
10519 "\"OOM-killed\". Under Linux 2.4 any nonzero value implies mode 1. In mode "
10520 "2 (available since Linux 2.6), the total virtual address space on the system "
10521 "is limited to (SS + RAM*(r/100)), where SS is the size of the swap space, "
10522 "and RAM is the size of the physical memory, and r is the contents of the "
10523 "file I</proc/sys/vm/overcommit_ratio>."
10527 #: build/C/man5/proc.5:2625
10529 msgid "I</proc/sys/vm/overcommit_ratio>"
10532 #. type: Plain text
10533 #: build/C/man5/proc.5:2629
10534 msgid "See the description of I</proc/sys/vm/overcommit_memory>."
10538 #: build/C/man5/proc.5:2629
10540 msgid "I</proc/sys/vm/panic_on_oom> (since Linux 2.6.18)"
10543 #. The following is adapted from Documentation/sysctl/vm.txt
10544 #. type: Plain text
10545 #: build/C/man5/proc.5:2634
10546 msgid "This enables or disables a kernel panic in an out-of-memory situation."
10549 #. type: Plain text
10550 #: build/C/man5/proc.5:2639
10552 "If this file is set to the value 0, the kernel's OOM-killer will kill some "
10553 "rogue process. Usually, the OOM-killer is able to kill a rogue process and "
10554 "the system will survive."
10557 #. type: Plain text
10558 #: build/C/man5/proc.5:2654
10560 "If this file is set to the value 1, then the kernel normally panics when "
10561 "out-of-memory happens. However, if a process limits allocations to certain "
10562 "nodes using memory policies (B<mbind>(2) B<MPOL_BIND>) or cpusets "
10563 "(B<cpuset>(7)) and those nodes reach memory exhaustion status, one process "
10564 "may be killed by the OOM-killer. No panic occurs in this case: because "
10565 "other nodes' memory may be free, this means the system as a whole may not "
10566 "have reached an out-of-memory situation yet."
10569 #. type: Plain text
10570 #: build/C/man5/proc.5:2657
10572 "If this file is set to the value 2, the kernel always panics when an "
10573 "out-of-memory condition occurs."
10576 #. type: Plain text
10577 #: build/C/man5/proc.5:2661
10579 "The default value is 0. 1 and 2 are for failover of clustering. Select "
10580 "either according to your policy of failover."
10584 #: build/C/man5/proc.5:2661
10586 msgid "I</proc/sys/vm/swappiness>"
10589 #. The following is from Documentation/sysctl/vm.txt
10590 #. type: Plain text
10591 #: build/C/man5/proc.5:2669
10593 "The value in this file controls how aggressively the kernel will swap memory "
10594 "pages. Higher values increase aggressiveness, lower values decrease "
10595 "aggressiveness. The default value is 60."
10599 #: build/C/man5/proc.5:2669
10601 msgid "I</proc/sysrq-trigger> (since Linux 2.4.21)"
10604 #. type: Plain text
10605 #: build/C/man5/proc.5:2678
10607 "Writing a character to this file triggers the same SysRq function as typing "
10608 "ALT-SysRq-E<lt>characterE<gt> (see the description of "
10609 "I</proc/sys/kernel/sysrq>). This file is normally only writable by "
10610 "I<root>. For further details see the kernel source file "
10611 "I<Documentation/sysrq.txt>."
10615 #: build/C/man5/proc.5:2678
10617 msgid "I</proc/sysvipc>"
10620 #. type: Plain text
10621 #: build/C/man5/proc.5:2691
10623 "Subdirectory containing the pseudo-files I<msg>, I<sem> and I<shm>. These "
10624 "files list the System V Interprocess Communication (IPC) objects "
10625 "(respectively: message queues, semaphores, and shared memory) that "
10626 "currently exist on the system, providing similar information to that "
10627 "available via B<ipcs>(1). These files have headers and are formatted (one "
10628 "IPC object per line) for easy understanding. B<svipc>(7) provides further "
10629 "background on the information shown by these files."
10633 #: build/C/man5/proc.5:2691
10635 msgid "I</proc/tty>"
10638 #. type: Plain text
10639 #: build/C/man5/proc.5:2695
10641 "Subdirectory containing the pseudo-files and subdirectories for tty drivers "
10642 "and line disciplines."
10646 #: build/C/man5/proc.5:2695
10648 msgid "I</proc/uptime>"
10651 #. type: Plain text
10652 #: build/C/man5/proc.5:2699
10654 "This file contains two numbers: the uptime of the system (seconds), and the "
10655 "amount of time spent in idle process (seconds)."
10659 #: build/C/man5/proc.5:2699
10661 msgid "I</proc/version>"
10664 #. type: Plain text
10665 #: build/C/man5/proc.5:2708
10667 "This string identifies the kernel version that is currently running. It "
10668 "includes the contents of I</proc/sys/kernel/ostype>, "
10669 "I</proc/sys/kernel/osrelease> and I</proc/sys/kernel/version>. For example:"
10672 #. type: Plain text
10673 #: build/C/man5/proc.5:2712
10675 msgid "CW<Linux version 1.0.9 (quinlan@phaze) #1 Sat May 14 01:51:54 EDT 1994>\n"
10679 #: build/C/man5/proc.5:2723
10681 msgid "I</proc/vmstat> (since Linux 2.6)"
10684 #. type: Plain text
10685 #: build/C/man5/proc.5:2726
10686 msgid "This file displays various virtual memory statistics."
10690 #: build/C/man5/proc.5:2726
10692 msgid "I</proc/zoneinfo> (since Linux 2.6.13)"
10695 #. FIXME more should be said about /proc/zoneinfo
10696 #. type: Plain text
10697 #: build/C/man5/proc.5:2731
10699 "This file display information about memory zones. This is useful for "
10700 "analyzing virtual memory behavior."
10703 #. type: Plain text
10704 #: build/C/man5/proc.5:2738
10706 "Many strings (i.e., the environment and command line) are in the internal "
10707 "format, with subfields terminated by null bytes (\\(aq\\e0\\(aq), so you may "
10708 "find that things are more readable if you use I<od -c> or I<tr \"\\e000\" "
10709 "\"\\en\"> to read them. Alternatively, I<echo \\`cat E<lt>fileE<gt>\\`> "
10713 #. .SH ACKNOWLEDGEMENTS
10714 #. The material on /proc/sys/fs and /proc/sys/kernel is closely based on
10715 #. kernel source documentation files written by Rik van Riel.
10716 #. type: Plain text
10717 #: build/C/man5/proc.5:2744
10719 "This manual page is incomplete, possibly inaccurate, and is the kind of "
10720 "thing that needs to be updated very often."
10723 #. type: Plain text
10724 #: build/C/man5/proc.5:2769
10726 "B<cat>(1), B<dmesg>(1), B<find>(1), B<free>(1), B<ps>(1), B<tr>(1), "
10727 "B<uptime>(1), B<chroot>(2), B<mmap>(2), B<readlink>(2), B<syslog>(2), "
10728 "B<slabinfo>(5), B<hier>(7), B<time>(7), B<arp>(8), B<hdparm>(8), "
10729 "B<ifconfig>(8), B<init>(8), B<lsmod>(8), B<lspci>(8), B<mount>(8), "
10730 "B<netstat>(8), B<procinfo>(8), B<route>(8)"
10733 #. type: Plain text
10734 #: build/C/man5/proc.5:2773
10736 "The kernel source files: I<Documentation/filesystems/proc.txt>, "
10737 "I<Documentation/sysctl/vm.txt>"
10741 #: build/C/man7/standards.7:25
10747 #: build/C/man7/standards.7:25
10752 #. type: Plain text
10753 #: build/C/man7/standards.7:28
10754 msgid "standards - C and UNIX Standards"
10757 #. type: Plain text
10758 #: build/C/man7/standards.7:32
10760 "The CONFORMING TO section that appears in many manual pages identifies "
10761 "various standards to which the documented interface conforms. The following "
10762 "list briefly describes these standards."
10766 #: build/C/man7/standards.7:32
10771 #. type: Plain text
10772 #: build/C/man7/standards.7:35
10773 msgid "Version 7, the ancestral UNIX from Bell Labs."
10777 #: build/C/man7/standards.7:35
10782 #. type: Plain text
10783 #: build/C/man7/standards.7:44
10785 "This is an implementation standard defined by the 4.2 release of the "
10786 "I<Berkeley Software Distribution>, released by the University of California "
10787 "at Berkeley. This was the first Berkeley release that contained a TCP/IP "
10788 "stack and the sockets API. 4.2BSD was released in 1983."
10791 #. type: Plain text
10792 #: build/C/man7/standards.7:47
10794 "Earlier major BSD releases included I<3BSD> (1980), I<4BSD> (1980), and "
10795 "I<4.1BSD> (1981)."
10799 #: build/C/man7/standards.7:47
10804 #. type: Plain text
10805 #: build/C/man7/standards.7:50
10806 msgid "The successor to 4.2BSD, released in 1986."
10810 #: build/C/man7/standards.7:50
10815 #. type: Plain text
10816 #: build/C/man7/standards.7:54
10818 "The successor to 4.3BSD, released in 1993. This was the last major Berkeley "
10823 #: build/C/man7/standards.7:54
10825 msgid "B<System V>"
10828 #. type: Plain text
10829 #: build/C/man7/standards.7:61
10831 "This is an implementation standard defined by AT&T's milestone 1983 release "
10832 "of its commercial System V (five) release. The previous major AT&T release "
10833 "was I<System III>, released in 1981."
10837 #: build/C/man7/standards.7:61
10839 msgid "B<System V release 2 (SVr2)>"
10842 #. type: Plain text
10843 #: build/C/man7/standards.7:68
10845 "This was the next System V release, made in 1985. The SVr2 was formally "
10846 "described in the I<System V Interface Definition version 1> (I<SVID 1>) "
10847 "published in 1985."
10851 #: build/C/man7/standards.7:68
10853 msgid "B<System V release 3 (SVr3)>"
10856 #. type: Plain text
10857 #: build/C/man7/standards.7:74
10859 "This was the successor to SVr2, released in 1986. This release was formally "
10860 "described in the I<System V Interface Definition version 2> (I<SVID 2>)."
10864 #: build/C/man7/standards.7:74
10866 msgid "B<System V release 4 (SVr4)>"
10869 #. type: Plain text
10870 #: build/C/man7/standards.7:84
10872 "This was the successor to SVr3, released in 1989. This version of System V "
10873 "is described in the \"Programmer's Reference Manual: Operating System API "
10874 "(Intel processors)\" (Prentice-Hall 1992, ISBN 0-13-951294-2) This release "
10875 "was formally described in the I<System V Interface Definition version 3> "
10876 "(I<SVID 3>), and is considered the definitive System V release."
10880 #: build/C/man7/standards.7:84
10885 #. type: Plain text
10886 #: build/C/man7/standards.7:88
10888 "System V Interface Definition version 4, issued in 1995. Available online "
10889 "at http://www.sco.com/developers/devspecs/ ."
10893 #: build/C/man7/standards.7:88
10898 #. type: Plain text
10899 #: build/C/man7/standards.7:102
10901 "This was the first C language standard, ratified by ANSI (American National "
10902 "Standards Institute) in 1989 (I<X3.159-1989>). Sometimes this is known as "
10903 "I<ANSI C>, but since C99 is also an ANSI standard, this term is ambiguous. "
10904 "This standard was also ratified by ISO (International Standards "
10905 "Organization) in 1990 (I<ISO/IEC 9899:1990>), and is thus occasionally "
10906 "referred to as I<ISO C90>."
10910 #: build/C/man7/standards.7:102
10915 #. type: Plain text
10916 #: build/C/man7/standards.7:108
10918 "This revision of the C language standard was ratified by ISO in 1999 "
10919 "(I<ISO/IEC 9899:1999>). Available online at "
10920 "http://www.open-std.org/jtc1/sc22/wg14/www/standards."
10924 #: build/C/man7/standards.7:108
10926 msgid "B<POSIX.1-1990>"
10929 #. type: Plain text
10930 #: build/C/man7/standards.7:114
10932 "\"Portable Operating System Interface for Computing Environments\". IEEE "
10933 "1003.1-1990 part 1, ratified by ISO in 1990 (I<ISO/IEC 9945-1:1990>). The "
10934 "term \"POSIX\" was coined by Richard Stallman."
10938 #: build/C/man7/standards.7:114
10943 #. type: Plain text
10944 #: build/C/man7/standards.7:119
10946 "IEEE Std 1003.2-1992, describing commands and utilities, ratified by ISO in "
10947 "1993 (I<ISO/IEC 9945-2:1993>)."
10951 #: build/C/man7/standards.7:119
10953 msgid "B<POSIX.1b> (formerly known as I<POSIX.4>)"
10956 #. type: Plain text
10957 #: build/C/man7/standards.7:125
10959 "IEEE Std 1003.1b-1993 describing real-time facilities for portable operating "
10960 "systems, ratified by ISO in 1996 (I<ISO/IEC 9945-1:1996>)."
10964 #: build/C/man7/standards.7:125
10966 msgid "B<POSIX.1c>"
10969 #. type: Plain text
10970 #: build/C/man7/standards.7:128
10971 msgid "IEEE Std 1003.1c-1995 describing the POSIX threads interfaces."
10975 #: build/C/man7/standards.7:128
10977 msgid "B<POSIX.1d>"
10980 #. type: Plain text
10981 #: build/C/man7/standards.7:131
10982 msgid "IEEE Std 1003.1c-1999 describing additional real-time extensions."
10986 #: build/C/man7/standards.7:131
10988 msgid "B<POSIX.1g>"
10991 #. type: Plain text
10992 #: build/C/man7/standards.7:134
10993 msgid "IEEE Std 1003.1g-2000 describing networking APIs (including sockets)."
10997 #: build/C/man7/standards.7:134
10999 msgid "B<POSIX.1j>"
11002 #. type: Plain text
11003 #: build/C/man7/standards.7:137
11004 msgid "IEEE Std 1003.1j-2000 describing advanced real-time extensions."
11008 #: build/C/man7/standards.7:137
11010 msgid "B<POSIX.1-1996>"
11013 #. type: Plain text
11014 #: build/C/man7/standards.7:140
11015 msgid "A 1996 revision of POSIX.1 which incorporated POSIX.1b and POSIX.1c."
11019 #: build/C/man7/standards.7:140
11024 #. type: Plain text
11025 #: build/C/man7/standards.7:147
11027 "Released in 1989, this was the first significant release of the I<X/Open "
11028 "Portability Guide>, produced by the X/Open Company, a multivendor "
11029 "consortium. This multivolume guide was based on the POSIX standards."
11033 #: build/C/man7/standards.7:147
11038 #. type: Plain text
11039 #: build/C/man7/standards.7:150
11040 msgid "A revision of the X/Open Portability Guide, released in 1992."
11044 #: build/C/man7/standards.7:150
11049 #. type: Plain text
11050 #: build/C/man7/standards.7:157
11052 "A 1994 revision of XPG4. This is also referred to as I<Spec 1170>, where "
11053 "1170 referred to the number of interfaces defined by this standard."
11057 #: build/C/man7/standards.7:157
11059 msgid "B<SUS (SUSv1)>"
11062 #. type: Plain text
11063 #: build/C/man7/standards.7:165
11065 "Single UNIX Specification. This was a repackaging of XPG4v2 and other "
11066 "X/Open standards (X/Open Curses Issue 4 version 2, X/Open Networking Service "
11067 "(XNS) Issue 4). Systems conforming to this standard can be branded I<UNIX "
11072 #: build/C/man7/standards.7:165
11077 #. type: Plain text
11078 #: build/C/man7/standards.7:175
11080 "Single UNIX Specification version 2. Sometimes also referred to as "
11081 "I<XPG5>. This standard appeared in 1997. Systems conforming to this "
11082 "standard can be branded I<UNIX 98>. See also "
11083 "http://www.UNIX-systems.org/version2/ .)"
11087 #: build/C/man7/standards.7:175
11089 msgid "B<POSIX.1-2001, SUSv3>"
11092 #. type: Plain text
11093 #: build/C/man7/standards.7:185
11095 "This was a 2001 revision and consolidation of the POSIX.1, POSIX.2, and SUS "
11096 "standards into a single document, conducted under the auspices of the Austin "
11097 "group (http://www.opengroup.org/austin/ .) The standard is available online "
11098 "at http://www.unix-systems.org/version3/ , and the interfaces that it "
11099 "describes are also available in the Linux manual pages package under "
11100 "sections 1p and 3p (e.g., \"man 3p open\")."
11103 #. type: Plain text
11104 #: build/C/man7/standards.7:198
11106 "The standard defines two levels of conformance: I<POSIX conformance>, which "
11107 "is a baseline set of interfaces required of a conforming system; and I<XSI "
11108 "Conformance>, which additionally mandates a set of interfaces (the \"XSI "
11109 "extension\") which are only optional for POSIX conformance. XSI-conformant "
11110 "systems can be branded I<UNIX 03>. (XSI conformance constitutes the "
11111 "I<Single UNIX Specification version 3> (I<SUSv3>).)"
11114 #. type: Plain text
11115 #: build/C/man7/standards.7:200
11116 msgid "The POSIX.1-2001 document is broken into four parts:"
11119 #. type: Plain text
11120 #: build/C/man7/standards.7:203
11121 msgid "B<XBD>: Definitions, terms and concepts, header file specifications."
11124 #. type: Plain text
11125 #: build/C/man7/standards.7:207
11127 "B<XSH>: Specifications of functions (i.e., system calls and library "
11128 "functions in actual implementations)."
11131 #. type: Plain text
11132 #: build/C/man7/standards.7:211
11134 "B<XCU>: Specifications of commands and utilities (i.e., the area formerly "
11135 "described by POSIX.2)."
11138 #. type: Plain text
11139 #: build/C/man7/standards.7:214
11140 msgid "B<XRAT>: Informative text on the other parts of the standard."
11143 #. type: Plain text
11144 #: build/C/man7/standards.7:218
11146 "POSIX.1-2001 is aligned with C99, so that all of the library functions "
11147 "standardized in C99 are also standardized in POSIX.1-2001."
11150 #. type: Plain text
11151 #: build/C/man7/standards.7:225
11153 "Two Technical Corrigenda (minor fixes and improvements) of the original "
11154 "2001 standard have occurred: TC1 in 2003 (referred to as I<POSIX.1-2003>), "
11155 "and TC2 in 2004 (referred to as I<POSIX.1-2004>)."
11159 #: build/C/man7/standards.7:225
11161 msgid "B<POSIX.1-2008, SUSv4>"
11164 #. type: Plain text
11165 #: build/C/man7/standards.7:229
11166 msgid "Work on the next revision of POSIX.1/SUS was completed and ratified in 2008."
11169 #. type: Plain text
11170 #: build/C/man7/standards.7:238
11172 "The changes in this revision are not as large as those that occurred for "
11173 "POSIX.1-2001/SUSv3, but a number of new interfaces are added and various "
11174 "details of existing specifications are modified. Many of the interfaces "
11175 "that were optional in POSIX.1-2001 become mandatory in the 2008 revision of "
11176 "the standard. A few interfaces that are present in POSIX.1-2001 are marked "
11177 "as obsolete in POSIX.1-2008, or removed from the standard altogether."
11180 #. type: Plain text
11181 #: build/C/man7/standards.7:246
11183 "The revised standard is broken into the same four parts as POSIX.1-2001, and "
11184 "again there are two levels of conformance: the baseline I<POSIX "
11185 "Conformance>, and I<XSI Conformance>, which mandates an additional set of "
11186 "interfaces beyond those in the base specification."
11189 #. type: Plain text
11190 #: build/C/man7/standards.7:250
11192 "In general, where the CONFORMING TO section of a manual page lists "
11193 "POSIX.1-2001, it can be assumed that the interface also conforms to "
11194 "POSIX.1-2008, unless otherwise noted."
11197 #. type: Plain text
11198 #: build/C/man7/standards.7:253
11200 "Further information can be found on the Austin group web site, "
11201 "http://www.opengroup.org/austin/ ."
11204 #. type: Plain text
11205 #: build/C/man7/standards.7:257
11206 msgid "B<feature_test_macros>(7), B<libc>(7), B<posixoptions>(7)"
11210 #: build/C/man7/suffixes.7:38
11216 #: build/C/man7/suffixes.7:38
11221 #. type: Plain text
11222 #: build/C/man7/suffixes.7:41
11223 msgid "suffixes - list of file suffixes"
11226 #. type: Plain text
11227 #: build/C/man7/suffixes.7:49
11229 "It is customary to indicate the contents of a file with the file suffix, "
11230 "which consists of a period, followed by one or more letters. Many standard "
11231 "utilities, such as compilers, use this to recognize the type of file they "
11232 "are dealing with. The B<make>(1) utility is driven by rules based on file "
11236 #. type: Plain text
11237 #: build/C/man7/suffixes.7:52
11239 "Following is a list of suffixes which are likely to be found on a Linux "
11244 #: build/C/man7/suffixes.7:57
11246 msgid "Suffix\tFile type\n"
11250 #: build/C/man7/suffixes.7:58
11252 msgid " ,v\tfiles for RCS (Revision Control System)\n"
11256 #: build/C/man7/suffixes.7:59
11258 msgid " -\tbackup file\n"
11262 #: build/C/man7/suffixes.7:60
11264 msgid " .C\tC++ source code, equivalent to I<.cc>\n"
11268 #: build/C/man7/suffixes.7:61
11270 msgid " .F\tFortran source with B<cpp>(1) directives\n"
11274 #: build/C/man7/suffixes.7:62
11276 msgid "\tor file compressed using freeze\n"
11280 #: build/C/man7/suffixes.7:63
11282 msgid " .S\tassembler source with B<cpp>(1) directives\n"
11286 #: build/C/man7/suffixes.7:64
11288 msgid " .Y\tfile compressed using yabba\n"
11292 #: build/C/man7/suffixes.7:65
11294 msgid " .Z\tfile compressed using B<compress>(1)\n"
11298 #: build/C/man7/suffixes.7:66
11300 msgid " .[0-9]+gf\tTeX generic font files\n"
11304 #: build/C/man7/suffixes.7:67
11306 msgid " .[0-9]+pk\tTeX packed font files\n"
11310 #: build/C/man7/suffixes.7:68
11312 msgid " .[1-9]\tmanual page for the corresponding section\n"
11316 #: build/C/man7/suffixes.7:69
11318 msgid " .[1-9][a-z]\tmanual page for section plus subsection\n"
11322 #: build/C/man7/suffixes.7:70
11324 msgid " .a\tstatic object code library\n"
11328 #: build/C/man7/suffixes.7:71
11330 msgid " .ad\tX application default resource file\n"
11334 #: build/C/man7/suffixes.7:72
11336 msgid " .ada\tAda source (may be body, spec, or combination)\n"
11340 #: build/C/man7/suffixes.7:73
11342 msgid " .adb\tAda body source\n"
11346 #: build/C/man7/suffixes.7:74
11348 msgid " .ads\tAda spec source\n"
11352 #: build/C/man7/suffixes.7:75
11354 msgid " .afm\tPostScript font metrics\n"
11358 #: build/C/man7/suffixes.7:76
11360 msgid " .al\tPerl autoload file\n"
11364 #: build/C/man7/suffixes.7:77
11366 msgid " .am\tB<automake>(1) input file\n"
11370 #: build/C/man7/suffixes.7:78
11372 msgid " .arc\tB<arc>(1) archive\n"
11376 #: build/C/man7/suffixes.7:79
11378 msgid " .arj\tB<arj>(1) archive\n"
11382 #: build/C/man7/suffixes.7:80
11384 msgid " .asc\tPGP ASCII-armored data\n"
11388 #: build/C/man7/suffixes.7:81
11390 msgid " .asm\t(GNU) assembler source file\n"
11394 #: build/C/man7/suffixes.7:82
11396 msgid " .au\tAudio sound file\n"
11400 #: build/C/man7/suffixes.7:83
11402 msgid " .aux\tLaTeX auxiliary file\n"
11406 #: build/C/man7/suffixes.7:84
11408 msgid " .avi\t(msvideo) movie\n"
11412 #: build/C/man7/suffixes.7:85
11414 msgid " .awk\tAWK language program\n"
11418 #: build/C/man7/suffixes.7:86
11420 msgid " .b\tLILO boot loader image\n"
11424 #: build/C/man7/suffixes.7:87
11426 msgid " .bak\tbackup file\n"
11430 #: build/C/man7/suffixes.7:88
11432 msgid " .bash\tB<bash>(1) shell script\n"
11436 #: build/C/man7/suffixes.7:89
11438 msgid " .bb\tbasic block list data produced by\n"
11442 #: build/C/man7/suffixes.7:90 build/C/man7/suffixes.7:92
11444 msgid "\tgcc -ftest-coverage\n"
11448 #: build/C/man7/suffixes.7:91
11450 msgid " .bbg\tbasic block graph data produced by\n"
11454 #: build/C/man7/suffixes.7:93
11456 msgid " .bbl\tBibTeX output\n"
11460 #: build/C/man7/suffixes.7:94
11462 msgid " .bdf\tX font file\n"
11466 #: build/C/man7/suffixes.7:95
11468 msgid " .bib\tTeX bibliographic database, BibTeX input\n"
11472 #: build/C/man7/suffixes.7:96
11474 msgid " .bm\tbitmap source\n"
11478 #: build/C/man7/suffixes.7:97
11480 msgid " .bmp\tbitmap\n"
11484 #: build/C/man7/suffixes.7:98
11486 msgid " .bz2\tfile compressed using B<bzip2>(1)\n"
11490 #: build/C/man7/suffixes.7:99
11492 msgid " .c\tC source\n"
11496 #: build/C/man7/suffixes.7:100
11498 msgid " .cat\tmessage catalog files\n"
11502 #: build/C/man7/suffixes.7:101
11504 msgid " .cc\tC++ source\n"
11508 #: build/C/man7/suffixes.7:102
11510 msgid " .cf\tconfiguration file\n"
11514 #: build/C/man7/suffixes.7:103
11516 msgid " .cfg\tconfiguration file\n"
11520 #: build/C/man7/suffixes.7:104
11522 msgid " .cgi\tWWW content generating script or program\n"
11526 #: build/C/man7/suffixes.7:105
11528 msgid " .cls\tLaTeX Class definition\n"
11532 #: build/C/man7/suffixes.7:106
11534 msgid " .class\tJava compiled byte-code\n"
11538 #: build/C/man7/suffixes.7:107
11540 msgid " .conf\tconfiguration file\n"
11544 #: build/C/man7/suffixes.7:108
11546 msgid " .config\tconfiguration file\n"
11550 #: build/C/man7/suffixes.7:109
11552 msgid " .cpp\tequivalent to I<.cc>\n"
11556 #: build/C/man7/suffixes.7:110
11558 msgid " .csh\tB<csh>(1) shell script\n"
11562 #: build/C/man7/suffixes.7:111
11564 msgid " .cxx\tequivalent to I<.cc>\n"
11568 #: build/C/man7/suffixes.7:112
11570 msgid " .dat\tdata file\n"
11574 #: build/C/man7/suffixes.7:113
11576 msgid " .deb\tDebian software package\n"
11580 #: build/C/man7/suffixes.7:114
11582 msgid " .def\tModula-2 source for definition modules\n"
11586 #: build/C/man7/suffixes.7:115
11588 msgid " .def\tother definition files\n"
11592 #: build/C/man7/suffixes.7:116
11594 msgid " .desc\tinitial part of mail message unpacked with\n"
11598 #: build/C/man7/suffixes.7:117
11600 msgid "\tB<munpack>(1)\n"
11604 #: build/C/man7/suffixes.7:118
11606 msgid " .diff\tfile differences (B<diff>(1) command output)\n"
11610 #: build/C/man7/suffixes.7:119
11612 msgid " .dir\tdbm data base directory file\n"
11616 #: build/C/man7/suffixes.7:120
11618 msgid " .doc\tdocumentation file\n"
11622 #: build/C/man7/suffixes.7:121
11624 msgid " .dsc\tDebian Source Control (source package)\n"
11628 #: build/C/man7/suffixes.7:122
11630 msgid " .dtx\tLaTeX package source file\n"
11634 #: build/C/man7/suffixes.7:123
11636 msgid " .dvi\tTeX's device independent output\n"
11640 #: build/C/man7/suffixes.7:124
11642 msgid " .el\tEmacs-Lisp source\n"
11646 #: build/C/man7/suffixes.7:125
11648 msgid " .elc\tcompiled Emacs-Lisp source\n"
11652 #: build/C/man7/suffixes.7:126
11654 msgid " .eps\tencapsulated PostScript\n"
11658 #: build/C/man7/suffixes.7:127
11660 msgid " .exp\tExpect source code\n"
11664 #: build/C/man7/suffixes.7:128
11666 msgid " .f\tFortran source\n"
11670 #: build/C/man7/suffixes.7:129
11672 msgid " .f77\tFortran 77 source\n"
11676 #: build/C/man7/suffixes.7:130
11678 msgid " .f90\tFortran 90 source\n"
11682 #: build/C/man7/suffixes.7:131
11684 msgid " .fas\tprecompiled Common-Lisp\n"
11688 #: build/C/man7/suffixes.7:132
11690 msgid " .fi\tFortran include files\n"
11694 #: build/C/man7/suffixes.7:133
11696 msgid " .fig\tFIG image file (used by B<xfig>(1))\n"
11700 #: build/C/man7/suffixes.7:134
11702 msgid " .fmt\tTeX format file\n"
11706 #: build/C/man7/suffixes.7:135
11708 msgid " .gif\tCompuserve Graphics Image File format\n"
11712 #: build/C/man7/suffixes.7:136
11714 msgid " .gmo\tGNU format message catalog\n"
11718 #: build/C/man7/suffixes.7:137
11720 msgid " .gsf\tGhostscript fonts\n"
11724 #: build/C/man7/suffixes.7:138
11726 msgid " .gz\tfile compressed using B<gzip>(1)\n"
11730 #: build/C/man7/suffixes.7:139
11732 msgid " .h\tC or C++ header files\n"
11736 #: build/C/man7/suffixes.7:140
11738 msgid " .help\thelp file\n"
11742 #: build/C/man7/suffixes.7:141
11744 msgid " .hf\tequivalent to I<.help>\n"
11748 #: build/C/man7/suffixes.7:142
11750 msgid " .hlp\tequivalent to I<.help>\n"
11754 #: build/C/man7/suffixes.7:143
11756 msgid " .htm\tpoor man's I<.html>\n"
11760 #: build/C/man7/suffixes.7:144
11762 msgid " .html\tHTML document used with the World Wide Web\n"
11766 #: build/C/man7/suffixes.7:145
11768 msgid " .hqx\t7-bit encoded Macintosh file\n"
11772 #: build/C/man7/suffixes.7:146
11774 msgid " .i\tC source after preprocessing\n"
11778 #: build/C/man7/suffixes.7:147
11780 msgid " .icon\tbitmap source\n"
11784 #: build/C/man7/suffixes.7:148
11786 msgid " .idx\treference or datum-index file for hypertext\n"
11790 #: build/C/man7/suffixes.7:149
11792 msgid "\tor database system\n"
11796 #: build/C/man7/suffixes.7:150
11798 msgid " .image\tbitmap source\n"
11802 #: build/C/man7/suffixes.7:151
11804 msgid " .in\tconfiguration template, especially for GNU Autoconf\n"
11808 #: build/C/man7/suffixes.7:152
11810 msgid " .info\tfiles for the Emacs info browser\n"
11814 #: build/C/man7/suffixes.7:153
11816 msgid " .info-[0-9]+\tsplit info files\n"
11820 #: build/C/man7/suffixes.7:154
11822 msgid " .ins\tLaTeX package install file for docstrip\n"
11826 #: build/C/man7/suffixes.7:155
11828 msgid " .itcl\titcl source code;\n"
11832 #: build/C/man7/suffixes.7:156
11834 msgid "\titcl ([incr Tcl]) is an OO extension of tcl\n"
11838 #: build/C/man7/suffixes.7:157
11840 msgid " .java\ta Java source file\n"
11844 #: build/C/man7/suffixes.7:158
11846 msgid " .jpeg\tJoint Photographic Experts Group format\n"
11850 #: build/C/man7/suffixes.7:159
11852 msgid " .jpg\tpoor man's I<.jpeg>\n"
11856 #: build/C/man7/suffixes.7:160
11858 msgid " .kmap\tB<lyx>(1) keymap\n"
11862 #: build/C/man7/suffixes.7:161
11864 msgid " .l\tequivalent to I<.lex> or I<.lisp>\n"
11868 #: build/C/man7/suffixes.7:162
11870 msgid " .lex\tB<lex>(1) or B<flex>(1) files\n"
11874 #: build/C/man7/suffixes.7:163
11876 msgid " .lha\tlharc archive\n"
11880 #: build/C/man7/suffixes.7:164
11882 msgid " .lib\tCommon-Lisp library\n"
11886 #: build/C/man7/suffixes.7:165
11888 msgid " .lisp\tLisp source\n"
11892 #: build/C/man7/suffixes.7:166
11894 msgid " .ln\tfiles for use with B<lint>(1)\n"
11898 #: build/C/man7/suffixes.7:167
11900 msgid " .log\tlog file, in particular produced by TeX\n"
11904 #: build/C/man7/suffixes.7:168
11906 msgid " .lsm\tLinux Software Map entry\n"
11910 #: build/C/man7/suffixes.7:169
11912 msgid " .lsp\tCommon-Lisp source\n"
11916 #: build/C/man7/suffixes.7:170
11918 msgid " .lzh\tlharc archive\n"
11922 #: build/C/man7/suffixes.7:171
11924 msgid " .m\tObjective-C source code\n"
11928 #: build/C/man7/suffixes.7:172
11930 msgid " .m4\tB<m4>(1) source\n"
11934 #: build/C/man7/suffixes.7:173
11936 msgid " .mac\tmacro files for various programs\n"
11940 #: build/C/man7/suffixes.7:174
11942 msgid " .man\tmanual page (usually source rather than formatted)\n"
11946 #: build/C/man7/suffixes.7:175
11948 msgid " .map\tmap files for various programs\n"
11952 #: build/C/man7/suffixes.7:176
11954 msgid " .me\tNroff source using the me macro package\n"
11958 #: build/C/man7/suffixes.7:177
11960 msgid " .mf\tMetafont (font generator for TeX) source\n"
11964 #: build/C/man7/suffixes.7:178
11966 msgid " .mgp\tMagicPoint file\n"
11970 #: build/C/man7/suffixes.7:179
11972 msgid " .mm\tsources for B<groff>(1) in mm - format\n"
11976 #: build/C/man7/suffixes.7:180
11978 msgid " .mo\tMessage catalog binary file\n"
11982 #: build/C/man7/suffixes.7:181
11984 msgid " .mod\tModula-2 source for implementation modules\n"
11988 #: build/C/man7/suffixes.7:182
11990 msgid " .mov\t(quicktime) movie\n"
11994 #: build/C/man7/suffixes.7:183
11996 msgid " .mp\tMetapost source\n"
12000 #: build/C/man7/suffixes.7:184
12002 msgid " .mp2\tMPEG Layer 2 (audio) file\n"
12006 #: build/C/man7/suffixes.7:185
12008 msgid " .mp3\tMPEG Layer 3 (audio) file\n"
12012 #: build/C/man7/suffixes.7:186
12014 msgid " .mpeg\tmovie file\n"
12018 #: build/C/man7/suffixes.7:187
12020 msgid " .o\tobject file\n"
12024 #: build/C/man7/suffixes.7:188
12026 msgid " .old\told or backup file\n"
12030 #: build/C/man7/suffixes.7:189
12032 msgid " .orig\tbackup (original) version of a file, from B<patch>(1)\n"
12036 #: build/C/man7/suffixes.7:190
12038 msgid " .out\toutput file, often executable program (a.out)\n"
12042 #: build/C/man7/suffixes.7:191
12044 msgid " .p\tPascal source\n"
12048 #: build/C/man7/suffixes.7:192
12050 msgid " .pag\tdbm data base data file\n"
12054 #: build/C/man7/suffixes.7:193
12056 msgid " .patch\tfile differences for B<patch>(1)\n"
12060 #: build/C/man7/suffixes.7:194
12062 msgid " .pbm\tportable bitmap format\n"
12066 #: build/C/man7/suffixes.7:195
12068 msgid " .pcf\tX11 font files\n"
12072 #: build/C/man7/suffixes.7:196
12074 msgid " .pdf\tAdobe Portable Data Format\n"
12078 #: build/C/man7/suffixes.7:197
12080 msgid "\t(use Acrobat/B<acroread> or B<xpdf>)\n"
12084 #: build/C/man7/suffixes.7:198
12086 msgid " .perl\tPerl source (see .ph, .pl and .pm)\n"
12090 #: build/C/man7/suffixes.7:199
12092 msgid " .pfa\tPostScript font definition files, ASCII format\n"
12096 #: build/C/man7/suffixes.7:200
12098 msgid " .pfb\tPostScript font definition files, binary format\n"
12102 #: build/C/man7/suffixes.7:201
12104 msgid " .pgm\tportable greymap format\n"
12108 #: build/C/man7/suffixes.7:202
12110 msgid " .pgp\tPGP binary data\n"
12114 #: build/C/man7/suffixes.7:203
12116 msgid " .ph\tPerl header file\n"
12120 #: build/C/man7/suffixes.7:204
12122 msgid " .php\tPHP program file\n"
12126 #: build/C/man7/suffixes.7:205
12128 msgid " .php3\tPHP3 program file\n"
12132 #: build/C/man7/suffixes.7:206
12134 msgid " .pid\tFile to store daemon PID (e.g., crond.pid)\n"
12138 #: build/C/man7/suffixes.7:207
12140 msgid " .pl\tTeX property list file or Perl library file\n"
12144 #: build/C/man7/suffixes.7:208
12146 msgid " .pm\tPerl module\n"
12150 #: build/C/man7/suffixes.7:209
12152 msgid " .png\tPortable Network Graphics file\n"
12156 #: build/C/man7/suffixes.7:210
12158 msgid " .po\tMessage catalog source\n"
12162 #: build/C/man7/suffixes.7:211
12164 msgid " .pod\tB<perldoc>(1) file\n"
12168 #: build/C/man7/suffixes.7:212
12170 msgid " .ppm\tportable pixmap format\n"
12174 #: build/C/man7/suffixes.7:213
12176 msgid " .pr\tbitmap source\n"
12180 #: build/C/man7/suffixes.7:214
12182 msgid " .ps\tPostScript file\n"
12186 #: build/C/man7/suffixes.7:215
12188 msgid " .py\tPython source\n"
12192 #: build/C/man7/suffixes.7:216
12194 msgid " .pyc\tcompiled python\n"
12198 #: build/C/man7/suffixes.7:217
12200 msgid " .qt\tquicktime movie\n"
12204 #: build/C/man7/suffixes.7:218
12206 msgid " .r\tRATFOR source (obsolete)\n"
12210 #: build/C/man7/suffixes.7:219
12212 msgid " .rej\tpatches that B<patch>(1) couldn't apply\n"
12216 #: build/C/man7/suffixes.7:220
12218 msgid " .rpm\tRPM software package\n"
12222 #: build/C/man7/suffixes.7:221
12224 msgid " .rtf\tRich Text Format file\n"
12228 #: build/C/man7/suffixes.7:222
12230 msgid " .rules\trules for something\n"
12234 #: build/C/man7/suffixes.7:223
12236 msgid " .s\tassembler source\n"
12240 #: build/C/man7/suffixes.7:224
12242 msgid " .sa\tstub libraries for a.out shared libraries\n"
12246 #: build/C/man7/suffixes.7:225
12248 msgid " .sc\tB<sc>(1) spreadsheet commands\n"
12252 #: build/C/man7/suffixes.7:226
12254 msgid " .scm\tScheme source code\n"
12258 #: build/C/man7/suffixes.7:227
12260 msgid " .sed\tsed source file\n"
12264 #: build/C/man7/suffixes.7:228
12266 msgid " .sgml\tSGML source file\n"
12270 #: build/C/man7/suffixes.7:229
12272 msgid " .sh\tB<sh>(1) scripts\n"
12276 #: build/C/man7/suffixes.7:230
12278 msgid " .shar\tarchive created by the B<shar>(1) utility\n"
12282 #: build/C/man7/suffixes.7:231
12284 msgid " .so\tShared library or dynamically loadable object\n"
12288 #: build/C/man7/suffixes.7:232
12290 msgid " .sql\tSQL source\n"
12294 #: build/C/man7/suffixes.7:233
12296 msgid " .sqml\tSQML schema or query program\n"
12300 #: build/C/man7/suffixes.7:234
12302 msgid " .sty\tLaTeX style files\n"
12306 #: build/C/man7/suffixes.7:235
12308 msgid " .sym\tModula-2 compiled definition modules\n"
12312 #: build/C/man7/suffixes.7:236
12314 msgid " .tar\tarchive created by the B<tar>(1) utility\n"
12318 #: build/C/man7/suffixes.7:237
12320 msgid " .tar.Z\ttar(1) archive compressed with B<compress>(1)\n"
12324 #: build/C/man7/suffixes.7:238
12326 msgid " .tar.bz2\ttar(1) archive compressed with B<bzip2>(1)\n"
12330 #: build/C/man7/suffixes.7:239
12332 msgid " .tar.gz\ttar(1) archive compressed with B<gzip>(1)\n"
12336 #: build/C/man7/suffixes.7:240
12338 msgid " .taz\ttar(1) archive compressed with B<compress>(1)\n"
12342 #: build/C/man7/suffixes.7:241
12344 msgid " .tcl\ttcl source code\n"
12348 #: build/C/man7/suffixes.7:242
12350 msgid " .tex\tTeX or LaTeX source\n"
12354 #: build/C/man7/suffixes.7:243
12356 msgid " .texi\tequivalent to I<.texinfo>\n"
12360 #: build/C/man7/suffixes.7:244
12362 msgid " .texinfo\tTexinfo documentation source\n"
12366 #: build/C/man7/suffixes.7:245
12368 msgid " .text\ttext file\n"
12372 #: build/C/man7/suffixes.7:246
12374 msgid " .tfm\tTeX font metric file\n"
12378 #: build/C/man7/suffixes.7:247
12380 msgid " .tgz\ttar archive compressed with B<gzip>(1)\n"
12384 #: build/C/man7/suffixes.7:248
12386 msgid " .tif\tpoor man's I<.tiff>\n"
12390 #: build/C/man7/suffixes.7:249
12392 msgid " .tiff\tTagged Image File Format\n"
12396 #: build/C/man7/suffixes.7:250
12398 msgid " .tk\ttcl/tk script\n"
12402 #: build/C/man7/suffixes.7:251
12404 msgid " .tmp\ttemporary file\n"
12408 #: build/C/man7/suffixes.7:252
12410 msgid " .tmpl\ttemplate files\n"
12414 #: build/C/man7/suffixes.7:253
12416 msgid " .txt\tequivalent to I<.text>\n"
12420 #: build/C/man7/suffixes.7:254
12422 msgid " .uu\tequivalent to I<.uue>\n"
12426 #: build/C/man7/suffixes.7:255
12428 msgid " .uue\tbinary file encoded with B<uuencode>(1)\n"
12432 #: build/C/man7/suffixes.7:256
12434 msgid " .vf\tTeX virtual font file\n"
12438 #: build/C/man7/suffixes.7:257
12440 msgid " .vpl\tTeX virtual property list file\n"
12444 #: build/C/man7/suffixes.7:258
12446 msgid " .w\tSilvio Levi's CWEB\n"
12450 #: build/C/man7/suffixes.7:259
12452 msgid " .wav\twave sound file\n"
12456 #: build/C/man7/suffixes.7:260
12458 msgid " .web\tDonald Knuth's WEB\n"
12462 #: build/C/man7/suffixes.7:261
12464 msgid " .wml\tSource file for Web Meta Language\n"
12468 #: build/C/man7/suffixes.7:262
12470 msgid " .xbm\tX11 bitmap source\n"
12474 #: build/C/man7/suffixes.7:263
12476 msgid " .xcf\tGIMP graphic\n"
12480 #: build/C/man7/suffixes.7:264
12482 msgid " .xml\teXtended Markup Language file\n"
12486 #: build/C/man7/suffixes.7:265
12488 msgid " .xpm\tX11 pixmap source\n"
12492 #: build/C/man7/suffixes.7:266
12494 msgid " .xs\tPerl xsub file produced by h2xs\n"
12498 #: build/C/man7/suffixes.7:267
12500 msgid " .xsl\tXSL stylesheet\n"
12504 #: build/C/man7/suffixes.7:268
12506 msgid " .y\tB<yacc>(1) or B<bison>(1) (parser generator) files\n"
12510 #: build/C/man7/suffixes.7:269
12512 msgid " .z\tFile compressed using B<pack>(1) (or an old B<gzip>(1))\n"
12516 #: build/C/man7/suffixes.7:270
12518 msgid " .zip\tB<zip>(1) archive\n"
12522 #: build/C/man7/suffixes.7:271
12524 msgid " .zoo\tB<zoo>(1) archive\n"
12528 #: build/C/man7/suffixes.7:272
12530 msgid " ~\tEmacs or B<patch>(1) backup file\n"
12534 #: build/C/man7/suffixes.7:273
12536 msgid " rc\tstartup (`run control') file, e.g., I<.newsrc>\n"
12539 #. type: Plain text
12540 #: build/C/man7/suffixes.7:277
12541 msgid "General UNIX conventions."
12544 #. type: Plain text
12545 #: build/C/man7/suffixes.7:279
12546 msgid "This list is not exhaustive."
12549 #. type: Plain text
12550 #: build/C/man7/suffixes.7:282
12551 msgid "B<file>(1), B<make>(1)"
12555 #: build/C/man3/undocumented.3:29
12557 msgid "UNDOCUMENTED"
12561 #: build/C/man3/undocumented.3:29
12566 #. type: Plain text
12567 #: build/C/man3/undocumented.3:32
12568 msgid "none - undocumented library functions"
12571 #. type: Plain text
12572 #: build/C/man3/undocumented.3:34
12573 msgid "Undocumented library functions"
12576 #. type: Plain text
12577 #: build/C/man3/undocumented.3:37
12579 "This man page mentions those library functions which are implemented in the "
12580 "standard libraries but not yet documented in man pages."
12584 #: build/C/man3/undocumented.3:37
12586 msgid "Solicitation"
12589 #. type: Plain text
12590 #: build/C/man3/undocumented.3:43
12592 "If you have information about these functions, please look in the source "
12593 "code, write a man page (using a style similar to that of the other Linux "
12594 "section 3 man pages), and send it to B<mtk.manpages@gmail.com> for inclusion "
12595 "in the next man page release."
12599 #: build/C/man3/undocumented.3:43
12604 #. .BR chflags (3),
12605 #. .BR fattach (3),
12606 #. .BR fchflags (3),
12608 #. .BR fdetach (3),
12609 #. .BR obstack stuff (3),
12610 #. type: Plain text
12611 #: build/C/man3/undocumented.3:187
12613 "B<authdes_create>(3), B<authdes_getucred>(3), B<authdes_pk_create>(3), "
12614 "B<clntunix_create>(3), B<creat64>(3), B<dn_skipname>(3), B<fcrypt>(3), "
12615 "B<fp_nquery>(3), B<fp_query>(3), B<fp_resstat>(3), B<freading>(3), "
12616 "B<freopen64>(3), B<fseeko64>(3), B<ftello64>(3), B<ftw64>(3), B<fwscanf>(3), "
12617 "B<get_avphys_pages>(3), B<getdirentries64>(3), B<getmsg>(3), "
12618 "B<getnetname>(3), B<get_nprocs>(3), B<get_nprocs_conf>(3), "
12619 "B<get_phys_pages>(3), B<getpublickey>(3), B<getsecretkey>(3), "
12620 "B<h_errlist>(3), B<host2netname>(3), B<hostalias>(3), "
12621 "B<if_freenameindex>(3), B<if_indextoname>(3), B<if_nameindex>(3), "
12622 "B<if_nametoindex>(3), B<inet_nsap_addr>(3), B<inet_nsap_ntoa>(3), "
12623 "B<init_des>(3), B<libc_nls_init>(3), B<lio_listio>(3), B<mstats>(3), "
12624 "B<netname2host>(3), B<netname2user>(3), B<nlist>(3), B<obstack_free>(3), "
12625 "B<parse_printf_format>(3), B<p_cdname>(3), B<p_cdnname>(3), B<p_class>(3), "
12626 "B<p_fqname>(3), B<p_option>(3), B<p_query>(3), B<printf_size>(3), "
12627 "B<printf_size_info>(3), B<p_rr>(3), B<p_time>(3), B<p_type>(3), "
12628 "B<putlong>(3), B<putshort>(3), B<re_compile_fastmap>(3), "
12629 "B<re_compile_pattern>(3), B<register_printf_function>(3), B<re_match>(3), "
12630 "B<re_match_2>(3), B<re_rx_search>(3), B<re_search>(3), B<re_search_2>(3), "
12631 "B<re_set_registers>(3), B<re_set_syntax>(3), B<res_send_setqhook>(3), "
12632 "B<res_send_setrhook>(3), B<ruserpass>(3), B<setfileno>(3), "
12633 "B<sethostfile>(3), B<svc_exit>(3), B<svcudp_enablecache>(3), B<tell>(3), "
12634 "B<tr_break>(3), B<tzsetwall>(3), B<ufc_dofinalperm>(3), B<ufc_doit>(3), "
12635 "B<user2netname>(3), B<vlimit>(3), B<vtimes>(3), B<wcschrnul>(3), "
12636 "B<wcsftime>(3), B<wscanf>(3), B<xdr_authdes_cred>(3), "
12637 "B<xdr_authdes_verf>(3), B<xdr_cryptkeyarg>(3), B<xdr_cryptkeyres>(3), "
12638 "B<xdr_datum>(3), B<xdr_des_block>(3), B<xdr_domainname>(3), "
12639 "B<xdr_getcredres>(3), B<xdr_keybuf>(3), B<xdr_keystatus>(3), "
12640 "B<xdr_mapname>(3), B<xdr_netnamestr>(3), B<xdr_netobj>(3), B<xdr_passwd>(3), "
12641 "B<xdr_peername>(3), B<xdr_rmtcall_args>(3), B<xdr_rmtcallres>(3), "
12642 "B<xdr_unixcred>(3), B<xdr_yp_buf>(3), B<xdr_yp_inaddr>(3), "
12643 "B<xdr_ypbind_binding>(3), B<xdr_ypbind_resp>(3), B<xdr_ypbind_resptype>(3), "
12644 "B<xdr_ypbind_setdom>(3), B<xdr_ypdelete_args>(3), B<xdr_ypmaplist>(3), "
12645 "B<xdr_ypmaplist_str>(3), B<xdr_yppasswd>(3), B<xdr_ypreq_key>(3), "
12646 "B<xdr_ypreq_nokey>(3), B<xdr_ypresp_all>(3), B<xdr_ypresp_all_seq>(3), "
12647 "B<xdr_ypresp_key_val>(3), B<xdr_ypresp_maplist>(3), B<xdr_ypresp_master>(3), "
12648 "B<xdr_ypresp_order>(3), B<xdr_ypresp_val>(3), B<xdr_ypstat>(3), "
12649 "B<xdr_ypupdate_args>(3), B<yp_all>(3), B<yp_bind>(3), B<yperr_string>(3), "
12650 "B<yp_first>(3), B<yp_get_default_domain>(3), B<yp_maplist>(3), "
12651 "B<yp_master>(3), B<yp_match>(3), B<yp_next>(3), B<yp_order>(3), "
12652 "B<ypprot_err>(3), B<yp_unbind>(3), B<yp_update>(3)"
12656 #: build/C/man2/unimplemented.2:27
12658 msgid "UNIMPLEMENTED"
12662 #: build/C/man2/unimplemented.2:27
12667 #. type: Plain text
12668 #: build/C/man2/unimplemented.2:31
12670 "afs_syscall, break, ftime, getpmsg, gtty, lock, madvise1, mpx, prof, profil, "
12671 "putpmsg, security, stty, tuxcall, ulimit, vserver - unimplemented system "
12675 #. type: Plain text
12676 #: build/C/man2/unimplemented.2:33
12677 msgid "Unimplemented system calls."
12680 #. type: Plain text
12681 #: build/C/man2/unimplemented.2:35
12682 msgid "These system calls are not implemented in the Linux 2.6.22 kernel."
12685 #. type: Plain text
12686 #: build/C/man2/unimplemented.2:40
12687 msgid "These system calls always return -1 and set I<errno> to B<ENOSYS>."
12690 #. type: Plain text
12691 #: build/C/man2/unimplemented.2:47
12693 "Note that B<ftime>(3), B<profil>(3) and B<ulimit>(3) are implemented as "
12694 "library functions."
12697 #. type: Plain text
12698 #: build/C/man2/unimplemented.2:56
12700 "Some system calls, like B<alloc_hugepages>(2), B<free_hugepages>(2), "
12701 "B<ioperm>(2), B<iopl>(2), and B<vm86>(2) only exist on certain "
12705 #. type: Plain text
12706 #: build/C/man2/unimplemented.2:64
12708 "Some system calls, like B<ipc>(2), B<create_module>(2), B<init_module>(2), "
12709 "and B<delete_module>(2) only exist when the Linux kernel was built with "
12710 "support for them."
12713 #. type: Plain text
12714 #: build/C/man2/unimplemented.2:66
12715 msgid "B<syscalls>(2)"
12719 #: build/C/man7/units.7:24
12725 #: build/C/man7/units.7:24
12730 #. type: Plain text
12731 #: build/C/man7/units.7:27
12732 msgid "units, kilo, kibi, mega, mebi, giga, gibi - decimal and binary prefixes"
12736 #: build/C/man7/units.7:28
12738 msgid "Decimal prefixes"
12741 #. type: Plain text
12742 #: build/C/man7/units.7:32
12744 "The SI system of units uses prefixes that indicate powers of ten. A "
12745 "kilometer is 1000 meter, and a megawatt is 1000000 watt. Below the standard "
12750 #: build/C/man7/units.7:35 build/C/man7/units.7:76
12752 msgid "Prefix\tName\tValue\n"
12756 #: build/C/man7/units.7:36
12758 msgid "y\tyocto\t10^-24 = 0.000000000000000000000001\n"
12762 #: build/C/man7/units.7:37
12764 msgid "z\tzepto\t10^-21 = 0.000000000000000000001\n"
12768 #: build/C/man7/units.7:38
12770 msgid "a\tatto\t10^-18 = 0.000000000000000001\n"
12774 #: build/C/man7/units.7:39
12776 msgid "f\tfemto\t10^-15 = 0.000000000000001\n"
12780 #: build/C/man7/units.7:40
12782 msgid "p\tpico\t10^-12 = 0.000000000001\n"
12786 #: build/C/man7/units.7:41
12788 msgid "n\tnano\t10^-9 = 0.000000001\n"
12792 #: build/C/man7/units.7:42
12794 msgid "u\tmicro\t10^-6 = 0.000001\n"
12798 #: build/C/man7/units.7:43
12800 msgid "m\tmilli\t10^-3 = 0.001\n"
12804 #: build/C/man7/units.7:44
12806 msgid "c\tcenti\t10^-2 = 0.01\n"
12810 #: build/C/man7/units.7:45
12812 msgid "d\tdeci\t10^-1 = 0.1\n"
12816 #: build/C/man7/units.7:46
12818 msgid "da\tdeka\t10^ 1 = 10\n"
12822 #: build/C/man7/units.7:47
12824 msgid "h\thecto\t10^ 2 = 100\n"
12828 #: build/C/man7/units.7:48
12830 msgid "k\tkilo\t10^ 3 = 1000\n"
12834 #: build/C/man7/units.7:49
12836 msgid "M\tmega\t10^ 6 = 1000000\n"
12840 #: build/C/man7/units.7:50
12842 msgid "G\tgiga\t10^ 9 = 1000000000\n"
12846 #: build/C/man7/units.7:51
12848 msgid "T\ttera\t10^12 = 1000000000000\n"
12852 #: build/C/man7/units.7:52
12854 msgid "P\tpeta\t10^15 = 1000000000000000\n"
12858 #: build/C/man7/units.7:53
12860 msgid "E\texa\t10^18 = 1000000000000000000\n"
12864 #: build/C/man7/units.7:54
12866 msgid "Z\tzetta\t10^21 = 1000000000000000000000\n"
12870 #: build/C/man7/units.7:55
12872 msgid "Y\tyotta\t10^24 = 1000000000000000000000000\n"
12875 #. type: Plain text
12876 #: build/C/man7/units.7:62
12878 "The symbol for micro is the Greek letter mu, often written u in an ASCII "
12879 "context where this Greek letter is not available. See also"
12882 #. type: Plain text
12883 #: build/C/man7/units.7:65
12884 msgid "http://physics.nist.gov/cuu/Units/prefixes.html"
12888 #: build/C/man7/units.7:66
12890 msgid "Binary prefixes"
12893 #. type: Plain text
12894 #: build/C/man7/units.7:73
12896 "The binary prefixes resemble the decimal ones, but have an additional "
12897 "\\(aqi\\(aq (and \"Ki\" starts with a capital \\(aqK\\(aq). The names are "
12898 "formed by taking the first syllable of the names of the decimal prefix with "
12899 "roughly the same size, followed by \"bi\" for \"binary\"."
12903 #: build/C/man7/units.7:77
12905 msgid "Ki\tkibi\t2^10 = 1024\n"
12909 #: build/C/man7/units.7:78
12911 msgid "Mi\tmebi\t2^20 = 1048576\n"
12915 #: build/C/man7/units.7:79
12917 msgid "Gi\tgibi\t2^30 = 1073741824\n"
12921 #: build/C/man7/units.7:80
12923 msgid "Ti\ttebi\t2^40 = 1099511627776\n"
12927 #: build/C/man7/units.7:81
12929 msgid "Pi\tpebi\t2^50 = 1125899906842624\n"
12933 #: build/C/man7/units.7:82
12935 msgid "Ei\texbi\t2^60 = 1152921504606846976\n"
12938 #. type: Plain text
12939 #: build/C/man7/units.7:87
12943 #. type: Plain text
12944 #: build/C/man7/units.7:90
12945 msgid "http://physics.nist.gov/cuu/Units/binary.html"
12949 #: build/C/man7/units.7:91
12954 #. type: Plain text
12955 #: build/C/man7/units.7:96
12957 "Before these binary prefixes were introduced, it was fairly common to use "
12958 "k=1000 and K=1024, just like b=bit, B=byte. Unfortunately, the M is capital "
12959 "already, and cannot be capitalized to indicate binary-ness."
12962 #. type: Plain text
12963 #: build/C/man7/units.7:107
12965 "At first that didn't matter too much, since memory modules and disks came in "
12966 "sizes that were powers of two, so everyone knew that in such contexts "
12967 "\"kilobyte\" and \"megabyte\" meant 1024 and 1048576 bytes, respectively. "
12968 "What originally was a sloppy use of the prefixes \"kilo\" and \"mega\" "
12969 "started to become regarded as the \"real true meaning\" when computers were "
12970 "involved. But then disk technology changed, and disk sizes became arbitrary "
12971 "numbers. After a period of uncertainty all disk manufacturers settled on "
12972 "the standard, namely k=1000, M=1000k, G=1000M."
12975 #. also common: 14.4k modem
12976 #. type: Plain text
12977 #: build/C/man7/units.7:114
12979 "The situation was messy: in the 14k4 modems, k=1000; in the 1.44MB "
12980 "diskettes, M=1024000; etc. In 1998 the IEC approved the standard that "
12981 "defines the binary prefixes given above, enabling people to be precise and "
12985 #. type: Plain text
12986 #: build/C/man7/units.7:116
12987 msgid "Thus, today, MB = 1000000B and MiB = 1048576B."
12990 #. type: Plain text
12991 #: build/C/man7/units.7:120
12993 "In the free software world programs are slowly being changed to conform. "
12994 "When the Linux kernel boots and says"
12997 #. type: Plain text
12998 #: build/C/man7/units.7:124
13000 msgid "hda: 120064896 sectors (61473 MB) w/2048KiB Cache\n"
13003 #. type: Plain text
13004 #: build/C/man7/units.7:128
13005 msgid "the MB are megabytes and the KiB are kibibytes."
13009 #: build/C/man7/mdoc.samples.7:39
13011 msgid "December 30, 1993"
13015 #: build/C/man7/mdoc.samples.7:41
13017 msgid "MDOC.SAMPLES 7"
13020 #. type: Plain text
13021 #: build/C/man7/mdoc.samples.7:44
13022 msgid "E<.Nm mdoc.samples>"
13026 #: build/C/man7/mdoc.samples.7:44
13028 msgid "tutorial sampler for writing"
13031 #. type: Plain text
13032 #: build/C/man7/mdoc.samples.7:48
13033 msgid "E<.Bx> manuals with E<.Nm \\-mdoc>"
13036 #. type: Plain text
13037 #: build/C/man7/mdoc.samples.7:50
13038 msgid "E<.Nm man mdoc.samples>"
13041 #. type: Plain text
13042 #: build/C/man7/mdoc.samples.7:96
13044 "A tutorial sampler for writing E<.Bx> manual pages with the E<.Nm \\-mdoc> "
13045 "macro package, a E<.Em content Ns \\-based> and E<.Em domain Ns \\-based> "
13046 "formatting package for E<.Xr troff 1>. Its predecessor, the E<.Xr \\-man 7> "
13047 "package, addressed page layout leaving the manipulation of fonts and other "
13048 "typesetting details to the individual author. In E<.Nm \\-mdoc>, page "
13049 "layout macros make up the E<.Em \"page structure domain\"> which consists of "
13050 "macros for titles, section headers, displays and lists. Essentially items "
13051 "which affect the physical position of text on a formatted page. In addition "
13052 "to the page structure domain, there are two more domains, the manual domain "
13053 "and the general text domain. The general text domain is defined as macros "
13054 "which perform tasks such as quoting or emphasizing pieces of text. The "
13055 "manual domain is defined as macros that are a subset of the day to day "
13056 "informal language used to describe commands, routines and related E<.Bx> "
13057 "files. Macros in the manual domain handle command names, command-line "
13058 "arguments and options, function names, function parameters, pathnames, "
13059 "variables, cross references to other manual pages, and so on. These domain "
13060 "items have value for both the author and the future user of the manual "
13061 "page. It is hoped the consistency gained across the manual set will provide "
13062 "easier translation to future documentation tools."
13065 #. type: Plain text
13066 #: build/C/man7/mdoc.samples.7:103
13068 "Throughout the E<.Ux> manual pages, a manual entry is simply referred to as "
13069 "a man page, regardless of actual length and without sexist intention."
13073 #: build/C/man7/mdoc.samples.7:103
13075 msgid "GETTING STARTED"
13078 #. type: Plain text
13079 #: build/C/man7/mdoc.samples.7:109
13081 "Since a tutorial document is normally read when a person desires to use the "
13082 "material immediately, the assumption has been made that the user of this "
13083 "document may be impatient. The material presented in the remained of this "
13084 "document is outlined as follows:"
13087 #. type: Plain text
13088 #: build/C/man7/mdoc.samples.7:112
13089 msgid "E<.Tn \"TROFF IDIOSYNCRASIES\">"
13093 #: build/C/man7/mdoc.samples.7:113
13095 msgid "\"Macro Usage\" ."
13099 #: build/C/man7/mdoc.samples.7:114
13101 msgid "\"Passing Space Characters in an Argument\" ."
13105 #: build/C/man7/mdoc.samples.7:115
13107 msgid "\"Trailing Blank Space Characters (a warning)\" ."
13111 #: build/C/man7/mdoc.samples.7:116
13113 msgid "\"Escaping Special Characters\" ."
13116 #. type: Plain text
13117 #: build/C/man7/mdoc.samples.7:120
13118 msgid "E<.Tn \"THE ANATOMY OF A MAN PAGE\">"
13122 #: build/C/man7/mdoc.samples.7:121
13124 msgid "\"A manual page template\" ."
13127 #. type: Plain text
13128 #: build/C/man7/mdoc.samples.7:125
13129 msgid "E<.Tn \"TITLE MACROS\">."
13132 #. type: Plain text
13133 #: build/C/man7/mdoc.samples.7:127
13134 msgid "E<.Tn \"INTRODUCTION OF MANUAL AND GENERAL TEXT DOMAINS\">."
13138 #: build/C/man7/mdoc.samples.7:128
13140 msgid "\"What's in a name...\" ."
13144 #: build/C/man7/mdoc.samples.7:129
13146 msgid "\"General Syntax\" ."
13149 #. type: Plain text
13150 #: build/C/man7/mdoc.samples.7:133
13151 msgid "E<.Tn \"MANUAL DOMAIN\">"
13155 #: build/C/man7/mdoc.samples.7:134
13157 msgid "Addresses ."
13161 #: build/C/man7/mdoc.samples.7:135
13163 msgid "\"Author name\" ."
13167 #: build/C/man7/mdoc.samples.7:136
13169 msgid "Arguments ."
13173 #: build/C/man7/mdoc.samples.7:137
13175 msgid "\"Configuration Declarations (section four only)\" ."
13179 #: build/C/man7/mdoc.samples.7:138
13181 msgid "\"Command Modifier\" ."
13185 #: build/C/man7/mdoc.samples.7:139
13187 msgid "\"Defined Variables\" ."
13191 #: build/C/man7/mdoc.samples.7:140
13193 msgid "\"Errno's (Section two only)\" ."
13197 #: build/C/man7/mdoc.samples.7:141
13199 msgid "\"Environment Variables\" ."
13203 #: build/C/man7/mdoc.samples.7:142
13205 msgid "\"Function Argument\" ."
13209 #: build/C/man7/mdoc.samples.7:143
13211 msgid "\"Function Declaration\" ."
13215 #: build/C/man7/mdoc.samples.7:144
13221 #: build/C/man7/mdoc.samples.7:145
13223 msgid "\"Functions (library routines)\" ."
13227 #: build/C/man7/mdoc.samples.7:146
13229 msgid "\"Function Types\" ."
13232 #. .It "Header File (including source code)" .
13234 #: build/C/man7/mdoc.samples.7:148
13236 msgid "\"Interactive Commands\" ."
13240 #: build/C/man7/mdoc.samples.7:149
13246 #: build/C/man7/mdoc.samples.7:150
13252 #: build/C/man7/mdoc.samples.7:151
13254 msgid "Pathnames ."
13258 #: build/C/man7/mdoc.samples.7:152
13260 msgid "Variables ."
13264 #: build/C/man7/mdoc.samples.7:153
13266 msgid "\"Cross References\" ."
13269 #. type: Plain text
13270 #: build/C/man7/mdoc.samples.7:157
13271 msgid "E<.Tn \"GENERAL TEXT DOMAIN\">"
13275 #: build/C/man7/mdoc.samples.7:158
13277 msgid "\"AT&T Macro\" ."
13281 #: build/C/man7/mdoc.samples.7:159
13283 msgid "\"BSD Macro\" ."
13287 #: build/C/man7/mdoc.samples.7:160
13289 msgid "\"FreeBSD Macro\" ."
13293 #: build/C/man7/mdoc.samples.7:161
13295 msgid "\"UNIX Macro\" ."
13299 #: build/C/man7/mdoc.samples.7:162
13301 msgid "Enclosure/Quoting Macros"
13305 #: build/C/man7/mdoc.samples.7:164
13307 msgid "\"Angle Bracket Quote/Enclosure\" ."
13311 #: build/C/man7/mdoc.samples.7:165
13313 msgid "\"Bracket Quotes/Enclosure\" ."
13317 #: build/C/man7/mdoc.samples.7:166
13319 msgid "\"Double Quote macro/Enclosure\" ."
13323 #: build/C/man7/mdoc.samples.7:167
13325 msgid "\"Parenthesis Quote/Enclosure\" ."
13329 #: build/C/man7/mdoc.samples.7:168
13331 msgid "\"Single Quotes/Enclosure\" ."
13335 #: build/C/man7/mdoc.samples.7:169
13337 msgid "\"Prefix Macro\" ."
13341 #: build/C/man7/mdoc.samples.7:171
13343 msgid "\"No\\-Op or Normal Text Macro\" ."
13347 #: build/C/man7/mdoc.samples.7:172
13349 msgid "\"No Space Macro\" ."
13353 #: build/C/man7/mdoc.samples.7:173
13355 msgid "\"Section Cross References\" ."
13359 #: build/C/man7/mdoc.samples.7:174
13361 msgid "\"References and Citations\" ."
13365 #: build/C/man7/mdoc.samples.7:175
13367 msgid "Return Values (sections two and three only)"
13371 #: build/C/man7/mdoc.samples.7:176
13373 msgid "\"Trade Names (Acronyms and Type Names)\" ."
13377 #: build/C/man7/mdoc.samples.7:177
13379 msgid "\"Extended Arguments\" ."
13382 #. type: Plain text
13383 #: build/C/man7/mdoc.samples.7:181
13384 msgid "E<.Tn \"PAGE STRUCTURE DOMAIN\">"
13388 #: build/C/man7/mdoc.samples.7:182
13390 msgid "\"Section Headers\" ."
13394 #: build/C/man7/mdoc.samples.7:183
13396 msgid "\"Paragraphs and Line Spacing\" ."
13400 #: build/C/man7/mdoc.samples.7:184
13406 #: build/C/man7/mdoc.samples.7:185
13412 #: build/C/man7/mdoc.samples.7:186
13414 msgid "\"Font Modes (Emphasis, Literal, and Symbolic)\" ."
13418 #: build/C/man7/mdoc.samples.7:187
13420 msgid "\"Lists and Columns\" ."
13423 #. type: Plain text
13424 #: build/C/man7/mdoc.samples.7:191
13425 msgid "E<.Tn \"PREDEFINED STRINGS\">"
13428 #. type: Plain text
13429 #: build/C/man7/mdoc.samples.7:193
13430 msgid "E<.Tn \"DIAGNOSTICS\">"
13433 #. type: Plain text
13434 #: build/C/man7/mdoc.samples.7:195
13435 msgid "E<.Tn \"FORMATTING WITH GROFF, TROFF AND NROFF\">"
13438 #. type: Plain text
13439 #: build/C/man7/mdoc.samples.7:197
13440 msgid "E<.Tn \"BUGS\">"
13444 #: build/C/man7/mdoc.samples.7:199
13446 msgid "TROFF IDIOSYNCRASIES"
13449 #. type: Plain text
13450 #: build/C/man7/mdoc.samples.7:213
13452 "The E<.Nm \\-mdoc> package attempts to simplify the process of writing a man "
13453 "page. Theoretically, one should not have to learn the dirty details of "
13454 "E<.Xr troff 1> to use E<.Nm \\-mdoc>; however, there are a few limitations "
13455 "which are unavoidable and best gotten out of the way. And, too, be "
13456 "forewarned, this package is E<.Em not> fast."
13460 #: build/C/man7/mdoc.samples.7:213
13462 msgid "Macro Usage"
13465 #. type: Plain text
13466 #: build/C/man7/mdoc.samples.7:238
13468 "As in E<.Xr troff 1>, a macro is called by placing a E<.Ql \\&.> (dot "
13469 "character) at the beginning of a line followed by the two character name "
13470 "for the macro. Arguments may follow the macro separated by spaces. It is "
13471 "the dot character at the beginning of the line which causes E<.Xr troff 1> "
13472 "to interpret the next two characters as a macro name. To place a E<.Ql "
13473 "\\&.> (dot character) at the beginning of a line in some context other than "
13474 "a macro invocation, precede the E<.Ql \\&.> (dot) with the E<.Ql \\e&> "
13475 "escape sequence. The E<.Ql \\e&> translates literally to a zero width "
13476 "space, and is never displayed in the output."
13479 #. type: Plain text
13480 #: build/C/man7/mdoc.samples.7:253
13482 "In general, E<.Xr troff 1> macros accept up to nine arguments, any extra "
13483 "arguments are ignored. Most macros in E<.Nm \\-mdoc> accept nine arguments "
13484 "and, in limited cases, arguments may be continued or extended on the next "
13485 "line (See E<.Sx Extensions>). A few macros handle quoted arguments (see "
13486 "E<.Sx Passing Space Characters in an Argument> below)."
13489 #. type: Plain text
13490 #: build/C/man7/mdoc.samples.7:280
13492 "Most of the E<.Nm \\-mdoc> general text domain and manual domain macros are "
13493 "special in that their argument lists are E<.Em parsed> for callable macro "
13494 "names. This means an argument on the argument list which matches a general "
13495 "text or manual domain macro name and is determined to be callable will be "
13496 "executed or called when it is processed. In this case the argument, "
13497 "although the name of a macro, is not preceded by a E<.Ql \\&.> (dot). It is "
13498 "in this manner that many macros are nested; for example the option macro, "
13499 "E<.Ql \\&.Op>, may E<.Em call> the flag and argument macros, E<.Ql \\&Fl> "
13500 "and E<.Ql \\&Ar>, to specify an optional flag with an argument:"
13504 #: build/C/man7/mdoc.samples.7:281
13506 msgid "Op Fl s Ar bytes"
13509 #. type: Plain text
13510 #: build/C/man7/mdoc.samples.7:284
13511 msgid "is produced by E<.Li \\&.Op \\&Fl s \\&Ar bytes>"
13514 #. type: Plain text
13515 #: build/C/man7/mdoc.samples.7:291
13517 "To prevent a two character string from being interpreted as a macro name, "
13518 "precede the string with the escape sequence E<.Ql \\e&>:"
13522 #: build/C/man7/mdoc.samples.7:292
13524 msgid "Op \\&Fl s \\&Ar bytes"
13527 #. type: Plain text
13528 #: build/C/man7/mdoc.samples.7:295
13529 msgid "is produced by E<.Li \\&.Op \\e&Fl s \\e&Ar bytes>"
13532 #. type: Plain text
13533 #: build/C/man7/mdoc.samples.7:316
13535 "Here the strings E<.Ql \\&Fl> and E<.Ql \\&Ar> are not interpreted as "
13536 "macros. Macros whose argument lists are parsed for callable arguments are "
13537 "referred to as parsed and macros which may be called from an argument list "
13538 "are referred to as callable throughout this document and in the companion "
13539 "quick reference manual E<.Xr mdoc 7>. This is a technical E<.Em faux pas> "
13540 "as almost all of the macros in E<.Nm \\-mdoc> are parsed, but as it was "
13541 "cumbersome to constantly refer to macros as being callable and being able to "
13542 "call other macros, the term parsed has been used."
13546 #: build/C/man7/mdoc.samples.7:316
13548 msgid "Passing Space Characters in an Argument"
13551 #. type: Plain text
13552 #: build/C/man7/mdoc.samples.7:334
13554 "Sometimes it is desirable to give as one argument a string containing one or "
13555 "more blank space characters. This may be necessary to defeat the nine "
13556 "argument limit or to specify arguments to macros which expect particular "
13557 "arrangement of items in the argument list. For example, the function macro "
13558 "E<.Ql \\&.Fn> expects the first argument to be the name of a function and "
13559 "any remaining arguments to be function parameters. As E<.Tn \"ANSI C\"> "
13560 "stipulates the declaration of function parameters in the parenthesized "
13561 "parameter list, each parameter is guaranteed to be at minimum a two word "
13562 "string. For example, E<.Fa int foo>."
13565 #. type: Plain text
13566 #: build/C/man7/mdoc.samples.7:349
13568 "There are two possible ways to pass an argument which contains an embedded "
13569 "space. E<.Em Implementation note>: Unfortunately, the most convenient way "
13570 "of passing spaces in between quotes by reassigning individual arguments "
13571 "before parsing was fairly expensive speed wise and space wise to implement "
13572 "in all the macros for E<.Tn AT&T> E<.Xr troff>. It is not expensive for "
13573 "E<.Xr groff> but for the sake of portability, has been limited to the "
13574 "following macros which need it the most:"
13578 #: build/C/man7/mdoc.samples.7:351
13583 #. type: Plain text
13584 #: build/C/man7/mdoc.samples.7:354
13585 msgid "Configuration declaration (section 4 E<.Sx SYNOPSIS>)"
13589 #: build/C/man7/mdoc.samples.7:354
13594 #. type: Plain text
13595 #: build/C/man7/mdoc.samples.7:356
13596 msgid "Begin list (for the width specifier)."
13600 #: build/C/man7/mdoc.samples.7:356
13605 #. type: Plain text
13606 #: build/C/man7/mdoc.samples.7:358
13607 msgid "Emphasized text."
13611 #: build/C/man7/mdoc.samples.7:358
13616 #. type: Plain text
13617 #: build/C/man7/mdoc.samples.7:360
13618 msgid "Functions (sections two and four)."
13622 #: build/C/man7/mdoc.samples.7:360
13627 #. type: Plain text
13628 #: build/C/man7/mdoc.samples.7:362
13629 msgid "List items."
13633 #: build/C/man7/mdoc.samples.7:362
13638 #. type: Plain text
13639 #: build/C/man7/mdoc.samples.7:364
13640 msgid "Literal text."
13644 #: build/C/man7/mdoc.samples.7:364
13649 #. type: Plain text
13650 #: build/C/man7/mdoc.samples.7:366
13651 msgid "Symbolic text."
13655 #: build/C/man7/mdoc.samples.7:366
13660 #. type: Plain text
13661 #: build/C/man7/mdoc.samples.7:368
13662 msgid "Book titles."
13666 #: build/C/man7/mdoc.samples.7:368
13671 #. type: Plain text
13672 #: build/C/man7/mdoc.samples.7:370
13673 msgid "Journal names."
13677 #: build/C/man7/mdoc.samples.7:370
13682 #. type: Plain text
13683 #: build/C/man7/mdoc.samples.7:372
13684 msgid "Optional notes for a reference."
13688 #: build/C/man7/mdoc.samples.7:372
13693 #. type: Plain text
13694 #: build/C/man7/mdoc.samples.7:374
13695 msgid "Report title (in a reference)."
13699 #: build/C/man7/mdoc.samples.7:374
13704 #. type: Plain text
13705 #: build/C/man7/mdoc.samples.7:376
13706 msgid "Title of article in a book or journal."
13709 #. type: Plain text
13710 #: build/C/man7/mdoc.samples.7:393
13712 "One way of passing a string containing blank spaces is to use the hard or "
13713 "unpaddable space character E<.Ql \\e\\ >, that is, a blank space preceded by "
13714 "the escape character E<.Ql \\e>. This method may be used with any macro but "
13715 "has the side effect of interfering with the adjustment of text over the "
13716 "length of a line. E<.Xr Troff> sees the hard space as if it were any other "
13717 "printable character and cannot split the string into blank or newline "
13718 "separated pieces as one would expect. The method is useful for strings "
13719 "which are not expected to overlap a line boundary. For example:"
13723 #: build/C/man7/mdoc.samples.7:394
13725 msgid "Fn fetch char\\ *str"
13728 #. type: Plain text
13729 #: build/C/man7/mdoc.samples.7:397
13730 msgid "is created by E<.Ql \\&.Fn fetch char\\e *str>"
13734 #: build/C/man7/mdoc.samples.7:397
13736 msgid "Fn fetch \"char *str\""
13739 #. type: Plain text
13740 #: build/C/man7/mdoc.samples.7:400
13741 msgid "can also be created by E<.Ql \\&.Fn fetch \"\\*qchar *str\\*q\">"
13744 #. type: Plain text
13745 #: build/C/man7/mdoc.samples.7:409
13747 "If the E<.Ql \\e> or quotes were omitted, E<.Ql \\&.Fn> would see three "
13748 "arguments and the result would be:"
13752 #: build/C/man7/mdoc.samples.7:410
13754 msgid "Fn fetch char *str"
13757 #. type: Plain text
13758 #: build/C/man7/mdoc.samples.7:416
13760 "For an example of what happens when the parameter list overlaps a newline "
13761 "boundary, see the E<.Sx BUGS> section."
13765 #: build/C/man7/mdoc.samples.7:416
13767 msgid "Trailing Blank Space Characters"
13770 #. type: Plain text
13771 #: build/C/man7/mdoc.samples.7:429
13773 "E<.Xr Troff> can be confused by blank space characters at the end of a "
13774 "line. It is a wise preventive measure to globally remove all blank spaces "
13775 "from E<lt>blank-spaceE<gt>E<lt>end-of-lineE<gt> character sequences. Should "
13776 "the need arise to force a blank character at the end of a line, it may be "
13777 "forced with an unpaddable space and the E<.Ql \\e&> escape character. For "
13778 "example, E<.Ql string\\e\\ \\e&>."
13782 #: build/C/man7/mdoc.samples.7:429
13784 msgid "Escaping Special Characters"
13787 #. type: Plain text
13788 #: build/C/man7/mdoc.samples.7:441
13790 "Special characters like the newline character E<.Ql \\en>, are handled by "
13791 "replacing the E<.Ql \\e> with E<.Ql \\ee> (e.g., E<.Ql \\een>) to preserve "
13796 #: build/C/man7/mdoc.samples.7:441
13798 msgid "THE ANATOMY OF A MAN PAGE"
13801 #. type: Plain text
13802 #: build/C/man7/mdoc.samples.7:448
13804 "The body of a man page is easily constructed from a basic template found in "
13805 "the file E<.Pa /usr/share/misc/mdoc.template>. Several example man pages "
13806 "can also be found in E<.Pa /usr/share/examples/mdoc>."
13810 #: build/C/man7/mdoc.samples.7:449
13812 msgid "A manual page template"
13815 #. type: Plain text
13816 #: build/C/man7/mdoc.samples.7:480
13819 "\\&.\\e\" The following requests are required for all man pages.\n"
13820 "\\&.Dd Month day, year\n"
13821 "\\&.Os OPERATING_SYSTEM [version/release]\n"
13822 "\\&.Dt DOCUMENT_TITLE [section number] [volume]\n"
13825 "\\&.Nd one line description of name\n"
13826 "\\&.Sh SYNOPSIS\n"
13827 "\\&.Sh DESCRIPTION\n"
13828 "\\&.\\e\" The following requests should be uncommented and\n"
13829 "\\&.\\e\" used where appropriate. This next request is\n"
13830 "\\&.\\e\" for sections 2 and 3 function return values only.\n"
13831 "\\&.\\e\" .Sh RETURN VALUE\n"
13832 "\\&.\\e\" This next request is for sections 1, 6, 7 & 8 only\n"
13833 "\\&.\\e\" .Sh ENVIRONMENT\n"
13834 "\\&.\\e\" .Sh FILES\n"
13835 "\\&.\\e\" .Sh EXAMPLES\n"
13836 "\\&.\\e\" This next request is for sections 1, 6, 7 & 8 only\n"
13837 "\\&.\\e\" (command return values (to shell) and\n"
13838 "\\&.\\e\"\t fprintf/stderr type diagnostics)\n"
13839 "\\&.\\e\" .Sh DIAGNOSTICS\n"
13840 "\\&.\\e\" The next request is for sections 2 and 3 error\n"
13841 "\\&.\\e\" and signal handling only.\n"
13842 "\\&.\\e\" .Sh ERRORS\n"
13843 "\\&.\\e\" .Sh SEE ALSO\n"
13844 "\\&.\\e\" .Sh CONFORMING TO\n"
13845 "\\&.\\e\" .Sh HISTORY\n"
13846 "\\&.\\e\" .Sh AUTHORS\n"
13847 "\\&.\\e\" .Sh BUGS\n"
13850 #. type: Plain text
13851 #: build/C/man7/mdoc.samples.7:494
13853 "The first items in the template are the macros E<.Pq Li \\&.Dd , \\&.Os , "
13854 "\\&.Dt>; the document date, the operating system the man page or subject "
13855 "source is developed or modified for, and the man page title E<.Pq Em in "
13856 "upper case> along with the section of the manual the page belongs in. These "
13857 "macros identify the page, and are discussed below in E<.Sx TITLE MACROS>."
13860 #. type: Plain text
13861 #: build/C/man7/mdoc.samples.7:513
13863 "The remaining items in the template are section headers E<.Pq Li \\&.Sh>; of "
13864 "which E<.Sx NAME>, E<.Sx SYNOPSIS> and E<.Sx DESCRIPTION> are mandatory. "
13865 "The headers are discussed in E<.Sx PAGE STRUCTURE DOMAIN>, after "
13866 "presentation of E<.Sx MANUAL DOMAIN>. Several content macros are used to "
13867 "demonstrate page layout macros; reading about content macros before page "
13868 "layout macros is recommended."
13872 #: build/C/man7/mdoc.samples.7:513
13874 msgid "TITLE MACROS"
13877 #. type: Plain text
13878 #: build/C/man7/mdoc.samples.7:522
13880 "The title macros are the first portion of the page structure domain, but are "
13881 "presented first and separate for someone who wishes to start writing a man "
13882 "page yesterday. Three header macros designate the document title or manual "
13883 "page title, the operating system, and the date of authorship. These macros "
13884 "are one called once at the very beginning of the document and are used to "
13885 "construct the headers and footers only."
13889 #: build/C/man7/mdoc.samples.7:523
13891 msgid "Li \\&.Dt DOCUMENT_TITLE section# [volume]"
13895 #. USD UNIX User's Supplementary Documents
13897 #. PS1 UNIX Programmer's Supplementary Documents
13898 #. type: Plain text
13899 #: build/C/man7/mdoc.samples.7:537
13901 "The document title is the subject of the man page and must be in E<.Tn "
13902 "CAPITALS> due to troff limitations. The section number may be 1,\\ ...,\\ "
13903 "8, and if it is specified, the volume title may be omitted. A volume title "
13904 "may be arbitrary or one of the following:"
13908 #: build/C/man7/mdoc.samples.7:539
13910 msgid "Li \"AMD\tUNIX\" Ancestral Manual Documents"
13914 #: build/C/man7/mdoc.samples.7:540
13916 msgid "Li \"SMM\tUNIX\" System Manager's Manual"
13920 #: build/C/man7/mdoc.samples.7:541
13922 msgid "Li \"URM\tUNIX\" Reference Manual"
13926 #: build/C/man7/mdoc.samples.7:542
13928 msgid "Li \"PRM\tUNIX\" Programmer's Manual"
13932 #. MMI UNIX Manual Master Index
13934 #. CON UNIX Contributed Software Manual
13936 #. LOC UNIX Local Manual
13937 #. type: Plain text
13938 #: build/C/man7/mdoc.samples.7:558
13940 "The default volume labeling is E<.Li URM> for sections 1, 6, and 7; E<.Li "
13941 "SMM> for section 8; E<.Li PRM> for sections 2, 3, 4, and 5."
13945 #: build/C/man7/mdoc.samples.7:558
13947 msgid "Li \\&.Os operating_system release#"
13950 #. type: Plain text
13951 #: build/C/man7/mdoc.samples.7:571
13953 "The name of the operating system should be the common acronym, for example, "
13954 "E<.Tn BSD> or E<.Tn FreeBSD> or E<.Tn ATT>. The release should be the "
13955 "standard release nomenclature for the system specified, for example, 4.3, "
13956 "4.3+Tahoe, V.3, V.4. Unrecognized arguments are displayed as given in the "
13957 "page footer. For instance, a typical footer might be:"
13961 #: build/C/man7/mdoc.samples.7:572
13963 msgid "\\&.Os 4.3BSD"
13966 #. type: Plain text
13967 #: build/C/man7/mdoc.samples.7:575
13972 #: build/C/man7/mdoc.samples.7:575
13974 msgid "\\&.Os FreeBSD 2.2"
13977 #. type: Plain text
13978 #: build/C/man7/mdoc.samples.7:578
13979 msgid "or for a locally produced set"
13983 #: build/C/man7/mdoc.samples.7:579
13985 msgid "\\&.Os CS Department"
13988 #. type: Plain text
13989 #: build/C/man7/mdoc.samples.7:594
13991 "The Berkeley default, E<.Ql \\&.Os> without an argument, has been defined as "
13992 "E<.Tn BSD> in the site-specific file E<.Pa "
13993 "/usr/share/tmac/mdoc/doc-common>. It really should default to E<.Tn "
13994 "LOCAL>. Note, if the E<.Ql \\&.Os> macro is not present, the bottom left "
13995 "corner of the page will be ugly."
13999 #: build/C/man7/mdoc.samples.7:594
14001 msgid "Li \\&.Dd month day, year"
14004 #. type: Plain text
14005 #: build/C/man7/mdoc.samples.7:596
14006 msgid "The date should be written formally:"
14010 #: build/C/man7/mdoc.samples.7:598
14012 msgid "January 25, 1989"
14016 #: build/C/man7/mdoc.samples.7:600
14018 msgid "INTRODUCTION OF MANUAL AND GENERAL TEXT DOMAINS"
14022 #: build/C/man7/mdoc.samples.7:601
14024 msgid "What's in a name..."
14027 #. type: Plain text
14028 #: build/C/man7/mdoc.samples.7:618
14030 "The manual domain macro names are derived from the day to day informal "
14031 "language used to describe commands, subroutines and related files. Slightly "
14032 "different variations of this language are used to describe the three "
14033 "different aspects of writing a man page. First, there is the description of "
14034 "E<.Nm \\-mdoc> macro request usage. Second is the description of a E<.Ux> "
14035 "command E<.Em with> E<.Nm \\-mdoc> macros and third, the description of a "
14036 "command to a user in the verbal sense; that is, discussion of a command in "
14037 "the text of a man page."
14040 #. type: Plain text
14041 #: build/C/man7/mdoc.samples.7:623
14043 "In the first case, E<.Xr troff 1> macros are themselves a type of command; "
14044 "the general syntax for a troff command is:"
14047 #. type: Plain text
14048 #: build/C/man7/mdoc.samples.7:625
14050 msgid "\\&.Va argument1 argument2 ... argument9\n"
14053 #. type: Plain text
14054 #: build/C/man7/mdoc.samples.7:639
14056 "The E<.Ql \\&.Va> is a macro command or request, and anything following it "
14057 "is an argument to be processed. In the second case, the description of a "
14058 "E<.Ux> command using the content macros is a bit more involved; a typical "
14059 "E<.Sx SYNOPSIS> command line might be displayed as:"
14062 #. type: Plain text
14063 #: build/C/man7/mdoc.samples.7:643
14068 "E<.Ar infile outfile>\n"
14071 #. type: Plain text
14072 #: build/C/man7/mdoc.samples.7:663
14074 "Here, E<.Nm filter> is the command name and the bracketed string E<.Fl flag> "
14075 "is a E<.Em flag> argument designated as optional by the option brackets. In "
14076 "E<.Nm \\-mdoc> terms, E<.Ar infile> and E<.Ar outfile> are called E<.Em "
14077 "arguments>. The macros which formatted the above example:"
14080 #. type: Plain text
14081 #: build/C/man7/mdoc.samples.7:667
14085 "\\&.Op \\&Fl flag\n"
14086 "\\&.Ar infile outfile\n"
14089 #. type: Plain text
14090 #: build/C/man7/mdoc.samples.7:681
14092 "In the third case, discussion of commands and command syntax includes both "
14093 "examples above, but may add more detail. The arguments E<.Ar infile> and "
14094 "E<.Ar outfile> from the example above might be referred to as E<.Em "
14095 "operands> or E<.Em file arguments>. Some command-line argument lists are "
14100 #: build/C/man7/mdoc.samples.7:682
14105 #. type: Plain text
14106 #: build/C/man7/mdoc.samples.7:695
14108 "E<.Op Fl eiknqrstv> E<.Op Fl D Ar variable> E<.Op Fl d Ar flags> E<.Op Fl f "
14109 "Ar makefile> E<.Bk -words> E<.Op Fl I Ar directory> E<.Ek> E<.Op Fl j Ar "
14110 "max_jobs> E<.Op Ar variable=value> E<.Bk -words> E<.Op Ar target ...> E<.Ek>"
14113 #. type: Plain text
14114 #: build/C/man7/mdoc.samples.7:721
14116 "Here one might talk about the command E<.Nm make> and qualify the argument "
14117 "E<.Ar makefile>, as an argument to the flag, E<.Fl f>, or discuss the "
14118 "optional file operand E<.Ar target>. In the verbal context, such detail can "
14119 "prevent confusion, however the E<.Nm \\-mdoc> package does not have a macro "
14120 "for an argument E<.Em to> a flag. Instead the E<.Ql \\&Ar> argument macro "
14121 "is used for an operand or file argument like E<.Ar target> as well as an "
14122 "argument to a flag like E<.Ar variable>. The make command line was produced "
14126 #. type: Plain text
14127 #: build/C/man7/mdoc.samples.7:733
14131 "\\&.Op Fl eiknqrstv\n"
14132 "\\&.Op Fl D Ar variable\n"
14133 "\\&.Op Fl d Ar flags\n"
14134 "\\&.Op Fl f Ar makefile\n"
14135 "\\&.Op Fl I Ar directory\n"
14136 "\\&.Op Fl j Ar max_jobs\n"
14137 "\\&.Op Ar variable=value\n"
14139 "\\&.Op Ar target ...\n"
14143 #. type: Plain text
14144 #: build/C/man7/mdoc.samples.7:741
14145 msgid "The E<.Ql \\&.Bk> and E<.Ql \\&.Ek> macros are explained in E<.Sx Keeps>."
14149 #: build/C/man7/mdoc.samples.7:741
14151 msgid "General Syntax"
14154 #. type: Plain text
14155 #: build/C/man7/mdoc.samples.7:764
14157 "The manual domain and general text domain macros share a similar syntax with "
14158 "a few minor deviations: E<.Ql \\&.Ar>, E<.Ql \\&.Fl>, E<.Ql \\&.Nm>, and "
14159 "E<.Ql \\&.Pa> differ only when called without arguments; E<.Ql \\&.Fn> and "
14160 "E<.Ql \\&.Xr> impose an order on their argument lists and the E<.Ql \\&.Op> "
14161 "and E<.Ql \\&.Fn> macros have nesting limitations. All content macros are "
14162 "capable of recognizing and properly handling punctuation, provided each "
14163 "punctuation character is separated by a leading space. If a request is "
14168 #: build/C/man7/mdoc.samples.7:765
14170 msgid "\\&.Li sptr, ptr),"
14173 #. type: Plain text
14174 #: build/C/man7/mdoc.samples.7:768 build/C/man7/mdoc.samples.7:778
14175 msgid "The result is:"
14179 #: build/C/man7/mdoc.samples.7:769
14181 msgid "Li sptr, ptr),"
14184 #. type: Plain text
14185 #: build/C/man7/mdoc.samples.7:774
14187 "The punctuation is not recognized and all is output in the literal font. If "
14188 "the punctuation is separated by a leading white space:"
14192 #: build/C/man7/mdoc.samples.7:775
14194 msgid "\\&.Li \"sptr , ptr ) ,\""
14198 #: build/C/man7/mdoc.samples.7:779
14200 msgid "Li sptr , ptr ) ,"
14203 #. type: Plain text
14204 #: build/C/man7/mdoc.samples.7:783
14206 "The punctuation is now recognized and is output in the default font "
14207 "distinguishing it from the strings in literal font."
14210 #. type: Plain text
14211 #: build/C/man7/mdoc.samples.7:792
14213 "To remove the special meaning from a punctuation character escape it with "
14214 "E<.Ql \\e&>. E<.Xr Troff> is limited as a macro language, and has "
14215 "difficulty when presented with a string containing a member of the "
14216 "mathematical, logical or quotation set:"
14219 #. type: Plain text
14220 #: build/C/man7/mdoc.samples.7:794
14222 msgid "\\&{+,\\-,/,*,\\&%,E<lt>,E<gt>,E<lt>=,E<gt>=,=,==,&,`,',\"}\n"
14225 #. type: Plain text
14226 #: build/C/man7/mdoc.samples.7:806
14228 "The problem is that E<.Xr troff> may assume it is supposed to actually "
14229 "perform the operation or evaluation suggested by the characters. To prevent "
14230 "the accidental evaluation of these characters, escape them with E<.Ql "
14231 "\\e&>. Typical syntax is shown in the first content macro displayed below, "
14236 #: build/C/man7/mdoc.samples.7:806
14238 msgid "MANUAL DOMAIN"
14242 #: build/C/man7/mdoc.samples.7:807
14244 msgid "Address Macro"
14247 #. type: Plain text
14248 #: build/C/man7/mdoc.samples.7:810
14250 "The address macro identifies an address construct of the form "
14251 "addr1[,addr2[,addr3]]."
14255 #: build/C/man7/mdoc.samples.7:811
14257 msgid "Usage: .Ad address ... \\*(Pu"
14261 #: build/C/man7/mdoc.samples.7:813
14263 msgid "Li \\&.Ad addr1"
14266 #. type: Plain text
14267 #: build/C/man7/mdoc.samples.7:815
14268 msgid "E<.Ad addr1>"
14272 #: build/C/man7/mdoc.samples.7:815
14274 msgid "Li \\&.Ad addr1\\ ."
14277 #. type: Plain text
14278 #: build/C/man7/mdoc.samples.7:817
14279 msgid "E<.Ad addr1>."
14283 #: build/C/man7/mdoc.samples.7:817
14285 msgid "Li \\&.Ad addr1\\ , file2"
14288 #. type: Plain text
14289 #: build/C/man7/mdoc.samples.7:819
14290 msgid "E<.Ad addr1 , file2>"
14294 #: build/C/man7/mdoc.samples.7:819
14296 msgid "Li \\&.Ad f1\\ , f2\\ , f3\\ :"
14299 #. type: Plain text
14300 #: build/C/man7/mdoc.samples.7:821
14301 msgid "E<.Ad f1 , f2 , f3>:"
14305 #: build/C/man7/mdoc.samples.7:821
14307 msgid "Li \\&.Ad addr\\ )\\ )\\ ,"
14310 #. type: Plain text
14311 #: build/C/man7/mdoc.samples.7:823
14312 msgid "E<.Ad addr>)),"
14315 #. type: Plain text
14316 #: build/C/man7/mdoc.samples.7:830
14318 "It is an error to call E<.Ql \\&.Ad> without arguments. E<.Ql \\&.Ad> is "
14319 "callable by other macros and is parsed."
14323 #: build/C/man7/mdoc.samples.7:830
14325 msgid "Author Name"
14328 #. type: Plain text
14329 #: build/C/man7/mdoc.samples.7:837
14331 "The E<.Ql \\&.An> macro is used to specify the name of the author of the "
14332 "item being documented, or the name of the author of the actual manual page. "
14333 "Any remaining arguments after the name information are assumed to be "
14338 #: build/C/man7/mdoc.samples.7:838
14340 msgid "Usage: .An author_name \\*(Pu"
14344 #: build/C/man7/mdoc.samples.7:840
14346 msgid "Li \\&.An Joe\\ Author"
14349 #. type: Plain text
14350 #: build/C/man7/mdoc.samples.7:842
14351 msgid "E<.An Joe Author>"
14355 #: build/C/man7/mdoc.samples.7:842
14357 msgid "Li \\&.An Joe\\ Author\\ ,"
14360 #. type: Plain text
14361 #: build/C/man7/mdoc.samples.7:844
14362 msgid "E<.An Joe\\ Author>,"
14366 #: build/C/man7/mdoc.samples.7:844
14368 msgid "Li \\&.An Joe\\ Author\\ \\&Aq\\ nobody@FreeBSD.ORG"
14371 #. type: Plain text
14372 #: build/C/man7/mdoc.samples.7:846
14373 msgid "E<.An Joe Author Aq nobody@FreeBSD.ORG>"
14377 #: build/C/man7/mdoc.samples.7:846
14379 msgid "Li \\&.An Joe\\ Author\\ )\\ )\\ ,"
14382 #. type: Plain text
14383 #: build/C/man7/mdoc.samples.7:848
14384 msgid "E<.An Joe Author>)),"
14387 #. type: Plain text
14388 #: build/C/man7/mdoc.samples.7:857
14390 "The E<.Ql \\&.An> macro is parsed and is callable. It is an error to call "
14391 "E<.Ql \\&.An> without any arguments."
14395 #: build/C/man7/mdoc.samples.7:857
14397 msgid "Argument Macro"
14400 #. type: Plain text
14401 #: build/C/man7/mdoc.samples.7:862
14403 "The E<.Ql \\&.Ar> argument macro may be used whenever a command-line "
14404 "argument is referenced."
14408 #: build/C/man7/mdoc.samples.7:863
14410 msgid "Usage: .Ar argument ... \\*(Pu"
14414 #: build/C/man7/mdoc.samples.7:865
14419 #. type: Plain text
14420 #: build/C/man7/mdoc.samples.7:867
14425 #: build/C/man7/mdoc.samples.7:867
14427 msgid "Li \\&.Ar file1"
14430 #. type: Plain text
14431 #: build/C/man7/mdoc.samples.7:869
14432 msgid "E<.Ar file1>"
14436 #: build/C/man7/mdoc.samples.7:869
14438 msgid "Li \\&.Ar file1\\ ."
14441 #. type: Plain text
14442 #: build/C/man7/mdoc.samples.7:871
14443 msgid "E<.Ar file1>."
14447 #: build/C/man7/mdoc.samples.7:871
14449 msgid "Li \\&.Ar file1 file2"
14452 #. type: Plain text
14453 #: build/C/man7/mdoc.samples.7:873
14454 msgid "E<.Ar file1 file2>"
14458 #: build/C/man7/mdoc.samples.7:873
14460 msgid "Li \\&.Ar f1 f2 f3\\ :"
14463 #. type: Plain text
14464 #: build/C/man7/mdoc.samples.7:875
14465 msgid "E<.Ar f1 f2 f3>:"
14469 #: build/C/man7/mdoc.samples.7:875
14471 msgid "Li \\&.Ar file\\ )\\ )\\ ,"
14474 #. type: Plain text
14475 #: build/C/man7/mdoc.samples.7:877
14476 msgid "E<.Ar file>)),"
14479 #. type: Plain text
14480 #: build/C/man7/mdoc.samples.7:887
14482 "If E<.Ql \\&.Ar> is called without arguments E<.Ql Ar> is assumed. The "
14483 "E<.Ql \\&.Ar> macro is parsed and is callable."
14487 #: build/C/man7/mdoc.samples.7:887
14489 msgid "Configuration Declaration (section four only)"
14492 #. type: Plain text
14493 #: build/C/man7/mdoc.samples.7:894
14495 "The E<.Ql \\&.Cd> macro is used to demonstrate a E<.Xr config 8> declaration "
14496 "for a device interface in a section four manual. This macro accepts quoted "
14497 "arguments (double quotes only)."
14501 #: build/C/man7/mdoc.samples.7:896
14503 msgid "Cd \"device le0 at scode?\""
14506 #. type: Plain text
14507 #: build/C/man7/mdoc.samples.7:899
14508 msgid "produced by: E<.Ql \".Cd device le0 at scode?\">."
14512 #: build/C/man7/mdoc.samples.7:900
14514 msgid "Command Modifier"
14517 #. type: Plain text
14518 #: build/C/man7/mdoc.samples.7:914
14520 "The command modifier is identical to the E<.Ql \\&.Fl> (flag) command with "
14521 "the exception the E<.Ql \\&.Cm> macro does not assert a dash in front of "
14522 "every argument. Traditionally flags are marked by the preceding dash, some "
14523 "commands or subsets of commands do not use them. Command modifiers may also "
14524 "be specified in conjunction with interactive commands such as editor "
14525 "commands. See E<.Sx Flags>."
14529 #: build/C/man7/mdoc.samples.7:914
14531 msgid "Defined Variables"
14534 #. type: Plain text
14535 #: build/C/man7/mdoc.samples.7:918
14537 "A variable which is defined in an include file is specified by the macro "
14542 #: build/C/man7/mdoc.samples.7:919
14544 msgid "Usage: .Dv defined_variable ... \\*(Pu"
14548 #: build/C/man7/mdoc.samples.7:921
14550 msgid "Li \".Dv MAXHOSTNAMELEN\""
14553 #. type: Plain text
14554 #: build/C/man7/mdoc.samples.7:923
14555 msgid "E<.Dv MAXHOSTNAMELEN>"
14559 #: build/C/man7/mdoc.samples.7:923
14561 msgid "Li \".Dv TIOCGPGRP )\""
14564 #. type: Plain text
14565 #: build/C/man7/mdoc.samples.7:925
14566 msgid "E<.Dv TIOCGPGRP>)"
14569 #. type: Plain text
14570 #: build/C/man7/mdoc.samples.7:932
14572 "It is an error to call E<.Ql \\&.Dv> without arguments. E<.Ql \\&.Dv> is "
14573 "parsed and is callable."
14577 #: build/C/man7/mdoc.samples.7:932
14579 msgid "Errno's (Section two only)"
14582 #. type: Plain text
14583 #: build/C/man7/mdoc.samples.7:944
14585 "The E<.Ql \\&.Er> errno macro specifies the error return value for section "
14586 "two library routines. The second example below shows E<.Ql \\&.Er> used "
14587 "with the E<.Ql \\&.Bq> general text domain macro, as it would be used in a "
14588 "section two manual page."
14592 #: build/C/man7/mdoc.samples.7:945
14594 msgid "Usage: .Er ERRNOTYPE ... \\*(Pu"
14598 #: build/C/man7/mdoc.samples.7:947
14600 msgid "Li \\&.Er ENOENT"
14603 #. type: Plain text
14604 #: build/C/man7/mdoc.samples.7:949
14605 msgid "E<.Er ENOENT>"
14609 #: build/C/man7/mdoc.samples.7:949
14611 msgid "Li \\&.Er ENOENT\\ )\\ ;"
14614 #. type: Plain text
14615 #: build/C/man7/mdoc.samples.7:951
14616 msgid "E<.Er ENOENT>);"
14620 #: build/C/man7/mdoc.samples.7:951
14622 msgid "Li \\&.Bq \\&Er ENOTDIR"
14625 #. type: Plain text
14626 #: build/C/man7/mdoc.samples.7:953
14627 msgid "E<.Bq Er ENOTDIR>"
14630 #. type: Plain text
14631 #: build/C/man7/mdoc.samples.7:961
14633 "It is an error to call E<.Ql \\&.Er> without arguments. The E<.Ql \\&.Er> "
14634 "macro is parsed and is callable."
14638 #: build/C/man7/mdoc.samples.7:961
14640 msgid "Environment Variables"
14643 #. type: Plain text
14644 #: build/C/man7/mdoc.samples.7:965
14645 msgid "The E<.Ql \\&.Ev> macro specifies an environment variable."
14649 #: build/C/man7/mdoc.samples.7:966
14651 msgid "Usage: .Ev argument ... \\*(Pu"
14655 #: build/C/man7/mdoc.samples.7:968
14657 msgid "Li \\&.Ev DISPLAY"
14660 #. type: Plain text
14661 #: build/C/man7/mdoc.samples.7:970
14662 msgid "E<.Ev DISPLAY>"
14666 #: build/C/man7/mdoc.samples.7:970
14668 msgid "Li \\&.Ev PATH\\ ."
14671 #. type: Plain text
14672 #: build/C/man7/mdoc.samples.7:972
14673 msgid "E<.Ev PATH>."
14677 #: build/C/man7/mdoc.samples.7:972
14679 msgid "Li \\&.Ev PRINTER\\ )\\ )\\ ,"
14682 #. type: Plain text
14683 #: build/C/man7/mdoc.samples.7:974
14684 msgid "E<.Ev PRINTER>)),"
14687 #. type: Plain text
14688 #: build/C/man7/mdoc.samples.7:982
14690 "It is an error to call E<.Ql \\&.Ev> without arguments. The E<.Ql \\&.Ev> "
14691 "macro is parsed and is callable."
14695 #: build/C/man7/mdoc.samples.7:982
14697 msgid "Function Argument"
14700 #. type: Plain text
14701 #: build/C/man7/mdoc.samples.7:1001
14703 "The E<.Ql \\&.Fa> macro is used to refer to function arguments (parameters) "
14704 "outside of the E<.Sx SYNOPSIS> section of the manual or inside the E<.Sx "
14705 "SYNOPSIS> section should a parameter list be too long for the E<.Ql \\&.Fn> "
14706 "macro and the enclosure macros E<.Ql \\&.Fo> and E<.Ql \\&.Fc> must be "
14707 "used. E<.Ql \\&.Fa> may also be used to refer to structure members."
14711 #: build/C/man7/mdoc.samples.7:1002
14713 msgid "Usage: .Fa function_argument ... \\*(Pu"
14717 #: build/C/man7/mdoc.samples.7:1004
14719 msgid "Li \\&.Fa d_namlen\\ )\\ )\\ ,"
14722 #. type: Plain text
14723 #: build/C/man7/mdoc.samples.7:1006
14724 msgid "E<.Fa d_namlen>)),"
14728 #: build/C/man7/mdoc.samples.7:1006
14730 msgid "Li \\&.Fa iov_len"
14733 #. type: Plain text
14734 #: build/C/man7/mdoc.samples.7:1008
14735 msgid "E<.Fa iov_len>"
14738 #. type: Plain text
14739 #: build/C/man7/mdoc.samples.7:1015
14741 "It is an error to call E<.Ql \\&.Fa> without arguments. E<.Ql \\&.Fa> is "
14742 "parsed and is callable."
14746 #: build/C/man7/mdoc.samples.7:1015
14748 msgid "Function Declaration"
14751 #. type: Plain text
14752 #: build/C/man7/mdoc.samples.7:1026
14754 "The E<.Ql \\&.Fd> macro is used in the E<.Sx SYNOPSIS> section with section "
14755 "two or three functions. The E<.Ql \\&.Fd> macro does not call other macros "
14756 "and is not callable by other macros."
14760 #: build/C/man7/mdoc.samples.7:1027
14762 msgid "Usage: .Fd include_file (or defined variable)"
14765 #. type: Plain text
14766 #: build/C/man7/mdoc.samples.7:1038
14768 "In the E<.Sx SYNOPSIS> section a E<.Ql \\&.Fd> request causes a line break "
14769 "if a function has already been presented and a break has not occurred. This "
14770 "leaves a nice vertical space in between the previous function call and the "
14771 "declaration for the next function."
14775 #: build/C/man7/mdoc.samples.7:1038
14780 #. type: Plain text
14781 #: build/C/man7/mdoc.samples.7:1051
14783 "The E<.Ql \\&.Fl> macro handles command-line flags. It prepends a dash, "
14784 "E<.Ql \\->, to the flag. For interactive command flags, which are not "
14785 "prepended with a dash, the E<.Ql \\&.Cm> (command modifier) macro is "
14786 "identical, but without the dash."
14790 #: build/C/man7/mdoc.samples.7:1052
14792 msgid "Usage: .Fl argument ... \\*(Pu"
14796 #: build/C/man7/mdoc.samples.7:1054
14801 #. type: Plain text
14802 #: build/C/man7/mdoc.samples.7:1056
14807 #: build/C/man7/mdoc.samples.7:1056
14809 msgid "Li \\&.Fl cfv"
14812 #. type: Plain text
14813 #: build/C/man7/mdoc.samples.7:1058
14818 #: build/C/man7/mdoc.samples.7:1058
14820 msgid "Li \\&.Fl cfv\\ ."
14823 #. type: Plain text
14824 #: build/C/man7/mdoc.samples.7:1060
14825 msgid "E<.Fl cfv>."
14829 #: build/C/man7/mdoc.samples.7:1060
14831 msgid "Li \\&.Fl s v t"
14834 #. type: Plain text
14835 #: build/C/man7/mdoc.samples.7:1062
14836 msgid "E<.Fl s v t>"
14840 #: build/C/man7/mdoc.samples.7:1062
14842 msgid "Li \\&.Fl -\\ ,"
14845 #. type: Plain text
14846 #: build/C/man7/mdoc.samples.7:1064
14851 #: build/C/man7/mdoc.samples.7:1064
14853 msgid "Li \\&.Fl xyz\\ )\\ ,"
14856 #. type: Plain text
14857 #: build/C/man7/mdoc.samples.7:1066
14858 msgid "E<.Fl xyz>),"
14861 #. type: Plain text
14862 #: build/C/man7/mdoc.samples.7:1078
14864 "The E<.Ql \\&.Fl> macro without any arguments results in a dash representing "
14865 "I<stdin>/I<stdout>. Note that giving E<.Ql \\&.Fl> a single dash, will "
14866 "result in two dashes. The E<.Ql \\&.Fl> macro is parsed and is callable."
14870 #: build/C/man7/mdoc.samples.7:1078
14872 msgid "Functions (library routines)"
14875 #. type: Plain text
14876 #: build/C/man7/mdoc.samples.7:1080
14877 msgid "The .Fn macro is modeled on ANSI C conventions."
14880 #. type: Plain text
14881 #: build/C/man7/mdoc.samples.7:1082
14883 msgid "Usage: .Fn [type] function [[type] parameters ... \\*(Pu]\n"
14887 #: build/C/man7/mdoc.samples.7:1084
14889 msgid "Li \"\\&.Fn getchar\""
14892 #. type: Plain text
14893 #: build/C/man7/mdoc.samples.7:1086
14894 msgid "E<.Fn getchar>"
14898 #: build/C/man7/mdoc.samples.7:1086
14900 msgid "Li \"\\&.Fn strlen ) ,\""
14903 #. type: Plain text
14904 #: build/C/man7/mdoc.samples.7:1088
14905 msgid "E<.Fn strlen>),"
14909 #: build/C/man7/mdoc.samples.7:1088
14911 msgid "Li \\&.Fn \"\\*qint align\\*q\" \"\\*qconst * char *sptrs\\*q\" ,"
14914 #. type: Plain text
14915 #: build/C/man7/mdoc.samples.7:1090
14916 msgid "E<.Fn \"int align\" \"const * char *sptrs\">,"
14919 #. type: Plain text
14920 #: build/C/man7/mdoc.samples.7:1103
14922 "It is an error to call E<.Ql \\&.Fn> without any arguments. The E<.Ql "
14923 "\\&.Fn> macro is parsed and is callable, note that any call to another macro "
14924 "signals the end of the E<.Ql \\&.Fn> call (it will close-parenthesis at that "
14928 #. type: Plain text
14929 #: build/C/man7/mdoc.samples.7:1117
14931 "For functions that have more than eight parameters (and this is rare), the "
14932 "macros E<.Ql \\&.Fo> (function open) and E<.Ql \\&.Fc> (function close) "
14933 "may be used with E<.Ql \\&.Fa> (function argument) to get around the "
14934 "limitation. For example:"
14937 #. type: Plain text
14938 #: build/C/man7/mdoc.samples.7:1129
14941 "\\&.Fo \"int res_mkquery\"\n"
14942 "\\&.Fa \"int op\"\n"
14943 "\\&.Fa \"char *dname\"\n"
14944 "\\&.Fa \"int class\"\n"
14945 "\\&.Fa \"int type\"\n"
14946 "\\&.Fa \"char *data\"\n"
14947 "\\&.Fa \"int datalen\"\n"
14948 "\\&.Fa \"struct rrec *newrr\"\n"
14949 "\\&.Fa \"char *buf\"\n"
14950 "\\&.Fa \"int buflen\"\n"
14954 #. type: Plain text
14955 #: build/C/man7/mdoc.samples.7:1132 build/C/man7/mdoc.samples.7:2471
14959 #. type: Plain text
14960 #: build/C/man7/mdoc.samples.7:1144
14963 "E<.Fo \"int res_mkquery\">\n"
14964 "E<.Fa \"int op\">\n"
14965 "E<.Fa \"char *dname\">\n"
14966 "E<.Fa \"int class\">\n"
14967 "E<.Fa \"int type\">\n"
14968 "E<.Fa \"char *data\">\n"
14969 "E<.Fa \"int datalen\">\n"
14970 "E<.Fa \"struct rrec *newrr\">\n"
14971 "E<.Fa \"char *buf\">\n"
14972 "E<.Fa \"int buflen\">\n"
14976 #. type: Plain text
14977 #: build/C/man7/mdoc.samples.7:1167
14979 "The E<.Ql \\&.Fo> and E<.Ql \\&.Fc> macros are parsed and are callable. In "
14980 "the E<.Sx SYNOPSIS> section, the function will always begin at the beginning "
14981 "of line. If there is more than one function presented in the E<.Sx "
14982 "SYNOPSIS> section and a function type has not been given, a line break will "
14983 "occur, leaving a nice vertical space between the current function name and "
14984 "the one prior. At the moment, E<.Ql \\&.Fn> does not check its word "
14985 "boundaries against troff line lengths and may split across a newline "
14986 "ungracefully. This will be fixed in the near future."
14990 #: build/C/man7/mdoc.samples.7:1167
14992 msgid "Function Type"
14995 #. type: Plain text
14996 #: build/C/man7/mdoc.samples.7:1178
14998 "This macro is intended for the E<.Sx SYNOPSIS> section. It may be used "
14999 "anywhere else in the man page without problems, but its main purpose is to "
15000 "present the function type in kernel normal form for the E<.Sx SYNOPSIS> of "
15001 "sections two and three (it causes a line break allowing the function name to "
15002 "appear on the next line)."
15006 #: build/C/man7/mdoc.samples.7:1179
15008 msgid "Usage: .Ft type ... \\*(Pu"
15012 #: build/C/man7/mdoc.samples.7:1181
15014 msgid "Li \\&.Ft struct stat"
15017 #. type: Plain text
15018 #: build/C/man7/mdoc.samples.7:1183
15019 msgid "E<.Ft struct stat>"
15022 #. type: Plain text
15023 #: build/C/man7/mdoc.samples.7:1188
15024 msgid "The E<.Ql \\&.Ft> request is not callable by other macros."
15028 #: build/C/man7/mdoc.samples.7:1188
15030 msgid "Interactive Commands"
15033 #. type: Plain text
15034 #: build/C/man7/mdoc.samples.7:1192
15035 msgid "The E<.Ql \\&.Ic> macro designates an interactive or internal command."
15039 #: build/C/man7/mdoc.samples.7:1193
15041 msgid "Usage: .Ic argument ... \\*(Pu"
15045 #: build/C/man7/mdoc.samples.7:1195
15047 msgid "Li \\&.Ic :wq"
15050 #. type: Plain text
15051 #: build/C/man7/mdoc.samples.7:1197
15056 #: build/C/man7/mdoc.samples.7:1197
15058 msgid "Li \\&.Ic do while {...}"
15061 #. type: Plain text
15062 #: build/C/man7/mdoc.samples.7:1199
15063 msgid "E<.Ic do while {...}>"
15067 #: build/C/man7/mdoc.samples.7:1199
15069 msgid "Li \\&.Ic setenv\\ , unsetenv"
15072 #. type: Plain text
15073 #: build/C/man7/mdoc.samples.7:1201
15074 msgid "E<.Ic setenv , unsetenv>"
15077 #. type: Plain text
15078 #: build/C/man7/mdoc.samples.7:1209
15080 "It is an error to call E<.Ql \\&.Ic> without arguments. The E<.Ql \\&.Ic> "
15081 "macro is parsed and is callable."
15085 #: build/C/man7/mdoc.samples.7:1209
15090 #. type: Plain text
15091 #: build/C/man7/mdoc.samples.7:1245
15093 "The E<.Ql \\&.Nm> macro is used for the document title or subject name. It "
15094 "has the peculiarity of remembering the first argument it was called with, "
15095 "which should always be the subject name of the page. When called without "
15096 "arguments, E<.Ql \\&.Nm> regurgitates this initial name for the sole purpose "
15097 "of making less work for the author. Note: a section two or three document "
15098 "function name is addressed with the E<.Ql \\&.Nm> in the E<.Sx NAME> "
15099 "section, and with E<.Ql \\&.Fn> in the E<.Sx SYNOPSIS> and remaining "
15100 "sections. For interactive commands, such as the E<.Ql while> command "
15101 "keyword in E<.Xr csh 1>, the E<.Ql \\&.Ic> macro should be used. While the "
15102 "E<.Ql \\&.Ic> is nearly identical to E<.Ql \\&.Nm>, it can not recall the "
15103 "first argument it was invoked with."
15107 #: build/C/man7/mdoc.samples.7:1246
15109 msgid "Usage: .Nm argument ... \\*(Pu"
15113 #: build/C/man7/mdoc.samples.7:1248
15115 msgid "Li \\&.Nm mdoc.sample"
15118 #. type: Plain text
15119 #: build/C/man7/mdoc.samples.7:1250
15120 msgid "E<.Nm mdoc.sample>"
15124 #: build/C/man7/mdoc.samples.7:1250
15126 msgid "Li \\&.Nm \\e-mdoc"
15129 #. type: Plain text
15130 #: build/C/man7/mdoc.samples.7:1252
15131 msgid "E<.Nm \\-mdoc>."
15135 #: build/C/man7/mdoc.samples.7:1252
15137 msgid "Li \\&.Nm foo\\ )\\ )\\ ,"
15140 #. type: Plain text
15141 #: build/C/man7/mdoc.samples.7:1254
15142 msgid "E<.Nm foo>)),"
15146 #: build/C/man7/mdoc.samples.7:1254
15151 #. type: Plain text
15152 #: build/C/man7/mdoc.samples.7:1256
15156 #. type: Plain text
15157 #: build/C/man7/mdoc.samples.7:1261
15158 msgid "The E<.Ql \\&.Nm> macro is parsed and is callable."
15162 #: build/C/man7/mdoc.samples.7:1261
15167 #. type: Plain text
15168 #: build/C/man7/mdoc.samples.7:1273
15170 "The E<.Ql \\&.Op> macro places option brackets around the any remaining "
15171 "arguments on the command line, and places any trailing punctuation outside "
15172 "the brackets. The macros E<.Ql \\&.Oc> and E<.Ql \\&.Oo> may be used across "
15173 "one or more lines."
15177 #: build/C/man7/mdoc.samples.7:1274
15179 msgid "Usage: .Op options ... \\*(Pu"
15183 #: build/C/man7/mdoc.samples.7:1276
15188 #. type: Plain text
15189 #: build/C/man7/mdoc.samples.7:1278
15194 #: build/C/man7/mdoc.samples.7:1278
15196 msgid "Li \".Op Fl k\""
15199 #. type: Plain text
15200 #: build/C/man7/mdoc.samples.7:1280
15201 msgid "E<.Op Fl k>"
15205 #: build/C/man7/mdoc.samples.7:1280
15207 msgid "Li \".Op Fl k ) .\""
15210 #. type: Plain text
15211 #: build/C/man7/mdoc.samples.7:1282
15212 msgid "E<.Op Fl k>)."
15216 #: build/C/man7/mdoc.samples.7:1282
15218 msgid "Li \".Op Fl k Ar kookfile\""
15221 #. type: Plain text
15222 #: build/C/man7/mdoc.samples.7:1284
15223 msgid "E<.Op Fl k Ar kookfile>"
15227 #: build/C/man7/mdoc.samples.7:1284
15229 msgid "Li \".Op Fl k Ar kookfile ,\""
15232 #. type: Plain text
15233 #: build/C/man7/mdoc.samples.7:1286
15234 msgid "E<.Op Fl k Ar kookfile>,"
15238 #: build/C/man7/mdoc.samples.7:1286
15240 msgid "Li \".Op Ar objfil Op Ar corfil\""
15243 #. type: Plain text
15244 #: build/C/man7/mdoc.samples.7:1288
15245 msgid "E<.Op Ar objfil Op Ar corfil>"
15249 #: build/C/man7/mdoc.samples.7:1288
15251 msgid "Li \".Op Fl c Ar objfil Op Ar corfil ,\""
15254 #. type: Plain text
15255 #: build/C/man7/mdoc.samples.7:1290
15256 msgid "E<.Op Fl c Ar objfil Op Ar corfil>,"
15260 #: build/C/man7/mdoc.samples.7:1290
15262 msgid "Li \\&.Op word1 word2"
15265 #. type: Plain text
15266 #: build/C/man7/mdoc.samples.7:1292
15267 msgid "E<.Op word1 word2>"
15270 #. type: Plain text
15271 #: build/C/man7/mdoc.samples.7:1299
15272 msgid "The E<.Ql \\&.Oc> and E<.Ql \\&.Oo> macros:"
15275 #. type: Plain text
15276 #: build/C/man7/mdoc.samples.7:1305
15280 "\\&.Op \\&Fl k \\&Ar kilobytes\n"
15281 "\\&.Op \\&Fl i \\&Ar interval\n"
15282 "\\&.Op \\&Fl c \\&Ar count\n"
15286 #. type: Plain text
15287 #: build/C/man7/mdoc.samples.7:1313
15289 "Produce: E<.Oo> E<.Op Fl k Ar kilobytes> E<.Op Fl i Ar interval> E<.Op Fl c "
15293 #. type: Plain text
15294 #: build/C/man7/mdoc.samples.7:1320
15296 "The macros E<.Ql \\&.Op>, E<.Ql \\&.Oc> and E<.Ql \\&.Oo> are parsed and are "
15301 #: build/C/man7/mdoc.samples.7:1320
15306 #. type: Plain text
15307 #: build/C/man7/mdoc.samples.7:1324
15308 msgid "The E<.Ql \\&.Pa> macro formats pathnames or filenames."
15312 #: build/C/man7/mdoc.samples.7:1325
15314 msgid "Usage: .Pa pathname \\*(Pu"
15318 #: build/C/man7/mdoc.samples.7:1327
15320 msgid "Li \\&.Pa /usr/share"
15323 #. type: Plain text
15324 #: build/C/man7/mdoc.samples.7:1329
15325 msgid "E<.Pa /usr/share>"
15329 #: build/C/man7/mdoc.samples.7:1329
15331 msgid "Li \\&.Pa /tmp/fooXXXXX\\ )\\ ."
15334 #. type: Plain text
15335 #: build/C/man7/mdoc.samples.7:1331
15336 msgid "E<.Pa /tmp/fooXXXXX>)."
15339 #. type: Plain text
15340 #: build/C/man7/mdoc.samples.7:1336
15341 msgid "The E<.Ql \\&.Pa> macro is parsed and is callable."
15345 #: build/C/man7/mdoc.samples.7:1336
15350 #. type: Plain text
15351 #: build/C/man7/mdoc.samples.7:1338
15352 msgid "Generic variable reference:"
15356 #: build/C/man7/mdoc.samples.7:1339
15358 msgid "Usage: .Va variable ... \\*(Pu"
15362 #: build/C/man7/mdoc.samples.7:1341
15364 msgid "Li \\&.Va count"
15367 #. type: Plain text
15368 #: build/C/man7/mdoc.samples.7:1343
15369 msgid "E<.Va count>"
15373 #: build/C/man7/mdoc.samples.7:1343
15375 msgid "Li \\&.Va settimer ,"
15378 #. type: Plain text
15379 #: build/C/man7/mdoc.samples.7:1345
15380 msgid "E<.Va settimer>,"
15384 #: build/C/man7/mdoc.samples.7:1345
15386 msgid "Li \\&.Va int\\ *prt\\ )\\ :"
15389 #. type: Plain text
15390 #: build/C/man7/mdoc.samples.7:1347
15391 msgid "E<.Va int\\ *prt>):"
15395 #: build/C/man7/mdoc.samples.7:1347
15397 msgid "Li \\&.Va char\\ s\\ ]\\ )\\ )\\ ,"
15400 #. type: Plain text
15401 #: build/C/man7/mdoc.samples.7:1349
15402 msgid "E<.Va char\\ s>])),"
15405 #. type: Plain text
15406 #: build/C/man7/mdoc.samples.7:1357
15408 "It is an error to call E<.Ql \\&.Va> without any arguments. The E<.Ql "
15409 "\\&.Va> macro is parsed and is callable."
15413 #: build/C/man7/mdoc.samples.7:1357
15415 msgid "Manual Page Cross References"
15418 #. type: Plain text
15419 #: build/C/man7/mdoc.samples.7:1365
15421 "The E<.Ql \\&.Xr> macro expects the first argument to be a manual page name, "
15422 "and the second argument, if it exists, to be either a section page number or "
15423 "punctuation. Any remaining arguments are assumed to be punctuation."
15427 #: build/C/man7/mdoc.samples.7:1366
15429 msgid "Usage: .Xr man_page [1,...,8] \\*(Pu"
15433 #: build/C/man7/mdoc.samples.7:1368
15435 msgid "Li \\&.Xr mdoc"
15438 #. type: Plain text
15439 #: build/C/man7/mdoc.samples.7:1370
15440 msgid "E<.Xr mdoc>"
15444 #: build/C/man7/mdoc.samples.7:1370
15446 msgid "Li \\&.Xr mdoc\\ ,"
15449 #. type: Plain text
15450 #: build/C/man7/mdoc.samples.7:1372
15451 msgid "E<.Xr mdoc>,"
15455 #: build/C/man7/mdoc.samples.7:1372
15457 msgid "Li \\&.Xr mdoc 7"
15460 #. type: Plain text
15461 #: build/C/man7/mdoc.samples.7:1374
15462 msgid "E<.Xr mdoc 7>"
15466 #: build/C/man7/mdoc.samples.7:1374
15468 msgid "Li \\&.Xr mdoc 7\\ )\\ )\\ ,"
15471 #. type: Plain text
15472 #: build/C/man7/mdoc.samples.7:1376
15473 msgid "E<.Xr mdoc 7>)),"
15476 #. type: Plain text
15477 #: build/C/man7/mdoc.samples.7:1385
15479 "The E<.Ql \\&.Xr> macro is parsed and is callable. It is an error to call "
15480 "E<.Ql \\&.Xr> without any arguments."
15484 #: build/C/man7/mdoc.samples.7:1385
15486 msgid "GENERAL TEXT DOMAIN"
15490 #: build/C/man7/mdoc.samples.7:1386
15495 #. type: Plain text
15496 #: build/C/man7/mdoc.samples.7:1389
15498 msgid "Usage: .At [v6 | v7 | 32v | V.1 | V.4] ... \\*(Pu\n"
15502 #: build/C/man7/mdoc.samples.7:1391
15507 #. type: Plain text
15508 #: build/C/man7/mdoc.samples.7:1393
15513 #: build/C/man7/mdoc.samples.7:1393
15515 msgid "Li \".At v6 .\""
15518 #. type: Plain text
15519 #: build/C/man7/mdoc.samples.7:1395
15523 #. type: Plain text
15524 #: build/C/man7/mdoc.samples.7:1405
15526 "The E<.Ql \\&.At> macro is E<.Em not> parsed and E<.Em not> callable It "
15527 "accepts at most two arguments."
15531 #: build/C/man7/mdoc.samples.7:1405
15537 #: build/C/man7/mdoc.samples.7:1406
15539 msgid "Usage: .Bx [Version/release] ... \\*(Pu"
15543 #: build/C/man7/mdoc.samples.7:1408
15548 #. type: Plain text
15549 #: build/C/man7/mdoc.samples.7:1410
15554 #: build/C/man7/mdoc.samples.7:1410
15556 msgid "Li \".Bx 4.3 .\""
15559 #. type: Plain text
15560 #: build/C/man7/mdoc.samples.7:1412
15561 msgid "E<.Bx 4.3>."
15564 #. type: Plain text
15565 #: build/C/man7/mdoc.samples.7:1417
15566 msgid "The E<.Ql \\&.Bx> macro is parsed and is callable."
15570 #: build/C/man7/mdoc.samples.7:1417
15572 msgid "FreeBSD Macro"
15575 #. type: Plain text
15576 #: build/C/man7/mdoc.samples.7:1420
15578 msgid "Usage: .Fx Version.release ... \\*(Pu\n"
15582 #: build/C/man7/mdoc.samples.7:1422
15584 msgid "Li \".Fx 2.2 .\""
15587 #. type: Plain text
15588 #: build/C/man7/mdoc.samples.7:1424
15589 msgid "E<.Fx 2.2>."
15592 #. type: Plain text
15593 #: build/C/man7/mdoc.samples.7:1434
15595 "The E<.Ql \\&.Fx> macro is E<.Em not> parsed and E<.Em not> callable It "
15596 "accepts at most two arguments."
15600 #: build/C/man7/mdoc.samples.7:1434
15606 #: build/C/man7/mdoc.samples.7:1435
15608 msgid "Usage: .Ux ... \\*(Pu"
15612 #: build/C/man7/mdoc.samples.7:1437
15617 #. type: Plain text
15618 #: build/C/man7/mdoc.samples.7:1439
15622 #. type: Plain text
15623 #: build/C/man7/mdoc.samples.7:1444
15624 msgid "The E<.Ql \\&.Ux> macro is parsed and is callable."
15628 #: build/C/man7/mdoc.samples.7:1444
15630 msgid "Enclosure and Quoting Macros"
15633 #. type: Plain text
15634 #: build/C/man7/mdoc.samples.7:1466
15636 "The concept of enclosure is similar to quoting. The object being to enclose "
15637 "one or more strings between a pair of characters like quotes or "
15638 "parentheses. The terms quoting and enclosure are used interchangeably "
15639 "throughout this document. Most of the one line enclosure macros end in "
15640 "small letter E<.Ql q> to give a hint of quoting, but there are a few "
15641 "irregularities. For each enclosure macro there is also a pair of open and "
15642 "close macros which end in small letters E<.Ql o> and E<.Ql c> respectively. "
15643 "These can be used across one or more lines of text and while they have "
15644 "nesting limitations, the one line quote macros can be used inside of them."
15647 #. type: Plain text
15648 #: build/C/man7/mdoc.samples.7:1479
15651 "E<.Em \" Quote\t Close\t Open\tFunction\tResult\">\n"
15652 "\\&.Aq\t.Ac\t.Ao\tAngle Bracket Enclosure\tE<lt>stringE<gt>\n"
15653 "\\&.Bq\t.Bc\t.Bo\tBracket Enclosure\t[string]\n"
15654 "\\&.Dq\t.Dc\t.Do\tDouble Quote\t``string''\n"
15655 "\t.Ec\t.Eo\tEnclose String (in XX)\tXXstringXX\n"
15656 "\\&.Pq\t.Pc\t.Po\tParenthesis Enclosure\t(string)\n"
15657 "\\&.Ql\t\t\tQuoted Literal\t`st' or string\n"
15658 "\\&.Qq\t.Qc\t.Qo\tStraight Double Quote\t\"string\"\n"
15659 "\\&.Sq\t.Sc\t.So\tSingle Quote\t`string'\n"
15662 #. type: Plain text
15663 #: build/C/man7/mdoc.samples.7:1490
15665 "Except for the irregular macros noted below, all of the quoting macros are "
15666 "parsed and callable. All handle punctuation properly, as long as it is "
15667 "presented one character at a time and separated by spaces. The quoting "
15668 "macros examine opening and closing punctuation to determine whether it comes "
15669 "before or after the enclosing string This makes some nesting possible."
15673 #: build/C/man7/mdoc.samples.7:1491
15675 msgid "Li \\&.Ec , \\&.Eo"
15678 #. type: Plain text
15679 #: build/C/man7/mdoc.samples.7:1494
15681 "These macros expect the first argument to be the opening and closing strings "
15686 #: build/C/man7/mdoc.samples.7:1494
15691 #. type: Plain text
15692 #: build/C/man7/mdoc.samples.7:1507
15694 "The quoted literal macro behaves differently for E<.Xr troff> than E<.Xr "
15695 "nroff>. If formatted with E<.Xr nroff>, a quoted literal is always quoted. "
15696 "If formatted with troff, an item is only quoted if the width of the item is "
15697 "less than three constant width characters. This is to make short strings "
15698 "more visible where the font change to literal (constant width) is less "
15703 #: build/C/man7/mdoc.samples.7:1507
15708 #. type: Plain text
15709 #: build/C/man7/mdoc.samples.7:1509
15710 msgid "The prefix macro is not callable, but it is parsed:"
15714 #: build/C/man7/mdoc.samples.7:1510
15716 msgid "Li \".Pf ( Fa name2\""
15719 #. type: Plain text
15720 #: build/C/man7/mdoc.samples.7:1513
15721 msgid "becomes E<.Pf ( Fa name2>."
15724 #. type: Plain text
15725 #: build/C/man7/mdoc.samples.7:1518
15726 msgid "The E<.Ql \\&.Ns> (no space) macro performs the analogous suffix function."
15729 #. type: Plain text
15730 #: build/C/man7/mdoc.samples.7:1522
15731 msgid "Examples of quoting:"
15735 #: build/C/man7/mdoc.samples.7:1523
15740 #. type: Plain text
15741 #: build/C/man7/mdoc.samples.7:1525
15746 #: build/C/man7/mdoc.samples.7:1525
15748 msgid "Li \\&.Aq \\&Ar ctype.h\\ )\\ ,"
15751 #. type: Plain text
15752 #: build/C/man7/mdoc.samples.7:1527
15753 msgid "E<.Aq Ar ctype.h>),"
15757 #: build/C/man7/mdoc.samples.7:1527
15762 #. type: Plain text
15763 #: build/C/man7/mdoc.samples.7:1529
15768 #: build/C/man7/mdoc.samples.7:1529
15770 msgid "Li \\&.Bq \\&Em Greek \\&, French \\&."
15773 #. type: Plain text
15774 #: build/C/man7/mdoc.samples.7:1531
15775 msgid "E<.Bq Em Greek , French>."
15779 #: build/C/man7/mdoc.samples.7:1531
15784 #. type: Plain text
15785 #: build/C/man7/mdoc.samples.7:1533
15790 #: build/C/man7/mdoc.samples.7:1533
15792 msgid "Li \".Dq string abc .\""
15795 #. type: Plain text
15796 #: build/C/man7/mdoc.samples.7:1535
15797 msgid "E<.Dq string abc>."
15801 #: build/C/man7/mdoc.samples.7:1535
15803 msgid "Li \".Dq \\'^[A-Z]\\'\""
15806 #. type: Plain text
15807 #: build/C/man7/mdoc.samples.7:1537
15808 msgid "E<.Dq \\'^[A-Z]\\'>"
15812 #: build/C/man7/mdoc.samples.7:1537
15814 msgid "Li \"\\&.Ql man mdoc\""
15817 #. type: Plain text
15818 #: build/C/man7/mdoc.samples.7:1539
15819 msgid "E<.Ql man mdoc>"
15823 #: build/C/man7/mdoc.samples.7:1539
15828 #. type: Plain text
15829 #: build/C/man7/mdoc.samples.7:1541
15834 #: build/C/man7/mdoc.samples.7:1541
15836 msgid "Li \"\\&.Qq string ) ,\""
15839 #. type: Plain text
15840 #: build/C/man7/mdoc.samples.7:1543
15841 msgid "E<.Qq string>),"
15845 #: build/C/man7/mdoc.samples.7:1543
15847 msgid "Li \"\\&.Qq string Ns ),\""
15850 #. type: Plain text
15851 #: build/C/man7/mdoc.samples.7:1545
15852 msgid "E<.Qq string Ns ),>"
15856 #: build/C/man7/mdoc.samples.7:1545
15861 #. type: Plain text
15862 #: build/C/man7/mdoc.samples.7:1547
15867 #: build/C/man7/mdoc.samples.7:1547
15869 msgid "Li \"\\&.Sq string\""
15872 #. type: Plain text
15873 #: build/C/man7/mdoc.samples.7:1549
15874 msgid "E<.Sq string>"
15877 #. type: Plain text
15878 #: build/C/man7/mdoc.samples.7:1566
15880 "For a good example of nested enclosure macros, see the E<.Ql \\&.Op> option "
15881 "macro. It was created from the same underlying enclosure macros as those "
15882 "presented in the list above. The E<.Ql \\&.Xo> and E<.Ql \\&.Xc> extended "
15883 "argument list macros were also built from the same underlying routines and "
15884 "are a good example of E<.Nm \\-mdoc> macro usage at its worst."
15888 #: build/C/man7/mdoc.samples.7:1566
15890 msgid "No\\-Op or Normal Text Macro"
15893 #. type: Plain text
15894 #: build/C/man7/mdoc.samples.7:1574
15896 "The macro E<.Ql \\&.No> is a hack for words in a macro command line which "
15897 "should E<.Em not> be formatted and follows the conventional syntax for "
15902 #: build/C/man7/mdoc.samples.7:1574
15904 msgid "No Space Macro"
15907 #. type: Plain text
15908 #: build/C/man7/mdoc.samples.7:1580
15910 "The E<.Ql \\&.Ns> macro eliminates unwanted spaces in between macro "
15911 "requests. It is useful for old style argument lists where there is no space "
15912 "between the flag and argument:"
15916 #: build/C/man7/mdoc.samples.7:1581
15918 msgid "Li \".Op Fl I Ns Ar directory\""
15921 #. type: Plain text
15922 #: build/C/man7/mdoc.samples.7:1584
15923 msgid "produces E<.Op Fl I Ns Ar directory>"
15926 #. type: Plain text
15927 #: build/C/man7/mdoc.samples.7:1595
15929 "Note: the E<.Ql \\&.Ns> macro always invokes the E<.Ql \\&.No> macro after "
15930 "eliminating the space unless another macro name follows it. The macro E<.Ql "
15931 "\\&.Ns> is parsed and is callable."
15935 #: build/C/man7/mdoc.samples.7:1595
15937 msgid "Section Cross References"
15940 #. type: Plain text
15941 #: build/C/man7/mdoc.samples.7:1601
15943 "The E<.Ql \\&.Sx> macro designates a reference to a section header within "
15944 "the same document. It is parsed and is callable."
15948 #: build/C/man7/mdoc.samples.7:1603
15950 msgid "Li \\&.Sx FILES"
15953 #. type: Plain text
15954 #: build/C/man7/mdoc.samples.7:1605
15955 msgid "E<.Sx FILES>"
15959 #: build/C/man7/mdoc.samples.7:1606
15961 msgid "References and Citations"
15964 #. type: Plain text
15965 #: build/C/man7/mdoc.samples.7:1610
15967 "The following macros make a modest attempt to handle references. At best, "
15968 "the macros make it convenient to manually drop in a subset of refer style "
15973 #: build/C/man7/mdoc.samples.7:1612
15978 #. type: Plain text
15979 #: build/C/man7/mdoc.samples.7:1617
15981 "Reference Start. Causes a line break and begins collection of reference "
15982 "information until the reference end macro is read."
15986 #: build/C/man7/mdoc.samples.7:1617
15991 #. type: Plain text
15992 #: build/C/man7/mdoc.samples.7:1620
15993 msgid "Reference End. The reference is printed."
15997 #: build/C/man7/mdoc.samples.7:1620
16002 #. type: Plain text
16003 #: build/C/man7/mdoc.samples.7:1622
16004 msgid "Reference author name, one name per invocation."
16008 #: build/C/man7/mdoc.samples.7:1622
16013 #. type: Plain text
16014 #: build/C/man7/mdoc.samples.7:1624
16015 msgid "Book title."
16019 #: build/C/man7/mdoc.samples.7:1624
16024 #. type: Plain text
16025 #: build/C/man7/mdoc.samples.7:1626
16026 msgid "City/place."
16030 #: build/C/man7/mdoc.samples.7:1626
16035 #. type: Plain text
16036 #: build/C/man7/mdoc.samples.7:1628
16041 #: build/C/man7/mdoc.samples.7:1628
16046 #. type: Plain text
16047 #: build/C/man7/mdoc.samples.7:1630
16048 msgid "Journal name."
16052 #: build/C/man7/mdoc.samples.7:1630
16057 #. type: Plain text
16058 #: build/C/man7/mdoc.samples.7:1632
16059 msgid "Issue number."
16063 #: build/C/man7/mdoc.samples.7:1632
16068 #. type: Plain text
16069 #: build/C/man7/mdoc.samples.7:1634
16070 msgid "Optional information."
16074 #: build/C/man7/mdoc.samples.7:1634
16079 #. type: Plain text
16080 #: build/C/man7/mdoc.samples.7:1636
16081 msgid "Page number."
16085 #: build/C/man7/mdoc.samples.7:1636
16090 #. type: Plain text
16091 #: build/C/man7/mdoc.samples.7:1638
16092 msgid "Report name."
16096 #: build/C/man7/mdoc.samples.7:1638
16101 #. type: Plain text
16102 #: build/C/man7/mdoc.samples.7:1640
16103 msgid "Title of article."
16107 #: build/C/man7/mdoc.samples.7:1640
16112 #. type: Plain text
16113 #: build/C/man7/mdoc.samples.7:1642
16117 #. type: Plain text
16118 #: build/C/man7/mdoc.samples.7:1653
16120 "The macros beginning with E<.Ql %> are not callable, and are parsed only for "
16121 "the trade name macro which returns to its caller. (And not very predictably "
16122 "at the moment either.) The purpose is to allow trade names to be pretty "
16123 "printed in E<.Xr troff Ns / Ns Xr ditroff> output."
16127 #: build/C/man7/mdoc.samples.7:1653
16129 msgid "Return Values"
16132 #. type: Plain text
16133 #: build/C/man7/mdoc.samples.7:1659
16135 "The E<.Ql \\&.Rv> macro generates text for use in the E<.Sx RETURN VALUE> "
16140 #: build/C/man7/mdoc.samples.7:1660
16142 msgid "Usage: .Rv [-std function]"
16145 #. type: Plain text
16146 #: build/C/man7/mdoc.samples.7:1664
16147 msgid "E<.Ql \\&.Rv -std atexit> will generate the following text:"
16150 #. fake chapter 3 to avoid error message from Rv
16152 #: build/C/man7/mdoc.samples.7:1666
16157 #. and back to 7 again
16158 #. type: Plain text
16159 #: build/C/man7/mdoc.samples.7:1669
16160 msgid "E<.Rv -std atexit>"
16164 #: build/C/man7/mdoc.samples.7:1669
16169 #. type: Plain text
16170 #: build/C/man7/mdoc.samples.7:1674
16171 msgid "The E<.Fl std> option is valid only for manual page sections 2 and 3."
16175 #: build/C/man7/mdoc.samples.7:1674
16177 msgid "Trade Names (or Acronyms and Type Names)"
16180 #. type: Plain text
16181 #: build/C/man7/mdoc.samples.7:1677
16183 "The trade name macro is generally a small caps macro for all upper case "
16184 "words longer than two characters."
16188 #: build/C/man7/mdoc.samples.7:1678
16190 msgid "Usage: .Tn symbol ... \\*(Pu"
16194 #: build/C/man7/mdoc.samples.7:1680
16196 msgid "Li \\&.Tn DEC"
16199 #. type: Plain text
16200 #: build/C/man7/mdoc.samples.7:1682
16205 #: build/C/man7/mdoc.samples.7:1682
16207 msgid "Li \\&.Tn ASCII"
16210 #. type: Plain text
16211 #: build/C/man7/mdoc.samples.7:1684
16212 msgid "E<.Tn ASCII>"
16215 #. type: Plain text
16216 #: build/C/man7/mdoc.samples.7:1690
16217 msgid "The E<.Ql \\&.Tn> macro is parsed and is callable by other macros."
16221 #: build/C/man7/mdoc.samples.7:1690
16223 msgid "Extended Arguments"
16226 #. type: Plain text
16227 #: build/C/man7/mdoc.samples.7:1702
16229 "The E<.Ql \\&.Xo> and E<.Ql \\&.Xc> macros allow one to extend an argument "
16230 "list on a macro boundary. Argument lists cannot be extended within a macro "
16231 "which expects all of its arguments on one line such as E<.Ql \\&.Op>."
16234 #. type: Plain text
16235 #: build/C/man7/mdoc.samples.7:1706
16237 "Here is an example of E<.Ql \\&.Xo> using the space mode macro to turn "
16241 #. type: Plain text
16242 #: build/C/man7/mdoc.samples.7:1712
16246 "\\&.It Xo Sy I Ar operation\n"
16247 "\\&.No \\een Ar count No \\een\n"
16252 #. type: Plain text
16253 #: build/C/man7/mdoc.samples.7:1715 build/C/man7/mdoc.samples.7:1736 build/C/man7/mdoc.samples.7:1760
16257 #. type: Plain text
16258 #: build/C/man7/mdoc.samples.7:1718 build/C/man7/mdoc.samples.7:1739
16260 msgid "E<.Sm off>\n"
16264 #: build/C/man7/mdoc.samples.7:1718
16266 msgid "Xo Sy I Ar operation"
16269 #. type: Plain text
16270 #: build/C/man7/mdoc.samples.7:1722
16273 "E<.No \\en Ar count No \\en>\n"
16278 #. type: Plain text
16279 #: build/C/man7/mdoc.samples.7:1726
16280 msgid "Another one:"
16283 #. type: Plain text
16284 #: build/C/man7/mdoc.samples.7:1733
16288 "\\&.It Cm S No \\&/ Ar old_pattern Xo\n"
16289 "\\&.No \\&/ Ar new_pattern\n"
16290 "\\&.No \\&/ Op Cm g\n"
16296 #: build/C/man7/mdoc.samples.7:1739
16298 msgid "Cm S No \\&/ Ar old_pattern Xo"
16301 #. type: Plain text
16302 #: build/C/man7/mdoc.samples.7:1744
16305 "E<.No \\&/ Ar new_pattern>\n"
16306 "E<.No \\&/ Op Cm g>\n"
16311 #. type: Plain text
16312 #: build/C/man7/mdoc.samples.7:1751
16314 "Another example of E<.Ql \\&.Xo> and using enclosure macros: Test the value "
16318 #. type: Plain text
16319 #: build/C/man7/mdoc.samples.7:1757
16324 "\\&.Oo \\e&! Oc Ns Ar variable\n"
16325 "\\&.Op Ar operator variable ...\n"
16330 #: build/C/man7/mdoc.samples.7:1762
16335 #. type: Plain text
16336 #: build/C/man7/mdoc.samples.7:1767
16340 "E<.Oo \\&! Oc Ns Ar variable>\n"
16341 "E<.Op Ar operator variable ...>\n"
16345 #. type: Plain text
16346 #: build/C/man7/mdoc.samples.7:1805
16348 "All of the above examples have used the E<.Ql \\&.Xo> macro on the argument "
16349 "list of the E<.Ql \\&.It> (list-item) macro. The extend macros are not "
16350 "used very often, and when they are it is usually to extend the list-item "
16351 "argument list. Unfortunately, this is also where the extend macros are the "
16352 "most finicky. In the first two examples, spacing was turned off; in the "
16353 "third, spacing was desired in part of the output but not all of it. To make "
16354 "these macros work in this situation make sure the E<.Ql \\&.Xo> and E<.Ql "
16355 "\\&.Xc> macros are placed as shown in the third example. If the E<.Ql "
16356 "\\&.Xo> macro is not alone on the E<.Ql \\&.It> argument list, spacing will "
16357 "be unpredictable. The E<.Ql \\&.Ns> (no space macro) must not occur as the "
16358 "first or last macro on a line in this situation. Out of 900 manual pages "
16359 "(about 1500 actual pages) currently released with E<.Bx> only fifteen use "
16360 "the E<.Ql \\&.Xo> macro."
16364 #: build/C/man7/mdoc.samples.7:1806
16366 msgid "Section Headers"
16369 #. type: Plain text
16370 #: build/C/man7/mdoc.samples.7:1819
16372 "The first three E<.Ql \\&.Sh> section header macros list below are required "
16373 "in every man page. The remaining section headers are recommended at the "
16374 "discretion of the author writing the manual page. The E<.Ql \\&.Sh> macro "
16375 "can take up to nine arguments. It is parsed and but is not callable."
16379 #: build/C/man7/mdoc.samples.7:1820
16381 msgid "\\&.Sh NAME"
16384 #. type: Plain text
16385 #: build/C/man7/mdoc.samples.7:1840
16387 "The E<.Ql \\&.Sh NAME> macro is mandatory. If not specified, the headers, "
16388 "footers and page layout defaults will not be set and things will be rather "
16389 "unpleasant. The E<.Sx NAME> section consists of at least three items. The "
16390 "first is the E<.Ql \\&.Nm> name macro naming the subject of the man page. "
16391 "The second is the Name Description macro, E<.Ql \\&.Nd>, which separates the "
16392 "subject name from the third item, which is the description. The description "
16393 "should be the most terse and lucid possible, as the space available is "
16398 #: build/C/man7/mdoc.samples.7:1840
16400 msgid "\\&.Sh SYNOPSIS"
16403 #. type: Plain text
16404 #: build/C/man7/mdoc.samples.7:1872
16406 "The E<.Sx SYNOPSIS> section describes the typical usage of the subject of a "
16407 "man page. The macros required are either E<.Ql \".Nm\">, E<.Ql \".Cd\">, "
16408 "E<.Ql \".Fn\">, (and possibly E<.Ql \".Fo\">, E<.Ql \".Fc\">, E<.Ql "
16409 "\".Fd\">, E<.Ql \".Ft\"> macros). The function name macro E<.Ql \".Fn\"> is "
16410 "required for manual page sections 2 and 3, the command and general name "
16411 "macro E<.Ql \\&.Nm> is required for sections 1, 5, 6, 7, 8. Section 4 "
16412 "manuals require a E<.Ql \".Nm\">, E<.Ql \".Fd\"> or a E<.Ql \".Cd\"> "
16413 "configuration device usage macro. Several other macros may be necessary to "
16414 "produce the synopsis line as shown below:"
16417 #. type: Plain text
16418 #: build/C/man7/mdoc.samples.7:1878
16422 "E<.Op Fl benstuv>\n"
16427 #. type: Plain text
16428 #: build/C/man7/mdoc.samples.7:1881
16429 msgid "The following macros were used:"
16433 #: build/C/man7/mdoc.samples.7:1882
16439 #: build/C/man7/mdoc.samples.7:1883
16441 msgid "\\&.Op \\&Fl benstuv"
16445 #: build/C/man7/mdoc.samples.7:1884
16447 msgid "\\&.Op \\&Fl"
16451 #: build/C/man7/mdoc.samples.7:1885
16456 #. type: Plain text
16457 #: build/C/man7/mdoc.samples.7:1896
16459 "E<.Sy Note>: The macros E<.Ql \\&.Op>, E<.Ql \\&.Fl>, and E<.Ql \\&.Ar> "
16460 "recognize the pipe bar character E<.Ql \\*(Ba>, so a command line such as:"
16464 #: build/C/man7/mdoc.samples.7:1897
16466 msgid ".Op Fl a | Fl b"
16469 #. type: Plain text
16470 #: build/C/man7/mdoc.samples.7:1906
16472 "will not go orbital. E<.Xr Troff> normally interprets a \\*(Ba as a special "
16473 "operator. See E<.Sx PREDEFINED STRINGS> for a usable \\*(Ba character in "
16474 "other situations."
16478 #: build/C/man7/mdoc.samples.7:1906
16480 msgid "\\&.Sh DESCRIPTION"
16483 #. type: Plain text
16484 #: build/C/man7/mdoc.samples.7:1923
16486 "In most cases the first text in the E<.Sx DESCRIPTION> section is a brief "
16487 "paragraph on the command, function or file, followed by a lexical list of "
16488 "options and respective explanations. To create such a list, the E<.Ql "
16489 "\\&.Bl> begin-list, E<.Ql \\&.It> list-item and E<.Ql \\&.El> end-list "
16490 "macros are used (see E<.Sx Lists and Columns> below)."
16493 #. type: Plain text
16494 #: build/C/man7/mdoc.samples.7:1932
16496 "The following E<.Ql \\&.Sh> section headers are part of the preferred manual "
16497 "page layout and must be used appropriately to maintain consistency. They "
16498 "are listed in the order in which they would be used."
16502 #: build/C/man7/mdoc.samples.7:1933
16504 msgid "\\&.Sh ENVIRONMENT"
16507 #. type: Plain text
16508 #: build/C/man7/mdoc.samples.7:1939
16510 "The E<.Sx ENVIRONMENT> section should reveal any related environment "
16511 "variables and clues to their behavior and/or usage."
16515 #: build/C/man7/mdoc.samples.7:1939
16517 msgid "\\&.Sh EXAMPLES"
16520 #. type: Plain text
16521 #: build/C/man7/mdoc.samples.7:1946
16523 "There are several ways to create examples. See the E<.Sx EXAMPLES> section "
16524 "below for details."
16528 #: build/C/man7/mdoc.samples.7:1946
16530 msgid "\\&.Sh FILES"
16533 #. type: Plain text
16534 #: build/C/man7/mdoc.samples.7:1953
16536 "Files which are used or created by the man page subject should be listed via "
16537 "the E<.Ql \\&.Pa> macro in the E<.Sx FILES> section."
16541 #: build/C/man7/mdoc.samples.7:1953
16543 msgid "\\&.Sh SEE ALSO"
16546 #. type: Plain text
16547 #: build/C/man7/mdoc.samples.7:1967
16549 "References to other material on the man page topic and cross references to "
16550 "other relevant man pages should be placed in the E<.Sx SEE ALSO> section. "
16551 "Cross references are specified using the E<.Ql \\&.Xr> macro. Cross "
16552 "references in the E<.Sx SEE ALSO> section should be sorted by section "
16553 "number, and then placed in alphabetical order and comma separated. For "
16557 #. type: Plain text
16558 #: build/C/man7/mdoc.samples.7:1972
16559 msgid "E<.Xr ls 1>, E<.Xr ps 1>, E<.Xr group 5>, E<.Xr passwd 5>."
16562 #. type: Plain text
16563 #: build/C/man7/mdoc.samples.7:1976
16564 msgid "At this time E<.Xr refer 1> style references are not accommodated."
16568 #: build/C/man7/mdoc.samples.7:1976
16570 msgid "\\&.Sh CONFORMING TO"
16573 #. type: Plain text
16574 #: build/C/man7/mdoc.samples.7:1988
16576 "If the command, library function or file adheres to a specific "
16577 "implementation such as E<.St -p1003.2> or E<.St -ansiC> this should be noted "
16578 "here. If the command does not adhere to any standard, its history should be "
16579 "noted in the E<.Sx HISTORY> section."
16583 #: build/C/man7/mdoc.samples.7:1988
16585 msgid "\\&.Sh HISTORY"
16588 #. type: Plain text
16589 #: build/C/man7/mdoc.samples.7:1991
16591 "Any command which does not adhere to any specific standards should be "
16592 "outlined historically in this section."
16596 #: build/C/man7/mdoc.samples.7:1991
16598 msgid "\\&.Sh AUTHORS"
16601 #. type: Plain text
16602 #: build/C/man7/mdoc.samples.7:1993
16603 msgid "Credits, if need be, should be placed here."
16607 #: build/C/man7/mdoc.samples.7:1993
16609 msgid "\\&.Sh DIAGNOSTICS"
16612 #. type: Plain text
16613 #: build/C/man7/mdoc.samples.7:1995
16614 msgid "Diagnostics from a command should be placed in this section."
16618 #: build/C/man7/mdoc.samples.7:1995
16620 msgid "\\&.Sh ERRORS"
16623 #. type: Plain text
16624 #: build/C/man7/mdoc.samples.7:2001
16626 "Specific error handling, especially from library functions (man page "
16627 "sections 2 and 3) should go here. The E<.Ql \\&.Er> macro is used to "
16628 "specify an errno."
16632 #: build/C/man7/mdoc.samples.7:2001
16634 msgid "\\&.Sh BUGS"
16637 #. type: Plain text
16638 #: build/C/man7/mdoc.samples.7:2003
16639 msgid "Blatant problems with the topic go here..."
16642 #. type: Plain text
16643 #: build/C/man7/mdoc.samples.7:2009
16645 "User specified E<.Ql \\&.Sh> sections may be added, for example, this "
16646 "section was set with:"
16649 #. type: Plain text
16650 #: build/C/man7/mdoc.samples.7:2011
16652 msgid "\\&.Sh PAGE STRUCTURE DOMAIN\n"
16656 #: build/C/man7/mdoc.samples.7:2012
16658 msgid "Paragraphs and Line Spacing."
16662 #: build/C/man7/mdoc.samples.7:2014
16667 #. type: Plain text
16668 #: build/C/man7/mdoc.samples.7:2030
16670 "The E<.Ql \\&.Pp> paragraph command may be used to specify a line space "
16671 "where necessary. The macro is not necessary after a E<.Ql \\&.Sh> or E<.Ql "
16672 "\\&.Ss> macro or before a E<.Ql \\&.Bl> macro. (The E<.Ql \\&.Bl> macro "
16673 "asserts a vertical distance unless the -compact flag is given)."
16676 #. This worked with version one, need to redo for version three
16679 #. .Cw (ax+bx+c) \ is\ produced\ by\ \&
16680 #. .\".Cw (ax+bx+c) \&.Va_by_) \&_and_\& \&[?/]m_b1_e1_f1[?/]\&
16697 #. .Em is produced by
16713 #. This example shows the same equation in a different format.
16717 #. signs were forced with
16721 #. .Cw (ax\ +\ bx\ +\ c) \ is\ produced\ by\ \&
16722 #. .\".Cw (ax+bx+c) \&.Va_by_) \&_and_\& \&[?/]m_b1_e1_f1[?/]\&
16733 #. .Li \&.Cx \e\ +\e\ \e&
16744 #. .Em is produced by
16752 #. .Li \&.Cx \e\ +\e\ \e&
16763 #. The incantation below was
16769 #. .Cw \&[?/]m_b1_e1_f1[?/]\& is\ produced\ by
16771 #. .Li \&.Cx Op Sy ?/
16781 #. .Em is produced by
16783 #. .Li \&.Ar \e\ b1 e1 f1
16795 #: build/C/man7/mdoc.samples.7:2149
16800 #. type: Plain text
16801 #: build/C/man7/mdoc.samples.7:2178
16803 "The only keep that is implemented at this time is for words. The macros are "
16804 "E<.Ql \\&.Bk> (begin-keep) and E<.Ql \\&.Ek> (end-keep). The only option "
16805 "that E<.Ql \\&.Bk> accepts is E<.Fl words> and is useful for preventing line "
16806 "breaks in the middle of options. In the example for the make command-line "
16807 "arguments (see E<.Sx What's in a name>), the keep prevented E<.Xr nroff> "
16808 "from placing up the flag and the argument on separate lines. (Actually, the "
16809 "option macro used to prevent this from occurring, but was dropped when the "
16810 "decision (religious) was made to force right justified margins in E<.Xr "
16811 "troff> as options in general look atrocious when spread across a sparse "
16812 "line. More work needs to be done with the keep macros, a E<.Fl line> option "
16813 "needs to be added.)"
16817 #: build/C/man7/mdoc.samples.7:2178
16819 msgid "Examples and Displays"
16822 #. type: Plain text
16823 #: build/C/man7/mdoc.samples.7:2190
16825 "There are five types of displays, a quickie one line indented display E<.Ql "
16826 "\\&.D1>, a quickie one line literal display E<.Ql \\&.Dl>, and a block "
16827 "literal, block filled and block ragged which use the E<.Ql \\&.Bd> "
16828 "begin-display and E<.Ql \\&.Ed> end-display macros."
16831 #. type: Plain text
16832 #: build/C/man7/mdoc.samples.7:2195
16834 "(D-one) Display one line of indented text. This macro is parsed, but it is "
16839 #: build/C/man7/mdoc.samples.7:2196
16841 msgid "Fl ldghfstru"
16844 #. type: Plain text
16845 #: build/C/man7/mdoc.samples.7:2200
16846 msgid "The above was produced by: E<.Li \\&.Dl Fl ldghfstru>."
16849 #. type: Plain text
16850 #: build/C/man7/mdoc.samples.7:2215
16852 "(D-ell) Display one line of indented E<.Em literal> text. The E<.Ql "
16853 "\\&.Dl> example macro has been used throughout this file. It allows the "
16854 "indent (display) of one line of text. Its default font is set to constant "
16855 "width (literal) however it is parsed and will recognized other macros. It "
16856 "is not callable however."
16860 #: build/C/man7/mdoc.samples.7:2216
16862 msgid "% ls -ldg /usr/local/bin"
16865 #. type: Plain text
16866 #: build/C/man7/mdoc.samples.7:2220
16867 msgid "The above was produced by E<.Li \\&.Dl % ls -ldg /usr/local/bin>."
16870 #. type: Plain text
16871 #: build/C/man7/mdoc.samples.7:2231
16873 "Begin-display. The E<.Ql \\&.Bd> display must be ended with the E<.Ql "
16874 "\\&.Ed> macro. Displays may be nested within displays and lists. E<.Ql "
16875 "\\&.Bd> has the following syntax:"
16879 #: build/C/man7/mdoc.samples.7:2232
16881 msgid ".Bd display-type [-offset offset_value] [-compact]"
16884 #. type: Plain text
16885 #: build/C/man7/mdoc.samples.7:2237
16887 "The display-type must be one of the following four types and may have an "
16888 "offset specifier for indentation: E<.Ql \\&.Bd>."
16891 #. type: Plain text
16892 #: build/C/man7/mdoc.samples.7:2242
16894 "Display a block of text as typed, right (and left) margin edges are left "
16898 #. type: Plain text
16899 #: build/C/man7/mdoc.samples.7:2246
16901 "Display a filled (formatted) block. The block of text is formatted (the "
16902 "edges are filled \\- not left unjustified)."
16905 #. type: Plain text
16906 #: build/C/man7/mdoc.samples.7:2249
16908 "Display a literal block, useful for source code or simple tabbed or spaced "
16913 #: build/C/man7/mdoc.samples.7:2249
16915 msgid "Fl file Ar file_name"
16918 #. type: Plain text
16919 #: build/C/man7/mdoc.samples.7:2258
16921 "The filename following the E<.Fl file> flag is read and displayed. Literal "
16922 "mode is asserted and tabs are set at 8 constant width character intervals, "
16923 "however any E<.Xr troff/ Ns Nm \\-mdoc> commands in file will be processed."
16926 #. type: Plain text
16927 #: build/C/man7/mdoc.samples.7:2264
16929 "If E<.Fl offset> is specified with one of the following strings, the string "
16930 "is interpreted to indicate the level of indentation for the forthcoming "
16934 #. type: Plain text
16935 #: build/C/man7/mdoc.samples.7:2270
16937 "Align block on the current left margin, this is the default mode of E<.Ql "
16941 #. type: Plain text
16942 #: build/C/man7/mdoc.samples.7:2275
16944 "Supposedly center the block. At this time unfortunately, the block merely "
16945 "gets left aligned about an imaginary center margin."
16948 #. type: Plain text
16949 #: build/C/man7/mdoc.samples.7:2284
16951 "Indents by one default indent value or tab. The default indent value is "
16952 "also used for the E<.Ql \\&.D1> display so one is guaranteed the two types "
16953 "of displays will line up. This indent is normally set to 6n or about two "
16954 "thirds of an inch (six constant width characters)."
16957 #. type: Plain text
16958 #: build/C/man7/mdoc.samples.7:2286
16959 msgid "Indents two times the default indent value."
16962 #. type: Plain text
16963 #: build/C/man7/mdoc.samples.7:2294
16965 "This E<.Em left> aligns the block about two inches from the right side of "
16966 "the page. This macro needs work and perhaps may never do the right thing by "
16971 #: build/C/man7/mdoc.samples.7:2296
16976 #. type: Plain text
16977 #: build/C/man7/mdoc.samples.7:2298
16978 msgid "End-display."
16982 #: build/C/man7/mdoc.samples.7:2299
16987 #. type: Plain text
16988 #: build/C/man7/mdoc.samples.7:2301
16989 msgid "There are five macros for changing the appearance of the manual page text:"
16993 #: build/C/man7/mdoc.samples.7:2302
16998 #. type: Plain text
16999 #: build/C/man7/mdoc.samples.7:2307
17001 "Text may be stressed or emphasized with the E<.Ql \\&.Em> macro. The usual "
17002 "font for emphasis is italic."
17006 #: build/C/man7/mdoc.samples.7:2308
17008 msgid "Usage: .Em argument ... \\*(Pu"
17012 #: build/C/man7/mdoc.samples.7:2310
17014 msgid "Li \".Em does not\""
17017 #. type: Plain text
17018 #: build/C/man7/mdoc.samples.7:2312
17019 msgid "E<.Em does not>"
17023 #: build/C/man7/mdoc.samples.7:2312
17025 msgid "Li \".Em exceed 1024 .\""
17028 #. type: Plain text
17029 #: build/C/man7/mdoc.samples.7:2314
17030 msgid "E<.Em exceed 1024>."
17034 #: build/C/man7/mdoc.samples.7:2314
17036 msgid "Li \".Em vide infra ) ) ,\""
17039 #. type: Plain text
17040 #: build/C/man7/mdoc.samples.7:2316
17041 msgid "E<.Em vide infra>)),"
17044 #. type: Plain text
17045 #: build/C/man7/mdoc.samples.7:2324
17047 "The E<.Ql \\&.Em> macro is parsed and is callable. It is an error to call "
17048 "E<.Ql \\&.Em> without arguments."
17052 #: build/C/man7/mdoc.samples.7:2324
17057 #. type: Plain text
17058 #: build/C/man7/mdoc.samples.7:2330
17060 "The E<.Ql \\&.Li> literal macro may be used for special characters, variable "
17061 "constants, anything which should be displayed as it would be typed."
17065 #: build/C/man7/mdoc.samples.7:2331
17067 msgid "Usage: .Li argument ... \\*(Pu"
17071 #: build/C/man7/mdoc.samples.7:2333
17073 msgid "Li \\&.Li \\een"
17076 #. type: Plain text
17077 #: build/C/man7/mdoc.samples.7:2335
17078 msgid "E<.Li \\en>"
17082 #: build/C/man7/mdoc.samples.7:2335
17084 msgid "Li \\&.Li M1 M2 M3\\ ;"
17087 #. type: Plain text
17088 #: build/C/man7/mdoc.samples.7:2337
17089 msgid "E<.Li M1 M2 M3>;"
17093 #: build/C/man7/mdoc.samples.7:2337
17095 msgid "Li \\&.Li cntrl-D\\ )\\ ,"
17098 #. type: Plain text
17099 #: build/C/man7/mdoc.samples.7:2339
17100 msgid "E<.Li cntrl-D>),"
17104 #: build/C/man7/mdoc.samples.7:2339
17106 msgid "Li \\&.Li 1024\\ ..."
17109 #. type: Plain text
17110 #: build/C/man7/mdoc.samples.7:2341
17111 msgid "E<.Li 1024 ...>"
17114 #. type: Plain text
17115 #: build/C/man7/mdoc.samples.7:2346
17116 msgid "The E<.Ql \\&.Li> macro is parsed and is callable."
17120 #: build/C/man7/mdoc.samples.7:2346
17125 #. type: Plain text
17126 #: build/C/man7/mdoc.samples.7:2349
17128 "The symbolic emphasis macro is generally a boldface macro in either the "
17129 "symbolic sense or the traditional English usage."
17133 #: build/C/man7/mdoc.samples.7:2350
17135 msgid "Usage: .Sy symbol ... \\*(Pu"
17139 #: build/C/man7/mdoc.samples.7:2352
17141 msgid "Li \\&.Sy Important Notice"
17144 #. type: Plain text
17145 #: build/C/man7/mdoc.samples.7:2354
17146 msgid "E<.Sy Important Notice>"
17149 #. type: Plain text
17150 #: build/C/man7/mdoc.samples.7:2362
17152 "The E<.Ql \\&.Sy> macro is parsed and is callable. Arguments to E<.Ql "
17153 "\\&.Sy> may be quoted."
17157 #: build/C/man7/mdoc.samples.7:2362
17162 #. type: Plain text
17163 #: build/C/man7/mdoc.samples.7:2372
17165 "Begin font mode. The E<.Ql \\&.Bf> font mode must be ended with the E<.Ql "
17166 "\\&.Ef> macro. Font modes may be nested within other font modes. E<.Ql "
17167 "\\&.Bf> has the following syntax:"
17171 #: build/C/man7/mdoc.samples.7:2373
17173 msgid ".Bf font-mode"
17176 #. type: Plain text
17177 #: build/C/man7/mdoc.samples.7:2377
17178 msgid "The font-mode must be one of the following three types: E<.Ql \\&.Bf>."
17182 #: build/C/man7/mdoc.samples.7:2379
17184 msgid "Sy \\&Em | Fl emphasis"
17187 #. type: Plain text
17188 #: build/C/man7/mdoc.samples.7:2383
17189 msgid "Same as if the E<.Ql \\&.Em> macro was used for the entire block of text."
17193 #: build/C/man7/mdoc.samples.7:2383
17195 msgid "Sy \\&Li | Fl literal"
17198 #. type: Plain text
17199 #: build/C/man7/mdoc.samples.7:2387
17200 msgid "Same as if the E<.Ql \\&.Li> macro was used for the entire block of text."
17204 #: build/C/man7/mdoc.samples.7:2387
17206 msgid "Sy \\&Sy | Fl symbolic"
17209 #. type: Plain text
17210 #: build/C/man7/mdoc.samples.7:2391
17211 msgid "Same as if the E<.Ql \\&.Sy> macro was used for the entire block of text."
17215 #: build/C/man7/mdoc.samples.7:2392
17220 #. type: Plain text
17221 #: build/C/man7/mdoc.samples.7:2394
17222 msgid "End font mode."
17226 #: build/C/man7/mdoc.samples.7:2395
17228 msgid "Tagged Lists and Columns"
17231 #. type: Plain text
17232 #: build/C/man7/mdoc.samples.7:2409
17234 "There are several types of lists which may be initiated with the E<.Ql "
17235 "\".Bl\"> begin-list macro. Items within the list are specified with the "
17236 "E<.Ql \".It\"> item macro and each list must end with the E<.Ql \".El\"> "
17237 "macro. Lists may be nested within themselves and within displays. Columns "
17238 "may be used inside of lists, but lists are unproven inside of columns."
17241 #. type: Plain text
17242 #: build/C/man7/mdoc.samples.7:2424
17244 "In addition, several list attributes may be specified such as the width of a "
17245 "tag, the list offset, and compactness (blank lines between items allowed or "
17246 "disallowed). Most of this document has been formatted with a tag style list "
17247 "E<.Pq Fl tag>. For a change of pace, the list-type used to present the "
17248 "list-types is an over-hanging list E<.Pq Fl ohang>. This type of list is "
17249 "quite popular with E<.Tn TeX> users, but might look a bit funny after having "
17250 "read many pages of tagged lists. The following list types are accepted by "
17255 #: build/C/man7/mdoc.samples.7:2426
17261 #: build/C/man7/mdoc.samples.7:2427
17267 #: build/C/man7/mdoc.samples.7:2428
17272 #. type: Plain text
17273 #: build/C/man7/mdoc.samples.7:2438
17275 "These three are the simplest types of lists. Once the E<.Ql \".Bl\"> macro "
17276 "has been given, items in the list are merely indicated by a line consisting "
17277 "solely of the E<.Ql \".It\"> macro. For example, the source text for a "
17278 "simple enumerated list would look like:"
17281 #. type: Plain text
17282 #: build/C/man7/mdoc.samples.7:2447
17285 "\\&.Bl -enum -compact\n"
17287 "\\&Item one goes here.\n"
17289 "\\&And item two here.\n"
17291 "\\&Lastly item three goes here.\n"
17295 #. type: Plain text
17296 #: build/C/man7/mdoc.samples.7:2450
17297 msgid "The results:"
17300 #. type: Plain text
17301 #: build/C/man7/mdoc.samples.7:2454
17302 msgid "Item one goes here."
17305 #. type: Plain text
17306 #: build/C/man7/mdoc.samples.7:2456
17307 msgid "And item two here."
17310 #. type: Plain text
17311 #: build/C/man7/mdoc.samples.7:2458
17312 msgid "Lastly item three goes here."
17315 #. type: Plain text
17316 #: build/C/man7/mdoc.samples.7:2461
17317 msgid "A simple bullet list construction:"
17320 #. type: Plain text
17321 #: build/C/man7/mdoc.samples.7:2468
17324 "\\&.Bl -bullet -compact\n"
17326 "\\&Bullet one goes here.\n"
17328 "\\&Bullet two here.\n"
17332 #. type: Plain text
17333 #: build/C/man7/mdoc.samples.7:2474
17334 msgid "Bullet one goes here."
17337 #. type: Plain text
17338 #: build/C/man7/mdoc.samples.7:2476
17339 msgid "Bullet two here."
17343 #: build/C/man7/mdoc.samples.7:2478
17349 #: build/C/man7/mdoc.samples.7:2479
17355 #: build/C/man7/mdoc.samples.7:2480
17361 #: build/C/man7/mdoc.samples.7:2481
17367 #: build/C/man7/mdoc.samples.7:2482
17372 #. type: Plain text
17373 #: build/C/man7/mdoc.samples.7:2502
17375 "These list-types collect arguments specified with the E<.Ql \\&.It> macro "
17376 "and create a label which may be E<.Em inset> into the forthcoming text, "
17377 "E<.Em hanged> from the forthcoming text, E<.Em overhanged> from above and "
17378 "not indented or E<.Em tagged>. This list was constructed with the E<.Ql Fl "
17379 "ohang> list-type. The E<.Ql \\&.It> macro is parsed only for the inset, "
17380 "hang and tag list-types and is not callable. Here is an example of inset "
17385 #: build/C/man7/mdoc.samples.7:2503
17390 #. type: Plain text
17391 #: build/C/man7/mdoc.samples.7:2506
17393 "The tagged list (also called a tagged paragraph) is the most common type of "
17394 "list used in the Berkeley manuals."
17398 #: build/C/man7/mdoc.samples.7:2506
17403 #. type: Plain text
17404 #: build/C/man7/mdoc.samples.7:2510
17406 "Diag lists create section four diagnostic lists and are similar to inset "
17407 "lists except callable macros are ignored."
17411 #: build/C/man7/mdoc.samples.7:2510
17416 #. type: Plain text
17417 #: build/C/man7/mdoc.samples.7:2512
17418 msgid "Hanged labels are a matter of taste."
17422 #: build/C/man7/mdoc.samples.7:2512
17427 #. type: Plain text
17428 #: build/C/man7/mdoc.samples.7:2514
17429 msgid "Overhanging labels are nice when space is constrained."
17433 #: build/C/man7/mdoc.samples.7:2514
17438 #. type: Plain text
17439 #: build/C/man7/mdoc.samples.7:2519
17441 "Inset labels are useful for controlling blocks of paragraphs and are "
17442 "valuable for converting E<.Nm \\-mdoc> manuals to other formats."
17445 #. type: Plain text
17446 #: build/C/man7/mdoc.samples.7:2522
17447 msgid "Here is the source text which produced the above example:"
17450 #. type: Plain text
17451 #: build/C/man7/mdoc.samples.7:2541
17454 "\\&.Bl -inset -offset indent\n"
17456 "\\&The tagged list (also called a tagged paragraph) is the\n"
17457 "\\&most common type of list used in the Berkeley manuals.\n"
17459 "\\&Diag lists create section four diagnostic lists\n"
17460 "\\&and are similar to inset lists except callable\n"
17461 "\\¯os are ignored.\n"
17463 "\\&Hanged labels are a matter of taste.\n"
17464 "\\&.It Em Ohang\n"
17465 "\\&Overhanging labels are nice when space is constrained.\n"
17466 "\\&.It Em Inset\n"
17467 "\\&Inset labels are useful for controlling blocks of\n"
17468 "\\¶graphs and are valuable for converting\n"
17470 "\\&manuals to other formats.\n"
17474 #. type: Plain text
17475 #: build/C/man7/mdoc.samples.7:2544
17476 msgid "Here is a hanged list with two items:"
17480 #: build/C/man7/mdoc.samples.7:2545
17485 #. type: Plain text
17486 #: build/C/man7/mdoc.samples.7:2548
17488 "labels appear similar to tagged lists when the label is smaller than the "
17493 #: build/C/man7/mdoc.samples.7:2548
17495 msgid "Em Longer hanged list labels"
17498 #. type: Plain text
17499 #: build/C/man7/mdoc.samples.7:2551
17500 msgid "blend in to the paragraph unlike tagged paragraph labels."
17503 #. type: Plain text
17504 #: build/C/man7/mdoc.samples.7:2554
17505 msgid "And the unformatted text which created it:"
17508 #. type: Plain text
17509 #: build/C/man7/mdoc.samples.7:2563
17512 "\\&.Bl -hang -offset indent\n"
17513 "\\&.It Em Hanged\n"
17514 "\\&labels appear similar to tagged lists when the\n"
17515 "\\&label is smaller than the label width.\n"
17516 "\\&.It Em Longer hanged list labels\n"
17517 "\\&blend in to the paragraph unlike\n"
17518 "\\&tagged paragraph labels.\n"
17522 #. type: Plain text
17523 #: build/C/man7/mdoc.samples.7:2567
17525 "The tagged list which follows uses an optional width specifier to control "
17526 "the width of the tag."
17530 #: build/C/man7/mdoc.samples.7:2569
17535 #. type: Plain text
17536 #: build/C/man7/mdoc.samples.7:2571
17537 msgid "sleep time of the process (seconds blocked)"
17541 #: build/C/man7/mdoc.samples.7:2571
17546 #. type: Plain text
17547 #: build/C/man7/mdoc.samples.7:2576
17549 "number of disk E<.Tn I/O Ns 's> resulting from references by the process to "
17550 "pages not loaded in core."
17554 #: build/C/man7/mdoc.samples.7:2576
17559 #. type: Plain text
17560 #: build/C/man7/mdoc.samples.7:2578
17561 msgid "numerical user-id of process owner"
17565 #: build/C/man7/mdoc.samples.7:2578
17570 #. type: Plain text
17571 #: build/C/man7/mdoc.samples.7:2581
17573 "numerical ID of parent of process process priority (nonpositive when in "
17574 "noninterruptible wait)"
17577 #. type: Plain text
17578 #: build/C/man7/mdoc.samples.7:2584
17579 msgid "The raw text:"
17582 #. type: Plain text
17583 #: build/C/man7/mdoc.samples.7:2599
17586 "\\&.Bl -tag -width \"PAGEIN\" -compact -offset indent\n"
17588 "\\&sleep time of the process (seconds blocked)\n"
17590 "\\&number of disk\n"
17591 "\\&.Tn I/O Ns 's\n"
17592 "\\&resulting from references\n"
17593 "\\&by the process to pages not loaded in core.\n"
17595 "\\&numerical user ID of process owner\n"
17597 "\\&numerical ID of parent of process process priority\n"
17598 "\\&(nonpositive when in noninterruptible wait)\n"
17602 #. type: Plain text
17603 #: build/C/man7/mdoc.samples.7:2602
17604 msgid "Acceptable width specifiers:"
17608 #: build/C/man7/mdoc.samples.7:2603
17610 msgid "Fl width Ar \\&Fl"
17613 #. type: Plain text
17614 #: build/C/man7/mdoc.samples.7:2612
17616 "sets the width to the default width for a flag. All callable macros have a "
17617 "default width value. The E<.Ql \\&.Fl>, value is presently set to ten "
17618 "constant width characters or about five sixth of an inch."
17622 #: build/C/man7/mdoc.samples.7:2612
17624 msgid "Fl width Ar 24n"
17627 #. type: Plain text
17628 #: build/C/man7/mdoc.samples.7:2618
17630 "sets the width to 24 constant width characters or about two inches. The "
17631 "E<.Ql n> is absolutely necessary for the scaling to work correctly."
17635 #: build/C/man7/mdoc.samples.7:2618
17637 msgid "Fl width Ar ENAMETOOLONG"
17640 #. type: Plain text
17641 #: build/C/man7/mdoc.samples.7:2621
17642 msgid "sets width to the constant width length of the string given."
17646 #: build/C/man7/mdoc.samples.7:2621
17648 msgid "Fl width Ar \"\\*qint mkfifo\\*q\""
17651 #. type: Plain text
17652 #: build/C/man7/mdoc.samples.7:2624
17653 msgid "again, the width is set to the constant width of the string given."
17656 #. type: Plain text
17657 #: build/C/man7/mdoc.samples.7:2639
17659 "If a width is not specified for the tag list type, the first time E<.Ql "
17660 "\\&.It> is invoked, an attempt is made to determine an appropriate width. "
17661 "If the first argument to E<.Ql \".It\"> is a callable macro, the default "
17662 "width for that macro will be used as if the macro name had been supplied as "
17663 "the width. However, if another item in the list is given with a different "
17664 "callable macro name, a new and nested list is assumed."
17668 #: build/C/man7/mdoc.samples.7:2639
17670 msgid "PREDEFINED STRINGS"
17673 #. type: Plain text
17674 #: build/C/man7/mdoc.samples.7:2651
17676 "The following strings are predefined as may be used by preceding with the "
17677 "troff string interpreting sequence E<.Ql \\&\\e*(xx> where E<.Em xx> is the "
17678 "name of the defined string or as E<.Ql \\&\\e*x> where E<.Em x> is the name "
17679 "of the string. The interpreting sequence may be used any where in the text."
17683 #: build/C/man7/mdoc.samples.7:2653
17685 msgid "Sy \"String\tNroff\tTroff\""
17689 #: build/C/man7/mdoc.samples.7:2654
17691 msgid "Li E<lt>= Ta \\&E<lt>\\&= Ta \\*(E<lt>="
17695 #: build/C/man7/mdoc.samples.7:2655
17697 msgid "Li E<gt>= Ta \\&E<gt>\\&= Ta \\*(E<gt>="
17701 #: build/C/man7/mdoc.samples.7:2656
17703 msgid "Li Rq Ta '' Ta \\*(Rq"
17707 #: build/C/man7/mdoc.samples.7:2657
17709 msgid "Li Lq Ta `` Ta \\*(Lq"
17713 #: build/C/man7/mdoc.samples.7:2658
17715 msgid "Li ua Ta ^ Ta \\*(ua"
17719 #: build/C/man7/mdoc.samples.7:2659
17721 msgid "Li aa Ta ' Ta \\*(aa"
17725 #: build/C/man7/mdoc.samples.7:2660
17727 msgid "Li ga Ta \\` Ta \\*(ga"
17730 #. .It Li "sL" Ta ` Ta \*(sL
17731 #. .It Li "sR" Ta ' Ta \*(sR
17733 #: build/C/man7/mdoc.samples.7:2663
17735 msgid "Li q Ta \\(dq Ta \\*q"
17739 #: build/C/man7/mdoc.samples.7:2664
17741 msgid "Li Pi Ta pi Ta \\*(Pi"
17745 #: build/C/man7/mdoc.samples.7:2665
17747 msgid "Li Ne Ta != Ta \\*(Ne"
17751 #: build/C/man7/mdoc.samples.7:2666
17753 msgid "Li Le Ta E<lt>= Ta \\*(Le"
17757 #: build/C/man7/mdoc.samples.7:2667
17759 msgid "Li Ge Ta E<gt>= Ta \\*(Ge"
17763 #: build/C/man7/mdoc.samples.7:2668
17765 msgid "Li Lt Ta E<lt> Ta \\*(Gt"
17769 #: build/C/man7/mdoc.samples.7:2669
17771 msgid "Li Gt Ta E<gt> Ta \\*(Lt"
17775 #: build/C/man7/mdoc.samples.7:2670
17777 msgid "Li Pm Ta +- Ta \\*(Pm"
17781 #: build/C/man7/mdoc.samples.7:2671
17783 msgid "Li If Ta infinity Ta \\*(If"
17787 #: build/C/man7/mdoc.samples.7:2672
17789 msgid "Li Na Ta I<NaN> Ta \\*(Na"
17793 #: build/C/man7/mdoc.samples.7:2673
17795 msgid "Li Ba Ta \\&| Ta \\*(Ba"
17798 #. type: Plain text
17799 #: build/C/man7/mdoc.samples.7:2682
17801 "E<.Sy Note>: The string named E<.Ql q> should be written as E<.Ql \\e*q> "
17802 "since it is only one char."
17806 #: build/C/man7/mdoc.samples.7:2682
17808 msgid "DIAGNOSTICS"
17811 #. type: Plain text
17812 #: build/C/man7/mdoc.samples.7:2715
17814 "The debugging facilities for E<.Nm \\-mdoc> are limited, but can help detect "
17815 "subtle errors such as the collision of an argument name with an internal "
17816 "register or macro name. (A what?) A register is an arithmetic storage "
17817 "class for E<.Xr troff> with a one or two character name. All registers "
17818 "internal to E<.Nm \\-mdoc> for E<.Xr troff> and E<.Xr ditroff> are two "
17819 "characters and of the form E<lt>upper_caseE<gt>E<lt>lower_caseE<gt> such as "
17820 "E<.Ql \\&Ar>, E<lt>lower_caseE<gt>E<lt>upper_caseE<gt> as E<.Ql \\&aR> or "
17821 "E<lt>upper or lower letterE<gt>E<lt>digitE<gt> as E<.Ql \\&C\\&1>. And "
17822 "adding to the muddle, E<.Xr troff> has its own internal registers all of "
17823 "which are either two lower case characters or a dot plus a letter or "
17824 "metacharacter character. In one of the introduction examples, it was shown "
17825 "how to prevent the interpretation of a macro name with the escape sequence "
17826 "E<.Ql \\e&>. This is sufficient for the internal register names also."
17829 #. Every callable macro name has a corresponding register
17830 #. of the same name (<upper_case><lower_case>).
17831 #. There are also specific registers which have
17832 #. been used for stacks and arrays and are listed in the
17834 #. .Bd -ragged -offset 4n
17835 #. [A-Z][a-z] registers corresponding to macro names (example ``Ar'')
17836 #. [a-z][A-Z] registers corresponding to macro names (example ``aR'')
17837 #. C[0-9] argument types (example C1)
17838 #. O[0-9] offset stack (displays)
17839 #. h[0-9] horizontal spacing stack (lists)
17840 #. o[0-9] offset (stack) (lists)
17841 #. t[0-9] tag stack (lists)
17842 #. v[0-9] vertical spacing stack (lists)
17843 #. w[0-9] width tag/label stack
17846 #. type: Plain text
17847 #: build/C/man7/mdoc.samples.7:2754
17849 "If a nonescaped register name is given in the argument list of a request "
17850 "unpredictable behavior will occur. In general, any time huge portions of "
17851 "text do not appear where expected in the output, or small strings such as "
17852 "list tags disappear, chances are there is a misunderstanding about an "
17853 "argument type in the argument list. Your mother never intended for you to "
17854 "remember this evil stuff - so here is a way to find out whether or not your "
17855 "arguments are valid: The E<.Ql \\&.Db> (debug) macro displays the "
17856 "interpretation of the argument list for most macros. Macros such as the "
17857 "E<.Ql \\&.Pp> (paragraph) macro do not contain debugging information. All "
17858 "of the callable macros do, and it is strongly advised whenever in doubt, "
17859 "turn on the E<.Ql \\&.Db> macro."
17863 #: build/C/man7/mdoc.samples.7:2755
17865 msgid "Usage: \\&.Db [on | off]"
17868 #. type: Plain text
17869 #: build/C/man7/mdoc.samples.7:2764
17871 "An example of a portion of text with the debug macro placed above and below "
17872 "an artificially created problem (a flag argument E<.Ql \\&aC> which should "
17873 "be E<.Ql \\e&aC> in order to work):"
17876 #. type: Plain text
17877 #: build/C/man7/mdoc.samples.7:2768
17881 "\\&.Op Fl aC Ar file )\n"
17885 #. type: Plain text
17886 #: build/C/man7/mdoc.samples.7:2771
17887 msgid "The resulting output:"
17890 #. type: Plain text
17891 #: build/C/man7/mdoc.samples.7:2786
17895 "DEBUG(argv) MACRO: `.Op' Line #: 2\n"
17896 "\tArgc: 1 Argv: `Fl' Length: 2\n"
17897 "\tSpace: `' Class: Executable\n"
17898 "\tArgc: 2 Argv: `aC' Length: 2\n"
17899 "\tSpace: `' Class: Executable\n"
17900 "\tArgc: 3 Argv: `Ar' Length: 2\n"
17901 "\tSpace: `' Class: Executable\n"
17902 "\tArgc: 4 Argv: `file' Length: 4\n"
17903 "\tSpace: ` ' Class: String\n"
17904 "\tArgc: 5 Argv: `)' Length: 1\n"
17905 "\tSpace: ` ' Class: Closing Punctuation or suffix\n"
17906 "\tMACRO REQUEST: .Op Fl aC Ar file )\n"
17910 #. type: Plain text
17911 #: build/C/man7/mdoc.samples.7:2813
17913 "The first line of information tells the name of the calling macro, here "
17914 "E<.Ql \\&.Op>, and the line number it appears on. If one or more files are "
17915 "involved (especially if text from another file is included) the line number "
17916 "may be bogus. If there is only one file, it should be accurate. The second "
17917 "line gives the argument count, the argument E<.Pq Ql \\&Fl> and its length. "
17918 "If the length of an argument is two characters, the argument is tested to "
17919 "see if it is executable (unfortunately, any register which contains a "
17920 "nonzero value appears executable). The third line gives the space allotted "
17921 "for a class, and the class type. The problem here is the argument aC should "
17922 "not be executable. The four types of classes are string, executable, "
17923 "closing punctuation and opening punctuation. The last line shows the entire "
17924 "argument list as it was read. In this next example, the offending E<.Ql "
17925 "\\&aC> is escaped:"
17928 #. type: Plain text
17929 #: build/C/man7/mdoc.samples.7:2817
17933 "\\&.Em An escaped \\e&aC\n"
17937 #. type: Plain text
17938 #: build/C/man7/mdoc.samples.7:2829
17942 "DEBUG(fargv) MACRO: `.Em' Line #: 2\n"
17943 "\tArgc: 1 Argv: `An' Length: 2\n"
17944 "\tSpace: ` ' Class: String\n"
17945 "\tArgc: 2 Argv: `escaped' Length: 7\n"
17946 "\tSpace: ` ' Class: String\n"
17947 "\tArgc: 3 Argv: `aC' Length: 2\n"
17948 "\tSpace: ` ' Class: String\n"
17949 "\tMACRO REQUEST: .Em An escaped &aC\n"
17953 #. type: Plain text
17954 #: build/C/man7/mdoc.samples.7:2839
17956 "The argument E<.Ql \\e&aC> shows up with the same length of 2 as the E<.Ql "
17957 "\\e&> sequence produces a zero width, but a register named E<.Ql \\e&aC> was "
17958 "not found and the type classified as string."
17961 #. type: Plain text
17962 #: build/C/man7/mdoc.samples.7:2841
17963 msgid "Other diagnostics consist of usage statements and are self explanatory."
17967 #: build/C/man7/mdoc.samples.7:2841
17969 msgid "GROFF, TROFF AND NROFF"
17972 #. type: Plain text
17973 #: build/C/man7/mdoc.samples.7:2846
17975 "The E<.Nm \\-mdoc> package does not need compatibility mode with E<.Xr "
17979 #. type: Plain text
17980 #: build/C/man7/mdoc.samples.7:2864
17982 "The package inhibits page breaks, and the headers and footers which normally "
17983 "occur at those breaks with E<.Xr nroff>, to make the manual more efficient "
17984 "for viewing on-line. At the moment, E<.Xr groff> with E<.Fl T Ns Ar ascii> "
17985 "does eject the imaginary remainder of the page at end of file. The "
17986 "inhibiting of the page breaks makes E<.Xr nroff Ns 'd> files unsuitable for "
17987 "hardcopy. There is a register named E<.Ql \\&cR> which can be set to zero "
17988 "in the site dependent style file E<.Pa /usr/src/share/tmac/doc-nroff> to "
17989 "restore the old style behavior."
17993 #: build/C/man7/mdoc.samples.7:2866
17995 msgid "Pa /usr/share/tmac/doc.tmac"
17998 #. type: Plain text
17999 #: build/C/man7/mdoc.samples.7:2868
18000 msgid "manual macro package"
18004 #: build/C/man7/mdoc.samples.7:2868
18006 msgid "Pa /usr/share/misc/mdoc.template"
18009 #. type: Plain text
18010 #: build/C/man7/mdoc.samples.7:2870
18011 msgid "template for writing a man page"
18015 #: build/C/man7/mdoc.samples.7:2870
18017 msgid "Pa /usr/share/examples/mdoc/*"
18020 #. type: Plain text
18021 #: build/C/man7/mdoc.samples.7:2872
18022 msgid "several example man pages"
18025 #. type: Plain text
18026 #: build/C/man7/mdoc.samples.7:2880
18028 "Undesirable hyphenation on the dash of a flag argument is not yet resolved, "
18029 "and causes occasional mishaps in the E<.Sx DESCRIPTION> section. (line "
18030 "break on the hyphen)."
18033 #. type: Plain text
18034 #: build/C/man7/mdoc.samples.7:2882
18035 msgid "Predefined strings are not declared in documentation."
18038 #. type: Plain text
18039 #: build/C/man7/mdoc.samples.7:2884
18040 msgid "Section 3f has not been added to the header routines."
18043 #. type: Plain text
18044 #: build/C/man7/mdoc.samples.7:2889
18045 msgid "E<.Ql \\&.Nm> font should be changed in E<.Sx NAME> section."
18048 #. type: Plain text
18049 #: build/C/man7/mdoc.samples.7:2896
18051 "E<.Ql \\&.Fn> needs to have a check to prevent splitting up if the line "
18052 "length is too short. Occasionally it separates the last parenthesis, and "
18053 "sometimes looks ridiculous if a line is in fill mode."
18056 #. type: Plain text
18057 #: build/C/man7/mdoc.samples.7:2901
18059 "The method used to prevent header and footer page breaks (other than the "
18060 "initial header and footer) when using nroff occasionally places an unsightly "
18061 "partially filled line (blank) at the would be bottom of the page."
18064 #. Note what happens if the parameter list overlaps a newline
18066 #. to make sure a line boundary is crossed:
18068 #. \&.Fn struct\e\ dictionarytable\e\ *dictionarylookup struct\e\ dictionarytable\e\ *tab[]
18071 #. produces, nudge nudge,
18072 #. .Fn struct\ dictionarytable\ *dictionarylookup char\ *h struct\ dictionarytable\ *tab[] ,
18073 #. .Fn struct\ dictionarytable\ *dictionarylookup char\ *h struct\ dictionarytable\ *tab[] ,
18075 #. .Fn struct\ dictionarytable\ *dictionarylookup char\ *h struct\ dictionarytable\ *tab[] .
18077 #. If double quotes are used, for example:
18079 #. \&.Fn \*qstruct dictionarytable *dictionarylookup\*q \*qchar *h\*q \*qstruct dictionarytable *tab[]\*q
18082 #. produces, nudge nudge,
18083 #. .Fn "struct dictionarytable *dictionarylookup" "char *h" "struct dictionarytable *tab[]" ,
18085 #. .Fn "struct dictionarytable *dictionarylookup" "char *h" "struct dictionarytable *tab[]" ,
18087 #. .Fn "struct dictionarytable *dictionarylookup" "char *h" "struct dictionarytable *tab[]" .
18089 #. Not a pretty sight...
18090 #. In a paragraph, a long parameter containing unpaddable spaces as
18091 #. in the former example will cause
18093 #. to break the line and spread
18094 #. the remaining words out.
18095 #. The latter example will adjust nicely to
18096 #. justified margins, but may break in between an argument and its
18100 #. the right margin adjustment is normally ragged and the problem is
18102 #. type: Plain text
18103 #: build/C/man7/mdoc.samples.7:2942
18105 "The list and display macros to not do any keeps and certainly should be able "
18109 #. type: Plain text
18110 #: build/C/man7/mdoc.samples.7:2947
18111 msgid "E<.Xr man 1>, E<.Xr troff 1>, E<.Xr groff_mdoc 7>, E<.Xr mdoc 7>"