other sections
SOCKET(9) | Kernel Developer's Manual | SOCKET(9) |
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 kernelsocket
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 usingsocreate
().
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¶
Thesobind
() 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¶
Thesogetopt
() 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
orSOPT_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¶
Thesoreceive
() 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 oncurthread
, 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
().April 12, 2013 | Debian |