Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
SOCKET(9)	       FreeBSD Kernel Developer's Manual	     SOCKET(9)

     socket -- kernel socket interface

     #include <sys/socket.h>
     #include <sys/socketvar.h>

     soabort(struct socket *so);

     soaccept(struct socket *so, struct	sockaddr **nam);

     socheckuid(struct socket *so, uid_t uid);

     sobind(struct socket *so, struct sockaddr *nam, struct thread *td);

     soclose(struct socket *so);

     soconnect(struct socket *so, struct sockaddr *nam,	struct thread *td);

     socreate(int dom, struct socket **aso, int	type, int proto,
	 struct	ucred *cred, struct thread *td);

     sodisconnect(struct socket	*so);

     sodtor_set(struct socket *so, void	(*func)(struct socket *));

     struct sockaddr *
     sodupsockaddr(const struct	sockaddr *sa, int mflags);

     sofree(struct socket *so);

     sohasoutofband(struct socket *so);

     solisten(struct socket *so, int backlog, struct thread *td);

     solisten_proto(struct socket *so, int backlog);

     solisten_proto_check(struct socket	*so);

     struct socket *
     sonewconn(struct socket *head, int	connstatus);

     sopoll(struct socket *so, int events, struct ucred	*active_cred,
	 struct	thread *td);

     sopoll_generic(struct socket *so, int events, struct ucred	*active_cred,
	 struct	thread *td);

     soreceive(struct socket *so, struct sockaddr **psa, struct	uio *uio,
	 struct	mbuf **mp0, struct mbuf	**controlp, int	*flagsp);

     soreceive_stream(struct socket *so, struct	sockaddr **paddr,
	 struct	uio *uio, struct mbuf **mp0, struct mbuf **controlp,
	 int *flagsp);

     soreceive_dgram(struct socket *so,	struct sockaddr	**paddr,
	 struct	uio *uio, struct mbuf **mp0, struct mbuf **controlp,
	 int *flagsp);

     soreceive_generic(struct socket *so, struct sockaddr **paddr,
	 struct	uio *uio, struct mbuf **mp0, struct mbuf **controlp,
	 int *flagsp);

     soreserve(struct socket *so, u_long sndcc,	u_long rcvcc);

     sorflush(struct socket *so);

     sosend(struct socket *so, struct sockaddr *addr, struct uio *uio,
	 struct	mbuf *top, struct mbuf *control, int flags,
	 struct	thread *td);

     sosend_dgram(struct socket	*so, struct sockaddr *addr, struct uio *uio,
	 struct	mbuf *top, struct mbuf *control, int flags,
	 struct	thread *td);

     sosend_generic(struct socket *so, struct sockaddr *addr, struct uio *uio,
	 struct	mbuf *top, struct mbuf *control, int flags,
	 struct	thread *td);

     soshutdown(struct socket *so, int how);

     sotoxsocket(struct	socket *so, struct xsocket *xso);

     soupcall_clear(struct socket *so, int which);

     soupcall_set(struct socket	*so, int which,
	 int (*func)(struct socket *, void *, int), void *arg);

     sowakeup(struct socket *so, struct	sockbuf	*sb);

     #include <sys/sockopt.h>

     sosetopt(struct socket *so, struct	sockopt	*sopt);

     sogetopt(struct socket *so, struct	sockopt	*sopt);

     sooptcopyin(struct	sockopt	*sopt, void *buf, size_t len, size_t minlen);

     sooptcopyout(struct sockopt *sopt,	const void *buf, size_t	len);

     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	appro-
     priate 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.  Some portions of
     the kernel	API exist only to implement the	user API, and are not expected
     to	be used	by kernel code.	 The portions of the socket API	used by	socket
     consumers and implementations of network protocols	will differ; some rou-
     tines are only useful for protocol	implementors.

     Except where otherwise indicated, socket functions	may sleep, and are not
     appropriate for use in an interrupt thread	context	or while holding non-
     sleepable kernel locks.

   Creating and	Destroying Sockets
     A new socket may be created using socreate().  As with socket(2), argu-
     ments specify the requested domain, type, and protocol via	dom, type, and
     proto.  The socket	is returned via	aso on success.	 In addition, the cre-
     dential 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 creden-
     tial for some protocols (such as raw sockets).

     Sockets may be closed and freed using soclose(), which has	similar	seman-
     tics to close(2).

     In	certain	circumstances, it is appropriate to destroy a socket without
     waiting for it to disconnect, for which soabort() is used.	 This is only
     appropriate for incoming connections which	are in a partially connected
     state.  It	must be	called on an unreferenced socket, by the thread	which
     removed the socket	from its listen	queue, to prevent races.  It will call
     into protocol code, so no socket locks may	be held	over the call.	The
     caller of soabort() is responsible	for setting the	VNET context.  The
     normal path to freeing a socket is	sofree(), which	handles	reference
     counting on the socket.  It should	be called whenever a reference is re-
     leased, and also whenever reference flags are cleared in socket or	proto-
     col code.	Calls to sofree() should not be	made from outside the socket
     layer; outside callers should use soclose() instead.

   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 us-
     ing 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 opera-
     tion 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

     A call to sodisconnect() disconnects the socket without closing it.

     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.

     Sockets are transitioned from non-listening status	to listening with

   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 second	argument in both sogetopt() and	sosetopt() is the sopt pointer
     to	a struct sopt describing the socket option operation.  The caller-al-
     located structure must be zeroed, and then	have its fields	initialized to
     specify socket option operation arguments:

     sopt_dir	   Set to SOPT_SET or SOPT_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

     sopt_valsize  Size	of the argument	value in bytes.

   Socket Upcalls
     In	order for the owner of a socket	to be notified when the	socket is
     ready to send or receive data, an upcall may be registered	on the socket.
     The upcall	is a function that will	be called by the socket	framework when
     a socket buffer associated	with the given socket is ready for reading or
     writing.  soupcall_set() is used to register a socket upcall.  The	func-
     tion func is registered, and the pointer arg will be passed as its	second
     argument when it is called	by the framework.  The possible	values for
     which are SO_RCV and SO_SND, which	register upcalls for receive and send
     events, respectively.  The	upcall function	func() must return either
     SU_OK or SU_ISCONNECTED, depending	on whether or not a call to
     soisconnected should be made by the socket	framework after	the upcall re-
     turns.  The upcall	func cannot call soisconnected itself due to lock or-
     dering with the socket buffer lock.  Only SO_RCV upcalls should return
     SU_ISCONNECTED.  When a SO_RCV upcall returns SU_ISCONNECTED, the upcall
     will be removed from the socket.

     Upcalls are removed from their socket by soupcall_clear().	 The which ar-
     gument again specifies whether the	sending	or receiving upcall is to be
     cleared, with SO_RCV or SO_SND.

   Socket Destructor Callback
     A kernel system can use the sodtor_set() function to set a	destructor for
     a socket.	The destructor is called when the socket is about to be	freed.
     The destructor is called before the protocol detach routine.  The de-
     structor can serve	as a callback to initiate additional cleanup actions.

   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
     awaiting for data if none is ready	to read.  Data may be retrieved	di-
     rectly 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 al-
     ways 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, avoid-
     ing 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 ar-
     gument, which may result in an implicit connect if	supported by the pro-
     tocol.  The caller	may optionally send control data mbufs via a non-NULL
     control argument.	Flags may be passed to sosend()	using the flags	argu-
     ment, and use the same flag name space as the sendmsg(2) system call.

     Kernel callers running in an interrupt thread 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.

     A socket can be queried for readability, writability, out-of-band data,
     or	end-of-file using sopoll().  The possible values for events are	as for
     poll(2), with symbolic values POLLIN, POLLPRI, POLLOUT, POLLRDNORM,
     POLLWRNORM, POLLRDBAND, and POLLINGEOF taken from <sys/poll.h>.

     Calls to soaccept() pass through to the protocol's	accept routine to ac-
     cept an incoming connection.

   Socket Utility Functions
     The uid of	a socket's credential may be compared against a	uid with

     A copy of an existing struct sockaddr may be made using sodupsockaddr().

     Protocol implementations notify the socket	layer of the arrival of	out-
     of-band data using	sohasoutofband(), so that the socket layer can notify
     socket consumers of the available data.

     An	"external-format" version of a struct socket can be created using
     sotoxsocket(), suitable for isolating user	code from changes in the ker-
     nel structure.

   Protocol Implementations
     Protocols must supply an implementation for solisten(); such protocol im-
     plementations can call back into the socket layer using
     solisten_proto_check() and	solisten_proto() to check and set the socket-
     layer listen state.  These	callbacks are provided so that the protocol
     implementation can	order the socket layer and protocol locks as neces-
     sary.  Protocols must supply an implementation of soreceive(); the	func-
     tions soreceive_stream(), soreceive_dgram(), and soreceive_generic() are
     supplied for use by such implementations.

     Protocol implementations can use sonewconn() to create a socket and at-
     tach protocol state to that socket.  This can be used to create new sock-
     ets available for soaccept() on a listen socket.  The returned socket has
     a reference count of zero.

     Protocols must supply an implementation for sopoll(); sopoll_generic() is
     provided for the use by protocol implementations.

     The functions sosend_dgram() and sosend_generic() are supplied to assist
     in	protocol implementations of sosend().

     When a protocol creates a new socket structure, it	is necessary to	re-
     serve socket buffer space for that	socket,	by calling soreserve().	 The
     rough inverse of this reservation is performed by sorflush(), which is
     called automatically by the socket	framework.

     When a protocol needs to wake up threads waiting for the socket to	become
     ready to read or write, variants of sowakeup() are	used.  The sowakeup()
     function should not be called directly by protocol	code, instead use the
     wrappers sorwakeup(), sorwakeup_locked(), sowwakeup(), and
     sowwakeup_locked()	for readers and	writers, with the corresponding	socket
     buffer lock not already locked, or	already	held, respectively.

     The functions sooptcopyin() and sooptcopyout() are	useful for transfer-
     ring struct sockopt data between user and kernel code.

     bind(2), close(2),	connect(2), getsockopt(2), recv(2), send(2),
     setsockopt(2), shutdown(2), socket(2), ng_ksocket(4), intr_event(9),
     msleep(9),	ucred(9)

     The socket(2) system call appeared	in 4.2BSD.  This manual	page was in-
     troduced in FreeBSD 7.0.

     This manual page was written by Robert Watson and
     Benjamin Kaduk.

     The use of	explicitly passed credentials, credentials hung	from explic-
     itly passed threads, the credential on curthread, and the cached creden-
     tial from socket creation time is inconsistent, and may lead to unex-
     pected 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() re-
     turns 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 mon-
     itor 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 interac-
     tions when	sorele() is last called	after soclose().

FreeBSD	13.0		       September 6, 2022		  FreeBSD 13.0


Want to link to this manual page? Use this URL:

home | help