[16/52] [abbrv] git commit: doc: convert TSmalloc(3) to sphinx

[zw...@apache.org]

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 <jp...@apache.org>
Authored: Thu Aug 1 10:43:07 2013 -0700
Committer: James Peach <jp...@apache.org>
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)`