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

FreeBSD Manual Pages


home | help
socket(2)							     socket(2)

       socket -	create an endpoint for communication

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

       s = socket(af, type, protocol)
       int s, af, type,	protocol;

       The  system  call  creates  an endpoint for communication and returns a

       The operation of	sockets	is controlled by socket-level options, defined
       in  the	file  and explained in the section, Socket-level Options.  The
       calls and are used to set and get options.

       The af parameter	specifies an address format.  Addresses	 specified  in
       later  operations  using	 the socket are	interpreted according to these
       formats.	 The formats are defined in the	include	file

       AF_UNIX	 UNIX	path   names   AF_INET	 ARPA	 Internet    addresses
       AF_IMPLINK     IMP "host	at IMP"	addresses AF_DLI	 For access to
       broadcast devices (Ethernet)

       The type	 argument  specifies  the  semantics  of  communication.   The
       defined types are:


       The  SOCK_STREAM	and SOCK_DGRAM types are available only	if your	system
       includes	the TCP/IP network.  For example, if you can use  the  command
       to  log	in  to a remote	ULTRIX node, your system supports these	socket

       A SOCK_STREAM type provides sequenced, reliable,	2-way-connection-based
       byte  streams  with  an	out-of-band  data  transmission	 mechanism.  A
       SOCK_DGRAM socket supports datagrams (connectionless,  unreliable  mes-
       sages of	a fixed	maximum	length,	typically small).

       SOCK_RAW	 sockets provide access	to internal network interfaces and are
       available only to the super-user.

       The SOCK_SEQPACKET type is the socket protocol to request when you want
       to communicate with other Digital systems using DECnet.

       Socket types are	discussed further in following sections.

       The  protocol  argument	specifies  the	protocol  to  be used with the
       socket.	Normally, only a single	protocol exists	to support a  particu-
       lar  socket type	using a	given address format.  However,	it is possible
       that many protocols may exist, in which case a particular protocol must
       be  specified in	this manner.  The protocol number to use is particular
       to the communication domain in which communication is  to  take	place.
       For further information,	see and

       Sockets	of  type  SOCK_STREAM are full-duplex byte streams, similar to
       pipes.  A stream	socket must be in a connected state  before  any  data
       can  be sent or received	on it.	A connection to	another	socket is cre-
       ated with a call.  Once connected, data can be  transferred  using  and
       calls  or  some variant of the and calls.  When a session has been com-
       pleted, a may be	performed.  Out-of-band	data can also  be  transmitted
       as described in and received as described in

       The  communications  protocols  used  to	implement a SOCK_STREAM	ensure
       that data is not	lost or	duplicated.  If	a piece	of data	for which  the
       peer  protocol  has  buffer  space  cannot  be successfully transmitted
       within a	reasonable length of time, then	the connection	is  considered
       broken  and  calls  will	 indicate  an  error  with -1 returns and with
       ETIMEDOUT as the	specific code in the global variable errno.  The  pro-
       tocols  optionally keep sockets "warm" by forcing transmissions roughly
       every minute in the absence of other activity.  An error	is then	 indi-
       cated  if  no  response can be elicited on an otherwise idle connection
       for an extended period (for example, 5 minutes).	 A SIGPIPE  signal  is
       raised  if  a  process  sends on	a broken stream; this causes processes
       that do not handle the signal to	exit.

Socket Types SOCK_DGRAM	and SOCK_RAW
       SOCK_DGRAM and SOCK_RAW sockets allow sending of	 datagrams  to	corre-
       spondents  named	in calls.  It is also possible to receive datagrams at
       these sockets with

       An call can be used to specify a	process	group to receive a SIGURG sig-
       nal when	the out-of-band	data arrives.

       SOCK_DGRAM sockets are the only type of socket allowed by the Data Link

       SOCK_SEQPACKET sockets are similar to datagrams except  that  they  are
       guaranteed to be	received in the	sequence that they are sent.  They are
       also guaranteed to be error-free.

