aboutsummaryrefslogtreecommitdiffstats
path: root/erts/doc/src/erlang.xml
diff options
context:
space:
mode:
Diffstat (limited to 'erts/doc/src/erlang.xml')
-rw-r--r--erts/doc/src/erlang.xml6920
1 files changed, 6920 insertions, 0 deletions
diff --git a/erts/doc/src/erlang.xml b/erts/doc/src/erlang.xml
new file mode 100644
index 0000000000..fd4447009a
--- /dev/null
+++ b/erts/doc/src/erlang.xml
@@ -0,0 +1,6920 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+ <header>
+ <copyright>
+ <year>1996</year><year>2009</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>erlang</title>
+ <prepared></prepared>
+ <docno></docno>
+ <date></date>
+ <rev></rev>
+ <file>erlang.xml</file>
+ </header>
+ <module>erlang</module>
+ <modulesummary>The Erlang BIFs</modulesummary>
+ <description>
+ <p>By convention, most built-in functions (BIFs) are seen as being
+ in the module <c>erlang</c>. A number of the BIFs are viewed more
+ or less as part of the Erlang programming language and are
+ <em>auto-imported</em>. Thus, it is not necessary to specify
+ the module name and both the calls <c>atom_to_list(Erlang)</c> and
+ <c>erlang:atom_to_list(Erlang)</c> are identical.</p>
+ <p>In the text, auto-imported BIFs are listed without module prefix.
+ BIFs listed with module prefix are not auto-imported.</p>
+ <p>BIFs may fail for a variety of reasons. All BIFs fail with
+ reason <c>badarg</c> if they are called with arguments of an
+ incorrect type. The other reasons that may make BIFs fail are
+ described in connection with the description of each individual
+ BIF.</p>
+ <p>Some BIFs may be used in guard tests, these are marked with
+ "Allowed in guard tests".</p>
+ </description>
+
+ <section>
+ <title>DATA TYPES</title>
+ <marker id="iolist_definition"></marker>
+ <code type="none">
+ext_binary()
+ a binary data object,
+ structured according to the Erlang external term format
+
+iodata() = iolist() | binary()
+
+iolist() = [char() | binary() | iolist()]
+ a binary is allowed as the tail of the list</code>
+ </section>
+ <funcs>
+ <func>
+ <name>abs(Number) -> int() | float()</name>
+ <fsummary>Arithmetical absolute value</fsummary>
+ <type>
+ <v>Number = number()</v>
+ </type>
+ <desc>
+ <p>Returns an integer or float which is the arithmetical
+ absolute value of <c>Number</c>.</p>
+ <pre>
+> <input>abs(-3.33).</input>
+3.33
+> <input>abs(-3).</input>
+3</pre>
+ <p>Allowed in guard tests.</p>
+ </desc>
+ </func>
+ <func>
+ <name>adler32(Data) -> int()</name>
+ <fsummary>Compute adler32 checksum</fsummary>
+ <type>
+ <v>Data = iodata()</v>
+ </type>
+ <desc>
+ <p>Computes and returns the adler32 checksum for <c>Data</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>adler32(OldAdler, Data) -> int()</name>
+ <fsummary>Compute adler32 checksum</fsummary>
+ <type>
+ <v>OldAdler = int()</v>
+ <v>Data = iodata()</v>
+ </type>
+ <desc>
+ <p>Continue computing the adler32 checksum by combining
+ the previous checksum, <c>OldAdler</c>, with the checksum of
+ <c>Data</c>.</p>
+ <p>The following code:</p>
+ <code>
+ X = adler32(Data1),
+ Y = adler32(X,Data2).
+ </code>
+ <p>- would assign the same value to <c>Y</c> as this would:</p>
+ <code>
+ Y = adler32([Data1,Data2]).
+ </code>
+ </desc>
+ </func>
+ <func>
+ <name>adler32_combine(FirstAdler, SecondAdler, SecondSize) -> int()</name>
+ <fsummary>Combine two adler32 checksums</fsummary>
+ <type>
+ <v>FirstAdler = SecondAdler = int()</v>
+ <v>SecondSize = int()</v>
+ </type>
+ <desc>
+ <p>Combines two previously computed adler32 checksums.
+ This computation requires the size of the data object for
+ the second checksum to be known.</p>
+ <p>The following code:</p>
+ <code>
+ Y = adler32(Data1),
+ Z = adler32(Y,Data2).
+ </code>
+ <p>- would assign the same value to <c>Z</c> as this would:</p>
+ <code>
+ X = adler32(Data1),
+ Y = adler32(Data2),
+ Z = adler32_combine(X,Y,iolist_size(Data2)).
+ </code>
+ </desc>
+ </func>
+ <func>
+ <name>erlang:append_element(Tuple1, Term) -> Tuple2</name>
+ <fsummary>Append an extra element to a tuple</fsummary>
+ <type>
+ <v>Tuple1 = Tuple2 = tuple()</v>
+ <v>Term = term()</v>
+ </type>
+ <desc>
+ <p>Returns a new tuple which has one element more than
+ <c>Tuple1</c>, and contains the elements in <c>Tuple1</c>
+ followed by <c>Term</c> as the last element. Semantically
+ equivalent to
+ <c>list_to_tuple(tuple_to_list(Tuple ++ [Term])</c>, but much
+ faster.</p>
+ <pre>
+> <input>erlang:append_element({one, two}, three).</input>
+{one,two,three}</pre>
+ </desc>
+ </func>
+ <func>
+ <name>apply(Fun, Args) -> term() | empty()</name>
+ <fsummary>Apply a function to an argument list</fsummary>
+ <type>
+ <v>Fun = fun()</v>
+ <v>Args = [term()]</v>
+ </type>
+ <desc>
+ <p>Call a fun, passing the elements in <c>Args</c> as
+ arguments.</p>
+ <p>Note: If the number of elements in the arguments are known at
+ compile-time, the call is better written as
+ <c>Fun(Arg1, Arg2, ... ArgN)</c>.</p>
+ <warning>
+ <p>Earlier, <c>Fun</c> could also be given as
+ <c>{Module, Function}</c>, equivalent to
+ <c>apply(Module, Function, Args)</c>. This usage is
+ deprecated and will stop working in a future release of
+ Erlang/OTP.</p>
+ </warning>
+ </desc>
+ </func>
+ <func>
+ <name>apply(Module, Function, Args) -> term() | empty()</name>
+ <fsummary>Apply a function to an argument list</fsummary>
+ <type>
+ <v>Module = Function = atom()</v>
+ <v>Args = [term()]</v>
+ </type>
+ <desc>
+ <p>Returns the result of applying <c>Function</c> in
+ <c>Module</c> to <c>Args</c>. The applied function must
+ be exported from <c>Module</c>. The arity of the function is
+ the length of <c>Args</c>.</p>
+ <pre>
+> <input>apply(lists, reverse, [[a, b, c]]).</input>
+[c,b,a]</pre>
+ <p><c>apply</c> can be used to evaluate BIFs by using
+ the module name <c>erlang</c>.</p>
+ <pre>
+> <input>apply(erlang, atom_to_list, ['Erlang']).</input>
+"Erlang"</pre>
+ <p>Note: If the number of arguments are known at compile-time,
+ the call is better written as
+ <c>Module:Function(Arg1, Arg2, ..., ArgN)</c>.</p>
+ <p>Failure: <c>error_handler:undefined_function/3</c> is called
+ if the applied function is not exported. The error handler
+ can be redefined (see
+ <seealso marker="#process_flag/2">process_flag/2</seealso>).
+ If the <c>error_handler</c> is undefined, or if the user has
+ redefined the default <c>error_handler</c> so the replacement
+ module is undefined, an error with the reason <c>undef</c>
+ is generated.</p>
+ </desc>
+ </func>
+ <func>
+ <name>atom_to_binary(Atom, Encoding) -> binary()</name>
+ <fsummary>Return the binary representation of an atom</fsummary>
+ <type>
+ <v>Atom = atom()</v>
+ <v>Encoding = latin1 | utf8 | unicode</v>
+ </type>
+ <desc>
+ <p>Returns a binary which corresponds to the text
+ representation of <c>Atom</c>. If <c>Encoding</c>
+ is <c>latin1</c>, there will be one byte for each character
+ in the text representation. If <c>Encoding</c> is <c>utf8</c> or
+ <c>unicode</c>, the characters will encoded using UTF-8
+ (meaning that characters from 16#80 up to 0xFF will be
+ encode in two bytes).</p>
+
+ <note><p>Currently, <c>atom_to_binary(Atom, latin1)</c> can
+ never fail because the text representation of an atom can only contain
+ characters from 0 to 16#FF. In a future release, the text representation
+ of atoms might be allowed to contain any Unicode character
+ and <c>atom_to_binary(Atom, latin1)</c> will fail if the
+ text representation for the <c>Atom</c> contains a Unicode
+ character greater than 16#FF.</p></note>
+
+ <pre>
+> <input>atom_to_binary('Erlang', latin1).</input>
+&lt;&lt;"Erlang"&gt;&gt;</pre>
+ </desc>
+ </func>
+ <func>
+ <name>atom_to_list(Atom) -> string()</name>
+ <fsummary>Text representation of an atom</fsummary>
+ <type>
+ <v>Atom = atom()</v>
+ </type>
+ <desc>
+ <p>Returns a string which corresponds to the text
+ representation of <c>Atom</c>.</p>
+ <pre>
+> <input>atom_to_list('Erlang').</input>
+"Erlang"</pre>
+ </desc>
+ </func>
+ <func>
+ <name>binary_to_atom(Binary, Encoding) -> atom()</name>
+ <fsummary>Convert from text representation to an atom</fsummary>
+ <type>
+ <v>Binary = binary()</v>
+ <v>Encoding = latin1 | utf8 | unicode</v>
+ </type>
+ <desc>
+ <p>Returns the atom whose text representation is
+ <c>Binary</c>. If <c>Encoding</c> is <c>latin1</c>, no
+ translation of bytes in the binary is done. If <c>Encoding</c>
+ is <c>utf8</c> or <c>unicode</c>, the binary must contain
+ valid UTF-8 sequences; furthermore, only Unicode characters up
+ to 0xFF are allowed.</p>
+
+ <note><p><c>binary_to_atom(Binary, utf8)</c> will fail if
+ the binary contains Unicode characters greater than 16#FF.
+ In a future release, such Unicode characters might be allowed
+ and <c>binary_to_atom(Binary, utf8)</c>
+ will not fail in that case.</p></note>
+
+ <pre>
+> <input>binary_to_atom(&lt;&lt;"Erlang"&gt;&gt;, latin1).</input>
+'Erlang'
+> <input>binary_to_atom(&lt;&lt;1024/utf8&gt;&gt;, utf8).</input>
+** exception error: bad argument
+ in function binary_to_atom/2
+ called as binary_to_atom(&lt;&lt;208,128&gt;&gt;,utf8)</pre>
+ </desc>
+ </func>
+ <func>
+ <name>binary_to_existing_atom(Binary, Encoding) -> atom()</name>
+ <fsummary>Convert from text representation to an atom</fsummary>
+ <type>
+ <v>Binary = binary()</v>
+ <v>Encoding = latin1 | utf8 | unicode</v>
+ </type>
+ <desc>
+ <p>Works like <seealso marker="#binary_to_atom/2">binary_to_atom/2</seealso>,
+ but the atom must already exist.</p>
+ <p>Failure: <c>badarg</c> if the atom does not already exist.</p>
+ </desc>
+ </func>
+ <func>
+ <name>binary_to_list(Binary) -> [char()]</name>
+ <fsummary>Convert a binary to a list</fsummary>
+ <type>
+ <v>Binary = binary()</v>
+ </type>
+ <desc>
+ <p>Returns a list of integers which correspond to the bytes of
+ <c>Binary</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>binary_to_list(Binary, Start, Stop) -> [char()]</name>
+ <fsummary>Convert part of a binary to a list</fsummary>
+ <type>
+ <v>Binary = binary()</v>
+ <v>Start = Stop = 1..byte_size(Binary)</v>
+ </type>
+ <desc>
+ <p>As <c>binary_to_list/1</c>, but returns a list of integers
+ corresponding to the bytes from position <c>Start</c> to
+ position <c>Stop</c> in <c>Binary</c>. Positions in the
+ binary are numbered starting from 1.</p>
+ </desc>
+ </func>
+ <func>
+ <name>bitstring_to_list(Bitstring) -> [char()|bitstring()]</name>
+ <fsummary>Convert a bitstring to a list</fsummary>
+ <type>
+ <v>Bitstring = bitstring()</v>
+ </type>
+ <desc>
+ <p>Returns a list of integers which correspond to the bytes of
+ <c>Bitstring</c>. If the number of bits in the binary is not
+ divisible by 8, the last element of the list will be a bitstring
+ containing the remaining bits (1 up to 7 bits).</p>
+ </desc>
+ </func>
+ <func>
+ <name>binary_to_term(Binary) -> term()</name>
+ <fsummary>Decode an Erlang external term format binary</fsummary>
+ <type>
+ <v>Binary = ext_binary()</v>
+ </type>
+ <desc>
+ <p>Returns an Erlang term which is the result of decoding
+ the binary object <c>Binary</c>, which must be encoded
+ according to the Erlang external term format. See also
+ <seealso marker="#term_to_binary/1">term_to_binary/1</seealso>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>bit_size(Bitstring) -> int()</name>
+ <fsummary>Return the size of a bitstring</fsummary>
+ <type>
+ <v>Bitstring = bitstring()</v>
+ </type>
+ <desc>
+ <p>Returns an integer which is the size in bits of <c>Bitstring</c>.</p>
+ <pre>
+> <input>bit_size(&lt;&lt;433:16,3:3&gt;&gt;).</input>
+19
+> <input>bit_size(&lt;&lt;1,2,3&gt;&gt;).</input>
+24</pre>
+ <p>Allowed in guard tests.</p>
+ </desc>
+ </func>
+ <func>
+ <name>erlang:bump_reductions(Reductions) -> void()</name>
+ <fsummary>Increment the reduction counter</fsummary>
+ <type>
+ <v>Reductions = int()</v>
+ </type>
+ <desc>
+ <p>This implementation-dependent function increments
+ the reduction counter for the calling process. In the Beam
+ emulator, the reduction counter is normally incremented by
+ one for each function and BIF call, and a context switch is
+ forced when the counter reaches the maximum number of reductions
+ for a process (2000 reductions in R12B).</p>
+ <warning>
+ <p>This BIF might be removed in a future version of the Beam
+ machine without prior warning. It is unlikely to be
+ implemented in other Erlang implementations.</p>
+ </warning>
+ </desc>
+ </func>
+ <func>
+ <name>byte_size(Bitstring) -> int()</name>
+ <fsummary>Return the size of a bitstring (or binary)</fsummary>
+ <type>
+ <v>Bitstring = bitstring()</v>
+ </type>
+ <desc>
+ <p>Returns an integer which is the number of bytes needed to contain
+ <c>Bitstring</c>. (That is, if the number of bits in <c>Bitstring</c> is not
+ divisible by 8, the resulting number of bytes will be rounded <em>up</em>.)</p>
+ <pre>
+> <input>byte_size(&lt;&lt;433:16,3:3&gt;&gt;).</input>
+3
+> <input>byte_size(&lt;&lt;1,2,3&gt;&gt;).</input>
+3</pre>
+ <p>Allowed in guard tests.</p>
+ </desc>
+ </func>
+ <func>
+ <name>erlang:cancel_timer(TimerRef) -> Time | false</name>
+ <fsummary>Cancel a timer</fsummary>
+ <type>
+ <v>TimerRef = ref()</v>
+ <v>Time = int()</v>
+ </type>
+ <desc>
+ <p>Cancels a timer, where <c>TimerRef</c> was returned by
+ either
+ <seealso marker="#erlang:send_after/3">erlang:send_after/3</seealso>
+ or
+ <seealso marker="#erlang:start_timer/3">erlang:start_timer/3</seealso>.
+ If the timer is there to be removed, the function returns
+ the time in milliseconds left until the timer would have expired,
+ otherwise <c>false</c> (which means that <c>TimerRef</c> was
+ never a timer, that it has already been cancelled, or that it
+ has already delivered its message).</p>
+ <p>See also
+ <seealso marker="#erlang:send_after/3">erlang:send_after/3</seealso>,
+ <seealso marker="#erlang:start_timer/3">erlang:start_timer/3</seealso>,
+ and
+ <seealso marker="#erlang:read_timer/1">erlang:read_timer/1</seealso>.</p>
+ <p>Note: Cancelling a timer does not guarantee that the message
+ has not already been delivered to the message queue.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>check_process_code(Pid, Module) -> bool()</name>
+ <fsummary>Check if a process is executing old code for a module</fsummary>
+ <type>
+ <v>Pid = pid()</v>
+ <v>Module = atom()</v>
+ </type>
+ <desc>
+ <p>Returns <c>true</c> if the process <c>Pid</c> is executing
+ old code for <c>Module</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>See also <seealso marker="kernel:code">code(3)</seealso>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>concat_binary(ListOfBinaries)</name>
+ <fsummary>Concatenate a list of binaries (deprecated)</fsummary>
+ <desc>
+ <p>Do not use; use
+ <seealso marker="#list_to_binary/1">list_to_binary/1</seealso>
+ instead.</p>
+ </desc>
+ </func>
+ <func>
+ <name>crc32(Data) -> int()</name>
+ <fsummary>Compute crc32 (IEEE 802.3) checksum</fsummary>
+ <type>
+ <v>Data = iodata()</v>
+ </type>
+ <desc>
+ <p>Computes and returns the crc32 (IEEE 802.3 style) checksum for <c>Data</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>crc32(OldCrc, Data) -> int()</name>
+ <fsummary>Compute crc32 (IEEE 802.3) checksum</fsummary>
+ <type>
+ <v>OldCrc = int()</v>
+ <v>Data = iodata()</v>
+ </type>
+ <desc>
+ <p>Continue computing the crc32 checksum by combining
+ the previous checksum, <c>OldCrc</c>, with the checksum of
+ <c>Data</c>.</p>
+ <p>The following code:</p>
+ <code>
+ X = crc32(Data1),
+ Y = crc32(X,Data2).
+ </code>
+ <p>- would assign the same value to <c>Y</c> as this would:</p>
+ <code>
+ Y = crc32([Data1,Data2]).
+ </code>
+ </desc>
+ </func>
+ <func>
+ <name>crc32_combine(FirstCrc, SecondCrc, SecondSize) -> int()</name>
+ <fsummary>Combine two crc32 (IEEE 802.3) checksums</fsummary>
+ <type>
+ <v>FirstCrc = SecondCrc = int()</v>
+ <v>SecondSize = int()</v>
+ </type>
+ <desc>
+ <p>Combines two previously computed crc32 checksums.
+ This computation requires the size of the data object for
+ the second checksum to be known.</p>
+ <p>The following code:</p>
+ <code>
+ Y = crc32(Data1),
+ Z = crc32(Y,Data2).
+ </code>
+ <p>- would assign the same value to <c>Z</c> as this would:</p>
+ <code>
+ X = crc32(Data1),
+ Y = crc32(Data2),
+ Z = crc32_combine(X,Y,iolist_size(Data2)).
+ </code>
+ </desc>
+ </func>
+ <func>
+ <name>date() -> {Year, Month, Day}</name>
+ <fsummary>Current date</fsummary>
+ <type>
+ <v>Year = Month = Day = int()</v>
+ </type>
+ <desc>
+ <p>Returns the current date as <c>{Year, Month, Day}</c>.</p>
+ <p>The time zone and daylight saving time correction depend on
+ the underlying OS.</p>
+ <pre>
+> <input>date().</input>
+{1995,2,19}</pre>
+ </desc>
+ </func>
+ <func>
+ <name>decode_packet(Type,Bin,Options) -> {ok,Packet,Rest} | {more,Length} | {error,Reason}</name>
+ <fsummary>Extracts a protocol packet from a binary</fsummary>
+ <type>
+ <v>Bin = binary()</v>
+ <v>Options = [Opt]</v>
+ <v>Packet = binary() | HttpPacket</v>
+ <v>Rest = binary()</v>
+ <v>Length = int() | undefined</v>
+ <v>Reason = term()</v>
+ <v>&nbsp;Type, Opt -- see below</v>
+ <v></v>
+ <v>HttpPacket = HttpRequest | HttpResponse | HttpHeader | http_eoh | HttpError</v>
+ <v>HttpRequest = {http_request, HttpMethod, HttpUri, HttpVersion}</v>
+ <v>HttpResponse = {http_response, HttpVersion, integer(), HttpString}</v>
+ <v>HttpHeader = {http_header, int(), HttpField, Reserved=term(), Value=HttpString}</v>
+ <v>HttpError = {http_error, HttpString}</v>
+ <v>HttpMethod = HttpMethodAtom | HttpString</v>
+ <v>HttpMethodAtom = 'OPTIONS' | 'GET' | 'HEAD' | 'POST' | 'PUT' | 'DELETE' | 'TRACE'</v>
+ <v>HttpUri = '*' | {absoluteURI, http|https, Host=HttpString, Port=int()|undefined, Path=HttpString} |
+ {scheme, Scheme=HttpString, HttpString} | {abs_path, HttpString} | HttpString</v>
+ <v>HttpVersion = {Major=int(), Minor=int()}</v>
+ <v>HttpString = string() | binary()</v>
+ <v>HttpField = HttpFieldAtom | HttpString</v>
+ <v>HttpFieldAtom = 'Cache-Control' | 'Connection' | 'Date' | 'Pragma' | 'Transfer-Encoding' | 'Upgrade' | 'Via' | 'Accept' | 'Accept-Charset' | 'Accept-Encoding' | 'Accept-Language' | 'Authorization' | 'From' | 'Host' | 'If-Modified-Since' | 'If-Match' | 'If-None-Match' | 'If-Range' | 'If-Unmodified-Since' | 'Max-Forwards' | 'Proxy-Authorization' | 'Range' | 'Referer' | 'User-Agent' | 'Age' | 'Location' | 'Proxy-Authenticate' | 'Public' | 'Retry-After' | 'Server' | 'Vary' | 'Warning' | 'Www-Authenticate' | 'Allow' | 'Content-Base' | 'Content-Encoding' | 'Content-Language' | 'Content-Length' | 'Content-Location' | 'Content-Md5' | 'Content-Range' | 'Content-Type' | 'Etag' | 'Expires' | 'Last-Modified' | 'Accept-Ranges' | 'Set-Cookie' | 'Set-Cookie2' | 'X-Forwarded-For' | 'Cookie' | 'Keep-Alive' | 'Proxy-Connection'</v>
+ <v></v>
+ </type>
+ <desc>
+ <p>Decodes the binary <c>Bin</c> according to the packet
+ protocol specified by <c>Type</c>. Very similar to the packet
+ handling done by sockets with the option {packet,Type}.</p>
+ <p>If an entire packet is contained in <c>Bin</c> it is
+ returned together with the remainder of the binary as
+ <c>{ok,Packet,Rest}</c>.</p>
+ <p>If <c>Bin</c> does not contain the entire packet,
+ <c>{more,Length}</c> is returned. <c>Length</c> is either the
+ expected <em>total size</em> of the packet or <c>undefined</c>
+ if the expected packet size is not known. <c>decode_packet</c>
+ can then be called again with more data added.</p>
+ <p>If the packet does not conform to the protocol format
+ <c>{error,Reason}</c> is returned.</p>
+ <p>The following values of <c>Type</c> are valid:</p>
+ <taglist>
+ <tag><c>raw | 0</c></tag>
+ <item>
+ <p>No packet handling is done. Entire binary is
+ returned unless it is empty.</p>
+ </item>
+ <tag><c>1 | 2 | 4</c></tag>
+ <item>
+ <p>Packets consist of a header specifying the number of
+ bytes in the packet, followed by that number of bytes.
+ The length of header can be one, two, or four bytes;
+ the order of the bytes is big-endian. The header
+ will be stripped off when the packet is returned.</p>
+ </item>
+ <tag><c>line</c></tag>
+ <item>
+ <p>A packet is a line terminated with newline. The
+ newline character is included in the returned packet
+ unless the line was truncated according to the option
+ <c>line_length</c>.</p>
+ </item>
+ <tag><c>asn1 | cdr | sunrm | fcgi | tpkt</c></tag>
+ <item>
+ <p>The header is <em>not</em> stripped off.</p>
+ <p>The meanings of the packet types are as follows:</p>
+ <taglist>
+ <tag><c>asn1</c> - ASN.1 BER</tag><item></item>
+ <tag><c>sunrm</c> - Sun's RPC encoding</tag><item></item>
+ <tag><c>cdr</c> - CORBA (GIOP 1.1)</tag><item></item>
+ <tag><c>fcgi</c> - Fast CGI</tag><item></item>
+ <tag><c>tpkt</c> - TPKT format [RFC1006]</tag><item></item>
+ </taglist>
+ </item>
+ <tag><c>http | httph | http_bin | httph_bin</c></tag>
+ <item>
+ <p>The Hypertext Transfer Protocol. The packets
+ are returned with the format according to
+ <c>HttpPacket</c> described above. A packet is either a
+ request, a response, a header or an end of header
+ mark. Invalid lines are returned as <c>HttpError</c>.</p>
+ <p>Recognized request methods and header fields are returned as atoms.
+ Others are returned as strings.</p>
+ <p>The protocol type <c>http</c> should only be used for
+ the first line when a <c>HttpRequest</c> or a
+ <c>HttpResponse</c> is expected. The following calls
+ should use <c>httph</c> to get <c>HttpHeader</c>'s until
+ <c>http_eoh</c> is returned that marks the end of the
+ headers and the beginning of any following message body.</p>
+ <p>The variants <c>http_bin</c> and <c>httph_bin</c> will return
+ strings (<c>HttpString</c>) as binaries instead of lists.</p>
+ </item>
+ </taglist>
+ <p>The following options are available:</p>
+ <taglist>
+ <tag><c>{packet_size, int()}</c></tag>
+ <item><p>Sets the max allowed size of the packet body. If
+ the packet header indicates that the length of the
+ packet is longer than the max allowed length, the packet
+ is considered invalid. Default is 0 which means no
+ size limit.</p>
+ </item>
+ <tag><c>{line_length, int()}</c></tag>
+ <item><p>Applies only to line oriented protocols
+ (<c>line</c>, <c>http</c>). Lines longer than this
+ will be truncated.</p>
+ </item>
+ </taglist>
+ <pre>
+> <input>erlang:decode_packet(1,&lt;&lt;3,"abcd"&gt;&gt;,[]).</input>
+{ok,&lt;&lt;"abc"&gt;&gt;,&lt;&lt;"d"&gt;&gt;}
+> <input>erlang:decode_packet(1,&lt;&lt;5,"abcd"&gt;&gt;,[]).</input>
+{more,6}</pre>
+ </desc>
+ </func>
+ <func>
+ <name>delete_module(Module) -> true | undefined</name>
+ <fsummary>Make the current code for a module old</fsummary>
+ <type>
+ <v>Module = atom()</v>
+ </type>
+ <desc>
+ <p>Makes the current code for <c>Module</c> become old code, and
+ deletes all references for this module from the export table.
+ Returns <c>undefined</c> if the module does not exist,
+ otherwise <c>true</c>.</p>
+ <warning>
+ <p>This BIF is intended for the code server (see
+ <seealso marker="kernel:code">code(3)</seealso>) and should not be
+ used elsewhere.</p>
+ </warning>
+ <p>Failure: <c>badarg</c> if there is already an old version of
+ <c>Module</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>erlang:demonitor(MonitorRef) -> true</name>
+ <fsummary>Stop monitoring</fsummary>
+ <type>
+ <v>MonitorRef = ref()</v>
+ </type>
+ <desc>
+ <p>If <c>MonitorRef</c> is a reference which the calling process
+ obtained by calling
+ <seealso marker="#erlang:monitor/2">erlang:monitor/2</seealso>,
+ this monitoring is turned off. If the monitoring is already
+ turned off, nothing happens.</p>
+ <p>Once <c>erlang:demonitor(MonitorRef)</c> has returned it is
+ guaranteed that no <c>{'DOWN', MonitorRef, _, _, _}</c> message
+ due to the monitor will be placed in the callers message queue
+ in the future. A <c>{'DOWN', MonitorRef, _, _, _}</c> message
+ might have been placed in the callers message queue prior to
+ the call, though. Therefore, in most cases, it is advisable
+ to remove such a <c>'DOWN'</c> message from the message queue
+ after monitoring has been stopped.
+ <seealso marker="#erlang:demonitor/2">erlang:demonitor(MonitorRef, [flush])</seealso> can be used instead of
+ <c>erlang:demonitor(MonitorRef)</c> if this cleanup is wanted.</p>
+ <note>
+ <p>Prior to OTP release R11B (erts version 5.5) <c>erlang:demonitor/1</c>
+ behaved completely asynchronous, i.e., the monitor was active
+ until the "demonitor signal" reached the monitored entity. This
+ had one undesirable effect, though. You could never know when
+ you were guaranteed <em>not</em> to receive a <c>DOWN</c> message
+ due to the monitor.</p>
+ <p>Current behavior can be viewed as two combined operations:
+ asynchronously send a "demonitor signal" to the monitored entity
+ and ignore any future results of the monitor. </p>
+ </note>
+ <p>Failure: It is an error if <c>MonitorRef</c> refers to a
+ monitoring started by another process. Not all such cases are
+ cheap to check; if checking is cheap, the call fails with
+ <c>badarg</c> (for example if <c>MonitorRef</c> is a remote
+ reference).</p>
+ </desc>
+ </func>
+ <func>
+ <name>erlang:demonitor(MonitorRef, OptionList) -> true|false</name>
+ <fsummary>Stop monitoring</fsummary>
+ <type>
+ <v>MonitorRef = ref()</v>
+ <v>OptionList = [Option]</v>
+ <v>Option = flush</v>
+ <v>Option = info</v>
+ </type>
+ <desc>
+ <p>The returned value is <c>true</c> unless <c>info</c> is part
+ of <c>OptionList</c>.
+ </p>
+ <p><c>erlang:demonitor(MonitorRef, [])</c> is equivalent to
+ <seealso marker="#erlang:demonitor/1">erlang:demonitor(MonitorRef)</seealso>.</p>
+ <p>Currently the following <c>Option</c>s are valid:</p>
+ <taglist>
+ <tag><c>flush</c></tag>
+ <item>
+ <p>Remove (one) <c>{_, MonitorRef, _, _, _}</c> message,
+ if there is one, from the callers message queue after
+ monitoring has been stopped.</p>
+ <p>Calling <c>erlang:demonitor(MonitorRef, [flush])</c>
+ is equivalent to the following, but more efficient:</p>
+ <code type="none">
+
+ erlang:demonitor(MonitorRef),
+ receive
+\011{_, MonitorRef, _, _, _} ->
+\011 true
+ after 0 ->
+\011 true
+ end</code>
+ </item>
+ <tag><c>info</c></tag>
+ <item>
+ <p>The returned value is one of the following:</p>
+ <taglist>
+ <tag><c>true</c></tag>
+ <item><p>The monitor was found and removed. In this case
+ no <c>'DOWN'</c> message due to this monitor have
+ been nor will be placed in the message queue
+ of the caller.
+ </p>
+ </item>
+ <tag><c>false</c></tag>
+ <item><p>The monitor was not found and could not be removed.
+ This probably because someone already has placed a
+ <c>'DOWN'</c> message corresponding to this monitor
+ in the callers message queue.
+ </p>
+ </item>
+ </taglist>
+ <p>If the <c>info</c> option is combined with the <c>flush</c>
+ option, <c>false</c> will be returned if a flush was needed;
+ otherwise, <c>true</c>.
+ </p>
+ </item>
+ </taglist>
+ <note>
+ <p>More options may be added in the future.</p>
+ </note>
+ <p>Failure: <c>badarg</c> if <c>OptionList</c> is not a list, or
+ if <c>Option</c> is not a valid option, or the same failure as for
+ <seealso marker="#erlang:demonitor/1">erlang:demonitor/1</seealso></p>
+ </desc>
+ </func>
+ <func>
+ <name>disconnect_node(Node) -> bool() | ignored</name>
+ <fsummary>Force the disconnection of a node</fsummary>
+ <type>
+ <v>Node = atom()</v>
+ </type>
+ <desc>
+ <p>Forces the disconnection of a node. This will appear to
+ the node <c>Node</c> as if the local node has crashed. This
+ BIF is mainly used in the Erlang network authentication
+ protocols. Returns <c>true</c> if disconnection succeeds,
+ otherwise <c>false</c>. If the local node is not alive,
+ the function returns <c>ignored</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>erlang:display(Term) -> true</name>
+ <fsummary>Print a term on standard output</fsummary>
+ <type>
+ <v>Term = term()</v>
+ </type>
+ <desc>
+ <p>Prints a text representation of <c>Term</c> on the standard
+ output.</p>
+ <warning>
+ <p>This BIF is intended for debugging only.</p>
+ </warning>
+ </desc>
+ </func>
+ <func>
+ <name>element(N, Tuple) -> term()</name>
+ <fsummary>Get Nth element of a tuple</fsummary>
+ <type>
+ <v>N = 1..tuple_size(Tuple)</v>
+ <v>Tuple = tuple()</v>
+ </type>
+ <desc>
+ <p>Returns the <c>N</c>th element (numbering from 1) of
+ <c>Tuple</c>.</p>
+ <pre>
+> <input>element(2, {a, b, c}).</input>
+b</pre>
+ <p>Allowed in guard tests.</p>
+ </desc>
+ </func>
+ <func>
+ <name>erase() -> [{Key, Val}]</name>
+ <fsummary>Return and delete the process dictionary</fsummary>
+ <type>
+ <v>Key = Val = term()</v>
+ </type>
+ <desc>
+ <p>Returns the process dictionary and deletes it.</p>
+ <pre>
+> <input>put(key1, {1, 2, 3}),</input>
+<input>put(key2, [a, b, c]),</input>
+<input>erase().</input>
+[{key1,{1,2,3}},{key2,[a,b,c]}]</pre>
+ </desc>
+ </func>
+ <func>
+ <name>erase(Key) -> Val | undefined</name>
+ <fsummary>Return and delete a value from the process dictionary</fsummary>
+ <type>
+ <v>Key = Val = term()</v>
+ </type>
+ <desc>
+ <p>Returns the value <c>Val</c> associated with <c>Key</c> and
+ deletes it from the process dictionary. Returns
+ <c>undefined</c> if no value is associated with <c>Key</c>.</p>
+ <pre>
+> <input>put(key1, {merry, lambs, are, playing}),</input>
+<input>X = erase(key1),</input>
+<input>{X, erase(key1)}.</input>
+{{merry,lambs,are,playing},undefined}</pre>
+ </desc>
+ </func>
+ <func>
+ <name>erlang:error(Reason)</name>
+ <fsummary>Stop execution with a given reason</fsummary>
+ <type>
+ <v>Reason = term()</v>
+ </type>
+ <desc>
+ <p>Stops the execution of the calling process with the reason
+ <c>Reason</c>, where <c>Reason</c> is any term. The actual
+ exit reason will be <c>{Reason, Where}</c>, where <c>Where</c>
+ is a list of the functions most recently called (the current
+ function first). Since evaluating this function causes
+ the process to terminate, it has no return value.</p>
+ <pre>
+> <input>catch erlang:error(foobar).</input>
+{'EXIT',{foobar,[{erl_eval,do_apply,5},
+ {erl_eval,expr,5},
+ {shell,exprs,6},
+ {shell,eval_exprs,6},
+ {shell,eval_loop,3}]}}</pre>
+ </desc>
+ </func>
+ <func>
+ <name>erlang:error(Reason, Args)</name>
+ <fsummary>Stop execution with a given reason</fsummary>
+ <type>
+ <v>Reason = term()</v>
+ <v>Args = [term()]</v>
+ </type>
+ <desc>
+ <p>Stops the execution of the calling process with the reason
+ <c>Reason</c>, where <c>Reason</c> is any term. The actual
+ exit reason will be <c>{Reason, Where}</c>, where <c>Where</c>
+ is a list of the functions most recently called (the current
+ function first). <c>Args</c> is expected to be the list of
+ arguments for the current function; in Beam it will be used
+ to provide the actual arguments for the current function in
+ the <c>Where</c> term. Since evaluating this function causes
+ the process to terminate, it has no return value.</p>
+ </desc>
+ </func>
+ <func>
+ <name>exit(Reason)</name>
+ <fsummary>Stop execution with a given reason</fsummary>
+ <type>
+ <v>Reason = term()</v>
+ </type>
+ <desc>
+ <p>Stops the execution of the calling process with the exit
+ reason <c>Reason</c>, where <c>Reason</c> is any term. Since
+ evaluating this function causes the process to terminate, it
+ has no return value.</p>
+ <pre>
+> <input>exit(foobar).</input>
+** exception exit: foobar
+> <input>catch exit(foobar).</input>
+{'EXIT',foobar}</pre>
+ </desc>
+ </func>
+ <func>
+ <name>exit(Pid, Reason) -> true</name>
+ <fsummary>Send an exit signal to a process</fsummary>
+ <type>
+ <v>Pid = pid()</v>
+ <v>Reason = term()</v>
+ </type>
+ <desc>
+ <p>Sends an exit signal with exit reason <c>Reason</c> to
+ the process <c>Pid</c>.</p>
+ <p>The following behavior apply if <c>Reason</c> is any term
+ except <c>normal</c> or <c>kill</c>:</p>
+ <p>If <c>Pid</c> is not trapping exits, <c>Pid</c> itself will
+ exit with exit reason <c>Reason</c>. If <c>Pid</c> is trapping
+ exits, the exit signal is transformed into a message
+ <c>{'EXIT', From, Reason}</c> and delivered to the message
+ queue of <c>Pid</c>. <c>From</c> is the pid of the process
+ which sent the exit signal. See also
+ <seealso marker="#process_flag/2">process_flag/2</seealso>.</p>
+ <p>If <c>Reason</c> is the atom <c>normal</c>, <c>Pid</c> will
+ not exit. If it is trapping exits, the exit signal is
+ transformed into a message <c>{'EXIT', From, normal}</c>
+ and delivered to its message queue.</p>
+ <p>If <c>Reason</c> is the atom <c>kill</c>, that is if
+ <c>exit(Pid, kill)</c> is called, an untrappable exit signal
+ is sent to <c>Pid</c> which will unconditionally exit with
+ exit reason <c>killed</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>float(Number) -> float()</name>
+ <fsummary>Convert a number to a float</fsummary>
+ <type>
+ <v>Number = number()</v>
+ </type>
+ <desc>
+ <p>Returns a float by converting <c>Number</c> to a float.</p>
+ <pre>
+> <input>float(55).</input>
+55.0</pre>
+ <p>Allowed in guard tests.</p>
+ <note>
+ <p>Note that if used on the top-level in a guard, it will
+ test whether the argument is a floating point number; for
+ clarity, use
+ <seealso marker="#is_float/1">is_float/1</seealso> instead.</p>
+ <p>When <c>float/1</c> is used in an expression in a guard,
+ such as '<c>float(A) == 4.0</c>', it converts a number as
+ described above.</p>
+ </note>
+ </desc>
+ </func>
+ <func>
+ <name>float_to_list(Float) -> string()</name>
+ <fsummary>Text representation of a float</fsummary>
+ <type>
+ <v>Float = float()</v>
+ </type>
+ <desc>
+ <p>Returns a string which corresponds to the text
+ representation of <c>Float</c>.</p>
+ <pre>
+> <input>float_to_list(7.0).</input>
+"7.00000000000000000000e+00"</pre>
+ </desc>
+ </func>
+ <func>
+ <name>erlang:fun_info(Fun) -> [{Item, Info}]</name>
+ <fsummary>Information about a fun</fsummary>
+ <type>
+ <v>Fun = fun()</v>
+ <v>Item, Info -- see below</v>
+ </type>
+ <desc>
+ <p>Returns a list containing information about the fun
+ <c>Fun</c>. Each element of the list is a tuple. The order of
+ the tuples is not defined, and more tuples may be added in a
+ future release.</p>
+ <warning>
+ <p>This BIF is mainly intended for debugging, but it can
+ occasionally be useful in library functions that might need
+ to verify, for instance, the arity of a fun.</p>
+ </warning>
+ <p>There are two types of funs with slightly different
+ semantics:</p>
+ <p>A fun created by <c>fun M:F/A</c> is called an
+ <em>external</em> fun. Calling it will always call the
+ function <c>F</c> with arity <c>A</c> in the latest code for
+ module <c>M</c>. Note that module <c>M</c> does not even need
+ to be loaded when the fun <c>fun M:F/A</c> is created.</p>
+ <p>All other funs are called <em>local</em>. When a local fun
+ is called, the same version of the code that created the fun
+ will be called (even if newer version of the module has been
+ loaded).</p>
+ <p>The following elements will always be present in the list
+ for both local and external funs:</p>
+ <taglist>
+ <tag><c>{type, Type}</c></tag>
+ <item>
+ <p><c>Type</c> is either <c>local</c> or <c>external</c>.</p>
+ </item>
+ <tag><c>{module, Module}</c></tag>
+ <item>
+ <p><c>Module</c> (an atom) is the module name.</p>
+ <p>If <c>Fun</c> is a local fun, <c>Module</c> is the module
+ in which the fun is defined.</p>
+ <p>If <c>Fun</c> is an external fun, <c>Module</c> is the
+ module that the fun refers to.</p>
+ </item>
+ <tag><c>{name, Name}</c></tag>
+ <item>
+ <p><c>Name</c> (an atom) is a function name.</p>
+ <p>If <c>Fun</c> is a local fun, <c>Name</c> is the name
+ of the local function that implements the fun.
+ (This name was generated by the compiler, and is generally
+ only of informational use. As it is a local function, it
+ is not possible to call it directly.)
+ If no code is currently loaded for the fun, <c>[]</c>
+ will be returned instead of an atom.</p>
+ <p>If <c>Fun</c> is an external fun, <c>Name</c> is the name
+ of the exported function that the fun refers to.</p>
+ </item>
+ <tag><c>{arity, Arity}</c></tag>
+ <item>
+ <p><c>Arity</c> is the number of arguments that the fun
+ should be called with.</p>
+ </item>
+ <tag><c>{env, Env}</c></tag>
+ <item>
+ <p><c>Env</c> (a list) is the environment or free variables
+ for the fun. (For external funs, the returned list is
+ always empty.)</p>
+ </item>
+ </taglist>
+ <p>The following elements will only be present in the list if
+ <c>Fun</c> is local:</p>
+ <taglist>
+ <tag><c>{pid, Pid}</c></tag>
+ <item>
+ <p><c>Pid</c> is the pid of the process that originally
+ created the fun.</p>
+ </item>
+ <tag><c>{index, Index}</c></tag>
+ <item>
+ <p><c>Index</c> (an integer) is an index into the module's
+ fun table.</p>
+ </item>
+ <tag><c>{new_index, Index}</c></tag>
+ <item>
+ <p><c>Index</c> (an integer) is an index into the module's
+ fun table.</p>
+ </item>
+ <tag><c>{new_uniq, Uniq}</c></tag>
+ <item>
+ <p><c>Uniq</c> (a binary) is a unique value for this fun.</p>
+ </item>
+ <tag><c>{uniq, Uniq}</c></tag>
+ <item>
+ <p><c>Uniq</c> (an integer) is a unique value for this fun.</p>
+ </item>
+ </taglist>
+ </desc>
+ </func>
+ <func>
+ <name>erlang:fun_info(Fun, Item) -> {Item, Info}</name>
+ <fsummary>Information about a fun</fsummary>
+ <type>
+ <v>Fun = fun()</v>
+ <v>Item, Info -- see below</v>
+ </type>
+ <desc>
+ <p>Returns information about <c>Fun</c> as specified by
+ <c>Item</c>, in the form <c>{Item,Info}</c>.</p>
+ <p>For any fun, <c>Item</c> can be any of the atoms
+ <c>module</c>, <c>name</c>, <c>arity</c>, or <c>env</c>.</p>
+ <p>For a local fun, <c>Item</c> can also be any of the atoms
+ <c>index</c>, <c>new_index</c>, <c>new_uniq</c>,
+ <c>uniq</c>, and <c>pid</c>. For an external fun, the value
+ of any of these items is always the atom <c>undefined</c>.</p>
+ <p>See
+ <seealso marker="#erlang:fun_info/1">erlang:fun_info/1</seealso>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>erlang:fun_to_list(Fun) -> string()</name>
+ <fsummary>Text representation of a fun</fsummary>
+ <type>
+ <v>Fun = fun()</v>
+ </type>
+ <desc>
+ <p>Returns a string which corresponds to the text
+ representation of <c>Fun</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>erlang:function_exported(Module, Function, Arity) -> bool()</name>
+ <fsummary>Check if a function is exported and loaded</fsummary>
+ <type>
+ <v>Module = Function = atom()</v>
+ <v>Arity = int()</v>
+ </type>
+ <desc>
+ <p>Returns <c>true</c> if the module <c>Module</c> is loaded
+ and contains an exported function <c>Function/Arity</c>;
+ otherwise <c>false</c>.</p>
+ <p>Returns <c>false</c> for any BIF (functions implemented in C
+ rather than in Erlang).</p>
+ </desc>
+ </func>
+ <func>
+ <name>garbage_collect() -> true</name>
+ <fsummary>Force an immediate garbage collection of the calling process</fsummary>
+ <desc>
+ <p>Forces an immediate garbage collection of the currently
+ executing process. The function should not be used, unless
+ it has been noticed -- or there are good reasons to suspect --
+ 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>garbage_collect(Pid) -> bool()</name>
+ <fsummary>Force an immediate garbage collection of a process</fsummary>
+ <type>
+ <v>Pid = pid()</v>
+ </type>
+ <desc>
+ <p>Works like <c>erlang:garbage_collect()</c> but on any
+ process. The same caveats apply. Returns <c>false</c> if
+ <c>Pid</c> refers to a dead process; <c>true</c> otherwise.</p>
+ </desc>
+ </func>
+ <func>
+ <name>get() -> [{Key, Val}]</name>
+ <fsummary>Return the process dictionary</fsummary>
+ <type>
+ <v>Key = Val = term()</v>
+ </type>
+ <desc>
+ <p>Returns the process dictionary as a list of
+ <c>{Key, Val}</c> tuples.</p>
+ <pre>
+> <input>put(key1, merry),</input>
+<input>put(key2, lambs),</input>
+<input>put(key3, {are, playing}),</input>
+<input>get().</input>
+[{key1,merry},{key2,lambs},{key3,{are,playing}}]</pre>
+ </desc>
+ </func>
+ <func>
+ <name>get(Key) -> Val | undefined</name>
+ <fsummary>Return a value from the process dictionary</fsummary>
+ <type>
+ <v>Key = Val = term()</v>
+ </type>
+ <desc>
+ <p>Returns the value <c>Val</c>associated with <c>Key</c> in
+ the process dictionary, or <c>undefined</c> if <c>Key</c>
+ does not exist.</p>
+ <pre>
+> <input>put(key1, merry),</input>
+<input>put(key2, lambs),</input>
+<input>put({any, [valid, term]}, {are, playing}),</input>
+<input>get({any, [valid, term]}).</input>
+{are,playing}</pre>
+ </desc>
+ </func>
+ <func>
+ <name>erlang:get_cookie() -> Cookie | nocookie</name>
+ <fsummary>Get the magic cookie of the local node</fsummary>
+ <type>
+ <v>Cookie = atom()</v>
+ </type>
+ <desc>
+ <p>Returns the magic cookie of the local node, if the node is
+ alive; otherwise the atom <c>nocookie</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>get_keys(Val) -> [Key]</name>
+ <fsummary>Return a list of keys from the process dictionary</fsummary>
+ <type>
+ <v>Val = Key = term()</v>
+ </type>
+ <desc>
+ <p>Returns a list of keys which are associated with the value
+ <c>Val</c> in the process dictionary.</p>
+ <pre>
+> <input>put(mary, {1, 2}),</input>
+<input>put(had, {1, 2}),</input>
+<input>put(a, {1, 2}),</input>
+<input>put(little, {1, 2}),</input>
+<input>put(dog, {1, 3}),</input>
+<input>put(lamb, {1, 2}),</input>
+<input>get_keys({1, 2}).</input>
+[mary,had,a,little,lamb]</pre>
+ </desc>
+ </func>
+ <func>
+ <name>erlang:get_stacktrace() -> [{Module, Function, Arity | Args}]</name>
+ <fsummary>Get the call stack back-trace of the last exception</fsummary>
+ <type>
+ <v>Module = Function = atom()</v>
+ <v>Arity = int()</v>
+ <v>Args = [term()]</v>
+ </type>
+ <desc>
+ <p>Get the call stack back-trace (<em>stacktrace</em>) of the last
+ exception in the calling process as a list of
+ <c>{Module,Function,Arity}</c> tuples.
+ The <c>Arity</c> field in the first tuple may be the argument
+ list of that function call instead of an arity integer,
+ depending on the exception.</p>
+ <p>If there has not been any exceptions in a process, the
+ stacktrace is []. After a code change for the process,
+ the stacktrace may also be reset to [].</p>
+ <p>The stacktrace is the same data as the <c>catch</c> operator
+ returns, for example:</p>
+ <p><c>{'EXIT',{badarg,Stacktrace}} = catch abs(x)</c></p>
+ <p>See also
+ <seealso marker="#erlang:error/1">erlang:error/1</seealso> and
+ <seealso marker="#erlang:error/2">erlang:error/2</seealso>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>group_leader() -> GroupLeader</name>
+ <fsummary>Get the group leader for the calling process</fsummary>
+ <type>
+ <v>GroupLeader = pid()</v>
+ </type>
+ <desc>
+ <p>Returns the pid of the group leader for the process which
+ evaluates the function.</p>
+ <p>Every process is a member of some process group and all
+ groups have a <em>group leader</em>. All IO from the group
+ is channeled to the group leader. When a new process is
+ spawned, it gets the same group leader as the spawning
+ process. Initially, at system start-up, <c>init</c> is both
+ its own group leader and the group leader of all processes.</p>
+ </desc>
+ </func>
+ <func>
+ <name>group_leader(GroupLeader, Pid) -> true</name>
+ <fsummary>Set the group leader for a process</fsummary>
+ <type>
+ <v>GroupLeader = Pid = pid()</v>
+ </type>
+ <desc>
+ <p>Sets the group leader of <c>Pid</c> to <c>GroupLeader</c>.
+ Typically, this is used when a processes started from a
+ certain shell should have another group leader than
+ <c>init</c>.</p>
+ <p>See also
+ <seealso marker="#group_leader/0">group_leader/0</seealso>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>halt()</name>
+ <fsummary>Halt the Erlang runtime system and indicate normal exit to the calling environment</fsummary>
+ <desc>
+ <p>Halts the Erlang runtime system and indicates normal exit to
+ the calling environment. Has no return value.</p>
+ <pre>
+> <input>halt().</input>
+os_prompt%</pre>
+ </desc>
+ </func>
+ <func>
+ <name>halt(Status)</name>
+ <fsummary>Halt the Erlang runtime system</fsummary>
+ <type>
+ <v>Status = int()>=0 | string()</v>
+ </type>
+ <desc>
+ <p><c>Status</c> must be a non-negative integer, or a string.
+ Halts the Erlang runtime system. Has no return value.
+ If <c>Status</c> is an integer, it is returned as an exit
+ status of Erlang to the calling environment.
+ If <c>Status</c> is a string, produces an Erlang crash dump
+ with <c>String</c> as slogan, and then exits with a non-zero
+ status code.</p>
+ <p>Note that on many platforms, only the status codes 0-255 are
+ supported by the operating system.</p>
+ </desc>
+ </func>
+ <func>
+ <name>erlang:hash(Term, Range) -> Hash</name>
+ <fsummary>Hash function (deprecated)</fsummary>
+ <desc>
+ <p>Returns a hash value for <c>Term</c> within the range
+ <c>1..Range</c>. The allowed range is 1..2^27-1.</p>
+ <warning>
+ <p>This BIF is deprecated as the hash value may differ on
+ different architectures. Also the hash values for integer
+ terms larger than 2^27 as well as large binaries are very
+ poor. The BIF is retained for backward compatibility
+ reasons (it may have been used to hash records into a file),
+ but all new code should use one of the BIFs
+ <c>erlang:phash/2</c> or <c>erlang:phash2/1,2</c> instead.</p>
+ </warning>
+ </desc>
+ </func>
+ <func>
+ <name>hd(List) -> term()</name>
+ <fsummary>Head of a list</fsummary>
+ <type>
+ <v>List = [term()]</v>
+ </type>
+ <desc>
+ <p>Returns the head of <c>List</c>, that is, the first element.</p>
+ <pre>
+> <input>hd([1,2,3,4,5]).</input>
+1</pre>
+ <p>Allowed in guard tests.</p>
+ <p>Failure: <c>badarg</c> if <c>List</c> is the empty list [].</p>
+ </desc>
+ </func>
+ <func>
+ <name>erlang:hibernate(Module, Function, Args)</name>
+ <fsummary>Hibernate a process until a message is sent to it</fsummary>
+ <type>
+ <v>Module = Function = atom()</v>
+ <v>Args = [term()]</v>
+ </type>
+ <desc>
+ <p>Puts the calling process into a wait state where its memory
+ allocation has been reduced as much as possible, which is
+ useful if the process does not expect to receive any messages
+ in the near future.</p>
+ <p>The process will be awaken when a message is sent to it, and
+ control will resume in <c>Module:Function</c> with
+ the arguments given by <c>Args</c> with the call stack
+ emptied, meaning that the process will terminate when that
+ function returns. Thus <c>erlang:hibernate/3</c> will never
+ return to its caller.</p>
+ <p>If the process has any message in its message queue,
+ the process will be awaken immediately in the same way as
+ described above.</p>
+ <p>In more technical terms, what <c>erlang:hibernate/3</c> does
+ is the following. It discards the call stack for the process.
+ Then it garbage collects the process. After the garbage
+ collection, all live data is in one continuous heap. The heap
+ is then shrunken to the exact same size as the live data
+ which it holds (even if that size is less than the minimum
+ heap size for the process).</p>
+ <p>If the size of the live data in the process is less than
+ the minimum heap size, the first garbage collection occurring
+ after the process has been awaken will ensure that the heap
+ size is changed to a size not smaller than the minimum heap
+ size.</p>
+ <p>Note that emptying the call stack means that any surrounding
+ <c>catch</c> is removed and has to be re-inserted after
+ hibernation. One effect of this is that processes started
+ using <c>proc_lib</c> (also indirectly, such as
+ <c>gen_server</c> processes), should use
+ <seealso marker="stdlib:proc_lib#hibernate/3">proc_lib:hibernate/3</seealso>
+ instead to ensure that the exception handler continues to work
+ when the process wakes up.</p>
+ </desc>
+ </func>
+ <func>
+ <name>integer_to_list(Integer) -> string()</name>
+ <fsummary>Text representation of an integer</fsummary>
+ <type>
+ <v>Integer = int()</v>
+ </type>
+ <desc>
+ <p>Returns a string which corresponds to the text
+ representation of <c>Integer</c>.</p>
+ <pre>
+> <input>integer_to_list(77).</input>
+"77"</pre>
+ </desc>
+ </func>
+ <func>
+ <name>erlang:integer_to_list(Integer, Base) -> string()</name>
+ <fsummary>Text representation of an integer</fsummary>
+ <type>
+ <v>Integer = int()</v>
+ <v>Base = 2..36</v>
+ </type>
+ <desc>
+ <p>Returns a string which corresponds to the text
+ representation of <c>Integer</c> in base <c>Base</c>.</p>
+ <pre>
+> <input>erlang:integer_to_list(1023, 16).</input>
+"3FF"</pre>
+ </desc>
+ </func>
+ <func>
+ <name>iolist_to_binary(IoListOrBinary) -> binary()</name>
+ <fsummary>Convert an iolist to a binary</fsummary>
+ <type>
+ <v>IoListOrBinary = iolist() | binary()</v>
+ </type>
+ <desc>
+ <p>Returns a binary which is made from the integers and
+ binaries in <c>IoListOrBinary</c>.</p>
+ <pre>
+> <input>Bin1 = &lt;&lt;1,2,3&gt;&gt;.</input>
+&lt;&lt;1,2,3&gt;&gt;
+> <input>Bin2 = &lt;&lt;4,5&gt;&gt;.</input>
+&lt;&lt;4,5&gt;&gt;
+> <input>Bin3 = &lt;&lt;6&gt;&gt;.</input>
+&lt;&lt;6&gt;&gt;
+> <input>iolist_to_binary([Bin1,1,[2,3,Bin2],4|Bin3]).</input>
+&lt;&lt;1,2,3,1,2,3,4,5,4,6&gt;&gt;</pre>
+ </desc>
+ </func>
+ <func>
+ <name>iolist_size(Item) -> int()</name>
+ <fsummary>Size of an iolist</fsummary>
+ <type>
+ <v>Item = iolist() | binary()</v>
+ </type>
+ <desc>
+ <p>Returns an integer which is the size in bytes
+ of the binary that would be the result of
+ <c>iolist_to_binary(Item)</c>.</p>
+ <pre>
+> <input>iolist_size([1,2|&lt;&lt;3,4>>]).</input>
+4</pre>
+ </desc>
+ </func>
+ <func>
+ <name>is_alive() -> bool()</name>
+ <fsummary>Check whether the local node is alive</fsummary>
+ <desc>
+ <p>Returns <c>true</c> if the local node is alive; that is, if
+ the node can be part of a distributed system. Otherwise, it
+ returns <c>false</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>is_atom(Term) -> bool()</name>
+ <fsummary>Check whether a term is an atom</fsummary>
+ <type>
+ <v>Term = term()</v>
+ </type>
+ <desc>
+ <p>Returns <c>true</c> if <c>Term</c> is an atom;
+ otherwise returns <c>false</c>.</p>
+ <p>Allowed in guard tests.</p>
+ </desc>
+ </func>
+ <func>
+ <name>is_binary(Term) -> bool()</name>
+ <fsummary>Check whether a term is a binary</fsummary>
+ <type>
+ <v>Term = term()</v>
+ </type>
+ <desc>
+ <p>Returns <c>true</c> if <c>Term</c> is a binary;
+ otherwise returns <c>false</c>.</p>
+
+ <p>A binary always contains a complete number of bytes.</p>
+
+ <p>Allowed in guard tests.</p>
+ </desc>
+ </func>
+ <func>
+ <name>is_bitstring(Term) -> bool()</name>
+ <fsummary>Check whether a term is a bitstring</fsummary>
+ <type>
+ <v>Term = term()</v>
+ </type>
+ <desc>
+ <p>Returns <c>true</c> if <c>Term</c> is a bitstring (including a binary);
+ otherwise returns <c>false</c>.</p>
+
+ <p>Allowed in guard tests.</p>
+ </desc>
+ </func>
+ <func>
+ <name>is_boolean(Term) -> bool()</name>
+ <fsummary>Check whether a term is a boolean</fsummary>
+ <type>
+ <v>Term = term()</v>
+ </type>
+ <desc>
+ <p>Returns <c>true</c> if <c>Term</c> is
+ either the atom <c>true</c> or the atom <c>false</c>
+ (i.e. a boolean); otherwise returns <c>false</c>.</p>
+ <p>Allowed in guard tests.</p>
+ </desc>
+ </func>
+ <func>
+ <name>erlang:is_builtin(Module, Function, Arity) -> bool()</name>
+ <fsummary>Check if a function is a BIF implemented in C</fsummary>
+ <type>
+ <v>Module = Function = atom()</v>
+ <v>Arity = int()</v>
+ </type>
+ <desc>
+ <p>Returns <c>true</c> if <c>Module:Function/Arity</c> is
+ a BIF implemented in C; otherwise returns <c>false</c>.
+ This BIF is useful for builders of cross reference tools.</p>
+ </desc>
+ </func>
+ <func>
+ <name>is_float(Term) -> bool()</name>
+ <fsummary>Check whether a term is a float</fsummary>
+ <type>
+ <v>Term = term()</v>
+ </type>
+ <desc>
+ <p>Returns <c>true</c> if <c>Term</c> is a floating point
+ number; otherwise returns <c>false</c>.</p>
+ <p>Allowed in guard tests.</p>
+ </desc>
+ </func>
+ <func>
+ <name>is_function(Term) -> bool()</name>
+ <fsummary>Check whether a term is a fun</fsummary>
+ <type>
+ <v>Term = term()</v>
+ </type>
+ <desc>
+ <p>Returns <c>true</c> if <c>Term</c> is a fun; otherwise
+ returns <c>false</c>.</p>
+ <p>Allowed in guard tests.</p>
+ </desc>
+ </func>
+ <func>
+ <name>is_function(Term, Arity) -> bool()</name>
+ <fsummary>Check whether a term is a fun with a given arity</fsummary>
+ <type>
+ <v>Term = term()</v>
+ <v>Arity = int()</v>
+ </type>
+ <desc>
+ <p>Returns <c>true</c> if <c>Term</c> is a fun that can be
+ applied with <c>Arity</c> number of arguments; otherwise
+ returns <c>false</c>.</p>
+ <p>Allowed in guard tests.</p>
+ <warning>
+ <p>Currently, <c>is_function/2</c> will also return
+ <c>true</c> if the first argument is a tuple fun (a tuple
+ containing two atoms). In a future release, tuple funs will
+ no longer be supported and <c>is_function/2</c> will return
+ <c>false</c> if given a tuple fun.</p>
+ </warning>
+ </desc>
+ </func>
+ <func>
+ <name>is_integer(Term) -> bool()</name>
+ <fsummary>Check whether a term is an integer</fsummary>
+ <type>
+ <v>Term = term()</v>
+ </type>
+ <desc>
+ <p>Returns <c>true</c> if <c>Term</c> is an integer;
+ otherwise returns <c>false</c>.</p>
+ <p>Allowed in guard tests.</p>
+ </desc>
+ </func>
+ <func>
+ <name>is_list(Term) -> bool()</name>
+ <fsummary>Check whether a term is a list</fsummary>
+ <type>
+ <v>Term = term()</v>
+ </type>
+ <desc>
+ <p>Returns <c>true</c> if <c>Term</c> is a list with
+ zero or more elements; otherwise returns <c>false</c>.</p>
+ <p>Allowed in guard tests.</p>
+ </desc>
+ </func>
+ <func>
+ <name>is_number(Term) -> bool()</name>
+ <fsummary>Check whether a term is a number</fsummary>
+ <type>
+ <v>Term = term()</v>
+ </type>
+ <desc>
+ <p>Returns <c>true</c> if <c>Term</c> is either an integer or a
+ floating point number; otherwise returns <c>false</c>.</p>
+ <p>Allowed in guard tests.</p>
+ </desc>
+ </func>
+ <func>
+ <name>is_pid(Term) -> bool()</name>
+ <fsummary>Check whether a term is a pid</fsummary>
+ <type>
+ <v>Term = term()</v>
+ </type>
+ <desc>
+ <p>Returns <c>true</c> if <c>Term</c> is a pid (process
+ identifier); otherwise returns <c>false</c>.</p>
+ <p>Allowed in guard tests.</p>
+ </desc>
+ </func>
+ <func>
+ <name>is_port(Term) -> bool()</name>
+ <fsummary>Check whether a term is a port</fsummary>
+ <type>
+ <v>Term = term()</v>
+ </type>
+ <desc>
+ <p>Returns <c>true</c> if <c>Term</c> is a port identifier;
+ otherwise returns <c>false</c>.</p>
+ <p>Allowed in guard tests.</p>
+ </desc>
+ </func>
+ <func>
+ <name>is_process_alive(Pid) -> bool()</name>
+ <fsummary>Check whether a process is alive</fsummary>
+ <type>
+ <v>Pid = pid()</v>
+ </type>
+ <desc>
+ <p>
+ <c>Pid</c> must refer to a process at the local node.
+ Returns <c>true</c> if the process exists and is alive, that
+ is, is not exiting and has not exited. Otherwise, returns
+ <c>false</c>.
+ </p>
+ </desc>
+ </func>
+ <func>
+ <name>is_record(Term, RecordTag) -> bool()</name>
+ <fsummary>Check whether a term appears to be a record</fsummary>
+ <type>
+ <v>Term = term()</v>
+ <v>RecordTag = atom()</v>
+ </type>
+ <desc>
+ <p>Returns <c>true</c> if <c>Term</c> is a tuple and its first
+ element is <c>RecordTag</c>. Otherwise, returns <c>false</c>.</p>
+ <note>
+ <p>Normally the compiler treats calls to <c>is_record/2</c>
+ specially. It emits code to verify that <c>Term</c> is a
+ tuple, that its first element is <c>RecordTag</c>, and that
+ the size is correct. However, if the <c>RecordTag</c> is
+ not a literal atom, the <c>is_record/2</c> BIF will be
+ called instead and the size of the tuple will not be
+ verified.</p>
+ </note>
+ <p>Allowed in guard tests, if <c>RecordTag</c> is a literal
+ atom.</p>
+ </desc>
+ </func>
+ <func>
+ <name>is_record(Term, RecordTag, Size) -> bool()</name>
+ <fsummary>Check whether a term appears to be a record</fsummary>
+ <type>
+ <v>Term = term()</v>
+ <v>RecordTag = atom()</v>
+ <v>Size = int()</v>
+ </type>
+ <desc>
+ <p><c>RecordTag</c> must be an atom. Returns <c>true</c> if
+ <c>Term</c> is a tuple, its first element is <c>RecordTag</c>,
+ and its size is <c>Size</c>. Otherwise, returns <c>false</c>.</p>
+ <p>Allowed in guard tests, provided that <c>RecordTag</c> is
+ a literal atom and <c>Size</c> is a literal integer.</p>
+ <note>
+ <p>This BIF is documented for completeness. In most cases
+ <c>is_record/2</c> should be used.</p>
+ </note>
+ </desc>
+ </func>
+ <func>
+ <name>is_reference(Term) -> bool()</name>
+ <fsummary>Check whether a term is a reference</fsummary>
+ <type>
+ <v>Term = term()</v>
+ </type>
+ <desc>
+ <p>Returns <c>true</c> if <c>Term</c> is a reference;
+ otherwise returns <c>false</c>.</p>
+ <p>Allowed in guard tests.</p>
+ </desc>
+ </func>
+ <func>
+ <name>is_tuple(Term) -> bool()</name>
+ <fsummary>Check whether a term is a tuple</fsummary>
+ <type>
+ <v>Term = term()</v>
+ </type>
+ <desc>
+ <p>Returns <c>true</c> if <c>Term</c> is a tuple;
+ otherwise returns <c>false</c>.</p>
+ <p>Allowed in guard tests.</p>
+ </desc>
+ </func>
+ <func>
+ <name>length(List) -> int()</name>
+ <fsummary>Length of a list</fsummary>
+ <type>
+ <v>List = [term()]</v>
+ </type>
+ <desc>
+ <p>Returns the length of <c>List</c>.</p>
+ <pre>
+> <input>length([1,2,3,4,5,6,7,8,9]).</input>
+9</pre>
+ <p>Allowed in guard tests.</p>
+ </desc>
+ </func>
+ <func>
+ <name>link(Pid) -> true</name>
+ <fsummary>Create a link to another process (or port)</fsummary>
+ <type>
+ <v>Pid = pid() | port()</v>
+ </type>
+ <desc>
+ <p>Creates a link between the calling process and another
+ process (or port) <c>Pid</c>, if there is not such a link
+ already. If a process attempts to create a link to itself,
+ nothing is done. Returns <c>true</c>.</p>
+ <p>If <c>Pid</c> does not exist, the behavior of the BIF depends
+ on if the calling process is trapping exits or not (see
+ <seealso marker="#process_flag/2">process_flag/2</seealso>):</p>
+ <list type="bulleted">
+ <item>If the calling process is not trapping exits, and
+ checking <c>Pid</c> is cheap -- that is, if <c>Pid</c> is
+ local -- <c>link/1</c> fails with reason <c>noproc</c>.</item>
+ <item>Otherwise, if the calling process is trapping exits,
+ and/or <c>Pid</c> is remote, <c>link/1</c> returns
+ <c>true</c>, but an exit signal with reason <c>noproc</c>
+ is sent to the calling process.</item>
+ </list>
+ </desc>
+ </func>
+ <func>
+ <name>list_to_atom(String) -> atom()</name>
+ <fsummary>Convert from text representation to an atom</fsummary>
+ <type>
+ <v>String = string()</v>
+ </type>
+ <desc>
+ <p>Returns the atom whose text representation is <c>String</c>.</p>
+ <pre>
+> <input>list_to_atom("Erlang").</input>
+'Erlang'</pre>
+ </desc>
+ </func>
+ <func>
+ <name>list_to_binary(IoList) -> binary()</name>
+ <fsummary>Convert a list to a binary</fsummary>
+ <type>
+ <v>IoList = iolist()</v>
+ </type>
+ <desc>
+ <p>Returns a binary which is made from the integers and
+ binaries in <c>IoList</c>.</p>
+ <pre>
+> <input>Bin1 = &lt;&lt;1,2,3&gt;&gt;.</input>
+&lt;&lt;1,2,3&gt;&gt;
+> <input>Bin2 = &lt;&lt;4,5&gt;&gt;.</input>
+&lt;&lt;4,5&gt;&gt;
+> <input>Bin3 = &lt;&lt;6&gt;&gt;.</input>
+&lt;&lt;6&gt;&gt;
+> <input>list_to_binary([Bin1,1,[2,3,Bin2],4|Bin3]).</input>
+&lt;&lt;1,2,3,1,2,3,4,5,4,6&gt;&gt;</pre>
+ </desc>
+ </func>
+ <func>
+ <name>list_to_bitstring(BitstringList) -> bitstring()</name>
+ <fsummary>Convert a list to a bitstring</fsummary>
+ <type>
+ <v>BitstringList = [BitstringList | bitstring() | char()]</v>
+ </type>
+ <desc>
+ <p>Returns a bitstring which is made from the integers and
+ bitstrings in <c>BitstringList</c>. (The last tail in <c>BitstringList</c>
+ is allowed to be a bitstring.)</p>
+ <pre>
+> <input>Bin1 = &lt;&lt;1,2,3&gt;&gt;.</input>
+&lt;&lt;1,2,3&gt;&gt;
+> <input>Bin2 = &lt;&lt;4,5&gt;&gt;.</input>
+&lt;&lt;4,5&gt;&gt;
+> <input>Bin3 = &lt;&lt;6,7:4,&gt;&gt;.</input>
+&lt;&lt;6&gt;&gt;
+> <input>list_to_binary([Bin1,1,[2,3,Bin2],4|Bin3]).</input>
+&lt;&lt;1,2,3,1,2,3,4,5,4,6,7:46&gt;&gt;</pre>
+ </desc>
+ </func>
+ <func>
+ <name>list_to_existing_atom(String) -> atom()</name>
+ <fsummary>Convert from text representation to an atom</fsummary>
+ <type>
+ <v>String = string()</v>
+ </type>
+ <desc>
+ <p>Returns the atom whose text representation is <c>String</c>,
+ but only if there already exists such atom.</p>
+ <p>Failure: <c>badarg</c> if there does not already exist an atom
+ whose text representation is <c>String</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>list_to_float(String) -> float()</name>
+ <fsummary>Convert from text representation to a float</fsummary>
+ <type>
+ <v>String = string()</v>
+ </type>
+ <desc>
+ <p>Returns the float whose text representation is <c>String</c>.</p>
+ <pre>
+> <input>list_to_float("2.2017764e+0").</input>
+2.2017764</pre>
+ <p>Failure: <c>badarg</c> if <c>String</c> contains a bad
+ representation of a float.</p>
+ </desc>
+ </func>
+ <func>
+ <name>list_to_integer(String) -> int()</name>
+ <fsummary>Convert from text representation to an integer</fsummary>
+ <type>
+ <v>String = string()</v>
+ </type>
+ <desc>
+ <p>Returns an integer whose text representation is
+ <c>String</c>.</p>
+ <pre>
+> <input>list_to_integer("123").</input>
+123</pre>
+ <p>Failure: <c>badarg</c> if <c>String</c> contains a bad
+ representation of an integer.</p>
+ </desc>
+ </func>
+ <func>
+ <name>erlang:list_to_integer(String, Base) -> int()</name>
+ <fsummary>Convert from text representation to an integer</fsummary>
+ <type>
+ <v>String = string()</v>
+ <v>Base = 2..36</v>
+ </type>
+ <desc>
+ <p>Returns an integer whose text representation in base
+ <c>Base</c> is <c>String</c>.</p>
+ <pre>
+> <input>erlang:list_to_integer("3FF", 16).</input>
+1023</pre>
+ <p>Failure: <c>badarg</c> if <c>String</c> contains a bad
+ representation of an integer.</p>
+ </desc>
+ </func>
+ <func>
+ <name>list_to_pid(String) -> pid()</name>
+ <fsummary>Convert from text representation to a pid</fsummary>
+ <type>
+ <v>String = string()</v>
+ </type>
+ <desc>
+ <p>Returns a pid whose text representation is <c>String</c>.</p>
+ <warning>
+ <p>This BIF is intended for debugging and for use in
+ the Erlang operating system. It should not be used in
+ application programs.</p>
+ </warning>
+ <pre>
+> <input>list_to_pid("&lt;0.4.1>").</input>
+&lt;0.4.1></pre>
+ <p>Failure: <c>badarg</c> if <c>String</c> contains a bad
+ representation of a pid.</p>
+ </desc>
+ </func>
+ <func>
+ <name>list_to_tuple(List) -> tuple()</name>
+ <fsummary>Convert a list to a tuple</fsummary>
+ <type>
+ <v>List = [term()]</v>
+ </type>
+ <desc>
+ <p>Returns a tuple which corresponds to <c>List</c>. <c>List</c>
+ can contain any Erlang terms.</p>
+ <pre>
+> <input>list_to_tuple([share, ['Ericsson_B', 163]]).</input>
+{share, ['Ericsson_B', 163]}</pre>
+ </desc>
+ </func>
+ <func>
+ <name>load_module(Module, Binary) -> {module, Module} | {error, Reason}</name>
+ <fsummary>Load object code for a module</fsummary>
+ <type>
+ <v>Module = atom()</v>
+ <v>Binary = binary()</v>
+ <v>Reason = badfile | not_purged | badfile</v>
+ </type>
+ <desc>
+ <p>If <c>Binary</c> contains the object code for the module
+ <c>Module</c>, this BIF loads that object code. Also, if
+ the code for the module <c>Module</c> already exists, all
+ export references are replaced so they point to the newly
+ loaded code. The previously loaded code is kept in the system
+ as old code, as there may still be processes which are
+ executing that code. It returns either
+ <c>{module, Module}</c>, or <c>{error, Reason}</c> if loading
+ fails. <c>Reason</c> is one of the following:</p>
+ <taglist>
+ <tag><c>badfile</c></tag>
+ <item>
+ <p>The object code in <c>Binary</c> has an incorrect format.</p>
+ </item>
+ <tag><c>not_purged</c></tag>
+ <item>
+ <p><c>Binary</c> contains a module which cannot be loaded
+ because old code for this module already exists.</p>
+ </item>
+ <tag><c>badfile</c></tag>
+ <item>
+ <p>The object code contains code for another module than
+ <c>Module</c></p>
+ </item>
+ </taglist>
+ <warning>
+ <p>This BIF is intended for the code server (see
+ <seealso marker="kernel:code">code(3)</seealso>) and should not be
+ used elsewhere.</p>
+ </warning>
+ </desc>
+ </func>
+ <func>
+ <name>erlang:load_nif(Path, LoadInfo) -> ok | {error, Reason, Text}</name>
+ <fsummary>Load NIF library</fsummary>
+ <type>
+ <v>Path = string()</v>
+ <v>LoadInfo = term()</v>
+ <v>Reason = load_failed | bad_lib | load | reload |
+ upgrade | old_code</v>
+ <v>Text = string()</v>
+ </type>
+ <desc>
+ <warning>
+ <p>This BIF is currently introduced as an experimental
+ feature. The interface may be changed in any way in future
+ releases.</p>
+ </warning>
+ <p>Loads and links a dynamic library containing native
+ implemented functions (NIFs) for a module. <c>Path</c> is a
+ file path to the sharable object/dynamic library file minus
+ the OS-dependant file extension (.so for Unix and .ddl for
+ Windows). See <seealso marker="erl_nif">erl_nif</seealso>
+ on how to implement a NIF library.</p>
+ <p><c>LoadInfo</c> can be any term. It will be passed on to
+ the library as part of the initialization. A good practice is
+ to include a module version number to support future code
+ upgrade scenarios.</p>
+ <p>The call to <c>load_nif/2</c> must be made
+ <em>directly</em> from the Erlang code of the module that the
+ NIF library belongs to.</p>
+ <p>It returns either <c>ok</c>, or <c>{error,Reason,Text}</c>
+ if loading fails. <c>Reason</c> is one of the atoms below,
+ while <c>Text</c> is a human readable string that may give
+ some more information about the failure:</p>
+ <taglist>
+ <tag><c>load_failed</c></tag>
+ <item>
+ <p>The OS failed to load the NIF library.</p>
+ </item>
+ <tag><c>bad_lib</c></tag>
+ <item>
+ <p>The library did not fulfil the requirements as a NIF
+ library of the calling module.</p>
+ </item>
+ <tag><c>load | reload | upgrade</c></tag>
+ <item>
+ <p>The corresponding library callback was not successful.</p>
+ </item>
+ <tag><c>old_code</c></tag>
+ <item>
+ <p>The call to <c>load_nif/2</c> was made from the old
+ code of a module that has been upgraded. This is not
+ allowed.</p>
+ </item>
+ </taglist>
+ </desc>
+ </func>
+ <func>
+ <name>erlang:loaded() -> [Module]</name>
+ <fsummary>List of all loaded modules</fsummary>
+ <type>
+ <v>Module = atom()</v>
+ </type>
+ <desc>
+ <p>Returns a list of all loaded Erlang modules (current and/or
+ old code), including preloaded modules.</p>
+ <p>See also <seealso marker="kernel:code">code(3)</seealso>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>erlang:localtime() -> {Date, Time}</name>
+ <fsummary>Current local date and time</fsummary>
+ <type>
+ <v>Date = {Year, Month, Day}</v>
+ <v>Time = {Hour, Minute, Second}</v>
+ <v>&nbsp;Year = Month = Day = Hour = Minute = Second = int()</v>
+ </type>
+ <desc>
+ <p>Returns the current local date and time
+ <c>{{Year, Month, Day}, {Hour, Minute, Second}}</c>.</p>
+ <p>The time zone and daylight saving time correction depend
+ on the underlying OS.</p>
+ <pre>
+> <input>erlang:localtime().</input>
+{{1996,11,6},{14,45,17}}</pre>
+ </desc>
+ </func>
+ <func>
+ <name>erlang:localtime_to_universaltime({Date1, Time1}) -> {Date2, Time2}</name>
+ <fsummary>Convert from local to Universal Time Coordinated (UTC) date and time</fsummary>
+ <type>
+ <v>Date1 = Date2 = {Year, Month, Day}</v>
+ <v>Time1 = Time2 = {Hour, Minute, Second}</v>
+ <v>&nbsp;Year = Month = Day = Hour = Minute = Second = int()</v>
+ </type>
+ <desc>
+ <p>Converts local date and time to Universal Time Coordinated
+ (UTC), if this is supported by the underlying OS. Otherwise,
+ no conversion is done and <c>{Date1, Time1}</c> is returned.</p>
+ <pre>
+> <input>erlang:localtime_to_universaltime({{1996,11,6},{14,45,17}}).</input>
+{{1996,11,6},{13,45,17}}</pre>
+ <p>Failure: <c>badarg</c> if <c>Date1</c> or <c>Time1</c> do
+ not denote a valid date or time.</p>
+ </desc>
+ </func>
+ <func>
+ <name>erlang:localtime_to_universaltime({Date1, Time1}, IsDst) -> {Date2, Time2}</name>
+ <fsummary>Convert from local to Universal Time Coordinated (UTC) date and time</fsummary>
+ <type>
+ <v>Date1 = Date2 = {Year, Month, Day}</v>
+ <v>Time1 = Time2 = {Hour, Minute, Second}</v>
+ <v>&nbsp;Year = Month = Day = Hour = Minute = Second = int()</v>
+ <v>IsDst = true | false | undefined</v>
+ </type>
+ <desc>
+ <p>Converts local date and time to Universal Time Coordinated
+ (UTC) just like <c>erlang:localtime_to_universaltime/1</c>,
+ but the caller decides if daylight saving time is active or
+ not.</p>
+ <p>If <c>IsDst == true</c> the <c>{Date1, Time1}</c> is during
+ daylight saving time, if <c>IsDst == false</c> it is not,
+ and if <c>IsDst == undefined</c> the underlying OS may
+ guess, which is the same as calling
+ <c>erlang:localtime_to_universaltime({Date1, Time1})</c>.</p>
+ <pre>
+> <input>erlang:localtime_to_universaltime({{1996,11,6},{14,45,17}}, true).</input>
+{{1996,11,6},{12,45,17}}
+> <input>erlang:localtime_to_universaltime({{1996,11,6},{14,45,17}}, false).</input>
+{{1996,11,6},{13,45,17}}
+> <input>erlang:localtime_to_universaltime({{1996,11,6},{14,45,17}}, undefined).</input>
+{{1996,11,6},{13,45,17}}</pre>
+ <p>Failure: <c>badarg</c> if <c>Date1</c> or <c>Time1</c> do
+ not denote a valid date or time.</p>
+ </desc>
+ </func>
+ <func>
+ <name>make_ref() -> ref()</name>
+ <fsummary>Return an almost unique reference</fsummary>
+ <desc>
+ <p>Returns an almost unique reference.</p>
+ <p>The returned reference will re-occur after approximately 2^82
+ calls; therefore it is unique enough for practical purposes.</p>
+ <pre>
+> <input>make_ref().</input>
+#Ref&lt;0.0.0.135></pre>
+ </desc>
+ </func>
+ <func>
+ <name>erlang:make_tuple(Arity, InitialValue) -> tuple()</name>
+ <fsummary>Create a new tuple of a given arity</fsummary>
+ <type>
+ <v>Arity = int()</v>
+ <v>InitialValue = term()</v>
+ </type>
+ <desc>
+ <p>Returns a new tuple of the given <c>Arity</c>, where all
+ elements are <c>InitialValue</c>.</p>
+ <pre>
+> <input>erlang:make_tuple(4, []).</input>
+{[],[],[],[]}</pre>
+ </desc>
+ </func>
+ <func>
+ <name>erlang:make_tuple(Arity, Default, InitList) -> tuple()</name>
+ <fsummary>Create a new tuple with given arity and contents</fsummary>
+ <type>
+ <v>Arity = int()</v>
+ <v>Default = term()</v>
+ <v>InitList = [{Position,term()}]</v>
+ <v>Position = integer()</v>
+ </type>
+ <desc>
+ <p><c>erlang:make_tuple</c> first creates a tuple of size <c>Arity</c>
+ where each element has the value <c>Default</c>. It then fills
+ in values from <c>InitList</c>. Each list element in <c>InitList</c>
+ must be a two-tuple where the first element is a position in the
+ newly created tuple and the second element is any term. If a position
+ occurs more than once in the list, the term corresponding to
+ last occurrence will be used.</p>
+ <pre>
+> <input>erlang:make_tuple(5, [], [{2,ignored},{5,zz},{2,aa}]).</input>
+{{[],aa,[],[],zz}</pre>
+ </desc>
+ </func>
+ <func>
+ <name>erlang:max(Term1, Term2) -> Maximum</name>
+ <fsummary>Return the largest of two term</fsummary>
+ <type>
+ <v>Term1 = Term2 = Maximum = term()</v>
+ </type>
+ <desc>
+ <p>Return the largest of <c>Term1</c> and <c>Term2</c>;
+ if the terms compares equal, <c>Term1</c> will be returned.</p>
+ </desc>
+ </func>
+ <func>
+ <name>erlang:md5(Data) -> Digest</name>
+ <fsummary>Compute an MD5 message digest</fsummary>
+ <type>
+ <v>Data = iodata()</v>
+ <v>Digest = binary()</v>
+ </type>
+ <desc>
+ <p>Computes an <c>MD5</c> message digest from <c>Data</c>, where
+ the length of the digest is 128 bits (16 bytes). <c>Data</c>
+ is a binary or a list of small integers and binaries.</p>
+ <p>See The MD5 Message Digest Algorithm (RFC 1321) for more
+ information about MD5.</p>
+ <warning><p>The MD5 Message Digest Algorithm is <em>not</em> considered
+ safe for code-signing or software integrity purposes.</p></warning>
+ </desc>
+ </func>
+ <func>
+ <name>erlang:md5_final(Context) -> Digest</name>
+ <fsummary>Finish the update of an MD5 context and return the computed MD5 message digest</fsummary>
+ <type>
+ <v>Context = Digest = binary()</v>
+ </type>
+ <desc>
+ <p>Finishes the update of an MD5 <c>Context</c> and returns
+ the computed <c>MD5</c> message digest.</p>
+ </desc>
+ </func>
+ <func>
+ <name>erlang:md5_init() -> Context</name>
+ <fsummary>Create an MD5 context</fsummary>
+ <type>
+ <v>Context = binary()</v>
+ </type>
+ <desc>
+ <p>Creates an MD5 context, to be used in subsequent calls to
+ <c>md5_update/2</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>erlang:md5_update(Context, Data) -> NewContext</name>
+ <fsummary>Update an MD5 context with data, and return a new context</fsummary>
+ <type>
+ <v>Data = iodata()</v>
+ <v>Context = NewContext = binary()</v>
+ </type>
+ <desc>
+ <p>Updates an MD5 <c>Context</c> with <c>Data</c>, and returns
+ a <c>NewContext</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>erlang:memory() -> [{Type, Size}]</name>
+ <fsummary>Information about dynamically allocated memory</fsummary>
+ <type>
+ <v>Type, Size -- see below</v>
+ </type>
+ <desc>
+ <p>Returns a list containing information about memory
+ dynamically allocated by the Erlang emulator. Each element of
+ the list is a tuple <c>{Type, Size}</c>. The first element
+ <c>Type</c>is an atom describing memory type. The second
+ element <c>Size</c>is memory size in bytes. A description of
+ each memory type follows:</p>
+ <taglist>
+ <tag><c>total</c></tag>
+ <item>
+ <p>The total amount of memory currently allocated, which is
+ the same as the sum of memory size for <c>processes</c>
+ and <c>system</c>.</p>
+ </item>
+ <tag><c>processes</c></tag>
+ <item>
+ <p>The total amount of memory currently allocated by
+ the Erlang processes.</p>
+ </item>
+ <tag><c>processes_used</c></tag>
+ <item>
+ <p>The total amount of memory currently used by the Erlang
+ processes.</p>
+ <p>This memory is part of the memory presented as
+ <c>processes</c> memory.</p>
+ </item>
+ <tag><c>system</c></tag>
+ <item>
+ <p>The total amount of memory currently allocated by
+ the emulator that is not directly related to any Erlang
+ process.</p>
+ <p>Memory presented as <c>processes</c> is not included in
+ this memory.</p>
+ </item>
+ <tag><c>atom</c></tag>
+ <item>
+ <p>The total amount of memory currently allocated for atoms.</p>
+ <p>This memory is part of the memory presented as
+ <c>system</c> memory.</p>
+ </item>
+ <tag><c>atom_used</c></tag>
+ <item>
+ <p>The total amount of memory currently used for atoms.</p>
+ <p>This memory is part of the memory presented as
+ <c>atom</c> memory.</p>
+ </item>
+ <tag><c>binary</c></tag>
+ <item>
+ <p>The total amount of memory currently allocated for
+ binaries.</p>
+ <p>This memory is part of the memory presented as
+ <c>system</c> memory.</p>
+ </item>
+ <tag><c>code</c></tag>
+ <item>
+ <p>The total amount of memory currently allocated for
+ Erlang code.</p>
+ <p>This memory is part of the memory presented as
+ <c>system</c> memory.</p>
+ </item>
+ <tag><c>ets</c></tag>
+ <item>
+ <p>The total amount of memory currently allocated for ets
+ tables.</p>
+ <p>This memory is part of the memory presented as
+ <c>system</c> memory.</p>
+ </item>
+ <tag><c>maximum</c></tag>
+ <item>
+ <p>The maximum total amount of memory allocated since
+ the emulator was started.</p>
+ <p>This tuple is only present when the emulator is run with
+ instrumentation.</p>
+ <p>For information on how to run the emulator with
+ instrumentation see
+ <seealso marker="tools:instrument">instrument(3)</seealso>
+ and/or <seealso marker="erts:erl">erl(1)</seealso>.</p>
+ </item>
+ </taglist>
+ <note>
+ <p>The <c>system</c> value is not complete. Some allocated
+ memory that should be part of the <c>system</c> value are
+ not.</p>
+ <p>When the emulator is run with instrumentation,
+ the <c>system</c> value is more accurate, but memory
+ directly allocated by <c>malloc</c> (and friends) are still
+ not part of the <c>system</c> value. Direct calls to
+ <c>malloc</c> are only done from OS specific runtime
+ libraries and perhaps from user implemented Erlang drivers
+ that do not use the memory allocation functions in
+ the driver interface.</p>
+ <p>Since the <c>total</c> value is the sum of <c>processes</c>
+ and <c>system</c> the error in <c>system</c> will propagate
+ to the <c>total</c> value.</p>
+ <p>The different amounts of memory that are summed are
+ <em>not</em> gathered atomically which also introduce
+ an error in the result.</p>
+ </note>
+ <p>The different values has the following relation to each
+ other. Values beginning with an uppercase letter is not part
+ of the result.</p>
+ <code type="none">
+\011total = processes + system
+\011processes = processes_used + ProcessesNotUsed
+\011system = atom + binary + code + ets + OtherSystem
+\011atom = atom_used + AtomNotUsed
+
+\011RealTotal = processes + RealSystem
+\011RealSystem = system + MissedSystem</code>
+ <p>More tuples in the returned list may be added in the future.</p>
+ <note>
+ <p>The <c>total</c> value is supposed to be the total amount
+ of memory dynamically allocated by the emulator. Shared
+ libraries, the code of the emulator itself, and
+ the emulator stack(s) are not supposed to be included. That
+ is, the <c>total</c> value is <em>not</em> supposed to be
+ equal to the total size of all pages mapped to the emulator.
+ Furthermore, due to fragmentation and pre-reservation of
+ memory areas, the size of the memory segments which contain
+ the dynamically allocated memory blocks can be substantially
+ larger than the total size of the dynamically allocated
+ memory blocks.</p>
+ </note>
+ <note>
+ <p>
+ Since erts version 5.6.4 <c>erlang:memory/0</c> requires that
+ all <seealso marker="erts:erts_alloc">erts_alloc(3)</seealso>
+ allocators are enabled (default behaviour).
+ </p>
+ </note>
+ <p>Failure:</p>
+ <taglist>
+ <tag><c>notsup</c></tag>
+ <item>
+ If an <seealso marker="erts:erts_alloc">erts_alloc(3)</seealso>
+ allocator has been disabled.
+ </item>
+ </taglist>
+ </desc>
+ </func>
+ <func>
+ <name>erlang:memory(Type | [Type]) -> Size | [{Type, Size}]</name>
+ <fsummary>Information about dynamically allocated memory</fsummary>
+ <type>
+ <v>Type, Size -- see below</v>
+ </type>
+ <desc>
+ <p>Returns the memory size in bytes allocated for memory of
+ type <c>Type</c>. The argument can also be given as a list
+ of <c>Type</c> atoms, in which case a corresponding list of
+ <c>{Type, Size}</c> tuples is returned.</p>
+ <note>
+ <p>
+ Since erts version 5.6.4 <c>erlang:memory/1</c> requires that
+ all <seealso marker="erts:erts_alloc">erts_alloc(3)</seealso>
+ allocators are enabled (default behaviour).
+ </p>
+ </note>
+ <p>Failures:</p>
+ <taglist>
+ <tag><c>badarg</c></tag>
+ <item>
+ If <c>Type</c> is not one of the memory types listed in the
+ documentation of
+ <seealso marker="#erlang:memory/0">erlang:memory/0</seealso>.
+ </item>
+ <tag><c>badarg</c></tag>
+ <item>
+ If <c>maximum</c> is passed as <c>Type</c> and the emulator
+ is not run in instrumented mode.
+ </item>
+ <tag><c>notsup</c></tag>
+ <item>
+ If an <seealso marker="erts:erts_alloc">erts_alloc(3)</seealso>
+ allocator has been disabled.
+ </item>
+ </taglist>
+ <p>See also
+ <seealso marker="#erlang:memory/0">erlang:memory/0</seealso>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>erlang:min(Term1, Term2) -> Minimum</name>
+ <fsummary>Return the smallest of two term</fsummary>
+ <type>
+ <v>Term1 = Term2 = Minimum = term()</v>
+ </type>
+ <desc>
+ <p>Return the smallest of <c>Term1</c> and <c>Term2</c>;
+ if the terms compare equal, <c>Term1</c> will be returned.</p>
+ </desc>
+ </func>
+ <func>
+ <name>module_loaded(Module) -> bool()</name>
+ <fsummary>Check if a module is loaded</fsummary>
+ <type>
+ <v>Module = atom()</v>
+ </type>
+ <desc>
+ <p>Returns <c>true</c> if the module <c>Module</c> is loaded,
+ otherwise returns <c>false</c>. It does not attempt to load
+ the module.</p>
+ <warning>
+ <p>This BIF is intended for the code server (see
+ <seealso marker="kernel:code">code(3)</seealso>) and should not be
+ used elsewhere.</p>
+ </warning>
+ </desc>
+ </func>
+ <func>
+ <name>erlang:monitor(Type, Item) -> MonitorRef</name>
+ <fsummary>Start monitoring</fsummary>
+ <type>
+ <v>Type = process</v>
+ <v>Item = pid() | {RegName, Node} | RegName</v>
+ <v>&nbsp;RegName = atom()</v>
+ <v>&nbsp;Node = node()</v>
+ <v>MonitorRef = reference()</v>
+ </type>
+ <desc>
+ <p>The calling process starts monitoring <c>Item</c> which is
+ an object of type <c>Type</c>.</p>
+ <p>Currently only processes can be monitored, i.e. the only
+ allowed <c>Type</c> is <c>process</c>, but other types may be
+ allowed in the future.</p>
+ <p><c>Item</c> can be:</p>
+ <taglist>
+ <tag><c>pid()</c></tag>
+ <item>
+ <p>The pid of the process to monitor.</p>
+ </item>
+ <tag><c>{RegName, Node}</c></tag>
+ <item>
+ <p>A tuple consisting of a registered name of a process and
+ a node name. The process residing on the node <c>Node</c>
+ with the registered name <c>RegName</c> will be monitored.</p>
+ </item>
+ <tag><c>RegName</c></tag>
+ <item>
+ <p>The process locally registered as <c>RegName</c> will be
+ monitored.</p>
+ </item>
+ </taglist>
+ <note>
+ <p>When a process is monitored by registered name, the process
+ that has the registered name at the time when
+ <c>erlang:monitor/2</c> is called will be monitored.
+ The monitor will not be effected, if the registered name is
+ unregistered.</p>
+ </note>
+ <p>A <c>'DOWN'</c> message will be sent to the monitoring
+ process if <c>Item</c> dies, if <c>Item</c> does not exist,
+ or if the connection is lost to the node which <c>Item</c>
+ resides on. A <c>'DOWN'</c> message has the following pattern:</p>
+ <code type="none">
+{'DOWN', MonitorRef, Type, Object, Info}</code>
+ <p>where <c>MonitorRef</c> and <c>Type</c> are the same as
+ described above, and:</p>
+ <taglist>
+ <tag><c>Object</c></tag>
+ <item>
+ <p>A reference to the monitored object:</p>
+ <list type="bulleted">
+ <item>the pid of the monitored process, if <c>Item</c> was
+ specified as a pid.</item>
+ <item><c>{RegName, Node}</c>, if <c>Item</c> was specified as
+ <c>{RegName, Node}</c>.</item>
+ <item><c>{RegName, Node}</c>, if <c>Item</c> was specified as
+ <c>RegName</c>. <c>Node</c> will in this case be the
+ name of the local node (<c>node()</c>).</item>
+ </list>
+ </item>
+ <tag><c>Info</c></tag>
+ <item>
+ <p>Either the exit reason of the process, <c>noproc</c>
+ (non-existing process), or <c>noconnection</c> (no
+ connection to <c>Node</c>).</p>
+ </item>
+ </taglist>
+ <note>
+ <p>If/when <c>erlang:monitor/2</c> is extended (e.g. to
+ handle other item types than <c>process</c>), other
+ possible values for <c>Object</c>, and <c>Info</c> in the
+ <c>'DOWN'</c> message will be introduced.</p>
+ </note>
+ <p>The monitoring is turned off either when the <c>'DOWN'</c>
+ message is sent, or when
+ <seealso marker="#erlang:demonitor/1">erlang:demonitor/1</seealso>
+ is called.</p>
+ <p>If an attempt is made to monitor a process on an older node
+ (where remote process monitoring is not implemented or one
+ where remote process monitoring by registered name is not
+ implemented), the call fails with <c>badarg</c>.</p>
+ <p>Making several calls to <c>erlang:monitor/2</c> for the same
+ <c>Item</c> is not an error; it results in as many, completely
+ independent, monitorings.</p>
+ <note>
+ <p>The format of the <c>'DOWN'</c> message changed in the 5.2
+ version of the emulator (OTP release R9B) for monitor <em>by registered name</em>. The <c>Object</c> element of
+ the <c>'DOWN'</c> message could in earlier versions
+ sometimes be the pid of the monitored process and sometimes
+ be the registered name. Now the <c>Object</c> element is
+ always a tuple consisting of the registered name and
+ the node name. Processes on new nodes (emulator version 5.2
+ or greater) will always get <c>'DOWN'</c> messages on
+ the new format even if they are monitoring processes on old
+ nodes. Processes on old nodes will always get <c>'DOWN'</c>
+ messages on the old format.</p>
+ </note>
+ </desc>
+ </func>
+ <func>
+ <name>monitor_node(Node, Flag) -> true</name>
+ <fsummary>Monitor the status of a node</fsummary>
+ <type>
+ <v>Node = node()</v>
+ <v>Flag = bool()</v>
+ </type>
+ <desc>
+ <p>Monitors the status of the node <c>Node</c>. If <c>Flag</c>
+ is <c>true</c>, monitoring is turned on; if <c>Flag</c> is
+ <c>false</c>, monitoring is turned off.</p>
+ <p>Making several calls to <c>monitor_node(Node, true)</c> for
+ the same <c>Node</c> is not an error; it results in as many,
+ completely independent, monitorings.</p>
+ <p>If <c>Node</c> fails or does not exist, the message
+ <c>{nodedown, Node}</c> is delivered to the process. If a
+ process has made two calls to <c>monitor_node(Node, true)</c>
+ and <c>Node</c> terminates, two <c>nodedown</c> messages are
+ delivered to the process. If there is no connection to
+ <c>Node</c>, there will be an attempt to create one. If this
+ fails, a <c>nodedown</c> message is delivered.</p>
+ <p>Nodes connected through hidden connections can be monitored
+ as any other node.</p>
+ <p>Failure: <c>badarg</c>if the local node is not alive.</p>
+ </desc>
+ </func>
+ <func>
+ <name>erlang:monitor_node(Node, Flag, Options) -> true</name>
+ <fsummary>Monitor the status of a node</fsummary>
+ <type>
+ <v>Node = node()</v>
+ <v>Flag = bool()</v>
+ <v>Options = [Option]</v>
+ <v>Option = allow_passive_connect</v>
+ </type>
+ <desc>
+ <p>Behaves as <c>monitor_node/2</c> except that it allows an
+ extra option to be given, namely <c>allow_passive_connect</c>.
+ The option allows the BIF to wait the normal net connection
+ timeout for the <em>monitored node</em> to connect itself,
+ even if it cannot be actively connected from this node
+ (i.e. it is blocked). The state where this might be useful can
+ only be achieved by using the kernel option
+ <c>dist_auto_connect once</c>. If that kernel option is not
+ used, the <c>allow_passive_connect</c> option has no
+ effect.</p>
+ <note>
+ <p>The <c>allow_passive_connect</c> option is used
+ internally and is seldom needed in applications where the
+ network topology and the kernel options in effect is known in
+ advance.</p>
+ </note>
+ <p>Failure: <c>badarg</c> if the local node is not alive or the
+ option list is malformed.</p>
+ </desc>
+ </func>
+ <func>
+ <name>node() -> Node</name>
+ <fsummary>Name of the local node</fsummary>
+ <type>
+ <v>Node = node()</v>
+ </type>
+ <desc>
+ <p>Returns the name of the local node. If the node is not alive,
+ <c>nonode@nohost</c> is returned instead.</p>
+ <p>Allowed in guard tests.</p>
+ </desc>
+ </func>
+ <func>
+ <name>node(Arg) -> Node</name>
+ <fsummary>At which node is a pid, port or reference located</fsummary>
+ <type>
+ <v>Arg = pid() | port() | ref()</v>
+ <v>Node = node()</v>
+ </type>
+ <desc>
+ <p>Returns the node where <c>Arg</c> is located. <c>Arg</c> can
+ be a pid, a reference, or a port. If the local node is not
+ alive, <c>nonode@nohost</c> is returned.</p>
+ <p>Allowed in guard tests.</p>
+ </desc>
+ </func>
+ <func>
+ <name>nodes() -> Nodes</name>
+ <fsummary>All visible nodes in the system</fsummary>
+ <type>
+ <v>Nodes = [node()]</v>
+ </type>
+ <desc>
+ <p>Returns a list of all visible nodes in the system, excluding
+ the local node. Same as <c>nodes(visible)</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>nodes(Arg | [Arg]) -> Nodes</name>
+ <fsummary>All nodes of a certain type in the system</fsummary>
+ <type>
+ <v>Arg = visible | hidden | connected | this | known</v>
+ <v>Nodes = [node()]</v>
+ </type>
+ <desc>
+ <p>Returns a list of nodes according to argument given.
+ The result returned when the argument is a list, is the list
+ of nodes satisfying the disjunction(s) of the list elements.</p>
+ <p><c>Arg</c> can be any of the following:</p>
+ <taglist>
+ <tag><c>visible</c></tag>
+ <item>
+ <p>Nodes connected to this node through normal connections.</p>
+ </item>
+ <tag><c>hidden</c></tag>
+ <item>
+ <p>Nodes connected to this node through hidden connections.</p>
+ </item>
+ <tag><c>connected</c></tag>
+ <item>
+ <p>All nodes connected to this node.</p>
+ </item>
+ <tag><c>this</c></tag>
+ <item>
+ <p>This node.</p>
+ </item>
+ <tag><c>known</c></tag>
+ <item>
+ <p>Nodes which are known to this node, i.e., connected,
+ previously connected, etc.</p>
+ </item>
+ </taglist>
+ <p>Some equalities: <c>[node()] = nodes(this)</c>,
+ <c>nodes(connected) = nodes([visible, hidden])</c>, and
+ <c>nodes() = nodes(visible)</c>.</p>
+ <p>If the local node is not alive,
+ <c>nodes(this) == nodes(known) == [nonode@nohost]</c>, for
+ any other <c>Arg</c> the empty list [] is returned.</p>
+ </desc>
+ </func>
+ <func>
+ <name>now() -> {MegaSecs, Secs, MicroSecs}</name>
+ <fsummary>Elapsed time since 00:00 GMT</fsummary>
+ <type>
+ <v>MegaSecs = Secs = MicroSecs = int()</v>
+ </type>
+ <desc>
+ <p>Returns the tuple <c>{MegaSecs, Secs, MicroSecs}</c> which is
+ the elapsed time since 00:00 GMT, January 1, 1970 (zero hour)
+ on the assumption that the underlying OS supports this.
+ Otherwise, some other point in time is chosen. It is also
+ guaranteed that subsequent calls to this BIF returns
+ continuously increasing values. Hence, the return value from
+ <c>now()</c> can be used to generate unique time-stamps. It
+ can only be used to check the local time of day if
+ the time-zone info of the underlying operating system is
+ properly configured.</p>
+ </desc>
+ </func>
+ <func>
+ <name>open_port(PortName, PortSettings) -> port()</name>
+ <fsummary>Open a port</fsummary>
+ <type>
+ <v>PortName = {spawn, Command} | {spawn_driver, Command} | {spawn_executable, Command} | {fd, In, Out}</v>
+ <v>&nbsp;Command = string()</v>
+ <v>&nbsp;In = Out = int()</v>
+ <v>PortSettings = [Opt]</v>
+ <v>&nbsp;Opt = {packet, N} | stream | {line, L} | {cd, Dir} | {env, Env} | {args, [ string() ]} | {arg0, string()} | exit_status | use_stdio | nouse_stdio | stderr_to_stdout | in | out | binary | eof</v>
+ <v>&nbsp;&nbsp;N = 1 | 2 | 4</v>
+ <v>&nbsp;&nbsp;L = int()</v>
+ <v>&nbsp;&nbsp;Dir = string()</v>
+ <v>&nbsp;&nbsp;Env = [{Name, Val}]</v>
+ <v>&nbsp;&nbsp;&nbsp;Name = string()</v>
+ <v>&nbsp;&nbsp;&nbsp;Val = string() | false</v>
+ </type>
+ <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>PortName</c> is one of the following:</p>
+ <taglist>
+ <tag><c>{spawn, Command}</c></tag>
+ <item>
+ <p>Starts an external program. <c>Command</c> is the name
+ of the external program which will be run. <c>Command</c>
+ runs outside the Erlang work space unless an Erlang
+ driver with the name <c>Command</c> is found. If found,
+ that driver will be started. A driver runs in the Erlang
+ workspace, which means that it is linked with the Erlang
+ runtime system.</p>
+ <p>When starting external programs on Solaris, the system
+ call <c>vfork</c> is used in preference to <c>fork</c>
+ for performance reasons, although it has a history of
+ being less robust. If there are problems with using
+ <c>vfork</c>, setting the environment variable
+ <c>ERL_NO_VFORK</c> to any value will cause <c>fork</c>
+ to be used instead.</p>
+
+ <p>For external programs, the <c>PATH</c> is searched
+ (or an equivalent method is used to find programs,
+ depending on operating system). This is done by invoking
+ the shell och certain platforms. The first space
+ separated token of the command will be considered as the
+ name of the executable (or driver). This (among other
+ things) makes this option unsuitable for running
+ programs having spaces in file or directory names. Use
+ {spawn_executable, Command} instead if spaces in executable
+ file names is desired.</p>
+ </item>
+ <tag><c>{spawn_driver, Command}</c></tag>
+ <item>
+ <p>Works like <c>{spawn, Command}</c>, but demands the
+ first (space separated) token of the command to be the name of a
+ loaded driver. If no driver with that name is loaded, a
+ <c>badarg</c> error is raised.</p>
+ </item>
+ <tag><c>{spawn_executable, Command}</c></tag>
+ <item>
+
+ <p>Works like <c>{spawn, Command}</c>, but only runs
+ external executables. The <c>Command</c> in it's whole
+ is used as the name of the executable, including any
+ spaces. If arguments are to be passed, the
+ <c>args</c> and <c>arg0</c> <c>PortSettings</c> can be used.</p>
+
+ <p>The shell is not usually invoked to start the
+ program, it's executed directly. Neither is the
+ <c>PATH</c> (or equivalent) searched. To find a program
+ in the PATH to execute, use <seealso
+ marker="kernel:os#find_executable/1">os:find_executable/1</seealso>.</p>
+ <p>Only if a shell script or <c>.bat</c> file is
+ executed, the appropriate command interpreter will
+ implicitly be invoked, but there will still be no
+ command argument expansion or implicit PATH search.</p>
+
+ <p>If the <c>Command</c> cannot be run, an error
+ exception, with the posix error code as the reason, is
+ raised. The error reason may differ between operating
+ systems. Typically the error <c>enoent</c> is raised
+ when one tries to run a program that is not found and
+ <c>eaccess</c> is raised when the given file is not
+ executable.</p>
+ </item>
+ <tag><c>{fd, In, Out}</c></tag>
+ <item>
+ <p>Allows an Erlang process to access any currently opened
+ file descriptors used by Erlang. The file descriptor
+ <c>In</c> can be used for standard input, and the file
+ descriptor <c>Out</c> for standard output. It is only
+ used for various servers in the Erlang operating system
+ (<c>shell</c> and <c>user</c>). Hence, its use is very
+ limited.</p>
+ </item>
+ </taglist>
+ <p><c>PortSettings</c> is a list of settings for the port.
+ Valid settings are:</p>
+ <taglist>
+ <tag><c>{packet, N}</c></tag>
+ <item>
+ <p>Messages are preceded by their length, sent in <c>N</c>
+ bytes, with the most significant byte first. Valid values
+ for <c>N</c> are 1, 2, or 4.</p>
+ </item>
+ <tag><c>stream</c></tag>
+ <item>
+ <p>Output messages are sent without packet lengths. A
+ user-defined protocol must be used between the Erlang
+ process and the external object.</p>
+ </item>
+ <tag><c>{line, L}</c></tag>
+ <item>
+ <p>Messages are delivered on a per line basis. Each line
+ (delimited by the OS-dependent newline sequence) is
+ delivered in one single message. The message data format
+ is <c>{Flag, Line}</c>, where <c>Flag</c> is either
+ <c>eol</c> or <c>noeol</c> and <c>Line</c> is the actual
+ data delivered (without the newline sequence).</p>
+ <p><c>L</c> specifies the maximum line length in bytes.
+ Lines longer than this will be delivered in more than one
+ message, with the <c>Flag</c> set to <c>noeol</c> for all
+ but the last message. If end of file is encountered
+ anywhere else than immediately following a newline
+ sequence, the last line will also be delivered with
+ the <c>Flag</c> set to <c>noeol</c>. In all other cases,
+ lines are delivered with <c>Flag</c> set to <c>eol</c>.</p>
+ <p>The <c>{packet, N}</c> and <c>{line, L}</c> settings are
+ mutually exclusive.</p>
+ </item>
+ <tag><c>{cd, Dir}</c></tag>
+ <item>
+ <p>This is only valid for <c>{spawn, Command}</c> and
+ <c>{spawn_executable, Command}</c>.
+ The external program starts using <c>Dir</c> as its
+ working directory. <c>Dir</c> must be a string. Not
+ available on VxWorks.</p>
+ </item>
+ <tag><c>{env, Env}</c></tag>
+ <item>
+ <p>This is only valid for <c>{spawn, Command}</c> and
+ <c>{spawn_executable, Command}</c>.
+ The environment of the started process is extended using
+ the environment specifications in <c>Env</c>.</p>
+ <p><c>Env</c> should be a list of tuples <c>{Name, Val}</c>,
+ where <c>Name</c> is the name of an environment variable,
+ and <c>Val</c> is the value it is to have in the spawned
+ port process. Both <c>Name</c> and <c>Val</c> must be
+ strings. The one exception is <c>Val</c> being the atom
+ <c>false</c> (in analogy with <c>os:getenv/1</c>), which
+ removes the environment variable. Not available on
+ VxWorks.</p>
+ </item>
+ <tag><c>{args, [ string() ]}</c></tag>
+ <item>
+
+ <p>This option is only valid for <c>{spawn_executable, Command}</c>
+ and specifies arguments to the executable. Each argument
+ is given as a separate string and (on Unix) eventually
+ ends up as one element each in the argument vector. On
+ other platforms, similar behavior is mimicked.</p>
+
+ <p>The arguments are not expanded by the shell prior to
+ being supplied to the executable, most notably this
+ means that file wildcard expansion will not happen. Use
+ <seealso
+ marker="stdlib:filelib#wildcard/1">filelib:wildcard/1</seealso>
+ to expand wildcards for the arguments. Note that even if
+ the program is a Unix shell script, meaning that the
+ shell will ultimately be invoked, wildcard expansion
+ will not happen and the script will be provided with the
+ untouched arguments. On Windows&reg;, wildcard expansion
+ is always up to the program itself, why this isn't an
+ issue.</p>
+
+ <p>Note also that the actual executable name (a.k.a. <c>argv[0]</c>)
+ should not be given in this list. The proper executable name will
+ automatically be used as argv[0] where applicable.</p>
+
+ <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>
+
+ </item>
+ <tag><c>{arg0, string()}</c></tag>
+ <item>
+
+ <p>This option is only valid for <c>{spawn_executable, Command}</c>
+ and explicitly specifies the program name argument when
+ running an executable. This might in some circumstances,
+ on some operating systems, be desirable. How the program
+ responds to this is highly system dependent and no specific
+ effect is guaranteed.</p>
+
+ </item>
+
+ <tag><c>exit_status</c></tag>
+ <item>
+ <p>This is only valid for <c>{spawn, Command}</c> where
+ <c>Command</c> refers to an external program, and for
+ <c>{spawn_executable, Command}</c>.</p>
+ <p>When the external process connected to the port exits, a
+ message of the form <c>{Port,{exit_status,Status}}</c> is
+ sent to the connected process, where <c>Status</c> is the
+ exit status of the external process. If the program
+ aborts, on Unix the same convention is used as the shells
+ do (i.e., 128+signal).</p>
+ <p>If the <c>eof</c> option has been given as well,
+ the <c>eof</c> message and the <c>exit_status</c> message
+ appear in an unspecified order.</p>
+ <p>If the port program closes its stdout without exiting,
+ the <c>exit_status</c> option will not work.</p>
+ </item>
+ <tag><c>use_stdio</c></tag>
+ <item>
+ <p>This is only valid for <c>{spawn, Command}</c> and
+ <c>{spawn_executable, Command}</c>. It
+ allows the standard input and output (file descriptors 0
+ and 1) of the spawned (UNIX) process for communication
+ with Erlang.</p>
+ </item>
+ <tag><c>nouse_stdio</c></tag>
+ <item>
+ <p>The opposite of <c>use_stdio</c>. Uses file descriptors
+ 3 and 4 for communication with Erlang.</p>
+ </item>
+ <tag><c>stderr_to_stdout</c></tag>
+ <item>
+ <p>Affects ports to external programs. The executed program
+ gets its standard error file redirected to its standard
+ output file. <c>stderr_to_stdout</c> and
+ <c>nouse_stdio</c> are mutually exclusive.</p>
+ </item>
+ <tag><c>overlapped_io</c></tag>
+ <item>
+ <p>Affects ports to external programs on Windows&reg; only.
+ The standard input and standard output handles of the port program
+ will, if this option is supplied, be opened with the flag
+ FILE_FLAG_OVERLAPPED, so that the port program can (and has to) do
+ overlapped I/O on it's standard handles. This is not normally
+ the case for simple port programs, but an option of value for the
+ experienced Windows programmer. <em>On all other platforms, this
+ option is silently discarded</em>.</p>
+ </item>
+ <tag><c>in</c></tag>
+ <item>
+ <p>The port can only be used for input.</p>
+ </item>
+ <tag><c>out</c></tag>
+ <item>
+ <p>The port can only be used for output.</p>
+ </item>
+ <tag><c>binary</c></tag>
+ <item>
+ <p>All IO from the port are binary data objects as opposed
+ to lists of bytes.</p>
+ </item>
+ <tag><c>eof</c></tag>
+ <item>
+ <p>The port will not be closed at the end of the file and
+ produce an exit signal. Instead, it will remain open and
+ a <c>{Port, eof}</c> message will be sent to the process
+ holding the port.</p>
+ </item>
+ <tag><c>hide</c></tag>
+ <item>
+ <p>When running on Windows, suppress creation of a new
+ console window when spawning the port program.
+ (This option has no effect on other platforms.)</p>
+ </item>
+ </taglist>
+ <p>The default is <c>stream</c> for all types of port and
+ <c>use_stdio</c> for spawned ports.</p>
+ <p>Failure: If the port cannot be opened, the exit reason is
+ <c>badarg</c>, <c>system_limit</c>, or the Posix error code which
+ most closely describes the error, or <c>einval</c> if no Posix code
+ is appropriate:</p>
+ <taglist>
+ <tag><c>badarg</c></tag>
+ <item>
+ <p>Bad input arguments to <c>open_port</c>.</p>
+ </item>
+ <tag><c>system_limit</c></tag>
+ <item>
+ <p>All available ports in the Erlang emulator are in use.</p>
+ </item>
+ <tag><c>enomem</c></tag>
+ <item>
+ <p>There was not enough memory to create the port.</p>
+ </item>
+ <tag><c>eagain</c></tag>
+ <item>
+ <p>There are no more available operating system processes.</p>
+ </item>
+ <tag><c>enametoolong</c></tag>
+ <item>
+ <p>The external command given was too long.</p>
+ </item>
+ <tag><c>emfile</c></tag>
+ <item>
+ <p>There are no more available file descriptors (for the operating system process
+ that the Erlang emulator runs in).</p>
+ </item>
+ <tag><c>enfile</c></tag>
+ <item>
+ <p>The file table is full (for the entire operating system).</p>
+ </item>
+ <tag><c>eacces</c></tag>
+ <item>
+ <p>The <c>Command</c> given in <c>{spawn_executable, Command}</c> does not point out an executable file.</p>
+ </item>
+ <tag><c>enoent</c></tag>
+ <item>
+ <p>The <c>Command</c> given in <c>{spawn_executable, Command}</c> does not point out an existing file.</p>
+ </item>
+ </taglist>
+ <p>During use of a port opened using <c>{spawn, Name}</c>,
+ <c>{spawn_driver, Name}</c> or <c>{spawn_executable, Name}</c>,
+ errors arising when sending messages to it are reported to
+ the owning process using signals of the form
+ <c>{'EXIT', Port, PosixCode}</c>. See <c>file(3)</c> for
+ possible values of <c>PosixCode</c>.</p>
+ <p><marker id="ERL_MAX_PORTS"></marker>
+ The maximum number of ports that can be open at the same
+ time is 1024 by default, but can be configured by
+ the environment variable <c>ERL_MAX_PORTS</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>erlang:phash(Term, Range) -> Hash</name>
+ <fsummary>Portable hash function</fsummary>
+ <type>
+ <v>Term = term()</v>
+ <v>Range = 1..2^32</v>
+ <v>Hash = 1..Range</v>
+ </type>
+ <desc>
+ <p>Portable hash function that will give the same hash for
+ the same Erlang term regardless of machine architecture and
+ ERTS version (the BIF was introduced in ERTS 4.9.1.1). Range
+ can be between 1 and 2^32, the function returns a hash value
+ for <c>Term</c> within the range <c>1..Range</c>.</p>
+ <p>This BIF could be used instead of the old deprecated
+ <c>erlang:hash/2</c> BIF, as it calculates better hashes for
+ all data-types, but consider using <c>phash2/1,2</c> instead.</p>
+ </desc>
+ </func>
+ <func>
+ <name>erlang:phash2(Term [, Range]) -> Hash</name>
+ <fsummary>Portable hash function</fsummary>
+ <type>
+ <v>Term = term()</v>
+ <v>Range = 1..2^32</v>
+ <v>Hash = 0..Range-1</v>
+ </type>
+ <desc>
+ <p>Portable hash function that will give the same hash for
+ the same Erlang term regardless of machine architecture and
+ ERTS version (the BIF was introduced in ERTS 5.2). Range can
+ be between 1 and 2^32, the function returns a hash value for
+ <c>Term</c> within the range <c>0..Range-1</c>. When called
+ without the <c>Range</c> argument, a value in the range
+ <c>0..2^27-1</c> is returned.</p>
+ <p>This BIF should always be used for hashing terms. It
+ distributes small integers better than <c>phash/2</c>, and
+ it is faster for bignums and binaries.</p>
+ <p>Note that the range <c>0..Range-1</c> is different from
+ the range of <c>phash/2</c> (<c>1..Range</c>).</p>
+ </desc>
+ </func>
+ <func>
+ <name>pid_to_list(Pid) -> string()</name>
+ <fsummary>Text representation of a pid</fsummary>
+ <type>
+ <v>Pid = pid()</v>
+ </type>
+ <desc>
+ <p>Returns a string which corresponds to the text
+ representation of <c>Pid</c>.</p>
+ <warning>
+ <p>This BIF is intended for debugging and for use in
+ the Erlang operating system. It should not be used in
+ application programs.</p>
+ </warning>
+ </desc>
+ </func>
+ <func>
+ <name>port_close(Port) -> true</name>
+ <fsummary>Close an open port</fsummary>
+ <type>
+ <v>Port = port() | atom()</v>
+ </type>
+ <desc>
+ <p>Closes an open port. Roughly the same as
+ <c>Port ! {self(), close}</c> except for the error behaviour
+ (see below), and that the port does <em>not</em> reply with
+ <c>{Port, closed}</c>. Any process may close a port with
+ <c>port_close/1</c>, not only the port owner (the connected
+ process).</p>
+ <p>For comparison: <c>Port ! {self(), close}</c> fails with
+ <c>badarg</c> if <c>Port</c> cannot be sent to (i.e.,
+ <c>Port</c> refers neither to a port nor to a process). If
+ <c>Port</c> is a closed port nothing happens. If <c>Port</c>
+ is an open port and the calling process is the port owner,
+ the port replies with <c>{Port, closed}</c> when all buffers
+ have been flushed and the port really closes, but if
+ the calling process is not the port owner the <em>port owner</em> fails with <c>badsig</c>.</p>
+ <p>Note that any process can close a port using
+ <c>Port ! {PortOwner, close}</c> just as if it itself was
+ the port owner, but the reply always goes to the port owner.</p>
+ <p>In short: <c>port_close(Port)</c> has a cleaner and more
+ logical behaviour than <c>Port ! {self(), close}</c>.</p>
+ <p>Failure: <c>badarg</c> if <c>Port</c> is not an open port or
+ the registered name of an open port.</p>
+ </desc>
+ </func>
+ <func>
+ <name>port_command(Port, Data) -> true</name>
+ <fsummary>Send data to a port</fsummary>
+ <type>
+ <v>Port = port() | atom()</v>
+ <v>Data = iodata()</v>
+ </type>
+ <desc>
+ <p>Sends data to a port. Same as
+ <c>Port ! {self(), {command, Data}}</c> except for the error
+ behaviour (see below). Any process may send data to a port
+ with <c>port_command/2</c>, not only the port owner
+ (the connected process).</p>
+ <p>For comparison: <c>Port ! {self(), {command, Data}}</c>
+ fails with <c>badarg</c> if <c>Port</c> cannot be sent to
+ (i.e., <c>Port</c> refers neither to a port nor to a process).
+ If <c>Port</c> is a closed port the data message disappears
+ without a sound. If <c>Port</c> is open and the calling
+ process is not the port owner, the <em>port owner</em> fails
+ with <c>badsig</c>. The port owner fails with <c>badsig</c>
+ also if <c>Data</c> is not a valid IO list.</p>
+ <p>Note that any process can send to a port using
+ <c>Port ! {PortOwner, {command, Data}}</c> just as if it
+ itself was the port owner.</p>
+ <p>In short: <c>port_command(Port, Data)</c> has a cleaner and
+ more logical behaviour than
+ <c>Port ! {self(), {command, Data}}</c>.</p>
+ <p>If the port is busy, the calling process will be suspended
+ until the port is not busy anymore.</p>
+ <p>Failures:</p>
+ <taglist>
+ <tag><c>badarg</c></tag>
+ <item>
+ If <c>Port</c> is not an open port or the registered name
+ of an open port.
+ </item>
+ <tag><c>badarg</c></tag>
+ <item>
+ If <c>Data</c> is not a valid io list.
+ </item>
+ </taglist>
+ </desc>
+ </func>
+ <func>
+ <name>erlang:port_command(Port, Data, OptionList) -> true|false</name>
+ <fsummary>Send data to a port</fsummary>
+ <type>
+ <v>Port = port() | atom()</v>
+ <v>Data = iodata()</v>
+ <v>OptionList = [Option]</v>
+ <v>Option = force</v>
+ <v>Option = nosuspend</v>
+ </type>
+ <desc>
+ <p>Sends data to a port. <c>port_command(Port, Data, [])</c>
+ equals <c>port_command(Port, Data)</c>.</p>
+ <p>If the port command is aborted <c>false</c> is returned;
+ otherwise, <c>true</c> is returned.</p>
+ <p>If the port is busy, the calling process will be suspended
+ until the port is not busy anymore.</p>
+ <p>Currently the following <c>Option</c>s are valid:</p>
+ <taglist>
+ <tag><c>force</c></tag>
+ <item>The calling process will not be suspended if the port is
+ busy; instead, the port command is forced through. The
+ call will fail with a <c>notsup</c> exception if the
+ driver of the port does not support this. For more
+ information see the
+ <seealso marker="driver_entry#driver_flags"><![CDATA[ERL_DRV_FLAG_SOFT_BUSY]]></seealso>
+ driver flag.
+ </item>
+ <tag><c>nosuspend</c></tag>
+ <item>The calling process will not be suspended if the port is
+ busy; instead, the port command is aborted and
+ <c>false</c> is returned.
+ </item>
+ </taglist>
+ <note>
+ <p>More options may be added in the future.</p>
+ </note>
+ <note>
+ <p><c>erlang:port_command/3</c> is currently not auto imported, but
+ it is planned to be auto imported in OTP R14.</p>
+ </note>
+ <p>Failures:</p>
+ <taglist>
+ <tag><c>badarg</c></tag>
+ <item>
+ If <c>Port</c> is not an open port or the registered name
+ of an open port.
+ </item>
+ <tag><c>badarg</c></tag>
+ <item>
+ If <c>Data</c> is not a valid io list.
+ </item>
+ <tag><c>badarg</c></tag>
+ <item>
+ If <c>OptionList</c> is not a valid option list.
+ </item>
+ <tag><c>notsup</c></tag>
+ <item>
+ If the <c>force</c> option has been passed, but the
+ driver of the port does not allow forcing through
+ a busy port.
+ </item>
+ </taglist>
+ </desc>
+ </func>
+ <func>
+ <name>port_connect(Port, Pid) -> true</name>
+ <fsummary>Set the owner of a port</fsummary>
+ <type>
+ <v>Port = port() | atom()</v>
+ <v>Pid = pid()</v>
+ </type>
+ <desc>
+ <p>Sets the port owner (the connected port) to <c>Pid</c>.
+ Roughly the same as <c>Port ! {self(), {connect, Pid}}</c>
+ except for the following:</p>
+ <list type="bulleted">
+ <item>
+ <p>The error behavior differs, see below.</p>
+ </item>
+ <item>
+ <p>The port does <em>not</em> reply with
+ <c>{Port,connected}</c>.</p>
+ </item>
+ <item>
+ <p>The new port owner gets linked to the port.</p>
+ </item>
+ </list>
+ <p>The old port owner stays linked to the port and have to call
+ <c>unlink(Port)</c> if this is not desired. Any process may
+ set the port owner to be any process with
+ <c>port_connect/2</c>.</p>
+ <p>For comparison: <c>Port ! {self(), {connect, Pid}}</c> fails
+ with <c>badarg</c> if <c>Port</c> cannot be sent to (i.e.,
+ <c>Port</c> refers neither to a port nor to a process). If
+ <c>Port</c> is a closed port nothing happens. If <c>Port</c>
+ is an open port and the calling process is the port owner,
+ the port replies with <c>{Port, connected}</c> to the old
+ port owner. Note that the old port owner is still linked to
+ the port, and that the new is not. If <c>Port</c> is an open
+ port and the calling process is not the port owner,
+ the <em>port owner</em> fails with <c>badsig</c>. The port
+ owner fails with <c>badsig</c> also if <c>Pid</c> is not an
+ existing local pid.</p>
+ <p>Note that any process can set the port owner using
+ <c>Port ! {PortOwner, {connect, Pid}}</c> just as if it
+ itself was the port owner, but the reply always goes to
+ the port owner.</p>
+ <p>In short: <c>port_connect(Port, Pid)</c> has a cleaner and
+ more logical behaviour than
+ <c>Port ! {self(),{connect,Pid}}</c>.</p>
+ <p>Failure: <c>badarg</c> if <c>Port</c> is not an open port
+ or the registered name of an open port, or if <c>Pid</c> is
+ not an existing local pid.</p>
+ </desc>
+ </func>
+ <func>
+ <name>port_control(Port, Operation, Data) -> Res</name>
+ <fsummary>Perform a synchronous control operation on a port</fsummary>
+ <type>
+ <v>Port = port() | atom()</v>
+ <v>Operation = int()</v>
+ <v>Data = Res = iodata()</v>
+ </type>
+ <desc>
+ <p>Performs a synchronous control operation on a port.
+ The meaning of <c>Operation</c> and <c>Data</c> depends on
+ the port, i.e., on the port driver. Not all port drivers
+ support this control feature.</p>
+ <p>Returns: a list of integers in the range 0 through 255, or a
+ binary, depending on the port driver. The meaning of
+ the returned data also depends on the port driver.</p>
+ <p>Failure: <c>badarg</c> if <c>Port</c> is not an open port or
+ the registered name of an open port, if <c>Operation</c>
+ cannot fit in a 32-bit integer, if the port driver does not
+ support synchronous control operations, or if the port driver
+ so decides for any reason (probably something wrong with
+ <c>Operation</c> or <c>Data</c>).</p>
+ </desc>
+ </func>
+ <func>
+ <name>erlang:port_call(Port, Operation, Data) -> term()</name>
+ <fsummary>Synchronous call to a port with term data</fsummary>
+ <type>
+ <v>Port = port() | atom()</v>
+ <v>Operation = int()</v>
+ <v>Data = term()</v>
+ </type>
+ <desc>
+ <p>Performs a synchronous call to a port. The meaning of
+ <c>Operation</c> and <c>Data</c> depends on the port, i.e.,
+ on the port driver. Not all port drivers support this feature.</p>
+ <p><c>Port</c> is a port identifier, referring to a driver.</p>
+ <p><c>Operation</c> is an integer, which is passed on to
+ the driver.</p>
+ <p><c>Data</c> is any Erlang term. This data is converted to
+ binary term format and sent to the port.</p>
+ <p>Returns: a term from the driver. The meaning of the returned
+ data also depends on the port driver.</p>
+ <p>Failure: <c>badarg</c> if <c>Port</c> is not an open port or
+ the registered name of an open port, if <c>Operation</c>
+ cannot fit in a 32-bit integer, if the port driver does not
+ support synchronous control operations, or if the port driver
+ so decides for any reason (probably something wrong with
+ <c>Operation</c> or <c>Data</c>).</p>
+ </desc>
+ </func>
+ <func>
+ <name>erlang:port_info(Port) -> [{Item, Info}] | undefined</name>
+ <fsummary>Information about a port</fsummary>
+ <type>
+ <v>Port = port() | atom()</v>
+ <v>Item, Info -- see below</v>
+ </type>
+ <desc>
+ <p>Returns a list containing tuples with information about
+ the <c>Port</c>, or <c>undefined</c> if the port is not open.
+ The order of the tuples is not defined, nor are all the
+ tuples mandatory.</p>
+ <taglist>
+ <tag><c>{registered_name, RegName}</c></tag>
+ <item>
+ <p><c>RegName</c> (an atom) is the registered name of
+ the port. If the port has no registered name, this tuple
+ is not present in the list.</p>
+ </item>
+ <tag><c>{id, Index}</c></tag>
+ <item>
+ <p><c>Index</c> (an integer) is the internal index of the
+ port. This index may be used to separate ports.</p>
+ </item>
+ <tag><c>{connected, Pid}</c></tag>
+ <item>
+ <p><c>Pid</c> is the process connected to the port.</p>
+ </item>
+ <tag><c>{links, Pids}</c></tag>
+ <item>
+ <p><c>Pids</c> is a list of pids to which processes the
+ port is linked.</p>
+ </item>
+ <tag><c>{name, String}</c></tag>
+ <item>
+ <p><c>String</c> is the command name set by
+ <c>open_port</c>.</p>
+ </item>
+ <tag><c>{input, Bytes}</c></tag>
+ <item>
+ <p><c>Bytes</c> is the total number of bytes read from
+ the port.</p>
+ </item>
+ <tag><c>{output, Bytes}</c></tag>
+ <item>
+ <p><c>Bytes</c> is the total number of bytes written to
+ the port.</p>
+ </item>
+ </taglist>
+ <p>Failure: <c>badarg</c> if <c>Port</c> is not a local port.</p>
+ </desc>
+ </func>
+ <func>
+ <name>erlang:port_info(Port, Item) -> {Item, Info} | undefined | []</name>
+ <fsummary>Information about a port</fsummary>
+ <type>
+ <v>Port = port() | atom()</v>
+ <v>Item, Info -- see below</v>
+ </type>
+ <desc>
+ <p>Returns information about <c>Port</c> as specified
+ by <c>Item</c>, or <c>undefined</c> if the port is not open.
+ Also, if <c>Item == registered_name</c> and the port has no
+ registered name, [] is returned.</p>
+ <p>For valid values of <c>Item</c>, and corresponding
+ values of <c>Info</c>, see
+ <seealso marker="#erlang:port_info/1">erlang:port_info/1</seealso>.</p>
+ <p>Failure: <c>badarg</c> if <c>Port</c> is not a local port.</p>
+ </desc>
+ </func>
+ <func>
+ <name>erlang:port_to_list(Port) -> string()</name>
+ <fsummary>Text representation of a port identifier</fsummary>
+ <type>
+ <v>Port = port()</v>
+ </type>
+ <desc>
+ <p>Returns a string which corresponds to the text
+ representation of the port identifier <c>Port</c>.</p>
+ <warning>
+ <p>This BIF is intended for debugging and for use in
+ the Erlang operating system. It should not be used in
+ application programs.</p>
+ </warning>
+ </desc>
+ </func>
+ <func>
+ <name>erlang:ports() -> [port()]</name>
+ <fsummary>All open ports</fsummary>
+ <desc>
+ <p>Returns a list of all ports on the local node.</p>
+ </desc>
+ </func>
+ <func>
+ <name>pre_loaded() -> [Module]</name>
+ <fsummary>List of all pre-loaded modules</fsummary>
+ <type>
+ <v>Module = atom()</v>
+ </type>
+ <desc>
+ <p>Returns a list of Erlang modules which are pre-loaded in
+ the system. As all loading of code is done through the file
+ system, the file system must have been loaded previously.
+ Hence, at least the module <c>init</c> must be pre-loaded.</p>
+ </desc>
+ </func>
+ <func>
+ <name>erlang:process_display(Pid, Type) -> void()</name>
+ <fsummary>Write information about a local process on standard error</fsummary>
+ <type>
+ <v>Pid = pid()</v>
+ <v>Type = backtrace</v>
+ </type>
+ <desc>
+ <p>Writes information about the local process <c>Pid</c> on
+ standard error. The currently allowed value for the atom
+ <c>Type</c> is <c>backtrace</c>, which shows the contents of
+ the call stack, including information about the call chain, with
+ the current function printed first. The format of the output
+ is not further defined.</p>
+ </desc>
+ </func>
+ <func>
+ <name>process_flag(Flag, Value) -> OldValue</name>
+ <fsummary>Set process flags for the calling process</fsummary>
+ <type>
+ <v>Flag, Value, OldValue -- see below</v>
+ </type>
+ <desc>
+ <p>Sets certain flags for the process which calls this
+ function. Returns the old value of the flag.</p>
+ <taglist>
+ <tag><c>process_flag(trap_exit, Boolean)</c></tag>
+ <item>
+ <p>When <c>trap_exit</c> is set to <c>true</c>, exit signals
+ arriving to a process are converted to <c>{'EXIT', From, Reason}</c> messages, which can be received as ordinary
+ messages. If <c>trap_exit</c> is set to <c>false</c>, the
+ process exits if it receives an exit signal other than
+ <c>normal</c> and the exit signal is propagated to its
+ linked processes. Application processes should normally
+ not trap exits.</p>
+ <p>See also <seealso marker="#exit/2">exit/2</seealso>.</p>
+ </item>
+ <tag><c>process_flag(error_handler, Module)</c></tag>
+ <item>
+ <p>This is used by a process to redefine the error handler
+ for undefined function calls and undefined registered
+ processes. Inexperienced users should not use this flag
+ since code auto-loading is dependent on the correct
+ operation of the error handling module.</p>
+ </item>
+ <tag><c>process_flag(min_heap_size, MinHeapSize)</c></tag>
+ <item>
+ <p>This changes the minimum heap size for the calling
+ process.</p>
+ </item>
+ <tag><c>process_flag(priority, Level)</c></tag>
+ <item>
+ <marker id="process_flag_priority"></marker>
+ <p>This sets the process priority. <c>Level</c> is an atom.
+ There are currently four priority levels: <c>low</c>,
+ <c>normal</c>, <c>high</c>, and <c>max</c>. The default
+ priority level is <c>normal</c>. <em>NOTE</em>: The
+ <c>max</c> priority level is reserved for internal use in
+ the Erlang runtime system, and should <em>not</em> be used
+ by others.
+ </p>
+ <p>Internally in each priority level processes are scheduled
+ in a round robin fashion.
+ </p>
+ <p>Execution of processes on priority <c>normal</c> and
+ priority <c>low</c> will be interleaved. Processes on
+ priority <c>low</c> will be selected for execution less
+ frequently than processes on priority <c>normal</c>.
+ </p>
+ <p>When there are runnable processes on priority <c>high</c>
+ no processes on priority <c>low</c>, or <c>normal</c> will
+ be selected for execution. Note, however, that this does
+ <em>not</em> mean that no processes on priority <c>low</c>,
+ or <c>normal</c> will be able to run when there are
+ processes on priority <c>high</c> running. On the runtime
+ system with SMP support there might be more processes running
+ in parallel than processes on priority <c>high</c>, i.e.,
+ a <c>low</c>, and a <c>high</c> priority process might
+ execute at the same time.
+ </p>
+ <p>When there are runnable processes on priority <c>max</c>
+ no processes on priority <c>low</c>, <c>normal</c>, or
+ <c>high</c> will be selected for execution. As with the
+ <c>high</c> priority, processes on lower priorities might
+ execute in parallel with processes on priority <c>max</c>.
+ </p>
+ <p>Scheduling is preemptive. Regardless of priority, a process
+ is preempted when it has consumed more than a certain amount
+ of reductions since the last time it was selected for
+ execution.
+ </p>
+ <p><em>NOTE</em>: You should not depend on the scheduling
+ to remain exactly as it is today. Scheduling, at least on
+ the runtime system with SMP support, is very likely to be
+ modified in the future in order to better utilize available
+ processor cores.
+ </p>
+ <p>There is currently <em>no</em> automatic mechanism for
+ avoiding priority inversion, such as priority inheritance,
+ or priority ceilings. When using priorities you have
+ to take this into account and handle such scenarios by
+ yourself.
+ </p>
+ <p>Making calls from a <c>high</c> priority process into code
+ that you don't have control over may cause the <c>high</c>
+ priority process to wait for a processes with lower
+ priority, i.e., effectively decreasing the priority of the
+ <c>high</c> priority process during the call. Even if this
+ isn't the case with one version of the code that you don't
+ have under your control, it might be the case in a future
+ version of it. This might, for example, happen if a
+ <c>high</c> priority process triggers code loading, since
+ the code server runs on priority <c>normal</c>.
+ </p>
+ <p>Other priorities than <c>normal</c> are normally not needed.
+ When other priorities are used, they need to be used
+ with care, especially the <c>high</c> priority <em>must</em>
+ be used with care. A process on <c>high</c> priority should
+ only perform work for short periods of time. Busy looping for
+ long periods of time in a <c>high</c> priority process will
+ most likely cause problems, since there are important servers
+ in OTP running on priority <c>normal</c>.
+ </p>
+ </item>
+
+ <tag><c>process_flag(save_calls, N)</c></tag>
+ <item>
+ <p>When there are runnable processes on priority <c>max</c>
+ no processes on priority <c>low</c>, <c>normal</c>, or
+ <c>high</c> will be selected for execution. As with the
+ <c>high</c> priority, processes on lower priorities might
+ execute in parallel with processes on priority <c>max</c>.
+ </p>
+ <p><c>N</c> must be an integer in the interval 0..10000.
+ If <c>N</c> &gt; 0, call saving is made active for the
+ process, which means that information about the <c>N</c>
+ most recent global function calls, BIF calls, sends and
+ receives made by the process are saved in a list, which
+ can be retrieved with
+ <c>process_info(Pid, last_calls)</c>. A global function
+ call is one in which the module of the function is
+ explicitly mentioned. Only a fixed amount of information
+ is saved: a tuple <c>{Module, Function, Arity}</c> for
+ function calls, and the mere atoms <c>send</c>,
+ <c>'receive'</c> and <c>timeout</c> for sends and receives
+ (<c>'receive'</c> when a message is received and
+ <c>timeout</c> when a receive times out). If <c>N</c> = 0,
+ call saving is disabled for the process, which is the
+ default. Whenever the size of the call saving list is set,
+ its contents are reset.</p>
+ </item>
+ <tag><c>process_flag(sensitive, Boolean)</c></tag>
+ <item>
+ <p>Set or clear the <c>sensitive</c> flag for the current process.
+ When a process has been marked as sensitive by calling
+ <c>process_flag(sensitive, true)</c>, features in the run-time
+ system that can be used for examining the data and/or inner working
+ of the process are silently disabled.</p>
+ <p>Features that are disabled include (but are not limited to)
+ the following:</p>
+ <p>Tracing: Trace flags can still be set for the process, but no
+ trace messages of any kind will be generated.
+ (If the <c>sensitive</c> flag is turned off, trace messages will
+ again be generated if there are any trace flags set.)</p>
+ <p>Sequential tracing: The sequential trace token will be propagated
+ as usual, but no sequential trace messages will be generated.</p>
+ <p><c>process_info/1,2</c> cannot be used to read out the message
+ queue or the process dictionary (both will be returned as empty lists).</p>
+ <p>Stack back-traces cannot be displayed for the process.</p>
+ <p>In crash dumps, the stack, messages, and the process dictionary
+ will be omitted.</p>
+ <p>If <c>{save_calls,N}</c> has been set for the process, no
+ function calls will be saved to the call saving list.
+ (The call saving list will not be cleared; furthermore, send, receive,
+ and timeout events will still be added to the list.)</p>
+ </item>
+ </taglist>
+ </desc>
+ </func>
+ <func>
+ <name>process_flag(Pid, Flag, Value) -> OldValue</name>
+ <fsummary>Set process flags for a process</fsummary>
+ <type>
+ <v>Pid = pid()</v>
+ <v>Flag, Value, OldValue -- see below</v>
+ </type>
+ <desc>
+ <p>Sets certain flags for the process <c>Pid</c>, in the same
+ manner as
+ <seealso marker="#process_flag/2">process_flag/2</seealso>.
+ Returns the old value of the flag. The allowed values for
+ <c>Flag</c> are only a subset of those allowed in
+ <c>process_flag/2</c>, namely: <c>save_calls</c>.</p>
+ <p>Failure: <c>badarg</c> if <c>Pid</c> is not a local process.</p>
+ </desc>
+ </func>
+ <func>
+ <name>process_info(Pid) -> InfoResult</name>
+ <fsummary>Information about a process</fsummary>
+ <type>
+ <v>Pid = pid()</v>
+ <v>Item = atom()</v>
+ <v>Info = term()</v>
+ <v>InfoTuple = {Item, Info}</v>
+ <v>InfoTupleList = [InfoTuple]</v>
+ <v>InfoResult = InfoTupleList | undefined</v>
+ </type>
+ <desc>
+ <p>Returns a list containing <c>InfoTuple</c>s with
+ miscellaneous information about the process identified by
+ <c>Pid</c>, or <c>undefined</c> if the process is not alive.
+ </p>
+ <p>
+ The order of the <c>InfoTuple</c>s is not defined, nor
+ are all the <c>InfoTuple</c>s mandatory. The <c>InfoTuple</c>s
+ part of the result may be changed without prior notice.
+ Currently <c>InfoTuple</c>s with the following <c>Item</c>s
+ are part of the result:
+ <c>current_function</c>, <c>initial_call</c>, <c>status</c>,
+ <c>message_queue_len</c>, <c>messages</c>, <c>links</c>,
+ <c>dictionary</c>, <c>trap_exit</c>, <c>error_handler</c>,
+ <c>priority</c>, <c>group_leader</c>, <c>total_heap_size</c>,
+ <c>heap_size</c>, <c>stack_size</c>, <c>reductions</c>, and
+ <c>garbage_collection</c>.
+ If the process identified by <c>Pid</c> has a registered name
+ also an <c>InfoTuple</c> with <c>Item == registered_name</c>
+ will appear.
+ </p>
+ <p>See <seealso marker="#process_info/2">process_info/2</seealso>
+ for information about specific <c>InfoTuple</c>s.</p>
+ <warning>
+ <p>This BIF is intended for <em>debugging only</em>, use
+ <seealso marker="#process_info/2">process_info/2</seealso>
+ for all other purposes.
+ </p>
+ </warning>
+ <p>Failure: <c>badarg</c> if <c>Pid</c> is not a local process.</p>
+ </desc>
+ </func>
+ <func>
+ <name>process_info(Pid, ItemSpec) -> InfoResult</name>
+ <fsummary>Information about a process</fsummary>
+ <type>
+ <v>Pid = pid()</v>
+ <v>Item = atom()</v>
+ <v>Info = term()</v>
+ <v>ItemList = [Item]</v>
+ <v>ItemSpec = Item | ItemList</v>
+ <v>InfoTuple = {Item, Info}</v>
+ <v>InfoTupleList = [InfoTuple]</v>
+ <v>InfoResult = InfoTuple | InfoTupleList | undefined | []</v>
+ </type>
+ <desc>
+ <p>Returns information about the process identified by <c>Pid</c>
+ as specified by the <c>ItemSpec</c>, or <c>undefined</c> if the
+ process is not alive.
+ </p>
+ <p>If the process is alive and <c>ItemSpec</c> is a single
+ <c>Item</c>, the returned value is the corresponding
+ <c>InfoTuple</c> unless <c>ItemSpec == registered_name</c>
+ and the process has no registered name. In this case
+ <c>[]</c> is returned. This strange behavior is due to
+ historical reasons, and is kept for backward compatibility.
+ </p>
+ <p>If <c>ItemSpec</c> is an <c>ItemList</c>, the result is an
+ <c>InfoTupleList</c>. The <c>InfoTuple</c>s in the
+ <c>InfoTupleList</c> will appear with the corresponding
+ <c>Item</c>s in the same order as the <c>Item</c>s appeared
+ in the <c>ItemList</c>. Valid <c>Item</c>s may appear multiple
+ times in the <c>ItemList</c>.
+ </p>
+ <note><p>If <c>registered_name</c> is part of an <c>ItemList</c>
+ and the process has no name registered a
+ <c>{registered_name, []}</c> <c>InfoTuple</c> <em>will</em>
+ appear in the resulting <c>InfoTupleList</c>. This
+ behavior is different than when
+ <c>ItemSpec == registered_name</c>, and than when
+ <c>process_info/1</c> is used.
+ </p></note>
+ <p>Currently the following <c>InfoTuple</c>s with corresponding
+ <c>Item</c>s are valid:</p>
+ <taglist>
+ <tag><c>{backtrace, Bin}</c></tag>
+ <item>
+ <p>The binary <c>Bin</c> contains the same information as
+ the output from
+ <c>erlang:process_display(Pid, backtrace)</c>. Use
+ <c>binary_to_list/1</c> to obtain the string of characters
+ from the binary.</p>
+ </item>
+ <tag><c>{binary, BinInfo}</c></tag>
+ <item>
+ <p><c>BinInfo</c> is a list containing miscellaneous information
+ about binaries currently being referred to by this process.
+ This <c>InfoTuple</c> may be changed or removed without prior
+ notice.</p>
+ </item>
+ <tag><c>{catchlevel, CatchLevel}</c></tag>
+ <item>
+ <p><c>CatchLevel</c> is the number of currently active
+ catches in this process. This <c>InfoTuple</c> may be
+ changed or removed without prior notice.</p>
+ </item>
+ <tag><c>{current_function, {Module, Function, Args}}</c></tag>
+ <item>
+ <p><c>Module</c>, <c>Function</c>, <c>Args</c> is
+ the current function call of the process.</p>
+ </item>
+ <tag><c>{dictionary, Dictionary}</c></tag>
+ <item>
+ <p><c>Dictionary</c> is the dictionary of the process.</p>
+ </item>
+ <tag><c>{error_handler, Module}</c></tag>
+ <item>
+ <p><c>Module</c> is the error handler module used by
+ the process (for undefined function calls, for example).</p>
+ </item>
+ <tag><c>{garbage_collection, GCInfo}</c></tag>
+ <item>
+ <p><c>GCInfo</c> is a list which contains miscellaneous
+ information about garbage collection for this process.
+ The content of <c>GCInfo</c> may be changed without
+ prior notice.</p>
+ </item>
+ <tag><c>{group_leader, GroupLeader}</c></tag>
+ <item>
+ <p><c>GroupLeader</c> is group leader for the IO of
+ the process.</p>
+ </item>
+ <tag><c>{heap_size, Size}</c></tag>
+ <item>
+ <p><c>Size</c> is the size in words of youngest heap generation
+ of the process. This generation currently include the stack
+ of the process. This information is highly implementation
+ dependent, and may change if the implementation change.
+ </p>
+ </item>
+ <tag><c>{initial_call, {Module, Function, Arity}}</c></tag>
+ <item>
+ <p><c>Module</c>, <c>Function</c>, <c>Arity</c> is
+ the initial function call with which the process was
+ spawned.</p>
+ </item>
+ <tag><c>{links, Pids}</c></tag>
+ <item>
+ <p><c>Pids</c> is a list of pids, with processes to
+ which the process has a link.</p>
+ </item>
+ <tag><c>{last_calls, false|Calls}</c></tag>
+ <item>
+ <p>The value is <c>false</c> if call saving is not active
+ for the process (see
+ <seealso marker="#process_flag/3">process_flag/3</seealso>).
+ If call saving is active, a list is returned, in which
+ the last element is the most recent called.</p>
+ </item>
+ <tag><c>{memory, Size}</c></tag>
+ <item>
+ <p><c>Size</c> is the size in bytes of the process. This
+ includes call stack, heap and internal structures.</p>
+ </item>
+ <tag><c>{message_binary, BinInfo}</c></tag>
+ <item>
+ <p><c>BinInfo</c> is a list containing miscellaneous information
+ about binaries currently being referred to by the message
+ area. This <c>InfoTuple</c> is only valid on an emulator
+ using the hybrid heap type. This <c>InfoTuple</c> may be
+ changed or removed without prior notice.</p>
+ </item>
+ <tag><c>{message_queue_len, MessageQueueLen}</c></tag>
+ <item>
+ <p><c>MessageQueueLen</c> is the number of messages
+ currently in the message queue of the process. This is
+ the length of the list <c>MessageQueue</c> returned as
+ the info item <c>messages</c> (see below).</p>
+ </item>
+ <tag><c>{messages, MessageQueue}</c></tag>
+ <item>
+ <p><c>MessageQueue</c> is a list of the messages to
+ the process, which have not yet been processed.</p>
+ </item>
+ <tag><c>{monitored_by, Pids}</c></tag>
+ <item>
+ <p>A list of pids that are monitoring the process (with
+ <c>erlang:monitor/2</c>).</p>
+ </item>
+ <tag><c>{monitors, Monitors}</c></tag>
+ <item>
+ <p>A list of monitors (started by <c>erlang:monitor/2</c>)
+ that are active for the process. For a local process
+ monitor or a remote process monitor by pid, the list item
+ is <c>{process, Pid}</c>, and for a remote process
+ monitor by name, the list item is
+ <c>{process, {RegName, Node}}</c>.</p>
+ </item>
+ <tag><c>{priority, Level}</c></tag>
+ <item>
+ <p><c>Level</c> is the current priority level for
+ the process. For more information on priorities see
+ <seealso marker="#process_flag_priority">process_flag(priority, Level)</seealso>.</p>
+ </item>
+ <tag><c>{reductions, Number}</c></tag>
+ <item>
+ <p><c>Number</c> is the number of reductions executed by
+ the process.</p>
+ </item>
+ <tag><c>{registered_name, Atom}</c></tag>
+ <item>
+ <p><c>Atom</c> is the registered name of the process. If
+ the process has no registered name, this tuple is not
+ present in the list.</p>
+ </item>
+ <tag><c>{sequential_trace_token, [] | SequentialTraceToken}</c></tag>
+ <item>
+ <p><c>SequentialTraceToken</c> the sequential trace token for
+ the process. This <c>InfoTuple</c> may be changed or removed
+ without prior notice.</p>
+ </item>
+ <tag><c>{stack_size, Size}</c></tag>
+ <item>
+ <p><c>Size</c> is the stack size of the process in words.</p>
+ </item>
+ <tag><c>{status, Status}</c></tag>
+ <item>
+ <p><c>Status</c> is the status of the process. <c>Status</c>
+ is <c>waiting</c> (waiting for a message), <c>running</c>,
+ <c>runnable</c> (ready to run, but another process is
+ running), or <c>suspended</c> (suspended on a "busy" port
+ or by the <c>erlang:suspend_process/[1,2]</c> BIF).</p>
+ </item>
+ <tag><c>{suspending, SuspendeeList}</c></tag>
+ <item>
+ <p><c>SuspendeeList</c> is a list of <c>{Suspendee,
+ ActiveSuspendCount, OutstandingSuspendCount}</c> tuples.
+ <c>Suspendee</c> is the pid of a process that have been or is to
+ be suspended by the process identified by <c>Pid</c> via the
+ <seealso marker="#erlang:suspend_process/2">erlang:suspend_process/2</seealso>
+ BIF, or the
+ <seealso marker="#erlang:suspend_process/1">erlang:suspend_process/1</seealso>
+ BIF. <c>ActiveSuspendCount</c> is the number of times the
+ <c>Suspendee</c> has been suspended by <c>Pid</c>.
+ <c>OutstandingSuspendCount</c> is the number of not yet
+ completed suspend requests sent by <c>Pid</c>. That is,
+ if <c>ActiveSuspendCount /= 0</c>, <c>Suspendee</c> is
+ currently in the suspended state, and if
+ <c>OutstandingSuspendCount /= 0</c> the <c>asynchronous</c>
+ option of <c>erlang:suspend_process/2</c> has been used and
+ the suspendee has not yet been suspended by <c>Pid</c>.
+ Note that the <c>ActiveSuspendCount</c> and
+ <c>OutstandingSuspendCount</c> are not the total suspend count
+ on <c>Suspendee</c>, only the parts contributed by <c>Pid</c>.
+ </p>
+ </item>
+ <tag><c>{total_heap_size, Size}</c></tag>
+ <item>
+ <p><c>Size</c> is the total size in words of all heap
+ fragments of the process. This currently include the stack
+ of the process.
+ </p>
+ </item>
+ <tag><c>{trace, InternalTraceFlags}</c></tag>
+ <item>
+ <p><c>InternalTraceFlags</c> is an integer representing
+ internal trace flag for this process. This <c>InfoTuple</c>
+ may be changed or removed without prior notice.</p>
+ </item>
+ <tag><c>{trap_exit, Boolean}</c></tag>
+ <item>
+ <p><c>Boolean</c> is <c>true</c> if the process is trapping
+ exits, otherwise it is <c>false</c>.</p>
+ </item>
+ </taglist>
+ <p>Note however, that not all implementations support every one
+ of the above <c>Items</c>.</p>
+ <p>Failure: <c>badarg</c> if <c>Pid</c> is not a local process,
+ or if <c>Item</c> is not a valid <c>Item</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>processes() -> [pid()]</name>
+ <fsummary>All processes</fsummary>
+ <desc>
+ <p>Returns a list of process identifiers corresponding to
+ all the processes currently existing on the local node.
+ </p>
+ <p>Note that a process that is exiting, exists but is not alive, i.e.,
+ <c>is_process_alive/1</c> will return <c>false</c> for a process
+ that is exiting, but its process identifier will be part
+ of the result returned from <c>processes/0</c>.
+ </p>
+ <pre>
+> <input>processes().</input>
+[&lt;0.0.0&gt;,&lt;0.2.0&gt;,&lt;0.4.0&gt;,&lt;0.5.0&gt;,&lt;0.7.0&gt;,&lt;0.8.0&gt;]</pre>
+ </desc>
+ </func>
+ <func>
+ <name>purge_module(Module) -> void()</name>
+ <fsummary>Remove old code for a module</fsummary>
+ <type>
+ <v>Module = atom()</v>
+ </type>
+ <desc>
+ <p>Removes old code for <c>Module</c>. Before this BIF is used,
+ <c>erlang:check_process_code/2</c> should be called to check
+ that no processes are executing old code in the module.</p>
+ <warning>
+ <p>This BIF is intended for the code server (see
+ <seealso marker="kernel:code">code(3)</seealso>) and should not be
+ used elsewhere.</p>
+ </warning>
+ <p>Failure: <c>badarg</c> if there is no old code for
+ <c>Module</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>put(Key, Val) -> OldVal | undefined</name>
+ <fsummary>Add a new value to the process dictionary</fsummary>
+ <type>
+ <v>Key = Val = OldVal = term()</v>
+ </type>
+ <desc>
+ <p>Adds a new <c>Key</c> to the process dictionary, associated
+ with the value <c>Val</c>, and returns <c>undefined</c>. If
+ <c>Key</c> already exists, the old value is deleted and
+ replaced by <c>Val</c> and the function returns the old value.</p>
+ <note>
+ <p>The values stored when <c>put</c> is evaluated within
+ the scope of a <c>catch</c> will not be retracted if a
+ <c>throw</c> is evaluated, or if an error occurs.</p>
+ </note>
+ <pre>
+> <input>X = put(name, walrus), Y = put(name, carpenter),</input>
+<input>Z = get(name),</input>
+<input>{X, Y, Z}.</input>
+{undefined,walrus,carpenter}</pre>
+ </desc>
+ </func>
+ <func>
+ <name>erlang:raise(Class, Reason, Stacktrace)</name>
+ <fsummary>Stop execution with an exception of given class, reason and call stack backtrace</fsummary>
+ <type>
+ <v>Class = error | exit | throw</v>
+ <v>Reason = term()</v>
+ <v>Stacktrace = [{Module, Function, Arity | Args} | {Fun, Args}]</v>
+ <v>&nbsp;Module = Function = atom()</v>
+ <v>&nbsp;Arity = int()</v>
+ <v>&nbsp;Args = [term()]</v>
+ <v>&nbsp;Fun = [fun()]</v>
+ </type>
+ <desc>
+ <p>Stops the execution of the calling process with an
+ exception of given class, reason and call stack backtrace
+ (<em>stacktrace</em>).</p>
+ <warning>
+ <p>This BIF is intended for debugging and for use in
+ the Erlang operating system. In general, it should
+ be avoided in applications, unless you know
+ very well what you are doing.</p>
+ </warning>
+ <p><c>Class</c> is one of <c>error</c>, <c>exit</c> or
+ <c>throw</c>, so if it were not for the stacktrace
+ <c>erlang:raise(Class, Reason, Stacktrace)</c> is
+ equivalent to <c>erlang:Class(Reason)</c>.
+ <c>Reason</c> is any term and <c>Stacktrace</c> is a list as
+ returned from <c>get_stacktrace()</c>, that is a list of
+ 3-tuples <c>{Module, Function, Arity | Args}</c> where
+ <c>Module</c> and <c>Function</c> are atoms and the third
+ element is an integer arity or an argument list. The
+ stacktrace may also contain <c>{Fun, Args}</c> tuples where
+ <c>Fun</c> is a local fun and <c>Args</c> is an argument list.</p>
+ <p>The stacktrace is used as the exception stacktrace for the
+ calling process; it will be truncated to the current
+ maximum stacktrace depth.</p>
+ <p>Because evaluating this function causes the process to
+ terminate, it has no return value - unless the arguments are
+ invalid, in which case the function <em>returns the error reason</em>, that is <c>badarg</c>. If you want to be
+ really sure not to return you can call
+ <c>erlang:error(erlang:raise(Class, Reason, Stacktrace))</c>
+ and hope to distinguish exceptions later.</p>
+ </desc>
+ </func>
+ <func>
+ <name>erlang:read_timer(TimerRef) -> int() | false</name>
+ <fsummary>Number of milliseconds remaining for a timer</fsummary>
+ <type>
+ <v>TimerRef = ref()</v>
+ </type>
+ <desc>
+ <p><c>TimerRef</c> is a timer reference returned by
+ <seealso marker="#erlang:send_after/3">erlang:send_after/3</seealso>
+ or
+ <seealso marker="#erlang:start_timer/3">erlang:start_timer/3</seealso>.
+ If the timer is active, the function returns the time in
+ milliseconds left until the timer will expire, otherwise
+ <c>false</c> (which means that <c>TimerRef</c> was never a
+ timer, that it has been cancelled, or that it has already
+ delivered its message).</p>
+ <p>See also
+ <seealso marker="#erlang:send_after/3">erlang:send_after/3</seealso>,
+ <seealso marker="#erlang:start_timer/3">erlang:start_timer/3</seealso>,
+ and
+ <seealso marker="#erlang:cancel_timer/1">erlang:cancel_timer/1</seealso>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>erlang:ref_to_list(Ref) -> string()</name>
+ <fsummary>Text representation of a reference</fsummary>
+ <type>
+ <v>Ref = ref()</v>
+ </type>
+ <desc>
+ <p>Returns a string which corresponds to the text
+ representation of <c>Ref</c>.</p>
+ <warning>
+ <p>This BIF is intended for debugging and for use in
+ the Erlang operating system. It should not be used in
+ application programs.</p>
+ </warning>
+ </desc>
+ </func>
+ <func>
+ <name>register(RegName, Pid | Port) -> true</name>
+ <fsummary>Register a name for a pid (or port)</fsummary>
+ <type>
+ <v>RegName = atom()</v>
+ <v>Pid = pid()</v>
+ <v>Port = port()</v>
+ </type>
+ <desc>
+ <p>Associates the name <c>RegName</c> with a pid or a port
+ identifier. <c>RegName</c>, which must be an atom, can be used
+ instead of the pid / port identifier in the send operator
+ (<c>RegName ! Message</c>).</p>
+ <pre>
+> <input>register(db, Pid).</input>
+true</pre>
+ <p>Failure: <c>badarg</c> if <c>Pid</c> is not an existing,
+ local process or port, if <c>RegName</c> is already in use,
+ if the process or port is already registered (already has a
+ name), or if <c>RegName</c> is the atom <c>undefined</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>registered() -> [RegName]</name>
+ <fsummary>All registered names</fsummary>
+ <type>
+ <v>RegName = atom()</v>
+ </type>
+ <desc>
+ <p>Returns a list of names which have been registered using
+ <seealso marker="#register/2">register/2</seealso>.</p>
+ <pre>
+> <input>registered().</input>
+[code_server, file_server, init, user, my_db]</pre>
+ </desc>
+ </func>
+ <func>
+ <name>erlang:resume_process(Suspendee) -> true</name>
+ <fsummary>Resume a suspended process</fsummary>
+ <type>
+ <v>Suspendee = pid()</v>
+ </type>
+ <desc>
+ <p>Decreases the suspend count on the process identified by
+ <c>Suspendee</c>. <c>Suspendee</c> should previously have been
+ suspended via
+ <seealso marker="#erlang:suspend_process/2">erlang:suspend_process/2</seealso>,
+ or
+ <seealso marker="#erlang:suspend_process/1">erlang:suspend_process/1</seealso>
+ by the process calling <c>erlang:resume_process(Suspendee)</c>. When
+ the suspend count on <c>Suspendee</c> reach zero, <c>Suspendee</c>
+ will be resumed, i.e., the state of the <c>Suspendee</c> is changed
+ from suspended into the state <c>Suspendee</c> was in before it was
+ suspended.
+ </p>
+ <warning>
+ <p>This BIF is intended for debugging only.</p>
+ </warning>
+ <p>Failures:</p>
+ <taglist>
+ <tag><c>badarg</c></tag>
+ <item>
+ If <c>Suspendee</c> isn't a process identifier.
+ </item>
+ <tag><c>badarg</c></tag>
+ <item>
+ If the process calling <c>erlang:resume_process/1</c> had
+ not previously increased the suspend count on the process
+ identified by <c>Suspendee</c>.
+ </item>
+ <tag><c>badarg</c></tag>
+ <item>
+ If the process identified by <c>Suspendee</c> is not alive.
+ </item>
+ </taglist>
+ </desc>
+ </func>
+ <func>
+ <name>round(Number) -> int()</name>
+ <fsummary>Return an integer by rounding a number</fsummary>
+ <type>
+ <v>Number = number()</v>
+ </type>
+ <desc>
+ <p>Returns an integer by rounding <c>Number</c>.</p>
+ <pre>
+> <input>round(5.5).</input>
+6</pre>
+ <p>Allowed in guard tests.</p>
+ </desc>
+ </func>
+ <func>
+ <name>self() -> pid()</name>
+ <fsummary>Pid of the calling process</fsummary>
+ <desc>
+ <p>Returns the pid (process identifier) of the calling process.</p>
+ <pre>
+> <input>self().</input>
+&lt;0.26.0></pre>
+ <p>Allowed in guard tests.</p>
+ </desc>
+ </func>
+ <func>
+ <name>erlang:send(Dest, Msg) -> Msg</name>
+ <fsummary>Send a message</fsummary>
+ <type>
+ <v>Dest = pid() | port() | RegName | {RegName, Node}</v>
+ <v>Msg = term()</v>
+ <v>&nbsp;RegName = atom()</v>
+ <v>&nbsp;Node = node()</v>
+ </type>
+ <desc>
+ <p>Sends a message and returns <c>Msg</c>. This is the same as
+ <c>Dest ! Msg</c>.</p>
+ <p><c>Dest</c> may be a remote or local pid, a (local) port, a
+ locally registered name, or a tuple <c>{RegName, Node}</c>
+ for a registered name at another node.</p>
+ </desc>
+ </func>
+ <func>
+ <name>erlang:send(Dest, Msg, [Option]) -> Res</name>
+ <fsummary>Send a message conditionally</fsummary>
+ <type>
+ <v>Dest = pid() | port() | RegName | {RegName, Node}</v>
+ <v>&nbsp;RegName = atom()</v>
+ <v>&nbsp;Node = node()</v>
+ <v>Msg = term()</v>
+ <v>Option = nosuspend | noconnect</v>
+ <v>Res = ok | nosuspend | noconnect</v>
+ </type>
+ <desc>
+ <p>Sends a message and returns <c>ok</c>, or does not send
+ the message but returns something else (see below). Otherwise
+ the same as
+ <seealso marker="#erlang:send/2">erlang:send/2</seealso>. See
+ also
+ <seealso marker="#erlang:send_nosuspend/2">erlang:send_nosuspend/2,3</seealso>.
+ for more detailed explanation and warnings.</p>
+ <p>The possible options are:</p>
+ <taglist>
+ <tag><c>nosuspend</c></tag>
+ <item>
+ <p>If the sender would have to be suspended to do the send,
+ <c>nosuspend</c> is returned instead.</p>
+ </item>
+ <tag><c>noconnect</c></tag>
+ <item>
+ <p>If the destination node would have to be auto-connected
+ before doing the send, <c>noconnect</c> is returned
+ instead.</p>
+ </item>
+ </taglist>
+ <warning>
+ <p>As with <c>erlang:send_nosuspend/2,3</c>: Use with extreme
+ care!</p>
+ </warning>
+ </desc>
+ </func>
+ <func>
+ <name>erlang:send_after(Time, Dest, Msg) -> TimerRef</name>
+ <fsummary>Start a timer</fsummary>
+ <type>
+ <v>Time = int()</v>
+ <v>&nbsp;0 &lt;= Time &lt;= 4294967295</v>
+ <v>Dest = pid() | RegName </v>
+ <v>&nbsp;LocalPid = pid() (of a process, alive or dead, on the local node)</v>
+ <v>Msg = term()</v>
+ <v>TimerRef = ref()</v>
+ </type>
+ <desc>
+ <p>Starts a timer which will send the message <c>Msg</c>
+ to <c>Dest</c> after <c>Time</c> milliseconds.</p>
+ <p>If <c>Dest</c> is an atom, it is supposed to be the name of
+ a registered process. The process referred to by the name is
+ looked up at the time of delivery. No error is given if
+ the name does not refer to a process.</p>
+ <p>If <c>Dest</c> is a pid, the timer will be automatically
+ canceled if the process referred to by the pid is not alive,
+ or when the process exits. This feature was introduced in
+ erts version 5.4.11. Note that timers will not be
+ automatically canceled when <c>Dest</c> is an atom.</p>
+ <p>See also
+ <seealso marker="#erlang:start_timer/3">erlang:start_timer/3</seealso>,
+ <seealso marker="#erlang:cancel_timer/1">erlang:cancel_timer/1</seealso>,
+ and
+ <seealso marker="#erlang:read_timer/1">erlang:read_timer/1</seealso>.</p>
+ <p>Failure: <c>badarg</c> if the arguments does not satisfy
+ the requirements specified above.</p>
+ </desc>
+ </func>
+ <func>
+ <name>erlang:send_nosuspend(Dest, Msg) -> bool()</name>
+ <fsummary>Try to send a message without ever blocking</fsummary>
+ <type>
+ <v>Dest = pid() | port() | RegName | {RegName, Node}</v>
+ <v>&nbsp;RegName = atom()</v>
+ <v>&nbsp;Node = node()</v>
+ <v>Msg = term()</v>
+ </type>
+ <desc>
+ <p>The same as
+ <seealso marker="#erlang:send/3">erlang:send(Dest, Msg, [nosuspend])</seealso>, but returns <c>true</c> if
+ the message was sent and <c>false</c> if the message was not
+ sent because the sender would have had to be suspended.</p>
+ <p>This function is intended for send operations towards an
+ unreliable remote node without ever blocking the sending
+ (Erlang) process. If the connection to the remote node
+ (usually not a real Erlang node, but a node written in C or
+ Java) is overloaded, this function <em>will not send the message</em> but return <c>false</c> instead.</p>
+ <p>The same happens, if <c>Dest</c> refers to a local port that
+ is busy. For all other destinations (allowed for the ordinary
+ send operator <c>'!'</c>) this function sends the message and
+ returns <c>true</c>.</p>
+ <p>This function is only to be used in very rare circumstances
+ where a process communicates with Erlang nodes that can
+ disappear without any trace causing the TCP buffers and
+ the drivers queue to be over-full before the node will actually
+ be shut down (due to tick timeouts) by <c>net_kernel</c>. The
+ normal reaction to take when this happens is some kind of
+ premature shutdown of the other node.</p>
+ <p>Note that ignoring the return value from this function would
+ result in <em>unreliable</em> message passing, which is
+ contradictory to the Erlang programming model. The message is
+ <em>not</em> sent if this function returns <c>false</c>.</p>
+ <p>Note also that in many systems, transient states of
+ overloaded queues are normal. The fact that this function
+ returns <c>false</c> does not in any way mean that the other
+ node is guaranteed to be non-responsive, it could be a
+ temporary overload. Also a return value of <c>true</c> does
+ only mean that the message could be sent on the (TCP) channel
+ without blocking, the message is not guaranteed to have
+ arrived at the remote node. Also in the case of a disconnected
+ non-responsive node, the return value is <c>true</c> (mimics
+ the behaviour of the <c>!</c> operator). The expected
+ behaviour as well as the actions to take when the function
+ returns <c>false</c> are application and hardware specific.</p>
+ <warning>
+ <p>Use with extreme care!</p>
+ </warning>
+ </desc>
+ </func>
+ <func>
+ <name>erlang:send_nosuspend(Dest, Msg, Options) -> bool()</name>
+ <fsummary>Try to send a message without ever blocking</fsummary>
+ <type>
+ <v>Dest = pid() | port() | RegName | {RegName, Node}</v>
+ <v>&nbsp;RegName = atom()</v>
+ <v>&nbsp;Node = node()</v>
+ <v>Msg = term()</v>
+ <v>Option = noconnect</v>
+ </type>
+ <desc>
+ <p>The same as
+ <seealso marker="#erlang:send/3">erlang:send(Dest, Msg, [nosuspend | Options])</seealso>,
+ but with boolean return value.</p>
+ <p>This function behaves like
+ <seealso marker="#erlang:send_nosuspend/2">erlang:send_nosuspend/2)</seealso>,
+ but takes a third parameter, a list of options. The only
+ currently implemented option is <c>noconnect</c>. The option
+ <c>noconnect</c> makes the function return <c>false</c> if
+ the remote node is not currently reachable by the local
+ node. The normal behaviour is to try to connect to the node,
+ which may stall the process for a shorter period. The use of
+ the <c>noconnect</c> option makes it possible to be
+ absolutely sure not to get even the slightest delay when
+ sending to a remote process. This is especially useful when
+ communicating with nodes who expect to always be
+ the connecting part (i.e. nodes written in C or Java).</p>
+ <p>Whenever the function returns <c>false</c> (either when a
+ suspend would occur or when <c>noconnect</c> was specified and
+ the node was not already connected), the message is guaranteed
+ <em>not</em> to have been sent.</p>
+ <warning>
+ <p>Use with extreme care!</p>
+ </warning>
+ </desc>
+ </func>
+ <func>
+ <name>erlang:set_cookie(Node, Cookie) -> true</name>
+ <fsummary>Set the magic cookie of a node</fsummary>
+ <type>
+ <v>Node = node()</v>
+ <v>Cookie = atom()</v>
+ </type>
+ <desc>
+ <p>Sets the magic cookie of <c>Node</c> to the atom
+ <c>Cookie</c>. If <c>Node</c> is the local node, the function
+ also sets the cookie of all other unknown nodes to
+ <c>Cookie</c> (see
+ <seealso marker="doc/reference_manual:distributed">Distributed Erlang</seealso> in the Erlang Reference Manual).</p>
+ <p>Failure: <c>function_clause</c> if the local node is not
+ alive.</p>
+ </desc>
+ </func>
+ <func>
+ <name>setelement(Index, Tuple1, Value) -> Tuple2</name>
+ <fsummary>Set Nth element of a tuple</fsummary>
+ <type>
+ <v>Index = 1..tuple_size(Tuple1)</v>
+ <v>Tuple1 = Tuple2 = tuple()</v>
+ <v>Value = term()</v>
+ </type>
+ <desc>
+ <p>Returns a tuple which is a copy of the argument <c>Tuple1</c>
+ with the element given by the integer argument <c>Index</c>
+ (the first element is the element with index 1) replaced by
+ the argument <c>Value</c>.</p>
+ <pre>
+> <input>setelement(2, {10, green, bottles}, red).</input>
+{10,red,bottles}</pre>
+ </desc>
+ </func>
+ <func>
+ <name>size(Item) -> int()</name>
+ <fsummary>Size of a tuple or binary</fsummary>
+ <type>
+ <v>Item = tuple() | binary()</v>
+ </type>
+ <desc>
+ <p>Returns an integer which is the size of the argument
+ <c>Item</c>, which must be either a tuple or a binary.</p>
+ <pre>
+> <input>size({morni, mulle, bwange}).</input>
+3</pre>
+ <p>Allowed in guard tests.</p>
+ </desc>
+ </func>
+ <func>
+ <name>spawn(Fun) -> pid()</name>
+ <fsummary>Create a new process with a fun as entry point</fsummary>
+ <type>
+ <v>Fun = fun()</v>
+ </type>
+ <desc>
+ <p>Returns the pid of a new process started by the application
+ of <c>Fun</c> to the empty list <c>[]</c>. Otherwise works
+ like <seealso marker="#spawn/3">spawn/3</seealso>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>spawn(Node, Fun) -> pid()</name>
+ <fsummary>Create a new process with a fun as entry point on a given node</fsummary>
+ <type>
+ <v>Node = node()</v>
+ <v>Fun = fun()</v>
+ </type>
+ <desc>
+ <p>Returns the pid of a new process started by the application
+ of <c>Fun</c> to the empty list <c>[]</c> on <c>Node</c>. If
+ <c>Node</c> does not exist, a useless pid is returned.
+ Otherwise works like
+ <seealso marker="#spawn/3">spawn/3</seealso>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>spawn(Module, Function, Args) -> pid()</name>
+ <fsummary>Create a new process with a function as entry point</fsummary>
+ <type>
+ <v>Module = Function = atom()</v>
+ <v>Args = [term()]</v>
+ </type>
+ <desc>
+ <p>Returns the pid of a new process started by the application
+ of <c>Module:Function</c> to <c>Args</c>. The new process
+ created will be placed in the system scheduler queue and be
+ run some time later.</p>
+ <p><c>error_handler:undefined_function(Module, Function, Args)</c> is evaluated by the new process if
+ <c>Module:Function/Arity</c> does not exist (where
+ <c>Arity</c> is the length of <c>Args</c>). The error handler
+ can be redefined (see
+ <seealso marker="#process_flag/2">process_flag/2</seealso>).
+ If <c>error_handler</c> is undefined, or the user has
+ redefined the default <c>error_handler</c> its replacement is
+ undefined, a failure with the reason <c>undef</c> will occur.</p>
+ <pre>
+> <input>spawn(speed, regulator, [high_speed, thin_cut]).</input>
+&lt;0.13.1></pre>
+ </desc>
+ </func>
+ <func>
+ <name>spawn(Node, Module, Function, ArgumentList) -> pid()</name>
+ <fsummary>Create a new process with a function as entry point on a given node</fsummary>
+ <type>
+ <v>Node = node()</v>
+ <v>Module = Function = atom()</v>
+ <v>Args = [term()]</v>
+ </type>
+ <desc>
+ <p>Returns the pid of a new process started by the application
+ of <c>Module:Function</c> to <c>Args</c> on <c>Node</c>. If
+ <c>Node</c> does not exists, a useless pid is returned.
+ Otherwise works like
+ <seealso marker="#spawn/3">spawn/3</seealso>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>spawn_link(Fun) -> pid()</name>
+ <fsummary>Create and link to a new process with a fun as entry point</fsummary>
+ <type>
+ <v>Fun = fun()</v>
+ </type>
+ <desc>
+ <p>Returns the pid of a new process started by the application
+ of <c>Fun</c> to the empty list []. A link is created between
+ the calling process and the new process, atomically.
+ Otherwise works like
+ <seealso marker="#spawn/3">spawn/3</seealso>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>spawn_link(Node, Fun) -></name>
+ <fsummary>Create and link to a new process with a fun as entry point on a specified node</fsummary>
+ <type>
+ <v>Node = node()</v>
+ <v>Fun = fun()</v>
+ </type>
+ <desc>
+ <p>Returns the pid of a new process started by the application
+ of <c>Fun</c> to the empty list [] on <c>Node</c>. A link is
+ created between the calling process and the new process,
+ atomically. If <c>Node</c> does not exist, a useless pid is
+ returned (and due to the link, an exit signal with exit
+ reason <c>noconnection</c> will be received). Otherwise works
+ like <seealso marker="#spawn/3">spawn/3</seealso>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>spawn_link(Module, Function, Args) -> pid()</name>
+ <fsummary>Create and link to a new process with a function as entry point</fsummary>
+ <type>
+ <v>Module = Function = atom()</v>
+ <v>Args = [term()]</v>
+ </type>
+ <desc>
+ <p>Returns the pid of a new process started by the application
+ of <c>Module:Function</c> to <c>Args</c>. A link is created
+ between the calling process and the new process, atomically.
+ Otherwise works like
+ <seealso marker="#spawn/3">spawn/3</seealso>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>spawn_link(Node, Module, Function, Args) -> pid()</name>
+ <fsummary>Create and link to a new process with a function as entry point on a given node</fsummary>
+ <type>
+ <v>Node = node()</v>
+ <v>Module = Function = atom()</v>
+ <v>Args = [term()]</v>
+ </type>
+ <desc>
+ <p>Returns the pid of a new process started by the application
+ of <c>Module:Function</c> to <c>Args</c> on <c>Node</c>. A
+ link is created between the calling process and the new
+ process, atomically. If <c>Node</c> does not exist, a useless
+ pid is returned (and due to the link, an exit signal with exit
+ reason <c>noconnection</c> will be received). Otherwise works
+ like <seealso marker="#spawn/3">spawn/3</seealso>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>spawn_monitor(Fun) -> {pid(),reference()}</name>
+ <fsummary>Create and monitor a new process with a fun as entry point</fsummary>
+ <type>
+ <v>Fun = fun()</v>
+ </type>
+ <desc>
+ <p>Returns the pid of a new process started by the application
+ of <c>Fun</c> to the empty list [] and reference for a monitor
+ created to the new process.
+ Otherwise works like
+ <seealso marker="#spawn/3">spawn/3</seealso>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>spawn_monitor(Module, Function, Args) -> {pid(),reference()}</name>
+ <fsummary>Create and monitor a new process with a function as entry point</fsummary>
+ <type>
+ <v>Module = Function = atom()</v>
+ <v>Args = [term()]</v>
+ </type>
+ <desc>
+ <p>A new process is started by the application
+ of <c>Module:Function</c> to <c>Args</c>, and the process is
+ monitored at the same time. Returns the pid and a reference
+ for the monitor.
+ Otherwise works like
+ <seealso marker="#spawn/3">spawn/3</seealso>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>spawn_opt(Fun, [Option]) -> pid() | {pid(),reference()}</name>
+ <fsummary>Create a new process with a fun as entry point</fsummary>
+ <type>
+ <v>Fun = fun()</v>
+ <v>Option = link | monitor | {priority, Level} | {fullsweep_after, Number} | {min_heap_size, Size}</v>
+ <v>&nbsp;Level = low | normal | high</v>
+ <v>&nbsp;Number = int()</v>
+ <v>&nbsp;Size = int()</v>
+ </type>
+ <desc>
+ <p>Returns the pid of a new process started by the application
+ of <c>Fun</c> to the empty list <c>[]</c>. Otherwise
+ works like
+ <seealso marker="#spawn_opt/4">spawn_opt/4</seealso>.</p>
+ <p>If the option <c>monitor</c> is given, the newly created
+ process will be monitored and both the pid and reference for
+ the monitor will be returned.</p>
+ </desc>
+ </func>
+ <func>
+ <name>spawn_opt(Node, Fun, [Option]) -> pid()</name>
+ <fsummary>Create a new process with a fun as entry point on a given node</fsummary>
+ <type>
+ <v>Node = node()</v>
+ <v>Fun = fun()</v>
+ <v>Option = link | {priority, Level} | {fullsweep_after, Number} | {min_heap_size, Size}</v>
+ <v>&nbsp;Level = low | normal | high</v>
+ <v>&nbsp;Number = int()</v>
+ <v>&nbsp;Size = int()</v>
+ </type>
+ <desc>
+ <p>Returns the pid of a new process started by the application
+ of <c>Fun</c> to the empty list <c>[]</c> on <c>Node</c>. If
+ <c>Node</c> does not exist, a useless pid is returned.
+ Otherwise works like
+ <seealso marker="#spawn_opt/4">spawn_opt/4</seealso>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>spawn_opt(Module, Function, Args, [Option]) -> pid() | {pid(),reference()}</name>
+ <fsummary>Create a new process with a function as entry point</fsummary>
+ <type>
+ <v>Module = Function = atom()</v>
+ <v>Args = [term()]</v>
+ <v>Option = link | monitor | {priority, Level} | {fullsweep_after, Number} | {min_heap_size, Size}</v>
+ <v>&nbsp;Level = low | normal | high</v>
+ <v>&nbsp;Number = int()</v>
+ <v>&nbsp;Size = int()</v>
+ </type>
+ <desc>
+ <p>Works exactly like
+ <seealso marker="#spawn/3">spawn/3</seealso>, except that an
+ extra option list is given when creating the process.</p>
+ <p>If the option <c>monitor</c> is given, the newly created
+ process will be monitored and both the pid and reference for
+ the monitor will be returned.</p>
+ <taglist>
+ <tag><c>link</c></tag>
+ <item>
+ <p>Sets a link to the parent process (like
+ <c>spawn_link/3</c> does).</p>
+ </item>
+ <tag><c>monitor</c></tag>
+ <item>
+ <p>Monitor the new process (just like
+ <seealso marker="#erlang:monitor/2">erlang:monitor/2</seealso> does).</p>
+ </item>
+ <tag><c>{priority, Level}</c></tag>
+ <item>
+ <p>Sets the priority of the new process. Equivalent to
+ executing
+ <seealso marker="#process_flag_priority">process_flag(priority, Level)</seealso> in the start function of the new process,
+ except that the priority will be set before the process is
+ selected for execution for the first time. For more information
+ on priorities see
+ <seealso marker="#process_flag_priority">process_flag(priority, Level)</seealso>.</p>
+ </item>
+ <tag><c>{fullsweep_after, Number}</c></tag>
+ <item>
+ <p>This option is only useful for performance tuning.
+ In general, you should not use this option unless you
+ know that there is problem with execution times and/or
+ memory consumption, and you should measure to make sure
+ that the option improved matters.
+ </p>
+ <p>The Erlang runtime system uses a generational garbage
+ collection scheme, using an "old heap" for data that has
+ survived at least one garbage collection. When there is
+ no more room on the old heap, a fullsweep garbage
+ collection will be done.</p>
+ <p>The <c>fullsweep_after</c> option makes it possible to
+ specify the maximum number of generational collections
+ before forcing a fullsweep even if there is still room on
+ the old heap. Setting the number to zero effectively
+ disables the general collection algorithm, meaning that
+ all live data is copied at every garbage collection.</p>
+ <p>Here are a few cases when it could be useful to change
+ <c>fullsweep_after</c>. Firstly, if binaries that are no
+ longer used should be thrown away as soon as possible.
+ (Set <c>Number</c> to zero.) Secondly, a process that
+ mostly have short-lived data will be fullsweeped seldom
+ or never, meaning that the old heap will contain mostly
+ garbage. To ensure a fullsweep once in a while, set
+ <c>Number</c> to a suitable value such as 10 or 20.
+ Thirdly, in embedded systems with limited amount of RAM
+ and no virtual memory, one might want to preserve memory
+ by setting <c>Number</c> to zero. (The value may be set
+ globally, see
+ <seealso marker="#erlang:system_flag/2">erlang:system_flag/2</seealso>.)</p>
+ </item>
+ <tag><c>{min_heap_size, Size}</c></tag>
+ <item>
+ <p>This option is only useful for performance tuning.
+ In general, you should not use this option unless you
+ know that there is problem with execution times and/or
+ memory consumption, and you should measure to make sure
+ that the option improved matters.
+ </p>
+ <p>Gives a minimum heap size in words. Setting this value
+ higher than the system default might speed up some
+ processes because less garbage collection is done.
+ Setting too high value, however, might waste memory and
+ slow down the system due to worse data locality.
+ Therefore, it is recommended to use this option only for
+ fine-tuning an application and to measure the execution
+ time with various <c>Size</c> values.</p>
+ </item>
+ </taglist>
+ </desc>
+ </func>
+ <func>
+ <name>spawn_opt(Node, Module, Function, Args, [Option]) -> pid()</name>
+ <fsummary>Create a new process with a function as entry point on a given node</fsummary>
+ <type>
+ <v>Node = node()</v>
+ <v>Module = Function = atom()</v>
+ <v>Args = [term()]</v>
+ <v>Option = link | {priority, Level} | {fullsweep_after, Number} | {min_heap_size, Size}</v>
+ <v>&nbsp;Level = low | normal | high</v>
+ <v>&nbsp;Number = int()</v>
+ <v>&nbsp;Size = int()</v>
+ </type>
+ <desc>
+ <p>Returns the pid of a new process started by the application
+ of <c>Module:Function</c> to <c>Args</c> on <c>Node</c>. If
+ <c>Node</c> does not exist, a useless pid is returned.
+ Otherwise works like
+ <seealso marker="#spawn_opt/4">spawn_opt/4</seealso>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>split_binary(Bin, Pos) -> {Bin1, Bin2}</name>
+ <fsummary>Split a binary into two</fsummary>
+ <type>
+ <v>Bin = Bin1 = Bin2 = binary()</v>
+ <v>Pos = 1..byte_size(Bin)</v>
+ </type>
+ <desc>
+ <p>Returns a tuple containing the binaries which are the result
+ of splitting <c>Bin</c> into two parts at position <c>Pos</c>.
+ This is not a destructive operation. After the operation,
+ there will be three binaries altogether.</p>
+ <pre>
+> <input>B = list_to_binary("0123456789").</input>
+&lt;&lt;"0123456789">>
+> <input>byte_size(B).</input>
+10
+> <input>{B1, B2} = split_binary(B,3).</input>
+{&lt;&lt;"012">>,&lt;&lt;"3456789">>}
+> <input>byte_size(B1).</input>
+3
+> <input>byte_size(B2).</input>
+7</pre>
+ </desc>
+ </func>
+ <func>
+ <name>erlang:start_timer(Time, Dest, Msg) -> TimerRef</name>
+ <fsummary>Start a timer</fsummary>
+ <type>
+ <v>Time = int()</v>
+ <v>&nbsp;0 &lt;= Time &lt;= 4294967295</v>
+ <v>Dest = LocalPid | RegName </v>
+ <v>&nbsp;LocalPid = pid() (of a process, alive or dead, on the local node)</v>
+ <v>&nbsp;RegName = atom()</v>
+ <v>Msg = term()</v>
+ <v>TimerRef = ref()</v>
+ </type>
+ <desc>
+ <p>Starts a timer which will send the message
+ <c>{timeout, TimerRef, Msg}</c> to <c>Dest</c>
+ after <c>Time</c> milliseconds.</p>
+ <p>If <c>Dest</c> is an atom, it is supposed to be the name of
+ a registered process. The process referred to by the name is
+ looked up at the time of delivery. No error is given if
+ the name does not refer to a process.</p>
+ <p>If <c>Dest</c> is a pid, the timer will be automatically
+ canceled if the process referred to by the pid is not alive,
+ or when the process exits. This feature was introduced in
+ erts version 5.4.11. Note that timers will not be
+ automatically canceled when <c>Dest</c> is an atom.</p>
+ <p>See also
+ <seealso marker="#erlang:send_after/3">erlang:send_after/3</seealso>,
+ <seealso marker="#erlang:cancel_timer/1">erlang:cancel_timer/1</seealso>,
+ and
+ <seealso marker="#erlang:read_timer/1">erlang:read_timer/1</seealso>.</p>
+ <p>Failure: <c>badarg</c> if the arguments does not satisfy
+ the requirements specified above.</p>
+ </desc>
+ </func>
+ <func>
+ <name>statistics(Type) -> Res</name>
+ <fsummary>Information about the system</fsummary>
+ <type>
+ <v>Type, Res -- see below</v>
+ </type>
+ <desc>
+ <p>Returns information about the system as specified by
+ <c>Type</c>:</p>
+ <taglist>
+ <tag><c>context_switches</c></tag>
+ <item>
+ <p>Returns <c>{ContextSwitches, 0}</c>, where
+ <c>ContextSwitches</c> is the total number of context
+ switches since the system started.</p>
+ </item>
+ <tag><c>exact_reductions</c></tag>
+ <item>
+ <marker id="statistics_exact_reductions"></marker>
+ <p>Returns
+ <c>{Total_Exact_Reductions, Exact_Reductions_Since_Last_Call}</c>.</p>
+ <p><em>NOTE:</em><c>statistics(exact_reductions)</c> is
+ a more expensive operation than
+ <seealso marker="#statistics_reductions">statistics(reductions)</seealso>
+ especially on an Erlang machine with SMP support.</p>
+ </item>
+ <tag><c>garbage_collection</c></tag>
+ <item>
+ <p>Returns <c>{Number_of_GCs, Words_Reclaimed, 0}</c>. This
+ information may not be valid for all implementations.</p>
+ </item>
+ <tag><c>io</c></tag>
+ <item>
+ <p>Returns <c>{{input, Input}, {output, Output}}</c>,
+ where <c>Input</c> is the total number of bytes received
+ through ports, and <c>Output</c> is the total number of
+ bytes output to ports.</p>
+ </item>
+ <tag><c>reductions</c></tag>
+ <item>
+ <marker id="statistics_reductions"></marker>
+ <p>Returns
+ <c>{Total_Reductions, Reductions_Since_Last_Call}</c>.</p>
+ <p><em>NOTE:</em> From erts version 5.5 (OTP release R11B)
+ this value does not include reductions performed in current
+ time slices of currently scheduled processes. If an
+ exact value is wanted, use
+ <seealso marker="#statistics_exact_reductions">statistics(exact_reductions)</seealso>.</p>
+ </item>
+ <tag><c>run_queue</c></tag>
+ <item>
+ <p>Returns the length of the run queue, that is, the number
+ of processes that are ready to run.</p>
+ </item>
+ <tag><c>runtime</c></tag>
+ <item>
+ <p>Returns <c>{Total_Run_Time, Time_Since_Last_Call}</c>.
+ Note that the run-time is the sum of the run-time for all
+ threads in the Erlang run-time system and may therefore be greater
+ than the wall-clock time.</p>
+ </item>
+ <tag><c>wall_clock</c></tag>
+ <item>
+ <p>Returns
+ <c>{Total_Wallclock_Time, Wallclock_Time_Since_Last_Call}</c>.
+ <c>wall_clock</c> can be used in the same manner as
+ <c>runtime</c>, except that real time is measured as
+ opposed to runtime or CPU time.</p>
+ </item>
+ </taglist>
+ <p>All times are in milliseconds.</p>
+ <pre>
+> <input>statistics(runtime).</input>
+{1690,1620}
+> <input>statistics(reductions).</input>
+{2046,11}
+> <input>statistics(garbage_collection).</input>
+{85,23961,0}</pre>
+ </desc>
+ </func>
+ <func>
+ <name>erlang:suspend_process(Suspendee, OptList) -> true | false</name>
+ <fsummary>Suspend a process</fsummary>
+ <type>
+ <v>Suspendee = pid()</v>
+ <v>OptList = [Opt]</v>
+ <v>Opt = atom()</v>
+ </type>
+ <desc>
+ <p>Increases the suspend count on the process identified by
+ <c>Suspendee</c> and puts it in the suspended state if it isn't
+ already in the suspended state. A suspended process will not be
+ scheduled for execution until the process has been resumed.
+ </p>
+
+ <p>A process can be suspended by multiple processes and can
+ be suspended multiple times by a single process. A suspended
+ process will not leave the suspended state until its suspend
+ count reach zero. The suspend count of <c>Suspendee</c> is
+ decreased when
+ <seealso marker="#erlang:resume_process/1">erlang:resume_process(Suspendee)</seealso>
+ is called by the same process that called
+ <c>erlang:suspend_process(Suspendee)</c>. All increased suspend
+ counts on other processes acquired by a process will automatically be
+ decreased when the process terminates.</p>
+
+ <p>Currently the following options (<c>Opt</c>s) are available:</p>
+ <taglist>
+ <tag><c>asynchronous</c></tag>
+ <item>
+ A suspend request is sent to the process identified by
+ <c>Suspendee</c>. <c>Suspendee</c> will eventually suspend
+ unless it is resumed before it was able to suspend. The caller
+ of <c>erlang:suspend_process/2</c> will return immediately,
+ regardless of whether the <c>Suspendee</c> has suspended yet
+ or not. Note that the point in time when the <c>Suspendee</c>
+ will actually suspend cannot be deduced from other events
+ in the system. The only guarantee given is that the
+ <c>Suspendee</c> will <em>eventually</em> suspend (unless it
+ is resumed). If the <c>asynchronous</c> option has <em>not</em>
+ been passed, the caller of <c>erlang:suspend_process/2</c> will
+ be blocked until the <c>Suspendee</c> has actually suspended.
+ </item>
+ <tag><c>unless_suspending</c></tag>
+ <item>
+ The process identified by <c>Suspendee</c> will be suspended
+ unless the calling process already is suspending the
+ <c>Suspendee</c>. If <c>unless_suspending</c> is combined
+ with the <c>asynchronous</c> option, a suspend request will be
+ sent unless the calling process already is suspending the
+ <c>Suspendee</c> or if a suspend request already has been sent
+ and is in transit. If the calling process already is suspending
+ the <c>Suspendee</c>, or if combined with the <c>asynchronous</c>
+ option and a send request already is in transit,
+ <c>false</c> is returned and the suspend count on <c>Suspendee</c>
+ will remain unchanged.
+ </item>
+ </taglist>
+
+ <p>If the suspend count on the process identified by
+ <c>Suspendee</c> was increased, <c>true</c> is returned; otherwise,
+ <c>false</c> is returned.</p>
+
+ <warning>
+ <p>This BIF is intended for debugging only.</p>
+ </warning>
+ <p>Failures:</p>
+ <taglist>
+ <tag><c>badarg</c></tag>
+ <item>
+ If <c>Suspendee</c> isn't a process identifier.
+ </item>
+ <tag><c>badarg</c></tag>
+ <item>
+ If the process identified by <c>Suspendee</c> is same the process as
+ the process calling <c>erlang:suspend_process/2</c>.
+ </item>
+ <tag><c>badarg</c></tag>
+ <item>
+ If the process identified by <c>Suspendee</c> is not alive.
+ </item>
+ <tag><c>badarg</c></tag>
+ <item>
+ If the process identified by <c>Suspendee</c> resides on another node.
+ </item>
+ <tag><c>badarg</c></tag>
+ <item>
+ If <c>OptList</c> isn't a proper list of valid <c>Opt</c>s.
+ </item>
+ <tag><c>system_limit</c></tag>
+ <item>
+ If the process identified by <c>Suspendee</c> has been suspended more
+ times by the calling process than can be represented by the
+ currently used internal data structures. The current system limit
+ is larger than 2 000 000 000 suspends, and it will never be less
+ than that.
+ </item>
+ </taglist>
+ </desc>
+ </func>
+ <func>
+ <name>erlang:suspend_process(Suspendee) -> true</name>
+ <fsummary>Suspend a process</fsummary>
+ <type>
+ <v>Suspendee = pid()</v>
+ </type>
+ <desc>
+ <p>Suspends the process identified by <c>Suspendee</c>. The
+ same as calling
+ <seealso marker="#erlang:suspend_process/2">erlang:suspend_process(Suspendee, [])</seealso>. For more information see the documentation of <seealso marker="#erlang:suspend_process/2">erlang:suspend_process/2</seealso>.
+ </p>
+ <warning>
+ <p>This BIF is intended for debugging only.</p>
+ </warning>
+ </desc>
+ </func>
+ <func>
+ <name>erlang:system_flag(Flag, Value) -> OldValue</name>
+ <fsummary>Set system flags</fsummary>
+ <type>
+ <v>Flag, Value, OldValue -- see below</v>
+ </type>
+ <desc>
+ <p>Sets various system properties of the Erlang node. Returns
+ the old value of the flag.</p>
+ <taglist>
+ <tag><c>erlang:system_flag(backtrace_depth, Depth)</c></tag>
+ <item>
+ <p>Sets the maximum depth of call stack back-traces in the
+ exit reason element of <c>'EXIT'</c> tuples.</p>
+ </item>
+ <tag><c>erlang:system_flag(cpu_topology, CpuTopology)</c></tag>
+ <item>
+ <marker id="system_flag_cpu_topology"></marker>
+ <p>Sets the user defined <c>CpuTopology</c>. The user defined
+ CPU topology will override any automatically detected
+ CPU topology. By passing <c>undefined</c> as <c>CpuTopology</c>
+ the system will revert back to the CPU topology automatically
+ detected. The returned value equals the value returned
+ from <c>erlang:system_info(cpu_topology)</c> before the
+ change was made.
+ </p>
+ <p>The CPU topology is used when binding schedulers to logical
+ processors. If schedulers are already bound when the CPU
+ topology is changed, the schedulers will be sent a request
+ to rebind according to the new CPU topology.
+ </p>
+ <p>The user defined CPU topology can also be set by passing
+ the <seealso marker="erl#+sct">+sct</seealso> command
+ line argument to <c>erl</c>.
+ </p>
+ <p>For information on the <c>CpuTopology</c> type
+ and more, see the documentation of
+ <seealso marker="#system_info_cpu_topology">erlang:system_info(cpu_topology)</seealso>,
+ the <c>erl</c> <seealso marker="erl#+sct">+sct</seealso>
+ emulator flag, and
+ <seealso marker="#system_flag_scheduler_bind_type">erlang:system_flag(scheduler_bind_type, How)</seealso>.
+ </p>
+ </item>
+ <tag><c>erlang:system_flag(fullsweep_after, Number)</c></tag>
+ <item>
+ <p><c>Number</c> is a non-negative integer which indicates
+ how many times generational garbage collections can be
+ done without forcing a fullsweep collection. The value
+ applies to new processes; processes already running are
+ not affected.</p>
+ <p>In low-memory systems (especially without virtual
+ memory), setting the value to 0 can help to conserve
+ memory.</p>
+ <p>An alternative way to set this value is through the
+ (operating system) environment variable
+ <c>ERL_FULLSWEEP_AFTER</c>.</p>
+ </item>
+ <tag><c>erlang:system_flag(min_heap_size, MinHeapSize)</c></tag>
+ <item>
+ <p>Sets the default minimum heap size for processes. The
+ size is given in words. The new <c>min_heap_size</c> only
+ effects processes spawned after the change of
+ <c>min_heap_size</c> has been made.
+ The <c>min_heap_size</c> can be set for individual
+ processes by use of
+ <seealso marker="#spawn_opt/4">spawn_opt/N</seealso> or
+ <seealso marker="#process_flag/2">process_flag/2</seealso>. </p>
+ </item>
+ <tag><c>erlang:system_flag(multi_scheduling, BlockState)</c></tag>
+ <item>
+ <marker id="system_flag_multi_scheduling"></marker>
+ <p><c>BlockState = block | unblock</c></p>
+ <p>If multi-scheduling is enabled, more than one scheduler
+ thread is used by the emulator. Multi-scheduling can be
+ blocked. When multi-scheduling has been blocked, only
+ one scheduler thread will schedule Erlang processes.</p>
+ <p>If <c>BlockState =:= block</c>, multi-scheduling will
+ be blocked. If <c>BlockState =:= unblock</c> and no-one
+ else is blocking multi-scheduling and this process has
+ only blocked one time, multi-scheduling will be unblocked.
+ One process can block multi-scheduling multiple times.
+ If a process has blocked multiple times, it has to
+ unblock exactly as many times as it has blocked before it
+ has released its multi-scheduling block. If a process that
+ has blocked multi-scheduling exits, it will release its
+ blocking of multi-scheduling.</p>
+ <p>The return values are <c>disabled</c>, <c>blocked</c>,
+ or <c>enabled</c>. The returned value describes the
+ state just after the call to
+ <c>erlang:system_flag(multi_scheduling, BlockState)</c>
+ has been made. The return values are described in the
+ documentation of <seealso marker="#system_info_multi_scheduling">erlang:system_info(multi_scheduling)</seealso>.</p>
+ <p><em>NOTE</em>: Blocking of multi-scheduling should normally
+ not be needed. If you feel that you need to
+ block multi-scheduling, think through the
+ problem at least a couple of times again.
+ Blocking multi-scheduling should only be used
+ as a last resort since it will most likely be
+ a <em>very inefficient</em> way to solve the
+ problem.</p>
+ <p>See also <seealso marker="#system_info_multi_scheduling">erlang:system_info(multi_scheduling)</seealso>,
+ <seealso marker="#system_info_multi_scheduling_blockers">erlang:system_info(multi_scheduling_blockers)</seealso>, and
+ <seealso marker="#system_info_schedulers">erlang:system_info(schedulers)</seealso>.</p>
+ </item>
+ <tag><c>erlang:system_flag(scheduler_bind_type, How)</c></tag>
+ <item>
+ <marker id="system_flag_scheduler_bind_type"></marker>
+ <p>Controls if and how schedulers are bound to logical
+ processors.</p>
+ <p>When <c>erlang:system_flag(scheduler_bind_type, How)</c> is
+ called, an asynchronous signal is sent to all schedulers
+ online which causes them to try to bind or unbind as requested.
+ <em>NOTE:</em> If a scheduler fails to bind, this
+ will often be silently ignored. This since it isn't always
+ possible to verify valid logical processor identifiers. If
+ an error is reported, it will be reported to the
+ <c>error_logger</c>. If you want to verify that the
+ schedulers actually have bound as requested, call
+ <seealso marker="#system_info_scheduler_bindings">erlang:system_info(scheduler_bindings)</seealso>.
+ </p>
+ <p>Schedulers can currently only be bound on newer Linux
+ and Solaris systems, but more systems will be supported
+ in the future.
+ </p>
+ <p>In order for the runtime system to be able to bind schedulers,
+ the CPU topology needs to be known. If the runtime system fails
+ to automatically detect the CPU topology, it can be defined.
+ For more information on how to define the CPU topology, see
+ <seealso marker="#system_flag_cpu_topology">erlang:system_flag(cpu_topology, CpuTopology)</seealso>.
+ </p>
+ <p><em>NOTE:</em> If other programs on the system have bound
+ to processors, e.g. another Erlang runtime system, you
+ may loose performance when binding schedulers. Therefore,
+ schedulers are by default not bound.</p>
+ <p>Schedulers can be bound in different ways. The <c>How</c>
+ argument determines how schedulers are bound. <c>How</c> can
+ currently be one of:</p>
+ <taglist>
+ <tag><c>unbound</c></tag>
+ <item>
+ <p>Schedulers will not be bound to logical processors, i.e.,
+ the operating system decides where the scheduler threads
+ execute, and when to migrate them. This is the default.</p>
+ </item>
+ <tag><c>no_spread</c></tag>
+ <item>
+ <p>Schedulers with close scheduler identifiers will be bound
+ as close as possible in hardware.</p>
+ </item>
+ <tag><c>thread_spread</c></tag>
+ <item>
+ <p>Thread refers to hardware threads (e.g. Intels
+ hyper-threads). Schedulers with low scheduler identifiers,
+ will be bound to the first hardware thread of each core,
+ then schedulers with higher scheduler identifiers will be
+ bound to the second hardware thread of each core, etc.</p>
+ </item>
+ <tag><c>processor_spread</c></tag>
+ <item>
+ <p>Schedulers will be spread like <c>thread_spread</c>, but
+ also over physical processor chips.</p>
+ </item>
+ <tag><c>spread</c></tag>
+ <item>
+ <p>Schedulers will be spread as much as possible.</p>
+ </item>
+ <tag><c>no_node_thread_spread</c></tag>
+ <item>
+ <p>Like <c>thread_spread</c>, but if multiple NUMA
+ (Non-Uniform Memory Access) nodes exists,
+ schedulers will be spread over one NUMA node at a time,
+ i.e., all logical processors of one NUMA node will
+ be bound to schedulers in sequence.</p>
+ </item>
+ <tag><c>no_node_processor_spread</c></tag>
+ <item>
+ <p>Like <c>processor_spread</c>, but if multiple NUMA
+ nodes exists, schedulers will be spread over one
+ NUMA node at a time, i.e., all logical processors of
+ one NUMA node will be bound to schedulers in sequence.</p>
+ </item>
+ <tag><c>thread_no_node_processor_spread</c></tag>
+ <item>
+ <p>A combination of <c>thread_spread</c>, and
+ <c>no_node_processor_spread</c>. Schedulers will be
+ spread over hardware threads across NUMA nodes, but
+ schedulers will only be spread over processors internally
+ in one NUMA node at a time.</p>
+ </item>
+ <tag><c>default_bind</c></tag>
+ <item>
+ <p>Binds schedulers the default way. Currently the default
+ is <c>thread_no_node_processor_spread</c> (which might change
+ in the future).</p>
+ </item>
+ </taglist>
+ <p>How schedulers are bound matters. For example, in
+ situations when there are fewer running processes than
+ schedulers online, the runtime system tries to migrate
+ processes to schedulers with low scheduler identifiers.
+ The more the schedulers are spread over the hardware,
+ the more resources will be available to the runtime
+ system in such situations.
+ </p>
+ <p>The value returned equals <c>How</c> before the
+ <c>scheduler_bind_type</c> flag was changed.</p>
+ <p>Failure:</p>
+ <taglist>
+ <tag><c>notsup</c></tag>
+ <item>
+ <p>If binding of schedulers is not supported.</p>
+ </item>
+ <tag><c>badarg</c></tag>
+ <item>
+ <p>If <c>How</c> isn't one of the documented alternatives.</p>
+ </item>
+ <tag><c>badarg</c></tag>
+ <item>
+ <p>If no CPU topology information is available.</p>
+ </item>
+ </taglist>
+ <p>The scheduler bind type can also be set by passing
+ the <seealso marker="erl#+sbt">+sbt</seealso> command
+ line argument to <c>erl</c>.
+ </p>
+ <p>For more information, see
+ <seealso marker="#system_info_scheduler_bind_type">erlang:system_info(scheduler_bind_type)</seealso>,
+ <seealso marker="#system_info_scheduler_bindings">erlang:system_info(scheduler_bindings)</seealso>,
+ the <c>erl</c> <seealso marker="erl#+sbt">+sbt</seealso>
+ emulator flag, and
+ <seealso marker="#system_flag_cpu_topology">erlang:system_flag(cpu_topology, CpuTopology)</seealso>.
+ </p>
+ </item>
+ <tag><c>erlang:system_flag(schedulers_online, SchedulersOnline)</c></tag>
+ <item>
+ <marker id="system_flag_schedulers_online"></marker>
+ <p>Sets the amount of schedulers online. Valid range is
+ <![CDATA[1 <= SchedulerId <= erlang:system_info(schedulers)]]>.
+ </p>
+ <p>For more information see,
+ <seealso marker="#system_info_schedulers">erlang:system_info(schedulers)</seealso>,
+ and
+ <seealso marker="#system_info_schedulers_online">erlang:system_info(schedulers_online)</seealso>.
+ </p>
+ </item>
+ <tag><c>erlang:system_flag(trace_control_word, TCW)</c></tag>
+ <item>
+ <p>Sets the value of the node's trace control word to
+ <c>TCW</c>. <c>TCW</c> should be an unsigned integer. For
+ more information see documentation of the
+ <seealso marker="erts:match_spec#set_tcw">set_tcw</seealso>
+ function in the match specification documentation in the
+ ERTS User's Guide.</p>
+ </item>
+ </taglist>
+ <note>
+ <p>The <c>schedulers</c> option has been removed as
+ of erts version 5.5.3. The number of scheduler
+ threads is determined at emulator boot time, and
+ cannot be changed after that.</p>
+ </note>
+ </desc>
+ </func>
+ <func>
+ <name>erlang:system_info(Type) -> Res</name>
+ <fsummary>Information about the system</fsummary>
+ <type>
+ <v>Type, Res -- see below</v>
+ </type>
+ <desc>
+ <p>Returns various information about the current system
+ (emulator) as specified by <c>Type</c>:</p>
+ <taglist>
+ <tag><c>allocated_areas</c></tag>
+ <item>
+ <marker id="system_info_allocated_areas"></marker>
+ <p>Returns a list of tuples with information about
+ miscellaneous allocated memory areas.</p>
+ <p>Each tuple contains an atom describing type of memory as
+ first element and amount of allocated memory in bytes as
+ second element. In those cases when there is information
+ present about allocated and used memory, a third element
+ is present. This third element contains the amount of
+ used memory in bytes.</p>
+ <p><c>erlang:system_info(allocated_areas)</c> is intended
+ for debugging, and the content is highly implementation
+ dependent. The content of the results will therefore
+ change when needed without prior notice.</p>
+ <p><em>Note:</em> The sum of these values is <em>not</em>
+ the total amount of memory allocated by the emulator.
+ Some values are part of other values, and some memory
+ areas are not part of the result. If you are interested
+ in the total amount of memory allocated by the emulator
+ see <seealso marker="#erlang:memory/0">erlang:memory/0,1</seealso>.</p>
+ </item>
+ <tag><c>allocator</c></tag>
+ <item>
+ <marker id="system_info_allocator"></marker>
+ <p>Returns <c>{Allocator, Version, Features, Settings}.</c></p>
+ <p>Types:</p>
+ <list type="bulleted">
+ <item><c>Allocator = undefined | elib_malloc | glibc</c></item>
+ <item><c>Version = [int()]</c></item>
+ <item><c>Features = [atom()]</c></item>
+ <item><c>Settings = [{Subsystem, [{Parameter, Value}]}]</c></item>
+ <item><c>Subsystem = atom()</c></item>
+ <item><c>Parameter = atom()</c></item>
+ <item><c>Value = term()</c></item>
+ </list>
+ <p>Explanation:</p>
+ <list type="bulleted">
+ <item>
+ <p><c>Allocator</c> corresponds to the <c>malloc()</c>
+ implementation used. If <c>Allocator</c> equals
+ <c>undefined</c>, the <c>malloc()</c> implementation
+ used could not be identified. Currently
+ <c>elib_malloc</c> and <c>glibc</c> can be identified.</p>
+ </item>
+ <item>
+ <p><c>Version</c> is a list of integers (but not a
+ string) representing the version of
+ the <c>malloc()</c> implementation used.</p>
+ </item>
+ <item>
+ <p><c>Features</c> is a list of atoms representing
+ allocation features used.</p>
+ </item>
+ <item>
+ <p><c>Settings</c> is a list of subsystems, their
+ configurable parameters, and used values. Settings
+ may differ between different combinations of
+ platforms, allocators, and allocation features.
+ Memory sizes are given in bytes.</p>
+ </item>
+ </list>
+ <p>See also "System Flags Effecting erts_alloc" in
+ <seealso marker="erts:erts_alloc#flags">erts_alloc(3)</seealso>.</p>
+ </item>
+ <tag><c>alloc_util_allocators</c></tag>
+ <item>
+ <marker id="system_info_alloc_util_allocators"></marker>
+ <p>Returns a list of the names of all allocators
+ using the ERTS internal <c>alloc_util</c> framework
+ as atoms. For more information see the
+ <seealso marker="erts:erts_alloc#alloc_util">"the
+ alloc_util framework" section in the
+ erts_alloc(3)</seealso> documentation.
+ </p>
+ </item>
+ <tag><c>{allocator, Alloc}</c></tag>
+ <item>
+ <marker id="system_info_allocator_tuple"></marker>
+ <p>Returns information about the specified allocator.
+ As of erts version 5.6.1 the return value is a list
+ of <c>{instance, InstanceNo, InstanceInfo}</c> tuples
+ where <c>InstanceInfo</c> contains information about
+ a specific instance of the allocator.
+ If <c>Alloc</c> is not a recognized allocator,
+ <c>undefined</c> is returned. If <c>Alloc</c> is disabled,
+ <c>false</c> is returned.</p>
+ <p><em>Note:</em> The information returned is highly
+ implementation dependent and may be changed, or removed
+ at any time without prior notice. It was initially
+ intended as a tool when developing new allocators, but
+ since it might be of interest for others it has been
+ briefly documented.</p>
+ <p>The recognized allocators are listed in
+ <seealso marker="erts:erts_alloc">erts_alloc(3)</seealso>.
+ After reading the <c>erts_alloc(3)</c> documentation,
+ the returned information
+ should more or less speak for itself. But it can be worth
+ explaining some things. Call counts are presented by two
+ values. The first value is giga calls, and the second
+ value is calls. <c>mbcs</c>, and <c>sbcs</c> are
+ abbreviations for, respectively, multi-block carriers, and
+ single-block carriers. Sizes are presented in bytes. When
+ it is not a size that is presented, it is the amount of
+ something. Sizes and amounts are often presented by three
+ values, the first is current value, the second is maximum
+ value since the last call to
+ <c>erlang:system_info({allocator, Alloc})</c>, and
+ the third is maximum value since the emulator was started.
+ If only one value is present, it is the current value.
+ <c>fix_alloc</c> memory block types are presented by two
+ values. The first value is memory pool size and
+ the second value used memory size.</p>
+ </item>
+ <tag><c>{allocator_sizes, Alloc}</c></tag>
+ <item>
+ <marker id="system_info_allocator_sizes"></marker>
+ <p>Returns various size information for the specified
+ allocator. The information returned is a subset of the
+ information returned by
+ <seealso marker="#system_info_allocator_tuple">erlang:system_info({allocator, Alloc})</seealso>.
+ </p>
+ </item>
+ <tag><c>c_compiler_used</c></tag>
+ <item>
+ <p>Returns a two-tuple describing the C compiler used when
+ compiling the runtime system. The first element is an
+ atom describing the name of the compiler, or <c>undefined</c>
+ if unknown. The second element is a term describing the
+ version of the compiler, or <c>undefined</c> if unknown.
+ </p>
+ </item>
+ <tag><c>check_io</c></tag>
+ <item>
+ <p>Returns a list containing miscellaneous information
+ regarding the emulators internal I/O checking. Note,
+ the content of the returned list may vary between
+ platforms and over time. The only thing guaranteed is
+ that a list is returned.</p>
+ </item>
+ <tag><c>compat_rel</c></tag>
+ <item>
+ <p>Returns the compatibility mode of the local node as
+ an integer. The integer returned represents the
+ Erlang/OTP release which the current emulator has been
+ set to be backward compatible with. The compatibility
+ mode can be configured at startup by using the command
+ line flag <c>+R</c>, see
+ <seealso marker="erts:erl#compat_rel">erl(1)</seealso>.</p>
+ </item>
+ <tag><c>cpu_topology</c></tag>
+ <item>
+ <marker id="system_info_cpu_topology"></marker>
+ <p>Returns the <c>CpuTopology</c> which currently is used by the
+ emulator. The CPU topology is used when binding schedulers
+ to logical processors. The CPU topology used is the user defined
+ CPU topology if such exist; otherwise, the automatically
+ detected CPU topology if such exist. If no CPU topology
+ exist <c>undefined</c> is returned.</p>
+ <p>Types:</p>
+ <list type="bulleted">
+ <item><c>CpuTopology = LevelEntryList | undefined</c></item>
+ <item><c>LevelEntryList = [LevelEntry]</c> (all
+ <c>LevelEntry</c>s of a <c>LevelEntryList</c>
+ must contain the same <c>LevelTag</c>, except
+ on the top level where both <c>node</c> and
+ <c>processor</c> <c>LevelTag</c>s may co-exist)</item>
+ <item><c>LevelEntry = {LevelTag, SubLevel}
+ | {LevelTag, InfoList, SubLevel}</c>
+ (<c>{LevelTag, SubLevel}
+ == {LevelTag, [], SubLevel}</c>)</item>
+ <item><c>LevelTag = node|processor|core|thread</c>
+ (more <c>LevelTag</c>s may be introduced in
+ the future)</item>
+ <item><c>SubLevel = [LevelEntry] | LogicalCpuId</c></item>
+ <item><c>LogicalCpuId = {logical, integer()}</c></item>
+ <item><c>InfoList = []</c> (the <c>InfoList</c>
+ may be extended in the future)</item>
+ </list>
+ <p><c>node</c> refers to NUMA (non-uniform memory access)
+ nodes, and <c>thread</c> refers to hardware threads
+ (e.g. Intels hyper-threads).</p>
+ <p>A level in the <c>CpuTopology</c> term can be omitted if
+ only one entry exists and the <c>InfoList</c> is empty.
+ </p>
+ <p><c>thread</c> can only be a sub level to <c>core</c>.
+ <c>core</c> can be a sub level to either <c>processor</c>
+ or <c>node</c>. <c>processor</c> can either be on the
+ top level or a sub level to <c>node</c>. <c>node</c>
+ can either be on the top level or a sub level to
+ <c>processor</c>. That is, NUMA nodes can be processor
+ internal or processor external. A CPU topology can
+ consist of a mix of processor internal and external
+ NUMA nodes, as long as each logical CPU belongs to one
+ and only one NUMA node. Cache hierarchy is not part of
+ the <c>CpuTopology</c> type yet, but will be in the
+ future. Other things may also make it into the CPU
+ topology in the future. In other words, expect the
+ <c>CpuTopology</c> type to change.
+ </p>
+ </item>
+ <tag><c>{cpu_topology, defined}</c></tag>
+ <item>
+ <p>Returns the user defined <c>CpuTopology</c>. For more
+ information see the documentation of
+ <seealso marker="#system_flag_cpu_topology">erlang:system_flag(cpu_topology, CpuTopology)</seealso>
+ and the documentation of the
+ <seealso marker="#system_info_cpu_topology">cpu_topology</seealso>
+ argument.
+ </p>
+ </item>
+ <tag><c>{cpu_topology, detected}</c></tag>
+ <item>
+ <p>Returns the automatically detected <c>CpuTopology</c>. The
+ emulator currently only detects the CPU topology on some newer
+ linux and solaris systems. For more information see the
+ documentation of the
+ <seealso marker="#system_info_cpu_topology">cpu_topology</seealso>
+ argument.
+ </p>
+ </item>
+ <tag><c>{cpu_topology, used}</c></tag>
+ <item>
+ <p>Returns the <c>CpuTopology</c> which is used by the
+ emulator. For more information see the
+ documentation of the
+ <seealso marker="#system_info_cpu_topology">cpu_topology</seealso>
+ argument.
+ </p>
+ </item>
+ <tag><c>creation</c></tag>
+ <item>
+ <p>Returns the creation of the local node as an integer.
+ The creation is changed when a node is restarted. The
+ creation of a node is stored in process identifiers, port
+ identifiers, and references. This makes it (to some
+ extent) possible to distinguish between identifiers from
+ different incarnations of a node. Currently valid
+ creations are integers in the range 1..3, but this may
+ (probably will) change in the future. If the node is not
+ alive, 0 is returned.</p>
+ </item>
+ <tag><c>debug_compiled</c></tag>
+ <item>
+ <p>Returns <c>true</c> if the emulator has been debug
+ compiled; otherwise, <c>false</c>.
+ </p>
+ </item>
+ <tag><c>dist</c></tag>
+ <item>
+ <p>Returns a binary containing a string of distribution
+ information formatted as in Erlang crash dumps. For more
+ information see the <seealso marker="erts:crash_dump">"How to interpret the Erlang crash dumps"</seealso>
+ chapter in the ERTS User's Guide.</p>
+ </item>
+ <tag><c>dist_ctrl</c></tag>
+ <item>
+ <p>Returns a list of tuples
+ <c>{Node, ControllingEntity}</c>, one entry for each
+ connected remote node. The <c>Node</c> is the name of the
+ node and the <c>ControllingEntity</c> is the port or pid
+ responsible for the communication to that node. More
+ specifically, the <c>ControllingEntity</c> for nodes
+ connected via TCP/IP (the normal case) is the socket
+ actually used in communication with the specific node.</p>
+ </item>
+ <tag><c>driver_version</c></tag>
+ <item>
+ <p>Returns a string containing the erlang driver version
+ used by the runtime system. It will be on the form
+ <seealso marker="erts:erl_driver#version_management">"&lt;major ver&gt;.&lt;minor ver&gt;"</seealso>.</p>
+ </item>
+ <tag><c>elib_malloc</c></tag>
+ <item>
+ <p>If the emulator uses the <c>elib_malloc</c> memory
+ allocator, a list of two-element tuples containing status
+ information is returned; otherwise, <c>false</c> is
+ returned. The list currently contains the following
+ two-element tuples (all sizes are presented in bytes):</p>
+ <taglist>
+ <tag><c>{heap_size, Size}</c></tag>
+ <item>
+ <p>Where <c>Size</c> is the current heap size.</p>
+ </item>
+ <tag><c>{max_alloced_size, Size}</c></tag>
+ <item>
+ <p>Where <c>Size</c> is the maximum amount of memory
+ allocated on the heap since the emulator started.</p>
+ </item>
+ <tag><c>{alloced_size, Size}</c></tag>
+ <item>
+ <p>Where <c>Size</c> is the current amount of memory
+ allocated on the heap.</p>
+ </item>
+ <tag><c>{free_size, Size}</c></tag>
+ <item>
+ <p>Where <c>Size</c> is the current amount of free
+ memory on the heap.</p>
+ </item>
+ <tag><c>{no_alloced_blocks, No}</c></tag>
+ <item>
+ <p>Where <c>No</c> is the current number of allocated
+ blocks on the heap.</p>
+ </item>
+ <tag><c>{no_free_blocks, No}</c></tag>
+ <item>
+ <p>Where <c>No</c> is the current number of free blocks
+ on the heap.</p>
+ </item>
+ <tag><c>{smallest_alloced_block, Size}</c></tag>
+ <item>
+ <p>Where <c>Size</c> is the size of the smallest
+ allocated block on the heap.</p>
+ </item>
+ <tag><c>{largest_free_block, Size}</c></tag>
+ <item>
+ <p>Where <c>Size</c> is the size of the largest free
+ block on the heap.</p>
+ </item>
+ </taglist>
+ </item>
+ <tag><c>fullsweep_after</c></tag>
+ <item>
+ <p>Returns <c>{fullsweep_after, int()}</c> which is the
+ <c>fullsweep_after</c> garbage collection setting used
+ by default. For more information see
+ <c>garbage_collection</c> described below.</p>
+ </item>
+ <tag><c>garbage_collection</c></tag>
+ <item>
+ <p>Returns a list describing the default garbage collection
+ settings. A process spawned on the local node by a
+ <c>spawn</c> or <c>spawn_link</c> will use these
+ garbage collection settings. The default settings can be
+ changed by use of
+ <seealso marker="#erlang:system_flag/2">system_flag/2</seealso>.
+ <seealso marker="#spawn_opt/4">spawn_opt/4</seealso>
+ can spawn a process that does not use the default
+ settings.</p>
+ </item>
+ <tag><c>global_heaps_size</c></tag>
+ <item>
+ <p>Returns the current size of the shared (global) heap.</p>
+ </item>
+ <tag><c>heap_sizes</c></tag>
+ <item>
+ <p>Returns a list of integers representing valid heap sizes
+ in words. All Erlang heaps are sized from sizes in this
+ list.</p>
+ </item>
+ <tag><c>heap_type</c></tag>
+ <item>
+ <p>Returns the heap type used by the current emulator.
+ Currently the following heap types exist:</p>
+ <taglist>
+ <tag><c>private</c></tag>
+ <item>
+ <p>Each process has a heap reserved for its use and no
+ references between heaps of different processes are
+ allowed. Messages passed between processes are copied
+ between heaps.</p>
+ </item>
+ <tag><c>shared</c></tag>
+ <item>
+ <p>One heap for use by all processes. Messages passed
+ between processes are passed by reference.</p>
+ </item>
+ <tag><c>hybrid</c></tag>
+ <item>
+ <p>A hybrid of the <c>private</c> and <c>shared</c> heap
+ types. A shared heap as well as private heaps are
+ used.</p>
+ </item>
+ </taglist>
+ </item>
+ <tag><c>info</c></tag>
+ <item>
+ <p>Returns a binary containing a string of miscellaneous
+ system information formatted as in Erlang crash dumps.
+ For more information see the
+ <seealso marker="erts:crash_dump">"How to interpret the Erlang crash dumps"</seealso> chapter in the ERTS
+ User's Guide.</p>
+ </item>
+ <tag><c>kernel_poll</c></tag>
+ <item>
+ <p>Returns <c>true</c> if the emulator uses some kind of
+ kernel-poll implementation; otherwise, <c>false</c>.</p>
+ </item>
+ <tag><c>loaded</c></tag>
+ <item>
+ <p>Returns a binary containing a string of loaded module
+ information formatted as in Erlang crash dumps. For more
+ information see the <seealso marker="erts:crash_dump">"How to interpret the Erlang crash dumps"</seealso> chapter
+ in the ERTS User's Guide.</p>
+ </item>
+ <tag><c>logical_processors</c></tag>
+ <item>
+ <p>Returns the number of logical processors detected on the
+ system as an integer or the atom <c>unknown</c> if the
+ emulator wasn't able to detect any.
+ </p>
+ </item>
+ <tag><c>machine</c></tag>
+ <item>
+ <p>Returns a string containing the Erlang machine name.</p>
+ </item>
+ <tag><c>modified_timing_level</c></tag>
+ <item>
+ <p>Returns the modified timing level (an integer) if
+ modified timing has been enabled; otherwise,
+ <c>undefined</c>. See the <c>+T</c> command line flag
+ in the documentation of the
+ <seealso marker="erts:erl#+T">erl(1)</seealso>
+ command for more information on modified timing.</p>
+ </item>
+ <tag><c>multi_scheduling</c></tag>
+ <item>
+ <marker id="system_info_multi_scheduling"></marker>
+ <p>Returns <c>disabled</c>, <c>blocked</c>, or <c>enabled</c>.
+ A description of the return values:</p>
+ <taglist>
+ <tag><c>disabled</c></tag>
+ <item>
+ <p>The emulator has only one scheduler thread. The
+ emulator does not have SMP support, or have been
+ started with only one scheduler thread.</p>
+ </item>
+ <tag><c>blocked</c></tag>
+ <item>
+ <p>The emulator has more than one scheduler thread,
+ but all scheduler threads but one have been blocked,
+ i.e., only one scheduler thread will schedule
+ Erlang processes and execute Erlang code.</p>
+ </item>
+ <tag><c>enabled</c></tag>
+ <item>
+ <p>The emulator has more than one scheduler thread,
+ and no scheduler threads have been blocked, i.e.,
+ all available scheduler threads will schedule
+ Erlang processes and execute Erlang code.</p>
+ </item>
+ </taglist>
+ <p>See also <seealso marker="#system_flag_multi_scheduling">erlang:system_flag(multi_scheduling, BlockState)</seealso>,
+ <seealso marker="#system_info_multi_scheduling_blockers">erlang:system_info(multi_scheduling_blockers)</seealso>, and
+ <seealso marker="#system_info_schedulers">erlang:system_info(schedulers)</seealso>.</p>
+ </item>
+ <tag><c>multi_scheduling_blockers</c></tag>
+ <item>
+ <marker id="system_info_multi_scheduling_blockers"></marker>
+ <p>Returns a list of <c>PID</c>s when multi-scheduling
+ is blocked; otherwise, the empty list. The <c>PID</c>s
+ in the list is <c>PID</c>s of the processes currently
+ blocking multi-scheduling. A <c>PID</c> will only be
+ present once in the list, even if the corresponding
+ process has blocked multiple times.</p>
+ <p>See also <seealso marker="#system_flag_multi_scheduling">erlang:system_flag(multi_scheduling, BlockState)</seealso>,
+ <seealso marker="#system_info_multi_scheduling">erlang:system_info(multi_scheduling)</seealso>, and
+ <seealso marker="#system_info_schedulers">erlang:system_info(schedulers)</seealso>.</p>
+ </item>
+ <tag><c>otp_release</c></tag>
+ <item>
+ <marker id="system_info_otp_release"></marker>
+ <p>Returns a string containing the OTP release number.</p>
+ </item>
+ <tag><c>process_count</c></tag>
+ <item>
+ <p>Returns the number of processes currently existing at
+ the local node as an integer. The same value as
+ <c>length(processes())</c> returns.</p>
+ </item>
+ <tag><c>process_limit</c></tag>
+ <item>
+ <p>Returns the maximum number of concurrently existing
+ processes at the local node as an integer. This limit
+ can be configured at startup by using the command line
+ flag <c>+P</c>, see
+ <seealso marker="erts:erl#max_processes">erl(1)</seealso>.</p>
+ </item>
+ <tag><c>procs</c></tag>
+ <item>
+ <p>Returns a binary containing a string of process and port
+ information formatted as in Erlang crash dumps. For more
+ information see the <seealso marker="erts:crash_dump">"How to interpret the Erlang crash dumps"</seealso> chapter
+ in the ERTS User's Guide.</p>
+ </item>
+ <tag><c>scheduler_bind_type</c></tag>
+ <item>
+ <marker id="system_info_scheduler_bind_type"></marker>
+ <p>Returns information on how user has requested
+ schedulers to be bound or not bound.</p>
+ <p><em>NOTE:</em> Even though user has requested
+ schedulers to be bound via
+ <seealso marker="#system_flag_scheduler_bind_type">erlang:system_flag(scheduler_bind_type, How)</seealso>,
+ they might have silently failed to bind. In order to
+ inspect actual scheduler bindings call
+ <seealso marker="#system_info_scheduler_bindings">erlang:system_info(scheduler_bindings)</seealso>.
+ </p>
+ <p>For more information, see
+ <seealso marker="#system_flag_scheduler_bind_type">erlang:system_flag(scheduler_bind_type, How)</seealso>, and
+ <seealso marker="#system_info_scheduler_bindings">erlang:system_info(scheduler_bindings)</seealso>.
+ </p>
+ </item>
+ <tag><c>scheduler_bindings</c></tag>
+ <item>
+ <marker id="system_info_scheduler_bindings"></marker>
+ <p>Returns information on currently used scheduler
+ bindings.</p>
+ <p>A tuple of a size equal to
+ <seealso marker="#system_info_schedulers">erlang:system_info(schedulers)</seealso> is returned. The elements of the tuple are integers
+ or the atom <c>unbound</c>. Logical processor identifiers
+ are represented as integers. The <c>N</c>th
+ element of the tuple equals the current binding for
+ the scheduler with the scheduler identifier equal to
+ <c>N</c>. E.g., if the schedulers have been bound,
+ <c>element(erlang:system_info(scheduler_id),
+ erlang:system_info(scheduler_bindings))</c> will return
+ the identifier of the logical processor that the calling
+ process is executing on.
+ </p>
+ <p>Note that only schedulers online can be bound to logical
+ processors.</p>
+ <p>For more information, see
+ <seealso marker="#system_flag_scheduler_bind_type">erlang:system_flag(scheduler_bind_type, How)</seealso>,
+ <seealso marker="#system_info_schedulers_online">erlang:system_info(schedulers_online)</seealso>.
+ </p>
+ </item>
+ <tag><c>scheduler_id</c></tag>
+ <item>
+ <marker id="system_info_scheduler_id"></marker>
+ <p>Returns the scheduler id (<c>SchedulerId</c>) of the
+ scheduler thread that the calling process is executing
+ on. <c>SchedulerId</c> is a positive integer; where
+ <c><![CDATA[1 <= SchedulerId <= erlang:system_info(schedulers)]]></c>. See also
+ <seealso marker="#system_info_schedulers">erlang:system_info(schedulers)</seealso>.</p>
+ </item>
+ <tag><c>schedulers</c></tag>
+ <item>
+ <marker id="system_info_schedulers"></marker>
+ <p>Returns the number of scheduler threads used by
+ the emulator. Scheduler threads online schedules Erlang
+ processes and Erlang ports, and execute Erlang code
+ and Erlang linked in driver code.</p>
+ <p>The number of scheduler threads is determined at
+ emulator boot time and cannot be changed after
+ that. The amount of schedulers online can
+ however be changed at any time.</p>
+ <p>See also <seealso marker="#system_flag_schedulers_online">erlang:system_flag(schedulers_online, SchedulersOnline)</seealso>,
+ <seealso marker="#system_info_schedulers_online">erlang:system_info(schedulers_online)</seealso>,
+ <seealso marker="#system_info_scheduler_id">erlang:system_info(scheduler_id)</seealso>,
+ <seealso marker="#system_flag_multi_scheduling">erlang:system_flag(multi_scheduling, BlockState)</seealso>,
+ <seealso marker="#system_info_multi_scheduling">erlang:system_info(multi_scheduling)</seealso>, and
+ and <seealso marker="#system_info_multi_scheduling_blockers">erlang:system_info(multi_scheduling_blockers)</seealso>.</p>
+ </item>
+ <tag><c>schedulers_online</c></tag>
+ <item>
+ <marker id="system_info_schedulers_online"></marker>
+ <p>Returns the amount of schedulers online. The scheduler
+ identifiers of schedulers online satisfy the following
+ relationship:
+ <c><![CDATA[1 <= SchedulerId <= erlang:system_info(schedulers_online)]]></c>.
+ </p>
+ <p>For more information, see
+ <seealso marker="#system_info_schedulers">erlang:system_info(schedulers)</seealso>,
+ and
+ <seealso marker="#system_flag_schedulers_online">erlang:system_flag(schedulers_online, SchedulersOnline)</seealso>.
+ </p>
+ </item>
+ <tag><c>smp_support</c></tag>
+ <item>
+ <p>Returns <c>true</c> if the emulator has been compiled
+ with smp support; otherwise, <c>false</c>.</p>
+ </item>
+ <tag><c>system_version</c></tag>
+ <item>
+ <p>Returns a string containing version number and
+ some important properties such as the number of schedulers.</p>
+ </item>
+ <tag><c>system_architecture</c></tag>
+ <item>
+ <p>Returns a string containing the processor and OS
+ architecture the emulator is built for.</p>
+ </item>
+ <tag><c>threads</c></tag>
+ <item>
+ <p>Returns <c>true</c> if the emulator has been compiled
+ with thread support; otherwise, <c>false</c> is
+ returned.</p>
+ </item>
+ <tag><c>thread_pool_size</c></tag>
+ <item>
+ <marker id="system_info_thread_pool_size"></marker>
+ <p>Returns the number of async threads in the async thread
+ pool used for asynchronous driver calls
+ (<seealso marker="erts:erl_driver#driver_async">driver_async()</seealso>)
+ as an integer.</p>
+ </item>
+ <tag><c>trace_control_word</c></tag>
+ <item>
+ <p>Returns the value of the node's trace control word.
+ For more information see documentation of the function
+ <c>get_tcw</c> in "Match Specifications in Erlang",
+ <seealso marker="erts:match_spec#get_tcw">ERTS User's Guide</seealso>.</p>
+ </item>
+ <tag><c>version</c></tag>
+ <item>
+ <marker id="system_info_version"></marker>
+ <p>Returns a string containing the version number of the
+ emulator.</p>
+ </item>
+ <tag><c>wordsize</c></tag>
+ <item>
+ <p>Returns the word size in bytes as an integer, i.e. on a
+ 32-bit architecture 4 is returned, and on a 64-bit
+ architecture 8 is returned.</p>
+ </item>
+ </taglist>
+ <note>
+ <p>The <c>scheduler</c> argument has changed name to
+ <c>scheduler_id</c>. This in order to avoid mixup with
+ the <c>schedulers</c> argument. The <c>scheduler</c>
+ argument was introduced in ERTS version 5.5 and renamed
+ in ERTS version 5.5.1.</p>
+ </note>
+ </desc>
+ </func>
+
+ <func>
+ <name>erlang:system_monitor() -> MonSettings</name>
+ <fsummary>Current system performance monitoring settings</fsummary>
+ <type>
+ <v>MonSettings -> {MonitorPid, Options} | undefined</v>
+ <v>&nbsp;MonitorPid = pid()</v>
+ <v>&nbsp;Options = [Option]</v>
+ <v>&nbsp;&nbsp;Option = {long_gc, Time} | {large_heap, Size} | busy_port | busy_dist_port</v>
+ <v>&nbsp;&nbsp;&nbsp;Time = Size = int()</v>
+ </type>
+ <desc>
+ <p>Returns the current system monitoring settings set by
+ <seealso marker="#erlang:system_monitor/2">erlang:system_monitor/2</seealso>
+ as <c>{MonitorPid, Options}</c>, or <c>undefined</c> if there
+ are no settings. The order of the options may be different
+ from the one that was set.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>erlang:system_monitor(undefined | {MonitorPid, Options}) -> MonSettings</name>
+ <fsummary>Set or clear system performance monitoring options</fsummary>
+ <type>
+ <v>MonitorPid, Options, MonSettings -- see below</v>
+ </type>
+ <desc>
+ <p>When called with the argument <c>undefined</c>, all
+ system performance monitoring settings are cleared.</p>
+ <p>Calling the function with <c>{MonitorPid, Options}</c> as
+ argument, is the same as calling
+ <seealso marker="#erlang:system_monitor/2">erlang:system_monitor(MonitorPid, Options)</seealso>.</p>
+ <p>Returns the previous system monitor settings just like
+ <seealso marker="#erlang:system_monitor/0">erlang:system_monitor/0</seealso>.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>erlang:system_monitor(MonitorPid, [Option]) -> MonSettings</name>
+ <fsummary>Set system performance monitoring options</fsummary>
+ <type>
+ <v>MonitorPid = pid()</v>
+ <v>Option = {long_gc, Time} | {large_heap, Size} | busy_port | busy_dist_port</v>
+ <v>&nbsp;Time = Size = int()</v>
+ <v>MonSettings = {OldMonitorPid, [Option]}</v>
+ <v>&nbsp;OldMonitorPid = pid()</v>
+ </type>
+ <desc>
+ <p>Sets system performance monitoring options. <c>MonitorPid</c>
+ is a local pid that will receive system monitor messages, and
+ the second argument is a list of monitoring options:</p>
+ <taglist>
+ <tag><c>{long_gc, Time}</c></tag>
+ <item>
+ <p>If a garbage collection in the system takes at least
+ <c>Time</c> wallclock milliseconds, a message
+ <c>{monitor, GcPid, long_gc, Info}</c> is sent to
+ <c>MonitorPid</c>. <c>GcPid</c> is the pid that was
+ garbage collected and <c>Info</c> is a list of two-element
+ tuples describing the result of the garbage collection.
+ One of the tuples is <c>{timeout, GcTime}</c> where
+ <c>GcTime</c> is the actual time for the garbage
+ collection in milliseconds. The other tuples are
+ tagged with <c>heap_size</c>, <c>heap_block_size</c>,
+ <c>stack_size</c>, <c>mbuf_size</c>, <c>old_heap_size</c>,
+ and <c>old_heap_block_size</c>. These tuples are
+ explained in the documentation of the
+ <seealso marker="#gc_start">gc_start</seealso>
+ trace message (see
+ <seealso marker="#erlang:trace/3">erlang:trace/3</seealso>).
+ New tuples may be added, and the order of the tuples in
+ the <c>Info</c> list may be changed at any time without prior
+ notice.
+ </p>
+ </item>
+ <tag><c>{large_heap, Size}</c></tag>
+ <item>
+ <p>If a garbage collection in the system results in
+ the allocated size of a heap being at least <c>Size</c>
+ words, a message <c>{monitor, GcPid, large_heap, Info}</c>
+ is sent to <c>MonitorPid</c>. <c>GcPid</c> and <c>Info</c>
+ are the same as for <c>long_gc</c> above, except that
+ the tuple tagged with <c>timeout</c> is not present.
+ <em>Note</em>: As of erts version 5.6 the monitor message
+ is sent if the sum of the sizes of all memory blocks allocated
+ for all heap generations is equal to or larger than <c>Size</c>.
+ Previously the monitor message was sent if the memory block
+ allocated for the youngest generation was equal to or larger
+ than <c>Size</c>.
+ </p>
+ </item>
+ <tag><c>busy_port</c></tag>
+ <item>
+ <p>If a process in the system gets suspended because it
+ sends to a busy port, a message
+ <c>{monitor, SusPid, busy_port, Port}</c> is sent to
+ <c>MonitorPid</c>. <c>SusPid</c> is the pid that got
+ suspended when sending to <c>Port</c>.</p>
+ </item>
+ <tag><c>busy_dist_port</c></tag>
+ <item>
+ <p>If a process in the system gets suspended because it
+ sends to a process on a remote node whose inter-node
+ communication was handled by a busy port, a message
+ <c>{monitor, SusPid, busy_dist_port, Port}</c> is sent to
+ <c>MonitorPid</c>. <c>SusPid</c> is the pid that got
+ suspended when sending through the inter-node
+ communication port <c>Port</c>.</p>
+ </item>
+ </taglist>
+ <p>Returns the previous system monitor settings just like
+ <seealso marker="#erlang:system_monitor/0">erlang:system_monitor/0</seealso>.</p>
+ <note>
+ <p>If a monitoring process gets so large that it itself
+ starts to cause system monitor messages when garbage
+ collecting, the messages will enlarge the process's
+ message queue and probably make the problem worse.</p>
+ <p>Keep the monitoring process neat and do not set the system
+ monitor limits too tight.</p>
+ </note>
+ <p>Failure: <c>badarg</c> if <c>MonitorPid</c> does not exist.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>erlang:system_profile() -> ProfilerSettings</name>
+ <fsummary>Current system profiling settings</fsummary>
+ <type>
+ <v>ProfilerSettings -> {ProfilerPid, Options} | undefined</v>
+ <v>&nbsp;ProfilerPid = pid() | port()</v>
+ <v>&nbsp;Options = [Option]</v>
+ <v>&nbsp;&nbsp;Option = runnable_procs | runnable_ports | scheduler | exclusive</v>
+ </type>
+ <desc>
+ <p>Returns the current system profiling settings set by
+ <seealso marker="#erlang:system_profile/2">erlang:system_profile/2</seealso>
+ as <c>{ProfilerPid, Options}</c>, or <c>undefined</c> if there
+ are no settings. The order of the options may be different
+ from the one that was set.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>erlang:system_profile(ProfilerPid, Options) -> ProfilerSettings</name>
+ <fsummary>Current system profiling settings</fsummary>
+ <type>
+ <v>ProfilerSettings -> {ProfilerPid, Options} | undefined</v>
+ <v>&nbsp;ProfilerPid = pid() | port()</v>
+ <v>&nbsp;Options = [Option]</v>
+ <v>&nbsp;&nbsp;Option = runnable_procs | runnable_ports | scheduler | exclusive</v>
+ </type>
+ <desc>
+ <p>Sets system profiler options. <c>ProfilerPid</c>
+ is a local pid or port that will receive profiling messages. The
+ receiver is excluded from all profiling.
+ The second argument is a list of profiling options:</p>
+ <taglist>
+ <tag><c>runnable_procs</c></tag>
+ <item>
+ <p>If a process is put into or removed from the run queue a message,
+ <c>{profile, Pid, State, Mfa, Ts}</c>, is sent to
+ <c>ProfilerPid</c>. Running processes that is reinserted into the
+ run queue after having been preemptively scheduled out will not trigger this
+ message.
+ </p>
+ </item>
+ <tag><c>runnable_ports</c></tag>
+ <item>
+ <p>If a port is put into or removed from the run queue a message,
+ <c>{profile, Port, State, 0, Ts}</c>, is sent to
+ <c>ProfilerPid</c>.
+ </p>
+ </item>
+ <tag><c>scheduler</c></tag>
+ <item>
+ <p>If a scheduler is put to sleep or awoken a message,
+ <c>{profile, scheduler, Id, State, NoScheds, Ts}</c>, is sent
+ to <c>ProfilerPid</c>.
+ </p>
+ </item>
+ <tag><c>exclusive</c></tag>
+ <item>
+ <p>
+ If a synchronous call to a port from a process is done, the
+ calling process is considered not runnable during the call
+ runtime to the port. The calling process is notified as
+ <c>inactive</c> and subsequently <c>active</c> when the port
+ callback returns.
+ </p>
+ </item>
+ </taglist>
+ <note><p><c>erlang:system_profile</c> is considered experimental and
+ its behaviour may change in the future.</p>
+ </note>
+ </desc>
+ </func>
+
+ <func>
+ <name>term_to_binary(Term) -> ext_binary()</name>
+ <fsummary>Encode a term to an Erlang external term format binary</fsummary>
+ <type>
+ <v>Term = term()</v>
+ </type>
+ <desc>
+ <p>Returns a binary data object which is the result of encoding
+ <c>Term</c> according to the Erlang external term format.</p>
+ <p>This can be used for a variety of purposes, for example
+ writing a term to a file in an efficient way, or sending an
+ Erlang term to some type of communications channel not
+ supported by distributed Erlang.</p>
+ <p>See also
+ <seealso marker="#binary_to_term/1">binary_to_term/1</seealso>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>term_to_binary(Term, [Option]) -> ext_binary()</name>
+ <fsummary>Encode a term to en Erlang external term format binary</fsummary>
+ <type>
+ <v>Term = term()</v>
+ <v>Option = compressed | {compressed,Level} | {minor_version,Version}</v>
+ </type>
+ <desc>
+ <p>Returns a binary data object which is the result of encoding
+ <c>Term</c> according to the Erlang external term format.</p>
+ <p>If the option <c>compressed</c> is provided, the external
+ term format will be compressed. The compressed format is
+ automatically recognized by <c>binary_to_term/1</c> in R7B and later.</p>
+ <p>It is also possible to specify a compression level by giving
+ the option <c>{compressed,Level}</c>, where <c>Level</c> is an
+ integer from 0 through 9. <c>0</c> means that no compression
+ will be done (it is the same as not giving any <c>compressed</c> option);
+ <c>1</c> will take the least time but may not compress as well as
+ the higher levels; <c>9</c> will take the most time and may produce
+ a smaller result. Note the "mays" in the preceding sentence; depending
+ on the input term, level 9 compression may or may not produce a smaller
+ result than level 1 compression.</p>
+ <p>Currently, <c>compressed</c> gives the same result as
+ <c>{compressed,6}</c>.</p>
+ <p>The option <c>{minor_version,Version}</c> can be use to control
+ some details of the encoding. This option was
+ introduced in R11B-4. Currently, the allowed values for <c>Version</c>
+ are <c>0</c> and <c>1</c>.</p>
+ <p><c>{minor_version,1}</c> forces any floats in the term to be encoded
+ in a more space-efficient and exact way (namely in the 64-bit IEEE format,
+ rather than converted to a textual representation). <c>binary_to_term/1</c>
+ in R11B-4 and later is able decode the new representation.</p>
+ <p><c>{minor_version,0}</c> is currently the default, meaning that floats
+ will be encoded using a textual representation; this option is useful if
+ you want to ensure that releases prior to R11B-4 can decode resulting
+ binary.</p>
+ <p>See also
+ <seealso marker="#binary_to_term/1">binary_to_term/1</seealso>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>throw(Any)</name>
+ <fsummary>Throw an exception</fsummary>
+ <type>
+ <v>Any = term()</v>
+ </type>
+ <desc>
+ <p>A non-local return from a function. If evaluated within a
+ <c>catch</c>, <c>catch</c> will return the value <c>Any</c>.</p>
+ <pre>
+> <input>catch throw({hello, there}).</input>
+{hello,there}</pre>
+ <p>Failure: <c>nocatch</c> if not evaluated within a catch.</p>
+ </desc>
+ </func>
+ <func>
+ <name>time() -> {Hour, Minute, Second}</name>
+ <fsummary>Current time</fsummary>
+ <type>
+ <v>Hour = Minute = Second = int()</v>
+ </type>
+ <desc>
+ <p>Returns the current time as <c>{Hour, Minute, Second}</c>.</p>
+ <p>The time zone and daylight saving time correction depend on
+ the underlying OS.</p>
+ <pre>
+> <input>time().</input>
+{9,42,44}</pre>
+ </desc>
+ </func>
+ <func>
+ <name>tl(List1) -> List2</name>
+ <fsummary>Tail of a list</fsummary>
+ <type>
+ <v>List1 = List2 = [term()]</v>
+ </type>
+ <desc>
+ <p>Returns the tail of <c>List1</c>, that is, the list minus
+ the first element.</p>
+ <pre>
+> <input>tl([geesties, guilies, beasties]).</input>
+[guilies, beasties]</pre>
+ <p>Allowed in guard tests.</p>
+ <p>Failure: <c>badarg</c> if <c>List</c> is the empty list [].</p>
+ </desc>
+ </func>
+ <func>
+ <name>erlang:trace(PidSpec, How, FlagList) -> int()</name>
+ <fsummary>Set trace flags for a process or processes</fsummary>
+ <type>
+ <v>PidSpec = pid() | existing | new | all</v>
+ <v>How = bool()</v>
+ <v>FlagList = [Flag]</v>
+ <v>&nbsp;Flag -- see below</v>
+ </type>
+ <desc>
+ <p>Turns on (if <c>How == true</c>) or off (if
+ <c>How == false</c>) the trace flags in <c>FlagList</c> for
+ the process or processes represented by <c>PidSpec</c>.</p>
+ <p><c>PidSpec</c> is either a pid for a local process, or one of
+ the following atoms:</p>
+ <taglist>
+ <tag><c>existing</c></tag>
+ <item>
+ <p>All processes currently existing.</p>
+ </item>
+ <tag><c>new</c></tag>
+ <item>
+ <p>All processes that will be created in the future.</p>
+ </item>
+ <tag><c>all</c></tag>
+ <item>
+ <p>All currently existing processes and all processes that
+ will be created in the future.</p>
+ </item>
+ </taglist>
+ <p><c>FlagList</c> can contain any number of the following
+ flags (the "message tags" refers to the list of messages
+ following below):</p>
+ <taglist>
+ <tag><c>all</c></tag>
+ <item>
+ <p>Set all trace flags except <c>{tracer, Tracer}</c> and
+ <c>cpu_timestamp</c> that are in their nature different
+ than the others.</p>
+ </item>
+ <tag><c>send</c></tag>
+ <item>
+ <p>Trace sending of messages.</p>
+ <p>Message tags: <c>send</c>,
+ <c>send_to_non_existing_process</c>.</p>
+ </item>
+ <tag><c>'receive'</c></tag>
+ <item>
+ <p>Trace receiving of messages.</p>
+ <p>Message tags: <c>'receive'</c>.</p>
+ </item>
+ <tag><c>procs</c></tag>
+ <item>
+ <p>Trace process related events.</p>
+ <p>Message tags: <c>spawn</c>, <c>exit</c>,
+ <c>register</c>, <c>unregister</c>, <c>link</c>,
+ <c>unlink</c>, <c>getting_linked</c>,
+ <c>getting_unlinked</c>.</p>
+ </item>
+ <tag><c>call</c></tag>
+ <item>
+ <p>Trace certain function calls. Specify which function
+ calls to trace by calling
+ <seealso marker="#erlang:trace_pattern/3">erlang:trace_pattern/3</seealso>.</p>
+ <p>Message tags: <c>call</c>, <c>return_from</c>.</p>
+ </item>
+ <tag><c>silent</c></tag>
+ <item>
+ <p>Used in conjunction with the <c>call</c> trace flag.
+ The <c>call</c>, <c>return_from</c> and <c>return_to</c>
+ trace messages are inhibited if this flag is set,
+ but if there are match specs they are executed as normal.</p>
+ <p>Silent mode is inhibited by executing
+ <c>erlang:trace(_, false, [silent|_])</c>,
+ or by a match spec executing the <c>{silent, false}</c>
+ function.</p>
+ <p>The <c>silent</c> trace flag facilitates setting up
+ a trace on many or even all processes in the system.
+ Then the interesting trace can be activated and
+ deactivated using the <c>{silent,Bool}</c>
+ match spec function, giving a high degree
+ of control of which functions with which
+ arguments that triggers the trace.</p>
+ <p>Message tags: <c>call</c>, <c>return_from</c>,
+ <c>return_to</c>. Or rather, the absence of.</p>
+ </item>
+ <tag><c>return_to</c></tag>
+ <item>
+ <p>Used in conjunction with the <c>call</c> trace flag.
+ Trace the actual return from a traced function back to
+ its caller. Only works for functions traced with
+ the <c>local</c> option to
+ <seealso marker="#erlang:trace_pattern/3">erlang:trace_pattern/3</seealso>.</p>
+ <p>The semantics is that a trace message is sent when a
+ call traced function actually returns, that is, when a
+ chain of tail recursive calls is ended. There will be
+ only one trace message sent per chain of tail recursive
+ calls, why the properties of tail recursiveness for
+ function calls are kept while tracing with this flag.
+ Using <c>call</c> and <c>return_to</c> trace together
+ makes it possible to know exactly in which function a
+ process executes at any time.</p>
+ <p>To get trace messages containing return values from
+ functions, use the <c>{return_trace}</c> match_spec
+ action instead.</p>
+ <p>Message tags: <c>return_to</c>.</p>
+ </item>
+ <tag><c>running</c></tag>
+ <item>
+ <p>Trace scheduling of processes.</p>
+ <p>Message tags: <c>in</c>, and <c>out</c>.</p>
+ </item>
+ <tag><c>exiting</c></tag>
+ <item>
+ <p>Trace scheduling of an exiting processes.</p>
+ <p>Message tags: <c>in_exiting</c>, <c>out_exiting</c>, and
+ <c>out_exited</c>.</p>
+ </item>
+ <tag><c>garbage_collection</c></tag>
+ <item>
+ <p>Trace garbage collections of processes.</p>
+ <p>Message tags: <c>gc_start</c>, <c>gc_end</c>.</p>
+ </item>
+ <tag><c>timestamp</c></tag>
+ <item>
+ <p>Include a time stamp in all trace messages. The time
+ stamp (Ts) is of the same form as returned by
+ <c>erlang:now()</c>.</p>
+ </item>
+ <tag><c>cpu_timestamp</c></tag>
+ <item>
+ <p>A global trace flag for the Erlang node that makes all
+ trace timestamps be in CPU time, not wallclock. It is
+ only allowed with <c>PidSpec==all</c>. If the host
+ machine operating system does not support high resolution
+ CPU time measurements, <c>trace/3</c> exits with
+ <c>badarg</c>.</p>
+ </item>
+ <tag><c>arity</c></tag>
+ <item>
+ <p>Used in conjunction with the <c>call</c> trace flag.
+ <c>{M, F, Arity}</c> will be specified instead of
+ <c>{M, F, Args}</c> in call trace messages.</p>
+ </item>
+ <tag><c>set_on_spawn</c></tag>
+ <item>
+ <p>Makes any process created by a traced process inherit
+ its trace flags, including the <c>set_on_spawn</c> flag.</p>
+ </item>
+ <tag><c>set_on_first_spawn</c></tag>
+ <item>
+ <p>Makes the first process created by a traced process
+ inherit its trace flags, excluding
+ the <c>set_on_first_spawn</c> flag.</p>
+ </item>
+ <tag><c>set_on_link</c></tag>
+ <item>
+ <p>Makes any process linked by a traced process inherit its
+ trace flags, including the <c>set_on_link</c> flag.</p>
+ </item>
+ <tag><c>set_on_first_link</c></tag>
+ <item>
+ <p>Makes the first process linked to by a traced process
+ inherit its trace flags, excluding
+ the <c>set_on_first_link</c> flag.</p>
+ </item>
+ <tag><c>{tracer, Tracer}</c></tag>
+ <item>
+ <p>Specify where to send the trace messages. <c>Tracer</c>
+ must be the pid of a local process or the port identifier
+ of a local port. If this flag is not given, trace
+ messages will be sent to the process that called
+ <c>erlang:trace/3</c>.</p>
+ </item>
+ </taglist>
+ <p>The effect of combining <c>set_on_first_link</c> with
+ <c>set_on_link</c> is the same as having
+ <c>set_on_first_link</c> alone. Likewise for
+ <c>set_on_spawn</c> and <c>set_on_first_spawn</c>.</p>
+ <p>If the <c>timestamp</c> flag is not given, the tracing
+ process will receive the trace messages described below.
+ <c>Pid</c> is the pid of the traced process in which
+ the traced event has occurred. The third element of the tuple
+ is the message tag.</p>
+ <p>If the <c>timestamp</c> flag is given, the first element of
+ the tuple will be <c>trace_ts</c> instead and the timestamp
+ is added last in the tuple.</p>
+ <taglist>
+ <tag><c>{trace, Pid, 'receive', Msg}</c></tag>
+ <item>
+ <p>When <c>Pid</c> receives the message <c>Msg</c>.</p>
+ </item>
+ <tag><c>{trace, Pid, send, Msg, To}</c></tag>
+ <item>
+ <p>When <c>Pid</c> sends the message <c>Msg</c> to
+ the process <c>To</c>.</p>
+ </item>
+ <tag><c>{trace, Pid, send_to_non_existing_process, Msg, To}</c></tag>
+ <item>
+ <p>When <c>Pid</c> sends the message <c>Msg</c> to
+ the non-existing process <c>To</c>.</p>
+ </item>
+ <tag><c>{trace, Pid, call, {M, F, Args}}</c></tag>
+ <item>
+ <p>When <c>Pid</c> calls a traced function. The return
+ values of calls are never supplied, only the call and its
+ arguments.</p>
+ <p>Note that the trace flag <c>arity</c> can be used to
+ change the contents of this message, so that <c>Arity</c>
+ is specified instead of <c>Args</c>.</p>
+ </item>
+ <tag><c>{trace, Pid, return_to, {M, F, Arity}}</c></tag>
+ <item>
+ <p>When <c>Pid</c> returns <em>to</em> the specified
+ function. This trace message is sent if both
+ the <c>call</c> and the <c>return_to</c> flags are set,
+ and the function is set to be traced on <em>local</em>
+ function calls. The message is only sent when returning
+ from a chain of tail recursive function calls where at
+ least one call generated a <c>call</c> trace message
+ (that is, the functions match specification matched and
+ <c>{message, false}</c> was not an action).</p>
+ </item>
+ <tag><c>{trace, Pid, return_from, {M, F, Arity}, ReturnValue}</c></tag>
+ <item>
+ <p>When <c>Pid</c> returns <em>from</em> the specified
+ function. This trace message is sent if the <c>call</c>
+ flag is set, and the function has a match specification
+ with a <c>return_trace</c> or <c>exception_trace</c> action.</p>
+ </item>
+ <tag><c>{trace, Pid, exception_from, {M, F, Arity}, {Class, Value}}</c></tag>
+ <item>
+ <p>When <c>Pid</c> exits <em>from</em> the specified
+ function due to an exception. This trace message is sent
+ if the <c>call</c> flag is set, and the function has
+ a match specification with an <c>exception_trace</c> action.</p>
+ </item>
+ <tag><c>{trace, Pid, spawn, Pid2, {M, F, Args}}</c></tag>
+ <item>
+ <p>When <c>Pid</c> spawns a new process <c>Pid2</c> with
+ the specified function call as entry point.</p>
+ <p>Note that <c>Args</c> is supposed to be the argument
+ list, but may be any term in the case of an erroneous
+ spawn.</p>
+ </item>
+ <tag><c>{trace, Pid, exit, Reason}</c></tag>
+ <item>
+ <p>When <c>Pid</c> exits with reason <c>Reason</c>.</p>
+ </item>
+ <tag><c>{trace, Pid, link, Pid2}</c></tag>
+ <item>
+ <p>When <c>Pid</c> links to a process <c>Pid2</c>.</p>
+ </item>
+ <tag><c>{trace, Pid, unlink, Pid2}</c></tag>
+ <item>
+ <p>When <c>Pid</c> removes the link from a process
+ <c>Pid2</c>.</p>
+ </item>
+ <tag><c>{trace, Pid, getting_linked, Pid2}</c></tag>
+ <item>
+ <p>When <c>Pid</c> gets linked to a process <c>Pid2</c>.</p>
+ </item>
+ <tag><c>{trace, Pid, getting_unlinked, Pid2}</c></tag>
+ <item>
+ <p>When <c>Pid</c> gets unlinked from a process <c>Pid2</c>.</p>
+ </item>
+ <tag><c>{trace, Pid, register, RegName}</c></tag>
+ <item>
+ <p>When <c>Pid</c> gets the name <c>RegName</c> registered.</p>
+ </item>
+ <tag><c>{trace, Pid, unregister, RegName}</c></tag>
+ <item>
+ <p>When <c>Pid</c> gets the name <c>RegName</c> unregistered.
+ Note that this is done automatically when a registered
+ process exits.</p>
+ </item>
+ <tag><c>{trace, Pid, in, {M, F, Arity} | 0}</c></tag>
+ <item>
+ <p>When <c>Pid</c> is scheduled to run. The process will
+ run in function <c>{M, F, Arity}</c>. On some rare
+ occasions the current function cannot be determined, then
+ the last element <c>Arity</c> is 0.</p>
+ </item>
+ <tag><c>{trace, Pid, out, {M, F, Arity} | 0}</c></tag>
+ <item>
+ <p>When <c>Pid</c> is scheduled out. The process was
+ running in function {M, F, Arity}. On some rare occasions
+ the current function cannot be determined, then the last
+ element <c>Arity</c> is 0.</p>
+ </item>
+ <tag><c>{trace, Pid, gc_start, Info}</c></tag>
+ <item>
+ <marker id="gc_start"></marker>
+ <p>Sent when garbage collection is about to be started.
+ <c>Info</c> is a list of two-element tuples, where
+ the first element is a key, and the second is the value.
+ You should not depend on the tuples have any defined
+ order. Currently, the following keys are defined:</p>
+ <taglist>
+ <tag><c>heap_size</c></tag>
+ <item>The size of the used part of the heap.</item>
+ <tag><c>heap_block_size</c></tag>
+ <item>The size of the memory block used for storing
+ the heap and the stack.</item>
+ <tag><c>old_heap_size</c></tag>
+ <item>The size of the used part of the old heap.</item>
+ <tag><c>old_heap_block_size</c></tag>
+ <item>The size of the memory block used for storing
+ the old heap.</item>
+ <tag><c>stack_size</c></tag>
+ <item>The actual size of the stack.</item>
+ <tag><c>recent_size</c></tag>
+ <item>The size of the data that survived the previous garbage
+ collection.</item>
+ <tag><c>mbuf_size</c></tag>
+ <item>The combined size of message buffers associated with
+ the process.</item>
+ </taglist>
+ <p>All sizes are in words.</p>
+ </item>
+ <tag><c>{trace, Pid, gc_end, Info}</c></tag>
+ <item>
+ <p>Sent when garbage collection is finished. <c>Info</c>
+ contains the same kind of list as in the <c>gc_start</c>
+ message, but the sizes reflect the new sizes after
+ garbage collection.</p>
+ </item>
+ </taglist>
+ <p>If the tracing process dies, the flags will be silently
+ removed.</p>
+ <p>Only one process can trace a particular process. For this
+ reason, attempts to trace an already traced process will fail.</p>
+ <p>Returns: A number indicating the number of processes that
+ matched <c>PidSpec</c>. If <c>PidSpec</c> is a pid,
+ the return value will be <c>1</c>. If <c>PidSpec</c> is
+ <c>all</c> or <c>existing</c> the return value will be
+ the number of processes running, excluding tracer processes.
+ If <c>PidSpec</c> is <c>new</c>, the return value will be
+ <c>0</c>.</p>
+ <p>Failure: If specified arguments are not supported. For
+ example <c>cpu_timestamp</c> is not supported on all
+ platforms.</p>
+ </desc>
+ </func>
+ <func>
+ <name>erlang:trace_delivered(Tracee) -> Ref</name>
+ <fsummary>Notification when trace has been delivered</fsummary>
+ <type>
+ <v>Tracee = pid() | all</v>
+ <v>Ref = reference()</v>
+ </type>
+ <desc>
+ <p>The delivery of trace messages is dislocated on the time-line
+ compared to other events in the system. If you know that the
+ <c>Tracee</c> has passed some specific point in its execution,
+ and you want to know when at least all trace messages
+ corresponding to events up to this point have reached the tracer
+ you can use <c>erlang:trace_delivered(Tracee)</c>. A
+ <c>{trace_delivered, Tracee, Ref}</c> message is sent to
+ the caller of <c>erlang:trace_delivered(Tracee)</c> when it
+ is guaranteed that all trace messages have been delivered to
+ the tracer up to the point that the <c>Tracee</c> had reached
+ at the time of the call to
+ <c>erlang:trace_delivered(Tracee)</c>.</p>
+ <p>Note that the <c>trace_delivered</c> message does <em>not</em>
+ imply that trace messages have been delivered; instead, it implies
+ that all trace messages that <em>should</em> be delivered have
+ been delivered. It is not an error if <c>Tracee</c> isn't, and
+ hasn't been traced by someone, but if this is the case,
+ <em>no</em> trace messages will have been delivered when the
+ <c>trace_delivered</c> message arrives.</p>
+ <p>Note that <c>Tracee</c> has to refer to a process currently,
+ or previously existing on the same node as the caller of
+ <c>erlang:trace_delivered(Tracee)</c> resides on.
+ The special <c>Tracee</c> atom <c>all</c> denotes all processes
+ that currently are traced in the node.</p>
+ <p>An example: Process <c>A</c> is tracee, port <c>B</c> is
+ tracer, and process <c>C</c> is the port owner of <c>B</c>.
+ <c>C</c> wants to close <c>B</c> when <c>A</c> exits. <c>C</c>
+ can ensure that the trace isn't truncated by calling
+ <c>erlang:trace_delivered(A)</c> when <c>A</c> exits and wait
+ for the <c>{trace_delivered, A, Ref}</c> message before closing
+ <c>B</c>.</p>
+ <p>Failure: <c>badarg</c> if <c>Tracee</c> does not refer to a
+ process (dead or alive) on the same node as the caller of
+ <c>erlang:trace_delivered(Tracee)</c> resides on.</p>
+ </desc>
+ </func>
+ <func>
+ <name>erlang:trace_info(PidOrFunc, Item) -> Res</name>
+ <fsummary>Trace information about a process or function</fsummary>
+ <type>
+ <v>PidOrFunc = pid() | new | {Module, Function, Arity} | on_load</v>
+ <v>&nbsp;Module = Function = atom()</v>
+ <v>&nbsp;Arity = int()</v>
+ <v>Item, Res -- see below</v>
+ </type>
+ <desc>
+ <p>Returns trace information about a process or function.</p>
+ <p>To get information about a process, <c>PidOrFunc</c> should
+ be a pid or the atom <c>new</c>. The atom <c>new</c> means
+ that the default trace state for processes to be created will
+ be returned. <c>Item</c> must have one of the following
+ values:</p>
+ <taglist>
+ <tag><c>flags</c></tag>
+ <item>
+ <p>Return a list of atoms indicating what kind of traces is
+ enabled for the process. The list will be empty if no
+ traces are enabled, and one or more of the followings
+ atoms if traces are enabled: <c>send</c>,
+ <c>'receive'</c>, <c>set_on_spawn</c>, <c>call</c>,
+ <c>return_to</c>, <c>procs</c>, <c>set_on_first_spawn</c>,
+ <c>set_on_link</c>, <c>running</c>,
+ <c>garbage_collection</c>, <c>timestamp</c>, and
+ <c>arity</c>. The order is arbitrary.</p>
+ </item>
+ <tag><c>tracer</c></tag>
+ <item>
+ <p>Return the identifier for process or port tracing this
+ process. If this process is not being traced, the return
+ value will be <c>[]</c>.</p>
+ </item>
+ </taglist>
+ <p>To get information about a function, <c>PidOrFunc</c> should
+ be a three-element tuple: <c>{Module, Function, Arity}</c> or
+ the atom <c>on_load</c>. No wildcards are allowed. Returns
+ <c>undefined</c> if the function does not exist or
+ <c>false</c> if the function is not traced at all. <c>Item</c>
+ must have one of the following values:</p>
+ <taglist>
+ <tag><c>traced</c></tag>
+ <item>
+ <p>Return <c>global</c> if this function is traced on
+ global function calls, <c>local</c> if this function is
+ traced on local function calls (i.e local and global
+ function calls), and <c>false</c> if neither local nor
+ global function calls are traced.</p>
+ </item>
+ <tag><c>match_spec</c></tag>
+ <item>
+ <p>Return the match specification for this function, if it
+ has one. If the function is locally or globally traced but
+ has no match specification defined, the returned value
+ is <c>[]</c>.</p>
+ </item>
+ <tag><c>meta</c></tag>
+ <item>
+ <p>Return the meta trace tracer process or port for this
+ function, if it has one. If the function is not meta
+ traced the returned value is <c>false</c>, and if
+ the function is meta traced but has once detected that
+ the tracer proc is invalid, the returned value is [].</p>
+ </item>
+ <tag><c>meta_match_spec</c></tag>
+ <item>
+ <p>Return the meta trace match specification for this
+ function, if it has one. If the function is meta traced
+ but has no match specification defined, the returned
+ value is <c>[]</c>.</p>
+ </item>
+ <tag><c>call_count</c></tag>
+ <item>
+ <p>Return the call count value for this function or
+ <c>true</c> for the pseudo function <c>on_load</c> if call
+ count tracing is active. Return <c>false</c> otherwise.
+ See also
+ <seealso marker="#erlang:trace_pattern/3">erlang:trace_pattern/3</seealso>.</p>
+ </item>
+ <tag><c>all</c></tag>
+ <item>
+ <p>Return a list containing the <c>{Item, Value}</c> tuples
+ for all other items, or return <c>false</c> if no tracing
+ is active for this function.</p>
+ </item>
+ </taglist>
+ <p>The actual return value will be <c>{Item, Value}</c>, where
+ <c>Value</c> is the requested information as described above.
+ If a pid for a dead process was given, or the name of a
+ non-existing function, <c>Value</c> will be <c>undefined</c>.</p>
+ <p>If <c>PidOrFunc</c> is the <c>on_load</c>, the information
+ returned refers to the default value for code that will be
+ loaded.</p>
+ </desc>
+ </func>
+ <func>
+ <name>erlang:trace_pattern(MFA, MatchSpec) -> int()</name>
+ <fsummary>Set trace patterns for global call tracing</fsummary>
+ <desc>
+ <p>The same as
+ <seealso marker="#erlang:trace_pattern/3">erlang:trace_pattern(MFA, MatchSpec, [])</seealso>,
+ retained for backward compatibility.</p>
+ </desc>
+ </func>
+ <func>
+ <name>erlang:trace_pattern(MFA, MatchSpec, FlagList) -> int()</name>
+ <fsummary>Set trace patterns for tracing of function calls</fsummary>
+ <type>
+ <v>MFA, MatchSpec, FlagList -- see below</v>
+ </type>
+ <desc>
+ <p>This BIF is used to enable or disable call tracing for
+ exported functions. It must be combined with
+ <seealso marker="#erlang:trace/3">erlang:trace/3</seealso>
+ to set the <c>call</c> trace flag for one or more processes.</p>
+ <p>Conceptually, call tracing works like this: Inside
+ the Erlang virtual machine there is a set of processes to be
+ traced and a set of functions to be traced. Tracing will be
+ enabled on the intersection of the set. That is, if a process
+ included in the traced process set calls a function included
+ in the traced function set, the trace action will be taken.
+ Otherwise, nothing will happen.</p>
+ <p>Use
+ <seealso marker="#erlang:trace/3">erlang:trace/3</seealso> to
+ add or remove one or more processes to the set of traced
+ processes. Use <c>erlang:trace_pattern/2</c> to add or remove
+ exported functions to the set of traced functions.</p>
+ <p>The <c>erlang:trace_pattern/3</c> BIF can also add match
+ specifications to an exported function. A match specification
+ comprises a pattern that the arguments to the function must
+ match, a guard expression which must evaluate to <c>true</c>
+ and an action to be performed. The default action is to send a
+ trace message. If the pattern does not match or the guard
+ fails, the action will not be executed.</p>
+ <p>The <c>MFA</c> argument should be a tuple like
+ <c>{Module, Function, Arity}</c> or the atom <c>on_load</c>
+ (described below). It can be the module, function, and arity
+ for an exported function (or a BIF in any module).
+ The <c>'_'</c> atom can be used to mean any of that kind.
+ Wildcards can be used in any of the following ways:</p>
+ <taglist>
+ <tag><c>{Module,Function,'_'}</c></tag>
+ <item>
+ <p>All exported functions of any arity named <c>Function</c>
+ in module <c>Module</c>.</p>
+ </item>
+ <tag><c>{Module,'_','_'}</c></tag>
+ <item>
+ <p>All exported functions in module <c>Module</c>.</p>
+ </item>
+ <tag><c>{'_','_','_'}</c></tag>
+ <item>
+ <p>All exported functions in all loaded modules.</p>
+ </item>
+ </taglist>
+ <p>Other combinations, such as <c>{Module,'_',Arity}</c>, are
+ not allowed. Local functions will match wildcards only if
+ the <c>local</c> option is in the <c>FlagList</c>.</p>
+ <p>If the <c>MFA</c> argument is the atom <c>on_load</c>,
+ the match specification and flag list will be used on all
+ modules that are newly loaded.</p>
+ <p>The <c>MatchSpec</c> argument can take any of the following
+ forms:</p>
+ <taglist>
+ <tag><c>false</c></tag>
+ <item>
+ <p>Disable tracing for the matching function(s). Any match
+ specification will be removed.</p>
+ </item>
+ <tag><c>true</c></tag>
+ <item>
+ <p>Enable tracing for the matching function(s).</p>
+ </item>
+ <tag><c>MatchSpecList</c></tag>
+ <item>
+ <p>A list of match specifications. An empty list is
+ equivalent to <c>true</c>. See the ERTS User's Guide
+ for a description of match specifications.</p>
+ </item>
+ <tag><c>restart</c></tag>
+ <item>
+ <p>For the <c>FlagList</c> option <c>call_count</c>:
+ restart the existing counters. The behaviour is undefined
+ for other <c>FlagList</c> options.</p>
+ </item>
+ <tag><c>pause</c></tag>
+ <item>
+ <p>For the <c>FlagList</c> option <c>call_count</c>: pause
+ the existing counters. The behaviour is undefined for
+ other <c>FlagList</c> options.</p>
+ </item>
+ </taglist>
+ <p>The <c>FlagList</c> parameter is a list of options.
+ The following options are allowed:</p>
+ <taglist>
+ <tag><c>global</c></tag>
+ <item>
+ <p>Turn on or off call tracing for global function calls
+ (that is, calls specifying the module explicitly). Only
+ exported functions will match and only global calls will
+ generate trace messages. This is the default.</p>
+ </item>
+ <tag><c>local</c></tag>
+ <item>
+ <p>Turn on or off call tracing for all types of function
+ calls. Trace messages will be sent whenever any of
+ the specified functions are called, regardless of how they
+ are called. If the <c>return_to</c> flag is set for
+ the process, a <c>return_to</c> message will also be sent
+ when this function returns to its caller.</p>
+ </item>
+ <tag><c>meta | {meta, Pid}</c></tag>
+ <item>
+ <p>Turn on or off meta tracing for all types of function
+ calls. Trace messages will be sent to the tracer process
+ or port <c>Pid</c> whenever any of the specified
+ functions are called, regardless of how they are called.
+ If no <c>Pid</c> is specified, <c>self()</c> is used as a
+ default tracer process.</p>
+ <p>Meta tracing traces all processes and does not care
+ about the process trace flags set by <c>trace/3</c>,
+ the trace flags are instead fixed to
+ <c>[call, timestamp]</c>.</p>
+ <p>The match spec function <c>{return_trace}</c> works with
+ meta trace and send its trace message to the same tracer
+ process.</p>
+ </item>
+ <tag><c>call_count</c></tag>
+ <item>
+ <p>Starts (<c>MatchSpec == true</c>) or stops
+ (<c>MatchSpec == false</c>) call count tracing for all
+ types of function calls. For every function a counter is
+ incremented when the function is called, in any process.
+ No process trace flags need to be activated.</p>
+ <p>If call count tracing is started while already running,
+ the count is restarted from zero. Running counters can be
+ paused with <c>MatchSpec == pause</c>. Paused and running
+ counters can be restarted from zero with
+ <c>MatchSpec == restart</c>.</p>
+ <p>The counter value can be read with
+ <seealso marker="#erlang:trace_info/2">erlang:trace_info/2</seealso>.</p>
+ </item>
+ </taglist>
+ <p>The <c>global</c> and <c>local</c> options are mutually
+ exclusive and <c>global</c> is the default (if no options are
+ specified). The <c>call_count</c> and <c>meta</c> options
+ perform a kind of local tracing, and can also not be combined
+ with <c>global</c>. A function can be either globally or
+ locally traced. If global tracing is specified for a
+ specified set of functions; local, meta and call count
+ tracing for the matching set of local functions will be
+ disabled, and vice versa.</p>
+ <p>When disabling trace, the option must match the type of trace
+ that is set on the function, so that local tracing must be
+ disabled with the <c>local</c> option and global tracing with
+ the <c>global</c> option (or no option at all), and so forth.</p>
+ <p>There is no way to directly change part of a match
+ specification list. If a function has a match specification,
+ you can replace it with a completely new one. If you need to
+ change an existing match specification, use the
+ <seealso marker="#erlang:trace_info/2">erlang:trace_info/2</seealso>
+ BIF to retrieve the existing match specification.</p>
+ <p>Returns the number of exported functions that matched
+ the <c>MFA</c> argument. This will be zero if none matched at
+ all.</p>
+ </desc>
+ </func>
+ <func>
+ <name>trunc(Number) -> int()</name>
+ <fsummary>Return an integer by the truncating a number</fsummary>
+ <type>
+ <v>Number = number()</v>
+ </type>
+ <desc>
+ <p>Returns an integer by the truncating <c>Number</c>.</p>
+ <pre>
+> <input>trunc(5.5).</input>
+5</pre>
+ <p>Allowed in guard tests.</p>
+ </desc>
+ </func>
+ <func>
+ <name>tuple_size(Tuple) -> int()</name>
+ <fsummary>Return the size of a tuple</fsummary>
+ <type>
+ <v>Tuple = tuple()</v>
+ </type>
+ <desc>
+ <p>Returns an integer which is the number of elements in <c>Tuple</c>.</p>
+ <pre>
+> <input>tuple_size({morni, mulle, bwange}).</input>
+3</pre>
+ <p>Allowed in guard tests.</p>
+ </desc>
+ </func>
+ <func>
+ <name>tuple_to_list(Tuple) -> [term()]</name>
+ <fsummary>Convert a tuple to a list</fsummary>
+ <type>
+ <v>Tuple = tuple()</v>
+ </type>
+ <desc>
+ <p>Returns a list which corresponds to <c>Tuple</c>.
+ <c>Tuple</c> may contain any Erlang terms.</p>
+ <pre>
+> <input>tuple_to_list({share, {'Ericsson_B', 163}}).</input>
+[share,{'Ericsson_B',163}]</pre>
+ </desc>
+ </func>
+ <func>
+ <name>erlang:universaltime() -> {Date, Time}</name>
+ <fsummary>Current date and time according to Universal Time Coordinated (UTC)</fsummary>
+ <type>
+ <v>Date = {Year, Month, Day}</v>
+ <v>Time = {Hour, Minute, Second}</v>
+ <v>&nbsp;Year = Month = Day = Hour = Minute = Second = int()</v>
+ </type>
+ <desc>
+ <p>Returns the current date and time according to Universal
+ Time Coordinated (UTC), also called GMT, in the form
+ <c>{{Year, Month, Day}, {Hour, Minute, Second}}</c> if
+ supported by the underlying operating system. If not,
+ <c>erlang:universaltime()</c> is equivalent to
+ <c>erlang:localtime()</c>.</p>
+ <pre>
+> <input>erlang:universaltime().</input>
+{{1996,11,6},{14,18,43}}</pre>
+ </desc>
+ </func>
+ <func>
+ <name>erlang:universaltime_to_localtime({Date1, Time1}) -> {Date2, Time2}</name>
+ <fsummary>Convert from Universal Time Coordinated (UTC) to local date and time</fsummary>
+ <type>
+ <v>Date1 = Date2 = {Year, Month, Day}</v>
+ <v>Time1 = Time2 = {Hour, Minute, Second}</v>
+ <v>&nbsp;Year = Month = Day = Hour = Minute = Second = int()</v>
+ </type>
+ <desc>
+ <p>Converts Universal Time Coordinated (UTC) date and time to
+ local date and time, if this is supported by the underlying
+ OS. Otherwise, no conversion is done, and
+ <c>{Date1, Time1}</c> is returned.</p>
+ <pre>
+> <input>erlang:universaltime_to_localtime({{1996,11,6},{14,18,43}}).</input>
+{{1996,11,7},{15,18,43}}</pre>
+ <p>Failure: <c>badarg</c> if <c>Date1</c> or <c>Time1</c> do
+ not denote a valid date or time.</p>
+ </desc>
+ </func>
+ <func>
+ <name>unlink(Id) -> true</name>
+ <fsummary>Remove a link, if there is one, to another process or port</fsummary>
+ <type>
+ <v>Id = pid() | port()</v>
+ </type>
+ <desc>
+ <p>Removes the link, if there is one, between the calling
+ process and the process or port referred to by <c>Id</c>.</p>
+ <p>Returns <c>true</c> and does not fail, even if there is no
+ link to <c>Id</c>, or if <c>Id</c> does not exist.</p>
+ <p>Once <c>unlink(Id)</c> has returned it is guaranteed that
+ the link between the caller and the entity referred to by
+ <c>Id</c> has no effect on the caller in the future (unless
+ the link is setup again). If caller is trapping exits, an
+ <c>{'EXIT', Id, _}</c> message due to the link might have
+ been placed in the callers message queue prior to the call,
+ though. Note, the <c>{'EXIT', Id, _}</c> message can be the
+ result of the link, but can also be the result of <c>Id</c>
+ calling <c>exit/2</c>. Therefore, it <em>may</em> be
+ appropriate to cleanup the message queue when trapping exits
+ after the call to <c>unlink(Id)</c>, as follow:</p>
+ <code type="none">
+
+ unlink(Id),
+ receive
+\011{'EXIT', Id, _} ->
+\011 true
+ after 0 ->
+\011 true
+ end</code>
+ <note>
+ <p>Prior to OTP release R11B (erts version 5.5) <c>unlink/1</c>
+ behaved completely asynchronous, i.e., the link was active
+ until the "unlink signal" reached the linked entity. This
+ had one undesirable effect, though. You could never know when
+ you were guaranteed <em>not</em> to be effected by the link.</p>
+ <p>Current behavior can be viewed as two combined operations:
+ asynchronously send an "unlink signal" to the linked entity
+ and ignore any future results of the link.</p>
+ </note>
+ </desc>
+ </func>
+ <func>
+ <name>unregister(RegName) -> true</name>
+ <fsummary>Remove the registered name for a process (or port)</fsummary>
+ <type>
+ <v>RegName = atom()</v>
+ </type>
+ <desc>
+ <p>Removes the registered name <c>RegName</c>, associated with a
+ pid or a port identifier.</p>
+ <pre>
+> <input>unregister(db).</input>
+true</pre>
+ <p>Users are advised not to unregister system processes.</p>
+ <p>Failure: <c>badarg</c> if <c>RegName</c> is not a registered
+ name.</p>
+ </desc>
+ </func>
+ <func>
+ <name>whereis(RegName) -> pid() | port() | undefined</name>
+ <fsummary>Get the pid (or port) with a given registered name</fsummary>
+ <desc>
+ <p>Returns the pid or port identifier with the registered name
+ <c>RegName</c>. Returns <c>undefined</c> if the name is not
+ registered.</p>
+ <pre>
+> <input>whereis(db).</input>
+&lt;0.43.0></pre>
+ </desc>
+ </func>
+ <func>
+ <name>erlang:yield() -> true</name>
+ <fsummary>Let other processes get a chance to execute</fsummary>
+ <desc>
+ <p>Voluntarily let other processes (if any) get a chance to
+ execute. Using <c>erlang:yield()</c> is similar to
+ <c>receive after 1 -> ok end</c>, except that <c>yield()</c>
+ is faster.</p>
+ <warning><p>There is seldom or never any need to use this BIF,
+ especially in the SMP-emulator as other processes will have a
+ chance to run in another scheduler thread anyway.
+ Using this BIF without a thorough grasp of how the scheduler
+ works may cause performance degradation.</p></warning>
+ </desc>
+ </func>
+ </funcs>
+</erlref>
+