gen_udp(3)

NAME
gen_udp - 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.