From d833b799cd708b10cde5d13af89d42f0b4d95758 Mon Sep 17 00:00:00 2001 From: Rich Bowen Date: Mon, 21 Jan 2002 03:21:26 +0000 Subject: [PATCH] Patches applied to the 1.3 docs. See versions 1.36 - 1.39 of mod_include in 1.3. Primarily clarification of exec cgi vs include virtual. git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@92960 13f79535-47bb-0310-9956-ffa450edef68 --- docs/manual/mod/mod_include.html | 120 ++++++++++++++++++++++--------- 1 file changed, 88 insertions(+), 32 deletions(-) diff --git a/docs/manual/mod/mod_include.html b/docs/manual/mod/mod_include.html index d1c3c8913a..dcb4531a86 100644 --- a/docs/manual/mod/mod_include.html +++ b/docs/manual/mod/mod_include.html @@ -109,20 +109,20 @@ valid attributes are:
-
errmsg
+
errmsg
The value is a message that is sent back to the client if an error occurs whilst parsing the document.
-
sizefmt
+
sizefmt
The value sets the format to be used which displaying the size of a file. Valid values are bytes for a count in bytes, or abbrev for a count in Kb or Mb as appropriate.
-
timefmt
+
timefmt
The value is a string to be used by the strftime(3) library routine when printing @@ -133,17 +133,18 @@
echo
- This command prints one of the include variables, defined + This command prints one of the include + variables, defined below. If the variable is unset, it is printed as (none). Any dates printed are subject to the currently configured timefmt. Attributes:
-
var
+
var
The value is the name of the variable to print.
-
encoding
+
encoding
Specifies how Apache should encode special characters contained in the variable before outputting them. If set @@ -177,7 +178,7 @@ completely. The valid attributes are:
-
cgi
+
cgi
The value specifies a (%-encoded) URL relative path to @@ -198,19 +199,51 @@ addition to the standard CGI environment.

+

For example:

+ + <!--#exec cgi="/cgi-bin/example.cgi" --> +

If the script returns a Location: header instead of output, then this will be translated into an HTML anchor.

-

The include virtual element should be - used in preference to exec cgi.

+

The include + virtual element should be + used in preference to exec cgi. In particular, + if you need to pass additional arguments to a CGI program, + using the query string, this cannot be done with exec + cgi, but can be done with include + virtual, as shown here:

+ + <!--#include virtual="/cgi-bin/example.cgi?argument=value" -->
-
cmd
+
cmd
-
The server will execute the given string using - /bin/sh. The include variables are available - to the command.
+
+

The server will execute the given string using + /bin/sh. The include variables are available + to the command, in addition to the usual set of CGI + variables.

+ +

The use of #include + virtual is almost always + prefered to using either #exec cgi or #exec + cmd. The former (#include virtual) used the + standard Apache sub-request mechanism to include files or + scripts. It is much better tested and maintained.

+ +

In addition, on some platforms, like Win32, and on unix + when using suexec, you cannot pass arguments to a command in + an exec directive, or otherwise include spaces in + the command. Thus, while the following will work under a + non-suexec configuration on unix, it will not produce the + desired result under Win32, or when running suexec:

+ + <!--#exec cmd="perl /path/to/perlscript arg1 arg2" --> + +
@@ -222,12 +255,12 @@ Attributes:
-
file
+
file
The value is a path relative to the directory containing the current document being parsed.
-
virtual
+
virtual
The value is a (%-encoded) URL-path relative to the current document being parsed. If it does not begin with @@ -264,62 +297,85 @@ command. The valid attributes are:

-
file
+
file
The value is a path relative to the directory containing the current document being parsed. It cannot contain ../, nor can it be an absolute path. + Therefore, you cannot include files that are outside of the + document root, or above the current document in the directory + structure. The virtual attribute should always be used in preference to this one.
-
virtual
+
virtual
-
The value is a (%-encoded) URL relative to the +
+

The value is a (%-encoded) URL relative to the current document being parsed. The URL cannot contain a scheme or hostname, only a path and an optional query string. If it does not begin with a slash (/) then it is - taken to be relative to the current document.

-
- A URL is constructed from the attribute, and the output the + taken to be relative to the current document.

+ +

A URL is constructed from the attribute, and the output the server would return if the URL were accessed by the client is included in the parsed output. Thus included files can - be nested. + be nested.

+ +

If the specified URL is a CGI program, the program will + be executed and its output inserted in place of the directive + in the parsed file. You may include a query string in a CGI + url:

+ + <!--#include virtual="/cgi-bin/example.cgi?argument=value" --> + +

include virtual should be used in preference + to exec cgi to include the output of CGI + programs into an HTML document. +

+
printenv
-
This prints out a listing of all existing variables and +
+

This prints out a listing of all existing variables and their values. Starting with Apache 1.3.12, special characters are entity encoded (see the echo element for details) - before being output. No attributes.

+ before being output. There are no attributes.

-
For example: <!--#printenv -->
+

For example:

-
Apache 1.2 and above.
+

<!--#printenv -->

+

The printenv element is available only in + Apache 1.2 and above.

+
set
This sets the value of a variable. Attributes:
-
var
+
var
The name of the variable to set.
-
value
+
value
The value to give a variable.
+

For example: <!--#set var="category" value="help" - --> -

+ -->

-
Apache 1.2 and above.
+

The set element is available only in + Apache 1.2 and above.

+
-

Include Variables

+

Include Variables

In addition to the variables in the standard CGI environment, these are available for the echo command, for if and elif, and to any program -- 2.50.1