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 Those commands that can be executed by the user from within a
26 shell.
27 2 System calls
29 Those functions which wrap operations performed by the ker‐
30 nel.
31 3 Library calls
33 All library functions excluding the system call wrappers
34 (Most of the libc functions).
35 4 Special files (devices)
37 Files found in /dev which allow to access to devices through
38 the kernel.
39 5 File formats and configuration files
41 Describes various human-readable file formats and configura‐
42 tion files.
43 6 Games Games and funny little programs available on the system.
45 7 Overview, conventions, and miscellaneous
47 Overviews or descriptions of various topics, conventions and
48 protocols, character set standards, the standard filesystem
49 layout, and miscellaneous other things.
50 8 System management commands
52 Commands like mount(8), many of which only root can execute.
53 Macro package
55 New manual pages should be marked up using the groff an.tmac package
56 described in man(7). This choice is mainly for consistency: the vast
57 majority of existing Linux manual pages are marked up using these
58 macros.
59 Conventions for source file layout
61 Please limit source code line length to no more than about 75 charac‐
62 ters wherever possible. This helps avoid line-wrapping in some mail
63 clients when patches are submitted inline.
64 Title line
66 The first command in a man page should be a TH command:
67 .TH title section date source manual
69 where:
71 title The title of the man page, written in all caps (e.g.,
73 MAN-PAGES).
74 section The section number in which the man page should be
76 placed (e.g., 7).
77 date The date of the last nontrivial change that was made
79 to the man page. (Within the man-pages project, the
80 necessary updates to these timestamps are handled
81 automatically by scripts, so there is no need to manu‐
82 ally update them as part of a patch.) Dates should be
83 written in the form YYYY-MM-DD.
84 source The source of the command, function, or system call.
86 For those few man-pages pages in Sections 1 and 8,
88 probably you just want to write GNU.
89 For system calls, just write Linux. (An earlier prac‐
91 tice was to write the version number of the kernel
92 from which the manual page was being written/checked.
93 However, this was never done consistently, and so was
94 probably worse than including no version number.
95 Henceforth, avoid including a version number.)
96 For library calls that are part of glibc or one of the
98 other common GNU libraries, just use GNU C Library,
99 GNU, or an empty string.
100 For Section 4 pages, use Linux.
102 In cases of doubt, just write Linux, or GNU.
104 manual The title of the manual (e.g., for Section 2 and 3
106 pages in the man-pages package, use Linux Programmer's
107 Manual).
108 Sections within a manual page
110 The list below shows conventional or suggested sections. Most manual
111 pages should include at least the highlighted sections. Arrange a new
112 manual page so that sections are placed in the order shown in the list.
113 NAME
115 SYNOPSIS
116 CONFIGURATION [Normally only in Section 4]
117 DESCRIPTION
118 OPTIONS [Normally only in Sections 1, 8]
119 EXIT STATUS [Normally only in Sections 1, 8]
120 RETURN VALUE [Normally only in Sections 2, 3]
121 ERRORS [Typically only in Sections 2, 3]
122 ENVIRONMENT
123 FILES
124 VERSIONS [Normally only in Sections 2, 3]
125 ATTRIBUTES [Normally only in Sections 2, 3]
126 CONFORMING TO
127 NOTES
128 BUGS
129 EXAMPLE
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
146 should follow the .SH NAME command. All words in this
147 line (including the word immediately following the "\-")
148 should be in lowercase, except where English or technical
149 terminological convention dictates otherwise.
150 SYNOPSIS A brief summary of the command or function's interface.
152 For commands, this shows the syntax of the command and
154 its arguments (including options); boldface is used for
155 as-is text and italics are used to indicate replaceable
156 arguments. Brackets ([]) surround optional arguments,
157 vertical bars (|) separate choices, and ellipses (...)
158 can be repeated. For functions, it shows any required
159 data declarations or #include directives, followed by the
160 function declaration.
161 Where a feature test macro must be defined in order to
163 obtain the declaration of a function (or a variable) from
164 a header file, then the SYNOPSIS should indicate this, as
165 described in feature_test_macros(7).
166 CONFIGURATION Configuration details for a device.
168 This section normally appears only in Section 4 pages.
170 DESCRIPTION An explanation of what the program, function, or format
172 does.
173 Discuss how it interacts with files and standard input,
175 and what it produces on standard output or standard
176 error. Omit internals and implementation details unless
177 they're critical for understanding the interface.
178 Describe the usual case; for information on command-line
179 options of a program use the OPTIONS section.
180 When describing new behavior or new flags for a system
182 call or library function, be careful to note the kernel
183 or C library version that introduced the change. The
184 preferred method of noting this information for flags is
185 as part of a .TP list, in the following form (here, for a
186 new system call flag):
187 XYZ_FLAG (since Linux 3.7)
189 Description of flag...
190 Including version information is especially useful to
192 users who are constrained to using older kernel or C
193 library versions (which is typical in embedded systems,
194 for example).
195 OPTIONS A description of the command-line options accepted by a
197 program and how they change its behavior.
198 This section should appear only for Section 1 and 8 man‐
200 ual pages.
201 EXIT STATUS A list of the possible exit status values of a program
203 and the conditions that cause these values to be
204 returned.
205 This section should appear only for Section 1 and 8 man‐
207 ual pages.
208 RETURN VALUE For Section 2 and 3 pages, this section gives a list of
210 the values the library routine will return to the caller
211 and the conditions that cause these values to be
212 returned.
213 ERRORS For Section 2 and 3 manual pages, this is a list of the
215 values that may be placed in errno in the event of an
216 error, along with information about the cause of the
217 errors.
218 Where several different conditions produce the same
220 error, the preferred approach is to create separate list
221 entries (with duplicate error names) for each of the con‐
222 ditions. This makes the separate conditions clear, may
223 make the list easier to read, and allows metainformation
224 (e.g., kernel version number where the condition first
225 became applicable) to be more easily marked for each con‐
226 dition.
227 The error list should be in alphabetical order.
229 ENVIRONMENT A list of all environment variables that affect the pro‐
231 gram or function and how they affect it.
232 FILES A list of the files the program or function uses, such as
234 configuration files, startup files, and files the program
235 directly operates on.
236 Give the full pathname of these files, and use the
238 installation process to modify the directory part to
239 match user preferences. For many programs, the default
240 installation location is in /usr/local, so your base man‐
241 ual page should use /usr/local as the base.
242 ATTRIBUTES A summary of various attributes of the function(s) docu‐
244 mented on this page. See attributes(7) for further
245 details.
246 VERSIONS A brief summary of the Linux kernel or glibc versions
248 where a system call or library function appeared, or
249 changed significantly in its operation.
250 As a general rule, every new interface should include a
252 VERSIONS section in its manual page. Unfortunately, many
253 existing manual pages don't include this information
254 (since there was no policy to do so when they were writ‐
255 ten). Patches to remedy this are welcome, but, from the
256 perspective of programmers writing new code, this infor‐
257 mation probably matters only in the case of kernel inter‐
258 faces that have been added in Linux 2.4 or later (i.e.,
259 changes since kernel 2.2), and library functions that
260 have been added to glibc since version 2.1 (i.e., changes
261 since glibc 2.0).
262 The syscalls(2) manual page also provides information
264 about kernel versions in which various system calls first
265 appeared.
266 CONFORMING TO A description of any standards or conventions that relate
268 to the function or command described by the manual page.
269 The preferred terms to use for the various standards are
271 listed as headings in standards(7).
272 For a page in Section 2 or 3, this section should note
274 the POSIX.1 version(s) that the call conforms to, and
275 also whether the call is specified in C99. (Don't worry
276 too much about other standards like SUS, SUSv2, and XPG,
277 or the SVr4 and 4.xBSD implementation standards, unless
278 the call was specified in those standards, but isn't in
279 the current version of POSIX.1.)
280 If the call is not governed by any standards but commonly
282 exists on other systems, note them. If the call is
283 Linux-specific, note this.
284 If this section consists of just a list of standards
286 (which it commonly does), terminate the list with a
287 period ('.').
288 NOTES Miscellaneous notes.
290 For Section 2 and 3 man pages you may find it useful to
292 include subsections (SS) named Linux Notes and Glibc
293 Notes.
294 In Section 2, use the heading C library/kernel differ‐
296 ences to mark off notes that describe the differences (if
297 any) between the C library wrapper function for a system
298 call and the raw system call interface provided by the
299 kernel.
300 BUGS A list of limitations, known defects or inconveniences,
302 and other questionable activities.
303 EXAMPLE One or more examples demonstrating how this function,
305 file or command is used.
306 For details on writing example programs, see Example pro‐
308 grams below.
309 AUTHORS A list of authors of the documentation or program.
311 Use of an AUTHORS section is strongly discouraged. Gen‐
313 erally, it is better not to clutter every page with a
314 list of (over time potentially numerous) authors; if you
315 write or significantly amend a page, add a copyright
316 notice as a comment in the source file. If you are the
317 author of a device driver and want to include an address
318 for reporting bugs, place this under the BUGS section.
319 SEE ALSO A comma-separated list of related man pages, possibly
321 followed by other related pages or documents.
322 The list should be ordered by section number and then
324 alphabetically by name. Do not terminate this list with
325 a period.
326 Where the SEE ALSO list contains many long manual page
328 names, to improve the visual result of the output, it may
329 be useful to employ the .ad l (don't right justify) and
330 .nh (don't hyphenate) directives. Hyphenation of indi‐
331 vidual page names can be prevented by preceding words
332 with the string "\%".
333 Given the distributed, autonomous nature of FOSS projects
335 and their documentation, it is sometimes necessary—and in
336 many cases desirable—that the SEE ALSO section includes
337 references to manual pages provided by other projects.
338
340 The following subsections describe the preferred style for the man-
341 pages project. For details not covered below, the Chicago Manual of
342 Style is usually a good source; try also grepping for preexisting usage
343 in the project source tree.
344 Use of gender-neutral language
346 As far as possible, use gender-neutral language in the text of man
347 pages. Use of "they" ("them", "themself", "their") as a gender-neutral
348 singular pronoun is acceptable.
349 Formatting conventions for manual pages describing commands
351 For manual pages that describe a command (typically in Sections 1 and
352 8), the arguments are always specified using italics, even in the SYN‐
353 OPSIS section.
354 The name of the command, and its options, should always be formatted in
356 bold.
357 Formatting conventions for manual pages describing functions
359 For manual pages that describe functions (typically in Sections 2 and
360 3), the arguments are always specified using italics, even in the SYN‐
361 OPSIS section, where the rest of the function is specified in bold:
362 int myfunction(int argc, char **argv);
364 Variable names should, like argument names, be specified in italics.
366 Any reference to the subject of the current manual page should be writ‐
368 ten with the name in bold followed by a pair of parentheses in Roman
369 (normal) font. For example, in the fcntl(2) man page, references to
370 the subject of the page would be written as: fcntl(). The preferred
371 way to write this in the source file is:
372 .BR fcntl ()
374 (Using this format, rather than the use of "\fB...\fP()" makes it eas‐
376 ier to write tools that parse man page source files.)
377 Use semantic newlines
379 In the source of a manual page, new sentences should be started on new
380 lines, and long sentences should split into lines at clause breaks
381 (commas, semicolons, colons, and so on). This convention, sometimes
382 known as "semantic newlines", makes it easier to see the effect of
383 patches, which often operate at the level of individual sentences or
384 sentence clauses.
385 Formatting conventions (general)
387 Paragraphs should be separated by suitable markers (usually either .PP
388 or .IP). Do not separate paragraphs using blank lines, as this results
389 in poor rendering in some output formats (such as PostScript and PDF).
390 Filenames (whether pathnames, or references to header files) are always
392 in italics (e.g., <stdio.h>), except in the SYNOPSIS section, where
393 included files are in bold (e.g., #include <stdio.h>). When referring
394 to a standard header file include, specify the header file surrounded
395 by angle brackets, in the usual C way (e.g., <stdio.h>).
396 Special macros, which are usually in uppercase, are in bold (e.g., MAX‐
398 INT). Exception: don't boldface NULL.
399 When enumerating a list of error codes, the codes are in bold (this
401 list usually uses the .TP macro).
402 Complete commands should, if long, be written as an indented line on
404 their own, with a blank line before and after the command, for example
405 man 7 man-pages
407 If the command is short, then it can be included inline in the text, in
409 italic format, for example, man 7 man-pages. In this case, it may be
410 worth using nonbreaking spaces ("\ ") at suitable places in the com‐
411 mand. Command options should be written in italics (e.g., -l).
412 Expressions, if not written on a separate indented line, should be
414 specified in italics. Again, the use of nonbreaking spaces may be
415 appropriate if the expression is inlined with normal text.
416 When showing example shell sessions, user input should be formatted in
418 bold, for example
419 $ date
421 Thu Jul 7 13:01:27 CEST 2016
422 Any reference to another man page should be written with the name in
424 bold, always followed by the section number, formatted in Roman (nor‐
425 mal) font, without any separating spaces (e.g., intro(2)). The pre‐
426 ferred way to write this in the source file is:
427 .BR intro (2)
429 (Including the section number in cross references lets tools like
431 man2html(1) create properly hyperlinked pages.)
432 Control characters should be written in bold face, with no quotes; for
434 example, ^X.
435 Spelling
437 Starting with release 2.59, man-pages follows American spelling conven‐
438 tions (previously, there was a random mix of British and American
439 spellings); please write all new pages and patches according to these
440 conventions.
441 Aside from the well-known spelling differences, there are a few other
443 subtleties to watch for:
444 * American English tends to use the forms "backward", "upward",
446 "toward", and so on rather than the British forms "backwards",
447 "upwards", "towards", and so on.
448 BSD version numbers
450 The classical scheme for writing BSD version numbers is x.yBSD, where
451 x.y is the version number (e.g., 4.2BSD). Avoid forms such as BSD 4.3.
452 Capitalization
454 In subsection ("SS") headings, capitalize the first word in the head‐
455 ing, but otherwise use lowercase, except where English usage (e.g.,
456 proper nouns) or programming language requirements (e.g., identifier
457 names) dictate otherwise. For example:
458 .SS Unicode under Linux
460 Indentation of structure definitions, shell session logs, and so on
462 When structure definitions, shell session logs, and so on are included
463 in running text, indent them by 4 spaces (i.e., a block enclosed by
464 .in +4n and .in), format them using the .EX and EE macros, and surround
465 them with suitable paragraph markers (either .PP or .IP). For example:
466 .PP
468 .in +4n
469 .EX
470 int
471 main(int argc, char *argv[])
472 {
473 return 0;
474 }
475 .EE
476 .in
477 .PP
478 Preferred terms
480 The following table lists some preferred terms to use in man pages,
481 mainly to ensure consistency across pages.
482 Term Avoid using Notes
484 ──────────────────────────────────────────────────────────────────
485 bit mask bitmask
487 built-in builtin
488 Epoch epoch For the UNIX Epoch
489 (00:00:00, 1 Jan
490 1970 UTC)
491 filename file name
492 filesystem file system
493 hostname host name
494 inode i-node
495 lowercase lower case, lower-case
496 nonzero non-zero
497 pathname path name
498 pseudoterminal pseudo-terminal
499 privileged port reserved port, system
500 port
501 real-time realtime, real time
502 run time runtime
503 saved set-group-ID saved group ID, saved
504 set-GID
505 saved set-user-ID saved user ID, saved
506 set-UID
507 set-group-ID set-GID, setgid
508 set-user-ID set-UID, setuid
509 superuser super user, super-user
510 superblock super block, super-
511 block
512 timestamp time stamp
513 timezone time zone
514 uppercase upper case, upper-case
515 usable useable
516 user space userspace
517 username user name
518 x86-64 x86_64 Except if referring
519 to result of
520 "uname -m" or simi‐
521 lar
522 zeros zeroes
523 See also the discussion Hyphenation of attributive compounds below.
525 Terms to avoid
527 The following table lists some terms to avoid using in man pages, along
528 with some suggested alternatives, mainly to ensure consistency across
529 pages.
530 Avoid Use instead Notes
532 ────────────────────────────────────────────────────────────
533 32bit 32-bit same for 8-bit,
535 16-bit, etc.
536 current process calling process A common mistake
538 made by kernel pro‐
539 grammers when writ‐
540 ing man pages
541 manpage man page, manual
542 page
543 minus infinity negative infinity
544 non-root unprivileged user
545 non-superuser unprivileged user
546 nonprivileged unprivileged
547 OS operating system
548 plus infinity positive infinity
549 pty pseudoterminal
550 tty terminal
551 Unices UNIX systems
552 Unixes UNIX systems
553 Trademarks
555 Use the correct spelling and case for trademarks. The following is a
556 list of the correct spellings of various relevant trademarks that are
557 sometimes misspelled:
558 DG/UX
560 HP-UX
561 UNIX
562 UnixWare
563 NULL, NUL, null pointer, and null character
565 A null pointer is a pointer that points to nothing, and is normally
566 indicated by the constant NULL. On the other hand, NUL is the null
567 byte, a byte with the value 0, represented in C via the character con‐
568 stant '\0'.
569 The preferred term for the pointer is "null pointer" or simply "NULL";
571 avoid writing "NULL pointer".
572 The preferred term for the byte is "null byte". Avoid writing "NUL",
574 since it is too easily confused with "NULL". Avoid also the terms
575 "zero byte" and "null character". The byte that terminates a C string
576 should be described as "the terminating null byte"; strings may be
577 described as "null-terminated", but avoid the use of "NUL-terminated".
578 Hyperlinks
580 For hyperlinks, use the .UR/.UE macro pair (see groff_man(7)). This
581 produces proper hyperlinks that can be used in a web browser, when ren‐
582 dering a page with, say:
583 BROWSER=firefox man -H pagename
585 Use of e.g., i.e., etc., a.k.a., and similar
587 In general, the use of abbreviations such as "e.g.", "i.e.", "etc.",
588 "cf.", and "a.k.a." should be avoided, in favor of suitable full word‐
589 ings ("for example", "that is", "compare to", "and so on", "also known
590 as").
591 The only place where such abbreviations may be acceptable is in short
593 parenthetical asides (e.g., like this one).
594 Always include periods in such abbreviations, as shown here. In addi‐
596 tion, "e.g." and "i.e." should always be followed by a comma.
597 Em-dashes
599 The way to write an em-dash—the glyph that appears at either end of
600 this subphrase—in *roff is with the macro "\(em". (On an ASCII termi‐
601 nal, an em-dash typically renders as two hyphens, but in other typo‐
602 graphical contexts it renders as a long dash.) Em-dashes should be
603 written without surrounding spaces.
604 Hyphenation of attributive compounds
606 Compound terms should be hyphenated when used attributively (i.e., to
607 qualify a following noun). Some examples:
608 32-bit value
610 command-line argument
611 floating-point number
612 run-time check
613 user-space function
614 wide-character string
615 Hyphenation with multi, non, pre, re, sub, and so on
617 The general tendency in modern English is not to hyphenate after pre‐
618 fixes such as "multi", "non", "pre", "re", "sub", and so on. Manual
619 pages should generally follow this rule when these prefixes are used in
620 natural English constructions with simple suffixes. The following list
621 gives some examples of the preferred forms:
622 interprocess
624 multithreaded
625 multiprocess
626 nonblocking
627 nondefault
628 nonempty
629 noninteractive
630 nonnegative
631 nonportable
632 nonzero
633 preallocated
634 precreate
635 prerecorded
636 reestablished
637 reinitialize
638 rearm
639 reread
640 subcomponent
641 subdirectory
642 subsystem
643 Hyphens should be retained when the prefixes are used in nonstandard
645 English words, with trademarks, proper nouns, acronyms, or compound
646 terms. Some examples:
647 non-ASCII
649 non-English
650 non-NULL
651 non-real-time
652 Finally, note that "re-create" and "recreate" are two different verbs,
654 and the former is probably what you want.
655 Real minus character
657 Where a real minus character is required (e.g., for numbers such as -1,
658 for man page cross references such as utf-8(7), or when writing options
659 that have a leading dash, such as in ls -l), use the following form in
660 the man page source:
661 \-
663 This guideline applies also to code examples.
665 Character constants
667 To produce single quotes that render well in both ASCII and UTF-8, use
668 the following form for character constants in the man page source:
669 \(aqC\(aq
671 where C is the quoted character. This guideline applies also to char‐
673 acter constants used in code examples.
674 Example programs and shell sessions
676 Manual pages may include example programs demonstrating how to use a
677 system call or library function. However, note the following:
678 * Example programs should be written in C.
680 * An example program is necessary and useful only if it demonstrates
682 something beyond what can easily be provided in a textual descrip‐
683 tion of the interface. An example program that does nothing other
684 than call an interface usually serves little purpose.
685 * Example programs should be fairly short (preferably less than 100
687 lines; ideally less than 50 lines).
688 * Example programs should do error checking after system calls and
690 library function calls.
691 * Example programs should be complete, and compile without warnings
693 when compiled with cc -Wall.
694 * Where possible and appropriate, example programs should allow exper‐
696 imentation, by varying their behavior based on inputs (ideally from
697 command-line arguments, or alternatively, via input read by the pro‐
698 gram).
699 * Example programs should be laid out according to Kernighan and
701 Ritchie style, with 4-space indents. (Avoid the use of TAB charac‐
702 ters in source code!) The following command can be used to format
703 your source code to something close to the preferred style:
704 indent -npro -kr -i4 -ts4 -sob -l72 -ss -nut -psl prog.c
706 * For consistency, all example programs should terminate using either
708 of:
709 exit(EXIT_SUCCESS);
711 exit(EXIT_FAILURE);
712 Avoid using the following forms to terminate a program:
714 exit(0);
716 exit(1);
717 return n;
718 * If there is extensive explanatory text before the program source
720 code, mark off the source code with a subsection heading Program
721 source, as in:
722 .SS Program source
724 Always do this if the explanatory text includes a shell session log.
726 If you include a shell session log demonstrating the use of a program
728 or other system feature:
729 * Place the session log above the source code listing
731 * Indent the session log by four spaces.
733 * Boldface the user input text, to distinguish it from output produced
735 by the system.
736 For some examples of what example programs should look like, see
738 wait(2) and pipe(2).
739
741 For canonical examples of how man pages in the man-pages package should
742 look, see pipe(2) and fcntl(2).
743
745 man(1), man2html(1), attributes(7), groff(7), groff_man(7), man(7),
746 mdoc(7)
747
749 This page is part of release 5.04 of the Linux man-pages project. A
750 description of the project, information about reporting bugs, and the
751 latest version of this page, can be found at
752 https://www.kernel.org/doc/man-pages/.
753Linux 2019-10-10 MAN-PAGES(7)