erlang(3)

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

A few BIFs may be used in guard tests, for example:
tuple_5(Something) when size(Something) == 5 ->
    is_tuple_size_5;
tuple_5(_) ->
    is_something_else.

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:
tuple_5(Something) ->
    case size(Something) of
         5 -> is_tuple_size_5;
                 _ -> is_something_else
            end.

In this case, size/1 is not in a guard. If Something is not a tuple, size/1 will fail and cause the process to exit with the associated reason badarg (see above).

Some of the BIFs in this chapter are optional in Erlang implementations, and not all implementations will include them.

The following descriptions indicate which BIFs can be used in guards and which BIFs are optional.

EXPORTS

abs(Number)

    Returns an integer or float which is the arithmetical absolute value of the argument Number (integer or float).
    > abs(-3.33).
    3.33000
    > abs(-3).
    3

    This BIF is allowed in guard tests.

    Failure: badarg if the argument is not an integer or a float.

apply({Module, Function}, ArgumentList)

    This is equivalent to apply(Module, Function, ArgumentList).

apply(Module, Function, ArgumentList)

    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.

atom_to_list(Atom)

    Returns a list of integers (Latin-1 codes), which corresponds to the text representation of the argument Atom.
    >atom_to_list('Erlang').
    "Erlang"

    Failure: badarg if the argument is not an atom.

binary_to_list(Binary)

    Returns a list of integers which correspond to the bytes of Binary.

binary_to_list(Binary, Start, Stop)

    As binary_to_list/1, but it only returns the list from position Start to position Stop. Start and Stop are integers. Positions in the binary are numbered starting from 1.

binary_to_term(Binary)

    Returns an Erlang term which is the result of decoding the binary Binary. Binary is encoded in the Erlang external binary representation. See term_to_binary/1.

erlang:cancel_timer(Ref)

    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:
            cancel_timer(Ref),
            receive
                {timeout, Ref, _} ->
                    ok
            after 0 ->
                    ok
            end

    Failure: badarg if Ref isn't a reference.

erlang:check_process_code(Pid, Module)

    Returns true if the process Pid is executing an old version of Module, if the current call of the process executes code for an old version of the module, or if the process has references to an old version of the module. Otherwise, it returns false.
    > erlang:check_process_code(Pid, lists).
    false

    This is an optional BIF.

    Failure: badarg, if the argument is not a Pid.

concat_binary(ListOfBinaries)

    Concatenates a list of binaries ListOfBinaries into one binary.

date()

    Returns the current date as {Year, Month, Day}
    > date().
    {1995, 2, 19}

erlang:delete_module(Module)

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

  Warning:

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.

erlang:disconnect_node(Node)

    Forces the disconnection of a node. This will appear to the node Node as if the current node has crashed. This BIF is mainly used in the Erlang network authentication protocols. Returns true if disconnection succeeds, otherwise false.

    Failure: badarg if Node is not an atom.

element(N, Tuple)

    Returns the Nth element (numbering from 1) of Tuple.
    > element(2, {a, b, c}).
    b

    Failure: badarg if N < 1, or N > size(Tuple), or if the argument Tuple is not a tuple. Allowed in guard tests.

erase()

    Returns the process dictionary and deletes it.
    > put(key1, {1, 2, 3}), put(key2, [a, b, c]), erase().
    [{key1,{1, 2, 3}},{key2,[a, b, c]}]

erase(Key)

    Returns the value associated with Key and deletes it from the process dictionary. Returns undefined if no value is associated with Key. Key can be any Erlang term.
    > put(key1, {merry, lambs, are, playing}),
      X = erase(key1), {X, erase(key1)}.
    {{merry, lambs, are, playing}, undefined}

exit(Reason)

    Stops the execution of the current process with the reason Reason. Can be caught. Reason is any Erlang term. Since evaluating this function causes the process to terminate, it has no return value.
    > exit(foobar).
    ** exited: foobar **
    > catch exit(foobar).
    {'EXIT', foobar}

exit(Pid, Reason)

    Sends an EXIT message to the process Pid. Returns true.
    > exit(Pid, goodbye).
    true

  Note:

The above is not necessarily the same as:
Pid ! {'EXIT', self(), goodbye}

