1gen_udp(3) Erlang Module Definition gen_udp(3)
2
3
4
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 |
26 binary |
27 {multicast_if, inet:ip_address()} |
28 {multicast_loop, boolean()} |
29 {multicast_ttl, integer() >= 0} |
30 {priority, integer() >= 0} |
31 {raw,
32 Protocol :: integer() >= 0,
33 OptionNum :: integer() >= 0,
34 ValueBin :: binary()} |
35 {read_packets, integer() >= 0} |
36 {recbuf, integer() >= 0} |
37 {reuseaddr, boolean()} |
38 {sndbuf, integer() >= 0} |
39 {tos, integer() >= 0} |
40 {tclass, integer() >= 0} |
41 {ttl, integer() >= 0} |
42 {recvtos, boolean()} |
43 {recvtclass, boolean()} |
44 {recvttl, boolean()} |
45 {ipv6_v6only, boolean()}
46
47 option_name() =
48 active |
49 broadcast |
50 buffer |
51 deliver |
52 dontroute |
53 header |
54 high_msgq_watermark |
55 low_msgq_watermark |
56 mode |
57 multicast_if |
58 multicast_loop |
59 multicast_ttl |
60 priority |
61 {raw,
62 Protocol :: integer() >= 0,
63 OptionNum :: integer() >= 0,
64 ValueSpec ::
65 (ValueSize :: integer() >= 0) | (ValueBin :: binary())} |
66 read_packets |
67 recbuf |
68 reuseaddr |
69 sndbuf |
70 tos |
71 tclass |
72 ttl |
73 recvtos |
74 recvtclass |
75 recvttl |
76 pktoptions |
77 ipv6_v6only
78
79 socket()
80
81 As returned by open/1,2.
82
84 close(Socket) -> ok
85
86 Types:
87
88 Socket = socket()
89
90 Closes a UDP socket.
91
92 controlling_process(Socket, Pid) -> ok | {error, Reason}
93
94 Types:
95
96 Socket = socket()
97 Pid = pid()
98 Reason = closed | not_owner | badarg | inet:posix()
99
100 Assigns a new controlling process Pid to Socket. The controlling
101 process is the process that receives messages from the socket.
102 If called by any other process than the current controlling
103 process, {error, not_owner} is returned. If the process identi‐
104 fied by Pid is not an existing local pid, {error, badarg} is
105 returned. {error, badarg} may also be returned in some cases
106 when Socket is closed during the execution of this function.
107
108 open(Port) -> {ok, Socket} | {error, Reason}
109
110 open(Port, Opts) -> {ok, Socket} | {error, Reason}
111
112 Types:
113
114 Port = inet:port_number()
115 Opts = [Option]
116 Option =
117 {ip, inet:socket_address()} |
118 {fd, integer() >= 0} |
119 {ifaddr, inet:socket_address()} |
120 inet:address_family() |
121 {port, inet:port_number()} |
122 {netns, file:filename_all()} |
123 {bind_to_device, binary()} |
124 option()
125 Socket = socket()
126 Reason = inet:posix()
127
128 Associates a UDP port number (Port) with the calling process.
129
130 The following options are available:
131
132 list:
133 Received Packet is delivered as a list.
134
135 binary:
136 Received Packet is delivered as a binary.
137
138 {ip, Address}:
139 If the host has many network interfaces, this option speci‐
140 fies which one to use.
141
142 {ifaddr, Address}:
143 Same as {ip, Address}. If the host has many network inter‐
144 faces, this option specifies which one to use.
145
146 {fd, integer() >= 0}:
147 If a socket has somehow been opened without using gen_udp,
148 use this option to pass the file descriptor for it. If Port
149 is not set to 0 and/or {ip, ip_address()} is combined with
150 this option, the fd is bound to the specified interface and
151 port after it is being opened. If these options are not
152 specified, it is assumed that the fd is already bound appro‐
153 priately.
154
155 inet6:
156 Sets up the socket for IPv6.
157
158 inet:
159 Sets up the socket for IPv4.
160
161 local:
162 Sets up a Unix Domain Socket. See inet:local_address()
163
164 {udp_module, module()}:
165 Overrides which callback module is used. Defaults to
166 inet_udp for IPv4 and inet6_udp for IPv6.
167
168 {multicast_if, Address}:
169 Sets the local device for a multicast socket.
170
171 {multicast_loop, true | false}:
172 When true, sent multicast packets are looped back to the
173 local sockets.
174
175 {multicast_ttl, Integer}:
176 Option multicast_ttl changes the time-to-live (TTL) for out‐
177 going multicast datagrams to control the scope of the multi‐
178 casts.
179
180 Datagrams with a TTL of 1 are not forwarded beyond the local
181 network. Defaults to 1.
182
183 {add_membership, {MultiAddress, InterfaceAddress}}:
184 Joins a multicast group.
185
186 {drop_membership, {MultiAddress, InterfaceAddress}}:
187 Leaves a multicast group.
188
189 Opt:
190 See inet:setopts/2.
191
192 The returned socket Socket is used to send packets from this
193 port with send/4. When UDP packets arrive at the opened port, if
194 the socket is in an active mode, the packets are delivered as
195 messages to the controlling process:
196
197 {udp, Socket, IP, InPortNo, Packet} % Without ancillary data
198 {udp, Socket, IP, InPortNo, AncData, Packet} % With ancillary data
199
200
201 The message contains an AncData field if any of the socket
202 options recvtos, recvtclass or recvttl are active, otherwise it
203 does not.
204
205 If the socket is not in an active mode, data can be retrieved
206 through the recv/2,3 calls. Notice that arriving UDP packets
207 that are longer than the receive buffer option specifies can be
208 truncated without warning.
209
210 When a socket in {active, N} mode (see inet:setopts/2 for
211 details), transitions to passive ({active, false}) mode, the
212 controlling process is notified by a message of the following
213 form:
214
215 {udp_passive, Socket}
216
217 IP and InPortNo define the address from which Packet comes.
218 Packet is a list of bytes if option list is specified. Packet is
219 a binary if option binary is specified.
220
221 Default value for the receive buffer option is {recbuf, 8192}.
222
223 If Port == 0, the underlying OS assigns a free UDP port, use
224 inet:port/1 to retrieve it.
225
226 recv(Socket, Length) -> {ok, RecvData} | {error, Reason}
227
228 recv(Socket, Length, Timeout) -> {ok, RecvData} | {error, Reason}
229
230 Types:
231
232 Socket = socket()
233 Length = integer() >= 0
234 Timeout = timeout()
235 RecvData =
236 {Address, Port, Packet} | {Address, Port, AncData,
237 Packet}
238 Address = inet:ip_address() | inet:returned_non_ip_address()
239 Port = inet:port_number()
240 AncData = inet:ancillary_data()
241 Packet = string() | binary()
242 Reason = not_owner | inet:posix()
243
244 Receives a packet from a socket in passive mode. Optional param‐
245 eter Timeout specifies a time-out in milliseconds. Defaults to
246 infinity.
247
248 If any of the socket options recvtos, recvtclass or recvttl are
249 active, the RecvData tuple contains an AncData field, otherwise
250 it does not.
251
252 send(Socket, Address, Port, Packet) -> ok | {error, Reason}
253
254 Types:
255
256 Socket = socket()
257 Address = inet:socket_address() | inet:hostname()
258 Port = inet:port_number()
259 Packet = iodata()
260 Reason = not_owner | inet:posix()
261
262 Sends a packet to the specified address and port. Argument
263 Address can be a hostname or a socket address.
264
265
266
267Ericsson AB kernel 6.3.1.1 gen_udp(3)