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 2015/11/03 07:09:39 UTC
[03/51] trafficserver git commit: Documentation reorganization
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/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
deleted file mode 100644
index c22caa7..0000000
--- a/doc/sdk/http-transformation-plugin.en.rst
+++ /dev/null
@@ -1,183 +0,0 @@
-.. _http-transformation-plugin:
-
-HTTP Transformation Plugins
-***************************
-
-.. Licensed to the Apache Software Foundation (ASF) under one
- or more contributor license agreements. See the NOTICE file
- distributed with this work for additional information
- regarding copyright ownership. The ASF licenses this file
- to you under the Apache License, Version 2.0 (the
- "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing,
- software distributed under the License is distributed on an
- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- KIND, either express or implied. See the License for the
- specific language governing permissions and limitations
- under the License.
-
-Transform plugins examine or transform HTTP message body content. For
-example, transform plugins can:
-
-- Append text to HTML documents
-
-- Compress images
-
-- Do virus checking (on client ``POST`` data or server response data)
-
-- Do content-based filtering (filter out HTML documents that contain
- certain terms or expressions)
-
-This chapter explains how to write transform plugins. The following
-examples are discussed in detail:
-
-.. toctree::
- :maxdepth: 2
-
- http-transformation-plugin/sample-null-transformation-plugin.en
- http-transformation-plugin/append-transform-plugin.en
- http-transformation-plugin/sample-buffered-null-transformation-plugin.en
-
-.. _WritingContentTransformPlugin:
-
-Writing Content Transform Plugins
----------------------------------
-
-Content transformation plugins transform HTTP response content (such as
-images or HTML documents) and HTTP request content (such as client
-``POST`` data). Because the data stream to be transformed is of variable
-length, these plugins must use a mechanism that passes data from buffer
-to buffer *and* checks to see if the end of the data stream is reached.
-This mechanism is provided by virtual connections (``VConnection``\ s)
-and virtual IO descriptors (``VIO``\ s).
-
-A ``VConnection`` is an abstraction for a data pipe that allows its
-users to perform asynchronous reads and writes without knowing the
-underlying implementation. A transformation is a specific type of
-``VConnection``. A **transformation** connects an input data source and
-an output data sink; this feature enables it to view and modify all the
-data passing through it.
-
-Transformations can be chained together, one after the other, so that
-multiple transformations can be performed on the same content. The
-``VConnection`` type, ``TSVConn``, is actually a subclass of ``TSCont``,
-which means that ``VConnection``\ s (and transformations) are
-continuations. ``VConnection``\ s and transformations can thus exchange
-events, informing one another that data is available for reading or
-writing, or that the end of a data stream is reached.
-
-A ``VIO`` is a description of an IO operation that is in progress.
-Every ``VConnection`` has an associated *input VIO* and an associated
-*output VIO*. When ``VConnection``\ s are transferring data to one
-another, one ``VConnection``'s input ``VIO`` is another
-``VConnection``'s output ``VIO``. A ``VConnection``'s input ``VIO`` is
-also called its **write ``VIO``** because the input ``VIO`` refers to a
-write operation performed on the ``VConnection`` itself. Similarly, the
-output ``VIO`` is also called the **read ``VIO``**. For transformations,
-which are designed to pass data in one direction, you can picture the
-relationship between the transformation ``VConnection`` and its
-``VIO``\ s as follows:
-
-.. _transformationAndItsVIOs:
-
-.. figure:: /static/images/sdk/vconnection.jpg
- :alt: A Transformation and its VIOs
- :align: center
-
- **A Transformation and its VIOs**
-
-Because the Traffic Server API places transformations directly in the
-response or request data stream, the transformation ``VConnection`` is
-responsible only for reading the data from the input buffer,
-transforming it, and then writing it to the output buffer. The upstream
-``VConnection`` writes the incoming data to the transformation's input
-buffer. In the figure above, :ref:`TransformationAndItsVIOs`, the input ``VIO`` describes the
-progress of the upstream ``VConnection``'s write operation on the
-transformation, while the output ``VIO`` describes the progress of the
-transformation's write operation on the output (downstream)
-``VConnection``. The **nbytes** value in the ``VIO`` is the total number
-of bytes to be written. The **ndone** value is the current progress, or
-the number of bytes that have been written at a specific point in time.
-
-When writing a transformation plugin, you must understand implementation
-as well as the use of ``VConnection``\ s. The *implementor's side*
-refers to how to implement a ``VConnection`` that others can use. At
-minimum, a transform plugin creates a transformation that sits in the
-data stream and must be able to handle the events that the upstream and
-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
-~~~~~~~~~~~~~~~
-
-VIOs
-~~~~
-
-A ``VIO``*or virtual IO is a description of an in progress IO
-operation. The ``VIO`` data structure is used by ``VConnection`` users
-to determine how much progress has been made on a particular IO
-operation, and to reenable an IO operation when it stalls due to buffer
-space. ``VConnection`` implementors use ``VIO``\ s to determine the
-buffer for an IO operation, how much work to do on the IO operation, and
-which continuation to call back when progress on the IO operation is
-made.
-
-The ``TSVIO`` data structure itself is opaque, but it might have been
-defined as follows:
-
-.. code-block:: c
-
- typedef struct {
- TSCont continuation;
- TSVConn vconnection;
- TSIOBufferReader reader;
- TSMutex mutex;
- int nbytes;
- int ndone;
- } *TSVIO;
-
-IO Buffers
-~~~~~~~~~~
-
-The **IO buffer** data structure is the building block of the
-``VConnection`` abstraction. An IO buffer is composed of a list of
-buffer blocks which, in turn, point to buffer data. Both the *buffer
-block* (``TSIOBufferBlock``) and *buffer data* (``TSIOBufferData``) data
-structures are reference counted so they can reside in multiple buffers
-at the same time. This makes it extremely efficient to copy data from
-one IO buffer to another using ``TSIOBufferCopy``, since Traffic Server
-only needs to copy pointers and adjust reference counts appropriately
-(instead of actually copying any data).
-
-The IO buffer abstraction provides for a single writer and multiple
-readers. In order for the readers to have no knowledge of each other,
-they manipulate IO buffers through the\ ``TSIOBufferReader`` data
-structure. Since only a single writer is allowed, there is no
-corresponding ``TSIOBufferWriter`` data structure. The writer simply
-modifies the IO buffer directly.
-
-Transaction Data Sink
-~~~~~~~~~~~~~~~~~~~~~
-
-The hook `TS_HTTP_RESPONSE_CLIENT_HOOK` is a hook that supports a special type of transformation, one with only input and no output.
-Although the transformation doesn't provide data back to Traffic Server it can do anything else with the data, such as writing it
-to another output device or process. It must, however, consume all the data for the transaction. There are two primary use cases.
-
-#. Tap in to the transaction to provide the data for external processing.
-#. Maintain the transaction.
-
-For the latter it is important to note that if all consumers of a transaction (primarily the user agent) shut down the transaction is also
-terminated, including the connection to the origin server. A data sink transform, unlike a standard transform, is considered to be a consumer
-and will keep the transaction and the origin server connection up. This is useful when the transaction is in some way expensive and should
-run to completion even if the user agent disconnects. Examples would be a standard transform that is expensive to initiate, or expensive
-origin server connections that should be :ts:cv:`shared <proxy.config.http.server_session_sharing.match>`.
-
-There is an `example plugin <https://github.com/apache/trafficserver/blob/master/example/txn-data-sink/txn-data-sink.c>`_ that demonstrates
-this used as a pure data sink to keep the transaction up regardless of whether the user agent disconnects.
\ No newline at end of file
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/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
deleted file mode 100644
index 47c6589..0000000
--- a/doc/sdk/http-transformation-plugin/append-transform-plugin.en.rst
+++ /dev/null
@@ -1,144 +0,0 @@
-The Append-Transform Plugin
-***************************
-
-.. Licensed to the Apache Software Foundation (ASF) under one
- or more contributor license agreements. See the NOTICE file
- distributed with this work for additional information
- regarding copyright ownership. The ASF licenses this file
- to you under the Apache License, Version 2.0 (the
- "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing,
- software distributed under the License is distributed on an
- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- KIND, either express or implied. See the License for the
- specific language governing permissions and limitations
- under the License.
-
-The append-transform plugin appends text to the body of an HTTP
-response. It obtains this text from a file; the name of the file
-containing the append text is a parameter you specify in
-``plugin.config``, as follows:
-
-::
-
- append-transform.so path/to/file
-
-The append-transform plugin is based on ``null-transform.c``. The only
-difference is that after the plugin feeds the document through the
-transformation, it adds text to the response.
-
-Below is a list of the functions in ``append-transform.c``, in the order
-they appear in the source code. Below each entry is a description of
-what the function does:
-
-- **``my_data_alloc``**
-
- Allocates and initializes a ``MyData`` structure. The plugin defines
- a struct, ``MyData``, as follows:
-
- .. code-block:: c
-
- typedef struct {
- TSVIO output_vio;
- TSIOBuffer output_buffer;
- TSIOBufferReader output_reader;
- int append_needed;
- } MyData;
-
- The ``MyData`` structure is used to represent data that the
- transformation (vconnection) needs. The transformation's data pointer
- is set to a ``MyData`` pointer using ``TSContDataSet`` in the
- ``handle_transform`` routine.
-
-- **``my_data_destroy``**
-
- Destroys objects of type ``MyData``. To deallocate the transform's
- data, the ``append_transform`` routine (see below) calls
- ``my_data_destroy`` when the transformation is complete.
-
-- **``handle_transform``**
-
- This function does the actual data transformation. The transformation
- is created in ``transform_add`` (see below). ``handle_transform`` is
- called by ``append_transform``.
-
-- **``append_transform``**
-
- This is the handler function for the transformation vconnection
- created in ``transform_add``. It is the implementation of the
- vconnection.
-
- - If the transformation vconnection has been closed, then
- ``append_transform`` calls ``my_data_destroy`` to destroy the
- vonnection.
-
- - If ``append_transform`` receives an error event, then it calls
- back the continuation to let it know it has completed the write
- operation.
-
- - If it receives a ``WRITE_COMPLETE`` event, then it shuts down the
- write portion of its vconnection.
-
- - If it receives a ``WRITE_READY`` or any other event (such as
- ``TS_HTTP_RESPONSE_TRANSFORM_HOOK``), then it calls
- ``handle_transform`` to attempt to transform more data.
-
-- **``transformable``**
-
- The plugin transforms only documents that have a content type of
- ``text/html``. This function examines the ``Content-Type`` MIME
- header field in the response header. If the value of the MIME field
- is ``text/html``, then the function returns 1; otherwise, it returns
- zero.
-
-- **``transform_add``**
-
- Creates the transformation for the current transaction and sets up a
- transformation hook. The handler function for the transformation is
- ``append_transform``.
-
-- **``transform_plugin``**
-
- This is the handler function for the main continuation for the
- plugin. Traffic Server calls this function whenever it reads an HTTP
- response header. ``transform_plugin`` does the following:
-
- - Gets a handle to the HTTP transaction being processed
-
- - Calls ``transformable`` to determine whether the response document
- content is of type ``text/html``
-
- - If the content is transformable, then it calls ``transform_add``
- to create the transformation.
-
- - Calls ``TSHttpTxnReenable`` to continue the transaction
-
-- **``load``**
-
- Opens the file containing the text to be appended and loads the
- contents of the file into an ``TSIOBuffer`` called ``append_buffer``.
-
-- **``TSPluginInit``**
-
- Does the following:
-
- - Checks to make sure that the required configuration information
- (the append text filename) is entered in ``plugin.config``
- correctly.
-
- - If there is a filename, then ``TSPluginInit`` calls load to load
- the text.
-
- - Creates a continuation for the plugin. The handler for this
- continuation is ``transform_plugin``.
-
- - Adds the plugin's continuation to
- ``TS_HTTP_READ_RESPONSE_HDR_HOOK``. In other words, it sets up a
- callback of the plugin's continuation when Traffic Server reads
- HTTP response headers.
-
-
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/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
deleted file mode 100644
index ee6859b..0000000
--- a/doc/sdk/http-transformation-plugin/sample-buffered-null-transformation-plugin.en.rst
+++ /dev/null
@@ -1,212 +0,0 @@
-The Sample Buffered Null Transform Plugin
-*****************************************
-
-.. Licensed to the Apache Software Foundation (ASF) under one
- or more contributor license agreements. See the NOTICE file
- distributed with this work for additional information
- regarding copyright ownership. The ASF licenses this file
- to you under the Apache License, Version 2.0 (the
- "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing,
- software distributed under the License is distributed on an
- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- KIND, either express or implied. See the License for the
- specific language governing permissions and limitations
- under the License.
-
-The buffered null transform, ``bnull-transform.c``, reads the response
-content into a buffer and then writes the full buffer out to the client.
-Many examples of transformations, such as compression, require you to
-gather the full response content in order to perform the transformation.
-
-The buffered null transform uses a state variable to keep track of when
-it is (a) reading data into the buffer and (b) writing the data from the
-buffer to the downstream vconnection.
-
-The following is a step-by-step walk through the buffered null
-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)); }
-
- With this ``TSPluginInit`` routine, the plugin is called back every
- time Traffic Server reads a response header.
-
-#. Checks to see if the transaction response is transformable.
-
- .. 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
- data is ready to be transformed (as it is streaming from the origin
- server).
-
- .. code-block:: c
-
- static void transform_add (TSHttpTxn txnp)
- {
- TSVConn connp;
- connp = TSTransformCreate (bnull_transform, txnp);
- TSHttpTxnHookAdd (txnp, TS_HTTP_RESPONSE_TRANSFORM_HOOK, connp);
- }
-
- The previous code fragment shows that the handler function for the
- transformation vconnection is ``bnull_transform``.
-
-#. The ``bnull_transform`` function has to handle ``ERROR``,
- ``WRITE_COMPLETE``, ``WRITE_READY``, and ``IMMEDIATE`` events. If
- the transform is just beginning, the event received is probably
- ``IMMEDIATE``. The ``bnull_transform`` function calls
- ``handle_transform`` to handle ``WRITE_READY`` and ``IMMEDIATE``.
-
-#. The ``handle_transform`` function examines the data parameter for
- the continuation passed to it (the continuation passed to
- ``handle_transform`` is the transformation vconnection). The data
- structure keeps track of two states: copying the data into the
- buffer (``STATE_BUFFER_DATA``) and writing the contents of the
- buffer to the output vconnection (``STATE_OUTPUT_DATA``).
-
-#. Get a handle to the input VIO (see the ``handle_buffering``
- function). ``input_vio = TSVConnWriteVIOGet (contp);`` This is so
- that the transformation can get information about the upstream
- vconnection's write operation to the input buffer.
-
-#. Copy data from the input buffer to the output buffer. See the
- ``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
- ``handle_buffering`` function wakes up the upstream vconnection by
- sending it ``WRITE_READY``:
-
- .. code-block:: c
-
- if (TSVIONTodoGet (write_vio) > 0) {
- if (towrite > 0) {
- TSContCall (TSVIOContGet (write_vio),
- TS_EVENT_VCONN_WRITE_READY, write_vio);
- }
- } else {
-
- The process of passing data through the transformation is
- illustrated in the following diagram. The transformation sends
- ``WRITE_READY`` events when it needs more data; when data is
- available, the upstream vconnection reenables the transformation
- with an ``IMMEDIATE`` event.
-
- The following diagram illustrates the read from an input
- vconnection:
-
- **Reading Data Into the Buffer (the ``STATE_BUFFER_DATA`` State)**
- {#ReadingDataIntoBuffer}
-
- .. figure:: /static/images/sdk/vconn_buffer.jpg
- :alt: Reading Data Into the Buffer the STATE\_BUFFER\_DATA State
-
- Reading Data Into the Buffer the STATE\_BUFFER\_DATA State
-
-#. When the data is read into the output buffer, the
- ``handle_buffering`` function sets the state of the transformation's
- data structure to ``STATE_OUTPUT_DATA`` and calls the upstream
- 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);
-
-#. The upstream vconnection will probably shut down the write operation
- when it receives the ``WRITE_COMPLETE`` event. The handler function
- of the transformation, ``bnull_transform``, receives an
- ``IMMEDIATE`` event and calls the ``handle_transform`` function.
- This time, the state is ``STATE_OUTPUT_DATA``, so
- ``handle_transform`` calls ``handle_output``.
-
-#. The ``handle_output`` function gets a handle to the output
- vconnection: ``output_conn = TSTransformOutputVConnGet (contp);``
-
-#. The ``handle_output`` function writes the buffer to the output
- vconnection:
-
- .. code-block:: c
-
- data->output_vio =
- TSVConnWrite (output_conn, contp, data->output_reader,
- TSIOBufferReaderAvail (data->output_reader) );
-
- The following diagram illustrates the write to the output
- vconnection:
-
- **Writing the Buffered Data to the Output Vconnection**
- {#WritingBufferedtDataIntoVConnection}
-
- .. figure:: /static/images/sdk/vconn_buf_output.jpg
- :alt: Writing the Buffered Data to the Output Vconnection
-
- Writing the Buffered Data to the Output Vconnection
-
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/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
deleted file mode 100644
index ac500f2..0000000
--- a/doc/sdk/http-transformation-plugin/sample-null-transformation-plugin.en.rst
+++ /dev/null
@@ -1,217 +0,0 @@
-The Sample Null Transform Plugin
-********************************
-
-.. Licensed to the Apache Software Foundation (ASF) under one
- or more contributor license agreements. See the NOTICE file
- distributed with this work for additional information
- regarding copyright ownership. The ASF licenses this file
- to you under the Apache License, Version 2.0 (the
- "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing,
- software distributed under the License is distributed on an
- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- KIND, either express or implied. See the License for the
- specific language governing permissions and limitations
- under the License.
-
-This section provides a step-by-step description of what the null
-transform plugin does, along with sections of code that apply. For
-context, you can find each code snippet in the complete source code.
-Some of the error checking details are left out - to give the
-description a step-by-step flow, only the highlights of the transform
-are included.
-
-Below is an overview of the null transform plugin:
-
-1. 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));
-
- With this ``TSPluginInit`` routine, the plugin is called back every
- time Traffic Server reads a response header.
-
-2. Checks to see if the transaction response is transformable.
-
- .. 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 (you can also tell Traffic Server to cache untransformed
- content, if you want). Therefore, only responses received directly
- from an origin server need to be transformed. Objects served from
- 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
-
- static int transformable (TSHttpTxn txnp)
- {
- 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;
- }
- }
-
-3. If the response is transformable, then the plugin creates a
- transformation vconnection that gets called back when the response
- data is ready to be transformed (as it is streaming from the origin
- server).
-
- .. code-block:: c
-
- static void transform_add (TSHttpTxn txnp)
- {
- TSVConn connp;
- connp = TSTransformCreate (null_transform, txnp);
- TSHttpTxnHookAdd (txnp, TS_HTTP_RESPONSE_TRANSFORM_HOOK, connp);
- }
-
- The previous code fragment shows that the handler function for the
- transformation vconnection is ``null_transform``.
-
-4. Get a handle to the output vconnection (that receives data from the
- tranformation).
-
- .. code-block:: c
-
- output_conn = TSTransformOutputVConnGet (contp);
-
-5. Get a handle to the input VIO. (See the ``handle_transform``
- function.)
-
- .. code-block:: c
-
- input_vio = TSVConnWriteVIOGet (contp);
-
- This is so that the transformation can get information about the
- upstream vconnection's write operation to the input buffer.
-
-6. Initiate a write to the output vconnection of the specified number
- of bytes. When the write is initiated, the transformation expects to
- receive ``WRITE_READY``, ``WRITE_COMPLETE``, or ``ERROR`` events
- from the output vconnection. See the ``handle_transform`` function
- for the following code fragment:
-
- .. code-block:: 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
-
- 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);
-
-9. Modify the input VIO to tell it how much data has been read
- (increase the value of ``ndone``). See the ``handle_transform``
- function for the following code fragment:
-
- .. code-block:: c
-
- TSVIONDoneSet (input_vio, TSVIONDoneGet (input_vio) + towrite);
-
-10. If there is more data left to read ( if ndone < nbytes), then the
- ``handle_transform`` function wakes up the downstream vconnection
- with a reenable and wakes up the upstream vconnection by sending it
- ``WRITE_READY``:
-
- .. code-block:: c
-
- if (TSVIONTodoGet (input_vio) > 0) {
- if (towrite > 0) {
- TSVIOReenable (data->output_vio);
-
- TSContCall (TSVIOContGet (input_vio),
- TS_EVENT_VCONN_WRITE_READY, input_vio);
- }
- } else {
-
- The process of passing data through the transformation is
- illustrated in the following diagram. The downstream vconnections
- send ``WRITE_READY`` events when they need more data; when data is
- available, the upstream vconnections reenable the downstream
- vconnections. In this instance, the ``TSVIOReenable`` function sends
- ``TS_EVENT_IMMEDIATE``.
-
- **Passing Data Through a Transformation**
- {#PassingDataThroughaTransformation}
-
-.. figure:: /static/images/sdk/vconnection1.jpg
- :alt: Passing Data Through a Transformation
-
- Passing Data Through a Transformation
-
-11. If the ``handle_transform`` function finds there is no more data to
- read, then it sets ``nbytes`` to ``ndone`` on the output
- (downstream) VIO and wakes up the output vconnection with a
- reenable. It then triggers the end of the write operation from the
- upstream vconnection by sending the upstream vconnection a
- ``WRITE_COMPLETE`` event.
-
- .. code-block:: c
-
- TSVIONBytesSet (data->output_vio, TSVIONDoneGet (input_vio));
- TSVIOReenable (data->output_vio);
- TSContCall (TSVIOContGet (input_vio),
- TS_EVENT_VCONN_WRITE_COMPLETE, input_vio);
- }
-
- When the upstream vconnection receives the ``WRITE_COMPLETE`` event,
- it will probably shut down the write operation.
-
-12. Similarly, when the downstream vconnection has consumed all of the
- data, it sends the transformation a ``WRITE_COMPLETE`` event. The
- transformation handles this event with a shut down (the
- transformation shuts down the write operation to the downstream
- vconnection). See the ``null_plugin`` function for the following
- code fragment:
-
- .. code-block:: c
-
- case TS_EVENT_VCONN_WRITE_COMPLETE:
- TSVConnShutdown (TSTransformOutputVConnGet (contp), 0, 1
- break;
-
- The following diagram illustrates the flow of events:
-
- **Ending the Transformation** {#EndingTransformation}
-
- .. figure:: /static/images/sdk/vconnection2.jpg
- :alt: Ending the Transformation
-
- Ending the Transformation
-
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/sdk/index.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/index.en.rst b/doc/sdk/index.en.rst
deleted file mode 100644
index fbd2b18..0000000
--- a/doc/sdk/index.en.rst
+++ /dev/null
@@ -1,70 +0,0 @@
-.. _programmers-guide:
-
-Programmers' Guide
-******************
-
-.. Licensed to the Apache Software Foundation (ASF) under one
- or more contributor license agreements. See the NOTICE file
- distributed with this work for additional information
- regarding copyright ownership. The ASF licenses this file
- to you under the Apache License, Version 2.0 (the
- "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing,
- software distributed under the License is distributed on an
- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- KIND, either express or implied. See the License for the
- specific language governing permissions and limitations
- under the License.
-
-*In progress*
-
-**Abstract**
-
-The *Traffic Server Software Developers Kit* shows you how to create
-plugins using the Traffic Server SDK.
-
-Introduction
---------------
-
-This documentation is a work in progress. It was originally written for
-a previous, commercially-available version of Traffic Server that
-supported different operating systems and more functions than the
-current version. As a result, some of the sections may refer to
-functionality that no longer exists.
-
-If you find any such issues, you may want to submit a `bug or a
-patch <https://issues.apache.org/jira/secure/CreateIssue!default.jspa?pid=12310963>`__.
-We also have a Wiki page explaining how to `create useful bug reports
-<https://cwiki.apache.org/confluence/display/TS/Filing+useful+bug+reports>`__.
-We encourage everyone to file tickets, early and often. Looking for existing,
-duplicate bugs is encouraged, but not required.
-
-Contents:
-
-.. toctree::
- :maxdepth: 2
-
- preface.en
- getting-started.en
- how-to-create-trafficserver-plugins.en
- remap-plugin.en
- header-based-plugin-examples.en
- http-transformation-plugin.en
- new-protocol-plugins.en
- http-hooks-and-transactions.en
- trafficserver-timers.en
- misc-interface-guide.en
- http-headers.en
- mutex-guide.en
- continuations.en
- plugin-configurations.en
- actions-guide.en
- io-guide.en
- plugin-management.en
- adding-statistics.en
- sample-source-code.en
- troubleshooting-tips.en
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/sdk/io-guide.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/io-guide.en.rst b/doc/sdk/io-guide.en.rst
deleted file mode 100644
index 12d3397..0000000
--- a/doc/sdk/io-guide.en.rst
+++ /dev/null
@@ -1,194 +0,0 @@
-IO Guide
-********
-
-.. Licensed to the Apache Software Foundation (ASF) under one
- or more contributor license agreements. See the NOTICE file
- distributed with this work for additional information
- regarding copyright ownership. The ASF licenses this file
- to you under the Apache License, Version 2.0 (the
- "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing,
- software distributed under the License is distributed on an
- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- KIND, either express or implied. See the License for the
- specific language governing permissions and limitations
- under the License.
-
-This chapter contains the following sections:
-
-.. toctree::
- :maxdepth: 2
-
- io-guide/net-vconnections.en
- io-guide/transformations.en
- io-guide/vios.en
- io-guide/io-buffers.en
- io-guide/guide-to-cache-api.en
-
-
-.. _sdk-vconnections:
-
-Vconnections
-------------
-
-Vconnections: a User's Perspective
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-To use a vconnection, a user must first get a handle to one. This is
-usually accomplished by having it handed to the user; the user may also
-simply issue a call that creates a vconnection (such as
-``TSNetConnect)``. In the case of transform plugins, the plugin creates
-a transformation vconnection viav ``TSTransformCreate`` and then
-accesses the output vconnection using ``TSTransformOutputVConnGet``.
-
-After getting a handle to a vconnection, the user can then issue a read
-or write call. It's important to note that not all vconnections support
-both reading and writing - as of yet, there has not been a need to query
-a vconnection about whether it can perform a read or write operation.
-That ability should be obvious from context.
-
-To issue a read or write operation, a user calls ``TSVConnRead`` or
-``TSVConnWrite``. These two operations both return ``VIO (TSVIO)``. The
-VIO describes the operation being performed and how much progress has
-been made. Transform plugins initiate output to the downstream
-vconnection by calling ``TSVConnWrite``.
-
-A vconnection read or write operation is different from a normal UNIX
-``read(2)`` or ``write(2)`` operation. Specifically, the vconnection
-operation can specify more data to be read or written than exists in the
-buffer handed to the operation. For example, it's typical to issue a
-read for ``INT64_MAX`` (9 quintillion) bytes from a network vconnection
-in order to read all the data from the network connection until the end
-of stream is reached. This contrasts with the usual UNIX fashion of
-issuing repeated calls to ``read(2)`` until one of the calls finally
-returns ``0`` to indicate the end of stream was reached (indeed, the
-underlying implementation of vconnections on UNIX still does issue those
-calls to ``read(2)``, but the interface does not expose that detail).
-
-At most, a given vconnection can have one read operation and one write
-operation being performed on it. This is restricted both by design and
-common sense: if two write operations were performed on a single
-vconnection, then the user would not be able to specify which should
-occur first and the output would occur in an intermingled fashion. Note
-that both a read operation and a write operation can happen on a single
-vconnection at the same time; the restriction is for more than one
-operation of the same type.
-
-One obvious issue is that the buffer passed to ``TSVConnRead`` and
-``TSVConnWrite`` won't be large enough - there is no reasonable way to
-make a buffer that can hold ``INT64_MAX`` (9 quintillion) bytes! The
-secret is that vconnections engage in a protocol whereby they signal to
-the user (via the continuation passed to ``TSVConnRead`` and
-``TSVConnWrite``) that they have emptied the buffers passed to them and
-are ready for more data. When this occurs, it is up to the user to add
-more data to the buffers (or wait for more data to be added) and then
-wake up the vconnection by calling ``TSVIOReenable`` on the VIO
-describing the operation. ``TSVIOReenable`` specifies that the buffer
-for the operation has been modified and that the vconnection should
-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
-
- TSVIO TSVConnWrite (TSVConn connp, TSCont contp, TSIOBufferReader readerp, int nbytes)
-
-The ``connp`` is the vconnection the user is writing to and ``contp`` is
-the "user" - i.e., the continuation that ``connp`` calls back when it
-has emptied its buffer and is ready for more data.
-
-The call made in the null transform plugin is:
-
-.. code-block:: c
-
- TSVConnWrite (output_conn, contp, data->output_reader, TSVIONBytesGet (input_vio));
-
-In the example above, ``contp`` is the transformation vconnection that
-is writing to the output vconnection. The number of bytes to be written
-is obtained from ``input_vio`` by ``TSVIONBytesGet``.
-
-When a vconnection calls back its user to indicate that it wants more
-data (or when some other condition has occurred), it issues a call to
-``TSContCall``. It passes the ``TSVIO`` describing the operation as the
-data parameter, and one of the values below as the event parameter.
-
-``TS_EVENT_ERROR``
- Indicates an error has occurred on the vconnection. This will happen
- for network IO if the underlying ``read(2)`` or ``write(2)`` call
- returns an error.
-
-``TS_EVENT_VCONN_READ_READY``
- The vconnection has placed data in the buffer passed to an
- ``TSVConnRead`` operation and it would like to do more IO, but the
- buffer is now full. When the user consumes the data from the buffer,
- this should re-enable the VIO so it indicates to the vconnection
- that the buffer has been modified.
-
-``TS_EVENT_VCONN_WRITE_READY``
- The vconnection has removed data from the buffer passed to an
- ``TSVConnWrite`` operation and it would like to do more IO, but the
- buffer does not have enough data in it. When placing more data in
- the buffer, the user should re-enable the VIO so it indicates to the
- vconnection that the buffer has been modified.
-
-``TS_EVENT_VCONN_READ_COMPLETE``
- The vconnection has read all the bytes specified by an
- ``TSVConnRead`` operation. The vconnection can now be used to
- initiate a new IO operation.
-
-``TS_EVENT_VCONN_WRITE_COMPLETE``
- The vconnection has written all the bytes specified by an
- ``TSVConnWrite`` operation and can now be used to initiate a new IO
- operation.
-
-``TS_EVENT_VCONN_EOS``
- An attempt was made to read past the end of the stream of bytes
- during the handling of an ``TSVConnRead`` operation. This event
- occurs when the number of bytes available for reading from a
- vconnection is less than the number of bytes the user specifies
- should be read from the vconnection in a call to ``TSVConnRead``. A
- common case where this occurs is when the user specifies that
- ``INT64_MAX`` bytes are to be read from a network connection.
-
-For example: the null transform plugin's transformation receives
-``TS_EVENT_VCONN_WRITE_READY`` and ``TS_EVENT_VCONN_WRITE_COMPLETE``
-events from the downstream vconnection as a result of the call to
-``TSVConnWrite``.
-
-After using a vconnection, the user must call ``TSVConnClose`` or
-``TSVConnAbort``. While both calls indicate that the vconnection can
-destroy itself, ``TSVConnAbort`` should be used when the connection is
-being closed abnormally. After a call to ``TSVConnClose`` or
-``TSVConnAbort``, the user will not be called back by the vconnection
-again.
-
-Sometimes it's desirable to simply close down the write portion of a
-connection while keeping the read portion open. This can be accomplished
-via the ``TSVConnShutdown`` function, which shuts down either the read
-or write portion of a vconnection. *Shutdown* means that the vconnection
-will no longer call back the user with events for the portion of the
-connection that was shut down. For example: if the user shuts down the
-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 :ref:`Writing Content Transform
-Plugins <WritingContentTransformPlugin>`.
-
-The vconnection functions are listed below:
-
-- :c:func:`TSVConnAbort`
-- :c:func:`TSVConnClose`
-- :c:func:`TSVConnClosedGet`
-- :c:func:`TSVConnRead`
-- :c:func:`TSVConnReadVIOGet`
-- :c:func:`TSVConnShutdown`
-- :c:func:`TSVConnWrite`
-- :c:func:`TSVConnWriteVIOGet`
-
-
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/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
deleted file mode 100644
index 2944044..0000000
--- a/doc/sdk/io-guide/guide-to-cache-api.en.rst
+++ /dev/null
@@ -1,68 +0,0 @@
-Guide to the Cache API
-**********************
-
-.. Licensed to the Apache Software Foundation (ASF) under one
- or more contributor license agreements. See the NOTICE file
- distributed with this work for additional information
- regarding copyright ownership. The ASF licenses this file
- to you under the Apache License, Version 2.0 (the
- "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing,
- software distributed under the License is distributed on an
- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- KIND, either express or implied. See the License for the
- specific language governing permissions and limitations
- under the License.
-
-.. toctree::
- :maxdepth: 2
-
- guide-to-cache-api/how-to-do-a-cache-write.en
- guide-to-cache-api/how-to-do-a-cache-remove.en
- guide-to-cache-api/errors.en
- guide-to-cache-api/example.en
-
-
-The cache API enables plugins to read, write, and remove objects in the
-Traffic Server cache. All cache APIs are keyed by an object called an
-``TSCacheKey``; cache keys are created via ``TSCacheKeyCreate``; keys
-are destroyed via ``TSCacheKeyDestroy``. Use ``TSCacheKeyDigestSet`` to
-set the hash of the cache key.
-
-Note that the cache APIs differentiate between HTTP data and plugin
-data. The cache APIs do not allow you to write HTTP docs in the cache;
-you can only write plugin-specific data (a specific type of data that
-differs from the HTTP type).
-
-**Example:**
-
-.. code-block:: c
-
- const unsigned char *key_name = "example key name";
-
- TSCacheKey key;
- TSCacheKeyCreate (&key);
- TSCacheKeyDigestSet (key, (unsigned char *) key_name , strlen(key_name));
- TSCacheKeyDestroy (key);
-
-How to Do a Cache Read
-~~~~~~~~~~~~~~~~~~~~~~
-
-``TSCacheRead`` does not really read - it is used for lookups (see the
-sample Protocol plugin). Possible callback events include:
-
-- ``TS_EVENT_CACHE_OPEN_READ`` - indicates the lookup was successful.
- The data passed back along with this event is a cache vconnection
- that can be used to initiate a read on this keyed data.
-
-- ``TS_EVENT_CACHE_OPEN_READ_FAILED`` - indicates the lookup was
- unsuccessful. Reasons for this event could be that another
- continuation is writing to that cache location, or the cache key
- doesn't refer to a cached resource. Data payload for this event
- indicates the possible reason the read failed (``TSCacheError``).
-
-
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/sdk/io-guide/guide-to-cache-api/errors.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/io-guide/guide-to-cache-api/errors.en.rst b/doc/sdk/io-guide/guide-to-cache-api/errors.en.rst
deleted file mode 100644
index f45866b..0000000
--- a/doc/sdk/io-guide/guide-to-cache-api/errors.en.rst
+++ /dev/null
@@ -1,31 +0,0 @@
-Errors
-******
-
-.. Licensed to the Apache Software Foundation (ASF) under one
- or more contributor license agreements. See the NOTICE file
- distributed with this work for additional information
- regarding copyright ownership. The ASF licenses this file
- to you under the Apache License, Version 2.0 (the
- "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing,
- software distributed under the License is distributed on an
- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- KIND, either express or implied. See the License for the
- specific language governing permissions and limitations
- under the License.
-
-Errors pertaining to the failure of various cache operations are
-indicated by ``TSCacheError`` (enumeration). They are as follows:
-
-- ``TS_CACHE_ERROR_NO_DOC`` - the key does not match a cached resource
-
-- ``TS_CACHE_ERROR_DOC_BUSY`` - e.g, another continuation could be
- writing to the cache location
-
-- ``TS_CACHE_ERROR_NOT_READY`` - the cache is not ready
-
-
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/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
deleted file mode 100644
index 0179de6..0000000
--- a/doc/sdk/io-guide/guide-to-cache-api/example.en.rst
+++ /dev/null
@@ -1,73 +0,0 @@
-Example
-*******
-
-.. Licensed to the Apache Software Foundation (ASF) under one
- or more contributor license agreements. See the NOTICE file
- distributed with this work for additional information
- regarding copyright ownership. The ASF licenses this file
- to you under the Apache License, Version 2.0 (the
- "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing,
- software distributed under the License is distributed on an
- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- KIND, either express or implied. See the License for the
- specific language governing permissions and limitations
- under the License.
-
-In the example below, suppose there is a cache hit and the cache returns
-a vconnection that enables you to read the document from cache. To do
-this, you need to prepare a buffer (``cache_bufp``) to hold the
-document; meanwhile, use ``TSVConnCachedObjectSizeGet`` to find out the
-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
-
- TSIOBuffer cache_bufp = TSIOBufferCreate ();
- TSIOBufferReader cache_readerp = TSIOBufferReaderAlloc (out_bufp);
- TSVConn cache_vconnp = NULL;
- TSVIO cache_vio = NULL;
- int content_length = 0;
-
-In the ``TS_CACHE_OPEN_READ`` handler:
-
-.. code-block:: 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
-
- (usual VCONN_READ_READY handler logic)
- int nbytes = TSVIONBytesGet (cache_vio);
- int ntodo = TSVIONTodoGet (cache_vio);
- int ndone = TSVIONDoneGet (cache_vio);
- (consume data in cache_bufp)
- TSVIOReenable (cache_vio);
-
-Do not try to get continuations or VIOs from ``TSVConn`` objects for
-cache vconnections. Also note that the following APIs can only be used
-on transformation vconnections and must not be used on cache
-vconnections or net vconnections:
-
-- ``TSVConnWriteVIOGet``
-
-- ``TSVConnReadVIOGet``
-
-- ``TSVConnClosedGet``
-
-APIs such as ``TSVConnRead``, ``TSVConnWrite``, ``TSVConnClose``,
-``TSVConnAbort``, and ``TSVConnShutdown`` can be used on any kind of
-vconnections.
-
-When you are finished:
-
-``TSCacheKeyDestroy (key);``
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/sdk/io-guide/guide-to-cache-api/how-to-do-a-cache-remove.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/io-guide/guide-to-cache-api/how-to-do-a-cache-remove.en.rst b/doc/sdk/io-guide/guide-to-cache-api/how-to-do-a-cache-remove.en.rst
deleted file mode 100644
index 0edadf6..0000000
--- a/doc/sdk/io-guide/guide-to-cache-api/how-to-do-a-cache-remove.en.rst
+++ /dev/null
@@ -1,31 +0,0 @@
-How to Do a Cache Remove
-************************
-
-.. Licensed to the Apache Software Foundation (ASF) under one
- or more contributor license agreements. See the NOTICE file
- distributed with this work for additional information
- regarding copyright ownership. The ASF licenses this file
- to you under the Apache License, Version 2.0 (the
- "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing,
- software distributed under the License is distributed on an
- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- KIND, either express or implied. See the License for the
- specific language governing permissions and limitations
- under the License.
-
-Use ``TSCacheRemove`` to remove items from the cache. Possible callback
-events include:
-
-- ``TS_EVENT_CACHE_REMOVE`` - the item was removed. There is no data
- payload for this event.
-
-- ``TS_EVENT_CACHE_REMOVE_FAILED`` - indicates the cache was unable to
- remove the item identified by the cache key. ``TSCacheError`` data
- indicates why the remove failed.
-
-
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/sdk/io-guide/guide-to-cache-api/how-to-do-a-cache-write.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/io-guide/guide-to-cache-api/how-to-do-a-cache-write.en.rst b/doc/sdk/io-guide/guide-to-cache-api/how-to-do-a-cache-write.en.rst
deleted file mode 100644
index ebaf99d..0000000
--- a/doc/sdk/io-guide/guide-to-cache-api/how-to-do-a-cache-write.en.rst
+++ /dev/null
@@ -1,34 +0,0 @@
-How to Do a Cache Write
-***********************
-
-.. Licensed to the Apache Software Foundation (ASF) under one
- or more contributor license agreements. See the NOTICE file
- distributed with this work for additional information
- regarding copyright ownership. The ASF licenses this file
- to you under the Apache License, Version 2.0 (the
- "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing,
- software distributed under the License is distributed on an
- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- KIND, either express or implied. See the License for the
- specific language governing permissions and limitations
- under the License.
-
-Use ``TSCacheWrite`` to write to a cache (see the :ref:`sample Protocol
-plugin <about-the-sample-protocol>`). Possible
-callback events include:
-
-- ``TS_EVENT_CACHE_WRITE_READ`` - indicates the lookup was successful.
- The data passed back along with this event is a cache vconnection
- that can be used to initiate a cache write.
-
-- ``TS_EVENT_CACHE_OPEN_WRITE_FAILED`` - event returned when another
- continuation is currently writing to this location in the cache. Data
- payload for this event indicates the possible reason for the write
- failing (``TSCacheError``).
-
-
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/sdk/io-guide/io-buffers.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/io-guide/io-buffers.en.rst b/doc/sdk/io-guide/io-buffers.en.rst
deleted file mode 100644
index a43bab9..0000000
--- a/doc/sdk/io-guide/io-buffers.en.rst
+++ /dev/null
@@ -1,52 +0,0 @@
-IO Buffers
-**********
-
-.. Licensed to the Apache Software Foundation (ASF) under one
- or more contributor license agreements. See the NOTICE file
- distributed with this work for additional information
- regarding copyright ownership. The ASF licenses this file
- to you under the Apache License, Version 2.0 (the
- "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing,
- software distributed under the License is distributed on an
- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- KIND, either express or implied. See the License for the
- specific language governing permissions and limitations
- under the License.
-
-The IO buffer data structure is the building block of the vconnection
-abstraction. An **IO buffer** (``TSIOBuffer``) is composed of a list of
-buffer blocks that point to buffer data. Both the buffer block
-(``TSIOBufferBlock``) and buffer data (``TSIOBufferData``) data
-structures are reference-counted, so they can reside in multiple buffers
-at the same time. This makes it extremely efficient to copy data from
-one IO buffer to another via ``TSIOBufferCopy``, since Traffic Server
-must only copy pointers and adjust reference counts appropriately (and
-doesn't actually copy any data).
-
-The IO buffer abstraction provides for a single writer and multiple
-readers. In order for the readers to have no knowledge of each other,
-they manipulate IO buffers through the ``TSIOBufferReader`` data
-structure. Since only a single writer is allowed, there is no
-corresponding ``TSIOBufferWriter`` data structure. The writer simply
-modifies the IO buffer directly. To see an example that illustrates how
-to use IOBuffers, refer to the sample code in the description of
-:c:func:`TSIOBufferBlockReadStart`.
-
-Additional information about IO buffer functions:
-
-- The ``TSIOBufferReader`` data structure tracks how much data in
- ``TSIOBuffer`` has been read. It has an offset number of bytes that
- is the current start point of a particular buffer reader (for every
- read operation on an ``TSIOBuffer``, you must allocate an
- ``TSIOBufferReader``).
-
-- Bytes that have already been read may not necessarily be freed within
- the ``TSIOBuffer``. To consume bytes that have been read, you must
- call ``TSIOBufferConsume``.
-
-
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/sdk/io-guide/net-vconnections.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/io-guide/net-vconnections.en.rst b/doc/sdk/io-guide/net-vconnections.en.rst
deleted file mode 100644
index 4c4aef5..0000000
--- a/doc/sdk/io-guide/net-vconnections.en.rst
+++ /dev/null
@@ -1,31 +0,0 @@
-Net Vconnections
-****************
-
-.. Licensed to the Apache Software Foundation (ASF) under one
- or more contributor license agreements. See the NOTICE file
- distributed with this work for additional information
- regarding copyright ownership. The ASF licenses this file
- to you under the Apache License, Version 2.0 (the
- "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing,
- software distributed under the License is distributed on an
- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- KIND, either express or implied. See the License for the
- specific language governing permissions and limitations
- under the License.
-
-A **network vconnection** (or *netvconnection*) is a wrapper
-around a TCP socket that enables the socket to work within the Traffic
-Server vconnection framework. See
-:ref:`vconnections <sdk-vconnections>` for more information about
-the Traffic Server abstraction for doing asynchronous IO.
-
-The netvconnection functions are listed below:
-
-- [dox 'TSNetAccept'] in [dox "TSNetAccept" :src\_file]
-- [dox %TSNetConnect%] in [dox :src\_file]
-
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/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
deleted file mode 100644
index acfab5a..0000000
--- a/doc/sdk/io-guide/transformations.en.rst
+++ /dev/null
@@ -1,179 +0,0 @@
-Transformations
-***************
-
-.. Licensed to the Apache Software Foundation (ASF) under one
- or more contributor license agreements. See the NOTICE file
- distributed with this work for additional information
- regarding copyright ownership. The ASF licenses this file
- to you under the Apache License, Version 2.0 (the
- "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing,
- software distributed under the License is distributed on an
- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- KIND, either express or implied. See the License for the
- specific language governing permissions and limitations
- under the License.
-
-The Vconnection Implementor's View
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-A VConnection implementor writes only transformations. All other
-VConnections (net VConnections and cache VConnections) are implemented
-in iocore. As mentioned earlier, a given vconnection can have a maximum
-of one read operation and one write operation being performed on it. The
-vconnection user gets information about the operation being performed by
-examining the VIO returned by a call to ``TSVConnRead`` or
-``TSVConnWrite``. The implementor, in turn, gets a handle on the VIO
-operation by examining the VIO returned by ``TSVConnReadVIOGet`` or
-``TSVConnWriteVIOGet`` (recall that every vconnection created through
-the Traffic Server API has an associated read VIO and write VIO, even if
-it only supports reading or writing).
-
-For example, the null transform plugin's transformation examines the
-input VIO by calling:
-
-.. code-block:: c
-
- input_vio = TSVConnWriteVIOGet (contp);
-
-where ``contp`` is the transformation.
-
-A vconnection is a continuation. This means it has a handler function
-that is run when an event is sent to it, or more accurately, when an
-event that was sent to it is received. It is the handler function's job
-to examine the event, the current state of its read VIO and write VIO,
-and any other internal state the vconnection might have and potentially
-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
-
- int
- vconnection_handler (TSCont contp, TSEvent event, void *edata)
- {
- if (TSVConnClosedGet (contp)) {
- /* Destroy any vconnection specific data here. */
- TSContDestroy (contp);
- return 0;
- } else {
- /* Handle the incoming event */
- }
- }
-
-This code fragment basically shows that many vconnections simply want to
-destroy themselves when they are closed. However, the situation might
-also require the vconnection to do some cleanup processing - which is
-why ``TSVConnClose`` does not simply just destroy the vconnection.
-
-Vconnections are state machines that are animated by the events they
-receive. An event is sent to the vconnection whenever an
-``TSVConnRead``, ``TSVConnWrite``, ``TSVConnClose``,
-``TSVConnShutdown``, or ``TSVIOReenable`` call is performed.
-``TSVIOReenable`` indirectly references the vconnection through a
-back-pointer in the VIO structure to the vconnection. The vconnection
-itself only knows which call was performed by examining its state and
-the state of its VIOs. For example, when ``TSVConnClose`` is called, the
-vconnection is sent an immediate event (``TS_EVENT_IMMEDIATE``). For
-every event the vconnection receives, it needs to check its closed flag
-to see if it has been closed. Similarly, when ``TSVIOReenable`` is
-called, the vconnection is sent an immediate event. For every event the
-vconnection receives, it must check its VIOs to see if the buffers have
-been modified to a state in which it can continue processing one of its
-operations.
-
-Finally, a vconnection is likely the user of other vconnections. It also
-receives events as the user of these other vconnections. When it
-receives such an event, like ``TS_EVENT_VCONN_WRITE_READY``, it might
-just enable another vconnection that's writing into the buffer used by
-the vconnection reading from it. The above description is merely
-intended to give the overall idea for what a vconnection needs to do.
-
-Transformation VConnection
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-A :ref:`transformation <transformations>` is
-a specific type of vconnection. It supports a subset of the vconnection
-functionality that enables one or more transformations to be chained
-together. A transformation sits as a bottleneck between an input data
-source and an output data sink, which enables it to view and modify all
-the data passing through it. Alternatively, some transformations simply
-scan the data and pass it on. A common transformation is one that
-compresses data in some manner.
-
-A transformation can modify either the data stream being sent *to* an
-HTTP client (e.g. the document) or the data stream being sent *from* an
-HTTP client (e.g. post data). To do this, the transformation should hook
-on to one of the following hooks:
-
-- ``TS_HTTP_REQUEST_TRANSFORM_HOOK``
-
-- ``TS_HTTP_RESPONSE_TRANSFORM_HOOK``
-
-Note that because a transformation is intimately associated with a given
-transaction, it is only possible to add the hook to the transaction
-hooks - not to the global or session hooks. Transformations reside in a
-chain, so their ordering is quite easily determined: transformations
-that add themselves to the chain are simply appended to it.
-
-Data is passed in to the transformation by initiating a vconnection
-write operation on the transformation. As a consequence of this design,
-a transformation must support the vconnection write operation. In other
-words, your transformation must expect an upstream vconnection to write
-data to it. The transformation has to read the data, consume it, and
-tell the upstream vconnection it is finished by sending it an
-``TS_EVENT_WRITE_COMPLETE`` event. Transformations cannot send the
-``TS_EVENT_VCONN_WRITE_COMPLETE`` event to the upstream vconnection
-unless they are finished consuming all incoming data. If
-``TS_EVENT_VCONN_WRITE_COMPLETE`` is sent prematurely, then certain
-internal Traffic Server data structures will not be deallocated, thereby
-causing a memory leak.
-
-Here's how to make sure that all incoming data is consumed:
-
-- After reading or copying data, make sure that you consume the data
- and increase the value of ndone for the input VIO, as in the
- following example taken from ``null-transform.c``:
-
- .. code-block:: 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. */
- TSIOBufferReaderConsume (TSVIOReaderGet (input_vio), towrite);
- /* Modify the input VIO to reflect how much has been read.*/
- TSVIONDoneSet (input_vio, TSVIONDoneGet (input_vio) + towrite);
-
-- Before sending ``TS_EVENT_VCONN_WRITE_COMPLETE``, your transformation
- should check the number of bytes remaining in the upstream
- vconnection's write VIO (input VIO) using the function
- ``TSVIONTodoGet`` (``input_vio``). This value should go to zero when
- all of the upstream data is consumed
- (``TSVIONTodoGet = nbytes - ndone``). Do not send
- ``TS_EVENT_VCONN_WRITE_COMPLETE`` events if ``TSVIONTodoGet`` is
- greater than zero.
-- The transformation passes data out of itself by using the output
- vconnection retrieved by ``TSTransformOutputVConnGet``. Immediately
- before Traffic Server initiates the write operation (which inputs
- data into the transformation), it sets the output vconnection either
- to the next transformation in the chain of transformations or to a
- special terminating transformation (if it's the last transformation
- in the chain). Since the transformation is handed ownership of the
- output vconnection, it must close it at some point in order for it to
- be deallocated.
-- All of the transformations in a transformation chain share the
- transaction's mutex. This small restriction (enforced by
- ``TSTransformCreate``) removes many of the locking complications of
- implementing general vconnections. For example, a transformation does
- not have to grab its write VIO mutex before accessing its write VIO
- because it knows it already holds the mutex.
-
-The transformation functions are: \*
-:c:func:`TSTransformCreate`
-\*
-:c:func:`TSTransformOutputVConnGet`
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/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
deleted file mode 100644
index b04aaef..0000000
--- a/doc/sdk/io-guide/vios.en.rst
+++ /dev/null
@@ -1,58 +0,0 @@
-VIOs
-****
-
-.. Licensed to the Apache Software Foundation (ASF) under one
- or more contributor license agreements. See the NOTICE file
- distributed with this work for additional information
- regarding copyright ownership. The ASF licenses this file
- to you under the Apache License, Version 2.0 (the
- "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing,
- software distributed under the License is distributed on an
- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- KIND, either express or implied. See the License for the
- specific language governing permissions and limitations
- under the License.
-
-A **VIO**, or **virtual IO**, is a description of an IO operation that's
-currently in progress. The VIO data structure is used by vconnection
-users to determine how much progress has been made on a particular IO
-operation and to re-enable an IO operation when it stalls due to buffer
-space issues. VIOs are used by vconnection implementors to determine the
-buffer for an IO operation, how much work to do on the IO operation, and
-which continuation to call back when progress on the IO operation is
-made.
-
-The ``TSVIO`` data structure itself is opaque, but it could be defined
-as follows:
-
-.. code-block:: c
-
- typedef struct {
- TSCont continuation;
- TSVConn vconnection;
- TSIOBufferReader reader;
- TSMutex mutex;
- int nbytes;
- int ndone;
- } *TSVIO;
-
-The VIO functions below access and modify various parts of the data
-structure.
-
-- :c:func:`TSVIOBufferGet`
-- :c:func:`TSVIOVConnGet`
-- :c:func:`TSVIOContGet`
-- :c:func:`TSVIOMutexGet`
-- :c:func:`TSVIONBytesGet`
-- :c:func:`TSVIONBytesSet`
-- :c:func:`TSVIONDoneGet`
-- :c:func:`TSVIONDoneSet`
-- :c:func:`TSVIONTodoGet`
-- :c:func:`TSVIOReaderGet`
-- :c:func:`TSVIOReenable`
-
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/sdk/misc-interface-guide.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/misc-interface-guide.en.rst b/doc/sdk/misc-interface-guide.en.rst
deleted file mode 100644
index 067068b..0000000
--- a/doc/sdk/misc-interface-guide.en.rst
+++ /dev/null
@@ -1,60 +0,0 @@
-Miscellaneous Interface Guide
-*****************************
-
-.. Licensed to the Apache Software Foundation (ASF) under one
- or more contributor license agreements. See the NOTICE file
- distributed with this work for additional information
- regarding copyright ownership. The ASF licenses this file
- to you under the Apache License, Version 2.0 (the
- "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing,
- software distributed under the License is distributed on an
- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- KIND, either express or implied. See the License for the
- specific language governing permissions and limitations
- under the License.
-
-Most of the functions in the Traffic Server API provide an interface to
-specific code modules within Traffic Server. The miscellaneous functions
-described in this chapter provide some useful general capabilities. They
-are categorized as follows:
-
-.. toctree::
- :maxdepth: 2
-
- misc-interface-guide/tsfopen-family.en
- misc-interface-guide/memory-allocation.en
- misc-interface-guide/thread-functions.en
-
-
-The C library already provides functions such as ``printf``, ``malloc``,
-and ``fopen`` to perform these tasks. The Traffic Server API versions,
-however, overcome various C library limitations (such as portability to
-all Traffic Server-support platforms).
-
-Debugging Functions
--------------------
-
-- :c:func:`TSDebug`
- prints out a formatted statement if you are running Traffic Server in
- debug mode.
-
-- :c:func:`TSIsDebugTagSet`
- checks to see if a debug tag is set. If the debug tag is set, then
- Traffic Server prints out all debug statements associated with the
- tag.
-
-- :c:func:`TSError`
- prints error messages to Traffic Server's error log
-
-- :c:func:`TSAssert`
- enables the use of assertion in a plugin.
-
-- :c:func:`TSReleaseAssert`
- enables the use of assertion in a plugin.
-
-
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/sdk/misc-interface-guide/memory-allocation.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/misc-interface-guide/memory-allocation.en.rst b/doc/sdk/misc-interface-guide/memory-allocation.en.rst
deleted file mode 100644
index b270feb..0000000
--- a/doc/sdk/misc-interface-guide/memory-allocation.en.rst
+++ /dev/null
@@ -1,46 +0,0 @@
-Memory Allocation
-*****************
-
-.. Licensed to the Apache Software Foundation (ASF) under one
- or more contributor license agreements. See the NOTICE file
- distributed with this work for additional information
- regarding copyright ownership. The ASF licenses this file
- to you under the Apache License, Version 2.0 (the
- "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing,
- software distributed under the License is distributed on an
- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- KIND, either express or implied. See the License for the
- specific language governing permissions and limitations
- under the License.
-
-Traffic Server provides five routines for allocating and freeing memory.
-These routines correspond to similar routines in the C library. For
-example, ``TSrealloc`` behaves like the C library routine ``realloc``.
-
-There are two main reasons for using the routines provided by Traffic
-Server. The first is portability: the Traffic Server API routines behave
-the same on all of Traffic Server's supported platforms. For example,
-``realloc`` does not accept an argument of ``NULL`` on some platforms.
-The second reason is that the Traffic Server routines actually track the
-memory allocations by file and line number. This tracking is very
-efficient, always turned on, and quite useful when tracking down memory
-leaks.
-
-The memory allocation functions are:
-
-- :c:func:`TSfree`
-
-- :c:func:`TSmalloc`
-
-- :c:func:`TSrealloc`
-
-- :c:func:`TSstrdup`
-
-- :c:func:`TSstrndup`
-
-
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/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
deleted file mode 100644
index 2e9c6da..0000000
--- a/doc/sdk/misc-interface-guide/thread-functions.en.rst
+++ /dev/null
@@ -1,34 +0,0 @@
-Thread Functions
-****************
-
-.. Licensed to the Apache Software Foundation (ASF) under one
- or more contributor license agreements. See the NOTICE file
- distributed with this work for additional information
- regarding copyright ownership. The ASF licenses this file
- to you under the Apache License, Version 2.0 (the
- "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing,
- software distributed under the License is distributed on an
- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- KIND, either express or implied. See the License for the
- specific language governing permissions and limitations
- under the License.
-
-The Traffic Server API thread functions enable you to create, destroy,
-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
-:ref:`Mutexes`.
-
-The thread functions are listed below:
-
-- :c:func:`TSThreadCreate`
-- :c:func:`TSThreadDestroy`
-- :c:func:`TSThreadInit`
-- :c:func:`TSThreadSelf`
-
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/ce162a6d/doc/sdk/misc-interface-guide/tsfopen-family.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/misc-interface-guide/tsfopen-family.en.rst b/doc/sdk/misc-interface-guide/tsfopen-family.en.rst
deleted file mode 100644
index b0900b0..0000000
--- a/doc/sdk/misc-interface-guide/tsfopen-family.en.rst
+++ /dev/null
@@ -1,54 +0,0 @@
-The TSfopen Family
-******************
-
-.. Licensed to the Apache Software Foundation (ASF) under one
- or more contributor license agreements. See the NOTICE file
- distributed with this work for additional information
- regarding copyright ownership. The ASF licenses this file
- to you under the Apache License, Version 2.0 (the
- "License"); you may not use this file except in compliance
- with the License. You may obtain a copy of the License at
-
- http://www.apache.org/licenses/LICENSE-2.0
-
- Unless required by applicable law or agreed to in writing,
- software distributed under the License is distributed on an
- "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- KIND, either express or implied. See the License for the
- specific language governing permissions and limitations
- under the License.
-
-The ``fopen`` family of functions in C is normally used for reading
-configuration files, since ``fgets`` is an easy way to parse files on a
-line-by-line basis. The ``TSfopen`` family of functions aims at solving
-the same problem of buffered IO and line at a time IO in a
-platform-independent manner. The ``fopen`` family of C library functions
-can only open a file if a file descriptor less than 256 is available.
-Since Traffic Server often has more than 2000 file descriptors open at
-once, however, the likelihood of an available file descriptor less than
-256 very small. To solve this problem, the ``TSfopen`` family can open
-files with descriptors greater than 256.
-
-The ``TSfopen`` family of routines is not intended for high speed IO or
-flexibility - they are blocking APIs (not asynchronous). For performance
-reasons, you should not directly use these APIs on a Traffic Server
-thread (when being called back on an HTTP hook); it is better to use a
-separate thread for doing the blocking IO. The ``TSfopen`` family is
-intended for reading and writing configuration information when
-corresponding usage of the ``fopen`` family of functions is
-inappropriate due to file descriptor and portability limitations. The
-``TSfopen`` family of functions consists of the following:
-
-- :c:func:`TSfclose`
-
-- :c:func:`TSfflush`
-
-- :c:func:`TSfgets`
-
-- :c:func:`TSfopen`
-
-- :c:func:`TSfread`
-
-- :c:func:`TSfwrite`
-
-