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 ac-
       cordingly. 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 or-
		       der 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  be-
		       havior  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 en-
		       vironment 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 ex-
		       planation 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,  op-
       tionally	 followed by a subsection name,	typically one or more letters.
       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 re-

   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  in-
       put 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  de-
		       fault 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),  re-
       fer(1),	 tbl(1),   troff(1),  vgrind(1),  whatis(1),  catman(1M),  at-
       tributes(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