MAN(1)									MAN(1)

NAME
     man - print entries from the on-line reference manuals; find manual
     entries by keyword

SYNOPSIS
     man [-cdwWtpr] [-M path] [-T macropackage]	[section] title	...
     man [-M path] -k keyword ...
     man [-M path] -f filename ...

DESCRIPTION
     man locates and prints the	titleed	entries	from the on-line reference
     manuals.  man also	prints summaries of manual entries selected by keyword
     or	by associated filename.

     If	a section is given, only that particular section is searched for the
     specified title.  The current list	of valid sections are any single digit
     [0-9], the	letter 'D', plus the sections local, public, new, and old,
     corresponding to the sections l, p, n, and	o, respectively.  When a
     section name of this form is given, the first character is	used to	form
     the directory, thus "local", will cause directories ending	in "manl" to
     be	searched.  To find a man page with the name of one of these sections,
     it	is necessary to	first give a dummy name, such as "man junk local",
     which is unfortunate.

     If	no section is given, all sections of the on-line reference manuals are
     searched and all occurrences of title are printed.	 The default sections
     are searched in this order:  1nl6823457poD

     Manual entries are	retrieved in the following order:  for each root
     directory in the search path, language specific directories are searched
     first (see	discussion of the LANG environment variable below), followed
     by	generic	directories. Within each of those searches, local additions
     are searched first, followed by the standard manual directories.  In each
     leaf directory, there may be actual pages or subdirectories.  If the
     subdirectory name has the format cat[1-8lnopD] then the pages in that
     subdirectory are treated as pre-formatted "cat" manual entries.  If the
     subdirectory name has the format man[1-8lnopD] then the pages in that
     subdirectory are treated as unformatted nroff(1) source manual entries.
     Unformatted manual	entries	will be	processed by neqn(1), tbl(1),
     nroff(1), and col(1).  (See the CAVEATS section concerning	formatting
     unformatted manual	pages.)	 These must be installed with a	standard
     suffix, such as .1m, in order for the man command to find them (i.e.,
     name, period, suffix).  The "cat" manual entries are be compressed	to
     save disk space using pack(1) or compress(1); all pre-formatted man pages
     must be compressed	with one of the	abvoe in order for the man command to
     find them.	 man will automatically	uncompress compressed "cat" manual
     entries using pcat(1) and zcat(1) respectively.

     After the local additions are searched, the standard pre-formatted	manual
     entries in	/usr/share/catman/[agpu]_man are searched.

     After searching /usr/share/catman,	man will search	/usr/share/man ,
     /usr/catman , then	/usr/man , for manual pages.  The user may override
     these default root	directories for	manual entries with the	environment
     variable MANPATH or with the command-line options -M and -d.  (See
     discussion	below.)

     IRIX is derived from four main sources: AT&T, Berkeley, MIPS Computer
     Systems, and Sun Microsystems.  Because development at these sources is
     more or less independent, in several cases	programs have been given the
     same name but have	vastly different functionality.	 The manual entries
     for such programs have been distinguished by giving them suffixes:	 _att,
     _bsd, _mips, or _sun.  You	do not need to give the	suffixes.  If man is
     given an un-suffixed title	title for which	suffixed entries exist,	it
     will display all of them.

     Searches for titles, keywords, and	filenames are case-insensitive.	 For
     example, the manual entry RGBcolor(3G) can	be gotten by the command-line:

  man rgbcolor

     Also, titles, keywords, and filenames may contain special characters
     allowing manual pages to looked up	by only	specifying partial names in
     much the same way that sh(1) and csh(1) match file	names.	For example,
     the summaries of manual entries pertaining	to RGB writemasks may be
     searched by the command-line:

  man -k 'rgb*mask'

     The complete set of special characters is as follows:


     *	    Match any sequence of characters, including	none-at-all.

     ?	    Match any single character.

     [...]  Matches any	of the set of characters between the brackets.	A pair
    of characters separated by - matches any one of the	characters
    which comes	between	the two	characters, including the two
    characters,	based on ASCII character encoding (see ascii(5)).


     man also supports a more sophisticated means for looking up manual	pages
     using regular expressions.	 To use	regular	expressions to lookup manual
     pages, you	must use the -r	option discussed below.

OPTIONS
     -M	path	  Use path as the search path for manual entries.  path	is a
	  colon-separated list of directories where manual
	  subdirectories may be	found.	The default path is
	  /usr/share/catman:/usr/share/man:/usr/catman:/usr/man.  -M
	  is useful for	searching locations other than the standard
	  manual directories for manual	entries.  These	locations



								Page 2






