2 .\" (C) Copyright 1992-1999 Rickard E. Faith and David A. Wheeler
3 .\" (faith@cs.unc.edu and dwheeler@ida.org)
4 .\" and (C) Copyright 2007 Michael Kerrisk <mtk.manpages@gmail.com>
6 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
8 .\" 2007-05-30 created by mtk, using text from old man.7 plus
9 .\" rewrites and additional text.
11 .TH man-pages 7 (date) "Linux man-pages (unreleased)"
13 man-pages \- conventions for writing Linux man pages
19 This page describes the conventions that should be employed
20 when writing man pages for the Linux \fIman-pages\fP project,
21 which documents the user-space API provided by the Linux kernel
22 and the GNU C library.
23 The project thus provides most of the pages in Section 2,
24 many of the pages that appear in Sections 3, 4, and 7,
25 and a few of the pages that appear in Sections 1, 5, and 8
26 of the man pages on a Linux system.
27 The conventions described on this page may also be useful
28 for authors writing man pages for other projects.
29 .SS Sections of the manual pages
30 The manual Sections are traditionally defined as follows:
32 .B 1 User commands (Programs)
33 Commands that can be executed by the user from within
37 Functions which wrap operations performed by the kernel.
40 All library functions excluding the system call wrappers
45 .B 4 Special files (devices)
48 which allow to access to devices through the kernel.
50 .B 5 File formats and configuration files
51 Describes various human-readable file formats and configuration files.
54 Games and funny little programs available on the system.
56 .B 7 Overview, conventions, and miscellaneous
57 Overviews or descriptions of various topics, conventions, and protocols,
58 character set standards, the standard filesystem layout, and miscellaneous
61 .B 8 System management commands
64 many of which only root can execute.
66 .\" .B 9 Kernel routines
67 .\" This is an obsolete manual section.
68 .\" Once it was thought a good idea to document the Linux kernel here,
69 .\" but in fact very little has been documented, and the documentation
70 .\" that exists is outdated already.
71 .\" There are better sources of
72 .\" information for kernel developers.
74 New manual pages should be marked up using the
78 This choice is mainly for consistency: the vast majority of
79 existing Linux manual pages are marked up using these macros.
80 .SS Conventions for source file layout
81 Please limit source code line length to no more than about 75 characters
83 This helps avoid line-wrapping in some mail clients when patches are
86 The first command in a man page should be a
92 .I "title section date source manual-section"
95 The arguments of the command are as follows:
98 The title of the man page, written in all caps (e.g.,
102 The section number in which the man page should be placed (e.g.,
106 The date of the last nontrivial change that was made to the man page.
109 project, the necessary updates to these timestamps are handled
110 automatically by scripts, so there is no need to manually update
111 them as part of a patch.)
112 Dates should be written in the form YYYY-MM-DD.
115 The name and version of the project that provides the manual page
116 (not necessarily the package that provides the functionality).
119 Normally, this should be empty,
120 since the default value will be good.
122 .SS Sections within a manual page
123 The list below shows conventional or suggested sections.
124 Most manual pages should include at least the
127 Arrange a new manual page so that sections
128 are placed in the order shown in the list.
134 LIBRARY [Normally only in Sections 2, 3]
136 CONFIGURATION [Normally only in Section 4]
138 OPTIONS [Normally only in Sections 1, 8]
139 EXIT STATUS [Normally only in Sections 1, 8]
140 RETURN VALUE [Normally only in Sections 2, 3]
141 .\" May 07: Few current man pages have an ERROR HANDLING section,,,
143 ERRORS [Typically only in Sections 2, 3]
144 .\" May 07: Almost no current man pages have a USAGE section,,,
147 .\" May 07: Almost no current man pages have a SECURITY section,,,
151 ATTRIBUTES [Normally only in Sections 2, 3]
152 VERSIONS [Normally only in Sections 2, 3]
159 .\" AUTHORS sections are discouraged
160 AUTHORS [Discouraged]
161 REPORTING BUGS [Not used in man-pages]
162 COPYRIGHT [Not used in man-pages]
167 .IR "Where a traditional heading would apply" ", " "please use it" ;
168 this kind of consistency can make the information easier to understand.
169 If you must, you can create your own
170 headings if they make things easier to understand (this can
171 be especially useful for pages in Sections 4 and 5).
172 However, before doing this, consider whether you could use the
173 traditional headings, with some subsections (\fI.SS\fP) within
176 The following list elaborates on the contents of each of
180 The name of this manual page.
184 for important details of the line(s) that should follow the
185 \fB.SH NAME\fP command.
186 All words in this line (including the word immediately
187 following the "\e\-") should be in lowercase,
188 except where English or technical terminological convention
192 The library providing a symbol.
194 It shows the common name of the library,
196 the name of the library file
197 and, if needed, the linker flag needed to link a program against it:
198 .RI ( libfoo "[, " \-lfoo ]).
201 A brief summary of the command or function's interface.
203 For commands, this shows the syntax of the command and its arguments
205 boldface is used for as-is text and italics are used to
206 indicate replaceable arguments.
207 Brackets ([]) surround optional arguments, vertical bars (|)
208 separate choices, and ellipses (\&...) can be repeated.
209 For functions, it shows any required data declarations or
211 directives, followed by the function declaration.
213 Where a feature test macro must be defined in order to obtain
214 the declaration of a function (or a variable) from a header file,
215 then the SYNOPSIS should indicate this, as described in
216 .BR feature_test_macros (7).
217 .\" FIXME . Say something here about compiler options
220 Configuration details for a device.
222 This section normally appears only in Section 4 pages.
225 An explanation of what the program, function, or format does.
227 Discuss how it interacts with files and standard input, and what it
228 produces on standard output or standard error.
229 Omit internals and implementation details unless they're critical for
230 understanding the interface.
231 Describe the usual case;
232 for information on command-line options of a program use the
235 .\" If there is some kind of input grammar or complex set of subcommands,
236 .\" consider describing them in a separate
238 .\" section (and just place an overview in the
242 When describing new behavior or new flags for
243 a system call or library function,
244 be careful to note the kernel or C library version
245 that introduced the change.
246 The preferred method of noting this information for flags is as part of a
248 list, in the following form (here, for a new system call flag):
251 .BR XYZ_FLAG " (since Linux 3.7)"
252 Description of flag...
255 Including version information is especially useful to users
256 who are constrained to using older kernel or C library versions
257 (which is typical in embedded systems, for example).
260 A description of the command-line options accepted by a
261 program and how they change its behavior.
263 This section should appear only for Section 1 and 8 manual pages.
266 .\" describes the grammar of any sublanguage this implements.
269 A list of the possible exit status values of a program and
270 the conditions that cause these values to be returned.
272 This section should appear only for Section 1 and 8 manual pages.
275 For Section 2 and 3 pages, this section gives a
276 list of the values the library routine will return to the caller
277 and the conditions that cause these values to be returned.
280 For Section 2 and 3 manual pages, this is a list of the
281 values that may be placed in
283 in the event of an error, along with information about the cause
286 Where several different conditions produce the same error,
287 the preferred approach is to create separate list entries
288 (with duplicate error names) for each of the conditions.
289 This makes the separate conditions clear, may make the list easier to read,
290 and allows metainformation
291 (e.g., kernel version number where the condition first became applicable)
292 to be more easily marked for each condition.
294 .IR "The error list should be in alphabetical order" .
297 A list of all environment variables that affect the program or function
298 and how they affect it.
301 A list of the files the program or function uses, such as
302 configuration files, startup files,
303 and files the program directly operates on.
305 Give the full pathname of these files, and use the installation
306 process to modify the directory part to match user preferences.
307 For many programs, the default installation location is in
309 so your base manual page should use
312 .\" May 07: Almost no current man pages have a DIAGNOSTICS section;
313 .\" "RETURN VALUE" or "EXIT STATUS" is preferred.
316 .\" gives an overview of the most common error messages and how to
318 .\" You don't need to explain system error messages
319 .\" or fatal signals that can appear during execution of any program
320 .\" unless they're special in some way to the program.
322 .\" May 07: Almost no current man pages have a SECURITY section.
325 .\"discusses security issues and implications.
326 .\"Warn about configurations or environments that should be avoided,
327 .\"commands that may have security implications, and so on, especially
328 .\"if they aren't obvious.
329 .\"Discussing security in a separate section isn't necessary;
330 .\"if it's easier to understand, place security information in the
331 .\"other sections (such as the
336 .\" However, please include security information somewhere!
339 A summary of various attributes of the function(s) documented on this page.
345 A summary of systems where the API performs differently,
346 or where there's a similar API.
349 A description of any standards or conventions that relate to the function
350 or command described by the manual page.
352 The preferred terms to use for the various standards are listed as
356 This section should note the current standards to which the API conforms to.
358 If the API is not governed by any standards but commonly
359 exists on other systems, note them.
360 If the call is Linux-specific or GNU-specific, note this.
361 If it's available in the BSDs, note that.
363 If this section consists of just a list of standards
364 (which it commonly does),
365 terminate the list with a period (\[aq].\[aq]).
368 A brief summary of the Linux kernel or glibc versions where a
369 system call or library function appeared,
370 or changed significantly in its operation.
372 As a general rule, every new interface should
373 include a HISTORY section in its manual page.
375 many existing manual pages don't include this information
376 (since there was no policy to do so when they were written).
377 Patches to remedy this are welcome,
378 but, from the perspective of programmers writing new code,
379 this information probably matters only in the case of kernel
380 interfaces that have been added in Linux 2.4 or later
381 (i.e., changes since Linux 2.2),
382 and library functions that have been added to glibc since glibc 2.1
383 (i.e., changes since glibc 2.0).
387 manual page also provides information about kernel versions
388 in which various system calls first appeared.
390 Old versions of standards should be mentioned here,
391 rather than in STANDARDS,
393 SUS, SUSv2, and XPG, or the SVr4 and 4.xBSD implementation standards.
398 For Section 2 and 3 man pages you may find it useful to include
399 subsections (\fBSS\fP) named \fILinux Notes\fP and \fIglibc Notes\fP.
401 In Section 2, use the heading
402 .I "C library/kernel differences"
403 to mark off notes that describe the differences (if any) between
404 the C library wrapper function for a system call and
405 the raw system call interface provided by the kernel.
408 Warnings about typical user misuse of an API,
409 that don't constitute an API bug or design defect.
412 A list of limitations, known defects or inconveniences,
413 and other questionable activities.
416 One or more examples demonstrating how this function, file, or
419 For details on writing example programs,
420 see \fIExample programs\fP below.
423 A list of authors of the documentation or program.
425 \fBUse of an AUTHORS section is strongly discouraged\fP.
426 Generally, it is better not to clutter every page with a list
427 of (over time potentially numerous) authors;
428 if you write or significantly amend a page,
429 add a copyright notice as a comment in the source file.
430 If you are the author of a device driver and want to include
431 an address for reporting bugs, place this under the BUGS section.
436 project doesn't use a REPORTING BUGS section in manual pages.
437 Information on reporting bugs is instead supplied in the
438 script-generated COLOPHON section.
439 However, various projects do use a REPORTING BUGS section.
440 It is recommended to place it near the foot of the page.
445 project doesn't use a COPYRIGHT section in manual pages.
446 Copyright information is instead maintained in the page source.
447 In pages where this section is present,
448 it is recommended to place it near the foot of the page, just above SEE ALSO.
451 A comma-separated list of related man pages, possibly followed by
452 other related pages or documents.
454 The list should be ordered by section number and
455 then alphabetically by name.
456 Do not terminate this list with a period.
458 Where the SEE ALSO list contains many long manual page names,
459 to improve the visual result of the output, it may be useful to employ the
461 (don't right justify)
466 Hyphenation of individual page names can be prevented
467 by preceding words with the string "\e%".
469 Given the distributed, autonomous nature of FOSS projects
470 and their documentation, it is sometimes necessary\[em]and in many cases
471 desirable\[em]that the SEE ALSO section includes references to
472 manual pages provided by other projects.
473 .SH FORMATTING AND WORDING CONVENTIONS
474 The following subsections note some details for preferred formatting and
475 wording conventions in various sections of the pages in the
479 Wrap the function prototype(s) in a
481 pair to prevent filling.
483 In general, where more than one function prototype is shown in the SYNOPSIS,
484 the prototypes should
486 be separated by blank lines.
487 However, blank lines (achieved using
489 may be added in the following cases:
491 to separate long lists of function prototypes into related groups
495 in other cases that may improve readability.
497 In the SYNOPSIS, a long function prototype may need to be
498 continued over to the next line.
499 The continuation line is indented according to the following rules:
501 If there is a single such prototype that needs to be continued,
502 then align the continuation line so that when the page is
503 rendered on a fixed-width font device (e.g., on an xterm) the
504 continuation line starts just below the start of the argument
505 list in the line above.
506 (Exception: the indentation may be
507 adjusted if necessary to prevent a very long continuation line
508 or a further continuation line where the function prototype is
514 .BI "int tcsetattr(int " fd ", int " optional_actions ,
515 .BI " const struct termios *" termios_p );
519 But, where multiple functions in the SYNOPSIS require
520 continuation lines, and the function names have different
521 lengths, then align all continuation lines to start in the
523 This provides a nicer rendering in PDF output
524 (because the SYNOPSIS uses a variable width font where
525 spaces render narrower than most characters).
530 .BI "int getopt(int " argc ", char * const " argv[] ,
531 .BI " const char *" optstring );
532 .BI "int getopt_long(int " argc ", char * const " argv[] ,
533 .BI " const char *" optstring ,
534 .BI " const struct option *" longopts ", int *" longindex );
538 The preferred wording to describe how
542 is set to indicate the error"
544 .\" Before man-pages 5.11, many different wordings were used, which
545 .\" was confusing, and potentially made scripted edits more difficult.
546 This wording is consistent with the wording used in both POSIX.1 and FreeBSD.
548 .\" See man-pages commit c466875ecd64ed3d3cd3e578406851b7dfb397bf
551 Wrap the table in this section in a
553 pair to disable text filling and a
555 pair to disable hyphenation.
557 Ensure that the table occupies the full page width through the use of an
559 description for one of the columns
560 (usually the first column,
561 though in some cases the last column if it contains a lot of text).
565 macro pairs to allow table cells to be broken over multiple lines
566 (also bearing in mind that pages may sometimes be rendered to a
567 width of less than 80 columns).
569 For examples of all of the above, see the source code of various pages.
571 The following subsections describe the preferred style for the
574 For details not covered below, the Chicago Manual of Style
575 is usually a good source;
576 try also grepping for preexisting usage in the project source tree.
577 .SS Use of gender-neutral language
578 As far as possible, use gender-neutral language in the text of man
580 Use of "they" ("them", "themself", "their") as a gender-neutral singular
581 pronoun is acceptable.
583 .SS Formatting conventions for manual pages describing commands
584 For manual pages that describe a command (typically in Sections 1 and 8),
585 the arguments are always specified using italics,
586 .IR "even in the SYNOPSIS section" .
588 The name of the command, and its options, should
589 always be formatted in bold.
591 .SS Formatting conventions for manual pages describing functions
592 For manual pages that describe functions (typically in Sections 2 and 3),
593 the arguments are always specified using italics,
594 .IR "even in the SYNOPSIS section" ,
595 where the rest of the function is specified in bold:
597 .BI " int myfunction(int " argc ", char **" argv );
599 Variable names should, like argument names, be specified in italics.
601 Any reference to the subject of the current manual page
602 should be written with the name in bold followed by
603 a pair of parentheses in Roman (normal) font.
606 man page, references to the subject of the page would be written as:
608 The preferred way to write this in the source file is:
614 (Using this format, rather than the use of "\efB...\efP()"
615 makes it easier to write tools that parse man page source files.)
617 .SS Use semantic newlines
618 In the source of a manual page,
619 new sentences should be started on new lines,
620 long sentences should be split into lines at clause breaks
621 (commas, semicolons, colons, and so on),
622 and long clauses should be split at phrase boundaries.
623 This convention, sometimes known as "semantic newlines",
624 makes it easier to see the effect of patches,
625 which often operate at the level of
626 individual sentences, clauses, or phrases.
629 There are different kinds of lists:
632 These are used for a list of tags and their descriptions.
633 When the tags are constants (either macros or numbers)
639 An example is this "Tagged paragraphs" subsection is itself.
642 Elements are preceded by a number in parentheses (1), (2).
643 These represent a set of steps that have an order.
645 When there are substeps,
646 they will be numbered like (4.2).
649 Elements are preceded by a number (index) in square brackets [4], [5].
650 These represent fields in a set.
651 The first index will be:
655 When it represents fields of a C data structure,
656 to be consistent with arrays.
660 When it represents fields of a file,
661 to be consistent with tools like
667 Elements are preceded by a letter in parentheses (a), (b).
668 These represent a set of (normally) exclusive alternatives.
671 Elements are preceded by bullet symbols
673 Anything that doesn't fit elsewhere is
674 usually covered by this type of list.
678 but the syntax is identical to "positional lists".
680 There should always be exactly
681 2 spaces between the list symbol and the elements.
682 This doesn't apply to "tagged paragraphs",
683 which use the default indentation rules.
685 .SS Formatting conventions (general)
686 Paragraphs should be separated by suitable markers (usually either
692 separate paragraphs using blank lines, as this results in poor rendering
693 in some output formats (such as PostScript and PDF).
695 Filenames (whether pathnames, or references to header files)
696 are always in italics (e.g.,
698 except in the SYNOPSIS section, where included files are in bold (e.g.,
699 .BR "#include <stdio.h>" ).
700 When referring to a standard header file include,
701 specify the header file surrounded by angle brackets,
702 in the usual C way (e.g.,
705 Special macros, which are usually in uppercase, are in bold (e.g.,
707 Exception: don't boldface NULL.
709 When enumerating a list of error codes, the codes are in bold (this list
714 Complete commands should, if long,
715 be written as an indented line on their own,
716 with a blank line before and after the command, for example
724 If the command is short, then it can be included inline in the text,
725 in italic format, for example,
726 .IR "man 7 man-pages" .
727 In this case, it may be worth using nonbreaking spaces
728 (\e[ti]) at suitable places in the command.
729 Command options should be written in italics (e.g.,
732 Expressions, if not written on a separate indented line, should
733 be specified in italics.
734 Again, the use of nonbreaking spaces may be appropriate
735 if the expression is inlined with normal text.
737 When showing example shell sessions,
738 user input should be formatted in bold,
744 Thu Jul 7 13:01:27 CEST 2016
748 Any reference to another man page
749 should be written with the name in bold,
751 followed by the section number,
752 formatted in Roman (normal) font, without any
753 separating spaces (e.g.,
755 The preferred way to write this in the source file is:
761 (Including the section number in cross references lets tools like
763 create properly hyperlinked pages.)
765 Control characters should be written in bold face,
766 with no quotes; for example,
769 Starting with release 2.59,
771 follows American spelling conventions
772 (previously, there was a random mix of British and American spellings);
773 please write all new pages and patches according to these conventions.
775 Aside from the well-known spelling differences,
776 there are a few other subtleties to watch for:
778 American English tends to use the forms "backward", "upward", "toward",
780 rather than the British forms "backwards", "upwards", "towards", and so on.
782 Opinions are divided on "acknowledgement" vs "acknowledgment".
783 The latter is predominant, but not universal usage in American English.
784 POSIX and the BSD license use the former spelling.
785 In the Linux man-pages project, we use "acknowledgement".
786 .SS BSD version numbers
787 The classical scheme for writing BSD version numbers is
791 is the version number (e.g., 4.2BSD).
795 In subsection ("SS") headings,
796 capitalize the first word in the heading, but otherwise use lowercase,
797 except where English usage (e.g., proper nouns) or programming
798 language requirements (e.g., identifier names) dictate otherwise.
803 \&.SS Unicode under Linux
807 .SS Indentation of structure definitions, shell session logs, and so on
808 When structure definitions, shell session logs, and so on are included
809 in running text, indent them by 4 spaces (i.e., a block enclosed by
813 format them using the
817 macros, and surround them with suitable paragraph markers (either
829 main(int argc, char *argv[])
839 The following table lists some preferred terms to use in man pages,
840 mainly to ensure consistency across pages.
846 Term Avoid using Notes
851 For the UNIX Epoch (00:00:00, 1 Jan 1970 UTC)
854 filesystem file system
857 lowercase lower case, lower-case
860 pseudoterminal pseudo-terminal
870 saved set-group-ID T{
878 set-group-ID set-GID, setgid
879 set-user-ID set-UID, setuid
888 symbolic link symlink
891 uppercase upper case, upper-case
896 Except if referring to result of "uname\ \-m" or similar
901 See also the discussion
902 .I Hyphenation of attributive compounds
905 The following table lists some terms to avoid using in man pages,
906 along with some suggested alternatives,
907 mainly to ensure consistency across pages.
913 Avoid Use instead Notes
916 same for 8-bit, 16-bit, etc.
918 current process calling process T{
919 A common mistake made by kernel programmers when writing man pages
922 man page, manual page
924 minus infinity negative infinity
925 non-root unprivileged user
926 non-superuser unprivileged user
927 nonprivileged unprivileged
929 plus infinity positive infinity
938 Use the correct spelling and case for trademarks.
939 The following is a list of the correct spellings of various
940 relevant trademarks that are sometimes misspelled:
949 .SS NULL, NUL, null pointer, and null byte
952 is a pointer that points to nothing,
953 and is normally indicated by the constant
959 a byte with the value 0, represented in C via the character constant
962 The preferred term for the pointer is "null pointer" or simply "NULL";
963 avoid writing "NULL pointer".
965 The preferred term for the byte is "null byte".
966 Avoid writing "NUL", since it is too easily confused with "NULL".
967 Avoid also the terms "zero byte" and "null character".
968 The byte that terminates a C string should be described
969 as "the terminating null byte";
970 strings may be described as "null-terminated",
971 but avoid the use of "NUL-terminated".
973 For hyperlinks, use the
978 This produces proper hyperlinks that can be used in a web browser,
979 when rendering a page with, say:
983 BROWSER=firefox man -H pagename
986 .SS Use of e.g., i.e., etc., a.k.a., and similar
987 In general, the use of abbreviations such as "e.g.", "i.e.", "etc.",
988 "cf.", and "a.k.a." should be avoided,
989 in favor of suitable full wordings
990 ("for example", "that is", "and so on", "compare to", "also known as").
992 The only place where such abbreviations may be acceptable is in
994 parenthetical asides (e.g., like this one).
996 Always include periods in such abbreviations, as shown here.
997 In addition, "e.g." and "i.e." should always be followed by a comma.
999 The way to write an em-dash\[em]the glyph that appears
1000 at either end of this subphrase\[em]in *roff is with the macro "\e[em]".
1001 (On an ASCII terminal, an em-dash typically renders as two hyphens,
1002 but in other typographical contexts it renders as a long dash.)
1003 Em-dashes should be written
1006 .SS Hyphenation of attributive compounds
1007 Compound terms should be hyphenated when used attributively
1008 (i.e., to qualify a following noun). Some examples:
1013 command-line argument
1014 floating-point number
1017 wide-character string
1019 .SS Hyphenation with multi, non, pre, re, sub, and so on
1020 The general tendency in modern English is not to hyphenate
1021 after prefixes such as "multi", "non", "pre", "re", "sub", and so on.
1022 Manual pages should generally follow this rule when these prefixes are
1023 used in natural English constructions with simple suffixes.
1024 The following list gives some examples of the preferred forms:
1050 Hyphens should be retained when the prefixes are used in nonstandard
1051 English words, with trademarks, proper nouns, acronyms, or compound terms.
1062 Finally, note that "re-create" and "recreate" are two different verbs,
1063 and the former is probably what you want.
1065 .SS Generating optimal glyphs
1066 Where a real minus character is required (e.g., for numbers such as \-1,
1067 for man page cross references such as
1069 or when writing options that have a leading dash, such as in
1071 use the following form in the man page source:
1079 This guideline applies also to code examples.
1081 The use of real minus signs serves the following purposes:
1082 .\" https://lore.kernel.org/linux-man/20210121061158.5ul7226fgbrmodbt@localhost.localdomain/
1084 To provide better renderings on various targets other than
1086 notably in PDF and on Unicode/UTF\-8-capable terminals.
1088 To generate glyphs that when copied from rendered pages will
1089 produce real minus signs when pasted into a terminal.
1091 To produce unslanted single quotes that render well in ASCII, UTF-8, and PDF,
1092 use "\e[aq]" ("apostrophe quote"); for example
1102 is the quoted character.
1103 This guideline applies also to character constants used in code examples.
1105 Where a proper caret (\[ha]) that renders well in both a terminal and PDF
1106 is required, use "\\[ha]".
1107 This is especially necessary in code samples,
1108 to get a nicely rendered caret when rendering to PDF.
1110 Using a naked "\[ti]" character results in a poor rendering in PDF.
1111 Instead use "\\[ti]".
1112 This is especially necessary in code samples,
1113 to get a nicely rendered tilde when rendering to PDF.
1115 .SS Example programs and shell sessions
1116 Manual pages may include example programs demonstrating how to
1117 use a system call or library function.
1118 However, note the following:
1120 Example programs should be written in C.
1122 An example program is necessary and useful only if it demonstrates
1123 something beyond what can easily be provided in a textual
1124 description of the interface.
1125 An example program that does nothing
1126 other than call an interface usually serves little purpose.
1128 Example programs should ideally be short
1129 (e.g., a good example can often be provided in less than 100 lines of code),
1130 though in some cases longer programs may be necessary
1131 to properly illustrate the use of an API.
1133 Expressive code is appreciated.
1135 Comments should included where helpful.
1136 Complete sentences in free-standing comments should be
1137 terminated by a period.
1138 Periods should generally be omitted in "tag" comments
1139 (i.e., comments that are placed on the same line of code);
1140 such comments are in any case typically brief phrases
1141 rather than complete sentences.
1143 Example programs should do error checking after system calls and
1144 library function calls.
1146 Example programs should be complete, and compile without
1147 warnings when compiled with \fIcc\ \-Wall\fP.
1149 Where possible and appropriate, example programs should allow
1150 experimentation, by varying their behavior based on inputs
1151 (ideally from command-line arguments, or alternatively, via
1152 input read by the program).
1154 Example programs should be laid out according to Kernighan and
1155 Ritchie style, with 4-space indents.
1156 (Avoid the use of TAB characters in source code!)
1157 The following command can be used to format your source code to
1158 something close to the preferred style:
1162 indent \-npro \-kr \-i4 \-ts4 \-sob \-l72 \-ss \-nut \-psl prog.c
1166 For consistency, all example programs should terminate using either of:
1175 Avoid using the following forms to terminate a program:
1185 If there is extensive explanatory text before the
1186 program source code, mark off the source code
1187 with a subsection heading
1188 .IR "Program source" ,
1193 \&.SS Program source
1197 Always do this if the explanatory text includes a shell session log.
1199 If you include a shell session log demonstrating the use of a program
1200 or other system feature:
1202 Place the session log above the source code listing.
1204 Indent the session log by four spaces.
1206 Boldface the user input text,
1207 to distinguish it from output produced by the system.
1209 For some examples of what example programs should look like, see
1214 For canonical examples of how man pages in the
1216 package should look, see