Provided by: erlang-manpages_16.b.3-dfsg-1ubuntu2_all bug

NAME

       ssh_sftp - SFTP client.

DESCRIPTION

       This module implements an SFTP (SSH FTP) client. SFTP is a secure, encrypted file transfer
       service available for SSH.

DATA TYPES

       Type definitions that are used more than  once  in  this  module  and/or  abstractions  to
       indicate the intended use of the data type:

       ssh_connection_ref() - opaque to the user returned by ssh:connect/3

       timeout() = infinity | integer() - in milliseconds.

TIMEOUTS

       If  the  request  functions  for  the  SFTP  channel  return  {error, timeout} it does not
       guarantee that the request did not reach the server and was not performed, it  only  means
       that we did not receive an answer from the server within the time that was expected.

EXPORTS

       start_channel(ConnectionRef) ->
       start_channel(ConnectionRef, Options) ->
       start_channel(Host, Options) ->
       start_channel(Host,  Port,  Options)  ->  {ok,  Pid}  | {ok, Pid, ConnectionRef} | {error,
       Reason}

              Types:

                 Host = string()
                 ConnectionRef = ssh_connection_ref()
                 Port = integer()
                 Options = [{Option, Value}]
                 Reason = term()

              If no connection reference is  provided,  a  connection  is  set  up  and  the  new
              connection   is  returned.  An  SSH  channel  process  is  started  to  handle  the
              communication with the SFTP server. The returned pid for  this  process  should  be
              used as input to all other API functions in this module.

              Options are:

                {timeout, timeout()}:
                  The  timeout  is  passed  to  the  ssh_channel  start function, and defaults to
                  infinity.

              All other options are directly passed to ssh:connect/3 or ignored if  a  connection
              is already provided.

       stop_channel(ChannelPid) -> ok

              Types:

                 ChannelPid = pid()

              Stops  an  SFTP channel. Does not close the SSH connetion. Use ssh:close/1 to close
              it.

       read_file(ChannelPid, File) ->
       read_file(ChannelPid, File, Timeout) -> {ok, Data} | {error, Reason}

              Types:

                 ChannelPid = pid()
                 File = string()
                 Data = binary()
                 Timeout = timeout()
                 Reason = term()

              Reads  a  file  from  the  server,  and  returns  the  data  in  a   binary,   like
              file:read_file/1.

       write_file(ChannelPid, File, Iolist) ->
       write_file(ChannelPid, File, Iolist, Timeout) -> ok | {error, Reason}

              Types:

                 ChannelPid = pid()
                 File = string()
                 Iolist = iolist()
                 Timeout = timeout()
                 Reason = term()

              Writes a file to the server, like file:write_file/2. The file is created if it does
              not exist or is owerwritten if it does.

       list_dir(ChannelPid, Path) ->
       list_dir(ChannelPid, Path, Timeout) -> {ok, Filenames} | {error, Reason}

              Types:

                 ChannelPid = pid()
                 Path = string()
                 Filenames = [Filename]
                 Filename = string()
                 Timeout = timeout()
                 Reason = term()

              Lists the given directory on the server, returning  the  filenames  as  a  list  of
              strings.

       open(ChannelPid, File, Mode) ->
       open(ChannelPid, File, Mode, Timeout) -> {ok, Handle} | {error, Reason}

              Types:

                 ChannelPid = pid()
                 File = string()
                 Mode = [Modeflag]
                 Modeflag = read | write | creat | trunc | append | binary
                 Timeout = timeout()
                 Handle = term()
                 Reason = term()

              Opens  a  file  on the server, and returns a handle that can be used for reading or
              writing.

       opendir(ChannelPid, Path) ->
       opendir(ChannelPid, Path, Timeout) -> {ok, Handle} | {error, Reason}

              Types:

                 ChannelPid = pid()
                 Path = string()
                 Timeout = timeout()
                 Reason = term()

              Opens a handle to a directory on the server, the handle can  be  used  for  reading
              directory contents.

       close(ChannelPid, Handle) ->
       close(ChannelPid, Handle, Timeout) -> ok | {error, Reason}

              Types:

                 ChannelPid = pid()
                 Handle = term()
                 Timeout = timeout()
                 Reason = term()

              Closes a handle to an open file or directory on the server.

       read(ChannelPid, Handle, Len) ->
       read(ChannelPid, Handle, Len, Timeout) -> {ok, Data} | eof | {error, Error}
       pread(ChannelPid, Handle, Position, Len) ->
       pread(ChannelPid, Handle, Position, Len, Timeout) -> {ok, Data} | eof | {error, Error}

              Types:

                 ChannelPid = pid()
                 Handle = term()
                 Position = integer()
                 Len = integer()
                 Timeout = timeout()
                 Data = string() | binary()
                 Reason = term()

              Reads  Len  bytes  from  the file referenced by Handle. Returns {ok, Data}, eof, or
              {error, Reason}. If the file is opened with binary, Data is a binary, otherwise  it
              is a string.

              If  the  file is read past eof, only the remaining bytes will be read and returned.
              If no bytes are read, eof is returned.

              The pread function reads from a specified position, combining the position and read
              functions.

       aread(ChannelPid, Handle, Len) -> {async, N} | {error, Error}
       apread(ChannelPid, Handle, Position, Len) -> {async, N} | {error, Error}

              Types:

                 ChannelPid = pid()
                 Handle = term()
                 Position = integer()
                 Len = integer()
                 N = term()
                 Reason = term()

              Reads  from  an  open file, without waiting for the result. If the handle is valid,
              the function returns {async, N}, where N is a term guaranteed to be unique  between
              calls  of  aread. The actual data is sent as a message to the calling process. This
              message has the form {async_reply, N, Result}, where Result is the result from  the
              read, either {ok, Data}, or eof, or {error, Error}.

              The  apread  function  reads  from a specified position, combining the position and
              aread functions.

       write(ChannelPid, Handle, Data) ->
       write(ChannelPid, Handle, Data, Timeout) -> ok | {error, Error}
       pwrite(ChannelPid, Handle, Position, Data) -> ok
       pwrite(ChannelPid, Handle, Position, Data, Timeout) -> ok | {error, Error}

              Types:

                 ChannelPid = pid()
                 Handle = term()
                 Position = integer()
                 Data = iolist()
                 Timeout = timeout()
                 Reason = term()

              Writesdata to the file referenced by Handle. The file should be opened  with  write
              or append flag. Returns ok if successful or S{error, Reason} otherwise.

              Typical error reasons are:

                ebadf:
                  The file is not opened for writing.

                enospc:
                  There is a no space left on the device.

       awrite(ChannelPid, Handle, Data) -> ok | {error, Reason}
       apwrite(ChannelPid, Handle, Position, Data) -> ok | {error, Reason}

              Types:

                 ChannelPid = pid()
                 Handle = term()
                 Position = integer()
                 Len = integer()
                 Data = binary()
                 Timeout = timeout()
                 Reason = term()

              Writes to an open file, without waiting for the result. If the handle is valid, the
              function returns {async, N}, where N is a term  guaranteed  to  be  unique  between
              calls  of  awrite.  The  result  of the write operation is sent as a message to the
              calling process. This message has the form {async_reply, N, Result},  where  Result
              is the result from the write, either ok, or {error, Error}.

              The  apwrite  writes  on  a  specified  position, combining the position and awrite
              operations.

       position(ChannelPid, Handle, Location) ->
       position(ChannelPid, Handle, Location, Timeout) -> {ok, NewPosition | {error, Error}

              Types:

                 ChannelPid = pid()
                 Handle = term()
                 Location = Offset | {bof, Offset} | {cur, Offset} | {eof, Offset} | bof | cur  |
                 eof
                 Offset = integer()
                 Timeout = timeout()
                 NewPosition = integer()
                 Reason = term()

              Sets  the file position of the file referenced by Handle. Returns {ok, NewPosition}
              (as an absolute offset) if successful, otherwise {error, Reason}. Location  is  one
              of the following:

                Offset:
                  The same as {bof, Offset}.

                {bof, Offset}:
                  Absolute offset.

                {cur, Offset}:
                  Offset from the current position.

                {eof, Offset}:
                  Offset from the end of file.

                bof | cur | eof:
                  The same as above with Offset 0.

       read_file_info(ChannelPid, Name) ->
       read_file_info(ChannelPid, Name, Timeout) -> {ok, FileInfo} | {error, Reason}

              Types:

                 ChannelPid = pid()
                 Name = string()
                 Handle = term()
                 Timeout = timeout()
                 FileInfo = record()
                 Reason = term()

              Returns  a  file_info  record  from  the  file  specified  by  Name or Handle, like
              file:read_file_info/2.

       read_link_info(ChannelPid, Name) -> {ok, FileInfo} | {error, Reason}
       read_link_info(ChannelPid, Name, Timeout) -> {ok, FileInfo} | {error, Reason}

              Types:

                 ChannelPid = pid()
                 Name = string()
                 Handle = term()
                 Timeout = timeout()
                 FileInfo = record()
                 Reason = term()

              Returns a file_info record from the symbolic link specified by Name or Handle, like
              file:read_link_info/2.

       write_file_info(ChannelPid, Name, Info) ->
       write_file_info(ChannelPid, Name, Info, Timeout) -> ok | {error, Reason}

              Types:

                 ChannelPid = pid()
                 Name = string()
                 Info = record()
                 Timeout = timeout()
                 Reason = term()

              Writes file information from a file_info record to the file specified by Name, like
              file:write_file_info.

       read_link(ChannelPid, Name) ->
       read_link(ChannelPid, Name, Timeout) -> {ok, Target} | {error, Reason}

              Types:

                 ChannelPid = pid()
                 Name = string()
                 Target = string()
                 Reason = term()

              Reads  the  link  target  from  the  symbolic  link   specified   by   name,   like
              file:read_link/1.

       make_symlink(ChannelPid, Name, Target) ->
       make_symlink(ChannelPid, Name, Target, Timeout) -> ok | {error, Reason}

              Types:

                 ChannelPid = pid()
                 Name = string()
                 Target = string()
                 Reason = term()

              Creates   a   symbolic   link   pointing   to  Target  with  the  name  Name,  like
              file:make_symlink/2.

       rename(ChannelPid, OldName, NewName) ->
       rename(ChannelPid, OldName, NewName, Timeout) -> ok | {error, Reason}

              Types:

                 ChannelPid = pid()
                 OldName = string()
                 NewName = string()
                 Timeout = timeout()
                 Reason = term()

              Renames a file named OldName, and gives it the name NewName, like file:rename/2

       delete(ChannelPid, Name) ->
       delete(ChannelPid, Name, Timeout) -> ok | {error, Reason}

              Types:

                 ChannelPid = pid()
                 Name = string()
                 Timeout = timeout()
                 Reason = term()

              Deletes the file specified by Name, like file:delete/1

       make_dir(ChannelPid, Name) ->
       make_dir(ChannelPid, Name, Timeout) -> ok | {error, Reason}

              Types:

                 ChannelPid = pid()
                 Name = string()
                 Timeout = timeout()
                 Reason = term()

              Creates a directory specified by Name.  Name  should  be  a  full  path  to  a  new
              directory. The directory can only be created in an existing directory.

       del_dir(ChannelPid, Name) ->
       del_dir(ChannelPid, Name, Timeout) -> ok | {error, Reason}

              Types:

                 ChannelPid = pid()
                 Name = string()
                 Timeout = timeout()
                 Reason = term()

              Deletes a directory specified by Name. Note that the directory must be empty before
              it can be successfully deleted