TCP_FUNCTIONS(9)

okay so bestie, welcome to TCP_FUNCTIONS(9) from the Kernel Developer's Manual — aka the Alternate TCP Stack Framework, and it is a lot, but I gotchu 🫶

✨ NAME ✨

tcp_functions — Alternate TCP Stack Framework 💅

---

✨ SYNOPSIS ✨

#include <netinet/tcp.h>
#include <netinet/tcp_var.h>

int
register_tcp_functions(struct tcp_function_block *blk, int wait);

int
register_tcp_functions_as_name(struct tcp_function_block *blk,
    const char *name, int wait);

register_tcp_functions_as_names(struct tcp_function_block *blk,
    int wait, const char *names[], int *num_names);

int
deregister_tcp_functions(struct tcp_function_block *blk);

---

✨ DESCRIPTION ✨

okay so here's the vibe: the tcp_functions framework lets a kernel developer build alternate TCP stacks. Those alternate stacks can be baked straight into the kernel, or they can live in loadable kernel modules. The whole point is to encourage experimentation with the TCP stack and to let different behaviors get deployed for different TCP connections on one single system. It's giving "everybody gets their own TCP stack" and honestly? iconic 🌈

A system administrator can set a system default stack. By default, every TCP connection uses that system default stack. On top of that, users can pick a specific stack on a per-connection basis. (Go check tcp(4) for the deets on setting the system default stack, or on selecting a specific stack for a given connection.) 🎀

This man page treats "TCP stacks" as synonymous with "function blocks", and that is intentional, bestie. A "TCP stack" is a collection of functions that implement a set of behavior. Therefore, an alternate "function block" defines an alternate "TCP stack". No cap. 💖

The register_tcp_functions(), register_tcp_functions_as_name(), and register_tcp_functions_as_names() functions ask the system to add a specified function block and register it for use with a given name. Modules may register the same function block multiple times with different names. However — names must be globally unique among all registered function blocks. Also, modules may not ever modify the contents of the function block (including the name) after it's been registered, unless the module first successfully de-registers the function block. So like… hands off once it's out there 🙈

The register_tcp_functions() function asks the system to register the function block with the name defined in the function block's tfb_tcp_block_name field. Heads up: this is the only one of the three registration functions that automatically registers the function block using the name defined in the function block's tfb_tcp_block_name field. If a module uses one of the other registration functions, it may ask the system to register the function block using the name defined in the function block's tfb_tcp_block_name field by explicitly providing that name. iykyk 💅

The register_tcp_functions_as_name() function asks the system to register the function block with the name provided in the name argument.

The register_tcp_functions_as_names() function asks the system to register the function block with all the names provided in the names argument. The num_names argument provides a pointer to the number of names. This function will either succeed in registering all of the names in the array, or none of the names in the array. All or nothing, periodt. On failure, the num_names argument is updated with the index number of the entry in the names array which the system was processing when it encountered the error. 🔥

The deregister_tcp_functions() function asks the system to remove a specified function block from the system. If this call succeeds, it will completely deregister the function block, regardless of the number of names used to register the function block. If the call fails because sockets are still using the specified function block, the system will mark the function block as being in the process of being removed. This prevents additional sockets from using the specified function block. However, it will not impact sockets that are already using the function block — they're grandfathered in, main character energy 👑

tcp_functions modules must call one or more of the registration functions during initialization, and must successfully call the deregister_tcp_functions() function prior to allowing the module to be unloaded. No sneaky unloads, bestie 😭

The blk argument is a pointer to a struct tcp_function_block, which is explained below (see "Function Block Structure"). The wait argument is used as the flags argument to malloc(9), and must be set to one of the valid values defined in that man page.

🎀 Function Block Structure 🎀

The blk argument is a pointer to a struct tcp_function_block, which has the following members:

struct tcp_function_block {
        char    tfb_tcp_block_name[TCP_FUNCTION_NAME_LEN_MAX];
        int     (*tfb_tcp_output)(struct tcpcb *);
        void    (*tfb_tcp_do_segment)(struct mbuf *, struct tcphdr *,
                            struct socket *, struct tcpcb *,
                            int, int, uint8_t,
                            int);
        int     (*tfb_tcp_ctloutput)(struct socket *so,
                            struct sockopt *sopt,
                            struct inpcb *inp, struct tcpcb *tp);
        /* Optional memory allocation/free routine */
        void    (*tfb_tcp_fb_init)(struct tcpcb *);
        void    (*tfb_tcp_fb_fini)(struct tcpcb *, int);
        /* Optional timers, must define all if you define one */
        int     (*tfb_tcp_timer_stop_all)(struct tcpcb *);
        void    (*tfb_tcp_timer_activate)(struct tcpcb *,
                            uint32_t, u_int);
        int     (*tfb_tcp_timer_active)(struct tcpcb *, uint32_t);
        void    (*tfb_tcp_timer_stop)(struct tcpcb *, uint32_t);
        /* Optional functions */
        void    (*tfb_tcp_rexmit_tmr)(struct tcpcb *);
        void    (*tfb_tcp_handoff_ok)(struct tcpcb *);
        /* System use */
        volatile uint32_t tfb_refcnt;
        uint32_t  tfb_flags;
};

The tfb_tcp_block_name field identifies the unique name of the TCP stack, and it should be no longer than TCP_FUNCTION_NAME_LEN_MAX-1 characters in length. Keep it cute, keep it short 💖

The tfb_tcp_output, tfb_tcp_do_segment, and tfb_tcp_ctloutput fields are pointers to functions that do the equivalent actions as the default tcp_output(), tcp_do_segment(), and tcp_default_ctloutput() functions, respectively. Each of these function pointers must be non-NULL. Non-negotiable, fr fr.

