1tftp(3) Erlang Module Definition tftp(3)
2
6 tftp - Trivial FTP.
7
9 Interface module for the tftp application.
10
12 ServiceConfig = Options
13 Options = [option()]
15 Most of the options are common for both the client and the server side,
17 but some of them differs a little. The available option()s are as fol‐
18 lows:
19 {debug, Level}:
21 Level = none | error | warning | brief | normal | verbose | all
22 Controls the level of debug printouts. Default is none.
24 {host, Host}:
26 Host = hostname(), see inet(3).
27 The name or IP address of the host where the TFTP daemon resides.
29 This option is only used by the client.
30 {port, Port}:
32 Port = int()
33 The TFTP port where the daemon listens. Defaults is the standard‐
35 ized number 69. On the server side, it can sometimes make sense to
36 set it to 0, meaning that the daemon just picks a free port (which
37 one is returned by function info/1).
38 If a socket is connected already, option {udp, [{fd, integer()}]}
40 can be used to pass the open file descriptor to gen_udp. This can
41 be automated by using a command-line argument stating the prebound
42 file descriptor number. For example, if the port is 69 and file
43 descriptor 22 is opened by setuid_socket_wrap, the command-line
44 argument "-tftpd_69 22" triggers the prebound file descriptor 22 to
45 be used instead of opening port 69. The UDP option {udp, [{fd,
46 22}]} is automatically added. See init:get_argument/ about command-
47 line arguments and gen_udp:open/2 about UDP options.
48 {port_policy, Policy}:
50 Policy = random | Port | {range, MinPort, MaxPort}
51 Port = MinPort = MaxPort = int()
53 Policy for the selection of the temporary port that is used by the
55 server/client during the file transfer. Default is random, which is
56 the standardized policy. With this policy a randomized free port is
57 used. A single port or a range of ports can be useful if the proto‐
58 col passes through a firewall.
59 {udp, Options}:
61 Options = [Opt], see gen_udp:open/2.
62 {use_tsize, Bool}:
64 Bool = bool()
65 Flag for automated use of option tsize. With this set to true, the
67 write_file/3 client determines the filesize and sends it to the
68 server as the standardized tsize option. A read_file/3 client
69 acquires only a filesize from the server by sending a zero tsize.
70 {max_tsize, MaxTsize}:
72 MaxTsize = int() | infinity
73 Threshold for the maximal filesize in bytes. The transfer is
75 aborted if the limit is exceeded. Default is infinity.
76 {max_conn, MaxConn}:
78 MaxConn = int() | infinity
79 Threshold for the maximal number of active connections. The daemon
81 rejects the setup of new connections if the limit is exceeded.
82 Default is infinity.
83 {TftpKey, TftpVal}:
85 TftpKey = string()
86 TftpVal = string()
87 Name and value of a TFTP option.
89 {reject, Feature}:
91 Feature = Mode | TftpKey
92 Mode = read | write
93 TftpKey = string()
94 Controls which features to reject. This is mostly useful for the
96 server as it can restrict the use of certain TFTP options or
97 read/write access.
98 {callback, {RegExp, Module, State}}:
100 RegExp = string()
101 Module = atom()
102 State = term()
103 Registration of a callback module. When a file is to be trans‐
105 ferred, its local filename is matched to the regular expressions of
106 the registered callbacks. The first matching callback is used dur‐
107 ing the transfer. See read_file/3 and write_file/3.
108 The callback module must implement the tftp behavior, see CALLBACK
110 FUNCTIONS.
111 {logger, Module}:
113 Module = module()
114 Callback module for customized logging of errors, warnings, and
116 info messages. The callback module must implement the tftp_logger
117 behavior, see LOGGER FUNCTIONS. The default module is tftp_logger.
118 {max_retries, MaxRetries}:
120 MaxRetries = int()
121 Threshold for the maximal number of retries. By default the
123 server/client tries to resend a message up to five times when the
124 time-out expires.
125
127 change_config(daemons, Options) -> [{Pid, Result}]
128 Types:
130 Options = [option()]
132 Pid = pid()
133 Result = ok | {error, Reason}
134 Reason = term()
135 Changes configuration for all TFTP daemon processes.
137 change_config(servers, Options) -> [{Pid, Result}]
139 Types:
141 Options = [option()]
143 Pid = pid()
144 Result = ok | {error, Reason}
145 Reason = term()
146 Changes configuration for all TFTP server processes.
148 change_config(Pid, Options) -> Result
150 Types:
152 Pid = pid()
154 Options = [option()]
155 Result = ok | {error, Reason}
156 Reason = term()
157 Changes configuration for a TFTP daemon, server, or client
159 process.
160 info(daemons) -> [{Pid, Options}]
162 Types:
164 Pid = [pid()]
166 Options = [option()]
167 Reason = term()
168 Returns information about all TFTP daemon processes.
170 info(servers) -> [{Pid, Options}]
172 Types:
174 Pid = [pid()]
176 Options = [option()]
177 Reason = term()
178 Returns information about all TFTP server processes.
180 info(Pid) -> {ok, Options} | {error, Reason}
182 Types:
184 Options = [option()]
186 Reason = term()
187 Returns information about a TFTP daemon, server, or client
189 process.
190 read_file(RemoteFilename, LocalFilename, Options) -> {ok, LastCallback‐
192 State} | {error, Reason}
193 Types:
195 RemoteFilename = string()
197 LocalFilename = binary | string()
198 Options = [option()]
199 LastCallbackState = term()
200 Reason = term()
201 Reads a (virtual) file RemoteFilename from a TFTP server.
203 If LocalFilename is the atom binary, tftp_binary is used as
205 callback module. It concatenates all transferred blocks and
206 returns them as one single binary in LastCallbackState.
207 If LocalFilename is a string and there are no registered call‐
209 back modules, tftp_file is used as callback module. It writes
210 each transferred block to the file named LocalFilename and
211 returns the number of transferred bytes in LastCallbackState.
212 If LocalFilename is a string and there are registered callback
214 modules, LocalFilename is tested against the regexps of these
215 and the callback module corresponding to the first match is
216 used, or an error tuple is returned if no matching regexp is
217 found.
218 start(Options) -> {ok, Pid} | {error, Reason}
220 Types:
222 Options = [option()]
224 Pid = pid()
225 Reason = term()
226 Starts a daemon process listening for UDP packets on a port.
228 When it receives a request for read or write, it spawns a tempo‐
229 rary server process handling the actual transfer of the (vir‐
230 tual) file.
231 write_file(RemoteFilename, LocalFilename, Options) -> {ok, LastCall‐
233 backState} | {error, Reason}
234 Types:
236 RemoteFilename = string()
238 LocalFilename = binary() | string()
239 Options = [option()]
240 LastCallbackState = term()
241 Reason = term()
242 Writes a (virtual) file RemoteFilename to a TFTP server.
244 If LocalFilename is a binary, tftp_binary is used as callback
246 module. The binary is transferred block by block and the number
247 of transferred bytes is returned in LastCallbackState.
248 If LocalFilename is a string and there are no registered call‐
250 back modules, tftp_file is used as callback module. It reads the
251 file named LocalFilename block by block and returns the number
252 of transferred bytes in LastCallbackState.
253 If LocalFilename is a string and there are registered callback
255 modules, LocalFilename is tested against the regexps of these
256 and the callback module corresponding to the first match is
257 used, or an error tuple is returned if no matching regexp is
258 found.
259
261 A tftp callback module is to be implemented as a tftp behavior and
262 export the functions listed in the following.
263 On the server side, the callback interaction starts with a call to
265 open/5 with the registered initial callback state. open/5 is expected
266 to open the (virtual) file. Then either function read/1 or write/2 is
267 invoked repeatedly, once per transferred block. At each function call,
268 the state returned from the previous call is obtained. When the last
269 block is encountered, function read/1 or write/2 is expected to close
270 the (virtual) file and return its last state. Function abort/3 is only
271 used in error situations. Function prepare/5 is not used on the server
272 side.
273 On the client side, the callback interaction is the same, but it starts
275 and ends a bit differently. It starts with a call to prepare/5 with the
276 same arguments as open/5 takes. prepare/5 is expected to validate the
277 TFTP options suggested by the user and to return the subset of them
278 that it accepts. Then the options are sent to the server, which per‐
279 forms the same TFTP option negotiation procedure. The options that are
280 accepted by the server are forwarded to function open/5 on the client
281 side. On the client side, function open/5 must accept all option as-is
282 or reject the transfer. Then the callback interaction follows the same
283 pattern as described for the server side. When the last block is
284 encountered in read/1 or write/2, the returned state is forwarded to
285 the user and returned from read_file/3 or write_file/3.
286 If a callback (performing the file access in the TFTP server) takes too
288 long time (more than the double TFTP time-out), the server aborts the
289 connection and sends an error reply to the client. This implies that
290 the server releases resources attached to the connection faster than
291 before. The server simply assumes that the client has given up.
292 If the TFTP server receives yet another request from the same client
294 (same host and port) while it already has an active connection to the
295 client, it ignores the new request if the request is equal to the first
296 one (same filename and options). This implies that the (new) client
297 will be served by the already ongoing connection on the server side. By
298 not setting up yet another connection, in parallel with the ongoing
299 one, the server consumes less resources.
300
302 Module:abort(Code, Text, State) -> ok
303 Types:
305 Code = undef | enoent | eacces | enospc
307 | badop | eexist | baduser | badopt
308 | int()
309 Text = string()
310 State = term()
311 Invoked when the file transfer is aborted.
313 The callback function is expected to clean up its used resources
315 after the aborted file transfer, such as closing open file
316 descriptors and so on. The function is not invoked if any of the
317 other callback functions returns an error, as it is expected
318 that they already have cleaned up the necessary resources. How‐
319 ever, it is invoked if the functions fail (crash).
320 Module:open(Peer, Access, Filename, Mode, SuggestedOptions, State) ->
322 {ok, AcceptedOptions, NewState} | {error, {Code, Text}}
323 Types:
325 Peer = {PeerType, PeerHost, PeerPort}
327 PeerType = inet | inet6
328 PeerHost = ip_address()
329 PeerPort = integer()
330 Access = read | write
331 Filename = string()
332 Mode = string()
333 SuggestedOptions = AcceptedOptions = [{Key, Value}]
334 Key = Value = string()
335 State = InitialState | term()
336 InitialState = [] | [{root_dir, string()}]
337 NewState = term()
338 Code = undef | enoent | eacces | enospc
339 | badop | eexist | baduser | badopt
340 | int()
341 Text = string()
342 Opens a file for read or write access.
344 On the client side, where the open/5 call has been preceded by a
346 call to prepare/5, all options must be accepted or rejected.
347 On the server side, where there is no preceding prepare/5 call,
349 no new options can be added, but those present in SuggestedOp‐
350 tions can be omitted or replaced with new values in AcceptedOp‐
351 tions.
352 Module:prepare(Peer, Access, Filename, Mode, SuggestedOptions, Initial‐
354 State) -> {ok, AcceptedOptions, NewState} | {error, {Code, Text}}
355 Types:
357 Peer = {PeerType, PeerHost, PeerPort}
359 PeerType = inet | inet6
360 PeerHost = ip_address()
361 PeerPort = integer()
362 Access = read | write
363 Filename = string()
364 Mode = string()
365 SuggestedOptions = AcceptedOptions = [{Key, Value}]
366 Key = Value = string()
367 InitialState = [] | [{root_dir, string()}]
368 NewState = term()
369 Code = undef | enoent | eacces | enospc
370 | badop | eexist | baduser | badopt
371 | int()
372 Text = string()
373 Prepares to open a file on the client side.
375 No new options can be added, but those present in SuggestedOp‐
377 tions can be omitted or replaced with new values in AcceptedOp‐
378 tions.
379 This is followed by a call to open/4 before any read/write
381 access is performed. AcceptedOptions is sent to the server,
382 which replies with the options that it accepts. These are then
383 forwarded to open/4 as SuggestedOptions.
384 Module:read(State) -> {more, Bin, NewState} | {last, Bin, FileSize} |
386 {error, {Code, Text}}
387 Types:
389 State = NewState = term()
391 Bin = binary()
392 FileSize = int()
393 Code = undef | enoent | eacces | enospc
394 | badop | eexist | baduser | badopt
395 | int()
396 Text = string()
397 Reads a chunk from the file.
399 The callback function is expected to close the file when the
401 last file chunk is encountered. When an error is encountered,
402 the callback function is expected to clean up after the aborted
403 file transfer, such as closing open file descriptors, and so on.
404 In both cases there will be no more calls to any of the callback
405 functions.
406 Module:write(Bin, State) -> {more, NewState} | {last, FileSize} |
408 {error, {Code, Text}}
409 Types:
411 Bin = binary()
413 State = NewState = term()
414 FileSize = int()
415 Code = undef | enoent | eacces | enospc
416 | badop | eexist | baduser | badopt
417 | int()
418 Text = string()
419 Writes a chunk to the file.
421 The callback function is expected to close the file when the
423 last file chunk is encountered. When an error is encountered,
424 the callback function is expected to clean up after the aborted
425 file transfer, such as closing open file descriptors, and so on.
426 In both cases there will be no more calls to any of the callback
427 functions.
428
430 A tftp_logger callback module is to be implemented as a tftp_logger
431 behavior and export the following functions:
432
434 Logger:error_msg(Format, Data) -> ok | exit(Reason)
435 Types:
437 Format = string()
439 Data = [term()]
440 Reason = term()
441 Logs an error message. See error_logger:error_msg/2 for details.
443 Logger:info_msg(Format, Data) -> ok | exit(Reason)
445 Types:
447 Format = string()
449 Data = [term()]
450 Reason = term()
451 Logs an info message. See error_logger:info_msg/2 for details.
453 Logger:warning_msg(Format, Data) -> ok | exit(Reason)
455 Types:
457 Format = string()
459 Data = [term()]
460 Reason = term()
461 Logs a warning message. See error_logger:warning_msg/2 for
463 details.
464Ericsson AB tftp 1.0.2 tftp(3)