Annotation of mandoc/man.cgi.3, Revision 1.1
1.1 ! schwarze 1: .\" $Id: mandoc_html.3,v 1.1 2014/07/23 18:13:09 schwarze Exp $
! 2: .\"
! 3: .\" Copyright (c) 2016 Ingo Schwarze <schwarze@openbsd.org>
! 4: .\"
! 5: .\" Permission to use, copy, modify, and distribute this software for any
! 6: .\" purpose with or without fee is hereby granted, provided that the above
! 7: .\" copyright notice and this permission notice appear in all copies.
! 8: .\"
! 9: .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
! 10: .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
! 11: .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
! 12: .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
! 13: .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
! 14: .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
! 15: .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
! 16: .\"
! 17: .Dd $Mdocdate: July 23 2014 $
! 18: .Dt MAN.CGI 3
! 19: .Os
! 20: .Sh NAME
! 21: .Nm man.cgi
! 22: .Nd internals of the CGI program to search and display manual pages
! 23: .Sh DESCRIPTION
! 24: The source code of
! 25: .Xr man.cgi 8
! 26: is organized in four levels:
! 27: .Pp
! 28: .Bl -enum -compact
! 29: .It
! 30: .Sx Top level
! 31: .It
! 32: .Sx Page generators
! 33: .It
! 34: .Sx Result generators
! 35: .It
! 36: .Sx Utility routines
! 37: .El
! 38: .Ss Top level
! 39: The top level of
! 40: .Xr man.cgi 8
! 41: consists of the
! 42: .Fn main
! 43: program and a few parser routines.
! 44: .Bl -tag -width 1n
! 45: .It Ft int Fn main void
! 46: The main program
! 47: .Bl -dash -compact
! 48: .It
! 49: limits execution time;
! 50: .It
! 51: changes to
! 52: .Dv MAN_DIR ,
! 53: the data directory containing all the manual trees;
! 54: .It
! 55: calls
! 56: .Fn parse_manpath_conf ;
! 57: .It
! 58: calls
! 59: .Fn parse_path_info ;
! 60: .It
! 61: calls
! 62: .Fn parse_query_string
! 63: if
! 64: .Ev PATH_INFO
! 65: is empty;
! 66: .It
! 67: validates the manpath and the architecture;
! 68: .It
! 69: calls the appropriate one among the
! 70: .Sx Page generators .
! 71: .El
! 72: .It Ft void Fn parse_manpath_conf "struct req *req"
! 73: Parses and validates
! 74: .Pa manpath.conf
! 75: and fills
! 76: .Va req->p
! 77: and
! 78: .Va req->psz .
! 79: .It Ft void Fn parse_path_info "struct req *req" "const char *path"
! 80: Parses and validates
! 81: .Ev PATH_INFO ,
! 82: clears
! 83: .Va req->isquery ,
! 84: and fills
! 85: .Va req->q .
! 86: .It Ft void Fn parse_query_string "struct req *req" "const char *qs"
! 87: Parses and validates
! 88: .Ev QUERY_STRING ,
! 89: sets
! 90: .Va req->isquery ,
! 91: and fills
! 92: .Va req->q .
! 93: This function is the only user of the utility functions
! 94: .Fn http_decode
! 95: and
! 96: .Fn set_query_attr .
! 97: .El
! 98: .Ss Page generators
! 99: The purpose of each page generator is to print a complete HTML page,
! 100: starting with the HTTP headers and continuing to the page footer.
! 101: Before starting HTML output with
! 102: .Fn resp_begin_html ,
! 103: some page generators do some preparatory work, for example to decide
! 104: which page to show.
! 105: Each page generator ends with a call to
! 106: .Fn resp_end_html .
! 107: .Bl -tag -width 1n
! 108: .It Ft void Fn pg_show "struct req *req" "const char *fullpath"
! 109: This page generator is used when
! 110: .Ev PATH_INFO
! 111: contains the complete path to a manual page including manpath,
! 112: section directory, optional architecture subdirectory, manual name
! 113: and section number suffix.
! 114: It validates the manpath, changes into it, validate the filename,
! 115: and then calls
! 116: .Fn resp_begin_html ,
! 117: .Fn resp_searchform ,
! 118: .Fn resp_show ,
! 119: and
! 120: .Fn resp_end_html
! 121: in that order.
! 122: .It Ft void Fn pg_search "const struct req *req"
! 123: This page generator is used when
! 124: .Ev PATH_INFO
! 125: contains a search query in short format or when
! 126: .Ev PATH_INFO
! 127: is empty and a
! 128: .Ev QUERY_STRING
! 129: is provided.
! 130: It changes into the manpath and calls
! 131: .Xr mansearch 3 .
! 132: Depending on the result, it calls either
! 133: .Fn pg_noresult
! 134: or
! 135: .Fn pg_searchres .
! 136: .It Ft void Fn pg_noresult "const struct req *req" "const char *msg"
! 137: This function calls
! 138: .Fn resp_begin_html ,
! 139: .Fn resp_searchform ,
! 140: prints the
! 141: .Fa msg
! 142: passed to it, and calls
! 143: .Fn resp_end_html .
! 144: .It Ft void Fn pg_searchres "const struct req *req" "struct manpage *r"\
! 145: "size_t sz"
! 146: This function first validates the filenames found.
! 147: If
! 148: .Ev QUERY_STRING
! 149: was used and there is exactly one result,
! 150: it writes an HTTP redirect to that result.
! 151: Otherwise, it writes an HTML result page beginning with
! 152: .Fn resp_begin_html
! 153: and
! 154: .Fn resp_searchform .
! 155: If there is more than one result, it writes a list of links
! 156: to all the results.
! 157: If it was a
! 158: .Xr man 1
! 159: rather than an
! 160: .Xr apropos 1
! 161: query or if there is only one single result, it calls
! 162: .Fn resp_show .
! 163: Finally, it calls
! 164: .Fn resp_end_html .
! 165: .It Ft void Fn pg_index "const struct req *req"
! 166: This page generator is used when
! 167: .Ev PATH_INFO
! 168: and
! 169: .Ev QUERY_STRING
! 170: are both empty.
! 171: It calls
! 172: .Fn resp_begin_html
! 173: and
! 174: .Fn resp_searchform ,
! 175: writes links to help pages, and calls
! 176: .Fn resp_end_html .
! 177: .It Ft void Fn pg_error_badrequest "const char *msg"
! 178: This page generator is used when
! 179: .Fn main
! 180: or
! 181: .Fn pg_show
! 182: detect an invalid URI.
! 183: It calls
! 184: .Fn resp_begin_html ,
! 185: prints the
! 186: .Fa msg
! 187: provided, and calls
! 188: .Fn resp_end_html .
! 189: .It Ft void Fn pg_error_internal void
! 190: This page generator is used by various functions when errors are
! 191: detected in the
! 192: .Pa manpath.conf
! 193: configuration file, in
! 194: .Xr mandoc.db 5
! 195: databases, in the
! 196: .Xr mandoc 3
! 197: parser, in file system permissions, or when setting up timeouts.
! 198: It calls
! 199: .Fn resp_begin_html ,
! 200: prints
! 201: .Qq "Internal Server Error" ,
! 202: and calls
! 203: .Fn resp_end_html .
! 204: Before calling
! 205: .Fn pg_error_internal ,
! 206: call
! 207: .Xr warn 3
! 208: or
! 209: .Xr warnx 3
! 210: to log the reason of the error to the
! 211: .Xr httpd 8
! 212: server log file.
! 213: .El
! 214: .Ss Result generators
! 215: The purpose of result generators is to print a chunk of HTML code.
! 216: When they print untrusted strings or characters,
! 217: .Fn html_print
! 218: and
! 219: .Fn html_putchar
! 220: are used.
! 221: The highest level result generators are:
! 222: .Bl -tag -width 1n
! 223: .It Ft void Fn resp_begin_html "int code" "const char *msg"
! 224: This generator calls
! 225: .Fn resp_begin_http
! 226: to print the HTTP headers, then prints the HTML header up to the
! 227: opening tag of the <body> element, then copies the file
! 228: .Pa header.html
! 229: to the output, if it exists and is readable.
! 230: .It Ft void Fn resp_searchform "const struct req *req"
! 231: This generator prints a search form, filling it with data
! 232: from the provided request object.
! 233: .It Ft void Fn resp_show "const struct req *req" "const char *file"
! 234: This wrapper dispatches to either
! 235: .Fn resp_catman
! 236: or
! 237: .Fn resp_format ,
! 238: depending on whether
! 239: .Ar file
! 240: starts with
! 241: .Pa cat
! 242: or
! 243: .Pa man ,
! 244: respectively.
! 245: .It Ft void Fn resp_catman "const struct req *req" "const char *file"
! 246: This generator translates a preformatted, backspace-encoded manual
! 247: page to HTML and prints it to the output.
! 248: .It Ft void Fn resp_format "const struct req *req" "const char *file"
! 249: This generator formats a manual page on the standard output,
! 250: using the functions documented in
! 251: .Xr mchars_alloc 3
! 252: and
! 253: .Xr mandoc 3 .
! 254: .It Ft void Fn resp_end_html void
! 255: This generator copies the file
! 256: .Pa footer.html
! 257: to the output, if it exists and is readable,
! 258: and closes the <body> and <html> elements.
! 259: .El
! 260: .Ss Utility routines
! 261: These functions take a string and return 1 if it is valid, or 0 otherwise.
! 262: .Bl -tag -width 1n
! 263: .It Ft int Fn validate_urifrag "const char *frag"
! 264: Checks that the string only contains alphanumeric ASCII characters,
! 265: dashes, dots, slashes, and underscores.
! 266: .It Ft int Fn validate_manpath "const struct req *req" "const char* manpath"
! 267: Checks that the string is either
! 268: .Qq mandoc
! 269: or one of the manpaths configured in
! 270: .Pa manpath.conf .
! 271: .It Ft int Fn validate_filename "const char *file"
! 272: Checks that the string starts with
! 273: .Qq man
! 274: or
! 275: .Qq cat
! 276: and does not ascend to parent directories.
! 277: .El
! 278: .Sh SEE ALSO
! 279: .Xr mandoc 3 ,
! 280: .Xr mansearch 3 ,
! 281: .Xr mandoc.db 5 ,
! 282: .Xr man.cgi 8
CVSweb