aboutsummaryrefslogtreecommitdiffstats
path: root/lib/kernel/doc/src/gen_udp.xml
diff options
context:
space:
mode:
authorBjörn Gustavsson <[email protected]>2015-04-14 23:21:36 +0200
committerBjörn Gustavsson <[email protected]>2016-03-31 14:24:12 +0200
commit3d70cee4034e4da37d125679345aa2a10c58cb34 (patch)
tree9989c84b7556999bfe48693666e6c74c6f2d54c3 /lib/kernel/doc/src/gen_udp.xml
parente9929ee372001f6ce44697c0e71b93fc6db61f9c (diff)
downloadotp-3d70cee4034e4da37d125679345aa2a10c58cb34.tar.gz
otp-3d70cee4034e4da37d125679345aa2a10c58cb34.tar.bz2
otp-3d70cee4034e4da37d125679345aa2a10c58cb34.zip
Update Kernel documentation
Language cleaned up by technical writers from Combitech. Proofreading and corrections by Björn Gustavsson and Hans Bolinder.
Diffstat (limited to 'lib/kernel/doc/src/gen_udp.xml')
-rw-r--r--lib/kernel/doc/src/gen_udp.xml223
1 files changed, 94 insertions, 129 deletions
diff --git a/lib/kernel/doc/src/gen_udp.xml b/lib/kernel/doc/src/gen_udp.xml
index 79cd87dcef..67789d8555 100644
--- a/lib/kernel/doc/src/gen_udp.xml
+++ b/lib/kernel/doc/src/gen_udp.xml
@@ -29,9 +29,9 @@
<rev>A</rev>
</header>
<module>gen_udp</module>
- <modulesummary>Interface to UDP sockets</modulesummary>
+ <modulesummary>Interface to UDP sockets.</modulesummary>
<description>
- <p>The <c>gen_udp</c> module provides functions for communicating
+ <p>This module provides functions for communicating
with sockets using the UDP protocol.</p>
</description>
@@ -45,175 +45,140 @@
<datatype>
<name>socket()</name>
<desc>
- <p><marker id="type-socket"/>As returned by open/1,2.</p>
+ <marker id="type-socket"/>
+ <p>As returned by
+ <seealso marker="#open/1"><c>open/1,2</c></seealso>.</p>
</desc>
</datatype>
</datatypes>
<funcs>
<func>
+ <name name="close" arity="1"/>
+ <fsummary>Close a UDP socket.</fsummary>
+ <desc>
+ <p>Closes a UDP socket.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name name="controlling_process" arity="2"/>
+ <fsummary>Change controlling process of a socket.</fsummary>
+ <desc>
+ <p>Assigns a new controlling process <c><anno>Pid</anno></c> to
+ <c><anno>Socket</anno></c>. The controlling process is the process
+ that receives messages from the socket. If called by any other
+ process than the current controlling process,
+ <c>{error, not_owner}</c> is returned.</p>
+ </desc>
+ </func>
+
+ <func>
<name name="open" arity="1"/>
<name name="open" arity="2"/>
- <fsummary>Associate a UDP port number with the process calling it</fsummary>
+ <fsummary>Associate a UDP port number with the process calling it.</fsummary>
<desc>
- <p>Associates a UDP port number (<c><anno>Port</anno></c>) with the calling
- process.</p>
- <p>The available options are:</p>
+ <p>Associates a UDP port number (<c><anno>Port</anno></c>) with the
+ calling process.</p>
+ <p>The following options are available:</p>
<taglist>
<tag><c>list</c></tag>
- <item>
- <p>Received <c>Packet</c> is delivered as a list.</p>
- </item>
+ <item><p>Received <c>Packet</c> is delivered as a list.</p></item>
<tag><c>binary</c></tag>
- <item>
- <p>Received <c>Packet</c> is delivered as a binary.</p>
- </item>
+ <item><p>Received <c>Packet</c> is delivered as a binary.</p></item>
<tag><c>{ip, ip_address()}</c></tag>
- <item>
- <p>If the host has several network interfaces, this option
- specifies which one to use.</p>
- </item>
-
- <tag><c>{ifaddr, ip_address()}</c></tag>
- <item>
- <p>Same as <c>{ip, ip_address()}</c>. If the host has several network interfaces, this option
- specifies which one to use.</p>
- </item>
-
-
+ <item><p>If the host has many network interfaces, this option
+ specifies which one to use.</p></item>
+ <tag><c>{ifaddr, ip_address()}</c></tag>
+ <item><p>Same as <c>{ip, ip_address()}</c>. If the host has many
+ network interfaces, this option specifies which one to
+ use.</p></item>
<tag><c>{fd, integer() >= 0}</c></tag>
- <item>
- <p>If a socket has somehow been opened without using
- <c>gen_udp</c>, use this option to pass the file
- descriptor for it. If <c><anno>Port</anno></c> is not set to 0
- and/or <c>{ip, ip_address()}</c> is combined with this option
- the fd will be bound to the given interface and port after being
- opened. If these options are not given it is assumed that the fd
- is already bound appropriately.
- </p>
- </item>
+ <item><p>If a socket has somehow been opened without using
+ <c>gen_udp</c>, use this option to pass the file descriptor
+ for it. If <c><anno>Port</anno></c> is not set to <c>0</c> and/or
+ <c>{ip, ip_address()}</c> is combined with this option, the
+ <c>fd</c> is bound to the specified interface and port after it is
+ being opened. If these options are not specified, it is assumed that
+ the <c>fd</c> is already bound appropriately.</p></item>
<tag><c>inet6</c></tag>
- <item>
- <p>Set up the socket for IPv6.</p>
- </item>
+ <item><p>Sets up the socket for IPv6.</p></item>
<tag><c>inet</c></tag>
- <item>
- <p>Set up the socket for IPv4.</p>
- </item>
-
- <tag><c>{udp_module, module()}</c></tag>
- <item> <p>
- Override which callback module is used. Defaults to
- <c>inet_udp</c> for IPv4 and <c>inet6_udp</c> for IPv6.
- </p>
- </item>
-
+ <item><p>Sets up the socket for IPv4.</p></item>
+ <tag><c>{udp_module, module()}</c></tag>
+ <item><p>Overrides which callback module is used. Defaults to
+ <c>inet_udp</c> for IPv4 and <c>inet6_udp</c> for IPv6.</p></item>
<tag><c>{multicast_if, Address}</c></tag>
- <item>
- <p>Set the local device for a multicast socket.</p>
- </item>
-
+ <item><p>Sets the local device for a multicast socket.</p></item>
<tag><c>{multicast_loop, true | false}</c></tag>
- <item>
- <p>
- When <c>true</c> sent multicast packets will be looped back to the local
- sockets.
- </p>
- </item>
-
+ <item><p>When <c>true</c>, sent multicast packets are looped back to
+ the local sockets.</p></item>
<tag><c>{multicast_ttl, Integer}</c></tag>
- <item>
- <p>
- The <c>multicast_ttl</c> option changes the time-to-live (TTL) for
- outgoing multicast datagrams in order to control the scope of the
- multicasts.
- </p>
- <p>
- Datagrams with a TTL of 1 are not forwarded beyond the local
- network.
- <br />Default: 1
- </p>
- </item>
-
- <tag><c>{add_membership, {MultiAddress, InterfaceAddress}}</c></tag>
- <item>
- <p>Join a multicast group. </p>
- </item>
-
- <tag><c>{drop_membership, {MultiAddress, InterfaceAddress}}</c></tag>
- <item>
- <p>Leave multicast group.</p>
- </item>
-
+ <item><p>Option <c>multicast_ttl</c> changes the time-to-live (TTL)
+ for outgoing multicast datagrams to control the scope of the
+ multicasts.</p>
+ <p>Datagrams with a TTL of 1 are not forwarded beyond the local
+ network. Defaults to <c>1</c>.</p></item>
+ <tag><c>{add_membership, {MultiAddress, InterfaceAddress}}</c></tag>
+ <item><p>Joins a multicast group.</p></item>
+ <tag><c>{drop_membership, {MultiAddress, InterfaceAddress}}</c></tag>
+ <item><p>Leaves a multicast group.</p></item>
<tag><c>Opt</c></tag>
- <item>
- <p>See
- <seealso marker="inet#setopts/2">inet:setopts/2</seealso>.</p>
- </item>
+ <item><p>See
+ <seealso marker="inet#setopts/2"><c>inet:setopts/2</c></seealso>.
+ </p></item>
</taglist>
<p>The returned socket <c><anno>Socket</anno></c> is used to send
- packets from this port with <c>send/4</c>. When UDP packets arrive
- at the opened port, if the socket is in an active mode the packets
+ packets from this port with
+ <seealso marker="#send/4"><c>send/4</c></seealso>.
+ When UDP packets arrive
+ at the opened port, if the socket is in an active mode, the packets
are delivered as messages to the controlling process:</p>
<code type="none">
{udp, Socket, IP, InPortNo, Packet}</code>
<p>If the socket is not in an active mode, data can be
- retrieved via the <seealso marker="#recv/2">recv/2,3</seealso> calls.
- Note that arriving UDP packets that are longer than
- the receive buffer option specifies, might be truncated
+ retrieved through the
+ <seealso marker="#recv/2"><c>recv/2,3</c></seealso> calls.
+ Notice that arriving UDP packets that are longer than
+ the receive buffer option specifies can be truncated
without warning.</p>
- <p>When a socket in <c>{active, N}</c> mode (see <seealso marker="inet#setopts/2">
- inet:setopts/2</seealso> for details) transitions to passive
- (<c>{active, false}</c>) mode, the controlling process is notified by a
- message of the following form:</p>
+ <p>When a socket in <c>{active, N}</c> mode (see
+ <seealso marker="inet#setopts/2"><c>inet:setopts/2</c></seealso>
+ for details), transitions to passive (<c>{active, false}</c>) mode,
+ the controlling process is notified by a message of the following
+ form:</p>
<code type="none">
{udp_passive, Socket}</code>
<p><c>IP</c> and <c>InPortNo</c> define the address from which
- <c>Packet</c> came. <c>Packet</c> is a list of bytes if
- the option <c>list</c> was specified. <c>Packet</c> is a
- binary if the option <c>binary</c> was specified.</p>
+ <c>Packet</c> comes. <c>Packet</c> is a list of bytes if
+ option <c>list</c> is specified. <c>Packet</c> is a
+ binary if option <c>binary</c> is specified.</p>
<p>Default value for the receive buffer option is
<c>{recbuf, 8192}</c>.</p>
- <p>If <c><anno>Port</anno> == 0</c>, the underlying OS assigns a free UDP
- port, use <c>inet:port/1</c> to retrieve it.</p>
- </desc>
- </func>
- <func>
- <name name="send" arity="4"/>
- <fsummary>Send a packet</fsummary>
- <desc>
- <p>Sends a packet to the specified address and port.
- The <c><anno>Address</anno></c> argument can be either a hostname, or an
- IP address.</p>
+ <p>If <c><anno>Port</anno> == 0</c>, the underlying OS assigns a free
+ UDP port, use
+ <seealso marker="inet#port/1"><c>inet:port/1</c></seealso>
+ to retrieve it.</p>
</desc>
</func>
+
<func>
<name name="recv" arity="2"/>
<name name="recv" arity="3"/>
- <fsummary>Receive a packet from a passive socket</fsummary>
- <desc>
- <p>This function receives a packet from a socket in passive
- mode.</p>
- <p>The optional <c><anno>Timeout</anno></c> parameter specifies a timeout in
- milliseconds. The default value is <c>infinity</c>.</p>
- </desc>
- </func>
- <func>
- <name name="controlling_process" arity="2"/>
- <fsummary>Change controlling process of a socket</fsummary>
+ <fsummary>Receive a packet from a passive socket.</fsummary>
<desc>
- <p>Assigns a new controlling process <c><anno>Pid</anno></c> to
- <c><anno>Socket</anno></c>. The controlling process is the process which
- receives messages from the socket. If called by any other
- process than the current controlling process,
- <c>{error, not_owner}</c> is returned.</p>
+ <p>Receives a packet from a socket in passive mode. Optional parameter
+ <c><anno>Timeout</anno></c> specifies a time-out in milliseconds.
+ Defaults to <c>infinity</c>.</p>
</desc>
</func>
+
<func>
- <name name="close" arity="1"/>
- <fsummary>Close a UDP socket</fsummary>
+ <name name="send" arity="4"/>
+ <fsummary>Send a packet.</fsummary>
<desc>
- <p>Closes a UDP socket.</p>
+ <p>Sends a packet to the specified address and port. Argument
+ <c><anno>Address</anno></c> can be a hostname or an IP address.</p>
</desc>
</func>
</funcs>