13
13
compliance with the License. You should have received a copy of the
14
14
Erlang Public License along with this software. If not, it can be
15
15
retrieved online at http://www.erlang.org/.
17
17
Software distributed under the License is distributed on an "AS IS"
18
18
basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
19
19
the License for the specific language governing rights and limitations
24
24
<title>erlang</title>
103
103
<p>The following code:</p>
106
Y = adler32(X,Data2).
105
X = erlang:adler32(Data1),
106
Y = erlang:adler32(X,Data2).
108
108
<p>- would assign the same value to <c>Y</c> as this would:</p>
110
Y = adler32([Data1,Data2]).
110
Y = erlang:adler32([Data1,Data2]).
115
<name>adler32_combine(FirstAdler, SecondAdler, SecondSize) -> int()</name>
115
<name>erlang:adler32_combine(FirstAdler, SecondAdler, SecondSize) -> int()</name>
116
116
<fsummary>Combine two adler32 checksums</fsummary>
118
118
<v>FirstAdler = SecondAdler = int()</v>
124
124
the second checksum to be known.</p>
125
125
<p>The following code:</p>
128
Z = adler32(Y,Data2).
127
Y = erlang:adler32(Data1),
128
Z = erlang:adler32(Y,Data2).
130
130
<p>- would assign the same value to <c>Z</c> as this would:</p>
134
Z = adler32_combine(X,Y,iolist_size(Data2)).
132
X = erlang:adler32(Data1),
133
Y = erlang:adler32(Data2),
134
Z = erlang:adler32_combine(X,Y,iolist_size(Data2)).
147
147
<c>Tuple1</c>, and contains the elements in <c>Tuple1</c>
148
148
followed by <c>Term</c> as the last element. Semantically
150
<c>list_to_tuple(tuple_to_list(Tuple ++ [Term])</c>, but much
150
<c>list_to_tuple(tuple_to_list(Tuple) ++ [Term])</c>, but much
153
153
> <input>erlang:append_element({one, two}, three).</input>
256
<name>binary_part(Subject, PosLen) -> binary()</name>
257
<fsummary>Extracts a part of a binary</fsummary>
259
<v>Subject = binary()</v>
260
<v>PosLen = {Start,Length}</v>
262
<v>Length = int()</v>
265
<p>Extracts the part of the binary described by <c>PosLen</c>.</p>
267
<p>Negative length can be used to extract bytes at the end of a binary:</p>
270
1> Bin = <<1,2,3,4,5,6,7,8,9,10>>.
271
2> binary_part(Bin,{byte_size(Bin), -5)).
272
<<6,7,8,9,10>>
275
<p>If <c>PosLen</c> in any way references outside the binary, a <c>badarg</c> exception is raised.</p>
277
<p><c>Start</c> is zero-based, i.e:</p>
279
1> Bin = <<1,2,3>>
280
2> binary_part(Bin,{0,2}).
284
<p>See the STDLIB module <c>binary</c> for details about the <c>PosLen</c> semantics.</p>
286
<p>Allowed in guard tests.</p>
290
<name>binary_part(Subject, Start, Length) -> binary()</name>
291
<fsummary>Extracts a part of a binary</fsummary>
293
<v>Subject = binary()</v>
295
<v>Length = int()</v>
298
<p>The same as <c>binary_part(Subject, {Pos, Len})</c>.</p>
300
<p>Allowed in guard tests.</p>
256
304
<name>binary_to_atom(Binary, Encoding) -> atom()</name>
257
305
<fsummary>Convert from text representation to an atom</fsummary>
318
366
corresponding to the bytes from position <c>Start</c> to
319
367
position <c>Stop</c> in <c>Binary</c>. Positions in the
320
368
binary are numbered starting from 1.</p>
370
<note><p>This function's indexing style of using one-based indices for
371
binaries is deprecated. New code should use the functions in
372
the STDLIB module <c>binary</c> instead. They consequently
373
use the same (zero-based) style of indexing.</p></note>
343
396
<p>Returns an Erlang term which is the result of decoding
344
397
the binary object <c>Binary</c>, which must be encoded
345
according to the Erlang external term format. See also
346
<seealso marker="#term_to_binary/1">term_to_binary/1</seealso>.</p>
398
according to the Erlang external term format.</p>
400
<p>When decoding binaries from untrusted sources, consider using
401
<c>binary_to_term/2</c> to prevent denial of service attacks.</p>
404
<seealso marker="#term_to_binary/1">term_to_binary/1</seealso>
406
<seealso marker="#binary_to_term/2">binary_to_term/2</seealso>.</p>
410
<name>binary_to_term(Binary, Opts) -> term()</name>
411
<fsummary>Decode an Erlang external term format binary</fsummary>
414
<v>Binary = ext_binary()</v>
417
<p>As <c>binary_to_term/1</c>, but takes options that affect decoding
420
<tag><c>safe</c></tag>
422
<p>Use this option when receiving binaries from an untrusted
424
<p>When enabled, it prevents decoding data that may be used to
425
attack the Erlang system. In the event of receiving unsafe
426
data, decoding fails with a badarg error.</p>
427
<p>Currently, this prevents creation of new atoms directly,
428
creation of new atoms indirectly (as they are embedded in
429
certain structures like pids, refs, funs, etc.), and creation of
430
new external function references. None of those resources are
431
currently garbage collected, so unchecked creation of them can
432
exhaust available memory.</p>
435
<p>Failure: <c>badarg</c> if <c>safe</c> is specified and unsafe data
438
<seealso marker="#term_to_binary/1">term_to_binary/1</seealso>,
439
<seealso marker="#binary_to_term/1">binary_to_term/1</seealso>,
440
and <seealso marker="#list_to_existing_atom/1">
441
list_to_existing_atom/1</seealso>.</p>
404
499
<name>erlang:cancel_timer(TimerRef) -> Time | false</name>
405
500
<fsummary>Cancel a timer</fsummary>
407
<v>TimerRef = ref()</v>
502
<v>TimerRef = reference()</v>
408
503
<v>Time = int()</v>
411
506
<p>Cancels a timer, where <c>TimerRef</c> was returned by
413
<seealso marker="#erlang:send_after/3">erlang:send_after/3</seealso>
508
<seealso marker="#send_after/3">erlang:send_after/3</seealso>
415
<seealso marker="#erlang:start_timer/3">erlang:start_timer/3</seealso>.
510
<seealso marker="#start_timer/3">erlang:start_timer/3</seealso>.
416
511
If the timer is there to be removed, the function returns
417
512
the time in milliseconds left until the timer would have expired,
418
513
otherwise <c>false</c> (which means that <c>TimerRef</c> was
419
514
never a timer, that it has already been cancelled, or that it
420
515
has already delivered its message).</p>
422
<seealso marker="#erlang:send_after/3">erlang:send_after/3</seealso>,
423
<seealso marker="#erlang:start_timer/3">erlang:start_timer/3</seealso>,
517
<seealso marker="#send_after/3">erlang:send_after/3</seealso>,
518
<seealso marker="#start_timer/3">erlang:start_timer/3</seealso>,
425
<seealso marker="#erlang:read_timer/1">erlang:read_timer/1</seealso>.</p>
520
<seealso marker="#read_timer/1">erlang:read_timer/1</seealso>.</p>
426
521
<p>Note: Cancelling a timer does not guarantee that the message
427
522
has not already been delivered to the message queue.</p>
481
576
<p>The following code:</p>
578
X = erlang:crc32(Data1),
579
Y = erlang:crc32(X,Data2).
486
581
<p>- would assign the same value to <c>Y</c> as this would:</p>
488
Y = crc32([Data1,Data2]).
583
Y = erlang:crc32([Data1,Data2]).
493
<name>crc32_combine(FirstCrc, SecondCrc, SecondSize) -> int()</name>
588
<name>erlang:crc32_combine(FirstCrc, SecondCrc, SecondSize) -> int()</name>
494
589
<fsummary>Combine two crc32 (IEEE 802.3) checksums</fsummary>
496
591
<v>FirstCrc = SecondCrc = int()</v>
502
597
the second checksum to be known.</p>
503
598
<p>The following code:</p>
600
Y = erlang:crc32(Data1),
601
Z = erlang:crc32(Y,Data2).
508
603
<p>- would assign the same value to <c>Z</c> as this would:</p>
512
Z = crc32_combine(X,Y,iolist_size(Data2)).
605
X = erlang:crc32(Data1),
606
Y = erlang:crc32(Data2),
607
Z = erlang:crc32_combine(X,Y,iolist_size(Data2)).
532
<name>decode_packet(Type,Bin,Options) -> {ok,Packet,Rest} | {more,Length} | {error,Reason}</name>
627
<name>erlang:decode_packet(Type,Bin,Options) -> {ok,Packet,Rest} | {more,Length} | {error,Reason}</name>
533
628
<fsummary>Extracts a protocol packet from a binary</fsummary>
535
630
<v>Bin = binary()</v>
668
<name>erlang:demonitor(MonitorRef) -> true</name>
763
<name>demonitor(MonitorRef) -> true</name>
669
764
<fsummary>Stop monitoring</fsummary>
671
<v>MonitorRef = ref()</v>
766
<v>MonitorRef = reference()</v>
674
769
<p>If <c>MonitorRef</c> is a reference which the calling process
675
770
obtained by calling
676
<seealso marker="#erlang:monitor/2">erlang:monitor/2</seealso>,
771
<seealso marker="#monitor/2">monitor/2</seealso>,
677
772
this monitoring is turned off. If the monitoring is already
678
773
turned off, nothing happens.</p>
679
<p>Once <c>erlang:demonitor(MonitorRef)</c> has returned it is
774
<p>Once <c>demonitor(MonitorRef)</c> has returned it is
680
775
guaranteed that no <c>{'DOWN', MonitorRef, _, _, _}</c> message
681
776
due to the monitor will be placed in the callers message queue
682
777
in the future. A <c>{'DOWN', MonitorRef, _, _, _}</c> message
684
779
the call, though. Therefore, in most cases, it is advisable
685
780
to remove such a <c>'DOWN'</c> message from the message queue
686
781
after monitoring has been stopped.
687
<seealso marker="#erlang:demonitor/2">erlang:demonitor(MonitorRef, [flush])</seealso> can be used instead of
688
<c>erlang:demonitor(MonitorRef)</c> if this cleanup is wanted.</p>
782
<seealso marker="#demonitor/2">demonitor(MonitorRef, [flush])</seealso> can be used instead of
783
<c>demonitor(MonitorRef)</c> if this cleanup is wanted.</p>
690
<p>Prior to OTP release R11B (erts version 5.5) <c>erlang:demonitor/1</c>
785
<p>Prior to OTP release R11B (erts version 5.5) <c>demonitor/1</c>
691
786
behaved completely asynchronous, i.e., the monitor was active
692
787
until the "demonitor signal" reached the monitored entity. This
693
788
had one undesirable effect, though. You could never know when
708
<name>erlang:demonitor(MonitorRef, OptionList) -> true|false</name>
803
<name>demonitor(MonitorRef, OptionList) -> true|false</name>
709
804
<fsummary>Stop monitoring</fsummary>
711
<v>MonitorRef = ref()</v>
806
<v>MonitorRef = reference()</v>
712
807
<v>OptionList = [Option]</v>
713
808
<v>Option = flush</v>
714
809
<v>Option = info</v>
717
812
<p>The returned value is <c>true</c> unless <c>info</c> is part
718
813
of <c>OptionList</c>.
720
<p><c>erlang:demonitor(MonitorRef, [])</c> is equivalent to
721
<seealso marker="#erlang:demonitor/1">erlang:demonitor(MonitorRef)</seealso>.</p>
815
<p><c>demonitor(MonitorRef, [])</c> is equivalent to
816
<seealso marker="#demonitor/1">demonitor(MonitorRef)</seealso>.</p>
722
817
<p>Currently the following <c>Option</c>s are valid:</p>
724
819
<tag><c>flush</c></tag>
726
821
<p>Remove (one) <c>{_, MonitorRef, _, _, _}</c> message,
727
822
if there is one, from the callers message queue after
728
823
monitoring has been stopped.</p>
729
<p>Calling <c>erlang:demonitor(MonitorRef, [flush])</c>
824
<p>Calling <c>demonitor(MonitorRef, [flush])</c>
730
825
is equivalent to the following, but more efficient:</p>
731
826
<code type="none">
733
erlang:demonitor(MonitorRef),
828
demonitor(MonitorRef),
735
\011{_, MonitorRef, _, _, _} ->
830
{_, MonitorRef, _, _, _} ->
741
836
<tag><c>info</c></tag>
862
957
function first). Since evaluating this function causes
863
958
the process to terminate, it has no return value.</p>
865
> <input>catch erlang:error(foobar).</input>
960
> <input>catch error(foobar).</input>
866
961
{'EXIT',{foobar,[{erl_eval,do_apply,5},
867
962
{erl_eval,expr,5},
1233
1328
returns, for example:</p>
1234
1329
<p><c>{'EXIT',{badarg,Stacktrace}} = catch abs(x)</c></p>
1236
<seealso marker="#erlang:error/1">erlang:error/1</seealso> and
1237
<seealso marker="#erlang:error/2">erlang:error/2</seealso>.</p>
1331
<seealso marker="#error/1">erlang:error/1</seealso> and
1332
<seealso marker="#error/2">erlang:error/2</seealso>.</p>
1847
1942
<p>Returns an integer whose text representation in base
1848
1943
<c>Base</c> is <c>String</c>.</p>
1850
> <input>erlang:list_to_integer("3FF", 16).</input>
1945
> <input>list_to_integer("3FF", 16).</input>
1852
1947
<p>Failure: <c>badarg</c> if <c>String</c> contains a bad
1853
1948
representation of an integer.</p>
1939
2034
<v>Text = string()</v>
1943
<p>This BIF is currently introduced as an experimental
1944
feature. The interface may be changed in any way in future
2038
<p>In releases older than OTP R14B, NIFs were an
2039
experimental feature. Versions of OTP older than R14B might
2040
have different and possibly incompatible NIF semantics and
2041
interfaces. For example, in R13B03 the return value on
2043
<c>{error,Reason,Text}</c>.</p>
1947
2045
<p>Loads and links a dynamic library containing native
1948
2046
implemented functions (NIFs) for a module. <c>Path</c> is a
1949
2047
file path to the sharable object/dynamic library file minus
1950
the OS-dependant file extension (.so for Unix and .ddl for
2048
the OS-dependent file extension (.so for Unix and .dll for
1951
2049
Windows). See <seealso marker="erl_nif">erl_nif</seealso>
1952
2050
on how to implement a NIF library.</p>
1953
2051
<p><c>LoadInfo</c> can be any term. It will be passed on to
1957
2055
<p>The call to <c>load_nif/2</c> must be made
1958
2056
<em>directly</em> from the Erlang code of the module that the
1959
2057
NIF library belongs to.</p>
1960
<p>It returns either <c>ok</c>, or <c>{error,Reason,Text}</c>
2058
<p>It returns either <c>ok</c>, or <c>{error,{Reason,Text}}</c>
1961
2059
if loading fails. <c>Reason</c> is one of the atoms below,
1962
2060
while <c>Text</c> is a human readable string that may give
1963
some more information about the failure:</p>
2061
some more information about the failure.</p>
1965
2063
<tag><c>load_failed</c></tag>
2282
2380
other. Values beginning with an uppercase letter is not part
2283
2381
of the result.</p>
2284
2382
<code type="none">
2285
\011total = processes + system
2286
\011processes = processes_used + ProcessesNotUsed
2287
\011system = atom + binary + code + ets + OtherSystem
2288
\011atom = atom_used + AtomNotUsed
2383
total = processes + system
2384
processes = processes_used + ProcessesNotUsed
2385
system = atom + binary + code + ets + OtherSystem
2386
atom = atom_used + AtomNotUsed
2290
\011RealTotal = processes + RealSystem
2291
\011RealSystem = system + MissedSystem</code>
2388
RealTotal = processes + RealSystem
2389
RealSystem = system + MissedSystem</code>
2292
2390
<p>More tuples in the returned list may be added in the future.</p>
2294
2392
<p>The <c>total</c> value is supposed to be the total amount
2361
<seealso marker="#erlang:memory/0">erlang:memory/0</seealso>.</p>
2459
<seealso marker="#memory/0">erlang:memory/0</seealso>.</p>
2365
<name>erlang:min(Term1, Term2) -> Minimum</name>
2463
<name>min(Term1, Term2) -> Minimum</name>
2366
2464
<fsummary>Return the smallest of two term</fsummary>
2368
2466
<v>Term1 = Term2 = Minimum = term()</v>
2427
2525
<p>When a process is monitored by registered name, the process
2428
2526
that has the registered name at the time when
2429
<c>erlang:monitor/2</c> is called will be monitored.
2527
<c>monitor/2</c> is called will be monitored.
2430
2528
The monitor will not be effected, if the registered name is
2431
2529
unregistered.</p>
2463
<p>If/when <c>erlang:monitor/2</c> is extended (e.g. to
2561
<p>If/when <c>monitor/2</c> is extended (e.g. to
2464
2562
handle other item types than <c>process</c>), other
2465
2563
possible values for <c>Object</c>, and <c>Info</c> in the
2466
2564
<c>'DOWN'</c> message will be introduced.</p>
2468
2566
<p>The monitoring is turned off either when the <c>'DOWN'</c>
2469
2567
message is sent, or when
2470
<seealso marker="#erlang:demonitor/1">erlang:demonitor/1</seealso>
2568
<seealso marker="#demonitor/1">demonitor/1</seealso>
2472
2570
<p>If an attempt is made to monitor a process on an older node
2473
2571
(where remote process monitoring is not implemented or one
2474
2572
where remote process monitoring by registered name is not
2475
2573
implemented), the call fails with <c>badarg</c>.</p>
2476
<p>Making several calls to <c>erlang:monitor/2</c> for the same
2574
<p>Making several calls to <c>monitor/2</c> for the same
2477
2575
<c>Item</c> is not an error; it results in as many, completely
2478
2576
independent, monitorings.</p>
2649
<name>erlang:nif_error(Reason)</name>
2650
<fsummary>Stop execution with a given reason</fsummary>
2652
<v>Reason = term()</v>
2655
<p>Works exactly like
2656
<seealso marker="#error/1">erlang:error/1</seealso>,
2657
but Dialyzer thinks that this BIF will return an arbitrary term.
2658
When used in a stub function for a NIF to generate an
2659
exception when the NIF library is not loaded, Dialyzer
2660
will not generate false warnings.</p>
2664
<name>erlang:nif_error(Reason, Args)</name>
2665
<fsummary>Stop execution with a given reason</fsummary>
2667
<v>Reason = term()</v>
2668
<v>Args = [term()]</v>
2671
<p>Works exactly like
2672
<seealso marker="#error/2">erlang:error/2</seealso>,
2673
but Dialyzer thinks that this BIF will return an arbitrary term.
2674
When used in a stub function for a NIF to generate an
2675
exception when the NIF library is not loaded, Dialyzer
2676
will not generate false warnings.</p>
2551
2680
<name>node() -> Node</name>
2552
2681
<fsummary>Name of the local node</fsummary>
2640
2769
Otherwise, some other point in time is chosen. It is also
2641
2770
guaranteed that subsequent calls to this BIF returns
2642
2771
continuously increasing values. Hence, the return value from
2643
<c>now()</c> can be used to generate unique time-stamps. It
2644
can only be used to check the local time of day if
2772
<c>now()</c> can be used to generate unique time-stamps,
2773
and if it is called in a tight loop on a fast machine
2774
the time of the node can become skewed.</p>
2775
<p>It can only be used to check the local time of day if
2645
2776
the time-zone info of the underlying operating system is
2646
2777
properly configured.</p>
2650
2781
<name>open_port(PortName, PortSettings) -> port()</name>
2651
2782
<fsummary>Open a port</fsummary>
2653
<v>PortName = {spawn, Command} | {spawn_driver, Command} | {spawn_executable, Command} | {fd, In, Out}</v>
2784
<v>PortName = {spawn, Command} | {spawn_driver, Command} | {spawn_executable, FileName} | {fd, In, Out}</v>
2654
2785
<v> Command = string()</v>
2786
<v> FileName = [ FileNameChar ] | binary()</v>
2787
<v> FileNameChar = int() (1..255 or any Unicode codepoint, see description)</v>
2655
2788
<v> In = Out = int()</v>
2656
2789
<v>PortSettings = [Opt]</v>
2657
<v> Opt = {packet, N} | stream | {line, L} | {cd, Dir} | {env, Env} | {args, [ string() ]} | {arg0, string()} | exit_status | use_stdio | nouse_stdio | stderr_to_stdout | in | out | binary | eof</v>
2790
<v> Opt = {packet, N} | stream | {line, L} | {cd, Dir} | {env, Env} | {args, [ ArgString ]} | {arg0, ArgString} | exit_status | use_stdio | nouse_stdio | stderr_to_stdout | in | out | binary | eof</v>
2658
2791
<v> N = 1 | 2 | 4</v>
2659
2792
<v> L = int()</v>
2660
2793
<v> Dir = string()</v>
2794
<v> ArgString = [ FileNameChar ] | binary()</v>
2661
2795
<v> Env = [{Name, Val}]</v>
2662
2796
<v> Name = string()</v>
2663
2797
<v> Val = string() | false</v>
2708
2842
<p>Works like <c>{spawn, Command}</c>, but only runs
2709
external executables. The <c>Command</c> in it's whole
2843
external executables. The <c>Command</c> in its whole
2710
2844
is used as the name of the executable, including any
2711
2845
spaces. If arguments are to be passed, the
2712
2846
<c>args</c> and <c>arg0</c> <c>PortSettings</c> can be used.</p>
2720
2854
executed, the appropriate command interpreter will
2721
2855
implicitly be invoked, but there will still be no
2722
2856
command argument expansion or implicit PATH search.</p>
2858
<p>The name of the executable as well as the arguments
2859
given in <c>args</c> and <c>arg0</c> is subject to
2860
Unicode file name translation if the system is running
2861
in Unicode file name mode. To avoid
2862
translation or force i.e. UTF-8, supply the executable
2863
and/or arguments as a binary in the correct
2864
encoding. See the <seealso
2865
marker="kernel:file">file</seealso> module, the
2866
<seealso marker="kernel:file#native_name_encoding/0">
2867
file:native_name_encoding/0</seealso> function and the
2868
<seealso marker="stdlib:unicode_usage">stdlib users guide
2869
</seealso> for details.</p>
2871
<note>The characters in the name (if given as a list)
2872
can only be > 255 if the Erlang VM is started in
2873
Unicode file name translation mode, otherwise the name
2874
of the executable is limited to the ISO-latin-1
2875
character set.</note>
2724
2877
<p>If the <c>Command</c> cannot be run, an error
2725
2878
exception, with the posix error code as the reason, is
2726
2879
raised. The error reason may differ between operating
2823
2976
should not be given in this list. The proper executable name will
2824
2977
automatically be used as argv[0] where applicable.</p>
2979
<p>When the Erlang VM is running in Unicode file name
2980
mode, the arguments can contain any Unicode characters and
2981
will be translated into whatever is appropriate on the
2982
underlying OS, which means UTF-8 for all platforms except
2983
Windows, which has other (more transparent) ways of
2984
dealing with Unicode arguments to programs. To avoid
2985
Unicode translation of arguments, they can be supplied as
2986
binaries in whatever encoding is deemed appropriate.</p>
2988
<note>The characters in the arguments (if given as a
2989
list of characters) can only be > 255 if the Erlang
2990
VM is started in Unicode file name mode,
2991
otherwise the arguments are limited to the
2992
ISO-latin-1 character set.</note>
2826
2994
<p>If one, for any reason, wants to explicitly set the
2827
2995
program name in the argument vector, the <c>arg0</c>
2828
2996
option can be used.</p>
2883
3054
The standard input and standard output handles of the port program
2884
3055
will, if this option is supplied, be opened with the flag
2885
3056
FILE_FLAG_OVERLAPPED, so that the port program can (and has to) do
2886
overlapped I/O on it's standard handles. This is not normally
3057
overlapped I/O on its standard handles. This is not normally
2887
3058
the case for simple port programs, but an option of value for the
2888
3059
experienced Windows programmer. <em>On all other platforms, this
2889
3060
option is silently discarded</em>.</p>
3336
3503
registered name, [] is returned.</p>
3337
3504
<p>For valid values of <c>Item</c>, and corresponding
3338
3505
values of <c>Info</c>, see
3339
<seealso marker="#erlang:port_info/1">erlang:port_info/1</seealso>.</p>
3506
<seealso marker="#port_info/1">erlang:port_info/1</seealso>.</p>
3340
3507
<p>Failure: <c>badarg</c> if <c>Port</c> is not a local port.</p>
3426
3593
<p>This changes the minimum heap size for the calling
3429
<tag><c>process_flag(priority, Level)</c></tag>
3431
<marker id="process_flag_priority"></marker>
3596
<tag><c>process_flag(min_bin_vheap_size, MinBinVHeapSize)</c></tag>
3598
<p>This changes the minimum binary virtual heap size for the calling
3601
<tag><marker id="process_flag_priority"><c>process_flag(priority, Level)</c></marker></tag>
3432
3603
<p>This sets the process priority. <c>Level</c> is an atom.
3433
3604
There are currently four priority levels: <c>low</c>,
3434
3605
<c>normal</c>, <c>high</c>, and <c>max</c>. The default
3757
3928
<p><c>MessageQueue</c> is a list of the messages to
3758
3929
the process, which have not yet been processed.</p>
3931
<tag><c>{min_heap_size, MinHeapSize}</c></tag>
3933
<p><c>MinHeapSize</c> is the minimum heap size for the process.</p>
3935
<tag><c>{min_bin_vheap_size, MinBinVHeapSize}</c></tag>
3937
<p><c>MinBinVHeapSize</c> is the minimum binary virtual heap size for the process.</p>
3760
3939
<tag><c>{monitored_by, Pids}</c></tag>
3762
3941
<p>A list of pids that are monitoring the process (with
3763
<c>erlang:monitor/2</c>).</p>
3942
<c>monitor/2</c>).</p>
3765
3944
<tag><c>{monitors, Monitors}</c></tag>
3767
<p>A list of monitors (started by <c>erlang:monitor/2</c>)
3946
<p>A list of monitors (started by <c>monitor/2</c>)
3768
3947
that are active for the process. For a local process
3769
3948
monitor or a remote process monitor by pid, the list item
3770
3949
is <c>{process, Pid}</c>, and for a remote process
3801
3980
<tag><c>{status, Status}</c></tag>
3803
3982
<p><c>Status</c> is the status of the process. <c>Status</c>
3804
is <c>waiting</c> (waiting for a message), <c>running</c>,
3983
is <c>exiting</c>, <c>garbage_collecting</c>,
3984
<c>waiting</c> (for a message), <c>running</c>,
3805
3985
<c>runnable</c> (ready to run, but another process is
3806
3986
running), or <c>suspended</c> (suspended on a "busy" port
3807
3987
or by the <c>erlang:suspend_process/[1,2]</c> BIF).</p>
3812
3992
ActiveSuspendCount, OutstandingSuspendCount}</c> tuples.
3813
3993
<c>Suspendee</c> is the pid of a process that have been or is to
3814
3994
be suspended by the process identified by <c>Pid</c> via the
3815
<seealso marker="#erlang:suspend_process/2">erlang:suspend_process/2</seealso>
3995
<seealso marker="#suspend_process/2">erlang:suspend_process/2</seealso>
3817
<seealso marker="#erlang:suspend_process/1">erlang:suspend_process/1</seealso>
3997
<seealso marker="#suspend_process/1">erlang:suspend_process/1</seealso>
3818
3998
BIF. <c>ActiveSuspendCount</c> is the number of times the
3819
3999
<c>Suspendee</c> has been suspended by <c>Pid</c>.
3820
4000
<c>OutstandingSuspendCount</c> is the number of not yet
3953
4133
terminate, it has no return value - unless the arguments are
3954
4134
invalid, in which case the function <em>returns the error reason</em>, that is <c>badarg</c>. If you want to be
3955
4135
really sure not to return you can call
3956
<c>erlang:error(erlang:raise(Class, Reason, Stacktrace))</c>
4136
<c>error(erlang:raise(Class, Reason, Stacktrace))</c>
3957
4137
and hope to distinguish exceptions later.</p>
3961
4141
<name>erlang:read_timer(TimerRef) -> int() | false</name>
3962
4142
<fsummary>Number of milliseconds remaining for a timer</fsummary>
3964
<v>TimerRef = ref()</v>
4144
<v>TimerRef = reference()</v>
3967
4147
<p><c>TimerRef</c> is a timer reference returned by
3968
<seealso marker="#erlang:send_after/3">erlang:send_after/3</seealso>
4148
<seealso marker="#send_after/3">erlang:send_after/3</seealso>
3970
<seealso marker="#erlang:start_timer/3">erlang:start_timer/3</seealso>.
4150
<seealso marker="#start_timer/3">erlang:start_timer/3</seealso>.
3971
4151
If the timer is active, the function returns the time in
3972
4152
milliseconds left until the timer will expire, otherwise
3973
4153
<c>false</c> (which means that <c>TimerRef</c> was never a
3974
4154
timer, that it has been cancelled, or that it has already
3975
4155
delivered its message).</p>
3977
<seealso marker="#erlang:send_after/3">erlang:send_after/3</seealso>,
3978
<seealso marker="#erlang:start_timer/3">erlang:start_timer/3</seealso>,
4157
<seealso marker="#send_after/3">erlang:send_after/3</seealso>,
4158
<seealso marker="#start_timer/3">erlang:start_timer/3</seealso>,
3980
<seealso marker="#erlang:cancel_timer/1">erlang:cancel_timer/1</seealso>.</p>
4160
<seealso marker="#cancel_timer/1">erlang:cancel_timer/1</seealso>.</p>
3984
4164
<name>erlang:ref_to_list(Ref) -> string()</name>
3985
4165
<fsummary>Text representation of a reference</fsummary>
4167
<v>Ref = reference()</v>
3990
4170
<p>Returns a string which corresponds to the text
4042
4222
<p>Decreases the suspend count on the process identified by
4043
4223
<c>Suspendee</c>. <c>Suspendee</c> should previously have been
4045
<seealso marker="#erlang:suspend_process/2">erlang:suspend_process/2</seealso>,
4225
<seealso marker="#suspend_process/2">erlang:suspend_process/2</seealso>,
4047
<seealso marker="#erlang:suspend_process/1">erlang:suspend_process/1</seealso>
4227
<seealso marker="#suspend_process/1">erlang:suspend_process/1</seealso>
4048
4228
by the process calling <c>erlang:resume_process(Suspendee)</c>. When
4049
4229
the suspend count on <c>Suspendee</c> reach zero, <c>Suspendee</c>
4050
4230
will be resumed, i.e., the state of the <c>Suspendee</c> is changed
4130
4310
<p>Sends a message and returns <c>ok</c>, or does not send
4131
4311
the message but returns something else (see below). Otherwise
4133
<seealso marker="#erlang:send/2">erlang:send/2</seealso>. See
4313
<seealso marker="#send/2">erlang:send/2</seealso>. See
4135
<seealso marker="#erlang:send_nosuspend/2">erlang:send_nosuspend/2,3</seealso>.
4315
<seealso marker="#send_nosuspend/2">erlang:send_nosuspend/2,3</seealso>.
4136
4316
for more detailed explanation and warnings.</p>
4137
4317
<p>The possible options are:</p>
4178
4358
erts version 5.4.11. Note that timers will not be
4179
4359
automatically canceled when <c>Dest</c> is an atom.</p>
4181
<seealso marker="#erlang:start_timer/3">erlang:start_timer/3</seealso>,
4182
<seealso marker="#erlang:cancel_timer/1">erlang:cancel_timer/1</seealso>,
4361
<seealso marker="#start_timer/3">erlang:start_timer/3</seealso>,
4362
<seealso marker="#cancel_timer/1">erlang:cancel_timer/1</seealso>,
4184
<seealso marker="#erlang:read_timer/1">erlang:read_timer/1</seealso>.</p>
4364
<seealso marker="#read_timer/1">erlang:read_timer/1</seealso>.</p>
4185
4365
<p>Failure: <c>badarg</c> if the arguments does not satisfy
4186
4366
the requirements specified above.</p>
4200
<seealso marker="#erlang:send/3">erlang:send(Dest, Msg, [nosuspend])</seealso>, but returns <c>true</c> if
4380
<seealso marker="#send/3">erlang:send(Dest, Msg, [nosuspend])</seealso>, but returns <c>true</c> if
4201
4381
the message was sent and <c>false</c> if the message was not
4202
4382
sent because the sender would have had to be suspended.</p>
4203
4383
<p>This function is intended for send operations towards an
4252
<seealso marker="#erlang:send/3">erlang:send(Dest, Msg, [nosuspend | Options])</seealso>,
4432
<seealso marker="#send/3">erlang:send(Dest, Msg, [nosuspend | Options])</seealso>,
4253
4433
but with boolean return value.</p>
4254
4434
<p>This function behaves like
4255
<seealso marker="#erlang:send_nosuspend/2">erlang:send_nosuspend/2)</seealso>,
4435
<seealso marker="#send_nosuspend/2">erlang:send_nosuspend/2)</seealso>,
4256
4436
but takes a third parameter, a list of options. The only
4257
4437
currently implemented option is <c>noconnect</c>. The option
4258
4438
<c>noconnect</c> makes the function return <c>false</c> if
4490
4670
<fsummary>Create a new process with a fun as entry point</fsummary>
4492
4672
<v>Fun = fun()</v>
4493
<v>Option = link | monitor | {priority, Level} | {fullsweep_after, Number} | {min_heap_size, Size}</v>
4673
<v>Option = link | monitor | {priority, Level} | {fullsweep_after, Number} | {min_heap_size, Size} | {min_bin_vheap_size, VSize}</v>
4494
4674
<v> Level = low | normal | high</v>
4495
4675
<v> Number = int()</v>
4496
4676
<v> Size = int()</v>
4677
<v> VSize = int()</v>
4499
4680
<p>Returns the pid of a new process started by the application
4512
4693
<v>Node = node()</v>
4513
4694
<v>Fun = fun()</v>
4514
<v>Option = link | {priority, Level} | {fullsweep_after, Number} | {min_heap_size, Size}</v>
4695
<v>Option = link | {priority, Level} | {fullsweep_after, Number} | {min_heap_size, Size} | {min_bin_vheap_size, VSize}</v>
4515
4696
<v> Level = low | normal | high</v>
4516
4697
<v> Number = int()</v>
4517
4698
<v> Size = int()</v>
4699
<v> VSize = int()</v>
4520
4702
<p>Returns the pid of a new process started by the application
4531
4713
<v>Module = Function = atom()</v>
4532
4714
<v>Args = [term()]</v>
4533
<v>Option = link | monitor | {priority, Level} | {fullsweep_after, Number} | {min_heap_size, Size}</v>
4715
<v>Option = link | monitor | {priority, Level} | {fullsweep_after, Number} | {min_heap_size, Size} | {min_bin_vheap_size, VSize}</v>
4534
4716
<v> Level = low | normal | high</v>
4535
4717
<v> Number = int()</v>
4536
4718
<v> Size = int()</v>
4719
<v> VSize = int()</v>
4539
4722
<p>Works exactly like
4594
4777
and no virtual memory, one might want to preserve memory
4595
4778
by setting <c>Number</c> to zero. (The value may be set
4597
<seealso marker="#erlang:system_flag/2">erlang:system_flag/2</seealso>.)</p>
4780
<seealso marker="#system_flag/2">erlang:system_flag/2</seealso>.)</p>
4599
4782
<tag><c>{min_heap_size, Size}</c></tag>
4613
4796
fine-tuning an application and to measure the execution
4614
4797
time with various <c>Size</c> values.</p>
4799
<tag><c>{min_bin_vheap_size, VSize}</c></tag>
4801
<p>This option is only useful for performance tuning.
4802
In general, you should not use this option unless you
4803
know that there is problem with execution times and/or
4804
memory consumption, and you should measure to make sure
4805
that the option improved matters.
4807
<p>Gives a minimum binary virtual heap size in words. Setting this value
4808
higher than the system default might speed up some
4809
processes because less garbage collection is done.
4810
Setting too high value, however, might waste memory.
4811
Therefore, it is recommended to use this option only for
4812
fine-tuning an application and to measure the execution
4813
time with various <c>VSize</c> values.</p>
4623
4823
<v>Node = node()</v>
4624
4824
<v>Module = Function = atom()</v>
4625
4825
<v>Args = [term()]</v>
4626
<v>Option = link | {priority, Level} | {fullsweep_after, Number} | {min_heap_size, Size}</v>
4826
<v>Option = link | {priority, Level} | {fullsweep_after, Number} | {min_heap_size, Size} | {min_bin_vheap_size, VSize}</v>
4627
4827
<v> Level = low | normal | high</v>
4628
4828
<v> Number = int()</v>
4629
4829
<v> Size = int()</v>
4830
<v> VSize = int()</v>
4632
4833
<p>Returns the pid of a new process started by the application
4687
4888
erts version 5.4.11. Note that timers will not be
4688
4889
automatically canceled when <c>Dest</c> is an atom.</p>
4690
<seealso marker="#erlang:send_after/3">erlang:send_after/3</seealso>,
4691
<seealso marker="#erlang:cancel_timer/1">erlang:cancel_timer/1</seealso>,
4891
<seealso marker="#send_after/3">erlang:send_after/3</seealso>,
4892
<seealso marker="#cancel_timer/1">erlang:cancel_timer/1</seealso>,
4693
<seealso marker="#erlang:read_timer/1">erlang:read_timer/1</seealso>.</p>
4894
<seealso marker="#read_timer/1">erlang:read_timer/1</seealso>.</p>
4694
4895
<p>Failure: <c>badarg</c> if the arguments does not satisfy
4695
4896
the requirements specified above.</p>
4711
4912
<c>ContextSwitches</c> is the total number of context
4712
4913
switches since the system started.</p>
4714
<tag><c>exact_reductions</c></tag>
4915
<tag><marker id="statistics_exact_reductions"><c>exact_reductions</c></marker></tag>
4716
<marker id="statistics_exact_reductions"></marker>
4718
4918
<c>{Total_Exact_Reductions, Exact_Reductions_Since_Last_Call}</c>.</p>
4719
4919
<p><em>NOTE:</em><c>statistics(exact_reductions)</c> is
4733
4933
through ports, and <c>Output</c> is the total number of
4734
4934
bytes output to ports.</p>
4736
<tag><c>reductions</c></tag>
4936
<tag><marker id="statistics_reductions"><c>reductions</c></marker></tag>
4738
<marker id="statistics_reductions"></marker>
4740
4939
<c>{Total_Reductions, Reductions_Since_Last_Call}</c>.</p>
4741
4940
<p><em>NOTE:</em> From erts version 5.5 (OTP release R11B)
4795
4994
process will not leave the suspended state until its suspend
4796
4995
count reach zero. The suspend count of <c>Suspendee</c> is
4798
<seealso marker="#erlang:resume_process/1">erlang:resume_process(Suspendee)</seealso>
4997
<seealso marker="#resume_process/1">erlang:resume_process(Suspendee)</seealso>
4799
4998
is called by the same process that called
4800
4999
<c>erlang:suspend_process(Suspendee)</c>. All increased suspend
4801
5000
counts on other processes acquired by a process will automatically be
4885
5084
<p>Suspends the process identified by <c>Suspendee</c>. The
4886
5085
same as calling
4887
<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>.
5086
<seealso marker="#suspend_process/2">erlang:suspend_process(Suspendee, [])</seealso>. For more information see the documentation of <seealso marker="#suspend_process/2">erlang:suspend_process/2</seealso>.
4890
5089
<p>This BIF is intended for debugging only.</p>
4906
5105
<p>Sets the maximum depth of call stack back-traces in the
4907
5106
exit reason element of <c>'EXIT'</c> tuples.</p>
4909
<tag><c>erlang:system_flag(cpu_topology, CpuTopology)</c></tag>
5108
<tag><marker id="system_flag_cpu_topology"><c>erlang:system_flag(cpu_topology, CpuTopology)</c></marker></tag>
4911
<marker id="system_flag_cpu_topology"></marker>
4912
5110
<p>Sets the user defined <c>CpuTopology</c>. The user defined
4913
5111
CPU topology will override any automatically detected
4914
5112
CPU topology. By passing <c>undefined</c> as <c>CpuTopology</c>
4959
5157
<seealso marker="#spawn_opt/4">spawn_opt/N</seealso> or
4960
5158
<seealso marker="#process_flag/2">process_flag/2</seealso>. </p>
4962
<tag><c>erlang:system_flag(multi_scheduling, BlockState)</c></tag>
4964
<marker id="system_flag_multi_scheduling"></marker>
5160
<tag><c>erlang:system_flag(min_bin_vheap_size, MinBinVHeapSize)</c></tag>
5162
<p>Sets the default minimum binary virtual heap size for processes. The
5163
size is given in words. The new <c>min_bin_vhheap_size</c> only
5164
effects processes spawned after the change of
5165
<c>min_bin_vhheap_size</c> has been made.
5166
The <c>min_bin_vheap_size</c> can be set for individual
5168
<seealso marker="#spawn_opt/4">spawn_opt/N</seealso> or
5169
<seealso marker="#process_flag/2">process_flag/2</seealso>. </p>
5171
<tag><marker id="system_flag_multi_scheduling"><c>erlang:system_flag(multi_scheduling, BlockState)</c></marker></tag>
4965
5173
<p><c>BlockState = block | unblock</c></p>
4966
5174
<p>If multi-scheduling is enabled, more than one scheduler
4967
5175
thread is used by the emulator. Multi-scheduling can be
4995
5203
<seealso marker="#system_info_multi_scheduling_blockers">erlang:system_info(multi_scheduling_blockers)</seealso>, and
4996
5204
<seealso marker="#system_info_schedulers">erlang:system_info(schedulers)</seealso>.</p>
4998
<tag><c>erlang:system_flag(scheduler_bind_type, How)</c></tag>
5206
<tag><marker id="system_flag_scheduler_bind_type"><c>erlang:system_flag(scheduler_bind_type, How)</c></marker></tag>
5000
<marker id="system_flag_scheduler_bind_type"></marker>
5001
5208
<p>Controls if and how schedulers are bound to logical
5002
5209
processors.</p>
5003
5210
<p>When <c>erlang:system_flag(scheduler_bind_type, How)</c> is
5011
5218
schedulers actually have bound as requested, call
5012
5219
<seealso marker="#system_info_scheduler_bindings">erlang:system_info(scheduler_bindings)</seealso>.
5014
<p>Schedulers can currently only be bound on newer Linux
5015
and Solaris systems, but more systems will be supported
5221
<p>Schedulers can currently only be bound on newer Linux,
5222
Solaris, FreeBSD, and Windows systems, but more systems will be
5223
supported in the future.
5018
5225
<p>In order for the runtime system to be able to bind schedulers,
5019
5226
the CPU topology needs to be known. If the runtime system fails
5021
5228
For more information on how to define the CPU topology, see
5022
5229
<seealso marker="#system_flag_cpu_topology">erlang:system_flag(cpu_topology, CpuTopology)</seealso>.
5024
<p><em>NOTE:</em> If other programs on the system have bound
5025
to processors, e.g. another Erlang runtime system, you
5026
may loose performance when binding schedulers. Therefore,
5027
schedulers are by default not bound.</p>
5231
<p>The runtime system will by default bind schedulers to logical
5232
processors using the <c>default_bind</c> bind type if the amount
5233
of schedulers are at least equal to the amount of logical
5234
processors configured, binding of schedulers is supported,
5235
and a CPU topology is available at startup.
5237
<p><em>NOTE:</em> If the Erlang runtime system is the only
5238
operating system process that binds threads to logical processors,
5239
this improves the performance of the runtime system. However,
5240
if other operating system processes (as for example another Erlang
5241
runtime system) also bind threads to logical processors, there
5242
might be a performance penalty instead. If this is the case you,
5243
are are advised to unbind the schedulers using the
5244
<seealso marker="erl#+sbt">+sbtu</seealso> command line argument,
5245
or <c>erlang:system_flag(scheduler_bind_type, unbound)</c>.</p>
5028
5246
<p>Schedulers can be bound in different ways. The <c>How</c>
5029
5247
argument determines how schedulers are bound. <c>How</c> can
5030
5248
currently be one of:</p>
5124
5342
<seealso marker="#system_flag_cpu_topology">erlang:system_flag(cpu_topology, CpuTopology)</seealso>.
5127
<tag><c>erlang:system_flag(schedulers_online, SchedulersOnline)</c></tag>
5345
<tag><marker id="system_flag_schedulers_online"><c>erlang:system_flag(schedulers_online, SchedulersOnline)</c></marker></tag>
5129
<marker id="system_flag_schedulers_online"></marker>
5130
5347
<p>Sets the amount of schedulers online. Valid range is
5131
5348
<![CDATA[1 <= SchedulerId <= erlang:system_info(schedulers)]]>.
5164
5381
<p>Returns various information about the current system
5165
5382
(emulator) as specified by <c>Type</c>:</p>
5167
<tag><c>allocated_areas</c></tag>
5384
<tag><marker id="system_info_allocated_areas"><c>allocated_areas</c></marker></tag>
5169
<marker id="system_info_allocated_areas"></marker>
5170
5386
<p>Returns a list of tuples with information about
5171
5387
miscellaneous allocated memory areas.</p>
5172
5388
<p>Each tuple contains an atom describing type of memory as
5184
5400
Some values are part of other values, and some memory
5185
5401
areas are not part of the result. If you are interested
5186
5402
in the total amount of memory allocated by the emulator
5187
see <seealso marker="#erlang:memory/0">erlang:memory/0,1</seealso>.</p>
5403
see <seealso marker="#memory/0">erlang:memory/0,1</seealso>.</p>
5189
<tag><c>allocator</c></tag>
5405
<tag><marker id="system_info_allocator"><c>allocator</c></marker></tag>
5191
<marker id="system_info_allocator"></marker>
5192
5407
<p>Returns <c>{Allocator, Version, Features, Settings}.</c></p>
5194
5409
<list type="bulleted">
5195
<item><c>Allocator = undefined | elib_malloc | glibc</c></item>
5410
<item><c>Allocator = undefined | glibc</c></item>
5196
5411
<item><c>Version = [int()]</c></item>
5197
5412
<item><c>Features = [atom()]</c></item>
5198
5413
<item><c>Settings = [{Subsystem, [{Parameter, Value}]}]</c></item>
5207
5422
implementation used. If <c>Allocator</c> equals
5208
5423
<c>undefined</c>, the <c>malloc()</c> implementation
5209
5424
used could not be identified. Currently
5210
<c>elib_malloc</c> and <c>glibc</c> can be identified.</p>
5425
<c>glibc</c> can be identified.</p>
5213
5428
<p><c>Version</c> is a list of integers (but not a
5229
5444
<p>See also "System Flags Effecting erts_alloc" in
5230
5445
<seealso marker="erts:erts_alloc#flags">erts_alloc(3)</seealso>.</p>
5232
<tag><c>alloc_util_allocators</c></tag>
5447
<tag><marker id="system_info_alloc_util_allocators"><c>alloc_util_allocators</c></marker></tag>
5234
<marker id="system_info_alloc_util_allocators"></marker>
5235
5449
<p>Returns a list of the names of all allocators
5236
5450
using the ERTS internal <c>alloc_util</c> framework
5237
5451
as atoms. For more information see the
5240
5454
erts_alloc(3)</seealso> documentation.
5243
<tag><c>{allocator, Alloc}</c></tag>
5457
<tag><marker id="system_info_allocator_tuple"><c>{allocator, Alloc}</c></marker></tag>
5245
<marker id="system_info_allocator_tuple"></marker>
5246
5459
<p>Returns information about the specified allocator.
5247
5460
As of erts version 5.6.1 the return value is a list
5248
5461
of <c>{instance, InstanceNo, InstanceInfo}</c> tuples
5278
5491
values. The first value is memory pool size and
5279
5492
the second value used memory size.</p>
5281
<tag><c>{allocator_sizes, Alloc}</c></tag>
5494
<tag><marker id="system_info_allocator_sizes"><c>{allocator_sizes, Alloc}</c></marker></tag>
5283
<marker id="system_info_allocator_sizes"></marker>
5284
5496
<p>Returns various size information for the specified
5285
5497
allocator. The information returned is a subset of the
5286
5498
information returned by
5287
5499
<seealso marker="#system_info_allocator_tuple">erlang:system_info({allocator, Alloc})</seealso>.
5502
<tag><c>build_type</c></tag>
5504
<p>Returns an atom describing the build type of the runtime
5505
system. This is normally the atom <c>opt</c> for optimized.
5506
Other possible return values are <c>debug</c>, <c>purify</c>,
5507
<c>quantify</c>, <c>purecov</c>, <c>gcov</c>, <c>valgrind</c>,
5508
<c>gprof</c>, and <c>lcnt</c>. Possible return values
5509
may be added and/or removed at any time without prior notice.
5290
5512
<tag><c>c_compiler_used</c></tag>
5292
5514
<p>Returns a two-tuple describing the C compiler used when
5314
5536
line flag <c>+R</c>, see
5315
5537
<seealso marker="erts:erl#compat_rel">erl(1)</seealso>.</p>
5317
<tag><c>cpu_topology</c></tag>
5539
<tag><marker id="system_info_cpu_topology"><c>cpu_topology</c></marker></tag>
5319
<marker id="system_info_cpu_topology"></marker>
5320
5541
<p>Returns the <c>CpuTopology</c> which currently is used by the
5321
5542
emulator. The CPU topology is used when binding schedulers
5322
5543
to logical processors. The CPU topology used is the user defined
5365
5586
<c>CpuTopology</c> type to change.
5368
<tag><c>{cpu_topology, defined}</c></tag>
5589
<tag><marker id="system_info_cpu_topology_defined"><c>{cpu_topology, defined}</c></marker></tag>
5370
5591
<p>Returns the user defined <c>CpuTopology</c>. For more
5371
5592
information see the documentation of
5378
<tag><c>{cpu_topology, detected}</c></tag>
5599
<tag><marker id="system_info_cpu_topology_detected"><c>{cpu_topology, detected}</c></marker></tag>
5380
5601
<p>Returns the automatically detected <c>CpuTopology</c>. The
5381
5602
emulator currently only detects the CPU topology on some newer
5382
linux and solaris systems. For more information see the
5383
documentation of the
5603
Linux, Solaris, FreeBSD, and Windows systems. On Windows system with
5604
more than 32 logical processors the CPU topology is not detected.
5606
<p>For more information see the documentation of the
5384
5607
<seealso marker="#system_info_cpu_topology">cpu_topology</seealso>
5439
5662
<tag><c>elib_malloc</c></tag>
5441
<p>If the emulator uses the <c>elib_malloc</c> memory
5442
allocator, a list of two-element tuples containing status
5443
information is returned; otherwise, <c>false</c> is
5444
returned. The list currently contains the following
5445
two-element tuples (all sizes are presented in bytes):</p>
5447
<tag><c>{heap_size, Size}</c></tag>
5449
<p>Where <c>Size</c> is the current heap size.</p>
5451
<tag><c>{max_alloced_size, Size}</c></tag>
5453
<p>Where <c>Size</c> is the maximum amount of memory
5454
allocated on the heap since the emulator started.</p>
5456
<tag><c>{alloced_size, Size}</c></tag>
5458
<p>Where <c>Size</c> is the current amount of memory
5459
allocated on the heap.</p>
5461
<tag><c>{free_size, Size}</c></tag>
5463
<p>Where <c>Size</c> is the current amount of free
5464
memory on the heap.</p>
5466
<tag><c>{no_alloced_blocks, No}</c></tag>
5468
<p>Where <c>No</c> is the current number of allocated
5469
blocks on the heap.</p>
5471
<tag><c>{no_free_blocks, No}</c></tag>
5473
<p>Where <c>No</c> is the current number of free blocks
5476
<tag><c>{smallest_alloced_block, Size}</c></tag>
5478
<p>Where <c>Size</c> is the size of the smallest
5479
allocated block on the heap.</p>
5481
<tag><c>{largest_free_block, Size}</c></tag>
5483
<p>Where <c>Size</c> is the size of the largest free
5484
block on the heap.</p>
5664
<p>This option will be removed in a future release.
5665
The return value will always be <c>false</c> since
5666
the elib_malloc allocator has been removed.</p>
5668
<tag><marker id="system_info_dist_buf_busy_limit"><c>dist_buf_busy_limit</c></marker></tag>
5670
<p>Returns the value of the distribution buffer busy limit
5671
in bytes. This limit can be set on startup by passing the
5672
<seealso marker="erl#+zdbbl">+zdbbl</seealso> command line
5673
flag to <c>erl</c>.</p>
5488
5675
<tag><c>fullsweep_after</c></tag>
5499
5686
<c>spawn</c> or <c>spawn_link</c> will use these
5500
5687
garbage collection settings. The default settings can be
5501
5688
changed by use of
5502
<seealso marker="#erlang:system_flag/2">system_flag/2</seealso>.
5689
<seealso marker="#system_flag/2">system_flag/2</seealso>.
5503
5690
<seealso marker="#spawn_opt/4">spawn_opt/4</seealso>
5504
5691
can spawn a process that does not use the default
5559
5746
information see the <seealso marker="erts:crash_dump">"How to interpret the Erlang crash dumps"</seealso> chapter
5560
5747
in the ERTS User's Guide.</p>
5562
<tag><c>logical_processors</c></tag>
5564
<p>Returns the number of logical processors detected on the
5565
system as an integer or the atom <c>unknown</c> if the
5566
emulator wasn't able to detect any.
5749
<tag><marker id="logical_processors"><c>logical_processors</c></marker></tag>
5751
<p>Returns the detected number of logical processors configured
5752
on the system. The return value is either an integer, or
5753
the atom <c>unknown</c> if the emulator wasn't able to
5754
detect logical processors configured.
5757
<tag><marker id="logical_processors_available"><c>logical_processors_available</c></marker></tag>
5759
<p>Returns the detected number of logical processors available to
5760
the Erlang runtime system. The return value is either an
5761
integer, or the atom <c>unknown</c> if the emulator wasn't
5762
able to detect logical processors available. The number
5763
of logical processors available is less than or equal to
5764
the number of <seealso marker="#logical_processors_online">logical
5765
processors online</seealso>.
5768
<tag><marker id="logical_processors_online"><c>logical_processors_online</c></marker></tag>
5770
<p>Returns the detected number of logical processors online on
5771
the system. The return value is either an integer,
5772
or the atom <c>unknown</c> if the emulator wasn't able to
5773
detect logical processors online. The number of logical
5774
processors online is less than or equal to the number of
5775
<seealso marker="#logical_processors">logical processors
5776
configured</seealso>.
5569
5779
<tag><c>machine</c></tag>
5571
5781
<p>Returns a string containing the Erlang machine name.</p>
5783
<tag><c>min_heap_size</c></tag>
5785
<p>Returns <c>{min_heap_size, MinHeapSize}</c> where <c>MinHeapSize</c> is the current system wide
5786
minimum heap size for spawned processes.</p>
5788
<tag><c>min_bin_vheap_size</c></tag>
5790
<p>Returns <c>{min_bin_vheap_size, MinBinVHeapSize}</c> where <c>MinBinVHeapSize</c> is the current system wide
5791
minimum binary virtual heap size for spawned processes.</p>
5573
5793
<tag><c>modified_timing_level</c></tag>
5575
5795
<p>Returns the modified timing level (an integer) if
5579
5799
<seealso marker="erts:erl#+T">erl(1)</seealso>
5580
5800
command for more information on modified timing.</p>
5582
<tag><c>multi_scheduling</c></tag>
5802
<tag><marker id="system_info_multi_scheduling"><c>multi_scheduling</c></marker></tag>
5584
<marker id="system_info_multi_scheduling"></marker>
5585
5804
<p>Returns <c>disabled</c>, <c>blocked</c>, or <c>enabled</c>.
5586
5805
A description of the return values:</p>
5610
5829
<seealso marker="#system_info_multi_scheduling_blockers">erlang:system_info(multi_scheduling_blockers)</seealso>, and
5611
5830
<seealso marker="#system_info_schedulers">erlang:system_info(schedulers)</seealso>.</p>
5613
<tag><c>multi_scheduling_blockers</c></tag>
5832
<tag><marker id="system_info_multi_scheduling_blockers"><c>multi_scheduling_blockers</c></marker></tag>
5615
<marker id="system_info_multi_scheduling_blockers"></marker>
5616
5834
<p>Returns a list of <c>PID</c>s when multi-scheduling
5617
5835
is blocked; otherwise, the empty list. The <c>PID</c>s
5618
5836
in the list is <c>PID</c>s of the processes currently
5623
5841
<seealso marker="#system_info_multi_scheduling">erlang:system_info(multi_scheduling)</seealso>, and
5624
5842
<seealso marker="#system_info_schedulers">erlang:system_info(schedulers)</seealso>.</p>
5626
<tag><c>otp_release</c></tag>
5844
<tag><marker id="system_info_otp_release"><c>otp_release</c></marker></tag>
5628
<marker id="system_info_otp_release"></marker>
5629
5846
<p>Returns a string containing the OTP release number.</p>
5631
5848
<tag><c>process_count</c></tag>
5649
5866
information see the <seealso marker="erts:crash_dump">"How to interpret the Erlang crash dumps"</seealso> chapter
5650
5867
in the ERTS User's Guide.</p>
5652
<tag><c>scheduler_bind_type</c></tag>
5869
<tag><marker id="system_info_scheduler_bind_type"><c>scheduler_bind_type</c></marker></tag>
5654
<marker id="system_info_scheduler_bind_type"></marker>
5655
5871
<p>Returns information on how user has requested
5656
5872
schedulers to be bound or not bound.</p>
5657
5873
<p><em>NOTE:</em> Even though user has requested
5666
5882
<seealso marker="#system_info_scheduler_bindings">erlang:system_info(scheduler_bindings)</seealso>.
5669
<tag><c>scheduler_bindings</c></tag>
5885
<tag><marker id="system_info_scheduler_bindings"><c>scheduler_bindings</c></marker></tag>
5671
<marker id="system_info_scheduler_bindings"></marker>
5672
5887
<p>Returns information on currently used scheduler
5674
5889
<p>A tuple of a size equal to
5690
5905
<seealso marker="#system_info_schedulers_online">erlang:system_info(schedulers_online)</seealso>.
5693
<tag><c>scheduler_id</c></tag>
5908
<tag><marker id="system_info_scheduler_id"><c>scheduler_id</c></marker></tag>
5695
<marker id="system_info_scheduler_id"></marker>
5696
5910
<p>Returns the scheduler id (<c>SchedulerId</c>) of the
5697
5911
scheduler thread that the calling process is executing
5698
5912
on. <c>SchedulerId</c> is a positive integer; where
5699
5913
<c><![CDATA[1 <= SchedulerId <= erlang:system_info(schedulers)]]></c>. See also
5700
5914
<seealso marker="#system_info_schedulers">erlang:system_info(schedulers)</seealso>.</p>
5702
<tag><c>schedulers</c></tag>
5916
<tag><marker id="system_info_schedulers"><c>schedulers</c></marker></tag>
5704
<marker id="system_info_schedulers"></marker>
5705
5918
<p>Returns the number of scheduler threads used by
5706
5919
the emulator. Scheduler threads online schedules Erlang
5707
5920
processes and Erlang ports, and execute Erlang code
5717
5930
<seealso marker="#system_info_multi_scheduling">erlang:system_info(multi_scheduling)</seealso>, and
5718
5931
and <seealso marker="#system_info_multi_scheduling_blockers">erlang:system_info(multi_scheduling_blockers)</seealso>.</p>
5720
<tag><c>schedulers_online</c></tag>
5933
<tag><marker id="system_info_schedulers_online"><c>schedulers_online</c></marker></tag>
5722
<marker id="system_info_schedulers_online"></marker>
5723
5935
<p>Returns the amount of schedulers online. The scheduler
5724
5936
identifiers of schedulers online satisfy the following
5752
5964
with thread support; otherwise, <c>false</c> is
5755
<tag><c>thread_pool_size</c></tag>
5967
<tag><marker id="system_info_thread_pool_size"><c>thread_pool_size</c></marker></tag>
5757
<marker id="system_info_thread_pool_size"></marker>
5758
5969
<p>Returns the number of async threads in the async thread
5759
5970
pool used for asynchronous driver calls
5760
5971
(<seealso marker="erts:erl_driver#driver_async">driver_async()</seealso>)
5767
5978
<c>get_tcw</c> in "Match Specifications in Erlang",
5768
5979
<seealso marker="erts:match_spec#get_tcw">ERTS User's Guide</seealso>.</p>
5770
<tag><c>version</c></tag>
5772
<marker id="system_info_version"></marker>
5981
<tag><marker id="update_cpu_info"><c>update_cpu_info</c></marker></tag>
5983
<p>The runtime system rereads the CPU information available and
5984
updates its internally stored information about the
5985
<seealso marker="#system_info_cpu_topology_detected">detected CPU
5986
topology</seealso> and the amount of logical processors
5987
<seealso marker="#logical_processors">configured</seealso>,
5988
<seealso marker="#logical_processors_online">online</seealso>, and
5989
<seealso marker="#logical_processors_available">available</seealso>.
5990
If the CPU information has changed since the last time it was read,
5991
the atom <c>changed</c> is returned; otherwise, the atom
5992
<c>unchanged</c> is returned. If the CPU information has changed
5993
you probably want to
5994
<seealso marker="#system_flag_schedulers_online">adjust the amount
5995
of schedulers online</seealso>. You typically want to have as
5996
many schedulers online as
5997
<seealso marker="#logical_processors_available">logical processors
5998
available</seealso>.
6001
<tag><marker id="system_info_version"><c>version</c></marker></tag>
5773
6003
<p>Returns a string containing the version number of the
5776
6006
<tag><c>wordsize</c></tag>
5778
<p>Returns the word size in bytes as an integer, i.e. on a
5779
32-bit architecture 4 is returned, and on a 64-bit
5780
architecture 8 is returned.</p>
6008
<p>Same as <c>{wordsize, internal}</c></p>
6010
<tag><c>{wordsize, internal}</c></tag>
6012
<p>Returns the size of Erlang term words in bytes as an
6013
integer, i.e. on a 32-bit architecture 4 is returned,
6014
and on a pure 64-bit architecture 8 is returned. On a
6015
halfword 64-bit emulator, 4 is returned, as the Erlang
6016
terms are stored using a virtual wordsize of half the
6017
systems wordsize.</p>
6019
<tag><c>{wordsize, external}</c></tag>
6021
<p>Returns the true wordsize of the emulator, i.e. the size
6022
of a pointer, in bytes as an integer. On a pure 32-bit
6023
architecture 4 is returned, on both a halfword and pure
6024
64-bit architecture, 8 is returned.</p>
5804
6048
<p>Returns the current system monitoring settings set by
5805
<seealso marker="#erlang:system_monitor/2">erlang:system_monitor/2</seealso>
6049
<seealso marker="#system_monitor/2">erlang:system_monitor/2</seealso>
5806
6050
as <c>{MonitorPid, Options}</c>, or <c>undefined</c> if there
5807
6051
are no settings. The order of the options may be different
5808
6052
from the one that was set.</p>
5820
6064
system performance monitoring settings are cleared.</p>
5821
6065
<p>Calling the function with <c>{MonitorPid, Options}</c> as
5822
6066
argument, is the same as calling
5823
<seealso marker="#erlang:system_monitor/2">erlang:system_monitor(MonitorPid, Options)</seealso>.</p>
6067
<seealso marker="#system_monitor/2">erlang:system_monitor(MonitorPid, Options)</seealso>.</p>
5824
6068
<p>Returns the previous system monitor settings just like
5825
<seealso marker="#erlang:system_monitor/0">erlang:system_monitor/0</seealso>.</p>
6069
<seealso marker="#system_monitor/0">erlang:system_monitor/0</seealso>.</p>
5858
6102
explained in the documentation of the
5859
6103
<seealso marker="#gc_start">gc_start</seealso>
5860
6104
trace message (see
5861
<seealso marker="#erlang:trace/3">erlang:trace/3</seealso>).
6105
<seealso marker="#trace/3">erlang:trace/3</seealso>).
5862
6106
New tuples may be added, and the order of the tuples in
5863
6107
the <c>Info</c> list may be changed at any time without prior
5926
6170
<p>Returns the current system profiling settings set by
5927
<seealso marker="#erlang:system_profile/2">erlang:system_profile/2</seealso>
6171
<seealso marker="#system_profile/2">erlang:system_profile/2</seealso>
5928
6172
as <c>{ProfilerPid, Options}</c>, or <c>undefined</c> if there
5929
6173
are no settings. The order of the options may be different
5930
6174
from the one that was set.</p>
6181
6425
Trace the actual return from a traced function back to
6182
6426
its caller. Only works for functions traced with
6183
6427
the <c>local</c> option to
6184
<seealso marker="#erlang:trace_pattern/3">erlang:trace_pattern/3</seealso>.</p>
6428
<seealso marker="#trace_pattern/3">erlang:trace_pattern/3</seealso>.</p>
6185
6429
<p>The semantics is that a trace message is sent when a
6186
6430
call traced function actually returns, that is, when a
6187
6431
chain of tail recursive calls is ended. There will be
6379
6623
the current function cannot be determined, then the last
6380
6624
element <c>Arity</c> is 0.</p>
6382
<tag><c>{trace, Pid, gc_start, Info}</c></tag>
6626
<tag><marker id="gc_start"><c>{trace, Pid, gc_start, Info}</c></marker></tag>
6384
<marker id="gc_start"></marker>
6385
6628
<p>Sent when garbage collection is about to be started.
6386
6629
<c>Info</c> is a list of two-element tuples, where
6387
6630
the first element is a key, and the second is the value.
6406
6649
<tag><c>mbuf_size</c></tag>
6407
6650
<item>The combined size of message buffers associated with
6408
6651
the process.</item>
6653
<tag><c>bin_vheap_size</c></tag>
6654
<item>The total size of unique off-heap binaries referenced from the process heap.</item>
6655
<tag><c>bin_vheap_block_size</c></tag>
6656
<item>The total size of binaries, in words, allowed in the virtual
6657
heap in the process before doing a garbage collection. </item>
6658
<tag><c>bin_old_vheap_size</c></tag>
6659
<item>The total size of unique off-heap binaries referenced from the process old heap.</item>
6660
<tag><c>bin_vheap_block_size</c></tag>
6661
<item>The total size of binaries, in words, allowed in the virtual
6662
old heap in the process before doing a garbage collection. </item>
6410
6666
<p>All sizes are in words.</p>
6556
6812
<c>true</c> for the pseudo function <c>on_load</c> if call
6557
6813
count tracing is active. Return <c>false</c> otherwise.
6559
<seealso marker="#erlang:trace_pattern/3">erlang:trace_pattern/3</seealso>.</p>
6815
<seealso marker="#trace_pattern/3">erlang:trace_pattern/3</seealso>.</p>
6817
<tag><c>call_time</c></tag>
6819
<p>Return the call time values for this function or
6820
<c>true</c> for the pseudo function <c>on_load</c> if call
6821
time tracing is active. Returns <c>false</c> otherwise.
6822
The call time values returned, <c>[{Pid, Count, S, Us}]</c>,
6823
is a list of each process that has executed the function and its specific counters.
6825
<seealso marker="#trace_pattern/3">erlang:trace_pattern/3</seealso>.</p>
6561
6828
<tag><c>all</c></tag>
6563
6830
<p>Return a list containing the <c>{Item, Value}</c> tuples
6579
6846
<fsummary>Set trace patterns for global call tracing</fsummary>
6582
<seealso marker="#erlang:trace_pattern/3">erlang:trace_pattern(MFA, MatchSpec, [])</seealso>,
6849
<seealso marker="#trace_pattern/3">erlang:trace_pattern(MFA, MatchSpec, [])</seealso>,
6583
6850
retained for backward compatibility.</p>
6593
6860
<p>This BIF is used to enable or disable call tracing for
6594
6861
exported functions. It must be combined with
6595
<seealso marker="#erlang:trace/3">erlang:trace/3</seealso>
6862
<seealso marker="#trace/3">erlang:trace/3</seealso>
6596
6863
to set the <c>call</c> trace flag for one or more processes.</p>
6597
6864
<p>Conceptually, call tracing works like this: Inside
6598
6865
the Erlang virtual machine there is a set of processes to be
6602
6869
in the traced function set, the trace action will be taken.
6603
6870
Otherwise, nothing will happen.</p>
6605
<seealso marker="#erlang:trace/3">erlang:trace/3</seealso> to
6872
<seealso marker="#trace/3">erlang:trace/3</seealso> to
6606
6873
add or remove one or more processes to the set of traced
6607
6874
processes. Use <c>erlang:trace_pattern/2</c> to add or remove
6608
6875
exported functions to the set of traced functions.</p>
6661
6928
<tag><c>restart</c></tag>
6663
<p>For the <c>FlagList</c> option <c>call_count</c>:
6930
<p>For the <c>FlagList</c> option <c>call_count</c> and <c>call_time</c>:
6664
6931
restart the existing counters. The behaviour is undefined
6665
6932
for other <c>FlagList</c> options.</p>
6667
6934
<tag><c>pause</c></tag>
6669
<p>For the <c>FlagList</c> option <c>call_count</c>: pause
6936
<p>For the <c>FlagList</c> option <c>call_count</c> and <c>call_time</c>: pause
6670
6937
the existing counters. The behaviour is undefined for
6671
6938
other <c>FlagList</c> options.</p>
6719
6986
counters can be restarted from zero with
6720
6987
<c>MatchSpec == restart</c>.</p>
6721
6988
<p>The counter value can be read with
6722
<seealso marker="#erlang:trace_info/2">erlang:trace_info/2</seealso>.</p>
6989
<seealso marker="#trace_info/2">erlang:trace_info/2</seealso>.</p>
6991
<tag><c>call_time</c></tag>
6993
<p>Starts (<c>MatchSpec == true</c>) or stops
6994
(<c>MatchSpec == false</c>) call time tracing for all
6995
types of function calls. For every function a counter is
6996
incremented when the function is called. Time spent in the function
6997
is accumulated in two other counters, seconds and micro-seconds.
6998
The counters are stored for each call traced process.</p>
6999
<p>If call time tracing is started while already running,
7000
the count and time is restarted from zero. Running counters can be
7001
paused with <c>MatchSpec == pause</c>. Paused and running
7002
counters can be restarted from zero with
7003
<c>MatchSpec == restart</c>.</p>
7004
<p>The counter value can be read with
7005
<seealso marker="#trace_info/2">erlang:trace_info/2</seealso>.</p>
6725
7009
<p>The <c>global</c> and <c>local</c> options are mutually
6726
7010
exclusive and <c>global</c> is the default (if no options are
6728
7012
perform a kind of local tracing, and can also not be combined
6729
7013
with <c>global</c>. A function can be either globally or
6730
7014
locally traced. If global tracing is specified for a
6731
specified set of functions; local, meta and call count
7015
specified set of functions; local, meta, call time and call count
6732
7016
tracing for the matching set of local functions will be
6733
7017
disabled, and vice versa.</p>
6734
7018
<p>When disabling trace, the option must match the type of trace
6739
7023
specification list. If a function has a match specification,
6740
7024
you can replace it with a completely new one. If you need to
6741
7025
change an existing match specification, use the
6742
<seealso marker="#erlang:trace_info/2">erlang:trace_info/2</seealso>
7026
<seealso marker="#trace_info/2">erlang:trace_info/2</seealso>
6743
7027
BIF to retrieve the existing match specification.</p>
6744
7028
<p>Returns the number of exported functions that matched
6745
7029
the <c>MFA</c> argument. This will be zero if none matched at
added
removed
erts/doc/src/erlang.xml
