CGI program to search and display manual pages
CGI program searches for manual
pages on a WWW server and displays them to HTTP clients, providing
functionality equivalent to the
utilities. It can
use multiple manual trees in parallel.
At the top of each generated HTML page,
displays a search form containing
- An input box for search queries, expecting either a name of a manual page
or an expression using the syntax
described in the apropos(1)
manual; filling this in is required for each search.
The expression is broken into words at whitespace. Whitespace characters and
backslashes can be escaped by prepending a backslash. The effect of
prepending a backslash to another character is undefined; in the current
implementation, it has no effect.
- A man(1) submit button. The
string in the input box is interpreted as the name of a manual page.
- An apropos(1) submit
button. The string in the input box is interpreted as a search
- A dropdown menu to optionally select a manual section. If one is provided,
it has the same effect as the
-s option. Otherwise, pages from all
sections are shown.
- A dropdown menu to optionally select an architecture. If one is provided,
it has the same effect as the
-S option. By default, pages for all
architectures are shown.
- A dropdown menu to select a manual tree. If the configuration file
/var/www/man/manpath.conf contains only
one manpath, the dropdown menu is not shown. By default, the first manpath
given in the file is used.
program generates five kinds of
- The index page.
- This is returned when calling
PATH_INFO and without a
QUERY_STRING. It serves as a starting
point for using the program and shows the search form only.
- A list page.
- Lists are returned when searches match more than one manual page. The
first column shows the names and section numbers of manuals as clickable
links. The second column shows the one-line descriptions of the manuals.
For man(1) style searches, the
content of the first manual page follows the list.
- A manual page.
- This output format is used when a search matches exactly one manual page,
or when a link on a list page or an
link on another manual page is followed.
- A no-result page.
- This is shown when a search request returns no results - either because it
violates the query syntax, or because the search does not match any manual
- An error page.
- This cannot happen by merely clicking the “Search” button,
but only by manually entering an invalid URI. It does not show the search
form, but only an error message and a link back to the index page.
For each manual tree, create one first-level subdirectory below
. The name of one of these
directories is called a “manpath” in the context of
. Create a single ASCII text file
names of these directories, one per line. The directory given first is used as
the default manpath.
Inside each of these directories, use the same directory and file structure as
found below /usr/share/man
, that is,
etc. containing source
manuals with file name
extensions matching the section numbers, second-level subdirectories
preformatted manuals with the file name extension ‘0’, and
optional third-level subdirectories for architectures. Use
to create a
Configure your web server to execute CGI programs located in
. When using
proxy daemon is
needed to translate FastCGI requests to plain old CGI.
, first copy
and edit it according to your needs.
It contains the following compile-time definitions:
- Only useful for running on www.openbsd.org to deal with old URIs
containing “manpath=OpenBSD ” where the blank character has
to be translated to a hyphen. When compiling for other sites, this
definition can be deleted.
- An optional file system path to the directory containing the file
mandoc.css, to be specified relative to
the server's document root, and to be specified without a trailing slash.
When empty, the CSS file is assumed to be in the document root. Otherwise,
a leading slash is needed. This is used in generated HTML code.
- An ASCII string to be used for the HTML <TITLE> element.
- A file system path to the
directory relative to the web server
chroot(2) directory, to be
specified with a leading slash and without a trailing slash. It needs to
have at least one component; the root directory cannot be used for this
purpose. The files manpath.conf,
footer.html are looked up in this
directory. It is also prepended to the manpath when opening
mandoc.db(5) and manual
- The initial component of URIs, to be specified without leading and
trailing slashes. It can be empty.
After editing cgi.h
and copy the resulting binary to the proper location, for example using the
In addition to that, make sure the default manpath contains the files
, or the documentation links
at the bottom of the index page will not work.
uniform resource identifiers are not
needed for interactive use, but can be useful for deep linking. They consist
https:// protocol specifier.
- The host name.
SCRIPT_NAME, preceded by a slash
- To show a single page, a slash, the manpath, another slash, and the name
of the requested file, for example
can be abbreviated according to the following syntax:
- For searches, a query string starting with a question mark and consisting
pairs, separated by ampersands, for example
Supported keys are
arch, corresponding to
-S, respectively, and
apropos, which is a boolean parameter
to select or deselect the
apropos(1) query mode. For
backward compatibility with the traditional
sektion is supported as an alias for
For security reasons, in particular to prevent cross site scripting attacks,
some strings used by
contain the following characters:
- lower case and upper case ASCII letters
- the ten decimal digits
- the dash (‘-’)
- the dot (‘.’)
- the slash (‘/’)
- the underscore (‘_’)
In particular, this applies to all manpaths and architecture names.
The web server may pass the following CGI variables to
- The initial part of the URI passed from the client to the server, starting
after the server's host name and ending before
PATH_INFO. This is ignored by
man.cgi. When constructing URIs for
links and redirections, the
preprocessor constant is used instead.
- The final part of the URI path passed from the client to the server,
starting after the
ending before the
QUERY_STRING. It is
used by the
show page to acquire the
manpath and filename it needs.
- The HTTP query string passed from the client to the server. It is the
final part of the URI, after the question mark. It is used by the
search page to acquire the named
parameters it needs.
- Default web server chroot(2)
directory. All the following paths are specified relative to this
- The usual file system path to the
man.cgi program inside the web server
chroot(2) directory. A
different name can be chosen, but in any case, it needs to be configured
- The file system path to the server document root directory relative to the
server chroot(2) directory.
This is part of the web server configuration and not specific to
- A style sheet for mandoc(1)
HTML styling, referenced from each generated HTML page.
man.cgi data directory
containing all the manual trees. Can be overridden by
- The list of available manpaths, one per line. If any of the lines in this
file contains a slash (‘/’) or any character not contained
man.cgi reports an
internal server error and exits without doing anything.
- An optional file containing static HTML code to be inserted right after
opening the <BODY> element.
- An optional file containing static HTML code to be inserted right before
closing the <BODY> element.
- An example mdoc(7) source file
located below the “OpenBSD-current” manpath.
CGI program is call-compatible
with queries from the traditional man.cgi
script by Wolfram Schneider. However, the output looks quite different.
A version of
first appeared in
mdocml-1.12.1 (March 2012). The current
first appeared in OpenBSD 6.1
program was written by
and is maintained by Ingo Schwarze
who also designed and implemented the database format.