From 1d3d170d84fa1e6127bdf989319a5d7a91f81745 Mon Sep 17 00:00:00 2001 From: rwatson Date: Fri, 15 Dec 2006 23:35:15 +0000 Subject: 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 --- share/man/man9/Makefile | 10 ++ share/man/man9/socket.9 | 334 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 344 insertions(+) create mode 100644 share/man/man9/socket.9 diff --git a/share/man/man9/Makefile b/share/man/man9/Makefile index 48403f7..c50a0b5 100644 --- a/share/man/man9/Makefile +++ b/share/man/man9/Makefile @@ -211,6 +211,7 @@ MAN= accept_filter.9 \ signal.9 \ sleep.9 \ sleepqueue.9 \ + socket.9 \ spl.9 \ store.9 \ style.9 \ @@ -1009,6 +1010,15 @@ 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 \ + socket.9 soclose.9 \ + socket.9 soconnect.9 \ + socket.9 socreate.9 \ + socket.9 sogetopt.9 \ + socket.9 soreceive.9 \ + socket.9 sosetopt.9 \ + socket.9 sosend.9 \ + socket.9 soshutdown.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 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 . -- cgit v1.1