Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
ssh_sftp(3)		   Erlang Module Definition		   ssh_sftp(3)

NAME
       ssh_sftp	- SFTP client.

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

DATA TYPES
       Type definitions	that are used more than	once in	this  module,  or  ab-
       stractions to indicate the intended use of the data type, or both:

	 reason():
	   =  atom()  |	 string() | tuple() A description of the reason	why an
	   operation failed.

	   The atom() value is formed from the sftp error codes	in the	proto-
	   col-level  responses	as defined in draft-ietf-secsh-filexfer-13.txt
	   section 9.1.

	   The codes are named as SSH_FX_* which are transformed  into	lower-
	   case	of the star-part. E.g. the error code SSH_FX_NO_SUCH_FILE will
	   cause the reason() to be no_such_file.

	   The string()	reason is the error information	 from  the  server  in
	   case	of an exit-signal. If that information is empty, the reason is
	   the exit signal name.

	   The tuple() reason are other	 errors	 like  the  {exit_status,inte-
	   ger()} if the exit status is	not 0.

	 connection_ref() =:
	   opaque() - as returned by ssh:connect/3

	 timeout():
	   = infinity |	integer() in milliseconds. Default infinity.

TIME-OUTS
       If  the request functions for the SFTP channel return {error, timeout},
       no answer was received from the server within the expected time.

       The request may have reached the	server and may	have  been  performed.
       However,	 no  answer  was  received from	the server within the expected
       time.

