diff options
Diffstat (limited to 'erts/doc/src/erlang.xml')
| -rw-r--r-- | erts/doc/src/erlang.xml | 6920 |
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> +<<"Erlang">></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(<<"Erlang">>, latin1).</input> +'Erlang' +> <input>binary_to_atom(<<1024/utf8>>, utf8).</input> +** exception error: bad argument + in function binary_to_atom/2 + called as binary_to_atom(<<208,128>>,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(<<433:16,3:3>>).</input> +19 +> <input>bit_size(<<1,2,3>>).</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(<<433:16,3:3>>).</input> +3 +> <input>byte_size(<<1,2,3>>).</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> 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,<<3,"abcd">>,[]).</input> +{ok,<<"abc">>,<<"d">>} +> <input>erlang:decode_packet(1,<<5,"abcd">>,[]).</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 = <<1,2,3>>.</input> +<<1,2,3>> +> <input>Bin2 = <<4,5>>.</input> +<<4,5>> +> <input>Bin3 = <<6>>.</input> +<<6>> +> <input>iolist_to_binary([Bin1,1,[2,3,Bin2],4|Bin3]).</input> +<<1,2,3,1,2,3,4,5,4,6>></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|<<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 = <<1,2,3>>.</input> +<<1,2,3>> +> <input>Bin2 = <<4,5>>.</input> +<<4,5>> +> <input>Bin3 = <<6>>.</input> +<<6>> +> <input>list_to_binary([Bin1,1,[2,3,Bin2],4|Bin3]).</input> +<<1,2,3,1,2,3,4,5,4,6>></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 = <<1,2,3>>.</input> +<<1,2,3>> +> <input>Bin2 = <<4,5>>.</input> +<<4,5>> +> <input>Bin3 = <<6,7:4,>>.</input> +<<6>> +> <input>list_to_binary([Bin1,1,[2,3,Bin2],4|Bin3]).</input> +<<1,2,3,1,2,3,4,5,4,6,7:46>></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("<0.4.1>").</input> +<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> 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> 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> 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<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> RegName = atom()</v> + <v> 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> Command = string()</v> + <v> In = Out = int()</v> + <v>PortSettings = [Opt]</v> + <v> 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> N = 1 | 2 | 4</v> + <v> L = int()</v> + <v> Dir = string()</v> + <v> Env = [{Name, Val}]</v> + <v> Name = string()</v> + <v> 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®, 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® 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> > 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> +[<0.0.0>,<0.2.0>,<0.4.0>,<0.5.0>,<0.7.0>,<0.8.0>]</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> Module = Function = atom()</v> + <v> Arity = int()</v> + <v> Args = [term()]</v> + <v> 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> +<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> RegName = atom()</v> + <v> 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> RegName = atom()</v> + <v> 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> 0 <= Time <= 4294967295</v> + <v>Dest = pid() | RegName </v> + <v> 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> RegName = atom()</v> + <v> 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> RegName = atom()</v> + <v> 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> +<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> Level = low | normal | high</v> + <v> Number = int()</v> + <v> 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> Level = low | normal | high</v> + <v> Number = int()</v> + <v> 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> Level = low | normal | high</v> + <v> Number = int()</v> + <v> 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> Level = low | normal | high</v> + <v> Number = int()</v> + <v> 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> +<<"0123456789">> +> <input>byte_size(B).</input> +10 +> <input>{B1, B2} = split_binary(B,3).</input> +{<<"012">>,<<"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> 0 <= Time <= 4294967295</v> + <v>Dest = LocalPid | RegName </v> + <v> LocalPid = pid() (of a process, alive or dead, on the local node)</v> + <v> 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">"<major ver>.<minor ver>"</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> MonitorPid = pid()</v> + <v> Options = [Option]</v> + <v> Option = {long_gc, Time} | {large_heap, Size} | busy_port | busy_dist_port</v> + <v> 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> Time = Size = int()</v> + <v>MonSettings = {OldMonitorPid, [Option]}</v> + <v> 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> ProfilerPid = pid() | port()</v> + <v> Options = [Option]</v> + <v> 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> ProfilerPid = pid() | port()</v> + <v> Options = [Option]</v> + <v> 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> 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> Module = Function = atom()</v> + <v> 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> 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> 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> +<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> + |