aboutsummaryrefslogtreecommitdiffstats
path: root/lib/stdlib/doc
diff options
context:
space:
mode:
Diffstat (limited to 'lib/stdlib/doc')
-rw-r--r--lib/stdlib/doc/src/erl_tar.xml110
-rw-r--r--lib/stdlib/doc/src/io_protocol.xml9
-rw-r--r--lib/stdlib/doc/src/maps.xml2
-rw-r--r--lib/stdlib/doc/src/string.xml6
-rw-r--r--lib/stdlib/doc/src/unicode_usage.xml15
5 files changed, 125 insertions, 17 deletions
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
@@ -80,6 +80,12 @@
</section>
<section>
+ <title>OTHER STORAGE MEDIA</title>
+ <p>The <c>erl_ftp</c> module normally accesses the tar-file on disk using the <seealso marker="kernel:file">file module</seealso>. 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 <seealso marker="#init/3">init/3</seealso> for usage.</p>
+ <p>An example of this is the sftp support in <seealso marker="ssh:ssh_sftp#open_tar/3">ssh_sftp:open_tar/3</seealso>. That function opens a tar file on a remote machine using an sftp channel.</p>
+ </section>
+
+ <section>
<title>LIMITATIONS</title>
<p>For maximum compatibility, it is safe to archive files with names
up to 100 characters in length. Such tar files can generally be
@@ -99,7 +105,8 @@
<v>TarDescriptor = term()</v>
<v>Filename = filename()</v>
<v>Options = [Option]</v>
- <v>Option = dereference|verbose</v>
+ <v>Option = dereference|verbose|{chunks,ChunkSize}</v>
+ <v>ChunkSize = positive_integer()</v>
<v>RetValue = ok|{error,{Filename,Reason}}</v>
<v>Reason = term()</v>
</type>
@@ -119,6 +126,12 @@
<item>
<p>Print an informational message about the file being added.</p>
</item>
+ <tag><c>{chunks,ChunkSize}</c></tag>
+ <item>
+ <p>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
+ <seealso marker="ssh:ssh_sftp#open_tar/3">sftp</seealso>.</p>
+ </item>
</taglist>
</desc>
</func>
@@ -389,6 +402,101 @@
</warning>
</desc>
</func>
+
+ <func>
+ <name>init(UserPrivate, AccessMode, Fun) -> {ok,TarDescriptor} | {error,Reason}
+</name>
+ <fsummary>Creates a TarDescriptor used in subsequent tar operations when
+ defining own low-level storage access functions
+ </fsummary>
+ <type>
+ <v>UserPrivate = term()</v>
+ <v>AccessMode = [write] | [read]</v>
+ <v>Fun when AccessMode is [write] = fun(write, {UserPrivate,DataToWrite})->...;
+ (position,{UserPrivate,Position})->...;
+ (close, UserPrivate)->...
+ end
+ </v>
+ <v>Fun when AccessMode is [read] = fun(read2, {UserPrivate,Size})->...;
+ (position,{UserPrivate,Position})->...;
+ (close, UserPrivate)->...
+ end
+ </v>
+ <v>TarDescriptor = term()</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc>
+ <p>The <c>Fun</c> is the definition of what to do when the different
+ storage operations functions are to be called from the higher tar
+ handling functions (<c>add/3</c>, <c>add/4</c>, <c>close/1</c>...).
+ </p>
+ <p>The <c>Fun</c> 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 <c>Fun(Op,{UserPrivate,Parameters...})</c> where <c>Op</c> is the operation name,
+ <c>UserPrivate</c> is the term passed as the first argument to <c>init/1</c> and
+ <c>Parameters...</c> are the data added by the tar function to be passed down to
+ the storage handling function.
+ </p>
+ <p>The parameter <c>UserPrivate</c> is typically the result of opening a low level
+ structure like a file descriptor, a sftp channel id or such. The different <c>Fun</c>
+ clauses operates on that very term.
+ </p>
+ <p>The fun clauses parameter lists are:
+ <taglist>
+ <tag><c>(write, {UserPrivate,DataToWrite})</c></tag>
+ <item>Write the term <c>DataToWrite</c> using <c>UserPrivate</c></item>
+ <tag><c>(close, UserPrivate)</c></tag>
+ <item>Close the access.</item>
+ <tag><c>(read2, {UserPrivate,Size})</c></tag>
+ <item>Read using <c>UserPrivate</c> but only <c>Size</c> bytes. Note that there is
+ only an arity-2 read function, not an arity-1
+ </item>
+ <tag><c> (position,{UserPrivate,Position})</c></tag>
+ <item>Sets the position of <c>UserPrivate</c> as defined for files in <seealso marker="kernel:file#position-2">file:position/2</seealso></item>
+ <tag><c></c></tag>
+ <item></item>
+ </taglist>
+ </p>
+ <p>A complete <c>Fun</c> parameter for reading and writing on files using the
+ <seealso marker="kernel:file">file module</seealso> could be:
+ </p>
+ <code type="none">
+ 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
+ </code>
+ <p>where <c>Fd</c> was given to the <c>init/3</c> function as:</p>
+ <code>
+ {ok,Fd} = file:open(Name,...).
+ {ok,TarDesc} = erl_tar:init(Fd, [write], ExampleFun),
+ </code>
+ <p>The <c>TarDesc</c> is then used:</p>
+ <code>
+ erl_tar:add(TarDesc, SomeValueIwantToAdd, FileNameInTarFile),
+ ....,
+ erl_tar:close(TarDesc)
+ </code>
+ <p>When the erl_tar core wants to e.g. write a piece of Data, it would call
+ <c>ExampleFun(write,{UserPrivate,Data})</c>.
+ </p>
+ <note>
+ <p>The example above with <c>file</c> module operations is not necessary to
+ use directly since that is what the <seealso marker="#open">open</seealso> function
+ in principle does.
+ </p>
+ </note>
+ <warning>
+ <p>The <c>TarDescriptor</c> term is not a file descriptor.
+ You should not rely on the specific contents of the <c>TarDescriptor</c>
+ term, as it may change in future versions as more features are added
+ to the <c>erl_tar</c> module.</p>
+ </warning>
+ </desc>
+ </func>
+
<func>
<name>table(Name) -> RetValue</name>
<fsummary>Retrieve the name of all files in a tar file</fsummary>
diff --git a/lib/stdlib/doc/src/io_protocol.xml b/lib/stdlib/doc/src/io_protocol.xml
index 9328704e11..21da404c35 100644
--- a/lib/stdlib/doc/src/io_protocol.xml
+++ b/lib/stdlib/doc/src/io_protocol.xml
@@ -49,7 +49,7 @@ current I/O-protocol.</p>
<p>The original I/O-protocol was simple and flexible. Demands for spacial
and execution time efficiency has triggered extensions to the protocol
over the years, making the protocol larger and somewhat less easy to
-implement than the original. It can certainly be argumented that the
+implement than the original. It can certainly be argued that the
current protocol is too complex, but this text describes how it looks
today, not how it should have looked.</p>
@@ -76,10 +76,11 @@ the server eventually sends a corresponding <c>io_reply</c> tuple.</p>
the I/O server sends the IO reply to.</item>
<item><c>ReplyAs</c> can be any datum and is returned in the corresponding
-<c>io_reply</c>. The <seealso marker="stdlib:io">io</seealso> module simply uses the pid()
-of the I/O server as the <c>ReplyAs</c> datum, but a more complicated client
+<c>io_reply</c>. The <seealso marker="stdlib:io">io</seealso> module monitors
+the I/O server, and uses the monitor reference as the <c>ReplyAs</c> datum.
+A more complicated client
could have several outstanding I/O requests to the same I/O server and
-would then use i.e. a <c>reference()</c> or something else to differentiate among
+would then use different references (or something else) to differentiate among
the incoming IO replies. The <c>ReplyAs</c> element should be considered
opaque by the I/O server. Note that the <c>pid()</c> of the I/O server is not
explicitly present in the <c>io_reply</c> tuple. The reply can be sent from any
diff --git a/lib/stdlib/doc/src/maps.xml b/lib/stdlib/doc/src/maps.xml
index 64229fa8d3..f766c843be 100644
--- a/lib/stdlib/doc/src/maps.xml
+++ b/lib/stdlib/doc/src/maps.xml
@@ -330,7 +330,7 @@ false</code>
<code type="none">
> Map = #{42 => value_three,1337 => "value two","a" => 1},
Ks = ["a",42,"other key"],
- maps:without(Ks,Map).
+ maps:with(Ks,Map).
#{42 => value_three,"a" => 1}</code>
</desc>
</func>
diff --git a/lib/stdlib/doc/src/string.xml b/lib/stdlib/doc/src/string.xml
index c96cc95a44..b05d5cbc08 100644
--- a/lib/stdlib/doc/src/string.xml
+++ b/lib/stdlib/doc/src/string.xml
@@ -4,7 +4,7 @@
<erlref>
<header>
<copyright>
- <year>1996</year><year>2013</year>
+ <year>1996</year><year>2014</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -124,6 +124,10 @@
<code type="none">
> tokens("abc defxxghix jkl", "x ").
["abc", "def", "ghi", "jkl"] </code>
+ <p>Note that, as shown in the example above, two or more
+ adjacent separator characters in <c><anno>String</anno></c>
+ will be treated as one. That is, there will not be any empty
+ strings in the resulting list of tokens.</p>
</desc>
</func>
<func>
diff --git a/lib/stdlib/doc/src/unicode_usage.xml b/lib/stdlib/doc/src/unicode_usage.xml
index bebfbd4514..29b8940c62 100644
--- a/lib/stdlib/doc/src/unicode_usage.xml
+++ b/lib/stdlib/doc/src/unicode_usage.xml
@@ -50,12 +50,8 @@
encoded files in several circumstances. Most notable is the support
for UTF-8 in files read by <c>file:consult/1</c>, release handler support
for UTF-8 and more support for Unicode character sets in the
- I/O-system.</p>
-
- <p>In Erlang/OTP 17.0, the encoding default for Erlang source files was
- switched to UTF-8 and in Erlang/OTP 18.0 Erlang will support atoms in the full
- Unicode range, meaning full Unicode function and module
- names</p>
+ I/O-system. In Erlang/OTP 17.0, the encoding default for Erlang source files was
+ switched to UTF-8.</p>
<p>This guide outlines the current Unicode support and gives a couple
of recipes for working with Unicode data.</p>
@@ -289,8 +285,8 @@
<tag>The language</tag>
<item>Having the source code in UTF-8 also allows you to write
string literals containing Unicode characters with code points &gt;
- 255, although atoms, module names and function names will be
- restricted to the ISO-Latin-1 range until the Erlang/OTP 18.0 release. Binary
+ 255, although atoms, module names and function names are
+ restricted to the ISO-Latin-1 range. Binary
literals where you use the <c>/utf8</c> type, can also be
expressed using Unicode characters &gt; 255. Having module names
using characters other than 7-bit ASCII can cause trouble on
@@ -385,8 +381,7 @@ external_charlist() = maybe_improper_list(char() |
using characters from the ISO-latin-1 character set and atoms are
restricted to the same ISO-latin-1 range. These restrictions in the
language are of course independent of the encoding of the source
- file. Erlang/OTP 18.0 is expected to handle functions named in
- Unicode as well as Unicode atoms.</p>
+ file.</p>
<section>
<title>Bit-syntax</title>
<p>The bit-syntax contains types for coping with binary data in the