Add some kernel socket documentation. Originally from FreeBSD with some

tweaks by me to match the OpenBSD reality. Additional help from jmc@
ja ja ja dlg@ and OK blambert@

2 files changed, 303 insertions, 3 deletions

diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile
index d12b74319ec..bbc1af62bf5 100644
--- a/share/man/man9/Makefile
+++ b/share/man/man9/Makefile
@@ -1,4 +1,4 @@
-#	$OpenBSD: Makefile,v 1.148 2009/01/15 17:35:48 oga Exp $
+#	$OpenBSD: Makefile,v 1.149 2009/01/29 16:47:25 claudio Exp $
 #	$NetBSD: Makefile,v 1.4 1996/01/09 03:23:01 thorpej Exp $
 
 #	Makefile for section 9 (kernel function and variable) manual pages.
@@ -23,7 +23,7 @@ MAN=	altq.9 aml_evalnode.9 atomic.9 audio.9 autoconf.9 bio_register.9 \
 	radio.9 random.9 rasops.9 ratecheck.9 resettodr.9 rssadapt.9 rwlock.9 \
 	sensor_attach.9 \
 	shutdownhook_establish.9 tsleep.9 spl.9 startuphook_establish.9 \
-	style.9 syscall.9 systrace.9 sysctl_int.9 \
+	socreate.9 style.9 syscall.9 systrace.9 sysctl_int.9 \
 	tc_init.9 time.9 timeout.9 tvtohz.9 uiomove.9 uvm.9 vfs.9 vfs_busy.9 \
 	vfs_cache.9 vaccess.9 vclean.9 vcount.9 vdevgone.9 vfinddev.9 vflush.9 \
 	vflushbuf.9 vget.9 vgone.9 vhold.9 vinvalbuf.9 vnode.9 vnsubr.9 \
@@ -273,7 +273,9 @@ MLINKS+=sensor_attach.9 sensordev_install.9 \
 	sensor_attach.9 sensor_task_register.9 \
 	sensor_attach.9 sensor_task_unregister.9
 MLINKS+=shutdownhook_establish.9 shutdownhook_disestablish.9
-MLINKS+=tsleep.9 wakeup.9 tsleep.9 msleep.9
+MLINKS+=socreate.9 sobind.9 socreate.9 soclose.9 socreate.9 soconnect.9 \
+	socreate.9 sogetopt.9 socreate.9 soreceive.9 socreate.9 sosetopt.9 \
+	socreate.9 sosend.9 socreate.9 soshutdown.9
 MLINKS+=spl.9 spl0.9 spl.9 splassert.9 spl.9 splbio.9 spl.9 splclock.9 \
 	spl.9 splhigh.9 spl.9 spllowersoftclock.9 \
 	spl.9 splnet.9 spl.9 splsched.9 spl.9 splserial.9 spl.9 splsoftclock.9 \
@@ -295,6 +297,7 @@ MLINKS+=timeout.9 timeout_add.9 timeout.9 timeout_set.9 \
 	timeout.9 timeout_add_ts.9 timeout.9 timeout_add_bt.9 \
 	timeout.9 timeout_add_sec.9 timeout.9 timeout_add_usec.9 \
 	timeout.9 timeout_add_nsec.9
+MLINKS+=tsleep.9 wakeup.9 tsleep.9 msleep.9
 MLINKS+=uiomove.9 uio.9
 MLINKS+=uvm.9 uvm_init.9 uvm.9 uvm_init_limits.9 uvm.9 uvm_setpagesize.9 \
 	uvm.9 uvm_swap_init.9 uvm.9 uvm_map.9 uvm.9 uvm_map_pageable.9 \
diff --git a/share/man/man9/socreate.9 b/share/man/man9/socreate.9
new file mode 100644
index 00000000000..6a55cd289d6
--- /dev/null
+++ b/share/man/man9/socreate.9
@@ -0,0 +1,297 @@
+.\"	$OpenBSD: socreate.9,v 1.1 2009/01/29 16:47:25 claudio Exp $
+.\"
+.\" 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: src/share/man/man9/socket.9,v 1.2 2006/12/16 10:32:10 rwatson Exp $
+.\"
+.Dd $Mdocdate: January 29 2009 $
+.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 mbuf *nam" "struct proc *p"
+.Ft void
+.Fn soclose "struct socket *so"
+.Ft int
+.Fn soconnect "struct socket *so" "struct mbuf *nam"
+.Ft int
+.Fo socreate
+.Fa "int dom" "struct socket **aso" "int type" "int proto"
+.Fc
+.Ft int
+.Fn sogetopt "struct socket *so" "struct sockopt *sopt"
+.Ft int
+.Fo soreceive
+.Fa "struct socket *so" "struct mbuf **paddr" "struct uio *uio"
+.Fa "struct mbuf **mp0" "struct mbuf **controlp" "int *flagsp"
+.Fc
+.Ft int
+.Fn sosetopt "struct socket *so" "int level" "int optname" "struct mbuf *m0"
+.Ft int
+.Fn sogetopt "struct socket *so" "int level" "int optname" "struct mbuf **mp"
+.Ft int
+.Fo sosend
+.Fa "struct socket *so" "struct mbuf *addr" "struct uio *uio"
+.Fa "struct mbuf *top" "struct mbuf *control" "int flags"
+.Fc
+.Ft int
+.Fn soshutdown "struct socket *so" "int how"
+.Sh DESCRIPTION
+The kernel socket
+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.
+.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.
+.Em Warning :
+authorization of the socket creation operation will be performed
+using
+.Dv curproc
+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 process
+.Fa p .
+.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
+.Dv curproc .
+Unlike the user system call,
+.Fn soconnect
+returns immediately; the caller may
+.Xr tsleep 9
+on
+.Fa so-\*(Gtso_timeo
+and wait for the
+.Dv SS_ISCONNECTING
+flag to clear or
+.Fa so-\*(Gtso_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 next two arguments in both
+.Fn sogetopt
+and
+.Fn sosetopt
+are
+.Fa level
+and
+.Fa optname
+describing the protocol level and socket option.
+The last argument is either a pointer to a prefilled mbuf
+.Fa m0
+or a pointer to a mbuf pointer
+.Fa mp
+which will point to the retrieved data.
+.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 and awaiting 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 a
+.Pf non- Dv NULL
+.Fa paddr
+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 interrupt 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 ,
+.Xr tsleep 9
+.Sh HISTORY
+The
+.Xr socket 2
+system call appeared in
+.Bx 4.2 .
+This manual page was introduced in
+.Fx 7.0
+and ported to
+.Ox 4.5 .
+.Sh AUTHORS
+This manual page was written by
+.An Robert Watson .
+.Sh BUGS
+The use of credentials hung from explicitly passed processes,
+and the credential on
+.Dv curproc ,
+and the cached credential from socket creation time is inconsistent, and may
+lead to unexpected behaviour.
+.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 .
+.Pp
+This manual page does not describe how to register socket upcalls or monitor
+a socket for readability/writability without using blocking I/O.