·  Home
+   man pages
 -> Linux -> FreeBSD -> OpenBSD -> NetBSD -> Tru64 Unix -> HP-UX 11i -> IRIX
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

man pages->Linux man pages -> man (7)
 Title
 Content
 Arch
 Section All Sections 1 - General Commands 2 - System Calls 3 - Subroutines 4 - Special Files 5 - File Formats 6 - Games 7 - Macros and Conventions 8 - Maintenance Commands 9 - Kernel Interface n - New Commands

## MAN(7)

### Contents




### NAME[Toc][Back]

       man - macros to format man pages


### SYNOPSIS[Toc][Back]

       groff -Tascii -man file ...

groff -Tps -man file ...

man [section] title


### DESCRIPTION[Toc][Back]

       This manual page explains the groff tmac.an macro package (often called
the man macro package) and  related  conventions  for  creating	manual
(man)  pages.   This  macro  package  should be used by developers when
writing or porting man pages for Linux.	It is fairly  compatible  with
other  versions	of this macro package, so porting man pages should not
be a major problem (exceptions include the  NET-2  BSD  release,  which
uses a totally different macro package called mdoc; see mdoc(7)).

Note  that  NET-2  BSD  mdoc man pages can be used with groff simply by
specifying the -mdoc option instead of  the  -man  option.   Using  the
-mandoc	option is, however, recommended, since this will automatically
detect which macro package is in use.


### PREAMBLE[Toc][Back]

       The first command in a man page (after comment lines) should be

.TH title section date source manual,

where:

title	The title of the man page (e.g., MAN).

section	The section number the man page should	be  placed  in
(e.g., 7).

date	The date of the last revision--remember to change this
every time a change is made to	the  man  page,  since
this is the most general way of doing version control.

source	The source of the command.

For binaries, use something like: GNU, NET-2, SLS Dis-
tribution, MCC Distribution.

For  system  calls, use the version of the kernel that
you are currently looking at: Linux 0.99.11.

For library calls, use the  source  of	the  function:
GNU, BSD 4.3, Linux DLL 4.4.1.

manual	The title of the manual (e.g., Linux Programmer's Man-
ual).

Note that BSD mdoc-formatted pages begin with the Dd command,  not  the
TH command.

The manual sections are traditionally defined as follows:

1 Commands
Those  commands  that can be executed by the user from
within a shell.

2 System calls
Those functions which must be performed by the kernel.

3 Library calls
Most of the libc functions, such as qsort(3))

4 Special files
Files found in /dev)

5 File formats and conventions
The  format  for  /etc/passwd and other human-readable
files.

6 Games

7 Macro packages and conventions
A description of the standard file system layout, network
protocols, ASCII and other character codes, this
man page, and other things.

8 System management commands
Commands like mount(8), many of which  only  root  can
execute.

9 Kernel routines
This  is  an  obsolete	manual	section.   Once it was
thought a good idea to document the Linux kernel here,
but  in  fact very little has been documented, and the
documentation that exists is outdated  already.  There
are  better sources of information for kernel developers.



### SECTIONS[Toc][Back]

       Sections are started with .SH followed by the  heading  name.   If  the
name  contains  spaces  and appears on the same line as .SH, then place
the heading  in	double	quotes.   Traditional  or  suggested  headings
include:  NAME, SYNOPSIS, DESCRIPTION, RETURN VALUE, EXIT STATUS, ERROR
HANDLING, ERRORS,  OPTIONS,  USAGE,  FILES,  ENVIRONMENT,  DIAGNOSTICS,
SECURITY,  CONFORMING  TO,  NOTES, BUGS, AUTHOR, and SEE ALSO.  Where a
traditional heading would apply, please use it; this  kind  of  consistency
can  make  the  information easier to understand.  However, feel
free to create your own headings if they make things easier  to	understand.
The  only  required heading is NAME, which should be the first
section and be followed on the next line by a one line  description  of
the program:

.SH NAME
chess \- the game of chess

It  is extremely important that this format is followed, and that there
is a backslash before the single dash which follows the	command  name.
This syntax is used by the makewhatis(8) or mandb(8) programs to create
a database of short command descriptions for the  whatis(1)  and  apro-
pos(1) commands.

Some other traditional sections have the following contents:

