Main Page   Alphabetical List   Data Structures   File List   Data Fields   Globals  

cgi.c File Reference

Declares functions to intercept request, generate html or gif answers, and to compose HTTP resonses. More...


Functions

http_response * dispatch_known_cgi (struct client_state *csp, const char *path)
map * parse_cgi_parameters (char *argstring)
http_response * dispatch_cgi (struct client_state *csp)
char get_char_param (const struct map *parameters, const char *param_name)
jb_err get_string_param (const struct map *parameters, const char *param_name, const char **pparam)
jb_err get_number_param (struct client_state *csp, const struct map *parameters, char *name, unsigned *pvalue)
http_response * error_response (struct client_state *csp, const char *templatename, int sys_err)
void cgi_init_error_messages (void)
http_response * cgi_error_memory (void)
jb_err cgi_error_no_template (struct client_state *csp, struct http_response *rsp, const char *template_name)
jb_err cgi_error_unknown (struct client_state *csp, struct http_response *rsp, jb_err error_to_report)
jb_err cgi_error_bad_param (struct client_state *csp, struct http_response *rsp)
char * add_help_link (const char *item, struct configuration_spec *config)
void get_http_time (int time_offset, char *buf)
http_response * finish_http_response (struct http_response *rsp)
http_response * alloc_http_response (void)
void free_http_response (struct http_response *rsp)
jb_err template_load (struct client_state *csp, char **template_ptr, const char *templatename, int recursive)
jb_err template_fill (char **template_ptr, const struct map *exports)
jb_err template_fill_for_cgi (struct client_state *csp, const char *templatename, struct map *exports, struct http_response *rsp)
map * default_exports (const struct client_state *csp, const char *caller)
jb_err map_block_killer (struct map *exports, const char *name)
jb_err map_block_keep (struct map *exports, const char *name)
jb_err map_conditional (struct map *exports, const char *name, int choose_first)
char * make_menu (const char *self)
char * dump_map (const struct map *the_map)

Variables

const char cgi_rcs [] = "$Id: cgi.c,v 2.1 2002/06/04 17:55:24 jongfoster Exp $"
const char cgi_h_rcs [] = CGI_H_VERSION
const struct cgi_dispatcher cgi_dispatchers []
const char image_pattern_data []
const char image_blank_data []
const size_t image_pattern_length = sizeof(image_pattern_data) - 1
const size_t image_blank_length = sizeof(image_blank_data) - 1
http_response cgi_error_memory_response [1]

Detailed Description

Declares functions to intercept request, generate html or gif answers, and to compose HTTP resonses.

This only contains the framework functions, the actual handler functions are declared elsewhere.

Functions declared include:

Log:
cgi.c,v
Revision 2.1 2002/06/04 17:55:24 jongfoster Adding comments

Revision 2.0 2002/06/04 14:34:21 jongfoster Moving source files to src/

Revision 1.70 2002/05/19 11:33:20 jongfoster If a CGI error was not handled, and propogated back to dispatch_known_cgi(), then it was assumed to be "out of memory". This gave a very misleading error message.

Now other errors will cause a simple message giving the error number and asking the user to report a bug.

Bug report: http://sourceforge.net/tracker/index.php?func=detail &aid=557905&group_id=11118&atid=111118

Revision 1.69 2002/05/14 21:28:40 oes

Revision 1.68 2002/05/12 21:36:29 jongfoster Correcting function comments

Revision 1.67 2002/04/30 12:02:07 oes Nit: updated a comment

Revision 1.66 2002/04/26 18:32:57 jongfoster Fixing a memory leak on error

Revision 1.65 2002/04/26 12:53:51 oes

Revision 1.64 2002/04/24 02:17:21 oes Revision 1.63 2002/04/15 19:06:43 jongfoster Typos

Revision 1.62 2002/04/10 19:59:46 jongfoster Fixes to include in templates:

Revision 1.61 2002/04/10 13:37:48 oes Made templates modular: template_load now recursive with max depth 1

