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 {busy_limits_port,
3693 {integer() >= 0, integer() >= 0} | disabled} |
3694 {busy_limits_msgq,
3695 {integer() >= 0, integer() >= 0} | disabled}
3696 Returns a port identifier as the result of opening a new Erlang
3698 port. A port can be seen as an external Erlang process.
3699 The name of the executable as well as the arguments specifed in
3701 cd, env, args, and arg0 are subject to Unicode filename transla‐
3702 tion if the system is running in Unicode filename mode. To avoid
3703 translation or to force, for example UTF-8, supply the exe‐
3704 cutable and/or arguments as a binary in the correct encoding.
3705 For details, see the module file(3), the function
3706 file:native_name_encoding/0 in Kernel, and the Using Unicode in
3707 Erlang User's Guide.
3708 Note:
3710 The characters in the name (if specified as a list) can only be
3711 > 255 if the Erlang virtual machine is started in Unicode file‐
3712 name translation mode. Otherwise the name of the executable is
3713 limited to the ISO Latin-1 character set.
3714 PortNames:
3717 {spawn, Command}:
3719 Starts an external program. Command is the name of the
3720 external program to be run. Command runs outside the Erlang
3721 work space unless an Erlang driver with the name Command is
3722 found. If found, that driver is started. A driver runs in
3723 the Erlang work space, which means that it is linked with
3724 the Erlang runtime system.
3725 For external programs, PATH is searched (or an equivalent
3727 method is used to find programs, depending on the OS). This
3728 is done by invoking the shell on certain platforms. The
3729 first space-separated token of the command is considered as
3730 the name of the executable (or driver). This (among other
3731 things) makes this option unsuitable for running programs
3732 with spaces in filenames or directory names. If spaces in
3733 executable filenames are desired, use {spawn_executable,
3734 Command} instead.
3735 {spawn_driver, Command}:
3737 Works like {spawn, Command}, but demands the first (space-
3738 separated) token of the command to be the name of a loaded
3739 driver. If no driver with that name is loaded, a badarg
3740 error is raised.
3741 {spawn_executable, FileName}:
3743 Works like {spawn, FileName}, but only runs external exe‐
3744 cutables. FileName in its whole is used as the name of the
3745 executable, including any spaces. If arguments are to be
3746 passed, the PortSettings args and arg0 can be used.
3747 The shell is usually not invoked to start the program, it is
3749 executed directly. PATH (or equivalent) is not searched. To
3750 find a program in PATH to execute, use os:find_executable/1.
3751 Only if a shell script or .bat file is executed, the appro‐
3753 priate command interpreter is invoked implicitly, but there
3754 is still no command-argument expansion or implicit PATH
3755 search.
3756 If FileName cannot be run, an error exception is raised,
3758 with the POSIX error code as the reason. The error reason
3759 can differ between OSs. Typically the error enoent is raised
3760 when an attempt is made to run a program that is not found
3761 and eacces is raised when the specified file is not exe‐
3762 cutable.
3763 {fd, In, Out}:
3765 Allows an Erlang process to access any currently opened file
3766 descriptors used by Erlang. The file descriptor In can be
3767 used for standard input, and the file descriptor Out for
3768 standard output. It is only used for various servers in the
3769 Erlang OS (shell and user). Hence, its use is limited.
3770 PortSettings is a list of settings for the port. The valid set‐
3772 tings are as follows:
3773 {packet, N}:
3775 Messages are preceded by their length, sent in N bytes, with
3776 the most significant byte first. The valid values for N are
3777 1, 2, and 4.
3778 stream:
3780 Output messages are sent without packet lengths. A user-
3781 defined protocol must be used between the Erlang process and
3782 the external object.
3783 {line, L}:
3785 Messages are delivered on a per line basis. Each line
3786 (delimited by the OS-dependent newline sequence) is deliv‐
3787 ered in a single message. The message data format is {Flag,
3788 Line}, where Flag is eol or noeol, and Line is the data
3789 delivered (without the newline sequence).
3790 L specifies the maximum line length in bytes. Lines longer
3792 than this are delivered in more than one message, with Flag
3793 set to noeol for all but the last message. If end of file is
3794 encountered anywhere else than immediately following a new‐
3795 line sequence, the last line is also delivered with Flag set
3796 to noeol. Otherwise lines are delivered with Flag set to
3797 eol.
3798 The {packet, N} and {line, L} settings are mutually exclu‐
3800 sive.
3801 {cd, Dir}:
3803 Only valid for {spawn, Command} and {spawn_executable, File‐
3804 Name}. The external program starts using Dir as its working
3805 directory. Dir must be a string.
3806 {env, Env}:
3808 Types:
3809 Name = os:env_var_name()
3810 Val = os:env_var_value() | false
3811 Env = [{Name, Val}]
3812 Only valid for {spawn, Command}, and {spawn_executable,
3814 FileName}. The environment of the started process is
3815 extended using the environment specifications in Env.
3816 Env is to be a list of tuples {Name, Val}, where Name is the
3818 name of an environment variable, and Val is the value it is
3819 to have in the spawned port process. Both Name and Val must
3820 be strings. The one exception is Val being the atom false
3821 (in analogy with os:getenv/1, which removes the environment
3822 variable.
3823 For information about encoding requirements, see documenta‐
3825 tion of the types for Name and Val.
3826 {args, [ string() | binary() ]}:
3828 Only valid for {spawn_executable, FileName} and specifies
3829 arguments to the executable. Each argument is specified as a
3830 separate string and (on Unix) eventually ends up as one ele‐
3831 ment each in the argument vector. On other platforms, a sim‐
3832 ilar behavior is mimicked.
3833 The arguments are not expanded by the shell before they are
3835 supplied to the executable. Most notably this means that
3836 file wildcard expansion does not occur. To expand wildcards
3837 for the arguments, use filelib:wildcard/1. Notice that even
3838 if the program is a Unix shell script, meaning that the
3839 shell ultimately is invoked, wildcard expansion does not
3840 occur, and the script is provided with the untouched argu‐
3841 ments. On Windows, wildcard expansion is always up to the
3842 program itself, therefore this is not an issue.
3843 The executable name (also known as argv[0]) is not to be
3845 specified in this list. The proper executable name is auto‐
3846 matically used as argv[0], where applicable.
3847 If you explicitly want to set the program name in the argu‐
3849 ment vector, option arg0 can be used.
3850 {arg0, string() | binary()}:
3852 Only valid for {spawn_executable, FileName} and explicitly
3853 specifies the program name argument when running an exe‐
3854 cutable. This can in some circumstances, on some OSs, be
3855 desirable. How the program responds to this is highly sys‐
3856 tem-dependent and no specific effect is guaranteed.
3857 exit_status:
3859 Only valid for {spawn, Command}, where Command refers to an
3860 external program, and for {spawn_executable, FileName}.
3861 When the external process connected to the port exits, a
3863 message of the form {Port,{exit_status,Status}} is sent to
3864 the connected process, where Status is the exit status of
3865 the external process. If the program aborts on Unix, the
3866 same convention is used as the shells do (that is, 128+sig‐
3867 nal).
3868 If option eof is specified also, the messages eof and
3870 exit_status appear in an unspecified order.
3871 If the port program closes its stdout without exiting,
3873 option exit_status does not work.
3874 use_stdio:
3876 Only valid for {spawn, Command} and {spawn_executable, File‐
3877 Name}. It allows the standard input and output (file
3878 descriptors 0 and 1) of the spawned (Unix) process for com‐
3879 munication with Erlang.
3880 nouse_stdio:
3882 The opposite of use_stdio. It uses file descriptors 3 and 4
3883 for communication with Erlang.
3884 stderr_to_stdout:
3886 Affects ports to external programs. The executed program
3887 gets its standard error file redirected to its standard out‐
3888 put file. stderr_to_stdout and nouse_stdio are mutually
3889 exclusive.
3890 overlapped_io:
3892 Affects ports to external programs on Windows only. The
3893 standard input and standard output handles of the port pro‐
3894 gram are, if this option is supplied, opened with flag
3895 FILE_FLAG_OVERLAPPED, so that the port program can (and
3896 must) do overlapped I/O on its standard handles. This is not
3897 normally the case for simple port programs, but an option of
3898 value for the experienced Windows programmer. On all other
3899 platforms, this option is silently discarded.
3900 in:
3902 The port can only be used for input.
3903 out:
3905 The port can only be used for output.
3906 binary:
3908 All I/O from the port is binary data objects as opposed to
3909 lists of bytes.
3910 eof:
3912 The port is not closed at the end of the file and does not
3913 produce an exit signal. Instead, it remains open and a
3914 {Port, eof} message is sent to the process holding the port.
3915 hide:
3917 When running on Windows, suppresses creation of a new con‐
3918 sole window when spawning the port program. (This option has
3919 no effect on other platforms.)
3920 {parallelism, Boolean}:
3922 Sets scheduler hint for port parallelism. If set to true,
3925 the virtual machine schedules port tasks; when doing so, it
3926 improves parallelism in the system. If set to false, the
3927 virtual machine tries to perform port tasks immediately,
3928 improving latency at the expense of parallelism. The default
3929 can be set at system startup by passing command-line argu‐
3930 ment +spp to erl(1).
3931 {busy_limits_port, {Low, High} | disabled}:
3933 Sets limits that will be used for controlling the busy state
3934 of the port.
3935 When the ports internal output queue size becomes larger
3937 than or equal to High bytes, it enters the busy state. When
3938 it becomes less than Low bytes it leaves the busy state.
3939 When the port is in the busy state, processes sending com‐
3940 mands to it will be suspended until the port leaves the busy
3941 state. Commands are in this context either Port ! {Owner,
3942 {command, Data}} or port_command/[2,3].
3943 The Low limit is automatically adjusted to the same as High
3945 if it is set larger then High. Valid range of values for Low
3946 and High is [1, (1 bsl (8*erlang:system_info(wordsize)))-2].
3947 If the atom disabled is passed, the port will never enter
3948 the busy state.
3949 The defaults are Low = 4096 and High = 8192.
3951 Note that this option is only valid when spawning an exe‐
3953 cutable (port program) by opening the spawn driver and when
3954 opening the fd driver. This option will cause a failure with
3955 a badarg exception when opening other drivers.
3956 {busy_limits_msgq, {Low, High} | disabled}:
3958 Sets limits that will be used for controlling the busy state
3959 of the port message queue.
3960 When the ports message queue size becomes larger than or
3962 equal to High bytes it enters the busy state. When it
3963 becomes less than Low bytes it leaves the busy state. When
3964 the port message queue is in the busy state, processes send‐
3965 ing commands to it will be suspended until the port message
3966 queue leaves the busy state. Commands are in this context
3967 either Port ! {Owner, {command, Data}} or port_com‐
3968 mand/[2,3].
3969 The Low limit is automatically adjusted to the same as High
3971 if it is set larger then High. Valid range of values for Low
3972 and High is [1, (1 bsl (8*erlang:system_info(wordsize)))-2].
3973 If the atom disabled is passed, the port message queue will
3974 never enter the busy state.
3975 Note that if the driver statically has disabled the use of
3977 this feature, a failure with a badarg exception will be
3978 raised unless this option also is set to disable or not
3979 passed at all.
3980 The defaults are Low = 4096 and High = 8192 unless the
3982 driver itself does modifications of these values.
3983 Note that the driver might fail if it also adjust these lim‐
3985 its by itself and you have disabled this feature.
3986 The spawn driver (used when spawning an executable) and the
3988 fd driver do not disable this feature and do not adjust
3989 these limits by themselves.
3990 For more information see the documentation
3992 erl_drv_busy_msgq_limits().
3993 Default is stream for all port types and use_stdio for spawned
3995 ports.
3996 Failure: if the port cannot be opened, the exit reason is
3998 badarg, system_limit, or the POSIX error code that most closely
3999 describes the error, or einval if no POSIX code is appropriate:
4000 badarg:
4002 Bad input arguments to open_port.
4003 system_limit:
4005 All available ports in the Erlang emulator are in use.
4006 enomem:
4008 Not enough memory to create the port.
4009 eagain:
4011 No more available OS processes.
4012 enametoolong:
4014 Too long external command.
4015 emfile:
4017 No more available file descriptors (for the OS process that
4018 the Erlang emulator runs in).
4019 enfile:
4021 Full file table (for the entire OS).
4022 eacces:
4024 Command specified in {spawn_executable, Command} does not
4025 point out an executable file.
4026 enoent:
4028 FileName specified in {spawn_executable, FileName} does not
4029 point out an existing file.
4030 During use of a port opened using {spawn, Name}, {spawn_driver,
4032 Name}, or {spawn_executable, Name}, errors arising when sending
4033 messages to it are reported to the owning process using signals
4034 of the form {'EXIT', Port, PosixCode}. For the possible values
4035 of PosixCode, see file(3).
4036 The maximum number of ports that can be open at the same time
4038 can be configured by passing command-line flag +Q to erl(1).
4039 erlang:phash(Term, Range) -> Hash
4041 Types:
4043 Term = term()
4045 Range = Hash = integer() >= 1
4046 Range = 1..2^32, Hash = 1..Range
4047 Portable hash function that gives the same hash for the same
4049 Erlang term regardless of machine architecture and ERTS version
4050 (the BIF was introduced in ERTS 4.9.1.1). The function returns a
4051 hash value for Term within the range 1..Range. The maximum value
4052 for Range is 2^32.
4053 erlang:phash2(Term) -> Hash
4055 erlang:phash2(Term, Range) -> Hash
4057 Types:
4059 Term = term()
4061 Range = integer() >= 1
4062 1..2^32
4063 Hash = integer() >= 0
4064 0..Range-1
4065 Portable hash function that gives the same hash for the same
4067 Erlang term regardless of machine architecture and ERTS version
4068 (the BIF was introduced in ERTS 5.2). The function returns a
4069 hash value for Term within the range 0..Range-1. The maximum
4070 value for Range is 2^32. When without argument Range, a value in
4071 the range 0..2^27-1 is returned.
4072 This BIF is always to be used for hashing terms. It distributes
4074 small integers better than phash/2, and it is faster for bignums
4075 and binaries.
4076 Notice that the range 0..Range-1 is different from the range of
4078 phash/2, which is 1..Range.
4079 pid_to_list(Pid) -> string()
4081 Types:
4083 Pid = pid()
4085 Returns a string corresponding to the text representation of
4087 Pid.
4088 erlang:port_call(Port, Operation, Data) -> term()
4090 Types:
4092 Port = port() | atom()
4094 Operation = integer()
4095 Data = term()
4096 Performs a synchronous call to a port. The meaning of Operation
4098 and Data depends on the port, that is, on the port driver. Not
4099 all port drivers support this feature.
4100 Port is a port identifier, referring to a driver.
4102 Operation is an integer, which is passed on to the driver.
4104 Data is any Erlang term. This data is converted to binary term
4106 format and sent to the port.
4107 Returns a term from the driver. The meaning of the returned data
4109 also depends on the port driver.
4110 Failures:
4112 badarg:
4114 If Port is not an identifier of an open port, or the regis‐
4115 tered name of an open port. If the calling process was pre‐
4116 viously linked to the closed port, identified by Port, the
4117 exit signal from the port is guaranteed to be delivered
4118 before this badarg exception occurs.
4119 badarg:
4121 If Operation does not fit in a 32-bit integer.
4122 badarg:
4124 If the port driver does not support synchronous control
4125 operations.
4126 badarg:
4128 If the port driver so decides for any reason (probably some‐
4129 thing wrong with Operation or Data).
4130 Warning:
4132 Do not call port_call with an unknown Port identifier and
4133 expect badarg exception. Any undefined behavior is possible
4134 (including node crash) depending on how the port driver inter‐
4135 prets the supplied arguments.
4136 port_close(Port) -> true
4139 Types:
4141 Port = port() | atom()
4143 Closes an open port. Roughly the same as Port ! {self(), close}
4145 except for the error behavior (see below), being synchronous,
4146 and that the port does not reply with {Port, closed}. Any
4147 process can close a port with port_close/1, not only the port
4148 owner (the connected process). If the calling process is linked
4149 to the port identified by Port, the exit signal from the port is
4150 guaranteed to be delivered before port_close/1 returns.
4151 For comparison: Port ! {self(), close} only fails with badarg if
4153 Port does not refer to a port or a process. If Port is a closed
4154 port, nothing happens. If Port is an open port and the calling
4155 process is the port owner, the port replies with {Port, closed}
4156 when all buffers have been flushed and the port really closes.
4157 If the calling process is not the port owner, the port owner
4158 fails with badsig.
4159 Notice that any process can close a port using Port ! {Por‐
4161 tOwner, close} as if it itself was the port owner, but the reply
4162 always goes to the port owner.
4163 As from Erlang/OTP R16, Port ! {PortOwner, close} is truly asyn‐
4165 chronous. Notice that this operation has always been documented
4166 as an asynchronous operation, while the underlying implementa‐
4167 tion has been synchronous. port_close/1 is however still fully
4168 synchronous because of its error behavior.
4169 Failure: badarg if Port is not an identifier of an open port, or
4171 the registered name of an open port. If the calling process was
4172 previously linked to the closed port, identified by Port, the
4173 exit signal from the port is guaranteed to be delivered before
4174 this badarg exception occurs.
4175 port_command(Port, Data) -> true
4177 Types:
4179 Port = port() | atom()
4181 Data = iodata()
4182 Sends data to a port. Same as Port ! {PortOwner, {command,
4184 Data}} except for the error behavior and being synchronous (see
4185 below). Any process can send data to a port with port_command/2,
4186 not only the port owner (the connected process).
4187 For comparison: Port ! {PortOwner, {command, Data}} only fails
4189 with badarg if Port does not refer to a port or a process. If
4190 Port is a closed port, the data message disappears without a
4191 sound. If Port is open and the calling process is not the port
4192 owner, the port owner fails with badsig. The port owner fails
4193 with badsig also if Data is an invalid I/O list.
4194 Notice that any process can send to a port using Port ! {Por‐
4196 tOwner, {command, Data}} as if it itself was the port owner.
4197 If the port is busy, the calling process is suspended until the
4199 port is not busy any more.
4200 As from Erlang/OTP R16, Port ! {PortOwner, {command, Data}} is
4202 truly asynchronous. Notice that this operation has always been
4203 documented as an asynchronous operation, while the underlying
4204 implementation has been synchronous. port_command/2 is however
4205 still fully synchronous because of its error behavior.
4206 Failures:
4208 badarg:
4210 If Port is not an identifier of an open port, or the regis‐
4211 tered name of an open port. If the calling process was pre‐
4212 viously linked to the closed port, identified by Port, the
4213 exit signal from the port is guaranteed to be delivered
4214 before this badarg exception occurs.
4215 badarg:
4217 If Data is an invalid I/O list.
4218 Warning:
4220 Do not send data to an unknown port. Any undefined behavior is
4221 possible (including node crash) depending on how the port driver
4222 interprets the data.
4223 port_command(Port, Data, OptionList) -> boolean()
4226 Types:
4228 Port = port() | atom()
4230 Data = iodata()
4231 Option = force | nosuspend
4232 OptionList = [Option]
4233 Sends data to a port. port_command(Port, Data, []) equals
4235 port_command(Port, Data).
4236 If the port command is aborted, false is returned, otherwise
4238 true.
4239 If the port is busy, the calling process is suspended until the
4241 port is not busy anymore.
4242 Options:
4244 force:
4246 The calling process is not suspended if the port is busy,
4247 instead the port command is forced through. The call fails
4248 with a notsup exception if the driver of the port does not
4249 support this. For more information, see driver flag
4250 ![CDATA[ERL_DRV_FLAG_SOFT_BUSY]].
4251 nosuspend:
4253 The calling process is not suspended if the port is busy,
4254 instead the port command is aborted and false is returned.
4255 Note:
4257 More options can be added in a future release.
4258 Failures:
4261 badarg:
4263 If Port is not an identifier of an open port, or the regis‐
4264 tered name of an open port. If the calling process was pre‐
4265 viously linked to the closed port, identified by Port, the
4266 exit signal from the port is guaranteed to be delivered
4267 before this badarg exception occurs.
4268 badarg:
4270 If Data is an invalid I/O list.
4271 badarg:
4273 If OptionList is an invalid option list.
4274 notsup:
4276 If option force has been passed, but the driver of the port
4277 does not allow forcing through a busy port.
4278 Warning:
4280 Do not send data to an unknown port. Any undefined behavior is
4281 possible (including node crash) depending on how the port driver
4282 interprets the data.
4283 port_connect(Port, Pid) -> true
4286 Types:
4288 Port = port() | atom()
4290 Pid = pid()
4291 Sets the port owner (the connected port) to Pid. Roughly the
4293 same as Port ! {Owner, {connect, Pid}} except for the following:
4294 * The error behavior differs, see below.
4296 * The port does not reply with {Port,connected}.
4298 * port_connect/1 is synchronous, see below.
4300 * The new port owner gets linked to the port.
4302 The old port owner stays linked to the port and must call
4304 unlink(Port) if this is not desired. Any process can set the
4305 port owner to be any process with port_connect/2.
4306 For comparison: Port ! {self(), {connect, Pid}} only fails with
4308 badarg if Port does not refer to a port or a process. If Port is
4309 a closed port, nothing happens. If Port is an open port and the
4310 calling process is the port owner, the port replies with {Port,
4311 connected} to the old port owner. Notice that the old port owner
4312 is still linked to the port, while the new is not. If Port is an
4313 open port and the calling process is not the port owner, the
4314 port owner fails with badsig. The port owner fails with badsig
4315 also if Pid is not an existing local process identifier.
4316 Notice that any process can set the port owner using Port !
4318 {PortOwner, {connect, Pid}} as if it itself was the port owner,
4319 but the reply always goes to the port owner.
4320 As from Erlang/OTP R16, Port ! {PortOwner, {connect, Pid}} is
4322 truly asynchronous. Notice that this operation has always been
4323 documented as an asynchronous operation, while the underlying
4324 implementation has been synchronous. port_connect/2 is however
4325 still fully synchronous because of its error behavior.
4326 Failures:
4328 badarg:
4330 If Port is not an identifier of an open port, or the regis‐
4331 tered name of an open port. If the calling process was pre‐
4332 viously linked to the closed port, identified by Port, the
4333 exit signal from the port is guaranteed to be delivered
4334 before this badarg exception occurs.
4335 badarg:
4337 If the process identified by Pid is not an existing local
4338 process.
4339 port_control(Port, Operation, Data) -> iodata() | binary()
4341 Types:
4343 Port = port() | atom()
4345 Operation = integer()
4346 Data = iodata()
4347 Performs a synchronous control operation on a port. The meaning
4349 of Operation and Data depends on the port, that is, on the port
4350 driver. Not all port drivers support this control feature.
4351 Returns a list of integers in the range 0..255, or a binary,
4353 depending on the port driver. The meaning of the returned data
4354 also depends on the port driver.
4355 Failures:
4357 badarg:
4359 If Port is not an open port or the registered name of an
4360 open port.
4361 badarg:
4363 If Operation cannot fit in a 32-bit integer.
4364 badarg:
4366 If the port driver does not support synchronous control
4367 operations.
4368 badarg:
4370 If the port driver so decides for any reason (probably
4371 something wrong with Operation or Data).
4372 Warning:
4374 Do not call port_control/3 with an unknown Port identifier and
4375 expect badarg exception. Any undefined behavior is possible
4376 (including node crash) depending on how the port driver inter‐
4377 prets the supplied arguments.
4378 erlang:port_info(Port) -> Result
4381 Types:
4383 Port = port() | atom()
4385 ResultItem =
4386 {registered_name, RegisteredName :: atom()} |
4387 {id, Index :: integer() >= 0} |
4388 {connected, Pid :: pid()} |
4389 {links, Pids :: [pid()]} |
4390 {name, String :: string()} |
4391 {input, Bytes :: integer() >= 0} |
4392 {output, Bytes :: integer() >= 0} |
4393 {os_pid, OsPid :: integer() >= 0 | undefined}
4394 Result = [ResultItem] | undefined
4395 Returns a list containing tuples with information about Port, or
4397 undefined if the port is not open. The order of the tuples is
4398 undefined, and all the tuples are not mandatory. If the port is
4399 closed and the calling process was previously linked to the
4400 port, the exit signal from the port is guaranteed to be deliv‐
4401 ered before port_info/1 returns undefined.
4402 The result contains information about the following Items:
4404 * registered_name (if the port has a registered name)
4406 * id
4408 * connected
4410 * links
4412 * name
4414 * input
4416 * output
4418 For more information about the different Items, see port_info/2.
4420 Failure: badarg if Port is not a local port identifier, or an
4422 atom.
4423 erlang:port_info(Port, Item :: connected) ->
4425 {connected, Pid} | undefined
4426 Types:
4428 Port = port() | atom()
4430 Pid = pid()
4431 Pid is the process identifier of the process connected to the
4433 port.
4434 If the port identified by Port is not open, undefined is
4436 returned. If the port is closed and the calling process was pre‐
4437 viously linked to the port, the exit signal from the port is
4438 guaranteed to be delivered before port_info/2 returns undefined.
4439 Failure: badarg if Port is not a local port identifier, or an
4441 atom.
4442 erlang:port_info(Port, Item :: id) -> {id, Index} | undefined
4444 Types:
4446 Port = port() | atom()
4448 Index = integer() >= 0
4449 Index is the internal index of the port. This index can be used
4451 to separate ports.
4452 If the port identified by Port is not open, undefined is
4454 returned. If the port is closed and the calling process was pre‐
4455 viously linked to the port, the exit signal from the port is
4456 guaranteed to be delivered before port_info/2 returns undefined.
4457 Failure: badarg if Port is not a local port identifier, or an
4459 atom.
4460 erlang:port_info(Port, Item :: input) ->
4462 {input, Bytes} | undefined
4463 Types:
4465 Port = port() | atom()
4467 Bytes = integer() >= 0
4468 Bytes is the total number of bytes read from the port.
4470 If the port identified by Port is not open, undefined is
4472 returned. If the port is closed and the calling process was pre‐
4473 viously linked to the port, the exit signal from the port is
4474 guaranteed to be delivered before port_info/2 returns undefined.
4475 Failure: badarg if Port is not a local port identifier, or an
4477 atom.
4478 erlang:port_info(Port, Item :: links) -> {links, Pids} | undefined
4480 Types:
4482 Port = port() | atom()
4484 Pids = [pid()]
4485 Pids is a list of the process identifiers of the processes that
4487 the port is linked to.
4488 If the port identified by Port is not open, undefined is
4490 returned. If the port is closed and the calling process was pre‐
4491 viously linked to the port, the exit signal from the port is
4492 guaranteed to be delivered before port_info/2 returns undefined.
4493 Failure: badarg if Port is not a local port identifier, or an
4495 atom.
4496 erlang:port_info(Port, Item :: locking) ->
4498 {locking, Locking} | undefined
4499 Types:
4501 Port = port() | atom()
4503 Locking = false | port_level | driver_level
4504 Locking is one of the following:
4506 * port_level (port-specific locking)
4508 * driver_level (driver-specific locking)
4510 Notice that these results are highly implementation-specific and
4512 can change in a future release.
4513 If the port identified by Port is not open, undefined is
4515 returned. If the port is closed and the calling process was pre‐
4516 viously linked to the port, the exit signal from the port is
4517 guaranteed to be delivered before port_info/2 returns undefined.
4518 Failure: badarg if Port is not a local port identifier, or an
4520 atom.
4521 erlang:port_info(Port, Item :: memory) ->
4523 {memory, Bytes} | undefined
4524 Types:
4526 Port = port() | atom()
4528 Bytes = integer() >= 0
4529 Bytes is the total number of bytes allocated for this port by
4531 the runtime system. The port itself can have allocated memory
4532 that is not included in Bytes.
4533 If the port identified by Port is not open, undefined is
4535 returned. If the port is closed and the calling process was pre‐
4536 viously linked to the port, the exit signal from the port is
4537 guaranteed to be delivered before port_info/2 returns undefined.
4538 Failure: badarg if Port is not a local port identifier, or an
4540 atom.
4541 erlang:port_info(Port, Item :: monitors) ->
4543 {monitors, Monitors} | undefined
4544 Types:
4546 Port = port() | atom()
4548 Monitors = [{process, pid()}]
4549 Monitors represent processes monitored by this port.
4551 If the port identified by Port is not open, undefined is
4553 returned. If the port is closed and the calling process was pre‐
4554 viously linked to the port, the exit signal from the port is
4555 guaranteed to be delivered before port_info/2 returns undefined.
4556 Failure: badarg if Port is not a local port identifier, or an
4558 atom.
4559 erlang:port_info(Port, Item :: monitored_by) ->
4561 {monitored_by, MonitoredBy} | undefined
4562 Types:
4564 Port = port() | atom()
4566 MonitoredBy = [pid()]
4567 Returns list of pids that are monitoring given port at the
4569 moment.
4570 If the port identified by Port is not open, undefined is
4572 returned. If the port is closed and the calling process was pre‐
4573 viously linked to the port, the exit signal from the port is
4574 guaranteed to be delivered before port_info/2 returns undefined.
4575 Failure: badarg if Port is not a local port identifier, or an
4577 atom.
4578 erlang:port_info(Port, Item :: name) -> {name, Name} | undefined
4580 Types:
4582 Port = port() | atom()
4584 Name = string()
4585 Name is the command name set by open_port/2.
4587 If the port identified by Port is not open, undefined is
4589 returned. If the port is closed and the calling process was pre‐
4590 viously linked to the port, the exit signal from the port is
4591 guaranteed to be delivered before port_info/2 returns undefined.
4592 Failure: badarg if Port is not a local port identifier, or an
4594 atom.
4595 erlang:port_info(Port, Item :: os_pid) ->
4597 {os_pid, OsPid} | undefined
4598 Types:
4600 Port = port() | atom()
4602 OsPid = integer() >= 0 | undefined
4603 OsPid is the process identifier (or equivalent) of an OS process
4605 created with open_port({spawn | spawn_executable, Command},
4606 Options). If the port is not the result of spawning an OS
4607 process, the value is undefined.
4608 If the port identified by Port is not open, undefined is
4610 returned. If the port is closed and the calling process was pre‐
4611 viously linked to the port, the exit signal from the port is
4612 guaranteed to be delivered before port_info/2 returns undefined.
4613 Failure: badarg if Port is not a local port identifier, or an
4615 atom.
4616 erlang:port_info(Port, Item :: output) ->
4618 {output, Bytes} | undefined
4619 Types:
4621 Port = port() | atom()
4623 Bytes = integer() >= 0
4624 Bytes is the total number of bytes written to the port from
4626 Erlang processes using port_command/2, port_command/3, or Port !
4627 {Owner, {command, Data}.
4628 If the port identified by Port is not open, undefined is
4630 returned. If the port is closed and the calling process was pre‐
4631 viously linked to the port, the exit signal from the port is
4632 guaranteed to be delivered before port_info/2 returns undefined.
4633 Failure: badarg if Port is not a local port identifier, or an
4635 atom.
4636 erlang:port_info(Port, Item :: parallelism) ->
4638 {parallelism, Boolean} | undefined
4639 Types:
4641 Port = port() | atom()
4643 Boolean = boolean()
4644 Boolean corresponds to the port parallelism hint used by this
4646 port. For more information, see option parallelism of
4647 open_port/2.
4648 erlang:port_info(Port, Item :: queue_size) ->
4650 {queue_size, Bytes} | undefined
4651 Types:
4653 Port = port() | atom()
4655 Bytes = integer() >= 0
4656 Bytes is the total number of bytes queued by the port using the
4658 ERTS driver queue implementation.
4659 If the port identified by Port is not open, undefined is
4661 returned. If the port is closed and the calling process was pre‐
4662 viously linked to the port, the exit signal from the port is
4663 guaranteed to be delivered before port_info/2 returns undefined.
4664 Failure: badarg if Port is not a local port identifier, or an
4666 atom.
4667 erlang:port_info(Port, Item :: registered_name) ->
4669 {registered_name, RegisteredName} |
4670 [] | undefined
4671 Types:
4673 Port = port() | atom()
4675 RegisteredName = atom()
4676 RegisteredName is the registered name of the port. If the port
4678 has no registered name, [] is returned.
4679 If the port identified by Port is not open, undefined is
4681 returned. If the port is closed and the calling process was pre‐
4682 viously linked to the port, the exit signal from the port is
4683 guaranteed to be delivered before port_info/2 returns undefined.
4684 Failure: badarg if Port is not a local port identifier, or an
4686 atom.
4687 port_to_list(Port) -> string()
4689 Types:
4691 Port = port()
4693 Returns a string corresponding to the text representation of the
4695 port identifier Port.
4696 erlang:ports() -> [port()]
4698 Returns a list of port identifiers corresponding to all the
4700 ports existing on the local node.
4701 Notice that an exiting port exists, but is not open.
4703 pre_loaded() -> [module()]
4705 Returns a list of Erlang modules that are preloaded in the sys‐
4707 tem. As all loading of code is done through the file system, the
4708 file system must have been loaded previously. Hence, at least
4709 the module init must be preloaded.
4710 erlang:process_display(Pid, Type) -> true
4712 Types:
4714 Pid = pid()
4716 Type = backtrace
4717 Writes information about the local process Pid on standard
4719 error. The only allowed value for the atom Type is backtrace,
4720 which shows the contents of the call stack, including informa‐
4721 tion about the call chain, with the current function printed
4722 first. The format of the output is not further defined.
4723 process_flag(Flag :: trap_exit, Boolean) -> OldBoolean
4725 Types:
4727 Boolean = OldBoolean = boolean()
4729 When trap_exit is set to true, exit signals arriving to a
4731 process are converted to {'EXIT', From, Reason} messages, which
4732 can be received as ordinary messages. If trap_exit is set to
4733 false, the process exits if it receives an exit signal other
4734 than normal and the exit signal is propagated to its linked pro‐
4735 cesses. Application processes are normally not to trap exits.
4736 Returns the old value of the flag.
4738 See also exit/2.
4740 process_flag(Flag :: error_handler, Module) -> OldModule
4742 Types:
4744 Module = OldModule = atom()
4746 Used by a process to redefine the error handler for undefined
4748 function calls and undefined registered processes. Inexperienced
4749 users are not to use this flag, as code auto-loading depends on
4750 the correct operation of the error handling module.
4751 Returns the old value of the flag.
4753 process_flag(Flag :: min_heap_size, MinHeapSize) -> OldMinHeapSize
4755 Types:
4757 MinHeapSize = OldMinHeapSize = integer() >= 0
4759 Changes the minimum heap size for the calling process.
4761 Returns the old value of the flag.
4763 process_flag(Flag :: min_bin_vheap_size, MinBinVHeapSize) ->
4765 OldMinBinVHeapSize
4766 Types:
4768 MinBinVHeapSize = OldMinBinVHeapSize = integer() >= 0
4770 Changes the minimum binary virtual heap size for the calling
4772 process.
4773 Returns the old value of the flag.
4775 process_flag(Flag :: max_heap_size, MaxHeapSize) -> OldMaxHeapSize
4777 Types:
4779 MaxHeapSize = OldMaxHeapSize = max_heap_size()
4781 max_heap_size() =
4782 integer() >= 0 |
4783 #{size => integer() >= 0,
4784 kill => boolean(),
4785 error_logger => boolean()}
4786 This flag sets the maximum heap size for the calling process. If
4788 MaxHeapSize is an integer, the system default values for kill
4789 and error_logger are used.
4790 size:
4792 The maximum size in words of the process. If set to zero,
4793 the heap size limit is disabled. badarg is be thrown if the
4794 value is smaller than min_heap_size. The size check is only
4795 done when a garbage collection is triggered.
4796 size is the entire heap of the process when garbage collec‐
4798 tion is triggered. This includes all generational heaps, the
4799 process stack, any messages that are considered to be part
4800 of the heap, and any extra memory that the garbage collector
4801 needs during collection.
4802 size is the same as can be retrieved using
4804 erlang:process_info(Pid, total_heap_size), or by adding
4805 heap_block_size, old_heap_block_size and mbuf_size from
4806 erlang:process_info(Pid, garbage_collection_info).
4807 kill:
4809 When set to true, the runtime system sends an untrappable
4810 exit signal with reason kill to the process if the maximum
4811 heap size is reached. The garbage collection that triggered
4812 the kill is not completed, instead the process exits as soon
4813 as possible. When set to false, no exit signal is sent to
4814 the process, instead it continues executing.
4815 If kill is not defined in the map, the system default will
4817 be used. The default system default is true. It can be
4818 changed by either option +hmaxk in erl(1), or erlang:sys‐
4819 tem_flag(max_heap_size, MaxHeapSize).
4820 error_logger:
4822 When set to true, the runtime system logs an error event via
4823 logger, containing details about the process when the maxi‐
4824 mum heap size is reached. One log event is sent each time
4825 the limit is reached.
4826 If error_logger is not defined in the map, the system
4828 default is used. The default system default is true. It can
4829 be changed by either the option +hmaxel int erl(1), or
4830 erlang:system_flag(max_heap_size, MaxHeapSize).
4831 The heap size of a process is quite hard to predict, especially
4833 the amount of memory that is used during the garbage collection.
4834 When contemplating using this option, it is recommended to first
4835 run it in production with kill set to false and inspect the log
4836 events to see what the normal peak sizes of the processes in the
4837 system is and then tune the value accordingly.
4838 process_flag(Flag :: message_queue_data, MQD) -> OldMQD
4840 Types:
4842 MQD = OldMQD = message_queue_data()
4844 message_queue_data() = off_heap | on_heap
4845 This flag determines how messages in the message queue are
4847 stored, as follows:
4848 off_heap:
4850 All messages in the message queue will be stored outside of
4851 the process heap. This implies that no messages in the mes‐
4852 sage queue will be part of a garbage collection of the
4853 process.
4854 on_heap:
4856 All messages in the message queue will eventually be placed
4857 on heap. They can however temporarily be stored off heap.
4858 This is how messages always have been stored up until ERTS
4859 8.0.
4860 The default message_queue_data process flag is determined by
4862 command-line argument +hmqd in erl(1).
4863 If the process potentially can get many messages in its queue,
4865 you are advised to set the flag to off_heap. This because a
4866 garbage collection with many messages placed on the heap can
4867 become extremely expensive and the process can consume large
4868 amounts of memory. Performance of the actual message passing is
4869 however generally better when not using flag off_heap.
4870 When changing this flag messages will be moved. This work has
4872 been initiated but not completed when this function call
4873 returns.
4874 Returns the old value of the flag.
4876 process_flag(Flag :: priority, Level) -> OldLevel
4878 Types:
4880 Level = OldLevel = priority_level()
4882 priority_level() = low | normal | high | max
4883 Sets the process priority. Level is an atom. Four priority lev‐
4885 els exist: low, normal, high, and max. Default is normal.
4886 Note:
4888 Priority level max is reserved for internal use in the Erlang
4889 runtime system, and is not to be used by others.
4890 Internally in each priority level, processes are scheduled in a
4893 round robin fashion.
4894 Execution of processes on priority normal and low are inter‐
4896 leaved. Processes on priority low are selected for execution
4897 less frequently than processes on priority normal.
4898 When runnable processes on priority high exist, no processes on
4900 priority low or normal are selected for execution. Notice how‐
4901 ever that this does not mean that no processes on priority low
4902 or normal can run when processes are running on priority high.
4903 When using multiple schedulers, more processes can be running in
4904 parallel than processes on priority high. That is, a low and a
4905 high priority process can execute at the same time.
4906 When runnable processes on priority max exist, no processes on
4908 priority low, normal, or high are selected for execution. As
4909 with priority high, processes on lower priorities can execute in
4910 parallel with processes on priority max.
4911 Scheduling is pre-emptive. Regardless of priority, a process is
4913 pre-empted when it has consumed more than a certain number of
4914 reductions since the last time it was selected for execution.
4915 Note:
4917 Do not depend on the scheduling to remain exactly as it is
4918 today. Scheduling is likely to be changed in a future release to
4919 use available processor cores better.
4920 There is no automatic mechanism for avoiding priority inversion,
4923 such as priority inheritance or priority ceilings. When using
4924 priorities, take this into account and handle such scenarios by
4925 yourself.
4926 Making calls from a high priority process into code that you has
4928 no control over can cause the high priority process to wait for
4929 a process with lower priority. That is, effectively decreasing
4930 the priority of the high priority process during the call. Even
4931 if this is not the case with one version of the code that you
4932 have no control over, it can be the case in a future version of
4933 it. This can, for example, occur if a high priority process
4934 triggers code loading, as the code server runs on priority nor‐
4935 mal.
4936 Other priorities than normal are normally not needed. When other
4938 priorities are used, use them with care, especially priority
4939 high. A process on priority high is only to perform work for
4940 short periods. Busy looping for long periods in a high priority
4941 process causes most likely problems, as important OTP servers
4942 run on priority normal.
4943 Returns the old value of the flag.
4945 process_flag(Flag :: save_calls, N) -> OldN
4947 Types:
4949 N = OldN = 0..10000
4951 N must be an integer in the interval 0..10000. If N > 0, call
4953 saving is made active for the process. This means that informa‐
4954 tion about the N most recent global function calls, BIF calls,
4955 sends, and receives made by the process are saved in a list,
4956 which can be retrieved with process_info(Pid, last_calls). A
4957 global function call is one in which the module of the function
4958 is explicitly mentioned. Only a fixed amount of information is
4959 saved, as follows:
4960 * A tuple {Module, Function, Arity} for function calls
4962 * The atoms send, 'receive', and timeout for sends and
4964 receives ('receive' when a message is received and timeout
4965 when a receive times out)
4966 If N = 0, call saving is disabled for the process, which is the
4968 default. Whenever the size of the call saving list is set, its
4969 contents are reset.
4970 Returns the old value of the flag.
4972 process_flag(Flag :: sensitive, Boolean) -> OldBoolean
4974 Types:
4976 Boolean = OldBoolean = boolean()
4978 Sets or clears flag sensitive for the current process. When a
4980 process has been marked as sensitive by calling
4981 process_flag(sensitive, true), features in the runtime system
4982 that can be used for examining the data or inner working of the
4983 process are silently disabled.
4984 Features that are disabled include (but are not limited to) the
4986 following:
4987 * Tracing. Trace flags can still be set for the process, but
4989 no trace messages of any kind are generated. (If flag sensi‐
4990 tive is turned off, trace messages are again generated if
4991 any trace flags are set.)
4992 * Sequential tracing. The sequential trace token is propagated
4994 as usual, but no sequential trace messages are generated.
4995 process_info/1,2 cannot be used to read out the message queue or
4997 the process dictionary (both are returned as empty lists).
4998 Stack back-traces cannot be displayed for the process.
5000 In crash dumps, the stack, messages, and the process dictionary
5002 are omitted.
5003 If {save_calls,N} has been set for the process, no function
5005 calls are saved to the call saving list. (The call saving list
5006 is not cleared. Also, send, receive, and time-out events are
5007 still added to the list.)
5008 Returns the old value of the flag.
5010 process_flag(Pid, Flag, Value) -> OldValue
5012 Types:
5014 Pid = pid()
5016 Flag = save_calls
5017 Value = OldValue = integer() >= 0
5018 Sets certain flags for the process Pid, in the same manner as
5020 process_flag/2. Returns the old value of the flag. The valid
5021 values for Flag are only a subset of those allowed in
5022 process_flag/2, namely save_calls.
5023 Failure: badarg if Pid is not a local process.
5025 process_info(Pid) -> Info
5027 Types:
5029 Pid = pid()
5031 Info = [InfoTuple] | undefined
5032 InfoTuple = process_info_result_item()
5033 process_info_result_item() =
5034 {backtrace, Bin :: binary()} |
5035 {binary,
5036 BinInfo ::
5037 [{integer() >= 0,
5038 integer() >= 0,
5039 integer() >= 0}]} |
5040 {catchlevel, CatchLevel :: integer() >= 0} |
5041 {current_function,
5042 {Module :: module(), Function :: atom(), Arity :: arity()} |
5043 undefined} |
5044 {current_location,
5045 {Module :: module(),
5046 Function :: atom(),
5047 Arity :: arity(),
5048 Location ::
5049 [{file, Filename :: string()} |
5050 {line, Line :: integer() >= 1}]}} |
5051 {current_stacktrace, Stack :: [stack_item()]} |
5052 {dictionary, Dictionary :: [{Key :: term(), Value :: term()}]} |
5053 {error_handler, Module :: module()} |
5054 {garbage_collection, GCInfo :: [{atom(), integer() >= 0}]} |
5055 {garbage_collection_info,
5056 GCInfo :: [{atom(), integer() >= 0}]} |
5057 {group_leader, GroupLeader :: pid()} |
5058 {heap_size, Size :: integer() >= 0} |
5059 {initial_call, mfa()} |
5060 {links, PidsAndPorts :: [pid() | port()]} |
5061 {last_calls, false | (Calls :: [mfa()])} |
5062 {memory, Size :: integer() >= 0} |
5063 {message_queue_len, MessageQueueLen :: integer() >= 0} |
5064 {messages, MessageQueue :: [term()]} |
5065 {min_heap_size, MinHeapSize :: integer() >= 0} |
5066 {min_bin_vheap_size, MinBinVHeapSize :: integer() >= 0} |
5067 {max_heap_size, MaxHeapSize :: max_heap_size()} |
5068 {monitored_by,
5069 MonitoredBy :: [pid() | port() | nif_resource()]} |
5070 {monitors,
5071 Monitors ::
5072 [{process | port,
5073 Pid ::
5074 pid() |
5075 port() |
5076 {RegName :: atom(), Node :: node()}}]} |
5077 {message_queue_data, MQD :: message_queue_data()} |
5078 {priority, Level :: priority_level()} |
5079 {reductions, Number :: integer() >= 0} |
5080 {registered_name, [] | (Atom :: atom())} |
5081 {sequential_trace_token,
5082 [] | (SequentialTraceToken :: term())} |
5083 {stack_size, Size :: integer() >= 0} |
5084 {status,
5085 Status ::
5086 exiting | garbage_collecting | waiting | running |
5087 runnable | suspended} |
5088 {suspending,
5089 SuspendeeList ::
5090 [{Suspendee :: pid(),
5091 ActiveSuspendCount :: integer() >= 0,
5092 OutstandingSuspendCount :: integer() >= 0}]} |
5093 {total_heap_size, Size :: integer() >= 0} |
5094 {trace, InternalTraceFlags :: integer() >= 0} |
5095 {trap_exit, Boolean :: boolean()}
5096 priority_level() = low | normal | high | max
5097 stack_item() =
5098 {Module :: module(),
5099 Function :: atom(),
5100 Arity :: arity() | (Args :: [term()]),
5101 Location ::
5102 [{file, Filename :: string()} |
5103 {line, Line :: integer() >= 1}]}
5104 max_heap_size() =
5105 integer() >= 0 |
5106 #{size => integer() >= 0,
5107 kill => boolean(),
5108 error_logger => boolean()}
5109 message_queue_data() = off_heap | on_heap
5110 Returns a list containing InfoTuples with miscellaneous informa‐
5112 tion about the process identified by Pid, or undefined if the
5113 process is not alive.
5114 The order of the InfoTuples is undefined and all InfoTuples are
5116 not mandatory. The InfoTuples part of the result can be changed
5117 without prior notice.
5118 The InfoTuples with the following items are part of the result:
5120 * current_function
5122 * initial_call
5124 * status
5126 * message_queue_len
5128 * links
5130 * dictionary
5132 * trap_exit
5134 * error_handler
5136 * priority
5138 * group_leader
5140 * total_heap_size
5142 * heap_size
5144 * stack_size
5146 * reductions
5148 * garbage_collection
5150 If the process identified by Pid has a registered name, also an
5152 InfoTuple with item registered_name is included.
5153 For information about specific InfoTuples, see process_info/2.
5155 Warning:
5157 This BIF is intended for debugging only. For all other purposes,
5158 use process_info/2.
5159 Failure: badarg if Pid is not a local process.
5162 process_info(Pid, Item) -> InfoTuple | [] | undefined
5164 process_info(Pid, ItemList) -> InfoTupleList | [] | undefined
5166 Types:
5168 Pid = pid()
5170 ItemList = [Item]
5171 Item = process_info_item()
5172 InfoTupleList = [InfoTuple]
5173 InfoTuple = process_info_result_item()
5174 process_info_item() =
5175 backtrace | binary | catchlevel | current_function |
5176 current_location | current_stacktrace | dictionary |
5177 error_handler | garbage_collection | garbage_collection_info |
5178 group_leader | heap_size | initial_call | links | last_calls |
5179 memory | message_queue_len | messages | min_heap_size |
5180 min_bin_vheap_size | monitored_by | monitors |
5181 message_queue_data | priority | reductions | registered_name |
5182 sequential_trace_token | stack_size | status | suspending |
5183 total_heap_size | trace | trap_exit
5184 process_info_result_item() =
5185 {backtrace, Bin :: binary()} |
5186 {binary,
5187 BinInfo ::
5188 [{integer() >= 0,
5189 integer() >= 0,
5190 integer() >= 0}]} |
5191 {catchlevel, CatchLevel :: integer() >= 0} |
5192 {current_function,
5193 {Module :: module(), Function :: atom(), Arity :: arity()} |
5194 undefined} |
5195 {current_location,
5196 {Module :: module(),
5197 Function :: atom(),
5198 Arity :: arity(),
5199 Location ::
5200 [{file, Filename :: string()} |
5201 {line, Line :: integer() >= 1}]}} |
5202 {current_stacktrace, Stack :: [stack_item()]} |
5203 {dictionary, Dictionary :: [{Key :: term(), Value :: term()}]} |
5204 {error_handler, Module :: module()} |
5205 {garbage_collection, GCInfo :: [{atom(), integer() >= 0}]} |
5206 {garbage_collection_info,
5207 GCInfo :: [{atom(), integer() >= 0}]} |
5208 {group_leader, GroupLeader :: pid()} |
5209 {heap_size, Size :: integer() >= 0} |
5210 {initial_call, mfa()} |
5211 {links, PidsAndPorts :: [pid() | port()]} |
5212 {last_calls, false | (Calls :: [mfa()])} |
5213 {memory, Size :: integer() >= 0} |
5214 {message_queue_len, MessageQueueLen :: integer() >= 0} |
5215 {messages, MessageQueue :: [term()]} |
5216 {min_heap_size, MinHeapSize :: integer() >= 0} |
5217 {min_bin_vheap_size, MinBinVHeapSize :: integer() >= 0} |
5218 {max_heap_size, MaxHeapSize :: max_heap_size()} |
5219 {monitored_by,
5220 MonitoredBy :: [pid() | port() | nif_resource()]} |
5221 {monitors,
5222 Monitors ::
5223 [{process | port,
5224 Pid ::
5225 pid() |
5226 port() |
5227 {RegName :: atom(), Node :: node()}}]} |
5228 {message_queue_data, MQD :: message_queue_data()} |
5229 {priority, Level :: priority_level()} |
5230 {reductions, Number :: integer() >= 0} |
5231 {registered_name, [] | (Atom :: atom())} |
5232 {sequential_trace_token,
5233 [] | (SequentialTraceToken :: term())} |
5234 {stack_size, Size :: integer() >= 0} |
5235 {status,
5236 Status ::
5237 exiting | garbage_collecting | waiting | running |
5238 runnable | suspended} |
5239 {suspending,
5240 SuspendeeList ::
5241 [{Suspendee :: pid(),
5242 ActiveSuspendCount :: integer() >= 0,
5243 OutstandingSuspendCount :: integer() >= 0}]} |
5244 {total_heap_size, Size :: integer() >= 0} |
5245 {trace, InternalTraceFlags :: integer() >= 0} |
5246 {trap_exit, Boolean :: boolean()}
5247 stack_item() =
5248 {Module :: module(),
5249 Function :: atom(),
5250 Arity :: arity() | (Args :: [term()]),
5251 Location ::
5252 [{file, Filename :: string()} |
5253 {line, Line :: integer() >= 1}]}
5254 priority_level() = low | normal | high | max
5255 max_heap_size() =
5256 integer() >= 0 |
5257 #{size => integer() >= 0,
5258 kill => boolean(),
5259 error_logger => boolean()}
5260 message_queue_data() = off_heap | on_heap
5261 Returns information about the process identified by Pid, as
5263 specified by Item or ItemList. Returns undefined if the process
5264 is not alive.
5265 If the process is alive and a single Item is specified, the
5267 returned value is the corresponding InfoTuple, unless Item =:=
5268 registered_name and the process has no registered name. In this
5269 case, [] is returned. This strange behavior is because of his‐
5270 torical reasons, and is kept for backward compatibility.
5271 If ItemList is specified, the result is InfoTupleList. The Info‐
5273 Tuples in InfoTupleList are included with the corresponding
5274 Items in the same order as the Items were included in ItemList.
5275 Valid Items can be included multiple times in ItemList.
5276 Note:
5278 If registered_name is part of ItemList and the process has no
5279 name registered, a {registered_name, []}, InfoTuple will be
5280 included in the resulting InfoTupleList. This behavior is dif‐
5281 ferent when a single Item =:= registered_name is specified, and
5282 when process_info/1 is used.
5283 Valid InfoTuples with corresponding Items:
5286 {backtrace, Bin}:
5288 Binary Bin contains the same information as the output from
5289 erlang:process_display(Pid, backtrace). Use binary_to_list/1
5290 to obtain the string of characters from the binary.
5291 {binary, BinInfo}:
5293 BinInfo is a list containing miscellaneous information about
5294 binaries on the heap of this process. This InfoTuple can be
5295 changed or removed without prior notice. In the current
5296 implementation BinInfo is a list of tuples. The tuples con‐
5297 tain; BinaryId, BinarySize, BinaryRefcCount.
5298 The message queue is on the heap depending on the process
5300 flag message_queue_data.
5301 {catchlevel, CatchLevel}:
5303 CatchLevel is the number of currently active catches in this
5304 process. This InfoTuple can be changed or removed without
5305 prior notice.
5306 {current_function, {Module, Function, Arity} | undefined}:
5308 Module, Function, Arity is the current function call of the
5309 process. The value undefined can be returned if the process
5310 is currently executing native compiled code.
5311 {current_location, {Module, Function, Arity, Location}}:
5313 Module, Function, Arity is the current function call of the
5314 process. Location is a list of two-tuples describing the
5315 location in the source code.
5316 {current_stacktrace, Stack}:
5318 Returns the current call stack back-trace (stacktrace) of
5319 the process. The stack has the same format as returned by
5320 erlang:get_stacktrace/0. The depth of the stacktrace is
5321 truncated according to the backtrace_depth system flag set‐
5322 ting.
5323 {dictionary, Dictionary}:
5325 Dictionary is the process dictionary.
5326 {error_handler, Module}:
5328 Module is the error handler module used by the process (for
5329 undefined function calls, for example).
5330 {garbage_collection, GCInfo}:
5332 GCInfo is a list containing miscellaneous information about
5333 garbage collection for this process. The content of GCInfo
5334 can be changed without prior notice.
5335 {garbage_collection_info, GCInfo}:
5337 GCInfo is a list containing miscellaneous detailed informa‐
5338 tion about garbage collection for this process. The content
5339 of GCInfo can be changed without prior notice. For details
5340 about the meaning of each item, see gc_minor_start in
5341 erlang:trace/3.
5342 {group_leader, GroupLeader}:
5344 GroupLeader is the group leader for the I/O of the process.
5345 {heap_size, Size}:
5347 Size is the size in words of the youngest heap generation of
5348 the process. This generation includes the process stack.
5349 This information is highly implementation-dependent, and can
5350 change if the implementation changes.
5351 {initial_call, {Module, Function, Arity}}:
5353 Module, Function, Arity is the initial function call with
5354 which the process was spawned.
5355 {links, PidsAndPorts}:
5357 PidsAndPorts is a list of process identifiers and port iden‐
5358 tifiers, with processes or ports to which the process has a
5359 link.
5360 {last_calls, false|Calls}:
5362 The value is false if call saving is not active for the
5363 process (see process_flag/3). If call saving is active, a
5364 list is returned, in which the last element is the most
5365 recent called.
5366 {memory, Size}:
5368 Size is the size in bytes of the process. This includes call
5371 stack, heap, and internal structures.
5372 {message_queue_len, MessageQueueLen}:
5374 MessageQueueLen is the number of messages currently in the
5375 message queue of the process. This is the length of the list
5376 MessageQueue returned as the information item messages (see
5377 below).
5378 {messages, MessageQueue}:
5380 MessageQueue is a list of the messages to the process, which
5381 have not yet been processed.
5382 {min_heap_size, MinHeapSize}:
5384 MinHeapSize is the minimum heap size for the process.
5385 {min_bin_vheap_size, MinBinVHeapSize}:
5387 MinBinVHeapSize is the minimum binary virtual heap size for
5388 the process.
5389 {monitored_by, MonitoredBy}:
5391 A list of identifiers for all the processes, ports and NIF
5392 resources, that are monitoring the process.
5393 {monitors, Monitors}:
5395 A list of monitors (started by monitor/2) that are active
5396 for the process. For a local process monitor or a remote
5397 process monitor by a process identifier, the list consists
5398 of:
5399 {process, Pid}:
5401 Process is monitored by pid.
5402 {process, {RegName, Node}}:
5404 Local or remote process is monitored by name.
5405 {port, PortId}:
5407 Local port is monitored by port id.
5408 {port, {RegName, Node}}:
5410 Local port is monitored by name. Please note, that remote
5411 port monitors are not supported, so Node will always be
5412 the local node name.
5413 {message_queue_data, MQD}:
5415 Returns the current state of process flag mes‐
5416 sage_queue_data. MQD is either off_heap or on_heap. For more
5417 information, see the documentation of process_flag(mes‐
5418 sage_queue_data, MQD).
5419 {priority, Level}:
5421 Level is the current priority level for the process. For
5422 more information on priorities, see process_flag(priority,
5423 Level).
5424 {reductions, Number}:
5426 Number is the number of reductions executed by the process.
5427 {registered_name, Atom}:
5429 Atom is the registered process name. If the process has no
5430 registered name, this tuple is not present in the list.
5431 {sequential_trace_token, [] | SequentialTraceToken}:
5433 SequentialTraceToken is the sequential trace token for the
5434 process. This InfoTuple can be changed or removed without
5435 prior notice.
5436 {stack_size, Size}:
5438 Size is the stack size, in words, of the process.
5439 {status, Status}:
5441 Status is the status of the process and is one of the fol‐
5442 lowing:
5443 * exiting
5445 * garbage_collecting
5447 * waiting (for a message)
5449 * running
5451 * runnable (ready to run, but another process is running)
5453 * suspended (suspended on a "busy" port or by the BIF
5455 erlang:suspend_process/1,2)
5456 {suspending, SuspendeeList}:
5458 SuspendeeList is a list of {Suspendee, ActiveSuspendCount,
5459 OutstandingSuspendCount} tuples. Suspendee is the process
5460 identifier of a process that has been, or is to be, sus‐
5461 pended by the process identified by Pid through the BIF
5462 erlang:suspend_process/2 or erlang:suspend_process/1.
5463 ActiveSuspendCount is the number of times Suspendee has been
5465 suspended by Pid. OutstandingSuspendCount is the number of
5466 not yet completed suspend requests sent by Pid, that is:
5467 * If ActiveSuspendCount =/= 0, Suspendee is currently in the
5469 suspended state.
5470 * If OutstandingSuspendCount =/= 0, option asynchronous of
5472 erlang:suspend_process/2 has been used and the suspendee
5473 has not yet been suspended by Pid.
5474 Notice that ActiveSuspendCount and OutstandingSuspendCount
5476 are not the total suspend count on Suspendee, only the parts
5477 contributed by Pid.
5478 {total_heap_size, Size}:
5480 Size is the total size, in words, of all heap fragments of
5481 the process. This includes the process stack and any unre‐
5482 ceived messages that are considered to be part of the heap.
5483 {trace, InternalTraceFlags}:
5485 InternalTraceFlags is an integer representing the internal
5486 trace flag for this process. This InfoTuple can be changed
5487 or removed without prior notice.
5488 {trap_exit, Boolean}:
5490 Boolean is true if the process is trapping exits, otherwise
5491 false.
5492 Notice that not all implementations support all these Items.
5494 Failures:
5496 badarg:
5498 If Pid is not a local process.
5499 badarg:
5501 If Item is an invalid item.
5502 processes() -> [pid()]
5504 Returns a list of process identifiers corresponding to all the
5506 processes currently existing on the local node.
5507 Notice that an exiting process exists, but is not alive. That
5509 is, is_process_alive/1 returns false for an exiting process, but
5510 its process identifier is part of the result returned from pro‐
5511 cesses/0.
5512 Example:
5514 > processes().
5516 [<0.0.0>,<0.2.0>,<0.4.0>,<0.5.0>,<0.7.0>,<0.8.0>]
5517 purge_module(Module) -> true
5519 Types:
5521 Module = atom()
5523 Removes old code for Module. Before this BIF is used,
5525 check_process_code/2is to be called to check that no processes
5526 execute old code in the module.
5527 Warning:
5529 This BIF is intended for the code server (see code(3)) and is
5530 not to be used elsewhere.
5531 Note:
5534 As from ERTS 8.0 (Erlang/OTP 19), any lingering processes that
5535 still execute the old code is killed by this function. In ear‐
5536 lier versions, such incorrect use could cause much more fatal
5537 failures, like emulator crash.
5538 Failure: badarg if there is no old code for Module.
5541 put(Key, Val) -> term()
5543 Types:
5545 Key = Val = term()
5547 Adds a new Key to the process dictionary, associated with the
5549 value Val, and returns undefined. If Key exists, the old value
5550 is deleted and replaced by Val, and the function returns the old
5551 value. Example:
5552 > X = put(name, walrus), Y = put(name, carpenter),
5554 Z = get(name),
5555 {X, Y, Z}.
5556 {undefined,walrus,carpenter}
5557 Note:
5559 The values stored when put is evaluated within the scope of a
5560 catch are not retracted if a throw is evaluated, or if an error
5561 occurs.
5562 erlang:raise(Class, Reason, Stacktrace) -> no_return()
5565 Types:
5567 Class = error | exit | throw
5569 Reason = term()
5570 Stacktrace = raise_stacktrace()
5571 raise_stacktrace() =
5572 [{module(), atom(), arity() | [term()]} |
5573 {function(), [term()]}] |
5574 [{module(), atom(), arity() | [term()], [{atom(), term()}]} |
5575 {function(), [term()], [{atom(), term()}]}]
5576 Stops the execution of the calling process with an exception of
5578 the specified class, reason, and call stack backtrace (stack‐
5579 trace).
5580 Class is error, exit, or throw. So, if it were not for the
5582 stacktrace, erlang:raise(Class, Reason, Stacktrace) is equiva‐
5583 lent to erlang:Class(Reason).
5584 Reason is any term. Stacktrace is a list as returned from
5586 get_stacktrace(), that is, a list of four-tuples {Module, Func‐
5587 tion, Arity | Args, Location}, where Module and Function are
5588 atoms, and the third element is an integer arity or an argument
5589 list. The stacktrace can also contain {Fun, Args, Location}
5590 tuples, where Fun is a local fun and Args is an argument list.
5591 Element Location at the end is optional. Omitting it is equiva‐
5593 lent to specifying an empty list.
5594 The stacktrace is used as the exception stacktrace for the call‐
5596 ing process; it is truncated to the current maximum stacktrace
5597 depth.
5598 As evaluating this function causes the process to terminate, it
5600 has no return value unless the arguments are invalid, in which
5601 case the function returns the error reason badarg. If you want
5602 to be sure not to return, you can call error(erlang:raise(Class,
5603 Reason, Stacktrace)) and hope to distinguish exceptions later.
5604 erlang:read_timer(TimerRef) -> Result
5606 Types:
5608 TimerRef = reference()
5610 Time = integer() >= 0
5611 Result = Time | false
5612 Reads the state of a timer. The same as calling
5614 erlang:read_timer(TimerRef, []).
5615 erlang:read_timer(TimerRef, Options) -> Result | ok
5617 Types:
5619 TimerRef = reference()
5621 Async = boolean()
5622 Option = {async, Async}
5623 Options = [Option]
5624 Time = integer() >= 0
5625 Result = Time | false
5626 Reads the state of a timer that has been created by either
5628 erlang:start_timer or erlang:send_after. TimerRef identifies the
5629 timer, and was returned by the BIF that created the timer.
5630 Options:
5632 {async, Async}:
5634 Asynchronous request for state information. Async defaults
5635 to false, which causes the operation to be performed syn‐
5636 chronously. In this case, the Result is returned by
5637 erlang:read_timer. When Async is true, erlang:read_timer
5638 sends an asynchronous request for the state information to
5639 the timer service that manages the timer, and then returns
5640 ok. A message on the format {read_timer, TimerRef, Result}
5641 is sent to the caller of erlang:read_timer when the opera‐
5642 tion has been processed.
5643 More Options can be added in the future.
5645 If Result is an integer, it represents the time in milliseconds
5647 left until the timer expires.
5648 If Result is false, a timer corresponding to TimerRef could not
5650 be found. This because the timer had expired, or been canceled,
5651 or because TimerRef never has corresponded to a timer. Even if
5652 the timer has expired, it does not tell you whether or not the
5653 time-out message has arrived at its destination yet.
5654 Note:
5656 The timer service that manages the timer can be co-located with
5657 another scheduler than the scheduler that the calling process is
5658 executing on. If so, communication with the timer service takes
5659 much longer time than if it is located locally. If the calling
5660 process is in a critical path, and can do other things while
5661 waiting for the result of this operation, you want to use option
5662 {async, true}. If using option {async, false}, the calling
5663 process is blocked until the operation has been performed.
5664 See also erlang:send_after/4, erlang:start_timer/4, and
5667 erlang:cancel_timer/2.
5668 ref_to_list(Ref) -> string()
5670 Types:
5672 Ref = reference()
5674 Returns a string corresponding to the text representation of
5676 Ref.
5677 Warning:
5679 This BIF is intended for debugging and is not to be used in
5680 application programs.
5681 register(RegName, PidOrPort) -> true
5684 Types:
5686 RegName = atom()
5688 PidOrPort = port() | pid()
5689 Associates the name RegName with a process identifier (pid) or a
5691 port identifier. RegName, which must be an atom, can be used
5692 instead of the pid or port identifier in send operator (RegName
5693 ! Message). Example:
5694 > register(db, Pid).
5696 true
5697 Failures:
5699 badarg:
5701 If PidOrPort is not an existing local process or port.
5702 badarg:
5704 If RegName is already in use.
5705 badarg:
5707 If the process or port is already registered (already has a
5708 name).
5709 badarg:
5711 If RegName is the atom undefined.
5712 registered() -> [RegName]
5714 Types:
5716 RegName = atom()
5718 Returns a list of names that have been registered using regis‐
5720 ter/2, for example:
5721 > registered().
5723 [code_server, file_server, init, user, my_db]
5724 erlang:resume_process(Suspendee) -> true
5726 Types:
5728 Suspendee = pid()
5730 Decreases the suspend count on the process identified by Sus‐
5732 pendee. Suspendee is previously to have been suspended through
5733 erlang:suspend_process/2 or erlang:suspend_process/1 by the
5734 process calling erlang:resume_process(Suspendee). When the sus‐
5735 pend count on Suspendee reaches zero, Suspendee is resumed, that
5736 is, its state is changed from suspended into the state it had
5737 before it was suspended.
5738 Warning:
5740 This BIF is intended for debugging only.
5741 Failures:
5744 badarg:
5746 If Suspendee is not a process identifier.
5747 badarg:
5749 If the process calling erlang:resume_process/1 had not pre‐
5750 viously increased the suspend count on the process identi‐
5751 fied by Suspendee.
5752 badarg:
5754 If the process identified by Suspendee is not alive.
5755 round(Number) -> integer()
5757 Types:
5759 Number = number()
5761 Returns an integer by rounding Number, for example:
5763 round(5.5).
5765 6
5766 Allowed in guard tests.
5768 self() -> pid()
5770 Returns the process identifier of the calling process, for exam‐
5772 ple:
5773 > self().
5775 <0.26.0>
5776 Allowed in guard tests.
5778 erlang:send(Dest, Msg) -> Msg
5780 Types:
5782 Dest = dst()
5784 Msg = term()
5785 dst() =
5786 pid() |
5787 port() |
5788 (RegName :: atom()) |
5789 {RegName :: atom(), Node :: node()}
5790 Sends a message and returns Msg. This is the same as using the
5792 send operator: Dest ! Msg.
5793 Dest can be a remote or local process identifier, a (local)
5795 port, a locally registered name, or a tuple {RegName, Node} for
5796 a registered name at another node.
5797 The function fails with a badarg run-time error if Dest is an
5799 atom name, but this name is not registered. This is the only
5800 case when send fails for an unreachable destination Dest (of
5801 correct type).
5802 erlang:send(Dest, Msg, Options) -> Res
5804 Types:
5806 Dest = dst()
5808 Msg = term()
5809 Options = [nosuspend | noconnect]
5810 Res = ok | nosuspend | noconnect
5811 dst() =
5812 pid() |
5813 port() |
5814 (RegName :: atom()) |
5815 {RegName :: atom(), Node :: node()}
5816 Either sends a message and returns ok, or does not send the mes‐
5818 sage but returns something else (see below). Otherwise the same
5819 as erlang:send/2. For more detailed explanation and warnings,
5820 see erlang:send_nosuspend/2,3.
5821 Options:
5823 nosuspend:
5825 If the sender would have to be suspended to do the send,
5826 nosuspend is returned instead.
5827 noconnect:
5829 If the destination node would have to be auto-connected to
5830 do the send, noconnect is returned instead.
5831 Warning:
5833 As with erlang:send_nosuspend/2,3: use with extreme care.
5834 erlang:send_after(Time, Dest, Msg) -> TimerRef
5837 Types:
5839 Time = integer() >= 0
5841 Dest = pid() | atom()
5842 Msg = term()
5843 TimerRef = reference()
5844 Starts a timer. The same as calling erlang:send_after(Time,
5846 Dest, Msg, []).
5847 erlang:send_after(Time, Dest, Msg, Options) -> TimerRef
5849 Types:
5851 Time = integer()
5853 Dest = pid() | atom()
5854 Msg = term()
5855 Options = [Option]
5856 Abs = boolean()
5857 Option = {abs, Abs}
5858 TimerRef = reference()
5859 Starts a timer. When the timer expires, the message Msg is sent
5861 to the process identified by Dest. Apart from the format of the
5862 time-out message, this function works exactly as
5863 erlang:start_timer/4.
5864 erlang:send_nosuspend(Dest, Msg) -> boolean()
5866 Types:
5868 Dest = dst()
5870 Msg = term()
5871 dst() =
5872 pid() |
5873 port() |
5874 (RegName :: atom()) |
5875 {RegName :: atom(), Node :: node()}
5876 The same as erlang:send(Dest, Msg, [nosuspend]), but returns
5878 true if the message was sent and false if the message was not
5879 sent because the sender would have had to be suspended.
5880 This function is intended for send operations to an unreliable
5882 remote node without ever blocking the sending (Erlang) process.
5883 If the connection to the remote node (usually not a real Erlang
5884 node, but a node written in C or Java) is overloaded, this func‐
5885 tion does not send the message and returns false.
5886 The same occurs if Dest refers to a local port that is busy. For
5888 all other destinations (allowed for the ordinary send operator
5889 '!'), this function sends the message and returns true.
5890 This function is only to be used in rare circumstances where a
5892 process communicates with Erlang nodes that can disappear with‐
5893 out any trace, causing the TCP buffers and the drivers queue to
5894 be over-full before the node is shut down (because of tick time-
5895 outs) by net_kernel. The normal reaction to take when this
5896 occurs is some kind of premature shutdown of the other node.
5897 Notice that ignoring the return value from this function would
5899 result in an unreliable message passing, which is contradictory
5900 to the Erlang programming model. The message is not sent if this
5901 function returns false.
5902 In many systems, transient states of overloaded queues are nor‐
5904 mal. Although this function returns false does not mean that the
5905 other node is guaranteed to be non-responsive, it could be a
5906 temporary overload. Also, a return value of true does only mean
5907 that the message can be sent on the (TCP) channel without block‐
5908 ing; the message is not guaranteed to arrive at the remote node.
5909 For a disconnected non-responsive node, the return value is true
5910 (mimics the behavior of operator !). The expected behavior and
5911 the actions to take when the function returns false are applica‐
5912 tion- and hardware-specific.
5913 Warning:
5915 Use with extreme care.
5916 erlang:send_nosuspend(Dest, Msg, Options) -> boolean()
5919 Types:
5921 Dest = dst()
5923 Msg = term()
5924 Options = [noconnect]
5925 dst() =
5926 pid() |
5927 port() |
5928 (RegName :: atom()) |
5929 {RegName :: atom(), Node :: node()}
5930 The same as erlang:send(Dest, Msg, [nosuspend | Options]), but
5932 with a Boolean return value.
5933 This function behaves like erlang:send_nosuspend/2, but takes a
5935 third parameter, a list of options. The only option is nocon‐
5936 nect, which makes the function return false if the remote node
5937 is not currently reachable by the local node. The normal behav‐
5938 ior is to try to connect to the node, which can stall the
5939 process during a short period. The use of option noconnect makes
5940 it possible to be sure not to get the slightest delay when send‐
5941 ing to a remote process. This is especially useful when communi‐
5942 cating with nodes that expect to always be the connecting part
5943 (that is, nodes written in C or Java).
5944 Whenever the function returns false (either when a suspend would
5946 occur or when noconnect was specified and the node was not
5947 already connected), the message is guaranteed not to have been
5948 sent.
5949 Warning:
5951 Use with extreme care.
5952 erlang:set_cookie(Node, Cookie) -> true
5955 Types:
5957 Node = node()
5959 Cookie = atom()
5960 Sets the magic cookie of Node to the atom Cookie. If Node is the
5962 local node, the function also sets the cookie of all other
5963 unknown nodes to Cookie (see section Distributed Erlang in the
5964 Erlang Reference Manual in System Documentation).
5965 Failure: function_clause if the local node is not alive.
5967 setelement(Index, Tuple1, Value) -> Tuple2
5969 Types:
5971 Index = integer() >= 1
5973 1..tuple_size(Tuple1
5974 Tuple1 = Tuple2 = tuple()
5975 Value = term()
5976 Returns a tuple that is a copy of argument Tuple1 with the ele‐
5978 ment specified by integer argument Index (the first element is
5979 the element with index 1) replaced by argument Value, for exam‐
5980 ple:
5981 > setelement(2, {10, green, bottles}, red).
5983 {10,red,bottles}
5984 size(Item) -> integer() >= 0
5986 Types:
5988 Item = tuple() | binary()
5990 Returns the number of elements in a tuple or the number of bytes
5992 in a binary or bitstring, for example:
5993 > size({morni, mulle, bwange}).
5995 3
5996 > size(<<11, 22, 33>>).
5997 3
5998 For bitstrings, the number of whole bytes is returned. That is,
6000 if the number of bits in the bitstring is not divisible by 8,
6001 the resulting number of bytes is rounded down.
6002 Allowed in guard tests.
6004 See also tuple_size/1, byte_size/1, and bit_size/1.
6006 spawn(Fun) -> pid()
6008 Types:
6010 Fun = function()
6012 Returns the process identifier of a new process started by the
6014 application of Fun to the empty list []. Otherwise works like
6015 spawn/3.
6016 spawn(Node, Fun) -> pid()
6018 Types:
6020 Node = node()
6022 Fun = function()
6023 Returns the process identifier of a new process started by the
6025 application of Fun to the empty list [] on Node. If Node does
6026 not exist, a useless pid is returned. Otherwise works like
6027 spawn/3.
6028 spawn(Module, Function, Args) -> pid()
6030 Types:
6032 Module = module()
6034 Function = atom()
6035 Args = [term()]
6036 Returns the process identifier of a new process started by the
6038 application of Module:Function to Args.
6039 error_handler:undefined_function(Module, Function, Args) is
6041 evaluated by the new process if Module:Function/Arity does not
6042 exist (where Arity is the length of Args). The error handler can
6043 be redefined (see process_flag/2). If error_handler is unde‐
6044 fined, or the user has redefined the default error_handler and
6045 its replacement is undefined, a failure with reason undef
6046 occurs.
6047 Example:
6049 > spawn(speed, regulator, [high_speed, thin_cut]).
6051 <0.13.1>
6052 spawn(Node, Module, Function, Args) -> pid()
6054 Types:
6056 Node = node()
6058 Module = module()
6059 Function = atom()
6060 Args = [term()]
6061 Returns the process identifier (pid) of a new process started by
6063 the application of Module:Function to Args on Node. If Node does
6064 not exist, a useless pid is returned. Otherwise works like
6065 spawn/3.
6066 spawn_link(Fun) -> pid()
6068 Types:
6070 Fun = function()
6072 Returns the process identifier of a new process started by the
6074 application of Fun to the empty list []. A link is created
6075 between the calling process and the new process, atomically.
6076 Otherwise works like spawn/3.
6077 spawn_link(Node, Fun) -> pid()
6079 Types:
6081 Node = node()
6083 Fun = function()
6084 Returns the process identifier (pid) of a new process started by
6086 the application of Fun to the empty list [] on Node. A link is
6087 created between the calling process and the new process, atomi‐
6088 cally. If Node does not exist, a useless pid is returned and an
6089 exit signal with reason noconnection is sent to the calling
6090 process. Otherwise works like spawn/3.
6091 spawn_link(Module, Function, Args) -> pid()
6093 Types:
6095 Module = module()
6097 Function = atom()
6098 Args = [term()]
6099 Returns the process identifier of a new process started by the
6101 application of Module:Function to Args. A link is created
6102 between the calling process and the new process, atomically.
6103 Otherwise works like spawn/3.
6104 spawn_link(Node, Module, Function, Args) -> pid()
6106 Types:
6108 Node = node()
6110 Module = module()
6111 Function = atom()
6112 Args = [term()]
6113 Returns the process identifier (pid) of a new process started by
6115 the application of Module:Function to Args on Node. A link is
6116 created between the calling process and the new process, atomi‐
6117 cally. If Node does not exist, a useless pid is returned and an
6118 exit signal with reason noconnection is sent to the calling
6119 process. Otherwise works like spawn/3.
6120 spawn_monitor(Fun) -> {pid(), reference()}
6122 Types:
6124 Fun = function()
6126 Returns the process identifier of a new process, started by the
6128 application of Fun to the empty list [], and a reference for a
6129 monitor created to the new process. Otherwise works like
6130 spawn/3.
6131 spawn_monitor(Module, Function, Args) -> {pid(), reference()}
6133 Types:
6135 Module = module()
6137 Function = atom()
6138 Args = [term()]
6139 A new process is started by the application of Module:Function
6141 to Args. The process is monitored at the same time. Returns the
6142 process identifier and a reference for the monitor. Otherwise
6143 works like spawn/3.
6144 spawn_opt(Fun, Options) -> pid() | {pid(), reference()}
6146 Types:
6148 Fun = function()
6150 Options = [spawn_opt_option()]
6151 priority_level() = low | normal | high | max
6152 max_heap_size() =
6153 integer() >= 0 |
6154 #{size => integer() >= 0,
6155 kill => boolean(),
6156 error_logger => boolean()}
6157 message_queue_data() = off_heap | on_heap
6158 spawn_opt_option() =
6159 link | monitor |
6160 {priority, Level :: priority_level()} |
6161 {fullsweep_after, Number :: integer() >= 0} |
6162 {min_heap_size, Size :: integer() >= 0} |
6163 {min_bin_vheap_size, VSize :: integer() >= 0} |
6164 {max_heap_size, Size :: max_heap_size()} |
6165 {message_queue_data, MQD :: message_queue_data()}
6166 Returns the process identifier (pid) of a new process started by
6168 the application of Fun to the empty list []. Otherwise works
6169 like spawn_opt/4.
6170 If option monitor is specified, the newly created process is
6172 monitored, and both the pid and reference for the monitor are
6173 returned.
6174 spawn_opt(Node, Fun, Options) -> pid() | {pid(), reference()}
6176 Types:
6178 Node = node()
6180 Fun = function()
6181 Options = [spawn_opt_option()]
6182 priority_level() = low | normal | high | max
6183 max_heap_size() =
6184 integer() >= 0 |
6185 #{size => integer() >= 0,
6186 kill => boolean(),
6187 error_logger => boolean()}
6188 message_queue_data() = off_heap | on_heap
6189 spawn_opt_option() =
6190 link | monitor |
6191 {priority, Level :: priority_level()} |
6192 {fullsweep_after, Number :: integer() >= 0} |
6193 {min_heap_size, Size :: integer() >= 0} |
6194 {min_bin_vheap_size, VSize :: integer() >= 0} |
6195 {max_heap_size, Size :: max_heap_size()} |
6196 {message_queue_data, MQD :: message_queue_data()}
6197 Returns the process identifier (pid) of a new process started by
6199 the application of Fun to the empty list [] on Node. If Node
6200 does not exist, a useless pid is returned. Otherwise works like
6201 spawn_opt/4.
6202 spawn_opt(Module, Function, Args, Options) ->
6204 pid() | {pid(), reference()}
6205 Types:
6207 Module = module()
6209 Function = atom()
6210 Args = [term()]
6211 Options = [spawn_opt_option()]
6212 priority_level() = low | normal | high | max
6213 max_heap_size() =
6214 integer() >= 0 |
6215 #{size => integer() >= 0,
6216 kill => boolean(),
6217 error_logger => boolean()}
6218 message_queue_data() = off_heap | on_heap
6219 spawn_opt_option() =
6220 link | monitor |
6221 {priority, Level :: priority_level()} |
6222 {fullsweep_after, Number :: integer() >= 0} |
6223 {min_heap_size, Size :: integer() >= 0} |
6224 {min_bin_vheap_size, VSize :: integer() >= 0} |
6225 {max_heap_size, Size :: max_heap_size()} |
6226 {message_queue_data, MQD :: message_queue_data()}
6227 Works as spawn/3, except that an extra option list is specified
6229 when creating the process.
6230 If option monitor is specified, the newly created process is
6232 monitored, and both the pid and reference for the monitor are
6233 returned.
6234 Options:
6236 link:
6238 Sets a link to the parent process (like spawn_link/3 does).
6239 monitor:
6241 Monitors the new process (like monitor/2 does).
6242 {priority, Level}:
6244 Sets the priority of the new process. Equivalent to execut‐
6245 ing process_flag(priority, Level) in the start function of
6246 the new process, except that the priority is set before the
6247 process is selected for execution for the first time. For
6248 more information on priorities, see process_flag(priority,
6249 Level).
6250 {fullsweep_after, Number}:
6252 Useful only for performance tuning. Do not use this option
6253 unless you know that there is problem with execution times
6254 or memory consumption, and ensure that the option improves
6255 matters.
6256 The Erlang runtime system uses a generational garbage col‐
6258 lection scheme, using an "old heap" for data that has sur‐
6259 vived at least one garbage collection. When there is no more
6260 room on the old heap, a fullsweep garbage collection is
6261 done.
6262 Option fullsweep_after makes it possible to specify the max‐
6264 imum number of generational collections before forcing a
6265 fullsweep, even if there is room on the old heap. Setting
6266 the number to zero disables the general collection algo‐
6267 rithm, that is, all live data is copied at every garbage
6268 collection.
6269 A few cases when it can be useful to change fullsweep_after:
6271 * If binaries that are no longer used are to be thrown away
6273 as soon as possible. (Set Number to zero.)
6274 * A process that mostly have short-lived data is fullsweeped
6276 seldom or never, that is, the old heap contains mostly
6277 garbage. To ensure a fullsweep occasionally, set Number to
6278 a suitable value, such as 10 or 20.
6279 * In embedded systems with a limited amount of RAM and no
6281 virtual memory, you might want to preserve memory by set‐
6282 ting Number to zero. (The value can be set globally, see
6283 erlang:system_flag/2.)
6284 {min_heap_size, Size}:
6286 Useful only for performance tuning. Do not use this option
6287 unless you know that there is problem with execution times
6288 or memory consumption, and ensure that the option improves
6289 matters.
6290 Gives a minimum heap size, in words. Setting this value
6292 higher than the system default can speed up some processes
6293 because less garbage collection is done. However, setting a
6294 too high value can waste memory and slow down the system
6295 because of worse data locality. Therefore, use this option
6296 only for fine-tuning an application and to measure the exe‐
6297 cution time with various Size values.
6298 {min_bin_vheap_size, VSize}:
6300 Useful only for performance tuning. Do not use this option
6301 unless you know that there is problem with execution times
6302 or memory consumption, and ensure that the option improves
6303 matters.
6304 Gives a minimum binary virtual heap size, in words. Setting
6306 this value higher than the system default can speed up some
6307 processes because less garbage collection is done. However,
6308 setting a too high value can waste memory. Therefore, use
6309 this option only for fine-tuning an application and to mea‐
6310 sure the execution time with various VSize values.
6311 {max_heap_size, Size}:
6313 Sets the max_heap_size process flag. The default
6314 max_heap_size is determined by command-line argument +hmax
6315 in erl(1). For more information, see the documentation of
6316 process_flag(max_heap_size, Size).
6317 {message_queue_data, MQD}:
6319 Sets the state of the message_queue_data process flag. MQD
6320 is to be either off_heap or on_heap. The default mes‐
6321 sage_queue_data process flag is determined by command-line
6322 argument +hmqd in erl(1). For more information, see the doc‐
6323 umentation of process_flag(message_queue_data, MQD).
6324 spawn_opt(Node, Module, Function, Args, Options) ->
6326 pid() | {pid(), reference()}
6327 Types:
6329 Node = node()
6331 Module = module()
6332 Function = atom()
6333 Args = [term()]
6334 Options = [spawn_opt_option()]
6335 priority_level() = low | normal | high | max
6336 max_heap_size() =
6337 integer() >= 0 |
6338 #{size => integer() >= 0,
6339 kill => boolean(),
6340 error_logger => boolean()}
6341 message_queue_data() = off_heap | on_heap
6342 spawn_opt_option() =
6343 link | monitor |
6344 {priority, Level :: priority_level()} |
6345 {fullsweep_after, Number :: integer() >= 0} |
6346 {min_heap_size, Size :: integer() >= 0} |
6347 {min_bin_vheap_size, VSize :: integer() >= 0} |
6348 {max_heap_size, Size :: max_heap_size()} |
6349 {message_queue_data, MQD :: message_queue_data()}
6350 Returns the process identifier (pid) of a new process started by
6352 the application of Module:Function to Args on Node. If Node does
6353 not exist, a useless pid is returned. Otherwise works like
6354 spawn_opt/4.
6355 Note:
6357 Option monitor is not supported by spawn_opt/5.
6358 split_binary(Bin, Pos) -> {binary(), binary()}
6361 Types:
6363 Bin = binary()
6365 Pos = integer() >= 0
6366 0..byte_size(Bin)
6367 Returns a tuple containing the binaries that are the result of
6369 splitting Bin into two parts at position Pos. This is not a
6370 destructive operation. After the operation, there are three
6371 binaries altogether. Example:
6372 > B = list_to_binary("0123456789").
6374 <<"0123456789">>
6375 > byte_size(B).
6376 10
6377 > {B1, B2} = split_binary(B,3).
6378 {<<"012">>,<<"3456789">>}
6379 > byte_size(B1).
6380 3
6381 > byte_size(B2).
6382 7
6383 erlang:start_timer(Time, Dest, Msg) -> TimerRef
6385 Types:
6387 Time = integer() >= 0
6389 Dest = pid() | atom()
6390 Msg = term()
6391 TimerRef = reference()
6392 Starts a timer. The same as calling erlang:start_timer(Time,
6394 Dest, Msg, []).
6395 erlang:start_timer(Time, Dest, Msg, Options) -> TimerRef
6397 Types:
6399 Time = integer()
6401 Dest = pid() | atom()
6402 Msg = term()
6403 Options = [Option]
6404 Abs = boolean()
6405 Option = {abs, Abs}
6406 TimerRef = reference()
6407 Starts a timer. When the timer expires, the message {timeout,
6409 TimerRef, Msg} is sent to the process identified by Dest.
6410 Options:
6412 {abs, false}:
6414 This is the default. It means the Time value is interpreted
6415 as a time in milliseconds relative current Erlang monotonic
6416 time.
6417 {abs, true}:
6419 Absolute Time value. The Time value is interpreted as an
6420 absolute Erlang monotonic time in milliseconds.
6421 More Options can be added in the future.
6423 The absolute point in time, the timer is set to expire on, must
6425 be in the interval [erlang:system_info(start_time), erlang:sys‐
6426 tem_info(end_time)]. If a relative time is specified, the Time
6427 value is not allowed to be negative.
6428 If Dest is a pid(), it must be a pid() of a process created on
6430 the current runtime system instance. This process has either
6431 terminated or not. If Dest is an atom(), it is interpreted as
6432 the name of a locally registered process. The process referred
6433 to by the name is looked up at the time of timer expiration. No
6434 error is returned if the name does not refer to a process.
6435 If Dest is a pid(), the timer is automatically canceled if the
6437 process referred to by the pid() is not alive, or if the process
6438 exits. This feature was introduced in ERTS 5.4.11. Notice that
6439 timers are not automatically canceled when Dest is an atom().
6440 See also erlang:send_after/4, erlang:cancel_timer/2, and
6442 erlang:read_timer/2.
6443 Failure: badarg if the arguments do not satisfy the requirements
6445 specified here.
6446 statistics(Item :: active_tasks) -> [ActiveTasks]
6448 Types:
6450 ActiveTasks = integer() >= 0
6452 Returns the same as statistics(active_tasks_all) with the excep‐
6454 tion that no information about the dirty IO run queue and its
6455 associated schedulers is part of the result. That is, only tasks
6456 that are expected to be CPU bound are part of the result.
6457 statistics(Item :: active_tasks_all) -> [ActiveTasks]
6459 Types:
6461 ActiveTasks = integer() >= 0
6463 Returns a list where each element represents the amount of
6465 active processes and ports on each run queue and its associated
6466 schedulers. That is, the number of processes and ports that are
6467 ready to run, or are currently running. Values for normal run
6468 queues and their associated schedulers are located first in the
6469 resulting list. The first element corresponds to scheduler num‐
6470 ber 1 and so on. If support for dirty schedulers exist, an ele‐
6471 ment with the value for the dirty CPU run queue and its associ‐
6472 ated dirty CPU schedulers follow and then as last element the
6473 value for the the dirty IO run queue and its associated dirty IO
6474 schedulers follow. The information is not gathered atomically.
6475 That is, the result is not necessarily a consistent snapshot of
6476 the state, but instead quite efficiently gathered.
6477 Note:
6479 Each normal scheduler has one run queue that it manages. If
6480 dirty schedulers schedulers are supported, all dirty CPU sched‐
6481 ulers share one run queue, and all dirty IO schedulers share one
6482 run queue. That is, we have multiple normal run queues, one
6483 dirty CPU run queue and one dirty IO run queue. Work can not
6484 migrate between the different types of run queues. Only work in
6485 normal run queues can migrate to other normal run queues. This
6486 has to be taken into account when evaluating the result.
6487 See also statistics(total_active_tasks), statis‐
6490 tics(run_queue_lengths), statistics(run_queue_lengths_all), sta‐
6491 tistics(total_run_queue_lengths), and statis‐
6492 tics(total_run_queue_lengths_all).
6493 statistics(Item :: context_switches) -> {ContextSwitches, 0}
6495 Types:
6497 ContextSwitches = integer() >= 0
6499 Returns the total number of context switches since the system
6501 started.
6502 statistics(Item :: exact_reductions) ->
6504 {Total_Exact_Reductions,
6505 Exact_Reductions_Since_Last_Call}
6506 Types:
6508 Total_Exact_Reductions = Exact_Reductions_Since_Last_Call =
6510 integer() >= 0
6511 Returns the number of exact reductions.
6513 Note:
6515 statistics(exact_reductions) is a more expensive operation than
6516 statistics(reductions).
6517 statistics(Item :: garbage_collection) ->
6520 {Number_of_GCs, Words_Reclaimed, 0}
6521 Types:
6523 Number_of_GCs = Words_Reclaimed = integer() >= 0
6525 Returns information about garbage collection, for example:
6527 > statistics(garbage_collection).
6529 {85,23961,0}
6530 This information can be invalid for some implementations.
6532 statistics(Item :: io) -> {{input, Input}, {output, Output}}
6534 Types:
6536 Input = Output = integer() >= 0
6538 Returns Input, which is the total number of bytes received
6540 through ports, and Output, which is the total number of bytes
6541 output to ports.
6542 statistics(Item :: microstate_accounting) ->
6544 [MSAcc_Thread] | undefined
6545 Types:
6547 MSAcc_Thread =
6549 #{type := MSAcc_Thread_Type,
6550 id := MSAcc_Thread_Id,
6551 counters := MSAcc_Counters}
6552 MSAcc_Thread_Type =
6553 async | aux | dirty_io_scheduler | dirty_cpu_scheduler |
6554 poll | scheduler
6555 MSAcc_Thread_Id = integer() >= 0
6556 MSAcc_Counters = #{MSAcc_Thread_State => integer() >= 0}
6557 MSAcc_Thread_State =
6558 alloc | aux | bif | busy_wait | check_io | emulator | ets
6559 |
6560 gc | gc_fullsweep | nif | other | port | send | sleep |
6561 timers
6562 Microstate accounting can be used to measure how much time the
6564 Erlang runtime system spends doing various tasks. It is designed
6565 to be as lightweight as possible, but some overhead exists when
6566 this is enabled. Microstate accounting is meant to be a profil‐
6567 ing tool to help finding performance bottlenecks. To
6568 start/stop/reset microstate accounting, use system flag
6569 microstate_accounting.
6570 statistics(microstate_accounting) returns a list of maps repre‐
6572 senting some of the OS threads within ERTS. Each map contains
6573 type and id fields that can be used to identify what thread it
6574 is, and also a counters field that contains data about how much
6575 time has been spent in the various states.
6576 Example:
6578 > erlang:statistics(microstate_accounting).
6580 [#{counters => #{aux => 1899182914,
6581 check_io => 2605863602,
6582 emulator => 45731880463,
6583 gc => 1512206910,
6584 other => 5421338456,
6585 port => 221631,
6586 sleep => 5150294100},
6587 id => 1,
6588 type => scheduler}|...]
6589 The time unit is the same as returned by os:perf_counter/0. So,
6591 to convert it to milliseconds, you can do something like this:
6592 lists:map(
6594 fun(#{ counters := Cnt } = M) ->
6595 MsCnt = maps:map(fun(_K, PerfCount) ->
6596 erlang:convert_time_unit(PerfCount, perf_counter, 1000)
6597 end, Cnt),
6598 M#{ counters := MsCnt }
6599 end, erlang:statistics(microstate_accounting)).
6600 Notice that these values are not guaranteed to be the exact time
6602 spent in each state. This is because of various optimisation
6603 done to keep the overhead as small as possible.
6604 MSAcc_Thread_Types:
6606 scheduler:
6608 The main execution threads that do most of the work. See erl
6609 +S for more details.
6610 dirty_cpu_scheduler:
6612 The threads for long running cpu intensive work. See erl
6613 +SDcpu for more details.
6614 dirty_io_scheduler:
6616 The threads for long running I/O work. See erl +SDio for
6617 more details.
6618 async:
6620 Async threads are used by various linked-in drivers (mainly
6621 the file drivers) do offload non-CPU intensive work. See erl
6622 +A for more details.
6623 aux:
6625 Takes care of any work that is not specifically assigned to
6626 a scheduler.
6627 poll:
6629 Does the IO polling for the emulator. See erl +IOt for more
6630 details.
6631 The following MSAcc_Thread_States are available. All states are
6633 exclusive, meaning that a thread cannot be in two states at
6634 once. So, if you add the numbers of all counters in a thread,
6635 you get the total runtime for that thread.
6636 aux:
6638 Time spent handling auxiliary jobs.
6639 check_io:
6641 Time spent checking for new I/O events.
6642 emulator:
6644 Time spent executing Erlang processes.
6645 gc:
6647 Time spent doing garbage collection. When extra states are
6648 enabled this is the time spent doing non-fullsweep garbage
6649 collections.
6650 other:
6652 Time spent doing unaccounted things.
6653 port:
6655 Time spent executing ports.
6656 sleep:
6658 Time spent sleeping.
6659 More fine-grained MSAcc_Thread_States can be added through con‐
6661 figure (such as ./configure --with-microstate-accounting=extra).
6662 Enabling these states causes performance degradation when
6663 microstate accounting is turned off and increases the overhead
6664 when it is turned on.
6665 alloc:
6667 Time spent managing memory. Without extra states this time
6668 is spread out over all other states.
6669 bif:
6671 Time spent in BIFs. Without extra states this time is part
6672 of the emulator state.
6673 busy_wait:
6675 Time spent busy waiting. This is also the state where a
6676 scheduler no longer reports that it is active when using
6677 statistics(scheduler_wall_time). So, if you add all other
6678 states but this and sleep, and then divide that by all time
6679 in the thread, you should get something very similar to the
6680 scheduler_wall_time fraction. Without extra states this time
6681 is part of the other state.
6682 ets:
6684 Time spent executing ETS BIFs. Without extra states this
6685 time is part of the emulator state.
6686 gc_full:
6688 Time spent doing fullsweep garbage collection. Without extra
6689 states this time is part of the gc state.
6690 nif:
6692 Time spent in NIFs. Without extra states this time is part
6693 of the emulator state.
6694 send:
6696 Time spent sending messages (processes only). Without extra
6697 states this time is part of the emulator state.
6698 timers:
6700 Time spent managing timers. Without extra states this time
6701 is part of the other state.
6702 The utility module msacc(3) can be used to more easily analyse
6704 these statistics.
6705 Returns undefined if system flag microstate_accounting is turned
6707 off.
6708 The list of thread information is unsorted and can appear in
6710 different order between calls.
6711 Note:
6713 The threads and states are subject to change without any prior
6714 notice.
6715 statistics(Item :: reductions) ->
6718 {Total_Reductions, Reductions_Since_Last_Call}
6719 Types:
6721 Total_Reductions = Reductions_Since_Last_Call = integer() >=
6723 0
6724 Returns information about reductions, for example:
6726 > statistics(reductions).
6728 {2046,11}
6729 Note:
6731 As from ERTS 5.5 (Erlang/OTP R11B), this value does not include
6732 reductions performed in current time slices of currently sched‐
6733 uled processes. If an exact value is wanted, use statis‐
6734 tics(exact_reductions).
6735 statistics(Item :: run_queue) -> integer() >= 0
6738 Returns the total length of all normal run-queues. That is, the
6740 number of processes and ports that are ready to run on all
6741 available normal run-queues. Dirty run queues are not part of
6742 the result. The information is gathered atomically. That is, the
6743 result is a consistent snapshot of the state, but this operation
6744 is much more expensive compared to statis‐
6745 tics(total_run_queue_lengths), especially when a large amount of
6746 schedulers is used.
6747 statistics(Item :: run_queue_lengths) -> [RunQueueLength]
6749 Types:
6751 RunQueueLength = integer() >= 0
6753 Returns the same as statistics(run_queue_lengths_all) with the
6755 exception that no information about the dirty IO run queue is
6756 part of the result. That is, only run queues with work that is
6757 expected to be CPU bound is part of the result.
6758 statistics(Item :: run_queue_lengths_all) -> [RunQueueLength]
6760 Types:
6762 RunQueueLength = integer() >= 0
6764 Returns a list where each element represents the amount of pro‐
6766 cesses and ports ready to run for each run queue. Values for
6767 normal run queues are located first in the resulting list. The
6768 first element corresponds to the normal run queue of scheduler
6769 number 1 and so on. If support for dirty schedulers exist, val‐
6770 ues for the dirty CPU run queue and the dirty IO run queue fol‐
6771 low (in that order) at the end. The information is not gathered
6772 atomically. That is, the result is not necessarily a consistent
6773 snapshot of the state, but instead quite efficiently gathered.
6774 Note:
6776 Each normal scheduler has one run queue that it manages. If
6777 dirty schedulers schedulers are supported, all dirty CPU sched‐
6778 ulers share one run queue, and all dirty IO schedulers share one
6779 run queue. That is, we have multiple normal run queues, one
6780 dirty CPU run queue and one dirty IO run queue. Work can not
6781 migrate between the different types of run queues. Only work in
6782 normal run queues can migrate to other normal run queues. This
6783 has to be taken into account when evaluating the result.
6784 See also statistics(run_queue_lengths), statis‐
6787 tics(total_run_queue_lengths_all), statis‐
6788 tics(total_run_queue_lengths), statistics(active_tasks), statis‐
6789 tics(active_tasks_all), and statistics(total_active_tasks), sta‐
6790 tistics(total_active_tasks_all).
6791 statistics(Item :: runtime) ->
6793 {Total_Run_Time, Time_Since_Last_Call}
6794 Types:
6796 Total_Run_Time = Time_Since_Last_Call = integer() >= 0
6798 Returns information about runtime, in milliseconds.
6800 This is the sum of the runtime for all threads in the Erlang
6802 runtime system and can therefore be greater than the wall clock
6803 time.
6804 Warning:
6806 This value might wrap due to limitations in the underlying func‐
6807 tionality provided by the operating system that is used.
6808 Example:
6811 > statistics(runtime).
6813 {1690,1620}
6814 statistics(Item :: scheduler_wall_time) ->
6816 [{SchedulerId, ActiveTime, TotalTime}] | undefined
6817 Types:
6819 SchedulerId = integer() >= 1
6821 ActiveTime = TotalTime = integer() >= 0
6822 Returns a list of tuples with {SchedulerId, ActiveTime, Total‐
6824 Time}, where SchedulerId is an integer ID of the scheduler,
6825 ActiveTime is the duration the scheduler has been busy, and
6826 TotalTime is the total time duration since scheduler_wall_time
6827 activation for the specific scheduler. Note that activation time
6828 can differ significantly between schedulers. Currently dirty
6829 schedulers are activated at system start while normal schedulers
6830 are activated some time after the scheduler_wall_time function‐
6831 ality is enabled. The time unit is undefined and can be subject
6832 to change between releases, OSs, and system restarts. sched‐
6833 uler_wall_time is only to be used to calculate relative values
6834 for scheduler utilization. ActiveTime can never exceed Total‐
6835 Time.
6836 The definition of a busy scheduler is when it is not idle and is
6838 not scheduling (selecting) a process or port, that is:
6839 * Executing process code
6841 * Executing linked-in driver or NIF code
6843 * Executing BIFs, or any other runtime handling
6845 * Garbage collecting
6847 * Handling any other memory management
6849 Notice that a scheduler can also be busy even if the OS has
6851 scheduled out the scheduler thread.
6852 Returns undefined if system flag scheduler_wall_time is turned
6854 off.
6855 The list of scheduler information is unsorted and can appear in
6857 different order between calls.
6858 As of ERTS version 9.0, also dirty CPU schedulers will be
6860 included in the result. That is, all scheduler threads that are
6861 expected to handle CPU bound work. If you also want information
6862 about dirty I/O schedulers, use statistics(sched‐
6863 uler_wall_time_all) instead.
6864 Normal schedulers will have scheduler identifiers in the range 1
6866 =< SchedulerId =< erlang:system_info(schedulers). Dirty CPU
6867 schedulers will have scheduler identifiers in the range
6868 erlang:system_info(schedulers) < SchedulerId =< erlang:sys‐
6869 tem_info(schedulers) + erlang:system_info(dirty_cpu_schedulers).
6870 Note:
6872 The different types of schedulers handle specific types of jobs.
6873 Every job is assigned to a specific scheduler type. Jobs can
6874 migrate between different schedulers of the same type, but never
6875 between schedulers of different types. This fact has to be taken
6876 under consideration when evaluating the result returned.
6877 Using scheduler_wall_time to calculate scheduler utilization:
6880 > erlang:system_flag(scheduler_wall_time, true).
6882 false
6883 > Ts0 = lists:sort(erlang:statistics(scheduler_wall_time)), ok.
6884 ok
6885 Some time later the user takes another snapshot and calculates
6887 scheduler utilization per scheduler, for example:
6888 > Ts1 = lists:sort(erlang:statistics(scheduler_wall_time)), ok.
6890 ok
6891 > lists:map(fun({{I, A0, T0}, {I, A1, T1}}) -> {I, (A1 - A0)/(T1 - T0)} end, lists:zip(Ts0,Ts1)).
6892 [{1,0.9743474730177548},
6893 {2,0.9744843782751444},
6894 {3,0.9995902361669045},
6895 {4,0.9738012596572161},
6896 {5,0.9717956667018103},
6897 {6,0.9739235846420741},
6898 {7,0.973237033077876},
6899 {8,0.9741297293248656}]
6900 Using the same snapshots to calculate a total scheduler utiliza‐
6902 tion:
6903 > {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.
6905 0.9769136803764825
6906 Total scheduler utilization will equal 1.0 when all schedulers
6908 have been active all the time between the two measurements.
6909 Another (probably more) useful value is to calculate total
6911 scheduler utilization weighted against maximum amount of avail‐
6912 able CPU time:
6913 > WeightedSchedulerUtilization = (TotalSchedulerUtilization * (erlang:system_info(schedulers) + erlang:system_info(dirty_cpu_schedulers))) / erlang:system_info(logical_processors_available).
6915 0.9769136803764825
6916 This weighted scheduler utilization will reach 1.0 when sched‐
6918 ulers are active the same amount of time as maximum available
6919 CPU time. If more schedulers exist than available logical pro‐
6920 cessors, this value may be greater than 1.0.
6921 As of ERTS version 9.0, the Erlang runtime system will as
6923 default have more schedulers than logical processors. This due
6924 to the dirty schedulers.
6925 Note:
6927 scheduler_wall_time is by default disabled. To enable it, use
6928 erlang:system_flag(scheduler_wall_time, true).
6929 statistics(Item :: scheduler_wall_time_all) ->
6932 [{SchedulerId, ActiveTime, TotalTime}] | undefined
6933 Types:
6935 SchedulerId = integer() >= 1
6937 ActiveTime = TotalTime = integer() >= 0
6938 The same as statistics(scheduler_wall_time), except that it also
6940 include information about all dirty I/O schedulers.
6941 Dirty IO schedulers will have scheduler identifiers in the range
6943 erlang:system_info(schedulers) + erlang:sys‐
6944 tem_info(dirty_cpu_schedulers) < SchedulerId =< erlang:sys‐
6945 tem_info(schedulers) + erlang:system_info(dirty_cpu_schedulers)
6946 + erlang:system_info(dirty_io_schedulers).
6947 Note:
6949 Note that work executing on dirty I/O schedulers are expected to
6950 mainly wait for I/O. That is, when you get high scheduler uti‐
6951 lization on dirty I/O schedulers, CPU utilization is not
6952 expected to be high due to this work.
6953 statistics(Item :: total_active_tasks) -> ActiveTasks
6956 Types:
6958 ActiveTasks = integer() >= 0
6960 The same as calling lists:sum(statistics(active_tasks)), but
6962 more efficient.
6963 statistics(Item :: total_active_tasks_all) -> ActiveTasks
6965 Types:
6967 ActiveTasks = integer() >= 0
6969 The same as calling lists:sum(statistics(active_tasks_all)), but
6971 more efficient.
6972 statistics(Item :: total_run_queue_lengths) ->
6974 TotalRunQueueLengths
6975 Types:
6977 TotalRunQueueLengths = integer() >= 0
6979 The same as calling lists:sum(statistics(run_queue_lengths)),
6981 but more efficient.
6982 statistics(Item :: total_run_queue_lengths_all) ->
6984 TotalRunQueueLengths
6985 Types:
6987 TotalRunQueueLengths = integer() >= 0
6989 The same as calling lists:sum(statis‐
6991 tics(run_queue_lengths_all)), but more efficient.
6992 statistics(Item :: wall_clock) ->
6994 {Total_Wallclock_Time,
6995 Wallclock_Time_Since_Last_Call}
6996 Types:
6998 Total_Wallclock_Time = Wallclock_Time_Since_Last_Call = inte‐
7000 ger() >= 0
7001 Returns information about wall clock. wall_clock can be used in
7003 the same manner as runtime, except that real time is measured as
7004 opposed to runtime or CPU time.
7005 erlang:suspend_process(Suspendee) -> true
7007 Types:
7009 Suspendee = pid()
7011 Suspends the process identified by Suspendee. The same as call‐
7013 ing erlang:suspend_process(Suspendee, []).
7014 Warning:
7016 This BIF is intended for debugging only.
7017 erlang:suspend_process(Suspendee, OptList) -> boolean()
7020 Types:
7022 Suspendee = pid()
7024 OptList = [Opt]
7025 Opt = unless_suspending | asynchronous | {asynchronous,
7026 term()}
7027 Increases the suspend count on the process identified by Sus‐
7029 pendee and puts it in the suspended state if it is not already
7030 in that state. A suspended process is not scheduled for execu‐
7031 tion until the process has been resumed.
7032 A process can be suspended by multiple processes and can be sus‐
7034 pended multiple times by a single process. A suspended process
7035 does not leave the suspended state until its suspend count
7036 reaches zero. The suspend count of Suspendee is decreased when
7037 erlang:resume_process(Suspendee) is called by the same process
7038 that called erlang:suspend_process(Suspendee). All increased
7039 suspend counts on other processes acquired by a process are
7040 automatically decreased when the process terminates.
7041 Options (Opts):
7043 asynchronous:
7045 A suspend request is sent to the process identified by Sus‐
7046 pendee. Suspendee eventually suspends unless it is resumed
7047 before it could suspend. The caller of erlang:sus‐
7048 pend_process/2 returns immediately, regardless of whether
7049 Suspendee has suspended yet or not. The point in time when
7050 Suspendee suspends cannot be deduced from other events in
7051 the system. It is only guaranteed that Suspendee eventually
7052 suspends (unless it is resumed). If no asynchronous options
7053 has been passed, the caller of erlang:suspend_process/2 is
7054 blocked until Suspendee has suspended.
7055 {asynchronous, ReplyTag}:
7057 A suspend request is sent to the process identified by Sus‐
7058 pendee. When the suspend request has been processed, a reply
7059 message is sent to the caller of this function. The reply is
7060 on the form {ReplyTag, State} where State is either:
7061 exited:
7063 Suspendee has exited.
7064 suspended:
7066 Suspendee is now suspended.
7067 not_suspended:
7069 Suspendee is not suspended. This can only happen when the
7070 process that issued this request, have called
7071 resume_process(Suspendee) before getting the reply.
7072 Appart from the reply message, the {asynchronous, ReplyTag}
7074 option behaves exactly the same as the asynchronous option
7075 without reply tag.
7076 unless_suspending:
7078 The process identified by Suspendee is suspended unless the
7079 calling process already is suspending Suspendee. If
7080 unless_suspending is combined with option asynchronous, a
7081 suspend request is sent unless the calling process already
7082 is suspending Suspendee or if a suspend request already has
7083 been sent and is in transit. If the calling process already
7084 is suspending Suspendee, or if combined with option asyn‐
7085 chronous and a send request already is in transit, false is
7086 returned and the suspend count on Suspendee remains
7087 unchanged.
7088 If the suspend count on the process identified by Suspendee is
7090 increased, true is returned, otherwise false.
7091 Warning:
7093 This BIF is intended for debugging only.
7094 Warning:
7097 You can easily create deadlocks if processes suspends each other
7098 (directly or in circles). In ERTS versions prior to ERTS version
7099 10.0, the runtime system prevented such deadlocks, but this pre‐
7100 vention has now been removed due to performance reasons.
7101 Failures:
7104 badarg:
7106 If Suspendee is not a process identifier.
7107 badarg:
7109 If the process identified by Suspendee is the same process
7110 as the process calling erlang:suspend_process/2.
7111 badarg:
7113 If the process identified by Suspendee is not alive.
7114 badarg:
7116 If the process identified by Suspendee resides on another
7117 node.
7118 badarg:
7120 If OptList is not a proper list of valid Opts.
7121 system_limit:
7123 If the process identified by Suspendee has been suspended
7124 more times by the calling process than can be represented by
7125 the currently used internal data structures. The system
7126 limit is > 2,000,000,000 suspends and will never be lower.
7127 erlang:system_flag(Flag :: backtrace_depth, Depth) -> OldDepth
7129 Types:
7131 Depth = OldDepth = integer() >= 0
7133 Sets the maximum depth of call stack back-traces in the exit
7135 reason element of 'EXIT' tuples. The flag also limits the stack‐
7136 trace depth returned by process_info item current_stacktrace.
7137 Returns the old value of the flag.
7139 erlang:system_flag(Flag :: cpu_topology, CpuTopology) ->
7141 OldCpuTopology
7142 Types:
7144 CpuTopology = OldCpuTopology = cpu_topology()
7146 cpu_topology() = [LevelEntry :: level_entry()] | undefined
7147 level_entry() =
7148 {LevelTag :: level_tag(), SubLevel :: sub_level()} |
7149 {LevelTag :: level_tag(),
7150 InfoList :: info_list(),
7151 SubLevel :: sub_level()}
7152 level_tag() = core | node | processor | thread
7153 sub_level() =
7154 [LevelEntry :: level_entry()] |
7155 (LogicalCpuId :: {logical, integer() >= 0})
7156 info_list() = []
7157 Warning:
7159 This argument is deprecated. Instead of using this argument, use
7160 command-line argument +sct in erl(1).
7161 When this argument is removed, a final CPU topology to use is
7163 determined at emulator boot time.
7164 Sets the user-defined CpuTopology. The user-defined CPU topology
7167 overrides any automatically detected CPU topology. By passing
7168 undefined as CpuTopology, the system reverts to the CPU topology
7169 automatically detected. The returned value equals the value
7170 returned from erlang:system_info(cpu_topology) before the change
7171 was made.
7172 Returns the old value of the flag.
7174 The CPU topology is used when binding schedulers to logical pro‐
7176 cessors. If schedulers are already bound when the CPU topology
7177 is changed, the schedulers are sent a request to rebind accord‐
7178 ing to the new CPU topology.
7179 The user-defined CPU topology can also be set by passing com‐
7181 mand-line argument +sct to erl(1).
7182 For information on type CpuTopology and more, see erlang:sys‐
7184 tem_info(cpu_topology) as well as command-line flags +sct and
7185 +sbt in erl(1).
7186 erlang:system_flag(Flag :: dirty_cpu_schedulers_online,
7188 DirtyCPUSchedulersOnline) ->
7189 OldDirtyCPUSchedulersOnline
7190 Types:
7192 DirtyCPUSchedulersOnline = OldDirtyCPUSchedulersOnline =
7194 integer() >= 1
7195 Sets the number of dirty CPU schedulers online. Range is 1 <=
7197 DirtyCPUSchedulersOnline <= N, where N is the smallest of the
7198 return values of erlang:system_info(dirty_cpu_schedulers) and
7199 erlang:system_info(schedulers_online).
7200 Returns the old value of the flag.
7202 The number of dirty CPU schedulers online can change if the num‐
7204 ber of schedulers online changes. For example, if 12 schedulers
7205 and 6 dirty CPU schedulers are online, and system_flag/2 is used
7206 to set the number of schedulers online to 6, then the number of
7207 dirty CPU schedulers online is automatically decreased by half
7208 as well, down to 3. Similarly, the number of dirty CPU sched‐
7209 ulers online increases proportionally to increases in the number
7210 of schedulers online.
7211 For more information, see erlang:system_info(dirty_cpu_sched‐
7213 ulers) and erlang:system_info(dirty_cpu_schedulers_online).
7214 erlang:system_flag(Flag :: erts_alloc, Value :: {Alloc, F, V}) ->
7216 ok | notsup
7217 Types:
7219 Alloc = F = atom()
7221 V = integer()
7222 Sets system flags for erts_alloc(3). Alloc is the allocator to
7224 affect, for example binary_alloc. F is the flag to change and V
7225 is the new value.
7226 Only a subset of all erts_alloc flags can be changed at run
7228 time. This subset is currently only the flag sbct.
7229 Returns ok if the flag was set or notsup if not supported by
7231 erts_alloc.
7232 erlang:system_flag(Flag :: fullsweep_after, Number) -> OldNumber
7234 Types:
7236 Number = OldNumber = integer() >= 0
7238 Sets system flag fullsweep_after. Number is a non-negative inte‐
7240 ger indicating how many times generational garbage collections
7241 can be done without forcing a fullsweep collection. The value
7242 applies to new processes, while processes already running are
7243 not affected.
7244 Returns the old value of the flag.
7246 In low-memory systems (especially without virtual memory), set‐
7248 ting the value to 0 can help to conserve memory.
7249 This value can also be set through (OS) environment variable
7251 ERL_FULLSWEEP_AFTER.
7252 erlang:system_flag(Flag :: microstate_accounting, Action) ->
7254 OldState
7255 Types:
7257 Action = true | false | reset
7259 OldState = true | false
7260 Turns on/off microstate accounting measurements. When passing
7262 reset, all counters are reset to 0.
7263 For more information see statistics(microstate_accounting).
7265 erlang:system_flag(Flag :: min_heap_size, MinHeapSize) ->
7267 OldMinHeapSize
7268 Types:
7270 MinHeapSize = OldMinHeapSize = integer() >= 0
7272 Sets the default minimum heap size for processes. The size is
7274 specified in words. The new min_heap_size effects only processes
7275 spawned after the change of min_heap_size has been made.
7276 min_heap_size can be set for individual processes by using
7277 spawn_opt/4 or process_flag/2.
7278 Returns the old value of the flag.
7280 erlang:system_flag(Flag :: min_bin_vheap_size, MinBinVHeapSize) ->
7282 OldMinBinVHeapSize
7283 Types:
7285 MinBinVHeapSize = OldMinBinVHeapSize = integer() >= 0
7287 Sets the default minimum binary virtual heap size for processes.
7289 The size is specified in words. The new min_bin_vhheap_size
7290 effects only processes spawned after the change of
7291 min_bin_vheap_size has been made. min_bin_vheap_size can be set
7292 for individual processes by using spawn_opt/2,3,4 or
7293 process_flag/2.
7294 Returns the old value of the flag.
7296 erlang:system_flag(Flag :: max_heap_size, MaxHeapSize) ->
7298 OldMaxHeapSize
7299 Types:
7301 MaxHeapSize = OldMaxHeapSize = max_heap_size()
7303 max_heap_size() =
7304 integer() >= 0 |
7305 #{size => integer() >= 0,
7306 kill => boolean(),
7307 error_logger => boolean()}
7308 Sets the default maximum heap size settings for processes. The
7310 size is specified in words. The new max_heap_size effects only
7311 processes spawned efter the change has been made. max_heap_size
7312 can be set for individual processes using spawn_opt/2,3,4 or
7313 process_flag/2.
7314 Returns the old value of the flag.
7316 erlang:system_flag(Flag :: multi_scheduling, BlockState) ->
7318 OldBlockState
7319 Types:
7321 BlockState = block | unblock | block_normal | unblock_normal
7323 OldBlockState = blocked | disabled | enabled
7324 If multi-scheduling is enabled, more than one scheduler thread
7326 is used by the emulator. Multi-scheduling can be blocked in two
7327 different ways. Either all schedulers but one is blocked, or all
7328 normal schedulers but one is blocked. When only normal sched‐
7329 ulers are blocked, dirty schedulers are free to continue to
7330 schedule processes.
7331 If BlockState =:= block, multi-scheduling is blocked. That is,
7333 one and only one scheduler thread will execute. If BlockState
7334 =:= unblock and no one else blocks multi-scheduling, and this
7335 process has blocked only once, multi-scheduling is unblocked.
7336 If BlockState =:= block_normal, normal multi-scheduling is
7338 blocked. That is, only one normal scheduler thread will execute,
7339 but multiple dirty schedulers can execute. If BlockState =:=
7340 unblock_normal and no one else blocks normal multi-scheduling,
7341 and this process has blocked only once, normal multi-scheduling
7342 is unblocked.
7343 One process can block multi-scheduling and normal multi-schedul‐
7345 ing multiple times. If a process has blocked multiple times, it
7346 must unblock exactly as many times as it has blocked before it
7347 has released its multi-scheduling block. If a process that has
7348 blocked multi-scheduling or normal multi-scheduling exits, it
7349 automatically releases its blocking of multi-scheduling and nor‐
7350 mal multi-scheduling.
7351 The return values are disabled, blocked, blocked_normal, or
7353 enabled. The returned value describes the state just after the
7354 call to erlang:system_flag(multi_scheduling, BlockState) has
7355 been made. For information about the return values, see
7356 erlang:system_info(multi_scheduling).
7357 Note:
7359 Blocking of multi-scheduling and normal multi-scheduling is nor‐
7360 mally not needed. If you feel that you need to use these fea‐
7361 tures, consider it a few more times again. Blocking multi-sched‐
7362 uling is only to be used as a last resort, as it is most likely
7363 a very inefficient way to solve the problem.
7364 See also erlang:system_info(multi_scheduling), erlang:sys‐
7367 tem_info(normal_multi_scheduling_blockers), erlang:sys‐
7368 tem_info(multi_scheduling_blockers), and erlang:sys‐
7369 tem_info(schedulers).
7370 erlang:system_flag(Flag :: scheduler_bind_type, How) ->
7372 OldBindType
7373 Types:
7375 How = scheduler_bind_type() | default_bind
7377 OldBindType = scheduler_bind_type()
7378 scheduler_bind_type() =
7379 no_node_processor_spread | no_node_thread_spread | no_spread |
7380 processor_spread | spread | thread_spread |
7381 thread_no_node_processor_spread | unbound
7382 Warning:
7384 This argument is deprecated. Instead of using this argument, use
7385 command-line argument +sbt in erl(1). When this argument is
7386 removed, a final scheduler bind type to use is determined at
7387 emulator boot time.
7388 Controls if and how schedulers are bound to logical processors.
7391 When erlang:system_flag(scheduler_bind_type, How) is called, an
7393 asynchronous signal is sent to all schedulers online, causing
7394 them to try to bind or unbind as requested.
7395 Note:
7397 If a scheduler fails to bind, this is often silently ignored, as
7398 it is not always possible to verify valid logical processor
7399 identifiers. If an error is reported, an error event is logged.
7400 To verify that the schedulers have bound as requested, call
7401 erlang:system_info(scheduler_bindings).
7402 Schedulers can be bound on newer Linux, Solaris, FreeBSD, and
7405 Windows systems, but more systems will be supported in future
7406 releases.
7407 In order for the runtime system to be able to bind schedulers,
7409 the CPU topology must be known. If the runtime system fails to
7410 detect the CPU topology automatically, it can be defined. For
7411 more information on how to define the CPU topology, see command-
7412 line flag +sct in erl(1).
7413 The runtime system does by default not bind schedulers to logi‐
7415 cal processors.
7416 Note:
7418 If the Erlang runtime system is the only OS process binding
7419 threads to logical processors, this improves the performance of
7420 the runtime system. However, if other OS processes (for example,
7421 another Erlang runtime system) also bind threads to logical pro‐
7422 cessors, there can be a performance penalty instead. Sometimes
7423 this performance penalty can be severe. If so, it is recommended
7424 to not bind the schedulers.
7425 Schedulers can be bound in different ways. Argument How deter‐
7428 mines how schedulers are bound and can be any of the following:
7429 unbound:
7431 Same as command-line argument +sbt u in erl(1).
7432 no_spread:
7434 Same as command-line argument +sbt ns in erl(1).
7435 thread_spread:
7437 Same as command-line argument +sbt ts in erl(1).
7438 processor_spread:
7440 Same as command-line argument +sbt ps in erl(1).
7441 spread:
7443 Same as command-line argument +sbt s in erl(1).
7444 no_node_thread_spread:
7446 Same as command-line argument +sbt nnts in erl(1).
7447 no_node_processor_spread:
7449 Same as command-line argument +sbt nnps in erl(1).
7450 thread_no_node_processor_spread:
7452 Same as command-line argument +sbt tnnps in erl(1).
7453 default_bind:
7455 Same as command-line argument +sbt db in erl(1).
7456 The returned value equals How before flag scheduler_bind_type
7458 was changed.
7459 Failures:
7461 notsup:
7463 If binding of schedulers is not supported.
7464 badarg:
7466 If How is not one of the documented alternatives.
7467 badarg:
7469 If CPU topology information is unavailable.
7470 The scheduler bind type can also be set by passing command-line
7472 argument +sbt to erl(1).
7473 For more information, see erlang:system_info(sched‐
7475 uler_bind_type), erlang:system_info(scheduler_bindings), as well
7476 as command-line flags +sbt and +sct in erl(1).
7477 erlang:system_flag(Flag :: scheduler_wall_time, Boolean) ->
7479 OldBoolean
7480 Types:
7482 Boolean = OldBoolean = boolean()
7484 Turns on or off scheduler wall time measurements.
7486 For more information, see statistics(scheduler_wall_time).
7488 erlang:system_flag(Flag :: schedulers_online, SchedulersOnline) ->
7490 OldSchedulersOnline
7491 Types:
7493 SchedulersOnline = OldSchedulersOnline = integer() >= 1
7495 Sets the number of schedulers online. Range is 1 <= Scheduler‐
7497 sOnline <= erlang:system_info(schedulers).
7498 Returns the old value of the flag.
7500 If the emulator was built with support for dirty schedulers,
7502 changing the number of schedulers online can also change the
7503 number of dirty CPU schedulers online. For example, if 12 sched‐
7504 ulers and 6 dirty CPU schedulers are online, and system_flag/2
7505 is used to set the number of schedulers online to 6, then the
7506 number of dirty CPU schedulers online is automatically decreased
7507 by half as well, down to 3. Similarly, the number of dirty CPU
7508 schedulers online increases proportionally to increases in the
7509 number of schedulers online.
7510 For more information, see erlang:system_info(schedulers) and
7512 erlang:system_info(schedulers_online).
7513 erlang:system_flag(Flag :: system_logger, Logger) -> PrevLogger
7515 Types:
7517 Logger = PrevLogger = logger | undefined | pid()
7519 Sets the process that will receive the logging messages gener‐
7521 ated by ERTS. If set to undefined, all logging messages gener‐
7522 ated by ERTS will be dropped. The messages will be in the for‐
7523 mat:
7524 {log,Level,Format,ArgList,Metadata} where
7526 Level = atom(),
7528 Format = string(),
7529 ArgList = list(term()),
7530 Metadata = #{ pid => pid(),
7531 group_leader => pid(),
7532 time := logger:timestamp(),
7533 error_logger := #{ emulator := true, tag := atom() }
7534 If the system_logger process dies, this flag will be reset to
7537 logger.
7538 The default is the process named logger.
7540 Returns the old value of the flag.
7542 Note:
7544 This function is designed to be used by the KERNEL logger. Be
7545 careful if you change it to something else as log messages may
7546 be lost. If you want to intercept emulator log messages, do it
7547 by adding a specialized handler to the KERNEL logger.
7548 erlang:system_flag(Flag :: trace_control_word, TCW) -> OldTCW
7551 Types:
7553 TCW = OldTCW = integer() >= 0
7555 Sets the value of the node trace control word to TCW, which is
7557 to be an unsigned integer. For more information, see function
7558 set_tcw in section "Match Specifications in Erlang" in the
7559 User's Guide.
7560 Returns the old value of the flag.
7562 erlang:system_flag(Flag :: time_offset, Value :: finalize) ->
7564 OldState
7565 Types:
7567 OldState = preliminary | final | volatile
7569 Finalizes the time offset when single time warp mode is used. If
7571 another time warp mode is used, the time offset state is left
7572 unchanged.
7573 Returns the old state identifier, that is:
7575 * If preliminary is returned, finalization was performed and
7577 the time offset is now final.
7578 * If final is returned, the time offset was already in the
7580 final state. This either because another erlang:sys‐
7581 tem_flag(time_offset, finalize) call or because no time warp
7582 mode is used.
7583 * If volatile is returned, the time offset cannot be finalized
7585 because multi-time warp mode is used.
7586 erlang:system_info(Item ::
7588 wordsize |
7589 {wordsize, internal} |
7590 {wordsize, external}) ->
7591 4 | 8
7592 Returns information about the current system. The documentation
7594 of this function is broken into the following sections in order
7595 to make it easier to navigate.
7596 Memory Allocation:
7598 allocated_areas, allocator, alloc_util_allocators, alloca‐
7599 tor_sizes, elib_malloc
7600 CPU Topology:
7602 cpu_topology, logical_processors, update_cpu_info
7603 Process Information:
7605 fullsweep_after, garbage_collection, heap_sizes, heap_type,
7606 max_heap_size, message_queue_data, min_heap_size,
7607 min_bin_vheap_size, procs
7608 System Limits:
7610 atom_count, atom_limit, ets_count, ets_limit, port_count,
7611 port_limit, process_count, process_limit
7612 System Time:
7614 end_time, os_monotonic_time_source, os_system_time_source,
7615 start_time, time_correction, time_offset, time_warp_mode,
7616 tolerant_timeofday
7617 Scheduler Information:
7619 dirty_cpu_schedulers, dirty_cpu_schedulers_online,
7620 dirty_io_schedulers, multi_scheduling, multi_schedul‐
7621 ing_blockers, normal_multi_scheduling_blockers, sched‐
7622 uler_bind_type, scheduler_bindings, scheduler_id, sched‐
7623 ulers, smp_support, threads, thread_pool_size
7624 Distribution Information:
7626 creation, delayed_node_table_gc, dist, dist_buf_busy_limit,
7627 dist_ctrl
7628 System Information:
7630 build_type, c_compiler_used, check_io, compat_rel,
7631 debug_compiled, driver_version, dynamic_trace,
7632 dynamic_trace_probes, info, kernel_poll, loaded, machine,
7633 modified_timing_level, nif_version, otp_release, port_paral‐
7634 lelism, system_architecture, system_logger, system_version,
7635 trace_control_word, version, wordsize
7636 erlang:system_info(Item :: allocated_areas) -> [tuple()]
7638 erlang:system_info(Item :: allocator) ->
7640 {Allocator, Version, Features, Settings}
7641 erlang:system_info(Item :: {allocator, Alloc}) -> [term()]
7643 erlang:system_info(Item :: alloc_util_allocators) -> [Alloc]
7645 erlang:system_info(Item :: {allocator_sizes, Alloc}) -> [term()]
7647 erlang:system_info(Item :: elib_malloc) -> false
7649 Types:
7651 Allocator = undefined | glibc
7653 Version = [integer() >= 0]
7654 Features = [atom()]
7655 Settings =
7656 [{Subsystem :: atom(),
7657 [{Parameter :: atom(), Value :: term()}]}]
7658 Alloc = atom()
7659 Returns various information about the memory allocators of the
7661 current system (emulator) as specified by Item:
7662 allocated_areas:
7664 Returns a list of tuples with information about miscella‐
7665 neous allocated memory areas.
7666 Each tuple contains an atom describing the type of memory as
7668 first element and the amount of allocated memory in bytes as
7669 second element. When information about allocated and used
7670 memory is present, also a third element is present, contain‐
7671 ing the amount of used memory in bytes.
7672 erlang:system_info(allocated_areas) is intended for debug‐
7674 ging, and the content is highly implementation-dependent.
7675 The content of the results therefore changes when needed
7676 without prior notice.
7677 Notice that the sum of these values is not the total amount
7679 of memory allocated by the emulator. Some values are part of
7680 other values, and some memory areas are not part of the
7681 result. For information about the total amount of memory
7682 allocated by the emulator, see erlang:memory/0,1.
7683 allocator:
7685 Returns {Allocator, Version, Features, Settings, where:
7686 * Allocator corresponds to the malloc() implementation used.
7688 If Allocator equals undefined, the malloc() implementation
7689 used cannot be identified. glibc can be identified.
7690 * Version is a list of integers (but not a string) repre‐
7692 senting the version of the malloc() implementation used.
7693 * Features is a list of atoms representing the allocation
7695 features used.
7696 * Settings is a list of subsystems, their configurable
7698 parameters, and used values. Settings can differ between
7699 different combinations of platforms, allocators, and allo‐
7700 cation features. Memory sizes are given in bytes.
7701 See also "System Flags Effecting erts_alloc" in
7703 erts_alloc(3).
7704 {allocator, Alloc}:
7706 Returns information about the specified allocator. As from
7707 ERTS 5.6.1, the return value is a list of {instance, Instan‐
7708 ceNo, InstanceInfo} tuples, where InstanceInfo contains
7709 information about a specific instance of the allocator. If
7710 Alloc is not a recognized allocator, undefined is returned.
7711 If Alloc is disabled, false is returned.
7712 Notice that the information returned is highly implementa‐
7714 tion-dependent and can be changed or removed at any time
7715 without prior notice. It was initially intended as a tool
7716 when developing new allocators, but as it can be of interest
7717 for others it has been briefly documented.
7718 The recognized allocators are listed in erts_alloc(3).
7720 Information about super carriers can be obtained from ERTS
7721 8.0 with {allocator, erts_mmap} or from ERTS 5.10.4; the
7722 returned list when calling with {allocator, mseg_alloc} also
7723 includes an {erts_mmap, _} tuple as one element in the list.
7724 After reading the erts_alloc(3) documentation, the returned
7726 information more or less speaks for itself, but it can be
7727 worth explaining some things. Call counts are presented by
7728 two values, the first value is giga calls, and the second
7729 value is calls. mbcs and sbcs denote multi-block carriers,
7730 and single-block carriers, respectively. Sizes are presented
7731 in bytes. When a size is not presented, it is the amount of
7732 something. Sizes and amounts are often presented by three
7733 values:
7734 * The first is the current value.
7736 * The second is the maximum value since the last call to
7738 erlang:system_info({allocator, Alloc}).
7739 * The third is the maximum value since the emulator was
7741 started.
7742 If only one value is present, it is the current value.
7744 fix_alloc memory block types are presented by two values.
7745 The first value is the memory pool size and the second value
7746 is the used memory size.
7747 alloc_util_allocators:
7749 Returns a list of the names of all allocators using the ERTS
7750 internal alloc_util framework as atoms. For more informa‐
7751 tion, see section The alloc_util framework in erts_alloc(3).
7752 {allocator_sizes, Alloc}:
7754 Returns various size information for the specified alloca‐
7755 tor. The information returned is a subset of the information
7756 returned by erlang:system_info({allocator, Alloc}).
7757 elib_malloc:
7759 This option will be removed in a future release. The return
7760 value will always be false, as the elib_malloc allocator has
7761 been removed.
7762 erlang:system_info(Item :: cpu_topology) -> CpuTopology
7764 erlang:system_info(Item ::
7766 {cpu_topology, defined | detected | used}) ->
7767 CpuTopology
7768 erlang:system_info(Item ::
7770 logical_processors |
7771 logical_processors_available |
7772 logical_processors_online) ->
7773 unknown | integer() >= 1
7774 erlang:system_info(Item :: update_cpu_info) -> changed | unchanged
7776 Types:
7778 cpu_topology() = [LevelEntry :: level_entry()] | undefined
7780 All LevelEntrys of a list must contain the same LevelTag,
7781 except on the top level where both node and processor‐
7782 LevelTags can coexist.
7783 level_entry() =
7784 {LevelTag :: level_tag(), SubLevel :: sub_level()} |
7785 {LevelTag :: level_tag(),
7786 InfoList :: info_list(),
7787 SubLevel :: sub_level()}
7788 {LevelTag, SubLevel} == {LevelTag, [], SubLevel}
7789 level_tag() = core | node | processor | thread
7790 More LevelTags can be introduced in a future release.
7791 sub_level() =
7792 [LevelEntry :: level_entry()] |
7793 (LogicalCpuId :: {logical, integer() >= 0})
7794 info_list() = []
7795 The info_list() can be extended in a future release.
7796 Returns various information about the CPU topology of the cur‐
7798 rent system (emulator) as specified by Item:
7799 cpu_topology:
7801 Returns the CpuTopology currently used by the emulator. The
7802 CPU topology is used when binding schedulers to logical pro‐
7803 cessors. The CPU topology used is the user-defined CPU
7804 topology, if such exists, otherwise the automatically
7805 detected CPU topology, if such exists. If no CPU topology
7806 exists, undefined is returned.
7807 node refers to Non-Uniform Memory Access (NUMA) nodes.
7809 thread refers to hardware threads (for example, Intel hyper-
7810 threads).
7811 A level in term CpuTopology can be omitted if only one entry
7813 exists and InfoList is empty.
7814 thread can only be a sublevel to core. core can be a sub‐
7816 level to processor or node. processor can be on the top
7817 level or a sublevel to node. node can be on the top level or
7818 a sublevel to processor. That is, NUMA nodes can be proces‐
7819 sor internal or processor external. A CPU topology can con‐
7820 sist of a mix of processor internal and external NUMA nodes,
7821 as long as each logical CPU belongs to one NUMA node. Cache
7822 hierarchy is not part of the CpuTopology type, but will be
7823 in a future release. Other things can also make it into the
7824 CPU topology in a future release. So, expect the CpuTopology
7825 type to change.
7826 {cpu_topology, defined}:
7828 Returns the user-defined CpuTopology. For more information,
7831 see command-line flag +sct in erl(1) and argument cpu_topol‐
7832 ogy.
7833 {cpu_topology, detected}:
7835 Returns the automatically detected CpuTopologyy. The emula‐
7838 tor detects the CPU topology on some newer Linux, Solaris,
7839 FreeBSD, and Windows systems. On Windows system with more
7840 than 32 logical processors, the CPU topology is not
7841 detected.
7842 For more information, see argument cpu_topology.
7844 {cpu_topology, used}:
7846 Returns CpuTopology used by the emulator. For more informa‐
7847 tion, see argument cpu_topology.
7848 logical_processors:
7850 Returns the detected number of logical processors configured
7851 in the system. The return value is either an integer, or the
7852 atom unknown if the emulator cannot detect the configured
7853 logical processors.
7854 logical_processors_available:
7856 Returns the detected number of logical processors available
7857 to the Erlang runtime system. The return value is either an
7858 integer, or the atom unknown if the emulator cannot detect
7859 the available logical processors. The number of available
7860 logical processors is less than or equal to the number of
7861 logical processors online.
7862 logical_processors_online:
7864 Returns the detected number of logical processors online on
7865 the system. The return value is either an integer, or the
7866 atom unknown if the emulator cannot detect logical proces‐
7867 sors online. The number of logical processors online is less
7868 than or equal to the number of logical processors config‐
7869 ured.
7870 update_cpu_info:
7872 The runtime system rereads the CPU information available and
7873 updates its internally stored information about the detected
7874 CPU topology and the number of logical processors config‐
7875 ured, online, and available.
7876 If the CPU information has changed since the last time it
7878 was read, the atom changed is returned, otherwise the atom
7879 unchanged. If the CPU information has changed, you probably
7880 want to adjust the number of schedulers online. You typi‐
7881 cally want to have as many schedulers online as logical pro‐
7882 cessors available.
7883 erlang:system_info(Item :: fullsweep_after) ->
7885 {fullsweep_after, integer() >= 0}
7886 erlang:system_info(Item :: garbage_collection) ->
7888 [{atom(), integer()}]
7889 erlang:system_info(Item :: heap_sizes) -> [integer() >= 0]
7891 erlang:system_info(Item :: heap_type) -> private
7893 erlang:system_info(Item :: max_heap_size) ->
7895 {max_heap_size,
7896 MaxHeapSize :: max_heap_size()}
7897 erlang:system_info(Item :: message_queue_data) ->
7899 message_queue_data()
7900 erlang:system_info(Item :: min_heap_size) ->
7902 {min_heap_size,
7903 MinHeapSize :: integer() >= 1}
7904 erlang:system_info(Item :: min_bin_vheap_size) ->
7906 {min_bin_vheap_size,
7907 MinBinVHeapSize :: integer() >= 1}
7908 erlang:system_info(Item :: procs) -> binary()
7910 Types:
7912 message_queue_data() = off_heap | on_heap
7914 max_heap_size() =
7915 integer() >= 0 |
7916 #{size => integer() >= 0,
7917 kill => boolean(),
7918 error_logger => boolean()}
7919 Returns information about the default process heap settings:
7921 fullsweep_after:
7923 Returns {fullsweep_after, integer() >= 0}, which is the
7924 fullsweep_after garbage collection setting used by default.
7925 For more information, see garbage_collection described
7926 below.
7927 garbage_collection:
7929 Returns a list describing the default garbage collection
7930 settings. A process spawned on the local node by a spawn or
7931 spawn_link uses these garbage collection settings. The
7932 default settings can be changed by using erlang:sys‐
7933 tem_flag/2. spawn_opt/2,3,4 can spawn a process that does
7934 not use the default settings.
7935 heap_sizes:
7937 Returns a list of integers representing valid heap sizes in
7938 words. All Erlang heaps are sized from sizes in this list.
7939 heap_type:
7941 Returns the heap type used by the current emulator. One heap
7942 type exists:
7943 private:
7945 Each process has a heap reserved for its use and no ref‐
7946 erences between heaps of different processes are allowed.
7947 Messages passed between processes are copied between
7948 heaps.
7949 max_heap_size:
7951 Returns {max_heap_size, MaxHeapSize}, where MaxHeapSize is
7952 the current system-wide maximum heap size settings for
7953 spawned processes. This setting can be set using the com‐
7954 mand-line flags +hmax, +hmaxk and +hmaxel in erl(1). It can
7955 also be changed at runtime using erlang:sys‐
7956 tem_flag(max_heap_size, MaxHeapSize). For more details about
7957 the max_heap_size process flag, see
7958 process_flag(max_heap_size, MaxHeapSize).
7959 message_queue_data:
7961 Returns the default value of the message_queue_data process
7962 flag, which is either off_heap or on_heap. This default is
7963 set by command-line argument +hmqd in erl(1). For more
7964 information on the message_queue_data process flag, see doc‐
7965 umentation of process_flag(message_queue_data, MQD).
7966 min_heap_size:
7968 Returns {min_heap_size, MinHeapSize}, where MinHeapSize is
7969 the current system-wide minimum heap size for spawned pro‐
7970 cesses.
7971 min_bin_vheap_size:
7973 Returns {min_bin_vheap_size, MinBinVHeapSize}, where MinBin‐
7974 VHeapSize is the current system-wide minimum binary virtual
7975 heap size for spawned processes.
7976 procs:
7978 Returns a binary containing a string of process and port
7979 information formatted as in Erlang crash dumps. For more
7980 information, see section How to interpret the Erlang crash
7981 dumps in the User's Guide.
7982 erlang:system_info(Item :: atom_count) -> integer() >= 1
7984 erlang:system_info(Item :: atom_limit) -> integer() >= 1
7986 erlang:system_info(Item :: ets_count) -> integer() >= 1
7988 erlang:system_info(Item :: ets_limit) -> integer() >= 1
7990 erlang:system_info(Item :: port_count) -> integer() >= 0
7992 erlang:system_info(Item :: port_limit) -> integer() >= 1
7994 erlang:system_info(Item :: process_count) -> integer() >= 1
7996 erlang:system_info(Item :: process_limit) -> integer() >= 1
7998 Returns information about the current system (emulator) limits
8000 as specified by Item:
8001 atom_count:
8003 Returns the number of atoms currently existing at the local
8004 node. The value is given as an integer.
8005 atom_limit:
8007 Returns the maximum number of atoms allowed. This limit can
8008 be increased at startup by passing command-line flag +t to
8009 erl(1).
8010 ets_count:
8012 Returns the number of ETS tables currently existing at the
8013 local node.
8014 ets_limit:
8016 Returns the limit for number of ETS tables. This limit is
8017 partially obsolete and number of tables are only limited by
8018 available memory.
8019 port_count:
8021 Returns the number of ports currently existing at the local
8022 node. The value is given as an integer. This is the same
8023 value as returned by length(erlang:ports()), but more effi‐
8024 cient.
8025 port_limit:
8027 Returns the maximum number of simultaneously existing ports
8028 at the local node as an integer. This limit can be config‐
8029 ured at startup by using command-line flag +Q in erl(1).
8030 process_count:
8032 Returns the number of processes currently existing at the
8033 local node. The value is given as an integer. This is the
8034 same value as returned by length(processes()), but more
8035 efficient.
8036 process_limit:
8038 Returns the maximum number of simultaneously existing pro‐
8039 cesses at the local node. The value is given as an integer.
8040 This limit can be configured at startup by using command-
8041 line flag +P in erl(1).
8042 erlang:system_info(Item :: end_time) -> integer() >= 0
8044 erlang:system_info(Item :: os_monotonic_time_source) ->
8046 [{atom(), term()}]
8047 erlang:system_info(Item :: os_system_time_source) ->
8049 [{atom(), term()}]
8050 erlang:system_info(Item :: start_time) -> integer()
8052 erlang:system_info(Item :: time_correction) -> true | false
8054 erlang:system_info(Item :: time_offset) ->
8056 preliminary | final | volatile
8057 erlang:system_info(Item :: time_warp_mode) ->
8059 no_time_warp | single_time_warp |
8060 multi_time_warp
8061 erlang:system_info(Item :: tolerant_timeofday) ->
8063 enabled | disabled
8064 Returns information about the current system (emulator) time as
8066 specified by Item:
8067 end_time:
8069 The last Erlang monotonic time in native time unit that can
8070 be represented internally in the current Erlang runtime sys‐
8071 tem instance. The time between the start time and the end
8072 time is at least a quarter of a millennium.
8073 os_monotonic_time_source:
8075 Returns a list containing information about the source of OS
8076 monotonic time that is used by the runtime system.
8077 If [] is returned, no OS monotonic time is available. The
8079 list contains two-tuples with Keys as first element, and
8080 Values as second element. The order of these tuples is unde‐
8081 fined. The following tuples can be part of the list, but
8082 more tuples can be introduced in the future:
8083 {function, Function}:
8085 Function is the name of the function used. This tuple
8086 always exists if OS monotonic time is available to the
8087 runtime system.
8088 {clock_id, ClockId}:
8090 This tuple only exists if Function can be used with dif‐
8091 ferent clocks. ClockId corresponds to the clock identifier
8092 used when calling Function.
8093 {resolution, OsMonotonicTimeResolution}:
8095 Highest possible resolution of current OS monotonic time
8096 source as parts per second. If no resolution information
8097 can be retrieved from the OS, OsMonotonicTimeResolution is
8098 set to the resolution of the time unit of Functions return
8099 value. That is, the actual resolution can be lower than
8100 OsMonotonicTimeResolution. Notice that the resolution does
8101 not say anything about the accuracy or whether the pre‐
8102 cision aligns with the resolution. You do, however, know
8103 that the precision is not better than OsMonotonicTimeReso‐
8104 lution.
8105 {extended, Extended}:
8107 Extended equals yes if the range of time values has been
8108 extended; otherwise Extended equals no. The range must be
8109 extended if Function returns values that wrap fast. This
8110 typically is the case when the return value is a 32-bit
8111 value.
8112 {parallel, Parallel}:
8114 Parallel equals yes if Function is called in parallel from
8115 multiple threads. If it is not called in parallel, because
8116 calls must be serialized, Parallel equals no.
8117 {time, OsMonotonicTime}:
8119 OsMonotonicTime equals current OS monotonic time in native
8120 time unit.
8121 os_system_time_source:
8123 Returns a list containing information about the source of OS
8124 system time that is used by the runtime system.
8125 The list contains two-tuples with Keys as first element, and
8127 Values as second element. The order of these tuples is unde‐
8128 fined. The following tuples can be part of the list, but
8129 more tuples can be introduced in the future:
8130 {function, Function}:
8132 Function is the name of the funcion used.
8133 {clock_id, ClockId}:
8135 Exists only if Function can be used with different clocks.
8136 ClockId corresponds to the clock identifier used when
8137 calling Function.
8138 {resolution, OsSystemTimeResolution}:
8140 Highest possible resolution of current OS system time
8141 source as parts per second. If no resolution information
8142 can be retrieved from the OS, OsSystemTimeResolution is
8143 set to the resolution of the time unit of Functions return
8144 value. That is, the actual resolution can be lower than
8145 OsSystemTimeResolution. Notice that the resolution does
8146 not say anything about the accuracy or whether the pre‐
8147 cision do align with the resolution. You do, however, know
8148 that the precision is not better than OsSystemTimeResolu‐
8149 tion.
8150 {parallel, Parallel}:
8152 Parallel equals yes if Function is called in parallel from
8153 multiple threads. If it is not called in parallel, because
8154 calls needs to be serialized, Parallel equals no.
8155 {time, OsSystemTime}:
8157 OsSystemTime equals current OS system time in native time
8158 unit.
8159 start_time:
8161 The Erlang monotonic time in native time unit at the time
8162 when current Erlang runtime system instance started.
8163 See also erlang:system_info(end_time).
8165 time_correction:
8167 Returns a boolean value indicating whether time correction
8168 is enabled or not.
8169 time_offset:
8171 Returns the state of the time offset:
8172 preliminary:
8174 The time offset is preliminary, and will be changed and
8175 finalized later. The preliminary time offset is used dur‐
8176 ing the preliminary phase of the single time warp mode.
8177 final:
8179 The time offset is final. This either because no time
8180 warp mode is used, or because the time offset have been
8181 finalized when single time warp mode is used.
8182 volatile:
8184 The time offset is volatile. That is, it can change at any
8185 time. This is because multi-time warp mode is used.
8186 time_warp_mode:
8188 Returns a value identifying the time warp mode that is
8189 used:
8190 no_time_warp:
8192 The no time warp mode is used.
8193 single_time_warp:
8195 The single time warp mode is used.
8196 multi_time_warp:
8198 The multi-time warp mode is used.
8199 tolerant_timeofday:
8201 Returns whether a pre ERTS 7.0 backwards compatible compen‐
8202 sation for sudden changes of system time is enabled or dis‐
8203 abled. Such compensation is enabled when the time offset is
8204 final, and time correction is enabled.
8205 erlang:system_info(Item :: dirty_cpu_schedulers) ->
8207 integer() >= 0
8208 erlang:system_info(Item :: dirty_cpu_schedulers_online) ->
8210 integer() >= 0
8211 erlang:system_info(Item :: dirty_io_schedulers) ->
8213 integer() >= 0
8214 erlang:system_info(Item :: multi_scheduling) ->
8216 disabled | blocked | blocked_normal |
8217 enabled
8218 erlang:system_info(Item :: multi_scheduling_blockers) ->
8220 [Pid :: pid()]
8221 erlang:system_info(Item :: otp_release) -> string()
8223 erlang:system_info(Item :: scheduler_bind_type) ->
8225 spread | processor_spread | thread_spread |
8226 thread_no_node_processor_spread |
8227 no_node_processor_spread |
8228 no_node_thread_spread | no_spread | unbound
8229 erlang:system_info(Item :: scheduler_bindings) -> tuple()
8231 erlang:system_info(Item :: scheduler_id) ->
8233 SchedulerId :: integer() >= 1
8234 erlang:system_info(Item :: schedulers | schedulers_online) ->
8236 integer() >= 1
8237 erlang:system_info(Item :: smp_support) -> boolean()
8239 erlang:system_info(Item :: threads) -> boolean()
8241 erlang:system_info(Item :: thread_pool_size) -> integer() >= 0
8243 Returns information about schedulers, scheduling and threads in
8245 the current system as specified by Item:
8246 dirty_cpu_schedulers:
8248 Returns the number of dirty CPU scheduler threads used by
8249 the emulator. Dirty CPU schedulers execute CPU-bound native
8250 functions, such as NIFs, linked-in driver code, and BIFs
8251 that cannot be managed cleanly by the normal emulator sched‐
8252 ulers.
8253 The number of dirty CPU scheduler threads is determined at
8255 emulator boot time and cannot be changed after that. How‐
8256 ever, the number of dirty CPU scheduler threads online can
8257 be changed at any time. The number of dirty CPU schedulers
8258 can be set at startup by passing command-line flag +SDcpu or
8259 +SDPcpu in erl(1).
8260 See also erlang:system_flag(dirty_cpu_schedulers_online,
8262 DirtyCPUSchedulersOnline), erlang:sys‐
8263 tem_info(dirty_cpu_schedulers_online), erlang:sys‐
8264 tem_info(dirty_io_schedulers), erlang:system_info(sched‐
8265 ulers), erlang:system_info(schedulers_online), and
8266 erlang:system_flag(schedulers_online, SchedulersOnline).
8267 dirty_cpu_schedulers_online:
8269 Returns the number of dirty CPU schedulers online. The
8270 return value satisfies 1 <= DirtyCPUSchedulersOnline <= N,
8271 where N is the smallest of the return values of erlang:sys‐
8272 tem_info(dirty_cpu_schedulers) and erlang:system_info(sched‐
8273 ulers_online).
8274 The number of dirty CPU schedulers online can be set at
8276 startup by passing command-line flag +SDcpu in erl(1).
8277 For more information, see erlang:sys‐
8279 tem_info(dirty_cpu_schedulers), erlang:sys‐
8280 tem_info(dirty_io_schedulers), erlang:system_info(sched‐
8281 ulers_online), and erlang:system_flag(dirty_cpu_sched‐
8282 ulers_online, DirtyCPUSchedulersOnline).
8283 dirty_io_schedulers:
8285 Returns the number of dirty I/O schedulers as an integer.
8286 Dirty I/O schedulers execute I/O-bound native functions,
8287 such as NIFs and linked-in driver code, which cannot be man‐
8288 aged cleanly by the normal emulator schedulers.
8289 This value can be set at startup by passing command-line
8291 argument +SDio in erl(1).
8292 For more information, see erlang:sys‐
8294 tem_info(dirty_cpu_schedulers), erlang:sys‐
8295 tem_info(dirty_cpu_schedulers_online), and erlang:sys‐
8296 tem_flag(dirty_cpu_schedulers_online, DirtyCPUSchedulersOn‐
8297 line).
8298 multi_scheduling:
8300 Returns one of the following:
8301 disabled:
8303 The emulator has been started with only one scheduler
8304 thread.
8305 blocked:
8307 The emulator has more than one scheduler thread, but all
8308 scheduler threads except one are blocked. That is, only
8309 one scheduler thread schedules Erlang processes and exe‐
8310 cutes Erlang code.
8311 blocked_normal:
8313 The emulator has more than one scheduler thread, but all
8314 normal scheduler threads except one are blocked. Notice
8315 that dirty schedulers are not blocked, and can schedule
8316 Erlang processes and execute native code.
8317 enabled:
8319 The emulator has more than one scheduler thread, and no
8320 scheduler threads are blocked. That is, all available
8321 scheduler threads schedule Erlang processes and execute
8322 Erlang code.
8323 See also erlang:system_flag(multi_scheduling, BlockState),
8325 erlang:system_info(multi_scheduling_blockers), erlang:sys‐
8326 tem_info(normal_multi_scheduling_blockers), and erlang:sys‐
8327 tem_info(schedulers).
8328 multi_scheduling_blockers:
8330 Returns a list of Pids when multi-scheduling is blocked,
8331 otherwise the empty list is returned. The Pids in the list
8332 represent all the processes currently blocking multi-sched‐
8333 uling. A Pid occurs only once in the list, even if the cor‐
8334 responding process has blocked multiple times.
8335 See also erlang:system_flag(multi_scheduling, BlockState),
8337 erlang:system_info(multi_scheduling), erlang:sys‐
8338 tem_info(normal_multi_scheduling_blockers), and erlang:sys‐
8339 tem_info(schedulers).
8340 normal_multi_scheduling_blockers:
8342 Returns a list of Pids when normal multi-scheduling is
8343 blocked (that is, all normal schedulers but one is blocked),
8344 otherwise the empty list is returned. The Pids in the list
8345 represent all the processes currently blocking normal multi-
8346 scheduling. A Pid occurs only once in the list, even if the
8347 corresponding process has blocked multiple times.
8348 See also erlang:system_flag(multi_scheduling, BlockState),
8350 erlang:system_info(multi_scheduling), erlang:sys‐
8351 tem_info(multi_scheduling_blockers), and erlang:sys‐
8352 tem_info(schedulers).
8353 scheduler_bind_type:
8355 Returns information about how the user has requested sched‐
8356 ulers to be bound or not bound.
8357 Notice that although a user has requested schedulers to be
8359 bound, they can silently have failed to bind. To inspect the
8360 scheduler bindings, call erlang:system_info(scheduler_bind‐
8361 ings).
8362 For more information, see command-line argument +sbt in
8364 erl(1) and erlang:system_info(scheduler_bindings).
8365 scheduler_bindings:
8367 Returns information about the currently used scheduler bind‐
8368 ings.
8369 A tuple of a size equal to erlang:system_info(schedulers) is
8371 returned. The tuple elements are integers or the atom
8372 unbound. Logical processor identifiers are represented as
8373 integers. The Nth element of the tuple equals the current
8374 binding for the scheduler with the scheduler identifier
8375 equal to N. For example, if the schedulers are bound, ele‐
8376 ment(erlang:system_info(scheduler_id), erlang:sys‐
8377 tem_info(scheduler_bindings)) returns the identifier of the
8378 logical processor that the calling process is executing on.
8379 Notice that only schedulers online can be bound to logical
8381 processors.
8382 For more information, see command-line argument +sbt in
8384 erl(1) and erlang:system_info(schedulers_online).
8385 scheduler_id:
8387 Returns the scheduler ID (SchedulerId) of the scheduler
8388 thread that the calling process is executing on. SchedulerId
8389 is a positive integer, where 1 <= SchedulerId <= erlang:sys‐
8390 tem_info(schedulers).
8391 See also erlang:system_info(schedulers).
8393 schedulers:
8395 Returns the number of scheduler threads used by the emula‐
8396 tor. Scheduler threads online schedules Erlang processes and
8397 Erlang ports, and execute Erlang code and Erlang linked-in
8398 driver code.
8399 The number of scheduler threads is determined at emulator
8401 boot time and cannot be changed later. However, the number
8402 of schedulers online can be changed at any time.
8403 See also erlang:system_flag(schedulers_online, SchedulersOn‐
8405 line), erlang:system_info(schedulers_online), erlang:sys‐
8406 tem_info(scheduler_id), erlang:system_flag(multi_scheduling,
8407 BlockState), erlang:system_info(multi_scheduling),
8408 erlang:system_info(normal_multi_scheduling_blockers) and
8409 erlang:system_info(multi_scheduling_blockers).
8410 schedulers_online:
8412 Returns the number of schedulers online. The scheduler iden‐
8413 tifiers of schedulers online satisfy the relationship 1 <=
8414 SchedulerId <= erlang:system_info(schedulers_online).
8415 For more information, see erlang:system_info(schedulers) and
8417 erlang:system_flag(schedulers_online, SchedulersOnline).
8418 smp_support:
8420 Returns true.
8421 threads:
8423 Returns true.
8424 thread_pool_size:
8426 Returns the number of async threads in the async thread pool
8429 used for asynchronous driver calls
8430 (erl_driver:driver_async()). The value is given as an inte‐
8431 ger.
8432 erlang:system_info(Item :: creation) -> integer()
8434 erlang:system_info(Item :: delayed_node_table_gc) ->
8436 infinity | integer() >= 0
8437 erlang:system_info(Item :: dist) -> binary()
8439 erlang:system_info(Item :: dist_buf_busy_limit) ->
8441 integer() >= 0
8442 erlang:system_info(Item :: dist_ctrl) ->
8444 {Node :: node(),
8445 ControllingEntity :: port() | pid()}
8446 Returns information about Erlang Distribution in the current
8448 system as specified by Item:
8449 creation:
8451 Returns the creation of the local node as an integer. The
8452 creation is changed when a node is restarted. The creation
8453 of a node is stored in process identifiers, port identi‐
8454 fiers, and references. This makes it (to some extent) possi‐
8455 ble to distinguish between identifiers from different incar‐
8456 nations of a node. The valid creations are integers in the
8457 range 1..3, but this will probably change in a future
8458 release. If the node is not alive, 0 is returned.
8459 delayed_node_table_gc:
8461 Returns the amount of time in seconds garbage collection of
8462 an entry in a node table is delayed. This limit can be set
8463 on startup by passing command-line flag +zdntgc to erl(1).
8464 For more information, see the documentation of the command-
8465 line flag.
8466 dist:
8468 Returns a binary containing a string of distribution infor‐
8469 mation formatted as in Erlang crash dumps. For more informa‐
8470 tion, see section How to interpret the Erlang crash dumps
8471 in the User's Guide.
8472 dist_buf_busy_limit:
8474 Returns the value of the distribution buffer busy limit in
8475 bytes. This limit can be set at startup by passing command-
8476 line flag +zdbbl to erl(1).
8477 dist_ctrl:
8479 Returns a list of tuples {Node, ControllingEntity}, one
8480 entry for each connected remote node. Node is the node name
8481 and ControllingEntity is the port or process identifier
8482 responsible for the communication to that node. More specif‐
8483 ically, ControllingEntity for nodes connected through TCP/IP
8484 (the normal case) is the socket used in communication with
8485 the specific node.
8486 erlang:system_info(Item :: build_type) ->
8488 opt | debug | purify | quantify | purecov |
8489 gcov | valgrind | gprof | lcnt | frmptr
8490 erlang:system_info(Item :: c_compiler_used) -> {atom(), term()}
8492 erlang:system_info(Item :: check_io) -> [term()]
8494 erlang:system_info(Item :: compat_rel) -> integer()
8496 erlang:system_info(Item :: debug_compiled) -> boolean()
8498 erlang:system_info(Item :: driver_version) -> string()
8500 erlang:system_info(Item :: dynamic_trace) ->
8502 none | dtrace | systemtap
8503 erlang:system_info(Item :: dynamic_trace_probes) -> boolean()
8505 erlang:system_info(Item :: info) -> binary()
8507 erlang:system_info(Item :: kernel_poll) -> boolean()
8509 erlang:system_info(Item :: loaded) -> binary()
8511 erlang:system_info(Item :: machine) -> string()
8513 erlang:system_info(Item :: modified_timing_level) ->
8515 integer() | undefined
8516 erlang:system_info(Item :: nif_version) -> string()
8518 erlang:system_info(Item :: otp_release) -> string()
8520 erlang:system_info(Item :: port_parallelism) -> boolean()
8522 erlang:system_info(Item :: system_architecture) -> string()
8524 erlang:system_info(Item :: system_logger) ->
8526 logger | undefined | pid()
8527 erlang:system_info(Item :: system_version) -> string()
8529 erlang:system_info(Item :: trace_control_word) ->
8531 integer() >= 0
8532 erlang:system_info(Item :: version) -> string()
8534 erlang:system_info(Item ::
8536 wordsize |
8537 {wordsize, internal} |
8538 {wordsize, external}) ->
8539 4 | 8
8540 Returns various information about the current system (emulator)
8542 as specified by Item:
8543 build_type:
8545 Returns an atom describing the build type of the runtime
8546 system. This is normally the atom opt for optimized. Other
8547 possible return values are debug, purify, quantify, purecov,
8548 gcov, valgrind, gprof, and lcnt. Possible return values can
8549 be added or removed at any time without prior notice.
8550 c_compiler_used:
8552 Returns a two-tuple describing the C compiler used when com‐
8553 piling the runtime system. The first element is an atom
8554 describing the name of the compiler, or undefined if
8555 unknown. The second element is a term describing the version
8556 of the compiler, or undefined if unknown.
8557 check_io:
8559 Returns a list containing miscellaneous information about
8560 the emulators internal I/O checking. Notice that the content
8561 of the returned list can vary between platforms and over
8562 time. It is only guaranteed that a list is returned.
8563 compat_rel:
8565 Returns the compatibility mode of the local node as an inte‐
8566 ger. The integer returned represents the Erlang/OTP release
8567 that the current emulator has been set to be backward com‐
8568 patible with. The compatibility mode can be configured at
8569 startup by using command-line flag +R in erl(1).
8570 debug_compiled:
8572 Returns true if the emulator has been debug-compiled, other‐
8573 wise false.
8574 driver_version:
8576 Returns a string containing the Erlang driver version used
8577 by the runtime system. It has the form "<major ver>.<minor
8578 ver>".
8579 dynamic_trace:
8581 Returns an atom describing the dynamic trace framework com‐
8582 piled into the virtual machine. It can be dtrace, systemtap,
8583 or none. For a commercial or standard build, it is always
8584 none. The other return values indicate a custom configura‐
8585 tion (for example, ./configure --with-dynamic-trace=dtrace).
8586 For more information about dynamic tracing, see dyntrace(3)
8587 manual page and the README.dtrace/README.systemtap files in
8588 the Erlang source code top directory.
8589 dynamic_trace_probes:
8591 Returns a boolean() indicating if dynamic trace probes
8592 (dtrace or systemtap) are built into the emulator. This can
8593 only be true if the virtual machine was built for dynamic
8594 tracing (that is, system_info(dynamic_trace) returns dtrace
8595 or systemtap).
8596 info:
8598 Returns a binary containing a string of miscellaneous system
8599 information formatted as in Erlang crash dumps. For more
8600 information, see section How to interpret the Erlang crash
8601 dumps in the User's Guide.
8602 kernel_poll:
8604 Returns true if the emulator uses some kind of kernel-poll
8605 implementation, otherwise false.
8606 loaded:
8608 Returns a binary containing a string of loaded module infor‐
8609 mation formatted as in Erlang crash dumps. For more informa‐
8610 tion, see section How to interpret the Erlang crash dumps in
8611 the User's Guide.
8612 machine:
8614 Returns a string containing the Erlang machine name.
8615 modified_timing_level:
8617 Returns the modified timing-level (an integer) if modified
8618 timing is enabled, otherwise undefined. For more information
8619 about modified timing, see command-line flag +T in erl(1)
8620 nif_version:
8622 Returns a string containing the version of the Erlang NIF
8623 interface used by the runtime system. It is on the form
8624 "<major ver>.<minor ver>".
8625 otp_release:
8627 Returns a string containing the OTP release number of the
8630 OTP release that the currently executing ERTS application is
8631 part of.
8632 As from Erlang/OTP 17, the OTP release number corresponds to
8634 the major OTP version number. No erlang:system_info() argu‐
8635 ment gives the exact OTP version. This is because the exact
8636 OTP version in the general case is difficult to determine.
8637 For more information, see the description of versions in
8638 System principles in System Documentation.
8639 port_parallelism:
8641 Returns the default port parallelism scheduling hint used.
8642 For more information, see command-line argument +spp in
8643 erl(1).
8644 system_architecture:
8646 Returns a string containing the processor and OS architec‐
8647 ture the emulator is built for.
8648 system_logger:
8650 Returns the current system_logger as set by erlang:sys‐
8651 tem_flag(system_logger, _).
8652 system_version:
8654 Returns a string containing version number and some impor‐
8655 tant properties, such as the number of schedulers.
8656 trace_control_word:
8658 Returns the value of the node trace control word. For more
8659 information, see function get_tcw in section Match Specifi‐
8660 cations in Erlang in the User's Guide.
8661 version:
8663 Returns a string containing the version number of the emula‐
8664 tor.
8665 wordsize:
8667 Same as {wordsize, internal}.
8668 {wordsize, internal}:
8670 Returns the size of Erlang term words in bytes as an inte‐
8671 ger, that is, 4 is returned on a 32-bit architecture, and 8
8672 is returned on a pure 64-bit architecture. On a halfword
8673 64-bit emulator, 4 is returned, as the Erlang terms are
8674 stored using a virtual word size of half the system word
8675 size.
8676 {wordsize, external}:
8678 Returns the true word size of the emulator, that is, the
8679 size of a pointer. The value is given in bytes as an inte‐
8680 ger. On a pure 32-bit architecture, 4 is returned. On both a
8681 half word and on a pure 64-bit architecture, 8 is returned.
8682 erlang:system_monitor() -> MonSettings
8684 Types:
8686 MonSettings = undefined | {MonitorPid, Options}
8688 MonitorPid = pid()
8689 Options = [system_monitor_option()]
8690 system_monitor_option() =
8691 busy_port | busy_dist_port |
8692 {long_gc, integer() >= 0} |
8693 {long_schedule, integer() >= 0} |
8694 {large_heap, integer() >= 0}
8695 Returns the current system monitoring settings set by
8697 erlang:system_monitor/2 as {MonitorPid, Options}, or undefined
8698 if no settings exist. The order of the options can be different
8699 from the one that was set.
8700 erlang:system_monitor(Arg) -> MonSettings
8702 Types:
8704 Arg = MonSettings = undefined | {MonitorPid, Options}
8706 MonitorPid = pid()
8707 Options = [system_monitor_option()]
8708 system_monitor_option() =
8709 busy_port | busy_dist_port |
8710 {long_gc, integer() >= 0} |
8711 {long_schedule, integer() >= 0} |
8712 {large_heap, integer() >= 0}
8713 When called with argument undefined, all system performance mon‐
8715 itoring settings are cleared.
8716 Calling the function with {MonitorPid, Options} as argument is
8718 the same as calling erlang:system_monitor(MonitorPid, Options).
8719 Returns the previous system monitor settings just like
8721 erlang:system_monitor/0.
8722 erlang:system_monitor(MonitorPid, Options) -> MonSettings
8724 Types:
8726 MonitorPid = pid()
8728 Options = [system_monitor_option()]
8729 MonSettings = undefined | {OldMonitorPid, OldOptions}
8730 OldMonitorPid = pid()
8731 OldOptions = [system_monitor_option()]
8732 system_monitor_option() =
8733 busy_port | busy_dist_port |
8734 {long_gc, integer() >= 0} |
8735 {long_schedule, integer() >= 0} |
8736 {large_heap, integer() >= 0}
8737 Sets the system performance monitoring options. MonitorPid is a
8739 local process identifier (pid) receiving system monitor mes‐
8740 sages. The second argument is a list of monitoring options:
8741 {long_gc, Time}:
8743 If a garbage collection in the system takes at least Time
8744 wall clock milliseconds, a message {monitor, GcPid, long_gc,
8745 Info} is sent to MonitorPid. GcPid is the pid that was
8746 garbage collected. Info is a list of two-element tuples
8747 describing the result of the garbage collection.
8748 One of the tuples is {timeout, GcTime}, where GcTime is the
8750 time for the garbage collection in milliseconds. The other
8751 tuples are tagged with heap_size, heap_block_size,
8752 stack_size, mbuf_size, old_heap_size, and
8753 old_heap_block_size. These tuples are explained in the
8754 description of trace message gc_minor_start (see
8755 erlang:trace/3). New tuples can be added, and the order of
8756 the tuples in the Info list can be changed at any time with‐
8757 out prior notice.
8758 {long_schedule, Time}:
8760 If a process or port in the system runs uninterrupted for at
8761 least Time wall clock milliseconds, a message {monitor,
8762 PidOrPort, long_schedule, Info} is sent to MonitorPid.
8763 PidOrPort is the process or port that was running. Info is a
8764 list of two-element tuples describing the event.
8765 If a pid(), the tuples {timeout, Millis}, {in, Location},
8767 and {out, Location} are present, where Location is either an
8768 MFA ({Module, Function, Arity}) describing the function
8769 where the process was scheduled in/out, or the atom unde‐
8770 fined.
8771 If a port(), the tuples {timeout, Millis} and {port_op,Op}
8773 are present. Op is one of proc_sig, timeout, input, output,
8774 event, or dist_cmd, depending on which driver callback was
8775 executing.
8776 proc_sig is an internal operation and is never to appear,
8778 while the others represent the corresponding driver call‐
8779 backs timeout, ready_input, ready_output, event, and outputv
8780 (when the port is used by distribution). Value Millis in
8781 tuple timeout informs about the uninterrupted execution time
8782 of the process or port, which always is equal to or higher
8783 than the Time value supplied when starting the trace. New
8784 tuples can be added to the Info list in a future release.
8785 The order of the tuples in the list can be changed at any
8786 time without prior notice.
8787 This can be used to detect problems with NIFs or drivers
8789 that take too long to execute. 1 ms is considered a good
8790 maximum time for a driver callback or a NIF. However, a
8791 time-sharing system is usually to consider everything < 100
8792 ms as "possible" and fairly "normal". However, longer sched‐
8793 ule times can indicate swapping or a misbehaving NIF/driver.
8794 Misbehaving NIFs and drivers can cause bad resource utiliza‐
8795 tion and bad overall system performance.
8796 {large_heap, Size}:
8798 If a garbage collection in the system results in the allo‐
8799 cated size of a heap being at least Size words, a message
8800 {monitor, GcPid, large_heap, Info} is sent to MonitorPid.
8801 GcPid and Info are the same as for long_gc earlier, except
8802 that the tuple tagged with timeout is not present.
8803 The monitor message is sent if the sum of the sizes of all
8805 memory blocks allocated for all heap generations after a
8806 garbage collection is equal to or higher than Size.
8807 When a process is killed by max_heap_size, it is killed
8809 before the garbage collection is complete and thus no large
8810 heap message is sent.
8811 busy_port:
8813 If a process in the system gets suspended because it sends
8814 to a busy port, a message {monitor, SusPid, busy_port, Port}
8815 is sent to MonitorPid. SusPid is the pid that got suspended
8816 when sending to Port.
8817 busy_dist_port:
8819 If a process in the system gets suspended because it sends
8820 to a process on a remote node whose inter-node communication
8821 was handled by a busy port, a message {monitor, SusPid,
8822 busy_dist_port, Port} is sent to MonitorPid. SusPid is the
8823 pid that got suspended when sending through the inter-node
8824 communication port Port.
8825 Returns the previous system monitor settings just like
8827 erlang:system_monitor/0.
8828 The arguments to system_monitor/2 specifies how all system moni‐
8830 toring on the node should be done, not how it should be changed.
8831 This means only one process at a time (MonitorPid) can be the
8832 receiver of system monitor messages. Also, the way to clear a
8833 specific monitor option is to not include it in the list
8834 Options. All system monitoring will, however, be cleared if the
8835 process identified by MonitorPid terminates.
8836 There are no special option values (like zero) to clear an
8838 option. Some of the options have a unspecified minimum value.
8839 Lower values will be adjusted to the minimum value. For example,
8840 it is currently not possible to monitor all garbage collections
8841 with {long_gc, 0}.
8842 Note:
8844 If a monitoring process gets so large that it itself starts to
8845 cause system monitor messages when garbage collecting, the mes‐
8846 sages enlarge the process message queue and probably make the
8847 problem worse.
8848 Keep the monitoring process neat and do not set the system moni‐
8850 tor limits too tight.
8851 Failures:
8854 badarg:
8856 If MonitorPid does not exist.
8857 badarg:
8859 If MonitorPid is not a local process.
8860 erlang:system_profile() -> ProfilerSettings
8862 Types:
8864 ProfilerSettings = undefined | {ProfilerPid, Options}
8866 ProfilerPid = pid() | port()
8867 Options = [system_profile_option()]
8868 system_profile_option() =
8869 exclusive | runnable_ports | runnable_procs | scheduler |
8870 timestamp | monotonic_timestamp | strict_monotonic_timestamp
8871 Returns the current system profiling settings set by erlang:sys‐
8873 tem_profile/2 as {ProfilerPid, Options}, or undefined if there
8874 are no settings. The order of the options can be different from
8875 the one that was set.
8876 erlang:system_profile(ProfilerPid, Options) -> ProfilerSettings
8878 Types:
8880 ProfilerPid = pid() | port() | undefined
8882 Options = [system_profile_option()]
8883 ProfilerSettings =
8884 undefined | {pid() | port(), [system_profile_option()]}
8885 system_profile_option() =
8886 exclusive | runnable_ports | runnable_procs | scheduler |
8887 timestamp | monotonic_timestamp | strict_monotonic_timestamp
8888 Sets system profiler options. ProfilerPid is a local process
8890 identifier (pid) or port receiving profiling messages. The
8891 receiver is excluded from all profiling. The second argument is
8892 a list of profiling options:
8893 exclusive:
8895 If a synchronous call to a port from a process is done, the
8896 calling process is considered not runnable during the call
8897 runtime to the port. The calling process is notified as
8898 inactive, and later active when the port callback returns.
8899 monotonic_timestamp:
8901 Time stamps in profile messages use Erlang monotonic time.
8902 The time stamp (Ts) has the same format and value as pro‐
8903 duced by erlang:monotonic_time(nanosecond).
8904 runnable_procs:
8906 If a process is put into or removed from the run queue, a
8907 message, {profile, Pid, State, Mfa, Ts}, is sent to Profil‐
8908 erPid. Running processes that are reinserted into the run
8909 queue after having been pre-empted do not trigger this mes‐
8910 sage.
8911 runnable_ports:
8913 If a port is put into or removed from the run queue, a mes‐
8914 sage, {profile, Port, State, 0, Ts}, is sent to ProfilerPid.
8915 scheduler:
8917 If a scheduler is put to sleep or awoken, a message, {pro‐
8918 file, scheduler, Id, State, NoScheds, Ts}, is sent to Pro‐
8919 filerPid.
8920 strict_monotonic_timestamp:
8922 Time stamps in profile messages consist of Erlang monotonic
8923 time and a monotonically increasing integer. The time stamp
8924 (Ts) has the same format and value as produced by
8925 {erlang:monotonic_time(nanosecond), erlang:unique_inte‐
8926 ger([monotonic])}.
8927 timestamp:
8929 Time stamps in profile messages include a time stamp (Ts)
8930 that has the same form as returned by erlang:now(). This is
8931 also the default if no time stamp flag is specified. If
8932 cpu_timestamp has been enabled through erlang:trace/3, this
8933 also effects the time stamp produced in profiling messages
8934 when flag timestamp is enabled.
8935 Note:
8937 erlang:system_profile behavior can change in a future release.
8938 erlang:system_time() -> integer()
8941 Returns current Erlang system time in native time unit.
8943 Calling erlang:system_time() is equivalent to erlang:mono‐
8945 tonic_time() + erlang:time_offset().
8946 Note:
8948 This time is not a monotonically increasing time in the general
8949 case. For more information, see the documentation of time warp
8950 modes in the User's Guide.
8951 erlang:system_time(Unit) -> integer()
8954 Types:
8956 Unit = time_unit()
8958 Returns current Erlang system time converted into the Unit
8960 passed as argument.
8961 Calling erlang:system_time(Unit) is equivalent to erlang:con‐
8963 vert_time_unit(erlang:system_time(), native, Unit).
8964 Note:
8966 This time is not a monotonically increasing time in the general
8967 case. For more information, see the documentation of time warp
8968 modes in the User's Guide.
8969 term_to_binary(Term) -> ext_binary()
8972 Types:
8974 Term = term()
8976 Returns a binary data object that is the result of encoding Term
8978 according to the Erlang external term format.
8979 This can be used for various purposes, for example, writing a
8981 term to a file in an efficient way, or sending an Erlang term to
8982 some type of communications channel not supported by distributed
8983 Erlang.
8984 > Bin = term_to_binary(hello).
8986 <<131,100,0,5,104,101,108,108,111>>
8987 > hello = binary_to_term(Bin).
8988 hello
8989 See also binary_to_term/1.
8992 Note:
8994 There is no guarantee that this function will return the same
8995 encoded representation for the same term.
8996 term_to_binary(Term, Options) -> ext_binary()
8999 Types:
9001 Term = term()
9003 Options =
9004 [compressed |
9005 {compressed, Level :: 0..9} |
9006 {minor_version, Version :: 0..2}]
9007 Returns a binary data object that is the result of encoding Term
9009 according to the Erlang external term format.
9010 If option compressed is provided, the external term format is
9012 compressed. The compressed format is automatically recognized by
9013 binary_to_term/1 as from Erlang/OTP R7B.
9014 A compression level can be specified by giving option {com‐
9016 pressed, Level}. Level is an integer with range 0..9, where:
9017 * 0 - No compression is done (it is the same as giving no com‐
9019 pressed option).
9020 * 1 - Takes least time but may not compress as well as the
9022 higher levels.
9023 * 6 - Default level when option compressed is provided.
9025 * 9 - Takes most time and tries to produce a smaller result.
9027 Notice "tries" in the preceding sentence; depending on the
9028 input term, level 9 compression either does or does not pro‐
9029 duce a smaller result than level 1 compression.
9030 Option {minor_version, Version} can be used to control some
9032 encoding details. This option was introduced in Erlang/OTP
9033 R11B-4. The valid values for Version are:
9034 0:
9036 Floats are encoded using a textual representation. This
9037 option is useful to ensure that releases before Erlang/OTP
9038 R11B-4 can decode resulting binary.
9039 This version encode atoms that can be represented by a
9041 latin1 string using latin1 encoding while only atoms that
9042 cannot be represented by latin1 are encoded using utf8.
9043 1:
9045 This is as of Erlang/OTP 17.0 the default. It forces any
9046 floats in the term to be encoded in a more space-efficient
9047 and exact way (namely in the 64-bit IEEE format, rather than
9048 converted to a textual representation). As from Erlang/OTP
9049 R11B-4, binary_to_term/1 can decode this representation.
9050 This version encode atoms that can be represented by a
9052 latin1 string using latin1 encoding while only atoms that
9053 cannot be represented by latin1 are encoded using utf8.
9054 2:
9056 Drops usage of the latin1 atom encoding and unconditionally
9057 use utf8 encoding for all atoms. This will be changed to the
9058 default in a future major release of Erlang/OTP. Erlang/OTP
9059 systems as of R16B can decode this representation.
9060 See also binary_to_term/1.
9062 throw(Any) -> no_return()
9064 Types:
9066 Any = term()
9068 A non-local return from a function. If evaluated within a catch,
9070 catch returns value Any. Example:
9071 > catch throw({hello, there}).
9073 {hello,there}
9074 Failure: nocatch if not evaluated within a catch.
9076 time() -> Time
9078 Types:
9080 Time = calendar:time()
9082 Returns the current time as {Hour, Minute, Second}.
9084 The time zone and Daylight Saving Time correction depend on the
9086 underlying OS. Example:
9087 > time().
9089 {9,42,44}
9090 erlang:time_offset() -> integer()
9092 Returns the current time offset between Erlang monotonic time
9094 and Erlang system time in native time unit. Current time offset
9095 added to an Erlang monotonic time gives corresponding Erlang
9096 system time.
9097 The time offset may or may not change during operation depending
9099 on the time warp mode used.
9100 Note:
9102 A change in time offset can be observed at slightly different
9103 points in time by different processes.
9104 If the runtime system is in multi-time warp mode, the time off‐
9106 set is changed when the runtime system detects that the OS sys‐
9107 tem time has changed. The runtime system will, however, not
9108 detect this immediately when it occurs. A task checking the time
9109 offset is scheduled to execute at least once a minute; so, under
9110 normal operation this is to be detected within a minute, but
9111 during heavy load it can take longer time.
9112 erlang:time_offset(Unit) -> integer()
9115 Types:
9117 Unit = time_unit()
9119 Returns the current time offset between Erlang monotonic time
9121 and Erlang system time converted into the Unit passed as argu‐
9122 ment.
9123 Same as calling erlang:convert_time_unit(erlang:time_offset(),
9125 native, Unit) however optimized for commonly used Units.
9126 erlang:timestamp() -> Timestamp
9128 Types:
9130 Timestamp = timestamp()
9132 timestamp() =
9133 {MegaSecs :: integer() >= 0,
9134 Secs :: integer() >= 0,
9135 MicroSecs :: integer() >= 0}
9136 Returns current Erlang system time on the format {MegaSecs,
9138 Secs, MicroSecs}. This format is the same as os:timestamp/0 and
9139 the deprecated erlang:now/0 use. The reason for the existence of
9140 erlang:timestamp() is purely to simplify use for existing code
9141 that assumes this time stamp format. Current Erlang system time
9142 can more efficiently be retrieved in the time unit of your
9143 choice using erlang:system_time/1.
9144 The erlang:timestamp() BIF is equivalent to:
9146 timestamp() ->
9148 ErlangSystemTime = erlang:system_time(microsecond),
9149 MegaSecs = ErlangSystemTime div 1000000000000,
9150 Secs = ErlangSystemTime div 1000000 - MegaSecs*1000000,
9151 MicroSecs = ErlangSystemTime rem 1000000,
9152 {MegaSecs, Secs, MicroSecs}.
9153 It, however, uses a native implementation that does not build
9155 garbage on the heap and with slightly better performance.
9156 Note:
9158 This time is not a monotonically increasing time in the general
9159 case. For more information, see the documentation of time warp
9160 modes in the User's Guide.
9161 tl(List) -> term()
9164 Types:
9166 List = [term(), ...]
9168 Returns the tail of List, that is, the list minus the first ele‐
9170 ment, for example:
9171 > tl([geesties, guilies, beasties]).
9173 [guilies, beasties]
9174 Allowed in guard tests.
9176 Failure: badarg if List is the empty list [].
9178 erlang:trace(PidPortSpec, How, FlagList) -> integer()
9180 Types:
9182 PidPortSpec =
9184 pid() |
9185 port() |
9186 all | processes | ports | existing | existing_processes |
9187 existing_ports | new | new_processes | new_ports
9188 How = boolean()
9189 FlagList = [trace_flag()]
9190 trace_flag() =
9191 all | send | 'receive' | procs | ports | call | arity |
9192 return_to | silent | running | exiting | running_procs |
9193 running_ports | garbage_collection | timestamp |
9194 cpu_timestamp | monotonic_timestamp |
9195 strict_monotonic_timestamp | set_on_spawn |
9196 set_on_first_spawn | set_on_link | set_on_first_link |
9197 {tracer, pid() | port()} |
9198 {tracer, module(), term()}
9199 Turns on (if How == true) or off (if How == false) the trace
9201 flags in FlagList for the process or processes represented by
9202 PidPortSpec.
9203 PidPortSpec is either a process identifier (pid) for a local
9205 process, a port identifier, or one of the following atoms:
9206 all:
9208 All currently existing processes and ports and all that will
9209 be created in the future.
9210 processes:
9212 All currently existing processes and all that will be cre‐
9213 ated in the future.
9214 ports:
9216 All currently existing ports and all that will be created in
9217 the future.
9218 existing:
9220 All currently existing processes and ports.
9221 existing_processes:
9223 All currently existing processes.
9224 existing_ports:
9226 All currently existing ports.
9227 new:
9229 All processes and ports that will be created in the future.
9230 new_processes:
9232 All processes that will be created in the future.
9233 new_ports:
9235 All ports that will be created in the future.
9236 FlagList can contain any number of the following flags (the
9238 "message tags" refers to the list of trace messages):
9239 all:
9241 Sets all trace flags except tracer and cpu_timestamp, which
9242 are in their nature different than the others.
9243 send:
9245 Traces sending of messages.
9246 Message tags: send and send_to_non_existing_process.
9248 'receive':
9250 Traces receiving of messages.
9251 Message tags: 'receive'.
9253 call:
9255 Traces certain function calls. Specify which function calls
9256 to trace by calling erlang:trace_pattern/3.
9257 Message tags: call and return_from.
9259 silent:
9261 Used with the call trace flag. The call, return_from, and
9262 return_to trace messages are inhibited if this flag is set,
9263 but they are executed as normal if there are match specifi‐
9264 cations.
9265 Silent mode is inhibited by executing erlang:trace(_, false,
9267 [silent|_]), or by a match specification executing the func‐
9268 tion {silent, false}.
9269 The silent trace flag facilitates setting up a trace on many
9271 or even all processes in the system. The trace can then be
9272 activated and deactivated using the match specification
9273 function {silent,Bool}, giving a high degree of control of
9274 which functions with which arguments that trigger the trace.
9275 Message tags: call, return_from, and return_to. Or rather,
9277 the absence of.
9278 return_to:
9280 Used with the call trace flag. Traces the return from a
9281 traced function back to its caller. Only works for functions
9282 traced with option local to erlang:trace_pattern/3.
9283 The semantics is that a trace message is sent when a call
9285 traced function returns, that is, when a chain of tail
9286 recursive calls ends. Only one trace message is sent per
9287 chain of tail recursive calls, so the properties of tail
9288 recursiveness for function calls are kept while tracing with
9289 this flag. Using call and return_to trace together makes it
9290 possible to know exactly in which function a process exe‐
9291 cutes at any time.
9292 To get trace messages containing return values from func‐
9294 tions, use the {return_trace} match specification action
9295 instead.
9296 Message tags: return_to.
9298 procs:
9300 Traces process-related events.
9301 Message tags: spawn, spawned, exit, register, unregister,
9303 link, unlink, getting_linked, and getting_unlinked.
9304 ports:
9306 Traces port-related events.
9307 Message tags: open, closed, register, unregister, get‐
9309 ting_linked, and getting_unlinked.
9310 running:
9312 Traces scheduling of processes.
9313 Message tags: in and out.
9315 exiting:
9317 Traces scheduling of exiting processes.
9318 Message tags: in_exiting, out_exiting, and out_exited.
9320 running_procs:
9322 Traces scheduling of processes just like running. However,
9323 this option also includes schedule events when the process
9324 executes within the context of a port without being sched‐
9325 uled out itself.
9326 Message tags: in and out.
9328 running_ports:
9330 Traces scheduling of ports.
9331 Message tags: in and out.
9333 garbage_collection:
9335 Traces garbage collections of processes.
9336 Message tags: gc_minor_start, gc_max_heap_size, and
9338 gc_minor_end.
9339 timestamp:
9341 Includes a time stamp in all trace messages. The time stamp
9342 (Ts) has the same form as returned by erlang:now().
9343 cpu_timestamp:
9345 A global trace flag for the Erlang node that makes all trace
9346 time stamps using flag timestamp to be in CPU time, not wall
9347 clock time. That is, cpu_timestamp is not be used if mono‐
9348 tonic_timestamp or strict_monotonic_timestamp is enabled.
9349 Only allowed with PidPortSpec==all. If the host machine OS
9350 does not support high-resolution CPU time measurements,
9351 trace/3 exits with badarg. Notice that most OS do not syn‐
9352 chronize this value across cores, so be prepared that time
9353 can seem to go backwards when using this option.
9354 monotonic_timestamp:
9356 Includes an Erlang monotonic time time stamp in all trace
9357 messages. The time stamp (Ts) has the same format and value
9358 as produced by erlang:monotonic_time(nanosecond). This flag
9359 overrides flag cpu_timestamp.
9360 strict_monotonic_timestamp:
9362 Includes an time stamp consisting of Erlang monotonic time
9363 and a monotonically increasing integer in all trace mes‐
9364 sages. The time stamp (Ts) has the same format and value as
9365 produced by { erlang:monotonic_time(nanosecond),
9366 erlang:unique_integer([monotonic])}. This flag overrides
9367 flag cpu_timestamp.
9368 arity:
9370 Used with the call trace flag. {M, F, Arity} is specified
9371 instead of {M, F, Args} in call trace messages.
9372 set_on_spawn:
9374 Makes any process created by a traced process inherit its
9375 trace flags, including flag set_on_spawn.
9376 set_on_first_spawn:
9378 Makes the first process created by a traced process inherit
9379 its trace flags, excluding flag set_on_first_spawn.
9380 set_on_link:
9382 Makes any process linked by a traced process inherit its
9383 trace flags, including flag set_on_link.
9384 set_on_first_link:
9386 Makes the first process linked to by a traced process
9387 inherit its trace flags, excluding flag set_on_first_link.
9388 {tracer, Tracer}:
9390 Specifies where to send the trace messages. Tracer must be
9391 the process identifier of a local process or the port iden‐
9392 tifier of a local port.
9393 {tracer, TracerModule, TracerState}:
9395 Specifies that a tracer module is to be called instead of
9396 sending a trace message. The tracer module can then ignore
9397 or change the trace message. For more details on how to
9398 write a tracer module, see erl_tracer(3).
9399 If no tracer is specified, the calling process receives all the
9401 trace messages.
9402 The effect of combining set_on_first_link with set_on_link is
9404 the same as set_on_first_link alone. Likewise for set_on_spawn
9405 and set_on_first_spawn.
9406 The tracing process receives the trace messages described in the
9408 following list. Pid is the process identifier of the traced
9409 process in which the traced event has occurred. The third tuple
9410 element is the message tag.
9411 If flag timestamp, strict_monotonic_timestamp, or mono‐
9413 tonic_timestamp is specified, the first tuple element is
9414 trace_ts instead, and the time stamp is added as an extra ele‐
9415 ment last in the message tuple. If multiple time stamp flags are
9416 passed, timestamp has precedence over strict_monotonic_time‐
9417 stamp, which in turn has precedence over monotonic_timestamp.
9418 All time stamp flags are remembered, so if two are passed and
9419 the one with highest precedence later is disabled, the other one
9420 becomes active.
9421 If a match specification (applicable only for call, send and
9423 'receive' tracing) contains a {message} action function with a
9424 non-boolean value, that value is added as an extra element to
9425 the message tuple either in the last position or before the
9426 timestamp (if it is present).
9427 Trace messages:
9429 {trace, PidPort, send, Msg, To}:
9431 When PidPort sends message Msg to process To.
9432 {trace, PidPort, send_to_non_existing_process, Msg, To}:
9434 When PidPort sends message Msg to the non-existing process
9435 To.
9436 {trace, PidPort, 'receive', Msg}:
9438 When PidPort receives message Msg. If Msg is set to time-
9439 out, a receive statement can have timed out, or the process
9440 received a message with the payload timeout.
9441 {trace, Pid, call, {M, F, Args}}:
9443 When Pid calls a traced function. The return values of calls
9444 are never supplied, only the call and its arguments.
9445 Trace flag arity can be used to change the contents of this
9447 message, so that Arity is specified instead of Args.
9448 {trace, Pid, return_to, {M, F, Arity}}:
9450 When Pid returns to the specified function. This trace mes‐
9451 sage is sent if both the flags call and return_to are set,
9452 and the function is set to be traced on local function
9453 calls. The message is only sent when returning from a chain
9454 of tail recursive function calls, where at least one call
9455 generated a call trace message (that is, the functions match
9456 specification matched, and {message, false} was not an
9457 action).
9458 {trace, Pid, return_from, {M, F, Arity}, ReturnValue}:
9460 When Pid returns from the specified function. This trace
9461 message is sent if flag call is set, and the function has a
9462 match specification with a return_trace or exception_trace
9463 action.
9464 {trace, Pid, exception_from, {M, F, Arity}, {Class, Value}}:
9466 When Pid exits from the specified function because of an
9467 exception. This trace message is sent if flag call is set,
9468 and the function has a match specification with an excep‐
9469 tion_trace action.
9470 {trace, Pid, spawn, Pid2, {M, F, Args}}:
9472 When Pid spawns a new process Pid2 with the specified func‐
9473 tion call as entry point.
9474 Args is supposed to be the argument list, but can be any
9476 term if the spawn is erroneous.
9477 {trace, Pid, spawned, Pid2, {M, F, Args}}:
9479 When Pid is spawned by process Pid2 with the specified func‐
9480 tion call as entry point.
9481 Args is supposed to be the argument list, but can be any
9483 term if the spawn is erroneous.
9484 {trace, Pid, exit, Reason}:
9486 When Pid exits with reason Reason.
9487 {trace, PidPort, register, RegName}:
9489 When PidPort gets the name RegName registered.
9490 {trace, PidPort, unregister, RegName}:
9492 When PidPort gets the name RegName unregistered. This is
9493 done automatically when a registered process or port exits.
9494 {trace, Pid, link, Pid2}:
9496 When Pid links to a process Pid2.
9497 {trace, Pid, unlink, Pid2}:
9499 When Pid removes the link from a process Pid2.
9500 {trace, PidPort, getting_linked, Pid2}:
9502 When PidPort gets linked to a process Pid2.
9503 {trace, PidPort, getting_unlinked, Pid2}:
9505 When PidPort gets unlinked from a process Pid2.
9506 {trace, Pid, exit, Reason}:
9508 When Pid exits with reason Reason.
9509 {trace, Port, open, Pid, Driver}:
9511 When Pid opens a new port Port with the running Driver.
9512 Driver is the name of the driver as an atom.
9514 {trace, Port, closed, Reason}:
9516 When Port closes with Reason.
9517 {trace, Pid, in | in_exiting, {M, F, Arity} | 0}:
9519 When Pid is scheduled to run. The process runs in function
9520 {M, F, Arity}. On some rare occasions, the current function
9521 cannot be determined, then the last element is 0.
9522 {trace, Pid, out | out_exiting | out_exited, {M, F, Arity} |
9524 0}:
9525 When Pid is scheduled out. The process was running in func‐
9526 tion {M, F, Arity}. On some rare occasions, the current
9527 function cannot be determined, then the last element is 0.
9528 {trace, Port, in, Command | 0}:
9530 When Port is scheduled to run. Command is the first thing
9531 the port will execute, it can however run several commands
9532 before being scheduled out. On some rare occasions, the cur‐
9533 rent function cannot be determined, then the last element is
9534 0.
9535 The possible commands are call, close, command, connect,
9537 control, flush, info, link, open, and unlink.
9538 {trace, Port, out, Command | 0}:
9540 When Port is scheduled out. The last command run was Com‐
9541 mand. On some rare occasions, the current function cannot be
9542 determined, then the last element is 0. Command can contain
9543 the same commands as in
9544 {trace, Pid, gc_minor_start, Info}:
9546 Sent when a young garbage collection is about to be started.
9549 Info is a list of two-element tuples, where the first ele‐
9550 ment is a key, and the second is the value. Do not depend on
9551 any order of the tuples. The following keys are defined:
9552 heap_size:
9554 The size of the used part of the heap.
9555 heap_block_size:
9557 The size of the memory block used for storing the heap and
9558 the stack.
9559 old_heap_size:
9561 The size of the used part of the old heap.
9562 old_heap_block_size:
9564 The size of the memory block used for storing the old
9565 heap.
9566 stack_size:
9568 The size of the stack.
9569 recent_size:
9571 The size of the data that survived the previous garbage
9572 collection.
9573 mbuf_size:
9575 The combined size of message buffers associated with the
9576 process.
9577 bin_vheap_size:
9579 The total size of unique off-heap binaries referenced from
9580 the process heap.
9581 bin_vheap_block_size:
9583 The total size of binaries allowed in the virtual heap in
9584 the process before doing a garbage collection.
9585 bin_old_vheap_size:
9587 The total size of unique off-heap binaries referenced from
9588 the process old heap.
9589 bin_old_vheap_block_size:
9591 The total size of binaries allowed in the virtual old heap
9592 in the process before doing a garbage collection.
9593 All sizes are in words.
9595 {trace, Pid, gc_max_heap_size, Info}:
9597 Sent when the max_heap_size is reached during garbage col‐
9598 lection. Info contains the same kind of list as in message
9599 gc_start, but the sizes reflect the sizes that triggered
9600 max_heap_size to be reached.
9601 {trace, Pid, gc_minor_end, Info}:
9603 Sent when young garbage collection is finished. Info con‐
9604 tains the same kind of list as in message gc_minor_start,
9605 but the sizes reflect the new sizes after garbage collec‐
9606 tion.
9607 {trace, Pid, gc_major_start, Info}:
9609 Sent when fullsweep garbage collection is about to be
9610 started. Info contains the same kind of list as in message
9611 gc_minor_start.
9612 {trace, Pid, gc_major_end, Info}:
9614 Sent when fullsweep garbage collection is finished. Info
9615 contains the same kind of list as in message gc_minor_start,
9616 but the sizes reflect the new sizes after a fullsweep
9617 garbage collection.
9618 If the tracing process/port dies or the tracer module returns
9620 remove, the flags are silently removed.
9621 Each process can only be traced by one tracer. Therefore,
9623 attempts to trace an already traced process fail.
9624 Returns a number indicating the number of processes that matched
9626 PidPortSpec. If PidPortSpec is a process identifier, the return
9627 value is 1. If PidPortSpec is all or existing, the return value
9628 is the number of processes running. If PidPortSpec is new, the
9629 return value is 0.
9630 Failure: badarg if the specified arguments are not supported.
9632 For example, cpu_timestamp is not supported on all platforms.
9633 erlang:trace_delivered(Tracee) -> Ref
9635 Types:
9637 Tracee = pid() | all
9639 Ref = reference()
9640 The delivery of trace messages (generated by erlang:trace/3,
9642 seq_trace(3), or erlang:system_profile/2) is dislocated on the
9643 time-line compared to other events in the system. If you know
9644 that Tracee has passed some specific point in its execution, and
9645 you want to know when at least all trace messages corresponding
9646 to events up to this point have reached the tracer, use
9647 erlang:trace_delivered(Tracee).
9648 When it is guaranteed that all trace messages are delivered to
9650 the tracer up to the point that Tracee reached at the time of
9651 the call to erlang:trace_delivered(Tracee), then a {trace_deliv‐
9652 ered, Tracee, Ref} message is sent to the caller of
9653 erlang:trace_delivered(Tracee) .
9654 Notice that message trace_delivered does not imply that trace
9656 messages have been delivered. Instead it implies that all trace
9657 messages that are to be delivered have been delivered. It is not
9658 an error if Tracee is not, and has not been traced by someone,
9659 but if this is the case, no trace messages have been delivered
9660 when the trace_delivered message arrives.
9661 Notice that Tracee must refer to a process currently or previ‐
9663 ously existing on the same node as the caller of
9664 erlang:trace_delivered(Tracee) resides on. The special Tracee
9665 atom all denotes all processes that currently are traced in the
9666 node.
9667 When used together with a Tracer Module, any message sent in
9669 the trace callback is guaranteed to have reached its recipient
9670 before the trace_delivered message is sent.
9671 Example: Process A is Tracee, port B is tracer, and process C is
9673 the port owner of B. C wants to close B when A exits. To ensure
9674 that the trace is not truncated, C can call erlang:trace_deliv‐
9675 ered(A) when A exits, and wait for message {trace_delivered, A,
9676 Ref} before closing B.
9677 Failure: badarg if Tracee does not refer to a process (dead or
9679 alive) on the same node as the caller of erlang:trace_deliv‐
9680 ered(Tracee) resides on.
9681 erlang:trace_info(PidPortFuncEvent, Item) -> Res
9683 Types:
9685 PidPortFuncEvent =
9687 pid() |
9688 port() |
9689 new | new_processes | new_ports |
9690 {Module, Function, Arity} |
9691 on_load | send | 'receive'
9692 Module = module()
9693 Function = atom()
9694 Arity = arity()
9695 Item =
9696 flags | tracer | traced | match_spec | meta |
9697 meta_match_spec | call_count | call_time | all
9698 Res = trace_info_return()
9699 trace_info_return() =
9700 undefined |
9701 {flags, [trace_info_flag()]} |
9702 {tracer, pid() | port() | []} |
9703 {tracer, module(), term()} |
9704 trace_info_item_result() |
9705 {all, [trace_info_item_result()] | false | undefined}
9706 trace_info_item_result() =
9707 {traced, global | local | false | undefined} |
9708 {match_spec, trace_match_spec() | false | undefined} |
9709 {meta, pid() | port() | false | undefined | []} |
9710 {meta, module(), term()} |
9711 {meta_match_spec, trace_match_spec() | false | undefined} |
9712 {call_count, integer() >= 0 | boolean() | undefined} |
9713 {call_time,
9714 [{pid(),
9715 integer() >= 0,
9716 integer() >= 0,
9717 integer() >= 0}] |
9718 boolean() |
9719 undefined}
9720 trace_info_flag() =
9721 send | 'receive' | set_on_spawn | call | return_to | procs |
9722 set_on_first_spawn | set_on_link | running |
9723 garbage_collection | timestamp | monotonic_timestamp |
9724 strict_monotonic_timestamp | arity
9725 trace_match_spec() =
9726 [{[term()] | '_' | match_variable(), [term()], [term()]}]
9727 match_variable() = atom()
9728 Approximation of '$1' | '$2' | '$3' | ...
9729 Returns trace information about a port, process, function, or
9731 event.
9732 To get information about a port or process, PidPortFuncEvent is
9734 to be a process identifier (pid), port identifier, or one of the
9735 atoms new, new_processes, or new_ports. The atom new or new_pro‐
9736 cesses means that the default trace state for processes to be
9737 created is returned. The atom new_ports means that the default
9738 trace state for ports to be created is returned.
9739 Valid Items for ports and processes:
9741 flags:
9743 Returns a list of atoms indicating what kind of traces is
9744 enabled for the process. The list is empty if no traces are
9745 enabled, and one or more of the followings atoms if traces
9746 are enabled: send, 'receive', set_on_spawn, call, return_to,
9747 procs, ports, set_on_first_spawn, set_on_link, running, run‐
9748 ning_procs, running_ports, silent, exiting, monotonic_time‐
9749 stamp, strict_monotonic_timestamp, garbage_collection, time‐
9750 stamp, and arity. The order is arbitrary.
9751 tracer:
9753 Returns the identifier for process, port, or a tuple con‐
9754 taining the tracer module and tracer state tracing this
9755 process. If this process is not traced, the return value is
9756 [].
9757 To get information about a function, PidPortFuncEvent is to be
9759 the three-element tuple {Module, Function, Arity} or the atom
9760 on_load. No wildcards are allowed. Returns undefined if the
9761 function does not exist, or false if the function is not traced.
9762 If PidPortFuncEvent is on_load, the information returned refers
9763 to the default value for code that will be loaded.
9764 Valid Items for functions:
9766 traced:
9768 Returns global if this function is traced on global function
9769 calls, local if this function is traced on local function
9770 calls (that is, local and global function calls), and false
9771 if local or global function calls are not traced.
9772 match_spec:
9774 Returns the match specification for this function, if it has
9775 one. If the function is locally or globally traced but has
9776 no match specification defined, the returned value is [].
9777 meta:
9779 Returns the meta-trace tracer process, port, or trace module
9780 for this function, if it has one. If the function is not
9781 meta-traced, the returned value is false. If the function is
9782 meta-traced but has once detected that the tracer process is
9783 invalid, the returned value is [].
9784 meta_match_spec:
9786 Returns the meta-trace match specification for this func‐
9787 tion, if it has one. If the function is meta-traced but has
9788 no match specification defined, the returned value is [].
9789 call_count:
9791 Returns the call count value for this function or true for
9792 the pseudo function on_load if call count tracing is active.
9793 Otherwise false is returned.
9794 See also erlang:trace_pattern/3.
9796 call_time:
9798 Returns the call time values for this function or true for
9799 the pseudo function on_load if call time tracing is active.
9800 Otherwise false is returned. The call time values returned,
9801 [{Pid, Count, S, Us}], is a list of each process that exe‐
9802 cuted the function and its specific counters.
9803 See also erlang:trace_pattern/3.
9805 all:
9807 Returns a list containing the {Item, Value} tuples for all
9808 other items, or returns false if no tracing is active for
9809 this function.
9810 To get information about an event, PidPortFuncEvent is to be one
9812 of the atoms send or 'receive'.
9813 One valid Item for events exists:
9815 match_spec:
9817 Returns the match specification for this event, if it has
9818 one, or true if no match specification has been set.
9819 The return value is {Item, Value}, where Value is the requested
9821 information as described earlier. If a pid for a dead process
9822 was specified, or the name of a non-existing function, Value is
9823 undefined.
9824 erlang:trace_pattern(MFA, MatchSpec) -> integer() >= 0
9826 Types:
9828 MFA = trace_pattern_mfa() | send | 'receive'
9830 MatchSpec =
9831 (MatchSpecList :: trace_match_spec()) |
9832 boolean() |
9833 restart | pause
9834 trace_pattern_mfa() = {atom(), atom(), arity() | '_'} | on_load
9835 trace_match_spec() =
9836 [{[term()] | '_' | match_variable(), [term()], [term()]}]
9837 match_variable() = atom()
9838 Approximation of '$1' | '$2' | '$3' | ...
9839 The same as erlang:trace_pattern(Event, MatchSpec, []), retained
9841 for backward compatibility.
9842 erlang:trace_pattern(MFA :: send, MatchSpec, FlagList :: []) ->
9844 integer() >= 0
9845 Types:
9847 MatchSpec = (MatchSpecList :: trace_match_spec()) | boolean()
9849 trace_match_spec() =
9850 [{[term()] | '_' | match_variable(), [term()], [term()]}]
9851 match_variable() = atom()
9852 Approximation of '$1' | '$2' | '$3' | ...
9853 Sets trace pattern for message sending. Must be combined with
9855 erlang:trace/3 to set the send trace flag for one or more pro‐
9856 cesses. By default all messages sent from send traced processes
9857 are traced. To limit traced send events based on the message
9858 content, the sender and/or the receiver, use erlang:trace_pat‐
9859 tern/3.
9860 Argument MatchSpec can take the following forms:
9862 MatchSpecList:
9864 A list of match specifications. The matching is done on the
9865 list [Receiver, Msg]. Receiver is the process or port iden‐
9866 tity of the receiver and Msg is the message term. The pid of
9867 the sending process can be accessed with the guard function
9868 self/0. An empty list is the same as true. For more informa‐
9869 tion, see section Match Specifications in Erlang in the
9870 User's Guide.
9871 true:
9873 Enables tracing for all sent messages (from send traced pro‐
9874 cesses). Any match specification is removed. This is the
9875 default.
9876 false:
9878 Disables tracing for all sent messages. Any match specifica‐
9879 tion is removed.
9880 Argument FlagList must be [] for send tracing.
9882 The return value is always 1.
9884 Examples:
9886 Only trace messages to a specific process Pid:
9888 > erlang:trace_pattern(send, [{[Pid, '_'],[],[]}], []).
9890 1
9891 Only trace messages matching {reply, _}:
9893 > erlang:trace_pattern(send, [{['_', {reply,'_'}],[],[]}], []).
9895 1
9896 Only trace messages sent to the sender itself:
9898 > erlang:trace_pattern(send, [{['$1', '_'],[{'=:=','$1',{self}}],[]}], []).
9900 1
9901 Only trace messages sent to other nodes:
9903 > erlang:trace_pattern(send, [{['$1', '_'],[{'=/=',{node,'$1'},{node}}],[]}], []).
9905 1
9906 Note:
9908 A match specification for send trace can use all guard and body
9909 functions except caller.
9910 erlang:trace_pattern(MFA :: 'receive', MatchSpec, FlagList :: []) ->
9913 integer() >= 0
9914 Types:
9916 MatchSpec = (MatchSpecList :: trace_match_spec()) | boolean()
9918 trace_match_spec() =
9919 [{[term()] | '_' | match_variable(), [term()], [term()]}]
9920 match_variable() = atom()
9921 Approximation of '$1' | '$2' | '$3' | ...
9922 Sets trace pattern for message receiving. Must be combined with
9924 erlang:trace/3 to set the 'receive' trace flag for one or more
9925 processes. By default all messages received by 'receive' traced
9926 processes are traced. To limit traced receive events based on
9927 the message content, the sender and/or the receiver, use
9928 erlang:trace_pattern/3.
9929 Argument MatchSpec can take the following forms:
9931 MatchSpecList:
9933 A list of match specifications. The matching is done on the
9934 list [Node, Sender, Msg]. Node is the node name of the
9935 sender. Sender is the process or port identity of the
9936 sender, or the atom undefined if the sender is not known
9937 (which can be the case for remote senders). Msg is the mes‐
9938 sage term. The pid of the receiving process can be accessed
9939 with the guard function self/0. An empty list is the same as
9940 true. For more information, see section Match Specifica‐
9941 tions in Erlang in the User's Guide.
9942 true:
9944 Enables tracing for all received messages (to 'receive'
9945 traced processes). Any match specification is removed. This
9946 is the default.
9947 false:
9949 Disables tracing for all received messages. Any match speci‐
9950 fication is removed.
9951 Argument FlagList must be [] for receive tracing.
9953 The return value is always 1.
9955 Examples:
9957 Only trace messages from a specific process Pid:
9959 > erlang:trace_pattern('receive', [{['_',Pid, '_'],[],[]}], []).
9961 1
9962 Only trace messages matching {reply, _}:
9964 > erlang:trace_pattern('receive', [{['_','_', {reply,'_'}],[],[]}], []).
9966 1
9967 Only trace messages from other nodes:
9969 > erlang:trace_pattern('receive', [{['$1', '_', '_'],[{'=/=','$1',{node}}],[]}], []).
9971 1
9972 Note:
9974 A match specification for 'receive' trace can use all guard and
9975 body functions except caller, is_seq_trace, get_seq_token,
9976 set_seq_token, enable_trace, disable_trace, trace, silent, and
9977 process_dump.
9978 erlang:trace_pattern(MFA, MatchSpec, FlagList) ->
9981 integer() >= 0
9982 Types:
9984 MFA = trace_pattern_mfa()
9986 MatchSpec =
9987 (MatchSpecList :: trace_match_spec()) |
9988 boolean() |
9989 restart | pause
9990 FlagList = [trace_pattern_flag()]
9991 trace_pattern_mfa() = {atom(), atom(), arity() | '_'} | on_load
9992 trace_match_spec() =
9993 [{[term()] | '_' | match_variable(), [term()], [term()]}]
9994 trace_pattern_flag() =
9995 global | local | meta |
9996 {meta, Pid :: pid()} |
9997 {meta, TracerModule :: module(), TracerState :: term()} |
9998 call_count | call_time
9999 match_variable() = atom()
10000 Approximation of '$1' | '$2' | '$3' | ...
10001 Enables or disables call tracing for one or more functions. Must
10003 be combined with erlang:trace/3 to set the call trace flag for
10004 one or more processes.
10005 Conceptually, call tracing works as follows. Inside the Erlang
10007 virtual machine, a set of processes and a set of functions are
10008 to be traced. If a traced process calls a traced function, the
10009 trace action is taken. Otherwise, nothing happens.
10010 To add or remove one or more processes to the set of traced pro‐
10012 cesses, use erlang:trace/3.
10013 To add or remove functions to the set of traced functions, use
10015 erlang:trace_pattern/3.
10016 The BIF erlang:trace_pattern/3 can also add match specifications
10018 to a function. A match specification comprises a pattern that
10019 the function arguments must match, a guard expression that must
10020 evaluate to true, and an action to be performed. The default
10021 action is to send a trace message. If the pattern does not match
10022 or the guard fails, the action is not executed.
10023 Argument MFA is to be a tuple, such as {Module, Function,
10025 Arity}, or the atom on_load (described below). It can be the
10026 module, function, and arity for a function (or a BIF in any mod‐
10027 ule). The atom '_' can be used as a wildcard in any of the fol‐
10028 lowing ways:
10029 {Module,Function,'_'}:
10031 All functions of any arity named Function in module Module.
10032 {Module,'_','_'}:
10034 All functions in module Module.
10035 {'_','_','_'}:
10037 All functions in all loaded modules.
10038 Other combinations, such as {Module,'_',Arity}, are not allowed.
10040 Local functions match wildcards only if option local is in
10041 FlagList.
10042 If argument MFA is the atom on_load, the match specification and
10044 flag list are used on all modules that are newly loaded.
10045 Argument MatchSpec can take the following forms:
10047 false:
10049 Disables tracing for the matching functions. Any match spec‐
10050 ification is removed.
10051 true:
10053 Enables tracing for the matching functions. Any match speci‐
10054 fication is removed.
10055 MatchSpecList:
10057 A list of match specifications. An empty list is equivalent
10058 to true. For a description of match specifications, see sec‐
10059 tion Match Specifications in Erlang in the User's Guide.
10060 restart:
10062 For the FlagList options call_count and call_time: restarts
10063 the existing counters. The behavior is undefined for other
10064 FlagList options.
10065 pause:
10067 For the FlagList options call_count and call_time: pauses
10068 the existing counters. The behavior is undefined for other
10069 FlagList options.
10070 Parameter FlagList is a list of options. The following are the
10072 valid options:
10073 global:
10075 Turns on or off call tracing for global function calls (that
10076 is, calls specifying the module explicitly). Only exported
10077 functions match and only global calls generate trace mes‐
10078 sages. This is the default.
10079 local:
10081 Turns on or off call tracing for all types of function
10082 calls. Trace messages are sent whenever any of the specified
10083 functions are called, regardless of how they are called. If
10084 flag return_to is set for the process, a return_to message
10085 is also sent when this function returns to its caller.
10086 meta | {meta, Pid} | {meta, TracerModule, TracerState}:
10088 Turns on or off meta-tracing for all types of function
10089 calls. Trace messages are sent to the tracer whenever any of
10090 the specified functions are called. If no tracer is speci‐
10091 fied, self() is used as a default tracer process.
10092 Meta-tracing traces all processes and does not care about
10094 the process trace flags set by erlang:trace/3, the trace
10095 flags are instead fixed to [call, timestamp].
10096 The match specification function {return_trace} works with
10098 meta-trace and sends its trace message to the same tracer.
10099 call_count:
10101 Starts (MatchSpec == true) or stops (MatchSpec == false)
10102 call count tracing for all types of function calls. For
10103 every function, a counter is incremented when the function
10104 is called, in any process. No process trace flags need to be
10105 activated.
10106 If call count tracing is started while already running, the
10108 count is restarted from zero. To pause running counters, use
10109 MatchSpec == pause. Paused and running counters can be
10110 restarted from zero with MatchSpec == restart.
10111 To read the counter value, use erlang:trace_info/2.
10113 call_time:
10115 Starts (MatchSpec == true) or stops (MatchSpec == false)
10116 call time tracing for all types of function calls. For every
10117 function, a counter is incremented when the function is
10118 called. Time spent in the function is accumulated in two
10119 other counters, seconds and microseconds. The counters are
10120 stored for each call traced process.
10121 If call time tracing is started while already running, the
10123 count and time restart from zero. To pause running counters,
10124 use MatchSpec == pause. Paused and running counters can be
10125 restarted from zero with MatchSpec == restart.
10126 To read the counter value, use erlang:trace_info/2.
10128 The options global and local are mutually exclusive, and global
10130 is the default (if no options are specified). The options
10131 call_count and meta perform a kind of local tracing, and cannot
10132 be combined with global. A function can be globally or locally
10133 traced. If global tracing is specified for a set of functions,
10134 then local, meta, call time, and call count tracing for the
10135 matching set of local functions is disabled, and conversely.
10136 When disabling trace, the option must match the type of trace
10138 set on the function. That is, local tracing must be disabled
10139 with option local and global tracing with option global (or no
10140 option), and so on.
10141 Part of a match specification list cannot be changed directly.
10143 If a function has a match specification, it can be replaced with
10144 a new one. To change an existing match specification, use the
10145 BIF erlang:trace_info/2 to retrieve the existing match specifi‐
10146 cation.
10147 Returns the number of functions matching argument MFA. This is
10149 zero if none matched.
10150 trunc(Number) -> integer()
10152 Types:
10154 Number = number()
10156 Returns an integer by truncating Number, for example:
10158 > trunc(5.5).
10160 5
10161 Allowed in guard tests.
10163 tuple_size(Tuple) -> integer() >= 0
10165 Types:
10167 Tuple = tuple()
10169 Returns an integer that is the number of elements in Tuple, for
10171 example:
10172 > tuple_size({morni, mulle, bwange}).
10174 3
10175 Allowed in guard tests.
10177 tuple_to_list(Tuple) -> [term()]
10179 Types:
10181 Tuple = tuple()
10183 Returns a list corresponding to Tuple. Tuple can contain any
10185 Erlang terms. Example:
10186 > tuple_to_list({share, {'Ericsson_B', 163}}).
10188 [share,{'Ericsson_B',163}]
10189 erlang:unique_integer() -> integer()
10191 Generates and returns an integer unique on current runtime sys‐
10193 tem instance. The same as calling erlang:unique_integer([]).
10194 erlang:unique_integer(ModifierList) -> integer()
10196 Types:
10198 ModifierList = [Modifier]
10200 Modifier = positive | monotonic
10201 Generates and returns an integer unique on current runtime sys‐
10203 tem instance. The integer is unique in the sense that this BIF,
10204 using the same set of modifiers, does not return the same inte‐
10205 ger more than once on the current runtime system instance. Each
10206 integer value can of course be constructed by other means.
10207 By default, when [] is passed as ModifierList, both negative and
10209 positive integers can be returned. This to use the range of
10210 integers that do not need heap memory allocation as much as pos‐
10211 sible. By default the returned integers are also only guaranteed
10212 to be unique, that is, any returned integer can be smaller or
10213 larger than previously returned integers.
10214 Modifiers:
10216 positive:
10218 Returns only positive integers.
10219 Notice that by passing the positive modifier you will get
10221 heap allocated integers (bignums) quicker.
10222 monotonic:
10224 Returns strictly monotonically increasing integers corre‐
10225 sponding to creation time. That is, the integer returned is
10226 always larger than previously returned integers on the cur‐
10227 rent runtime system instance.
10228 These values can be used to determine order between events
10230 on the runtime system instance. That is, if both X =
10231 erlang:unique_integer([monotonic]) and Y =
10232 erlang:unique_integer([monotonic]) are executed by different
10233 processes (or the same process) on the same runtime system
10234 instance and X < Y, we know that X was created before Y.
10235 Warning:
10237 Strictly monotonically increasing values are inherently quite
10238 expensive to generate and scales poorly. This is because the
10239 values need to be synchronized between CPU cores. That is, do
10240 not pass the monotonic modifier unless you really need
10241 strictly monotonically increasing values.
10242 All valid Modifiers can be combined. Repeated (valid) Modifiers
10245 in the ModifierList are ignored.
10246 Note:
10248 The set of integers returned by erlang:unique_integer/1 using
10249 different sets of Modifiers will overlap. For example, by call‐
10250 ing unique_integer([monotonic]), and unique_integer([positive,
10251 monotonic]) repeatedly, you will eventually see some integers
10252 that are returned by both calls.
10253 Failures:
10256 badarg:
10258 if ModifierList is not a proper list.
10259 badarg:
10261 if Modifier is not a valid modifier.
10262 erlang:universaltime() -> DateTime
10264 Types:
10266 DateTime = calendar:datetime()
10268 Returns the current date and time according to Universal Time
10270 Coordinated (UTC) in the form {{Year, Month, Day}, {Hour,
10271 Minute, Second}} if supported by the underlying OS. Otherwise
10272 erlang:universaltime() is equivalent to erlang:localtime().
10273 Example:
10274 > erlang:universaltime().
10276 {{1996,11,6},{14,18,43}}
10277 erlang:universaltime_to_localtime(Universaltime) -> Localtime
10279 Types:
10281 Localtime = Universaltime = calendar:datetime()
10283 Converts Universal Time Coordinated (UTC) date and time to local
10285 date and time in the form {{Year, Month, Day}, {Hour, Minute,
10286 Second}} if supported by the underlying OS. Otherwise no conver‐
10287 sion is done, and Universaltime is returned. Example:
10288 > erlang:universaltime_to_localtime({{1996,11,6},{14,18,43}}).
10290 {{1996,11,7},{15,18,43}}
10291 Failure: badarg if Universaltime denotes an invalid date and
10293 time.
10294 unlink(Id) -> true
10296 Types:
10298 Id = pid() | port()
10300 Removes the link, if there is one, between the calling process
10302 and the process or port referred to by Id.
10303 Returns true and does not fail, even if there is no link to Id,
10305 or if Id does not exist.
10306 Once unlink(Id) has returned, it is guaranteed that the link
10308 between the caller and the entity referred to by Id has no
10309 effect on the caller in the future (unless the link is setup
10310 again). If the caller is trapping exits, an {'EXIT', Id, _} mes‐
10311 sage from the link can have been placed in the caller's message
10312 queue before the call.
10313 Notice that the {'EXIT', Id, _} message can be the result of the
10315 link, but can also be the result of Id calling exit/2. There‐
10316 fore, it can be appropriate to clean up the message queue when
10317 trapping exits after the call to unlink(Id), as follows:
10318 unlink(Id),
10320 receive
10321 {'EXIT', Id, _} ->
10322 true
10323 after 0 ->
10324 true
10325 end
10326 Note:
10328 Before Erlang/OTP R11B (ERTS 5.5) unlink/1 behaved completely
10329 asynchronously, that is, the link was active until the "unlink
10330 signal" reached the linked entity. This had an undesirable
10331 effect, as you could never know when you were guaranteed not to
10332 be effected by the link.
10333 The current behavior can be viewed as two combined operations:
10335 asynchronously send an "unlink signal" to the linked entity and
10336 ignore any future results of the link.
10337 unregister(RegName) -> true
10340 Types:
10342 RegName = atom()
10344 Removes the registered name RegName associated with a process
10346 identifier or a port identifier, for example:
10347 > unregister(db).
10349 true
10350 Users are advised not to unregister system processes.
10352 Failure: badarg if RegName is not a registered name.
10354 whereis(RegName) -> pid() | port() | undefined
10356 Types:
10358 RegName = atom()
10360 Returns the process identifier or port identifier with the reg‐
10362 istered name RegName. Returns undefined if the name is not reg‐
10363 istered. Example:
10364 > whereis(db).
10366 <0.43.0>
10367 erlang:yield() -> true
10369 Voluntarily lets other processes (if any) get a chance to exe‐
10371 cute. Using this function is similar to receive after 1 -> ok
10372 end, except that yield() is faster.
10373 Warning:
10375 There is seldom or never any need to use this BIF as other pro‐
10376 cesses have a chance to run in another scheduler thread anyway.
10377 Using this BIF without a thorough grasp of how the scheduler
10378 works can cause performance degradation.
10379Ericsson AB erts 10.7.1 erlang(3)