File 0312-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
@@ -535,6 +535,25 @@ Z = erlang:adler32_combine(X,Y,iolist_size(Data2)).</code>
           but the atom must exist. An atom exists if it has
           been created by the run-time system by either loading code or creating
           a term in which the atom is part.</p>
+
+        <p>The Erlang system has a <seeguide
+        marker="system/efficiency_guide:advanced">configurable
+        limit</seeguide> 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 <seemfa
+        marker="#binary_to_atom/2"><c>binary_to_atom/2</c></seemfa>. 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
@@ -546,6 +565,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
+          <seeguide marker="system/efficiency_guide:advanced">
+          efficiency guide (section Advanced)</seeguide>.</p>
+        </note>
       </desc>
     </func>
 
-- 
2.26.2