TSVCONNFDCREATE(3ts)

✨ TSVCONNFDCREATE ✨

okay bestie, welcome to the TSVConnFdCreate page, straight out of the Apache Traffic Server manual (that's the 3ts section, iykyk). this one's short, sweet, and honestly kinda iconic — it's the glow-up that turns a plain old socket into a whole TSVConn. 💅

---

🌸 NAME 🌸

TSVConnFdCreate — create a TSVConn from a socket

no cap, that's the whole job. it takes a socket and gives it main character energy. ✨

---

🎀 SYNOPSIS 🎀

#include <ts/ts.h>

TSVConn TSVConnFdCreate(int fd)

she takes one little int fd and returns you a TSVConn. that's it. that's the whole vibe. 🦋

---

💖 DESCRIPTION 💖

so like, TSVConnFdCreate() takes a network socket fd and hands you back a brand new TSVConn built out of that socket. fr fr.

heads up bestie: that socket descriptor has to be an already connected socket. like, it needs to have already done its whole connect arc. no half-finished situationships here. 🚫

once it's yours-as-a-TSVConn, it gets placed into non-blocking mode. so she's asynchronous now. she's free. she's not gonna sit there holding up the whole event loop. 🧚

---

👑 RETURN VALUES 👑

two timelines, bestie:

• success — the returned TSVConn object owns the socket, and the caller must not close it. it's not yours anymore, it's hers. hands off. 🙈
• failure — NULL comes back, the socket is unchanged, and the caller must close it. so like, if she says no, you still gotta take care of it yourself. 😭

---

🔥 EXAMPLES 🔥

this one's an excerpt from example/plugins/c-api/intercept/intercept.cc in the Traffic Server source distribution. it's showing off how you'd use TSVConnFdCreate() to construct a TSVConn from a connected socket. very demure, very mindful. ✨

       // the TSHttpTxn pointer.
       VDEBUG("allocated server intercept state istate=%p for txn=%p", istate, cdata.txn);

       // Set up a connection to our real origin, which will be
       // 127.0.0.1:$PORT.
       memset(&addr, 0, sizeof(addr));
       addr.sin.sin_family      = AF_INET;
       addr.sin.sin_addr.s_addr = htonl(INADDR_LOOPBACK); // XXX config option
       addr.sin.sin_port        = htons(PORT);            // XXX config option

       // Normally, we would use TSNetConnect to connect to a secondary service, but to demonstrate
       // the use of TSVConnFdCreate, we do a blocking connect inline. This it not recommended for
       // production plugins, since it might block an event thread for an arbitrary time.
       fd = ::socket(PF_INET, SOCK_STREAM, IPPROTO_TCP);
       TSReleaseAssert(fd != -1);

       if (::connect(fd, &addr.sa, sizeof(addr.sin)) == -1) {
         // We failed to connect to the intercepted origin. Abort the
         // server intercept since we cannot handle it.
         VDEBUG("connect failed with %s (%d)", strerror(errno), errno);
         TSVConnAbort(arg.vc, TS_VC_CLOSE_ABORT);

         delete istate;
         TSContDestroy(contp);

         ::close(fd);
         return TS_EVENT_NONE;
       }

       if ((istate->server.vc = TSVConnFdCreate(fd)) == nullptr) {
         VDEBUG("TSVconnFdCreate() failed");
         TSVConnAbort(arg.vc, TS_VC_CLOSE_ABORT);

         delete istate;
         TSContDestroy(contp);

         ::close(fd);
         return TS_EVENT_NONE;
       }

       VDEBUG("binding client vc=%p to %s:%u", istate->client.vc, inet_ntop(AF_INET, &addr.sin.sin_addr, buf, sizeof(buf)),
              (unsigned)ntohs(addr.sin.sin_port));

       istate->txn       = cdata.txn;
       istate->client.vc = arg.vc;

       // Reset the continuation data to be our intercept state
       // block. We will need this so that we can access both of the
       // VCs at the same time. We need to do this before calling

lowkey important: see that comment about the blocking connect inline? that's not recommended for production plugins, because it might block an event thread for an arbitrary amount of time. cute for a demo, cursed in prod. 💀

---

🌈 SEE ALSO 🌈

• TSAPI(3ts)

go read that one too, bestie, it's the whole friend group. 🫶

---

💜 COPYRIGHT 💜

2026, dev@trafficserver.apache.org

---

and that's the page!! slay 💖 this was TSVCONNFDCREATE(3ts) from the Apache Traffic Server manual, version 9.2, dated Feb 12, 2026. go forth and construct your TSVConns responsibly, mwah 🎀✨