erlang

MODULE

erlang

MODULE SUMMARY

The Erlang BIFs

DESCRIPTION

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 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.

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.

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:

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.

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.

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.

float/1 is also allowed in guards. But note
that if it used on the top-level in a guard, it will test whether
the argument is a floating point number; for clarity, use
is_float/1 instead.
When float/1 is used in an expression in a guard,
such as 'float(A) == 4.0', it behaves in the same
way as in a function body.

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.

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:

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.

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
erlang:phash/2 or erlang:phash2/1,2 instead.

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.

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 is_record/2
specially. It emits code to verify that Term is a tuple,
that its first element is RecordTag, and that the size is
correct. However, if the RecordTag is not a literal
atom, the is_record/2 BIF will be called instead.

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

The object code in 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

The object code contains code for another module than
Module

Failure: badarg if Module is not an atom, or
Binary is not a binary.

This BIF is intended for code server (see code(3))
and should not be used elsewhere.

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}}.

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.

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

The total amount of memory currently allocated.
total is the sum of processes and
system.

processes

The total amount of memory currently allocated by
the Erlang processes.

processes_used

The total amount of memory currently used by the Erlang
processes.
This memory is part of the memory presented as
processes memory.

system

The total amount of memory currently allocated by
the emulator that is not directly related to any Erlang
process.
Memory presented as processes is not included in
this memory.

atom

The total amount of memory currently allocated for atoms.
This memory is part of the memory presented as
system memory.

atom_used

The total amount of memory currently used for atoms.
This memory is part of the memory presented as
atom memory.

binary

The total amount of memory currently allocated for
binaries.
This memory is part of the memory presented as
system memory.

code

The total amount of memory currently allocated for
Erlang code.
This memory is part of the memory presented as
system memory.

ets

The total amount of memory currently allocated for ets
tables.
This memory is part of the memory presented as
system memory.

maximum

The maximum total amount of memory allocated since
the emulator was started.
This tuple is only present when the emulator is run with
instrumentation.
For information on how to run the emulator with
instrumentation see the
instrument(3) and/or
erl(1) man pages.

The system value is not complete. Some allocated
memory that should be part of the system value are
not. For example, memory allocated by drivers is missing.

When the emulator is run with instrumentation,
the system value is more accurate, but memory
directly allocated by malloc (and friends) are still
not part of the system value. Direct calls to
malloc 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.

Since the total value is the sum of processes
and system the error in system will propagate
to the total value.

The different values has the following relation to each
other. Values beginning with an uppercase letter is not part
of the result.

The total 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 total value is not 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.

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.

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 Items when Type is process are:

pid()

The pid of the process to monitor.

{RegisteredName, NodeName}

A tuple consisting of a registered name of a process
and a node name. The process residing on the node
NodeName with the registered name
RegisteredName will be monitored.

RegisteredName

The same as {RegisteredName, node()}.

When a process is monitored by registered name, the process
that has the registered name at the time when
erlang:monitor/2 is called will be monitored.
The monitor will not be effected, if the registered name is
unregistered.

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

The reference returned by erlang:monitor/2.

Type

The type of the monitored object.

Object

A reference to the monitored object.
When Type is process, Object will
be:

the pid of the monitored process, if 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

When Type is process, Info is
either the exit reason of the process, noproc
(non-existing process), or noconnection (no
connection to Items node).

If/when erlang:monitor/2 is extended (e.g. to
handle other item types than process), other
possible values for Type, Object, and
Info in the 'DOWN' message will be introduced.

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 'DOWN' message changed in the 5.2
version of the emulator (OTP release R9B) for monitor by
registered name. The Object element of
the 'DOWN' message could in earlier versions
sometimes be the pid of the monitored process and sometimes
be the registered name. Now the Object 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 'DOWN' messages on
the new format even if they are monitoring processes on old
nodes. Processes on old nodes will always get 'DOWN'
messages on the old format.

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:

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 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.

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}

Starts an external program. 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.
When starting external programs on Solaris, the system
call 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

