From b2171f6bf65c5897d37103afec102fa565bc134e Mon Sep 17 00:00:00 2001 From: Hans Nilsson Date: Mon, 10 Nov 2014 17:09:25 +0100 Subject: erl_tar: Extend api to define own storage media access functions. The reason for this is a requirement on enabling ssh_sftp to write a tar file on the server. This new api function is used by ssh_sftp:open_tar/3,4. --- lib/stdlib/doc/src/erl_tar.xml | 110 ++++++++++++++++++++++++++++++++++++++++- 1 file changed, 109 insertions(+), 1 deletion(-) (limited to 'lib/stdlib/doc/src/erl_tar.xml') diff --git a/lib/stdlib/doc/src/erl_tar.xml b/lib/stdlib/doc/src/erl_tar.xml index 7f25f5b7bc..95eefb8f9b 100644 --- a/lib/stdlib/doc/src/erl_tar.xml +++ b/lib/stdlib/doc/src/erl_tar.xml @@ -79,6 +79,12 @@ done.

+
+ OTHER STORAGE MEDIA +

The erl_ftp module normally accesses the tar-file on disk using the file module. When other needs arise, there is a way to define your own low-level Erlang functions to perform the writing and reading on the storage media. See init/3 for usage.

+

An example of this is the sftp support in ssh_sftp:open_tar/3. That function opens a tar file on a remote machine using an sftp channel.

+
+
LIMITATIONS

For maximum compatibility, it is safe to archive files with names @@ -99,7 +105,8 @@ TarDescriptor = term() Filename = filename() Options = [Option] - Option = dereference|verbose + Option = dereference|verbose|{chunks,ChunkSize} + ChunkSize = positive_integer() RetValue = ok|{error,{Filename,Reason}} Reason = term() @@ -119,6 +126,12 @@

Print an informational message about the file being added.

+ {chunks,ChunkSize} + +

Read data in parts from the file. This is intended for memory-limited + machines that for example builds a tar file on a remote machine over + sftp.

+ @@ -389,6 +402,101 @@ + + + init(UserPrivate, AccessMode, Fun) -> {ok,TarDescriptor} | {error,Reason} + + Creates a TarDescriptor used in subsequent tar operations when + defining own low-level storage access functions + + + UserPrivate = term() + AccessMode = [write] | [read] + Fun when AccessMode is [write] = fun(write, {UserPrivate,DataToWrite})->...; + (position,{UserPrivate,Position})->...; + (close, UserPrivate)->... + end + + Fun when AccessMode is [read] = fun(read2, {UserPrivate,Size})->...; + (position,{UserPrivate,Position})->...; + (close, UserPrivate)->... + end + + TarDescriptor = term() + Reason = term() + + +

The Fun is the definition of what to do when the different + storage operations functions are to be called from the higher tar + handling functions (add/3, add/4, close/1...). +

+

The Fun will be called when the tar function wants to do + a low-level operation, like writing a block to a file. The Fun is called + as Fun(Op,{UserPrivate,Parameters...}) where Op is the operation name, + UserPrivate is the term passed as the first argument to init/1 and + Parameters... are the data added by the tar function to be passed down to + the storage handling function. +

+

The parameter UserPrivate is typically the result of opening a low level + structure like a file descriptor, a sftp channel id or such. The different Fun + clauses operates on that very term. +

+

The fun clauses parameter lists are: + + (write, {UserPrivate,DataToWrite}) + Write the term DataToWrite using UserPrivate + (close, UserPrivate) + Close the access. + (read2, {UserPrivate,Size}) + Read using UserPrivate but only Size bytes. Note that there is + only an arity-2 read function, not an arity-1 + + (position,{UserPrivate,Position}) + Sets the position of UserPrivate as defined for files in file:position/2 + + + +

+

A complete Fun parameter for reading and writing on files using the + file module could be: +

+ + ExampleFun = + fun(write, {Fd,Data}) -> file:write(Fd, Data); + (position, {Fd,Pos}) -> file:position(Fd, Pos); + (read2, {Fd,Size}) -> file:read(Fd,Size); + (close, Fd) -> file:close(Fd) + end + +

where Fd was given to the init/3 function as:

+ + {ok,Fd} = file:open(Name,...). + {ok,TarDesc} = erl_tar:init(Fd, [write], ExampleFun), + +

The TarDesc is then used:

+ + erl_tar:add(TarDesc, SomeValueIwantToAdd, FileNameInTarFile), + ...., + erl_tar:close(TarDesc) + +

When the erl_tar core wants to e.g. write a piece of Data, it would call + ExampleFun(write,{UserPrivate,Data}). +

+ +

The example above with file module operations is not necessary to + use directly since that is what the open function + in principle does. +

+ + +

The TarDescriptor term is not a file descriptor. + You should not rely on the specific contents of the TarDescriptor + term, as it may change in future versions as more features are added + to the erl_tar module.

+ + + + table(Name) -> RetValue Retrieve the name of all files in a tar file -- cgit v1.2.3