.\" .\" Copyright (C) 2001 Chad David . All rights reserved. .\" Copyright (C) 2022 Gleb Smirnoff .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice(s), this list of conditions and the following disclaimer as .\" the first lines of this file unmodified other than the possible .\" addition of one or more copyright notices. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice(s), this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY .\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE .\" DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE LIABLE FOR ANY .\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES .\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR .\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER .\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH .\" DAMAGE. .\" .\" $FreeBSD$ .\" .Dd September 14, 2022 .Dt DOMAIN 9 .Os .Sh NAME .Nm domain , .Nm protosw .Nd "programming interface for kernel socket implementation" .Sh SYNOPSIS .In sys/param.h .In sys/kernel.h .In sys/protosw.h .In sys/domain.h .Ft void .Fn domain_add "struct domain *dom" .Ft void .Fn domain_remove "struct domain *dom" .Ft void .Fn DOMAIN_SET "domain" .Ft int .Fn protosw_register "struct domain *dom" "struct protosw *pr" .Ft int .Fn protosw_unregister "struct protosw *pr" .Sh DESCRIPTION The .Nm subsystem allows implementation of communication protocols that are exposed to the userland via the .Xr socket 2 API. When an application performs a .Fn socket "domain" "type" "protocol" syscall, the kernel searches for a .Nm matching the .Ar domain argument, then within this domain, searches for a protocol matching .Ar type . If the third argument, .Ar protocol , is not .Dv 0 , that value must also match. The structure found must implement certain methods, so that .Xr socket 2 API works for this particular kind of a socket. .Pp A minimal .Nm structure implementing a domain shall be initialized with sparse C99 initializer and has public fields as follows: .Bd -literal struct domain { /* * Mandatory fields. */ int dom_family; /* PF_xxx, first argument of socket(2) */ char *dom_name; /* text name of the domain */ u_int dom_nprotosw; /* length of dom_protosw[] */ /* * Following methods are optional. */ int (*dom_probe)(void); /* check for support */ struct rib_head *(*dom_rtattach)(uint32_t); /* init route table */ void (*dom_rtdetach)(struct rib_head *); /* clean up table */ void *(*dom_ifattach)(struct ifnet *); /* interface attach */ void (*dom_ifdetach)(struct ifnet *, void *);/* & detach callbacks */ int (*dom_ifmtu)(struct ifnet *); /* mtu change */ /* * Mandatory variable size array of pointers to protosw structs. */ struct protosw *dom_protosw[]; }; .Ed .Pp Each domain contains the .Va dom_protosw array of protocol switch structures .Pq Vt "struct protosw *" , one for each socket type supported. The array may have .Dv NULL spacers for loadable protocols. Sparse C99 initializers shall be used to initialize .Nm protosw structures. The structure has mandatory field .Va pr_type and mandatory .Va pr_attach method. The rest of the methods are optional, but a meaningful protocol should implement some. .Bd -literal struct protosw { short pr_type; /* second argument of socket(2) */ short pr_protocol; /* third argument of socket(2) or 0 */ short pr_flags; /* see protosw.h */ pr_soreceive_t *pr_soreceive; /* recv(2) */ pr_rcvd_t *pr_rcvd; /* soreceive_generic() if PR_WANTRCV */ pr_sosend_t *pr_sosend; /* send(2) */ pr_send_t *pr_send; /* send(2) via sosend_generic() */ pr_ready_t *pr_ready; /* sendfile/ktls readyness */ pr_sopoll_t *pr_sopoll; /* poll(2) */ pr_attach_t *pr_attach; /* creation: socreate(), sonewconn() */ pr_detach_t *pr_detach; /* destruction: sofree() */ pr_connect_t *pr_connect; /* connect(2) */ pr_disconnect_t *pr_disconnect; /* sodisconnect() */ pr_close_t *pr_close; /* close(2) */ pr_shutdown_t *pr_shutdown; /* shutdown(2) */ pr_abort_t *pr_abort; /* abrupt tear down: soabort() */ pr_aio_queue_t *pr_aio_queue; /* aio(9) */ pr_bind_t *pr_bind; /* bind(2) */ pr_bindat_t *pr_bindat; /* bindat(2) */ pr_listen_t *pr_listen; /* listen(2) */ pr_accept_t *pr_accept; /* accept(2) */ pr_connectat_t *pr_connectat; /* connectat(2) */ pr_connect2_t *pr_connect2; /* socketpair(2) */ pr_control_t *pr_control; /* ioctl(2) */ pr_rcvoob_t *pr_rcvoob; /* soreceive_rcvoob() */ pr_ctloutput_t *pr_ctloutput; /* control output (from above) */ pr_peeraddr_t *pr_peeraddr; /* getpeername(2) */ pr_sockaddr_t *pr_sockaddr; /* getsockname(2) */ pr_sense_t *pr_sense; /* stat(2) */ }; .Ed .Pp The following functions handle the registration of new domains and protocols. .Pp .Fn domain_add adds a new protocol domain to the system. In most cases .Fn domain_add is not called directly, instead .Fn DOMAIN_SET is used, which is a wrapper around .Fn SYSINIT macro. If the new domain has defined a .Va dom_probe routine, it is called first in .Fn domain_add to determine if the domain should be supported on the current system. If the probe routine returns a non-0 value, then the domain will not be added. Once a domain is added it cannot be completely unloaded. This is because there is no reference counting system in place to determine if there are any active references from sockets within that domain. However, the exprimental .Fn domain_remove exists, and unloadable domains may be supported in the future. .Pp .Fn protosw_register dynamically adds a protocol to a domain, if the latter has an empty slot in its .Va dom_protosw . Dynamically added protocol can later be unloaded with .Fn protosw_unregister . .Ed .Sh RETURN VALUES The .Fn domain_add never fails, but it may not add a domain if its .Va dom_probe fails. .Pp The .Fn protosw_register function may fail if: .Bl -tag -width Er .It Bq Er EEXIST A protocol with the same value of .Va pr_type and .Va pr_protocol already exists in the domain. .It Bq Er ENOMEM The domain doesn't have any NULL slots in its .Va dom_protosw . .El .Sh SEE ALSO .Xr socket 2 , .Xr SYSINIT 9 .Sh HISTORY The .Nm subsystem first appeared in .Bx 4.3 as the part of the very first .Xr socket 2 API implementation. .Pp The .Nm subsystem and this manual page were significantly rewritten in .Fx 14 . .Sh AUTHORS This manual page was written by .An Chad David Aq Mt davidc@acns.ab.ca and .An Gleb Smirnoff Aq Mt glebius@FreeBSD.org .