Manual page (Unix) - AbsoluteAstronomy.com

Man pages are the extensive documentation that comes preinstalled with almost all substantial Unix

Unix

Unix is a multitasking, multi-user computer operating system originally developed in 1969 by a group of AT&T employees at Bell Labs, including Ken Thompson, Dennis Ritchie, Brian Kernighan, Douglas McIlroy, and Joe Ossanna...

and Unix-like

Unix-like

A Unix-like operating system is one that behaves in a manner similar to a Unix system, while not necessarily conforming to or being certified to any version of the Single UNIX Specification....

operating system

Operating system

An operating system is a set of programs that manage computer hardware resources and provide common services for application software. The operating system is the most important type of system software in a computer system...

s. The Unix command used to display them is man. Each page is a self-contained document.

Usage

To read a manual page for a Unix command, one can use

man

at a shell

Shell (computing)

A shell is a piece of software that provides an interface for users of an operating system which provides access to the services of a kernel. However, the term is also applied very loosely to applications and may include any software that is "built around" a particular component, such as web...

prompt: for example, "man ftp". In order to simplify navigation through the output, man generally uses the less

Less (Unix)

less is a terminal pager program on Unix, Windows, and Unix-like systems used to view the contents of a text file one screen at a time. It is similar to more, but has the extended capability of allowing both forward and backward navigation through the file...

terminal pager

Terminal pager

A terminal pager, or paging program, is a computer program used to view the contents of a text file moving down the file one line or one screen at a time. Some, but not all, pagers allow movement up a file. A popular cross-platform terminal pager is more. more can move forwards and backwards in...

.

Pages are traditionally referred to using the notation "name(section)": for example, . The same page name may appear in more than one section of the manual, as when the names of system call

System call

In computing, a system call is how a program requests a service from an operating system's kernel. This may include hardware related services , creating and executing new processes, and communicating with integral kernel services...

s, user command

Command (computing)

In computing, a command is a directive to a computer program acting as an interpreter of some kind, in order to perform a specific task. Most commonly a command is a directive to some kind of command line interface, such as a shell....

s, or macro packages

Troff macro

The troff typesetting system includes sets of commands called macros that are run before starting to process the document. These macros include setting up page headers and footers, defining new commands, and generally influencing how the output will be formatted.The command-line argument for...

coincide. Examples are and , or and .
The syntax for accessing the non-default manual section varies between different man implementations. On Linux and *BSD, for example, the syntax for reading is

man 3 printf

which searches for printf in section 3 of the man pages.

History

The UNIX Programmer's Manual was first published on November 3, 1971. The first actual man pages were written by Dennis Ritchie

Dennis Ritchie

Dennis MacAlistair Ritchie , was an American computer scientist who "helped shape the digital era." He created the C programming language and, with long-time colleague Ken Thompson, the UNIX operating system...

and Ken Thompson

Ken Thompson

Kenneth Lane Thompson , commonly referred to as ken in hacker circles, is an American pioneer of computer science...

at the insistence of Doug McIlroy in 1971. The troff macro

Troff macro

s used for man pages (-mm) were the general-purpose ones written by Ted Dolotta (later to be the first manager of USG and the principal author of the System III manual), with additions for the manuals. At the time, the availability of online documentation through the manual page system was regarded as a great advance. To this day, virtually every Unix command line application comes with its man page, and many Unix users perceive a lack of man pages as a sign of low quality; indeed, some projects, such as Debian

Debian

Debian is a computer operating system composed of software packages released as free and open source software primarily under the GNU General Public License along with other free software licenses. Debian GNU/Linux, which includes the GNU OS tools and Linux kernel, is a popular and influential...

, go out of their way to write man pages for programs lacking one.

Few alternatives to man have enjoyed much popularity, with the possible exception of GNU Project's

GNU Project

The GNU Project is a free software, mass collaboration project, announced on September 27, 1983, by Richard Stallman at MIT. It initiated GNU operating system development in January, 1984...

infoTexinfo
Texinfo is a typesetting syntax used for generating documentation in both on-line and printed form  with a single source file...

" system, an early and simple hypertext

Hypertext