This use of open_port() is obsolete and will be
removed in a future version of Erlang. Use the file
module instead.

{fd, In, Out}

Allows an Erlang process to access any currently opened
file descriptors used by Erlang. The file descriptor
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}

Messages are preceded by their length, sent in N
bytes, with the most significant byte first. Valid values
for N are 1, 2, or 4.

stream

Output messages are sent without packet lengths. A
user-defined protocol must be used between the Erlang
process and the external object.

{line, N}

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 {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.
The {packet, N} and {line, N} settings are
mutually exclusive.

{cd, Dir}

This is only valid for {spawn, Command}.
The external program starts using Dir as its
working directory. Dir must be a string. Not
available on VxWorks.

{env, Environment}

This is only valid for {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

This is only valid for {spawn, Command} where
Command refers to an external program.
When the external process connected to the port exits, a
message of the form {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).
If the eof option has been given as well,
the eof message and the exit_status message
appear in an unspecified order.
If the port program closes its stdout without exiting,
the exit_status option will not work.

use_stdio

This is only valid for {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

The opposite of the above. Uses file descriptors 3 and 4
for communication with Erlang.

stderr_to_stdout

Affects ports to external programs. The executed program
gets its standard error file redirected to its standard
output file. stderr_to_stdout and
nouse_stdio are mutually exclusive.

in

The port can only be used for input.

out

The port can only be used for output.

binary

All I/O from the port are binary data objects as opposed
to lists of bytes.

eof

The port will not be closed at the end of the file and
produce an EXIT signal. Instead, it will remain open and
a {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

There was not enough memory to create the port.

eagain

There are no more available operating system processes.

enametoolong

The external command given was too long.

emfile

There are no more available file descriptors.

enfile

A file or port table is full.

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).

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}.

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:

The error behavior differs, see below.

The port does not reply with
{Port,connected}.

The new port owner gets linked to the port.

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}}.

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).

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 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.

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)

When 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)

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 autoloading is dependent on the
correct operation of the error handling module.

process_flag(min_heap_size, MinHeapSize)

This changes the minimum heap size for the current
process.

process_flag(priority, Level)

This sets the process priority. 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.

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.

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 put is evaluated within
the scope of a catch will not be retracted if a
throw is evaluated, or if an error occurs.

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 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).

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.

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

If the sender would have to be suspended to do the send,
nosuspend is returned instead.

noconnect

If the destination node would have to be autoconnected
before doing the send, noconnect is returned
instead.

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.

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.

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.

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.

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.

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

Sets a link to the parent process (like
spawn_link/3 does).

{priority, Level}

Sets the priority of the new process. Equivalent to
executing 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}

The Erlang runtime system uses a generational garbage
collection scheme, using an "old heap" for data that has
survived at least one garbage collection. When there is
no more room on the old heap, a fullsweep garbage
collection will be done.
Using the 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.
Here are a few cases when it could be useful to change
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}

Gives a minimum heap size in words. Setting this value
higher than the system default might speed up some
processes because less garbage collection is done.
Setting too high value, however, might waste memory and
slow down the system due to worse data locality.
Therefore, it is recommended to use this option only for
fine-tuning an application and to measure the execution
time with various Size values.

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:

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.

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

Sets the maximum depth of call stack backtraces in the
exit reason element of 'EXIT' tuples.

fullsweep_after

The value of the 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.
In low-memory systems (especially without virtual memory),
setting the value to zero can help to conserve memory.
An alternative way to set this value is through
the (operating system) environment variable
ERL_FULLSWEEP_AFTER.

min_heap_size

Sets the default minimum heap size for processes. The size is
given in words. The new 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

Sets the value of the node's trace control word to 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.

erlang:system_flag/2 accepts other arguments than
those documented above. These arguments have
intentionally been left undocumented. This either because
the undocumented Flag argument is used for implementation
of other documented functionality, or is used for testing and
debugging of the emulator. Do not use the undocumented
arguments of erlang:system_flag/2, they may have
undesirable side-effects, and may be changed or removed at any
time without prior notice.

