1gen_udp(3) Erlang Module Definition gen_udp(3)
2
6 gen_udp - Interface to UDP sockets.
7
9 This module provides functions for communicating with sockets using the
10 UDP protocol.
11 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 This is a temporary option that will be ignored in a future release.
18 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 The system default can be changed when the node is started with the ap‐
24 plication kernel's configuration variable inet_backend.
25 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 * The option read_packets is currently ignored.
32
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 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 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 socket()
92 As returned by open/1,2.
94 multicast_if() = ip_multicast_if() | ip6_multicast_if()
96 ip_multicast_if() = inet:ip4_address()
98 ip6_multicast_if() = integer()
100 For IPv6 this is an interface index (an integer).
102 membership() = ip_membership() | ip6_membership()
104 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 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 ip6_membership() =
117 {MultiAddress :: inet:ip6_address(), IfIndex :: integer()}
118
120 close(Socket) -> ok
121 Types:
123 Socket = socket()
125 Closes a UDP socket.
127 controlling_process(Socket, Pid) -> ok | {error, Reason}
129 Types:
131 Socket = socket()
133 Pid = pid()
134 Reason = closed | not_owner | badarg | inet:posix()
135 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 connect(Socket, SockAddr) -> ok | {error, Reason}
145 Types:
147 Socket = socket()
149 SockAddr = socket:sockaddr_in() | socket:sockaddr_in6()
150 Reason = inet:posix()
151 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 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 It also means that the socket will only received data from this
160 address.
161 connect(Socket, Address, Port) -> ok | {error, Reason}
163 Types:
165 Socket = socket()
167 Address = inet:socket_address() | inet:hostname()
168 Port = inet:port_number()
169 Reason = inet:posix()
170 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 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 It also means that the socket will only received data from this
179 address.
180 open(Port) -> {ok, Socket} | {error, Reason}
182 open(Port, Opts) -> {ok, Socket} | {error, Reason}
184 Types:
186 Port = inet:port_number()
188 Opts = [inet:inet_backend() | open_option()]
189 Socket = socket()
190 Reason = system_limit | inet:posix()
191 Associates a UDP port number (Port) with the calling process.
193 The following options are available:
195 list:
197 Received Packet is delivered as a list.
198 binary:
200 Received Packet is delivered as a binary.
201 {ip, Address}:
203 If the host has many network interfaces, this option speci‐
204 fies which one to use.
205 {ifaddr, Address}:
207 Same as {ip, Address}. If the host has many network inter‐
208 faces, this option specifies which one to use.
209 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 {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 inet6:
226 Sets up the socket for IPv6.
227 inet:
229 Sets up the socket for IPv4.
230 local:
232 Sets up a Unix Domain Socket. See inet:local_address()
233 {udp_module, module()}:
235 Overrides which callback module is used. Defaults to
236 inet_udp for IPv4 and inet6_udp for IPv6.
237 {multicast_if, Address}:
239 Sets the local device for a multicast socket.
240 {multicast_loop, true | false}:
242 When true, sent multicast packets are looped back to the lo‐
243 cal sockets.
244 {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 Datagrams with a TTL of 1 are not forwarded beyond the local
251 network. Defaults to 1.
252 {add_membership, {MultiAddress, InterfaceAddress}}:
254 Joins a multicast group.
255 {drop_membership, {MultiAddress, InterfaceAddress}}:
257 Leaves a multicast group.
258 Opt:
260 See inet:setopts/2.
261 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 {udp, Socket, IP, InPortNo, Packet} % Without ancillary data
268 {udp, Socket, IP, InPortNo, AncData, Packet} % With ancillary data
269 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 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 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 {udp_passive, Socket}
285 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 Default value for the receive buffer option is {recbuf, 8192}.
291 If Port == 0, the underlying OS assigns a free UDP port, use
293 inet:port/1 to retrieve it.
294 recv(Socket, Length) -> {ok, RecvData} | {error, Reason}
296 recv(Socket, Length, Timeout) -> {ok, RecvData} | {error, Reason}
298 Types:
300 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 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 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 send(Socket, Packet) -> ok | {error, Reason}
322 Types:
324 Socket = socket()
326 Packet = iodata()
327 Reason = not_owner | inet:posix()
328 Sends a packet on a connected socket (see connect/2 and con‐
330 nect/3).
331 send(Socket, Destination, Packet) -> ok | {error, Reason}
333 Types:
335 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 Sends a packet to the specified Destination.
346 This function is equivalent to send(Socket, Destination, [],
348 Packet).
349 send(Socket, Host, Port, Packet) -> ok | {error, Reason}
351 Types:
353 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 Sends a packet to the specified Host and Port.
361 This clause is equivalent to send(Socket, Host, Port, [],
363 Packet).
364 send(Socket, Destination, AncData, Packet) -> ok | {error, Reason}
366 Types:
368 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 Sends a packet to the specified Destination with ancillary data
380 AncData.
381 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 send(Socket, Destination, PortZero, Packet) ->
392 ok | {error, Reason}
393 Types:
395 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 Sends a packet to the specified Destination. Since Destination
405 is complete, PortZero is redundant and has to be 0.
406 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 send(Socket, Host, Port, AncData, Packet) -> ok | {error, Reason}
412 Types:
414 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 Sends a packet to the specified Host and Port, with ancillary
425 data AncData.
426 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.
432Ericsson AB kernel 8.5.3 gen_udp(3)