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 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 Len = integer()
347 Timeout = timeout()
348 Data = string() | binary()
349 Reads Len bytes from the file referenced by Handle. Returns {ok,
351 Data}, eof, or {error, reason()}. If the file is opened with
352 binary, Data is a binary, otherwise it is a string.
353 If the file is read past eof, only the remaining bytes are read
355 and returned. If no bytes are read, eof is returned.
356 read_file(ChannelPid, File) ->
358 read_file(ChannelPid, File, Timeout) -> {ok, Data} | {error, reason()}
359 Types:
361 ChannelPid = pid()
363 File = string()
364 Data = binary()
365 Timeout = timeout()
366 Reads a file from the server, and returns the data in a binary.
368 read_file_info(ChannelPid, Name) ->
370 read_file_info(ChannelPid, Name, Timeout) -> {ok, FileInfo} | {error,
371 reason()}
372 Types:
374 ChannelPid = pid()
376 Name = string()
377 Handle = term()
378 Timeout = timeout()
379 FileInfo = record()
380 Returns a file_info record from the file system object specified
382 by Name or Handle. See file:read_file_info/2 for information
383 about the record.
384 Depending on the underlying OS:es links might be followed and
386 info on the final file, directory etc is returned. See
387 ssh_sftp::read_link_info/2 on how to get information on links
388 instead.
389 read_link(ChannelPid, Name) ->
391 read_link(ChannelPid, Name, Timeout) -> {ok, Target} | {error, rea‐
392 son()}
393 Types:
395 ChannelPid = pid()
397 Name = string()
398 Target = string()
399 Reads the link target from the symbolic link specified by name.
401 read_link_info(ChannelPid, Name) -> {ok, FileInfo} | {error, reason()}
403 read_link_info(ChannelPid, Name, Timeout) -> {ok, FileInfo} | {error,
404 reason()}
405 Types:
407 ChannelPid = pid()
409 Name = string()
410 Handle = term()
411 Timeout = timeout()
412 FileInfo = record()
413 Returns a file_info record from the symbolic link specified by
415 Name or Handle. See file:read_link_info/2 for information about
416 the record.
417 rename(ChannelPid, OldName, NewName) ->
419 rename(ChannelPid, OldName, NewName, Timeout) -> ok | {error, reason()}
420 Types:
422 ChannelPid = pid()
424 OldName = string()
425 NewName = string()
426 Timeout = timeout()
427 Renames a file named OldName and gives it the name NewName.
429 start_channel(ConnectionRef) ->
431 start_channel(ConnectionRef, Options) -> {ok, Pid} | {error, rea‐
432 son()|term()}
433 start_channel(Host, Options) ->
434 start_channel(Host, Port, Options) -> {ok, Pid, ConnectionRef} |
435 {error, reason()|term()}
436 start_channel(TcpSocket) ->
437 start_channel(TcpSocket, Options) -> {ok, Pid, ConnectionRef} | {error,
438 reason()|term()}
439 Types:
441 Host = string()
443 ConnectionRef = connection_ref()
444 Port = integer()
445 TcpSocket = port()
446 The socket is supposed to be from gen_tcp:connect or
447 gen_tcp:accept with option {active,false}
448 Options = [{Option, Value}]
449 If no connection reference is provided, a connection is set up,
451 and the new connection is returned. An SSH channel process is
452 started to handle the communication with the SFTP server. The
453 returned pid for this process is to be used as input to all
454 other API functions in this module.
455 Options:
457 {timeout, timeout()}:
459 There are two ways to set a timeout for the underlying ssh
460 connection:
461 * If the connection timeout option connect_timeout is set,
463 that value is used also for the negotiation timeout and
464 this option (timeout) is ignored.
465 * Otherwise, this option (timeout) is used as the negotia‐
467 tion timeout only and there is no connection timeout set
468 The value defaults to infinity.
470 {sftp_vsn, integer()}:
472 Desired SFTP protocol version. The actual version is the
473 minimum of the desired version and the maximum supported
474 versions by the SFTP server.
475 All other options are directly passed to ssh:connect/3 or
477 ignored if a connection is already provided.
478 stop_channel(ChannelPid) -> ok
480 Types:
482 ChannelPid = pid()
484 Stops an SFTP channel. Does not close the SSH connection. Use
486 ssh:close/1 to close it.
487 write(ChannelPid, Handle, Data) ->
489 write(ChannelPid, Handle, Data, Timeout) -> ok | {error, reason()}
490 Types:
492 ChannelPid = pid()
494 Handle = term()
495 Position = integer()
496 Data = iolist()
497 Timeout = timeout()
498 Writes data to the file referenced by Handle. The file is to be
500 opened with write or append flag. Returns ok if successful or
501 {error, reason()} otherwise.
502 write_file(ChannelPid, File, Iolist) ->
504 write_file(ChannelPid, File, Iolist, Timeout) -> ok | {error, reason()}
505 Types:
507 ChannelPid = pid()
509 File = string()
510 Iolist = iolist()
511 Timeout = timeout()
512 Writes a file to the server. The file is created if it does not
514 exist but overwritten if it exists.
515 write_file_info(ChannelPid, Name, Info) ->
517 write_file_info(ChannelPid, Name, Info, Timeout) -> ok | {error, rea‐
518 son()}
519 Types:
521 ChannelPid = pid()
523 Name = string()
524 Info = record()
525 Timeout = timeout()
526 Writes file information from a file_info record to the file
528 specified by Name. See file:write_file_info/[2,3] for informa‐
529 tion about the record.
530Ericsson AB ssh 4.7.6 ssh_sftp(3)