1erlang(3) Erlang Module Definition erlang(3)
2
6 erlang - The Erlang BIFs.
7
9 By convention, most Built-In Functions (BIFs) are included in this mod‐
10 ule. Some of the BIFs are viewed more or less as part of the Erlang
11 programming language and are auto-imported. Thus, it is not necessary
12 to specify the module name. For example, the calls atom_to_list(Erlang)
13 and erlang:atom_to_list(Erlang) are identical.
14 Auto-imported BIFs are listed without module prefix. BIFs listed with
16 module prefix are not auto-imported.
17 BIFs can fail for various reasons. All BIFs fail with reason badarg if
19 they are called with arguments of an incorrect type. The other reasons
20 are described in the description of each individual BIF.
21 Some BIFs can be used in guard tests and are marked with "Allowed in
23 guard tests".
24
26 ext_binary()
27 A binary data object, structured according to the Erlang exter‐
29 nal term format.
30 iovec()
32 A list of binaries. This datatype is useful to use together with
34 enif_inspect_iovec.
35 message_queue_data() = off_heap | on_heap
37 See process_flag(message_queue_data, MQD).
39 timestamp() =
41 {MegaSecs :: integer() >= 0,
42 Secs :: integer() >= 0,
43 MicroSecs :: integer() >= 0}
44 See erlang:timestamp/0.
46 time_unit() =
48 integer() >= 1 |
49 second |
50 millisecond |
51 microsecond |
52 nanosecond |
53 native |
54 perf_counter |
55 deprecated_time_unit()
56 Supported time unit representations:
58 PartsPerSecond :: integer() >= 1:
60 Time unit expressed in parts per second. That is, the time
61 unit equals 1/PartsPerSecond second.
62 second:
64 Symbolic representation of the time unit represented by the
65 integer 1.
66 millisecond:
68 Symbolic representation of the time unit represented by the
69 integer 1000.
70 microsecond:
72 Symbolic representation of the time unit represented by the
73 integer 1000000.
74 nanosecond:
76 Symbolic representation of the time unit represented by the
77 integer 1000000000.
78 native:
80 Symbolic representation of the native time unit used by the
81 Erlang runtime system.
82 The native time unit is determined at runtime system start,
84 and remains the same until the runtime system terminates. If
85 a runtime system is stopped and then started again (even on
86 the same machine), the native time unit of the new runtime
87 system instance can differ from the native time unit of the
88 old runtime system instance.
89 One can get an approximation of the native time unit by
91 calling erlang:convert_time_unit(1, second, native). The
92 result equals the number of whole native time units per sec‐
93 ond. If the number of native time units per second does not
94 add up to a whole number, the result is rounded downwards.
95 Note:
97 The value of the native time unit gives you more or less no
98 information about the quality of time values. It sets a limit
99 for the resolution and for the precision of time values, but
100 it gives no information about the accuracy of time values.
101 The resolution of the native time unit and the resolution of
102 time values can differ significantly.
103 perf_counter:
106 Symbolic representation of the performance counter time unit
107 used by the Erlang runtime system.
108 The perf_counter time unit behaves much in the same way as
110 the native time unit. That is, it can differ between runtime
111 restarts. To get values of this type, call
112 os:perf_counter/0.
113 deprecated_time_unit():
115 Deprecated symbolic representations kept for backwards-com‐
116 patibility.
117 The time_unit/0 type can be extended. To convert time values
119 between time units, use erlang:convert_time_unit/3.
120 deprecated_time_unit() =
122 seconds | milli_seconds | micro_seconds | nano_seconds
123 The time_unit() type also consist of the following deprecated
125 symbolic time units:
126 seconds:
128 Same as second.
129 milli_seconds:
131 Same as millisecond.
132 micro_seconds:
134 Same as microsecond.
135 nano_seconds:
137 Same as nanosecond.
138
140 abs(Float) -> float()
141 abs(Int) -> integer() >= 0
143 Types:
145 Int = integer()
147 Types:
149 Float = float()
151 Int = integer()
152 Returns an integer or float that is the arithmetical absolute
154 value of Float or Int, for example:
155 > abs(-3.33).
157 3.33
158 > abs(-3).
159 3
160 Allowed in guard tests.
162 erlang:adler32(Data) -> integer() >= 0
164 Types:
166 Data = iodata()
168 Computes and returns the adler32 checksum for Data.
170 erlang:adler32(OldAdler, Data) -> integer() >= 0
172 Types:
174 OldAdler = integer() >= 0
176 Data = iodata()
177 Continues computing the adler32 checksum by combining the previ‐
179 ous checksum, OldAdler, with the checksum of Data.
180 The following code:
182 X = erlang:adler32(Data1),
184 Y = erlang:adler32(X,Data2).
185 assigns the same value to Y as this:
187 Y = erlang:adler32([Data1,Data2]).
189 erlang:adler32_combine(FirstAdler, SecondAdler, SecondSize) ->
191 integer() >= 0
192 Types:
194 FirstAdler = SecondAdler = SecondSize = integer() >= 0
196 Combines two previously computed adler32 checksums. This compu‐
198 tation requires the size of the data object for the second
199 checksum to be known.
200 The following code:
202 Y = erlang:adler32(Data1),
204 Z = erlang:adler32(Y,Data2).
205 assigns the same value to Z as this:
207 X = erlang:adler32(Data1),
209 Y = erlang:adler32(Data2),
210 Z = erlang:adler32_combine(X,Y,iolist_size(Data2)).
211 erlang:append_element(Tuple1, Term) -> Tuple2
213 Types:
215 Tuple1 = Tuple2 = tuple()
217 Term = term()
218 Returns a new tuple that has one element more than Tuple1, and
220 contains the elements in Tuple1 followed by Term as the last
221 element. Semantically equivalent to
222 list_to_tuple(tuple_to_list(Tuple1) ++ [Term]), but much faster.
223 Example:
224 > erlang:append_element({one, two}, three).
226 {one,two,three}
227 apply(Fun, Args) -> term()
229 Types:
231 Fun = function()
233 Args = [term()]
234 Calls a fun, passing the elements in Args as arguments.
236 If the number of elements in the arguments are known at compile
238 time, the call is better written as Fun(Arg1, Arg2, ... ArgN).
239 Warning:
241 Earlier, Fun could also be specified as {Module, Function},
242 equivalent to apply(Module, Function, Args). This use is depre‐
243 cated and will stop working in a future release.
244 apply(Module, Function, Args) -> term()
247 Types:
249 Module = module()
251 Function = atom()
252 Args = [term()]
253 Returns the result of applying Function in Module to Args. The
255 applied function must be exported from Module. The arity of the
256 function is the length of Args. Example:
257 > apply(lists, reverse, [[a, b, c]]).
259 [c,b,a]
260 > apply(erlang, atom_to_list, ['Erlang']).
261 "Erlang"
262 If the number of arguments are known at compile time, the call
264 is better written as Module:Function(Arg1, Arg2, ..., ArgN).
265 Failure: error_handler:undefined_function/3 is called if the
267 applied function is not exported. The error handler can be rede‐
268 fined (see process_flag/2). If error_handler is undefined, or if
269 the user has redefined the default error_handler so the replace‐
270 ment module is undefined, an error with reason undef is gener‐
271 ated.
272 atom_to_binary(Atom, Encoding) -> binary()
274 Types:
276 Atom = atom()
278 Encoding = latin1 | unicode | utf8
279 Returns a binary corresponding to the text representation of
281 Atom. If Encoding is latin1, one byte exists for each character
282 in the text representation. If Encoding is utf8 or unicode, the
283 characters are encoded using UTF-8 where characters may require
284 multiple bytes.
285 Note:
287 As from Erlang/OTP 20, atoms can contain any Unicode character
288 and atom_to_binary(Atom, latin1) may fail if the text represen‐
289 tation for Atom contains a Unicode character > 255.
290 Example:
293 > atom_to_binary('Erlang', latin1).
295 <<"Erlang">>
296 atom_to_list(Atom) -> string()
298 Types:
300 Atom = atom()
302 Returns a string corresponding to the text representation of
304 Atom, for example:
305 > atom_to_list('Erlang').
307 "Erlang"
308 binary_part(Subject, PosLen) -> binary()
310 Types:
312 Subject = binary()
314 PosLen = {Start :: integer() >= 0, Length :: integer()}
315 Extracts the part of the binary described by PosLen.
317 Negative length can be used to extract bytes at the end of a
319 binary, for example:
320 1> Bin = <<1,2,3,4,5,6,7,8,9,10>>.
322 2> binary_part(Bin,{byte_size(Bin), -5}).
323 <<6,7,8,9,10>>
324 Failure: badarg if PosLen in any way references outside the
326 binary.
327 Start is zero-based, that is:
329 1> Bin = <<1,2,3>>
331 2> binary_part(Bin,{0,2}).
332 <<1,2>>
333 For details about the PosLen semantics, see binary(3).
335 Allowed in guard tests.
337 binary_part(Subject, Start, Length) -> binary()
339 Types:
341 Subject = binary()
343 Start = integer() >= 0
344 Length = integer()
345 The same as binary_part(Subject, {Start, Length}).
347 Allowed in guard tests.
349 binary_to_atom(Binary, Encoding) -> atom()
351 Types:
353 Binary = binary()
355 Encoding = latin1 | unicode | utf8
356 Returns the atom whose text representation is Binary. If Encod‐
358 ing is latin1, no translation of bytes in the binary is done. If
359 Encoding is utf8 or unicode, the binary must contain valid UTF-8
360 sequences.
361 Note:
363 As from Erlang/OTP 20, binary_to_atom(Binary, utf8) is capable
364 of encoding any Unicode character. Earlier versions would fail
365 if the binary contained Unicode characters > 255. For more
366 information about Unicode support in atoms, see the note on
367 UTF-8 encoded atoms in section "External Term Format" in the
368 User's Guide.
369 Examples:
372 > binary_to_atom(<<"Erlang">>, latin1).
374 > binary_to_atom(<<1024/utf8>>, utf8).
375 binary_to_existing_atom(Binary, Encoding) -> atom()
377 Types:
379 Binary = binary()
381 Encoding = latin1 | unicode | utf8
382 As binary_to_atom/2, but the atom must exist.
384 Failure: badarg if the atom does not exist.
386 Note:
388 Note that the compiler may optimize away atoms. For example, the
389 compiler will rewrite atom_to_list(some_atom) to "some_atom". If
390 that expression is the only mention of the atom some_atom in the
391 containing module, the atom will not be created when the module
392 is loaded, and a subsequent call to binary_to_exist‐
393 ing_atom(<<"some_atom">>, utf8) will fail.
394 binary_to_float(Binary) -> float()
397 Types:
399 Binary = binary()
401 Returns the float whose text representation is Binary, for exam‐
403 ple:
404 > binary_to_float(<<"2.2017764e+0">>).
406 2.2017764
407 Failure: badarg if Binary contains a bad representation of a
409 float.
410 binary_to_integer(Binary) -> integer()
412 Types:
414 Binary = binary()
416 Returns an integer whose text representation is Binary, for
418 example:
419 > binary_to_integer(<<"123">>).
421 123
422 Failure: badarg if Binary contains a bad representation of an
424 integer.
425 binary_to_integer(Binary, Base) -> integer()
427 Types:
429 Binary = binary()
431 Base = 2..36
432 Returns an integer whose text representation in base Base is
434 Binary, for example:
435 > binary_to_integer(<<"3FF">>, 16).
437 1023
438 Failure: badarg if Binary contains a bad representation of an
440 integer.
441 binary_to_list(Binary) -> [byte()]
443 Types:
445 Binary = binary()
447 Returns a list of integers corresponding to the bytes of Binary.
449 binary_to_list(Binary, Start, Stop) -> [byte()]
451 Types:
453 Binary = binary()
455 Start = Stop = integer() >= 1
456 1..byte_size(Binary)
457 As binary_to_list/1, but returns a list of integers correspond‐
459 ing to the bytes from position Start to position Stop in Binary.
460 The positions in the binary are numbered starting from 1.
461 Note:
463 The one-based indexing for binaries used by this function is
464 deprecated. New code is to use binary:bin_to_list/3 in STDLIB
465 instead. All functions in module binary consistently use zero-
466 based indexing.
467 binary_to_term(Binary) -> term()
470 Types:
472 Binary = ext_binary()
474 Returns an Erlang term that is the result of decoding binary
476 object Binary, which must be encoded according to the Erlang
477 external term format.
478 > Bin = term_to_binary(hello).
480 <<131,100,0,5,104,101,108,108,111>>
481 > hello = binary_to_term(Bin).
482 hello
483 Warning:
486 When decoding binaries from untrusted sources, consider using
487 binary_to_term/2 to prevent Denial of Service attacks.
488 See also term_to_binary/1 and binary_to_term/2.
491 binary_to_term(Binary, Opts) -> term()
493 Types:
495 Binary = ext_binary()
497 Opts = [safe]
498 As binary_to_term/1, but takes options that affect decoding of
500 the binary.
501 Option:
503 safe:
505 Use this option when receiving binaries from an untrusted
506 source.
507 When enabled, it prevents decoding data that can be used to
509 attack the Erlang system. In the event of receiving unsafe
510 data, decoding fails with a badarg error.
511 This prevents creation of new atoms directly, creation of
513 new atoms indirectly (as they are embedded in certain struc‐
514 tures, such as process identifiers, refs, and funs), and
515 creation of new external function references. None of those
516 resources are garbage collected, so unchecked creation of
517 them can exhaust available memory.
518 Failure: badarg if safe is specified and unsafe data is decoded.
520 > binary_to_term(<<131,100,0,5,104,101,108,108,111>>, [safe]).
522 ** exception error: bad argument
523 > hello.
524 hello
525 > binary_to_term(<<131,100,0,5,104,101,108,108,111>>, [safe]).
526 hello
527 See also term_to_binary/1, binary_to_term/1, and list_to_exist‐
530 ing_atom/1.
531 bit_size(Bitstring) -> integer() >= 0
533 Types:
535 Bitstring = bitstring()
537 Returns an integer that is the size in bits of Bitstring, for
539 example:
540 > bit_size(<<433:16,3:3>>).
542 19
543 > bit_size(<<1,2,3>>).
544 24
545 Allowed in guard tests.
547 bitstring_to_list(Bitstring) -> [byte() | bitstring()]
549 Types:
551 Bitstring = bitstring()
553 Returns a list of integers corresponding to the bytes of Bit‐
555 string. If the number of bits in the binary is not divisible by
556 8, the last element of the list is a bitstring containing the
557 remaining 1-7 bits.
558 erlang:bump_reductions(Reductions) -> true
560 Types:
562 Reductions = integer() >= 1
564 This implementation-dependent function increments the reduction
566 counter for the calling process. In the Beam emulator, the
567 reduction counter is normally incremented by one for each func‐
568 tion and BIF call. A context switch is forced when the counter
569 reaches the maximum number of reductions for a process (2000
570 reductions in Erlang/OTP R12B).
571 Warning:
573 This BIF can be removed in a future version of the Beam machine
574 without prior warning. It is unlikely to be implemented in other
575 Erlang implementations.
576 byte_size(Bitstring) -> integer() >= 0
579 Types:
581 Bitstring = bitstring()
583 Returns an integer that is the number of bytes needed to contain
585 Bitstring. That is, if the number of bits in Bitstring is not
586 divisible by 8, the resulting number of bytes is rounded up.
587 Examples:
588 > byte_size(<<433:16,3:3>>).
590 3
591 > byte_size(<<1,2,3>>).
592 3
593 Allowed in guard tests.
595 erlang:cancel_timer(TimerRef) -> Result
597 Types:
599 TimerRef = reference()
601 Time = integer() >= 0
602 Result = Time | false
603 Cancels a timer. The same as calling erlang:cancel_timer(Timer‐
605 Ref, []).
606 erlang:cancel_timer(TimerRef, Options) -> Result | ok
608 Types:
610 TimerRef = reference()
612 Async = Info = boolean()
613 Option = {async, Async} | {info, Info}
614 Options = [Option]
615 Time = integer() >= 0
616 Result = Time | false
617 Cancels a timer that has been created by erlang:start_timer or
619 erlang:send_after. TimerRef identifies the timer, and was
620 returned by the BIF that created the timer.
621 Options:
623 {async, Async}:
625 Asynchronous request for cancellation. Async defaults to
626 false, which causes the cancellation to be performed syn‐
627 chronously. When Async is set to true, the cancel operation
628 is performed asynchronously. That is, cancel_timer() sends
629 an asynchronous request for cancellation to the timer ser‐
630 vice that manages the timer, and then returns ok.
631 {info, Info}:
633 Requests information about the Result of the cancellation.
634 Info defaults to true, which means the Result is given. When
635 Info is set to false, no information about the result of the
636 cancellation is given.
637 * When Async is false: if Info is true, the Result is
639 returned by erlang:cancel_timer(). otherwise ok is
640 returned.
641 * When Async is true: if Info is true, a message on the form
643 {cancel_timer, TimerRef, Result} is sent to the caller of
644 erlang:cancel_timer() when the cancellation operation has
645 been performed, otherwise no message is sent.
646 More Options may be added in the future.
648 If Result is an integer, it represents the time in milliseconds
650 left until the canceled timer would have expired.
651 If Result is false, a timer corresponding to TimerRef could not
653 be found. This can be either because the timer had expired,
654 already had been canceled, or because TimerRef never corre‐
655 sponded to a timer. Even if the timer had expired, it does not
656 tell you if the time-out message has arrived at its destination
657 yet.
658 Note:
660 The timer service that manages the timer can be co-located with
661 another scheduler than the scheduler that the calling process is
662 executing on. If so, communication with the timer service takes
663 much longer time than if it is located locally. If the calling
664 process is in critical path, and can do other things while wait‐
665 ing for the result of this operation, or is not interested in
666 the result of the operation, you want to use option {async,
667 true}. If using option {async, false}, the calling process
668 blocks until the operation has been performed.
669 See also erlang:send_after/4, erlang:start_timer/4, and
672 erlang:read_timer/2.
673 ceil(Number) -> integer()
675 Types:
677 Number = number()
679 Returns the smallest integer not less than Number. For example:
681 > ceil(5.5).
683 6
684 Allowed in guard tests.
686 check_old_code(Module) -> boolean()
688 Types:
690 Module = module()
692 Returns true if Module has old code, otherwise false.
694 See also code(3).
696 check_process_code(Pid, Module) -> CheckResult
698 Types:
700 Pid = pid()
702 Module = module()
703 CheckResult = boolean()
704 The same as check_process_code(Pid, Module, []).
706 check_process_code(Pid, Module, OptionList) -> CheckResult | async
708 Types:
710 Pid = pid()
712 Module = module()
713 RequestId = term()
714 Option = {async, RequestId} | {allow_gc, boolean()}
715 OptionList = [Option]
716 CheckResult = boolean() | aborted
717 Checks if the node local process identified by Pid executes old
719 code for Module.
720 Options:
722 {allow_gc, boolean()}:
724 Determines if garbage collection is allowed when performing
725 the operation. If {allow_gc, false} is passed, and a garbage
726 collection is needed to determine the result of the opera‐
727 tion, the operation is aborted (see information on CheckRe‐
728 sult below). The default is to allow garbage collection,
729 that is, {allow_gc, true}.
730 {async, RequestId}:
732 The function check_process_code/3 returns the value async
733 immediately after the request has been sent. When the
734 request has been processed, the process that called this
735 function is passed a message on the form
736 {check_process_code, RequestId, CheckResult}.
737 If Pid equals self(), and no async option has been passed, the
739 operation is performed at once. Otherwise a request for the
740 operation is sent to the process identified by Pid, and is han‐
741 dled when appropriate. If no async option has been passed, the
742 caller blocks until CheckResult is available and can be
743 returned.
744 CheckResult informs about the result of the request as follows:
746 true:
748 The process identified by Pid executes old code for Module.
749 That is, the current call of the process executes old code
750 for this module, or the process has references to old code
751 for this module, or the process contains funs that refer‐
752 ences old code for this module.
753 false:
755 The process identified by Pid does not execute old code for
756 Module.
757 aborted:
759 The operation was aborted, as the process needed to be
760 garbage collected to determine the operation result, and the
761 operation was requested by passing option {allow_gc, false}.
762 Note:
764 Up until ERTS version 8.*, the check process code operation
765 checks for all types of references to the old code. That is,
766 direct references (e.g. return addresses on the process stack),
767 indirect references (funs in process context), and references to
768 literals in the code.
769 As of ERTS version 9.0, the check process code operation only
771 checks for direct references to the code. Indirect references
772 via funs will be ignored. If such funs exist and are used after
773 a purge of the old code, an exception will be raised upon usage
774 (same as the case when the fun is received by the process after
775 the purge). Literals will be taken care of (copied) at a later
776 stage. This behavior can as of ERTS version 8.1 be enabled when
777 building OTP, and will automatically be enabled if dirty sched‐
778 uler support is enabled.
779 See also code(3).
782 Failures:
784 badarg:
786 If Pid is not a node local process identifier.
787 badarg:
789 If Module is not an atom.
790 badarg:
792 If OptionList is an invalid list of options.
793 erlang:convert_time_unit(Time, FromUnit, ToUnit) -> ConvertedTime
795 Types:
797 Time = ConvertedTime = integer()
799 FromUnit = ToUnit = time_unit()
800 Converts the Time value of time unit FromUnit to the correspond‐
802 ing ConvertedTime value of time unit ToUnit. The result is
803 rounded using the floor function.
804 Warning:
806 You can lose accuracy and precision when converting between time
807 units. To minimize such loss, collect all data at native time
808 unit and do the conversion on the end result.
809 erlang:crc32(Data) -> integer() >= 0
812 Types:
814 Data = iodata()
816 Computes and returns the crc32 (IEEE 802.3 style) checksum for
818 Data.
819 erlang:crc32(OldCrc, Data) -> integer() >= 0
821 Types:
823 OldCrc = integer() >= 0
825 Data = iodata()
826 Continues computing the crc32 checksum by combining the previous
828 checksum, OldCrc, with the checksum of Data.
829 The following code:
831 X = erlang:crc32(Data1),
833 Y = erlang:crc32(X,Data2).
834 assigns the same value to Y as this:
836 Y = erlang:crc32([Data1,Data2]).
838 erlang:crc32_combine(FirstCrc, SecondCrc, SecondSize) ->
840 integer() >= 0
841 Types:
843 FirstCrc = SecondCrc = SecondSize = integer() >= 0
845 Combines two previously computed crc32 checksums. This computa‐
847 tion requires the size of the data object for the second check‐
848 sum to be known.
849 The following code:
851 Y = erlang:crc32(Data1),
853 Z = erlang:crc32(Y,Data2).
854 assigns the same value to Z as this:
856 X = erlang:crc32(Data1),
858 Y = erlang:crc32(Data2),
859 Z = erlang:crc32_combine(X,Y,iolist_size(Data2)).
860 date() -> Date
862 Types:
864 Date = calendar:date()
866 Returns the current date as {Year, Month, Day}.
868 The time zone and Daylight Saving Time correction depend on the
870 underlying OS. Example:
871 > date().
873 {1995,2,19}
874 erlang:decode_packet(Type, Bin, Options) ->
876 {ok, Packet, Rest} |
877 {more, Length} |
878 {error, Reason}
879 Types:
881 Type =
883 raw |
884 0 |
885 1 |
886 2 |
887 4 |
888 asn1 |
889 cdr |
890 sunrm |
891 fcgi |
892 tpkt |
893 line |
894 http |
895 http_bin |
896 httph |
897 httph_bin
898 Bin = binary()
899 Options = [Opt]
900 Opt =
901 {packet_size, integer() >= 0} |
902 {line_length, integer() >= 0}
903 Packet = binary() | HttpPacket
904 Rest = binary()
905 Length = integer() >= 0 | undefined
906 Reason = term()
907 HttpPacket =
908 HttpRequest | HttpResponse | HttpHeader | http_eoh |
909 HttpError
910 HttpRequest = {http_request, HttpMethod, HttpUri, HttpVer‐
911 sion}
912 HttpResponse =
913 {http_response, HttpVersion, integer(), HttpString}
914 HttpHeader =
915 {http_header,
916 integer(),
917 HttpField,
918 Reserved :: term(),
919 Value :: HttpString}
920 HttpError = {http_error, HttpString}
921 HttpMethod =
922 'OPTIONS' |
923 'GET' |
924 'HEAD' |
925 'POST' |
926 'PUT' |
927 'DELETE' |
928 'TRACE' |
929 HttpString
930 HttpUri =
931 '*' |
932 {absoluteURI,
933 http | https,
934 Host :: HttpString,
935 Port :: inet:port_number() | undefined,
936 Path :: HttpString} |
937 {scheme, Scheme :: HttpString, HttpString} |
938 {abs_path, HttpString} |
939 HttpString
940 HttpVersion =
941 {Major :: integer() >= 0, Minor :: integer() >= 0}
942 HttpField =
943 'Cache-Control' |
944 'Connection' |
945 'Date' |
946 'Pragma' |
947 'Transfer-Encoding' |
948 'Upgrade' |
949 'Via' |
950 'Accept' |
951 'Accept-Charset' |
952 'Accept-Encoding' |
953 'Accept-Language' |
954 'Authorization' |
955 'From' |
956 'Host' |
957 'If-Modified-Since' |
958 'If-Match' |
959 'If-None-Match' |
960 'If-Range' |
961 'If-Unmodified-Since' |
962 'Max-Forwards' |
963 'Proxy-Authorization' |
964 'Range' |
965 'Referer' |
966 'User-Agent' |
967 'Age' |
968 'Location' |
969 'Proxy-Authenticate' |
970 'Public' |
971 'Retry-After' |
972 'Server' |
973 'Vary' |
974 'Warning' |
975 'Www-Authenticate' |
976 'Allow' |
977 'Content-Base' |
978 'Content-Encoding' |
979 'Content-Language' |
980 'Content-Length' |
981 'Content-Location' |
982 'Content-Md5' |
983 'Content-Range' |
984 'Content-Type' |
985 'Etag' |
986 'Expires' |
987 'Last-Modified' |
988 'Accept-Ranges' |
989 'Set-Cookie' |
990 'Set-Cookie2' |
991 'X-Forwarded-For' |
992 'Cookie' |
993 'Keep-Alive' |
994 'Proxy-Connection' |
995 HttpString
996 HttpString = string() | binary()
997 Decodes the binary Bin according to the packet protocol speci‐
999 fied by Type. Similar to the packet handling done by sockets
1000 with option {packet,Type}.
1001 If an entire packet is contained in Bin, it is returned together
1003 with the remainder of the binary as {ok,Packet,Rest}.
1004 If Bin does not contain the entire packet, {more,Length} is
1006 returned. Length is either the expected total size of the
1007 packet, or undefined if the expected packet size is unknown.
1008 decode_packet can then be called again with more data added.
1009 If the packet does not conform to the protocol format,
1011 {error,Reason} is returned.
1012 Types:
1014 raw | 0:
1016 No packet handling is done. The entire binary is returned
1017 unless it is empty.
1018 1 | 2 | 4:
1020 Packets consist of a header specifying the number of bytes
1021 in the packet, followed by that number of bytes. The length
1022 of the header can be one, two, or four bytes; the order of
1023 the bytes is big-endian. The header is stripped off when the
1024 packet is returned.
1025 line:
1027 A packet is a line-terminated by a delimiter byte, default
1028 is the latin-1 newline character. The delimiter byte is
1029 included in the returned packet unless the line was trun‐
1030 cated according to option line_length.
1031 asn1 | cdr | sunrm | fcgi | tpkt:
1033 The header is not stripped off.
1034 The meanings of the packet types are as follows:
1036 asn1 - ASN.1 BER:
1038 sunrm - Sun's RPC encoding:
1041 cdr - CORBA (GIOP 1.1):
1044 fcgi - Fast CGI:
1047 tpkt - TPKT format [RFC1006]:
1050 http | httph | http_bin | httph_bin:
1053 The Hypertext Transfer Protocol. The packets are returned
1054 with the format according to HttpPacket described earlier. A
1055 packet is either a request, a response, a header, or an end
1056 of header mark. Invalid lines are returned as HttpError.
1057 Recognized request methods and header fields are returned as
1059 atoms. Others are returned as strings. Strings of unrecog‐
1060 nized header fields are formatted with only capital letters
1061 first and after hyphen characters, for example, "Sec-Web‐
1062 socket-Key".
1063 The protocol type http is only to be used for the first line
1065 when an HttpRequest or an HttpResponse is expected. The fol‐
1066 lowing calls are to use httph to get HttpHeaders until
1067 http_eoh is returned, which marks the end of the headers and
1068 the beginning of any following message body.
1069 The variants http_bin and httph_bin return strings (Http‐
1071 String) as binaries instead of lists.
1072 Options:
1074 {packet_size, integer() >= 0}:
1076 Sets the maximum allowed size of the packet body. If the
1077 packet header indicates that the length of the packet is
1078 longer than the maximum allowed length, the packet is con‐
1079 sidered invalid. Defaults to 0, which means no size limit.
1080 {line_length, integer() >= 0}:
1082 For packet type line, lines longer than the indicated length
1083 are truncated.
1084 Option line_length also applies to http* packet types as an
1086 alias for option packet_size if packet_size itself is not
1087 set. This use is only intended for backward compatibility.
1088 {line_delimiter, 0 =< byte() =< 255}:
1090 For packet type line, sets the delimiting byte. Default is
1091 the latin-1 character $\n.
1092 Examples:
1094 > erlang:decode_packet(1,<<3,"abcd">>,[]).
1096 {ok,<<"abc">>,<<"d">>}
1097 > erlang:decode_packet(1,<<5,"abcd">>,[]).
1098 {more,6}
1099 erlang:delete_element(Index, Tuple1) -> Tuple2
1101 Types:
1103 Index = integer() >= 1
1105 1..tuple_size(Tuple1)
1106 Tuple1 = Tuple2 = tuple()
1107 Returns a new tuple with element at Index removed from tuple
1109 Tuple1, for example:
1110 > erlang:delete_element(2, {one, two, three}).
1112 {one,three}
1113 delete_module(Module) -> true | undefined
1115 Types:
1117 Module = module()
1119 Makes the current code for Module become old code and deletes
1121 all references for this module from the export table. Returns
1122 undefined if the module does not exist, otherwise true.
1123 Warning:
1125 This BIF is intended for the code server (see code(3)) and is
1126 not to be used elsewhere.
1127 Failure: badarg if there already is an old version of Module.
1130 demonitor(MonitorRef) -> true
1132 Types:
1134 MonitorRef = reference()
1136 If MonitorRef is a reference that the calling process obtained
1138 by calling monitor/2, this monitoring is turned off. If the mon‐
1139 itoring is already turned off, nothing happens.
1140 Once demonitor(MonitorRef) has returned, it is guaranteed that
1142 no {'DOWN', MonitorRef, _, _, _} message, because of the moni‐
1143 tor, will be placed in the caller message queue in the future.
1144 However, a {'DOWN', MonitorRef, _, _, _} message can have been
1145 placed in the caller message queue before the call. It is there‐
1146 fore usually advisable to remove such a 'DOWN' message from the
1147 message queue after monitoring has been stopped. demonitor(Moni‐
1148 torRef, [flush]) can be used instead of demonitor(MonitorRef) if
1149 this cleanup is wanted.
1150 Note:
1152 Before Erlang/OTP R11B (ERTS 5.5) demonitor/1 behaved completely
1153 asynchronously, that is, the monitor was active until the
1154 "demonitor signal" reached the monitored entity. This had one
1155 undesirable effect. You could never know when you were guaran‐
1156 teed not to receive a DOWN message because of the monitor.
1157 The current behavior can be viewed as two combined operations:
1159 asynchronously send a "demonitor signal" to the monitored entity
1160 and ignore any future results of the monitor.
1161 Failure: It is an error if MonitorRef refers to a monitoring
1164 started by another process. Not all such cases are cheap to
1165 check. If checking is cheap, the call fails with badarg, for
1166 example if MonitorRef is a remote reference.
1167 demonitor(MonitorRef, OptionList) -> boolean()
1169 Types:
1171 MonitorRef = reference()
1173 OptionList = [Option]
1174 Option = flush | info
1175 The returned value is true unless info is part of OptionList.
1177 demonitor(MonitorRef, []) is equivalent to demonitor(Monitor‐
1179 Ref).
1180 Options:
1182 flush:
1184 Removes (one) {_, MonitorRef, _, _, _} message, if there is
1185 one, from the caller message queue after monitoring has been
1186 stopped.
1187 Calling demonitor(MonitorRef, [flush]) is equivalent to the
1189 following, but more efficient:
1190 demonitor(MonitorRef),
1192 receive
1193 {_, MonitorRef, _, _, _} ->
1194 true
1195 after 0 ->
1196 true
1197 end
1198 info:
1200 The returned value is one of the following:
1201 true:
1203 The monitor was found and removed. In this case, no 'DOWN'
1204 message corresponding to this monitor has been delivered
1205 and will not be delivered.
1206 false:
1208 The monitor was not found and could not be removed. This
1209 probably because someone already has placed a 'DOWN' mes‐
1210 sage corresponding to this monitor in the caller message
1211 queue.
1212 If option info is combined with option flush, false is
1214 returned if a flush was needed, otherwise true.
1215 Note:
1217 More options can be added in a future release.
1218 Failures:
1221 badarg:
1223 If OptionList is not a list.
1224 badarg:
1226 If Option is an invalid option.
1227 badarg:
1229 The same failure as for demonitor/1.
1230 disconnect_node(Node) -> boolean() | ignored
1232 Types:
1234 Node = node()
1236 Forces the disconnection of a node. This appears to the node
1238 Node as if the local node has crashed. This BIF is mainly used
1239 in the Erlang network authentication protocols.
1240 Returns true if disconnection succeeds, otherwise false. If the
1242 local node is not alive, ignored is returned.
1243 erlang:display(Term) -> true
1245 Types:
1247 Term = term()
1249 Prints a text representation of Term on the standard output.
1251 Warning:
1253 This BIF is intended for debugging only.
1254 element(N, Tuple) -> term()
1257 Types:
1259 N = integer() >= 1
1261 1..tuple_size(Tuple)
1262 Tuple = tuple()
1263 Returns the Nth element (numbering from 1) of Tuple, for exam‐
1265 ple:
1266 > element(2, {a, b, c}).
1268 b
1269 Allowed in guard tests.
1271 erase() -> [{Key, Val}]
1273 Types:
1275 Key = Val = term()
1277 Returns the process dictionary and deletes it, for example:
1279 > put(key1, {1, 2, 3}),
1281 put(key2, [a, b, c]),
1282 erase().
1283 [{key1,{1,2,3}},{key2,[a,b,c]}]
1284 erase(Key) -> Val | undefined
1286 Types:
1288 Key = Val = term()
1290 Returns the value Val associated with Key and deletes it from
1292 the process dictionary. Returns undefined if no value is associ‐
1293 ated with Key. Example:
1294 > put(key1, {merry, lambs, are, playing}),
1296 X = erase(key1),
1297 {X, erase(key1)}.
1298 {{merry,lambs,are,playing},undefined}
1299 error(Reason) -> no_return()
1301 Types:
1303 Reason = term()
1305 Stops the execution of the calling process with the reason Rea‐
1307 son, where Reason is any term. The exit reason is {Reason,
1308 Where}, where Where is a list of the functions most recently
1309 called (the current function first). As evaluating this function
1310 causes the process to terminate, it has no return value. Exam‐
1311 ple:
1312 > catch error(foobar).
1314 {'EXIT',{foobar,[{erl_eval,do_apply,5},
1315 {erl_eval,expr,5},
1316 {shell,exprs,6},
1317 {shell,eval_exprs,6},
1318 {shell,eval_loop,3}]}}
1319 error(Reason, Args) -> no_return()
1321 Types:
1323 Reason = term()
1325 Args = [term()]
1326 Stops the execution of the calling process with the reason Rea‐
1328 son, where Reason is any term. The exit reason is {Reason,
1329 Where}, where Where is a list of the functions most recently
1330 called (the current function first). Args is expected to be the
1331 list of arguments for the current function; in Beam it is used
1332 to provide the arguments for the current function in the term
1333 Where. As evaluating this function causes the process to termi‐
1334 nate, it has no return value.
1335 exit(Reason) -> no_return()
1337 Types:
1339 Reason = term()
1341 Stops the execution of the calling process with exit reason Rea‐
1343 son, where Reason is any term. As evaluating this function
1344 causes the process to terminate, it has no return value. Exam‐
1345 ple:
1346 > exit(foobar).
1348 ** exception exit: foobar
1349 > catch exit(foobar).
1350 {'EXIT',foobar}
1351 exit(Pid, Reason) -> true
1353 Types:
1355 Pid = pid() | port()
1357 Reason = term()
1358 Sends an exit signal with exit reason Reason to the process or
1360 port identified by Pid.
1361 The following behavior applies if Reason is any term, except
1363 normal or kill:
1364 * If Pid is not trapping exits, Pid itself exits with exit
1366 reason Reason.
1367 * If Pid is trapping exits, the exit signal is transformed
1369 into a message {'EXIT', From, Reason} and delivered to the
1370 message queue of Pid.
1371 * From is the process identifier of the process that sent the
1373 exit signal. See also process_flag/2.
1374 If Reason is the atom normal, Pid does not exit. If it is trap‐
1376 ping exits, the exit signal is transformed into a message
1377 {'EXIT', From, normal} and delivered to its message queue.
1378 If Reason is the atom kill, that is, if exit(Pid, kill) is
1380 called, an untrappable exit signal is sent to Pid, which uncon‐
1381 ditionally exits with exit reason killed.
1382 erlang:external_size(Term) -> integer() >= 0
1384 Types:
1386 Term = term()
1388 Calculates, without doing the encoding, the maximum byte size
1390 for a term encoded in the Erlang external term format. The fol‐
1391 lowing condition applies always:
1392 > Size1 = byte_size(term_to_binary(Term)),
1394 > Size2 = erlang:external_size(Term),
1395 > true = Size1 =< Size2.
1396 true
1397 This is equivalent to a call to:
1399 erlang:external_size(Term, [])
1401 erlang:external_size(Term, Options) -> integer() >= 0
1403 Types:
1405 Term = term()
1407 Options = [{minor_version, Version :: integer() >= 0}]
1408 Calculates, without doing the encoding, the maximum byte size
1410 for a term encoded in the Erlang external term format. The fol‐
1411 lowing condition applies always:
1412 > Size1 = byte_size(term_to_binary(Term, Options)),
1414 > Size2 = erlang:external_size(Term, Options),
1415 > true = Size1 =< Size2.
1416 true
1417 Option {minor_version, Version} specifies how floats are
1419 encoded. For a detailed description, see term_to_binary/2.
1420 float(Number) -> float()
1422 Types:
1424 Number = number()
1426 Returns a float by converting Number to a float, for example:
1428 > float(55).
1430 55.0
1431 Allowed in guard tests.
1433 Note:
1435 If used on the top level in a guard, it tests whether the argu‐
1436 ment is a floating point number; for clarity, use is_float/1
1437 instead.
1438 When float/1 is used in an expression in a guard, such as
1440 'float(A) == 4.0', it converts a number as described earlier.
1441 float_to_binary(Float) -> binary()
1444 Types:
1446 Float = float()
1448 The same as float_to_binary(Float,[{scientific,20}]).
1450 float_to_binary(Float, Options) -> binary()
1452 Types:
1454 Float = float()
1456 Options = [Option]
1457 Option =
1458 {decimals, Decimals :: 0..253} |
1459 {scientific, Decimals :: 0..249} |
1460 compact
1461 Returns a binary corresponding to the text representation of
1463 Float using fixed decimal point formatting. Options behaves in
1464 the same way as float_to_list/2. Examples:
1465 > float_to_binary(7.12, [{decimals, 4}]).
1467 <<"7.1200">>
1468 > float_to_binary(7.12, [{decimals, 4}, compact]).
1469 <<"7.12">>
1470 float_to_list(Float) -> string()
1472 Types:
1474 Float = float()
1476 The same as float_to_list(Float,[{scientific,20}]).
1478 float_to_list(Float, Options) -> string()
1480 Types:
1482 Float = float()
1484 Options = [Option]
1485 Option =
1486 {decimals, Decimals :: 0..253} |
1487 {scientific, Decimals :: 0..249} |
1488 compact
1489 Returns a string corresponding to the text representation of
1491 Float using fixed decimal point formatting.
1492 Available options:
1494 * If option decimals is specified, the returned value contains
1496 at most Decimals number of digits past the decimal point. If
1497 the number does not fit in the internal static buffer of 256
1498 bytes, the function throws badarg.
1499 * If option compact is specified, the trailing zeros at the
1501 end of the list are truncated. This option is only meaning‐
1502 ful together with option decimals.
1503 * If option scientific is specified, the float is formatted
1505 using scientific notation with Decimals digits of precision.
1506 * If Options is [], the function behaves as float_to_list/1.
1508 Examples:
1510 > float_to_list(7.12, [{decimals, 4}]).
1512 "7.1200"
1513 > float_to_list(7.12, [{decimals, 4}, compact]).
1514 "7.12"
1515 floor(Number) -> integer()
1517 Types:
1519 Number = number()
1521 Returns the largest integer not greater than Number. For exam‐
1523 ple:
1524 > floor(-10.5).
1526 -11
1527 Allowed in guard tests.
1529 erlang:fun_info(Fun) -> [{Item, Info}]
1531 Types:
1533 Fun = function()
1535 Item =
1536 arity |
1537 env |
1538 index |
1539 name |
1540 module |
1541 new_index |
1542 new_uniq |
1543 pid |
1544 type |
1545 uniq
1546 Info = term()
1547 Returns a list with information about the fun Fun. Each list
1549 element is a tuple. The order of the tuples is undefined, and
1550 more tuples can be added in a future release.
1551 Warning:
1553 This BIF is mainly intended for debugging, but it can sometimes
1554 be useful in library functions that need to verify, for example,
1555 the arity of a fun.
1556 Two types of funs have slightly different semantics:
1559 * A fun created by fun M:F/A is called an external fun. Call‐
1561 ing it will always call the function F with arity A in the
1562 latest code for module M. Notice that module M does not even
1563 need to be loaded when the fun fun M:F/A is created.
1564 * All other funs are called local. When a local fun is called,
1566 the same version of the code that created the fun is called
1567 (even if a newer version of the module has been loaded).
1568 The following elements are always present in the list for both
1570 local and external funs:
1571 {type, Type}:
1573 Type is local or external.
1574 {module, Module}:
1576 Module (an atom) is the module name.
1577 If Fun is a local fun, Module is the module in which the fun
1579 is defined.
1580 If Fun is an external fun, Module is the module that the fun
1582 refers to.
1583 {name, Name}:
1585 Name (an atom) is a function name.
1586 If Fun is a local fun, Name is the name of the local func‐
1588 tion that implements the fun. (This name was generated by
1589 the compiler, and is only of informational use. As it is a
1590 local function, it cannot be called directly.) If no code is
1591 currently loaded for the fun, [] is returned instead of an
1592 atom.
1593 If Fun is an external fun, Name is the name of the exported
1595 function that the fun refers to.
1596 {arity, Arity}:
1598 Arity is the number of arguments that the fun is to be
1599 called with.
1600 {env, Env}:
1602 Env (a list) is the environment or free variables for the
1603 fun. For external funs, the returned list is always empty.
1604 The following elements are only present in the list if Fun is
1606 local:
1607 {pid, Pid}:
1609 Pid is the process identifier of the process that originally
1610 created the fun.
1611 {index, Index}:
1613 Index (an integer) is an index into the module fun table.
1614 {new_index, Index}:
1616 Index (an integer) is an index into the module fun table.
1617 {new_uniq, Uniq}:
1619 Uniq (a binary) is a unique value for this fun. It is calcu‐
1620 lated from the compiled code for the entire module.
1621 {uniq, Uniq}:
1623 Uniq (an integer) is a unique value for this fun. As from
1624 Erlang/OTP R15, this integer is calculated from the compiled
1625 code for the entire module. Before Erlang/OTP R15, this
1626 integer was based on only the body of the fun.
1627 erlang:fun_info(Fun, Item) -> {Item, Info}
1629 Types:
1631 Fun = function()
1633 Item = fun_info_item()
1634 Info = term()
1635 fun_info_item() =
1636 arity |
1637 env |
1638 index |
1639 name |
1640 module |
1641 new_index |
1642 new_uniq |
1643 pid |
1644 type |
1645 uniq
1646 Returns information about Fun as specified by Item, in the form
1648 {Item,Info}.
1649 For any fun, Item can be any of the atoms module, name, arity,
1651 env, or type.
1652 For a local fun, Item can also be any of the atoms index,
1654 new_index, new_uniq, uniq, and pid. For an external fun, the
1655 value of any of these items is always the atom undefined.
1656 See erlang:fun_info/1.
1658 erlang:fun_to_list(Fun) -> string()
1660 Types:
1662 Fun = function()
1664 Returns a string corresponding to the text representation of
1666 Fun.
1667 erlang:function_exported(Module, Function, Arity) -> boolean()
1669 Types:
1671 Module = module()
1673 Function = atom()
1674 Arity = arity()
1675 Returns true if the module Module is loaded and contains an
1677 exported function Function/Arity, or if there is a BIF (a built-
1678 in function implemented in C) with the specified name, otherwise
1679 returns false.
1680 Note:
1682 This function used to return false for BIFs before Erlang/OTP
1683 18.0.
1684 garbage_collect() -> true
1687 Forces an immediate garbage collection of the executing process.
1689 The function is not to be used unless it has been noticed (or
1690 there are good reasons to suspect) that the spontaneous garbage
1691 collection will occur too late or not at all.
1692 Warning:
1694 Improper use can seriously degrade system performance.
1695 garbage_collect(Pid) -> GCResult
1698 Types:
1700 Pid = pid()
1702 GCResult = boolean()
1703 The same as garbage_collect(Pid, []).
1705 garbage_collect(Pid, OptionList) -> GCResult | async
1707 Types:
1709 Pid = pid()
1711 RequestId = term()
1712 Option = {async, RequestId} | {type, major | minor}
1713 OptionList = [Option]
1714 GCResult = boolean()
1715 Garbage collects the node local process identified by Pid.
1717 Option:
1719 {async, RequestId}:
1721 The function garbage_collect/2 returns the value async imme‐
1722 diately after the request has been sent. When the request
1723 has been processed, the process that called this function is
1724 passed a message on the form {garbage_collect, RequestId,
1725 GCResult}.
1726 {type, 'major' | 'minor'}:
1728 Triggers garbage collection of requested type. Default value
1729 is 'major', which would trigger a fullsweep GC. The option
1730 'minor' is considered a hint and may lead to either minor or
1731 major GC run.
1732 If Pid equals self(), and no async option has been passed, the
1734 garbage collection is performed at once, that is, the same as
1735 calling garbage_collect/0. Otherwise a request for garbage col‐
1736 lection is sent to the process identified by Pid, and will be
1737 handled when appropriate. If no async option has been passed,
1738 the caller blocks until GCResult is available and can be
1739 returned.
1740 GCResult informs about the result of the garbage collection
1742 request as follows:
1743 true:
1745 The process identified by Pid has been garbage collected.
1746 false:
1748 No garbage collection was performed, as the process identi‐
1749 fied by Pid terminated before the request could be satis‐
1750 fied.
1751 Notice that the same caveats apply as for garbage_collect/0.
1753 Failures:
1755 badarg:
1757 If Pid is not a node local process identifier.
1758 badarg:
1760 If OptionList is an invalid list of options.
1761 get() -> [{Key, Val}]
1763 Types:
1765 Key = Val = term()
1767 Returns the process dictionary as a list of {Key, Val} tuples,
1769 for example:
1770 > put(key1, merry),
1772 put(key2, lambs),
1773 put(key3, {are, playing}),
1774 get().
1775 [{key1,merry},{key2,lambs},{key3,{are,playing}}]
1776 get(Key) -> Val | undefined
1778 Types:
1780 Key = Val = term()
1782 Returns the value Val associated with Key in the process dictio‐
1784 nary, or undefined if Key does not exist. Example:
1785 > put(key1, merry),
1787 put(key2, lambs),
1788 put({any, [valid, term]}, {are, playing}),
1789 get({any, [valid, term]}).
1790 {are,playing}
1791 erlang:get_cookie() -> Cookie | nocookie
1793 Types:
1795 Cookie = atom()
1797 Returns the magic cookie of the local node if the node is alive,
1799 otherwise the atom nocookie.
1800 get_keys() -> [Key]
1802 Types:
1804 Key = term()
1806 Returns a list of all keys present in the process dictionary,
1808 for example:
1809 > put(dog, {animal,1}),
1811 put(cow, {animal,2}),
1812 put(lamb, {animal,3}),
1813 get_keys().
1814 [dog,cow,lamb]
1815 get_keys(Val) -> [Key]
1817 Types:
1819 Val = Key = term()
1821 Returns a list of keys that are associated with the value Val in
1823 the process dictionary, for example:
1824 > put(mary, {1, 2}),
1826 put(had, {1, 2}),
1827 put(a, {1, 2}),
1828 put(little, {1, 2}),
1829 put(dog, {1, 3}),
1830 put(lamb, {1, 2}),
1831 get_keys({1, 2}).
1832 [mary,had,a,little,lamb]
1833 erlang:get_stacktrace() -> [stack_item()]
1835 Types:
1837 stack_item() =
1839 {Module :: module(),
1840 Function :: atom(),
1841 Arity :: arity() | (Args :: [term()]),
1842 Location ::
1843 [{file, Filename :: string()} |
1844 {line, Line :: integer() >= 1}]}
1845 Gets the call stack back-trace (stacktrace) for an exception
1847 that has just been caught in the calling process as a list of
1848 {Module,Function,Arity,Location} tuples. Field Arity in the
1849 first tuple can be the argument list of that function call
1850 instead of an arity integer, depending on the exception.
1851 If there has not been any exceptions in a process, the stack‐
1853 trace is []. After a code change for the process, the stacktrace
1854 can also be reset to [].
1855 erlang:get_stacktrace/0 is only guaranteed to return a stack‐
1857 trace if called (directly or indirectly) from within the scope
1858 of a try expression. That is, the following call works:
1859 try Expr
1861 catch
1862 C:R ->
1863 {C,R,erlang:get_stacktrace()}
1864 end
1865 As does this call:
1867 try Expr
1869 catch
1870 C:R ->
1871 {C,R,helper()}
1872 end
1873 helper() ->
1875 erlang:get_stacktrace().
1876 Warning:
1878 In a future release, erlang:get_stacktrace/0 will return [] if
1879 called from outside a try expression.
1880 The stacktrace is the same data as operator catch returns, for
1883 example:
1884 {'EXIT',{badarg,Stacktrace}} = catch abs(x)
1886 Location is a (possibly empty) list of two-tuples that can indi‐
1888 cate the location in the source code of the function. The first
1889 element is an atom describing the type of information in the
1890 second element. The following items can occur:
1891 file:
1893 The second element of the tuple is a string (list of charac‐
1894 ters) representing the filename of the source file of the
1895 function.
1896 line:
1898 The second element of the tuple is the line number (an inte‐
1899 ger > 0) in the source file where the exception occurred or
1900 the function was called.
1901 See also error/1 and error/2.
1903 group_leader() -> pid()
1905 Returns the process identifier of the group leader for the
1907 process evaluating the function.
1908 Every process is a member of some process group and all groups
1910 have a group leader. All I/O from the group is channeled to the
1911 group leader. When a new process is spawned, it gets the same
1912 group leader as the spawning process. Initially, at system
1913 startup, init is both its own group leader and the group leader
1914 of all processes.
1915 group_leader(GroupLeader, Pid) -> true
1917 Types:
1919 GroupLeader = Pid = pid()
1921 Sets the group leader of Pid to GroupLeader. Typically, this is
1923 used when a process started from a certain shell is to have
1924 another group leader than init.
1925 See also group_leader/0.
1927 halt() -> no_return()
1929 The same as halt(0, []). Example:
1931 > halt().
1933 os_prompt%
1934 halt(Status) -> no_return()
1936 Types:
1938 Status = integer() >= 0 | abort | string()
1940 The same as halt(Status, []). Example:
1942 > halt(17).
1944 os_prompt% echo $?
1945 17
1946 os_prompt%
1947 halt(Status, Options) -> no_return()
1949 Types:
1951 Status = integer() >= 0 | abort | string()
1953 Options = [Option]
1954 Option = {flush, boolean()}
1955 Status must be a non-negative integer, a string, or the atom
1957 abort. Halts the Erlang runtime system. Has no return value.
1958 Depending on Status, the following occurs:
1959 integer():
1961 The runtime system exits with integer value Status as status
1962 code to the calling environment (OS).
1963 Note:
1965 On many platforms, the OS supports only status codes 0-255. A
1966 too large status code is truncated by clearing the high bits.
1967 string():
1970 An Erlang crash dump is produced with Status as slogan. Then
1971 the runtime system exits with status code 1. The string will
1972 be truncated if longer than 200 characters.
1973 Note:
1975 Before ERTS 9.1 (OTP-20.1) only code points in the range 0-255
1976 was accepted in the string. Now any unicode string is valid.
1977 abort:
1980 The runtime system aborts producing a core dump, if that is
1981 enabled in the OS.
1982 For integer Status, the Erlang runtime system closes all ports
1984 and allows async threads to finish their operations before exit‐
1985 ing. To exit without such flushing, use Option as {flush,false}.
1986 For statuses string() and abort, option flush is ignored and
1988 flushing is not done.
1989 hd(List) -> term()
1991 Types:
1993 List = [term(), ...]
1995 Returns the head of List, that is, the first element, for exam‐
1997 ple:
1998 > hd([1,2,3,4,5]).
2000 1
2001 Allowed in guard tests.
2003 Failure: badarg if List is the empty list [].
2005 erlang:hibernate(Module, Function, Args) -> no_return()
2007 Types:
2009 Module = module()
2011 Function = atom()
2012 Args = [term()]
2013 Puts the calling process into a wait state where its memory
2015 allocation has been reduced as much as possible. This is useful
2016 if the process does not expect to receive any messages soon.
2017 The process is awaken when a message is sent to it, and control
2019 resumes in Module:Function with the arguments specified by Args
2020 with the call stack emptied, meaning that the process terminates
2021 when that function returns. Thus erlang:hibernate/3 never
2022 returns to its caller.
2023 If the process has any message in its message queue, the process
2025 is awakened immediately in the same way as described earlier.
2026 In more technical terms, erlang:hibernate/3 discards the call
2028 stack for the process, and then garbage collects the process.
2029 After this, all live data is in one continuous heap. The heap is
2030 then shrunken to the exact same size as the live data that it
2031 holds (even if that size is less than the minimum heap size for
2032 the process).
2033 If the size of the live data in the process is less than the
2035 minimum heap size, the first garbage collection occurring after
2036 the process is awakened ensures that the heap size is changed to
2037 a size not smaller than the minimum heap size.
2038 Notice that emptying the call stack means that any surrounding
2040 catch is removed and must be re-inserted after hibernation. One
2041 effect of this is that processes started using proc_lib (also
2042 indirectly, such as gen_server processes), are to use
2043 proc_lib:hibernate/3 instead, to ensure that the exception han‐
2044 dler continues to work when the process wakes up.
2045 erlang:insert_element(Index, Tuple1, Term) -> Tuple2
2047 Types:
2049 Index = integer() >= 1
2051 1..tuple_size(Tuple1) + 1
2052 Tuple1 = Tuple2 = tuple()
2053 Term = term()
2054 Returns a new tuple with element Term inserted at position Index
2056 in tuple Tuple1. All elements from position Index and upwards
2057 are pushed one step higher in the new tuple Tuple2. Example:
2058 > erlang:insert_element(2, {one, two, three}, new).
2060 {one,new,two,three}
2061 integer_to_binary(Integer) -> binary()
2063 Types:
2065 Integer = integer()
2067 Returns a binary corresponding to the text representation of
2069 Integer, for example:
2070 > integer_to_binary(77).
2072 <<"77">>
2073 integer_to_binary(Integer, Base) -> binary()
2075 Types:
2077 Integer = integer()
2079 Base = 2..36
2080 Returns a binary corresponding to the text representation of
2082 Integer in base Base, for example:
2083 > integer_to_binary(1023, 16).
2085 <<"3FF">>
2086 integer_to_list(Integer) -> string()
2088 Types:
2090 Integer = integer()
2092 Returns a string corresponding to the text representation of
2094 Integer, for example:
2095 > integer_to_list(77).
2097 "77"
2098 integer_to_list(Integer, Base) -> string()
2100 Types:
2102 Integer = integer()
2104 Base = 2..36
2105 Returns a string corresponding to the text representation of
2107 Integer in base Base, for example:
2108 > integer_to_list(1023, 16).
2110 "3FF"
2111 iolist_size(Item) -> integer() >= 0
2113 Types:
2115 Item = iolist() | binary()
2117 Returns an integer, that is the size in bytes, of the binary
2119 that would be the result of iolist_to_binary(Item), for example:
2120 > iolist_size([1,2|<<3,4>>]).
2122 4
2123 iolist_to_binary(IoListOrBinary) -> binary()
2125 Types:
2127 IoListOrBinary = iolist() | binary()
2129 Returns a binary that is made from the integers and binaries in
2131 IoListOrBinary, for example:
2132 > Bin1 = <<1,2,3>>.
2134 <<1,2,3>>
2135 > Bin2 = <<4,5>>.
2136 <<4,5>>
2137 > Bin3 = <<6>>.
2138 <<6>>
2139 > iolist_to_binary([Bin1,1,[2,3,Bin2],4|Bin3]).
2140 <<1,2,3,1,2,3,4,5,4,6>>
2141 erlang:iolist_to_iovec(IoListOrBinary) -> iovec()
2143 Types:
2145 IoListOrBinary = iolist() | binary()
2147 Returns an iovec that is made from the integers and binaries in
2149 IoListOrBinary.
2150 is_alive() -> boolean()
2152 Returns true if the local node is alive (that is, if the node
2154 can be part of a distributed system), otherwise false.
2155 is_atom(Term) -> boolean()
2157 Types:
2159 Term = term()
2161 Returns true if Term is an atom, otherwise false.
2163 Allowed in guard tests.
2165 is_binary(Term) -> boolean()
2167 Types:
2169 Term = term()
2171 Returns true if Term is a binary, otherwise false.
2173 A binary always contains a complete number of bytes.
2175 Allowed in guard tests.
2177 is_bitstring(Term) -> boolean()
2179 Types:
2181 Term = term()
2183 Returns true if Term is a bitstring (including a binary), other‐
2185 wise false.
2186 Allowed in guard tests.
2188 is_boolean(Term) -> boolean()
2190 Types:
2192 Term = term()
2194 Returns true if Term is the atom true or the atom false (that
2196 is, a boolean). Otherwise returns false.
2197 Allowed in guard tests.
2199 erlang:is_builtin(Module, Function, Arity) -> boolean()
2201 Types:
2203 Module = module()
2205 Function = atom()
2206 Arity = arity()
2207 This BIF is useful for builders of cross-reference tools.
2209 Returns true if Module:Function/Arity is a BIF implemented in C,
2211 otherwise false.
2212 is_float(Term) -> boolean()
2214 Types:
2216 Term = term()
2218 Returns true if Term is a floating point number, otherwise
2220 false.
2221 Allowed in guard tests.
2223 is_function(Term) -> boolean()
2225 Types:
2227 Term = term()
2229 Returns true if Term is a fun, otherwise false.
2231 Allowed in guard tests.
2233 is_function(Term, Arity) -> boolean()
2235 Types:
2237 Term = term()
2239 Arity = arity()
2240 Returns true if Term is a fun that can be applied with Arity
2242 number of arguments, otherwise false.
2243 Allowed in guard tests.
2245 is_integer(Term) -> boolean()
2247 Types:
2249 Term = term()
2251 Returns true if Term is an integer, otherwise false.
2253 Allowed in guard tests.
2255 is_list(Term) -> boolean()
2257 Types:
2259 Term = term()
2261 Returns true if Term is a list with zero or more elements, oth‐
2263 erwise false.
2264 Allowed in guard tests.
2266 is_map(Term) -> boolean()
2268 Types:
2270 Term = term()
2272 Returns true if Term is a map, otherwise false.
2274 Allowed in guard tests.
2276 is_number(Term) -> boolean()
2278 Types:
2280 Term = term()
2282 Returns true if Term is an integer or a floating point number.
2284 Otherwise returns false.
2285 Allowed in guard tests.
2287 is_pid(Term) -> boolean()
2289 Types:
2291 Term = term()
2293 Returns true if Term is a process identifier, otherwise false.
2295 Allowed in guard tests.
2297 is_port(Term) -> boolean()
2299 Types:
2301 Term = term()
2303 Returns true if Term is a port identifier, otherwise false.
2305 Allowed in guard tests.
2307 is_process_alive(Pid) -> boolean()
2309 Types:
2311 Pid = pid()
2313 Pid must refer to a process at the local node.
2315 Returns true if the process exists and is alive, that is, is not
2317 exiting and has not exited. Otherwise returns false.
2318 is_record(Term, RecordTag) -> boolean()
2320 Types:
2322 Term = term()
2324 RecordTag = atom()
2325 Returns true if Term is a tuple and its first element is Record‐
2327 Tag. Otherwise returns false.
2328 Note:
2330 Normally the compiler treats calls to is_record/2 especially. It
2331 emits code to verify that Term is a tuple, that its first ele‐
2332 ment is RecordTag, and that the size is correct. However, if
2333 RecordTag is not a literal atom, the BIF is_record/2 is called
2334 instead and the size of the tuple is not verified.
2335 Allowed in guard tests, if RecordTag is a literal atom.
2338 is_record(Term, RecordTag, Size) -> boolean()
2340 Types:
2342 Term = term()
2344 RecordTag = atom()
2345 Size = integer() >= 0
2346 RecordTag must be an atom.
2348 Returns true if Term is a tuple, its first element is RecordTag,
2350 and its size is Size. Otherwise returns false.
2351 Allowed in guard tests if RecordTag is a literal atom and Size
2353 is a literal integer.
2354 Note:
2356 This BIF is documented for completeness. Usually is_record/2 is
2357 to be used.
2358 is_reference(Term) -> boolean()
2361 Types:
2363 Term = term()
2365 Returns true if Term is a reference, otherwise false.
2367 Allowed in guard tests.
2369 is_tuple(Term) -> boolean()
2371 Types:
2373 Term = term()
2375 Returns true if Term is a tuple, otherwise false.
2377 Allowed in guard tests.
2379 length(List) -> integer() >= 0
2381 Types:
2383 List = [term()]
2385 Returns the length of List, for example:
2387 > length([1,2,3,4,5,6,7,8,9]).
2389 9
2390 Allowed in guard tests.
2392 link(PidOrPort) -> true
2394 Types:
2396 PidOrPort = pid() | port()
2398 Creates a link between the calling process and another process
2400 (or port) PidOrPort, if there is not such a link already. If a
2401 process attempts to create a link to itself, nothing is done.
2402 Returns true.
2403 If PidOrPort does not exist, the behavior of the BIF depends on
2405 if the calling process is trapping exits or not (see
2406 process_flag/2):
2407 * If the calling process is not trapping exits, and checking
2409 PidOrPort is cheap (that is, if PidOrPort is local), link/1
2410 fails with reason noproc.
2411 * Otherwise, if the calling process is trapping exits, and/or
2413 PidOrPort is remote, link/1 returns true, but an exit signal
2414 with reason noproc is sent to the calling process.
2415 list_to_atom(String) -> atom()
2417 Types:
2419 String = string()
2421 Returns the atom whose text representation is String.
2423 As from Erlang/OTP 20, String may contain any Unicode character.
2425 Earlier versions allowed only ISO-latin-1 characters as the
2426 implementation did not allow Unicode characters above 255. For
2427 more information on Unicode support in atoms, see note on UTF-8
2428 encoded atoms in section "External Term Format" in the User's
2429 Guide.
2430 Example:
2432 > list_to_atom("Erlang").
2434 list_to_binary(IoList) -> binary()
2436 Types:
2438 IoList = iolist()
2440 Returns a binary that is made from the integers and binaries in
2442 IoList, for example:
2443 > Bin1 = <<1,2,3>>.
2445 <<1,2,3>>
2446 > Bin2 = <<4,5>>.
2447 <<4,5>>
2448 > Bin3 = <<6>>.
2449 <<6>>
2450 > list_to_binary([Bin1,1,[2,3,Bin2],4|Bin3]).
2451 <<1,2,3,1,2,3,4,5,4,6>>
2452 list_to_bitstring(BitstringList) -> bitstring()
2454 Types:
2456 BitstringList = bitstring_list()
2458 bitstring_list() =
2459 maybe_improper_list(byte() | bitstring() | bitstring_list(),
2460 bitstring() | [])
2461 Returns a bitstring that is made from the integers and bit‐
2463 strings in BitstringList. (The last tail in BitstringList is
2464 allowed to be a bitstring.) Example:
2465 > Bin1 = <<1,2,3>>.
2467 <<1,2,3>>
2468 > Bin2 = <<4,5>>.
2469 <<4,5>>
2470 > Bin3 = <<6,7:4>>.
2471 <<6,7:4>>
2472 > list_to_bitstring([Bin1,1,[2,3,Bin2],4|Bin3]).
2473 <<1,2,3,1,2,3,4,5,4,6,7:4>>
2474 list_to_existing_atom(String) -> atom()
2476 Types:
2478 String = string()
2480 Returns the atom whose text representation is String, but only
2482 if there already exists such atom.
2483 Failure: badarg if there does not already exist an atom whose
2485 text representation is String.
2486 Note:
2488 Note that the compiler may optimize away atoms. For example, the
2489 compiler will rewrite atom_to_list(some_atom) to "some_atom". If
2490 that expression is the only mention of the atom some_atom in the
2491 containing module, the atom will not be created when the module
2492 is loaded, and a subsequent call to list_to_exist‐
2493 ing_atom("some_atom") will fail.
2494 list_to_float(String) -> float()
2497 Types:
2499 String = string()
2501 Returns the float whose text representation is String, for exam‐
2503 ple:
2504 > list_to_float("2.2017764e+0").
2506 2.2017764
2507 Failure: badarg if String contains a bad representation of a
2509 float.
2510 list_to_integer(String) -> integer()
2512 Types:
2514 String = string()
2516 Returns an integer whose text representation is String, for
2518 example:
2519 > list_to_integer("123").
2521 123
2522 Failure: badarg if String contains a bad representation of an
2524 integer.
2525 list_to_integer(String, Base) -> integer()
2527 Types:
2529 String = string()
2531 Base = 2..36
2532 Returns an integer whose text representation in base Base is
2534 String, for example:
2535 > list_to_integer("3FF", 16).
2537 1023
2538 Failure: badarg if String contains a bad representation of an
2540 integer.
2541 list_to_pid(String) -> pid()
2543 Types:
2545 String = string()
2547 Returns a process identifier whose text representation is a
2549 String, for example:
2550 > list_to_pid("<0.4.1>").
2552 <0.4.1>
2553 Failure: badarg if String contains a bad representation of a
2555 process identifier.
2556 Warning:
2558 This BIF is intended for debugging and is not to be used in
2559 application programs.
2560 list_to_port(String) -> port()
2563 Types:
2565 String = string()
2567 Returns a port identifier whose text representation is a String,
2569 for example:
2570 > list_to_port("#Port<0.4>").
2572 #Port<0.4>
2573 Failure: badarg if String contains a bad representation of a
2575 port identifier.
2576 Warning:
2578 This BIF is intended for debugging and is not to be used in
2579 application programs.
2580 list_to_ref(String) -> reference()
2583 Types:
2585 String = string()
2587 Returns a reference whose text representation is a String, for
2589 example:
2590 > list_to_ref("#Ref<0.4192537678.4073193475.71181>").
2592 #Ref<0.4192537678.4073193475.71181>
2593 Failure: badarg if String contains a bad representation of a
2595 reference.
2596 Warning:
2598 This BIF is intended for debugging and is not to be used in
2599 application programs.
2600 list_to_tuple(List) -> tuple()
2603 Types:
2605 List = [term()]
2607 Returns a tuple corresponding to List, for example
2609 > list_to_tuple([share, ['Ericsson_B', 163]]).
2611 {share, ['Ericsson_B', 163]}
2612 List can contain any Erlang terms.
2614 load_module(Module, Binary) -> {module, Module} | {error, Reason}
2616 Types:
2618 Module = module()
2620 Binary = binary()
2621 Reason = badfile | not_purged | on_load
2622 If Binary contains the object code for module Module, this BIF
2624 loads that object code. If the code for module Module already
2625 exists, all export references are replaced so they point to the
2626 newly loaded code. The previously loaded code is kept in the
2627 system as old code, as there can still be processes executing
2628 that code.
2629 Returns either {module, Module}, or {error, Reason} if loading
2631 fails. Reason is one of the following:
2632 badfile:
2634 The object code in Binary has an incorrect format or the
2635 object code contains code for another module than Module.
2636 not_purged:
2638 Binary contains a module that cannot be loaded because old
2639 code for this module already exists.
2640 Warning:
2642 This BIF is intended for the code server (see code(3)) and is
2643 not to be used elsewhere.
2644 erlang:load_nif(Path, LoadInfo) -> ok | Error
2647 Types:
2649 Path = string()
2651 LoadInfo = term()
2652 Error = {error, {Reason, Text :: string()}}
2653 Reason =
2654 load_failed | bad_lib | load | reload | upgrade |
2655 old_code
2656 Loads and links a dynamic library containing native implemented
2658 functions (NIFs) for a module. Path is a file path to the share‐
2659 able object/dynamic library file minus the OS-dependent file
2660 extension (.so for Unix and .dll for Windows). Notice that on
2661 most OSs the library has to have a different name on disc when
2662 an upgrade of the nif is done. If the name is the same, but the
2663 contents differ, the old library may be loaded instead. For
2664 information on how to implement a NIF library, see erl_nif(3).
2665 LoadInfo can be any term. It is passed on to the library as part
2667 of the initialization. A good practice is to include a module
2668 version number to support future code upgrade scenarios.
2669 The call to load_nif/2 must be made directly from the Erlang
2671 code of the module that the NIF library belongs to. It returns
2672 either ok, or {error,{Reason,Text}} if loading fails. Reason is
2673 one of the following atoms while Text is a human readable string
2674 that can give more information about the failure:
2675 load_failed:
2677 The OS failed to load the NIF library.
2678 bad_lib:
2680 The library did not fulfill the requirements as a NIF
2681 library of the calling module.
2682 load | upgrade:
2684 The corresponding library callback was unsuccessful.
2685 reload:
2687 A NIF library is already loaded for this module instance.
2688 The previously deprecated reload feature was removed in OTP
2689 20.
2690 old_code:
2692 The call to load_nif/2 was made from the old code of a mod‐
2693 ule that has been upgraded; this is not allowed.
2694 notsup:
2696 Lack of support. Such as loading NIF library for a HiPE com‐
2697 piled module.
2698 erlang:loaded() -> [Module]
2700 Types:
2702 Module = module()
2704 Returns a list of all loaded Erlang modules (current and old
2706 code), including preloaded modules.
2707 See also code(3).
2709 erlang:localtime() -> DateTime
2711 Types:
2713 DateTime = calendar:datetime()
2715 Returns the current local date and time, {{Year, Month, Day},
2717 {Hour, Minute, Second}}, for example:
2718 > erlang:localtime().
2720 {{1996,11,6},{14,45,17}}
2721 The time zone and Daylight Saving Time correction depend on the
2723 underlying OS.
2724 erlang:localtime_to_universaltime(Localtime) -> Universaltime
2726 Types:
2728 Localtime = Universaltime = calendar:datetime()
2730 Converts local date and time to Universal Time Coordinated
2732 (UTC), if supported by the underlying OS. Otherwise no conver‐
2733 sion is done and Localtime is returned. Example:
2734 > erlang:localtime_to_universaltime({{1996,11,6},{14,45,17}}).
2736 {{1996,11,6},{13,45,17}}
2737 Failure: badarg if Localtime denotes an invalid date and time.
2739 erlang:localtime_to_universaltime(Localtime, IsDst) ->
2741 Universaltime
2742 Types:
2744 Localtime = Universaltime = calendar:datetime()
2746 IsDst = true | false | undefined
2747 Converts local date and time to Universal Time Coordinated (UTC)
2749 as erlang:localtime_to_universaltime/1, but the caller decides
2750 if Daylight Saving Time is active.
2751 If IsDst == true, Localtime is during Daylight Saving Time, if
2753 IsDst == false it is not. If IsDst == undefined, the underlying
2754 OS can guess, which is the same as calling erlang:local‐
2755 time_to_universaltime(Localtime).
2756 Examples:
2758 > erlang:localtime_to_universaltime({{1996,11,6},{14,45,17}}, true).
2760 {{1996,11,6},{12,45,17}}
2761 > erlang:localtime_to_universaltime({{1996,11,6},{14,45,17}}, false).
2762 {{1996,11,6},{13,45,17}}
2763 > erlang:localtime_to_universaltime({{1996,11,6},{14,45,17}}, undefined).
2764 {{1996,11,6},{13,45,17}}
2765 Failure: badarg if Localtime denotes an invalid date and time.
2767 make_ref() -> reference()
2769 Returns a unique reference. The reference is unique among con‐
2771 nected nodes.
2772 Warning:
2774 Known issue: When a node is restarted multiple times with the
2775 same node name, references created on a newer node can be mis‐
2776 taken for a reference created on an older node with the same
2777 node name.
2778 erlang:make_tuple(Arity, InitialValue) -> tuple()
2781 Types:
2783 Arity = arity()
2785 InitialValue = term()
2786 Creates a new tuple of the specified Arity, where all elements
2788 are InitialValue, for example:
2789 > erlang:make_tuple(4, []).
2791 {[],[],[],[]}
2792 erlang:make_tuple(Arity, DefaultValue, InitList) -> tuple()
2794 Types:
2796 Arity = arity()
2798 DefaultValue = term()
2799 InitList = [{Position :: integer() >= 1, term()}]
2800 Creates a tuple of size Arity, where each element has value
2802 DefaultValue, and then fills in values from InitList. Each list
2803 element in InitList must be a two-tuple, where the first element
2804 is a position in the newly created tuple and the second element
2805 is any term. If a position occurs more than once in the list,
2806 the term corresponding to the last occurrence is used. Example:
2807 > erlang:make_tuple(5, [], [{2,ignored},{5,zz},{2,aa}]).
2809 {[],aa,[],[],zz}
2810 map_size(Map) -> integer() >= 0
2812 Types:
2814 Map = map()
2816 Returns an integer, which is the number of key-value pairs in
2818 Map, for example:
2819 > map_size(#{a=>1, b=>2, c=>3}).
2821 3
2822 Allowed in guard tests.
2824 erlang:match_spec_test(MatchAgainst, MatchSpec, Type) ->
2826 TestResult
2827 Types:
2829 MatchAgainst = [term()] | tuple()
2831 MatchSpec = term()
2832 Type = table | trace
2833 TestResult =
2834 {ok, term(), [return_trace], [{error | warning,
2835 string()}]} |
2836 {error, [{error | warning, string()}]}
2837 Tests a match specification used in calls to ets:select/2 and
2839 erlang:trace_pattern/3. The function tests both a match specifi‐
2840 cation for "syntactic" correctness and runs the match specifica‐
2841 tion against the object. If the match specification contains
2842 errors, the tuple {error, Errors} is returned, where Errors is a
2843 list of natural language descriptions of what was wrong with the
2844 match specification.
2845 If Type is table, the object to match against is to be a tuple.
2847 The function then returns {ok,Result,[],Warnings}, where Result
2848 is what would have been the result in a real ets:select/2 call,
2849 or false if the match specification does not match the object
2850 tuple.
2851 If Type is trace, the object to match against is to be a list.
2853 The function returns {ok, Result, Flags, Warnings}, where Result
2854 is one of the following:
2855 * true if a trace message is to be emitted
2857 * false if a trace message is not to be emitted
2859 * The message term to be appended to the trace message
2861 Flags is a list containing all the trace flags to be enabled,
2863 currently this is only return_trace.
2864 This is a useful debugging and test tool, especially when writ‐
2866 ing complicated match specifications.
2867 See also ets:test_ms/2.
2869 max(Term1, Term2) -> Maximum
2871 Types:
2873 Term1 = Term2 = Maximum = term()
2875 Returns the largest of Term1 and Term2. If the terms are equal,
2877 Term1 is returned.
2878 erlang:md5(Data) -> Digest
2880 Types:
2882 Data = iodata()
2884 Digest = binary()
2885 Computes an MD5 message digest from Data, where the length of
2887 the digest is 128 bits (16 bytes). Data is a binary or a list of
2888 small integers and binaries.
2889 For more information about MD5, see RFC 1321 - The MD5 Message-
2891 Digest Algorithm.
2892 Warning:
2894 The MD5 Message-Digest Algorithm is not considered safe for
2895 code-signing or software-integrity purposes.
2896 erlang:md5_final(Context) -> Digest
2899 Types:
2901 Context = Digest = binary()
2903 Finishes the update of an MD5 Context and returns the computed
2905 MD5 message digest.
2906 erlang:md5_init() -> Context
2908 Types:
2910 Context = binary()
2912 Creates an MD5 context, to be used in the following calls to
2914 md5_update/2.
2915 erlang:md5_update(Context, Data) -> NewContext
2917 Types:
2919 Context = binary()
2921 Data = iodata()
2922 NewContext = binary()
2923 Update an MD5 Context with Data and returns a NewContext.
2925 erlang:memory() -> [{Type, Size}]
2927 Types:
2929 Type = memory_type()
2931 Size = integer() >= 0
2932 memory_type() =
2933 total |
2934 processes |
2935 processes_used |
2936 system |
2937 atom |
2938 atom_used |
2939 binary |
2940 code |
2941 ets |
2942 low |
2943 maximum
2944 Returns a list with information about memory dynamically allo‐
2946 cated by the Erlang emulator. Each list element is a tuple
2947 {Type, Size}. The first element Type is an atom describing mem‐
2948 ory type. The second element Size is the memory size in bytes.
2949 Memory types:
2951 total:
2953 The total amount of memory currently allocated. This is the
2954 same as the sum of the memory size for processes and system.
2955 processes:
2957 The total amount of memory currently allocated for the
2958 Erlang processes.
2959 processes_used:
2961 The total amount of memory currently used by the Erlang pro‐
2962 cesses. This is part of the memory presented as processes
2963 memory.
2964 system:
2966 The total amount of memory currently allocated for the emu‐
2967 lator that is not directly related to any Erlang process.
2968 Memory presented as processes is not included in this mem‐
2969 ory. instrument(3) can be used to get a more detailed break‐
2970 down of what memory is part of this type.
2971 atom:
2973 The total amount of memory currently allocated for atoms.
2974 This memory is part of the memory presented as system mem‐
2975 ory.
2976 atom_used:
2978 The total amount of memory currently used for atoms. This
2979 memory is part of the memory presented as atom memory.
2980 binary:
2982 The total amount of memory currently allocated for binaries.
2983 This memory is part of the memory presented as system mem‐
2984 ory.
2985 code:
2987 The total amount of memory currently allocated for Erlang
2988 code. This memory is part of the memory presented as system
2989 memory.
2990 ets:
2992 The total amount of memory currently allocated for ETS
2993 tables. This memory is part of the memory presented as sys‐
2994 tem memory.
2995 low:
2997 Only on 64-bit halfword emulator. The total amount of memory
2998 allocated in low memory areas that are restricted to < 4 GB,
2999 although the system can have more memory.
3000 Can be removed in a future release of the halfword emulator.
3002 maximum:
3004 The maximum total amount of memory allocated since the emu‐
3005 lator was started. This tuple is only present when the emu‐
3006 lator is run with instrumentation.
3007 For information on how to run the emulator with instrumenta‐
3009 tion, see instrument(3) and/or erl(1).
3010 Note:
3012 The system value is not complete. Some allocated memory that is
3013 to be part of this value is not.
3014 When the emulator is run with instrumentation, the system value
3016 is more accurate, but memory directly allocated for malloc (and
3017 friends) is still not part of the system value. Direct calls to
3018 malloc are only done from OS-specific runtime libraries and per‐
3019 haps from user-implemented Erlang drivers that do not use the
3020 memory allocation functions in the driver interface.
3021 As the total value is the sum of processes and system, the error
3023 in system propagates to the total value.
3024 The different amounts of memory that are summed are not gathered
3026 atomically, which introduces an error in the result.
3027 The different values have the following relation to each other.
3030 Values beginning with an uppercase letter is not part of the
3031 result.
3032 total = processes + system
3034 processes = processes_used + ProcessesNotUsed
3035 system = atom + binary + code + ets + OtherSystem
3036 atom = atom_used + AtomNotUsed
3037 RealTotal = processes + RealSystem
3038 RealSystem = system + MissedSystem
3039 More tuples in the returned list can be added in a future
3041 release.
3042 Note:
3044 The total value is supposed to be the total amount of memory
3045 dynamically allocated by the emulator. Shared libraries, the
3046 code of the emulator itself, and the emulator stacks are not
3047 supposed to be included. That is, the total value is not sup‐
3048 posed to be equal to the total size of all pages mapped to the
3049 emulator.
3050 Also, because of fragmentation and prereservation of memory
3052 areas, the size of the memory segments containing the dynami‐
3053 cally allocated memory blocks can be much larger than the total
3054 size of the dynamically allocated memory blocks.
3055 Note:
3058 As from ERTS 5.6.4, erlang:memory/0 requires that all
3059 erts_alloc(3) allocators are enabled (default behavior).
3060 Failure: notsup if an erts_alloc(3) allocator has been disabled.
3063 erlang:memory(Type :: memory_type()) -> integer() >= 0
3065 erlang:memory(TypeList :: [memory_type()]) ->
3067 [{memory_type(), integer() >= 0}]
3068 Types:
3070 memory_type() =
3072 total |
3073 processes |
3074 processes_used |
3075 system |
3076 atom |
3077 atom_used |
3078 binary |
3079 code |
3080 ets |
3081 low |
3082 maximum
3083 Returns the memory size in bytes allocated for memory of type
3085 Type. The argument can also be specified as a list of mem‐
3086 ory_type() atoms, in which case a corresponding list of {mem‐
3087 ory_type(), Size :: integer >= 0} tuples is returned.
3088 Note:
3090 As from ERTS 5.6.4, erlang:memory/1 requires that all
3091 erts_alloc(3) allocators are enabled (default behavior).
3092 Failures:
3095 badarg:
3097 If Type is not one of the memory types listed in the
3098 description of erlang:memory/0.
3099 badarg:
3101 If maximum is passed as Type and the emulator is not run in
3102 instrumented mode.
3103 notsup:
3105 If an erts_alloc(3) allocator has been disabled.
3106 See also erlang:memory/0.
3108 min(Term1, Term2) -> Minimum
3110 Types:
3112 Term1 = Term2 = Minimum = term()
3114 Returns the smallest of Term1 and Term2. If the terms are equal,
3116 Term1 is returned.
3117 module_loaded(Module) -> boolean()
3119 Types:
3121 Module = module()
3123 Returns true if the module Module is loaded, otherwise false. It
3125 does not attempt to load the module.
3126 Warning:
3128 This BIF is intended for the code server (see code(3)) and is
3129 not to be used elsewhere.
3130 monitor(Type :: process, Item :: monitor_process_identifier()) ->
3133 MonitorRef
3134 monitor(Type :: port, Item :: monitor_port_identifier()) ->
3136 MonitorRef
3137 monitor(Type :: time_offset, Item :: clock_service) -> MonitorRef
3139 Types:
3141 MonitorRef = reference()
3143 registered_name() = atom()
3144 registered_process_identifier() =
3145 registered_name() | {registered_name(), node()}
3146 monitor_process_identifier() =
3147 pid() | registered_process_identifier()
3148 monitor_port_identifier() = port() | registered_name()
3149 Sends a monitor request of type Type to the entity identified by
3151 Item. If the monitored entity does not exist or it changes moni‐
3152 tored state, the caller of monitor/2 is notified by a message on
3153 the following format:
3154 {Tag, MonitorRef, Type, Object, Info}
3156 Note:
3158 The monitor request is an asynchronous signal. That is, it takes
3159 time before the signal reaches its destination.
3160 Type can be one of the following atoms: process, port or
3163 time_offset.
3164 A process or port monitor is triggered only once, after that it
3166 is removed from both monitoring process and the monitored
3167 entity. Monitors are fired when the monitored process or port
3168 terminates, does not exist at the moment of creation, or if the
3169 connection to it is lost. If the connection to it is lost, we do
3170 not know if it still exists. The monitoring is also turned off
3171 when demonitor/1 is called.
3172 A process or port monitor by name resolves the RegisteredName to
3174 pid() or port() only once at the moment of monitor instantia‐
3175 tion, later changes to the name registration will not affect the
3176 existing monitor.
3177 When a process or port monitor is triggered, a 'DOWN' message is
3179 sent that has the following pattern:
3180 {'DOWN', MonitorRef, Type, Object, Info}
3182 In the monitor message MonitorRef and Type are the same as
3184 described earlier, and:
3185 Object:
3187 The monitored entity, which triggered the event. When moni‐
3188 toring a local process or port, Object will be equal to the
3189 pid() or port() that was being monitored. When monitoring
3190 process or port by name, Object will have format {Regis‐
3191 teredName, Node} where RegisteredName is the name which has
3192 been used with monitor/2 call and Node is local or remote
3193 node name (for ports monitored by name, Node is always local
3194 node name).
3195 Info:
3197 Either the exit reason of the process, noproc (process or
3198 port did not exist at the time of monitor creation), or
3199 noconnection (no connection to the node where the monitored
3200 process resides).
3201 If an attempt is made to monitor a process on an older node
3203 (where remote process monitoring is not implemented or where
3204 remote process monitoring by registered name is not imple‐
3205 mented), the call fails with badarg.
3206 Note:
3208 The format of the 'DOWN' message changed in ERTS 5.2 (Erlang/OTP
3209 R9B) for monitoring by registered name. Element Object of the
3210 'DOWN' message could in earlier versions sometimes be the
3211 process identifier of the monitored process and sometimes be the
3212 registered name. Now element Object is always a tuple consisting
3213 of the registered name and the node name. Processes on new nodes
3214 (ERTS 5.2 or higher versions) always get 'DOWN' messages on the
3215 new format even if they are monitoring processes on old nodes.
3216 Processes on old nodes always get 'DOWN' messages on the old
3217 format.
3218 Monitoring a process:
3221 Creates monitor between the current process and another
3222 process identified by Item, which can be a pid() (local or
3223 remote), an atom RegisteredName or a tuple {RegisteredName,
3224 Node} for a registered process, located elsewhere.
3225 Monitoring a port:
3227 Creates monitor between the current process and a port iden‐
3228 tified by Item, which can be a port() (only local), an atom
3229 RegisteredName or a tuple {RegisteredName, Node} for a reg‐
3230 istered port, located on this node. Note, that attempt to
3231 monitor a remote port will result in badarg.
3232 Monitoring a time_offset:
3234 Monitors changes in time offset between Erlang monotonic
3235 time and Erlang system time. One valid Item exists in combi‐
3236 nation with the time_offset Type, namely the atom clock_ser‐
3237 vice. Notice that the atom clock_service is not the regis‐
3238 tered name of a process. In this case it serves as an iden‐
3239 tifier of the runtime system internal clock service at cur‐
3240 rent runtime system instance.
3241 The monitor is triggered when the time offset is changed.
3243 This either if the time offset value is changed, or if the
3244 offset is changed from preliminary to final during finaliza‐
3245 tion of the time offset when the single time warp mode is
3246 used. When a change from preliminary to final time offset is
3247 made, the monitor is triggered once regardless of whether
3248 the time offset value was changed or not.
3249 If the runtime system is in multi time warp mode, the time
3251 offset is changed when the runtime system detects that the
3252 OS system time has changed. The runtime system does, how‐
3253 ever, not detect this immediately when it occurs. A task
3254 checking the time offset is scheduled to execute at least
3255 once a minute, so under normal operation this is to be
3256 detected within a minute, but during heavy load it can take
3257 longer time.
3258 The monitor is not automatically removed after it has been
3260 triggered. That is, repeated changes of the time offset
3261 trigger the monitor repeatedly.
3262 When the monitor is triggered a 'CHANGE' message is sent to
3264 the monitoring process. A 'CHANGE' message has the following
3265 pattern:
3266 {'CHANGE', MonitorRef, Type, Item, NewTimeOffset}
3268 where MonitorRef, Type, and Item are the same as described
3270 above, and NewTimeOffset is the new time offset.
3271 When the 'CHANGE' message has been received you are guaran‐
3273 teed not to retrieve the old time offset when calling
3274 erlang:time_offset(). Notice that you can observe the change
3275 of the time offset when calling erlang:time_offset() before
3276 you get the 'CHANGE' message.
3277 Making several calls to monitor/2 for the same Item and/or Type
3279 is not an error; it results in as many independent monitoring
3280 instances.
3281 The monitor functionality is expected to be extended. That is,
3283 other Types and Items are expected to be supported in a future
3284 release.
3285 Note:
3287 If or when monitor/2 is extended, other possible values for Tag,
3288 Object, and Info in the monitor message will be introduced.
3289 monitor_node(Node, Flag) -> true
3292 Types:
3294 Node = node()
3296 Flag = boolean()
3297 Monitor the status of the node Node. If Flag is true, monitoring
3299 is turned on. If Flag is false, monitoring is turned off.
3300 Making several calls to monitor_node(Node, true) for the same
3302 Node is not an error; it results in as many independent monitor‐
3303 ing instances.
3304 If Node fails or does not exist, the message {nodedown, Node} is
3306 delivered to the process. If a process has made two calls to
3307 monitor_node(Node, true) and Node terminates, two nodedown mes‐
3308 sages are delivered to the process. If there is no connection to
3309 Node, an attempt is made to create one. If this fails, a node‐
3310 down message is delivered.
3311 Nodes connected through hidden connections can be monitored as
3313 any other nodes.
3314 Failure: badarg if the local node is not alive.
3316 erlang:monitor_node(Node, Flag, Options) -> true
3318 Types:
3320 Node = node()
3322 Flag = boolean()
3323 Options = [Option]
3324 Option = allow_passive_connect
3325 Behaves as monitor_node/2 except that it allows an extra option
3327 to be specified, namely allow_passive_connect. This option
3328 allows the BIF to wait the normal network connection time-out
3329 for the monitored node to connect itself, even if it cannot be
3330 actively connected from this node (that is, it is blocked). The
3331 state where this can be useful can only be achieved by using the
3332 Kernel option dist_auto_connect once. If that option is not
3333 used, option allow_passive_connect has no effect.
3334 Note:
3336 Option allow_passive_connect is used internally and is seldom
3337 needed in applications where the network topology and the Kernel
3338 options in effect are known in advance.
3339 Failure: badarg if the local node is not alive or the option
3342 list is malformed.
3343 erlang:monotonic_time() -> integer()
3345 Returns the current Erlang monotonic time in native time unit.
3347 This is a monotonically increasing time since some unspecified
3348 point in time.
3349 Note:
3351 This is a monotonically increasing time, but not a strictly
3352 monotonically increasing time. That is, consecutive calls to
3353 erlang:monotonic_time/0 can produce the same result.
3354 Different runtime system instances will use different unspeci‐
3356 fied points in time as base for their Erlang monotonic clocks.
3357 That is, it is pointless comparing monotonic times from differ‐
3358 ent runtime system instances. Different runtime system instances
3359 can also place this unspecified point in time different relative
3360 runtime system start. It can be placed in the future (time at
3361 start is a negative value), the past (time at start is a posi‐
3362 tive value), or the runtime system start (time at start is
3363 zero). The monotonic time at runtime system start can be
3364 retrieved by calling erlang:system_info(start_time).
3365 erlang:monotonic_time(Unit) -> integer()
3368 Types:
3370 Unit = time_unit()
3372 Returns the current Erlang monotonic time converted into the
3374 Unit passed as argument.
3375 Same as calling erlang:convert_time_unit(erlang:mono‐
3377 tonic_time(), native, Unit), however optimized for commonly used
3378 Units.
3379 erlang:nif_error(Reason) -> no_return()
3381 Types:
3383 Reason = term()
3385 Works exactly like error/1, but Dialyzer thinks that this BIF
3387 will return an arbitrary term. When used in a stub function for
3388 a NIF to generate an exception when the NIF library is not
3389 loaded, Dialyzer does not generate false warnings.
3390 erlang:nif_error(Reason, Args) -> no_return()
3392 Types:
3394 Reason = term()
3396 Args = [term()]
3397 Works exactly like error/2, but Dialyzer thinks that this BIF
3399 will return an arbitrary term. When used in a stub function for
3400 a NIF to generate an exception when the NIF library is not
3401 loaded, Dialyzer does not generate false warnings.
3402 node() -> Node
3404 Types:
3406 Node = node()
3408 Returns the name of the local node. If the node is not alive,
3410 nonode@nohost is returned instead.
3411 Allowed in guard tests.
3413 node(Arg) -> Node
3415 Types:
3417 Arg = pid() | port() | reference()
3419 Node = node()
3420 Returns the node where Arg originates. Arg can be a process
3422 identifier, a reference, or a port. If the local node is not
3423 alive, nonode@nohost is returned.
3424 Allowed in guard tests.
3426 nodes() -> Nodes
3428 Types:
3430 Nodes = [node()]
3432 Returns a list of all visible nodes in the system, except the
3434 local node. Same as nodes(visible).
3435 nodes(Arg) -> Nodes
3437 Types:
3439 Arg = NodeType | [NodeType]
3441 NodeType = visible | hidden | connected | this | known
3442 Nodes = [node()]
3443 Returns a list of nodes according to the argument specified. The
3445 returned result, when the argument is a list, is the list of
3446 nodes satisfying the disjunction(s) of the list elements.
3447 NodeTypes:
3449 visible:
3451 Nodes connected to this node through normal connections.
3452 hidden:
3454 Nodes connected to this node through hidden connections.
3455 connected:
3457 All nodes connected to this node.
3458 this:
3460 This node.
3461 known:
3463 Nodes that are known to this node. That is, connected nodes
3464 and nodes referred to by process identifiers, port identi‐
3465 fiers, and references located on this node. The set of known
3466 nodes is garbage collected. Notice that this garbage collec‐
3467 tion can be delayed. For more information, see erlang:sys‐
3468 tem_info(delayed_node_table_gc).
3469 Some equalities: [node()] = nodes(this), nodes(connected) =
3471 nodes([visible, hidden]), and nodes() = nodes(visible).
3472 now() -> Timestamp
3474 Types:
3476 Timestamp = timestamp()
3478 timestamp() =
3479 {MegaSecs :: integer() >= 0,
3480 Secs :: integer() >= 0,
3481 MicroSecs :: integer() >= 0}
3482 Warning:
3484 This function is deprecated. Do not use it.
3485 For more information, see section Time and Time Correction in
3487 the User's Guide. Specifically, section Dos and Dont's
3488 describes what to use instead of erlang:now/0.
3489 Returns the tuple {MegaSecs, Secs, MicroSecs}, which is the
3492 elapsed time since 00:00 GMT, January 1, 1970 (zero hour), if
3493 provided by the underlying OS. Otherwise some other point in
3494 time is chosen. It is also guaranteed that the following calls
3495 to this BIF return continuously increasing values. Hence, the
3496 return value from erlang:now/0 can be used to generate unique
3497 time stamps. If it is called in a tight loop on a fast machine,
3498 the time of the node can become skewed.
3499 Can only be used to check the local time of day if the time-zone
3501 information of the underlying OS is properly configured.
3502 open_port(PortName, PortSettings) -> port()
3504 Types:
3506 PortName =
3508 {spawn, Command :: string() | binary()} |
3509 {spawn_driver, Command :: string() | binary()} |
3510 {spawn_executable, FileName :: file:name()} |
3511 {fd, In :: integer() >= 0, Out :: integer() >= 0}
3512 PortSettings = [Opt]
3513 Opt =
3514 {packet, N :: 1 | 2 | 4} |
3515 stream |
3516 {line, L :: integer() >= 0} |
3517 {cd, Dir :: string() | binary()} |
3518 {env, Env :: [{Name :: string(), Val :: string() |
3519 false}]} |
3520 {args, [string() | binary()]} |
3521 {arg0, string() | binary()} |
3522 exit_status |
3523 use_stdio |
3524 nouse_stdio |
3525 stderr_to_stdout |
3526 in |
3527 out |
3528 binary |
3529 eof |
3530 {parallelism, Boolean :: boolean()} |
3531 hide
3532 Returns a port identifier as the result of opening a new Erlang
3534 port. A port can be seen as an external Erlang process.
3535 The name of the executable as well as the arguments specifed in
3537 cd, env, args, and arg0 are subject to Unicode filename transla‐
3538 tion if the system is running in Unicode filename mode. To avoid
3539 translation or to force, for example UTF-8, supply the exe‐
3540 cutable and/or arguments as a binary in the correct encoding.
3541 For details, see the module file(3), the function
3542 file:native_name_encoding/0 in Kernel, and the Using Unicode in
3543 Erlang User's Guide.
3544 Note:
3546 The characters in the name (if specified as a list) can only be
3547 > 255 if the Erlang virtual machine is started in Unicode file‐
3548 name translation mode. Otherwise the name of the executable is
3549 limited to the ISO Latin-1 character set.
3550 PortNames:
3553 {spawn, Command}:
3555 Starts an external program. Command is the name of the
3556 external program to be run. Command runs outside the Erlang
3557 work space unless an Erlang driver with the name Command is
3558 found. If found, that driver is started. A driver runs in
3559 the Erlang work space, which means that it is linked with
3560 the Erlang runtime system.
3561 When starting external programs on Solaris, the system call
3563 vfork is used in preference to fork for performance reasons,
3564 although it has a history of being less robust. If there are
3565 problems using vfork, setting environment variable
3566 ERL_NO_VFORK to any value causes fork to be used instead.
3567 For external programs, PATH is searched (or an equivalent
3569 method is used to find programs, depending on the OS). This
3570 is done by invoking the shell on certain platforms. The
3571 first space-separated token of the command is considered as
3572 the name of the executable (or driver). This (among other
3573 things) makes this option unsuitable for running programs
3574 with spaces in filenames or directory names. If spaces in
3575 executable filenames are desired, use {spawn_executable,
3576 Command} instead.
3577 {spawn_driver, Command}:
3579 Works like {spawn, Command}, but demands the first (space-
3580 separated) token of the command to be the name of a loaded
3581 driver. If no driver with that name is loaded, a badarg
3582 error is raised.
3583 {spawn_executable, FileName}:
3585 Works like {spawn, FileName}, but only runs external exe‐
3586 cutables. FileName in its whole is used as the name of the
3587 executable, including any spaces. If arguments are to be
3588 passed, the PortSettings args and arg0 can be used.
3589 The shell is usually not invoked to start the program, it is
3591 executed directly. PATH (or equivalent) is not searched. To
3592 find a program in PATH to execute, use os:find_executable/1.
3593 Only if a shell script or .bat file is executed, the appro‐
3595 priate command interpreter is invoked implicitly, but there
3596 is still no command-argument expansion or implicit PATH
3597 search.
3598 If FileName cannot be run, an error exception is raised,
3600 with the POSIX error code as the reason. The error reason
3601 can differ between OSs. Typically the error enoent is raised
3602 when an attempt is made to run a program that is not found
3603 and eacces is raised when the specified file is not exe‐
3604 cutable.
3605 {fd, In, Out}:
3607 Allows an Erlang process to access any currently opened file
3608 descriptors used by Erlang. The file descriptor In can be
3609 used for standard input, and the file descriptor Out for
3610 standard output. It is only used for various servers in the
3611 Erlang OS (shell and user). Hence, its use is limited.
3612 PortSettings is a list of settings for the port. The valid set‐
3614 tings are as follows:
3615 {packet, N}:
3617 Messages are preceded by their length, sent in N bytes, with
3618 the most significant byte first. The valid values for N are
3619 1, 2, and 4.
3620 stream:
3622 Output messages are sent without packet lengths. A user-
3623 defined protocol must be used between the Erlang process and
3624 the external object.
3625 {line, L}:
3627 Messages are delivered on a per line basis. Each line
3628 (delimited by the OS-dependent newline sequence) is deliv‐
3629 ered in a single message. The message data format is {Flag,
3630 Line}, where Flag is eol or noeol, and Line is the data
3631 delivered (without the newline sequence).
3632 L specifies the maximum line length in bytes. Lines longer
3634 than this are delivered in more than one message, with Flag
3635 set to noeol for all but the last message. If end of file is
3636 encountered anywhere else than immediately following a new‐
3637 line sequence, the last line is also delivered with Flag set
3638 to noeol. Otherwise lines are delivered with Flag set to
3639 eol.
3640 The {packet, N} and {line, L} settings are mutually exclu‐
3642 sive.
3643 {cd, Dir}:
3645 Only valid for {spawn, Command} and {spawn_executable, File‐
3646 Name}. The external program starts using Dir as its working
3647 directory. Dir must be a string.
3648 {env, Env}:
3650 Only valid for {spawn, Command}, and {spawn_executable,
3651 FileName}. The environment of the started process is
3652 extended using the environment specifications in Env.
3653 Env is to be a list of tuples {Name, Val}, where Name is the
3655 name of an environment variable, and Val is the value it is
3656 to have in the spawned port process. Both Name and Val must
3657 be strings. The one exception is Val being the atom false
3658 (in analogy with os:getenv/1, which removes the environment
3659 variable.
3660 {args, [ string() | binary() ]}:
3662 Only valid for {spawn_executable, FileName} and specifies
3663 arguments to the executable. Each argument is specified as a
3664 separate string and (on Unix) eventually ends up as one ele‐
3665 ment each in the argument vector. On other platforms, a sim‐
3666 ilar behavior is mimicked.
3667 The arguments are not expanded by the shell before they are
3669 supplied to the executable. Most notably this means that
3670 file wildcard expansion does not occur. To expand wildcards
3671 for the arguments, use filelib:wildcard/1. Notice that even
3672 if the program is a Unix shell script, meaning that the
3673 shell ultimately is invoked, wildcard expansion does not
3674 occur, and the script is provided with the untouched argu‐
3675 ments. On Windows, wildcard expansion is always up to the
3676 program itself, therefore this is not an issue.
3677 The executable name (also known as argv[0]) is not to be
3679 specified in this list. The proper executable name is auto‐
3680 matically used as argv[0], where applicable.
3681 If you explicitly want to set the program name in the argu‐
3683 ment vector, option arg0 can be used.
3684 {arg0, string() | binary()}:
3686 Only valid for {spawn_executable, FileName} and explicitly
3687 specifies the program name argument when running an exe‐
3688 cutable. This can in some circumstances, on some OSs, be
3689 desirable. How the program responds to this is highly sys‐
3690 tem-dependent and no specific effect is guaranteed.
3691 exit_status:
3693 Only valid for {spawn, Command}, where Command refers to an
3694 external program, and for {spawn_executable, FileName}.
3695 When the external process connected to the port exits, a
3697 message of the form {Port,{exit_status,Status}} is sent to
3698 the connected process, where Status is the exit status of
3699 the external process. If the program aborts on Unix, the
3700 same convention is used as the shells do (that is, 128+sig‐
3701 nal).
3702 If option eof is specified also, the messages eof and
3704 exit_status appear in an unspecified order.
3705 If the port program closes its stdout without exiting,
3707 option exit_status does not work.
3708 use_stdio:
3710 Only valid for {spawn, Command} and {spawn_executable, File‐
3711 Name}. It allows the standard input and output (file
3712 descriptors 0 and 1) of the spawned (Unix) process for com‐
3713 munication with Erlang.
3714 nouse_stdio:
3716 The opposite of use_stdio. It uses file descriptors 3 and 4
3717 for communication with Erlang.
3718 stderr_to_stdout:
3720 Affects ports to external programs. The executed program
3721 gets its standard error file redirected to its standard out‐
3722 put file. stderr_to_stdout and nouse_stdio are mutually
3723 exclusive.
3724 overlapped_io:
3726 Affects ports to external programs on Windows only. The
3727 standard input and standard output handles of the port pro‐
3728 gram are, if this option is supplied, opened with flag
3729 FILE_FLAG_OVERLAPPED, so that the port program can (and
3730 must) do overlapped I/O on its standard handles. This is not
3731 normally the case for simple port programs, but an option of
3732 value for the experienced Windows programmer. On all other
3733 platforms, this option is silently discarded.
3734 in:
3736 The port can only be used for input.
3737 out:
3739 The port can only be used for output.
3740 binary:
3742 All I/O from the port is binary data objects as opposed to
3743 lists of bytes.
3744 eof:
3746 The port is not closed at the end of the file and does not
3747 produce an exit signal. Instead, it remains open and a
3748 {Port, eof} message is sent to the process holding the port.
3749 hide:
3751 When running on Windows, suppresses creation of a new con‐
3752 sole window when spawning the port program. (This option has
3753 no effect on other platforms.)
3754 {parallelism, Boolean}:
3756 Sets scheduler hint for port parallelism. If set to true,
3759 the virtual machine schedules port tasks; when doing so, it
3760 improves parallelism in the system. If set to false, the
3761 virtual machine tries to perform port tasks immediately,
3762 improving latency at the expense of parallelism. The default
3763 can be set at system startup by passing command-line argu‐
3764 ment +spp to erl(1).
3765 Default is stream for all port types and use_stdio for spawned
3767 ports.
3768 Failure: if the port cannot be opened, the exit reason is
3770 badarg, system_limit, or the POSIX error code that most closely
3771 describes the error, or einval if no POSIX code is appropriate:
3772 badarg:
3774 Bad input arguments to open_port.
3775 system_limit:
3777 All available ports in the Erlang emulator are in use.
3778 enomem:
3780 Not enough memory to create the port.
3781 eagain:
3783 No more available OS processes.
3784 enametoolong:
3786 Too long external command.
3787 emfile:
3789 No more available file descriptors (for the OS process that
3790 the Erlang emulator runs in).
3791 enfile:
3793 Full file table (for the entire OS).
3794 eacces:
3796 Command specified in {spawn_executable, Command} does not
3797 point out an executable file.
3798 enoent:
3800 FileName specified in {spawn_executable, FileName} does not
3801 point out an existing file.
3802 During use of a port opened using {spawn, Name}, {spawn_driver,
3804 Name}, or {spawn_executable, Name}, errors arising when sending
3805 messages to it are reported to the owning process using signals
3806 of the form {'EXIT', Port, PosixCode}. For the possible values
3807 of PosixCode, see file(3).
3808 The maximum number of ports that can be open at the same time
3810 can be configured by passing command-line flag +Q to erl(1).
3811 erlang:phash(Term, Range) -> Hash
3813 Types:
3815 Term = term()
3817 Range = Hash = integer() >= 1
3818 Range = 1..2^32, Hash = 1..Range
3819 Portable hash function that gives the same hash for the same
3821 Erlang term regardless of machine architecture and ERTS version
3822 (the BIF was introduced in ERTS 4.9.1.1). The function returns a
3823 hash value for Term within the range 1..Range. The maximum value
3824 for Range is 2^32.
3825 erlang:phash2(Term) -> Hash
3827 erlang:phash2(Term, Range) -> Hash
3829 Types:
3831 Term = term()
3833 Range = integer() >= 1
3834 1..2^32
3835 Hash = integer() >= 0
3836 0..Range-1
3837 Portable hash function that gives the same hash for the same
3839 Erlang term regardless of machine architecture and ERTS version
3840 (the BIF was introduced in ERTS 5.2). The function returns a
3841 hash value for Term within the range 0..Range-1. The maximum
3842 value for Range is 2^32. When without argument Range, a value in
3843 the range 0..2^27-1 is returned.
3844 This BIF is always to be used for hashing terms. It distributes
3846 small integers better than phash/2, and it is faster for bignums
3847 and binaries.
3848 Notice that the range 0..Range-1 is different from the range of
3850 phash/2, which is 1..Range.
3851 pid_to_list(Pid) -> string()
3853 Types:
3855 Pid = pid()
3857 Returns a string corresponding to the text representation of
3859 Pid.
3860 erlang:port_call(Port, Operation, Data) -> term()
3862 Types:
3864 Port = port() | atom()
3866 Operation = integer()
3867 Data = term()
3868 Performs a synchronous call to a port. The meaning of Operation
3870 and Data depends on the port, that is, on the port driver. Not
3871 all port drivers support this feature.
3872 Port is a port identifier, referring to a driver.
3874 Operation is an integer, which is passed on to the driver.
3876 Data is any Erlang term. This data is converted to binary term
3878 format and sent to the port.
3879 Returns a term from the driver. The meaning of the returned data
3881 also depends on the port driver.
3882 Failures:
3884 badarg:
3886 If Port is not an identifier of an open port, or the regis‐
3887 tered name of an open port. If the calling process was pre‐
3888 viously linked to the closed port, identified by Port, the
3889 exit signal from the port is guaranteed to be delivered
3890 before this badarg exception occurs.
3891 badarg:
3893 If Operation does not fit in a 32-bit integer.
3894 badarg:
3896 If the port driver does not support synchronous control
3897 operations.
3898 badarg:
3900 If the port driver so decides for any reason (probably
3901 something wrong with Operation or Data).
3902 port_close(Port) -> true
3904 Types:
3906 Port = port() | atom()
3908 Closes an open port. Roughly the same as Port ! {self(), close}
3910 except for the error behavior (see below), being synchronous,
3911 and that the port does not reply with {Port, closed}. Any
3912 process can close a port with port_close/1, not only the port
3913 owner (the connected process). If the calling process is linked
3914 to the port identified by Port, the exit signal from the port is
3915 guaranteed to be delivered before port_close/1 returns.
3916 For comparison: Port ! {self(), close} only fails with badarg if
3918 Port does not refer to a port or a process. If Port is a closed
3919 port, nothing happens. If Port is an open port and the calling
3920 process is the port owner, the port replies with {Port, closed}
3921 when all buffers have been flushed and the port really closes.
3922 If the calling process is not the port owner, the port owner
3923 fails with badsig.
3924 Notice that any process can close a port using Port ! {Por‐
3926 tOwner, close} as if it itself was the port owner, but the reply
3927 always goes to the port owner.
3928 As from Erlang/OTP R16, Port ! {PortOwner, close} is truly asyn‐
3930 chronous. Notice that this operation has always been documented
3931 as an asynchronous operation, while the underlying implementa‐
3932 tion has been synchronous. port_close/1 is however still fully
3933 synchronous because of its error behavior.
3934 Failure: badarg if Port is not an identifier of an open port, or
3936 the registered name of an open port. If the calling process was
3937 previously linked to the closed port, identified by Port, the
3938 exit signal from the port is guaranteed to be delivered before
3939 this badarg exception occurs.
3940 port_command(Port, Data) -> true
3942 Types:
3944 Port = port() | atom()
3946 Data = iodata()
3947 Sends data to a port. Same as Port ! {PortOwner, {command,
3949 Data}} except for the error behavior and being synchronous (see
3950 below). Any process can send data to a port with port_command/2,
3951 not only the port owner (the connected process).
3952 For comparison: Port ! {PortOwner, {command, Data}} only fails
3954 with badarg if Port does not refer to a port or a process. If
3955 Port is a closed port, the data message disappears without a
3956 sound. If Port is open and the calling process is not the port
3957 owner, the port owner fails with badsig. The port owner fails
3958 with badsig also if Data is an invalid I/O list.
3959 Notice that any process can send to a port using Port ! {Por‐
3961 tOwner, {command, Data}} as if it itself was the port owner.
3962 If the port is busy, the calling process is suspended until the
3964 port is not busy any more.
3965 As from Erlang/OTP R16, Port ! {PortOwner, {command, Data}} is
3967 truly asynchronous. Notice that this operation has always been
3968 documented as an asynchronous operation, while the underlying
3969 implementation has been synchronous. port_command/2 is however
3970 still fully synchronous because of its error behavior.
3971 Failures:
3973 badarg:
3975 If Port is not an identifier of an open port, or the regis‐
3976 tered name of an open port. If the calling process was pre‐
3977 viously linked to the closed port, identified by Port, the
3978 exit signal from the port is guaranteed to be delivered
3979 before this badarg exception occurs.
3980 badarg:
3982 If Data is an invalid I/O list.
3983 port_command(Port, Data, OptionList) -> boolean()
3985 Types:
3987 Port = port() | atom()
3989 Data = iodata()
3990 Option = force | nosuspend
3991 OptionList = [Option]
3992 Sends data to a port. port_command(Port, Data, []) equals
3994 port_command(Port, Data).
3995 If the port command is aborted, false is returned, otherwise
3997 true.
3998 If the port is busy, the calling process is suspended until the
4000 port is not busy anymore.
4001 Options:
4003 force:
4005 The calling process is not suspended if the port is busy,
4006 instead the port command is forced through. The call fails
4007 with a notsup exception if the driver of the port does not
4008 support this. For more information, see driver flag
4009 ![CDATA[ERL_DRV_FLAG_SOFT_BUSY]].
4010 nosuspend:
4012 The calling process is not suspended if the port is busy,
4013 instead the port command is aborted and false is returned.
4014 Note:
4016 More options can be added in a future release.
4017 Failures:
4020 badarg:
4022 If Port is not an identifier of an open port, or the regis‐
4023 tered name of an open port. If the calling process was pre‐
4024 viously linked to the closed port, identified by Port, the
4025 exit signal from the port is guaranteed to be delivered
4026 before this badarg exception occurs.
4027 badarg:
4029 If Data is an invalid I/O list.
4030 badarg:
4032 If OptionList is an invalid option list.
4033 notsup:
4035 If option force has been passed, but the driver of the port
4036 does not allow forcing through a busy port.
4037 port_connect(Port, Pid) -> true
4039 Types:
4041 Port = port() | atom()
4043 Pid = pid()
4044 Sets the port owner (the connected port) to Pid. Roughly the
4046 same as Port ! {Owner, {connect, Pid}} except for the following:
4047 * The error behavior differs, see below.
4049 * The port does not reply with {Port,connected}.
4051 * port_connect/1 is synchronous, see below.
4053 * The new port owner gets linked to the port.
4055 The old port owner stays linked to the port and must call
4057 unlink(Port) if this is not desired. Any process can set the
4058 port owner to be any process with port_connect/2.
4059 For comparison: Port ! {self(), {connect, Pid}} only fails with
4061 badarg if Port does not refer to a port or a process. If Port is
4062 a closed port, nothing happens. If Port is an open port and the
4063 calling process is the port owner, the port replies with {Port,
4064 connected} to the old port owner. Notice that the old port owner
4065 is still linked to the port, while the new is not. If Port is an
4066 open port and the calling process is not the port owner, the
4067 port owner fails with badsig. The port owner fails with badsig
4068 also if Pid is not an existing local process identifier.
4069 Notice that any process can set the port owner using Port !
4071 {PortOwner, {connect, Pid}} as if it itself was the port owner,
4072 but the reply always goes to the port owner.
4073 As from Erlang/OTP R16, Port ! {PortOwner, {connect, Pid}} is
4075 truly asynchronous. Notice that this operation has always been
4076 documented as an asynchronous operation, while the underlying
4077 implementation has been synchronous. port_connect/2 is however
4078 still fully synchronous because of its error behavior.
4079 Failures:
4081 badarg:
4083 If Port is not an identifier of an open port, or the regis‐
4084 tered name of an open port. If the calling process was pre‐
4085 viously linked to the closed port, identified by Port, the
4086 exit signal from the port is guaranteed to be delivered
4087 before this badarg exception occurs.
4088 badarg:
4090 If the process identified by Pid is not an existing local
4091 process.
4092 port_control(Port, Operation, Data) -> iodata() | binary()
4094 Types:
4096 Port = port() | atom()
4098 Operation = integer()
4099 Data = iodata()
4100 Performs a synchronous control operation on a port. The meaning
4102 of Operation and Data depends on the port, that is, on the port
4103 driver. Not all port drivers support this control feature.
4104 Returns a list of integers in the range 0..255, or a binary,
4106 depending on the port driver. The meaning of the returned data
4107 also depends on the port driver.
4108 Failures:
4110 badarg:
4112 If Port is not an open port or the registered name of an
4113 open port.
4114 badarg:
4116 If Operation cannot fit in a 32-bit integer.
4117 badarg:
4119 If the port driver does not support synchronous control
4120 operations.
4121 badarg:
4123 If the port driver so decides for any reason (probably
4124 something wrong with Operation or Data).
4125 erlang:port_info(Port) -> Result
4127 Types:
4129 Port = port() | atom()
4131 ResultItem =
4132 {registered_name, RegisteredName :: atom()} |
4133 {id, Index :: integer() >= 0} |
4134 {connected, Pid :: pid()} |
4135 {links, Pids :: [pid()]} |
4136 {name, String :: string()} |
4137 {input, Bytes :: integer() >= 0} |
4138 {output, Bytes :: integer() >= 0} |
4139 {os_pid, OsPid :: integer() >= 0 | undefined}
4140 Result = [ResultItem] | undefined
4141 Returns a list containing tuples with information about Port, or
4143 undefined if the port is not open. The order of the tuples is
4144 undefined, and all the tuples are not mandatory. If the port is
4145 closed and the calling process was previously linked to the
4146 port, the exit signal from the port is guaranteed to be deliv‐
4147 ered before port_info/1 returns undefined.
4148 The result contains information about the following Items:
4150 * registered_name (if the port has a registered name)
4152 * id
4154 * connected
4156 * links
4158 * name
4160 * input
4162 * output
4164 For more information about the different Items, see port_info/2.
4166 Failure: badarg if Port is not a local port identifier, or an
4168 atom.
4169 erlang:port_info(Port, Item :: connected) ->
4171 {connected, Pid} | undefined
4172 Types:
4174 Port = port() | atom()
4176 Pid = pid()
4177 Pid is the process identifier of the process connected to the
4179 port.
4180 If the port identified by Port is not open, undefined is
4182 returned. If the port is closed and the calling process was pre‐
4183 viously linked to the port, the exit signal from the port is
4184 guaranteed to be delivered before port_info/2 returns undefined.
4185 Failure: badarg if Port is not a local port identifier, or an
4187 atom.
4188 erlang:port_info(Port, Item :: id) -> {id, Index} | undefined
4190 Types:
4192 Port = port() | atom()
4194 Index = integer() >= 0
4195 Index is the internal index of the port. This index can be used
4197 to separate ports.
4198 If the port identified by Port is not open, undefined is
4200 returned. If the port is closed and the calling process was pre‐
4201 viously linked to the port, the exit signal from the port is
4202 guaranteed to be delivered before port_info/2 returns undefined.
4203 Failure: badarg if Port is not a local port identifier, or an
4205 atom.
4206 erlang:port_info(Port, Item :: input) ->
4208 {input, Bytes} | undefined
4209 Types:
4211 Port = port() | atom()
4213 Bytes = integer() >= 0
4214 Bytes is the total number of bytes read from the port.
4216 If the port identified by Port is not open, undefined is
4218 returned. If the port is closed and the calling process was pre‐
4219 viously linked to the port, the exit signal from the port is
4220 guaranteed to be delivered before port_info/2 returns undefined.
4221 Failure: badarg if Port is not a local port identifier, or an
4223 atom.
4224 erlang:port_info(Port, Item :: links) -> {links, Pids} | undefined
4226 Types:
4228 Port = port() | atom()
4230 Pids = [pid()]
4231 Pids is a list of the process identifiers of the processes that
4233 the port is linked to.
4234 If the port identified by Port is not open, undefined is
4236 returned. If the port is closed and the calling process was pre‐
4237 viously linked to the port, the exit signal from the port is
4238 guaranteed to be delivered before port_info/2 returns undefined.
4239 Failure: badarg if Port is not a local port identifier, or an
4241 atom.
4242 erlang:port_info(Port, Item :: locking) ->
4244 {locking, Locking} | undefined
4245 Types:
4247 Port = port() | atom()
4249 Locking = false | port_level | driver_level
4250 Locking is one of the following:
4252 * false (emulator without SMP support)
4254 * port_level (port-specific locking)
4256 * driver_level (driver-specific locking)
4258 Notice that these results are highly implementation-specific and
4260 can change in a future release.
4261 If the port identified by Port is not open, undefined is
4263 returned. If the port is closed and the calling process was pre‐
4264 viously linked to the port, the exit signal from the port is
4265 guaranteed to be delivered before port_info/2 returns undefined.
4266 Failure: badarg if Port is not a local port identifier, or an
4268 atom.
4269 erlang:port_info(Port, Item :: memory) ->
4271 {memory, Bytes} | undefined
4272 Types:
4274 Port = port() | atom()
4276 Bytes = integer() >= 0
4277 Bytes is the total number of bytes allocated for this port by
4279 the runtime system. The port itself can have allocated memory
4280 that is not included in Bytes.
4281 If the port identified by Port is not open, undefined is
4283 returned. If the port is closed and the calling process was pre‐
4284 viously linked to the port, the exit signal from the port is
4285 guaranteed to be delivered before port_info/2 returns undefined.
4286 Failure: badarg if Port is not a local port identifier, or an
4288 atom.
4289 erlang:port_info(Port, Item :: monitors) ->
4291 {monitors, Monitors} | undefined
4292 Types:
4294 Port = port() | atom()
4296 Monitors = [{process, pid()}]
4297 Monitors represent processes monitored by this port.
4299 If the port identified by Port is not open, undefined is
4301 returned. If the port is closed and the calling process was pre‐
4302 viously linked to the port, the exit signal from the port is
4303 guaranteed to be delivered before port_info/2 returns undefined.
4304 Failure: badarg if Port is not a local port identifier, or an
4306 atom.
4307 erlang:port_info(Port, Item :: monitored_by) ->
4309 {monitored_by, MonitoredBy} | undefined
4310 Types:
4312 Port = port() | atom()
4314 MonitoredBy = [pid()]
4315 Returns list of pids that are monitoring given port at the
4317 moment.
4318 If the port identified by Port is not open, undefined is
4320 returned. If the port is closed and the calling process was pre‐
4321 viously linked to the port, the exit signal from the port is
4322 guaranteed to be delivered before port_info/2 returns undefined.
4323 Failure: badarg if Port is not a local port identifier, or an
4325 atom.
4326 erlang:port_info(Port, Item :: name) -> {name, Name} | undefined
4328 Types:
4330 Port = port() | atom()
4332 Name = string()
4333 Name is the command name set by open_port/2.
4335 If the port identified by Port is not open, undefined is
4337 returned. If the port is closed and the calling process was pre‐
4338 viously linked to the port, the exit signal from the port is
4339 guaranteed to be delivered before port_info/2 returns undefined.
4340 Failure: badarg if Port is not a local port identifier, or an
4342 atom.
4343 erlang:port_info(Port, Item :: os_pid) ->
4345 {os_pid, OsPid} | undefined
4346 Types:
4348 Port = port() | atom()
4350 OsPid = integer() >= 0 | undefined
4351 OsPid is the process identifier (or equivalent) of an OS process
4353 created with open_port({spawn | spawn_executable, Command},
4354 Options). If the port is not the result of spawning an OS
4355 process, the value is undefined.
4356 If the port identified by Port is not open, undefined is
4358 returned. If the port is closed and the calling process was pre‐
4359 viously linked to the port, the exit signal from the port is
4360 guaranteed to be delivered before port_info/2 returns undefined.
4361 Failure: badarg if Port is not a local port identifier, or an
4363 atom.
4364 erlang:port_info(Port, Item :: output) ->
4366 {output, Bytes} | undefined
4367 Types:
4369 Port = port() | atom()
4371 Bytes = integer() >= 0
4372 Bytes is the total number of bytes written to the port from
4374 Erlang processes using port_command/2, port_command/3, or Port !
4375 {Owner, {command, Data}.
4376 If the port identified by Port is not open, undefined is
4378 returned. If the port is closed and the calling process was pre‐
4379 viously linked to the port, the exit signal from the port is
4380 guaranteed to be delivered before port_info/2 returns undefined.
4381 Failure: badarg if Port is not a local port identifier, or an
4383 atom.
4384 erlang:port_info(Port, Item :: parallelism) ->
4386 {parallelism, Boolean} | undefined
4387 Types:
4389 Port = port() | atom()
4391 Boolean = boolean()
4392 Boolean corresponds to the port parallelism hint used by this
4394 port. For more information, see option parallelism of
4395 open_port/2.
4396 erlang:port_info(Port, Item :: queue_size) ->
4398 {queue_size, Bytes} | undefined
4399 Types:
4401 Port = port() | atom()
4403 Bytes = integer() >= 0
4404 Bytes is the total number of bytes queued by the port using the
4406 ERTS driver queue implementation.
4407 If the port identified by Port is not open, undefined is
4409 returned. If the port is closed and the calling process was pre‐
4410 viously linked to the port, the exit signal from the port is
4411 guaranteed to be delivered before port_info/2 returns undefined.
4412 Failure: badarg if Port is not a local port identifier, or an
4414 atom.
4415 erlang:port_info(Port, Item :: registered_name) ->
4417 {registered_name, RegisteredName} |
4418 [] |
4419 undefined
4420 Types:
4422 Port = port() | atom()
4424 RegisteredName = atom()
4425 RegisteredName is the registered name of the port. If the port
4427 has no registered name, [] is returned.
4428 If the port identified by Port is not open, undefined is
4430 returned. If the port is closed and the calling process was pre‐
4431 viously linked to the port, the exit signal from the port is
4432 guaranteed to be delivered before port_info/2 returns undefined.
4433 Failure: badarg if Port is not a local port identifier, or an
4435 atom.
4436 port_to_list(Port) -> string()
4438 Types:
4440 Port = port()
4442 Returns a string corresponding to the text representation of the
4444 port identifier Port.
4445 erlang:ports() -> [port()]
4447 Returns a list of port identifiers corresponding to all the
4449 ports existing on the local node.
4450 Notice that an exiting port exists, but is not open.
4452 pre_loaded() -> [module()]
4454 Returns a list of Erlang modules that are preloaded in the sys‐
4456 tem. As all loading of code is done through the file system, the
4457 file system must have been loaded previously. Hence, at least
4458 the module init must be preloaded.
4459 erlang:process_display(Pid, Type) -> true
4461 Types:
4463 Pid = pid()
4465 Type = backtrace
4466 Writes information about the local process Pid on standard
4468 error. The only allowed value for the atom Type is backtrace,
4469 which shows the contents of the call stack, including informa‐
4470 tion about the call chain, with the current function printed
4471 first. The format of the output is not further defined.
4472 process_flag(Flag :: trap_exit, Boolean) -> OldBoolean
4474 Types:
4476 Boolean = OldBoolean = boolean()
4478 When trap_exit is set to true, exit signals arriving to a
4480 process are converted to {'EXIT', From, Reason} messages, which
4481 can be received as ordinary messages. If trap_exit is set to
4482 false, the process exits if it receives an exit signal other
4483 than normal and the exit signal is propagated to its linked pro‐
4484 cesses. Application processes are normally not to trap exits.
4485 Returns the old value of the flag.
4487 See also exit/2.
4489 process_flag(Flag :: error_handler, Module) -> OldModule
4491 Types:
4493 Module = OldModule = atom()
4495 Used by a process to redefine the error handler for undefined
4497 function calls and undefined registered processes. Inexperienced
4498 users are not to use this flag, as code auto-loading depends on
4499 the correct operation of the error handling module.
4500 Returns the old value of the flag.
4502 process_flag(Flag :: min_heap_size, MinHeapSize) -> OldMinHeapSize
4504 Types:
4506 MinHeapSize = OldMinHeapSize = integer() >= 0
4508 Changes the minimum heap size for the calling process.
4510 Returns the old value of the flag.
4512 process_flag(Flag :: min_bin_vheap_size, MinBinVHeapSize) ->
4514 OldMinBinVHeapSize
4515 Types:
4517 MinBinVHeapSize = OldMinBinVHeapSize = integer() >= 0
4519 Changes the minimum binary virtual heap size for the calling
4521 process.
4522 Returns the old value of the flag.
4524 process_flag(Flag :: max_heap_size, MaxHeapSize) -> OldMaxHeapSize
4526 Types:
4528 MaxHeapSize = OldMaxHeapSize = max_heap_size()
4530 max_heap_size() =
4531 integer() >= 0 |
4532 #{size => integer() >= 0,
4533 kill => boolean(),
4534 error_logger => boolean()}
4535 This flag sets the maximum heap size for the calling process. If
4537 MaxHeapSize is an integer, the system default values for kill
4538 and error_logger are used.
4539 size:
4541 The maximum size in words of the process. If set to zero,
4542 the heap size limit is disabled. badarg is be thrown if the
4543 value is smaller than min_heap_size. The size check is only
4544 done when a garbage collection is triggered.
4545 size is the entire heap of the process when garbage collec‐
4547 tion is triggered. This includes all generational heaps, the
4548 process stack, any messages that are considered to be part
4549 of the heap, and any extra memory that the garbage collector
4550 needs during collection.
4551 size is the same as can be retrieved using
4553 erlang:process_info(Pid, total_heap_size), or by adding
4554 heap_block_size, old_heap_block_size and mbuf_size from
4555 erlang:process_info(Pid, garbage_collection_info).
4556 kill:
4558 When set to true, the runtime system sends an untrappable
4559 exit signal with reason kill to the process if the maximum
4560 heap size is reached. The garbage collection that triggered
4561 the kill is not completed, instead the process exits as soon
4562 as possible. When set to false, no exit signal is sent to
4563 the process, instead it continues executing.
4564 If kill is not defined in the map, the system default will
4566 be used. The default system default is true. It can be
4567 changed by either option +hmaxk in erl(1), or erlang:sys‐
4568 tem_flag(max_heap_size, MaxHeapSize).
4569 error_logger:
4571 When set to true, the runtime system sends a message to the
4572 current error_logger containing details about the process
4573 when the maximum heap size is reached. One error_logger
4574 report is sent each time the limit is reached.
4575 If error_logger is not defined in the map, the system
4577 default is used. The default system default is true. It can
4578 be changed by either the option +hmaxel int erl(1), or
4579 erlang:system_flag(max_heap_size, MaxHeapSize).
4580 The heap size of a process is quite hard to predict, especially
4582 the amount of memory that is used during the garbage collection.
4583 When contemplating using this option, it is recommended to first
4584 run it in production with kill set to false and inspect the
4585 error_logger reports to see what the normal peak sizes of the
4586 processes in the system is and then tune the value accordingly.
4587 process_flag(Flag :: message_queue_data, MQD) -> OldMQD
4589 Types:
4591 MQD = OldMQD = message_queue_data()
4593 message_queue_data() = off_heap | on_heap
4594 This flag determines how messages in the message queue are
4596 stored, as follows:
4597 off_heap:
4599 All messages in the message queue will be stored outside of
4600 the process heap. This implies that no messages in the mes‐
4601 sage queue will be part of a garbage collection of the
4602 process.
4603 on_heap:
4605 All messages in the message queue will eventually be placed
4606 on heap. They can however temporarily be stored off heap.
4607 This is how messages always have been stored up until ERTS
4608 8.0.
4609 The default message_queue_data process flag is determined by
4611 command-line argument +hmqd in erl(1).
4612 If the process potentially can get many messages in its queue,
4614 you are advised to set the flag to off_heap. This because a
4615 garbage collection with many messages placed on the heap can
4616 become extremely expensive and the process can consume large
4617 amounts of memory. Performance of the actual message passing is
4618 however generally better when not using flag off_heap.
4619 When changing this flag messages will be moved. This work has
4621 been initiated but not completed when this function call
4622 returns.
4623 Returns the old value of the flag.
4625 process_flag(Flag :: priority, Level) -> OldLevel
4627 Types:
4629 Level = OldLevel = priority_level()
4631 priority_level() = low | normal | high | max
4632 Sets the process priority. Level is an atom. Four priority lev‐
4634 els exist: low, normal, high, and max. Default is normal.
4635 Note:
4637 Priority level max is reserved for internal use in the Erlang
4638 runtime system, and is not to be used by others.
4639 Internally in each priority level, processes are scheduled in a
4642 round robin fashion.
4643 Execution of processes on priority normal and low are inter‐
4645 leaved. Processes on priority low are selected for execution
4646 less frequently than processes on priority normal.
4647 When runnable processes on priority high exist, no processes on
4649 priority low or normal are selected for execution. Notice how‐
4650 ever that this does not mean that no processes on priority low
4651 or normal can run when processes are running on priority high.
4652 On the runtime system with SMP support, more processes can be
4653 running in parallel than processes on priority high. That is, a
4654 low and a high priority process can execute at the same time.
4655 When runnable processes on priority max exist, no processes on
4657 priority low, normal, or high are selected for execution. As
4658 with priority high, processes on lower priorities can execute in
4659 parallel with processes on priority max.
4660 Scheduling is pre-emptive. Regardless of priority, a process is
4662 pre-empted when it has consumed more than a certain number of
4663 reductions since the last time it was selected for execution.
4664 Note:
4666 Do not depend on the scheduling to remain exactly as it is
4667 today. Scheduling, at least on the runtime system with SMP sup‐
4668 port, is likely to be changed in a future release to use avail‐
4669 able processor cores better.
4670 There is no automatic mechanism for avoiding priority inversion,
4673 such as priority inheritance or priority ceilings. When using
4674 priorities, take this into account and handle such scenarios by
4675 yourself.
4676 Making calls from a high priority process into code that you has
4678 no control over can cause the high priority process to wait for
4679 a process with lower priority. That is, effectively decreasing
4680 the priority of the high priority process during the call. Even
4681 if this is not the case with one version of the code that you
4682 have no control over, it can be the case in a future version of
4683 it. This can, for example, occur if a high priority process
4684 triggers code loading, as the code server runs on priority nor‐
4685 mal.
4686 Other priorities than normal are normally not needed. When other
4688 priorities are used, use them with care, especially priority
4689 high. A process on priority high is only to perform work for
4690 short periods. Busy looping for long periods in a high priority
4691 process causes most likely problems, as important OTP servers
4692 run on priority normal.
4693 Returns the old value of the flag.
4695 process_flag(Flag :: save_calls, N) -> OldN
4697 Types:
4699 N = OldN = 0..10000
4701 N must be an integer in the interval 0..10000. If N > 0, call
4703 saving is made active for the process. This means that informa‐
4704 tion about the N most recent global function calls, BIF calls,
4705 sends, and receives made by the process are saved in a list,
4706 which can be retrieved with process_info(Pid, last_calls). A
4707 global function call is one in which the module of the function
4708 is explicitly mentioned. Only a fixed amount of information is
4709 saved, as follows:
4710 * A tuple {Module, Function, Arity} for function calls
4712 * The atoms send, 'receive', and timeout for sends and
4714 receives ('receive' when a message is received and timeout
4715 when a receive times out)
4716 If N = 0, call saving is disabled for the process, which is the
4718 default. Whenever the size of the call saving list is set, its
4719 contents are reset.
4720 Returns the old value of the flag.
4722 process_flag(Flag :: sensitive, Boolean) -> OldBoolean
4724 Types:
4726 Boolean = OldBoolean = boolean()
4728 Sets or clears flag sensitive for the current process. When a
4730 process has been marked as sensitive by calling
4731 process_flag(sensitive, true), features in the runtime system
4732 that can be used for examining the data or inner working of the
4733 process are silently disabled.
4734 Features that are disabled include (but are not limited to) the
4736 following:
4737 * Tracing. Trace flags can still be set for the process, but
4739 no trace messages of any kind are generated. (If flag sensi‐
4740 tive is turned off, trace messages are again generated if
4741 any trace flags are set.)
4742 * Sequential tracing. The sequential trace token is propagated
4744 as usual, but no sequential trace messages are generated.
4745 process_info/1,2 cannot be used to read out the message queue or
4747 the process dictionary (both are returned as empty lists).
4748 Stack back-traces cannot be displayed for the process.
4750 In crash dumps, the stack, messages, and the process dictionary
4752 are omitted.
4753 If {save_calls,N} has been set for the process, no function
4755 calls are saved to the call saving list. (The call saving list
4756 is not cleared. Also, send, receive, and time-out events are
4757 still added to the list.)
4758 Returns the old value of the flag.
4760 process_flag(Pid, Flag, Value) -> OldValue
4762 Types:
4764 Pid = pid()
4766 Flag = save_calls
4767 Value = OldValue = integer() >= 0
4768 Sets certain flags for the process Pid, in the same manner as
4770 process_flag/2. Returns the old value of the flag. The valid
4771 values for Flag are only a subset of those allowed in
4772 process_flag/2, namely save_calls.
4773 Failure: badarg if Pid is not a local process.
4775 process_info(Pid) -> Info
4777 Types:
4779 Pid = pid()
4781 Info = [InfoTuple] | undefined
4782 InfoTuple = process_info_result_item()
4783 process_info_result_item() =
4784 {backtrace, Bin :: binary()} |
4785 {binary,
4786 BinInfo ::
4787 [{integer() >= 0,
4788 integer() >= 0,
4789 integer() >= 0}]} |
4790 {catchlevel, CatchLevel :: integer() >= 0} |
4791 {current_function,
4792 {Module :: module(), Function :: atom(), Arity :: arity()}} |
4793 {current_location,
4794 {Module :: module(),
4795 Function :: atom(),
4796 Arity :: arity(),
4797 Location ::
4798 [{file, Filename :: string()} |
4799 {line, Line :: integer() >= 1}]}} |
4800 {current_stacktrace, Stack :: [stack_item()]} |
4801 {dictionary, Dictionary :: [{Key :: term(), Value :: term()}]} |
4802 {error_handler, Module :: module()} |
4803 {garbage_collection, GCInfo :: [{atom(), integer() >= 0}]} |
4804 {garbage_collection_info,
4805 GCInfo :: [{atom(), integer() >= 0}]} |
4806 {group_leader, GroupLeader :: pid()} |
4807 {heap_size, Size :: integer() >= 0} |
4808 {initial_call, mfa()} |
4809 {links, PidsAndPorts :: [pid() | port()]} |
4810 {last_calls, false | (Calls :: [mfa()])} |
4811 {memory, Size :: integer() >= 0} |
4812 {message_queue_len, MessageQueueLen :: integer() >= 0} |
4813 {messages, MessageQueue :: [term()]} |
4814 {min_heap_size, MinHeapSize :: integer() >= 0} |
4815 {min_bin_vheap_size, MinBinVHeapSize :: integer() >= 0} |
4816 {max_heap_size, MaxHeapSize :: max_heap_size()} |
4817 {monitored_by, Pids :: [pid()]} |
4818 {monitors,
4819 Monitors ::
4820 [{process | port,
4821 Pid ::
4822 pid() |
4823 port() |
4824 {RegName :: atom(), Node :: node()}}]} |
4825 {message_queue_data, MQD :: message_queue_data()} |
4826 {priority, Level :: priority_level()} |
4827 {reductions, Number :: integer() >= 0} |
4828 {registered_name, [] | (Atom :: atom())} |
4829 {sequential_trace_token,
4830 [] | (SequentialTraceToken :: term())} |
4831 {stack_size, Size :: integer() >= 0} |
4832 {status,
4833 Status ::
4834 exiting |
4835 garbage_collecting |
4836 waiting |
4837 running |
4838 runnable |
4839 suspended} |
4840 {suspending,
4841 SuspendeeList ::
4842 [{Suspendee :: pid(),
4843 ActiveSuspendCount :: integer() >= 0,
4844 OutstandingSuspendCount :: integer() >= 0}]} |
4845 {total_heap_size, Size :: integer() >= 0} |
4846 {trace, InternalTraceFlags :: integer() >= 0} |
4847 {trap_exit, Boolean :: boolean()}
4848 priority_level() = low | normal | high | max
4849 stack_item() =
4850 {Module :: module(),
4851 Function :: atom(),
4852 Arity :: arity() | (Args :: [term()]),
4853 Location ::
4854 [{file, Filename :: string()} |
4855 {line, Line :: integer() >= 1}]}
4856 max_heap_size() =
4857 integer() >= 0 |
4858 #{size => integer() >= 0,
4859 kill => boolean(),
4860 error_logger => boolean()}
4861 message_queue_data() = off_heap | on_heap
4862 Returns a list containing InfoTuples with miscellaneous informa‐
4864 tion about the process identified by Pid, or undefined if the
4865 process is not alive.
4866 The order of the InfoTuples is undefined and all InfoTuples are
4868 not mandatory. The InfoTuples part of the result can be changed
4869 without prior notice.
4870 The InfoTuples with the following items are part of the result:
4872 * current_function
4874 * initial_call
4876 * status
4878 * message_queue_len
4880 * messages
4882 * links
4884 * dictionary
4886 * trap_exit
4888 * error_handler
4890 * priority
4892 * group_leader
4894 * total_heap_size
4896 * heap_size
4898 * stack_size
4900 * reductions
4902 * garbage_collection
4904 If the process identified by Pid has a registered name, also an
4906 InfoTuple with item registered_name is included.
4907 For information about specific InfoTuples, see process_info/2.
4909 Warning:
4911 This BIF is intended for debugging only. For all other purposes,
4912 use process_info/2.
4913 Failure: badarg if Pid is not a local process.
4916 process_info(Pid, Item) -> InfoTuple | [] | undefined
4918 process_info(Pid, ItemList) -> InfoTupleList | [] | undefined
4920 Types:
4922 Pid = pid()
4924 ItemList = [Item]
4925 Item = process_info_item()
4926 InfoTupleList = [InfoTuple]
4927 InfoTuple = process_info_result_item()
4928 process_info_item() =
4929 backtrace |
4930 binary |
4931 catchlevel |
4932 current_function |
4933 current_location |
4934 current_stacktrace |
4935 dictionary |
4936 error_handler |
4937 garbage_collection |
4938 garbage_collection_info |
4939 group_leader |
4940 heap_size |
4941 initial_call |
4942 links |
4943 last_calls |
4944 memory |
4945 message_queue_len |
4946 messages |
4947 min_heap_size |
4948 min_bin_vheap_size |
4949 monitored_by |
4950 monitors |
4951 message_queue_data |
4952 priority |
4953 reductions |
4954 registered_name |
4955 sequential_trace_token |
4956 stack_size |
4957 status |
4958 suspending |
4959 total_heap_size |
4960 trace |
4961 trap_exit
4962 process_info_result_item() =
4963 {backtrace, Bin :: binary()} |
4964 {binary,
4965 BinInfo ::
4966 [{integer() >= 0,
4967 integer() >= 0,
4968 integer() >= 0}]} |
4969 {catchlevel, CatchLevel :: integer() >= 0} |
4970 {current_function,
4971 {Module :: module(), Function :: atom(), Arity :: arity()}} |
4972 {current_location,
4973 {Module :: module(),
4974 Function :: atom(),
4975 Arity :: arity(),
4976 Location ::
4977 [{file, Filename :: string()} |
4978 {line, Line :: integer() >= 1}]}} |
4979 {current_stacktrace, Stack :: [stack_item()]} |
4980 {dictionary, Dictionary :: [{Key :: term(), Value :: term()}]} |
4981 {error_handler, Module :: module()} |
4982 {garbage_collection, GCInfo :: [{atom(), integer() >= 0}]} |
4983 {garbage_collection_info,
4984 GCInfo :: [{atom(), integer() >= 0}]} |
4985 {group_leader, GroupLeader :: pid()} |
4986 {heap_size, Size :: integer() >= 0} |
4987 {initial_call, mfa()} |
4988 {links, PidsAndPorts :: [pid() | port()]} |
4989 {last_calls, false | (Calls :: [mfa()])} |
4990 {memory, Size :: integer() >= 0} |
4991 {message_queue_len, MessageQueueLen :: integer() >= 0} |
4992 {messages, MessageQueue :: [term()]} |
4993 {min_heap_size, MinHeapSize :: integer() >= 0} |
4994 {min_bin_vheap_size, MinBinVHeapSize :: integer() >= 0} |
4995 {max_heap_size, MaxHeapSize :: max_heap_size()} |
4996 {monitored_by, Pids :: [pid()]} |
4997 {monitors,
4998 Monitors ::
4999 [{process | port,
5000 Pid ::
5001 pid() |
5002 port() |
5003 {RegName :: atom(), Node :: node()}}]} |
5004 {message_queue_data, MQD :: message_queue_data()} |
5005 {priority, Level :: priority_level()} |
5006 {reductions, Number :: integer() >= 0} |
5007 {registered_name, [] | (Atom :: atom())} |
5008 {sequential_trace_token,
5009 [] | (SequentialTraceToken :: term())} |
5010 {stack_size, Size :: integer() >= 0} |
5011 {status,
5012 Status ::
5013 exiting |
5014 garbage_collecting |
5015 waiting |
5016 running |
5017 runnable |
5018 suspended} |
5019 {suspending,
5020 SuspendeeList ::
5021 [{Suspendee :: pid(),
5022 ActiveSuspendCount :: integer() >= 0,
5023 OutstandingSuspendCount :: integer() >= 0}]} |
5024 {total_heap_size, Size :: integer() >= 0} |
5025 {trace, InternalTraceFlags :: integer() >= 0} |
5026 {trap_exit, Boolean :: boolean()}
5027 stack_item() =
5028 {Module :: module(),
5029 Function :: atom(),
5030 Arity :: arity() | (Args :: [term()]),
5031 Location ::
5032 [{file, Filename :: string()} |
5033 {line, Line :: integer() >= 1}]}
5034 priority_level() = low | normal | high | max
5035 max_heap_size() =
5036 integer() >= 0 |
5037 #{size => integer() >= 0,
5038 kill => boolean(),
5039 error_logger => boolean()}
5040 message_queue_data() = off_heap | on_heap
5041 Returns information about the process identified by Pid, as
5043 specified by Item or ItemList. Returns undefined if the process
5044 is not alive.
5045 If the process is alive and a single Item is specified, the
5047 returned value is the corresponding InfoTuple, unless Item =:=
5048 registered_name and the process has no registered name. In this
5049 case, [] is returned. This strange behavior is because of his‐
5050 torical reasons, and is kept for backward compatibility.
5051 If ItemList is specified, the result is InfoTupleList. The Info‐
5053 Tuples in InfoTupleList are included with the corresponding
5054 Items in the same order as the Items were included in ItemList.
5055 Valid Items can be included multiple times in ItemList.
5056 Note:
5058 If registered_name is part of ItemList and the process has no
5059 name registered, a {registered_name, []}, InfoTuple will be
5060 included in the resulting InfoTupleList. This behavior is dif‐
5061 ferent when a single Item =:= registered_name is specified, and
5062 when process_info/1 is used.
5063 Valid InfoTuples with corresponding Items:
5066 {backtrace, Bin}:
5068 Binary Bin contains the same information as the output from
5069 erlang:process_display(Pid, backtrace). Use binary_to_list/1
5070 to obtain the string of characters from the binary.
5071 {binary, BinInfo}:
5073 BinInfo is a list containing miscellaneous information about
5074 binaries on the heap of this process. This InfoTuple can be
5075 changed or removed without prior notice. In the current
5076 implementation BinInfo is a list of tuples. The tuples con‐
5077 tain; BinaryId, BinarySize, BinaryRefcCount.
5078 The message queue is on the heap depending on the process
5080 flag message_queue_data.
5081 {catchlevel, CatchLevel}:
5083 CatchLevel is the number of currently active catches in this
5084 process. This InfoTuple can be changed or removed without
5085 prior notice.
5086 {current_function, {Module, Function, Arity}}:
5088 Module, Function, Arity is the current function call of the
5089 process.
5090 {current_location, {Module, Function, Arity, Location}}:
5092 Module, Function, Arity is the current function call of the
5093 process. Location is a list of two-tuples describing the
5094 location in the source code.
5095 {current_stacktrace, Stack}:
5097 Returns the current call stack back-trace (stacktrace) of
5098 the process. The stack has the same format as returned by
5099 erlang:get_stacktrace/0. The depth of the stacktrace is
5100 truncated according to the backtrace_depth system flag set‐
5101 ting.
5102 {dictionary, Dictionary}:
5104 Dictionary is the process dictionary.
5105 {error_handler, Module}:
5107 Module is the error handler module used by the process (for
5108 undefined function calls, for example).
5109 {garbage_collection, GCInfo}:
5111 GCInfo is a list containing miscellaneous information about
5112 garbage collection for this process. The content of GCInfo
5113 can be changed without prior notice.
5114 {garbage_collection_info, GCInfo}:
5116 GCInfo is a list containing miscellaneous detailed informa‐
5117 tion about garbage collection for this process. The content
5118 of GCInfo can be changed without prior notice. For details
5119 about the meaning of each item, see gc_minor_start in
5120 erlang:trace/3.
5121 {group_leader, GroupLeader}:
5123 GroupLeader is the group leader for the I/O of the process.
5124 {heap_size, Size}:
5126 Size is the size in words of the youngest heap generation of
5127 the process. This generation includes the process stack.
5128 This information is highly implementation-dependent, and can
5129 change if the implementation changes.
5130 {initial_call, {Module, Function, Arity}}:
5132 Module, Function, Arity is the initial function call with
5133 which the process was spawned.
5134 {links, PidsAndPorts}:
5136 PidsAndPorts is a list of process identifiers and port iden‐
5137 tifiers, with processes or ports to which the process has a
5138 link.
5139 {last_calls, false|Calls}:
5141 The value is false if call saving is not active for the
5142 process (see process_flag/3). If call saving is active, a
5143 list is returned, in which the last element is the most
5144 recent called.
5145 {memory, Size}:
5147 Size is the size in bytes of the process. This includes call
5148 stack, heap, and internal structures.
5149 {message_queue_len, MessageQueueLen}:
5151 MessageQueueLen is the number of messages currently in the
5152 message queue of the process. This is the length of the list
5153 MessageQueue returned as the information item messages (see
5154 below).
5155 {messages, MessageQueue}:
5157 MessageQueue is a list of the messages to the process, which
5158 have not yet been processed.
5159 {min_heap_size, MinHeapSize}:
5161 MinHeapSize is the minimum heap size for the process.
5162 {min_bin_vheap_size, MinBinVHeapSize}:
5164 MinBinVHeapSize is the minimum binary virtual heap size for
5165 the process.
5166 {monitored_by, Pids}:
5168 A list of process identifiers monitoring the process (with
5169 monitor/2).
5170 {monitors, Monitors}:
5172 A list of monitors (started by monitor/2) that are active
5173 for the process. For a local process monitor or a remote
5174 process monitor by a process identifier, the list consists
5175 of:
5176 {process, Pid}:
5178 Process is monitored by pid.
5179 {process, {RegName, Node}}:
5181 Local or remote process is monitored by name.
5182 {port, PortId}:
5184 Local port is monitored by port id.
5185 {port, {RegName, Node}}:
5187 Local port is monitored by name. Please note, that remote
5188 port monitors are not supported, so Node will always be
5189 the local node name.
5190 {message_queue_data, MQD}:
5192 Returns the current state of process flag mes‐
5193 sage_queue_data. MQD is either off_heap or on_heap. For more
5194 information, see the documentation of process_flag(mes‐
5195 sage_queue_data, MQD).
5196 {priority, Level}:
5198 Level is the current priority level for the process. For
5199 more information on priorities, see process_flag(priority,
5200 Level).
5201 {reductions, Number}:
5203 Number is the number of reductions executed by the process.
5204 {registered_name, Atom}:
5206 Atom is the registered process name. If the process has no
5207 registered name, this tuple is not present in the list.
5208 {sequential_trace_token, [] | SequentialTraceToken}:
5210 SequentialTraceToken is the sequential trace token for the
5211 process. This InfoTuple can be changed or removed without
5212 prior notice.
5213 {stack_size, Size}:
5215 Size is the stack size, in words, of the process.
5216 {status, Status}:
5218 Status is the status of the process and is one of the fol‐
5219 lowing:
5220 * exiting
5222 * garbage_collecting
5224 * waiting (for a message)
5226 * running
5228 * runnable (ready to run, but another process is running)
5230 * suspended (suspended on a "busy" port or by the BIF
5232 erlang:suspend_process/1,2)
5233 {suspending, SuspendeeList}:
5235 SuspendeeList is a list of {Suspendee, ActiveSuspendCount,
5236 OutstandingSuspendCount} tuples. Suspendee is the process
5237 identifier of a process that has been, or is to be, sus‐
5238 pended by the process identified by Pid through the BIF
5239 erlang:suspend_process/2 or erlang:suspend_process/1.
5240 ActiveSuspendCount is the number of times Suspendee has been
5242 suspended by Pid. OutstandingSuspendCount is the number of
5243 not yet completed suspend requests sent by Pid, that is:
5244 * If ActiveSuspendCount =/= 0, Suspendee is currently in the
5246 suspended state.
5247 * If OutstandingSuspendCount =/= 0, option asynchronous of
5249 erlang:suspend_process/2 has been used and the suspendee
5250 has not yet been suspended by Pid.
5251 Notice that ActiveSuspendCount and OutstandingSuspendCount
5253 are not the total suspend count on Suspendee, only the parts
5254 contributed by Pid.
5255 {total_heap_size, Size}:
5257 Size is the total size, in words, of all heap fragments of
5258 the process. This includes the process stack and any unre‐
5259 ceived messages that are considered to be part of the heap.
5260 {trace, InternalTraceFlags}:
5262 InternalTraceFlags is an integer representing the internal
5263 trace flag for this process. This InfoTuple can be changed
5264 or removed without prior notice.
5265 {trap_exit, Boolean}:
5267 Boolean is true if the process is trapping exits, otherwise
5268 false.
5269 Notice that not all implementations support all these Items.
5271 Failures:
5273 badarg:
5275 If Pid is not a local process.
5276 badarg:
5278 If Item is an invalid item.
5279 processes() -> [pid()]
5281 Returns a list of process identifiers corresponding to all the
5283 processes currently existing on the local node.
5284 Notice that an exiting process exists, but is not alive. That
5286 is, is_process_alive/1 returns false for an exiting process, but
5287 its process identifier is part of the result returned from pro‐
5288 cesses/0.
5289 Example:
5291 > processes().
5293 [<0.0.0>,<0.2.0>,<0.4.0>,<0.5.0>,<0.7.0>,<0.8.0>]
5294 purge_module(Module) -> true
5296 Types:
5298 Module = atom()
5300 Removes old code for Module. Before this BIF is used,
5302 check_process_code/2is to be called to check that no processes
5303 execute old code in the module.
5304 Warning:
5306 This BIF is intended for the code server (see code(3)) and is
5307 not to be used elsewhere.
5308 Note:
5311 As from ERTS 8.0 (Erlang/OTP 19), any lingering processes that
5312 still execute the old code is killed by this function. In ear‐
5313 lier versions, such incorrect use could cause much more fatal
5314 failures, like emulator crash.
5315 Failure: badarg if there is no old code for Module.
5318 put(Key, Val) -> term()
5320 Types:
5322 Key = Val = term()
5324 Adds a new Key to the process dictionary, associated with the
5326 value Val, and returns undefined. If Key exists, the old value
5327 is deleted and replaced by Val, and the function returns the old
5328 value. Example:
5329 > X = put(name, walrus), Y = put(name, carpenter),
5331 Z = get(name),
5332 {X, Y, Z}.
5333 {undefined,walrus,carpenter}
5334 Note:
5336 The values stored when put is evaluated within the scope of a
5337 catch are not retracted if a throw is evaluated, or if an error
5338 occurs.
5339 erlang:raise(Class, Reason, Stacktrace) -> no_return()
5342 Types:
5344 Class = error | exit | throw
5346 Reason = term()
5347 Stacktrace = raise_stacktrace()
5348 raise_stacktrace() =
5349 [{module(), atom(), arity() | [term()]} |
5350 {function(), [term()]}] |
5351 [{module(), atom(), arity() | [term()], [{atom(), term()}]} |
5352 {function(), [term()], [{atom(), term()}]}]
5353 Stops the execution of the calling process with an exception of
5355 the specified class, reason, and call stack backtrace (stack‐
5356 trace).
5357 Class is error, exit, or throw. So, if it were not for the
5359 stacktrace, erlang:raise(Class, Reason, Stacktrace) is equiva‐
5360 lent to erlang:Class(Reason).
5361 Reason is any term. Stacktrace is a list as returned from
5363 get_stacktrace(), that is, a list of four-tuples {Module, Func‐
5364 tion, Arity | Args, Location}, where Module and Function are
5365 atoms, and the third element is an integer arity or an argument
5366 list. The stacktrace can also contain {Fun, Args, Location}
5367 tuples, where Fun is a local fun and Args is an argument list.
5368 Element Location at the end is optional. Omitting it is equiva‐
5370 lent to specifying an empty list.
5371 The stacktrace is used as the exception stacktrace for the call‐
5373 ing process; it is truncated to the current maximum stacktrace
5374 depth.
5375 As evaluating this function causes the process to terminate, it
5377 has no return value unless the arguments are invalid, in which
5378 case the function returns the error reason badarg. If you want
5379 to be sure not to return, you can call error(erlang:raise(Class,
5380 Reason, Stacktrace)) and hope to distinguish exceptions later.
5381 erlang:read_timer(TimerRef) -> Result
5383 Types:
5385 TimerRef = reference()
5387 Time = integer() >= 0
5388 Result = Time | false
5389 Reads the state of a timer. The same as calling
5391 erlang:read_timer(TimerRef, []).
5392 erlang:read_timer(TimerRef, Options) -> Result | ok
5394 Types:
5396 TimerRef = reference()
5398 Async = boolean()
5399 Option = {async, Async}
5400 Options = [Option]
5401 Time = integer() >= 0
5402 Result = Time | false
5403 Reads the state of a timer that has been created by either
5405 erlang:start_timer or erlang:send_after. TimerRef identifies the
5406 timer, and was returned by the BIF that created the timer.
5407 Options:
5409 {async, Async}:
5411 Asynchronous request for state information. Async defaults
5412 to false, which causes the operation to be performed syn‐
5413 chronously. In this case, the Result is returned by
5414 erlang:read_timer. When Async is true, erlang:read_timer
5415 sends an asynchronous request for the state information to
5416 the timer service that manages the timer, and then returns
5417 ok. A message on the format {read_timer, TimerRef, Result}
5418 is sent to the caller of erlang:read_timer when the opera‐
5419 tion has been processed.
5420 More Options can be added in the future.
5422 If Result is an integer, it represents the time in milliseconds
5424 left until the timer expires.
5425 If Result is false, a timer corresponding to TimerRef could not
5427 be found. This because the timer had expired, or been canceled,
5428 or because TimerRef never has corresponded to a timer. Even if
5429 the timer has expired, it does not tell you whether or not the
5430 time-out message has arrived at its destination yet.
5431 Note:
5433 The timer service that manages the timer can be co-located with
5434 another scheduler than the scheduler that the calling process is
5435 executing on. If so, communication with the timer service takes
5436 much longer time than if it is located locally. If the calling
5437 process is in a critical path, and can do other things while
5438 waiting for the result of this operation, you want to use option
5439 {async, true}. If using option {async, false}, the calling
5440 process is blocked until the operation has been performed.
5441 See also erlang:send_after/4, erlang:start_timer/4, and
5444 erlang:cancel_timer/2.
5445 ref_to_list(Ref) -> string()
5447 Types:
5449 Ref = reference()
5451 Returns a string corresponding to the text representation of
5453 Ref.
5454 Warning:
5456 This BIF is intended for debugging and is not to be used in
5457 application programs.
5458 register(RegName, PidOrPort) -> true
5461 Types:
5463 RegName = atom()
5465 PidOrPort = port() | pid()
5466 Associates the name RegName with a process identifier (pid) or a
5468 port identifier. RegName, which must be an atom, can be used
5469 instead of the pid or port identifier in send operator (RegName
5470 ! Message). Example:
5471 > register(db, Pid).
5473 true
5474 Failures:
5476 badarg:
5478 If PidOrPort is not an existing local process or port.
5479 badarg:
5481 If RegName is already in use.
5482 badarg:
5484 If the process or port is already registered (already has a
5485 name).
5486 badarg:
5488 If RegName is the atom undefined.
5489 registered() -> [RegName]
5491 Types:
5493 RegName = atom()
5495 Returns a list of names that have been registered using regis‐
5497 ter/2, for example:
5498 > registered().
5500 [code_server, file_server, init, user, my_db]
5501 erlang:resume_process(Suspendee) -> true
5503 Types:
5505 Suspendee = pid()
5507 Decreases the suspend count on the process identified by Sus‐
5509 pendee. Suspendee is previously to have been suspended through
5510 erlang:suspend_process/2 or erlang:suspend_process/1 by the
5511 process calling erlang:resume_process(Suspendee). When the sus‐
5512 pend count on Suspendee reaches zero, Suspendee is resumed, that
5513 is, its state is changed from suspended into the state it had
5514 before it was suspended.
5515 Warning:
5517 This BIF is intended for debugging only.
5518 Failures:
5521 badarg:
5523 If Suspendee is not a process identifier.
5524 badarg:
5526 If the process calling erlang:resume_process/1 had not pre‐
5527 viously increased the suspend count on the process identi‐
5528 fied by Suspendee.
5529 badarg:
5531 If the process identified by Suspendee is not alive.
5532 round(Number) -> integer()
5534 Types:
5536 Number = number()
5538 Returns an integer by rounding Number, for example:
5540 round(5.5).
5542 6
5543 Allowed in guard tests.
5545 self() -> pid()
5547 Returns the process identifier of the calling process, for exam‐
5549 ple:
5550 > self().
5552 <0.26.0>
5553 Allowed in guard tests.
5555 erlang:send(Dest, Msg) -> Msg
5557 Types:
5559 Dest = dst()
5561 Msg = term()
5562 dst() =
5563 pid() |
5564 port() |
5565 (RegName :: atom()) |
5566 {RegName :: atom(), Node :: node()}
5567 Sends a message and returns Msg. This is the same as Dest ! Msg.
5569 Dest can be a remote or local process identifier, a (local)
5571 port, a locally registered name, or a tuple {RegName, Node} for
5572 a registered name at another node.
5573 erlang:send(Dest, Msg, Options) -> Res
5575 Types:
5577 Dest = dst()
5579 Msg = term()
5580 Options = [nosuspend | noconnect]
5581 Res = ok | nosuspend | noconnect
5582 dst() =
5583 pid() |
5584 port() |
5585 (RegName :: atom()) |
5586 {RegName :: atom(), Node :: node()}
5587 Either sends a message and returns ok, or does not send the mes‐
5589 sage but returns something else (see below). Otherwise the same
5590 as erlang:send/2. For more detailed explanation and warnings,
5591 see erlang:send_nosuspend/2,3.
5592 Options:
5594 nosuspend:
5596 If the sender would have to be suspended to do the send,
5597 nosuspend is returned instead.
5598 noconnect:
5600 If the destination node would have to be auto-connected to
5601 do the send, noconnect is returned instead.
5602 Warning:
5604 As with erlang:send_nosuspend/2,3: use with extreme care.
5605 erlang:send_after(Time, Dest, Msg) -> TimerRef
5608 Types:
5610 Time = integer() >= 0
5612 Dest = pid() | atom()
5613 Msg = term()
5614 TimerRef = reference()
5615 Starts a timer. The same as calling erlang:send_after(Time,
5617 Dest, Msg, []).
5618 erlang:send_after(Time, Dest, Msg, Options) -> TimerRef
5620 Types:
5622 Time = integer()
5624 Dest = pid() | atom()
5625 Msg = term()
5626 Options = [Option]
5627 Abs = boolean()
5628 Option = {abs, Abs}
5629 TimerRef = reference()
5630 Starts a timer. When the timer expires, the message Msg is sent
5632 to the process identified by Dest. Apart from the format of the
5633 time-out message, this function works exactly as
5634 erlang:start_timer/4.
5635 erlang:send_nosuspend(Dest, Msg) -> boolean()
5637 Types:
5639 Dest = dst()
5641 Msg = term()
5642 dst() =
5643 pid() |
5644 port() |
5645 (RegName :: atom()) |
5646 {RegName :: atom(), Node :: node()}
5647 The same as erlang:send(Dest, Msg, [nosuspend]), but returns
5649 true if the message was sent and false if the message was not
5650 sent because the sender would have had to be suspended.
5651 This function is intended for send operations to an unreliable
5653 remote node without ever blocking the sending (Erlang) process.
5654 If the connection to the remote node (usually not a real Erlang
5655 node, but a node written in C or Java) is overloaded, this func‐
5656 tion does not send the message and returns false.
5657 The same occurs if Dest refers to a local port that is busy. For
5659 all other destinations (allowed for the ordinary send operator
5660 '!'), this function sends the message and returns true.
5661 This function is only to be used in rare circumstances where a
5663 process communicates with Erlang nodes that can disappear with‐
5664 out any trace, causing the TCP buffers and the drivers queue to
5665 be over-full before the node is shut down (because of tick time-
5666 outs) by net_kernel. The normal reaction to take when this
5667 occurs is some kind of premature shutdown of the other node.
5668 Notice that ignoring the return value from this function would
5670 result in an unreliable message passing, which is contradictory
5671 to the Erlang programming model. The message is not sent if this
5672 function returns false.
5673 In many systems, transient states of overloaded queues are nor‐
5675 mal. Although this function returns false does not mean that the
5676 other node is guaranteed to be non-responsive, it could be a
5677 temporary overload. Also, a return value of true does only mean
5678 that the message can be sent on the (TCP) channel without block‐
5679 ing; the message is not guaranteed to arrive at the remote node.
5680 For a disconnected non-responsive node, the return value is true
5681 (mimics the behavior of operator !). The expected behavior and
5682 the actions to take when the function returns false are applica‐
5683 tion- and hardware-specific.
5684 Warning:
5686 Use with extreme care.
5687 erlang:send_nosuspend(Dest, Msg, Options) -> boolean()
5690 Types:
5692 Dest = dst()
5694 Msg = term()
5695 Options = [noconnect]
5696 dst() =
5697 pid() |
5698 port() |
5699 (RegName :: atom()) |
5700 {RegName :: atom(), Node :: node()}
5701 The same as erlang:send(Dest, Msg, [nosuspend | Options]), but
5703 with a Boolean return value.
5704 This function behaves like erlang:send_nosuspend/2, but takes a
5706 third parameter, a list of options. The only option is nocon‐
5707 nect, which makes the function return false if the remote node
5708 is not currently reachable by the local node. The normal behav‐
5709 ior is to try to connect to the node, which can stall the
5710 process during a short period. The use of option noconnect makes
5711 it possible to be sure not to get the slightest delay when send‐
5712 ing to a remote process. This is especially useful when communi‐
5713 cating with nodes that expect to always be the connecting part
5714 (that is, nodes written in C or Java).
5715 Whenever the function returns false (either when a suspend would
5717 occur or when noconnect was specified and the node was not
5718 already connected), the message is guaranteed not to have been
5719 sent.
5720 Warning:
5722 Use with extreme care.
5723 erlang:set_cookie(Node, Cookie) -> true
5726 Types:
5728 Node = node()
5730 Cookie = atom()
5731 Sets the magic cookie of Node to the atom Cookie. If Node is the
5733 local node, the function also sets the cookie of all other
5734 unknown nodes to Cookie (see section Distributed Erlang in the
5735 Erlang Reference Manual in System Documentation).
5736 Failure: function_clause if the local node is not alive.
5738 setelement(Index, Tuple1, Value) -> Tuple2
5740 Types:
5742 Index = integer() >= 1
5744 1..tuple_size(Tuple1
5745 Tuple1 = Tuple2 = tuple()
5746 Value = term()
5747 Returns a tuple that is a copy of argument Tuple1 with the ele‐
5749 ment specified by integer argument Index (the first element is
5750 the element with index 1) replaced by argument Value, for exam‐
5751 ple:
5752 > setelement(2, {10, green, bottles}, red).
5754 {10,red,bottles}
5755 size(Item) -> integer() >= 0
5757 Types:
5759 Item = tuple() | binary()
5761 Returns the number of elements in a tuple or the number of bytes
5763 in a binary or bitstring, for example:
5764 > size({morni, mulle, bwange}).
5766 3
5767 > size(<<11, 22, 33>>).
5768 3
5769 For bitstrings, the number of whole bytes is returned. That is,
5771 if the number of bits in the bitstring is not divisible by 8,
5772 the resulting number of bytes is rounded down.
5773 Allowed in guard tests.
5775 See also tuple_size/1, byte_size/1, and bit_size/1.
5777 spawn(Fun) -> pid()
5779 Types:
5781 Fun = function()
5783 Returns the process identifier of a new process started by the
5785 application of Fun to the empty list []. Otherwise works like
5786 spawn/3.
5787 spawn(Node, Fun) -> pid()
5789 Types:
5791 Node = node()
5793 Fun = function()
5794 Returns the process identifier of a new process started by the
5796 application of Fun to the empty list [] on Node. If Node does
5797 not exist, a useless pid is returned. Otherwise works like
5798 spawn/3.
5799 spawn(Module, Function, Args) -> pid()
5801 Types:
5803 Module = module()
5805 Function = atom()
5806 Args = [term()]
5807 Returns the process identifier of a new process started by the
5809 application of Module:Function to Args.
5810 error_handler:undefined_function(Module, Function, Args) is
5812 evaluated by the new process if Module:Function/Arity does not
5813 exist (where Arity is the length of Args). The error handler can
5814 be redefined (see process_flag/2). If error_handler is unde‐
5815 fined, or the user has redefined the default error_handler and
5816 its replacement is undefined, a failure with reason undef
5817 occurs.
5818 Example:
5820 > spawn(speed, regulator, [high_speed, thin_cut]).
5822 <0.13.1>
5823 spawn(Node, Module, Function, Args) -> pid()
5825 Types:
5827 Node = node()
5829 Module = module()
5830 Function = atom()
5831 Args = [term()]
5832 Returns the process identifier (pid) of a new process started by
5834 the application of Module:Function to Args on Node. If Node does
5835 not exist, a useless pid is returned. Otherwise works like
5836 spawn/3.
5837 spawn_link(Fun) -> pid()
5839 Types:
5841 Fun = function()
5843 Returns the process identifier of a new process started by the
5845 application of Fun to the empty list []. A link is created
5846 between the calling process and the new process, atomically.
5847 Otherwise works like spawn/3.
5848 spawn_link(Node, Fun) -> pid()
5850 Types:
5852 Node = node()
5854 Fun = function()
5855 Returns the process identifier (pid) of a new process started by
5857 the application of Fun to the empty list [] on Node. A link is
5858 created between the calling process and the new process, atomi‐
5859 cally. If Node does not exist, a useless pid is returned and an
5860 exit signal with reason noconnection is sent to the calling
5861 process. Otherwise works like spawn/3.
5862 spawn_link(Module, Function, Args) -> pid()
5864 Types:
5866 Module = module()
5868 Function = atom()
5869 Args = [term()]
5870 Returns the process identifier of a new process started by the
5872 application of Module:Function to Args. A link is created
5873 between the calling process and the new process, atomically.
5874 Otherwise works like spawn/3.
5875 spawn_link(Node, Module, Function, Args) -> pid()
5877 Types:
5879 Node = node()
5881 Module = module()
5882 Function = atom()
5883 Args = [term()]
5884 Returns the process identifier (pid) of a new process started by
5886 the application of Module:Function to Args on Node. A link is
5887 created between the calling process and the new process, atomi‐
5888 cally. If Node does not exist, a useless pid is returned and an
5889 exit signal with reason noconnection is sent to the calling
5890 process. Otherwise works like spawn/3.
5891 spawn_monitor(Fun) -> {pid(), reference()}
5893 Types:
5895 Fun = function()
5897 Returns the process identifier of a new process, started by the
5899 application of Fun to the empty list [], and a reference for a
5900 monitor created to the new process. Otherwise works like
5901 spawn/3.
5902 spawn_monitor(Module, Function, Args) -> {pid(), reference()}
5904 Types:
5906 Module = module()
5908 Function = atom()
5909 Args = [term()]
5910 A new process is started by the application of Module:Function
5912 to Args. The process is monitored at the same time. Returns the
5913 process identifier and a reference for the monitor. Otherwise
5914 works like spawn/3.
5915 spawn_opt(Fun, Options) -> pid() | {pid(), reference()}
5917 Types:
5919 Fun = function()
5921 Options = [spawn_opt_option()]
5922 priority_level() = low | normal | high | max
5923 max_heap_size() =
5924 integer() >= 0 |
5925 #{size => integer() >= 0,
5926 kill => boolean(),
5927 error_logger => boolean()}
5928 message_queue_data() = off_heap | on_heap
5929 spawn_opt_option() =
5930 link |
5931 monitor |
5932 {priority, Level :: priority_level()} |
5933 {fullsweep_after, Number :: integer() >= 0} |
5934 {min_heap_size, Size :: integer() >= 0} |
5935 {min_bin_vheap_size, VSize :: integer() >= 0} |
5936 {max_heap_size, Size :: max_heap_size()} |
5937 {message_queue_data, MQD :: message_queue_data()}
5938 Returns the process identifier (pid) of a new process started by
5940 the application of Fun to the empty list []. Otherwise works
5941 like spawn_opt/4.
5942 If option monitor is specified, the newly created process is
5944 monitored, and both the pid and reference for the monitor are
5945 returned.
5946 spawn_opt(Node, Fun, Options) -> pid() | {pid(), reference()}
5948 Types:
5950 Node = node()
5952 Fun = function()
5953 Options = [spawn_opt_option()]
5954 priority_level() = low | normal | high | max
5955 max_heap_size() =
5956 integer() >= 0 |
5957 #{size => integer() >= 0,
5958 kill => boolean(),
5959 error_logger => boolean()}
5960 message_queue_data() = off_heap | on_heap
5961 spawn_opt_option() =
5962 link |
5963 monitor |
5964 {priority, Level :: priority_level()} |
5965 {fullsweep_after, Number :: integer() >= 0} |
5966 {min_heap_size, Size :: integer() >= 0} |
5967 {min_bin_vheap_size, VSize :: integer() >= 0} |
5968 {max_heap_size, Size :: max_heap_size()} |
5969 {message_queue_data, MQD :: message_queue_data()}
5970 Returns the process identifier (pid) of a new process started by
5972 the application of Fun to the empty list [] on Node. If Node
5973 does not exist, a useless pid is returned. Otherwise works like
5974 spawn_opt/4.
5975 spawn_opt(Module, Function, Args, Options) ->
5977 pid() | {pid(), reference()}
5978 Types:
5980 Module = module()
5982 Function = atom()
5983 Args = [term()]
5984 Options = [spawn_opt_option()]
5985 priority_level() = low | normal | high | max
5986 max_heap_size() =
5987 integer() >= 0 |
5988 #{size => integer() >= 0,
5989 kill => boolean(),
5990 error_logger => boolean()}
5991 message_queue_data() = off_heap | on_heap
5992 spawn_opt_option() =
5993 link |
5994 monitor |
5995 {priority, Level :: priority_level()} |
5996 {fullsweep_after, Number :: integer() >= 0} |
5997 {min_heap_size, Size :: integer() >= 0} |
5998 {min_bin_vheap_size, VSize :: integer() >= 0} |
5999 {max_heap_size, Size :: max_heap_size()} |
6000 {message_queue_data, MQD :: message_queue_data()}
6001 Works as spawn/3, except that an extra option list is specified
6003 when creating the process.
6004 If option monitor is specified, the newly created process is
6006 monitored, and both the pid and reference for the monitor are
6007 returned.
6008 Options:
6010 link:
6012 Sets a link to the parent process (like spawn_link/3 does).
6013 monitor:
6015 Monitors the new process (like monitor/2 does).
6016 {priority, Level:
6018 Sets the priority of the new process. Equivalent to execut‐
6019 ing process_flag(priority, Level) in the start function of
6020 the new process, except that the priority is set before the
6021 process is selected for execution for the first time. For
6022 more information on priorities, see process_flag(priority,
6023 Level).
6024 {fullsweep_after, Number}:
6026 Useful only for performance tuning. Do not use this option
6027 unless you know that there is problem with execution times
6028 or memory consumption, and ensure that the option improves
6029 matters.
6030 The Erlang runtime system uses a generational garbage col‐
6032 lection scheme, using an "old heap" for data that has sur‐
6033 vived at least one garbage collection. When there is no more
6034 room on the old heap, a fullsweep garbage collection is
6035 done.
6036 Option fullsweep_after makes it possible to specify the max‐
6038 imum number of generational collections before forcing a
6039 fullsweep, even if there is room on the old heap. Setting
6040 the number to zero disables the general collection algo‐
6041 rithm, that is, all live data is copied at every garbage
6042 collection.
6043 A few cases when it can be useful to change fullsweep_after:
6045 * If binaries that are no longer used are to be thrown away
6047 as soon as possible. (Set Number to zero.)
6048 * A process that mostly have short-lived data is fullsweeped
6050 seldom or never, that is, the old heap contains mostly
6051 garbage. To ensure a fullsweep occasionally, set Number to
6052 a suitable value, such as 10 or 20.
6053 * In embedded systems with a limited amount of RAM and no
6055 virtual memory, you might want to preserve memory by set‐
6056 ting Number to zero. (The value can be set globally, see
6057 erlang:system_flag/2.)
6058 {min_heap_size, Size}:
6060 Useful only for performance tuning. Do not use this option
6061 unless you know that there is problem with execution times
6062 or memory consumption, and ensure that the option improves
6063 matters.
6064 Gives a minimum heap size, in words. Setting this value
6066 higher than the system default can speed up some processes
6067 because less garbage collection is done. However, setting a
6068 too high value can waste memory and slow down the system
6069 because of worse data locality. Therefore, use this option
6070 only for fine-tuning an application and to measure the exe‐
6071 cution time with various Size values.
6072 {min_bin_vheap_size, VSize}:
6074 Useful only for performance tuning. Do not use this option
6075 unless you know that there is problem with execution times
6076 or memory consumption, and ensure that the option improves
6077 matters.
6078 Gives a minimum binary virtual heap size, in words. Setting
6080 this value higher than the system default can speed up some
6081 processes because less garbage collection is done. However,
6082 setting a too high value can waste memory. Therefore, use
6083 this option only for fine-tuning an application and to mea‐
6084 sure the execution time with various VSize values.
6085 {max_heap_size, Size}:
6087 Sets the max_heap_size process flag. The default
6088 max_heap_size is determined by command-line argument +hmax
6089 in erl(1). For more information, see the documentation of
6090 process_flag(max_heap_size, Size).
6091 {message_queue_data, MQD}:
6093 Sets the state of the message_queue_data process flag. MQD
6094 is to be either off_heap or on_heap. The default mes‐
6095 sage_queue_data process flag is determined by command-line
6096 argument +hmqd in erl(1). For more information, see the doc‐
6097 umentation of process_flag(message_queue_data, MQD).
6098 spawn_opt(Node, Module, Function, Args, Options) ->
6100 pid() | {pid(), reference()}
6101 Types:
6103 Node = node()
6105 Module = module()
6106 Function = atom()
6107 Args = [term()]
6108 Options = [spawn_opt_option()]
6109 priority_level() = low | normal | high | max
6110 max_heap_size() =
6111 integer() >= 0 |
6112 #{size => integer() >= 0,
6113 kill => boolean(),
6114 error_logger => boolean()}
6115 message_queue_data() = off_heap | on_heap
6116 spawn_opt_option() =
6117 link |
6118 monitor |
6119 {priority, Level :: priority_level()} |
6120 {fullsweep_after, Number :: integer() >= 0} |
6121 {min_heap_size, Size :: integer() >= 0} |
6122 {min_bin_vheap_size, VSize :: integer() >= 0} |
6123 {max_heap_size, Size :: max_heap_size()} |
6124 {message_queue_data, MQD :: message_queue_data()}
6125 Returns the process identifier (pid) of a new process started by
6127 the application of Module:Function to Args on Node. If Node does
6128 not exist, a useless pid is returned. Otherwise works like
6129 spawn_opt/4.
6130 Note:
6132 Option monitor is not supported by spawn_opt/5.
6133 split_binary(Bin, Pos) -> {binary(), binary()}
6136 Types:
6138 Bin = binary()
6140 Pos = integer() >= 0
6141 0..byte_size(Bin)
6142 Returns a tuple containing the binaries that are the result of
6144 splitting Bin into two parts at position Pos. This is not a
6145 destructive operation. After the operation, there are three
6146 binaries altogether. Example:
6147 > B = list_to_binary("0123456789").
6149 <<"0123456789">>
6150 > byte_size(B).
6151 10
6152 > {B1, B2} = split_binary(B,3).
6153 {<<"012">>,<<"3456789">>}
6154 > byte_size(B1).
6155 3
6156 > byte_size(B2).
6157 7
6158 erlang:start_timer(Time, Dest, Msg) -> TimerRef
6160 Types:
6162 Time = integer() >= 0
6164 Dest = pid() | atom()
6165 Msg = term()
6166 TimerRef = reference()
6167 Starts a timer. The same as calling erlang:start_timer(Time,
6169 Dest, Msg, []).
6170 erlang:start_timer(Time, Dest, Msg, Options) -> TimerRef
6172 Types:
6174 Time = integer()
6176 Dest = pid() | atom()
6177 Msg = term()
6178 Options = [Option]
6179 Abs = boolean()
6180 Option = {abs, Abs}
6181 TimerRef = reference()
6182 Starts a timer. When the timer expires, the message {timeout,
6184 TimerRef, Msg} is sent to the process identified by Dest.
6185 Options:
6187 {abs, false}:
6189 This is the default. It means the Time value is interpreted
6190 as a time in milliseconds relative current Erlang monotonic
6191 time.
6192 {abs, true}:
6194 Absolute Time value. The Time value is interpreted as an
6195 absolute Erlang monotonic time in milliseconds.
6196 More Options can be added in the future.
6198 The absolute point in time, the timer is set to expire on, must
6200 be in the interval [erlang:system_info(start_time), erlang:sys‐
6201 tem_info(end_time)]. If a relative time is specified, the Time
6202 value is not allowed to be negative.
6203 If Dest is a pid(), it must be a pid() of a process created on
6205 the current runtime system instance. This process has either
6206 terminated or not. If Dest is an atom(), it is interpreted as
6207 the name of a locally registered process. The process referred
6208 to by the name is looked up at the time of timer expiration. No
6209 error is returned if the name does not refer to a process.
6210 If Dest is a pid(), the timer is automatically canceled if the
6212 process referred to by the pid() is not alive, or if the process
6213 exits. This feature was introduced in ERTS 5.4.11. Notice that
6214 timers are not automatically canceled when Dest is an atom().
6215 See also erlang:send_after/4, erlang:cancel_timer/2, and
6217 erlang:read_timer/2.
6218 Failure: badarg if the arguments do not satisfy the requirements
6220 specified here.
6221 statistics(Item :: active_tasks) -> [ActiveTasks]
6223 Types:
6225 ActiveTasks = integer() >= 0
6227 Returns the same as statistics(active_tasks_all) with the excep‐
6229 tion that no information about the dirty IO run queue and its
6230 associated schedulers is part of the result. That is, only tasks
6231 that are expected to be CPU bound are part of the result.
6232 statistics(Item :: active_tasks_all) -> [ActiveTasks]
6234 Types:
6236 ActiveTasks = integer() >= 0
6238 Returns a list where each element represents the amount of
6240 active processes and ports on each run queue and its associated
6241 schedulers. That is, the number of processes and ports that are
6242 ready to run, or are currently running. Values for normal run
6243 queues and their associated schedulers are located first in the
6244 resulting list. The first element corresponds to scheduler num‐
6245 ber 1 and so on. If support for dirty schedulers exist, an ele‐
6246 ment with the value for the dirty CPU run queue and its associ‐
6247 ated dirty CPU schedulers follow and then as last element the
6248 value for the the dirty IO run queue and its associated dirty IO
6249 schedulers follow. The information is not gathered atomically.
6250 That is, the result is not necessarily a consistent snapshot of
6251 the state, but instead quite efficiently gathered.
6252 Note:
6254 Each normal scheduler has one run queue that it manages. If
6255 dirty schedulers schedulers are supported, all dirty CPU sched‐
6256 ulers share one run queue, and all dirty IO schedulers share one
6257 run queue. That is, we have multiple normal run queues, one
6258 dirty CPU run queue and one dirty IO run queue. Work can not
6259 migrate between the different types of run queues. Only work in
6260 normal run queues can migrate to other normal run queues. This
6261 has to be taken into account when evaluating the result.
6262 See also statistics(total_active_tasks), statis‐
6265 tics(run_queue_lengths), statistics(run_queue_lengths_all), sta‐
6266 tistics(total_run_queue_lengths), and statis‐
6267 tics(total_run_queue_lengths_all).
6268 statistics(Item :: context_switches) -> {ContextSwitches, 0}
6270 Types:
6272 ContextSwitches = integer() >= 0
6274 Returns the total number of context switches since the system
6276 started.
6277 statistics(Item :: exact_reductions) ->
6279 {Total_Exact_Reductions,
6280 Exact_Reductions_Since_Last_Call}
6281 Types:
6283 Total_Exact_Reductions = Exact_Reductions_Since_Last_Call =
6285 integer() >= 0
6286 Returns the number of exact reductions.
6288 Note:
6290 statistics(exact_reductions) is a more expensive operation than
6291 statistics(reductions), especially on an Erlang machine with SMP
6292 support.
6293 statistics(Item :: garbage_collection) ->
6296 {Number_of_GCs, Words_Reclaimed, 0}
6297 Types:
6299 Number_of_GCs = Words_Reclaimed = integer() >= 0
6301 Returns information about garbage collection, for example:
6303 > statistics(garbage_collection).
6305 {85,23961,0}
6306 This information can be invalid for some implementations.
6308 statistics(Item :: io) -> {{input, Input}, {output, Output}}
6310 Types:
6312 Input = Output = integer() >= 0
6314 Returns Input, which is the total number of bytes received
6316 through ports, and Output, which is the total number of bytes
6317 output to ports.
6318 statistics(Item :: microstate_accounting) ->
6320 [MSAcc_Thread] | undefined
6321 Types:
6323 MSAcc_Thread =
6325 #{type := MSAcc_Thread_Type,
6326 id := MSAcc_Thread_Id,
6327 counters := MSAcc_Counters}
6328 MSAcc_Thread_Type = scheduler | async | aux
6329 MSAcc_Thread_Id = integer() >= 0
6330 MSAcc_Counters = #{MSAcc_Thread_State => integer() >= 0}
6331 MSAcc_Thread_State =
6332 alloc |
6333 aux |
6334 bif |
6335 busy_wait |
6336 check_io |
6337 emulator |
6338 ets |
6339 gc |
6340 gc_fullsweep |
6341 nif |
6342 other |
6343 port |
6344 send |
6345 sleep |
6346 timers
6347 Microstate accounting can be used to measure how much time the
6349 Erlang runtime system spends doing various tasks. It is designed
6350 to be as lightweight as possible, but some overhead exists when
6351 this is enabled. Microstate accounting is meant to be a profil‐
6352 ing tool to help finding performance bottlenecks. To
6353 start/stop/reset microstate accounting, use system flag
6354 microstate_accounting.
6355 statistics(microstate_accounting) returns a list of maps repre‐
6357 senting some of the OS threads within ERTS. Each map contains
6358 type and id fields that can be used to identify what thread it
6359 is, and also a counters field that contains data about how much
6360 time has been spent in the various states.
6361 Example:
6363 > erlang:statistics(microstate_accounting).
6365 [#{counters => #{aux => 1899182914,
6366 check_io => 2605863602,
6367 emulator => 45731880463,
6368 gc => 1512206910,
6369 other => 5421338456,
6370 port => 221631,
6371 sleep => 5150294100},
6372 id => 1,
6373 type => scheduler}|...]
6374 The time unit is the same as returned by os:perf_counter/0. So,
6376 to convert it to milliseconds, you can do something like this:
6377 lists:map(
6379 fun(#{ counters := Cnt } = M) ->
6380 MsCnt = maps:map(fun(_K, PerfCount) ->
6381 erlang:convert_time_unit(PerfCount, perf_counter, 1000)
6382 end, Cnt),
6383 M#{ counters := MsCnt }
6384 end, erlang:statistics(microstate_accounting)).
6385 Notice that these values are not guaranteed to be the exact time
6387 spent in each state. This is because of various optimisation
6388 done to keep the overhead as small as possible.
6389 MSAcc_Thread_Types:
6391 scheduler:
6393 The main execution threads that do most of the work.
6394 dirty_cpu_scheduler:
6396 The threads for long running cpu intensive work.
6397 dirty_io_scheduler:
6399 The threads for long running I/O work.
6400 async:
6402 Async threads are used by various linked-in drivers (mainly
6403 the file drivers) do offload non-CPU intensive work.
6404 aux:
6406 Takes care of any work that is not specifically assigned to
6407 a scheduler.
6408 The following MSAcc_Thread_States are available. All states are
6410 exclusive, meaning that a thread cannot be in two states at
6411 once. So, if you add the numbers of all counters in a thread,
6412 you get the total runtime for that thread.
6413 aux:
6415 Time spent handling auxiliary jobs.
6416 check_io:
6418 Time spent checking for new I/O events.
6419 emulator:
6421 Time spent executing Erlang processes.
6422 gc:
6424 Time spent doing garbage collection. When extra states are
6425 enabled this is the time spent doing non-fullsweep garbage
6426 collections.
6427 other:
6429 Time spent doing unaccounted things.
6430 port:
6432 Time spent executing ports.
6433 sleep:
6435 Time spent sleeping.
6436 More fine-grained MSAcc_Thread_States can be added through con‐
6438 figure (such as ./configure --with-microstate-accounting=extra).
6439 Enabling these states causes performance degradation when
6440 microstate accounting is turned off and increases the overhead
6441 when it is turned on.
6442 alloc:
6444 Time spent managing memory. Without extra states this time
6445 is spread out over all other states.
6446 bif:
6448 Time spent in BIFs. Without extra states this time is part
6449 of the emulator state.
6450 busy_wait:
6452 Time spent busy waiting. This is also the state where a
6453 scheduler no longer reports that it is active when using
6454 statistics(scheduler_wall_time). So, if you add all other
6455 states but this and sleep, and then divide that by all time
6456 in the thread, you should get something very similar to the
6457 scheduler_wall_time fraction. Without extra states this time
6458 is part of the other state.
6459 ets:
6461 Time spent executing ETS BIFs. Without extra states this
6462 time is part of the emulator state.
6463 gc_full:
6465 Time spent doing fullsweep garbage collection. Without extra
6466 states this time is part of the gc state.
6467 nif:
6469 Time spent in NIFs. Without extra states this time is part
6470 of the emulator state.
6471 send:
6473 Time spent sending messages (processes only). Without extra
6474 states this time is part of the emulator state.
6475 timers:
6477 Time spent managing timers. Without extra states this time
6478 is part of the other state.
6479 The utility module msacc(3) can be used to more easily analyse
6481 these statistics.
6482 Returns undefined if system flag microstate_accounting is turned
6484 off.
6485 The list of thread information is unsorted and can appear in
6487 different order between calls.
6488 Note:
6490 The threads and states are subject to change without any prior
6491 notice.
6492 statistics(Item :: reductions) ->
6495 {Total_Reductions, Reductions_Since_Last_Call}
6496 Types:
6498 Total_Reductions = Reductions_Since_Last_Call = integer() >=
6500 0
6501 Returns information about reductions, for example:
6503 > statistics(reductions).
6505 {2046,11}
6506 Note:
6508 As from ERTS 5.5 (Erlang/OTP R11B), this value does not include
6509 reductions performed in current time slices of currently sched‐
6510 uled processes. If an exact value is wanted, use statis‐
6511 tics(exact_reductions).
6512 statistics(Item :: run_queue) -> integer() >= 0
6515 Returns the total length of all normal run-queues. That is, the
6517 number of processes and ports that are ready to run on all
6518 available normal run-queues. Dirty run queues are not part of
6519 the result. The information is gathered atomically. That is, the
6520 result is a consistent snapshot of the state, but this operation
6521 is much more expensive compared to statis‐
6522 tics(total_run_queue_lengths), especially when a large amount of
6523 schedulers is used.
6524 statistics(Item :: run_queue_lengths) -> [RunQueueLength]
6526 Types:
6528 RunQueueLength = integer() >= 0
6530 Returns the same as statistics(run_queue_lengths_all) with the
6532 exception that no information about the dirty IO run queue is
6533 part of the result. That is, only run queues with work that is
6534 expected to be CPU bound is part of the result.
6535 statistics(Item :: run_queue_lengths_all) -> [RunQueueLength]
6537 Types:
6539 RunQueueLength = integer() >= 0
6541 Returns a list where each element represents the amount of pro‐
6543 cesses and ports ready to run for each run queue. Values for
6544 normal run queues are located first in the resulting list. The
6545 first element corresponds to the normal run queue of scheduler
6546 number 1 and so on. If support for dirty schedulers exist, val‐
6547 ues for the dirty CPU run queue and the dirty IO run queue fol‐
6548 low (in that order) at the end. The information is not gathered
6549 atomically. That is, the result is not necessarily a consistent
6550 snapshot of the state, but instead quite efficiently gathered.
6551 Note:
6553 Each normal scheduler has one run queue that it manages. If
6554 dirty schedulers schedulers are supported, all dirty CPU sched‐
6555 ulers share one run queue, and all dirty IO schedulers share one
6556 run queue. That is, we have multiple normal run queues, one
6557 dirty CPU run queue and one dirty IO run queue. Work can not
6558 migrate between the different types of run queues. Only work in
6559 normal run queues can migrate to other normal run queues. This
6560 has to be taken into account when evaluating the result.
6561 See also statistics(run_queue_lengths), statis‐
6564 tics(total_run_queue_lengths_all), statis‐
6565 tics(total_run_queue_lengths), statistics(active_tasks), statis‐
6566 tics(active_tasks_all), and statistics(total_active_tasks), sta‐
6567 tistics(total_active_tasks_all).
6568 statistics(Item :: runtime) ->
6570 {Total_Run_Time, Time_Since_Last_Call}
6571 Types:
6573 Total_Run_Time = Time_Since_Last_Call = integer() >= 0
6575 Returns information about runtime, in milliseconds.
6577 This is the sum of the runtime for all threads in the Erlang
6579 runtime system and can therefore be greater than the wall clock
6580 time.
6581 Warning:
6583 This value might wrap due to limitations in the underlying func‐
6584 tionality provided by the operating system that is used.
6585 Example:
6588 > statistics(runtime).
6590 {1690,1620}
6591 statistics(Item :: scheduler_wall_time) ->
6593 [{SchedulerId, ActiveTime, TotalTime}] | undefined
6594 Types:
6596 SchedulerId = integer() >= 1
6598 ActiveTime = TotalTime = integer() >= 0
6599 Returns a list of tuples with {SchedulerId, ActiveTime, Total‐
6601 Time}, where SchedulerId is an integer ID of the scheduler,
6602 ActiveTime is the duration the scheduler has been busy, and
6603 TotalTime is the total time duration since scheduler_wall_time
6604 activation for the specific scheduler. Note that activation time
6605 can differ significantly between schedulers. Currently dirty
6606 schedulers are activated at system start while normal schedulers
6607 are activated some time after the scheduler_wall_time function‐
6608 ality is enabled. The time unit is undefined and can be subject
6609 to change between releases, OSs, and system restarts. sched‐
6610 uler_wall_time is only to be used to calculate relative values
6611 for scheduler utilization. ActiveTime can never exceed Total‐
6612 Time.
6613 The definition of a busy scheduler is when it is not idle and is
6615 not scheduling (selecting) a process or port, that is:
6616 * Executing process code
6618 * Executing linked-in driver or NIF code
6620 * Executing BIFs, or any other runtime handling
6622 * Garbage collecting
6624 * Handling any other memory management
6626 Notice that a scheduler can also be busy even if the OS has
6628 scheduled out the scheduler thread.
6629 Returns undefined if system flag scheduler_wall_time is turned
6631 off.
6632 The list of scheduler information is unsorted and can appear in
6634 different order between calls.
6635 As of ERTS version 9.0, also dirty CPU schedulers will be
6637 included in the result. That is, all scheduler threads that are
6638 expected to handle CPU bound work. If you also want information
6639 about dirty I/O schedulers, use statistics(sched‐
6640 uler_wall_time_all) instead.
6641 Normal schedulers will have scheduler identifiers in the range 1
6643 =< SchedulerId =< erlang:system_info(schedulers). Dirty CPU
6644 schedulers will have scheduler identifiers in the range
6645 erlang:system_info(schedulers) < SchedulerId =< erlang:sys‐
6646 tem_info(schedulers) + erlang:system_info(dirty_cpu_schedulers).
6647 Note:
6649 The different types of schedulers handle specific types of jobs.
6650 Every job is assigned to a specific scheduler type. Jobs can
6651 migrate between different schedulers of the same type, but never
6652 between schedulers of different types. This fact has to be taken
6653 under consideration when evaluating the result returned.
6654 Using scheduler_wall_time to calculate scheduler utilization:
6657 > erlang:system_flag(scheduler_wall_time, true).
6659 false
6660 > Ts0 = lists:sort(erlang:statistics(scheduler_wall_time)), ok.
6661 ok
6662 Some time later the user takes another snapshot and calculates
6664 scheduler utilization per scheduler, for example:
6665 > Ts1 = lists:sort(erlang:statistics(scheduler_wall_time)), ok.
6667 ok
6668 > lists:map(fun({{I, A0, T0}, {I, A1, T1}}) -> {I, (A1 - A0)/(T1 - T0)} end, lists:zip(Ts0,Ts1)).
6669 [{1,0.9743474730177548},
6670 {2,0.9744843782751444},
6671 {3,0.9995902361669045},
6672 {4,0.9738012596572161},
6673 {5,0.9717956667018103},
6674 {6,0.9739235846420741},
6675 {7,0.973237033077876},
6676 {8,0.9741297293248656}]
6677 Using the same snapshots to calculate a total scheduler utiliza‐
6679 tion:
6680 > {A, T} = lists:foldl(fun({{_, A0, T0}, {_, A1, T1}}, {Ai,Ti}) -> {Ai + (A1 - A0), Ti + (T1 - T0)} end, {0, 0}, lists:zip(Ts0,Ts1)), TotalSchedulerUtilization = A/T.
6682 0.9769136803764825
6683 Total scheduler utilization will equal 1.0 when all schedulers
6685 have been active all the time between the two measurements.
6686 Another (probably more) useful value is to calculate total
6688 scheduler utilization weighted against maximum amount of avail‐
6689 able CPU time:
6690 > WeightedSchedulerUtilization = (TotalSchedulerUtilization * (erlang:system_info(schedulers) + erlang:system_info(dirty_cpu_schedulers))) / erlang:system_info(logical_processors_available).
6692 0.9769136803764825
6693 This weighted scheduler utilization will reach 1.0 when sched‐
6695 ulers are active the same amount of time as maximum available
6696 CPU time. If more schedulers exist than available logical pro‐
6697 cessors, this value may be greater than 1.0.
6698 As of ERTS version 9.0, the Erlang runtime system with SMP sup‐
6700 port will as default have more schedulers than logical proces‐
6701 sors. This due to the dirty schedulers.
6702 Note:
6704 scheduler_wall_time is by default disabled. To enable it, use
6705 erlang:system_flag(scheduler_wall_time, true).
6706 statistics(Item :: scheduler_wall_time_all) ->
6709 [{SchedulerId, ActiveTime, TotalTime}] | undefined
6710 Types:
6712 SchedulerId = integer() >= 1
6714 ActiveTime = TotalTime = integer() >= 0
6715 The same as statistics(scheduler_wall_time), except that it also
6717 include information about all dirty I/O schedulers.
6718 Dirty IO schedulers will have scheduler identifiers in the range
6720 erlang:system_info(schedulers) + erlang:sys‐
6721 tem_info(dirty_cpu_schedulers) < SchedulerId =< erlang:sys‐
6722 tem_info(schedulers) + erlang:system_info(dirty_cpu_schedulers)
6723 + erlang:system_info(dirty_io_schedulers).
6724 Note:
6726 Note that work executing on dirty I/O schedulers are expected to
6727 mainly wait for I/O. That is, when you get high scheduler uti‐
6728 lization on dirty I/O schedulers, CPU utilization is not
6729 expected to be high due to this work.
6730 statistics(Item :: total_active_tasks) -> ActiveTasks
6733 Types:
6735 ActiveTasks = integer() >= 0
6737 The same as calling lists:sum(statistics(active_tasks)), but
6739 more efficient.
6740 statistics(Item :: total_active_tasks_all) -> ActiveTasks
6742 Types:
6744 ActiveTasks = integer() >= 0
6746 The same as calling lists:sum(statistics(active_tasks_all)), but
6748 more efficient.
6749 statistics(Item :: total_run_queue_lengths) ->
6751 TotalRunQueueLengths
6752 Types:
6754 TotalRunQueueLengths = integer() >= 0
6756 The same as calling lists:sum(statistics(run_queue_lengths)),
6758 but more efficient.
6759 statistics(Item :: total_run_queue_lengths_all) ->
6761 TotalRunQueueLengths
6762 Types:
6764 TotalRunQueueLengths = integer() >= 0
6766 The same as calling lists:sum(statis‐
6768 tics(run_queue_lengths_all)), but more efficient.
6769 statistics(Item :: wall_clock) ->
6771 {Total_Wallclock_Time,
6772 Wallclock_Time_Since_Last_Call}
6773 Types:
6775 Total_Wallclock_Time = Wallclock_Time_Since_Last_Call = inte‐
6777 ger() >= 0
6778 Returns information about wall clock. wall_clock can be used in
6780 the same manner as runtime, except that real time is measured as
6781 opposed to runtime or CPU time.
6782 erlang:suspend_process(Suspendee) -> true
6784 Types:
6786 Suspendee = pid()
6788 Suspends the process identified by Suspendee. The same as call‐
6790 ing erlang:suspend_process(Suspendee, []).
6791 Warning:
6793 This BIF is intended for debugging only.
6794 erlang:suspend_process(Suspendee, OptList) -> boolean()
6797 Types:
6799 Suspendee = pid()
6801 OptList = [Opt]
6802 Opt = unless_suspending | asynchronous
6803 Increases the suspend count on the process identified by Sus‐
6805 pendee and puts it in the suspended state if it is not already
6806 in that state. A suspended process is not scheduled for execu‐
6807 tion until the process has been resumed.
6808 A process can be suspended by multiple processes and can be sus‐
6810 pended multiple times by a single process. A suspended process
6811 does not leave the suspended state until its suspend count
6812 reaches zero. The suspend count of Suspendee is decreased when
6813 erlang:resume_process(Suspendee) is called by the same process
6814 that called erlang:suspend_process(Suspendee). All increased
6815 suspend counts on other processes acquired by a process are
6816 automatically decreased when the process terminates.
6817 Options (Opts):
6819 asynchronous:
6821 A suspend request is sent to the process identified by Sus‐
6822 pendee. Suspendee eventually suspends unless it is resumed
6823 before it could suspend. The caller of erlang:sus‐
6824 pend_process/2 returns immediately, regardless of whether
6825 Suspendee has suspended yet or not. The point in time when
6826 Suspendee suspends cannot be deduced from other events in
6827 the system. It is only guaranteed that Suspendee eventually
6828 suspends (unless it is resumed). If option asynchronous has
6829 not been passed, the caller of erlang:suspend_process/2 is
6830 blocked until Suspendee has suspended.
6831 unless_suspending:
6833 The process identified by Suspendee is suspended unless the
6834 calling process already is suspending Suspendee. If
6835 unless_suspending is combined with option asynchronous, a
6836 suspend request is sent unless the calling process already
6837 is suspending Suspendee or if a suspend request already has
6838 been sent and is in transit. If the calling process already
6839 is suspending Suspendee, or if combined with option asyn‐
6840 chronous and a send request already is in transit, false is
6841 returned and the suspend count on Suspendee remains
6842 unchanged.
6843 If the suspend count on the process identified by Suspendee is
6845 increased, true is returned, otherwise false.
6846 Warning:
6848 This BIF is intended for debugging only.
6849 Failures:
6852 badarg:
6854 If Suspendee is not a process identifier.
6855 badarg:
6857 If the process identified by Suspendee is the same process
6858 as the process calling erlang:suspend_process/2.
6859 badarg:
6861 If the process identified by Suspendee is not alive.
6862 badarg:
6864 If the process identified by Suspendee resides on another
6865 node.
6866 badarg:
6868 If OptList is not a proper list of valid Opts.
6869 system_limit:
6871 If the process identified by Suspendee has been suspended
6872 more times by the calling process than can be represented by
6873 the currently used internal data structures. The system
6874 limit is > 2,000,000,000 suspends and will never be lower.
6875 erlang:system_flag(Flag :: backtrace_depth, Depth) -> OldDepth
6877 Types:
6879 Depth = OldDepth = integer() >= 0
6881 Sets the maximum depth of call stack back-traces in the exit
6883 reason element of 'EXIT' tuples. The flag also limits the stack‐
6884 trace depth returned by process_info item current_stacktrace.
6885 Returns the old value of the flag.
6887 erlang:system_flag(Flag :: cpu_topology, CpuTopology) ->
6889 OldCpuTopology
6890 Types:
6892 CpuTopology = OldCpuTopology = cpu_topology()
6894 cpu_topology() = [LevelEntry :: level_entry()] | undefined
6895 level_entry() =
6896 {LevelTag :: level_tag(), SubLevel :: sub_level()} |
6897 {LevelTag :: level_tag(),
6898 InfoList :: info_list(),
6899 SubLevel :: sub_level()}
6900 level_tag() = core | node | processor | thread
6901 sub_level() =
6902 [LevelEntry :: level_entry()] |
6903 (LogicalCpuId :: {logical, integer() >= 0})
6904 info_list() = []
6905 Warning:
6907 This argument is deprecated. Instead of using this argument, use
6908 command-line argument +sct in erl(1).
6909 When this argument is removed, a final CPU topology to use is
6911 determined at emulator boot time.
6912 Sets the user-defined CpuTopology. The user-defined CPU topology
6915 overrides any automatically detected CPU topology. By passing
6916 undefined as CpuTopology, the system reverts to the CPU topology
6917 automatically detected. The returned value equals the value
6918 returned from erlang:system_info(cpu_topology) before the change
6919 was made.
6920 Returns the old value of the flag.
6922 The CPU topology is used when binding schedulers to logical pro‐
6924 cessors. If schedulers are already bound when the CPU topology
6925 is changed, the schedulers are sent a request to rebind accord‐
6926 ing to the new CPU topology.
6927 The user-defined CPU topology can also be set by passing com‐
6929 mand-line argument +sct to erl(1).
6930 For information on type CpuTopology and more, see erlang:sys‐
6932 tem_info(cpu_topology) as well as command-line flags +sct and
6933 +sbt in erl(1).
6934 erlang:system_flag(Flag :: dirty_cpu_schedulers_online,
6936 DirtyCPUSchedulersOnline) ->
6937 OldDirtyCPUSchedulersOnline
6938 Types:
6940 DirtyCPUSchedulersOnline = OldDirtyCPUSchedulersOnline =
6942 integer() >= 1
6943 Sets the number of dirty CPU schedulers online. Range is 1 <=
6945 DirtyCPUSchedulersOnline <= N, where N is the smallest of the
6946 return values of erlang:system_info(dirty_cpu_schedulers) and
6947 erlang:system_info(schedulers_online).
6948 Returns the old value of the flag.
6950 The number of dirty CPU schedulers online can change if the num‐
6952 ber of schedulers online changes. For example, if 12 schedulers
6953 and 6 dirty CPU schedulers are online, and system_flag/2 is used
6954 to set the number of schedulers online to 6, then the number of
6955 dirty CPU schedulers online is automatically decreased by half
6956 as well, down to 3. Similarly, the number of dirty CPU sched‐
6957 ulers online increases proportionally to increases in the number
6958 of schedulers online.
6959 For more information, see erlang:system_info(dirty_cpu_sched‐
6961 ulers) and erlang:system_info(dirty_cpu_schedulers_online).
6962 erlang:system_flag(Flag :: erts_alloc, Value :: {Alloc, F, V}) ->
6964 ok | notsup
6965 Types:
6967 Alloc = F = atom()
6969 V = integer()
6970 Sets system flags for erts_alloc(3). Alloc is the allocator to
6972 affect, for example binary_alloc. F is the flag to change and V
6973 is the new value.
6974 Only a subset of all erts_alloc flags can be changed at run
6976 time. This subset is currently only the flag sbct.
6977 Returns ok if the flag was set or notsup if not supported by
6979 erts_alloc.
6980 erlang:system_flag(Flag :: fullsweep_after, Number) -> OldNumber
6982 Types:
6984 Number = OldNumber = integer() >= 0
6986 Sets system flag fullsweep_after. Number is a non-negative inte‐
6988 ger indicating how many times generational garbage collections
6989 can be done without forcing a fullsweep collection. The value
6990 applies to new processes, while processes already running are
6991 not affected.
6992 Returns the old value of the flag.
6994 In low-memory systems (especially without virtual memory), set‐
6996 ting the value to 0 can help to conserve memory.
6997 This value can also be set through (OS) environment variable
6999 ERL_FULLSWEEP_AFTER.
7000 erlang:system_flag(Flag :: microstate_accounting, Action) ->
7002 OldState
7003 Types:
7005 Action = true | false | reset
7007 OldState = true | false
7008 Turns on/off microstate accounting measurements. When passing
7010 reset, all counters are reset to 0.
7011 For more information see statistics(microstate_accounting).
7013 erlang:system_flag(Flag :: min_heap_size, MinHeapSize) ->
7015 OldMinHeapSize
7016 Types:
7018 MinHeapSize = OldMinHeapSize = integer() >= 0
7020 Sets the default minimum heap size for processes. The size is
7022 specified in words. The new min_heap_size effects only processes
7023 spawned after the change of min_heap_size has been made.
7024 min_heap_size can be set for individual processes by using
7025 spawn_opt/4 or process_flag/2.
7026 Returns the old value of the flag.
7028 erlang:system_flag(Flag :: min_bin_vheap_size, MinBinVHeapSize) ->
7030 OldMinBinVHeapSize
7031 Types:
7033 MinBinVHeapSize = OldMinBinVHeapSize = integer() >= 0
7035 Sets the default minimum binary virtual heap size for processes.
7037 The size is specified in words. The new min_bin_vhheap_size
7038 effects only processes spawned after the change of
7039 min_bin_vheap_size has been made. min_bin_vheap_size can be set
7040 for individual processes by using spawn_opt/2,3,4 or
7041 process_flag/2.
7042 Returns the old value of the flag.
7044 erlang:system_flag(Flag :: max_heap_size, MaxHeapSize) ->
7046 OldMaxHeapSize
7047 Types:
7049 MaxHeapSize = OldMaxHeapSize = max_heap_size()
7051 max_heap_size() =
7052 integer() >= 0 |
7053 #{size => integer() >= 0,
7054 kill => boolean(),
7055 error_logger => boolean()}
7056 Sets the default maximum heap size settings for processes. The
7058 size is specified in words. The new max_heap_size effects only
7059 processes spawned efter the change has been made. max_heap_size
7060 can be set for individual processes using spawn_opt/2,3,4 or
7061 process_flag/2.
7062 Returns the old value of the flag.
7064 erlang:system_flag(Flag :: multi_scheduling, BlockState) ->
7066 OldBlockState
7067 Types:
7069 BlockState = block | unblock | block_normal | unblock_normal
7071 OldBlockState = blocked | disabled | enabled
7072 If multi-scheduling is enabled, more than one scheduler thread
7074 is used by the emulator. Multi-scheduling can be blocked in two
7075 different ways. Either all schedulers but one is blocked, or all
7076 normal schedulers but one is blocked. When only normal sched‐
7077 ulers are blocked, dirty schedulers are free to continue to
7078 schedule processes.
7079 If BlockState =:= block, multi-scheduling is blocked. That is,
7081 one and only one scheduler thread will execute. If BlockState
7082 =:= unblock and no one else blocks multi-scheduling, and this
7083 process has blocked only once, multi-scheduling is unblocked.
7084 If BlockState =:= block_normal, normal multi-scheduling is
7086 blocked. That is, only one normal scheduler thread will execute,
7087 but multiple dirty schedulers can execute. If BlockState =:=
7088 unblock_normal and no one else blocks normal multi-scheduling,
7089 and this process has blocked only once, normal multi-scheduling
7090 is unblocked.
7091 One process can block multi-scheduling and normal multi-schedul‐
7093 ing multiple times. If a process has blocked multiple times, it
7094 must unblock exactly as many times as it has blocked before it
7095 has released its multi-scheduling block. If a process that has
7096 blocked multi-scheduling or normal multi-scheduling exits, it
7097 automatically releases its blocking of multi-scheduling and nor‐
7098 mal multi-scheduling.
7099 The return values are disabled, blocked, blocked_normal, or
7101 enabled. The returned value describes the state just after the
7102 call to erlang:system_flag(multi_scheduling, BlockState) has
7103 been made. For information about the return values, see
7104 erlang:system_info(multi_scheduling).
7105 Note:
7107 Blocking of multi-scheduling and normal multi-scheduling is nor‐
7108 mally not needed. If you feel that you need to use these fea‐
7109 tures, consider it a few more times again. Blocking multi-sched‐
7110 uling is only to be used as a last resort, as it is most likely
7111 a very inefficient way to solve the problem.
7112 See also erlang:system_info(multi_scheduling), erlang:sys‐
7115 tem_info(normal_multi_scheduling_blockers), erlang:sys‐
7116 tem_info(multi_scheduling_blockers), and erlang:sys‐
7117 tem_info(schedulers).
7118 erlang:system_flag(Flag :: scheduler_bind_type, How) ->
7120 OldBindType
7121 Types:
7123 How = scheduler_bind_type() | default_bind
7125 OldBindType = scheduler_bind_type()
7126 scheduler_bind_type() =
7127 no_node_processor_spread |
7128 no_node_thread_spread |
7129 no_spread |
7130 processor_spread |
7131 spread |
7132 thread_spread |
7133 thread_no_node_processor_spread |
7134 unbound
7135 Warning:
7137 This argument is deprecated. Instead of using this argument, use
7138 command-line argument +sbt in erl(1). When this argument is
7139 removed, a final scheduler bind type to use is determined at
7140 emulator boot time.
7141 Controls if and how schedulers are bound to logical processors.
7144 When erlang:system_flag(scheduler_bind_type, How) is called, an
7146 asynchronous signal is sent to all schedulers online, causing
7147 them to try to bind or unbind as requested.
7148 Note:
7150 If a scheduler fails to bind, this is often silently ignored, as
7151 it is not always possible to verify valid logical processor
7152 identifiers. If an error is reported, it is reported to
7153 error_logger. To verify that the schedulers have bound as
7154 requested, call erlang:system_info(scheduler_bindings).
7155 Schedulers can be bound on newer Linux, Solaris, FreeBSD, and
7158 Windows systems, but more systems will be supported in future
7159 releases.
7160 In order for the runtime system to be able to bind schedulers,
7162 the CPU topology must be known. If the runtime system fails to
7163 detect the CPU topology automatically, it can be defined. For
7164 more information on how to define the CPU topology, see command-
7165 line flag +sct in erl(1).
7166 The runtime system does by default not bind schedulers to logi‐
7168 cal processors.
7169 Note:
7171 If the Erlang runtime system is the only OS process binding
7172 threads to logical processors, this improves the performance of
7173 the runtime system. However, if other OS processes (for example,
7174 another Erlang runtime system) also bind threads to logical pro‐
7175 cessors, there can be a performance penalty instead. Sometimes
7176 this performance penalty can be severe. If so, it is recommended
7177 to not bind the schedulers.
7178 Schedulers can be bound in different ways. Argument How deter‐
7181 mines how schedulers are bound and can be any of the following:
7182 unbound:
7184 Same as command-line argument +sbt u in erl(1).
7185 no_spread:
7187 Same as command-line argument +sbt ns in erl(1).
7188 thread_spread:
7190 Same as command-line argument +sbt ts in erl(1).
7191 processor_spread:
7193 Same as command-line argument +sbt ps in erl(1).
7194 spread:
7196 Same as command-line argument +sbt s in erl(1).
7197 no_node_thread_spread:
7199 Same as command-line argument +sbt nnts in erl(1).
7200 no_node_processor_spread:
7202 Same as command-line argument +sbt nnps in erl(1).
7203 thread_no_node_processor_spread:
7205 Same as command-line argument +sbt tnnps in erl(1).
7206 default_bind:
7208 Same as command-line argument +sbt db in erl(1).
7209 The returned value equals How before flag scheduler_bind_type
7211 was changed.
7212 Failures:
7214 notsup:
7216 If binding of schedulers is not supported.
7217 badarg:
7219 If How is not one of the documented alternatives.
7220 badarg:
7222 If CPU topology information is unavailable.
7223 The scheduler bind type can also be set by passing command-line
7225 argument +sbt to erl(1).
7226 For more information, see erlang:system_info(sched‐
7228 uler_bind_type), erlang:system_info(scheduler_bindings), as well
7229 as command-line flags +sbt and +sct in erl(1).
7230 erlang:system_flag(Flag :: scheduler_wall_time, Boolean) ->
7232 OldBoolean
7233 Types:
7235 Boolean = OldBoolean = boolean()
7237 Turns on or off scheduler wall time measurements.
7239 For more information, see statistics(scheduler_wall_time).
7241 erlang:system_flag(Flag :: schedulers_online, SchedulersOnline) ->
7243 OldSchedulersOnline
7244 Types:
7246 SchedulersOnline = OldSchedulersOnline = integer() >= 1
7248 Sets the number of schedulers online. Range is 1 <= Scheduler‐
7250 sOnline <= erlang:system_info(schedulers).
7251 Returns the old value of the flag.
7253 If the emulator was built with support for dirty schedulers,
7255 changing the number of schedulers online can also change the
7256 number of dirty CPU schedulers online. For example, if 12 sched‐
7257 ulers and 6 dirty CPU schedulers are online, and system_flag/2
7258 is used to set the number of schedulers online to 6, then the
7259 number of dirty CPU schedulers online is automatically decreased
7260 by half as well, down to 3. Similarly, the number of dirty CPU
7261 schedulers online increases proportionally to increases in the
7262 number of schedulers online.
7263 For more information, see erlang:system_info(schedulers) and
7265 erlang:system_info(schedulers_online).
7266 erlang:system_flag(Flag :: trace_control_word, TCW) -> OldTCW
7268 Types:
7270 TCW = OldTCW = integer() >= 0
7272 Sets the value of the node trace control word to TCW, which is
7274 to be an unsigned integer. For more information, see function
7275 set_tcw in section "Match Specifications in Erlang" in the
7276 User's Guide.
7277 Returns the old value of the flag.
7279 erlang:system_flag(Flag :: time_offset, Value :: finalize) ->
7281 OldState
7282 Types:
7284 OldState = preliminary | final | volatile
7286 Finalizes the time offset when single time warp mode is used. If
7288 another time warp mode is used, the time offset state is left
7289 unchanged.
7290 Returns the old state identifier, that is:
7292 * If preliminary is returned, finalization was performed and
7294 the time offset is now final.
7295 * If final is returned, the time offset was already in the
7297 final state. This either because another erlang:sys‐
7298 tem_flag(time_offset, finalize) call or because no time warp
7299 mode is used.
7300 * If volatile is returned, the time offset cannot be finalized
7302 because multi-time warp mode is used.
7303 erlang:system_info(Item :: allocated_areas) -> [tuple()]
7305 erlang:system_info(Item :: allocator) ->
7307 {Allocator, Version, Features, Settings}
7308 erlang:system_info(Item :: alloc_util_allocators) -> [Alloc]
7310 erlang:system_info(Item :: {allocator, Alloc}) -> [term()]
7312 erlang:system_info(Item :: {allocator_sizes, Alloc}) -> [term()]
7314 Types:
7316 Allocator = undefined | glibc
7318 Version = [integer() >= 0]
7319 Features = [atom()]
7320 Settings =
7321 [{Subsystem :: atom(),
7322 [{Parameter :: atom(), Value :: term()}]}]
7323 Alloc = atom()
7324 Returns various information about the allocators of the current
7326 system (emulator) as specified by Item:
7327 allocated_areas:
7329 Returns a list of tuples with information about miscella‐
7330 neous allocated memory areas.
7331 Each tuple contains an atom describing the type of memory as
7333 first element and the amount of allocated memory in bytes as
7334 second element. When information about allocated and used
7335 memory is present, also a third element is present, contain‐
7336 ing the amount of used memory in bytes.
7337 erlang:system_info(allocated_areas) is intended for debug‐
7339 ging, and the content is highly implementation-dependent.
7340 The content of the results therefore changes when needed
7341 without prior notice.
7342 Notice that the sum of these values is not the total amount
7344 of memory allocated by the emulator. Some values are part of
7345 other values, and some memory areas are not part of the
7346 result. For information about the total amount of memory
7347 allocated by the emulator, see erlang:memory/0,1.
7348 allocator:
7350 Returns {Allocator, Version, Features, Settings, where:
7353 * Allocator corresponds to the malloc() implementation used.
7355 If Allocator equals undefined, the malloc() implementation
7356 used cannot be identified. glibc can be identified.
7357 * Version is a list of integers (but not a string) repre‐
7359 senting the version of the malloc() implementation used.
7360 * Features is a list of atoms representing the allocation
7362 features used.
7363 * Settings is a list of subsystems, their configurable
7365 parameters, and used values. Settings can differ between
7366 different combinations of platforms, allocators, and allo‐
7367 cation features. Memory sizes are given in bytes.
7368 See also "System Flags Effecting erts_alloc" in
7370 erts_alloc(3).
7371 alloc_util_allocators:
7373 Returns a list of the names of all allocators using the ERTS
7376 internal alloc_util framework as atoms. For more informa‐
7377 tion, see section The alloc_util framework in erts_alloc(3).
7378 {allocator, Alloc}:
7380 Returns information about the specified allocator. As from
7383 ERTS 5.6.1, the return value is a list of {instance, Instan‐
7384 ceNo, InstanceInfo} tuples, where InstanceInfo contains
7385 information about a specific instance of the allocator. If
7386 Alloc is not a recognized allocator, undefined is returned.
7387 If Alloc is disabled, false is returned.
7388 Notice that the information returned is highly implementa‐
7390 tion-dependent and can be changed or removed at any time
7391 without prior notice. It was initially intended as a tool
7392 when developing new allocators, but as it can be of interest
7393 for others it has been briefly documented.
7394 The recognized allocators are listed in erts_alloc(3).
7396 Information about super carriers can be obtained from ERTS
7397 8.0 with {allocator, erts_mmap} or from ERTS 5.10.4; the
7398 returned list when calling with {allocator, mseg_alloc} also
7399 includes an {erts_mmap, _} tuple as one element in the list.
7400 After reading the erts_alloc(3) documentation, the returned
7402 information more or less speaks for itself, but it can be
7403 worth explaining some things. Call counts are presented by
7404 two values, the first value is giga calls, and the second
7405 value is calls. mbcs and sbcs denote multi-block carriers,
7406 and single-block carriers, respectively. Sizes are presented
7407 in bytes. When a size is not presented, it is the amount of
7408 something. Sizes and amounts are often presented by three
7409 values:
7410 * The first is the current value.
7412 * The second is the maximum value since the last call to
7414 erlang:system_info({allocator, Alloc}).
7415 * The third is the maximum value since the emulator was
7417 started.
7418 If only one value is present, it is the current value.
7420 fix_alloc memory block types are presented by two values.
7421 The first value is the memory pool size and the second value
7422 is the used memory size.
7423 {allocator_sizes, Alloc}:
7425 Returns various size information for the specified alloca‐
7428 tor. The information returned is a subset of the information
7429 returned by erlang:system_info({allocator, Alloc}).
7430 erlang:system_info(Item :: cpu_topology) -> CpuTopology
7432 erlang:system_info(Item ::
7434 {cpu_topology, defined | detected | used}) ->
7435 CpuTopology
7436 Types:
7438 CpuTopology = cpu_topology()
7440 cpu_topology() = [LevelEntry :: level_entry()] | undefined
7441 All LevelEntrys of a list must contain the same LevelTag,
7442 except on the top level where both node and processor‐
7443 LevelTags can coexist.
7444 level_entry() =
7445 {LevelTag :: level_tag(), SubLevel :: sub_level()} |
7446 {LevelTag :: level_tag(),
7447 InfoList :: info_list(),
7448 SubLevel :: sub_level()}
7449 {LevelTag, SubLevel} == {LevelTag, [], SubLevel}
7450 level_tag() = core | node | processor | thread
7451 More LevelTags can be introduced in a future release.
7452 sub_level() =
7453 [LevelEntry :: level_entry()] |
7454 (LogicalCpuId :: {logical, integer() >= 0})
7455 info_list() = []
7456 The info_list() can be extended in a future release.
7457 Returns various information about the CPU topology of the cur‐
7459 rent system (emulator) as specified by Item:
7460 cpu_topology:
7462 Returns the CpuTopology currently used by the emulator. The
7463 CPU topology is used when binding schedulers to logical pro‐
7464 cessors. The CPU topology used is the user-defined CPU
7465 topology, if such exists, otherwise the automatically
7466 detected CPU topology, if such exists. If no CPU topology
7467 exists, undefined is returned.
7468 node refers to Non-Uniform Memory Access (NUMA) nodes.
7470 thread refers to hardware threads (for example, Intel hyper-
7471 threads).
7472 A level in term CpuTopology can be omitted if only one entry
7474 exists and InfoList is empty.
7475 thread can only be a sublevel to core. core can be a sub‐
7477 level to processor or node. processor can be on the top
7478 level or a sublevel to node. node can be on the top level or
7479 a sublevel to processor. That is, NUMA nodes can be proces‐
7480 sor internal or processor external. A CPU topology can con‐
7481 sist of a mix of processor internal and external NUMA nodes,
7482 as long as each logical CPU belongs to one NUMA node. Cache
7483 hierarchy is not part of the CpuTopology type, but will be
7484 in a future release. Other things can also make it into the
7485 CPU topology in a future release. So, expect the CpuTopology
7486 type to change.
7487 {cpu_topology, defined}:
7489 Returns the user-defined CpuTopology. For more information,
7492 see command-line flag +sct in erl(1) and argument cpu_topol‐
7493 ogy.
7494 {cpu_topology, detected}:
7496 Returns the automatically detected CpuTopologyy. The emula‐
7499 tor detects the CPU topology on some newer Linux, Solaris,
7500 FreeBSD, and Windows systems. On Windows system with more
7501 than 32 logical processors, the CPU topology is not
7502 detected.
7503 For more information, see argument cpu_topology.
7505 {cpu_topology, used}:
7507 Returns CpuTopology used by the emulator. For more informa‐
7508 tion, see argument cpu_topology.
7509 erlang:system_info(Item :: fullsweep_after) ->
7511 {fullsweep_after, integer() >= 0}
7512 erlang:system_info(Item :: garbage_collection) ->
7514 [{atom(), integer()}]
7515 erlang:system_info(Item :: max_heap_size) ->
7517 {max_heap_size,
7518 MaxHeapSize :: max_heap_size()}
7519 erlang:system_info(Item :: message_queue_data) ->
7521 message_queue_data()
7522 erlang:system_info(Item :: min_heap_size) ->
7524 {min_heap_size,
7525 MinHeapSize :: integer() >= 1}
7526 erlang:system_info(Item :: min_bin_vheap_size) ->
7528 {min_bin_vheap_size,
7529 MinBinVHeapSize :: integer() >= 1}
7530 Types:
7532 message_queue_data() = off_heap | on_heap
7534 max_heap_size() =
7535 integer() >= 0 |
7536 #{size => integer() >= 0,
7537 kill => boolean(),
7538 error_logger => boolean()}
7539 Returns information about the default process heap settings:
7541 fullsweep_after:
7543 Returns {fullsweep_after, integer() >= 0}, which is the
7544 fullsweep_after garbage collection setting used by default.
7545 For more information, see garbage_collection described
7546 below.
7547 garbage_collection:
7549 Returns a list describing the default garbage collection
7550 settings. A process spawned on the local node by a spawn or
7551 spawn_link uses these garbage collection settings. The
7552 default settings can be changed by using erlang:sys‐
7553 tem_flag/2. spawn_opt/2,3,4 can spawn a process that does
7554 not use the default settings.
7555 max_heap_size:
7557 Returns {max_heap_size, MaxHeapSize}, where MaxHeapSize is
7558 the current system-wide maximum heap size settings for
7559 spawned processes. This setting can be set using the com‐
7560 mand-line flags +hmax, +hmaxk and +hmaxel in erl(1). It can
7561 also be changed at runtime using erlang:sys‐
7562 tem_flag(max_heap_size, MaxHeapSize). For more details about
7563 the max_heap_size process flag, see
7564 process_flag(max_heap_size, MaxHeapSize).
7565 message_queue_data:
7567 Returns the default value of the message_queue_data process
7568 flag, which is either off_heap or on_heap. This default is
7569 set by command-line argument +hmqd in erl(1). For more
7570 information on the message_queue_data process flag, see doc‐
7571 umentation of process_flag(message_queue_data, MQD).
7572 min_heap_size:
7574 Returns {min_heap_size, MinHeapSize}, where MinHeapSize is
7575 the current system-wide minimum heap size for spawned pro‐
7576 cesses.
7577 min_bin_vheap_size:
7579 Returns {min_bin_vheap_size, MinBinVHeapSize}, where MinBin‐
7580 VHeapSize is the current system-wide minimum binary virtual
7581 heap size for spawned processes.
7582 erlang:system_info(Item :: atom_count) -> integer() >= 1
7584 erlang:system_info(Item :: atom_limit) -> integer() >= 1
7586 erlang:system_info(Item :: build_type) ->
7588 opt |
7589 debug |
7590 purify |
7591 quantify |
7592 purecov |
7593 gcov |
7594 valgrind |
7595 gprof |
7596 lcnt |
7597 frmptr
7598 erlang:system_info(Item :: c_compiler_used) -> {atom(), term()}
7600 erlang:system_info(Item :: check_io) -> [term()]
7602 erlang:system_info(Item :: compat_rel) -> integer()
7604 erlang:system_info(Item :: creation) -> integer()
7606 erlang:system_info(Item :: debug_compiled) -> boolean()
7608 erlang:system_info(Item :: delayed_node_table_gc) ->
7610 infinity | integer() >= 0
7611 erlang:system_info(Item :: dirty_cpu_schedulers) ->
7613 integer() >= 0
7614 erlang:system_info(Item :: dirty_cpu_schedulers_online) ->
7616 integer() >= 0
7617 erlang:system_info(Item :: dirty_io_schedulers) ->
7619 integer() >= 0
7620 erlang:system_info(Item :: dist) -> binary()
7622 erlang:system_info(Item :: dist_buf_busy_limit) ->
7624 integer() >= 0
7625 erlang:system_info(Item :: dist_ctrl) ->
7627 {Node :: node(),
7628 ControllingEntity :: port() | pid()}
7629 erlang:system_info(Item :: driver_version) -> string()
7631 erlang:system_info(Item :: dynamic_trace) ->
7633 none | dtrace | systemtap
7634 erlang:system_info(Item :: dynamic_trace_probes) -> boolean()
7636 erlang:system_info(Item :: elib_malloc) -> false
7638 erlang:system_info(Item :: eager_check_io) -> boolean()
7640 erlang:system_info(Item :: ets_limit) -> integer() >= 1
7642 erlang:system_info(Item :: heap_sizes) -> [integer() >= 0]
7644 erlang:system_info(Item :: heap_type) -> private
7646 erlang:system_info(Item :: info) -> binary()
7648 erlang:system_info(Item :: kernel_poll) -> boolean()
7650 erlang:system_info(Item :: loaded) -> binary()
7652 erlang:system_info(Item ::
7654 logical_processors |
7655 logical_processors_available |
7656 logical_processors_online) ->
7657 unknown | integer() >= 1
7658 erlang:system_info(Item :: machine) -> string()
7660 erlang:system_info(Item :: modified_timing_level) ->
7662 integer() | undefined
7663 erlang:system_info(Item :: multi_scheduling) ->
7665 disabled |
7666 blocked |
7667 blocked_normal |
7668 enabled
7669 erlang:system_info(Item :: multi_scheduling_blockers) ->
7671 [Pid :: pid()]
7672 erlang:system_info(Item :: nif_version) -> string()
7674 erlang:system_info(Item :: normal_multi_scheduling_blockers) ->
7676 [Pid :: pid()]
7677 erlang:system_info(Item :: otp_release) -> string()
7679 erlang:system_info(Item :: os_monotonic_time_source) ->
7681 [{atom(), term()}]
7682 erlang:system_info(Item :: os_system_time_source) ->
7684 [{atom(), term()}]
7685 erlang:system_info(Item :: port_count) -> integer() >= 0
7687 erlang:system_info(Item :: port_limit) -> integer() >= 1
7689 erlang:system_info(Item :: process_count) -> integer() >= 1
7691 erlang:system_info(Item :: process_limit) -> integer() >= 1
7693 erlang:system_info(Item :: procs) -> binary()
7695 erlang:system_info(Item :: scheduler_bind_type) ->
7697 spread |
7698 processor_spread |
7699 thread_spread |
7700 thread_no_node_processor_spread |
7701 no_node_processor_spread |
7702 no_node_thread_spread |
7703 no_spread |
7704 unbound
7705 erlang:system_info(Item :: scheduler_bindings) -> tuple()
7707 erlang:system_info(Item :: scheduler_id) ->
7709 SchedulerId :: integer() >= 1
7710 erlang:system_info(Item :: schedulers | schedulers_online) ->
7712 integer() >= 1
7713 erlang:system_info(Item :: smp_support) -> boolean()
7715 erlang:system_info(Item :: start_time) -> integer()
7717 erlang:system_info(Item :: system_version) -> string()
7719 erlang:system_info(Item :: system_architecture) -> string()
7721 erlang:system_info(Item :: threads) -> boolean()
7723 erlang:system_info(Item :: thread_pool_size) -> integer() >= 0
7725 erlang:system_info(Item :: time_correction) -> true | false
7727 erlang:system_info(Item :: time_offset) ->
7729 preliminary | final | volatile
7730 erlang:system_info(Item :: time_warp_mode) ->
7732 no_time_warp |
7733 single_time_warp |
7734 multi_time_warp
7735 erlang:system_info(Item :: tolerant_timeofday) ->
7737 enabled | disabled
7738 erlang:system_info(Item :: trace_control_word) ->
7740 integer() >= 0
7741 erlang:system_info(Item :: update_cpu_info) -> changed | unchanged
7743 erlang:system_info(Item :: version) -> string()
7745 Returns various information about the current system (emulator)
7747 as specified by Item:
7748 atom_count:
7750 Returns the number of atoms currently existing at the local
7753 node. The value is given as an integer.
7754 atom_limit:
7756 Returns the maximum number of atoms allowed. This limit can
7759 be increased at startup by passing command-line flag +t to
7760 erl(1).
7761 build_type:
7763 Returns an atom describing the build type of the runtime
7764 system. This is normally the atom opt for optimized. Other
7765 possible return values are debug, purify, quantify, purecov,
7766 gcov, valgrind, gprof, and lcnt. Possible return values can
7767 be added or removed at any time without prior notice.
7768 c_compiler_used:
7770 Returns a two-tuple describing the C compiler used when com‐
7771 piling the runtime system. The first element is an atom
7772 describing the name of the compiler, or undefined if
7773 unknown. The second element is a term describing the version
7774 of the compiler, or undefined if unknown.
7775 check_io:
7777 Returns a list containing miscellaneous information about
7778 the emulators internal I/O checking. Notice that the content
7779 of the returned list can vary between platforms and over
7780 time. It is only guaranteed that a list is returned.
7781 compat_rel:
7783 Returns the compatibility mode of the local node as an inte‐
7784 ger. The integer returned represents the Erlang/OTP release
7785 that the current emulator has been set to be backward com‐
7786 patible with. The compatibility mode can be configured at
7787 startup by using command-line flag +R in erl(1).
7788 cpu_topology:
7790 See above.
7791 creation:
7793 Returns the creation of the local node as an integer. The
7794 creation is changed when a node is restarted. The creation
7795 of a node is stored in process identifiers, port identi‐
7796 fiers, and references. This makes it (to some extent) possi‐
7797 ble to distinguish between identifiers from different incar‐
7798 nations of a node. The valid creations are integers in the
7799 range 1..3, but this will probably change in a future
7800 release. If the node is not alive, 0 is returned.
7801 debug_compiled:
7803 Returns true if the emulator has been debug-compiled, other‐
7804 wise false.
7805 delayed_node_table_gc:
7807 Returns the amount of time in seconds garbage collection of
7810 an entry in a node table is delayed. This limit can be set
7811 on startup by passing command-line flag +zdntgc to erl(1).
7812 For more information, see the documentation of the command-
7813 line flag.
7814 dirty_cpu_schedulers:
7816 Returns the number of dirty CPU scheduler threads used by
7819 the emulator. Dirty CPU schedulers execute CPU-bound native
7820 functions, such as NIFs, linked-in driver code, and BIFs
7821 that cannot be managed cleanly by the normal emulator sched‐
7822 ulers.
7823 The number of dirty CPU scheduler threads is determined at
7825 emulator boot time and cannot be changed after that. How‐
7826 ever, the number of dirty CPU scheduler threads online can
7827 be changed at any time. The number of dirty CPU schedulers
7828 can be set at startup by passing command-line flag +SDcpu or
7829 +SDPcpu in erl(1).
7830 See also erlang:system_flag(dirty_cpu_schedulers_online,
7832 DirtyCPUSchedulersOnline), erlang:sys‐
7833 tem_info(dirty_cpu_schedulers_online), erlang:sys‐
7834 tem_info(dirty_io_schedulers), erlang:system_info(sched‐
7835 ulers), erlang:system_info(schedulers_online), and
7836 erlang:system_flag(schedulers_online, SchedulersOnline).
7837 dirty_cpu_schedulers_online:
7839 Returns the number of dirty CPU schedulers online. The
7842 return value satisfies 1 <= DirtyCPUSchedulersOnline <= N,
7843 where N is the smallest of the return values of erlang:sys‐
7844 tem_info(dirty_cpu_schedulers) and erlang:system_info(sched‐
7845 ulers_online).
7846 The number of dirty CPU schedulers online can be set at
7848 startup by passing command-line flag +SDcpu in erl(1).
7849 For more information, see erlang:sys‐
7851 tem_info(dirty_cpu_schedulers), erlang:sys‐
7852 tem_info(dirty_io_schedulers), erlang:system_info(sched‐
7853 ulers_online), and erlang:system_flag(dirty_cpu_sched‐
7854 ulers_online, DirtyCPUSchedulersOnline).
7855 dirty_io_schedulers:
7857 Returns the number of dirty I/O schedulers as an integer.
7860 Dirty I/O schedulers execute I/O-bound native functions,
7861 such as NIFs and linked-in driver code, which cannot be man‐
7862 aged cleanly by the normal emulator schedulers.
7863 This value can be set at startup by passing command-line
7865 argument +SDio in erl(1).
7866 For more information, see erlang:sys‐
7868 tem_info(dirty_cpu_schedulers), erlang:sys‐
7869 tem_info(dirty_cpu_schedulers_online), and erlang:sys‐
7870 tem_flag(dirty_cpu_schedulers_online, DirtyCPUSchedulersOn‐
7871 line).
7872 dist:
7874 Returns a binary containing a string of distribution infor‐
7875 mation formatted as in Erlang crash dumps. For more informa‐
7876 tion, see section How to interpret the Erlang crash dumps
7877 in the User's Guide.
7878 dist_buf_busy_limit:
7880 Returns the value of the distribution buffer busy limit in
7883 bytes. This limit can be set at startup by passing command-
7884 line flag +zdbbl to erl(1).
7885 dist_ctrl:
7887 Returns a list of tuples {Node, ControllingEntity}, one
7888 entry for each connected remote node. Node is the node name
7889 and ControllingEntity is the port or process identifier
7890 responsible for the communication to that node. More specif‐
7891 ically, ControllingEntity for nodes connected through TCP/IP
7892 (the normal case) is the socket used in communication with
7893 the specific node.
7894 driver_version:
7896 Returns a string containing the Erlang driver version used
7897 by the runtime system. It has the form "<major ver>.<minor
7898 ver>".
7899 dynamic_trace:
7901 Returns an atom describing the dynamic trace framework com‐
7902 piled into the virtual machine. It can be dtrace, systemtap,
7903 or none. For a commercial or standard build, it is always
7904 none. The other return values indicate a custom configura‐
7905 tion (for example, ./configure --with-dynamic-trace=dtrace).
7906 For more information about dynamic tracing, see dyntrace(3)
7907 manual page and the README.dtrace/README.systemtap files in
7908 the Erlang source code top directory.
7909 dynamic_trace_probes:
7911 Returns a boolean() indicating if dynamic trace probes
7912 (dtrace or systemtap) are built into the emulator. This can
7913 only be true if the virtual machine was built for dynamic
7914 tracing (that is, system_info(dynamic_trace) returns dtrace
7915 or systemtap).
7916 end_time:
7918 The last Erlang monotonic time in native time unit that can
7919 be represented internally in the current Erlang runtime sys‐
7920 tem instance. The time between the start time and the end
7921 time is at least a quarter of a millennium.
7922 elib_malloc:
7924 This option will be removed in a future release. The return
7925 value will always be false, as the elib_malloc allocator has
7926 been removed.
7927 eager_check_io:
7929 Returns the value of command-line flag +secio in erl(1),
7930 which is either true or false. For information about the
7931 different values, see the documentation of the command-line
7932 flag.
7933 ets_limit:
7935 Returns the maximum number of ETS tables allowed. This limit
7936 can be increased at startup by passing command-line flag +e
7937 to erl(1) or by setting environment variable
7938 ERL_MAX_ETS_TABLES before starting the Erlang runtime sys‐
7939 tem.
7940 heap_sizes:
7942 Returns a list of integers representing valid heap sizes in
7943 words. All Erlang heaps are sized from sizes in this list.
7944 heap_type:
7946 Returns the heap type used by the current emulator. One heap
7947 type exists:
7948 private:
7950 Each process has a heap reserved for its use and no ref‐
7951 erences between heaps of different processes are allowed.
7952 Messages passed between processes are copied between
7953 heaps.
7954 info:
7956 Returns a binary containing a string of miscellaneous system
7957 information formatted as in Erlang crash dumps. For more
7958 information, see section How to interpret the Erlang crash
7959 dumps in the User's Guide.
7960 kernel_poll:
7962 Returns true if the emulator uses some kind of kernel-poll
7963 implementation, otherwise false.
7964 loaded:
7966 Returns a binary containing a string of loaded module infor‐
7967 mation formatted as in Erlang crash dumps. For more informa‐
7968 tion, see section How to interpret the Erlang crash dumps in
7969 the User's Guide.
7970 logical_processors:
7972 Returns the detected number of logical processors configured
7975 in the system. The return value is either an integer, or the
7976 atom unknown if the emulator cannot detect the configured
7977 logical processors.
7978 logical_processors_available:
7980 Returns the detected number of logical processors available
7983 to the Erlang runtime system. The return value is either an
7984 integer, or the atom unknown if the emulator cannot detect
7985 the available logical processors. The number of available
7986 logical processors is less than or equal to the number of
7987 logical processors online.
7988 logical_processors_online:
7990 Returns the detected number of logical processors online on
7993 the system. The return value is either an integer, or the
7994 atom unknown if the emulator cannot detect logical proces‐
7995 sors online. The number of logical processors online is less
7996 than or equal to the number of logical processors config‐
7997 ured.
7998 machine:
8000 Returns a string containing the Erlang machine name.
8001 modified_timing_level:
8003 Returns the modified timing-level (an integer) if modified
8004 timing is enabled, otherwise undefined. For more information
8005 about modified timing, see command-line flag +T in erl(1)
8006 multi_scheduling:
8008 Returns one of the following:
8011 disabled:
8013 The emulator has only one scheduler thread. The emulator
8014 does not have SMP support, or have been started with only
8015 one scheduler thread.
8016 blocked:
8018 The emulator has more than one scheduler thread, but all
8019 scheduler threads except one are blocked. That is, only
8020 one scheduler thread schedules Erlang processes and exe‐
8021 cutes Erlang code.
8022 blocked_normal:
8024 The emulator has more than one scheduler thread, but all
8025 normal scheduler threads except one are blocked. Notice
8026 that dirty schedulers are not blocked, and can schedule
8027 Erlang processes and execute native code.
8028 enabled:
8030 The emulator has more than one scheduler thread, and no
8031 scheduler threads are blocked. That is, all available
8032 scheduler threads schedule Erlang processes and execute
8033 Erlang code.
8034 See also erlang:system_flag(multi_scheduling, BlockState),
8036 erlang:system_info(multi_scheduling_blockers), erlang:sys‐
8037 tem_info(normal_multi_scheduling_blockers), and erlang:sys‐
8038 tem_info(schedulers).
8039 multi_scheduling_blockers:
8041 Returns a list of Pids when multi-scheduling is blocked,
8044 otherwise the empty list is returned. The Pids in the list
8045 represent all the processes currently blocking multi-sched‐
8046 uling. A Pid occurs only once in the list, even if the cor‐
8047 responding process has blocked multiple times.
8048 See also erlang:system_flag(multi_scheduling, BlockState),
8050 erlang:system_info(multi_scheduling), erlang:sys‐
8051 tem_info(normal_multi_scheduling_blockers), and erlang:sys‐
8052 tem_info(schedulers).
8053 nif_version:
8055 Returns a string containing the version of the Erlang NIF
8056 interface used by the runtime system. It is on the form
8057 "<major ver>.<minor ver>".
8058 normal_multi_scheduling_blockers:
8060 Returns a list of Pids when normal multi-scheduling is
8063 blocked (that is, all normal schedulers but one is blocked),
8064 otherwise the empty list is returned. The Pids in the list
8065 represent all the processes currently blocking normal multi-
8066 scheduling. A Pid occurs only once in the list, even if the
8067 corresponding process has blocked multiple times.
8068 See also erlang:system_flag(multi_scheduling, BlockState),
8070 erlang:system_info(multi_scheduling), erlang:sys‐
8071 tem_info(multi_scheduling_blockers), and erlang:sys‐
8072 tem_info(schedulers).
8073 otp_release:
8075 Returns a string containing the OTP release number of the
8078 OTP release that the currently executing ERTS application is
8079 part of.
8080 As from Erlang/OTP 17, the OTP release number corresponds to
8082 the major OTP version number. No erlang:system_info() argu‐
8083 ment gives the exact OTP version. This is because the exact
8084 OTP version in the general case is difficult to determine.
8085 For more information, see the description of versions in
8086 System principles in System Documentation.
8087 os_monotonic_time_source:
8089 Returns a list containing information about the source of OS
8090 monotonic time that is used by the runtime system.
8091 If [] is returned, no OS monotonic time is available. The
8093 list contains two-tuples with Keys as first element, and
8094 Values as second element. The order of these tuples is unde‐
8095 fined. The following tuples can be part of the list, but
8096 more tuples can be introduced in the future:
8097 {function, Function}:
8099 Function is the name of the function used. This tuple
8100 always exists if OS monotonic time is available to the
8101 runtime system.
8102 {clock_id, ClockId}:
8104 This tuple only exists if Function can be used with dif‐
8105 ferent clocks. ClockId corresponds to the clock identifier
8106 used when calling Function.
8107 {resolution, OsMonotonicTimeResolution}:
8109 Highest possible resolution of current OS monotonic time
8110 source as parts per second. If no resolution information
8111 can be retrieved from the OS, OsMonotonicTimeResolution is
8112 set to the resolution of the time unit of Functions return
8113 value. That is, the actual resolution can be lower than
8114 OsMonotonicTimeResolution. Notice that the resolution does
8115 not say anything about the accuracy or whether the pre‐
8116 cision aligns with the resolution. You do, however, know
8117 that the precision is not better than OsMonotonicTimeReso‐
8118 lution.
8119 {extended, Extended}:
8121 Extended equals yes if the range of time values has been
8122 extended; otherwise Extended equals no. The range must be
8123 extended if Function returns values that wrap fast. This
8124 typically is the case when the return value is a 32-bit
8125 value.
8126 {parallel, Parallel}:
8128 Parallel equals yes if Function is called in parallel from
8129 multiple threads. If it is not called in parallel, because
8130 calls must be serialized, Parallel equals no.
8131 {time, OsMonotonicTime}:
8133 OsMonotonicTime equals current OS monotonic time in native
8134 time unit.
8135 os_system_time_source:
8137 Returns a list containing information about the source of OS
8138 system time that is used by the runtime system.
8139 The list contains two-tuples with Keys as first element, and
8141 Values as second element. The order if these tuples is unde‐
8142 fined. The following tuples can be part of the list, but
8143 more tuples can be introduced in the future:
8144 {function, Function}:
8146 Function is the name of the funcion used.
8147 {clock_id, ClockId}:
8149 Exists only if Function can be used with different clocks.
8150 ClockId corresponds to the clock identifier used when
8151 calling Function.
8152 {resolution, OsSystemTimeResolution}:
8154 Highest possible resolution of current OS system time
8155 source as parts per second. If no resolution information
8156 can be retrieved from the OS, OsSystemTimeResolution is
8157 set to the resolution of the time unit of Functions return
8158 value. That is, the actual resolution can be lower than
8159 OsSystemTimeResolution. Notice that the resolution does
8160 not say anything about the accuracy or whether the pre‐
8161 cision do align with the resolution. You do, however, know
8162 that the precision is not better than OsSystemTimeResolu‐
8163 tion.
8164 {parallel, Parallel}:
8166 Parallel equals yes if Function is called in parallel from
8167 multiple threads. If it is not called in parallel, because
8168 calls needs to be serialized, Parallel equals no.
8169 {time, OsSystemTime}:
8171 OsSystemTime equals current OS system time in native time
8172 unit.
8173 port_parallelism:
8175 Returns the default port parallelism scheduling hint used.
8178 For more information, see command-line argument +spp in
8179 erl(1).
8180 port_count:
8182 Returns the number of ports currently existing at the local
8183 node. The value is given as an integer. This is the same
8184 value as returned by length(erlang:ports()), but more effi‐
8185 cient.
8186 port_limit:
8188 Returns the maximum number of simultaneously existing ports
8191 at the local node as an integer. This limit can be config‐
8192 ured at startup by using command-line flag +Q in erl(1).
8193 process_count:
8195 Returns the number of processes currently existing at the
8196 local node. The value is given as an integer. This is the
8197 same value as returned by length(processes()), but more
8198 efficient.
8199 process_limit:
8201 Returns the maximum number of simultaneously existing pro‐
8204 cesses at the local node. The value is given as an integer.
8205 This limit can be configured at startup by using command-
8206 line flag +P in erl(1).
8207 procs:
8209 Returns a binary containing a string of process and port
8210 information formatted as in Erlang crash dumps. For more
8211 information, see section How to interpret the Erlang crash
8212 dumps in the User's Guide.
8213 scheduler_bind_type:
8215 Returns information about how the user has requested sched‐
8218 ulers to be bound or not bound.
8219 Notice that although a user has requested schedulers to be
8221 bound, they can silently have failed to bind. To inspect the
8222 scheduler bindings, call erlang:system_info(scheduler_bind‐
8223 ings).
8224 For more information, see command-line argument +sbt in
8226 erl(1) and erlang:system_info(scheduler_bindings).
8227 scheduler_bindings:
8229 Returns information about the currently used scheduler bind‐
8232 ings.
8233 A tuple of a size equal to erlang:system_info(schedulers) is
8235 returned. The tuple elements are integers or the atom
8236 unbound. Logical processor identifiers are represented as
8237 integers. The Nth element of the tuple equals the current
8238 binding for the scheduler with the scheduler identifier
8239 equal to N. For example, if the schedulers are bound, ele‐
8240 ment(erlang:system_info(scheduler_id), erlang:sys‐
8241 tem_info(scheduler_bindings)) returns the identifier of the
8242 logical processor that the calling process is executing on.
8243 Notice that only schedulers online can be bound to logical
8245 processors.
8246 For more information, see command-line argument +sbt in
8248 erl(1) and erlang:system_info(schedulers_online).
8249 scheduler_id:
8251 Returns the scheduler ID (SchedulerId) of the scheduler
8254 thread that the calling process is executing on. SchedulerId
8255 is a positive integer, where 1 <= SchedulerId <= erlang:sys‐
8256 tem_info(schedulers).
8257 See also erlang:system_info(schedulers).
8259 schedulers:
8261 Returns the number of scheduler threads used by the emula‐
8264 tor. Scheduler threads online schedules Erlang processes and
8265 Erlang ports, and execute Erlang code and Erlang linked-in
8266 driver code.
8267 The number of scheduler threads is determined at emulator
8269 boot time and cannot be changed later. However, the number
8270 of schedulers online can be changed at any time.
8271 See also erlang:system_flag(schedulers_online, SchedulersOn‐
8273 line), erlang:system_info(schedulers_online), erlang:sys‐
8274 tem_info(scheduler_id), erlang:system_flag(multi_scheduling,
8275 BlockState), erlang:system_info(multi_scheduling),
8276 erlang:system_info(normal_multi_scheduling_blockers) and
8277 erlang:system_info(multi_scheduling_blockers).
8278 schedulers_online:
8280 Returns the number of schedulers online. The scheduler iden‐
8283 tifiers of schedulers online satisfy the relationship 1 <=
8284 SchedulerId <= erlang:system_info(schedulers_online).
8285 For more information, see erlang:system_info(schedulers) and
8287 erlang:system_flag(schedulers_online, SchedulersOnline).
8288 smp_support:
8290 Returns true if the emulator has been compiled with SMP sup‐
8291 port, otherwise false is returned.
8292 start_time:
8294 The Erlang monotonic time in native time unit at the time
8295 when current Erlang runtime system instance started.
8296 See also erlang:system_info(end_time).
8298 system_version:
8300 Returns a string containing version number and some impor‐
8301 tant properties, such as the number of schedulers.
8302 system_architecture:
8304 Returns a string containing the processor and OS architec‐
8305 ture the emulator is built for.
8306 threads:
8308 Returns true if the emulator has been compiled with thread
8309 support, otherwise false is returned.
8310 thread_pool_size:
8312 Returns the number of async threads in the async thread pool
8315 used for asynchronous driver calls
8316 (erl_driver:driver_async()). The value is given as an inte‐
8317 ger.
8318 time_correction:
8320 Returns a boolean value indicating whether time correction
8323 is enabled or not.
8324 time_offset:
8326 Returns the state of the time offset:
8329 preliminary:
8331 The time offset is preliminary, and will be changed and
8332 finalized later. The preliminary time offset is used dur‐
8333 ing the preliminary phase of the single time warp mode.
8334 final:
8336 The time offset is final. This either because no time
8337 warp mode is used, or because the time offset have been
8338 finalized when single time warp mode is used.
8339 volatile:
8341 The time offset is volatile. That is, it can change at any
8342 time. This is because multi-time warp mode is used.
8343 time_warp_mode:
8345 Returns a value identifying the time warp mode that is
8346 used:
8347 no_time_warp:
8349 The no time warp mode is used.
8350 single_time_warp:
8352 The single time warp mode is used.
8353 multi_time_warp:
8355 The multi-time warp mode is used.
8356 tolerant_timeofday:
8358 Returns whether a pre ERTS 7.0 backwards compatible compen‐
8361 sation for sudden changes of system time is enabled or dis‐
8362 abled. Such compensation is enabled when the time offset is
8363 final, and time correction is enabled.
8364 trace_control_word:
8366 Returns the value of the node trace control word. For more
8367 information, see function get_tcw in section Match Specifi‐
8368 cations in Erlang in the User's Guide.
8369 update_cpu_info:
8371 The runtime system rereads the CPU information available and
8374 updates its internally stored information about the detected
8375 CPU topology and the number of logical processors config‐
8376 ured, online, and available.
8377 If the CPU information has changed since the last time it
8379 was read, the atom changed is returned, otherwise the atom
8380 unchanged. If the CPU information has changed, you probably
8381 want to adjust the number of schedulers online. You typi‐
8382 cally want to have as many schedulers online as logical pro‐
8383 cessors available.
8384 version:
8386 Returns a string containing the version number of the emula‐
8389 tor.
8390 wordsize:
8392 Same as {wordsize, internal}.
8393 {wordsize, internal}:
8395 Returns the size of Erlang term words in bytes as an inte‐
8396 ger, that is, 4 is returned on a 32-bit architecture, and 8
8397 is returned on a pure 64-bit architecture. On a halfword
8398 64-bit emulator, 4 is returned, as the Erlang terms are
8399 stored using a virtual word size of half the system word
8400 size.
8401 {wordsize, external}:
8403 Returns the true word size of the emulator, that is, the
8404 size of a pointer. The value is given in bytes as an inte‐
8405 ger. On a pure 32-bit architecture, 4 is returned. On both a
8406 half word and on a pure 64-bit architecture, 8 is returned.
8407 Note:
8409 Argument scheduler has changed name to scheduler_id to avoid mix
8410 up with argument schedulers. Argument scheduler was introduced
8411 in ERTS 5.5 and renamed in ERTS 5.5.1.
8412 erlang:system_monitor() -> MonSettings
8415 Types:
8417 MonSettings = undefined | {MonitorPid, Options}
8419 MonitorPid = pid()
8420 Options = [system_monitor_option()]
8421 system_monitor_option() =
8422 busy_port |
8423 busy_dist_port |
8424 {long_gc, integer() >= 0} |
8425 {long_schedule, integer() >= 0} |
8426 {large_heap, integer() >= 0}
8427 Returns the current system monitoring settings set by
8429 erlang:system_monitor/2 as {MonitorPid, Options}, or undefined
8430 if no settings exist. The order of the options can be different
8431 from the one that was set.
8432 erlang:system_monitor(Arg) -> MonSettings
8434 Types:
8436 Arg = MonSettings = undefined | {MonitorPid, Options}
8438 MonitorPid = pid()
8439 Options = [system_monitor_option()]
8440 system_monitor_option() =
8441 busy_port |
8442 busy_dist_port |
8443 {long_gc, integer() >= 0} |
8444 {long_schedule, integer() >= 0} |
8445 {large_heap, integer() >= 0}
8446 When called with argument undefined, all system performance mon‐
8448 itoring settings are cleared.
8449 Calling the function with {MonitorPid, Options} as argument is
8451 the same as calling erlang:system_monitor(MonitorPid, Options).
8452 Returns the previous system monitor settings just like
8454 erlang:system_monitor/0.
8455 erlang:system_monitor(MonitorPid, Options) -> MonSettings
8457 Types:
8459 MonitorPid = pid()
8461 Options = [system_monitor_option()]
8462 MonSettings = undefined | {OldMonitorPid, OldOptions}
8463 OldMonitorPid = pid()
8464 OldOptions = [system_monitor_option()]
8465 system_monitor_option() =
8466 busy_port |
8467 busy_dist_port |
8468 {long_gc, integer() >= 0} |
8469 {long_schedule, integer() >= 0} |
8470 {large_heap, integer() >= 0}
8471 Sets the system performance monitoring options. MonitorPid is a
8473 local process identifier (pid) receiving system monitor mes‐
8474 sages. The second argument is a list of monitoring options:
8475 {long_gc, Time}:
8477 If a garbage collection in the system takes at least Time
8478 wall clock milliseconds, a message {monitor, GcPid, long_gc,
8479 Info} is sent to MonitorPid. GcPid is the pid that was
8480 garbage collected. Info is a list of two-element tuples
8481 describing the result of the garbage collection.
8482 One of the tuples is {timeout, GcTime}, where GcTime is the
8484 time for the garbage collection in milliseconds. The other
8485 tuples are tagged with heap_size, heap_block_size,
8486 stack_size, mbuf_size, old_heap_size, and
8487 old_heap_block_size. These tuples are explained in the
8488 description of trace message gc_minor_start (see
8489 erlang:trace/3). New tuples can be added, and the order of
8490 the tuples in the Info list can be changed at any time with‐
8491 out prior notice.
8492 {long_schedule, Time}:
8494 If a process or port in the system runs uninterrupted for at
8495 least Time wall clock milliseconds, a message {monitor,
8496 PidOrPort, long_schedule, Info} is sent to MonitorPid.
8497 PidOrPort is the process or port that was running. Info is a
8498 list of two-element tuples describing the event.
8499 If a pid(), the tuples {timeout, Millis}, {in, Location},
8501 and {out, Location} are present, where Location is either an
8502 MFA ({Module, Function, Arity}) describing the function
8503 where the process was scheduled in/out, or the atom unde‐
8504 fined.
8505 If a port(), the tuples {timeout, Millis} and {port_op,Op}
8507 are present. Op is one of proc_sig, timeout, input, output,
8508 event, or dist_cmd, depending on which driver callback was
8509 executing.
8510 proc_sig is an internal operation and is never to appear,
8512 while the others represent the corresponding driver call‐
8513 backs timeout, ready_input, ready_output, event, and outputv
8514 (when the port is used by distribution). Value Millis in
8515 tuple timeout informs about the uninterrupted execution time
8516 of the process or port, which always is equal to or higher
8517 than the Time value supplied when starting the trace. New
8518 tuples can be added to the Info list in a future release.
8519 The order of the tuples in the list can be changed at any
8520 time without prior notice.
8521 This can be used to detect problems with NIFs or drivers
8523 that take too long to execute. 1 ms is considered a good
8524 maximum time for a driver callback or a NIF. However, a
8525 time-sharing system is usually to consider everything < 100
8526 ms as "possible" and fairly "normal". However, longer sched‐
8527 ule times can indicate swapping or a misbehaving NIF/driver.
8528 Misbehaving NIFs and drivers can cause bad resource utiliza‐
8529 tion and bad overall system performance.
8530 {large_heap, Size}:
8532 If a garbage collection in the system results in the allo‐
8533 cated size of a heap being at least Size words, a message
8534 {monitor, GcPid, large_heap, Info} is sent to MonitorPid.
8535 GcPid and Info are the same as for long_gc earlier, except
8536 that the tuple tagged with timeout is not present.
8537 The monitor message is sent if the sum of the sizes of all
8539 memory blocks allocated for all heap generations after a
8540 garbage collection is equal to or higher than Size.
8541 When a process is killed by max_heap_size, it is killed
8543 before the garbage collection is complete and thus no large
8544 heap message is sent.
8545 busy_port:
8547 If a process in the system gets suspended because it sends
8548 to a busy port, a message {monitor, SusPid, busy_port, Port}
8549 is sent to MonitorPid. SusPid is the pid that got suspended
8550 when sending to Port.
8551 busy_dist_port:
8553 If a process in the system gets suspended because it sends
8554 to a process on a remote node whose inter-node communication
8555 was handled by a busy port, a message {monitor, SusPid,
8556 busy_dist_port, Port} is sent to MonitorPid. SusPid is the
8557 pid that got suspended when sending through the inter-node
8558 communication port Port.
8559 Returns the previous system monitor settings just like
8561 erlang:system_monitor/0.
8562 Note:
8564 If a monitoring process gets so large that it itself starts to
8565 cause system monitor messages when garbage collecting, the mes‐
8566 sages enlarge the process message queue and probably make the
8567 problem worse.
8568 Keep the monitoring process neat and do not set the system moni‐
8570 tor limits too tight.
8571 Failures:
8574 badarg:
8576 If MonitorPid does not exist.
8577 badarg:
8579 If MonitorPid is not a local process.
8580 erlang:system_profile() -> ProfilerSettings
8582 Types:
8584 ProfilerSettings = undefined | {ProfilerPid, Options}
8586 ProfilerPid = pid() | port()
8587 Options = [system_profile_option()]
8588 system_profile_option() =
8589 exclusive |
8590 runnable_ports |
8591 runnable_procs |
8592 scheduler |
8593 timestamp |
8594 monotonic_timestamp |
8595 strict_monotonic_timestamp
8596 Returns the current system profiling settings set by erlang:sys‐
8598 tem_profile/2 as {ProfilerPid, Options}, or undefined if there
8599 are no settings. The order of the options can be different from
8600 the one that was set.
8601 erlang:system_profile(ProfilerPid, Options) -> ProfilerSettings
8603 Types:
8605 ProfilerPid = pid() | port() | undefined
8607 Options = [system_profile_option()]
8608 ProfilerSettings =
8609 undefined | {pid() | port(), [system_profile_option()]}
8610 system_profile_option() =
8611 exclusive |
8612 runnable_ports |
8613 runnable_procs |
8614 scheduler |
8615 timestamp |
8616 monotonic_timestamp |
8617 strict_monotonic_timestamp
8618 Sets system profiler options. ProfilerPid is a local process
8620 identifier (pid) or port receiving profiling messages. The
8621 receiver is excluded from all profiling. The second argument is
8622 a list of profiling options:
8623 exclusive:
8625 If a synchronous call to a port from a process is done, the
8626 calling process is considered not runnable during the call
8627 runtime to the port. The calling process is notified as
8628 inactive, and later active when the port callback returns.
8629 monotonic_timestamp:
8631 Time stamps in profile messages use Erlang monotonic time.
8632 The time stamp (Ts) has the same format and value as pro‐
8633 duced by erlang:monotonic_time(nanosecond).
8634 runnable_procs:
8636 If a process is put into or removed from the run queue, a
8637 message, {profile, Pid, State, Mfa, Ts}, is sent to Profil‐
8638 erPid. Running processes that are reinserted into the run
8639 queue after having been pre-empted do not trigger this mes‐
8640 sage.
8641 runnable_ports:
8643 If a port is put into or removed from the run queue, a mes‐
8644 sage, {profile, Port, State, 0, Ts}, is sent to ProfilerPid.
8645 scheduler:
8647 If a scheduler is put to sleep or awoken, a message, {pro‐
8648 file, scheduler, Id, State, NoScheds, Ts}, is sent to Pro‐
8649 filerPid.
8650 strict_monotonic_timestamp:
8652 Time stamps in profile messages consist of Erlang monotonic
8653 time and a monotonically increasing integer. The time stamp
8654 (Ts) has the same format and value as produced by
8655 {erlang:monotonic_time(nanosecond), erlang:unique_inte‐
8656 ger([monotonic])}.
8657 timestamp:
8659 Time stamps in profile messages include a time stamp (Ts)
8660 that has the same form as returned by erlang:now(). This is
8661 also the default if no time stamp flag is specified. If
8662 cpu_timestamp has been enabled through erlang:trace/3, this
8663 also effects the time stamp produced in profiling messages
8664 when flag timestamp is enabled.
8665 Note:
8667 erlang:system_profile behavior can change in a future release.
8668 erlang:system_time() -> integer()
8671 Returns current Erlang system time in native time unit.
8673 Calling erlang:system_time() is equivalent to erlang:mono‐
8675 tonic_time() + erlang:time_offset().
8676 Note:
8678 This time is not a monotonically increasing time in the general
8679 case. For more information, see the documentation of time warp
8680 modes in the User's Guide.
8681 erlang:system_time(Unit) -> integer()
8684 Types:
8686 Unit = time_unit()
8688 Returns current Erlang system time converted into the Unit
8690 passed as argument.
8691 Calling erlang:system_time(Unit) is equivalent to erlang:con‐
8693 vert_time_unit(erlang:system_time(), native, Unit).
8694 Note:
8696 This time is not a monotonically increasing time in the general
8697 case. For more information, see the documentation of time warp
8698 modes in the User's Guide.
8699 term_to_binary(Term) -> ext_binary()
8702 Types:
8704 Term = term()
8706 Returns a binary data object that is the result of encoding Term
8708 according to the Erlang external term format.
8709 This can be used for various purposes, for example, writing a
8711 term to a file in an efficient way, or sending an Erlang term to
8712 some type of communications channel not supported by distributed
8713 Erlang.
8714 > Bin = term_to_binary(hello).
8716 <<131,100,0,5,104,101,108,108,111>>
8717 > hello = binary_to_term(Bin).
8718 hello
8719 See also binary_to_term/1.
8722 Note:
8724 There is no guarantee that this function will return the same
8725 encoded representation for the same term.
8726 term_to_binary(Term, Options) -> ext_binary()
8729 Types:
8731 Term = term()
8733 Options =
8734 [compressed |
8735 {compressed, Level :: 0..9} |
8736 {minor_version, Version :: 0..2}]
8737 Returns a binary data object that is the result of encoding Term
8739 according to the Erlang external term format.
8740 If option compressed is provided, the external term format is
8742 compressed. The compressed format is automatically recognized by
8743 binary_to_term/1 as from Erlang/OTP R7B.
8744 A compression level can be specified by giving option {com‐
8746 pressed, Level}. Level is an integer with range 0..9, where:
8747 * 0 - No compression is done (it is the same as giving no com‐
8749 pressed option).
8750 * 1 - Takes least time but may not compress as well as the
8752 higher levels.
8753 * 6 - Default level when option compressed is provided.
8755 * 9 - Takes most time and tries to produce a smaller result.
8757 Notice "tries" in the preceding sentence; depending on the
8758 input term, level 9 compression either does or does not pro‐
8759 duce a smaller result than level 1 compression.
8760 Option {minor_version, Version} can be used to control some
8762 encoding details. This option was introduced in Erlang/OTP
8763 R11B-4. The valid values for Version are:
8764 0:
8766 Floats are encoded using a textual representation. This
8767 option is useful to ensure that releases before Erlang/OTP
8768 R11B-4 can decode resulting binary.
8769 This version encode atoms that can be represented by a
8771 latin1 string using latin1 encoding while only atoms that
8772 cannot be represented by latin1 are encoded using utf8.
8773 1:
8775 This is as of Erlang/OTP 17.0 the default. It forces any
8776 floats in the term to be encoded in a more space-efficient
8777 and exact way (namely in the 64-bit IEEE format, rather than
8778 converted to a textual representation). As from Erlang/OTP
8779 R11B-4, binary_to_term/1 can decode this representation.
8780 This version encode atoms that can be represented by a
8782 latin1 string using latin1 encoding while only atoms that
8783 cannot be represented by latin1 are encoded using utf8.
8784 2:
8786 Drops usage of the latin1 atom encoding and unconditionally
8787 use utf8 encoding for all atoms. This will be changed to the
8788 default in a future major release of Erlang/OTP. Erlang/OTP
8789 systems as of R16B can decode this representation.
8790 See also binary_to_term/1.
8792 throw(Any) -> no_return()
8794 Types:
8796 Any = term()
8798 A non-local return from a function. If evaluated within a catch,
8800 catch returns value Any. Example:
8801 > catch throw({hello, there}).
8803 {hello,there}
8804 Failure: nocatch if not evaluated within a catch.
8806 time() -> Time
8808 Types:
8810 Time = calendar:time()
8812 Returns the current time as {Hour, Minute, Second}.
8814 The time zone and Daylight Saving Time correction depend on the
8816 underlying OS. Example:
8817 > time().
8819 {9,42,44}
8820 erlang:time_offset() -> integer()
8822 Returns the current time offset between Erlang monotonic time
8824 and Erlang system time in native time unit. Current time offset
8825 added to an Erlang monotonic time gives corresponding Erlang
8826 system time.
8827 The time offset may or may not change during operation depending
8829 on the time warp mode used.
8830 Note:
8832 A change in time offset can be observed at slightly different
8833 points in time by different processes.
8834 If the runtime system is in multi-time warp mode, the time off‐
8836 set is changed when the runtime system detects that the OS sys‐
8837 tem time has changed. The runtime system will, however, not
8838 detect this immediately when it occurs. A task checking the time
8839 offset is scheduled to execute at least once a minute; so, under
8840 normal operation this is to be detected within a minute, but
8841 during heavy load it can take longer time.
8842 erlang:time_offset(Unit) -> integer()
8845 Types:
8847 Unit = time_unit()
8849 Returns the current time offset between Erlang monotonic time
8851 and Erlang system time converted into the Unit passed as argu‐
8852 ment.
8853 Same as calling erlang:convert_time_unit(erlang:time_offset(),
8855 native, Unit) however optimized for commonly used Units.
8856 erlang:timestamp() -> Timestamp
8858 Types:
8860 Timestamp = timestamp()
8862 timestamp() =
8863 {MegaSecs :: integer() >= 0,
8864 Secs :: integer() >= 0,
8865 MicroSecs :: integer() >= 0}
8866 Returns current Erlang system time on the format {MegaSecs,
8868 Secs, MicroSecs}. This format is the same as os:timestamp/0 and
8869 the deprecated erlang:now/0 use. The reason for the existence of
8870 erlang:timestamp() is purely to simplify use for existing code
8871 that assumes this time stamp format. Current Erlang system time
8872 can more efficiently be retrieved in the time unit of your
8873 choice using erlang:system_time/1.
8874 The erlang:timestamp() BIF is equivalent to:
8876 timestamp() ->
8878 ErlangSystemTime = erlang:system_time(microsecond),
8879 MegaSecs = ErlangSystemTime div 1000000000000,
8880 Secs = ErlangSystemTime div 1000000 - MegaSecs*1000000,
8881 MicroSecs = ErlangSystemTime rem 1000000,
8882 {MegaSecs, Secs, MicroSecs}.
8883 It, however, uses a native implementation that does not build
8885 garbage on the heap and with slightly better performance.
8886 Note:
8888 This time is not a monotonically increasing time in the general
8889 case. For more information, see the documentation of time warp
8890 modes in the User's Guide.
8891 tl(List) -> term()
8894 Types:
8896 List = [term(), ...]
8898 Returns the tail of List, that is, the list minus the first ele‐
8900 ment, for example:
8901 > tl([geesties, guilies, beasties]).
8903 [guilies, beasties]
8904 Allowed in guard tests.
8906 Failure: badarg if List is the empty list [].
8908 erlang:trace(PidPortSpec, How, FlagList) -> integer()
8910 Types:
8912 PidPortSpec =
8914 pid() |
8915 port() |
8916 all |
8917 processes |
8918 ports |
8919 existing |
8920 existing_processes |
8921 existing_ports |
8922 new |
8923 new_processes |
8924 new_ports
8925 How = boolean()
8926 FlagList = [trace_flag()]
8927 trace_flag() =
8928 all |
8929 send |
8930 'receive' |
8931 procs |
8932 ports |
8933 call |
8934 arity |
8935 return_to |
8936 silent |
8937 running |
8938 exiting |
8939 running_procs |
8940 running_ports |
8941 garbage_collection |
8942 timestamp |
8943 cpu_timestamp |
8944 monotonic_timestamp |
8945 strict_monotonic_timestamp |
8946 set_on_spawn |
8947 set_on_first_spawn |
8948 set_on_link |
8949 set_on_first_link |
8950 {tracer, pid() | port()} |
8951 {tracer, module(), term()}
8952 Turns on (if How == true) or off (if How == false) the trace
8954 flags in FlagList for the process or processes represented by
8955 PidPortSpec.
8956 PidPortSpec is either a process identifier (pid) for a local
8958 process, a port identifier, or one of the following atoms:
8959 all:
8961 All currently existing processes and ports and all that will
8962 be created in the future.
8963 processes:
8965 All currently existing processes and all that will be cre‐
8966 ated in the future.
8967 ports:
8969 All currently existing ports and all that will be created in
8970 the future.
8971 existing:
8973 All currently existing processes and ports.
8974 existing_processes:
8976 All currently existing processes.
8977 existing_ports:
8979 All currently existing ports.
8980 new:
8982 All processes and ports that will be created in the future.
8983 new_processes:
8985 All processes that will be created in the future.
8986 new_ports:
8988 All ports that will be created in the future.
8989 FlagList can contain any number of the following flags (the
8991 "message tags" refers to the list of trace messages):
8992 all:
8994 Sets all trace flags except tracer and cpu_timestamp, which
8995 are in their nature different than the others.
8996 send:
8998 Traces sending of messages.
8999 Message tags: send and send_to_non_existing_process.
9001 'receive':
9003 Traces receiving of messages.
9004 Message tags: 'receive'.
9006 call:
9008 Traces certain function calls. Specify which function calls
9009 to trace by calling erlang:trace_pattern/3.
9010 Message tags: call and return_from.
9012 silent:
9014 Used with the call trace flag. The call, return_from, and
9015 return_to trace messages are inhibited if this flag is set,
9016 but they are executed as normal if there are match specifi‐
9017 cations.
9018 Silent mode is inhibited by executing erlang:trace(_, false,
9020 [silent|_]), or by a match specification executing the func‐
9021 tion {silent, false}.
9022 The silent trace flag facilitates setting up a trace on many
9024 or even all processes in the system. The trace can then be
9025 activated and deactivated using the match specification
9026 function {silent,Bool}, giving a high degree of control of
9027 which functions with which arguments that trigger the trace.
9028 Message tags: call, return_from, and return_to. Or rather,
9030 the absence of.
9031 return_to:
9033 Used with the call trace flag. Traces the return from a
9034 traced function back to its caller. Only works for functions
9035 traced with option local to erlang:trace_pattern/3.
9036 The semantics is that a trace message is sent when a call
9038 traced function returns, that is, when a chain of tail
9039 recursive calls ends. Only one trace message is sent per
9040 chain of tail recursive calls, so the properties of tail
9041 recursiveness for function calls are kept while tracing with
9042 this flag. Using call and return_to trace together makes it
9043 possible to know exactly in which function a process exe‐
9044 cutes at any time.
9045 To get trace messages containing return values from func‐
9047 tions, use the {return_trace} match specification action
9048 instead.
9049 Message tags: return_to.
9051 procs:
9053 Traces process-related events.
9054 Message tags: spawn, spawned, exit, register, unregister,
9056 link, unlink, getting_linked, and getting_unlinked.
9057 ports:
9059 Traces port-related events.
9060 Message tags: open, closed, register, unregister, get‐
9062 ting_linked, and getting_unlinked.
9063 running:
9065 Traces scheduling of processes.
9066 Message tags: in and out.
9068 exiting:
9070 Traces scheduling of exiting processes.
9071 Message tags: in_exiting, out_exiting, and out_exited.
9073 running_procs:
9075 Traces scheduling of processes just like running. However,
9076 this option also includes schedule events when the process
9077 executes within the context of a port without being sched‐
9078 uled out itself.
9079 Message tags: in and out.
9081 running_ports:
9083 Traces scheduling of ports.
9084 Message tags: in and out.
9086 garbage_collection:
9088 Traces garbage collections of processes.
9089 Message tags: gc_minor_start, gc_max_heap_size, and
9091 gc_minor_end.
9092 timestamp:
9094 Includes a time stamp in all trace messages. The time stamp
9095 (Ts) has the same form as returned by erlang:now().
9096 cpu_timestamp:
9098 A global trace flag for the Erlang node that makes all trace
9099 time stamps using flag timestamp to be in CPU time, not wall
9100 clock time. That is, cpu_timestamp is not be used if mono‐
9101 tonic_timestamp or strict_monotonic_timestamp is enabled.
9102 Only allowed with PidPortSpec==all. If the host machine OS
9103 does not support high-resolution CPU time measurements,
9104 trace/3 exits with badarg. Notice that most OS do not syn‐
9105 chronize this value across cores, so be prepared that time
9106 can seem to go backwards when using this option.
9107 monotonic_timestamp:
9109 Includes an Erlang monotonic time time stamp in all trace
9110 messages. The time stamp (Ts) has the same format and value
9111 as produced by erlang:monotonic_time(nanosecond). This flag
9112 overrides flag cpu_timestamp.
9113 strict_monotonic_timestamp:
9115 Includes an time stamp consisting of Erlang monotonic time
9116 and a monotonically increasing integer in all trace mes‐
9117 sages. The time stamp (Ts) has the same format and value as
9118 produced by { erlang:monotonic_time(nanosecond),
9119 erlang:unique_integer([monotonic])}. This flag overrides
9120 flag cpu_timestamp.
9121 arity:
9123 Used with the call trace flag. {M, F, Arity} is specified
9124 instead of {M, F, Args} in call trace messages.
9125 set_on_spawn:
9127 Makes any process created by a traced process inherit its
9128 trace flags, including flag set_on_spawn.
9129 set_on_first_spawn:
9131 Makes the first process created by a traced process inherit
9132 its trace flags, excluding flag set_on_first_spawn.
9133 set_on_link:
9135 Makes any process linked by a traced process inherit its
9136 trace flags, including flag set_on_link.
9137 set_on_first_link:
9139 Makes the first process linked to by a traced process
9140 inherit its trace flags, excluding flag set_on_first_link.
9141 {tracer, Tracer}:
9143 Specifies where to send the trace messages. Tracer must be
9144 the process identifier of a local process or the port iden‐
9145 tifier of a local port.
9146 {tracer, TracerModule, TracerState}:
9148 Specifies that a tracer module is to be called instead of
9149 sending a trace message. The tracer module can then ignore
9150 or change the trace message. For more details on how to
9151 write a tracer module, see erl_tracer(3).
9152 If no tracer is specified, the calling process receives all the
9154 trace messages.
9155 The effect of combining set_on_first_link with set_on_link is
9157 the same as set_on_first_link alone. Likewise for set_on_spawn
9158 and set_on_first_spawn.
9159 The tracing process receives the trace messages described in the
9161 following list. Pid is the process identifier of the traced
9162 process in which the traced event has occurred. The third tuple
9163 element is the message tag.
9164 If flag timestamp, strict_monotonic_timestamp, or mono‐
9166 tonic_timestamp is specified, the first tuple element is
9167 trace_ts instead, and the time stamp is added as an extra ele‐
9168 ment last in the message tuple. If multiple time stamp flags are
9169 passed, timestamp has precedence over strict_monotonic_time‐
9170 stamp, which in turn has precedence over monotonic_timestamp.
9171 All time stamp flags are remembered, so if two are passed and
9172 the one with highest precedence later is disabled, the other one
9173 becomes active.
9174 Trace messages:
9176 {trace, PidPort, send, Msg, To}:
9178 When PidPort sends message Msg to process To.
9179 {trace, PidPort, send_to_non_existing_process, Msg, To}:
9181 When PidPort sends message Msg to the non-existing process
9182 To.
9183 {trace, PidPort, 'receive', Msg}:
9185 When PidPort receives message Msg. If Msg is set to time-
9186 out, a receive statement can have timed out, or the process
9187 received a message with the payload timeout.
9188 {trace, Pid, call, {M, F, Args}}:
9190 When Pid calls a traced function. The return values of calls
9191 are never supplied, only the call and its arguments.
9192 Trace flag arity can be used to change the contents of this
9194 message, so that Arity is specified instead of Args.
9195 {trace, Pid, return_to, {M, F, Arity}}:
9197 When Pid returns to the specified function. This trace mes‐
9198 sage is sent if both the flags call and return_to are set,
9199 and the function is set to be traced on local function
9200 calls. The message is only sent when returning from a chain
9201 of tail recursive function calls, where at least one call
9202 generated a call trace message (that is, the functions match
9203 specification matched, and {message, false} was not an
9204 action).
9205 {trace, Pid, return_from, {M, F, Arity}, ReturnValue}:
9207 When Pid returns from the specified function. This trace
9208 message is sent if flag call is set, and the function has a
9209 match specification with a return_trace or exception_trace
9210 action.
9211 {trace, Pid, exception_from, {M, F, Arity}, {Class, Value}}:
9213 When Pid exits from the specified function because of an
9214 exception. This trace message is sent if flag call is set,
9215 and the function has a match specification with an excep‐
9216 tion_trace action.
9217 {trace, Pid, spawn, Pid2, {M, F, Args}}:
9219 When Pid spawns a new process Pid2 with the specified func‐
9220 tion call as entry point.
9221 Args is supposed to be the argument list, but can be any
9223 term if the spawn is erroneous.
9224 {trace, Pid, spawned, Pid2, {M, F, Args}}:
9226 When Pid is spawned by process Pid2 with the specified func‐
9227 tion call as entry point.
9228 Args is supposed to be the argument list, but can be any
9230 term if the spawn is erroneous.
9231 {trace, Pid, exit, Reason}:
9233 When Pid exits with reason Reason.
9234 {trace, PidPort, register, RegName}:
9236 When PidPort gets the name RegName registered.
9237 {trace, PidPort, unregister, RegName}:
9239 When PidPort gets the name RegName unregistered. This is
9240 done automatically when a registered process or port exits.
9241 {trace, Pid, link, Pid2}:
9243 When Pid links to a process Pid2.
9244 {trace, Pid, unlink, Pid2}:
9246 When Pid removes the link from a process Pid2.
9247 {trace, PidPort, getting_linked, Pid2}:
9249 When PidPort gets linked to a process Pid2.
9250 {trace, PidPort, getting_unlinked, Pid2}:
9252 When PidPort gets unlinked from a process Pid2.
9253 {trace, Pid, exit, Reason}:
9255 When Pid exits with reason Reason.
9256 {trace, Port, open, Pid, Driver}:
9258 When Pid opens a new port Port with the running Driver.
9259 Driver is the name of the driver as an atom.
9261 {trace, Port, closed, Reason}:
9263 When Port closes with Reason.
9264 {trace, Pid, in | in_exiting, {M, F, Arity} | 0}:
9266 When Pid is scheduled to run. The process runs in function
9267 {M, F, Arity}. On some rare occasions, the current function
9268 cannot be determined, then the last element is 0.
9269 {trace, Pid, out | out_exiting | out_exited, {M, F, Arity} |
9271 0}:
9272 When Pid is scheduled out. The process was running in func‐
9273 tion {M, F, Arity}. On some rare occasions, the current
9274 function cannot be determined, then the last element is 0.
9275 {trace, Port, in, Command | 0}:
9277 When Port is scheduled to run. Command is the first thing
9278 the port will execute, it can however run several commands
9279 before being scheduled out. On some rare occasions, the cur‐
9280 rent function cannot be determined, then the last element is
9281 0.
9282 The possible commands are call, close, command, connect,
9284 control, flush, info, link, open, and unlink.
9285 {trace, Port, out, Command | 0}:
9287 When Port is scheduled out. The last command run was Com‐
9288 mand. On some rare occasions, the current function cannot be
9289 determined, then the last element is 0. Command can contain
9290 the same commands as in
9291 {trace, Pid, gc_minor_start, Info}:
9293 Sent when a young garbage collection is about to be started.
9296 Info is a list of two-element tuples, where the first ele‐
9297 ment is a key, and the second is the value. Do not depend on
9298 any order of the tuples. The following keys are defined:
9299 heap_size:
9301 The size of the used part of the heap.
9302 heap_block_size:
9304 The size of the memory block used for storing the heap and
9305 the stack.
9306 old_heap_size:
9308 The size of the used part of the old heap.
9309 old_heap_block_size:
9311 The size of the memory block used for storing the old
9312 heap.
9313 stack_size:
9315 The size of the stack.
9316 recent_size:
9318 The size of the data that survived the previous garbage
9319 collection.
9320 mbuf_size:
9322 The combined size of message buffers associated with the
9323 process.
9324 bin_vheap_size:
9326 The total size of unique off-heap binaries referenced from
9327 the process heap.
9328 bin_vheap_block_size:
9330 The total size of binaries allowed in the virtual heap in
9331 the process before doing a garbage collection.
9332 bin_old_vheap_size:
9334 The total size of unique off-heap binaries referenced from
9335 the process old heap.
9336 bin_old_vheap_block_size:
9338 The total size of binaries allowed in the virtual old heap
9339 in the process before doing a garbage collection.
9340 All sizes are in words.
9342 {trace, Pid, gc_max_heap_size, Info}:
9344 Sent when the max_heap_size is reached during garbage col‐
9345 lection. Info contains the same kind of list as in message
9346 gc_start, but the sizes reflect the sizes that triggered
9347 max_heap_size to be reached.
9348 {trace, Pid, gc_minor_end, Info}:
9350 Sent when young garbage collection is finished. Info con‐
9351 tains the same kind of list as in message gc_minor_start,
9352 but the sizes reflect the new sizes after garbage collec‐
9353 tion.
9354 {trace, Pid, gc_major_start, Info}:
9356 Sent when fullsweep garbage collection is about to be
9357 started. Info contains the same kind of list as in message
9358 gc_minor_start.
9359 {trace, Pid, gc_major_end, Info}:
9361 Sent when fullsweep garbage collection is finished. Info
9362 contains the same kind of list as in message gc_minor_start,
9363 but the sizes reflect the new sizes after a fullsweep
9364 garbage collection.
9365 If the tracing process/port dies or the tracer module returns
9367 remove, the flags are silently removed.
9368 Each process can only be traced by one tracer. Therefore,
9370 attempts to trace an already traced process fail.
9371 Returns a number indicating the number of processes that matched
9373 PidPortSpec. If PidPortSpec is a process identifier, the return
9374 value is 1. If PidPortSpec is all or existing, the return value
9375 is the number of processes running. If PidPortSpec is new, the
9376 return value is 0.
9377 Failure: badarg if the specified arguments are not supported.
9379 For example, cpu_timestamp is not supported on all platforms.
9380 erlang:trace_delivered(Tracee) -> Ref
9382 Types:
9384 Tracee = pid() | all
9386 Ref = reference()
9387 The delivery of trace messages (generated by erlang:trace/3,
9389 seq_trace(3), or erlang:system_profile/2) is dislocated on the
9390 time-line compared to other events in the system. If you know
9391 that Tracee has passed some specific point in its execution, and
9392 you want to know when at least all trace messages corresponding
9393 to events up to this point have reached the tracer, use
9394 erlang:trace_delivered(Tracee).
9395 When it is guaranteed that all trace messages are delivered to
9397 the tracer up to the point that Tracee reached at the time of
9398 the call to erlang:trace_delivered(Tracee), then a {trace_deliv‐
9399 ered, Tracee, Ref} message is sent to the caller of
9400 erlang:trace_delivered(Tracee) .
9401 Notice that message trace_delivered does not imply that trace
9403 messages have been delivered. Instead it implies that all trace
9404 messages that are to be delivered have been delivered. It is not
9405 an error if Tracee is not, and has not been traced by someone,
9406 but if this is the case, no trace messages have been delivered
9407 when the trace_delivered message arrives.
9408 Notice that Tracee must refer to a process currently or previ‐
9410 ously existing on the same node as the caller of
9411 erlang:trace_delivered(Tracee) resides on. The special Tracee
9412 atom all denotes all processes that currently are traced in the
9413 node.
9414 When used together with a Tracer Module, any message sent in
9416 the trace callback is guaranteed to have reached its recipient
9417 before the trace_delivered message is sent.
9418 Example: Process A is Tracee, port B is tracer, and process C is
9420 the port owner of B. C wants to close B when A exits. To ensure
9421 that the trace is not truncated, C can call erlang:trace_deliv‐
9422 ered(A) when A exits, and wait for message {trace_delivered, A,
9423 Ref} before closing B.
9424 Failure: badarg if Tracee does not refer to a process (dead or
9426 alive) on the same node as the caller of erlang:trace_deliv‐
9427 ered(Tracee) resides on.
9428 erlang:trace_info(PidPortFuncEvent, Item) -> Res
9430 Types:
9432 PidPortFuncEvent =
9434 pid() |
9435 port() |
9436 new |
9437 new_processes |
9438 new_ports |
9439 {Module, Function, Arity} |
9440 on_load |
9441 send |
9442 'receive'
9443 Module = module()
9444 Function = atom()
9445 Arity = arity()
9446 Item =
9447 flags |
9448 tracer |
9449 traced |
9450 match_spec |
9451 meta |
9452 meta_match_spec |
9453 call_count |
9454 call_time |
9455 all
9456 Res = trace_info_return()
9457 trace_info_return() =
9458 undefined |
9459 {flags, [trace_info_flag()]} |
9460 {tracer, pid() | port() | []} |
9461 {tracer, module(), term()} |
9462 trace_info_item_result() |
9463 {all, [trace_info_item_result()] | false | undefined}
9464 trace_info_item_result() =
9465 {traced, global | local | false | undefined} |
9466 {match_spec, trace_match_spec() | false | undefined} |
9467 {meta, pid() | port() | false | undefined | []} |
9468 {meta, module(), term()} |
9469 {meta_match_spec, trace_match_spec() | false | undefined} |
9470 {call_count, integer() >= 0 | boolean() | undefined} |
9471 {call_time,
9472 [{pid(),
9473 integer() >= 0,
9474 integer() >= 0,
9475 integer() >= 0}] |
9476 boolean() |
9477 undefined}
9478 trace_info_flag() =
9479 send |
9480 'receive' |
9481 set_on_spawn |
9482 call |
9483 return_to |
9484 procs |
9485 set_on_first_spawn |
9486 set_on_link |
9487 running |
9488 garbage_collection |
9489 timestamp |
9490 monotonic_timestamp |
9491 strict_monotonic_timestamp |
9492 arity
9493 trace_match_spec() =
9494 [{[term()] | '_' | match_variable(), [term()], [term()]}]
9495 match_variable() = atom()
9496 Approximation of '$1' | '$2' | '$3' | ...
9497 Returns trace information about a port, process, function, or
9499 event.
9500 To get information about a port or process, PidPortFuncEvent is
9502 to be a process identifier (pid), port identifier, or one of the
9503 atoms new, new_processes, or new_ports. The atom new or new_pro‐
9504 cesses means that the default trace state for processes to be
9505 created is returned. The atom new_ports means that the default
9506 trace state for ports to be created is returned.
9507 Valid Items for ports and processes:
9509 flags:
9511 Returns a list of atoms indicating what kind of traces is
9512 enabled for the process. The list is empty if no traces are
9513 enabled, and one or more of the followings atoms if traces
9514 are enabled: send, 'receive', set_on_spawn, call, return_to,
9515 procs, ports, set_on_first_spawn, set_on_link, running, run‐
9516 ning_procs, running_ports, silent, exiting, monotonic_time‐
9517 stamp, strict_monotonic_timestamp, garbage_collection, time‐
9518 stamp, and arity. The order is arbitrary.
9519 tracer:
9521 Returns the identifier for process, port, or a tuple con‐
9522 taining the tracer module and tracer state tracing this
9523 process. If this process is not traced, the return value is
9524 [].
9525 To get information about a function, PidPortFuncEvent is to be
9527 the three-element tuple {Module, Function, Arity} or the atom
9528 on_load. No wildcards are allowed. Returns undefined if the
9529 function does not exist, or false if the function is not traced.
9530 If PidPortFuncEvent is on_load, the information returned refers
9531 to the default value for code that will be loaded.
9532 Valid Items for functions:
9534 traced:
9536 Returns global if this function is traced on global function
9537 calls, local if this function is traced on local function
9538 calls (that is, local and global function calls), and false
9539 if local or global function calls are not traced.
9540 match_spec:
9542 Returns the match specification for this function, if it has
9543 one. If the function is locally or globally traced but has
9544 no match specification defined, the returned value is [].
9545 meta:
9547 Returns the meta-trace tracer process, port, or trace module
9548 for this function, if it has one. If the function is not
9549 meta-traced, the returned value is false. If the function is
9550 meta-traced but has once detected that the tracer process is
9551 invalid, the returned value is [].
9552 meta_match_spec:
9554 Returns the meta-trace match specification for this func‐
9555 tion, if it has one. If the function is meta-traced but has
9556 no match specification defined, the returned value is [].
9557 call_count:
9559 Returns the call count value for this function or true for
9560 the pseudo function on_load if call count tracing is active.
9561 Otherwise false is returned.
9562 See also erlang:trace_pattern/3.
9564 call_time:
9566 Returns the call time values for this function or true for
9567 the pseudo function on_load if call time tracing is active.
9568 Otherwise false is returned. The call time values returned,
9569 [{Pid, Count, S, Us}], is a list of each process that exe‐
9570 cuted the function and its specific counters.
9571 See also erlang:trace_pattern/3.
9573 all:
9575 Returns a list containing the {Item, Value} tuples for all
9576 other items, or returns false if no tracing is active for
9577 this function.
9578 To get information about an event, PidPortFuncEvent is to be one
9580 of the atoms send or 'receive'.
9581 One valid Item for events exists:
9583 match_spec:
9585 Returns the match specification for this event, if it has
9586 one, or true if no match specification has been set.
9587 The return value is {Item, Value}, where Value is the requested
9589 information as described earlier. If a pid for a dead process
9590 was specified, or the name of a non-existing function, Value is
9591 undefined.
9592 erlang:trace_pattern(MFA, MatchSpec) -> integer() >= 0
9594 Types:
9596 MFA = trace_pattern_mfa() | send | 'receive'
9598 MatchSpec =
9599 (MatchSpecList :: trace_match_spec()) |
9600 boolean() |
9601 restart |
9602 pause
9603 trace_pattern_mfa() = {atom(), atom(), arity() | '_'} | on_load
9604 trace_match_spec() =
9605 [{[term()] | '_' | match_variable(), [term()], [term()]}]
9606 match_variable() = atom()
9607 Approximation of '$1' | '$2' | '$3' | ...
9608 The same as erlang:trace_pattern(Event, MatchSpec, []), retained
9610 for backward compatibility.
9611 erlang:trace_pattern(MFA :: send, MatchSpec, FlagList :: []) ->
9613 integer() >= 0
9614 Types:
9616 MatchSpec = (MatchSpecList :: trace_match_spec()) | boolean()
9618 trace_match_spec() =
9619 [{[term()] | '_' | match_variable(), [term()], [term()]}]
9620 match_variable() = atom()
9621 Approximation of '$1' | '$2' | '$3' | ...
9622 Sets trace pattern for message sending. Must be combined with
9624 erlang:trace/3 to set the send trace flag for one or more pro‐
9625 cesses. By default all messages sent from send traced processes
9626 are traced. To limit traced send events based on the message
9627 content, the sender and/or the receiver, use erlang:trace_pat‐
9628 tern/3.
9629 Argument MatchSpec can take the following forms:
9631 MatchSpecList:
9633 A list of match specifications. The matching is done on the
9634 list [Receiver, Msg]. Receiver is the process or port iden‐
9635 tity of the receiver and Msg is the message term. The pid of
9636 the sending process can be accessed with the guard function
9637 self/0. An empty list is the same as true. For more informa‐
9638 tion, see section Match Specifications in Erlang in the
9639 User's Guide.
9640 true:
9642 Enables tracing for all sent messages (from send traced pro‐
9643 cesses). Any match specification is removed. This is the
9644 default.
9645 false:
9647 Disables tracing for all sent messages. Any match specifica‐
9648 tion is removed.
9649 Argument FlagList must be [] for send tracing.
9651 The return value is always 1.
9653 Examples:
9655 Only trace messages to a specific process Pid:
9657 > erlang:trace_pattern(send, [{[Pid, '_'],[],[]}], []).
9659 1
9660 Only trace messages matching {reply, _}:
9662 > erlang:trace_pattern(send, [{['_', {reply,'_'}],[],[]}], []).
9664 1
9665 Only trace messages sent to the sender itself:
9667 > erlang:trace_pattern(send, [{['$1', '_'],[{'=:=','$1',{self}}],[]}], []).
9669 1
9670 Only trace messages sent to other nodes:
9672 > erlang:trace_pattern(send, [{['$1', '_'],[{'=/=',{node,'$1'},{node}}],[]}], []).
9674 1
9675 Note:
9677 A match specification for send trace can use all guard and body
9678 functions except caller.
9679 erlang:trace_pattern(MFA :: 'receive', MatchSpec, FlagList :: []) ->
9682 integer() >= 0
9683 Types:
9685 MatchSpec = (MatchSpecList :: trace_match_spec()) | boolean()
9687 trace_match_spec() =
9688 [{[term()] | '_' | match_variable(), [term()], [term()]}]
9689 match_variable() = atom()
9690 Approximation of '$1' | '$2' | '$3' | ...
9691 Sets trace pattern for message receiving. Must be combined with
9693 erlang:trace/3 to set the 'receive' trace flag for one or more
9694 processes. By default all messages received by 'receive' traced
9695 processes are traced. To limit traced receive events based on
9696 the message content, the sender and/or the receiver, use
9697 erlang:trace_pattern/3.
9698 Argument MatchSpec can take the following forms:
9700 MatchSpecList:
9702 A list of match specifications. The matching is done on the
9703 list [Node, Sender, Msg]. Node is the node name of the
9704 sender. Sender is the process or port identity of the
9705 sender, or the atom undefined if the sender is not known
9706 (which can be the case for remote senders). Msg is the mes‐
9707 sage term. The pid of the receiving process can be accessed
9708 with the guard function self/0. An empty list is the same as
9709 true. For more information, see section Match Specifica‐
9710 tions in Erlang in the User's Guide.
9711 true:
9713 Enables tracing for all received messages (to 'receive'
9714 traced processes). Any match specification is removed. This
9715 is the default.
9716 false:
9718 Disables tracing for all received messages. Any match speci‐
9719 fication is removed.
9720 Argument FlagList must be [] for receive tracing.
9722 The return value is always 1.
9724 Examples:
9726 Only trace messages from a specific process Pid:
9728 > erlang:trace_pattern('receive', [{['_',Pid, '_'],[],[]}], []).
9730 1
9731 Only trace messages matching {reply, _}:
9733 > erlang:trace_pattern('receive', [{['_','_', {reply,'_'}],[],[]}], []).
9735 1
9736 Only trace messages from other nodes:
9738 > erlang:trace_pattern('receive', [{['$1', '_', '_'],[{'=/=','$1',{node}}],[]}], []).
9740 1
9741 Note:
9743 A match specification for 'receive' trace can use all guard and
9744 body functions except caller, is_seq_trace, get_seq_token,
9745 set_seq_token, enable_trace, disable_trace, trace, silent, and
9746 process_dump.
9747 erlang:trace_pattern(MFA, MatchSpec, FlagList) ->
9750 integer() >= 0
9751 Types:
9753 MFA = trace_pattern_mfa()
9755 MatchSpec =
9756 (MatchSpecList :: trace_match_spec()) |
9757 boolean() |
9758 restart |
9759 pause
9760 FlagList = [trace_pattern_flag()]
9761 trace_pattern_mfa() = {atom(), atom(), arity() | '_'} | on_load
9762 trace_match_spec() =
9763 [{[term()] | '_' | match_variable(), [term()], [term()]}]
9764 trace_pattern_flag() =
9765 global |
9766 local |
9767 meta |
9768 {meta, Pid :: pid()} |
9769 {meta, TracerModule :: module(), TracerState :: term()} |
9770 call_count |
9771 call_time
9772 match_variable() = atom()
9773 Approximation of '$1' | '$2' | '$3' | ...
9774 Enables or disables call tracing for one or more functions. Must
9776 be combined with erlang:trace/3 to set the call trace flag for
9777 one or more processes.
9778 Conceptually, call tracing works as follows. Inside the Erlang
9780 virtual machine, a set of processes and a set of functions are
9781 to be traced. If a traced process calls a traced function, the
9782 trace action is taken. Otherwise, nothing happens.
9783 To add or remove one or more processes to the set of traced pro‐
9785 cesses, use erlang:trace/3.
9786 To add or remove functions to the set of traced functions, use
9788 erlang:trace_pattern/3.
9789 The BIF erlang:trace_pattern/3 can also add match specifications
9791 to a function. A match specification comprises a pattern that
9792 the function arguments must match, a guard expression that must
9793 evaluate to true, and an action to be performed. The default
9794 action is to send a trace message. If the pattern does not match
9795 or the guard fails, the action is not executed.
9796 Argument MFA is to be a tuple, such as {Module, Function,
9798 Arity}, or the atom on_load (described below). It can be the
9799 module, function, and arity for a function (or a BIF in any mod‐
9800 ule). The atom '_' can be used as a wildcard in any of the fol‐
9801 lowing ways:
9802 {Module,Function,'_'}:
9804 All functions of any arity named Function in module Module.
9805 {Module,'_','_'}:
9807 All functions in module Module.
9808 {'_','_','_'}:
9810 All functions in all loaded modules.
9811 Other combinations, such as {Module,'_',Arity}, are not allowed.
9813 Local functions match wildcards only if option local is in
9814 FlagList.
9815 If argument MFA is the atom on_load, the match specification and
9817 flag list are used on all modules that are newly loaded.
9818 Argument MatchSpec can take the following forms:
9820 false:
9822 Disables tracing for the matching functions. Any match spec‐
9823 ification is removed.
9824 true:
9826 Enables tracing for the matching functions. Any match speci‐
9827 fication is removed.
9828 MatchSpecList:
9830 A list of match specifications. An empty list is equivalent
9831 to true. For a description of match specifications, see sec‐
9832 tion Match Specifications in Erlang in the User's Guide.
9833 restart:
9835 For the FlagList options call_count and call_time: restarts
9836 the existing counters. The behavior is undefined for other
9837 FlagList options.
9838 pause:
9840 For the FlagList options call_count and call_time: pauses
9841 the existing counters. The behavior is undefined for other
9842 FlagList options.
9843 Parameter FlagList is a list of options. The following are the
9845 valid options:
9846 global:
9848 Turns on or off call tracing for global function calls (that
9849 is, calls specifying the module explicitly). Only exported
9850 functions match and only global calls generate trace mes‐
9851 sages. This is the default.
9852 local:
9854 Turns on or off call tracing for all types of function
9855 calls. Trace messages are sent whenever any of the specified
9856 functions are called, regardless of how they are called. If
9857 flag return_to is set for the process, a return_to message
9858 is also sent when this function returns to its caller.
9859 meta | {meta, Pid} | {meta, TracerModule, TracerState}:
9861 Turns on or off meta-tracing for all types of function
9862 calls. Trace messages are sent to the tracer whenever any of
9863 the specified functions are called. If no tracer is speci‐
9864 fied, self() is used as a default tracer process.
9865 Meta-tracing traces all processes and does not care about
9867 the process trace flags set by erlang:trace/3, the trace
9868 flags are instead fixed to [call, timestamp].
9869 The match specification function {return_trace} works with
9871 meta-trace and sends its trace message to the same tracer.
9872 call_count:
9874 Starts (MatchSpec == true) or stops (MatchSpec == false)
9875 call count tracing for all types of function calls. For
9876 every function, a counter is incremented when the function
9877 is called, in any process. No process trace flags need to be
9878 activated.
9879 If call count tracing is started while already running, the
9881 count is restarted from zero. To pause running counters, use
9882 MatchSpec == pause. Paused and running counters can be
9883 restarted from zero with MatchSpec == restart.
9884 To read the counter value, use erlang:trace_info/2.
9886 call_time:
9888 Starts (MatchSpec == true) or stops (MatchSpec == false)
9889 call time tracing for all types of function calls. For every
9890 function, a counter is incremented when the function is
9891 called. Time spent in the function is accumulated in two
9892 other counters, seconds and microseconds. The counters are
9893 stored for each call traced process.
9894 If call time tracing is started while already running, the
9896 count and time restart from zero. To pause running counters,
9897 use MatchSpec == pause. Paused and running counters can be
9898 restarted from zero with MatchSpec == restart.
9899 To read the counter value, use erlang:trace_info/2.
9901 The options global and local are mutually exclusive, and global
9903 is the default (if no options are specified). The options
9904 call_count and meta perform a kind of local tracing, and cannot
9905 be combined with global. A function can be globally or locally
9906 traced. If global tracing is specified for a set of functions,
9907 then local, meta, call time, and call count tracing for the
9908 matching set of local functions is disabled, and conversely.
9909 When disabling trace, the option must match the type of trace
9911 set on the function. That is, local tracing must be disabled
9912 with option local and global tracing with option global (or no
9913 option), and so on.
9914 Part of a match specification list cannot be changed directly.
9916 If a function has a match specification, it can be replaced with
9917 a new one. To change an existing match specification, use the
9918 BIF erlang:trace_info/2 to retrieve the existing match specifi‐
9919 cation.
9920 Returns the number of functions matching argument MFA. This is
9922 zero if none matched.
9923 trunc(Number) -> integer()
9925 Types:
9927 Number = number()
9929 Returns an integer by truncating Number, for example:
9931 > trunc(5.5).
9933 5
9934 Allowed in guard tests.
9936 tuple_size(Tuple) -> integer() >= 0
9938 Types:
9940 Tuple = tuple()
9942 Returns an integer that is the number of elements in Tuple, for
9944 example:
9945 > tuple_size({morni, mulle, bwange}).
9947 3
9948 Allowed in guard tests.
9950 tuple_to_list(Tuple) -> [term()]
9952 Types:
9954 Tuple = tuple()
9956 Returns a list corresponding to Tuple. Tuple can contain any
9958 Erlang terms. Example:
9959 > tuple_to_list({share, {'Ericsson_B', 163}}).
9961 [share,{'Ericsson_B',163}]
9962 erlang:unique_integer() -> integer()
9964 Generates and returns an integer unique on current runtime sys‐
9966 tem instance. The same as calling erlang:unique_integer([]).
9967 erlang:unique_integer(ModifierList) -> integer()
9969 Types:
9971 ModifierList = [Modifier]
9973 Modifier = positive | monotonic
9974 Generates and returns an integer unique on current runtime sys‐
9976 tem instance. The integer is unique in the sense that this BIF,
9977 using the same set of modifiers, does not return the same inte‐
9978 ger more than once on the current runtime system instance. Each
9979 integer value can of course be constructed by other means.
9980 By default, when [] is passed as ModifierList, both negative and
9982 positive integers can be returned. This to use the range of
9983 integers that do not need heap memory allocation as much as pos‐
9984 sible. By default the returned integers are also only guaranteed
9985 to be unique, that is, any returned integer can be smaller or
9986 larger than previously returned integers.
9987 Modifiers:
9989 positive:
9991 Returns only positive integers.
9992 Notice that by passing the positive modifier you will get
9994 heap allocated integers (bignums) quicker.
9995 monotonic:
9997 Returns strictly monotonically increasing integers corre‐
9998 sponding to creation time. That is, the integer returned is
9999 always larger than previously returned integers on the cur‐
10000 rent runtime system instance.
10001 These values can be used to determine order between events
10003 on the runtime system instance. That is, if both X =
10004 erlang:unique_integer([monotonic]) and Y =
10005 erlang:unique_integer([monotonic]) are executed by different
10006 processes (or the same process) on the same runtime system
10007 instance and X < Y, we know that X was created before Y.
10008 Warning:
10010 Strictly monotonically increasing values are inherently quite
10011 expensive to generate and scales poorly. This is because the
10012 values need to be synchronized between CPU cores. That is, do
10013 not pass the monotonic modifier unless you really need
10014 strictly monotonically increasing values.
10015 All valid Modifiers can be combined. Repeated (valid) Modifiers
10018 in the ModifierList are ignored.
10019 Note:
10021 The set of integers returned by erlang:unique_integer/1 using
10022 different sets of Modifiers will overlap. For example, by call‐
10023 ing unique_integer([monotonic]), and unique_integer([positive,
10024 monotonic]) repeatedly, you will eventually see some integers
10025 that are returned by both calls.
10026 Failures:
10029 badarg:
10031 if ModifierList is not a proper list.
10032 badarg:
10034 if Modifier is not a valid modifier.
10035 erlang:universaltime() -> DateTime
10037 Types:
10039 DateTime = calendar:datetime()
10041 Returns the current date and time according to Universal Time
10043 Coordinated (UTC) in the form {{Year, Month, Day}, {Hour,
10044 Minute, Second}} if supported by the underlying OS. Otherwise
10045 erlang:universaltime() is equivalent to erlang:localtime().
10046 Example:
10047 > erlang:universaltime().
10049 {{1996,11,6},{14,18,43}}
10050 erlang:universaltime_to_localtime(Universaltime) -> Localtime
10052 Types:
10054 Localtime = Universaltime = calendar:datetime()
10056 Converts Universal Time Coordinated (UTC) date and time to local
10058 date and time in the form {{Year, Month, Day}, {Hour, Minute,
10059 Second}} if supported by the underlying OS. Otherwise no conver‐
10060 sion is done, and Universaltime is returned. Example:
10061 > erlang:universaltime_to_localtime({{1996,11,6},{14,18,43}}).
10063 {{1996,11,7},{15,18,43}}
10064 Failure: badarg if Universaltime denotes an invalid date and
10066 time.
10067 unlink(Id) -> true
10069 Types:
10071 Id = pid() | port()
10073 Removes the link, if there is one, between the calling process
10075 and the process or port referred to by Id.
10076 Returns true and does not fail, even if there is no link to Id,
10078 or if Id does not exist.
10079 Once unlink(Id) has returned, it is guaranteed that the link
10081 between the caller and the entity referred to by Id has no
10082 effect on the caller in the future (unless the link is setup
10083 again). If the caller is trapping exits, an {'EXIT', Id, _} mes‐
10084 sage from the link can have been placed in the caller's message
10085 queue before the call.
10086 Notice that the {'EXIT', Id, _} message can be the result of the
10088 link, but can also be the result of Id calling exit/2. There‐
10089 fore, it can be appropriate to clean up the message queue when
10090 trapping exits after the call to unlink(Id), as follows:
10091 unlink(Id),
10093 receive
10094 {'EXIT', Id, _} ->
10095 true
10096 after 0 ->
10097 true
10098 end
10099 Note:
10101 Before Erlang/OTP R11B (ERTS 5.5) unlink/1 behaved completely
10102 asynchronously, that is, the link was active until the "unlink
10103 signal" reached the linked entity. This had an undesirable
10104 effect, as you could never know when you were guaranteed not to
10105 be effected by the link.
10106 The current behavior can be viewed as two combined operations:
10108 asynchronously send an "unlink signal" to the linked entity and
10109 ignore any future results of the link.
10110 unregister(RegName) -> true
10113 Types:
10115 RegName = atom()
10117 Removes the registered name RegName associated with a process
10119 identifier or a port identifier, for example:
10120 > unregister(db).
10122 true
10123 Users are advised not to unregister system processes.
10125 Failure: badarg if RegName is not a registered name.
10127 whereis(RegName) -> pid() | port() | undefined
10129 Types:
10131 RegName = atom()
10133 Returns the process identifier or port identifier with the reg‐
10135 istered name RegName. Returns undefined if the name is not reg‐
10136 istered. Example:
10137 > whereis(db).
10139 <0.43.0>
10140 erlang:yield() -> true
10142 Voluntarily lets other processes (if any) get a chance to exe‐
10144 cute. Using this function is similar to receive after 1 -> ok
10145 end, except that yield() is faster.
10146 Warning:
10148 There is seldom or never any need to use this BIF, especially in
10149 the SMP emulator, as other processes have a chance to run in
10150 another scheduler thread anyway. Using this BIF without a thor‐
10151 ough grasp of how the scheduler works can cause performance
10152 degradation.
10153Ericsson AB erts 9.3.3.10 erlang(3)