1ssh_sftp(3)                Erlang Module Definition                ssh_sftp(3)
2
3
4

NAME

6       ssh_sftp - SFTP client.
7

DESCRIPTION

9       This  module implements an SSH FTP (SFTP) client. SFTP is a secure, en‐
10       crypted file transfer service available for SSH.
11

DATA TYPES

13       sftp_option() =
14           {timeout, timeout()} |
15           {sftp_vsn, integer() >= 1} |
16           {window_size, integer() >= 1} |
17           {packet_size, integer() >= 1}
18
19   Error cause
20       reason() = atom() | string() | tuple()
21
22              A description of the reason why an operation failed.
23
24              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
30              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
34              The tuple() reason are other errors like for example  {exit_sta‐
35              tus,1}.
36
37   Crypto operations for open_tar
38       tar_crypto_spec() = encrypt_spec() | decrypt_spec()
39
40       encrypt_spec() = {init_fun(), crypto_fun(), final_fun()}
41
42       decrypt_spec() = {init_fun(), crypto_fun()}
43
44              Specifies the encryption or decryption applied to tar files when
45              using open_tar/3 or open_tar/4.
46
47              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
51              For code examples see Section Example with encryption in the ssh
52              Users Guide.
53
54       init_fun() =
55           fun(() -> {ok, crypto_state()}) |
56           fun(() -> {ok, crypto_state(), chunk_size()})
57
58       chunk_size() = undefined | integer() >= 1
59
60       crypto_state() = any()
61
62              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
68              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
77       crypto_fun() =
78           fun((TextIn :: binary(), crypto_state()) -> crypto_result())
79
80       crypto_result() =
81           {ok, TextOut :: binary(), crypto_state()} |
82           {ok, TextOut :: binary(), crypto_state(), chunk_size()}
83
84              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
90              If the crypto_fun() reurns a  chunk_size(),  that  value  is  as
91              block size for further blocks in calls to crypto_fun().
92
93       final_fun() =
94           fun((FinalTextIn :: binary(), crypto_state()) ->
95                   {ok, FinalTextOut :: binary()})
96
97              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

EXPORTS

