|
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
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:
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:
- man pages section 1: User Commands -- Contains all non-administration commands on the system. The Intro(1) man page provides information on man page command syntax for users, guidelines for developers who are designing new man pages, and an explanation of the subdivisions within Section 1.
-
man pages section 1M: System Administration Commands -- Contains commands for system maintenance and other administrative purposes.
-
man pages section 2: System Calls -- Contains prototypes and descriptions for the various system calls that can be made in the Solaris OS. Focuses on calls that directly invoke UNIX system primitives. The Intro(2) man page provides a list of all possible error returns from system calls as well as a glossary of system call terminology.
- man pages section 3: Libraries -- The Intro(3) man page provides the complete organization of the Section 3 libraries, a brief explanation of multithreaded applications, and a few basic definitions.
- man pages section 4: File Formats -- Describes file formats. The C structure declarations for the file formats are provided where applicable.
-
man pages section 5: Standards, Environments, and Macros -- Contains miscellaneous information. The Intro(5) man page describes the topics in this section.
-
man pages section 6: Demos -- Contains games and demos.
-
man pages section 7: Device and Network Interfaces -- Contains various device and network interfaces available on the system. The Intro(7) man page explains how this section is organized.
- man pages section 9 -- Has different volumes.
-
DDI and DKI Driver Entry Points -- Contains information on the Device Driver Interface and the Driver-Kernel Interface (DDI/DKI), which are recommended for device drivers in the Solaris kernel. The Intro(9E) man page provides an overview of driver entry points.
-
DDI and DKI Kernel Functions -- Contains kernel functions that are available for use by device drivers. The Intro(9F) man page presents summaries of the functions, organized into STREAMS and non-STREAMS functions.
-
DDI and DKI Properties and Data Structures -- Contains data structures that are used by drivers to share information between the driver and the kernel. The Intro(9S) man page presents summaries of the structures, organized into STREAMS and non-STREAMS structures.
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:
For Bourne and Korn shell users:
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
Ifeyinwa Okoye is an intern at Sun Microsystems for the Sun Developer Network.
|
|
Print-friendly Version
