aboutsummaryrefslogtreecommitdiffstats
path: root/erts/doc/src/socket.xml
diff options
context:
space:
mode:
authorMicael Karlberg <[email protected]>2018-05-31 10:58:19 +0200
committerMicael Karlberg <[email protected]>2018-09-18 13:01:37 +0200
commit63338250778d2caad08aa3180b372e5260f22aa7 (patch)
tree81b90d47c0f92e22fc2b656373defbc7b2b4229a /erts/doc/src/socket.xml
parent7ce277e9635830c6d5c56ba02e3346a6496dec09 (diff)
downloadotp-63338250778d2caad08aa3180b372e5260f22aa7.tar.gz
otp-63338250778d2caad08aa3180b372e5260f22aa7.tar.bz2
otp-63338250778d2caad08aa3180b372e5260f22aa7.zip
[socket-nif-doc] Add preliminary doc for socket
The doc now builds. Had to update the code (spec and types) to match. Though, te result is less then stellar. OTP-14831
Diffstat (limited to 'erts/doc/src/socket.xml')
-rw-r--r--erts/doc/src/socket.xml308
1 files changed, 308 insertions, 0 deletions
diff --git a/erts/doc/src/socket.xml b/erts/doc/src/socket.xml
new file mode 100644
index 0000000000..9b487172c5
--- /dev/null
+++ b/erts/doc/src/socket.xml
@@ -0,0 +1,308 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+ <header>
+ <copyright>
+ <year>2018</year><year>2018</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>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.</p>
+ </description>
+
+ <datatypes>
+ <datatype>
+ <name name="domain"/>
+ </datatype>
+ <datatype>
+ <name name="type"/>
+ </datatype>
+ <datatype>
+ <name name="protocol"/>
+ </datatype>
+ <datatype>
+ <name name="socket"/>
+ </datatype>
+ <datatype>
+ <name name="ip4_address"/>
+ </datatype>
+ <datatype>
+ <name name="ip6_address"/>
+ </datatype>
+ <datatype>
+ <name name="ip_address"/>
+ </datatype>
+ <datatype>
+ <name name="in4_sockaddr"/>
+ </datatype>
+ <datatype>
+ <name name="in6_sockaddr"/>
+ </datatype>
+ <datatype>
+ <name name="in_sockaddr"/>
+ </datatype>
+ <datatype>
+ <name name="port_number"/>
+ </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="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="ip_tos_flag"/>
+ </datatype>
+ </datatypes>
+
+ <funcs>
+ <func>
+ <name name="accept" arity="1"/>
+ <name name="accept" arity="2"/>
+ <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
+ (stream or seqpacket). It extracs the first pending connection
+ request for the listen socket and returns the (newly) connected
+ socket.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name name="bind" arity="2"/>
+ <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"><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="close" arity="1"/>
+ <fsummary>Close a socket.</fsummary>
+ <desc>
+ <p>Closes the socket.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name name="connect" arity="2"/>
+ <name name="connect" arity="3"/>
+ <fsummary>Initiate a connection on a socket.</fsummary>
+ <desc>
+ <p>This function connects the socket to the address
+ specied by the <c>Addr</c> argument.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name name="getopt" arity="3" clause_i="1"/>
+ <name name="getopt" arity="3" clause_i="2"/>
+ <name name="getopt" arity="3" clause_i="3"/>
+ <name name="getopt" arity="3" clause_i="4"/>
+ <name name="getopt" arity="3" clause_i="5"/>
+ <name name="getopt" arity="3" clause_i="6"/>
+ <name name="getopt" arity="3" clause_i="7"/>
+ <name name="getopt" arity="3" clause_i="8"/>
+ <fsummary>Get an option on a socket.</fsummary>
+ <desc>
+ <p>Get an option on a socket.</p>
+ <p>What properties are valid depend 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>
+
+ <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"/>
+ <name name="listen" arity="2"/>
+ <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"/>
+ <name name="open" arity="3"/>
+ <name name="open" arity="4"/>
+ <fsummary>Create an endpoint for communication.</fsummary>
+ <desc>
+ <p>Creates an endpoint (socket) for communication.</p>
+ <p>For some types there is a default protocol, which will
+ be used if no protocol is specified: </p>
+ <taglist>
+ <tag><c>stream</c></tag>
+ <item>
+ <p><c>tcp</c></p>
+ </item>
+ <tag><c>dgram</c></tag>
+ <item>
+ <p><c>udp</c></p>
+ </item>
+ <tag><c>seqpacket</c></tag>
+ <item>
+ <p><c>sctp</c></p>
+ </item>
+ </taglist>
+ </desc>
+ </func>
+
+ <func>
+ <name name="recv" arity="2"/>
+ <name name="recv" arity="3"/>
+ <name name="recv" arity="4"/>
+ <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="recvfrom" arity="1"/>
+ <name name="recvfrom" arity="2"/>
+ <name name="recvfrom" arity="3"/>
+ <name name="recvfrom" arity="4"/>
+ <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 <c>MaxSize</c> argument basically defines the size of the
+ receive buffer. By setting the value to zero (0), the configured
+ size (setopt) 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="send" arity="2"/>
+ <name name="send" arity="3"/>
+ <name name="send" arity="4"/>
+ <fsummary>Send a message on a socket.</fsummary>
+ <desc>
+ <p>Send a message on a connected socket.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name name="sendto" arity="4"/>
+ <name name="sendto" arity="5"/>
+ <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="setopt" arity="4" clause_i="1"/>
+ <name name="setopt" arity="4" clause_i="2"/>
+ <name name="setopt" arity="4" clause_i="3"/>
+ <name name="setopt" arity="4" clause_i="4"/>
+ <name name="setopt" arity="4" clause_i="5"/>
+ <name name="setopt" arity="4" clause_i="6"/>
+ <name name="setopt" arity="4" clause_i="7"/>
+ <fsummary>Set options on a socket.</fsummary>
+ <desc>
+ <p>Set options on a socket.</p>
+ <p>What properties are valid depend on what kind of socket
+ it is (<c>domain</c>, <c>type</c> and <c>protocol</c>).</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"/>
+ <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>
+
+ </funcs>
+</erlref>
+