EXPORTS
       apread(ChannelPid, Handle, Position, Len) -> {async, N} | {error,  rea-
       son()}

	      Types:

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

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

       apwrite(ChannelPid, Handle, Position, Data) ->  {async,	N}  |  {error,
       reason()}

	      Types:

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

	      The apwrite/4 function writes to a specified position, combining
	      the position/3 and awrite/3 functions.

       aread(ChannelPid, Handle, Len) -> {async, N} | {error, reason()}

	      Types:

		 ChannelPid = pid()
		 Handle	= term()
		 Position = integer()
		 Len = integer()
		 N = 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  re-
	      sult  from  the  read,  either  {ok, Data}, eof, or {error, rea-
	      son()}.

       awrite(ChannelPid, Handle, Data)	-> {async, N} |	{error,	reason()}

	      Types:

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

	      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,
	      reason()}.

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

	      Types:

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

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

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

	      Types:

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

	      Deletes the file specified by Name.

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

	      Types:

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

	      Deletes a	directory specified by Name.  The  directory  must  be
	      empty before it can be successfully deleted.

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

	      Types:

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

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

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

	      Types:

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

	      Creates  a directory specified by	Name. Name must	be a full path
	      to a new directory. The directory	can only be created in an  ex-
	      isting directory.

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

	      Types:

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

	      Creates a	symbolic link pointing to Target with the name Name.

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

	      Types:

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

	      Opens  a	file  on the server and	returns	a handle, which	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()

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

       open_tar(ChannelPid, Path, Mode)	->
       open_tar(ChannelPid,  Path,  Mode,  Timeout)  ->	{ok, Handle} | {error,
       reason()}

	      Types:

		 ChannelPid = pid()
		 Path =	string()
		 Mode =	[read] | [write] | [read,EncryptOpt] |	[write,Decryp-
		 tOpt]
		 EncryptOpt = {crypto,{InitFun,EncryptFun,CloseFun}}
		 DecryptOpt = {crypto,{InitFun,DecryptFun}}
		 InitFun  =  (fun() -> {ok,CryptoState}) | (fun() -> {ok,Cryp-
		 toState,ChunkSize})
		 CryptoState = any()
		 ChunkSize = undefined | pos_integer()
		 EncryptFun = (fun(PlainBin,CryptoState) -> EncryptResult)
		 EncryptResult = {ok,EncryptedBin,CryptoState} |  {ok,Encrypt-
		 edBin,CryptoState,ChunkSize}
		 PlainBin = binary()
		 EncryptedBin =	binary()
		 DecryptFun = (fun(EncryptedBin,CryptoState) ->	DecryptResult)
		 DecryptResult	 =   {ok,PlainBin,CryptoState}	 |  {ok,Plain-
		 Bin,CryptoState,ChunkSize}
		 CloseFun = (fun(PlainBin,CryptoState) -> {ok,EncryptedBin})
		 Timeout = timeout()

	      Opens a handle to	a tar file  on	the  server,  associated  with
	      ChannelPid.  The	handle can be used for remote tar creation and
	      extraction, as defined by	the erl_tar:init/3 function.

	      For code exampel see Section SFTP	Client	with  TAR  Compression
	      and Encryption in	the ssh	Users Guide.

	      The  crypto  mode	 option	 is applied to the generated stream of
	      bytes prior to sending them to the SFTP server. This is intended
	      for encryption but can be	used for other purposes.

	      The InitFun is applied once prior	to any other crypto operation.
	      The returned CryptoState is then folded into  repeated  applica-
	      tions  of	the EncryptFun or DecryptFun. The binary returned from
	      those funs are sent further to the remote	SFTP server.  Finally,
	      if  doing	 encryption, the CloseFun is applied to	the last piece
	      of data. The CloseFun is responsible for padding (if needed) and
	      encryption of that last piece.

	      The  ChunkSize  defines the size of the PlainBins	that EncodeFun
	      is applied to. If	the ChunkSize is undefined, the	 size  of  the
	      PlainBins	 varies,  because  this	is intended for	stream crypto,
	      whereas a	fixed ChunkSize	is intended for	block  crypto.	Chunk-
	      Sizes  can  be  changed in the return from the EncryptFun	or De-
	      cryptFun.	The value can be changed between pos_integer() and un-
	      defined.

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

	      Types:

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

	      Sets the file position of	the file referenced by Handle. Returns
	      {ok, NewPosition}	(as an absolute	offset)	if successful,	other-
	      wise {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 eariler with Offset 0, that is, {bof, 0} | {cur,
		  0} | {eof, 0}.

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

	      Types:

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

	      The  pread/3,4 function reads from a specified position, combin-
	      ing the position/3 and read/3,4 functions.

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

	      Types:

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

	      The  pwrite/3,4 function writes to a specified position, combin-
	      ing the position/3 and write/3,4 functions.

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

	      Types:

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

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

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

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

	      Types:

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

	      Reads a file from	the server, and	returns	the data in a binary.

       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()

	      Returns a	file_info record from the file system object specified
	      by Name or Handle.  See  file:read_file_info/2  for  information
	      about the	record.

	      Depending	 on  the  underlying OS:es links might be followed and
	      info  on	the  final  file,  directory  etc  is  returned.   See
	      ssh_sftp::read_link_info/2  on  how  to get information on links
	      instead.

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

	      Types:

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

	      Reads the	link target from the symbolic link specified by	name.

       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()

	      Returns a	file_info record from the symbolic link	 specified  by
	      Name  or Handle. See file:read_link_info/2 for information about
	      the record.

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

	      Types:

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

	      Renames a	file named OldName and gives it	the name NewName.

       start_channel(ConnectionRef) ->
       start_channel(ConnectionRef, Options)  ->  {ok,	Pid}  |	 {error,  rea-
       son()|term()}
       start_channel(Host, Options) ->
       start_channel(Host,  Port,  Options) -> {ok, Pid, ConnectionRef}	| {er-
       ror, reason()|term()}
       start_channel(TcpSocket)	->
       start_channel(TcpSocket,	Options) -> {ok, Pid, ConnectionRef} | {error,
       reason()|term()}

	      Types:

		 Host =	string()
		 ConnectionRef = connection_ref()
		 Port =	integer()
		 TcpSocket = port()
		   The	socket	is  supposed  to  be  from  gen_tcp:connect or
		   gen_tcp:accept with option {active,false}
		 Options = [{Option, Value}]

	      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	 is to be used as input	to all
	      other API	functions in this module.

	      Options:

		{timeout, timeout()}:
		  There	are two	ways to	set a timeout for the  underlying  ssh
		  connection:

		  * If	the  connection	timeout	option connect_timeout is set,
		    that value is used also for	the  negotiation  timeout  and
		    this option	(timeout) is ignored.

		  * Otherwise,	this  option (timeout) is used as the negotia-
		    tion timeout only and there	is no connection timeout set

		  The value defaults to	infinity.

		{sftp_vsn, integer()}:
		  Desired SFTP protocol	version. The  actual  version  is  the
		  minimum  of  the  desired  version and the maximum supported
		  versions by the SFTP server.

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

       stop_channel(ChannelPid)	-> ok

	      Types:

		 ChannelPid = pid()

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

       write(ChannelPid, Handle, Data) ->
       write(ChannelPid, Handle, Data, Timeout)	-> ok |	{error,	reason()}

	      Types:

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

	      Writes data to the file referenced by Handle. The	file is	to  be
	      opened  with  write  or append flag. Returns ok if successful or
	      {error, reason()}	otherwise.

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

	      Types:

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

	      Writes a file to the server. The file is created if it does  not
	      exist but	overwritten if it exists.

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

	      Types:

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

	      Writes file information from a  file_info	 record	 to  the  file
	      specified	 by  Name. See file:write_file_info/[2,3] for informa-
	      tion about the record.

Ericsson AB			   ssh 4.7.4			   ssh_sftp(3)

NAME | DESCRIPTION | DATA TYPES | TIME-OUTS | EXPORTS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=ssh_sftp&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help