By convention, most built-in functions (BIFs) are seen as being
in the module erlang
. A number of the BIFs are viewed more
or less as part of the Erlang programming language and are
auto-imported. Thus, it is not necessary to specify
the module name and both the calls atom_to_list(Erlang)
and
erlang:atom_to_list(Erlang)
are identical.
In the text, auto-imported BIFs are listed without module prefix. BIFs listed with module prefix are not auto-imported.
BIFs may fail for a variety of reasons. All BIFs fail with
reason badarg
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.
Some BIFs may be used in guard tests, these are marked with "Allowed in guard tests".
Some BIFs, such as list_to_binary_1,
take I/O lists as documents (written as iolist()
in type
descriptions). An I/O list is a deep list of binaries,
integers in the range 0 through 255, and other I/O lists. In an I/O list,
a binary is allowed as the tail of a list.
Returns an integer or float which is the arithmetical
absolute value of the argument Number
(integer or
float).
> abs(-3.33). 3.33000 > abs(-3). 3
Allowed in guard tests.
Failure: badarg
if Number
is not a number.
erlang:append_element(Tuple, Term)
Returns a new tuple which has one element more than
Tuple
, and contains the elements in Tuple
followed by Term
as the last element. Semantically
equivalent to
list_to_tuple(tuple_to_list(Tuple ++ [Term])
,
but much faster.
Failure: badarg
if Tuple
is not a tuple.
Types:
Fun = fun()
ArgumentList = list()
Call a fun, passing the elements in ArgumentList
as
arguments.
Note: If the number of elements in the arguments are known at
compile-time, the call is better written as
Fun(Arg1, Arg2, ... ArgN)
.
Fun
can also be given as {Module,Function}, which is
equivalent to apply(Module, Function, ArgumentList)
.
This usage is deprecated and will stop
working in a future release of Erlang/OTP.
apply(Module, Function, ArgumentList)
Returns the result of applying Function
in
Module
to ArgumentList
. The applied function
must have been exported from Module
. The arity of the
function is the length of ArgumentList
.
> apply(lists, reverse, [[a, b, c]]). [c,b,a]
apply
can be used to evaluate BIFs by using
the module name erlang
.
> apply(erlang, atom_to_list, ['Erlang']). "Erlang"
Note: If the number of arguments are known at compile-time,
the call is better written as
Module:Function(Arg1, Arg2, ... ArgN)
.
Failure: error_handler:undefined_function/3
is called
if Module
has not exported Function/Arity
. The
error handler can be redefined (see the BIF
process_flag/2
). If the error_handler
is
undefined, or if the user has redefined the default
error_handler
so the replacement module is undefined,
an error with the reason undef
will be generated.
Returns a list of integers (Latin-1 codes), which
corresponds to the text representation of the argument
Atom
.
> atom_to_list('Erlang'). "Erlang"
Failure: badarg
if Atom
is not an atom.
Returns a list of integers which correspond to the bytes of
Binary
.
binary_to_list(Binary, Start, Stop)
As binary_to_list/1
, but it only returns the list from
position Start
to position Stop
. Start
and Stop
are integers. Positions in the binary are
numbered starting from 1.
Returns an Erlang term which is the result of decoding
the binary Binary
. Binary
is encoded in
the Erlang external binary representation.
See term_to_binary/1
.
erlang:bump_reductions(Reductions)
This implementation-dependent function increments the reduction counter for the current 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 1000.
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. If you think that you must use it, encapsulate it your own wrapper module, and/or wrap it in a catch. |
cancel_timer(Ref)
cancels a timer, where Ref
was returned by either send_after/3
or
start_timer/3
. If the timer was there to be removed,
cancel_timer/1
returns the time in ms left until
the timer would have expired, otherwise false
(which
means that Ref
was never a timer, or that it had
already been cancelled, or that it had already delivered its
message).
Note: Usually, cancelling a timer does not guarantee that the message has not already been delivered to the message queue. However, in the special case of a process P cancelling a timer which would have sent a message to P itself, attempting to read the timeout message from the queue is guaranteed to remove the timeout in that situation:
cancel_timer(Ref) -> receive {timeout, Ref, _} -> ok after 0 -> ok end
Failure: badarg
if Ref
is not a reference.
check_process_code(Pid, Module)
Returns true
if the process Pid
is executing an
old version of Module
, if the current call of
the process executes code for an old version of the module,
if the process has references to an old version of the module,
or if the process contains funs that references the old
version of the module. Otherwise, it returns false
.
> check_process_code(Pid, lists). false
Failure: badarg
if Pid
is not a pid or
Module
is not an atom.
Don't use; use list_to_binary_1 instead.
Returns the current date as {Year, Month, Day}
> date(). {1995, 2, 19}
Makes the current version of the code of Module
to
the old version and deletes all export references of
Module
. Returns undefined
if the module does not
exist, otherwise true
.
> delete_module(test). true
Failure: badarg
if there is already an old version of
the module (see purge_module/1
).
This BIF is intended for code server (see |
If Ref
is a reference which the current process
obtained by calling
erlang:monitor/2,
the monitoring is turned off. No action is performed if
the monitoring already is turned of before the call. Returns
true
.
After the call to erlang:monitor/2
the monitoring
process will not get any new 'DOWN'
message from this
monitor into the receive queue.
It is an error if Ref
refers to a monitoring started
by another process. Not all such cases are cheap to check; if
checking is cheap, the call fails with badarg
(for
example if Ref
is a remote reference).
Forces the disconnection of a node. This will appear to
the node Node
as if the current node has crashed. This
BIF is mainly used in the Erlang network authentication
protocols. Returns true
if disconnection succeeds,
otherwise false
.
Failure: badarg
if Node
is not an atom.
Prints a text representation of Term
on the standard
output.
This BIF is intended for debugging only. |
Returns the N
th element (numbering from 1) of
Tuple
.
> element(2, {a, b, c}). b
Allowed in guard tests.
Failure: badarg
if N
<1
, or
N
>size(Tuple)
, or if Tuple
is not a
tuple.
Returns the process dictionary and deletes it.
> put(key1, {1, 2, 3}), put(key2, [a, b, c]), erase(). [{key1,{1,2,3}},{key2,[a,b,c]}]
Returns the value associated with Key
and deletes it
from the process dictionary. Returns undefined
if no
value is associated with Key
. Key
can be any
Erlang term.
> put(key1, {merry, lambs, are, playing}), X = erase(key1), {X, erase(key1)}. {{merry,lambs,are,playing},undefined}
Stops the execution of the current process with the reason
Reason
, where Reason
is any term. The actual
EXIT reason will be {Reason, Where}
, where Where
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.
Stops the execution of the current process with the reason
Reason
, where Reason
is any term. The actual
EXIT reason will be {Reason, Where}
, where Where
is a list of the functions most recently called (the current
function first). Args
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 Where
term. Since evaluating this function causes
the process to terminate, it has no return value.
Stops the execution of the current process with the reason
Reason
. Can be caught. Reason
is any Erlang
term. Since evaluating this function causes the process to
terminate, it has no return value.
> exit(foobar). ** exited: foobar ** > catch exit(foobar). {'EXIT', foobar}
Sends an EXIT signal with reason Reason
to
the process Pid
. Returns true
.
> exit(Pid, goodbye). true
The above is not necessarily the same as: Pid ! {'EXIT', self(), goodbye} |
The above two alternatives are the same if the process with
the process identity Pid
is trapping exits. However,
if Pid
is not trapping exits, Pid
itself will
exit with reason Reason
.
If the reason is the atom kill
, that is if
exit(Pid, kill)
is called, an untrappable EXIT signal
is sent to Pid
which will unconditionally exit with
reason killed
.
Returns true
.
Failure: badarg
if Pid
is not a pid.
Stops the execution of the current process with the reason
Reason
. This an old equivalent to
erlang:error(Reason).
Stops the execution of the current process with the reason
Reason
. This an old equivalent to
erlang:error(Reason, Args)
.
Returns a float by converting Number
to a float.
> float(55). 55.0000
|
Failure: badarg
if Number
is not a number.
Returns a list of integers (ASCII codes) which corresponds to
Float
.
> float_to_list(7.0). "7.00000000000000000000e+00"
Failure: badarg
if Float
is not a float.
Returns a list containing information about the fun
Fun
. Each element of the list is a tuple.
You should not depend on the order of the tuples,
as it might change and more tuples can be added in a future
release.
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. |
There are two types of funs with slightly different semantics.
A fun created by fun M:F/A
is called an external
fun. Calling it will always call the function F
with
arity A
in the latest code for module M
.
Note that module M
doesn't even need to be loaded when
the fun fun M:F/A
is created.
All other funs are called local. 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).
The following elements will always be present in the list for both local and external funs.
{type,Type}
Type
is either local
or external
.
{module,Module}
Module
(an atom) is the module name.
If Fun
is a local fun, Module
is the module
in which the fun is defined.
Fun
is an external fun, Module
is the module
that the fun refers to.
{name,Name}
Name
(an atom) is a function name.
Fun
is a local fun, Name
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, []
will be returned instead of an atom.
Fun
is an external fun, Name
is the name
of the exported function that the fun refers to.
{arity,Arity}
Arity
is the number of arguments that the fun should
be called with.
{env,Env}
Env
(a list) is the environment or free variables
for the fun. (For external funs, the returned list is always empty.)
The following elements will only be present in the list if
Fun
is local.
{pid,Pid}
Pid
is the pid of the process that originally
created the fun.
{index,Index}
Index
(an integer) is an index into the module's fun
table.
{new_index,Index}
Index
(an integer) is an index into the module's fun
table.
{new_uniq,Uniq}
Uniq
(a binary) is a unique value for this fun.
{uniq,Uniq}
Uniq
(an integer) is a unique value for this fun.
Returns information about Fun
as specified by
Item
, in the form {Item,Info}
.
For any fun, Item
can be any of the atoms module
,
name
, arity
, or env
.
For a local fun (a fun not created using
fun M:F/A
), any of the Item
s
index
, new_index
, new_uniq
,
uniq
, and pid
returns meaningful information;
for an external fun the value returned will be undefined
.
See erlang:fun_info/1.
Returns a textual representation of the fun Fun
.
erlang:function_exported(Module, Function, Arity)
Returns true
if the module Module
is loaded
and contains an exported function Function/Arity
;
otherwise false
.
Returns false
for any BIF (functions implemented in C
rather than in Erlang).
This function is retained mainly for backwards compatibility. It is not clear why you really would want to use it.
Forces an immediate garbage collection of the currently executing process. You should not use this function unless you have noticed or have good reasons to suspect that the spontaneous garbage collection will occur too late or not at all. Improper use may seriously degrade system performance.
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
erlang:garbage_collect()
, it was sufficient to make
any function call.
Works like erlang:garbage_collect() but on any process.
The same caveats apply. Returns false
if Pid
refers to a dead process; true
otherwise.
Returns the process dictionary as a list of
{Key, Value}
tuples.
> put(key1, merry), put(key2, lambs), put(key3, {are, playing}), get(). [{key1,merry},{key2,lambs},{key3,{are,playing}}]
Returns the value associated with Key
in the process
dictionary, or undefined
if there is no such key.
Key
is any term.
> put(key1, merry), put(key2, lambs), put({any, [valid, term]}, {are, playing}), get({any, [valid, term]}). {are,playing}
Returns the magic cookie of the current node, if the node is
alive; otherwise the atom nocookie
.
Returns a list of keys which corresponds to Value
in
the process dictionary.
> put(mary, {1, 2}), put(had, {1, 2}), put(a, {1, 2}), put(little, {1, 2}), put(dog, {1, 3}), put(lamb, {1, 2}), get_keys({1, 2}). [mary,had,a,little,lamb]
Get the stacktrace of the last exception in the
running process as a list of
{Module,Function,Arity}
tuples. The Arity
field in the first tuple may be the argument list of
that function instead of an arity integer, depending
on the exception.
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 []
.
The stacktrace is the same data you get from the
catch
operator, for example:
{'EXIT',{badarg,Stacktrace}} = catch abs(x)
See also erlang:error/1 and erlang:error/2 .
Returns the pid Pid
of the group leader for
the process which evaluates the function.
Every process is a member of some process group and all
groups have a group leader. When a new process
is spawned, the group leader of the spawned process is the
same as that of the process which spawned it. Initially, at
system start-up, init
is both its own group leader and
the group leader of all processes.
Sets the group leader of Pid
to Leader
.
Typically, this is used when a processes started from a
certain shell should have another group leader than
init
. The process Leader
is normally a process
with an I/O protocol. All I/O from this group of processes
are thus channeled to the same place.
Halts the Erlang runtime system and indicates normal exit to the calling environment. Has no return value.
> halt(). os_prompt%
Status
must be a non-negative integer, or a string.
Halts the Erlang runtime system. Has no return value.
If Status
is an integer, it is returned as an exit
status of Erlang to the calling environment.
If Status
is a string, produces an Erlang crash dump
with String
as slogan, and then exits with a non-zero
status code.
Note that on many platforms, only the status codes 0-255 are supported by the operating system.
Returns a hash value for Term
within the range
1..Range
. The allowed range is 1..2^27-1.
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
|
Returns the first element of List
.
> hd([1,2,3,4,5]). 1
Allowed in guard tests.
Failure: badarg
if List
is the empty list [],
or is not a list.
erlang:hibernate(Module, Function, ArgumentList)
erlang:hibernate/3
gives a way to put a 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.
The process will be awaken when a message is sent to it, and
control will resume in Module:Function
with
the arguments given by ArgumentList
with the call stack
emptied, meaning that the process will terminate when that
function returns. Thus erlang:hibernate/3
will never
return to its caller.
If the process has any message in its message queue, the process will be awaken immediately in the same way as described above.
In more technical terms, what erlang:hibernate/3
will
do is the following. It will discard the call stack for
the process. Then it will garbage collect the process. After
the garbage collection, all live data will be in one
contionous heap. The heap will then be shrunk to the exact
same size as the live data which it holds (even if that size
should be less than the minimum heap size for the process).
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.
Failure: badarg
if Module
or Function
is not an atom, or if ArgumentList
is not a list.
This BIF is now equivalent to erlang:system_info/1.
Returns a list of integers (ASCII codes) which correspond
to Integer
.
> integer_to_list(77). "77"
Failure: badarg
if Integer
is not an integer.
erlang:integer_to_list(Integer, Base)
Returns a list of integers (ASCII codes) in base Base
which correspond to Integer
.
> erlang:integer_to_list(1023, 16). "3FF"
Failure: badarg
if Integer
or Base
is
not an integer, or if Base
is not in the range 2..36.
Returns true
if the current node is alive; i.e., if
the node can be part of a distributed system. Otherwise, it
returns false
.
Types:
Term = term()
Bool = true | false
Returns true
if Term
is an atom;
otherwise returns false
.
This BIF may be used also in guards.
Types:
Term = term()
Bool = true | false
Returns true
if Term
is a binary;
otherwise returns false
.
This BIF may be used also in guards.
Types:
Term = term()
Bool = true | false
Returns true
if Term
is
either the atom true
or the atom false
(i.e. a boolean); otherwise returns false
.
This BIF may be used also in guards.
erlang:is_builtin(Module, Function, Arity)
Returns true
if Module:Function/Arity
is
a BIF implemented in C; otherwise returns false
.
This BIF is useful for builders of cross reference tools.
Types:
Term = term()
Bool = true | false
Returns true
if Term
is a floating point number;
otherwise returns false
.
This BIF may be used also in guards.
Types:
Term = term()
Bool = true | false
Returns true
if Term
is a fun;
otherwise returns false
.
This BIF may be used also in guards.
is_function(Term, Arity) -> Bool
Types:
Term = term()
Arity = integer()
Bool = true | false
Returns true
if Term
is a fun that can be applied
with Arity
number of arguments;
otherwise returns false
.
This BIF may be used also in guards.
Currently, |
Types:
Term = term()
Bool = true | false
Returns true
if Term
is an integer;
otherwise returns false
.
This BIF may be used also in guards.
Types:
Term = term()
Bool = true | false
Returns true
if Term
is a list with
zero or more elements; otherwise returns false
.
This BIF may be used also in guards.
Types:
Term = term()
Bool = true | false
Returns true
if Term
is either an integer
or a floating point number; otherwise returns false
.
This BIF may be used also in guards.
Types:
Term = term()
Bool = true | false
Returns true
if Term
is a process identifier (pid);
otherwise returns false
.
This BIF may be used also in guards.
Types:
Term = term()
Bool = true | false
Returns true
if Term
is a port;
otherwise returns false
.
This BIF may be used also in guards.
Pid
must refer to a process at the current node.
Returns true
if the process is alive, i.e., has not
exited. Otherwise, returns false
.
is_record(Term, RecordTag) -> Bool
Types:
Term = term()
RecordTag = atom()
Bool = true | false
RecordTag
must be an atom.
Returns true
if Term
is a tuple and
its first element is RecordTag
.
Otherwise, returns false
.
Normally the compiler treats calls to |
If RecordTag
is a literal atom, this BIF can also be
used in a guard.
Failure: badarg
if RecordTag
is not an atom.
erlang:is_record(Term, RecordTag, Size) -> Bool
Types:
Term = term()
RecordTag = atom()
Size = integer()
Bool = true | false
The RecordTag
must be an atom.
Returns true
if Term
is a tuple,
its first element is RecordTag
, and its size is Size
.
Otherwise, returns false
.
This BIF is documented for completeness. In most cases you should
use |
Failure: badarg
if RecordTag
is not an atom,
or Size
is not an integer.
Types:
Term = term()
Bool = true | false
Returns true
if Term
is a reference;
otherwise returns false
.
This BIF may be used also in guards.
Types:
Term = term()
Bool = true | false
Returns true
if Term
is a tuple;
otherwise returns false
.
This BIF may be used also in guards.
Returns the length of List
.
> length([1,2,3,4,5,6,7,8,9]). 9
Allowed in guard tests.
Failure: badarg
if List
is not a proper list.
Creates a link to the process (or port) Pid
, if there
is not such a link already. If a process attempts to create a
link to itself, nothing is done. Returns true
.
Sends an EXIT signal with reason noproc
to the calling
process if Pid
does no longer exist.
Failure: badarg
if Pid
is not a pid or port.
Returns an atom whose text representation is the integers
(Latin-1 codes) in List
.
> list_to_atom([69, 114, 108, 97, 110, 103]). 'Erlang'
Failure: badarg
if the argument is not a list of
integers in the range [0, 255].
Types:
DeepList = iolist()
Returns a binary which is made from the integers and
binaries in List
. List
may be deep and may
contain any combination of integers and binaries.
Example: list_to_binary([Bin1,1,[2,3,Bin2],4|Bin3])
Failure: badarg
if List
is not a list, or if
it or any sublist contains anything else than binaries or
integers in the range [0, 255].
Returns a float whose text representation is the integers
(ASCII-values) in List
.
> list_to_float([50,46,50,48,49,55,55,54,52,101,43,48]). 2.20178
Failure: badarg
if List
is not a list of
integers, or if it contains a bad representation of a float.
Returns an integer whose text representation is the integers
(ASCII-values) in List
.
> list_to_integer([49, 50, 51]). 123
Failure: badarg
if List
is not a list of
integers, or if it contains a bad representation of an
integer.
erlang:list_to_integer(List, Base)
Returns an integer whose text representation in base
Base
is the integers (ASCII-values) in List
.
> erlang:list_to_integer("3FF", 16). 1023
Failure: badarg
if List
is not a list of
integers, contains a bad representation of an integer, or if
Base
is not in the range 2..36.
Returns a pid whose text representation is the integers
(ASCII-values) in List
.
This BIF is intended for debugging and for use in the Erlang operating system. It should not be used in application programs. |
> list_to_pid("<0.4.1>"). <0.4.1>
Failure: badarg
if List
is not a list of
integers, or if it contains a bad representation of a pid.
Returns a tuple which corresponds to List
. List
can contain any Erlang terms.
> list_to_tuple([mary, had, a, little, {dog, cat, lamb}]). {mary, had, a, little, {dog, cat, lamb}}
Failure: badarg
if List
is not a proper list.
If Binary
contains the object code for the module
Module
, this BIF loads that object code. Also, if
the code for the module Module
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 {module,Module}
,
where Module
is the name of the module which has been
loaded, or {error, Reason}
if loading fails.
Reason
is one of the following:
badfile
Binary
has an incorrect format.
not_purged
Binary
contains a module which cannot be loaded
because old code for this module already exists (see
the BIFs purge_module
and delete_module
).
badfile
Module
Failure: badarg
if Module
is not an atom, or
Binary
is not a binary.
This BIF is intended for code server (see |
Returns a list of all loaded Erlang modules, including preloaded modules. A module will be included in the list if it has either current code or old code or both loaded.
Returns the current local date and time
{{Year, Month, Day}, {Hour, Minute, Second}}
.
The time zone and daylight saving time correction depend on the underlying OS.
> erlang:localtime(). {{1996,11,6},{14,45,17}}
erlang:localtime_to_universaltime(DateTime)
Converts local date and time in DateTime
to
Universal Time Coordinated (UTC), if this is supported by
the underlying OS. Otherwise, no conversion is done and
DateTime
is returned. The return value is of the form
{{Year, Month, Day}, {Hour, Minute, Second}}
.
Failure: badarg
if DateTime
is not a valid
date and time tuple
{{Year,Month,Day}, {Hour,Minute,Second}}
.
> erlang:localtime_to_universaltime({{1996,11,6},{14,45,17}}). {{1996,11,6},{13,45,17}}
erlang:localtime_to_universaltime(DateTime, IsDst)
Converts local date and time in DateTime
to
Universal Time Coordinated (UTC) just like
erlang:localtime_to_universaltime/1
, but the caller
decides if daylight saving time is active or not.
If IsDst == true
the DateTime
is during
daylight saving time, if IsDst == false
it is not,
and if IsDst == undefined
the underlying OS may
guess, which is the same as calling
erlang:localtime_to_universaltime(DateTime)
.
Failure: badarg
if DateTime
is not a valid
date and time tuple
{{Year,Month,Day}, {Hour,Minute,Second}}
or if
IsDst
is not one of the atoms true
, false
or undefined
.
> erlang:localtime_to_universaltime({{1996,11,6},{14,45,17}}, true). {{1996,11,6},{12,45,17}} > erlang:localtime_to_universaltime({{1996,11,6},{14,45,17}}, false). {{1996,11,6},{13,45,17}} > erlang:localtime_to_universaltime({{1996,11,6},{14,45,17}}, undefined). {{1996,11,6},{13,45,17}}
Returns an almost unique reference.
The returned reference will reoccur after approximately 2^82 calls; therefore it is unique enough for practical purposes.
> make_ref(). #Ref<0.0.0.135>
erlang:make_tuple(Arity, InitialValue)
Returns a new tuple of the given Arity
, where all
elements are InitialValue
.
> erlang:make_tuple(4, []). {[],[],[],[]}
Types:
Data = iolist() | binary()
Digest = binary()
Computes an MD5
message digest from Data
, where
the length of the digest is 128 bits (16 bytes). Data
is a binary or a list of small integers and binaries.
See The MD5 Message Digest Algorithm (RFC 1321) for more information about MD5.
Failure: badarg
if Data
is not a list, or if
it or any sublist contains anything else than binaries or
integers in the range [0, 255].
erlang:md5_final(Context) -> Digest
Types:
Context = Digest = binary()
Finishes the update of an MD5 Context
and returns
the computed MD5
message digest.
Types:
Context = binary()
Creates an MD5 context, to be used in subsequent calls to
md5_update/2
.
erlang:md5_update(Context, Data) -> NewContext
Types:
Data = iolist() | binary()
Context = NewContext = binary()
Updates an MD5 Context
with Data
, and returns
a NewContext
.
Types:
MemList = [MemInfo]
MemInfo = {atom(), int()}
Returns information about memory dynamically allocated by the Erlang emulator.
A list of tuples is returned. Each tuple has two elements. The first element is an atom describing memory type. The second element is memory size in bytes. A description of each tuple follows:
total
total
is the sum of processes
and
system
.processes
processes_used
processes
memory.system
processes
is not included in
this memory.atom
system
memory.atom_used
atom
memory.binary
system
memory.code
system
memory.
ets
system
memory.maximum
The When the emulator is run with instrumentation,
the Since the |
The different values has the following relation to each other. Values beginning with an uppercase letter is not part of the result.
total = processes + system processes = processes_used + ProcessesNotUsed system = atom + binary + code + ets + OtherSystem atom = atom_used + AtomNotUsed RealTotal = processes + RealSystem RealSystem = system + MissedSystem
The |
More tuples in the returned list may be added in the future.
erlang:memory(MemoryTypeSpec) -> MemList | int()
Types:
MemoryTypeSpec = MemoryType | [MemoryType]
MemoryType = atom()
MemList = [MemInfo]
MemInfo = {atom(), int()}
erlang:memory/1
returns the same type of information
as erlang:memory/0
, but allows the caller to select
specific information.
MemoryType
is an atom equal to any atom that is used
by erlang:memory/0
to describe a memory type.
When MemoryTypeSpec
is an atom the corresponding
memory size is returned as an integer.
When MemoryTypeSpec
is a list of atoms
the corresponding values are returned as a MemList
.
The elements of the list returned are sorted, with regard to
the atoms, in the same order as the MemoryTypeSpec
list
is sorted with the exception that duplicate atoms are ignored.
Failure: badarg
if MemoryType
is not an atom
that is used by erlang:memory/0
to describe a memory
type, or if the emulator is not run with instrumentation and
maximum
is used as a MemoryType
.
Returns true
if the module Module
is loaded,
otherwise returns false
. It does not attempt to load
the module.
This BIF is intended for code server (see |
> erlang:module_loaded(lists). true
Failure: badarg
if Module
is not an atom.
erlang:monitor(Type, Item) -> MonitorReference
Types:
Type = atom()
Item = pid() | {RegisteredName,NodeName} | RegisteredName
RegisteredName = atom()
NodeName = atom()
MonitorReference = reference()
The current process starts monitoring Item
which is
an object of type Type
.
Currently only processes can be monitored, i.e. the only
allowed Type
is process
, but other types may be
allowed in the future.
Valid Item
s when Type
is process
are:
pid()
{RegisteredName, NodeName}
NodeName
with the registered name
RegisteredName
will be monitored.RegisteredName
{RegisteredName, node()}
.
When a process is monitored by registered name, the process
that has the registered name at the time when
|
A 'DOWN'
message will be sent to the monitoring
process if Item
dies, if Item
does not exist,
or if the connection is lost to the node which Item
resides on. A 'DOWN'
message has the following pattern:
{'DOWN', MonitorReference, Type, Object, Info}
where:
MonitorReference
erlang:monitor/2
.Type
Object
Type
is process
, Object
will
be:Item
was the pid in the call to erlang:monitor/2
.
{RegisteredName, NodeName}
, if Item
was {RegisteredName, NodeName}
in the call to
erlang:monitor/2
.
{RegisteredName, NodeName}
, if Item
was
RegisteredName
in the call to
erlang:monitor/2
. NodeName
will in this
case be the name of the local node.
Info
Type
is process
, Info
is
either the exit reason of the process, noproc
(non-existing process), or noconnection
(no
connection to Item
s node).
If/when |
The monitoring is turned off either when the 'DOWN'
message is sent, or when erlang:demonitor(MonitorReference)
is called (MonitorReference
is the value returned by
erlang:monitor/2
).
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 badarg
.
Making several calls to erlang:monitor/2
for the same
Item
is not an error; it results in several completely
independent monitorings.
The format of the |
Monitors the status of the node Node
. If Flag
is true
, monitoring is turned on; if Flag
is
false
, monitoring is turned off. Calls to the BIF are
accumulated. This is shown in the following example, where a
process is already monitoring the node Node
and a
library function is called:
monitor_node(Node, true), ... some operations monitor_node(Node, false),
After the call, the process is still monitoring the node.
If Node
fails or does not exist, the message
{nodedown, Node}
is delivered to the process. If a
process has made two calls to monitor_node(Node, true)
and Node
terminates, two nodedown
messages are
delivered to the process. If there is no connection to
Node
, there will be an attempt to create one. If this
fails, a nodedown
message is delivered.
Nodes connected through hidden connections can be monitored
as any other node with erlang:monitor_node/2
.
Returns true
.
Failure: badarg
if Flag
is not true
or
false
, or if Node
is not an atom indicating a
remote node, or if the local node is not alive.
Returns the name of the current node. If it is not a
networked node but a local Erlang runtime system, the atom
nonode@nohost
is returned.
Allowed in guard tests.
Returns the node where Arg
is located. Arg
can
be a pid, a reference, or a port.
Allowed in guard tests.
Failure: badarg
if Arg
is not a pid,
reference, or port.
Returns a list of all visible nodes in the system, excluding
the current node. Same as nodes(visible)
.
Types:
Arg = ArgList | ArgAtom
ArgList = [ArgAtom]
ArgAtom = visible | hidden | connected | this | known
Returns a list of nodes according to argument given.
The result returned when Arg
is an ArgList
is
the list of nodes satisfying the disjunction(s) of
ArgAtom
s in ArgList
.
ArgAtom
description:
visible
hidden
connected
this
known
More ArgAtom
s may be added in the future.
Some equalities: [node()] = nodes(this)
,
nodes(connected) = nodes([visible, hidden])
, and
nodes() = nodes(visible)
.
Failure: badarg
if Arg
is not a valid
ArgAtom
, or a list of validArgAtom
s.
Returns the tuple {MegaSecs,Secs,Microsecs}
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
now()
can be used to generate unique time-stamps. It
can only be used to check the local time of day if
the time-zone info of the underlying operating system is
properly configured.
open_port(PortName, PortSettings)
Returns a port identifier as the result of opening a
new Erlang port. A port can be seen as an external Erlang
process. PortName
is one of the following:
{spawn, Command}
Command
is the name
of the external program which will be run. Command
runs outside the Erlang work space unless an Erlang
driver with the name Command
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.vfork
is used in preference to fork
for performance reasons, although it has a history of
being less robust. If there are problems with using
vfork
, setting the environment variable
ERL_NO_VFORK
to any value will cause fork
to be used instead.Atom
open_port()
is obsolete and will be
removed in a future version of Erlang. Use the file
module instead.{fd, In, Out}
In
can be used for standard input, and the file
descriptor Out
for standard output. It is only
used for various servers in the Erlang operating system
(shell
and user
). Hence, its use is very
limited.PortSettings
is a list of settings for the port.
Valid values are:
{packet, N}
N
bytes, with the most significant byte first. Valid values
for N
are 1, 2, or 4.stream
{line, N}
{Flag, Line}
, where Flag
is either
eol
or noeol
and Line
is the actual
data delivered (without the newline sequence).N
specifies the maximum line length in bytes.
Lines longer than this will be delivered in more than one
message, with the Flag
set to noeol
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 Flag
set to noeol
. In all other cases,
lines are delivered with Flag
set to eol
.
{packet, N}
and {line, N}
settings are
mutually exclusive.{cd, Dir}
{spawn, Command}
.
The external program starts using Dir
as its
working directory. Dir
must be a string. Not
available on VxWorks.{env, Environment}
{spawn, Command}
.
The environment of the started process is extended using
the environment specifications in Environment
.
Environment
should be a list of tuples
{Name,Value}
, where Name
is the name of an
environment variable, and Value
is the value it is
to have in the spawned port process. Both Name
and
Value
must be strings. The one exception is
Value
being the atom false
(in analogy with
os:getenv/1
), which removes the environment
variable. Not available on VxWorks.exit_status
{spawn, Command}
where
Command
refers to an external program.{Port,{exit_status,Status}}
is
sent to the connected process, where Status
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).eof
option has been given as well,
the eof
message and the exit_status
message
appear in an unspecified order.exit_status
option will not work.use_stdio
{spawn, Command}
. It
allows the standard input and output (file descriptors 0
and 1) of the spawned (UNIX) process for communication
with Erlang.nouse_stdio
stderr_to_stdout
stderr_to_stdout
and
nouse_stdio
are mutually exclusive.in
out
binary
eof
{Port, eof}
message will be sent to the process
holding the port.The default is stream
for all types of port and
use_stdio
for spawned ports.
Failure: badarg
if the format of PortName
or
PortSettings
is incorrect. If the port cannot be
opened, the exit reason is the Posix error code which most
closely describes the error, or einval
if no Posix code
is appropriate. The following Posix error codes may appear:
enomem
eagain
enametoolong
emfile
enfile
During use of a port opened using {spawn,Name}
,
errors arising when sending messages to it are reported to
the owning process using signals of the form
{'EXIT',Port,PosixCode}
. Posix codes listed in
the documentation for the file
module.
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 ERL_MAX_PORTS
.
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 Term
within the range 1..Range
.
This BIF could be used instead of the old deprecated
erlang:hash/2
BIF, as it calculates better hashes for
all datatypes, but consider using phash2/1,2
instead.
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
Term
within the range 0..Range-1
. When called
without the Range
argument, a value in the range
0..2^27-1
is returned.
This BIF should always be used for hashing terms. It
distributes small integers better than phash/2
, and
it is faster for bignums and binaries.
Note that the range 0..Range-1
is different from
the range of phash/2
(1..Range
).
Returns a list which corresponds to the process Pid
.
This BIF is intended for debugging and for use in the Erlang operating system. It should not be used in application programs. |
> pid_to_list(whereis(init)). "<0.0.0>"
Failure: badarg
if Pid
is not a pid.
Closes an open port. Roughly the same as
Port ! {self(), close}
except for the error behaviour
(see below), and that the port does not reply with
{Port, closed}
. Any process may close a port with
port_close/1
, not only the port owner (the connected
process).
Returns: true
.
Failure: badarg
if Port
is not an open port or
the registered name of an open port.
For comparison: Port ! {self(), close}
fails with
badarg
if Port
cannot be sent to (i.e.,
Port
refers neither to a port nor to a process). If
Port
is a closed port nothing happens. If Port
is an open port and the current process is the port owner,
the port replies with {Port, closed}
when all buffers
have been flushed and the port really closes, but if
the current process is not the port owner the port
owner fails with badsig
.
Note that any process can close a port using
Port ! {PortOwner, close}
just as if it itself was
the port owner, but the reply always goes to the port owner.
In short: port_close(Port)
has a cleaner and more
logical behaviour than Port ! {self(), close}
.
Types:
Port = port()
Data = iolist() | binary()
Sends data to a port. Same as
Port ! {self(), {command, Data}}
except for the error
behaviour (see below). Any process may send data to a port
with port_command/2
, not only the port owner
(the connected process).
Returns: true
.
Failure: badarg
if Port
is not an open port
or the registered name of an open port, or if Data
is
not an I/O list. An I/O list is binary or a (possibly) deep
list of binaries or integers in the range 0 through 255.
For comparison: Port ! {self(), {command, Data}}
fails with badarg
if Port
cannot be sent to
(i.e., Port
refers neither to a port nor to a process).
If Port
is a closed port the data message disappears
without a sound. If Port
is open and the current
process is not the port owner, the port owner fails
with badsig
. The port owner fails withbadsig
also if Data
is not a legal I/O list.
Note that any process can send to a port using
Port ! {PortOwner, {command, Data}}
just as if it
itself was the port owner.
In short: port_command(Port, Data)
has a cleaner and
more logical behaviour than
Port ! {self(), {command, Data}}
.
Sets the port owner (the connected port) to Pid
.
Roughly the same as Port ! {self(), {connect, Pid}}
except for the following:
{Port,connected}
.The old port owner stays linked to the port and have to call
unlink(Port)
if this is not desired. Any process may
set the port owner to be any process with
port_connect/2
.
Returns: true
.
Failure: badarg
if Port
is not an open port
or the registered name of a port, or if Pid
is not a
valid local pid.
For comparison: Port ! {self(), {connect, Pid}}
fails
with badarg
if Port
cannot be sent to (i.e.,
Port
refers neither to a port nor to a process). If
Port
is a closed port nothing happens. If Port
is an open port and the current process is the port owner,
the port replies with {Port, connected}
to the old
port owner. Note that the old port owner is still linked to
the port, and that the new is not. If Port
is an open
port and the current process is not the port owner,
the port owner fails with badsig
. The port
owner fails with badsig
also if Pid
is not a
valid local pid.
Note that any process can set the port owner using
Port ! {PortOwner, {connect, Pid}}
just as if it
itself was the port owner, but the reply always goes to
the port owner.
In short: port_connect(Port, Pid)
has a cleaner and
more logical behaviour than
Port ! {self(),{connect,Pid}}
.
port_control(Port, Operation, Data)
Types:
Port = port()
Operation = integer()
Data = iolist() | binary()
Performs a synchronous control operation on a port.
The meaning of Operation
and Data
depends on
the port, i.e., on the port driver. Not all port drivers
support this control feature.
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.
Failure: badarg
if Port
is not an open port or
the registered name of a port, if Operation
cannot fit
in a 32-bit integer, if the port driver does not support
synchronous control operations, if Data
is not a valid
I/O list (see port_command/2), or if the port driver so
decides for any reason (probably something wrong with
Operation
or Data
).
erlang:port_call(Port, Operation, Data)
Performs a synchronous call to a port. The meaning of
Operation
and Data
depends on the port, i.e.,
on the port driver. Not all port drivers support this feature.
Port
is an Erlang port, referring to a driver.
Operation
is an integer, which is passed on to
the driver.
Data
is any Erlang term. This data is converted to
binary term format and sent to the port.
Returns: a term from the driver. The meaning of the returned data also depends on the port driver.
Failure: badarg
if Port
is not an open port or
the registered name of a port, if Operation
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
Operation
or Data
).
Returns a list containing tuples with information about
the port Port
. The order of these tuples are not
defined, nor are all the tuples mandatory.
{registered_name,Atom}
Atom
is the registered name of the port. If
the port has no registered name, this tuple is not
present in the list.{id,Index}
Index
is the internal index of the port. This
index may be used to separate ports.{connected, Pid}
Pid
is the process connected to the port.{links,ListOfPids}
ListOfPids
is a list of Pids with processes to
which the port has a link.{name,String}
String
is the command name set by
open_port
.{input,Bytes}
Bytes
is the total number of bytes read from
the port.{output,Bytes}
Bytes
is the total number of bytes written to
the port.Failure: badarg
if Port
is not a port
identifier, or if Port
is a port identifier for
a port created on another Erlang node.
Returns information about the port Port
as specified
by Item
, which can be any one of the atoms
registered_name
, id
, connected
,
links
, name
, input
, or output
.
{registered_name,Atom}
Atom
is the registered name of the port. If
the port has no registered name, []
is returned.{id,Index}
Index
is the internal index of the port. This
index may be used to separate ports.{connected, Pid}
Pid
is the process connected to the port.{links,ListOfPids}
ListOfPids
is a list of Pids with processes to
which the port has a link.{name,String}
String
is the command name set by
open_port
.{input,Bytes}
Bytes
is the total number of bytes read from
the port.{output,Bytes}
Bytes
is the total number of bytes written to
the port.Returns undefined
if the port does not exist.
Failure: badarg
if Port
is not a port
identifier, or if Port
is a port identifier for
a port created on another Erlang node,
or if Item
is not valid.
Returns a list which corresponds to the port identifier
Port
.
This BIF is intended for debugging and for use in the Erlang operating system. It should not be used in application programs. |
> erlang:port_to_list(open_port({spawn,ls}, [])). "#Port<0.15>"
Failure: badarg
if Port
is not a port
identifier.
Returns a list of all ports on the current node.
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 init
must be pre-loaded.
erlang:process_display(Pid, Type)
Writes information about the local process Pid
on
standard error. The currently allowed value for the atom
Type
is backtrace
, which shows the contents of
the stack, including information about the call chain, with
the most recent data printed last. The format of the output
is not further defined.
Sets certain flags for the process which calls this function. Returns the old value of the flag.
process_flag(trap_exit, Boolean)
trap_exit
is set to true
, EXIT signals
arriving to a process are converted to {'EXIT', From,
Reason}
messages, which can be received as ordinary
messages. If trap_exit
is set to false
, the
process exits if it receives an EXIT signal other than
normal
and the EXIT signal is propagated to its
linked processes. Application processes should normally
not trap exits.
process_flag(error_handler, Module)
process_flag(min_heap_size, MinHeapSize)
process_flag(priority, Level)
Level
is an
atom. All implementations support three priority levels,
low
, normal
, and high
. The default
is normal
.
process_flag(save_calls, N)
N
must be an integer in the interval
[0, 10000].
If N
> 0, call saving is made active for the process,
which means that information about the N
most recent global
function calls, BIF calls, sends and receives made by the process
are saved in a list, which can be retrieved with
process_info(Pid, last_calls)
.
A global function call is one in which the module of the function
is explicitly mentioned.
Only a fixed amount of
information is saved: a tuple {Module, Function, Arity}
for function calls, and the mere atoms send
,
'receive'
and timeout
for sends and receives
('receive'
when a message is received and timeout
when a receive times out).
If N
= 0, call saving is disabled for the process,
which is the default.
Whenever the size of the call saving list is set, its contents
are reset.
Failure: badarg
if Flag
is not an atom, or is
not a recognized flag value, or if Option
is not a
recognized term for Flag
.
process_flag(Pid, Flag, Option)
Sets certain flags for the process Pid
, in the same
manner as process_flag/2
.
Returns the old value of the flag. The allowed values for
Flag
are only a subset of those allowed in
process_flag/2
, namely: save_calls
.
Failure: badarg
if Pid
is not a process on the
local node, or if
Flag
is not an atom, or is
not a recognized flag value, or if Option
is not a
recognized term for Flag
.
Returns a list containing tuples with information about
the process Pid
. The order of these tuples are not
defined, nor are all the tuples mandatory.
This BIF is intended for debugging only. |
{current_function, {Module, Function, Args}}
Module
, Function
, Args
is
the current function call of the process.{dictionary, Dictionary}
Dictionary
is the dictionary of the process.{error_handler, Module}
Module
is the error handler module used by
the process (for undefined function calls, for example).
{group_leader, Groupleader}
Groupleader
is group leader for the I/O of
the process.{heap_size, Size}
Size
is the heap size of the process in heap
words.{initial_call, {Module, Function, Arity}}
Module
, Function
, Arity
is
the initial function call with which the process was
spawned.{links, ListOfPids}
ListOfPids
is a list of Pids, with processes to
which the process has a link.{message_queue_len, MessageQueueLen}
MessageQueueLen
is the number of messages
currently in the message queue of the process. This is
the length of the list MessageQueue
returned as
the info item messages
(see below).{messages, MessageQueue}
MessageQueue
is a list of the messages to
the process, which have not yet been processed.{priority, Level}
Level
is the current priority level for
the process. Only low
and normal
are always
supported.{reductions, Number}
Number
is the number of reductions executed by
the process.{registered_name, Atom}
Atom
is the registered name of the process. If
the process has no registered name, this tuple is not
present in the list.{stack_size, Size}
Size
is the stack size of the process in stack
words.{status, Status}
Status
is the status of the process. Status
is waiting
(waiting for a message), running
,
runnable
(ready to run, but another process is
running), or suspended
(suspended on a "busy" port
or by the erlang:suspend_process/1
BIF).{trap_exit, Boolean}
Boolean
is true
if the process is trapping
exits, otherwise it is false
.Failure: badarg
if Pid
is not a pid, or if it
is the pid of a remote process.
Returns information about the process Pid
as
specified by Item
, in the form {Item, Info}
.
Item
can be any one of the atoms backtrace
,
current_function
, dictionary
,
error_handler
, group_leader
, heap_size
,
initial_call
, last_calls
, links
,
memory
, message_queue_len
, messages
,
monitored_by
, monitors
, priority
,
reductions
, registered_name
, stack_size
,
status
or trap_exit
.
Returns undefined
if no information is known about
the process.
Item registered_name
returns []
if the process
has no registered name.
Item memory
returns {memory,Size}, where Size
is the size of the process in bytes. This includes stack,
heap and internal structures.
Item backtrace
returns a binary, which contains
the same information as the output from
erlang:process_display(Pid, backtrace)
. Use
binary_to_list/1
to obtain the string of characters
from the binary.
Item last_calls
returns false
if call saving
is not active for the process (see
process_flag/3).
If call saving is active, a list is returned, in which
the last element is the most recent.
Item links
returns a list of pids to which
the process is linked.
Item monitors
returns a list of monitors (started by
erlang:monitor/2
) that are active for the process. For
a local process monitor or a remote process monitor by pid,
the list item is {process, Pid}
, and for a remote
process monitor by name, the list item is
{process, {Name, Node}}
.
Item monitored_by
returns a list of pids that are
monitoring the process (with erlang:monitor/2
).
Not all implementations support every one of the above
Items
.
Failure: badarg
if Pid
is not a pid, or if it
is a process identifier of a remote process.
Returns a list of all processes on the current node.
> processes(). [<0.0.0>, <0.2.0>, <0.4.0>, <0.5.0>, <0.7.0>, <0.8.0>]
Removes old code for Module
. Before this BIF is used,
erlang:check_process_code/2
should be called to check
that no processes are executing old code in this module.
This BIF is intended for code server (see |
Failure: badarg
if Module
does not exist.
Adds a new Value
to the process dictionary and
associates it with Key
. If a value is already
associated with Key
, that value is deleted and replaced
by the new value Value
. It returns any value
previously associated with Key
, or undefined
if
no value was associated with Key
. Key
and
Value
can be any valid Erlang terms.
The values stored when |
> X = put(name, walrus), Y = put(name, carpenter), Z = get(name), {X, Y, Z}. {undefined,walrus,carpenter}
erlang:raise(Class, Reason, Stacktrace)
Stops the execution of the current process with an exception of given class, reason and stacktrace.
This BIF is intended for debugging and for use in the Erlang operating system. It should not be used in application programs. |
Class
is one of error
, exit
or
throw
, so if it were not for the stacktrace
erlang:raise(Class, Reason, Stacktrace)
is
equivalent to erlang:Class(Reason)
.
Reason
is any term and
Stacktrace
is a list as returned
from get_stacktrace()
, that is a list of
3-tuples {Module,Function,A}
where Module
and Function
are atoms and A
should be
an integer arity or an argument list. The stacktrace
may also contain {Fun,A}
tuples where Fun
is a local fun and A
is an argument list.
The stacktrace is used as the exception stacktrace
for the current process, so it will be truncated to
the current maximum stacktrace depth. Any non-existent
functions or funs it refers to may also be removed,
even if they became non-existent after the stacktrace
was stored for example due to code purge. This is
because a true stacktrace can only refer to existing
code. (Except for the head element from a
function_clause
or undef
error that refers
to the function that did not exist.)
Because evaluating this function causes
the process to terminate, it has no return value -
unless the arguments are invalid, in which case the
function returns the error reason, that is
badarg
. If you want to be really sure not to
return you can call
erlang:error(erlang:raise(Class, Reason, Stacktrace))
and hope to distinguish exceptions later.
Ref
is a timer reference returned by
send_after/3
or start_timer/3
. If the timer is
active, the function returns the time in milliseconds left
until the timer will expire, otherwise false
(which may
mean that Ref
was never a timer, or that it has been
cancelled, or that it has already delivered its message).
Failure: badarg
if Ref
is not a reference.
Returns a list which corresponds to the reference Ref
.
This BIF is intended for debugging and for use in the Erlang operating system. It should not be used in application programs. |
> erlang:ref_to_list(make_ref()). "#Ref<0.0.0.134>"
Failure: badarg
if Ref
is not a reference.
Associates the name Name
with the port or pid
P
. Name
, which must be an atom, can be used
instead of a port or pid in the send operator
(Name ! Message
).
Returns true
.
Failure: badarg
if P
is not an active port or
process, if P
is on another node, if Name
is
already in use, if the port or process is already registered
(already has a name), if Name
is not an atom, or if
Name
is the atom undefined
.
Returns a list of names which have been registered using
register/2
.
> registered(). [code_server, file_server, init, user, my_db]
Resume a suspended process.
This BIF is intended for debugging only. |
Returns an integer by rounding the number Number
.
> round(5.5). 6
Allowed in guard tests.
Failure: badarg
if Number
is not a number.
Returns the pid (process identity) of the calling process.
> self(). <0.26.0>
Allowed in guard tests.
Sends a message and returns Msg
. This is the same as
Dest ! Msg
.
Dest
may be a remote or local pid, a (local) port, a
locally registered name, or a tuple {Name,Node}
for a
registered name on another node.
erlang:send(Dest, Msg, Options)
Sends a message and returns ok
, or does not send
the message but returns something else (see below). Otherwise
the same as send/2
. See also send_nosuspend/2,3
for more detailed explanation and warnings.
Options
is a list of options. The possible options
are:
nosuspend
nosuspend
is returned instead.noconnect
noconnect
is returned
instead.As with send_nosuspend/2,3
:
Use with extreme care!
erlang:send_after(Time, Pid, Msg)
Time
is a non-negative integer, Pid
is either
a pid or an atom, and Msg
is any Erlang term.
The function returns a reference Ref
.
After Time
ms, send_after/3
sends Msg
to Pid
.
If Pid
is an atom, it is supposed to be the name of
a registered process. The process referred to by the name is
looked up at the time of delivery. No error is given if
the name does not refer to a process. See also
start_timer/3
and cancel_timer/1
.
Limitations: Pid
must be a process on the local node.
The timeout value must fit in 32 bits.
Failure: badarg
if any arguments are of the
wrong type, or do not obey the limitations noted above.
erlang:send_nosuspend(Dest, Msg)
The same as send(Dest, Msg, [nosuspend)
, but returns
true
if the message was sent and false
if
the message was not sent because the sender would have been
suspended.
This function is intended for send operations towards an
unreliable remote node without ever blocking the sending
(Erlang) process. If the connection to the remote node
(usually not a real Erlang node, but a node written in C or
Java) is overloaded, this function will not send
the message but return false
instead.
The same happens, if Dest
refers to a local port that
is busy. For all other destinations (allowed for the ordinary
send operator '!'
) this function sends the message and
returns true
.
This function is only to be used in very rare circumstances where a process communicates with Erlang nodes that can disappear without any trace causing the TCP buffers and the drivers que to be overfull before the node will actually be shut down (due to tick timeouts) by net_kernel. The normal reaction to take when this happens is some kind of premature shutdown of the other node.
Note that ignoring the return value from this function would
result in unreliable message passing, which is
contradictory to the Erlang programming model. The message is
not sent if this function returns false
.
Note also that in many systems, transient states of
overloaded queues are normal. The fact that this function
returns false
does not in any way mean that the other
node is guaranteed to be nonrespoinsive, it could be a
temporary overload. Also a return value of true
does
only mean that the message could be sent on the (TCP) channel
without blocking, the message is not guaranteed to have
arrived at the remote node. Also in the case of a disconnected
nonresponsive node, the return value is true
(mimics
the behaviour of the !
operator). The expected
behaviour as well as the actions to take when the function
returns false
are application and hardware specific.
Use with extreme care!
erlang:send_nosuspend(Dest, Msg, Options)
The same as send(Dest, Msg, [nosuspend | Options])
,
but with boolean return value.
This function behaves like send_nosuspend/2
, but
takes a third parameter, a list()
of options. The only
currently implemented option is noconnect
. The option
noconnect
makes the function return false
if
the remote node is not currently reachable by the local
Erlang node. The normal behaviour is to try to connect to
the node, which may stall the process for a shorter period.
The use of the noconnect
option makes it possible to
be absolutely sure not to get even the slightest delay when
sending to a remote process. This is especially useful when
communicating with nodes who expect to always be
the connecting part (i.e. nodes written in C or Java).
Whenever the function returns false
(either when a
suspend would occur or when noconnect
was specified and
the node was not already connected), the message is guaranteed
not to have been sent.
Use with extreme care!
erlang:set_cookie(Node, Cookie)
Sets the magic cookie of Node
to the atom
Cookie
. If Node
is the current node,
the function also sets the cookie of all other unknown nodes
to Cookie
(see auth(3)).
setelement(Index, Tuple, Value)
Returns a tuple which is a copy of the argument Tuple
with the element given by the integer argument Index
(the first element is the element with index 1) replaced by
the argument Value
.
> setelement(2, {10, green, bottles}, red). {10, red, bottles}
Failure: badarg
if Index
is not an integer,
Tuple
is not a tuple, or if Index
is less than 1
or greater than the size of Tuple
.
Returns an integer which is the size of the argument
Item
, which must be either a tuple or a binary.
> size({morni, mulle, bwange}). 3
Allowed in guard tests.
Failure: badarg
if Item
is not a tuple or a
binary.
Returns the pid of a new process started by the application
of Fun
to the empty argument list []
. Otherwise
works like spawn/3
.
Returns the pid of a new process started by the application
of Fun
to the empty argument list []
on node
Node
. Otherwise works like spawn/4
.
spawn(Module, Function, ArgumentList)
Returns the pid of a new process started by the application
of Module:Function
to ArgumentList
.
Note: The new process created will be placed in
the system scheduler queue and will be run some time later.
error_handler:undefined_function(Module, Function,
ArgumentList)
is evaluated by the new process if
Module:Function/Arity
does not exist (where
Arity
is the length of ArgumentList
). The error
handler can be redefined (see BIF process_flag/2)
).
Arity
is the length of ArgumentList
. If
error_handler
is undefined, or the user has redefined
the default error_handler
its replacement is undefined,
a failure with the reason undef
will occur.
> spawn(speed, regulator, [high_speed, thin_cut]). <0.13.1>
Failure: badarg
if Module
and/or
Function
is not an atom, or if ArgumentList
is
not a list.
spawn(Node, Module, Function, ArgumentList)
Works like spawn/3
, with the exception that
the process is spawned at Node
. If Node
does not
exist, a useless pid is returned.
Failure: badarg
if Node
, Module
, or
Function
are not atoms, or ArgumentList
is not
a list.
Works like spawn/1
except that a link is made from
thed current process to the newly created one, atomically.
Works like spawn/2
except that a link is made from
thed current process to the newly created one, atomically.
Returns the Pid
of the newly created process.
Failure: See spawn/3
.
spawn_link(Module, Function, ArgumentList)
This BIF is identical to the following code being evaluated in an atomic operation:
> Pid = spawn(Module, Function, ArgumentList), link(Pid), Pid.
This BIF is necessary since the process created might run
immediately and fail before link/1
is called.
Returns the pid of the newly created process.
Failure: See spawn/3
.
spawn_link(Node, Module, Function, ArgumentList)
Works like spawn_link/3
, except that the process is
spawned at Node
. If an attempt is made to spawn a
process on a node which does not exist, a useless Pid is
returned, and an EXIT signal will be received.
Returns the pid of a new process started by the application
of Fun
to the empty argument list []
. Otherwise
works like spawn_opt/4
.
Returns the pid of a new process started by the application
of Fun
to the empty argument list []
. Otherwise
works like spawn_opt/5
.
spawn_opt(Module, Function, ArgumentList, Options)
Works exactly like spawn/3
, except that an extra
option list can be given when creating the process.
This BIF is only useful for performance tuning. Random tweaking of the parameters without measuring execution times and memory consumption may actually make things worse. Furthermore, most of the options are inherently implementation-dependent, and they can be changed or removed in future versions of OTP. |
link
spawn_link/3
does).{priority, Level}
process_flag(priority, Level)
in
the start function of the new process, except that
the priority will be set before the process is scheduled
in the first time.{fullsweep_after, Number}
fullsweep_after
option, you can specify
the maximum number of generational collections before
forcing a fullsweep even if there is still room on
the old heap. Setting the number to zero effectively
disables the general collection algorithm, meaning that
all live data is copied at every garbage collection.fullsweep_after
. Firstly, if you want binaries
that are no longer used to be thrown away as soon as
possible. (Set Number
to zero.) Secondly, a
process that mostly have short-lived data will be
fullsweeped seldom or never, meaning that the old heap
will contain mostly garbage. To ensure a fullsweep once
in a while, set Number
to a suitable value such as
10 or 20. Thirdly, in embedded systems with limited
amount of RAM and no virtual memory, you might want to
preserve memory by setting Number
to zero. (You
probably want to the set the value globally. See
system_flag/2.)
{min_heap_size, Size}
Size
values.spawn_opt(Node, Module, Function, ArgumentList, Options)
Works like spawn_opt/4
, except that the process is
spawned at Node
. If an attempt is made to spawn a
process on a node which does not exist, a useless pid is
returned, and an EXIT signal will be received.
Returns a tuple which contains two binaries which are
the result of splitting Binary
into two parts at
position Pos
. This is not a destructive operation.
After this operation, there are three binaries altogether.
Returns a tuple consisting of the two new binaries. For
example:
1> B = list_to_binary("0123456789"). <<48,49,50,51,52,53,54,55,56,57>> 2> size(B). 10 3> {B1, B2} = split_binary(B,3). {<<48,49,50>>, <<51,52,53,54,55,56,57>>} 4> size(B1). 3 5> size(B2). 7
Failure: badarg
if Binary
is not a binary, or
Pos
is not an integer or is out of range.
erlang:start_timer(Time, Proc, Msg)
Time
is a non-negative integer, Proc
is either
a pid or an atom, and Msg
is any Erlang term.
The function returns a reference.
After Time
ms, start_timer/3
sends the tuple
{timeout, Ref, Msg}
to Proc
, where Ref
is
the reference returned by start_timer/3
.
If Proc
is an atom, it is supposed to be the name of
a registered process. The process referred to by the name is
looked up at the time of delivery. No error is given if
the name does not refer to a process. See also
send_after/3
and cancel_timer/1
.
Limitations: Proc
must be a process on the local
node. The timeout value must fit in 32 bits.
Failure: badarg
if any arguments are of the wrong
type, or do not obey the limitations noted above.
Returns information about the system. Type
is an atom
which is one of:
run_queue
runtime
{Total_Run_Time,Time_Since_Last_Call}
.wall_clock
{Total_Wallclock_Time,
Wallclock_Time_Since_Last_Call}
. wall_clock
can be used in the same manner as the atom runtime
,
except that real time is measured as opposed to runtime
or CPU time.reductions
{Total_Reductions,
Reductions_Since_Last_Call}
.garbage_collection
{Number_of_GCs,Words_Reclaimed,0}
. This
information may not be valid for all implementations.All times are in milliseconds.
> statistics(runtime). {1690, 1620} > statistics(reductions). {2046, 11} > statistics(garbage_collection). {85, 23961, 0}
Failure: badarg
if Type
is not one of the atoms
shown above.
Suspends the process Pid
.
This BIF is intended for debugging only. |
erlang:system_flag(Flag, Value)
This BIF sets various system properties of the Erlang node.
If Flag
is a valid name of a system flag, its value is
set to Value
, and the old value is returned.
The following values for Flag
are currently allowed:
backtrace_depth
'EXIT'
tuples. fullsweep_after
fullsweep_after
is an non-negative
integer which indicates how many times generational garbages
collections can be done without forcing a fullsweep
collection. The value applies to new processes; processes
already running are not affected.ERL_FULLSWEEP_AFTER
.min_heap_size
min_heap_size
only effects
processes spawned after the change of min_heap_size
has been made. The min_heap_size
can be set for
individual processes by use of
spawn_opt() or
process_flag/2.
trace_control_word
Value
.
Value
should be an unsigned integer. For more information
see documentation of the
set_tcw
function in the
match specification
documentation in the ERTS User's Guide.
|
Types:
What = atom() | {atom() | term()}
This BIF returns various information about the current system (emulator).
What
can be one of the following terms:
allocated_areas
erlang:system_info(allocated_areas)
is intended
for debugging, and the content is highly implementation
dependent. The content of the results will therefore
change when needed without prior notice.allocator
{Allocator, Version, Features, Settings}.
Allocator = atom()
Version = [int()]
Features = [atom()]
Settings =
[{Subsystem, [{Parameter, Value}]}]
Subsystem = atom()
Parameter = atom()
Value = term()
Allocator
corresponds to the malloc()
implementation used. If Allocator
equals
undefined
, the malloc()
implementation
used could not be identified. Currently
elib_malloc
and glibc
can be identified.
Version
is a list of integers (but not a
string) representing the version of
the malloc()
implementation used.Features
is a list of atoms representing
allocation features used.Settings
is a list of subsystems, their
configurable parameters, and used values. Settings
may differ between different combinations of
platforms, allocators, and allocation features.
Memory sizes are given in bytes.{allocator, Alloc}
Alloc = atom()
Alloc
allocator. If
Alloc
is not a recognized allocator,
undefined
is returned. If Alloc
is disabled,
false
is returned.mbcs
, and
sbcs
are abbreviations for, respectively,
multiblock carriers, and singleblock carriers. Sizes are
presented in bytes. When it is not a size that is
presented, it is the amount of something. Sizes and
amounts are often presented by three values, the first is
current value, the second is maximum value since the last
call to erlang:system_info({allocator, Alloc})
,
and the third is maximum value since the emulator was
started. If only one value is present, it is the current
value. fix_alloc
memory block types are presented
by two values. The first value is memory pool size and
the second value used memory size.compat_rel
creation
dist
dist_ctrl
{NodeName,ControllingEntity}
, one entry for each
connected remote node. The NodeName
is the name
of the node and the ControllingEntity
is the
port()
or pid()
responsible for the
communication to that node. More specifically, the
ControllingEntity
for nodes connected via TCP/IP
(the normal case) is the socket actually used in
communication with the specific node.
elib_malloc
elib_malloc
memory allocator,
a list of two-element tuples containing status information
of elib_malloc
is returned; otherwise, false
is
returned. The list currently contains the following two-element
tuples (all sizes are presented in bytes):{heap_size, Size}
Size
is the current heap size.
{max_alloced_size, Size}
Size
is the maximum amount of
memory allocated on the heap since the emulator started.
{alloced_size, Size}
Size
is the current amount of
memory allocated on the heap.
{free_size, Size}
Size
is the current amount of
free memory on the heap.
{no_alloced_blocks, No}
No
is the current number of
allocated blocks on the heap.
{no_free_blocks, No}
No
is the current number of
free blocks on the heap.
{smallest_alloced_block, Size}
Size
is the size of the smallest
allocated block on the heap.
{largest_free_block, Size}
Size
is the size of the largest
free block on the heap.
fullsweep_after
{fullsweep_after, integer()}
which is the
fullsweep_after
garbage collection setting used
by default. For more information see the
garbage_collection
argument described below.garbage_collection
spawn()
or spawn_link()
will use
these garbage collection settings. The default settings
can be changed by use of
system_flag/2.
spawn_opt()
can spawn a process that does not use the default settings.
global_heaps_size
heap_sizes
heap_type
private
shared
hybrid
private
and shared
heap
types. A shared heap as well as private heaps are used.
info
loaded
machine
process_count
length(processes())
returns.process_limit
procs
system_version
system_architecture
threads
true
if the emulator has been compiled
with thread support; otherwise, false
is
returned.thread_pool_size
trace_control_word
version
wordsize
|
Failure: badarg
if What
is not either one of the
arguments documented above or one of the undocumented arguments.
erlang:system_monitor(MonitorPid, Options)
Sets system performance monitoring options. MonitorPid
is a local pid that will receive system monitor messages, and
Options
is a list of monitoring options:
{long_gc, Time}
Time
wallclock milliseconds, a message
{monitor,GcPid,long_gc,Info}
is sent to
MonitorPid
. GcPid
is the pid that was
garbage collected and Info
is a list of two-element
tuples describing the result of the garbage collection.
One of the tuples is {timeout, GcTime}
where
GcTime
is the actual time for the garbage
collection in milliseconds. The other are the tuples
tagged with heap_size
, stack_size
,
mbuf_size
and heap_block_size
from
the gc_start
trace message (see
erlang:trace/3
).{large_heap, Size}
Size
words, a message {monitor, GcPid, large_heap, Info}
is sent to MonitorPid
. GcPid
and Info
are the same as for long_gc
above, except that
the tuple tagged with timeout
is not present.busy_port
{monitor, SusPid, busy_port, Port}
is sent to
MonitorPid
. SusPid
is the pid that got
suspended when sending to Port
.busy_dist_port
{monitor, SusPid, busy_port, Port}
is sent to
MonitorPid
. SusPid
is the pid that got
suspended when sending through the inter-node
communication port Port
.Returns the previous system monitor settings just like
erlang:system_monitor/0
.
If a monitoring process gets so large that it itself starts to cause system monitor messages when garbage collecting, the messages will enlargen the process's message queue and probably make the problem worse. Keep the monitoring process neat and do not set the system monitor limits too tight. |
erlang:system_monitor({MonitorPid, Options})
The same as
erlang:system_monitor(MonitorPid, Options)
.
erlang:system_monitor(undefined)
Clears all system monitoring set by
erlang:system_monitor/2
.
Returns the previous system monitor settings just like
erlang:system_monitor/0
.
Returns the current system monitoring settings set by
erlang:system_monitor/2
as
{MonitorPid, Options}
. The order of the options may be
different from the one that was set.
This BIF returns the encoded value of any Erlang term and turns it into the Erlang external term format. It can be used for a variety of purposes, for example writing a term to a file in an efficient way, or sending an Erlang term to some type of communications channel not supported by distributed Erlang.
Returns a binary data object which corresponds to an
external representation of the Erlang term Term
.
This BIF returns the encoded value of any Erlang term and
turns it into the Erlang external term format. If
the Options
list contains the atom compressed
,
the external term format will be compressed. The compressed
format is automatically recognized by binary_to_term/1
in R7.
Returnsa binary data object which corresponds to an
external representation of the Erlang term Term
.
Failure: badarg
if Options
is not a list or
if contains something else than the supported flags (currently
only the atom compressed
).
A non-local return from a function. If evaluated within a
catch
, catch
will return the value Any
.
> catch throw({hello, there}). {hello, there}
Failure: nocatch
if not evaluated within a catch.
Returns the tuple {Hour, Minute, Second}
of
the current system time. The time zone correction is
implementation-dependent.
> time(). {9, 42, 44}
Returns the tail of List
, that is the list minus
the first element.
> tl([geesties, guilies, beasties]). [guilies, beasties]
Allowed in guard tests.
Failure: badarg
if List
is the empty list [],
or is not a list.
erlang:trace(PidSpec, How, Flaglist)
Turns on (if How == true
) or off (if How ==
false
) the trace flags in Flaglist
for
the process or processes represented by PidSpec
.
PidSpec
is either a pid for a local process, or one of
the following atoms:
existing
new
all
Flaglist
can contain any number of the following
atoms (the "message tags" refers to the list of messages
following below):
all
{tracer, Tracer}
and
cpu_timestamp
that are in their nature different
than the others.send
Pid
sends.
Message tags: send
,
send_to_non_existing_process
.'receive'
Pid
receives.
Message tags: 'receive'
.procs
spawn
,
link
, exit
. Message tags: spawn
,
exit
, register
, unregister
,
link
, unlink
, getting_linked
,
getting_unlinked
.call
call
,
return_from
.silent
call
trace
flag. Sets the call trace message mode for the process
Pid
to silent, i.e, the call tracing is
active, match specs are executed as normal, but no call
trace messages are generated.erlang:trace/3
without
the silent
flag, but also by a match spec executing
the {silent, false}
function.return_to
local
option to
erlang:trace_pattern/3
. The semantics is that a message is sent when
a call traced function actually returns, i.e., when a
chain of tail recursive calls is ended. There will be
only one trace message sent per chain of tail recursive
calls, why the properties of tail recursiveness for
function calls are kept while tracing with this flag.
Using call
and return_to
trace together
makes it possible to know exactly in which function a
process executes at any time.{return_trace}
match_spec
action instead.return_to
.running
in
,
out
.garbage_collection
gc_start
, gc_end
.timestamp
erlang:now()
.cpu_timestamp
PidSpec==all
. If the host
machine operating system does not support high resolution
CPU time measurements, trace/3
exits with
badarg
.arity
{Mod, Fun, Args}
in call traces, there
will be {Mod, Fun, Arity}
.set_on_spawn
Pid
inherit
the flags of Pid
, including the set_on_spawn
flag.set_on_first_spawn
Pid
inherit the flags of Pid
That process does not
inherit the set_on_first_spawn
flag.set_on_link
Pid
inherit the flags
of Pid
, including the set_on_link
flag.set_on_first_link
Pid
inherit
the flags of Pid
. That process does not inherit
the set_on_first_link
flag.{tracer, Tracer}
Tracer
should be the pid for a local process or
the port identifier for a local port. All trace messages
will be sent to the given process or port. If this flag
is not given, trace messages will be sent to the process
that called erlang:trace/3
.The effect of combining set_on_first_link
with
set_on_link
is the same as having
set_on_first_link
alone. Likewise for
set_on_spawn
and set_on_first_spawn
.
If the timestamp
flag is not given, the tracing
process will receive the trace messages described below. If
the timestamp
flag is given, the first element of
the tuple will be trace_ts
and the timestamp will be in
the last element of the tuple.
{trace, Pid, 'receive', Message}
Pid
receives something.{trace, Pid, send, Msg, To}
Pid
sends a message.{trace, Pid, send_to_non_existing_process, Msg, To}
Pid
sends a message to a non existing
process.{trace, Pid, call, {M,F,A}}
Pid
makes a function/BIF call. The return
values of calls are never supplied, only the call and its
arguments.{trace, Pid, return_to, {M,F,A}}
Pid
returns to function
{M,F,A}
. This message will be sent if both
the call
and the return_to
flags are present
and the function is set to be traced on local
function calls. The message is only sent when returning
from a chain of tail recursive function calls where at
least one call generated a call
trace message
(i.e., the functions match specification matched and
{message,false}
was not an action).{trace, Pid, return_from, {M,F,A}, ReturnValue}
Pid
returns from the function
{M,F,A}
This trace message is sent when
the call
flag has been specified, and the function
has a match specification with a return_trace
action.{trace, Pid, spawn, Pid2, {M, F, A}}
Pid
spawns a new process Pid2
.
{M, F, A}
are the initial function call with
arguments for the new process.A
is supposed to be the argument list,
but may be any term in the case of an erroneous spawn.{trace, Pid, exit, Reason}
Pid
exits with reason Reason
.{trace, Pid, link, Pid2}
Pid
links to a process Pid2
.{trace, Pid, unlink, Pid2}
Pid
removes the link from a process
Pid2
.{trace, Pid, getting_linked, Pid2}
Pid
gets linked to a process Pid2
.{trace, Pid, getting_unlinked, Pid2}
Pid
gets unlinked from a process Pid2
.
{trace, Pid, register, Name}
Pid
gets the name Name
registered.{trace, Pid, unregister, Name}
Pid
gets the name Name
unregistered.
Note that this is done automatically when a registered
process exits.{trace, Pid, in, {M,F,A} | 0}
Pid
is scheduled to run. The process will
run in function {M,F,A}
, where A
is always
the arity. On some rare occasions the current function
cannot be determined, then the last element is 0
.
{trace, Pid, out, {M,F,A} | 0}
Pid
is scheduled out. The process was
running in function {M,F,A} where A is always the arity.
On some rare occasions the current function cannot be
determined, then the last element is 0
.{trace, Pid, gc_start, Info}
Info
is a list of two-element tuples, where
the first element is a key, and the second is the value.
You should not depend on the tuples have any defined
order. Currently, the following keys are defined.heap_size
old_heap_size
stack_size
recent_size
mbuf_size
{trace, Pid, gc_end, Info}
Info
contains the same kind of list as in the gc_start
message, but the sizes reflect the new sizes after
garbage collection.If the tracing process dies, the flags will be silently removed.
Only one process can trace a particular process. For this reason, attempts to trace an already traced process will fail.
Returns: A number indicating the number of processes that
matched PidSpec
. If PidSped
is a pid,
the return value will be 1
. If PidSpec
is
all
or existing
the return value will be
the number of processes running, excluding tracer processes.
If PidSpec
is new
, the return value will be
0
.
Failure: badarg
if bad arguments are given. Or if
arguments are not supported, for example cpu_timestamp
is not supported on all platforms.
erlang:trace_info(PidOrFunc, Item)
Returns trace information about a process or function.
To get information about a process, PidOrFunc
should
be a pid or the atom new
. The atom new
means
that the default trace state for processes to be created will
be returned. Item
must have one of the following
values:
flags
send
,
'receive'
, set_on_spawn
, call
,
return_to
, procs
, set_on_first_spawn
,
set_on_link
, running
,
garbage_collection
, timestamp
, and
arity
. The order is arbitrary.tracer
[]
.To get information about a function, PidOrFunc
should
be a three-element tuple: {Module, Function, Arity}
or
the atom on_load
. No wildcards are allowed. Return
undefined
if the function does not exist and
false
if the function is not traced at all. Item
must have one of the following values:
traced
global
if this function is traced on
global function calls, local
if this function is
traced on local function calls (i.e local and global
function calls), and false
if neither local nor
global function calls are traced.match_spec
[]
.meta
false
, and if
the function is meta traced but has once detected
that the tracer proc is invalid, the returned value is
[]
.meta_match_spec
[]
.call_count
true
for the pseudo function on_load
if call
count tracing is active. Return false
otherwise.
See also
erlang:trace_pattern/3
.all
{Item, Value}
tuples
for all other items, or return false
if no tracing
is active for this function.The actual return value will be {Item, Value}
, where
Value
is the requested information as described above.
If a pid for a dead process was given, or the name of a
non-existing function, Value
will be undefined
.
If PidOrFunc
is the on_load
, the information
returned refers to the default value for code that will be
loaded.
erlang:trace_pattern(MFA, MatchSpec)
The same as erlang:trace_pattern(MFA, MatchSpec, [])
,
retained for backward compatibility.
erlang:trace_pattern(MFA, MatchSpec, FlagList)
This BIF is used to enable or disable call tracing for
exported functions. It must be combined with
erlang:trace/3 to set
the call
trace flag for one or more processes.
Conceptually, call tracing works like this: Inside the Erlang virtual machine there is a set of processes to be traced and a set of functions to be traced. Tracing will be enabled on the intersection of the set. That is, if a process included in the traced process set calls a function included in the traced function set, the trace action will be taken. Otherwise, nothing will happen.
Use erlang:trace/3 to
add or remove one or more processes to the set of traced
processes. Use erlang:trace_pattern/2
to add or remove
exported functions to the set of traced functions.
The erlang:trace_pattern/3
BIF can also add match
specifications to an exported function. A match specification
comprises a pattern that the arguments to the function must
match, a guard expression which must evaluate to true
and action to be performed. The default action is to send a
trace message. If the pattern does not match or the guard
fails, the action will not be executed.
The MFA
argument should be a tuple like
{Module, Function, Arity}
or the atom on_load
(described below). It can be the module, function, and arity
for an exported function (or a BIF in any module).
The '_'
atom can be used to mean any of that kind.
Wildcards can be used in any of the following ways:
{Mod,Func,'_'}
Func
in module Mod
.{Mod,'_','_'}
Mod
.{'_','_','_'}
Other combinations, such as {Mod,'_',Arity}
, are not
allowed. Local functions will match wildcards only if
the local
option is in the FlagList
.
If the MFA
argument is the atom on_load
,
the match specification and flag list will be used on all
modules that are newly loaded.
The MatchSpec
argument can take any of the following
forms:
false
true
MatchSpecList
true
. See the ERTS User's Guide
for a description of match specifications.restart
FlagList
option call_count
:
restart the existing counters. The behaviour is undefined
for other FlagList
options.pause
FlagList
option call_count
: pause
the existing counters. The behaviour is undefined for
other FlagList
options.The FlagList
parameter is a list of options.
The following options are allowed:
global
local
return_to
flag is set for
the process, a return_to
message will also be sent
when this function returns to its caller.meta | {meta, Pid}
Pid
whenever any of the specified
functions are called, regardless of how they are called.
If no Pid
is specified, self()
is used as a
default tracer process.trace/3
,
the trace flags are instead fixed to
[call, timestamp]
.{return_trace}
works with
meta trace and send its trace message to the same tracer
process.call_count
MatchSpec == true
) or stops
(MatchSpec == false
) call count tracing for all
types of function calls. For every function a counter is
incremented when the function is called, in any process.
No process trace flags need to be activated.MatchSpec == pause
. Paused and running
counters can be restarted from zero with
MatchSpec == restart
.The global
and local
options are mutually
exclusive and global
is the default (if no options are
specified). The call_count
and meta
options
perform a kind of local tracing, and can also not be combined
with global
. A function can be either
globally or locally traced. If global tracing is specified
for a specified set of functions; local, meta and call count
tracing for the matching set of local functions will be
disabled, and vice versa.
When disabling trace, the option must match the type of trace
that is set on the function, so that local tracing must be
disabled with the local
option and global tracing with
the global
option (or no option at all), and so forth.
There is no way to directly change part of a match specification list. If a function has a match specification, you can replace it with a completely new one. If you need to change an existing match specification, use the erlang:trace_info/2 BIF to retrieve the existing match specification.
Returns the number of exported functions that matched
the MFA
argument. This will be zero if none matched at
all.
Failure: badarg
for invalid MFA
or
MatchSpec
.
Returns an integer by the truncation of Number
.
> trunc(5.5). 5
Allowed in guard tests.
Failure: badarg
if Number
is not a number.
Returns a list which corresponds to Tuple
.
Tuple
may contain any valid Erlang terms.
> tuple_to_list({share, {'Ericsson_B', 163}}). [share, {'Ericsson_B', 163}]
Failure: badarg
if Tuple
is not a tuple.
Returns the current date and time according to Universal
Time Coordinated (UTC), also called GMT, in the form
{{Year, Month, Day}, {Hour, Minute, Second}}
if
supported by the underlying operating system. If not,
erlang:universaltime()
is equivalent to
erlang:localtime()
.
> erlang:universaltime(). {{1996,11,6},{14,18,43}}
erlang:universaltime_to_localtime(DateTime)
Converts UTC date and time in DateTime
to local date
and time if supported by the underlying operating system.
Otherwise, no conversion is done, and DateTime
is
returned. The return value is of the form
{{Year, Month, Day}, {Hour, Minute, Second}}
.
> erlang:universaltime_to_localtime({{1996,11,6},{14,18,43}}). {{1996,11,7},{15,18,43}}
Failure: badarg
if the argument is not a valid date
and time tuple
{{Year, Month, Day}, {Hour, Minute, Second}}
.
Removes a link, if there is one, from the calling process
to another process given by the argument Pid
.
Returns true
. Will not fail if not linked to
Pid
, or if Pid
does not exist.
Failure: badarg
if Pid
is not a pid.
Removes the registered name for a process or port, given by
the atom argument Name
.
Returns the atom true
.
> unregister(db). true
Failure: badarg
if Name
is not the name of a
registered port or process.
Users are advised not to unregister system processes.
Returns the pid or port identifier registered under
Name
(see register/2
). Returns undefined
if no such port or process is registered.
> whereis(user). <0.3.1>
Failure: badarg
if Name
is not an atom.
Voluntarily let other processes (if any) get a chance to
execute. Using yield()
is similar to
receive after 1 -> ok end
, except that yield()
is faster.