1gen_udp(3)                 Erlang Module Definition                 gen_udp(3)
2
3
4

NAME

6       gen_udp - Interface to UDP sockets.
7

DESCRIPTION

9       This module provides functions for communicating with sockets using the
10       UDP protocol.
11

DATA TYPES

13       option() =
14           {active, true | false | once | -32768..32767} |
15           {add_membership, {inet:ip_address(), inet:ip_address()}} |
16           {broadcast, boolean()} |
17           {buffer, integer() >= 0} |
18           {deliver, port | term} |
19           {dontroute, boolean()} |
20           {drop_membership, {inet:ip_address(), inet:ip_address()}} |
21           {header, integer() >= 0} |
22           {high_msgq_watermark, integer() >= 1} |
23           {low_msgq_watermark, integer() >= 1} |
24           {mode, list | binary} |
25           list | binary |
26           {multicast_if, inet:ip_address()} |
27           {multicast_loop, boolean()} |
28           {multicast_ttl, integer() >= 0} |
29           {priority, integer() >= 0} |
30           {raw,
31            Protocol :: integer() >= 0,
32            OptionNum :: integer() >= 0,
33            ValueBin :: binary()} |
34           {read_packets, integer() >= 0} |
35           {recbuf, integer() >= 0} |
36           {reuseaddr, boolean()} |
37           {sndbuf, integer() >= 0} |
38           {tos, integer() >= 0} |
39           {tclass, integer() >= 0} |
40           {ttl, integer() >= 0} |
41           {recvtos, boolean()} |
42           {recvtclass, boolean()} |
43           {recvttl, boolean()} |
44           {ipv6_v6only, boolean()}
45
46       option_name() =
47           active | broadcast | buffer | deliver | dontroute | header |
48           high_msgq_watermark | low_msgq_watermark | mode |
49           multicast_if | multicast_loop | multicast_ttl | priority |
50           {raw,
51            Protocol :: integer() >= 0,
52            OptionNum :: integer() >= 0,
53            ValueSpec ::
54                (ValueSize :: integer() >= 0) | (ValueBin :: binary())} |
55           read_packets | recbuf | reuseaddr | sndbuf | tos | tclass |
56           ttl | recvtos | recvtclass | recvttl | pktoptions |
57           ipv6_v6only
58
59       socket()
60
61              As returned by open/1,2.
62

EXPORTS

