erlang

MODULE

MODULE SUMMARY

The Erlang BIFs

DESCRIPTION

By convention, Built In Functions (BIFs) are seen as being in the module
erlang. Thus, both the calls atom_to_list(Erlang)
and erlang:atom_to_list(Erlang) are identical.

BIFs may fail for a variety of reasons. All BIFs fail if they
are called with arguments of an incorrect type. For example,
atom_to_list/1 will fail if it is called with an argument
which is not an atom. If this type of failure is not within the
scope of a catch (and the BIF is not called within a guard; see
below), it will cause the process making the call to exit and an
EXIT signal with the associated reason badarg will be sent
to all linked processes. The other reasons BIFs may fail
are described in connection with the description of each
individual BIF.

Here the BIF size/1 is used in a guard. If size/1
is called with a tuple, it will return the size of the tuple
(i.e., how many elements there are in the tuple). In the above example,
size/1 is used in a guard which tests if its
argument Something is a tuple and, if it is, whether it is
of size 5. In this case, calling size with an argument other than
a tuple will cause the guard to fail and execution will continue
with the next clause. Suppose tuple_5/1 is written as
follows:

Returns the result of applying Function in
Module on 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"

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.

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 may
mean 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 doesn't guarantee
that the message hasn't 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, or if the
process has references to an old version of the module.
Otherwise, it returns false.

Moves 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

This is an optional BIF.

Failure: badarg if there is already an old version of
the module (see BIF purge_module/1).

In normal Erlang implementations code handling - which includes loading, deleting, and replacing modules - is performed in the module code. This BIF is intended for use with the implementation of the module code and should not be used elsewhere.

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.

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, the
Pid itself will exit and propagate EXIT signals in
turn to its linked processes.

If the reason is the atom kill, for example
exit(Pid, kill), an untrappable EXIT signal will be
sent to the process Pid. In other words, the process
Pid will be unconditionally killed.

Every process is a member of some process group and all groups
have a leader.

This BIF returns the process identifier Pid of the group
leader for the process which evaluates the BIF. When a 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 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.