This BIF returns various information about the current
system (emulator).

What can be one of the following terms:

allocated_areas

Information about miscellaneous allocated memory areas.
A list of tuples is returned. Each tuple contains an atom
describing type of memory as first element and amount of
allocated memory in bytes as second element. In those
cases when there is information present about allocated
and used memory, a third element is present. This third
element contains the amount of used memory in bytes.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.Note: The sum of these values is not
the total amount of memory allocated by the emulator.
Some values are part of other values, and some memory
areas are not part of the result. If you are interested
in the total amount of memory allocated by the emulator
see erlang:memory/0
or erlang:memory/1.

allocator

Returns {Allocator, Version, Features, Settings}.
Types:

Allocator = atom()

Version = [int()]

Features = [atom()]

Settings =
[{Subsystem, [{Parameter, Value}]}]

Subsystem = atom()

Parameter = atom()

Value = term()

Explanation:

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.

Returns information about the Alloc allocator. If
Alloc is not a recognized allocator,
undefined is returned. If Alloc is disabled,
false is returned.Note: The information returned is highly
implementation dependent and may be changed, or removed
at any time without prior notice. It was initially
intended as a tool when developing new allocators, but
since it might be of interest for others it has been
briefly documented.
The returned information more or less speaks for itself
once you have read the
erts_alloc(3)
documentation, but
it can be worth explaining some things. Call counts are
presented by two values. The first value is giga calls,
and the second value is calls. 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

Returns the compatibility mode of the current node as
an integer. The integer returned represents the
Erlang/OTP release which the current emulator has been
set to be backward compatible with. The compatibility mode can
be configured at startup by use of the
+R system flag
(see the erl(1)
documentation)

creation

Returns the creation of the current node as an integer.
The creation is changed when a node is restarted. The creation
of a node is stored in process identifiers, port identifiers,
and references. This makes it (to some extent) possible to
distinguish between identifiers from different incarnations of
a node. Currently valid creations are integers in the range
[1, 3], but this may (probably will) change in the future.
If the node is not alive 0 is returned.

dist

Returns a binary containing a string of distribution
information formatted as in Erlang crash dumps. For more
information see the "How
to interpret the Erlang crash dumps"
chapter in the ERTS User's Guide.

dist_ctrl

Returns a list of tuples
{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

If the emulator uses the 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}

Where Size is the current heap size.

{max_alloced_size, Size}

Where Size is the maximum amount of
memory allocated on the heap since the emulator started.

{alloced_size, Size}

Where Size is the current amount of
memory allocated on the heap.

{free_size, Size}

Where Size is the current amount of
free memory on the heap.

{no_alloced_blocks, No}

Where No is the current number of
allocated blocks on the heap.

{no_free_blocks, No}

Where No is the current number of
free blocks on the heap.

{smallest_alloced_block, Size}

Where Size is the size of the smallest
allocated block on the heap.

{largest_free_block, Size}

Where Size is the size of the largest
free block on the heap.

fullsweep_after