The above two alternatives are the same if the process with the process identity Pid is trapping exits. However, if Pid is not trapping exits, 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.

Returns true.

Failure: badarg if Pid is not a Pid.

float(Number)

    Returns a float by converting Number to a float.
    > float(55).
    55.0000

  Note:

float/1 is allowed in guard tests, but it tests whether the argument is a float or not.
-module(t).
f(F) when float(F) -> float;
f(F) -> not_a_float.
1> t:f(1).
not_a_float
2> t:f(1.0).
float
3>

Failure: badarg if the argument is not a float or an integer.

float_to_list(Float)

    Returns a list of integers (ASCII codes) which corresponds to Float.
    > float_to_list(7.0).
    "7.00000000000000000000e+00"

    Failure: badarg if the argument is not a float.

get()

    Returns the process dictionary as a list of {Key, Value} tuples.
    > put(key1, merry), put(key2, lambs),
      put(key3, {are, playing}), get().
    [{key1, merry}, {key2, lambs}, {key3, {are, playing}}]

get(Key)

    Returns the value associated with Key in the process dictionary, and undefined if no value is associated with Key. Key can be any Erlang term.
    > put(key1, merry), put(key2, lambs),
      put({any, [valid, term]}, {are, playing}),
      get({any, [valid, term]}).
    {are, playing}

erlang:get_cookie()

    Returns the "magic cookie" of the current node, if the node is alive; otherwise the atom nocookie.

get_keys(Value)

    Returns a list of keys which corresponds to Value in the process dictionary.
    > put(mary, {1, 2}), put(had, {1, 2}), put(a, {1, 2}),
      put(little, {1, 2}), put(dog, {1, 3}), put(lamb, {1, 2}),
      get_keys({1, 2}).
    [mary, had, a, little, lamb]

group_leader()

    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.

group_leader(Leader, Pid)

    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.

halt()

    Halts the Erlang system and indicates normal exit to the calling environment. Has no return value.
    > halt().
    unix_prompt%

halt(Status)

    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.

erlang:hash(Term, Range)

    Returns a hash value for Term within the range 1..Range.

hd(List)

    Returns the first item of List.
    > hd([1,2,3,4,5]).
    1

    Allowed in guard tests.

    Failure: badarg if List is the empty list [], or is not a list.

erlang:info(What)

    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.

    Failure: badarg if What is not one of the atoms shown above.

integer_to_list(Integer)

    Returns a list of integers (ASCII codes) which correspond to Integer.
    > integer_to_list(77).
    "77"

    Failure: badarg if the argument is not an integer.

is_alive()

    Returns the atom true if the current node is alive; i.e., if the node can be part of a distributed system. Otherwise, it returns the atom false.

length(List)

    Returns the length of List.
    > length([1,2,3,4,5,6,7,8,9]).
    9

    Allowed in guard tests.

    Failure: badarg if the argument is not a proper list.

link(Pid)

    Creates a link to the process (or port) Pid, if there is not such a link already. If a process attempts to create a link to itself, nothing is done. Returns true.

    Failure: badarg if the argument is not a Pid or port. Sends the EXIT signal noproc to the process which evaluates link if the argument is the Pid of a process which does not exist.

list_to_atom(CharIntegerList)

    Returns an atom whose text representation is the integers (Latin-1 codes) in CharIntegerList.
    > list_to_atom([69, 114, 108, 97, 110, 103]).
    'Erlang'

    Failure: badarg if the argument is not a list of integers, or if any integer in the list is not an integer in the range [0, 255].

list_to_binary(ListOfIntegers)

    Returns a binary which is made from the integer list ListOfIntegers.

    Failure: badarg if the argument is not a list of integers, or if any integer in the list is not an integer in the range [0, 255].

list_to_float(AsciiIntegerList)

    Returns a float whose text representation is the integers (ASCII-values) in AsciiIntegerList.
    > list_to_float([50,46,50,48,49,55,55,54,52,101,43,48]).
    2.20178

    Failure: badarg if the argument is not a list of integers, or if AsciiIntegerList contains a bad representation of a float.

list_to_integer(AsciiIntegerList)

    Returns an integer whose text representation is the integers (ASCII-values) in AsciiIntegerList.
    > list_to_integer([49, 50, 51]).
    123

    Failure: badarg if the argument is not a list of integers, or if AsciiIntegerList contains a bad representation of an integer.

