man.cgi.3

   1 .\"     $Id: man.cgi.3,v 1.1 2016/04/15 21:16:22 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: April 15 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 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