---
name: "TSVConnArgs"
section: "3ts"
platform: "linux"
package: "trafficserver-dev"
version: "9.2.5+ds-0+deb12u4"
release: "Debian 12 (Bookworm)"
platforms: ["linux"]
url: "https://new.carta.tech/TSVConnArgs"
---

# TSVConnArgs(3ts)

TSVConnArgs API function

## NAME

TSVConnArgs - TSVConnArgs API function

## SYNOPSIS

**NOTE:**

This set of API is obsoleted as of ATS v9.0.0, and will be removed with ATS v10.0.0! For details of the new APIs, see *TSUserArgs*.

```
#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

Virtual connection objects (API type *TSVConn*) support an array of **void \*** values that are controlled entirely by plugins. These are not used in any way by the core. This allows plugins to store data associated with a specific virtual connection for later retrieval by the same plugin in a different hook or by another plugin. Because the core does not interact with these values any cleanup is the responsibility of the plugin.

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 the reservation is by convention - nothing stops a plugin from interacting with a **TSVConn** arg it has not reserved.

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.

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. *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*. The values can be retrieved with *TSVConnArgGet()* which returns the specified value. Values that have not been set are **nullptr**.

## 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.

## COPYRIGHT

2026, dev@trafficserver.apache.org