SYNOPSIS      briefly  describes  the  command or function's interface.
For commands, this shows the syntax of  the  command  and
its  arguments  (including options); boldface is used for
as-is text and italics are used to  indicate  replaceable
arguments.  Brackets  ([])  surround  optional arguments,
vertical bars (|) separate choices,  and  ellipses  (...)
can  be  repeated.   For functions, it shows any required
data declarations or #include directives, followed by the
function declaration.

DESCRIPTION   gives  an	explanation  of what the command, function, or
format does.  Discuss how it  interacts  with  files  and
standard  input,  and what it produces on standard output
or standard error.   Omit	internals  and	implementation
details  unless  they're  critical  for understanding the
interface.  Describe the usual case; for  information  on
options  use  the OPTIONS section.  If there is some kind
of input grammar or complex set of subcommands,  consider
describing  them  in  a  separate USAGE section (and just
place an overview in the DESCRIPTION section).

RETURN VALUE  gives a list of  the  values  the	library  routine  will
return  to the caller and the conditions that cause these
values to be returned.

EXIT STATUS   lists the possible exit status values or  a  program  and
the conditions that cause these values to be returned.

OPTIONS	     describes	the  options  accepted	by the program and how
they change its behavior.

USAGE	     describes the grammar of any sublanguage this implements.

FILES	     lists  the  files	the  program or function uses, such as
configuration files, startup files, and files the program
directly  operates  on.   Give the full pathname of these
files, and use the installation  process  to  modify  the
directory	part to match user preferences.  For many programs,
the   default   installation   location   is   in
/usr/local,   so	your   base  manual  page  should  use
/usr/local as the base.

ENVIRONMENT   lists all environment variables that affect your  program
or function and how they affect it.

DIAGNOSTICS   gives  an	overview of the most common error messages and
how to cope with them.  You don't need to explain	system
error  messages  or  fatal signals that can appear during
execution of any program unless they're special  in  some
way to your program.

SECURITY      discusses	security  issues and implications.  Warn about
configurations or environments that  should  be  avoided,
commands  that may have security implications, and so on,
especially if they aren't obvious.   Discussing  security
in  a separate section isn't necessary; if it's easier to
understand, place security information in the other  sections
(such  as the DESCRIPTION or USAGE section).  However,
please include security information somewhere!

CONFORMING TO describes any standards or conventions this implements.

NOTES	     provides miscellaneous notes.

BUGS	     lists limitations, known defects or  inconveniences,  and
other questionable activities.

AUTHOR	     lists  authors of the documentation or program so you can
mail in bug reports.

SEE ALSO      lists related man pages in alphabetical  order,  possibly
followed  by  other  related pages or documents.  Conventionally
this is the last section.


### FONTS[Toc][Back]

       Although there are many arbitrary conventions for man pages in the UNIX
world,  the  existence  of  several  hundred  Linux-specific  man pages
defines our font standards:

For functions, the arguments are always specified using italics,
even  in the SYNOPSIS section, where the rest of the function is
specified in bold:
int myfunction(int argc, char **argv);

