Using Man Pages in the Solaris OS

 
By Ifeyinwa Okoye, November 17, 2005  
Abstract: This overview of man pages covers the basics, for example, how information on man pages is organized and how to set up access to the man pages of newly installed software.
Contents
 
Introduction
Finding Information on a Command or Function
Commands to Execute When Viewing a Man Page
Organization of Information on a Man Page
Setting Up Access to the Man Page of a Newly Installed Software Package
Conclusion
References
 
Introduction

Man pages (short for manual pages) are the official collection of quick reference sheets for the UNIX platform. These pages provide quick access to libraries, commands, and functions. Man pages for the Solaris Operating System can be browsed online and can also be accessed from a terminal window by typing:

man <command/function>

All man page libraries are organized into sections. The numerals in parentheses that follow the man page name indicate the section where that man page is located. The man pages for the Solaris OS are organized as follows:

Finding Information on a Command or Function

From the command line, you can run the following commands to find information about a command or function:

whereis <command/function>
Displays the location of the command/function.
whatis <command/function>
Displays a one-line summary of the command/function.
which <command/function>
Displays the pathname and alias of a command/function.
man <command/function>
Displays detailed information about the command/function.
man <man>
Displays information about the man pages.
Commands to Execute When Viewing a Man Page

When you type man to view a man page, the man page information is displayed one screen at a time if there is too much information for the window. You can use the following commands to display the man page:

<space>
Displays more information by current screen size.
<return>
Displays more information one line at a time.
/<regular expression>
Finds the next occurrence of the regular expression in the file.
b
Goes back to the previous page.
f
Goes forward to the next page.
:f
Displays current file name and line number.
q
Returns to the console/exit from more.
h
Short for "help." Displays all the available commands.
Organization of Information on a Man Page

Each man page is organized into different sections, which provide specific information about the library, command, or function. The main sections are as follows:

NAME
Gives the name of the command or function and a short description of what it does.
SYNOPSIS
Shows the syntax of the command or function. The full path is shown if the file or command does not exist in the standard path.
[]
Options or arguments in these enclosed brackets are optional.
..
These ellipses mean that the previous argument can have several values or can be repeated several times.
|
Only one of the arguments separated by this character can be specified at a time.
{ }
Every option or argument enclosed within these braces must be treated as a unit.
DESCRIPTION
Defines the functionality and behavior.
OPTIONS
Lists the command options, what they do, their possible arguments, and default values, if any.
OPERANDS
Lists operands and describes how they affect the actions of the command.
OUTPUT
Describes the types of output generated by the command.
RETURN VALUES
Lists and describes return values for functions on the man page.
ERRORS
Lists error codes the function can generate and describes the conditions that cause each error.
USAGE
Lists special rules, features, and commands that require in-depth explanations under subcategories like commands, modifiers, variables, expressions, and input grammar.
EXAMPLES
Shows how to use a command or function.
ENVIRONMENT VARIABLES
Lists any environment variables that the command or function affects and a brief description of the effect.
EXIT STATUS
Lists the values the command returns to the calling program and the conditions that cause these values to be returned.
FILES
Lists and briefly describes all file names referred to by the man page.
ATTRIBUTES
Defines attribute types and their corresponding values. Typing <man -s 5 attributes> in a terminal window will give you detailed information about this section.
Architecture
Specifies the processor or specific hardware.
Availability
Specifies the software package that contains the command or component being described.
CSI (Code Set Independence)
Specifies the dependence of OS utilities and libraries on code sets. OS utilities and libraries that are free of dependencies on the properties of any code sets are said to be CSI enabled.
Interface Stability
"Stable" means it is standardized. "Unstable" means the interface might change in later releases.
MT-Level
Describes how safe it is to use this command in a multithreaded application. It could be Unsafe, Safe, MT-Safe, async-signal safe, MT-Safe with Exceptions, Safe with Exceptions, Fork1-safe, or Cancel-Safe.
SEE ALSO
Lists references to other man pages, in-house documentation, and outside publication.
DIAGNOSTICS
Lists diagnostic messages with a brief explanation of the condition causing the error.
WARNINGS
Describes special conditions that could seriously affect your working conditions.
NOTES
Lists additional information that does not belong anywhere else.
BUGS
Describes known bugs and wherever possible, suggests workarounds.
Setting Up Access to the Man Page of a Newly Installed Software Package

Man pages are provided for all software that is bundled with the operating system. The path to man pages for software that is not bundled with the OS must be added to the MANPATH variable. Let's use Sun Studio software as an example and assume the installation directory for Sun Studio Software is usr/local/sunstudio. Let's place the Sun Studio software man page directory in usr/local/sunstudio/man. Setting up the MANPATH variable takes the following steps:

1. Check if the MANPATH variable has been set by typing $echo MANPATH. If you see undefined variable or an empty line, then the MANPATH variable is not set.

For C shell (csh) users:

Your prompt is machine-name% or machine-name#. If your MANPATH variable has not been set, edit your .cshrc file and add the following:

setenv MANPATH /usr/local/sunstudio/man:/usr/share/man 

If your MANPATH variable has been set, edit your .cshrc file and add the following:

setenv MANPATH /usr/local/sunstudio/man:$MANPATH

For Bourne or Korn shell users:

Your prompt is $ or #.

Edit the .profile file in your home directory and add this:

MANPATH=/usr/local/sunstudio/man:${MANPATH:=/usr/share/man}
export MANPATH

2. Save the file you edited ( .profile or .cshrc).

3. For the changes to take effect, you have to restart your computer or reinitialize every open terminal by executing the appropriate command.

For C shell users:

source ~/.cshrc

For Bourne and Korn shell users:

.~/.profile      

Conclusion

This article describes how to find information on commands, functions, and files using the man pages in the Solaris OS. In addition, the article explains the organization of man page sections, how individual man pages are set up, how to navigate within a man page, and how to set up the access for newly installed software packages.

References
About the Author
Ifeyinwa Okoye is an intern at Sun Microsystems for the Sun Developer Network.