feat: Added FreeBSD man pages

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 .