Welcome to Linux Knowledge Base and Tutorial
"The place where you learn linux"

 Create an AccountHome | Submit News | Your Account  

Tutorial Menu
Linux Tutorial Home
Table of Contents

· Introduction to Operating Systems
· Linux Basics
· Working with the System
· Shells and Utilities
· Editing Files
· Basic Administration
· The Operating System
· The X Windowing System
· The Computer Itself
· Networking
· System Monitoring
· Solving Problems
· Security
· Installing and Upgrading
· Linux and Windows

Man Pages
Linux Topics
Test Your Knowledge

Site Menu
Site Map
Copyright Info
Terms of Use
Privacy Info
Masthead / Impressum
Your Account

Private Messages

News Archive
Submit News
User Articles
Web Links


The Web

Who's Online
There are currently, 365 guest(s) and 8 member(s) that are online.

You are an Anonymous user. You can register for free by clicking here




       groff -Tascii -man file ...

       groff -Tps -man file ...

       man [section] title


       This  manual page explains the groff tmac.an macro package
       (often called the man macro package) and  related  conven­
       tions 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 ver­
       sions 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, recom­
       mended, since this will automatically detect  which  macro
       package is in use.


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

              .TH title section date source manual,


              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  con­

              source    The source of the command.

                        For  binaries,  use  something like: GNU,
                        NET-2, SLS  Distribution,  MCC  Distribu­

                        For  system calls, use the version of the
                        kernel that you are currently looking at:
                        Linux 0.99.11.
                        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

              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 docu­
                        mentation   that   exists   is   outdated
                        already.  There  are  better  sources  of
                        information for kernel developers.


       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,
       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

       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  ([]) sur­
                     round 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  decla­

       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 stan­
                     dard  error.  Omit internals and implementa­
                     tion 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  subcom­
                     mands,  consider  describing them in a sepa­
                     rate  USAGE  section  (and  just  place   an
                     overview in the DESCRIPTION section).

       RETURN VALUE  gives  a list of the values the library rou­
                     tine will return to the caller and the  con­
                     ditions   that  cause  these  values  to  be

       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  pro­
                     gram and how they change its behavior.

       USAGE         describes  the  grammar  of  any sublanguage
                     this implements.

       EXAMPLES      provides one or more examples describing how
                     this function, file or command is used.

       FILES         lists  the  files  the  program  or function
                     uses, such as configuration  files,  startup
                     files,  and files the program directly oper­
                     ates on.  Give the full  pathname  of  these
                     files,  and  use the installation process to
                     modify the  directory  part  to  match  user
                     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, espe­
                     cially  if  they aren't obvious.  Discussing
                     security in a separate section isn't  neces­
                     sary;  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

       CONFORMING TO describes  any standards or conventions this

       NOTES         provides miscellaneous notes.

       BUGS          lists limitations, known defects or inconve­
                     niences,  and other questionable activities.

       AUTHOR        lists authors of the documentation  or  pro­
                     gram 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.


       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 sec­
              tion, 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  sub­

       .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


       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  defini­
       tions are:

   Normal Paragraphs
       .LP      Same as .PP (begin a new paragraph).

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

       .PP      Begin   a  new  paragraph  and  reset  prevailing

   Relative Margin Indent
                graph's lines are indented).

       .IP x i  Indented paragraph with optional hanging tag.  If
                the tag x is omitted, the entire following  para­
                graph  is  indented  by  i.  If the tag x is pro­
                vided, 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 sim­
                plifies 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
       .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 excep­
                tion: if u is the  special  value  ":",  then  no
                hypertext  link  of  any  kind  will be generated
                until after the closing  UE  (this  permits  dis­
                abling  hypertext  links  in phrases like LALR(1)
                when linking is not appropriate).   These  hyper­
                text  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 generat­
                ing 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

   Miscellaneous Macros
       .DT      Reset  tabs  to  default  tab  values  (every 0.5
                inches); does not cause a break.

       .PD d    Set inter-paragraph vertical distance  to  d  (if
       \*(lq  Left angled doublequote: "

       \*(rq  Right angled doublequote: "


       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 abil­
       ities 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 trans­
       lators): \", ., 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 neg­
       ative  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

       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.


       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
       list of characters, indicating how the page is to be  pre­
       processed.   For  portability's sake to non-troff transla­
       tors 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

       e  eqn(1)

       g  grap(1)

       p  pic(1)

       r  refer(1)

       t  tbl(1)

       v  vgrind(1)




       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 consis­
       tent 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.


       -- 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

       -- David A. Wheeler  (dwheeler@ida.org)  heavily  modified
          this  manual  page, such as adding detailed information
Show your Support for the Linux Tutorial

Purchase one of the products from our new online shop. For each product you purchase, the Linux Tutorial gets a portion of the proceeds to help keep us going.



Security Code
Security Code
Type Security Code

Don't have an account yet? You can create one. As a registered user you have some advantages like theme manager, comments configuration and post comments with your name.

Help if you can!

Amazon Wish List

Did You Know?
You can get all the latest Site and Linux news by checking out our news page.


Tell a Friend About Us

Bookmark and Share

Web site powered by PHP-Nuke

Is this information useful? At the very least you can help by spreading the word to your favorite newsgroups, mailing lists and forums.
All logos and trademarks in this site are property of their respective owner. The comments are property of their posters. Articles are the property of their respective owners. Unless otherwise stated in the body of the article, article content (C) 1994-2013 by James Mohr. All rights reserved. The stylized page/paper, as well as the terms "The Linux Tutorial", "The Linux Server Tutorial", "The Linux Knowledge Base and Tutorial" and "The place where you learn Linux" are service marks of James Mohr. All rights reserved.
The Linux Knowledge Base and Tutorial may contain links to sites on the Internet, which are owned and operated by third parties. The Linux Tutorial is not responsible for the content of any such third-party site. By viewing/utilizing this web site, you have agreed to our disclaimer, terms of use and privacy policy. Use of automated download software ("harvesters") such as wget, httrack, etc. causes the site to quickly exceed its bandwidth limitation and are therefore expressly prohibited. For more details on this, take a look here

PHP-Nuke Copyright © 2004 by Francisco Burzi. This is free software, and you may redistribute it under the GPL. PHP-Nuke comes with absolutely no warranty, for details, see the license.
Page Generation: 0.08 Seconds