1MAN-PAGES(7) Linux Programmer's Manual MAN-PAGES(7)
2
6 man-pages - conventions for writing Linux man pages
7
9 man [section] title
10
12 This page describes the conventions that should be employed when writ‐
13 ing man pages for the Linux man-pages project, which documents the
14 user-space API provided by the Linux kernel and the GNU C library. The
15 project thus provides most of the pages in Section 2, many of the pages
16 that appear in Sections 3, 4, and 7, and a few of the pages that appear
17 in Sections 1, 5, and 8 of the man pages on a Linux system. The con‐
18 ventions described on this page may also be useful for authors writing
19 man pages for other projects.
20 Sections of the manual pages
22 The manual Sections are traditionally defined as follows:
23 1 User commands (Programs)
25 Commands that can be executed by the user from within a shell.
26 2 System calls
28 Functions which wrap operations performed by the kernel.
29 3 Library calls
31 All library functions excluding the system call wrappers (Most
32 of the libc functions).
33 4 Special files (devices)
35 Files found in /dev which allow to access to devices through the
36 kernel.
37 5 File formats and configuration files
39 Describes various human-readable file formats and configuration
40 files.
41 6 Games
43 Games and funny little programs available on the system.
44 7 Overview, conventions, and miscellaneous
46 Overviews or descriptions of various topics, conventions, and
47 protocols, character set standards, the standard filesystem lay‐
48 out, and miscellaneous other things.
49 8 System management commands
51 Commands like mount(8), many of which only root can execute.
52 Macro package
54 New manual pages should be marked up using the groff an.tmac package
55 described in man(7). This choice is mainly for consistency: the vast
56 majority of existing Linux manual pages are marked up using these
57 macros.
58 Conventions for source file layout
60 Please limit source code line length to no more than about 75 charac‐
61 ters wherever possible. This helps avoid line-wrapping in some mail
62 clients when patches are submitted inline.
63 Title line
65 The first command in a man page should be a TH command:
66 .TH title section date source manual
68 The arguments of the command are as follows:
70 title The title of the man page, written in all caps (e.g., MAN-
72 PAGES).
73 section
75 The section number in which the man page should be placed (e.g.,
76 7).
77 date The date of the last nontrivial change that was made to the man
79 page. (Within the man-pages project, the necessary updates to
80 these timestamps are handled automatically by scripts, so there
81 is no need to manually update them as part of a patch.) Dates
82 should be written in the form YYYY-MM-DD.
83 source The source of the command, function, or system call.
85 For those few man-pages pages in Sections 1 and 8, probably you
87 just want to write GNU.
88 For system calls, just write Linux. (An earlier practice was to
90 write the version number of the kernel from which the manual
91 page was being written/checked. However, this was never done
92 consistently, and so was probably worse than including no ver‐
93 sion number. Henceforth, avoid including a version number.)
94 For library calls that are part of glibc or one of the other
96 common GNU libraries, just use GNU C Library, GNU, or an empty
97 string.
98 For Section 4 pages, use Linux.
100 In cases of doubt, just write Linux, or GNU.
102 manual The title of the manual (e.g., for Section 2 and 3 pages in the
104 man-pages package, use Linux Programmer's Manual).
105 Sections within a manual page
107 The list below shows conventional or suggested sections. Most manual
108 pages should include at least the highlighted sections. Arrange a new
109 manual page so that sections are placed in the order shown in the list.
110 NAME
112 SYNOPSIS
113 CONFIGURATION [Normally only in Section 4]
114 DESCRIPTION
115 OPTIONS [Normally only in Sections 1, 8]
116 EXIT STATUS [Normally only in Sections 1, 8]
117 RETURN VALUE [Normally only in Sections 2, 3]
118 ERRORS [Typically only in Sections 2, 3]
119 ENVIRONMENT
120 FILES
121 VERSIONS [Normally only in Sections 2, 3]
122 ATTRIBUTES [Normally only in Sections 2, 3]
123 CONFORMING TO
124 NOTES
125 BUGS
126 EXAMPLES
127 AUTHORS [Discouraged]
128 REPORTING BUGS [Not used in man-pages]
129 COPYRIGHT [Not used in man-pages]
130 SEE ALSO
131 Where a traditional heading would apply, please use it; this kind of
133 consistency can make the information easier to understand. If you
134 must, you can create your own headings if they make things easier to
135 understand (this can be especially useful for pages in Sections 4 and
136 5). However, before doing this, consider whether you could use the
137 traditional headings, with some subsections (.SS) within those sec‐
138 tions.
139 The following list elaborates on the contents of each of the above sec‐
141 tions.
142 NAME The name of this manual page.
144 See man(7) for important details of the line(s) that should fol‐
146 low the .SH NAME command. All words in this line (including the
147 word immediately following the "\-") should be in lowercase, ex‐
148 cept where English or technical terminological convention dic‐
149 tates otherwise.
150 SYNOPSIS
152 A brief summary of the command or function's interface.
153 For commands, this shows the syntax of the command and its argu‐
155 ments (including options); boldface is used for as-is text and
156 italics are used to indicate replaceable arguments. Brackets
157 ([]) surround optional arguments, vertical bars (|) separate
158 choices, and ellipses (...) can be repeated. For functions, it
159 shows any required data declarations or #include directives,
160 followed by the function declaration.
161 Where a feature test macro must be defined in order to obtain
163 the declaration of a function (or a variable) from a header
164 file, then the SYNOPSIS should indicate this, as described in
165 feature_test_macros(7).
166 CONFIGURATION
168 Configuration details for a device.
169 This section normally appears only in Section 4 pages.
171 DESCRIPTION
173 An explanation of what the program, function, or format does.
174 Discuss how it interacts with files and standard input, and what
176 it produces on standard output or standard error. Omit inter‐
177 nals and implementation details unless they're critical for un‐
178 derstanding the interface. Describe the usual case; for infor‐
179 mation on command-line options of a program use the OPTIONS sec‐
180 tion.
181 When describing new behavior or new flags for a system call or
183 library function, be careful to note the kernel or C library
184 version that introduced the change. The preferred method of
185 noting this information for flags is as part of a .TP list, in
186 the following form (here, for a new system call flag):
187 XYZ_FLAG (since Linux 3.7)
189 Description of flag...
190 Including version information is especially useful to users who
192 are constrained to using older kernel or C library versions
193 (which is typical in embedded systems, for example).
194 OPTIONS
196 A description of the command-line options accepted by a program
197 and how they change its behavior.
198 This section should appear only for Section 1 and 8 manual
200 pages.
201 EXIT STATUS
203 A list of the possible exit status values of a program and the
204 conditions that cause these values to be returned.
205 This section should appear only for Section 1 and 8 manual
207 pages.
208 RETURN VALUE
210 For Section 2 and 3 pages, this section gives a list of the val‐
211 ues the library routine will return to the caller and the condi‐
212 tions that cause these values to be returned.
213 ERRORS For Section 2 and 3 manual pages, this is a list of the values
215 that may be placed in errno in the event of an error, along with
216 information about the cause of the errors.
217 Where several different conditions produce the same error, the
219 preferred approach is to create separate list entries (with du‐
220 plicate error names) for each of the conditions. This makes the
221 separate conditions clear, may make the list easier to read, and
222 allows metainformation (e.g., kernel version number where the
223 condition first became applicable) to be more easily marked for
224 each condition.
225 The error list should be in alphabetical order.
227 ENVIRONMENT
229 A list of all environment variables that affect the program or
230 function and how they affect it.
231 FILES A list of the files the program or function uses, such as con‐
233 figuration files, startup files, and files the program directly
234 operates on.
235 Give the full pathname of these files, and use the installation
237 process to modify the directory part to match user preferences.
238 For many programs, the default installation location is in
239 /usr/local, so your base manual page should use /usr/local as
240 the base.
241 ATTRIBUTES
243 A summary of various attributes of the function(s) documented on
244 this page. See attributes(7) for further details.
245 VERSIONS
247 A brief summary of the Linux kernel or glibc versions where a
248 system call or library function appeared, or changed signifi‐
249 cantly in its operation.
250 As a general rule, every new interface should include a VERSIONS
252 section in its manual page. Unfortunately, many existing manual
253 pages don't include this information (since there was no policy
254 to do so when they were written). Patches to remedy this are
255 welcome, but, from the perspective of programmers writing new
256 code, this information probably matters only in the case of ker‐
257 nel interfaces that have been added in Linux 2.4 or later (i.e.,
258 changes since kernel 2.2), and library functions that have been
259 added to glibc since version 2.1 (i.e., changes since glibc
260 2.0).
261 The syscalls(2) manual page also provides information about ker‐
263 nel versions in which various system calls first appeared.
264 CONFORMING TO
266 A description of any standards or conventions that relate to the
267 function or command described by the manual page.
268 The preferred terms to use for the various standards are listed
270 as headings in standards(7).
271 For a page in Section 2 or 3, this section should note the
273 POSIX.1 version(s) that the call conforms to, and also whether
274 the call is specified in C99. (Don't worry too much about other
275 standards like SUS, SUSv2, and XPG, or the SVr4 and 4.xBSD im‐
276 plementation standards, unless the call was specified in those
277 standards, but isn't in the current version of POSIX.1.)
278 If the call is not governed by any standards but commonly exists
280 on other systems, note them. If the call is Linux-specific,
281 note this.
282 If this section consists of just a list of standards (which it
284 commonly does), terminate the list with a period ('.').
285 NOTES Miscellaneous notes.
287 For Section 2 and 3 man pages you may find it useful to include
289 subsections (SS) named Linux Notes and Glibc Notes.
290 In Section 2, use the heading C library/kernel differences to
292 mark off notes that describe the differences (if any) between
293 the C library wrapper function for a system call and the raw
294 system call interface provided by the kernel.
295 BUGS A list of limitations, known defects or inconveniences, and
297 other questionable activities.
298 EXAMPLES
300 One or more examples demonstrating how this function, file, or
301 command is used.
302 For details on writing example programs, see Example programs
304 below.
305 AUTHORS
307 A list of authors of the documentation or program.
308 Use of an AUTHORS section is strongly discouraged. Generally,
310 it is better not to clutter every page with a list of (over time
311 potentially numerous) authors; if you write or significantly
312 amend a page, add a copyright notice as a comment in the source
313 file. If you are the author of a device driver and want to in‐
314 clude an address for reporting bugs, place this under the BUGS
315 section.
316 REPORTING BUGS
318 The man-pages project doesn't use a REPORTING BUGS section in
319 manual pages. Information on reporting bugs is instead supplied
320 in the script-generated COLOPHON section. However, various
321 projects do use a REPORTING BUGS section. It is recommended to
322 place it near the foot of the page.
323 COPYRIGHT
325 The man-pages project doesn't use a COPYRIGHT section in manual
326 pages. Copyright information is instead maintained in the page
327 source. In pages where this section is present, it is recom‐
328 mended to place it near the foot of the page, just above SEE
329 ALSO.
330 SEE ALSO
332 A comma-separated list of related man pages, possibly followed
333 by other related pages or documents.
334 The list should be ordered by section number and then alphabeti‐
336 cally by name. Do not terminate this list with a period.
337 Where the SEE ALSO list contains many long manual page names, to
339 improve the visual result of the output, it may be useful to em‐
340 ploy the .ad l (don't right justify) and .nh (don't hyphenate)
341 directives. Hyphenation of individual page names can be pre‐
342 vented by preceding words with the string "\%".
343 Given the distributed, autonomous nature of FOSS projects and
345 their documentation, it is sometimes necessary—and in many cases
346 desirable—that the SEE ALSO section includes references to man‐
347 ual pages provided by other projects.
348
350 The following subsections note some details for preferred formatting
351 and wording conventions in various sections of the pages in the man-
352 pages project.
353 SYNOPSIS
355 Wrap the function prototype(s) in a .nf/.fi pair to prevent filling.
356 In general, where more than one function prototype is shown in the SYN‐
358 OPSIS, the prototypes should not be separated by blank lines. However,
359 blank lines (achieved using .PP) may be added in the following cases:
360 * to separate long lists of function prototypes into related groups
362 (see for example list(3));
363 * in other cases that may improve readability.
365 In the SYNOPSIS, a long function prototype may need to be continued
367 over to the next line. The continuation line is indented according to
368 the following rules:
369 1. If there is a single such prototype that needs to be continued, then
371 align the continuation line so that when the page is rendered on a
372 fixed-width font device (e.g., on an xterm) the continuation line
373 starts just below the start of the argument list in the line above.
374 (Exception: the indentation may be adjusted if necessary to prevent
375 a very long continuation line or a further continuation line where
376 the function prototype is very long.) As an example:
377 int tcsetattr(int fd, int optional_actions,
379 const struct termios *termios_p);
380 2. But, where multiple functions in the SYNOPSIS require continuation
382 lines, and the function names have different lengths, then align all
383 continuation lines to start in the same column. This provides a
384 nicer rendering in PDF output (because the SYNOPSIS uses a variable
385 width font where spaces render narrower than most characters). As
386 an example:
387 int getopt(int argc, char * const argv[],
389 const char *optstring);
390 int getopt_long(int argc, char * const argv[],
391 const char *optstring,
392 const struct option *longopts, int *longindex);
393 RETURN VALUE
395 The preferred wording to describe how errno is set is "errno is set to
396 indicate the error" or similar. This wording is consistent with the
397 wording used in both POSIX.1 and FreeBSD.
398 ATTRIBUTES
400 Note the following:
401 * Wrap the table in this section in a .ad l/.ad pair to disable text
403 filling and a .nh/.hy pair to disable hyphenation.
404 * Ensure that the table occupies the full page width through the use
406 of an lbx description for one of the columns (usually the first col‐
407 umn, though in some cases the last column if it contains a lot of
408 text).
409 * Make free use of T{/T} macro pairs to allow table cells to be broken
411 over multiple lines (also bearing in mind that pages may sometimes
412 be rendered to a width of less than 80 columns).
413 For examples of all of the above, see the source code of various pages.
415
417 The following subsections describe the preferred style for the man-
418 pages project. For details not covered below, the Chicago Manual of
419 Style is usually a good source; try also grepping for preexisting usage
420 in the project source tree.
421 Use of gender-neutral language
423 As far as possible, use gender-neutral language in the text of man
424 pages. Use of "they" ("them", "themself", "their") as a gender-neutral
425 singular pronoun is acceptable.
426 Formatting conventions for manual pages describing commands
428 For manual pages that describe a command (typically in Sections 1 and
429 8), the arguments are always specified using italics, even in the SYN‐
430 OPSIS section.
431 The name of the command, and its options, should always be formatted in
433 bold.
434 Formatting conventions for manual pages describing functions
436 For manual pages that describe functions (typically in Sections 2 and
437 3), the arguments are always specified using italics, even in the SYN‐
438 OPSIS section, where the rest of the function is specified in bold:
439 int myfunction(int argc, char **argv);
441 Variable names should, like argument names, be specified in italics.
443 Any reference to the subject of the current manual page should be writ‐
445 ten with the name in bold followed by a pair of parentheses in Roman
446 (normal) font. For example, in the fcntl(2) man page, references to
447 the subject of the page would be written as: fcntl(). The preferred
448 way to write this in the source file is:
449 .BR fcntl ()
451 (Using this format, rather than the use of "\fB...\fP()" makes it eas‐
453 ier to write tools that parse man page source files.)
454 Use semantic newlines
456 In the source of a manual page, new sentences should be started on new
457 lines, and long sentences should split into lines at clause breaks
458 (commas, semicolons, colons, and so on). This convention, sometimes
459 known as "semantic newlines", makes it easier to see the effect of
460 patches, which often operate at the level of individual sentences or
461 sentence clauses.
462 Formatting conventions (general)
464 Paragraphs should be separated by suitable markers (usually either .PP
465 or .IP). Do not separate paragraphs using blank lines, as this results
466 in poor rendering in some output formats (such as PostScript and PDF).
467 Filenames (whether pathnames, or references to header files) are always
469 in italics (e.g., <stdio.h>), except in the SYNOPSIS section, where in‐
470 cluded files are in bold (e.g., #include <stdio.h>). When referring to
471 a standard header file include, specify the header file surrounded by
472 angle brackets, in the usual C way (e.g., <stdio.h>).
473 Special macros, which are usually in uppercase, are in bold (e.g., MAX‐
475 INT). Exception: don't boldface NULL.
476 When enumerating a list of error codes, the codes are in bold (this
478 list usually uses the .TP macro).
479 Complete commands should, if long, be written as an indented line on
481 their own, with a blank line before and after the command, for example
482 man 7 man-pages
484 If the command is short, then it can be included inline in the text, in
486 italic format, for example, man 7 man-pages. In this case, it may be
487 worth using nonbreaking spaces ("\ ") at suitable places in the com‐
488 mand. Command options should be written in italics (e.g., -l).
489 Expressions, if not written on a separate indented line, should be
491 specified in italics. Again, the use of nonbreaking spaces may be ap‐
492 propriate if the expression is inlined with normal text.
493 When showing example shell sessions, user input should be formatted in
495 bold, for example
496 $ date
498 Thu Jul 7 13:01:27 CEST 2016
499 Any reference to another man page should be written with the name in
501 bold, always followed by the section number, formatted in Roman (nor‐
502 mal) font, without any separating spaces (e.g., intro(2)). The pre‐
503 ferred way to write this in the source file is:
504 .BR intro (2)
506 (Including the section number in cross references lets tools like
508 man2html(1) create properly hyperlinked pages.)
509 Control characters should be written in bold face, with no quotes; for
511 example, ^X.
512 Spelling
514 Starting with release 2.59, man-pages follows American spelling conven‐
515 tions (previously, there was a random mix of British and American
516 spellings); please write all new pages and patches according to these
517 conventions.
518 Aside from the well-known spelling differences, there are a few other
520 subtleties to watch for:
521 * American English tends to use the forms "backward", "upward", "to‐
523 ward", and so on rather than the British forms "backwards", "up‐
524 wards", "towards", and so on.
525 * Opinions are divided on "acknowledgement" vs "acknowledgment". The
527 latter is predominant, but not universal usage in American English.
528 POSIX and the BSD license use the former spelling. In the Linux
529 man-pages project, we use "acknowledgement".
530 BSD version numbers
532 The classical scheme for writing BSD version numbers is x.yBSD, where
533 x.y is the version number (e.g., 4.2BSD). Avoid forms such as BSD 4.3.
534 Capitalization
536 In subsection ("SS") headings, capitalize the first word in the head‐
537 ing, but otherwise use lowercase, except where English usage (e.g.,
538 proper nouns) or programming language requirements (e.g., identifier
539 names) dictate otherwise. For example:
540 .SS Unicode under Linux
542 Indentation of structure definitions, shell session logs, and so on
544 When structure definitions, shell session logs, and so on are included
545 in running text, indent them by 4 spaces (i.e., a block enclosed by
546 .in +4n and .in), format them using the .EX and EE macros, and surround
547 them with suitable paragraph markers (either .PP or .IP). For example:
548 .PP
550 .in +4n
551 .EX
552 int
553 main(int argc, char *argv[])
554 {
555 return 0;
556 }
557 .EE
558 .in
559 .PP
560 Preferred terms
562 The following table lists some preferred terms to use in man pages,
563 mainly to ensure consistency across pages.
564 Term Avoid using Notes
566 ────────────────────────────────────────────────────────────────
567 bit mask bitmask
568 built-in builtin
569 Epoch epoch For the UNIX
570 Epoch (00:00:00,
571 1 Jan 1970 UTC)
572 filename file name
573 filesystem file system
574 hostname host name
575 inode i-node
576 lowercase lower case, lower-case
577 nonzero non-zero
578 pathname path name
579 pseudoterminal pseudo-terminal
580 privileged port reserved port, system
581 port
582 real-time realtime, real time
583 run time runtime
584 saved set-group-ID saved group ID, saved
585 set-GID
586 saved set-user-ID saved user ID, saved
587 set-UID
588 set-group-ID set-GID, setgid
589 set-user-ID set-UID, setuid
590 superuser super user, super-user
591 superblock super block, super-
592 block
593 timestamp time stamp
594 timezone time zone
596 uppercase upper case, upper-case
597 usable useable
598 user space userspace
599 username user name
600 x86-64 x86_64 Except if refer‐
601 ring to result
602 of "uname -m" or
603 similar
604 zeros zeroes
605 See also the discussion Hyphenation of attributive compounds below.
607 Terms to avoid
609 The following table lists some terms to avoid using in man pages, along
610 with some suggested alternatives, mainly to ensure consistency across
611 pages.
612 Avoid Use instead Notes
614 ──────────────────────────────────────────────────────────
615 32bit 32-bit same for 8-bit,
617 16-bit, etc.
618 current process calling process A common mistake
619 made by kernel pro‐
620 grammers when writ‐
621 ing man pages
622 manpage man page, manual
623 page
624 minus infinity negative infinity
625 non-root unprivileged user
626 non-superuser unprivileged user
627 nonprivileged unprivileged
628 OS operating system
629 plus infinity positive infinity
630 pty pseudoterminal
631 tty terminal
632 Unices UNIX systems
633 Unixes UNIX systems
634 Trademarks
636 Use the correct spelling and case for trademarks. The following is a
637 list of the correct spellings of various relevant trademarks that are
638 sometimes misspelled:
639 DG/UX
641 HP-UX
642 UNIX
643 UnixWare
644 NULL, NUL, null pointer, and null character
646 A null pointer is a pointer that points to nothing, and is normally in‐
647 dicated by the constant NULL. On the other hand, NUL is the null byte,
648 a byte with the value 0, represented in C via the character constant
649 '\0'.
650 The preferred term for the pointer is "null pointer" or simply "NULL";
652 avoid writing "NULL pointer".
653 The preferred term for the byte is "null byte". Avoid writing "NUL",
655 since it is too easily confused with "NULL". Avoid also the terms
656 "zero byte" and "null character". The byte that terminates a C string
657 should be described as "the terminating null byte"; strings may be de‐
658 scribed as "null-terminated", but avoid the use of "NUL-terminated".
659 Hyperlinks
661 For hyperlinks, use the .UR/.UE macro pair (see groff_man(7)). This
662 produces proper hyperlinks that can be used in a web browser, when ren‐
663 dering a page with, say:
664 BROWSER=firefox man -H pagename
666 Use of e.g., i.e., etc., a.k.a., and similar
668 In general, the use of abbreviations such as "e.g.", "i.e.", "etc.",
669 "cf.", and "a.k.a." should be avoided, in favor of suitable full word‐
670 ings ("for example", "that is", "and so on", "compare to", "also known
671 as").
672 The only place where such abbreviations may be acceptable is in short
674 parenthetical asides (e.g., like this one).
675 Always include periods in such abbreviations, as shown here. In addi‐
677 tion, "e.g." and "i.e." should always be followed by a comma.
678 Em-dashes
680 The way to write an em-dash—the glyph that appears at either end of
681 this subphrase—in *roff is with the macro "\(em". (On an ASCII termi‐
682 nal, an em-dash typically renders as two hyphens, but in other typo‐
683 graphical contexts it renders as a long dash.) Em-dashes should be
684 written without surrounding spaces.
685 Hyphenation of attributive compounds
687 Compound terms should be hyphenated when used attributively (i.e., to
688 qualify a following noun). Some examples:
689 32-bit value
691 command-line argument
692 floating-point number
693 run-time check
694 user-space function
695 wide-character string
696 Hyphenation with multi, non, pre, re, sub, and so on
698 The general tendency in modern English is not to hyphenate after pre‐
699 fixes such as "multi", "non", "pre", "re", "sub", and so on. Manual
700 pages should generally follow this rule when these prefixes are used in
701 natural English constructions with simple suffixes. The following list
702 gives some examples of the preferred forms:
703 interprocess
705 multithreaded
706 multiprocess
707 nonblocking
708 nondefault
709 nonempty
710 noninteractive
711 nonnegative
712 nonportable
713 nonzero
714 preallocated
715 precreate
716 prerecorded
717 reestablished
718 reinitialize
719 rearm
720 reread
721 subcomponent
722 subdirectory
723 subsystem
724 Hyphens should be retained when the prefixes are used in nonstandard
726 English words, with trademarks, proper nouns, acronyms, or compound
727 terms. Some examples:
728 non-ASCII
730 non-English
731 non-NULL
732 non-real-time
733 Finally, note that "re-create" and "recreate" are two different verbs,
735 and the former is probably what you want.
736 Generating optimal glyphs
738 Where a real minus character is required (e.g., for numbers such as -1,
739 for man page cross references such as utf-8(7), or when writing options
740 that have a leading dash, such as in ls -l), use the following form in
741 the man page source:
742 \-
744 This guideline applies also to code examples.
746 The use of real minus signs serves the following purposes:
748 * To provide better renderings on various targets other than ASCII
750 terminals, notably in PDF and on Unicode/UTF-8-capable terminals.
751 * To generate glyphs that when copied from rendered pages will produce
753 real minus signs when pasted into a terminal.
754 To produce unslanted single quotes that render well in ASCII, UTF-8,
756 and PDF, use "\(aq" ("apostrophe quote"); for example
757 \(aqC\(aq
759 where C is the quoted character. This guideline applies also to char‐
761 acter constants used in code examples.
762 Where a proper caret (^) that renders well in both a terminal and PDF
764 is required, use "\(ha". This is especially necessary in code samples,
765 to get a nicely rendered caret when rendering to PDF.
766 Using a naked "~" character results in a poor rendering in PDF. In‐
768 stead use "\(ti". This is especially necessary in code samples, to get
769 a nicely rendered tilde when rendering to PDF.
770 Example programs and shell sessions
772 Manual pages may include example programs demonstrating how to use a
773 system call or library function. However, note the following:
774 * Example programs should be written in C.
776 * An example program is necessary and useful only if it demonstrates
778 something beyond what can easily be provided in a textual descrip‐
779 tion of the interface. An example program that does nothing other
780 than call an interface usually serves little purpose.
781 * Example programs should ideally be short (e.g., a good example can
783 often be provided in less than 100 lines of code), though in some
784 cases longer programs may be necessary to properly illustrate the
785 use of an API.
786 * Expressive code is appreciated.
788 * Comments should included where helpful. Complete sentences in free-
790 standing comments should be terminated by a period. Periods should
791 generally be omitted in "tag" comments (i.e., comments that are
792 placed on the same line of code); such comments are in any case typ‐
793 ically brief phrases rather than complete sentences.
794 * Example programs should do error checking after system calls and li‐
796 brary function calls.
797 * Example programs should be complete, and compile without warnings
799 when compiled with cc -Wall.
800 * Where possible and appropriate, example programs should allow exper‐
802 imentation, by varying their behavior based on inputs (ideally from
803 command-line arguments, or alternatively, via input read by the pro‐
804 gram).
805 * Example programs should be laid out according to Kernighan and
807 Ritchie style, with 4-space indents. (Avoid the use of TAB charac‐
808 ters in source code!) The following command can be used to format
809 your source code to something close to the preferred style:
810 indent -npro -kr -i4 -ts4 -sob -l72 -ss -nut -psl prog.c
812 * For consistency, all example programs should terminate using either
814 of:
815 exit(EXIT_SUCCESS);
817 exit(EXIT_FAILURE);
818 Avoid using the following forms to terminate a program:
820 exit(0);
822 exit(1);
823 return n;
824 * If there is extensive explanatory text before the program source
826 code, mark off the source code with a subsection heading Program
827 source, as in:
828 .SS Program source
830 Always do this if the explanatory text includes a shell session log.
832 If you include a shell session log demonstrating the use of a program
834 or other system feature:
835 * Place the session log above the source code listing
837 * Indent the session log by four spaces.
839 * Boldface the user input text, to distinguish it from output produced
841 by the system.
842 For some examples of what example programs should look like, see
844 wait(2) and pipe(2).
845
847 For canonical examples of how man pages in the man-pages package should
848 look, see pipe(2) and fcntl(2).
849
851 man(1), man2html(1), attributes(7), groff(7), groff_man(7), man(7),
852 mdoc(7)
853
855 This page is part of release 5.12 of the Linux man-pages project. A
856 description of the project, information about reporting bugs, and the
857 latest version of this page, can be found at
858 https://www.kernel.org/doc/man-pages/.
859Linux 2021-03-22 MAN-PAGES(7)