Document some more socket features

Add some mention of the functions used by protocol implementations,
upcalls, and other general routines.

Not all functionality is documented; in particular:
o the *at() variants, which are useful only for implementing the
  corresponding syscalls.
o soconnect2(), also only used to implement a syscall (socketpair()).
o sockargs(), which is essentually unused and only tangentially
  socket-related.
o selsocket(), which is commented as being present solely for use by
  netncp and netsmb.
o getsockaddr(), which is just a convenience shortcut for copyin().

Reviewed by:	jhb (previous version)
Approved by:	hrs (mentor)

2 files changed, 323 insertions, 6 deletions

diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index 453f3c0850df..d027d3751761 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -1260,15 +1260,41 @@ MLINKS+=sleepqueue.9 init_sleepqueues.9 \
 	sleepqueue.9 sleepq_timedwait_sig.9 \
 	sleepqueue.9 sleepq_wait.9 \
 	sleepqueue.9 sleepq_wait_sig.9
-MLINKS+=socket.9 sobind.9 \
+MLINKS+=socket.9 soabort.9 \
+	socket.9 soaccept.9 \
+	socket.9 sobind.9 \
+	socket.9 socheckuid.9 \
 	socket.9 soclose.9 \
 	socket.9 soconnect.9 \
 	socket.9 socreate.9 \
+	socket.9 sodisconnect.9 \
+	socket.9 sodupsockaddr.9 \
+	socket.9 sofree.9 \
 	socket.9 sogetopt.9 \
+	socket.9 sohasoutofband.9 \
+	socket.9 solisten.9 \
+	socket.9 solisten_proto.9 \
+	socket.9 solisten_proto_check.9 \
+	socket.9 sonewconn.9 \
+	socket.9 sooptcopyin.9 \
+	socket.9 sooptcopyout.9 \
+	socket.9 sopoll.9 \
+	socket.9 sopoll_generic.9 \
 	socket.9 soreceive.9 \
+	socket.9 soreceive_dgram.9 \
+	socket.9 soreceive_generic.9 \
+	socket.9 soreceive_stream.9 \
+	socket.9 soreserve.9 \
+	socket.9 sorflush.9 \
 	socket.9 sosend.9 \
+	socket.9 sosend_dgram.9 \
+	socket.9 sosend_generic.9 \
 	socket.9 sosetopt.9 \
-	socket.9 soshutdown.9
+	socket.9 soshutdown.9 \
+	socket.9 sotoxsocket.9 \
+	socket.9 soupcall_clear.9 \
+	socket.9 soupcall_set.9 \
+	socket.9 sowakeup.9
 MLINKS+=spl.9 spl0.9 \
 	spl.9 splbio.9 \
 	spl.9 splclock.9 \
diff --git a/share/man/man9/socket.9 b/share/man/man9/socket.9
index f2cb5bae5b0d..8590a3d41e2d 100644
--- a/share/man/man9/socket.9
+++ b/share/man/man9/socket.9
@@ -1,5 +1,6 @@
 .\"-
 .\" Copyright (c) 2006 Robert N. M. Watson
+.\" Copyright (c) 2014 Benjamin J. Kaduk
 .\" All rights reserved.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
@@ -25,7 +26,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd April 12, 2013
+.Dd May 26, 2014
 .Dt SOCKET 9
 .Os
 .Sh NAME
@@ -34,6 +35,12 @@
 .Sh SYNOPSIS
 .In sys/socket.h
 .In sys/socketvar.h
+.Ft void
+.Fn soabort "struct socket *so"
+.Ft int
+.Fn soaccept "struct socket *so" "struct sockaddr **nam"
+.Ft int
+.Fn socheckuid "struct socket *so" "uid_t uid"
 .Ft int
 .Fn sobind "struct socket *so" "struct sockaddr *nam" "struct thread *td"
 .Ft void
@@ -46,21 +53,97 @@
 .Fa "struct ucred *cred" "struct thread *td"
 .Fc
 .Ft int
