Difference between revisions of "Manual"

From Hackepedia
Jump to navigationJump to search
m (→‎Searching in a man page: the funny n (next) key.)
 
(22 intermediate revisions by 5 users not shown)
Line 1: Line 1:
Most UNIX systems have online manual pages.  The types of manpages have sections which they are grouped in.  Here is the layout of [[BSD]]:
+
== About ==
  
  
section 1
+
Most [[UBO]]s have manual pages. 
  
general commands (tools and utilities)
+
MAN(1)                     OpenBSD Reference Manual                    MAN(1)
 +
NAME
 +
    man - display the on-line manual pages
 +
SYNOPSIS
 +
    man [-achw] [-C file] [-M path] [-m path] [-S subsection] [-s section]
 +
        [section] name [...]
 +
    man -f command
 +
    man -k keyword
 +
DESCRIPTION
  
section 2
+
The types of manpages have sections which they are grouped in.  Here is the manual page layout of [[BSD]]:
  
system calls and error numbers
+
;Section 1 : General commands (tools and utilities)
 +
; Section 2 : System calls and error numbers
 +
; Section 3 : Library functions, especially for C and Tk
 +
; Section 4  : Special files and hardware support
 +
; Section 5 : File formats, especially configuration files
 +
; Section 6 : Games
 +
; Section 7 : Miscellaneous information pages
 +
; Section 8 : System maintenance and operation commands
 +
; Section 9 : Kernel internals
  
section 3
+
When someone tells you to run "man 6 tetris", that means that you should read the tetris manpage found in section 6 of the manpages.  Sometimes the same manpage name exists, but in different sections. One example is the fstat manpage it exists in sections 1 and 2.  The lower number sections take precedence over higher numbered sections.  Thus, to see the manpage for fstat in section 2 you would type:
 +
$ man 2 fstat
 +
 
 +
Similarely functions, [[syscall]]s or commands are sometimes mentioned with the section of manpages in brackets behind them like so:  '''fstat(2)''', you'll see this mentioned a lot in this wiki.
 +
 
 +
Simple example to type at your [[shell]] prompt of most [[UBO]]s:
 +
$ man 1 intro
 +
This brings up the man page for intro(1). You can use your spacebar to go down a page, and "q" for quit.
  
the C libraries
+
== Installing manpages ==
  
section 4
+
On [[Debian]] based GNU/[[Linux]]:
  
special files and hardware support
+
$ sudo apt-get install manpages
  
section 5
+
== Creating windex ==
  
file formats
+
If you're looking for a man page and get the following:
 +
# man -k snoop
 +
/usr/share/man/windex: No such file or directory
  
section 6
+
It means you have yet to create your Index:
 +
# [[variables|/usr/bin/catman]] -w
 +
#
  
the games
+
== Searching for Manual Pages ==
  
section 7
+
It is possible to do a keyword search in the manpage system.
  
miscellaneous information pages
+
$ man -k filesystem
 +
OpenBSD::Vstat (3p) - virtual filesystem for pkg_add(1) simulations
 +
dump (8) - filesystem backup
 +
fstab (5) - static information about the filesystems
 +
...
  
section 8
+
Another command synonymous to man -k is apropos:
  
system maintenance and operation commands
+
$ apropos archiver
 +
tar (1) - tape archiver
  
section 9
+
Do notice that the section of the manpage is displayed in the keyword search, this is to ease viewing the particular manpage. 
  
kernel internals
+
<code>$MANPATH</code> is used, unless something else is explicitly specified.
  
 +
== Location of Manual Pages ==
  
When someone says to you "man 6 tetris" he means that you should read the tetris manpage in section 6 of the manpagesSometimes the same manpage name exists, but in different sections. One example is the fstat manpage it exists in sections 1 and 2. To see the manpage for fstat in section 2 you would type  
+
In [[BSD]] the default manual pages are located in /usr/share/man.  This can be changed with the MANPATH [[environment variable]]:
  $ man 2 fstat
+
 
 +
$ export MANPATH=/usr/local/man
 +
$ man ls
 +
man: no entry for ls in the manual.  
 +
$ unset MANPATH
 +
