# gen_udp

### MODULE

gen_udp

### MODULE SUMMARY

Interface to UDP.

### DESCRIPTION

The `gen_udp` module is an interface to User Datagram Protocol (UDP).

The possible `{error, Reason}` results are described in the inet manual page.

### EXPORTS

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

Types:

`Socket = Reason = term()`

Removes the `Socket` created with `open/1` or `open/2`.

`controlling_process(Socket,NewOwner) ->`

Types:

`Socket = term()`
`NewOwner = pid()`

The process associated with a Socket is changed to `NewOwner`. The `NewOwner` will receive all subsequent data.

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

Types:

`Port = integer(0..65535)`
`Options = list()`
`Socket = term()`
`Reason = term()`

Associates a UDP port number (`Port`) with the calling process. It returns `{ok, Socket}`, or `{error, Reason}`. The returned `Socket` is used to send packets from this port with the `send/4` function. `Options` is a list of options associated with this port.

When UDP packets arrive at the opened `Port` they will be delivered as messages of the type `{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.

The available options are:

`list`
  Received `Packet` is delivered as a list.
`binary`
  Received `Packet` is delivered as a binary.
`{ip,IPAddress}`
  If the host has several network interfaces, this option specifies which one to use.
`{fd,Fd}`
  If a UDP socket has somehow been opened without using `gen_udp`, use this option to pass in the file descriptor for it and create a Socket for it.
`inet6`
  Set up the socket for IPv6
`inet`
  Set up the socket for IPv4
common `inet` options
  The common `inet` options available are described in the setopts/2 function in the `inet` manual page. Default value for the receive buffer option is `{recbuf, 8192}`.

If you set Port to 0, the underlying Operating System assigns a free UDP port. (You can find out which port by calling `inet:port(Socket)`.)

If any of the following functions are called with a `Socket` that was not opened by the calling process, they will return `{error,not_owner}`. The ownership of a `Socket` can be transferred to another process with `controlling_process/2`.

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

Types:

`Socket = socket()`
`Address = { integer(), integer(), integer(), integer()}`
`Port = integer(0..65535)`
`Length = integer()`
`Packet = list() | binary()`
`Timeout = integer()`
`Reason = atom()`

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

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

Types:

`Address = { integer(), integer(), integer(), integer()} | atom() | string()`
`Port = integer(0..65535)`
`Packet = [byte()] | binary()`
`Reason = term()`

Sends `Packet` to the specified address (address, port). It returns `ok`, or `{error, Reason}`. `Address` can be an IP address expressed as a tuple, for example `{192, 0, 0, 1}`. It can also be a host name expressed as an atom or a string, for example 'somehost.some.domain'. `Port` is an integer, and `Packet` is either a list of bytes or a binary.

### AUTHORS

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

kernel 2.9
Copyright © 1991-2003 Ericsson Utvecklings AB