gen_udp

MODULE

gen_udp

MODULE SUMMARY

Interface to UDP sockets

DESCRIPTION

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

DATA TYPES

option() = {active, true | false | once | -32768..32767}
         | {add_membership,
            {inet:ip_address(), inet:ip_address()}}
         | {broadcast, boolean()}
         | {buffer, integer() >= 0}
         | {deliver, port | term}
         | {dontroute, boolean()}
         | {drop_membership,
            {inet:ip_address(), inet:ip_address()}}
         | {header, integer() >= 0}
         | {high_msgq_watermark, integer() >= 1}
         | {low_msgq_watermark, integer() >= 1}
         | {mode, list | binary}
         | list
         | binary
         | {multicast_if, inet:ip_address()}
         | {multicast_loop, boolean()}
         | {multicast_ttl, integer() >= 0}
         | {priority, integer() >= 0}
         | {raw,
            Protocol :: integer() >= 0,
            OptionNum :: integer() >= 0,
            ValueBin :: binary()}
         | {read_packets, integer() >= 0}
         | {recbuf, integer() >= 0}
         | {reuseaddr, boolean()}
         | {sndbuf, integer() >= 0}
         | {tos, integer() >= 0}
         | {ipv6_v6only, boolean()}

option_name() = active
              | broadcast
              | buffer
              | deliver
              | dontroute
              | header
              | high_msgq_watermark
              | low_msgq_watermark
              | mode
              | multicast_if
              | multicast_loop
              | multicast_ttl
              | priority
              | {raw,
                 Protocol :: integer() >= 0,
                 OptionNum :: integer() >= 0,
                 ValueSpec :: (ValueSize :: integer() >= 0)
                            | (ValueBin :: binary())}
              | read_packets
              | recbuf
              | reuseaddr
              | sndbuf
              | tos
              | ipv6_v6only

socket()

As returned by open/1,2.

EXPORTS

open(Port) -> {ok, Socket} | {error, Reason}
open(Port, Opts) -> {ok, Socket} | {error, Reason}

Types:

Port = inet:port_number()

Opts = [Option]

Option = {ip, inet:ip_address()}
       | {fd, integer() >= 0}
       | {ifaddr, inet:ip_address()}
       | inet:address_family()
       | {port, inet:port_number()}
       | option()

Socket = socket()

Reason = inet:posix()

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

The available options are:

list

Received Packet is delivered as a list.

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.

{fd, integer() >= 0}

If a socket has somehow been opened without using gen_udp, use this option to pass the file descriptor for it.

inet6

Set 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.

{multicast_if, Address}

Set the local device for a multicast socket.

{multicast_loop, true | false}

When true sent multicast packets will be 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.

Opt

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 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 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:

{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.

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(Socket, Address, Port, Packet) -> ok | {error, Reason}

Types:

Socket = socket()

Address = inet:ip_address() | inet:hostname()

Port = inet:port_number()

Packet = iodata()

Reason = not_owner | inet:posix()

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

recv(Socket, Length) ->
{ok, {Address, Port, Packet}} | {error, Reason}
recv(Socket, Length, Timeout) ->
{ok, {Address, Port, Packet}} | {error, Reason}

Types:

Socket = socket()

Length = integer() >= 0

Timeout = timeout()

Address = inet:ip_address()

Port = inet:port_number()

Packet = string() | binary()

Reason = not_owner | inet:posix()

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.

controlling_process(Socket, Pid) -> ok | {error, Reason}

Types:

Socket = socket()

Pid = pid()

Reason = closed | not_owner | inet:posix()

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.

close(Socket) -> ok

Types:

Socket = socket()

Closes a UDP socket.