$ man ls
 +
LS(1)                      OpenBSD Reference Manual                      LS(1)
 +
  ...
 +
 
 +
Another manpage section can be added on to the current MANPATH:
 +
 
 +
$ export MANPATH=/usr/share/man:/usr/local/man
 +
 
 +
 
 +
== Searching in a man page ==
 +
 
 +
Often you will want to search a man page you are viewing for a particular keyword. You can preceed this search word with a "/". If I wanted to see what mediaopt(ions) my sis [[NIC]] has I could do
 +
 
 +
/mediaopt
 +
 
 +
while reading the sis(4) manpage I have on my system. If the first result is not what I want, I don't have to type the full search word after the first time, I can simply use
 +
 +
  /
 +
 
 +
which is to "find another instance".  This btw can also be achieved by typing "n" (lowercase) to search forward and "N" (uppercase) to search backwards, at least on [[FreeBSD]].

Latest revision as of 02:20, 26 September 2012

About

Most UBOs have manual pages.

MAN(1)                     OpenBSD Reference Manual                     MAN(1)
NAME
    man - display the on-line manual pages
SYNOPSIS
    man [-achw] [-C file] [-M path] [-m path] [-S subsection] [-s section]
        [section] name [...]
    man -f command
    man -k keyword
DESCRIPTION

The types of manpages have sections which they are grouped in. Here is the manual page layout of BSD:

Section 1
General commands (tools and utilities)
Section 2
System calls and error numbers
Section 3
Library functions, especially for C and Tk
Section 4
Special files and hardware support
Section 5
File formats, especially configuration files
Section 6
Games
Section 7
Miscellaneous information pages
Section 8
System maintenance and operation commands
Section 9
Kernel internals

When someone tells you to run "man 6 tetris", that means that you should read the tetris manpage found in section 6 of the manpages. Sometimes the same manpage name exists, but in different sections. One example is the fstat manpage it exists in sections 1 and 2. The lower number sections take precedence over higher numbered sections. Thus, to see the manpage for fstat in section 2 you would type:

$ man 2 fstat

Similarely functions, syscalls or commands are sometimes mentioned with the section of manpages in brackets behind them like so: fstat(2), you'll see this mentioned a lot in this wiki.

Simple example to type at your shell prompt of most UBOs:

$ man 1 intro

This brings up the man page for intro(1). You can use your spacebar to go down a page, and "q" for quit.

Installing manpages

On Debian based GNU/Linux:

$ sudo apt-get install manpages

Creating windex

If you're looking for a man page and get the following:

# man -k snoop
/usr/share/man/windex: No such file or directory

It means you have yet to create your Index:

# /usr/bin/catman -w 
#

Searching for Manual Pages

It is possible to do a keyword search in the manpage system.

$ man -k filesystem
OpenBSD::Vstat (3p) - virtual filesystem for pkg_add(1) simulations
dump (8) - filesystem backup
fstab (5) - static information about the filesystems
...

Another command synonymous to man -k is apropos:

$ apropos archiver
tar (1) - tape archiver

Do notice that the section of the manpage is displayed in the keyword search, this is to ease viewing the particular manpage.

$MANPATH is used, unless something else is explicitly specified.

Location of Manual Pages

In BSD the default manual pages are located in /usr/share/man. This can be changed with the MANPATH environment variable:

$ export MANPATH=/usr/local/man
$ man ls
man: no entry for ls in the manual. 
$ unset MANPATH
$ man ls
LS(1)                      OpenBSD Reference Manual                      LS(1)
...

Another manpage section can be added on to the current MANPATH:

$ export MANPATH=/usr/share/man:/usr/local/man


Searching in a man page

Often you will want to search a man page you are viewing for a particular keyword. You can preceed this search word with a "/". If I wanted to see what mediaopt(ions) my sis NIC has I could do

/mediaopt

while reading the sis(4) manpage I have on my system. If the first result is not what I want, I don't have to type the full search word after the first time, I can simply use

/

which is to "find another instance". This btw can also be achieved by typing "n" (lowercase) to search forward and "N" (uppercase) to search backwards, at least on FreeBSD.