HOME

TheInfoList



OR:

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 Othe ...
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

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. ...
, 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 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 s ...
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

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.su
service 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 ...
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 comm ...
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 hig ...
. 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 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-known products include the ...
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 hel ...
* ManOpen
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