diff options
Diffstat (limited to 'erts/doc/src/socket.xml')
| -rw-r--r-- | erts/doc/src/socket.xml | 362 |
1 files changed, 334 insertions, 28 deletions
diff --git a/erts/doc/src/socket.xml b/erts/doc/src/socket.xml index 343b61d4aa..2f7ff2fc07 100644 --- a/erts/doc/src/socket.xml +++ b/erts/doc/src/socket.xml @@ -41,6 +41,40 @@ 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> @@ -65,6 +99,30 @@ </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> @@ -257,7 +315,7 @@ <funcs> <func> <name name="accept" arity="1" since="OTP 22.0"/> - <name name="accept" arity="2" 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> @@ -269,6 +327,28 @@ </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 + <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> @@ -282,6 +362,18 @@ </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> @@ -302,7 +394,7 @@ <func> <name name="connect" arity="2" since="OTP 22.0"/> - <name name="connect" arity="3" 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 @@ -311,6 +403,26 @@ </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 + <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"/> @@ -359,6 +471,20 @@ </func> <func> + <name name="info" arity="1" since="OTP @OTP-15818@"/> + <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> @@ -373,19 +499,24 @@ <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, which will - be used if no protocol is specified: </p> + <p>Creates an endpoint (socket) for communication.</p> - <list> - <item><p><c>stream</c>: <c>tcp</c></p></item> - <item><p><c>dgram</c>: <c>udp</c></p></item> - <item><p><c>seqpacket</c>: <c>sctp</c></p></item> - </list> + <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> @@ -401,8 +532,8 @@ <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="2" since="OTP 22.0"/> - <name name="recv" arity="4" 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> @@ -413,36 +544,128 @@ </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 + <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="1" 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="4" 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.</p> + 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> + 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="2" since="OTP 22.0"/> - <name name="recvmsg" arity="3" 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="5" 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> @@ -456,8 +679,8 @@ <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> + 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. @@ -469,25 +692,58 @@ (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="2" since="OTP 22.0"/> - <name name="send" arity="4" 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 + <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="2" since="OTP 22.0"/> - <name name="sendmsg" arity="4" 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 @@ -508,10 +764,41 @@ </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 + <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="2" since="OTP 22.0"/> - <name name="sendto" arity="5" 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> @@ -519,6 +806,25 @@ </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 + <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"/> |