1 .\" (C) Copyright 1992-1999 Rickard E. Faith and David A. Wheeler
2 .\" (faith@cs.unc.edu and dwheeler@ida.org)
3 .\" and (C) Copyright 2007 Michael Kerrisk <mtk.manpages@gmail.com>
5 .\" %%%LICENSE_START(VERBATIM)
6 .\" Permission is granted to make and distribute verbatim copies of this
7 .\" manual provided the copyright notice and this permission notice are
8 .\" preserved on all copies.
10 .\" Permission is granted to copy and distribute modified versions of this
11 .\" manual under the conditions for verbatim copying, provided that the
12 .\" entire resulting derived work is distributed under the terms of a
13 .\" permission notice identical to this one.
15 .\" Since the Linux kernel and libraries are constantly changing, this
16 .\" manual page may be incorrect or out-of-date. The author(s) assume no
17 .\" responsibility for errors or omissions, or for damages resulting from
18 .\" the use of the information contained herein. The author(s) may not
19 .\" have taken the same level of care in the production of this manual,
20 .\" which is licensed free of charge, as they might when working
23 .\" Formatted or processed versions of this manual, if unaccompanied by
24 .\" the source, must acknowledge the copyright and authors of this work.
27 .\" 2007-05-30 created by mtk, using text from old man.7 plus
28 .\" rewrites and additional text.
30 .TH MAN-PAGES 7 2020-04-11 "Linux" "Linux Programmer's Manual"
32 man-pages \- conventions for writing Linux man pages
38 This page describes the conventions that should be employed
39 when writing man pages for the Linux \fIman-pages\fP project,
40 which documents the user-space API provided by the Linux kernel
41 and the GNU C library.
42 The project thus provides most of the pages in Section 2,
43 many of the pages that appear in Sections 3, 4, and 7,
44 and a few of the pages that appear in Sections 1, 5, and 8
45 of the man pages on a Linux system.
46 The conventions described on this page may also be useful
47 for authors writing man pages for other projects.
48 .SS Sections of the manual pages
50 The manual Sections are traditionally defined as follows:
52 .B 1 User commands (Programs)
53 Commands that can be executed by the user from within
57 Functions which wrap operations performed by the kernel.
60 All library functions excluding the system call wrappers
65 .B 4 Special files (devices)
68 which allow to access to devices through the kernel.
70 .B 5 File formats and configuration files
71 Describes various human-readable file formats and configuration files.
74 Games and funny little programs available on the system.
76 .B 7 Overview, conventions, and miscellaneous
77 Overviews or descriptions of various topics, conventions and protocols,
78 character set standards, the standard filesystem layout, and miscellaneous
81 .B 8 System management commands
84 many of which only root can execute.
86 .\" .B 9 Kernel routines
87 .\" This is an obsolete manual section.
88 .\" Once it was thought a good idea to document the Linux kernel here,
89 .\" but in fact very little has been documented, and the documentation
90 .\" that exists is outdated already.
91 .\" There are better sources of
92 .\" information for kernel developers.
94 New manual pages should be marked up using the
98 This choice is mainly for consistency: the vast majority of
99 existing Linux manual pages are marked up using these macros.
100 .SS Conventions for source file layout
101 Please limit source code line length to no more than about 75 characters
103 This helps avoid line-wrapping in some mail clients when patches are
106 The first command in a man page should be a
112 .I "title section date source manual"
119 The title of the man page, written in all caps (e.g.,
123 The section number in which the man page should be placed (e.g.,
127 The date of the last nontrivial change that was made to the man page.
130 project, the necessary updates to these timestamps are handled
131 automatically by scripts, so there is no need to manually update
132 them as part of a patch.)
133 Dates should be written in the form YYYY-MM-DD.
136 The source of the command, function, or system call.
138 For those few \fIman-pages\fP pages in Sections 1 and 8,
139 probably you just want to write
142 For system calls, just write
144 (An earlier practice was to write the version number
145 of the kernel from which the manual page was being written/checked.
146 However, this was never done consistently, and so was
147 probably worse than including no version number.
148 Henceforth, avoid including a version number.)
150 For library calls that are part of glibc or one of the
151 other common GNU libraries, just use
152 .IR "GNU C Library" ", " GNU ,
155 For Section 4 pages, use
158 In cases of doubt, just write
159 .IR Linux ", or " GNU .
162 The title of the manual (e.g., for Section 2 and 3 pages in
163 the \fIman-pages\fP package, use
164 .IR "Linux Programmer's Manual" ).
166 .SS Sections within a manual page
167 The list below shows conventional or suggested sections.
168 Most manual pages should include at least the
171 Arrange a new manual page so that sections
172 are placed in the order shown in the list.
178 CONFIGURATION [Normally only in Section 4]
180 OPTIONS [Normally only in Sections 1, 8]
181 EXIT STATUS [Normally only in Sections 1, 8]
182 RETURN VALUE [Normally only in Sections 2, 3]
183 .\" May 07: Few current man pages have an ERROR HANDLING section,,,
185 ERRORS [Typically only in Sections 2, 3]
186 .\" May 07: Almost no current man pages have a USAGE section,,,
189 .\" May 07: Almost no current man pages have a SECURITY section,,,
193 VERSIONS [Normally only in Sections 2, 3]
194 ATTRIBUTES [Normally only in Sections 2, 3]
199 .\" AUTHORS sections are discouraged
200 AUTHORS [Discouraged]
201 REPORTING BUGS [Not used in man-pages]
202 COPYRIGHT [Not used in man-pages]
207 .IR "Where a traditional heading would apply" ", " "please use it" ;
208 this kind of consistency can make the information easier to understand.
209 If you must, you can create your own
210 headings if they make things easier to understand (this can
211 be especially useful for pages in Sections 4 and 5).
212 However, before doing this, consider whether you could use the
213 traditional headings, with some subsections (\fI.SS\fP) within
216 The following list elaborates on the contents of each of
220 The name of this manual page.
224 for important details of the line(s) that should follow the
225 \fB.SH NAME\fP command.
226 All words in this line (including the word immediately
227 following the "\e\-") should be in lowercase,
228 except where English or technical terminological convention
232 A brief summary of the command or function's interface.
234 For commands, this shows the syntax of the command and its arguments
236 boldface is used for as-is text and italics are used to
237 indicate replaceable arguments.
238 Brackets ([]) surround optional arguments, vertical bars (|)
239 separate choices, and ellipses (\&...) can be repeated.
240 For functions, it shows any required data declarations or
242 directives, followed by the function declaration.
244 Where a feature test macro must be defined in order to obtain
245 the declaration of a function (or a variable) from a header file,
246 then the SYNOPSIS should indicate this, as described in
247 .BR feature_test_macros (7).
248 .\" FIXME . Say something here about compiler options
251 Configuration details for a device.
253 This section normally appears only in Section 4 pages.
256 An explanation of what the program, function, or format does.
258 Discuss how it interacts with files and standard input, and what it
259 produces on standard output or standard error.
260 Omit internals and implementation details unless they're critical for
261 understanding the interface.
262 Describe the usual case;
263 for information on command-line options of a program use the
266 .\" If there is some kind of input grammar or complex set of subcommands,
267 .\" consider describing them in a separate
269 .\" section (and just place an overview in the
273 When describing new behavior or new flags for
274 a system call or library function,
275 be careful to note the kernel or C library version
276 that introduced the change.
277 The preferred method of noting this information for flags is as part of a
279 list, in the following form (here, for a new system call flag):
282 .BR XYZ_FLAG " (since Linux 3.7)"
283 Description of flag...
286 Including version information is especially useful to users
287 who are constrained to using older kernel or C library versions
288 (which is typical in embedded systems, for example).
291 A description of the command-line options accepted by a
292 program and how they change its behavior.
294 This section should appear only for Section 1 and 8 manual pages.
297 .\" describes the grammar of any sublanguage this implements.
300 A list of the possible exit status values of a program and
301 the conditions that cause these values to be returned.
303 This section should appear only for Section 1 and 8 manual pages.
306 For Section 2 and 3 pages, this section gives a
307 list of the values the library routine will return to the caller
308 and the conditions that cause these values to be returned.
311 For Section 2 and 3 manual pages, this is a list of the
312 values that may be placed in
314 in the event of an error, along with information about the cause
317 Where several different conditions produce the same error,
318 the preferred approach is to create separate list entries
319 (with duplicate error names) for each of the conditions.
320 This makes the separate conditions clear, may make the list easier to read,
321 and allows metainformation
322 (e.g., kernel version number where the condition first became applicable)
323 to be more easily marked for each condition.
325 .IR "The error list should be in alphabetical order" .
328 A list of all environment variables that affect the program or function
329 and how they affect it.
332 A list of the files the program or function uses, such as
333 configuration files, startup files,
334 and files the program directly operates on.
336 Give the full pathname of these files, and use the installation
337 process to modify the directory part to match user preferences.
338 For many programs, the default installation location is in
340 so your base manual page should use
343 .\" May 07: Almost no current man pages have a DIAGNOSTICS section;
344 .\" "RETURN VALUE" or "EXIT STATUS" is preferred.
347 .\" gives an overview of the most common error messages and how to
349 .\" You don't need to explain system error messages
350 .\" or fatal signals that can appear during execution of any program
351 .\" unless they're special in some way to the program.
353 .\" May 07: Almost no current man pages have a SECURITY section.
356 .\"discusses security issues and implications.
357 .\"Warn about configurations or environments that should be avoided,
358 .\"commands that may have security implications, and so on, especially
359 .\"if they aren't obvious.
360 .\"Discussing security in a separate section isn't necessary;
361 .\"if it's easier to understand, place security information in the
362 .\"other sections (such as the
367 .\" However, please include security information somewhere!
370 A summary of various attributes of the function(s) documented on this page.
376 A brief summary of the Linux kernel or glibc versions where a
377 system call or library function appeared,
378 or changed significantly in its operation.
380 As a general rule, every new interface should
381 include a VERSIONS section in its manual page.
383 many existing manual pages don't include this information
384 (since there was no policy to do so when they were written).
385 Patches to remedy this are welcome,
386 but, from the perspective of programmers writing new code,
387 this information probably matters only in the case of kernel
388 interfaces that have been added in Linux 2.4 or later
389 (i.e., changes since kernel 2.2),
390 and library functions that have been added to glibc since version 2.1
391 (i.e., changes since glibc 2.0).
395 manual page also provides information about kernel versions
396 in which various system calls first appeared.
399 A description of any standards or conventions that relate to the function
400 or command described by the manual page.
402 The preferred terms to use for the various standards are listed as
406 For a page in Section 2 or 3,
407 this section should note the POSIX.1
408 version(s) that the call conforms to,
409 and also whether the call is specified in C99.
410 (Don't worry too much about other standards like SUS, SUSv2, and XPG,
411 or the SVr4 and 4.xBSD implementation standards,
412 unless the call was specified in those standards,
413 but isn't in the current version of POSIX.1.)
415 If the call is not governed by any standards but commonly
416 exists on other systems, note them.
417 If the call is Linux-specific, note this.
419 If this section consists of just a list of standards
420 (which it commonly does),
421 terminate the list with a period (\(aq.\(aq).
426 For Section 2 and 3 man pages you may find it useful to include
427 subsections (\fBSS\fP) named \fILinux Notes\fP and \fIGlibc Notes\fP.
429 In Section 2, use the heading
430 .I "C library/kernel differences"
431 to mark off notes that describe the differences (if any) between
432 the C library wrapper function for a system call and
433 the raw system call interface provided by the kernel.
436 A list of limitations, known defects or inconveniences,
437 and other questionable activities.
440 One or more examples demonstrating how this function, file or
443 For details on writing example programs,
444 see \fIExample programs\fP below.
447 A list of authors of the documentation or program.
449 \fBUse of an AUTHORS section is strongly discouraged\fP.
450 Generally, it is better not to clutter every page with a list
451 of (over time potentially numerous) authors;
452 if you write or significantly amend a page,
453 add a copyright notice as a comment in the source file.
454 If you are the author of a device driver and want to include
455 an address for reporting bugs, place this under the BUGS section.
460 project doesn't use a REPORTING BUGS section in manual pages.
461 Information on reporting bugs is instead supplied in the
462 script-generated COLOPHON section.
463 However, various projects do use a REPORTING BUGS section.
464 it is recommended to place it near the foot of the page.
469 project doesn't use a COPYRIGHT section in manual pages.
470 Copyright information is instead maintained in the page source.
471 In pages where this section is present,
472 it is recommended to place it near the foot of the page, just above SEE ALSO.
475 A comma-separated list of related man pages, possibly followed by
476 other related pages or documents.
478 The list should be ordered by section number and
479 then alphabetically by name.
480 Do not terminate this list with a period.
482 Where the SEE ALSO list contains many long manual page names,
483 to improve the visual result of the output, it may be useful to employ the
485 (don't right justify)
490 Hyphenation of individual page names can be prevented
491 by preceding words with the string "\e%".
493 Given the distributed, autonomous nature of FOSS projects
494 and their documentation, it is sometimes necessary\(emand in many cases
495 desirable\(emthat the SEE ALSO section includes references to
496 manual pages provided by other projects.
498 The following subsections describe the preferred style for the
501 For details not covered below, the Chicago Manual of Style
502 is usually a good source;
503 try also grepping for preexisting usage in the project source tree.
504 .SS Use of gender-neutral language
505 As far as possible, use gender-neutral language in the text of man
507 Use of "they" ("them", "themself", "their") as a gender-neutral singular
508 pronoun is acceptable.
510 .SS Formatting conventions for manual pages describing commands
512 For manual pages that describe a command (typically in Sections 1 and 8),
513 the arguments are always specified using italics,
514 .IR "even in the SYNOPSIS section" .
516 The name of the command, and its options, should
517 always be formatted in bold.
519 .SS Formatting conventions for manual pages describing functions
520 For manual pages that describe functions (typically in Sections 2 and 3),
521 the arguments are always specified using italics,
522 .IR "even in the SYNOPSIS section" ,
523 where the rest of the function is specified in bold:
525 .BI " int myfunction(int " argc ", char **" argv );
527 Variable names should, like argument names, be specified in italics.
529 Any reference to the subject of the current manual page
530 should be written with the name in bold followed by
531 a pair of parentheses in Roman (normal) font.
534 man page, references to the subject of the page would be written as:
536 The preferred way to write this in the source file is:
542 (Using this format, rather than the use of "\efB...\efP()"
543 makes it easier to write tools that parse man page source files.)
545 .SS Use semantic newlines
546 In the source of a manual page,
547 new sentences should be started on new lines,
548 and long sentences should split into lines at clause breaks
549 (commas, semicolons, colons, and so on).
550 This convention, sometimes known as "semantic newlines",
551 makes it easier to see the effect of patches,
552 which often operate at the level of individual sentences or sentence clauses.
554 .SS Formatting conventions (general)
556 Paragraphs should be separated by suitable markers (usually either
562 separate paragraphs using blank lines, as this results in poor rendering
563 in some output formats (such as PostScript and PDF).
565 Filenames (whether pathnames, or references to header files)
566 are always in italics (e.g.,
568 except in the SYNOPSIS section, where included files are in bold (e.g.,
569 .BR "#include <stdio.h>" ).
570 When referring to a standard header file include,
571 specify the header file surrounded by angle brackets,
572 in the usual C way (e.g.,
575 Special macros, which are usually in uppercase, are in bold (e.g.,
577 Exception: don't boldface NULL.
579 When enumerating a list of error codes, the codes are in bold (this list
584 Complete commands should, if long,
585 be written as an indented line on their own,
586 with a blank line before and after the command, for example
594 If the command is short, then it can be included inline in the text,
595 in italic format, for example,
596 .IR "man 7 man-pages" .
597 In this case, it may be worth using nonbreaking spaces
598 ("\e\ ") at suitable places in the command.
599 Command options should be written in italics (e.g.,
602 Expressions, if not written on a separate indented line, should
603 be specified in italics.
604 Again, the use of nonbreaking spaces may be appropriate
605 if the expression is inlined with normal text.
607 When showing example shell sessions, user input should be formatted in bold, for example
612 Thu Jul 7 13:01:27 CEST 2016
617 Any reference to another man page
618 should be written with the name in bold,
620 followed by the section number,
621 formatted in Roman (normal) font, without any
622 separating spaces (e.g.,
624 The preferred way to write this in the source file is:
630 (Including the section number in cross references lets tools like
632 create properly hyperlinked pages.)
634 Control characters should be written in bold face,
635 with no quotes; for example,
638 Starting with release 2.59,
640 follows American spelling conventions
641 (previously, there was a random mix of British and American spellings);
642 please write all new pages and patches according to these conventions.
644 Aside from the well-known spelling differences,
645 there are a few other subtleties to watch for:
647 American English tends to use the forms "backward", "upward", "toward",
649 rather than the British forms "backwards", "upwards", "towards", and so on.
650 .SS BSD version numbers
651 The classical scheme for writing BSD version numbers is
655 is the version number (e.g., 4.2BSD).
659 In subsection ("SS") headings,
660 capitalize the first word in the heading, but otherwise use lowercase,
661 except where English usage (e.g., proper nouns) or programming
662 language requirements (e.g., identifier names) dictate otherwise.
666 .SS Unicode under Linux
669 .SS Indentation of structure definitions, shell session logs, and so on
670 When structure definitions, shell session logs, and so on are included
671 in running text, indent them by 4 spaces (i.e., a block enclosed by
675 format them using the
679 macros, and surround them with suitable paragraph markers (either
691 main(int argc, char *argv[])
701 The following table lists some preferred terms to use in man pages,
702 mainly to ensure consistency across pages.
707 Term Avoid using Notes
712 For the UNIX Epoch (00:00:00, 1 Jan 1970 UTC)
715 filesystem file system
718 lowercase lower case, lower-case
721 pseudoterminal pseudo-terminal
731 saved set-group-ID T{
739 set-group-ID set-GID, setgid
740 set-user-ID set-UID, setuid
751 uppercase upper case, upper-case
756 Except if referring to result of "uname\ \-m" or similar
761 See also the discussion
762 .IR "Hyphenation of attributive compounds"
765 The following table lists some terms to avoid using in man pages,
766 along with some suggested alternatives,
767 mainly to ensure consistency across pages.
772 Avoid Use instead Notes
775 same for 8-bit, 16-bit, etc.
777 current process calling process T{
778 A common mistake made by kernel programmers when writing man pages
781 man page, manual page
783 minus infinity negative infinity
784 non-root unprivileged user
785 non-superuser unprivileged user
786 nonprivileged unprivileged
788 plus infinity positive infinity
795 Use the correct spelling and case for trademarks.
796 The following is a list of the correct spellings of various
797 relevant trademarks that are sometimes misspelled:
803 .SS NULL, NUL, null pointer, and null character
806 is a pointer that points to nothing,
807 and is normally indicated by the constant
813 a byte with the value 0, represented in C via the character constant
816 The preferred term for the pointer is "null pointer" or simply "NULL";
817 avoid writing "NULL pointer".
819 The preferred term for the byte is "null byte".
820 Avoid writing "NUL", since it is too easily confused with "NULL".
821 Avoid also the terms "zero byte" and "null character".
822 The byte that terminates a C string should be described
823 as "the terminating null byte";
824 strings may be described as "null-terminated",
825 but avoid the use of "NUL-terminated".
827 For hyperlinks, use the
832 This produces proper hyperlinks that can be used in a web browser,
833 when rendering a page with, say:
835 BROWSER=firefox man -H pagename
836 .SS Use of e.g., i.e., etc., a.k.a., and similar
837 In general, the use of abbreviations such as "e.g.", "i.e.", "etc.",
838 "cf.", and "a.k.a." should be avoided,
839 in favor of suitable full wordings
840 ("for example", "that is", "compare to", "and so on", "also known as").
842 The only place where such abbreviations may be acceptable is in
844 parenthetical asides (e.g., like this one).
846 Always include periods in such abbreviations, as shown here.
847 In addition, "e.g." and "i.e." should always be followed by a comma.
849 The way to write an em-dash\(emthe glyph that appears
850 at either end of this subphrase\(emin *roff is with the macro "\e(em".
851 (On an ASCII terminal, an em-dash typically renders as two hyphens,
852 but in other typographical contexts it renders as a long dash.)
853 Em-dashes should be written
856 .SS Hyphenation of attributive compounds
857 Compound terms should be hyphenated when used attributively
858 (i.e., to qualify a following noun). Some examples:
861 command-line argument
862 floating-point number
865 wide-character string
866 .SS Hyphenation with multi, non, pre, re, sub, and so on
867 The general tendency in modern English is not to hyphenate
868 after prefixes such as "multi", "non", "pre", "re", "sub", and so on.
869 Manual pages should generally follow this rule when these prefixes are
870 used in natural English constructions with simple suffixes.
871 The following list gives some examples of the preferred forms:
894 Hyphens should be retained when the prefixes are used in nonstandard
895 English words, with trademarks, proper nouns, acronyms, or compound terms.
903 Finally, note that "re-create" and "recreate" are two different verbs,
904 and the former is probably what you want.
905 .SS Real minus character
906 Where a real minus character is required (e.g., for numbers such as \-1,
907 for man page cross references such as
909 or when writing options that have a leading dash, such as in
911 use the following form in the man page source:
915 This guideline applies also to code examples.
916 .SS Character constants
917 To produce single quotes that render well in both ASCII and UTF-8,
918 use the following form for character constants in the man page source:
924 is the quoted character.
925 This guideline applies also to character constants used in code examples.
926 .SS Example programs and shell sessions
927 Manual pages may include example programs demonstrating how to
928 use a system call or library function.
929 However, note the following:
931 Example programs should be written in C.
933 An example program is necessary and useful only if it demonstrates
934 something beyond what can easily be provided in a textual
935 description of the interface.
936 An example program that does nothing
937 other than call an interface usually serves little purpose.
939 Example programs should be fairly short (preferably less than 100 lines;
940 ideally less than 50 lines).
942 Example programs should do error checking after system calls and
943 library function calls.
945 Example programs should be complete, and compile without
946 warnings when compiled with \fIcc\ \-Wall\fP.
948 Where possible and appropriate, example programs should allow
949 experimentation, by varying their behavior based on inputs
950 (ideally from command-line arguments, or alternatively, via
951 input read by the program).
953 Example programs should be laid out according to Kernighan and
954 Ritchie style, with 4-space indents.
955 (Avoid the use of TAB characters in source code!)
956 The following command can be used to format your source code to
957 something close to the preferred style:
959 indent \-npro \-kr \-i4 \-ts4 \-sob \-l72 \-ss \-nut \-psl prog.c
961 For consistency, all example programs should terminate using either of:
966 Avoid using the following forms to terminate a program:
972 If there is extensive explanatory text before the
973 program source code, mark off the source code
974 with a subsection heading
975 .IR "Program source" ,
980 Always do this if the explanatory text includes a shell session log.
982 If you include a shell session log demonstrating the use of a program
983 or other system feature:
985 Place the session log above the source code listing
987 Indent the session log by four spaces.
989 Boldface the user input text,
990 to distinguish it from output produced by the system.
992 For some examples of what example programs should look like, see
997 For canonical examples of how man pages in the
999 package should look, see