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 2012/10/20 06:52:54 UTC
git commit: SDK man pages TSAPI, TSDebug, TSMalloc,
TSTrafficServerVersion
Updated Branches:
refs/heads/master 71b9502f3 -> baa602e14
SDK man pages TSAPI, TSDebug, TSMalloc, TSTrafficServerVersion
Project: http://git-wip-us.apache.org/repos/asf/trafficserver/repo
Commit: http://git-wip-us.apache.org/repos/asf/trafficserver/commit/baa602e1
Tree: http://git-wip-us.apache.org/repos/asf/trafficserver/tree/baa602e1
Diff: http://git-wip-us.apache.org/repos/asf/trafficserver/diff/baa602e1
Branch: refs/heads/master
Commit: baa602e14e3ef616b60e7650428f55812396fe35
Parents: 71b9502
Author: James Peach <jp...@apache.org>
Authored: Fri Oct 19 21:52:35 2012 -0700
Committer: James Peach <jp...@apache.org>
Committed: Fri Oct 19 21:52:50 2012 -0700
----------------------------------------------------------------------
doc/Makefile.am | 6 +
doc/sdk/TSAPI.3 | 170 ++++++++++++++++++++++++++++++
doc/sdk/TSDebug.3 | 145 +++++++++++++++++++++++++
doc/sdk/TSMalloc.3 | 153 +++++++++++++++++++++++++++
doc/sdk/TSTrafficServerVersionGet.3 | 110 +++++++++++++++++++
5 files changed, 584 insertions(+), 0 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/baa602e1/doc/Makefile.am
----------------------------------------------------------------------
diff --git a/doc/Makefile.am b/doc/Makefile.am
index cf092d4..3767152 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -79,6 +79,12 @@ dist_trafficshell_DATA = \
man1_MANS = \
man/traffic_shell.1
+man3_MANS = \
+ sdk/TSAPI.3 \
+ sdk/TSDebug.3 \
+ sdk/TSMalloc.3 \
+ sdk/TSTrafficServerVersionGet.3
+
EXTRA_DIST = \
Doxyfile.in \
$(dist_trafficshell_DATA)
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/baa602e1/doc/sdk/TSAPI.3
----------------------------------------------------------------------
diff --git a/doc/sdk/TSAPI.3 b/doc/sdk/TSAPI.3
new file mode 100644
index 0000000..9e91a8f
--- /dev/null
+++ b/doc/sdk/TSAPI.3
@@ -0,0 +1,170 @@
+.\" 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. .\"
+.Dd December 22, 2011
+.Dt TSAPI 3ts TSAPI
+.Sh NAME
+.Nm TSAPI
+.Nd introduction to the Traffic Server plugin API
+.Sh SYNOPSIS
+.In ts/ts.h
+.In ts/remap.h
+.Sh DESCRIPTION
+The Traffic Server API enables you to create plugins, using the C
+programming language, that customize the behavior of your Traffic
+Server installation.
+.Pp
+Traffic Server enables sophisticated caching and processing of
+web-related traffic, such as DNS and HTTP requests and responses.
+Traffic Server itself consists of an event-driven loop that can be
+simplified as follows:
+.Pp
+.nf
+ for (;;) {
+ event = get_next_event();
+ handle_event (event);
+ }
+.fn
+.Pp
+You compile your plugin source code to create a shared library that
+Traffic Server loads when it is started. Your plugin contains
+callback functions that are registered for specific Traffic Server
+events. When Traffic Server needs to process an event, it invokes
+any and all call-back functions you've registered for that event
+type.
+.Pp
+Possible uses for plugins include the following:
+.Bl -bullet
+.It
+HTTP processing plugins can filter, blacklist, authorize users or
+transform content.
+.It
+Protocol plugins can enable Traffic Server to proxy-cache
+new protocol content
+.It
+A blacklisting plugin denies attempts to access web sites that are
+off-limits.
+.It
+Append transform plugins add data to HTTP response content.
+.It
+An image conversion plugin transforms JPEG images to GIF images.
+.It
+Compression plugins send response content to a compression server
+that compresses the data (alternatively, a compression library local
+to the Traffic Server host machine could do the compression).
+.It
+Authorization plugins check a user's permissions to access particular
+web sites. The plugin could consult a local authorization program
+or send queries to an authorization server.
+.It
+A plugin that gathers client information from request headers and
+enters this information in a database.
+.It
+A protocol plugin listen for specific protocol requests on a
+designated port and then uses Traffic Server's proxy server & cache
+to serve client requests.
+.El
+.Sh NAMING CONVENTIONS
+The Traffic Server API adheres to the following naming conventions:
+.Bl -bullet
+.It
+The TS prefix is used for all function and variable names defined
+in the Traffic Server API.
+For example,
+.Ft TS_EVENT_NONE ,
+.Ft TSMutex ,
+and
+.Ft TSContCreate .
+.It
+Enumerated values are always written in all uppercase letters.
+For example,
+.Ft TS_EVENT_NONE
+and
+.Ft TS_VC_CLOSE_ABORT .
+.It
+Constant values are all uppercase; enumerated values can be seen
+as a subset of constants.
+For example,
+.Ft TS_URL_SCHEME_FILE
+and
+.Ft TS_MIME_FIELD_ACCEPT .
+.It
+The names of defined types are mixed-case.
+For example,
+.Ft TSHttpSsn
+and
+.Ft TSHttpTxn .
+.It
+Function names are mixed-case.
+For example,
+.Fn TSUrlCreate
+and
+.Fn TSContDestroy .
+.It
+Function names use the following subject-verb naming style:
+TS-<subject>-<verb>, where <subject> goes from general to specific.
+This makes it easier to determine what a function does by reading
+its name. For example, the function to retrieve the password field
+(the specific subject) from a URL (the general subject) is
+.Fn TSUrlPasswordGet .
+.It
+Common verbs like Create, Destroy, Get, Set, Copy, Find, Retrieve,
+Insert, Remove, and Delete are used only when appropriate.
+.El
+.Sh PLUGIN LOADING AND CONFIGURATION
+When Traffic Server is first started, it consults the plugin.config
+file to determine the names of all shared plugin libraries that
+need to be loaded. The plugin.config file also defines arguments
+that are to be passed to each plugin's initialization function,
+.Fn TSPluginInit .
+The records.config file defines the path to each
+plugin shared library.
+.Pp
+The sample plugin.config file below contains a comment line, a blank
+line, and two plugin configurations:
+.Pp
+.nf
+ # This is a comment line.
+ my-plugin.so www.junk.com www.trash.com www.garbage.com
+ some-plugin.so arg1 arg2 $proxy.config.http.cache.on
+.fn
+.Pp
+Each plugin configuration in the plugin.config file resembles a
+UNIX or DOS shell command; each line in plugin.config cannot exceed
+1023 characters.
+.Pp
+The first plugin configuration is for a plugin named my-plugin.so.
+It contains three arguments that are to be passed to that plugin's
+initialization routine. The second configuration is for a plugin
+named some-plugin.so; it contains three arguments. The last argument,
+$proxy.config.http.cache.on, is actually a configuration variable.
+Traffic Server will look up the specified configuration variable
+and substitute its value.
+.Pp
+Plugins are loaded and initialized by Traffic Server in the order
+they appear in the plugin.config file.
+.Sh PLUGIN INITIALIZATION
+Each plugin must define an initialization function named
+.Fn TSPluginInit
+that Traffic Server invokes when the plugin is loaded.
+.Fn TSPluginInit
+is commonly used to read configuration information and
+register hooks for event notification.
+.Sh FILES
+.Pa <CONFIG_DIR>/plugin.config ,
+.Pa <CONFIG_DIR>/records.config
+.Sh SEE ALSO
+.Xr TSPluginInit 3ts
+.\" vim: set ts=4 sw=4 et :
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/baa602e1/doc/sdk/TSDebug.3
----------------------------------------------------------------------
diff --git a/doc/sdk/TSDebug.3 b/doc/sdk/TSDebug.3
new file mode 100644
index 0000000..ba6d1d8
--- /dev/null
+++ b/doc/sdk/TSDebug.3
@@ -0,0 +1,145 @@
+.\" 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. .\"
+.Dd October 19, 2012
+.Dt TSDebug 3ts TSAPI
+.Sh NAME
+
+.Nm TSDebug,
+.Nm TSError,
+.Nm TSIsDebugTagSet,
+.Nm TSDebugSpecific,
+.Nm TSHttpTxnDebugSet,
+.Nm TSHttpSsnDebugSet,
+.Nm TSHttpTxnDebugGet,
+.Nm TSHttpSsnDebugGet,
+.Nm TSAssert,
+.Nm TSReleaseAssert
+.Nd TrafficServer debugging APIs
+.Sh LIBRARY
+Apache Traffic Server plugin API
+.Sh SYNOPSIS
+.In ts/ts.h
+
+.Ft void
+.Fo TSDebug
+.Fa "const char * tag"
+.Fa "const char * format"
+.Fa ...
+.Fc
+
+.Ft void
+.Fo TSError
+.Fa "const char * tag"
+.Fa "const char * format"
+.Fa ...
+.Fc
+
+.Ft int
+.Fo TSIsDebugTagSet
+.Fa "const char * tag"
+.Fc
+
+.Ft void
+.Fo TSDebugSpecific
+.Fa "int debug_flag"
+.Fa "const char * tag"
+.Fa "const char * format"
+.Fa ...
+.Fc
+
+.Ft void
+.Fo TSHttpTxnDebugSet
+.Fa "TSHttpTxn txnp"
+.Fa "int on"
+.Fc
+
+.Ft void
+.Fo TSHttpSsnDebugSet
+.Fa "TSHttpSsn ssn"
+.Fa "int on"
+.Fc
+
+.Ft int
+.Fo TSHttpTxnDebugGet
+.Fa "TSHttpTxn txnp"
+.Fc
+
+.Ft int
+.Fo TSHttpSsnDebugGet
+.Fa "TSHttpSsn ssn"
+.Fc
+
+.Ft void
+.Fo TSAssert
+.Fa expr
+.Fc
+
+.Ft void
+.Fo TSReleaseAssert
+.Fa expr
+.Fc
+
+.Sh DESCRIPTION
+
+.Fn TSError
+is similar to
+.Fn printf
+except that instead of writing the output to the C standard output,
+it writes output to the Traffic Server error log.
+
+.Pp
+.Fn TSDebug
+is the same as
+.Fn TSError
+except that it only logs the debug message if the given debug tag
+is enabled. It writes output to the Traffic Server debug log.
+
+.Pp
+.Fn TSIsDebugSet
+returns non-zero if the given debug tag is enabled.
+
+.Pp
+In debug mode,
+.Fn TSAssert
+Traffic Server to prints the file name, line number and expression,
+and then aborts. In release mode, the expression is not removed but
+the effects of printing an error message and aborting are.
+.Fn TSReleaseAssert
+prints an error message and aborts in both release and debug mode.
+
+.Pp
+.Fn TSDebugSpecific
+emits a debug line even if the debug tag is turned off, as long as
+debug flag is enabled. This can be used in conjuction with
+.Fn TSHttpTxnDebugSet,
+.Fn TSHttpSsnDebugSet,
+.Fn TSHttpTxnDebugGet,
+and
+.Fn TSHttpSsnDebugGet
+to enable debugging on specific session and transaction objects.
+
+.Sh EXAMPLES
+.nf
+#include <ts/ts.h>
+
+// Emit debug message if "tag" is enabled or the txn debug flag is set.
+TSDebugSpecifc(TSHttpTxnDebugGet(txn), "tag" ,
+ "Hello World from transaction %p", txn);
+
+.fi
+.Sh SEE ALSO
+.Xr tsapi 3ts
+.\" vim: set ts=4 sw=4 et :
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/baa602e1/doc/sdk/TSMalloc.3
----------------------------------------------------------------------
diff --git a/doc/sdk/TSMalloc.3 b/doc/sdk/TSMalloc.3
new file mode 100644
index 0000000..14ec42f
--- /dev/null
+++ b/doc/sdk/TSMalloc.3
@@ -0,0 +1,153 @@
+.\" 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. .\"
+.Dd October 19, 2012
+.Dt TSMalloc 3ts TSAPI
+.Sh NAME
+
+.Nm TSMalloc,
+.Nm TSrealloc,
+.Nm TSstrdup,
+.Nm TSstrndup,
+.Nm TSstrlcpy,
+.Nm TSstrlcat,
+.Nm TSfree
+.Nd TrafficServer memory allocation APIs
+.Sh LIBRARY
+Apache Traffic Server plugin API
+.Sh SYNOPSIS
+.In ts/ts.h
+
+.Ft "void *"
+.Fo TSmalloc
+.Fa "size_t size"
+.Fa "const char * path"
+.Fc
+
+.Ft "void *"
+.Fo TSrealloc
+.Fa "void * ptr"
+.Fa "size_t size"
+.Fa "const char * path"
+.Fc
+
+.Ft "char *"
+.Fo TSstrdup
+.Fa "const char * str"
+.Fa "int64_t length"
+.Fa "const char * path"
+.Fc
+
+.Ft size_t
+.Fo TSstrlcpy
+.Fa "char * dst"
+.Fa "const char * src"
+.Fa "size_t size"
+.Fc
+
+.Ft size_t
+.Fo TSstrlcat
+.Fa "char * dst"
+.Fa "const char * src"
+.Fa "size_t size"
+.Fc
+
+.Ft void
+.Fo TSfree
+.Fa "void * ptr"
+.Fc
+
+.Sh DESCRIPTION
+Traffic Server provides a number of routines for allocating and freeing
+memory. These routines correspond to similar routines in the C
+library. For example,
+.Fn TSrealloc
+behaves like the C library routine
+.Fn realloc
+\. There are two reasons to use 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,
+.Fn 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, is always turned on, and is useful for
+tracking down memory leaks.
+
+.Fn TSMalloc
+returns a pointer to
+.Fa size
+bytes of memory allocated from the heap. Traffic Server uses
+.Fn TSMalloc
+internally for memory allocations.
+Always use
+.Fn TSFree
+to release memory allocated by
+.Fn TSMalloc ; do not
+use
+.Fn free .
+
+.Fn TSstrdup
+returns a pointer to a new string that is a duplicate of the string
+pointed to by
+.Fa str .
+The memory for the new string is allocated using
+.Fn TSMalloc
+and should be freed by a call to
+.Fn TSfree .
+
+.Fn TSstrndup
+returns a pointer to a new string that is a duplicate of the string
+pointed to by
+.Fa str
+and
+.Fa length
+bytes long. The new string will be
+NULL-terminated. This API is very useful for transforming non NULL-terminated string values returned by APIs such as
+.Fn TSMimeHdrFieldStringValueGet
+into NULL-terminated string values. The memory for the new string is allocated using
+.Fn TSmalloc and
+should be freed by a call to
+.Fn TSfree .
+
+.Fn TSstrlcpy
+copies up to
+.Fa size
+- 1 characters from the NULL-terminated string
+.Fa src
+to
+.Fa dst ,
+NULL-terminating the result.
+
+.Fn TSstrlcat
+appends the NULL-terminated string src to the end of dst. It will append at most
+.Fa size
+- strlen(dst) - 1 bytes, NULL-terminating the result.
+
+.Fn TSFree
+releases the memory allocated by
+.Fn Tsmalloc
+or
+.Fn TSrealloc .
+If
+.Fa ptr
+is NULL,
+.Fn TSfree
+does no operation.
+
+.Sh SEE ALSO
+.Xr tsapi 3ts
+.\" vim: set ts=4 sw=4 et :
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/baa602e1/doc/sdk/TSTrafficServerVersionGet.3
----------------------------------------------------------------------
diff --git a/doc/sdk/TSTrafficServerVersionGet.3 b/doc/sdk/TSTrafficServerVersionGet.3
new file mode 100644
index 0000000..ff443b5
--- /dev/null
+++ b/doc/sdk/TSTrafficServerVersionGet.3
@@ -0,0 +1,110 @@
+.\" 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. .\"
+.Dd December 22, 2011
+.Dt TSTrafficServerVersionGet 3ts TSAPI
+.Sh NAME
+.Nm TSTrafficServerVersionGet,
+.Nm TSTrafficServerVersionGetMajor,
+.Nm TSTrafficServerVersionGetMinor,
+.Nm TSTrafficServerVersionGetMajor
+.Nd return TrafficServer version information
+.Sh LIBRARY
+Apache Traffic Server plugin API
+.Sh SYNOPSIS
+.In ts/ts.h
+.Ft "const char *"
+.Fo TSTrafficServerVersionGet
+.Fa void
+.Fc
+.Ft "int"
+.Fo TSTrafficServerVersionGetMajor
+.Fa void
+.Fc
+.Ft "int"
+.Fo TSTrafficServerVersionGetMinor
+.Fa void
+.Fc
+.Ft "int"
+.Fo TSTrafficServerVersionGetPacth
+.Fa void
+.Fc
+.Sh DESCRIPTION
+.Fn TSTrafficServerVersionGet
+returns the string that indicates the release version of Traffic
+Server running the plugin.
+.Sh "RETURN VALUES"
+.Fn TSTrafficServerVersionGet
+returns a pointer to a string of characters that indicates the Traffic
+Server release version. This string must not be modified.
+.Pp
+The other APIs return an integer version number.
+.Sh EXAMPLE
+.nf
+#include <stdio.h>
+#include <ts/ts.h>
+
+int
+check_ts_version()
+{
+
+ const char *ts_version = TSTrafficServerVersionGet();
+ int result = 0;
+
+ if (ts_version) {
+ int major_ts_version = 0;
+ int minor_ts_version = 0;
+ int patch_ts_version = 0;
+
+ if (sscanf(ts_version, "%d.%d.%d", &major_ts_version,
+ &minor_ts_version, &patch_ts_version) != 3) {
+ return 0;
+ }
+
+ /* We need at least Traffic Server 2.0 */
+
+ if (major_ts_version >= 2) {
+ result = 1;
+ }
+
+ }
+
+ return result;
+}
+
+void
+TSPluginInit (int argc, const char *argv[])
+{
+ TSPluginRegistrationInfo info;
+
+ info.plugin_name = "hello-world";
+ info.vendor_name = "MyCompany";
+ info.support_email = "ts-api-support@MyCompany.com";
+
+ if (!TSPluginRegister(TS_SDK_VERSION_2_0 , &info)) {
+ TSError("Plugin registration failed. \n");
+ }
+
+ if (!check_ts_version()) {
+ TSError("Plugin requires Traffic Server 2.0 or later\n");
+ return;
+ }
+
+ TSDebug("debug-hello", "Hello World!\n");
+}
+.fi
+.Sh SEE ALSO
+.Xr tsapi 3ts
+.\" vim: set ts=4 sw=4 et :