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

FreeBSD Manual Pages

  
 
  

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

NAME
     socket -- kernel socket interface

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

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

     void
     soclose(struct socket *so);

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

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

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

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

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

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

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

     Except where otherwise indicated, socket functions	may sleep, and are not
     appropriate for use in an ithread(9) context or while holding non-sleep-
     able 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).

   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
     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 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
		   option.

     sopt_valsize  Size	of the argument	value in bytes.

   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.  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 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 ithread(9) 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), ng_ksocket(4), ithread(9),
     msleep(9),	ucred(9)

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

AUTHORS
     This manual page was written by Robert Watson.

BUGS
     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().

BSD			       December	14, 2006			   BSD

NAME | SYNOPSIS | DESCRIPTION | SEE ALSO | HISTORY | AUTHORS | BUGS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=socket&sektion=9&manpath=FreeBSD+9.0-RELEASE>

home | help