TSVCONNARGS(3ts)

💖 TSVCONNARGS(3ts) — the TSVConnArgs API function 💖

okay bestie, welcome to the TSVConnArgs manual page, from the Apache Traffic Server section 3ts manual. this is the whole vibe, let's get into it 🫶

---

✨ NAME ✨

TSVConnArgs — the TSVConnArgs API function, periodt 💅

---

🎀 SYNOPSIS 🎀

⚠️ NOTE: this whole set of API is obsoleted as of ATS v9.0.0, and it will be removed with ATS v10.0.0! for the details of the new APIs, see TSUserArgs. so like... it's giving legacy, no cap 😭

#include <ts/ts.h>

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

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

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

void TSVConnArgSet(TSVConn vc, int arg_idx, void *arg)

void *TSVConnArgGet(TSVConn vc, int arg_idx)

---

🌸 DESCRIPTION 🌸

so virtual connection objects (API type TSVConn) support an array of void * values, and those values are controlled entirely by plugins. the core literally does not use them in any way. this is the whole point, and it's iconic: it lets plugins store data associated with a specific virtual connection, so the same plugin can grab it back later in a different hook — or another plugin can pick it up. 🦋 and because the core doesn't interact with these values at all, all cleanup is the responsibility of the plugin. yes, that means you. your mess, your problem, bestie 🙈

to avoid collisions between plugins, a plugin should first reserve an index in the array by calling TSVConnArgIndexReserve(), passing it an identifying name, a description, and a pointer to an integer which will get the reserved index. the function returns TS_SUCCESS if an index was reserved, 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. note that the reservation is by convention — nothing stops a plugin from interacting with a TSVConn arg it has not reserved. so like, be normal about it please 🫶

to look up the owner of a reserved index, use TSVConnArgIndexNameLookup(). if the 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 nullptr then it will be updated with the description for that reserved index. this 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. collab energy, love that for them 💖

the owner of a reserved index can be found with TSVConnArgIndexLookup(). if arg_index is reserved then the function returns TS_SUCCESS and name and description are updated. name must point at a valid character pointer, but description can be nullptr. ✨

manipulating the array is simple, honestly. TSVConnArgSet() sets the array slot at arg_idx for the vc to the value arg. note this sets the value only for the specific TSVConn — not a global, don't get it twisted 💅. the values can be retrieved with TSVConnArgGet(), which returns the specified value. values that have not been set are nullptr. easy!

---

🔥 HOOKS 🔥

although these can be used from any hook that has access to a TSVConn, it will generally be the case that TSVConnArgSet() will be used in early intervention hooks and TSVConnArgGet() in session / transaction hooks. cleanup should be done on the TS_VCONN_CLOSE_HOOK. 👑

💜 Appendix 💜

NOTE: this is originally from Issue 2388. it has been extended based on discussions with Kees and Leif Hedstrom at the ATS summit. history! we love a glow-up 🌈

---

⭐ COPYRIGHT ⭐

2026, dev@trafficserver.apache.org

---

and that's the whole page bestie, you ate that 🍓 ok so the little footer at the bottom of the real page says this is from Apache Traffic Server, version 9.2, dated Feb 12, 2026 — so go forth, reserve your indices, and remember: cleanup is on you. mwah 💖🧚‍♀️