#include <sys/socket.h>
#include <sys/socketvar.h> int
sobind (struct socket *so struct sockaddr *nam struct thread *td); void
soclose (struct socket *so); int
soconnect (struct socket *so struct sockaddr *nam struct thread *td); int
Fo socreate
Fa int dom struct socket **aso int type int proto
Fa struct ucred *cred struct thread *td
Fc Ft int
sogetopt (struct socket *so struct sockopt *sopt); 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
sosetopt (struct socket *so struct sockopt *sopt); 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
soshutdown (struct socket *so int how);
DESCRIPTION
The kernel
programming interface permits in-kernel consumers to interact with
local and network socket objects in a manner similar to that permitted using
the
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.
Except where otherwise indicated,
functions may sleep, and are not appropriate for use in an
ithread(9)
context or while holding non-sleepable kernel locks.
Creating and Destroying Sockets
A new socket may be created using
socreate (.);
As with
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 .
Warning
authorization of the socket creation operation will be performed
using the thread credential for some protocols (such as raw sockets).
Sockets may be closed and freed using
soclose (,);
which has similar semantics to
close(2).
Connections and Addresses
The
sobind ();
function is equivalent to the
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 .
The
soconnect ();
function is equivalent to the
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,
soconnect ();
returns immediately; the caller may
msleep(9)
on
Fa so->so_timeo
while holding the socket mutex and waiting for the
SS_ISCONNECTING
flag to clear or
Fa so->so_error
to become non-zero.
If
soconnect ();
fails, the caller must manually clear the
SS_ISCONNECTING
flag.
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.
Socket Options
The
sogetopt ();
function is equivalent to the
getsockopt(2)
system call, and retrieves a socket option on socket
Fa so .
The
sosetopt ();
function is equivalent to the
setsockopt(2)
system call, and sets a socket option on socket
Fa so .
The second argument in both
sogetopt ();
and
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:
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.
Socket I/O
The
soreceive ();
function is equivalent to the
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
non- NULL
The caller may optionally retrieve a socket address on a protocol with the
PR_ADDR
capability by providing storage via
non- NULL
Fa psa
argument.
The caller may optionally retrieve control data mbufs via a
non- NULL
Fa controlp
argument.
Optional flags may be passed to
soreceive ();
via a
non- NULL
Fa flagsp
argument, and use the same flag name space as the
recvmsg(2)
system call.
The
sosend ();
function is equivalent to the
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
non- NULL
An optional destination address may be specified via a
non- 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
non- NULL
Fa control
argument.
Flags may be passed to
sosend ();
using the
Fa flags
argument, and use the same flag name space as the
sendmsg(2)
system call.
Kernel callers running in
ithread(9)
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.
The
socket(2)
system call appeared in
BSD 4.2
This manual page was introduced in
Fx 7.0 .
AUTHORS
This manual page was written by
An Robert Watson .
BUGS
The use of explicitly passed credentials, credentials hung from explicitly
passed threads, the credential on
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.
The caller may need to manually clear
SS_ISCONNECTING
if
soconnect ();
returns an error.
The
MSG_DONTWAIT
flag is not implemented for
sosend (,);
and may not always work with
soreceive ();
when zero copy sockets are enabled.
This manual page does not describe how to register socket upcalls or monitor
a socket for readability/writability without using blocking I/O.
The
soref ();
and
sorele ();
functions are not described, and in most cases should not be used, due to
confusing and potentially incorrect interactions when
sorele ();
is last called after
soclose (.);