-.Fn sogetopt "struct socket *so" "struct sockopt *sopt"
+.Fn sodisconnect "struct socket *so"
+.Ft struct  sockaddr *
+.Fn sodupsockaddr "const struct sockaddr *sa" "int mflags"
+.Ft void
+.Fn sofree "struct socket *so"
+.Ft void
+.Fn sohasoutofband "struct socket *so"
+.Ft int
+.Fn solisten "struct socket *so" "int backlog" "struct thread *td"
+.Ft void
+.Fn solisten_proto "struct socket *so" "int backlog"
+.Ft int
+.Fn solisten_proto_check "struct socket *so"
+.Ft struct socket *
+.Fn sonewconn "struct socket *head" "int connstatus"
+.Ft int
+.Fo sopoll
+.Fa "struct socket *so" "int events" "struct ucred *active_cred"
+.Fa "struct thread *td"
+.Fc
+.Ft int
+.Fo sopoll_generic
+.Fa "struct socket *so" "int events" "struct ucred *active_cred"
+.Fa "struct thread *td"
+.Fc
 .Ft int
 .Fo soreceive
 .Fa "struct socket *so" "struct sockaddr **psa" "struct uio *uio"
 .Fa "struct mbuf **mp0" "struct mbuf **controlp" "int *flagsp"
 .Fc
 .Ft int
-.Fn sosetopt "struct socket *so" "struct sockopt *sopt"
+.Fo soreceive_stream
+.Fa "struct socket *so" "struct sockaddr **paddr"
+.Fa "struct uio *uio" "struct mbuf **mp0" "struct mbuf **controlp"
+.Fa "int *flagsp"
+.Fc
+.Ft int
+.Fo soreceive_dgram
+.Fa "struct socket *so" "struct sockaddr **paddr"
+.Fa "struct uio *uio" "struct mbuf **mp0" "struct mbuf **controlp"
+.Fa "int *flagsp"
+.Fc
+.Ft int
+.Fo soreceive_generic
+.Fa "struct socket *so" "struct sockaddr **paddr"
+.Fa "struct uio *uio" "struct mbuf **mp0" "struct mbuf **controlp"
+.Fa "int *flagsp"
+.Fc
+.Ft int
+.Fn soreserve "struct socket *so" "u_long sndcc" "u_long rcvcc"
+.Ft void
+.Fn sorflush "struct socket *so"
 .Ft int
 .Fo sosend
 .Fa "struct socket *so" "struct sockaddr *addr" "struct uio *uio"
 .Fa "struct mbuf *top" "struct mbuf *control" "int flags" "struct thread *td"
 .Fc
 .Ft int
+.Fo sosend_dgram
+.Fa "struct socket *so" "struct sockaddr *addr"
+.Fa "struct uio *uio" "struct mbuf *top" "struct mbuf *control"
+.Fa "int flags" "struct thread *td"
+.Fc
+.Ft int
+.Fo sosend_generic
+.Fa "struct socket *so" "struct sockaddr *addr"
+.Fa "struct uio *uio" "struct mbuf *top" "struct mbuf *control"
+.Fa "int flags" "struct thread *td"
+.Fc
+.Ft int
 .Fn soshutdown "struct socket *so" "int how"
+.Ft void
+.Fn sotoxsocket "struct socket *so" "struct xsocket *xso"
+.Ft void
+.Fn soupcall_clear "struct socket *so" "int which"
+.Ft void
+.Fo soupcall_set
+.Fa "struct socket *so" "int which"
+.Fa "int (*func)(struct socket *, void *, int)" "void *arg"
+.Fc
+.Ft void
+.Fn sowakeup "struct socket *so" "struct sockbuf *sb"
+.In sys/sockopt.h
+.Ft int
+.Fn sosetopt "struct socket *so" "struct sockopt *sopt"
+.Ft int
+.Fn sogetopt "struct socket *so" "struct sockopt *sopt"
+.Ft int
+.Fn sooptcopyin "struct sockopt *sopt" "void *buf" "size_t len" "size_t minlen"
+.Ft int
+.Fn sooptcopyout "struct sockopt *sopt" "const void *buf" "size_t len"
 .Sh DESCRIPTION
 The kernel
 .Nm
