From 3d70cee4034e4da37d125679345aa2a10c58cb34 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B6rn=20Gustavsson?= Date: Tue, 14 Apr 2015 23:21:36 +0200 Subject: Update Kernel documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Language cleaned up by technical writers from Combitech. Proofreading and corrections by Björn Gustavsson and Hans Bolinder. --- lib/kernel/doc/src/gen_udp.xml | 223 +++++++++++++++++------------------------ 1 file changed, 94 insertions(+), 129 deletions(-) (limited to 'lib/kernel/doc/src/gen_udp.xml') 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 @@ A gen_udp - Interface to UDP sockets + Interface to UDP sockets. -

The gen_udp module provides functions for communicating +

This module provides functions for communicating with sockets using the UDP protocol.

 @@ -45,175 +45,140 @@ socket() -

As returned by open/1,2.

+ +

As returned by + open/1,2.

 + + + Close a UDP socket. + +

Closes a UDP socket.

+ + + + + + Change controlling process of a socket. + +

Assigns a new controlling process Pid to + Socket. The controlling process is the process + that receives messages from the socket. If called by any other + process than the current controlling process, + {error, not_owner} is returned.

+ + + - Associate a UDP port number with the process calling it + Associate a UDP port number with the process calling it. -

Associates a UDP port number (Port) with the calling - process.

-

The available options are:

+

Associates a UDP port number (Port) with the + calling process.

+

The following options are available:

list - -

Received Packet is delivered as a list.

- +

Received Packet is delivered as a list.

 binary - -

Received Packet is delivered as a binary.

- +

Received Packet is delivered as a binary.

 {ip, ip_address()} - -

If the host has several network interfaces, this option - specifies which one to use.

- - - {ifaddr, ip_address()} - -

Same as {ip, ip_address()}. If the host has several network interfaces, this option - specifies which one to use.

- - - +

If the host has many network interfaces, this option + specifies which one to use.

 + {ifaddr, ip_address()} +

Same as {ip, ip_address()}. If the host has many + network interfaces, this option specifies which one to + use.

 {fd, integer() >= 0} - -

If a socket has somehow been opened without using - gen_udp, use this option to pass the file - descriptor for it. If Port is not set to 0 - and/or {ip, ip_address()} 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. -

- +

If a socket has somehow been opened without using + gen_udp, use this option to pass the file descriptor + for it. If Port is not set to 0 and/or + {ip, ip_address()} is combined with this option, the + fd is bound to the specified interface and port after it is + being opened. If these options are not specified, it is assumed that + the fd is already bound appropriately.

 inet6 - -

Set up the socket for IPv6.

- +

Sets up the socket for IPv6.

 inet - -

Set up the socket for IPv4.

- - - {udp_module, module()} -

- Override which callback module is used. Defaults to - inet_udp for IPv4 and inet6_udp for IPv6. -

- - +

Sets up the socket for IPv4.

 + {udp_module, module()} +

Overrides which callback module is used. Defaults to + inet_udp for IPv4 and inet6_udp for IPv6.

 {multicast_if, Address} - -

Set the local device for a multicast socket.

- - +

Sets the local device for a multicast socket.

 {multicast_loop, true | false} - -

- When true sent multicast packets will be looped back to the local - sockets. -

- - +

When true, sent multicast packets are looped back to + the local sockets.

 {multicast_ttl, Integer} - -

- The multicast_ttl option changes the time-to-live (TTL) for - outgoing multicast datagrams in order to control the scope of the - multicasts. -

-

- Datagrams with a TTL of 1 are not forwarded beyond the local - network. -
Default: 1 -

- - - {add_membership, {MultiAddress, InterfaceAddress}} - -

Join a multicast group.

- - - {drop_membership, {MultiAddress, InterfaceAddress}} - -

Leave multicast group.

- - +

Option multicast_ttl changes the time-to-live (TTL) + for outgoing multicast datagrams to control the scope of the + multicasts.

+

Datagrams with a TTL of 1 are not forwarded beyond the local + network. Defaults to 1.

 + {add_membership, {MultiAddress, InterfaceAddress}} +

Joins a multicast group.

 + {drop_membership, {MultiAddress, InterfaceAddress}} +

Leaves a multicast group.

 Opt - -

See - inet:setopts/2.

- +

See + inet:setopts/2. +

The returned socket Socket is used to send - packets from this port with send/4. When UDP packets arrive - at the opened port, if the socket is in an active mode the packets + packets from this port with + send/4. + 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:

{udp, Socket, IP, InPortNo, Packet}

If the socket is not in an active mode, data can be - retrieved via the recv/2,3 calls. - Note that arriving UDP packets that are longer than - the receive buffer option specifies, might be truncated + retrieved through the + recv/2,3 calls. + Notice that arriving UDP packets that are longer than + the receive buffer option specifies can be truncated without warning.

-

When a socket in {active, N} mode (see - inet:setopts/2 for details) transitions to passive - ({active, false}) mode, the controlling process is notified by a - message of the following form:

+

When a socket in {active, N} mode (see + inet:setopts/2 + for details), transitions to passive ({active, false}) mode, + the controlling process is notified by a message of the following + form:

{udp_passive, Socket}

IP and InPortNo define the address from which - Packet came. Packet is a list of bytes if - the option list was specified. Packet is a - binary if the option binary was specified.

+ Packet comes. Packet is a list of bytes if + option list is specified. Packet is a + binary if option binary is specified.

Default value for the receive buffer option is {recbuf, 8192}.

-

If Port == 0, the underlying OS assigns a free UDP - port, use inet:port/1 to retrieve it.

- - - - - Send a packet - -

Sends a packet to the specified address and port. - The Address argument can be either a hostname, or an - IP address.

+

If Port == 0, the underlying OS assigns a free + UDP port, use + inet:port/1 + to retrieve it.

 + - Receive a packet from a passive socket - -

This function receives a packet from a socket in passive - mode.

-

The optional Timeout parameter specifies a timeout in - milliseconds. The default value is infinity.

- - - - - Change controlling process of a socket + Receive a packet from a passive socket. -

Assigns a new controlling process Pid to - Socket. The controlling process is the process which - receives messages from the socket. If called by any other - process than the current controlling process, - {error, not_owner} is returned.

+

Receives a packet from a socket in passive mode. Optional parameter + Timeout specifies a time-out in milliseconds. + Defaults to infinity.

 + - - Close a UDP socket + + Send a packet. -

Closes a UDP socket.

+

Sends a packet to the specified address and port. Argument + Address can be a hostname or an IP address.

 -- cgit v1.2.3