Hypertext is text displayed on a computer or other electronic device with references to other text that the reader can immediately access, usually by a mouse click or keypress sequence. Apart from running text, hypertext may contain tables, images and other presentational devices. Hypertext is the...

system.
Also some Unix GUI

Graphical user interface

In computing, a graphical user interface is a type of user interface that allows users to interact with electronic devices with images rather than text commands. GUIs can be used in computers, hand-held devices such as MP3 players, portable media players or gaming devices, household appliances and...

applications (particularly those built using the GNOME

GNOME

GNOME is a desktop environment and graphical user interface that runs on top of a computer operating system. It is composed entirely of free and open source software...

and KDE

KDE

KDE is an international free software community producing an integrated set of cross-platform applications designed to run on Linux, FreeBSD, Microsoft Windows, Solaris and Mac OS X systems...

development environments) now provide end-user documentation in HTML

HTML

HyperText Markup Language is the predominant markup language for web pages. HTML elements are the basic building-blocks of webpages....

and include embedded HTML viewers such as yelp for reading the help within the application.

Usually the man pages are written in English. Translations into other languages can be also available on the system.

The default format of the man pages is troff

Troff

troff is a document processing system developed by AT&T for the Unix operating system.-History:troff can trace its origins back to a text formatting program called RUNOFF, written by Jerome H. Saltzer for MIT's CTSS operating system in the mid-1960s...

, with either the macro package man (appearance oriented) or on some systems mdoc

MDOC

MDOC can refer to:* Maine Department of Corrections* Michigan Department of Corrections* Mississippi Department of Corrections* Missouri Department of Corrections...

(semantic oriented). This makes it possible to typeset a man page to PostScript

PostScript

PostScript is a dynamically typed concatenative programming language created by John Warnock and Charles Geschke in 1982. It is best known for its use as a page description language in the electronic and desktop publishing areas. Adobe PostScript 3 is also the worldwide printing and imaging...

, PDF

Portable Document Format

Portable Document Format is an open standard for document exchange. This file format, created by Adobe Systems in 1993, is used for representing documents in a manner independent of application software, hardware, and operating systems....

and various other formats for viewing or printing.

The man package on most modern linux distributions includes the man2html command which can be used to enable users to browse their man pages using a html browser.

In 2010, OpenBSD

OpenBSD

OpenBSD is a Unix-like computer operating system descended from Berkeley Software Distribution , a Unix derivative developed at the University of California, Berkeley. It was forked from NetBSD by project leader Theo de Raadt in late 1995...

deprecated troff

Troff

for formatting manpages in favour of mandoc

Mandoc

mandoc is an ISC licensed utility for formatting man pages, specifically those written in the mdoc macro language...

, a specialised compiler/formatter for manpages with native support for output in PostScript

PostScript

, HTML

HTML

HyperText Markup Language is the predominant markup language for web pages. HTML elements are the basic building-blocks of webpages....

, XHTML

XHTML

XHTML is a family of XML markup languages that mirror or extend versions of the widely-used Hypertext Markup Language , the language in which web pages are written....

, and the terminal.

Manual sections