If a TCP stack needs to initialize data when a socket first selects the TCP stack (or, when the socket is first opened), it should set a non-NULL pointer in the tfb_tcp_fb_init field. Likewise, if a TCP stack needs to clean up data when a socket stops using the TCP stack (or, when the socket is closed), it should set a non-NULL pointer in the tfb_tcp_fb_fini field. 🧹✨

If the tfb_tcp_fb_fini argument is non-NULL, the function it points to is called when the kernel is destroying the TCP control block, or when the socket is transitioning to use a different TCP stack. The function gets called with arguments of the TCP control block and an integer flag. That flag will be zero if the socket is transitioning to use another TCP stack, or one if the TCP control block is being destroyed. Two moods, one flag 🌸

If the TCP stack implements additional timers, the TCP stack should set a non-NULL pointer in the tfb_tcp_timer_stop_all, tfb_tcp_timer_activate, tfb_tcp_timer_active, and tfb_tcp_timer_stop fields. These fields should all be NULL or should all contain pointers to functions. No halfsies. The tfb_tcp_timer_activate, tfb_tcp_timer_active, and tfb_tcp_timer_stop functions will be called when the tcp_timer_activate(), tcp_timer_active(), and tcp_timer_stop() functions, respectively, are called with a timer type other than the standard types. The functions defined by the TCP stack have the same semantics (both for arguments and return values) as the normal timer functions they supplement. Matching energy only ⏰

Additionally, a stack may define its own actions to take when the retransmit timer fires by setting a non-NULL function pointer in the tfb_tcp_rexmit_tmr field. This function is called very early in the process of handling a retransmit timer. However, care must be taken to ensure the retransmit timer leaves the TCP control block in a valid state for the remainder of the retransmit timer logic. Don't leave it messy, bestie 😭

A user may select a new TCP stack before calling connect(2) or listen(2). Optionally, a TCP stack may also allow a user to begin using the TCP stack for a connection that is in a later state by setting a non-NULL function pointer in the tfb_tcp_handoff_ok field. If this field is non-NULL and a user attempts to select that TCP stack after calling connect(2) or listen(2) for that socket, the kernel will call the function pointed to by the tfb_tcp_handoff_ok field. The function should return 0 if the user is allowed to switch the socket to use the TCP stack. Otherwise, the function should return an error code, which will be returned to the user. If the tfb_tcp_handoff_ok field is NULL and a user attempts to select the TCP stack after calling connect(2) or listen(2) for that socket, the operation will fail and the kernel will return EINVAL. 💀

The tfb_refcnt and tfb_flags fields are used by the kernel's TCP code and will be initialized when the TCP stack is registered. System use only, don't touch 🫶

🌸 Requirements for Alternate TCP Stacks 🌸

If the TCP stack needs to store data beyond what's stored in the default TCP control block, the TCP stack can initialize its own per-connection storage. The t_fb_ptr field in the struct tcpcb control block structure has been reserved to hold a pointer to this per-connection storage. If the TCP stack uses this alternate storage, it should understand that the value of the t_fb_ptr pointer may not be initialized to NULL. Therefore, it should use a tfb_tcp_fb_init function to initialize this field. Additionally, it should use a tfb_tcp_fb_fini function to deallocate storage when the socket is closed. Clean up after yourself, queen 💅

It is understood that alternate TCP stacks may keep different sets of data. However, in order to ensure that data is available to both the user and the rest of the system in a standardized format, alternate TCP stacks must update all fields in the TCP control block to the greatest extent practical. Everybody has to be able to read the room 📖

---

✨ RETURN VALUES ✨

The register_tcp_functions(), register_tcp_functions_as_name(), register_tcp_functions_as_names(), and deregister_tcp_functions() functions return zero on success and non-zero on failure. ✨

In particular, the deregister_tcp_functions() will return EBUSY until no more connections are using the specified TCP stack. A module calling deregister_tcp_functions() must be prepared to wait until all connections have stopped using the specified TCP stack. Like, actually wait. Not pretend-wait. ⏳

💥 ERRORS 💥

okay so bestie, here's where it gets real — these are the ways things go sideways. 🫠

The register_tcp_functions() function will fail if:

• [EINVAL] — literally any of the members of the blk argument are set incorrectly. like, any of them. it's giving "you had one job". 🙈
• [ENOMEM] — the function could not allocate memory for its internal data. she tried her best, the RAM said no. 😭
• [EALREADY] — a function block is already registered with the same name. bestie, that name is taken. pick a different one. 💅

The deregister_tcp_functions() function will fail if:

• [EPERM] — the blk argument references the kernel's compiled-in default function block. no you cannot delete the main character, she's built in. 👑
• [EBUSY] — the function block is still in use by one or more sockets, or is defined as the current default function block. she's booked and busy, come back later. 🚫
• [ENOENT] — the blk argument references a function block that is not currently registered. ghosted. doesn't exist. never did. 💀

---

👀 SEE ALSO 👀

go read these, they're the extended universe fr fr:

• connect(2)
• listen(2)
• tcp(4)
• malloc(9)

---

📜 HISTORY 📜

This framework first appeared in FreeBSD 11.0. a classic, honestly. iconic behavior from the start. 🌈

---

🫶 AUTHORS 🫶

The tcp_functions framework was written by Randall Stewart <rrs@FreeBSD.org>. absolute legend, no cap. 🔥

This manual page was written by Jonathan Looney <jtl@FreeBSD.org>. thank you for your service, king. 💖

---

and that's the whole page bestie!! ✨ this one came from the Debian crew, dated March 10, 2017 — so like, it's been serving accurate documentation energy for years and honestly? she ate. go forth and register your function blocks responsibly. mwah. 💅🎀🦋