Debian Codegraph @

upstream/debian-unstable/man7/man-pages.7

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