d/freebsd-skq
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Document some more socket features

Browse Source 
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)
This commit is contained in:
bjk 2014-06-02 03:03:57 +00:00
parent 6a69528255
commit 1665c1635c
2 changed files with 323 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

30
share/man/man9/Makefile
View File

@ -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 \

299
share/man/man9/socket.9
View File

@ -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