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 <[email protected]> Authored: Fri Oct 19 21:52:35 2012 -0700 Committer: James Peach <[email protected]> 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 = "[email protected]"; + + 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 :
