346 lines
8.7 KiB
Groff
346 lines
8.7 KiB
Groff
.\"-
|
|
.\" Copyright (c) 2006 Robert N. M. Watson
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd April 12, 2013
|
|
.Dt SOCKET 9
|
|
.Os
|
|
.Sh NAME
|
|
.Nm socket
|
|
.Nd "kernel socket interface"
|
|
.Sh SYNOPSIS
|
|
.In sys/socket.h
|
|
.In sys/socketvar.h
|
|
.Ft int
|
|
.Fn sobind "struct socket *so" "struct sockaddr *nam" "struct thread *td"
|
|
.Ft void
|
|
.Fn soclose "struct socket *so"
|
|
.Ft int
|
|
.Fn soconnect "struct socket *so" "struct sockaddr *nam" "struct thread *td"
|
|
.Ft int
|
|
.Fo socreate
|
|
.Fa "int dom" "struct socket **aso" "int type" "int proto"
|
|
.Fa "struct ucred *cred" "struct thread *td"
|
|
.Fc
|
|
.Ft int
|
|
.Fn sogetopt "struct socket *so" "struct sockopt *sopt"
|
|
.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"
|
|
.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
|
|
.Fn soshutdown "struct socket *so" "int how"
|
|
.Sh DESCRIPTION
|
|
The kernel
|
|
.Nm
|
|
programming interface permits in-kernel consumers to interact with
|
|
local and network socket objects in a manner similar to that permitted using
|
|
the
|
|
.Xr 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.
|
|
.Pp
|
|
Except where otherwise indicated,
|
|
.Nm
|
|
functions may sleep, and are not appropriate for use in an
|
|
.Xr ithread 9
|
|
context or while holding non-sleepable kernel locks.
|
|
.Ss Creating and Destroying Sockets
|
|
A new socket may be created using
|
|
.Fn socreate .
|
|
As with
|
|
.Xr 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 .
|
|
.Em Warning :
|
|
authorization of the socket creation operation will be performed
|
|
using the thread credential for some protocols (such as raw sockets).
|
|
.Pp
|
|
Sockets may be closed and freed using
|
|
.Fn soclose ,
|
|
which has similar semantics to
|
|
.Xr close 2 .
|
|
.Ss Connections and Addresses
|
|
The
|
|
.Fn sobind
|
|
function is equivalent to the
|
|
.Xr 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 .
|
|
.Pp
|
|
The
|
|
.Fn soconnect
|
|
function is equivalent to the
|
|
.Xr 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,
|
|
.Fn soconnect
|
|
returns immediately; the caller may
|
|
.Xr msleep 9
|
|
on
|
|
.Fa so->so_timeo
|
|
while holding the socket mutex and waiting for the
|
|
.Dv SS_ISCONNECTING
|
|
flag to clear or
|
|
.Fa so->so_error
|
|
to become non-zero.
|
|
If
|
|
.Fn soconnect
|
|
fails, the caller must manually clear the
|
|
.Dv SS_ISCONNECTING
|
|
flag.
|
|
.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.
|
|
.Ss Socket Options
|
|
The
|
|
.Fn sogetopt
|
|
function is equivalent to the
|
|
.Xr getsockopt 2
|
|
system call, and retrieves a socket option on socket
|
|
.Fa so .
|
|
The
|
|
.Fn sosetopt
|
|
function is equivalent to the
|
|
.Xr setsockopt 2
|
|
system call, and sets a socket option on socket
|
|
.Fa so .
|
|
.Pp
|
|
The second argument in both
|
|
.Fn sogetopt
|
|
and
|
|
.Fn 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:
|
|
.Bl -tag -width ".Va sopt_valsize"
|
|
.It Va sopt_dir
|
|
Set to
|
|
.Dv SOPT_SET
|
|
or
|
|
.Dv SOPT_GET
|
|
depending on whether this is a get or set operation.
|
|
.It Va sopt_level
|
|
Specify the level in the network stack the operation is targeted at; for
|
|
example,
|
|
.Dv SOL_SOCKET .
|
|
.It Va sopt_name
|
|
Specify the name of the socket option to set.
|
|
.It Va sopt_val
|
|
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 I/O
|
|
The
|
|
.Fn soreceive
|
|
function is equivalent to the
|
|
.Xr 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.
|
|
The
|
|
.Fa uio
|
|
must always be
|
|
.Pf non- Dv NULL .
|
|
If
|
|
.Fa mp0
|
|
is
|
|
.Pf non- Dv NULL ,
|
|
only the
|
|
.Pf uio_resid
|
|
of
|
|
.Fa uio
|
|
is used.
|
|
The caller may optionally retrieve a socket address on a protocol with the
|
|
.Dv PR_ADDR
|
|
capability by providing storage via
|
|
.Pf non- Dv NULL
|
|
.Fa psa
|
|
argument.
|
|
The caller may optionally retrieve control data mbufs via a
|
|
.Pf non- Dv NULL
|
|
.Fa controlp
|
|
argument.
|
|
Optional flags may be passed to
|
|
.Fn soreceive
|
|
via a
|
|
.Pf non- Dv NULL
|
|
.Fa flagsp
|
|
argument, and use the same flag name space as the
|
|
.Xr recvmsg 2
|
|
system call.
|
|
.Pp
|
|
The
|
|
.Fn sosend
|
|
function is equivalent to the
|
|
.Xr 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
|
|
.Pf non- Dv NULL .
|
|
An optional destination address may be specified via a
|
|
.Pf non- Dv 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
|
|
.Pf non- Dv NULL
|
|
.Fa control
|
|
argument.
|
|
Flags may be passed to
|
|
.Fn sosend
|
|
using the
|
|
.Fa flags
|
|
argument, and use the same flag name space as the
|
|
.Xr sendmsg 2
|
|
system call.
|
|
.Pp
|
|
Kernel callers running in
|
|
.Xr ithread 9
|
|
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.
|
|
.Sh SEE ALSO
|
|
.Xr bind 2 ,
|
|
.Xr close 2 ,
|
|
.Xr connect 2 ,
|
|
.Xr getsockopt 2 ,
|
|
.Xr recv 2 ,
|
|
.Xr send 2 ,
|
|
.Xr setsockopt 2 ,
|
|
.Xr shutdown 2 ,
|
|
.Xr socket 2 ,
|
|
.Xr ng_ksocket 4 ,
|
|
.Xr ithread 9 ,
|
|
.Xr msleep 9 ,
|
|
.Xr ucred 9
|
|
.Sh HISTORY
|
|
The
|
|
.Xr socket 2
|
|
system call appeared in
|
|
.Bx 4.2 .
|
|
This manual page was introduced in
|
|
.Fx 7.0 .
|
|
.Sh AUTHORS
|
|
This manual page was written by
|
|
.An Robert Watson .
|
|
.Sh BUGS
|
|
The use of explicitly passed credentials, credentials hung from explicitly
|
|
passed threads, the credential on
|
|
.Dv 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.
|
|
.Pp
|
|
The caller may need to manually clear
|
|
.Dv SS_ISCONNECTING
|
|
if
|
|
.Fn soconnect
|
|
returns an error.
|
|
.Pp
|
|
The
|
|
.Dv MSG_DONTWAIT
|
|
flag is not implemented for
|
|
.Fn sosend ,
|
|
and may not always work with
|
|
.Fn soreceive
|
|
when zero copy sockets are enabled.
|
|
.Pp
|
|
This manual page does not describe how to register socket upcalls or monitor
|
|
a socket for readability/writability without using blocking I/O.
|
|
.Pp
|
|
The
|
|
.Fn soref
|
|
and
|
|
.Fn sorele
|
|
functions are not described, and in most cases should not be used, due to
|
|
confusing and potentially incorrect interactions when
|
|
.Fn sorele
|
|
is last called after
|
|
.Fn soclose .
|