diff options
Diffstat (limited to 'lib/kernel/doc/src/gen_udp.xml')
| -rw-r--r-- | lib/kernel/doc/src/gen_udp.xml | 223 |
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> |