Socket-Level Options
       The operation of	sockets	is controlled by socket-level options.	 These
       options	are defined in the file, The calls and are used	to set and get

       Options other than SO_LINGER take an integer parameter that  should  be
       nonzero,	 if  the  option is to be enabled, or zero (0),	if it is to be
       disabled.  SO_LINGER uses a ``linger'' structure	parameter  defined  in
       This structure specifies	the desired state of the option	and the	linger
       interval	(see the following).

       SO_DEBUG		     Turn  on  recording  of   debugging   information
       SO_REUSEADDR	       Allow	local	address	  reuse	  SO_KEEPALIVE
       Keep connections	alive SO_DONTROUTE	   Do  not  apply  routing  on
       outgoing	 messages SO_LINGER	       Linger on close if data present
       SO_BROADCAST	    Permit sending of broadcast	messages SO_ACCEPTCONN
       Socket  has had listen()	SO_USELOOPBACK	     Bypass hardware when pos-
       sible SO_OOBINLINE	  Leave	received OOB data in line

SO_DEBUG enables debugging in the underlying protocol modules.

SO_REUSEADDR indicates the rules used in validating addresses  supplied	 in  a
call should allow reuse	of local addresses.

SO_KEEPALIVE  enables  the  periodic  transmission  of messages	on a connected
socket.	 Should	the connected party fail to respond  to	 these	messages,  the
connection  is	considered  broken and processes using the socket are notified
through	a SIGIO	signal.	 Note that in order to receive signals on a socket the
program	 must  first  call with	a F_SETOWN request to set the process group of
the process to receive the signal, and with  a	F_SETFL	 request  to  set  the
FASYNC flag, which enables the SIGIO signal to be sent.

SO_DONTROUTE indicates that outgoing messages should bypass the	standard rout-
ing facilities.	 Instead, messages are directed	 to  the  appropriate  network
interface, according to	the network portion of the destination address.

SO_LINGER  controls  the  actions taken	when unsent messages are queued	on the
socket and a is	performed.  When using the  to	set  the  linger  values,  the
option	value  for the SO_LINGER command is the	address	of a linger structure:
struct	linger {
	int	l_onoff;       /* option on/off	*/
	int	l_linger;      /* linger time */ };  If	 the  socket  promises
reliable  delivery  of	data  and  l_onoff  is	nonzero, the system blocks the
process	on the attempt until it	is able	to  transmit  the  data	 or  until  it
decides	it is unable to	deliver	the information.  A timeout period, termed the
linger interval, is specified in l_linger in seconds.  If l_onoff  is  set  to
zero  (0)  and	a  is  issued, the system processes the	close in a manner that
allows the process to continue as quickly as possible.

SO_BROADCAST is	used to	enable or disable broadcasting on the socket.

Return Values
       A -1 is returned	if an error occurs.   Otherwise, the return value is a
       descriptor to be	used in	other calls to refer to	the socket.

       The call	fails if:

		 The specified address family is not supported in this version
		 of the	system.

		 The specified socket type is not supported  in	 this  address

		 The specified protocol	is not supported.

		 Request for a type of socket for which	there is no supporting

       [EMFILE]	 The per-process descriptor table is full.

       [ENOBUFS] No buffer space is available.	The socket cannot be  created.

See Also
       accept(2),  bind(2),  close(2),	connect(2),  fcntl(2), getsockname(2),
       getsockopt(2),  ioctl(2),  listen(2),  read  (2),  recv(2),  select(2),
       send(2),	 setsockopt(2),	shutdown(2), socketpair(2), protocols(5), ser-
       vices(5), write(2),
       Guide to	Network	Programming,
       Guide to	the Data Link Interface


Name | Syntax | Description | Arguments | Socket Type SOCK_STREAM | Socket Types SOCK_DGRAM and SOCK_RAW | Socket Type SOCK_SEQPACKET | Socket-Level Options | Return Values | Diagnostics | See Also

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

home | help