This BIF is optional and may be removed or changed in
future releases of Erlang. What can be any of the
atoms info, procs, loaded, or dist.
The BIF returns information of the different `topics' as
binary data objects.

Returns a Pid whose text representation is the integers
(ASCII-values) in AsciiIntegerList. This BIF
is intended for debugging, and 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 the argument is not a list of
integers, or AsciiIntegerList contains a bad
representation of a Pid.

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
load fails. Reason is one of the following:

badfile

If the object code in Binary has an incorrect format.

not_purged

If 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

If the object code contains code for another module
than Module

Code handling - which includes
loading, deleting, and replacing of modules - is done by
the module code in normal Erlang implementations. This BIF is intended for the implementation of the module named code and should not
be used elsewhere.

This is an optional BIF.

Failure: badarg if the first argument is not an atom,
or the second argument is not a binary.

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 the argument is not a valid date and
time tuple {{Year, Month, Day}, {Hour, Minute, Second}}.

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.

Returns true.

Failure: badarg if Flag is not true or
false,
and badarg if Node is not an atom indicating a
remote node, or if the local node isn't alive.

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 filemodule instead.
The atom is assumed to be the name of an
external resource. A transparent connection is
established between Erlang and the resource named by the
atom Atom. The characteristics of the port depend
on the type of resource. If Atom represents a
normal file, the entire contents of the file is sent to
the Erlang process as one or more messages. When
messages are sent to the port, it causes data to be
written to the file.

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

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
exit signals of the form {'EXIT', Port, PosixCode}. Posix codes
are listed in the documentation for the file module.

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.

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

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.

Returns a long list which contains information about the
process Pid. This BIF is only intended for
debugging. It should not be used for any other purpose. The list returned contains the following tuples. The order in which these tuples are returned is not defined, nor are all the tuples mandatory.

{registered_name, Atom}

Atom is the registered name of the process (if any).

{current_function, {Module, Function, Arguments}}

Module, Function, Arguments is the
current function call of the process.

{initial_call, {Module, Function, Arity}}

Module, Function, Arity is the
initial function call with which the process was
spawned.

{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 trace/3
BIF).

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

{links, ListOfPids}

ListOfPids is a list of Pids, with processes to
which the process has a link.

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

{trap_exit, Boolean}

Boolean is true if the process is trapping
exits, otherwise it is false.

{stack_size, Size}

Size is the stack size of the process in stack words.

{heap_size, Size}

Size is the heap size of the process in heap words.

{reductions, Number}

Number is the number of reductions executed by
the process.

{group_leader, Groupleader}

Groupleader is group leader for the I/O of the
process.

{priority, Level}

Level is the current priority level for the
process. Only low and normal are always
supported.

Failure: badarg if the argument is not a Pid, or
if Pid is a Pid of a remote process.

Returns information about the process Pid as specified by
Item, which can be any one of the atoms
registered_name, current_function,
initial_call, status, messages,
message_queue_len, memory,
links, dictionary, trap_exit,
error_handler, heap_size, group_leader,
priority, stack_size, or reductions.

Not all implementations support every one of the above
Items. Returns undefined if the process does not
exist.

Item memory returns {memory, Size}, where Size
is the size of the process in bytes. This includes stack, heap and
internal structures.

Failure: badarg if Pid is not a process
identifier, or if Pid is a process identifier of a
remote process.

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.

In normal Erlang implementations, code handling - which is
loading, deleting and replacing modules - is evaluated
by the module code. This BIF is intended to be
used by the implementation of the module code and should
not be used in any other place.

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.

Associates the name Name with the process identity
Pid.
Name, which must be an atom, can be used instead of a pid
in the send operator (Name ! Message).

Returns true.

Failure: badarg if Pid is not an active
process, or if Pid is a process on another node,
or if the name Name is already in use,
or if the process is already registered (it already has a name),
or if the name Name is not an atom, or if Name
is the atom undefined.

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.

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 doesn't refer to a process. See also
start_timer/3 and cancel_timer/1.

Limitations: Pid must be a process on the
local node. Only a smallint (27 bits) can be used for the
timeout value.

Failure: badarg if any arguments are of the
wrong type, or do not obey the limitations noted above.

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 the
ArgumentList. If error_handler is undefined,
or the user has redefined the default error_handler
so 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 the following options can be given when creating the process:

link

Sets a link to the parent process (link 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.

{gc_switch, Threshold}

Sets the garbage collection strategy for the new process.
If Threshold is 0, generational garbage collection will be
used (this is default). If Threshold is greater than zero,
the fullsweep algorithm will be until the amount of live data (counted
in words) reaches Threshold, at which point generational collection
will be used. A large Threshold or the atom infinity means
the fullsweep algorithm will be used.
Note: Generation collection is generally faster, especially for processes
with a large amount of live data, but requires more memory since two heaps
are allocated.

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

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, Pid 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 Pid, where
Ref is the reference returned by
start_timer/3.

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 doesn't refer to a process. See also
send_after/3<C> and <C>cancel_timer/1.

Limitations: Pid must be a process on the
local node. Only a smallint (27 bits) can be used for the
timeout value.

Failure: badarg if any arguments are of the
wrong type, or do not obey the limitations noted above.

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.

Turns on tracing (if How == true) for the process
Pid for all the trace items present in
Flaglist. If How == false, the items in Flaglist
are turned off.

Flaglist can contain any number of the following
atoms:

send

Traces the messages the process Pid sends.

receive

Traces the messages the process Pid receives.

set_on_spawn

Makes any process created by Pid inherit the
flags of Pid.

set_on_first_spawn

The same as above, but only for the first process
created by Pid.

set_on_link

Makes any process linked by Pid inherit the flags
of Pid.

set_on_first_link

Makes the first process linked to by Pid inherit
the flags of Pid.

procs

Traces process related events, for example spawn,
link, exit.

bifs

Traces calls to BIFs.

call

Traces function calls. This flag only works for code
that has been trace-compiled.

running

Traces scheduling of processes.

garbage_collection

Traces garbage collections of processes.

timestamp

Make a time stamp in all trace messages. When a time stamp
is used, traces on form {Mod, Fun, Args} are always converted
to {Mod, Fun, Arity}. The time stamp (Ts) is on the form as
returned by erlang:now().

suspend

Suspend/resume the process.

The tracing process receives messages of the form:

{trace, 'receive', Pid, Message [,Ts]}

When the traced Pid receives something.

{trace, send, Msg, Pid, To [,Ts]}

When Pid sends a message.

{trace, send_to_non_existing_process, Mes, Pid, To [,Ts]}

When Pid send a message to a non existing process.

{trace, Pid, call, {M, F, A} [,Ts]}

When Pid makes a function/BIF call. The return values
of calls are never supplied, only the call and its
arguments.

{trace, Pid, return, {M,F,A}, Ts}

When Pid returns to function {M,F,A}. This
trace message is only sent when both flag calls and
timestamp are used.

{trace, Pid, spawn, Pid2 [,Ts]}

When Pid spawns a new process Pid2.

{trace, Pid, exit, Reason [,Ts]}

When Pid exits with reason Reason.

{trace, Pid, link, Pid2 [,Ts]}

When Pid links to a process Pid2.

{trace, Pid, unlink, Pid2 [,Ts]}

When Pid removes the link from a process Pid2.

{trace, Pid, getting_linked, Pid2 [,Ts]}

When Pid gets linked to a process Pid2.

{trace, Pid, in, {M,F,A} [,Ts]}

When Pid is scheduled to run. The process will
run in function {M,F,A}, where A always is the arity.

{trace, Pid, out, {M,F,A} [,Ts]}

When Pid is scheduled out. The process where
running in function {M,F,A} where A always is the arity.

{trace, Pid, gc_start, Info, [,Ts]}

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 the 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, [,Ts]}

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

Failure: badarg if the argument is not a valid date and
time tuple {{Year, Month, Day}, {Hour, Minute, Second}}.