SOCREATE(9) OpenBSD Kernel Manual SOCREATE(9)NAME
sobind, soclose, soconnect, socreate, soreceive, sosetopt, sogetopt,
sosend, soshutdown - kernel socket interface
SYNOPSIS
#include <sys/socket.h>
#include <sys/socketvar.h>
int
sobind(struct socket *so, struct mbuf *nam, struct proc *p);
void
soclose(struct socket *so);
int
soconnect(struct socket *so, struct mbuf *nam);
int
socreate(int dom, struct socket **aso, int type, int proto);
int
soreceive(struct socket *so, struct mbuf **paddr, struct uio *uio, struct
mbuf **mp0, struct mbuf **controlp, int *flagsp);
int
sosetopt(struct socket *so, int level, int optname, struct mbuf *m0);
int
sogetopt(struct socket *so, int level, int optname, struct mbuf **mp);
int
sosend(struct socket *so, struct mbuf *addr, struct uio *uio, struct mbuf
*top, struct mbuf *control, int flags);
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, sobind functions may sleep.
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. Warning:
authorization of the socket creation operation will be performed using
curproc 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 process p.
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 curproc. Unlike the
user system call, soconnect() returns immediately; the caller may
tsleep(9) on so->so_timeo and wait 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 next two arguments in both sogetopt() and sosetopt() are level and
optname describing the protocol level and socket option. The last
argument is either a pointer to a prefilled mbuf m0 or a pointer to a
mbuf pointer mp which will point to the retrieved data.
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
and awaiting 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. Only one of
the uio or 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 a non-NULL paddr 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 interrupt 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 ALSObind(2), close(2), connect(2), getsockopt(2), recv(2), send(2),
setsockopt(2), shutdown(2), socket(2), tsleep(9)HISTORY
The socket(2) system call appeared in 4.2BSD. This manual page was
introduced in FreeBSD 7.0 and ported to OpenBSD 4.5.
AUTHORS
This manual page was written by Robert Watson.
BUGS
The use of credentials hung from explicitly passed processes, and the
credential on curproc, and the cached credential from socket creation
time is inconsistent, and may lead to unexpected behaviour.
The caller may need to manually clear SS_ISCONNECTING if soconnect()
returns an error.
The MSG_DONTWAIT flag is not implemented for sosend().
This manual page does not describe how to register socket upcalls or
monitor a socket for readability/writability without using blocking I/O.
OpenBSD 4.9 January 29, 2009 OpenBSD 4.9