102       apread(ChannelPid, Handle, Position, Len) -> {async, N} | Error
103
104              Types:
105
106                 ChannelPid = pid()
107                 Handle = term()
108                 Position = Len = integer()
109                 Error = {error, reason()}
110                 N = term()
111
112              The apread/4 function reads from a specified position, combining
113              the position/3 and aread/3 functions.
114
115       apwrite(ChannelPid, Handle, Position, Data) -> {async, N} | Error
116
117              Types:
118
119                 ChannelPid = pid()
120                 Handle = term()
121                 Position = integer()
122                 Data = binary()
123                 Error = {error, reason()}
124                 N = term()
125
126              The apwrite/4 function writes to a specified position, combining
127              the position/3 and awrite/3 functions.
128
129       aread(ChannelPid, Handle, Len) -> {async, N} | Error
130
131              Types:
132
133                 ChannelPid = pid()
134                 Handle = term()
135                 Len = integer()
136                 Error = {error, reason()}
137                 N = term()
138
139              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
147       awrite(ChannelPid, Handle, Data) -> {async, N} | Error
148
149              Types:
150
151                 ChannelPid = pid()
152                 Handle = term()
153                 Data = binary()
154                 Error = {error, reason()}
155                 N = term()
156
157              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
165       close(ChannelPid, Handle) -> ok | Error
166
167       close(ChannelPid, Handle, Timeout) -> ok | Error
168
169              Types:
170
171                 ChannelPid = pid()
172                 Handle = term()
173                 Timeout = timeout()
174                 Error = {error, reason()}
175
176              Closes a handle to an open file or directory on the server.
177
178       delete(ChannelPid, Name) -> ok | Error
179
180       delete(ChannelPid, Name, Timeout) -> ok | Error
181
182              Types:
183
184                 ChannelPid = pid()
185                 Name = string()
186                 Timeout = timeout()
187                 Error = {error, reason()}
188
189              Deletes the file specified by Name.
190
191       del_dir(ChannelPid, Name) -> ok | Error
192
193       del_dir(ChannelPid, Name, Timeout) -> ok | Error
194
195              Types:
196
197                 ChannelPid = pid()
198                 Name = string()
199                 Timeout = timeout()
200                 Error = {error, reason()}
201
202              Deletes  a  directory  specified  by Name. The directory must be
203              empty before it can be successfully deleted.
204
205       list_dir(ChannelPid, Path) -> {ok, FileNames} | Error
206
207       list_dir(ChannelPid, Path, Timeout) -> {ok, FileNames} | Error
208
209              Types:
210
211                 ChannelPid = pid()
212                 Path = string()
213                 Timeout = timeout()
214                 FileNames = [FileName]
215                 FileName = string()
216                 Error = {error, reason()}
217
218              Lists the given directory on the server, returning the filenames
219              as a list of strings.
220
221       make_dir(ChannelPid, Name) -> ok | Error
222
223       make_dir(ChannelPid, Name, Timeout) -> ok | Error
224
225              Types:
226
227                 ChannelPid = pid()
228                 Name = string()
229                 Timeout = timeout()
230                 Error = {error, reason()}
231
232              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
236       make_symlink(ChannelPid, Name, Target) -> ok | Error
237
238       make_symlink(ChannelPid, Name, Target, Timeout) -> ok | Error
239
240              Types:
241
242                 ChannelPid = pid()
243                 Name = Target = string()
244                 Timeout = timeout()
245                 Error = {error, reason()}
246
247              Creates a symbolic link pointing to Target with the name Name.
248
249       open(ChannelPid, Name, Mode) -> {ok, Handle} | Error
250
251       open(ChannelPid, Name, Mode, Timeout) -> {ok, Handle} | Error
252
253              Types:
254
255                 ChannelPid = pid()
256                 Name = string()
257                 Mode = [read | write | append | binary | raw]
258                 Timeout = timeout()
259                 Handle = term()
260                 Error = {error, reason()}
261
262              Opens  a  file  on the server and returns a handle, which can be
263              used for reading or writing.
264
265       opendir(ChannelPid, Path) -> {ok, Handle} | Error
266
267       opendir(ChannelPid, Path, Timeout) -> {ok, Handle} | Error
268
269              Types:
270
271                 ChannelPid = pid()
272                 Path = string()
273                 Timeout = timeout()
274                 Handle = term()
275                 Error = {error, reason()}
276
277              Opens a handle to a directory on the server. The handle  can  be
278              used for reading directory contents.
279
280       open_tar(ChannelPid, Path, Mode) -> {ok, Handle} | Error
281
282       open_tar(ChannelPid, Path, Mode, Timeout) -> {ok, Handle} | Error
283
284              Types:
285
286                 ChannelPid = pid()
287                 Path = string()
288                 Mode = [read | write | {crypto, tar_crypto_spec()}]
289                 Timeout = timeout()
290                 Handle = term()
291                 Error = {error, reason()}
292
293              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
300              For code examples see Section SFTP Client with  TAR  Compression
301              in the ssh Users Guide.
302
303              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
308       position(ChannelPid, Handle, Location) ->
309                   {ok, NewPosition} | Error
310
311       position(ChannelPid, Handle, Location, Timeout) ->
312                   {ok, NewPosition} | Error
313
314              Types:
315
316                 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
328              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
332                Offset:
333                  The same as {bof, Offset}.
334
335                {bof, Offset}:
336                  Absolute offset.
337
338                {cur, Offset}:
339                  Offset from the current position.
340
341                {eof, Offset}:
342                  Offset from the end of file.
343
344                bof | cur | eof:
345                  The same as eariler with Offset 0, that is, {bof, 0} | {cur,
346                  0} | {eof, 0}.
347
348       pread(ChannelPid, Handle, Position, Len) ->
349                {ok, Data} | eof | Error
350
351       pread(ChannelPid, Handle, Position, Len, Timeout) ->
352                {ok, Data} | eof | Error
353
354              Types:
355
356                 ChannelPid = pid()
357                 Handle = term()
358                 Position = Len = integer()
359                 Timeout = timeout()
360                 Data = string() | binary()
361                 Error = {error, reason()}
362
363              The  pread/3,4 function reads from a specified position, combin‐
364              ing the position/3 and read/3,4 functions.
365
366       pwrite(ChannelPid, Handle, Position, Data) -> ok | Error
367
368       pwrite(ChannelPid, Handle, Position, Data, Timeout) -> ok | Error
369
370              Types:
371
372                 ChannelPid = pid()
373                 Handle = term()
374                 Position = integer()
375                 Data = iolist()
376                 Timeout = timeout()
377                 Error = {error, reason()}
378
379              The pwrite/3,4 function writes to a specified position,  combin‐
380              ing the position/3 and write/3,4 functions.
381
382       read(ChannelPid, Handle, Len) -> {ok, Data} | eof | Error
383
384       read(ChannelPid, Handle, Len, Timeout) -> {ok, Data} | eof | Error
385
386              Types:
387
388                 ChannelPid = pid()
389                 Handle = term()
390                 Len = integer()
391                 Timeout = timeout()
392                 Data = string() | binary()
393                 Error = {error, reason()}
394
395              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
399              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
402       read_file(ChannelPid, File) -> {ok, Data} | Error
403
404       read_file(ChannelPid, File, Timeout) -> {ok, Data} | Error
405
406              Types:
407
408                 ChannelPid = pid()
409                 File = string()
410                 Data = binary()
411                 Timeout = timeout()
412                 Error = {error, reason()}
413
414              Reads a file from the server, and returns the data in a binary.
415
416       read_file_info(ChannelPid, Name) -> {ok, FileInfo} | Error
417
418       read_file_info(ChannelPid, Name, Timeout) ->
419                         {ok, FileInfo} | Error
420
421              Types:
422
423                 ChannelPid = pid()
424                 Name = string()
425                 Timeout = timeout()
426                 FileInfo = file:file_info()
427                 Error = {error, reason()}
428
429              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
433              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
437       read_link(ChannelPid, Name) -> {ok, Target} | Error
438
439       read_link(ChannelPid, Name, Timeout) -> {ok, Target} | Error
440
441              Types:
442
443                 ChannelPid = pid()
444                 Name = Target = string()
445                 Timeout = timeout()
446                 Error = {error, reason()}
447
448              Reads the link target from the symbolic link specified by name.
449
450       read_link_info(ChannelPid, Name) -> {ok, FileInfo} | Error
451
452       read_link_info(ChannelPid, Name, Timeout) ->
453                         {ok, FileInfo} | Error
454
455              Types:
456
457                 ChannelPid = pid()
458                 Name = string()
459                 FileInfo = file:file_info()
460                 Timeout = timeout()
461                 Error = {error, reason()}
462
463              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
467       rename(ChannelPid, OldName, NewName) -> ok | Error
468
469       rename(ChannelPid, OldName, NewName, Timeout) -> ok | Error
470
471              Types:
472
473                 ChannelPid = pid()
474                 OldName = NewName = string()
475                 Timeout = timeout()
476                 Error = {error, reason()}
477
478              Renames a file named OldName and gives it the name NewName.
479
480       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
489              Types:
490
491                 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
500              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
506              Options:
507
508                {timeout, timeout()}:
509                  There  are  two ways to set a timeout for the underlying ssh
510                  connection:
511
512                  * 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
516                  * Otherwise, this option (timeout) is used as  the  negotia‐
517                    tion timeout only and there is no connection timeout set
518
519                  The value defaults to infinity.
520
521                {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
526              All  other  options  are directly passed to ssh:connect/3 or ig‐
527              nored if a connection is already provided.
528
529       stop_channel(ChannelPid) -> ok
530
531              Types:
532
533                 ChannelPid = pid()
534
535              Stops an SFTP channel. Does not close the  SSH  connection.  Use
536              ssh:close/1 to close it.
537
538       write(ChannelPid, Handle, Data) -> ok | Error
539
540       write(ChannelPid, Handle, Data, Timeout) -> ok | Error
541
542              Types:
543
544                 ChannelPid = pid()
545                 Handle = term()
546                 Data = iodata()
547                 Timeout = timeout()
548                 Error = {error, reason()}
549
550              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
554       write_file(ChannelPid, File, Data) -> ok | Error
555
556       write_file(ChannelPid, File, Data, Timeout) -> ok | Error
557
558              Types:
559
560                 ChannelPid = pid()
561                 File = string()
562                 Data = iodata()
563                 Timeout = timeout()
564                 Error = {error, reason()}
565
566              Writes  a file to the server. The file is created if it does not
567              exist but overwritten if it exists.
568
569       write_file_info(ChannelPid, Name, FileInfo) -> ok | Error
570
571       write_file_info(ChannelPid, Name, FileInfo, Timeout) -> ok | Error
572
573              Types:
574
575                 ChannelPid = pid()
576                 Name = string()
577                 FileInfo = file:file_info()
578                 Timeout = timeout()
579                 Error = {error, reason()}
580
581              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.
584
585
586
587Ericsson AB                      ssh 4.13.2.1                      ssh_sftp(3)
Impressum