<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE erlref SYSTEM "erlref.dtd">

<erlref>
  <header>
    <copyright>
      <year>2018</year><year>2020</year>
      <holder>Ericsson AB. All Rights Reserved.</holder>
    </copyright>
    <legalnotice>
      Licensed under the Apache License, Version 2.0 (the "License");
      you may not use this file except in compliance with the License.
      You may obtain a copy of the License at
 
          http://www.apache.org/licenses/LICENSE-2.0

      Unless required by applicable law or agreed to in writing, software
      distributed under the License is distributed on an "AS IS" BASIS,
      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
      See the License for the specific language governing permissions and
      limitations under the License.

    </legalnotice>

    <title>socket</title>
    <prepared></prepared>
    <docno></docno>
    <date></date>
    <rev></rev>
    <file>socket.xml</file>
  </header>
  <module since="OTP 22.0">socket</module>
  <modulesummary>Socket interface.</modulesummary>
  <description>
    <p>This module provides an API for network socket.
    Functions are provided to create, delete and manipulate the sockets
    as well as sending and receiving data on them. </p>
    <p>The intent is that it shall be as "close as possible" to the OS
    level socket interface. The only significant addition is that some of
    the functions,
    e.g. <seemfa marker="#recv/3"><c>recv/3</c></seemfa>, 
    have a time-out argument. </p>
    <marker id="asynchronous-call"/>
    <note>
      <p>
        Some functions allow for an <i>asynchronous</i> call.
        This is achieved by setting the <c>Timeout</c> argument to
        <c>nowait</c>. For instance, if calling the
        <seeerl marker="#recv-nowait"><c>recv/3</c></seeerl>
        function with Timeout set to <c>nowait</c>
        (<c>recv(Sock, 0, nowait)</c>)
        when there is actually nothing to read, it will return with
        <c>{select, </c>
        <seetype marker="#select_info"><c>SelectInfo</c></seetype><c>}</c>
        (<c>SelectInfo</c> contains the
        <seetype marker="socket#select_handle">SelectHandle</seetype>).
        When data eventually arrives a 'select' message
        will be sent to the caller:
      </p>
      <taglist>
	<!-- NOTE THAT THE EMPTY TAG IS INTENTIONAL -->
	<tag></tag>
	<item><c>{'$socket', socket(), select, SelectHandle}</c></item>
      </taglist>
      <p>
	The caller can now make new call
	to the recv function and expect data.
      </p>
      <p>
	Note that all other users are <em>locked out</em> until the
	'current user' has called the function (recv in this case).
      </p>
      <p>
	Instead of <c>Timeout = nowait</c> it is equivalent to	create a
	<seetype marker="socket#select_handle"><c>SelectHandle</c></seetype>)
	with
	<seemfa marker="erts:erlang#make_ref/0"><c>make_ref()</c></seemfa>
	and give as <c>Timeout</c>.
	This will then be the <c>SelectHandle</c> in the 'select' message,
	which enables a compiler optimization for receiving
	a message containing a newly created <c>reference()</c>
	(ignore the part of the message queue that had arrived
	before the the <c>reference()</c> was created).
      </p>
      <p>Another message the user must be prepared for (when making asynchronous
      calls) is the <c>abort</c> message:</p>
      <taglist>
	<!-- NOTE THAT THE EMPTY TAG IS INTENTIONAL -->
	<tag></tag>
	<item><c>{'$socket', socket(), abort, Info}</c></item>
      </taglist>
      <p>This message indicates
      that the (asynchronous) operation has been aborted.
      If, for instance, the socket has been closed (by another process),
      <c>Info</c> will be <c>{SelectHandle, closed}</c>. </p>
    </note>
    <note>
      <p>There is currently <em>no</em> support for Windows. </p>
      <p>Support for IPv6 has been implemented but <em>not</em> tested. </p>
      <p>SCTP has only been partly implemented (and not tested). </p>
    </note>
  </description>

  <datatypes>
    <datatype>
      <name name="invalid"/>
    </datatype>
    <datatype>
      <name name="domain"/>
      <desc>
	<p>
	  A lowercase <c>atom()</c> representing a protocol <em>domain</em>
	  on the platform named <c>AF_*</c> (or <c>PF_*</c>).
	</p>
        <p>
          The calls
          <seemfa marker="#supports/0"><c>supports()</c></seemfa>,
          <seemfa marker="#is_supported/1">
            <c>is_supported(ipv6)</c>
          </seemfa>
          and
          <seemfa marker="#is_supported/1">
            <c>is_supported(local)</c>
          </seemfa>
          tells if the IPv6 protocol for the <c>inet6</c>
          protocol domain / address family,
          and if the <c>local</c> protocol domain / address family
          is supported by the platform's header files.
        </p>
      </desc>
    </datatype>
    <datatype>
      <name name="type"/>
      <desc>
	<p>
	  A lowercase <c>atom()</c> representing a protocol <em>type</em>
	  on the platform named <c>SOCK_*</c>.
	</p>
      </desc>
    </datatype>
    <datatype>
      <name name="protocol"/>
      <desc>
	<p>
	  An <c>atom()</c> means any <em>protocol</em> as enumerated by the
	  <c>C</c> library call <c>getprotoent()</c>
	  on the platform, or at least the supported ones of
	  <c>ip | ipv6 | tcp | udp | sctp</c>.
	</p>
	<p>See <seemfa marker="#open/3"><c>open/2,3,4</c></seemfa></p>
	<p>
	  The call
	  <seemfa marker="#supports/1"><c>supports(protocols)</c></seemfa>
	  returns which protocols are supported, and
	  <seemfa marker="#is_supported/2">
            <c>is_supported(protocols, Protocol)</c>
          </seemfa>
          tells if <c>Protocol</c> is among the enumerated.
	</p>
      </desc>
    </datatype>
    <datatype>
      <name>socket()</name>
      <desc><p>As returned by
        <seemfa marker="#open/1"><c>open/1,2,3,4</c></seemfa> and
        <seemfa marker="#accept/1"><c>accept/1,2</c></seemfa>.</p>
      </desc>
    </datatype>
    <datatype>
      <name name="select_tag"/>
      <desc>
	<p>
          A tag that describes the (select) operation,
          contained in the returned
          <seetype marker="#select_info"><c>select_info()</c></seetype>.
        </p>
      </desc>
    </datatype>
    <datatype>
      <name name="select_handle"/>
      <desc>
	<p>
	  A <c>reference()</c> that uniquely identifies
	  the (select) operation, contained in the returned
          <seetype marker="#select_info"><c>select_info()</c></seetype>.
	</p>
      </desc>
    </datatype>
    <datatype>
      <name name="select_info"/>
      <desc>
        <p>
          Returned by an operation that requires the caller to wait
          for a
          <seeerl marker="#asynchronous-call">select message</seeerl>
          containing the
          <seetype marker="#select_handle"><c>SelectHandle</c></seetype>.
        </p>
      </desc>
    </datatype>
    <datatype>
      <name name="info"/>
      <desc>
        <p>
          The smallest allowed <c>iov_max</c> value according to POSIX
          is <c>16</c>, but check your platform documentation
          to be sure.
        </p>
      </desc>
    </datatype>
    <datatype>
      <name name="socket_counters"/>
    </datatype>
    <datatype>
      <name name="socket_info"/>
    </datatype>
    <datatype>
      <name name="in_addr"/>
    </datatype>
    <datatype>
      <name name="in6_addr"/>
    </datatype>
    <datatype>
      <name name="sockaddr"/>
    </datatype>
    <datatype>
      <name name="sockaddr_in"/>
    </datatype>
    <datatype>
      <name name="sockaddr_in6"/>
    </datatype>
    <datatype>
      <name name="sockaddr_un"/>
      <desc>
	<p>
	  The <c>path</c> element will always be a <c>binary</c> when
	  returned from this module.  When supplied to an API function
	  in this module it may be a <c>string()</c>, which will be
	  encoded into a binary according to the
	  <seemfa marker="file#native_name_encoding/0">
	    native file name encoding
	  </seemfa>
	  on the platform.
	</p>
	<p>
	  A terminating zero character will be appended before
	  the address path is given to the OS, and the terminating
	  zero will be stripped before giving the address path
	  to the caller.
	</p>
	<p>
	  Linux's non-portable abstract socket address extension is handled
	  by not doing any terminating zero processing in either direction,
	  if the first byte of the address is zero.
	</p>
      </desc>
    </datatype>
    <datatype>
      <name name="sockaddr_ll"/>
    </datatype>
    <datatype>
      <name name="sockaddr_recv"/>
    </datatype>
    <datatype>
      <name name="packet_type"/>
    </datatype>
    <datatype>
      <name name="port_number"/>
    </datatype>
    <datatype>
      <name name="in6_flow_info"/>
    </datatype>
    <datatype>
      <name name="in6_scope_id"/>
    </datatype>
    <datatype>
      <name name="msg_flag"/>
      <desc>
	<p>
	  Flags corresponding to the message flag constants
	  on the platform.  The flags are lowercase and
	  the constants are uppercase with the prefix <c>MSG_</c>.
	</p>
	<p>
	  Some flags are only used for sending,
	  some only for receiving,
	  some in received control messages,
	  and some for several of these.
	  Not all flags are supported on all platforms.
	  See the platform's documentation,
          <seemfa marker="#supports/1"><c>supports(msg_flags)</c></seemfa>,
          and
          <seemfa marker="#is_supported/2"><c>is_supported(msg_flags, MsgFlag)</c></seemfa>.
	</p>
      </desc>
    </datatype>
    <datatype>
      <name name="level"/>
      <desc>
	<p>
	  The OS protocol levels for, for example,
	  socket options and control messages,
	  with the following names in the OS header files:
	</p>
	<taglist>
	  <tag><c>socket</c></tag>
	  <item>
	    <c>SOL_SOCKET</c> with options named <c>SO_</c>*.
	  </item>
	  <tag><c>ip</c></tag>
	  <item>
	    <c>IPPROTO_IP</c> a.k.a <c>SOL_IP</c>
	     with options named <c>IP_</c>*.
	  </item>
	  <tag><c>ipv6</c></tag>
	  <item>
	    <c>IPPROTO_IPV6</c> a.k.a <c>SOL_IPV6</c>
	    with options named <c>IPV6_</c>*.
	  </item>
	  <tag><c>tcp</c></tag>
	  <item>
	    <c>IPPROTO_TCP</c> with options named <c>TCP_</c>*.
	  </item>
	  <tag><c>udp</c></tag>
	  <item>
	    <c>IPPROTO_UDP</c> with options named <c>UDP_</c>*.
	  </item>
	  <tag><c>sctp</c></tag>
	  <item>
	    <c>IPPROTO_SCTP</c> with options named <c>SCTP_</c>*.
	  </item>
	</taglist>
	<p>
	  There are many other possible protocols, but the ones
	  above are those for which this socket library
	  implements socket options and/or control messages.
	</p>
	<p>
	  All protocols known to the OS are enumerated
	  when the Erlang VM is started.
	  See the OS man page for protocols(5).
	  The protocol level 'socket' is always implemented
	  as <c>SOL_SOCKET</c> and all the others mentioned
	  in the list above are valid,
	  if supported by the platform, enumerated or not.
	</p>
        <p>
          The calls
          <seemfa marker="#supports/0"><c>supports()</c></seemfa>
          and
          <seemfa marker="#is_supported/2">
            <c>is_supported(protocols, Protocol)</c>
          </seemfa>
          can be used to find out if protocols <c>ipv6</c>
          and/or <c>sctp</c> are supported according to
          the platform's header files.
        </p>
      </desc>
    </datatype>
    <datatype>
      <name name="otp_socket_option"/>
      <desc>
	<p>
	  These are socket options for the <c>otp</c> protocol level,
	  that is <c>{otp, Name}</c> options,
	  above all OS protocol levels.
	  They affect Erlang/OTP's socket implementation.
	</p>
	<taglist>
	  <tag><c>debug</c></tag>
	  <item><c>boolean()</c> - Activate debug printout.</item>
	  <tag><c>iow</c></tag>
	  <item>
	    <c>boolean()</c>
	    - Inform On Wrap of statistics counters.
	  </item>
	  <tag><c>controlling_process</c></tag>
	  <item>
	    <c>pid()</c>
	    - The socket "owner".
	    Only the current controlling process can set this option.
	  </item>
	  <tag><c>rcvbuf</c></tag>
	  <item>
	    <c>
	      BufSize&nbsp;::&nbsp;(default&nbsp;|&nbsp;integer()>0) |
	      {N&nbsp;::&nbsp;integer()>0,
	      BufSize&nbsp;::&nbsp;(default&nbsp;|&nbsp;integer()>0)}
	    </c>
	    - Receive buffer size.
	    The value <c>default</c> is only valid to <em>set</em>.
	    <c>N</c> specifies the number of read attempts to do
	    in a tight loop before assuming no more data is pending.
	  </item>
	  <tag><c>rcvctrlbuf</c></tag>
	  <item>
	    <c>
	      BufSize&nbsp;::&nbsp;(default&nbsp;|&nbsp;integer()>0)
	    </c>
	    - Buffer size for received ancillary messages.
	    The value <c>default</c> is only valid to <em>set</em>.
	  </item>
	  <tag><c>sndctrlbuf</c></tag>
	  <item>
	    <c>
	      BufSize&nbsp;::&nbsp;(default&nbsp;|&nbsp;integer()>0)
	    </c>
	    - Buffer size for sent ancillary messages.
	    The value <c>default</c> is only valid to <em>set</em>.
	  </item>
	  <tag><c>fd</c></tag>
	  <item>
	    <c>integer()</c>
	    - Only valid to <em>get</em>.
	    The OS protocol levels' socket descriptor.
	    Functions <seemfa marker="#open/1"><c>open/1,2</c></seemfa>
	    can be used to create a socket according to this module
	    from an existing OS socket descriptor.
	  </item>
	  <tag><c>use_registry</c></tag>
	  <item>
	    <c>boolean()</c>
	    - Only valid to <em>get</em>.
	    The value is set when the socket is created with
	    <seemfa marker="#open/2"><c>open/2</c></seemfa>
	    or
	    <seemfa marker="#open/4"><c>open/4</c></seemfa>.
	  </item>
	</taglist>
	<p>
	  Options not described here are intentionally undocumented
	  and for Erlang/OTP internal use only.
	</p>
      </desc>
    </datatype>
    <datatype>
      <name name="socket_option"/>
      <desc>
	<p>
	  Socket option on the form
	  <c>{Level, Opt}</c> where the OS protocol
	  <c>Level</c> =
	  <seetype marker="#level"><c>level()</c></seetype>
	  and <c>Opt</c> is a socket option on that protocol level.
	</p>
	<p>
	  The OS name for an options is, except where otherwise noted,
	  the <c>Opt</c> atom, in capitals, with prefix according to
	  <seetype marker="#level"><c>level()</c></seetype>.
	</p>
	<note><p>See the OS documentation for every socket option.</p></note>
	<p>
	  An option below that has the value type <c>boolean()</c>
	  will translate the value <c>false</c>
	  to a C <c>int</c> with value <c>0</c>,
	  and the value <c>true</c> to <c>!!0</c> (not (not false)).
	</p>
	<p>
	  An option with value type <c>integer()</c>
	  will be translated to a C <c>int</c> that may have
	  a restricted range, for example byte: <c>0..255</c>.
	  See the OS documentation.
	</p>
        <p>
          The calls
          <seemfa marker="#supports/1"><c>supports(options)</c></seemfa>,
          <seemfa marker="#supports/1"><c>supports(options, Level)</c></seemfa>
          and
          <seemfa marker="#is_supported/2">
            <c>is_supported(options, {Level, Opt})</c>
          </seemfa>
          can be used to find out which socket options
          that are supported by the platform.
        </p>
	<!-- ## Protocol level 'socket' ###################### -->
	<p>
	  <em>Options for protocol level</em>
	  <seetype marker="#level"><em><c>socket</c></em>:</seetype>
	</p>
	<taglist>
	  <tag><c>{socket, acceptconn}</c></tag>
	  <item><p><c>Value = boolean()</c></p></item>
	  <tag><c>{socket, bindtodevice}</c></tag>
	  <item><p><c>Value = string()</c></p></item>
	  <tag><c>{socket, broadcast}</c></tag>
	  <item><p><c>Value = boolean()</c></p></item>
	  <tag><c>{socket, debug}</c></tag>
	  <item><p><c>Value = integer()</c></p></item>
	  <tag><c>{socket, domain}</c></tag>
	  <item>
	    <p>
	      <c>Value =</c>
	      <seetype marker="#domain"><c>domain()</c></seetype>
	    </p>
	    <p>Only valid to <em>get</em>.</p>
	    <p>
	      The socket's protocol domain.
	      Does <em>not</em> work on for instance FreeBSD.
	    </p>
	  </item>
	  <tag><c>{socket, dontroute}</c></tag>
	  <item><p><c>Value = boolean()</c></p></item>
	  <tag><c>{socket, keepalive}</c></tag>
	  <item><p><c>Value = boolean()</c></p></item>
	  <tag><c>{socket, linger}</c></tag>
	  <item>
	    <p>
	      <c>Value = abort |</c>
	      <seetype marker="#linger"><c>linger()</c></seetype>
	    </p>
	    <p>
	      The value <c>abort</c>
	      is shorthand for <c>#{onoff => true, linger => 0}</c>,
	      and only valid to <em>set</em>.
	    </p>
	  </item>
	  <tag><c>{socket, oobinline}</c></tag>
	  <item><p><c>Value = boolean()</c></p></item>
	  <tag><c>{socket, passcred}</c></tag>
	  <item><p><c>Value = boolean()</c></p></item>
	  <tag><c>{socket, peek_off}</c></tag>
	  <item>
	    <p><c>Value = integer()</c></p>
	    <p>
	      Currently disabled due to a possible infinite loop when calling
	      <seemfa marker="#recv/1"><c>recv/1-4</c></seemfa>
	      with
	      <seetype marker="#msg_flag"><c>peek</c></seetype>
	      in <c>Flags</c>.
	    </p>
	  </item>
	  <tag><c>{socket, priority}</c></tag>
	  <item><p><c>Value = integer()</c></p></item>
	  <tag><c>{socket, protocol}</c></tag>
	  <item>
	    <p>
	      <c>Value =</c>
	      <seetype marker="#protocol"><c>protocol()</c></seetype>
	    </p>
	    <p>Only valid to <em>get</em>.</p>
	    <p>
	      The socket's protocol.
	      Does <em>not</em> work on for instance Darwin.
	    </p>
	  </item>
	  <tag><c>{socket, rcvbuf}</c></tag>
	  <item><p><c>Value = integer()</c></p></item>
	  <tag><c>{socket, rcvlowat}</c></tag>
	  <item><p><c>Value = integer()</c></p></item>
	  <tag><c>{socket, rcvtimeo}</c></tag>
	  <item>
	    <p>
	      <c>Value =</c>
	      <seetype marker="#timeval"><c>timeval()</c></seetype>
	    </p>
	    <p>
	      This option is unsupported per default;
	      OTP has to be explicitly built with the
	      <c>--enable-esock-rcvsndtimeo</c> configure option
	      for this to be available.
	    </p>
	    <p>
	      Since our implementation uses nonblocking sockets,
	      it is unknown if and how this option works,
	      or even if it may cause malfunction.
	      Therefore, we do not recommend setting this option.
	    </p>
	    <p>
	      Instead, use the <c>Timeout</c> argument to,
	      for instance, the
	      <seemfa marker="#recv/3"><c>recv/3</c></seemfa>
	      function.
	    </p>
	  </item>
	  <tag><c>{socket, reuseaddr}</c></tag>
	  <item><p><c>Value = boolean()</c></p></item>
	  <tag><c>{socket, reuseport}</c></tag>
	  <item><p><c>Value = boolean()</c></p></item>
	  <tag><c>{socket, sndbuf}</c></tag>
	  <item><p><c>Value = integer()</c></p></item>
	  <tag><c>{socket, sndlowat}</c></tag>
	  <item><p><c>Value = integer()</c></p></item>
	  <tag><c>{socket, sndtimeo}</c></tag>
	  <item>
	    <p>
	      <c>Value =</c>
	      <seetype marker="#timeval"><c>timeval()</c></seetype>
	    </p>
	    <p>
	      This option is unsupported per default;
	      OTP has to be explicitly built with the
	      <c>--enable-esock-rcvsndtimeo</c> configure option
	      for this to be available.
	    </p>
	    <p>
	      Since our implementation uses nonblocking sockets,
	      it is unknown if and how this option works,
	      or even if it may cause malfunction.
	      Therefore, we do not recommend setting this option.
	    </p>
	    <p>
	      Instead, use the <c>Timeout</c> argument to,
	      for instance, the
	      <seemfa marker="#send/3"><c>send/3</c></seemfa>
	      function. 
	    </p>
	  </item>
	  <tag><c>{socket, timestamp}</c></tag>
	  <item><p><c>Value = boolean()</c></p></item>

	  <tag><c>{socket, type}</c></tag>
	  <item>
	    <p>
	      <c>Value =</c>
	      <seetype marker="#type"><c>type()</c></seetype>
	    </p>
	    <p>Only valid to <em>get</em>.</p>
	    <p>The socket's type.</p>
	  </item>
	</taglist>
	<p></p>
	<!-- ## Protocol level 'ip' ########################## -->
	<p>
	  <em>Options for protocol level</em>
	  <seetype marker="#level"><em><c>ip</c></em>:</seetype>
	</p>
	<taglist>
	  <tag><c>{ip, add_membership}</c></tag>
	  <item>
	    <p>
	      <c>Value =</c>
	      <seetype marker="#ip_mreq"><c>ip_mreq()</c></seetype>
	    </p>
	    <p>Only valid to <em>set</em>.</p>
	  </item>
	  <tag><c>{ip, add_source_membership}</c></tag>
	  <item>
	    <p>
	      <c>Value =</c>
	      <seetype marker="#ip_mreq_source">
		<c>ip_mreq_source()</c>
	      </seetype>
	    </p>
	    <p>Only valid to <em>set</em>.</p>
	  </item>
	  <tag><c>{ip, block_source}</c></tag>
	  <item>
	    <p>
	      <c>Value =</c>
	      <seetype marker="#ip_mreq_source">
		<c>ip_mreq_source()</c>
	      </seetype>
	    </p>
	    <p>Only valid to <em>set</em>.</p>
	  </item>
	  <tag><c>{ip, drop_membership}</c></tag>
	  <item>
	    <p>
	      <c>Value =</c>
	      <seetype marker="#ip_mreq"><c>ip_mreq()</c></seetype>
	    </p>
	    <p>Only valid to <em>set</em>.</p>
	  </item>
	  <tag><c>{ip, drop_source_membership}</c></tag>
	  <item>
	    <p>
	      <c>Value =</c>
	      <seetype marker="#ip_mreq_source">
		<c>ip_mreq_source()</c>
	      </seetype>
	    </p>
	    <p>Only valid to <em>set</em>.</p>
	  </item>
	  <tag><c>{ip, freebind}</c></tag>
	  <item><p><c>Value = boolean()</c></p></item>
	  <tag><c>{ip, hdrincl}</c></tag>
	  <item><p><c>Value = boolean()</c></p></item>
	  <tag><c>{ip, minttl}</c></tag>
	  <item><p><c>Value = integer()</c></p></item>
	  <tag><c>{ip, msfilter}</c></tag>
	  <item>
	    <p>
	      <c>Value =</c>
	      <c>null |</c>
	      <seetype marker="#ip_msfilter">
		<c>ip_msfilter()</c>
	      </seetype>
	    </p>
	    <p>Only valid to <em>set</em>.</p>
	    <p>
	      The value <c>null</c> passes a <c>NULL</c> pointer
	      and size <c>0</c> to the C library call.
	    </p>
	  </item>
	  <tag><c>{ip, mtu}</c></tag>
	  <item>
	    <p><c>Value = integer()</c></p>
	    <p>Only valid to <em>get</em>.</p>
	  </item>
	  <tag><c>{ip, mtu_discover}</c></tag>
	  <item>
	    <p>
	      <c>Value =</c>
	      <seetype marker="#ip_pmtudisc">
		<c>ip_pmtudisc()</c>
	      </seetype>
	      <c>| integer()</c>
	    </p>
	    <p>
	      An <c>integer()</c> value is  according
	      to the platform's header files.
	    </p>
	  </item>
	  <tag><c>{ip, multicast_all}</c></tag>
	  <item><p><c>Value = boolean()</c></p></item>
	  <tag><c>{ip, multicast_if}</c></tag>
	  <item>
	    <p>
	      <c>Value =</c>
	      <c>any |</c>
	      <seetype marker="#in_addr">
		<c>in_addr()</c>
	      </seetype>
	    </p>
	  </item>
	  <tag><c>{ip, multicast_loop}</c></tag>
	  <item><p><c>Value = boolean()</c></p></item>
	  <tag><c>{ip, multicast_ttl}</c></tag>
	  <item><p><c>Value = integer()</c></p></item>
	  <tag><c>{ip, nodefrag}</c></tag>
	  <item><p><c>Value = boolean()</c></p></item>
	  <tag><c>{ip, pktinfo}</c></tag>
	  <item><p><c>Value = boolean()</c></p></item>
	  <tag><c>{ip, recvdstaddr}</c></tag>
	  <item><p><c>Value = boolean()</c></p></item>
	  <tag><c>{ip, recverr}</c></tag>
	  <item>
            <p><c>Value = boolean()</c></p>
            <p>
              <em>Warning!</em>
              When this option is enabled, error messages may
              arrive on the socket's error queue, which should be read
              using the message flag
              <seetype marker="#msg_flag"><c>errqueue</c></seetype>,
              and using
              <seemfa marker="#recvmsg/1"><c>recvmsg/1,2,3,4,5</c></seemfa>
              to get all error information in the
              <seetype marker="#msg_recv">message's</seetype>
              <c>ctrl</c> field as a
              <seetype marker="#cmsg_recv">control message</seetype>
              <c>#{level&nbsp;:=&nbsp;ip, type&nbsp;:=&nbsp;recverr}</c>.
            </p>
            <p>
              A working strategy should be to first poll
              the error queue using
              <seeerl marker="#recvmsg-timeout">
                <c>recvmsg/2,3,4</c>
              </seeerl>
              with <c>Timeout&nbsp;=:=&nbsp;0</c> and
              <c>Flags</c> containing <c>errqueue</c>
              (ignore the return value <c>{error,&nbsp;timeout}</c>)
              before reading the actual data
              to ensure that the error queue gets cleared.
              And read the data using one of the
              <c>nowait |</c>
              <seetype marker="#select_handle">
                <c>select_handle()</c>
              </seetype>
              recv functions:
              <seeerl marker="#recv-nowait"><c>recv/3,4</c></seeerl>,
              <seeerl marker="#recvfrom-nowait"><c>recvfrom/3,4</c></seeerl> or
              <seeerl marker="#recvmsg-nowait"><c>recvmsg/3,4,5</c></seeerl>.
              Otherwise you might accidentally cause a busy loop
              in and out of 'select' for the socket.
            </p>
          </item>
	  <tag><c>{ip, recvif}</c></tag>
	  <item><p><c>Value = boolean()</c></p></item>
	  <tag><c>{ip, recvopts}</c></tag>
	  <item><p><c>Value = boolean()</c></p></item>
	  <tag><c>{ip, recvorigdstaddr}</c></tag>
	  <item><p><c>Value = boolean()</c></p></item>
	  <tag><c>{ip, recvtos}</c></tag>
	  <item><p><c>Value = boolean()</c></p></item>
	  <tag><c>{ip, recvttl}</c></tag>
	  <item><p><c>Value = boolean()</c></p></item>
	  <tag><c>{ip, retopts}</c></tag>
	  <item><p><c>Value = boolean()</c></p></item>
	  <tag><c>{ip, router_alert}</c></tag>
	  <item><p><c>Value = integer()</c></p></item>
	  <tag><c>{ip, sendsrcaddr}</c></tag>
	  <item><p><c>Value = boolean()</c></p></item>
	  <tag><c>{ip, tos}</c></tag>
	  <item>
	    <p>
	      <c>Value =</c>
	      <seetype marker="#ip_tos">
		<c>ip_tos()</c>
	      </seetype>
	    <c> | integer()</c>
	    </p>
	    <p>
	      An <c>integer()</c> value is  according
	      to the platform's header files.
	    </p>
	  </item>
	  <tag><c>{ip, transparent}</c></tag>
	  <item><p><c>Value = boolean()</c></p></item>
	  <tag><c>{ip, ttl}</c></tag>
	  <item><p><c>Value = integer()</c></p></item>
	  <tag><c>{ip, unblock_source}</c></tag>
	  <item>
	    <p>
	      <c>Value =</c>
	      <seetype marker="#ip_mreq_source">
		<c>ip_mreq_source()</c>
	      </seetype>
	    </p>
	    <p>Only valid to <em>set</em>.</p>
	  </item>
	</taglist>
	<p></p>
	<!-- ## Protocol level 'ipv6' ######################## -->
	<p>
	  <em>Options for protocol level</em>
	  <seetype marker="#level"><em><c>ipv6</c></em>:</seetype>
	</p>
	<taglist>
	  <tag><c>{ipv6, addrform}</c></tag>
	  <item>
	    <p>
	      <c>Value =</c>
	      <seetype marker="#domain">
		<c>domain()</c>
	      </seetype>
	    </p>
	    <p>
	      As far as we know the only valid value is <c>inet</c>
	      and it is only allowed for an IPv6 socket that is connected
	      and bound to an IPv4-mapped IPv6 address.
	    </p>
	  </item>
	  <tag><c>{ipv6, add_membership}</c></tag>
	  <item>
	    <p>
	      <c>Value =</c>
	      <seetype marker="#ipv6_mreq"><c>ipv6_mreq()</c></seetype>
	    </p>
	    <p>Only valid to <em>set</em>.</p>
	  </item>
	  <tag><c>{ipv6, authhdr}</c></tag>
	  <item><p><c>Value = boolean()</c></p></item>
	  <tag><c>{ipv6, drop_membership}</c></tag>
	  <item>
	    <p>
	      <c>Value =</c>
	      <seetype marker="#ipv6_mreq"><c>ipv6_mreq()</c></seetype>
	    </p>
	    <p>Only valid to <em>set</em>.</p>
	  </item>
	  <tag><c>{ipv6, dstopts}</c></tag>
	  <item><p><c>Value = boolean()</c></p></item>
	  <tag><c>{ipv6, flowinfo}</c></tag>
	  <item><p><c>Value = boolean()</c></p></item>
	  <tag><c>{ipv6, hoplimit}</c></tag>
	  <item><p><c>Value = boolean()</c></p></item>
	  <tag><c>{ipv6, hopopts}</c></tag>
	  <item><p><c>Value = boolean()</c></p></item>
	  <tag><c>{ipv6, mtu}</c></tag>
	  <item><p><c>Value = integer()</c></p></item>
	  <tag><c>{ipv6, mtu_discover}</c></tag>
	  <item>
	    <p>
	      <c>Value =</c>
	      <seetype marker="#ipv6_pmtudisc">
		<c>ipv6_pmtudisc()</c>
	      </seetype>
	      <c>| integer()</c>
	    </p>
	    <p>
	      An <c>integer()</c> value is  according
	      to the platform's header files.
	    </p>
	  </item>
	  <tag><c>{ipv6, multicast_hops}</c></tag>
	  <item>
	    <p>
	      <c>Value =</c>
	      <seetype marker="#ipv6_hops"><c>ipv6_hops()</c></seetype>
	    </p>
	  </item>
	  <tag><c>{ipv6, multicast_if}</c></tag>
	  <item><p><c>Value = integer()</c></p></item>
	  <tag><c>{ipv6, multicast_loop}</c></tag>
	  <item><p><c>Value = boolean()</c></p></item>
	  <tag><c>{ipv6, recverr}</c></tag>
	  <item>
            <p><c>Value = boolean()</c></p>
            <p>
              <em>Warning!</em>
              See the socket option <c>{ip, recverr}</c>
              regarding the socket's error queue.
              The same warning applies for this option.
            </p>
          </item>
	  <tag><c>{ipv6, recvhoplimit}</c></tag>
	  <item><p><c>Value = boolean()</c></p></item>
	  <tag><c>{ipv6, recvpktinfo}</c></tag>
	  <item><p><c>Value = boolean()</c></p></item>
	  <tag><c>{ipv6, recvtclass}</c></tag>
	  <item><p><c>Value = boolean()</c></p></item>
	  <tag><c>{ipv6, router_alert}</c></tag>
	  <item><p><c>Value = integer()</c></p></item>
	  <tag><c>{ipv6, rthdr}</c></tag>
	  <item><p><c>Value = boolean()</c></p></item>
	  <tag><c>{ipv6, tclass}</c></tag>
	  <item><p><c>Value = boolean()</c></p></item>
	  <tag><c>{ipv6, unicast_hops}</c></tag>
	  <item>
	    <p>
	      <c>Value =</c>
	      <seetype marker="#ipv6_hops"><c>ipv6_hops()</c></seetype>
	    </p>
	  </item>
	  <tag><c>{ipv6, v6only}</c></tag>
	  <item><p><c>Value = boolean()</c></p></item>
	</taglist>
	<p></p>
	<!-- ## Protocol level 'sctp' ######################## -->
	<p>
	  <em>Options for protocol level</em>
	  <seetype marker="#level"><em><c>sctp</c></em></seetype>.
	  See also RFC 6458.
	</p>
	<taglist>
	  <tag><c>{sctp, associnfo}</c></tag>
	  <item>
	    <p>
	      <c>Value =</c>
	      <seetype marker="#sctp_assocparams">
		<c>sctp_assocparams()</c>
	      </seetype>
	    </p>
	  </item>
	  <tag><c>{sctp, autoclose}</c></tag>
	  <item><p><c>Value = integer()</c></p></item>
	  <tag><c>{sctp, disable_fragments}</c></tag>
	  <item><p><c>Value = boolean()</c></p></item>
	  <tag><c>{sctp, events}</c></tag>
	  <item>
	    <p>
	      <c>Value =</c>
	      <seetype marker="#sctp_event_subscribe">
		<c>sctp_event_subscribe()</c>
	      </seetype>
	    </p>
	    <p>Only valid to <em>set</em>.</p>
	  </item>
	  <tag><c>{sctp, initmsg}</c></tag>
	  <item>
	    <p>
	      <c>Value =</c>
	      <seetype marker="#sctp_initmsg">
		<c>sctp_initmsg()</c>
	      </seetype>
	    </p>
	  </item>
	  <tag><c>{sctp, maxseg}</c></tag>
	  <item><p><c>Value = integer()</c></p></item>
	  <tag><c>{sctp, nodelay}</c></tag>
	  <item><p><c>Value = boolean()</c></p></item>
	  <tag><c>{sctp, rtoinfo}</c></tag>
	  <item>
	    <p>
	      <c>Value =</c>
	      <seetype marker="#sctp_rtoinfo">
		<c>sctp_rtoinfo()</c>
	      </seetype>
	    </p>
	  </item>
	</taglist>
	<p></p>
	<!-- ## Protocol level 'tcp' ######################### -->
	<p>
	  <em>Options for protocol level</em>
	  <seetype marker="#level"><em><c>tcp</c>:</em></seetype>
	</p>
	<taglist>
	  <tag><c>{tcp, congestion}</c></tag>
	  <item><p><c>Value = string()</c></p></item>
	  <tag><c>{tcp, cork}</c></tag>
	  <item><p><c>Value = boolean()</c></p></item>
	  <tag><c>{tcp, maxseg}</c></tag>
	  <item><p><c>Value = integer()</c></p></item>
	  <tag><c>{tcp, nodelay}</c></tag>
	  <item><p><c>Value = boolean()</c></p></item>
	</taglist>
	<p></p>
	<!-- ## Protocol level 'udp' ######################### -->
	<p>
	  <em>Options for protocol level</em>
	  <seetype marker="#level"><em><c>udp</c>:</em></seetype>
	</p>
	<taglist>
	  <tag><c>{udp, cork}</c></tag>
	  <item><p><c>Value = boolean()</c></p></item>
	</taglist>
      </desc>
    </datatype>
    <datatype>
      <name name="linger"/>
      <desc>
	<p>
	  Corresponds to the C <c>struct linger</c>
	  for managing the
	  <seetype marker="#socket_option">socket option</seetype>
	  <c>{socket, linger}</c>.
	</p>
      </desc>
    </datatype>
    <datatype>
      <name name="timeval"/>
      <desc>
	<p>
	  Corresponds to the C <c>struct timeval</c>.
	  The field <c>sec</c> holds seconds,
	  and <c>usec</c> microseconds.
	</p>
      </desc>
    </datatype>
    <datatype>
      <name name="ip_mreq"/>
      <desc>
	<p>
	  Corresponds to the C <c>struct ip_mreq</c>
	  for managing multicast groups.
	</p>
      </desc>
    </datatype>
    <datatype>
      <name name="ip_mreq_source"/>
      <desc>
	<p>
	  Corresponds to the C <c>struct ip_mreq_source</c>
	  for managing multicast groups.
	</p>
      </desc>
    </datatype>
    <datatype>
      <name name="ip_msfilter"/>
      <desc>
	<p>
	  Corresponds to the C <c>struct ip_msfilter</c>
	  for managing multicast source filtering (RFC 3376).
	</p>
      </desc>
    </datatype>
    <datatype>
      <name name="ip_pmtudisc"/>
      <desc>
	<p>
	  Lowercase <c>atom()</c> values corresponding to
	  the C library constants <c>IP_PMTUDISC_*</c>.
	  Some constant(s) may be unsupported by the platform.
	</p>
      </desc>
    </datatype>
    <datatype>
      <name name="ip_tos"/>
      <desc>
	<p>
	  Lowercase <c>atom()</c> values corresponding to
	  the C library constants <c>IPTOS_*</c>.
	  Some constant(s) may be unsupported by the platform.
	</p>
      </desc>
    </datatype>
    <datatype>
      <name name="ip_pktinfo"/>
    </datatype>
    <datatype>
      <name name="ipv6_mreq"/>
      <desc>
	<p>
	  Corresponds to the C <c>struct ipv6_mreq</c>
	  for managing multicast groups.
	  See also RFC 2553.
	</p>
      </desc>
    </datatype>
    <datatype>
      <name name="ipv6_hops"/>
      <desc>
	<p>
	  The value <c>default</c> is only valid to <em>set</em>
	  and is translated to the C value <c>-1</c>,
	  meaning the route default.
	</p>
      </desc>
    </datatype>
    <datatype>
      <name name="ipv6_pmtudisc"/>
      <desc>
	<p>
	  Lowercase <c>atom()</c> values corresponding to
	  the C library constants <c>IPV6_PMTUDISC_*</c>.
	  Some constant(s) may be unsupported by the platform.
	</p>
      </desc>
    </datatype>
    <datatype>
      <name name="ipv6_pktinfo"/>
    </datatype>
    <datatype>
      <name name="sctp_assocparams"/>
      <desc>
	<p>
	  Corresponds to the C <c>struct sctp_assocparams</c>.
	</p>
      </desc>
    </datatype>
    <datatype>
      <name name="sctp_event_subscribe"/>
      <desc>
	<p>
	  Corresponds to the C <c>struct sctp_event_subscribe</c>.
	</p>
	<p>
	  Not all fields are implemented on all platforms;
	  unimplemented fields are ignored,
	  but implemented fields are mandatory.
	  Note that the '_event' suffixes have been stripped
	  from the C struct field names, for convenience.
	</p>
      </desc>
    </datatype>
    <datatype>
      <name name="sctp_initmsg"/>
      <desc>
	<p>
	  Corresponds to the C <c>struct sctp_initmsg</c>.
	</p>
      </desc>
    </datatype>
    <datatype>
      <name name="sctp_rtoinfo"/>
      <desc>
	<p>
	  Corresponds to the C <c>struct sctp_rtoinfo</c>.
	</p>
      </desc>
    </datatype>
    <datatype>
      <name name="msg"/>
    </datatype>
    <datatype>
      <name name="msg_send"/>
      <desc>
	<p>
	  Message sent by
	  <seemfa marker="#sendmsg/2"><c>sendmsg/2,3,4</c></seemfa>.
	</p>
	<p>
	  Corresponds to a C <c>struct msghdr</c>,
	  see your platform documentation for <c>sendmsg(2)</c>.
	</p>
	<taglist>
	  <tag><c>addr</c></tag>
	  <item>
	    Optional peer address, used on unconnected sockets.
	    Corresponds to <c>msg_name</c> and <c>msg_namelen</c>
	    fields of a <c>struct msghdr</c>.
	    If not used they are set to <c>NULL</c>, <c>0</c>.
	  </item>
	  <tag><c>iov</c></tag>
	  <item>
	    Mandatory data as a list of binaries.
	    The <c>msg_iov</c> and <c>msg_iovlen</c>
	    fields of a <c>struct msghdr</c>.
	  </item>
	  <tag><c>ctrl</c></tag>
	  <item>
	    Optional list of control messages (CMSG).
	    Corresponds to the <c>msg_control</c> and <c>msg_controllen</c>
	    fields of a <c>struct msghdr</c>.
	    If not used they are set to <c>NULL</c>, <c>0</c>.
	  </item>
	</taglist>
	<p>
	  The <c>msg_flags</c> field of the <c>struct msghdr</c>
	  is set to <c>0</c>.
	</p>
      </desc>
    </datatype>
    <datatype>
      <name name="msg_recv"/>
      <desc>
	<p>
	  Message returned by
	  <seemfa marker="#recvmsg/1"><c>recvmsg/1,2,3,5</c></seemfa>.
	</p>
	<p>
	  Corresponds to a C <c>struct msghdr</c>,
	  see your platform documentation for <c>recvmsg(2)</c>.
	</p>
	<taglist>
	  <tag><c>addr</c></tag>
	  <item>
	    Optional peer address, used on unconnected sockets.
	    Corresponds to <c>msg_name</c> and <c>msg_namelen</c>
	    fields of a <c>struct msghdr</c>.
	    If <c>NULL</c> the map key is not present.
	  </item>
	  <tag><c>iov</c></tag>
	  <item>
	    Data as a list of binaries.
	    The <c>msg_iov</c> and <c>msg_iovlen</c>
	    fields of a <c>struct msghdr</c>.
	  </item>
	  <tag><c>ctrl</c></tag>
	  <item>
	    A possibly empty list of control messages (CMSG).
	    Corresponds to the <c>msg_control</c> and <c>msg_controllen</c>
	    fields of a <c>struct msghdr</c>.
	  </item>
	  <tag><c>flags</c></tag>
	  <item>
	    Message flags.
	    Corresponds to the <c>msg_flags</c>
	    field of a <c>struct msghdr</c>.
            Unknown flags, if any, are returned in one <c>integer()</c>,
            last in the containing list.
	  </item>
	</taglist>
      </desc>
    </datatype>
    <datatype>
      <name name="native_value"/>
    </datatype>
    <datatype>
      <name name="cmsg_send"/>
      <desc>
	<p>
	  Control messages (ancillary messages) accepted by
	  <seemfa marker="#sendmsg/2"><c>sendmsg/2,3,4</c></seemfa>.
	</p>
	<p>
	  A control message may for some message types have a
	  <c>value</c> field with a symbolic value,
	  or a <c>data</c> field with a native value,
	  that has to be binary compatible what is defined
	  in the platform's header files.
	</p>
      </desc>
    </datatype>
    <datatype>
      <name name="cmsg_recv"/>
      <desc>
	<p>
	  Control messages (ancillary messages) returned by
	  <seemfa marker="#recvmsg/1"><c>recvmsg/1,2,3,5</c></seemfa>.
	</p>
	<p>
	  A control message has got a <c>data</c> field with
	  a native (<c>binary</c>) value for the message data,
	  and may also have a decoded <c>value</c> field
	  if this socket library succesfully decoded the data.
	</p>
      </desc>
    </datatype>
    <datatype>
      <name name="icmp_dest_unreach"/>
    </datatype>
    <datatype>
      <name name="icmpv6_dest_unreach"/>
    </datatype>
    <datatype>
      <name name="ee_origin"/>
    </datatype>
    <datatype>
      <name name="extended_err"/>
    </datatype>
    <datatype>
      <name name="posix"/>
      <desc>
	<p>
	  The POSIX error codes originates from the
	  OS level socket interface.
	</p>
      </desc>
    </datatype>
  </datatypes>

  <funcs>
    <func>
      <name name="accept" arity="1" since="OTP 22.0"
            anchor="accept-infinity"/>
      <name name="accept" arity="2" clause_i="3" since="OTP 22.0"/>
      <fsummary>Accept a connection on a socket.</fsummary>
      <desc>
        <p>Accept a connection on a socket.</p>
        <p>
	  This call is used with connection oriented socket types
	  (<c>stream</c> or <c>seqpacket</c>).
	  It returns the first pending incoming connection
	  for a listen socket, or waits for one to arrive,
	  and returns the (newly) connected socket.
	</p>
      </desc>
    </func>

    <func>
      <name name="accept" arity="2" clause_i="4" since="OTP 22.0"
            anchor="accept-timeout"/>
      <fsummary>Accept a connection on a socket.</fsummary>
      <desc>
	<p>
	  The same as
	  <seemfa marker="#accept/1">accept/1</seemfa>
	  but returns <c>{error, timeout}</c>
	  if no connection has been accepted after
	  <c><anno>Timeout</anno></c> milliseconds.
	</p>
      </desc>
    </func>

    <func>
      <name name="accept" arity="2" clause_i="1" since="OTP 22.1"
            anchor="accept-nowait"/>
      <name name="accept" arity="2" clause_i="2" since="OTP 24.0"/>
      <fsummary>Accept a connection on a socket.</fsummary>
      <desc>
	<p>
	  The same as
	  <seemfa marker="#accept/1">accept/1</seemfa>
	  but returns promptly.
	</p>
	<p>
	  When there is no pending connection to return,
	  the function will return
	  <seetype marker="#select_info"><c>{select, <anno>SelectInfo</anno>}</c></seetype>,
	  and the caller will later receive a select message,
	  <c>{'$socket', Socket, select, SelectHandle}</c> (
	  with the
	  <seetype marker="socket#select_handle"><c>SelectHandle</c></seetype>
	  contained in the
	  <seetype marker="#select_info">
	    <c><anno>SelectInfo</anno></c>
	  </seetype>
	  ) when a client connects.
	  A subsequent call to <c>accept/1,2</c>
	  will then return the socket.
	</p>
	<p>
	  If the time-out argument is <c>SelectHandle</c>,
	  that term will be contained in a returned
	  <c><anno>SelectInfo</anno></c>
	  and the corresponding select message.
	  The <c>SelectHandle</c> is presumed to be
	  unique to this call.
	</p>
	<p>
	  If the time-out argument is <c>nowait</c>, and a
	  <c><anno>SelectInfo</anno></c> is returned,
	  it will contain a
	  <seetype marker="socket#select_handle">
	    <c>select_handle()</c>
	  </seetype> generated by the call.
	</p>
      </desc>
    </func>

    <func>
      <name name="bind" arity="2" since="OTP 22.0"/>
      <fsummary>Bind a name to a socket.</fsummary>
      <desc>
        <p>Bind a name to a socket.</p>
        <p>
	  When a socket is created
	  (with <seemfa marker="#open/2"><c>open</c></seemfa>),
	  it has no address assigned to it. <c>bind</c> assigns the
	  address specified by the <c>Addr</c> argument.
	</p>
	<p>
	  The rules used for name binding vary between domains.
	</p>
	<p>
	  If you bind a socket to an address in for example
	  the 'inet' or 'inet6' address families,
	  with an ephemeral port number (0),
	  and want to know which port that was chosen,
	  you can find out using something like:
	  <c>{ok, #{port := Port}} =</c>
	  <seemfa marker ="#sockname/1">
	    <c>socket:sockname(<anno>Socket</anno>)</c>
	  </seemfa>
	</p>
      </desc>
    </func>

    <func>
      <name name="cancel" arity="2" since="OTP 22.1"/>
      <fsummary>Cancel an asynchronous request.</fsummary>
      <desc>
	<p>Cancel an asynchronous request.</p>
	<p>
	  Call this function in order to cancel a previous
	  asynchronous call to, e.g.
	  <seemfa marker="#recv/3"><c>recv/3</c></seemfa>.
	</p>
      </desc>
    </func>

    <func>
      <name name="close" arity="1" since="OTP 22.0"/>
      <fsummary>Close a socket.</fsummary>
      <desc>
	<p>Closes the socket.</p>

	<note>
	  <p>Note that for e.g. <c>protocol</c> = <c>tcp</c>, most implementations
	  doing a close does not guarantee that any data sent is delivered to
	  the recipient before the close is detected at the remote side. </p>
	  <p>One way to handle this is to use the
	  <seemfa marker="#shutdown/2"><c>shutdown</c></seemfa>
	  function
	  (<c>socket:shutdown(Socket, write)</c>) to signal that no more data is
	  to be sent and then wait for the read side of the socket to be closed.</p>
	</note>
      </desc>
    </func>

    <func>
      <name name="connect" arity="2" since="OTP 22.0"
            anchor="connect-infinity"/>
      <name name="connect" arity="3" clause_i="3" since="OTP 22.0"/>
      <fsummary>Initiate a connection on a socket.</fsummary>
      <desc>
        <p>
	  This function connects the socket to the address
	  specified by the <c>SockAddr</c> argument,
	  and returns when the connection has been established
	  or failed.
	</p>
	<p>
	  If a connection attempt is already in progress
	  (by another process), <c>{error, already}</c> is returned.
	</p>
      </desc>
    </func>

    <func>
      <name name="connect" arity="3" clause_i="4" since="OTP 22.0"
            anchor="connect-timeout"/>
      <fsummary>Initiate a connection on a socket.</fsummary>
      <desc>
        <p>
	  The same as
	  <seemfa marker="#connect/2">connect/2</seemfa>
	  but returns <c>{error, timeout}</c>
	  if no connection has been established
	  after <c><anno>Timeout</anno></c> milliseconds.
	</p>
	<note>
	  <p>
	    Note that when this call has returned
	    <c>{error, timeout</c> the connection state of the socket
	    is uncertain since the platform's network stack
	    may complete the connection at any time,
	    up to some platform specific time-out.
	  </p>
	  <p>
	    Repeating a connection attempt towards the same address
	    would be ok, but towards a different address could
	    end up with a connection to either address.
	  </p>
	  <p>
	    The safe play would be to close the socket and start over.
	  </p>
	  <p>
	    Also note that all this applies to cancelling
	    a connect call with a no-wait time-out described below.
	  </p>
	</note>
      </desc>
    </func>

    <func>
      <name name="connect" arity="3" clause_i="1" since="OTP 22.1"
            anchor="connect-nowait"/>
      <name name="connect" arity="3" clause_i="2" since="OTP 24.0"/>
      <fsummary>Initiate a connection on a socket.</fsummary>
      <desc>
        <p>
	  The same as
	  <seemfa marker="#connect/2">connect/2</seemfa>
	  but returns promptly.
	</p>
 	<p>
	  If it is not possible to immediately establish a
	  connection, the function will return
	  <seetype marker="#select_info"><c>{select, SelectInfo}</c></seetype>,
	  and the caller will later receive a select message,
	  <c>{'$socket', Socket, select, SelectHandle}</c> (
	  with the
	  <seetype marker="socket#select_handle"><c>SelectHandle</c></seetype>
	  contained in the
	  <seetype marker="#select_info"><c>SelectInfo</c></seetype>
	  ) when the connection has been completed or failed.
	  A subsequent call to
	  <seemfa marker="#connect/1"><c>connect/1</c></seemfa>
	  will then finalize the connection and return the result.
	</p>
	<p>
	  If the time-out argument is <c>SelectHandle</c>,
	  that term will be contained in a returned
	  <c><anno>SelectInfo</anno></c>
	  and the corresponding select message.
	  The <c>SelectHandle</c> is presumed to be
	  unique to this call.
	</p>
	<p>
	  If the time-out argument is <c>nowait</c>, and a
	  <c><anno>SelectInfo</anno></c> is returned,
	  it will contain a
	  <seetype marker="socket#select_handle">
	    <c>select_handle()</c>
	  </seetype> generated by the call.
	</p>
     </desc>
    </func>

    <func>
      <name name="connect" arity="1" since="OTP 24.0"/>
      <fsummary>Finalize a connection initiation on a socket.</fsummary>
      <desc>
        <p>
	  This function finalizes a connection setup on a socket,
	  after calling
	  <seemfa marker="#connect/3">
	    <c>connect(_, _, nowait | select_handle())</c>
	  </seemfa>
	  that returned
	  <seetype marker="#select_info"><c>{select, SelectInfo}</c></seetype>,
	  and receiving the select message
	  <c>{'$socket', Socket, select, SelectHandle}</c>,
	  and returns whether the connection setup was succesful or not.
	</p>
	<p>
	  Instead of calling this function, for backwards compatibility,
	  it is allowed to call
	  <seemfa marker="#connect/2"><c>connect/2,3</c></seemfa>,
	  but that incurs more overhead since the connect address
	  and time-out are processed in vain.
	</p>
      </desc>
    </func>

    <func>
      <name name="getopt" arity="2" clause_i="1" since="OTP 22.0"/>
      <fsummary>
	Get a socket option from the protocol level <c>otp</c>.
      </fsummary>
      <desc>
        <p>
	  Gets a socket option from the protocol level <c>otp</c>,
	  which is this implementation's level
	  above the OS protocol layers.
	</p>
	<p>
	  See the type
	  <seetype marker="#otp_socket_option">
	    otp_socket_option()
	  </seetype>
	  for a description of the options on this level.
	</p>
      </desc>
    </func>

    <func>
      <name name="getopt" arity="2" clause_i="2" since="OTP 22.0"/>
      <fsummary>
	Get a socket option from one of the OS's protocol levels.
      </fsummary>
      <desc>
        <p>
	  Gets a socket option from one of the OS's protocol levels.
	  See the type
	  <seetype marker="#socket_option">socket_option()</seetype>
	  for which options that this implementation knows about,
	  how they are related to option names in the OS,
	  and if there are known pecularities with any of them.
	</p>
	<p>
	  What options are valid depends on what kind of socket it is
	  (<seetype marker="#domain"><c>domain()</c></seetype>,
	  <seetype marker="#type"><c>type()</c></seetype> and
	  <seetype marker="#protocol"><c>protocol()</c></seetype>).
	</p>
	<p>
	  See the
	  <seeguide marker="socket_usage#socket_options">
	    socket options
	  </seeguide>
	  chapter of the users guide for more info.
	</p>
	<note>
	  <p>
	    Not all options are valid, nor possible to get,
	    on all platforms.
	    That is, even if "we" support an option;
	    it does not mean that the underlying OS does.
	  </p>
	</note>
      </desc>
    </func>

    <func>
      <!--
	  Backwards compatibility function - remove documentation?
	  Document the Native clause?
      -->
      <name since="OTP 22.0">
	getopt(Socket, Level, Opt) -> ok | {error, Reason}
      </name>
      <fsummary>
	Get a socket protocol option.
      </fsummary>
      <type>
	<v>
	  Socket = <seetype marker="#socket">socket()</seetype>
	</v>
	<v>
	  Reason = <seetype marker="inet#posix">inet:posix()</seetype>
	  | <seetype marker="#invalid"><c>invalid()</c></seetype>
	  | closed
	</v>
      </type>
      <desc>
	<p>Backwards compatibility function.</p>
        <p>
	  The same as
	  <seemfa marker="#getopt/2">
	    <c>getopt(Socket, {Level, Opt})</c>
	  </seemfa>
	</p>
      </desc>
    </func>

    <func>
      <name name="getopt_native" arity="3" clause_i="1" since="OTP 22.0"/>
      <name name="getopt_native" arity="3" clause_i="2" since="OTP 22.0"/>
      <name name="getopt_native" arity="3" clause_i="3" since="OTP 22.0"/>
      <name name="getopt_native" arity="3" clause_i="4" since="OTP 24.0"/>
      <fsummary>Get a "native" socket option.</fsummary>
      <desc>
        <p>
	  Gets a socket option that may be unknown to our
	  implementation, or that has a type not compatible
	  with our implementation, that is; in "native mode".
	</p>
	<p>
	  The socket option may be specified with an ordinary
	  <seetype marker="#socket_option">
	    <c>socket_option()</c>
	  </seetype>
	  tuple, with a known 
	  <seetype marker="#level">
	    <c><anno>Level</anno> = level()</c>
	  </seetype>
	  and an integer <c><anno>NativeOpt</anno></c>,
	  or with both an integer <c><anno>NativeLevel</anno></c>
	  and <c><anno>NativeOpt</anno></c>.
	</p>
	<p>
	  How to decode the option value has to be specified
	  either with <c><anno>ValueType</anno></c>,
	  by specifying the <c><anno>ValueSize</anno></c>
	  for a <c>binary()</c> that will contain
	  the fetched option value,
	  or by specifying a <c>binary()</c> <c><anno>ValueSpec</anno></c>
	  that will be copied to a buffer for the
	  <c>getsockopt()</c> call to write the value
	  in which will be returned as a new <c>binary()</c>.
	</p>
	<p>
	  If <c><anno>ValueType</anno></c> is <c>integer</c>
	  a <c>C</c> type <c>(int)</c> will be fetched,
	  if it is <c>boolean</c> a <c>C</c> type <c>(int)</c>
	  will be fetched and converted into a <c>boolean()</c>
	  according to the <c>C</c> implementation.
	</p>
	<p>
	  What options are valid depends on what kind of socket it is
	  (<seetype marker="#domain"><c>domain()</c></seetype>,
	  <seetype marker="#type"><c>type()</c></seetype> and
	  <seetype marker="#protocol"><c>protocol()</c></seetype>).
	</p>
	<p>
	  The integer values for 
	  <c><anno>NativeLevel</anno></c> and
	  <c><anno>NativeOpt</anno></c>
	  as well as the <c><anno>Value</anno></c> encoding
	  has to be deduced from the header files for
	  the running system.
	</p>
      </desc>
    </func>

    <func>
      <name name="info" arity="0" since="OTP 24.0"/>
      <fsummary>Get miscellaneous socket library info.</fsummary>
      <desc>
        <p>Get miscellaneous info about the socket library.</p>
	<p>
          The function returns a map with each info item as a key-value
	  binding.
        </p>
	<note>
	  <p>
            In order to ensure data integrity, mutex'es are taken when
	    needed. So, do not call this function often.
          </p>
	</note>
      </desc>
    </func>

    <func>
      <name name="info" arity="1" since="OTP 22.1"/>
      <fsummary>Get miscellaneous socket info.</fsummary>
      <desc>
        <p>Get miscellaneous info about the socket.</p>
	<p>The function returns a map with each info item as a key-value
	binding. It reflects the "current" state of the socket. </p>
	<note>
	  <p>In order to ensure data integrity, mutex'es are taken when
	  needed. So, do not call this function often. </p>
	</note>
      </desc>
    </func>

    <func>
      <name name="is_supported" arity="1" since="OTP 23.0"/>
      <name name="is_supported" arity="2" since="OTP 23.0"/>
      <fsummary>Report info about what the platform supports.</fsummary>
      <desc>
	<p>
	  This function retreives information about what the
	  platform supports,  such as if SCTP is supported,
	  or if a socket options are supported.
	</p>
	<p>
	  For keys other than the known <c>false</c> is returned.
	  Note that in a future version or on a different platform
	  there might be more supported items.
	</p>
	<p>
	  This functions returns a <c>boolean</c> corresponding to what
	  <seemfa marker="#supports/0"><c>supports/0-2</c></seemfa>
	  reports for the same <c><anno>Key1</anno></c>
	  (and <c><anno>Key2</anno></c>).
	</p>
      </desc>
    </func>

    <func>
      <name name="listen" arity="1" since="OTP 22.0"/>
      <name name="listen" arity="2" since="OTP 22.0"/>
      <fsummary>Listen for connections on a socket.</fsummary>
      <desc>
        <p>Listen for connections on a socket.</p>
      </desc>
    </func>

    <func>
      <name name="number_of" arity="0" since="OTP 22.3"/>
      <fsummary>Get the number of active sockets.</fsummary>
      <desc>
        <p>Returns the number of active sockets.</p>
      </desc>
    </func>

    <func>
      <name name="open" arity="1" since="OTP 23.0"/>
      <name name="open" arity="2" clause_i="1" since="OTP 23.0"/>
      <fsummary>Create an endpoint for communication.</fsummary>
      <desc>
	<p>Create an endpoint (socket) for communication based on an
	already existing file descriptor.
	The function attempts to retrieve domain, type and protocol from
	the system. This is however not possible on all platforms, and
	in those cases it expects it in <c>Opts</c>. </p>

	<p>The <c>Opts</c> argument is intended for providing extra
	information for the open call:</p>
	<taglist>
	  <tag>
	    <c>domain</c>
	  </tag>
	  <item>
	    <p>
	      Which protocol domain is the descriptor of.
	      See also <seemfa marker="#open/3"><c>open/2,3,4</c></seemfa>.
	    </p>
	  </item>

	  <tag>
	    <c>type</c>
	  </tag>
	  <item>
	    <p>Which protocol type type is the descriptor of.</p>
	    <p>
	      See also <seemfa marker="#open/3"><c>open/2,3,4</c></seemfa>.
	    </p>
	  </item>

	  <tag>
	    <c>protocol</c>
	  </tag>
	  <item>
	    <p>
	      Which protocol is the descriptor of.
	      The atom <c>default</c> is equivalent to the integer
	      protocol number <c>0</c> which means the default
	      protocol for a given domain and type.
	    </p>
	    <p>
	      See also <seemfa marker="#open/3"><c>open/2,3,4</c></seemfa>.
	    </p>
	  </item>

	  <tag><c>dup</c></tag>
	  <item>
	    <p>Shall the provided descriptor be duplicated (dup) or not.
	    <br/>Defaults to <c>true</c>. </p>
	  </item>

	  <tag><c>debug</c></tag>
	  <item>
	    <p>Enable or disable debug during the open call.
	    <br/>Defaults to <c>false</c>. </p>
	  </item>

	  <tag><c>use_registry></c></tag>
	  <item>
	    <p>Enable or disable use of the socket registry for this socket.
	    This overrides the global value.
	    <br/>Defaults to the global value, see
	    <seemfa marker="#use_registry/1"><c>use_registry/1</c></seemfa>.
	    </p>
	  </item>

	</taglist>

	<note>
	  <p>This function should be used with care! </p>
	  <p>On some platforms its <em>necessary</em> to provide the
	  <c>protocol</c> as its impossible to retrieve it. </p>
	</note>
      </desc>
    </func>

    <func>
      <name name="open" arity="2" clause_i="2" since="OTP 22.0"/>
      <name name="open" arity="3" clause_i="1" since="OTP 24.0"/>
      <name name="open" arity="3" clause_i="2" since="OTP 22.0"/>
      <name name="open" arity="4" since="OTP 22.0"/>
      <fsummary>Create an endpoint for communication.</fsummary>
      <desc>
	<p>Creates an endpoint (socket) for communication.</p>

	<p>
	  <c><anno>Domain</anno></c> and
	  <c><anno>Type</anno></c> may be <c>integer()</c>s,
	  as defined in the platform's header files.
	  The same goes for <c><anno>Protocol</anno></c>
	  but according to the platform's <c>services(5)</c> database.
	  See the OS man page for the library call <c>socket(2)</c>
	</p>

	<p>For some <c><anno>Type</anno></c>s there is a default protocol,
	indicated by <c>default</c>, which it <em>may</em> be
	possible to specify.
	And for <c>Domain = local</c>,
	if a protocol <em>is</em> specified,
	it <em>must</em> be <c>default</c>.</p>

	<p>The <c>Opts</c> argument is intended for "other" options.
	The supported option(s) are described below:</p>

	<taglist>
	  <tag><c><![CDATA[netns: string()]]></c></tag>
	  <item>
	    <p>Used to set the network namespace during the open call.
	    Only supported on the Linux platform. </p>
	  </item>

	  <tag><c><![CDATA[debug: boolean()]]></c></tag>
	  <item>
	    <p>Enable or disable debug during the open call.
	    <br/>Defaults to <c>false</c>. </p>
	  </item>

	  <tag><c><![CDATA[use_registry: boolean()]]></c></tag>
	  <item>
	    <p>Enable or disable use of the socket registry for this socket.
	    This overrides the global value.
	    <br/>Defaults to the global value, see
	    <seemfa marker="#use_registry/1"><c>use_registry/1</c></seemfa>.
	    </p>
	  </item>

	</taglist>

	<note>
	  <p>It may not be possible to specify the default protocol (except
	  when <c>Domain = local</c>). We need to be able to retreive
	  the resulting protocol, which is <em>not</em> possble on all
	  platforms. </p>
	</note>
      </desc>
    </func>

    <func>
      <name name="peername" arity="1" since="OTP 22.0"/>
      <fsummary>Get name of connected socket peer.</fsummary>
      <desc>
        <p>Returns the address of the peer connected to the socket.</p>
      </desc>
    </func>

    <func>
      <name name="recv" arity="1" since="OTP 22.0"
	    anchor="recv-infinity"/>
      <name name="recv" arity="2" clause_i="1" since="OTP 24.0"/>
      <name name="recv" arity="2" clause_i="2" since="OTP 22.0"/>
      <name name="recv" arity="3" clause_i="3" since="OTP 24.0"/>
      <name name="recv" arity="3" clause_i="5" since="OTP 22.0"/>
      <name name="recv" arity="3" clause_i="8" since="OTP 22.0"/>
      <name name="recv" arity="4" clause_i="3" since="OTP 22.0"/>
      <fsummary>
        Receive data from a socket, with "infinite" time-out.
      </fsummary>
      <desc>
        <p>
          Receives data from a socket, waiting for it to arrive.
        </p>
	<p>
	  The argument <c><anno>Length</anno></c>
	  specifies how many bytes to receive,
	  with the special case <c>0</c> meaning "all available".
	</p>
	<p>
          For a socket of
          <seetype marker="#type">type <c>stream</c></seetype>
	  this call will not return until all requested
	  data can be delivered, or if "all available" data
          was requested when the first data chunk arrives.
	</p>
        <p>
          The message <c>Flags</c> may be symbolic
          <seetype marker="#msg_flag"><c>msg_flag()</c></seetype>s and/or
          <c>integer()</c>s, as in the platform's appropriate header files.
          The values of all symbolic flags and integers are or:ed together.
        </p>
	<p>
	  When there is a socket error this function returns
	  <c>{error,&nbsp;<anno>Reason</anno>}</c>,
          or if some data arrived before the error;
	  <c>{error,&nbsp;{<anno>Reason</anno>,&nbsp;<anno>Data</anno>}}</c>.
	</p>
      </desc>
    </func>

    <func>
      <name name="recv" arity="3" clause_i="4" since="OTP 24.0"
	    anchor="recv-timeout"/>
      <name name="recv" arity="3" clause_i="9" since="OTP 22.0"/>
      <name name="recv" arity="4" clause_i="4" since="OTP 22.0"/>
      <fsummary>Receive data from a socket, with time-out.</fsummary>
      <desc>
        <p>
          Receives data from a socket, waiting at most
          <c><anno>Timeout</anno></c> milliseconds for it to arrive.
        </p>
	<p>
	  The same as
	  <seeerl marker="#recv-infinity">
            infinite time-out <c>recv/1,2,3,4</c>
          </seeerl>
	  but returns <c>{error,&nbsp;timeout}</c> or
	  <c>{error,&nbsp;{timeout,&nbsp;<anno>Data</anno>}}</c>
	  after <c><anno>Timeout</anno></c> milliseconds,
	  if the requested data has not been delivered.
	</p>
      </desc>
    </func>

    <func>
      <name name="recv" arity="3" clause_i="1" since="OTP 24.0"
	    anchor="recv-nowait"/>
      <name name="recv" arity="3" clause_i="2" since="OTP 24.0"/>
      <name name="recv" arity="3" clause_i="6" since="OTP 22.1"/>
      <name name="recv" arity="3" clause_i="7" since="OTP 24.0"/>
      <name name="recv" arity="4" clause_i="1" since="OTP 22.1"/>
      <name name="recv" arity="4" clause_i="2" since="OTP 24.0"/>
      <fsummary>Receive data from a socket, but do not wait.</fsummary>
      <desc>
        <p>
          Receives data from a socket,
          but returns a select continuation if the data
          could not be returned immediately.
        </p>
	<p>
	  The same as
	  <seeerl marker="#recv-infinity">
            infinite time-out <c>recv/1,2,3,4</c>
          </seeerl>
	  but if the data can not be delivered immediately,
	  the function returns
	  <seetype marker="#select_info"><c>{select,&nbsp;<anno>SelectInfo</anno>}</c></seetype>,
	  and the caller will then receive a select message,
	  <c>{'$socket',&nbsp;Socket,&nbsp;select,&nbsp;SelectHandle}</c>
          ( with the
	  <seetype marker="socket#select_handle"><c>SelectHandle</c></seetype>
	  contained in the
	  <seetype marker="#select_info">
	    <c><anno>SelectInfo</anno></c>
	  </seetype>
	  ) when data has arrived.
	  A subsequent call to <c>recv/1,2,3,4</c>
	  will then return the data.
	</p>
	<p>
	  If the time-out argument is <c>SelectHandle</c>,
	  that term will be contained in a returned
	  <c><anno>SelectInfo</anno></c>
	  and the corresponding select message.
	  The <c>SelectHandle</c> is presumed to be
	  unique to this call.
	</p>
	<p>
	  If the time-out argument is <c>nowait</c>, and a
	  <c><anno>SelectInfo</anno></c> is returned,
	  it will contain a
	  <seetype marker="socket#select_handle">
	    <c>select_handle()</c>
	  </seetype> generated by the call.
	</p>
	<p>
	  Note that for a socket of type <c>stream</c>,
          if <c><anno>Length</anno>&nbsp;&gt;&nbsp;0</c>
	  and only part of that amount of data is available,
	  the function will return
	  <seetype marker="#select_info">
	    <c>{ok, {<anno>Data</anno>, <anno>SelectInfo</anno></c>
	  </seetype>
	  with partial data.  If the caller doesn't want to wait
	  for more data, it must call
	  <seemfa marker="#cancel/2"><c>cancel/2</c></seemfa>
          to cancel the operation.
	</p>
      </desc>
    </func>

    <func>
      <name name="recvfrom" arity="1" since="OTP 22.0"
	    anchor="recvfrom-infinity"/>
      <name name="recvfrom" arity="2" clause_i="1" since="OTP 24.0"/>
      <name name="recvfrom" arity="2" clause_i="2" since="OTP 22.0"/>
      <name name="recvfrom" arity="3" clause_i="3" since="OTP 22.0"/>
      <name name="recvfrom" arity="3" clause_i="5" since="OTP 22.0"/>
      <name name="recvfrom" arity="3" clause_i="8" since="OTP 22.0"/>
      <name name="recvfrom" arity="4" clause_i="3" since="OTP 22.0"/>
      <fsummary>
        Receive a message from a socket, with "infinite" time-out.
      </fsummary>
      <desc>
        <p>
          Receive a message from a socket, waiting for it to arrive.
        </p>
	<p>
	  The function returns when a message is received,
          or when there is a socket error.
	  Argument <c><anno>BufSz</anno></c> specifies the
	  number of bytes for the receive buffer.
	  If the buffer size is too small,
	  the message will be truncated.
	</p>
	<p>
	  If <c><anno>BufSz</anno></c> is not specified or <c>0</c>,
	  a default buffer size is used, which can be set by
	  <seemfa marker="#setopt/3">
	    <c>socket:setopt(Socket, {otp,recvbuf}, <anno>BufSz</anno>)</c>.
	  </seemfa>
	</p>
	<p>
	  If it is impossible to know the appropriate buffer size,
	  it may be possible to use the receive
	  <seetype marker="#msg_flag">message flag</seetype>
	  <c>peek</c>.  When this flag is used, the message is
	  <em>not</em> "consumed" from the underlying buffers,
	  so another <c>recvfrom/1,2,3,4</c>
	  call is needed, possibly with an adjusted buffer size.
	</p>
        <p>
          The message <c>Flags</c> may be symbolic
          <seetype marker="#msg_flag"><c>msg_flag()</c></seetype>s and/or
          <c>integer()</c>s, as in the platform's appropriate header files.
          The values of all symbolic flags and integers are or:ed together.
        </p>
      </desc>
    </func>

    <func>
      <name name="recvfrom" arity="3" clause_i="4" since="OTP 22.0"
	    anchor="recvfrom-timeout"/>
      <name name="recvfrom" arity="3" clause_i="9" since="OTP 22.0"/>
      <name name="recvfrom" arity="4" clause_i="4" since="OTP 22.0"/>
      <fsummary>Receive a message from a socket, with time-out.</fsummary>
      <desc>
        <p>
          Receives a message from a socket, waiting at most
          <c><anno>Timeout</anno></c> milliseconds for it to arrive.
        </p>
	<p>
	  The same as
	  <seeerl marker="#recvfrom-infinity">
            infinite time-out <c>recvfrom/1,2,3,4</c>
          </seeerl>
	  but returns <c>{error,&nbsp;timeout}</c>
	  after <c><anno>Timeout</anno></c> milliseconds,
	  if no message has been delivered.
	</p>
      </desc>
    </func>

    <func>
      <name name="recvfrom" arity="3" clause_i="1" since="OTP 22.1"
	    anchor="recvfrom-nowait"/>
      <name name="recvfrom" arity="3" clause_i="2" since="OTP 24.0"/>
      <name name="recvfrom" arity="3" clause_i="6" since="OTP 22.1"/>
      <name name="recvfrom" arity="3" clause_i="7" since="OTP 24.0"/>
      <name name="recvfrom" arity="4" clause_i="1" since="OTP 22.1"/>
      <name name="recvfrom" arity="4" clause_i="2" since="OTP 24.0"/>
      <fsummary>Receive a message from a socket, but do not wait.</fsummary>
      <desc>
        <p>
          Receives a message from a socket,
          but returns a select continuation if no message
          could be returned immediately.
        </p>
	<p>
	  The same as
	  <seeerl marker="#recvfrom-infinity">
            infinite time-out <c>recvfrom/1,2,3,4</c>
          </seeerl>
	  but if no message can not delivered immediately,
	  the function returns
	  <seetype marker="#select_info"><c>{select,&nbsp;<anno>SelectInfo</anno>}</c></seetype>,
	  and the caller will then receive a select message,
	  <c>{'$socket',&nbsp;Socket,&nbsp;select,&nbsp;SelectHandle}</c>
          ( with the
	  <seetype marker="socket#select_handle"><c>SelectHandle</c></seetype>
	  contained in the
	  <seetype marker="#select_info">
	    <c><anno>SelectInfo</anno></c>
	  </seetype>
	  ) when data has arrived.
	  A subsequent call to <c>recvfrom/1,2,3,4</c>
	  will then return the message.
	</p>
	<p>
	  If the time-out argument is <c>SelectHandle</c>,
	  that term will be contained in a returned
	  <c><anno>SelectInfo</anno></c>
	  and the corresponding select message.
	  The <c>SelectHandle</c> is presumed to be
	  unique to this call.
	</p>
	<p>
	  If the time-out argument is <c>nowait</c>, and a
	  <c><anno>SelectInfo</anno></c> is returned,
	  it will contain a
	  <seetype marker="socket#select_handle">
	    <c>select_handle()</c>
	  </seetype> generated by the call.
	</p>
      </desc>
    </func>

    <func>
      <name name="recvmsg" arity="1" since="OTP 22.0"
            anchor="recvmsg-infinity"/>
      <name name="recvmsg" arity="2" clause_i="1" since="OTP 22.0"/>
      <name name="recvmsg" arity="2" clause_i="4" since="OTP 22.0"/>
      <name name="recvmsg" arity="3" clause_i="3" since="OTP 22.0"/>
      <name name="recvmsg" arity="3" clause_i="5" since="OTP 22.0"/>
      <name name="recvmsg" arity="4" clause_i="3" since="OTP 24.0"/>
      <name name="recvmsg" arity="5" clause_i="3" since="OTP 22.0"/>
      <fsummary>
        Receive a message from a socket, with "infinite" time-out.
      </fsummary>
      <desc>
        <p>
          Receive a message from a socket, waiting for it to arrive.
        </p>
	<p>
	  The function returns when a message is received,
          or when there is a socket error.
	  Arguments <c><anno>BufSz</anno></c>
	  and <c><anno>CtrlSz</anno></c> specifies the
	  number of bytes for the receive buffer
	  and the control message buffer.
	  If the buffer size(s) is(are) too small,
	  the message and/or control message list will be truncated.
	</p>
	<p>
	  If <c><anno>BufSz</anno></c> is not specified or <c>0</c>,
	  a default buffer size is used, which can be set by
	  <seemfa marker="#setopt/3">
	    <c>socket:setopt(Socket, {otp,recvbuf}, <anno>BufSz</anno>)</c>.
	  </seemfa>
	  The same applies to <c><anno>CtrlSz</anno></c> and
	  <seemfa marker="#setopt/3">
	    <c>socket:setopt(Socket, {otp,recvctrlbuf},
	    <anno>CtrlSz</anno>)</c>.
	  </seemfa>
	</p>
	<p>
	  If it is impossible to know the appropriate buffer size,
	  it may be possible to use the receive
	  <seetype marker="#msg_flag">message flag</seetype>
	  <c>peek</c>.  When this flag is used, the message is
	  <em>not</em> "consumed" from the underlying buffers,
	  so another <c>recvfrom/1,2,3,4,5</c>
	  call is needed, possibly with an adjusted buffer size.
	</p>
        <p>
          The message <c>Flags</c> may be symbolic
          <seetype marker="#msg_flag"><c>msg_flag()</c></seetype>s and/or
          <c>integer()</c>s, as in the platform's appropriate header files.
          The values of all symbolic flags and integers are or:ed together.
        </p>
      </desc>
    </func>

    <func>
      <name name="recvmsg" arity="2" clause_i="5" since="OTP 22.0"
            anchor="recvmsg-timeout"/>
      <name name="recvmsg" arity="3" clause_i="4" since="OTP 22.0"/>
      <name name="recvmsg" arity="4" clause_i="4" since="OTP 24.0"/>
      <name name="recvmsg" arity="5" clause_i="4" since="OTP 22.0"/>
      <fsummary>Receive a message from a socket, with time-out.</fsummary>
      <desc>
        <p>
          Receives a message from a socket, waiting at most
          <c><anno>Timeout</anno></c> milliseconds for it to arrive.
        </p>
	<p>
	  The same as
	  <seeerl marker="#recvmsg-infinity">recvmsg/1,2,3,4,5</seeerl>
	  but returns <c>{error,&nbsp;timeout}</c>
	  after <c><anno>Timeout</anno></c> milliseconds,
	  if no message has been delivered.
	</p>
      </desc>
    </func>

    <func>
      <name name="recvmsg" arity="2" clause_i="2" since="OTP 22.1"
            anchor="recvmsg-nowait"/>
      <name name="recvmsg" arity="2" clause_i="3" since="OTP 24.0"/>
      <name name="recvmsg" arity="3" clause_i="1" since="OTP 22.1"/>
      <name name="recvmsg" arity="3" clause_i="2" since="OTP 24.0"/>
      <name name="recvmsg" arity="4" clause_i="1" since="OTP 24.0"/>
      <name name="recvmsg" arity="4" clause_i="2" since="OTP 24.0"/>
      <name name="recvmsg" arity="5" clause_i="1" since="OTP 22.1"/>
      <name name="recvmsg" arity="5" clause_i="2" since="OTP 24.0"/>
      <fsummary>Receive a message from a socket, but do not wait.</fsummary>
      <desc>
        <p>
          Receives a message from a socket,
          but returns a select continuation if no message
          could be returned immediately.
        </p>
	<p>
	  The same as
	  <seeerl marker="#recvfrom-infinity">
            infinite time-out <c>recvfrom/1,2,3,4</c>
          </seeerl>
	  but if no message can not delivered immediately,
	  the function returns
	  <seetype marker="#select_info"><c>{select,&nbsp;<anno>SelectInfo</anno>}</c></seetype>,
	  and the caller will then receive a select message,
	  <c>{'$socket',&nbsp;Socket,&nbsp;select,&nbsp;SelectHandle}</c>
          ( with the
	  <seetype marker="socket#select_handle"><c>SelectHandle</c></seetype>
	  contained in the
	  <seetype marker="#select_info">
	    <c><anno>SelectInfo</anno></c>
	  </seetype>
	  ) when data has arrived.
	  A subsequent call to <c>recvmsg/1,2,3,4,5</c>
	  will then return the data.
	</p>
	<p>
	  If the time-out argument is <c>SelectHandle</c>,
	  that term will be contained in a returned
	  <c><anno>SelectInfo</anno></c>
	  and the corresponding select message.
	  The <c>SelectHandle</c> is presumed to be
	  unique to this call.
	</p>
	<p>
	  If the time-out argument is <c>nowait</c>, and a
	  <c><anno>SelectInfo</anno></c> is returned,
	  it will contain a
	  <seetype marker="socket#select_handle">
	    <c>select_handle()</c>
	  </seetype> generated by the call.
	</p>
      </desc>
    </func>

    <func>
      <name name="send" arity="2" since="OTP 22.0"
            anchor="send-infinity"/>
      <name name="send" arity="3" clause_i="1" since="OTP 22.0"/>
      <name name="send" arity="3" clause_i="5" since="OTP 22.0"/>
      <name name="send" arity="4" clause_i="3" since="OTP 22.0"/>
      <fsummary>
        Send data on a connected socket, with "infinite" time-out.
      </fsummary>
      <desc>
        <p>
          Sends data on a connected socket, waiting for it to be sent.
        </p>
	<p>
	  This call will not return until the <c><anno>Data</anno></c>
          has been accepted by the platform's network layer,
          or it reports an error.
	</p>
        <p>
          The message <c><anno>Flags</anno></c> may be symbolic
          <seetype marker="#msg_flag"><c>msg_flag()</c></seetype>s
          and/or <c>integer()</c>s, matching the platform's
          appropriate header files.
          The values of all symbolic flags and integers are or:ed together.
        </p>
        <p>
          The <c><anno>Data</anno></c>, if it is not a <c>binary()</c>,
          is copied into one before calling the platform network API,
          because a single buffer is required.  A returned
          <c><anno>RestData</anno></c> is a sub binary
          of this data binary.
        </p>
        <p>
          The return value indicates the result from
          the platform's network layer:
        </p>
        <taglist>
          <tag><c>ok</c></tag>
          <item>
            <p>
              All data has been accepted.
            </p>
          </item>
          <tag><c>{ok,&nbsp;<anno>RestData</anno>}</c></tag>
          <item>
            <p>
              Not all data has been accepted,
              but no error has been reported.
              <c><anno>RestData</anno></c> is the tail of
              <c><anno>Data</anno></c> that has not been accepted.
            </p>
            <p>
              This can not happen for a socket of
              <seetype marker="#type">type <c>stream</c></seetype>
              where a partially succesful send is retried until
              the data is either accepted or there is an error.
            </p>
            <p>
              For a socket of
              <seetype marker="#type">type <c>dgram</c></seetype>
              this should probably also not happen since a message
              that can not be passed atomically should render an error.
            </p>
            <p>
              It is nevertheless possible for the platform's network layer
              to return this.
            </p>
          </item>
          <tag><c>{error,&nbsp;<anno>Reason</anno>}</c></tag>
          <item>
            <p>
              An error has been reported and no data has been accepted.
              The <seetype marker="#posix"><c>posix()</c></seetype>
              <c><anno>Reason</anno>s</c> are from the
              platform's network layer.
              <c>closed</c> means that this socket library
              knows that the socket is closed, and
              <seetype marker="#invalid"><c>invalid()</c></seetype>
              means that something about an argument is invalid.
            </p>
          </item>
          <tag>
            <c>
              {error,&nbsp;{<anno>Reason</anno>,&nbsp;<anno>RestData</anno>}}
            </c>
          </tag>
          <item>
            <p>
              An error has been reported
              but before that some data was accepted.
              <c><anno>RestData</anno></c> is the tail of
              <c><anno>Data</anno></c> that has not been accepted.
              See <c>{error,&nbsp;<anno>Reason</anno>}</c> above.
            </p>
            <p>
              This can only happen for a socket of
              <seetype marker="#type">type <c>stream</c></seetype>
              when a partially succesful send is retried
              untill there is an error.
            </p>
          </item>
        </taglist>
      </desc>
    </func>

    <func>
      <name name="send" arity="3" clause_i="6" since="OTP 22.0"
            anchor="send-timeout"/>
      <name name="send" arity="4" clause_i="4" since="OTP 22.0"/>
      <fsummary>Send data on a connected socket, with time-out.</fsummary>
      <desc>
        <p>
          Sends data on a connected socket, waiting at most
          <c><anno>Timeout</anno></c> milliseconds for it to be sent.
        </p>
	<p>
	  The same as
	  <seeerl marker="#send-infinity">
            infinite time-out <c>send/2,3,4</c>
          </seeerl>
	  but returns <c>{error,&nbsp;timeout}</c>
          or <c>{error,&nbsp;{timeout,&nbsp;<anno>RestData</anno>}}</c>
	  after <c><anno>Timeout</anno></c> milliseconds,
	  if no <c><anno>Data</anno></c> or only some of it
          was accepted by the platform's network layer.
	</p>
      </desc>
    </func>

    <func>
      <name name="send" arity="3" clause_i="3" since="OTP 22.1"
	    anchor="send-nowait"/>
      <name name="send" arity="3" clause_i="4" since="OTP 24.0"/>
      <name name="send" arity="4" clause_i="1" since="OTP 22.1"/>
      <name name="send" arity="4" clause_i="2" since="OTP 24.0"/>
      <fsummary>Send data on a connected socket, but do not wait.</fsummary>
      <desc>
        <p>
          Sends data on a connected socket,
          but return a select continuation if the data
          could not be sent immediately.
        </p>
	<p>
	  The same as
	  <seeerl marker="#send-infinity">
            infinite time-out <c>send/2,3</c>
          </seeerl>
	  but if the data is not immediately accepted by
	  the platform network layer, the function returns
	  <seetype marker="#select_info"><c>{select,&nbsp;<anno>SelectInfo</anno>}</c></seetype>,
	  and the caller will then receive a select message,
	  <c>{'$socket',&nbsp;Socket,&nbsp;select,&nbsp;SelectHandle}</c> (
	  with the
	  <seetype marker="socket#select_handle"><c>SelectHandle</c></seetype>
	  that was contained in the
	  <seetype marker="#select_info">
	    <c><anno>SelectInfo</anno></c>
	  </seetype>
	  ) when there is room for more data.
	  A subsequent call to <c>send/2-4</c> will then send the data.
	</p>
	<p>
	  If <c>SelectHandle</c> is a
          <seetype marker="#select_handle"><c>select_handle()</c></seetype>,
	  that term will be contained in a returned
	  <c><anno>SelectInfo</anno></c>
	  and the corresponding select message.
	  The <c>SelectHandle</c> is presumed to be
	  unique to this call.
	</p>
	<p>
	  If <c>SelectHandle</c> is <c>nowait</c>, and a
	  <c><anno>SelectInfo</anno></c> is returned,
	  it will contain a
	  <seetype marker="socket#select_handle">
	    <c>select_handle()</c>
	  </seetype> generated by the call.
	</p>
	<p>
	  If some of the data was sent, the function will return
	  <seetype marker="#select_info">
	    <c>
              {ok,&nbsp;{<anno>RestData</anno>,&nbsp;<anno>SelectInfo</anno>},
            </c>
	  </seetype>
          which can only happen for a socket of
          <seetype marker="#type">type <c>stream</c></seetype>.
	  If the caller does not want to wait to send the rest of the data,
	  it should cancel the operation with
	  <seemfa marker="#cancel/2"><c>cancel/2</c></seemfa>.
        </p>
      </desc>
    </func>

    <func>
      <name name="send" arity="3" clause_i="2" since="OTP 24.0"
	    anchor="send-cont"/>
      <name name="send" arity="4" clause_i="7" since="OTP 24.0"/>
      <name name="send" arity="4" clause_i="8" since="OTP 24.0"/>
      <name name="send" arity="4" clause_i="5" since="OTP 24.0"/>
      <name name="send" arity="4" clause_i="6" since="OTP 24.0"/>
      <fsummary>Send data on a connected socket, continuation.</fsummary>
      <desc>
        <p>
          Continues sending data on a connected socket, where the
          send operation was initiated by
          <seeerl marker="#send-nowait"><c>send/3,4</c></seeerl>
          that returned a <c>SelectInfo</c> continuation.
          Otherwise like
          <seeerl marker="#send-infinity">
            infinite time-out <c>send/2,3,4</c>
          </seeerl>
          ,
          <seeerl marker="#send-timeout">
            limited time-out <c>send/3,4</c>
          </seeerl>
          or
          <seeerl marker="#send-nowait">
            nowait <c>send/3,4</c>
          </seeerl>
          respectively.
        </p>
	<p>
          <c><anno>Cont</anno></c> is the <c>SelectInfo</c>
          that was returned from the previous <c>send()</c> call.
	</p>
        <p>
          If <c><anno>Data</anno></c> is not a <c>binary()</c>,
          it will be copied into one, again.
        </p>
        <p>
          The return value indicates the result from
          the platform's network layer.
          See
          <seeerl marker="#send-infinity"><c>send/2,3,4</c></seeerl>
          and
          <seeerl marker="#send-nowait">nowait <c>send/3,4</c></seeerl>.
        </p>
      </desc>
    </func>

    <func>
      <name name="sendmsg" arity="2" since="OTP 22.0"
            anchor="sendmsg-infinity"/>
      <name name="sendmsg" arity="3" clause_i="1" since="OTP 22.0"/>
      <name name="sendmsg" arity="3" clause_i="5" since="OTP 22.0"/>
      <name name="sendmsg" arity="4" clause_i="3" since="OTP 22.0"/>
      <fsummary>Send a message on a socket, with "infinite" time-out.</fsummary>
      <desc>
	<p>
          Sends a message on a socket, waiting for it to be sent.
        </p>
	<p>
	  The destination, if needed,
          that is: if the socket is <em>not</em> connected,
	  is provided in <c><anno>Msg</anno></c>,
	  which also contains the data to send
          as a
          <seetype marker="erts:erlang#iovec">list of binaries</seetype>.
	  <c>Msg</c> may also contain an list of optional
	  <seetype marker="#cmsg_send">control messages</seetype>
	  (depending on what the protocol and platform supports).
	</p>
        <p>
          For a connected socket no address field should be
          present in <c><anno>Msg</anno></c>,
          the platform may return an error or ignore one.
        </p>
        <p>
          The message data is given to to the platform's network layer
          in the form of an I/O vector without copying the content.
          If the number of elements in the I/O vector is larger than
          allowed on the platform
          (reported in the
          <seetype marker="#info"><c>iov_max</c></seetype>
          field from
          <seemfa marker="#info/0">info/0</seemfa>),
          on a socket of
          <seetype marker="#type">type <c>stream</c></seetype>
          the send is iterated over all elements,
          but for other socket types the call fails.
        </p>
	<p>
	  This call will not return until the data has been
	  handed over to the platform's network layer,
          or when it reports an error.
	</p>
        <p>
          The message <c><anno>Flags</anno></c> may be symbolic
          <seetype marker="#msg_flag"><c>msg_flag()</c></seetype>s
          and/or <c>integer()</c>s, matching the platform's
          appropriate header files.
          The values of all symbolic flags and integers are or:ed together.
        </p>
        <p>
          The return value indicates the result from
          the platform's network layer.
          See <seeerl marker="#send-infinity"><c>send/2,3,4</c></seeerl>.
        </p>
      </desc>
    </func>

    <func>
      <name name="sendmsg" arity="3" clause_i="6" since="OTP 22.0"
            anchor="sendmsg-timeout"/>
      <name name="sendmsg" arity="4" clause_i="4" since="OTP 22.0"/>
      <fsummary>Send a message on a socket, with time-out.</fsummary>
      <desc>
        <p>
          Sends a message on a socket, waiting at most
          <c><anno>Timeout</anno></c> milliseconds for it to be sent.
        </p>
	<p>
	  The same as
	  <seeerl marker="#sendmsg-infinity">
            infinite time-out <c>sendmsg/2,3,4</c>
          </seeerl>
	  but returns <c>{error, timeout}</c>
          or <c>{error,&nbsp;{timeout,&nbsp;<anno>RestData</anno>}}</c>
          after <c><anno>Timeout</anno></c> milliseconds,
	  if no data or only some of it
          was accepted by the platform's network layer.
	</p>
      </desc>
    </func>

    <func>
      <name name="sendmsg" arity="3" clause_i="3" since="OTP 22.1"
	    anchor="sendmsg-nowait"/>
      <name name="sendmsg" arity="3" clause_i="4" since="OTP 24.0"/>
      <name name="sendmsg" arity="4" clause_i="1" since="OTP 22.1"/>
      <name name="sendmsg" arity="4" clause_i="2" since="OTP 24.0"/>
      <fsummary>Send a message on a socket, but do not wait.</fsummary>
      <desc>
        <p>
          Sends a message on a socket,
          but return a select continuation if the data
          could not be sent immediately.
        </p>
	<p>
	  The same as
	  <seeerl marker="#sendmsg-infinity">
            infinity time-out <c>sendmsg/2,3</c>
          </seeerl>
	  but if the data is not immediately accepted by
	  the platform network layer, the function returns
	  <seetype marker="#select_info"><c>{select,&nbsp;<anno>SelectInfo</anno>}</c></seetype>,
	  and the caller will then receive a select message,
	  <c>{'$socket',&nbsp;Socket,&nbsp;select,&nbsp;SelectHandle}</c> (
	  with the
	  <seetype marker="socket#select_handle"><c>SelectHandle</c></seetype>
	  that was contained in the
	  <seetype marker="#select_info">
	    <c><anno>SelectInfo</anno></c>
	  </seetype>
	  ) when there is room for more data.
	  A subsequent call to <c>sendmsg/2-4</c> will then send the data.
	</p>
	<p>
	  If <c>SelectHandle</c>, is a
          <seetype marker="#select_handle"><c>select_handle()</c></seetype>,
	  that term will be contained in a returned
	  <c><anno>SelectInfo</anno></c>
	  and the corresponding select message.
	  The <c>SelectHandle</c> is presumed to be
	  unique to this call.
	</p>
	<p>
	  If <c>SelectHandle</c> is <c>nowait</c>, and a
	  <c><anno>SelectInfo</anno></c> is returned,
	  it will contain a
	  <seetype marker="socket#select_handle">
	    <c>select_handle()</c>
	  </seetype> generated by the call.
	</p>
	<p>
	  If some of the data was sent, the function will return
	  <seetype marker="#select_info">
	    <c>
              {ok,&nbsp;{<anno>RestData</anno>,&nbsp;<anno>SelectInfo</anno>},
            </c>
	  </seetype>
          which can only happen for a socket of
          <seetype marker="#type">type <c>stream</c></seetype>.
	  If the caller does not want to wait to send the rest of the data,
	  it should cancel the operation with
	  <seemfa marker="#cancel/2"><c>cancel/2</c></seemfa>.
        </p>
      </desc>
    </func>

    <func>
      <name name="sendmsg" arity="3" clause_i="2" since="OTP 24.0"
	    anchor="sendmsg-cont"/>
      <name name="sendmsg" arity="4" clause_i="7" since="OTP 24.0"/>
      <name name="sendmsg" arity="4" clause_i="8" since="OTP 24.0"/>
      <name name="sendmsg" arity="4" clause_i="5" since="OTP 24.0"/>
      <name name="sendmsg" arity="4" clause_i="6" since="OTP 24.0"/>
      <fsummary>Send a message on a socket, continuation.</fsummary>
      <desc>
        <p>
          Continues sending a message data on a socket, where the
          send operation was initiated by
          <seeerl marker="#sendmsg-nowait"><c>sendmsg/3,4</c></seeerl>
          that returned a <c>SelectInfo</c> continuation.
          Otherwise like
          <seeerl marker="#sendmsg-infinity">
            infinite time-out <c>sendmsg/2,3,4</c>
          </seeerl>
          ,
          <seeerl marker="#sendmsg-timeout">
            limited time-out <c>sendmsg/3,4</c>
          </seeerl>
          or
          <seeerl marker="#sendmsg-nowait">
            nowait <c>sendmsg/3,4</c>
          </seeerl>
          respectively.
        </p>
	<p>
          <c><anno>Cont</anno></c> is the <c>SelectInfo</c>
          that was returned from the previous <c>sendmsg()</c> call.
	</p>
        <p>
          The return value indicates the result from
          the platform's network layer.
          See
          <seeerl marker="#send-infinity"><c>send/2,3,4</c></seeerl>
          and
          <seeerl marker="#sendmsg-nowait">nowait <c>sendmsg/3,4</c></seeerl>.
        </p>
      </desc>
    </func>

    <func>
      <name name="sendto" arity="3" clause_i="1" since="OTP 22.0"
	    anchor="sendto-infinity"/>
      <name name="sendto" arity="4" clause_i="1" since="OTP 22.0"/>
      <name name="sendto" arity="4" clause_i="4" since="OTP 22.0"/>
      <name name="sendto" arity="5" clause_i="3" since="OTP 22.0"/>
      <fsummary>Send data on a socket, with "infinite" time-out.</fsummary>
      <desc>
        <p>
          Sends data on a socket, to the specified destination,
          waiting for it to be sent.
        </p>
	<p>
	  This call will not return until the data has been accepted
          by the platform's network layer, or it reports an error.
	</p>
        <p>
          If this call is used on a connection mode socket
          or on a connected socket, the platforms's network layer
          may return an error or ignore the destination address.
        </p>
        <p>
          The message <c>Flags</c> may be symbolic
          <seetype marker="#msg_flag"><c>msg_flag()</c></seetype>s and/or
          <c>integer()</c>s, matching the platform's appropriate header files.
          The values of all symbolic flags and integers are or:ed together.
        </p>
        <p>
          The return value indicates the result from
          the platform's network layer.
          See <seeerl marker="#send-infinity"><c>send/2,3,4</c></seeerl>.
        </p>
      </desc>
    </func>

    <func>
      <name name="sendto" arity="4" clause_i="5" since="OTP 22.0"
	    anchor="sendto-timeout"/>
      <name name="sendto" arity="5" clause_i="4" since="OTP 22.0"/>
      <fsummary>Send data on a socket, with time-out.</fsummary>
      <desc>
        <p>
          Sends data on a socket, waiting at most
          <c><anno>Timeout</anno></c> milliseconds for it to be sent.
        </p>
	<p>
	  The same as
	  <seeerl marker="#sendto-infinity">
            infinite time-out <c>sendto/3,4,5</c>
          </seeerl>
	  but returns <c>{error,&nbsp;timeout}</c>
          or <c>{error,&nbsp;{timeout,&nbsp;<anno>RestData</anno>}}</c>
	  after <c><anno>Timeout</anno></c> milliseconds,
	  if no <c><anno>Data</anno></c> or only some of it
          was accepted by the platform's network layer.
	</p>
      </desc>
    </func>

    <func>
      <name name="sendto" arity="4" clause_i="2" since="OTP 22.1"
	    anchor="sendto-nowait"/>
      <name name="sendto" arity="4" clause_i="3" since="OTP 24.0"/>
      <name name="sendto" arity="5" clause_i="1" since="OTP 22.1"/>
      <name name="sendto" arity="5" clause_i="2" since="OTP 24.0"/>
      <fsummary>Send data on a socket, but do not wait.</fsummary>
      <desc>
        <p>
          Sends data on a socket,
          but return a select continuation if the data
          could not be sent immediately.
        </p>
	<p>
	  The same as
	  <seeerl marker="#sendto-infinity">
            infinity time-out <c>sendto/3,4</c>
          </seeerl>
	  but if the data is not be immediately accepted
	  by the platform network layer,
	  the function returns
	  <seetype marker="#select_info"><c>{select,&nbsp;<anno>SelectInfo</anno>}</c></seetype>,
	  and the caller will then receive a select message,
	  <c>{'$socket',&nbsp;Socket,&nbsp;select,&nbsp;SelectHandle}</c> (
	  with the
	  <seetype marker="socket#select_handle"><c>SelectHandle</c></seetype>
	  that was contained in the
	  <seetype marker="#select_info">
	    <c><anno>SelectInfo</anno></c>
	  </seetype>
	  ) when there is room for more data.
	  A subsequent call to <c>sendto/3-5</c> will then send the data.
	</p>
	<p>
	  If <c>SelectHandle</c> is a
          <seetype marker="#select_handle"><c>select_handle()</c></seetype>,
	  that term will be contained in a returned
	  <c><anno>SelectInfo</anno></c>
	  and the corresponding select message.
	  The <c>SelectHandle</c> is presumed to be
	  unique to this call.
	</p>
	<p>
	  If <c>SelectHandle</c> is <c>nowait</c>, and a
	  <c><anno>SelectInfo</anno></c> is returned,
	  it will contain a
	  <seetype marker="socket#select_handle">
	    <c>select_handle()</c>
	  </seetype> generated by the call.
	</p>
	<p>
	  If some of the data was sent, the function will return
	  <seetype marker="#select_info">
	    <c>
              {ok,&nbsp;{<anno>RestData</anno>,&nbsp;<anno>SelectInfo</anno>},
            </c>
	  </seetype>
          which can only happen for a socket of
          <seetype marker="#type">type <c>stream</c></seetype>.
	  If the caller does not want to wait to send the rest of the data,
	  it should cancel the operation with
	  <seemfa marker="#cancel/2"><c>cancel/2</c></seemfa>.
        </p>
      </desc>
    </func>

    <func>
      <name name="sendto" arity="3" clause_i="2" since="OTP 24.0"
	    anchor="sendto-cont"/>
      <name name="sendto" arity="4" clause_i="8" since="OTP 24.0"/>
      <name name="sendto" arity="4" clause_i="9" since="OTP 24.0"/>
      <name name="sendto" arity="4" clause_i="6" since="OTP 24.0"/>
      <name name="sendto" arity="4" clause_i="7" since="OTP 24.0"/>
      <fsummary>Send data on a socket, continuation.</fsummary>
      <desc>
        <p>
          Continues sending data on a socket, where the
          send operation was initiated by
          <seeerl marker="#sendto-nowait"><c>sendto/4,5</c></seeerl>
          that returned a <c>SelectInfo</c> continuation.
          Otherwise like
          <seeerl marker="#sendto-infinity">
            infinite time-out <c>sendto/3,4,5</c>
          </seeerl>
          ,
          <seeerl marker="#sendto-timeout">
            limited time-out <c>sendto/4,5</c>
          </seeerl>
          or
          <seeerl marker="#sendto-nowait">
            nowait <c>sendto/4,5</c>
          </seeerl>
          respectively.
        </p>
	<p>
          <c><anno>Cont</anno></c> is the <c>SelectInfo</c>
          that was returned from the previous <c>sendto()</c> call.
	</p>
        <p>
          If <c><anno>Data</anno></c> is not a <c>binary()</c>,
          it will be copied into one, again.
        </p>
        <p>
          The return value indicates the result from
          the platform's network layer.
          See
          <seeerl marker="#send-infinity"><c>send/2,3,4</c></seeerl>
          and
          <seeerl marker="#sendto-nowait">nowait <c>sendto/4,5</c></seeerl>.
        </p>
      </desc>
    </func>

    <func>
      <name name="setopt" arity="3" clause_i="1" since="OTP 22.0"/>
      <fsummary>
	Set a socket option in the protocol level <c>otp</c>.
      </fsummary>
      <desc>
        <p>
	  Sets a socket option in the protocol level <c>otp</c>,
	  which is this implementation's level
	  above the OS protocol layers.
	</p>
	<p>
	  See the type
	  <seetype marker="#otp_socket_option">
	    otp_socket_option()
	  </seetype>
	  for a description of the options on this level.
	</p>
      </desc>
    </func>

    <func>
      <name name="setopt" arity="3" clause_i="2" since="OTP 22.0"/>
      <fsummary>
	Set a socket option in one of the OS's protocol levels.
      </fsummary>
      <desc>
        <p>
	  Set a socket option in one of the OS's protocol levels.
	  See the type
	  <seetype marker="#socket_option">socket_option()</seetype>
	  for which options that this implementation knows about,
	  how they are related to option names in the OS,
	  and if there are known pecularities with any of them.
	</p>
	<p>
	  What options are valid depends on what kind of socket it is
	  (<seetype marker="#domain"><c>domain()</c></seetype>,
	  <seetype marker="#type"><c>type()</c></seetype> and
	  <seetype marker="#protocol"><c>protocol()</c></seetype>).
	</p>
	<p>
	  See the
	  <seeguide marker="socket_usage#socket_options">
	    socket options
	  </seeguide>
	  chapter of the users guide for more info.
	</p>
	<note>
	  <p>
	    Not all options are valid, nor possible to set,
	    on all platforms.
	    That is, even if "we" support an option;
	    it does not mean that the underlying OS does.
	  </p>
	</note>
      </desc>
    </func>

    <func>
      <!--
	  Backwards compatibility function - remove documentation?
	  Document the Native clause?
      -->
      <name since="OTP 22.0">
	setopt(Socket, Level, Opt, Value) -> ok | {error, Reason}
      </name>
      <fsummary>
	Set a socket protocol option.
      </fsummary>
      <type>
	<v>
	  Socket = <seetype marker="#socket">socket()</seetype>
	</v>
	<v>
	  Value = term()
	</v>
	<v>
	  Reason = <seetype marker="inet#posix">inet:posix()</seetype>
	  | <seetype marker="#invalid"><c>invalid()</c></seetype>
	  | closed
	</v>
      </type>
      <desc>
	<p>Backwards compatibility function.</p>
        <p>
	  The same as
	  <seemfa marker="#setopt/3">
	    <c>setopt(Socket, {Level, Opt}, Value)</c>
	  </seemfa>
	</p>
      </desc>
    </func>

    <func>
      <name name="setopt_native" arity="3" since="OTP 22.0"/>
      <fsummary>Set a "native" socket option.</fsummary>
      <desc>
        <p>
	  Sets a socket option that may be unknown to our
	  implementation, or that has a type not compatible
	  with our implementation, that is; in "native mode".
	</p>
	<p>
	  If <c><anno>Value</anno></c> is an <c>integer()</c>
	  it will be used as a <c>C</c> type <c>(int)</c>,
	  if it is a <c>boolean()</c> it will be used
	  as a <c>C</c> type <c>(int)</c> with the <c>C</c>
	  implementations values for <c>false</c> or <c>true</c>,
	  and if it is a <c>binary()</c> its content and size
	  will be used as the option value.
	</p>
	<p>
	  The socket option may be specified with an ordinary
	  <seetype marker="#socket_option">
	    <c>socket_option()</c>
	  </seetype>
	  tuple, with a known 
	  <seetype marker="#level">
	    <c><anno>Level</anno> = level()</c>
	  </seetype>
	  and an integer <c><anno>NativeOpt</anno></c>,
	  or with both an integer <c><anno>NativeLevel</anno></c>
	  and <c><anno>NativeOpt</anno></c>.
	</p>
	<p>
	  What options are valid depends on what kind of socket it is
	  (<seetype marker="#domain"><c>domain()</c></seetype>,
	  <seetype marker="#type"><c>type()</c></seetype> and
	  <seetype marker="#protocol"><c>protocol()</c></seetype>).
	</p>
	<p>
	  The integer values for 
	  <c><anno>NativeLevel</anno></c> and
	  <c><anno>NativeOpt</anno></c>
	  as well as the encoding of <c><anno>Value</anno></c>
	  has to be deduced from the header files for
	  the running system.
	</p>
      </desc>
    </func>

    <func>
      <name name="shutdown" arity="2" since="OTP 22.0"/>
      <fsummary>Shut down part of a full-duplex connection.</fsummary>
      <desc>
        <p>Shut down all or part of a full-duplex connection.</p>
      </desc>
    </func>

    <func>
      <name name="sockname" arity="1" since="OTP 22.0"/>
      <fsummary>Get socket name.</fsummary>
      <desc>
        <p>Returns the current address to which the socket is bound.</p>
      </desc>
    </func>

    <func>
      <name name="supports" arity="0" since="OTP 22.0"/>
      <name name="supports" arity="1" since="OTP 22.0"/>
      <name name="supports" arity="2" since="OTP 22.0"/>
      <fsummary>Report info about what the platform supports.</fsummary>
      <desc>
	<p>
	  These functions function retreives information about what the
	  platform supports, such which platform features
	  or which socket options, are supported.
	</p>
	<p>
	  For keys other than the known the empty list is returned,
	  Note that in a future version or on a different platform
	  there might be more supported items.
	</p>
	<taglist>
	  <tag><c>supports()</c></tag>
	  <item>
 	    <p>
	      Returns a list of
	      <c>{<anno>Key1</anno>, supports(Key1)}</c> tuples
	      for every <c><anno>Key1</anno></c> described in
	      <seemfa marker="#supports/1">supports/1</seemfa> and
	      <c>{<anno>Key1</anno>, boolean()}</c> tuples
	      for each of the following keys:
	    </p>
	    <taglist>
	      <tag><c>sctp</c></tag>
	      <item>SCTP support</item>
	      <tag><c>ipv6</c></tag>
	      <item>IPv6 support</item>
	      <tag><c>local</c></tag>
	      <item>
		Unix Domain sockets support (<c>AF_UNIX | AF_LOCAL</c>)
	      </item>
	      <tag><c>netns</c></tag>
	      <item>
		Network Namespaces support (Linux, <c>setns(2)</c>)
	      </item>
	    </taglist>
	    <p></p>
	  </item>
	  <tag><c>supports(msg_flags = <anno>Key1</anno>)</c></tag>
	  <item>
	    <p>
	      Returns a list of 
	      <c>{Flag, boolean()}</c> tuples
	      for every <c>Flag</c> in
	      <seetype marker="#msg_flag">
		<c>msg_flag()</c>
	      </seetype>
	      with the <c>boolean()</c> indicating if the flag
	      is supported on this platform.
 	    </p>
	  </item>
	  <tag><c>supports(protocols = <anno>Key1</anno>)</c></tag>
	  <item>
 	    <p>
	      Returns a list of 
	      <c>{Name :: atom(), boolean()}</c> tuples
	      for every <c>Name</c> in
	      <seetype marker="#protocol">
		<c>protocol()</c>
	      </seetype>
	      with the <c>boolean()</c> indicating if the protocol
	      is supported on this platform.
	    </p>
	  </item>
	  <tag><c>supports(options = <anno>Key1</anno>)</c></tag>
	  <item>
	    <p>
	      Returns a list of
	      <c>{SocketOption, boolean()}</c> tuples
	      for every <c>SocketOption</c> in
	      <seetype marker="#socket_option">
		<c>socket_option()</c>
	      </seetype>
	      with the <c>boolean()</c> indicating if
	      the socket option is supported on this platform.
 	    </p>
	  </item>
	  <tag>
	    <c>
	      supports(options = <anno>Key1</anno>, <anno>Key2</anno>)
	    </c>
	  </tag>
	  <item>
	    <p>
	      For a <c><anno>Key2</anno></c> in
	      <seetype marker="#level">
		<c>level()</c>
	      </seetype>
	      returns a list of <c>{Opt, boolean()}</c> tuples
	      for all known
	      <seetype marker="#socket_option">
		socket options <c>Opt</c>
		on that <c>Level =:= <anno>Key2</anno></c>,
	      </seetype>
	      and the <c>boolean()</c> indicating if the socket option
	      is supported on this platform.
	      See <seemfa marker="#setopt/3">setopt/3</seemfa>
	      and <seemfa marker="#getopt/2">getopt/2</seemfa>.
	    </p>
	  </item>
	</taglist>
      </desc>
    </func>

    <func>
      <name name="use_registry" arity="1" since="OTP 23.1"/>
      <fsummary>Globally change the use of the socket registry.</fsummary>
      <desc>
	<p>Globally change if the socket registry is to be used or not.
	Note that its still possible to override this explicitly when
	creating an individual sockets,
	see
	<seemfa marker="socket#open/2"><c>open/2</c></seemfa>
	or
	<seemfa marker="socket#open/4"><c>open/4</c></seemfa>
	for more info (use the Extra argument). </p>
      </desc>
    </func>

    <func>
      <name name="which_sockets" arity="0" since="OTP 22.3"/>
      <name name="which_sockets" arity="1" since="OTP 22.3"/>
      <fsummary>Get the current active sockets.</fsummary>
      <desc>
	<p>Returns a list of all sockets, according to the
	filter rule.</p>
	<p>There are several pre-made filter rule(s) and one general: </p>
	<taglist>
	  <tag><c><![CDATA[inet | inet6]]></c></tag>
	  <item>
	    <p>Selection based on the domain of the socket.
	    <br/>Only a subset is valid. </p>
	  </item>

	  <tag><c><![CDATA[stream | dgram | seqpacket]]></c></tag>
	  <item>
	    <p>Selection based on the type of the socket.
	    <br/>Only a subset is valid. </p>
	  </item>

	  <tag><c><![CDATA[sctp | tcp | udp]]></c></tag>
	  <item>
	    <p>Selection based on the protocol of the socket.
	    <br/>Only a subset is valid. </p>
	  </item>

	  <tag><c><![CDATA[pid()]]></c></tag>
	  <item>
	    <p>Selection base on which sockets has this pid as
	    Controlling Process. </p>
	  </item>

	  <tag><c><![CDATA[fun((socket_info()) -> boolean())]]></c></tag>
	  <item>
	    <p>The general filter rule.
	    <br/>A fun that takes the socket info and returns a
	    <c><![CDATA[boolean()]]></c>
	    (<c><![CDATA[true]]></c> if the socket sould be included and
	    <c><![CDATA[false]]></c> if should not). </p>
	  </item>
	</taglist>
      </desc>
    </func>

  </funcs>
  <section>
    <title>Examples</title>
    <marker id="examples"></marker>
    <code type="none">
client(SAddr, SPort) ->
   {ok, Sock} = socket:open(inet, stream, tcp),
   ok = socket:connect(Sock, #{family => inet,
                               addr   => SAddr,
                               port   => SPort}),
   Msg = &lt;&lt;"hello"&gt;&gt;,
   ok = socket:send(Sock, Msg),
   ok = socket:shutdown(Sock, write),
   {ok, Msg} = socket:recv(Sock),
   ok = socket:close(Sock).

server(Addr, Port) ->  
   {ok, LSock} = socket:open(inet, stream, tcp),
   ok = socket:bind(LSock, #{family => inet,
                             port   => Port,
                             addr   => Addr}),
   ok = socket:listen(LSock),
   {ok, Sock} = socket:accept(LSock),
   {ok, Msg} = socket:recv(Sock),
   ok = socket:send(Sock, Msg),
   ok = socket:close(Sock),
   ok = socket:close(LSock).
    </code>
  </section>
</erlref>
