Debian Codegraph @

upstream/fedora-44/man7/man-pages.7

raw
1 '\" t
2 .\" (C) Copyright 1992-1999 Rickard E. Faith and David A. Wheeler
3 .\" ([email protected] and [email protected])
4 .\" and (C) Copyright 2007 Michael Kerrisk <[email protected]>
5 .\"
6 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
7 .\"
8 .\" 2007-05-30 created by mtk, using text from old man.7 plus
9 .\" rewrites and additional text.
10 .\"
11 .TH man-pages 7 2025-01-15 "Linux man-pages 6.13"
12 .SH NAME
13 man-pages \- conventions for writing Linux man pages
14 .SH SYNOPSIS
15 .B man
16 .RI [ section ]
17 .I title
18 .SH DESCRIPTION
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:
31 .TP
32 .B 1 User commands (Programs)
33 Commands that can be executed by the user from within
34 a shell.
35 .TP
36 .B 2 System calls
37 Functions which wrap operations performed by the kernel.
38 .TP
39 .B 3 Library calls
40 All library functions excluding the system call wrappers
41 (Most of the
42 .I libc
43 functions).
44 .TP
45 .B 4 Special files (devices)
46 Files found in
47 .I /dev
48 which allow to access to devices through the kernel.
49 .TP
50 .B 5 File formats and configuration files
51 Describes various human-readable file formats and configuration files.
52 .TP
53 .B 6 Games
54 Games and funny little programs available on the system.
55 .TP
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
59 other things.
60 .TP
61 .B 8 System management commands
62 Commands like
63 .BR mount (8),
64 many of which only root can execute.
65 .\" .TP
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.
73 .SS Macro package
74 New manual pages should be marked up using the
75 .B groff an.tmac
76 package described in
77 .BR man (7).
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
82 wherever possible.
83 This helps avoid line-wrapping in some mail clients when patches are
84 submitted inline.
85 .SS Title line
86 The first command in a man page should be a
87 .B TH
88 command:
89 .P
90 .RS
91 .B \&.TH
92 .I "title section date source manual-section"
93 .RE
94 .P
95 The arguments of the command are as follows:
96 .TP
97 .I title
98 The title of the man page.
99 .TP
100 .I section
101 The section number in which the man page should be placed (e.g.,
102 .IR 7 ).
103 .TP
104 .I date
105 The date of the last nontrivial change that was made to the man page.
106 (Within the
107 .I man-pages
108 project, the necessary updates to these timestamps are handled
109 automatically by scripts, so there is no need to manually update
110 them as part of a patch.)
111 Dates should be written in the form YYYY-MM-DD.
112 .TP
113 .I source
114 The name and version of the project that provides the manual page
115 (not necessarily the package that provides the functionality).
116 .TP
117 .I manual-section
118 Normally, this should be empty,
119 since the default value will be good.
120 .\"
121 .SS Sections within a manual page
122 The list below shows conventional or suggested sections.
123 Most manual pages should include at least the
124 .B highlighted
125 sections.
126 Arrange a new manual page so that sections
127 are placed in the order shown in the list.
128 .P
129 .RS
130 .TS
131 l l.
132 \fBNAME\fP
133 LIBRARY [Normally only in Sections 2, 3]
134 \fBSYNOPSIS\fP
135 CONFIGURATION [Normally only in Section 4]
136 \fBDESCRIPTION\fP
137 OPTIONS [Normally only in Sections 1, 8]
138 EXIT STATUS [Normally only in Sections 1, 8]
139 RETURN VALUE [Normally only in Sections 2, 3]
140 .\" May 07: Few current man pages have an ERROR HANDLING section,,,
141 .\" ERROR HANDLING,
142 ERRORS [Typically only in Sections 2, 3]
143 .\" May 07: Almost no current man pages have a USAGE section,,,
144 .\" USAGE,
145 .\" DIAGNOSTICS,
146 .\" May 07: Almost no current man pages have a SECURITY section,,,
147 .\" SECURITY,
148 ENVIRONMENT
149 FILES
150 ATTRIBUTES [Normally only in Sections 2, 3]
151 VERSIONS [Normally only in Sections 2, 3]
152 STANDARDS
153 HISTORY
154 NOTES
155 CAVEATS
156 BUGS
157 EXAMPLES
158 .\" AUTHORS sections are discouraged
159 AUTHORS [Discouraged]
160 REPORTING BUGS [Not used in man-pages]
161 COPYRIGHT [Not used in man-pages]
162 \fBSEE ALSO\fP
163 .TE
164 .RE
165 .P
166 .IR "Where a traditional heading would apply" ", " "please use it" ;
167 this kind of consistency can make the information easier to understand.
168 If you must, you can create your own
169 headings if they make things easier to understand (this can
170 be especially useful for pages in Sections 4 and 5).
171 However, before doing this, consider whether you could use the
172 traditional headings, with some subsections (\fI.SS\fP) within
173 those sections.
174 .P
175 The following list elaborates on the contents of each of
176 the above sections.
177 .TP
178 .B NAME
179 The name of this manual page.
180 .IP
181 See
182 .BR man (7)
183 for important details of the line(s) that should follow the
184 \fB.SH NAME\fP command.
185 All words in this line (including the word immediately
186 following the "\[rs]\-") should be in lowercase,
187 except where English or technical terminological convention
188 dictates otherwise.
189 .TP
190 .B LIBRARY
191 The library providing a symbol.
192 .IP
193 It shows the common name of the library,
194 and in parentheses,
195 the name of the library file
196 and, if needed, the linker flag needed to link a program against it:
197 .RI ( libfoo "[, " \-lfoo ]).
198 .TP
199 .B SYNOPSIS
200 A brief summary of the command or function's interface.
201 .IP
202 For commands, this shows the syntax of the command and its arguments
203 (including options);
204 boldface is used for as-is text and italics are used to
205 indicate replaceable arguments.
206 Brackets ([]) surround optional arguments, vertical bars (|)
207 separate choices, and ellipses (\&...) can be repeated.
208 For functions, it shows any required data declarations or
209 .B #include
210 directives, followed by the function declaration.
211 .IP
212 Where a feature test macro must be defined in order to obtain
213 the declaration of a function (or a variable) from a header file,
214 then the SYNOPSIS should indicate this, as described in
215 .BR feature_test_macros (7).
216 .\" FIXME . Say something here about compiler options
217 .TP
218 .B CONFIGURATION
219 Configuration details for a device.
220 .IP
221 This section normally appears only in Section 4 pages.
222 .TP
223 .B DESCRIPTION
224 An explanation of what the program, function, or format does.
225 .IP
226 Discuss how it interacts with files and standard input, and what it
227 produces on standard output or standard error.
228 Omit internals and implementation details unless they're critical for
229 understanding the interface.
230 Describe the usual case;
231 for information on command-line options of a program use the
232 .B OPTIONS
233 section.
234 .\" If there is some kind of input grammar or complex set of subcommands,
235 .\" consider describing them in a separate
236 .\" .B USAGE
237 .\" section (and just place an overview in the
238 .\" .B DESCRIPTION
239 .\" section).
240 .IP
241 When describing new behavior or new flags for
242 a system call or library function,
243 be careful to note the kernel or C library version
244 that introduced the change.
245 The preferred method of noting this information for flags is as part of a
246 .B .TP
247 list, in the following form (here, for a new system call flag):
248 .RS 16
249 .TP
250 .BR XYZ_FLAG " (since Linux 3.7)"
251 Description of flag...
252 .RE
253 .IP
254 Including version information is especially useful to users
255 who are constrained to using older kernel or C library versions
256 (which is typical in embedded systems, for example).
257 .TP
258 .B OPTIONS
259 A description of the command-line options accepted by a
260 program and how they change its behavior.
261 .IP
262 This section should appear only for Section 1 and 8 manual pages.
263 .\" .TP
264 .\" .B USAGE
265 .\" describes the grammar of any sublanguage this implements.
266 .TP
267 .B EXIT STATUS
268 A list of the possible exit status values of a program and
269 the conditions that cause these values to be returned.
270 .IP
271 This section should appear only for Section 1 and 8 manual pages.
272 .TP
273 .B RETURN VALUE
274 For Section 2 and 3 pages, this section gives a
275 list of the values the library routine will return to the caller
276 and the conditions that cause these values to be returned.
277 .TP
278 .B ERRORS
279 For Section 2 and 3 manual pages, this is a list of the
280 values that may be placed in
281 .I errno
282 in the event of an error, along with information about the cause
283 of the errors.
284 .IP
285 Where several different conditions produce the same error,
286 the preferred approach is to create separate list entries
287 (with duplicate error names) for each of the conditions.
288 This makes the separate conditions clear, may make the list easier to read,
289 and allows metainformation
290 (e.g., kernel version number where the condition first became applicable)
291 to be more easily marked for each condition.
292 .IP
293 .IR "The error list should be in alphabetical order" .
294 .TP
295 .B ENVIRONMENT
296 A list of all environment variables that affect the program or function
297 and how they affect it.
298 .TP
299 .B FILES
300 A list of the files the program or function uses, such as
301 configuration files, startup files,
302 and files the program directly operates on.
303 .IP
304 Give the full pathname of these files, and use the installation
305 process to modify the directory part to match user preferences.
306 For many programs, the default installation location is in
307 .IR /usr/local ,
308 so your base manual page should use
309 .I /usr/local
310 as the base.
311 .\" May 07: Almost no current man pages have a DIAGNOSTICS section;
312 .\" "RETURN VALUE" or "EXIT STATUS" is preferred.
313 .\" .TP
314 .\" .B DIAGNOSTICS
315 .\" gives an overview of the most common error messages and how to
316 .\" cope with them.
317 .\" You don't need to explain system error messages
318 .\" or fatal signals that can appear during execution of any program
319 .\" unless they're special in some way to the program.
320 .\"
321 .\" May 07: Almost no current man pages have a SECURITY section.
322 .\".TP
323 .\".B SECURITY
324 .\"discusses security issues and implications.
325 .\"Warn about configurations or environments that should be avoided,
326 .\"commands that may have security implications, and so on, especially
327 .\"if they aren't obvious.
328 .\"Discussing security in a separate section isn't necessary;
329 .\"if it's easier to understand, place security information in the
330 .\"other sections (such as the
331 .\" .B DESCRIPTION
332 .\" or
333 .\" .B USAGE
334 .\" section).
335 .\" However, please include security information somewhere!
336 .TP
337 .B ATTRIBUTES
338 A summary of various attributes of the function(s) documented on this page.
339 See
340 .BR attributes (7)
341 for further details.
342 .TP
343 .B VERSIONS
344 A summary of systems where the API performs differently,
345 or where there's a similar API.
346 .TP
347 .B STANDARDS
348 A description of any standards or conventions that relate to the function
349 or command described by the manual page.
350 .IP
351 The preferred terms to use for the various standards are listed as
352 headings in
353 .BR standards (7).
354 .IP
355 This section should note the current standards to which the API conforms to.
356 .IP
357 If the API is not governed by any standards but commonly
358 exists on other systems, note them.
359 If the call is Linux-specific or GNU-specific, note this.
360 If it's available in the BSDs, note that.
361 .IP
362 If this section consists of just a list of standards
363 (which it commonly does),
364 terminate the list with a period (\[aq].\[aq]).
365 .TP
366 .B HISTORY
367 A brief summary of the Linux kernel or glibc versions where a
368 system call or library function appeared,
369 or changed significantly in its operation.
370 .IP
371 As a general rule, every new interface should
372 include a HISTORY section in its manual page.
373 Unfortunately,
374 many existing manual pages don't include this information
375 (since there was no policy to do so when they were written).
376 Patches to remedy this are welcome,
377 but, from the perspective of programmers writing new code,
378 this information probably matters only in the case of kernel
379 interfaces that have been added in Linux 2.4 or later
380 (i.e., changes since Linux 2.2),
381 and library functions that have been added to glibc since glibc 2.1
382 (i.e., changes since glibc 2.0).
383 .IP
384 The
385 .BR syscalls (2)
386 manual page also provides information about kernel versions
387 in which various system calls first appeared.
388 .P
389 Old versions of standards should be mentioned here,
390 rather than in STANDARDS,
391 for example,
392 SUS, SUSv2, and XPG, or the SVr4 and 4.xBSD implementation standards.
393 .TP
394 .B NOTES
395 Miscellaneous notes.
396 .IP
397 For Section 2 and 3 man pages you may find it useful to include
398 subsections (\fBSS\fP) named \fILinux Notes\fP and \fIglibc Notes\fP.
399 .IP
400 In Section 2, use the heading
401 .I "C library/kernel differences"
402 to mark off notes that describe the differences (if any) between
403 the C library wrapper function for a system call and
404 the raw system call interface provided by the kernel.
405 .TP
406 .B CAVEATS
407 Warnings about typical user misuse of an API,
408 that don't constitute an API bug or design defect.
409 .TP
410 .B BUGS
411 A list of limitations, known defects or inconveniences,
412 and other questionable activities.
413 .TP
414 .B EXAMPLES
415 One or more examples demonstrating how this function, file, or
416 command is used.
417 .IP
418 For details on writing example programs,
419 see \fIExample programs\fP below.
420 .TP
421 .B AUTHORS
422 A list of authors of the documentation or program.
423 .IP
424 \fBUse of an AUTHORS section is strongly discouraged\fP.
425 Generally, it is better not to clutter every page with a list
426 of (over time potentially numerous) authors;
427 if you write or significantly amend a page,
428 add a copyright notice as a comment in the source file.
429 If you are the author of a device driver and want to include
430 an address for reporting bugs, place this under the BUGS section.
431 .TP
432 .B REPORTING BUGS
433 The
434 .I man-pages
435 project doesn't use a REPORTING BUGS section in manual pages.
436 Information on reporting bugs is instead supplied in the
437 script-generated COLOPHON section.
438 However, various projects do use a REPORTING BUGS section.
439 It is recommended to place it near the foot of the page.
440 .TP
441 .B COPYRIGHT
442 The
443 .I man-pages
444 project doesn't use a COPYRIGHT section in manual pages.
445 Copyright information is instead maintained in the page source.
446 In pages where this section is present,
447 it is recommended to place it near the foot of the page, just above SEE ALSO.
448 .TP
449 .B SEE ALSO
450 A comma-separated list of related man pages, possibly followed by
451 other related pages or documents.
452 .IP
453 The list should be ordered by section number and
454 then alphabetically by name.
455 Do not terminate this list with a period.
456 .IP
457 Where the SEE ALSO list contains many long manual page names,
458 to improve the visual result of the output, it may be useful to employ the
459 .I .ad l
460 (don't right justify)
461 and
462 .I .nh
463 (don't hyphenate)
464 directives.
465 Hyphenation of individual page names can be prevented
466 by preceding words with the string "\[rs]%".
467 .IP
468 Given the distributed, autonomous nature of FOSS projects
469 and their documentation, it is sometimes necessary\[em]and in many cases
470 desirable\[em]that the SEE ALSO section includes references to
471 manual pages provided by other projects.
472 .SH FORMATTING AND WORDING CONVENTIONS
473 The following subsections note some details for preferred formatting and
474 wording conventions in various sections of the pages in the
475 .I man-pages
476 project.
477 .SS SYNOPSIS
478 Wrap the function prototype(s) in a
479 .IR .nf / .fi
480 pair to prevent filling.
481 .P
482 In general, where more than one function prototype is shown in the SYNOPSIS,
483 the prototypes should
484 .I not
485 be separated by blank lines.
486 However, blank lines (achieved using
487 .IR .P )
488 may be added in the following cases:
489 .IP \[bu] 3
490 to separate long lists of function prototypes into related groups
491 (see for example
492 .BR list (3));
493 .IP \[bu]
494 in other cases that may improve readability.
495 .P
496 In the SYNOPSIS, a long function prototype may need to be
497 continued over to the next line.
498 The continuation line is indented according to the following rules:
499 .IP (1) 5
500 If there is a single such prototype that needs to be continued,
501 then align the continuation line so that when the page is
502 rendered on a fixed-width font device (e.g., on an xterm) the
503 continuation line starts just below the start of the argument
504 list in the line above.
505 (Exception: the indentation may be
506 adjusted if necessary to prevent a very long continuation line
507 or a further continuation line where the function prototype is
508 very long.)
509 As an example:
510 .IP
511 .in +4n
512 .nf
513 .BI "int tcsetattr(int " fd ", int " optional_actions ,
514 .BI " const struct termios *" termios_p );
515 .fi
516 .in
517 .IP (2)
518 But, where multiple functions in the SYNOPSIS require
519 continuation lines, and the function names have different
520 lengths, then align all continuation lines to start in the
521 same column.
522 This provides a nicer rendering in PDF output
523 (because the SYNOPSIS uses a variable width font where
524 spaces render narrower than most characters).
525 As an example:
526 .IP
527 .in +4n
528 .nf
529 .BI "int getopt(int " argc ", char * const " argv[] ,
530 .BI " const char *" optstring );
531 .BI "int getopt_long(int " argc ", char * const " argv[] ,
532 .BI " const char *" optstring ,
533 .BI " const struct option *" longopts ", int *" longindex );
534 .fi
535 .in
536 .SS RETURN VALUE
537 The preferred wording to describe how
538 .I errno
539 is set is
540 .RI \[dq] errno
541 is set to indicate the error"
542 or similar.
543 .\" Before man-pages 5.11, many different wordings were used, which
544 .\" was confusing, and potentially made scripted edits more difficult.
545 This wording is consistent with the wording used in both POSIX.1 and FreeBSD.
546 .SS ATTRIBUTES
547 .\" See man-pages commit c466875ecd64ed3d3cd3e578406851b7dfb397bf
548 Note the following:
549 .IP \[bu] 3
550 Wrap the table in this section in a
551 .IR ".ad\ l" / .ad
552 pair to disable text filling and a
553 .IR .nh / .hy
554 pair to disable hyphenation.
555 .IP \[bu]
556 Ensure that the table occupies the full page width through the use of an
557 .I lbx
558 description for one of the columns
559 (usually the first column,
560 though in some cases the last column if it contains a lot of text).
561 .IP \[bu]
562 Make free use of
563 .IR T{ / T}
564 macro pairs to allow table cells to be broken over multiple lines
565 (also bearing in mind that pages may sometimes be rendered to a
566 width of less than 80 columns).
567 .P
568 For examples of all of the above, see the source code of various pages.
569 .SH STYLE GUIDE
570 The following subsections describe the preferred style for the
571 .I man-pages
572 project.
573 For details not covered below, the Chicago Manual of Style
574 is usually a good source;
575 try also grepping for preexisting usage in the project source tree.
576 .SS Use of gender-neutral language
577 As far as possible, use gender-neutral language in the text of man
578 pages.
579 Use of "they" ("them", "themself", "their") as a gender-neutral singular
580 pronoun is acceptable.
581 .\"
582 .SS Formatting conventions for manual pages describing commands
583 For manual pages that describe a command (typically in Sections 1 and 8),
584 the arguments are always specified using italics,
585 .IR "even in the SYNOPSIS section" .
586 .P
587 The name of the command, and its options, should
588 always be formatted in bold.
589 .\"
590 .SS Formatting conventions for manual pages describing functions
591 For manual pages that describe functions (typically in Sections 2 and 3),
592 the arguments are always specified using italics,
593 .IR "even in the SYNOPSIS section" ,
594 where the rest of the function is specified in bold:
595 .P
596 .BI " int myfunction(int " argc ", char **" argv );
597 .P
598 Variable names should, like argument names, be specified in italics.
599 .P
600 Any reference to the subject of the current manual page
601 should be written with the name in bold followed by
602 a pair of parentheses in Roman (normal) font.
603 For example, in the
604 .BR fcntl (2)
605 man page, references to the subject of the page would be written as:
606 .BR fcntl ().
607 The preferred way to write this in the source file is:
608 .P
609 .EX
610 .BR fcntl ()
611 .EE
612 .P
613 (Using this format, rather than the use of "\[rs]fB...\[rs]fP()"
614 makes it easier to write tools that parse man page source files.)
615 .\"
616 .SS Use semantic newlines
617 In the source of a manual page,
618 new sentences should be started on new lines,
619 long sentences should be split into lines at clause breaks
620 (commas, semicolons, colons, and so on),
621 and long clauses should be split at phrase boundaries.
622 This convention, sometimes known as "semantic newlines",
623 makes it easier to see the effect of patches,
624 which often operate at the level of
625 individual sentences, clauses, or phrases.
626 .\"
627 .SS Lists
628 There are different kinds of lists:
629 .TP
630 Tagged paragraphs
631 These are used for a list of tags and their descriptions.
632 When the tags are constants (either macros or numbers)
633 they are in bold.
634 Use the
635 .B .TP
636 macro.
637 .IP
638 An example is this "Tagged paragraphs" subsection is itself.
639 .TP
640 Ordered lists
641 Elements are preceded by a number in parentheses (1), (2).
642 These represent a set of steps that have an order.
643 .IP
644 When there are substeps,
645 they will be numbered like (4.2).
646 .TP
647 Positional lists
648 Elements are preceded by a number (index) in square brackets [4], [5].
649 These represent fields in a set.
650 The first index will be:
651 .RS
652 .TP
653 .B 0
654 When it represents fields of a C data structure,
655 to be consistent with arrays.
656 .PD 0
657 .TP
658 .B 1
659 When it represents fields of a file,
660 to be consistent with tools like
661 .BR cut (1).
662 .PD
663 .RE
664 .TP
665 Alternatives list
666 Elements are preceded by a letter in parentheses (a), (b).
667 These represent a set of (normally) exclusive alternatives.
668 .TP
669 Bullet lists
670 Elements are preceded by bullet symbols
671 .RB ( \[rs][bu] ).
672 Anything that doesn't fit elsewhere is
673 usually covered by this type of list.
674 .TP
675 Numbered notes
676 Not really a list,
677 but the syntax is identical to "positional lists".
678 .P
679 There should always be exactly
680 2 spaces between the list symbol and the elements.
681 This doesn't apply to "tagged paragraphs",
682 which use the default indentation rules.
683 .\"
684 .SS Formatting conventions (general)
685 Paragraphs should be separated by suitable markers (usually either
686 .I .P
687 or
688 .IR .IP ).
689 Do
690 .I not
691 separate paragraphs using blank lines, as this results in poor rendering
692 in some output formats (such as PostScript and PDF).
693 .P
694 Filenames (whether pathnames, or references to header files)
695 are always in italics (e.g.,
696 .IR <stdio.h> ),
697 except in the SYNOPSIS section, where included files are in bold (e.g.,
698 .BR "#include <stdio.h>" ).
699 When referring to a standard header file include,
700 specify the header file surrounded by angle brackets,
701 in the usual C way (e.g.,
702 .IR <stdio.h> ).
703 .P
704 Special macros, which are usually in uppercase, are in bold (e.g.,
705 .BR MAXINT ).
706 Exception: don't boldface NULL.
707 .P
708 When enumerating a list of error codes, the codes are in bold (this list
709 usually uses the
710 .B \&.TP
711 macro).
712 .P
713 Complete commands should, if long,
714 be written as an indented line on their own,
715 with a blank line before and after the command, for example
716 .P
717 .in +4n
718 .EX
719 man 7 man\-pages
720 .EE
721 .in
722 .P
723 If the command is short, then it can be included inline in the text,
724 in italic format, for example,
725 .IR "man 7 man-pages" .
726 In this case, it may be worth using nonbreaking spaces
727 .RB ( \[rs]\[ti] )
728 at suitable places in the command.
729 Command options should be written in italics (e.g.,
730 .IR \-l ).
731 .P
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.
736 .P
737 When showing example shell sessions,
738 user input should be formatted in bold,
739 for example
740 .P
741 .in +4n
742 .EX
743 $ \fBdate\fP
744 Thu Jul 7 13:01:27 CEST 2016
745 .EE
746 .in
747 .P
748 Any reference to another man page
749 should be written with the name in bold,
750 .I always
751 followed by the section number,
752 formatted in Roman (normal) font, without any
753 separating spaces (e.g.,
754 .BR intro (2)).
755 The preferred way to write this in the source file is:
756 .P
757 .EX
758 .BR intro (2)
759 .EE
760 .P
761 (Including the section number in cross references lets tools like
762 .BR man2html (1)
763 create properly hyperlinked pages.)
764 .P
765 Control characters should be written in bold face,
766 with no quotes; for example,
767 .BR \[ha]X .
768 .SS Spelling
769 Starting with release 2.59,
770 .I man-pages
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.
774 .P
775 Aside from the well-known spelling differences,
776 there are a few other subtleties to watch for:
777 .IP \[bu] 3
778 American English tends to use the forms "backward", "upward", "toward",
779 and so on
780 rather than the British forms "backwards", "upwards", "towards", and so on.
781 .IP \[bu]
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
788 .IR x.yBSD ,
789 where
790 .I x.y
791 is the version number (e.g., 4.2BSD).
792 Avoid forms such as
793 .IR "BSD 4.3" .
794 .SS Capitalization
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.
799 For example:
800 .P
801 .in +4n
802 .EX
803 \&.SS Unicode under Linux
804 .EE
805 .in
806 .\"
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
810 .I ".in\ +4n"
811 and
812 .IR ".in" ),
813 format them using the
814 .I .EX
815 and
816 .I .EE
817 macros, and surround them with suitable paragraph markers (either
818 .I .P
819 or
820 .IR .IP ).
821 For example:
822 .P
823 .in +4n
824 .EX
825 \&.P
826 \&.in +4n
827 \&.EX
828 int
829 main(int argc, char *argv[])
830 {
831 return 0;
832 }
833 \&.EE
834 \&.in
835 \&.P
836 .EE
837 .in
838 .SS Preferred terms
839 The following table lists some preferred terms to use in man pages,
840 mainly to ensure consistency across pages.
841 .ad l
842 .TS
843 l l l
844 ---
845 l l ll.
846 Term Avoid using Notes
847
848 bit mask bitmask
849 built-in builtin
850 Epoch epoch T{
851 For the UNIX Epoch (00:00:00, 1 Jan 1970 UTC)
852 T}
853 filename file name
854 filesystem file system
855 hostname host name
856 inode i-node
857 lowercase lower case, lower-case
858 nonzero non-zero
859 pathname path name
860 pseudoterminal pseudo-terminal
861 privileged port T{
862 reserved port,
863 system port
864 T}
865 real-time T{
866 realtime,
867 real time
868 T}
869 run time runtime
870 saved set-group-ID T{
871 saved group ID,
872 saved set-GID
873 T}
874 saved set-user-ID T{
875 saved user ID,
876 saved set-UID
877 T}
878 set-group-ID set-GID, setgid
879 set-user-ID set-UID, setuid
880 superuser T{
881 super user,
882 super-user
883 T}
884 superblock T{
885 super block,
886 super-block
887 T}
888 symbolic link symlink
889 timestamp time stamp
890 timezone time zone
891 uppercase upper case, upper-case
892 usable useable
893 user space userspace
894 username user name
895 x86-64 x86_64 T{
896 Except if referring to result of "uname\ \-m" or similar
897 T}
898 zeros zeroes
899 .TE
900 .P
901 See also the discussion
902 .I Hyphenation of attributive compounds
903 below.
904 .SS Terms to avoid
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.
908 .ad l
909 .TS
910 l l l
911 ---
912 l l l.
913 Avoid Use instead Notes
914
915 32bit 32-bit T{
916 same for 8-bit, 16-bit, etc.
917 T}
918 current process calling process T{
919 A common mistake made by kernel programmers when writing man pages
920 T}
921 manpage T{
922 man page, manual page
923 T}
924 minus infinity negative infinity
925 non-root unprivileged user
926 non-superuser unprivileged user
927 nonprivileged unprivileged
928 OS operating system
929 plus infinity positive infinity
930 pty pseudoterminal
931 tty terminal
932 Unices UNIX systems
933 Unixes UNIX systems
934 .TE
935 .ad
936 .\"
937 .SS Trademarks
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:
941 .IP
942 .TS
943 l.
944 DG/UX
945 HP-UX
946 UNIX
947 UnixWare
948 .TE
949 .SS NULL, NUL, null pointer, and null byte
950 A
951 .I null pointer
952 is a pointer that points to nothing,
953 and is normally indicated by the constant
954 .IR NULL .
955 On the other hand,
956 .I NUL
957 is the
958 .IR "null byte" ,
959 a byte with the value 0, represented in C via the character constant
960 .IR \[aq]\[rs]0\[aq] .
961 .P
962 The preferred term for the pointer is "null pointer" or simply "NULL";
963 avoid writing "NULL pointer".
964 .P
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".
972 .SS Hyperlinks
973 For hyperlinks, use the
974 .IR .UR / .UE
975 macro pair
976 (see
977 .BR groff_man (7)).
978 This produces proper hyperlinks that can be used in a web browser,
979 when rendering a page with, say:
980 .P
981 .in +4n
982 .EX
983 BROWSER=firefox man -H pagename
984 .EE
985 .in
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").
991 .P
992 The only place where such abbreviations may be acceptable is in
993 .I short
994 parenthetical asides (e.g., like this one).
995 .P
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.
998 .SS Em-dashes
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 "\[rs][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
1004 .I without
1005 surrounding spaces.
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:
1009 .IP
1010 .TS
1011 l.
1012 32-bit value
1013 command-line argument
1014 floating-point number
1015 run-time check
1016 user-space function
1017 wide-character string
1018 .TE
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:
1025 .IP
1026 .TS
1027 l.
1028 interprocess
1029 multithreaded
1030 multiprocess
1031 nonblocking
1032 nondefault
1033 nonempty
1034 noninteractive
1035 nonnegative
1036 nonportable
1037 nonzero
1038 preallocated
1039 precreate
1040 prerecorded
1041 reestablished
1042 reinitialize
1043 rearm
1044 reread
1045 subcomponent
1046 subdirectory
1047 subsystem
1048 .TE
1049 .P
1050 Hyphens should be retained when the prefixes are used in nonstandard
1051 English words, with trademarks, proper nouns, acronyms, or compound terms.
1052 Some examples:
1053 .IP
1054 .TS
1055 l.
1056 non-ASCII
1057 non-English
1058 non-NULL
1059 non-real-time
1060 .TE
1061 .P
1062 Finally, note that "re-create" and "recreate" are two different verbs,
1063 and the former is probably what you want.
1064 .\"
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
1068 .BR utf\-8 (7),
1069 or when writing options that have a leading dash, such as in
1070 .IR "ls\ \-l"),
1071 use the following form in the man page source:
1072 .P
1073 .in +4n
1074 .EX
1075 \[rs]\-
1076 .EE
1077 .in
1078 .P
1079 This guideline applies also to code examples.
1080 .P
1081 The use of real minus signs serves the following purposes:
1082 .\" https://lore.kernel.org/linux-man/[email protected]/
1083 .IP \[bu] 3
1084 To provide better renderings on various targets other than
1085 ASCII terminals,
1086 notably in PDF and on Unicode/UTF\-8-capable terminals.
1087 .IP \[bu]
1088 To generate glyphs that when copied from rendered pages will
1089 produce real minus signs when pasted into a terminal.
1090 .P
1091 To produce unslanted single quotes that render well in ASCII, UTF-8, and PDF,
1092 use "\[rs][aq]" ("apostrophe quote"); for example
1093 .P
1094 .in +4n
1095 .EX
1096 \[rs][aq]C\[rs][aq]
1097 .EE
1098 .in
1099 .P
1100 where
1101 .I C
1102 is the quoted character.
1103 This guideline applies also to character constants used in code examples.
1104 .P
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.
1109 .P
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.
1114 .\"
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:
1119 .IP \[bu] 3
1120 Example programs should be written in C.
1121 .IP \[bu]
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.
1127 .IP \[bu]
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.
1132 .IP \[bu]
1133 Expressive code is appreciated.
1134 .IP \[bu]
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.
1142 .IP \[bu]
1143 Example programs should do error checking after system calls and
1144 library function calls.
1145 .IP \[bu]
1146 Example programs should be complete, and compile without
1147 warnings when compiled with \fIcc\ \-Wall\fP.
1148 .IP \[bu]
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).
1153 .IP \[bu]
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:
1159 .IP
1160 .in +4n
1161 .EX
1162 indent \-npro \-kr \-i4 \-ts4 \-sob \-l72 \-ss \-nut \-psl prog.c
1163 .EE
1164 .in
1165 .IP \[bu]
1166 For consistency, all example programs should terminate using either of:
1167 .IP
1168 .in +4n
1169 .EX
1170 exit(EXIT_SUCCESS);
1171 exit(EXIT_FAILURE);
1172 .EE
1173 .in
1174 .IP
1175 Avoid using the following forms to terminate a program:
1176 .IP
1177 .in +4n
1178 .EX
1179 exit(0);
1180 exit(1);
1181 return n;
1182 .EE
1183 .in
1184 .IP \[bu]
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" ,
1189 as in:
1190 .IP
1191 .in +4n
1192 .EX
1193 \&.SS Program source
1194 .EE
1195 .in
1196 .IP
1197 Always do this if the explanatory text includes a shell session log.
1198 .P
1199 If you include a shell session log demonstrating the use of a program
1200 or other system feature:
1201 .IP \[bu] 3
1202 Place the session log above the source code listing.
1203 .IP \[bu]
1204 Indent the session log by four spaces.
1205 .IP \[bu]
1206 Boldface the user input text,
1207 to distinguish it from output produced by the system.
1208 .P
1209 For some examples of what example programs should look like, see
1210 .BR wait (2)
1211 and
1212 .BR pipe (2).
1213 .SH EXAMPLES
1214 For canonical examples of how man pages in the
1215 .I man-pages
1216 package should look, see
1217 .BR pipe (2)
1218 and
1219 .BR fcntl (2).
1220 .SH SEE ALSO
1221 .BR man (1),
1222 .BR man2html (1),
1223 .BR attributes (7),
1224 .BR groff (7),
1225 .BR groff_man (7),
1226 .BR man (7),
1227 .BR mdoc (7)