Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
man(1)									man(1)

       man - find and display reference	manual pages

       man [-] [-adFlrt] [-M path] [-T macro-package] [-s section] name...

       man [-M path] -k	keyword...

       man [-M path] -f	file...

       The  man	 command  displays  information	from the reference manuals. It
       displays	complete manual	pages that you select  by  name,  or  one-line
       summaries selected either by keyword (-k), or by	the name of an associ-
       ated file (-f). If no manual page is located, man prints	an error  mes-

   Source Format
       Reference  Manual  pages	are marked up with either nroff	(see nroff(1))
       or SGML (Standard Generalized Markup Language) tags (see	sgml(5)).  The
       man  command  recognizes	 the  type  of	markup	and processes the file
       accordingly. The	various	source files are kept in separate  directories
       depending on the	type of	markup.

   Location of Manual Pages
       The online Reference Manual page	directories are	conventionally located
       in   /usr/share/man.   The   nroff   sources   are   located   in   the
       /usr/share/man/man*  directories.  The  SGML sources are	located	in the
       /usr/share/man/sman* directories. Each directory	corresponds to a  sec-
       tion  of	 the manual. Since these directories are optionally installed,
       they  might  not	 reside	 on  your  host.  You  might  have  to	 mount
       /usr/share/man from a host on which they	do reside.

       If  there  are  preformatted,  up-to-date versions in the corresponding
       cat* or fmt* directories, man simply displays or	prints those versions.
       If  the preformatted version of interest	is out of date or missing, man
       reformats it prior to display and stores	the  preformatted  version  if
       cat*  or	  fmt* is writable.   The  windex database is not updated. See
       catman(1M). If directories for the preformatted versions	are  not  pro-
       vided,	man reformats a	page whenever it is requested. man uses	a tem-
       porary file to store the	formatted text during display.

       If the standard output is not a terminal, or if the `-' flag is	given,
       man  pipes  its	output through cat(1). Otherwise, man pipes its	output
       through more(1) to handle paging	and underlining	on the screen.

       The following options are supported:

       -a	       Shows all manual	pages matching	name within  the  MAN-
		       PATH  search  path.  Manual  pages are displayed	in the
		       order found.

       -d	       Debugs. Displays	what a section-specifier evaluates to,
		       method used for searching, and paths searched by	man.

       -f file ...     man  attempts  to locate	manual pages related to	any of
		       the given files.	It strips the leading path name	compo-
		       nents  from  each  file,	 and then prints one-line sum-
		       maries containing the resulting basename	or names. This
		       option also uses	the windex database.

       -F	       Forces  man to search all directories specified by MAN-
		       PATH or the file,	rather than using  the	windex
		       lookup  database. This option is	useful if the database
		       is not up to date and it	 has  been  made  the  default
		       behavior	 of the	man command. The option	therefore does
		       not have	to be invoked and is documented	here for  ref-
		       erence only.

       -k keyword ...  Prints  out one-line summaries from the windex database
		       (table of contents) that	contain	any of the given  key-
		       words. The windex database is created using catman(1M).

       -l	       Lists all manual	pages found matching name  within  the
		       search path.

       -M path	       Specifies  an  alternate	 search	path for manual	pages.
		       path is a colon-separated list of directories that con-
		       tain  manual  page  directory subtrees. For example, if
		       path is /usr/share/man:/usr/local/man, man searches for
		       name in the standard location, and then /usr/local/man.
		       When used with the -k or	-f options, the	-M option must
		       appear  first. Each directory in	the path is assumed to
		       contain subdirectories of the form man* or sman*	,  one
		       for  each  section.  This  option overrides the MANPATH
		       environment variable.

       -r	       Reformats the manual page, but  does  not  display  it.
		       This replaces the man - -t name combination.

       -s section ...  Specifies sections of the manual	for man	to search. The
		       directories searched for	 name  are  limited  to	 those
		       specified by section. section can be a numerical	digit,
		       perhaps followed	by one or more letters	to  match  the
		       desired	section	of the manual, for example, "3libucb".
		       Also, section can be a word, for	example,  local,  new,
		       old,  public.  section can also be a letter. To specify
		       multiple	sections, separate each	section	with a	comma.
		       This  option overrides the MANPATH environment variable
		       and the file.  See  Search  Path	below  for  an
		       explanation of how man conducts its search.

       -t	       man  arranges  for  the	specified  manual  pages to be
		       troffed	to  a  suitable	 raster	 output	 device	  (see
		       troff(1)).   If	both the - and -t flags	are given, man
		       updates the troffed versions of	each  named  name  (if
		       necessary), but does not	display	them.

       -T macro-packageFormats	manual	pages  using macro-package rather than
		       the     standard	    -man     macros	defined	    in
		       /usr/share/lib/tmac/an.	See   Search Path under	 for a
		       complete	explanation of the default search path	order.

       The following operand is	supported:

       name	       A keyword or the	name of	a standard utility.

       The usage of man	is described below:

   Manual Page Sections
       Entries in the reference	manuals	are organized into sections. A section
       name consists of	a  major  section  name,  typically  a	single	digit,
       optionally  followed  by	 a subsection name, typically one or more let-
       ters. An	unadorned major	section	name, for example, "9",	does  not  act
       as  an  abbreviation  for  the  subsections of that name, such as "9e",
       "9f", or	"9s". That is, each subsection must be searched	separately  by
       man  -s.	  Each	section	 contains descriptions apropos to a particular
       reference category, with	subsections refining these  distinctions.  See
       the intro manual	pages for an explanation of the	classification used in
       this release.

   Search Path
       Before searching	for a given name, man constructs a list	 of  candidate
       directories  and	 sections.  man	 searches  for name in the directories
       specified by the	MANPATH	environment variable. If this variable is  not
       set, /usr/share/man is searched by default.

       Within the manual page directories, man confines	its search to the sec-
       tions specified in the following	order:

	 o  sections specified on the command line with	the -s option

	 o  sections embedded in the MANPATH environment variable

	 o  sections specified in the file for each directory specified
	    in the MANPATH environment variable

       If  none	 of the	above exist, man searches each directory in the	manual
       page path, and displays the first matching manual page found.

       The file has the following format:


       Lines beginning with `#'	and blank lines	are considered	comments,  and
       are  ignored.  Each directory specified in MANPATH can contain a	manual
       page configuration file,	specifying the default search order  for  that