list_to_pid(AsciiIntegerList)

    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.

list_to_tuple(List)

    Returns a tuple which corresponds to List. List can contain any Erlang terms.
    > list_to_tuple([mary, had, a, little, {dog, cat, lamb}]).
    {mary, had, a, little, {dog, cat, lamb}}

    Failure: badarg if List is not a proper list.

erlang:load_module(Module, Binary)

    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

  Warning:

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.

erlang:localtime()

    Returns the current local date and time {{Year, Month, Day}, {Hour, Minute, Second}}.

    The time zone and daylight saving time correction depend on the underlying OS.
    > erlang:localtime().
    {{1996,11,6},{14,45,17}}

erlang:localtime_to_universaltime(DateTime)

    Converts local date and time in DateTime to Universal Time Coordinated (UTC), if this is supported by the underlying OS. Otherwise, no conversion is done and DateTime is returned. The return value is of the form {{Year, Month, Day}, {Hour, Minute, Second}}.

    Failure: badarg if the argument is not a valid date and time tuple {{Year, Month, Day}, {Hour, Minute, Second}}.
    > erlang:localtime_to_universaltime({{1996,11,6},{14,45,17}}).
    {{1996,11,6},{13,45,17}}

make_ref()

    Returns a unique reference.
    > make_ref().
    #Ref

erlang:module_loaded(Module)

    Returns the atom true if the module contained in atom Module is loaded, otherwise it returns the atom false. It does not attempt to load the module.

  Warning:

This BIF is intended for the implementation of the module named code and should not be used anywhere else. Use code:is_loaded/1 instead.
> erlang:module_loaded(lists).
true

This is an optional BIF.

Failure: badarg if the argument is not an atom.

monitor_node(Node, Flag)

    Monitors the status of the node Node. If Flag is true, monitoring is turned on; if Flag is false, monitoring is turned off. Calls to the BIF are accumulated. This is shown in the following example, where a process is already monitoring the node Node and a library function is called:
    monitor_node(Node, true),
        ...  some operations
    monitor_node(Node, false),

    After the call, the process is still monitoring the node.

    If Node fails or does not exist, the message {nodedown, Node} is delivered to the process. If a process has made two calls to monitor_node(Node, true) and Node terminates, two nodedown messages are delivered to the process. If there is no connection to Node, there will be an attempt to create one. If this fails, a nodedown message is delivered.

    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.

node()

    Returns the name of the current node. If it is not a networked node but a local Erlang system, the atom nonode@nohost is returned.

    Allowed in guard tests.

node(Arg)

    Returns the node where Arg is located. Arg can be a Pid, a reference, or a port.

    Allowed in guard tests.

    Failure: badarg if Arg is not a Pid, reference, or port.

nodes()

    Returns a list of all known nodes in the system, excluding the current node.

now()

    Returns the tuple {MegaSecs, Secs, Microsecs}

    which is the elapsed time since 00:00 GMT, January 1, 1970 (zero hour) on the assumption that the underlying OS supports this. Otherwise, some other point in time is chosen. It is also guaranteed that subsequent calls to this BIF returns continuously increasing values. Hence, the return value from now() can be used to generate unique time-stamps. It can only be used to check the local time of day if the time-zone info of the underlying operating system is properly configured.

open_port(PortName, PortSettings)

    Returns a port identifier as the result of opening a new Erlang port. A port can be seen as an external Erlang process. PortName is one of the following:

        {spawn, Command}:
            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. 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.

pid_to_list(Pid)

    Returns a list which corresponds to the process Pid.

  Warning:

This BIF is intended for debugging and for use in the Erlang operating system. It should not be used in application programs.
> pid_to_list(whereis(init)).
"<0.0.0>"

Failure: badarg if the argument is not a Pid.

erlang:port_info(Port, Item)

    Returns information about the port Port as specified by Item, which can be any one of the atoms id, connected, links, name, input, or output.

        {id, Index}:
            Index is the internal index of the port. This index may be used to separate ports.

        {connected, Pid}:
            Pid is the process connected to the port.

        {links, ListOfPids}:
            ListOfPids is a list of Pids with processes to which the port has a link.

        {name, String}:
            String is the command name set by open_port.

        {input, Bytes}:
            Bytes is the total number of bytes read from the port.

        {output, Bytes}:
            Bytes is the total number of bytes written to the port.

    All implementations may not support all of the above Items. Returns undefined if the port does not exist.

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

