Page MenuHomeFreeBSD
Files F154341425

D56089.diff
No OneTemporary
Actions

D56089.diff
View Options

diff --git a/share/man/man9/domain.9 b/share/man/man9/domain.9
--- a/share/man/man9/domain.9
+++ b/share/man/man9/domain.9
@@ -1,6 +1,7 @@
.\"
.\" Copyright (C) 2001 Chad David <davidc@acns.ab.ca>. All rights reserved.
.\" Copyright (C) 2022 Gleb Smirnoff <glebius@FreeBSD.org>
+.\" Copyright (C) 2026 Pouria Mousavizadeh Tehrani <pouria@FreeBSD.org>
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
@@ -25,7 +26,7 @@
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
.\" DAMAGE.
.\"
-.Dd September 14, 2022
+.Dd March 25, 2026
.Dt DOMAIN 9
.Os
.Sh NAME
@@ -37,6 +38,7 @@
.In sys/kernel.h
.In sys/protosw.h
.In sys/domain.h
+.Ss "Protocol Registration Interfaces"
.Ft void
.Fn domain_add "struct domain *dom"
.Ft void
@@ -47,6 +49,63 @@
.Fn protosw_register "struct domain *dom" "struct protosw *pr"
.Ft int
.Fn protosw_unregister "struct protosw *pr"
+.Ss "Interface Prototypes for protosw"
+.Ft int
+.Fo pr_soreceive_t
+.Fa "struct socket *so" "struct sockaddr **sa" "struct uio *uio"
+.Fa "struct mbuf **m" "struct mbuf **control" "int *flags"
+.Fc
+.Ft int
+.Fo pr_sosend_t
+.Fa "struct socket *so" "struct sockaddr *sa" "struct uio *uio"
+.Fa "struct mbuf *m" "struct mbuf *control" "int flags" "struct thread *td"
+.Fc
+.Ft int
+.Fo pr_send_t
+.Fa "struct socket *so" "int flags" "struct mbuf *m"
+.Fa "struct sockaddr *sa" "struct mbuf *control" "struct thread *td"
+.Fc
+.Ft int
+.Fn pr_sopoll_t "struct socket *so" "struct thread *td"
+.Ft int
+.Fn pr_attach_t "struct socket *so" "int proto" "struct thread *td"
+.Ft void
+.Fn pr_detach_t "struct socket *so"
+.Ft int
+.Fn pr_connect_t "struct socket *so" "struct sockaddr *sa" "struct thread *td"
+.Ft int
+.Fn pr_disconnect_t "struct socket *so"
+.Ft int
+.Fn pr_close_t "struct socket *so"
+.Ft int
+.Fn pr_rcvd_t "struct socket *so" "int flags"
+.Ft int
+.Fn pr_bind_t "struct socket *so" "struct sockaddr *sa" "struct thread *td"
+.Ft int
+.Fn pr_listen_t "struct socket *so" "int backlog" "struct thread *td"
+.Ft int
+.Fn pr_accept_t "struct socket *so" "struct sockaddr *sa"
+.Ft int
+.Fn pr_connect2_t "struct socket *so1" "struct socket *so2"
+.Ft int
+.Fo pr_control_t
+.Fa "struct socket *so" "unsigned long cmd" "void *data" "struct ifnet *ifp"
+.Fa "struct thread *td"
+.Fc
+.Ft int
+.Fn pr_rcvoob_t "struct socket *so" "struct mbuf *m" "int flags"
+.Ft int
+.Fn pr_ctloutput_t "struct socket *so" "struct sockopt *opt"
+.Ft void
+.Fn pr_abort_t "struct socket *so"
+.Ft int
+.Fn pr_peeraddr_t "struct socket *so" "struct sockaddr *nam"
+.Ft int
+.Fn pr_sockaddr_t "struct socket *so" "struct sockaddr *nam"
+.Ft int
+.Fn pr_sense_t "struct socket *so" "struct stat *stat"
+.Ft int
+.Fn pr_shutdown_t "struct socket *so" "enum shutdown_how"
.Sh DESCRIPTION
The
.Nm
@@ -183,6 +242,210 @@
.Va dom_protosw .
Dynamically added protocol can later be unloaded with
.Fn protosw_unregister .
+.Sh PROTOCOL SWITCH PROTOTYPES
+All of the functions must pass the
+.Va struct socket *
+as their first argument.
+.Pp
+.Fn pr_soreceive_t
+handles receive data from receive buffer of the socket using
+.Xr uio 9 .
+Protocols can implement this function to handle data for user requests from
+.Xr recv 2
+and
+.Xr recvmsg 2 .
+.Pp
+.Fn pr_sosend_t
+is the same as
+.Fn pr_send_t
+called from
+.Fn sosend_generic .
+.Pp
+.Fn pr_send_t
+should prepare and fill the
+.Va struct mbuf *
+in order to pass the user data to the lower level protocols.
+If unable, protocols must free the received mbuf using
+.Fn m_freem .
+.Pp
+.Fn pr_sopoll_t
+currently only used by local domain to notify the user if there is any I/O
+available to receive.
+Only called from
+.Xr select 2
+and
+.Xr poll 2 .
+.Pp
+.Fn pr_attach_t
+verifies thread privilege, allocates and initializes necessary resources during
+socket creation by
+.Fn socreate
+and
+.Fn sonewconn .
+This function usually reserves socket's send and receive buffers by calling the
+.Fn soreserve .
+It also should allocate and initialize the protocol database using
+.Fn in_pcballoc .
+.Pp
+.Fn pr_detach_t
+releases socket-specific resources during
+.Fn sofree .
+These resources include the protocol database and can be freed by calling
+.Fn in_pcbfree .
+.Pp
+.Fn pr_connect_t
+validates destination address and should select an appropriate source address
+for requested socket.
+Connection-oriented protocols should verify incoming socket to NOT be flagged
+with
+.Va INP_DROPPED
+to avoid reusing open sockets without ongoing open connections and also should
+check for already listening sockets using
+.Va SOLISTENING .
+.Pp
+After performing the actual connection, Connection-oriented protocols must
+inform the socket layer that their socket is in connecting state by using
+.Fn soisconnecting .
+Otherwise, datagram protocols can notify that socket is connected by using
+.Fn soisconnected .
+.Fn pr_disconnect_t
+used by network protocols to clear PCB address and abort their connections.
+Datagram protocols should call
+.Fn in_pcbdisconnect
+and notify socket layer by clearing
+.Va SS_ISCONNECTED
+flags.
+Connection-oriented protocols should start to close their connections
+and notify the socket layer by calling
+.Fn soisdisconnected .
+.Pp
+.Fn pr_close_t
+terminates the socket when the reference count of the socket is zero.
+Therefore, protocols should delete any associated PCB using
+.Fn in_pcbdisconnect ,
+and notify the socket layer via
+.Fn soisdisconnected .
+.Pp
+.Fn pr_rcvd_t
+only used by connection-oriented protocols during
+.Fn soreceive_generic
+execution to acknowledge received data by notifying their peer, if
+they set the
+.Va PR_WANTRCVD
+flag in their
+.Va pr_flags .
+.Pp
+.Fn pr_bind_t
+validates user provided
+.Va struct sockaddr *
+and verifies its thread privilege.
+Finally, it assigns the socket address to the protocol database.
+.Pp
+.Fn pr_bindat_t
+currently only used by the local domain for
+.Xr capsicum 4
+to bind the socket via a file descriptor.
+.Pp
+.Fn pr_listen_t
+Used by transport protocols to prepare the socket to accept connections.
+Connection-oriented protocols validate that the incoming socket
+is NOT flagged with
+.Va INP_DROPPED
+to avoid listening to open sockets without an ongoing open connection.
+Protocols also should check for already listening sockets via
+.Va SOLISTENING .
+After performing protocol validations, protocols also must acquire necessary
+locks and socket state validations by calling the
+.Fn solisten_proto_check .
+Transport protocols can use
+.Fn in_pcbbind
+for unspecified socket addresses and ports to select an appropriate one
+based on the provided thread credential.
+.Pp
+.Fn pr_accept_t
+is connection-oriented only function.
+Protocols like
+.Xr tcp 4
+should return the address of their peer by storing it into
+.Va struct sockaddr *sa .
+.Pp
+.Fn pr_connectat_t
+currently only used by local domain for
+.Xr capsicum 4
+to connect a socket by a file descriptor.
+.Pp
+.Fn pr_connect2_t
+currently only used by local domain to connect two user provided sockets via
+.Xr socketpair 2 .
+.Pp
+.Fn pr_control_t
+should be defined to use protocol-specific operations using
+.Xr ioctl 2
+interface.
+IP protocols can use generic
+.Fn in_control
+and
+.Fn in6_control
+interfaces.
+.Pp
+.Fn pr_rcvoob_t
+called from
+.Fn soreceive_rcvoob
+to handle out-of-band data from socket and place it in the provided mbuf.
+.Pp
+.Fn pr_ctloutput_t
+should be defined to set or get a protocol-specific option at
+the socket layer using
+.Xr ioctl 2
+interface.
+.Va sopt->sopt_dir
+provided by the user can be either
+.Va SOPT_GET
+to retrieve an option or
+.Va SOPT_SET
+to set an option.
+.Pp
+.Fn pr_abort_t
+abnormally terminates the socket.
+Therefore, protocols should delete any associated PCB using
+.Fn in_pcbdisconnect ,
+and they also should notify the socket layer via
+.Fn soisdisconnected .
+Connection-oriented protocols can also notify their peer there.
+.Pp
+.Fn pr_peeraddr_t
+called from
+.Xr getpeername 2
+and protocols must fill the provided
+.Va struct sockaddr *
+with peer address.
+.Pp
+.Fn pr_sockaddr_t
+called from
+.Xr getsockname 2
+and protocols must fill the provided
+.Va struct sockaddr *
+with local socket address.
+.Pp
+.Fn pr_sense_t
+currently only used by local domain to return socket status via
+.Va struct stat .
+.Pp
+.Fn pr_shutdown_t
+requires protocols to shut down their data transmission based on provided
+.Va enum shutdown_how
+as defined in Posix.1g.
+Protocols can use the generic
+.Fn sorflush
+function to flush the read queue for
+.Va SHUT_RD .
+For
+.Va SHUT_WR ,
+however, protocols should call the
+.Fn socantsendmore
+to flush the write queue.
+Connection-oriented protocols can also notify their peer during execution of
+this function call.
.Sh RETURN VALUES
The
.Fn domain_add
@@ -223,5 +486,6 @@
.Sh AUTHORS
This manual page was written by
.An Chad David Aq Mt davidc@acns.ab.ca
+.An Gleb Smirnoff Aq Mt glebius@FreeBSD.org
and
-.An Gleb Smirnoff Aq Mt glebius@FreeBSD.org .
+.An Pouria Mousavizadeh Tehrani Aq Mt pouria@FreeBSD.org .

File Metadata

Mime Type
text/plain
Expires
Tue, Apr 28, 11:26 PM (10 h, 45 m)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
32233734
Default Alt Text
D56089.diff (8 KB)

Event Timeline