diff options
Diffstat (limited to 'erts/doc/src/socket.xml')
| -rw-r--r-- | erts/doc/src/socket.xml | 1017 |
1 files changed, 0 insertions, 1017 deletions
diff --git a/erts/doc/src/socket.xml b/erts/doc/src/socket.xml deleted file mode 100644 index e5a0be2879..0000000000 --- a/erts/doc/src/socket.xml +++ /dev/null @@ -1,1017 +0,0 @@ -<?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 network socket. - Functions are provided to create, delete and manupilate the sockets - aswell as sending and reciving 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. <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>{select, </c> - <seealso marker="#type-select_info"><c>SelectInfo</c></seealso><c>}</c> - (<c>SelectInfo</c> contains the - <seealso marker="socket#type-select_ref">SelectRef</seealso>). - 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, SelectRef}</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>{SelectRef, 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="socket_counters"/> - </datatype> - <datatype> - <name name="socket_counter"/> - </datatype> - <datatype> - <name name="socket_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="sockaddr_ll"/> - </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="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="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="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> - <datatype> - <name name="supports_send_flags"/> - </datatype> - <datatype> - <name name="supports_recv_flags"/> - </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 22.1"/> - <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 - <seealso marker="socket#type-select_ref"><c>ref</c></seealso> - field 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 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. - <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 22.1"/> - <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 - <seealso marker="socket#type-select_ref"><c>ref</c></seealso> - field 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>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>For more info, see - <seealso marker="#getopt/3">getopt</seealso> above. </p> - </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="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="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 22.1"/> - <name name="recv" arity="4" clause_i="1" since="OTP 22.1"/> - <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 - <seealso marker="socket#type-select_ref"><c>ref</c></seealso> - field 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 too 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 22.1"/> - <name name="recvfrom" arity="3" clause_i="4" since="OTP 22.1"/> - <name name="recvfrom" arity="4" clause_i="1" since="OTP 22.1"/> - <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 too 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 - <seealso marker="socket#type-select_ref"><c>ref</c></seealso> - field 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 22.1"/> - <name name="recvmsg" arity="3" clause_i="1" since="OTP 22.1"/> - <name name="recvmsg" arity="5" clause_i="1" since="OTP 22.1"/> - <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 - <seealso marker="socket#type-select_ref"><c>ref</c></seealso> - field 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 22.1"/> - <name name="send" arity="4" clause_i="1" since="OTP 22.1"/> - <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 - <seealso marker="socket#type-select_ref"><c>ref</c></seealso> - field 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 22.1"/> - <name name="sendmsg" arity="4" clause_i="1" since="OTP 22.1"/> - <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 - <seealso marker="socket#type-select_ref"><c>ref</c></seealso> - field 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 22.1"/> - <name name="sendto" arity="5" clause_i="1" since="OTP 22.1"/> - <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 - <seealso marker="socket#type-select_ref"><c>ref</c></seealso> - field 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>When specifying <c>Level</c> as an integer, and therefor - using "native mode", it is *currently* up to the caller to - know how to encode the <c>Value</c>.</p> - - <p>For more info, see - <seealso marker="#setopt/4">setopt</seealso> above. </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" 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="1" clause_i="5" since="OTP 22.3"/> - <name name="supports" arity="1" clause_i="6" since="OTP 22.3"/> - <name name="supports" arity="1" clause_i="7" 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.3"/> - <name name="supports" arity="2" clause_i="8" since="OTP 22.3"/> - <name name="supports" arity="2" clause_i="9" 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> - - <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(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> - |