SOCKET(2)                 SYSTEM CALLS                  SOCKET(2)

NAME
     socket - create an endpoint for communication

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

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

DESCRIPTION
     socket() 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  address  family  for  the
     addresses supplied in later operations on the socket.  These
     families  are  defined  in  the include file <sys/socket.h>.
     The currently understood formats are

          PF_UNIX             (UNIX system internal protocols),
                              (AF_UNIX is a synonym)

          PF_INET             (ARPA Internet protocols)
                              (AF_INET is a synonym)

          PF_IMPLINK          (IMP "host at IMP" link layer).

     The socket has  the  indicated  type,  which  specifies  the
     semantics of communication.  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, unreliable mes-
     sages 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 protocol specific, and presently not
     implemented for any protocol family.  SOCK_RAW sockets  pro-
     vide  access  to  internal  network  interfaces.   The types
     SOCK_RAW, which is available only  to  the  super-user,  and
     SOCK_RDM,  for which no implementation currently exists, are
     not described here.

     The protocol specifies a particular protocol to be used with
     the  socket.  Normally only a single protocol exists to sup-
     port a particular socket type within a given  protocol  fam-
     ily.  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; see protocols(5).

     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 con-
     nection to another socket is created with a connect(2) call.
     Once connected, data may be transferred using  read(2V)  and
     write(2V)  calls  or some variant of the send(2) and recv(2)
     calls.  When a session has been completed a  close(2V),  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
     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  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  a  extended  period   (for
     instance  5  minutes).  A SIGPIPE signal is raised if a pro-
     cess sends 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(2V)
     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  correspondents  named  in  send(2) calls.  Datagrams are
     generally received with  recv(2),  which  returns  the  next
     datagram with its return address.

     An fcntl(2V) 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 notifi-
     cation of I/O events with SIGIO signals.

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

RETURN VALUES
     socket() returns a non-negative descriptor on  success.   On
     failure, it returns -1 and sets errno to indicate the error.

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

     EMFILE              The  per-process  descriptor  table   is
                         full.

     ENFILE              The system file table is full.

     ENOBUFS             Insufficient buffer space is  available.
                         The  socket cannot be created until suf-
                         ficient resources are freed.

     EPROTONOSUPPORT     The protocol type or the specified  pro-
                         tocol   is  not  supported  within  this
                         domain.

     EPROTOTYPE          The protocol is the wrong type  for  the
                         socket.

SEE ALSO
     accept(2), bind(2), close(2V), connect(2),  fcntl(2V),  get-
     sockname(2),  getsockopt(2),  ioctl(2), listen(2), read(2V),
     recv(2),  select(2),  send(2),  shutdown(2),  socketpair(2),
     write(2V), protocols(5)





















Sun Release 4.1   Last change: 21 January 1990                  3



