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

FreeBSD Manual Pages


home | help
man(1)				 User Commands				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(1) or  sgml(5)
       (Standard Generalized Markup Language) tags. 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

   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 may	not reside on your host. You may 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 will store 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
       provided,   man	reformats  a page whenever it is requested. man	uses a
       temporary 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  MANPATH	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 components from each file,
	     and then prints one-line summaries	containing the resulting base-
	     name or names. This option	also uses the windex database.

       -F    Forces  man to search all directories specified by	MANPATH	or the file, rather than using the	windex lookup  database.  This
	     is	 useful	if the database	is not up to date. If the windex data-
	     base does not exist, this option is assumed.

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

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

       -M path
	     Specifies	an  alternate  search path for manual pages. path is a
	     colon-separated list of directories that contain manual page  di-
	     rectory subtrees. For example, if path is /usr/share/man:/usr/lo-
	     cal/man, man searches for name in the standard location, and then
	     /usr/local/man.   When used with the -k or	-f options, the	-M op-
	     tion 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 directo-
	     ries 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");  a  word (for example:	local, new, old, public); or 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-package
	     Formats manual pages using	macro-package rather than the standard
	     -man  macros  defined in /usr/share/lib/tmac/an. See  Search Path
	     under USAGE for a complete	explanation of the default search path

       The following operand is	supported:

       name  A keyword or the name of a	standard utility.

   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	speci-
	     fied 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  will  automatically	 read 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: LC_CTYPE, LC_MESSAGES,	and NLSPATH.

	     A colon-separated list of directories; each directory can be fol-
	     lowed 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 manual pages.

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

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

       apropos(1),   cat(1),  col(1),  eqn(1),	more(1),  nroff(1),  refer(1),
       tbl(1), troff(1), vgrind(1), whatis(1), catman(1M), attributes(5), env-
       iron(5),	eqnchar(5), man(5), sgml(5)

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

       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  may 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 may 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>
       will clear a terminal that gets confused	by eqn(1) output.

SunOS 5.9			  10 Dec 2001				man(1)


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

home | help