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 .\" [todo: split this into man.7 describing the macros
29 .\" and manpage.7 describing the Linux man page conventions]
31 .TH MAN 7 1999-06-16 "Linux" "Linux Programmer's Manual"
33 man \- macros to format man pages
35 .B groff \-Tascii \-man
47 This manual page explains the
49 macro package (often called the
51 macro package) and related conventions for creating manual (man) pages.
52 This macro package should be used by developers when
53 writing or porting man pages for Linux. It is fairly compatible with other
54 versions of this macro package, so porting man pages should not be a major
55 problem (exceptions include the NET-2 BSD release, which uses a totally
56 different macro package called mdoc; see
59 Note that NET-2 BSD mdoc man pages can be used with
61 simply by specifying the
67 option is, however, recommended, since this will automatically detect which
68 macro package is in use.
70 The first command in a man page (after comment lines) should be
74 .IR "title section date source manual" ,
81 The title of the man page (e.g.,
85 The section number the man page should be placed in (e.g.,
89 The date of the last revision\(emremember to change this every time a
90 change is made to the man page, since this is the most general way of doing
94 The source of the command.
96 For binaries, use something like:
97 .IR GNU ", " NET-2 ", " "SLS Distribution" ", " "MCC Distribution" .
99 For system calls, use the version of the kernel that you are currently
101 .IR "Linux 0.99.11" .
103 For library calls, use the source of the function:
104 .IR GNU ", " "BSD 4.3" ", " "Linux DLL 4.4.1" .
107 The title of the manual (e.g.,
108 .IR "Linux Programmer's Manual" ).
111 Note that BSD mdoc-formatted pages begin with the
117 The manual sections are traditionally defined as follows:
121 Those commands that can be executed by the user from within
125 Those functions which must be performed by the kernel.
137 .B 5 File formats and conventions
140 and other human-readable files.
144 .B 7 Macro packages and conventions
145 A description of the standard file system layout, network protocols,
146 ASCII and other character codes, this man page, and other things.
148 .B 8 System management commands
156 This is an obsolete manual section.
157 Once it was thought a good idea to document the Linux kernel here,
158 but in fact very little has been documented, and the documentation
159 that exists is outdated already. There are better sources of
160 information for kernel developers.
163 Sections are started with
165 followed by the heading name. If the name contains spaces and appears
168 then place the heading in double quotes. Traditional or suggested
170 NAME, SYNOPSIS, DESCRIPTION, RETURN VALUE,
171 EXIT STATUS, ERROR HANDLING, ERRORS,
172 OPTIONS, USAGE, EXAMPLES, FILES, ENVIRONMENT, DIAGNOSTICS, SECURITY,
173 CONFORMING TO, NOTES,
174 BUGS, AUTHOR, and SEE ALSO.
175 Where a traditional heading would apply, please use it;
176 this kind of consistency can make the information easier to understand.
177 However, feel free to create your own headings if they make things easier
179 The only required heading is
181 which should be the first section and
182 be followed on the next line by a one line description of the program:
187 chess \\- the game of chess
190 It is extremely important that this format is followed, and that there is a
191 backslash before the single dash which follows the command name. This
192 syntax is used by the
194 program to create a database of short command descriptions for the
200 Some other traditional sections have the following contents:
203 briefly describes the command or function's interface.
204 For commands, this shows the syntax of the command and its arguments
206 boldface is used for as-is text and italics are used to indicate replaceable
207 arguments. Brackets ([]) surround optional arguments, vertical bars (|)
208 separate choices, and ellipses (\&...) can be repeated.
209 For functions, it shows any required data declarations or
211 directives, followed by the function declaration.
214 gives an explanation of what the command, function, or format does.
215 Discuss how it interacts with files and standard input, and what it
216 produces on standard output or standard error.
217 Omit internals and implementation details unless they're critical for
218 understanding the interface.
219 Describe the usual case; for information on options use the
222 If there is some kind of input grammar or complex set of subcommands,
223 consider describing them in a separate
225 section (and just place an overview in the
231 list of the values the library routine will return to the caller
232 and the conditions that cause these values to be returned.
235 lists the possible exit status values or a program and
236 the conditions that cause these values to be returned.
239 describes the options accepted by the program and how they change
243 describes the grammar of any sublanguage this implements.
246 provides one or more examples describing how this function, file or
250 lists the files the program or function uses, such as
251 configuration files, startup files,
252 and files the program directly operates on.
253 Give the full pathname of these files, and use the installation
254 process to modify the directory part to match user preferences.
255 For many programs, the default installation location is in /usr/local,
256 so your base manual page should use /usr/local as the base.
259 lists all environment variables that affect your program or function
260 and how they affect it.
263 gives an overview of the most common error messages and how to
264 cope with them. You don't need to explain system error messages
265 or fatal signals that can appear during execution of any program
266 unless they're special in some way to your program.
269 discusses security issues and implications.
270 Warn about configurations or environments that should be avoided,
271 commands that may have security implications, and so on, especially
272 if they aren't obvious.
273 Discussing security in a separate section isn't necessary;
274 if it's easier to understand, place security information in the
275 other sections (such as the
280 However, please include security information somewhere!
283 describes any standards or conventions this implements.
286 provides miscellaneous notes.
289 lists limitations, known defects or inconveniences,
290 and other questionable activities.
293 lists authors of the documentation or program so you can mail in bug
297 lists related man pages in alphabetical order, possibly followed by
298 other related pages or documents.
299 Conventionally this is the last section.
301 Although there are many arbitrary conventions for man pages in the UNIX
302 world, the existence of several hundred Linux-specific man pages defines our
305 For functions, the arguments are always specified using italics,
306 .IR "even in the SYNOPSIS section" ,
307 where the rest of the function is specified in bold:
309 .BI "int myfunction(int " argc ", char **" argv );
312 Filenames are always in italics (e.g.,
313 .IR "/usr/include/stdio.h" ),
314 except in the SYNOPSIS section, where included files are in bold (e.g.,
315 .BR "#include <stdio.h>" ).
317 Special macros, which are usually in upper case, are in bold (e.g.,
320 When enumerating a list of error codes, the codes are in bold (this list
325 Any reference to another man page (or to the subject of the current man
326 page) is in bold. If the manual section number is given, it is given in
327 Roman (normal) font, without any spaces (e.g.,
330 The commands to select the type face are:
336 Bold alternating with italics
337 (especially useful for function specifications)
340 Bold alternating with Roman
341 (especially useful for referring to other
348 Italics alternating with bold
351 Italics alternating with Roman
354 Roman alternating with bold
357 Roman alternating with italics
360 Small alternating with bold
363 Small (useful for acronyms)
365 Traditionally, each command can have up to six arguments, but the GNU
366 implementation removes this limitation (you might still want to limit
367 yourself to 6 arguments for portability's sake).
368 Arguments are delimited by
369 spaces. Double quotes can be used to specify an argument which contains
370 spaces. All of the arguments will be printed next to each other without
371 intervening spaces, so that the
373 command can be used to specify a word in bold followed by a mark of
374 punctuation in Roman.
375 If no arguments are given, the command is applied to the following line
377 .SH "OTHER MACROS AND STRINGS"
379 Below are other relevant macros and predefined strings.
380 Unless noted otherwise, all macros
381 cause a break (end the current line of text).
382 Many of these macros set or use the "prevailing indent."
383 The "prevailing indent" value is set by any macro with the parameter
388 in which case the current prevailing indent will be used.
389 As a result, successive indented paragraphs can use the same indent without
390 re-specifying the indent value.
391 A normal (non-indented) paragraph resets the prevailing indent value
392 to its default value (0.5 inches).
393 By default a given indent is measured in ens; try to ens or ems as units for
394 indents, since these will automatically adjust to font size changes.
395 The other key macro definitions are:
396 .SS "Normal Paragraphs"
401 (begin a new paragraph).
406 (begin a new paragraph).
409 Begin a new paragraph and reset prevailing indent.
410 .SS "Relative Margin Indent"
413 Start relative margin indent - moves the left margin
417 is omitted, the prevailing indent value is used).
418 A new prevailing indent is set to 0.5 inches.
419 As a result, all following paragraph(s) will be
420 indented until the corresponding
424 End relative margin indent and
425 restores the previous value of the prevailing indent.
426 .SS "Indented Paragraph Macros"
429 Begin paragraph with a hanging indent
430 (the first line of the paragraph is at the left margin of
431 normal paragraphs, and the rest of the paragraph's lines are indented).
434 Indented paragraph with optional hanging tag.
437 is omitted, the entire following paragraph is indented by
441 is provided, it is hung at the left margin
442 before the following indented paragraph
445 except the tag is included with the command instead of being on the
447 If the tag is too long, the text after the tag will be moved down to the
448 next line (text will not be lost or garbled).
449 For bulleted lists, use this macro with \e(bu (bullet) or \e(em (em dash)
450 as the tag, and for numbered lists, use the number or letter followed by
452 this simplifies translation to other formats.
455 Begin paragraph with hanging tag. The tag is given on the next line, but
456 its results are like those of the
459 .SS "Hypertext Link Macros"
462 Begins a hypertext link to the URI (URL)
464 it will end with the corresponding
467 When generating HTML this should translate into the HTML command
468 \fB<A HREF="\fP\fIu\fP\fB">\fP.
469 There is an exception: if
471 is the special value ":", then no hypertext link of any kind
472 will be generated until after the closing
474 (this permits disabling hypertext links in phrases like
478 when linking is not appropriate).
479 These hypertext link "macros" are new, and
480 many tools won't do anything with them, but
481 since many tools (including troff) will simply ignore undefined macros
482 (or at worst insert their text) these are safe to insert.
485 Ends the corresponding
488 when generating HTML this should translate into
492 Creates a named hypertext location named
494 do not include a corresponding
497 When generating HTML this should translate into the HTML command
498 \fB<A NAME="\fP\fIu\fP\fB" id="\fP\fIu\fP\fB"> </A>\fP
499 (the is optional if support for Mosaic is unneeded).
500 .SS "Miscellaneous Macros"
503 Reset tabs to default tab values (every 0.5 inches);
504 does not cause a break.
507 Set inter-paragraph vertical distance to d
508 (if omitted, d=0.4v);
509 does not cause a break.
516 but used for a subsection inside a section).
517 .SS "Predefined Strings"
520 package has the following predefined strings:
522 Registration Symbol: \*R
524 Change to default font size
526 Trademark Symbol: \*(Tm
528 Left angled doublequote: \*(lq
530 Right angled doublequote: \*(rq
534 is a troff macro package, in reality a large number of other tools
535 process man page files that don't implement all of troff's abilities.
536 Thus, it's best to avoid some of troff's more exotic abilities where possible
537 to permit these other tools to work correctly.
538 Avoid using the various troff preprocessors
539 (if you must, go ahead and use
545 commands instead for two-column tables).
546 Avoid using computations; most other tools can't process them.
547 Use simple commands that are easy to translate to other formats.
548 The following troff macros are believed to be safe (though in many cases
549 they will be ignored by translators):
576 You may also use many troff escape sequences (those sequences beginning
578 When you need to include the backslash character as normal text,
580 Other sequences you may use, where x or xx are any characters and N
581 is any digit, include:
597 Avoid using the escape sequences for drawing graphics.
599 Do not use the optional parameter for
602 Use only positive values for
607 with the same name as a macro in this or the
608 mdoc macro package with a different meaning; it's likely that
609 such redefinitions will be ignored.
610 Every positive indent
612 should be paired with a matching negative indent
613 (although you should be using the
620 should only have 't' or 'n' as the condition.
623 that can be ignored should be used.
626 and the \fB\ef\fP escape sequence)
627 should only have the values 1, 2, 3, 4, R, I, B, P, or CW
628 (the ft command may also have no parameters).
630 If you use capabilities beyond these, check the
631 results carefully on several tools.
632 Once you've confirmed that the additional capability is safe,
633 let the maintainer of this
634 document know about the safe command or sequence
635 that should be added to this list.
638 By all means include full URLs (or URIs) in the text itself;
641 can automatically turn them into hypertext links.
642 You can also use the new
644 macro to identify links to related information.
645 If you include URLs, use the full URL
646 (e.g., <http://www.kernelnotes.org>) to ensure that tools
647 can automatically find the URLs.
649 Tools processing these files should open the file and examine the first
650 non-whitespace character. A period (.) or single quote (')
651 at the beginning of a line indicates a troff-based file (such as man or mdoc).
652 A left angle bracket (<) indicates an SGML/XML-based
653 file (such as HTML or Docbook). Anything else suggests simple ASCII
654 text (e.g., a "catman" result).
656 Many man pages begin with '\e" followed by a space and a list of characters,
657 indicating how the page is to be preprocessed.
658 For portability's sake to non-troff translators we recommend that you avoid
659 using anything other than
661 and Linux can detect that automatically.
662 However, you might want to include this information so your man page
663 can be handled by other (less capable) systems.
664 Here are the definitions of the preprocessors invoked by these characters:
684 .IR /usr/share/groff/ [*/] tmac/tmac.an
689 Most of the macros describe formatting (e.g., font type and spacing) instead
690 of marking semantic content (e.g., this text is a reference to another page),
691 compared to formats like mdoc and DocBook (even HTML has more semantic
693 This situation makes it harder to vary the
695 format for different media,
696 to make the formatting consistent for a given media, and to automatically
697 insert cross-references.
698 By sticking to the safe subset described above, it should be easier to
699 automate transitioning to a different reference page format in the future.
706 James Clark (jjc@jclark.com) wrote the implementation of the macro package.
708 Rickard E. Faith (faith@cs.unc.edu) wrote the initial version of
711 Jens Schweikhardt (schweikh@noc.fdn.de) wrote the Linux Man-Page Mini-HOWTO
712 (which influenced this manual page).
714 David A. Wheeler (dwheeler@ida.org) heavily modified this
715 manual page, such as adding detailed information on sections and macros.
722 .BR mdoc.samples (7),