git commit: TSMBufferCreate man page

[jp...@apache.org]

Updated Branches:
  refs/heads/master 1e83ffd8e -> 79da694bb


TSMBufferCreate man page


Project: http://git-wip-us.apache.org/repos/asf/trafficserver/repo
Commit: http://git-wip-us.apache.org/repos/asf/trafficserver/commit/79da694b
Tree: http://git-wip-us.apache.org/repos/asf/trafficserver/tree/79da694b
Diff: http://git-wip-us.apache.org/repos/asf/trafficserver/diff/79da694b

Branch: refs/heads/master
Commit: 79da694bb54c719c06acd2201449bcf94c4f90c7
Parents: 1e83ffd
Author: James Peach <jp...@apache.org>
Authored: Thu Oct 25 17:42:28 2012 -0700
Committer: James Peach <jp...@apache.org>
Committed: Thu Oct 25 17:42:28 2012 -0700

----------------------------------------------------------------------
 doc/Makefile.am           |    1 +
 doc/sdk/TSMBufferCreate.3 |  110 ++++++++++++++++++++++++++++++++++++++++
 2 files changed, 111 insertions(+), 0 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/trafficserver/blob/79da694b/doc/Makefile.am
----------------------------------------------------------------------
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 4092bf8..c4d945c 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -82,6 +82,7 @@ man1_MANS = \
 man3_MANS = \
   sdk/TSAPI.3 \
   sdk/TSDebug.3 \
+  sdk/TSMBufferCreate.3 \
   sdk/TSMalloc.3 \
   sdk/TSPluginInit.3 \
   sdk/TSTrafficServerVersionGet.3

http://git-wip-us.apache.org/repos/asf/trafficserver/blob/79da694b/doc/sdk/TSMBufferCreate.3
----------------------------------------------------------------------
diff --git a/doc/sdk/TSMBufferCreate.3 b/doc/sdk/TSMBufferCreate.3
new file mode 100644
index 0000000..0d2a0c7
--- /dev/null
+++ b/doc/sdk/TSMBufferCreate.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 .\"
+.Dd October 25, 2012
+.Dt TSMBufferCreate 3ts TSAPI
+.Sh NAME
+.Nm TSMBufferCreate,
+.Nm TSMBufferDestroy,
+.Nm TSHandleMLocRelease
+.Nd Traffic Server marshall buffers
+.Sh LIBRARY
+Apache Traffic Server plugin API
+.Sh SYNOPSIS
+.In ts/ts.h
+.Ft "TSMBuffer"
+.Fo TSMBufferCreate
+.Fa "void"
+.Fc
+.Ft "TSReturnCode"
+.Fo TSMBufferDestroy
+.Fa "TSMBuffer bufp"
+.Fc
+.Ft "TSReturnCode"
+.Fo TSHandleMLocRelease
+.Fa "TSMBuffer bufp"
+.Fa "TSMLoc parent"
+.Fa "TSMLoc mloc"
+.Fc
+.Sh DESCRIPTION
+The marshal buffer or TSMBuffer is a heap data structure that
+stores parsed URLs, MIME headers and HTTP headers. You can allocate
+new objects out of marshal buffers, and change the values within
+the marshal buffer. Whenever you manipulate an object, you require
+the handle to the object (TSMLoc) and the marshal buffer containing
+the object (TSMBuffer).
+.Pp
+Any marshal buffer fetched by
+.Fn TSHttpTxn*Get
+will be used by other parts of the system. Be careful not to destroy these shared, transaction marshal buffers.
+
+.Fn TSMBufferCreate
+creates a new marshal buffer and initializes the reference count.
+.Fn TSMBufferDestroy
+Ignores the reference count and destroys the marshal buffer
+.Fa bufp .
+The internal data buffer associated with the marshal buffer is also
+destroyed if the marshal buffer allocated it.
+
+.Fn TSHandleMLocRelease
+Releases the TSMLoc
+.Fa mloc
+created from the TSMLoc
+.Fa parent .
+If a TSMLoc is obtained from a transaction, it does not have a parent
+TSMLoc. Use the the constant
+.Fa TS_NULL_MLOC
+as its parent.
+
+.Sh RETURN VALUES
+.Fn TSMBufferDestroy
+and 
+.Fn TSHandleMLocRelease 
+return
+.Fa TS_SUCCESS
+on success, or
+.Fa TS_ERROR
+on failure.
+.Fn TSMBufferCreate
+returns the new TSMBuffer.
+
+.Sh EXAMPLES
+.nf
+#include <ts/ts.h>
+
+static void
+copyResponseMimeHdr (TSCont pCont, TSHttpTxn pTxn)
+{
+  TSMBuffer respHdrBuf, tmpBuf;
+  TSMLoc respHttpHdrLoc, tmpMimeHdrLoc;
+
+  if (!TSHttpTxnClientRespGet(pTxn, &respHdrBuf, &respHttpHdrLoc)) {
+    TSError("couldn't retrieve client response header\n");
+    TSHandleMLocRelease(respHdrBuf, TS_NULL_MLOC, respHttpHdrLoc);
+    goto done;
+  }
+
+  tmpBuf = TSMBufferCreate();
+  tmpMimeHdrLoc = TSMimeHdrCreate(tmpBuf);
+  TSMimeHdrCopy(tmpBuf, tmpMimeHdrLoc, respHdrBuf, respHttpHdrLoc);
+  TSHandleMLocRelease(tmpBuf, TS_NULL_MLOC, tmpMimeHdrLoc);
+  TSHandleMLocRelease(respHdrBuf, TS_NULL_MLOC, respHttpHdrLoc);
+  TSMBufferDestroy(tmpBuf);
+
+done:
+  TSHttpTxnReenable(pTxn, TS_EVENT_HTTP_CONTINUE);
+}
+.fi
+.Sh SEE ALSO
+.Xr TSAPI 3ts