![Man page on Linux screenshot](https://upload.wikimedia.org/wikipedia/commons/2/2c/Man_page_on_Linux_screenshot.png)
A man page (short for manual page) is a form of
software documentation
Software documentation is written text or illustration that accompanies computer software or is embedded in the source code. The documentation either explains how the software operates or how to use it, and may mean different things to people in ...
usually found on a
Unix
Unix (; trademarked as UNIX) is a family of multitasking, multiuser computer operating systems that derive from the original AT&T Unix, whose development started in 1969 at the Bell Labs research center by Ken Thompson, Dennis Ritchie, and ot ...
or
Unix-like
A Unix-like (sometimes referred to as UN*X or *nix) operating system is one that behaves in a manner similar to a Unix system, although not necessarily conforming to or being certified to any version of the Single UNIX Specification. A Unix-li ...
operating system
An operating system (OS) is system software that manages computer hardware, software resources, and provides common services for computer programs.
Time-sharing operating systems schedule tasks for efficient use of the system and may also in ...
. Topics covered include
computer program
A computer program is a sequence or set of instructions in a programming language for a computer to execute. Computer programs are one component of software, which also includes documentation and other intangible components.
A computer program ...
s (including
library
A library is a collection of materials, books or media that are accessible for use and not just for display purposes. A library provides physical (hard copies) or digital access (soft copies) materials, and may be a physical location or a vir ...
and
system call
In computing, a system call (commonly abbreviated to syscall) is the programmatic way in which a computer program requests a service from the operating system on which it is executed. This may include hardware-related services (for example, acc ...
s), formal standards and conventions, and even abstract concepts. A
user
Ancient Egyptian roles
* User (ancient Egyptian official), an ancient Egyptian nomarch (governor) of the Eighth Dynasty
* Useramen, an ancient Egyptian vizier also called "User"
Other uses
* User (computing), a person (or software) using an ...
may invoke a man page by issuing the
man
command
Command may refer to:
Computing
* Command (computing), a statement in a computer language
* COMMAND.COM, the default operating system shell and command-line interpreter for DOS
* Command key, a modifier key on Apple Macintosh computer keyboards
* ...
.
By default,
man
typically uses a
terminal pager
A terminal pager, paging program or simply pager is a computer program used to view (but not modify) 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 popul ...
program such as
more
More or Mores may refer to:
Computing
* MORE (application), outline software for Mac OS
* more (command), a shell command
* MORE protocol, a routing protocol
* Missouri Research and Education Network
Music Albums
* ''More!'' (album), by Booka S ...
or
less
Less or LESS may refer to: fewer than,: not as much.
Computing
* less (Unix), a Unix utility program
* Less (stylesheet language), a dynamic stylesheet language
* Large-Scale Scrum (LeSS), a product development framework that extends Scrum
Other ...
to display its output.
Man pages are often referred to as an ''on-line'' or ''
online
In computer technology and telecommunications, online indicates a state of connectivity and offline indicates a disconnected state. In modern terminology, this usually refers to an Internet connection, but (especially when expressed "on line" or ...
'' form of software documentation,
[
*] even though the
man
command does not require internet access, dating back to the times when printed ''
out-of-band
Out-of-band activity is activity outside a defined telecommunications frequency band, or, metaphorically, outside of any primary communication channel. Protection from falsing is among its purposes.
Examples General usage
* Out-of-band agreement ...
'' manuals were the norm.
History
![OpenBSD Manpages Section 8 Intro](https://upload.wikimedia.org/wikipedia/commons/4/40/OpenBSD_Manpages_Section_8_Intro.png)
In the first two years of the
history of Unix
The history of Unix dates back to the mid-1960s, when the Massachusetts Institute of Technology, AT&T Bell Labs, and General Electric were jointly developing an experimental time-sharing operating system called Multics for the GE-645 mainframe.
M ...
, no documentation existed.
The
Unix Programmer's Manual' was first published on November 3, 1971. The first actual man pages were written by
Dennis Ritchie
Dennis MacAlistair Ritchie (September 9, 1941 – October 12, 2011) was an American computer scientist. He is most well-known for creating the C programming language and, with long-time colleague Ken Thompson, the Unix operating system and B p ...
and
Ken Thompson
Kenneth Lane Thompson (born February 4, 1943) is an American pioneer of computer science. Thompson worked at Bell Labs for most of his career where he designed and implemented the original Unix operating system. He also invented the B programmi ...
at the insistence of their manager
Doug McIlroy
Malcolm Douglas McIlroy (born 1932) is a mathematician, engineer, and programmer. As of 2019 he is an Adjunct Professor of Computer Science at Dartmouth College.
McIlroy is best known for having originally proposed Unix pipelines and developed se ...
in 1971. Aside from the man pages, the ''Programmer's Manual'' also accumulated a set of short papers, some of them
tutorial
A tutorial, in education, is a method of transferring knowledge and may be used as a part of a learning process. More interactive and specific than a book or a lecture, a tutorial seeks to teach by example and supply the information to complete ...
s (e.g. for general Unix usage, the
C programming language, and tools such as
Yacc
Yacc (Yet Another Compiler-Compiler) is a computer program for the Unix operating system developed by Stephen C. Johnson. It is a Look Ahead Left-to-Right Rightmost Derivation (LALR) parser generator, generating a LALR parser (the part of a com ...
), and others more detailed descriptions of operating system features. The printed version of the manual initially fit into a single binder, but as of
PWB/UNIX
The Programmer's Workbench (PWB/UNIX) is an early, now discontinued, version of the Unix operating system that had been created in the Bell Labs Computer Science Research Group of AT&T. Its stated goal was to provide a time-sharing working envir ...
and the
7th Edition of
Research Unix
The term "Research Unix" refers to early versions of the Unix operating system for DEC PDP-7, PDP-11, VAX and Interdata 7/32 and 8/32 computers, developed in the Bell Labs Computing Sciences Research Center (CSRC).
History
The term ''Research ...
, it was split into two volumes with the printed man pages forming Volume 1.
[ Originally published in ''Microsystems'' 5(11), November 1984.]
Later versions of the documentation imitated the first man pages' terseness. Ritchie added a "How to get started" section to the
Third Edition introduction, and
Lorinda Cherry
Lorinda Cherry ( Landgraf; November 18, 1944 – February 2022) was an American computer scientist and programmer. Much of her career was spent at Bell Labs, where she was for many years a member of the original Unix Lab. Cherry developed severa ...
provided the "Purple Card" pocket reference for the
Sixth and
Seventh
Seventh is the ordinal form of the number seven.
Seventh may refer to:
* Seventh Amendment to the United States Constitution
* A fraction (mathematics), , equal to one of seven equal parts
Film and television
*"The Seventh", a second-season e ...
Editions. Versions of the software were named after the revision of the manual; the seventh edition of the ''Unix Programmer's Manual'', for example, came with the 7th Edition or Version 7 of Unix.
For the
Fourth Edition the man pages were formatted using the
troff
troff (), short for "typesetter roff", is the major component of a document processing system developed by Bell Labs for the Unix operating system. troff and the related nroff were both developed from the original roff.
While nroff was inten ...
typesetting package and its set of
-man
macros (which were completely revised between the Sixth and Seventh Editions of the ''Manual'',
but have since not drastically changed). 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 a man page, and many Unix users perceive a program's lack of man pages as a sign of low quality; indeed, some projects, such as
Debian
Debian (), also known as Debian GNU/Linux, is a Linux distribution composed of free and open-source software, developed by the community-supported Debian Project, which was established by Ian Murdock on August 16, 1993. The first version of D ...
, go out of their way to write man pages for programs lacking one. The modern descendants of
4.4BSD The History of the Berkeley Software Distribution begins in the 1970s.
1BSD (PDP-11)
The earliest distributions of Unix from Bell Labs in the 1970s included the source code to the operating system, allowing researchers at universities to modify a ...
also distribute man pages as one of the primary forms of system documentation (having replaced the old
-man
macros with the newer
-mdoc
).
There was a hidden
easter egg
Easter eggs, also called Paschal eggs, are eggs that are decorated for the Christian feast of Easter, which celebrates the resurrection of Jesus. As such, Easter eggs are common during the season of Eastertide (Easter season). The oldest tr ...
in the man-db version of the man command that would cause the command to return "gimme gimme gimme" when run at 00:30 (a reference to the
ABBA
ABBA ( , , formerly named Björn & Benny, Agnetha & Anni-Frid or Björn & Benny, Agnetha & Frida) are a Swedish supergroup formed in Stockholm in 1972 by Agnetha Fältskog, Björn Ulvaeus, Benny Andersson, and Anni-Frid Lyngstad. The group's ...
song
Gimme! Gimme! Gimme! (A Man After Midnight)
"Gimme! Gimme! Gimme! (A Man After Midnight)" is a song by Swedish band ABBA. It was recorded in August 1979 in order to help promote their North American and European tour of that year, and was released on ABBA's '' Greatest Hits Vol. 2'' album ...
. It was introduced in 2011
but first restricted
and then removed in 2017 after finally being found.
Formatting
![FreeBSD typeset man page](https://upload.wikimedia.org/wikipedia/commons/d/d8/FreeBSD_typeset_man_page.png)
The default format of man pages is
troff
troff (), short for "typesetter roff", is the major component of a document processing system developed by Bell Labs for the Unix operating system. troff and the related nroff were both developed from the original roff.
While nroff was inten ...
, with either the
macro package man (appearance oriented) or mdoc (semantic oriented). This makes it possible to typeset a man page into
PostScript
PostScript (PS) is a page description language in the electronic publishing and desktop publishing realm. It is a dynamically typed, concatenative programming language. It was created at Adobe Systems by John Warnock, Charles Geschke, Doug Br ...
,
PDF
Portable Document Format (PDF), standardized as ISO 32000, is a file format developed by Adobe in 1992 to present documents, including text formatting and images, in a manner independent of application software, hardware, and operating systems. ...
, and various other formats for viewing or printing.
Some
Unix
Unix (; trademarked as UNIX) is a family of multitasking, multiuser computer operating systems that derive from the original AT&T Unix, whose development started in 1969 at the Bell Labs research center by Ken Thompson, Dennis Ritchie, and ot ...
systems have a package for the command, which enables users to browse their man pages using an HTML browser. Systems with groff and man-db should use the higher-quality native HTML output () instead.
The
GNU Emacs
GNU Emacs is a free software text editor. It was created by GNU Project founder Richard Stallman, based on the Emacs editor developed for Unix operating systems. GNU Emacs has been a central component of the GNU project and a flagship project of ...
program ''WoMan'' (from "WithOut man") allows to browse man pages from the editor.
In 2010,
OpenBSD
OpenBSD is a security-focused, free and open-source, Unix-like operating system based on the Berkeley Software Distribution (BSD). Theo de Raadt created OpenBSD in 1995 by forking NetBSD 1.0. According to the website, the OpenBSD project em ...
deprecated
troff
troff (), short for "typesetter roff", is the major component of a document processing system developed by Bell Labs for the Unix operating system. troff and the related nroff were both developed from the original roff.
While nroff was inten ...
for formatting man pages in favour of
mandoc
mandoc (historically called mdocml) is a utility used for formatting man pages in BSD Operating Systems (e.g. NetBSD), specifically those written in the ''mdoc'' and ''man'' macro languages. Unlike the groff and older troff and nroff tools tha ...
, a specialised compiler/formatter for man pages with native support for output in
PostScript
PostScript (PS) is a page description language in the electronic publishing and desktop publishing realm. It is a dynamically typed, concatenative programming language. It was created at Adobe Systems by John Warnock, Charles Geschke, Doug Br ...
,
HTML
The HyperText Markup Language or HTML is the standard markup language for documents designed to be displayed in a web browser. It can be assisted by technologies such as Cascading Style Sheets (CSS) and scripting languages such as JavaScri ...
,
XHTML
Extensible HyperText Markup Language (XHTML) is part of the family of XML markup languages. It mirrors or extends versions of the widely used HyperText Markup Language (HTML), the language in which Web pages are formulated.
While HTML, prior ...
, and the terminal. It is meant to only support a subset of troff used in manual pages, specifically those using mdoc macros.
Online services
Quite a few websites offer online access to manual pages from various Unix-like systems.
In February 2013, the
BSD
The Berkeley Software Distribution or Berkeley Standard Distribution (BSD) is a discontinued operating system based on Research Unix, developed and distributed by the Computer Systems Research Group (CSRG) at the University of California, Berk ...
community saw a new open sourc
mdoc.suservice launched, which unified and shortened access to the man.cgi scripts of the major modern BSD projects through a unique
nginx
Nginx (pronounced "engine x" ) is a web server that can also be used as a reverse proxy, load balancer, mail proxy and HTTP cache. The software was created by Igor Sysoev and publicly released in 2004. Nginx is free and open-source software ...
-based deterministic
URL shortening
URL shortening is a technique on the World Wide Web in which a Uniform Resource Locator (URL) may be made substantially shorter and still direct to the required page. This is achieved by using a redirect which links to the web page that has a ...
service for the *BSD man pages.
For Linux, a man7.org service has been set up to serve manuals specific to the system. A ManKier service provides a wider selection, and integrates the TLDR pages too.
Command usage
To read a manual page for a Unix command, a user can type:
man
Pages are traditionally referred to using the notation "name(section)": for example, . The section refers to different ways the topic might be referenced - for example, as a system call, or a shell (command line) command or package, or a package's configuration file, or as a coding construct / header.
The same page name may appear in more than one section of the manual, such as when the names of
system call
In computing, a system call (commonly abbreviated to syscall) is the programmatic way in which a computer program requests a service from the operating system on which it is executed. This may include hardware-related services (for example, acc ...
s, user
command
Command may refer to:
Computing
* Command (computing), a statement in a computer language
* COMMAND.COM, the default operating system shell and command-line interpreter for DOS
* Command key, a modifier key on Apple Macintosh computer keyboards
* ...
s, or
macro packages coincide. Examples are and , or and . The syntax for accessing the non-default manual section varies between different man implementations.
On Solaris and illumos, for example, the syntax for reading is:
man -s 3c printf
On Linux and BSD derivatives the same invocation would be:
man 3 printf
which searches for ''
printf
The printf format string is a control parameter used by a class of functions in the input/output libraries of C and many other programming languages. The string is written in a simple template language: characters are usually copied literal ...
'' in section 3 of the man pages.
Manual sections
The manual is generally split into eight numbered sections, organized as follows (on
Research Unix
The term "Research Unix" refers to early versions of the Unix operating system for DEC PDP-7, PDP-11, VAX and Interdata 7/32 and 8/32 computers, developed in the Bell Labs Computing Sciences Research Center (CSRC).
History
The term ''Research ...
,
BSD
The Berkeley Software Distribution or Berkeley Standard Distribution (BSD) is a discontinued operating system based on Research Unix, developed and distributed by the Computer Systems Research Group (CSRG) at the University of California, Berk ...
,
macOS
macOS (; previously OS X and originally Mac OS X) is a Unix operating system developed and marketed by Apple Inc. since 2001. It is the primary operating system for Apple's Mac computers. Within the market of desktop and lapt ...
and
Linux
Linux ( or ) is a family of open-source Unix-like operating systems based on the Linux kernel, an operating system kernel first released on September 17, 1991, by Linus Torvalds. Linux is typically packaged as a Linux distribution, which ...
):
POSIX
The Portable Operating System Interface (POSIX) is a family of standards specified by the IEEE Computer Society for maintaining compatibility between operating systems. POSIX defines both the system- and user-level application programming interf ...
system calls are often present in both sections 2 and 3, where section 2 contains the system call's documentation from the local operating system and section 3 contains the system call's documentation from the POSIX Programmer's Manual.
Unix System V
Unix System V (pronounced: "System Five") is one of the first commercial versions of the Unix operating system. It was originally developed by AT&T and first released in 1983. Four major versions of System V were released, numbered 1, 2, 3, an ...
uses a similar numbering scheme, except in a different order:
On some systems some of the following sections are available:
Some sections are further subdivided by means of a suffix; for example, in some systems, 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:
(Section 3 tends to be the exception with the many suffixes for different languages.)
Some versions of man
cache the formatted versions of the last several pages viewed. One form is the ''cat page'', simply piped to the pager for display.
Layout
All man pages follow a common layout that is optimized for presentation on a simple ASCII
ASCII ( ), abbreviated from American Standard Code for Information Interchange, is a character encoding standard for electronic communication. ASCII codes represent text in computers, telecommunications equipment, and other devices. Because of ...
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, 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 declaration.
; 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, RETURN VALUE, ENVIRONMENT, BUGS, FILES, AUTHOR, REPORTING BUGS, HISTORY and COPYRIGHT.
]
Authoring
Manual pages can be written either in the old macros, the new macros, or a combination of both (). The macro set provides minimal rich text
Rich may refer to:
Common uses
* Rich, an entity possessing wealth
* Rich, an intense flavor, color, sound, texture, or feeling
** Rich (wine), a descriptor in wine tasting
Places United States
* Rich, Mississippi, an unincorporated commun ...
functions, with directives for the title line, section headers, (bold, small or italic) fonts, paragraphs and adding/reducing indentation. The newer language is more semantic in nature, and contains specialized macros for most standard sections such as program name, synopsis, function names, and the name of the authors. This information can be used to implement a semantic search
Semantic search denotes search with meaning, as distinguished from lexical search where the search engine looks for literal matches of the query words or variants of them, without understanding the overall meaning of the query. Semantic search seek ...
for manuals by programs such as mandoc
mandoc (historically called mdocml) is a utility used for formatting man pages in BSD Operating Systems (e.g. NetBSD), specifically those written in the ''mdoc'' and ''man'' macro languages. Unlike the groff and older troff and nroff tools tha ...
. Although it also includes directives to directly control the styling, it is expected that the specialized macros will cover most of the use-cases. Both the mandoc and the groff projects consider the preferred format for new documents.
Although man pages are, to troff, text laid out using 10-point Roman type
In Latin script typography, roman is one of the three main kinds of historical type, alongside blackletter and italic. Roman type was modelled from a European scribal manuscript style of the 15th century, based on the pairing of inscriptional ...
, this distinction is usually moot because man pages are viewed in the terminal (TTY) instead of laid out on paper. As a result, the "small font" macro is seldom used. On the other hand, bold and italic text is supported by the terminal via ECMA-48, and groff's does emit them as requested when it detects a supporting terminal. The BSD mandoc however only supports bold and underlined (as a replacement for italics) text via the typewriter backspace-then-overstrike sequence, which needs to be translated into ECMA-48 by .
Man pages are usually written in English, but translations into other languages may be available on the system. The GNU and the mandoc is known to search for localized manual pages under subdirectories.[
]
Alternatives
Few alternatives to man
have enjoyed much popularity, with the possible exception of GNU Project's "info
Info is shorthand for "information". It may also refer to:
Computing
* .info, a generic top-level domain
* info:, a URI scheme for information assets with identifiers in public namespaces
* info (Unix), a command used to view documentation produc ...
" system, an early and simple hypertext
Hypertext is E-text, text displayed on a computer display or other electronic devices with references (hyperlinks) to other text that the reader can immediately access. Hypertext documents are interconnected by hyperlinks, which are typi ...
system. There is also a third-party effort known as TLDR pages (tldr
) that provides simple examples for common use cases, similar to a cheatsheet
A cheat sheet (also ''cheatsheet'') or crib sheet is a concise set of notes used for quick reference. Cheat sheets were historically used by students without an instructor or teacher's knowledge to cheat on a test or exam. In the context of h ...
.
In addition, some Unix GUI
The GUI ( "UI" by itself is still usually pronounced . or ), graphical user interface, is a form of user interface that allows users to interact with electronic devices through graphical icons and audio indicator such as primary notation, inste ...
applications (particularly those built using the GNOME
A gnome is a mythological creature and diminutive spirit in Renaissance magic and alchemy, first introduced by Paracelsus in the 16th century and later adopted by more recent authors including those of modern fantasy literature. Its characte ...
and KDE
KDE is an international Free software movement, free software community that develops free and open-source software. As a central development hub, it provides tools and resources that allow collaborative work on this kind of software. Well-know ...
development environments) now provide end-user documentation in HTML
The HyperText Markup Language or HTML is the standard markup language for documents designed to be displayed in a web browser. It can be assisted by technologies such as Cascading Style Sheets (CSS) and scripting languages such as JavaScri ...
and include embedded HTML viewers such as yelp
for reading the help within the application.
See also
* List of Unix commands
This is a list of Unix commands as specified by IEEE Std 1003.1-2008, which is part of the Single UNIX Specification (SUS). These commands can be found on Unix operating systems and most Unix-like operating systems.
List
See also
* List of G ...
* List of Plan 9 applications
This is a list of Plan 9 programs. Many of these programs are very similar to the UNIX programs with the same name, others are to be found only on Plan 9. Others again share only the name, but have a different behaviour.
System software
Gen ...
* info
Info is shorthand for "information". It may also refer to:
Computing
* .info, a generic top-level domain
* info:, a URI scheme for information assets with identifiers in public namespaces
* info (Unix), a command used to view documentation produc ...
* apropos
* README
In software development, a README file contains information about the other files in a directory or archive of computer software. A form of documentation, it is usually a simple plain text file called README, Read Me, READ.ME, README.TXT, R ...
* RTFM
RTFM is an initialism and internet slang for the expression "read the fucking manual" – typically used to reply to a basic question where the answer is easily found in the documentation, user guide, owner's manual, man page, online help, i ...
* ManOpen
ManOpen is a utility for NeXTSTEP and Mac OS X created by Carl Lindberg that can display Unix man pages in a graphical environment instead of a terminal emulator such as Terminal.
Man pages are included in the program; it has a Recents menu, w ...
– NeXT
Next may refer to:
Arts and entertainment Film
* ''Next'' (1990 film), an animated short about William Shakespeare
* ''Next'' (2007 film), a sci-fi film starring Nicolas Cage
* '' Next: A Primer on Urban Painting'', a 2005 documentary film
Lit ...
/macOS
macOS (; previously OS X and originally Mac OS X) is a Unix operating system developed and marketed by Apple Inc. since 2001. It is the primary operating system for Apple's Mac computers. Within the market of desktop and lapt ...
graphical man utility
References
External links
History of UNIX Manpages
for a primary-source history of UNIX man pages.
UNIX and Linux Man Page Repository
with nearly 300,000 well formatted man pages.
What do the numbers in a man page mean?
FreeBSD Manual Pages
freebsd.org – has also man pages for Darwin, Debian, HP-UX, IRIS, NetBSD, OpenBSD, NextSTEP, SunOS and more
{{DEFAULTSORT:Man Page
Technical communication
Unix SUS2008 utilities
Plan 9 from Bell Labs
Online help