SOCREATE(9) | Kernel Developer's Manual | SOCREATE(9)

# NAME

`sobind`, `soclose`, `soconnect`, `socreate`, `soreceive`, `so_upcall`, `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 flags);

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, socklen_t controllen);

void
`(*so_upcall)`(struct socket *so, caddr_t arg, int waitflag);

int
`sosetopt`(struct socket *so, int level, int optname, struct mbuf *m);

int
`sogetopt`(struct socket *so, int level, int optname, struct mbuf *m);

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 m is either a pointer to a prefilled mbuf or a pointer to an mbuf to retrieve 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. If mp0 is not `NULL`, uio must still be passed with uio_resid set to specify the maximum amount of data to be returned to the caller via an mbuf chain. 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 up to controllen bytes of control data in 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.

When the `so_upcall`() function pointer is not `NULL`, it is called when `soreceive`() matches an incoming connection.

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 ALSO

bind(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.

This manual page does not describe how to register socket upcalls or monitor a socket for readability/writability without using blocking I/O.

September 11, 2022 | Debian