Filenames are always in  italics	(e.g.,	/usr/include/stdio.h),
except in the SYNOPSIS section, where included files are in bold
(e.g., #include <stdio.h>).

Special macros, which are usually in upper  case,  are  in  bold
(e.g., MAXINT).

When  enumerating  a  list of error codes, the codes are in bold
(this list usually uses the .TP macro).

Any reference to another man page (or to the subject of the current
man  page)	is  in	bold.  If the manual section number is
given, it is given in Roman (normal) font,  without  any	spaces
(e.g., man(7)).

The commands to select the type face are:

.B  Bold

.BI Bold alternating with italics (especially useful for function specifications)

.BR Bold alternating with Roman (especially  useful  for  referring  to
other manual pages)

.I  Italics

.IB Italics alternating with bold

.IR Italics alternating with Roman

.RB Roman alternating with bold

.RI Roman alternating with italics

.SB Small alternating with bold

.SM Small (useful for acronyms)

Traditionally,  each  command can have up to six arguments, but the GNU
implementation removes this limitation (you might still want  to  limit
yourself  to 6 arguments for portability's sake).  Arguments are delimited
by spaces.	Double quotes can be used to specify an argument which
contains  spaces.   All	of  the arguments will be printed next to each
other without intervening spaces, so that the .BR command can  be  used
to  specify  a word in bold followed by a mark of punctuation in Roman.
If no arguments are given, the command is applied to the following line
of text.


### OTHER MACROS AND STRINGS[Toc][Back]

       Below  are  other relevant macros and predefined strings.  Unless noted
otherwise, all macros cause a break (end the  current  line  of	text).
Many of these macros set or use the "prevailing indent."  The "prevailing
indent" value is set by any	macro  with  the  parameter  i	below;
macros  may  omit i in which case the current prevailing indent will be
used.  As a result, successive indented paragraphs  can	use  the  same
indent without re-specifying the indent value.  A normal (non-indented)
paragraph resets the prevailing indent value to its default value  (0.5
inches).   By  default a given indent is measured in ens; try to ens or
ems as units for indents, since these will automatically adjust to font
size changes.  The other key macro definitions are:

Normal Paragraphs    [Toc]    [Back]
.LP	Same as .PP (begin a new paragraph).

.P	Same as .PP (begin a new paragraph).

.PP	Begin a new paragraph and reset prevailing indent.

Relative Margin Indent    [Toc]    [Back]
.RS i	Start  relative margin indent - moves the left margin i to the
right (if i is omitted, the prevailing indent value is	used).
A  new	prevailing  indent is set to 0.5 inches.  As a result,
all following paragraph(s) will be indented until  the	corresponding
.RE.

.RE	End  relative margin indent and restores the previous value of
the prevailing indent.

Indented Paragraph Macros    [Toc]    [Back]
.HP i	Begin paragraph with a hanging indent (the first line  of  the
paragraph  is at the left margin of normal paragraphs, and the
rest of the paragraph's lines are indented).

.IP x i	Indented paragraph with optional hanging tag.  If the tag x is
omitted,  the entire following paragraph is indented by i.  If
the tag x is provided, it is hung at the  left	margin	before
the following indented paragraph (this is just like .TP except
the tag is included with the command instead of being  on  the
following  line).   If the tag is too long, the text after the
tag will be moved down to the next line (text will not be lost
or  garbled).	For  bulleted  lists, use this macro with $$bu (bullet) or \(em (em dash) as the tag, and for numbered lists, use the number or letter followed by a period as the tag; this simplifies translation to other formats. .TP i Begin paragraph with hanging tag. The tag is given on the next line, but its results are like those of the .IP command. Hypertext Link Macros [Toc] [Back] .UR u Begins a hypertext link to the URI (URL) u; it will end with the corresponding UE command. When generating HTML this should translate into the HTML command <A HREF="u">. There is an exception: if u is the special value ":", then no hypertext link of any kind will be generated until after the closing UE (this permits disabling hypertext links in phrases like LALR(1) when linking is not appropriate). These hypertext link "macros" are new, and many tools won't do anything with them, but since many tools (including troff) will simply ignore undefined macros (or at worst insert their text) these are safe to insert. .UE Ends the corresponding UR command; when generating HTML this should translate into </A>. .UN u Creates a named hypertext location named u; do not include a corresponding UE command. When generating HTML this should translate into the HTML command <A NAME="u" id="u">&nbsp;</A> (the &nbsp; is optional if support for Mosaic is unneeded). Miscellaneous Macros [Toc] [Back] .DT Reset tabs to default tab values (every 0.5 inches); does not cause a break. .IX ... Inserts index information (for a search system or printed index list). Index information is not normally displayed in the page itself. If followed by a single parameter, the parameter is added as a standalone index term pointing to this location in the man page. If it's two parameters, it's probably in Perl manpage format; the first parameter identifies the type of name (one of Name, Title, Header, Subsection, or Item) and the second parameter the name itself to be indexed. Otherwise, it's in the long index format: each parameter gives an index term, subordinate index term, subsubordinate index term, and so on until terminated by an empty parameter, then a parameter with the name of the program, \em, and short description; this may be followed by another empty parameter and possibly by page control messages (e.g. PAGE START). An example of this would be "programming tools" "make" "" "\fLmake\fP \(em build programs". .PD d Set inter-paragraph vertical distance to d (if omitted, d=0.4v); does not cause a break. .SS t Subheading t (like .SH, but used for a subsection inside a section). Predefined Strings [Toc] [Back] The man package has the following predefined strings: \*R Registration Symbol: (R) \*S Change to default font size \*(Tm Trademark Symbol: tm \*(lq Left angled doublequote: " \*(rq Right angled doublequote: "  ### SAFE SUBSET[Toc][Back]  Although technically man is a troff macro package, in reality a large number of other tools process man page files that don't implement all of troff's abilities. Thus, it's best to avoid some of troff's more exotic abilities where possible to permit these other tools to work correctly. Avoid using the various troff preprocessors (if you must, go ahead and use tbl(1), but try to use the IP and TP commands instead for two-column tables). Avoid using computations; most other tools can't process them. Use simple commands that are easy to translate to other formats. The following troff macros are believed to be safe (though in many cases they will be ignored by translators): \", ., ad, bp, br, ce, de, ds, el, ie, if, fi, ft, hy, ig, in, na, ne, nf, nh, ps, so, sp, ti, tr. You may also use many troff escape sequences (those sequences beginning with$$.  When you need to include the backslash  character  as	normal
text, use \e.  Other sequences you may use, where x or xx are any characters
and N is any digit, include: \', \, \-, \., \", \%, \*x, \*(xx,
\(xx,  \\$N,  \nx,  \n(xx,  \fx,	and  \f(xx.   Avoid  using  the escape
sequences for drawing graphics.

Do not use the optional parameter for bp (break page).  Use only  positive
values  for  sp (vertical space).	Don't define a macro (de) with
the same name as a macro in this or the mdoc macro package with a  different
meaning;  it's  likely that such redefinitions will be ignored.
Every positive indent (in) should be paired with  a  matching  negative
indent  (although  you  should  be using the RS and RE macros instead).
The condition test (if,ie) should only have 't' or 'n'  as  the	condition.
Only translations (tr) that can be ignored should be used.  Font
changes (ft and the \f escape sequence) should only have the values  1,
2,  3,  4,  R,  I, B, P, or CW (the ft command may also have no parameters).

If you use capabilities beyond these, check the	results  carefully  on
several tools.  Once you've confirmed that the additional capability is
safe, let the maintainer of this document know about the  safe  command
or sequence that should be added to this list.


### NOTES[Toc][Back]

       By all means include full URLs (or URIs) in the text itself; some tools
such as man2html(1) can automatically turn them into  hypertext	links.
You can also use the new UR macro to identify links to related information.
If you include URLs, use the full URL (e.g., <http://www.kernel-
notes.org>) to ensure that tools can automatically find the URLs.

Tools processing these files should open the file and examine the first
non-whitespace character. A period (.)  or  single  quote  (')  at  the
beginning of a line indicates a troff-based file (such as man or mdoc).
A left angle bracket (<) indicates an SGML/XML-based file (such as HTML
or Docbook). Anything else suggests simple ASCII text (e.g., a "catman"
result).

Many man pages begin with '\" followed by a space and a list of characters,
indicating how the page is to be preprocessed.  For portability's
sake to non-troff translators we recommend that you  avoid  using  anything
other than tbl(1), and Linux can detect that automatically.  However,
you might want to include this information so your man  page  can
be  handled  by other (less capable) systems.  Here are the definitions
of the preprocessors invoked by these characters:

e  eqn(1)

g  grap(1)

p  pic(1)

r  refer(1)

t  tbl(1)

v  vgrind(1)


### FILES[Toc][Back]

       /usr/share/groff/tmac/tmac.an
/usr/man/whatis


### BUGS[Toc][Back]

       Most of the macros describe formatting (e.g., font  type  and  spacing)
instead	of marking semantic content (e.g., this text is a reference to
another page), compared to formats like mdoc and DocBook (even HTML has
more  semantic  markings).   This situation makes it harder to vary the
man format for different media, to make the formatting consistent for a
given media, and to automatically insert cross-references.  By sticking
to the safe subset described above, it should  be  easier  to  automate
transitioning to a different reference page format in the future.

The Sun macro TX is not implemented.


### AUTHORS[Toc][Back]

       -- James  Clark	(jjc@jclark.com) wrote the implementation of the macro
package.

-- Rickard E. Faith (faith@cs.unc.edu) wrote  the  initial  version  of
this manual page.

-- Jens	Schweikhardt  (schweikh@noc.fdn.de)  wrote  the Linux Man-Page
Mini-HOWTO (which influenced this manual page).

-- David A. Wheeler (dwheeler@ida.org)  heavily	modified  this	manual
page, such as adding detailed information on sections and macros.


### SEE ALSO[Toc][Back]

       apropos(1),  groff(1),  man(1),	man2html(1), mdoc(7), mdoc.samples(7),
whatis(1)

Linux				  1999-06-16				MAN(7)
`
[ Back ]
Similar pages
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service