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, en‐
10 crypted file transfer service available for SSH.
11
13 sftp_option() =
14 {timeout, timeout()} |
15 {sftp_vsn, integer() >= 1} |
16 {window_size, integer() >= 1} |
17 {packet_size, integer() >= 1}
18 Error cause
20 reason() = atom() | string() | tuple()
21 A description of the reason why an operation failed.
23 The atom() value is formed from the sftp error codes in the pro‐
25 tocol-level responses as defined in draft-ietf-secsh-filexfer-13
26 section 9.1. The codes are named as SSH_FX_* which are trans‐
27 formed into lowercase of the star-part. E.g. the error code
28 SSH_FX_NO_SUCH_FILE will cause the reason() to be no_such_file.
29 The string() reason is the error information from the server in
31 case of an exit-signal. If that information is empty, the reason
32 is the exit signal name.
33 The tuple() reason are other errors like for example {exit_sta‐
35 tus,1}.
36 Crypto operations for open_tar
38 tar_crypto_spec() = encrypt_spec() | decrypt_spec()
39 encrypt_spec() = {init_fun(), crypto_fun(), final_fun()}
41 decrypt_spec() = {init_fun(), crypto_fun()}
43 Specifies the encryption or decryption applied to tar files when
45 using open_tar/3 or open_tar/4.
46 The encryption or decryption is applied to the generated stream
48 of bytes prior to sending the resulting stream to the SFTP
49 server.
50 For code examples see Section Example with encryption in the ssh
52 Users Guide.
53 init_fun() =
55 fun(() -> {ok, crypto_state()}) |
56 fun(() -> {ok, crypto_state(), chunk_size()})
57 chunk_size() = undefined | integer() >= 1
59 crypto_state() = any()
61 The init_fun() in the tar_crypto_spec is applied once prior to
63 any other crypto operation. The intention is that this function
64 initiates the encryption or decryption for example by calling
65 crypto:crypto_init/4 or similar. The crypto_state() is the state
66 such a function may return.
67 If the selected cipher needs to have the input data partioned
69 into blocks of a certain size, the init_fun() should return the
70 second form of return value with the chunk_size() set to the
71 block size. If the chunk_size() is undefined, the size of the
72 PlainBins varies, because this is intended for stream crypto,
73 whereas a fixed chunk_size() is intended for block crypto. A
74 chunk_size() can be changed in the return from the crypto_fun().
75 The value can be changed between pos_integer() and undefined.
76 crypto_fun() =
78 fun((TextIn :: binary(), crypto_state()) -> crypto_result())
79 crypto_result() =
81 {ok, TextOut :: binary(), crypto_state()} |
82 {ok, TextOut :: binary(), crypto_state(), chunk_size()}
83 The initial crypto_state() returned from the init_fun() is
85 folded into repeated applications of the crypto_fun() in the
86 tar_crypto_spec. The binary returned from that fun is sent to
87 the remote SFTP server and the new crypto_state() is used in the
88 next call of the crypto_fun().
89 If the crypto_fun() reurns a chunk_size(), that value is as
91 block size for further blocks in calls to crypto_fun().
92 final_fun() =
94 fun((FinalTextIn :: binary(), crypto_state()) ->
95 {ok, FinalTextOut :: binary()})
96 If doing encryption, the final_fun() in the tar_crypto_spec is
98 applied to the last piece of data. The final_fun() is responsi‐
99 ble for padding (if needed) and encryption of that last piece.
100
102 apread(ChannelPid, Handle, Position, Len) -> {async, N} | Error
103 Types:
105 ChannelPid = pid()
107 Handle = term()
108 Position = Len = integer()
109 Error = {error, reason()}
110 N = term()
111 The apread/4 function reads from a specified position, combining
113 the position/3 and aread/3 functions.
114 apwrite(ChannelPid, Handle, Position, Data) -> {async, N} | Error
116 Types:
118 ChannelPid = pid()
120 Handle = term()
121 Position = integer()
122 Data = binary()
123 Error = {error, reason()}
124 N = term()
125 The apwrite/4 function writes to a specified position, combining
127 the position/3 and awrite/3 functions.
128 aread(ChannelPid, Handle, Len) -> {async, N} | Error
130 Types:
132 ChannelPid = pid()
134 Handle = term()
135 Len = integer()
136 Error = {error, reason()}
137 N = term()
138 Reads from an open file, without waiting for the result. If the
140 handle is valid, the function returns {async, N}, where N is a
141 term guaranteed to be unique between calls of aread. The actual
142 data is sent as a message to the calling process. This message
143 has the form {async_reply, N, Result}, where Result is the re‐
144 sult from the read, either {ok, Data}, eof, or {error, rea‐
145 son()}.
146 awrite(ChannelPid, Handle, Data) -> {async, N} | Error
148 Types:
150 ChannelPid = pid()
152 Handle = term()
153 Data = binary()
154 Error = {error, reason()}
155 N = term()
156 Writes to an open file, without waiting for the result. If the
158 handle is valid, the function returns {async, N}, where N is a
159 term guaranteed to be unique between calls of awrite. The result
160 of the write operation is sent as a message to the calling
161 process. This message has the form {async_reply, N, Result},
162 where Result is the result from the write, either ok, or {error,
163 reason()}.
164 close(ChannelPid, Handle) -> ok | Error
166 close(ChannelPid, Handle, Timeout) -> ok | Error
168 Types:
170 ChannelPid = pid()
172 Handle = term()
173 Timeout = timeout()
174 Error = {error, reason()}
175 Closes a handle to an open file or directory on the server.
177 delete(ChannelPid, Name) -> ok | Error
179 delete(ChannelPid, Name, Timeout) -> ok | Error
181 Types:
183 ChannelPid = pid()
185 Name = string()
186 Timeout = timeout()
187 Error = {error, reason()}
188 Deletes the file specified by Name.
190 del_dir(ChannelPid, Name) -> ok | Error
192 del_dir(ChannelPid, Name, Timeout) -> ok | Error
194 Types:
196 ChannelPid = pid()
198 Name = string()
199 Timeout = timeout()
200 Error = {error, reason()}
201 Deletes a directory specified by Name. The directory must be
203 empty before it can be successfully deleted.
204 list_dir(ChannelPid, Path) -> {ok, FileNames} | Error
206 list_dir(ChannelPid, Path, Timeout) -> {ok, FileNames} | Error
208 Types:
210 ChannelPid = pid()
212 Path = string()
213 Timeout = timeout()
214 FileNames = [FileName]
215 FileName = string()
216 Error = {error, reason()}
217 Lists the given directory on the server, returning the filenames
219 as a list of strings.
220 make_dir(ChannelPid, Name) -> ok | Error
222 make_dir(ChannelPid, Name, Timeout) -> ok | Error
224 Types:
226 ChannelPid = pid()
228 Name = string()
229 Timeout = timeout()
230 Error = {error, reason()}
231 Creates a directory specified by Name. Name must be a full path
233 to a new directory. The directory can only be created in an ex‐
234 isting directory.
235 make_symlink(ChannelPid, Name, Target) -> ok | Error
237 make_symlink(ChannelPid, Name, Target, Timeout) -> ok | Error
239 Types:
241 ChannelPid = pid()
243 Name = Target = string()
244 Timeout = timeout()
245 Error = {error, reason()}
246 Creates a symbolic link pointing to Target with the name Name.
248 open(ChannelPid, Name, Mode) -> {ok, Handle} | Error
250 open(ChannelPid, Name, Mode, Timeout) -> {ok, Handle} | Error
252 Types:
254 ChannelPid = pid()
256 Name = string()
257 Mode = [read | write | append | binary | raw]
258 Timeout = timeout()
259 Handle = term()
260 Error = {error, reason()}
261 Opens a file on the server and returns a handle, which can be
263 used for reading or writing.
264 opendir(ChannelPid, Path) -> {ok, Handle} | Error
266 opendir(ChannelPid, Path, Timeout) -> {ok, Handle} | Error
268 Types:
270 ChannelPid = pid()
272 Path = string()
273 Timeout = timeout()
274 Handle = term()
275 Error = {error, reason()}
276 Opens a handle to a directory on the server. The handle can be
278 used for reading directory contents.
279 open_tar(ChannelPid, Path, Mode) -> {ok, Handle} | Error
281 open_tar(ChannelPid, Path, Mode, Timeout) -> {ok, Handle} | Error
283 Types:
285 ChannelPid = pid()
287 Path = string()
288 Mode = [read | write | {crypto, tar_crypto_spec()}]
289 Timeout = timeout()
290 Handle = term()
291 Error = {error, reason()}
292 Opens a handle to a tar file on the server, associated with
294 ChannelPid. The handle can be used for remote tar creation and
295 extraction. The actual writing and reading is performed by calls
296 to erl_tar:add/3,4 and erl_tar:extract/2. Note: The
297 erl_tar:init/3 function should not be called, that one is called
298 by this open_tar function.
299 For code examples see Section SFTP Client with TAR Compression
301 in the ssh Users Guide.
302 The crypto mode option is explained in the data types section
304 above, see Crypto operations for open_tar. Encryption is assumed
305 if the Mode contains write, and decryption if the Mode contains
306 read.
307 position(ChannelPid, Handle, Location) ->
309 {ok, NewPosition} | Error
310 position(ChannelPid, Handle, Location, Timeout) ->
312 {ok, NewPosition} | Error
313 Types:
315 ChannelPid = pid()
317 Handle = term()
318 Location =
319 Offset |
320 {bof, Offset} |
321 {cur, Offset} |
322 {eof, Offset} |
323 bof | cur | eof
324 Timeout = timeout()
325 Offset = NewPosition = integer()
326 Error = {error, reason()}
327 Sets the file position of the file referenced by Handle. Returns
329 {ok, NewPosition} (as an absolute offset) if successful, other‐
330 wise {error, reason()}. Location is one of the following:
331 Offset:
333 The same as {bof, Offset}.
334 {bof, Offset}:
336 Absolute offset.
337 {cur, Offset}:
339 Offset from the current position.
340 {eof, Offset}:
342 Offset from the end of file.
343 bof | cur | eof:
345 The same as eariler with Offset 0, that is, {bof, 0} | {cur,
346 0} | {eof, 0}.
347 pread(ChannelPid, Handle, Position, Len) ->
349 {ok, Data} | eof | Error
350 pread(ChannelPid, Handle, Position, Len, Timeout) ->
352 {ok, Data} | eof | Error
353 Types:
355 ChannelPid = pid()
357 Handle = term()
358 Position = Len = integer()
359 Timeout = timeout()
360 Data = string() | binary()
361 Error = {error, reason()}
362 The pread/3,4 function reads from a specified position, combin‐
364 ing the position/3 and read/3,4 functions.
365 pwrite(ChannelPid, Handle, Position, Data) -> ok | Error
367 pwrite(ChannelPid, Handle, Position, Data, Timeout) -> ok | Error
369 Types:
371 ChannelPid = pid()
373 Handle = term()
374 Position = integer()
375 Data = iolist()
376 Timeout = timeout()
377 Error = {error, reason()}
378 The pwrite/3,4 function writes to a specified position, combin‐
380 ing the position/3 and write/3,4 functions.
381 read(ChannelPid, Handle, Len) -> {ok, Data} | eof | Error
383 read(ChannelPid, Handle, Len, Timeout) -> {ok, Data} | eof | Error
385 Types:
387 ChannelPid = pid()
389 Handle = term()
390 Len = integer()
391 Timeout = timeout()
392 Data = string() | binary()
393 Error = {error, reason()}
394 Reads Len bytes from the file referenced by Handle. Returns {ok,
396 Data}, eof, or {error, reason()}. If the file is opened with bi‐
397 nary, Data is a binary, otherwise it is a string.
398 If the file is read past eof, only the remaining bytes are read
400 and returned. If no bytes are read, eof is returned.
401 read_file(ChannelPid, File) -> {ok, Data} | Error
403 read_file(ChannelPid, File, Timeout) -> {ok, Data} | Error
405 Types:
407 ChannelPid = pid()
409 File = string()
410 Data = binary()
411 Timeout = timeout()
412 Error = {error, reason()}
413 Reads a file from the server, and returns the data in a binary.
415 read_file_info(ChannelPid, Name) -> {ok, FileInfo} | Error
417 read_file_info(ChannelPid, Name, Timeout) ->
419 {ok, FileInfo} | Error
420 Types:
422 ChannelPid = pid()
424 Name = string()
425 Timeout = timeout()
426 FileInfo = file:file_info()
427 Error = {error, reason()}
428 Returns a file_info record from the file system object specified
430 by Name or Handle. See file:read_file_info/2 for information
431 about the record.
432 Depending on the underlying OS:es links might be followed and
434 info on the final file, directory etc is returned. See
435 read_link_info/2 on how to get information on links instead.
436 read_link(ChannelPid, Name) -> {ok, Target} | Error
438 read_link(ChannelPid, Name, Timeout) -> {ok, Target} | Error
440 Types:
442 ChannelPid = pid()
444 Name = Target = string()
445 Timeout = timeout()
446 Error = {error, reason()}
447 Reads the link target from the symbolic link specified by name.
449 read_link_info(ChannelPid, Name) -> {ok, FileInfo} | Error
451 read_link_info(ChannelPid, Name, Timeout) ->
453 {ok, FileInfo} | Error
454 Types:
456 ChannelPid = pid()
458 Name = string()
459 FileInfo = file:file_info()
460 Timeout = timeout()
461 Error = {error, reason()}
462 Returns a file_info record from the symbolic link specified by
464 Name or Handle. See file:read_link_info/2 for information about
465 the record.
466 rename(ChannelPid, OldName, NewName) -> ok | Error
468 rename(ChannelPid, OldName, NewName, Timeout) -> ok | Error
470 Types:
472 ChannelPid = pid()
474 OldName = NewName = string()
475 Timeout = timeout()
476 Error = {error, reason()}
477 Renames a file named OldName and gives it the name NewName.
479 start_channel(ConnectionRef) ->
481 start_channel(ConnectionRef, SftpOptions) -> {ok, ChannelPid} | Error
482 start_channel(Host) ->
483 start_channel(Host, Options) ->
484 start_channel(Host, Port, Options) ->
485 start_channel(TcpSocket) ->
486 start_channel(TcpSocket, Options) -> {ok, ChannelPid, ConnectionRef} |
487 Error
488 Types:
490 Host = ssh:host()
492 Port = inet:port_number()
493 TcpSocket = ssh:open_socket()
494 Options = [ sftp_option() | ssh:client_option() ]
495 SftpOptions = [ sftp_option() ]
496 ChannelPid = pid()
497 ConnectionRef = ssh:connection_ref()
498 Error = {error, reason()}
499 If no connection reference is provided, a connection is set up,
501 and the new connection is returned. An SSH channel process is
502 started to handle the communication with the SFTP server. The
503 returned pid for this process is to be used as input to all
504 other API functions in this module.
505 Options:
507 {timeout, timeout()}:
509 There are two ways to set a timeout for the underlying ssh
510 connection:
511 * If the connection timeout option connect_timeout is set,
513 that value is used also for the negotiation timeout and
514 this option (timeout) is ignored.
515 * Otherwise, this option (timeout) is used as the negotia‐
517 tion timeout only and there is no connection timeout set
518 The value defaults to infinity.
520 {sftp_vsn, integer()}:
522 Desired SFTP protocol version. The actual version is the
523 minimum of the desired version and the maximum supported
524 versions by the SFTP server.
525 All other options are directly passed to ssh:connect/3 or ig‐
527 nored if a connection is already provided.
528 stop_channel(ChannelPid) -> ok
530 Types:
532 ChannelPid = pid()
534 Stops an SFTP channel. Does not close the SSH connection. Use
536 ssh:close/1 to close it.
537 write(ChannelPid, Handle, Data) -> ok | Error
539 write(ChannelPid, Handle, Data, Timeout) -> ok | Error
541 Types:
543 ChannelPid = pid()
545 Handle = term()
546 Data = iodata()
547 Timeout = timeout()
548 Error = {error, reason()}
549 Writes data to the file referenced by Handle. The file is to be
551 opened with write or append flag. Returns ok if successful or
552 {error, reason()} otherwise.
553 write_file(ChannelPid, File, Data) -> ok | Error
555 write_file(ChannelPid, File, Data, Timeout) -> ok | Error
557 Types:
559 ChannelPid = pid()
561 File = string()
562 Data = iodata()
563 Timeout = timeout()
564 Error = {error, reason()}
565 Writes a file to the server. The file is created if it does not
567 exist but overwritten if it exists.
568 write_file_info(ChannelPid, Name, FileInfo) -> ok | Error
570 write_file_info(ChannelPid, Name, FileInfo, Timeout) -> ok | Error
572 Types:
574 ChannelPid = pid()
576 Name = string()
577 FileInfo = file:file_info()
578 Timeout = timeout()
579 Error = {error, reason()}
580 Writes file information from a file_info record to the file
582 specified by Name. See file:write_file_info/[2,3] for informa‐
583 tion about the record.
584Ericsson AB ssh 4.13.2.1 ssh_sftp(3)