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

FreeBSD Manual Pages

  
 
  

home | help
socket(3SOCKET)		   Sockets Library Functions	       socket(3SOCKET)

NAME
       socket -	create an endpoint for communication

SYNOPSIS
       cc [ flag ... ] file ...	-lsocket -lnsl [ library ... ]
       #include	<sys/types.h>
       #include	<sys/socket.h>

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

DESCRIPTION
       The socket() function creates an	endpoint for communication and returns
       a descriptor.

       The domain parameter specifies a	 communications	 domain	 within	 which
       communication  will  take place;	this selects the protocol family which
       should be used. The protocol family generally is	the same  as  the  ad-
       dress  family  for  the	addresses  supplied in later operations	on the
       socket. These families are defined in the include file  <sys/socket.h>.
       There  must be an entry in the netconfig(4) file	for at least each pro-
       tocol family and	type required. If  protocol has	been specified,	but no
       exact  match  for  the tuplet family, type, protocol is found, then the
       first entry containing the specified family and type with zero for pro-
       tocol will be used. The currently understood formats are:

       PF_UNIX	       UNIX system internal protocols

       PF_INET		Internet Protocol Version 4 (IPv4)

       PF_INET6		Internet Protocol Version 6 (IPv6)

       PF_NCA	       Network Cache and Accelerator (NCA) protocols

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

       SOCK_STREAM
       SOCK_DGRAM
       SOCK_RAW
       SOCK_SEQPACKET
       SOCK_RDM

       A SOCK_STREAM type provides sequenced,  reliable,  two-way  connection-
       based  byte  streams. An	out-of-band data transmission mechanism	may be
       supported. A SOCK_DGRAM socket supports datagrams (connectionless,  un-
       reliable	 messages  of  a  fixed	 (typically  small) maximum length). A
       SOCK_SEQPACKET socket may provide a sequenced, reliable,	 two-way  con-
       nection-based  data  transmission  path	for datagrams of fixed maximum
       length; a consumer may be required to read an entire packet  with  each
       read system call. This facility is protocol specific, and presently not
       implemented for any protocol family. SOCK_RAW sockets provide access to
       internal	 network  interfaces.  The  types SOCK_RAW, which is available
       only to the superuser, and SOCK_RDM, for	which no  implementation  cur-
       rently exists, are not described	here.

       The  protocol parameter specifies a particular protocol to be used with
       the socket. Normally only a single protocol exists to support a partic-
       ular socket type	within a given protocol	family.	However, multiple pro-
       tocols may exist, in which case a particular protocol must be specified
       in this manner. The protocol number to use is particular	to the "commu-
       nication	domain"	in which communication is to take place. If a protocol
       is  specified  by  the  caller,	then it	will be	packaged into a	socket
       level option request and	sent to	the underlying protocol	layers.

       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 may
       be sent or received on it. A connection to another  socket  is  created
       with  a	connect(3SOCKET) call. Once connected, data may	be transferred
       using read(2) and write(2) calls	or some	variant	of  the	 send(3SOCKET)
       and  recv(3SOCKET) calls. When a	session	has been completed, a close(2)
       may be performed. Out-of-band data may also be transmitted as described
       on  the	send(3SOCKET)  manual  page  and  received as described	on the
       recv(3SOCKET) manual page.

       The communications protocols used to  implement	a  SOCK_STREAM	insure
       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	proto-
       cols 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  a  extended	 period	(for instance 5	minutes). A  SIGPIPE signal is
       raised if a thread sends	on a broken stream;  this  causes  naive  pro-
       cesses, 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.

       SOCK_DGRAM and SOCK_RAW sockets allow datagrams to be  sent  to	corre-
       spondents  named	 in sendto(3SOCKET) calls. Datagrams are generally re-
       ceived with recvfrom(3SOCKET), which returns the	next datagram with its
       return address.

       An  fcntl(2)  call  can be used to specify a process group to receive a
       SIGURG signal when the out-of-band data arrives.	 It  can  also	enable
       non-blocking I/O.

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

RETURN VALUES
       A  -1  is  returned if an error occurs. Otherwise the return value is a
       descriptor referencing the socket.

ERRORS
       The socket() function will fail if:

       EACCES		       Permission to create a socket of	the  specified
			       type or protocol	is denied.

       EAFNOSUPPORT	       The  specified  address family is not supported
			       by the protocol family.

       EMFILE		       The per-process descriptor table	is full.

       ENOMEM		       Insufficient user memory	is available.

       ENOSR		       There  were  insufficient   STREAMS   resources
			       available to complete the operation.

       EPFNOSUPPORT	       The specified protocol family is	not supported.

       EPROTONOSUPPORT	       The  protocol  type is not supported by the ad-
			       dress family.

       EPROTOTYPE	       The socket type is not supported	by the	proto-
			       col.

ATTRIBUTES
       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |MT-Level		     |Safe			   |
       +-----------------------------+-----------------------------+

SEE ALSO
       nca(1),	 close(2),   fcntl(2),	 ioctl(2),   read(2),  write(2),   ac-
       cept(3SOCKET), bind(3SOCKET),  connect(3SOCKET),	 getsockname(3SOCKET),
       getsockopt(3SOCKET),  in.h(3HEAD),listen(3SOCKET),  recv(3SOCKET), set-
       sockopt(3SOCKET),  send(3SOCKET),  shutdown(3SOCKET),  socket.h(3HEAD),
       socketpair(3SOCKET), attributes(5)

SunOS 5.10			  21 Nov 2003		       socket(3SOCKET)

NAME | SYNOPSIS | DESCRIPTION | RETURN VALUES | ERRORS | ATTRIBUTES | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=socket&sektion=3socket&manpath=SunOS+5.10>

home | help