Man Pages

The OpenSolaris reference manual (man) pages contain a wealth of information, including much more than just how to use a given command. For example, there's also documentation on file formats, system calls and library functions as well as overview documentation on OpenSolaris technologies like RBAC, SMF and Zones. So getting comfortable with using the man pages will pay dividends.

There are over 19,000 man pages available (which should give you a new appreciation for the amount of work that goes into localizing the system) and they're found based on the MANPATH environment variable. Here's the default setting:

bleonard@os200906:~$ echo $MANPATH
/usr/gnu/share/man:/usr/share/man:/usr/X11/share/man

With the bulk of the man pages found under /usr/share/man.

Note, OpenSolaris has it's own version of most, if not all, of the GNU man pages. Generally, since you're probably running the GNU version of these common utilities, you'll probably want to see the GNU version of the man page, which is what you get based on the MATNPATH setting above. However, if you do want to see the OpenSolaris version, you have to specify the path to the man page. For example:

man -M /usr/share/man ls 

Another confusing aspect of man pages is that the pages are divided into sections. A good example of this is the pkg command, where you'll often see references to pkg(1) and pkg(5). pkg(1) explains how to use the pkg command while pkg(5) explains the Image Packaging System in general.

There are over 200 different sections, but they roughly break down into the following 9 categories:

1 - User Commands
1M - System Administration Commands
2 - System Calls
3 - Library Functions
4 - File Formats
5 - Standards, Environments, and Macros (general documentation)
6 - Games/Demos
7 - Device and Network Interfaces
8 - Maintenance Procedures
9 - Device Driver Interfaces

For more details on the categories see the OpenSolaris Reference Manual Collection.

If the same man page has multiple sections, you'll be presented with the first man page found starting with section 1, which is generally what you're after (User Commands). So for example, typing man pkg, will return pkg(1). To see the man page for pkg(5), you have to specify the section to the man command as follows:

man -s 5 pkg

Or as Shawn points out in the comments below:

man pkg.5

To see all man pages for a given name:

bleonard@os200906:~$ man -l intro
intro (1)	-M /usr/share/man
intro (1m)	-M /usr/share/man
intro (2)	-M /usr/share/man
intro (3)	-M /usr/share/man
intro (7)	-M /usr/share/man
intro (9)	-M /usr/share/man
intro (9e)	-M /usr/share/man
intro (9f)	-M /usr/share/man
intro (9s)	-M /usr/share/man
intro (4)	-M /usr/share/man
intro (5)	-M /usr/share/man

Some man pages can be very long, so learning to navigate around is also very beneficial. Some commands that I use frequently:


RETURN
 Line forward

SPACE
 Page forward

 /<pattern>  Search forward

 n
 Find next occurrence

 N
 Find previous occurrence

 g  Go to top

 G
 Go to bottom

 h
 Help

Oh yeah, man itself has a man page. So I guess I could have just told you to read the man(1) man page.

Comments:

You are so last-decade with the use of MANPATH and man -M...

Why not just do "man /usr/bin/ls"?

http://hub.opensolaris.org/bin/view/Community+Group+on/2008051501

Here's the relevant section from the OpenSolaris man(1) page:

http://docs.sun.com/app/docs/doc/819-2239/man-1?a=view#Search%20Path

Posted by Mike Gerdts on February 10, 2010 at 04:10 PM GMT #

A little known syntax that also works is:

man pkg.1

or:

man pkg.5

...avoids the need to type the -s.

Posted by Shawn on February 10, 2010 at 06:19 PM GMT #

Shawn, thanks for your tip. I've incorporated it above.

Mike, also thanks for your tip. I'm curious how this approach works for man pages not tied to a command, such as a file format description? Also, it doesn't seem ubiquitous. For example, `man /opt/DTT/iosnoop` doesn't work while `man -M /opt/DTT/Man iosnoop` does.

Posted by Brian Leonard on February 11, 2010 at 07:45 AM GMT #

File formats aren't handled by my approach. It is really about helping people find the man page for the command that is in their PATH. Thus, if a person has /usr/gnu/bin at the front of their path, he should see the GNU ls man page instead of the Solaris ls man page.

/opt/DTT/Man is not handled automatically because of the upper-case M. The DTrace Toolkit is in the slim minority with its use of upper-case for the first letter of directory names. While I believe that it would be pretty easy to change the code to handle this oddball case (http://src.opensolaris.org/source/xref/onnv/onnv-gate/usr/src/cmd/man/src/man.c#211), I think that the right solution is for the OpenSolaris installation of DTrace Toolkit to fall in line with the rest of the distro WRT case in directory names.

Posted by Mike Gerdts on February 11, 2010 at 07:57 AM GMT #

All of your approaches assume, that a sysadmin is running nothing but OpenSolaris.

The reality is that sysadmins around the world are running heterogeneous environments, composed of different types of UNIXes.

For example, the man ls.1 syntax works on Solaris (SunOS 5.x) only -- it does not work on other UNIXes and cannot be relied upon.

The extensions to MANPATH detection which Mike put in are OpenSolaris only -- no other UNIX implements them.

(The cleaner approach would have been to implement /etc/MANPATH and /etc/PATH, like HP-UX does.)

Point: these hints are of very limited value, if any, and are actually detrimental for people not experienced in UNIX. They should not learn these OpenSolaris-only shortcuts until they understand the above mentioned consequences.

Posted by UX-admin on February 11, 2010 at 11:11 AM GMT #

How "man" can be configured to handle PgUp and PgDwn to go up and down a page? It works out of the box in most Linux distros, but not by default on OpenSolaris.

Posted by shmerl on February 12, 2010 at 08:49 AM GMT #

Post a Comment:
  • HTML Syntax: NOT allowed
About

The Observatory is a blog for users of Oracle Solaris. Tune in here for tips, tricks and more as we explore the Solaris operating system from Oracle.

Connect with Oracle Solaris:


Search

Archives
« April 2014
SunMonTueWedThuFriSat
  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
   
       
Today