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
12   Note:
13       Functions that create sockets can take an optional option;  {inet_back‐
14       end,  Backend} that, if specified, has to be the first option. This se‐
15       lects the implementation backend towards the platform's socket API.
16
17       This is a temporary option that will be ignored in a future release.
18
19       The default is Backend = inet that selects the  traditional  inet_drv.c
20       driver.  The  other  choice  is  Backend  = socket that selects the new
21       socket module and its NIF implementation.
22
23       The system default can be changed when the node is started with the ap‐
24       plication kernel's configuration variable inet_backend.
25
26       For gen_udp with inet_backend = socket we have tried to be as "compati‐
27       ble" as possible which has sometimes been impossible. Here is a list of
28       cases  when the behaviour of inet-backend inet (default) and socket are
29       different:
30
31         * The option read_packets is currently ignored.
32

DATA TYPES

34       option() =
35           {active, true | false | once | -32768..32767} |
36           {add_membership, membership()} |
37           {broadcast, boolean()} |
38           {buffer, integer() >= 0} |
39           {debug, boolean()} |
40           {deliver, port | term} |
41           {dontroute, boolean()} |
42           {drop_membership, membership()} |
43           {header, integer() >= 0} |
44           {high_msgq_watermark, integer() >= 1} |
45           {low_msgq_watermark, integer() >= 1} |
46           {mode, list | binary} |
47           list | binary |
48           {multicast_if, multicast_if()} |
49           {multicast_loop, boolean()} |
50           {multicast_ttl, integer() >= 0} |
51           {priority, integer() >= 0} |
52           {raw,
53            Protocol :: integer() >= 0,
54            OptionNum :: integer() >= 0,
55            ValueBin :: binary()} |
56           {read_packets, integer() >= 0} |
57           {recbuf, integer() >= 0} |
58           {reuseaddr, boolean()} |
59           {sndbuf, integer() >= 0} |
60           {tos, integer() >= 0} |
61           {tclass, integer() >= 0} |
62           {ttl, integer() >= 0} |
63           {recvtos, boolean()} |
64           {recvtclass, boolean()} |
65           {recvttl, boolean()} |
66           {ipv6_v6only, boolean()}
67
68       option_name() =
69           active | broadcast | buffer | debug | deliver | dontroute |
70           header | high_msgq_watermark | low_msgq_watermark | mode |
71           multicast_if | multicast_loop | multicast_ttl | priority |
72           {raw,
73            Protocol :: integer() >= 0,
74            OptionNum :: integer() >= 0,
75            ValueSpec ::
76                (ValueSize :: integer() >= 0) | (ValueBin :: binary())} |
77           read_packets | recbuf | reuseaddr | sndbuf | tos | tclass |
78           ttl | recvtos | recvtclass | recvttl | pktoptions |
79           ipv6_v6only
80
81       open_option() =
82           {ip, inet:socket_address()} |
83           {fd, integer() >= 0} |
84           {ifaddr, inet:socket_address()} |
85           inet:address_family() |
86           {port, inet:port_number()} |
87           {netns, file:filename_all()} |
88           {bind_to_device, binary()} |
89           option()
90
91       socket()
92
93              As returned by open/1,2.
94
95       multicast_if() = ip_multicast_if() | ip6_multicast_if()
96
97       ip_multicast_if() = inet:ip4_address()
98
99       ip6_multicast_if() = integer()
100
101              For IPv6 this is an interface index (an integer).
102
103       membership() = ip_membership() | ip6_membership()
104
105       ip_membership() =
106           {MultiAddress :: inet:ip4_address(),
107            Interface :: inet:ip4_address()} |
108           {MultiAddress :: inet:ip4_address(),
109            Address :: inet:ip4_address(),
110            IfIndex :: integer()}
111
112              The tuple with size 3  is  *not*  supported  on  all  platforms.
113              'ifindex'  defaults  to  zero (0) on platforms that supports the
114              3-tuple variant.
115
116       ip6_membership() =
117           {MultiAddress :: inet:ip6_address(), IfIndex :: integer()}
118

EXPORTS

