gen_udp

Interface to UDP sockets

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

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.

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

Port = inet:port_number()
Socket = socket()
Reason = inet:posix()

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

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}

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}

Socket = socket()
Length = integer() >= 0
Address = inet:ip_address()
Port = inet:port_number()
Packet = string() | binary()
Reason = not_owner | inet:posix()

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

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}

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

Socket = socket()

Closes a UDP socket.

View Functions

open
open-1
send
recv
recv-1
controlling_process
close