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, {inet:ip_address(), inet:ip_address()}} |
37 {broadcast, boolean()} |
38 {buffer, integer() >= 0} |
39 {deliver, port | term} |
40 {dontroute, boolean()} |
41 {drop_membership, {inet:ip_address(), inet:ip_address()}} |
42 {header, integer() >= 0} |
43 {high_msgq_watermark, integer() >= 1} |
44 {low_msgq_watermark, integer() >= 1} |
45 {mode, list | binary} |
46 list | binary |
47 {multicast_if, inet:ip_address()} |
48 {multicast_loop, boolean()} |
49 {multicast_ttl, integer() >= 0} |
50 {priority, integer() >= 0} |
51 {raw,
52 Protocol :: integer() >= 0,
53 OptionNum :: integer() >= 0,
54 ValueBin :: binary()} |
55 {read_packets, integer() >= 0} |
56 {recbuf, integer() >= 0} |
57 {reuseaddr, boolean()} |
58 {sndbuf, integer() >= 0} |
59 {tos, integer() >= 0} |
60 {tclass, integer() >= 0} |
61 {ttl, integer() >= 0} |
62 {recvtos, boolean()} |
63 {recvtclass, boolean()} |
64 {recvttl, boolean()} |
65 {ipv6_v6only, boolean()}
66 option_name() =
68 active | broadcast | buffer | deliver | dontroute | header |
69 high_msgq_watermark | low_msgq_watermark | mode |
70 multicast_if | multicast_loop | multicast_ttl | priority |
71 {raw,
72 Protocol :: integer() >= 0,
73 OptionNum :: integer() >= 0,
74 ValueSpec ::
75 (ValueSize :: integer() >= 0) | (ValueBin :: binary())} |
76 read_packets | recbuf | reuseaddr | sndbuf | tos | tclass |
77 ttl | recvtos | recvtclass | recvttl | pktoptions |
78 ipv6_v6only
79 open_option() =
81 {ip, inet:socket_address()} |
82 {fd, integer() >= 0} |
83 {ifaddr, inet:socket_address()} |
84 inet:address_family() |
85 {port, inet:port_number()} |
86 {netns, file:filename_all()} |
87 {bind_to_device, binary()} |
88 option()
89 socket()
91 As returned by open/1,2.
93
95 close(Socket) -> ok
96 Types:
98 Socket = socket()
100 Closes a UDP socket.
102 controlling_process(Socket, Pid) -> ok | {error, Reason}
104 Types:
106 Socket = socket()
108 Pid = pid()
109 Reason = closed | not_owner | badarg | inet:posix()
110 Assigns a new controlling process Pid to Socket. The controlling
112 process is the process that receives messages from the socket.
113 If called by any other process than the current controlling
114 process, {error, not_owner} is returned. If the process identi‐
115 fied by Pid is not an existing local pid, {error, badarg} is re‐
116 turned. {error, badarg} may also be returned in some cases when
117 Socket is closed during the execution of this function.
118 connect(Socket, SockAddr) -> ok | {error, Reason}
120 Types:
122 Socket = socket()
124 SockAddr = socket:sockaddr_in() | socket:sockaddr_in6()
125 Reason = inet:posix()
126 Connecting a UDP socket only means storing the specified (desti‐
128 nation) socket address, as specified by SockAddr, so that the
129 system knows where to send data.
130 This means that it is not necessary to specify the destination
132 address when sending a datagram. That is, we can use send/2.
133 It also means that the socket will only received data from this
135 address.
136 connect(Socket, Address, Port) -> ok | {error, Reason}
138 Types:
140 Socket = socket()
142 Address = inet:socket_address() | inet:hostname()
143 Port = inet:port_number()
144 Reason = inet:posix()
145 Connecting a UDP socket only means storing the specified (desti‐
147 nation) socket address, as specified by Address and Port, so
148 that the system knows where to send data.
149 This means that it is not necessary to specify the destination
151 address when sending a datagram. That is, we can use send/2.
152 It also means that the socket will only received data from this
154 address.
155 open(Port) -> {ok, Socket} | {error, Reason}
157 open(Port, Opts) -> {ok, Socket} | {error, Reason}
159 Types:
161 Port = inet:port_number()
163 Opts = [inet:inet_backend() | open_option()]
164 Socket = socket()
165 Reason = system_limit | inet:posix()
166 Associates a UDP port number (Port) with the calling process.
168 The following options are available:
170 list:
172 Received Packet is delivered as a list.
173 binary:
175 Received Packet is delivered as a binary.
176 {ip, Address}:
178 If the host has many network interfaces, this option speci‐
179 fies which one to use.
180 {ifaddr, Address}:
182 Same as {ip, Address}. If the host has many network inter‐
183 faces, this option specifies which one to use.
184 However, if this instead is an socket:sockaddr_in() or
186 socket:sockaddr_in6() this takes precedence over any value
187 previously set with the ip options. If the ip option comes
188 after the ifaddr option, it may be used to update its corre‐
189 sponding field of the ifaddr option (the addr field).
190 {fd, integer() >= 0}:
192 If a socket has somehow been opened without using gen_udp,
193 use this option to pass the file descriptor for it. If Port
194 is not set to 0 and/or {ip, ip_address()} is combined with
195 this option, the fd is bound to the specified interface and
196 port after it is being opened. If these options are not
197 specified, it is assumed that the fd is already bound appro‐
198 priately.
199 inet6:
201 Sets up the socket for IPv6.
202 inet:
204 Sets up the socket for IPv4.
205 local:
207 Sets up a Unix Domain Socket. See inet:local_address()
208 {udp_module, module()}:
210 Overrides which callback module is used. Defaults to
211 inet_udp for IPv4 and inet6_udp for IPv6.
212 {multicast_if, Address}:
214 Sets the local device for a multicast socket.
215 {multicast_loop, true | false}:
217 When true, sent multicast packets are looped back to the lo‐
218 cal sockets.
219 {multicast_ttl, Integer}:
221 Option multicast_ttl changes the time-to-live (TTL) for out‐
222 going multicast datagrams to control the scope of the multi‐
223 casts.
224 Datagrams with a TTL of 1 are not forwarded beyond the local
226 network. Defaults to 1.
227 {add_membership, {MultiAddress, InterfaceAddress}}:
229 Joins a multicast group.
230 {drop_membership, {MultiAddress, InterfaceAddress}}:
232 Leaves a multicast group.
233 Opt:
235 See inet:setopts/2.
236 The returned socket Socket is used to send packets from this
238 port with send/4. When UDP packets arrive at the opened port, if
239 the socket is in an active mode, the packets are delivered as
240 messages to the controlling process:
241 {udp, Socket, IP, InPortNo, Packet} % Without ancillary data
243 {udp, Socket, IP, InPortNo, AncData, Packet} % With ancillary data
244 The message contains an AncData field if any of the socket op‐
247 tions recvtos, recvtclass or recvttl are active, otherwise it
248 does not.
249 If the socket is not in an active mode, data can be retrieved
251 through the recv/2,3 calls. Notice that arriving UDP packets
252 that are longer than the receive buffer option specifies can be
253 truncated without warning.
254 When a socket in {active, N} mode (see inet:setopts/2 for de‐
256 tails), transitions to passive ({active, false}) mode, the con‐
257 trolling process is notified by a message of the following form:
258 {udp_passive, Socket}
260 IP and InPortNo define the address from which Packet comes.
262 Packet is a list of bytes if option list is specified. Packet is
263 a binary if option binary is specified.
264 Default value for the receive buffer option is {recbuf, 8192}.
266 If Port == 0, the underlying OS assigns a free UDP port, use
268 inet:port/1 to retrieve it.
269 recv(Socket, Length) -> {ok, RecvData} | {error, Reason}
271 recv(Socket, Length, Timeout) -> {ok, RecvData} | {error, Reason}
273 Types:
275 Socket = socket()
277 Length = integer() >= 0
278 Timeout = timeout()
279 RecvData =
280 {Address, Port, Packet} | {Address, Port, AncData,
281 Packet}
282 Address = inet:ip_address() | inet:returned_non_ip_address()
283 Port = inet:port_number()
284 AncData = inet:ancillary_data()
285 Packet = string() | binary()
286 Reason = not_owner | timeout | inet:posix()
287 Receives a packet from a socket in passive mode. Optional param‐
289 eter Timeout specifies a time-out in milliseconds. Defaults to
290 infinity.
291 If any of the socket options recvtos, recvtclass or recvttl are
293 active, the RecvData tuple contains an AncData field, otherwise
294 it does not.
295 send(Socket, Packet) -> ok | {error, Reason}
297 Types:
299 Socket = socket()
301 Packet = iodata()
302 Reason = not_owner | inet:posix()
303 Sends a packet on a connected socket (see connect/2 and con‐
305 nect/3).
306 send(Socket, Destination, Packet) -> ok | {error, Reason}
308 Types:
310 Socket = socket()
312 Destination =
313 {inet:ip_address(), inet:port_number()} |
314 inet:family_address() |
315 socket:sockaddr_in() |
316 socket:sockaddr_in6()
317 Packet = iodata()
318 Reason = not_owner | inet:posix()
319 Sends a packet to the specified Destination.
321 This function is equivalent to send(Socket, Destination, [],
323 Packet).
324 send(Socket, Host, Port, Packet) -> ok | {error, Reason}
326 Types:
328 Socket = socket()
330 Host = inet:hostname() | inet:ip_address()
331 Port = inet:port_number() | atom()
332 Packet = iodata()
333 Reason = not_owner | inet:posix()
334 Sends a packet to the specified Host and Port.
336 This clause is equivalent to send(Socket, Host, Port, [],
338 Packet).
339 send(Socket, Destination, AncData, Packet) -> ok | {error, Reason}
341 Types:
343 Socket = socket()
345 Destination =
346 {inet:ip_address(), inet:port_number()} |
347 inet:family_address() |
348 socket:sockaddr_in() |
349 socket:sockaddr_in6()
350 AncData = inet:ancillary_data()
351 Packet = iodata()
352 Reason = not_owner | inet:posix()
353 Sends a packet to the specified Destination with ancillary data
355 AncData.
356 Note:
358 The ancillary data AncData contains options that for this single
359 message override the default options for the socket, an opera‐
360 tion that may not be supported on all platforms, and if so re‐
361 turn {error, einval}. Using more than one of an ancillary data
362 item type may also not be supported. AncData =:= [] is always
363 supported.
364 send(Socket, Destination, PortZero, Packet) ->
367 ok | {error, Reason}
368 Types:
370 Socket = socket()
372 Destination =
373 {inet:ip_address(), inet:port_number()} |
374 inet:family_address()
375 PortZero = inet:port_number()
376 Packet = iodata()
377 Reason = not_owner | inet:posix()
378 Sends a packet to the specified Destination. Since Destination
380 is complete, PortZero is redundant and has to be 0.
381 This is a legacy clause mostly for Destination = {local, Binary}
383 where PortZero is superfluous. It is equivalent to send(Socket,
384 Destination, [], Packet), the clause right above here.
385 send(Socket, Host, Port, AncData, Packet) -> ok | {error, Reason}
387 Types:
389 Socket = socket()
391 Host =
392 inet:hostname() | inet:ip_address() | inet:local_ad‐
393 dress()
394 Port = inet:port_number() | atom()
395 AncData = inet:ancillary_data()
396 Packet = iodata()
397 Reason = not_owner | inet:posix()
398 Sends a packet to the specified Host and Port, with ancillary
400 data AncData.
401 Argument Host can be a hostname or a socket address, and Port
403 can be a port number or a service name atom. These are resolved
404 into a Destination and after that this function is equivalent to
405 send(Socket, Destination, AncData, Packet), read there about an‐
406 cillary data.
407Ericsson AB kernel 8.3.2 gen_udp(3)