Standard CGI Implementation

The Common Gateway Interface (CGI) is a standard for interfacing external applications with information servers, such as HTTP or Web servers. A plain HTML document retrieved by a Web daemon is a static text file that doesn't change. A CGI program, on the other hand, is executed in real-time and able to output dynamic content.

CGI script are written in any language that can read STDIN, write to STDOUT, and read environment variables. This means that virtually any programming language can be used, including C, Perl, or even shell scripting.

Note: this WebServer documentation does not provide instructions on how to write CGI scripts for processing Web forms; however, numerous books and Websites are readily available that do an excellent job in covering this basic information.

In WebServer 2.0, GoForms CGI processing was accomplished by instructing the webs module to treat all URLs beginning with "/goform" as GoForms. Using a similar mechanism, WebServer 2.1 has a new "handler" that is called when URL requests are received for URLs beginning with
"/cgi-bin". CGI executable processes must be located in the WebServer's cgi-bin subdirectory. Separate processes will be created for each CGI request.

CGI for VxWorks

CGI's standard implementation requires that standalone processes be executed and their outputs returned to the browser via the WebServer. In VxWorks, processes are not implemented, but rather tasks are. In addition to understanding the mechanisms used in the implementation of VxWorks CGI tasks, developers of CGI processes must be aware of the differences between processes on other operating systems and tasks on VxWorks.

    1. VxWorks tasks can be spawned using code already loaded in memory. On VxWorks systems with no file system, the CGI task code can be included in the OS image and is not necessarily contained in a file.
    2. If the CGI code is contained in a file, a browser request for it will cause it to be loaded into memory prior to its execution. It will be unloaded and reloaded each time it is invoked, which allows the upgrading to a new version between invocation.
    3. The VxWorks taskSpawn API is used to spawn the CGI task.
    4. An entry point symbol name must be used to spawn the task. The request for the CGI process can define this entry point name in the request by including the query string keyword=value pair "cgientry=symbolname", where symbolname is a function name in the CGI code that is to be executed. If cgientry is not defined in this way, a default entry name will be searched for in the loaded code. The default name is "basename_cgientry", where basename is the name of the requested CGI process minus any file extension or path info (e.g., if the request is for "cgi-bin/cgitest.out", the default entry point symbol name will be "cgitest_cgientry"). If the entry point symbol name is not found or if the requested module cannot be loaded, the CGI request will fail.
    5. The priority of the spawned task will be the same priority at which WebServer is running.
    6. The stack size of the spawned task is 20,000 bytes.
    7. The task name will be the same as the entry point name.
    8. The standard CGI environment variables are copied to the task environment. They can be retrieved/modified by the getenv/putenv APIs.
    9. Command line arguments (if any) are passed to the user's entry point via an (int argc, char **argv) standard convention, where argc is the number of arguments and argv is an array of strings.
    10. As in standard CGI processes, the VxWorks CGI task can retrieve additional POST data from standard input device and must write any output to be returned to the client to the standard output device. These devices are actually temporary files where stdin and stdout have been redirected.
    11. User-defined CGI task codes should always be terminated with a return rather than an exit API. This allows environment space and redirected I/O files used by the task to be cleaned up and released back to the operating system appropriately.

Environment Variables

Input to Standard CGIs is accomplished mainly through these environment variables:

SERVER_SOFTWARE
The name and version of the information server software answering the request (and running the gateway).
Format: name/version

SERVER_NAME
The server's hostname, DNS alias, or IP address as it would appear in self-referencing URLs.

GATEWAY_INTERFACE
The revision of the CGI specification used by this server.
Format: CGI/revision

SERVER_PROTOCOL
The name and revision of the information protocol used by this request.
Format: protocol/revision

SERVER_PORT
The port number receiving the request.

REQUEST_METHOD
The method used to make the request. For HTTP, this is "GET", "HEAD", "POST", etc.

PATH_INFO
The extra path information, as given by the client. In other words, scripts can be accessed by their virtual pathname, followed by extra information at the end of this path. The extra information is sent as PATH_INFO. The server decodes this information before it is passed to the CGI script.

PATH_TRANSLATED
The server provides a translated version of PATH_INFO, which completes a virtual-to-physical mapping of the path as required.

SCRIPT_NAME
A virtual path to the script being executed for self-referencing URLs.

QUERY_STRING
The information which follows the "?" in the URL which referenced this script. This is the query information. It is not decoded in any fashion. This variable is always set when there is query information, regardless of command line decoding.

REMOTE_HOST
The hostname making the request. If the server does not have this information, it will set REMOTE_ADDR and leave this unset.

REMOTE_ADDR
The IP address of the remote host making the request.

AUTH_TYPE
If the script is protected, this is the protocol-specific authentication method used to validate the user.

REMOTE_USER
If the script is protected, this is the authenticated username.

REMOTE_IDENT
This variable is set to the remote user name retrieved from the server. Use of this variable should be limited to logging only.

CONTENT_TYPE
For queries having attached information, such as HTTP POST and PUT, this identifies the content type of the data.

CONTENT_LENGTH
The length of the said content as given by the client.

HTTP_ACCEPT
The MIME types accepted by the client, as given by HTTP headers. Other protocols may need to receive this information from elsewhere. Each item in this list should be separated by commas as specified by HTTP.
Format: type/subtype, type/subtype.

HTTP_USER_AGENT
The browser being used by the client to send the request. General format: software/version library/version.

Standard CGI Implementation Data Structures

The data structures provided for GoForms function for standard CGI implementation.