erlang:ports()

    Returns a list of all ports on the current node.

erlang:pre_loaded()

    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.

process_flag(Flag, Option)

    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.

process_info(Pid)

    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.

process_info(Pid, Item)

    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.

processes()

    Returns a list of all processes on the current node.
    > processes().
    [<0.0.1>, <0.1.1>, <0.2.1>, <0.3.1>, <0.4.1>, <0.6.1>]

erlang:purge_module(Module)

    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.

  Warning:

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.

This is an optional BIF.

Failure: badarg if Module does not exist.

put(Key, Value)

    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.

  Note:

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.
> X = put(name, walrus), Y = put(name, carpenter),
  Z = get(name),
  {X, Y, Z}.
{undefined, walrus, carpenter}

register(Name, Pid)

    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.

registered()

    Returns a list of names which have been registered using register/2.
    > registered().
    [code_server, file_server, init, user, my_db]

round(Number)

    Returns an integer by rounding the number Number. Allowed in guard tests.
    > round(5.5).
    6

    Failure: badarg if the argument is not a float (or an integer).

self()

    Returns the process identity of the calling process. Allowed in guard tests.
    > self().
    <0.16.1>

erlang:send_after(Time, Pid, Msg)

    Time is a non-negative integer, Pid is either a pid or an atom, and Msg is any Erlang term. The function returns a reference.

    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.

erlang:set_cookie(Node, Cookie)

    Sets the "magic cookie" of Node to the atom Cookie. If Node is the current node, the BIF also sets the cookie of all other unknown nodes to Cookie (see auth(3)).

setelement(Index, Tuple, Value)

    Returns a tuple which is a copy of the argument Tuple with the element given by the integer argument Index (the first element is the element with index 1) replaced by the argument Value.
    > setelement(2, {10, green, bottles}, red).
    {10, red, bottles}

    Failure: badarg if Index is not an integer, or Tuple is not a tuple, or if Index is less than 1 or greater than the size of Tuple.

size(Item)

    Returns an integer which is the size of the argument Item, where Item must be either a tuple or a binary.
    > size({morni, mulle, bwange}).
    3

    Allowed in guard tests.

    Failure: badarg if Item is not a tuple or a binary.

spawn(Module, Function, ArgumentList)

    Returns the Pid of a new process started by the application of Module:Function to ArgumentList. Note: The new process created will be placed in the system scheduler queue and will be run some time later.

    error_handler:undefined_function(Module, Function, ArgumentList) is evaluated by the new process if Module:Function/Arity does not exist (where Arity is the length of ArgumentList). The error handler can be redefined (see BIF process_flag/2)). Arity is the length of 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.

spawn(Node, Module, Function, ArgumentList)

    Works like spawn/3, with the exception that the process is spawned at Node. If Node does not exist, a useless Pid is returned.

    Failure: badarg if Node, Module, or Function are not atoms, or ArgumentList is not a list.

spawn_link(Module, Function, ArgumentList)

    This BIF is identical to the following code being evaluated in an atomic operation:
    > Pid = spawn(Module, Function, ArgumentList),
      link(Pid),
      Pid.

    This BIF is necessary since the process created might run immediately and fail before link/1 is called.

    Failure: See spawn/3.

spawn_link(Node, Module, Function, ArgumentList)

    Works like spawn_link/3, except that the process is spawned at Node. If an attempt is made to spawn a process on a node which does not exist, a useless Pid is returned, and an EXIT signal will be received.

spawn_opt(Module, Function, ArgumentList, Options)

    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.

