contrib/mdocml/man.cgi.3

   1 .\"     $Id: man.cgi.3,v 1.2 2016/07/07 19:19:01 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 7 2016 $
  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 if
  59 .Ev PATH_INFO
  60 is empty, calls
  61 .Fn parse_query_string ;
  62 otherwise,
  63 calls
  64 .Fn parse_path_info ;
  65 .It
  66 validates the manpath and the architecture;
  67 .It
  68 calls the appropriate one among the
  69 .Sx Page generators .
  70 .El
  71 .It Ft void Fn parse_manpath_conf "struct req *req"
  72 Parses and validates
  73 .Pa manpath.conf
  74 and fills
  75 .Va req->p
  76 and
  77 .Va req->psz .
  78 .It Ft void Fn parse_path_info "struct req *req" "const char *path"
  79 Parses and validates
  80 .Ev PATH_INFO ,
  81 clears
  82 .Va req->isquery ,
  83 and fills
  84 .Va req->q .
  85 .It Ft void Fn parse_query_string "struct req *req" "const char *qs"
  86 Parses and validates
  87 .Ev QUERY_STRING ,
  88 sets
  89 .Va req->isquery ,
  90 and fills
  91 .Va req->q .
  92 This function is the only user of the utility functions
  93 .Fn http_decode
  94 and
  95 .Fn set_query_attr .
  96 .El
  97 .Ss Page generators
  98 The purpose of each page generator is to print a complete HTML page,
  99 starting with the HTTP headers and continuing to the page footer.
 100 Before starting HTML output with
 101 .Fn resp_begin_html ,
 102 some page generators do some preparatory work, for example to decide
 103 which page to show.
 104 Each page generator ends with a call to
 105 .Fn resp_end_html .
 106 .Bl -tag -width 1n
 107 .It Ft void Fn pg_show "struct req *req" "const char *fullpath"
 108 This page generator is used when
 109 .Ev PATH_INFO
 110 contains the complete path to a manual page including manpath,
 111 section directory, optional architecture subdirectory, manual name
 112 and section number suffix.
 113 It validates the manpath, changes into it, validate the filename,
 114 and then calls
 115 .Fn resp_begin_html ,
 116 .Fn resp_searchform ,
 117 .Fn resp_show ,
 118 and
 119 .Fn resp_end_html
 120 in that order.
 121 .It Ft void Fn pg_search "const struct req *req"
 122 This page generator is used when
 123 .Ev PATH_INFO
 124 contains a search query in short format or when
 125 .Ev PATH_INFO
 126 is empty and a
 127 .Ev QUERY_STRING
 128 is provided.
 129 It changes into the manpath and calls
 130 .Xr mansearch 3 .
 131 Depending on the result, it calls either
 132 .Fn pg_noresult
 133 or
 134 .Fn pg_searchres .
 135 .It Ft void Fn pg_noresult "const struct req *req" "const char *msg"
 136 This function calls
 137 .Fn resp_begin_html ,
 138 .Fn resp_searchform ,
 139 prints the
 140 .Fa msg
 141 passed to it, and calls
 142 .Fn resp_end_html .
 143 .It Ft void Fn pg_searchres "const struct req *req" "struct manpage *r"\
 144  "size_t sz"
 145 This function first validates the filenames found.
 146 If
 147 .Ev QUERY_STRING
 148 was used and there is exactly one result,
 149 it writes an HTTP redirect to that result.
 150 Otherwise, it writes an HTML result page beginning with
 151 .Fn resp_begin_html
 152 and
 153 .Fn resp_searchform .
 154 If there is more than one result, it writes a list of links
 155 to all the results.
 156 If it was a
 157 .Xr man 1
 158 rather than an
 159 .Xr apropos 1
 160 query or if there is only one single result, it calls
 161 .Fn resp_show .
 162 Finally, it calls
 163 .Fn resp_end_html .
 164 .It Ft void Fn pg_index "const struct req *req"
 165 This page generator is used when
 166 .Ev PATH_INFO
 167 and
 168 .Ev QUERY_STRING
 169 are both empty.
 170 It calls
 171 .Fn resp_begin_html
 172 and
 173 .Fn resp_searchform ,
 174 writes links to help pages, and calls
 175 .Fn resp_end_html .
 176 .It Ft void Fn pg_error_badrequest "const char *msg"
 177 This page generator is used when
 178 .Fn main
 179 or
 180 .Fn pg_show
 181 detect an invalid URI.
 182 It calls
 183 .Fn resp_begin_html ,
 184 prints the
 185 .Fa msg
 186 provided, and calls
 187 .Fn resp_end_html .
 188 .It Ft void Fn pg_error_internal void
 189 This page generator is used by various functions when errors are
 190 detected in the
 191 .Pa manpath.conf
 192 configuration file, in
 193 .Xr mandoc.db 5
 194 databases, in the
 195 .Xr mandoc 3
 196 parser, in file system permissions, or when setting up timeouts.
 197 It calls
 198 .Fn resp_begin_html ,
 199 prints
 200 .Qq "Internal Server Error" ,
 201 and calls
 202 .Fn resp_end_html .
 203 Before calling
 204 .Fn pg_error_internal ,
 205 call
 206 .Xr warn 3
 207 or
 208 .Xr warnx 3
 209 to log the reason of the error to the
 210 .Xr httpd 8
 211 server log file.
 212 .El
 213 .Ss Result generators
 214 The purpose of result generators is to print a chunk of HTML code.
 215 When they print untrusted strings or characters,
 216 .Fn html_print
 217 and
 218 .Fn html_putchar
 219 are used.
 220 The highest level result generators are:
 221 .Bl -tag -width 1n
 222 .It Ft void Fn resp_begin_html "int code" "const char *msg"
 223 This generator calls
 224 .Fn resp_begin_http
 225 to print the HTTP headers, then prints the HTML header up to the
 226 opening tag of the <body> element, then copies the file
 227 .Pa header.html
 228 to the output, if it exists and is readable.
 229 .It Ft void Fn resp_searchform "const struct req *req" "enum focus focus"
 230 This generator prints a search form, filling it with data
 231 from the provided request object.
 232 If the
 233 .Fa focus
 234 argument is
 235 .Dv FOCUS_QUERY ,
 236 it sets the document's autofocus to the query input box.
 237 .It Ft void Fn resp_show "const struct req *req" "const char *file"
 238 This wrapper dispatches to either
 239 .Fn resp_catman
 240 or
 241 .Fn resp_format ,
 242 depending on whether
 243 .Ar file
 244 starts with
 245 .Pa cat
 246 or
 247 .Pa man ,
 248 respectively.
 249 .It Ft void Fn resp_catman "const struct req *req" "const char *file"
 250 This generator translates a preformatted, backspace-encoded manual
 251 page to HTML and prints it to the output.
 252 .It Ft void Fn resp_format "const struct req *req" "const char *file"
 253 This generator formats a manual page on the standard output,
 254 using the functions documented in
 255 .Xr mchars_alloc 3
 256 and
 257 .Xr mandoc 3 .
 258 .It Ft void Fn resp_end_html void
 259 This generator copies the file
 260 .Pa footer.html
 261 to the output, if it exists and is readable,
 262 and closes the <body> and <html> elements.
 263 .El
 264 .Ss Utility routines
 265 These functions take a string and return 1 if it is valid, or 0 otherwise.
 266 .Bl -tag -width 1n
 267 .It Ft int Fn validate_urifrag "const char *frag"
 268 Checks that the string only contains alphanumeric ASCII characters,
 269 dashes, dots, slashes, and underscores.
 270 .It Ft int Fn validate_manpath "const struct req *req" "const char* manpath"
 271 Checks that the string is either
 272 .Qq mandoc
 273 or one of the manpaths configured in
 274 .Pa manpath.conf .
 275 .It Ft int Fn validate_filename "const char *file"
 276 Checks that the string starts with
 277 .Qq man
 278 or
 279 .Qq cat
 280 and does not ascend to parent directories.
 281 .El
 282 .Sh SEE ALSO
 283 .Xr mandoc 3 ,
 284 .Xr mansearch 3 ,
 285 .Xr mchars_alloc 3 ,
 286 .Xr mandoc.db 5 ,
 287 .Xr man.cgi 8