aboutsummaryrefslogtreecommitdiffstats
path: root/erts/doc
diff options
context:
space:
mode:
Diffstat (limited to 'erts/doc')
-rw-r--r--erts/doc/src/Makefile1
-rw-r--r--erts/doc/src/absform.xml2
-rw-r--r--erts/doc/src/alt_dist.xml4
-rw-r--r--erts/doc/src/book.xml4
-rw-r--r--erts/doc/src/communication.xml2
-rw-r--r--erts/doc/src/crash_dump.xml2
-rw-r--r--erts/doc/src/driver.xml4
-rw-r--r--erts/doc/src/driver_entry.xml6
-rw-r--r--erts/doc/src/epmd.xml4
-rw-r--r--erts/doc/src/erl.xml2
-rw-r--r--erts/doc/src/erl_dist_protocol.xml2
-rw-r--r--erts/doc/src/erl_driver.xml2
-rw-r--r--erts/doc/src/erl_ext_dist.xml2
-rw-r--r--erts/doc/src/erl_nif.xml4
-rw-r--r--erts/doc/src/erl_prim_loader.xml4
-rw-r--r--erts/doc/src/erlang.xml229
-rw-r--r--erts/doc/src/erlc.xml4
-rw-r--r--erts/doc/src/erlsrv.xml4
-rw-r--r--erts/doc/src/erts_alloc.xml2
-rw-r--r--erts/doc/src/escript.xml2
-rw-r--r--erts/doc/src/fascicules.xml2
-rw-r--r--erts/doc/src/inet_cfg.xml4
-rw-r--r--erts/doc/src/init.xml4
-rw-r--r--erts/doc/src/match_spec.xml4
-rw-r--r--erts/doc/src/notes_history.xml4
-rw-r--r--erts/doc/src/part.xml3
-rw-r--r--erts/doc/src/part_notes.xml4
-rw-r--r--erts/doc/src/part_notes_history.xml4
-rw-r--r--erts/doc/src/ref_man.xml2
-rw-r--r--erts/doc/src/run_erl.xml4
-rw-r--r--erts/doc/src/specs.xml2
-rw-r--r--erts/doc/src/start.xml4
-rw-r--r--erts/doc/src/start_erl.xml4
-rw-r--r--erts/doc/src/time_correction.xml274
-rw-r--r--erts/doc/src/tty.xml4
-rw-r--r--erts/doc/src/werl.xml4
-rw-r--r--erts/doc/src/zlib.xml4
37 files changed, 501 insertions, 116 deletions
diff --git a/erts/doc/src/Makefile b/erts/doc/src/Makefile
index 89d7c85a86..d4c6fe67d2 100644
--- a/erts/doc/src/Makefile
+++ b/erts/doc/src/Makefile
@@ -78,6 +78,7 @@ XML_CHAPTER_FILES = \
erl_ext_dist.xml \
erl_dist_protocol.xml \
communication.xml \
+ time_correction.xml \
notes.xml \
notes_history.xml
diff --git a/erts/doc/src/absform.xml b/erts/doc/src/absform.xml
index e512c19e05..55aef9f8ab 100644
--- a/erts/doc/src/absform.xml
+++ b/erts/doc/src/absform.xml
@@ -1,4 +1,4 @@
-<?xml version="1.0" encoding="latin1" ?>
+<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE chapter SYSTEM "chapter.dtd">
<chapter>
diff --git a/erts/doc/src/alt_dist.xml b/erts/doc/src/alt_dist.xml
index 038950b54d..e4912576f7 100644
--- a/erts/doc/src/alt_dist.xml
+++ b/erts/doc/src/alt_dist.xml
@@ -1,10 +1,10 @@
-<?xml version="1.0" encoding="latin1" ?>
+<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE chapter SYSTEM "chapter.dtd">
<chapter>
<header>
<copyright>
- <year>2000</year><year>2011</year>
+ <year>2000</year><year>2013</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
diff --git a/erts/doc/src/book.xml b/erts/doc/src/book.xml
index 00a2888685..dc02edc5c6 100644
--- a/erts/doc/src/book.xml
+++ b/erts/doc/src/book.xml
@@ -1,10 +1,10 @@
-<?xml version="1.0" encoding="latin1" ?>
+<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE book SYSTEM "book.dtd">
<book xmlns:xi="http://www.w3.org/2001/XInclude">
<header titlestyle="normal">
<copyright>
- <year>1997</year><year>2009</year>
+ <year>1997</year><year>2013</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
diff --git a/erts/doc/src/communication.xml b/erts/doc/src/communication.xml
index 61a9b0e716..02040c9edb 100644
--- a/erts/doc/src/communication.xml
+++ b/erts/doc/src/communication.xml
@@ -1,4 +1,4 @@
-<?xml version="1.0" encoding="latin1" ?>
+<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE chapter SYSTEM "chapter.dtd">
<chapter>
diff --git a/erts/doc/src/crash_dump.xml b/erts/doc/src/crash_dump.xml
index 8f5515baca..c59741f250 100644
--- a/erts/doc/src/crash_dump.xml
+++ b/erts/doc/src/crash_dump.xml
@@ -1,4 +1,4 @@
-<?xml version="1.0" encoding="latin1" ?>
+<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE chapter SYSTEM "chapter.dtd">
<chapter>
diff --git a/erts/doc/src/driver.xml b/erts/doc/src/driver.xml
index 52283879c7..616703fdef 100644
--- a/erts/doc/src/driver.xml
+++ b/erts/doc/src/driver.xml
@@ -1,10 +1,10 @@
-<?xml version="1.0" encoding="latin1" ?>
+<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE chapter SYSTEM "chapter.dtd">
<chapter>
<header>
<copyright>
- <year>2001</year><year>2011</year>
+ <year>2001</year><year>2013</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
diff --git a/erts/doc/src/driver_entry.xml b/erts/doc/src/driver_entry.xml
index c37138e7b1..48dfcb09b1 100644
--- a/erts/doc/src/driver_entry.xml
+++ b/erts/doc/src/driver_entry.xml
@@ -1,10 +1,10 @@
-<?xml version="1.0" encoding="latin1" ?>
+<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE cref SYSTEM "cref.dtd">
<cref>
<header>
<copyright>
- <year>2001</year><year>2012</year>
+ <year>2001</year><year>2013</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
@@ -110,6 +110,8 @@
<p>When the driver has passed the <c>driver_entry</c> over to
the emulator, the driver is <em>not</em> allowed to modify the
<c>driver_entry</c>.</p>
+ <p>If compiling a driver for static inclusion via --enable-static-drivers you
+ have to define STATIC_ERLANG_DRIVER before the DRIVER_INIT declaration.</p>
<note>
<p>Do <em>not</em> declare the <c>driver_entry</c> <c>const</c>. This since the emulator needs to
modify the <c>handle</c>, and the <c>handle2</c>
diff --git a/erts/doc/src/epmd.xml b/erts/doc/src/epmd.xml
index 3e7005410f..963d35c3c8 100644
--- a/erts/doc/src/epmd.xml
+++ b/erts/doc/src/epmd.xml
@@ -1,10 +1,10 @@
-<?xml version="1.0" encoding="latin1" ?>
+<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE comref SYSTEM "comref.dtd">
<comref>
<header>
<copyright>
- <year>1996</year><year>2011</year>
+ <year>1996</year><year>2013</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
diff --git a/erts/doc/src/erl.xml b/erts/doc/src/erl.xml
index 528a2d95aa..bf0d132955 100644
--- a/erts/doc/src/erl.xml
+++ b/erts/doc/src/erl.xml
@@ -1,4 +1,4 @@
-<?xml version="1.0" encoding="latin1" ?>
+<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE comref SYSTEM "comref.dtd">
<comref>
diff --git a/erts/doc/src/erl_dist_protocol.xml b/erts/doc/src/erl_dist_protocol.xml
index 84f4be208d..890293d802 100644
--- a/erts/doc/src/erl_dist_protocol.xml
+++ b/erts/doc/src/erl_dist_protocol.xml
@@ -1,4 +1,4 @@
-<?xml version="1.0" encoding="iso-8859-1" ?>
+<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE chapter SYSTEM "chapter.dtd">
<chapter>
diff --git a/erts/doc/src/erl_driver.xml b/erts/doc/src/erl_driver.xml
index c055d1ca9e..b453a4861e 100644
--- a/erts/doc/src/erl_driver.xml
+++ b/erts/doc/src/erl_driver.xml
@@ -1,4 +1,4 @@
-<?xml version="1.0" encoding="latin1" ?>
+<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE cref SYSTEM "cref.dtd">
<cref>
diff --git a/erts/doc/src/erl_ext_dist.xml b/erts/doc/src/erl_ext_dist.xml
index 64a201cc8f..f91ed78122 100644
--- a/erts/doc/src/erl_ext_dist.xml
+++ b/erts/doc/src/erl_ext_dist.xml
@@ -1,4 +1,4 @@
-<?xml version="1.0" encoding="iso-8859-1" ?>
+<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE chapter SYSTEM "chapter.dtd">
<chapter>
diff --git a/erts/doc/src/erl_nif.xml b/erts/doc/src/erl_nif.xml
index 864b91946a..7ac8181d47 100644
--- a/erts/doc/src/erl_nif.xml
+++ b/erts/doc/src/erl_nif.xml
@@ -1,4 +1,4 @@
-<?xml version="1.0" encoding="latin1" ?>
+<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE cref SYSTEM "cref.dtd">
<cref>
@@ -330,6 +330,8 @@ ok
<c>upgrade</c> will be called to initialize the library.
<c>unload</c> is called to release the library. They are all
described individually below.</p>
+ <p>If compiling a nif for static inclusion via --enable-static-nifs you
+ have to define STATIC_ERLANG_NIF before the ERL_NIF_INIT declaration.</p>
</item>
<tag><marker id="load"/>int (*load)(ErlNifEnv* env, void** priv_data, ERL_NIF_TERM load_info)</tag>
diff --git a/erts/doc/src/erl_prim_loader.xml b/erts/doc/src/erl_prim_loader.xml
index 9f5b3f385b..6751deda4d 100644
--- a/erts/doc/src/erl_prim_loader.xml
+++ b/erts/doc/src/erl_prim_loader.xml
@@ -1,10 +1,10 @@
-<?xml version="1.0" encoding="latin1" ?>
+<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE erlref SYSTEM "erlref.dtd">
<erlref>
<header>
<copyright>
- <year>1996</year><year>2011</year>
+ <year>1996</year><year>2013</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml
index e3ef48a6c1..711473afd2 100644
--- a/erts/doc/src/erlang.xml
+++ b/erts/doc/src/erlang.xml
@@ -1,4 +1,4 @@
-<?xml version="1.0" encoding="latin1" ?>
+<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE erlref SYSTEM "erlref.dtd">
<erlref>
@@ -501,16 +501,87 @@
<name name="check_process_code" arity="2"/>
<fsummary>Check if a process is executing old code for a module</fsummary>
<desc>
- <p>Returns <c>true</c> if the process <c><anno>Pid</anno></c> is executing
- old code for <c><anno>Module</anno></c>. That is, if the current call of
- the process executes old code for this module, or if the
- process has references to old code for this module, or if the
- process contains funs that references old code for this
- module. Otherwise, it returns <c>false</c>.</p>
- <pre>
-> <input>check_process_code(Pid, lists).</input>
-false</pre>
+ <p>The same as
+ <seealso marker="#check_process_code/3"><c>erlang:check_process_code(<anno>Pid</anno>,
+ <anno>Module</anno>, [])</c></seealso>.</p>
+ </desc>
+ </func>
+ <func>
+ <name name="check_process_code" arity="3"/>
+ <fsummary>Check if a process is executing old code for a module</fsummary>
+ <desc>
+ <p>Check if the node local process identified by <c><anno>Pid</anno></c>
+ is executing old code for <c><anno>Module</anno></c>.</p>
+ <p>Currently available <c><anno>Option</anno>s</c>:</p>
+ <taglist>
+ <tag><c>{allow_gc, boolean()}</c></tag>
+ <item>
+ Determines if garbage collection is allowed when performing
+ the operation. If <c>{allow_gc, false}</c> is passed, and
+ a garbage collection is needed in order to determine the
+ result of the operation, the operation will be aborted
+ (see information on <c><anno>CheckResult</anno></c> below).
+ The default is to allow garbage collection, i.e.,
+ <c>{allow_gc, true}</c>.
+ </item>
+ <tag><c>{async, RequestId}</c></tag>
+ <item>
+ The <c>check_process_code/3</c> function will return
+ the value <c>async</c> immediately after the request
+ has been sent. When the request has been processed, the
+ process that called this function will be passed a
+ message on the form:<br/>
+ <c>{check_process_code, <anno>RequestId</anno>, <anno>CheckResult</anno>}</c>.
+ </item>
+ </taglist>
+ <p>If <c><anno>Pid</anno></c> equals <c>self()</c>, and
+ no <c>async</c> option has been passed, the operation will
+ be performed at once. In all other cases a request for
+ the operation will be sent to the process identified by
+ <c><anno>Pid</anno></c>, and will be handled when
+ appropriate. If no <c>async</c> option has been passed,
+ the caller will block until <c><anno>CheckResult</anno></c>
+ is available and can be returned.</p>
+ <p><c><anno>CheckResult</anno></c> informs about the result of
+ the request:</p>
+ <taglist>
+ <tag><c>true</c></tag>
+ <item>
+ The process identified by <c><anno>Pid</anno></c> is
+ executing old code for <c><anno>Module</anno></c>.
+ That is, the current call of the process executes old
+ code for this module, or the process has references
+ to old code for this module, or the process contains
+ funs that references old code for this module.
+ </item>
+ <tag><c>false</c></tag>
+ <item>
+ The process identified by <c><anno>Pid</anno></c> is
+ not executing old code for <c><anno>Module</anno></c>.
+ </item>
+ <tag><c>aborted</c></tag>
+ <item>
+ The operation was aborted since the process needed to
+ be garbage collected in order to determine the result
+ of the operation, and the operation was requested
+ by passing the <c>{allow_gc, false}</c> option.</item>
+ </taglist>
<p>See also <seealso marker="kernel:code">code(3)</seealso>.</p>
+ <p>Failures:</p>
+ <taglist>
+ <tag><c>badarg</c></tag>
+ <item>
+ If <c><anno>Pid</anno></c> is not a node local process identifier.
+ </item>
+ <tag><c>badarg</c></tag>
+ <item>
+ If <c><anno>Module</anno></c> is not an atom.
+ </item>
+ <tag><c>badarg</c></tag>
+ <item>
+ If <c><anno>OptionList</anno></c> is not a valid list of options.
+ </item>
+ </taglist>
</desc>
</func>
<func>
@@ -1197,20 +1268,74 @@ true
that the spontaneous garbage collection will occur too late
or not at all. Improper use may seriously degrade system
performance.</p>
- <p>Compatibility note: In versions of OTP prior to R7,
- the garbage collection took place at the next context switch,
- not immediately. To force a context switch after a call to
- <c>erlang:garbage_collect()</c>, it was sufficient to make
- any function call.</p>
</desc>
</func>
<func>
<name name="garbage_collect" arity="1"/>
- <fsummary>Force an immediate garbage collection of a process</fsummary>
+ <fsummary>Garbage collect a process</fsummary>
<desc>
- <p>Works like <c>erlang:garbage_collect()</c> but on any
- process. The same caveats apply. Returns <c>false</c> if
- <c><anno>Pid</anno></c> refers to a dead process; <c>true</c> otherwise.</p>
+ <p>The same as
+ <seealso marker="#garbage_collect/2"><c>garbage_collect(<anno>Pid</anno>, [])</c></seealso>.</p>
+ </desc>
+ </func>
+ <func>
+ <name name="garbage_collect" arity="2"/>
+ <fsummary>Garbage collect a process</fsummary>
+ <desc>
+ <p>Garbage collect the node local process identified by
+ <c><anno>Pid</anno></c>.</p>
+ <p>Currently available <c><anno>Option</anno></c>s:</p>
+ <taglist>
+ <tag><c>{async, RequestId}</c></tag>
+ <item>
+ The <c>garbage_collect/2</c> function will return
+ the value <c>async</c> immediately after the request
+ has been sent. When the request has been processed, the
+ process that called this function will be passed a
+ message on the form:<br/>
+ <c>{garbage_collect, <anno>RequestId</anno>, <anno>GCResult</anno>}</c>.
+ </item>
+ </taglist>
+ <p>If <c><anno>Pid</anno></c> equals <c>self()</c>, and
+ no <c>async</c> option has been passed, the garbage
+ collection will be performed at once, i.e. the same as
+ calling
+ <seealso marker="#garbage_collect/0">garbage_collect/0</seealso>.
+ In all other cases a request for garbage collection will
+ be sent to the process identified by <c><anno>Pid</anno></c>,
+ and will be handled when appropriate. If no <c>async</c>
+ option has been passed, the caller will block until
+ <c><anno>GCResult</anno></c> is available and can be
+ returned.</p>
+ <p><c><anno>GCResult</anno></c> informs about the result of
+ the garbage collection request:</p>
+ <taglist>
+ <tag><c>true</c></tag>
+ <item>
+ The process identified by <c><anno>Pid</anno></c> has
+ been garbage collected.
+ </item>
+ <tag><c>false</c></tag>
+ <item>
+ No garbage collection was performed. This since the
+ the process identified by <c><anno>Pid</anno></c>
+ terminated before the request could be satisfied.
+ </item>
+ </taglist>
+ <p>Note that the same caveats as for
+ <seealso marker="#garbage_collect/0">garbage_collect/0</seealso>
+ apply.</p>
+ <p>Failures:</p>
+ <taglist>
+ <tag><c>badarg</c></tag>
+ <item>
+ If <c><anno>Pid</anno></c> is not a node local process identifier.
+ </item>
+ <tag><c>badarg</c></tag>
+ <item>
+ If <c><anno>OptionList</anno></c> is not a valid list of options.
+ </item>
+ </taglist>
</desc>
</func>
<func>
@@ -2613,7 +2738,28 @@ os_prompt% </pre>
<desc>
<p>Returns a port identifier as the result of opening a
new Erlang port. A port can be seen as an external Erlang
- process. <c><anno>PortName</anno></c> is one of the following:</p>
+ process.
+ </p>
+ <p>The name of the executable as well as the arguments
+ given in <c>cd</c>, <c>env</c>, <c>args</c> and <c>arg0</c> is subject to
+ Unicode file name translation if the system is running
+ in Unicode file name mode. To avoid
+ translation or force i.e. UTF-8, supply the executable
+ and/or arguments as a binary in the correct
+ encoding. See the <seealso
+ marker="kernel:file">file</seealso> module, the
+ <seealso marker="kernel:file#native_name_encoding/0">
+ file:native_name_encoding/0</seealso> function and the
+ <seealso marker="stdlib:unicode_usage">stdlib users guide
+ </seealso> for details.</p>
+
+ <note><p>The characters in the name (if given as a list)
+ can only be &gt; 255 if the Erlang VM is started in
+ Unicode file name translation mode, otherwise the name
+ of the executable is limited to the ISO-latin-1
+ character set.</p></note>
+
+ <p><c><anno>PortName</anno></c> is one of the following:</p>
<taglist>
<tag><c>{spawn, <anno>Command</anno>}</c></tag>
<item>
@@ -2668,25 +2814,6 @@ os_prompt% </pre>
executed, the appropriate command interpreter will
implicitly be invoked, but there will still be no
command argument expansion or implicit PATH search.</p>
-
- <p>The name of the executable as well as the arguments
- given in <c>args</c> and <c>arg0</c> is subject to
- Unicode file name translation if the system is running
- in Unicode file name mode. To avoid
- translation or force i.e. UTF-8, supply the executable
- and/or arguments as a binary in the correct
- encoding. See the <seealso
- marker="kernel:file">file</seealso> module, the
- <seealso marker="kernel:file#native_name_encoding/0">
- file:native_name_encoding/0</seealso> function and the
- <seealso marker="stdlib:unicode_usage">stdlib users guide
- </seealso> for details.</p>
-
- <note><p>The characters in the name (if given as a list)
- can only be &gt; 255 if the Erlang VM is started in
- Unicode file name translation mode, otherwise the name
- of the executable is limited to the ISO-latin-1
- character set.</p></note>
<p>If the <c><anno>FileName</anno></c> cannot be run, an error
exception, with the posix error code as the reason, is
@@ -2762,11 +2889,7 @@ os_prompt% </pre>
strings. The one exception is <c><anno>Val</anno></c> being the atom
<c>false</c> (in analogy with <c>os:getenv/1</c>), which
removes the environment variable.
- </p>
- <p>If Unicode filename encoding is in effect (see the <seealso
- marker="erts:erl#file_name_encoding">erl manual
- page</seealso>), the strings (both <c>Name</c> and
- <c>Value</c>) may contain characters with codepoints > 255.</p>
+ </p>
</item>
<tag><c>{args, [ string() | binary() ]}</c></tag>
<item>
@@ -2794,21 +2917,6 @@ os_prompt% </pre>
should not be given in this list. The proper executable name will
automatically be used as argv[0] where applicable.</p>
- <p>When the Erlang VM is running in Unicode file name
- mode, the arguments can contain any Unicode characters and
- will be translated into whatever is appropriate on the
- underlying OS, which means UTF-8 for all platforms except
- Windows, which has other (more transparent) ways of
- dealing with Unicode arguments to programs. To avoid
- Unicode translation of arguments, they can be supplied as
- binaries in whatever encoding is deemed appropriate.</p>
-
- <note><p>The characters in the arguments (if given as a
- list of characters) can only be &gt; 255 if the Erlang
- VM is started in Unicode file name mode,
- otherwise the arguments are limited to the
- ISO-latin-1 character set.</p></note>
-
<p>If one, for any reason, wants to explicitly set the
program name in the argument vector, the <c>arg0</c>
option can be used.</p>
@@ -2824,9 +2932,6 @@ os_prompt% </pre>
responds to this is highly system dependent and no specific
effect is guaranteed.</p>
- <p>The unicode file name translation rules of the
- <c>args</c> option apply to this option as well.</p>
-
</item>
<tag><c>exit_status</c></tag>
diff --git a/erts/doc/src/erlc.xml b/erts/doc/src/erlc.xml
index 81dffe45cf..10cab344b0 100644
--- a/erts/doc/src/erlc.xml
+++ b/erts/doc/src/erlc.xml
@@ -1,10 +1,10 @@
-<?xml version="1.0" encoding="latin1" ?>
+<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE comref SYSTEM "comref.dtd">
<comref>
<header>
<copyright>
- <year>1997</year><year>2012</year>
+ <year>1997</year><year>2013</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
diff --git a/erts/doc/src/erlsrv.xml b/erts/doc/src/erlsrv.xml
index 365ae21d39..71cee714a5 100644
--- a/erts/doc/src/erlsrv.xml
+++ b/erts/doc/src/erlsrv.xml
@@ -1,10 +1,10 @@
-<?xml version="1.0" encoding="latin1" ?>
+<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE comref SYSTEM "comref.dtd">
<comref>
<header>
<copyright>
- <year>1998</year><year>2012</year>
+ <year>1998</year><year>2013</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
diff --git a/erts/doc/src/erts_alloc.xml b/erts/doc/src/erts_alloc.xml
index 49ee740a73..fffa9f594c 100644
--- a/erts/doc/src/erts_alloc.xml
+++ b/erts/doc/src/erts_alloc.xml
@@ -1,4 +1,4 @@
-<?xml version="1.0" encoding="latin1" ?>
+<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE cref SYSTEM "cref.dtd">
<cref>
diff --git a/erts/doc/src/escript.xml b/erts/doc/src/escript.xml
index 9e2a87dde6..180447cac4 100644
--- a/erts/doc/src/escript.xml
+++ b/erts/doc/src/escript.xml
@@ -1,4 +1,4 @@
-<?xml version="1.0" encoding="latin1" ?>
+<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE comref SYSTEM "comref.dtd">
<comref>
diff --git a/erts/doc/src/fascicules.xml b/erts/doc/src/fascicules.xml
index cae197a516..1c371bd9c8 100644
--- a/erts/doc/src/fascicules.xml
+++ b/erts/doc/src/fascicules.xml
@@ -1,4 +1,4 @@
-<?xml version="1.0" encoding="latin1" ?>
+<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE fascicules SYSTEM "fascicules.dtd">
<fascicules>
diff --git a/erts/doc/src/inet_cfg.xml b/erts/doc/src/inet_cfg.xml
index 2a033c037c..d40bc5f9ee 100644
--- a/erts/doc/src/inet_cfg.xml
+++ b/erts/doc/src/inet_cfg.xml
@@ -1,10 +1,10 @@
-<?xml version="1.0" encoding="latin1" ?>
+<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE chapter SYSTEM "chapter.dtd">
<chapter>
<header>
<copyright>
- <year>2004</year><year>2010</year>
+ <year>2004</year><year>2013</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
diff --git a/erts/doc/src/init.xml b/erts/doc/src/init.xml
index d5c43f6e57..09b5493341 100644
--- a/erts/doc/src/init.xml
+++ b/erts/doc/src/init.xml
@@ -1,10 +1,10 @@
-<?xml version="1.0" encoding="latin1" ?>
+<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE erlref SYSTEM "erlref.dtd">
<erlref>
<header>
<copyright>
- <year>1996</year><year>2011</year>
+ <year>1996</year><year>2013</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
diff --git a/erts/doc/src/match_spec.xml b/erts/doc/src/match_spec.xml
index bdcf9c3816..334b47d34c 100644
--- a/erts/doc/src/match_spec.xml
+++ b/erts/doc/src/match_spec.xml
@@ -1,10 +1,10 @@
-<?xml version="1.0" encoding="latin1" ?>
+<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE chapter SYSTEM "chapter.dtd">
<chapter>
<header>
<copyright>
- <year>1999</year><year>2012</year>
+ <year>1999</year><year>2013</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
diff --git a/erts/doc/src/notes_history.xml b/erts/doc/src/notes_history.xml
index cc3b938c86..4420311912 100644
--- a/erts/doc/src/notes_history.xml
+++ b/erts/doc/src/notes_history.xml
@@ -1,10 +1,10 @@
-<?xml version="1.0" encoding="latin1" ?>
+<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE chapter SYSTEM "chapter.dtd">
<chapter>
<header>
<copyright>
- <year>2006</year><year>2009</year>
+ <year>2006</year><year>2013</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
diff --git a/erts/doc/src/part.xml b/erts/doc/src/part.xml
index fa50329cad..7b17b5b551 100644
--- a/erts/doc/src/part.xml
+++ b/erts/doc/src/part.xml
@@ -1,4 +1,4 @@
-<?xml version="1.0" encoding="latin1" ?>
+<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE part SYSTEM "part.dtd">
<part xmlns:xi="http://www.w3.org/2001/XInclude">
@@ -32,6 +32,7 @@
<p>The Erlang Runtime System Application <em>ERTS</em>.</p>
</description>
<xi:include href="communication.xml"/>
+ <xi:include href="time_correction.xml"/>
<xi:include href="match_spec.xml"/>
<xi:include href="crash_dump.xml"/>
<xi:include href="alt_dist.xml"/>
diff --git a/erts/doc/src/part_notes.xml b/erts/doc/src/part_notes.xml
index 4f183999e6..b5c8f0af09 100644
--- a/erts/doc/src/part_notes.xml
+++ b/erts/doc/src/part_notes.xml
@@ -1,10 +1,10 @@
-<?xml version="1.0" encoding="latin1" ?>
+<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE part SYSTEM "part.dtd">
<part xmlns:xi="http://www.w3.org/2001/XInclude">
<header>
<copyright>
- <year>2004</year><year>2009</year>
+ <year>2004</year><year>2013</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
diff --git a/erts/doc/src/part_notes_history.xml b/erts/doc/src/part_notes_history.xml
index 1b9bcca773..a99fa4a17f 100644
--- a/erts/doc/src/part_notes_history.xml
+++ b/erts/doc/src/part_notes_history.xml
@@ -1,10 +1,10 @@
-<?xml version="1.0" encoding="latin1" ?>
+<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE part SYSTEM "part.dtd">
<part xmlns:xi="http://www.w3.org/2001/XInclude">
<header>
<copyright>
- <year>2006</year><year>2009</year>
+ <year>2006</year><year>2013</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
diff --git a/erts/doc/src/ref_man.xml b/erts/doc/src/ref_man.xml
index e55923c344..8ed7090a61 100644
--- a/erts/doc/src/ref_man.xml
+++ b/erts/doc/src/ref_man.xml
@@ -1,4 +1,4 @@
-<?xml version="1.0" encoding="latin1" ?>
+<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE application SYSTEM "application.dtd">
<application xmlns:xi="http://www.w3.org/2001/XInclude">
diff --git a/erts/doc/src/run_erl.xml b/erts/doc/src/run_erl.xml
index c9784299b3..684f7b1ddd 100644
--- a/erts/doc/src/run_erl.xml
+++ b/erts/doc/src/run_erl.xml
@@ -1,10 +1,10 @@
-<?xml version="1.0" encoding="latin1" ?>
+<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE comref SYSTEM "comref.dtd">
<comref>
<header>
<copyright>
- <year>1999</year><year>2011</year>
+ <year>1999</year><year>2013</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
diff --git a/erts/doc/src/specs.xml b/erts/doc/src/specs.xml
index e5c2f4783f..41a3984659 100644
--- a/erts/doc/src/specs.xml
+++ b/erts/doc/src/specs.xml
@@ -1,4 +1,4 @@
-<?xml version="1.0" encoding="latin1" ?>
+<?xml version="1.0" encoding="utf-8" ?>
<specs xmlns:xi="http://www.w3.org/2001/XInclude">
<xi:include href="../specs/specs_erl_prim_loader.xml"/>
<xi:include href="../specs/specs_erlang.xml"/>
diff --git a/erts/doc/src/start.xml b/erts/doc/src/start.xml
index 5dc33deb2a..e9a5714f93 100644
--- a/erts/doc/src/start.xml
+++ b/erts/doc/src/start.xml
@@ -1,10 +1,10 @@
-<?xml version="1.0" encoding="latin1" ?>
+<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE comref SYSTEM "comref.dtd">
<comref>
<header>
<copyright>
- <year>1999</year><year>2009</year>
+ <year>1999</year><year>2013</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
diff --git a/erts/doc/src/start_erl.xml b/erts/doc/src/start_erl.xml
index 92d87b095a..fe808f7737 100644
--- a/erts/doc/src/start_erl.xml
+++ b/erts/doc/src/start_erl.xml
@@ -1,10 +1,10 @@
-<?xml version="1.0" encoding="latin1" ?>
+<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE comref SYSTEM "comref.dtd">
<comref>
<header>
<copyright>
- <year>1998</year><year>2011</year>
+ <year>1998</year><year>2013</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
diff --git a/erts/doc/src/time_correction.xml b/erts/doc/src/time_correction.xml
new file mode 100644
index 0000000000..d52cc7f3e2
--- /dev/null
+++ b/erts/doc/src/time_correction.xml
@@ -0,0 +1,274 @@
+<?xml version="1.0" encoding="utf8" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+ <header>
+ <copyright>
+ <year>1999</year><year>2013</year>
+ <holder>Ericsson AB. All Rights Reserved.</holder>
+ </copyright>
+ <legalnotice>
+ The contents of this file are subject to the Erlang Public License,
+ Version 1.1, (the "License"); you may not use this file except in
+ compliance with the License. You should have received a copy of the
+ Erlang Public License along with this software. If not, it can be
+ retrieved online at http://www.erlang.org/.
+
+ Software distributed under the License is distributed on an "AS IS"
+ basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+ the License for the specific language governing rights and limitations
+ under the License.
+
+ </legalnotice>
+
+ <title>Time and time correction in Erlang</title>
+ <prepared>Patrik Nyblom</prepared>
+ <responsible></responsible>
+ <docno></docno>
+ <approved></approved>
+ <checked></checked>
+ <date>2013-08-28</date>
+ <rev>PA1</rev>
+ <file>time_correction.xml</file>
+ </header>
+ <p>Time is vital to an Erlang program and, more importantly, <em>correct</em>
+ time is vital to an Erlang program. As Erlang is a language with
+ soft real time properties and we have the possibility to express
+ time in our programs, the Virtual Machine and the language has to be
+ very careful about what is considered a correct point in time and in
+ how time functions behave.</p>
+
+ <p>In the beginning, Erlang was constructed assuming that the wall
+ clock time in the system showed a monotonic time moving forward at
+ exactly the same pace as the definition of time. That more or less
+ meant that an atomic clock (or better) was expected to be attached
+ to your hardware and that the hardware was then expected to be
+ locked away from any human (or unearthly) tinkering for all
+ eternity. While this might be a compelling thought, it's simply
+ never the case.</p>
+
+ <p>A "normal" modern computer can not keep time. Not on itself and
+ not unless you actually have a chip level atomic clock wired to
+ it. Time, as perceived by your computer, will normally need to be
+ corrected. Hence the NTP protocol that together with the ntpd
+ process will do it's best to keep your computers time in sync with
+ the "real" time in the universe. Between NTP corrections, usually a
+ less potent time-keeper than an atomic clock is used.</p>
+
+ <p>But NTP is not fail safe. The NTP server can be unavailable, the
+ ntp.conf can be wrongly configured or your computer may from time to
+ time be disconnected from the internet. Furthermore you can have a
+ user (or even system administrator) on your system that thinks the
+ right way to handle daylight saving time is to adjust the clock one
+ hour two times a year (a tip, that is not the right way to do
+ it...). To further complicate things, this user fetched your
+ software from the internet and has never ever thought about what's
+ the correct time as perceived by a computer. The user simply does
+ not care about keeping the wall clock in sync with the rest of the
+ universe. The user expects your program to have omnipotent knowledge
+ about the time.</p>
+
+ <p>Most programmers also expect time to be reliable, at least until
+ they realize that the wall clock time on their workstation is of by
+ a minute. Then they simply set it to the correct time, maybe or
+ maybe not in a smooth way. Most probably not in a smooth way.</p>
+
+ <p>The amount of problems that arise when you expect the wall clock
+ time on the system to always be correct may be immense. Therefore Erlang
+ introduced the "corrected estimate of time", or the "time
+ correction" many years ago. The time correction relies on the fact
+ that most operating systems have some kind of monotonic clock,
+ either a real time extension or some built in "tick counter" that is
+ independent of the wall clock settings. This counter may have
+ microsecond resolution or much less, but generally it has a drift
+ that is not to be ignored.</p>
+
+ <p>So we have this monotonic ticking and we have the wall clock
+ time. Two unreliable times that together can give us an estimate of
+ an actual wall clock time that does not jump around and that
+ monotonically moves forward. If the tick counter has a high
+ resolution, this is fairly easy to do, if the counter has a low
+ resolution, it's more expensive, but still doable down to
+ frequencies of 50-60 Hz (of the tick counter).</p>
+
+ <p>So the corrected time is the nearest approximation of an atomic
+ clock that is available on the computer. We want it to have the
+ following properties:</p>
+ <taglist>
+ <tag>Monotonic</tag>
+ <item>The clock should not move backwards</item>
+ <tag>Intervals should be near the truth</tag>
+ <item>We want the actual time (as measured by an atomic clock or
+ an astronomer) that passes between two time stamps, T1 and T2, to be as
+ near to T2 - T1 as possible.</item>
+ <tag>Tight coupling to the wall clock</tag>
+ <item>We want a timer that is to be fired when the wall clock
+ reaches a time in the future, to fire as near to that point in
+ time as possible</item>
+ </taglist>
+ <p>To meet all the criteria, we have to utilize both times in such a
+ way that Erlangs "corrected time" moves slightly slower or slightly
+ faster than the wall clock to get in sync with it. The word
+ "slightly" means a maximum of 1% difference to the wall clock time,
+ meaning that a sudden change in the wall clock of one minute, takes
+ 100 minutes to fix, by letting all "corrected time" move 1% slower
+ or faster.</p>
+
+ <p>Needless to say, correcting for a faulty handling of daylight
+ saving time may be disturbing to a user comparing wall clock
+ time to for example calendar:now_to_local_time(erlang:now()). But
+ calendar:now_to_local_time/1 is not supposed to be used for presenting wall
+ clock time to the user.</p>
+
+ <p>Time correction is not perfect, but it saves you from the havoc
+ of clocks jumping around, which would make timers in your program
+ fire far to late or far to early and could bring your whole system
+ to it's knees (or worse) just because someone detected a small error
+ in the wall clock time of the server where your program runs. So
+ while it might be confusing, it is still a really good feature of
+ Erlang and you should not throw it away using time functions which
+ may give you higher benchmark results, not unless you really know
+ what you're doing.</p>
+
+ <section>
+ <title>What does time correction mean in my system?</title>
+ <p>Time correction means that Erlang estimates a time from current
+ and previous settings of the wall clock, and it uses a fairly
+ exact tick counter to detect when the wall clock time has jumped
+ for some reason, slowly adjusting to the new value.</p>
+
+ <p>In practice, this means that the difference between two calls
+ to time corrected functions, like erlang:now(), might differ up to
+ one percent from the corresponding calls to non time corrected
+ functions (like os:timestamp()). Furthermore, if comparing
+ calendar:local_time/0 to calendar:now_to_local_time(erlang:now()),
+ you might temporarily see a difference, depending on how well kept your
+ system is.</p>
+
+ <p>It is important to understand that it is (to the program)
+ always unknown if it is the wall clock time that moves in the
+ wrong pace or the Erlang corrected time. The only way to determine
+ that, is to have an external source of universally correct time. If
+ some such source is available, the wall clock time can be kept
+ nearly perfect at all times, and no significant difference will be
+ detected between erlang:now/0's pace and the wall clock's.</p>
+
+ <p>Still, the time correction will mean that your system keeps
+ it's real time characteristics very well, even when the wall clock
+ is unreliable.</p>
+ </section>
+ <section>
+ <title>Where does Erlang use corrected time?</title>
+ <p>For all functionality where real time characteristics are
+ desirable, time correction is used. This basically means:</p>
+ <taglist>
+ <tag>erlang:now/0</tag>
+ <item>The infamous erlang:now/0 function uses time correction so
+ that differences between two "now-timestamps" will correspond to
+ other timeouts in the system. erlang:now/0 also holds other
+ properties, discussed later.</item>
+ <tag>receive ... after</tag>
+ <item>Timeouts on receive uses time correction to determine a
+ stable timeout interval.</item>
+ <tag>The timer module</tag>
+ <item>As the timer module uses other built in functions which
+ deliver corrected time, the timer module itself works with
+ corrected time.</item>
+ <tag>erlang:start_timer/3 and erlang:send_after/3</tag>
+ <item>The timer BIF's work with corrected time, so that they
+ will not fire prematurely or too late due to changes in the wall
+ clock time.</item>
+ </taglist>
+
+ <p>All other functionality in the system where erlang:now/0 or any
+ other time corrected functionality is used, will of course
+ automatically benefit from it, as long as it's not "optimized" to
+ use some other time stamp function (like os:timestamp/0).</p>
+
+ <p>Modules like calendar and functions like erlang:localtime/0 use
+ the wall clock time as it is currently set on the system. They
+ will not use corrected time. However, if you use a now-value and
+ convert it to local time, you will get a corrected local time
+ value, which may or may not be what you want. Typically older code
+ tend to use erlang:now/0 as a wall clock time, which is usually
+ correct (at least when testing), but might surprise you when
+ compared to other times in the system.</p>
+ </section>
+ <section>
+ <title>What is erlang:now/0 really?</title>
+ <p>erlang:now/0 is a function designed to serve multiple purposes
+ (or a multi-headed beast if you're a VM designer). It is expected
+ to hold the following properties:</p>
+ <taglist>
+ <tag>Monotonic</tag>
+ <item>erlang:now() never jumps backwards - it always moves
+ forward</item>
+ <tag>Interval correct</tag>
+ <item>The interval between two erlang:now() calls is expected to
+ correspond to the correct time in real life (as defined by an
+ atomic clock, or better)</item>
+ <tag>Absolute correctness</tag>
+ <item>The erlang:now/0 value should be possible to convert to an
+ absolute and correct date-time, corresponding to the real world
+ date and time (the wall clock)</item>
+ <tag>System correspondence</tag>
+ <item>The erlang:now/0 value converted to a date-time is
+ expected to correspond to times given by other programs on the
+ system (or by functions like os:timestamp/0)</item>
+ <tag>Unique</tag>
+ <item>No two calls to erlang:now on one Erlang node should
+ return the same value</item>
+ </taglist>
+ <p>All these requirements are possible to uphold at the same
+ time if (and only if):</p>
+ <taglist>
+ <tag>The wall clock time of the system is perfect</tag>
+ <item>The system (Operating System) time needs to be perfectly
+ in sync with the actual time as defined by an atomic clock or
+ a better time source. A good installation using NTP, and that is
+ up to date before Erlang starts, will have properties that for
+ most users and programs will be near indistinguishable from the
+ perfect time. Note that any larger corrections to the time done
+ by hand, or after Erlang has started, will partly (or
+ temporarily) invalidate some of the properties, as the time is
+ no longer perfect.</item>
+ <tag>Less than one call per microsecond to erlang:now/0 is
+ done</tag>
+ <item>This means that at <em>any</em> microsecond interval in
+ time, there can be no more than one call to erlang:now/0 in the
+ system. However, for the system not to loose it's properties
+ completely, it's enough that it on average is no more than one
+ call per microsecond (in one Erlang node).</item>
+ </taglist>
+ <p>The uniqueness property of erlang:now/0 is the most limiting
+ property. It means that erlang:now() maintains a global state and
+ that there is a hard-to-check property of the system that needs to
+ be maintained. For most applications this is still not a problem,
+ but a future system might very well manage to violate the
+ frequency limit on the calls globally. The uniqueness property is
+ also quite useless, as there are globally unique references that
+ provide a much better unique value to programs. However the
+ property will need to be maintained unless a really subtle
+ backward compatibility issue is to be introduced.</p>
+ </section>
+ <section>
+ <title>Should I use erlang:now/0 or os:timestamp/0</title>
+ <p>The simple answer is to use erlang:now/0 for everything where
+ you want to keep real time characteristics, but use os:timestamp
+ for things like logs, user communication and debugging (typically
+ timer:ts uses os:timestamp, as it is a test tool, not a real world
+ application API). The benefit of using os:timestamp/0 is that it's
+ faster and does not involve any global state (unless the operating
+ system has one). The downside is that it will be vulnerable to wall
+ clock time changes.</p>
+ </section>
+ <section>
+ <title>Turning off time correction</title>
+ <p>If, for some reason, time correction causes trouble and you are
+ absolutely confident that the wall clock on the system is nearly
+ perfect, you can turn off time correction completely by giving the
+ <c>+c</c> option to <c>erl</c>. The probability for this being a
+ good idea, is very low.</p>
+ </section>
+</chapter>
+
diff --git a/erts/doc/src/tty.xml b/erts/doc/src/tty.xml
index b16523e085..db15195f65 100644
--- a/erts/doc/src/tty.xml
+++ b/erts/doc/src/tty.xml
@@ -1,10 +1,10 @@
-<?xml version="1.0" encoding="latin1" ?>
+<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE chapter SYSTEM "chapter.dtd">
<chapter>
<header>
<copyright>
- <year>1996</year><year>2010</year>
+ <year>1996</year><year>2013</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
diff --git a/erts/doc/src/werl.xml b/erts/doc/src/werl.xml
index 1494d91da8..49cc45e745 100644
--- a/erts/doc/src/werl.xml
+++ b/erts/doc/src/werl.xml
@@ -1,10 +1,10 @@
-<?xml version="1.0" encoding="latin1" ?>
+<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE comref SYSTEM "comref.dtd">
<comref>
<header>
<copyright>
- <year>1998</year><year>2009</year>
+ <year>1998</year><year>2013</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
diff --git a/erts/doc/src/zlib.xml b/erts/doc/src/zlib.xml
index 8917ab5c3a..afc597b729 100644
--- a/erts/doc/src/zlib.xml
+++ b/erts/doc/src/zlib.xml
@@ -1,10 +1,10 @@
-<?xml version="1.0" encoding="latin1" ?>
+<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE erlref SYSTEM "erlref.dtd">
<erlref>
<header>
<copyright>
- <year>2005</year><year>2011</year>
+ <year>2005</year><year>2013</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>