split_binary(Binary, Pos)

    Returns a tuple which contains two binaries which are the result of splitting Binary into two parts at position Pos. This is not a destructive operation. After this operation, there are three binaries altogether. Returns a tuple consisting of the two new binaries. For example:
    1> B = list_to_binary("0123456789").
    #Bin
    2> size(B).
    10
    3> {B1, B2} = split_binary(B,3).
    {#Bin, #Bin}
    4> size(B1).
    3
    5> size(B2).
    7

    Failure: badarg if Binary is not a binary, or Pos is not an integer or is out of range.

erlang:start_timer(Time, Pid, Msg)

    Time is a non-negative integer, Pid is either a pid or an atom, and Msg is any Erlang term. The function returns a reference.

    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.

statistics(Type)

    Returns information about the system. Type is an atom which is one of:

        run_queue:
            Returns the length of the run queue, that is the number of processes that are ready to run.

        runtime:
            Returns {Total_Run_Time, Time_Since_Last_Call}.

        wall_clock:
            Returns {Total_Wallclock_Time, Wallclock_Time_Since_Last_Call}. wall_clock can be used in the same manner as the atom runtime, except that real time is measured as opposed to runtime or CPU time.

        reductions:
            Returns {Total_Reductions, Reductions_Since_Last_Call}.

        garbage_collection:
            Returns {Number_of_GCs, Words_Reclaimed, 0}. This information may not be valid for all implementations.

    All times are in milliseconds.
    > statistics(runtime).
    {1690, 1620}
    > statistics(reductions).
    {2046, 11}
    > statistics(garbage_collection).
    {85, 23961, 0}

    Failure: badarg if Type is not one of the atoms shown above.

term_to_binary(Term)

    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.

throw(Any)

    A non-local return from a function. If evaluated within a catch, catch will return the value Any.
    > catch throw({hello, there}).
    {hello, there}

    Failure: nocatch if not evaluated within a catch.

time()

    Returns the tuple {Hour, Minute, Second} of the current system time. The time zone correction is implementation-dependent.
    > time().
    {9, 42, 44}

tl(List)

    Returns List stripped of its first element.
    > tl([geesties, guilies, beasties]).
    [guilies, beasties]

    Failure: badarg if List is the empty list [], or is not a list. Allowed in guard tests.

trace(Pid, How, Flaglist)

    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.

    Tracing of processes which trace other processes is not allowed.

    Failure: badarg if bad arguments are given.

trunc(Number)

    Returns an integer by the truncation of Number. Allowed in guard tests.
    > trunc(5.5).
    5

    Failure: badarg if the argument is not a float, or an integer.

tuple_to_list(Tuple)

    Returns a list which corresponds to Tuple. Tuple may contain any valid Erlang terms.
    > tuple_to_list({share, {'Ericsson_B', 163}}).
    [share, {'Ericsson_B', 163}]

    Failure: badarg if the argument is not a tuple.

erlang:universaltime()

    Returns the current date and time according to Universal Time Coordinated (UTC), also called GMT, in the form {{Year, Month, Day}, {Hour, Minute, Second}} if supported by the underlying operating system. If not, erlang:universaltime() is equivalent to erlang:localtime().
    > erlang:universaltime().
    {{1996,11,6},{14,18,43}}

erlang:universaltime_to_localtime(DateTime)

    Converts UTC date and time in DateTime to local date and time if supported by the underlying operating system. Otherwise, no conversion is done, and DateTime is returned. The return value is of the form {{Year, Month, Day}, {Hour, Minute, Second}}.

    Failure: badarg if the argument is not a valid date and time tuple {{Year, Month, Day}, {Hour, Minute, Second}}.
    > erlang:universaltime_to_localtime({{1996,11,6},{14,18,43}}).
    {{1996,11,7},{15,18,43}}

unlink(Pid)

    Removes a link, if there is one, from the calling process to another process given by the argument Pid.

    Returns true. Will not fail if not linked to Pid, or if Pid does not exist.

    Failure: badarg if the argument is not a valid Pid.

unregister(Name)

    Removes the registered name for a process, given by the atom argument Name.

    Returns the atom true.
    > unregister(db).
    true

    Failure: badarg if Name is not the name of a registered process.

    Users are advised not to unregister system processes.

whereis(Name)

    Returns the Pid for the process registered under Name (see register/2). Returns undefined if no such process is registered.
    > whereis(user).
    <0.3.1>

    Failure: badarg if the argument is not an atom.

AUTHORS
Joe Armstrong - joe@erix.ericsson.se
Mike Williams - mike@erix.ericsson.se
Robert Virding - rv@erix.ericsson.se
Claes Wikstrom - klacke@erix.ericsson.se