@@ -75,6 +158,11 @@ While the user API operates on file descriptors, the kernel interfaces
 operate directly on
 .Vt "struct socket"
 pointers.
+Some portions of the kernel API exist only to implement the user API,
+and are not expected to be used by kernel code.
+The portions of the socket API used by socket consumers and
+implementations of network protocols will differ; some routines
+are only useful for protocol implementors.
 .Pp
 Except where otherwise indicated,
 .Nm
@@ -107,6 +195,31 @@ Sockets may be closed and freed using
 .Fn soclose ,
 which has similar semantics to
 .Xr close 2 .
+.Pp
+In certain circumstances, it is appropriate to destroy a socket without
+waiting for it to disconnect, for which
+.Fn soabort
+is used.
+This is only appropriate for incoming connections which are in a
+partially connected state.
+It must be called on an unreferenced socket, by the thread which
+removed the socket from its listen queue, to prevent races.
+It will call into protocol code, so no socket locks may be held
+over the call.
+The caller of
+.Fn soabort
+is responsible for setting the VNET context.
+The normal path to freeing a socket is
+.Fn sofree ,
+which handles reference counting on the socket.
+It should be called whenever a reference is released, and also whenever
+reference flags are cleared in socket or protocol code.
+Calls to
+.Fn sofree
+should not be made from outside the socket layer; outside callers
+should use
+.Fn soclose
+instead.
 .Ss Connections and Addresses
 The
 .Fn sobind
@@ -146,12 +259,19 @@ fails, the caller must manually clear the
 .Dv SS_ISCONNECTING
 flag.
 .Pp
+A call to
+.Fn sodisconnect
+disconnects the socket without closing it.
+.Pp
 The
 .Fn soshutdown
 function is equivalent to the
 .Xr shutdown 2
 system call, and causes part or all of a connection on a socket to be closed
 down.
+.Pp
+Sockets are transitioned from non-listening status to listening with
+.Fn solisten .
 .Ss Socket Options
 The
 .Fn sogetopt
@@ -195,6 +315,60 @@ Kernel space pointer to the argument value for the socket option.
 .It Va sopt_valsize
 Size of the argument value in bytes.
 .El
+.Ss Socket Upcalls
+In order for the owner of a socket to be notified when the socket
+is ready to send or receive data, an upcall may be registered on
+the socket.
+The upcall is a function that will be called by the socket framework
+when a socket buffer associated with the given socket is ready for
+reading or writing.
+.Fn soupcall_set
+is used to register a socket upcall.
+The function
+.Va func
+is registered, and the pointer
+.Va arg
+will be passed as its second argument when it is called by the framework.
+The possible values for
+.Va which
+are
+.Dv SO_RCV
+and
+.Dv SO_SND ,
+which register upcalls for receive and send events, respectively.
+The upcall function
+.Fn func
+must return either
+.Dv SU_OK
+or
+.Dv SU_ISCONNECTED ,
+depending on whether or not a call to
+.Xr soisconnected
+should be made by the socket framework after the upcall returns.
+The upcall
+.Va func
+cannot call
+.Xr soisconnected
+itself due to lock ordering with the socket buffer lock.
+Only
+.Dv SO_RCV
+upcalls should return
+.Dv SU_ISCONNECTED .
+When a
+.Dv SO_RCV
+upcall returns
+.Dv SU_ISCONNECTED ,
+the upcall will be removed from the socket.
+.Pp
+Upcalls are removed from their socket by
+.Fn soupcall_clear .
+The
+.Va which
+argument again specifies whether the sending or receiving upcall is to
+be cleared, with
+.Dv SO_RCV
+or
+.Dv SO_SND .
 .Ss Socket I/O
 The
 .Fn soreceive
