Add a basic man page for the socket(9) kernel programming interface used

by the NFS client and server, netsmb, netncp, etc.

Reviewed by:	ru
Fixed by:	ru

1 files changed, 334 insertions, 0 deletions

diff --git a/share/man/man9/socket.9 b/share/man/man9/socket.9
new file mode 100644
index 0000000..1931bfe
--- /dev/null
+++ b/share/man/man9/socket.9
@@ -0,0 +1,334 @@
+.\"-
+.\" Copyright (c) 2006 Robert N. M. Watson
+.\" All rights reserved.
+.\"
+.\" 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, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, 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 AUTHOR AND CONTRIBUTORS ``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 AUTHOR OR CONTRIBUTORS 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.
+.\"
+.\" $FreeBSD$
+.\"
+.Dd December 14, 2006
+.Dt SOCKET 9
+.Os
+.Sh NAME
+.Nm socket
+.Nd "kernel socket interface"
+.Sh SYNOPSIS
+.In sys/socket.h
+.In sys/socketvar.h
+.Ft int
+.Fn sobind "struct socket *so" "struct sockaddr *nam" "struct thread *td"
+.Ft void
+.Fn soclose "struct socket *so"
+.Ft int
+.Fn soconnect "struct socket *so" "struct sockaddr *nam" "struct thread *td"
+.Ft int
+.Fo socreate
+.Fa "int dom" "struct socket **aso" "int type" "int proto"
+.Fa "struct ucred *cred" "struct thread *td"
+.Fc
+.Ft int
+.Fn sogetopt "struct socket *so" "struct sockopt *sopt"
+.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"
+.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
+.Fn soshutdown "struct socket *so" "int how"
+.Sh DESCRIPTION
+The kernel
+.Nm
+programming interface permits in-kernel consumers to interact with
+local and network socket objects in a manner similar to that permitted using
+the
+.Xr socket 2
+user API.
+These interfaces are appropriate for use by distributed file systems and
+other network-aware kernel services.
+While the user API operates on file descriptors, the kernel interfaces
+operate directly on
+.Vt "struct socket"
+pointers.
+.Pp
+Except where otherwise indicated,
+.Nm
+functions may sleep, and are not appropriate for use in an
+.Xr ithread 9
+context or while holding non-sleepable kernel locks.
+.Ss Creating and Destroying Sockets
+A new socket may be created using
+.Fn socreate .
+As with
+.Xr socket 2 ,
+arguments specify the requested domain, type, and protocol via
+.Fa dom , type ,
+and
+.Fa proto .
+The socket is returned via
+.Fa aso
+on success.
+In addition, the credential used to authorize operations associated with the
+socket will be passed via
+.Fa cred
+(and will be cached for the lifetime of the socket), and the thread
+performing the operation via
+.Fa td .
+.Em Warning :
+authorization of the socket creation operation will be performed
+using the thread credential for some protocols (such as raw sockets).
+.Pp
+Sockets may be closed and freed using
+.Fn soclose ,
+which has similar semantics to
+.Xr close 2 .
+.Ss Connections and Addresses
+The
+.Fn sobind
+function is equivalent to the
+.Xr bind 2
+system call, and binds the socket
+.Fa so
+to the address
+.Fa nam .
+The operation would be authorized using the credential on thread
+.Fa td .
+.Pp
+The
+.Fn soconnect
+function is equivalent to the
+.Xr connect 2
+system call, and initiates a connection on the socket
+.Fa so
+to the address
+.Fa nam .
+The operation will be authorized using the credential on thread
+.Fa td .
+Unlike the user system call,
+.Fn soconnect
+returns immediately; the caller may
+.Xr msleep 9
+on
+.Fa so->so_timeo
+while holding the socket mutex and waiting for the
+.Dv SS_ISCONNECTING
+flag to clear or
+.Fa so->so_error
+to become non-zero.
+If
+.Fn soconnect
+fails, the caller must manually clear the
+.Dv SS_ISCONNECTING
+flag.
+.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.
+.Ss Socket Options
+The
+.Fn sogetopt
+function is equivalent to the
+.Xr getsockopt 2
+system call, and retrieves a socket option on socket
+.Fa so .
+The
+.Fn sosetopt
+function is equivalent to the
+.Xr setsockopt 2
+system call, and sets a socket option on socket
+.Fa so .
+.Pp
+The second argument in both
+.Fn sogetopt
+and
+.Fn sosetopt
+is the
+.Fa sopt
+pointer to a
+.Vt "struct sopt"
+describing the socket option operation.
+The caller-allocated structure must be zeroed, and then have its fields
+initialized to specify socket option operation arguments:
+.Bl -tag -width ".Va sopt_valsize"
+.It Va sopt_dir
+Set to
+.Dv SOPT_SET
+or
+.Dv SOPT_GET
+depending on whether this is a get or set operation.
+.It Va sopt_level
+Specify the level in the network stack the operation is targeted at; for
+example,
+.Dv SOL_SOCKET .
+.It Va sopt_name
+Specify the name of the socket option to set.
+.It Va sopt_val
+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 I/O
+The
+.Fn soreceive
+function is equivalent to the
+.Xr recvmsg 2
+system call, and attempts to receive bytes of data from the socket
+.Fa so ,
+optionally blocking awaiting for data if none is ready to read.
+Data may be retrieved directly to kernel or user memory via the
+.Fa uio
+argument, or as an mbuf chain returned to the caller via
+.Fa mp0 ,
+avoiding a data copy.
+Only one of the
+.Fa uio
+or
+.Fa mp0
+pointers may be
+.Pf non- Dv NULL .
+The caller may optionally retrieve a socket address on a protocol with the
+.Dv PR_ADDR
+capability by providing storage via
+.Pf non- Dv NULL
+.Fa psa
+argument.
+The caller may optionally retrieve control data mbufs via a
+.Pf non- Dv NULL
+.Fa controlp
+argument.
+Optional flags may be passed to
+.Fn soreceive
+via a
+.Pf non- Dv NULL
+.Fa flagsp
+argument, and use the same flag name space as the
+.Xr recvmsg 2
+system call.
+.Pp
+The
+.Fn sosend
+function is equivalent to the
+.Xr sendmsg 2
+system call, and attempts to send bytes of data via the socket
+.Fa so ,
+optionally blocking if data cannot be immediately sent.
+Data may be sent directly from kernel or user memory via the
+.Fa uio
+argument, or as an mbuf chain via
+.Fa top ,
+avoiding a data copy.
+Only one of the
+.Fa uio
+or
+.Fa top
+pointers may be
+.Pf non- Dv NULL .
+An optional destination address may be specified via a
+.Pf non- Dv NULL
+.Fa addr
+argument, which may result in an implicit connect if supported by the
+protocol.
+The caller may optionally send control data mbufs via a
+.Pf non- Dv NULL
+.Fa control
+argument.
+Flags may be passed to
+.Fn sosend
+using the
+.Fa flags
+argument, and use the same flag name space as the
+.Xr sendmsg 2
+system call.
+.Pp
+Kernel callers running in
+.Xr ithread 9
+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.
+.Sh SEE ALSO
+.Xr bind 2 ,
+.Xr close 2 ,
+.Xr connect 2 ,
+.Xr getsockopt 2 ,
+.Xr recv 2 ,
+.Xr send 2 ,
+.Xr setsockopt 2 ,
+.Xr shutdown 2 ,
+.Xr socket 2
+.Sh HISTORY
+The
+.Xr socket 2
+system call appeared in
+.Bx 4.2 .
+This manual page was introduced in
+.Fx 7.0 .
+.Sh AUTHORS
+This manual page was written by
+.An Robert Watson .
+.Sh BUGS
+The use of explicitly passed credentials, credentials hung from explicitly
+passed threads, the credential on
+.Dv curthread ,
+and the cached credential from
+socket creation time is inconsistent, and may lead to unexpected behaviour.
+It is possible that several of the
+.Fa td
+arguments should be
+.Fa cred
+arguments, or simply not be present at all.
+.Pp
+The caller may need to manually clear
+.Dv SS_ISCONNECTING
+if
+.Fn soconnect
+returns an error.
+.Pp
+The
+.Dv MSG_DONTWAIT
+flag is not implemented for
+.Fn sosend ,
+and may not always work with
+.Fn soreceive
+when zero copy sockets are enabled.
+.Pp
+This manual page does not describe how to register socket upcalls or monitor
+a socket for readability/writability without using blocking I/O.
+.Pp
+The
+.Fn soref
+and
+.Fn sorele
+functions are not described, and in most cases should not be used, due to
+confusing and potentially incorrect interactions when
+.Fn sorele
+is last called after
+.Fn soclose .