Revision 1.60 2002/04/08 20:50:25 swa fixed JB spelling

Revision 1.59 2002/04/05 15:51:51 oes

Revision 1.58 2002/03/29 03:33:13 david__schmidt Fix Mac OSX compiler warnings

Revision 1.57 2002/03/26 22:29:54 swa we have a new homepage!

Revision 1.56 2002/03/24 17:50:46 jongfoster Fixing compile error if actions file editor disabled

Revision 1.55 2002/03/24 16:55:06 oes Making GIF checkerboard transparent

Revision 1.54 2002/03/24 16:18:15 jongfoster Removing old logo

Revision 1.53 2002/03/24 16:06:00 oes Correct transparency for checkerboard PNG. Thanks, Magnus!

Revision 1.52 2002/03/24 15:23:33 jongfoster Name changes

Revision 1.51 2002/03/24 13:25:43 swa name change related issues

Revision 1.50 2002/03/16 23:54:06 jongfoster Adding graceful termination feature, to help look for memory leaks. If you enable this (which, by design, has to be done by hand editing config.h) and then go to http://i.j.b/die, then the program will exit cleanly after the *next* request. It should free all the memory that was used.

Revision 1.49 2002/03/13 00:27:04 jongfoster Killing warnings

Revision 1.48 2002/03/08 17:47:07 jongfoster Adding comments

Revision 1.47 2002/03/08 16:41:33 oes Added GIF images again

Revision 1.46 2002/03/07 03:48:38 oes

Revision 1.45 2002/03/06 22:54:35 jongfoster Automated function-comment nitpicking.

Revision 1.44 2002/03/05 22:43:45 david__schmidt

Revision 1.43 2002/03/05 21:33:45 david__schmidt Revision 1.42 2002/01/21 00:33:20 jongfoster Replacing strsav() with the safer string_append() or string_join(). Adding map_block_keep() to save a few bytes in the edit-actions-list HTML. Adding missing html_encode() to error message generators. Adding edit-actions-section-swap and many "shortcuts" to the list of CGIs.

Revision 1.41 2002/01/17 20:56:22 jongfoster Replacing hard references to the URL of the config interface with defines from project.h

Revision 1.40 2002/01/09 14:26:46 oes Added support for thread-safe gmtime_r call.

Revision 1.39 2001/11/16 00:48:13 jongfoster Fixing a compiler warning

Revision 1.38 2001/11/13 00:31:21 jongfoster

Revision 1.37 2001/11/01 14:28:47 david__schmidt Show enablement/disablement status in almost all templates. There is a little trickiness here: apparent recursive resolution of @if-enabled-then@ caused the toggle template to show status out-of-phase with the actual enablement status. So a similar construct, @if-enabled-display-then@, is used to resolve the status display on non-'toggle' templates.

Revision 1.36 2001/10/26 17:33:27 oes marginal bugfix

Revision 1.35 2001/10/23 21:48:19 jongfoster Cleaning up error handling in CGI functions - they now send back a HTML error page and should never cause a FATAL error. (Fixes one potential source of "denial of service" attacks).

CGI actions file editor that works and is actually useful.

Ability to toggle Junkbuster remotely using a CGI call.

You can turn off both the above features in the main configuration file, e.g. if you are running a multi-user proxy.

Revision 1.34 2001/10/18 22:22:09 david__schmidt Only show "Local support" on templates conditionally:

Revision 1.33 2001/10/14 22:28:41 jongfoster Fixing stupid typo.

Revision 1.32 2001/10/14 22:20:18 jongfoster

Revision 1.31 2001/10/10 10:56:39 oes Failiure to load template now fatal. Before, the user got a hard-to-understand assertion failure from cgi.c

Revision 1.30 2001/10/02 15:30:57 oes Introduced show-request cgi

Revision 1.29 2001/09/20 15:47:44 steudten

Fix BUG: Modify int size to size_t size in fill_template()