Returns {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

Returns a list describing the default garbage
collection settings. A process spawned on the current
node by a 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

Returns the current size of the shared (global) heap.

heap_sizes

Returns a list of integers representing valid heap sizes
in words. All Erlang heaps are sized from sizes in this
list.

heap_type

Returns the heap type used by the current emulator.
Currently the following heap types exist:

private

Each process has a heap reserved for its use and no
references between heaps of different processes are
allowed. Messages passed between processes are copied
between heaps.

shared

One heap for use by all processes. Messages passed
between processes are passed by reference.

hybrid

A hybrid of the private and shared heap
types. A shared heap as well as private heaps are used.

info

Returns a binary containing a string of miscellaneous
system information formatted as in Erlang crash dumps. For more
information see the "How
to interpret the Erlang crash dumps"
chapter in the ERTS User's Guide.

loaded

Returns a binary containing a string of loaded module
information formatted as in Erlang crash dumps. For more
information see the "How
to interpret the Erlang crash dumps"
chapter in the ERTS User's Guide.

machine

Returns a string containing the Erlang machine name.

process_count

Returns the number of processes currently existing on
the current node as an integer. The same value as
length(processes()) returns.

process_limit

Returns the maximum number of concurrently existing
processes on the current node as an integer. This limit
can be configured at startup by use of the
+P
system flag (see the
erl(1) documentation)

procs

Returns a binary containing a string of process and port
information formatted as in Erlang crash dumps. For more
information see the "How
to interpret the Erlang crash dumps"
chapter in the ERTS User's Guide.

system_version

Returns a string containing the emulator type and
version as well as some important properties such as
the size of the thread pool, etc.

system_architecture

Returns a string containing the processor and OS
architecture the emulator is built for.

threads

Returns true if the emulator has been compiled
with thread support; otherwise, false is
returned.

thread_pool_size

Returns the number of threads used for driver calls
as an integer.

trace_control_word

Returns the value of the node's trace control word.
For more information see documentation of the
get_tcw
function in the match
specification documentation in the ERTS User's Guide.

version

Returns a string containing the version number of the
emulator.

wordsize

Returns the word size in bytes as an integer, i.e.
on a 32-bit architecture 4 is returned, and on a 64-bit
architecture 8 is returned.

erlang:system_info/1 accepts other arguments than
those documented above. These arguments have intentionally
been left undocumented. This either because the undocumented
argument is used for implementation of other documented
functionality, or is used for testing and debugging of the
emulator. Do not use the undocumented arguments of
erlang:system_info/1, they may have undesirable
side-effects, and may be changed or removed at any time without
prior notice.

Failure: badarg if What is not either one of the
arguments documented above or one of the undocumented arguments.

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}

If a garbage collection in the system takes at least
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}

If a garbage collection in the system results in
the allocated size of a heap being at least 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

If a process in the system gets suspended because it
sends to a busy port, a message
{monitor, SusPid, busy_port, Port} is sent to
MonitorPid. SusPid is the pid that got
suspended when sending to Port.

busy_dist_port

If a process in the system gets suspended because it
sends to a process on a remote node whose inter-node
communication was handled by a busy port, a message
{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.

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).

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

All processes currently existing.

new

All processes that will be created in the future.

all

All currently existing processes and all processes that
will be created in the future.

Flaglist can contain any number of the following
atoms (the "message tags" refers to the list of messages
following below):

all

All trace flags except {tracer, Tracer} and
cpu_timestamp that are in their nature different
than the others.

Traces function calls to functions that tracing has been
enabled for. Use the erlang:trace_pattern/3 BIF to enable tracing
for functions. Message tags: call,
return_from.

silent

To be used in conjunction with the 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.
The silent mode can, of course, be inhibited
by executing erlang:trace/3 without
the silent flag, but also by a match spec executing
the {silent, false} function.

return_to

Traces the actual return of a process from a traced
function back to its caller. This return trace only works
together with call trace and functions traced with
the 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.
To get trace messages containing return values from
functions, use the {return_trace} match_spec
action instead.
Message tags: return_to.

Make a time stamp in all trace messages. The time stamp
(Ts) is of the same form as returned by
erlang:now().

cpu_timestamp

A global trace flag for the Erlang node that makes all
trace timestamps be in CPU time, not wallclock. It is
only allowed with PidSpec==all. If the host
machine operating system does not support high resolution
CPU time measurements, trace/3 exits with
badarg.

arity

Instead of {Mod, Fun, Args} in call traces, there
will be {Mod, Fun, Arity}.

set_on_spawn

Makes any process created by Pid inherit
the flags of Pid, including the set_on_spawn
flag.

set_on_first_spawn

Makes the first process created by Pid
inherit the flags of Pid That process does not
inherit the set_on_first_spawn flag.

set_on_link

Makes any process linked by Pid inherit the flags
of Pid, including the set_on_link flag.

