home | help
SOCKET(2)		       System Calls Manual		       SOCKET(2)

NAME
     socket -- create an endpoint for communication

LIBRARY
     Standard C Library (libc, -lc)

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

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

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

     The domain argument specifies a communications domain within which communi-
     cation will take place; this selects the protocol family  which  should  be
     used.   These families are defined in the include file <sys/socket.h>.  The
     currently understood formats are:

	   PF_LOCAL	   Host-internal protocols, formerly called PF_UNIX,
	   PF_UNIX	   Host-internal protocols, deprecated, use PF_LOCAL,
	   PF_INET	   Internet version 4 protocols,
	   PF_PUP	   PUP protocols, like BSP,
	   PF_APPLETALK    AppleTalk protocols,
	   PF_ROUTE	   Internal Routing protocol,
	   PF_LINK	   Link layer interface,
	   PF_IPX	   Novell Internet Packet eXchange protocol,
	   PF_RTIP	   Help Identify RTIP packets,
	   PF_PIP	   Help Identify PIP packets,
	   PF_ISDN	   Integrated Services Digital Network,
	   PF_KEY	   Internal key-management function,
	   PF_INET6	   Internet version 6 protocols,
	   PF_NATM	   Native ATM access,
	   PF_ATM	   ATM,
	   PF_NETGRAPH	   Netgraph sockets

     The socket has the indicated type, which specifies the semantics of  commu-
     nication.	Currently defined types are:

	   SOCK_STREAM	   Stream socket,
	   SOCK_DGRAM	   Datagram socket,
	   SOCK_RAW	   Raw-protocol interface,
	   SOCK_RDM	   Reliably-delivered packet,
	   SOCK_SEQPACKET  Sequenced packet stream

     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, unreliable messages
     of a fixed (typically small) maximum length).  A SOCK_SEQPACKET socket  may
     provide  a  sequenced, reliable, two-way connection-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 proto-
     col specific, and presently unimplemented.  SOCK_RAW sockets provide access
     to internal network protocols and interfaces.  The types SOCK_RAW, which is
     available only to the super-user, and SOCK_RDM, which is planned,	but  not
     yet implemented, are not described here.

     The  protocol  argument 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.  However, it is possible that
     many protocols may exist, in which case a particular protocol must be spec-
     ified in this manner.  The protocol number to  use  is  particular  to  the
     "communication  domain" in which communication is to take place; see proto-
     cols(5).

     The protocol argument may be set to zero (0) to request the default  imple-
     mentation of a socket type for the protocol, if any.

     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 con-
     nect(2) system call.  Once connected, data may be transferred using read(2)
     and write(2) calls or some variant of the send(2)	and  recv(2)  functions.
     (Some protocol families, such as the Internet family, support the notion of
     an "implied connect", which permits data to be sent piggybacked onto a con-
     nect  operation  by  using  the sendto(2) system call.)  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 recv(2).

     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 pro-
     tocol has buffer space cannot be successfully transmitted within a  reason-
     able  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 protocols optionally keep sockets
     "warm" by forcing transmissions roughly every  minute  in	the  absence  of
     other  activity.  An error is then indicated if no response can be elicited
     on an otherwise idle connection for an extended period  (e.g.  5  minutes).
     By  default,  a  SIGPIPE  signal  is  raised if a process sends on a broken
     stream, but this behavior may be inhibited via setsockopt(2).

     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 sending of datagrams to correspon-
     dents named in  send(2)  calls.   Datagrams  are  generally  received  with
     recvfrom(2), which returns the next datagram with its return address.

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

     The operation of sockets is controlled by socket level options.  These  op-
     tions  are  defined in the file <sys/socket.h>.  The setsockopt(2) and get-
     sockopt(2) system calls are used to set and get options, respectively.

RETURN VALUES
     A -1 is returned if an error occurs, otherwise the return value  is  a  de-
     scriptor referencing the socket.

ERRORS
     The socket() system call fails if:

     [EPROTONOSUPPORT]	The  protocol type or the specified protocol is not sup-
			ported within this domain.

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

     [ENFILE]		The system file table is full.

     [EACCES]		Permission to create a	socket	of  the  specified  type
			and/or protocol is denied.

     [ENOBUFS]		Insufficient buffer space is available.  The socket can-
			not be created until sufficient resources are freed.

     [EPERM]		User  has  insufficient  privileges to carry out the re-
			quested operation.

SEE ALSO
     accept(2), bind(2), connect(2),  getpeername(2),  getsockname(2),	getsock-
     opt(2),  ioctl(2),  listen(2),  read(2), recv(2), select(2), send(2), shut-
     down(2), socketpair(2), write(2), getprotoent(3), netgraph(4), protocols(5)

     "An Introductory 4.3 BSD Interprocess Communication Tutorial", PS1, 7.

     "BSD Interprocess Communication Tutorial", PS1, 8.

HISTORY
     The socket() system call appeared in 4.2BSD.

FreeBSD 9.0			 January 5, 2009		       SOCKET(2)

home | help