diff options
Diffstat (limited to 'system/doc/reference_manual')
| -rw-r--r-- | system/doc/reference_manual/Makefile | 3 | ||||
| -rw-r--r-- | system/doc/reference_manual/character_set.xml | 17 | ||||
| -rw-r--r-- | system/doc/reference_manual/data_types.xml | 9 | ||||
| -rw-r--r-- | system/doc/reference_manual/distributed.xml | 15 | ||||
| -rw-r--r-- | system/doc/reference_manual/errors.xml | 55 | ||||
| -rw-r--r-- | system/doc/reference_manual/expressions.xml | 44 | ||||
| -rw-r--r-- | system/doc/reference_manual/introduction.xml | 10 | ||||
| -rw-r--r-- | system/doc/reference_manual/macros.xml | 38 | ||||
| -rw-r--r-- | system/doc/reference_manual/modules.xml | 9 | ||||
| -rw-r--r-- | system/doc/reference_manual/records.xml | 8 | ||||
| -rw-r--r-- | system/doc/reference_manual/typespec.xml | 35 | ||||
| -rw-r--r-- | system/doc/reference_manual/xmlfiles.mk | 7 |
12 files changed, 177 insertions, 73 deletions
diff --git a/system/doc/reference_manual/Makefile b/system/doc/reference_manual/Makefile index e14a056979..02a7f002ed 100644 --- a/system/doc/reference_manual/Makefile +++ b/system/doc/reference_manual/Makefile @@ -1,7 +1,7 @@ # # %CopyrightBegin% # -# Copyright Ericsson AB 2003-2016. All Rights Reserved. +# Copyright Ericsson AB 2003-2018. All Rights Reserved. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. @@ -28,6 +28,7 @@ include $(ERL_TOP)/erts/vsn.mk #VSN=$(SYSTEM_VSN) APPLICATION=otp-system-documentation +XMLDIR := $(XMLDIR)/reference_manual # ---------------------------------------------------- # Release directory specification # ---------------------------------------------------- diff --git a/system/doc/reference_manual/character_set.xml b/system/doc/reference_manual/character_set.xml index d25f2c001d..ef14bf1372 100644 --- a/system/doc/reference_manual/character_set.xml +++ b/system/doc/reference_manual/character_set.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>2014</year><year>2015</year> + <year>2014</year><year>2017</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -32,9 +32,9 @@ <section> <title>Character Set</title> - <p>Since Erlang 4.8/OTP R5A, the syntax of Erlang tokens is extended to - allow the use of the full ISO-8859-1 (Latin-1) character set. This - is noticeable in the following ways:</p> + <p>The syntax of Erlang tokens allow the use of the full + ISO-8859-1 (Latin-1) character set. This is noticeable in the + following ways:</p> <list type="bulleted"> <item> <p>All the Latin-1 printable characters can be used and are @@ -102,13 +102,16 @@ <tcaption>Character Classes</tcaption> </table> <p>In Erlang/OTP R16B the syntax of Erlang tokens was extended to - handle Unicode. The support is limited to - string literals and comments. Atoms, module names, and - function names are restricted to the ISO-Latin-1 range. + handle Unicode. The support was limited to + string literals and comments. More about the usage of Unicode in Erlang source files can be found in <seealso marker="stdlib:unicode_usage#unicode_in_erlang">STDLIB's User's Guide</seealso>.</p> + <p>From Erlang/OTP 20, atoms and function names are also allowed + to contain Unicode characters outside the ISO-Latin-1 range. + Module names, application names, and node names are still + restricted to the ISO-Latin-1 range.</p> </section> <section> <title>Source File Encoding</title> diff --git a/system/doc/reference_manual/data_types.xml b/system/doc/reference_manual/data_types.xml index e63825b97d..93c679357b 100644 --- a/system/doc/reference_manual/data_types.xml +++ b/system/doc/reference_manual/data_types.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>2003</year><year>2015</year> + <year>2003</year><year>2017</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -50,10 +50,7 @@ <item><em><c>base</c></em><c>#</c><em><c>value</c></em> <br></br> Integer with the base <em><c>base</c></em>, that must be an - integer in the range 2..36. <br></br> - - In Erlang 5.2/OTP R9B and earlier versions, the allowed range - is 2..16.</item> + integer in the range 2..36.</item> </list> <p><em>Examples:</em></p> <pre> @@ -455,7 +452,7 @@ hello <<"77">> 16> <input>float_to_binary(7.0).</input> <<"7.00000000000000000000e+00">> -17> <input>binary_to_float(<<"7.000e+00>>").</input> +17> <input>binary_to_float(<<"7.000e+00">>).</input> 7.0</pre> </section> </chapter> diff --git a/system/doc/reference_manual/distributed.xml b/system/doc/reference_manual/distributed.xml index 0a4a323fe9..b519609717 100644 --- a/system/doc/reference_manual/distributed.xml +++ b/system/doc/reference_manual/distributed.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>2003</year><year>2015</year> + <year>2003</year><year>2017</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -42,6 +42,19 @@ <p>The distribution mechanism is implemented using TCP/IP sockets. How to implement an alternative carrier is described in the <seealso marker="erts:alt_dist">ERTS User's Guide</seealso>.</p> + <warning> + <p> + Starting a distributed node without also specifying + <seealso marker="erts:erl#proto_dist"><c>-proto_dist inet_tls</c></seealso> + will expose the node to attacks that may give the attacker + complete access to the node and in extension the cluster. + When using un-secure distributed nodes, make sure that the + network is configured to keep potential attackers out. + See the <seealso marker="ssl:ssl_distribution"> + Using SSL for Erlang Distribution</seealso> User's Guide + for details on how to setup a secure distributed node. + </p> + </warning> </section> <section> diff --git a/system/doc/reference_manual/errors.xml b/system/doc/reference_manual/errors.xml index e764cf431f..16d3e7590e 100644 --- a/system/doc/reference_manual/errors.xml +++ b/system/doc/reference_manual/errors.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>2003</year><year>2015</year> + <year>2003</year><year>2017</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -49,8 +49,7 @@ The Erlang programming language has built-in features for handling of run-time errors.</p> <p>A run-time error can also be emulated by calling - <c>erlang:error(Reason)</c> or <c>erlang:error(Reason, Args)</c> - (those appeared in Erlang 5.4/OTP-R10).</p> + <c>erlang:error(Reason)</c> or <c>erlang:error(Reason, Args)</c>.</p> <p>A run-time error is another name for an exception of class <c>error</c>. </p> @@ -79,7 +78,6 @@ <p>Exceptions are run-time errors or generated errors and are of three different classes, with different origins. The <seealso marker="expressions#try">try</seealso> expression - (new in Erlang 5.4/OTP R10B) can distinguish between the different classes, whereas the <seealso marker="expressions#catch">catch</seealso> expression cannot. They are described in @@ -94,7 +92,7 @@ <cell align="left" valign="middle"><c>error</c></cell> <cell align="left" valign="middle">Run-time error, for example, <c>1+a</c>, or the process called - <c>erlang:error/1,2</c> (new in Erlang 5.4/OTP R10B)</cell> + <c>erlang:error/1,2</c></cell> </row> <row> <cell align="left" valign="middle"><c>exit</c></cell> @@ -110,14 +108,55 @@ (see <seealso marker="#exit_reasons">Exit Reason</seealso>), and a stack trace (which aids in finding the code location of the exception).</p> - <p>The stack trace can be retrieved using - <c>erlang:get_stacktrace/0</c> (new in Erlang 5.4/OTP R10B) - from within a <c>try</c> expression, and is returned for + <p>The stack trace can be be bound to a variable from within + a <c>try</c> expression, and is returned for exceptions of class <c>error</c> from a <c>catch</c> expression.</p> <p>An exception of class <c>error</c> is also known as a run-time error.</p> + + <section> + <title>The call-stack back trace (stacktrace)</title> + <p>The stack back-trace (<em>stacktrace</em>) is a list of + <c>{Module,Function,Arity,Location}</c> + tuples. The field <c>Arity</c> in the first tuple can be the + argument list of that function call instead of an arity integer, + depending on the exception.</p> + + <p><c>Location</c> is a (possibly empty) list of two-tuples + that can indicate the location in the source code of the + function. The first element is an atom describing the type of + information in the second element. The following items can + occur:</p> + <taglist> + <tag><c>file</c></tag> + <item>The second element of the tuple is a string (list of + characters) representing the filename of the source file + of the function. + </item> + <tag><c>line</c></tag> + <item>The second element of the tuple is the line number + (an integer > 0) in the source file + where the exception occurred or the function was called. + </item> + </taglist> + <warning><p>Developers should rely on stacktrace entries only for + debugging purposes.</p> + <p>The VM performs tail call optimization, which + does not add new entries to the stacktrace, and also limits stacktraces + to a certain depth. Furthermore, compiler options, optimizations and + future changes may add or remove stacktrace entries, causing any code + that expects the stacktrace to be in a certain order or contain specific + items to fail.</p> + <p>The only exception to this rule is the class <c>error</c> with the + reason <c>undef</c> which is guaranteed to include the <c>Module</c>, + <c>Function</c> and <c>Arity</c> of the attempted + function as the first stacktrace entry.</p> + </warning> + </section> + </section> + <section> <title>Handling of Run-time Errors in Erlang</title> diff --git a/system/doc/reference_manual/expressions.xml b/system/doc/reference_manual/expressions.xml index 1a3d19aed1..94e40dd077 100644 --- a/system/doc/reference_manual/expressions.xml +++ b/system/doc/reference_manual/expressions.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>2003</year><year>2016</year> + <year>2003</year><year>2017</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -123,10 +123,9 @@ member(_Elem, []) -> or <c>receive</c> expression must be bound in all branches to have a value outside the expression. Otherwise they are regarded as 'unsafe' outside the expression.</p> - <p>For the <c>try</c> expression introduced in - Erlang 5.4/OTP R10B, variable scoping is limited so that + <p>For the <c>try</c> expression variable scoping is limited so that variables bound in the expression are always 'unsafe' outside - the expression. This is to be improved.</p> + the expression.</p> </section> <section> @@ -189,7 +188,6 @@ f([$p,$r,$e,$f,$i,$x | Str]) -> ...</pre> <pre> case {Value, Result} of {?THRESHOLD+1, ok} -> ...</pre> - <p>This feature was added in Erlang 5.0/OTP R7.</p> </section> </section> @@ -1342,14 +1340,14 @@ hello</pre> <code type="none"> try Exprs catch - [Class1:]ExceptionPattern1 [when ExceptionGuardSeq1] -> + Class1:ExceptionPattern1[:Stacktrace] [when ExceptionGuardSeq1] -> ExceptionBody1; - [ClassN:]ExceptionPatternN [when ExceptionGuardSeqN] -> + ClassN:ExceptionPatternN[:Stacktrace] [when ExceptionGuardSeqN] -> ExceptionBodyN end</code> <p>This is an enhancement of - <seealso marker="#catch">catch</seealso> that appeared in - Erlang 5.4/OTP R10B. It gives the possibility to:</p> + <seealso marker="#catch">catch</seealso>. + It gives the possibility to:</p> <list type="bulleted"> <item>Distinguish between different exception classes.</item> <item>Choose to handle only the desired ones.</item> @@ -1364,10 +1362,12 @@ end</code> the evaluation. In that case the exception is caught and the patterns <c>ExceptionPattern</c> with the right exception class <c>Class</c> are sequentially matched against the caught - exception. An omitted <c>Class</c> is shorthand for <c>throw</c>. - If a match succeeds and the optional guard sequence + exception. If a match succeeds and the optional guard sequence <c>ExceptionGuardSeq</c> is true, the corresponding <c>ExceptionBody</c> is evaluated to become the return value.</p> + <p><c>Stacktrace</c>, if specified, must be the name of a variable + (not a pattern). The stack trace is bound to the variable when + the corresponding <c>ExceptionPattern</c> matches.</p> <p>If an exception occurs during evaluation of <c>Exprs</c> but there is no matching <c>ExceptionPattern</c> of the right <c>Class</c> with a true guard sequence, the exception is passed @@ -1375,6 +1375,18 @@ end</code> expression.</p> <p>If an exception occurs during evaluation of <c>ExceptionBody</c>, it is not caught.</p> + <p>It is allowed to omit <c>Class</c> and <c>Stacktrace</c>. + An omitted <c>Class</c> is shorthand for <c>throw</c>:</p> + + <code type="none"> +try Exprs +catch + ExceptionPattern1 [when ExceptionGuardSeq1] -> + ExceptionBody1; + ExceptionPatternN [when ExceptionGuardSeqN] -> + ExceptionBodyN +end</code> + <p>The <c>try</c> expression can have an <c>of</c> section: </p> @@ -1386,10 +1398,10 @@ try Exprs of PatternN [when GuardSeqN] -> BodyN catch - [Class1:]ExceptionPattern1 [when ExceptionGuardSeq1] -> + Class1:ExceptionPattern1[:Stacktrace] [when ExceptionGuardSeq1] -> ExceptionBody1; ...; - [ClassN:]ExceptionPatternN [when ExceptionGuardSeqN] -> + ClassN:ExceptionPatternN[:Stacktrace] [when ExceptionGuardSeqN] -> ExceptionBodyN end</code> <p>If the evaluation of <c>Exprs</c> succeeds without an exception, @@ -1410,10 +1422,10 @@ try Exprs of PatternN [when GuardSeqN] -> BodyN catch - [Class1:]ExceptionPattern1 [when ExceptionGuardSeq1] -> + Class1:ExceptionPattern1[:Stacktrace] [when ExceptionGuardSeq1] -> ExceptionBody1; ...; - [ClassN:]ExceptionPatternN [when ExceptionGuardSeqN] -> + ClassN:ExceptionPatternN[:Stacktrace] [when ExceptionGuardSeqN] -> ExceptionBodyN after AfterBody @@ -1472,7 +1484,7 @@ try Expr catch throw:Term -> Term; exit:Reason -> {'EXIT',Reason} - error:Reason -> {'EXIT',{Reason,erlang:get_stacktrace()}} + error:Reason:Stk -> {'EXIT',{Reason,Stk}} end</code> </section> diff --git a/system/doc/reference_manual/introduction.xml b/system/doc/reference_manual/introduction.xml index abb4ed407d..69e52e0b37 100644 --- a/system/doc/reference_manual/introduction.xml +++ b/system/doc/reference_manual/introduction.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>2003</year><year>2015</year> + <year>2003</year><year>2018</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -48,7 +48,7 @@ System Principles</seealso></p> <p>Starting and stopping, boot scripts, code loading, <seealso marker="doc/system_principles:error_logging"> - error logging</seealso>, + logging</seealso>, <seealso marker="doc/system_principles:create_target"> creating target systems</seealso></p> </item> @@ -80,14 +80,14 @@ <item>A <em>list</em> is any number of items. For example, an argument list can consist of zero, one, or more arguments.</item> </list> - <p>If a feature has been added recently, in Erlang 5.0/OTP R7 or - later, this is mentioned in the text.</p> + <p>If a feature has been added in R13A or later, + this is mentioned in the text.</p> </section> <section> <title>Complete List of BIFs</title> <p>For a complete list of BIFs, their arguments and return values, - see <seealso marker="erts:erlang#process_flag/2">erlang(3)</seealso> + see <seealso marker="erts:erlang">erlang(3)</seealso> manual page in ERTS.</p> </section> diff --git a/system/doc/reference_manual/macros.xml b/system/doc/reference_manual/macros.xml index 5f24473557..8a8d5f3a4c 100644 --- a/system/doc/reference_manual/macros.xml +++ b/system/doc/reference_manual/macros.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>2003</year><year>2016</year> + <year>2003</year><year>2018</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -150,6 +150,11 @@ bar(X) -> <item>The name of the current function.</item> <tag><c>?FUNCTION_ARITY</c></tag> <item>The arity (number of arguments) for the current function.</item> + <tag><c>?OTP_RELEASE</c></tag> + <item>The OTP release that the currently executing ERTS + application is part of, as an integer. For details, see + <seealso marker="erts:erlang#system_info/1"><c>erlang:system_info(otp_release)</c></seealso>. + This macro was introduced in OTP release 21.</item> </taglist> </section> @@ -202,8 +207,16 @@ f() -> directive. If that condition is false, the lines following <c>else</c> are evaluated instead.</item> <tag><c>-endif.</c></tag> - <item>Specifies the end of an <c>ifdef</c> or <c>ifndef</c> - directive.</item> + <item>Specifies the end of an <c>ifdef</c>, an <c>ifndef</c> + directive, or the end of an <c>if</c> or <c>elif</c> directive.</item> + <tag><c>-if(Condition).</c></tag> + <item>Evaluates the following lines only if <c>Condition</c> + evaluates to true.</item> + <tag><c>-elif(Condition).</c></tag> + <item>Only allowed after an <c>if</c> or another <c>elif</c> directive. + If the preceding <c>if</c> or <c>elif</c> directives do not + evaluate to true, and the <c>Condition</c> evaluates to true, + the lines following the <c>elif</c> are evaluated instead.</item> </taglist> <note> <p>The macro directives cannot be used inside functions.</p> @@ -231,6 +244,24 @@ or {ok,m}</pre> <p><c>?LOG(Arg)</c> is then expanded to a call to <c>io:format/2</c> and provide the user with some simple trace output.</p> + + <p><em>Example:</em></p> + <code type="none"> +-module(m) +... +-ifdef(OTP_RELEASE). + %% OTP 21 or higher + -if(?OTP_RELEASE >= 22). + %% Code that will work in OTP 22 or higher + -elif(?OTP_RELEASE >= 21). + %% Code that will work in OTP 21 or higher + -endif. +-else. + %% OTP 20 or lower. +-endif. +...</code> + <p>The code uses the <c>OTP_RELEASE</c> macro to conditionally + select code depending on release.</p> </section> <section> @@ -286,7 +317,6 @@ t.erl:5: Warning: -warning("Macro VERSION not defined -- using default version." argument, is expanded to a string containing the tokens of the argument. This is similar to the <c>#arg</c> stringifying construction in C.</p> - <p>The feature was added in Erlang 5.0/OTP R7.</p> <p><em>Example:</em></p> <code type="none"> -define(TESTCALL(Call), io:format("Call ~s: ~w~n", [??Call, Call])). diff --git a/system/doc/reference_manual/modules.xml b/system/doc/reference_manual/modules.xml index 96968b547e..6f93198ec1 100644 --- a/system/doc/reference_manual/modules.xml +++ b/system/doc/reference_manual/modules.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>2003</year><year>2016</year> + <year>2003</year><year>2018</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -143,7 +143,6 @@ fact(0) -> % | standard behaviours:</p> <list type="bulleted"> <item><c>gen_server</c></item> - <item><c>gen_fsm</c></item> <item><c>gen_statem</c></item> <item><c>gen_event</c></item> <item><c>supervisor</c></item> @@ -308,6 +307,12 @@ behaviour_info(callbacks) -> Callbacks.</pre> all functions in the module.</p> </item> + <tag><c>nifs</c></tag> + <item> + <p>Returns a list of <c>{Name,Arity}</c> tuples with + all NIF functions in the module.</p> + </item> + <tag><c>native</c></tag> <item> <p>Return <c>true</c> if the module has native compiled code. diff --git a/system/doc/reference_manual/records.xml b/system/doc/reference_manual/records.xml index 12a3e697cd..6b26e2c242 100644 --- a/system/doc/reference_manual/records.xml +++ b/system/doc/reference_manual/records.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>2003</year><year>2015</year> + <year>2003</year><year>2017</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -72,9 +72,9 @@ <pre> #Name{Field1=Expr1,...,FieldK=ExprK, _=ExprL}</pre> <p>Omitted fields then get the value of evaluating <c>ExprL</c> - instead of their default values. This feature was added in - Erlang 5.1/OTP R8 and is primarily intended to be used to create - patterns for ETS and Mnesia match functions.</p> + instead of their default values. This feature is primarily + intended to be used to create patterns for ETS and Mnesia match + functions.</p> <p><em>Example:</em></p> <pre> -record(person, {name, phone, address}). diff --git a/system/doc/reference_manual/typespec.xml b/system/doc/reference_manual/typespec.xml index a0ea41cb3b..f6a19397c3 100644 --- a/system/doc/reference_manual/typespec.xml +++ b/system/doc/reference_manual/typespec.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>2003</year><year>2016</year> + <year>2003</year><year>2017</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -133,17 +133,17 @@ Map :: map() %% denotes a map of any size | #{} %% denotes the empty map - | #{PairList} + | #{AssociationList} Tuple :: tuple() %% denotes a tuple of any size | {} | {TList} - PairList :: Pair - | Pair, PairList + AssociationList :: Association + | Association, AssociationList - Pair :: Type := Type %% denotes a mandatory pair - | Type => Type %% denotes an optional pair + Association :: Type := Type %% denotes a mandatory association + | Type => Type %% denotes an optional association TList :: Type | Type, TList @@ -173,14 +173,17 @@ The notation <c>[]</c> specifies the singleton type for the empty list. </p> <p> - The general form of maps is <c>#{PairList}</c>. The key types in - <c>PairList</c> are allowed to overlap, and if they do, the - leftmost pair takes precedence. A map pair has a key in - <c>PairList</c> if it belongs to this type. A <c>PairList</c> may contain - both 'mandatory' and 'optional' pairs where 'mandatory' denotes that - a key type, and its associated value type, must be present. - In the case of an 'optional' pair it is not required for the key type to - be present. + The general form of map types is <c>#{AssociationList}</c>. + The key types in + <c>AssociationList</c> are allowed to overlap, and if they do, the + leftmost association takes precedence. A map association has a key in + <c>AssociationList</c> if it belongs to this type. + <c>AssociationList</c> can contain both mandatory and optional + association types. + If an association type is mandatory, an association with that type + is to be present. + In the case of an optional association type it is not required for + the key type to be present. </p> <p> Notice that the syntactic representation of <c>map()</c> is @@ -512,8 +515,8 @@ <p> Currently, the <c>::</c> constraint (read as «is a subtype of») is - the only guard constraint that can be used in the <c>'when'</c> - part of a <c>'-spec'</c> attribute. + the only guard constraint that can be used in the <c>when</c> + part of a <c>-spec</c> attribute. </p> <note> <p> diff --git a/system/doc/reference_manual/xmlfiles.mk b/system/doc/reference_manual/xmlfiles.mk index 61637ae701..92d232b628 100644 --- a/system/doc/reference_manual/xmlfiles.mk +++ b/system/doc/reference_manual/xmlfiles.mk @@ -1,7 +1,7 @@ # # %CopyrightBegin% # -# Copyright Ericsson AB 2009-2016. All Rights Reserved. +# Copyright Ericsson AB 2009-2018. All Rights Reserved. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. @@ -30,5 +30,6 @@ REF_MAN_CHAPTER_FILES = \ processes.xml \ distributed.xml \ code_loading.xml \ - ports.xml - + ports.xml \ + character_set.xml \ + typespec.xml |