You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@trafficserver.apache.org by jp...@apache.org on 2014/05/12 18:27:10 UTC
git commit: docs: fix literal blocks and broken links
Repository: trafficserver
Updated Branches:
refs/heads/master f8a086404 -> caf1bc13c
docs: fix literal blocks and broken links
This closes #81
Project: http://git-wip-us.apache.org/repos/asf/trafficserver/repo
Commit: http://git-wip-us.apache.org/repos/asf/trafficserver/commit/caf1bc13
Tree: http://git-wip-us.apache.org/repos/asf/trafficserver/tree/caf1bc13
Diff: http://git-wip-us.apache.org/repos/asf/trafficserver/diff/caf1bc13
Branch: refs/heads/master
Commit: caf1bc13c269aefe24fd6c0f25f7f4ed8805c563
Parents: f8a0864
Author: Masakazu Kitajo <m4...@gmail.com>
Authored: Mon May 12 00:05:56 2014 +0900
Committer: James Peach <jp...@apache.org>
Committed: Mon May 12 09:26:04 2014 -0700
----------------------------------------------------------------------
doc/admin/working-log-files.en.rst | 3 +-
doc/reference/configuration/icp.config.en.rst | 1 -
doc/sdk/actions-guide.en.rst | 10 +-
.../adding-statistics/coupled-statistics.en.rst | 3 +-
...viewing-statistics-using-traffic-line.en.rst | 4 +-
doc/sdk/continuations.en.rst | 2 +-
...gin-registration-and-version-checking.en.rst | 3 +-
...d-getting-a-handle-to-the-transaction.en.rst | 3 +-
.../setting-a-transaction-hook.en.rst | 3 +-
.../working-with-http-headers.en.rst | 6 +-
doc/sdk/http-headers.en.rst | 8 +-
...plicate-mime-fields-are-not-coalesced.en.rst | 2 +-
...s-belong-to-an-associated-mime-header.en.rst | 12 +--
doc/sdk/http-headers/http-headers.en.rst | 2 +-
doc/sdk/http-headers/mime-headers.en.rst | 8 +-
doc/sdk/http-headers/urls.en.rst | 2 -
.../adding-hooks.en.rst | 20 ++--
.../http-transactions.en.rst | 18 ++--
doc/sdk/http-transformation-plugin.en.rst | 4 +
.../append-transform-plugin.en.rst | 3 +-
...e-buffered-null-transformation-plugin.en.rst | 104 +++++++++----------
.../sample-null-transformation-plugin.en.rst | 35 +++----
doc/sdk/io-guide.en.rst | 10 +-
doc/sdk/io-guide/guide-to-cache-api.en.rst | 3 +-
.../io-guide/guide-to-cache-api/example.en.rst | 9 +-
doc/sdk/io-guide/transformations.en.rst | 9 +-
doc/sdk/io-guide/vios.en.rst | 3 +-
.../thread-functions.en.rst | 2 +-
doc/sdk/mutex-guide.en.rst | 68 ++++++------
doc/sdk/new-protocol-plugins.en.rst | 40 ++++---
doc/sdk/plugin-configurations.en.rst | 7 +-
.../guide-to-the-logging-api.en.rst | 31 ++++--
...trafficserver-settings-and-statistics.en.rst | 4 +-
doc/sdk/remap-plugin/example-query-remap.en.rst | 6 +-
doc/sdk/sample-source-code.en.rst | 7 +-
doc/sdk/troubleshooting-tips.en.rst | 2 -
.../debugging-memory-leaks.en.rst | 1 -
.../unable-to-debug-tags.en.rst | 6 +-
.../using-a-debugger.en.rst | 1 -
39 files changed, 214 insertions(+), 251 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/caf1bc13/doc/admin/working-log-files.en.rst
----------------------------------------------------------------------
diff --git a/doc/admin/working-log-files.en.rst b/doc/admin/working-log-files.en.rst
index 6c4701b..6c5626d 100644
--- a/doc/admin/working-log-files.en.rst
+++ b/doc/admin/working-log-files.en.rst
@@ -360,9 +360,8 @@ To create a summary log file format, we
:file:`logs_xml.config` as
follows:
- ::
+ .. code-block:: xml
- :::xml
<LogFormat>
<Name = "summary"/>
<Format = "%<operator(field)> : %<operator(field)>"/>
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/caf1bc13/doc/reference/configuration/icp.config.en.rst
----------------------------------------------------------------------
diff --git a/doc/reference/configuration/icp.config.en.rst b/doc/reference/configuration/icp.config.en.rst
index 877e459..d7b927d 100644
--- a/doc/reference/configuration/icp.config.en.rst
+++ b/doc/reference/configuration/icp.config.en.rst
@@ -97,7 +97,6 @@ one parent, and one sibling.
::
- :::text
localhost:0.0.0.0:3:8080:3130:0:0.0.0.0:1
host1:123.12.1.23:1:8080:3131:0:0.0.0.0:1
host2:123.12.1.24:2:8080:3131:0:0.0.0.0:1
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/caf1bc13/doc/sdk/actions-guide.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/actions-guide.en.rst b/doc/sdk/actions-guide.en.rst
index ec9a53d..e05e0ac 100644
--- a/doc/sdk/actions-guide.en.rst
+++ b/doc/sdk/actions-guide.en.rst
@@ -59,9 +59,8 @@ data because the continuation may have already been destroyed.
Below is an example of typical usage for an action:
-::
+.. code-block:: c
- ::::c
#include <ts/ts.h>
static int
handler (TSCont contp, TSEvent event, void *edata)
@@ -86,7 +85,7 @@ Below is an example of typical usage for an action:
return 0;
}
- void
+ void
TSPluginInit (int argc, const char *argv[])
{
TSCont contp;
@@ -120,9 +119,8 @@ schedule itself to get called back in 30 seconds and then initiate the
net connection. If the timeout expires first, then the plugin would
cancel the action. The following sample code implements this:
-::
+.. code-block:: c
- :::::c
#include <ts/ts.h>
static int
handler (TSCont contp, TSEvent event, void *edata)
@@ -159,7 +157,7 @@ cancel the action. The following sample code implements this:
return 0;
}
- void
+ void
TSPluginInit (int argc, const char *argv[])
{
TSCont contp;
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/caf1bc13/doc/sdk/adding-statistics/coupled-statistics.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/adding-statistics/coupled-statistics.en.rst b/doc/sdk/adding-statistics/coupled-statistics.en.rst
index 305350d..774f509 100644
--- a/doc/sdk/adding-statistics/coupled-statistics.en.rst
+++ b/doc/sdk/adding-statistics/coupled-statistics.en.rst
@@ -78,9 +78,8 @@ To add coupled statistics:
Example Using the redirect-1.c Sample Plugin
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-::
+.. code-block:: c
- :::c
static TSCoupledStat request_outcomes;
static TSStat requests_all;
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/caf1bc13/doc/sdk/adding-statistics/viewing-statistics-using-traffic-line.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/adding-statistics/viewing-statistics-using-traffic-line.en.rst b/doc/sdk/adding-statistics/viewing-statistics-using-traffic-line.en.rst
index 0e8785e..76327f1 100644
--- a/doc/sdk/adding-statistics/viewing-statistics-using-traffic-line.en.rst
+++ b/doc/sdk/adding-statistics/viewing-statistics-using-traffic-line.en.rst
@@ -28,6 +28,8 @@ To view statistics for your plugin, follow the steps below:
2. In your ``<Traffic Server>/bin`` directory, enter the following:
- ::::text ./traffic\_line -r the\_name
+ ::
+
+ ./traffic\_line -r the\_name
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/caf1bc13/doc/sdk/continuations.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/continuations.en.rst b/doc/sdk/continuations.en.rst
index 34e3a04..286cedc 100644
--- a/doc/sdk/continuations.en.rst
+++ b/doc/sdk/continuations.en.rst
@@ -83,7 +83,7 @@ Caveats that could cause issues include the following:
Below is an example, followed by an explanation.
-::
+.. code-block:: c
continuation_handler (TSCont contp, TSEvent event, void *edata) {
switch (event) {
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/caf1bc13/doc/sdk/getting-started/plugin-registration-and-version-checking.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/getting-started/plugin-registration-and-version-checking.en.rst b/doc/sdk/getting-started/plugin-registration-and-version-checking.en.rst
index 7b403b8..22ad893 100644
--- a/doc/sdk/getting-started/plugin-registration-and-version-checking.en.rst
+++ b/doc/sdk/getting-started/plugin-registration-and-version-checking.en.rst
@@ -29,9 +29,8 @@ Use the following interfaces:
The following version of ``hello-world`` registers the plugin and
ensures it's running with a compatible version of Traffic Server.
-::
+.. code-block:: c
- :::c
#include <stdio.h>
#include <ts/ts.h>
int
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/caf1bc13/doc/sdk/header-based-plugin-examples/basic-authorization-plugin/implementing-the-handler-and-getting-a-handle-to-the-transaction.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/header-based-plugin-examples/basic-authorization-plugin/implementing-the-handler-and-getting-a-handle-to-the-transaction.en.rst b/doc/sdk/header-based-plugin-examples/basic-authorization-plugin/implementing-the-handler-and-getting-a-handle-to-the-transaction.en.rst
index 5ea3f05..8b7b883 100644
--- a/doc/sdk/header-based-plugin-examples/basic-authorization-plugin/implementing-the-handler-and-getting-a-handle-to-the-transaction.en.rst
+++ b/doc/sdk/header-based-plugin-examples/basic-authorization-plugin/implementing-the-handler-and-getting-a-handle-to-the-transaction.en.rst
@@ -21,9 +21,8 @@ Implementing the Handler and Getting a Handle to the Transaction
The handler function for the plugin's parent continuation is implemented
as follows:
-::
+.. code-block:: c
- :::c
static int
auth_plugin (TSCont contp, TSEvent event, void *edata)
{
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/caf1bc13/doc/sdk/header-based-plugin-examples/basic-authorization-plugin/setting-a-transaction-hook.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/header-based-plugin-examples/basic-authorization-plugin/setting-a-transaction-hook.en.rst b/doc/sdk/header-based-plugin-examples/basic-authorization-plugin/setting-a-transaction-hook.en.rst
index c7c8708..1c877ff 100644
--- a/doc/sdk/header-based-plugin-examples/basic-authorization-plugin/setting-a-transaction-hook.en.rst
+++ b/doc/sdk/header-based-plugin-examples/basic-authorization-plugin/setting-a-transaction-hook.en.rst
@@ -27,9 +27,8 @@ then resend the request.
In the ``handle_dns`` routine, the following lines handle the
authorization error case:
-::
+.. code-block:: c
- :::c
done:
TSHttpTxnHookAdd (txnp, TS_HTTP_SEND_RESPONSE_HDR_HOOK, contp);
TSHttpTxnReenable (txnp, TS_EVENT_HTTP_ERROR);
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/caf1bc13/doc/sdk/header-based-plugin-examples/basic-authorization-plugin/working-with-http-headers.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/header-based-plugin-examples/basic-authorization-plugin/working-with-http-headers.en.rst b/doc/sdk/header-based-plugin-examples/basic-authorization-plugin/working-with-http-headers.en.rst
index 207ea73..9e26fe6 100644
--- a/doc/sdk/header-based-plugin-examples/basic-authorization-plugin/working-with-http-headers.en.rst
+++ b/doc/sdk/header-based-plugin-examples/basic-authorization-plugin/working-with-http-headers.en.rst
@@ -25,9 +25,8 @@ check the ``Proxy-Authorization`` field. The ``handle_dns`` routine uses
``TSHttpTxnClientReqGet`` and ``TSMimeHdrFieldFind`` to obtain the
``Proxy-Authorization`` field:
-::
+.. code-block:: c
- :::c
{
TSMBuffer bufp;
TSMLoc hdr_loc;
@@ -47,9 +46,8 @@ If the ``Proxy-Authorization`` field is present, then the plugin checks
that the authentication type is "Basic", and the user name and password
are present and valid:
-::
+.. code-block:: c
- :::c
val = TSMimeHdrFieldValueStringGet (bufp, hdr_loc, field_loc, -1, &authval_length);
if (!val) {
TSError ("no value in Proxy-Authorization field\n");
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/caf1bc13/doc/sdk/http-headers.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/http-headers.en.rst b/doc/sdk/http-headers.en.rst
index 2b42b92..167a1d5 100644
--- a/doc/sdk/http-headers.en.rst
+++ b/doc/sdk/http-headers.en.rst
@@ -52,7 +52,9 @@ A **MIME header** is comprised of zero or more MIME fields. A **MIME
field** is composed of a field name, a colon, and (zero or more) field
values. The values in a field are separated by commas. An HTTP header
containing a request line is usually referred to as a **request**. The
-following example shows a typical request header::
+following example shows a typical request header:
+
+.. code-block:: http
GET http://www.tiggerwigger.com/ HTTP/1.0
Proxy-Connection: Keep-Alive
@@ -64,7 +66,9 @@ following example shows a typical request header::
Accept-Charset: iso-8859-1, *, utf-8
The **response header** for the above request might look like the
-following::
+following:
+
+.. code-block:: http
HTTP/1.0 200 OK
Date: Fri, 13 Nov 2009 06:57:43 GMT
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/caf1bc13/doc/sdk/http-headers/guide-to-trafficserver-http-header-system/duplicate-mime-fields-are-not-coalesced.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/http-headers/guide-to-trafficserver-http-header-system/duplicate-mime-fields-are-not-coalesced.en.rst b/doc/sdk/http-headers/guide-to-trafficserver-http-header-system/duplicate-mime-fields-are-not-coalesced.en.rst
index 40d9cef..f354956 100644
--- a/doc/sdk/http-headers/guide-to-trafficserver-http-header-system/duplicate-mime-fields-are-not-coalesced.en.rst
+++ b/doc/sdk/http-headers/guide-to-trafficserver-http-header-system/duplicate-mime-fields-are-not-coalesced.en.rst
@@ -28,4 +28,4 @@ duplicate fields.
Properly-behaving plugins should check for the presence of duplicate
fields and then iterate over the duplicate fields via
-:ref:``TSMimeHdrFieldNextDup <http://people.apache.org/~amc/ats/doc/html/ts_8h.html#af2d776615afe959ed7c3639830a7061f>``.
+:c:func:`TSMimeHdrFieldNextDup`.
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/caf1bc13/doc/sdk/http-headers/guide-to-trafficserver-http-header-system/mime-fields-always-belong-to-an-associated-mime-header.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/http-headers/guide-to-trafficserver-http-header-system/mime-fields-always-belong-to-an-associated-mime-header.en.rst b/doc/sdk/http-headers/guide-to-trafficserver-http-header-system/mime-fields-always-belong-to-an-associated-mime-header.en.rst
index 66b2971..4603181 100644
--- a/doc/sdk/http-headers/guide-to-trafficserver-http-header-system/mime-fields-always-belong-to-an-associated-mime-header.en.rst
+++ b/doc/sdk/http-headers/guide-to-trafficserver-http-header-system/mime-fields-always-belong-to-an-associated-mime-header.en.rst
@@ -36,31 +36,27 @@ every deprecated *``TSMimeField``* function, there is a new, preferred
Instead of:
-::
+.. code-block:: c
- :::c
TSMLoc TSMimeFieldCreate (TSMBuffer bufp)
You should use:
-::
+.. code-block:: c
- :::c
TSMLoc TSMimeHdrFieldCreate (TSMBuffer bufp, TSMLoc hdr)
Instead of:
-::
+.. code-block:: c
- :::c
void TSMimeFieldCopyValues (TSMBuffer dest_bufp, TSMLoc dest_offset,
TSMBuffer src_bufp, TSMLoc src_offset)
You should use:
-::
+.. code-block:: c
- :::c
void TSMimeHdrFieldCopyValues (TSMBuffer dest_bufp, TSMLoc dest_hdr,
TSMLoc dest_field, TSMBuffer src_bufp, TSMLoc src_hdr, TSMLoc
src_field)
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/caf1bc13/doc/sdk/http-headers/http-headers.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/http-headers/http-headers.en.rst b/doc/sdk/http-headers/http-headers.en.rst
index f74f8a0..623bd7f 100644
--- a/doc/sdk/http-headers/http-headers.en.rst
+++ b/doc/sdk/http-headers/http-headers.en.rst
@@ -180,7 +180,7 @@ The **HTTP Header Functions** are listed below:
- :c:func:`TSHttpHdrVersionSet`
- :c:func:`TSHttpParserClear`
- :c:func:`TSHttpParserCreate`
-- `TSHttpParserDestroy <link/to/doxyge>`__
+- :c:func:`TSHttpParserDestroy`
- :c:func:`TSHttpHdrParseReq`
- :c:func:`TSHttpHdrParseResp`
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/caf1bc13/doc/sdk/http-headers/mime-headers.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/http-headers/mime-headers.en.rst b/doc/sdk/http-headers/mime-headers.en.rst
index 7796678..b0f0b6d 100644
--- a/doc/sdk/http-headers/mime-headers.en.rst
+++ b/doc/sdk/http-headers/mime-headers.en.rst
@@ -32,7 +32,6 @@ first MIME field value, and ``car`` is the second MIME field value.
::
- :::text
Foo: bar, car
The following example is an augmented **Backus-Naur Form** (BNF) for the
@@ -47,7 +46,6 @@ are all equivalent.
::
- :::text
MIME-header = *MIME-field
MIME-field = field-name ":" #field-value
field-name = *token
@@ -68,8 +66,8 @@ field and the field does not exist, then it returns ``TS_NULL_MLOC``. In
such a case, you wouldn't need to deallocate the handle with a call to
``TSHandleMLocRelease``.
-The location (``TSMLoc``) in the `MIME header
-functions <#MimeHeaderFxns>`__ can be either an HTTP header location or
+The location (``TSMLoc``) in the :ref:`MIME header
+functions <MimeHeaderFxns>` can be either an HTTP header location or
a MIME header location. If an HTTP header location is passed to these
functions, then the system locates the MIME header associated with that
HTTP header and executes the corresponding MIME header operations
@@ -391,6 +389,8 @@ custom log configuration file that explicitly logs such fields. This
provides a useful mechanism for plugins to store information about an
object in one of the MIME headers associated with the object.
+.. _MimeHeaderFxns:
+
The MIME header functions are listed below:
- :c:func:`TSMimeHdrFieldAppend`
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/caf1bc13/doc/sdk/http-headers/urls.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/http-headers/urls.en.rst b/doc/sdk/http-headers/urls.en.rst
index 91b74b5..0b24e63 100644
--- a/doc/sdk/http-headers/urls.en.rst
+++ b/doc/sdk/http-headers/urls.en.rst
@@ -27,7 +27,6 @@ The general form of an Internet URL is:
::
- :::text
scheme://user:password@host:port/stuff
The URL data structure includes support for two specific types of
@@ -35,7 +34,6 @@ internet URLs. HTTP URLs have the form:
::
- :::text
http://user:password@host:port/path;params?query#fragment
The URL port is stored as integer. All remaining parts of the URL
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/caf1bc13/doc/sdk/http-hooks-and-transactions/adding-hooks.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/http-hooks-and-transactions/adding-hooks.en.rst b/doc/sdk/http-hooks-and-transactions/adding-hooks.en.rst
index 04e3e94..6a3cbb4 100644
--- a/doc/sdk/http-hooks-and-transactions/adding-hooks.en.rst
+++ b/doc/sdk/http-hooks-and-transactions/adding-hooks.en.rst
@@ -29,21 +29,21 @@ There are several ways to add hooks to your plugin.
- **Transaction hooks** Transaction hooks can be used to call plugins
back for a specific HTTP transaction. You cannot add transaction
hooks in ``TSPluginInit``; you first need a handle to a transaction.
- See `Accessing the Transaction Being
- Processed <../header-based-plugin-examples/blacklist-plugin/accessing-the-transaction-being-processed>`__
+ See :doc:`Accessing the Transaction Being
+ Processed <../header-based-plugin-examples/blacklist-plugin/accessing-the-transaction-being-processed.en>`
- **Transformation hooks** Transformation hooks are a special case of
transaction hooks. See
:c:func:`TSVConnCacheObjectSizeGet`
for more information about transformation hooks. You add a
- transformation hook using ``TSHttpTxnHookAdd``, as described in `HTTP
- Transactions <HTTP_Transactions.html>`__.
+ transformation hook using ``TSHttpTxnHookAdd``, as described in :doc:`HTTP
+ Transactions <http-transactions.en>`.
- **Session hooks** An HTTP session starts when a client opens a
connection to Traffic Server and ends when the connection closes. A
session can consist of several transactions. Session hooks enable you
to hook your plugin to a particular point in every transaction within
- a specified session (see `HTTP Sessions <HTTPSessions.html>`__).
+ a specified session (see :doc:`HTTP Sessions <http-sessions.en>`).
Session hooks are added in a manner similar to transaction hooks (ie,
you first need a handle to an HTTP session).
@@ -51,7 +51,7 @@ There are several ways to add hooks to your plugin.
to hook on to the alternate selection state. These hooks must be
added globally, since Traffic Server does not have a handle to a
transaction or session when alternate selection is taking place. See
- `HTTP Alternate Selection <HTTPAlternateSelection.html>`__ for
+ :doc:`HTTP Alternate Selection <http-alternate-selection.en>` for
information on the alternate selection mechanism.
All of the hook addition functions
@@ -101,8 +101,7 @@ values for ``TSHttpHookID`` are:
``TS_EVENT_HTTP_READ_RESPONSE_HDR``.
``TS_HTTP_RESPONSE_TRANSFORM_HOOK``
- See
- "`"Transformations" <../http-transformation-plugin#Transformations>`__
+ See :ref:`"Transformations" <transformations>`
for information about transformation hooks.
``TS_HTTP_READ_REQUEST_HDR_HOOK``
@@ -110,12 +109,11 @@ values for ``TSHttpHookID`` are:
Corresponds to the event ``TS_EVENT_HTTP_READ_REQUEST_HDR``.
``TS_HTTP_REQUEST_TRANSFORM_HOOK``
- See
- "`"Transformations" <../http-transformation-plugin#Transformations>`__
+ See :ref:`"Transformations" <transformations>`
for information about transformation hooks.
``TS_HTTP_SELECT_ALT_HOOK``
- See `"HTTP Alternate Selection" <http-alternate-selection>`__ for
+ See :doc:`"HTTP Alternate Selection" <http-alternate-selection.en>` for
information about the alternate selection mechanism.
``TS_HTTP_SEND_RESPONSE_HDR_HOOK``
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/caf1bc13/doc/sdk/http-hooks-and-transactions/http-transactions.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/http-hooks-and-transactions/http-transactions.en.rst b/doc/sdk/http-hooks-and-transactions/http-transactions.en.rst
index e859fb2..7aad410 100644
--- a/doc/sdk/http-hooks-and-transactions/http-transactions.en.rst
+++ b/doc/sdk/http-hooks-and-transactions/http-transactions.en.rst
@@ -32,9 +32,8 @@ reference back to the HTTP session that created it.
The sample code below illustrates how to register locally to a
transaction and associate data to the transaction.
-::
+.. code-block:: c
- :::c
/*
* Simple plugin that illustrates:
* - how to register locally to a transaction
@@ -149,11 +148,10 @@ transaction and associate data to the transaction.
TSHttpHookAdd(TS_HTTP_TXN_START_HOOK, contp);
}
-See `Adding Hooks <adding-hooks>`__ for background about HTTP
-transactions and HTTP hooks, as well as `HTTP Hooks and
-Transactions <../http-hooks-and-transactions>`__ Also see the [HTTP
-Transaction State Diagram
-](HTTPHooksAndTransactions.html(../http-hooks-and-transactions#HHTTPTxStateDiag)
+See :doc:`Adding Hooks <adding-hooks.en>` for background about HTTP
+transactions and HTTP hooks, as well as :doc:`HTTP Hooks and
+Transactions <../http-hooks-and-transactions.en>` Also see the :ref:`HTTP
+Transaction State Diagram <http-txn-state-diagram>`
for an illustration of the steps involved in a typical HTTP transaction.
The HTTP transaction functions are:
@@ -166,11 +164,11 @@ The HTTP transaction functions are:
- :c:func:`TSHttpTxnCachedRespGet`
- Note that it is an error to modify cached headers.
-- `TSHttpTxnClientIncomingPortGet <link/to/doxygen>`__
+- :c:func:`TSHttpTxnClientIncomingPortGet`
-- `TSHttpTxnClientIPGet <link/to/doxygen>`__
+- :c:func:`TSHttpTxnClientIPGet`
-- `TSHttpTxnClientRemotePortGet <link/to/doxygen>`__
+- :c:func:`TSHttpTxnClientRemotePortGet`
- :c:func:`TSHttpTxnClientReqGet`
- Plugins that must read client request headers use this call to
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/caf1bc13/doc/sdk/http-transformation-plugin.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/http-transformation-plugin.en.rst b/doc/sdk/http-transformation-plugin.en.rst
index b78b5f6..f446401 100644
--- a/doc/sdk/http-transformation-plugin.en.rst
+++ b/doc/sdk/http-transformation-plugin.en.rst
@@ -42,6 +42,8 @@ examples are discussed in detail:
http-transformation-plugin/append-transform-plugin.en
http-transformation-plugin/sample-buffered-null-transformation-plugin.en
+.. _WritingContentTransformPlugin:
+
Writing Content Transform Plugins
---------------------------------
@@ -110,6 +112,8 @@ downstream ``VConnection``\ s send to it. The *user's side* refers to
how to use a ``VConnection`` to read or write data. At the very least,
transformations output (write) data.
+.. _transformations:
+
Transformations
~~~~~~~~~~~~~~~
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/caf1bc13/doc/sdk/http-transformation-plugin/append-transform-plugin.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/http-transformation-plugin/append-transform-plugin.en.rst b/doc/sdk/http-transformation-plugin/append-transform-plugin.en.rst
index 5896c57..47c6589 100644
--- a/doc/sdk/http-transformation-plugin/append-transform-plugin.en.rst
+++ b/doc/sdk/http-transformation-plugin/append-transform-plugin.en.rst
@@ -40,9 +40,8 @@ what the function does:
Allocates and initializes a ``MyData`` structure. The plugin defines
a struct, ``MyData``, as follows:
- ::
+ .. code-block:: c
- :::c
typedef struct {
TSVIO output_vio;
TSIOBuffer output_buffer;
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/caf1bc13/doc/sdk/http-transformation-plugin/sample-buffered-null-transformation-plugin.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/http-transformation-plugin/sample-buffered-null-transformation-plugin.en.rst b/doc/sdk/http-transformation-plugin/sample-buffered-null-transformation-plugin.en.rst
index f1e1b3a..ee6859b 100644
--- a/doc/sdk/http-transformation-plugin/sample-buffered-null-transformation-plugin.en.rst
+++ b/doc/sdk/http-transformation-plugin/sample-buffered-null-transformation-plugin.en.rst
@@ -32,54 +32,54 @@ transform:
#. Gets a handle to HTTP transactions.
- .. code-block:: c
-
- void
- TSPluginInit (int argc, const char *argv[]) {
- TSHttpHookAdd (TS_HTTP_READ_RESPONSE_HDR_HOOK,
- TSContCreate (transform_plugin, NULL)); }
+ .. code-block:: c
- With this ``TSPluginInit`` routine, the plugin is called back every
- time Traffic Server reads a response header.
+ void
+ TSPluginInit (int argc, const char *argv[]) {
+ TSHttpHookAdd (TS_HTTP_READ_RESPONSE_HDR_HOOK,
+ TSContCreate (transform_plugin, NULL)); }
-#. Checks to see if the transaction response is transformable.
+ With this ``TSPluginInit`` routine, the plugin is called back every
+ time Traffic Server reads a response header.
- .. code-block:: c
-
- static int transform_plugin (TSCont contp, TSEvent event, void *edata) {
- TSHttpTxn txnp = (TSHttpTxn) edata;
- switch (event) {
- case TS_EVENT_HTTP_READ_RESPONSE_HDR:
- if (transformable (txnp)) {
- transform_add (txnp);
- }
-
- The default behavior for transformations is to cache the transformed
- content (if desired, you also can tell Traffic Server to cache
- untransformed content). Therefore, only responses received directly
- from an origin server need to be transformed. Objects served from
- the cache are already transformed. To determine whether the response
- is from the origin server, the routine transformable checks the
- response header for the "200 OK" server response.
+#. Checks to see if the transaction response is transformable.
- .. code-block:: c
-
- {
- TSMBuffer bufp;
- TSMLoc hdr_loc;
- TSHttpStatus resp_status;
-
- TSHttpTxnServerRespGet (txnp, &bufp, &hdr_loc);
-
- if(TS_HTTP_STATUS_OK==
- (resp_status=TSHttpHdrStatusGet(bufp,hdr_loc)))
- {
- return 1;
- }
- else {
- return 0;
- }
- }
+ .. code-block:: c
+
+ static int transform_plugin (TSCont contp, TSEvent event, void *edata) {
+ TSHttpTxn txnp = (TSHttpTxn) edata;
+ switch (event) {
+ case TS_EVENT_HTTP_READ_RESPONSE_HDR:
+ if (transformable (txnp)) {
+ transform_add (txnp);
+ }
+
+ The default behavior for transformations is to cache the transformed
+ content (if desired, you also can tell Traffic Server to cache
+ untransformed content). Therefore, only responses received directly
+ from an origin server need to be transformed. Objects served from
+ the cache are already transformed. To determine whether the response
+ is from the origin server, the routine transformable checks the
+ response header for the "200 OK" server response.
+
+ .. code-block:: c
+
+ {
+ TSMBuffer bufp;
+ TSMLoc hdr_loc;
+ TSHttpStatus resp_status;
+
+ TSHttpTxnServerRespGet (txnp, &bufp, &hdr_loc);
+
+ if(TS_HTTP_STATUS_OK==
+ (resp_status=TSHttpHdrStatusGet(bufp,hdr_loc)))
+ {
+ return 1;
+ }
+ else {
+ return 0;
+ }
+ }
#. If the response is transformable, then the plugin creates a
transformation vconnection that gets called back when the response
@@ -87,7 +87,7 @@ transform:
server).
.. code-block:: c
-
+
static void transform_add (TSHttpTxn txnp)
{
TSVConn connp;
@@ -120,23 +120,23 @@ transform:
``handle_buffering`` function for the following code fragment:
.. code-block:: c
-
+
TSIOBufferCopy (data->output_buffer,
TSVIOReaderGet (write_vio), towrite, 0);
#. Tell the input buffer that the transformation has read the data. See
the ``handle_buffering`` function for the following code fragment:
-
+
.. code-block:: c
-
+
TSIOBufferReaderConsume (TSVIOReaderGet (write_vio), towrite);
#. Modify the input VIO to tell it how much data has been read
(increase the value of ``ndone``). See the ``handle_buffering``
function for the following code fragment:
-
+
.. code-block:: c
-
+
TSVIONDoneSet (write_vio, TSVIONDoneGet (write_vio) + towrite); }
#. If there is more data left to read ( if ndone < nbytes), then the
@@ -144,7 +144,7 @@ transform:
sending it ``WRITE_READY``:
.. code-block:: c
-
+
if (TSVIONTodoGet (write_vio) > 0) {
if (towrite > 0) {
TSContCall (TSVIOContGet (write_vio),
@@ -175,7 +175,7 @@ transform:
vconnection back with the ``WRITE_COMPLETE`` event.
.. code-block:: c
-
+
data->state = STATE_OUTPUT_DATA;
TSContCall (TSVIOContGet (write_vio),
TS_EVENT_VCONN_WRITE_COMPLETE, write_vio);
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/caf1bc13/doc/sdk/http-transformation-plugin/sample-null-transformation-plugin.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/http-transformation-plugin/sample-null-transformation-plugin.en.rst b/doc/sdk/http-transformation-plugin/sample-null-transformation-plugin.en.rst
index 91f7612..603470c 100644
--- a/doc/sdk/http-transformation-plugin/sample-null-transformation-plugin.en.rst
+++ b/doc/sdk/http-transformation-plugin/sample-null-transformation-plugin.en.rst
@@ -29,9 +29,8 @@ Below is an overview of the null transform plugin:
1. Gets a handle to HTTP transactions.
- ::
+ .. code-block:: c
- :::c
void
TSPluginInit (int argc, const char *argv[]) {
TSHttpHookAdd (TS_HTTP_READ_RESPONSE_HDR_HOOK,
@@ -42,9 +41,8 @@ Below is an overview of the null transform plugin:
2. Checks to see if the transaction response is transformable.
- ::
+ .. code-block:: c
- :::c
static int transform_plugin (TSCont contp, TSEvent event, void *edata) {
TSHttpTxn txnp = (TSHttpTxn) edata;
switch (event) {
@@ -61,9 +59,8 @@ Below is an overview of the null transform plugin:
from the origin server, the routine ``transformable`` checks the
response header for the "200 OK" server response.
- ::
+ .. code-block:: c
- :::c
static int transformable (TSHttpTxn txnp)
{
TSMBuffer bufp;
@@ -84,9 +81,8 @@ Below is an overview of the null transform plugin:
data is ready to be transformed (as it is streaming from the origin
server).
- ::
+ .. code-block:: c
- :::c
static void transform_add (TSHttpTxn txnp)
{
TSVConn connp;
@@ -100,17 +96,15 @@ Below is an overview of the null transform plugin:
4. Get a handle to the output vconnection (that receives data from the
tranformation).
- ::
+ .. code-block:: c
- :::c
output_conn = TSTransformOutputVConnGet (con
5. Get a handle to the input VIO. (See the ``handle_transform``
function.)
- ::
+ .. code-block:: c
- :::c
input_vio = TSVConnWriteVIOGet (contp);
This is so that the transformation can get information about the
@@ -122,25 +116,23 @@ Below is an overview of the null transform plugin:
from the output vconnection. See the ``handle_transform`` function
for the following code fragment:
- ::
+ .. code-block:: c
- :::c
data->output_vio = TSVConnWrite (output_conn, contp,
data->output_reader, TSVIONBytesGet (input_vio));
7. Copy data from the input buffer to the output buffer. See the
``handle_transform`` function for the following code fragment:
- ::
+ .. code-block:: c
- ::::c
TSIOBufferCopy (TSVIOBufferGet (data->output_vio),
TSVIOReaderGet (input_vio), towrite, 0);
8. Tell the input buffer that the transformation has read the data. See
the ``handle_transform`` function for the following code fragment:
- ::
+ .. code-block:: c
TSIOBufferReaderConsume (TSVIOReaderGet (input_vio), towrite);
@@ -148,9 +140,8 @@ Below is an overview of the null transform plugin:
(increase the value of ``ndone``). See the ``handle_transform``
function for the following code fragment:
- ::
+ .. code-block:: c
- ::::c
TSVIONDoneSet (input_vio, TSVIONDoneGet (input_vio) + towrite);
10. If there is more data left to read ( if ndone < nbytes), then the
@@ -158,9 +149,8 @@ Below is an overview of the null transform plugin:
with a reenable and wakes up the upstream vconnection by sending it
``WRITE_READY``:
- ::
+ .. code-block:: c
- :::c
if (TSVIONTodoGet (input_vio) > 0) {
if (towrite > 0) {
TSVIOReenable (data->output_vio);
@@ -210,9 +200,8 @@ Below is an overview of the null transform plugin:
vconnection). See the ``null_plugin`` function for the following
code fragment:
- ::
+ .. code-block:: c
- :::c
case TS_EVENT_VCONN_WRITE_COMPLETE:
TSVConnShutdown (TSTransformOutputVConnGet (contp), 0, 1
break;
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/caf1bc13/doc/sdk/io-guide.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/io-guide.en.rst b/doc/sdk/io-guide.en.rst
index 7e95cf3..faece66 100644
--- a/doc/sdk/io-guide.en.rst
+++ b/doc/sdk/io-guide.en.rst
@@ -92,9 +92,8 @@ reexamine it to see if it can make further progress.
The null transform plugin provides an example of how this is done. Below
is a prototype for ``TSVConnWrite``:
-::
+.. code-block:: c
- ::::c
TSVIO TSVConnWrite (TSVConn connp, TSCont contp, TSIOBufferReader readerp, int nbytes)
The ``connp`` is the vconnection the user is writing to and ``contp`` is
@@ -103,9 +102,8 @@ has emptied its buffer and is ready for more data.
The call made in the null transform plugin is:
-::
+.. code-block:: c
- :::c
TSVConnWrite (output_conn, contp, data->output_reader, TSVIONBytesGet (input_vio));
In the example above, ``contp`` is the transformation vconnection that
@@ -177,8 +175,8 @@ write portion of a connection, then the ``TS_EVENT_VCONN_WRITE_READY``
or ``TS_EVENT_VCONN_WRITE_COMPLETE`` events will not be produced. In the
null transform plugin, the write operation is shut down with a call to
``TSVConnShutdown``. To learn how vconnections are used in
-transformation plugins, see `Writing Content Transform
-Plugins <../http-transformation-plugin#WritingContentTransformPlugins>`__.
+transformation plugins, see :ref:`Writing Content Transform
+Plugins <WritingContentTransformPlugin>`.
The vconnection functions are listed below:
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/caf1bc13/doc/sdk/io-guide/guide-to-cache-api.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/io-guide/guide-to-cache-api.en.rst b/doc/sdk/io-guide/guide-to-cache-api.en.rst
index ea63967..2944044 100644
--- a/doc/sdk/io-guide/guide-to-cache-api.en.rst
+++ b/doc/sdk/io-guide/guide-to-cache-api.en.rst
@@ -40,9 +40,8 @@ differs from the HTTP type).
**Example:**
-::
+.. code-block:: c
- :::c
const unsigned char *key_name = "example key name";
TSCacheKey key;
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/caf1bc13/doc/sdk/io-guide/guide-to-cache-api/example.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/io-guide/guide-to-cache-api/example.en.rst b/doc/sdk/io-guide/guide-to-cache-api/example.en.rst
index c00dbea..0179de6 100644
--- a/doc/sdk/io-guide/guide-to-cache-api/example.en.rst
+++ b/doc/sdk/io-guide/guide-to-cache-api/example.en.rst
@@ -26,9 +26,8 @@ actual size of the document (``content_length``). Then, issue
``TSVConnRead`` to read the document with the total data length required
as ``content_length``. Assume the following data:
-::
+.. code-block:: c
- ::::c
TSIOBuffer cache_bufp = TSIOBufferCreate ();
TSIOBufferReader cache_readerp = TSIOBufferReaderAlloc (out_bufp);
TSVConn cache_vconnp = NULL;
@@ -37,18 +36,16 @@ as ``content_length``. Assume the following data:
In the ``TS_CACHE_OPEN_READ`` handler:
-::
+.. code-block:: c
- ::::c
cache_vconnp = (TSVConn) data;
TSVConnCachedObjectSizeGet (cache_vconnp, &content_length);
cache_vio = TSVConnRead (cache_vconn, contp, cache_bufp, content_length);
In the ``TS_EVENT_VCONN_READ_READY`` handler:
-::
+.. code-block:: c
- ::::c
(usual VCONN_READ_READY handler logic)
int nbytes = TSVIONBytesGet (cache_vio);
int ntodo = TSVIONTodoGet (cache_vio);
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/caf1bc13/doc/sdk/io-guide/transformations.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/io-guide/transformations.en.rst b/doc/sdk/io-guide/transformations.en.rst
index e627000..76a9c0d 100644
--- a/doc/sdk/io-guide/transformations.en.rst
+++ b/doc/sdk/io-guide/transformations.en.rst
@@ -36,9 +36,8 @@ it only supports reading or writing).
For example, the null transform plugin's transformation examines the
input VIO by calling:
-::
+.. code-block:: c
- :::c
input_vio = TSVConnWriteVIOGet (contp);
where ``contp`` is the transformation.
@@ -53,9 +52,8 @@ make some progress on the IO operations.
It is common for the handler function for all vconnections to look
similar. Their basic form looks something like the code fragment below:
-::
+.. code-block:: c
- ::::c
int
vconnection_handler (TSCont contp, TSEvent event, void *edata)
{
@@ -142,9 +140,8 @@ Here's how to make sure that all incoming data is consumed:
and increase the value of ndone for the input VIO, as in the
following example taken from ``null-transform.c``:
- ::
+ .. code-block:: c
- :::c
TSIOBufferCopy (TSVIOBufferGet (data->output_vio),
TSVIOReaderGet (input_vio), towrite, 0);
/* Tell the read buffer that we have read the data and are no longer interested in it. */
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/caf1bc13/doc/sdk/io-guide/vios.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/io-guide/vios.en.rst b/doc/sdk/io-guide/vios.en.rst
index 61718c2..b04aaef 100644
--- a/doc/sdk/io-guide/vios.en.rst
+++ b/doc/sdk/io-guide/vios.en.rst
@@ -30,9 +30,8 @@ made.
The ``TSVIO`` data structure itself is opaque, but it could be defined
as follows:
-::
+.. code-block:: c
- ::::c
typedef struct {
TSCont continuation;
TSVConn vconnection;
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/caf1bc13/doc/sdk/misc-interface-guide/thread-functions.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/misc-interface-guide/thread-functions.en.rst b/doc/sdk/misc-interface-guide/thread-functions.en.rst
index a39f515..2e9c6da 100644
--- a/doc/sdk/misc-interface-guide/thread-functions.en.rst
+++ b/doc/sdk/misc-interface-guide/thread-functions.en.rst
@@ -23,7 +23,7 @@ and identify threads within Traffic Server. Multithreading enables a
single program to have more than one stream of execution and to process
more than one transaction at a time. Threads serialize their access to
shared resources and data using the ``TSMutex`` type, as described in
-`Mutexes <../mutex-guide/#Mutexes>`__.
+:ref:`Mutexes`.
The thread functions are listed below:
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/caf1bc13/doc/sdk/mutex-guide.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/mutex-guide.en.rst b/doc/sdk/mutex-guide.en.rst
index de2eaad..3dcb461 100644
--- a/doc/sdk/mutex-guide.en.rst
+++ b/doc/sdk/mutex-guide.en.rst
@@ -24,6 +24,8 @@ the mutex interface.
.. toctree::
:maxdepth: 1
+.. _Mutexes:
+
Mutexes
-------
@@ -78,11 +80,8 @@ data. The blacklist plugin reads its blacklisted sites from a
configuration file; file read operations are protected by a mutex
created in ``TSPluginInit``. The ``blacklist-1.c`` code uses
``TSMutexLockTry`` instead of ``InkMutexLock``. For more detailed
-information, see the
-```blacklist-1.c`` <../sample-source-code#Sample_blacklist-1.c>`__ code;
-start by looking at the
-:c:func:`TSPluginInit`
-function.
+information, see the :ref:`blacklist-1.c` code;
+start by looking at the :c:func:`TSPluginInit` function.
General guidelines for locking shared data are as follows:
@@ -109,9 +108,8 @@ accessed by other continuations or processes. Here's how:
1. | Create a mutex for the continuation using ``TSMutexCreate``.
| For example:
- ::
+ .. code-block:: c
- ::::c
TSMutex mutexp;
mutexp = TSMutexCreate ();
@@ -119,10 +117,9 @@ accessed by other continuations or processes. Here's how:
continuation's mutex.
| For example:
- ::
+ .. code-block:: c
- :::c
- TSCont contp;
+ TSCont contp;
contp = TSContCreate (handler, mutexp);
If any other functions want to access ``contp``'s data, then it is up to
@@ -154,9 +151,8 @@ plugin continuation to be called back by HTTP transactions globally when
they reach ``TS_HTTP_TXN_START_HOOK``. Refer to the example below, which
uses a transaction-specific continuation called ``txn_contp``.
-::
+.. code-block:: c
- ::::c
void TSPluginInit(int argc, const char *argv[])
{
/* Plugin continuation */
@@ -174,9 +170,8 @@ In the plugin continuation handler, create the new continuation
``txn_contp`` and then register it to be called back at
``TS_HTTP_TXN_CLOSE_HOOK``:
-::
+.. code-block:: c
- ::::c
static int plugin_cont_handler(TSCont contp, TSEvent event, void *edata)
{
TSHttpTxn txnp = (TSHttpTxn)edata;
@@ -210,9 +205,9 @@ Remember that the ``txn_contp`` handler must destory itself when the
HTTP transaction is closed. If you forget to do this, then your plugin
will have a memory leak.
-::
+.. code-block:: c
+
- ::::c
static int txn_cont_handler(TSCont txn_contp, TSEvent event, void *edata)
{
TSHttpTxn txnp;
@@ -241,9 +236,8 @@ For the example above, store the data in the ``txn_contp`` data
structure - this means that you'll create your own data structure. Now
suppose you want to store the state of the HTTP transaction:
-::
+.. code-block:: c
- ::::c
typedef struct {
int state;
} ContData;
@@ -252,9 +246,8 @@ You need to allocate the memory and initialize this structure for each
HTTP ``txnp``. You can do that in the plugin continuation handler when
it is called back with ``TS_EVENT_HTTP_TXN_START``
-::
+.. code-block:: c
- ::::c
static int plugin_cont_handler(TSCont contp, TSEvent event, void *edata)
{
TSHttpTxn txnp = (TSHttpTxn)edata;
@@ -294,9 +287,8 @@ it is called back with ``TS_EVENT_HTTP_TXN_START``
For accessing this data from anywhere, use TSContDataGet:
-::
+.. code-block:: c
- ::::c
TSCont txn_contp;
ContData *contData;
@@ -308,9 +300,8 @@ For accessing this data from anywhere, use TSContDataGet:
Remember to free this memory before destroying the continuation:
-::
+.. code-block:: c
- ::::c
static int txn_cont_handler(TSCont txn_contp, TSEvent event, void *edata)
{
TSHttpTxn txnp;
@@ -374,9 +365,8 @@ HTTP transaction (``TSHttpTxn`` object) already has its own mutex.
In the example below, it's not necessary to specify a mutex for the
continuation created in ``txn_handler``:
-::
+.. code-block:: c
- ::::c
static void
txn_handler (TSHttpTxn txnp, TSCont contp) {
TSCont newCont;
@@ -389,19 +379,19 @@ continuation created in ``txn_handler``:
TSHttpTxnReenable (txnp, TS_EVENT_HTTP_CONTINUE);
}
- static int
- test_plugin (TSCont contp, TSEvent event, void *edata) {
- TSHttpTxn txnp = (TSHttpTxn) edata;
-
- switch (event) {
- case TS_EVENT_HTTP_READ_REQUEST_HDR:
- txn_handler (txnp, contp);
- return 0;
- default:
- break;
- }
- return 0;
- }
+ static int
+ test_plugin (TSCont contp, TSEvent event, void *edata) {
+ TSHttpTxn txnp = (TSHttpTxn) edata;
+
+ switch (event) {
+ case TS_EVENT_HTTP_READ_REQUEST_HDR:
+ txn_handler (txnp, contp);
+ return 0;
+ default:
+ break;
+ }
+ return 0;
+ }
The mutex functions are listed below:
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/caf1bc13/doc/sdk/new-protocol-plugins.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/new-protocol-plugins.en.rst b/doc/sdk/new-protocol-plugins.en.rst
index 195fce8..c0f7fc5 100644
--- a/doc/sdk/new-protocol-plugins.en.rst
+++ b/doc/sdk/new-protocol-plugins.en.rst
@@ -44,8 +44,8 @@ Using the Protocol plugin, Traffic Server can accept these requests,
parse them, and act as a proxy cache (i.e., request the file from the
origin server on the client's behalf and store copies of response
messages in cache). The Protocol plugin is a state machine that flows
-through the states illustrated in the `Sample Protocol State
-Diagram <#SampleProtocolStDiag>`_. This figure illustrates the steps
+through the states illustrated in the :ref:`Sample Protocol State
+Diagram <SampleProtocolStDiag>`. This figure illustrates the steps
that Traffic Server and the Protocol plugin go through in order to
support the sample protocol.
@@ -70,7 +70,9 @@ In more specific terms, Traffic Server and the Protocol plugin must:
- Cache the response and send it on to the client
-**Sample Protocol State Diagram** {#SampleProtocolStDiag}
+**Sample Protocol State Diagram**
+
+.. _SampleProtocolStDiag:
.. figure:: ../static/images/sdk/Protocol_state_diagram.jpg
:alt: Sample Protocol State Diagram
@@ -84,9 +86,9 @@ To see how the Protocol plugin works, you need to understand some
broader concepts. This section assumes you're familiar with the concepts
of :term:`continuation`, Traffic Server's **asynchronous event model**, and
basic Traffic Server **plugin structure**. If you are not familiar with
-these concepts, then reference `Getting
-Started <../getting-started#GettingStarted>`_ and `How to Create
-Traffic Server Plugins <../how-to-create-trafficserver-plugins>`_
+these concepts, then reference :ref:`Getting
+Started <sdk-getting-started>` and :doc:`How to Create
+Traffic Server Plugins <how-to-create-trafficserver-plugins.en>`
Continuations in the Protocol Plugin
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -102,11 +104,13 @@ request and Traffic Server's response). Each transaction state machine
lives until the transaction completes; then it is destroyed. If the
client's request for content is a cache miss, then a transaction state
machine might need to open a connection to the origin server. This is
-illustrated in the `Protocol Plugin
-Overview <#ProtocolPluginOverview>`__ diagram below.
+illustrated in the :ref:`Protocol Plugin
+Overview <ProtocolPluginOverview>` diagram below.
**Protocol Plugin Overview**
+.. _ProtocolPluginOverview:
+
.. figure:: ../static/images/sdk/protocol_sm_big.jpg
:alt: Protocol Plugin Overview
@@ -160,13 +164,15 @@ Processor.
**Protocol Plugin Flow of Events**
+.. _ProtocolPluginFlow:
+
.. figure:: ../static/images/sdk/protocol_evt.jpg
:alt: Protocol Plugin Flow of Events
Protocol Plugin Flow of Events
-The flow of events is illustrated in the `Protocol Plugin Flow of
-Events <#ProtocolPluginFlow>`_ diagram above. The thin straight lines
+The flow of events is illustrated in the :ref:`Protocol Plugin Flow of
+Events <ProtocolPluginFlow>` diagram above. The thin straight lines
show Net Processor event flow, the thin dashed lines represent Host
Database event flow, and the thick dashed lines show Cache event flow.
@@ -216,9 +222,9 @@ plugin does this are provided in the next section.
``main_handler`` calls the state handler functions to handle each
state.
-The steps below describe the flow of execution illustrated in `"How
+The steps below describe the flow of execution illustrated in :ref:`"How
Transaction State Machines are Implemented in the Protocol
-Plugin" <#ImplementTransStMachine>`__.
+Plugin" <ImplementTransStMachine>`.
1. The handler for the TSM, (called **``main_handler``** in the Protocol
plugin) receives events from the TSM.
@@ -228,12 +234,12 @@ Plugin" <#ImplementTransStMachine>`__.
3. **``main_handler``** calls the **``current_handler``** (which is one
of the state handler functions), and then passes the current event to
- **``current_handler``**. In `the image
- below <#ImplementTransStMachine>`__ below, the current handler is
+ **``current_handler``**. In :ref:`the image
+ below <ImplementTransStMachine>` below, the current handler is
called **``state2_handler``**.
4. The **``current_handler``** handles the event and updates the data.
- In `the image below <#ImplementTransStMachine>`__ below, the state is
+ In :ref:`the image below <ImplementTransStMachine>` below, the state is
changed from **``state2``** to **``state3``** (and the current
handler is changed from **``state2_handler``** to
**``state3_handler``**). The next time **``main_handler``** receives
@@ -246,7 +252,9 @@ Plugin" <#ImplementTransStMachine>`__.
arrive from Traffic Server.
**How Transaction State Machines are Implemented in the Protocol
-Plugin** {#ImplementTransStMachine}
+Plugin**
+
+.. _ImplementTransStMachine:
.. figure:: ../static/images/sdk/txn_sm.jpg
:alt: How Transaction State Machines are Implemented in the Protocol Plugin
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/caf1bc13/doc/sdk/plugin-configurations.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/plugin-configurations.en.rst b/doc/sdk/plugin-configurations.en.rst
index 994f519..2dc222a 100644
--- a/doc/sdk/plugin-configurations.en.rst
+++ b/doc/sdk/plugin-configurations.en.rst
@@ -31,8 +31,8 @@ and changing global configuration information within a plugin.
The functions discussed in this section do not examine or modify Traffic
Server configuration variables. To examine Traffic Server configuration
-and statistics variables, see `"Reading Traffic Server Settings and
-Statistics" <../plugin-management/reading-trafficserver-settings-and-statistics>`__
+and statistics variables, see :doc:`"Reading Traffic Server Settings and
+Statistics" <plugin-management/reading-trafficserver-settings-and-statistics.en>`.
The ``TSConfig`` family of functions is designed to provide a fast and
efficient mechanism for accessing and changing global configuration
@@ -55,9 +55,8 @@ global data updates.
Here's how the interface works:
-::
+.. code-block:: c
- ::::c
/* Assume that you have previously defined a plugin configuration
* data structure named ConfigData, along with its constructor
* plugin_config_allocator () and its destructor
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/caf1bc13/doc/sdk/plugin-management/guide-to-the-logging-api.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/plugin-management/guide-to-the-logging-api.en.rst b/doc/sdk/plugin-management/guide-to-the-logging-api.en.rst
index ad0b193..1471be7 100644
--- a/doc/sdk/plugin-management/guide-to-the-logging-api.en.rst
+++ b/doc/sdk/plugin-management/guide-to-the-logging-api.en.rst
@@ -56,16 +56,14 @@ The steps below show how the logging API is used in the
1. A new log file is defined as a global variable.
- ::
+ .. code-block:: c
- ::::c
static TSTextLogObject log;
2. In ``TSPluginInit``, a new log object is allocated:
- ::
+ .. code-block:: c
- ::::c
log = TSTextLogObjectCreate("blacklist", TS_LOG_MODE_ADD_TIMESTAMP, NULL, &error);
The new log is named ``blacklist.log``. Each entry written to the log
@@ -77,9 +75,8 @@ The steps below show how the logging API is used in the
3. After creating the log, the plugin makes sure that the log was
created successfully:
- ::
+ .. code-block:: c
- ::::c
if (!log) {
printf("Blacklist plugin: error %d while creating log\n", error);
}
@@ -88,15 +85,27 @@ The steps below show how the logging API is used in the
each client request) with a list of blacklisted sites (stored in the
array ``sites[``]):
- ::::c for (i = 0; i < nsites; i++) { if (strncmp (host, sites[i],
- host\_length) == 0) { If the host matches one of the blacklisted
+ .. code-block:: c
+
+ for (i = 0; i < nsites; i++) { if (strncmp (host, sites[i],
+ host\_length) == 0) {
+
+ If the host matches one of the blacklisted
sites (such as ``sites[i]``), then the plugin writes a blacklist
entry to ``blacklist.log``:
- ::::c if (log) { TSTextLogObjectWrite(log, "blacklisting site: %s",
- sites[i]); The format of the log entry is as follows:
+ .. code-block:: c
+
+ if (log) { TSTextLogObjectWrite(log, "blacklisting site: %s",
+ sites[i]);
+
+ The format of the log entry is as follows:
+
+ ::
+
+ blacklisting site: sites[i]
- :::text blacklisting site: sites[i] The log is not flushed or
+ The log is not flushed or
destroyed in the ``blacklist-1`` plugin - it lives for the life of
the plugin.
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/caf1bc13/doc/sdk/plugin-management/reading-trafficserver-settings-and-statistics.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/plugin-management/reading-trafficserver-settings-and-statistics.en.rst b/doc/sdk/plugin-management/reading-trafficserver-settings-and-statistics.en.rst
index e203198..c275dfa 100644
--- a/doc/sdk/plugin-management/reading-trafficserver-settings-and-statistics.en.rst
+++ b/doc/sdk/plugin-management/reading-trafficserver-settings-and-statistics.en.rst
@@ -29,13 +29,13 @@ statistics are stored in ``PROCESS`` variables.
Not all ``CONFIG`` and ``PROCESS`` variables in :file:`records.config` are
relevant to Traffic Server's configuration and statistics. Therefore,
retrieve only the :file:`records.config` variables that are documented in
- the `Traffic Server Administrator's Guide <../../admin/>`__.
+ the :doc:`Traffic Server Administrator's Guide <../../admin/index.en>`.
To retrieve a variable, you need to know its type (``int``, ``counter``,
``float``, or ``string``). Plugins store the :file:`records.config` values
as an ``TSMgmtInt``, ``TSMgmtCounter``, ``TSMgmtFloat``, or
``TSMgmtString``. You can look up :file:`records.config` variable types in
-the `Traffic Server Administrator's Guide <../../admin/>`__.
+the :doc:`Traffic Server Administrator's Guide <../../admin/index.en>`.
Depending on the result type, you'll use ``TSMgmtIntGet``,
``TSMgmtCounterGet``, ``TSMgmtFloatGet``, or ``TSMgmtStringGet`` to
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/caf1bc13/doc/sdk/remap-plugin/example-query-remap.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/remap-plugin/example-query-remap.en.rst b/doc/sdk/remap-plugin/example-query-remap.en.rst
index 757b76e..776c46d 100644
--- a/doc/sdk/remap-plugin/example-query-remap.en.rst
+++ b/doc/sdk/remap-plugin/example-query-remap.en.rst
@@ -56,9 +56,8 @@ parameters. The ihandle, an opaque pointer that can be used to pass
per-instance data, is set to this struct pointer and will be passed to
the ``tsremap_remap`` function when it is triggered for a request.
-::
+.. code-block:: c
- :::c
typedef struct _query_remap_info {
char *param_name;
size_t param_len;
@@ -101,9 +100,8 @@ struct contains input and output members for the remap operation.
parameter. If the parameter is found, the plugin sets a ``new_host`` to
modify the request host:
-::
+.. code-block:: c
- :::c
int tsremap_remap(ihandle ih, rhandle rh, TSRemapRequestInfo *rri)
{
int hostidx = -1;
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/caf1bc13/doc/sdk/sample-source-code.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/sample-source-code.en.rst b/doc/sdk/sample-source-code.en.rst
index 3568f41..bd84584 100644
--- a/doc/sdk/sample-source-code.en.rst
+++ b/doc/sdk/sample-source-code.en.rst
@@ -24,6 +24,8 @@ the previous chapters. The following sample plugins are provided:
- `blacklist-1.c`_
+.. _blacklist-1.c:
+
blacklist-1.c
-------------
@@ -43,9 +45,8 @@ This plugin illustrates:
- How to use the plugin configuration management interface
-.. raw:: html
+.. code-block:: c
- <pre>
/* blacklist-1.c: An example program that denies client access
* to blacklisted sites. This plugin illustrates
* how to use configuration information from the
@@ -304,6 +305,4 @@ This plugin illustrates:
TSMgmtUpdateRegister (contp, "Super Blacklist Plugin", "blacklist.cgi");
}
- </pre>
-
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/caf1bc13/doc/sdk/troubleshooting-tips.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/troubleshooting-tips.en.rst b/doc/sdk/troubleshooting-tips.en.rst
index 189b403..3a312bf 100644
--- a/doc/sdk/troubleshooting-tips.en.rst
+++ b/doc/sdk/troubleshooting-tips.en.rst
@@ -44,7 +44,6 @@ could use the following commands to building a shared library:
::
- :::text
tsxs -c hello-world.c -o hello-world.so
To install this plugin in your ``plugindir`` use the equivalent of sudo
@@ -52,6 +51,5 @@ on your platform to execute:
::
- :::text
sudo tsxs -o hello-world.so -i
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/caf1bc13/doc/sdk/troubleshooting-tips/debugging-memory-leaks.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/troubleshooting-tips/debugging-memory-leaks.en.rst b/doc/sdk/troubleshooting-tips/debugging-memory-leaks.en.rst
index d8db570..a2c87dc 100644
--- a/doc/sdk/troubleshooting-tips/debugging-memory-leaks.en.rst
+++ b/doc/sdk/troubleshooting-tips/debugging-memory-leaks.en.rst
@@ -24,7 +24,6 @@ related to memory - you can use memory dump information. Enable
::
- :::text
CONFIG proxy.config.dump_mem_info_frequency INT <value>
This causes Traffic Server to dump memory information to ``traffic.out``
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/caf1bc13/doc/sdk/troubleshooting-tips/unable-to-debug-tags.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/troubleshooting-tips/unable-to-debug-tags.en.rst b/doc/sdk/troubleshooting-tips/unable-to-debug-tags.en.rst
index 745712a..a72d160 100644
--- a/doc/sdk/troubleshooting-tips/unable-to-debug-tags.en.rst
+++ b/doc/sdk/troubleshooting-tips/unable-to-debug-tags.en.rst
@@ -34,7 +34,6 @@ below:
::
- :::text
traffic_server -T"my-plugin"
Set the following variables in :file:`records.config` (in the Traffic Server
@@ -42,7 +41,6 @@ Set the following variables in :file:`records.config` (in the Traffic Server
::
- :::text
CONFIG proxy.config.diags.debug.enabled INT 1
CONFIG proxy.config.diags.debug.tags STRING debug-tag-name
@@ -50,9 +48,8 @@ In this case, debug output goes to ``traffic.out``.
Example:
-::
+.. code-block:: c
- :::c
TSDebug ("my-plugin", "Starting my-plugin at %d\n", the_time);
The statement ``"Starting my-plugin at <time>"`` appears whenever you
@@ -60,7 +57,6 @@ run Traffic Server with the ``my-plugin`` tag:
::
- :::text
traffic_server -T"my-plugin"
Other Useful Internal Debug Tags
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/caf1bc13/doc/sdk/troubleshooting-tips/using-a-debugger.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/troubleshooting-tips/using-a-debugger.en.rst b/doc/sdk/troubleshooting-tips/using-a-debugger.en.rst
index 8af57d2..d2729e2 100644
--- a/doc/sdk/troubleshooting-tips/using-a-debugger.en.rst
+++ b/doc/sdk/troubleshooting-tips/using-a-debugger.en.rst
@@ -25,7 +25,6 @@ the core files in the :file:`records.config` file to -1 as follows:
::
- :::c
CONFIG proxy.config.core_limit INT -1
This is the equivalent of setting ``ulimit -c unlimited``