diff options
Diffstat (limited to 'static/freebsd/man9/domain.9')
| -rw-r--r-- | static/freebsd/man9/domain.9 | 227 |
1 files changed, 227 insertions, 0 deletions
diff --git a/static/freebsd/man9/domain.9 b/static/freebsd/man9/domain.9 new file mode 100644 index 00000000..d7e743ea --- /dev/null +++ b/static/freebsd/man9/domain.9 @@ -0,0 +1,227 @@ +.\" +.\" Copyright (C) 2001 Chad David <davidc@acns.ab.ca>. All rights reserved. +.\" Copyright (C) 2022 Gleb Smirnoff <glebius@FreeBSD.org> +.\" +.\" 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. +.\" +.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 experimental +.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 . +.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 . |