set_on_first_link

Makes the first process linked to by 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}

When the traced Pid receives something.

{trace, Pid, send, Msg, To}

When Pid sends a message.

{trace, Pid, send_to_non_existing_process, Msg, To}

When Pid sends a message to a non existing
process.

{trace, Pid, call, {M,F,A}}

When 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}}

When 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}

When 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}}

When Pid spawns a new process Pid2.
{M, F, A} are the initial function call with
arguments for the new process.
Note that A is supposed to be the argument list,
but may be any term in the case of an erroneous spawn.

{trace, Pid, exit, Reason}

When Pid exits with reason Reason.

{trace, Pid, link, Pid2}

When Pid links to a process Pid2.

{trace, Pid, unlink, Pid2}

When Pid removes the link from a process
Pid2.

{trace, Pid, getting_linked, Pid2}

When Pid gets linked to a process Pid2.

{trace, Pid, getting_unlinked, Pid2}

When Pid gets unlinked from a process Pid2.

{trace, Pid, register, Name}

When Pid gets the name Name registered.

{trace, Pid, unregister, Name}

When Pid gets the name Name unregistered.
Note that this is done automatically when a registered
process exits.

{trace, Pid, in, {M,F,A} | 0}

When 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}

When 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}

Sent when garbage collection is about to be started.
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

The size of the used part of the heap.

old_heap_size

The size of the used part of the old heap.

stack_size

The actual size of the stack.

recent_size

The size of the data that survived the previous garbage
collection.

mbuf_size

The combined size of message buffers associated with
the process.

All sizes are in words.

{trace, Pid, gc_end, Info}

Sent when garbage collection is finished. 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.

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

Return a list of atoms indicating what kind of traces is
enabled for the process. The list will be empty if no
traces are enabled, and one or more of the followings
atoms if traces are enabled: 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

Return the identifier for process or port tracing this
process. If this process is not being traced, the return
value will be [].

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

Return 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

Return the match specification for this function, if it
has one. If the function is locally or globally traced but
has no match specification defined, the returned value
is [].

meta

Return the meta trace tracer process or port for this
function, if it has one. If the function is not meta
traced the returned value is 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

Return the meta trace match specification for this
function, if it has one. If the function is meta traced
but has no match specification defined, the returned
value is [].

call_count

Return the call count value for this function or
true for the pseudo function on_load if call
count tracing is active. Return false otherwise.
See also
erlang:trace_pattern/3
.

all

Return a list contaning the {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.

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,'_'}

All exported functions of any arity named Func
in module Mod.

{Mod,'_','_'}

All exported functions in module Mod.

{'_','_','_'}

All exported functions in all loaded modules.

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

Disable tracing for the matching function(s). Any match
specification will be removed.

true

Enable tracing for the matching function(s).

MatchSpecList

A list of match specifications. An empty list is
equivalent to true. See the ERTS User's Guide
for a description of match specifications.

restart

For the FlagList option call_count:
restart the existing counters. The behaviour is undefined
for other FlagList options.

pause

For the 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

Turn on or off call tracing for global function calls
(i.e., calls specifying the module explicitly). Only
exported functions will match and only global calls will
generate trace messages. This is the default.

local

Turn on or off call tracing for all types of function
calls. Trace messages will be sent whenever any of
the specified functions are called, regardless of how they
are called. If the 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}

Turn on or off meta tracing for all types of function
calls. Trace messages will be sent to the tracer process
or port 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.
Meta tracing traces all processes and does not care
about the process trace flags set by trace/3,
the trace flags are instead fixed to
[call, timestamp].
The match spec function {return_trace} works with
meta trace and send its trace message to the same tracer
process.

call_count

Starts (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.
If call count tracing is started while already running,
the count is restarted from zero. Running counters can be
paused with MatchSpec == pause. Paused and running
counters can be restarted from zero with
MatchSpec == restart.
The counter value can be read with
erlang:trace_info/2
.

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.

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().

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}}.