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.

gen_udp

Interface to UDP sockets

Types

socket()

Functions

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

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

send(Socket, Address, Port, Packet) -> ok | {error, Reason}

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

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

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

close(Socket) -> ok

gen_udp

Interface to UDP sockets

Types

socket()

Functions

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

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

send(Socket, Address, Port, Packet) -> ok | {error, Reason}

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

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

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

close(Socket) -> ok

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

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