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