Add a basic man page for the socket(9) kernel programming interface used
by the NFS client and server, netsmb, netncp, etc. Reviewed by: ru Fixed by: ru
This commit is contained in:
rwatson
parent
22a6932ccb
commit
1d3d170d84
@ -211,6 +211,7 @@ MAN= accept_filter.9 \
|
||||
signal.9 \
|
||||
sleep.9 \
|
||||
sleepqueue.9 \
|
||||
socket.9 \
|
||||
spl.9 \
|
||||
store.9 \
|
||||
style.9 \
|
||||
@ -1009,6 +1010,15 @@ MLINKS+=sleepqueue.9 init_sleepqueues.9 \
|
||||
sleepqueue.9 sleepq_timedwait_sig.9 \
|
||||
sleepqueue.9 sleepq_wait.9 \
|
||||
sleepqueue.9 sleepq_wait_sig.9
|
||||
MLINKS+=socket.9 sobind.9 \
|
||||
socket.9 soclose.9 \
|
||||
socket.9 soconnect.9 \
|
||||
socket.9 socreate.9 \
|
||||
socket.9 sogetopt.9 \
|
||||
socket.9 soreceive.9 \
|
||||
socket.9 sosetopt.9 \
|
||||
socket.9 sosend.9 \
|
||||
socket.9 soshutdown.9
|
||||
MLINKS+=spl.9 spl0.9 \
|
||||
spl.9 splbio.9 \
|
||||
spl.9 splclock.9 \
|
||||
|
||||
334
share/man/man9/socket.9
Normal file
334
share/man/man9/socket.9
Normal file
@ -0,0 +1,334 @@
|
||||
.\"-
|
||||
.\" 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 December 14, 2006
|
||||
.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.
|
||||
Only one of the
|
||||
.Fa uio
|
||||
or
|
||||
.Fa mp0
|
||||
pointers may be
|
||||
.Pf non- Dv NULL .
|
||||
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
|
||||
.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 .
|
||||
Loading…
Reference in New Issue
Block a user