MAN(1)									MAN(1)



	  could	be personal manual page	trees or NFS mounted BSD style
	  manual page trees from another system.  For example, the
	  standard manual directories could be augmented with personal
	  manual pages by specifying the path:

	    /usr/share/catman:/usr/share/man:/usr/catman:/usr/man:$HOME/man

	  -M must be given before -k and -f.  -M will override the
	  environment variable MANPATH.	 -M and	-d are mutually
	  exclusive.  At most 100 directories may be specified;	if
	  more are specified, the rest will be ignored.

     -c		  Copy the manual page to the standard output instead of using
	  more(1) or the user specified	PAGER or MANPAGER.

     -d		  Use the direct path specified	for finding the	manual page
	  title.  The -d option	uses the full path name	of the
	  specified title as the manual	page to	print, formatting it
	  if necessary.	 Since -d does no searching, any suffixes like
	  ".1" must be specified otherwise the manual page will	not be
	  found.  If no	leading	path is	specified, the current
	  directory (.)	is assumed.  -d	is useful for formatting
	  manual page sources you are editing as part of your software
	  development.	The -t option may be used in conjunction with
	  -d to	format a manual	page source file and send it to	the
	  printer.  -d will ignore the environment variable MANPATH.
	  -d and -M are	mutually exclusive.

     -p		  Print	on standard output the commands	that would be executed
	  to format and	display	the specified manual pages instead of
	  actually executing the commands.

     -w		  Print	only the pathname of each entry	matching the given
	  title.  The actual matching entry will not be	printed, only
	  its path is given.

     -t		  Typeset each titled manual entry and send the	result to the
	  printer.  In the case	of the preformatted "cat" manual pages
	  which	come standard with IRIX, the entry is unpacked using
	  pcat(1) and then sent	to the default printer using lp(1).
	  If, however, the manual entry	is a locally added,
	  unformatted nroff(1) source, the entry will be formatted
	  using	psroff(1) and sent to the printer.  The	environment
	  variable TROFF may be	used to	specify	another	formatting
	  program other	than psroff (see the discussion	on ENVIRONMENT
	  below.  If the BSD lpr(1) printing facility is used, the
	  TCAT and NCAT	environment variables should be	set to send
	  the output to	lpr instead of lp.

     -T	macropackage
	  The given nroff(1) macro package will	be used	for formatting
	  unformatted manual entries.  By default,



								Page 3






MAN(1)									MAN(1)



	  /usr/lib/tmac/tmac.an	is used.

     -k	keyword	  Print	the manual entry summaries which contain the given
	  keywords.  The summaries are gotten from the whatis
	  database.  (See also apropos(1).)

     -f	filename  Print	the manual entry summaries which might pertain to the
	  given	filenames.  Any	leading	pathname components are
	  stripped from	the filename before the	filename is matched
	  against the summaries.  The summaries	are gotten from	the
	  whatis database.  (See also whatis(1).)

     -W		  is normally used only	by the makewhatis(1m) command to build
	  the whatis and apropos databases.

     -r		  Treat	specified names	as regular expressions for searches.
	  The regular expressions handled are those supported by
	  regex(3X).

ENVIRONMENT
     MANPATH  If set, MANPATH overrides	the default manual entry search	path.
      MANPATH is a colon-separated list	of directories where manual
      subdirectories may be found.  (See the discussion	of -M.)	 -M
      and -d will override MANPATH.

     LANG     If set, then for each directory to be searched (as determined by
      the -M option, the MANPATH variable, or the default search
      path), an	additional directory is	constructed and	searched which
      has the value of the LC_MESSAGES locale catagory appended	to it.
      These language specific directories are searched before the
      corresponding generic directory.	LC_MESSAGES may	be set either
      in the environment or will automatically be set based on the
      setting of the LANG variable (see	environ(5)).

     PAGER and MANPAGER
      If set, PAGER and	MANPAGER specify a program for interactively
      displaying the output from man.  MANPAGER	will override PAGER so
      a	program	other than the user's standard paging program may be
      used for displaying man output.  If neither PAGER	or MANPAGER
      are set, the command "ul -b | more -s -f"	is used.  See ul(1)
      and more(1) for details on these options.

     TCAT     may be used to specify the command for printing or displaying
      unformatted (nroff/troff source) manual pages when the -t	option
      is selected.  If TCAT is not set,	the command "lp" is used.  For
      systems using the	BSD lpr(1) printing facility, TCAT should be
      set to "lpr".  If	a troff	formatting program which does not
      output PostScript	is used, TCAT should be	set to "lpr "
      where  specifies the proper printing for the troff
      output.





								Page 4






MAN(1)									MAN(1)



     NCAT     may be used to specify the command for printing or displaying
      preformatted manual pages	when the -t option is selected.	 If
      NCAT is not set, the command specified by	TCAT is	used.  It is
      only necessary to	set NCAT if TCAT is set	to "lpr	"
      where  specifies printing	of some	special	(non-ASCII)
      format.

     TROFF    may be used to specify a formatter to use	when the -t option is
      selected,	and unformatted	man pages are processed.  The command
      specified	by TROFF must output its results to the	standard
      output for TCAT to work.	If TROFF is not	set, the command
      "psroff -t" is used.

     NROFF    Similar to TROFF above, used when	the -t option is not
      specified.

FILES
     /usr/share/catman			 root directory	of on-line reference
				 manual	entry tree
     /usr/share/catman/whatis		 table of contents and keyword
				 database
     /usr/share/catman/u_man/cat[1,6]/*	 user manual pages
     /usr/share/catman/a_man/cat[1,4,7]/*
				 system	administrator manual pages
     /usr/share/catman/p_man/cat[2-5]/*	 programmer manual pages
     /usr/share/catman/g_man/cat3/*	 Graphics Library manual pages
     /usr/share/catman/local/cat[1-8lnop]/*
				 local pre-formatted manual entries
     /usr/catman/local/man[1-8lnop]/*	 local unformatted nroff(1) source
				 manual	entries
     /usr/share/man/*			 additional unformatted	manual pages
     /usr/lib/tmac/tmac.an		 default macro package used for
				 formatting manual entries (contained
				 in the	Documentor's Work Bench
				 software option)

SEE ALSO
     apropos(1), col(1), compress(1), csh(1), eqn(1), grep(1), lp(1), lpr(1),
     makewhatis(1M), more(1), neqn(1), nroff(1), pack(1), pcat(1), psroff(1),
     sh(1), tbl(1), troff(1), ul(1), whatis(1),	zcat(1), regex(3X), ascii(5),
     environ(5), man(5), term(5).

CAVEATS
     apropos (man -k) and whatis (man -f) require that the whatis database be
     kept up to	date by	running	makewhatis(1M) after installing	or removing
     software from the system.	If the whatis database is not kept up to date,
     apropos (man -k) and whatis (man -f) will not find	entries	for new	manual
     pages and will erroneously	refer to manual	pages which no longer exist on
     the system.






								Page 5






MAN(1)									MAN(1)



     The /usr/share/catman directories have all	been processed by nroff(1).
     AT&T does not allow Silicon Graphics, Inc.	to ship	the nroff(1) sources
     for manual	pages.

     To	format locally added, unformatted manual pages,	man requires nroff(1),
     tbl(1), and neqn(1) or eqn(1) and psroff(1) with the -t option; these are
     contained in the Documentor's Work	Bench software option.	If they	are
     not found in the search path, a message to	this effect will be printed
     once per invocation of man, and any unformatted man pages will be
     skipped.  psroff and nroff	many be	overridded with	environment variables
     (see above), but the others may not; they must exist somewhere in the
     search path.  Manual pages	may be pre-formatted on	systems	which have
     nroff, et al, and the resulting formatted versions	may be installed on
     IRISes which do not have the Documentor's Work Bench.  To create pre-
     formatted manual pages, use the commands:


  neqn mymanpage.1 | tbl | nroff -man >	mymanpage
  pack -f mymanpage

     The resulting mymanpage.z file may	be copied into the appropriate
     /usr/local/man/cat[1-8] directory.

     The command psroff(1) used	by the -t option requires the Laser Printer
     Support software option.

     man will not locate manual	pages in directories with names	containing a
     period (.).

     man may produce some extra	matches	if man page names have a period	(.) in
     them, as it matches up to a period, assuming the rest is a	suffix.
























								Page 6






MAN(5)									MAN(5)



NAME
     man - macros for formatting entries in this manual

SYNOPSIS
     nroff -man	files

     troff -man	[ -rs1 ] [ -rv2	] files

DESCRIPTION
     These troff(1) macros are used to lay out the format of the entries of
     this manual.  These macros	are used by the	man(1) command.

     The default page size is 8.5"x11",	with a 6.5"x10"	text area; the -rs1
     option reduces these dimensions to	6"x9" and 4.75"x8.375",	respectively;
     this option (which	is not effective in nroff) also	reduces	the default
     type size from 10-point to	9-point, and the vertical line spacing from
     12-point to 10-point.  The	-rV2 option may	be used	to set certain
     parameters	to values appropriate for certain Versatec printers:  it sets
     the line length to	82 characters, the page	length to 84 lines, and	it
     inhibits underlining; this	option should not be confused with the -Tvp
     option of the man(1) command, which is available at some UNIX System
     sites.

     Any text argument below may be one	to six ``words''.  Double quotes ("")
     may be used to include blanks in a	``word''.  If text is empty, the
     special treatment is applied to the next line that	contains text to be
     printed.  For example, .I may be used to italicize	a whole	line, or .SM
     followed by .B to make small bold text.  By default, hyphenation is
     turned off	for nroff, but remains on for troff.

     Type font and size	are reset to default values before each	paragraph and
     after processing font- and	size-setting macros, e.g., .I, .RB, .SM.  Tab
     stops are neither used nor	set by any macro except	.DT and	.TH.

     Default units for indents in are ens.  When in is omitted,	the previous
     indent is used.  This remembered indent is	set to its default value (7.2
     ens in troff, 5 ens in nroff-this corresponds to 0.5" in the default page
     size) by .TH, .P, and .RS,	and restored by	.RE.

     .TH t s c n  Set the title	and entry heading; t is	the title, s is	the
	  section number, c is extra commentary, e.g., ``local'', n is
	  new manual name.  Invokes .DT	(see below).
     .SH text	  Place	subhead	text, e.g., SYNOPSIS, here.
     .SS text	  Place	sub-subhead text, e.g.,	Options, here.
     .B	text	  Make text bold.
     .I	text	  Make text italic.
     .SM text	  Make text 1 point smaller than default point size.
     .RI a b	  Concatenate roman a with italic b, and alternate these two
	  fonts	for up to six arguments.  Similar macros alternate
	  between any two of roman, italic, and	bold:
	       .IR   .RB   .BR	 .IB   .BI




								Page 1






MAN(5)									MAN(5)



     .P		  Begin	a paragraph with normal	font, point size, and indent.
	  .PP is a synonym for .P.
     .HP in	  Begin	paragraph with hanging indent.
     .TP in	  Begin	indented paragraph with	hanging	tag.  The next line
	  that contains	text to	be printed is taken as the tag.	 If
	  the tag does not fit,	it is printed on a separate line.
     .IP t in	  Same as .TP in with tag t; often used	to get an indented
	  paragraph without a tag.
     .RS in	  Increase relative indent (initially zero).  Indent all
	  output an extra in units from	the current left margin.
     .RE k	  Return to the	kth relative indent level (initially, k=1; k=0
	  is equivalent	to k=1); if k is omitted, return to the	most
	  recent lower indent level.
     .PM m	  Produces proprietary markings; where m may be	P for PRIVATE,
	  N for	NOTICE,	BP for BELL LABORATORIES PROPRIETARY, or BR
	  for BELL LABORATORIES	RESTRICTED.
     .DT	  Restore default tab settings (every 7.2 ens in troff,	5 ens
	  in nroff).
     .PD v	  Set the interparagraph distance to v vertical	spaces.	 If v
	  is omitted, set the interparagraph distance to the default
	  value	(0.4v in troff,	1v in nroff).

     The following strings are defined:

     \*R	  ``(Reg.)''  in nroff,	``Registered'' symbol in troff(1).
     \*S	  Change to default type size.
     \*(Tm	  Trademark indicator.

     The following number registers are	given default values by	.TH:

     IN		  Left margin indent relative to subheads (default is 7.2 ens
	  in troff, 5 ens in nroff).
     LL		  Line length including	IN.
     PD		  Current interparagraph distance.

CAVEATS
     In	addition to the	macros,	strings, and number registers mentioned	above,
     there are defined a number	of internal macros, strings, and number
     registers.	 Except	for names predefined by	troff and number registers d,
     m,	and y, all such	internal names are of the form XA, where X is one of
     ),	], and }, and A	stands for any alphanumeric character.

     If	a manual entry needs to	be preprocessed	by cw(1), eqn(1) (or neqn),
     and/or tbl(1), it must begin with a special line (described in man(1)),
     causing the man command to	invoke the appropriate preprocessor(s).

     The programs that prepare the Table of Contents and the Permuted Index
     for this Manual assume the	NAME section of	each entry consists of a
     single line of input that has the following format:






								Page 2






MAN(5)									MAN(5)



  name[, name, name ...] \- explanatory	text

     The macro package increases the inter-word	spaces (to eliminate
     ambiguity)	in the SYNOPSIS	section	of each	entry.

     The macro package itself uses only	the roman font.	 Of course, if the
     input text	of an entry contains requests for other	fonts (e.g., .I, .RB,
     \fI), the corresponding fonts must	be mounted.

EXAMPLE
  nroff	-man man.5

     to	nroff this manual section.

FILES
     /usr/lib/tmac/tmac.an
     /usr/lib/macros/cmp.[nt].[dt].an
     /usr/lib/macros/ucmp.[nt].an
     /usr/man/man0/skeleton

SEE ALSO
     man(1), nroff(1), troff(1).

BUGS
     If	the argument to	.TH contains any blanks	and is not enclosed by double
     quotes (""), there	will be	bird-dropping-like things on the output.





























								Page 3