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

FreeBSD Manual Pages


home | help
SOCKET(2)		   Linux Programmer's Manual		     SOCKET(2)

       socket -	create an endpoint for communication

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

       int socket(int domain, int type,	int protocol);

       Socket  creates an endpoint for communication and returns a descriptor.

       The domain parameter specifies a	communication domain; this selects the
       protocol	 family	 which will be used for	communication.	These families
       are  defined  in	 <sys/socket.h>.   The	currently  understood  formats

       Name		  Purpose			   Man page
       PF_UNIX,PF_LOCAL	  Local	communication		   unix(7)
       PF_INET		  IPv4 Internet	protocols	   ip(7)
       PF_INET6		  IPv6 Internet	protocols
       PF_IPX		  IPX -	Novell protocols
       PF_NETLINK	  Kernel user interface	device	   netlink(7)
       PF_X25		  ITU-T	X.25 / ISO-8208	protocol   x25(7)
       PF_AX25		  Amateur radio	AX.25 protocol
       PF_ATMPVC	  Access to raw	ATM PVCs
       PF_APPLETALK	  Appletalk			   ddp(7)
       PF_PACKET	  Low level packet interface	   packet(7)

       The  socket  has	 the indicated type, which specifies the communication
       semantics.  Currently defined types are:

	      Provides sequenced,  reliable,  two-way,	connection-based  byte
	      streams.	An out-of-band data transmission mechanism may be sup-

	      Supports datagrams (connectionless,  unreliable  messages	 of  a
	      fixed maximum length).

	      Provides	a  sequenced,  reliable, two-way connection-based data
	      transmission path	for datagrams of fixed maximum length; a  con-
	      sumer is required	to read	an entire packet with each read	system

	      Provides raw network protocol access.

	      Provides a reliable  datagram  layer  that  does	not  guarantee

	      Obsolete	and should not be used in new programs;	see packet(7).

       Some socket types may not be implemented	by all protocol	families;  for
       example,	SOCK_SEQPACKET is not implemented for AF_INET.

       The  protocol  specifies	 a  particular	protocol  to  be used with the
       socket.	Normally only a	single protocol	exists to support a particular
       socket  type  within  a given protocol family, in which a case protocol
       can be specified	as 0.  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 specific to  the	"communication
       domain" in which	communication is to take place;	see protocols(5).  See
       getprotoent(3) on how to	map protocol name strings to protocol numbers.

       Sockets	of  type  SOCK_STREAM are full-duplex byte streams, similar to
       pipes.  They do not preserve record boundaries. A stream	socket must be
       in  a connected state before any	data may be sent or received on	it.  A
       connection to another socket is created with a connect(2)  call.	  Once
       connected,  data	may be transferred using read(2) and write(2) calls or
       some variant of the send(2) and recv(2) calls.  When a session has been
       completed  a  close(2)  may be performed.  Out-of-band data may also be
       transmitted as described	 in  send(2)  and  received  as	 described  in

       The  communications protocols which 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	to  be
       dead.   When  SO_KEEPALIVE is enabled on	the socket the protocol	checks
       in a protocol-specific manner if	the other end is still alive.  A  SIG-
       PIPE  signal  is	 raised	 if  a	process	 sends or receives on a	broken
       stream; this causes naive processes, which do not handle	the signal, to
       exit.	SOCK_SEQPACKET	 sockets  employ  the  same  system  calls  as
       SOCK_STREAM sockets.  The only difference is that  read(2)  calls  will
       return  only  the  amount  of  data requested, and any remaining	in the
       arriving	packet will be	discarded.  Also  all  message	boundaries  in
       incoming	datagrams are preserved.

       SOCK_DGRAM  and	SOCK_RAW  sockets allow	sending	of datagrams to	corre-
       spondents named in send(2) calls.   Datagrams  are  generally  received
       with  recvfrom(2),  which  returns  the	next  datagram with its	return

       SOCK_PACKET is an obsolete socket type to receive raw packets  directly
       from the	device driver. Use packet(7) instead.

       An  fcntl(2) call with the the F_SETOWN argument	can be used to specify
       a process group to receive a SIGURG signal when	the  out-of-band  data
       arrives	or  SIGPIPE  signal when a SOCK_STREAM connection breaks unex-
       pectedly.  It may also be used to set the process or process group that
       receives	the I/O	and asynchronous notification of I/O events via	SIGIO.
       Using F_SETOWN is equivalent to an ioctl(2) call	with the FIOSETOWN  or
       SIOCSPGRP argument.

       When  the  network  signals  an	error condition	to the protocol	module
       (e.g.  using a ICMP message for IP) the pending error flag is  set  for
       the  socket.   The  next	operation on this socket will return the error
       code of the pending error. For some protocols it	is possible to	enable
       a  per-socket  error  queue  to retrieve	detailed information about the
       error; see IP_RECVERR in	ip(7).

       The operation of	sockets	is controlled by socket	level options.	 These
       options are defined in <sys/socket.h>.  The functions setsockopt(2) and
       getsockopt(2) are used to set and get options, respectively.

       -1 is returned if an error occurs; otherwise  the  return  value	 is  a
       descriptor referencing the socket.

	      The  protocol  type  or  the specified protocol is not supported
	      within this domain.

	      The implementation does not support the specified	 address  fam-

       ENFILE Not enough kernel	memory to allocate a new socket	structure.

       EMFILE Process file table overflow.

       EACCES Permission  to create a socket of	the specified type and/or pro-
	      tocol is denied.

	      Insufficient memory is available.	 The socket cannot be  created
	      until sufficient resources are freed.

       EINVAL Unknown protocol,	or protocol family not available.

       Other errors may	be generated by	the underlying protocol	modules.

       4.4BSD  (the socket function call appeared in 4.2BSD). Generally	porta-
       ble to/from non-BSD systems supporting clones of	the BSD	 socket	 layer
       (including System V variants).

       The  manifest  constants	 used  under BSD 4.* for protocol families are
       PF_UNIX,	PF_INET, etc., while AF_UNIX etc. are used for	address	 fami-
       lies.  However, already the BSD man page	promises: "The protocol	family
       generally is the	same as	the address family", and subsequent  standards
       use AF_*	everywhere.

       SOCK_UUCP is not	implemented yet.

       accept(2),  bind(2),  connect(2),  fcntl(2),  getpeername(2),  getsock-
       name(2),	 getsockopt(2),	  ioctl(2),   listen(2),   read(2),   recv(2),
       select(2),   send(2),  shutdown(2),  socketpair(2),  write(2),  getpro-
       toent(3), ip(7),	socket(7), tcp(7), udp(7), unix(7)

       "An  Introductory  4.3  BSD  Interprocess  Communication	 Tutorial"  is
       reprinted in UNIX Programmer's Supplementary Documents Volume 1.

       "BSD Interprocess Communication Tutorial" is reprinted in UNIX Program-
       mer's Supplementary Documents Volume 1.

Linux Man Page			  1999-04-24			     SOCKET(2)


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

home | help