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
13 option() =
14 {active, true | false | once | -32768..32767} |
15 {add_membership, {inet:ip_address(), inet:ip_address()}} |
16 {broadcast, boolean()} |
17 {buffer, integer() >= 0} |
18 {deliver, port | term} |
19 {dontroute, boolean()} |
20 {drop_membership, {inet:ip_address(), inet:ip_address()}} |
21 {header, integer() >= 0} |
22 {high_msgq_watermark, integer() >= 1} |
23 {low_msgq_watermark, integer() >= 1} |
24 {mode, list | binary} |
25 list | binary |
26 {multicast_if, inet:ip_address()} |
27 {multicast_loop, boolean()} |
28 {multicast_ttl, integer() >= 0} |
29 {priority, integer() >= 0} |
30 {raw,
31 Protocol :: integer() >= 0,
32 OptionNum :: integer() >= 0,
33 ValueBin :: binary()} |
34 {read_packets, integer() >= 0} |
35 {recbuf, integer() >= 0} |
36 {reuseaddr, boolean()} |
37 {sndbuf, integer() >= 0} |
38 {tos, integer() >= 0} |
39 {tclass, integer() >= 0} |
40 {ttl, integer() >= 0} |
41 {recvtos, boolean()} |
42 {recvtclass, boolean()} |
43 {recvttl, boolean()} |
44 {ipv6_v6only, boolean()}
45 option_name() =
47 active | broadcast | buffer | deliver | dontroute | header |
48 high_msgq_watermark | low_msgq_watermark | mode |
49 multicast_if | multicast_loop | multicast_ttl | priority |
50 {raw,
51 Protocol :: integer() >= 0,
52 OptionNum :: integer() >= 0,
53 ValueSpec ::
54 (ValueSize :: integer() >= 0) | (ValueBin :: binary())} |
55 read_packets | recbuf | reuseaddr | sndbuf | tos | tclass |
56 ttl | recvtos | recvtclass | recvttl | pktoptions |
57 ipv6_v6only
58 socket()
60 As returned by open/1,2.
62
64 close(Socket) -> ok
65 Types:
67 Socket = socket()
69 Closes a UDP socket.
71 controlling_process(Socket, Pid) -> ok | {error, Reason}
73 Types:
75 Socket = socket()
77 Pid = pid()
78 Reason = closed | not_owner | badarg | inet:posix()
79 Assigns a new controlling process Pid to Socket. The controlling
81 process is the process that receives messages from the socket.
82 If called by any other process than the current controlling
83 process, {error, not_owner} is returned. If the process identi‐
84 fied by Pid is not an existing local pid, {error, badarg} is re‐
85 turned. {error, badarg} may also be returned in some cases when
86 Socket is closed during the execution of this function.
87 open(Port) -> {ok, Socket} | {error, Reason}
89 open(Port, Opts) -> {ok, Socket} | {error, Reason}
91 Types:
93 Port = inet:port_number()
95 Opts = [Option]
96 Option =
97 {ip, inet:socket_address()} |
98 {fd, integer() >= 0} |
99 {ifaddr, inet:socket_address()} |
100 inet:address_family() |
101 {port, inet:port_number()} |
102 {netns, file:filename_all()} |
103 {bind_to_device, binary()} |
104 option()
105 Socket = socket()
106 Reason = system_limit | inet:posix()
107 Associates a UDP port number (Port) with the calling process.
109 The following options are available:
111 list:
113 Received Packet is delivered as a list.
114 binary:
116 Received Packet is delivered as a binary.
117 {ip, Address}:
119 If the host has many network interfaces, this option speci‐
120 fies which one to use.
121 {ifaddr, Address}:
123 Same as {ip, Address}. If the host has many network inter‐
124 faces, this option specifies which one to use.
125 {fd, integer() >= 0}:
127 If a socket has somehow been opened without using gen_udp,
128 use this option to pass the file descriptor for it. If Port
129 is not set to 0 and/or {ip, ip_address()} is combined with
130 this option, the fd is bound to the specified interface and
131 port after it is being opened. If these options are not
132 specified, it is assumed that the fd is already bound appro‐
133 priately.
134 inet6:
136 Sets up the socket for IPv6.
137 inet:
139 Sets up the socket for IPv4.
140 local:
142 Sets up a Unix Domain Socket. See inet:local_address()
143 {udp_module, module()}:
145 Overrides which callback module is used. Defaults to
146 inet_udp for IPv4 and inet6_udp for IPv6.
147 {multicast_if, Address}:
149 Sets the local device for a multicast socket.
150 {multicast_loop, true | false}:
152 When true, sent multicast packets are looped back to the lo‐
153 cal sockets.
154 {multicast_ttl, Integer}:
156 Option multicast_ttl changes the time-to-live (TTL) for out‐
157 going multicast datagrams to control the scope of the multi‐
158 casts.
159 Datagrams with a TTL of 1 are not forwarded beyond the local
161 network. Defaults to 1.
162 {add_membership, {MultiAddress, InterfaceAddress}}:
164 Joins a multicast group.
165 {drop_membership, {MultiAddress, InterfaceAddress}}:
167 Leaves a multicast group.
168 Opt:
170 See inet:setopts/2.
171 The returned socket Socket is used to send packets from this
173 port with send/4. When UDP packets arrive at the opened port, if
174 the socket is in an active mode, the packets are delivered as
175 messages to the controlling process:
176 {udp, Socket, IP, InPortNo, Packet} % Without ancillary data
178 {udp, Socket, IP, InPortNo, AncData, Packet} % With ancillary data
179 The message contains an AncData field if any of the socket op‐
182 tions recvtos, recvtclass or recvttl are active, otherwise it
183 does not.
184 If the socket is not in an active mode, data can be retrieved
186 through the recv/2,3 calls. Notice that arriving UDP packets
187 that are longer than the receive buffer option specifies can be
188 truncated without warning.
189 When a socket in {active, N} mode (see inet:setopts/2 for de‐
191 tails), transitions to passive ({active, false}) mode, the con‐
192 trolling process is notified by a message of the following form:
193 {udp_passive, Socket}
195 IP and InPortNo define the address from which Packet comes.
197 Packet is a list of bytes if option list is specified. Packet is
198 a binary if option binary is specified.
199 Default value for the receive buffer option is {recbuf, 8192}.
201 If Port == 0, the underlying OS assigns a free UDP port, use
203 inet:port/1 to retrieve it.
204 recv(Socket, Length) -> {ok, RecvData} | {error, Reason}
206 recv(Socket, Length, Timeout) -> {ok, RecvData} | {error, Reason}
208 Types:
210 Socket = socket()
212 Length = integer() >= 0
213 Timeout = timeout()
214 RecvData =
215 {Address, Port, Packet} | {Address, Port, AncData,
216 Packet}
217 Address = inet:ip_address() | inet:returned_non_ip_address()
218 Port = inet:port_number()
219 AncData = inet:ancillary_data()
220 Packet = string() | binary()
221 Reason = not_owner | timeout | inet:posix()
222 Receives a packet from a socket in passive mode. Optional param‐
224 eter Timeout specifies a time-out in milliseconds. Defaults to
225 infinity.
226 If any of the socket options recvtos, recvtclass or recvttl are
228 active, the RecvData tuple contains an AncData field, otherwise
229 it does not.
230 send(Socket, Destination, Packet) -> ok | {error, Reason}
232 Types:
234 Socket = socket()
236 Destination =
237 {inet:ip_address(), inet:port_number()} |
238 inet:family_address()
239 Packet = iodata()
240 Reason = not_owner | inet:posix()
241 Sends a packet to the specified Destination.
243 This function is equivalent to send(Socket, Destination, [],
245 Packet).
246 send(Socket, Host, Port, Packet) -> ok | {error, Reason}
248 Types:
250 Socket = socket()
252 Host = inet:hostname() | inet:ip_address()
253 Port = inet:port_number() | atom()
254 Packet = iodata()
255 Reason = not_owner | inet:posix()
256 Sends a packet to the specified Host and Port.
258 This clause is equivalent to send(Socket, Host, Port, [],
260 Packet).
261 send(Socket, Destination, AncData, Packet) -> ok | {error, Reason}
263 Types:
265 Socket = socket()
267 Destination =
268 {inet:ip_address(), inet:port_number()} |
269 inet:family_address()
270 AncData = inet:ancillary_data()
271 Packet = iodata()
272 Reason = not_owner | inet:posix()
273 Sends a packet to the specified Destination with ancillary data
275 AncData.
276 Note:
278 The ancillary data AncData contains options that for this single
279 message override the default options for the socket, an opera‐
280 tion that may not be supported on all platforms, and if so re‐
281 turn {error, einval}. Using more than one of an ancillary data
282 item type may also not be supported. AncData =:= [] is always
283 supported.
284 send(Socket, Destination, PortZero, Packet) ->
287 ok | {error, Reason}
288 Types:
290 Socket = socket()
292 Destination =
293 {inet:ip_address(), inet:port_number()} |
294 inet:family_address()
295 PortZero = inet:port_number()
296 Packet = iodata()
297 Reason = not_owner | inet:posix()
298 Sends a packet to the specified Destination. Since Destination
300 is complete, PortZero is redundant and has to be 0.
301 This is a legacy clause mostly for Destination = {local, Binary}
303 where PortZero is superfluous. It is equivalent to send(Socket,
304 Destination, [], Packet), the clause right above here.
305 send(Socket, Host, Port, AncData, Packet) -> ok | {error, Reason}
307 Types:
309 Socket = socket()
311 Host =
312 inet:hostname() | inet:ip_address() | inet:local_ad‐
313 dress()
314 Port = inet:port_number() | atom()
315 AncData = inet:ancillary_data()
316 Packet = iodata()
317 Reason = not_owner | inet:posix()
318 Sends a packet to the specified Host and Port, with ancillary
320 data AncData.
321 Argument Host can be a hostname or a socket address, and Port
323 can be a port number or a service name atom. These are resolved
324 into a Destination and after that this function is equivalent to
325 send(Socket, Destination, AncData, Packet), read there about an‐
326 cillary data.
327Ericsson AB kernel 7.3.1.1 gen_udp(3)