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 open(Port) -> {ok, Socket} | {error, Reason}
120 open(Port, Opts) -> {ok, Socket} | {error, Reason}
122 Types:
124 Port = inet:port_number()
126 Opts = [inet:inet_backend() | open_option()]
127 Socket = socket()
128 Reason = system_limit | inet:posix()
129 Associates a UDP port number (Port) with the calling process.
131 The following options are available:
133 list:
135 Received Packet is delivered as a list.
136 binary:
138 Received Packet is delivered as a binary.
139 {ip, Address}:
141 If the host has many network interfaces, this option speci‐
142 fies which one to use.
143 {ifaddr, Address}:
145 Same as {ip, Address}. If the host has many network inter‐
146 faces, this option specifies which one to use.
147 {fd, integer() >= 0}:
149 If a socket has somehow been opened without using gen_udp,
150 use this option to pass the file descriptor for it. If Port
151 is not set to 0 and/or {ip, ip_address()} is combined with
152 this option, the fd is bound to the specified interface and
153 port after it is being opened. If these options are not
154 specified, it is assumed that the fd is already bound appro‐
155 priately.
156 inet6:
158 Sets up the socket for IPv6.
159 inet:
161 Sets up the socket for IPv4.
162 local:
164 Sets up a Unix Domain Socket. See inet:local_address()
165 {udp_module, module()}:
167 Overrides which callback module is used. Defaults to
168 inet_udp for IPv4 and inet6_udp for IPv6.
169 {multicast_if, Address}:
171 Sets the local device for a multicast socket.
172 {multicast_loop, true | false}:
174 When true, sent multicast packets are looped back to the lo‐
175 cal sockets.
176 {multicast_ttl, Integer}:
178 Option multicast_ttl changes the time-to-live (TTL) for out‐
179 going multicast datagrams to control the scope of the multi‐
180 casts.
181 Datagrams with a TTL of 1 are not forwarded beyond the local
183 network. Defaults to 1.
184 {add_membership, {MultiAddress, InterfaceAddress}}:
186 Joins a multicast group.
187 {drop_membership, {MultiAddress, InterfaceAddress}}:
189 Leaves a multicast group.
190 Opt:
192 See inet:setopts/2.
193 The returned socket Socket is used to send packets from this
195 port with send/4. When UDP packets arrive at the opened port, if
196 the socket is in an active mode, the packets are delivered as
197 messages to the controlling process:
198 {udp, Socket, IP, InPortNo, Packet} % Without ancillary data
200 {udp, Socket, IP, InPortNo, AncData, Packet} % With ancillary data
201 The message contains an AncData field if any of the socket op‐
204 tions recvtos, recvtclass or recvttl are active, otherwise it
205 does not.
206 If the socket is not in an active mode, data can be retrieved
208 through the recv/2,3 calls. Notice that arriving UDP packets
209 that are longer than the receive buffer option specifies can be
210 truncated without warning.
211 When a socket in {active, N} mode (see inet:setopts/2 for de‐
213 tails), transitions to passive ({active, false}) mode, the con‐
214 trolling process is notified by a message of the following form:
215 {udp_passive, Socket}
217 IP and InPortNo define the address from which Packet comes.
219 Packet is a list of bytes if option list is specified. Packet is
220 a binary if option binary is specified.
221 Default value for the receive buffer option is {recbuf, 8192}.
223 If Port == 0, the underlying OS assigns a free UDP port, use
225 inet:port/1 to retrieve it.
226 recv(Socket, Length) -> {ok, RecvData} | {error, Reason}
228 recv(Socket, Length, Timeout) -> {ok, RecvData} | {error, Reason}
230 Types:
232 Socket = socket()
234 Length = integer() >= 0
235 Timeout = timeout()
236 RecvData =
237 {Address, Port, Packet} | {Address, Port, AncData,
238 Packet}
239 Address = inet:ip_address() | inet:returned_non_ip_address()
240 Port = inet:port_number()
241 AncData = inet:ancillary_data()
242 Packet = string() | binary()
243 Reason = not_owner | timeout | inet:posix()
244 Receives a packet from a socket in passive mode. Optional param‐
246 eter Timeout specifies a time-out in milliseconds. Defaults to
247 infinity.
248 If any of the socket options recvtos, recvtclass or recvttl are
250 active, the RecvData tuple contains an AncData field, otherwise
251 it does not.
252 send(Socket, Destination, Packet) -> ok | {error, Reason}
254 Types:
256 Socket = socket()
258 Destination =
259 {inet:ip_address(), inet:port_number()} |
260 inet:family_address()
261 Packet = iodata()
262 Reason = not_owner | inet:posix()
263 Sends a packet to the specified Destination.
265 This function is equivalent to send(Socket, Destination, [],
267 Packet).
268 send(Socket, Host, Port, Packet) -> ok | {error, Reason}
270 Types:
272 Socket = socket()
274 Host = inet:hostname() | inet:ip_address()
275 Port = inet:port_number() | atom()
276 Packet = iodata()
277 Reason = not_owner | inet:posix()
278 Sends a packet to the specified Host and Port.
280 This clause is equivalent to send(Socket, Host, Port, [],
282 Packet).
283 send(Socket, Destination, AncData, Packet) -> ok | {error, Reason}
285 Types:
287 Socket = socket()
289 Destination =
290 {inet:ip_address(), inet:port_number()} |
291 inet:family_address()
292 AncData = inet:ancillary_data()
293 Packet = iodata()
294 Reason = not_owner | inet:posix()
295 Sends a packet to the specified Destination with ancillary data
297 AncData.
298 Note:
300 The ancillary data AncData contains options that for this single
301 message override the default options for the socket, an opera‐
302 tion that may not be supported on all platforms, and if so re‐
303 turn {error, einval}. Using more than one of an ancillary data
304 item type may also not be supported. AncData =:= [] is always
305 supported.
306 send(Socket, Destination, PortZero, Packet) ->
309 ok | {error, Reason}
310 Types:
312 Socket = socket()
314 Destination =
315 {inet:ip_address(), inet:port_number()} |
316 inet:family_address()
317 PortZero = inet:port_number()
318 Packet = iodata()
319 Reason = not_owner | inet:posix()
320 Sends a packet to the specified Destination. Since Destination
322 is complete, PortZero is redundant and has to be 0.
323 This is a legacy clause mostly for Destination = {local, Binary}
325 where PortZero is superfluous. It is equivalent to send(Socket,
326 Destination, [], Packet), the clause right above here.
327 send(Socket, Host, Port, AncData, Packet) -> ok | {error, Reason}
329 Types:
331 Socket = socket()
333 Host =
334 inet:hostname() | inet:ip_address() | inet:local_ad‐
335 dress()
336 Port = inet:port_number() | atom()
337 AncData = inet:ancillary_data()
338 Packet = iodata()
339 Reason = not_owner | inet:posix()
340 Sends a packet to the specified Host and Port, with ancillary
342 data AncData.
343 Argument Host can be a hostname or a socket address, and Port
345 can be a port number or a service name atom. These are resolved
346 into a Destination and after that this function is equivalent to
347 send(Socket, Destination, AncData, Packet), read there about an‐
348 cillary data.
349Ericsson AB kernel 8.1.3 gen_udp(3)