File 1142-erlang-module-doc-binary_to_existing_atom.patch of Package erlang

From ae7278e494f6d0cff4c490c51e371fa343c2887d Mon Sep 17 00:00:00 2001
From: Kjell Winblad <kjellwinblad@gmail.com>
Date: Tue, 1 Sep 2020 14:12:46 +0200
Subject: [PATCH 12/39] erlang module doc: binary_to_existing_atom

* Define what it means for an atom to exist
* Describe the purpose of the function
* Note about atom max length
---
 erts/doc/src/erlang.xml | 31 ++++++++++++++++++++++++++++---
 1 file changed, 28 insertions(+), 3 deletions(-)

diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml
index 0633dd6f15..a33eaffb87 100644
--- a/erts/doc/src/erlang.xml
+++ b/erts/doc/src/erlang.xml
@@ -464,9 +464,28 @@ Z = erlang:adler32_combine(X,Y,iolist_size(Data2)).</code>
       <name name="binary_to_existing_atom" arity="2"/>
       <fsummary>Convert from text representation to an atom.</fsummary>
       <desc>
-        <p>As
-          <seealso marker="#binary_to_atom/2"><c>binary_to_atom/2</c></seealso>,
-          but the atom must exist.</p>
+        <p>As <seealso
+        marker="#binary_to_atom/2"><c>binary_to_atom/2</c></seealso>,
+        but the atom must exist.</p>
+
+        <p>The Erlang system has a <seealso
+        marker="system/efficiency_guide:advanced">configurable
+        limit</seealso> for the total number of atoms that can exist,
+        and atoms are not garbage collected. Therefore, it is not safe
+        to create many atoms from binaries that come from an untrusted
+        source (for example, a file fetched from the Internet), for
+        example, using <seealso
+        marker="#binary_to_atom/2"><c>binary_to_atom/2</c></seealso>. This
+        function is thus the appropriate option when the input binary
+        comes from an untrusted source.</p>
+
+        <p>An atom exists in an Erlang system when included in a
+        loaded Erlang module or when created programmatically (for
+        example, by <c>binary_to_atom/2</c>). See the next note for an
+        example of when an atom exists in the source code for an
+        Erlang module but not in the compiled version of the same
+        module.</p>
+
         <p>Failure: <c>badarg</c> if the atom does not exist.</p>
 	<note>
 	  <p>Note that the compiler may optimize away atoms. For
@@ -478,6 +497,12 @@ Z = erlang:adler32_combine(X,Y,iolist_size(Data2)).</code>
 	  to <c>binary_to_existing_atom(&lt;&lt;"some_atom"&gt;&gt;, utf8)</c>
 	  will fail.</p>
 	</note>
+        <note>
+          <p>The number of characters that are permitted in an atom
+          name is limited. The default limits can be found in the
+          <seealso marker="system/efficiency_guide:advanced">
+          efficiency guide (section Advanced)</seealso>.</p>
+        </note>
       </desc>
     </func>
 
-- 
2.26.2