Revision 1.28 2001/09/19 18:00:37 oes Revision 1.27 2001/09/16 17:08:54 jongfoster Moving simple CGI functions from cgi.c to new file cgisimple.c

Revision 1.26 2001/09/16 15:47:37 jongfoster First version of CGI-based edit interface. This is very much a work-in-progress, and you can't actually use it to edit anything yet. You must define FEATURE_CGI_EDIT_ACTIONS for these changes to have any effect.

Revision 1.25 2001/09/16 15:02:35 jongfoster Adding i.j.b/robots.txt. Inlining add_stats() since it's only ever called from one place.

Revision 1.24 2001/09/16 11:38:01 jongfoster Splitting fill_template() into 2 functions: template_load() loads the file template_fill() performs the PCRS regexps. This is because the CGI edit interface has a "table row" template which is used many times in the page - this change means it's only loaded from disk once.

Revision 1.23 2001/09/16 11:16:05 jongfoster Better error handling in dispatch_cgi() and parse_cgi_parameters()

Revision 1.22 2001/09/16 11:00:10 jongfoster New function alloc_http_response, for symmetry with free_http_response

Revision 1.21 2001/09/13 23:53:03 jongfoster Support for both static and dynamically generated CGI pages. Correctly setting Last-Modified: and Expires: HTTP headers.

Revision 1.20 2001/09/13 23:40:36 jongfoster (Cosmetic only) Indentation correction

Revision 1.19 2001/09/13 23:31:25 jongfoster Moving image data to cgi.c rather than cgi.h.

Revision 1.18 2001/08/05 16:06:20 jongfoster Modifiying "struct map" so that there are now separate header and "map_entry" structures. This means that functions which modify a map no longer need to return a pointer to the modified map. Also, it no longer reverses the order of the entries (which may be important with some advanced template substitutions).

Revision 1.17 2001/08/05 15:57:38 oes Adapted finish_http_response to new list_to_text

Revision 1.16 2001/08/01 21:33:18 jongfoster Changes to fill_template() that reduce memory usage without having an impact on performance. I also renamed some variables so as not to clash with the C++ keywords "new" and "template".

Revision 1.15 2001/08/01 21:19:22 jongfoster Moving file version information to a separate CGI page.

Revision 1.14 2001/08/01 00:19:03 jongfoster New function: map_conditional() for an if-then-else syntax. Changing to use new version of show_defines()

Revision 1.13 2001/07/30 22:08:36 jongfoster Tidying up defines:

Revision 1.12 2001/07/29 18:47:05 jongfoster Adding missing include "loadcfg.h"

Revision 1.11 2001/07/18 17:24:37 oes Changed to conform to new pcrs interface

Revision 1.10 2001/07/13 13:53:13 oes Removed all ifdef PCRS and related code

Revision 1.9 2001/06/29 21:45:41 oes Indentation, CRLF->LF, Tab-> Space

Revision 1.8 2001/06/29 13:21:46 oes

Revision 1.7 2001/06/09 10:51:58 jongfoster Changing "show URL info" handler to new style. Changing BUFSIZ ==> BUFFER_SIZE

Revision 1.6 2001/06/07 23:05:19 jongfoster Removing code related to old forward and ACL files.

