NAME¶
socket
—
kernel socket interface
SYNOPSIS¶
#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
socreate
(
int
dom,
struct socket **aso,
int type,
int
proto,
struct ucred *cred,
struct thread *td);
int
sogetopt
(
struct
socket *so,
struct sockopt
*sopt);
int
soreceive
(
struct
socket *so,
struct sockaddr **psa,
struct uio *uio,
struct mbuf **mp0,
struct mbuf **controlp,
int *flagsp);
int
sosetopt
(
struct
socket *so,
struct sockopt
*sopt);
int
sosend
(
struct
socket *so,
struct sockaddr *addr,
struct uio *uio,
struct mbuf *top,
struct mbuf *control,
int flags,
struct
thread *td);
int
soshutdown
(
struct
socket *so,
int
how);
DESCRIPTION¶
The kernel
socket
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
struct socket
pointers.
Except where otherwise indicated,
socket
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
dom,
type, and
proto. The socket is returned via
aso on success. In addition, the credential
used to authorize operations associated with the socket will be passed via
cred (and will be cached for the lifetime of
the socket), and the thread performing the operation via
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
so to the address
nam. The operation would be authorized using
the credential on thread
td.
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.
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
so. The
sosetopt
() function is equivalent to the
setsockopt(2) system call, and sets a socket
option on socket
so.
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.
Socket I/O¶
The
soreceive
() function is equivalent to the
recvmsg(2) system call, and attempts to receive
bytes of data from the socket
so, optionally
blocking awaiting for data if none is ready to read. Data may be retrieved
directly to kernel or user memory via the
uio
argument, or as an mbuf chain returned to the caller via
mp0, avoiding a data copy. The
uio must always be
non-
NULL
. If
mp0 is
non-
NULL
, only the uio_resid of
uio is used. The caller may optionally
retrieve a socket address on a protocol with the
PR_ADDR
capability by providing storage via
non-
NULL
psa argument. The caller may optionally
retrieve control data mbufs via a non-
NULL
controlp argument. Optional flags may be
passed to
soreceive
() via a
non-
NULL
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
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
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.
SEE ALSO¶
bind(2),
close(2),
connect(2),
getsockopt(2),
recv(2),
send(2),
setsockopt(2),
shutdown(2),
socket(2),
ng_ksocket(4),
ithread(9),
msleep(9),
ucred(9)
HISTORY¶
The
socket(2) system call appeared in
4.2BSD. This manual page was introduced in
FreeBSD 7.0.
AUTHORS¶
This manual page was written by
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
td arguments
should be
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
().