Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Fetching contributors…

Cannot retrieve contributors at this time

7298 lines (7230 sloc) 321.935 kb
<?xml version="1.0" encoding="latin1" ?>
<!DOCTYPE erlref SYSTEM "erlref.dtd">
<erlref>
<header>
<copyright>
<year>1996</year><year>2012</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>
<datatypes>
<datatype>
<name><marker id="type-ext_binary">ext_binary()</marker></name>
<desc>
<p>A binary data object, structured according to
the Erlang external term format.</p>
</desc>
</datatype>
<datatype>
<name name="timestamp"></name>
<desc><p>See <seealso marker="#now/0">now/0</seealso>.</p>
</desc>
</datatype>
</datatypes>
<funcs>
<func>
<name>abs(Number) -> integer() | 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>erlang:adler32(Data) -> integer()</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>erlang:adler32(OldAdler, Data) -> integer()</name>
<fsummary>Compute adler32 checksum</fsummary>
<type>
<v>OldAdler = integer()</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 = erlang:adler32(Data1),
Y = erlang:adler32(X,Data2).
</code>
<p>- would assign the same value to <c>Y</c> as this would:</p>
<code>
Y = erlang:adler32([Data1,Data2]).
</code>
</desc>
</func>
<func>
<name>erlang:adler32_combine(FirstAdler, SecondAdler, SecondSize) -> integer()</name>
<fsummary>Combine two adler32 checksums</fsummary>
<type>
<v>FirstAdler = SecondAdler = integer()</v>
<v>SecondSize = integer()</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 = erlang:adler32(Data1),
Z = erlang:adler32(Y,Data2).
</code>
<p>- would assign the same value to <c>Z</c> as this would:</p>
<code>
X = erlang:adler32(Data1),
Y = erlang:adler32(Data2),
Z = erlang: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 name="apply" arity="2"/>
<fsummary>Apply a function to an argument list</fsummary>
<desc>
<p>Call a fun, passing the elements in <c><anno>Args</anno></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><anno>Fun</anno>(Arg1, Arg2, ... ArgN)</c>.</p>
<warning>
<p>Earlier, <c><anno>Fun</anno></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 name="apply" arity="3"/>
<fsummary>Apply a function to an argument list</fsummary>
<desc>
<p>Returns the result of applying <c>Function</c> in
<c><anno>Module</anno></c> to <c><anno>Args</anno></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><anno>Module</anno>:<anno>Function</anno>(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 be encoded using UTF-8
(meaning that characters from 16#80 up to 0xFF will be
encoded in two bytes).</p>
<note><p>Currently, <c>atom_to_binary(Atom, latin1)</c> can
never fail because the text representation of an atom can only contain
characters from 0 to 16#FF. In a future release, the text representation
of atoms might be allowed to contain any Unicode character
and <c>atom_to_binary(Atom, latin1)</c> will fail if the
text representation for the <c>Atom</c> contains a Unicode
character greater than 16#FF.</p></note>
<pre>
> <input>atom_to_binary('Erlang', latin1).</input>
&lt;&lt;"Erlang"&gt;&gt;</pre>
</desc>
</func>
<func>
<name>atom_to_list(Atom) -> string()</name>
<fsummary>Text representation of an atom</fsummary>
<type>
<v>Atom = atom()</v>
</type>
<desc>
<p>Returns a string which corresponds to the text
representation of <c>Atom</c>.</p>
<pre>
> <input>atom_to_list('Erlang').</input>
"Erlang"</pre>
</desc>
</func>
<func>
<name>binary_part(Subject, PosLen) -> binary()</name>
<fsummary>Extracts a part of a binary</fsummary>
<type>
<v>Subject = binary()</v>
<v>PosLen = {Start,Length}</v>
<v>Start = integer() >= 0</v>
<v>Length = integer() >= 0</v>
</type>
<desc>
<p>Extracts the part of the binary described by <c>PosLen</c>.</p>
<p>Negative length can be used to extract bytes at the end of a binary:</p>
<code>
1> Bin = &lt;&lt;1,2,3,4,5,6,7,8,9,10&gt;&gt;.
2> binary_part(Bin,{byte_size(Bin), -5)).
&lt;&lt;6,7,8,9,10&gt;&gt;
</code>
<p>If <c>PosLen</c> in any way references outside the binary, a <c>badarg</c> exception is raised.</p>
<p><c>Start</c> is zero-based, i.e.:</p>
<code>
1> Bin = &lt;&lt;1,2,3&gt;&gt;
2> binary_part(Bin,{0,2}).
&lt;&lt;1,2&gt;&gt;
</code>
<p>See the STDLIB module <c>binary</c> for details about the <c>PosLen</c> semantics.</p>
<p>Allowed in guard tests.</p>
</desc>
</func>
<func>
<name>binary_part(Subject, Start, Length) -> binary()</name>
<fsummary>Extracts a part of a binary</fsummary>
<type>
<v>Subject = binary()</v>
<v>Start = integer() >= 0</v>
<v>Length = integer() >= 0</v>
</type>
<desc>
<p>The same as <c>binary_part(Subject, {Pos, Len})</c>.</p>
<p>Allowed in guard tests.</p>
</desc>
</func>
<func>
<name>binary_to_atom(Binary, Encoding) -> atom()</name>
<fsummary>Convert from text representation to an atom</fsummary>
<type>
<v>Binary = binary()</v>
<v>Encoding = latin1 | utf8 | unicode</v>
</type>
<desc>
<p>Returns the atom whose text representation is
<c>Binary</c>. If <c>Encoding</c> is <c>latin1</c>, no
translation of bytes in the binary is done. If <c>Encoding</c>
is <c>utf8</c> or <c>unicode</c>, the binary must contain
valid UTF-8 sequences; furthermore, only Unicode characters up
to 0xFF are allowed.</p>
<note><p><c>binary_to_atom(Binary, utf8)</c> will fail if
the binary contains Unicode characters greater than 16#FF.
In a future release, such Unicode characters might be allowed
and <c>binary_to_atom(Binary, utf8)</c>
will not fail in that case.</p></note>
<pre>
> <input>binary_to_atom(&lt;&lt;"Erlang"&gt;&gt;, latin1).</input>
'Erlang'
> <input>binary_to_atom(&lt;&lt;1024/utf8&gt;&gt;, utf8).</input>
** exception error: bad argument
in function binary_to_atom/2
called as binary_to_atom(&lt;&lt;208,128&gt;&gt;,utf8)</pre>
</desc>
</func>
<func>
<name>binary_to_existing_atom(Binary, Encoding) -> atom()</name>
<fsummary>Convert from text representation to an atom</fsummary>
<type>
<v>Binary = binary()</v>
<v>Encoding = latin1 | utf8 | unicode</v>
</type>
<desc>
<p>Works like <seealso marker="#binary_to_atom/2">binary_to_atom/2</seealso>,
but the atom must already exist.</p>
<p>Failure: <c>badarg</c> if the atom does not already exist.</p>
</desc>
</func>
<func>
<name>binary_to_list(Binary) -> [char()]</name>
<fsummary>Convert a binary to a list</fsummary>
<type>
<v>Binary = binary()</v>
</type>
<desc>
<p>Returns a list of integers which correspond to the bytes of
<c>Binary</c>.</p>
</desc>
</func>
<func>
<name>binary_to_list(Binary, Start, Stop) -> [char()]</name>
<fsummary>Convert part of a binary to a list</fsummary>
<type>
<v>Binary = binary()</v>
<v>Start = Stop = 1..byte_size(Binary)</v>
</type>
<desc>
<p>As <c>binary_to_list/1</c>, but returns a list of integers
corresponding to the bytes from position <c>Start</c> to
position <c>Stop</c> in <c>Binary</c>. Positions in the
binary are numbered starting from 1.</p>
<note><p>This function's indexing style of using one-based indices for
binaries is deprecated. New code should use the functions in
the STDLIB module <c>binary</c> instead. They consequently
use the same (zero-based) style of indexing.</p></note>
</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 = <seealso marker="#type-ext_binary">ext_binary()</seealso></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.</p>
<warning>
<p>When decoding binaries from untrusted sources, consider using
<c>binary_to_term/2</c> to prevent denial of service attacks.</p>
</warning>
<p>See also
<seealso marker="#term_to_binary/1">term_to_binary/1</seealso>
and
<seealso marker="#binary_to_term/2">binary_to_term/2</seealso>.</p>
</desc>
</func>
<func>
<name>binary_to_term(Binary, Opts) -> term()</name>
<fsummary>Decode an Erlang external term format binary</fsummary>
<type>
<v>Opts = [safe]</v>
<v>Binary = <seealso marker="#type-ext_binary">ext_binary()</seealso></v>
</type>
<desc>
<p>As <c>binary_to_term/1</c>, but takes options that affect decoding
of the binary.</p>
<taglist>
<tag><c>safe</c></tag>
<item>
<p>Use this option when receiving binaries from an untrusted
source.</p>
<p>When enabled, it prevents decoding data that may be used to
attack the Erlang system. In the event of receiving unsafe
data, decoding fails with a badarg error.</p>
<p>Currently, this prevents creation of new atoms directly,
creation of new atoms indirectly (as they are embedded in
certain structures like pids, refs, funs, etc.), and creation of
new external function references. None of those resources are
currently garbage collected, so unchecked creation of them can
exhaust available memory.</p>
</item>
</taglist>
<p>Failure: <c>badarg</c> if <c>safe</c> is specified and unsafe data
is decoded.</p>
<p>See also
<seealso marker="#term_to_binary/1">term_to_binary/1</seealso>,
<seealso marker="#binary_to_term/1">binary_to_term/1</seealso>,
and <seealso marker="#list_to_existing_atom/1">
list_to_existing_atom/1</seealso>.</p>
</desc>
</func>
<func>
<name>bit_size(Bitstring) -> integer() >= 0</name>
<fsummary>Return the size of a bitstring</fsummary>
<type>
<v>Bitstring = bitstring()</v>
</type>
<desc>
<p>Returns an integer which is the size in bits of <c>Bitstring</c>.</p>
<pre>
> <input>bit_size(&lt;&lt;433:16,3:3&gt;&gt;).</input>
19
> <input>bit_size(&lt;&lt;1,2,3&gt;&gt;).</input>
24</pre>
<p>Allowed in guard tests.</p>
</desc>
</func>
<func>
<name>erlang:bump_reductions(Reductions) -> void()</name>
<fsummary>Increment the reduction counter</fsummary>
<type>
<v>Reductions = integer() >= 0</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) -> integer() >= 0</name>
<fsummary>Return the size of a bitstring (or binary)</fsummary>
<type>
<v>Bitstring = bitstring()</v>
</type>
<desc>
<p>Returns an integer which is the number of bytes needed to contain
<c>Bitstring</c>. (That is, if the number of bits in <c>Bitstring</c> is not
divisible by 8, the resulting number of bytes will be rounded <em>up</em>.)</p>
<pre>
> <input>byte_size(&lt;&lt;433:16,3:3&gt;&gt;).</input>
3
> <input>byte_size(&lt;&lt;1,2,3&gt;&gt;).</input>
3</pre>
<p>Allowed in guard tests.</p>
</desc>
</func>
<func>
<name>erlang:cancel_timer(TimerRef) -> Time | false</name>
<fsummary>Cancel a timer</fsummary>
<type>
<v>TimerRef = reference()</v>
<v>Time = integer() >= 0</v>
</type>
<desc>
<p>Cancels a timer, where <c>TimerRef</c> was returned by
either
<seealso marker="#send_after/3">erlang:send_after/3</seealso>
or
<seealso marker="#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="#send_after/3">erlang:send_after/3</seealso>,
<seealso marker="#start_timer/3">erlang:start_timer/3</seealso>,
and
<seealso marker="#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_old_code(Module) -> boolean()</name>
<fsummary>Check if a module has old code</fsummary>
<type>
<v>Module = atom()</v>
</type>
<desc>
<p>Returns <c>true</c> if the <c>Module</c> has old code,
and <c>false</c> otherwise.</p>
<p>See also <seealso marker="kernel:code">code(3)</seealso>.</p>
</desc>
</func>
<func>
<name>check_process_code(Pid, Module) -> boolean()</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>erlang:crc32(Data) -> integer() >= 0</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>erlang:crc32(OldCrc, Data) -> integer() >= 0</name>
<fsummary>Compute crc32 (IEEE 802.3) checksum</fsummary>
<type>
<v>OldCrc = integer() >= 0</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 = erlang:crc32(Data1),
Y = erlang:crc32(X,Data2).
</code>
<p>- would assign the same value to <c>Y</c> as this would:</p>
<code>
Y = erlang:crc32([Data1,Data2]).
</code>
</desc>
</func>
<func>
<name>erlang:crc32_combine(FirstCrc, SecondCrc, SecondSize) -> integer() >= 0</name>
<fsummary>Combine two crc32 (IEEE 802.3) checksums</fsummary>
<type>
<v>FirstCrc = SecondCrc = integer() >= 0</v>
<v>SecondSize = integer() >= 0</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 = erlang:crc32(Data1),
Z = erlang:crc32(Y,Data2).
</code>
<p>- would assign the same value to <c>Z</c> as this would:</p>
<code>
X = erlang:crc32(Data1),
Y = erlang:crc32(Data2),
Z = erlang:crc32_combine(X,Y,iolist_size(Data2)).
</code>
</desc>
</func>
<func>
<name>date() -> Date</name>
<fsummary>Current date</fsummary>
<type>
<v>Date = <seealso marker="calendar#type-date">calendar:date()</seealso></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>erlang: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 = integer() > 0 | undefined</v>
<v>Reason = term()</v>
<v>&nbsp;Type, Opt -- see below</v>
<v></v>
<v>HttpPacket = HttpRequest | HttpResponse | HttpHeader | http_eoh | HttpError</v>
<v>HttpRequest = {http_request, HttpMethod, HttpUri, HttpVersion}</v>
<v>HttpResponse = {http_response, HttpVersion, integer(), HttpString}</v>
<v>HttpHeader = {http_header, integer(), 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=integer()|undefined, Path=HttpString} |
{scheme, Scheme=HttpString, HttpString} | {abs_path, HttpString} | HttpString</v>
<v>HttpVersion = {Major=integer(), Minor=integer()}</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, integer()}</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, integer()}</c></tag>
<item><p>For packet type <c>line</c>, truncate lines longer
than the indicated length.</p>
<p>Option <c>line_length</c> also applies to <c>http*</c>
packet types as an alias for option <c>packet_size</c> in the
case when <c>packet_size</c> itself is not set. This usage is
only intended for backward compatibility.</p>
</item>
</taglist>
<pre>
> <input>erlang:decode_packet(1,&lt;&lt;3,"abcd"&gt;&gt;,[]).</input>
{ok,&lt;&lt;"abc"&gt;&gt;,&lt;&lt;"d"&gt;&gt;}
> <input>erlang:decode_packet(1,&lt;&lt;5,"abcd"&gt;&gt;,[]).</input>
{more,6}</pre>
</desc>
</func>
<func>
<name>delete_module(Module) -> true | undefined</name>
<fsummary>Make the current code for a module old</fsummary>
<type>
<v>Module = atom()</v>
</type>
<desc>
<p>Makes the current code for <c>Module</c> become old code, and
deletes all references for this module from the export table.
Returns <c>undefined</c> if the module does not exist,
otherwise <c>true</c>.</p>
<warning>
<p>This BIF is intended for the code server (see
<seealso marker="kernel:code">code(3)</seealso>) and should not be
used elsewhere.</p>
</warning>
<p>Failure: <c>badarg</c> if there is already an old version of
<c>Module</c>.</p>
</desc>
</func>
<func>
<name>demonitor(MonitorRef) -> true</name>
<fsummary>Stop monitoring</fsummary>
<type>
<v>MonitorRef = reference()</v>
</type>
<desc>
<p>If <c>MonitorRef</c> is a reference which the calling process
obtained by calling
<seealso marker="#monitor/2">monitor/2</seealso>,
this monitoring is turned off. If the monitoring is already
turned off, nothing happens.</p>
<p>Once <c>demonitor(MonitorRef)</c> has returned it is
guaranteed that no <c>{'DOWN', MonitorRef, _, _, _}</c> message
due to the monitor will be placed in the caller's message queue
in the future. A <c>{'DOWN', MonitorRef, _, _, _}</c> message
might have been placed in the caller's 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="#demonitor/2">demonitor(MonitorRef, [flush])</seealso> can be used instead of
<c>demonitor(MonitorRef)</c> if this cleanup is wanted.</p>
<note>
<p>Prior to OTP release R11B (erts version 5.5) <c>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>demonitor(MonitorRef, OptionList) -> boolean()</name>
<fsummary>Stop monitoring</fsummary>
<type>
<v>MonitorRef = reference()</v>
<v>OptionList = [Option]</v>
<v>&nbsp;Option = flush | 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>demonitor(MonitorRef, [])</c> is equivalent to
<seealso marker="#demonitor/1">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 caller's message queue after
monitoring has been stopped.</p>
<p>Calling <c>demonitor(MonitorRef, [flush])</c>
is equivalent to the following, but more efficient:</p>
<code type="none">
demonitor(MonitorRef),
receive
{_, MonitorRef, _, _, _} ->
true
after 0 ->
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 caller's 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="#demonitor/1">demonitor/1</seealso></p>
</desc>
</func>
<func>
<name name="disconnect_node" arity="1"/>
<fsummary>Force the disconnection of a node</fsummary>
<desc>
<p>Forces the disconnection of a node. This will appear to
the node <c><anno>Node</anno></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>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 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>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>erlang:external_size(Term) -> integer() >= 0</name>
<fsummary>Calculate the maximum size for a term encoded in the Erlang
external term format</fsummary>
<type>
<v>Term = term()</v>
</type>
<desc>
<p>Calculates, without doing the encoding, the maximum byte size for
a term encoded in the Erlang external term format. The following
condition applies always:</p>
<p>
<pre>
> <input>Size1 = byte_size(term_to_binary(Term)),</input>
> <input>Size2 = erlang:external_size(Term),</input>
> <input>true = Size1 =&lt; Size2.</input>
true
</pre>
</p>
<p>This is equivalent to a call to: <code>erlang:external_size(Term, [])
</code></p>
</desc>
</func>
<func>
<name>erlang:external_size(Term, [Option]) -> integer() >= 0</name>
<fsummary>Calculate the maximum size for a term encoded in the Erlang
external term format</fsummary>
<type>
<v>Term = term()</v>
<v>Option = {minor_version, Version}</v>
</type>
<desc>
<p>Calculates, without doing the encoding, the maximum byte size for
a term encoded in the Erlang external term format. The following
condition applies always:</p>
<p>
<pre>
> <input>Size1 = byte_size(term_to_binary(Term, Options)),</input>
> <input>Size2 = erlang:external_size(Term, Options),</input>
> <input>true = Size1 =&lt; Size2.</input>
true
</pre>
</p>
<p>The option <c>{minor_version, Version}</c> specifies how floats
are encoded. See
<seealso marker="#term_to_binary/2">term_to_binary/2</seealso> for
a more detailed description.
</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 name="fun_info" arity="1"/>
<fsummary>Information about a fun</fsummary>
<desc>
<p>Returns a list containing information about the fun
<c><anno>Fun</anno></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.
It is calculated from the compiled code for the entire module.</p>
</item>
<tag><c>{uniq, Uniq}</c></tag>
<item>
<p><c>Uniq</c> (an integer) is a unique value for this fun.
Starting in the R15 release, this integer is calculated from
the compiled code for the entire module. Before R15, this
integer was based on only the body of the 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>, <c>env</c>, or <c>type</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="#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) -> boolean()</name>
<fsummary>Check if a function is exported and loaded</fsummary>
<type>
<v>Module = Function = atom()</v>
<v>Arity = arity()</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) -> boolean()</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 name="get_cookie" arity="0"/>
<fsummary>Get the magic cookie of the local node</fsummary>
<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, Location}]</name>
<fsummary>Get the call stack back-trace of the last exception</fsummary>
<type>
<v>Module = Function = atom()</v>
<v>Arity = arity()</v>
<v>Args = [term()]</v>
<v>Location = [{atom(),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,Location}</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><c>Location</c> is a (possibly empty) list of two-tuples that
may indicate the location in the source code of the function.
The first element is an atom that describes the type of
information in the second element. Currently the following
items may occur:</p>
<taglist>
<tag><c>file</c></tag>
<item>
<p>The second element of the tuple is a string (list of
characters) representing the filename of the source file
of the function.</p>
</item>
<tag><c>line</c></tag>
<item>
<p>The second element of the tuple is the line number
(an integer greater than zero) in the source file
where the exception occurred or the function was called.</p>
</item>
</taglist>
<p>See also
<seealso marker="#error/1">erlang:error/1</seealso> and
<seealso marker="#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>The same as
<seealso marker="#halt/2"><c>halt(0, [])</c></seealso>.</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 = integer() >= 0 | string() | abort</v>
</type>
<desc>
<p>The same as
<seealso marker="#halt/2"><c>halt(Status, [])</c></seealso>.</p>
<pre>
> <input>halt(17).</input>
os_prompt% <input>echo $?</input>
17
os_prompt% </pre>
</desc>
</func>
<func>
<name>halt(Status, Options)</name>
<fsummary>Halt the Erlang runtime system</fsummary>
<type>
<v>Status = integer() >= 0 | string() | abort</v>
<v>Options = [Option]</v>
<v>Option = {flush,boolean()} | term()</v>
</type>
<desc>
<p><c>Status</c> must be a non-negative integer, a string,
or the atom <c>abort</c>.
Halts the Erlang runtime system. Has no return value.
Depending on <c>Status</c>:
</p>
<taglist>
<tag>integer()</tag>
<item>The runtime system exits with the integer value <c>Status</c>
as status code to the calling environment (operating system).
</item>
<tag>string()</tag>
<item>An erlang crash dump is produced with <c>Status</c> as slogan,
and then the runtime system exits with status code <c>1</c>.
</item>
<tag><c>abort</c></tag>
<item>
The runtime system aborts producing a core dump, if that is
enabled in the operating system.
</item>
</taglist>
<p>Note that on many platforms, only the status codes 0-255 are
supported by the operating system.
</p>
<p>For integer <c>Status</c> the Erlang runtime system closes all ports
and allows async threads to finish their operations before exiting.
To exit without such flushing use
<c>Option</c> as <c>{flush,false}</c>.
</p>
<p>For statuses <c>string()</c> and <c>abort</c> the <c>flush</c>
option is ignored and flushing is <em>not</em> done.
</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 = integer()</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 name="integer_to_list" arity="2"/>
<fsummary>Text representation of an integer</fsummary>
<desc>
<p>Returns a string which corresponds to the text
representation of <c><anno>Integer</anno></c> in base <c><anno>Base</anno></c>.</p>
<pre>
> <input>integer_to_list(1023, 16).</input>
"3FF"</pre>
</desc>
</func>
<func>
<name>iolist_to_binary(IoListOrBinary) -> binary()</name>
<fsummary>Convert an iolist to a binary</fsummary>
<type>
<v>IoListOrBinary = iolist() | binary()</v>
</type>
<desc>
<p>Returns a binary which is made from the integers and
binaries in <c>IoListOrBinary</c>.</p>
<pre>
> <input>Bin1 = &lt;&lt;1,2,3&gt;&gt;.</input>
&lt;&lt;1,2,3&gt;&gt;
> <input>Bin2 = &lt;&lt;4,5&gt;&gt;.</input>
&lt;&lt;4,5&gt;&gt;
> <input>Bin3 = &lt;&lt;6&gt;&gt;.</input>
&lt;&lt;6&gt;&gt;
> <input>iolist_to_binary([Bin1,1,[2,3,Bin2],4|Bin3]).</input>
&lt;&lt;1,2,3,1,2,3,4,5,4,6&gt;&gt;</pre>
</desc>
</func>
<func>
<name>iolist_size(Item) -> integer() >= 0</name>
<fsummary>Size of an iolist</fsummary>
<type>
<v>Item = iolist() | binary()</v>
</type>
<desc>
<p>Returns an integer which is the size in bytes
of the binary that would be the result of
<c>iolist_to_binary(Item)</c>.</p>
<pre>
> <input>iolist_size([1,2|&lt;&lt;3,4>>]).</input>
4</pre>
</desc>
</func>
<func>
<name>is_alive() -> boolean()</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) -> boolean()</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) -> boolean()</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) -> boolean()</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) -> boolean()</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) -> boolean()</name>
<fsummary>Check if a function is a BIF implemented in C</fsummary>
<type>
<v>Module = Function = atom()</v>
<v>Arity = arity()</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) -> boolean()</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) -> boolean()</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) -> boolean()</name>
<fsummary>Check whether a term is a fun with a given arity</fsummary>
<type>
<v>Term = term()</v>
<v>Arity = arity()</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) -> boolean()</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) -> boolean()</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) -> boolean()</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) -> boolean()</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) -> boolean()</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) -> boolean()</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) -> boolean()</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) -> boolean()</name>
<fsummary>Check whether a term appears to be a record</fsummary>
<type>
<v>Term = term()</v>
<v>RecordTag = atom()</v>
<v>Size = integer()</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) -> boolean()</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) -> boolean()</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) -> integer() >= 0</name>
<fsummary>Length of a list</fsummary>
<type>
<v>List = [term()]</v>
</type>
<desc>
<p>Returns the length of <c>List</c>.</p>
<pre>
> <input>length([1,2,3,4,5,6,7,8,9]).</input>
9</pre>
<p>Allowed in guard tests.</p>
</desc>
</func>
<func>
<name>link(Pid) -> true</name>
<fsummary>Create a link to another process (or port)</fsummary>
<type>
<v>Pid = pid() | port()</v>
</type>
<desc>
<p>Creates a link between the calling process and another
process (or port) <c>Pid</c>, if there is not such a link
already. If a process attempts to create a link to itself,
nothing is done. Returns <c>true</c>.</p>
<p>If <c>Pid</c> does not exist, the behavior of the BIF depends
on if the calling process is trapping exits or not (see
<seealso marker="#process_flag/2">process_flag/2</seealso>):</p>
<list type="bulleted">
<item>If the calling process is not trapping exits, and
checking <c>Pid</c> is cheap -- that is, if <c>Pid</c> is
local -- <c>link/1</c> fails with reason <c>noproc</c>.</item>
<item>Otherwise, if the calling process is trapping exits,
and/or <c>Pid</c> is remote, <c>link/1</c> returns
<c>true</c>, but an exit signal with reason <c>noproc</c>
is sent to the calling process.</item>
</list>
</desc>
</func>
<func>
<name>list_to_atom(String) -> atom()</name>
<fsummary>Convert from text representation to an atom</fsummary>
<type>
<v>String = string()</v>
</type>
<desc>
<p>Returns the atom whose text representation is <c>String</c>.</p>
<pre>
> <input>list_to_atom("Erlang").</input>
'Erlang'</pre>
</desc>
</func>
<func>
<name>list_to_binary(IoList) -> binary()</name>
<fsummary>Convert a list to a binary</fsummary>
<type>
<v>IoList = iolist()</v>
</type>
<desc>
<p>Returns a binary which is made from the integers and
binaries in <c>IoList</c>.</p>
<pre>
> <input>Bin1 = &lt;&lt;1,2,3&gt;&gt;.</input>
&lt;&lt;1,2,3&gt;&gt;
> <input>Bin2 = &lt;&lt;4,5&gt;&gt;.</input>
&lt;&lt;4,5&gt;&gt;
> <input>Bin3 = &lt;&lt;6&gt;&gt;.</input>
&lt;&lt;6&gt;&gt;
> <input>list_to_binary([Bin1,1,[2,3,Bin2],4|Bin3]).</input>
&lt;&lt;1,2,3,1,2,3,4,5,4,6&gt;&gt;</pre>
</desc>
</func>
<func>
<name>list_to_bitstring(BitstringList) -> bitstring()</name>
<fsummary>Convert a list to a bitstring</fsummary>
<type>
<v>BitstringList = [BitstringList | bitstring() | char()]</v>
</type>
<desc>
<p>Returns a bitstring which is made from the integers and
bitstrings in <c>BitstringList</c>. (The last tail in <c>BitstringList</c>
is allowed to be a bitstring.)</p>
<pre>
> <input>Bin1 = &lt;&lt;1,2,3&gt;&gt;.</input>
&lt;&lt;1,2,3&gt;&gt;
> <input>Bin2 = &lt;&lt;4,5&gt;&gt;.</input>
&lt;&lt;4,5&gt;&gt;
> <input>Bin3 = &lt;&lt;6,7:4,&gt;&gt;.</input>
&lt;&lt;6&gt;&gt;
> <input>list_to_binary([Bin1,1,[2,3,Bin2],4|Bin3]).</input>
&lt;&lt;1,2,3,1,2,3,4,5,4,6,7:46&gt;&gt;</pre>
</desc>
</func>
<func>
<name>list_to_existing_atom(String) -> atom()</name>
<fsummary>Convert from text representation to an atom</fsummary>
<type>
<v>String = string()</v>
</type>
<desc>
<p>Returns the atom whose text representation is <c>String</c>,
but only if there already exists such atom.</p>
<p>Failure: <c>badarg</c> if there does not already exist an atom
whose text representation is <c>String</c>.</p>
</desc>
</func>
<func>
<name>list_to_float(String) -> float()</name>
<fsummary>Convert from text representation to a float</fsummary>
<type>
<v>String = string()</v>
</type>
<desc>
<p>Returns the float whose text representation is <c>String</c>.</p>
<pre>
> <input>list_to_float("2.2017764e+0").</input>
2.2017764</pre>
<p>Failure: <c>badarg</c> if <c>String</c> contains a bad
representation of a float.</p>
</desc>
</func>
<func>
<name>list_to_integer(String) -> integer()</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 name="list_to_integer" arity="2"/>
<fsummary>Convert from text representation to an integer</fsummary>
<desc>
<p>Returns an integer whose text representation in base
<c><anno>Base</anno></c> is <c><anno>String</anno></c>.</p>
<pre>
> <input>list_to_integer("3FF", 16).</input>
1023</pre>
<p>Failure: <c>badarg</c> if <c><anno>String</anno></c> contains a bad
representation of an integer.</p>
</desc>
</func>
<func>
<name>list_to_pid(String) -> pid()</name>
<fsummary>Convert from text representation to a pid</fsummary>
<type>
<v>String = string()</v>
</type>
<desc>
<p>Returns a pid whose text representation is <c>String</c>.</p>
<warning>
<p>This BIF is intended for debugging and for use in
the Erlang operating system. It should not be used in
application programs.</p>
</warning>
<pre>
> <input>list_to_pid("&lt;0.4.1>").</input>
&lt;0.4.1></pre>
<p>Failure: <c>badarg</c> if <c>String</c> contains a bad
representation of a pid.</p>
</desc>
</func>
<func>
<name>list_to_tuple(List) -> tuple()</name>
<fsummary>Convert a list to a tuple</fsummary>
<type>
<v>List = [term()]</v>
</type>
<desc>
<p>Returns a tuple which corresponds to <c>List</c>. <c>List</c>
can contain any Erlang terms.</p>
<pre>
> <input>list_to_tuple([share, ['Ericsson_B', 163]]).</input>
{share, ['Ericsson_B', 163]}</pre>
</desc>
</func>
<func>
<name>load_module(Module, Binary) -> {module, Module} | {error, Reason}</name>
<fsummary>Load object code for a module</fsummary>
<type>
<v>Module = atom()</v>
<v>Binary = binary()</v>
<v>Reason = badfile | not_purged | badfile</v>
</type>
<desc>
<p>If <c>Binary</c> contains the object code for the module
<c>Module</c>, this BIF loads that object code. Also, if
the code for the module <c>Module</c> already exists, all
export references are replaced so they point to the newly
loaded code. The previously loaded code is kept in the system
as old code, as there may still be processes which are
executing that code. It returns either
<c>{module, Module}</c>, or <c>{error, Reason}</c> if loading
fails. <c>Reason</c> is one of the following:</p>
<taglist>
<tag><c>badfile</c></tag>
<item>
<p>The object code in <c>Binary</c> has an incorrect format.</p>
</item>
<tag><c>not_purged</c></tag>
<item>
<p><c>Binary</c> contains a module which cannot be loaded
because old code for this module already exists.</p>
</item>
<tag><c>badfile</c></tag>
<item>
<p>The object code contains code for another module than
<c>Module</c></p>
</item>
</taglist>
<warning>
<p>This BIF is intended for the code server (see
<seealso marker="kernel:code">code(3)</seealso>) and should not be
used elsewhere.</p>
</warning>
</desc>
</func>
<func>
<name>erlang:load_nif(Path, LoadInfo) -> ok | {error, {Reason, Text}}</name>
<fsummary>Load NIF library</fsummary>
<type>
<v>Path = string()</v>
<v>LoadInfo = term()</v>
<v>Reason = load_failed | bad_lib | load | reload |
upgrade | old_code</v>
<v>Text = string()</v>
</type>
<desc>
<note>
<p>In releases older than OTP R14B, NIFs were an
experimental feature. Versions of OTP older than R14B might
have different and possibly incompatible NIF semantics and
interfaces. For example, in R13B03 the return value on
failure was
<c>{error,Reason,Text}</c>.</p>
</note>
<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-dependent file extension (.so for Unix and .dll 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() -> DateTime</name>
<fsummary>Current local date and time</fsummary>
<type>
<v>DateTime = <seealso marker="calendar#type-datetime">calendar:datetime()</seealso></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 name="localtime_to_universaltime" arity="1"/>
<fsummary>Convert from local to Universal Time Coordinated (UTC) date and time</fsummary>
<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>{<anno>Date1</anno>, <anno>Time1</anno>}</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 = <seealso marker="calendar#type-date">calendar:date()</seealso></v>
<v>Time1 = Time2 = <seealso marker="calendar#type-time">calendar:time()</seealso></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() -> reference()</name>
<fsummary>Return an almost unique reference</fsummary>
<desc>
<p>Returns an almost unique reference.</p>
<p>The returned reference will re-occur after approximately 2^82
calls; therefore it is unique enough for practical purposes.</p>
<pre>
> <input>make_ref().</input>
#Ref&lt;0.0.0.135></pre>
</desc>
</func>
<func>
<name>erlang:make_tuple(Arity, InitialValue) -> tuple()</name>
<fsummary>Create a new tuple of a given arity</fsummary>
<type>
<v>Arity = arity()</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 = arity()</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 name="max" arity="2"/>
<fsummary>Return the largest of two term</fsummary>
<desc>
<p>Return the largest of <c><anno>Term1</anno></c> and <c><anno>Term2</anno></c>;
if the terms compare equal, <c><anno>Term1</anno></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>
<tag><c>low</c></tag>
<item>
<p>Only on 64-bit halfword emulator.</p>
<p>The total amount of memory allocated in low memory areas
that are restricted to less than 4 Gb even though
the system may have more physical memory.</p>
<p>May be removed in future releases of halfword emulator.</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">
total = processes + system
processes = processes_used + ProcessesNotUsed
system = atom + binary + code + ets + OtherSystem
atom = atom_used + AtomNotUsed
RealTotal = processes + RealSystem
RealSystem = 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="#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="#memory/0">erlang:memory/0</seealso>.</p>
</desc>
</func>
<func>
<name name="min" arity="2"/>
<fsummary>Return the smallest of two term</fsummary>
<desc>
<p>Return the smallest of <c><anno>Term1</anno></c> and <c><anno>Term2</anno></c>;
if the terms compare equal, <c><anno>Term1</anno></c> will be returned.</p>
</desc>
</func>
<func>
<name>module_loaded(Module) -> boolean()</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>monitor(Type, Item) -> MonitorRef</name>
<fsummary>Start monitoring</fsummary>
<type>
<v>Type = process</v>
<v>Item = pid() | {RegName, Node} | RegName</v>
<v>&nbsp;RegName = atom()</v>
<v>&nbsp;Node = node()</v>
<v>MonitorRef = reference()</v>
</type>
<desc>
<p>The calling process starts monitoring <c>Item</c> which is
an object of type <c>Type</c>.</p>
<p>Currently only processes can be monitored, i.e. the only
allowed <c>Type</c> is <c>process</c>, but other types may be
allowed in the future.</p>
<p><c>Item</c> can be:</p>
<taglist>
<tag><c>pid()</c></tag>
<item>
<p>The pid of the process to monitor.</p>
</item>
<tag><c>{RegName, Node}</c></tag>
<item>
<p>A tuple consisting of a registered name of a process and
a node name. The process residing on the node <c>Node</c>
with the registered name <c>RegName</c> will be monitored.</p>
</item>
<tag><c>RegName</c></tag>
<item>
<p>The process locally registered as <c>RegName</c> will be
monitored.</p>
</item>
</taglist>
<note>
<p>When a process is monitored by registered name, the process
that has the registered name at the time when
<c>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>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="#demonitor/1">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>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 = boolean()</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 = boolean()</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>erlang:nif_error(Reason)</name>
<fsummary>Stop execution with a given reason</fsummary>
<type>
<v>Reason = term()</v>
</type>
<desc>
<p>Works exactly like
<seealso marker="#error/1">erlang:error/1</seealso>,
but Dialyzer thinks that this BIF will return an arbitrary term.
When used in a stub function for a NIF to generate an
exception when the NIF library is not loaded, Dialyzer
will not generate false warnings.</p>
</desc>
</func>
<func>
<name>erlang:nif_error(Reason, Args)</name>
<fsummary>Stop execution with a given reason</fsummary>
<type>
<v>Reason = term()</v>
<v>Args = [term()]</v>
</type>
<desc>
<p>Works exactly like
<seealso marker="#error/2">erlang:error/2</seealso>,
but Dialyzer thinks that this BIF will return an arbitrary term.
When used in a stub function for a NIF to generate an
exception when the NIF library is not loaded, Dialyzer
will not generate false warnings.</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() | reference()</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 name="nodes" arity="0"/>
<fsummary>All visible nodes in the system</fsummary>
<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() -> timestamp()</name>
<type>
<v>timestamp() = {MegaSecs, Secs, MicroSecs}</v>
<v>MegaSecs = Secs = MicroSecs = integer() >= 0</v>
</type>
<fsummary>Elapsed time since 00:00 GMT</fsummary>
<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,
and if it is called in a tight loop on a fast machine
the time of the node can become skewed.</p>
<p>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>
<p>If you do not need the return value to be unique and
monotonically increasing, use
<seealso marker="kernel:os#timestamp/0">os:timestamp/0</seealso>
instead to avoid some overhead.</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, FileName} | {fd, In, Out}</v>
<v>&nbsp;Command = string()</v>
<v>&nbsp;FileName = [ FileNameChar ] | binary()</v>
<v>&nbsp;FileNameChar = integer() (1..255 or any Unicode codepoint, see description)</v>
<v>&nbsp;In = Out = integer()</v>
<v>PortSettings = [Opt]</v>
<v>&nbsp;Opt = {packet, N} | stream | {line, L} | {cd, Dir} | {env, Env} | {args, [ ArgString ]} | {arg0, ArgString} | exit_status | use_stdio | nouse_stdio | stderr_to_stdout | in | out | binary | eof</v>
<v>&nbsp;&nbsp;N = 1 | 2 | 4</v>
<v>&nbsp;&nbsp;L = integer()</v>
<v>&nbsp;&nbsp;Dir = string()</v>
<v>&nbsp;&nbsp;ArgString = [ FileNameChar ] | binary()</v>
<v>&nbsp;&nbsp;Env = [{Name, Val}]</v>
<v>&nbsp;&nbsp;&nbsp;Name = string()</v>
<v>&nbsp;&nbsp;&nbsp;Val = string() | false</v>
</type>
<desc>
<p>Returns a port identifier as the result of opening a
new Erlang port. A port can be seen as an external Erlang
process. <c>PortName</c> is one of the following:</p>
<taglist>
<tag><c>{spawn, Command}</c></tag>
<item>
<p>Starts an external program. <c>Command</c> is the name
of the external program which will be run. <c>Command</c>
runs outside the Erlang work space unless an Erlang
driver with the name <c>Command</c> is found. If found,
that driver will be started. A driver runs in the Erlang
workspace, which means that it is linked with the Erlang
runtime system.</p>
<p>When starting external programs on Solaris, the system
call <c>vfork</c> is used in preference to <c>fork</c>
for performance reasons, although it has a history of
being less robust. If there are problems with using
<c>vfork</c>, setting the environment variable
<c>ERL_NO_VFORK</c> to any value will cause <c>fork</c>
to be used instead.</p>
<p>For external programs, the <c>PATH</c> is searched
(or an equivalent method is used to find programs,
depending on operating system). This is done by invoking
the shell on 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 its 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>The name of the executable as well as the arguments
given in <c>args</c> and <c>arg0</c> is subject to
Unicode file name translation if the system is running
in Unicode file name mode. To avoid
translation or force i.e. UTF-8, supply the executable
and/or arguments as a binary in the correct
encoding. See the <seealso
marker="kernel:file">file</seealso> module, the
<seealso marker="kernel:file#native_name_encoding/0">
file:native_name_encoding/0</seealso> function and the
<seealso marker="stdlib:unicode_usage">stdlib users guide
</seealso> for details.</p>
<note><p>The characters in the name (if given as a list)
can only be &gt; 255 if the Erlang VM is started in
Unicode file name translation mode, otherwise the name
of the executable is limited to the ISO-latin-1
character set.</p></note>
<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.</p>
<p>If Unicode filename encoding is in effect (see the <seealso
marker="erts:erl#file_name_encoding">erl manual
page</seealso>), the strings (both <c>Name</c> and
<c>Value</c>) may contain characters with codepoints > 255.</p>
</item>
<tag><c>{args, [ string() ]}</c></tag>
<item>
<p>This option is only valid for <c>{spawn_executable, Command}</c>
and specifies arguments to the executable. Each argument
is given as a separate string and (on Unix) eventually
ends up as one element each in the argument vector. On
other platforms, similar behavior is mimicked.</p>
<p>The arguments are not expanded by the shell prior to
being supplied to the executable, most notably this
means that file wildcard expansion will not happen. Use
<seealso
marker="stdlib:filelib#wildcard/1">filelib:wildcard/1</seealso>
to expand wildcards for the arguments. Note that even if
the program is a Unix shell script, meaning that the
shell will ultimately be invoked, wildcard expansion
will not happen and the script will be provided with the
untouched arguments. On Windows&reg;, wildcard expansion
is always up to the program itself, why this isn't an
issue.</p>
<p>Note also that the actual executable name (a.k.a. <c>argv[0]</c>)
should not be given in this list. The proper executable name will
automatically be used as argv[0] where applicable.</p>
<p>When the Erlang VM is running in Unicode file name
mode, the arguments can contain any Unicode characters and
will be translated into whatever is appropriate on the
underlying OS, which means UTF-8 for all platforms except
Windows, which has other (more transparent) ways of
dealing with Unicode arguments to programs. To avoid
Unicode translation of arguments, they can be supplied as
binaries in whatever encoding is deemed appropriate.</p>
<note><p>The characters in the arguments (if given as a
list of characters) can only be &gt; 255 if the Erlang
VM is started in Unicode file name mode,
otherwise the arguments are limited to the
ISO-latin-1 character set.</p></note>
<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>
<p>The unicode file name translation rules of the
<c>args</c> option apply to this option as well.</p>
</item>
<tag><c>exit_status</c></tag>
<item>
<p>This is only valid for <c>{spawn, Command}</c> where
<c>Command</c> refers to an external program, and for
<c>{spawn_executable, Command}</c>.</p>
<p>When the external process connected to the port exits, a
message of the form <c>{Port,{exit_status,Status}}</c> is
sent to the connected process, where <c>Status</c> is the
exit status of the external process. If the program
aborts, on Unix the same convention is used as the shells
do (i.e., 128+signal).</p>
<p>If the <c>eof</c> option has been given as well,
the <c>eof</c> message and the <c>exit_status</c> message
appear in an unspecified order.</p>
<p>If the port program closes its stdout without exiting,
the <c>exit_status</c> option will not work.</p>
</item>
<tag><c>use_stdio</c></tag>
<item>
<p>This is only valid for <c>{spawn, Command}</c> and
<c>{spawn_executable, Command}</c>. It
allows the standard input and output (file descriptors 0
and 1) of the spawned (UNIX) process for communication
with Erlang.</p>
</item>
<tag><c>nouse_stdio</c></tag>
<item>
<p>The opposite of <c>use_stdio</c>. Uses file descriptors
3 and 4 for communication with Erlang.</p>
</item>
<tag><c>stderr_to_stdout</c></tag>
<item>
<p>Affects ports to external programs. The executed program
gets its standard error file redirected to its standard
output file. <c>stderr_to_stdout</c> and
<c>nouse_stdio</c> are mutually exclusive.</p>
</item>
<tag><c>overlapped_io</c></tag>
<item>
<p>Affects ports to external programs on Windows&reg; only.
The standard input and standard output handles of the port program
will, if this option is supplied, be opened with the flag
FILE_FLAG_OVERLAPPED, so that the port program can (and has to) do
overlapped I/O on its 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>port_command(Port, Data, OptionList) -> boolean()</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>
<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 = integer()</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 = integer()</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>
<tag><c>{os_pid, Integer | undefined}</c></tag>
<item>
<p><c>Integer</c> is the process identifier (or equivalent) of an OS process created with <c>open_port({spawn | spawn_executable, Command}, Options)</c>. If the port is not the result of spawning an OS process, the value is <c>undefined</c>.</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="#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(min_bin_vheap_size, MinBinVHeapSize)</c></tag>
<item>
<p>This changes the minimum binary virtual heap size for the calling
process.</p>
</item>
<tag><marker id="process_flag_priority"><c>process_flag(priority, Level)</c></marker></tag>
<item>
<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