1ssh_sftp(3) Erlang Module Definition ssh_sftp(3)
2
6 ssh_sftp - SFTP client.
7
9 This module implements an SSH FTP (SFTP) client. SFTP is a secure,
10 encrypted file transfer service available for SSH.
11
13 Type definitions that are used more than once in this module, or
14 abstractions to indicate the intended use of the data type, or both:
15 reason():
17 = atom() | string() | tuple() A description of the reason why an
18 operation failed.
19 The atom() value is formed from the sftp error codes in the proto‐
21 col-level responses as defined in draft-ietf-secsh-filexfer-13.txt
22 section 9.1.
23 The codes are named as SSH_FX_* which are transformed into lower‐
25 case of the star-part. E.g. the error code SSH_FX_NO_SUCH_FILE will
26 cause the reason() to be no_such_file.
27 The string() reason is the error information from the server in
29 case of an exit-signal. If that information is empty, the reason is
30 the exit signal name.
31 The tuple() reason are other errors like the {exit_status,inte‐
33 ger()} if the exit status is not 0.
34 ssh_connection_ref() =:
36 opaque() - as returned by ssh:connect/3
37 timeout():
39 = infinity | integer() in milliseconds. Default infinity.
40
42 If the request functions for the SFTP channel return {error, timeout},
43 no answer was received from the server within the expected time.
44 The request may have reached the server and may have been performed.
46 However, no answer was received from the server within the expected
47 time.
48
50 apread(ChannelPid, Handle, Position, Len) -> {async, N} | {error, rea‐
51 son()}
52 Types:
54 ChannelPid = pid()
56 Handle = term()
57 Position = integer()
58 Len = integer()
59 N = term()
60 The apread/4 function reads from a specified position, combining
62 the position/3 and aread/3 functions.
63 apwrite(ChannelPid, Handle, Position, Data) -> {async, N} | {error,
65 reason()}
66 Types:
68 ChannelPid = pid()
70 Handle = term()
71 Position = integer()
72 Len = integer()
73 Data = binary()
74 Timeout = timeout()
75 N = term()
76 The apwrite/4 function writes to a specified position, combining
78 the position/3 and awrite/3 functions.
79 aread(ChannelPid, Handle, Len) -> {async, N} | {error, reason()}
81 Types:
83 ChannelPid = pid()
85 Handle = term()
86 Position = integer()
87 Len = integer()
88 N = term()
89 Reads from an open file, without waiting for the result. If the
91 handle is valid, the function returns {async, N}, where N is a
92 term guaranteed to be unique between calls of aread. The actual
93 data is sent as a message to the calling process. This message
94 has the form {async_reply, N, Result}, where Result is the
95 result from the read, either {ok, Data}, eof, or {error, rea‐
96 son()}.
97 awrite(ChannelPid, Handle, Data) -> {async, N} | {error, reason()}
99 Types:
101 ChannelPid = pid()
103 Handle = term()
104 Position = integer()
105 Len = integer()
106 Data = binary()
107 Timeout = timeout()
108 Writes to an open file, without waiting for the result. If the
110 handle is valid, the function returns {async, N}, where N is a
111 term guaranteed to be unique between calls of awrite. The result
112 of the write operation is sent as a message to the calling
113 process. This message has the form {async_reply, N, Result},
114 where Result is the result from the write, either ok, or {error,
115 reason()}.
116 close(ChannelPid, Handle) ->
118 close(ChannelPid, Handle, Timeout) -> ok | {error, reason()}
119 Types:
121 ChannelPid = pid()
123 Handle = term()
124 Timeout = timeout()
125 Closes a handle to an open file or directory on the server.
127 delete(ChannelPid, Name) ->
129 delete(ChannelPid, Name, Timeout) -> ok | {error, reason()}
130 Types:
132 ChannelPid = pid()
134 Name = string()
135 Timeout = timeout()
136 Deletes the file specified by Name.
138 del_dir(ChannelPid, Name) ->
140 del_dir(ChannelPid, Name, Timeout) -> ok | {error, reason()}
141 Types:
143 ChannelPid = pid()
145 Name = string()
146 Timeout = timeout()
147 Deletes a directory specified by Name. The directory must be
149 empty before it can be successfully deleted.
150 list_dir(ChannelPid, Path) ->
152 list_dir(ChannelPid, Path, Timeout) -> {ok, Filenames} | {error, rea‐
153 son()}
154 Types:
156 ChannelPid = pid()
158 Path = string()
159 Filenames = [Filename]
160 Filename = string()
161 Timeout = timeout()
162 Lists the given directory on the server, returning the filenames
164 as a list of strings.
165 make_dir(ChannelPid, Name) ->
167 make_dir(ChannelPid, Name, Timeout) -> ok | {error, reason()}
168 Types:
170 ChannelPid = pid()
172 Name = string()
173 Timeout = timeout()
174 Creates a directory specified by Name. Name must be a full path
176 to a new directory. The directory can only be created in an
177 existing directory.
178 make_symlink(ChannelPid, Name, Target) ->
180 make_symlink(ChannelPid, Name, Target, Timeout) -> ok | {error, rea‐
181 son()}
182 Types:
184 ChannelPid = pid()
186 Name = string()
187 Target = string()
188 Creates a symbolic link pointing to Target with the name Name.
190 open(ChannelPid, File, Mode) ->
192 open(ChannelPid, File, Mode, Timeout) -> {ok, Handle} | {error, rea‐
193 son()}
194 Types:
196 ChannelPid = pid()
198 File = string()
199 Mode = [Modeflag]
200 Modeflag = read | write | creat | trunc | append | binary
201 Timeout = timeout()
202 Handle = term()
203 Opens a file on the server and returns a handle, which can be
205 used for reading or writing.
206 opendir(ChannelPid, Path) ->
208 opendir(ChannelPid, Path, Timeout) -> {ok, Handle} | {error, reason()}
209 Types:
211 ChannelPid = pid()
213 Path = string()
214 Timeout = timeout()
215 Opens a handle to a directory on the server. The handle can be
217 used for reading directory contents.
218 open_tar(ChannelPid, Path, Mode) ->
220 open_tar(ChannelPid, Path, Mode, Timeout) -> {ok, Handle} | {error,
221 reason()}
222 Types:
224 ChannelPid = pid()
226 Path = string()
227 Mode = [read] | [write] | [read,EncryptOpt] | [write,Decryp‐
228 tOpt]
229 EncryptOpt = {crypto,{InitFun,EncryptFun,CloseFun}}
230 DecryptOpt = {crypto,{InitFun,DecryptFun}}
231 InitFun = (fun() -> {ok,CryptoState}) | (fun() -> {ok,Cryp‐
232 toState,ChunkSize})
233 CryptoState = any()
234 ChunkSize = undefined | pos_integer()
235 EncryptFun = (fun(PlainBin,CryptoState) -> EncryptResult)
236 EncryptResult = {ok,EncryptedBin,CryptoState} | {ok,Encrypt‐
237 edBin,CryptoState,ChunkSize}
238 PlainBin = binary()
239 EncryptedBin = binary()
240 DecryptFun = (fun(EncryptedBin,CryptoState) -> DecryptResult)
241 DecryptResult = {ok,PlainBin,CryptoState} | {ok,Plain‐
242 Bin,CryptoState,ChunkSize}
243 CloseFun = (fun(PlainBin,CryptoState) -> {ok,EncryptedBin})
244 Timeout = timeout()
245 Opens a handle to a tar file on the server, associated with
247 ChannelPid. The handle can be used for remote tar creation and
248 extraction, as defined by the erl_tar:init/3 function.
249 For code exampel see Section SFTP Client with TAR Compression
251 and Encryption in the ssh Users Guide.
252 The crypto mode option is applied to the generated stream of
254 bytes prior to sending them to the SFTP server. This is intended
255 for encryption but can be used for other purposes.
256 The InitFun is applied once prior to any other crypto operation.
258 The returned CryptoState is then folded into repeated applica‐
259 tions of the EncryptFun or DecryptFun. The binary returned from
260 those funs are sent further to the remote SFTP server. Finally,
261 if doing encryption, the CloseFun is applied to the last piece
262 of data. The CloseFun is responsible for padding (if needed) and
263 encryption of that last piece.
264 The ChunkSize defines the size of the PlainBins that EncodeFun
266 is applied to. If the ChunkSize is undefined, the size of the
267 PlainBins varies, because this is intended for stream crypto,
268 whereas a fixed ChunkSize is intended for block crypto. Chunk‐
269 Sizes can be changed in the return from the EncryptFun or
270 DecryptFun. The value can be changed between pos_integer() and
271 undefined.
272 position(ChannelPid, Handle, Location) ->
274 position(ChannelPid, Handle, Location, Timeout) -> {ok, NewPosition |
275 {error, reason()}
276 Types:
278 ChannelPid = pid()
280 Handle = term()
281 Location = Offset | {bof, Offset} | {cur, Offset} | {eof,
282 Offset} | bof | cur | eof
283 Offset = integer()
284 Timeout = timeout()
285 NewPosition = integer()
286 Sets the file position of the file referenced by Handle. Returns
288 {ok, NewPosition} (as an absolute offset) if successful, other‐
289 wise {error, reason()}. Location is one of the following:
290 Offset:
292 The same as {bof, Offset}.
293 {bof, Offset}:
295 Absolute offset.
296 {cur, Offset}:
298 Offset from the current position.
299 {eof, Offset}:
301 Offset from the end of file.
302 bof | cur | eof:
304 The same as eariler with Offset 0, that is, {bof, 0} | {cur,
305 0} | {eof, 0}.
306 pread(ChannelPid, Handle, Position, Len) ->
308 pread(ChannelPid, Handle, Position, Len, Timeout) -> {ok, Data} | eof |
309 {error, reason()}
310 Types:
312 ChannelPid = pid()
314 Handle = term()
315 Position = integer()
316 Len = integer()
317 Timeout = timeout()
318 Data = string() | binary()
319 The pread/3,4 function reads from a specified position, combin‐
321 ing the position/3 and read/3,4 functions.
322 pwrite(ChannelPid, Handle, Position, Data) -> ok
324 pwrite(ChannelPid, Handle, Position, Data, Timeout) -> ok | {error,
325 reason()}
326 Types:
328 ChannelPid = pid()
330 Handle = term()
331 Position = integer()
332 Data = iolist()
333 Timeout = timeout()
334 The pwrite/3,4 function writes to a specified position, combin‐
336 ing the position/3 and write/3,4 functions.
337 read(ChannelPid, Handle, Len) ->
339 read(ChannelPid, Handle, Len, Timeout) -> {ok, Data} | eof | {error,
340 reason()}
341 Types:
343 ChannelPid = pid()
345 Handle = term()
346 Position = integer()
347 Len = integer()
348 Timeout = timeout()
349 Data = string() | binary()
350 Reads Len bytes from the file referenced by Handle. Returns {ok,
352 Data}, eof, or {error, reason()}. If the file is opened with
353 binary, Data is a binary, otherwise it is a string.
354 If the file is read past eof, only the remaining bytes are read
356 and returned. If no bytes are read, eof is returned.
357 read_file(ChannelPid, File) ->
359 read_file(ChannelPid, File, Timeout) -> {ok, Data} | {error, reason()}
360 Types:
362 ChannelPid = pid()
364 File = string()
365 Data = binary()
366 Timeout = timeout()
367 Reads a file from the server, and returns the data in a binary.
369 read_file_info(ChannelPid, Name) ->
371 read_file_info(ChannelPid, Name, Timeout) -> {ok, FileInfo} | {error,
372 reason()}
373 Types:
375 ChannelPid = pid()
377 Name = string()
378 Handle = term()
379 Timeout = timeout()
380 FileInfo = record()
381 Returns a file_info record from the file system object specified
383 by Name or Handle. See file:read_file_info/2 for information
384 about the record.
385 Depending on the underlying OS:es links might be followed and
387 info on the final file, directory etc is returned. See
388 ssh_sftp::read_link_info/2 on how to get information on links
389 instead.
390 read_link(ChannelPid, Name) ->
392 read_link(ChannelPid, Name, Timeout) -> {ok, Target} | {error, rea‐
393 son()}
394 Types:
396 ChannelPid = pid()
398 Name = string()
399 Target = string()
400 Reads the link target from the symbolic link specified by name.
402 read_link_info(ChannelPid, Name) -> {ok, FileInfo} | {error, reason()}
404 read_link_info(ChannelPid, Name, Timeout) -> {ok, FileInfo} | {error,
405 reason()}
406 Types:
408 ChannelPid = pid()
410 Name = string()
411 Handle = term()
412 Timeout = timeout()
413 FileInfo = record()
414 Returns a file_info record from the symbolic link specified by
416 Name or Handle. See file:read_link_info/2 for information about
417 the record.
418 rename(ChannelPid, OldName, NewName) ->
420 rename(ChannelPid, OldName, NewName, Timeout) -> ok | {error, reason()}
421 Types:
423 ChannelPid = pid()
425 OldName = string()
426 NewName = string()
427 Timeout = timeout()
428 Renames a file named OldName and gives it the name NewName.
430 start_channel(ConnectionRef) ->
432 start_channel(ConnectionRef, Options) -> {ok, Pid} | {error, rea‐
433 son()|term()}
434 start_channel(Host, Options) ->
435 start_channel(Host, Port, Options) -> {ok, Pid, ConnectionRef} |
436 {error, reason()|term()}
437 start_channel(TcpSocket) ->
438 start_channel(TcpSocket, Options) -> {ok, Pid, ConnectionRef} | {error,
439 reason()|term()}
440 Types:
442 Host = string()
444 ConnectionRef = ssh_connection_ref()
445 Port = integer()
446 TcpSocket = port()
447 The socket is supposed to be from gen_tcp:connect or
448 gen_tcp:accept with option {active,false}
449 Options = [{Option, Value}]
450 If no connection reference is provided, a connection is set up,
452 and the new connection is returned. An SSH channel process is
453 started to handle the communication with the SFTP server. The
454 returned pid for this process is to be used as input to all
455 other API functions in this module.
456 Options:
458 {timeout, timeout()}:
460 There are two ways to set a timeout for the underlying ssh
461 connection:
462 * If the connection timeout option connect_timeout is set,
464 that value is used also for the negotiation timeout and
465 this option (timeout) is ignored.
466 * Otherwise, this option (timeout) is used as the negotia‐
468 tion timeout only and there is no connection timeout set
469 The value defaults to infinity.
471 {sftp_vsn, integer()}:
473 Desired SFTP protocol version. The actual version is the
474 minimum of the desired version and the maximum supported
475 versions by the SFTP server.
476 All other options are directly passed to ssh:connect/3 or
478 ignored if a connection is already provided.
479 stop_channel(ChannelPid) -> ok
481 Types:
483 ChannelPid = pid()
485 Stops an SFTP channel. Does not close the SSH connection. Use
487 ssh:close/1 to close it.
488 write(ChannelPid, Handle, Data) ->
490 write(ChannelPid, Handle, Data, Timeout) -> ok | {error, reason()}
491 Types:
493 ChannelPid = pid()
495 Handle = term()
496 Position = integer()
497 Data = iolist()
498 Timeout = timeout()
499 Writes data to the file referenced by Handle. The file is to be
501 opened with write or append flag. Returns ok if successful or
502 {error, reason()} otherwise.
503 write_file(ChannelPid, File, Iolist) ->
505 write_file(ChannelPid, File, Iolist, Timeout) -> ok | {error, reason()}
506 Types:
508 ChannelPid = pid()
510 File = string()
511 Iolist = iolist()
512 Timeout = timeout()
513 Writes a file to the server. The file is created if it does not
515 exist but overwritten if it exists.
516 write_file_info(ChannelPid, Name, Info) ->
518 write_file_info(ChannelPid, Name, Info, Timeout) -> ok | {error, rea‐
519 son()}
520 Types:
522 ChannelPid = pid()
524 Name = string()
525 Info = record()
526 Timeout = timeout()
527 Writes file information from a file_info record to the file
529 specified by Name. See file:write_file_info/[2,3] for informa‐
530 tion about the record.
531Ericsson AB ssh 4.6.9.4 ssh_sftp(3)