@@ -281,6 +455,121 @@ context, or with a mutex held, will wish to use non-blocking sockets and pass
 the
 .Dv MSG_DONTWAIT
 flag in order to prevent these functions from sleeping.
+.Pp
+A socket can be queried for readability, writability, out-of-band data,
+or end-of-file using
+.Fn sopoll .
+The possible values for
+.Va events
+are as for
+.Xr poll 2 ,
+with symbolic values
+.Dv POLLIN ,
+.Dv POLLPRI ,
+.Dv POLLOUT ,
+.Dv POLLRDNORM ,
+.Dv POLLWRNORM ,
+.Dv POLLRDBAND ,
+and
+.Dv POLLINGEOF
+taken from
+.In sys/poll.h .
+.Pp
+Calls to
+.Fn soaccept
+pass through to the protocol's accept routine to accept an incoming connection.
+.Ss Socket Utility Functions
+The uid of a socket's credential may be compared against a
+.Va uid
+with
+.Fn socheckuid .
+.Pp
+A copy of an existing
+.Vt struct sockaddr
+may be made using
+.Fn sodupsockaddr .
+.Pp
+Protocol implementations notify the socket layer of the arrival of
+out-of-band data using
+.Fn sohasoutofband ,
+so that the socket layer can notify socket consumers of the available data.
+.Pp
+An
+.Dq external-format
+version of a
+.Vt struct socket
+can be created using
+.Fn sotoxsocket ,
+suitable for isolating user code from changes in the kernel structure.
+.Ss Protocol Implementations
+Protocols must supply an implementation for
+.Fn solisten ;
+such protocol implementations can call back into the socket layer using
+.Fn solisten_proto_check
+and
+.Fn solisten_proto
+to check and set the socket-layer listen state.
+These callbacks are provided so that the protocol implementation
+can order the socket layer and protocol locks as necessary.
+Protocols must supply an implementation of
+.Fn soreceive ;
+the functions
+.Fn soreceive_stream ,
+.Fn soreceive_dgram ,
+and
+.Fn soreceive_generic
+are supplied for use by such implementations.
+.Pp
+Protocol implementations can use
+.Fn sonewconn
+to create a socket and attach protocol state to that socket.
+This can be used to create new sockets available for
+.Fn soaccept
+on a listen socket.
+The returned socket has a reference count of zero.
+.Pp
+Protocols must supply an implementation for
+.Fn sopoll ;
+.Fn sopoll_generic
+is provided for the use by protocol implementations.
+.Pp
+The functions
+.Fn sosend_dgram
+and
+.Fn sosend_generic
+are supplied to assist in protocol implementations of
+.Fn sosend .
+.Pp
+When a protocol creates a new socket structure, it is necessary to
+reserve socket buffer space for that socket, by calling
+.Fn soreserve .
+The rough inverse of this reservation is performed by
+.Fn sorflush ,
+which is called automatically by the socket framework.
+.Pp
+When a protocol needs to wake up threads waiting for the socket to
+become ready to read or write, variants of
+.Fn sowakeup
+are used.
+The
+.Fn sowakeup
+function should not be called directly by protocol code, instead use the
+wrappers
+.Fn sorwakeup ,
+.Fn sorwakeup_locked ,
+.Fn sowwakeup ,
+and
+.Fn sowwakeup_locked
+for readers and writers, with the corresponding socket buffer lock
+not already locked, or already held, respectively.
+.Pp
+The functions
+.Fn sooptcopyin
+and
+.Fn sooptcopyout
+are useful for transferring
+.Vt struct sockopt
+data between user and kernel code.
 .Sh SEE ALSO
 .Xr bind 2 ,
 .Xr close 2 ,
@@ -304,7 +593,9 @@ This manual page was introduced in
 .Fx 7.0 .
 .Sh AUTHORS
 This manual page was written by
-.An Robert Watson .
+.An Robert Watson
+and
+.An Benjamin Kaduk .
 .Sh BUGS
 The use of explicitly passed credentials, credentials hung from explicitly
 passed threads, the credential on