TSHTTPARGS(3ts)

✨ NAME ✨

TSHttpArgs — the TSHttpArgs API function 💅

---

🌸 SYNOPSIS 🌸

🚨 bestie, sit DOWN for this one: this entire API set is obsoleted as of ATS v9.0.0, and it's getting removed with ATS v10.0.0! For the details of the new APIs, go see TSUserArgs. 🚨

#include <ts/ts.h>

TSReturnCode TSHttpTxnArgIndexReserve(const char *name, const char *description, int *arg_idx)

TSReturnCode TSHttpTxnArgIndexNameLookup(const char *name, int *arg__idx, const char **description)

TSReturnCode TSHttpTxnArgIndexLookup(int arg_idx, const char **name, const char **description)

TSReturnCode TSHttpSsnArgIndexReserve(const char *name, const char *description, int *arg_idx)

TSReturnCode TSHttpSsnArgIndexNameLookup(const char *name, int *arg__idx, const char **description)

TSReturnCode TSHttpSsnArgIndexLookup(int arg_idx, const char **name, const char **description)

void TSHttpTxnArgSet(TSHttpTxn txnp, int arg_idx, void *arg)

void *TSHttpTxnArgGet(TSHttpTxn txnp, int arg_idx)

void TSHttpSsnArgSet(TSHttpSsn ssnp, int arg_idx, void *arg)

void *TSHttpSsnArgGet(TSHttpSsn ssnp, int arg_idx)

---

💖 DESCRIPTION 💖

okay so Traffic Server sessions and transactions hand you a fixed array of void pointers that plugins can use to stash information. ✨ Why is this iconic? Because it saves you from creating a whole per-session or per-transaction continuation just to hold some data — and because those array values are visible to any plugin that can reach the session or transaction, so plugins can literally gossip with each other through it. 🫶

The array values are opaque to Traffic Server — it will not dereference them, and it will not release them. Nope, not its problem. 💀 That means plugins are responsible for cleaning up any resources pointed to by the values. But if your values are simply values, then there's no need for the plugin to remove them after the session or transaction has completed. Easy. 😌

🎀 reserving your index (avoid the collisions, bestie) 🎀

To avoid collisions between plugins, a plugin should first reserve an index in the array. A transaction-based plugin argument gets reserved by calling TSHttpTxnArgIndexReserve(). A session-based plugin argument gets reserved by calling TSHttpSsnArgIndexReserve(). Both functions take these arguments:

• name — an identifying name for the plugin that reserved the index. Required.
• description — an optional description of the use of the arg. This can be nullptr.
• arg_idx — a pointer to an int. If an index is successfully reserved, the int pointed at by this is set to the reserved index. It is not modified if the call is unsuccessful.

These functions return TS_SUCCESS if an index was reserved, and TS_ERROR if not (most likely because all of the indices have already been reserved 😭). Generally this will be a file or library scope global which is set at plugin initialization. This function is used in the example remap plugin example/plugins/c-api/remap/remap.cc. The index is stored in the plugin global arg_index. And heads up — transaction and session plugin argument indices are reserved independently. 👑

🦋 looking up who owns what 🦋

To look up the owner of a reserved index, use TSHttpTxnArgIndexNameLookup() or TSHttpSsnArgIndexNameLookup() for transaction and session plugin arguments respectively. If name is found as an owner, the function returns TS_SUCCESS and arg_index is updated with the index reserved under that name. If description is not NULL, then the character pointer to which it points will be updated to point at the description for that reserved index. This is what enables communication between plugins where plugin "A" reserves an index under a well known name and plugin "B" locates the index by looking it up under that name. 🤝

The owner of a reserved index can be found with TSHttpTxnArgIndexLookup() or TSHttpSsnArgIndexLookup() for transaction and session plugin arguments respectively. If arg_index is reserved, then the function returns TS_SUCCESS and the pointers referred to by name and description are updated. name must point at a valid character pointer, but description can be NULL, in which case it is ignored. 🫡

🌈 manipulating the array 🌈

Manipulating the array is simple, fr fr. TSHttpTxnArgSet() sets the array slot at arg_idx for the transaction txnp to the value arg. Note this sets the value only for the specific transaction. Similarly, TSHttpSsnArgSet() sets the value for a session argument. The values can be retrieved with TSHttpTxnArgGet() for transactions and TSHttpSsnArgGet() for sessions, which return the specified value. Values that have not been set are NULL. 💅

📌 NOTE: Session arguments persist for the entire session — which means potentially across all transactions in that session. 👀

📌 NOTE: Following arg index reservations is conventional. It is not enforced. Do with that information what you will. 🙈

---

💜 COPYRIGHT 💜

2026, dev@trafficserver.apache.org

---

okay that's the whole page, bestie, you ate that 🍓 this was TSHTTPARGS(3ts) from the Apache Traffic Server manual, 9.2, dated Feb 12, 2026 — mwah, go reserve your indices responsibly 💖✨