Revision 1.5 2001/06/05 19:59:16 jongfoster Fixing multiline character string (a GCC-only "feature"), and snprintf (it's _snprintf under VC++).

Revision 1.4 2001/06/04 10:41:52 swa show version string of cgi.h and cgi.c

Revision 1.3 2001/06/03 19:12:16 oes introduced new cgi handling

No revisions before 1.3

Function Documentation

char* add_help_link (  const char *    item,
struct configuration_spec *    config
) 
 

Produce a copy of the string given as item, embedded in an HTML link to its corresponding section (item name in uppercase) in the actions chapter of the user manual, (whose URL is given in the config and defaults to our web site).

FIXME I currently only work for actions, and would like to be generalized for other topics.

Parameters:
item  item (will NOT be free()d.) It is assumed to be HTML-safe.
config  The current configuration.
Returns:
String with item embedded in link, or NULL on out-of-memory

struct http_response* alloc_http_response (  void    ) 
 

Allocates a new http_response structure.

Parameters : N/A

Returns:
pointer to a new http_response, or NULL.

jb_err cgi_error_bad_param (  struct client_state *    csp,
struct http_response *    rsp
) 
 

CGI function that is called if the parameters (query string) for a CGI were wrong.

Parameters:
csp  Current client state (buffers, headers, etc...)
rsp  http_response data structure for output
CGI Parameters:
None
Returns:
JB_ERR_OK on success JB_ERR_MEMORY on out-of-memory error.

struct http_response* cgi_error_memory (  void    ) 
 

Called if a CGI function runs out of memory.

Returns a statically-allocated error response. Parameters : N/A

Returns:
http_response data structure for output. This is statically allocated, for obvious reasons.

jb_err cgi_error_no_template (  struct client_state *    csp,
struct http_response *    rsp,
const char *    template_name
) 
 

Almost-CGI function that is called if a template cannot be loaded.

Note this is not a true CGI, it takes a template name rather than a map of parameters.

Parameters:
csp  Current client state (buffers, headers, etc...)
rsp  http_response data structure for output
template_name  Name of template that could not be loaded.
Returns:
JB_ERR_OK on success JB_ERR_MEMORY on out-of-memory error.

jb_err cgi_error_unknown (  struct client_state *    csp,
struct http_response *    rsp,
jb_err    error_to_report
) 
 

Almost-CGI function that is called if an unexpected error occurs in the top-level CGI dispatcher.

In this context, "unexpected" means "anything other than JB_ERR_MEMORY or JB_ERR_CGI_PARAMS" - CGIs are expected to handle all other errors internally, since they can give more relavent error messages that way. Note this is not a true CGI, it takes an error code rather than a map of parameters.

Parameters:
csp  Current client state (buffers, headers, etc...)
rsp  http_response data structure for output
error_to_report  Error code to report.
Returns:
JB_ERR_OK on success JB_ERR_MEMORY on out-of-memory error.

void cgi_init_error_messages (  void    ) 
 

Call at the start of the program to initialize the error message used by cgi_error_memory().

Parameters : N/A

Returns:
N/A

struct map* default_exports (  const struct client_state *    csp,
const char *    caller
) 
 

returns a struct map list that contains exports which are common to all CGI functions.

Parameters:
csp  Current client state (buffers, headers, etc...)
caller  name of CGI who calls us and which should be excluded from the generated menu. May be NULL.
Returns:
NULL if no memory, else a new map. Caller frees.

struct http_response* dispatch_cgi (  struct client_state *    csp ) 
 

Checks if a request URL has either the magical hostname CGI_SITE_1_HOST (usually http://p.p/) or matches CGI_SITE_2_HOST CGI_SITE_2_PATH (usually.

http //config.privoxy.org/). If so, it passes the (rest of the) path onto dispatch_known_cgi, which calls the relevant CGI handler function.

Parameters:
csp  Current client state (buffers, headers, etc...)
Returns:
http_response if match, NULL if nonmatch or handler fail

struct http_response * dispatch_known_cgi (  struct client_state *    csp,
const char *    path
)  [static]
 

Processes a CGI once dispatch_cgi has determined that it matches one of the magic prefixes.

Parses the path as a cgi name plus query string, prepares a map that maps CGI parameter names to their values, initializes the http_response struct, and calls the relevant CGI handler function.

Parameters:
csp  Current client state (buffers, headers, etc...)
path  Path of CGI, with the CGI prefix removed. Should not have a leading "/".
Returns:
http_response, or NULL on handler failure or out of memory.

char* dump_map (  const struct map *    the_map ) 
 

HTML-dump a map for debugging (as table).

Parameters:
the_map  map to dump
Returns:
string with HTML

struct http_response* error_response (  struct client_state *    csp,
const char *    templatename,
int    sys_err
) 
 

returns an http_response that explains the reason why a request failed.

Parameters:
csp  Current client state (buffers, headers, etc...)
templatename  Which template should be used for the answer
sys_err  system error number
Returns:
A http_response. If we run out of memory, this will be cgi_error_memory().

struct http_response* finish_http_response (  struct http_response *    rsp ) 
 

Fill in the missing headers in an http response, and flatten the headers to an http head.

Parameters:
rsp  pointer to http_response to be processed
Returns:
A http_response, usually the rsp parameter. On error, free()s rsp and returns cgi_error_memory()

void free_http_response (  struct http_response *    rsp ) 
 

Free the memory occupied by an http_response and its depandant structures.

Parameters:
rsp  pointer to http_response to be freed
Returns:
N/A

char get_char_param (  const struct map *    parameters,
const char *    param_name
) 
 

Get a single-character parameter passed to a CGI function.

Parameters:
parameters  map of cgi parameters
param_name  The name of the parameter to read
Returns:
Uppercase character on success, '\0' on error.

void get_http_time (  int    time_offset,
char *    buf
) 
 

Get the time in a format suitable for use in a HTTP header - e.g.: "Sun, 06 Nov 1994 08:49:37 GMT".

Parameters:
time_offset  Time returned will be current time plus this number of seconds.
buf  Destination for result. Must be long enough to hold 29 characters plus a trailing zero.
Returns:
N/A

jb_err get_number_param (  struct client_state *    csp,
const struct map *    parameters,
char *    name,
unsigned *    pvalue
) 
 

Get a non-negative integer from the parameters passed to a CGI function.

Parameters:
csp  Current client state (buffers, headers, etc...)
parameters  map of cgi parameters
name  Name of CGI parameter to read
pvalue  destination for value. Set to -1 on error.
Returns:
JB_ERR_OK on success JB_ERR_MEMORY on out-of-memory JB_ERR_CGI_PARAMS if the parameter was not specified or is not valid.

jb_err get_string_param (  const struct map *    parameters,
const char *    param_name,
const char **    pparam
) 
 

Get a string paramater, to be used as an ACTION_STRING or ACTION_MULTI paramater.

Validates the input to prevent stupid/malicious users from corrupting their action file.

Parameters:
parameters  map of cgi parameters
param_name  The name of the parameter to read
pparam  destination for paramater. Allocated as part of the map "parameters", so don't free it. Set to NULL if not specified.
Returns:
JB_ERR_OK on success, or if the paramater was not specified. JB_ERR_MEMORY on out-of-memory. JB_ERR_CGI_PARAMS if the paramater is not valid.

char* make_menu (  const char *    self ) 
 

Returns an HTML-formatted menu of the available unhidden CGIs, excluding the one given in <self> Parameters : self = name of CGI to leave out, can be NULL for complete listing.

Returns:
menu string, or NULL on out-of-memory error.

jb_err map_block_keep (  struct map *    exports,
const char *    name
) 
 

Convenience function.

Removes the markers used by map-block-killer, to save a few bytes. i.e. removes "@if-<name>-start@" and "@if-<name>-end@"

Parameters:
exports  map to extend
name  name of conditional block
Returns:
JB_ERR_OK on success JB_ERR_MEMORY on out-of-memory error.

jb_err map_block_killer (  struct map *    exports,
const char *    name
) 
 

Convenience function.

Adds a "killer" for the conditional HTML-template block <name>, i.e. a substitution of the regex "if-<name>-start.*if-<name>-end" to the given export list.

Parameters:
exports  map to extend
name  name of conditional block
Returns:
JB_ERR_OK on success JB_ERR_MEMORY on out-of-memory error.

jb_err map_conditional (  struct map *    exports,
const char *    name,
int    choose_first
) 
 

Convenience function.

Adds an "if-then-else" for the conditional HTML-template block <name>, i.e. a substitution of the form: @if-<name>-then@ True text @else-not-<name>@ False text @endif-<name>@ The control structure and one of the alternatives will be hidden.

Parameters:
exports  map to extend
name  name of conditional block
choose_first  nonzero for first, zero for second.
Returns:
JB_ERR_OK on success JB_ERR_MEMORY on out-of-memory error.

struct map * parse_cgi_parameters (  char *    argstring )  [static]
 

Parse a URL-encoded argument string into name/value pairs and store them in a struct map list.

Parameters:
argstring  string to be parsed. Will be trashed.
Returns:
pointer to param list, or NULL if out of memory.

jb_err template_fill (  char **    template_ptr,
const struct map *    exports
) 
 

CGI support function that fills in a pre-loaded HTML template by replacing @name@ with value using pcrs, for each item in the output map.

Note that a leading '$' charachter in the export map's values will be stripped and toggle on backreference interpretation.

Parameters:
template_ptr  IN: Template to be filled out. Will be free()d.

OUT Filled out template. Caller must free().

exports  map with fill in symbol -> name pairs
Returns:
JB_ERR_OK on success JB_ERR_MEMORY on out-of-memory error

jb_err template_fill_for_cgi (  struct client_state *    csp,
const char *    templatename,
struct map *    exports,
struct http_response *    rsp
) 
 

CGI support function that loads a HTML template and fills it in.

Handles file-not-found errors by sending a HTML error message. For convenience, this function also frees the passed "exports" map.

Parameters:
csp  Client state
templatename  name of the HTML template to be used
exports  map with fill in symbol -> name pairs. Will be freed by this function.
rsp  Response structure to fill in.
Returns:
JB_ERR_OK on success JB_ERR_MEMORY on out-of-memory error

jb_err template_load (  struct client_state *    csp,
char **    template_ptr,
const char *    templatename,
int    recursive
) 
 

CGI support function that loads a given HTML template from the confdir, ignoring comment lines and following include statements up to a depth of 1.

Parameters:
csp  Current client state (buffers, headers, etc...)
template_ptr  Destination for pointer to loaded template text.
templatename  name of the HTML template to be used
recursive  Flag set if this function calls itself following an include statament
Returns:
JB_ERR_OK on success JB_ERR_MEMORY on out-of-memory error. JB_ERR_FILE if the template file cannot be read

Variable Documentation

const struct cgi_dispatcher cgi_dispatchers[] [static]
 

List of CGI functions: name, handler, description.

Note: Do NOT use single quotes in the description; this will break the dynamic "blocked" template!

struct http_response cgi_error_memory_response[1] [static]
 

The "Out of memory" CGI response.

This is statically allocated and is initialized at startup, for obvious reasons. It's read-only. finish_http_response() and free_http_response() have been special-cased to do nothing if they are passed this structure.

const char cgi_h_rcs[] = CGI_H_VERSION
 

Version information about cgi.h.

const char cgi_rcs[] = "$Id: cgi.c,v 2.1 2002/06/04 17:55:24 jongfoster Exp $"
 

Version information about cgi.c.

const char image_blank_data[]
 

Initial value:

   "GIF89a\001\000\001\000\200\000\000\377\377\377\000\000"
   "\000!\371\004\001\000\000\000\000,\000\000\000\000\001"
   "\000\001\000\000\002\002D\001\000;"
1x1 transparant GIF.

const size_t image_blank_length = sizeof(image_blank_data) - 1
 

The size of the image_blank, in bytes.

const char image_pattern_data[]
 

Initial value:

   "\107\111\106\070\071\141\004\000\004\000\200\000\000\310\310"
   "\310\377\377\377\041\376\016\111\040\167\141\163\040\141\040"
   "\142\141\156\156\145\162\000\041\371\004\001\012\000\001\000"
   "\054\000\000\000\000\004\000\004\000\000\002\005\104\174\147"
   "\270\005\000\073"
Checkerboard pattern, as a GIF.

const size_t image_pattern_length = sizeof(image_pattern_data) - 1
 

The size of the image_pattern, in bytes.

Generated on Tue Jun 4 18:54:49 2002 for Privoxy 3.1.1 by doxygen1.2.15