2001-12-07 20:58:07 +00:00
|
|
|
.\"
|
|
|
|
.\" Copyright (C) 2001 Chad David <davidc@acns.ab.ca>. All rights reserved.
|
2022-09-14 21:11:40 +00:00
|
|
|
.\" Copyright (C) 2022 Gleb Smirnoff <glebius@FreeBSD.org>
|
2001-12-07 20:58:07 +00:00
|
|
|
.\"
|
|
|
|
.\" 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.
|
|
|
|
.\"
|
2022-09-14 21:11:40 +00:00
|
|
|
.Dd September 14, 2022
|
2001-12-07 20:58:07 +00:00
|
|
|
.Dt DOMAIN 9
|
|
|
|
.Os
|
|
|
|
.Sh NAME
|
2022-09-14 21:11:40 +00:00
|
|
|
.Nm domain ,
|
|
|
|
.Nm protosw
|
|
|
|
.Nd "programming interface for kernel socket implementation"
|
2001-12-07 20:58:07 +00:00
|
|
|
.Sh SYNOPSIS
|
|
|
|
.In sys/param.h
|
2001-12-26 23:14:04 +00:00
|
|
|
.In sys/kernel.h
|
2001-12-07 20:58:07 +00:00
|
|
|
.In sys/protosw.h
|
|
|
|
.In sys/domain.h
|
|
|
|
.Ft void
|
2022-09-14 21:11:40 +00:00
|
|
|
.Fn domain_add "struct domain *dom"
|
2001-12-07 20:58:07 +00:00
|
|
|
.Ft void
|
2022-09-14 21:11:40 +00:00
|
|
|
.Fn domain_remove "struct domain *dom"
|
2020-06-26 02:17:47 +00:00
|
|
|
.Ft void
|
2022-09-14 21:11:40 +00:00
|
|
|
.Fn DOMAIN_SET "domain"
|
|
|
|
.Ft int
|
|
|
|
.Fn protosw_register "struct domain *dom" "struct protosw *pr"
|
|
|
|
.Ft int
|
|
|
|
.Fn protosw_unregister "struct protosw *pr"
|
2001-12-07 20:58:07 +00:00
|
|
|
.Sh DESCRIPTION
|
2022-09-14 21:11:40 +00:00
|
|
|
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:
|
2001-12-07 20:58:07 +00:00
|
|
|
.Bd -literal
|
|
|
|
struct domain {
|
2022-09-14 21:11:40 +00:00
|
|
|
/*
|
|
|
|
* 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[];
|
2001-12-07 20:58:07 +00:00
|
|
|
};
|
|
|
|
.Ed
|
|
|
|
.Pp
|
2022-09-14 21:11:40 +00:00
|
|
|
Each domain contains the
|
|
|
|
.Va dom_protosw
|
|
|
|
array of protocol switch structures
|
2002-01-10 17:47:38 +00:00
|
|
|
.Pq Vt "struct protosw *" ,
|
2001-12-07 20:58:07 +00:00
|
|
|
one for each socket type supported.
|
2022-09-14 21:11:40 +00:00
|
|
|
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.
|
2001-12-07 20:58:07 +00:00
|
|
|
.Bd -literal
|
|
|
|
struct protosw {
|
2022-09-14 21:11:40 +00:00
|
|
|
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) */
|
2001-12-07 20:58:07 +00:00
|
|
|
};
|
|
|
|
.Ed
|
|
|
|
.Pp
|
2022-09-14 21:11:40 +00:00
|
|
|
The following functions handle the registration of new domains and protocols.
|
2001-12-07 20:58:07 +00:00
|
|
|
.Pp
|
2012-02-23 17:47:19 +00:00
|
|
|
.Fn domain_add
|
2001-12-07 20:58:07 +00:00
|
|
|
adds a new protocol domain to the system.
|
|
|
|
In most cases
|
2012-02-23 17:47:19 +00:00
|
|
|
.Fn domain_add
|
2001-12-07 20:58:07 +00:00
|
|
|
is not called directly, instead
|
|
|
|
.Fn DOMAIN_SET
|
2022-09-14 21:11:40 +00:00
|
|
|
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
|
2020-06-26 02:17:47 +00:00
|
|
|
.Fn domain_add
|
|
|
|
to determine if the domain should be supported on the current system.
|
2022-09-14 21:11:40 +00:00
|
|
|
If the probe routine returns a non-0 value, then the domain will not be added.
|
2020-06-26 02:17:47 +00:00
|
|
|
Once a domain is added it cannot be completely unloaded.
|
2002-01-10 17:47:38 +00:00
|
|
|
This is because there is
|
2001-12-07 20:58:07 +00:00
|
|
|
no reference counting system in place to determine if there are any
|
|
|
|
active references from sockets within that domain.
|
2022-09-14 21:11:40 +00:00
|
|
|
However, the exprimental
|
|
|
|
.Fn domain_remove
|
|
|
|
exists, and unloadable domains may be supported in the future.
|
2001-12-07 20:58:07 +00:00
|
|
|
.Pp
|
2022-09-14 21:11:40 +00:00
|
|
|
.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 .
|
2001-12-07 20:58:07 +00:00
|
|
|
.Ed
|
|
|
|
.Sh RETURN VALUES
|
2022-09-14 21:11:40 +00:00
|
|
|
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
|
2001-12-07 20:58:07 +00:00
|
|
|
and
|
2022-09-14 21:11:40 +00:00
|
|
|
.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
|
2001-12-07 20:58:07 +00:00
|
|
|
.Sh SEE ALSO
|
2022-09-14 21:11:40 +00:00
|
|
|
.Xr socket 2 ,
|
|
|
|
.Xr SYSINIT 9
|
2020-04-29 11:46:01 +00:00
|
|
|
.Sh HISTORY
|
2022-09-14 21:11:40 +00:00
|
|
|
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 .
|
2001-12-07 20:58:07 +00:00
|
|
|
.Sh AUTHORS
|
2005-06-28 20:15:19 +00:00
|
|
|
This manual page was written by
|
2022-09-14 21:11:40 +00:00
|
|
|
.An Chad David Aq Mt davidc@acns.ab.ca
|
|
|
|
and
|
|
|
|
.An Gleb Smirnoff Aq Mt glebius@FreeBSD.org .
|