doc/html/ref/net-common-tcpip-manpages-socket.html

   1 <!-- Copyright (C) 2003 Red Hat, Inc.                                -->
   2 <!-- This material may be distributed only subject to the terms      -->
   3 <!-- and conditions set forth in the Open Publication License, v1.0  -->
   4 <!-- or later (the latest version is presently available at          -->
   5 <!-- http://www.opencontent.org/openpub/).                           -->
   6 <!-- Distribution of the work or derivative of the work in any       -->
   7 <!-- standard (paper) book form is prohibited unless prior           -->
   8 <!-- permission is obtained from the copyright holder.               -->
   9 <HTML
  10 ><HEAD
  11 ><TITLE
  12 >socket</TITLE
  13 ><meta name="MSSmartTagsPreventParsing" content="TRUE">
  14 <META
  15 NAME="GENERATOR"
  16 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
  17 "><LINK
  18 REL="HOME"
  19 TITLE="eCos Reference Manual"
  20 HREF="ecos-ref.html"><LINK
  21 REL="UP"
  22 TITLE="TCP/IP Library Reference"
  23 HREF="tcpip-library-reference.html"><LINK
  24 REL="PREVIOUS"
  25 TITLE="shutdown"
  26 HREF="net-common-tcpip-manpages-shutdown.html"><LINK
  27 REL="NEXT"
  28 TITLE="socketpair"
  29 HREF="net-common-tcpip-manpages-socketpair.html"></HEAD
  30 ><BODY
  31 CLASS="SECT1"
  32 BGCOLOR="#FFFFFF"
  33 TEXT="#000000"
  34 LINK="#0000FF"
  35 VLINK="#840084"
  36 ALINK="#0000FF"
  37 ><DIV
  38 CLASS="NAVHEADER"
  39 ><TABLE
  40 SUMMARY="Header navigation table"
  41 WIDTH="100%"
  42 BORDER="0"
  43 CELLPADDING="0"
  44 CELLSPACING="0"
  45 ><TR
  46 ><TH
  47 COLSPAN="3"
  48 ALIGN="center"
  49 >eCos Reference Manual</TH
  50 ></TR
  51 ><TR
  52 ><TD
  53 WIDTH="10%"
  54 ALIGN="left"
  55 VALIGN="bottom"
  56 ><A
  57 HREF="net-common-tcpip-manpages-shutdown.html"
  58 ACCESSKEY="P"
  59 >Prev</A
  60 ></TD
  61 ><TD
  62 WIDTH="80%"
  63 ALIGN="center"
  64 VALIGN="bottom"
  65 >Chapter 38. TCP/IP Library Reference</TD
  66 ><TD
  67 WIDTH="10%"
  68 ALIGN="right"
  69 VALIGN="bottom"
  70 ><A
  71 HREF="net-common-tcpip-manpages-socketpair.html"
  72 ACCESSKEY="N"
  73 >Next</A
  74 ></TD
  75 ></TR
  76 ></TABLE
  77 ><HR
  78 ALIGN="LEFT"
  79 WIDTH="100%"></DIV
  80 ><DIV
  81 CLASS="SECT1"
  82 ><H1
  83 CLASS="SECT1"
  84 ><A
  85 NAME="NET-COMMON-TCPIP-MANPAGES-SOCKET">socket</H1
  86 ><TABLE
  87 BORDER="5"
  88 BGCOLOR="#E0E0F0"
  89 WIDTH="70%"
  90 ><TR
  91 ><TD
  92 ><PRE
  93 CLASS="SCREEN"
  94 >SOCKET(2)                     System Calls Manual                    SOCKET(2)
  95
  96 NAME
  97      socket - create an endpoint for communication
  98
  99 SYNOPSIS
 100      #include &lt;sys/types.h&#62;
 101      #include &lt;sys/socket.h&#62;
 102
 103      int
 104      socket(int domain, int type, int protocol);
 105
 106 DESCRIPTION
 107      socket() creates an endpoint for communication and returns a descriptor.
 108
 109      The domain parameter specifies a communications domain within which com-
 110      munication will take place; this selects the protocol family which should
 111      be used.  These families are defined in the include file &lt;sys/socket.h&#62;.
 112      The currently understood formats are
 113
 114            AF_UNIX         (UNIX internal protocols),
 115            AF_INET         (ARPA Internet protocols),
 116            AF_INET6        (ARPA IPv6 protocols),
 117            AF_ISO          (ISO protocols),
 118            AF_NS           (Xerox Network Systems protocols),
 119            AF_IPX          (Internetwork Packet Exchange), and
 120            AF_IMPLINK      (IMP host at IMP link layer).
 121
 122      The socket has the indicated type, which specifies the semantics of com-
 123      munication.  Currently defined types are:
 124
 125            SOCK_STREAM
 126            SOCK_DGRAM
 127            SOCK_RAW
 128            SOCK_SEQPACKET
 129            SOCK_RDM
 130
 131      A SOCK_STREAM type provides sequenced, reliable, two-way connection based
 132      byte streams.  An out-of-band data transmission mechanism may be sup-
 133      ported.  A SOCK_DGRAM socket supports datagrams (connectionless, unreli-
 134      able messages of a fixed (typically small) maximum length).  A
 135      SOCK_SEQPACKET socket may provide a sequenced, reliable, two-way connec-
 136      tion-based data transmission path for datagrams of fixed maximum length;
 137      a consumer may be required to read an entire packet with each read system
 138      call.  This facility is protocol specific, and presently implemented only
 139      for PF_NS.  SOCK_RAW sockets provide access to internal network protocols
 140      and interfaces.  The types SOCK_RAW, which is available only to the supe-
 141      ruser, and SOCK_RDM, which is planned, but not yet implemented, are not
 142      described here.
 143
 144      The protocol specifies a particular protocol to be used with the socket.
 145      Normally only a single protocol exists to support a particular socket
 146      type within a given protocol family.  However, it is possible that many
 147      protocols may exist, in which case a particular protocol must be speci-
 148      fied in this manner.  The protocol number to use is particular to the
 149      communication domain in which communication is to take place; see
 150      protocols(5).  A value of 0 for protocol will let the system select an
 151      appropriate protocol for the requested socket type.
 152
 153      Sockets of type SOCK_STREAM are full-duplex byte streams, similar to
 154      pipes.  A stream socket must be in a connected state before any data may
 155      be sent or received on it.  A connection to another socket is created
 156      with a connect(2) call.  Once connected, data may be transferred using
 157      read(2) and write(2) calls or some variant of the send(2) and recv(2)
 158      calls.  When a session has been completed a close(2) may be performed.
 159      Out-of-band data may also be transmitted as described in send(2) and
 160      received as described in recv(2).
 161
 162      The communications protocols used to implement a SOCK_STREAM ensure that
 163      data is not lost or duplicated.  If a piece of data for which the peer
 164      protocol has buffer space cannot be successfully transmitted within a
 165      reasonable length of time, then the connection is considered broken and
 166      calls will indicate an error with -1 returns and with ETIMEDOUT as the
 167      specific code in the global variable errno.  The protocols optionally
 168      keep sockets ``warm'' by forcing transmissions roughly every minute in
 169      the absence of other activity.  An error is then indicated if no response
 170      can be elicited on an otherwise idle connection for a extended period
 171      (e.g., 5 minutes).  A SIGPIPE signal is raised if a process sends on a
 172      broken stream; this causes naive processes, which do not handle the sig-
 173      nal, to exit.
 174
 175      SOCK_SEQPACKET sockets employ the same system calls as SOCK_STREAM sock-
 176      ets.  The only difference is that read(2) calls will return only the
 177      amount of data requested, and any remaining in the arriving packet will
 178      be discarded.
 179
 180      SOCK_DGRAM and SOCK_RAW sockets allow sending of datagrams to correspon-
 181      dents named in send(2) calls.  Datagrams are generally received with
 182      recvfrom(2), which returns the next datagram with its return address.
 183
 184      An fcntl(2) call can be used to specify a process group to receive a
 185      SIGURG signal when the out-of-band data arrives.  It may also enable non-
 186      blocking I/O and asynchronous notification of I/O events via SIGIO.
 187
 188      The operation of sockets is controlled by socket level options.  These
 189      options are defined in the file &lt;sys/socket.h&#62;.  setsockopt(2) and
 190      getsockopt(2) are used to set and get options, respectively.
 191
 192 RETURN VALUES
 193      A -1 is returned if an error occurs, otherwise the return value is a
 194      descriptor referencing the socket.
 195
 196 ERRORS
 197      The socket() call fails if:
 198
 199      [EPROTONOSUPPORT]  The protocol type or the specified protocol is not
 200                         supported within this domain.
 201
 202      [EMFILE]           The per-process descriptor table is full.
 203
 204      [ENFILE]           The system file table is full.
 205
 206      [EACCES]           Permission to create a socket of the specified type
 207                         and/or protocol is denied.
 208
 209      [ENOBUFS]          Insufficient buffer space is available.  The socket
 210                         cannot be created until sufficient resources are
 211                         freed.
 212
 213 SEE ALSO
 214      accept(2), bind(2), connect(2), getsockname(2), getsockopt(2), ioctl(2),
 215      listen(2), poll(2), read(2), recv(2), select(2), send(2), setsockopt(2),
 216      shutdown(2), socketpair(2), write(2), getprotoent(3), netintro(4)
 217
 218      An Introductory 4.3 BSD Interprocess Communication Tutorial, reprinted in
 219      UNIX Programmer's Supplementary Documents Volume 1.
 220
 221      BSD Interprocess Communication Tutorial, reprinted in UNIX Programmer's
 222      Supplementary Documents Volume 1.
 223
 224 HISTORY
 225      The socket() function call appeared in 4.2BSD.
 226
 227 BSD                              June 4, 1993                              BSD
 228     </PRE
 229 ></TD
 230 ></TR
 231 ></TABLE
 232 ></DIV
 233 ><DIV
 234 CLASS="NAVFOOTER"
 235 ><HR
 236 ALIGN="LEFT"
 237 WIDTH="100%"><TABLE
 238 SUMMARY="Footer navigation table"
 239 WIDTH="100%"
 240 BORDER="0"
 241 CELLPADDING="0"
 242 CELLSPACING="0"
 243 ><TR
 244 ><TD
 245 WIDTH="33%"
 246 ALIGN="left"
 247 VALIGN="top"
 248 ><A
 249 HREF="net-common-tcpip-manpages-shutdown.html"
 250 ACCESSKEY="P"
 251 >Prev</A
 252 ></TD
 253 ><TD
 254 WIDTH="34%"
 255 ALIGN="center"
 256 VALIGN="top"
 257 ><A
 258 HREF="ecos-ref.html"
 259 ACCESSKEY="H"
 260 >Home</A
 261 ></TD
 262 ><TD
 263 WIDTH="33%"
 264 ALIGN="right"
 265 VALIGN="top"
 266 ><A
 267 HREF="net-common-tcpip-manpages-socketpair.html"
 268 ACCESSKEY="N"
 269 >Next</A
 270 ></TD
 271 ></TR
 272 ><TR
 273 ><TD
 274 WIDTH="33%"
 275 ALIGN="left"
 276 VALIGN="top"
 277 >shutdown</TD
 278 ><TD
 279 WIDTH="34%"
 280 ALIGN="center"
 281 VALIGN="top"
 282 ><A
 283 HREF="tcpip-library-reference.html"
 284 ACCESSKEY="U"
 285 >Up</A
 286 ></TD
 287 ><TD
 288 WIDTH="33%"
 289 ALIGN="right"
 290 VALIGN="top"
 291 >socketpair</TD
 292 ></TR
 293 ></TABLE
 294 ></DIV
 295 ></BODY
 296 ></HTML
 297 >