doc: convert TSmalloc(3) to sphinx
Project: http://git-wip-us.apache.org/repos/asf/trafficserver/repo Commit: http://git-wip-us.apache.org/repos/asf/trafficserver/commit/c9767181 Tree: http://git-wip-us.apache.org/repos/asf/trafficserver/tree/c9767181 Diff: http://git-wip-us.apache.org/repos/asf/trafficserver/diff/c9767181 Branch: refs/heads/3.3.x Commit: c97671817cfc0abf06a40318aec87acd8b5b47c1 Parents: 4b14cee Author: James Peach <[email protected]> Authored: Thu Aug 1 10:43:07 2013 -0700 Committer: James Peach <[email protected]> Committed: Thu Aug 1 10:43:07 2013 -0700 ---------------------------------------------------------------------- doc/conf.py | 1 + doc/reference/api/TSmalloc.en.rst | 78 ++++++++++++++++++++++++++++++++++ 2 files changed, 79 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/trafficserver/blob/c9767181/doc/conf.py ---------------------------------------------------------------------- diff --git a/doc/conf.py b/doc/conf.py index 922ee96..75bf8b1 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -220,6 +220,7 @@ man_pages = [ ('reference/api/TSIOBufferCreate.en', 'TSIOBufferCreate', u'Traffic Server IO buffer API', None, u'3ts'), ('reference/api/TSInstallDirGet.en', 'TSInstallDirGet', u'Return Traffic Server installation directories', None, u'3ts'), ('reference/api/TSMBufferCreate.en', 'TSMBufferCreate', u'Traffic Server marshall buffer API', None, u'3ts'), + ('reference/api/TSmalloc.en', 'TSmalloc', u'Traffic Server memory allocation API', None, u'3ts'), ('reference/commands/traffic_cop.en', 'traffic_cop', u'Traffic Server watchdog', None, '8'), ('reference/commands/traffic_line.en', 'traffic_line', u'Traffic Server command line', None, '8'), http://git-wip-us.apache.org/repos/asf/trafficserver/blob/c9767181/doc/reference/api/TSmalloc.en.rst ---------------------------------------------------------------------- diff --git a/doc/reference/api/TSmalloc.en.rst b/doc/reference/api/TSmalloc.en.rst new file mode 100644 index 0000000..a050200 --- /dev/null +++ b/doc/reference/api/TSmalloc.en.rst @@ -0,0 +1,78 @@ +.. 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. + +.. default-domain:: c + +======== +TSmalloc +======== + +Synopsis +======== + +`#include <ts/ts.h>` + +.. function:: void * TSmalloc(size_t size , const char * path) +.. function:: void * TSrealloc(void * ptr , size_t size , const char * path) +.. function:: char * TSstrdup(const char * str) +.. function:: char * TSstrndup(const char * str, size_t size) +.. function:: size_t TSstrlcpy(char * dst , const char * src , size_t size) +.. function:: size_t TSstrlcat(char * dst , const char * src , size_t size) +.. function:: void TSfree(void * ptr) + +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, :func:`TSrealloc` behaves like the C library routine :func:`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 Servers supported platforms. For example, :func:`realloc` does +not accept an argument of :data:`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. + +:func:`TSmalloc` returns a pointer to size bytes of memory allocated from the +heap. Traffic Server uses :func:`TSmalloc` internally for memory allocations. +Always use :func:`TSfree` to release memory allocated by :func:`TSmalloc`; do not use +:func:`free`. + +:func:`TSstrdup` returns a pointer to a new string that is a duplicate +of the string pointed to by str. The memory for the new string is +allocated using :func:`TSmalloc` and should be freed by a call to +:func:`TSfree`. :func:`TSstrndup` returns a pointer to a new string that +is a duplicate of the string pointed to by str and size bytes +long. The new string will be NUL-terminated. This API is very +useful for transforming non NUL-terminated string values returned +by APIs such as :func:`TSMimeHdrFieldStringValueGet` into NLL-terminated +string values. The memory for the new string is allocated using +:func:`TSmalloc` and should be freed by a call to :func:`TSfree`. + +:func:`TSstrlcpy` copies up to size - 1 characters from the NUL-terminated +string src to dst, NUL-terminating the result. + +:func:`TSstrlcat` appends the NUL-terminated string src to the end of dst. It +will append at most size - strlen(dst) - 1 bytes, NUL-terminating the +result. + +:func:`TSfree` releases the memory allocated by :func:`TSmalloc` or :func:`TSrealloc`. If +ptr is :data:`NULL`, :func:`TSfree` does no operation. + +See also +======== +:manpage:`TSAPI(3ts)`