Formatting Manual Pages
       Manual  pages are marked	up in nroff(1) or sgml(5).  Nroff manual pages
       are processed by	nroff(1) or troff(1)  with  the	 -man  macro  package.
       Please  refer  to  man(5)  for information on macro usage. SGML--tagged
       manual pages are	processed by an	 SGML parser and passed	to the format-

   Preprocessing Nroff Manual Pages
       When  formatting	 an  nroff manual page,	man examines the first line to
       determine whether it requires special processing. If the	first line  is
       a string	of the form:

       '\" X

       where  X	 is separated from the `"' by a	single <SPACE> and consists of
       any combination of characters in	the  following	list,  man  pipes  its
       input  to troff(1) or nroff(1) through the corresponding	preprocessors.

       e	eqn(1),	or neqn	for nroff

       r	refer(1)

       t	tbl(1)

       v	vgrind(1)

       If  eqn	or  neqn  is  invoked,	it  automatically   reads   the	  file
       /usr/pub/eqnchar	 (see  eqnchar(5)).  If	nroff(1) is invoked, col(1) is
       automatically used.

   Referring to	Other nroff Manual Pages
       If the first line of the	nroff manual page is a	reference  to  another
       manual page entry fitting the pattern:

       .so man*/sourcefile

       man  processes the indicated file in place of the current one. The ref-
       erence must be expressed	as a path name relative	to  the	 root  of  the
       manual page directory subtree.

       When the	second or any subsequent line starts with .so, man ignores it;
       troff(1)	or nroff(1) processes the request in the usual manner.

   Processing SGML Manual Pages
       Manual pages are	identified as being marked up in SGML by the  presence
       of  the	string	<!DOCTYPE.  If	the  file  also	 contains  the	string
       SHADOW_PAGE, the	file refers to another manual page  for	 the  content.
       The  reference  is made with a file entity reference to the manual page
       that contains the text. This is similar to the  .so mechanism  used  in
       the nroff formatted man pages.

       See  environ(5) for descriptions	of the following environment variables
       that affect the execution of man: LANG, LC_ALL, LC_CTYPE,  LC_MESSAGES,
       and NLSPATH.

       MANPATH	       A  colon-separated  list	of directories;	each directory
		       can be followed by a comma-separated list of  sections.
		       If  set,	 its  value  overrides	/usr/share/man	as the
		       default directory search	path, and the  file  as
		       the  default section search path. The -M	and  -s	flags,
		       in turn,	override these values.)

       PAGER	       A program to use	 for  interactively  delivering	 man's
		       output  to  the	screen.	If not set, `more -s' is used.
		       See more(1).

       TCAT	       The name	of the program to use to display troffed  man-
		       ual pages.

       TROFF	       The  name  of  the formatter to use when	the -t flag is
		       given. If not set, troff(1) is used.

       Example 1: Creating a PostScript	Version	of a man page

       The following example creates the pipe(2) man page  in  postscript  for
       csh, tcsh, ksh and sh users:

	    % env TCAT=/usr/lib/lp/postscript/dpost man	-t -s 2	pipe >

       This  is	 an  alternative to  using man -t, which sends the man page to
       the default printer, if the user	 wants a postscript  file  version  of
       the man page.

       Example 2: Creating a Text Version of a man page

       The following example creates the pipe(2) man page in ascii text:

       man pipe.2 | col	-x -b  >  pipe.text

       This  is	 an  alternative to  using man -t, which sends the man page to
       the default printer, if the user	 wants a text file version of the  man

       The following exit values are returned:

       0	       Successful completion.

       >0	       An error	occurred.


	   Root	of the standard	manual page directory subtree


	   Unformatted nroff manual entries


	   Unformatted	SGML manual entries


	   nroffed manual entries


	   troffed manual entries


	   Table of contents and keyword database


	   Standard -man macro package


	   SGML	document type definition files


	   SGML	style sheet and	entity definitions directories


	   Standard definitions	for eqn	and neqn

	   Default search order	by section

       See attributes(5) for descriptions of the following attributes:

       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       |Availability		     |SUNWdoc			   |
       |CSI			     |Enabled, see .		   |
       |Interface Stability	     |Standard			   |

       apropos(1),   cat(1),  col(1),  dpost(1),  eqn(1),  more(1),  nroff(1),
       refer(1),   tbl(1),   troff(1),	 vgrind(1),   whatis(1),   catman(1M),
       attributes(5), environ(5), eqnchar(5), man(5), sgml(5), standards(5)

       The -f and -k options use the windex database, which is created by cat-

       The man command is CSI-capable. However,	some utilities invoked by  the
       man  command, namely, troff, eqn, neqn, refer, tbl, and vgrind, are not
       verified	to be CSI-capable. Because of this, the	man command  with  the
       -t  option  can not handle non-EUC data.	Also, using the	man command to
       display man pages that require special processing  through  eqn,	 neqn,
       refer, tbl, or vgrind can not be	CSI-capable.

       The  manual  is supposed	to be reproducible either on a phototypesetter
       or on an	ASCII terminal.	However, on a terminal some information	(indi-
       cated by	font changes, for instance) is lost.

       Some dumb terminals cannot process the vertical motions produced	by the
       e (see eqn(1)) preprocessing flag. To prevent garbled output  on	 these
       terminals,  when	 you  use  e, also use t, to invoke col(1) implicitly.
       This workaround has the disadvantage of	eliminating  superscripts  and
       subscripts,  even on those terminals that can display them. <Control-q>
       clears a	terminal that gets confused by eqn(1) output.

				  13 Jul 2005				man(1)

NAME | SYNOPSIS | Formatting Manual Pages | EXAMPLES

Want to link to this manual page? Use this URL:

home | help