.Dd $Mdocdate: April 15 2016 $

.Os

.Nm man.cgi

.Nd internals of the CGI program to search and display manual pages

The source code of

.Xr man.cgi 8

is organized in four levels:

.Pp

.Bl -enum -compact

.It

.Sx Top level

.It

.Sx Page generators

.It

.Sx Result generators

.It

.Sx Utility routines

.El

.Ss Top level

The top level of

.Xr man.cgi 8

consists of the

.Fn main

program and a few parser routines.

.Bl -tag -width 1n

.It Ft int Fn main void

The main program

.Bl -dash -compact

.It

limits execution time;

.It

changes to

.Dv MAN_DIR ,

the data directory containing all the manual trees;

.It

calls

.Fn parse_manpath_conf ;

.It

calls

.Fn parse_path_info ;

.It

calls

.Fn parse_query_string

if

.Ev PATH_INFO

is empty;

.It

validates the manpath and the architecture;

.It

calls the appropriate one among the

.Sx Page generators .

.El

.It Ft void Fn parse_manpath_conf "struct req *req"

Parses and validates

.Pa manpath.conf

and fills

.Va req->p

and

.Va req->psz .

.It Ft void Fn parse_path_info "struct req *req" "const char *path"

Parses and validates

.Ev PATH_INFO ,

clears

.Va req->isquery ,

and fills

.Va req->q .

.It Ft void Fn parse_query_string "struct req *req" "const char *qs"

Parses and validates

.Ev QUERY_STRING ,

sets

.Va req->isquery ,

and fills

.Va req->q .

This function is the only user of the utility functions

.Fn http_decode

and

.Fn set_query_attr .

.El

.Ss Page generators

The purpose of each page generator is to print a complete HTML page,

starting with the HTTP headers and continuing to the page footer.

Before starting HTML output with

.Fn resp_begin_html ,

some page generators do some preparatory work, for example to decide

which page to show.

Each page generator ends with a call to

.Fn resp_end_html .

.Bl -tag -width 1n

.It Ft void Fn pg_show "struct req *req" "const char *fullpath"

This page generator is used when

.Ev PATH_INFO

contains the complete path to a manual page including manpath,

section directory, optional architecture subdirectory, manual name

and section number suffix.

It validates the manpath, changes into it, validate the filename,

and then calls

.Fn resp_begin_html ,

.Fn resp_searchform ,

.Fn resp_show ,

and

.Fn resp_end_html

in that order.

.It Ft void Fn pg_search "const struct req *req"

This page generator is used when

.Ev PATH_INFO

contains a search query in short format or when

.Ev PATH_INFO

is empty and a

.Ev QUERY_STRING

is provided.

It changes into the manpath and calls

.Xr mansearch 3 .

Depending on the result, it calls either

.Fn pg_noresult

or

.Fn pg_searchres .

.It Ft void Fn pg_noresult "const struct req *req" "const char *msg"

This function calls

.Fn resp_begin_html ,

.Fn resp_searchform ,

prints the

.Fa msg

passed to it, and calls

.Fn resp_end_html .

.It Ft void Fn pg_searchres "const struct req *req" "struct manpage *r"\

"size_t sz"

This function first validates the filenames found.

If

.Ev QUERY_STRING

was used and there is exactly one result,

it writes an HTTP redirect to that result.

Otherwise, it writes an HTML result page beginning with

.Fn resp_begin_html

and

.Fn resp_searchform .

If there is more than one result, it writes a list of links

to all the results.

If it was a

.Xr man 1

rather than an

.Xr apropos 1

query or if there is only one single result, it calls

.Fn resp_show .

Finally, it calls

.Fn resp_end_html .

.It Ft void Fn pg_index "const struct req *req"

This page generator is used when

.Ev PATH_INFO

and

.Ev QUERY_STRING

are both empty.

It calls

.Fn resp_begin_html

and

.Fn resp_searchform ,

writes links to help pages, and calls

.Fn resp_end_html .

.It Ft void Fn pg_error_badrequest "const char *msg"

This page generator is used when

.Fn main

or

.Fn pg_show

detect an invalid URI.

It calls

.Fn resp_begin_html ,

prints the

.Fa msg

provided, and calls

.Fn resp_end_html .

.It Ft void Fn pg_error_internal void

This page generator is used by various functions when errors are

detected in the

.Pa manpath.conf

configuration file, in

.Xr mandoc.db 5

databases, in the

.Xr mandoc 3

parser, in file system permissions, or when setting up timeouts.

It calls

.Fn resp_begin_html ,

prints

.Qq "Internal Server Error" ,

and calls

.Fn resp_end_html .

Before calling

.Fn pg_error_internal ,

call

.Xr warn 3

or

.Xr warnx 3

to log the reason of the error to the

.Xr httpd 8

server log file.

.El

.Ss Result generators

The purpose of result generators is to print a chunk of HTML code.

When they print untrusted strings or characters,

.Fn html_print

and

.Fn html_putchar

are used.

The highest level result generators are:

.Bl -tag -width 1n

.It Ft void Fn resp_begin_html "int code" "const char *msg"

This generator calls

.Fn resp_begin_http

to print the HTTP headers, then prints the HTML header up to the

opening tag of the <body> element, then copies the file

.Pa header.html

to the output, if it exists and is readable.

.It Ft void Fn resp_searchform "const struct req *req"

This generator prints a search form, filling it with data

from the provided request object.

.It Ft void Fn resp_show "const struct req *req" "const char *file"

This wrapper dispatches to either

.Fn resp_catman

or

.Fn resp_format ,

depending on whether

.Ar file

starts with

.Pa cat

or

.Pa man ,

respectively.

.It Ft void Fn resp_catman "const struct req *req" "const char *file"

This generator translates a preformatted, backspace-encoded manual

page to HTML and prints it to the output.

.It Ft void Fn resp_format "const struct req *req" "const char *file"

This generator formats a manual page on the standard output,

using the functions documented in

.Xr mchars_alloc 3

and

.Xr mandoc 3 .

.It Ft void Fn resp_end_html void

This generator copies the file

.Pa footer.html

to the output, if it exists and is readable,

and closes the <body> and <html> elements.

.El

.Ss Utility routines

These functions take a string and return 1 if it is valid, or 0 otherwise.

.Bl -tag -width 1n

.It Ft int Fn validate_urifrag "const char *frag"

Checks that the string only contains alphanumeric ASCII characters,

dashes, dots, slashes, and underscores.

.It Ft int Fn validate_manpath "const struct req *req" "const char* manpath"

Checks that the string is either

.Qq mandoc

or one of the manpaths configured in

.Pa manpath.conf .

.It Ft int Fn validate_filename "const char *file"

Checks that the string starts with

.Qq man

or

.Qq cat

and does not ascend to parent directories.

.El

.Xr mandoc 3 ,

.Xr mansearch 3 ,

.Xr mandoc.db 5 ,

.Xr man.cgi 8