The manual is generally split into eight numbered sections, organized as follows (on BSD, Unix

Unix

and Linux

Linux

Linux is a Unix-like computer operating system assembled under the model of free and open source software development and distribution. The defining component of any Linux system is the Linux kernel, an operating system kernel first released October 5, 1991 by Linus Torvalds...

Section	Description
1	General command Command (computing) In computing, a command is a directive to a computer program acting as an interpreter of some kind, in order to perform a specific task. Most commonly a command is a directive to some kind of command line interface, such as a shell.... s
2	System call System call In computing, a system call is how a program requests a service from an operating system's kernel. This may include hardware related services , creating and executing new processes, and communicating with integral kernel services... s
3	Library functions, covering in particular the C standard library C standard library The C Standard Library is the standard library for the programming language C, as specified in the ANSI C standard.. It was developed at the same time as the C POSIX library, which is basically a superset of it...
4	Special files (usually devices, those found in /dev) and drivers Device driver In computing, a device driver or software driver is a computer program allowing higher-level computer programs to interact with a hardware device....
5	File format File format A file format is a particular way that information is encoded for storage in a computer file.Since a disk drive, or indeed any computer storage, can store only bits, the computer must have some way of converting information to 0s and 1s and vice-versa. There are different kinds of formats for... s and conventions
6	Games and screensaver Screensaver A screensaver is a type of computer program initially designed to prevent phosphor burn-in on CRT and plasma computer monitors by blanking the screen or filling it with moving images or patterns when the computer is not in use... s
7	Miscellanea
8	System administration command Command (computing) In computing, a command is a directive to a computer program acting as an interpreter of some kind, in order to perform a specific task. Most commonly a command is a directive to some kind of command line interface, such as a shell.... s and daemon Daemon (computer software) In Unix and other multitasking computer operating systems, a daemon is a computer program that runs as a background process, rather than being under the direct control of an interactive user... s

Unix System V uses a similar numbering scheme, except in a different order:

Section	Description
1	General command Command (computing) In computing, a command is a directive to a computer program acting as an interpreter of some kind, in order to perform a specific task. Most commonly a command is a directive to some kind of command line interface, such as a shell.... s
1M	System administration command Command (computing) In computing, a command is a directive to a computer program acting as an interpreter of some kind, in order to perform a specific task. Most commonly a command is a directive to some kind of command line interface, such as a shell.... s and daemon Daemon (computer software) In Unix and other multitasking computer operating systems, a daemon is a computer program that runs as a background process, rather than being under the direct control of an interactive user... s
2	System call System call In computing, a system call is how a program requests a service from an operating system's kernel. This may include hardware related services , creating and executing new processes, and communicating with integral kernel services... s
3	C library functions
4	File format File format A file format is a particular way that information is encoded for storage in a computer file.Since a disk drive, or indeed any computer storage, can store only bits, the computer must have some way of converting information to 0s and 1s and vice-versa. There are different kinds of formats for... s and conventions
5	Miscellanea
6	Games and screensaver Screensaver A screensaver is a type of computer program initially designed to prevent phosphor burn-in on CRT and plasma computer monitors by blanking the screen or filling it with moving images or patterns when the computer is not in use... s
7	Special files (usually devices, those found in /dev) and drivers Device driver In computing, a device driver or software driver is a computer program allowing higher-level computer programs to interact with a hardware device....

On some systems some of the following sections are available:

Section	Description
0	C library header file Header file Some programming languages use header files. These files allow programmers to separate certain elements of a program's source code into reusable files. Header files commonly contain forward declarations of classes, subroutines, variables, and other identifiers... s
9	Kernel routines
n	Tcl Tcl Tcl is a scripting language created by John Ousterhout. Originally "born out of frustration", according to the author, with programmers devising their own languages intended to be embedded into applications, Tcl gained acceptance on its own... /Tk keywords
x	The X Window System X Window System The X window system is a computer software system and network protocol that provides a basis for graphical user interfaces and rich input device capability for networked computers...

The sections are further subdivided by means of a suffix letter, such that section 3C is for C library calls, 3M is for the math library, and so on. A consequence of this is that section 8 (system administration commands) is sometimes relegated to the 1M subsection of the main commands section. Some subsection suffixes have a general meaning across sections:

Subsection	Description
p	POSIX POSIX POSIX , an acronym for "Portable Operating System Interface", is a family of standards specified by the IEEE for maintaining compatibility between operating systems... specifications
x	X Window System X Window System The X window system is a computer software system and network protocol that provides a basis for graphical user interfaces and rich input device capability for networked computers... documentation

Some versions of man cache the formatted versions of the last several pages viewed.

To see options you can use with command man, enter the command man man.

Layout

All man pages follow a common layout that is optimized for presentation on a simple ASCII

ASCII

The American Standard Code for Information Interchange is a character-encoding scheme based on the ordering of the English alphabet. ASCII codes represent text in computers, communications equipment, and other devices that use text...

text display, possibly without any form of highlighting or font control. Sections present may include:

NAME: The name of the command or function, followed by a one-line description of what it does.
SYNOPSIS: In the case of a command, you get a formal description of how to run it and what command line options it takes. For program functions, a list of the parameters the function takes and which header file contains its definition. For experienced users, this may be all the documentation they need.
DESCRIPTION: A textual description of the functioning of the command or function.
EXAMPLES: Some examples of common usage.
SEE ALSO: A list of related commands or functions.

Other sections may be present, but these are not well standardized across man pages. Common examples include: OPTIONS, EXIT STATUS, ENVIRONMENT, KNOWN BUGS, FILES, AUTHOR, REPORTING BUGS, HISTORY and COPYRIGHT.

Writing man pages

On Apple Mac OS X

Mac OS X

Mac OS X is a series of Unix-based operating systems and graphical user interfaces developed, marketed, and sold by Apple Inc. Since 2002, has been included with all new Macintosh computer systems...

and GNU

GNU

GNU is a Unix-like computer operating system developed by the GNU project, ultimately aiming to be a "complete Unix-compatible software system"...

/Linux

Linux

systems, two groff

Groff (software)

Groff is the GNU replacement for the troff and nroff text formatters. It is an original implementation written primarily in C++ by James Clark and is modeled after ditroff, including many extensions. The first version, 0.3.1, was released June 1990. The first stable version, 1.04, was announced in...

macro packages are available for use in writing manual pages, man and mdoc. The man macro package is older and is the traditional macro package used to write manual pages on UNIX

Unix

systems, whereas the mdoc package is newer and offers more support for semantic structuring of documents. The commands man groff_man and man groff_mdoc may be used in Mac OS X and GNU/Linux to bring up the online documentation (man pages) for using the man and mdoc macro packages, respectively.

In addition, one can simply inspect the source code for man pages installed on the system to see how they are written, typically found in /usr/share/man and other directories on Mac OS X and GNU/Linux systems. (To find the location of the manual page source file for command command, type man -w command.)

Man pages can also be written in DocBook

DocBook

DocBook is a semantic markup language for technical documentation. It was originally intended for writing technical documents related to computer hardware and software but it can be used for any other sort of documentation....

or LinuxDoc

LinuxDoc

LinuxDoc is an SGML DTD which is similar to DocBook. It was created by Matt Welsh and version 1.1 was announced in 1994. It is primarily used by the Linux Documentation Project. The DocBook SGML tags are often longer than the equivalent LinuxDoc tags...

format, then converted to groff.

Converting man pages

Besides viewing manual pages online (with man), man pages may also readily be converted to PDF

Portable Document Format

format for immediate printing. In Mac OS X and GNU/Linux (with command replaced by the name of the desired command):

groff -mandoc command.1 >command.ps
gs -dNOPAUSE -dBATCH -sDEVICE=pdfwrite -sOutputFile=command.pdf command.ps

The former command exports the manual page to PostScript

PostScript

format, while the latter then converts the resulting PostScript file to PDF. (The above works for both man- and mdoc-formatted manual pages.) In some cases, the hardcopy version of the manual page may be more readable if printed using a monospaced font; to do so, add the option -f C after the -mandoc option in the groff command above.

The mandoc

Mandoc

mandoc is an ISC licensed utility for formatting man pages, specifically those written in the mdoc macro language...

formatter directly supports PDF among other filetypes:

mandoc -Tpdf command.1 >command.1.pdf
mandoc -Tps command.1 >command.1.ps
mandoc -Txhtml command.1 >command.1.xhtml

External links

Unix Programmer's Manual of November 3, 1971 (see also the original scans in PS and PDF format).
History of UNIX Manpages for a primary-source history of UNIX manpages.
Online man pages for many versions of Unix, Linux, Macintosh Darwin and similar operating systems.
man: One open-source implementation of man; used on Red Hat, Fedora, Gentoo, Slackware, Mac OS-X and others.
man-db: Alternative implementation of man; used in Debian/Ubuntu, SUSE and others.
Practical UNIX Manuals: mdoc: Guide to writing mdoc UNIX manual pages.

The source of this article is wikipedia, the free encyclopedia. The text of this article is licensed under the GFDL.

Usage

History

Manual sections

Layout

Writing man pages

Converting man pages

See also

External links