--- name: "deregister_tcp_functions" section: "9" platform: "freebsd" package: "base" version: "16.0-CURRENT-20261027-61c70dc16a79" release: "FreeBSD 16.0-CURRENT (2026-10-27)" platforms: ["freebsd"] url: "https://new.carta.tech/deregister_tcp_functions" --- # deregister\_tcp\_functions(9) Alternate TCP Stack Framework ## NAME **tcp\_functions** – Alternate TCP Stack Framework ## SYNOPSIS **#include \** **#include \** *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*); *int*\ **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 The **tcp\_functions** framework allows a kernel developer to implement alternate TCP stacks. The alternate stacks can be compiled in the kernel or can be implemented in loadable kernel modules. This functionality is intended to encourage experimentation with the TCP stack and to allow alternate behaviors to be deployed for different TCP connections on a single system. A system administrator can set a system default stack. By default, all TCP connections will use the system default stack. Additionally, users can specify a particular stack to use on a per-connection basis. (See [tcp(4)](/tcp/4.md) for details on setting the system default stack, or selecting a specific stack for a given connection.) This man page treats "TCP stacks" as synonymous with "function blocks". This is intentional. A "TCP stack" is a collection of functions that implement a set of behavior. Therefore, an alternate "function block" defines an alternate "TCP stack". The **register\_tcp\_functions**(), **register\_tcp\_functions\_as\_name**(), and **register\_tcp\_functions\_as\_names**() functions request that the system 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 has been registered, unless the module first successfully de-registers the function block. The **register\_tcp\_functions**() function requests that the system register the function block with the name defined in the function block's *tfb\_tcp\_block\_name* field. Note that 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 request that the system register the function block using the name defined in the function block's *tfb\_tcp\_block\_name* field by explicitly providing that name. The **register\_tcp\_functions\_as\_name**() function requests that the system register the function block with the name provided in the *name* argument. The **register\_tcp\_functions\_as\_names**() function requests that the system 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 number must not exceed TCP\_FUNCTION\_NAME\_NUM\_MAX. This function will either succeed in registering all of the names in the array, or none of the names in the array. 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 requests that the system 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 will prevent additional sockets from using the specified function block. However, it will not impact sockets that are already using the function block. **tcp\_functions** modules must call one or more of the registration functions during initialization and successfully call the **deregister\_tcp\_functions**() function prior to allowing the module to be unloaded. 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)](/malloc/9.md), 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 function */ void (*tfb_tcp_rexmit_tmr)(struct tcpcb *); /* Mandatory function */ int (*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 should be no longer than TCP\_FUNCTION\_NAME\_LEN\_MAX-1 characters in length. The *tfb\_tcp\_output*, *tfb\_tcp\_do\_segment*, and *tfb\_tcp\_ctloutput* fields are pointers to functions that perform 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. 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 cleanup 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 to which it points 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 is called with arguments of the TCP control block and an integer flag. The flag will be zero if the socket is transitioning to use another TCP stack or one if the TCP control block is being destroyed. 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. 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. 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. A user may select a new TCP stack before calling at any time. Therefore, the function pointer *tfb\_tcp\_handoff\_ok* field must be non-NULL. If a user attempts to select that TCP stack, 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. In this case, the kernel will call the function pointed to by *tfb\_tcp\_fb\_init* if this function pointer is non-NULL and finally perform the stack switch. If the user is not allowed to switch the socket, the function should undo any changes it made to the connection state configuration and return an error code, which will be returned to the user. 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. ### Requirements for Alternate TCP Stacks If the TCP stack needs to store data beyond what is 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. 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. ## 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. ## ERRORS The **register\_tcp\_functions**(), **register\_tcp\_functions\_as\_name**(), and **register\_tcp\_functions\_as\_names**() functions will fail if: - \[EINVAL\] Any of the members of the *blk* argument are set incorrectly. - \[ENOMEM\] The function could not allocate memory for its internal data. - \[EALREADY\] The *blk* is already registered or a function block is already registered with the same name. Additionally, **register\_tcp\_functions\_as\_names**() will fail if: - \[E2BIG\] The number of names pointed to by the *num\_names* argument is larger than TCP\_FUNCTION\_NAME\_NUM\_MAX. The **deregister\_tcp\_functions**() function will fail if: - \[EPERM\] The *blk* argument references the kernel's compiled-in default function block. - \[EBUSY\] The function block is still in use by one or more sockets, or is defined as the current default function block. - \[ENOENT\] The *blk* argument references a function block that is not currently registered. ## SEE ALSO [connect(2)](/connect/2.md), [listen(2)](/listen/2.md), [tcp(4)](/tcp/4.md), [malloc(9)](/malloc/9.md) ## HISTORY This framework first appeared in FreeBSD 11.0. ## AUTHORS The **tcp\_functions** framework was written by Randall Stewart ⟨*rrs@FreeBSD.org*⟩. This manual page was written by Jonathan Looney ⟨*jtl@FreeBSD.org*⟩.