svn commit: r266962 - head/share/man/man9
Benjamin Kaduk
bjk at FreeBSD.org
Mon Jun 2 03:03:58 UTC 2014
Author: bjk (doc committer)
Date: Mon Jun 2 03:03:57 2014
New Revision: 266962
URL: http://svnweb.freebsd.org/changeset/base/266962
Log:
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)
Modified:
head/share/man/man9/Makefile
head/share/man/man9/socket.9
Modified: head/share/man/man9/Makefile
==============================================================================
--- head/share/man/man9/Makefile Mon Jun 2 02:20:28 2014 (r266961)
+++ head/share/man/man9/Makefile Mon Jun 2 03:03:57 2014 (r266962)
@@ -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 \
Modified: head/share/man/man9/socket.9
==============================================================================
--- head/share/man/man9/socket.9 Mon Jun 2 02:20:28 2014 (r266961)
+++ head/share/man/man9/socket.9 Mon Jun 2 03:03:57 2014 (r266962)
@@ -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 desc
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 th
.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 val
.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
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
More information about the svn-src-head
mailing list