1 .\" (C) Copyright 1992-1999 Rickard E. Faith and David A. Wheeler
2 .\" (faith@cs.unc.edu and dwheeler@ida.org)
4 .\" Permission is granted to make and distribute verbatim copies of this
5 .\" manual provided the copyright notice and this permission notice are
6 .\" preserved on all copies.
8 .\" Permission is granted to copy and distribute modified versions of this
9 .\" manual under the conditions for verbatim copying, provided that the
10 .\" entire resulting derived work is distributed under the terms of a
11 .\" permission notice identical to this one.
13 .\" Since the Linux kernel and libraries are constantly changing, this
14 .\" manual page may be incorrect or out-of-date. The author(s) assume no
15 .\" responsibility for errors or omissions, or for damages resulting from
16 .\" the use of the information contained herein. The author(s) may not
17 .\" have taken the same level of care in the production of this manual,
18 .\" which is licensed free of charge, as they might when working
21 .\" Formatted or processed versions of this manual, if unaccompanied by
22 .\" the source, must acknowledge the copyright and authors of this work.
24 .\" Modified Sun Jul 25 11:06:05 1993 by Rik Faith (faith@cs.unc.edu)
25 .\" Modified Sat Jun 8 00:39:52 1996 by aeb
26 .\" Modified Wed Jun 16 23:00:00 1999 by David A. Wheeler (dwheeler@ida.org)
27 .\" Modified Thu Jul 15 12:43:28 1999 by aeb
28 .\" FIXME split this page into two parts: man.7 describing the macros
29 .\" and manpage.7 describing the Linux man page conventions]
30 .\" Modified Sun Jan 6 18:26:25 2002 by Martin Schulze <joey@infodrom.org>
31 .\" Modified Tue Jul 27 20:12:02 2004 by Colin Watson <cjwatson@debian.org>
33 .\" FIXME add a reference to one or two canonical man pages, which
34 .\" can serve as examples of how things should be done.
35 .TH MAN 7 2007-05-17 "Linux" "Linux Programmer's Manual"
37 man \- macros to format man pages
39 .B groff \-Tascii \-man
51 This manual page explains the
53 macro package (often called the
55 macro package) and related conventions for creating manual (man) pages.
56 This macro package should be used by developers when
57 writing or porting man pages for Linux.
58 It is fairly compatible with other
59 versions of this macro package, so porting man pages should not be a major
60 problem (exceptions include the NET-2 BSD release, which uses a totally
61 different macro package called mdoc; see
64 Note that NET-2 BSD mdoc man pages can be used with
66 simply by specifying the
73 option is, however, recommended, since this will automatically detect which
74 macro package is in use.
76 The first command in a man page (after comment lines,
77 that is, lines that start with \fB.\\"\fP) should be
81 .IR "title section date source manual" ,
88 The title of the man page, wrtten in all caps (e.g.,
92 The section number in which the man page should be placed (e.g.,
96 The date of the last revision\(emremember to change this every time a
97 change is made to the man page, since this is the most general way of doing
99 Dates should be written in the form YYYY-MM-DD.
102 The source of the command, function, or system call.
104 For those few pages in Sections 1 and 8, probably you just want to write
107 For system calls, just write
109 (An earlier practice was to write the version number
110 of the kernel from which the manual page was being written/checked.
111 However, this was never done consistently, and so was
112 probably worse than including no version number.
113 Henceforth, avoid including a version number.)
115 For library calls that are part of glibc or one of the
116 other common GNU libraries, just use
117 .IR "GNU C Library" ", " GNU ,
120 For section 4 pages, use
123 In cases of doubt, just write
124 .IR Linux ", or " GNU .
127 The title of the manual (e.g., for Section 2 and 3 pages in
128 the \fIman-pages\fP package, use
129 .IR "Linux Programmer's Manual" ).
132 Note that BSD mdoc-formatted pages begin with the
138 The manual sections are traditionally defined as follows:
141 .B 1 Commands (Programs)
142 Those commands that can be executed by the user from within
146 Those functions which must be performed by the kernel.
153 .B 4 Special files (devices)
157 .B 5 File formats and conventions
160 and other human-readable files.
164 .B 7 Conventions and miscellaneous
165 Overviews of various topics, conventions and protocols,
166 character set standards, and miscellaneous other things.
168 .B 8 System management commands
171 many of which only root can execute.
173 .\" .B 9 Kernel routines
174 .\" This is an obsolete manual section.
175 .\" Once it was thought a good idea to document the Linux kernel here,
176 .\" but in fact very little has been documented, and the documentation
177 .\" that exists is outdated already.
178 .\" There are better sources of
179 .\" information for kernel developers.
182 Sections are started with
184 followed by the heading name.
185 .\" The following doesn't seem to be required (see Debian bug 411303),
186 .\" If the name contains spaces and appears
187 .\" on the same line as
189 .\" then place the heading in double quotes.
190 The list below shows conventional or suggested sections.
191 Most manual pages should include at least the
194 Please try to arrange a new manual page so that sections
195 are placed in approximately the order shown in the list.
202 OPTIONS [Normally only in sections 1, 8]
205 VERSIONS [Normally only in sections 2, 3]
206 RETURN VALUE [Normally only in sections 2, 3]
207 EXIT STATUS [Normally only in sections 1, 8]
208 .\" May 07: Few current man pages have an ERROR HANDLING section,,,
210 ERRORS [Typically only in sections 2, 3]
211 .\" May 07: Almost no current man pages have a USAGE section,,,
214 .\" May 07: Almost no current man pages have a SECURITY section,,,
219 .\" AUTHOR sections are discouraged
226 .IR "Where a traditional heading would apply" ", " "please use it" ;
227 this kind of consistency can make the information easier to understand.
228 If you must, you can create your own
229 headings if they make things easier to understand (this can
230 be especially useful for pages in sections 4 and 5).
231 However, before doing this, consider whether you could use the
232 traditional headings, with some subsections (\fI.SS\fP) within
235 The only mandatory heading is NAME, which should be the first section and
236 be followed on the next line by a one line description of the program:
241 chess \\- the game of chess
244 It is extremely important that this format is followed, and that there is a
245 backslash before the single dash which follows the command name.
246 This syntax is used by the
248 program to create a database of short command descriptions for the
254 Some other traditional sections have the following contents:
257 briefly describes the command or function's interface.
258 For commands, this shows the syntax of the command and its arguments
260 boldface is used for as-is text and italics are used to indicate replaceable
262 Brackets ([]) surround optional arguments, vertical bars (|)
263 separate choices, and ellipses (\&...) can be repeated.
264 For functions, it shows any required data declarations or
266 directives, followed by the function declaration.
269 gives an explanation of what the program, function, or format does.
270 Discuss how it interacts with files and standard input, and what it
271 produces on standard output or standard error.
272 Omit internals and implementation details unless they're critical for
273 understanding the interface.
274 Describe the usual case;
275 for information on command-line options of a program use the
278 .\" If there is some kind of input grammar or complex set of subcommands,
279 .\" consider describing them in a separate
281 .\" section (and just place an overview in the
287 list of the values the library routine will return to the caller
288 and the conditions that cause these values to be returned.
291 lists the possible exit status values of a program and
292 the conditions that cause these values to be returned.
293 This section should only appear for Section 1 and 8 manual pages.
296 describes the command-line options accepted by a
297 program and how they change its behavior.
298 This section should only appear for Section 1 and 8 manual pages.
301 .\" describes the grammar of any sublanguage this implements.
302 .\" FIXME document VERSIONS
303 .\" FIXME document other common Section Heading types
304 .\" FIXME make a clear statement about the order of Sections
307 provides one or more examples describing how this function, file or
311 lists the files the program or function uses, such as
312 configuration files, startup files,
313 and files the program directly operates on.
314 Give the full pathname of these files, and use the installation
315 process to modify the directory part to match user preferences.
316 For many programs, the default installation location is in
318 so your base manual page should use
323 lists all environment variables that affect the program or function
324 and how they affect it.
325 .\" May 07: Almost no current man pages have a DIAGNOSTICS section;
326 .\" "RETURN VALUE" or "EXIT STATUS" is preferred.
329 .\" gives an overview of the most common error messages and how to
331 .\" You don't need to explain system error messages
332 .\" or fatal signals that can appear during execution of any program
333 .\" unless they're special in some way to the program.
335 .\" May 07: Almost no current man pages have a SECURITY section.
338 .\"discusses security issues and implications.
339 .\"Warn about configurations or environments that should be avoided,
340 .\"commands that may have security implications, and so on, especially
341 .\"if they aren't obvious.
342 .\"Discussing security in a separate section isn't necessary;
343 .\"if it's easier to understand, place security information in the
344 .\"other sections (such as the
349 .\" However, please include security information somewhere!
352 A brif summary of the Linux kernel or glibc versions where a
353 system call or library function appeared,
354 or changed significantly in its operation.
357 describes any standards or conventions this implements.
360 provides miscellaneous notes.
361 .\" FIXME -- mention .SS Linux Notes and .SS Glibc Notes?
364 lists limitations, known defects or inconveniences,
365 and other questionable activities.
368 lists authors of the documentation or program so you can mail in bug
370 .IR "Use of an AUTHOR section is discouraged".
371 (One exception is section 4 pages that list the authors of
372 device drivers, to whom software bugs should be sent.)
373 Generally, it is better not to clutter every page with a list
374 of (over time potentially numerous) authors;
375 if you write or significantly amend a page,
376 add a copyright notice as a comment in the source file.
379 lists related man pages in alphabetical order, possibly followed by
380 other related pages or documents.
381 Conventionally this is the last section.
383 Although there are many arbitrary conventions for man pages in the UNIX
384 world, the existence of several hundred Linux-specific man pages defines our
387 For functions, the arguments are always specified using italics,
388 .IR "even in the SYNOPSIS section" ,
389 where the rest of the function is specified in bold:
392 .BI " int myfunction(int " argc ", char **" argv );
395 Filenames are always in italics (e.g.,
396 .IR "/usr/include/stdio.h" ),
397 except in the SYNOPSIS section, where included files are in bold (e.g.,
398 .BR "#include <stdio.h>" ).
400 Special macros, which are usually in upper case, are in bold (e.g.,
403 When enumerating a list of error codes, the codes are in bold (this list
408 Any reference to the subject of the current manual page
409 should be written with the name in bold,
410 followed by a pair of parentheses in Roman (normal) font,
413 The preferred way to write this in the source file is:
419 (Using this format, rather than the use of "\\fB...\\fP()"
420 makes it easier to write tools that parse man page source files.)
422 Any reference to another man page
423 should be written with the name in bold,
424 \fIalways\fP followed by the section number,
425 formatted in Roman (normal) font, without any
426 separating spaces (e.g.,
428 The preferred way to write this in the source file is:
434 (Including the section number in cross references lets tools like
436 create properly hyperlinked pages.)
438 The commands to select the type face are:
444 Bold alternating with italics
445 (especially useful for function specifications)
448 Bold alternating with Roman
449 (especially useful for referring to other
456 Italics alternating with bold
459 Italics alternating with Roman
462 Roman alternating with bold
465 Roman alternating with italics
468 Small alternating with bold
471 Small (useful for acronyms)
473 Traditionally, each command can have up to six arguments, but the GNU
474 implementation removes this limitation (you might still want to limit
475 yourself to 6 arguments for portability's sake).
476 Arguments are delimited by spaces.
477 Double quotes can be used to specify an argument which contains spaces.
478 All of the arguments will be printed next to each other without
479 intervening spaces, so that the
481 command can be used to specify a word in bold followed by a mark of
482 punctuation in Roman.
483 If no arguments are given, the command is applied to the following line
485 .SS "Other Macros and Strings"
487 Below are other relevant macros and predefined strings.
488 Unless noted otherwise, all macros
489 cause a break (end the current line of text).
490 Many of these macros set or use the "prevailing indent."
491 The "prevailing indent" value is set by any macro with the parameter
496 in which case the current prevailing indent will be used.
497 As a result, successive indented paragraphs can use the same indent without
498 re-specifying the indent value.
499 A normal (non-indented) paragraph resets the prevailing indent value
500 to its default value (0.5 inches).
501 By default a given indent is measured in ens;
502 try to use ens or ems as units for
503 indents, since these will automatically adjust to font size changes.
504 The other key macro definitions are:
505 .SS "Normal Paragraphs"
510 (begin a new paragraph).
515 (begin a new paragraph).
518 Begin a new paragraph and reset prevailing indent.
519 .SS "Relative Margin Indent"
522 Start relative margin indent: moves the left margin
526 is omitted, the prevailing indent value is used).
527 A new prevailing indent is set to 0.5 inches.
528 As a result, all following paragraph(s) will be
529 indented until the corresponding
533 End relative margin indent and
534 restores the previous value of the prevailing indent.
535 .SS "Indented Paragraph Macros"
538 Begin paragraph with a hanging indent
539 (the first line of the paragraph is at the left margin of
540 normal paragraphs, and the rest of the paragraph's lines are indented).
543 Indented paragraph with optional hanging tag.
546 is omitted, the entire following paragraph is indented by
550 is provided, it is hung at the left margin
551 before the following indented paragraph
554 except the tag is included with the command instead of being on the
556 If the tag is too long, the text after the tag will be moved down to the
557 next line (text will not be lost or garbled).
558 For bulleted lists, use this macro with \e(bu (bullet) or \e(em (em dash)
559 as the tag, and for numbered lists, use the number or letter followed by
561 this simplifies translation to other formats.
564 Begin paragraph with hanging tag.
565 The tag is given on the next line, but
566 its results are like those of the
569 .SS "Hypertext Link Macros"
570 (Feature supported with
573 In order to use hypertext link macros, it is necessary to load the
580 .BI \&.URL " url link trailer"
581 Inserts a hypertext link to the URI (URL)
585 as the text of the link.
588 will be printed immediately afterwards.
589 When generating HTML this should translate into the HTML command
590 \fB<A HREF="\fP\fIurl\fP\fB">\fIlink\fP\fB</A>\fP\fItrailer\fP.
591 .\" The following is a kludge to get a paragraph into the listing.
594 This and other related macros are new, and
595 many tools won't do anything with them, but
596 since many tools (including troff) will simply ignore undefined macros
597 (or at worst insert their text) these are safe to insert.
598 .\" The following is a kludge to get a paragraph into the listing.
601 It can be useful to define your own
603 macro in manual pages for the benefit of those viewing it with a roff
606 That way, the URL, link text, and trailer text (if any) are still visible.
607 .\" The following is a kludge to get a paragraph into the listing.
614 \\\\$2 \\(laURL: \\\\$1 \\(ra\\\\$3
618 \&.if \\n[.g] .mso www.tmac
623 .I (later in the page)
625 This software comes from the
627 \&.URL "http://www.gnu.org/" "GNU Project" " of the"
629 \&.URL "http://www.fsf.org/" "Free Software Foundation" .
631 .\" The following is a kludge to get a paragraph into the listing.
638 macro package's definition of the URL macro will supersede the locally
641 A number of other link macros are available.
645 .SS "Miscellaneous Macros"
648 Reset tabs to default tab values (every 0.5 inches);
649 does not cause a break.
652 Set inter-paragraph vertical distance to d
653 (if omitted, d=0.4v);
654 does not cause a break.
661 but used for a subsection inside a section).
662 .SS "Predefined Strings"
665 package has the following predefined strings:
667 Registration Symbol: \*R
669 Change to default font size
671 Trademark Symbol: \*(Tm
673 Left angled doublequote: \*(lq
675 Right angled doublequote: \*(rq
679 is a troff macro package, in reality a large number of other tools
680 process man page files that don't implement all of troff's abilities.
681 Thus, it's best to avoid some of troff's more exotic abilities where possible
682 to permit these other tools to work correctly.
683 Avoid using the various troff preprocessors
684 (if you must, go ahead and use
690 commands instead for two-column tables).
691 Avoid using computations; most other tools can't process them.
692 Use simple commands that are easy to translate to other formats.
693 The following troff macros are believed to be safe (though in many cases
694 they will be ignored by translators):
721 You may also use many troff escape sequences (those sequences beginning
723 When you need to include the backslash character as normal text,
725 Other sequences you may use, where x or xx are any characters and N
726 is any digit, include:
742 Avoid using the escape sequences for drawing graphics.
744 Do not use the optional parameter for
747 Use only positive values for
752 with the same name as a macro in this or the
753 mdoc macro package with a different meaning; it's likely that
754 such redefinitions will be ignored.
755 Every positive indent
757 should be paired with a matching negative indent
758 (although you should be using the
765 should only have 't' or 'n' as the condition.
768 that can be ignored should be used.
771 and the \fB\ef\fP escape sequence)
772 should only have the values 1, 2, 3, 4, R, I, B, P, or CW
773 (the ft command may also have no parameters).
775 If you use capabilities beyond these, check the
776 results carefully on several tools.
777 Once you've confirmed that the additional capability is safe,
778 let the maintainer of this
779 document know about the safe command or sequence
780 that should be added to this list.
783 By all means include full URLs (or URIs) in the text itself;
786 can automatically turn them into hypertext links.
787 You can also use the new
789 macro to identify links to related information.
790 If you include URLs, use the full URL
791 (e.g., <http://www.kernelnotes.org>) to ensure that tools
792 can automatically find the URLs.
794 Tools processing these files should open the file and examine the first
795 non-whitespace character.
796 A period (.) or single quote (')
797 at the beginning of a line indicates a troff-based file (such as man or mdoc).
798 A left angle bracket (<) indicates an SGML/XML-based
799 file (such as HTML or Docbook).
800 Anything else suggests simple ASCII
801 text (e.g., a "catman" result).
803 Many man pages begin with '\e" followed by a space and a list of characters,
804 indicating how the page is to be preprocessed.
805 For portability's sake to non-troff translators we recommend that you avoid
806 using anything other than
808 and Linux can detect that automatically.
809 However, you might want to include this information so your man page
810 can be handled by other (less capable) systems.
811 Here are the definitions of the preprocessors invoked by these characters:
831 .IR /usr/share/groff/ [*/] tmac/tmac.an
836 Most of the macros describe formatting (e.g., font type and spacing) instead
837 of marking semantic content (e.g., this text is a reference to another page),
838 compared to formats like mdoc and DocBook (even HTML has more semantic
840 This situation makes it harder to vary the
842 format for different media,
843 to make the formatting consistent for a given media, and to automatically
844 insert cross-references.
845 By sticking to the safe subset described above, it should be easier to
846 automate transitioning to a different reference page format in the future.
853 .\" James Clark (jjc@jclark.com) wrote the implementation of the macro package.
855 .\" Rickard E. Faith (faith@cs.unc.edu) wrote the initial version of
856 .\" this manual page.
858 .\" Jens Schweikhardt (schweikh@noc.fdn.de) wrote the Linux Man-Page Mini-HOWTO
859 .\" (which influenced this manual page).
861 .\" David A. Wheeler (dwheeler@ida.org) heavily modified this
862 .\" manual page, such as adding detailed information on sections and macros.
869 .BR mdoc.samples (7),
projects / thirdparty / man-pages.git / blob