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 * Windows require sockets (domain = inet | inet6) to be bound.
34 Currently all sockets created on Windows with inet_backend = socket
36 will be bound. If the user does not provide an address, gen_udp
37 will try to 'figure out' an address itself.
38
40 option() =
41 {active, true | false | once | -32768..32767} |
42 {add_membership, membership()} |
43 {broadcast, boolean()} |
44 {buffer, integer() >= 0} |
45 {debug, boolean()} |
46 {deliver, port | term} |
47 {dontroute, boolean()} |
48 {drop_membership, membership()} |
49 {exclusiveaddruse, boolean()} |
50 {header, integer() >= 0} |
51 {high_msgq_watermark, integer() >= 1} |
52 {low_msgq_watermark, integer() >= 1} |
53 {mode, list | binary} |
54 list | binary |
55 {multicast_if, multicast_if()} |
56 {multicast_loop, boolean()} |
57 {multicast_ttl, integer() >= 0} |
58 {priority, integer() >= 0} |
59 {raw,
60 Protocol :: integer() >= 0,
61 OptionNum :: integer() >= 0,
62 ValueBin :: binary()} |
63 {read_packets, integer() >= 0} |
64 {recbuf, integer() >= 0} |
65 {reuseaddr, boolean()} |
66 {reuseport, boolean()} |
67 {reuseport_lb, boolean()} |
68 {sndbuf, integer() >= 0} |
69 {tos, integer() >= 0} |
70 {tclass, integer() >= 0} |
71 {ttl, integer() >= 0} |
72 {recvtos, boolean()} |
73 {recvtclass, boolean()} |
74 {recvttl, boolean()} |
75 {ipv6_v6only, boolean()}
76 option_name() =
78 active | broadcast | buffer | debug | deliver | dontroute |
79 exclusiveaddruse | header | high_msgq_watermark |
80 low_msgq_watermark | mode | multicast_if | multicast_loop |
81 multicast_ttl | priority |
82 {raw,
83 Protocol :: integer() >= 0,
84 OptionNum :: integer() >= 0,
85 ValueSpec ::
86 (ValueSize :: integer() >= 0) | (ValueBin :: binary())} |
87 read_packets | recbuf | reuseaddr | reuseport | reuseport_lb |
88 sndbuf | tos | tclass | ttl | recvtos | recvtclass | recvttl |
89 pktoptions | ipv6_v6only
90 open_option() =
92 {ip, inet:socket_address()} |
93 {fd, integer() >= 0} |
94 {ifaddr, inet:socket_address()} |
95 inet:address_family() |
96 {port, inet:port_number()} |
97 {netns, file:filename_all()} |
98 {bind_to_device, binary()} |
99 option()
100 socket()
102 As returned by open/1,2.
104 multicast_if() = ip_multicast_if() | ip6_multicast_if()
106 ip_multicast_if() = inet:ip4_address()
108 ip6_multicast_if() = integer()
110 For IPv6 this is an interface index (an integer).
112 membership() = ip_membership() | ip6_membership()
114 ip_membership() =
116 {MultiAddress :: inet:ip4_address(),
117 Interface :: inet:ip4_address()} |
118 {MultiAddress :: inet:ip4_address(),
119 Address :: inet:ip4_address(),
120 IfIndex :: integer()}
121 The tuple with size 3 is *not* supported on all platforms.
123 'ifindex' defaults to zero (0) on platforms that supports the
124 3-tuple variant.
125 ip6_membership() =
127 {MultiAddress :: inet:ip6_address(), IfIndex :: integer()}
128
130 close(Socket) -> ok
131 Types:
133 Socket = socket()
135 Closes a UDP socket.
137 controlling_process(Socket, Pid) -> ok | {error, Reason}
139 Types:
141 Socket = socket()
143 Pid = pid()
144 Reason = closed | not_owner | badarg | inet:posix()
145 Assigns a new controlling process Pid to Socket. The controlling
147 process is the process that receives messages from the socket.
148 If called by any other process than the current controlling
149 process, {error, not_owner} is returned. If the process identi‐
150 fied by Pid is not an existing local pid, {error, badarg} is re‐
151 turned. {error, badarg} may also be returned in some cases when
152 Socket is closed during the execution of this function.
153 connect(Socket, SockAddr) -> ok | {error, Reason}
155 Types:
157 Socket = socket()
159 SockAddr = socket:sockaddr_in() | socket:sockaddr_in6()
160 Reason = inet:posix()
161 Connecting a UDP socket only means storing the specified (desti‐
163 nation) socket address, as specified by SockAddr, so that the
164 system knows where to send data.
165 This means that it is not necessary to specify the destination
167 address when sending a datagram. That is, we can use send/2.
168 It also means that the socket will only received data from this
170 address.
171 connect(Socket, Address, Port) -> ok | {error, Reason}
173 Types:
175 Socket = socket()
177 Address = inet:socket_address() | inet:hostname()
178 Port = inet:port_number()
179 Reason = inet:posix()
180 Connecting a UDP socket only means storing the specified (desti‐
182 nation) socket address, as specified by Address and Port, so
183 that the system knows where to send data.
184 This means that it is not necessary to specify the destination
186 address when sending a datagram. That is, we can use send/2.
187 It also means that the socket will only received data from this
189 address.
190 open(Port) -> {ok, Socket} | {error, Reason}
192 open(Port, Opts) -> {ok, Socket} | {error, Reason}
194 Types:
196 Port = inet:port_number()
198 Opts = [inet:inet_backend() | open_option()]
199 Socket = socket()
200 Reason = system_limit | inet:posix()
201 Associates a UDP port number (Port) with the calling process.
203 The following options are available:
205 list:
207 Received Packet is delivered as a list.
208 binary:
210 Received Packet is delivered as a binary.
211 {ip, Address}:
213 If the host has many network interfaces, this option speci‐
214 fies which one to use.
215 {ifaddr, Address}:
217 Same as {ip, Address}. If the host has many network inter‐
218 faces, this option specifies which one to use.
219 However, if this instead is an socket:sockaddr_in() or
221 socket:sockaddr_in6() this takes precedence over any value
222 previously set with the ip options. If the ip option comes
223 after the ifaddr option, it may be used to update its corre‐
224 sponding field of the ifaddr option (the addr field).
225 {fd, integer() >= 0}:
227 If a socket has somehow been opened without using gen_udp,
228 use this option to pass the file descriptor for it. If Port
229 is not set to 0 and/or {ip, ip_address()} is combined with
230 this option, the fd is bound to the specified interface and
231 port after it is being opened. If these options are not
232 specified, it is assumed that the fd is already bound appro‐
233 priately.
234 inet6:
236 Sets up the socket for IPv6.
237 inet:
239 Sets up the socket for IPv4.
240 local:
242 Sets up a Unix Domain Socket. See inet:local_address()
243 {udp_module, module()}:
245 Overrides which callback module is used. Defaults to
246 inet_udp for IPv4 and inet6_udp for IPv6.
247 {multicast_if, Address}:
249 Sets the local device for a multicast socket.
250 {multicast_loop, true | false}:
252 When true, sent multicast packets are looped back to the lo‐
253 cal sockets.
254 {multicast_ttl, Integer}:
256 Option multicast_ttl changes the time-to-live (TTL) for out‐
257 going multicast datagrams to control the scope of the multi‐
258 casts.
259 Datagrams with a TTL of 1 are not forwarded beyond the local
261 network. Defaults to 1.
262 {add_membership, {MultiAddress, InterfaceAddress}}:
264 Joins a multicast group.
265 {drop_membership, {MultiAddress, InterfaceAddress}}:
267 Leaves a multicast group.
268 Opt:
270 See inet:setopts/2.
271 The returned socket Socket is used to send packets from this
273 port with send/4. When UDP packets arrive at the opened port, if
274 the socket is in an active mode, the packets are delivered as
275 messages to the controlling process:
276 {udp, Socket, IP, InPortNo, Packet} % Without ancillary data
278 {udp, Socket, IP, InPortNo, AncData, Packet} % With ancillary data
279 The message contains an AncData field if any of the socket op‐
282 tions recvtos, recvtclass or recvttl are active, otherwise it
283 does not.
284 If the socket is not in an active mode, data can be retrieved
286 through the recv/2,3 calls. Notice that arriving UDP packets
287 that are longer than the receive buffer option specifies can be
288 truncated without warning.
289 When a socket in {active, N} mode (see inet:setopts/2 for de‐
291 tails), transitions to passive ({active, false}) mode, the con‐
292 trolling process is notified by a message of the following form:
293 {udp_passive, Socket}
295 IP and InPortNo define the address from which Packet comes.
297 Packet is a list of bytes if option list is specified. Packet is
298 a binary if option binary is specified.
299 Default value for the receive buffer option is {recbuf, 8192}.
301 If Port == 0, the underlying OS assigns a free UDP port, use
303 inet:port/1 to retrieve it.
304 recv(Socket, Length) -> {ok, RecvData} | {error, Reason}
306 recv(Socket, Length, Timeout) -> {ok, RecvData} | {error, Reason}
308 Types:
310 Socket = socket()
312 Length = integer() >= 0
313 Timeout = timeout()
314 RecvData =
315 {Address, Port, Packet} | {Address, Port, AncData,
316 Packet}
317 Address = inet:ip_address() | inet:returned_non_ip_address()
318 Port = inet:port_number()
319 AncData = inet:ancillary_data()
320 Packet = string() | binary()
321 Reason = not_owner | timeout | inet:posix()
322 Receives a packet from a socket in passive mode. Optional param‐
324 eter Timeout specifies a time-out in milliseconds. Defaults to
325 infinity.
326 If any of the socket options recvtos, recvtclass or recvttl are
328 active, the RecvData tuple contains an AncData field, otherwise
329 it does not.
330 send(Socket, Packet) -> ok | {error, Reason}
332 Types:
334 Socket = socket()
336 Packet = iodata()
337 Reason = not_owner | inet:posix()
338 Sends a packet on a connected socket (see connect/2 and con‐
340 nect/3).
341 send(Socket, Destination, Packet) -> ok | {error, Reason}
343 Types:
345 Socket = socket()
347 Destination =
348 {inet:ip_address(), inet:port_number()} |
349 inet:family_address() |
350 socket:sockaddr_in() |
351 socket:sockaddr_in6()
352 Packet = iodata()
353 Reason = not_owner | inet:posix()
354 Sends a packet to the specified Destination.
356 This function is equivalent to send(Socket, Destination, [],
358 Packet).
359 send(Socket, Host, Port, Packet) -> ok | {error, Reason}
361 Types:
363 Socket = socket()
365 Host = inet:hostname() | inet:ip_address()
366 Port = inet:port_number() | atom()
367 Packet = iodata()
368 Reason = not_owner | inet:posix()
369 Sends a packet to the specified Host and Port.
371 This clause is equivalent to send(Socket, Host, Port, [],
373 Packet).
374 send(Socket, Destination, AncData, Packet) -> ok | {error, Reason}
376 Types:
378 Socket = socket()
380 Destination =
381 {inet:ip_address(), inet:port_number()} |
382 inet:family_address() |
383 socket:sockaddr_in() |
384 socket:sockaddr_in6()
385 AncData = inet:ancillary_data()
386 Packet = iodata()
387 Reason = not_owner | inet:posix()
388 Sends a packet to the specified Destination with ancillary data
390 AncData.
391 Note:
393 The ancillary data AncData contains options that for this single
394 message override the default options for the socket, an opera‐
395 tion that may not be supported on all platforms, and if so re‐
396 turn {error, einval}. Using more than one of an ancillary data
397 item type may also not be supported. AncData =:= [] is always
398 supported.
399 send(Socket, Destination, PortZero, Packet) ->
402 ok | {error, Reason}
403 Types:
405 Socket = socket()
407 Destination =
408 {inet:ip_address(), inet:port_number()} |
409 inet:family_address()
410 PortZero = inet:port_number()
411 Packet = iodata()
412 Reason = not_owner | inet:posix()
413 Sends a packet to the specified Destination. Since Destination
415 is complete, PortZero is redundant and has to be 0.
416 This is a legacy clause mostly for Destination = {local, Binary}
418 where PortZero is superfluous. It is equivalent to send(Socket,
419 Destination, [], Packet), the clause right above here.
420 send(Socket, Host, Port, AncData, Packet) -> ok | {error, Reason}
422 Types:
424 Socket = socket()
426 Host =
427 inet:hostname() | inet:ip_address() | inet:local_ad‐
428 dress()
429 Port = inet:port_number() | atom()
430 AncData = inet:ancillary_data()
431 Packet = iodata()
432 Reason = not_owner | inet:posix()
433 Sends a packet to the specified Host and Port, with ancillary
435 data AncData.
436 Argument Host can be a hostname or a socket address, and Port
438 can be a port number or a service name atom. These are resolved
439 into a Destination and after that this function is equivalent to
440 send(Socket, Destination, AncData, Packet), read there about an‐
441 cillary data.
442Ericsson AB kernel 9.1 gen_udp(3)