# 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

    ip_address()
      see inet(3)

    posix()
      see inet(3)

    socket()
      as returned by open/1,2

### EXPORTS

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

Types:

`Port = 0..65535`
`Options = [Opt]`
`Opt -- see below`
`Socket = socket()`
`Reason = 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.
`{fd, int()}`
  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.
`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, they are delivered as messages:

    {udp, Socket, IP, InPortNo, Packet}

Note that arriving UDP packets that are longer than the receive buffer option specifies, might be truncated without warning.

`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 = string() | atom() | ip_address()`
`Port = 0..65535`
`Packet = [char()] | binary()`
`Reason = not_owner | 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 = int()`
`Address = ip_address()`
`Port = 0..65535`
`Packet = [char()] | binary()`
`Timeout = int() | infinity`
`Reason = not_owner | 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`

Types:

`Socket = socket()`
`Pid = pid()`

Assigns a new controlling process `Pid` to `Socket`. The controlling process is the process which receives messages from the socket.

`close(Socket) -> ok | {error, Reason}`

Types:

`Socket = socket()`
`Reason = not_owner | posix()`

Closes a UDP socket.

### AUTHORS

tony@erix.ericsson.se - support@erlang.ericsson.se

kernel 2.11
Copyright © 1991-2006 Ericsson AB