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() = binary()
27 A binary data object, structured according to the Erlang exter‐
29 nal term format.
30 iovec() = [binary()]
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 | millisecond | microsecond | nanosecond | native |
50 perf_counter |
51 deprecated_time_unit()
52 Supported time unit representations:
54 PartsPerSecond :: integer() >= 1:
56 Time unit expressed in parts per second. That is, the time
57 unit equals 1/PartsPerSecond second.
58 second:
60 Symbolic representation of the time unit represented by the
61 integer 1.
62 millisecond:
64 Symbolic representation of the time unit represented by the
65 integer 1000.
66 microsecond:
68 Symbolic representation of the time unit represented by the
69 integer 1000000.
70 nanosecond:
72 Symbolic representation of the time unit represented by the
73 integer 1000000000.
74 native:
76 Symbolic representation of the native time unit used by the
77 Erlang runtime system.
78 The native time unit is determined at runtime system start,
80 and remains the same until the runtime system terminates. If
81 a runtime system is stopped and then started again (even on
82 the same machine), the native time unit of the new runtime
83 system instance can differ from the native time unit of the
84 old runtime system instance.
85 One can get an approximation of the native time unit by
87 calling erlang:convert_time_unit(1, second, native). The
88 result equals the number of whole native time units per sec‐
89 ond. If the number of native time units per second does not
90 add up to a whole number, the result is rounded downwards.
91 Note:
93 The value of the native time unit gives you more or less no
94 information about the quality of time values. It sets a limit
95 for the resolution and for the precision of time values, but
96 it gives no information about the accuracy of time values.
97 The resolution of the native time unit and the resolution of
98 time values can differ significantly.
99 perf_counter:
102 Symbolic representation of the performance counter time unit
103 used by the Erlang runtime system.
104 The perf_counter time unit behaves much in the same way as
106 the native time unit. That is, it can differ between runtime
107 restarts. To get values of this type, call
108 os:perf_counter/0.
109 deprecated_time_unit():
111 Deprecated symbolic representations kept for backwards-com‐
112 patibility.
113 The time_unit/0 type can be extended. To convert time values
115 between time units, use erlang:convert_time_unit/3.
116 deprecated_time_unit() =
118 seconds | milli_seconds | micro_seconds | nano_seconds
119 The time_unit() type also consist of the following deprecated
121 symbolic time units:
122 seconds:
124 Same as second.
125 milli_seconds:
127 Same as millisecond.
128 micro_seconds:
130 Same as microsecond.
131 nano_seconds:
133 Same as nanosecond.
134 dist_handle()
136 An opaque handle identifing a distribution channel.
138 nif_resource()
140 An opaque handle identifing a NIF resource object .
142
144 abs(Float) -> float()
145 abs(Int) -> integer() >= 0
147 Types:
149 Int = integer()
151 Returns an integer or float that is the arithmetical absolute
153 value of Float or Int, for example:
154 > abs(-3.33).
156 3.33
157 > abs(-3).
158 3
159 Allowed in guard tests.
161 erlang:adler32(Data) -> integer() >= 0
163 Types:
165 Data = iodata()
167 Computes and returns the adler32 checksum for Data.
169 erlang:adler32(OldAdler, Data) -> integer() >= 0
171 Types:
173 OldAdler = integer() >= 0
175 Data = iodata()
176 Continues computing the adler32 checksum by combining the previ‐
178 ous checksum, OldAdler, with the checksum of Data.
179 The following code:
181 X = erlang:adler32(Data1),
183 Y = erlang:adler32(X,Data2).
184 assigns the same value to Y as this:
186 Y = erlang:adler32([Data1,Data2]).
188 erlang:adler32_combine(FirstAdler, SecondAdler, SecondSize) ->
190 integer() >= 0
191 Types:
193 FirstAdler = SecondAdler = SecondSize = integer() >= 0
195 Combines two previously computed adler32 checksums. This compu‐
197 tation requires the size of the data object for the second
198 checksum to be known.
199 The following code:
201 Y = erlang:adler32(Data1),
203 Z = erlang:adler32(Y,Data2).
204 assigns the same value to Z as this:
206 X = erlang:adler32(Data1),
208 Y = erlang:adler32(Data2),
209 Z = erlang:adler32_combine(X,Y,iolist_size(Data2)).
210 erlang:append_element(Tuple1, Term) -> Tuple2
212 Types:
214 Tuple1 = Tuple2 = tuple()
216 Term = term()
217 Returns a new tuple that has one element more than Tuple1, and
219 contains the elements in Tuple1 followed by Term as the last
220 element. Semantically equivalent to
221 list_to_tuple(tuple_to_list(Tuple1) ++ [Term]), but much faster.
222 Example:
223 > erlang:append_element({one, two}, three).
225 {one,two,three}
226 apply(Fun, Args) -> term()
228 Types:
230 Fun = function()
232 Args = [term()]
233 Calls a fun, passing the elements in Args as arguments.
235 If the number of elements in the arguments are known at compile
237 time, the call is better written as Fun(Arg1, Arg2, ... ArgN).
238 Warning:
240 Earlier, Fun could also be specified as {Module, Function},
241 equivalent to apply(Module, Function, Args). This use is depre‐
242 cated and will stop working in a future release.
243 apply(Module, Function, Args) -> term()
246 Types:
248 Module = module()
250 Function = atom()
251 Args = [term()]
252 Returns the result of applying Function in Module to Args. The
254 applied function must be exported from Module. The arity of the
255 function is the length of Args. Example:
256 > apply(lists, reverse, [[a, b, c]]).
258 [c,b,a]
259 > apply(erlang, atom_to_list, ['Erlang']).
260 "Erlang"
261 If the number of arguments are known at compile time, the call
263 is better written as Module:Function(Arg1, Arg2, ..., ArgN).
264 Failure: error_handler:undefined_function/3 is called if the
266 applied function is not exported. The error handler can be rede‐
267 fined (see process_flag/2). If error_handler is undefined, or if
268 the user has redefined the default error_handler so the replace‐
269 ment module is undefined, an error with reason undef is gener‐
270 ated.
271 atom_to_binary(Atom, Encoding) -> binary()
273 Types:
275 Atom = atom()
277 Encoding = latin1 | unicode | utf8
278 Returns a binary corresponding to the text representation of
280 Atom. If Encoding is latin1, one byte exists for each character
281 in the text representation. If Encoding is utf8 or unicode, the
282 characters are encoded using UTF-8 where characters may require
283 multiple bytes.
284 Note:
286 As from Erlang/OTP 20, atoms can contain any Unicode character
287 and atom_to_binary(Atom, latin1) may fail if the text represen‐
288 tation for Atom contains a Unicode character > 255.
289 Example:
292 > atom_to_binary('Erlang', latin1).
294 <<"Erlang">>
295 atom_to_list(Atom) -> string()
297 Types:
299 Atom = atom()
301 Returns a string corresponding to the text representation of
303 Atom, for example:
304 > atom_to_list('Erlang').
306 "Erlang"
307 binary_part(Subject, PosLen) -> binary()
309 Types:
311 Subject = binary()
313 PosLen = {Start :: integer() >= 0, Length :: integer()}
314 Extracts the part of the binary described by PosLen.
316 Negative length can be used to extract bytes at the end of a
318 binary, for example:
319 1> Bin = <<1,2,3,4,5,6,7,8,9,10>>.
321 2> binary_part(Bin,{byte_size(Bin), -5}).
322 <<6,7,8,9,10>>
323 Failure: badarg if PosLen in any way references outside the
325 binary.
326 Start is zero-based, that is:
328 1> Bin = <<1,2,3>>
330 2> binary_part(Bin,{0,2}).
331 <<1,2>>
332 For details about the PosLen semantics, see binary(3).
334 Allowed in guard tests.
336 binary_part(Subject, Start, Length) -> binary()
338 Types:
340 Subject = binary()
342 Start = integer() >= 0
343 Length = integer()
344 The same as binary_part(Subject, {Start, Length}).
346 Allowed in guard tests.
348 binary_to_atom(Binary, Encoding) -> atom()
350 Types:
352 Binary = binary()
354 Encoding = latin1 | unicode | utf8
355 Returns the atom whose text representation is Binary. If Encod‐
357 ing is latin1, no translation of bytes in the binary is done. If
358 Encoding is utf8 or unicode, the binary must contain valid UTF-8
359 sequences.
360 Note:
362 As from Erlang/OTP 20, binary_to_atom(Binary, utf8) is capable
363 of encoding any Unicode character. Earlier versions would fail
364 if the binary contained Unicode characters > 255. For more
365 information about Unicode support in atoms, see the note on
366 UTF-8 encoded atoms in section "External Term Format" in the
367 User's Guide.
368 Examples:
371 > binary_to_atom(<<"Erlang">>, latin1).
373 > binary_to_atom(<<1024/utf8>>, utf8).
374 binary_to_existing_atom(Binary, Encoding) -> atom()
376 Types:
378 Binary = binary()
380 Encoding = latin1 | unicode | utf8
381 As binary_to_atom/2, but the atom must exist.
383 Failure: badarg if the atom does not exist.
385 Note:
387 Note that the compiler may optimize away atoms. For example, the
388 compiler will rewrite atom_to_list(some_atom) to "some_atom". If
389 that expression is the only mention of the atom some_atom in the
390 containing module, the atom will not be created when the module
391 is loaded, and a subsequent call to binary_to_exist‐
392 ing_atom(<<"some_atom">>, utf8) will fail.
393 binary_to_float(Binary) -> float()
396 Types:
398 Binary = binary()
400 Returns the float whose text representation is Binary, for exam‐
402 ple:
403 > binary_to_float(<<"2.2017764e+0">>).
405 2.2017764
406 Failure: badarg if Binary contains a bad representation of a
408 float.
409 binary_to_integer(Binary) -> integer()
411 Types:
413 Binary = binary()
415 Returns an integer whose text representation is Binary, for
417 example:
418 > binary_to_integer(<<"123">>).
420 123
421 Failure: badarg if Binary contains a bad representation of an
423 integer.
424 binary_to_integer(Binary, Base) -> integer()
426 Types:
428 Binary = binary()
430 Base = 2..36
431 Returns an integer whose text representation in base Base is
433 Binary, for example:
434 > binary_to_integer(<<"3FF">>, 16).
436 1023
437 Failure: badarg if Binary contains a bad representation of an
439 integer.
440 binary_to_list(Binary) -> [byte()]
442 Types:
444 Binary = binary()
446 Returns a list of integers corresponding to the bytes of Binary.
448 binary_to_list(Binary, Start, Stop) -> [byte()]
450 Types:
452 Binary = binary()
454 Start = Stop = integer() >= 1
455 1..byte_size(Binary)
456 As binary_to_list/1, but returns a list of integers correspond‐
458 ing to the bytes from position Start to position Stop in Binary.
459 The positions in the binary are numbered starting from 1.
460 Note:
462 The one-based indexing for binaries used by this function is
463 deprecated. New code is to use binary:bin_to_list/3 in STDLIB
464 instead. All functions in module binary consistently use zero-
465 based indexing.
466 binary_to_term(Binary) -> term()
469 Types:
471 Binary = ext_binary()
473 Returns an Erlang term that is the result of decoding binary
475 object Binary, which must be encoded according to the Erlang
476 external term format.
477 > Bin = term_to_binary(hello).
479 <<131,100,0,5,104,101,108,108,111>>
480 > hello = binary_to_term(Bin).
481 hello
482 Warning:
485 When decoding binaries from untrusted sources, consider using
486 binary_to_term/2 to prevent Denial of Service attacks.
487 See also term_to_binary/1 and binary_to_term/2.
490 binary_to_term(Binary, Opts) -> term() | {term(), Used}
492 Types:
494 Binary = ext_binary()
496 Opt = safe | used
497 Opts = [Opt]
498 Used = integer() >= 1
499 As binary_to_term/1, but takes these options:
501 safe:
503 Use this option when receiving binaries from an untrusted
504 source.
505 When enabled, it prevents decoding data that can be used to
507 attack the Erlang system. In the event of receiving unsafe
508 data, decoding fails with a badarg error.
509 This prevents creation of new atoms directly, creation of
511 new atoms indirectly (as they are embedded in certain struc‐
512 tures, such as process identifiers, refs, and funs), and
513 creation of new external function references. None of those
514 resources are garbage collected, so unchecked creation of
515 them can exhaust available memory.
516 > binary_to_term(<<131,100,0,5,"hello">>, [safe]).
518 ** exception error: bad argument
519 > hello.
520 hello
521 > binary_to_term(<<131,100,0,5,"hello">>, [safe]).
522 hello
523 used:
526 Changes the return value to {Term, Used} where Used is the
527 number of bytes actually read from Binary.
528 > Input = <<131,100,0,5,"hello","world">>.
530 <<131,100,0,5,104,101,108,108,111,119,111,114,108,100>>
531 > {Term, Used} = binary_to_term(Input, [used]).
532 {hello, 9}
533 > split_binary(Input, Used).
534 {<<131,100,0,5,104,101,108,108,111>>, <<"world">>}
535 Failure: badarg if safe is specified and unsafe data is decoded.
538 See also term_to_binary/1, binary_to_term/1, and list_to_exist‐
540 ing_atom/1.
541 bit_size(Bitstring) -> integer() >= 0
543 Types:
545 Bitstring = bitstring()
547 Returns an integer that is the size in bits of Bitstring, for
549 example:
550 > bit_size(<<433:16,3:3>>).
552 19
553 > bit_size(<<1,2,3>>).
554 24
555 Allowed in guard tests.
557 bitstring_to_list(Bitstring) -> [byte() | bitstring()]
559 Types:
561 Bitstring = bitstring()
563 Returns a list of integers corresponding to the bytes of Bit‐
565 string. If the number of bits in the binary is not divisible by
566 8, the last element of the list is a bitstring containing the
567 remaining 1-7 bits.
568 erlang:bump_reductions(Reductions) -> true
570 Types:
572 Reductions = integer() >= 1
574 This implementation-dependent function increments the reduction
576 counter for the calling process. In the Beam emulator, the
577 reduction counter is normally incremented by one for each func‐
578 tion and BIF call. A context switch is forced when the counter
579 reaches the maximum number of reductions for a process (2000
580 reductions in Erlang/OTP R12B).
581 Warning:
583 This BIF can be removed in a future version of the Beam machine
584 without prior warning. It is unlikely to be implemented in other
585 Erlang implementations.
586 byte_size(Bitstring) -> integer() >= 0
589 Types:
591 Bitstring = bitstring()
593 Returns an integer that is the number of bytes needed to contain
595 Bitstring. That is, if the number of bits in Bitstring is not
596 divisible by 8, the resulting number of bytes is rounded up.
597 Examples:
598 > byte_size(<<433:16,3:3>>).
600 3
601 > byte_size(<<1,2,3>>).
602 3
603 Allowed in guard tests.
605 erlang:cancel_timer(TimerRef) -> Result
607 Types:
609 TimerRef = reference()
611 Time = integer() >= 0
612 Result = Time | false
613 Cancels a timer. The same as calling erlang:cancel_timer(Timer‐
615 Ref, []).
616 erlang:cancel_timer(TimerRef, Options) -> Result | ok
618 Types:
620 TimerRef = reference()
622 Async = Info = boolean()
623 Option = {async, Async} | {info, Info}
624 Options = [Option]
625 Time = integer() >= 0
626 Result = Time | false
627 Cancels a timer that has been created by erlang:start_timer or
629 erlang:send_after. TimerRef identifies the timer, and was
630 returned by the BIF that created the timer.
631 Options:
633 {async, Async}:
635 Asynchronous request for cancellation. Async defaults to
636 false, which causes the cancellation to be performed syn‐
637 chronously. When Async is set to true, the cancel operation
638 is performed asynchronously. That is, cancel_timer() sends
639 an asynchronous request for cancellation to the timer ser‐
640 vice that manages the timer, and then returns ok.
641 {info, Info}:
643 Requests information about the Result of the cancellation.
644 Info defaults to true, which means the Result is given. When
645 Info is set to false, no information about the result of the
646 cancellation is given.
647 * When Async is false: if Info is true, the Result is
649 returned by erlang:cancel_timer(). otherwise ok is
650 returned.
651 * When Async is true: if Info is true, a message on the form
653 {cancel_timer, TimerRef, Result} is sent to the caller of
654 erlang:cancel_timer() when the cancellation operation has
655 been performed, otherwise no message is sent.
656 More Options may be added in the future.
658 If Result is an integer, it represents the time in milliseconds
660 left until the canceled timer would have expired.
661 If Result is false, a timer corresponding to TimerRef could not
663 be found. This can be either because the timer had expired,
664 already had been canceled, or because TimerRef never corre‐
665 sponded to a timer. Even if the timer had expired, it does not
666 tell you if the time-out message has arrived at its destination
667 yet.
668 Note:
670 The timer service that manages the timer can be co-located with
671 another scheduler than the scheduler that the calling process is
672 executing on. If so, communication with the timer service takes
673 much longer time than if it is located locally. If the calling
674 process is in critical path, and can do other things while wait‐
675 ing for the result of this operation, or is not interested in
676 the result of the operation, you want to use option {async,
677 true}. If using option {async, false}, the calling process
678 blocks until the operation has been performed.
679 See also erlang:send_after/4, erlang:start_timer/4, and
682 erlang:read_timer/2.
683 ceil(Number) -> integer()
685 Types:
687 Number = number()
689 Returns the smallest integer not less than Number. For example:
691 > ceil(5.5).
693 6
694 Allowed in guard tests.
696 check_old_code(Module) -> boolean()
698 Types:
700 Module = module()
702 Returns true if Module has old code, otherwise false.
704 See also code(3).
706 check_process_code(Pid, Module) -> CheckResult
708 Types:
710 Pid = pid()
712 Module = module()
713 CheckResult = boolean()
714 The same as check_process_code(Pid, Module, []).
716 check_process_code(Pid, Module, OptionList) -> CheckResult | async
718 Types:
720 Pid = pid()
722 Module = module()
723 RequestId = term()
724 Option = {async, RequestId} | {allow_gc, boolean()}
725 OptionList = [Option]
726 CheckResult = boolean() | aborted
727 Checks if the node local process identified by Pid executes old
729 code for Module.
730 Options:
732 {allow_gc, boolean()}:
734 Determines if garbage collection is allowed when performing
735 the operation. If {allow_gc, false} is passed, and a garbage
736 collection is needed to determine the result of the opera‐
737 tion, the operation is aborted (see information on CheckRe‐
738 sult below). The default is to allow garbage collection,
739 that is, {allow_gc, true}.
740 {async, RequestId}:
742 The function check_process_code/3 returns the value async
743 immediately after the request has been sent. When the
744 request has been processed, the process that called this
745 function is passed a message on the form
746 {check_process_code, RequestId, CheckResult}.
747 If Pid equals self(), and no async option has been passed, the
749 operation is performed at once. Otherwise a request for the
750 operation is sent to the process identified by Pid, and is han‐
751 dled when appropriate. If no async option has been passed, the
752 caller blocks until CheckResult is available and can be
753 returned.
754 CheckResult informs about the result of the request as follows:
756 true:
758 The process identified by Pid executes old code for Module.
759 That is, the current call of the process executes old code
760 for this module, or the process has references to old code
761 for this module, or the process contains funs that refer‐
762 ences old code for this module.
763 false:
765 The process identified by Pid does not execute old code for
766 Module.
767 aborted:
769 The operation was aborted, as the process needed to be
770 garbage collected to determine the operation result, and the
771 operation was requested by passing option {allow_gc, false}.
772 Note:
774 Up until ERTS version 8.*, the check process code operation
775 checks for all types of references to the old code. That is,
776 direct references (e.g. return addresses on the process stack),
777 indirect references (funs in process context), and references to
778 literals in the code.
779 As of ERTS version 9.0, the check process code operation only
781 checks for direct references to the code. Indirect references
782 via funs will be ignored. If such funs exist and are used after
783 a purge of the old code, an exception will be raised upon usage
784 (same as the case when the fun is received by the process after
785 the purge). Literals will be taken care of (copied) at a later
786 stage. This behavior can as of ERTS version 8.1 be enabled when
787 building OTP, and will automatically be enabled if dirty sched‐
788 uler support is enabled.
789 See also code(3).
792 Failures:
794 badarg:
796 If Pid is not a node local process identifier.
797 badarg:
799 If Module is not an atom.
800 badarg:
802 If OptionList is an invalid list of options.
803 erlang:convert_time_unit(Time, FromUnit, ToUnit) -> ConvertedTime
805 Types:
807 Time = ConvertedTime = integer()
809 FromUnit = ToUnit = time_unit()
810 Converts the Time value of time unit FromUnit to the correspond‐
812 ing ConvertedTime value of time unit ToUnit. The result is
813 rounded using the floor function.
814 Warning:
816 You can lose accuracy and precision when converting between time
817 units. To minimize such loss, collect all data at native time
818 unit and do the conversion on the end result.
819 erlang:crc32(Data) -> integer() >= 0
822 Types:
824 Data = iodata()
826 Computes and returns the crc32 (IEEE 802.3 style) checksum for
828 Data.
829 erlang:crc32(OldCrc, Data) -> integer() >= 0
831 Types:
833 OldCrc = integer() >= 0
835 Data = iodata()
836 Continues computing the crc32 checksum by combining the previous
838 checksum, OldCrc, with the checksum of Data.
839 The following code:
841 X = erlang:crc32(Data1),
843 Y = erlang:crc32(X,Data2).
844 assigns the same value to Y as this:
846 Y = erlang:crc32([Data1,Data2]).
848 erlang:crc32_combine(FirstCrc, SecondCrc, SecondSize) ->
850 integer() >= 0
851 Types:
853 FirstCrc = SecondCrc = SecondSize = integer() >= 0
855 Combines two previously computed crc32 checksums. This computa‐
857 tion requires the size of the data object for the second check‐
858 sum to be known.
859 The following code:
861 Y = erlang:crc32(Data1),
863 Z = erlang:crc32(Y,Data2).
864 assigns the same value to Z as this:
866 X = erlang:crc32(Data1),
868 Y = erlang:crc32(Data2),
869 Z = erlang:crc32_combine(X,Y,iolist_size(Data2)).
870 date() -> Date
872 Types:
874 Date = calendar:date()
876 Returns the current date as {Year, Month, Day}.
878 The time zone and Daylight Saving Time correction depend on the
880 underlying OS. Example:
881 > date().
883 {1995,2,19}
884 erlang:decode_packet(Type, Bin, Options) ->
886 {ok, Packet, Rest} |
887 {more, Length} |
888 {error, Reason}
889 Types:
891 Type =
893 raw | 0 | 1 | 2 | 4 | asn1 | cdr | sunrm | fcgi | tpkt |
894 line | http | http_bin | httph | httph_bin
895 Bin = binary()
896 Options = [Opt]
897 Opt =
898 {packet_size, integer() >= 0} |
899 {line_length, integer() >= 0}
900 Packet = binary() | HttpPacket
901 Rest = binary()
902 Length = integer() >= 0 | undefined
903 Reason = term()
904 HttpPacket =
905 HttpRequest | HttpResponse | HttpHeader | http_eoh |
906 HttpError
907 HttpRequest = {http_request, HttpMethod, HttpUri, HttpVer‐
908 sion}
909 HttpResponse =
910 {http_response, HttpVersion, integer(), HttpString}
911 HttpHeader =
912 {http_header,
913 integer(),
914 HttpField,
915 Reserved :: term(),
916 Value :: HttpString}
917 HttpError = {http_error, HttpString}
918 HttpMethod =
919 'OPTIONS' | 'GET' | 'HEAD' | 'POST' | 'PUT' | 'DELETE' |
920 'TRACE' | HttpString
921 HttpUri =
922 '*' |
923 {absoluteURI,
924 http | https,
925 Host :: HttpString,
926 Port :: inet:port_number() | undefined,
927 Path :: HttpString} |
928 {scheme, Scheme :: HttpString, HttpString} |
929 {abs_path, HttpString} |
930 HttpString
931 HttpVersion =
932 {Major :: integer() >= 0, Minor :: integer() >= 0}
933 HttpField =
934 'Cache-Control' | 'Connection' | 'Date' | 'Pragma' |
935 'Transfer-Encoding' | 'Upgrade' | 'Via' | 'Accept' |
936 'Accept-Charset' | 'Accept-Encoding' | 'Accept-Language'
937 |
938 'Authorization' | 'From' | 'Host' | 'If-Modified-Since' |
939 'If-Match' | 'If-None-Match' | 'If-Range' |
940 'If-Unmodified-Since' | 'Max-Forwards' |
941 'Proxy-Authorization' | 'Range' | 'Referer' | 'User-
942 Agent' |
943 'Age' | 'Location' | 'Proxy-Authenticate' | 'Public' |
944 'Retry-After' | 'Server' | 'Vary' | 'Warning' |
945 'Www-Authenticate' | 'Allow' | 'Content-Base' |
946 'Content-Encoding' | 'Content-Language' | 'Content-
947 Length' |
948 'Content-Location' | 'Content-Md5' | 'Content-Range' |
949 'Content-Type' | 'Etag' | 'Expires' | 'Last-Modified' |
950 'Accept-Ranges' | 'Set-Cookie' | 'Set-Cookie2' |
951 'X-Forwarded-For' | 'Cookie' | 'Keep-Alive' |
952 'Proxy-Connection' | HttpString
953 HttpString = string() | binary()
954 Decodes the binary Bin according to the packet protocol speci‐
956 fied by Type. Similar to the packet handling done by sockets
957 with option {packet,Type}.
958 If an entire packet is contained in Bin, it is returned together
960 with the remainder of the binary as {ok,Packet,Rest}.
961 If Bin does not contain the entire packet, {more,Length} is
963 returned. Length is either the expected total size of the
964 packet, or undefined if the expected packet size is unknown.
965 decode_packet can then be called again with more data added.
966 If the packet does not conform to the protocol format,
968 {error,Reason} is returned.
969 Types:
971 raw | 0:
973 No packet handling is done. The entire binary is returned
974 unless it is empty.
975 1 | 2 | 4:
977 Packets consist of a header specifying the number of bytes
978 in the packet, followed by that number of bytes. The length
979 of the header can be one, two, or four bytes; the order of
980 the bytes is big-endian. The header is stripped off when the
981 packet is returned.
982 line:
984 A packet is a line-terminated by a delimiter byte, default
985 is the latin-1 newline character. The delimiter byte is
986 included in the returned packet unless the line was trun‐
987 cated according to option line_length.
988 asn1 | cdr | sunrm | fcgi | tpkt:
990 The header is not stripped off.
991 The meanings of the packet types are as follows:
993 asn1 - ASN.1 BER:
995 sunrm - Sun's RPC encoding:
998 cdr - CORBA (GIOP 1.1):
1001 fcgi - Fast CGI:
1004 tpkt - TPKT format [RFC1006]:
1007 http | httph | http_bin | httph_bin:
1010 The Hypertext Transfer Protocol. The packets are returned
1011 with the format according to HttpPacket described earlier. A
1012 packet is either a request, a response, a header, or an end
1013 of header mark. Invalid lines are returned as HttpError.
1014 Recognized request methods and header fields are returned as
1016 atoms. Others are returned as strings. Strings of unrecog‐
1017 nized header fields are formatted with only capital letters
1018 first and after hyphen characters, for example, "Sec-Web‐
1019 socket-Key".
1020 The protocol type http is only to be used for the first line
1022 when an HttpRequest or an HttpResponse is expected. The fol‐
1023 lowing calls are to use httph to get HttpHeaders until
1024 http_eoh is returned, which marks the end of the headers and
1025 the beginning of any following message body.
1026 The variants http_bin and httph_bin return strings (Http‐
1028 String) as binaries instead of lists.
1029 Options:
1031 {packet_size, integer() >= 0}:
1033 Sets the maximum allowed size of the packet body. If the
1034 packet header indicates that the length of the packet is
1035 longer than the maximum allowed length, the packet is con‐
1036 sidered invalid. Defaults to 0, which means no size limit.
1037 {line_length, integer() >= 0}:
1039 For packet type line, lines longer than the indicated length
1040 are truncated.
1041 Option line_length also applies to http* packet types as an
1043 alias for option packet_size if packet_size itself is not
1044 set. This use is only intended for backward compatibility.
1045 {line_delimiter, 0 =< byte() =< 255}:
1047 For packet type line, sets the delimiting byte. Default is
1048 the latin-1 character $\n.
1049 Examples:
1051 > erlang:decode_packet(1,<<3,"abcd">>,[]).
1053 {ok,<<"abc">>,<<"d">>}
1054 > erlang:decode_packet(1,<<5,"abcd">>,[]).
1055 {more,6}
1056 erlang:delete_element(Index, Tuple1) -> Tuple2
1058 Types:
1060 Index = integer() >= 1
1062 1..tuple_size(Tuple1)
1063 Tuple1 = Tuple2 = tuple()
1064 Returns a new tuple with element at Index removed from tuple
1066 Tuple1, for example:
1067 > erlang:delete_element(2, {one, two, three}).
1069 {one,three}
1070 delete_module(Module) -> true | undefined
1072 Types:
1074 Module = module()
1076 Makes the current code for Module become old code and deletes
1078 all references for this module from the export table. Returns
1079 undefined if the module does not exist, otherwise true.
1080 Warning:
1082 This BIF is intended for the code server (see code(3)) and is
1083 not to be used elsewhere.
1084 Failure: badarg if there already is an old version of Module.
1087 demonitor(MonitorRef) -> true
1089 Types:
1091 MonitorRef = reference()
1093 If MonitorRef is a reference that the calling process obtained
1095 by calling monitor/2, this monitoring is turned off. If the mon‐
1096 itoring is already turned off, nothing happens.
1097 Once demonitor(MonitorRef) has returned, it is guaranteed that
1099 no {'DOWN', MonitorRef, _, _, _} message, because of the moni‐
1100 tor, will be placed in the caller message queue in the future.
1101 However, a {'DOWN', MonitorRef, _, _, _} message can have been
1102 placed in the caller message queue before the call. It is there‐
1103 fore usually advisable to remove such a 'DOWN' message from the
1104 message queue after monitoring has been stopped. demonitor(Moni‐
1105 torRef, [flush]) can be used instead of demonitor(MonitorRef) if
1106 this cleanup is wanted.
1107 Note:
1109 Before Erlang/OTP R11B (ERTS 5.5) demonitor/1 behaved completely
1110 asynchronously, that is, the monitor was active until the
1111 "demonitor signal" reached the monitored entity. This had one
1112 undesirable effect. You could never know when you were guaran‐
1113 teed not to receive a DOWN message because of the monitor.
1114 The current behavior can be viewed as two combined operations:
1116 asynchronously send a "demonitor signal" to the monitored entity
1117 and ignore any future results of the monitor.
1118 Failure: It is an error if MonitorRef refers to a monitoring
1121 started by another process. Not all such cases are cheap to
1122 check. If checking is cheap, the call fails with badarg, for
1123 example if MonitorRef is a remote reference.
1124 demonitor(MonitorRef, OptionList) -> boolean()
1126 Types:
1128 MonitorRef = reference()
1130 OptionList = [Option]
1131 Option = flush | info
1132 The returned value is true unless info is part of OptionList.
1134 demonitor(MonitorRef, []) is equivalent to demonitor(Monitor‐
1136 Ref).
1137 Options:
1139 flush:
1141 Removes (one) {_, MonitorRef, _, _, _} message, if there is
1142 one, from the caller message queue after monitoring has been
1143 stopped.
1144 Calling demonitor(MonitorRef, [flush]) is equivalent to the
1146 following, but more efficient:
1147 demonitor(MonitorRef),
1149 receive
1150 {_, MonitorRef, _, _, _} ->
1151 true
1152 after 0 ->
1153 true
1154 end
1155 info:
1157 The returned value is one of the following:
1158 true:
1160 The monitor was found and removed. In this case, no 'DOWN'
1161 message corresponding to this monitor has been delivered
1162 and will not be delivered.
1163 false:
1165 The monitor was not found and could not be removed. This
1166 probably because someone already has placed a 'DOWN' mes‐
1167 sage corresponding to this monitor in the caller message
1168 queue.
1169 If option info is combined with option flush, false is
1171 returned if a flush was needed, otherwise true.
1172 Note:
1174 More options can be added in a future release.
1175 Failures:
1178 badarg:
1180 If OptionList is not a list.
1181 badarg:
1183 If Option is an invalid option.
1184 badarg:
1186 The same failure as for demonitor/1.
1187 disconnect_node(Node) -> boolean() | ignored
1189 Types:
1191 Node = node()
1193 Forces the disconnection of a node. This appears to the node
1195 Node as if the local node has crashed. This BIF is mainly used
1196 in the Erlang network authentication protocols.
1197 Returns true if disconnection succeeds, otherwise false. If the
1199 local node is not alive, ignored is returned.
1200 erlang:display(Term) -> true
1202 Types:
1204 Term = term()
1206 Prints a text representation of Term on the standard output.
1208 Warning:
1210 This BIF is intended for debugging only.
1211 erlang:dist_ctrl_get_data(DHandle) -> {Size, Data} | Data | none
1214 Types:
1216 Size = integer() >= 0
1218 DHandle = dist_handle()
1219 Data = iodata()
1220 Get distribution channel data from the local node that is to be
1222 passed to the remote node. The distribution channel is identi‐
1223 fied by DHandle. If no data is available, the atom none is
1224 returned. One can request to be informed by a message when more
1225 data is available by calling erlang:dist_ctrl_get_data_notifica‐
1226 tion(DHandle).
1227 The returned value when there are data available depends on the
1229 value of the get_size option configured on the distribution
1230 channel identified by DHandle. For more information see the doc‐
1231 umentation of the get_size option for the
1232 erlang:dist_ctrl_set_opt/3 function.
1233 Note:
1235 Only the process registered as distribution controller for the
1236 distribution channel identified by DHandle is allowed to call
1237 this function.
1238 This function is used when implementing an alternative distribu‐
1241 tion carrier using processes as distribution controllers. DHan‐
1242 dle is retrived via the callback f_handshake_complete. More
1243 information can be found in the documentation of ERTS User's
1244 Guide ➜ How to implement an Alternative Carrier for the Erlang
1245 Distribution ➜ Distribution Module.
1246 erlang:dist_ctrl_get_opt(DHandle, Opt :: get_size) -> Value
1248 Types:
1250 DHandle = dist_handle()
1252 Value = boolean()
1253 Returns the value of the get_size option on the distribution
1255 channel identified by DHandle. For more information see the doc‐
1256 umentation of the get_size option for the
1257 erlang:dist_ctrl_set_opt/3 function.
1258 Note:
1260 Only the process registered as distribution controller for the
1261 distribution channel identified by DHandle is allowed to call
1262 this function.
1263 This function is used when implementing an alternative distribu‐
1266 tion carrier using processes as distribution controllers. DHan‐
1267 dle is retrived via the callback f_handshake_complete. More
1268 information can be found in the documentation of ERTS User's
1269 Guide ➜ How to implement an Alternative Carrier for the Erlang
1270 Distribution ➜ Distribution Module.
1271 erlang:dist_ctrl_get_data_notification(DHandle) -> ok
1273 Types:
1275 DHandle = dist_handle()
1277 Request notification when more data is available to fetch using
1279 erlang:dist_ctrl_get_data(DHandle) for the distribution channel
1280 identified by DHandle. When more data is present, the caller
1281 will be sent the message dist_data. Once a dist_data messages
1282 has been sent, no more dist_data messages will be sent until the
1283 dist_ctrl_get_data_notification/1 function has been called
1284 again.
1285 Note:
1287 Only the process registered as distribution controller for the
1288 distribution channel identified by DHandle is allowed to call
1289 this function.
1290 This function is used when implementing an alternative distribu‐
1293 tion carrier using processes as distribution controllers. DHan‐
1294 dle is retrived via the callback f_handshake_complete. More
1295 information can be found in the documentation of ERTS User's
1296 Guide ➜ How to implement an Alternative Carrier for the Erlang
1297 Distribution ➜ Distribution Module.
1298 erlang:dist_ctrl_input_handler(DHandle, InputHandler) -> ok
1300 Types:
1302 DHandle = dist_handle()
1304 InputHandler = pid()
1305 Register an alternate input handler process for the distribution
1307 channel identified by DHandle. Once this function has been
1308 called, InputHandler is the only process allowed to call
1309 erlang:dist_ctrl_put_data(DHandle, Data) with the DHandle iden‐
1310 tifing this distribution channel.
1311 Note:
1313 Only the process registered as distribution controller for the
1314 distribution channel identified by DHandle is allowed to call
1315 this function.
1316 This function is used when implementing an alternative distribu‐
1319 tion carrier using processes as distribution controllers. DHan‐
1320 dle is retrived via the callback f_handshake_complete. More
1321 information can be found in the documentation of ERTS User's
1322 Guide ➜ How to implement an Alternative Carrier for the Erlang
1323 Distribution ➜ Distribution Module.
1324 erlang:dist_ctrl_put_data(DHandle, Data) -> ok
1326 Types:
1328 DHandle = dist_handle()
1330 Data = iodata()
1331 Deliver distribution channel data from a remote node to the
1333 local node.
1334 Note:
1336 Only the process registered as distribution controller for the
1337 distribution channel identified by DHandle is allowed to call
1338 this function unless an alternate input handler process has been
1339 registered using erlang:dist_ctrl_input_handler(DHandle,
1340 InputHandler). If an alternate input handler has been regis‐
1341 tered, only the registered input handler process is allowed to
1342 call this function.
1343 This function is used when implementing an alternative distribu‐
1346 tion carrier using processes as distribution controllers. DHan‐
1347 dle is retrived via the callback f_handshake_complete. More
1348 information can be found in the documentation of ERTS User's
1349 Guide ➜ How to implement an Alternative Carrier for the Erlang
1350 Distribution ➜ Distribution Module.
1351 erlang:dist_ctrl_set_opt(DHandle, Opt :: get_size, Value) ->
1353 OldValue
1354 Types:
1356 DHandle = dist_handle()
1358 Value = OldValue = boolean()
1359 Sets the value of the get_size option on the distribution chan‐
1361 nel identified by DHandle. This option controls the return value
1362 of calls to erlang:dist_ctrl_get_data(DHandle) where DHandle
1363 equals DHandle used when setting this option. When the get_size
1364 option is:
1365 false:
1367 and there are distribution data available, a call to
1368 erlang:dist_ctrl_get_data(DHandle) will just return Data to
1369 pass over the channel. This is the default value of the
1370 get_size option.
1371 true:
1373 and there are distribution data available, a call to
1374 erlang:dist_ctrl_get_data(DHandle) will return Data to pass
1375 over the channel as well as the Size of Data in bytes. This
1376 is returned as a tuple on the form {Size, Data}.
1377 All options are set to default when a channel is closed.
1379 Note:
1381 Only the process registered as distribution controller for the
1382 distribution channel identified by DHandle is allowed to call
1383 this function.
1384 This function is used when implementing an alternative distribu‐
1387 tion carrier using processes as distribution controllers. DHan‐
1388 dle is retrived via the callback f_handshake_complete. More
1389 information can be found in the documentation of ERTS User's
1390 Guide ➜ How to implement an Alternative Carrier for the Erlang
1391 Distribution ➜ Distribution Module.
1392 element(N, Tuple) -> term()
1394 Types:
1396 N = integer() >= 1
1398 1..tuple_size(Tuple)
1399 Tuple = tuple()
1400 Returns the Nth element (numbering from 1) of Tuple, for exam‐
1402 ple:
1403 > element(2, {a, b, c}).
1405 b
1406 Allowed in guard tests.
1408 erase() -> [{Key, Val}]
1410 Types:
1412 Key = Val = term()
1414 Returns the process dictionary and deletes it, for example:
1416 > put(key1, {1, 2, 3}),
1418 put(key2, [a, b, c]),
1419 erase().
1420 [{key1,{1,2,3}},{key2,[a,b,c]}]
1421 erase(Key) -> Val | undefined
1423 Types:
1425 Key = Val = term()
1427 Returns the value Val associated with Key and deletes it from
1429 the process dictionary. Returns undefined if no value is associ‐
1430 ated with Key. Example:
1431 > put(key1, {merry, lambs, are, playing}),
1433 X = erase(key1),
1434 {X, erase(key1)}.
1435 {{merry,lambs,are,playing},undefined}
1436 error(Reason) -> no_return()
1438 Types:
1440 Reason = term()
1442 Stops the execution of the calling process with the reason Rea‐
1444 son, where Reason is any term. The exit reason is {Reason,
1445 Where}, where Where is a list of the functions most recently
1446 called (the current function first). As evaluating this function
1447 causes the process to terminate, it has no return value. Exam‐
1448 ple:
1449 > catch error(foobar).
1451 {'EXIT',{foobar,[{shell,apply_fun,3,
1452 [{file,"shell.erl"},{line,906}]},
1453 {erl_eval,do_apply,6,[{file,"erl_eval.erl"},{line,677}]},
1454 {erl_eval,expr,5,[{file,"erl_eval.erl"},{line,430}]},
1455 {shell,exprs,7,[{file,"shell.erl"},{line,687}]},
1456 {shell,eval_exprs,7,[{file,"shell.erl"},{line,642}]},
1457 {shell,eval_loop,3,[{file,"shell.erl"},{line,627}]}]}}
1458 error(Reason, Args) -> no_return()
1461 Types:
1463 Reason = term()
1465 Args = [term()]
1466 Stops the execution of the calling process with the reason Rea‐
1468 son, where Reason is any term. The exit reason is {Reason,
1469 Where}, where Where is a list of the functions most recently
1470 called (the current function first). Args is expected to be the
1471 list of arguments for the current function; in Beam it is used
1472 to provide the arguments for the current function in the term
1473 Where. As evaluating this function causes the process to termi‐
1474 nate, it has no return value.
1475 exit(Reason) -> no_return()
1477 Types:
1479 Reason = term()
1481 Stops the execution of the calling process with exit reason Rea‐
1483 son, where Reason is any term. As evaluating this function
1484 causes the process to terminate, it has no return value. Exam‐
1485 ple:
1486 > exit(foobar).
1488 ** exception exit: foobar
1489 > catch exit(foobar).
1490 {'EXIT',foobar}
1491 exit(Pid, Reason) -> true
1493 Types:
1495 Pid = pid() | port()
1497 Reason = term()
1498 Sends an exit signal with exit reason Reason to the process or
1500 port identified by Pid.
1501 The following behavior applies if Reason is any term, except
1503 normal or kill:
1504 * If Pid is not trapping exits, Pid itself exits with exit
1506 reason Reason.
1507 * If Pid is trapping exits, the exit signal is transformed
1509 into a message {'EXIT', From, Reason} and delivered to the
1510 message queue of Pid.
1511 * From is the process identifier of the process that sent the
1513 exit signal. See also process_flag/2.
1514 If Reason is the atom normal, Pid does not exit. If it is trap‐
1516 ping exits, the exit signal is transformed into a message
1517 {'EXIT', From, normal} and delivered to its message queue.
1518 If Reason is the atom kill, that is, if exit(Pid, kill) is
1520 called, an untrappable exit signal is sent to Pid, which uncon‐
1521 ditionally exits with exit reason killed.
1522 erlang:external_size(Term) -> integer() >= 0
1524 Types:
1526 Term = term()
1528 Calculates, without doing the encoding, the maximum byte size
1530 for a term encoded in the Erlang external term format. The fol‐
1531 lowing condition applies always:
1532 > Size1 = byte_size(term_to_binary(Term)),
1534 > Size2 = erlang:external_size(Term),
1535 > true = Size1 =< Size2.
1536 true
1537 This is equivalent to a call to:
1539 erlang:external_size(Term, [])
1541 erlang:external_size(Term, Options) -> integer() >= 0
1543 Types:
1545 Term = term()
1547 Options = [{minor_version, Version :: integer() >= 0}]
1548 Calculates, without doing the encoding, the maximum byte size
1550 for a term encoded in the Erlang external term format. The fol‐
1551 lowing condition applies always:
1552 > Size1 = byte_size(term_to_binary(Term, Options)),
1554 > Size2 = erlang:external_size(Term, Options),
1555 > true = Size1 =< Size2.
1556 true
1557 Option {minor_version, Version} specifies how floats are
1559 encoded. For a detailed description, see term_to_binary/2.
1560 float(Number) -> float()
1562 Types:
1564 Number = number()
1566 Returns a float by converting Number to a float, for example:
1568 > float(55).
1570 55.0
1571 Allowed in guard tests.
1573 Note:
1575 If used on the top level in a guard, it tests whether the argu‐
1576 ment is a floating point number; for clarity, use is_float/1
1577 instead.
1578 When float/1 is used in an expression in a guard, such as
1580 'float(A) == 4.0', it converts a number as described earlier.
1581 float_to_binary(Float) -> binary()
1584 Types:
1586 Float = float()
1588 The same as float_to_binary(Float,[{scientific,20}]).
1590 float_to_binary(Float, Options) -> binary()
1592 Types:
1594 Float = float()
1596 Options = [Option]
1597 Option =
1598 {decimals, Decimals :: 0..253} |
1599 {scientific, Decimals :: 0..249} |
1600 compact
1601 Returns a binary corresponding to the text representation of
1603 Float using fixed decimal point formatting. Options behaves in
1604 the same way as float_to_list/2. Examples:
1605 > float_to_binary(7.12, [{decimals, 4}]).
1607 <<"7.1200">>
1608 > float_to_binary(7.12, [{decimals, 4}, compact]).
1609 <<"7.12">>
1610 float_to_list(Float) -> string()
1612 Types:
1614 Float = float()
1616 The same as float_to_list(Float,[{scientific,20}]).
1618 float_to_list(Float, Options) -> string()
1620 Types:
1622 Float = float()
1624 Options = [Option]
1625 Option =
1626 {decimals, Decimals :: 0..253} |
1627 {scientific, Decimals :: 0..249} |
1628 compact
1629 Returns a string corresponding to the text representation of
1631 Float using fixed decimal point formatting.
1632 Available options:
1634 * If option decimals is specified, the returned value contains
1636 at most Decimals number of digits past the decimal point. If
1637 the number does not fit in the internal static buffer of 256
1638 bytes, the function throws badarg.
1639 * If option compact is specified, the trailing zeros at the
1641 end of the list are truncated. This option is only meaning‐
1642 ful together with option decimals.
1643 * If option scientific is specified, the float is formatted
1645 using scientific notation with Decimals digits of precision.
1646 * If Options is [], the function behaves as float_to_list/1.
1648 Examples:
1650 > float_to_list(7.12, [{decimals, 4}]).
1652 "7.1200"
1653 > float_to_list(7.12, [{decimals, 4}, compact]).
1654 "7.12"
1655 floor(Number) -> integer()
1657 Types:
1659 Number = number()
1661 Returns the largest integer not greater than Number. For exam‐
1663 ple:
1664 > floor(-10.5).
1666 -11
1667 Allowed in guard tests.
1669 erlang:fun_info(Fun) -> [{Item, Info}]
1671 Types:
1673 Fun = function()
1675 Item =
1676 arity | env | index | name | module | new_index |
1677 new_uniq |
1678 pid | type | uniq
1679 Info = term()
1680 Returns a list with information about the fun Fun. Each list
1682 element is a tuple. The order of the tuples is undefined, and
1683 more tuples can be added in a future release.
1684 Warning:
1686 This BIF is mainly intended for debugging, but it can sometimes
1687 be useful in library functions that need to verify, for example,
1688 the arity of a fun.
1689 Two types of funs have slightly different semantics:
1692 * A fun created by fun M:F/A is called an external fun. Call‐
1694 ing it will always call the function F with arity A in the
1695 latest code for module M. Notice that module M does not even
1696 need to be loaded when the fun fun M:F/A is created.
1697 * All other funs are called local. When a local fun is called,
1699 the same version of the code that created the fun is called
1700 (even if a newer version of the module has been loaded).
1701 The following elements are always present in the list for both
1703 local and external funs:
1704 {type, Type}:
1706 Type is local or external.
1707 {module, Module}:
1709 Module (an atom) is the module name.
1710 If Fun is a local fun, Module is the module in which the fun
1712 is defined.
1713 If Fun is an external fun, Module is the module that the fun
1715 refers to.
1716 {name, Name}:
1718 Name (an atom) is a function name.
1719 If Fun is a local fun, Name is the name of the local func‐
1721 tion that implements the fun. (This name was generated by
1722 the compiler, and is only of informational use. As it is a
1723 local function, it cannot be called directly.) If no code is
1724 currently loaded for the fun, [] is returned instead of an
1725 atom.
1726 If Fun is an external fun, Name is the name of the exported
1728 function that the fun refers to.
1729 {arity, Arity}:
1731 Arity is the number of arguments that the fun is to be
1732 called with.
1733 {env, Env}:
1735 Env (a list) is the environment or free variables for the
1736 fun. For external funs, the returned list is always empty.
1737 The following elements are only present in the list if Fun is
1739 local:
1740 {pid, Pid}:
1742 Pid is the process identifier of the process that originally
1743 created the fun.
1744 It might point to the init process if the Fun was statically
1746 allocated when module was loaded (this optimisation is per‐
1747 formed for local functions that do not capture the enviorn‐
1748 ment).
1749 {index, Index}:
1751 Index (an integer) is an index into the module fun table.
1752 {new_index, Index}:
1754 Index (an integer) is an index into the module fun table.
1755 {new_uniq, Uniq}:
1757 Uniq (a binary) is a unique value for this fun. It is calcu‐
1758 lated from the compiled code for the entire module.
1759 {uniq, Uniq}:
1761 Uniq (an integer) is a unique value for this fun. As from
1762 Erlang/OTP R15, this integer is calculated from the compiled
1763 code for the entire module. Before Erlang/OTP R15, this
1764 integer was based on only the body of the fun.
1765 erlang:fun_info(Fun, Item) -> {Item, Info}
1767 Types:
1769 Fun = function()
1771 Item = fun_info_item()
1772 Info = term()
1773 fun_info_item() =
1774 arity | env | index | name | module | new_index | new_uniq |
1775 pid | type | uniq
1776 Returns information about Fun as specified by Item, in the form
1778 {Item,Info}.
1779 For any fun, Item can be any of the atoms module, name, arity,
1781 env, or type.
1782 For a local fun, Item can also be any of the atoms index,
1784 new_index, new_uniq, uniq, and pid. For an external fun, the
1785 value of any of these items is always the atom undefined.
1786 See erlang:fun_info/1.
1788 erlang:fun_to_list(Fun) -> string()
1790 Types:
1792 Fun = function()
1794 Returns a string corresponding to the text representation of
1796 Fun.
1797 erlang:function_exported(Module, Function, Arity) -> boolean()
1799 Types:
1801 Module = module()
1803 Function = atom()
1804 Arity = arity()
1805 Returns true if the module Module is loaded and contains an
1807 exported function Function/Arity, or if there is a BIF (a built-
1808 in function implemented in C) with the specified name, otherwise
1809 returns false.
1810 Note:
1812 This function used to return false for BIFs before Erlang/OTP
1813 18.0.
1814 garbage_collect() -> true
1817 Forces an immediate garbage collection of the executing process.
1819 The function is not to be used unless it has been noticed (or
1820 there are good reasons to suspect) that the spontaneous garbage
1821 collection will occur too late or not at all.
1822 Warning:
1824 Improper use can seriously degrade system performance.
1825 garbage_collect(Pid) -> GCResult
1828 Types:
1830 Pid = pid()
1832 GCResult = boolean()
1833 The same as garbage_collect(Pid, []).
1835 garbage_collect(Pid, OptionList) -> GCResult | async
1837 Types:
1839 Pid = pid()
1841 RequestId = term()
1842 Option = {async, RequestId} | {type, major | minor}
1843 OptionList = [Option]
1844 GCResult = boolean()
1845 Garbage collects the node local process identified by Pid.
1847 Option:
1849 {async, RequestId}:
1851 The function garbage_collect/2 returns the value async imme‐
1852 diately after the request has been sent. When the request
1853 has been processed, the process that called this function is
1854 passed a message on the form {garbage_collect, RequestId,
1855 GCResult}.
1856 {type, 'major' | 'minor'}:
1858 Triggers garbage collection of requested type. Default value
1859 is 'major', which would trigger a fullsweep GC. The option
1860 'minor' is considered a hint and may lead to either minor or
1861 major GC run.
1862 If Pid equals self(), and no async option has been passed, the
1864 garbage collection is performed at once, that is, the same as
1865 calling garbage_collect/0. Otherwise a request for garbage col‐
1866 lection is sent to the process identified by Pid, and will be
1867 handled when appropriate. If no async option has been passed,
1868 the caller blocks until GCResult is available and can be
1869 returned.
1870 GCResult informs about the result of the garbage collection
1872 request as follows:
1873 true:
1875 The process identified by Pid has been garbage collected.
1876 false:
1878 No garbage collection was performed, as the process identi‐
1879 fied by Pid terminated before the request could be satis‐
1880 fied.
1881 Notice that the same caveats apply as for garbage_collect/0.
1883 Failures:
1885 badarg:
1887 If Pid is not a node local process identifier.
1888 badarg:
1890 If OptionList is an invalid list of options.
1891 get() -> [{Key, Val}]
1893 Types:
1895 Key = Val = term()
1897 Returns the process dictionary as a list of {Key, Val} tuples,
1899 for example:
1900 > put(key1, merry),
1902 put(key2, lambs),
1903 put(key3, {are, playing}),
1904 get().
1905 [{key1,merry},{key2,lambs},{key3,{are,playing}}]
1906 get(Key) -> Val | undefined
1908 Types:
1910 Key = Val = term()
1912 Returns the value Val associated with Key in the process dictio‐
1914 nary, or undefined if Key does not exist. Example:
1915 > put(key1, merry),
1917 put(key2, lambs),
1918 put({any, [valid, term]}, {are, playing}),
1919 get({any, [valid, term]}).
1920 {are,playing}
1921 erlang:get_cookie() -> Cookie | nocookie
1923 Types:
1925 Cookie = atom()
1927 Returns the magic cookie of the local node if the node is alive,
1929 otherwise the atom nocookie.
1930 get_keys() -> [Key]
1932 Types:
1934 Key = term()
1936 Returns a list of all keys present in the process dictionary,
1938 for example:
1939 > put(dog, {animal,1}),
1941 put(cow, {animal,2}),
1942 put(lamb, {animal,3}),
1943 get_keys().
1944 [dog,cow,lamb]
1945 get_keys(Val) -> [Key]
1947 Types:
1949 Val = Key = term()
1951 Returns a list of keys that are associated with the value Val in
1953 the process dictionary, for example:
1954 > put(mary, {1, 2}),
1956 put(had, {1, 2}),
1957 put(a, {1, 2}),
1958 put(little, {1, 2}),
1959 put(dog, {1, 3}),
1960 put(lamb, {1, 2}),
1961 get_keys({1, 2}).
1962 [mary,had,a,little,lamb]
1963 erlang:get_stacktrace() -> [stack_item()]
1965 Types:
1967 stack_item() =
1969 {Module :: module(),
1970 Function :: atom(),
1971 Arity :: arity() | (Args :: [term()]),
1972 Location ::
1973 [{file, Filename :: string()} |
1974 {line, Line :: integer() >= 1}]}
1975 Warning:
1977 erlang:get_stacktrace/0 is deprecated and will stop working in a
1978 future release.
1979 Instead of using erlang:get_stacktrace/0 to retrieve the call
1982 stack back-trace, use the following syntax:
1983 try Expr
1985 catch
1986 Class:Reason:Stacktrace ->
1987 {Class,Reason,Stacktrace}
1988 end
1989 erlang:get_stacktrace/0 retrieves the call stack back-trace
1991 (stacktrace) for an exception that has just been caught in the
1992 calling process as a list of {Module,Function,Arity,Location}
1993 tuples. Field Arity in the first tuple can be the argument list
1994 of that function call instead of an arity integer, depending on
1995 the exception.
1996 If there has not been any exceptions in a process, the stack‐
1998 trace is []. After a code change for the process, the stacktrace
1999 can also be reset to [].
2000 The stacktrace is the same data as operator catch returns, for
2002 example:
2003 {'EXIT',{badarg,Stacktrace}} = catch abs(x)
2005 Location is a (possibly empty) list of two-tuples that can indi‐
2007 cate the location in the source code of the function. The first
2008 element is an atom describing the type of information in the
2009 second element. The following items can occur:
2010 file:
2012 The second element of the tuple is a string (list of charac‐
2013 ters) representing the filename of the source file of the
2014 function.
2015 line:
2017 The second element of the tuple is the line number (an inte‐
2018 ger > 0) in the source file where the exception occurred or
2019 the function was called.
2020 Warning:
2022 Developers should rely on stacktrace entries only for debugging
2023 purposes.
2024 The VM performs tail call optimization, which does not add new
2026 entries to the stacktrace, and also limits stacktraces to a cer‐
2027 tain depth. Furthermore, compiler options, optimizations and
2028 future changes may add or remove stacktrace entries, causing any
2029 code that expects the stacktrace to be in a certain order or
2030 contain specific items to fail.
2031 The only exception to this rule is error:undef which guarantees
2033 to include the Module, Function and Arity of the attempted func‐
2034 tion as the first stacktrace entry.
2035 See also error/1 and error/2.
2038 group_leader() -> pid()
2040 Returns the process identifier of the group leader for the
2042 process evaluating the function.
2043 Every process is a member of some process group and all groups
2045 have a group leader. All I/O from the group is channeled to the
2046 group leader. When a new process is spawned, it gets the same
2047 group leader as the spawning process. Initially, at system
2048 startup, init is both its own group leader and the group leader
2049 of all processes.
2050 group_leader(GroupLeader, Pid) -> true
2052 Types:
2054 GroupLeader = Pid = pid()
2056 Sets the group leader of Pid to GroupLeader. Typically, this is
2058 used when a process started from a certain shell is to have
2059 another group leader than init.
2060 The group leader should be rarely changed in applications with a
2062 supervision tree, because OTP assumes the group leader of their
2063 processes is their application master.
2064 See also group_leader/0 and OTP design principles related to
2066 starting and stopping applications.
2067 halt() -> no_return()
2069 The same as halt(0, []). Example:
2071 > halt().
2073 os_prompt%
2074 halt(Status) -> no_return()
2076 Types:
2078 Status = integer() >= 0 | abort | string()
2080 The same as halt(Status, []). Example:
2082 > halt(17).
2084 os_prompt% echo $?
2085 17
2086 os_prompt%
2087 halt(Status, Options) -> no_return()
2089 Types:
2091 Status = integer() >= 0 | abort | string()
2093 Options = [Option]
2094 Option = {flush, boolean()}
2095 Status must be a non-negative integer, a string, or the atom
2097 abort. Halts the Erlang runtime system. Has no return value.
2098 Depending on Status, the following occurs:
2099 integer():
2101 The runtime system exits with integer value Status as status
2102 code to the calling environment (OS).
2103 Note:
2105 On many platforms, the OS supports only status codes 0-255. A
2106 too large status code is truncated by clearing the high bits.
2107 string():
2110 An Erlang crash dump is produced with Status as slogan. Then
2111 the runtime system exits with status code 1. The string will
2112 be truncated if longer than 200 characters.
2113 Note:
2115 Before ERTS 9.1 (OTP-20.1) only code points in the range 0-255
2116 was accepted in the string. Now any unicode string is valid.
2117 abort:
2120 The runtime system aborts producing a core dump, if that is
2121 enabled in the OS.
2122 For integer Status, the Erlang runtime system closes all ports
2124 and allows async threads to finish their operations before exit‐
2125 ing. To exit without such flushing, use Option as {flush,false}.
2126 For statuses string() and abort, option flush is ignored and
2128 flushing is not done.
2129 hd(List) -> term()
2131 Types:
2133 List = [term(), ...]
2135 Returns the head of List, that is, the first element, for exam‐
2137 ple:
2138 > hd([1,2,3,4,5]).
2140 1
2141 Allowed in guard tests.
2143 Failure: badarg if List is the empty list [].
2145 erlang:hibernate(Module, Function, Args) -> no_return()
2147 Types:
2149 Module = module()
2151 Function = atom()
2152 Args = [term()]
2153 Puts the calling process into a wait state where its memory
2155 allocation has been reduced as much as possible. This is useful
2156 if the process does not expect to receive any messages soon.
2157 The process is awaken when a message is sent to it, and control
2159 resumes in Module:Function with the arguments specified by Args
2160 with the call stack emptied, meaning that the process terminates
2161 when that function returns. Thus erlang:hibernate/3 never
2162 returns to its caller.
2163 If the process has any message in its message queue, the process
2165 is awakened immediately in the same way as described earlier.
2166 In more technical terms, erlang:hibernate/3 discards the call
2168 stack for the process, and then garbage collects the process.
2169 After this, all live data is in one continuous heap. The heap is
2170 then shrunken to the exact same size as the live data that it
2171 holds (even if that size is less than the minimum heap size for
2172 the process).
2173 If the size of the live data in the process is less than the
2175 minimum heap size, the first garbage collection occurring after
2176 the process is awakened ensures that the heap size is changed to
2177 a size not smaller than the minimum heap size.
2178 Notice that emptying the call stack means that any surrounding
2180 catch is removed and must be re-inserted after hibernation. One
2181 effect of this is that processes started using proc_lib (also
2182 indirectly, such as gen_server processes), are to use
2183 proc_lib:hibernate/3 instead, to ensure that the exception han‐
2184 dler continues to work when the process wakes up.
2185 erlang:insert_element(Index, Tuple1, Term) -> Tuple2
2187 Types:
2189 Index = integer() >= 1
2191 1..tuple_size(Tuple1) + 1
2192 Tuple1 = Tuple2 = tuple()
2193 Term = term()
2194 Returns a new tuple with element Term inserted at position Index
2196 in tuple Tuple1. All elements from position Index and upwards
2197 are pushed one step higher in the new tuple Tuple2. Example:
2198 > erlang:insert_element(2, {one, two, three}, new).
2200 {one,new,two,three}
2201 integer_to_binary(Integer) -> binary()
2203 Types:
2205 Integer = integer()
2207 Returns a binary corresponding to the text representation of
2209 Integer, for example:
2210 > integer_to_binary(77).
2212 <<"77">>
2213 integer_to_binary(Integer, Base) -> binary()
2215 Types:
2217 Integer = integer()
2219 Base = 2..36
2220 Returns a binary corresponding to the text representation of
2222 Integer in base Base, for example:
2223 > integer_to_binary(1023, 16).
2225 <<"3FF">>
2226 integer_to_list(Integer) -> string()
2228 Types:
2230 Integer = integer()
2232 Returns a string corresponding to the text representation of
2234 Integer, for example:
2235 > integer_to_list(77).
2237 "77"
2238 integer_to_list(Integer, Base) -> string()
2240 Types:
2242 Integer = integer()
2244 Base = 2..36
2245 Returns a string corresponding to the text representation of
2247 Integer in base Base, for example:
2248 > integer_to_list(1023, 16).
2250 "3FF"
2251 iolist_size(Item) -> integer() >= 0
2253 Types:
2255 Item = iolist() | binary()
2257 Returns an integer, that is the size in bytes, of the binary
2259 that would be the result of iolist_to_binary(Item), for example:
2260 > iolist_size([1,2|<<3,4>>]).
2262 4
2263 iolist_to_binary(IoListOrBinary) -> binary()
2265 Types:
2267 IoListOrBinary = iolist() | binary()
2269 Returns a binary that is made from the integers and binaries in
2271 IoListOrBinary, for example:
2272 > Bin1 = <<1,2,3>>.
2274 <<1,2,3>>
2275 > Bin2 = <<4,5>>.
2276 <<4,5>>
2277 > Bin3 = <<6>>.
2278 <<6>>
2279 > iolist_to_binary([Bin1,1,[2,3,Bin2],4|Bin3]).
2280 <<1,2,3,1,2,3,4,5,4,6>>
2281 erlang:iolist_to_iovec(IoListOrBinary) -> iovec()
2283 Types:
2285 IoListOrBinary = iolist() | binary()
2287 Returns an iovec that is made from the integers and binaries in
2289 IoListOrBinary.
2290 is_alive() -> boolean()
2292 Returns true if the local node is alive (that is, if the node
2294 can be part of a distributed system), otherwise false.
2295 is_atom(Term) -> boolean()
2297 Types:
2299 Term = term()
2301 Returns true if Term is an atom, otherwise false.
2303 Allowed in guard tests.
2305 is_binary(Term) -> boolean()
2307 Types:
2309 Term = term()
2311 Returns true if Term is a binary, otherwise false.
2313 A binary always contains a complete number of bytes.
2315 Allowed in guard tests.
2317 is_bitstring(Term) -> boolean()
2319 Types:
2321 Term = term()
2323 Returns true if Term is a bitstring (including a binary), other‐
2325 wise false.
2326 Allowed in guard tests.
2328 is_boolean(Term) -> boolean()
2330 Types:
2332 Term = term()
2334 Returns true if Term is the atom true or the atom false (that
2336 is, a boolean). Otherwise returns false.
2337 Allowed in guard tests.
2339 erlang:is_builtin(Module, Function, Arity) -> boolean()
2341 Types:
2343 Module = module()
2345 Function = atom()
2346 Arity = arity()
2347 This BIF is useful for builders of cross-reference tools.
2349 Returns true if Module:Function/Arity is a BIF implemented in C,
2351 otherwise false.
2352 is_float(Term) -> boolean()
2354 Types:
2356 Term = term()
2358 Returns true if Term is a floating point number, otherwise
2360 false.
2361 Allowed in guard tests.
2363 is_function(Term) -> boolean()
2365 Types:
2367 Term = term()
2369 Returns true if Term is a fun, otherwise false.
2371 Allowed in guard tests.
2373 is_function(Term, Arity) -> boolean()
2375 Types:
2377 Term = term()
2379 Arity = arity()
2380 Returns true if Term is a fun that can be applied with Arity
2382 number of arguments, otherwise false.
2383 Allowed in guard tests.
2385 is_integer(Term) -> boolean()
2387 Types:
2389 Term = term()
2391 Returns true if Term is an integer, otherwise false.
2393 Allowed in guard tests.
2395 is_list(Term) -> boolean()
2397 Types:
2399 Term = term()
2401 Returns true if Term is a list with zero or more elements, oth‐
2403 erwise false.
2404 Allowed in guard tests.
2406 is_map(Term) -> boolean()
2408 Types:
2410 Term = term()
2412 Returns true if Term is a map, otherwise false.
2414 Allowed in guard tests.
2416 is_map_key(Key, Map) -> boolean()
2418 Types:
2420 Key = term()
2422 Map = map()
2423 Returns true if map Map contains Key and returns false if it
2425 does not contain the Key.
2426 The call fails with a {badmap,Map} exception if Map is not a
2428 map.
2429 Example:
2431 > Map = #{"42" => value}.
2433 #{"42" => value}
2434 > is_map_key("42",Map).
2435 true
2436 > is_map_key(value,Map).
2437 false
2438 Allowed in guard tests.
2440 is_number(Term) -> boolean()
2442 Types:
2444 Term = term()
2446 Returns true if Term is an integer or a floating point number.
2448 Otherwise returns false.
2449 Allowed in guard tests.
2451 is_pid(Term) -> boolean()
2453 Types:
2455 Term = term()
2457 Returns true if Term is a process identifier, otherwise false.
2459 Allowed in guard tests.
2461 is_port(Term) -> boolean()
2463 Types:
2465 Term = term()
2467 Returns true if Term is a port identifier, otherwise false.
2469 Allowed in guard tests.
2471 is_process_alive(Pid) -> boolean()
2473 Types:
2475 Pid = pid()
2477 Pid must refer to a process at the local node.
2479 Returns true if the process exists and is alive, that is, is not
2481 exiting and has not exited. Otherwise returns false.
2482 is_record(Term, RecordTag) -> boolean()
2484 Types:
2486 Term = term()
2488 RecordTag = atom()
2489 Returns true if Term is a tuple and its first element is Record‐
2491 Tag. Otherwise returns false.
2492 Note:
2494 Normally the compiler treats calls to is_record/2 especially. It
2495 emits code to verify that Term is a tuple, that its first ele‐
2496 ment is RecordTag, and that the size is correct. However, if
2497 RecordTag is not a literal atom, the BIF is_record/2 is called
2498 instead and the size of the tuple is not verified.
2499 Allowed in guard tests, if RecordTag is a literal atom.
2502 is_record(Term, RecordTag, Size) -> boolean()
2504 Types:
2506 Term = term()
2508 RecordTag = atom()
2509 Size = integer() >= 0
2510 RecordTag must be an atom.
2512 Returns true if Term is a tuple, its first element is RecordTag,
2514 and its size is Size. Otherwise returns false.
2515 Allowed in guard tests if RecordTag is a literal atom and Size
2517 is a literal integer.
2518 Note:
2520 This BIF is documented for completeness. Usually is_record/2 is
2521 to be used.
2522 is_reference(Term) -> boolean()
2525 Types:
2527 Term = term()
2529 Returns true if Term is a reference, otherwise false.
2531 Allowed in guard tests.
2533 is_tuple(Term) -> boolean()
2535 Types:
2537 Term = term()
2539 Returns true if Term is a tuple, otherwise false.
2541 Allowed in guard tests.
2543 length(List) -> integer() >= 0
2545 Types:
2547 List = [term()]
2549 Returns the length of List, for example:
2551 > length([1,2,3,4,5,6,7,8,9]).
2553 9
2554 Allowed in guard tests.
2556 link(PidOrPort) -> true
2558 Types:
2560 PidOrPort = pid() | port()
2562 Creates a link between the calling process and another process
2564 (or port) PidOrPort, if there is not such a link already. If a
2565 process attempts to create a link to itself, nothing is done.
2566 Returns true.
2567 If PidOrPort does not exist, the behavior of the BIF depends on
2569 if the calling process is trapping exits or not (see
2570 process_flag/2):
2571 * If the calling process is not trapping exits, and checking
2573 PidOrPort is cheap (that is, if PidOrPort is local), link/1
2574 fails with reason noproc.
2575 * Otherwise, if the calling process is trapping exits, and/or
2577 PidOrPort is remote, link/1 returns true, but an exit signal
2578 with reason noproc is sent to the calling process.
2579 list_to_atom(String) -> atom()
2581 Types:
2583 String = string()
2585 Returns the atom whose text representation is String.
2587 As from Erlang/OTP 20, String may contain any Unicode character.
2589 Earlier versions allowed only ISO-latin-1 characters as the
2590 implementation did not allow Unicode characters above 255. For
2591 more information on Unicode support in atoms, see note on UTF-8
2592 encoded atoms in section "External Term Format" in the User's
2593 Guide.
2594 Example:
2596 > list_to_atom("Erlang").
2598 list_to_binary(IoList) -> binary()
2600 Types:
2602 IoList = iolist()
2604 Returns a binary that is made from the integers and binaries in
2606 IoList, for example:
2607 > Bin1 = <<1,2,3>>.
2609 <<1,2,3>>
2610 > Bin2 = <<4,5>>.
2611 <<4,5>>
2612 > Bin3 = <<6>>.
2613 <<6>>
2614 > list_to_binary([Bin1,1,[2,3,Bin2],4|Bin3]).
2615 <<1,2,3,1,2,3,4,5,4,6>>
2616 list_to_bitstring(BitstringList) -> bitstring()
2618 Types:
2620 BitstringList = bitstring_list()
2622 bitstring_list() =
2623 maybe_improper_list(byte() | bitstring() | bitstring_list(),
2624 bitstring() | [])
2625 Returns a bitstring that is made from the integers and bit‐
2627 strings in BitstringList. (The last tail in BitstringList is
2628 allowed to be a bitstring.) Example:
2629 > Bin1 = <<1,2,3>>.
2631 <<1,2,3>>
2632 > Bin2 = <<4,5>>.
2633 <<4,5>>
2634 > Bin3 = <<6,7:4>>.
2635 <<6,7:4>>
2636 > list_to_bitstring([Bin1,1,[2,3,Bin2],4|Bin3]).
2637 <<1,2,3,1,2,3,4,5,4,6,7:4>>
2638 list_to_existing_atom(String) -> atom()
2640 Types:
2642 String = string()
2644 Returns the atom whose text representation is String, but only
2646 if there already exists such atom.
2647 Failure: badarg if there does not already exist an atom whose
2649 text representation is String.
2650 Note:
2652 Note that the compiler may optimize away atoms. For example, the
2653 compiler will rewrite atom_to_list(some_atom) to "some_atom". If
2654 that expression is the only mention of the atom some_atom in the
2655 containing module, the atom will not be created when the module
2656 is loaded, and a subsequent call to list_to_exist‐
2657 ing_atom("some_atom") will fail.
2658 list_to_float(String) -> float()
2661 Types:
2663 String = string()
2665 Returns the float whose text representation is String, for exam‐
2667 ple:
2668 > list_to_float("2.2017764e+0").
2670 2.2017764
2671 Failure: badarg if String contains a bad representation of a
2673 float.
2674 list_to_integer(String) -> integer()
2676 Types:
2678 String = string()
2680 Returns an integer whose text representation is String, for
2682 example:
2683 > list_to_integer("123").
2685 123
2686 Failure: badarg if String contains a bad representation of an
2688 integer.
2689 list_to_integer(String, Base) -> integer()
2691 Types:
2693 String = string()
2695 Base = 2..36
2696 Returns an integer whose text representation in base Base is
2698 String, for example:
2699 > list_to_integer("3FF", 16).
2701 1023
2702 Failure: badarg if String contains a bad representation of an
2704 integer.
2705 list_to_pid(String) -> pid()
2707 Types:
2709 String = string()
2711 Returns a process identifier whose text representation is a
2713 String, for example:
2714 > list_to_pid("<0.4.1>").
2716 <0.4.1>
2717 Failure: badarg if String contains a bad representation of a
2719 process identifier.
2720 Warning:
2722 This BIF is intended for debugging and is not to be used in
2723 application programs.
2724 list_to_port(String) -> port()
2727 Types:
2729 String = string()
2731 Returns a port identifier whose text representation is a String,
2733 for example:
2734 > list_to_port("#Port<0.4>").
2736 #Port<0.4>
2737 Failure: badarg if String contains a bad representation of a
2739 port identifier.
2740 Warning:
2742 This BIF is intended for debugging and is not to be used in
2743 application programs.
2744 list_to_ref(String) -> reference()
2747 Types:
2749 String = string()
2751 Returns a reference whose text representation is a String, for
2753 example:
2754 > list_to_ref("#Ref<0.4192537678.4073193475.71181>").
2756 #Ref<0.4192537678.4073193475.71181>
2757 Failure: badarg if String contains a bad representation of a
2759 reference.
2760 Warning:
2762 This BIF is intended for debugging and is not to be used in
2763 application programs.
2764 list_to_tuple(List) -> tuple()
2767 Types:
2769 List = [term()]
2771 Returns a tuple corresponding to List, for example
2773 > list_to_tuple([share, ['Ericsson_B', 163]]).
2775 {share, ['Ericsson_B', 163]}
2776 List can contain any Erlang terms.
2778 load_module(Module, Binary) -> {module, Module} | {error, Reason}
2780 Types:
2782 Module = module()
2784 Binary = binary()
2785 Reason = badfile | not_purged | on_load
2786 If Binary contains the object code for module Module, this BIF
2788 loads that object code. If the code for module Module already
2789 exists, all export references are replaced so they point to the
2790 newly loaded code. The previously loaded code is kept in the
2791 system as old code, as there can still be processes executing
2792 that code.
2793 Returns either {module, Module}, or {error, Reason} if loading
2795 fails. Reason is one of the following:
2796 badfile:
2798 The object code in Binary has an incorrect format or the
2799 object code contains code for another module than Module.
2800 not_purged:
2802 Binary contains a module that cannot be loaded because old
2803 code for this module already exists.
2804 Warning:
2806 This BIF is intended for the code server (see code(3)) and is
2807 not to be used elsewhere.
2808 erlang:load_nif(Path, LoadInfo) -> ok | Error
2811 Types:
2813 Path = string()
2815 LoadInfo = term()
2816 Error = {error, {Reason, Text :: string()}}
2817 Reason =
2818 load_failed | bad_lib | load | reload | upgrade |
2819 old_code
2820 Loads and links a dynamic library containing native implemented
2822 functions (NIFs) for a module. Path is a file path to the share‐
2823 able object/dynamic library file minus the OS-dependent file
2824 extension (.so for Unix and .dll for Windows). Notice that on
2825 most OSs the library has to have a different name on disc when
2826 an upgrade of the nif is done. If the name is the same, but the
2827 contents differ, the old library may be loaded instead. For
2828 information on how to implement a NIF library, see erl_nif(3).
2829 LoadInfo can be any term. It is passed on to the library as part
2831 of the initialization. A good practice is to include a module
2832 version number to support future code upgrade scenarios.
2833 The call to load_nif/2 must be made directly from the Erlang
2835 code of the module that the NIF library belongs to. It returns
2836 either ok, or {error,{Reason,Text}} if loading fails. Reason is
2837 one of the following atoms while Text is a human readable string
2838 that can give more information about the failure:
2839 load_failed:
2841 The OS failed to load the NIF library.
2842 bad_lib:
2844 The library did not fulfill the requirements as a NIF
2845 library of the calling module.
2846 load | upgrade:
2848 The corresponding library callback was unsuccessful.
2849 reload:
2851 A NIF library is already loaded for this module instance.
2852 The previously deprecated reload feature was removed in OTP
2853 20.
2854 old_code:
2856 The call to load_nif/2 was made from the old code of a mod‐
2857 ule that has been upgraded; this is not allowed.
2858 notsup:
2860 Lack of support. Such as loading NIF library for a HiPE com‐
2861 piled module.
2862 erlang:loaded() -> [Module]
2864 Types:
2866 Module = module()
2868 Returns a list of all loaded Erlang modules (current and old
2870 code), including preloaded modules.
2871 See also code(3).
2873 erlang:localtime() -> DateTime
2875 Types:
2877 DateTime = calendar:datetime()
2879 Returns the current local date and time, {{Year, Month, Day},
2881 {Hour, Minute, Second}}, for example:
2882 > erlang:localtime().
2884 {{1996,11,6},{14,45,17}}
2885 The time zone and Daylight Saving Time correction depend on the
2887 underlying OS.
2888 erlang:localtime_to_universaltime(Localtime) -> Universaltime
2890 Types:
2892 Localtime = Universaltime = calendar:datetime()
2894 Converts local date and time to Universal Time Coordinated
2896 (UTC), if supported by the underlying OS. Otherwise no conver‐
2897 sion is done and Localtime is returned. Example:
2898 > erlang:localtime_to_universaltime({{1996,11,6},{14,45,17}}).
2900 {{1996,11,6},{13,45,17}}
2901 Failure: badarg if Localtime denotes an invalid date and time.
2903 erlang:localtime_to_universaltime(Localtime, IsDst) ->
2905 Universaltime
2906 Types:
2908 Localtime = Universaltime = calendar:datetime()
2910 IsDst = true | false | undefined
2911 Converts local date and time to Universal Time Coordinated (UTC)
2913 as erlang:localtime_to_universaltime/1, but the caller decides
2914 if Daylight Saving Time is active.
2915 If IsDst == true, Localtime is during Daylight Saving Time, if
2917 IsDst == false it is not. If IsDst == undefined, the underlying
2918 OS can guess, which is the same as calling erlang:local‐
2919 time_to_universaltime(Localtime).
2920 Examples:
2922 > erlang:localtime_to_universaltime({{1996,11,6},{14,45,17}}, true).
2924 {{1996,11,6},{12,45,17}}
2925 > erlang:localtime_to_universaltime({{1996,11,6},{14,45,17}}, false).
2926 {{1996,11,6},{13,45,17}}
2927 > erlang:localtime_to_universaltime({{1996,11,6},{14,45,17}}, undefined).
2928 {{1996,11,6},{13,45,17}}
2929 Failure: badarg if Localtime denotes an invalid date and time.
2931 make_ref() -> reference()
2933 Returns a unique reference. The reference is unique among con‐
2935 nected nodes.
2936 Warning:
2938 Known issue: When a node is restarted multiple times with the
2939 same node name, references created on a newer node can be mis‐
2940 taken for a reference created on an older node with the same
2941 node name.
2942 erlang:make_tuple(Arity, InitialValue) -> tuple()
2945 Types:
2947 Arity = arity()
2949 InitialValue = term()
2950 Creates a new tuple of the specified Arity, where all elements
2952 are InitialValue, for example:
2953 > erlang:make_tuple(4, []).
2955 {[],[],[],[]}
2956 erlang:make_tuple(Arity, DefaultValue, InitList) -> tuple()
2958 Types:
2960 Arity = arity()
2962 DefaultValue = term()
2963 InitList = [{Position :: integer() >= 1, term()}]
2964 Creates a tuple of size Arity, where each element has value
2966 DefaultValue, and then fills in values from InitList. Each list
2967 element in InitList must be a two-tuple, where the first element
2968 is a position in the newly created tuple and the second element
2969 is any term. If a position occurs more than once in the list,
2970 the term corresponding to the last occurrence is used. Example:
2971 > erlang:make_tuple(5, [], [{2,ignored},{5,zz},{2,aa}]).
2973 {[],aa,[],[],zz}
2974 map_get(Key, Map) -> Value
2976 Types:
2978 Map = map()
2980 Key = Value = any()
2981 Returns value Value associated with Key if Map contains Key.
2983 The call fails with a {badmap,Map} exception if Map is not a
2985 map, or with a {badkey,Key} exception if no value is associated
2986 with Key.
2987 Example:
2989 > Key = 1337,
2991 Map = #{42 => value_two,1337 => "value one","a" => 1},
2992 map_get(Key,Map).
2993 "value one"
2994 Allowed in guard tests.
2996 map_size(Map) -> integer() >= 0
2998 Types:
3000 Map = map()
3002 Returns an integer, which is the number of key-value pairs in
3004 Map, for example:
3005 > map_size(#{a=>1, b=>2, c=>3}).
3007 3
3008 Allowed in guard tests.
3010 erlang:match_spec_test(MatchAgainst, MatchSpec, Type) ->
3012 TestResult
3013 Types:
3015 MatchAgainst = [term()] | tuple()
3017 MatchSpec = term()
3018 Type = table | trace
3019 TestResult =
3020 {ok, term(), [return_trace], [{error | warning,
3021 string()}]} |
3022 {error, [{error | warning, string()}]}
3023 Tests a match specification used in calls to ets:select/2 and
3025 erlang:trace_pattern/3. The function tests both a match specifi‐
3026 cation for "syntactic" correctness and runs the match specifica‐
3027 tion against the object. If the match specification contains
3028 errors, the tuple {error, Errors} is returned, where Errors is a
3029 list of natural language descriptions of what was wrong with the
3030 match specification.
3031 If Type is table, the object to match against is to be a tuple.
3033 The function then returns {ok,Result,[],Warnings}, where Result
3034 is what would have been the result in a real ets:select/2 call,
3035 or false if the match specification does not match the object
3036 tuple.
3037 If Type is trace, the object to match against is to be a list.
3039 The function returns {ok, Result, Flags, Warnings}, where Result
3040 is one of the following:
3041 * true if a trace message is to be emitted
3043 * false if a trace message is not to be emitted
3045 * The message term to be appended to the trace message
3047 Flags is a list containing all the trace flags to be enabled,
3049 currently this is only return_trace.
3050 This is a useful debugging and test tool, especially when writ‐
3052 ing complicated match specifications.
3053 See also ets:test_ms/2.
3055 max(Term1, Term2) -> Maximum
3057 Types:
3059 Term1 = Term2 = Maximum = term()
3061 Returns the largest of Term1 and Term2. If the terms are equal,
3063 Term1 is returned.
3064 erlang:md5(Data) -> Digest
3066 Types:
3068 Data = iodata()
3070 Digest = binary()
3071 Computes an MD5 message digest from Data, where the length of
3073 the digest is 128 bits (16 bytes). Data is a binary or a list of
3074 small integers and binaries.
3075 For more information about MD5, see RFC 1321 - The MD5 Message-
3077 Digest Algorithm.
3078 Warning:
3080 The MD5 Message-Digest Algorithm is not considered safe for
3081 code-signing or software-integrity purposes.
3082 erlang:md5_final(Context) -> Digest
3085 Types:
3087 Context = Digest = binary()
3089 Finishes the update of an MD5 Context and returns the computed
3091 MD5 message digest.
3092 erlang:md5_init() -> Context
3094 Types:
3096 Context = binary()
3098 Creates an MD5 context, to be used in the following calls to
3100 md5_update/2.
3101 erlang:md5_update(Context, Data) -> NewContext
3103 Types:
3105 Context = binary()
3107 Data = iodata()
3108 NewContext = binary()
3109 Update an MD5 Context with Data and returns a NewContext.
3111 erlang:memory() -> [{Type, Size}]
3113 Types:
3115 Type = memory_type()
3117 Size = integer() >= 0
3118 memory_type() =
3119 total | processes | processes_used | system | atom |
3120 atom_used | binary | code | ets
3121 Returns a list with information about memory dynamically allo‐
3123 cated by the Erlang emulator. Each list element is a tuple
3124 {Type, Size}. The first element Type is an atom describing mem‐
3125 ory type. The second element Size is the memory size in bytes.
3126 Memory types:
3128 total:
3130 The total amount of memory currently allocated. This is the
3131 same as the sum of the memory size for processes and system.
3132 processes:
3134 The total amount of memory currently allocated for the
3135 Erlang processes.
3136 processes_used:
3138 The total amount of memory currently used by the Erlang pro‐
3139 cesses. This is part of the memory presented as processes
3140 memory.
3141 system:
3143 The total amount of memory currently allocated for the emu‐
3144 lator that is not directly related to any Erlang process.
3145 Memory presented as processes is not included in this mem‐
3146 ory. instrument(3) can be used to get a more detailed break‐
3147 down of what memory is part of this type.
3148 atom:
3150 The total amount of memory currently allocated for atoms.
3151 This memory is part of the memory presented as system mem‐
3152 ory.
3153 atom_used:
3155 The total amount of memory currently used for atoms. This
3156 memory is part of the memory presented as atom memory.
3157 binary:
3159 The total amount of memory currently allocated for binaries.
3160 This memory is part of the memory presented as system mem‐
3161 ory.
3162 code:
3164 The total amount of memory currently allocated for Erlang
3165 code. This memory is part of the memory presented as system
3166 memory.
3167 ets:
3169 The total amount of memory currently allocated for ETS
3170 tables. This memory is part of the memory presented as sys‐
3171 tem memory.
3172 low:
3174 Only on 64-bit halfword emulator. The total amount of memory
3175 allocated in low memory areas that are restricted to < 4 GB,
3176 although the system can have more memory.
3177 Can be removed in a future release of the halfword emulator.
3179 maximum:
3181 The maximum total amount of memory allocated since the emu‐
3182 lator was started. This tuple is only present when the emu‐
3183 lator is run with instrumentation.
3184 For information on how to run the emulator with instrumenta‐
3186 tion, see instrument(3) and/or erl(1).
3187 Note:
3189 The system value is not complete. Some allocated memory that is
3190 to be part of this value is not.
3191 When the emulator is run with instrumentation, the system value
3193 is more accurate, but memory directly allocated for malloc (and
3194 friends) is still not part of the system value. Direct calls to
3195 malloc are only done from OS-specific runtime libraries and per‐
3196 haps from user-implemented Erlang drivers that do not use the
3197 memory allocation functions in the driver interface.
3198 As the total value is the sum of processes and system, the error
3200 in system propagates to the total value.
3201 The different amounts of memory that are summed are not gathered
3203 atomically, which introduces an error in the result.
3204 The different values have the following relation to each other.
3207 Values beginning with an uppercase letter is not part of the
3208 result.
3209 total = processes + system
3211 processes = processes_used + ProcessesNotUsed
3212 system = atom + binary + code + ets + OtherSystem
3213 atom = atom_used + AtomNotUsed
3214 RealTotal = processes + RealSystem
3215 RealSystem = system + MissedSystem
3216 More tuples in the returned list can be added in a future
3218 release.
3219 Note:
3221 The total value is supposed to be the total amount of memory
3222 dynamically allocated by the emulator. Shared libraries, the
3223 code of the emulator itself, and the emulator stacks are not
3224 supposed to be included. That is, the total value is not sup‐
3225 posed to be equal to the total size of all pages mapped to the
3226 emulator.
3227 Also, because of fragmentation and prereservation of memory
3229 areas, the size of the memory segments containing the dynami‐
3230 cally allocated memory blocks can be much larger than the total
3231 size of the dynamically allocated memory blocks.
3232 Note:
3235 As from ERTS 5.6.4, erlang:memory/0 requires that all
3236 erts_alloc(3) allocators are enabled (default behavior).
3237 Failure: notsup if an erts_alloc(3) allocator has been disabled.
3240 erlang:memory(Type :: memory_type()) -> integer() >= 0
3242 erlang:memory(TypeList :: [memory_type()]) ->
3244 [{memory_type(), integer() >= 0}]
3245 Types:
3247 memory_type() =
3249 total | processes | processes_used | system | atom |
3250 atom_used | binary | code | ets
3251 Returns the memory size in bytes allocated for memory of type
3253 Type. The argument can also be specified as a list of mem‐
3254 ory_type() atoms, in which case a corresponding list of {mem‐
3255 ory_type(), Size :: integer >= 0} tuples is returned.
3256 Note:
3258 As from ERTS 5.6.4, erlang:memory/1 requires that all
3259 erts_alloc(3) allocators are enabled (default behavior).
3260 Failures:
3263 badarg:
3265 If Type is not one of the memory types listed in the
3266 description of erlang:memory/0.
3267 badarg:
3269 If maximum is passed as Type and the emulator is not run in
3270 instrumented mode.
3271 notsup:
3273 If an erts_alloc(3) allocator has been disabled.
3274 See also erlang:memory/0.
3276 min(Term1, Term2) -> Minimum
3278 Types:
3280 Term1 = Term2 = Minimum = term()
3282 Returns the smallest of Term1 and Term2. If the terms are equal,
3284 Term1 is returned.
3285 module_loaded(Module) -> boolean()
3287 Types:
3289 Module = module()
3291 Returns true if the module Module is loaded, otherwise false. It
3293 does not attempt to load the module.
3294 Warning:
3296 This BIF is intended for the code server (see code(3)) and is
3297 not to be used elsewhere.
3298 monitor(Type :: process, Item :: monitor_process_identifier()) ->
3301 MonitorRef
3302 monitor(Type :: port, Item :: monitor_port_identifier()) ->
3304 MonitorRef
3305 monitor(Type :: time_offset, Item :: clock_service) -> MonitorRef
3307 Types:
3309 MonitorRef = reference()
3311 registered_name() = atom()
3312 registered_process_identifier() =
3313 registered_name() | {registered_name(), node()}
3314 monitor_process_identifier() =
3315 pid() | registered_process_identifier()
3316 monitor_port_identifier() = port() | registered_name()
3317 Sends a monitor request of type Type to the entity identified by
3319 Item. If the monitored entity does not exist or it changes moni‐
3320 tored state, the caller of monitor/2 is notified by a message on
3321 the following format:
3322 {Tag, MonitorRef, Type, Object, Info}
3324 Note:
3326 The monitor request is an asynchronous signal. That is, it takes
3327 time before the signal reaches its destination.
3328 Type can be one of the following atoms: process, port or
3331 time_offset.
3332 A process or port monitor is triggered only once, after that it
3334 is removed from both monitoring process and the monitored
3335 entity. Monitors are fired when the monitored process or port
3336 terminates, does not exist at the moment of creation, or if the
3337 connection to it is lost. If the connection to it is lost, we do
3338 not know if it still exists. The monitoring is also turned off
3339 when demonitor/1 is called.
3340 A process or port monitor by name resolves the RegisteredName to
3342 pid() or port() only once at the moment of monitor instantia‐
3343 tion, later changes to the name registration will not affect the
3344 existing monitor.
3345 When a process or port monitor is triggered, a 'DOWN' message is
3347 sent that has the following pattern:
3348 {'DOWN', MonitorRef, Type, Object, Info}
3350 In the monitor message MonitorRef and Type are the same as
3352 described earlier, and:
3353 Object:
3355 The monitored entity, which triggered the event. When moni‐
3356 toring a local process or port, Object will be equal to the
3357 pid() or port() that was being monitored. When monitoring
3358 process or port by name, Object will have format {Regis‐
3359 teredName, Node} where RegisteredName is the name which has
3360 been used with monitor/2 call and Node is local or remote
3361 node name (for ports monitored by name, Node is always local
3362 node name).
3363 Info:
3365 Either the exit reason of the process, noproc (process or
3366 port did not exist at the time of monitor creation), or
3367 noconnection (no connection to the node where the monitored
3368 process resides).
3369 Monitoring a process:
3371 Creates monitor between the current process and another
3372 process identified by Item, which can be a pid() (local or
3373 remote), an atom RegisteredName or a tuple {RegisteredName,
3374 Node} for a registered process, located elsewhere.
3375 Note:
3377 Before ERTS 10.0 (OTP 21.0), monitoring a process could fail
3378 with badarg if the monitored process resided on a primitive
3379 node (such as erl_interface or jinterface), where remote
3380 process monitoring is not implemented.
3381 Now, such a call to monitor will instead succeed and a monitor
3383 is created. But the monitor will only supervise the connec‐
3384 tion. That is, a {'DOWN', _, process, _, noconnection} is the
3385 only message that may be received, as the primitive node have
3386 no way of reporting the status of the monitored process.
3387 Monitoring a port:
3390 Creates monitor between the current process and a port iden‐
3391 tified by Item, which can be a port() (only local), an atom
3392 RegisteredName or a tuple {RegisteredName, Node} for a reg‐
3393 istered port, located on this node. Note, that attempt to
3394 monitor a remote port will result in badarg.
3395 Monitoring a time_offset:
3397 Monitors changes in time offset between Erlang monotonic
3398 time and Erlang system time. One valid Item exists in combi‐
3399 nation with the time_offset Type, namely the atom clock_ser‐
3400 vice. Notice that the atom clock_service is not the regis‐
3401 tered name of a process. In this case it serves as an iden‐
3402 tifier of the runtime system internal clock service at cur‐
3403 rent runtime system instance.
3404 The monitor is triggered when the time offset is changed.
3406 This either if the time offset value is changed, or if the
3407 offset is changed from preliminary to final during finaliza‐
3408 tion of the time offset when the single time warp mode is
3409 used. When a change from preliminary to final time offset is
3410 made, the monitor is triggered once regardless of whether
3411 the time offset value was changed or not.
3412 If the runtime system is in multi time warp mode, the time
3414 offset is changed when the runtime system detects that the
3415 OS system time has changed. The runtime system does, how‐
3416 ever, not detect this immediately when it occurs. A task
3417 checking the time offset is scheduled to execute at least
3418 once a minute, so under normal operation this is to be
3419 detected within a minute, but during heavy load it can take
3420 longer time.
3421 The monitor is not automatically removed after it has been
3423 triggered. That is, repeated changes of the time offset
3424 trigger the monitor repeatedly.
3425 When the monitor is triggered a 'CHANGE' message is sent to
3427 the monitoring process. A 'CHANGE' message has the following
3428 pattern:
3429 {'CHANGE', MonitorRef, Type, Item, NewTimeOffset}
3431 where MonitorRef, Type, and Item are the same as described
3433 above, and NewTimeOffset is the new time offset.
3434 When the 'CHANGE' message has been received you are guaran‐
3436 teed not to retrieve the old time offset when calling
3437 erlang:time_offset(). Notice that you can observe the change
3438 of the time offset when calling erlang:time_offset() before
3439 you get the 'CHANGE' message.
3440 Making several calls to monitor/2 for the same Item and/or Type
3442 is not an error; it results in as many independent monitoring
3443 instances.
3444 The monitor functionality is expected to be extended. That is,
3446 other Types and Items are expected to be supported in a future
3447 release.
3448 Note:
3450 If or when monitor/2 is extended, other possible values for Tag,
3451 Object, and Info in the monitor message will be introduced.
3452 monitor_node(Node, Flag) -> true
3455 Types:
3457 Node = node()
3459 Flag = boolean()
3460 Monitor the status of the node Node. If Flag is true, monitoring
3462 is turned on. If Flag is false, monitoring is turned off.
3463 Making several calls to monitor_node(Node, true) for the same
3465 Node is not an error; it results in as many independent monitor‐
3466 ing instances.
3467 If Node fails or does not exist, the message {nodedown, Node} is
3469 delivered to the process. If a process has made two calls to
3470 monitor_node(Node, true) and Node terminates, two nodedown mes‐
3471 sages are delivered to the process. If there is no connection to
3472 Node, an attempt is made to create one. If this fails, a node‐
3473 down message is delivered.
3474 Nodes connected through hidden connections can be monitored as
3476 any other nodes.
3477 Failure: badarg if the local node is not alive.
3479 erlang:monitor_node(Node, Flag, Options) -> true
3481 Types:
3483 Node = node()
3485 Flag = boolean()
3486 Options = [Option]
3487 Option = allow_passive_connect
3488 Behaves as monitor_node/2 except that it allows an extra option
3490 to be specified, namely allow_passive_connect. This option
3491 allows the BIF to wait the normal network connection time-out
3492 for the monitored node to connect itself, even if it cannot be
3493 actively connected from this node (that is, it is blocked). The
3494 state where this can be useful can only be achieved by using the
3495 Kernel option dist_auto_connect once. If that option is not
3496 used, option allow_passive_connect has no effect.
3497 Note:
3499 Option allow_passive_connect is used internally and is seldom
3500 needed in applications where the network topology and the Kernel
3501 options in effect are known in advance.
3502 Failure: badarg if the local node is not alive or the option
3505 list is malformed.
3506 erlang:monotonic_time() -> integer()
3508 Returns the current Erlang monotonic time in native time unit.
3510 This is a monotonically increasing time since some unspecified
3511 point in time.
3512 Note:
3514 This is a monotonically increasing time, but not a strictly
3515 monotonically increasing time. That is, consecutive calls to
3516 erlang:monotonic_time/0 can produce the same result.
3517 Different runtime system instances will use different unspeci‐
3519 fied points in time as base for their Erlang monotonic clocks.
3520 That is, it is pointless comparing monotonic times from differ‐
3521 ent runtime system instances. Different runtime system instances
3522 can also place this unspecified point in time different relative
3523 runtime system start. It can be placed in the future (time at
3524 start is a negative value), the past (time at start is a posi‐
3525 tive value), or the runtime system start (time at start is
3526 zero). The monotonic time at runtime system start can be
3527 retrieved by calling erlang:system_info(start_time).
3528 erlang:monotonic_time(Unit) -> integer()
3531 Types:
3533 Unit = time_unit()
3535 Returns the current Erlang monotonic time converted into the
3537 Unit passed as argument.
3538 Same as calling erlang:convert_time_unit(erlang:mono‐
3540 tonic_time(), native, Unit), however optimized for commonly used
3541 Units.
3542 erlang:nif_error(Reason) -> no_return()
3544 Types:
3546 Reason = term()
3548 Works exactly like error/1, but Dialyzer thinks that this BIF
3550 will return an arbitrary term. When used in a stub function for
3551 a NIF to generate an exception when the NIF library is not
3552 loaded, Dialyzer does not generate false warnings.
3553 erlang:nif_error(Reason, Args) -> no_return()
3555 Types:
3557 Reason = term()
3559 Args = [term()]
3560 Works exactly like error/2, but Dialyzer thinks that this BIF
3562 will return an arbitrary term. When used in a stub function for
3563 a NIF to generate an exception when the NIF library is not
3564 loaded, Dialyzer does not generate false warnings.
3565 node() -> Node
3567 Types:
3569 Node = node()
3571 Returns the name of the local node. If the node is not alive,
3573 nonode@nohost is returned instead.
3574 Allowed in guard tests.
3576 node(Arg) -> Node
3578 Types:
3580 Arg = pid() | port() | reference()
3582 Node = node()
3583 Returns the node where Arg originates. Arg can be a process
3585 identifier, a reference, or a port. If the local node is not
3586 alive, nonode@nohost is returned.
3587 Allowed in guard tests.
3589 nodes() -> Nodes
3591 Types:
3593 Nodes = [node()]
3595 Returns a list of all visible nodes in the system, except the
3597 local node. Same as nodes(visible).
3598 nodes(Arg) -> Nodes
3600 Types:
3602 Arg = NodeType | [NodeType]
3604 NodeType = visible | hidden | connected | this | known
3605 Nodes = [node()]
3606 Returns a list of nodes according to the argument specified. The
3608 returned result, when the argument is a list, is the list of
3609 nodes satisfying the disjunction(s) of the list elements.
3610 NodeTypes:
3612 visible:
3614 Nodes connected to this node through normal connections.
3615 hidden:
3617 Nodes connected to this node through hidden connections.
3618 connected:
3620 All nodes connected to this node.
3621 this:
3623 This node.
3624 known:
3626 Nodes that are known to this node. That is, connected nodes
3627 and nodes referred to by process identifiers, port identi‐
3628 fiers, and references located on this node. The set of known
3629 nodes is garbage collected. Notice that this garbage collec‐
3630 tion can be delayed. For more information, see erlang:sys‐
3631 tem_info(delayed_node_table_gc).
3632 Some equalities: [node()] = nodes(this), nodes(connected) =
3634 nodes([visible, hidden]), and nodes() = nodes(visible).
3635 now() -> Timestamp
3637 Types:
3639 Timestamp = timestamp()
3641 timestamp() =
3642 {MegaSecs :: integer() >= 0,
3643 Secs :: integer() >= 0,
3644 MicroSecs :: integer() >= 0}
3645 Warning:
3647 This function is deprecated. Do not use it.
3648 For more information, see section Time and Time Correction in
3650 the User's Guide. Specifically, section Dos and Dont's
3651 describes what to use instead of erlang:now/0.
3652 Returns the tuple {MegaSecs, Secs, MicroSecs}, which is the
3655 elapsed time since 00:00 GMT, January 1, 1970 (zero hour), if
3656 provided by the underlying OS. Otherwise some other point in
3657 time is chosen. It is also guaranteed that the following calls
3658 to this BIF return continuously increasing values. Hence, the
3659 return value from erlang:now/0 can be used to generate unique
3660 time stamps. If it is called in a tight loop on a fast machine,
3661 the time of the node can become skewed.
3662 Can only be used to check the local time of day if the time-zone
3664 information of the underlying OS is properly configured.
3665 open_port(PortName, PortSettings) -> port()
3667 Types:
3669 PortName =
3671 {spawn, Command :: string() | binary()} |
3672 {spawn_driver, Command :: string() | binary()} |
3673 {spawn_executable, FileName :: file:name()} |
3674 {fd, In :: integer() >= 0, Out :: integer() >= 0}
3675 PortSettings = [Opt]
3676 Opt =
3677 {packet, N :: 1 | 2 | 4} |
3678 stream |
3679 {line, L :: integer() >= 0} |
3680 {cd, Dir :: string() | binary()} |
3681 {env,
3682 Env ::
3683 [{Name :: os:env_var_name(),
3684 Val :: os:env_var_value() | false}]} |
3685 {args, [string() | binary()]} |
3686 {arg0, string() | binary()} |
3687 exit_status | use_stdio | nouse_stdio | stderr_to_stdout
3688 |
3689 in | out | binary | eof |
3690 {parallelism, Boolean :: boolean()} |
3691 hide
3692 Returns a port identifier as the result of opening a new Erlang
3694 port. A port can be seen as an external Erlang process.
3695 The name of the executable as well as the arguments specifed in
3697 cd, env, args, and arg0 are subject to Unicode filename transla‐
3698 tion if the system is running in Unicode filename mode. To avoid
3699 translation or to force, for example UTF-8, supply the exe‐
3700 cutable and/or arguments as a binary in the correct encoding.
3701 For details, see the module file(3), the function
3702 file:native_name_encoding/0 in Kernel, and the Using Unicode in
3703 Erlang User's Guide.
3704 Note:
3706 The characters in the name (if specified as a list) can only be
3707 > 255 if the Erlang virtual machine is started in Unicode file‐
3708 name translation mode. Otherwise the name of the executable is
3709 limited to the ISO Latin-1 character set.
3710 PortNames:
3713 {spawn, Command}:
3715 Starts an external program. Command is the name of the
3716 external program to be run. Command runs outside the Erlang
3717 work space unless an Erlang driver with the name Command is
3718 found. If found, that driver is started. A driver runs in
3719 the Erlang work space, which means that it is linked with
3720 the Erlang runtime system.
3721 For external programs, PATH is searched (or an equivalent
3723 method is used to find programs, depending on the OS). This
3724 is done by invoking the shell on certain platforms. The
3725 first space-separated token of the command is considered as
3726 the name of the executable (or driver). This (among other
3727 things) makes this option unsuitable for running programs
3728 with spaces in filenames or directory names. If spaces in
3729 executable filenames are desired, use {spawn_executable,
3730 Command} instead.
3731 {spawn_driver, Command}:
3733 Works like {spawn, Command}, but demands the first (space-
3734 separated) token of the command to be the name of a loaded
3735 driver. If no driver with that name is loaded, a badarg
3736 error is raised.
3737 {spawn_executable, FileName}:
3739 Works like {spawn, FileName}, but only runs external exe‐
3740 cutables. FileName in its whole is used as the name of the
3741 executable, including any spaces. If arguments are to be
3742 passed, the PortSettings args and arg0 can be used.
3743 The shell is usually not invoked to start the program, it is
3745 executed directly. PATH (or equivalent) is not searched. To
3746 find a program in PATH to execute, use os:find_executable/1.
3747 Only if a shell script or .bat file is executed, the appro‐
3749 priate command interpreter is invoked implicitly, but there
3750 is still no command-argument expansion or implicit PATH
3751 search.
3752 If FileName cannot be run, an error exception is raised,
3754 with the POSIX error code as the reason. The error reason
3755 can differ between OSs. Typically the error enoent is raised
3756 when an attempt is made to run a program that is not found
3757 and eacces is raised when the specified file is not exe‐
3758 cutable.
3759 {fd, In, Out}:
3761 Allows an Erlang process to access any currently opened file
3762 descriptors used by Erlang. The file descriptor In can be
3763 used for standard input, and the file descriptor Out for
3764 standard output. It is only used for various servers in the
3765 Erlang OS (shell and user). Hence, its use is limited.
3766 PortSettings is a list of settings for the port. The valid set‐
3768 tings are as follows:
3769 {packet, N}:
3771 Messages are preceded by their length, sent in N bytes, with
3772 the most significant byte first. The valid values for N are
3773 1, 2, and 4.
3774 stream:
3776 Output messages are sent without packet lengths. A user-
3777 defined protocol must be used between the Erlang process and
3778 the external object.
3779 {line, L}:
3781 Messages are delivered on a per line basis. Each line
3782 (delimited by the OS-dependent newline sequence) is deliv‐
3783 ered in a single message. The message data format is {Flag,
3784 Line}, where Flag is eol or noeol, and Line is the data
3785 delivered (without the newline sequence).
3786 L specifies the maximum line length in bytes. Lines longer
3788 than this are delivered in more than one message, with Flag
3789 set to noeol for all but the last message. If end of file is
3790 encountered anywhere else than immediately following a new‐
3791 line sequence, the last line is also delivered with Flag set
3792 to noeol. Otherwise lines are delivered with Flag set to
3793 eol.
3794 The {packet, N} and {line, L} settings are mutually exclu‐
3796 sive.
3797 {cd, Dir}:
3799 Only valid for {spawn, Command} and {spawn_executable, File‐
3800 Name}. The external program starts using Dir as its working
3801 directory. Dir must be a string.
3802 {env, Env}:
3804 Types:
3805 Name = os:env_var_name()
3806 Val = os:env_var_value() | false
3807 Env = [{Name, Val}]
3808 Only valid for {spawn, Command}, and {spawn_executable,
3810 FileName}. The environment of the started process is
3811 extended using the environment specifications in Env.
3812 Env is to be a list of tuples {Name, Val}, where Name is the
3814 name of an environment variable, and Val is the value it is
3815 to have in the spawned port process. Both Name and Val must
3816 be strings. The one exception is Val being the atom false
3817 (in analogy with os:getenv/1, which removes the environment
3818 variable.
3819 For information about encoding requirements, see documenta‐
3821 tion of the types for Name and Val.
3822 {args, [ string() | binary() ]}:
3824 Only valid for {spawn_executable, FileName} and specifies
3825 arguments to the executable. Each argument is specified as a
3826 separate string and (on Unix) eventually ends up as one ele‐
3827 ment each in the argument vector. On other platforms, a sim‐
3828 ilar behavior is mimicked.
3829 The arguments are not expanded by the shell before they are
3831 supplied to the executable. Most notably this means that
3832 file wildcard expansion does not occur. To expand wildcards
3833 for the arguments, use filelib:wildcard/1. Notice that even
3834 if the program is a Unix shell script, meaning that the
3835 shell ultimately is invoked, wildcard expansion does not
3836 occur, and the script is provided with the untouched argu‐
3837 ments. On Windows, wildcard expansion is always up to the
3838 program itself, therefore this is not an issue.
3839 The executable name (also known as argv[0]) is not to be
3841 specified in this list. The proper executable name is auto‐
3842 matically used as argv[0], where applicable.
3843 If you explicitly want to set the program name in the argu‐
3845 ment vector, option arg0 can be used.
3846 {arg0, string() | binary()}:
3848 Only valid for {spawn_executable, FileName} and explicitly
3849 specifies the program name argument when running an exe‐
3850 cutable. This can in some circumstances, on some OSs, be
3851 desirable. How the program responds to this is highly sys‐
3852 tem-dependent and no specific effect is guaranteed.
3853 exit_status:
3855 Only valid for {spawn, Command}, where Command refers to an
3856 external program, and for {spawn_executable, FileName}.
3857 When the external process connected to the port exits, a
3859 message of the form {Port,{exit_status,Status}} is sent to
3860 the connected process, where Status is the exit status of
3861 the external process. If the program aborts on Unix, the
3862 same convention is used as the shells do (that is, 128+sig‐
3863 nal).
3864 If option eof is specified also, the messages eof and
3866 exit_status appear in an unspecified order.
3867 If the port program closes its stdout without exiting,
3869 option exit_status does not work.
3870 use_stdio:
3872 Only valid for {spawn, Command} and {spawn_executable, File‐
3873 Name}. It allows the standard input and output (file
3874 descriptors 0 and 1) of the spawned (Unix) process for com‐
3875 munication with Erlang.
3876 nouse_stdio:
3878 The opposite of use_stdio. It uses file descriptors 3 and 4
3879 for communication with Erlang.
3880 stderr_to_stdout:
3882 Affects ports to external programs. The executed program
3883 gets its standard error file redirected to its standard out‐
3884 put file. stderr_to_stdout and nouse_stdio are mutually
3885 exclusive.
3886 overlapped_io:
3888 Affects ports to external programs on Windows only. The
3889 standard input and standard output handles of the port pro‐
3890 gram are, if this option is supplied, opened with flag
3891 FILE_FLAG_OVERLAPPED, so that the port program can (and
3892 must) do overlapped I/O on its standard handles. This is not
3893 normally the case for simple port programs, but an option of
3894 value for the experienced Windows programmer. On all other
3895 platforms, this option is silently discarded.
3896 in:
3898 The port can only be used for input.
3899 out:
3901 The port can only be used for output.
3902 binary:
3904 All I/O from the port is binary data objects as opposed to
3905 lists of bytes.
3906 eof:
3908 The port is not closed at the end of the file and does not
3909 produce an exit signal. Instead, it remains open and a
3910 {Port, eof} message is sent to the process holding the port.
3911 hide:
3913 When running on Windows, suppresses creation of a new con‐
3914 sole window when spawning the port program. (This option has
3915 no effect on other platforms.)
3916 {parallelism, Boolean}:
3918 Sets scheduler hint for port parallelism. If set to true,
3921 the virtual machine schedules port tasks; when doing so, it
3922 improves parallelism in the system. If set to false, the
3923 virtual machine tries to perform port tasks immediately,
3924 improving latency at the expense of parallelism. The default
3925 can be set at system startup by passing command-line argu‐
3926 ment +spp to erl(1).
3927 Default is stream for all port types and use_stdio for spawned
3929 ports.
3930 Failure: if the port cannot be opened, the exit reason is
3932 badarg, system_limit, or the POSIX error code that most closely
3933 describes the error, or einval if no POSIX code is appropriate:
3934 badarg:
3936 Bad input arguments to open_port.
3937 system_limit:
3939 All available ports in the Erlang emulator are in use.
3940 enomem:
3942 Not enough memory to create the port.
3943 eagain:
3945 No more available OS processes.
3946 enametoolong:
3948 Too long external command.
3949 emfile:
3951 No more available file descriptors (for the OS process that
3952 the Erlang emulator runs in).
3953 enfile:
3955 Full file table (for the entire OS).
3956 eacces:
3958 Command specified in {spawn_executable, Command} does not
3959 point out an executable file.
3960 enoent:
3962 FileName specified in {spawn_executable, FileName} does not
3963 point out an existing file.
3964 During use of a port opened using {spawn, Name}, {spawn_driver,
3966 Name}, or {spawn_executable, Name}, errors arising when sending
3967 messages to it are reported to the owning process using signals
3968 of the form {'EXIT', Port, PosixCode}. For the possible values
3969 of PosixCode, see file(3).
3970 The maximum number of ports that can be open at the same time
3972 can be configured by passing command-line flag +Q to erl(1).
3973 erlang:phash(Term, Range) -> Hash
3975 Types:
3977 Term = term()
3979 Range = Hash = integer() >= 1
3980 Range = 1..2^32, Hash = 1..Range
3981 Portable hash function that gives the same hash for the same
3983 Erlang term regardless of machine architecture and ERTS version
3984 (the BIF was introduced in ERTS 4.9.1.1). The function returns a
3985 hash value for Term within the range 1..Range. The maximum value
3986 for Range is 2^32.
3987 erlang:phash2(Term) -> Hash
3989 erlang:phash2(Term, Range) -> Hash
3991 Types:
3993 Term = term()
3995 Range = integer() >= 1
3996 1..2^32
3997 Hash = integer() >= 0
3998 0..Range-1
3999 Portable hash function that gives the same hash for the same
4001 Erlang term regardless of machine architecture and ERTS version
4002 (the BIF was introduced in ERTS 5.2). The function returns a
4003 hash value for Term within the range 0..Range-1. The maximum
4004 value for Range is 2^32. When without argument Range, a value in
4005 the range 0..2^27-1 is returned.
4006 This BIF is always to be used for hashing terms. It distributes
4008 small integers better than phash/2, and it is faster for bignums
4009 and binaries.
4010 Notice that the range 0..Range-1 is different from the range of
4012 phash/2, which is 1..Range.
4013 pid_to_list(Pid) -> string()
4015 Types:
4017 Pid = pid()
4019 Returns a string corresponding to the text representation of
4021 Pid.
4022 erlang:port_call(Port, Operation, Data) -> term()
4024 Types:
4026 Port = port() | atom()
4028 Operation = integer()
4029 Data = term()
4030 Performs a synchronous call to a port. The meaning of Operation
4032 and Data depends on the port, that is, on the port driver. Not
4033 all port drivers support this feature.
4034 Port is a port identifier, referring to a driver.
4036 Operation is an integer, which is passed on to the driver.
4038 Data is any Erlang term. This data is converted to binary term
4040 format and sent to the port.
4041 Returns a term from the driver. The meaning of the returned data
4043 also depends on the port driver.
4044 Failures:
4046 badarg:
4048 If Port is not an identifier of an open port, or the regis‐
4049 tered name of an open port. If the calling process was pre‐
4050 viously linked to the closed port, identified by Port, the
4051 exit signal from the port is guaranteed to be delivered
4052 before this badarg exception occurs.
4053 badarg:
4055 If Operation does not fit in a 32-bit integer.
4056 badarg:
4058 If the port driver does not support synchronous control
4059 operations.
4060 badarg:
4062 If the port driver so decides for any reason (probably some‐
4063 thing wrong with Operation or Data).
4064 Warning:
4066 Do not call port_call with an unknown Port identifier and
4067 expect badarg exception. Any undefined behavior is possible
4068 (including node crash) depending on how the port driver inter‐
4069 prets the supplied arguments.
4070 port_close(Port) -> true
4073 Types:
4075 Port = port() | atom()
4077 Closes an open port. Roughly the same as Port ! {self(), close}
4079 except for the error behavior (see below), being synchronous,
4080 and that the port does not reply with {Port, closed}. Any
4081 process can close a port with port_close/1, not only the port
4082 owner (the connected process). If the calling process is linked
4083 to the port identified by Port, the exit signal from the port is
4084 guaranteed to be delivered before port_close/1 returns.
4085 For comparison: Port ! {self(), close} only fails with badarg if
4087 Port does not refer to a port or a process. If Port is a closed
4088 port, nothing happens. If Port is an open port and the calling
4089 process is the port owner, the port replies with {Port, closed}
4090 when all buffers have been flushed and the port really closes.
4091 If the calling process is not the port owner, the port owner
4092 fails with badsig.
4093 Notice that any process can close a port using Port ! {Por‐
4095 tOwner, close} as if it itself was the port owner, but the reply
4096 always goes to the port owner.
4097 As from Erlang/OTP R16, Port ! {PortOwner, close} is truly asyn‐
4099 chronous. Notice that this operation has always been documented
4100 as an asynchronous operation, while the underlying implementa‐
4101 tion has been synchronous. port_close/1 is however still fully
4102 synchronous because of its error behavior.
4103 Failure: badarg if Port is not an identifier of an open port, or
4105 the registered name of an open port. If the calling process was
4106 previously linked to the closed port, identified by Port, the
4107 exit signal from the port is guaranteed to be delivered before
4108 this badarg exception occurs.
4109 port_command(Port, Data) -> true
4111 Types:
4113 Port = port() | atom()
4115 Data = iodata()
4116 Sends data to a port. Same as Port ! {PortOwner, {command,
4118 Data}} except for the error behavior and being synchronous (see
4119 below). Any process can send data to a port with port_command/2,
4120 not only the port owner (the connected process).
4121 For comparison: Port ! {PortOwner, {command, Data}} only fails
4123 with badarg if Port does not refer to a port or a process. If
4124 Port is a closed port, the data message disappears without a
4125 sound. If Port is open and the calling process is not the port
4126 owner, the port owner fails with badsig. The port owner fails
4127 with badsig also if Data is an invalid I/O list.
4128 Notice that any process can send to a port using Port ! {Por‐
4130 tOwner, {command, Data}} as if it itself was the port owner.
4131 If the port is busy, the calling process is suspended until the
4133 port is not busy any more.
4134 As from Erlang/OTP R16, Port ! {PortOwner, {command, Data}} is
4136 truly asynchronous. Notice that this operation has always been
4137 documented as an asynchronous operation, while the underlying
4138 implementation has been synchronous. port_command/2 is however
4139 still fully synchronous because of its error behavior.
4140 Failures:
4142 badarg:
4144 If Port is not an identifier of an open port, or the regis‐
4145 tered name of an open port. If the calling process was pre‐
4146 viously linked to the closed port, identified by Port, the
4147 exit signal from the port is guaranteed to be delivered
4148 before this badarg exception occurs.
4149 badarg:
4151 If Data is an invalid I/O list.
4152 Warning:
4154 Do not send data to an unknown port. Any undefined behavior is
4155 possible (including node crash) depending on how the port driver
4156 interprets the data.
4157 port_command(Port, Data, OptionList) -> boolean()
4160 Types:
4162 Port = port() | atom()
4164 Data = iodata()
4165 Option = force | nosuspend
4166 OptionList = [Option]
4167 Sends data to a port. port_command(Port, Data, []) equals
4169 port_command(Port, Data).
4170 If the port command is aborted, false is returned, otherwise
4172 true.
4173 If the port is busy, the calling process is suspended until the
4175 port is not busy anymore.
4176 Options:
4178 force:
4180 The calling process is not suspended if the port is busy,
4181 instead the port command is forced through. The call fails
4182 with a notsup exception if the driver of the port does not
4183 support this. For more information, see driver flag
4184 ![CDATA[ERL_DRV_FLAG_SOFT_BUSY]].
4185 nosuspend:
4187 The calling process is not suspended if the port is busy,
4188 instead the port command is aborted and false is returned.
4189 Note:
4191 More options can be added in a future release.
4192 Failures:
4195 badarg:
4197 If Port is not an identifier of an open port, or the regis‐
4198 tered name of an open port. If the calling process was pre‐
4199 viously linked to the closed port, identified by Port, the
4200 exit signal from the port is guaranteed to be delivered
4201 before this badarg exception occurs.
4202 badarg:
4204 If Data is an invalid I/O list.
4205 badarg:
4207 If OptionList is an invalid option list.
4208 notsup:
4210 If option force has been passed, but the driver of the port
4211 does not allow forcing through a busy port.
4212 Warning:
4214 Do not send data to an unknown port. Any undefined behavior is
4215 possible (including node crash) depending on how the port driver
4216 interprets the data.
4217 port_connect(Port, Pid) -> true
4220 Types:
4222 Port = port() | atom()
4224 Pid = pid()
4225 Sets the port owner (the connected port) to Pid. Roughly the
4227 same as Port ! {Owner, {connect, Pid}} except for the following:
4228 * The error behavior differs, see below.
4230 * The port does not reply with {Port,connected}.
4232 * port_connect/1 is synchronous, see below.
4234 * The new port owner gets linked to the port.
4236 The old port owner stays linked to the port and must call
4238 unlink(Port) if this is not desired. Any process can set the
4239 port owner to be any process with port_connect/2.
4240 For comparison: Port ! {self(), {connect, Pid}} only fails with
4242 badarg if Port does not refer to a port or a process. If Port is
4243 a closed port, nothing happens. If Port is an open port and the
4244 calling process is the port owner, the port replies with {Port,
4245 connected} to the old port owner. Notice that the old port owner
4246 is still linked to the port, while the new is not. If Port is an
4247 open port and the calling process is not the port owner, the
4248 port owner fails with badsig. The port owner fails with badsig
4249 also if Pid is not an existing local process identifier.
4250 Notice that any process can set the port owner using Port !
4252 {PortOwner, {connect, Pid}} as if it itself was the port owner,
4253 but the reply always goes to the port owner.
4254 As from Erlang/OTP R16, Port ! {PortOwner, {connect, Pid}} is
4256 truly asynchronous. Notice that this operation has always been
4257 documented as an asynchronous operation, while the underlying
4258 implementation has been synchronous. port_connect/2 is however
4259 still fully synchronous because of its error behavior.
4260 Failures:
4262 badarg:
4264 If Port is not an identifier of an open port, or the regis‐
4265 tered name of an open port. If the calling process was pre‐
4266 viously linked to the closed port, identified by Port, the
4267 exit signal from the port is guaranteed to be delivered
4268 before this badarg exception occurs.
4269 badarg:
4271 If the process identified by Pid is not an existing local
4272 process.
4273 port_control(Port, Operation, Data) -> iodata() | binary()
4275 Types:
4277 Port = port() | atom()
4279 Operation = integer()
4280 Data = iodata()
4281 Performs a synchronous control operation on a port. The meaning
4283 of Operation and Data depends on the port, that is, on the port
4284 driver. Not all port drivers support this control feature.
4285 Returns a list of integers in the range 0..255, or a binary,
4287 depending on the port driver. The meaning of the returned data
4288 also depends on the port driver.
4289 Failures:
4291 badarg:
4293 If Port is not an open port or the registered name of an
4294 open port.
4295 badarg:
4297 If Operation cannot fit in a 32-bit integer.
4298 badarg:
4300 If the port driver does not support synchronous control
4301 operations.
4302 badarg:
4304 If the port driver so decides for any reason (probably
4305 something wrong with Operation or Data).
4306 Warning:
4308 Do not call port_control/3 with an unknown Port identifier and
4309 expect badarg exception. Any undefined behavior is possible
4310 (including node crash) depending on how the port driver inter‐
4311 prets the supplied arguments.
4312 erlang:port_info(Port) -> Result
4315 Types:
4317 Port = port() | atom()
4319 ResultItem =
4320 {registered_name, RegisteredName :: atom()} |
4321 {id, Index :: integer() >= 0} |
4322 {connected, Pid :: pid()} |
4323 {links, Pids :: [pid()]} |
4324 {name, String :: string()} |
4325 {input, Bytes :: integer() >= 0} |
4326 {output, Bytes :: integer() >= 0} |
4327 {os_pid, OsPid :: integer() >= 0 | undefined}
4328 Result = [ResultItem] | undefined
4329 Returns a list containing tuples with information about Port, or
4331 undefined if the port is not open. The order of the tuples is
4332 undefined, and all the tuples are not mandatory. If the port is
4333 closed and the calling process was previously linked to the
4334 port, the exit signal from the port is guaranteed to be deliv‐
4335 ered before port_info/1 returns undefined.
4336 The result contains information about the following Items:
4338 * registered_name (if the port has a registered name)
4340 * id
4342 * connected
4344 * links
4346 * name
4348 * input
4350 * output
4352 For more information about the different Items, see port_info/2.
4354 Failure: badarg if Port is not a local port identifier, or an
4356 atom.
4357 erlang:port_info(Port, Item :: connected) ->
4359 {connected, Pid} | undefined
4360 Types:
4362 Port = port() | atom()
4364 Pid = pid()
4365 Pid is the process identifier of the process connected to the
4367 port.
4368 If the port identified by Port is not open, undefined is
4370 returned. If the port is closed and the calling process was pre‐
4371 viously linked to the port, the exit signal from the port is
4372 guaranteed to be delivered before port_info/2 returns undefined.
4373 Failure: badarg if Port is not a local port identifier, or an
4375 atom.
4376 erlang:port_info(Port, Item :: id) -> {id, Index} | undefined
4378 Types:
4380 Port = port() | atom()
4382 Index = integer() >= 0
4383 Index is the internal index of the port. This index can be used
4385 to separate ports.
4386 If the port identified by Port is not open, undefined is
4388 returned. If the port is closed and the calling process was pre‐
4389 viously linked to the port, the exit signal from the port is
4390 guaranteed to be delivered before port_info/2 returns undefined.
4391 Failure: badarg if Port is not a local port identifier, or an
4393 atom.
4394 erlang:port_info(Port, Item :: input) ->
4396 {input, Bytes} | undefined
4397 Types:
4399 Port = port() | atom()
4401 Bytes = integer() >= 0
4402 Bytes is the total number of bytes read from the port.
4404 If the port identified by Port is not open, undefined is
4406 returned. If the port is closed and the calling process was pre‐
4407 viously linked to the port, the exit signal from the port is
4408 guaranteed to be delivered before port_info/2 returns undefined.
4409 Failure: badarg if Port is not a local port identifier, or an
4411 atom.
4412 erlang:port_info(Port, Item :: links) -> {links, Pids} | undefined
4414 Types:
4416 Port = port() | atom()
4418 Pids = [pid()]
4419 Pids is a list of the process identifiers of the processes that
4421 the port is linked to.
4422 If the port identified by Port is not open, undefined is
4424 returned. If the port is closed and the calling process was pre‐
4425 viously linked to the port, the exit signal from the port is
4426 guaranteed to be delivered before port_info/2 returns undefined.
4427 Failure: badarg if Port is not a local port identifier, or an
4429 atom.
4430 erlang:port_info(Port, Item :: locking) ->
4432 {locking, Locking} | undefined
4433 Types:
4435 Port = port() | atom()
4437 Locking = false | port_level | driver_level
4438 Locking is one of the following:
4440 * port_level (port-specific locking)
4442 * driver_level (driver-specific locking)
4444 Notice that these results are highly implementation-specific and
4446 can change in a future release.
4447 If the port identified by Port is not open, undefined is
4449 returned. If the port is closed and the calling process was pre‐
4450 viously linked to the port, the exit signal from the port is
4451 guaranteed to be delivered before port_info/2 returns undefined.
4452 Failure: badarg if Port is not a local port identifier, or an
4454 atom.
4455 erlang:port_info(Port, Item :: memory) ->
4457 {memory, Bytes} | undefined
4458 Types:
4460 Port = port() | atom()
4462 Bytes = integer() >= 0
4463 Bytes is the total number of bytes allocated for this port by
4465 the runtime system. The port itself can have allocated memory
4466 that is not included in Bytes.
4467 If the port identified by Port is not open, undefined is
4469 returned. If the port is closed and the calling process was pre‐
4470 viously linked to the port, the exit signal from the port is
4471 guaranteed to be delivered before port_info/2 returns undefined.
4472 Failure: badarg if Port is not a local port identifier, or an
4474 atom.
4475 erlang:port_info(Port, Item :: monitors) ->
4477 {monitors, Monitors} | undefined
4478 Types:
4480 Port = port() | atom()
4482 Monitors = [{process, pid()}]
4483 Monitors represent processes monitored by this port.
4485 If the port identified by Port is not open, undefined is
4487 returned. If the port is closed and the calling process was pre‐
4488 viously linked to the port, the exit signal from the port is
4489 guaranteed to be delivered before port_info/2 returns undefined.
4490 Failure: badarg if Port is not a local port identifier, or an
4492 atom.
4493 erlang:port_info(Port, Item :: monitored_by) ->
4495 {monitored_by, MonitoredBy} | undefined
4496 Types:
4498 Port = port() | atom()
4500 MonitoredBy = [pid()]
4501 Returns list of pids that are monitoring given port at the
4503 moment.
4504 If the port identified by Port is not open, undefined is
4506 returned. If the port is closed and the calling process was pre‐
4507 viously linked to the port, the exit signal from the port is
4508 guaranteed to be delivered before port_info/2 returns undefined.
4509 Failure: badarg if Port is not a local port identifier, or an
4511 atom.
4512 erlang:port_info(Port, Item :: name) -> {name, Name} | undefined
4514 Types:
4516 Port = port() | atom()
4518 Name = string()
4519 Name is the command name set by open_port/2.
4521 If the port identified by Port is not open, undefined is
4523 returned. If the port is closed and the calling process was pre‐
4524 viously linked to the port, the exit signal from the port is
4525 guaranteed to be delivered before port_info/2 returns undefined.
4526 Failure: badarg if Port is not a local port identifier, or an
4528 atom.
4529 erlang:port_info(Port, Item :: os_pid) ->
4531 {os_pid, OsPid} | undefined
4532 Types:
4534 Port = port() | atom()
4536 OsPid = integer() >= 0 | undefined
4537 OsPid is the process identifier (or equivalent) of an OS process
4539 created with open_port({spawn | spawn_executable, Command},
4540 Options). If the port is not the result of spawning an OS
4541 process, the value is undefined.
4542 If the port identified by Port is not open, undefined is
4544 returned. If the port is closed and the calling process was pre‐
4545 viously linked to the port, the exit signal from the port is
4546 guaranteed to be delivered before port_info/2 returns undefined.
4547 Failure: badarg if Port is not a local port identifier, or an
4549 atom.
4550 erlang:port_info(Port, Item :: output) ->
4552 {output, Bytes} | undefined
4553 Types:
4555 Port = port() | atom()
4557 Bytes = integer() >= 0
4558 Bytes is the total number of bytes written to the port from
4560 Erlang processes using port_command/2, port_command/3, or Port !
4561 {Owner, {command, Data}.
4562 If the port identified by Port is not open, undefined is
4564 returned. If the port is closed and the calling process was pre‐
4565 viously linked to the port, the exit signal from the port is
4566 guaranteed to be delivered before port_info/2 returns undefined.
4567 Failure: badarg if Port is not a local port identifier, or an
4569 atom.
4570 erlang:port_info(Port, Item :: parallelism) ->
4572 {parallelism, Boolean} | undefined
4573 Types:
4575 Port = port() | atom()
4577 Boolean = boolean()
4578 Boolean corresponds to the port parallelism hint used by this
4580 port. For more information, see option parallelism of
4581 open_port/2.
4582 erlang:port_info(Port, Item :: queue_size) ->
4584 {queue_size, Bytes} | undefined
4585 Types:
4587 Port = port() | atom()
4589 Bytes = integer() >= 0
4590 Bytes is the total number of bytes queued by the port using the
4592 ERTS driver queue implementation.
4593 If the port identified by Port is not open, undefined is
4595 returned. If the port is closed and the calling process was pre‐
4596 viously linked to the port, the exit signal from the port is
4597 guaranteed to be delivered before port_info/2 returns undefined.
4598 Failure: badarg if Port is not a local port identifier, or an
4600 atom.
4601 erlang:port_info(Port, Item :: registered_name) ->
4603 {registered_name, RegisteredName} |
4604 [] | undefined
4605 Types:
4607 Port = port() | atom()
4609 RegisteredName = atom()
4610 RegisteredName is the registered name of the port. If the port
4612 has no registered name, [] is returned.
4613 If the port identified by Port is not open, undefined is
4615 returned. If the port is closed and the calling process was pre‐
4616 viously linked to the port, the exit signal from the port is
4617 guaranteed to be delivered before port_info/2 returns undefined.
4618 Failure: badarg if Port is not a local port identifier, or an
4620 atom.
4621 port_to_list(Port) -> string()
4623 Types:
4625 Port = port()
4627 Returns a string corresponding to the text representation of the
4629 port identifier Port.
4630 erlang:ports() -> [port()]
4632 Returns a list of port identifiers corresponding to all the
4634 ports existing on the local node.
4635 Notice that an exiting port exists, but is not open.
4637 pre_loaded() -> [module()]
4639 Returns a list of Erlang modules that are preloaded in the sys‐
4641 tem. As all loading of code is done through the file system, the
4642 file system must have been loaded previously. Hence, at least
4643 the module init must be preloaded.
4644 erlang:process_display(Pid, Type) -> true
4646 Types:
4648 Pid = pid()
4650 Type = backtrace
4651 Writes information about the local process Pid on standard
4653 error. The only allowed value for the atom Type is backtrace,
4654 which shows the contents of the call stack, including informa‐
4655 tion about the call chain, with the current function printed
4656 first. The format of the output is not further defined.
4657 process_flag(Flag :: trap_exit, Boolean) -> OldBoolean
4659 Types:
4661 Boolean = OldBoolean = boolean()
4663 When trap_exit is set to true, exit signals arriving to a
4665 process are converted to {'EXIT', From, Reason} messages, which
4666 can be received as ordinary messages. If trap_exit is set to
4667 false, the process exits if it receives an exit signal other
4668 than normal and the exit signal is propagated to its linked pro‐
4669 cesses. Application processes are normally not to trap exits.
4670 Returns the old value of the flag.
4672 See also exit/2.
4674 process_flag(Flag :: error_handler, Module) -> OldModule
4676 Types:
4678 Module = OldModule = atom()
4680 Used by a process to redefine the error handler for undefined
4682 function calls and undefined registered processes. Inexperienced
4683 users are not to use this flag, as code auto-loading depends on
4684 the correct operation of the error handling module.
4685 Returns the old value of the flag.
4687 process_flag(Flag :: min_heap_size, MinHeapSize) -> OldMinHeapSize
4689 Types:
4691 MinHeapSize = OldMinHeapSize = integer() >= 0
4693 Changes the minimum heap size for the calling process.
4695 Returns the old value of the flag.
4697 process_flag(Flag :: min_bin_vheap_size, MinBinVHeapSize) ->
4699 OldMinBinVHeapSize
4700 Types:
4702 MinBinVHeapSize = OldMinBinVHeapSize = integer() >= 0
4704 Changes the minimum binary virtual heap size for the calling
4706 process.
4707 Returns the old value of the flag.
4709 process_flag(Flag :: max_heap_size, MaxHeapSize) -> OldMaxHeapSize
4711 Types:
4713 MaxHeapSize = OldMaxHeapSize = max_heap_size()
4715 max_heap_size() =
4716 integer() >= 0 |
4717 #{size => integer() >= 0,
4718 kill => boolean(),
4719 error_logger => boolean()}
4720 This flag sets the maximum heap size for the calling process. If
4722 MaxHeapSize is an integer, the system default values for kill
4723 and error_logger are used.
4724 size:
4726 The maximum size in words of the process. If set to zero,
4727 the heap size limit is disabled. badarg is be thrown if the
4728 value is smaller than min_heap_size. The size check is only
4729 done when a garbage collection is triggered.
4730 size is the entire heap of the process when garbage collec‐
4732 tion is triggered. This includes all generational heaps, the
4733 process stack, any messages that are considered to be part
4734 of the heap, and any extra memory that the garbage collector
4735 needs during collection.
4736 size is the same as can be retrieved using
4738 erlang:process_info(Pid, total_heap_size), or by adding
4739 heap_block_size, old_heap_block_size and mbuf_size from
4740 erlang:process_info(Pid, garbage_collection_info).
4741 kill:
4743 When set to true, the runtime system sends an untrappable
4744 exit signal with reason kill to the process if the maximum
4745 heap size is reached. The garbage collection that triggered
4746 the kill is not completed, instead the process exits as soon
4747 as possible. When set to false, no exit signal is sent to
4748 the process, instead it continues executing.
4749 If kill is not defined in the map, the system default will
4751 be used. The default system default is true. It can be
4752 changed by either option +hmaxk in erl(1), or erlang:sys‐
4753 tem_flag(max_heap_size, MaxHeapSize).
4754 error_logger:
4756 When set to true, the runtime system logs an error event via
4757 logger, containing details about the process when the maxi‐
4758 mum heap size is reached. One log event is sent each time
4759 the limit is reached.
4760 If error_logger is not defined in the map, the system
4762 default is used. The default system default is true. It can
4763 be changed by either the option +hmaxel int erl(1), or
4764 erlang:system_flag(max_heap_size, MaxHeapSize).
4765 The heap size of a process is quite hard to predict, especially
4767 the amount of memory that is used during the garbage collection.
4768 When contemplating using this option, it is recommended to first
4769 run it in production with kill set to false and inspect the log
4770 events to see what the normal peak sizes of the processes in the
4771 system is and then tune the value accordingly.
4772 process_flag(Flag :: message_queue_data, MQD) -> OldMQD
4774 Types:
4776 MQD = OldMQD = message_queue_data()
4778 message_queue_data() = off_heap | on_heap
4779 This flag determines how messages in the message queue are
4781 stored, as follows:
4782 off_heap:
4784 All messages in the message queue will be stored outside of
4785 the process heap. This implies that no messages in the mes‐
4786 sage queue will be part of a garbage collection of the
4787 process.
4788 on_heap:
4790 All messages in the message queue will eventually be placed
4791 on heap. They can however temporarily be stored off heap.
4792 This is how messages always have been stored up until ERTS
4793 8.0.
4794 The default message_queue_data process flag is determined by
4796 command-line argument +hmqd in erl(1).
4797 If the process potentially can get many messages in its queue,
4799 you are advised to set the flag to off_heap. This because a
4800 garbage collection with many messages placed on the heap can
4801 become extremely expensive and the process can consume large
4802 amounts of memory. Performance of the actual message passing is
4803 however generally better when not using flag off_heap.
4804 When changing this flag messages will be moved. This work has
4806 been initiated but not completed when this function call
4807 returns.
4808 Returns the old value of the flag.
4810 process_flag(Flag :: priority, Level) -> OldLevel
4812 Types:
4814 Level = OldLevel = priority_level()
4816 priority_level() = low | normal | high | max
4817 Sets the process priority. Level is an atom. Four priority lev‐
4819 els exist: low, normal, high, and max. Default is normal.
4820 Note:
4822 Priority level max is reserved for internal use in the Erlang
4823 runtime system, and is not to be used by others.
4824 Internally in each priority level, processes are scheduled in a
4827 round robin fashion.
4828 Execution of processes on priority normal and low are inter‐
4830 leaved. Processes on priority low are selected for execution
4831 less frequently than processes on priority normal.
4832 When runnable processes on priority high exist, no processes on
4834 priority low or normal are selected for execution. Notice how‐
4835 ever that this does not mean that no processes on priority low
4836 or normal can run when processes are running on priority high.
4837 When using multiple schedulers, more processes can be running in
4838 parallel than processes on priority high. That is, a low and a
4839 high priority process can execute at the same time.
4840 When runnable processes on priority max exist, no processes on
4842 priority low, normal, or high are selected for execution. As
4843 with priority high, processes on lower priorities can execute in
4844 parallel with processes on priority max.
4845 Scheduling is pre-emptive. Regardless of priority, a process is
4847 pre-empted when it has consumed more than a certain number of
4848 reductions since the last time it was selected for execution.
4849 Note:
4851 Do not depend on the scheduling to remain exactly as it is
4852 today. Scheduling is likely to be changed in a future release to
4853 use available processor cores better.
4854 There is no automatic mechanism for avoiding priority inversion,
4857 such as priority inheritance or priority ceilings. When using
4858 priorities, take this into account and handle such scenarios by
4859 yourself.
4860 Making calls from a high priority process into code that you has
4862 no control over can cause the high priority process to wait for
4863 a process with lower priority. That is, effectively decreasing
4864 the priority of the high priority process during the call. Even
4865 if this is not the case with one version of the code that you
4866 have no control over, it can be the case in a future version of
4867 it. This can, for example, occur if a high priority process
4868 triggers code loading, as the code server runs on priority nor‐
4869 mal.
4870 Other priorities than normal are normally not needed. When other
4872 priorities are used, use them with care, especially priority
4873 high. A process on priority high is only to perform work for
4874 short periods. Busy looping for long periods in a high priority
4875 process causes most likely problems, as important OTP servers
4876 run on priority normal.
4877 Returns the old value of the flag.
4879 process_flag(Flag :: save_calls, N) -> OldN
4881 Types:
4883 N = OldN = 0..10000
4885 N must be an integer in the interval 0..10000. If N > 0, call
4887 saving is made active for the process. This means that informa‐
4888 tion about the N most recent global function calls, BIF calls,
4889 sends, and receives made by the process are saved in a list,
4890 which can be retrieved with process_info(Pid, last_calls). A
4891 global function call is one in which the module of the function
4892 is explicitly mentioned. Only a fixed amount of information is
4893 saved, as follows:
4894 * A tuple {Module, Function, Arity} for function calls
4896 * The atoms send, 'receive', and timeout for sends and
4898 receives ('receive' when a message is received and timeout
4899 when a receive times out)
4900 If N = 0, call saving is disabled for the process, which is the
4902 default. Whenever the size of the call saving list is set, its
4903 contents are reset.
4904 Returns the old value of the flag.
4906 process_flag(Flag :: sensitive, Boolean) -> OldBoolean
4908 Types:
4910 Boolean = OldBoolean = boolean()
4912 Sets or clears flag sensitive for the current process. When a
4914 process has been marked as sensitive by calling
4915 process_flag(sensitive, true), features in the runtime system
4916 that can be used for examining the data or inner working of the
4917 process are silently disabled.
4918 Features that are disabled include (but are not limited to) the
4920 following:
4921 * Tracing. Trace flags can still be set for the process, but
4923 no trace messages of any kind are generated. (If flag sensi‐
4924 tive is turned off, trace messages are again generated if
4925 any trace flags are set.)
4926 * Sequential tracing. The sequential trace token is propagated
4928 as usual, but no sequential trace messages are generated.
4929 process_info/1,2 cannot be used to read out the message queue or
4931 the process dictionary (both are returned as empty lists).
4932 Stack back-traces cannot be displayed for the process.
4934 In crash dumps, the stack, messages, and the process dictionary
4936 are omitted.
4937 If {save_calls,N} has been set for the process, no function
4939 calls are saved to the call saving list. (The call saving list
4940 is not cleared. Also, send, receive, and time-out events are
4941 still added to the list.)
4942 Returns the old value of the flag.
4944 process_flag(Pid, Flag, Value) -> OldValue
4946 Types:
4948 Pid = pid()
4950 Flag = save_calls
4951 Value = OldValue = integer() >= 0
4952 Sets certain flags for the process Pid, in the same manner as
4954 process_flag/2. Returns the old value of the flag. The valid
4955 values for Flag are only a subset of those allowed in
4956 process_flag/2, namely save_calls.
4957 Failure: badarg if Pid is not a local process.
4959 process_info(Pid) -> Info
4961 Types:
4963 Pid = pid()
4965 Info = [InfoTuple] | undefined
4966 InfoTuple = process_info_result_item()
4967 process_info_result_item() =
4968 {backtrace, Bin :: binary()} |
4969 {binary,
4970 BinInfo ::
4971 [{integer() >= 0,
4972 integer() >= 0,
4973 integer() >= 0}]} |
4974 {catchlevel, CatchLevel :: integer() >= 0} |
4975 {current_function,
4976 {Module :: module(), Function :: atom(), Arity :: arity()} |
4977 undefined} |
4978 {current_location,
4979 {Module :: module(),
4980 Function :: atom(),
4981 Arity :: arity(),
4982 Location ::
4983 [{file, Filename :: string()} |
4984 {line, Line :: integer() >= 1}]}} |
4985 {current_stacktrace, Stack :: [stack_item()]} |
4986 {dictionary, Dictionary :: [{Key :: term(), Value :: term()}]} |
4987 {error_handler, Module :: module()} |
4988 {garbage_collection, GCInfo :: [{atom(), integer() >= 0}]} |
4989 {garbage_collection_info,
4990 GCInfo :: [{atom(), integer() >= 0}]} |
4991 {group_leader, GroupLeader :: pid()} |
4992 {heap_size, Size :: integer() >= 0} |
4993 {initial_call, mfa()} |
4994 {links, PidsAndPorts :: [pid() | port()]} |
4995 {last_calls, false | (Calls :: [mfa()])} |
4996 {memory, Size :: integer() >= 0} |
4997 {message_queue_len, MessageQueueLen :: integer() >= 0} |
4998 {messages, MessageQueue :: [term()]} |
4999 {min_heap_size, MinHeapSize :: integer() >= 0} |
5000 {min_bin_vheap_size, MinBinVHeapSize :: integer() >= 0} |
5001 {max_heap_size, MaxHeapSize :: max_heap_size()} |
5002 {monitored_by,
5003 MonitoredBy :: [pid() | port() | nif_resource()]} |
5004 {monitors,
5005 Monitors ::
5006 [{process | port,
5007 Pid ::
5008 pid() |
5009 port() |
5010 {RegName :: atom(), Node :: node()}}]} |
5011 {message_queue_data, MQD :: message_queue_data()} |
5012 {priority, Level :: priority_level()} |
5013 {reductions, Number :: integer() >= 0} |
5014 {registered_name, [] | (Atom :: atom())} |
5015 {sequential_trace_token,
5016 [] | (SequentialTraceToken :: term())} |
5017 {stack_size, Size :: integer() >= 0} |
5018 {status,
5019 Status ::
5020 exiting | garbage_collecting | waiting | running |
5021 runnable | suspended} |
5022 {suspending,
5023 SuspendeeList ::
5024 [{Suspendee :: pid(),
5025 ActiveSuspendCount :: integer() >= 0,
5026 OutstandingSuspendCount :: integer() >= 0}]} |
5027 {total_heap_size, Size :: integer() >= 0} |
5028 {trace, InternalTraceFlags :: integer() >= 0} |
5029 {trap_exit, Boolean :: boolean()}
5030 priority_level() = low | normal | high | max
5031 stack_item() =
5032 {Module :: module(),
5033 Function :: atom(),
5034 Arity :: arity() | (Args :: [term()]),
5035 Location ::
5036 [{file, Filename :: string()} |
5037 {line, Line :: integer() >= 1}]}
5038 max_heap_size() =
5039 integer() >= 0 |
5040 #{size => integer() >= 0,
5041 kill => boolean(),
5042 error_logger => boolean()}
5043 message_queue_data() = off_heap | on_heap
5044 Returns a list containing InfoTuples with miscellaneous informa‐
5046 tion about the process identified by Pid, or undefined if the
5047 process is not alive.
5048 The order of the InfoTuples is undefined and all InfoTuples are
5050 not mandatory. The InfoTuples part of the result can be changed
5051 without prior notice.
5052 The InfoTuples with the following items are part of the result:
5054 * current_function
5056 * initial_call
5058 * status
5060 * message_queue_len
5062 * links
5064 * dictionary
5066 * trap_exit
5068 * error_handler
5070 * priority
5072 * group_leader
5074 * total_heap_size
5076 * heap_size
5078 * stack_size
5080 * reductions
5082 * garbage_collection
5084 If the process identified by Pid has a registered name, also an
5086 InfoTuple with item registered_name is included.
5087 For information about specific InfoTuples, see process_info/2.
5089 Warning:
5091 This BIF is intended for debugging only. For all other purposes,
5092 use process_info/2.
5093 Failure: badarg if Pid is not a local process.
5096 process_info(Pid, Item) -> InfoTuple | [] | undefined
5098 process_info(Pid, ItemList) -> InfoTupleList | [] | undefined
5100 Types:
5102 Pid = pid()
5104 ItemList = [Item]
5105 Item = process_info_item()
5106 InfoTupleList = [InfoTuple]
5107 InfoTuple = process_info_result_item()
5108 process_info_item() =
5109 backtrace | binary | catchlevel | current_function |
5110 current_location | current_stacktrace | dictionary |
5111 error_handler | garbage_collection | garbage_collection_info |
5112 group_leader | heap_size | initial_call | links | last_calls |
5113 memory | message_queue_len | messages | min_heap_size |
5114 min_bin_vheap_size | monitored_by | monitors |
5115 message_queue_data | priority | reductions | registered_name |
5116 sequential_trace_token | stack_size | status | suspending |
5117 total_heap_size | trace | trap_exit
5118 process_info_result_item() =
5119 {backtrace, Bin :: binary()} |
5120 {binary,
5121 BinInfo ::
5122 [{integer() >= 0,
5123 integer() >= 0,
5124 integer() >= 0}]} |
5125 {catchlevel, CatchLevel :: integer() >= 0} |
5126 {current_function,
5127 {Module :: module(), Function :: atom(), Arity :: arity()} |
5128 undefined} |
5129 {current_location,
5130 {Module :: module(),
5131 Function :: atom(),
5132 Arity :: arity(),
5133 Location ::
5134 [{file, Filename :: string()} |
5135 {line, Line :: integer() >= 1}]}} |
5136 {current_stacktrace, Stack :: [stack_item()]} |
5137 {dictionary, Dictionary :: [{Key :: term(), Value :: term()}]} |
5138 {error_handler, Module :: module()} |
5139 {garbage_collection, GCInfo :: [{atom(), integer() >= 0}]} |
5140 {garbage_collection_info,
5141 GCInfo :: [{atom(), integer() >= 0}]} |
5142 {group_leader, GroupLeader :: pid()} |
5143 {heap_size, Size :: integer() >= 0} |
5144 {initial_call, mfa()} |
5145 {links, PidsAndPorts :: [pid() | port()]} |
5146 {last_calls, false | (Calls :: [mfa()])} |
5147 {memory, Size :: integer() >= 0} |
5148 {message_queue_len, MessageQueueLen :: integer() >= 0} |
5149 {messages, MessageQueue :: [term()]} |
5150 {min_heap_size, MinHeapSize :: integer() >= 0} |
5151 {min_bin_vheap_size, MinBinVHeapSize :: integer() >= 0} |
5152 {max_heap_size, MaxHeapSize :: max_heap_size()} |
5153 {monitored_by,
5154 MonitoredBy :: [pid() | port() | nif_resource()]} |
5155 {monitors,
5156 Monitors ::
5157 [{process | port,
5158 Pid ::
5159 pid() |
5160 port() |
5161 {RegName :: atom(), Node :: node()}}]} |
5162 {message_queue_data, MQD :: message_queue_data()} |
5163 {priority, Level :: priority_level()} |
5164 {reductions, Number :: integer() >= 0} |
5165 {registered_name, [] | (Atom :: atom())} |
5166 {sequential_trace_token,
5167 [] | (SequentialTraceToken :: term())} |
5168 {stack_size, Size :: integer() >= 0} |
5169 {status,
5170 Status ::
5171 exiting | garbage_collecting | waiting | running |
5172 runnable | suspended} |
5173 {suspending,
5174 SuspendeeList ::
5175 [{Suspendee :: pid(),
5176 ActiveSuspendCount :: integer() >= 0,
5177 OutstandingSuspendCount :: integer() >= 0}]} |
5178 {total_heap_size, Size :: integer() >= 0} |
5179 {trace, InternalTraceFlags :: integer() >= 0} |
5180 {trap_exit, Boolean :: boolean()}
5181 stack_item() =
5182 {Module :: module(),
5183 Function :: atom(),
5184 Arity :: arity() | (Args :: [term()]),
5185 Location ::
5186 [{file, Filename :: string()} |
5187 {line, Line :: integer() >= 1}]}
5188 priority_level() = low | normal | high | max
5189 max_heap_size() =
5190 integer() >= 0 |
5191 #{size => integer() >= 0,
5192 kill => boolean(),
5193 error_logger => boolean()}
5194 message_queue_data() = off_heap | on_heap
5195 Returns information about the process identified by Pid, as
5197 specified by Item or ItemList. Returns undefined if the process
5198 is not alive.
5199 If the process is alive and a single Item is specified, the
5201 returned value is the corresponding InfoTuple, unless Item =:=
5202 registered_name and the process has no registered name. In this
5203 case, [] is returned. This strange behavior is because of his‐
5204 torical reasons, and is kept for backward compatibility.
5205 If ItemList is specified, the result is InfoTupleList. The Info‐
5207 Tuples in InfoTupleList are included with the corresponding
5208 Items in the same order as the Items were included in ItemList.
5209 Valid Items can be included multiple times in ItemList.
5210 Note:
5212 If registered_name is part of ItemList and the process has no
5213 name registered, a {registered_name, []}, InfoTuple will be
5214 included in the resulting InfoTupleList. This behavior is dif‐
5215 ferent when a single Item =:= registered_name is specified, and
5216 when process_info/1 is used.
5217 Valid InfoTuples with corresponding Items:
5220 {backtrace, Bin}:
5222 Binary Bin contains the same information as the output from
5223 erlang:process_display(Pid, backtrace). Use binary_to_list/1
5224 to obtain the string of characters from the binary.
5225 {binary, BinInfo}:
5227 BinInfo is a list containing miscellaneous information about
5228 binaries on the heap of this process. This InfoTuple can be
5229 changed or removed without prior notice. In the current
5230 implementation BinInfo is a list of tuples. The tuples con‐
5231 tain; BinaryId, BinarySize, BinaryRefcCount.
5232 The message queue is on the heap depending on the process
5234 flag message_queue_data.
5235 {catchlevel, CatchLevel}:
5237 CatchLevel is the number of currently active catches in this
5238 process. This InfoTuple can be changed or removed without
5239 prior notice.
5240 {current_function, {Module, Function, Arity} | undefined}:
5242 Module, Function, Arity is the current function call of the
5243 process. The value undefined can be returned if the process
5244 is currently executing native compiled code.
5245 {current_location, {Module, Function, Arity, Location}}:
5247 Module, Function, Arity is the current function call of the
5248 process. Location is a list of two-tuples describing the
5249 location in the source code.
5250 {current_stacktrace, Stack}:
5252 Returns the current call stack back-trace (stacktrace) of
5253 the process. The stack has the same format as returned by
5254 erlang:get_stacktrace/0. The depth of the stacktrace is
5255 truncated according to the backtrace_depth system flag set‐
5256 ting.
5257 {dictionary, Dictionary}:
5259 Dictionary is the process dictionary.
5260 {error_handler, Module}:
5262 Module is the error handler module used by the process (for
5263 undefined function calls, for example).
5264 {garbage_collection, GCInfo}:
5266 GCInfo is a list containing miscellaneous information about
5267 garbage collection for this process. The content of GCInfo
5268 can be changed without prior notice.
5269 {garbage_collection_info, GCInfo}:
5271 GCInfo is a list containing miscellaneous detailed informa‐
5272 tion about garbage collection for this process. The content
5273 of GCInfo can be changed without prior notice. For details
5274 about the meaning of each item, see gc_minor_start in
5275 erlang:trace/3.
5276 {group_leader, GroupLeader}:
5278 GroupLeader is the group leader for the I/O of the process.
5279 {heap_size, Size}:
5281 Size is the size in words of the youngest heap generation of
5282 the process. This generation includes the process stack.
5283 This information is highly implementation-dependent, and can
5284 change if the implementation changes.
5285 {initial_call, {Module, Function, Arity}}:
5287 Module, Function, Arity is the initial function call with
5288 which the process was spawned.
5289 {links, PidsAndPorts}:
5291 PidsAndPorts is a list of process identifiers and port iden‐
5292 tifiers, with processes or ports to which the process has a
5293 link.
5294 {last_calls, false|Calls}:
5296 The value is false if call saving is not active for the
5297 process (see process_flag/3). If call saving is active, a
5298 list is returned, in which the last element is the most
5299 recent called.
5300 {memory, Size}:
5302 Size is the size in bytes of the process. This includes call
5305 stack, heap, and internal structures.
5306 {message_queue_len, MessageQueueLen}:
5308 MessageQueueLen is the number of messages currently in the
5309 message queue of the process. This is the length of the list
5310 MessageQueue returned as the information item messages (see
5311 below).
5312 {messages, MessageQueue}:
5314 MessageQueue is a list of the messages to the process, which
5315 have not yet been processed.
5316 {min_heap_size, MinHeapSize}:
5318 MinHeapSize is the minimum heap size for the process.
5319 {min_bin_vheap_size, MinBinVHeapSize}:
5321 MinBinVHeapSize is the minimum binary virtual heap size for
5322 the process.
5323 {monitored_by, MonitoredBy}:
5325 A list of identifiers for all the processes, ports and NIF
5326 resources, that are monitoring the process.
5327 {monitors, Monitors}:
5329 A list of monitors (started by monitor/2) that are active
5330 for the process. For a local process monitor or a remote
5331 process monitor by a process identifier, the list consists
5332 of:
5333 {process, Pid}:
5335 Process is monitored by pid.
5336 {process, {RegName, Node}}:
5338 Local or remote process is monitored by name.
5339 {port, PortId}:
5341 Local port is monitored by port id.
5342 {port, {RegName, Node}}:
5344 Local port is monitored by name. Please note, that remote
5345 port monitors are not supported, so Node will always be
5346 the local node name.
5347 {message_queue_data, MQD}:
5349 Returns the current state of process flag mes‐
5350 sage_queue_data. MQD is either off_heap or on_heap. For more
5351 information, see the documentation of process_flag(mes‐
5352 sage_queue_data, MQD).
5353 {priority, Level}:
5355 Level is the current priority level for the process. For
5356 more information on priorities, see process_flag(priority,
5357 Level).
5358 {reductions, Number}:
5360 Number is the number of reductions executed by the process.
5361 {registered_name, Atom}:
5363 Atom is the registered process name. If the process has no
5364 registered name, this tuple is not present in the list.
5365 {sequential_trace_token, [] | SequentialTraceToken}:
5367 SequentialTraceToken is the sequential trace token for the
5368 process. This InfoTuple can be changed or removed without
5369 prior notice.
5370 {stack_size, Size}:
5372 Size is the stack size, in words, of the process.
5373 {status, Status}:
5375 Status is the status of the process and is one of the fol‐
5376 lowing:
5377 * exiting
5379 * garbage_collecting
5381 * waiting (for a message)
5383 * running
5385 * runnable (ready to run, but another process is running)
5387 * suspended (suspended on a "busy" port or by the BIF
5389 erlang:suspend_process/1,2)
5390 {suspending, SuspendeeList}:
5392 SuspendeeList is a list of {Suspendee, ActiveSuspendCount,
5393 OutstandingSuspendCount} tuples. Suspendee is the process
5394 identifier of a process that has been, or is to be, sus‐
5395 pended by the process identified by Pid through the BIF
5396 erlang:suspend_process/2 or erlang:suspend_process/1.
5397 ActiveSuspendCount is the number of times Suspendee has been
5399 suspended by Pid. OutstandingSuspendCount is the number of
5400 not yet completed suspend requests sent by Pid, that is:
5401 * If ActiveSuspendCount =/= 0, Suspendee is currently in the
5403 suspended state.
5404 * If OutstandingSuspendCount =/= 0, option asynchronous of
5406 erlang:suspend_process/2 has been used and the suspendee
5407 has not yet been suspended by Pid.
5408 Notice that ActiveSuspendCount and OutstandingSuspendCount
5410 are not the total suspend count on Suspendee, only the parts
5411 contributed by Pid.
5412 {total_heap_size, Size}:
5414 Size is the total size, in words, of all heap fragments of
5415 the process. This includes the process stack and any unre‐
5416 ceived messages that are considered to be part of the heap.
5417 {trace, InternalTraceFlags}:
5419 InternalTraceFlags is an integer representing the internal
5420 trace flag for this process. This InfoTuple can be changed
5421 or removed without prior notice.
5422 {trap_exit, Boolean}:
5424 Boolean is true if the process is trapping exits, otherwise
5425 false.
5426 Notice that not all implementations support all these Items.
5428 Failures:
5430 badarg:
5432 If Pid is not a local process.
5433 badarg:
5435 If Item is an invalid item.
5436 processes() -> [pid()]
5438 Returns a list of process identifiers corresponding to all the
5440 processes currently existing on the local node.
5441 Notice that an exiting process exists, but is not alive. That
5443 is, is_process_alive/1 returns false for an exiting process, but
5444 its process identifier is part of the result returned from pro‐
5445 cesses/0.
5446 Example:
5448 > processes().
5450 [<0.0.0>,<0.2.0>,<0.4.0>,<0.5.0>,<0.7.0>,<0.8.0>]
5451 purge_module(Module) -> true
5453 Types:
5455 Module = atom()
5457 Removes old code for Module. Before this BIF is used,
5459 check_process_code/2is to be called to check that no processes
5460 execute old code in the module.
5461 Warning:
5463 This BIF is intended for the code server (see code(3)) and is
5464 not to be used elsewhere.
5465 Note:
5468 As from ERTS 8.0 (Erlang/OTP 19), any lingering processes that
5469 still execute the old code is killed by this function. In ear‐
5470 lier versions, such incorrect use could cause much more fatal
5471 failures, like emulator crash.
5472 Failure: badarg if there is no old code for Module.
5475 put(Key, Val) -> term()
5477 Types:
5479 Key = Val = term()
5481 Adds a new Key to the process dictionary, associated with the
5483 value Val, and returns undefined. If Key exists, the old value
5484 is deleted and replaced by Val, and the function returns the old
5485 value. Example:
5486 > X = put(name, walrus), Y = put(name, carpenter),
5488 Z = get(name),
5489 {X, Y, Z}.
5490 {undefined,walrus,carpenter}
5491 Note:
5493 The values stored when put is evaluated within the scope of a
5494 catch are not retracted if a throw is evaluated, or if an error
5495 occurs.
5496 erlang:raise(Class, Reason, Stacktrace) -> no_return()
5499 Types:
5501 Class = error | exit | throw
5503 Reason = term()
5504 Stacktrace = raise_stacktrace()
5505 raise_stacktrace() =
5506 [{module(), atom(), arity() | [term()]} |
5507 {function(), [term()]}] |
5508 [{module(), atom(), arity() | [term()], [{atom(), term()}]} |
5509 {function(), [term()], [{atom(), term()}]}]
5510 Stops the execution of the calling process with an exception of
5512 the specified class, reason, and call stack backtrace (stack‐
5513 trace).
5514 Class is error, exit, or throw. So, if it were not for the
5516 stacktrace, erlang:raise(Class, Reason, Stacktrace) is equiva‐
5517 lent to erlang:Class(Reason).
5518 Reason is any term. Stacktrace is a list as returned from
5520 get_stacktrace(), that is, a list of four-tuples {Module, Func‐
5521 tion, Arity | Args, Location}, where Module and Function are
5522 atoms, and the third element is an integer arity or an argument
5523 list. The stacktrace can also contain {Fun, Args, Location}
5524 tuples, where Fun is a local fun and Args is an argument list.
5525 Element Location at the end is optional. Omitting it is equiva‐
5527 lent to specifying an empty list.
5528 The stacktrace is used as the exception stacktrace for the call‐
5530 ing process; it is truncated to the current maximum stacktrace
5531 depth.
5532 As evaluating this function causes the process to terminate, it
5534 has no return value unless the arguments are invalid, in which
5535 case the function returns the error reason badarg. If you want
5536 to be sure not to return, you can call error(erlang:raise(Class,
5537 Reason, Stacktrace)) and hope to distinguish exceptions later.
5538 erlang:read_timer(TimerRef) -> Result
5540 Types:
5542 TimerRef = reference()
5544 Time = integer() >= 0
5545 Result = Time | false
5546 Reads the state of a timer. The same as calling
5548 erlang:read_timer(TimerRef, []).
5549 erlang:read_timer(TimerRef, Options) -> Result | ok
5551 Types:
5553 TimerRef = reference()
5555 Async = boolean()
5556 Option = {async, Async}
5557 Options = [Option]
5558 Time = integer() >= 0
5559 Result = Time | false
5560 Reads the state of a timer that has been created by either
5562 erlang:start_timer or erlang:send_after. TimerRef identifies the
5563 timer, and was returned by the BIF that created the timer.
5564 Options:
5566 {async, Async}:
5568 Asynchronous request for state information. Async defaults
5569 to false, which causes the operation to be performed syn‐
5570 chronously. In this case, the Result is returned by
5571 erlang:read_timer. When Async is true, erlang:read_timer
5572 sends an asynchronous request for the state information to
5573 the timer service that manages the timer, and then returns
5574 ok. A message on the format {read_timer, TimerRef, Result}
5575 is sent to the caller of erlang:read_timer when the opera‐
5576 tion has been processed.
5577 More Options can be added in the future.
5579 If Result is an integer, it represents the time in milliseconds
5581 left until the timer expires.
5582 If Result is false, a timer corresponding to TimerRef could not
5584 be found. This because the timer had expired, or been canceled,
5585 or because TimerRef never has corresponded to a timer. Even if
5586 the timer has expired, it does not tell you whether or not the
5587 time-out message has arrived at its destination yet.
5588 Note:
5590 The timer service that manages the timer can be co-located with
5591 another scheduler than the scheduler that the calling process is
5592 executing on. If so, communication with the timer service takes
5593 much longer time than if it is located locally. If the calling
5594 process is in a critical path, and can do other things while
5595 waiting for the result of this operation, you want to use option
5596 {async, true}. If using option {async, false}, the calling
5597 process is blocked until the operation has been performed.
5598 See also erlang:send_after/4, erlang:start_timer/4, and
5601 erlang:cancel_timer/2.
5602 ref_to_list(Ref) -> string()
5604 Types:
5606 Ref = reference()
5608 Returns a string corresponding to the text representation of
5610 Ref.
5611 Warning:
5613 This BIF is intended for debugging and is not to be used in
5614 application programs.
5615 register(RegName, PidOrPort) -> true
5618 Types:
5620 RegName = atom()
5622 PidOrPort = port() | pid()
5623 Associates the name RegName with a process identifier (pid) or a
5625 port identifier. RegName, which must be an atom, can be used
5626 instead of the pid or port identifier in send operator (RegName
5627 ! Message). Example:
5628 > register(db, Pid).
5630 true
5631 Failures:
5633 badarg:
5635 If PidOrPort is not an existing local process or port.
5636 badarg:
5638 If RegName is already in use.
5639 badarg:
5641 If the process or port is already registered (already has a
5642 name).
5643 badarg:
5645 If RegName is the atom undefined.
5646 registered() -> [RegName]
5648 Types:
5650 RegName = atom()
5652 Returns a list of names that have been registered using regis‐
5654 ter/2, for example:
5655 > registered().
5657 [code_server, file_server, init, user, my_db]
5658 erlang:resume_process(Suspendee) -> true
5660 Types:
5662 Suspendee = pid()
5664 Decreases the suspend count on the process identified by Sus‐
5666 pendee. Suspendee is previously to have been suspended through
5667 erlang:suspend_process/2 or erlang:suspend_process/1 by the
5668 process calling erlang:resume_process(Suspendee). When the sus‐
5669 pend count on Suspendee reaches zero, Suspendee is resumed, that
5670 is, its state is changed from suspended into the state it had
5671 before it was suspended.
5672 Warning:
5674 This BIF is intended for debugging only.
5675 Failures:
5678 badarg:
5680 If Suspendee is not a process identifier.
5681 badarg:
5683 If the process calling erlang:resume_process/1 had not pre‐
5684 viously increased the suspend count on the process identi‐
5685 fied by Suspendee.
5686 badarg:
5688 If the process identified by Suspendee is not alive.
5689 round(Number) -> integer()
5691 Types:
5693 Number = number()
5695 Returns an integer by rounding Number, for example:
5697 round(5.5).
5699 6
5700 Allowed in guard tests.
5702 self() -> pid()
5704 Returns the process identifier of the calling process, for exam‐
5706 ple:
5707 > self().
5709 <0.26.0>
5710 Allowed in guard tests.
5712 erlang:send(Dest, Msg) -> Msg
5714 Types:
5716 Dest = dst()
5718 Msg = term()
5719 dst() =
5720 pid() |
5721 port() |
5722 (RegName :: atom()) |
5723 {RegName :: atom(), Node :: node()}
5724 Sends a message and returns Msg. This is the same as using the
5726 send operator: Dest ! Msg.
5727 Dest can be a remote or local process identifier, a (local)
5729 port, a locally registered name, or a tuple {RegName, Node} for
5730 a registered name at another node.
5731 The function fails with a badarg run-time error if Dest is an
5733 atom name, but this name is not registered. This is the only
5734 case when send fails for an unreachable destination Dest (of
5735 correct type).
5736 erlang:send(Dest, Msg, Options) -> Res
5738 Types:
5740 Dest = dst()
5742 Msg = term()
5743 Options = [nosuspend | noconnect]
5744 Res = ok | nosuspend | noconnect
5745 dst() =
5746 pid() |
5747 port() |
5748 (RegName :: atom()) |
5749 {RegName :: atom(), Node :: node()}
5750 Either sends a message and returns ok, or does not send the mes‐
5752 sage but returns something else (see below). Otherwise the same
5753 as erlang:send/2. For more detailed explanation and warnings,
5754 see erlang:send_nosuspend/2,3.
5755 Options:
5757 nosuspend:
5759 If the sender would have to be suspended to do the send,
5760 nosuspend is returned instead.
5761 noconnect:
5763 If the destination node would have to be auto-connected to
5764 do the send, noconnect is returned instead.
5765 Warning:
5767 As with erlang:send_nosuspend/2,3: use with extreme care.
5768 erlang:send_after(Time, Dest, Msg) -> TimerRef
5771 Types:
5773 Time = integer() >= 0
5775 Dest = pid() | atom()
5776 Msg = term()
5777 TimerRef = reference()
5778 Starts a timer. The same as calling erlang:send_after(Time,
5780 Dest, Msg, []).
5781 erlang:send_after(Time, Dest, Msg, Options) -> TimerRef
5783 Types:
5785 Time = integer()
5787 Dest = pid() | atom()
5788 Msg = term()
5789 Options = [Option]
5790 Abs = boolean()
5791 Option = {abs, Abs}
5792 TimerRef = reference()
5793 Starts a timer. When the timer expires, the message Msg is sent
5795 to the process identified by Dest. Apart from the format of the
5796 time-out message, this function works exactly as
5797 erlang:start_timer/4.
5798 erlang:send_nosuspend(Dest, Msg) -> boolean()
5800 Types:
5802 Dest = dst()
5804 Msg = term()
5805 dst() =
5806 pid() |
5807 port() |
5808 (RegName :: atom()) |
5809 {RegName :: atom(), Node :: node()}
5810 The same as erlang:send(Dest, Msg, [nosuspend]), but returns
5812 true if the message was sent and false if the message was not
5813 sent because the sender would have had to be suspended.
5814 This function is intended for send operations to an unreliable
5816 remote node without ever blocking the sending (Erlang) process.
5817 If the connection to the remote node (usually not a real Erlang
5818 node, but a node written in C or Java) is overloaded, this func‐
5819 tion does not send the message and returns false.
5820 The same occurs if Dest refers to a local port that is busy. For
5822 all other destinations (allowed for the ordinary send operator
5823 '!'), this function sends the message and returns true.
5824 This function is only to be used in rare circumstances where a
5826 process communicates with Erlang nodes that can disappear with‐
5827 out any trace, causing the TCP buffers and the drivers queue to
5828 be over-full before the node is shut down (because of tick time-
5829 outs) by net_kernel. The normal reaction to take when this
5830 occurs is some kind of premature shutdown of the other node.
5831 Notice that ignoring the return value from this function would
5833 result in an unreliable message passing, which is contradictory
5834 to the Erlang programming model. The message is not sent if this
5835 function returns false.
5836 In many systems, transient states of overloaded queues are nor‐
5838 mal. Although this function returns false does not mean that the
5839 other node is guaranteed to be non-responsive, it could be a
5840 temporary overload. Also, a return value of true does only mean
5841 that the message can be sent on the (TCP) channel without block‐
5842 ing; the message is not guaranteed to arrive at the remote node.
5843 For a disconnected non-responsive node, the return value is true
5844 (mimics the behavior of operator !). The expected behavior and
5845 the actions to take when the function returns false are applica‐
5846 tion- and hardware-specific.
5847 Warning:
5849 Use with extreme care.
5850 erlang:send_nosuspend(Dest, Msg, Options) -> boolean()
5853 Types:
5855 Dest = dst()
5857 Msg = term()
5858 Options = [noconnect]
5859 dst() =
5860 pid() |
5861 port() |
5862 (RegName :: atom()) |
5863 {RegName :: atom(), Node :: node()}
5864 The same as erlang:send(Dest, Msg, [nosuspend | Options]), but
5866 with a Boolean return value.
5867 This function behaves like erlang:send_nosuspend/2, but takes a
5869 third parameter, a list of options. The only option is nocon‐
5870 nect, which makes the function return false if the remote node
5871 is not currently reachable by the local node. The normal behav‐
5872 ior is to try to connect to the node, which can stall the
5873 process during a short period. The use of option noconnect makes
5874 it possible to be sure not to get the slightest delay when send‐
5875 ing to a remote process. This is especially useful when communi‐
5876 cating with nodes that expect to always be the connecting part
5877 (that is, nodes written in C or Java).
5878 Whenever the function returns false (either when a suspend would
5880 occur or when noconnect was specified and the node was not
5881 already connected), the message is guaranteed not to have been
5882 sent.
5883 Warning:
5885 Use with extreme care.
5886 erlang:set_cookie(Node, Cookie) -> true
5889 Types:
5891 Node = node()
5893 Cookie = atom()
5894 Sets the magic cookie of Node to the atom Cookie. If Node is the
5896 local node, the function also sets the cookie of all other
5897 unknown nodes to Cookie (see section Distributed Erlang in the
5898 Erlang Reference Manual in System Documentation).
5899 Failure: function_clause if the local node is not alive.
5901 setelement(Index, Tuple1, Value) -> Tuple2
5903 Types:
5905 Index = integer() >= 1
5907 1..tuple_size(Tuple1
5908 Tuple1 = Tuple2 = tuple()
5909 Value = term()
5910 Returns a tuple that is a copy of argument Tuple1 with the ele‐
5912 ment specified by integer argument Index (the first element is
5913 the element with index 1) replaced by argument Value, for exam‐
5914 ple:
5915 > setelement(2, {10, green, bottles}, red).
5917 {10,red,bottles}
5918 size(Item) -> integer() >= 0
5920 Types:
5922 Item = tuple() | binary()
5924 Returns the number of elements in a tuple or the number of bytes
5926 in a binary or bitstring, for example:
5927 > size({morni, mulle, bwange}).
5929 3
5930 > size(<<11, 22, 33>>).
5931 3
5932 For bitstrings, the number of whole bytes is returned. That is,
5934 if the number of bits in the bitstring is not divisible by 8,
5935 the resulting number of bytes is rounded down.
5936 Allowed in guard tests.
5938 See also tuple_size/1, byte_size/1, and bit_size/1.
5940 spawn(Fun) -> pid()
5942 Types:
5944 Fun = function()
5946 Returns the process identifier of a new process started by the
5948 application of Fun to the empty list []. Otherwise works like
5949 spawn/3.
5950 spawn(Node, Fun) -> pid()
5952 Types:
5954 Node = node()
5956 Fun = function()
5957 Returns the process identifier of a new process started by the
5959 application of Fun to the empty list [] on Node. If Node does
5960 not exist, a useless pid is returned. Otherwise works like
5961 spawn/3.
5962 spawn(Module, Function, Args) -> pid()
5964 Types:
5966 Module = module()
5968 Function = atom()
5969 Args = [term()]
5970 Returns the process identifier of a new process started by the
5972 application of Module:Function to Args.
5973 error_handler:undefined_function(Module, Function, Args) is
5975 evaluated by the new process if Module:Function/Arity does not
5976 exist (where Arity is the length of Args). The error handler can
5977 be redefined (see process_flag/2). If error_handler is unde‐
5978 fined, or the user has redefined the default error_handler and
5979 its replacement is undefined, a failure with reason undef
5980 occurs.
5981 Example:
5983 > spawn(speed, regulator, [high_speed, thin_cut]).
5985 <0.13.1>
5986 spawn(Node, Module, Function, Args) -> pid()
5988 Types:
5990 Node = node()
5992 Module = module()
5993 Function = atom()
5994 Args = [term()]
5995 Returns the process identifier (pid) of a new process started by
5997 the application of Module:Function to Args on Node. If Node does
5998 not exist, a useless pid is returned. Otherwise works like
5999 spawn/3.
6000 spawn_link(Fun) -> pid()
6002 Types:
6004 Fun = function()
6006 Returns the process identifier of a new process started by the
6008 application of Fun to the empty list []. A link is created
6009 between the calling process and the new process, atomically.
6010 Otherwise works like spawn/3.
6011 spawn_link(Node, Fun) -> pid()
6013 Types:
6015 Node = node()
6017 Fun = function()
6018 Returns the process identifier (pid) of a new process started by
6020 the application of Fun to the empty list [] on Node. A link is
6021 created between the calling process and the new process, atomi‐
6022 cally. If Node does not exist, a useless pid is returned and an
6023 exit signal with reason noconnection is sent to the calling
6024 process. Otherwise works like spawn/3.
6025 spawn_link(Module, Function, Args) -> pid()
6027 Types:
6029 Module = module()
6031 Function = atom()
6032 Args = [term()]
6033 Returns the process identifier of a new process started by the
6035 application of Module:Function to Args. A link is created
6036 between the calling process and the new process, atomically.
6037 Otherwise works like spawn/3.
6038 spawn_link(Node, Module, Function, Args) -> pid()
6040 Types:
6042 Node = node()
6044 Module = module()
6045 Function = atom()
6046 Args = [term()]
6047 Returns the process identifier (pid) of a new process started by
6049 the application of Module:Function to Args on Node. A link is
6050 created between the calling process and the new process, atomi‐
6051 cally. If Node does not exist, a useless pid is returned and an
6052 exit signal with reason noconnection is sent to the calling
6053 process. Otherwise works like spawn/3.
6054 spawn_monitor(Fun) -> {pid(), reference()}
6056 Types:
6058 Fun = function()
6060 Returns the process identifier of a new process, started by the
6062 application of Fun to the empty list [], and a reference for a
6063 monitor created to the new process. Otherwise works like
6064 spawn/3.
6065 spawn_monitor(Module, Function, Args) -> {pid(), reference()}
6067 Types:
6069 Module = module()
6071 Function = atom()
6072 Args = [term()]
6073 A new process is started by the application of Module:Function
6075 to Args. The process is monitored at the same time. Returns the
6076 process identifier and a reference for the monitor. Otherwise
6077 works like spawn/3.
6078 spawn_opt(Fun, Options) -> pid() | {pid(), reference()}
6080 Types:
6082 Fun = function()
6084 Options = [spawn_opt_option()]
6085 priority_level() = low | normal | high | max
6086 max_heap_size() =
6087 integer() >= 0 |
6088 #{size => integer() >= 0,
6089 kill => boolean(),
6090 error_logger => boolean()}
6091 message_queue_data() = off_heap | on_heap
6092 spawn_opt_option() =
6093 link | monitor |
6094 {priority, Level :: priority_level()} |
6095 {fullsweep_after, Number :: integer() >= 0} |
6096 {min_heap_size, Size :: integer() >= 0} |
6097 {min_bin_vheap_size, VSize :: integer() >= 0} |
6098 {max_heap_size, Size :: max_heap_size()} |
6099 {message_queue_data, MQD :: message_queue_data()}
6100 Returns the process identifier (pid) of a new process started by
6102 the application of Fun to the empty list []. Otherwise works
6103 like spawn_opt/4.
6104 If option monitor is specified, the newly created process is
6106 monitored, and both the pid and reference for the monitor are
6107 returned.
6108 spawn_opt(Node, Fun, Options) -> pid() | {pid(), reference()}
6110 Types:
6112 Node = node()
6114 Fun = function()
6115 Options = [spawn_opt_option()]
6116 priority_level() = low | normal | high | max
6117 max_heap_size() =
6118 integer() >= 0 |
6119 #{size => integer() >= 0,
6120 kill => boolean(),
6121 error_logger => boolean()}
6122 message_queue_data() = off_heap | on_heap
6123 spawn_opt_option() =
6124 link | monitor |
6125 {priority, Level :: priority_level()} |
6126 {fullsweep_after, Number :: integer() >= 0} |
6127 {min_heap_size, Size :: integer() >= 0} |
6128 {min_bin_vheap_size, VSize :: integer() >= 0} |
6129 {max_heap_size, Size :: max_heap_size()} |
6130 {message_queue_data, MQD :: message_queue_data()}
6131 Returns the process identifier (pid) of a new process started by
6133 the application of Fun to the empty list [] on Node. If Node
6134 does not exist, a useless pid is returned. Otherwise works like
6135 spawn_opt/4.
6136 spawn_opt(Module, Function, Args, Options) ->
6138 pid() | {pid(), reference()}
6139 Types:
6141 Module = module()
6143 Function = atom()
6144 Args = [term()]
6145 Options = [spawn_opt_option()]
6146 priority_level() = low | normal | high | max
6147 max_heap_size() =
6148 integer() >= 0 |
6149 #{size => integer() >= 0,
6150 kill => boolean(),
6151 error_logger => boolean()}
6152 message_queue_data() = off_heap | on_heap
6153 spawn_opt_option() =
6154 link | monitor |
6155 {priority, Level :: priority_level()} |
6156 {fullsweep_after, Number :: integer() >= 0} |
6157 {min_heap_size, Size :: integer() >= 0} |
6158 {min_bin_vheap_size, VSize :: integer() >= 0} |
6159 {max_heap_size, Size :: max_heap_size()} |
6160 {message_queue_data, MQD :: message_queue_data()}
6161 Works as spawn/3, except that an extra option list is specified
6163 when creating the process.
6164 If option monitor is specified, the newly created process is
6166 monitored, and both the pid and reference for the monitor are
6167 returned.
6168 Options:
6170 link:
6172 Sets a link to the parent process (like spawn_link/3 does).
6173 monitor:
6175 Monitors the new process (like monitor/2 does).
6176 {priority, Level}:
6178 Sets the priority of the new process. Equivalent to execut‐
6179 ing process_flag(priority, Level) in the start function of
6180 the new process, except that the priority is set before the
6181 process is selected for execution for the first time. For
6182 more information on priorities, see process_flag(priority,
6183 Level).
6184 {fullsweep_after, Number}:
6186 Useful only for performance tuning. Do not use this option
6187 unless you know that there is problem with execution times
6188 or memory consumption, and ensure that the option improves
6189 matters.
6190 The Erlang runtime system uses a generational garbage col‐
6192 lection scheme, using an "old heap" for data that has sur‐
6193 vived at least one garbage collection. When there is no more
6194 room on the old heap, a fullsweep garbage collection is
6195 done.
6196 Option fullsweep_after makes it possible to specify the max‐
6198 imum number of generational collections before forcing a
6199 fullsweep, even if there is room on the old heap. Setting
6200 the number to zero disables the general collection algo‐
6201 rithm, that is, all live data is copied at every garbage
6202 collection.
6203 A few cases when it can be useful to change fullsweep_after:
6205 * If binaries that are no longer used are to be thrown away
6207 as soon as possible. (Set Number to zero.)
6208 * A process that mostly have short-lived data is fullsweeped
6210 seldom or never, that is, the old heap contains mostly
6211 garbage. To ensure a fullsweep occasionally, set Number to
6212 a suitable value, such as 10 or 20.
6213 * In embedded systems with a limited amount of RAM and no
6215 virtual memory, you might want to preserve memory by set‐
6216 ting Number to zero. (The value can be set globally, see
6217 erlang:system_flag/2.)
6218 {min_heap_size, Size}:
6220 Useful only for performance tuning. Do not use this option
6221 unless you know that there is problem with execution times
6222 or memory consumption, and ensure that the option improves
6223 matters.
6224 Gives a minimum heap size, in words. Setting this value
6226 higher than the system default can speed up some processes
6227 because less garbage collection is done. However, setting a
6228 too high value can waste memory and slow down the system
6229 because of worse data locality. Therefore, use this option
6230 only for fine-tuning an application and to measure the exe‐
6231 cution time with various Size values.
6232 {min_bin_vheap_size, VSize}:
6234 Useful only for performance tuning. Do not use this option
6235 unless you know that there is problem with execution times
6236 or memory consumption, and ensure that the option improves
6237 matters.
6238 Gives a minimum binary virtual heap size, in words. Setting
6240 this value higher than the system default can speed up some
6241 processes because less garbage collection is done. However,
6242 setting a too high value can waste memory. Therefore, use
6243 this option only for fine-tuning an application and to mea‐
6244 sure the execution time with various VSize values.
6245 {max_heap_size, Size}:
6247 Sets the max_heap_size process flag. The default
6248 max_heap_size is determined by command-line argument +hmax
6249 in erl(1). For more information, see the documentation of
6250 process_flag(max_heap_size, Size).
6251 {message_queue_data, MQD}:
6253 Sets the state of the message_queue_data process flag. MQD
6254 is to be either off_heap or on_heap. The default mes‐
6255 sage_queue_data process flag is determined by command-line
6256 argument +hmqd in erl(1). For more information, see the doc‐
6257 umentation of process_flag(message_queue_data, MQD).
6258 spawn_opt(Node, Module, Function, Args, Options) ->
6260 pid() | {pid(), reference()}
6261 Types:
6263 Node = node()
6265 Module = module()
6266 Function = atom()
6267 Args = [term()]
6268 Options = [spawn_opt_option()]
6269 priority_level() = low | normal | high | max
6270 max_heap_size() =
6271 integer() >= 0 |
6272 #{size => integer() >= 0,
6273 kill => boolean(),
6274 error_logger => boolean()}
6275 message_queue_data() = off_heap | on_heap
6276 spawn_opt_option() =
6277 link | monitor |
6278 {priority, Level :: priority_level()} |
6279 {fullsweep_after, Number :: integer() >= 0} |
6280 {min_heap_size, Size :: integer() >= 0} |
6281 {min_bin_vheap_size, VSize :: integer() >= 0} |
6282 {max_heap_size, Size :: max_heap_size()} |
6283 {message_queue_data, MQD :: message_queue_data()}
6284 Returns the process identifier (pid) of a new process started by
6286 the application of Module:Function to Args on Node. If Node does
6287 not exist, a useless pid is returned. Otherwise works like
6288 spawn_opt/4.
6289 Note:
6291 Option monitor is not supported by spawn_opt/5.
6292 split_binary(Bin, Pos) -> {binary(), binary()}
6295 Types:
6297 Bin = binary()
6299 Pos = integer() >= 0
6300 0..byte_size(Bin)
6301 Returns a tuple containing the binaries that are the result of
6303 splitting Bin into two parts at position Pos. This is not a
6304 destructive operation. After the operation, there are three
6305 binaries altogether. Example:
6306 > B = list_to_binary("0123456789").
6308 <<"0123456789">>
6309 > byte_size(B).
6310 10
6311 > {B1, B2} = split_binary(B,3).
6312 {<<"012">>,<<"3456789">>}
6313 > byte_size(B1).
6314 3
6315 > byte_size(B2).
6316 7
6317 erlang:start_timer(Time, Dest, Msg) -> TimerRef
6319 Types:
6321 Time = integer() >= 0
6323 Dest = pid() | atom()
6324 Msg = term()
6325 TimerRef = reference()
6326 Starts a timer. The same as calling erlang:start_timer(Time,
6328 Dest, Msg, []).
6329 erlang:start_timer(Time, Dest, Msg, Options) -> TimerRef
6331 Types:
6333 Time = integer()
6335 Dest = pid() | atom()
6336 Msg = term()
6337 Options = [Option]
6338 Abs = boolean()
6339 Option = {abs, Abs}
6340 TimerRef = reference()
6341 Starts a timer. When the timer expires, the message {timeout,
6343 TimerRef, Msg} is sent to the process identified by Dest.
6344 Options:
6346 {abs, false}:
6348 This is the default. It means the Time value is interpreted
6349 as a time in milliseconds relative current Erlang monotonic
6350 time.
6351 {abs, true}:
6353 Absolute Time value. The Time value is interpreted as an
6354 absolute Erlang monotonic time in milliseconds.
6355 More Options can be added in the future.
6357 The absolute point in time, the timer is set to expire on, must
6359 be in the interval [erlang:system_info(start_time), erlang:sys‐
6360 tem_info(end_time)]. If a relative time is specified, the Time
6361 value is not allowed to be negative.
6362 If Dest is a pid(), it must be a pid() of a process created on
6364 the current runtime system instance. This process has either
6365 terminated or not. If Dest is an atom(), it is interpreted as
6366 the name of a locally registered process. The process referred
6367 to by the name is looked up at the time of timer expiration. No
6368 error is returned if the name does not refer to a process.
6369 If Dest is a pid(), the timer is automatically canceled if the
6371 process referred to by the pid() is not alive, or if the process
6372 exits. This feature was introduced in ERTS 5.4.11. Notice that
6373 timers are not automatically canceled when Dest is an atom().
6374 See also erlang:send_after/4, erlang:cancel_timer/2, and
6376 erlang:read_timer/2.
6377 Failure: badarg if the arguments do not satisfy the requirements
6379 specified here.
6380 statistics(Item :: active_tasks) -> [ActiveTasks]
6382 Types:
6384 ActiveTasks = integer() >= 0
6386 Returns the same as statistics(active_tasks_all) with the excep‐
6388 tion that no information about the dirty IO run queue and its
6389 associated schedulers is part of the result. That is, only tasks
6390 that are expected to be CPU bound are part of the result.
6391 statistics(Item :: active_tasks_all) -> [ActiveTasks]
6393 Types:
6395 ActiveTasks = integer() >= 0
6397 Returns a list where each element represents the amount of
6399 active processes and ports on each run queue and its associated
6400 schedulers. That is, the number of processes and ports that are
6401 ready to run, or are currently running. Values for normal run
6402 queues and their associated schedulers are located first in the
6403 resulting list. The first element corresponds to scheduler num‐
6404 ber 1 and so on. If support for dirty schedulers exist, an ele‐
6405 ment with the value for the dirty CPU run queue and its associ‐
6406 ated dirty CPU schedulers follow and then as last element the
6407 value for the the dirty IO run queue and its associated dirty IO
6408 schedulers follow. The information is not gathered atomically.
6409 That is, the result is not necessarily a consistent snapshot of
6410 the state, but instead quite efficiently gathered.
6411 Note:
6413 Each normal scheduler has one run queue that it manages. If
6414 dirty schedulers schedulers are supported, all dirty CPU sched‐
6415 ulers share one run queue, and all dirty IO schedulers share one
6416 run queue. That is, we have multiple normal run queues, one
6417 dirty CPU run queue and one dirty IO run queue. Work can not
6418 migrate between the different types of run queues. Only work in
6419 normal run queues can migrate to other normal run queues. This
6420 has to be taken into account when evaluating the result.
6421 See also statistics(total_active_tasks), statis‐
6424 tics(run_queue_lengths), statistics(run_queue_lengths_all), sta‐
6425 tistics(total_run_queue_lengths), and statis‐
6426 tics(total_run_queue_lengths_all).
6427 statistics(Item :: context_switches) -> {ContextSwitches, 0}
6429 Types:
6431 ContextSwitches = integer() >= 0
6433 Returns the total number of context switches since the system
6435 started.
6436 statistics(Item :: exact_reductions) ->
6438 {Total_Exact_Reductions,
6439 Exact_Reductions_Since_Last_Call}
6440 Types:
6442 Total_Exact_Reductions = Exact_Reductions_Since_Last_Call =
6444 integer() >= 0
6445 Returns the number of exact reductions.
6447 Note:
6449 statistics(exact_reductions) is a more expensive operation than
6450 statistics(reductions).
6451 statistics(Item :: garbage_collection) ->
6454 {Number_of_GCs, Words_Reclaimed, 0}
6455 Types:
6457 Number_of_GCs = Words_Reclaimed = integer() >= 0
6459 Returns information about garbage collection, for example:
6461 > statistics(garbage_collection).
6463 {85,23961,0}
6464 This information can be invalid for some implementations.
6466 statistics(Item :: io) -> {{input, Input}, {output, Output}}
6468 Types:
6470 Input = Output = integer() >= 0
6472 Returns Input, which is the total number of bytes received
6474 through ports, and Output, which is the total number of bytes
6475 output to ports.
6476 statistics(Item :: microstate_accounting) ->
6478 [MSAcc_Thread] | undefined
6479 Types:
6481 MSAcc_Thread =
6483 #{type := MSAcc_Thread_Type,
6484 id := MSAcc_Thread_Id,
6485 counters := MSAcc_Counters}
6486 MSAcc_Thread_Type =
6487 async | aux | dirty_io_scheduler | dirty_cpu_scheduler |
6488 poll | scheduler
6489 MSAcc_Thread_Id = integer() >= 0
6490 MSAcc_Counters = #{MSAcc_Thread_State => integer() >= 0}
6491 MSAcc_Thread_State =
6492 alloc | aux | bif | busy_wait | check_io | emulator | ets
6493 |
6494 gc | gc_fullsweep | nif | other | port | send | sleep |
6495 timers
6496 Microstate accounting can be used to measure how much time the
6498 Erlang runtime system spends doing various tasks. It is designed
6499 to be as lightweight as possible, but some overhead exists when
6500 this is enabled. Microstate accounting is meant to be a profil‐
6501 ing tool to help finding performance bottlenecks. To
6502 start/stop/reset microstate accounting, use system flag
6503 microstate_accounting.
6504 statistics(microstate_accounting) returns a list of maps repre‐
6506 senting some of the OS threads within ERTS. Each map contains
6507 type and id fields that can be used to identify what thread it
6508 is, and also a counters field that contains data about how much
6509 time has been spent in the various states.
6510 Example:
6512 > erlang:statistics(microstate_accounting).
6514 [#{counters => #{aux => 1899182914,
6515 check_io => 2605863602,
6516 emulator => 45731880463,
6517 gc => 1512206910,
6518 other => 5421338456,
6519 port => 221631,
6520 sleep => 5150294100},
6521 id => 1,
6522 type => scheduler}|...]
6523 The time unit is the same as returned by os:perf_counter/0. So,
6525 to convert it to milliseconds, you can do something like this:
6526 lists:map(
6528 fun(#{ counters := Cnt } = M) ->
6529 MsCnt = maps:map(fun(_K, PerfCount) ->
6530 erlang:convert_time_unit(PerfCount, perf_counter, 1000)
6531 end, Cnt),
6532 M#{ counters := MsCnt }
6533 end, erlang:statistics(microstate_accounting)).
6534 Notice that these values are not guaranteed to be the exact time
6536 spent in each state. This is because of various optimisation
6537 done to keep the overhead as small as possible.
6538 MSAcc_Thread_Types:
6540 scheduler:
6542 The main execution threads that do most of the work. See erl
6543 +S for more details.
6544 dirty_cpu_scheduler:
6546 The threads for long running cpu intensive work. See erl
6547 +SDcpu for more details.
6548 dirty_io_scheduler:
6550 The threads for long running I/O work. See erl +SDio for
6551 more details.
6552 async:
6554 Async threads are used by various linked-in drivers (mainly
6555 the file drivers) do offload non-CPU intensive work. See erl
6556 +A for more details.
6557 aux:
6559 Takes care of any work that is not specifically assigned to
6560 a scheduler.
6561 poll:
6563 Does the IO polling for the emulator. See erl +IOt for more
6564 details.
6565 The following MSAcc_Thread_States are available. All states are
6567 exclusive, meaning that a thread cannot be in two states at
6568 once. So, if you add the numbers of all counters in a thread,
6569 you get the total runtime for that thread.
6570 aux:
6572 Time spent handling auxiliary jobs.
6573 check_io:
6575 Time spent checking for new I/O events.
6576 emulator:
6578 Time spent executing Erlang processes.
6579 gc:
6581 Time spent doing garbage collection. When extra states are
6582 enabled this is the time spent doing non-fullsweep garbage
6583 collections.
6584 other:
6586 Time spent doing unaccounted things.
6587 port:
6589 Time spent executing ports.
6590 sleep:
6592 Time spent sleeping.
6593 More fine-grained MSAcc_Thread_States can be added through con‐
6595 figure (such as ./configure --with-microstate-accounting=extra).
6596 Enabling these states causes performance degradation when
6597 microstate accounting is turned off and increases the overhead
6598 when it is turned on.
6599 alloc:
6601 Time spent managing memory. Without extra states this time
6602 is spread out over all other states.
6603 bif:
6605 Time spent in BIFs. Without extra states this time is part
6606 of the emulator state.
6607 busy_wait:
6609 Time spent busy waiting. This is also the state where a
6610 scheduler no longer reports that it is active when using
6611 statistics(scheduler_wall_time). So, if you add all other
6612 states but this and sleep, and then divide that by all time
6613 in the thread, you should get something very similar to the
6614 scheduler_wall_time fraction. Without extra states this time
6615 is part of the other state.
6616 ets:
6618 Time spent executing ETS BIFs. Without extra states this
6619 time is part of the emulator state.
6620 gc_full:
6622 Time spent doing fullsweep garbage collection. Without extra
6623 states this time is part of the gc state.
6624 nif:
6626 Time spent in NIFs. Without extra states this time is part
6627 of the emulator state.
6628 send:
6630 Time spent sending messages (processes only). Without extra
6631 states this time is part of the emulator state.
6632 timers:
6634 Time spent managing timers. Without extra states this time
6635 is part of the other state.
6636 The utility module msacc(3) can be used to more easily analyse
6638 these statistics.
6639 Returns undefined if system flag microstate_accounting is turned
6641 off.
6642 The list of thread information is unsorted and can appear in
6644 different order between calls.
6645 Note:
6647 The threads and states are subject to change without any prior
6648 notice.
6649 statistics(Item :: reductions) ->
6652 {Total_Reductions, Reductions_Since_Last_Call}
6653 Types:
6655 Total_Reductions = Reductions_Since_Last_Call = integer() >=
6657 0
6658 Returns information about reductions, for example:
6660 > statistics(reductions).
6662 {2046,11}
6663 Note:
6665 As from ERTS 5.5 (Erlang/OTP R11B), this value does not include
6666 reductions performed in current time slices of currently sched‐
6667 uled processes. If an exact value is wanted, use statis‐
6668 tics(exact_reductions).
6669 statistics(Item :: run_queue) -> integer() >= 0
6672 Returns the total length of all normal run-queues. That is, the
6674 number of processes and ports that are ready to run on all
6675 available normal run-queues. Dirty run queues are not part of
6676 the result. The information is gathered atomically. That is, the
6677 result is a consistent snapshot of the state, but this operation
6678 is much more expensive compared to statis‐
6679 tics(total_run_queue_lengths), especially when a large amount of
6680 schedulers is used.
6681 statistics(Item :: run_queue_lengths) -> [RunQueueLength]
6683 Types:
6685 RunQueueLength = integer() >= 0
6687 Returns the same as statistics(run_queue_lengths_all) with the
6689 exception that no information about the dirty IO run queue is
6690 part of the result. That is, only run queues with work that is
6691 expected to be CPU bound is part of the result.
6692 statistics(Item :: run_queue_lengths_all) -> [RunQueueLength]
6694 Types:
6696 RunQueueLength = integer() >= 0
6698 Returns a list where each element represents the amount of pro‐
6700 cesses and ports ready to run for each run queue. Values for
6701 normal run queues are located first in the resulting list. The
6702 first element corresponds to the normal run queue of scheduler
6703 number 1 and so on. If support for dirty schedulers exist, val‐
6704 ues for the dirty CPU run queue and the dirty IO run queue fol‐
6705 low (in that order) at the end. The information is not gathered
6706 atomically. That is, the result is not necessarily a consistent
6707 snapshot of the state, but instead quite efficiently gathered.
6708 Note:
6710 Each normal scheduler has one run queue that it manages. If
6711 dirty schedulers schedulers are supported, all dirty CPU sched‐
6712 ulers share one run queue, and all dirty IO schedulers share one
6713 run queue. That is, we have multiple normal run queues, one
6714 dirty CPU run queue and one dirty IO run queue. Work can not
6715 migrate between the different types of run queues. Only work in
6716 normal run queues can migrate to other normal run queues. This
6717 has to be taken into account when evaluating the result.
6718 See also statistics(run_queue_lengths), statis‐
6721 tics(total_run_queue_lengths_all), statis‐
6722 tics(total_run_queue_lengths), statistics(active_tasks), statis‐
6723 tics(active_tasks_all), and statistics(total_active_tasks), sta‐
6724 tistics(total_active_tasks_all).
6725 statistics(Item :: runtime) ->
6727 {Total_Run_Time, Time_Since_Last_Call}
6728 Types:
6730 Total_Run_Time = Time_Since_Last_Call = integer() >= 0
6732 Returns information about runtime, in milliseconds.
6734 This is the sum of the runtime for all threads in the Erlang
6736 runtime system and can therefore be greater than the wall clock
6737 time.
6738 Warning:
6740 This value might wrap due to limitations in the underlying func‐
6741 tionality provided by the operating system that is used.
6742 Example:
6745 > statistics(runtime).
6747 {1690,1620}
6748 statistics(Item :: scheduler_wall_time) ->
6750 [{SchedulerId, ActiveTime, TotalTime}] | undefined
6751 Types:
6753 SchedulerId = integer() >= 1
6755 ActiveTime = TotalTime = integer() >= 0
6756 Returns a list of tuples with {SchedulerId, ActiveTime, Total‐
6758 Time}, where SchedulerId is an integer ID of the scheduler,
6759 ActiveTime is the duration the scheduler has been busy, and
6760 TotalTime is the total time duration since scheduler_wall_time
6761 activation for the specific scheduler. Note that activation time
6762 can differ significantly between schedulers. Currently dirty
6763 schedulers are activated at system start while normal schedulers
6764 are activated some time after the scheduler_wall_time function‐
6765 ality is enabled. The time unit is undefined and can be subject
6766 to change between releases, OSs, and system restarts. sched‐
6767 uler_wall_time is only to be used to calculate relative values
6768 for scheduler utilization. ActiveTime can never exceed Total‐
6769 Time.
6770 The definition of a busy scheduler is when it is not idle and is
6772 not scheduling (selecting) a process or port, that is:
6773 * Executing process code
6775 * Executing linked-in driver or NIF code
6777 * Executing BIFs, or any other runtime handling
6779 * Garbage collecting
6781 * Handling any other memory management
6783 Notice that a scheduler can also be busy even if the OS has
6785 scheduled out the scheduler thread.
6786 Returns undefined if system flag scheduler_wall_time is turned
6788 off.
6789 The list of scheduler information is unsorted and can appear in
6791 different order between calls.
6792 As of ERTS version 9.0, also dirty CPU schedulers will be
6794 included in the result. That is, all scheduler threads that are
6795 expected to handle CPU bound work. If you also want information
6796 about dirty I/O schedulers, use statistics(sched‐
6797 uler_wall_time_all) instead.
6798 Normal schedulers will have scheduler identifiers in the range 1
6800 =< SchedulerId =< erlang:system_info(schedulers). Dirty CPU
6801 schedulers will have scheduler identifiers in the range
6802 erlang:system_info(schedulers) < SchedulerId =< erlang:sys‐
6803 tem_info(schedulers) + erlang:system_info(dirty_cpu_schedulers).
6804 Note:
6806 The different types of schedulers handle specific types of jobs.
6807 Every job is assigned to a specific scheduler type. Jobs can
6808 migrate between different schedulers of the same type, but never
6809 between schedulers of different types. This fact has to be taken
6810 under consideration when evaluating the result returned.
6811 Using scheduler_wall_time to calculate scheduler utilization:
6814 > erlang:system_flag(scheduler_wall_time, true).
6816 false
6817 > Ts0 = lists:sort(erlang:statistics(scheduler_wall_time)), ok.
6818 ok
6819 Some time later the user takes another snapshot and calculates
6821 scheduler utilization per scheduler, for example:
6822 > Ts1 = lists:sort(erlang:statistics(scheduler_wall_time)), ok.
6824 ok
6825 > lists:map(fun({{I, A0, T0}, {I, A1, T1}}) -> {I, (A1 - A0)/(T1 - T0)} end, lists:zip(Ts0,Ts1)).
6826 [{1,0.9743474730177548},
6827 {2,0.9744843782751444},
6828 {3,0.9995902361669045},
6829 {4,0.9738012596572161},
6830 {5,0.9717956667018103},
6831 {6,0.9739235846420741},
6832 {7,0.973237033077876},
6833 {8,0.9741297293248656}]
6834 Using the same snapshots to calculate a total scheduler utiliza‐
6836 tion:
6837 > {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.
6839 0.9769136803764825
6840 Total scheduler utilization will equal 1.0 when all schedulers
6842 have been active all the time between the two measurements.
6843 Another (probably more) useful value is to calculate total
6845 scheduler utilization weighted against maximum amount of avail‐
6846 able CPU time:
6847 > WeightedSchedulerUtilization = (TotalSchedulerUtilization * (erlang:system_info(schedulers) + erlang:system_info(dirty_cpu_schedulers))) / erlang:system_info(logical_processors_available).
6849 0.9769136803764825
6850 This weighted scheduler utilization will reach 1.0 when sched‐
6852 ulers are active the same amount of time as maximum available
6853 CPU time. If more schedulers exist than available logical pro‐
6854 cessors, this value may be greater than 1.0.
6855 As of ERTS version 9.0, the Erlang runtime system will as
6857 default have more schedulers than logical processors. This due
6858 to the dirty schedulers.
6859 Note:
6861 scheduler_wall_time is by default disabled. To enable it, use
6862 erlang:system_flag(scheduler_wall_time, true).
6863 statistics(Item :: scheduler_wall_time_all) ->
6866 [{SchedulerId, ActiveTime, TotalTime}] | undefined
6867 Types:
6869 SchedulerId = integer() >= 1
6871 ActiveTime = TotalTime = integer() >= 0
6872 The same as statistics(scheduler_wall_time), except that it also
6874 include information about all dirty I/O schedulers.
6875 Dirty IO schedulers will have scheduler identifiers in the range
6877 erlang:system_info(schedulers) + erlang:sys‐
6878 tem_info(dirty_cpu_schedulers) < SchedulerId =< erlang:sys‐
6879 tem_info(schedulers) + erlang:system_info(dirty_cpu_schedulers)
6880 + erlang:system_info(dirty_io_schedulers).
6881 Note:
6883 Note that work executing on dirty I/O schedulers are expected to
6884 mainly wait for I/O. That is, when you get high scheduler uti‐
6885 lization on dirty I/O schedulers, CPU utilization is not
6886 expected to be high due to this work.
6887 statistics(Item :: total_active_tasks) -> ActiveTasks
6890 Types:
6892 ActiveTasks = integer() >= 0
6894 The same as calling lists:sum(statistics(active_tasks)), but
6896 more efficient.
6897 statistics(Item :: total_active_tasks_all) -> ActiveTasks
6899 Types:
6901 ActiveTasks = integer() >= 0
6903 The same as calling lists:sum(statistics(active_tasks_all)), but
6905 more efficient.
6906 statistics(Item :: total_run_queue_lengths) ->
6908 TotalRunQueueLengths
6909 Types:
6911 TotalRunQueueLengths = integer() >= 0
6913 The same as calling lists:sum(statistics(run_queue_lengths)),
6915 but more efficient.
6916 statistics(Item :: total_run_queue_lengths_all) ->
6918 TotalRunQueueLengths
6919 Types:
6921 TotalRunQueueLengths = integer() >= 0
6923 The same as calling lists:sum(statis‐
6925 tics(run_queue_lengths_all)), but more efficient.
6926 statistics(Item :: wall_clock) ->
6928 {Total_Wallclock_Time,
6929 Wallclock_Time_Since_Last_Call}
6930 Types:
6932 Total_Wallclock_Time = Wallclock_Time_Since_Last_Call = inte‐
6934 ger() >= 0
6935 Returns information about wall clock. wall_clock can be used in
6937 the same manner as runtime, except that real time is measured as
6938 opposed to runtime or CPU time.
6939 erlang:suspend_process(Suspendee) -> true
6941 Types:
6943 Suspendee = pid()
6945 Suspends the process identified by Suspendee. The same as call‐
6947 ing erlang:suspend_process(Suspendee, []).
6948 Warning:
6950 This BIF is intended for debugging only.
6951 erlang:suspend_process(Suspendee, OptList) -> boolean()
6954 Types:
6956 Suspendee = pid()
6958 OptList = [Opt]
6959 Opt = unless_suspending | asynchronous | {asynchronous,
6960 term()}
6961 Increases the suspend count on the process identified by Sus‐
6963 pendee and puts it in the suspended state if it is not already
6964 in that state. A suspended process is not scheduled for execu‐
6965 tion until the process has been resumed.
6966 A process can be suspended by multiple processes and can be sus‐
6968 pended multiple times by a single process. A suspended process
6969 does not leave the suspended state until its suspend count
6970 reaches zero. The suspend count of Suspendee is decreased when
6971 erlang:resume_process(Suspendee) is called by the same process
6972 that called erlang:suspend_process(Suspendee). All increased
6973 suspend counts on other processes acquired by a process are
6974 automatically decreased when the process terminates.
6975 Options (Opts):
6977 asynchronous:
6979 A suspend request is sent to the process identified by Sus‐
6980 pendee. Suspendee eventually suspends unless it is resumed
6981 before it could suspend. The caller of erlang:sus‐
6982 pend_process/2 returns immediately, regardless of whether
6983 Suspendee has suspended yet or not. The point in time when
6984 Suspendee suspends cannot be deduced from other events in
6985 the system. It is only guaranteed that Suspendee eventually
6986 suspends (unless it is resumed). If no asynchronous options
6987 has been passed, the caller of erlang:suspend_process/2 is
6988 blocked until Suspendee has suspended.
6989 {asynchronous, ReplyTag}:
6991 A suspend request is sent to the process identified by Sus‐
6992 pendee. When the suspend request has been processed, a reply
6993 message is sent to the caller of this function. The reply is
6994 on the form {ReplyTag, State} where State is either:
6995 exited:
6997 Suspendee has exited.
6998 suspended:
7000 Suspendee is now suspended.
7001 not_suspended:
7003 Suspendee is not suspended. This can only happen when the
7004 process that issued this request, have called
7005 resume_process(Suspendee) before getting the reply.
7006 Appart from the reply message, the {asynchronous, ReplyTag}
7008 option behaves exactly the same as the asynchronous option
7009 without reply tag.
7010 unless_suspending:
7012 The process identified by Suspendee is suspended unless the
7013 calling process already is suspending Suspendee. If
7014 unless_suspending is combined with option asynchronous, a
7015 suspend request is sent unless the calling process already
7016 is suspending Suspendee or if a suspend request already has
7017 been sent and is in transit. If the calling process already
7018 is suspending Suspendee, or if combined with option asyn‐
7019 chronous and a send request already is in transit, false is
7020 returned and the suspend count on Suspendee remains
7021 unchanged.
7022 If the suspend count on the process identified by Suspendee is
7024 increased, true is returned, otherwise false.
7025 Warning:
7027 This BIF is intended for debugging only.
7028 Warning:
7031 You can easily create deadlocks if processes suspends each other
7032 (directly or in circles). In ERTS versions prior to ERTS version
7033 10.0, the runtime system prevented such deadlocks, but this pre‐
7034 vention has now been removed due to performance reasons.
7035 Failures:
7038 badarg:
7040 If Suspendee is not a process identifier.
7041 badarg:
7043 If the process identified by Suspendee is the same process
7044 as the process calling erlang:suspend_process/2.
7045 badarg:
7047 If the process identified by Suspendee is not alive.
7048 badarg:
7050 If the process identified by Suspendee resides on another
7051 node.
7052 badarg:
7054 If OptList is not a proper list of valid Opts.
7055 system_limit:
7057 If the process identified by Suspendee has been suspended
7058 more times by the calling process than can be represented by
7059 the currently used internal data structures. The system
7060 limit is > 2,000,000,000 suspends and will never be lower.
7061 erlang:system_flag(Flag :: backtrace_depth, Depth) -> OldDepth
7063 Types:
7065 Depth = OldDepth = integer() >= 0
7067 Sets the maximum depth of call stack back-traces in the exit
7069 reason element of 'EXIT' tuples. The flag also limits the stack‐
7070 trace depth returned by process_info item current_stacktrace.
7071 Returns the old value of the flag.
7073 erlang:system_flag(Flag :: cpu_topology, CpuTopology) ->
7075 OldCpuTopology
7076 Types:
7078 CpuTopology = OldCpuTopology = cpu_topology()
7080 cpu_topology() = [LevelEntry :: level_entry()] | undefined
7081 level_entry() =
7082 {LevelTag :: level_tag(), SubLevel :: sub_level()} |
7083 {LevelTag :: level_tag(),
7084 InfoList :: info_list(),
7085 SubLevel :: sub_level()}
7086 level_tag() = core | node | processor | thread
7087 sub_level() =
7088 [LevelEntry :: level_entry()] |
7089 (LogicalCpuId :: {logical, integer() >= 0})
7090 info_list() = []
7091 Warning:
7093 This argument is deprecated. Instead of using this argument, use
7094 command-line argument +sct in erl(1).
7095 When this argument is removed, a final CPU topology to use is
7097 determined at emulator boot time.
7098 Sets the user-defined CpuTopology. The user-defined CPU topology
7101 overrides any automatically detected CPU topology. By passing
7102 undefined as CpuTopology, the system reverts to the CPU topology
7103 automatically detected. The returned value equals the value
7104 returned from erlang:system_info(cpu_topology) before the change
7105 was made.
7106 Returns the old value of the flag.
7108 The CPU topology is used when binding schedulers to logical pro‐
7110 cessors. If schedulers are already bound when the CPU topology
7111 is changed, the schedulers are sent a request to rebind accord‐
7112 ing to the new CPU topology.
7113 The user-defined CPU topology can also be set by passing com‐
7115 mand-line argument +sct to erl(1).
7116 For information on type CpuTopology and more, see erlang:sys‐
7118 tem_info(cpu_topology) as well as command-line flags +sct and
7119 +sbt in erl(1).
7120 erlang:system_flag(Flag :: dirty_cpu_schedulers_online,
7122 DirtyCPUSchedulersOnline) ->
7123 OldDirtyCPUSchedulersOnline
7124 Types:
7126 DirtyCPUSchedulersOnline = OldDirtyCPUSchedulersOnline =
7128 integer() >= 1
7129 Sets the number of dirty CPU schedulers online. Range is 1 <=
7131 DirtyCPUSchedulersOnline <= N, where N is the smallest of the
7132 return values of erlang:system_info(dirty_cpu_schedulers) and
7133 erlang:system_info(schedulers_online).
7134 Returns the old value of the flag.
7136 The number of dirty CPU schedulers online can change if the num‐
7138 ber of schedulers online changes. For example, if 12 schedulers
7139 and 6 dirty CPU schedulers are online, and system_flag/2 is used
7140 to set the number of schedulers online to 6, then the number of
7141 dirty CPU schedulers online is automatically decreased by half
7142 as well, down to 3. Similarly, the number of dirty CPU sched‐
7143 ulers online increases proportionally to increases in the number
7144 of schedulers online.
7145 For more information, see erlang:system_info(dirty_cpu_sched‐
7147 ulers) and erlang:system_info(dirty_cpu_schedulers_online).
7148 erlang:system_flag(Flag :: erts_alloc, Value :: {Alloc, F, V}) ->
7150 ok | notsup
7151 Types:
7153 Alloc = F = atom()
7155 V = integer()
7156 Sets system flags for erts_alloc(3). Alloc is the allocator to
7158 affect, for example binary_alloc. F is the flag to change and V
7159 is the new value.
7160 Only a subset of all erts_alloc flags can be changed at run
7162 time. This subset is currently only the flag sbct.
7163 Returns ok if the flag was set or notsup if not supported by
7165 erts_alloc.
7166 erlang:system_flag(Flag :: fullsweep_after, Number) -> OldNumber
7168 Types:
7170 Number = OldNumber = integer() >= 0
7172 Sets system flag fullsweep_after. Number is a non-negative inte‐
7174 ger indicating how many times generational garbage collections
7175 can be done without forcing a fullsweep collection. The value
7176 applies to new processes, while processes already running are
7177 not affected.
7178 Returns the old value of the flag.
7180 In low-memory systems (especially without virtual memory), set‐
7182 ting the value to 0 can help to conserve memory.
7183 This value can also be set through (OS) environment variable
7185 ERL_FULLSWEEP_AFTER.
7186 erlang:system_flag(Flag :: microstate_accounting, Action) ->
7188 OldState
7189 Types:
7191 Action = true | false | reset
7193 OldState = true | false
7194 Turns on/off microstate accounting measurements. When passing
7196 reset, all counters are reset to 0.
7197 For more information see statistics(microstate_accounting).
7199 erlang:system_flag(Flag :: min_heap_size, MinHeapSize) ->
7201 OldMinHeapSize
7202 Types:
7204 MinHeapSize = OldMinHeapSize = integer() >= 0
7206 Sets the default minimum heap size for processes. The size is
7208 specified in words. The new min_heap_size effects only processes
7209 spawned after the change of min_heap_size has been made.
7210 min_heap_size can be set for individual processes by using
7211 spawn_opt/4 or process_flag/2.
7212 Returns the old value of the flag.
7214 erlang:system_flag(Flag :: min_bin_vheap_size, MinBinVHeapSize) ->
7216 OldMinBinVHeapSize
7217 Types:
7219 MinBinVHeapSize = OldMinBinVHeapSize = integer() >= 0
7221 Sets the default minimum binary virtual heap size for processes.
7223 The size is specified in words. The new min_bin_vhheap_size
7224 effects only processes spawned after the change of
7225 min_bin_vheap_size has been made. min_bin_vheap_size can be set
7226 for individual processes by using spawn_opt/2,3,4 or
7227 process_flag/2.
7228 Returns the old value of the flag.
7230 erlang:system_flag(Flag :: max_heap_size, MaxHeapSize) ->
7232 OldMaxHeapSize
7233 Types:
7235 MaxHeapSize = OldMaxHeapSize = max_heap_size()
7237 max_heap_size() =
7238 integer() >= 0 |
7239 #{size => integer() >= 0,
7240 kill => boolean(),
7241 error_logger => boolean()}
7242 Sets the default maximum heap size settings for processes. The
7244 size is specified in words. The new max_heap_size effects only
7245 processes spawned efter the change has been made. max_heap_size
7246 can be set for individual processes using spawn_opt/2,3,4 or
7247 process_flag/2.
7248 Returns the old value of the flag.
7250 erlang:system_flag(Flag :: multi_scheduling, BlockState) ->
7252 OldBlockState
7253 Types:
7255 BlockState = block | unblock | block_normal | unblock_normal
7257 OldBlockState = blocked | disabled | enabled
7258 If multi-scheduling is enabled, more than one scheduler thread
7260 is used by the emulator. Multi-scheduling can be blocked in two
7261 different ways. Either all schedulers but one is blocked, or all
7262 normal schedulers but one is blocked. When only normal sched‐
7263 ulers are blocked, dirty schedulers are free to continue to
7264 schedule processes.
7265 If BlockState =:= block, multi-scheduling is blocked. That is,
7267 one and only one scheduler thread will execute. If BlockState
7268 =:= unblock and no one else blocks multi-scheduling, and this
7269 process has blocked only once, multi-scheduling is unblocked.
7270 If BlockState =:= block_normal, normal multi-scheduling is
7272 blocked. That is, only one normal scheduler thread will execute,
7273 but multiple dirty schedulers can execute. If BlockState =:=
7274 unblock_normal and no one else blocks normal multi-scheduling,
7275 and this process has blocked only once, normal multi-scheduling
7276 is unblocked.
7277 One process can block multi-scheduling and normal multi-schedul‐
7279 ing multiple times. If a process has blocked multiple times, it
7280 must unblock exactly as many times as it has blocked before it
7281 has released its multi-scheduling block. If a process that has
7282 blocked multi-scheduling or normal multi-scheduling exits, it
7283 automatically releases its blocking of multi-scheduling and nor‐
7284 mal multi-scheduling.
7285 The return values are disabled, blocked, blocked_normal, or
7287 enabled. The returned value describes the state just after the
7288 call to erlang:system_flag(multi_scheduling, BlockState) has
7289 been made. For information about the return values, see
7290 erlang:system_info(multi_scheduling).
7291 Note:
7293 Blocking of multi-scheduling and normal multi-scheduling is nor‐
7294 mally not needed. If you feel that you need to use these fea‐
7295 tures, consider it a few more times again. Blocking multi-sched‐
7296 uling is only to be used as a last resort, as it is most likely
7297 a very inefficient way to solve the problem.
7298 See also erlang:system_info(multi_scheduling), erlang:sys‐
7301 tem_info(normal_multi_scheduling_blockers), erlang:sys‐
7302 tem_info(multi_scheduling_blockers), and erlang:sys‐
7303 tem_info(schedulers).
7304 erlang:system_flag(Flag :: scheduler_bind_type, How) ->
7306 OldBindType
7307 Types:
7309 How = scheduler_bind_type() | default_bind
7311 OldBindType = scheduler_bind_type()
7312 scheduler_bind_type() =
7313 no_node_processor_spread | no_node_thread_spread | no_spread |
7314 processor_spread | spread | thread_spread |
7315 thread_no_node_processor_spread | unbound
7316 Warning:
7318 This argument is deprecated. Instead of using this argument, use
7319 command-line argument +sbt in erl(1). When this argument is
7320 removed, a final scheduler bind type to use is determined at
7321 emulator boot time.
7322 Controls if and how schedulers are bound to logical processors.
7325 When erlang:system_flag(scheduler_bind_type, How) is called, an
7327 asynchronous signal is sent to all schedulers online, causing
7328 them to try to bind or unbind as requested.
7329 Note:
7331 If a scheduler fails to bind, this is often silently ignored, as
7332 it is not always possible to verify valid logical processor
7333 identifiers. If an error is reported, an error event is logged.
7334 To verify that the schedulers have bound as requested, call
7335 erlang:system_info(scheduler_bindings).
7336 Schedulers can be bound on newer Linux, Solaris, FreeBSD, and
7339 Windows systems, but more systems will be supported in future
7340 releases.
7341 In order for the runtime system to be able to bind schedulers,
7343 the CPU topology must be known. If the runtime system fails to
7344 detect the CPU topology automatically, it can be defined. For
7345 more information on how to define the CPU topology, see command-
7346 line flag +sct in erl(1).
7347 The runtime system does by default not bind schedulers to logi‐
7349 cal processors.
7350 Note:
7352 If the Erlang runtime system is the only OS process binding
7353 threads to logical processors, this improves the performance of
7354 the runtime system. However, if other OS processes (for example,
7355 another Erlang runtime system) also bind threads to logical pro‐
7356 cessors, there can be a performance penalty instead. Sometimes
7357 this performance penalty can be severe. If so, it is recommended
7358 to not bind the schedulers.
7359 Schedulers can be bound in different ways. Argument How deter‐
7362 mines how schedulers are bound and can be any of the following:
7363 unbound:
7365 Same as command-line argument +sbt u in erl(1).
7366 no_spread:
7368 Same as command-line argument +sbt ns in erl(1).
7369 thread_spread:
7371 Same as command-line argument +sbt ts in erl(1).
7372 processor_spread:
7374 Same as command-line argument +sbt ps in erl(1).
7375 spread:
7377 Same as command-line argument +sbt s in erl(1).
7378 no_node_thread_spread:
7380 Same as command-line argument +sbt nnts in erl(1).
7381 no_node_processor_spread:
7383 Same as command-line argument +sbt nnps in erl(1).
7384 thread_no_node_processor_spread:
7386 Same as command-line argument +sbt tnnps in erl(1).
7387 default_bind:
7389 Same as command-line argument +sbt db in erl(1).
7390 The returned value equals How before flag scheduler_bind_type
7392 was changed.
7393 Failures:
7395 notsup:
7397 If binding of schedulers is not supported.
7398 badarg:
7400 If How is not one of the documented alternatives.
7401 badarg:
7403 If CPU topology information is unavailable.
7404 The scheduler bind type can also be set by passing command-line
7406 argument +sbt to erl(1).
7407 For more information, see erlang:system_info(sched‐
7409 uler_bind_type), erlang:system_info(scheduler_bindings), as well
7410 as command-line flags +sbt and +sct in erl(1).
7411 erlang:system_flag(Flag :: scheduler_wall_time, Boolean) ->
7413 OldBoolean
7414 Types:
7416 Boolean = OldBoolean = boolean()
7418 Turns on or off scheduler wall time measurements.
7420 For more information, see statistics(scheduler_wall_time).
7422 erlang:system_flag(Flag :: schedulers_online, SchedulersOnline) ->
7424 OldSchedulersOnline
7425 Types:
7427 SchedulersOnline = OldSchedulersOnline = integer() >= 1
7429 Sets the number of schedulers online. Range is 1 <= Scheduler‐
7431 sOnline <= erlang:system_info(schedulers).
7432 Returns the old value of the flag.
7434 If the emulator was built with support for dirty schedulers,
7436 changing the number of schedulers online can also change the
7437 number of dirty CPU schedulers online. For example, if 12 sched‐
7438 ulers and 6 dirty CPU schedulers are online, and system_flag/2
7439 is used to set the number of schedulers online to 6, then the
7440 number of dirty CPU schedulers online is automatically decreased
7441 by half as well, down to 3. Similarly, the number of dirty CPU
7442 schedulers online increases proportionally to increases in the
7443 number of schedulers online.
7444 For more information, see erlang:system_info(schedulers) and
7446 erlang:system_info(schedulers_online).
7447 erlang:system_flag(Flag :: system_logger, Logger) -> PrevLogger
7449 Types:
7451 Logger = PrevLogger = logger | undefined | pid()
7453 Sets the process that will receive the logging messages gener‐
7455 ated by ERTS. If set to undefined, all logging messages gener‐
7456 ated by ERTS will be dropped. The messages will be in the for‐
7457 mat:
7458 {log,Level,Format,ArgList,Metadata} where
7460 Level = atom(),
7462 Format = string(),
7463 ArgList = list(term()),
7464 Metadata = #{ pid => pid(),
7465 group_leader => pid(),
7466 time := logger:timestamp(),
7467 error_logger := #{ emulator := true, tag := atom() }
7468 If the system_logger process dies, this flag will be reset to
7471 logger.
7472 The default is the process named logger.
7474 Returns the old value of the flag.
7476 Note:
7478 This function is designed to be used by the KERNEL logger. Be
7479 careful if you change it to something else as log messages may
7480 be lost. If you want to intercept emulator log messages, do it
7481 by adding a specialized handler to the KERNEL logger.
7482 erlang:system_flag(Flag :: trace_control_word, TCW) -> OldTCW
7485 Types:
7487 TCW = OldTCW = integer() >= 0
7489 Sets the value of the node trace control word to TCW, which is
7491 to be an unsigned integer. For more information, see function
7492 set_tcw in section "Match Specifications in Erlang" in the
7493 User's Guide.
7494 Returns the old value of the flag.
7496 erlang:system_flag(Flag :: time_offset, Value :: finalize) ->
7498 OldState
7499 Types:
7501 OldState = preliminary | final | volatile
7503 Finalizes the time offset when single time warp mode is used. If
7505 another time warp mode is used, the time offset state is left
7506 unchanged.
7507 Returns the old state identifier, that is:
7509 * If preliminary is returned, finalization was performed and
7511 the time offset is now final.
7512 * If final is returned, the time offset was already in the
7514 final state. This either because another erlang:sys‐
7515 tem_flag(time_offset, finalize) call or because no time warp
7516 mode is used.
7517 * If volatile is returned, the time offset cannot be finalized
7519 because multi-time warp mode is used.
7520 erlang:system_info(Item ::
7522 wordsize |
7523 {wordsize, internal} |
7524 {wordsize, external}) ->
7525 4 | 8
7526 Returns information about the current system. The documentation
7528 of this function is broken into the following sections in order
7529 to make it easier to navigate.
7530 Memory Allocation:
7532 allocated_areas, allocator, alloc_util_allocators, alloca‐
7533 tor_sizes, elib_malloc
7534 CPU Topology:
7536 cpu_topology, logical_processors, update_cpu_info
7537 Process Information:
7539 fullsweep_after, garbage_collection, heap_sizes, heap_type,
7540 max_heap_size, message_queue_data, min_heap_size,
7541 min_bin_vheap_size, procs
7542 System Limits:
7544 atom_count, atom_limit, ets_count, ets_limit, port_count,
7545 port_limit, process_count, process_limit
7546 System Time:
7548 end_time, os_monotonic_time_source, os_system_time_source,
7549 start_time, time_correction, time_offset, time_warp_mode,
7550 tolerant_timeofday
7551 Scheduler Information:
7553 dirty_cpu_schedulers, dirty_cpu_schedulers_online,
7554 dirty_io_schedulers, multi_scheduling, multi_schedul‐
7555 ing_blockers, normal_multi_scheduling_blockers, sched‐
7556 uler_bind_type, scheduler_bindings, scheduler_id, sched‐
7557 ulers, smp_support, threads, thread_pool_size
7558 Distribution Information:
7560 creation, delayed_node_table_gc, dist, dist_buf_busy_limit,
7561 dist_ctrl
7562 System Information:
7564 build_type, c_compiler_used, check_io, compat_rel,
7565 debug_compiled, driver_version, dynamic_trace,
7566 dynamic_trace_probes, info, kernel_poll, loaded, machine,
7567 modified_timing_level, nif_version, otp_release, port_paral‐
7568 lelism, system_architecture, system_logger, system_version,
7569 trace_control_word, version, wordsize
7570 erlang:system_info(Item :: allocated_areas) -> [tuple()]
7572 erlang:system_info(Item :: allocator) ->
7574 {Allocator, Version, Features, Settings}
7575 erlang:system_info(Item :: {allocator, Alloc}) -> [term()]
7577 erlang:system_info(Item :: alloc_util_allocators) -> [Alloc]
7579 erlang:system_info(Item :: {allocator_sizes, Alloc}) -> [term()]
7581 erlang:system_info(Item :: elib_malloc) -> false
7583 Types:
7585 Allocator = undefined | glibc
7587 Version = [integer() >= 0]
7588 Features = [atom()]
7589 Settings =
7590 [{Subsystem :: atom(),
7591 [{Parameter :: atom(), Value :: term()}]}]
7592 Alloc = atom()
7593 Returns various information about the memory allocators of the
7595 current system (emulator) as specified by Item:
7596 allocated_areas:
7598 Returns a list of tuples with information about miscella‐
7599 neous allocated memory areas.
7600 Each tuple contains an atom describing the type of memory as
7602 first element and the amount of allocated memory in bytes as
7603 second element. When information about allocated and used
7604 memory is present, also a third element is present, contain‐
7605 ing the amount of used memory in bytes.
7606 erlang:system_info(allocated_areas) is intended for debug‐
7608 ging, and the content is highly implementation-dependent.
7609 The content of the results therefore changes when needed
7610 without prior notice.
7611 Notice that the sum of these values is not the total amount
7613 of memory allocated by the emulator. Some values are part of
7614 other values, and some memory areas are not part of the
7615 result. For information about the total amount of memory
7616 allocated by the emulator, see erlang:memory/0,1.
7617 allocator:
7619 Returns {Allocator, Version, Features, Settings, where:
7620 * Allocator corresponds to the malloc() implementation used.
7622 If Allocator equals undefined, the malloc() implementation
7623 used cannot be identified. glibc can be identified.
7624 * Version is a list of integers (but not a string) repre‐
7626 senting the version of the malloc() implementation used.
7627 * Features is a list of atoms representing the allocation
7629 features used.
7630 * Settings is a list of subsystems, their configurable
7632 parameters, and used values. Settings can differ between
7633 different combinations of platforms, allocators, and allo‐
7634 cation features. Memory sizes are given in bytes.
7635 See also "System Flags Effecting erts_alloc" in
7637 erts_alloc(3).
7638 {allocator, Alloc}:
7640 Returns information about the specified allocator. As from
7641 ERTS 5.6.1, the return value is a list of {instance, Instan‐
7642 ceNo, InstanceInfo} tuples, where InstanceInfo contains
7643 information about a specific instance of the allocator. If
7644 Alloc is not a recognized allocator, undefined is returned.
7645 If Alloc is disabled, false is returned.
7646 Notice that the information returned is highly implementa‐
7648 tion-dependent and can be changed or removed at any time
7649 without prior notice. It was initially intended as a tool
7650 when developing new allocators, but as it can be of interest
7651 for others it has been briefly documented.
7652 The recognized allocators are listed in erts_alloc(3).
7654 Information about super carriers can be obtained from ERTS
7655 8.0 with {allocator, erts_mmap} or from ERTS 5.10.4; the
7656 returned list when calling with {allocator, mseg_alloc} also
7657 includes an {erts_mmap, _} tuple as one element in the list.
7658 After reading the erts_alloc(3) documentation, the returned
7660 information more or less speaks for itself, but it can be
7661 worth explaining some things. Call counts are presented by
7662 two values, the first value is giga calls, and the second
7663 value is calls. mbcs and sbcs denote multi-block carriers,
7664 and single-block carriers, respectively. Sizes are presented
7665 in bytes. When a size is not presented, it is the amount of
7666 something. Sizes and amounts are often presented by three
7667 values:
7668 * The first is the current value.
7670 * The second is the maximum value since the last call to
7672 erlang:system_info({allocator, Alloc}).
7673 * The third is the maximum value since the emulator was
7675 started.
7676 If only one value is present, it is the current value.
7678 fix_alloc memory block types are presented by two values.
7679 The first value is the memory pool size and the second value
7680 is the used memory size.
7681 alloc_util_allocators:
7683 Returns a list of the names of all allocators using the ERTS
7684 internal alloc_util framework as atoms. For more informa‐
7685 tion, see section The alloc_util framework in erts_alloc(3).
7686 {allocator_sizes, Alloc}:
7688 Returns various size information for the specified alloca‐
7689 tor. The information returned is a subset of the information
7690 returned by erlang:system_info({allocator, Alloc}).
7691 elib_malloc:
7693 This option will be removed in a future release. The return
7694 value will always be false, as the elib_malloc allocator has
7695 been removed.
7696 erlang:system_info(Item :: cpu_topology) -> CpuTopology
7698 erlang:system_info(Item ::
7700 {cpu_topology, defined | detected | used}) ->
7701 CpuTopology
7702 erlang:system_info(Item ::
7704 logical_processors |
7705 logical_processors_available |
7706 logical_processors_online) ->
7707 unknown | integer() >= 1
7708 erlang:system_info(Item :: update_cpu_info) -> changed | unchanged
7710 Types:
7712 cpu_topology() = [LevelEntry :: level_entry()] | undefined
7714 All LevelEntrys of a list must contain the same LevelTag,
7715 except on the top level where both node and processor‐
7716 LevelTags can coexist.
7717 level_entry() =
7718 {LevelTag :: level_tag(), SubLevel :: sub_level()} |
7719 {LevelTag :: level_tag(),
7720 InfoList :: info_list(),
7721 SubLevel :: sub_level()}
7722 {LevelTag, SubLevel} == {LevelTag, [], SubLevel}
7723 level_tag() = core | node | processor | thread
7724 More LevelTags can be introduced in a future release.
7725 sub_level() =
7726 [LevelEntry :: level_entry()] |
7727 (LogicalCpuId :: {logical, integer() >= 0})
7728 info_list() = []
7729 The info_list() can be extended in a future release.
7730 Returns various information about the CPU topology of the cur‐
7732 rent system (emulator) as specified by Item:
7733 cpu_topology:
7735 Returns the CpuTopology currently used by the emulator. The
7736 CPU topology is used when binding schedulers to logical pro‐
7737 cessors. The CPU topology used is the user-defined CPU
7738 topology, if such exists, otherwise the automatically
7739 detected CPU topology, if such exists. If no CPU topology
7740 exists, undefined is returned.
7741 node refers to Non-Uniform Memory Access (NUMA) nodes.
7743 thread refers to hardware threads (for example, Intel hyper-
7744 threads).
7745 A level in term CpuTopology can be omitted if only one entry
7747 exists and InfoList is empty.
7748 thread can only be a sublevel to core. core can be a sub‐
7750 level to processor or node. processor can be on the top
7751 level or a sublevel to node. node can be on the top level or
7752 a sublevel to processor. That is, NUMA nodes can be proces‐
7753 sor internal or processor external. A CPU topology can con‐
7754 sist of a mix of processor internal and external NUMA nodes,
7755 as long as each logical CPU belongs to one NUMA node. Cache
7756 hierarchy is not part of the CpuTopology type, but will be
7757 in a future release. Other things can also make it into the
7758 CPU topology in a future release. So, expect the CpuTopology
7759 type to change.
7760 {cpu_topology, defined}:
7762 Returns the user-defined CpuTopology. For more information,
7765 see command-line flag +sct in erl(1) and argument cpu_topol‐
7766 ogy.
7767 {cpu_topology, detected}:
7769 Returns the automatically detected CpuTopologyy. The emula‐
7772 tor detects the CPU topology on some newer Linux, Solaris,
7773 FreeBSD, and Windows systems. On Windows system with more
7774 than 32 logical processors, the CPU topology is not
7775 detected.
7776 For more information, see argument cpu_topology.
7778 {cpu_topology, used}:
7780 Returns CpuTopology used by the emulator. For more informa‐
7781 tion, see argument cpu_topology.
7782 logical_processors:
7784 Returns the detected number of logical processors configured
7785 in the system. The return value is either an integer, or the
7786 atom unknown if the emulator cannot detect the configured
7787 logical processors.
7788 logical_processors_available:
7790 Returns the detected number of logical processors available
7791 to the Erlang runtime system. The return value is either an
7792 integer, or the atom unknown if the emulator cannot detect
7793 the available logical processors. The number of available
7794 logical processors is less than or equal to the number of
7795 logical processors online.
7796 logical_processors_online:
7798 Returns the detected number of logical processors online on
7799 the system. The return value is either an integer, or the
7800 atom unknown if the emulator cannot detect logical proces‐
7801 sors online. The number of logical processors online is less
7802 than or equal to the number of logical processors config‐
7803 ured.
7804 update_cpu_info:
7806 The runtime system rereads the CPU information available and
7807 updates its internally stored information about the detected
7808 CPU topology and the number of logical processors config‐
7809 ured, online, and available.
7810 If the CPU information has changed since the last time it
7812 was read, the atom changed is returned, otherwise the atom
7813 unchanged. If the CPU information has changed, you probably
7814 want to adjust the number of schedulers online. You typi‐
7815 cally want to have as many schedulers online as logical pro‐
7816 cessors available.
7817 erlang:system_info(Item :: fullsweep_after) ->
7819 {fullsweep_after, integer() >= 0}
7820 erlang:system_info(Item :: garbage_collection) ->
7822 [{atom(), integer()}]
7823 erlang:system_info(Item :: heap_sizes) -> [integer() >= 0]
7825 erlang:system_info(Item :: heap_type) -> private
7827 erlang:system_info(Item :: max_heap_size) ->
7829 {max_heap_size,
7830 MaxHeapSize :: max_heap_size()}
7831 erlang:system_info(Item :: message_queue_data) ->
7833 message_queue_data()
7834 erlang:system_info(Item :: min_heap_size) ->
7836 {min_heap_size,
7837 MinHeapSize :: integer() >= 1}
7838 erlang:system_info(Item :: min_bin_vheap_size) ->
7840 {min_bin_vheap_size,
7841 MinBinVHeapSize :: integer() >= 1}
7842 erlang:system_info(Item :: procs) -> binary()
7844 Types:
7846 message_queue_data() = off_heap | on_heap
7848 max_heap_size() =
7849 integer() >= 0 |
7850 #{size => integer() >= 0,
7851 kill => boolean(),
7852 error_logger => boolean()}
7853 Returns information about the default process heap settings:
7855 fullsweep_after:
7857 Returns {fullsweep_after, integer() >= 0}, which is the
7858 fullsweep_after garbage collection setting used by default.
7859 For more information, see garbage_collection described
7860 below.
7861 garbage_collection:
7863 Returns a list describing the default garbage collection
7864 settings. A process spawned on the local node by a spawn or
7865 spawn_link uses these garbage collection settings. The
7866 default settings can be changed by using erlang:sys‐
7867 tem_flag/2. spawn_opt/2,3,4 can spawn a process that does
7868 not use the default settings.
7869 heap_sizes:
7871 Returns a list of integers representing valid heap sizes in
7872 words. All Erlang heaps are sized from sizes in this list.
7873 heap_type:
7875 Returns the heap type used by the current emulator. One heap
7876 type exists:
7877 private:
7879 Each process has a heap reserved for its use and no ref‐
7880 erences between heaps of different processes are allowed.
7881 Messages passed between processes are copied between
7882 heaps.
7883 max_heap_size:
7885 Returns {max_heap_size, MaxHeapSize}, where MaxHeapSize is
7886 the current system-wide maximum heap size settings for
7887 spawned processes. This setting can be set using the com‐
7888 mand-line flags +hmax, +hmaxk and +hmaxel in erl(1). It can
7889 also be changed at runtime using erlang:sys‐
7890 tem_flag(max_heap_size, MaxHeapSize). For more details about
7891 the max_heap_size process flag, see
7892 process_flag(max_heap_size, MaxHeapSize).
7893 message_queue_data:
7895 Returns the default value of the message_queue_data process
7896 flag, which is either off_heap or on_heap. This default is
7897 set by command-line argument +hmqd in erl(1). For more
7898 information on the message_queue_data process flag, see doc‐
7899 umentation of process_flag(message_queue_data, MQD).
7900 min_heap_size:
7902 Returns {min_heap_size, MinHeapSize}, where MinHeapSize is
7903 the current system-wide minimum heap size for spawned pro‐
7904 cesses.
7905 min_bin_vheap_size:
7907 Returns {min_bin_vheap_size, MinBinVHeapSize}, where MinBin‐
7908 VHeapSize is the current system-wide minimum binary virtual
7909 heap size for spawned processes.
7910 procs:
7912 Returns a binary containing a string of process and port
7913 information formatted as in Erlang crash dumps. For more
7914 information, see section How to interpret the Erlang crash
7915 dumps in the User's Guide.
7916 erlang:system_info(Item :: atom_count) -> integer() >= 1
7918 erlang:system_info(Item :: atom_limit) -> integer() >= 1
7920 erlang:system_info(Item :: ets_count) -> integer() >= 1
7922 erlang:system_info(Item :: ets_limit) -> integer() >= 1
7924 erlang:system_info(Item :: port_count) -> integer() >= 0
7926 erlang:system_info(Item :: port_limit) -> integer() >= 1
7928 erlang:system_info(Item :: process_count) -> integer() >= 1
7930 erlang:system_info(Item :: process_limit) -> integer() >= 1
7932 Returns information about the current system (emulator) limits
7934 as specified by Item:
7935 atom_count:
7937 Returns the number of atoms currently existing at the local
7938 node. The value is given as an integer.
7939 atom_limit:
7941 Returns the maximum number of atoms allowed. This limit can
7942 be increased at startup by passing command-line flag +t to
7943 erl(1).
7944 ets_count:
7946 Returns the number of ETS tables currently existing at the
7947 local node.
7948 ets_limit:
7950 Returns the limit for number of ETS tables. This limit is
7951 partially obsolete and number of tables are only limited by
7952 available memory.
7953 port_count:
7955 Returns the number of ports currently existing at the local
7956 node. The value is given as an integer. This is the same
7957 value as returned by length(erlang:ports()), but more effi‐
7958 cient.
7959 port_limit:
7961 Returns the maximum number of simultaneously existing ports
7962 at the local node as an integer. This limit can be config‐
7963 ured at startup by using command-line flag +Q in erl(1).
7964 process_count:
7966 Returns the number of processes currently existing at the
7967 local node. The value is given as an integer. This is the
7968 same value as returned by length(processes()), but more
7969 efficient.
7970 process_limit:
7972 Returns the maximum number of simultaneously existing pro‐
7973 cesses at the local node. The value is given as an integer.
7974 This limit can be configured at startup by using command-
7975 line flag +P in erl(1).
7976 erlang:system_info(Item :: end_time) -> integer() >= 0
7978 erlang:system_info(Item :: os_monotonic_time_source) ->
7980 [{atom(), term()}]
7981 erlang:system_info(Item :: os_system_time_source) ->
7983 [{atom(), term()}]
7984 erlang:system_info(Item :: start_time) -> integer()
7986 erlang:system_info(Item :: time_correction) -> true | false
7988 erlang:system_info(Item :: time_offset) ->
7990 preliminary | final | volatile
7991 erlang:system_info(Item :: time_warp_mode) ->
7993 no_time_warp | single_time_warp |
7994 multi_time_warp
7995 erlang:system_info(Item :: tolerant_timeofday) ->
7997 enabled | disabled
7998 Returns information about the current system (emulator) time as
8000 specified by Item:
8001 end_time:
8003 The last Erlang monotonic time in native time unit that can
8004 be represented internally in the current Erlang runtime sys‐
8005 tem instance. The time between the start time and the end
8006 time is at least a quarter of a millennium.
8007 os_monotonic_time_source:
8009 Returns a list containing information about the source of OS
8010 monotonic time that is used by the runtime system.
8011 If [] is returned, no OS monotonic time is available. The
8013 list contains two-tuples with Keys as first element, and
8014 Values as second element. The order of these tuples is unde‐
8015 fined. The following tuples can be part of the list, but
8016 more tuples can be introduced in the future:
8017 {function, Function}:
8019 Function is the name of the function used. This tuple
8020 always exists if OS monotonic time is available to the
8021 runtime system.
8022 {clock_id, ClockId}:
8024 This tuple only exists if Function can be used with dif‐
8025 ferent clocks. ClockId corresponds to the clock identifier
8026 used when calling Function.
8027 {resolution, OsMonotonicTimeResolution}:
8029 Highest possible resolution of current OS monotonic time
8030 source as parts per second. If no resolution information
8031 can be retrieved from the OS, OsMonotonicTimeResolution is
8032 set to the resolution of the time unit of Functions return
8033 value. That is, the actual resolution can be lower than
8034 OsMonotonicTimeResolution. Notice that the resolution does
8035 not say anything about the accuracy or whether the pre‐
8036 cision aligns with the resolution. You do, however, know
8037 that the precision is not better than OsMonotonicTimeReso‐
8038 lution.
8039 {extended, Extended}:
8041 Extended equals yes if the range of time values has been
8042 extended; otherwise Extended equals no. The range must be
8043 extended if Function returns values that wrap fast. This
8044 typically is the case when the return value is a 32-bit
8045 value.
8046 {parallel, Parallel}:
8048 Parallel equals yes if Function is called in parallel from
8049 multiple threads. If it is not called in parallel, because
8050 calls must be serialized, Parallel equals no.
8051 {time, OsMonotonicTime}:
8053 OsMonotonicTime equals current OS monotonic time in native
8054 time unit.
8055 os_system_time_source:
8057 Returns a list containing information about the source of OS
8058 system time that is used by the runtime system.
8059 The list contains two-tuples with Keys as first element, and
8061 Values as second element. The order of these tuples is unde‐
8062 fined. The following tuples can be part of the list, but
8063 more tuples can be introduced in the future:
8064 {function, Function}:
8066 Function is the name of the funcion used.
8067 {clock_id, ClockId}:
8069 Exists only if Function can be used with different clocks.
8070 ClockId corresponds to the clock identifier used when
8071 calling Function.
8072 {resolution, OsSystemTimeResolution}:
8074 Highest possible resolution of current OS system time
8075 source as parts per second. If no resolution information
8076 can be retrieved from the OS, OsSystemTimeResolution is
8077 set to the resolution of the time unit of Functions return
8078 value. That is, the actual resolution can be lower than
8079 OsSystemTimeResolution. Notice that the resolution does
8080 not say anything about the accuracy or whether the pre‐
8081 cision do align with the resolution. You do, however, know
8082 that the precision is not better than OsSystemTimeResolu‐
8083 tion.
8084 {parallel, Parallel}:
8086 Parallel equals yes if Function is called in parallel from
8087 multiple threads. If it is not called in parallel, because
8088 calls needs to be serialized, Parallel equals no.
8089 {time, OsSystemTime}:
8091 OsSystemTime equals current OS system time in native time
8092 unit.
8093 start_time:
8095 The Erlang monotonic time in native time unit at the time
8096 when current Erlang runtime system instance started.
8097 See also erlang:system_info(end_time).
8099 time_correction:
8101 Returns a boolean value indicating whether time correction
8102 is enabled or not.
8103 time_offset:
8105 Returns the state of the time offset:
8106 preliminary:
8108 The time offset is preliminary, and will be changed and
8109 finalized later. The preliminary time offset is used dur‐
8110 ing the preliminary phase of the single time warp mode.
8111 final:
8113 The time offset is final. This either because no time
8114 warp mode is used, or because the time offset have been
8115 finalized when single time warp mode is used.
8116 volatile:
8118 The time offset is volatile. That is, it can change at any
8119 time. This is because multi-time warp mode is used.
8120 time_warp_mode:
8122 Returns a value identifying the time warp mode that is
8123 used:
8124 no_time_warp:
8126 The no time warp mode is used.
8127 single_time_warp:
8129 The single time warp mode is used.
8130 multi_time_warp:
8132 The multi-time warp mode is used.
8133 tolerant_timeofday:
8135 Returns whether a pre ERTS 7.0 backwards compatible compen‐
8136 sation for sudden changes of system time is enabled or dis‐
8137 abled. Such compensation is enabled when the time offset is
8138 final, and time correction is enabled.
8139 erlang:system_info(Item :: dirty_cpu_schedulers) ->
8141 integer() >= 0
8142 erlang:system_info(Item :: dirty_cpu_schedulers_online) ->
8144 integer() >= 0
8145 erlang:system_info(Item :: dirty_io_schedulers) ->
8147 integer() >= 0
8148 erlang:system_info(Item :: multi_scheduling) ->
8150 disabled | blocked | blocked_normal |
8151 enabled
8152 erlang:system_info(Item :: multi_scheduling_blockers) ->
8154 [Pid :: pid()]
8155 erlang:system_info(Item :: otp_release) -> string()
8157 erlang:system_info(Item :: scheduler_bind_type) ->
8159 spread | processor_spread | thread_spread |
8160 thread_no_node_processor_spread |
8161 no_node_processor_spread |
8162 no_node_thread_spread | no_spread | unbound
8163 erlang:system_info(Item :: scheduler_bindings) -> tuple()
8165 erlang:system_info(Item :: scheduler_id) ->
8167 SchedulerId :: integer() >= 1
8168 erlang:system_info(Item :: schedulers | schedulers_online) ->
8170 integer() >= 1
8171 erlang:system_info(Item :: smp_support) -> boolean()
8173 erlang:system_info(Item :: threads) -> boolean()
8175 erlang:system_info(Item :: thread_pool_size) -> integer() >= 0
8177 Returns information about schedulers, scheduling and threads in
8179 the current system as specified by Item:
8180 dirty_cpu_schedulers:
8182 Returns the number of dirty CPU scheduler threads used by
8183 the emulator. Dirty CPU schedulers execute CPU-bound native
8184 functions, such as NIFs, linked-in driver code, and BIFs
8185 that cannot be managed cleanly by the normal emulator sched‐
8186 ulers.
8187 The number of dirty CPU scheduler threads is determined at
8189 emulator boot time and cannot be changed after that. How‐
8190 ever, the number of dirty CPU scheduler threads online can
8191 be changed at any time. The number of dirty CPU schedulers
8192 can be set at startup by passing command-line flag +SDcpu or
8193 +SDPcpu in erl(1).
8194 See also erlang:system_flag(dirty_cpu_schedulers_online,
8196 DirtyCPUSchedulersOnline), erlang:sys‐
8197 tem_info(dirty_cpu_schedulers_online), erlang:sys‐
8198 tem_info(dirty_io_schedulers), erlang:system_info(sched‐
8199 ulers), erlang:system_info(schedulers_online), and
8200 erlang:system_flag(schedulers_online, SchedulersOnline).
8201 dirty_cpu_schedulers_online:
8203 Returns the number of dirty CPU schedulers online. The
8204 return value satisfies 1 <= DirtyCPUSchedulersOnline <= N,
8205 where N is the smallest of the return values of erlang:sys‐
8206 tem_info(dirty_cpu_schedulers) and erlang:system_info(sched‐
8207 ulers_online).
8208 The number of dirty CPU schedulers online can be set at
8210 startup by passing command-line flag +SDcpu in erl(1).
8211 For more information, see erlang:sys‐
8213 tem_info(dirty_cpu_schedulers), erlang:sys‐
8214 tem_info(dirty_io_schedulers), erlang:system_info(sched‐
8215 ulers_online), and erlang:system_flag(dirty_cpu_sched‐
8216 ulers_online, DirtyCPUSchedulersOnline).
8217 dirty_io_schedulers:
8219 Returns the number of dirty I/O schedulers as an integer.
8220 Dirty I/O schedulers execute I/O-bound native functions,
8221 such as NIFs and linked-in driver code, which cannot be man‐
8222 aged cleanly by the normal emulator schedulers.
8223 This value can be set at startup by passing command-line
8225 argument +SDio in erl(1).
8226 For more information, see erlang:sys‐
8228 tem_info(dirty_cpu_schedulers), erlang:sys‐
8229 tem_info(dirty_cpu_schedulers_online), and erlang:sys‐
8230 tem_flag(dirty_cpu_schedulers_online, DirtyCPUSchedulersOn‐
8231 line).
8232 multi_scheduling:
8234 Returns one of the following:
8235 disabled:
8237 The emulator has been started with only one scheduler
8238 thread.
8239 blocked:
8241 The emulator has more than one scheduler thread, but all
8242 scheduler threads except one are blocked. That is, only
8243 one scheduler thread schedules Erlang processes and exe‐
8244 cutes Erlang code.
8245 blocked_normal:
8247 The emulator has more than one scheduler thread, but all
8248 normal scheduler threads except one are blocked. Notice
8249 that dirty schedulers are not blocked, and can schedule
8250 Erlang processes and execute native code.
8251 enabled:
8253 The emulator has more than one scheduler thread, and no
8254 scheduler threads are blocked. That is, all available
8255 scheduler threads schedule Erlang processes and execute
8256 Erlang code.
8257 See also erlang:system_flag(multi_scheduling, BlockState),
8259 erlang:system_info(multi_scheduling_blockers), erlang:sys‐
8260 tem_info(normal_multi_scheduling_blockers), and erlang:sys‐
8261 tem_info(schedulers).
8262 multi_scheduling_blockers:
8264 Returns a list of Pids when multi-scheduling is blocked,
8265 otherwise the empty list is returned. The Pids in the list
8266 represent all the processes currently blocking multi-sched‐
8267 uling. A Pid occurs only once in the list, even if the cor‐
8268 responding process has blocked multiple times.
8269 See also erlang:system_flag(multi_scheduling, BlockState),
8271 erlang:system_info(multi_scheduling), erlang:sys‐
8272 tem_info(normal_multi_scheduling_blockers), and erlang:sys‐
8273 tem_info(schedulers).
8274 normal_multi_scheduling_blockers:
8276 Returns a list of Pids when normal multi-scheduling is
8277 blocked (that is, all normal schedulers but one is blocked),
8278 otherwise the empty list is returned. The Pids in the list
8279 represent all the processes currently blocking normal multi-
8280 scheduling. A Pid occurs only once in the list, even if the
8281 corresponding process has blocked multiple times.
8282 See also erlang:system_flag(multi_scheduling, BlockState),
8284 erlang:system_info(multi_scheduling), erlang:sys‐
8285 tem_info(multi_scheduling_blockers), and erlang:sys‐
8286 tem_info(schedulers).
8287 scheduler_bind_type:
8289 Returns information about how the user has requested sched‐
8290 ulers to be bound or not bound.
8291 Notice that although a user has requested schedulers to be
8293 bound, they can silently have failed to bind. To inspect the
8294 scheduler bindings, call erlang:system_info(scheduler_bind‐
8295 ings).
8296 For more information, see command-line argument +sbt in
8298 erl(1) and erlang:system_info(scheduler_bindings).
8299 scheduler_bindings:
8301 Returns information about the currently used scheduler bind‐
8302 ings.
8303 A tuple of a size equal to erlang:system_info(schedulers) is
8305 returned. The tuple elements are integers or the atom
8306 unbound. Logical processor identifiers are represented as
8307 integers. The Nth element of the tuple equals the current
8308 binding for the scheduler with the scheduler identifier
8309 equal to N. For example, if the schedulers are bound, ele‐
8310 ment(erlang:system_info(scheduler_id), erlang:sys‐
8311 tem_info(scheduler_bindings)) returns the identifier of the
8312 logical processor that the calling process is executing on.
8313 Notice that only schedulers online can be bound to logical
8315 processors.
8316 For more information, see command-line argument +sbt in
8318 erl(1) and erlang:system_info(schedulers_online).
8319 scheduler_id:
8321 Returns the scheduler ID (SchedulerId) of the scheduler
8322 thread that the calling process is executing on. SchedulerId
8323 is a positive integer, where 1 <= SchedulerId <= erlang:sys‐
8324 tem_info(schedulers).
8325 See also erlang:system_info(schedulers).
8327 schedulers:
8329 Returns the number of scheduler threads used by the emula‐
8330 tor. Scheduler threads online schedules Erlang processes and
8331 Erlang ports, and execute Erlang code and Erlang linked-in
8332 driver code.
8333 The number of scheduler threads is determined at emulator
8335 boot time and cannot be changed later. However, the number
8336 of schedulers online can be changed at any time.
8337 See also erlang:system_flag(schedulers_online, SchedulersOn‐
8339 line), erlang:system_info(schedulers_online), erlang:sys‐
8340 tem_info(scheduler_id), erlang:system_flag(multi_scheduling,
8341 BlockState), erlang:system_info(multi_scheduling),
8342 erlang:system_info(normal_multi_scheduling_blockers) and
8343 erlang:system_info(multi_scheduling_blockers).
8344 schedulers_online:
8346 Returns the number of schedulers online. The scheduler iden‐
8347 tifiers of schedulers online satisfy the relationship 1 <=
8348 SchedulerId <= erlang:system_info(schedulers_online).
8349 For more information, see erlang:system_info(schedulers) and
8351 erlang:system_flag(schedulers_online, SchedulersOnline).
8352 smp_support:
8354 Returns true.
8355 threads:
8357 Returns true.
8358 thread_pool_size:
8360 Returns the number of async threads in the async thread pool
8363 used for asynchronous driver calls
8364 (erl_driver:driver_async()). The value is given as an inte‐
8365 ger.
8366 erlang:system_info(Item :: creation) -> integer()
8368 erlang:system_info(Item :: delayed_node_table_gc) ->
8370 infinity | integer() >= 0
8371 erlang:system_info(Item :: dist) -> binary()
8373 erlang:system_info(Item :: dist_buf_busy_limit) ->
8375 integer() >= 0
8376 erlang:system_info(Item :: dist_ctrl) ->
8378 {Node :: node(),
8379 ControllingEntity :: port() | pid()}
8380 Returns information about Erlang Distribution in the current
8382 system as specified by Item:
8383 creation:
8385 Returns the creation of the local node as an integer. The
8386 creation is changed when a node is restarted. The creation
8387 of a node is stored in process identifiers, port identi‐
8388 fiers, and references. This makes it (to some extent) possi‐
8389 ble to distinguish between identifiers from different incar‐
8390 nations of a node. The valid creations are integers in the
8391 range 1..3, but this will probably change in a future
8392 release. If the node is not alive, 0 is returned.
8393 delayed_node_table_gc:
8395 Returns the amount of time in seconds garbage collection of
8396 an entry in a node table is delayed. This limit can be set
8397 on startup by passing command-line flag +zdntgc to erl(1).
8398 For more information, see the documentation of the command-
8399 line flag.
8400 dist:
8402 Returns a binary containing a string of distribution infor‐
8403 mation formatted as in Erlang crash dumps. For more informa‐
8404 tion, see section How to interpret the Erlang crash dumps
8405 in the User's Guide.
8406 dist_buf_busy_limit:
8408 Returns the value of the distribution buffer busy limit in
8409 bytes. This limit can be set at startup by passing command-
8410 line flag +zdbbl to erl(1).
8411 dist_ctrl:
8413 Returns a list of tuples {Node, ControllingEntity}, one
8414 entry for each connected remote node. Node is the node name
8415 and ControllingEntity is the port or process identifier
8416 responsible for the communication to that node. More specif‐
8417 ically, ControllingEntity for nodes connected through TCP/IP
8418 (the normal case) is the socket used in communication with
8419 the specific node.
8420 erlang:system_info(Item :: build_type) ->
8422 opt | debug | purify | quantify | purecov |
8423 gcov | valgrind | gprof | lcnt | frmptr
8424 erlang:system_info(Item :: c_compiler_used) -> {atom(), term()}
8426 erlang:system_info(Item :: check_io) -> [term()]
8428 erlang:system_info(Item :: compat_rel) -> integer()
8430 erlang:system_info(Item :: debug_compiled) -> boolean()
8432 erlang:system_info(Item :: driver_version) -> string()
8434 erlang:system_info(Item :: dynamic_trace) ->
8436 none | dtrace | systemtap
8437 erlang:system_info(Item :: dynamic_trace_probes) -> boolean()
8439 erlang:system_info(Item :: info) -> binary()
8441 erlang:system_info(Item :: kernel_poll) -> boolean()
8443 erlang:system_info(Item :: loaded) -> binary()
8445 erlang:system_info(Item :: machine) -> string()
8447 erlang:system_info(Item :: modified_timing_level) ->
8449 integer() | undefined
8450 erlang:system_info(Item :: nif_version) -> string()
8452 erlang:system_info(Item :: otp_release) -> string()
8454 erlang:system_info(Item :: port_parallelism) -> boolean()
8456 erlang:system_info(Item :: system_architecture) -> string()
8458 erlang:system_info(Item :: system_logger) ->
8460 logger | undefined | pid()
8461 erlang:system_info(Item :: system_version) -> string()
8463 erlang:system_info(Item :: trace_control_word) ->
8465 integer() >= 0
8466 erlang:system_info(Item :: version) -> string()
8468 erlang:system_info(Item ::
8470 wordsize |
8471 {wordsize, internal} |
8472 {wordsize, external}) ->
8473 4 | 8
8474 Returns various information about the current system (emulator)
8476 as specified by Item:
8477 build_type:
8479 Returns an atom describing the build type of the runtime
8480 system. This is normally the atom opt for optimized. Other
8481 possible return values are debug, purify, quantify, purecov,
8482 gcov, valgrind, gprof, and lcnt. Possible return values can
8483 be added or removed at any time without prior notice.
8484 c_compiler_used:
8486 Returns a two-tuple describing the C compiler used when com‐
8487 piling the runtime system. The first element is an atom
8488 describing the name of the compiler, or undefined if
8489 unknown. The second element is a term describing the version
8490 of the compiler, or undefined if unknown.
8491 check_io:
8493 Returns a list containing miscellaneous information about
8494 the emulators internal I/O checking. Notice that the content
8495 of the returned list can vary between platforms and over
8496 time. It is only guaranteed that a list is returned.
8497 compat_rel:
8499 Returns the compatibility mode of the local node as an inte‐
8500 ger. The integer returned represents the Erlang/OTP release
8501 that the current emulator has been set to be backward com‐
8502 patible with. The compatibility mode can be configured at
8503 startup by using command-line flag +R in erl(1).
8504 debug_compiled:
8506 Returns true if the emulator has been debug-compiled, other‐
8507 wise false.
8508 driver_version:
8510 Returns a string containing the Erlang driver version used
8511 by the runtime system. It has the form "<major ver>.<minor
8512 ver>".
8513 dynamic_trace:
8515 Returns an atom describing the dynamic trace framework com‐
8516 piled into the virtual machine. It can be dtrace, systemtap,
8517 or none. For a commercial or standard build, it is always
8518 none. The other return values indicate a custom configura‐
8519 tion (for example, ./configure --with-dynamic-trace=dtrace).
8520 For more information about dynamic tracing, see dyntrace(3)
8521 manual page and the README.dtrace/README.systemtap files in
8522 the Erlang source code top directory.
8523 dynamic_trace_probes:
8525 Returns a boolean() indicating if dynamic trace probes
8526 (dtrace or systemtap) are built into the emulator. This can
8527 only be true if the virtual machine was built for dynamic
8528 tracing (that is, system_info(dynamic_trace) returns dtrace
8529 or systemtap).
8530 info:
8532 Returns a binary containing a string of miscellaneous system
8533 information formatted as in Erlang crash dumps. For more
8534 information, see section How to interpret the Erlang crash
8535 dumps in the User's Guide.
8536 kernel_poll:
8538 Returns true if the emulator uses some kind of kernel-poll
8539 implementation, otherwise false.
8540 loaded:
8542 Returns a binary containing a string of loaded module infor‐
8543 mation formatted as in Erlang crash dumps. For more informa‐
8544 tion, see section How to interpret the Erlang crash dumps in
8545 the User's Guide.
8546 machine:
8548 Returns a string containing the Erlang machine name.
8549 modified_timing_level:
8551 Returns the modified timing-level (an integer) if modified
8552 timing is enabled, otherwise undefined. For more information
8553 about modified timing, see command-line flag +T in erl(1)
8554 nif_version:
8556 Returns a string containing the version of the Erlang NIF
8557 interface used by the runtime system. It is on the form
8558 "<major ver>.<minor ver>".
8559 otp_release:
8561 Returns a string containing the OTP release number of the
8564 OTP release that the currently executing ERTS application is
8565 part of.
8566 As from Erlang/OTP 17, the OTP release number corresponds to
8568 the major OTP version number. No erlang:system_info() argu‐
8569 ment gives the exact OTP version. This is because the exact
8570 OTP version in the general case is difficult to determine.
8571 For more information, see the description of versions in
8572 System principles in System Documentation.
8573 port_parallelism:
8575 Returns the default port parallelism scheduling hint used.
8576 For more information, see command-line argument +spp in
8577 erl(1).
8578 system_architecture:
8580 Returns a string containing the processor and OS architec‐
8581 ture the emulator is built for.
8582 system_logger:
8584 Returns the current system_logger as set by erlang:sys‐
8585 tem_flag(system_logger, _).
8586 system_version:
8588 Returns a string containing version number and some impor‐
8589 tant properties, such as the number of schedulers.
8590 trace_control_word:
8592 Returns the value of the node trace control word. For more
8593 information, see function get_tcw in section Match Specifi‐
8594 cations in Erlang in the User's Guide.
8595 version:
8597 Returns a string containing the version number of the emula‐
8598 tor.
8599 wordsize:
8601 Same as {wordsize, internal}.
8602 {wordsize, internal}:
8604 Returns the size of Erlang term words in bytes as an inte‐
8605 ger, that is, 4 is returned on a 32-bit architecture, and 8
8606 is returned on a pure 64-bit architecture. On a halfword
8607 64-bit emulator, 4 is returned, as the Erlang terms are
8608 stored using a virtual word size of half the system word
8609 size.
8610 {wordsize, external}:
8612 Returns the true word size of the emulator, that is, the
8613 size of a pointer. The value is given in bytes as an inte‐
8614 ger. On a pure 32-bit architecture, 4 is returned. On both a
8615 half word and on a pure 64-bit architecture, 8 is returned.
8616 erlang:system_monitor() -> MonSettings
8618 Types:
8620 MonSettings = undefined | {MonitorPid, Options}
8622 MonitorPid = pid()
8623 Options = [system_monitor_option()]
8624 system_monitor_option() =
8625 busy_port | busy_dist_port |
8626 {long_gc, integer() >= 0} |
8627 {long_schedule, integer() >= 0} |
8628 {large_heap, integer() >= 0}
8629 Returns the current system monitoring settings set by
8631 erlang:system_monitor/2 as {MonitorPid, Options}, or undefined
8632 if no settings exist. The order of the options can be different
8633 from the one that was set.
8634 erlang:system_monitor(Arg) -> MonSettings
8636 Types:
8638 Arg = MonSettings = undefined | {MonitorPid, Options}
8640 MonitorPid = pid()
8641 Options = [system_monitor_option()]
8642 system_monitor_option() =
8643 busy_port | busy_dist_port |
8644 {long_gc, integer() >= 0} |
8645 {long_schedule, integer() >= 0} |
8646 {large_heap, integer() >= 0}
8647 When called with argument undefined, all system performance mon‐
8649 itoring settings are cleared.
8650 Calling the function with {MonitorPid, Options} as argument is
8652 the same as calling erlang:system_monitor(MonitorPid, Options).
8653 Returns the previous system monitor settings just like
8655 erlang:system_monitor/0.
8656 erlang:system_monitor(MonitorPid, Options) -> MonSettings
8658 Types:
8660 MonitorPid = pid()
8662 Options = [system_monitor_option()]
8663 MonSettings = undefined | {OldMonitorPid, OldOptions}
8664 OldMonitorPid = pid()
8665 OldOptions = [system_monitor_option()]
8666 system_monitor_option() =
8667 busy_port | busy_dist_port |
8668 {long_gc, integer() >= 0} |
8669 {long_schedule, integer() >= 0} |
8670 {large_heap, integer() >= 0}
8671 Sets the system performance monitoring options. MonitorPid is a
8673 local process identifier (pid) receiving system monitor mes‐
8674 sages. The second argument is a list of monitoring options:
8675 {long_gc, Time}:
8677 If a garbage collection in the system takes at least Time
8678 wall clock milliseconds, a message {monitor, GcPid, long_gc,
8679 Info} is sent to MonitorPid. GcPid is the pid that was
8680 garbage collected. Info is a list of two-element tuples
8681 describing the result of the garbage collection.
8682 One of the tuples is {timeout, GcTime}, where GcTime is the
8684 time for the garbage collection in milliseconds. The other
8685 tuples are tagged with heap_size, heap_block_size,
8686 stack_size, mbuf_size, old_heap_size, and
8687 old_heap_block_size. These tuples are explained in the
8688 description of trace message gc_minor_start (see
8689 erlang:trace/3). New tuples can be added, and the order of
8690 the tuples in the Info list can be changed at any time with‐
8691 out prior notice.
8692 {long_schedule, Time}:
8694 If a process or port in the system runs uninterrupted for at
8695 least Time wall clock milliseconds, a message {monitor,
8696 PidOrPort, long_schedule, Info} is sent to MonitorPid.
8697 PidOrPort is the process or port that was running. Info is a
8698 list of two-element tuples describing the event.
8699 If a pid(), the tuples {timeout, Millis}, {in, Location},
8701 and {out, Location} are present, where Location is either an
8702 MFA ({Module, Function, Arity}) describing the function
8703 where the process was scheduled in/out, or the atom unde‐
8704 fined.
8705 If a port(), the tuples {timeout, Millis} and {port_op,Op}
8707 are present. Op is one of proc_sig, timeout, input, output,
8708 event, or dist_cmd, depending on which driver callback was
8709 executing.
8710 proc_sig is an internal operation and is never to appear,
8712 while the others represent the corresponding driver call‐
8713 backs timeout, ready_input, ready_output, event, and outputv
8714 (when the port is used by distribution). Value Millis in
8715 tuple timeout informs about the uninterrupted execution time
8716 of the process or port, which always is equal to or higher
8717 than the Time value supplied when starting the trace. New
8718 tuples can be added to the Info list in a future release.
8719 The order of the tuples in the list can be changed at any
8720 time without prior notice.
8721 This can be used to detect problems with NIFs or drivers
8723 that take too long to execute. 1 ms is considered a good
8724 maximum time for a driver callback or a NIF. However, a
8725 time-sharing system is usually to consider everything < 100
8726 ms as "possible" and fairly "normal". However, longer sched‐
8727 ule times can indicate swapping or a misbehaving NIF/driver.
8728 Misbehaving NIFs and drivers can cause bad resource utiliza‐
8729 tion and bad overall system performance.
8730 {large_heap, Size}:
8732 If a garbage collection in the system results in the allo‐
8733 cated size of a heap being at least Size words, a message
8734 {monitor, GcPid, large_heap, Info} is sent to MonitorPid.
8735 GcPid and Info are the same as for long_gc earlier, except
8736 that the tuple tagged with timeout is not present.
8737 The monitor message is sent if the sum of the sizes of all
8739 memory blocks allocated for all heap generations after a
8740 garbage collection is equal to or higher than Size.
8741 When a process is killed by max_heap_size, it is killed
8743 before the garbage collection is complete and thus no large
8744 heap message is sent.
8745 busy_port:
8747 If a process in the system gets suspended because it sends
8748 to a busy port, a message {monitor, SusPid, busy_port, Port}
8749 is sent to MonitorPid. SusPid is the pid that got suspended
8750 when sending to Port.
8751 busy_dist_port:
8753 If a process in the system gets suspended because it sends
8754 to a process on a remote node whose inter-node communication
8755 was handled by a busy port, a message {monitor, SusPid,
8756 busy_dist_port, Port} is sent to MonitorPid. SusPid is the
8757 pid that got suspended when sending through the inter-node
8758 communication port Port.
8759 Returns the previous system monitor settings just like
8761 erlang:system_monitor/0.
8762 The arguments to system_monitor/2 specifies how all system moni‐
8764 toring on the node should be done, not how it should be changed.
8765 This means only one process at a time (MonitorPid) can be the
8766 receiver of system monitor messages. Also, the way to clear a
8767 specific monitor option is to not include it in the list
8768 Options. All system monitoring will, however, be cleared if the
8769 process identified by MonitorPid terminates.
8770 There are no special option values (like zero) to clear an
8772 option. Some of the options have a unspecified minimum value.
8773 Lower values will be adjusted to the minimum value. For example,
8774 it is currently not possible to monitor all garbage collections
8775 with {long_gc, 0}.
8776 Note:
8778 If a monitoring process gets so large that it itself starts to
8779 cause system monitor messages when garbage collecting, the mes‐
8780 sages enlarge the process message queue and probably make the
8781 problem worse.
8782 Keep the monitoring process neat and do not set the system moni‐
8784 tor limits too tight.
8785 Failures:
8788 badarg:
8790 If MonitorPid does not exist.
8791 badarg:
8793 If MonitorPid is not a local process.
8794 erlang:system_profile() -> ProfilerSettings
8796 Types:
8798 ProfilerSettings = undefined | {ProfilerPid, Options}
8800 ProfilerPid = pid() | port()
8801 Options = [system_profile_option()]
8802 system_profile_option() =
8803 exclusive | runnable_ports | runnable_procs | scheduler |
8804 timestamp | monotonic_timestamp | strict_monotonic_timestamp
8805 Returns the current system profiling settings set by erlang:sys‐
8807 tem_profile/2 as {ProfilerPid, Options}, or undefined if there
8808 are no settings. The order of the options can be different from
8809 the one that was set.
8810 erlang:system_profile(ProfilerPid, Options) -> ProfilerSettings
8812 Types:
8814 ProfilerPid = pid() | port() | undefined
8816 Options = [system_profile_option()]
8817 ProfilerSettings =
8818 undefined | {pid() | port(), [system_profile_option()]}
8819 system_profile_option() =
8820 exclusive | runnable_ports | runnable_procs | scheduler |
8821 timestamp | monotonic_timestamp | strict_monotonic_timestamp
8822 Sets system profiler options. ProfilerPid is a local process
8824 identifier (pid) or port receiving profiling messages. The
8825 receiver is excluded from all profiling. The second argument is
8826 a list of profiling options:
8827 exclusive:
8829 If a synchronous call to a port from a process is done, the
8830 calling process is considered not runnable during the call
8831 runtime to the port. The calling process is notified as
8832 inactive, and later active when the port callback returns.
8833 monotonic_timestamp:
8835 Time stamps in profile messages use Erlang monotonic time.
8836 The time stamp (Ts) has the same format and value as pro‐
8837 duced by erlang:monotonic_time(nanosecond).
8838 runnable_procs:
8840 If a process is put into or removed from the run queue, a
8841 message, {profile, Pid, State, Mfa, Ts}, is sent to Profil‐
8842 erPid. Running processes that are reinserted into the run
8843 queue after having been pre-empted do not trigger this mes‐
8844 sage.
8845 runnable_ports:
8847 If a port is put into or removed from the run queue, a mes‐
8848 sage, {profile, Port, State, 0, Ts}, is sent to ProfilerPid.
8849 scheduler:
8851 If a scheduler is put to sleep or awoken, a message, {pro‐
8852 file, scheduler, Id, State, NoScheds, Ts}, is sent to Pro‐
8853 filerPid.
8854 strict_monotonic_timestamp:
8856 Time stamps in profile messages consist of Erlang monotonic
8857 time and a monotonically increasing integer. The time stamp
8858 (Ts) has the same format and value as produced by
8859 {erlang:monotonic_time(nanosecond), erlang:unique_inte‐
8860 ger([monotonic])}.
8861 timestamp:
8863 Time stamps in profile messages include a time stamp (Ts)
8864 that has the same form as returned by erlang:now(). This is
8865 also the default if no time stamp flag is specified. If
8866 cpu_timestamp has been enabled through erlang:trace/3, this
8867 also effects the time stamp produced in profiling messages
8868 when flag timestamp is enabled.
8869 Note:
8871 erlang:system_profile behavior can change in a future release.
8872 erlang:system_time() -> integer()
8875 Returns current Erlang system time in native time unit.
8877 Calling erlang:system_time() is equivalent to erlang:mono‐
8879 tonic_time() + erlang:time_offset().
8880 Note:
8882 This time is not a monotonically increasing time in the general
8883 case. For more information, see the documentation of time warp
8884 modes in the User's Guide.
8885 erlang:system_time(Unit) -> integer()
8888 Types:
8890 Unit = time_unit()
8892 Returns current Erlang system time converted into the Unit
8894 passed as argument.
8895 Calling erlang:system_time(Unit) is equivalent to erlang:con‐
8897 vert_time_unit(erlang:system_time(), native, Unit).
8898 Note:
8900 This time is not a monotonically increasing time in the general
8901 case. For more information, see the documentation of time warp
8902 modes in the User's Guide.
8903 term_to_binary(Term) -> ext_binary()
8906 Types:
8908 Term = term()
8910 Returns a binary data object that is the result of encoding Term
8912 according to the Erlang external term format.
8913 This can be used for various purposes, for example, writing a
8915 term to a file in an efficient way, or sending an Erlang term to
8916 some type of communications channel not supported by distributed
8917 Erlang.
8918 > Bin = term_to_binary(hello).
8920 <<131,100,0,5,104,101,108,108,111>>
8921 > hello = binary_to_term(Bin).
8922 hello
8923 See also binary_to_term/1.
8926 Note:
8928 There is no guarantee that this function will return the same
8929 encoded representation for the same term.
8930 term_to_binary(Term, Options) -> ext_binary()
8933 Types:
8935 Term = term()
8937 Options =
8938 [compressed |
8939 {compressed, Level :: 0..9} |
8940 {minor_version, Version :: 0..2}]
8941 Returns a binary data object that is the result of encoding Term
8943 according to the Erlang external term format.
8944 If option compressed is provided, the external term format is
8946 compressed. The compressed format is automatically recognized by
8947 binary_to_term/1 as from Erlang/OTP R7B.
8948 A compression level can be specified by giving option {com‐
8950 pressed, Level}. Level is an integer with range 0..9, where:
8951 * 0 - No compression is done (it is the same as giving no com‐
8953 pressed option).
8954 * 1 - Takes least time but may not compress as well as the
8956 higher levels.
8957 * 6 - Default level when option compressed is provided.
8959 * 9 - Takes most time and tries to produce a smaller result.
8961 Notice "tries" in the preceding sentence; depending on the
8962 input term, level 9 compression either does or does not pro‐
8963 duce a smaller result than level 1 compression.
8964 Option {minor_version, Version} can be used to control some
8966 encoding details. This option was introduced in Erlang/OTP
8967 R11B-4. The valid values for Version are:
8968 0:
8970 Floats are encoded using a textual representation. This
8971 option is useful to ensure that releases before Erlang/OTP
8972 R11B-4 can decode resulting binary.
8973 This version encode atoms that can be represented by a
8975 latin1 string using latin1 encoding while only atoms that
8976 cannot be represented by latin1 are encoded using utf8.
8977 1:
8979 This is as of Erlang/OTP 17.0 the default. It forces any
8980 floats in the term to be encoded in a more space-efficient
8981 and exact way (namely in the 64-bit IEEE format, rather than
8982 converted to a textual representation). As from Erlang/OTP
8983 R11B-4, binary_to_term/1 can decode this representation.
8984 This version encode atoms that can be represented by a
8986 latin1 string using latin1 encoding while only atoms that
8987 cannot be represented by latin1 are encoded using utf8.
8988 2:
8990 Drops usage of the latin1 atom encoding and unconditionally
8991 use utf8 encoding for all atoms. This will be changed to the
8992 default in a future major release of Erlang/OTP. Erlang/OTP
8993 systems as of R16B can decode this representation.
8994 See also binary_to_term/1.
8996 throw(Any) -> no_return()
8998 Types:
9000 Any = term()
9002 A non-local return from a function. If evaluated within a catch,
9004 catch returns value Any. Example:
9005 > catch throw({hello, there}).
9007 {hello,there}
9008 Failure: nocatch if not evaluated within a catch.
9010 time() -> Time
9012 Types:
9014 Time = calendar:time()
9016 Returns the current time as {Hour, Minute, Second}.
9018 The time zone and Daylight Saving Time correction depend on the
9020 underlying OS. Example:
9021 > time().
9023 {9,42,44}
9024 erlang:time_offset() -> integer()
9026 Returns the current time offset between Erlang monotonic time
9028 and Erlang system time in native time unit. Current time offset
9029 added to an Erlang monotonic time gives corresponding Erlang
9030 system time.
9031 The time offset may or may not change during operation depending
9033 on the time warp mode used.
9034 Note:
9036 A change in time offset can be observed at slightly different
9037 points in time by different processes.
9038 If the runtime system is in multi-time warp mode, the time off‐
9040 set is changed when the runtime system detects that the OS sys‐
9041 tem time has changed. The runtime system will, however, not
9042 detect this immediately when it occurs. A task checking the time
9043 offset is scheduled to execute at least once a minute; so, under
9044 normal operation this is to be detected within a minute, but
9045 during heavy load it can take longer time.
9046 erlang:time_offset(Unit) -> integer()
9049 Types:
9051 Unit = time_unit()
9053 Returns the current time offset between Erlang monotonic time
9055 and Erlang system time converted into the Unit passed as argu‐
9056 ment.
9057 Same as calling erlang:convert_time_unit(erlang:time_offset(),
9059 native, Unit) however optimized for commonly used Units.
9060 erlang:timestamp() -> Timestamp
9062 Types:
9064 Timestamp = timestamp()
9066 timestamp() =
9067 {MegaSecs :: integer() >= 0,
9068 Secs :: integer() >= 0,
9069 MicroSecs :: integer() >= 0}
9070 Returns current Erlang system time on the format {MegaSecs,
9072 Secs, MicroSecs}. This format is the same as os:timestamp/0 and
9073 the deprecated erlang:now/0 use. The reason for the existence of
9074 erlang:timestamp() is purely to simplify use for existing code
9075 that assumes this time stamp format. Current Erlang system time
9076 can more efficiently be retrieved in the time unit of your
9077 choice using erlang:system_time/1.
9078 The erlang:timestamp() BIF is equivalent to:
9080 timestamp() ->
9082 ErlangSystemTime = erlang:system_time(microsecond),
9083 MegaSecs = ErlangSystemTime div 1000000000000,
9084 Secs = ErlangSystemTime div 1000000 - MegaSecs*1000000,
9085 MicroSecs = ErlangSystemTime rem 1000000,
9086 {MegaSecs, Secs, MicroSecs}.
9087 It, however, uses a native implementation that does not build
9089 garbage on the heap and with slightly better performance.
9090 Note:
9092 This time is not a monotonically increasing time in the general
9093 case. For more information, see the documentation of time warp
9094 modes in the User's Guide.
9095 tl(List) -> term()
9098 Types:
9100 List = [term(), ...]
9102 Returns the tail of List, that is, the list minus the first ele‐
9104 ment, for example:
9105 > tl([geesties, guilies, beasties]).
9107 [guilies, beasties]
9108 Allowed in guard tests.
9110 Failure: badarg if List is the empty list [].
9112 erlang:trace(PidPortSpec, How, FlagList) -> integer()
9114 Types:
9116 PidPortSpec =
9118 pid() |
9119 port() |
9120 all | processes | ports | existing | existing_processes |
9121 existing_ports | new | new_processes | new_ports
9122 How = boolean()
9123 FlagList = [trace_flag()]
9124 trace_flag() =
9125 all | send | 'receive' | procs | ports | call | arity |
9126 return_to | silent | running | exiting | running_procs |
9127 running_ports | garbage_collection | timestamp |
9128 cpu_timestamp | monotonic_timestamp |
9129 strict_monotonic_timestamp | set_on_spawn |
9130 set_on_first_spawn | set_on_link | set_on_first_link |
9131 {tracer, pid() | port()} |
9132 {tracer, module(), term()}
9133 Turns on (if How == true) or off (if How == false) the trace
9135 flags in FlagList for the process or processes represented by
9136 PidPortSpec.
9137 PidPortSpec is either a process identifier (pid) for a local
9139 process, a port identifier, or one of the following atoms:
9140 all:
9142 All currently existing processes and ports and all that will
9143 be created in the future.
9144 processes:
9146 All currently existing processes and all that will be cre‐
9147 ated in the future.
9148 ports:
9150 All currently existing ports and all that will be created in
9151 the future.
9152 existing:
9154 All currently existing processes and ports.
9155 existing_processes:
9157 All currently existing processes.
9158 existing_ports:
9160 All currently existing ports.
9161 new:
9163 All processes and ports that will be created in the future.
9164 new_processes:
9166 All processes that will be created in the future.
9167 new_ports:
9169 All ports that will be created in the future.
9170 FlagList can contain any number of the following flags (the
9172 "message tags" refers to the list of trace messages):
9173 all:
9175 Sets all trace flags except tracer and cpu_timestamp, which
9176 are in their nature different than the others.
9177 send:
9179 Traces sending of messages.
9180 Message tags: send and send_to_non_existing_process.
9182 'receive':
9184 Traces receiving of messages.
9185 Message tags: 'receive'.
9187 call:
9189 Traces certain function calls. Specify which function calls
9190 to trace by calling erlang:trace_pattern/3.
9191 Message tags: call and return_from.
9193 silent:
9195 Used with the call trace flag. The call, return_from, and
9196 return_to trace messages are inhibited if this flag is set,
9197 but they are executed as normal if there are match specifi‐
9198 cations.
9199 Silent mode is inhibited by executing erlang:trace(_, false,
9201 [silent|_]), or by a match specification executing the func‐
9202 tion {silent, false}.
9203 The silent trace flag facilitates setting up a trace on many
9205 or even all processes in the system. The trace can then be
9206 activated and deactivated using the match specification
9207 function {silent,Bool}, giving a high degree of control of
9208 which functions with which arguments that trigger the trace.
9209 Message tags: call, return_from, and return_to. Or rather,
9211 the absence of.
9212 return_to:
9214 Used with the call trace flag. Traces the return from a
9215 traced function back to its caller. Only works for functions
9216 traced with option local to erlang:trace_pattern/3.
9217 The semantics is that a trace message is sent when a call
9219 traced function returns, that is, when a chain of tail
9220 recursive calls ends. Only one trace message is sent per
9221 chain of tail recursive calls, so the properties of tail
9222 recursiveness for function calls are kept while tracing with
9223 this flag. Using call and return_to trace together makes it
9224 possible to know exactly in which function a process exe‐
9225 cutes at any time.
9226 To get trace messages containing return values from func‐
9228 tions, use the {return_trace} match specification action
9229 instead.
9230 Message tags: return_to.
9232 procs:
9234 Traces process-related events.
9235 Message tags: spawn, spawned, exit, register, unregister,
9237 link, unlink, getting_linked, and getting_unlinked.
9238 ports:
9240 Traces port-related events.
9241 Message tags: open, closed, register, unregister, get‐
9243 ting_linked, and getting_unlinked.
9244 running:
9246 Traces scheduling of processes.
9247 Message tags: in and out.
9249 exiting:
9251 Traces scheduling of exiting processes.
9252 Message tags: in_exiting, out_exiting, and out_exited.
9254 running_procs:
9256 Traces scheduling of processes just like running. However,
9257 this option also includes schedule events when the process
9258 executes within the context of a port without being sched‐
9259 uled out itself.
9260 Message tags: in and out.
9262 running_ports:
9264 Traces scheduling of ports.
9265 Message tags: in and out.
9267 garbage_collection:
9269 Traces garbage collections of processes.
9270 Message tags: gc_minor_start, gc_max_heap_size, and
9272 gc_minor_end.
9273 timestamp:
9275 Includes a time stamp in all trace messages. The time stamp
9276 (Ts) has the same form as returned by erlang:now().
9277 cpu_timestamp:
9279 A global trace flag for the Erlang node that makes all trace
9280 time stamps using flag timestamp to be in CPU time, not wall
9281 clock time. That is, cpu_timestamp is not be used if mono‐
9282 tonic_timestamp or strict_monotonic_timestamp is enabled.
9283 Only allowed with PidPortSpec==all. If the host machine OS
9284 does not support high-resolution CPU time measurements,
9285 trace/3 exits with badarg. Notice that most OS do not syn‐
9286 chronize this value across cores, so be prepared that time
9287 can seem to go backwards when using this option.
9288 monotonic_timestamp:
9290 Includes an Erlang monotonic time time stamp in all trace
9291 messages. The time stamp (Ts) has the same format and value
9292 as produced by erlang:monotonic_time(nanosecond). This flag
9293 overrides flag cpu_timestamp.
9294 strict_monotonic_timestamp:
9296 Includes an time stamp consisting of Erlang monotonic time
9297 and a monotonically increasing integer in all trace mes‐
9298 sages. The time stamp (Ts) has the same format and value as
9299 produced by { erlang:monotonic_time(nanosecond),
9300 erlang:unique_integer([monotonic])}. This flag overrides
9301 flag cpu_timestamp.
9302 arity:
9304 Used with the call trace flag. {M, F, Arity} is specified
9305 instead of {M, F, Args} in call trace messages.
9306 set_on_spawn:
9308 Makes any process created by a traced process inherit its
9309 trace flags, including flag set_on_spawn.
9310 set_on_first_spawn:
9312 Makes the first process created by a traced process inherit
9313 its trace flags, excluding flag set_on_first_spawn.
9314 set_on_link:
9316 Makes any process linked by a traced process inherit its
9317 trace flags, including flag set_on_link.
9318 set_on_first_link:
9320 Makes the first process linked to by a traced process
9321 inherit its trace flags, excluding flag set_on_first_link.
9322 {tracer, Tracer}:
9324 Specifies where to send the trace messages. Tracer must be
9325 the process identifier of a local process or the port iden‐
9326 tifier of a local port.
9327 {tracer, TracerModule, TracerState}:
9329 Specifies that a tracer module is to be called instead of
9330 sending a trace message. The tracer module can then ignore
9331 or change the trace message. For more details on how to
9332 write a tracer module, see erl_tracer(3).
9333 If no tracer is specified, the calling process receives all the
9335 trace messages.
9336 The effect of combining set_on_first_link with set_on_link is
9338 the same as set_on_first_link alone. Likewise for set_on_spawn
9339 and set_on_first_spawn.
9340 The tracing process receives the trace messages described in the
9342 following list. Pid is the process identifier of the traced
9343 process in which the traced event has occurred. The third tuple
9344 element is the message tag.
9345 If flag timestamp, strict_monotonic_timestamp, or mono‐
9347 tonic_timestamp is specified, the first tuple element is
9348 trace_ts instead, and the time stamp is added as an extra ele‐
9349 ment last in the message tuple. If multiple time stamp flags are
9350 passed, timestamp has precedence over strict_monotonic_time‐
9351 stamp, which in turn has precedence over monotonic_timestamp.
9352 All time stamp flags are remembered, so if two are passed and
9353 the one with highest precedence later is disabled, the other one
9354 becomes active.
9355 If a match specification (applicable only for call, send and
9357 'receive' tracing) contains a {message} action function with a
9358 non-boolean value, that value is added as an extra element to
9359 the message tuple either in the last position or before the
9360 timestamp (if it is present).
9361 Trace messages:
9363 {trace, PidPort, send, Msg, To}:
9365 When PidPort sends message Msg to process To.
9366 {trace, PidPort, send_to_non_existing_process, Msg, To}:
9368 When PidPort sends message Msg to the non-existing process
9369 To.
9370 {trace, PidPort, 'receive', Msg}:
9372 When PidPort receives message Msg. If Msg is set to time-
9373 out, a receive statement can have timed out, or the process
9374 received a message with the payload timeout.
9375 {trace, Pid, call, {M, F, Args}}:
9377 When Pid calls a traced function. The return values of calls
9378 are never supplied, only the call and its arguments.
9379 Trace flag arity can be used to change the contents of this
9381 message, so that Arity is specified instead of Args.
9382 {trace, Pid, return_to, {M, F, Arity}}:
9384 When Pid returns to the specified function. This trace mes‐
9385 sage is sent if both the flags call and return_to are set,
9386 and the function is set to be traced on local function
9387 calls. The message is only sent when returning from a chain
9388 of tail recursive function calls, where at least one call
9389 generated a call trace message (that is, the functions match
9390 specification matched, and {message, false} was not an
9391 action).
9392 {trace, Pid, return_from, {M, F, Arity}, ReturnValue}:
9394 When Pid returns from the specified function. This trace
9395 message is sent if flag call is set, and the function has a
9396 match specification with a return_trace or exception_trace
9397 action.
9398 {trace, Pid, exception_from, {M, F, Arity}, {Class, Value}}:
9400 When Pid exits from the specified function because of an
9401 exception. This trace message is sent if flag call is set,
9402 and the function has a match specification with an excep‐
9403 tion_trace action.
9404 {trace, Pid, spawn, Pid2, {M, F, Args}}:
9406 When Pid spawns a new process Pid2 with the specified func‐
9407 tion call as entry point.
9408 Args is supposed to be the argument list, but can be any
9410 term if the spawn is erroneous.
9411 {trace, Pid, spawned, Pid2, {M, F, Args}}:
9413 When Pid is spawned by process Pid2 with the specified func‐
9414 tion call as entry point.
9415 Args is supposed to be the argument list, but can be any
9417 term if the spawn is erroneous.
9418 {trace, Pid, exit, Reason}:
9420 When Pid exits with reason Reason.
9421 {trace, PidPort, register, RegName}:
9423 When PidPort gets the name RegName registered.
9424 {trace, PidPort, unregister, RegName}:
9426 When PidPort gets the name RegName unregistered. This is
9427 done automatically when a registered process or port exits.
9428 {trace, Pid, link, Pid2}:
9430 When Pid links to a process Pid2.
9431 {trace, Pid, unlink, Pid2}:
9433 When Pid removes the link from a process Pid2.
9434 {trace, PidPort, getting_linked, Pid2}:
9436 When PidPort gets linked to a process Pid2.
9437 {trace, PidPort, getting_unlinked, Pid2}:
9439 When PidPort gets unlinked from a process Pid2.
9440 {trace, Pid, exit, Reason}:
9442 When Pid exits with reason Reason.
9443 {trace, Port, open, Pid, Driver}:
9445 When Pid opens a new port Port with the running Driver.
9446 Driver is the name of the driver as an atom.
9448 {trace, Port, closed, Reason}:
9450 When Port closes with Reason.
9451 {trace, Pid, in | in_exiting, {M, F, Arity} | 0}:
9453 When Pid is scheduled to run. The process runs in function
9454 {M, F, Arity}. On some rare occasions, the current function
9455 cannot be determined, then the last element is 0.
9456 {trace, Pid, out | out_exiting | out_exited, {M, F, Arity} |
9458 0}:
9459 When Pid is scheduled out. The process was running in func‐
9460 tion {M, F, Arity}. On some rare occasions, the current
9461 function cannot be determined, then the last element is 0.
9462 {trace, Port, in, Command | 0}:
9464 When Port is scheduled to run. Command is the first thing
9465 the port will execute, it can however run several commands
9466 before being scheduled out. On some rare occasions, the cur‐
9467 rent function cannot be determined, then the last element is
9468 0.
9469 The possible commands are call, close, command, connect,
9471 control, flush, info, link, open, and unlink.
9472 {trace, Port, out, Command | 0}:
9474 When Port is scheduled out. The last command run was Com‐
9475 mand. On some rare occasions, the current function cannot be
9476 determined, then the last element is 0. Command can contain
9477 the same commands as in
9478 {trace, Pid, gc_minor_start, Info}:
9480 Sent when a young garbage collection is about to be started.
9483 Info is a list of two-element tuples, where the first ele‐
9484 ment is a key, and the second is the value. Do not depend on
9485 any order of the tuples. The following keys are defined:
9486 heap_size:
9488 The size of the used part of the heap.
9489 heap_block_size:
9491 The size of the memory block used for storing the heap and
9492 the stack.
9493 old_heap_size:
9495 The size of the used part of the old heap.
9496 old_heap_block_size:
9498 The size of the memory block used for storing the old
9499 heap.
9500 stack_size:
9502 The size of the stack.
9503 recent_size:
9505 The size of the data that survived the previous garbage
9506 collection.
9507 mbuf_size:
9509 The combined size of message buffers associated with the
9510 process.
9511 bin_vheap_size:
9513 The total size of unique off-heap binaries referenced from
9514 the process heap.
9515 bin_vheap_block_size:
9517 The total size of binaries allowed in the virtual heap in
9518 the process before doing a garbage collection.
9519 bin_old_vheap_size:
9521 The total size of unique off-heap binaries referenced from
9522 the process old heap.
9523 bin_old_vheap_block_size:
9525 The total size of binaries allowed in the virtual old heap
9526 in the process before doing a garbage collection.
9527 All sizes are in words.
9529 {trace, Pid, gc_max_heap_size, Info}:
9531 Sent when the max_heap_size is reached during garbage col‐
9532 lection. Info contains the same kind of list as in message
9533 gc_start, but the sizes reflect the sizes that triggered
9534 max_heap_size to be reached.
9535 {trace, Pid, gc_minor_end, Info}:
9537 Sent when young garbage collection is finished. Info con‐
9538 tains the same kind of list as in message gc_minor_start,
9539 but the sizes reflect the new sizes after garbage collec‐
9540 tion.
9541 {trace, Pid, gc_major_start, Info}:
9543 Sent when fullsweep garbage collection is about to be
9544 started. Info contains the same kind of list as in message
9545 gc_minor_start.
9546 {trace, Pid, gc_major_end, Info}:
9548 Sent when fullsweep garbage collection is finished. Info
9549 contains the same kind of list as in message gc_minor_start,
9550 but the sizes reflect the new sizes after a fullsweep
9551 garbage collection.
9552 If the tracing process/port dies or the tracer module returns
9554 remove, the flags are silently removed.
9555 Each process can only be traced by one tracer. Therefore,
9557 attempts to trace an already traced process fail.
9558 Returns a number indicating the number of processes that matched
9560 PidPortSpec. If PidPortSpec is a process identifier, the return
9561 value is 1. If PidPortSpec is all or existing, the return value
9562 is the number of processes running. If PidPortSpec is new, the
9563 return value is 0.
9564 Failure: badarg if the specified arguments are not supported.
9566 For example, cpu_timestamp is not supported on all platforms.
9567 erlang:trace_delivered(Tracee) -> Ref
9569 Types:
9571 Tracee = pid() | all
9573 Ref = reference()
9574 The delivery of trace messages (generated by erlang:trace/3,
9576 seq_trace(3), or erlang:system_profile/2) is dislocated on the
9577 time-line compared to other events in the system. If you know
9578 that Tracee has passed some specific point in its execution, and
9579 you want to know when at least all trace messages corresponding
9580 to events up to this point have reached the tracer, use
9581 erlang:trace_delivered(Tracee).
9582 When it is guaranteed that all trace messages are delivered to
9584 the tracer up to the point that Tracee reached at the time of
9585 the call to erlang:trace_delivered(Tracee), then a {trace_deliv‐
9586 ered, Tracee, Ref} message is sent to the caller of
9587 erlang:trace_delivered(Tracee) .
9588 Notice that message trace_delivered does not imply that trace
9590 messages have been delivered. Instead it implies that all trace
9591 messages that are to be delivered have been delivered. It is not
9592 an error if Tracee is not, and has not been traced by someone,
9593 but if this is the case, no trace messages have been delivered
9594 when the trace_delivered message arrives.
9595 Notice that Tracee must refer to a process currently or previ‐
9597 ously existing on the same node as the caller of
9598 erlang:trace_delivered(Tracee) resides on. The special Tracee
9599 atom all denotes all processes that currently are traced in the
9600 node.
9601 When used together with a Tracer Module, any message sent in
9603 the trace callback is guaranteed to have reached its recipient
9604 before the trace_delivered message is sent.
9605 Example: Process A is Tracee, port B is tracer, and process C is
9607 the port owner of B. C wants to close B when A exits. To ensure
9608 that the trace is not truncated, C can call erlang:trace_deliv‐
9609 ered(A) when A exits, and wait for message {trace_delivered, A,
9610 Ref} before closing B.
9611 Failure: badarg if Tracee does not refer to a process (dead or
9613 alive) on the same node as the caller of erlang:trace_deliv‐
9614 ered(Tracee) resides on.
9615 erlang:trace_info(PidPortFuncEvent, Item) -> Res
9617 Types:
9619 PidPortFuncEvent =
9621 pid() |
9622 port() |
9623 new | new_processes | new_ports |
9624 {Module, Function, Arity} |
9625 on_load | send | 'receive'
9626 Module = module()
9627 Function = atom()
9628 Arity = arity()
9629 Item =
9630 flags | tracer | traced | match_spec | meta |
9631 meta_match_spec | call_count | call_time | all
9632 Res = trace_info_return()
9633 trace_info_return() =
9634 undefined |
9635 {flags, [trace_info_flag()]} |
9636 {tracer, pid() | port() | []} |
9637 {tracer, module(), term()} |
9638 trace_info_item_result() |
9639 {all, [trace_info_item_result()] | false | undefined}
9640 trace_info_item_result() =
9641 {traced, global | local | false | undefined} |
9642 {match_spec, trace_match_spec() | false | undefined} |
9643 {meta, pid() | port() | false | undefined | []} |
9644 {meta, module(), term()} |
9645 {meta_match_spec, trace_match_spec() | false | undefined} |
9646 {call_count, integer() >= 0 | boolean() | undefined} |
9647 {call_time,
9648 [{pid(),
9649 integer() >= 0,
9650 integer() >= 0,
9651 integer() >= 0}] |
9652 boolean() |
9653 undefined}
9654 trace_info_flag() =
9655 send | 'receive' | set_on_spawn | call | return_to | procs |
9656 set_on_first_spawn | set_on_link | running |
9657 garbage_collection | timestamp | monotonic_timestamp |
9658 strict_monotonic_timestamp | arity
9659 trace_match_spec() =
9660 [{[term()] | '_' | match_variable(), [term()], [term()]}]
9661 match_variable() = atom()
9662 Approximation of '$1' | '$2' | '$3' | ...
9663 Returns trace information about a port, process, function, or
9665 event.
9666 To get information about a port or process, PidPortFuncEvent is
9668 to be a process identifier (pid), port identifier, or one of the
9669 atoms new, new_processes, or new_ports. The atom new or new_pro‐
9670 cesses means that the default trace state for processes to be
9671 created is returned. The atom new_ports means that the default
9672 trace state for ports to be created is returned.
9673 Valid Items for ports and processes:
9675 flags:
9677 Returns a list of atoms indicating what kind of traces is
9678 enabled for the process. The list is empty if no traces are
9679 enabled, and one or more of the followings atoms if traces
9680 are enabled: send, 'receive', set_on_spawn, call, return_to,
9681 procs, ports, set_on_first_spawn, set_on_link, running, run‐
9682 ning_procs, running_ports, silent, exiting, monotonic_time‐
9683 stamp, strict_monotonic_timestamp, garbage_collection, time‐
9684 stamp, and arity. The order is arbitrary.
9685 tracer:
9687 Returns the identifier for process, port, or a tuple con‐
9688 taining the tracer module and tracer state tracing this
9689 process. If this process is not traced, the return value is
9690 [].
9691 To get information about a function, PidPortFuncEvent is to be
9693 the three-element tuple {Module, Function, Arity} or the atom
9694 on_load. No wildcards are allowed. Returns undefined if the
9695 function does not exist, or false if the function is not traced.
9696 If PidPortFuncEvent is on_load, the information returned refers
9697 to the default value for code that will be loaded.
9698 Valid Items for functions:
9700 traced:
9702 Returns global if this function is traced on global function
9703 calls, local if this function is traced on local function
9704 calls (that is, local and global function calls), and false
9705 if local or global function calls are not traced.
9706 match_spec:
9708 Returns the match specification for this function, if it has
9709 one. If the function is locally or globally traced but has
9710 no match specification defined, the returned value is [].
9711 meta:
9713 Returns the meta-trace tracer process, port, or trace module
9714 for this function, if it has one. If the function is not
9715 meta-traced, the returned value is false. If the function is
9716 meta-traced but has once detected that the tracer process is
9717 invalid, the returned value is [].
9718 meta_match_spec:
9720 Returns the meta-trace match specification for this func‐
9721 tion, if it has one. If the function is meta-traced but has
9722 no match specification defined, the returned value is [].
9723 call_count:
9725 Returns the call count value for this function or true for
9726 the pseudo function on_load if call count tracing is active.
9727 Otherwise false is returned.
9728 See also erlang:trace_pattern/3.
9730 call_time:
9732 Returns the call time values for this function or true for
9733 the pseudo function on_load if call time tracing is active.
9734 Otherwise false is returned. The call time values returned,
9735 [{Pid, Count, S, Us}], is a list of each process that exe‐
9736 cuted the function and its specific counters.
9737 See also erlang:trace_pattern/3.
9739 all:
9741 Returns a list containing the {Item, Value} tuples for all
9742 other items, or returns false if no tracing is active for
9743 this function.
9744 To get information about an event, PidPortFuncEvent is to be one
9746 of the atoms send or 'receive'.
9747 One valid Item for events exists:
9749 match_spec:
9751 Returns the match specification for this event, if it has
9752 one, or true if no match specification has been set.
9753 The return value is {Item, Value}, where Value is the requested
9755 information as described earlier. If a pid for a dead process
9756 was specified, or the name of a non-existing function, Value is
9757 undefined.
9758 erlang:trace_pattern(MFA, MatchSpec) -> integer() >= 0
9760 Types:
9762 MFA = trace_pattern_mfa() | send | 'receive'
9764 MatchSpec =
9765 (MatchSpecList :: trace_match_spec()) |
9766 boolean() |
9767 restart | pause
9768 trace_pattern_mfa() = {atom(), atom(), arity() | '_'} | on_load
9769 trace_match_spec() =
9770 [{[term()] | '_' | match_variable(), [term()], [term()]}]
9771 match_variable() = atom()
9772 Approximation of '$1' | '$2' | '$3' | ...
9773 The same as erlang:trace_pattern(Event, MatchSpec, []), retained
9775 for backward compatibility.
9776 erlang:trace_pattern(MFA :: send, MatchSpec, FlagList :: []) ->
9778 integer() >= 0
9779 Types:
9781 MatchSpec = (MatchSpecList :: trace_match_spec()) | boolean()
9783 trace_match_spec() =
9784 [{[term()] | '_' | match_variable(), [term()], [term()]}]
9785 match_variable() = atom()
9786 Approximation of '$1' | '$2' | '$3' | ...
9787 Sets trace pattern for message sending. Must be combined with
9789 erlang:trace/3 to set the send trace flag for one or more pro‐
9790 cesses. By default all messages sent from send traced processes
9791 are traced. To limit traced send events based on the message
9792 content, the sender and/or the receiver, use erlang:trace_pat‐
9793 tern/3.
9794 Argument MatchSpec can take the following forms:
9796 MatchSpecList:
9798 A list of match specifications. The matching is done on the
9799 list [Receiver, Msg]. Receiver is the process or port iden‐
9800 tity of the receiver and Msg is the message term. The pid of
9801 the sending process can be accessed with the guard function
9802 self/0. An empty list is the same as true. For more informa‐
9803 tion, see section Match Specifications in Erlang in the
9804 User's Guide.
9805 true:
9807 Enables tracing for all sent messages (from send traced pro‐
9808 cesses). Any match specification is removed. This is the
9809 default.
9810 false:
9812 Disables tracing for all sent messages. Any match specifica‐
9813 tion is removed.
9814 Argument FlagList must be [] for send tracing.
9816 The return value is always 1.
9818 Examples:
9820 Only trace messages to a specific process Pid:
9822 > erlang:trace_pattern(send, [{[Pid, '_'],[],[]}], []).
9824 1
9825 Only trace messages matching {reply, _}:
9827 > erlang:trace_pattern(send, [{['_', {reply,'_'}],[],[]}], []).
9829 1
9830 Only trace messages sent to the sender itself:
9832 > erlang:trace_pattern(send, [{['$1', '_'],[{'=:=','$1',{self}}],[]}], []).
9834 1
9835 Only trace messages sent to other nodes:
9837 > erlang:trace_pattern(send, [{['$1', '_'],[{'=/=',{node,'$1'},{node}}],[]}], []).
9839 1
9840 Note:
9842 A match specification for send trace can use all guard and body
9843 functions except caller.
9844 erlang:trace_pattern(MFA :: 'receive', MatchSpec, FlagList :: []) ->
9847 integer() >= 0
9848 Types:
9850 MatchSpec = (MatchSpecList :: trace_match_spec()) | boolean()
9852 trace_match_spec() =
9853 [{[term()] | '_' | match_variable(), [term()], [term()]}]
9854 match_variable() = atom()
9855 Approximation of '$1' | '$2' | '$3' | ...
9856 Sets trace pattern for message receiving. Must be combined with
9858 erlang:trace/3 to set the 'receive' trace flag for one or more
9859 processes. By default all messages received by 'receive' traced
9860 processes are traced. To limit traced receive events based on
9861 the message content, the sender and/or the receiver, use
9862 erlang:trace_pattern/3.
9863 Argument MatchSpec can take the following forms:
9865 MatchSpecList:
9867 A list of match specifications. The matching is done on the
9868 list [Node, Sender, Msg]. Node is the node name of the
9869 sender. Sender is the process or port identity of the
9870 sender, or the atom undefined if the sender is not known
9871 (which can be the case for remote senders). Msg is the mes‐
9872 sage term. The pid of the receiving process can be accessed
9873 with the guard function self/0. An empty list is the same as
9874 true. For more information, see section Match Specifica‐
9875 tions in Erlang in the User's Guide.
9876 true:
9878 Enables tracing for all received messages (to 'receive'
9879 traced processes). Any match specification is removed. This
9880 is the default.
9881 false:
9883 Disables tracing for all received messages. Any match speci‐
9884 fication is removed.
9885 Argument FlagList must be [] for receive tracing.
9887 The return value is always 1.
9889 Examples:
9891 Only trace messages from a specific process Pid:
9893 > erlang:trace_pattern('receive', [{['_',Pid, '_'],[],[]}], []).
9895 1
9896 Only trace messages matching {reply, _}:
9898 > erlang:trace_pattern('receive', [{['_','_', {reply,'_'}],[],[]}], []).
9900 1
9901 Only trace messages from other nodes:
9903 > erlang:trace_pattern('receive', [{['$1', '_', '_'],[{'=/=','$1',{node}}],[]}], []).
9905 1
9906 Note:
9908 A match specification for 'receive' trace can use all guard and
9909 body functions except caller, is_seq_trace, get_seq_token,
9910 set_seq_token, enable_trace, disable_trace, trace, silent, and
9911 process_dump.
9912 erlang:trace_pattern(MFA, MatchSpec, FlagList) ->
9915 integer() >= 0
9916 Types:
9918 MFA = trace_pattern_mfa()
9920 MatchSpec =
9921 (MatchSpecList :: trace_match_spec()) |
9922 boolean() |
9923 restart | pause
9924 FlagList = [trace_pattern_flag()]
9925 trace_pattern_mfa() = {atom(), atom(), arity() | '_'} | on_load
9926 trace_match_spec() =
9927 [{[term()] | '_' | match_variable(), [term()], [term()]}]
9928 trace_pattern_flag() =
9929 global | local | meta |
9930 {meta, Pid :: pid()} |
9931 {meta, TracerModule :: module(), TracerState :: term()} |
9932 call_count | call_time
9933 match_variable() = atom()
9934 Approximation of '$1' | '$2' | '$3' | ...
9935 Enables or disables call tracing for one or more functions. Must
9937 be combined with erlang:trace/3 to set the call trace flag for
9938 one or more processes.
9939 Conceptually, call tracing works as follows. Inside the Erlang
9941 virtual machine, a set of processes and a set of functions are
9942 to be traced. If a traced process calls a traced function, the
9943 trace action is taken. Otherwise, nothing happens.
9944 To add or remove one or more processes to the set of traced pro‐
9946 cesses, use erlang:trace/3.
9947 To add or remove functions to the set of traced functions, use
9949 erlang:trace_pattern/3.
9950 The BIF erlang:trace_pattern/3 can also add match specifications
9952 to a function. A match specification comprises a pattern that
9953 the function arguments must match, a guard expression that must
9954 evaluate to true, and an action to be performed. The default
9955 action is to send a trace message. If the pattern does not match
9956 or the guard fails, the action is not executed.
9957 Argument MFA is to be a tuple, such as {Module, Function,
9959 Arity}, or the atom on_load (described below). It can be the
9960 module, function, and arity for a function (or a BIF in any mod‐
9961 ule). The atom '_' can be used as a wildcard in any of the fol‐
9962 lowing ways:
9963 {Module,Function,'_'}:
9965 All functions of any arity named Function in module Module.
9966 {Module,'_','_'}:
9968 All functions in module Module.
9969 {'_','_','_'}:
9971 All functions in all loaded modules.
9972 Other combinations, such as {Module,'_',Arity}, are not allowed.
9974 Local functions match wildcards only if option local is in
9975 FlagList.
9976 If argument MFA is the atom on_load, the match specification and
9978 flag list are used on all modules that are newly loaded.
9979 Argument MatchSpec can take the following forms:
9981 false:
9983 Disables tracing for the matching functions. Any match spec‐
9984 ification is removed.
9985 true:
9987 Enables tracing for the matching functions. Any match speci‐
9988 fication is removed.
9989 MatchSpecList:
9991 A list of match specifications. An empty list is equivalent
9992 to true. For a description of match specifications, see sec‐
9993 tion Match Specifications in Erlang in the User's Guide.
9994 restart:
9996 For the FlagList options call_count and call_time: restarts
9997 the existing counters. The behavior is undefined for other
9998 FlagList options.
9999 pause:
10001 For the FlagList options call_count and call_time: pauses
10002 the existing counters. The behavior is undefined for other
10003 FlagList options.
10004 Parameter FlagList is a list of options. The following are the
10006 valid options:
10007 global:
10009 Turns on or off call tracing for global function calls (that
10010 is, calls specifying the module explicitly). Only exported
10011 functions match and only global calls generate trace mes‐
10012 sages. This is the default.
10013 local:
10015 Turns on or off call tracing for all types of function
10016 calls. Trace messages are sent whenever any of the specified
10017 functions are called, regardless of how they are called. If
10018 flag return_to is set for the process, a return_to message
10019 is also sent when this function returns to its caller.
10020 meta | {meta, Pid} | {meta, TracerModule, TracerState}:
10022 Turns on or off meta-tracing for all types of function
10023 calls. Trace messages are sent to the tracer whenever any of
10024 the specified functions are called. If no tracer is speci‐
10025 fied, self() is used as a default tracer process.
10026 Meta-tracing traces all processes and does not care about
10028 the process trace flags set by erlang:trace/3, the trace
10029 flags are instead fixed to [call, timestamp].
10030 The match specification function {return_trace} works with
10032 meta-trace and sends its trace message to the same tracer.
10033 call_count:
10035 Starts (MatchSpec == true) or stops (MatchSpec == false)
10036 call count tracing for all types of function calls. For
10037 every function, a counter is incremented when the function
10038 is called, in any process. No process trace flags need to be
10039 activated.
10040 If call count tracing is started while already running, the
10042 count is restarted from zero. To pause running counters, use
10043 MatchSpec == pause. Paused and running counters can be
10044 restarted from zero with MatchSpec == restart.
10045 To read the counter value, use erlang:trace_info/2.
10047 call_time:
10049 Starts (MatchSpec == true) or stops (MatchSpec == false)
10050 call time tracing for all types of function calls. For every
10051 function, a counter is incremented when the function is
10052 called. Time spent in the function is accumulated in two
10053 other counters, seconds and microseconds. The counters are
10054 stored for each call traced process.
10055 If call time tracing is started while already running, the
10057 count and time restart from zero. To pause running counters,
10058 use MatchSpec == pause. Paused and running counters can be
10059 restarted from zero with MatchSpec == restart.
10060 To read the counter value, use erlang:trace_info/2.
10062 The options global and local are mutually exclusive, and global
10064 is the default (if no options are specified). The options
10065 call_count and meta perform a kind of local tracing, and cannot
10066 be combined with global. A function can be globally or locally
10067 traced. If global tracing is specified for a set of functions,
10068 then local, meta, call time, and call count tracing for the
10069 matching set of local functions is disabled, and conversely.
10070 When disabling trace, the option must match the type of trace
10072 set on the function. That is, local tracing must be disabled
10073 with option local and global tracing with option global (or no
10074 option), and so on.
10075 Part of a match specification list cannot be changed directly.
10077 If a function has a match specification, it can be replaced with
10078 a new one. To change an existing match specification, use the
10079 BIF erlang:trace_info/2 to retrieve the existing match specifi‐
10080 cation.
10081 Returns the number of functions matching argument MFA. This is
10083 zero if none matched.
10084 trunc(Number) -> integer()
10086 Types:
10088 Number = number()
10090 Returns an integer by truncating Number, for example:
10092 > trunc(5.5).
10094 5
10095 Allowed in guard tests.
10097 tuple_size(Tuple) -> integer() >= 0
10099 Types:
10101 Tuple = tuple()
10103 Returns an integer that is the number of elements in Tuple, for
10105 example:
10106 > tuple_size({morni, mulle, bwange}).
10108 3
10109 Allowed in guard tests.
10111 tuple_to_list(Tuple) -> [term()]
10113 Types:
10115 Tuple = tuple()
10117 Returns a list corresponding to Tuple. Tuple can contain any
10119 Erlang terms. Example:
10120 > tuple_to_list({share, {'Ericsson_B', 163}}).
10122 [share,{'Ericsson_B',163}]
10123 erlang:unique_integer() -> integer()
10125 Generates and returns an integer unique on current runtime sys‐
10127 tem instance. The same as calling erlang:unique_integer([]).
10128 erlang:unique_integer(ModifierList) -> integer()
10130 Types:
10132 ModifierList = [Modifier]
10134 Modifier = positive | monotonic
10135 Generates and returns an integer unique on current runtime sys‐
10137 tem instance. The integer is unique in the sense that this BIF,
10138 using the same set of modifiers, does not return the same inte‐
10139 ger more than once on the current runtime system instance. Each
10140 integer value can of course be constructed by other means.
10141 By default, when [] is passed as ModifierList, both negative and
10143 positive integers can be returned. This to use the range of
10144 integers that do not need heap memory allocation as much as pos‐
10145 sible. By default the returned integers are also only guaranteed
10146 to be unique, that is, any returned integer can be smaller or
10147 larger than previously returned integers.
10148 Modifiers:
10150 positive:
10152 Returns only positive integers.
10153 Notice that by passing the positive modifier you will get
10155 heap allocated integers (bignums) quicker.
10156 monotonic:
10158 Returns strictly monotonically increasing integers corre‐
10159 sponding to creation time. That is, the integer returned is
10160 always larger than previously returned integers on the cur‐
10161 rent runtime system instance.
10162 These values can be used to determine order between events
10164 on the runtime system instance. That is, if both X =
10165 erlang:unique_integer([monotonic]) and Y =
10166 erlang:unique_integer([monotonic]) are executed by different
10167 processes (or the same process) on the same runtime system
10168 instance and X < Y, we know that X was created before Y.
10169 Warning:
10171 Strictly monotonically increasing values are inherently quite
10172 expensive to generate and scales poorly. This is because the
10173 values need to be synchronized between CPU cores. That is, do
10174 not pass the monotonic modifier unless you really need
10175 strictly monotonically increasing values.
10176 All valid Modifiers can be combined. Repeated (valid) Modifiers
10179 in the ModifierList are ignored.
10180 Note:
10182 The set of integers returned by erlang:unique_integer/1 using
10183 different sets of Modifiers will overlap. For example, by call‐
10184 ing unique_integer([monotonic]), and unique_integer([positive,
10185 monotonic]) repeatedly, you will eventually see some integers
10186 that are returned by both calls.
10187 Failures:
10190 badarg:
10192 if ModifierList is not a proper list.
10193 badarg:
10195 if Modifier is not a valid modifier.
10196 erlang:universaltime() -> DateTime
10198 Types:
10200 DateTime = calendar:datetime()
10202 Returns the current date and time according to Universal Time
10204 Coordinated (UTC) in the form {{Year, Month, Day}, {Hour,
10205 Minute, Second}} if supported by the underlying OS. Otherwise
10206 erlang:universaltime() is equivalent to erlang:localtime().
10207 Example:
10208 > erlang:universaltime().
10210 {{1996,11,6},{14,18,43}}
10211 erlang:universaltime_to_localtime(Universaltime) -> Localtime
10213 Types:
10215 Localtime = Universaltime = calendar:datetime()
10217 Converts Universal Time Coordinated (UTC) date and time to local
10219 date and time in the form {{Year, Month, Day}, {Hour, Minute,
10220 Second}} if supported by the underlying OS. Otherwise no conver‐
10221 sion is done, and Universaltime is returned. Example:
10222 > erlang:universaltime_to_localtime({{1996,11,6},{14,18,43}}).
10224 {{1996,11,7},{15,18,43}}
10225 Failure: badarg if Universaltime denotes an invalid date and
10227 time.
10228 unlink(Id) -> true
10230 Types:
10232 Id = pid() | port()
10234 Removes the link, if there is one, between the calling process
10236 and the process or port referred to by Id.
10237 Returns true and does not fail, even if there is no link to Id,
10239 or if Id does not exist.
10240 Once unlink(Id) has returned, it is guaranteed that the link
10242 between the caller and the entity referred to by Id has no
10243 effect on the caller in the future (unless the link is setup
10244 again). If the caller is trapping exits, an {'EXIT', Id, _} mes‐
10245 sage from the link can have been placed in the caller's message
10246 queue before the call.
10247 Notice that the {'EXIT', Id, _} message can be the result of the
10249 link, but can also be the result of Id calling exit/2. There‐
10250 fore, it can be appropriate to clean up the message queue when
10251 trapping exits after the call to unlink(Id), as follows:
10252 unlink(Id),
10254 receive
10255 {'EXIT', Id, _} ->
10256 true
10257 after 0 ->
10258 true
10259 end
10260 Note:
10262 Before Erlang/OTP R11B (ERTS 5.5) unlink/1 behaved completely
10263 asynchronously, that is, the link was active until the "unlink
10264 signal" reached the linked entity. This had an undesirable
10265 effect, as you could never know when you were guaranteed not to
10266 be effected by the link.
10267 The current behavior can be viewed as two combined operations:
10269 asynchronously send an "unlink signal" to the linked entity and
10270 ignore any future results of the link.
10271 unregister(RegName) -> true
10274 Types:
10276 RegName = atom()
10278 Removes the registered name RegName associated with a process
10280 identifier or a port identifier, for example:
10281 > unregister(db).
10283 true
10284 Users are advised not to unregister system processes.
10286 Failure: badarg if RegName is not a registered name.
10288 whereis(RegName) -> pid() | port() | undefined
10290 Types:
10292 RegName = atom()
10294 Returns the process identifier or port identifier with the reg‐
10296 istered name RegName. Returns undefined if the name is not reg‐
10297 istered. Example:
10298 > whereis(db).
10300 <0.43.0>
10301 erlang:yield() -> true
10303 Voluntarily lets other processes (if any) get a chance to exe‐
10305 cute. Using this function is similar to receive after 1 -> ok
10306 end, except that yield() is faster.
10307 Warning:
10309 There is seldom or never any need to use this BIF as other pro‐
10310 cesses have a chance to run in another scheduler thread anyway.
10311 Using this BIF without a thorough grasp of how the scheduler
10312 works can cause performance degradation.
10313Ericsson AB erts 10.5.6 erlang(3)