Manual Pages  — SOCKET

Except where otherwise indicated, socket functions may sleep, and are not appropriate for use in an interrupt thread context or while holding non-sleepable kernel locks.

Sockets may be closed and freed using soclose(), which has similar semantics to close(2).

In certain circumstances, it is appropriate to destroy a socket without waiting for it to disconnect, for which 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 soabort() is responsible for setting the VNET context. The normal path to freeing a socket is 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 sofree() should not be made from outside the socket layer; outside callers should use soclose() instead.

The soconnect() function is equivalent to the connect(2) system call, and initiates a connection on the socket so to the address nam. The operation will be authorized using the credential on thread td. Unlike the user system call, soconnect() returns immediately; the caller may msleep(9) on so->so_timeo while holding the socket mutex and waiting for the SS_ISCONNECTING flag to clear or so->so_error to become non-zero. If soconnect() fails, the caller must manually clear the SS_ISCONNECTING flag.

A call to sodisconnect() disconnects the socket without closing it.

The soshutdown() function is equivalent to the shutdown(2) system call, and causes part or all of a connection on a socket to be closed down.

Sockets are transitioned from non-listening status to listening with solisten().

The second argument in both sogetopt() and sosetopt() is the sopt pointer to a 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:

sopt_dir
	Set to SOPT_SET or SOPT_GET depending on whether this is a get or set operation.
sopt_level
	Specify the level in the network stack the operation is targeted at; for example, SOL_SOCKET.
sopt_name
	Specify the name of the socket option to set.
sopt_val
	Kernel space pointer to the argument value for the socket option.
sopt_valsize
	Size of the argument value in bytes.

The sosend() function is equivalent to the sendmsg(2) system call, and attempts to send bytes of data via the socket so, optionally blocking if data cannot be immediately sent. Data may be sent directly from kernel or user memory via the uio argument, or as an mbuf chain via top, avoiding a data copy. Only one of the uio or top pointers may be non- NULL. An optional destination address may be specified via a non- NULL addr argument, which may result in an implicit connect if supported by the protocol. The caller may optionally send control data mbufs via a non- NULL control argument. Flags may be passed to sosend() using the flags argument, and use the same flag name space as the sendmsg(2) system call.

Kernel callers running in an interrupt thread context, or with a mutex held, will wish to use non-blocking sockets and pass the MSG_DONTWAIT flag in order to prevent these functions from sleeping.

A socket can be queried for readability, writability, out-of-band data, or end-of-file using sopoll(). The possible values for events are as for poll(2), with symbolic values POLLIN, POLLPRI, POLLOUT, POLLRDNORM, POLLWRNORM, POLLRDBAND, and POLLINGEOF taken from <sys/poll.h>.

Calls to soaccept() pass through to the protocol's accept routine to accept an incoming connection.