120       close(Socket) -> ok
121
122              Types:
123
124                 Socket = socket()
125
126              Closes a UDP socket.
127
128       controlling_process(Socket, Pid) -> ok | {error, Reason}
129
130              Types:
131
132                 Socket = socket()
133                 Pid = pid()
134                 Reason = closed | not_owner | badarg | inet:posix()
135
136              Assigns a new controlling process Pid to Socket. The controlling
137              process  is  the process that receives messages from the socket.
138              If called by any other  process  than  the  current  controlling
139              process,  {error, not_owner} is returned. If the process identi‐
140              fied by Pid is not an existing local pid, {error, badarg} is re‐
141              turned.  {error, badarg} may also be returned in some cases when
142              Socket is closed during the execution of this function.
143
144       connect(Socket, SockAddr) -> ok | {error, Reason}
145
146              Types:
147
148                 Socket = socket()
149                 SockAddr = socket:sockaddr_in() | socket:sockaddr_in6()
150                 Reason = inet:posix()
151
152              Connecting a UDP socket only means storing the specified (desti‐
153              nation)  socket  address,  as specified by SockAddr, so that the
154              system knows where to send data.
155
156              This means that it is not necessary to specify  the  destination
157              address when sending a datagram. That is, we can use send/2.
158
159              It  also means that the socket will only received data from this
160              address.
161
162       connect(Socket, Address, Port) -> ok | {error, Reason}
163
164              Types:
165
166                 Socket = socket()
167                 Address = inet:socket_address() | inet:hostname()
168                 Port = inet:port_number()
169                 Reason = inet:posix()
170
171              Connecting a UDP socket only means storing the specified (desti‐
172              nation)  socket  address,  as  specified by Address and Port, so
173              that the system knows where to send data.
174
175              This means that it is not necessary to specify  the  destination
176              address when sending a datagram. That is, we can use send/2.
177
178              It  also means that the socket will only received data from this
179              address.
180
181       open(Port) -> {ok, Socket} | {error, Reason}
182
183       open(Port, Opts) -> {ok, Socket} | {error, Reason}
184
185              Types:
186
187                 Port = inet:port_number()
188                 Opts = [inet:inet_backend() | open_option()]
189                 Socket = socket()
190                 Reason = system_limit | inet:posix()
191
192              Associates a UDP port number (Port) with the calling process.
193
194              The following options are available:
195
196                list:
197                  Received Packet is delivered as a list.
198
199                binary:
200                  Received Packet is delivered as a binary.
201
202                {ip, Address}:
203                  If the host has many network interfaces, this option  speci‐
204                  fies which one to use.
205
206                {ifaddr, Address}:
207                  Same  as  {ip, Address}. If the host has many network inter‐
208                  faces, this option specifies which one to use.
209
210                  However, if  this  instead  is  an  socket:sockaddr_in()  or
211                  socket:sockaddr_in6()  this  takes precedence over any value
212                  previously set with the ip options. If the ip  option  comes
213                  after the ifaddr option, it may be used to update its corre‐
214                  sponding field of the ifaddr option (the addr field).
215
216                {fd, integer() >= 0}:
217                  If a socket has somehow been opened without  using  gen_udp,
218                  use  this option to pass the file descriptor for it. If Port
219                  is not set to 0 and/or {ip, ip_address()} is  combined  with
220                  this  option, the fd is bound to the specified interface and
221                  port after it is being opened.  If  these  options  are  not
222                  specified, it is assumed that the fd is already bound appro‐
223                  priately.
224
225                inet6:
226                  Sets up the socket for IPv6.
227
228                inet:
229                  Sets up the socket for IPv4.
230
231                local:
232                  Sets up a Unix Domain Socket. See inet:local_address()
233
234                {udp_module, module()}:
235                  Overrides  which  callback  module  is  used.  Defaults   to
236                  inet_udp for IPv4 and inet6_udp for IPv6.
237
238                {multicast_if, Address}:
239                  Sets the local device for a multicast socket.
240
241                {multicast_loop, true | false}:
242                  When true, sent multicast packets are looped back to the lo‐
243                  cal sockets.
244
245                {multicast_ttl, Integer}:
246                  Option multicast_ttl changes the time-to-live (TTL) for out‐
247                  going multicast datagrams to control the scope of the multi‐
248                  casts.
249
250                  Datagrams with a TTL of 1 are not forwarded beyond the local
251                  network. Defaults to 1.
252
253                {add_membership, {MultiAddress, InterfaceAddress}}:
254                  Joins a multicast group.
255
256                {drop_membership, {MultiAddress, InterfaceAddress}}:
257                  Leaves a multicast group.
258
259                Opt:
260                  See inet:setopts/2.
261
262              The  returned  socket  Socket  is used to send packets from this
263              port with send/4. When UDP packets arrive at the opened port, if
264              the  socket  is  in an active mode, the packets are delivered as
265              messages to the controlling process:
266
267              {udp, Socket, IP, InPortNo, Packet} % Without ancillary data
268              {udp, Socket, IP, InPortNo, AncData, Packet} % With ancillary data
269
270
271              The message contains an AncData field if any of the  socket  op‐
272              tions  recvtos,  recvtclass  or recvttl are active, otherwise it
273              does not.
274
275              If the socket is not in an active mode, data  can  be  retrieved
276              through  the  recv/2,3  calls.  Notice that arriving UDP packets
277              that are longer than the receive buffer option specifies can  be
278              truncated without warning.
279
280              When  a  socket  in {active, N} mode (see inet:setopts/2 for de‐
281              tails), transitions to passive ({active, false}) mode, the  con‐
282              trolling process is notified by a message of the following form:
283
284              {udp_passive, Socket}
285
286              IP  and  InPortNo  define  the  address from which Packet comes.
287              Packet is a list of bytes if option list is specified. Packet is
288              a binary if option binary is specified.
289
290              Default value for the receive buffer option is {recbuf, 8192}.
291
292              If  Port  ==  0,  the underlying OS assigns a free UDP port, use
293              inet:port/1 to retrieve it.
294
295       recv(Socket, Length) -> {ok, RecvData} | {error, Reason}
296
297       recv(Socket, Length, Timeout) -> {ok, RecvData} | {error, Reason}
298
299              Types:
300
301                 Socket = socket()
302                 Length = integer() >= 0
303                 Timeout = timeout()
304                 RecvData =
305                     {Address,  Port,  Packet}  |  {Address,  Port,   AncData,
306                 Packet}
307                 Address = inet:ip_address() | inet:returned_non_ip_address()
308                 Port = inet:port_number()
309                 AncData = inet:ancillary_data()
310                 Packet = string() | binary()
311                 Reason = not_owner | timeout | inet:posix()
312
313              Receives a packet from a socket in passive mode. Optional param‐
314              eter Timeout specifies a time-out in milliseconds.  Defaults  to
315              infinity.
316
317              If  any of the socket options recvtos, recvtclass or recvttl are
318              active, the RecvData tuple contains an AncData field,  otherwise
319              it does not.
320
321       send(Socket, Packet) -> ok | {error, Reason}
322
323              Types:
324
325                 Socket = socket()
326                 Packet = iodata()
327                 Reason = not_owner | inet:posix()
328
329              Sends  a  packet  on  a connected socket (see connect/2 and con‐
330              nect/3).
331
332       send(Socket, Destination, Packet) -> ok | {error, Reason}
333
334              Types:
335
336                 Socket = socket()
337                 Destination =
338                     {inet:ip_address(), inet:port_number()} |
339                     inet:family_address() |
340                     socket:sockaddr_in() |
341                     socket:sockaddr_in6()
342                 Packet = iodata()
343                 Reason = not_owner | inet:posix()
344
345              Sends a packet to the specified Destination.
346
347              This function is equivalent  to  send(Socket,  Destination,  [],
348              Packet).
349
350       send(Socket, Host, Port, Packet) -> ok | {error, Reason}
351
352              Types:
353
354                 Socket = socket()
355                 Host = inet:hostname() | inet:ip_address()
356                 Port = inet:port_number() | atom()
357                 Packet = iodata()
358                 Reason = not_owner | inet:posix()
359
360              Sends a packet to the specified Host and Port.
361
362              This  clause  is  equivalent  to  send(Socket,  Host,  Port, [],
363              Packet).
364
365       send(Socket, Destination, AncData, Packet) -> ok | {error, Reason}
366
367              Types:
368
369                 Socket = socket()
370                 Destination =
371                     {inet:ip_address(), inet:port_number()} |
372                     inet:family_address() |
373                     socket:sockaddr_in() |
374                     socket:sockaddr_in6()
375                 AncData = inet:ancillary_data()
376                 Packet = iodata()
377                 Reason = not_owner | inet:posix()
378
379              Sends a packet to the specified Destination with ancillary  data
380              AncData.
381
382          Note:
383              The ancillary data AncData contains options that for this single
384              message override the default options for the socket,  an  opera‐
385              tion  that  may not be supported on all platforms, and if so re‐
386              turn {error, einval}. Using more than one of an  ancillary  data
387              item  type  may  also not be supported. AncData =:= [] is always
388              supported.
389
390
391       send(Socket, Destination, PortZero, Packet) ->
392               ok | {error, Reason}
393
394              Types:
395
396                 Socket = socket()
397                 Destination =
398                     {inet:ip_address(), inet:port_number()} |
399                     inet:family_address()
400                 PortZero = inet:port_number()
401                 Packet = iodata()
402                 Reason = not_owner | inet:posix()
403
404              Sends a packet to the specified Destination.  Since  Destination
405              is complete, PortZero is redundant and has to be 0.
406
407              This is a legacy clause mostly for Destination = {local, Binary}
408              where PortZero is superfluous. It is equivalent to  send(Socket,
409              Destination, [], Packet), the clause right above here.
410
411       send(Socket, Host, Port, AncData, Packet) -> ok | {error, Reason}
412
413              Types:
414
415                 Socket = socket()
416                 Host =
417                     inet:hostname()   |  inet:ip_address()  |  inet:local_ad‐
418                 dress()
419                 Port = inet:port_number() | atom()
420                 AncData = inet:ancillary_data()
421                 Packet = iodata()
422                 Reason = not_owner | inet:posix()
423
424              Sends a packet to the specified Host and  Port,  with  ancillary
425              data AncData.
426
427              Argument  Host  can  be a hostname or a socket address, and Port
428              can be a port number or a service name atom. These are  resolved
429              into a Destination and after that this function is equivalent to
430              send(Socket, Destination, AncData, Packet), read there about an‐
431              cillary data.
432
433
434
435Ericsson AB                     kernel 8.5.4.2                      gen_udp(3)
Impressum