aboutsummaryrefslogtreecommitdiffstats
path: root/erts/doc/src/socket.xml
diff options
context:
space:
mode:
Diffstat (limited to 'erts/doc/src/socket.xml')
-rw-r--r--erts/doc/src/socket.xml915
1 files changed, 915 insertions, 0 deletions
diff --git a/erts/doc/src/socket.xml b/erts/doc/src/socket.xml
new file mode 100644
index 0000000000..b4e22e86a8
--- /dev/null
+++ b/erts/doc/src/socket.xml
@@ -0,0 +1,915 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+ <header>
+ <copyright>
+ <year>2018</year><year>2019</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 the socket interface.
+ It is used to create, delete and manipulate sockets,
+ send and receive data.</p>
+ <p>The idea 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. <seealso marker="#recv/3"><c>recv/3</c></seealso>,
+ has a timeout argument. </p>
+ <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
+ <seealso marker="#recv_async"><c>recv/3</c></seealso>
+ 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>{ok, </c>
+ <seealso marker="#type-select_info"><c>SelectInfo</c></seealso><c>}</c>.
+ 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, select_ref()}</c></item>
+ </taglist>
+ <p>The caller can now make another
+ call to the recv function and now 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>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>{select_ref(), 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="domain"/>
+ </datatype>
+ <datatype>
+ <name name="type"/>
+ </datatype>
+ <datatype>
+ <name name="protocol"/>
+ </datatype>
+ <datatype>
+ <name>socket()</name>
+ <desc><p>As returned by
+ <seealso marker="#open/2"><c>open/2,3,4</c></seealso> and
+ <seealso marker="#accept/1"><c>accept/1,2</c></seealso>.</p>
+ </desc>
+ </datatype>
+ <datatype>
+ <name name="select_tag"/>
+ <desc>
+ <p>A tag that describes the (select) operation.</p>
+ </desc>
+ </datatype>
+ <datatype>
+ <name name="select_ref"/>
+ <desc>
+ <p>A reference that uniquely identifies the (select) operation.</p>
+ </desc>
+ </datatype>
+ <datatype>
+ <name name="select_info"/>
+ </datatype>
+ <datatype>
+ <name name="ip4_address"/>
+ </datatype>
+ <datatype>
+ <name name="ip6_address"/>
+ </datatype>
+ <datatype>
+ <name name="ip_address"/>
+ </datatype>
+ <datatype>
+ <name name="sockaddr"/>
+ </datatype>
+ <datatype>
+ <name name="sockaddr_in4"/>
+ </datatype>
+ <datatype>
+ <name name="sockaddr_in6"/>
+ </datatype>
+ <datatype>
+ <name name="sockaddr_un"/>
+ </datatype>
+ <datatype>
+ <name name="port_number"/>
+ </datatype>
+ <datatype>
+ <name name="in6_flow_info"/>
+ </datatype>
+ <datatype>
+ <name name="in6_scope_id"/>
+ </datatype>
+ <datatype>
+ <name name="accept_flags"/>
+ </datatype>
+ <datatype>
+ <name name="accept_flag"/>
+ </datatype>
+ <datatype>
+ <name name="send_flags"/>
+ </datatype>
+ <datatype>
+ <name name="send_flag"/>
+ </datatype>
+ <datatype>
+ <name name="recv_flags"/>
+ </datatype>
+ <datatype>
+ <name name="recv_flag"/>
+ </datatype>
+ <datatype>
+ <name name="shutdown_how"/>
+ </datatype>
+ <datatype>
+ <name name="sockopt_level"/>
+ </datatype>
+ <datatype>
+ <name name="otp_socket_option"/>
+ </datatype>
+ <datatype>
+ <name name="socket_option"/>
+ </datatype>
+ <datatype>
+ <name name="ip_socket_option"/>
+ </datatype>
+ <datatype>
+ <name name="ipv6_socket_option"/>
+ </datatype>
+ <datatype>
+ <name name="tcp_socket_option"/>
+ </datatype>
+ <datatype>
+ <name name="udp_socket_option"/>
+ </datatype>
+ <datatype>
+ <name name="sctp_socket_option"/>
+ </datatype>
+ <datatype>
+ <name name="timeval"/>
+ </datatype>
+ <datatype>
+ <name name="ip_tos"/>
+ </datatype>
+ <datatype>
+ <name name="ip_mreq"/>
+ </datatype>
+ <datatype>
+ <name name="ip_mreq_source"/>
+ </datatype>
+ <datatype>
+ <name name="ip_pmtudisc"/>
+ </datatype>
+ <datatype>
+ <name name="ip_msfilter_mode"/>
+ </datatype>
+ <datatype>
+ <name name="ip_msfilter"/>
+ </datatype>
+ <datatype>
+ <name name="ip_pktinfo"/>
+ </datatype>
+ <datatype>
+ <name name="ipv6_mreq"/>
+ </datatype>
+ <datatype>
+ <name name="ipv6_pmtudisc"/>
+ </datatype>
+ <datatype>
+ <name name="ipv6_pktinfo"/>
+ </datatype>
+ <datatype>
+ <name name="sctp_assoc_id"/>
+ </datatype>
+ <datatype>
+ <name name="sctp_sndrcvinfo"/>
+ </datatype>
+ <datatype>
+ <name name="sctp_event_subscribe"/>
+ </datatype>
+ <datatype>
+ <name name="sctp_assocparams"/>
+ </datatype>
+ <datatype>
+ <name name="sctp_initmsg"/>
+ </datatype>
+ <datatype>
+ <name name="sctp_rtoinfo"/>
+ </datatype>
+ <datatype>
+ <name name="msghdr_flag"/>
+ </datatype>
+ <datatype>
+ <name name="msghdr_flags"/>
+ </datatype>
+ <datatype>
+ <name name="msghdr"/>
+ </datatype>
+ <datatype>
+ <name name="cmsghdr_level"/>
+ </datatype>
+ <datatype>
+ <name name="cmsghdr_type"/>
+ </datatype>
+ <!--
+ <datatype>
+ <name name="cmsghdr_data"/>
+ </datatype>
+ -->
+ <datatype>
+ <name name="cmsghdr_recv"/>
+ </datatype>
+ <datatype>
+ <name name="cmsghdr_send"/>
+ </datatype>
+ <datatype>
+ <name name="uint8"/>
+ </datatype>
+ <datatype>
+ <name name="uint16"/>
+ </datatype>
+ <datatype>
+ <name name="uint20"/>
+ </datatype>
+ <datatype>
+ <name name="uint32"/>
+ </datatype>
+ <datatype>
+ <name name="int32"/>
+ </datatype>
+ <datatype>
+ <name name="supports_options_socket"/>
+ </datatype>
+ <datatype>
+ <name name="supports_options_ip"/>
+ </datatype>
+ <datatype>
+ <name name="supports_options_ipv6"/>
+ </datatype>
+ <datatype>
+ <name name="supports_options_tcp"/>
+ </datatype>
+ <datatype>
+ <name name="supports_options_udp"/>
+ </datatype>
+ <datatype>
+ <name name="supports_options_sctp"/>
+ </datatype>
+ <datatype>
+ <name name="supports_options"/>
+ </datatype>
+ </datatypes>
+
+ <funcs>
+ <func>
+ <name name="accept" arity="1" since="OTP 22.0"/>
+ <name name="accept" arity="2" clause_i="2" 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-based socket types
+ (<c>stream</c> or <c>seqpacket</c>). It extracs the first pending
+ connection request for the listen socket and returns the (newly)
+ connected socket.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name name="accept" arity="2" clause_i="1" anchor="accept_async" since="OTP @OTP-15731@"/>
+ <fsummary>Accept a connection on a socket.</fsummary>
+ <desc>
+ <p>Accept a connection on a socket.</p>
+
+ <p>This call is used with connection-based socket types
+ (<c>stream</c> or <c>seqpacket</c>). It extracs the first pending
+ connection request for the listen socket and returns the (newly)
+ connected socket.</p>
+
+ <p>In the case when there is no connections waiting, the function
+ will return with the <c>SelectInfo</c>. The caller can then await a
+ select message, <c>{'$socket', Socket, select, Info}</c> (where
+ <c>Info</c> is the <c>select_ref()</c> from the <c>SelectInfo</c>),
+ when a client connects (a subsequent call to accept will then return
+ the socket). </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 <seealso marker="#open/2"><c>open</c></seealso>),
+ 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>
+ </desc>
+ </func>
+
+ <func>
+ <name name="cancel" arity="2" since="OTP @OTP-15731@"/>
+ <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.
+ <seealso marker="#recv/3"><c>recv/3</c></seealso>. </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
+ <seealso marker="#shutdown/2"><c>shutdown</c></seealso>
+ 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"/>
+ <name name="connect" arity="3" clause_i="2" since="OTP 22.0"/>
+ <fsummary>Initiate a connection on a socket.</fsummary>
+ <desc>
+ <p>This function connects the socket to the address
+ specied by the <c>SockAddr</c> argument.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name name="connect" arity="3" clause_i="1" anchor="connect_async" since="OTP @OTP-15731@"/>
+ <fsummary>Initiate a connection on a socket.</fsummary>
+ <desc>
+ <p>This function connects the socket to the address
+ specied by the <c>SockAddr</c> argument.</p>
+
+ <p>In the case when its not possible to immediately establish a
+ connection, the function will return with the
+ <seealso marker="#type-select_info"><c>SelectInfo</c></seealso>.
+ The caller can then await a
+ select message, <c>{'$socket', Socket, select, Info}</c> (where
+ <c>Info</c> is the <c>select_ref()</c> from the <c>SelectInfo</c>,
+ a subsequent call to connect will then
+ establish the connection). </p>
+ </desc>
+ </func>
+
+ <func>
+ <name name="getopt" arity="3" clause_i="1" since="OTP 22.0"/>
+ <name name="getopt" arity="3" clause_i="2" since="OTP 22.0"/>
+ <name name="getopt" arity="3" clause_i="3" since="OTP 22.0"/>
+ <name name="getopt" arity="3" clause_i="4" since="OTP 22.0"/>
+ <name name="getopt" arity="3" clause_i="5" since="OTP 22.0"/>
+ <name name="getopt" arity="3" clause_i="6" since="OTP 22.0"/>
+ <name name="getopt" arity="3" clause_i="7" since="OTP 22.0"/>
+ <fsummary>Get an option on a socket.</fsummary>
+ <desc>
+ <p>Get an option on a socket.</p>
+ <p>What properties are valid depend both on <c>Level</c> and
+ on what kind of socket it is (<c>domain</c>, <c>type</c> and
+ <c>protocol</c>).</p>
+
+ <p>See the
+ <seealso marker="socket_usage#socket_options">socket options</seealso>
+ chapter of the users guide for more info. </p>
+
+ <note><p>Not all options are valid on all platforms. That is,
+ even if "we" support an option, that does not mean that the
+ underlying OS does.</p></note>
+
+ </desc>
+ </func>
+
+ <func>
+ <name name="getopt" arity="3" clause_i="8" since="OTP 22.0"/>
+ <fsummary>Get an option on a socket.</fsummary>
+ <desc>
+ <p>Get an option on a socket.</p>
+ <p>What properties are valid depend both on <c>Level</c> and
+ on what kind of socket it is (<c>domain</c>, <c>type</c> and
+ <c>protocol</c>).</p>
+ <p>When specifying <c>Level</c> as an integer, and therefor
+ using "native mode", it is *currently* up to the caller to
+ know how to interpret the result.</p>
+
+ <p>See the
+ <seealso marker="socket_usage#socket_options">socket options</seealso>
+ chapter of the users guide for more info. </p>
+
+ <note><p>Not all options are valid on all platforms. That is,
+ even if "we" support an option, that does not mean that the
+ underlying OS does.</p></note>
+ </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="open" arity="2" since="OTP 22.0"/>
+ <name name="open" arity="3" 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>For some <c>types</c> 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> pecified,
+ it <em>must</em> be <c>default</c>. </p>
+
+ <p>The <c>Extra</c> argument is intended for "obscure" options.
+ Currently the only supported option is <c>netns</c>, which
+ is only supported on the linux platform.</p>
+
+ <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"/>
+ <name name="recv" arity="2" since="OTP 22.0"/>
+ <name name="recv" arity="3" clause_i="1" since="OTP 22.0"/>
+ <name name="recv" arity="3" clause_i="3" since="OTP 22.0"/>
+ <name name="recv" arity="4" clause_i="2" since="OTP 22.0"/>
+ <fsummary>Receive a message from a socket.</fsummary>
+ <desc>
+ <p>Receive a message from a socket.</p>
+ <p>There is a special case for the argument <c>Length</c>.
+ If it is set to zero (0), it means "give me everything you
+ currently have".</p>
+ </desc>
+ </func>
+
+ <func>
+ <name name="recv" arity="3" clause_i="2" anchor="recv_async" since="OTP @OTP-15731@"/>
+ <name name="recv" arity="4" clause_i="1" since="OTP @OTP-15731@"/>
+ <fsummary>Receive a message from a socket.</fsummary>
+ <desc>
+ <p>Receive a message from a socket.</p>
+
+ <p>There is a special case for the argument <c>Length</c>.
+ If it is set to zero (0), it means "give me everything you
+ currently have".</p>
+
+ <p>In the case when there is no data waiting, the function
+ will return with the <c>SelectInfo</c>. The caller can then await a
+ select message, <c>{'$socket', Socket, select, Info}</c> (where
+ <c>Info</c> is the <c>select_ref()</c> from the <c>SelectInfo</c>),
+ when data has arrived (a subsequent call to recv will then return
+ the data). </p>
+ <p>Note that if a length (<c>> 0</c>) is specified, and only part
+ of that amount of data is available, the function will return with
+ that data <em>and</em> the <c>SelectInfo</c> (if the caller don't
+ want to wait for the remaining data, it must immediately call
+ the <seealso marker="#cancel/2"><c>cancel/2</c></seealso> function.)</p>
+ </desc>
+ </func>
+
+ <func>
+ <name name="recvfrom" arity="1" since="OTP 22.0"/>
+ <name name="recvfrom" arity="2" since="OTP 22.0"/>
+ <name name="recvfrom" arity="3" 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="4" clause_i="2" since="OTP 22.0"/>
+ <fsummary>Receive a message from a socket.</fsummary>
+ <desc>
+ <p>Receive a message from a socket.</p>
+ <p>This function reads "messages", which means that regardless of
+ how much we want to read, it returns when we get a message
+ (if the buffer size is to small, the message will be truncated).</p>
+ <p>The <c>BufSz</c> argument basically defines the size of the
+ receive buffer. By setting the value to zero (0), the configured
+ size (setopt with <c>Level</c> = <c>otp</c> and
+ <c>Key</c> = <c>rcvbuf</c>) is used.</p>
+ <p>It may be impossible to know what (buffer) size is appropriate
+ "in advance", and in those cases it may be convenient to use the
+ (recv) 'peek' flag. When this flag is provided, the message is *not*
+ "consumed" from the underlying buffers, so another recvfrom call
+ is needed, possibly with a then adjusted buffer size.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name name="recvfrom" arity="3" clause_i="1" anchor="recvfrom_async" since="OTP @OTP-15731@"/>
+ <name name="recvfrom" arity="3" clause_i="4" since="OTP @OTP-15731@"/>
+ <name name="recvfrom" arity="4" clause_i="1" since="OTP @OTP-15731@"/>
+ <fsummary>Receive a message from a socket.</fsummary>
+ <desc>
+ <p>Receive a message from a socket.</p>
+ <p>This function reads "messages", which means that regardless of
+ how much we want to read, it returns when we get a message
+ (if the buffer size is to small, the message will be truncated).</p>
+ <p>The <c>BufSz</c> argument basically defines the size of the
+ receive buffer. By setting the value to zero (0), the configured
+ size (setopt with <c>Level</c> = <c>otp</c> and
+ <c>Key</c> = <c>rcvbuf</c>) is used.</p>
+ <p>It may be impossible to know what (buffer) size is appropriate
+ "in advance", and in those cases it may be convenient to use the
+ (recv) 'peek' flag. When this flag is provided, the message is *not*
+ "consumed" from the underlying buffers, so another recvfrom call
+ is needed, possibly with a then adjusted buffer size.</p>
+
+ <p>In the case when there is no data waiting, the function
+ will return with the <c>SelectInfo</c>. The caller can then await a
+ select message, <c>{'$socket', Socket, select, Info}</c> (where
+ <c>Info</c> is the <c>select_ref()</c> from the <c>SelectInfo</c>),
+ when data has arrived (a subsequent call to recvfrom will then return
+ the data). </p>
+ </desc>
+ </func>
+
+ <func>
+ <name name="recvmsg" arity="1" since="OTP 22.0"/>
+ <name name="recvmsg" arity="2" clause_i="1" since="OTP 22.0"/>
+ <name name="recvmsg" arity="2" clause_i="3" since="OTP 22.0"/>
+ <name name="recvmsg" arity="3" clause_i="2" since="OTP 22.0"/>
+ <name name="recvmsg" arity="3" clause_i="3" since="OTP 22.0"/>
+ <name name="recvmsg" arity="5" clause_i="2" since="OTP 22.0"/>
+ <fsummary>Receive a message from a socket.</fsummary>
+ <desc>
+ <p>Receive a message from a socket.</p>
+ <p>This function reads "messages", which means that regardless of
+ how much we want to read, it returns when we get a message.</p>
+ <p>The message will be delivered in the form of a <c>msghdr()</c>,
+ which may contain the source address (if socket not connected),
+ a list of <c>cmsghdr_recv()</c> (depends on what socket options have
+ been set and what the protocol and platform supports) and
+ also a set of flags, providing further info about the read. </p>
+
+ <p>The <c>BufSz</c> argument basically defines the size of the
+ receive buffer. By setting the value to zero (0), the configured
+ size (setopt with <c>Level</c> = <c>otp</c> and
+ <c>Key</c> = <c>rcvbuf</c>) is used.</p>
+
+ <p>The <c>CtrlSz</c> argument basically defines the size of the
+ receive buffer for the control messages.
+ By setting the value to zero (0), the configured size (setopt
+ with <c>Level</c> = <c>otp</c>) is used.</p>
+
+ <p>It may be impossible to know what (buffer) size is appropriate
+ "in advance", and in those cases it may be convenient to use the
+ (recv) 'peek' flag. When this flag is provided, the message is *not*
+ "consumed" from the underlying buffers, so another recvmsg call
+ is needed, possibly with a then adjusted buffer size.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name name="recvmsg" arity="2" clause_i="2" anchor="recvmsg_async" since="OTP @OTP-15731@"/>
+ <name name="recvmsg" arity="3" clause_i="1" since="OTP @OTP-15731@"/>
+ <name name="recvmsg" arity="5" clause_i="1" since="OTP @OTP-15731@"/>
+ <fsummary>Receive a message from a socket.</fsummary>
+ <desc>
+ <p>Receive a message from a socket.</p>
+ <p>This function reads "messages", which means that regardless of
+ how much we want to read, it returns when we get a message.</p>
+ <p>The message will be delivered in the form of a <c>msghdr()</c>,
+ which may contain the source address (if socket not connected),
+ a list of <c>cmsghdr_recv()</c> (depends on what socket options have
+ been set and what the protocol and platform supports) and
+ also a set of flags, providing further info about the read. </p>
+
+ <p>The <c>BufSz</c> argument basically defines the size of the
+ receive buffer. By setting the value to zero (0), the configured
+ size (setopt with <c>Level</c> = <c>otp</c> and
+ <c>Key</c> = <c>rcvbuf</c>) is used.</p>
+
+ <p>The <c>CtrlSz</c> argument basically defines the size of the
+ receive buffer for the control messages.
+ By setting the value to zero (0), the configured size (setopt
+ with <c>Level</c> = <c>otp</c>) is used.</p>
+
+ <p>It may be impossible to know what (buffer) size is appropriate
+ "in advance", and in those cases it may be convenient to use the
+ (recv) 'peek' flag. When this flag is provided, the message is *not*
+ "consumed" from the underlying buffers, so another recvmsg call
+ is needed, possibly with a then adjusted buffer size.</p>
+
+ <p>In the case when there is no data waiting, the function
+ will return with the <c>SelectInfo</c>. The caller can then await a
+ select message, <c>{'$socket', Socket, select, Info}</c> (where
+ <c>Info</c> is the <c>select_ref()</c> from the <c>SelectInfo</c>),
+ when data has arrived (a subsequent call to recvmsg will then return
+ the data). </p>
+ </desc>
+ </func>
+
+ <func>
+ <name name="send" arity="2" since="OTP 22.0"/>
+ <name name="send" arity="3" clause_i="1" since="OTP 22.0"/>
+ <name name="send" arity="3" clause_i="3" since="OTP 22.0"/>
+ <name name="send" arity="4" clause_i="2" since="OTP 22.0"/>
+ <fsummary>Send a message on a socket.</fsummary>
+ <desc>
+ <p>Send a message on a connected socket.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name name="send" arity="3" clause_i="2" anchor="send_async" since="OTP @OTP-15731@"/>
+ <name name="send" arity="4" clause_i="1" since="OTP @OTP-15731@"/>
+ <fsummary>Send a message on a socket.</fsummary>
+ <desc>
+ <p>Send a message on a connected socket.</p>
+
+ <p>In the case when there is no room in the (system-) buffers,
+ the function will return with the <c>SelectInfo</c>. The caller
+ can then await a select message,
+ <c>{'$socket', Socket, select, Info}</c>
+ (where <c>Info</c> is the <c>select_ref()</c> from the
+ <c>SelectInfo</c>), when there is room for more data (a subsequent
+ call to send will then send the data). </p>
+ <p>Note that if not all the data was sent, the function will return
+ with the remaining data <em>and</em> the <c>SelectInfo</c>
+ (if the caller don't
+ want to wait to be able to send the rest, it should immediately call
+ the <seealso marker="#cancel/2"><c>cancel/2</c></seealso> function.)</p>
+ </desc>
+ </func>
+
+ <func>
+ <name name="sendmsg" arity="2" since="OTP 22.0"/>
+ <name name="sendmsg" arity="3" clause_i="1" since="OTP 22.0"/>
+ <name name="sendmsg" arity="3" clause_i="3" since="OTP 22.0"/>
+ <name name="sendmsg" arity="4" clause_i="2" since="OTP 22.0"/>
+ <fsummary>Send a message on a socket.</fsummary>
+ <desc>
+ <p>Send a message on a socket. The destination, if needed
+ (socket <em>not</em> connected) is provided in the <c>MsgHdr</c>,
+ which also contains the message to send,
+ The <c>MsgHdr</c> may also contain an list of optional <c>cmsghdr_send()</c>
+ (depends on what the protocol and platform supports).</p>
+
+ <p>Unlike the <seealso marker="#send/2"><c>send</c></seealso> function,
+ this one sends <em>one message</em>.
+ This means that if, for whatever reason, its not possible to send the
+ message in one go, the function will instead return with the
+ <em>remaining</em> data (<c>{ok, Remaining}</c>). Thereby leaving it
+ up to the caller to decide what to do (retry with the remaining data
+ of give up). </p>
+
+ </desc>
+ </func>
+
+ <func>
+ <name name="sendmsg" arity="3" clause_i="2" anchor="sendmsg_async" since="OTP @OTP-15731@"/>
+ <name name="sendmsg" arity="4" clause_i="1" since="OTP @OTP-15731@"/>
+ <fsummary>Send a message on a socket.</fsummary>
+ <desc>
+ <p>Send a message on a socket. The destination, if needed
+ (socket <em>not</em> connected) is provided in the <c>MsgHdr</c>,
+ which also contains the message to send,
+ The <c>MsgHdr</c> may also contain an list of optional <c>cmsghdr_send()</c>
+ (depends on what the protocol and platform supports).</p>
+
+ <p>Unlike the <seealso marker="#send/2"><c>send</c></seealso> function,
+ this one sends <em>one message</em>.
+ This means that if, for whatever reason, its not possible to send the
+ message in one go, the function will instead return with the
+ <em>remaining</em> data (<c>{ok, Remaining}</c>). Thereby leaving it
+ up to the caller to decide what to do (retry with the remaining data
+ of give up). </p>
+
+ <p>In the case when there is no room in the (system-) buffers,
+ the function will return with the <c>SelectInfo</c>. The caller
+ can then await a select message,
+ <c>{'$socket', Socket, select, Info}</c>
+ (where <c>Info</c> is the <c>select_ref()</c> from the
+ <c>SelectInfo</c>), when there is room for more data (a subsequent
+ call to sendmsg will then send the data). </p>
+ </desc>
+ </func>
+
+ <func>
+ <name name="sendto" arity="3" since="OTP 22.0"/>
+ <name name="sendto" arity="4" clause_i="1" since="OTP 22.0"/>
+ <name name="sendto" arity="4" clause_i="3" since="OTP 22.0"/>
+ <name name="sendto" arity="5" clause_i="2" since="OTP 22.0"/>
+ <fsummary>Send a message on a socket.</fsummary>
+ <desc>
+ <p>Send a message on a socket, to the specified destination.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name name="sendto" arity="4" clause_i="2" anchor="sendto_async" since="OTP @OTP-15731@"/>
+ <name name="sendto" arity="5" clause_i="1" since="OTP @OTP-15731@"/>
+ <fsummary>Send a message on a socket.</fsummary>
+ <desc>
+ <p>Send a message on a socket, to the specified destination.</p>
+
+ <p>In the case when there is no room in the (system-) buffers,
+ the function will return with the <c>SelectInfo</c>. The caller
+ can then await a select message,
+ <c>{'$socket', Socket, select, Info}</c>
+ (where <c>Info</c> is the <c>select_ref()</c> from the
+ <c>SelectInfo</c>), when there is room for more data (a subsequent
+ call to sendto will then send the data). </p>
+ </desc>
+ </func>
+
+ <func>
+ <name name="setopt" arity="4" clause_i="1" since="OTP 22.0"/>
+ <name name="setopt" arity="4" clause_i="2" since="OTP 22.0"/>
+ <name name="setopt" arity="4" clause_i="3" since="OTP 22.0"/>
+ <name name="setopt" arity="4" clause_i="4" since="OTP 22.0"/>
+ <name name="setopt" arity="4" clause_i="5" since="OTP 22.0"/>
+ <name name="setopt" arity="4" clause_i="6" since="OTP 22.0"/>
+ <name name="setopt" arity="4" clause_i="7" since="OTP 22.0"/>
+ <fsummary>Set options on a socket.</fsummary>
+ <desc>
+ <p>Set options on a socket.</p>
+ <p>What properties are valid depend both on <c>Level</c> and on
+ what kind of socket it is (<c>domain</c>, <c>type</c> and
+ <c>protocol</c>).</p>
+
+ <p>See the
+ <seealso marker="socket_usage#socket_options">socket options</seealso>
+ chapter of the users guide for more info. </p>
+
+ <note><p>Not all options are valid on all platforms. That is,
+ even if "we" support an option, that does not mean that the
+ underlying OS does.</p></note>
+
+ <note><p>Sockets are set 'non-blocking' when created, so this option
+ is *not* available (as it would adversely effect the Erlang VM
+ to set a socket 'blocking').</p></note>
+ </desc>
+ </func>
+
+ <func>
+ <name name="setopt" arity="4" clause_i="8" since="OTP 22.0"/>
+ <fsummary>Set options on a socket.</fsummary>
+ <desc>
+ <p>Set options on a socket.</p>
+ <p>What properties are valid depend both on <c>Level</c> and on
+ what kind of socket it is (<c>domain</c>, <c>type</c> and
+ <c>protocol</c>).</p>
+
+ <p>See the
+ <seealso marker="socket_usage#socket_options">socket options</seealso>
+ chapter of the users guide for more info. </p>
+
+ <note><p>Not all options are valid on all platforms. That is,
+ even if "we" support an option, that does not mean that the
+ underlying OS does.</p></note>
+
+ <note><p>Sockets are set 'non-blocking' when created, so this option
+ is *not* available (as it would adversely effect the Erlang VM
+ to set a socket 'blocking').</p></note>
+ </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" clause_i="1" since="OTP 22.0"/>
+ <name name="supports" arity="1" clause_i="2" since="OTP 22.0"/>
+ <name name="supports" arity="1" clause_i="3" since="OTP 22.0"/>
+ <name name="supports" arity="1" clause_i="4" since="OTP 22.0"/>
+ <name name="supports" arity="2" clause_i="1" since="OTP 22.0"/>
+ <name name="supports" arity="2" clause_i="2" since="OTP 22.0"/>
+ <name name="supports" arity="2" clause_i="3" since="OTP 22.0"/>
+ <name name="supports" arity="2" clause_i="4" since="OTP 22.0"/>
+ <name name="supports" arity="2" clause_i="5" since="OTP 22.0"/>
+ <name name="supports" arity="2" clause_i="6" since="OTP 22.0"/>
+ <name name="supports" arity="2" clause_i="7" since="OTP 22.0"/>
+ <name name="supports" arity="3" clause_i="1" since="OTP 22.0"/>
+ <name name="supports" arity="3" clause_i="2" since="OTP 22.0"/>
+ <name name="supports" arity="3" clause_i="3" since="OTP 22.0"/>
+ <name name="supports" arity="3" clause_i="4" since="OTP 22.0"/>
+ <name name="supports" arity="3" clause_i="5" since="OTP 22.0"/>
+ <name name="supports" arity="3" clause_i="6" since="OTP 22.0"/>
+ <name name="supports" arity="3" clause_i="7" since="OTP 22.0"/>
+ <fsummary>Report info about what the platform supports.</fsummary>
+ <desc>
+ <p>This function intends to retreive information about what the
+ platform supports. Such as if SCTP is supported. Or which socket
+ options are supported. </p>
+ </desc>
+ </func>
+
+ </funcs>
+ <section>
+ <title>Examples</title>
+ <marker id="examples"></marker>
+ <code type="none">
+client(Addr, SAddr, SPort) ->
+ {ok, Sock} = socket:open(inet, stream, tcp),
+ {ok, _} = socket:bind(Sock, #{family => inet,
+ addr => Addr}),
+ ok = socket:connect(Sock, #{family => inet,
+ addr => SAddr,
+ port => SPort}),
+ Msg = list_to_binary("hello"),
+ 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:shutdown(Sock, write),
+ ok = socket:close(Sock),
+ ok = socket:close(LSock).
+ </code>
+ </section>
+</erlref>
+