1
<?xml version="1.0" encoding="latin1" ?>
2
<!DOCTYPE erlref SYSTEM "erlref.dtd">
9
<holder>Ericsson AB, All Rights Reserved</holder>
12
The contents of this file are subject to the Erlang Public License,
13
Version 1.1, (the "License"); you may not use this file except in
14
compliance with the License. You should have received a copy of the
15
Erlang Public License along with this software. If not, it can be
16
retrieved online at http://www.erlang.org/.
18
Software distributed under the License is distributed on an "AS IS"
19
basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
20
the License for the specific language governing rights and limitations
23
The Initial Developer of the Original Code is Ericsson AB.
32
<module>erlang</module>
33
<modulesummary>The Erlang BIFs</modulesummary>
35
<p>By convention, most built-in functions (BIFs) are seen as being
36
in the module <c>erlang</c>. A number of the BIFs are viewed more
37
or less as part of the Erlang programming language and are
38
<em>auto-imported</em>. Thus, it is not necessary to specify
39
the module name and both the calls <c>atom_to_list(Erlang)</c> and
40
<c>erlang:atom_to_list(Erlang)</c> are identical.</p>
41
<p>In the text, auto-imported BIFs are listed without module prefix.
42
BIFs listed with module prefix are not auto-imported.</p>
43
<p>BIFs may fail for a variety of reasons. All BIFs fail with
44
reason <c>badarg</c> if they are called with arguments of an
45
incorrect type. The other reasons that may make BIFs fail are
46
described in connection with the description of each individual
48
<p>Some BIFs may be used in guard tests, these are marked with
49
"Allowed in guard tests".</p>
53
<title>DATA TYPES</title>
54
<marker id="iolist_definition"></marker>
58
structured according to the Erlang external term format
60
iodata() = iolist() | binary()
62
iolist() = [char() | binary() | iolist()]
63
a binary is allowed as the tail of the list</code>
67
<name>abs(Number) -> int() | float()</name>
68
<fsummary>Arithmetical absolute value</fsummary>
70
<v>Number = number()</v>
73
<p>Returns an integer or float which is the arithmetical
74
absolute value of <c>Number</c>.</p>
76
> <input>abs(-3.33).</input>
78
> <input>abs(-3).</input>
80
<p>Allowed in guard tests.</p>
84
<name>adler32(Data) -> int()</name>
85
<fsummary>Compute adler32 checksum</fsummary>
87
<v>Data = iodata()</v>
90
<p>Computes and returns the adler32 checksum for <c>Data</c>.</p>
94
<name>adler32(OldAdler, Data) -> int()</name>
95
<fsummary>Compute adler32 checksum</fsummary>
97
<v>OldAdler = int()</v>
98
<v>Data = iodata()</v>
101
<p>Continue computing the adler32 checksum by combining
102
the previous checksum, <c>OldAdler</c>, with the checksum of
104
<p>The following code:</p>
107
Y = adler32(X,Data2).
109
<p>- would assign the same value to <c>Y</c> as this would:</p>
111
Y = adler32([Data1,Data2]).
116
<name>adler32_combine(FirstAdler, SecondAdler, SecondSize) -> int()</name>
117
<fsummary>Combine two adler32 checksums</fsummary>
119
<v>FirstAdler = SecondAdler = int()</v>
120
<v>SecondSize = int()</v>
123
<p>Combines two previously computed adler32 checksums.
124
This computation requires the size of the data object for
125
the second checksum to be known.</p>
126
<p>The following code:</p>
129
Z = adler32(Y,Data2).
131
<p>- would assign the same value to <c>Z</c> as this would:</p>
135
Z = adler32_combine(X,Y,iolist_size(Data2)).
140
<name>erlang:append_element(Tuple1, Term) -> Tuple2</name>
141
<fsummary>Append an extra element to a tuple</fsummary>
143
<v>Tuple1 = Tuple2 = tuple()</v>
147
<p>Returns a new tuple which has one element more than
148
<c>Tuple1</c>, and contains the elements in <c>Tuple1</c>
149
followed by <c>Term</c> as the last element. Semantically
151
<c>list_to_tuple(tuple_to_list(Tuple ++ [Term])</c>, but much
154
> <input>erlang:append_element({one, two}, three).</input>
155
{one,two,three}</pre>
159
<name>apply(Fun, Args) -> term() | empty()</name>
160
<fsummary>Apply a function to an argument list</fsummary>
163
<v>Args = [term()]</v>
166
<p>Call a fun, passing the elements in <c>Args</c> as
168
<p>Note: If the number of elements in the arguments are known at
169
compile-time, the call is better written as
170
<c>Fun(Arg1, Arg2, ... ArgN)</c>.</p>
172
<p>Earlier, <c>Fun</c> could also be given as
173
<c>{Module, Function}</c>, equivalent to
174
<c>apply(Module, Function, Args)</c>. This usage is
175
deprecated and will stop working in a future release of
181
<name>apply(Module, Function, Args) -> term() | empty()</name>
182
<fsummary>Apply a function to an argument list</fsummary>
184
<v>Module = Function = atom()</v>
185
<v>Args = [term()]</v>
188
<p>Returns the result of applying <c>Function</c> in
189
<c>Module</c> to <c>Args</c>. The applied function must
190
be exported from <c>Module</c>. The arity of the function is
191
the length of <c>Args</c>.</p>
193
> <input>apply(lists, reverse, [[a, b, c]]).</input>
195
<p><c>apply</c> can be used to evaluate BIFs by using
196
the module name <c>erlang</c>.</p>
198
> <input>apply(erlang, atom_to_list, ['Erlang']).</input>
200
<p>Note: If the number of arguments are known at compile-time,
201
the call is better written as
202
<c>Module:Function(Arg1, Arg2, ..., ArgN)</c>.</p>
203
<p>Failure: <c>error_handler:undefined_function/3</c> is called
204
if the applied function is not exported. The error handler
205
can be redefined (see
206
<seealso marker="#process_flag/2">process_flag/2</seealso>).
207
If the <c>error_handler</c> is undefined, or if the user has
208
redefined the default <c>error_handler</c> so the replacement
209
module is undefined, an error with the reason <c>undef</c>
214
<name>atom_to_list(Atom) -> string()</name>
215
<fsummary>Text representation of an atom</fsummary>
220
<p>Returns a string which corresponds to the text
221
representation of <c>Atom</c>.</p>
223
> <input>atom_to_list('Erlang').</input>
228
<name>binary_to_list(Binary) -> [char()]</name>
229
<fsummary>Convert a binary to a list</fsummary>
231
<v>Binary = binary()</v>
234
<p>Returns a list of integers which correspond to the bytes of
239
<name>binary_to_list(Binary, Start, Stop) -> [char()]</name>
240
<fsummary>Convert part of a binary to a list</fsummary>
242
<v>Binary = binary()</v>
243
<v>Start = Stop = 1..byte_size(Binary)</v>
246
<p>As <c>binary_to_list/1</c>, but returns a list of integers
247
corresponding to the bytes from position <c>Start</c> to
248
position <c>Stop</c> in <c>Binary</c>. Positions in the
249
binary are numbered starting from 1.</p>
253
<name>bitstring_to_list(Bitstring) -> [char()|bitstring()]</name>
254
<fsummary>Convert a bitstring to a list</fsummary>
256
<v>Bitstring = bitstring()</v>
259
<p>Returns a list of integers which correspond to the bytes of
260
<c>Bitstring</c>. If the number of bits in the binary is not
261
divisible by 8, the last element of the list will be a bitstring
262
containing the remaining bits (1 up to 7 bits).</p>
266
<name>binary_to_term(Binary) -> term()</name>
267
<fsummary>Decode an Erlang external term format binary</fsummary>
269
<v>Binary = ext_binary()</v>
272
<p>Returns an Erlang term which is the result of decoding
273
the binary object <c>Binary</c>, which must be encoded
274
according to the Erlang external term format. See also
275
<seealso marker="#term_to_binary/1">term_to_binary/1</seealso>.</p>
279
<name>bit_size(Bitstring) -> int()</name>
280
<fsummary>Return the size of a bitstring</fsummary>
282
<v>Bitstring = bitstring()</v>
285
<p>Returns an integer which is the size in bits of <c>Bitstring</c>.</p>
287
> <input>bit_size(<<433:16,3:3>>).</input>
289
> <input>bit_size(<<1,2,3>>).</input>
291
<p>Allowed in guard tests.</p>
295
<name>erlang:bump_reductions(Reductions) -> void()</name>
296
<fsummary>Increment the reduction counter</fsummary>
298
<v>Reductions = int()</v>
301
<p>This implementation-dependent function increments
302
the reduction counter for the calling process. In the Beam
303
emulator, the reduction counter is normally incremented by
304
one for each function and BIF call, and a context switch is
305
forced when the counter reaches 1000.</p>
307
<p>This BIF might be removed in a future version of the Beam
308
machine without prior warning. It is unlikely to be
309
implemented in other Erlang implementations.</p>
314
<name>byte_size(Bitstring) -> int()</name>
315
<fsummary>Return the size of a bitstring (or binary)</fsummary>
317
<v>Bitstring = bitstring()</v>
320
<p>Returns an integer which is the number of bytes needed to contain
321
<c>Bitstring</c>. (That is, if the number of bits in <c>Bitstring</c> is not
322
divisible by 8, the resulting number of bytes will be rounded <em>up</em>.)</p>
324
> <input>byte_size(<<433:16,3:3>>).</input>
326
> <input>byte_size(<<1,2,3>>).</input>
328
<p>Allowed in guard tests.</p>
332
<name>erlang:cancel_timer(TimerRef) -> Time | false</name>
333
<fsummary>Cancel a timer</fsummary>
335
<v>TimerRef = ref()</v>
339
<p>Cancels a timer, where <c>TimerRef</c> was returned by
341
<seealso marker="#erlang:send_after/3">erlang:send_after/3</seealso>
343
<seealso marker="#erlang:start_timer/3">erlang:start_timer/3</seealso>.
344
If the timer is there to be removed, the function returns
345
the time in milliseconds left until the timer would have expired,
346
otherwise <c>false</c> (which means that <c>TimerRef</c> was
347
never a timer, that it has already been cancelled, or that it
348
has already delivered its message).</p>
350
<seealso marker="#erlang:send_after/3">erlang:send_after/3</seealso>,
351
<seealso marker="#erlang:start_timer/3">erlang:start_timer/3</seealso>,
353
<seealso marker="#erlang:read_timer/1">erlang:read_timer/1</seealso>.</p>
354
<p>Note: Cancelling a timer does not guarantee that the message
355
has not already been delivered to the message queue.</p>
360
<name>check_process_code(Pid, Module) -> bool()</name>
361
<fsummary>Check if a process is executing old code for a module</fsummary>
364
<v>Module = atom()</v>
367
<p>Returns <c>true</c> if the process <c>Pid</c> is executing
368
old code for <c>Module</c>. That is, if the current call of
369
the process executes old code for this module, or if the
370
process has references to old code for this module, or if the
371
process contains funs that references old code for this
372
module. Otherwise, it returns <c>false</c>.</p>
374
> <input>check_process_code(Pid, lists).</input>
376
<p>See also <seealso marker="code">code(3)</seealso>.</p>
380
<name>concat_binary(ListOfBinaries)</name>
381
<fsummary>Concatenate a list of binaries (deprecated)</fsummary>
384
<seealso marker="#list_to_binary/1">list_to_binary/1</seealso>
389
<name>crc32(Data) -> int()</name>
390
<fsummary>Compute crc32 (IEEE 802.3) checksum</fsummary>
392
<v>Data = iodata()</v>
395
<p>Computes and returns the crc32 (IEEE 802.3 style) checksum for <c>Data</c>.</p>
399
<name>crc32(OldCrc, Data) -> int()</name>
400
<fsummary>Compute crc32 (IEEE 802.3) checksum</fsummary>
402
<v>OldCrc = int()</v>
403
<v>Data = iodata()</v>
406
<p>Continue computing the crc32 checksum by combining
407
the previous checksum, <c>OldCrc</c>, with the checksum of
409
<p>The following code:</p>
414
<p>- would assign the same value to <c>Y</c> as this would:</p>
416
Y = crc32([Data1,Data2]).
421
<name>crc32_combine(FirstCrc, SecondCrc, SecondSize) -> int()</name>
422
<fsummary>Combine two crc32 (IEEE 802.3) checksums</fsummary>
424
<v>FirstCrc = SecondCrc = int()</v>
425
<v>SecondSize = int()</v>
428
<p>Combines two previously computed crc32 checksums.
429
This computation requires the size of the data object for
430
the second checksum to be known.</p>
431
<p>The following code:</p>
436
<p>- would assign the same value to <c>Z</c> as this would:</p>
440
Z = crc32_combine(X,Y,iolist_size(Data2)).
445
<name>date() -> {Year, Month, Day}</name>
446
<fsummary>Current date</fsummary>
448
<v>Year = Month = Day = int()</v>
451
<p>Returns the current date as <c>{Year, Month, Day}</c>.</p>
452
<p>The time zone and daylight saving time correction depend on
453
the underlying OS.</p>
455
> <input>date().</input>
460
<name>decode_packet(Type,Bin,Options) -> {ok,Packet,Rest} | {more,Length} | {error,Reason}</name>
461
<fsummary>Extracts a protocol packet from a binary</fsummary>
463
<v>Bin = binary()</v>
464
<v>Options = [Opt]</v>
465
<v>Packet = binary() | HttpPacket</v>
466
<v>Rest = binary()</v>
467
<v>Length = int() | undefined</v>
468
<v>Reason = term()</v>
469
<v> Type, Opt -- see below</v>
471
<v>HttpPacket = HttpRequest | HttpResponse | HttpHeader | http_eoh | HttpError</v>
472
<v>HttpRequest = {http_request, HttpMethod, HttpUri, HttpVersion}</v>
473
<v>HttpResponse = {http_response, HttpVersion, integer(), string()}</v>
474
<v>HttpHeader = {http_header, int(), HttpField, Reserved=term(), Value=string()}</v>
475
<v>HttpError = {http_error, string()}</v>
476
<v>HttpMethod = HttpMethodAtom | string()</v>
477
<v>HttpMethodAtom = 'OPTIONS' | 'GET' | 'HEAD' | 'POST' | 'PUT' | 'DELETE' | 'TRACE'</v>
478
<v>HttpUri = '*' | {absoluteURI, http|https, Host=string(), Port=int()|undefined, Path=string()} |
479
{scheme, Scheme=string(), string()} | {abs_path, string} | string()</v>
480
<v>HttpVersion = {Major=int(), Minor=int()}</v>
481
<v>HttpField = HttpFieldAtom | string()</v>
482
<v>HttpFieldAtom = 'Cache-Control' | 'Connection' | 'Date' | 'Pragma' | 'Transfer-Encoding' | 'Upgrade' | 'Via' | 'Accept' | 'Accept-Charset' | 'Accept-Encoding' | 'Accept-Language' | 'Authorization' | 'From' | 'Host' | 'If-Modified-Since' | 'If-Match' | 'If-None-Match' | 'If-Range' | 'If-Unmodified-Since' | 'Max-Forwards' | 'Proxy-Authorization' | 'Range' | 'Referer' | 'User-Agent' | 'Age' | 'Location' | 'Proxy-Authenticate' | 'Public' | 'Retry-After' | 'Server' | 'Vary' | 'Warning' | 'Www-Authenticate' | 'Allow' | 'Content-Base' | 'Content-Encoding' | 'Content-Language' | 'Content-Length' | 'Content-Location' | 'Content-Md5' | 'Content-Range' | 'Content-Type' | 'Etag' | 'Expires' | 'Last-Modified' | 'Accept-Ranges' | 'Set-Cookie' | 'Set-Cookie2' | 'X-Forwarded-For' | 'Cookie' | 'Keep-Alive' | 'Proxy-Connection'</v>
486
<p>Decodes the binary <c>Bin</c> according to the packet
487
protocol specified by <c>Type</c>. Very simular to the packet
488
handling done by sockets with the option {packet,Type}.</p>
489
<p>If an entire packet is contained in <c>Bin</c> it is
490
returned together with the remainder of the binary as
491
<c>{ok,Packet,Rest}</c>.</p>
492
<p>If <c>Bin</c> does not contain the entire packet,
493
<c>{more,Length}</c> is returned. <c>Length</c> is either the
494
expected <em>total size</em> of the packet or <c>undefined</c>
495
if the expected packet size is not known. <c>decode_packet</c>
496
can then be called again with more data added.</p>
497
<p>If the packet does not conform to the protocol format
498
<c>{error,Reason}</c> is returned.</p>
499
<p>The following values of <c>Type</c> are valid:</p>
501
<tag><c>raw | 0</c></tag>
503
<p>No packet handling is done. Entire binary is
504
returned unless it is empty.</p>
506
<tag><c>1 | 2 | 4</c></tag>
508
<p>Packets consist of a header specifying the number of
509
bytes in the packet, followed by that number of bytes.
510
The length of header can be one, two, or four bytes;
511
the order of the bytes is big-endian. The header
512
will be stripped off when the packet is returned.</p>
514
<tag><c>line</c></tag>
516
<p>A packet is a line terminated with newline. The
517
newline character is included in the returned packet
518
unless the line was truncated according to the option
519
<c>line_length</c>.</p>
521
<tag><c>asn1 | cdr | sunrm | fcgi | tpkt</c></tag>
523
<p>The header is <em>not</em> stripped off.</p>
524
<p>The meanings of the packet types are as follows:</p>
526
<tag><c>asn1</c> - ASN.1 BER</tag><item></item>
527
<tag><c>sunrm</c> - Sun's RPC encoding</tag><item></item>
528
<tag><c>cdr</c> - CORBA (GIOP 1.1)</tag><item></item>
529
<tag><c>fcgi</c> - Fast CGI</tag><item></item>
530
<tag><c>tpkt</c> - TPKT format [RFC1006]</tag><item></item>
533
<tag><c>http | httph</c></tag>
535
<p>The Hypertext Transfer Protocol. The packets
536
are returned with the format according to
537
<c>HttpPacket</c> described above. A packet is either a
538
request, a response, a header or an end of header
539
mark. Invalid lines are returned as <c>HttpError</c>.</p>
540
<p>Recognized request methods and header fields are returned as atoms.
541
Others are returned as strings.</p>
542
<p>The protocol type <c>http</c> should only be used for
543
the first line when a <c>HttpRequest</c> or a
544
<c>HttpResponse</c> is expected. The following calls
545
should use <c>httph</c> to get <c>HttpHeader</c>'s until
546
<c>http_eoh</c> is returned that marks the end of the
547
headers and the beginning of any following message body.</p>
550
<p>The following options are available:</p>
552
<tag><c>{packet_size, int()}</c></tag>
553
<item><p>Sets the max allowed size of the packet body. If
554
the packet header indicates that the length of the
555
packet is longer than the max allowed length, the packet
556
is considered invalid. Default is 0 which means no
559
<tag><c>{line_length, int()}</c></tag>
560
<item><p>Applies only to line oriented protocols
561
(<c>line</c>, <c>http</c>). Lines longer than this
562
will be truncated.</p>
566
> <input>erlang:decode_packet(1,<<3,"abcd">>,[]).</input>
567
{ok,<<"abc">>,<<"d">>}
568
> <input>erlang:decode_packet(1,<<5,"abcd">>,[]).</input>
573
<name>delete_module(Module) -> true | undefined</name>
574
<fsummary>Make the current code for a module old</fsummary>
576
<v>Module = atom()</v>
579
<p>Makes the current code for <c>Module</c> become old code, and
580
deletes all references for this module from the export table.
581
Returns <c>undefined</c> if the module does not exist,
582
otherwise <c>true</c>.</p>
584
<p>This BIF is intended for the code server (see
585
<seealso marker="code">code(3)</seealso>) and should not be
588
<p>Failure: <c>badarg</c> if there is already an old version of
593
<name>erlang:demonitor(MonitorRef) -> true</name>
594
<fsummary>Stop monitoring</fsummary>
596
<v>MonitorRef = ref()</v>
599
<p>If <c>MonitorRef</c> is a reference which the calling process
601
<seealso marker="#erlang:monitor/2">erlang:monitor/2</seealso>,
602
this monitoring is turned off. If the monitoring is already
603
turned off, nothing happens.</p>
604
<p>Once <c>erlang:demonitor(MonitorRef)</c> has returned it is
605
guaranteed that no <c>{'DOWN', MonitorRef, _, _, _}</c> message
606
due to the monitor will be placed in the callers message queue
607
in the future. A <c>{'DOWN', MonitorRef, _, _, _}</c> message
608
might have been placed in the callers message queue prior to
609
the call, though. Therefore, in most cases, it is advisable
610
to remove such a <c>'DOWN'</c> message from the message queue
611
after monitoring has been stopped.
612
<seealso marker="#erlang:demonitor/2">erlang:demonitor(MonitorRef, [flush])</seealso> can be used instead of
613
<c>erlang:demonitor(MonitorRef)</c> if this cleanup is wanted.</p>
615
<p>Prior to OTP release R11B (erts version 5.5) <c>erlang:demonitor/1</c>
616
behaved completely asynchronous, i.e., the monitor was active
617
until the "demonitor signal" reached the monitored entity. This
618
had one undesirable effect, though. You could never know when
619
you were guaranteed <em>not</em> to receive a <c>DOWN</c> message
620
due to the monitor.</p>
621
<p>Current behavior can be viewed as two combined operations:
622
asynchronously send a "demonitor signal" to the monitored entity
623
and ignore any future results of the monitor. </p>
625
<p>Failure: It is an error if <c>MonitorRef</c> refers to a
626
monitoring started by another process. Not all such cases are
627
cheap to check; if checking is cheap, the call fails with
628
<c>badarg</c> (for example if <c>MonitorRef</c> is a remote
633
<name>erlang:demonitor(MonitorRef, OptionList) -> true</name>
634
<fsummary>Stop monitoring</fsummary>
636
<v>MonitorRef = ref()</v>
637
<v>OptionList = [Option]</v>
638
<v>Option = flush</v>
641
<p><c>erlang:demonitor(MonitorRef, [])</c> is equivalent to
642
<seealso marker="#erlang:demonitor/1">erlang:demonitor(MonitorRef)</seealso>.</p>
643
<p>Currently the following <c>Option</c>s are valid:</p>
645
<tag><c>flush</c></tag>
647
<p>Remove (one) <c>{_, MonitorRef, _, _, _}</c> message,
648
if there is one, from the callers message queue after
649
monitoring has been stopped.</p>
650
<p>Calling <c>erlang:demonitor(MonitorRef, [flush])</c>
651
is equivalent to:</p>
654
erlang:demonitor(MonitorRef),
656
\011{_, MonitorRef, _, _, _} ->
664
<p>More options may be added in the future.</p>
666
<p>Failure: <c>badarg</c> if <c>OptionList</c> is not a list, or
667
if <c>Option</c> is not a valid option, or the same failure as for
668
<seealso marker="#erlang:demonitor/1">erlang:demonitor/1</seealso></p>
672
<name>disconnect_node(Node) -> bool() | ignored</name>
673
<fsummary>Force the disconnection of a node</fsummary>
678
<p>Forces the disconnection of a node. This will appear to
679
the node <c>Node</c> as if the local node has crashed. This
680
BIF is mainly used in the Erlang network authentication
681
protocols. Returns <c>true</c> if disconnection succeeds,
682
otherwise <c>false</c>. If the local node is not alive,
683
the function returns <c>ignored</c>.</p>
687
<name>erlang:display(Term) -> true</name>
688
<fsummary>Print a term on standard output</fsummary>
693
<p>Prints a text representation of <c>Term</c> on the standard
696
<p>This BIF is intended for debugging only.</p>
701
<name>element(N, Tuple) -> term()</name>
702
<fsummary>Get Nth element of a tuple</fsummary>
704
<v>N = 1..tuple_size(Tuple)</v>
705
<v>Tuple = tuple()</v>
708
<p>Returns the <c>N</c>th element (numbering from 1) of
711
> <input>element(2, {a, b, c}).</input>
713
<p>Allowed in guard tests.</p>
717
<name>erase() -> [{Key, Val}]</name>
718
<fsummary>Return and delete the process dictionary</fsummary>
720
<v>Key = Val = term()</v>
723
<p>Returns the process dictionary and deletes it.</p>
725
> <input>put(key1, {1, 2, 3}),</input>
726
<input>put(key2, [a, b, c]),</input>
727
<input>erase().</input>
728
[{key1,{1,2,3}},{key2,[a,b,c]}]</pre>
732
<name>erase(Key) -> Val | undefined</name>
733
<fsummary>Return and delete a value from the process dictionary</fsummary>
735
<v>Key = Val = term()</v>
738
<p>Returns the value <c>Val</c> associated with <c>Key</c> and
739
deletes it from the process dictionary. Returns
740
<c>undefined</c> if no value is associated with <c>Key</c>.</p>
742
> <input>put(key1, {merry, lambs, are, playing}),</input>
743
<input>X = erase(key1),</input>
744
<input>{X, erase(key1)}.</input>
745
{{merry,lambs,are,playing},undefined}</pre>
749
<name>erlang:error(Reason)</name>
750
<fsummary>Stop execution with a given reason</fsummary>
752
<v>Reason = term()</v>
755
<p>Stops the execution of the calling process with the reason
756
<c>Reason</c>, where <c>Reason</c> is any term. The actual
757
exit reason will be <c>{Reason, Where}</c>, where <c>Where</c>
758
is a list of the functions most recently called (the current
759
function first). Since evaluating this function causes
760
the process to terminate, it has no return value.</p>
762
> <input>catch erlang:error(foobar).</input>
763
{'EXIT',{foobar,[{erl_eval,do_apply,5},
766
{shell,eval_exprs,6},
767
{shell,eval_loop,3}]}}</pre>
771
<name>erlang:error(Reason, Args)</name>
772
<fsummary>Stop execution with a given reason</fsummary>
774
<v>Reason = term()</v>
775
<v>Args = [term()]</v>
778
<p>Stops the execution of the calling process with the reason
779
<c>Reason</c>, where <c>Reason</c> is any term. The actual
780
exit reason will be <c>{Reason, Where}</c>, where <c>Where</c>
781
is a list of the functions most recently called (the current
782
function first). <c>Args</c> is expected to be the list of
783
arguments for the current function; in Beam it will be used
784
to provide the actual arguments for the current function in
785
the <c>Where</c> term. Since evaluating this function causes
786
the process to terminate, it has no return value.</p>
790
<name>exit(Reason)</name>
791
<fsummary>Stop execution with a given reason</fsummary>
793
<v>Reason = term()</v>
796
<p>Stops the execution of the calling process with the exit
797
reason <c>Reason</c>, where <c>Reason</c> is any term. Since
798
evaluating this function causes the process to terminate, it
799
has no return value.</p>
801
> <input>exit(foobar).</input>
802
** exception exit: foobar
803
> <input>catch exit(foobar).</input>
804
{'EXIT',foobar}</pre>
808
<name>exit(Pid, Reason) -> true</name>
809
<fsummary>Send an exit signal to a process</fsummary>
812
<v>Reason = term()</v>
815
<p>Sends an exit signal with exit reason <c>Reason</c> to
816
the process <c>Pid</c>.</p>
817
<p>The following behavior apply if <c>Reason</c> is any term
818
except <c>normal</c> or <c>kill</c>:</p>
819
<p>If <c>Pid</c> is not trapping exits, <c>Pid</c> itself will
820
exit with exit reason <c>Reason</c>. If <c>Pid</c> is trapping
821
exits, the exit signal is transformed into a message
822
<c>{'EXIT', From, Reason}</c> and delivered to the message
823
queue of <c>Pid</c>. <c>From</c> is the pid of the process
824
which sent the exit signal. See also
825
<seealso marker="#process_flag/2">process_flag/2</seealso>.</p>
826
<p>If <c>Reason</c> is the atom <c>normal</c>, <c>Pid</c> will
827
not exit. If it is trapping exits, the exit signal is
828
transformed into a message <c>{'EXIT', From, normal}</c>
829
and delivered to its message queue.</p>
830
<p>If <c>Reason</c> is the atom <c>kill</c>, that is if
831
<c>exit(Pid, kill)</c> is called, an untrappable exit signal
832
is sent to <c>Pid</c> which will unconditionally exit with
833
exit reason <c>killed</c>.</p>
837
<name>erlang:fault(Reason)</name>
838
<fsummary>Stop execution with a given reason</fsummary>
840
<v>Reason = term()</v>
843
<p>This function is deprecated and will be removed in the next release.
844
Used <seealso marker="#erlang:error/1">erlang:error(Reason)</seealso>
849
<name>erlang:fault(Reason, Args)</name>
850
<fsummary>Stop execution with a given reason</fsummary>
852
<v>Reason = term()</v>
853
<v>Args = [term()]</v>
856
<p>This function is deprecated and will be removed in the next release.
857
Use <seealso marker="#erlang:error/2">erlang:error(Reason, Args)</seealso>
862
<name>float(Number) -> float()</name>
863
<fsummary>Convert a number to a float</fsummary>
865
<v>Number = number()</v>
868
<p>Returns a float by converting <c>Number</c> to a float.</p>
870
> <input>float(55).</input>
872
<p>Allowed in guard tests.</p>
874
<p>Note that if used on the top-level in a guard, it will
875
test whether the argument is a floating point number; for
877
<seealso marker="#is_float/1">is_float/1</seealso> instead.</p>
878
<p>When <c>float/1</c> is used in an expression in a guard,
879
such as '<c>float(A) == 4.0</c>', it converts a number as
885
<name>float_to_list(Float) -> string()</name>
886
<fsummary>Text representation of a float</fsummary>
888
<v>Float = float()</v>
891
<p>Returns a string which corresponds to the text
892
representation of <c>Float</c>.</p>
894
> <input>float_to_list(7.0).</input>
895
"7.00000000000000000000e+00"</pre>
899
<name>erlang:fun_info(Fun) -> [{Item, Info}]</name>
900
<fsummary>Information about a fun</fsummary>
903
<v>Item, Info -- see below</v>
906
<p>Returns a list containing information about the fun
907
<c>Fun</c>. Each element of the list is a tuple. The order of
908
the tuples is not defined, and more tuples may be added in a
911
<p>This BIF is mainly intended for debugging, but it can
912
occasionally be useful in library functions that might need
913
to verify, for instance, the arity of a fun.</p>
915
<p>There are two types of funs with slightly different
917
<p>A fun created by <c>fun M:F/A</c> is called an
918
<em>external</em> fun. Calling it will always call the
919
function <c>F</c> with arity <c>A</c> in the latest code for
920
module <c>M</c>. Note that module <c>M</c> does not even need
921
to be loaded when the fun <c>fun M:F/A</c> is created.</p>
922
<p>All other funs are called <em>local</em>. When a local fun
923
is called, the same version of the code that created the fun
924
will be called (even if newer version of the module has been
926
<p>The following elements will always be present in the list
927
for both local and external funs:</p>
929
<tag><c>{type, Type}</c></tag>
931
<p><c>Type</c> is either <c>local</c> or <c>external</c>.</p>
933
<tag><c>{module, Module}</c></tag>
935
<p><c>Module</c> (an atom) is the module name.</p>
936
<p>If <c>Fun</c> is a local fun, <c>Module</c> is the module
937
in which the fun is defined.</p>
938
<p>If <c>Fun</c> is an external fun, <c>Module</c> is the
939
module that the fun refers to.</p>
941
<tag><c>{name, Name}</c></tag>
943
<p><c>Name</c> (an atom) is a function name.</p>
944
<p>If <c>Fun</c> is a local fun, <c>Name</c> is the name
945
of the local function that implements the fun.
946
(This name was generated by the compiler, and is generally
947
only of informational use. As it is a local function, it
948
is not possible to call it directly.)
949
If no code is currently loaded for the fun, <c>[]</c>
950
will be returned instead of an atom.</p>
951
<p>If <c>Fun</c> is an external fun, <c>Name</c> is the name
952
of the exported function that the fun refers to.</p>
954
<tag><c>{arity, Arity}</c></tag>
956
<p><c>Arity</c> is the number of arguments that the fun
957
should be called with.</p>
959
<tag><c>{env, Env}</c></tag>
961
<p><c>Env</c> (a list) is the environment or free variables
962
for the fun. (For external funs, the returned list is
966
<p>The following elements will only be present in the list if
967
<c>Fun</c> is local:</p>
969
<tag><c>{pid, Pid}</c></tag>
971
<p><c>Pid</c> is the pid of the process that originally
974
<tag><c>{index, Index}</c></tag>
976
<p><c>Index</c> (an integer) is an index into the module's
979
<tag><c>{new_index, Index}</c></tag>
981
<p><c>Index</c> (an integer) is an index into the module's
984
<tag><c>{new_uniq, Uniq}</c></tag>
986
<p><c>Uniq</c> (a binary) is a unique value for this fun.</p>
988
<tag><c>{uniq, Uniq}</c></tag>
990
<p><c>Uniq</c> (an integer) is a unique value for this fun.</p>
996
<name>erlang:fun_info(Fun, Item) -> {Item, Info}</name>
997
<fsummary>Information about a fun</fsummary>
1000
<v>Item, Info -- see below</v>
1003
<p>Returns information about <c>Fun</c> as specified by
1004
<c>Item</c>, in the form <c>{Item,Info}</c>.</p>
1005
<p>For any fun, <c>Item</c> can be any of the atoms
1006
<c>module</c>, <c>name</c>, <c>arity</c>, or <c>env</c>.</p>
1007
<p>For a local fun, <c>Item</c> can also be any of the atoms
1008
<c>index</c>, <c>new_index</c>, <c>new_uniq</c>,
1009
<c>uniq</c>, and <c>pid</c>. For an external fun, the value
1010
of any of these items is always the atom <c>undefined</c>.</p>
1012
<seealso marker="#erlang:fun_info/1">erlang:fun_info/1</seealso>.</p>
1016
<name>erlang:fun_to_list(Fun) -> string()</name>
1017
<fsummary>Text representation of a fun</fsummary>
1022
<p>Returns a string which corresponds to the text
1023
representation of <c>Fun</c>.</p>
1027
<name>erlang:function_exported(Module, Function, Arity) -> bool()</name>
1028
<fsummary>Check if a function is exported and loaded</fsummary>
1030
<v>Module = Function = atom()</v>
1031
<v>Arity = int()</v>
1034
<p>Returns <c>true</c> if the module <c>Module</c> is loaded
1035
and contains an exported function <c>Function/Arity</c>;
1036
otherwise <c>false</c>.</p>
1037
<p>Returns <c>false</c> for any BIF (functions implemented in C
1038
rather than in Erlang).</p>
1042
<name>garbage_collect() -> true</name>
1043
<fsummary>Force an immediate garbage collection of the calling process</fsummary>
1045
<p>Forces an immediate garbage collection of the currently
1046
executing process. The function should not be used, unless
1047
it has been noticed -- or there are good reasons to suspect --
1048
that the spontaneous garbage collection will occur too late
1049
or not at all. Improper use may seriously degrade system
1051
<p>Compatibility note: In versions of OTP prior to R7,
1052
the garbage collection took place at the next context switch,
1053
not immediately. To force a context switch after a call to
1054
<c>erlang:garbage_collect()</c>, it was sufficient to make
1055
any function call.</p>
1059
<name>garbage_collect(Pid) -> bool()</name>
1060
<fsummary>Force an immediate garbage collection of a process</fsummary>
1065
<p>Works like <c>erlang:garbage_collect()</c> but on any
1066
process. The same caveats apply. Returns <c>false</c> if
1067
<c>Pid</c> refers to a dead process; <c>true</c> otherwise.</p>
1071
<name>get() -> [{Key, Val}]</name>
1072
<fsummary>Return the process dictionary</fsummary>
1074
<v>Key = Val = term()</v>
1077
<p>Returns the process dictionary as a list of
1078
<c>{Key, Val}</c> tuples.</p>
1080
> <input>put(key1, merry),</input>
1081
<input>put(key2, lambs),</input>
1082
<input>put(key3, {are, playing}),</input>
1083
<input>get().</input>
1084
[{key1,merry},{key2,lambs},{key3,{are,playing}}]</pre>
1088
<name>get(Key) -> Val | undefined</name>
1089
<fsummary>Return a value from the process dictionary</fsummary>
1091
<v>Key = Val = term()</v>
1094
<p>Returns the value <c>Val</c>associated with <c>Key</c> in
1095
the process dictionary, or <c>undefined</c> if <c>Key</c>
1098
> <input>put(key1, merry),</input>
1099
<input>put(key2, lambs),</input>
1100
<input>put({any, [valid, term]}, {are, playing}),</input>
1101
<input>get({any, [valid, term]}).</input>
1106
<name>erlang:get_cookie() -> Cookie | nocookie</name>
1107
<fsummary>Get the magic cookie of the local node</fsummary>
1109
<v>Cookie = atom()</v>
1112
<p>Returns the magic cookie of the local node, if the node is
1113
alive; otherwise the atom <c>nocookie</c>.</p>
1117
<name>get_keys(Val) -> [Key]</name>
1118
<fsummary>Return a list of keys from the process dictionary</fsummary>
1120
<v>Val = Key = term()</v>
1123
<p>Returns a list of keys which are associated with the value
1124
<c>Val</c> in the process dictionary.</p>
1126
> <input>put(mary, {1, 2}),</input>
1127
<input>put(had, {1, 2}),</input>
1128
<input>put(a, {1, 2}),</input>
1129
<input>put(little, {1, 2}),</input>
1130
<input>put(dog, {1, 3}),</input>
1131
<input>put(lamb, {1, 2}),</input>
1132
<input>get_keys({1, 2}).</input>
1133
[mary,had,a,little,lamb]</pre>
1137
<name>erlang:get_stacktrace() -> [{Module, Function, Arity | Args}]</name>
1138
<fsummary>Get the call stack back-trace of the last exception</fsummary>
1140
<v>Module = Function = atom()</v>
1141
<v>Arity = int()</v>
1142
<v>Args = [term()]</v>
1145
<p>Get the call stack back-trace (<em>stacktrace</em>) of the last
1146
exception in the calling process as a list of
1147
<c>{Module,Function,Arity}</c> tuples.
1148
The <c>Arity</c> field in the first tuple may be the argument
1149
list of that function call instead of an arity integer,
1150
depending on the exception.</p>
1151
<p>If there has not been any exceptions in a process, the
1152
stacktrace is []. After a code change for the process,
1153
the stacktrace may also be reset to [].</p>
1154
<p>The stacktrace is the same data as the <c>catch</c> operator
1155
returns, for example:</p>
1156
<p><c>{'EXIT',{badarg,Stacktrace}} = catch abs(x)</c></p>
1158
<seealso marker="#erlang:error/1">erlang:error/1</seealso> and
1159
<seealso marker="#erlang:error/2">erlang:error/2</seealso>.</p>
1163
<name>group_leader() -> GroupLeader</name>
1164
<fsummary>Get the group leader for the calling process</fsummary>
1166
<v>GroupLeader = pid()</v>
1169
<p>Returns the pid of the group leader for the process which
1170
evaluates the function.</p>
1171
<p>Every process is a member of some process group and all
1172
groups have a <em>group leader</em>. All IO from the group
1173
is channeled to the group leader. When a new process is
1174
spawned, it gets the same group leader as the spawning
1175
process. Initially, at system start-up, <c>init</c> is both
1176
its own group leader and the group leader of all processes.</p>
1180
<name>group_leader(GroupLeader, Pid) -> true</name>
1181
<fsummary>Set the group leader for a process</fsummary>
1183
<v>GroupLeader = Pid = pid()</v>
1186
<p>Sets the group leader of <c>Pid</c> to <c>GroupLeader</c>.
1187
Typically, this is used when a processes started from a
1188
certain shell should have another group leader than
1191
<seealso marker="#group_leader/0">group_leader/0</seealso>.</p>
1196
<fsummary>Halt the Erlang runtime system and indicate normal exit to the calling environment</fsummary>
1198
<p>Halts the Erlang runtime system and indicates normal exit to
1199
the calling environment. Has no return value.</p>
1201
> <input>halt().</input>
1206
<name>halt(Status)</name>
1207
<fsummary>Halt the Erlang runtime system</fsummary>
1209
<v>Status = int()>=0 | string()</v>
1212
<p><c>Status</c> must be a non-negative integer, or a string.
1213
Halts the Erlang runtime system. Has no return value.
1214
If <c>Status</c> is an integer, it is returned as an exit
1215
status of Erlang to the calling environment.
1216
If <c>Status</c> is a string, produces an Erlang crash dump
1217
with <c>String</c> as slogan, and then exits with a non-zero
1219
<p>Note that on many platforms, only the status codes 0-255 are
1220
supported by the operating system.</p>
1224
<name>erlang:hash(Term, Range) -> Hash</name>
1225
<fsummary>Hash function (deprecated)</fsummary>
1227
<p>Returns a hash value for <c>Term</c> within the range
1228
<c>1..Range</c>. The allowed range is 1..2^27-1.</p>
1230
<p>This BIF is deprecated as the hash value may differ on
1231
different architectures. Also the hash values for integer
1232
terms larger than 2^27 as well as large binaries are very
1233
poor. The BIF is retained for backward compatibility
1234
reasons (it may have been used to hash records into a file),
1235
but all new code should use one of the BIFs
1236
<c>erlang:phash/2</c> or <c>erlang:phash2/1,2</c> instead.</p>
1241
<name>hd(List) -> term()</name>
1242
<fsummary>Head of a list</fsummary>
1244
<v>List = [term()]</v>
1247
<p>Returns the head of <c>List</c>, that is, the first element.</p>
1249
> <input>hd([1,2,3,4,5]).</input>
1251
<p>Allowed in guard tests.</p>
1252
<p>Failure: <c>badarg</c> if <c>List</c> is the empty list [].</p>
1256
<name>erlang:hibernate(Module, Function, Args)</name>
1257
<fsummary>Hibernate a process until a message is sent to it</fsummary>
1259
<v>Module = Function = atom()</v>
1260
<v>Args = [term()]</v>
1263
<p>Puts the calling process into a wait state where its memory
1264
allocation has been reduced as much as possible, which is
1265
useful if the process does not expect to receive any messages
1266
in the near future.</p>
1267
<p>The process will be awaken when a message is sent to it, and
1268
control will resume in <c>Module:Function</c> with
1269
the arguments given by <c>Args</c> with the call stack
1270
emptied, meaning that the process will terminate when that
1271
function returns. Thus <c>erlang:hibernate/3</c> will never
1272
return to its caller.</p>
1273
<p>If the process has any message in its message queue,
1274
the process will be awaken immediately in the same way as
1275
described above.</p>
1276
<p>In more technical terms, what <c>erlang:hibernate/3</c> does
1277
is the following. It discards the call stack for the process.
1278
Then it garbage collects the process. After the garbage
1279
collection, all live data is in one continuous heap. The heap
1280
is then shrunken to the exact same size as the live data
1281
which it holds (even if that size is less than the minimum
1282
heap size for the process).</p>
1283
<p>If the size of the live data in the process is less than
1284
the minimum heap size, the first garbage collection occurring
1285
after the process has been awaken will ensure that the heap
1286
size is changed to a size not smaller than the minimum heap
1288
<p>Note that emptying the call stack means that any surrounding
1289
<c>catch</c> is removed and has to be re-inserted after
1290
hibernation. One effect of this is that processes started
1291
using <c>proc_lib</c> (also indirectly, such as
1292
<c>gen_server</c> processes), should use
1293
<seealso marker="stdlib:proc_lib#hibernate/3">proc_lib:hibernate/3</seealso>
1294
instead to ensure that the exception handler continues to work
1295
when the process wakes up.</p>
1299
<name>integer_to_list(Integer) -> string()</name>
1300
<fsummary>Text representation of an integer</fsummary>
1302
<v>Integer = int()</v>
1305
<p>Returns a string which corresponds to the text
1306
representation of <c>Integer</c>.</p>
1308
> <input>integer_to_list(77).</input>
1313
<name>erlang:integer_to_list(Integer, Base) -> string()</name>
1314
<fsummary>Text representation of an integer</fsummary>
1316
<v>Integer = int()</v>
1320
<p>Returns a string which corresponds to the text
1321
representation of <c>Integer</c> in base <c>Base</c>.</p>
1323
> <input>erlang:integer_to_list(1023, 16).</input>
1328
<name>iolist_to_binary(IoListOrBinary) -> binary()</name>
1329
<fsummary>Convert an iolist to a binary</fsummary>
1331
<v>IoListOrBinary = iolist() | binary()</v>
1334
<p>Returns a binary which is made from the integers and
1335
binaries in <c>IoListOrBinary</c>.</p>
1337
> <input>Bin1 = <<1,2,3>>.</input>
1338
<<1,2,3>>
1339
> <input>Bin2 = <<4,5>>.</input>
1341
> <input>Bin3 = <<6>>.</input>
1343
> <input>iolist_to_binary([Bin1,1,[2,3,Bin2],4|Bin3]).</input>
1344
<<1,2,3,1,2,3,4,5,4,6>></pre>
1348
<name>iolist_size(Item) -> int()</name>
1349
<fsummary>Size of an iolist</fsummary>
1351
<v>Item = iolist() | binary()</v>
1354
<p>Returns an integer which is the size in bytes
1355
of the binary that would be the result of
1356
<c>iolist_to_binary(Item)</c>.</p>
1358
> <input>iolist_size([1,2|<<3,4>>]).</input>
1363
<name>is_alive() -> bool()</name>
1364
<fsummary>Check whether the local node is alive</fsummary>
1366
<p>Returns <c>true</c> if the local node is alive; that is, if
1367
the node can be part of a distributed system. Otherwise, it
1368
returns <c>false</c>.</p>
1372
<name>is_atom(Term) -> bool()</name>
1373
<fsummary>Check whether a term is an atom</fsummary>
1375
<v>Term = term()</v>
1378
<p>Returns <c>true</c> if <c>Term</c> is an atom;
1379
otherwise returns <c>false</c>.</p>
1380
<p>Allowed in guard tests.</p>
1384
<name>is_binary(Term) -> bool()</name>
1385
<fsummary>Check whether a term is a binary</fsummary>
1387
<v>Term = term()</v>
1390
<p>Returns <c>true</c> if <c>Term</c> is a binary;
1391
otherwise returns <c>false</c>.</p>
1393
<p>A binary always contains a complete number of bytes.</p>
1395
<p>Allowed in guard tests.</p>
1399
<name>is_bitstring(Term) -> bool()</name>
1400
<fsummary>Check whether a term is a bitstring</fsummary>
1402
<v>Term = term()</v>
1405
<p>Returns <c>true</c> if <c>Term</c> is a bitstring (including a binary);
1406
otherwise returns <c>false</c>.</p>
1408
<p>Allowed in guard tests.</p>
1412
<name>is_boolean(Term) -> bool()</name>
1413
<fsummary>Check whether a term is a boolean</fsummary>
1415
<v>Term = term()</v>
1418
<p>Returns <c>true</c> if <c>Term</c> is
1419
either the atom <c>true</c> or the atom <c>false</c>
1420
(i.e. a boolean); otherwise returns <c>false</c>.</p>
1421
<p>Allowed in guard tests.</p>
1425
<name>erlang:is_builtin(Module, Function, Arity) -> bool()</name>
1426
<fsummary>Check if a function is a BIF implemented in C</fsummary>
1428
<v>Module = Function = atom()</v>
1429
<v>Arity = int()</v>
1432
<p>Returns <c>true</c> if <c>Module:Function/Arity</c> is
1433
a BIF implemented in C; otherwise returns <c>false</c>.
1434
This BIF is useful for builders of cross reference tools.</p>
1438
<name>is_float(Term) -> bool()</name>
1439
<fsummary>Check whether a term is a float</fsummary>
1441
<v>Term = term()</v>
1444
<p>Returns <c>true</c> if <c>Term</c> is a floating point
1445
number; otherwise returns <c>false</c>.</p>
1446
<p>Allowed in guard tests.</p>
1450
<name>is_function(Term) -> bool()</name>
1451
<fsummary>Check whether a term is a fun</fsummary>
1453
<v>Term = term()</v>
1456
<p>Returns <c>true</c> if <c>Term</c> is a fun; otherwise
1457
returns <c>false</c>.</p>
1458
<p>Allowed in guard tests.</p>
1462
<name>is_function(Term, Arity) -> bool()</name>
1463
<fsummary>Check whether a term is a fun with a given arity</fsummary>
1465
<v>Term = term()</v>
1466
<v>Arity = int()</v>
1469
<p>Returns <c>true</c> if <c>Term</c> is a fun that can be
1470
applied with <c>Arity</c> number of arguments; otherwise
1471
returns <c>false</c>.</p>
1472
<p>Allowed in guard tests.</p>
1474
<p>Currently, <c>is_function/2</c> will also return
1475
<c>true</c> if the first argument is a tuple fun (a tuple
1476
containing two atoms). In a future release, tuple funs will
1477
no longer be supported and <c>is_function/2</c> will return
1478
<c>false</c> if given a tuple fun.</p>
1483
<name>is_integer(Term) -> bool()</name>
1484
<fsummary>Check whether a term is an integer</fsummary>
1486
<v>Term = term()</v>
1489
<p>Returns <c>true</c> if <c>Term</c> is an integer;
1490
otherwise returns <c>false</c>.</p>
1491
<p>Allowed in guard tests.</p>
1495
<name>is_list(Term) -> bool()</name>
1496
<fsummary>Check whether a term is a list</fsummary>
1498
<v>Term = term()</v>
1501
<p>Returns <c>true</c> if <c>Term</c> is a list with
1502
zero or more elements; otherwise returns <c>false</c>.</p>
1503
<p>Allowed in guard tests.</p>
1507
<name>is_number(Term) -> bool()</name>
1508
<fsummary>Check whether a term is a number</fsummary>
1510
<v>Term = term()</v>
1513
<p>Returns <c>true</c> if <c>Term</c> is either an integer or a
1514
floating point number; otherwise returns <c>false</c>.</p>
1515
<p>Allowed in guard tests.</p>
1519
<name>is_pid(Term) -> bool()</name>
1520
<fsummary>Check whether a term is a pid</fsummary>
1522
<v>Term = term()</v>
1525
<p>Returns <c>true</c> if <c>Term</c> is a pid (process
1526
identifier); otherwise returns <c>false</c>.</p>
1527
<p>Allowed in guard tests.</p>
1531
<name>is_port(Term) -> bool()</name>
1532
<fsummary>Check whether a term is a port</fsummary>
1534
<v>Term = term()</v>
1537
<p>Returns <c>true</c> if <c>Term</c> is a port identifier;
1538
otherwise returns <c>false</c>.</p>
1539
<p>Allowed in guard tests.</p>
1543
<name>is_process_alive(Pid) -> bool()</name>
1544
<fsummary>Check whether a process is alive</fsummary>
1550
<c>Pid</c> must refer to a process at the local node.
1551
Returns <c>true</c> if the process exists and is alive, that
1552
is, is not exiting and has not exited. Otherwise, returns
1558
<name>is_record(Term, RecordTag) -> bool()</name>
1559
<fsummary>Check whether a term appears to be a record</fsummary>
1561
<v>Term = term()</v>
1562
<v>RecordTag = atom()</v>
1565
<p>Returns <c>true</c> if <c>Term</c> is a tuple and its first
1566
element is <c>RecordTag</c>. Otherwise, returns <c>false</c>.</p>
1568
<p>Normally the compiler treats calls to <c>is_record/2</c>
1569
specially. It emits code to verify that <c>Term</c> is a
1570
tuple, that its first element is <c>RecordTag</c>, and that
1571
the size is correct. However, if the <c>RecordTag</c> is
1572
not a literal atom, the <c>is_record/2</c> BIF will be
1573
called instead and the size of the tuple will not be
1576
<p>Allowed in guard tests, if <c>RecordTag</c> is a literal
1581
<name>is_record(Term, RecordTag, Size) -> bool()</name>
1582
<fsummary>Check whether a term appears to be a record</fsummary>
1584
<v>Term = term()</v>
1585
<v>RecordTag = atom()</v>
1589
<p><c>RecordTag</c> must be an atom. Returns <c>true</c> if
1590
<c>Term</c> is a tuple, its first element is <c>RecordTag</c>,
1591
and its size is <c>Size</c>. Otherwise, returns <c>false</c>.</p>
1592
<p>Allowed in guard tests, provided that <c>RecordTag</c> is
1593
a literal atom and <c>Size</c> is a literal integer.</p>
1595
<p>This BIF is documented for completeness. In most cases
1596
<c>is_record/2</c> should be used.</p>
1601
<name>is_reference(Term) -> bool()</name>
1602
<fsummary>Check whether a term is a reference</fsummary>
1604
<v>Term = term()</v>
1607
<p>Returns <c>true</c> if <c>Term</c> is a reference;
1608
otherwise returns <c>false</c>.</p>
1609
<p>Allowed in guard tests.</p>
1613
<name>is_tuple(Term) -> bool()</name>
1614
<fsummary>Check whether a term is a tuple</fsummary>
1616
<v>Term = term()</v>
1619
<p>Returns <c>true</c> if <c>Term</c> is a tuple;
1620
otherwise returns <c>false</c>.</p>
1621
<p>Allowed in guard tests.</p>
1625
<name>length(List) -> int()</name>
1626
<fsummary>Length of a list</fsummary>
1628
<v>List = [term()]</v>
1631
<p>Returns the length of <c>List</c>.</p>
1633
> <input>length([1,2,3,4,5,6,7,8,9]).</input>
1635
<p>Allowed in guard tests.</p>
1639
<name>link(Pid) -> true</name>
1640
<fsummary>Create a link to another process (or port)</fsummary>
1642
<v>Pid = pid() | port()</v>
1645
<p>Creates a link between the calling process and another
1646
process (or port) <c>Pid</c>, if there is not such a link
1647
already. If a process attempts to create a link to itself,
1648
nothing is done. Returns <c>true</c>.</p>
1649
<p>If <c>Pid</c> does not exist, the behavior of the BIF depends
1650
on if the calling process is trapping exits or not (see
1651
<seealso marker="#process_flag/2">process_flag/2</seealso>):</p>
1652
<list type="bulleted">
1653
<item>If the calling process is not trapping exits, and
1654
checking <c>Pid</c> is cheap -- that is, if <c>Pid</c> is
1655
local -- <c>link/1</c> fails with reason <c>noproc</c>.</item>
1656
<item>Otherwise, if the calling process is trapping exits,
1657
and/or <c>Pid</c> is remote, <c>link/1</c> returns
1658
<c>true</c>, but an exit signal with reason <c>noproc</c>
1659
is sent to the calling process.</item>
1664
<name>list_to_atom(String) -> atom()</name>
1665
<fsummary>Convert from text representation to an atom</fsummary>
1667
<v>String = string()</v>
1670
<p>Returns the atom whose text representation is <c>String</c>.</p>
1672
> <input>list_to_atom("Erlang").</input>
1677
<name>list_to_binary(IoList) -> binary()</name>
1678
<fsummary>Convert a list to a binary</fsummary>
1680
<v>IoList = iolist()</v>
1683
<p>Returns a binary which is made from the integers and
1684
binaries in <c>IoList</c>.</p>
1686
> <input>Bin1 = <<1,2,3>>.</input>
1687
<<1,2,3>>
1688
> <input>Bin2 = <<4,5>>.</input>
1690
> <input>Bin3 = <<6>>.</input>
1692
> <input>list_to_binary([Bin1,1,[2,3,Bin2],4|Bin3]).</input>
1693
<<1,2,3,1,2,3,4,5,4,6>></pre>
1697
<name>list_to_bitstring(BitstringList) -> bitstring()</name>
1698
<fsummary>Convert a list to a bitstring</fsummary>
1700
<v>BitstringList = [BitstringList | bitstring() | char()]</v>
1703
<p>Returns a bitstring which is made from the integers and
1704
bitstrings in <c>BitstringList</c>. (The last tail in <c>BitstringList</c>
1705
is allowed to be a bitstring.)</p>
1707
> <input>Bin1 = <<1,2,3>>.</input>
1708
<<1,2,3>>
1709
> <input>Bin2 = <<4,5>>.</input>
1711
> <input>Bin3 = <<6,7:4,>>.</input>
1713
> <input>list_to_binary([Bin1,1,[2,3,Bin2],4|Bin3]).</input>
1714
<<1,2,3,1,2,3,4,5,4,6,7:46>></pre>
1718
<name>list_to_existing_atom(String) -> atom()</name>
1719
<fsummary>Convert from text representation to an atom</fsummary>
1721
<v>String = string()</v>
1724
<p>Returns the atom whose text representation is <c>String</c>,
1725
but only if there already exists such atom.</p>
1726
<p>Failure: <c>badarg</c> if there does not already exist an atom
1727
whose text representation is <c>String</c>.</p>
1731
<name>list_to_float(String) -> float()</name>
1732
<fsummary>Convert from text representation to a float</fsummary>
1734
<v>String = string()</v>
1737
<p>Returns the float whose text representation is <c>String</c>.</p>
1739
> <input>list_to_float("2.2017764e+0").</input>
1741
<p>Failure: <c>badarg</c> if <c>String</c> contains a bad
1742
representation of a float.</p>
1746
<name>list_to_integer(String) -> int()</name>
1747
<fsummary>Convert from text representation to an integer</fsummary>
1749
<v>String = string()</v>
1752
<p>Returns an integer whose text representation is
1755
> <input>list_to_integer("123").</input>
1757
<p>Failure: <c>badarg</c> if <c>String</c> contains a bad
1758
representation of an integer.</p>
1762
<name>erlang:list_to_integer(String, Base) -> int()</name>
1763
<fsummary>Convert from text representation to an integer</fsummary>
1765
<v>String = string()</v>
1769
<p>Returns an integer whose text representation in base
1770
<c>Base</c> is <c>String</c>.</p>
1772
> <input>erlang:list_to_integer("3FF", 16).</input>
1774
<p>Failure: <c>badarg</c> if <c>String</c> contains a bad
1775
representation of an integer.</p>
1779
<name>list_to_pid(String) -> pid()</name>
1780
<fsummary>Convert from text representation to a pid</fsummary>
1782
<v>String = string()</v>
1785
<p>Returns a pid whose text representation is <c>String</c>.</p>
1787
<p>This BIF is intended for debugging and for use in
1788
the Erlang operating system. It should not be used in
1789
application programs.</p>
1792
> <input>list_to_pid("<0.4.1>").</input>
1794
<p>Failure: <c>badarg</c> if <c>String</c> contains a bad
1795
representation of a pid.</p>
1799
<name>list_to_tuple(List) -> tuple()</name>
1800
<fsummary>Convert a list to a tuple</fsummary>
1802
<v>List = [term()]</v>
1805
<p>Returns a tuple which corresponds to <c>List</c>. <c>List</c>
1806
can contain any Erlang terms.</p>
1808
> <input>list_to_tuple([share, ['Ericsson_B', 163]]).</input>
1809
{share, ['Ericsson_B', 163]}</pre>
1813
<name>load_module(Module, Binary) -> {module, Module} | {error, Reason}</name>
1814
<fsummary>Load object code for a module</fsummary>
1816
<v>Module = atom()</v>
1817
<v>Binary = binary()</v>
1818
<v>Reason = badfile | not_purged | badfile</v>
1821
<p>If <c>Binary</c> contains the object code for the module
1822
<c>Module</c>, this BIF loads that object code. Also, if
1823
the code for the module <c>Module</c> already exists, all
1824
export references are replaced so they point to the newly
1825
loaded code. The previously loaded code is kept in the system
1826
as old code, as there may still be processes which are
1827
executing that code. It returns either
1828
<c>{module, Module}</c>, or <c>{error, Reason}</c> if loading
1829
fails. <c>Reason</c> is one of the following:</p>
1831
<tag><c>badfile</c></tag>
1833
<p>The object code in <c>Binary</c> has an incorrect format.</p>
1835
<tag><c>not_purged</c></tag>
1837
<p><c>Binary</c> contains a module which cannot be loaded
1838
because old code for this module already exists.</p>
1840
<tag><c>badfile</c></tag>
1842
<p>The object code contains code for another module than
1847
<p>This BIF is intended for the code server (see
1848
<seealso marker="code">code(3)</seealso>) and should not be
1854
<name>erlang:loaded() -> [Module]</name>
1855
<fsummary>List of all loaded modules</fsummary>
1857
<v>Module = atom()</v>
1860
<p>Returns a list of all loaded Erlang modules (current and/or
1861
old code), including preloaded modules.</p>
1862
<p>See also <seealso marker="code">code(3)</seealso>.</p>
1866
<name>erlang:localtime() -> {Date, Time}</name>
1867
<fsummary>Current local date and time</fsummary>
1869
<v>Date = {Year, Month, Day}</v>
1870
<v>Time = {Hour, Minute, Second}</v>
1871
<v> Year = Month = Day = Hour = Minute = Second = int()</v>
1874
<p>Returns the current local date and time
1875
<c>{{Year, Month, Day}, {Hour, Minute, Second}}</c>.</p>
1876
<p>The time zone and daylight saving time correction depend
1877
on the underlying OS.</p>
1879
> <input>erlang:localtime().</input>
1880
{{1996,11,6},{14,45,17}}</pre>
1884
<name>erlang:localtime_to_universaltime({Date1, Time1}) -> {Date2, Time2}</name>
1885
<fsummary>Convert from local to Universal Time Coordinated (UTC) date and time</fsummary>
1887
<v>Date1 = Date2 = {Year, Month, Day}</v>
1888
<v>Time1 = Time2 = {Hour, Minute, Second}</v>
1889
<v> Year = Month = Day = Hour = Minute = Second = int()</v>
1892
<p>Converts local date and time to Universal Time Coordinated
1893
(UTC), if this is supported by the underlying OS. Otherwise,
1894
no conversion is done and <c>{Date1, Time1}</c> is returned.</p>
1896
> <input>erlang:localtime_to_universaltime({{1996,11,6},{14,45,17}}).</input>
1897
{{1996,11,6},{13,45,17}}</pre>
1898
<p>Failure: <c>badarg</c> if <c>Date1</c> or <c>Time1</c> do
1899
not denote a valid date or time.</p>
1903
<name>erlang:localtime_to_universaltime({Date1, Time1}, IsDst) -> {Date2, Time2}</name>
1904
<fsummary>Convert from local to Universal Time Coordinated (UTC) date and time</fsummary>
1906
<v>Date1 = Date2 = {Year, Month, Day}</v>
1907
<v>Time1 = Time2 = {Hour, Minute, Second}</v>
1908
<v> Year = Month = Day = Hour = Minute = Second = int()</v>
1909
<v>IsDst = true | false | undefined</v>
1912
<p>Converts local date and time to Universal Time Coordinated
1913
(UTC) just like <c>erlang:localtime_to_universaltime/1</c>,
1914
but the caller decides if daylight saving time is active or
1916
<p>If <c>IsDst == true</c> the <c>{Date1, Time1}</c> is during
1917
daylight saving time, if <c>IsDst == false</c> it is not,
1918
and if <c>IsDst == undefined</c> the underlying OS may
1919
guess, which is the same as calling
1920
<c>erlang:localtime_to_universaltime({Date1, Time1})</c>.</p>
1922
> <input>erlang:localtime_to_universaltime({{1996,11,6},{14,45,17}}, true).</input>
1923
{{1996,11,6},{12,45,17}}
1924
> <input>erlang:localtime_to_universaltime({{1996,11,6},{14,45,17}}, false).</input>
1925
{{1996,11,6},{13,45,17}}
1926
> <input>erlang:localtime_to_universaltime({{1996,11,6},{14,45,17}}, undefined).</input>
1927
{{1996,11,6},{13,45,17}}</pre>
1928
<p>Failure: <c>badarg</c> if <c>Date1</c> or <c>Time1</c> do
1929
not denote a valid date or time.</p>
1933
<name>make_ref() -> ref()</name>
1934
<fsummary>Return an almost unique reference</fsummary>
1936
<p>Returns an almost unique reference.</p>
1937
<p>The returned reference will re-occur after approximately 2^82
1938
calls; therefore it is unique enough for practical purposes.</p>
1940
> <input>make_ref().</input>
1941
#Ref<0.0.0.135></pre>
1945
<name>erlang:make_tuple(Arity, InitialValue) -> tuple()</name>
1946
<fsummary>Create a new tuple of a given arity</fsummary>
1948
<v>Arity = int()</v>
1949
<v>InitialValue = term()</v>
1952
<p>Returns a new tuple of the given <c>Arity</c>, where all
1953
elements are <c>InitialValue</c>.</p>
1955
> <input>erlang:make_tuple(4, []).</input>
1960
<name>erlang:md5(Data) -> Digest</name>
1961
<fsummary>Compute an MD5 message digest</fsummary>
1963
<v>Data = iodata()</v>
1964
<v>Digest = binary()</v>
1967
<p>Computes an <c>MD5</c> message digest from <c>Data</c>, where
1968
the length of the digest is 128 bits (16 bytes). <c>Data</c>
1969
is a binary or a list of small integers and binaries.</p>
1970
<p>See The MD5 Message Digest Algorithm (RFC 1321) for more
1971
information about MD5.</p>
1972
<warning><p>The MD5 Message Digest Algorithm is <em>not</em> considered
1973
safe for code-signing or software integrity purposes.</p></warning>
1977
<name>erlang:md5_final(Context) -> Digest</name>
1978
<fsummary>Finish the update of an MD5 context and return the computed MD5 message digest</fsummary>
1980
<v>Context = Digest = binary()</v>
1983
<p>Finishes the update of an MD5 <c>Context</c> and returns
1984
the computed <c>MD5</c> message digest.</p>
1988
<name>erlang:md5_init() -> Context</name>
1989
<fsummary>Create an MD5 context</fsummary>
1991
<v>Context = binary()</v>
1994
<p>Creates an MD5 context, to be used in subsequent calls to
1995
<c>md5_update/2</c>.</p>
1999
<name>erlang:md5_update(Context, Data) -> NewContext</name>
2000
<fsummary>Update an MD5 context with data, and return a new context</fsummary>
2002
<v>Data = iodata()</v>
2003
<v>Context = NewContext = binary()</v>
2006
<p>Updates an MD5 <c>Context</c> with <c>Data</c>, and returns
2007
a <c>NewContext</c>.</p>
2011
<name>erlang:memory() -> [{Type, Size}]</name>
2012
<fsummary>Information about dynamically allocated memory</fsummary>
2014
<v>Type, Size -- see below</v>
2017
<p>Returns a list containing information about memory
2018
dynamically allocated by the Erlang emulator. Each element of
2019
the list is a tuple <c>{Type, Size}</c>. The first element
2020
<c>Type</c>is an atom describing memory type. The second
2021
element <c>Size</c>is memory size in bytes. A description of
2022
each memory type follows:</p>
2024
<tag><c>total</c></tag>
2026
<p>The total amount of memory currently allocated, which is
2027
the same as the sum of memory size for <c>processes</c>
2028
and <c>system</c>.</p>
2030
<tag><c>processes</c></tag>
2032
<p>The total amount of memory currently allocated by
2033
the Erlang processes.</p>
2035
<tag><c>processes_used</c></tag>
2037
<p>The total amount of memory currently used by the Erlang
2039
<p>This memory is part of the memory presented as
2040
<c>processes</c> memory.</p>
2042
<tag><c>system</c></tag>
2044
<p>The total amount of memory currently allocated by
2045
the emulator that is not directly related to any Erlang
2047
<p>Memory presented as <c>processes</c> is not included in
2050
<tag><c>atom</c></tag>
2052
<p>The total amount of memory currently allocated for atoms.</p>
2053
<p>This memory is part of the memory presented as
2054
<c>system</c> memory.</p>
2056
<tag><c>atom_used</c></tag>
2058
<p>The total amount of memory currently used for atoms.</p>
2059
<p>This memory is part of the memory presented as
2060
<c>atom</c> memory.</p>
2062
<tag><c>binary</c></tag>
2064
<p>The total amount of memory currently allocated for
2066
<p>This memory is part of the memory presented as
2067
<c>system</c> memory.</p>
2069
<tag><c>code</c></tag>
2071
<p>The total amount of memory currently allocated for
2073
<p>This memory is part of the memory presented as
2074
<c>system</c> memory.</p>
2076
<tag><c>ets</c></tag>
2078
<p>The total amount of memory currently allocated for ets
2080
<p>This memory is part of the memory presented as
2081
<c>system</c> memory.</p>
2083
<tag><c>maximum</c></tag>
2085
<p>The maximum total amount of memory allocated since
2086
the emulator was started.</p>
2087
<p>This tuple is only present when the emulator is run with
2088
instrumentation.</p>
2089
<p>For information on how to run the emulator with
2091
<seealso marker="tools:instrument">instrument(3)</seealso>
2092
and/or <seealso marker="erts:erl">erl(1)</seealso>.</p>
2096
<p>The <c>system</c> value is not complete. Some allocated
2097
memory that should be part of the <c>system</c> value are
2099
<p>When the emulator is run with instrumentation,
2100
the <c>system</c> value is more accurate, but memory
2101
directly allocated by <c>malloc</c> (and friends) are still
2102
not part of the <c>system</c> value. Direct calls to
2103
<c>malloc</c> are only done from OS specific runtime
2104
libraries and perhaps from user implemented Erlang drivers
2105
that do not use the memory allocation functions in
2106
the driver interface.</p>
2107
<p>Since the <c>total</c> value is the sum of <c>processes</c>
2108
and <c>system</c> the error in <c>system</c> will propagate
2109
to the <c>total</c> value.</p>
2110
<p>The different amounts of memory that are summed are
2111
<em>not</em> gathered atomically which also introduce
2112
an error in the result.</p>
2114
<p>The different values has the following relation to each
2115
other. Values beginning with an uppercase letter is not part
2118
\011total = processes + system
2119
\011processes = processes_used + ProcessesNotUsed
2120
\011system = atom + binary + code + ets + OtherSystem
2121
\011atom = atom_used + AtomNotUsed
2123
\011RealTotal = processes + RealSystem
2124
\011RealSystem = system + MissedSystem</code>
2125
<p>More tuples in the returned list may be added in the future.</p>
2127
<p>The <c>total</c> value is supposed to be the total amount
2128
of memory dynamically allocated by the emulator. Shared
2129
libraries, the code of the emulator itself, and
2130
the emulator stack(s) are not supposed to be included. That
2131
is, the <c>total</c> value is <em>not</em> supposed to be
2132
equal to the total size of all pages mapped to the emulator.
2133
Furthermore, due to fragmentation and pre-reservation of
2134
memory areas, the size of the memory segments which contain
2135
the dynamically allocated memory blocks can be substantially
2136
larger than the total size of the dynamically allocated
2141
Since erts version 5.6.4 <c>erlang:memory/0</c> requires that
2142
all <seealso marker="erts:erts_alloc">erts_alloc(3)</seealso>
2143
allocators are enabled (default behaviour).
2148
<tag><c>notsup</c></tag>
2150
If an <seealso marker="erts:erts_alloc">erts_alloc(3)</seealso>
2151
allocator has been disabled.
2157
<name>erlang:memory(Type | [Type]) -> Size | [{Type, Size}]</name>
2158
<fsummary>Information about dynamically allocated memory</fsummary>
2160
<v>Type, Size -- see below</v>
2163
<p>Returns the memory size in bytes allocated for memory of
2164
type <c>Type</c>. The argument can also be given as a list
2165
of <c>Type</c> atoms, in which case a corresponding list of
2166
<c>{Type, Size}</c> tuples is returned.</p>
2169
Since erts version 5.6.4 <c>erlang:memory/1</c> requires that
2170
all <seealso marker="erts:erts_alloc">erts_alloc(3)</seealso>
2171
allocators are enabled (default behaviour).
2176
<tag><c>badarg</c></tag>
2178
If <c>Type</c> is not one of the memory types listed in the
2180
<seealso marker="#erlang:memory/0">erlang:memory/0</seealso>.
2182
<tag><c>badarg</c></tag>
2184
If <c>maximum</c> is passed as <c>Type</c> and the emulator
2185
is not run in instrumented mode.
2187
<tag><c>notsup</c></tag>
2189
If an <seealso marker="erts:erts_alloc">erts_alloc(3)</seealso>
2190
allocator has been disabled.
2194
<seealso marker="#erlang:memory/0">erlang:memory/0</seealso>.</p>
2198
<name>module_loaded(Module) -> bool()</name>
2199
<fsummary>Check if a module is loaded</fsummary>
2201
<v>Module = atom()</v>
2204
<p>Returns <c>true</c> if the module <c>Module</c> is loaded,
2205
otherwise returns <c>false</c>. It does not attempt to load
2208
<p>This BIF is intended for the code server (see
2209
<seealso marker="code">code(3)</seealso>) and should not be
2215
<name>erlang:monitor(Type, Item) -> MonitorRef</name>
2216
<fsummary>Start monitoring</fsummary>
2218
<v>Type = process</v>
2219
<v>Item = pid() | {RegName, Node} | RegName</v>
2220
<v> RegName = atom()</v>
2221
<v> Node = node()</v>
2222
<v>MonitorRef = reference()</v>
2225
<p>The calling process starts monitoring <c>Item</c> which is
2226
an object of type <c>Type</c>.</p>
2227
<p>Currently only processes can be monitored, i.e. the only
2228
allowed <c>Type</c> is <c>process</c>, but other types may be
2229
allowed in the future.</p>
2230
<p><c>Item</c> can be:</p>
2232
<tag><c>pid()</c></tag>
2234
<p>The pid of the process to monitor.</p>
2236
<tag><c>{RegName, Node}</c></tag>
2238
<p>A tuple consisting of a registered name of a process and
2239
a node name. The process residing on the node <c>Node</c>
2240
with the registered name <c>RegName</c> will be monitored.</p>
2242
<tag><c>RegName</c></tag>
2244
<p>The process locally registered as <c>RegName</c> will be
2249
<p>When a process is monitored by registered name, the process
2250
that has the registered name at the time when
2251
<c>erlang:monitor/2</c> is called will be monitored.
2252
The monitor will not be effected, if the registered name is
2255
<p>A <c>'DOWN'</c> message will be sent to the monitoring
2256
process if <c>Item</c> dies, if <c>Item</c> does not exist,
2257
or if the connection is lost to the node which <c>Item</c>
2258
resides on. A <c>'DOWN'</c> message has the following pattern:</p>
2260
{'DOWN', MonitorRef, Type, Object, Info}</code>
2261
<p>where <c>MonitorRef</c> and <c>Type</c> are the same as
2262
described above, and:</p>
2264
<tag><c>Object</c></tag>
2266
<p>A reference to the monitored object:</p>
2267
<list type="bulleted">
2268
<item>the pid of the monitored process, if <c>Item</c> was
2269
specified as a pid.</item>
2270
<item><c>{RegName, Node}</c>, if <c>Item</c> was specified as
2271
<c>{RegName, Node}</c>.</item>
2272
<item><c>{RegName, Node}</c>, if <c>Item</c> was specified as
2273
<c>RegName</c>. <c>Node</c> will in this case be the
2274
name of the local node (<c>node()</c>).</item>
2277
<tag><c>Info</c></tag>
2279
<p>Either the exit reason of the process, <c>noproc</c>
2280
(non-existing process), or <c>noconnection</c> (no
2281
connection to <c>Node</c>).</p>
2285
<p>If/when <c>erlang:monitor/2</c> is extended (e.g. to
2286
handle other item types than <c>process</c>), other
2287
possible values for <c>Object</c>, and <c>Info</c> in the
2288
<c>'DOWN'</c> message will be introduced.</p>
2290
<p>The monitoring is turned off either when the <c>'DOWN'</c>
2291
message is sent, or when
2292
<seealso marker="#erlang:demonitor/1">erlang:demonitor/1</seealso>
2294
<p>If an attempt is made to monitor a process on an older node
2295
(where remote process monitoring is not implemented or one
2296
where remote process monitoring by registered name is not
2297
implemented), the call fails with <c>badarg</c>.</p>
2298
<p>Making several calls to <c>erlang:monitor/2</c> for the same
2299
<c>Item</c> is not an error; it results in as many, completely
2300
independent, monitorings.</p>
2302
<p>The format of the <c>'DOWN'</c> message changed in the 5.2
2303
version of the emulator (OTP release R9B) for monitor <em>by registered name</em>. The <c>Object</c> element of
2304
the <c>'DOWN'</c> message could in earlier versions
2305
sometimes be the pid of the monitored process and sometimes
2306
be the registered name. Now the <c>Object</c> element is
2307
always a tuple consisting of the registered name and
2308
the node name. Processes on new nodes (emulator version 5.2
2309
or greater) will always get <c>'DOWN'</c> messages on
2310
the new format even if they are monitoring processes on old
2311
nodes. Processes on old nodes will always get <c>'DOWN'</c>
2312
messages on the old format.</p>
2317
<name>monitor_node(Node, Flag) -> true</name>
2318
<fsummary>Monitor the status of a node</fsummary>
2320
<v>Node = node()</v>
2321
<v>Flag = bool()</v>
2324
<p>Monitors the status of the node <c>Node</c>. If <c>Flag</c>
2325
is <c>true</c>, monitoring is turned on; if <c>Flag</c> is
2326
<c>false</c>, monitoring is turned off.</p>
2327
<p>Making several calls to <c>monitor_node(Node, true)</c> for
2328
the same <c>Node</c> is not an error; it results in as many,
2329
completely independent, monitorings.</p>
2330
<p>If <c>Node</c> fails or does not exist, the message
2331
<c>{nodedown, Node}</c> is delivered to the process. If a
2332
process has made two calls to <c>monitor_node(Node, true)</c>
2333
and <c>Node</c> terminates, two <c>nodedown</c> messages are
2334
delivered to the process. If there is no connection to
2335
<c>Node</c>, there will be an attempt to create one. If this
2336
fails, a <c>nodedown</c> message is delivered.</p>
2337
<p>Nodes connected through hidden connections can be monitored
2338
as any other node.</p>
2339
<p>Failure: <c>badarg</c>if the local node is not alive.</p>
2343
<name>erlang:monitor_node(Node, Flag, Options) -> true</name>
2344
<fsummary>Monitor the status of a node</fsummary>
2346
<v>Node = node()</v>
2347
<v>Flag = bool()</v>
2348
<v>Options = [Option]</v>
2349
<v>Option = allow_passive_connect</v>
2352
<p>Behaves as <c>monitor_node/2</c> except that it allows an
2353
extra option to be given, namely <c>allow_passive_connect</c>.
2354
The option allows the BIF to wait the normal net connection
2355
timeout for the <em>monitored node</em> to connect itself,
2356
even if it cannot be actively connected from this node
2357
(i.e. it is blocked). The state where this might be useful can
2358
only be achieved by using the kernel option
2359
<c>dist_auto_connect once</c>. If that kernel option is not
2360
used, the <c>allow_passive_connect</c> option has no
2363
<p>The <c>allow_passive_connect</c> option is used
2364
internally and is seldom needed in applications where the
2365
network topology and the kernel options in effect is known in
2368
<p>Failure: <c>badarg</c> if the local node is not alive or the
2369
option list is malformed.</p>
2373
<name>node() -> Node</name>
2374
<fsummary>Name of the local node</fsummary>
2376
<v>Node = node()</v>
2379
<p>Returns the name of the local node. If the node is not alive,
2380
<c>nonode@nohost</c> is returned instead.</p>
2381
<p>Allowed in guard tests.</p>
2385
<name>node(Arg) -> Node</name>
2386
<fsummary>At which node is a pid, port or reference located</fsummary>
2388
<v>Arg = pid() | port() | ref()</v>
2389
<v>Node = node()</v>
2392
<p>Returns the node where <c>Arg</c> is located. <c>Arg</c> can
2393
be a pid, a reference, or a port. If the local node is not
2394
alive, <c>nonode@nohost</c> is returned.</p>
2395
<p>Allowed in guard tests.</p>
2399
<name>nodes() -> Nodes</name>
2400
<fsummary>All visible nodes in the system</fsummary>
2402
<v>Nodes = [node()]</v>
2405
<p>Returns a list of all visible nodes in the system, excluding
2406
the local node. Same as <c>nodes(visible)</c>.</p>
2410
<name>nodes(Arg | [Arg]) -> Nodes</name>
2411
<fsummary>All nodes of a certain type in the system</fsummary>
2413
<v>Arg = visible | hidden | connected | this | known</v>
2414
<v>Nodes = [node()]</v>
2417
<p>Returns a list of nodes according to argument given.
2418
The result returned when the argument is a list, is the list
2419
of nodes satisfying the disjunction(s) of the list elements.</p>
2420
<p><c>Arg</c> can be any of the following:</p>
2422
<tag><c>visible</c></tag>
2424
<p>Nodes connected to this node through normal connections.</p>
2426
<tag><c>hidden</c></tag>
2428
<p>Nodes connected to this node through hidden connections.</p>
2430
<tag><c>connected</c></tag>
2432
<p>All nodes connected to this node.</p>
2434
<tag><c>this</c></tag>
2438
<tag><c>known</c></tag>
2440
<p>Nodes which are known to this node, i.e., connected,
2441
previously connected, etc.</p>
2444
<p>Some equalities: <c>[node()] = nodes(this)</c>,
2445
<c>nodes(connected) = nodes([visible, hidden])</c>, and
2446
<c>nodes() = nodes(visible)</c>.</p>
2447
<p>If the local node is not alive,
2448
<c>nodes(this) == nodes(known) == [nonode@nohost]</c>, for
2449
any other <c>Arg</c> the empty list [] is returned.</p>
2453
<name>now() -> {MegaSecs, Secs, MicroSecs}</name>
2454
<fsummary>Elapsed time since 00:00 GMT</fsummary>
2456
<v>MegaSecs = Secs = MicroSecs = int()</v>
2459
<p>Returns the tuple <c>{MegaSecs, Secs, MicroSecs}</c> which is
2460
the elapsed time since 00:00 GMT, January 1, 1970 (zero hour)
2461
on the assumption that the underlying OS supports this.
2462
Otherwise, some other point in time is chosen. It is also
2463
guaranteed that subsequent calls to this BIF returns
2464
continuously increasing values. Hence, the return value from
2465
<c>now()</c> can be used to generate unique time-stamps. It
2466
can only be used to check the local time of day if
2467
the time-zone info of the underlying operating system is
2468
properly configured.</p>
2472
<name>open_port(PortName, PortSettings) -> port()</name>
2473
<fsummary>Open a port</fsummary>
2475
<v>PortName = {spawn, Command} | {fd, In, Out}</v>
2476
<v> Command = string()</v>
2477
<v> In = Out = int()</v>
2478
<v>PortSettings = [Opt]</v>
2479
<v> Opt = {packet, N} | stream | {line, L} | {cd, Dir} | {env, Env} | exit_status | use_stdio | nouse_stdio | stderr_to_stdout | in | out | binary | eof</v>
2480
<v> N = 1 | 2 | 4</v>
2481
<v> L = int()</v>
2482
<v> Dir = string()</v>
2483
<v> Env = [{Name, Val}]</v>
2484
<v> Name = string()</v>
2485
<v> Val = string() | false</v>
2488
<p>Returns a port identifier as the result of opening a
2489
new Erlang port. A port can be seen as an external Erlang
2490
process. <c>PortName</c> is one of the following:</p>
2492
<tag><c>{spawn, Command}</c></tag>
2494
<p>Starts an external program. <c>Command</c> is the name
2495
of the external program which will be run. <c>Command</c>
2496
runs outside the Erlang work space unless an Erlang
2497
driver with the name <c>Command</c> is found. If found,
2498
that driver will be started. A driver runs in the Erlang
2499
workspace, which means that it is linked with the Erlang
2501
<p>When starting external programs on Solaris, the system
2502
call <c>vfork</c> is used in preference to <c>fork</c>
2503
for performance reasons, although it has a history of
2504
being less robust. If there are problems with using
2505
<c>vfork</c>, setting the environment variable
2506
<c>ERL_NO_VFORK</c> to any value will cause <c>fork</c>
2507
to be used instead.</p>
2509
<tag><c>{fd, In, Out}</c></tag>
2511
<p>Allows an Erlang process to access any currently opened
2512
file descriptors used by Erlang. The file descriptor
2513
<c>In</c> can be used for standard input, and the file
2514
descriptor <c>Out</c> for standard output. It is only
2515
used for various servers in the Erlang operating system
2516
(<c>shell</c> and <c>user</c>). Hence, its use is very
2520
<p><c>PortSettings</c> is a list of settings for the port.
2521
Valid settings are:</p>
2523
<tag><c>{packet, N}</c></tag>
2525
<p>Messages are preceded by their length, sent in <c>N</c>
2526
bytes, with the most significant byte first. Valid values
2527
for <c>N</c> are 1, 2, or 4.</p>
2529
<tag><c>stream</c></tag>
2531
<p>Output messages are sent without packet lengths. A
2532
user-defined protocol must be used between the Erlang
2533
process and the external object.</p>
2535
<tag><c>{line, L}</c></tag>
2537
<p>Messages are delivered on a per line basis. Each line
2538
(delimited by the OS-dependent newline sequence) is
2539
delivered in one single message. The message data format
2540
is <c>{Flag, Line}</c>, where <c>Flag</c> is either
2541
<c>eol</c> or <c>noeol</c> and <c>Line</c> is the actual
2542
data delivered (without the newline sequence).</p>
2543
<p><c>L</c> specifies the maximum line length in bytes.
2544
Lines longer than this will be delivered in more than one
2545
message, with the <c>Flag</c> set to <c>noeol</c> for all
2546
but the last message. If end of file is encountered
2547
anywhere else than immediately following a newline
2548
sequence, the last line will also be delivered with
2549
the <c>Flag</c> set to <c>noeol</c>. In all other cases,
2550
lines are delivered with <c>Flag</c> set to <c>eol</c>.</p>
2551
<p>The <c>{packet, N}</c> and <c>{line, L}</c> settings are
2552
mutually exclusive.</p>
2554
<tag><c>{cd, Dir}</c></tag>
2556
<p>This is only valid for <c>{spawn, Command}</c>.
2557
The external program starts using <c>Dir</c> as its
2558
working directory. <c>Dir</c> must be a string. Not
2559
available on VxWorks.</p>
2561
<tag><c>{env, Env}</c></tag>
2563
<p>This is only valid for <c>{spawn, Command}</c>.
2564
The environment of the started process is extended using
2565
the environment specifications in <c>Env</c>.</p>
2566
<p><c>Env</c> should be a list of tuples <c>{Name, Val}</c>,
2567
where <c>Name</c> is the name of an environment variable,
2568
and <c>Val</c> is the value it is to have in the spawned
2569
port process. Both <c>Name</c> and <c>Val</c> must be
2570
strings. The one exception is <c>Val</c> being the atom
2571
<c>false</c> (in analogy with <c>os:getenv/1</c>), which
2572
removes the environment variable. Not available on
2575
<tag><c>exit_status</c></tag>
2577
<p>This is only valid for <c>{spawn, Command}</c> where
2578
<c>Command</c> refers to an external program.</p>
2579
<p>When the external process connected to the port exits, a
2580
message of the form <c>{Port,{exit_status,Status}}</c> is
2581
sent to the connected process, where <c>Status</c> is the
2582
exit status of the external process. If the program
2583
aborts, on Unix the same convention is used as the shells
2584
do (i.e., 128+signal).</p>
2585
<p>If the <c>eof</c> option has been given as well,
2586
the <c>eof</c> message and the <c>exit_status</c> message
2587
appear in an unspecified order.</p>
2588
<p>If the port program closes its stdout without exiting,
2589
the <c>exit_status</c> option will not work.</p>
2591
<tag><c>use_stdio</c></tag>
2593
<p>This is only valid for <c>{spawn, Command}</c>. It
2594
allows the standard input and output (file descriptors 0
2595
and 1) of the spawned (UNIX) process for communication
2598
<tag><c>nouse_stdio</c></tag>
2600
<p>The opposite of <c>use_stdio</c>. Uses file descriptors
2601
3 and 4 for communication with Erlang.</p>
2603
<tag><c>stderr_to_stdout</c></tag>
2605
<p>Affects ports to external programs. The executed program
2606
gets its standard error file redirected to its standard
2607
output file. <c>stderr_to_stdout</c> and
2608
<c>nouse_stdio</c> are mutually exclusive.</p>
2610
<tag><c>in</c></tag>
2612
<p>The port can only be used for input.</p>
2614
<tag><c>out</c></tag>
2616
<p>The port can only be used for output.</p>
2618
<tag><c>binary</c></tag>
2620
<p>All IO from the port are binary data objects as opposed
2621
to lists of bytes.</p>
2623
<tag><c>eof</c></tag>
2625
<p>The port will not be closed at the end of the file and
2626
produce an exit signal. Instead, it will remain open and
2627
a <c>{Port, eof}</c> message will be sent to the process
2628
holding the port.</p>
2630
<tag><c>hide</c></tag>
2632
<p>When running on Windows, suppress creation of a new
2633
console window when spawning the port program.
2634
(This option has no effect on other platforms.)</p>
2637
<p>The default is <c>stream</c> for all types of port and
2638
<c>use_stdio</c> for spawned ports.</p>
2639
<p>Failure: If the port cannot be opened, the exit reason is
2640
<c>badarg</c>, <c>system_limit</c>, or the Posix error code which
2641
most closely describes the error, or <c>einval</c> if no Posix code
2644
<tag><c>badarg</c></tag>
2646
<p>Bad input arguments to <c>open_port</c>.</p>
2648
<tag><c>system_limit</c></tag>
2650
<p>All available ports in the Erlang emulator are in use.</p>
2652
<tag><c>enomem</c></tag>
2654
<p>There was not enough memory to create the port.</p>
2656
<tag><c>eagain</c></tag>
2658
<p>There are no more available operating system processes.</p>
2660
<tag><c>enametoolong</c></tag>
2662
<p>The external command given was too long.</p>
2664
<tag><c>emfile</c></tag>
2666
<p>There are no more available file descriptors (for the operating system process
2667
that the Erlang emulator runs in).</p>
2669
<tag><c>enfile</c></tag>
2671
<p>The file table is full (for the entire operating system).</p>
2674
<p>During use of a port opened using <c>{spawn, Name}</c>,
2675
errors arising when sending messages to it are reported to
2676
the owning process using signals of the form
2677
<c>{'EXIT', Port, PosixCode}</c>. See <c>file(3)</c> for
2678
possible values of <c>PosixCode</c>.</p>
2679
<p><marker id="ERL_MAX_PORTS"></marker>
2680
The maximum number of ports that can be open at the same
2681
time is 1024 by default, but can be configured by
2682
the environment variable <c>ERL_MAX_PORTS</c>.</p>
2686
<name>erlang:phash(Term, Range) -> Hash</name>
2687
<fsummary>Portable hash function</fsummary>
2689
<v>Term = term()</v>
2690
<v>Range = 1..2^32</v>
2691
<v>Hash = 1..Range</v>
2694
<p>Portable hash function that will give the same hash for
2695
the same Erlang term regardless of machine architecture and
2696
ERTS version (the BIF was introduced in ERTS 4.9.1.1). Range
2697
can be between 1 and 2^32, the function returns a hash value
2698
for <c>Term</c> within the range <c>1..Range</c>.</p>
2699
<p>This BIF could be used instead of the old deprecated
2700
<c>erlang:hash/2</c> BIF, as it calculates better hashes for
2701
all data-types, but consider using <c>phash2/1,2</c> instead.</p>
2705
<name>erlang:phash2(Term [, Range]) -> Hash</name>
2706
<fsummary>Portable hash function</fsummary>
2708
<v>Term = term()</v>
2709
<v>Range = 1..2^32</v>
2710
<v>Hash = 0..Range-1</v>
2713
<p>Portable hash function that will give the same hash for
2714
the same Erlang term regardless of machine architecture and
2715
ERTS version (the BIF was introduced in ERTS 5.2). Range can
2716
be between 1 and 2^32, the function returns a hash value for
2717
<c>Term</c> within the range <c>0..Range-1</c>. When called
2718
without the <c>Range</c> argument, a value in the range
2719
<c>0..2^27-1</c> is returned.</p>
2720
<p>This BIF should always be used for hashing terms. It
2721
distributes small integers better than <c>phash/2</c>, and
2722
it is faster for bignums and binaries.</p>
2723
<p>Note that the range <c>0..Range-1</c> is different from
2724
the range of <c>phash/2</c> (<c>1..Range</c>).</p>
2728
<name>pid_to_list(Pid) -> string()</name>
2729
<fsummary>Text representation of a pid</fsummary>
2734
<p>Returns a string which corresponds to the text
2735
representation of <c>Pid</c>.</p>
2737
<p>This BIF is intended for debugging and for use in
2738
the Erlang operating system. It should not be used in
2739
application programs.</p>
2744
<name>port_close(Port) -> true</name>
2745
<fsummary>Close an open port</fsummary>
2747
<v>Port = port() | atom()</v>
2750
<p>Closes an open port. Roughly the same as
2751
<c>Port ! {self(), close}</c> except for the error behaviour
2752
(see below), and that the port does <em>not</em> reply with
2753
<c>{Port, closed}</c>. Any process may close a port with
2754
<c>port_close/1</c>, not only the port owner (the connected
2756
<p>For comparison: <c>Port ! {self(), close}</c> fails with
2757
<c>badarg</c> if <c>Port</c> cannot be sent to (i.e.,
2758
<c>Port</c> refers neither to a port nor to a process). If
2759
<c>Port</c> is a closed port nothing happens. If <c>Port</c>
2760
is an open port and the calling process is the port owner,
2761
the port replies with <c>{Port, closed}</c> when all buffers
2762
have been flushed and the port really closes, but if
2763
the calling process is not the port owner the <em>port owner</em> fails with <c>badsig</c>.</p>
2764
<p>Note that any process can close a port using
2765
<c>Port ! {PortOwner, close}</c> just as if it itself was
2766
the port owner, but the reply always goes to the port owner.</p>
2767
<p>In short: <c>port_close(Port)</c> has a cleaner and more
2768
logical behaviour than <c>Port ! {self(), close}</c>.</p>
2769
<p>Failure: <c>badarg</c> if <c>Port</c> is not an open port or
2770
the registered name of an open port.</p>
2774
<name>port_command(Port, Data) -> true</name>
2775
<fsummary>Send data to a port</fsummary>
2777
<v>Port = port() | atom()</v>
2778
<v>Data = iodata()</v>
2781
<p>Sends data to a port. Same as
2782
<c>Port ! {self(), {command, Data}}</c> except for the error
2783
behaviour (see below). Any process may send data to a port
2784
with <c>port_command/2</c>, not only the port owner
2785
(the connected process).</p>
2786
<p>For comparison: <c>Port ! {self(), {command, Data}}</c>
2787
fails with <c>badarg</c> if <c>Port</c> cannot be sent to
2788
(i.e., <c>Port</c> refers neither to a port nor to a process).
2789
If <c>Port</c> is a closed port the data message disappears
2790
without a sound. If <c>Port</c> is open and the calling
2791
process is not the port owner, the <em>port owner</em> fails
2792
with <c>badsig</c>. The port owner fails with <c>badsig</c>
2793
also if <c>Data</c> is not a valid IO list.</p>
2794
<p>Note that any process can send to a port using
2795
<c>Port ! {PortOwner, {command, Data}}</c> just as if it
2796
itself was the port owner.</p>
2797
<p>In short: <c>port_command(Port, Data)</c> has a cleaner and
2798
more logical behaviour than
2799
<c>Port ! {self(), {command, Data}}</c>.</p>
2800
<p>Failure: <c>badarg</c> if <c>Port</c> is not an open port
2801
or the registered name of an open port.</p>
2805
<name>port_connect(Port, Pid) -> true</name>
2806
<fsummary>Set the owner of a port</fsummary>
2808
<v>Port = port() | atom()</v>
2812
<p>Sets the port owner (the connected port) to <c>Pid</c>.
2813
Roughly the same as <c>Port ! {self(), {connect, Pid}}</c>
2814
except for the following:</p>
2815
<list type="bulleted">
2817
<p>The error behavior differs, see below.</p>
2820
<p>The port does <em>not</em> reply with
2821
<c>{Port,connected}</c>.</p>
2824
<p>The new port owner gets linked to the port.</p>
2827
<p>The old port owner stays linked to the port and have to call
2828
<c>unlink(Port)</c> if this is not desired. Any process may
2829
set the port owner to be any process with
2830
<c>port_connect/2</c>.</p>
2831
<p>For comparison: <c>Port ! {self(), {connect, Pid}}</c> fails
2832
with <c>badarg</c> if <c>Port</c> cannot be sent to (i.e.,
2833
<c>Port</c> refers neither to a port nor to a process). If
2834
<c>Port</c> is a closed port nothing happens. If <c>Port</c>
2835
is an open port and the calling process is the port owner,
2836
the port replies with <c>{Port, connected}</c> to the old
2837
port owner. Note that the old port owner is still linked to
2838
the port, and that the new is not. If <c>Port</c> is an open
2839
port and the calling process is not the port owner,
2840
the <em>port owner</em> fails with <c>badsig</c>. The port
2841
owner fails with <c>badsig</c> also if <c>Pid</c> is not an
2842
existing local pid.</p>
2843
<p>Note that any process can set the port owner using
2844
<c>Port ! {PortOwner, {connect, Pid}}</c> just as if it
2845
itself was the port owner, but the reply always goes to
2847
<p>In short: <c>port_connect(Port, Pid)</c> has a cleaner and
2848
more logical behaviour than
2849
<c>Port ! {self(),{connect,Pid}}</c>.</p>
2850
<p>Failure: <c>badarg</c> if <c>Port</c> is not an open port
2851
or the registered name of an open port, or if <c>Pid</c> is
2852
not an existing local pid.</p>
2856
<name>port_control(Port, Operation, Data) -> Res</name>
2857
<fsummary>Perform a synchronous control operation on a port</fsummary>
2859
<v>Port = port() | atom()</v>
2860
<v>Operation = int()</v>
2861
<v>Data = Res = iodata()</v>
2864
<p>Performs a synchronous control operation on a port.
2865
The meaning of <c>Operation</c> and <c>Data</c> depends on
2866
the port, i.e., on the port driver. Not all port drivers
2867
support this control feature.</p>
2868
<p>Returns: a list of integers in the range 0 through 255, or a
2869
binary, depending on the port driver. The meaning of
2870
the returned data also depends on the port driver.</p>
2871
<p>Failure: <c>badarg</c> if <c>Port</c> is not an open port or
2872
the registered name of an open port, if <c>Operation</c>
2873
cannot fit in a 32-bit integer, if the port driver does not
2874
support synchronous control operations, or if the port driver
2875
so decides for any reason (probably something wrong with
2876
<c>Operation</c> or <c>Data</c>).</p>
2880
<name>erlang:port_call(Port, Operation, Data) -> term()</name>
2881
<fsummary>Synchronous call to a port with term data</fsummary>
2883
<v>Port = port() | atom()</v>
2884
<v>Operation = int()</v>
2885
<v>Data = term()</v>
2888
<p>Performs a synchronous call to a port. The meaning of
2889
<c>Operation</c> and <c>Data</c> depends on the port, i.e.,
2890
on the port driver. Not all port drivers support this feature.</p>
2891
<p><c>Port</c> is a port identifier, referring to a driver.</p>
2892
<p><c>Operation</c> is an integer, which is passed on to
2894
<p><c>Data</c> is any Erlang term. This data is converted to
2895
binary term format and sent to the port.</p>
2896
<p>Returns: a term from the driver. The meaning of the returned
2897
data also depends on the port driver.</p>
2898
<p>Failure: <c>badarg</c> if <c>Port</c> is not an open port or
2899
the registered name of an open port, if <c>Operation</c>
2900
cannot fit in a 32-bit integer, if the port driver does not
2901
support synchronous control operations, or if the port driver
2902
so decides for any reason (probably something wrong with
2903
<c>Operation</c> or <c>Data</c>).</p>
2907
<name>erlang:port_info(Port) -> [{Item, Info}] | undefined</name>
2908
<fsummary>Information about a port</fsummary>
2910
<v>Port = port() | atom()</v>
2911
<v>Item, Info -- see below</v>
2914
<p>Returns a list containing tuples with information about
2915
the <c>Port</c>, or <c>undefined</c> if the port is not open.
2916
The order of the tuples is not defined, nor are all the
2917
tuples mandatory.</p>
2919
<tag><c>{registered_name, RegName}</c></tag>
2921
<p><c>RegName</c> (an atom) is the registered name of
2922
the port. If the port has no registered name, this tuple
2923
is not present in the list.</p>
2925
<tag><c>{id, Index}</c></tag>
2927
<p><c>Index</c> (an integer) is the internal index of the
2928
port. This index may be used to separate ports.</p>
2930
<tag><c>{connected, Pid}</c></tag>
2932
<p><c>Pid</c> is the process connected to the port.</p>
2934
<tag><c>{links, Pids}</c></tag>
2936
<p><c>Pids</c> is a list of pids to which processes the
2939
<tag><c>{name, String}</c></tag>
2941
<p><c>String</c> is the command name set by
2942
<c>open_port</c>.</p>
2944
<tag><c>{input, Bytes}</c></tag>
2946
<p><c>Bytes</c> is the total number of bytes read from
2949
<tag><c>{output, Bytes}</c></tag>
2951
<p><c>Bytes</c> is the total number of bytes written to
2955
<p>Failure: <c>badarg</c> if <c>Port</c> is not a local port.</p>
2959
<name>erlang:port_info(Port, Item) -> {Item, Info} | undefined | []</name>
2960
<fsummary>Information about a port</fsummary>
2962
<v>Port = port() | atom()</v>
2963
<v>Item, Info -- see below</v>
2966
<p>Returns information about <c>Port</c> as specified
2967
by <c>Item</c>, or <c>undefined</c> if the port is not open.
2968
Also, if <c>Item == registered_name</c> and the port has no
2969
registered name, [] is returned.</p>
2970
<p>For valid values of <c>Item</c>, and corresponding
2971
values of <c>Info</c>, see
2972
<seealso marker="#erlang:port_info/1">erlang:port_info/1</seealso>.</p>
2973
<p>Failure: <c>badarg</c> if <c>Port</c> is not a local port.</p>
2977
<name>erlang:port_to_list(Port) -> string()</name>
2978
<fsummary>Text representation of a port identifier</fsummary>
2980
<v>Port = port()</v>
2983
<p>Returns a string which corresponds to the text
2984
representation of the port identifier <c>Port</c>.</p>
2986
<p>This BIF is intended for debugging and for use in
2987
the Erlang operating system. It should not be used in
2988
application programs.</p>
2993
<name>erlang:ports() -> [port()]</name>
2994
<fsummary>All open ports</fsummary>
2996
<p>Returns a list of all ports on the local node.</p>
3000
<name>pre_loaded() -> [Module]</name>
3001
<fsummary>List of all pre-loaded modules</fsummary>
3003
<v>Module = atom()</v>
3006
<p>Returns a list of Erlang modules which are pre-loaded in
3007
the system. As all loading of code is done through the file
3008
system, the file system must have been loaded previously.
3009
Hence, at least the module <c>init</c> must be pre-loaded.</p>
3013
<name>erlang:process_display(Pid, Type) -> void()</name>
3014
<fsummary>Write information about a local process on standard error</fsummary>
3017
<v>Type = backtrace</v>
3020
<p>Writes information about the local process <c>Pid</c> on
3021
standard error. The currently allowed value for the atom
3022
<c>Type</c> is <c>backtrace</c>, which shows the contents of
3023
the call stack, including information about the call chain, with
3024
the current function printed first. The format of the output
3025
is not further defined.</p>
3029
<name>process_flag(Flag, Value) -> OldValue</name>
3030
<fsummary>Set process flags for the calling process</fsummary>
3032
<v>Flag, Value, OldValue -- see below</v>
3035
<p>Sets certain flags for the process which calls this
3036
function. Returns the old value of the flag.</p>
3038
<tag><c>process_flag(trap_exit, Boolean)</c></tag>
3040
<p>When <c>trap_exit</c> is set to <c>true</c>, exit signals
3041
arriving to a process are converted to <c>{'EXIT', From, Reason}</c> messages, which can be received as ordinary
3042
messages. If <c>trap_exit</c> is set to <c>false</c>, the
3043
process exits if it receives an exit signal other than
3044
<c>normal</c> and the exit signal is propagated to its
3045
linked processes. Application processes should normally
3047
<p>See also <seealso marker="#exit/2">exit/2</seealso>.</p>
3049
<tag><c>process_flag(error_handler, Module)</c></tag>
3051
<p>This is used by a process to redefine the error handler
3052
for undefined function calls and undefined registered
3053
processes. Inexperienced users should not use this flag
3054
since code auto-loading is dependent on the correct
3055
operation of the error handling module.</p>
3057
<tag><c>process_flag(min_heap_size, MinHeapSize)</c></tag>
3059
<p>This changes the minimum heap size for the calling
3062
<tag><c>process_flag(priority, Level)</c></tag>
3064
<marker id="process_flag_priority"></marker>
3065
<p>This sets the process priority. <c>Level</c> is an atom.
3066
There are currently four priority levels: <c>low</c>,
3067
<c>normal</c>, <c>high</c>, and <c>max</c>. The default
3068
priority level is <c>normal</c>. <em>NOTE</em>: The
3069
<c>max</c> priority level is reserved for internal use in
3070
the Erlang runtime system, and should <em>not</em> be used
3073
<p>Internally in each priority level processes are scheduled
3074
in a round robin fashion.
3076
<p>Execution of processes on priority <c>normal</c> and
3077
priority <c>low</c> will be interleaved. Processes on
3078
priority <c>low</c> will be selected for execution less
3079
frequently than processes on priority <c>normal</c>.
3081
<p>When there are runnable processes on priority <c>high</c>
3082
no processes on priority <c>low</c>, or <c>normal</c> will
3083
be selected for execution. Note, however, that this does
3084
<em>not</em> mean that no processes on priority <c>low</c>,
3085
or <c>normal</c> will be able to run when there are
3086
processes on priority <c>high</c> running. On the runtime
3087
system with SMP support there might be more processes running
3088
in parallel than processes on priority <c>high</c>, i.e.,
3089
a <c>low</c>, and a <c>high</c> priority process might
3090
execute at the same time.
3092
<p>When there are runnable processes on priority <c>max</c>
3093
no processes on priority <c>low</c>, <c>normal</c>, or
3094
<c>high</c> will be selected for execution. As with the
3095
<c>high</c> priority, processes on lower priorities might
3096
execute in parallel with processes on priority <c>max</c>.
3098
<p>Scheduling is preemptive. Regardless of priority, a process
3099
is preempted when it has consumed more than a certain amount
3100
of reductions since the last time it was selected for
3103
<p><em>NOTE</em>: You should not depend on the scheduling
3104
to remain exactly as it is today. Scheduling, at least on
3105
the runtime system with SMP support, is very likely to be
3106
modified in the future in order to better utilize available
3109
<p>There is currently <em>no</em> automatic mechanism for
3110
avoiding priority inversion, such as priority inheritance,
3111
or priority ceilings. When using priorities you have
3112
to take this into account and handle such scenarios by
3115
<p>Making calls from a <c>high</c> priority process into code
3116
that you don't have control over may cause the <c>high</c>
3117
priority process to wait for a processes with lower
3118
priority, i.e., effectively decreasing the priority of the
3119
<c>high</c> priority process during the call. Even if this
3120
isn't the case with one version of the code that you don't
3121
have under your control, it might be the case in a future
3122
version of it. This might, for example, happen if a
3123
<c>high</c> priority process triggers code loading, since
3124
the code server runs on priority <c>normal</c>.
3126
<p>Other priorities than <c>normal</c> are normally not needed.
3127
When other priorities are used, they need to be used
3128
with care, especially the <c>high</c> priority <em>must</em>
3129
be used with care. A process on <c>high</c> priority should
3130
only perform work for short periods of time. Busy looping for
3131
long periods of time in a <c>high</c> priority process will
3132
most likely cause problems, since there are important servers
3133
in OTP running on priority <c>normal</c>.
3137
<tag><c>process_flag(save_calls, N)</c></tag>
3139
<p>When there are runnable processes on priority <c>max</c>
3140
no processes on priority <c>low</c>, <c>normal</c>, or
3141
<c>high</c> will be selected for execution. As with the
3142
<c>high</c> priority, processes on lower priorities might
3143
execute in parallel with processes on priority <c>max</c>.
3145
<p><c>N</c> must be an integer in the interval 0..10000.
3146
If <c>N</c> > 0, call saving is made active for the
3147
process, which means that information about the <c>N</c>
3148
most recent global function calls, BIF calls, sends and
3149
receives made by the process are saved in a list, which
3150
can be retrieved with
3151
<c>process_info(Pid, last_calls)</c>. A global function
3152
call is one in which the module of the function is
3153
explicitly mentioned. Only a fixed amount of information
3154
is saved: a tuple <c>{Module, Function, Arity}</c> for
3155
function calls, and the mere atoms <c>send</c>,
3156
<c>'receive'</c> and <c>timeout</c> for sends and receives
3157
(<c>'receive'</c> when a message is received and
3158
<c>timeout</c> when a receive times out). If <c>N</c> = 0,
3159
call saving is disabled for the process, which is the
3160
default. Whenever the size of the call saving list is set,
3161
its contents are reset.</p>
3163
<tag><c>process_flag(sensitive, Boolean)</c></tag>
3165
<p>Set or clear the <c>sensitive</c> flag for the current process.
3166
When a process has been marked as sensitive by calling
3167
<c>process_flag(sensitive, true)</c>, features in the run-time
3168
system that can be used for examining the data and/or inner working
3169
of the process are silently disabled.</p>
3170
<p>Features that are disabled include (but are not limited to)
3172
<p>Tracing: Trace flags can still be set for the process, but no
3173
trace messages of any kind will be generated.
3174
(If the <c>sensitive</c> flag is turned off, trace messages will
3175
again be generated if there are any trace flags set.)</p>
3176
<p>Sequential tracing: The sequential trace token will be propagated
3177
as usual, but no sequential trace messages will be generated.</p>
3178
<p><c>process_info/1,2</c> cannot be used to read out the message
3179
queue or the process dictionary (both will be returned as empty lists).</p>
3180
<p>Stack back-traces cannot be displayed for the process.</p>
3181
<p>In crash dumps, the stack, messages, and the process dictionary
3182
will be omitted.</p>
3183
<p>If <c>{save_calls,N}</c> has been set for the process, no
3184
function calls will be saved to the call saving list.
3185
(The call saving list will not be cleared; furthermore, send, receive,
3186
and timeout events will still be added to the list.)</p>
3192
<name>process_flag(Pid, Flag, Value) -> OldValue</name>
3193
<fsummary>Set process flags for a process</fsummary>
3196
<v>Flag, Value, OldValue -- see below</v>
3199
<p>Sets certain flags for the process <c>Pid</c>, in the same
3201
<seealso marker="#process_flag/2">process_flag/2</seealso>.
3202
Returns the old value of the flag. The allowed values for
3203
<c>Flag</c> are only a subset of those allowed in
3204
<c>process_flag/2</c>, namely: <c>save_calls</c>.</p>
3205
<p>Failure: <c>badarg</c> if <c>Pid</c> is not a local process.</p>
3209
<name>process_info(Pid) -> InfoResult</name>
3210
<fsummary>Information about a process</fsummary>
3213
<v>Item = atom()</v>
3214
<v>Info = term()</v>
3215
<v>InfoTuple = {Item, Info}</v>
3216
<v>InfoTupleList = [InfoTuple]</v>
3217
<v>InfoResult = InfoTupleList | undefined</v>
3220
<p>Returns a list containing <c>InfoTuple</c>s with
3221
miscellaneous information about the process identified by
3222
<c>Pid</c>, or <c>undefined</c> if the process is not alive.
3225
The order of the <c>InfoTuple</c>s is not defined, nor
3226
are all the <c>InfoTuple</c>s mandatory. The <c>InfoTuple</c>s
3227
part of the result may be changed without prior notice.
3228
Currently <c>InfoTuple</c>s with the following <c>Item</c>s
3229
are part of the result:
3230
<c>current_function</c>, <c>initial_call</c>, <c>status</c>,
3231
<c>message_queue_len</c>, <c>messages</c>, <c>links</c>,
3232
<c>dictionary</c>, <c>trap_exit</c>, <c>error_handler</c>,
3233
<c>priority</c>, <c>group_leader</c>, <c>total_heap_size</c>,
3234
<c>heap_size</c>, <c>stack_size</c>, <c>reductions</c>, and
3235
<c>garbage_collection</c>.
3236
If the process identified by <c>Pid</c> has a registered name
3237
also an <c>InfoTuple</c> with <c>Item == registered_name</c>
3240
<p>See <seealso marker="#process_info/2">process_info/2</seealso>
3241
for information about specific <c>InfoTuple</c>s.</p>
3243
<p>This BIF is intended for <em>debugging only</em>, use
3244
<seealso marker="#process_info/2">process_info/2</seealso>
3245
for all other purposes.
3248
<p>Failure: <c>badarg</c> if <c>Pid</c> is not a local process.</p>
3252
<name>process_info(Pid, ItemSpec) -> InfoResult</name>
3253
<fsummary>Information about a process</fsummary>
3256
<v>Item = atom()</v>
3257
<v>Info = term()</v>
3258
<v>ItemList = [Item]</v>
3259
<v>ItemSpec = Item | ItemList</v>
3260
<v>InfoTuple = {Item, Info}</v>
3261
<v>InfoTupleList = [InfoTuple]</v>
3262
<v>InfoResult = InfoTuple | InfoTupleList | undefined | []</v>
3265
<p>Returns information about the process identified by <c>Pid</c>
3266
as specified by the <c>ItemSpec</c>, or <c>undefined</c> if the
3267
process is not alive.
3269
<p>If the process is alive and <c>ItemSpec</c> is a single
3270
<c>Item</c>, the returned value is the corresponding
3271
<c>InfoTuple</c> unless <c>ItemSpec == registered_name</c>
3272
and the process has no registered name. In this case
3273
<c>[]</c> is returned. This strange behavior is due to
3274
historical reasons, and is kept for backward compatibility.
3276
<p>If <c>ItemSpec</c> is an <c>ItemList</c>, the result is an
3277
<c>InfoTupleList</c>. The <c>InfoTuple</c>s in the
3278
<c>InfoTupleList</c> will appear with the corresponding
3279
<c>Item</c>s in the same order as the <c>Item</c>s appeared
3280
in the <c>ItemList</c>. Valid <c>Item</c>s may appear multiple
3281
times in the <c>ItemList</c>.
3283
<note><p>If <c>registered_name</c> is part of an <c>ItemList</c>
3284
and the process has no name registered a
3285
<c>{registered_name, []}</c> <c>InfoTuple</c> <em>will</em>
3286
appear in the resulting <c>InfoTupleList</c>. This
3287
behavior is different than when
3288
<c>ItemSpec == registered_name</c>, and than when
3289
<c>process_info/1</c> is used.
3291
<p>Currently the following <c>InfoTuple</c>s with corresponding
3292
<c>Item</c>s are valid:</p>
3294
<tag><c>{backtrace, Bin}</c></tag>
3296
<p>The binary <c>Bin</c> contains the same information as
3298
<c>erlang:process_display(Pid, backtrace)</c>. Use
3299
<c>binary_to_list/1</c> to obtain the string of characters
3300
from the binary.</p>
3302
<tag><c>{binary, BinInfo}</c></tag>
3304
<p><c>BinInfo</c> is a list containing miscellaneous information
3305
about binaries currently being referred to by this process.
3306
This <c>InfoTuple</c> may be changed or removed without prior
3309
<tag><c>{catchlevel, CatchLevel}</c></tag>
3311
<p><c>CatchLevel</c> is the number of currently active
3312
catches in this process. This <c>InfoTuple</c> may be
3313
changed or removed without prior notice.</p>
3315
<tag><c>{current_function, {Module, Function, Args}}</c></tag>
3317
<p><c>Module</c>, <c>Function</c>, <c>Args</c> is
3318
the current function call of the process.</p>
3320
<tag><c>{dictionary, Dictionary}</c></tag>
3322
<p><c>Dictionary</c> is the dictionary of the process.</p>
3324
<tag><c>{error_handler, Module}</c></tag>
3326
<p><c>Module</c> is the error handler module used by
3327
the process (for undefined function calls, for example).</p>
3329
<tag><c>{garbage_collection, GCInfo}</c></tag>
3331
<p><c>GCInfo</c> is a list which contains miscellaneous
3332
information about garbage collection for this process.
3333
The content of <c>GCInfo</c> may be changed without
3336
<tag><c>{group_leader, GroupLeader}</c></tag>
3338
<p><c>GroupLeader</c> is group leader for the IO of
3341
<tag><c>{heap_size, Size}</c></tag>
3343
<p><c>Size</c> is the size in words of youngest heap generation
3344
of the process. This generation currently include the stack
3345
of the process. This information is highly implementation
3346
dependent, and may change if the implementation change.
3349
<tag><c>{initial_call, {Module, Function, Arity}}</c></tag>
3351
<p><c>Module</c>, <c>Function</c>, <c>Arity</c> is
3352
the initial function call with which the process was
3355
<tag><c>{links, Pids}</c></tag>
3357
<p><c>Pids</c> is a list of pids, with processes to
3358
which the process has a link.</p>
3360
<tag><c>{last_calls, false|Calls}</c></tag>
3362
<p>The value is <c>false</c> if call saving is not active
3363
for the process (see
3364
<seealso marker="#process_flag/3">process_flag/3</seealso>).
3365
If call saving is active, a list is returned, in which
3366
the last element is the most recent called.</p>
3368
<tag><c>{memory, Size}</c></tag>
3370
<p><c>Size</c> is the size in bytes of the process. This
3371
includes call stack, heap and internal structures.</p>
3373
<tag><c>{message_binary, BinInfo}</c></tag>
3375
<p><c>BinInfo</c> is a list containing miscellaneous information
3376
about binaries currently being referred to by the message
3377
area. This <c>InfoTuple</c> is only valid on an emulator
3378
using the hybrid heap type. This <c>InfoTuple</c> may be
3379
changed or removed without prior notice.</p>
3381
<tag><c>{message_queue_len, MessageQueueLen}</c></tag>
3383
<p><c>MessageQueueLen</c> is the number of messages
3384
currently in the message queue of the process. This is
3385
the length of the list <c>MessageQueue</c> returned as
3386
the info item <c>messages</c> (see below).</p>
3388
<tag><c>{messages, MessageQueue}</c></tag>
3390
<p><c>MessageQueue</c> is a list of the messages to
3391
the process, which have not yet been processed.</p>
3393
<tag><c>{monitored_by, Pids}</c></tag>
3395
<p>A list of pids that are monitoring the process (with
3396
<c>erlang:monitor/2</c>).</p>
3398
<tag><c>{monitors, Monitors}</c></tag>
3400
<p>A list of monitors (started by <c>erlang:monitor/2</c>)
3401
that are active for the process. For a local process
3402
monitor or a remote process monitor by pid, the list item
3403
is <c>{process, Pid}</c>, and for a remote process
3404
monitor by name, the list item is
3405
<c>{process, {RegName, Node}}</c>.</p>
3407
<tag><c>{priority, Level}</c></tag>
3409
<p><c>Level</c> is the current priority level for
3410
the process. For more information on priorities see
3411
<seealso marker="#process_flag_priority">process_flag(priority, Level)</seealso>.</p>
3413
<tag><c>{reductions, Number}</c></tag>
3415
<p><c>Number</c> is the number of reductions executed by
3418
<tag><c>{registered_name, Atom}</c></tag>
3420
<p><c>Atom</c> is the registered name of the process. If
3421
the process has no registered name, this tuple is not
3422
present in the list.</p>
3424
<tag><c>{sequential_trace_token, [] | SequentialTraceToken}</c></tag>
3426
<p><c>SequentialTraceToken</c> the sequential trace token for
3427
the process. This <c>InfoTuple</c> may be changed or removed
3428
without prior notice.</p>
3430
<tag><c>{stack_size, Size}</c></tag>
3432
<p><c>Size</c> is the stack size of the process in words.</p>
3434
<tag><c>{status, Status}</c></tag>
3436
<p><c>Status</c> is the status of the process. <c>Status</c>
3437
is <c>waiting</c> (waiting for a message), <c>running</c>,
3438
<c>runnable</c> (ready to run, but another process is
3439
running), or <c>suspended</c> (suspended on a "busy" port
3440
or by the <c>erlang:suspend_process/[1,2]</c> BIF).</p>
3442
<tag><c>{suspending, SuspendeeList}</c></tag>
3444
<p><c>SuspendeeList</c> is a list of <c>{Suspendee,
3445
ActiveSuspendCount, OutstandingSuspendCount}</c> tuples.
3446
<c>Suspendee</c> is the pid of a process that have been or is to
3447
be suspended by the process identified by <c>Pid</c> via the
3448
<seealso marker="#erlang:suspend_process/2">erlang:suspend_process/2</seealso>
3450
<seealso marker="#erlang:suspend_process/1">erlang:suspend_process/1</seealso>
3451
BIF. <c>ActiveSuspendCount</c> is the number of times the
3452
<c>Suspendee</c> has been suspended by <c>Pid</c>.
3453
<c>OutstandingSuspendCount</c> is the number of not yet
3454
completed suspend requests sent by <c>Pid</c>. That is,
3455
if <c>ActiveSuspendCount /= 0</c>, <c>Suspendee</c> is
3456
currently in the suspended state, and if
3457
<c>OutstandingSuspendCount /= 0</c> the <c>asynchronous</c>
3458
option of <c>erlang:suspend_process/2</c> has been used and
3459
the suspendee has not yet been suspended by <c>Pid</c>.
3460
Note that the <c>ActiveSuspendCount</c> and
3461
<c>OutstandingSuspendCount</c> are not the total suspend count
3462
on <c>Suspendee</c>, only the parts contributed by <c>Pid</c>.
3465
<tag><c>{total_heap_size, Size}</c></tag>
3467
<p><c>Size</c> is the total size in words of all heap
3468
fragments of the process. This currently include the stack
3472
<tag><c>{trace, InternalTraceFlags}</c></tag>
3474
<p><c>InternalTraceFlags</c> is an integer representing
3475
internal trace flag for this process. This <c>InfoTuple</c>
3476
may be changed or removed without prior notice.</p>
3478
<tag><c>{trap_exit, Boolean}</c></tag>
3480
<p><c>Boolean</c> is <c>true</c> if the process is trapping
3481
exits, otherwise it is <c>false</c>.</p>
3484
<p>Note however, that not all implementations support every one
3485
of the above <c>Items</c>.</p>
3486
<p>Failure: <c>badarg</c> if <c>Pid</c> is not a local process,
3487
or if <c>Item</c> is not a valid <c>Item</c>.</p>
3491
<name>processes() -> [pid()]</name>
3492
<fsummary>All processes</fsummary>
3494
<p>Returns a list of process identifiers corresponding to
3495
all the processes currently existing on the local node.
3497
<p>Note that a process that is exiting, exists but is not alive, i.e.,
3498
<c>is_process_alive/1</c> will return <c>false</c> for a process
3499
that is exiting, but its process identifier will be part
3500
of the result returned from <c>processes/0</c>.
3503
> <input>processes().</input>
3504
[<0.0.0>,<0.2.0>,<0.4.0>,<0.5.0>,<0.7.0>,<0.8.0>]</pre>
3508
<name>purge_module(Module) -> void()</name>
3509
<fsummary>Remove old code for a module</fsummary>
3511
<v>Module = atom()</v>
3514
<p>Removes old code for <c>Module</c>. Before this BIF is used,
3515
<c>erlang:check_process_code/2</c> should be called to check
3516
that no processes are executing old code in the module.</p>
3518
<p>This BIF is intended for the code server (see
3519
<seealso marker="code">code(3)</seealso>) and should not be
3522
<p>Failure: <c>badarg</c> if there is no old code for
3527
<name>put(Key, Val) -> OldVal | undefined</name>
3528
<fsummary>Add a new value to the process dictionary</fsummary>
3530
<v>Key = Val = OldVal = term()</v>
3533
<p>Adds a new <c>Key</c> to the process dictionary, associated
3534
with the value <c>Val</c>, and returns <c>undefined</c>. If
3535
<c>Key</c> already exists, the old value is deleted and
3536
replaced by <c>Val</c> and the function returns the old value.</p>
3538
<p>The values stored when <c>put</c> is evaluated within
3539
the scope of a <c>catch</c> will not be retracted if a
3540
<c>throw</c> is evaluated, or if an error occurs.</p>
3543
> <input>X = put(name, walrus), Y = put(name, carpenter),</input>
3544
<input>Z = get(name),</input>
3545
<input>{X, Y, Z}.</input>
3546
{undefined,walrus,carpenter}</pre>
3550
<name>erlang:raise(Class, Reason, Stacktrace)</name>
3551
<fsummary>Stop execution with an exception of given class, reason and call stack backtrace</fsummary>
3553
<v>Class = error | exit | throw</v>
3554
<v>Reason = term()</v>
3555
<v>Stacktrace = [{Module, Function, Arity | Args} | {Fun, Args}]</v>
3556
<v> Module = Function = atom()</v>
3557
<v> Arity = int()</v>
3558
<v> Args = [term()]</v>
3559
<v> Fun = [fun()]</v>
3562
<p>Stops the execution of the calling process with an
3563
exception of given class, reason and call stack backtrace
3564
(<em>stacktrace</em>).</p>
3566
<p>This BIF is intended for debugging and for use in
3567
the Erlang operating system. In general, it should
3568
be avoided in applications, unless you know
3569
very well what you are doing.</p>
3571
<p><c>Class</c> is one of <c>error</c>, <c>exit</c> or
3572
<c>throw</c>, so if it were not for the stacktrace
3573
<c>erlang:raise(Class, Reason, Stacktrace)</c> is
3574
equivalent to <c>erlang:Class(Reason)</c>.
3575
<c>Reason</c> is any term and <c>Stacktrace</c> is a list as
3576
returned from <c>get_stacktrace()</c>, that is a list of
3577
3-tuples <c>{Module, Function, Arity | Args}</c> where
3578
<c>Module</c> and <c>Function</c> are atoms and the third
3579
element is an integer arity or an argument list. The
3580
stacktrace may also contain <c>{Fun, Args}</c> tuples where
3581
<c>Fun</c> is a local fun and <c>Args</c> is an argument list.</p>
3582
<p>The stacktrace is used as the exception stacktrace for the
3583
calling process; it will be truncated to the current
3584
maximum stacktrace depth.</p>
3585
<p>Because evaluating this function causes the process to
3586
terminate, it has no return value - unless the arguments are
3587
invalid, in which case the function <em>returns the error reason</em>, that is <c>badarg</c>. If you want to be
3588
really sure not to return you can call
3589
<c>erlang:error(erlang:raise(Class, Reason, Stacktrace))</c>
3590
and hope to distinguish exceptions later.</p>
3594
<name>erlang:read_timer(TimerRef) -> int() | false</name>
3595
<fsummary>Number of milliseconds remaining for a timer</fsummary>
3597
<v>TimerRef = ref()</v>
3600
<p><c>TimerRef</c> is a timer reference returned by
3601
<seealso marker="#erlang:send_after/3">erlang:send_after/3</seealso>
3603
<seealso marker="#erlang:start_timer/3">erlang:start_timer/3</seealso>.
3604
If the timer is active, the function returns the time in
3605
milliseconds left until the timer will expire, otherwise
3606
<c>false</c> (which means that <c>TimerRef</c> was never a
3607
timer, that it has been cancelled, or that it has already
3608
delivered its message).</p>
3610
<seealso marker="#erlang:send_after/3">erlang:send_after/3</seealso>,
3611
<seealso marker="#erlang:start_timer/3">erlang:start_timer/3</seealso>,
3613
<seealso marker="#erlang:cancel_timer/1">erlang:cancel_timer/1</seealso>.</p>
3617
<name>erlang:ref_to_list(Ref) -> string()</name>
3618
<fsummary>Text representation of a reference</fsummary>
3623
<p>Returns a string which corresponds to the text
3624
representation of <c>Ref</c>.</p>
3626
<p>This BIF is intended for debugging and for use in
3627
the Erlang operating system. It should not be used in
3628
application programs.</p>
3633
<name>register(RegName, Pid | Port) -> true</name>
3634
<fsummary>Register a name for a pid (or port)</fsummary>
3636
<v>RegName = atom()</v>
3638
<v>Port = port()</v>
3641
<p>Associates the name <c>RegName</c> with a pid or a port
3642
identifier. <c>RegName</c>, which must be an atom, can be used
3643
instead of the pid / port identifier in the send operator
3644
(<c>RegName ! Message</c>).</p>
3646
> <input>register(db, Pid).</input>
3648
<p>Failure: <c>badarg</c> if <c>Pid</c> is not an existing,
3649
local process or port, if <c>RegName</c> is already in use,
3650
if the process or port is already registered (already has a
3651
name), or if <c>RegName</c> is the atom <c>undefined</c>.</p>
3655
<name>registered() -> [RegName]</name>
3656
<fsummary>All registered names</fsummary>
3658
<v>RegName = atom()</v>
3661
<p>Returns a list of names which have been registered using
3662
<seealso marker="#register/2">register/2</seealso>.</p>
3664
> <input>registered().</input>
3665
[code_server, file_server, init, user, my_db]</pre>
3669
<name>erlang:resume_process(Suspendee) -> true</name>
3670
<fsummary>Resume a suspended process</fsummary>
3672
<v>Suspendee = pid()</v>
3675
<p>Decreases the suspend count on the process identified by
3676
<c>Suspendee</c>. <c>Suspendee</c> should previously have been
3678
<seealso marker="#erlang:suspend_process/2">erlang:suspend_process/2</seealso>,
3680
<seealso marker="#erlang:suspend_process/1">erlang:suspend_process/1</seealso>
3681
by the process calling <c>erlang:resume_process(Suspendee)</c>. When
3682
the suspend count on <c>Suspendee</c> reach zero, <c>Suspendee</c>
3683
will be resumed, i.e., the state of the <c>Suspendee</c> is changed
3684
from suspended into the state <c>Suspendee</c> was in before it was
3688
<p>This BIF is intended for debugging only.</p>
3692
<tag><c>badarg</c></tag>
3694
If <c>Suspendee</c> isn't a process identifier.
3696
<tag><c>badarg</c></tag>
3698
If the process calling <c>erlang:resume_process/1</c> had
3699
not previously increased the suspend count on the process
3700
identified by <c>Suspendee</c>.
3702
<tag><c>badarg</c></tag>
3704
If the process identified by <c>Suspendee</c> is not alive.
3710
<name>round(Number) -> int()</name>
3711
<fsummary>Return an integer by rounding a number</fsummary>
3713
<v>Number = number()</v>
3716
<p>Returns an integer by rounding <c>Number</c>.</p>
3718
> <input>round(5.5).</input>
3720
<p>Allowed in guard tests.</p>
3724
<name>self() -> pid()</name>
3725
<fsummary>Pid of the calling process</fsummary>
3727
<p>Returns the pid (process identifier) of the calling process.</p>
3729
> <input>self().</input>
3731
<p>Allowed in guard tests.</p>
3735
<name>erlang:send(Dest, Msg) -> Msg</name>
3736
<fsummary>Send a message</fsummary>
3738
<v>Dest = pid() | port() | RegName | {RegName, Node}</v>
3740
<v> RegName = atom()</v>
3741
<v> Node = node()</v>
3744
<p>Sends a message and returns <c>Msg</c>. This is the same as
3745
<c>Dest ! Msg</c>.</p>
3746
<p><c>Dest</c> may be a remote or local pid, a (local) port, a
3747
locally registered name, or a tuple <c>{RegName, Node}</c>
3748
for a registered name at another node.</p>
3752
<name>erlang:send(Dest, Msg, [Option]) -> Res</name>
3753
<fsummary>Send a message conditionally</fsummary>
3755
<v>Dest = pid() | port() | RegName | {RegName, Node}</v>
3756
<v> RegName = atom()</v>
3757
<v> Node = node()</v>
3759
<v>Option = nosuspend | noconnect</v>
3760
<v>Res = ok | nosuspend | noconnect</v>
3763
<p>Sends a message and returns <c>ok</c>, or does not send
3764
the message but returns something else (see below). Otherwise
3766
<seealso marker="#erlang:send/2">erlang:send/2</seealso>. See
3768
<seealso marker="#erlang:send_nosuspend/2">erlang:send_nosuspend/2,3</seealso>.
3769
for more detailed explanation and warnings.</p>
3770
<p>The possible options are:</p>
3772
<tag><c>nosuspend</c></tag>
3774
<p>If the sender would have to be suspended to do the send,
3775
<c>nosuspend</c> is returned instead.</p>
3777
<tag><c>noconnect</c></tag>
3779
<p>If the destination node would have to be auto-connected
3780
before doing the send, <c>noconnect</c> is returned
3785
<p>As with <c>erlang:send_nosuspend/2,3</c>: Use with extreme
3791
<name>erlang:send_after(Time, Dest, Msg) -> TimerRef</name>
3792
<fsummary>Start a timer</fsummary>
3795
<v> 0 <= Time <= 4294967295</v>
3796
<v>Dest = pid() | RegName </v>
3797
<v> LocalPid = pid() (of a process, alive or dead, on the local node)</v>
3799
<v>TimerRef = ref()</v>
3802
<p>Starts a timer which will send the message <c>Msg</c>
3803
to <c>Dest</c> after <c>Time</c> milliseconds.</p>
3804
<p>If <c>Dest</c> is an atom, it is supposed to be the name of
3805
a registered process. The process referred to by the name is
3806
looked up at the time of delivery. No error is given if
3807
the name does not refer to a process.</p>
3808
<p>If <c>Dest</c> is a pid, the timer will be automatically
3809
canceled if the process referred to by the pid is not alive,
3810
or when the process exits. This feature was introduced in
3811
erts version 5.4.11. Note that timers will not be
3812
automatically canceled when <c>Dest</c> is an atom.</p>
3814
<seealso marker="#erlang:start_timer/3">erlang:start_timer/3</seealso>,
3815
<seealso marker="#erlang:cancel_timer/1">erlang:cancel_timer/1</seealso>,
3817
<seealso marker="#erlang:read_timer/1">erlang:read_timer/1</seealso>.</p>
3818
<p>Failure: <c>badarg</c> if the arguments does not satisfy
3819
the requirements specified above.</p>
3823
<name>erlang:send_nosuspend(Dest, Msg) -> bool()</name>
3824
<fsummary>Try to send a message without ever blocking</fsummary>
3826
<v>Dest = pid() | port() | RegName | {RegName, Node}</v>
3827
<v> RegName = atom()</v>
3828
<v> Node = node()</v>
3833
<seealso marker="#erlang:send/3">erlang:send(Dest, Msg, [nosuspend])</seealso>, but returns <c>true</c> if
3834
the message was sent and <c>false</c> if the message was not
3835
sent because the sender would have had to be suspended.</p>
3836
<p>This function is intended for send operations towards an
3837
unreliable remote node without ever blocking the sending
3838
(Erlang) process. If the connection to the remote node
3839
(usually not a real Erlang node, but a node written in C or
3840
Java) is overloaded, this function <em>will not send the message</em> but return <c>false</c> instead.</p>
3841
<p>The same happens, if <c>Dest</c> refers to a local port that
3842
is busy. For all other destinations (allowed for the ordinary
3843
send operator <c>'!'</c>) this function sends the message and
3844
returns <c>true</c>.</p>
3845
<p>This function is only to be used in very rare circumstances
3846
where a process communicates with Erlang nodes that can
3847
disappear without any trace causing the TCP buffers and
3848
the drivers queue to be over-full before the node will actually
3849
be shut down (due to tick timeouts) by <c>net_kernel</c>. The
3850
normal reaction to take when this happens is some kind of
3851
premature shutdown of the other node.</p>
3852
<p>Note that ignoring the return value from this function would
3853
result in <em>unreliable</em> message passing, which is
3854
contradictory to the Erlang programming model. The message is
3855
<em>not</em> sent if this function returns <c>false</c>.</p>
3856
<p>Note also that in many systems, transient states of
3857
overloaded queues are normal. The fact that this function
3858
returns <c>false</c> does not in any way mean that the other
3859
node is guaranteed to be non-responsive, it could be a
3860
temporary overload. Also a return value of <c>true</c> does
3861
only mean that the message could be sent on the (TCP) channel
3862
without blocking, the message is not guaranteed to have
3863
arrived at the remote node. Also in the case of a disconnected
3864
non-responsive node, the return value is <c>true</c> (mimics
3865
the behaviour of the <c>!</c> operator). The expected
3866
behaviour as well as the actions to take when the function
3867
returns <c>false</c> are application and hardware specific.</p>
3869
<p>Use with extreme care!</p>
3874
<name>erlang:send_nosuspend(Dest, Msg, Options) -> bool()</name>
3875
<fsummary>Try to send a message without ever blocking</fsummary>
3877
<v>Dest = pid() | port() | RegName | {RegName, Node}</v>
3878
<v> RegName = atom()</v>
3879
<v> Node = node()</v>
3881
<v>Option = noconnect</v>
3885
<seealso marker="#erlang:send/3">erlang:send(Dest, Msg, [nosuspend | Options])</seealso>,
3886
but with boolean return value.</p>
3887
<p>This function behaves like
3888
<seealso marker="#erlang:send_nosuspend/2">erlang:send_nosuspend/2)</seealso>,
3889
but takes a third parameter, a list of options. The only
3890
currently implemented option is <c>noconnect</c>. The option
3891
<c>noconnect</c> makes the function return <c>false</c> if
3892
the remote node is not currently reachable by the local
3893
node. The normal behaviour is to try to connect to the node,
3894
which may stall the process for a shorter period. The use of
3895
the <c>noconnect</c> option makes it possible to be
3896
absolutely sure not to get even the slightest delay when
3897
sending to a remote process. This is especially useful when
3898
communicating with nodes who expect to always be
3899
the connecting part (i.e. nodes written in C or Java).</p>
3900
<p>Whenever the function returns <c>false</c> (either when a
3901
suspend would occur or when <c>noconnect</c> was specified and
3902
the node was not already connected), the message is guaranteed
3903
<em>not</em> to have been sent.</p>
3905
<p>Use with extreme care!</p>
3910
<name>erlang:set_cookie(Node, Cookie) -> true</name>
3911
<fsummary>Set the magic cookie of a node</fsummary>
3913
<v>Node = node()</v>
3914
<v>Cookie = atom()</v>
3917
<p>Sets the magic cookie of <c>Node</c> to the atom
3918
<c>Cookie</c>. If <c>Node</c> is the local node, the function
3919
also sets the cookie of all other unknown nodes to
3921
<seealso marker="doc/reference_manual:distributed">Distributed Erlang</seealso> in the Erlang Reference Manual).</p>
3922
<p>Failure: <c>function_clause</c> if the local node is not
3927
<name>setelement(Index, Tuple1, Value) -> Tuple2</name>
3928
<fsummary>Set Nth element of a tuple</fsummary>
3930
<v>Index = 1..tuple_size(Tuple1)</v>
3931
<v>Tuple1 = Tuple2 = tuple()</v>
3932
<v>Value = term()</v>
3935
<p>Returns a tuple which is a copy of the argument <c>Tuple1</c>
3936
with the element given by the integer argument <c>Index</c>
3937
(the first element is the element with index 1) replaced by
3938
the argument <c>Value</c>.</p>
3940
> <input>setelement(2, {10, green, bottles}, red).</input>
3941
{10,red,bottles}</pre>
3945
<name>size(Item) -> int()</name>
3946
<fsummary>Size of a tuple or binary</fsummary>
3948
<v>Item = tuple() | binary()</v>
3951
<p>Returns an integer which is the size of the argument
3952
<c>Item</c>, which must be either a tuple or a binary.</p>
3954
> <input>size({morni, mulle, bwange}).</input>
3956
<p>Allowed in guard tests.</p>
3960
<name>spawn(Fun) -> pid()</name>
3961
<fsummary>Create a new process with a fun as entry point</fsummary>
3966
<p>Returns the pid of a new process started by the application
3967
of <c>Fun</c> to the empty list <c>[]</c>. Otherwise works
3968
like <seealso marker="#spawn/3">spawn/3</seealso>.</p>
3972
<name>spawn(Node, Fun) -> pid()</name>
3973
<fsummary>Create a new process with a fun as entry point on a given node</fsummary>
3975
<v>Node = node()</v>
3979
<p>Returns the pid of a new process started by the application
3980
of <c>Fun</c> to the empty list <c>[]</c> on <c>Node</c>. If
3981
<c>Node</c> does not exist, a useless pid is returned.
3982
Otherwise works like
3983
<seealso marker="#spawn/3">spawn/3</seealso>.</p>
3987
<name>spawn(Module, Function, Args) -> pid()</name>
3988
<fsummary>Create a new process with a function as entry point</fsummary>
3990
<v>Module = Function = atom()</v>
3991
<v>Args = [term()]</v>
3994
<p>Returns the pid of a new process started by the application
3995
of <c>Module:Function</c> to <c>Args</c>. The new process
3996
created will be placed in the system scheduler queue and be
3997
run some time later.</p>
3998
<p><c>error_handler:undefined_function(Module, Function, Args)</c> is evaluated by the new process if
3999
<c>Module:Function/Arity</c> does not exist (where
4000
<c>Arity</c> is the length of <c>Args</c>). The error handler
4001
can be redefined (see
4002
<seealso marker="#process_flag/2">process_flag/2</seealso>).
4003
If <c>error_handler</c> is undefined, or the user has
4004
redefined the default <c>error_handler</c> its replacement is
4005
undefined, a failure with the reason <c>undef</c> will occur.</p>
4007
> <input>spawn(speed, regulator, [high_speed, thin_cut]).</input>
4012
<name>spawn(Node, Module, Function, ArgumentList) -> pid()</name>
4013
<fsummary>Create a new process with a function as entry point on a given node</fsummary>
4015
<v>Node = node()</v>
4016
<v>Module = Function = atom()</v>
4017
<v>Args = [term()]</v>
4020
<p>Returns the pid of a new process started by the application
4021
of <c>Module:Function</c> to <c>Args</c> on <c>Node</c>. If
4022
<c>Node</c> does not exists, a useless pid is returned.
4023
Otherwise works like
4024
<seealso marker="#spawn/3">spawn/3</seealso>.</p>
4028
<name>spawn_link(Fun) -> pid()</name>
4029
<fsummary>Create and link to a new process with a fun as entry point</fsummary>
4034
<p>Returns the pid of a new process started by the application
4035
of <c>Fun</c> to the empty list []. A link is created between
4036
the calling process and and the new process, atomically.
4037
Otherwise works like
4038
<seealso marker="#spawn/3">spawn/3</seealso>.</p>
4042
<name>spawn_link(Node, Fun) -></name>
4043
<fsummary>Create and link to a new process with a fun as entry point on a specified node</fsummary>
4045
<v>Node = node()</v>
4049
<p>Returns the pid of a new process started by the application
4050
of <c>Fun</c> to the empty list [] on <c>Node</c>. A link is
4051
created between the calling process and and the new process,
4052
atomically. If <c>Node</c> does not exist, a useless pid is
4053
returned (and due to the link, an exit signal with exit
4054
reason <c>noconnection</c> will be received). Otherwise works
4055
like <seealso marker="#spawn/3">spawn/3</seealso>.</p>
4059
<name>spawn_link(Module, Function, Args) -> pid()</name>
4060
<fsummary>Create and link to a new process with a function as entry point</fsummary>
4062
<v>Module = Function = atom()</v>
4063
<v>Args = [term()]</v>
4066
<p>Returns the pid of a new process started by the application
4067
of <c>Module:Function</c> to <c>Args</c>. A link is created
4068
between the calling process and the new process, atomically.
4069
Otherwise works like
4070
<seealso marker="#spawn/3">spawn/3</seealso>.</p>
4074
<name>spawn_link(Node, Module, Function, Args) -> pid()</name>
4075
<fsummary>Create and link to a new process with a function as entry point on a given node</fsummary>
4077
<v>Node = node()</v>
4078
<v>Module = Function = atom()</v>
4079
<v>Args = [term()]</v>
4082
<p>Returns the pid of a new process started by the application
4083
of <c>Module:Function</c> to <c>Args</c> on <c>Node</c>. A
4084
link is created between the calling process and the new
4085
process, atomically. If <c>Node</c> does not exist, a useless
4086
pid is returned (and due to the link, an exit signal with exit
4087
reason <c>noconnection</c> will be received). Otherwise works
4088
like <seealso marker="#spawn/3">spawn/3</seealso>.</p>
4092
<name>spawn_monitor(Fun) -> {pid(),reference()}</name>
4093
<fsummary>Create and monitor a new process with a fun as entry point</fsummary>
4098
<p>Returns the pid of a new process started by the application
4099
of <c>Fun</c> to the empty list [] and reference for a monitor
4100
created to the new process.
4101
Otherwise works like
4102
<seealso marker="#spawn/3">spawn/3</seealso>.</p>
4106
<name>spawn_monitor(Module, Function, Args) -> {pid(),reference()}</name>
4107
<fsummary>Create and monitor a new process with a function as entry point</fsummary>
4109
<v>Module = Function = atom()</v>
4110
<v>Args = [term()]</v>
4113
<p>A new process is started by the application
4114
of <c>Module:Function</c> to <c>Args</c>, and the process is
4115
monitored at the same time. Returns the pid and a reference
4117
Otherwise works like
4118
<seealso marker="#spawn/3">spawn/3</seealso>.</p>
4122
<name>spawn_opt(Fun, [Option]) -> pid() | {pid(),reference()}</name>
4123
<fsummary>Create a new process with a fun as entry point</fsummary>
4126
<v>Option = link | monitor | {priority, Level} | {fullsweep_after, Number} | {min_heap_size, Size}</v>
4127
<v> Level = low | normal | high</v>
4128
<v> Number = int()</v>
4129
<v> Size = int()</v>
4132
<p>Returns the pid of a new process started by the application
4133
of <c>Fun</c> to the empty list <c>[]</c>. Otherwise
4135
<seealso marker="#spawn_opt/4">spawn_opt/4</seealso>.</p>
4136
<p>If the option <c>monitor</c> is given, the newly created
4137
process will be monitored and both the pid and reference for
4138
the monitor will be returned.</p>
4142
<name>spawn_opt(Node, Fun, [Option]) -> pid()</name>
4143
<fsummary>Create a new process with a fun as entry point on a given node</fsummary>
4145
<v>Node = node()</v>
4147
<v>Option = link | {priority, Level} | {fullsweep_after, Number} | {min_heap_size, Size}</v>
4148
<v> Level = low | normal | high</v>
4149
<v> Number = int()</v>
4150
<v> Size = int()</v>
4153
<p>Returns the pid of a new process started by the application
4154
of <c>Fun</c> to the empty list <c>[]</c> on <c>Node</c>. If
4155
<c>Node</c> does not exist, a useless pid is returned.
4156
Otherwise works like
4157
<seealso marker="#spawn_opt/4">spawn_opt/4</seealso>.</p>
4161
<name>spawn_opt(Module, Function, Args, [Option]) -> pid() | {pid(),reference()}</name>
4162
<fsummary>Create a new process with a function as entry point</fsummary>
4164
<v>Module = Function = atom()</v>
4165
<v>Args = [term()]</v>
4166
<v>Option = link | monitor | {priority, Level} | {fullsweep_after, Number} | {min_heap_size, Size}</v>
4167
<v> Level = low | normal | high</v>
4168
<v> Number = int()</v>
4169
<v> Size = int()</v>
4172
<p>Works exactly like
4173
<seealso marker="#spawn/3">spawn/3</seealso>, except that an
4174
extra option list is given when creating the process.</p>
4175
<p>If the option <c>monitor</c> is given, the newly created
4176
process will be monitored and both the pid and reference for
4177
the monitor will be returned.</p>
4179
<tag><c>link</c></tag>
4181
<p>Sets a link to the parent process (like
4182
<c>spawn_link/3</c> does).</p>
4184
<tag><c>monitor</c></tag>
4186
<p>Monitor the new process (just like
4187
<seealso marker="#erlang:monitor/2">erlang:monitor/2</seealso> does).</p>
4189
<tag><c>{priority, Level}</c></tag>
4191
<p>Sets the priority of the new process. Equivalent to
4193
<seealso marker="#process_flag_priority">process_flag(priority, Level)</seealso> in the start function of the new process,
4194
except that the priority will be set before the process is
4195
selected for execution for the first time. For more information
4197
<seealso marker="#process_flag_priority">process_flag(priority, Level)</seealso>.</p>
4199
<tag><c>{fullsweep_after, Number}</c></tag>
4201
<p>This option is only useful for performance tuning.
4202
In general, you should not use this option unless you
4203
know that there is problem with execution times and/or
4204
memory consumption, and you should measure to make sure
4205
that the option improved matters.
4207
<p>The Erlang runtime system uses a generational garbage
4208
collection scheme, using an "old heap" for data that has
4209
survived at least one garbage collection. When there is
4210
no more room on the old heap, a fullsweep garbage
4211
collection will be done.</p>
4212
<p>The <c>fullsweep_after</c> option makes it possible to
4213
specify the maximum number of generational collections
4214
before forcing a fullsweep even if there is still room on
4215
the old heap. Setting the number to zero effectively
4216
disables the general collection algorithm, meaning that
4217
all live data is copied at every garbage collection.</p>
4218
<p>Here are a few cases when it could be useful to change
4219
<c>fullsweep_after</c>. Firstly, if binaries that are no
4220
longer used should be thrown away as soon as possible.
4221
(Set <c>Number</c> to zero.) Secondly, a process that
4222
mostly have short-lived data will be fullsweeped seldom
4223
or never, meaning that the old heap will contain mostly
4224
garbage. To ensure a fullsweep once in a while, set
4225
<c>Number</c> to a suitable value such as 10 or 20.
4226
Thirdly, in embedded systems with limited amount of RAM
4227
and no virtual memory, one might want to preserve memory
4228
by setting <c>Number</c> to zero. (The value may be set
4230
<seealso marker="#erlang:system_flag/2">erlang:system_flag/2</seealso>.)</p>
4232
<tag><c>{min_heap_size, Size}</c></tag>
4234
<p>This option is only useful for performance tuning.
4235
In general, you should not use this option unless you
4236
know that there is problem with execution times and/or
4237
memory consumption, and you should measure to make sure
4238
that the option improved matters.
4240
<p>Gives a minimum heap size in words. Setting this value
4241
higher than the system default might speed up some
4242
processes because less garbage collection is done.
4243
Setting too high value, however, might waste memory and
4244
slow down the system due to worse data locality.
4245
Therefore, it is recommended to use this option only for
4246
fine-tuning an application and to measure the execution
4247
time with various <c>Size</c> values.</p>
4253
<name>spawn_opt(Node, Module, Function, Args, [Option]) -> pid()</name>
4254
<fsummary>Create a new process with a function as entry point on a given node</fsummary>
4256
<v>Node = node()</v>
4257
<v>Module = Function = atom()</v>
4258
<v>Args = [term()]</v>
4259
<v>Option = link | {priority, Level} | {fullsweep_after, Number} | {min_heap_size, Size}</v>
4260
<v> Level = low | normal | high</v>
4261
<v> Number = int()</v>
4262
<v> Size = int()</v>
4265
<p>Returns the pid of a new process started by the application
4266
of <c>Module:Function</c> to <c>Args</c> on <c>Node</c>. If
4267
<c>Node</c> does not exist, a useless pid is returned.
4268
Otherwise works like
4269
<seealso marker="#spawn_opt/4">spawn_opt/4</seealso>.</p>
4273
<name>split_binary(Bin, Pos) -> {Bin1, Bin2}</name>
4274
<fsummary>Split a binary into two</fsummary>
4276
<v>Bin = Bin1 = Bin2 = binary()</v>
4277
<v>Pos = 1..byte_size(Bin)</v>
4280
<p>Returns a tuple containing the binaries which are the result
4281
of splitting <c>Bin</c> into two parts at position <c>Pos</c>.
4282
This is not a destructive operation. After the operation,
4283
there will be three binaries altogether.</p>
4285
> <input>B = list_to_binary("0123456789").</input>
4286
<<"0123456789">>
4287
> <input>byte_size(B).</input>
4289
> <input>{B1, B2} = split_binary(B,3).</input>
4290
{<<"012">>,<<"3456789">>}
4291
> <input>byte_size(B1).</input>
4293
> <input>byte_size(B2).</input>
4298
<name>erlang:start_timer(Time, Dest, Msg) -> TimerRef</name>
4299
<fsummary>Start a timer</fsummary>
4302
<v> 0 <= Time <= 4294967295</v>
4303
<v>Dest = LocalPid | RegName </v>
4304
<v> LocalPid = pid() (of a process, alive or dead, on the local node)</v>
4305
<v> RegName = atom()</v>
4307
<v>TimerRef = ref()</v>
4310
<p>Starts a timer which will send the message
4311
<c>{timeout, TimerRef, Msg}</c> to <c>Dest</c>
4312
after <c>Time</c> milliseconds.</p>
4313
<p>If <c>Dest</c> is an atom, it is supposed to be the name of
4314
a registered process. The process referred to by the name is
4315
looked up at the time of delivery. No error is given if
4316
the name does not refer to a process.</p>
4317
<p>If <c>Dest</c> is a pid, the timer will be automatically
4318
canceled if the process referred to by the pid is not alive,
4319
or when the process exits. This feature was introduced in
4320
erts version 5.4.11. Note that timers will not be
4321
automatically canceled when <c>Dest</c> is an atom.</p>
4323
<seealso marker="#erlang:send_after/3">erlang:send_after/3</seealso>,
4324
<seealso marker="#erlang:cancel_timer/1">erlang:cancel_timer/1</seealso>,
4326
<seealso marker="#erlang:read_timer/1">erlang:read_timer/1</seealso>.</p>
4327
<p>Failure: <c>badarg</c> if the arguments does not satisfy
4328
the requirements specified above.</p>
4332
<name>statistics(Type) -> Res</name>
4333
<fsummary>Information about the system</fsummary>
4335
<v>Type, Res -- see below</v>
4338
<p>Returns information about the system as specified by
4341
<tag><c>context_switches</c></tag>
4343
<p>Returns <c>{ContextSwitches, 0}</c>, where
4344
<c>ContextSwitches</c> is the total number of context
4345
switches since the system started.</p>
4347
<tag><c>exact_reductions</c></tag>
4349
<marker id="statistics_exact_reductions"></marker>
4351
<c>{Total_Exact_Reductions, Exact_Reductions_Since_Last_Call}</c>.</p>
4352
<p><em>NOTE:</em><c>statistics(exact_reductions)</c> is
4353
a more expensive operation than
4354
<seealso marker="#statistics_reductions">statistics(reductions)</seealso>
4355
especially on an Erlang machine with SMP support.</p>
4357
<tag><c>garbage_collection</c></tag>
4359
<p>Returns <c>{Number_of_GCs, Words_Reclaimed, 0}</c>. This
4360
information may not be valid for all implementations.</p>
4362
<tag><c>io</c></tag>
4364
<p>Returns <c>{{input, Input}, {output, Output}}</c>,
4365
where <c>Input</c> is the total number of bytes received
4366
through ports, and <c>Output</c> is the total number of
4367
bytes output to ports.</p>
4369
<tag><c>reductions</c></tag>
4371
<marker id="statistics_reductions"></marker>
4373
<c>{Total_Reductions, Reductions_Since_Last_Call}</c>.</p>
4374
<p><em>NOTE:</em> From erts version 5.5 (OTP release R11B)
4375
this value does not include reductions performed in current
4376
time slices of currently scheduled processes. If an
4377
exact value is wanted, use
4378
<seealso marker="#statistics_exact_reductions">statistics(exact_reductions)</seealso>.</p>
4380
<tag><c>run_queue</c></tag>
4382
<p>Returns the length of the run queue, that is, the number
4383
of processes that are ready to run.</p>
4385
<tag><c>runtime</c></tag>
4387
<p>Returns <c>{Total_Run_Time, Time_Since_Last_Call}</c>.</p>
4389
<tag><c>wall_clock</c></tag>
4392
<c>{Total_Wallclock_Time, Wallclock_Time_Since_Last_Call}</c>.
4393
<c>wall_clock</c> can be used in the same manner as
4394
<c>runtime</c>, except that real time is measured as
4395
opposed to runtime or CPU time.</p>
4398
<p>All times are in milliseconds.</p>
4400
> <input>statistics(runtime).</input>
4402
> <input>statistics(reductions).</input>
4404
> <input>statistics(garbage_collection).</input>
4409
<name>erlang:suspend_process(Suspendee, OptList) -> true | false</name>
4410
<fsummary>Suspend a process</fsummary>
4412
<v>Suspendee = pid()</v>
4413
<v>OptList = [Opt]</v>
4417
<p>Increases the suspend count on the process identified by
4418
<c>Suspendee</c> and puts it in the suspended state if it isn't
4419
already in the suspended state. A suspended process will not be
4420
scheduled for execution until the process has been resumed.
4423
<p>A process can be suspended by multiple processes and can
4424
be suspended multiple times by a single process. A suspended
4425
process will not leave the suspended state until its suspend
4426
count reach zero. The suspend count of <c>Suspendee</c> is
4428
<seealso marker="#erlang:resume_process/1">erlang:resume_process(Suspendee)</seealso>
4429
is called by the same process that called
4430
<c>erlang:suspend_process(Suspendee)</c>. All increased suspend
4431
counts on other processes acquired by a process will automatically be
4432
decreased when the process terminates.</p>
4434
<p>Currently the following options (<c>Opt</c>s) are available:</p>
4436
<tag><c>asynchronous</c></tag>
4438
A suspend request is sent to the process identified by
4439
<c>Suspendee</c>. <c>Suspendee</c> will eventually suspend
4440
unless it is resumed before it was able to suspend. The caller
4441
of <c>erlang:suspend_process/2</c> will return immediately,
4442
regardless of whether the <c>Suspendee</c> has suspended yet
4443
or not. Note that the point in time when the <c>Suspendee</c>
4444
will actually suspend cannot be deduced from other events
4445
in the system. The only guarantee given is that the
4446
<c>Suspendee</c> will <em>eventually</em> suspend (unless it
4447
is resumed). If the <c>asynchronous</c> option has <em>not</em>
4448
been passed, the caller of <c>erlang:suspend_process/2</c> will
4449
be blocked until the <c>Suspendee</c> has actually suspended.
4451
<tag><c>unless_suspending</c></tag>
4453
The process identified by <c>Suspendee</c> will be suspended
4454
unless the calling process already is suspending the
4455
<c>Suspendee</c>. If <c>unless_suspending</c> is combined
4456
with the <c>asynchronous</c> option, a suspend request will be
4457
sent unless the calling process already is suspending the
4458
<c>Suspendee</c> or if a suspend request already has been sent
4459
and is in transit. If the calling process already is suspending
4460
the <c>Suspendee</c>, or if combined with the <c>asynchronous</c>
4461
option and a send request already is in transit,
4462
<c>false</c> is returned and the suspend count on <c>Suspendee</c>
4463
will remain unchanged.
4467
<p>If the suspend count on the process identified by
4468
<c>Suspendee</c> was increased, <c>true</c> is returned; otherwise,
4469
<c>false</c> is returned.</p>
4472
<p>This BIF is intended for debugging only.</p>
4476
<tag><c>badarg</c></tag>
4478
If <c>Suspendee</c> isn't a process identifier.
4480
<tag><c>badarg</c></tag>
4482
If the process identified by <c>Suspendee</c> is same the process as
4483
the process calling <c>erlang:suspend_process/2</c>.
4485
<tag><c>badarg</c></tag>
4487
If the process identified by <c>Suspendee</c> is not alive.
4489
<tag><c>badarg</c></tag>
4491
If the process identified by <c>Suspendee</c> resides on another node.
4493
<tag><c>badarg</c></tag>
4495
If <c>OptList</c> isn't a proper list of valid <c>Opt</c>s.
4497
<tag><c>system_limit</c></tag>
4499
If the process identified by <c>Suspendee</c> has been suspended more
4500
times by the calling process than can be represented by the
4501
currently used internal data structures. The current system limit
4502
is larger than 2 000 000 000 suspends, and it will never be less
4509
<name>erlang:suspend_process(Suspendee) -> true</name>
4510
<fsummary>Suspend a process</fsummary>
4512
<v>Suspendee = pid()</v>
4515
<p>Suspends the process identified by <c>Suspendee</c>. The
4517
<seealso marker="#erlang:suspend_process/2">erlang:suspend_process(Suspendee, [])</seealso>. For more information see the documentation of <seealso marker="#erlang:suspend_process/2">erlang:suspend_process/2</seealso>.
4520
<p>This BIF is intended for debugging only.</p>
4525
<name>erlang:system_flag(Flag, Value) -> OldValue</name>
4526
<fsummary>Set system flags</fsummary>
4528
<v>Flag, Value, OldValue -- see below</v>
4531
<p>Sets various system properties of the Erlang node. Returns
4532
the old value of the flag.</p>
4534
<tag><c>erlang:system_flag(backtrace_depth, Depth)</c></tag>
4536
<p>Sets the maximum depth of call stack back-traces in the
4537
exit reason element of <c>'EXIT'</c> tuples.</p>
4539
<tag><c>erlang:system_flag(fullsweep_after, Number)</c></tag>
4541
<p><c>Number</c> is a non-negative integer which indicates
4542
how many times generational garbages collections can be
4543
done without forcing a fullsweep collection. The value
4544
applies to new processes; processes already running are
4546
<p>In low-memory systems (especially without virtual
4547
memory), setting the value to 0 can help to conserve
4549
<p>An alternative way to set this value is through the
4550
(operating system) environment variable
4551
<c>ERL_FULLSWEEP_AFTER</c>.</p>
4553
<tag><c>erlang:system_flag(min_heap_size, MinHeapSize)</c></tag>
4555
<p>Sets the default minimum heap size for processes. The
4556
size is given in words. The new <c>min_heap_size</c> only
4557
effects processes spawned after the change of
4558
<c>min_heap_size</c> has been made.
4559
The <c>min_heap_size</c> can be set for individual
4561
<seealso marker="#spawn_opt/4">spawn_opt/N</seealso> or
4562
<seealso marker="#process_flag/2">process_flag/2</seealso>. </p>
4564
<tag><c>erlang:system_flag(multi_scheduling, BlockState)</c></tag>
4566
<marker id="system_flag_multi_scheduling"></marker>
4567
<p><c>BlockState = block | unblock</c></p>
4568
<p>If multi-scheduling is enabled, more than one scheduler
4569
thread is used by the emulator. Multi-scheduling can be
4570
blocked. When multi-scheduling has been blocked, only
4571
one scheduler thread will schedule Erlang processes.</p>
4572
<p>If <c>BlockState =:= block</c>, multi-scheduling will
4573
be blocked. If <c>BlockState =:= unblock</c> and no-one
4574
else is blocking multi-scheduling and this process has
4575
only blocked one time, multi-scheduling will be unblocked.
4576
One process can block multi-scheduling multiple times.
4577
If a process has blocked multiple times, it has to
4578
unblock exactly as many times as it has blocked before it
4579
has released its multi-scheduling block. If a process that
4580
has blocked multi-scheduling exits, it will release its
4581
blocking of multi-scheduling.</p>
4582
<p>The return values are <c>disabled</c>, <c>blocked</c>,
4583
or <c>enabled</c>. The returned value describes the
4584
state just after the call to
4585
<c>erlang:system_flag(multi_scheduling, BlockState)</c>
4586
has been made. The return values are described in the
4587
documentation of <seealso marker="#system_info_multi_scheduling">erlang:system_info(multi_scheduling)</seealso>.</p>
4588
<p><em>NOTE</em>: Blocking of multi-scheduling should normally
4589
not be needed. If you feel that you need to
4590
block multi-scheduling, think through the
4591
problem at least a couple of times again.
4592
Blocking multi-scheduling should only be used
4593
as a last resort since it will most likely be
4594
a <em>very inefficient</em> way to solve the
4596
<p>See also <seealso marker="#system_info_multi_scheduling">erlang:system_info(multi_scheduling)</seealso>,
4597
<seealso marker="#system_info_multi_scheduling_blockers">erlang:system_info(multi_scheduling_blockers)</seealso>, and
4598
<seealso marker="#system_info_schedulers">erlang:system_info(schedulers)</seealso>.</p>
4600
<tag><c>erlang:system_flag(trace_control_word, TCW)</c></tag>
4602
<p>Sets the value of the node's trace control word to
4603
<c>TCW</c>. <c>TCW</c> should be an unsigned integer. For
4604
more information see documentation of the
4605
<seealso marker="erts:match_spec#set_tcw">set_tcw</seealso>
4606
function in the match specification documentation in the
4607
ERTS User's Guide.</p>
4611
<p>The <c>schedulers</c> option has been removed as
4612
of erts version 5.5.3. The number of scheduler
4613
threads is determined at emulator boot time, and
4614
cannot be changed after that.</p>
4619
<name>erlang:system_info(Type) -> Res</name>
4620
<fsummary>Information about the system</fsummary>
4622
<v>Type, Res -- see below</v>
4625
<p>Returns various information about the current system
4626
(emulator) as specified by <c>Type</c>:</p>
4628
<tag><c>allocated_areas</c></tag>
4630
<marker id="system_info_allocated_areas"></marker>
4631
<p>Returns a list of tuples with information about
4632
miscellaneous allocated memory areas.</p>
4633
<p>Each tuple contains an atom describing type of memory as
4634
first element and amount of allocated memory in bytes as
4635
second element. In those cases when there is information
4636
present about allocated and used memory, a third element
4637
is present. This third element contains the amount of
4638
used memory in bytes.</p>
4639
<p><c>erlang:system_info(allocated_areas)</c> is intended
4640
for debugging, and the content is highly implementation
4641
dependent. The content of the results will therefore
4642
change when needed without prior notice.</p>
4643
<p><em>Note:</em> The sum of these values is <em>not</em>
4644
the total amount of memory allocated by the emulator.
4645
Some values are part of other values, and some memory
4646
areas are not part of the result. If you are interested
4647
in the total amount of memory allocated by the emulator
4648
see <seealso marker="#erlang:memory/0">erlang:memory/0,1</seealso>.</p>
4650
<tag><c>allocator</c></tag>
4652
<marker id="system_info_allocator"></marker>
4653
<p>Returns <c>{Allocator, Version, Features, Settings}.</c></p>
4655
<list type="bulleted">
4656
<item><c>Allocator = undefined | elib_malloc | glibc</c></item>
4657
<item><c>Version = [int()]</c></item>
4658
<item><c>Features = [atom()]</c></item>
4659
<item><c>Settings = [{Subsystem, [{Parameter, Value}]}]</c></item>
4660
<item><c>Subsystem = atom()</c></item>
4661
<item><c>Parameter = atom()</c></item>
4662
<item><c>Value = term()</c></item>
4665
<list type="bulleted">
4667
<p><c>Allocator</c> corresponds to the <c>malloc()</c>
4668
implementation used. If <c>Allocator</c> equals
4669
<c>undefined</c>, the <c>malloc()</c> implementation
4670
used could not be identified. Currently
4671
<c>elib_malloc</c> and <c>glibc</c> can be identified.</p>
4674
<p><c>Version</c> is a list of integers (but not a
4675
string) representing the version of
4676
the <c>malloc()</c> implementation used.</p>
4679
<p><c>Features</c> is a list of atoms representing
4680
allocation features used.</p>
4683
<p><c>Settings</c> is a list of subsystems, their
4684
configurable parameters, and used values. Settings
4685
may differ between different combinations of
4686
platforms, allocators, and allocation features.
4687
Memory sizes are given in bytes.</p>
4690
<p>See also "System Flags Effecting erts_alloc" in
4691
<seealso marker="erts:erts_alloc#flags">erts_alloc(3)</seealso>.</p>
4693
<tag><c>alloc_util_allocators</c></tag>
4695
<marker id="system_info_alloc_util_allocators"></marker>
4696
<p>Returns a list of the names of all allocators
4697
using the ERTS internal <c>alloc_util</c> framework
4698
as atoms. For more information see the
4699
<seealso marker="erts:erts_alloc#alloc_util">"the
4700
alloc_util framework" section in the
4701
erts_alloc(3)</seealso> documentation.
4704
<tag><c>{allocator, Alloc}</c></tag>
4706
<marker id="system_info_allocator_tuple"></marker>
4707
<p>Returns information about the specified allocator.
4708
As of erts version 5.6.1 the return value is a list
4709
of <c>{instance, InstanceNo, InstanceInfo}</c> tuples
4710
where <c>InstanceInfo</c> contains information about
4711
a specific instance of the allocator.
4712
If <c>Alloc</c> is not a recognized allocator,
4713
<c>undefined</c> is returned. If <c>Alloc</c> is disabled,
4714
<c>false</c> is returned.</p>
4715
<p><em>Note:</em> The information returned is highly
4716
implementation dependent and may be changed, or removed
4717
at any time without prior notice. It was initially
4718
intended as a tool when developing new allocators, but
4719
since it might be of interest for others it has been
4720
briefly documented.</p>
4721
<p>The recognized allocators are listed in
4722
<seealso marker="erts:erts_alloc">erts_alloc(3)</seealso>.
4723
After reading the <c>erts_alloc(3)</c> documentation,
4724
the returned information
4725
should more or less speak for itself. But it can be worth
4726
explaining some things. Call counts are presented by two
4727
values. The first value is giga calls, and the second
4728
value is calls. <c>mbcs</c>, and <c>sbcs</c> are
4729
abbreviations for, respectively, multi-block carriers, and
4730
single-block carriers. Sizes are presented in bytes. When
4731
it is not a size that is presented, it is the amount of
4732
something. Sizes and amounts are often presented by three
4733
values, the first is current value, the second is maximum
4734
value since the last call to
4735
<c>erlang:system_info({allocator, Alloc})</c>, and
4736
the third is maximum value since the emulator was started.
4737
If only one value is present, it is the current value.
4738
<c>fix_alloc</c> memory block types are presented by two
4739
values. The first value is memory pool size and
4740
the second value used memory size.</p>
4742
<tag><c>{allocator_sizes, Alloc}</c></tag>
4744
<marker id="system_info_allocator_sizes"></marker>
4745
<p>Returns various size information for the specified
4746
allocator. The information returned is a subset of the
4747
information returned by
4748
<seealso marker="#system_info_allocator_tuple">erlang:system_info({allocator, Alloc})</seealso>.
4751
<tag><c>c_compiler_used</c></tag>
4753
<p>Returns a two-tuple describing the C compiler used when
4754
compiling the runtime system. The first element is an
4755
atom describing the name of the compiler, or <c>undefined</c>
4756
if unknown. The second element is a term describing the
4757
version of the compiler, or <c>undefined</c> if unknown.
4760
<tag><c>check_io</c></tag>
4762
<p>Returns a list containing miscellaneous information
4763
regarding the emulators internal I/O checking. Note,
4764
the content of the returned list may vary between
4765
platforms and over time. The only thing guaranteed is
4766
that a list is returned.</p>
4768
<tag><c>compat_rel</c></tag>
4770
<p>Returns the compatibility mode of the local node as
4771
an integer. The integer returned represents the
4772
Erlang/OTP release which the current emulator has been
4773
set to be backward compatible with. The compatibility
4774
mode can be configured at startup by using the command
4775
line flag <c>+R</c>, see
4776
<seealso marker="erts:erl#compat_rel">erl(1)</seealso>.</p>
4778
<tag><c>creation</c></tag>
4780
<p>Returns the creation of the local node as an integer.
4781
The creation is changed when a node is restarted. The
4782
creation of a node is stored in process identifiers, port
4783
identifiers, and references. This makes it (to some
4784
extent) possible to distinguish between identifiers from
4785
different incarnations of a node. Currently valid
4786
creations are integers in the range 1..3, but this may
4787
(probably will) change in the future. If the node is not
4788
alive, 0 is returned.</p>
4790
<tag><c>debug_compiled</c></tag>
4792
<p>Returns <c>true</c> if the emulator has been debug
4793
compiled; otherwise, <c>false</c>.
4796
<tag><c>dist</c></tag>
4798
<p>Returns a binary containing a string of distribution
4799
information formatted as in Erlang crash dumps. For more
4800
information see the <seealso marker="erts:crash_dump">"How to interpret the Erlang crash dumps"</seealso>
4801
chapter in the ERTS User's Guide.</p>
4803
<tag><c>dist_ctrl</c></tag>
4805
<p>Returns a list of tuples
4806
<c>{Node, ControllingEntity}</c>, one entry for each
4807
connected remote node. The <c>Node</c> is the name of the
4808
node and the <c>ControllingEntity</c> is the port or pid
4809
responsible for the communication to that node. More
4810
specifically, the <c>ControllingEntity</c> for nodes
4811
connected via TCP/IP (the normal case) is the socket
4812
actually used in communication with the specific node.</p>
4814
<tag><c>driver_version</c></tag>
4816
<p>Returns a string containing the erlang driver version
4817
used by the runtime system. It will be on the form
4818
<seealso marker="erts:erl_driver#version_management">"<major ver>.<minor ver>"</seealso>.</p>
4820
<tag><c>elib_malloc</c></tag>
4822
<p>If the emulator uses the <c>elib_malloc</c> memory
4823
allocator, a list of two-element tuples containing status
4824
information is returned; otherwise, <c>false</c> is
4825
returned. The list currently contains the following
4826
two-element tuples (all sizes are presented in bytes):</p>
4828
<tag><c>{heap_size, Size}</c></tag>
4830
<p>Where <c>Size</c> is the current heap size.</p>
4832
<tag><c>{max_alloced_size, Size}</c></tag>
4834
<p>Where <c>Size</c> is the maximum amount of memory
4835
allocated on the heap since the emulator started.</p>
4837
<tag><c>{alloced_size, Size}</c></tag>
4839
<p>Where <c>Size</c> is the current amount of memory
4840
allocated on the heap.</p>
4842
<tag><c>{free_size, Size}</c></tag>
4844
<p>Where <c>Size</c> is the current amount of free
4845
memory on the heap.</p>
4847
<tag><c>{no_alloced_blocks, No}</c></tag>
4849
<p>Where <c>No</c> is the current number of allocated
4850
blocks on the heap.</p>
4852
<tag><c>{no_free_blocks, No}</c></tag>
4854
<p>Where <c>No</c> is the current number of free blocks
4857
<tag><c>{smallest_alloced_block, Size}</c></tag>
4859
<p>Where <c>Size</c> is the size of the smallest
4860
allocated block on the heap.</p>
4862
<tag><c>{largest_free_block, Size}</c></tag>
4864
<p>Where <c>Size</c> is the size of the largest free
4865
block on the heap.</p>
4869
<tag><c>fullsweep_after</c></tag>
4871
<p>Returns <c>{fullsweep_after, int()}</c> which is the
4872
<c>fullsweep_after</c> garbage collection setting used
4873
by default. For more information see
4874
<c>garbage_collection</c> described below.</p>
4876
<tag><c>garbage_collection</c></tag>
4878
<p>Returns a list describing the default garbage collection
4879
settings. A process spawned on the local node by a
4880
<c>spawn</c> or <c>spawn_link</c> will use these
4881
garbage collection settings. The default settings can be
4883
<seealso marker="#erlang:system_flag/2">system_flag/2</seealso>.
4884
<seealso marker="#spawn_opt/4">spawn_opt/4</seealso>
4885
can spawn a process that does not use the default
4888
<tag><c>global_heaps_size</c></tag>
4890
<p>Returns the current size of the shared (global) heap.</p>
4892
<tag><c>heap_sizes</c></tag>
4894
<p>Returns a list of integers representing valid heap sizes
4895
in words. All Erlang heaps are sized from sizes in this
4898
<tag><c>heap_type</c></tag>
4900
<p>Returns the heap type used by the current emulator.
4901
Currently the following heap types exist:</p>
4903
<tag><c>private</c></tag>
4905
<p>Each process has a heap reserved for its use and no
4906
references between heaps of different processes are
4907
allowed. Messages passed between processes are copied
4910
<tag><c>shared</c></tag>
4912
<p>One heap for use by all processes. Messages passed
4913
between processes are passed by reference.</p>
4915
<tag><c>hybrid</c></tag>
4917
<p>A hybrid of the <c>private</c> and <c>shared</c> heap
4918
types. A shared heap as well as private heaps are
4923
<tag><c>info</c></tag>
4925
<p>Returns a binary containing a string of miscellaneous
4926
system information formatted as in Erlang crash dumps.
4927
For more information see the
4928
<seealso marker="erts:crash_dump">"How to interpret the Erlang crash dumps"</seealso> chapter in the ERTS
4931
<tag><c>kernel_poll</c></tag>
4933
<p>Returns <c>true</c> if the emulator uses some kind of
4934
kernel-poll implementation; otherwise, <c>false</c>.</p>
4936
<tag><c>loaded</c></tag>
4938
<p>Returns a binary containing a string of loaded module
4939
information formatted as in Erlang crash dumps. For more
4940
information see the <seealso marker="erts:crash_dump">"How to interpret the Erlang crash dumps"</seealso> chapter
4941
in the ERTS User's Guide.</p>
4943
<tag><c>logical_processors</c></tag>
4945
<p>Returns the number of logical processors detected on the
4946
system as an integer or the atom <c>unknown</c> if the
4947
emulator wasn't able to detect any.
4950
<tag><c>machine</c></tag>
4952
<p>Returns a string containing the Erlang machine name.</p>
4954
<tag><c>modified_timing_level</c></tag>
4956
<p>Returns the modified timing level (an integer) if
4957
modified timing has been enabled; otherwise,
4958
<c>undefined</c>. See the <c>+T</c> command line flag
4959
in the documentation of the
4960
<seealso marker="erts:erl#+T">erl(1)</seealso>
4961
command for more information on modified timing.</p>
4963
<tag><c>multi_scheduling</c></tag>
4965
<marker id="system_info_multi_scheduling"></marker>
4966
<p>Returns <c>disabled</c>, <c>blocked</c>, or <c>enabled</c>.
4967
A description of the return values:</p>
4969
<tag><c>disabled</c></tag>
4971
<p>The emulator has only one scheduler thread. The
4972
emulator does not have SMP support, or have been
4973
started with only one scheduler thread.</p>
4975
<tag><c>blocked</c></tag>
4977
<p>The emulator has more than one scheduler thread,
4978
but all scheduler threads but one have been blocked,
4979
i.e., only one scheduler thread will schedule
4980
Erlang processes and execute Erlang code.</p>
4982
<tag><c>enabled</c></tag>
4984
<p>The emulator has more than one scheduler thread,
4985
and no scheduler threads have been blocked, i.e.,
4986
all available scheduler threads will schedule
4987
Erlang processes and execute Erlang code.</p>
4990
<p>See also <seealso marker="#system_flag_multi_scheduling">erlang:system_flag(multi_scheduling, BlockState)</seealso>,
4991
<seealso marker="#system_info_multi_scheduling_blockers">erlang:system_info(multi_scheduling_blockers)</seealso>, and
4992
<seealso marker="#system_info_schedulers">erlang:system_info(schedulers)</seealso>.</p>
4994
<tag><c>multi_scheduling_blockers</c></tag>
4996
<marker id="system_info_multi_scheduling_blockers"></marker>
4997
<p>Returns a list of <c>PID</c>s when multi-scheduling
4998
is blocked; otherwise, the empty list. The <c>PID</c>s
4999
in the list is <c>PID</c>s of the processes currently
5000
blocking multi-scheduling. A <c>PID</c> will only be
5001
present once in the list, even if the corresponding
5002
process has blocked multiple times.</p>
5003
<p>See also <seealso marker="#system_flag_multi_scheduling">erlang:system_flag(multi_scheduling, BlockState)</seealso>,
5004
<seealso marker="#system_info_multi_scheduling">erlang:system_info(multi_scheduling)</seealso>, and
5005
<seealso marker="#system_info_schedulers">erlang:system_info(schedulers)</seealso>.</p>
5007
<tag><c>otp_release</c></tag>
5009
<marker id="system_info_otp_release"></marker>
5010
<p>Returns a string containing the OTP release number.</p>
5012
<tag><c>process_count</c></tag>
5014
<p>Returns the number of processes currently existing at
5015
the local node as an integer. The same value as
5016
<c>length(processes())</c> returns.</p>
5018
<tag><c>process_limit</c></tag>
5020
<p>Returns the maximum number of concurrently existing
5021
processes at the local node as an integer. This limit
5022
can be configured at startup by using the command line
5024
<seealso marker="erts:erl#max_processes">erl(1)</seealso>.</p>
5026
<tag><c>procs</c></tag>
5028
<p>Returns a binary containing a string of process and port
5029
information formatted as in Erlang crash dumps. For more
5030
information see the <seealso marker="erts:crash_dump">"How to interpret the Erlang crash dumps"</seealso> chapter
5031
in the ERTS User's Guide.</p>
5033
<tag><c>scheduler_id</c></tag>
5035
<marker id="system_info_scheduler_id"></marker>
5036
<p>Returns the scheduler id (<c>SchedulerId</c>) of the
5037
scheduler thread that the calling process is executing
5038
on. <c>SchedulerId</c> is a positive integer; where
5039
<c><![CDATA[1 <= SchedulerId <= erlang:system_info(schedulers)]]></c>. See also
5040
<seealso marker="#system_info_schedulers">erlang:system_info(schedulers)</seealso>.</p>
5042
<tag><c>schedulers</c></tag>
5044
<marker id="system_info_schedulers"></marker>
5045
<p>Returns the number of scheduler threads used by
5046
the emulator. A scheduler thread schedules Erlang
5047
processes and Erlang ports, and execute Erlang code
5048
and Erlang linked in driver code.</p>
5049
<p>The number of scheduler threads is determined at
5050
emulator boot time and cannot be changed after
5052
<p>See also <seealso marker="#system_info_scheduler_id">erlang:system_info(scheduler_id)</seealso>,
5053
<seealso marker="#system_flag_multi_scheduling">erlang:system_flag(multi_scheduling, BlockState)</seealso>,
5054
<seealso marker="#system_info_multi_scheduling">erlang:system_info(multi_scheduling)</seealso>, and
5055
and <seealso marker="#system_info_multi_scheduling_blockers">erlang:system_info(multi_scheduling_blockers)</seealso>.</p>
5057
<tag><c>smp_support</c></tag>
5059
<p>Returns <c>true</c> if the emulator has been compiled
5060
with smp support; otherwise, <c>false</c>.</p>
5062
<tag><c>system_version</c></tag>
5064
<p>Returns a string containing the emulator type and
5065
version as well as some important properties such as
5066
the size of the thread pool, etc.</p>
5068
<tag><c>system_architecture</c></tag>
5070
<p>Returns a string containing the processor and OS
5071
architecture the emulator is built for.</p>
5073
<tag><c>threads</c></tag>
5075
<p>Returns <c>true</c> if the emulator has been compiled
5076
with thread support; otherwise, <c>false</c> is
5079
<tag><c>thread_pool_size</c></tag>
5081
<marker id="system_info_thread_pool_size"></marker>
5082
<p>Returns the number of async threads in the async thread
5083
pool used for asynchronous driver calls
5084
(<seealso marker="erts:erl_driver#driver_async">driver_async()</seealso>)
5087
<tag><c>trace_control_word</c></tag>
5089
<p>Returns the value of the node's trace control word.
5090
For more information see documentation of the function
5091
<c>get_tcw</c> in "Match Specifications in Erlang",
5092
<seealso marker="erts:match_spec#get_tcw">ERTS User's Guide</seealso>.</p>
5094
<tag><c>version</c></tag>
5096
<marker id="system_info_version"></marker>
5097
<p>Returns a string containing the version number of the
5100
<tag><c>wordsize</c></tag>
5102
<p>Returns the word size in bytes as an integer, i.e. on a
5103
32-bit architecture 4 is returned, and on a 64-bit
5104
architecture 8 is returned.</p>
5108
<p>The <c>scheduler</c> argument has changed name to
5109
<c>scheduler_id</c>. This in order to avoid mixup with
5110
the <c>schedulers</c> argument. The <c>scheduler</c>
5111
argument was introduced in ERTS version 5.5 and renamed
5112
in ERTS version 5.5.1.</p>
5118
<name>erlang:system_monitor() -> MonSettings</name>
5119
<fsummary>Current system performance monitoring settings</fsummary>
5121
<v>MonSettings -> {MonitorPid, Options} | undefined</v>
5122
<v> MonitorPid = pid()</v>
5123
<v> Options = [Option]</v>
5124
<v> Option = {long_gc, Time} | {large_heap, Size} | busy_port | busy_dist_port</v>
5125
<v> Time = Size = int()</v>
5128
<p>Returns the current system monitoring settings set by
5129
<seealso marker="#erlang:system_monitor/2">erlang:system_monitor/2</seealso>
5130
as <c>{MonitorPid, Options}</c>, or <c>undefined</c> if there
5131
are no settings. The order of the options may be different
5132
from the one that was set.</p>
5137
<name>erlang:system_monitor(undefined | {MonitorPid, Options}) -> MonSettings</name>
5138
<fsummary>Set or clear system performance monitoring options</fsummary>
5140
<v>MonitorPid, Options, MonSettings -- see below</v>
5143
<p>When called with the argument <c>undefined</c>, all
5144
system performance monitoring settings are cleared.</p>
5145
<p>Calling the function with <c>{MonitorPid, Options}</c> as
5146
argument, is the same as calling
5147
<seealso marker="#erlang:system_monitor/2">erlang:system_monitor(MonitorPid, Options)</seealso>.</p>
5148
<p>Returns the previous system monitor settings just like
5149
<seealso marker="#erlang:system_monitor/0">erlang:system_monitor/0</seealso>.</p>
5154
<name>erlang:system_monitor(MonitorPid, [Option]) -> MonSettings</name>
5155
<fsummary>Set system performance monitoring options</fsummary>
5157
<v>MonitorPid = pid()</v>
5158
<v>Option = {long_gc, Time} | {large_heap, Size} | busy_port | busy_dist_port</v>
5159
<v> Time = Size = int()</v>
5160
<v>MonSettings = {OldMonitorPid, [Option]}</v>
5161
<v> OldMonitorPid = pid()</v>
5164
<p>Sets system performance monitoring options. <c>MonitorPid</c>
5165
is a local pid that will receive system monitor messages, and
5166
the second argument is a list of monitoring options:</p>
5168
<tag><c>{long_gc, Time}</c></tag>
5170
<p>If a garbage collection in the system takes at least
5171
<c>Time</c> wallclock milliseconds, a message
5172
<c>{monitor, GcPid, long_gc, Info}</c> is sent to
5173
<c>MonitorPid</c>. <c>GcPid</c> is the pid that was
5174
garbage collected and <c>Info</c> is a list of two-element
5175
tuples describing the result of the garbage collection.
5176
One of the tuples is <c>{timeout, GcTime}</c> where
5177
<c>GcTime</c> is the actual time for the garbage
5178
collection in milliseconds. The other tuples are
5179
tagged with <c>heap_size</c>, <c>heap_block_size</c>,
5180
<c>stack_size</c>, <c>mbuf_size</c>, <c>old_heap_size</c>,
5181
and <c>old_heap_block_size</c>. These tuples are
5182
explained in the documentation of the
5183
<seealso marker="#gc_start">gc_start</seealso>
5185
<seealso marker="#erlang:trace/3">erlang:trace/3</seealso>).
5186
New tuples may be added, and the order of the tuples in
5187
the <c>Info</c> list may be changed at any time without prior
5191
<tag><c>{large_heap, Size}</c></tag>
5193
<p>If a garbage collection in the system results in
5194
the allocated size of a heap being at least <c>Size</c>
5195
words, a message <c>{monitor, GcPid, large_heap, Info}</c>
5196
is sent to <c>MonitorPid</c>. <c>GcPid</c> and <c>Info</c>
5197
are the same as for <c>long_gc</c> above, except that
5198
the tuple tagged with <c>timeout</c> is not present.
5199
<em>Note</em>: As of erts version 5.6 the monitor message
5200
is sent if the sum of the sizes of all memory blocks allocated
5201
for all heap generations is equal to or larger than <c>Size</c>.
5202
Previously the monitor message was sent if the memory block
5203
allocated for the youngest generation was equal to or larger
5207
<tag><c>busy_port</c></tag>
5209
<p>If a process in the system gets suspended because it
5210
sends to a busy port, a message
5211
<c>{monitor, SusPid, busy_port, Port}</c> is sent to
5212
<c>MonitorPid</c>. <c>SusPid</c> is the pid that got
5213
suspended when sending to <c>Port</c>.</p>
5215
<tag><c>busy_dist_port</c></tag>
5217
<p>If a process in the system gets suspended because it
5218
sends to a process on a remote node whose inter-node
5219
communication was handled by a busy port, a message
5220
<c>{monitor, SusPid, busy_dist_port, Port}</c> is sent to
5221
<c>MonitorPid</c>. <c>SusPid</c> is the pid that got
5222
suspended when sending through the inter-node
5223
communication port <c>Port</c>.</p>
5226
<p>Returns the previous system monitor settings just like
5227
<seealso marker="#erlang:system_monitor/0">erlang:system_monitor/0</seealso>.</p>
5229
<p>If a monitoring process gets so large that it itself
5230
starts to cause system monitor messages when garbage
5231
collecting, the messages will enlarge the process's
5232
message queue and probably make the problem worse.</p>
5233
<p>Keep the monitoring process neat and do not set the system
5234
monitor limits too tight.</p>
5236
<p>Failure: <c>badarg</c> if <c>MonitorPid</c> does not exist.</p>
5241
<name>erlang:system_profile() -> ProfilerSettings</name>
5242
<fsummary>Current system profiling settings</fsummary>
5244
<v>ProfilerSettings -> {ProfilerPid, Options} | undefined</v>
5245
<v> ProfilerPid = pid() | port()</v>
5246
<v> Options = [Option]</v>
5247
<v> Option = runnable_procs | runnable_ports | scheduler | exclusive</v>
5250
<p>Returns the current system profiling settings set by
5251
<seealso marker="#erlang:system_profile/2">erlang:system_profile/2</seealso>
5252
as <c>{ProfilerPid, Options}</c>, or <c>undefined</c> if there
5253
are no settings. The order of the options may be different
5254
from the one that was set.</p>
5259
<name>erlang:system_profile(ProfilerPid, Options) -> ProfilerSettings</name>
5260
<fsummary>Current system profiling settings</fsummary>
5262
<v>ProfilerSettings -> {ProfilerPid, Options} | undefined</v>
5263
<v> ProfilerPid = pid() | port()</v>
5264
<v> Options = [Option]</v>
5265
<v> Option = runnable_procs | runnable_ports | scheduler | exclusive</v>
5268
<p>Sets system profiler options. <c>ProfilerPid</c>
5269
is a local pid or port that will receive profiling messages. The
5270
receiver is excluded from all profiling.
5271
The second argument is a list of profiling options:</p>
5273
<tag><c>runnable_procs</c></tag>
5275
<p>If a process is put into or removed from the runqueue a message,
5276
<c>{profile, Pid, State, Mfa, Ts}</c>, is sent to
5277
<c>ProfilerPid</c>. Running processes that is reinsertet into the
5278
runqueue after completing its reductions does not trigger this
5282
<tag><c>runnable_ports</c></tag>
5284
<p>If a port is put into or removed from the runqueue a message,
5285
<c>{profile, Port, State, 0, Ts}</c>, is sent to
5289
<tag><c>scheduler</c></tag>
5291
<p>If a scheduler is put to sleep or awoken a message,
5292
<c>{profile, scheduler, Id, State, NoScheds, Ts}</c>, is sent
5293
to <c>ProfilerPid</c>.
5296
<tag><c>exclusive</c></tag>
5299
If a synchronous call to a port from a process is done, the
5300
calling process is considered not runnable during the call
5301
runtime to the port. The calling process is notified as
5302
<c>inactive</c> and subsequently <c>active</c> when the port
5307
<note><p><c>erlang:system_profile</c> is considered experimental and
5308
its behaviour may change in the future.</p>
5314
<name>term_to_binary(Term) -> ext_binary()</name>
5315
<fsummary>Encode a term to an Erlang external term format binary</fsummary>
5317
<v>Term = term()</v>
5320
<p>Returns a binary data object which is the result of encoding
5321
<c>Term</c> according to the Erlang external term format.</p>
5322
<p>This can be used for a variety of purposes, for example
5323
writing a term to a file in an efficient way, or sending an
5324
Erlang term to some type of communications channel not
5325
supported by distributed Erlang.</p>
5327
<seealso marker="#binary_to_term/1">binary_to_term/1</seealso>.</p>
5331
<name>term_to_binary(Term, [Option]) -> ext_binary()</name>
5332
<fsummary>Encode a term to en Erlang external term format binary</fsummary>
5334
<v>Term = term()</v>
5335
<v>Option = compressed | {compressed,Level} | {minor_version,Version}</v>
5338
<p>Returns a binary data object which is the result of encoding
5339
<c>Term</c> according to the Erlang external term format.</p>
5340
<p>If the option <c>compressed</c> is provided, the external
5341
term format will be compressed. The compressed format is
5342
automatically recognized by <c>binary_to_term/1</c> in R7B and later.</p>
5343
<p>It is also possible to specify a compression level by giving
5344
the option <c>{compressed,Level}</c>, where <c>Level</c> is an
5345
integer from 0 through 9. <c>0</c> means that no compression
5346
will be done (it is the same as not giving any <c>compressed</c> option);
5347
<c>1</c> will take the least time but may not compress as well as
5348
the higher levels; <c>9</c> will take the most time and may produce
5349
a smaller result. Note the "mays" in the preceding sentence; depending
5350
on the input term, level 9 compression may or may not produce a smaller
5351
result than level 1 compression.</p>
5352
<p>Currently, <c>compressed</c> gives the same result as
5353
<c>{compressed,6}</c>.</p>
5354
<p>The option <c>{minor_version,Version}</c> can be use to control
5355
some details of the encoding. This option was
5356
introduced in R11B-4. Currently, the allowed values for <c>Version</c>
5357
are <c>0</c> and <c>1</c>.</p>
5358
<p><c>{minor_version,1}</c> forces any floats in the term to be encoded
5359
in a more space-efficient and exact way (namely in the 64-bit IEEE format,
5360
rather than converted to a textual representation). <c>binary_to_term/1</c>
5361
in R11B-4 and later is able decode the new representation.</p>
5362
<p><c>{minor_version,0}</c> is currently the default, meaning that floats
5363
will be encoded using a textual representation; this option is useful if
5364
you want to ensure that releases prior to R11B-4 can decode resulting
5367
<seealso marker="#binary_to_term/1">binary_to_term/1</seealso>.</p>
5371
<name>throw(Any)</name>
5372
<fsummary>Throw an exception</fsummary>
5377
<p>A non-local return from a function. If evaluated within a
5378
<c>catch</c>, <c>catch</c> will return the value <c>Any</c>.</p>
5380
> <input>catch throw({hello, there}).</input>
5382
<p>Failure: <c>nocatch</c> if not evaluated within a catch.</p>
5386
<name>time() -> {Hour, Minute, Second}</name>
5387
<fsummary>Current time</fsummary>
5389
<v>Hour = Minute = Second = int()</v>
5392
<p>Returns the current time as <c>{Hour, Minute, Second}</c>.</p>
5393
<p>The time zone and daylight saving time correction depend on
5394
the underlying OS.</p>
5396
> <input>time().</input>
5401
<name>tl(List1) -> List2</name>
5402
<fsummary>Tail of a list</fsummary>
5404
<v>List1 = List2 = [term()]</v>
5407
<p>Returns the tail of <c>List1</c>, that is, the list minus
5408
the first element.</p>
5410
> <input>tl([geesties, guilies, beasties]).</input>
5411
[guilies, beasties]</pre>
5412
<p>Allowed in guard tests.</p>
5413
<p>Failure: <c>badarg</c> if <c>List</c> is the empty list [].</p>
5417
<name>erlang:trace(PidSpec, How, FlagList) -> int()</name>
5418
<fsummary>Set trace flags for a process or processes</fsummary>
5420
<v>PidSpec = pid() | existing | new | all</v>
5422
<v>FlagList = [Flag]</v>
5423
<v> Flag -- see below</v>
5426
<p>Turns on (if <c>How == true</c>) or off (if
5427
<c>How == false</c>) the trace flags in <c>FlagList</c> for
5428
the process or processes represented by <c>PidSpec</c>.</p>
5429
<p><c>PidSpec</c> is either a pid for a local process, or one of
5430
the following atoms:</p>
5432
<tag><c>existing</c></tag>
5434
<p>All processes currently existing.</p>
5436
<tag><c>new</c></tag>
5438
<p>All processes that will be created in the future.</p>
5440
<tag><c>all</c></tag>
5442
<p>All currently existing processes and all processes that
5443
will be created in the future.</p>
5446
<p><c>FlagList</c> can contain any number of the following
5447
flags (the "message tags" refers to the list of messages
5448
following below):</p>
5450
<tag><c>all</c></tag>
5452
<p>Set all trace flags except <c>{tracer, Tracer}</c> and
5453
<c>cpu_timestamp</c> that are in their nature different
5454
than the others.</p>
5456
<tag><c>send</c></tag>
5458
<p>Trace sending of messages.</p>
5459
<p>Message tags: <c>send</c>,
5460
<c>send_to_non_existing_process</c>.</p>
5462
<tag><c>'receive'</c></tag>
5464
<p>Trace receiving of messages.</p>
5465
<p>Message tags: <c>'receive'</c>.</p>
5467
<tag><c>procs</c></tag>
5469
<p>Trace process related events.</p>
5470
<p>Message tags: <c>spawn</c>, <c>exit</c>,
5471
<c>register</c>, <c>unregister</c>, <c>link</c>,
5472
<c>unlink</c>, <c>getting_linked</c>,
5473
<c>getting_unlinked</c>.</p>
5475
<tag><c>call</c></tag>
5477
<p>Trace certain function calls. Specify which function
5478
calls to trace by calling
5479
<seealso marker="#erlang:trace_pattern/3">erlang:trace_pattern/3</seealso>.</p>
5480
<p>Message tags: <c>call</c>, <c>return_from</c>.</p>
5482
<tag><c>silent</c></tag>
5484
<p>Used in conjunction with the <c>call</c> trace flag.
5485
The <c>call</c>, <c>return_from</c> and <c>return_to</c>
5486
trace messages are inhibited if this flag is set,
5487
but if there are match specs they are executed as normal.</p>
5488
<p>Silent mode is inhibited by executing
5489
<c>erlang:trace(_, false, [silent|_])</c>,
5490
or by a match spec executing the <c>{silent, false}</c>
5492
<p>The <c>silent</c> trace flag facilitates setting up
5493
a trace on many or even all processes in the system.
5494
Then the interesting trace can be activated and
5495
deactivated using the <c>{silent,Bool}</c>
5496
match spec function, giving a high degree
5497
of control of which functions with which
5498
arguments that triggers the trace.</p>
5499
<p>Message tags: <c>call</c>, <c>return_from</c>,
5500
<c>return_to</c>. Or rather, the absence of.</p>
5502
<tag><c>return_to</c></tag>
5504
<p>Used in conjunction with the <c>call</c> trace flag.
5505
Trace the actual return from a traced function back to
5506
its caller. Only works for functions traced with
5507
the <c>local</c> option to
5508
<seealso marker="#erlang:trace_pattern/3">erlang:trace_pattern/3</seealso>.</p>
5509
<p>The semantics is that a trace message is sent when a
5510
call traced function actually returns, that is, when a
5511
chain of tail recursive calls is ended. There will be
5512
only one trace message sent per chain of tail recursive
5513
calls, why the properties of tail recursiveness for
5514
function calls are kept while tracing with this flag.
5515
Using <c>call</c> and <c>return_to</c> trace together
5516
makes it possible to know exactly in which function a
5517
process executes at any time.</p>
5518
<p>To get trace messages containing return values from
5519
functions, use the <c>{return_trace}</c> match_spec
5521
<p>Message tags: <c>return_to</c>.</p>
5523
<tag><c>running</c></tag>
5525
<p>Trace scheduling of processes.</p>
5526
<p>Message tags: <c>in</c>, and <c>out</c>.</p>
5528
<tag><c>exiting</c></tag>
5530
<p>Trace scheduling of an exiting processes.</p>
5531
<p>Message tags: <c>in_exiting</c>, <c>out_exiting</c>, and
5532
<c>out_exited</c>.</p>
5534
<tag><c>garbage_collection</c></tag>
5536
<p>Trace garbage collections of processes.</p>
5537
<p>Message tags: <c>gc_start</c>, <c>gc_end</c>.</p>
5539
<tag><c>timestamp</c></tag>
5541
<p>Include a time stamp in all trace messages. The time
5542
stamp (Ts) is of the same form as returned by
5543
<c>erlang:now()</c>.</p>
5545
<tag><c>cpu_timestamp</c></tag>
5547
<p>A global trace flag for the Erlang node that makes all
5548
trace timestamps be in CPU time, not wallclock. It is
5549
only allowed with <c>PidSpec==all</c>. If the host
5550
machine operating system does not support high resolution
5551
CPU time measurements, <c>trace/3</c> exits with
5554
<tag><c>arity</c></tag>
5556
<p>Used in conjunction with the <c>call</c> trace flag.
5557
<c>{M, F, Arity}</c> will be specified instead of
5558
<c>{M, F, Args}</c> in call trace messages.</p>
5560
<tag><c>set_on_spawn</c></tag>
5562
<p>Makes any process created by a traced process inherit
5563
its trace flags, including the <c>set_on_spawn</c> flag.</p>
5565
<tag><c>set_on_first_spawn</c></tag>
5567
<p>Makes the first process created by a traced process
5568
inherit its trace flags, excluding
5569
the <c>set_on_first_spawn</c> flag.</p>
5571
<tag><c>set_on_link</c></tag>
5573
<p>Makes any process linked by a traced process inherit its
5574
trace flags, including the <c>set_on_link</c> flag.</p>
5576
<tag><c>set_on_first_link</c></tag>
5578
<p>Makes the first process linked to by a traced process
5579
inherit its trace flags, excluding
5580
the <c>set_on_first_link</c> flag.</p>
5582
<tag><c>{tracer, Tracer}</c></tag>
5584
<p>Specify where to send the trace messages. <c>Tracer</c>
5585
must be the pid of a local process or the port identifier
5586
of a local port. If this flag is not given, trace
5587
messages will be sent to the process that called
5588
<c>erlang:trace/3</c>.</p>
5591
<p>The effect of combining <c>set_on_first_link</c> with
5592
<c>set_on_link</c> is the same as having
5593
<c>set_on_first_link</c> alone. Likewise for
5594
<c>set_on_spawn</c> and <c>set_on_first_spawn</c>.</p>
5595
<p>If the <c>timestamp</c> flag is not given, the tracing
5596
process will receive the trace messages described below.
5597
<c>Pid</c> is the pid of the traced process in which
5598
the traced event has occurred. The third element of the tuple
5599
is the message tag.</p>
5600
<p>If the <c>timestamp</c> flag is given, the first element of
5601
the tuple will be <c>trace_ts</c> instead and the timestamp
5602
is added last in the tuple.</p>
5604
<tag><c>{trace, Pid, 'receive', Msg}</c></tag>
5606
<p>When <c>Pid</c> receives the message <c>Msg</c>.</p>
5608
<tag><c>{trace, Pid, send, Msg, To}</c></tag>
5610
<p>When <c>Pid</c> sends the message <c>Msg</c> to
5611
the process <c>To</c>.</p>
5613
<tag><c>{trace, Pid, send_to_non_existing_process, Msg, To}</c></tag>
5615
<p>When <c>Pid</c> sends the message <c>Msg</c> to
5616
the non-existing process <c>To</c>.</p>
5618
<tag><c>{trace, Pid, call, {M, F, Args}}</c></tag>
5620
<p>When <c>Pid</c> calls a traced function. The return
5621
values of calls are never supplied, only the call and its
5623
<p>Note that the trace flag <c>arity</c> can be used to
5624
change the contents of this message, so that <c>Arity</c>
5625
is specified instead of <c>Args</c>.</p>
5627
<tag><c>{trace, Pid, return_to, {M, F, Arity}}</c></tag>
5629
<p>When <c>Pid</c> returns <em>to</em> the specified
5630
function. This trace message is sent if both
5631
the <c>call</c> and the <c>return_to</c> flags are set,
5632
and the function is set to be traced on <em>local</em>
5633
function calls. The message is only sent when returning
5634
from a chain of tail recursive function calls where at
5635
least one call generated a <c>call</c> trace message
5636
(that is, the functions match specification matched and
5637
<c>{message, false}</c> was not an action).</p>
5639
<tag><c>{trace, Pid, return_from, {M, F, Arity}, ReturnValue}</c></tag>
5641
<p>When <c>Pid</c> returns <em>from</em> the specified
5642
function. This trace message is sent if the <c>call</c>
5643
flag is set, and the function has a match specification
5644
with a <c>return_trace</c> or <c>exception_trace</c> action.</p>
5646
<tag><c>{trace, Pid, exception_from, {M, F, Arity}, {Class, Value}}</c></tag>
5648
<p>When <c>Pid</c> exits <em>from</em> the specified
5649
function due to an exception. This trace message is sent
5650
if the <c>call</c> flag is set, and the function has
5651
a match specification with an <c>exception_trace</c> action.</p>
5653
<tag><c>{trace, Pid, spawn, Pid2, {M, F, Args}}</c></tag>
5655
<p>When <c>Pid</c> spawns a new process <c>Pid2</c> with
5656
the specified function call as entry point.</p>
5657
<p>Note that <c>Args</c> is supposed to be the argument
5658
list, but may be any term in the case of an erroneous
5661
<tag><c>{trace, Pid, exit, Reason}</c></tag>
5663
<p>When <c>Pid</c> exits with reason <c>Reason</c>.</p>
5665
<tag><c>{trace, Pid, link, Pid2}</c></tag>
5667
<p>When <c>Pid</c> links to a process <c>Pid2</c>.</p>
5669
<tag><c>{trace, Pid, unlink, Pid2}</c></tag>
5671
<p>When <c>Pid</c> removes the link from a process
5674
<tag><c>{trace, Pid, getting_linked, Pid2}</c></tag>
5676
<p>When <c>Pid</c> gets linked to a process <c>Pid2</c>.</p>
5678
<tag><c>{trace, Pid, getting_unlinked, Pid2}</c></tag>
5680
<p>When <c>Pid</c> gets unlinked from a process <c>Pid2</c>.</p>
5682
<tag><c>{trace, Pid, register, RegName}</c></tag>
5684
<p>When <c>Pid</c> gets the name <c>RegName</c> registered.</p>
5686
<tag><c>{trace, Pid, unregister, RegName}</c></tag>
5688
<p>When <c>Pid</c> gets the name <c>RegName</c> unregistered.
5689
Note that this is done automatically when a registered
5692
<tag><c>{trace, Pid, in, {M, F, Arity} | 0}</c></tag>
5694
<p>When <c>Pid</c> is scheduled to run. The process will
5695
run in function <c>{M, F, Arity}</c>. On some rare
5696
occasions the current function cannot be determined, then
5697
the last element <c>Arity</c> is 0.</p>
5699
<tag><c>{trace, Pid, out, {M, F, Arity} | 0}</c></tag>
5701
<p>When <c>Pid</c> is scheduled out. The process was
5702
running in function {M, F, Arity}. On some rare occasions
5703
the current function cannot be determined, then the last
5704
element <c>Arity</c> is 0.</p>
5706
<tag><c>{trace, Pid, gc_start, Info}</c></tag>
5708
<marker id="gc_start"></marker>
5709
<p>Sent when garbage collection is about to be started.
5710
<c>Info</c> is a list of two-element tuples, where
5711
the first element is a key, and the second is the value.
5712
You should not depend on the tuples have any defined
5713
order. Currently, the following keys are defined:</p>
5715
<tag><c>heap_size</c></tag>
5716
<item>The size of the used part of the heap.</item>
5717
<tag><c>heap_block_size</c></tag>
5718
<item>The size of the memory block used for storing
5719
the heap and the stack.</item>
5720
<tag><c>old_heap_size</c></tag>
5721
<item>The size of the used part of the old heap.</item>
5722
<tag><c>old_heap_block_size</c></tag>
5723
<item>The size of the memory block used for storing
5724
the old heap.</item>
5725
<tag><c>stack_size</c></tag>
5726
<item>The actual size of the stack.</item>
5727
<tag><c>recent_size</c></tag>
5728
<item>The size of the data that survived the previous garbage
5730
<tag><c>mbuf_size</c></tag>
5731
<item>The combined size of message buffers associated with
5734
<p>All sizes are in words.</p>
5736
<tag><c>{trace, Pid, gc_end, Info}</c></tag>
5738
<p>Sent when garbage collection is finished. <c>Info</c>
5739
contains the same kind of list as in the <c>gc_start</c>
5740
message, but the sizes reflect the new sizes after
5741
garbage collection.</p>
5744
<p>If the tracing process dies, the flags will be silently
5746
<p>Only one process can trace a particular process. For this
5747
reason, attempts to trace an already traced process will fail.</p>
5748
<p>Returns: A number indicating the number of processes that
5749
matched <c>PidSpec</c>. If <c>PidSpec</c> is a pid,
5750
the return value will be <c>1</c>. If <c>PidSpec</c> is
5751
<c>all</c> or <c>existing</c> the return value will be
5752
the number of processes running, excluding tracer processes.
5753
If <c>PidSpec</c> is <c>new</c>, the return value will be
5755
<p>Failure: If specified arguments are not supported. For
5756
example <c>cpu_timestamp</c> is not supported on all
5761
<name>erlang:trace_delivered(Tracee) -> Ref</name>
5762
<fsummary>Notification when trace has been delivered</fsummary>
5764
<v>Tracee = pid() | all</v>
5765
<v>Ref = reference()</v>
5768
<p>The delivery of trace messages is dislocated on the time-line
5769
compared to other events in the system. If you know that the
5770
<c>Tracee</c> has passed some specific point in its execution,
5771
and you want to know when at least all trace messages
5772
corresponding to events up to this point have reached the tracer
5773
you can use <c>erlang:trace_delivered(Tracee)</c>. A
5774
<c>{trace_delivered, Tracee, Ref}</c> message is sent to
5775
the caller of <c>erlang:trace_delivered(Tracee)</c> when it
5776
is guaranteed that all trace messages have been delivered to
5777
the tracer up to the point that the <c>Tracee</c> had reached
5778
at the time of the call to
5779
<c>erlang:trace_delivered(Tracee)</c>.</p>
5780
<p>Note that the <c>trace_delivered</c> message does <em>not</em>
5781
imply that trace messages have been delivered; instead, it implies
5782
that all trace messages that <em>should</em> be delivered have
5783
been delivered. It is not an error if <c>Tracee</c> isn't, and
5784
hasn't been traced by someone, but if this is the case,
5785
<em>no</em> trace messages will have been delivered when the
5786
<c>trace_delivered</c> message arrives.</p>
5787
<p>Note that <c>Tracee</c> has to refer to a process currently,
5788
or previously existing on the same node as the caller of
5789
<c>erlang:trace_delivered(Tracee)</c> resides on.
5790
The special <c>Tracee</c> atom <c>all</c> denotes all processes
5791
that currently are traced in the node.</p>
5792
<p>An example: Process <c>A</c> is tracee, port <c>B</c> is
5793
tracer, and process <c>C</c> is the port owner of <c>B</c>.
5794
<c>C</c> wants to close <c>B</c> when <c>A</c> exits. <c>C</c>
5795
can ensure that the trace isn't truncated by calling
5796
<c>erlang:trace_delivered(A)</c> when <c>A</c> exits and wait
5797
for the <c>{trace_delivered, A, Ref}</c> message before closing
5799
<p>Failure: <c>badarg</c> if <c>Tracee</c> does not refer to a
5800
process (dead or alive) on the same node as the caller of
5801
<c>erlang:trace_delivered(Tracee)</c> resides on.</p>
5805
<name>erlang:trace_info(PidOrFunc, Item) -> Res</name>
5806
<fsummary>Trace information about a process or function</fsummary>
5808
<v>PidOrFunc = pid() | new | {Module, Function, Arity} | on_load</v>
5809
<v> Module = Function = atom()</v>
5810
<v> Arity = int()</v>
5811
<v>Item, Res -- see below</v>
5814
<p>Returns trace information about a process or function.</p>
5815
<p>To get information about a process, <c>PidOrFunc</c> should
5816
be a pid or the atom <c>new</c>. The atom <c>new</c> means
5817
that the default trace state for processes to be created will
5818
be returned. <c>Item</c> must have one of the following
5821
<tag><c>flags</c></tag>
5823
<p>Return a list of atoms indicating what kind of traces is
5824
enabled for the process. The list will be empty if no
5825
traces are enabled, and one or more of the followings
5826
atoms if traces are enabled: <c>send</c>,
5827
<c>'receive'</c>, <c>set_on_spawn</c>, <c>call</c>,
5828
<c>return_to</c>, <c>procs</c>, <c>set_on_first_spawn</c>,
5829
<c>set_on_link</c>, <c>running</c>,
5830
<c>garbage_collection</c>, <c>timestamp</c>, and
5831
<c>arity</c>. The order is arbitrary.</p>
5833
<tag><c>tracer</c></tag>
5835
<p>Return the identifier for process or port tracing this
5836
process. If this process is not being traced, the return
5837
value will be <c>[]</c>.</p>
5840
<p>To get information about a function, <c>PidOrFunc</c> should
5841
be a three-element tuple: <c>{Module, Function, Arity}</c> or
5842
the atom <c>on_load</c>. No wildcards are allowed. Returns
5843
<c>undefined</c> if the function does not exist or
5844
<c>false</c> if the function is not traced at all. <c>Item</c>
5845
must have one of the following values:</p>
5847
<tag><c>traced</c></tag>
5849
<p>Return <c>global</c> if this function is traced on
5850
global function calls, <c>local</c> if this function is
5851
traced on local function calls (i.e local and global
5852
function calls), and <c>false</c> if neither local nor
5853
global function calls are traced.</p>
5855
<tag><c>match_spec</c></tag>
5857
<p>Return the match specification for this function, if it
5858
has one. If the function is locally or globally traced but
5859
has no match specification defined, the returned value
5862
<tag><c>meta</c></tag>
5864
<p>Return the meta trace tracer process or port for this
5865
function, if it has one. If the function is not meta
5866
traced the returned value is <c>false</c>, and if
5867
the function is meta traced but has once detected that
5868
the tracer proc is invalid, the returned value is [].</p>
5870
<tag><c>meta_match_spec</c></tag>
5872
<p>Return the meta trace match specification for this
5873
function, if it has one. If the function is meta traced
5874
but has no match specification defined, the returned
5875
value is <c>[]</c>.</p>
5877
<tag><c>call_count</c></tag>
5879
<p>Return the call count value for this function or
5880
<c>true</c> for the pseudo function <c>on_load</c> if call
5881
count tracing is active. Return <c>false</c> otherwise.
5883
<seealso marker="#erlang:trace_pattern/3">erlang:trace_pattern/3</seealso>.</p>
5885
<tag><c>all</c></tag>
5887
<p>Return a list containing the <c>{Item, Value}</c> tuples
5888
for all other items, or return <c>false</c> if no tracing
5889
is active for this function.</p>
5892
<p>The actual return value will be <c>{Item, Value}</c>, where
5893
<c>Value</c> is the requested information as described above.
5894
If a pid for a dead process was given, or the name of a
5895
non-existing function, <c>Value</c> will be <c>undefined</c>.</p>
5896
<p>If <c>PidOrFunc</c> is the <c>on_load</c>, the information
5897
returned refers to the default value for code that will be
5902
<name>erlang:trace_pattern(MFA, MatchSpec) -> int()</name>
5903
<fsummary>Set trace patterns for global call tracing</fsummary>
5906
<seealso marker="#erlang:trace_pattern/3">erlang:trace_pattern(MFA, MatchSpec, [])</seealso>,
5907
retained for backward compatibility.</p>
5911
<name>erlang:trace_pattern(MFA, MatchSpec, FlagList) -> int()</name>
5912
<fsummary>Set trace patterns for tracing of function calls</fsummary>
5914
<v>MFA, MatchSpec, FlagList -- see below</v>
5917
<p>This BIF is used to enable or disable call tracing for
5918
exported functions. It must be combined with
5919
<seealso marker="#erlang:trace/3">erlang:trace/3</seealso>
5920
to set the <c>call</c> trace flag for one or more processes.</p>
5921
<p>Conceptually, call tracing works like this: Inside
5922
the Erlang virtual machine there is a set of processes to be
5923
traced and a set of functions to be traced. Tracing will be
5924
enabled on the intersection of the set. That is, if a process
5925
included in the traced process set calls a function included
5926
in the traced function set, the trace action will be taken.
5927
Otherwise, nothing will happen.</p>
5929
<seealso marker="#erlang:trace/3">erlang:trace/3</seealso> to
5930
add or remove one or more processes to the set of traced
5931
processes. Use <c>erlang:trace_pattern/2</c> to add or remove
5932
exported functions to the set of traced functions.</p>
5933
<p>The <c>erlang:trace_pattern/3</c> BIF can also add match
5934
specifications to an exported function. A match specification
5935
comprises a pattern that the arguments to the function must
5936
match, a guard expression which must evaluate to <c>true</c>
5937
and an action to be performed. The default action is to send a
5938
trace message. If the pattern does not match or the guard
5939
fails, the action will not be executed.</p>
5940
<p>The <c>MFA</c> argument should be a tuple like
5941
<c>{Module, Function, Arity}</c> or the atom <c>on_load</c>
5942
(described below). It can be the module, function, and arity
5943
for an exported function (or a BIF in any module).
5944
The <c>'_'</c> atom can be used to mean any of that kind.
5945
Wildcards can be used in any of the following ways:</p>
5947
<tag><c>{Module,Function,'_'}</c></tag>
5949
<p>All exported functions of any arity named <c>Function</c>
5950
in module <c>Module</c>.</p>
5952
<tag><c>{Module,'_','_'}</c></tag>
5954
<p>All exported functions in module <c>Module</c>.</p>
5956
<tag><c>{'_','_','_'}</c></tag>
5958
<p>All exported functions in all loaded modules.</p>
5961
<p>Other combinations, such as <c>{Module,'_',Arity}</c>, are
5962
not allowed. Local functions will match wildcards only if
5963
the <c>local</c> option is in the <c>FlagList</c>.</p>
5964
<p>If the <c>MFA</c> argument is the atom <c>on_load</c>,
5965
the match specification and flag list will be used on all
5966
modules that are newly loaded.</p>
5967
<p>The <c>MatchSpec</c> argument can take any of the following
5970
<tag><c>false</c></tag>
5972
<p>Disable tracing for the matching function(s). Any match
5973
specification will be removed.</p>
5975
<tag><c>true</c></tag>
5977
<p>Enable tracing for the matching function(s).</p>
5979
<tag><c>MatchSpecList</c></tag>
5981
<p>A list of match specifications. An empty list is
5982
equivalent to <c>true</c>. See the ERTS User's Guide
5983
for a description of match specifications.</p>
5985
<tag><c>restart</c></tag>
5987
<p>For the <c>FlagList</c> option <c>call_count</c>:
5988
restart the existing counters. The behaviour is undefined
5989
for other <c>FlagList</c> options.</p>
5991
<tag><c>pause</c></tag>
5993
<p>For the <c>FlagList</c> option <c>call_count</c>: pause
5994
the existing counters. The behaviour is undefined for
5995
other <c>FlagList</c> options.</p>
5998
<p>The <c>FlagList</c> parameter is a list of options.
5999
The following options are allowed:</p>
6001
<tag><c>global</c></tag>
6003
<p>Turn on or off call tracing for global function calls
6004
(that is, calls specifying the module explicitly). Only
6005
exported functions will match and only global calls will
6006
generate trace messages. This is the default.</p>
6008
<tag><c>local</c></tag>
6010
<p>Turn on or off call tracing for all types of function
6011
calls. Trace messages will be sent whenever any of
6012
the specified functions are called, regardless of how they
6013
are called. If the <c>return_to</c> flag is set for
6014
the process, a <c>return_to</c> message will also be sent
6015
when this function returns to its caller.</p>
6017
<tag><c>meta | {meta, Pid}</c></tag>
6019
<p>Turn on or off meta tracing for all types of function
6020
calls. Trace messages will be sent to the tracer process
6021
or port <c>Pid</c> whenever any of the specified
6022
functions are called, regardless of how they are called.
6023
If no <c>Pid</c> is specified, <c>self()</c> is used as a
6024
default tracer process.</p>
6025
<p>Meta tracing traces all processes and does not care
6026
about the process trace flags set by <c>trace/3</c>,
6027
the trace flags are instead fixed to
6028
<c>[call, timestamp]</c>.</p>
6029
<p>The match spec function <c>{return_trace}</c> works with
6030
meta trace and send its trace message to the same tracer
6033
<tag><c>call_count</c></tag>
6035
<p>Starts (<c>MatchSpec == true</c>) or stops
6036
(<c>MatchSpec == false</c>) call count tracing for all
6037
types of function calls. For every function a counter is
6038
incremented when the function is called, in any process.
6039
No process trace flags need to be activated.</p>
6040
<p>If call count tracing is started while already running,
6041
the count is restarted from zero. Running counters can be
6042
paused with <c>MatchSpec == pause</c>. Paused and running
6043
counters can be restarted from zero with
6044
<c>MatchSpec == restart</c>.</p>
6045
<p>The counter value can be read with
6046
<seealso marker="#erlang:trace_info/2">erlang:trace_info/2</seealso>.</p>
6049
<p>The <c>global</c> and <c>local</c> options are mutually
6050
exclusive and <c>global</c> is the default (if no options are
6051
specified). The <c>call_count</c> and <c>meta</c> options
6052
perform a kind of local tracing, and can also not be combined
6053
with <c>global</c>. A function can be either globally or
6054
locally traced. If global tracing is specified for a
6055
specified set of functions; local, meta and call count
6056
tracing for the matching set of local functions will be
6057
disabled, and vice versa.</p>
6058
<p>When disabling trace, the option must match the type of trace
6059
that is set on the function, so that local tracing must be
6060
disabled with the <c>local</c> option and global tracing with
6061
the <c>global</c> option (or no option at all), and so forth.</p>
6062
<p>There is no way to directly change part of a match
6063
specification list. If a function has a match specification,
6064
you can replace it with a completely new one. If you need to
6065
change an existing match specification, use the
6066
<seealso marker="#erlang:trace_info/2">erlang:trace_info/2</seealso>
6067
BIF to retrieve the existing match specification.</p>
6068
<p>Returns the number of exported functions that matched
6069
the <c>MFA</c> argument. This will be zero if none matched at
6074
<name>trunc(Number) -> int()</name>
6075
<fsummary>Return an integer by the truncating a number</fsummary>
6077
<v>Number = number()</v>
6080
<p>Returns an integer by the truncating <c>Number</c>.</p>
6082
> <input>trunc(5.5).</input>
6084
<p>Allowed in guard tests.</p>
6088
<name>tuple_size(Tuple) -> int()</name>
6089
<fsummary>Return the size of a tuple</fsummary>
6091
<v>Tuple = tuple()</v>
6094
<p>Returns an integer which is the number of elements in <c>Tuple</c>.</p>
6096
> <input>tuple_size({morni, mulle, bwange}).</input>
6098
<p>Allowed in guard tests.</p>
6102
<name>tuple_to_list(Tuple) -> [term()]</name>
6103
<fsummary>Convert a tuple to a list</fsummary>
6105
<v>Tuple = tuple()</v>
6108
<p>Returns a list which corresponds to <c>Tuple</c>.
6109
<c>Tuple</c> may contain any Erlang terms.</p>
6111
> <input>tuple_to_list({share, {'Ericsson_B', 163}}).</input>
6112
[share,{'Ericsson_B',163}]</pre>
6116
<name>erlang:universaltime() -> {Date, Time}</name>
6117
<fsummary>Current date and time according to Universal Time Coordinated (UTC)</fsummary>
6119
<v>Date = {Year, Month, Day}</v>
6120
<v>Time = {Hour, Minute, Second}</v>
6121
<v> Year = Month = Day = Hour = Minute = Second = int()</v>
6124
<p>Returns the current date and time according to Universal
6125
Time Coordinated (UTC), also called GMT, in the form
6126
<c>{{Year, Month, Day}, {Hour, Minute, Second}}</c> if
6127
supported by the underlying operating system. If not,
6128
<c>erlang:universaltime()</c> is equivalent to
6129
<c>erlang:localtime()</c>.</p>
6131
> <input>erlang:universaltime().</input>
6132
{{1996,11,6},{14,18,43}}</pre>
6136
<name>erlang:universaltime_to_localtime({Date1, Time1}) -> {Date2, Time2}</name>
6137
<fsummary>Convert from Universal Time Coordinated (UTC) to local date and time</fsummary>
6139
<v>Date1 = Date2 = {Year, Month, Day}</v>
6140
<v>Time1 = Time2 = {Hour, Minute, Second}</v>
6141
<v> Year = Month = Day = Hour = Minute = Second = int()</v>
6144
<p>Converts Universal Time Coordinated (UTC) date and time to
6145
local date and time, if this is supported by the underlying
6146
OS. Otherwise, no conversion is done, and
6147
<c>{Date1, Time1}</c> is returned.</p>
6149
> <input>erlang:universaltime_to_localtime({{1996,11,6},{14,18,43}}).</input>
6150
{{1996,11,7},{15,18,43}}</pre>
6151
<p>Failure: <c>badarg</c> if <c>Date1</c> or <c>Time1</c> do
6152
not denote a valid date or time.</p>
6156
<name>unlink(Id) -> true</name>
6157
<fsummary>Remove a link, if there is one, to another process or port</fsummary>
6159
<v>Id = pid() | port()</v>
6162
<p>Removes the link, if there is one, between the calling
6163
process and the process or port referred to by <c>Id</c>.</p>
6164
<p>Returns <c>true</c> and does not fail, even if there is no
6165
link to <c>Id</c>, or if <c>Id</c> does not exist.</p>
6166
<p>Once <c>unlink(Id)</c> has returned it is guaranteed that
6167
the link between the caller and the entity referred to by
6168
<c>Id</c> has no effect on the caller in the future (unless
6169
the link is setup again). If caller is trapping exits, an
6170
<c>{'EXIT', Id, _}</c> message due to the link might have
6171
been placed in the callers message queue prior to the call,
6172
though. Note, the <c>{'EXIT', Id, _}</c> message can be the
6173
result of the link, but can also be the result of <c>Id</c>
6174
calling <c>exit/2</c>. Therefore, it <em>may</em> be
6175
appropriate to cleanup the message queue when trapping exits
6176
after the call to <c>unlink(Id)</c>, as follow:</p>
6181
\011{'EXIT', Id, _} ->
6187
<p>Prior to OTP release R11B (erts version 5.5) <c>unlink/1</c>
6188
behaved completely asynchronous, i.e., the link was active
6189
until the "unlink signal" reached the linked entity. This
6190
had one undesirable effect, though. You could never know when
6191
you were guaranteed <em>not</em> to be effected by the link.</p>
6192
<p>Current behavior can be viewed as two combined operations:
6193
asynchronously send an "unlink signal" to the linked entity
6194
and ignore any future results of the link.</p>
6199
<name>unregister(RegName) -> true</name>
6200
<fsummary>Remove the registered name for a process (or port)</fsummary>
6202
<v>RegName = atom()</v>
6205
<p>Removes the registered name <c>RegName</c>, associated with a
6206
pid or a port identifier.</p>
6208
> <input>unregister(db).</input>
6210
<p>Users are advised not to unregister system processes.</p>
6211
<p>Failure: <c>badarg</c> if <c>RegName</c> is not a registered
6216
<name>whereis(RegName) -> pid() | port() | undefined</name>
6217
<fsummary>Get the pid (or port) with a given registered name</fsummary>
6219
<p>Returns the pid or port identifier with the registered name
6220
<c>RegName</c>. Returns <c>undefined</c> if the name is not
6223
> <input>whereis(db).</input>
6228
<name>erlang:yield() -> true</name>
6229
<fsummary>Let other processes get a chance to execute</fsummary>
6231
<p>Voluntarily let other processes (if any) get a chance to
6232
execute. Using <c>erlang:yield()</c> is similar to
6233
<c>receive after 1 -> ok end</c>, except that <c>yield()</c>
added
removed
lib/kernel/doc/src/erlang.xml
