Linux provides two very powerful tools for accessing the documentation. These tools are man and info. ‘man’ has been around for several decades and ‘info’ was introduced couple of years back.
‘man is short form of ‘manual’. ‘man’ is certainly good for quickly searching the items, however it lacks structure and linking. This is where, info comes in. ‘info’ offers better structure for the documentation and allows documentation to be hyperlinked.
This article provides the detailed explanation of man and info documentation in Linux.
Linux man Command
In Linux, man command is used to access the manual pages for thousands of utilities. The default location for the man pages is /usr/share/man.
# ls -l /usr/share/man
total 856
drwxr-xr-x 5 root root 4096 Aug 2 15:00 bg
drwxr-xr-x 5 root root 4096 Jul 13 2006 cs
drwxr-xr-x 5 root root 4096 Aug 2 15:00 da
drwxr-xr-x 5 root root 4096 Jul 13 2006 de
drwxr-xr-x 5 root root 4096 Aug 2 15:00 el
drwxr-xr-x 14 root root 4096 Jul 13 2006 en
drwxr-xr-x 5 root root 4096 Aug 2 15:00 es
drwxr-xr-x 5 root root 4096 Aug 2 15:00 fi
drwxr-xr-x 6 root root 4096 Jul 13 2006 fr
and more ...
Following is the syntax for viewing the manual pages using the man command.
Syntax:
# man [Manual_Section] Program_Name
Argument, Manual_Section is optional. If this argument is not specified then the lowest available section number gets printed first. Doh! I didn’t explain about the manual sections yet. Ok, let’s do that first and then we shall look at some of the examples.
Linux man pages are divided into sections. There are total 8 sections each covering a specific subject area. Following is the list of standard man page sections.
Section Subject 1 User tools 2 System calls 3 C library calls 4 Device driver information 5 Configuration files 6 Games 7 Packages 8 System tools
Other than these, on some systems following sections are available as well,
Section Subject 0 C library headers file 9 Kernel routines n Tcl/tk keywords x The X Window System
While referring to the Linux documentation on the internet and other information sources you will often encounter the references to the command followed by a number in parenthesis. For example, printf(1) or lsof(8) etc. The number in parenthesis represents the manual page section. Following is an example documentation from the web.
This documentation provides the lsof command information contained in the maual section 8.
Ok, so now we have got some idea about the Linux man page sections. Let’s go back to the man page command.
As mentioned earlier, Linux man command can be used to view the manual pages of specific program/utility. You can also view a specific section of the manual by mentioning the section number. By default, man displays the content of lowest available section.
You can view the available section pages for a utility by using –f option with man command. Let’s find out the manual pages available for printf.
# man -f printf
printf (1) - format and print data
printf (1p) - write formatted output
printf (3) - formatted output conversion
printf (3p) - print formatted output
printf [builtins] (1) - bash built-in commands, see bash(1)
You can see that the printf manual contains section 1 and section 3.
Let’s take another example of ls command.
# man -f ls
ls (1) - list directory contents
ls (1p) - list directory contents
Let’s view the manual page of printf
# man printf
PRINTF(1) User Commands PRINTF(1)
NAME
printf - format and print data
SYNOPSIS
printf FORMAT [ARGUMENT]...
printf OPTION
DESCRIPTION
Print ARGUMENT(s) according to FORMAT.
--help display this help and exit
--version
output version information and exit
FORMAT controls the output as in C printf. Interpreted sequences are:
and more ...
You can see that by default the lowest manual section for printf is displayed.
printf is also a function in the c standard library. Manual page for C library function printf can be viewed by specifically providing the section number ‘3’ with man command.
# man 3 printf
PRINTF(3) Linux Programmer’s Manual PRINTF(3)
NAME
printf, fprintf, sprintf, snprintf, vprintf, vfprintf, vsprintf, vsnprintf - formatted output conversion
SYNOPSIS
#include
int printf(const char *format, ...);
int fprintf(FILE *stream, const char *format, ...);
int sprintf(char *str, const char *format, ...);
int snprintf(char *str, size_t size, const char *format, ...);
and more ...
Let’s check out the content of section 8 for printf. We already know that section 8 is not available for printf. However, let’s see what happens when we try to view the section 8.
# man 8 printf
No entry for printf in section 8 of the manual
As expected, man command informs that printf manual doesn’t contain section 8.
Linux Info Command
Another common form of Linux documentation is created using texinfo tool which can be accessed by using info command. Default location of the info pages in Linux is /usr/share/info.
# ls -l /usr/share/info
total 11380
-rw-r--r-- 1 root root 10441 Jul 16 2008 accounting.info.gz
-rw-r--r-- 1 root root 15328 Dec 11 2007 ada-mode.gz
-rw-r--r-- 1 root root 14208 Nov 18 2008 annotate.info.gz
-rw-r--r-- 1 root root 193788 Oct 29 2008 as.info.gz
-rw-r--r-- 1 root root 85141 Jul 12 2006 aspell.info.gz
-rw-r--r-- 1 root root 178356 Oct 13 2006 autoconf.info.gz
-rw-r--r-- 1 root root 91080 Jul 12 2006 automake.info-1.gz
-rw-r--r-- 1 root root 34494 Jul 12 2006 automake.info-2.gz
-rw-r--r-- 1 root root 2168 Jul 12 2006 automake.info.gz
-rw-r--r-- 1 root root 9917 Dec 11 2007 autotype.gz
-rw-r--r-- 1 root root 110635 Oct 21 2008 bash.info.gz
-rw-r--r-- 1 root root 12083 Jul 13 2006 bc.info.gz
-rw-r--r-- 1 root root 43730 Oct 29 2008 binutils.info.gz
and more ...
Let’s use the info command to view the documentation of printf.
# man printf
File: coreutils.info, Node: printf invocation, Next: yes invocation, Prev: echo invocation, Up: Printing text
15.2 `printf': Format and print data
====================================
`printf' does formatted printing of text. Synopsis:
printf FORMAT [ARGUMENT]...
`printf' prints the FORMAT string, interpreting `%' directives and
`\' escapes to format numeric and string arguments in a way that is
mostly similar to the C `printf' function. The differences are as
follows:
* The FORMAT argument is reused as necessary to convert all the
given ARGUMENTs. For example, the command `printf %s a b' outputs
`ab'.
* Missing ARGUMENTs are treated as null strings or as zeros,
depending on whether the context expects a string or a number. For
example, the command `printf %sx%d' prints `x0'.
and more ...
A detailed guide on Linux info command can be found at http://www.gentoo.org/doc/en/info-guide.xml.
{ 0 comments… add one now }
{ 1 trackback }