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 2014-03-16 "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 as well as many of the pages that appear
44 in Sections 3, 4, 5, and 7 of the man pages on a Linux system.
45 The conventions described on this page may also be useful
46 for authors writing man pages for other projects.
47 .SS Sections of the manual pages
49 The manual Sections are traditionally defined as follows:
51 .B 1 Commands (Programs)
52 Those commands that can be executed by the user from within
56 Those functions which must be performed by the kernel.
63 .B 4 Special files (devices)
67 .B 5 File formats and conventions
70 and other human-readable files.
74 .B 7 Overview, conventions, and miscellaneous
75 Overviews of various topics, conventions and protocols,
76 character set standards, and miscellaneous other things.
78 .B 8 System management commands
81 many of which only root can execute.
83 .\" .B 9 Kernel routines
84 .\" This is an obsolete manual section.
85 .\" Once it was thought a good idea to document the Linux kernel here,
86 .\" but in fact very little has been documented, and the documentation
87 .\" that exists is outdated already.
88 .\" There are better sources of
89 .\" information for kernel developers.
91 New manual pages should be marked up using the
95 This choice is mainly for consistency: the vast majority of
96 existing Linux manual pages are marked up using these macros.
97 .SS Conventions for source file layout
98 Please limit source code line length to no more than about 75 characters
100 This helps avoid line-wrapping in some mail clients when patches are
103 New sentences should be started on new lines.
104 This makes it easier to see the effect of patches,
105 which often operate at the level of individual sentences.
107 The first command in a man page should be a
113 .I "title section date source manual"
120 The title of the man page, written in all caps (e.g.,
124 The section number in which the man page should be placed (e.g.,
128 The date of the last revision\(emremember to change this every time a
129 nontrivial change is made to the man page.
130 Dates should be written in the form YYYY-MM-DD.
133 The source of the command, function, or system call.
135 For those few \fIman-pages\fP pages in Sections 1 and 8,
136 probably you just want to write
139 For system calls, just write
141 (An earlier practice was to write the version number
142 of the kernel from which the manual page was being written/checked.
143 However, this was never done consistently, and so was
144 probably worse than including no version number.
145 Henceforth, avoid including a version number.)
147 For library calls that are part of glibc or one of the
148 other common GNU libraries, just use
149 .IR "GNU C Library" ", " GNU ,
152 For Section 4 pages, use
155 In cases of doubt, just write
156 .IR Linux ", or " GNU .
159 The title of the manual (e.g., for Section 2 and 3 pages in
160 the \fIman-pages\fP package, use
161 .IR "Linux Programmer's Manual" ).
163 .SS Sections within a manual page
164 The list below shows conventional or suggested sections.
165 Most manual pages should include at least the
168 Arrange a new manual page so that sections
169 are placed in the order shown in the list.
175 CONFIGURATION [Normally only in Section 4]
177 OPTIONS [Normally only in Sections 1, 8]
178 EXIT STATUS [Normally only in Sections 1, 8]
179 RETURN VALUE [Normally only in Sections 2, 3]
180 .\" May 07: Few current man pages have an ERROR HANDLING section,,,
182 ERRORS [Typically only in Sections 2, 3]
183 .\" May 07: Almost no current man pages have a USAGE section,,,
186 .\" May 07: Almost no current man pages have a SECURITY section,,,
190 VERSIONS [Normally only in Sections 2, 3]
191 ATTRIBUTES [Normally only in Sections 2, 3]
196 .\" AUTHORS sections are discouraged
197 .\" AUTHORS [Discouraged]
202 .IR "Where a traditional heading would apply" ", " "please use it" ;
203 this kind of consistency can make the information easier to understand.
204 If you must, you can create your own
205 headings if they make things easier to understand (this can
206 be especially useful for pages in Sections 4 and 5).
207 However, before doing this, consider whether you could use the
208 traditional headings, with some subsections (\fI.SS\fP) within
211 The following list elaborates on the contents of each of
215 The name of this manual page.
218 for important details of the line(s) that should follow the
219 \fB.SH NAME\fP command.
220 All words in this line (including the word immediately
221 following the "\\\-") should be in lowercase,
222 except where English or technical terminological convention
226 briefly describes the command or function's interface.
227 For commands, this shows the syntax of the command and its arguments
229 boldface is used for as-is text and italics are used to
230 indicate replaceable arguments.
231 Brackets ([]) surround optional arguments, vertical bars (|)
232 separate choices, and ellipses (\&...) can be repeated.
233 For functions, it shows any required data declarations or
235 directives, followed by the function declaration.
237 Where a feature test macro must be defined in order to obtain
238 the declaration of a function (or a variable) from a header file,
239 then the SYNOPSIS should indicate this, as described in
240 .BR feature_test_macros (7).
241 .\" FIXME . Say something here about compiler options
244 Configuration details for a device.
245 This section normally appears only in Section 4 pages.
248 gives an explanation of what the program, function, or format does.
249 Discuss how it interacts with files and standard input, and what it
250 produces on standard output or standard error.
251 Omit internals and implementation details unless they're critical for
252 understanding the interface.
253 Describe the usual case;
254 for information on command-line options of a program use the
257 .\" If there is some kind of input grammar or complex set of subcommands,
258 .\" consider describing them in a separate
260 .\" section (and just place an overview in the
264 When describing new behavior or new flags for
265 a system call or library function,
266 be careful to note the kernel or C library version
267 that introduced the change.
268 The preferred method of noting this information for flags is as part of a
270 list, in the following form (here, for a new system call flag):
273 .BR XYZ_FLAG " (since Linux 3.7)"
274 Description of flag...
277 Including version information is especially useful to users
278 who are constrained to using older kernel or C library versions
279 (which is typical in embedded systems, for example).
282 describes the command-line options accepted by a
283 program and how they change its behavior.
284 This section should appear only for Section 1 and 8 manual pages.
287 .\" describes the grammar of any sublanguage this implements.
290 lists the possible exit status values of a program and
291 the conditions that cause these values to be returned.
292 This section should appear only for Section 1 and 8 manual pages.
295 For Section 2 and 3 pages, this section gives a
296 list of the values the library routine will return to the caller
297 and the conditions that cause these values to be returned.
300 For Section 2 and 3 manual pages, this is a list of the
301 values that may be placed in
303 in the event of an error, along with information about the cause
305 .IR "The error list should be in alphabetical order" .
308 lists all environment variables that affect the program or function
309 and how they affect it.
312 lists the files the program or function uses, such as
313 configuration files, startup files,
314 and files the program directly operates on.
315 Give the full pathname of these files, and use the installation
316 process to modify the directory part to match user preferences.
317 For many programs, the default installation location is in
319 so your base manual page should use
322 .\" May 07: Almost no current man pages have a DIAGNOSTICS section;
323 .\" "RETURN VALUE" or "EXIT STATUS" is preferred.
326 .\" gives an overview of the most common error messages and how to
328 .\" You don't need to explain system error messages
329 .\" or fatal signals that can appear during execution of any program
330 .\" unless they're special in some way to the program.
332 .\" May 07: Almost no current man pages have a SECURITY section.
335 .\"discusses security issues and implications.
336 .\"Warn about configurations or environments that should be avoided,
337 .\"commands that may have security implications, and so on, especially
338 .\"if they aren't obvious.
339 .\"Discussing security in a separate section isn't necessary;
340 .\"if it's easier to understand, place security information in the
341 .\"other sections (such as the
346 .\" However, please include security information somewhere!
349 A summary of various attributes of the function(s) documented on this page,
350 broken into subsections.
351 The following subsections are defined:
355 .B "Multithreading (see pthreads(7))"
356 This subsection notes attributes relating to multithreaded applications:
359 Whether the function is thread-safe.
361 Whether the function is a cancellation point.
363 Whether the function is async-cancel-safe.
366 Details of these attributes can be found in
371 A brief summary of the Linux kernel or glibc versions where a
372 system call or library function appeared,
373 or changed significantly in its operation.
374 As a general rule, every new interface should
375 include a VERSIONS section in its manual page.
377 many existing manual pages don't include this information
378 (since there was no policy to do so when they were written).
379 Patches to remedy this are welcome,
380 but, from the perspective of programmers writing new code,
381 this information probably matters only in the case of kernel
382 interfaces that have been added in Linux 2.4 or later
383 (i.e., changes since kernel 2.2),
384 and library functions that have been added to glibc since version 2.1
385 (i.e., changes since glibc 2.0).
389 manual page also provides information about kernel versions
390 in which various system calls first appeared.
393 describes any standards or conventions that relate to the function
394 or command described by the manual page.
395 The preferred terms to use for the various standards are listed as
398 For a page in Section 2 or 3,
399 this section should note the POSIX.1
400 version(s) that the call conforms to,
401 and also whether the call is specified in C99.
402 (Don't worry too much about other standards like SUS, SUSv2, and XPG,
403 or the SVr4 and 4.xBSD implementation standards,
404 unless the call was specified in those standards,
405 but isn't in the current version of POSIX.1.)
409 If the call is not governed by any standards but commonly
410 exists on other systems, note them.
411 If the call is Linux-specific, note this.
413 If this section consists of just a list of standards
414 (which it commonly does),
415 terminate the list with a period (\(aq.\(aq).
418 provides miscellaneous notes.
419 For Section 2 and 3 man pages you may find it useful to include
420 subsections (\fBSS\fP) named \fILinux Notes\fP and \fIGlibc Notes\fP.
423 lists limitations, known defects or inconveniences,
424 and other questionable activities.
427 provides one or more examples describing how this function, file or
429 For details on writing example programs,
430 see \fIExample Programs\fP below.
433 lists authors of the documentation or program.
434 \fBUse of an AUTHORS section is strongly discouraged\fP.
435 Generally, it is better not to clutter every page with a list
436 of (over time potentially numerous) authors;
437 if you write or significantly amend a page,
438 add a copyright notice as a comment in the source file.
439 If you are the author of a device driver and want to include
440 an address for reporting bugs, place this under the BUGS section.
443 provides a comma-separated list of related man pages,
444 ordered by section number and
445 then alphabetically by name, possibly followed by
446 other related pages or documents.
447 Do not terminate this with a period.
449 Where the SEE ALSO list contains many long manual page names,
450 to improve the visual result of the output, it may be useful to employ the
452 (don't right justify)
457 Hyphenation of individual page names can be prevented
458 by preceding words with the string "\\%".
460 The following subsections describe the preferred style for the
463 For details not covered below, the Chicago Manual of Style
464 is usually a good source;
465 try also grepping for preexisting usage in the project source tree.
466 .SS Use of gender-neutral language
467 As far as possible, use gender-neutral language in the text of man
469 Use of "they" ("them", "themself", "their") as a gender-neutral singular
470 pronoun is acceptable.
473 For functions, the arguments are always specified using italics,
474 .IR "even in the SYNOPSIS section" ,
475 where the rest of the function is specified in bold:
477 .BI " int myfunction(int " argc ", char **" argv );
479 Variable names should, like argument names, be specified in italics.
481 Filenames (whether pathnames, or references to header files)
482 are always in italics (e.g.,
484 except in the SYNOPSIS section, where included files are in bold (e.g.,
485 .BR "#include <stdio.h>" ).
486 When referring to a standard header file include,
487 specify the header file surrounded by angle brackets,
488 in the usual C way (e.g.,
491 Special macros, which are usually in uppercase, are in bold (e.g.,
493 Exception: don't boldface NULL.
495 When enumerating a list of error codes, the codes are in bold (this list
500 Complete commands should, if long,
501 be written as an indented line on their own,
502 with a blank line before and after the command, for example
510 If the command is short, then it can be included inline in the text,
511 in italic format, for example,
512 .IR "man 7 man-pages" .
513 In this case, it may be worth using nonbreaking spaces
514 ("\e\ ") at suitable places in the command.
515 Command options should be written in italics (e.g.,
518 Expressions, if not written on a separate indented line, should
519 be specified in italics.
520 Again, the use of nonbreaking spaces may be appropriate
521 if the expression is inlined with normal text.
523 Any reference to the subject of the current manual page
524 should be written with the name in bold.
525 If the subject is a function (i.e., this is a Section 2 or 3 page),
526 then the name should be followed by a pair of parentheses
527 in Roman (normal) font.
530 man page, references to the subject of the page would be written as:
532 The preferred way to write this in the source file is:
538 (Using this format, rather than the use of "\\fB...\\fP()"
539 makes it easier to write tools that parse man page source files.)
541 Any reference to another man page
542 should be written with the name in bold,
544 followed by the section number,
545 formatted in Roman (normal) font, without any
546 separating spaces (e.g.,
548 The preferred way to write this in the source file is:
554 (Including the section number in cross references lets tools like
556 create properly hyperlinked pages.)
558 Control characters should be written in bold face,
559 with no quotes; for example,
562 Starting with release 2.59,
564 follows American spelling conventions
565 (previously, there was a random mix of British and American spellings);
566 please write all new pages and patches according to these conventions.
568 Aside from the well-known spelling differences,
569 there are a few other subtleties to watch for:
571 American English tends to use the forms "backward", "upward", "toward",
573 rather than the British forms "backwards", "upwards", "towards", and so on.
574 .SS BSD version numbers
575 The classical scheme for writing BSD version numbers is
579 is the version number (e.g., 4.2BSD).
583 In subsection ("SS") headings,
584 capitalize the first word in the heading, but otherwise use lowercase,
585 except where English usage (e.g., proper nouns) or programming
586 language requirements (e.g., identifier names) dictate otherwise.
589 .SS Unicode under Linux
591 .SS Indentation of structure definitions, shell session logs, and so on
592 When structure definitions, shell session logs, and so on are included
593 in running text, indent them by 4 spaces (i.e., a block enclosed by
598 The following table lists some preferred terms to use in man pages,
599 mainly to ensure consistency across pages.
604 Term Avoid using Notes
609 For the UNIX Epoch (00:00:00, 1 Jan 1970 UTC)
612 filesystem file system
615 lowercase lower case, lower-case
617 pseudoterminal pseudo-terminal
627 saved set-group-ID T{
635 set-group-ID set-GID, setgid
636 set-user-ID set-UID, setuid
647 uppercase upper case, upper-case
654 See also the discussion
655 .IR "Hyphenation of attributive compounds"
658 The following table lists some terms to avoid using in man pages,
659 along with some suggested alternatives,
660 mainly to ensure consistency across pages.
665 Avoid Use instead Notes
668 same for 8-bit, 16-bit, etc.
670 current process calling process T{
671 A common mistake made by kernel programmers when writing man pages
674 man page, manual page
676 minus infinity negative infinity
677 non-root unprivileged user
678 non-superuser unprivileged user
679 nonprivileged unprivileged
681 plus infinity positive infinity
688 Use the correct spelling and case for trademarks.
689 The following is a list of the correct spellings of various
690 relevant trademarks that are sometimes misspelled:
696 .SS NULL, NUL, null pointer, and null character
699 is a pointer that points to nothing,
700 and is normally indicated by the constant
706 a byte with the value 0, represented in C via the character constant
709 The preferred term for the pointer is "null pointer" or simply "NULL";
710 avoid writing "NULL pointer".
712 The preferred term for the byte is "null byte".
713 Avoid writing "NUL", since it is too easily confused with "NULL".
714 Avoid also the terms "zero byte" and "null character".
715 The byte that terminates a C string should be described
716 as "the terminating null byte";
717 strings may be described as "null-terminated",
718 but avoid the use of "NUL-terminated".
720 For hyperlinks, use the
725 This produces proper hyperlinks that can be used in a web browser,
726 when rendering a page with, say:
728 BROWSER=firefox man -H pagename
729 .SS Use of e.g., i.e., etc., a.k.a., and similar
730 In general, the use of abbreviations such as "e.g.", "i.e.", "etc.", "a.k.a."
731 should be avoided, in favor of suitable full wordings
732 ("for example", "that is", "and so on", "also known as").
734 The only place where such abbreviations may be acceptable is in
736 parenthetical asides (e.g., like this one).
738 Always include periods in such abbreviations, as shown here.
739 In addition, "e.g." and "i.e." should always be followed by a comma.
741 The way to write an em-dash\(emthe glyph that appears
742 at either end of this subphrase\(emin *roff is with the macro "\\(em".
743 (On an ASCII terminal, an em-dash typically renders as two hyphens,
744 but in other typographical contexts it renders as a long dash.)
745 Em-dashes should be written
748 .SS Hyphenation of attributive compounds
749 Compound terms should be hyphenated when used attributively
750 (i.e., to qualify a following noun). Some examples:
753 command-line argument
754 floating-point number
757 wide-character string
758 .SS Hyphenation with multi, non, pre, re, sub, and so on
759 The general tendency in modern English is not to hyphenate
760 after prefixes such as "multi", "non", "pre", "re", "sub", and so on.
761 Manual pages should generally follow this rule when these prefixes are
762 used in natural English constructions with simple suffixes.
763 The following list gives some examples of the preferred forms:
786 Hyphens should be retained when the prefixes are used in nonstandard
787 English words, with trademarks, proper nouns, acronyms, or compound terms.
795 Finally, note that "re-create" and "recreate" are two different verbs,
796 and the former is probably what you want.
797 .SS Real minus character
798 Where a real minus character is required (e.g., for numbers such as \-1,
799 or when writing options that have a leading dash, such as in
801 use the following form in the man page source:
805 This guideline applies also to code examples.
806 .SS Character constants
807 To produce single quotes that render well in both ASCII and UTF-8,
808 use the following form for character constants in the man page source:
814 is the quoted character.
815 This guideline applies also to character constants used in code examples.
816 .SS Example programs and shell sessions
817 Manual pages may include example programs demonstrating how to
818 use a system call or library function.
819 However, note the following:
821 Example programs should be written in C.
823 An example program is necessary and useful only if it demonstrates
824 something beyond what can easily be provided in a textual
825 description of the interface.
826 An example program that does nothing
827 other than call an interface usually serves little purpose.
829 Example programs should be fairly short (preferably less than 100 lines;
830 ideally less than 50 lines).
832 Example programs should do error checking after system calls and
833 library function calls.
835 Example programs should be complete, and compile without
836 warnings when compiled with \fIcc\ \-Wall\fP.
838 Where possible and appropriate, example programs should allow
839 experimentation, by varying their behavior based on inputs
840 (ideally from command-line arguments, or alternatively, via
841 input read by the program).
843 Example programs should be laid out according to Kernighan and
844 Ritchie style, with 4-space indents.
845 (Avoid the use of TAB characters in source code!)
847 For consistency, all example programs should terminate using either of:
852 Avoid using the following forms to terminate a program:
858 If there is extensive explanatory text before the
859 program source code, mark off the source code
860 with a subsection heading
861 .IR "Program source" ,
866 Always do this if the explanatory text includes a shell session log.
868 If you include a shell session log demonstrating the use of a program
869 or other system feature:
871 Place the session log above the source code listing
873 Indent the session log by four spaces.
875 Boldface the user input text,
876 to distinguish it from output produced by the system.
878 For some examples of what example programs should look like, see
883 For canonical examples of how man pages in the
885 package should look, see
897 This page is part of release 3.67 of the Linux
900 A description of the project,
901 information about reporting bugs,
902 and the latest version of this page,
904 \%http://www.kernel.org/doc/man\-pages/.