64       close(Socket) -> ok
65
66              Types:
67
68                 Socket = socket()
69
70              Closes a UDP socket.
71
72       controlling_process(Socket, Pid) -> ok | {error, Reason}
73
74              Types:
75
76                 Socket = socket()
77                 Pid = pid()
78                 Reason = closed | not_owner | badarg | inet:posix()
79
80              Assigns a new controlling process Pid to Socket. The controlling
81              process  is  the process that receives messages from the socket.
82              If called by any other  process  than  the  current  controlling
83              process,  {error, not_owner} is returned. If the process identi‐
84              fied by Pid is not an existing local  pid,  {error,  badarg}  is
85              returned.  {error,  badarg}  may  also be returned in some cases
86              when Socket is closed during the execution of this function.
87
88       open(Port) -> {ok, Socket} | {error, Reason}
89
90       open(Port, Opts) -> {ok, Socket} | {error, Reason}
91
92              Types:
93
94                 Port = inet:port_number()
95                 Opts = [Option]
96                 Option =
97                     {ip, inet:socket_address()} |
98                     {fd, integer() >= 0} |
99                     {ifaddr, inet:socket_address()} |
100                     inet:address_family() |
101                     {port, inet:port_number()} |
102                     {netns, file:filename_all()} |
103                     {bind_to_device, binary()} |
104                     option()
105                 Socket = socket()
106                 Reason = system_limit | inet:posix()
107
108              Associates a UDP port number (Port) with the calling process.
109
110              The following options are available:
111
112                list:
113                  Received Packet is delivered as a list.
114
115                binary:
116                  Received Packet is delivered as a binary.
117
118                {ip, Address}:
119                  If the host has many network interfaces, this option  speci‐
120                  fies which one to use.
121
122                {ifaddr, Address}:
123                  Same  as  {ip, Address}. If the host has many network inter‐
124                  faces, this option specifies which one to use.
125
126                {fd, integer() >= 0}:
127                  If a socket has somehow been opened without  using  gen_udp,
128                  use  this option to pass the file descriptor for it. If Port
129                  is not set to 0 and/or {ip, ip_address()} is  combined  with
130                  this  option, the fd is bound to the specified interface and
131                  port after it is being opened.  If  these  options  are  not
132                  specified, it is assumed that the fd is already bound appro‐
133                  priately.
134
135                inet6:
136                  Sets up the socket for IPv6.
137
138                inet:
139                  Sets up the socket for IPv4.
140
141                local:
142                  Sets up a Unix Domain Socket. See inet:local_address()
143
144                {udp_module, module()}:
145                  Overrides  which  callback  module  is  used.  Defaults   to
146                  inet_udp for IPv4 and inet6_udp for IPv6.
147
148                {multicast_if, Address}:
149                  Sets the local device for a multicast socket.
150
151                {multicast_loop, true | false}:
152                  When  true,  sent  multicast  packets are looped back to the
153                  local sockets.
154
155                {multicast_ttl, Integer}:
156                  Option multicast_ttl changes the time-to-live (TTL) for out‐
157                  going multicast datagrams to control the scope of the multi‐
158                  casts.
159
160                  Datagrams with a TTL of 1 are not forwarded beyond the local
161                  network. Defaults to 1.
162
163                {add_membership, {MultiAddress, InterfaceAddress}}:
164                  Joins a multicast group.
165
166                {drop_membership, {MultiAddress, InterfaceAddress}}:
167                  Leaves a multicast group.
168
169                Opt:
170                  See inet:setopts/2.
171
172              The  returned  socket  Socket  is used to send packets from this
173              port with send/4. When UDP packets arrive at the opened port, if
174              the  socket  is  in an active mode, the packets are delivered as
175              messages to the controlling process:
176
177              {udp, Socket, IP, InPortNo, Packet} % Without ancillary data
178              {udp, Socket, IP, InPortNo, AncData, Packet} % With ancillary data
179
180
181              The message contains an AncData  field  if  any  of  the  socket
182              options  recvtos, recvtclass or recvttl are active, otherwise it
183              does not.
184
185              If the socket is not in an active mode, data  can  be  retrieved
186              through  the  recv/2,3  calls.  Notice that arriving UDP packets
187              that are longer than the receive buffer option specifies can  be
188              truncated without warning.
189
190              When  a  socket  in  {active,  N}  mode  (see inet:setopts/2 for
191              details), transitions to passive  ({active,  false})  mode,  the
192              controlling  process  is  notified by a message of the following
193              form:
194
195              {udp_passive, Socket}
196
197              IP and InPortNo define the  address  from  which  Packet  comes.
198              Packet is a list of bytes if option list is specified. Packet is
199              a binary if option binary is specified.
200
201              Default value for the receive buffer option is {recbuf, 8192}.
202
203              If Port == 0, the underlying OS assigns a  free  UDP  port,  use
204              inet:port/1 to retrieve it.
205
206       recv(Socket, Length) -> {ok, RecvData} | {error, Reason}
207
208       recv(Socket, Length, Timeout) -> {ok, RecvData} | {error, Reason}
209
210              Types:
211
212                 Socket = socket()
213                 Length = integer() >= 0
214                 Timeout = timeout()
215                 RecvData =
216                     {Address,   Port,  Packet}  |  {Address,  Port,  AncData,
217                 Packet}
218                 Address = inet:ip_address() | inet:returned_non_ip_address()
219                 Port = inet:port_number()
220                 AncData = inet:ancillary_data()
221                 Packet = string() | binary()
222                 Reason = not_owner | timeout | inet:posix()
223
224              Receives a packet from a socket in passive mode. Optional param‐
225              eter  Timeout  specifies a time-out in milliseconds. Defaults to
226              infinity.
227
228              If any of the socket options recvtos, recvtclass or recvttl  are
229              active,  the RecvData tuple contains an AncData field, otherwise
230              it does not.
231
232       send(Socket, Destination, Packet) -> ok | {error, Reason}
233
234              Types:
235
236                 Socket = socket()
237                 Destination =
238                     {inet:ip_address(), inet:port_number()} |
239                     inet:family_address()
240                 Packet = iodata()
241                 Reason = not_owner | inet:posix()
242
243              Sends a packet to the specified Destination.
244
245              This function is equivalent  to  send(Socket,  Destination,  [],
246              Packet).
247
248       send(Socket, Host, Port, Packet) -> ok | {error, Reason}
249
250              Types:
251
252                 Socket = socket()
253                 Host = inet:hostname() | inet:ip_address()
254                 Port = inet:port_number() | atom()
255                 Packet = iodata()
256                 Reason = not_owner | inet:posix()
257
258              Sends a packet to the specified Host and Port.
259
260              This  clause  is  equivalent  to  send(Socket,  Host,  Port, [],
261              Packet).
262
263       send(Socket, Destination, AncData, Packet) -> ok | {error, Reason}
264
265              Types:
266
267                 Socket = socket()
268                 Destination =
269                     {inet:ip_address(), inet:port_number()} |
270                     inet:family_address()
271                 AncData = inet:ancillary_data()
272                 Packet = iodata()
273                 Reason = not_owner | inet:posix()
274
275              Sends a packet to the specified Destination with ancillary  data
276              AncData.
277
278          Note:
279              The ancillary data AncData contains options that for this single
280              message override the default options for the socket,  an  opera‐
281              tion  that  may  not  be  supported  on all platforms, and if so
282              return {error, einval}. Using more than one of an ancillary data
283              item  type  may  also not be supported. AncData =:= [] is always
284              supported.
285
286
287       send(Socket, Destination, PortZero, Packet) ->
288               ok | {error, Reason}
289
290              Types:
291
292                 Socket = socket()
293                 Destination =
294                     {inet:ip_address(), inet:port_number()} |
295                     inet:family_address()
296                 PortZero = inet:port_number()
297                 Packet = iodata()
298                 Reason = not_owner | inet:posix()
299
300              Sends a packet to the specified Destination.  Since  Destination
301              is complete, PortZero is redundant and has to be 0.
302
303              This is a legacy clause mostly for Destination = {local, Binary}
304              where PortZero is superfluous. It is equivalent to  send(Socket,
305              Destination, [], Packet), the clause right above here.
306
307       send(Socket, Host, Port, AncData, Packet) -> ok | {error, Reason}
308
309              Types:
310
311                 Socket = socket()
312                 Host =
313                     inet:hostname()        |        inet:ip_address()       |
314                 inet:local_address()
315                 Port = inet:port_number() | atom()
316                 AncData = inet:ancillary_data()
317                 Packet = iodata()
318                 Reason = not_owner | inet:posix()
319
320              Sends a packet to the specified Host and  Port,  with  ancillary
321              data AncData.
322
323              Argument  Host  can  be a hostname or a socket address, and Port
324              can be a port number or a service name atom. These are  resolved
325              into a Destination and after that this function is equivalent to
326              send(Socket, Destination, AncData,  Packet),  read  there  about
327              ancillary data.
328
329
330
331Ericsson AB                       kernel 6.5                        gen_udp(3)
Impressum