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 COPYRIGHT [Not used in man-pages]
206 .IR "Where a traditional heading would apply" ", " "please use it" ;
207 this kind of consistency can make the information easier to understand.
208 If you must, you can create your own
209 headings if they make things easier to understand (this can
210 be especially useful for pages in Sections 4 and 5).
211 However, before doing this, consider whether you could use the
212 traditional headings, with some subsections (\fI.SS\fP) within
215 The following list elaborates on the contents of each of
219 The name of this manual page.
223 for important details of the line(s) that should follow the
224 \fB.SH NAME\fP command.
225 All words in this line (including the word immediately
226 following the "\e\-") should be in lowercase,
227 except where English or technical terminological convention
231 A brief summary of the command or function's interface.
233 For commands, this shows the syntax of the command and its arguments
235 boldface is used for as-is text and italics are used to
236 indicate replaceable arguments.
237 Brackets ([]) surround optional arguments, vertical bars (|)
238 separate choices, and ellipses (\&...) can be repeated.
239 For functions, it shows any required data declarations or
241 directives, followed by the function declaration.
243 Where a feature test macro must be defined in order to obtain
244 the declaration of a function (or a variable) from a header file,
245 then the SYNOPSIS should indicate this, as described in
246 .BR feature_test_macros (7).
247 .\" FIXME . Say something here about compiler options
250 Configuration details for a device.
252 This section normally appears only in Section 4 pages.
255 An explanation of what the program, function, or format does.
257 Discuss how it interacts with files and standard input, and what it
258 produces on standard output or standard error.
259 Omit internals and implementation details unless they're critical for
260 understanding the interface.
261 Describe the usual case;
262 for information on command-line options of a program use the
265 .\" If there is some kind of input grammar or complex set of subcommands,
266 .\" consider describing them in a separate
268 .\" section (and just place an overview in the
272 When describing new behavior or new flags for
273 a system call or library function,
274 be careful to note the kernel or C library version
275 that introduced the change.
276 The preferred method of noting this information for flags is as part of a
278 list, in the following form (here, for a new system call flag):
281 .BR XYZ_FLAG " (since Linux 3.7)"
282 Description of flag...
285 Including version information is especially useful to users
286 who are constrained to using older kernel or C library versions
287 (which is typical in embedded systems, for example).
290 A description of the command-line options accepted by a
291 program and how they change its behavior.
293 This section should appear only for Section 1 and 8 manual pages.
296 .\" describes the grammar of any sublanguage this implements.
299 A list of the possible exit status values of a program and
300 the conditions that cause these values to be returned.
302 This section should appear only for Section 1 and 8 manual pages.
305 For Section 2 and 3 pages, this section gives a
306 list of the values the library routine will return to the caller
307 and the conditions that cause these values to be returned.
310 For Section 2 and 3 manual pages, this is a list of the
311 values that may be placed in
313 in the event of an error, along with information about the cause
316 Where several different conditions produce the same error,
317 the preferred approach is to create separate list entries
318 (with duplicate error names) for each of the conditions.
319 This makes the separate conditions clear, may make the list easier to read,
320 and allows metainformation
321 (e.g., kernel version number where the condition first became applicable)
322 to be more easily marked for each condition.
324 .IR "The error list should be in alphabetical order" .
327 A list of all environment variables that affect the program or function
328 and how they affect it.
331 A list of the files the program or function uses, such as
332 configuration files, startup files,
333 and files the program directly operates on.
335 Give the full pathname of these files, and use the installation
336 process to modify the directory part to match user preferences.
337 For many programs, the default installation location is in
339 so your base manual page should use
342 .\" May 07: Almost no current man pages have a DIAGNOSTICS section;
343 .\" "RETURN VALUE" or "EXIT STATUS" is preferred.
346 .\" gives an overview of the most common error messages and how to
348 .\" You don't need to explain system error messages
349 .\" or fatal signals that can appear during execution of any program
350 .\" unless they're special in some way to the program.
352 .\" May 07: Almost no current man pages have a SECURITY section.
355 .\"discusses security issues and implications.
356 .\"Warn about configurations or environments that should be avoided,
357 .\"commands that may have security implications, and so on, especially
358 .\"if they aren't obvious.
359 .\"Discussing security in a separate section isn't necessary;
360 .\"if it's easier to understand, place security information in the
361 .\"other sections (such as the
366 .\" However, please include security information somewhere!
369 A summary of various attributes of the function(s) documented on this page.
375 A brief summary of the Linux kernel or glibc versions where a
376 system call or library function appeared,
377 or changed significantly in its operation.
379 As a general rule, every new interface should
380 include a VERSIONS section in its manual page.
382 many existing manual pages don't include this information
383 (since there was no policy to do so when they were written).
384 Patches to remedy this are welcome,
385 but, from the perspective of programmers writing new code,
386 this information probably matters only in the case of kernel
387 interfaces that have been added in Linux 2.4 or later
388 (i.e., changes since kernel 2.2),
389 and library functions that have been added to glibc since version 2.1
390 (i.e., changes since glibc 2.0).
394 manual page also provides information about kernel versions
395 in which various system calls first appeared.
398 A description of any standards or conventions that relate to the function
399 or command described by the manual page.
401 The preferred terms to use for the various standards are listed as
405 For a page in Section 2 or 3,
406 this section should note the POSIX.1
407 version(s) that the call conforms to,
408 and also whether the call is specified in C99.
409 (Don't worry too much about other standards like SUS, SUSv2, and XPG,
410 or the SVr4 and 4.xBSD implementation standards,
411 unless the call was specified in those standards,
412 but isn't in the current version of POSIX.1.)
414 If the call is not governed by any standards but commonly
415 exists on other systems, note them.
416 If the call is Linux-specific, note this.
418 If this section consists of just a list of standards
419 (which it commonly does),
420 terminate the list with a period (\(aq.\(aq).
425 For Section 2 and 3 man pages you may find it useful to include
426 subsections (\fBSS\fP) named \fILinux Notes\fP and \fIGlibc Notes\fP.
428 In Section 2, use the heading
429 .I "C library/kernel differences"
430 to mark off notes that describe the differences (if any) between
431 the C library wrapper function for a system call and
432 the raw system call interface provided by the kernel.
435 A list of limitations, known defects or inconveniences,
436 and other questionable activities.
439 One or more examples demonstrating how this function, file or
442 For details on writing example programs,
443 see \fIExample programs\fP below.
446 A list of authors of the documentation or program.
448 \fBUse of an AUTHORS section is strongly discouraged\fP.
449 Generally, it is better not to clutter every page with a list
450 of (over time potentially numerous) authors;
451 if you write or significantly amend a page,
452 add a copyright notice as a comment in the source file.
453 If you are the author of a device driver and want to include
454 an address for reporting bugs, place this under the BUGS section.
459 project doesn't use a COPYRIGHT section in manual pages.
460 Copyright information is instead maintained in the page source.
461 In pages where this section is present,
462 it is recommended to place it near the foot of the page, just above SEE ALSO.
465 A comma-separated list of related man pages, possibly followed by
466 other related pages or documents.
468 The list should be ordered by section number and
469 then alphabetically by name.
470 Do not terminate this list with a period.
472 Where the SEE ALSO list contains many long manual page names,
473 to improve the visual result of the output, it may be useful to employ the
475 (don't right justify)
480 Hyphenation of individual page names can be prevented
481 by preceding words with the string "\e%".
483 Given the distributed, autonomous nature of FOSS projects
484 and their documentation, it is sometimes necessary\(emand in many cases
485 desirable\(emthat the SEE ALSO section includes references to
486 manual pages provided by other projects.
488 The following subsections describe the preferred style for the
491 For details not covered below, the Chicago Manual of Style
492 is usually a good source;
493 try also grepping for preexisting usage in the project source tree.
494 .SS Use of gender-neutral language
495 As far as possible, use gender-neutral language in the text of man
497 Use of "they" ("them", "themself", "their") as a gender-neutral singular
498 pronoun is acceptable.
500 .SS Formatting conventions for manual pages describing commands
502 For manual pages that describe a command (typically in Sections 1 and 8),
503 the arguments are always specified using italics,
504 .IR "even in the SYNOPSIS section" .
506 The name of the command, and its options, should
507 always be formatted in bold.
509 .SS Formatting conventions for manual pages describing functions
510 For manual pages that describe functions (typically in Sections 2 and 3),
511 the arguments are always specified using italics,
512 .IR "even in the SYNOPSIS section" ,
513 where the rest of the function is specified in bold:
515 .BI " int myfunction(int " argc ", char **" argv );
517 Variable names should, like argument names, be specified in italics.
519 Any reference to the subject of the current manual page
520 should be written with the name in bold followed by
521 a pair of parentheses in Roman (normal) font.
524 man page, references to the subject of the page would be written as:
526 The preferred way to write this in the source file is:
532 (Using this format, rather than the use of "\efB...\efP()"
533 makes it easier to write tools that parse man page source files.)
535 .SS Use semantic newlines
536 In the source of a manual page,
537 new sentences should be started on new lines,
538 and long sentences should split into lines at clause breaks
539 (commas, semicolons, colons, and so on).
540 This convention, sometimes known as "semantic newlines",
541 makes it easier to see the effect of patches,
542 which often operate at the level of individual sentences or sentence clauses.
544 .SS Formatting conventions (general)
546 Paragraphs should be separated by suitable markers (usually either
552 separate paragraphs using blank lines, as this results in poor rendering
553 in some output formats (such as PostScript and PDF).
555 Filenames (whether pathnames, or references to header files)
556 are always in italics (e.g.,
558 except in the SYNOPSIS section, where included files are in bold (e.g.,
559 .BR "#include <stdio.h>" ).
560 When referring to a standard header file include,
561 specify the header file surrounded by angle brackets,
562 in the usual C way (e.g.,
565 Special macros, which are usually in uppercase, are in bold (e.g.,
567 Exception: don't boldface NULL.
569 When enumerating a list of error codes, the codes are in bold (this list
574 Complete commands should, if long,
575 be written as an indented line on their own,
576 with a blank line before and after the command, for example
584 If the command is short, then it can be included inline in the text,
585 in italic format, for example,
586 .IR "man 7 man-pages" .
587 In this case, it may be worth using nonbreaking spaces
588 ("\e\ ") at suitable places in the command.
589 Command options should be written in italics (e.g.,
592 Expressions, if not written on a separate indented line, should
593 be specified in italics.
594 Again, the use of nonbreaking spaces may be appropriate
595 if the expression is inlined with normal text.
597 When showing example shell sessions, user input should be formatted in bold, for example
602 Thu Jul 7 13:01:27 CEST 2016
607 Any reference to another man page
608 should be written with the name in bold,
610 followed by the section number,
611 formatted in Roman (normal) font, without any
612 separating spaces (e.g.,
614 The preferred way to write this in the source file is:
620 (Including the section number in cross references lets tools like
622 create properly hyperlinked pages.)
624 Control characters should be written in bold face,
625 with no quotes; for example,
628 Starting with release 2.59,
630 follows American spelling conventions
631 (previously, there was a random mix of British and American spellings);
632 please write all new pages and patches according to these conventions.
634 Aside from the well-known spelling differences,
635 there are a few other subtleties to watch for:
637 American English tends to use the forms "backward", "upward", "toward",
639 rather than the British forms "backwards", "upwards", "towards", and so on.
640 .SS BSD version numbers
641 The classical scheme for writing BSD version numbers is
645 is the version number (e.g., 4.2BSD).
649 In subsection ("SS") headings,
650 capitalize the first word in the heading, but otherwise use lowercase,
651 except where English usage (e.g., proper nouns) or programming
652 language requirements (e.g., identifier names) dictate otherwise.
656 .SS Unicode under Linux
659 .SS Indentation of structure definitions, shell session logs, and so on
660 When structure definitions, shell session logs, and so on are included
661 in running text, indent them by 4 spaces (i.e., a block enclosed by
665 format them using the
669 macros, and surround them with suitable paragraph markers (either
681 main(int argc, char *argv[])
691 The following table lists some preferred terms to use in man pages,
692 mainly to ensure consistency across pages.
697 Term Avoid using Notes
702 For the UNIX Epoch (00:00:00, 1 Jan 1970 UTC)
705 filesystem file system
708 lowercase lower case, lower-case
711 pseudoterminal pseudo-terminal
721 saved set-group-ID T{
729 set-group-ID set-GID, setgid
730 set-user-ID set-UID, setuid
741 uppercase upper case, upper-case
746 Except if referring to result of "uname\ \-m" or similar
751 See also the discussion
752 .IR "Hyphenation of attributive compounds"
755 The following table lists some terms to avoid using in man pages,
756 along with some suggested alternatives,
757 mainly to ensure consistency across pages.
762 Avoid Use instead Notes
765 same for 8-bit, 16-bit, etc.
767 current process calling process T{
768 A common mistake made by kernel programmers when writing man pages
771 man page, manual page
773 minus infinity negative infinity
774 non-root unprivileged user
775 non-superuser unprivileged user
776 nonprivileged unprivileged
778 plus infinity positive infinity
785 Use the correct spelling and case for trademarks.
786 The following is a list of the correct spellings of various
787 relevant trademarks that are sometimes misspelled:
793 .SS NULL, NUL, null pointer, and null character
796 is a pointer that points to nothing,
797 and is normally indicated by the constant
803 a byte with the value 0, represented in C via the character constant
806 The preferred term for the pointer is "null pointer" or simply "NULL";
807 avoid writing "NULL pointer".
809 The preferred term for the byte is "null byte".
810 Avoid writing "NUL", since it is too easily confused with "NULL".
811 Avoid also the terms "zero byte" and "null character".
812 The byte that terminates a C string should be described
813 as "the terminating null byte";
814 strings may be described as "null-terminated",
815 but avoid the use of "NUL-terminated".
817 For hyperlinks, use the
822 This produces proper hyperlinks that can be used in a web browser,
823 when rendering a page with, say:
825 BROWSER=firefox man -H pagename
826 .SS Use of e.g., i.e., etc., a.k.a., and similar
827 In general, the use of abbreviations such as "e.g.", "i.e.", "etc.",
828 "cf.", and "a.k.a." should be avoided,
829 in favor of suitable full wordings
830 ("for example", "that is", "compare to", "and so on", "also known as").
832 The only place where such abbreviations may be acceptable is in
834 parenthetical asides (e.g., like this one).
836 Always include periods in such abbreviations, as shown here.
837 In addition, "e.g." and "i.e." should always be followed by a comma.
839 The way to write an em-dash\(emthe glyph that appears
840 at either end of this subphrase\(emin *roff is with the macro "\e(em".
841 (On an ASCII terminal, an em-dash typically renders as two hyphens,
842 but in other typographical contexts it renders as a long dash.)
843 Em-dashes should be written
846 .SS Hyphenation of attributive compounds
847 Compound terms should be hyphenated when used attributively
848 (i.e., to qualify a following noun). Some examples:
851 command-line argument
852 floating-point number
855 wide-character string
856 .SS Hyphenation with multi, non, pre, re, sub, and so on
857 The general tendency in modern English is not to hyphenate
858 after prefixes such as "multi", "non", "pre", "re", "sub", and so on.
859 Manual pages should generally follow this rule when these prefixes are
860 used in natural English constructions with simple suffixes.
861 The following list gives some examples of the preferred forms:
884 Hyphens should be retained when the prefixes are used in nonstandard
885 English words, with trademarks, proper nouns, acronyms, or compound terms.
893 Finally, note that "re-create" and "recreate" are two different verbs,
894 and the former is probably what you want.
895 .SS Real minus character
896 Where a real minus character is required (e.g., for numbers such as \-1,
897 for man page cross references such as
899 or when writing options that have a leading dash, such as in
901 use the following form in the man page source:
905 This guideline applies also to code examples.
906 .SS Character constants
907 To produce single quotes that render well in both ASCII and UTF-8,
908 use the following form for character constants in the man page source:
914 is the quoted character.
915 This guideline applies also to character constants used in code examples.
916 .SS Example programs and shell sessions
917 Manual pages may include example programs demonstrating how to
918 use a system call or library function.
919 However, note the following:
921 Example programs should be written in C.
923 An example program is necessary and useful only if it demonstrates
924 something beyond what can easily be provided in a textual
925 description of the interface.
926 An example program that does nothing
927 other than call an interface usually serves little purpose.
929 Example programs should be fairly short (preferably less than 100 lines;
930 ideally less than 50 lines).
932 Example programs should do error checking after system calls and
933 library function calls.
935 Example programs should be complete, and compile without
936 warnings when compiled with \fIcc\ \-Wall\fP.
938 Where possible and appropriate, example programs should allow
939 experimentation, by varying their behavior based on inputs
940 (ideally from command-line arguments, or alternatively, via
941 input read by the program).
943 Example programs should be laid out according to Kernighan and
944 Ritchie style, with 4-space indents.
945 (Avoid the use of TAB characters in source code!)
946 The following command can be used to format your source code to
947 something close to the preferred style:
949 indent \-npro \-kr \-i4 \-ts4 \-sob \-l72 \-ss \-nut \-psl prog.c
951 For consistency, all example programs should terminate using either of:
956 Avoid using the following forms to terminate a program:
962 If there is extensive explanatory text before the
963 program source code, mark off the source code
964 with a subsection heading
965 .IR "Program source" ,
970 Always do this if the explanatory text includes a shell session log.
972 If you include a shell session log demonstrating the use of a program
973 or other system feature:
975 Place the session log above the source code listing
977 Indent the session log by four spaces.
979 Boldface the user input text,
980 to distinguish it from output produced by the system.
982 For some examples of what example programs should look like, see
987 For canonical examples of how man pages in the
989 package should look, see