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 |
50 millisecond |
51 microsecond |
52 nanosecond |
53 native |
54 perf_counter |
55 deprecated_time_unit()
56 Supported time unit representations:
58 PartsPerSecond :: integer() >= 1:
60 Time unit expressed in parts per second. That is, the time
61 unit equals 1/PartsPerSecond second.
62 second:
64 Symbolic representation of the time unit represented by the
65 integer 1.
66 millisecond:
68 Symbolic representation of the time unit represented by the
69 integer 1000.
70 microsecond:
72 Symbolic representation of the time unit represented by the
73 integer 1000000.
74 nanosecond:
76 Symbolic representation of the time unit represented by the
77 integer 1000000000.
78 native:
80 Symbolic representation of the native time unit used by the
81 Erlang runtime system.
82 The native time unit is determined at runtime system start,
84 and remains the same until the runtime system terminates. If
85 a runtime system is stopped and then started again (even on
86 the same machine), the native time unit of the new runtime
87 system instance can differ from the native time unit of the
88 old runtime system instance.
89 One can get an approximation of the native time unit by
91 calling erlang:convert_time_unit(1, second, native). The
92 result equals the number of whole native time units per sec‐
93 ond. If the number of native time units per second does not
94 add up to a whole number, the result is rounded downwards.
95 Note:
97 The value of the native time unit gives you more or less no
98 information about the quality of time values. It sets a limit
99 for the resolution and for the precision of time values, but
100 it gives no information about the accuracy of time values.
101 The resolution of the native time unit and the resolution of
102 time values can differ significantly.
103 perf_counter:
106 Symbolic representation of the performance counter time unit
107 used by the Erlang runtime system.
108 The perf_counter time unit behaves much in the same way as
110 the native time unit. That is, it can differ between runtime
111 restarts. To get values of this type, call
112 os:perf_counter/0.
113 deprecated_time_unit():
115 Deprecated symbolic representations kept for backwards-com‐
116 patibility.
117 The time_unit/0 type can be extended. To convert time values
119 between time units, use erlang:convert_time_unit/3.
120 deprecated_time_unit() =
122 seconds | milli_seconds | micro_seconds | nano_seconds
123 The time_unit() type also consist of the following deprecated
125 symbolic time units:
126 seconds:
128 Same as second.
129 milli_seconds:
131 Same as millisecond.
132 micro_seconds:
134 Same as microsecond.
135 nano_seconds:
137 Same as nanosecond.
138 dist_handle()
140 An opaque handle identifing a distribution channel.
142 nif_resource()
144 An opaque handle identifing a NIF resource object .
146
148 abs(Float) -> float()
149 abs(Int) -> integer() >= 0
151 Types:
153 Int = integer()
155 Returns an integer or float that is the arithmetical absolute
157 value of Float or Int, for example:
158 > abs(-3.33).
160 3.33
161 > abs(-3).
162 3
163 Allowed in guard tests.
165 erlang:adler32(Data) -> integer() >= 0
167 Types:
169 Data = iodata()
171 Computes and returns the adler32 checksum for Data.
173 erlang:adler32(OldAdler, Data) -> integer() >= 0
175 Types:
177 OldAdler = integer() >= 0
179 Data = iodata()
180 Continues computing the adler32 checksum by combining the previ‐
182 ous checksum, OldAdler, with the checksum of Data.
183 The following code:
185 X = erlang:adler32(Data1),
187 Y = erlang:adler32(X,Data2).
188 assigns the same value to Y as this:
190 Y = erlang:adler32([Data1,Data2]).
192 erlang:adler32_combine(FirstAdler, SecondAdler, SecondSize) ->
194 integer() >= 0
195 Types:
197 FirstAdler = SecondAdler = SecondSize = integer() >= 0
199 Combines two previously computed adler32 checksums. This compu‐
201 tation requires the size of the data object for the second
202 checksum to be known.
203 The following code:
205 Y = erlang:adler32(Data1),
207 Z = erlang:adler32(Y,Data2).
208 assigns the same value to Z as this:
210 X = erlang:adler32(Data1),
212 Y = erlang:adler32(Data2),
213 Z = erlang:adler32_combine(X,Y,iolist_size(Data2)).
214 erlang:append_element(Tuple1, Term) -> Tuple2
216 Types:
218 Tuple1 = Tuple2 = tuple()
220 Term = term()
221 Returns a new tuple that has one element more than Tuple1, and
223 contains the elements in Tuple1 followed by Term as the last
224 element. Semantically equivalent to
225 list_to_tuple(tuple_to_list(Tuple1) ++ [Term]), but much faster.
226 Example:
227 > erlang:append_element({one, two}, three).
229 {one,two,three}
230 apply(Fun, Args) -> term()
232 Types:
234 Fun = function()
236 Args = [term()]
237 Calls a fun, passing the elements in Args as arguments.
239 If the number of elements in the arguments are known at compile
241 time, the call is better written as Fun(Arg1, Arg2, ... ArgN).
242 Warning:
244 Earlier, Fun could also be specified as {Module, Function},
245 equivalent to apply(Module, Function, Args). This use is depre‐
246 cated and will stop working in a future release.
247 apply(Module, Function, Args) -> term()
250 Types:
252 Module = module()
254 Function = atom()
255 Args = [term()]
256 Returns the result of applying Function in Module to Args. The
258 applied function must be exported from Module. The arity of the
259 function is the length of Args. Example:
260 > apply(lists, reverse, [[a, b, c]]).
262 [c,b,a]
263 > apply(erlang, atom_to_list, ['Erlang']).
264 "Erlang"
265 If the number of arguments are known at compile time, the call
267 is better written as Module:Function(Arg1, Arg2, ..., ArgN).
268 Failure: error_handler:undefined_function/3 is called if the
270 applied function is not exported. The error handler can be rede‐
271 fined (see process_flag/2). If error_handler is undefined, or if
272 the user has redefined the default error_handler so the replace‐
273 ment module is undefined, an error with reason undef is gener‐
274 ated.
275 atom_to_binary(Atom, Encoding) -> binary()
277 Types:
279 Atom = atom()
281 Encoding = latin1 | unicode | utf8
282 Returns a binary corresponding to the text representation of
284 Atom. If Encoding is latin1, one byte exists for each character
285 in the text representation. If Encoding is utf8 or unicode, the
286 characters are encoded using UTF-8 where characters may require
287 multiple bytes.
288 Note:
290 As from Erlang/OTP 20, atoms can contain any Unicode character
291 and atom_to_binary(Atom, latin1) may fail if the text represen‐
292 tation for Atom contains a Unicode character > 255.
293 Example:
296 > atom_to_binary('Erlang', latin1).
298 <<"Erlang">>
299 atom_to_list(Atom) -> string()
301 Types:
303 Atom = atom()
305 Returns a string corresponding to the text representation of
307 Atom, for example:
308 > atom_to_list('Erlang').
310 "Erlang"
311 binary_part(Subject, PosLen) -> binary()
313 Types:
315 Subject = binary()
317 PosLen = {Start :: integer() >= 0, Length :: integer()}
318 Extracts the part of the binary described by PosLen.
320 Negative length can be used to extract bytes at the end of a
322 binary, for example:
323 1> Bin = <<1,2,3,4,5,6,7,8,9,10>>.
325 2> binary_part(Bin,{byte_size(Bin), -5}).
326 <<6,7,8,9,10>>
327 Failure: badarg if PosLen in any way references outside the
329 binary.
330 Start is zero-based, that is:
332 1> Bin = <<1,2,3>>
334 2> binary_part(Bin,{0,2}).
335 <<1,2>>
336 For details about the PosLen semantics, see binary(3).
338 Allowed in guard tests.
340 binary_part(Subject, Start, Length) -> binary()
342 Types:
344 Subject = binary()
346 Start = integer() >= 0
347 Length = integer()
348 The same as binary_part(Subject, {Start, Length}).
350 Allowed in guard tests.
352 binary_to_atom(Binary, Encoding) -> atom()
354 Types:
356 Binary = binary()
358 Encoding = latin1 | unicode | utf8
359 Returns the atom whose text representation is Binary. If Encod‐
361 ing is latin1, no translation of bytes in the binary is done. If
362 Encoding is utf8 or unicode, the binary must contain valid UTF-8
363 sequences.
364 Note:
366 As from Erlang/OTP 20, binary_to_atom(Binary, utf8) is capable
367 of encoding any Unicode character. Earlier versions would fail
368 if the binary contained Unicode characters > 255. For more
369 information about Unicode support in atoms, see the note on
370 UTF-8 encoded atoms in section "External Term Format" in the
371 User's Guide.
372 Examples:
375 > binary_to_atom(<<"Erlang">>, latin1).
377 > binary_to_atom(<<1024/utf8>>, utf8).
378 binary_to_existing_atom(Binary, Encoding) -> atom()
380 Types:
382 Binary = binary()
384 Encoding = latin1 | unicode | utf8
385 As binary_to_atom/2, but the atom must exist.
387 Failure: badarg if the atom does not exist.
389 Note:
391 Note that the compiler may optimize away atoms. For example, the
392 compiler will rewrite atom_to_list(some_atom) to "some_atom". If
393 that expression is the only mention of the atom some_atom in the
394 containing module, the atom will not be created when the module
395 is loaded, and a subsequent call to binary_to_exist‐
396 ing_atom(<<"some_atom">>, utf8) will fail.
397 binary_to_float(Binary) -> float()
400 Types:
402 Binary = binary()
404 Returns the float whose text representation is Binary, for exam‐
406 ple:
407 > binary_to_float(<<"2.2017764e+0">>).
409 2.2017764
410 Failure: badarg if Binary contains a bad representation of a
412 float.
413 binary_to_integer(Binary) -> integer()
415 Types:
417 Binary = binary()
419 Returns an integer whose text representation is Binary, for
421 example:
422 > binary_to_integer(<<"123">>).
424 123
425 Failure: badarg if Binary contains a bad representation of an
427 integer.
428 binary_to_integer(Binary, Base) -> integer()
430 Types:
432 Binary = binary()
434 Base = 2..36
435 Returns an integer whose text representation in base Base is
437 Binary, for example:
438 > binary_to_integer(<<"3FF">>, 16).
440 1023
441 Failure: badarg if Binary contains a bad representation of an
443 integer.
444 binary_to_list(Binary) -> [byte()]
446 Types:
448 Binary = binary()
450 Returns a list of integers corresponding to the bytes of Binary.
452 binary_to_list(Binary, Start, Stop) -> [byte()]
454 Types:
456 Binary = binary()
458 Start = Stop = integer() >= 1
459 1..byte_size(Binary)
460 As binary_to_list/1, but returns a list of integers correspond‐
462 ing to the bytes from position Start to position Stop in Binary.
463 The positions in the binary are numbered starting from 1.
464 Note:
466 The one-based indexing for binaries used by this function is
467 deprecated. New code is to use binary:bin_to_list/3 in STDLIB
468 instead. All functions in module binary consistently use zero-
469 based indexing.
470 binary_to_term(Binary) -> term()
473 Types:
475 Binary = ext_binary()
477 Returns an Erlang term that is the result of decoding binary
479 object Binary, which must be encoded according to the Erlang
480 external term format.
481 > Bin = term_to_binary(hello).
483 <<131,100,0,5,104,101,108,108,111>>
484 > hello = binary_to_term(Bin).
485 hello
486 Warning:
489 When decoding binaries from untrusted sources, consider using
490 binary_to_term/2 to prevent Denial of Service attacks.
491 See also term_to_binary/1 and binary_to_term/2.
494 binary_to_term(Binary, Opts) -> term() | {term(), Used}
496 Types:
498 Binary = ext_binary()
500 Opt = safe | used
501 Opts = [Opt]
502 Used = integer() >= 1
503 As binary_to_term/1, but takes these options:
505 safe:
507 Use this option when receiving binaries from an untrusted
508 source.
509 When enabled, it prevents decoding data that can be used to
511 attack the Erlang system. In the event of receiving unsafe
512 data, decoding fails with a badarg error.
513 This prevents creation of new atoms directly, creation of
515 new atoms indirectly (as they are embedded in certain struc‐
516 tures, such as process identifiers, refs, and funs), and
517 creation of new external function references. None of those
518 resources are garbage collected, so unchecked creation of
519 them can exhaust available memory.
520 > binary_to_term(<<131,100,0,5,"hello">>, [safe]).
522 ** exception error: bad argument
523 > hello.
524 hello
525 > binary_to_term(<<131,100,0,5,"hello">>, [safe]).
526 hello
527 used:
530 Changes the return value to {Term, Used} where Used is the
531 number of bytes actually read from Binary.
532 > Input = <<131,100,0,5,"hello","world">>.
534 <<131,100,0,5,104,101,108,108,111,119,111,114,108,100>>
535 > {Term, Used} = binary_to_term(Input, [used]).
536 {hello, 9}
537 > split_binary(Input, Used).
538 {<<131,100,0,5,104,101,108,108,111>>, <<"world">>}
539 Failure: badarg if safe is specified and unsafe data is decoded.
542 See also term_to_binary/1, binary_to_term/1, and list_to_exist‐
544 ing_atom/1.
545 bit_size(Bitstring) -> integer() >= 0
547 Types:
549 Bitstring = bitstring()
551 Returns an integer that is the size in bits of Bitstring, for
553 example:
554 > bit_size(<<433:16,3:3>>).
556 19
557 > bit_size(<<1,2,3>>).
558 24
559 Allowed in guard tests.
561 bitstring_to_list(Bitstring) -> [byte() | bitstring()]
563 Types:
565 Bitstring = bitstring()
567 Returns a list of integers corresponding to the bytes of Bit‐
569 string. If the number of bits in the binary is not divisible by
570 8, the last element of the list is a bitstring containing the
571 remaining 1-7 bits.
572 erlang:bump_reductions(Reductions) -> true
574 Types:
576 Reductions = integer() >= 1
578 This implementation-dependent function increments the reduction
580 counter for the calling process. In the Beam emulator, the
581 reduction counter is normally incremented by one for each func‐
582 tion and BIF call. A context switch is forced when the counter
583 reaches the maximum number of reductions for a process (2000
584 reductions in Erlang/OTP R12B).
585 Warning:
587 This BIF can be removed in a future version of the Beam machine
588 without prior warning. It is unlikely to be implemented in other
589 Erlang implementations.
590 byte_size(Bitstring) -> integer() >= 0
593 Types:
595 Bitstring = bitstring()
597 Returns an integer that is the number of bytes needed to contain
599 Bitstring. That is, if the number of bits in Bitstring is not
600 divisible by 8, the resulting number of bytes is rounded up.
601 Examples:
602 > byte_size(<<433:16,3:3>>).
604 3
605 > byte_size(<<1,2,3>>).
606 3
607 Allowed in guard tests.
609 erlang:cancel_timer(TimerRef) -> Result
611 Types:
613 TimerRef = reference()
615 Time = integer() >= 0
616 Result = Time | false
617 Cancels a timer. The same as calling erlang:cancel_timer(Timer‐
619 Ref, []).
620 erlang:cancel_timer(TimerRef, Options) -> Result | ok
622 Types:
624 TimerRef = reference()
626 Async = Info = boolean()
627 Option = {async, Async} | {info, Info}
628 Options = [Option]
629 Time = integer() >= 0
630 Result = Time | false
631 Cancels a timer that has been created by erlang:start_timer or
633 erlang:send_after. TimerRef identifies the timer, and was
634 returned by the BIF that created the timer.
635 Options:
637 {async, Async}:
639 Asynchronous request for cancellation. Async defaults to
640 false, which causes the cancellation to be performed syn‐
641 chronously. When Async is set to true, the cancel operation
642 is performed asynchronously. That is, cancel_timer() sends
643 an asynchronous request for cancellation to the timer ser‐
644 vice that manages the timer, and then returns ok.
645 {info, Info}:
647 Requests information about the Result of the cancellation.
648 Info defaults to true, which means the Result is given. When
649 Info is set to false, no information about the result of the
650 cancellation is given.
651 * When Async is false: if Info is true, the Result is
653 returned by erlang:cancel_timer(). otherwise ok is
654 returned.
655 * When Async is true: if Info is true, a message on the form
657 {cancel_timer, TimerRef, Result} is sent to the caller of
658 erlang:cancel_timer() when the cancellation operation has
659 been performed, otherwise no message is sent.
660 More Options may be added in the future.
662 If Result is an integer, it represents the time in milliseconds
664 left until the canceled timer would have expired.
665 If Result is false, a timer corresponding to TimerRef could not
667 be found. This can be either because the timer had expired,
668 already had been canceled, or because TimerRef never corre‐
669 sponded to a timer. Even if the timer had expired, it does not
670 tell you if the time-out message has arrived at its destination
671 yet.
672 Note:
674 The timer service that manages the timer can be co-located with
675 another scheduler than the scheduler that the calling process is
676 executing on. If so, communication with the timer service takes
677 much longer time than if it is located locally. If the calling
678 process is in critical path, and can do other things while wait‐
679 ing for the result of this operation, or is not interested in
680 the result of the operation, you want to use option {async,
681 true}. If using option {async, false}, the calling process
682 blocks until the operation has been performed.
683 See also erlang:send_after/4, erlang:start_timer/4, and
686 erlang:read_timer/2.
687 ceil(Number) -> integer()
689 Types:
691 Number = number()
693 Returns the smallest integer not less than Number. For example:
695 > ceil(5.5).
697 6
698 Allowed in guard tests.
700 check_old_code(Module) -> boolean()
702 Types:
704 Module = module()
706 Returns true if Module has old code, otherwise false.
708 See also code(3).
710 check_process_code(Pid, Module) -> CheckResult
712 Types:
714 Pid = pid()
716 Module = module()
717 CheckResult = boolean()
718 The same as check_process_code(Pid, Module, []).
720 check_process_code(Pid, Module, OptionList) -> CheckResult | async
722 Types:
724 Pid = pid()
726 Module = module()
727 RequestId = term()
728 Option = {async, RequestId} | {allow_gc, boolean()}
729 OptionList = [Option]
730 CheckResult = boolean() | aborted
731 Checks if the node local process identified by Pid executes old
733 code for Module.
734 Options:
736 {allow_gc, boolean()}:
738 Determines if garbage collection is allowed when performing
739 the operation. If {allow_gc, false} is passed, and a garbage
740 collection is needed to determine the result of the opera‐
741 tion, the operation is aborted (see information on CheckRe‐
742 sult below). The default is to allow garbage collection,
743 that is, {allow_gc, true}.
744 {async, RequestId}:
746 The function check_process_code/3 returns the value async
747 immediately after the request has been sent. When the
748 request has been processed, the process that called this
749 function is passed a message on the form
750 {check_process_code, RequestId, CheckResult}.
751 If Pid equals self(), and no async option has been passed, the
753 operation is performed at once. Otherwise a request for the
754 operation is sent to the process identified by Pid, and is han‐
755 dled when appropriate. If no async option has been passed, the
756 caller blocks until CheckResult is available and can be
757 returned.
758 CheckResult informs about the result of the request as follows:
760 true:
762 The process identified by Pid executes old code for Module.
763 That is, the current call of the process executes old code
764 for this module, or the process has references to old code
765 for this module, or the process contains funs that refer‐
766 ences old code for this module.
767 false:
769 The process identified by Pid does not execute old code for
770 Module.
771 aborted:
773 The operation was aborted, as the process needed to be
774 garbage collected to determine the operation result, and the
775 operation was requested by passing option {allow_gc, false}.
776 Note:
778 Up until ERTS version 8.*, the check process code operation
779 checks for all types of references to the old code. That is,
780 direct references (e.g. return addresses on the process stack),
781 indirect references (funs in process context), and references to
782 literals in the code.
783 As of ERTS version 9.0, the check process code operation only
785 checks for direct references to the code. Indirect references
786 via funs will be ignored. If such funs exist and are used after
787 a purge of the old code, an exception will be raised upon usage
788 (same as the case when the fun is received by the process after
789 the purge). Literals will be taken care of (copied) at a later
790 stage. This behavior can as of ERTS version 8.1 be enabled when
791 building OTP, and will automatically be enabled if dirty sched‐
792 uler support is enabled.
793 See also code(3).
796 Failures:
798 badarg:
800 If Pid is not a node local process identifier.
801 badarg:
803 If Module is not an atom.
804 badarg:
806 If OptionList is an invalid list of options.
807 erlang:convert_time_unit(Time, FromUnit, ToUnit) -> ConvertedTime
809 Types:
811 Time = ConvertedTime = integer()
813 FromUnit = ToUnit = time_unit()
814 Converts the Time value of time unit FromUnit to the correspond‐
816 ing ConvertedTime value of time unit ToUnit. The result is
817 rounded using the floor function.
818 Warning:
820 You can lose accuracy and precision when converting between time
821 units. To minimize such loss, collect all data at native time
822 unit and do the conversion on the end result.
823 erlang:crc32(Data) -> integer() >= 0
826 Types:
828 Data = iodata()
830 Computes and returns the crc32 (IEEE 802.3 style) checksum for
832 Data.
833 erlang:crc32(OldCrc, Data) -> integer() >= 0
835 Types:
837 OldCrc = integer() >= 0
839 Data = iodata()
840 Continues computing the crc32 checksum by combining the previous
842 checksum, OldCrc, with the checksum of Data.
843 The following code:
845 X = erlang:crc32(Data1),
847 Y = erlang:crc32(X,Data2).
848 assigns the same value to Y as this:
850 Y = erlang:crc32([Data1,Data2]).
852 erlang:crc32_combine(FirstCrc, SecondCrc, SecondSize) ->
854 integer() >= 0
855 Types:
857 FirstCrc = SecondCrc = SecondSize = integer() >= 0
859 Combines two previously computed crc32 checksums. This computa‐
861 tion requires the size of the data object for the second check‐
862 sum to be known.
863 The following code:
865 Y = erlang:crc32(Data1),
867 Z = erlang:crc32(Y,Data2).
868 assigns the same value to Z as this:
870 X = erlang:crc32(Data1),
872 Y = erlang:crc32(Data2),
873 Z = erlang:crc32_combine(X,Y,iolist_size(Data2)).
874 date() -> Date
876 Types:
878 Date = calendar:date()
880 Returns the current date as {Year, Month, Day}.
882 The time zone and Daylight Saving Time correction depend on the
884 underlying OS. Example:
885 > date().
887 {1995,2,19}
888 erlang:decode_packet(Type, Bin, Options) ->
890 {ok, Packet, Rest} |
891 {more, Length} |
892 {error, Reason}
893 Types:
895 Type =
897 raw |
898 0 |
899 1 |
900 2 |
901 4 |
902 asn1 |
903 cdr |
904 sunrm |
905 fcgi |
906 tpkt |
907 line |
908 http |
909 http_bin |
910 httph |
911 httph_bin
912 Bin = binary()
913 Options = [Opt]
914 Opt =
915 {packet_size, integer() >= 0} |
916 {line_length, integer() >= 0}
917 Packet = binary() | HttpPacket
918 Rest = binary()
919 Length = integer() >= 0 | undefined
920 Reason = term()
921 HttpPacket =
922 HttpRequest | HttpResponse | HttpHeader | http_eoh |
923 HttpError
924 HttpRequest = {http_request, HttpMethod, HttpUri, HttpVer‐
925 sion}
926 HttpResponse =
927 {http_response, HttpVersion, integer(), HttpString}
928 HttpHeader =
929 {http_header,
930 integer(),
931 HttpField,
932 Reserved :: term(),
933 Value :: HttpString}
934 HttpError = {http_error, HttpString}
935 HttpMethod =
936 'OPTIONS' |
937 'GET' |
938 'HEAD' |
939 'POST' |
940 'PUT' |
941 'DELETE' |
942 'TRACE' |
943 HttpString
944 HttpUri =
945 '*' |
946 {absoluteURI,
947 http | https,
948 Host :: HttpString,
949 Port :: inet:port_number() | undefined,
950 Path :: HttpString} |
951 {scheme, Scheme :: HttpString, HttpString} |
952 {abs_path, HttpString} |
953 HttpString
954 HttpVersion =
955 {Major :: integer() >= 0, Minor :: integer() >= 0}
956 HttpField =
957 'Cache-Control' |
958 'Connection' |
959 'Date' |
960 'Pragma' |
961 'Transfer-Encoding' |
962 'Upgrade' |
963 'Via' |
964 'Accept' |
965 'Accept-Charset' |
966 'Accept-Encoding' |
967 'Accept-Language' |
968 'Authorization' |
969 'From' |
970 'Host' |
971 'If-Modified-Since' |
972 'If-Match' |
973 'If-None-Match' |
974 'If-Range' |
975 'If-Unmodified-Since' |
976 'Max-Forwards' |
977 'Proxy-Authorization' |
978 'Range' |
979 'Referer' |
980 'User-Agent' |
981 'Age' |
982 'Location' |
983 'Proxy-Authenticate' |
984 'Public' |
985 'Retry-After' |
986 'Server' |
987 'Vary' |
988 'Warning' |
989 'Www-Authenticate' |
990 'Allow' |
991 'Content-Base' |
992 'Content-Encoding' |
993 'Content-Language' |
994 'Content-Length' |
995 'Content-Location' |
996 'Content-Md5' |
997 'Content-Range' |
998 'Content-Type' |
999 'Etag' |
1000 'Expires' |
1001 'Last-Modified' |
1002 'Accept-Ranges' |
1003 'Set-Cookie' |
1004 'Set-Cookie2' |
1005 'X-Forwarded-For' |
1006 'Cookie' |
1007 'Keep-Alive' |
1008 'Proxy-Connection' |
1009 HttpString
1010 HttpString = string() | binary()
1011 Decodes the binary Bin according to the packet protocol speci‐
1013 fied by Type. Similar to the packet handling done by sockets
1014 with option {packet,Type}.
1015 If an entire packet is contained in Bin, it is returned together
1017 with the remainder of the binary as {ok,Packet,Rest}.
1018 If Bin does not contain the entire packet, {more,Length} is
1020 returned. Length is either the expected total size of the
1021 packet, or undefined if the expected packet size is unknown.
1022 decode_packet can then be called again with more data added.
1023 If the packet does not conform to the protocol format,
1025 {error,Reason} is returned.
1026 Types:
1028 raw | 0:
1030 No packet handling is done. The entire binary is returned
1031 unless it is empty.
1032 1 | 2 | 4:
1034 Packets consist of a header specifying the number of bytes
1035 in the packet, followed by that number of bytes. The length
1036 of the header can be one, two, or four bytes; the order of
1037 the bytes is big-endian. The header is stripped off when the
1038 packet is returned.
1039 line:
1041 A packet is a line-terminated by a delimiter byte, default
1042 is the latin-1 newline character. The delimiter byte is
1043 included in the returned packet unless the line was trun‐
1044 cated according to option line_length.
1045 asn1 | cdr | sunrm | fcgi | tpkt:
1047 The header is not stripped off.
1048 The meanings of the packet types are as follows:
1050 asn1 - ASN.1 BER:
1052 sunrm - Sun's RPC encoding:
1055 cdr - CORBA (GIOP 1.1):
1058 fcgi - Fast CGI:
1061 tpkt - TPKT format [RFC1006]:
1064 http | httph | http_bin | httph_bin:
1067 The Hypertext Transfer Protocol. The packets are returned
1068 with the format according to HttpPacket described earlier. A
1069 packet is either a request, a response, a header, or an end
1070 of header mark. Invalid lines are returned as HttpError.
1071 Recognized request methods and header fields are returned as
1073 atoms. Others are returned as strings. Strings of unrecog‐
1074 nized header fields are formatted with only capital letters
1075 first and after hyphen characters, for example, "Sec-Web‐
1076 socket-Key".
1077 The protocol type http is only to be used for the first line
1079 when an HttpRequest or an HttpResponse is expected. The fol‐
1080 lowing calls are to use httph to get HttpHeaders until
1081 http_eoh is returned, which marks the end of the headers and
1082 the beginning of any following message body.
1083 The variants http_bin and httph_bin return strings (Http‐
1085 String) as binaries instead of lists.
1086 Options:
1088 {packet_size, integer() >= 0}:
1090 Sets the maximum allowed size of the packet body. If the
1091 packet header indicates that the length of the packet is
1092 longer than the maximum allowed length, the packet is con‐
1093 sidered invalid. Defaults to 0, which means no size limit.
1094 {line_length, integer() >= 0}:
1096 For packet type line, lines longer than the indicated length
1097 are truncated.
1098 Option line_length also applies to http* packet types as an
1100 alias for option packet_size if packet_size itself is not
1101 set. This use is only intended for backward compatibility.
1102 {line_delimiter, 0 =< byte() =< 255}:
1104 For packet type line, sets the delimiting byte. Default is
1105 the latin-1 character $\n.
1106 Examples:
1108 > erlang:decode_packet(1,<<3,"abcd">>,[]).
1110 {ok,<<"abc">>,<<"d">>}
1111 > erlang:decode_packet(1,<<5,"abcd">>,[]).
1112 {more,6}
1113 erlang:delete_element(Index, Tuple1) -> Tuple2
1115 Types:
1117 Index = integer() >= 1
1119 1..tuple_size(Tuple1)
1120 Tuple1 = Tuple2 = tuple()
1121 Returns a new tuple with element at Index removed from tuple
1123 Tuple1, for example:
1124 > erlang:delete_element(2, {one, two, three}).
1126 {one,three}
1127 delete_module(Module) -> true | undefined
1129 Types:
1131 Module = module()
1133 Makes the current code for Module become old code and deletes
1135 all references for this module from the export table. Returns
1136 undefined if the module does not exist, otherwise true.
1137 Warning:
1139 This BIF is intended for the code server (see code(3)) and is
1140 not to be used elsewhere.
1141 Failure: badarg if there already is an old version of Module.
1144 demonitor(MonitorRef) -> true
1146 Types:
1148 MonitorRef = reference()
1150 If MonitorRef is a reference that the calling process obtained
1152 by calling monitor/2, this monitoring is turned off. If the mon‐
1153 itoring is already turned off, nothing happens.
1154 Once demonitor(MonitorRef) has returned, it is guaranteed that
1156 no {'DOWN', MonitorRef, _, _, _} message, because of the moni‐
1157 tor, will be placed in the caller message queue in the future.
1158 However, a {'DOWN', MonitorRef, _, _, _} message can have been
1159 placed in the caller message queue before the call. It is there‐
1160 fore usually advisable to remove such a 'DOWN' message from the
1161 message queue after monitoring has been stopped. demonitor(Moni‐
1162 torRef, [flush]) can be used instead of demonitor(MonitorRef) if
1163 this cleanup is wanted.
1164 Note:
1166 Before Erlang/OTP R11B (ERTS 5.5) demonitor/1 behaved completely
1167 asynchronously, that is, the monitor was active until the
1168 "demonitor signal" reached the monitored entity. This had one
1169 undesirable effect. You could never know when you were guaran‐
1170 teed not to receive a DOWN message because of the monitor.
1171 The current behavior can be viewed as two combined operations:
1173 asynchronously send a "demonitor signal" to the monitored entity
1174 and ignore any future results of the monitor.
1175 Failure: It is an error if MonitorRef refers to a monitoring
1178 started by another process. Not all such cases are cheap to
1179 check. If checking is cheap, the call fails with badarg, for
1180 example if MonitorRef is a remote reference.
1181 demonitor(MonitorRef, OptionList) -> boolean()
1183 Types:
1185 MonitorRef = reference()
1187 OptionList = [Option]
1188 Option = flush | info
1189 The returned value is true unless info is part of OptionList.
1191 demonitor(MonitorRef, []) is equivalent to demonitor(Monitor‐
1193 Ref).
1194 Options:
1196 flush:
1198 Removes (one) {_, MonitorRef, _, _, _} message, if there is
1199 one, from the caller message queue after monitoring has been
1200 stopped.
1201 Calling demonitor(MonitorRef, [flush]) is equivalent to the
1203 following, but more efficient:
1204 demonitor(MonitorRef),
1206 receive
1207 {_, MonitorRef, _, _, _} ->
1208 true
1209 after 0 ->
1210 true
1211 end
1212 info:
1214 The returned value is one of the following:
1215 true:
1217 The monitor was found and removed. In this case, no 'DOWN'
1218 message corresponding to this monitor has been delivered
1219 and will not be delivered.
1220 false:
1222 The monitor was not found and could not be removed. This
1223 probably because someone already has placed a 'DOWN' mes‐
1224 sage corresponding to this monitor in the caller message
1225 queue.
1226 If option info is combined with option flush, false is
1228 returned if a flush was needed, otherwise true.
1229 Note:
1231 More options can be added in a future release.
1232 Failures:
1235 badarg:
1237 If OptionList is not a list.
1238 badarg:
1240 If Option is an invalid option.
1241 badarg:
1243 The same failure as for demonitor/1.
1244 disconnect_node(Node) -> boolean() | ignored
1246 Types:
1248 Node = node()
1250 Forces the disconnection of a node. This appears to the node
1252 Node as if the local node has crashed. This BIF is mainly used
1253 in the Erlang network authentication protocols.
1254 Returns true if disconnection succeeds, otherwise false. If the
1256 local node is not alive, ignored is returned.
1257 erlang:display(Term) -> true
1259 Types:
1261 Term = term()
1263 Prints a text representation of Term on the standard output.
1265 Warning:
1267 This BIF is intended for debugging only.
1268 erlang:dist_ctrl_get_data(DHandle) -> Data | none
1271 Types:
1273 DHandle = dist_handle()
1275 Data = iodata()
1276 Get distribution channel data from the local node that is to be
1278 passed to the remote node. The distribution channel is identi‐
1279 fied by DHandle. If no data is available, the atom none is
1280 returned. One can request to be informed by a message when more
1281 data is available by calling erlang:dist_ctrl_get_data_notifica‐
1282 tion(DHandle).
1283 Note:
1285 Only the process registered as distribution controller for the
1286 distribution channel identified by DHandle is allowed to call
1287 this function.
1288 This function is used when implementing an alternative distribu‐
1291 tion carrier using processes as distribution controllers. DHan‐
1292 dle is retrived via the callback f_handshake_complete. More
1293 information can be found in the documentation of ERTS User's
1294 Guide ➜ How to implement an Alternative Carrier for the Erlang
1295 Distribution ➜ Distribution Module.
1296 erlang:dist_ctrl_get_data_notification(DHandle) -> ok
1298 Types:
1300 DHandle = dist_handle()
1302 Request notification when more data is available to fetch using
1304 erlang:dist_ctrl_get_data(DHandle) for the distribution channel
1305 identified by DHandle. When more data is present, the caller
1306 will be sent the message dist_data. Once a dist_data messages
1307 has been sent, no more dist_data messages will be sent until the
1308 dist_ctrl_get_data_notification/1 function has been called
1309 again.
1310 Note:
1312 Only the process registered as distribution controller for the
1313 distribution channel identified by DHandle is allowed to call
1314 this function.
1315 This function is used when implementing an alternative distribu‐
1318 tion carrier using processes as distribution controllers. DHan‐
1319 dle is retrived via the callback f_handshake_complete. More
1320 information can be found in the documentation of ERTS User's
1321 Guide ➜ How to implement an Alternative Carrier for the Erlang
1322 Distribution ➜ Distribution Module.
1323 erlang:dist_ctrl_input_handler(DHandle, InputHandler) -> ok
1325 Types:
1327 DHandle = dist_handle()
1329 InputHandler = pid()
1330 Register an alternate input handler process for the distribution
1332 channel identified by DHandle. Once this function has been
1333 called, InputHandler is the only process allowed to call
1334 erlang:dist_ctrl_put_data(DHandle, Data) with the DHandle iden‐
1335 tifing this distribution channel.
1336 Note:
1338 Only the process registered as distribution controller for the
1339 distribution channel identified by DHandle is allowed to call
1340 this function.
1341 This function is used when implementing an alternative distribu‐
1344 tion carrier using processes as distribution controllers. DHan‐
1345 dle is retrived via the callback f_handshake_complete. More
1346 information can be found in the documentation of ERTS User's
1347 Guide ➜ How to implement an Alternative Carrier for the Erlang
1348 Distribution ➜ Distribution Module.
1349 erlang:dist_ctrl_put_data(DHandle, Data) -> ok
1351 Types:
1353 DHandle = dist_handle()
1355 Data = iodata()
1356 Deliver distribution channel data from a remote node to the
1358 local node.
1359 Note:
1361 Only the process registered as distribution controller for the
1362 distribution channel identified by DHandle is allowed to call
1363 this function unless an alternate input handler process has been
1364 registered using erlang:dist_ctrl_input_handler(DHandle,
1365 InputHandler). If an alternate input handler has been regis‐
1366 tered, only the registered input handler process is allowed to
1367 call this function.
1368 This function is used when implementing an alternative distribu‐
1371 tion carrier using processes as distribution controllers. DHan‐
1372 dle is retrived via the callback f_handshake_complete. More
1373 information can be found in the documentation of ERTS User's
1374 Guide ➜ How to implement an Alternative Carrier for the Erlang
1375 Distribution ➜ Distribution Module.
1376 element(N, Tuple) -> term()
1378 Types:
1380 N = integer() >= 1
1382 1..tuple_size(Tuple)
1383 Tuple = tuple()
1384 Returns the Nth element (numbering from 1) of Tuple, for exam‐
1386 ple:
1387 > element(2, {a, b, c}).
1389 b
1390 Allowed in guard tests.
1392 erase() -> [{Key, Val}]
1394 Types:
1396 Key = Val = term()
1398 Returns the process dictionary and deletes it, for example:
1400 > put(key1, {1, 2, 3}),
1402 put(key2, [a, b, c]),
1403 erase().
1404 [{key1,{1,2,3}},{key2,[a,b,c]}]
1405 erase(Key) -> Val | undefined
1407 Types:
1409 Key = Val = term()
1411 Returns the value Val associated with Key and deletes it from
1413 the process dictionary. Returns undefined if no value is associ‐
1414 ated with Key. Example:
1415 > put(key1, {merry, lambs, are, playing}),
1417 X = erase(key1),
1418 {X, erase(key1)}.
1419 {{merry,lambs,are,playing},undefined}
1420 error(Reason) -> no_return()
1422 Types:
1424 Reason = term()
1426 Stops the execution of the calling process with the reason Rea‐
1428 son, where Reason is any term. The exit reason is {Reason,
1429 Where}, where Where is a list of the functions most recently
1430 called (the current function first). As evaluating this function
1431 causes the process to terminate, it has no return value. Exam‐
1432 ple:
1433 > catch error(foobar).
1435 {'EXIT',{foobar,[{shell,apply_fun,3,
1436 [{file,"shell.erl"},{line,906}]},
1437 {erl_eval,do_apply,6,[{file,"erl_eval.erl"},{line,677}]},
1438 {erl_eval,expr,5,[{file,"erl_eval.erl"},{line,430}]},
1439 {shell,exprs,7,[{file,"shell.erl"},{line,687}]},
1440 {shell,eval_exprs,7,[{file,"shell.erl"},{line,642}]},
1441 {shell,eval_loop,3,[{file,"shell.erl"},{line,627}]}]}}
1442 error(Reason, Args) -> no_return()
1445 Types:
1447 Reason = term()
1449 Args = [term()]
1450 Stops the execution of the calling process with the reason Rea‐
1452 son, where Reason is any term. The exit reason is {Reason,
1453 Where}, where Where is a list of the functions most recently
1454 called (the current function first). Args is expected to be the
1455 list of arguments for the current function; in Beam it is used
1456 to provide the arguments for the current function in the term
1457 Where. As evaluating this function causes the process to termi‐
1458 nate, it has no return value.
1459 exit(Reason) -> no_return()
1461 Types:
1463 Reason = term()
1465 Stops the execution of the calling process with exit reason Rea‐
1467 son, where Reason is any term. As evaluating this function
1468 causes the process to terminate, it has no return value. Exam‐
1469 ple:
1470 > exit(foobar).
1472 ** exception exit: foobar
1473 > catch exit(foobar).
1474 {'EXIT',foobar}
1475 exit(Pid, Reason) -> true
1477 Types:
1479 Pid = pid() | port()
1481 Reason = term()
1482 Sends an exit signal with exit reason Reason to the process or
1484 port identified by Pid.
1485 The following behavior applies if Reason is any term, except
1487 normal or kill:
1488 * If Pid is not trapping exits, Pid itself exits with exit
1490 reason Reason.
1491 * If Pid is trapping exits, the exit signal is transformed
1493 into a message {'EXIT', From, Reason} and delivered to the
1494 message queue of Pid.
1495 * From is the process identifier of the process that sent the
1497 exit signal. See also process_flag/2.
1498 If Reason is the atom normal, Pid does not exit. If it is trap‐
1500 ping exits, the exit signal is transformed into a message
1501 {'EXIT', From, normal} and delivered to its message queue.
1502 If Reason is the atom kill, that is, if exit(Pid, kill) is
1504 called, an untrappable exit signal is sent to Pid, which uncon‐
1505 ditionally exits with exit reason killed.
1506 erlang:external_size(Term) -> integer() >= 0
1508 Types:
1510 Term = term()
1512 Calculates, without doing the encoding, the maximum byte size
1514 for a term encoded in the Erlang external term format. The fol‐
1515 lowing condition applies always:
1516 > Size1 = byte_size(term_to_binary(Term)),
1518 > Size2 = erlang:external_size(Term),
1519 > true = Size1 =< Size2.
1520 true
1521 This is equivalent to a call to:
1523 erlang:external_size(Term, [])
1525 erlang:external_size(Term, Options) -> integer() >= 0
1527 Types:
1529 Term = term()
1531 Options = [{minor_version, Version :: integer() >= 0}]
1532 Calculates, without doing the encoding, the maximum byte size
1534 for a term encoded in the Erlang external term format. The fol‐
1535 lowing condition applies always:
1536 > Size1 = byte_size(term_to_binary(Term, Options)),
1538 > Size2 = erlang:external_size(Term, Options),
1539 > true = Size1 =< Size2.
1540 true
1541 Option {minor_version, Version} specifies how floats are
1543 encoded. For a detailed description, see term_to_binary/2.
1544 float(Number) -> float()
1546 Types:
1548 Number = number()
1550 Returns a float by converting Number to a float, for example:
1552 > float(55).
1554 55.0
1555 Allowed in guard tests.
1557 Note:
1559 If used on the top level in a guard, it tests whether the argu‐
1560 ment is a floating point number; for clarity, use is_float/1
1561 instead.
1562 When float/1 is used in an expression in a guard, such as
1564 'float(A) == 4.0', it converts a number as described earlier.
1565 float_to_binary(Float) -> binary()
1568 Types:
1570 Float = float()
1572 The same as float_to_binary(Float,[{scientific,20}]).
1574 float_to_binary(Float, Options) -> binary()
1576 Types:
1578 Float = float()
1580 Options = [Option]
1581 Option =
1582 {decimals, Decimals :: 0..253} |
1583 {scientific, Decimals :: 0..249} |
1584 compact
1585 Returns a binary corresponding to the text representation of
1587 Float using fixed decimal point formatting. Options behaves in
1588 the same way as float_to_list/2. Examples:
1589 > float_to_binary(7.12, [{decimals, 4}]).
1591 <<"7.1200">>
1592 > float_to_binary(7.12, [{decimals, 4}, compact]).
1593 <<"7.12">>
1594 float_to_list(Float) -> string()
1596 Types:
1598 Float = float()
1600 The same as float_to_list(Float,[{scientific,20}]).
1602 float_to_list(Float, Options) -> string()
1604 Types:
1606 Float = float()
1608 Options = [Option]
1609 Option =
1610 {decimals, Decimals :: 0..253} |
1611 {scientific, Decimals :: 0..249} |
1612 compact
1613 Returns a string corresponding to the text representation of
1615 Float using fixed decimal point formatting.
1616 Available options:
1618 * If option decimals is specified, the returned value contains
1620 at most Decimals number of digits past the decimal point. If
1621 the number does not fit in the internal static buffer of 256
1622 bytes, the function throws badarg.
1623 * If option compact is specified, the trailing zeros at the
1625 end of the list are truncated. This option is only meaning‐
1626 ful together with option decimals.
1627 * If option scientific is specified, the float is formatted
1629 using scientific notation with Decimals digits of precision.
1630 * If Options is [], the function behaves as float_to_list/1.
1632 Examples:
1634 > float_to_list(7.12, [{decimals, 4}]).
1636 "7.1200"
1637 > float_to_list(7.12, [{decimals, 4}, compact]).
1638 "7.12"
1639 floor(Number) -> integer()
1641 Types:
1643 Number = number()
1645 Returns the largest integer not greater than Number. For exam‐
1647 ple:
1648 > floor(-10.5).
1650 -11
1651 Allowed in guard tests.
1653 erlang:fun_info(Fun) -> [{Item, Info}]
1655 Types:
1657 Fun = function()
1659 Item =
1660 arity |
1661 env |
1662 index |
1663 name |
1664 module |
1665 new_index |
1666 new_uniq |
1667 pid |
1668 type |
1669 uniq
1670 Info = term()
1671 Returns a list with information about the fun Fun. Each list
1673 element is a tuple. The order of the tuples is undefined, and
1674 more tuples can be added in a future release.
1675 Warning:
1677 This BIF is mainly intended for debugging, but it can sometimes
1678 be useful in library functions that need to verify, for example,
1679 the arity of a fun.
1680 Two types of funs have slightly different semantics:
1683 * A fun created by fun M:F/A is called an external fun. Call‐
1685 ing it will always call the function F with arity A in the
1686 latest code for module M. Notice that module M does not even
1687 need to be loaded when the fun fun M:F/A is created.
1688 * All other funs are called local. When a local fun is called,
1690 the same version of the code that created the fun is called
1691 (even if a newer version of the module has been loaded).
1692 The following elements are always present in the list for both
1694 local and external funs:
1695 {type, Type}:
1697 Type is local or external.
1698 {module, Module}:
1700 Module (an atom) is the module name.
1701 If Fun is a local fun, Module is the module in which the fun
1703 is defined.
1704 If Fun is an external fun, Module is the module that the fun
1706 refers to.
1707 {name, Name}:
1709 Name (an atom) is a function name.
1710 If Fun is a local fun, Name is the name of the local func‐
1712 tion that implements the fun. (This name was generated by
1713 the compiler, and is only of informational use. As it is a
1714 local function, it cannot be called directly.) If no code is
1715 currently loaded for the fun, [] is returned instead of an
1716 atom.
1717 If Fun is an external fun, Name is the name of the exported
1719 function that the fun refers to.
1720 {arity, Arity}:
1722 Arity is the number of arguments that the fun is to be
1723 called with.
1724 {env, Env}:
1726 Env (a list) is the environment or free variables for the
1727 fun. For external funs, the returned list is always empty.
1728 The following elements are only present in the list if Fun is
1730 local:
1731 {pid, Pid}:
1733 Pid is the process identifier of the process that originally
1734 created the fun.
1735 {index, Index}:
1737 Index (an integer) is an index into the module fun table.
1738 {new_index, Index}:
1740 Index (an integer) is an index into the module fun table.
1741 {new_uniq, Uniq}:
1743 Uniq (a binary) is a unique value for this fun. It is calcu‐
1744 lated from the compiled code for the entire module.
1745 {uniq, Uniq}:
1747 Uniq (an integer) is a unique value for this fun. As from
1748 Erlang/OTP R15, this integer is calculated from the compiled
1749 code for the entire module. Before Erlang/OTP R15, this
1750 integer was based on only the body of the fun.
1751 erlang:fun_info(Fun, Item) -> {Item, Info}
1753 Types:
1755 Fun = function()
1757 Item = fun_info_item()
1758 Info = term()
1759 fun_info_item() =
1760 arity |
1761 env |
1762 index |
1763 name |
1764 module |
1765 new_index |
1766 new_uniq |
1767 pid |
1768 type |
1769 uniq
1770 Returns information about Fun as specified by Item, in the form
1772 {Item,Info}.
1773 For any fun, Item can be any of the atoms module, name, arity,
1775 env, or type.
1776 For a local fun, Item can also be any of the atoms index,
1778 new_index, new_uniq, uniq, and pid. For an external fun, the
1779 value of any of these items is always the atom undefined.
1780 See erlang:fun_info/1.
1782 erlang:fun_to_list(Fun) -> string()
1784 Types:
1786 Fun = function()
1788 Returns a string corresponding to the text representation of
1790 Fun.
1791 erlang:function_exported(Module, Function, Arity) -> boolean()
1793 Types:
1795 Module = module()
1797 Function = atom()
1798 Arity = arity()
1799 Returns true if the module Module is loaded and contains an
1801 exported function Function/Arity, or if there is a BIF (a built-
1802 in function implemented in C) with the specified name, otherwise
1803 returns false.
1804 Note:
1806 This function used to return false for BIFs before Erlang/OTP
1807 18.0.
1808 garbage_collect() -> true
1811 Forces an immediate garbage collection of the executing process.
1813 The function is not to be used unless it has been noticed (or
1814 there are good reasons to suspect) that the spontaneous garbage
1815 collection will occur too late or not at all.
1816 Warning:
1818 Improper use can seriously degrade system performance.
1819 garbage_collect(Pid) -> GCResult
1822 Types:
1824 Pid = pid()
1826 GCResult = boolean()
1827 The same as garbage_collect(Pid, []).
1829 garbage_collect(Pid, OptionList) -> GCResult | async
1831 Types:
1833 Pid = pid()
1835 RequestId = term()
1836 Option = {async, RequestId} | {type, major | minor}
1837 OptionList = [Option]
1838 GCResult = boolean()
1839 Garbage collects the node local process identified by Pid.
1841 Option:
1843 {async, RequestId}:
1845 The function garbage_collect/2 returns the value async imme‐
1846 diately after the request has been sent. When the request
1847 has been processed, the process that called this function is
1848 passed a message on the form {garbage_collect, RequestId,
1849 GCResult}.
1850 {type, 'major' | 'minor'}:
1852 Triggers garbage collection of requested type. Default value
1853 is 'major', which would trigger a fullsweep GC. The option
1854 'minor' is considered a hint and may lead to either minor or
1855 major GC run.
1856 If Pid equals self(), and no async option has been passed, the
1858 garbage collection is performed at once, that is, the same as
1859 calling garbage_collect/0. Otherwise a request for garbage col‐
1860 lection is sent to the process identified by Pid, and will be
1861 handled when appropriate. If no async option has been passed,
1862 the caller blocks until GCResult is available and can be
1863 returned.
1864 GCResult informs about the result of the garbage collection
1866 request as follows:
1867 true:
1869 The process identified by Pid has been garbage collected.
1870 false:
1872 No garbage collection was performed, as the process identi‐
1873 fied by Pid terminated before the request could be satis‐
1874 fied.
1875 Notice that the same caveats apply as for garbage_collect/0.
1877 Failures:
1879 badarg:
1881 If Pid is not a node local process identifier.
1882 badarg:
1884 If OptionList is an invalid list of options.
1885 get() -> [{Key, Val}]
1887 Types:
1889 Key = Val = term()
1891 Returns the process dictionary as a list of {Key, Val} tuples,
1893 for example:
1894 > put(key1, merry),
1896 put(key2, lambs),
1897 put(key3, {are, playing}),
1898 get().
1899 [{key1,merry},{key2,lambs},{key3,{are,playing}}]
1900 get(Key) -> Val | undefined
1902 Types:
1904 Key = Val = term()
1906 Returns the value Val associated with Key in the process dictio‐
1908 nary, or undefined if Key does not exist. Example:
1909 > put(key1, merry),
1911 put(key2, lambs),
1912 put({any, [valid, term]}, {are, playing}),
1913 get({any, [valid, term]}).
1914 {are,playing}
1915 erlang:get_cookie() -> Cookie | nocookie
1917 Types:
1919 Cookie = atom()
1921 Returns the magic cookie of the local node if the node is alive,
1923 otherwise the atom nocookie.
1924 get_keys() -> [Key]
1926 Types:
1928 Key = term()
1930 Returns a list of all keys present in the process dictionary,
1932 for example:
1933 > put(dog, {animal,1}),
1935 put(cow, {animal,2}),
1936 put(lamb, {animal,3}),
1937 get_keys().
1938 [dog,cow,lamb]
1939 get_keys(Val) -> [Key]
1941 Types:
1943 Val = Key = term()
1945 Returns a list of keys that are associated with the value Val in
1947 the process dictionary, for example:
1948 > put(mary, {1, 2}),
1950 put(had, {1, 2}),
1951 put(a, {1, 2}),
1952 put(little, {1, 2}),
1953 put(dog, {1, 3}),
1954 put(lamb, {1, 2}),
1955 get_keys({1, 2}).
1956 [mary,had,a,little,lamb]
1957 erlang:get_stacktrace() -> [stack_item()]
1959 Types:
1961 stack_item() =
1963 {Module :: module(),
1964 Function :: atom(),
1965 Arity :: arity() | (Args :: [term()]),
1966 Location ::
1967 [{file, Filename :: string()} |
1968 {line, Line :: integer() >= 1}]}
1969 Warning:
1971 erlang:get_stacktrace/0 is deprecated and will stop working in a
1972 future release.
1973 Instead of using erlang:get_stacktrace/0 to retrieve the call
1976 stack back-trace, use the following syntax:
1977 try Expr
1979 catch
1980 Class:Reason:Stacktrace ->
1981 {Class,Reason,Stacktrace}
1982 end
1983 erlang:get_stacktrace/0 retrieves the call stack back-trace
1985 (stacktrace) for an exception that has just been caught in the
1986 calling process as a list of {Module,Function,Arity,Location}
1987 tuples. Field Arity in the first tuple can be the argument list
1988 of that function call instead of an arity integer, depending on
1989 the exception.
1990 If there has not been any exceptions in a process, the stack‐
1992 trace is []. After a code change for the process, the stacktrace
1993 can also be reset to [].
1994 The stacktrace is the same data as operator catch returns, for
1996 example:
1997 {'EXIT',{badarg,Stacktrace}} = catch abs(x)
1999 Location is a (possibly empty) list of two-tuples that can indi‐
2001 cate the location in the source code of the function. The first
2002 element is an atom describing the type of information in the
2003 second element. The following items can occur:
2004 file:
2006 The second element of the tuple is a string (list of charac‐
2007 ters) representing the filename of the source file of the
2008 function.
2009 line:
2011 The second element of the tuple is the line number (an inte‐
2012 ger > 0) in the source file where the exception occurred or
2013 the function was called.
2014 Warning:
2016 Developers should rely on stacktrace entries only for debugging
2017 purposes.
2018 The VM performs tail call optimization, which does not add new
2020 entries to the stacktrace, and also limits stacktraces to a cer‐
2021 tain depth. Furthermore, compiler options, optimizations and
2022 future changes may add or remove stacktrace entries, causing any
2023 code that expects the stacktrace to be in a certain order or
2024 contain specific items to fail.
2025 The only exception to this rule is error:undef which guarantees
2027 to include the Module, Function and Arity of the attempted func‐
2028 tion as the first stacktrace entry.
2029 See also error/1 and error/2.
2032 group_leader() -> pid()
2034 Returns the process identifier of the group leader for the
2036 process evaluating the function.
2037 Every process is a member of some process group and all groups
2039 have a group leader. All I/O from the group is channeled to the
2040 group leader. When a new process is spawned, it gets the same
2041 group leader as the spawning process. Initially, at system
2042 startup, init is both its own group leader and the group leader
2043 of all processes.
2044 group_leader(GroupLeader, Pid) -> true
2046 Types:
2048 GroupLeader = Pid = pid()
2050 Sets the group leader of Pid to GroupLeader. Typically, this is
2052 used when a process started from a certain shell is to have
2053 another group leader than init.
2054 The group leader should be rarely changed in applications with a
2056 supervision tree, because OTP assumes the group leader of their
2057 processes is their application master.
2058 See also group_leader/0 and OTP design principles related to
2060 starting and stopping applications.
2061 halt() -> no_return()
2063 The same as halt(0, []). Example:
2065 > halt().
2067 os_prompt%
2068 halt(Status) -> no_return()
2070 Types:
2072 Status = integer() >= 0 | abort | string()
2074 The same as halt(Status, []). Example:
2076 > halt(17).
2078 os_prompt% echo $?
2079 17
2080 os_prompt%
2081 halt(Status, Options) -> no_return()
2083 Types:
2085 Status = integer() >= 0 | abort | string()
2087 Options = [Option]
2088 Option = {flush, boolean()}
2089 Status must be a non-negative integer, a string, or the atom
2091 abort. Halts the Erlang runtime system. Has no return value.
2092 Depending on Status, the following occurs:
2093 integer():
2095 The runtime system exits with integer value Status as status
2096 code to the calling environment (OS).
2097 Note:
2099 On many platforms, the OS supports only status codes 0-255. A
2100 too large status code is truncated by clearing the high bits.
2101 string():
2104 An Erlang crash dump is produced with Status as slogan. Then
2105 the runtime system exits with status code 1. The string will
2106 be truncated if longer than 200 characters.
2107 Note:
2109 Before ERTS 9.1 (OTP-20.1) only code points in the range 0-255
2110 was accepted in the string. Now any unicode string is valid.
2111 abort:
2114 The runtime system aborts producing a core dump, if that is
2115 enabled in the OS.
2116 For integer Status, the Erlang runtime system closes all ports
2118 and allows async threads to finish their operations before exit‐
2119 ing. To exit without such flushing, use Option as {flush,false}.
2120 For statuses string() and abort, option flush is ignored and
2122 flushing is not done.
2123 hd(List) -> term()
2125 Types:
2127 List = [term(), ...]
2129 Returns the head of List, that is, the first element, for exam‐
2131 ple:
2132 > hd([1,2,3,4,5]).
2134 1
2135 Allowed in guard tests.
2137 Failure: badarg if List is the empty list [].
2139 erlang:hibernate(Module, Function, Args) -> no_return()
2141 Types:
2143 Module = module()
2145 Function = atom()
2146 Args = [term()]
2147 Puts the calling process into a wait state where its memory
2149 allocation has been reduced as much as possible. This is useful
2150 if the process does not expect to receive any messages soon.
2151 The process is awaken when a message is sent to it, and control
2153 resumes in Module:Function with the arguments specified by Args
2154 with the call stack emptied, meaning that the process terminates
2155 when that function returns. Thus erlang:hibernate/3 never
2156 returns to its caller.
2157 If the process has any message in its message queue, the process
2159 is awakened immediately in the same way as described earlier.
2160 In more technical terms, erlang:hibernate/3 discards the call
2162 stack for the process, and then garbage collects the process.
2163 After this, all live data is in one continuous heap. The heap is
2164 then shrunken to the exact same size as the live data that it
2165 holds (even if that size is less than the minimum heap size for
2166 the process).
2167 If the size of the live data in the process is less than the
2169 minimum heap size, the first garbage collection occurring after
2170 the process is awakened ensures that the heap size is changed to
2171 a size not smaller than the minimum heap size.
2172 Notice that emptying the call stack means that any surrounding
2174 catch is removed and must be re-inserted after hibernation. One
2175 effect of this is that processes started using proc_lib (also
2176 indirectly, such as gen_server processes), are to use
2177 proc_lib:hibernate/3 instead, to ensure that the exception han‐
2178 dler continues to work when the process wakes up.
2179 erlang:insert_element(Index, Tuple1, Term) -> Tuple2
2181 Types:
2183 Index = integer() >= 1
2185 1..tuple_size(Tuple1) + 1
2186 Tuple1 = Tuple2 = tuple()
2187 Term = term()
2188 Returns a new tuple with element Term inserted at position Index
2190 in tuple Tuple1. All elements from position Index and upwards
2191 are pushed one step higher in the new tuple Tuple2. Example:
2192 > erlang:insert_element(2, {one, two, three}, new).
2194 {one,new,two,three}
2195 integer_to_binary(Integer) -> binary()
2197 Types:
2199 Integer = integer()
2201 Returns a binary corresponding to the text representation of
2203 Integer, for example:
2204 > integer_to_binary(77).
2206 <<"77">>
2207 integer_to_binary(Integer, Base) -> binary()
2209 Types:
2211 Integer = integer()
2213 Base = 2..36
2214 Returns a binary corresponding to the text representation of
2216 Integer in base Base, for example:
2217 > integer_to_binary(1023, 16).
2219 <<"3FF">>
2220 integer_to_list(Integer) -> string()
2222 Types:
2224 Integer = integer()
2226 Returns a string corresponding to the text representation of
2228 Integer, for example:
2229 > integer_to_list(77).
2231 "77"
2232 integer_to_list(Integer, Base) -> string()
2234 Types:
2236 Integer = integer()
2238 Base = 2..36
2239 Returns a string corresponding to the text representation of
2241 Integer in base Base, for example:
2242 > integer_to_list(1023, 16).
2244 "3FF"
2245 iolist_size(Item) -> integer() >= 0
2247 Types:
2249 Item = iolist() | binary()
2251 Returns an integer, that is the size in bytes, of the binary
2253 that would be the result of iolist_to_binary(Item), for example:
2254 > iolist_size([1,2|<<3,4>>]).
2256 4
2257 iolist_to_binary(IoListOrBinary) -> binary()
2259 Types:
2261 IoListOrBinary = iolist() | binary()
2263 Returns a binary that is made from the integers and binaries in
2265 IoListOrBinary, for example:
2266 > Bin1 = <<1,2,3>>.
2268 <<1,2,3>>
2269 > Bin2 = <<4,5>>.
2270 <<4,5>>
2271 > Bin3 = <<6>>.
2272 <<6>>
2273 > iolist_to_binary([Bin1,1,[2,3,Bin2],4|Bin3]).
2274 <<1,2,3,1,2,3,4,5,4,6>>
2275 erlang:iolist_to_iovec(IoListOrBinary) -> iovec()
2277 Types:
2279 IoListOrBinary = iolist() | binary()
2281 Returns an iovec that is made from the integers and binaries in
2283 IoListOrBinary.
2284 is_alive() -> boolean()
2286 Returns true if the local node is alive (that is, if the node
2288 can be part of a distributed system), otherwise false.
2289 is_atom(Term) -> boolean()
2291 Types:
2293 Term = term()
2295 Returns true if Term is an atom, otherwise false.
2297 Allowed in guard tests.
2299 is_binary(Term) -> boolean()
2301 Types:
2303 Term = term()
2305 Returns true if Term is a binary, otherwise false.
2307 A binary always contains a complete number of bytes.
2309 Allowed in guard tests.
2311 is_bitstring(Term) -> boolean()
2313 Types:
2315 Term = term()
2317 Returns true if Term is a bitstring (including a binary), other‐
2319 wise false.
2320 Allowed in guard tests.
2322 is_boolean(Term) -> boolean()
2324 Types:
2326 Term = term()
2328 Returns true if Term is the atom true or the atom false (that
2330 is, a boolean). Otherwise returns false.
2331 Allowed in guard tests.
2333 erlang:is_builtin(Module, Function, Arity) -> boolean()
2335 Types:
2337 Module = module()
2339 Function = atom()
2340 Arity = arity()
2341 This BIF is useful for builders of cross-reference tools.
2343 Returns true if Module:Function/Arity is a BIF implemented in C,
2345 otherwise false.
2346 is_float(Term) -> boolean()
2348 Types:
2350 Term = term()
2352 Returns true if Term is a floating point number, otherwise
2354 false.
2355 Allowed in guard tests.
2357 is_function(Term) -> boolean()
2359 Types:
2361 Term = term()
2363 Returns true if Term is a fun, otherwise false.
2365 Allowed in guard tests.
2367 is_function(Term, Arity) -> boolean()
2369 Types:
2371 Term = term()
2373 Arity = arity()
2374 Returns true if Term is a fun that can be applied with Arity
2376 number of arguments, otherwise false.
2377 Allowed in guard tests.
2379 is_integer(Term) -> boolean()
2381 Types:
2383 Term = term()
2385 Returns true if Term is an integer, otherwise false.
2387 Allowed in guard tests.
2389 is_list(Term) -> boolean()
2391 Types:
2393 Term = term()
2395 Returns true if Term is a list with zero or more elements, oth‐
2397 erwise false.
2398 Allowed in guard tests.
2400 is_map(Term) -> boolean()
2402 Types:
2404 Term = term()
2406 Returns true if Term is a map, otherwise false.
2408 Allowed in guard tests.
2410 is_map_key(Key, Map) -> boolean()
2412 Types:
2414 Key = term()
2416 Map = map()
2417 Returns true if map Map contains Key and returns false if it
2419 does not contain the Key.
2420 The call fails with a {badmap,Map} exception if Map is not a
2422 map.
2423 Example:
2425 > Map = #{"42" => value}.
2427 #{"42" => value}
2428 > is_map_key("42",Map).
2429 true
2430 > is_map_key(value,Map).
2431 false
2432 is_number(Term) -> boolean()
2434 Types:
2436 Term = term()
2438 Returns true if Term is an integer or a floating point number.
2440 Otherwise returns false.
2441 Allowed in guard tests.
2443 is_pid(Term) -> boolean()
2445 Types:
2447 Term = term()
2449 Returns true if Term is a process identifier, otherwise false.
2451 Allowed in guard tests.
2453 is_port(Term) -> boolean()
2455 Types:
2457 Term = term()
2459 Returns true if Term is a port identifier, otherwise false.
2461 Allowed in guard tests.
2463 is_process_alive(Pid) -> boolean()
2465 Types:
2467 Pid = pid()
2469 Pid must refer to a process at the local node.
2471 Returns true if the process exists and is alive, that is, is not
2473 exiting and has not exited. Otherwise returns false.
2474 is_record(Term, RecordTag) -> boolean()
2476 Types:
2478 Term = term()
2480 RecordTag = atom()
2481 Returns true if Term is a tuple and its first element is Record‐
2483 Tag. Otherwise returns false.
2484 Note:
2486 Normally the compiler treats calls to is_record/2 especially. It
2487 emits code to verify that Term is a tuple, that its first ele‐
2488 ment is RecordTag, and that the size is correct. However, if
2489 RecordTag is not a literal atom, the BIF is_record/2 is called
2490 instead and the size of the tuple is not verified.
2491 Allowed in guard tests, if RecordTag is a literal atom.
2494 is_record(Term, RecordTag, Size) -> boolean()
2496 Types:
2498 Term = term()
2500 RecordTag = atom()
2501 Size = integer() >= 0
2502 RecordTag must be an atom.
2504 Returns true if Term is a tuple, its first element is RecordTag,
2506 and its size is Size. Otherwise returns false.
2507 Allowed in guard tests if RecordTag is a literal atom and Size
2509 is a literal integer.
2510 Note:
2512 This BIF is documented for completeness. Usually is_record/2 is
2513 to be used.
2514 is_reference(Term) -> boolean()
2517 Types:
2519 Term = term()
2521 Returns true if Term is a reference, otherwise false.
2523 Allowed in guard tests.
2525 is_tuple(Term) -> boolean()
2527 Types:
2529 Term = term()
2531 Returns true if Term is a tuple, otherwise false.
2533 Allowed in guard tests.
2535 length(List) -> integer() >= 0
2537 Types:
2539 List = [term()]
2541 Returns the length of List, for example:
2543 > length([1,2,3,4,5,6,7,8,9]).
2545 9
2546 Allowed in guard tests.
2548 link(PidOrPort) -> true
2550 Types:
2552 PidOrPort = pid() | port()
2554 Creates a link between the calling process and another process
2556 (or port) PidOrPort, if there is not such a link already. If a
2557 process attempts to create a link to itself, nothing is done.
2558 Returns true.
2559 If PidOrPort does not exist, the behavior of the BIF depends on
2561 if the calling process is trapping exits or not (see
2562 process_flag/2):
2563 * If the calling process is not trapping exits, and checking
2565 PidOrPort is cheap (that is, if PidOrPort is local), link/1
2566 fails with reason noproc.
2567 * Otherwise, if the calling process is trapping exits, and/or
2569 PidOrPort is remote, link/1 returns true, but an exit signal
2570 with reason noproc is sent to the calling process.
2571 list_to_atom(String) -> atom()
2573 Types:
2575 String = string()
2577 Returns the atom whose text representation is String.
2579 As from Erlang/OTP 20, String may contain any Unicode character.
2581 Earlier versions allowed only ISO-latin-1 characters as the
2582 implementation did not allow Unicode characters above 255. For
2583 more information on Unicode support in atoms, see note on UTF-8
2584 encoded atoms in section "External Term Format" in the User's
2585 Guide.
2586 Example:
2588 > list_to_atom("Erlang").
2590 list_to_binary(IoList) -> binary()
2592 Types:
2594 IoList = iolist()
2596 Returns a binary that is made from the integers and binaries in
2598 IoList, for example:
2599 > Bin1 = <<1,2,3>>.
2601 <<1,2,3>>
2602 > Bin2 = <<4,5>>.
2603 <<4,5>>
2604 > Bin3 = <<6>>.
2605 <<6>>
2606 > list_to_binary([Bin1,1,[2,3,Bin2],4|Bin3]).
2607 <<1,2,3,1,2,3,4,5,4,6>>
2608 list_to_bitstring(BitstringList) -> bitstring()
2610 Types:
2612 BitstringList = bitstring_list()
2614 bitstring_list() =
2615 maybe_improper_list(byte() | bitstring() | bitstring_list(),
2616 bitstring() | [])
2617 Returns a bitstring that is made from the integers and bit‐
2619 strings in BitstringList. (The last tail in BitstringList is
2620 allowed to be a bitstring.) Example:
2621 > Bin1 = <<1,2,3>>.
2623 <<1,2,3>>
2624 > Bin2 = <<4,5>>.
2625 <<4,5>>
2626 > Bin3 = <<6,7:4>>.
2627 <<6,7:4>>
2628 > list_to_bitstring([Bin1,1,[2,3,Bin2],4|Bin3]).
2629 <<1,2,3,1,2,3,4,5,4,6,7:4>>
2630 list_to_existing_atom(String) -> atom()
2632 Types:
2634 String = string()
2636 Returns the atom whose text representation is String, but only
2638 if there already exists such atom.
2639 Failure: badarg if there does not already exist an atom whose
2641 text representation is String.
2642 Note:
2644 Note that the compiler may optimize away atoms. For example, the
2645 compiler will rewrite atom_to_list(some_atom) to "some_atom". If
2646 that expression is the only mention of the atom some_atom in the
2647 containing module, the atom will not be created when the module
2648 is loaded, and a subsequent call to list_to_exist‐
2649 ing_atom("some_atom") will fail.
2650 list_to_float(String) -> float()
2653 Types:
2655 String = string()
2657 Returns the float whose text representation is String, for exam‐
2659 ple:
2660 > list_to_float("2.2017764e+0").
2662 2.2017764
2663 Failure: badarg if String contains a bad representation of a
2665 float.
2666 list_to_integer(String) -> integer()
2668 Types:
2670 String = string()
2672 Returns an integer whose text representation is String, for
2674 example:
2675 > list_to_integer("123").
2677 123
2678 Failure: badarg if String contains a bad representation of an
2680 integer.
2681 list_to_integer(String, Base) -> integer()
2683 Types:
2685 String = string()
2687 Base = 2..36
2688 Returns an integer whose text representation in base Base is
2690 String, for example:
2691 > list_to_integer("3FF", 16).
2693 1023
2694 Failure: badarg if String contains a bad representation of an
2696 integer.
2697 list_to_pid(String) -> pid()
2699 Types:
2701 String = string()
2703 Returns a process identifier whose text representation is a
2705 String, for example:
2706 > list_to_pid("<0.4.1>").
2708 <0.4.1>
2709 Failure: badarg if String contains a bad representation of a
2711 process identifier.
2712 Warning:
2714 This BIF is intended for debugging and is not to be used in
2715 application programs.
2716 list_to_port(String) -> port()
2719 Types:
2721 String = string()
2723 Returns a port identifier whose text representation is a String,
2725 for example:
2726 > list_to_port("#Port<0.4>").
2728 #Port<0.4>
2729 Failure: badarg if String contains a bad representation of a
2731 port identifier.
2732 Warning:
2734 This BIF is intended for debugging and is not to be used in
2735 application programs.
2736 list_to_ref(String) -> reference()
2739 Types:
2741 String = string()
2743 Returns a reference whose text representation is a String, for
2745 example:
2746 > list_to_ref("#Ref<0.4192537678.4073193475.71181>").
2748 #Ref<0.4192537678.4073193475.71181>
2749 Failure: badarg if String contains a bad representation of a
2751 reference.
2752 Warning:
2754 This BIF is intended for debugging and is not to be used in
2755 application programs.
2756 list_to_tuple(List) -> tuple()
2759 Types:
2761 List = [term()]
2763 Returns a tuple corresponding to List, for example
2765 > list_to_tuple([share, ['Ericsson_B', 163]]).
2767 {share, ['Ericsson_B', 163]}
2768 List can contain any Erlang terms.
2770 load_module(Module, Binary) -> {module, Module} | {error, Reason}
2772 Types:
2774 Module = module()
2776 Binary = binary()
2777 Reason = badfile | not_purged | on_load
2778 If Binary contains the object code for module Module, this BIF
2780 loads that object code. If the code for module Module already
2781 exists, all export references are replaced so they point to the
2782 newly loaded code. The previously loaded code is kept in the
2783 system as old code, as there can still be processes executing
2784 that code.
2785 Returns either {module, Module}, or {error, Reason} if loading
2787 fails. Reason is one of the following:
2788 badfile:
2790 The object code in Binary has an incorrect format or the
2791 object code contains code for another module than Module.
2792 not_purged:
2794 Binary contains a module that cannot be loaded because old
2795 code for this module already exists.
2796 Warning:
2798 This BIF is intended for the code server (see code(3)) and is
2799 not to be used elsewhere.
2800 erlang:load_nif(Path, LoadInfo) -> ok | Error
2803 Types:
2805 Path = string()
2807 LoadInfo = term()
2808 Error = {error, {Reason, Text :: string()}}
2809 Reason =
2810 load_failed | bad_lib | load | reload | upgrade |
2811 old_code
2812 Loads and links a dynamic library containing native implemented
2814 functions (NIFs) for a module. Path is a file path to the share‐
2815 able object/dynamic library file minus the OS-dependent file
2816 extension (.so for Unix and .dll for Windows). Notice that on
2817 most OSs the library has to have a different name on disc when
2818 an upgrade of the nif is done. If the name is the same, but the
2819 contents differ, the old library may be loaded instead. For
2820 information on how to implement a NIF library, see erl_nif(3).
2821 LoadInfo can be any term. It is passed on to the library as part
2823 of the initialization. A good practice is to include a module
2824 version number to support future code upgrade scenarios.
2825 The call to load_nif/2 must be made directly from the Erlang
2827 code of the module that the NIF library belongs to. It returns
2828 either ok, or {error,{Reason,Text}} if loading fails. Reason is
2829 one of the following atoms while Text is a human readable string
2830 that can give more information about the failure:
2831 load_failed:
2833 The OS failed to load the NIF library.
2834 bad_lib:
2836 The library did not fulfill the requirements as a NIF
2837 library of the calling module.
2838 load | upgrade:
2840 The corresponding library callback was unsuccessful.
2841 reload:
2843 A NIF library is already loaded for this module instance.
2844 The previously deprecated reload feature was removed in OTP
2845 20.
2846 old_code:
2848 The call to load_nif/2 was made from the old code of a mod‐
2849 ule that has been upgraded; this is not allowed.
2850 notsup:
2852 Lack of support. Such as loading NIF library for a HiPE com‐
2853 piled module.
2854 erlang:loaded() -> [Module]
2856 Types:
2858 Module = module()
2860 Returns a list of all loaded Erlang modules (current and old
2862 code), including preloaded modules.
2863 See also code(3).
2865 erlang:localtime() -> DateTime
2867 Types:
2869 DateTime = calendar:datetime()
2871 Returns the current local date and time, {{Year, Month, Day},
2873 {Hour, Minute, Second}}, for example:
2874 > erlang:localtime().
2876 {{1996,11,6},{14,45,17}}
2877 The time zone and Daylight Saving Time correction depend on the
2879 underlying OS.
2880 erlang:localtime_to_universaltime(Localtime) -> Universaltime
2882 Types:
2884 Localtime = Universaltime = calendar:datetime()
2886 Converts local date and time to Universal Time Coordinated
2888 (UTC), if supported by the underlying OS. Otherwise no conver‐
2889 sion is done and Localtime is returned. Example:
2890 > erlang:localtime_to_universaltime({{1996,11,6},{14,45,17}}).
2892 {{1996,11,6},{13,45,17}}
2893 Failure: badarg if Localtime denotes an invalid date and time.
2895 erlang:localtime_to_universaltime(Localtime, IsDst) ->
2897 Universaltime
2898 Types:
2900 Localtime = Universaltime = calendar:datetime()
2902 IsDst = true | false | undefined
2903 Converts local date and time to Universal Time Coordinated (UTC)
2905 as erlang:localtime_to_universaltime/1, but the caller decides
2906 if Daylight Saving Time is active.
2907 If IsDst == true, Localtime is during Daylight Saving Time, if
2909 IsDst == false it is not. If IsDst == undefined, the underlying
2910 OS can guess, which is the same as calling erlang:local‐
2911 time_to_universaltime(Localtime).
2912 Examples:
2914 > erlang:localtime_to_universaltime({{1996,11,6},{14,45,17}}, true).
2916 {{1996,11,6},{12,45,17}}
2917 > erlang:localtime_to_universaltime({{1996,11,6},{14,45,17}}, false).
2918 {{1996,11,6},{13,45,17}}
2919 > erlang:localtime_to_universaltime({{1996,11,6},{14,45,17}}, undefined).
2920 {{1996,11,6},{13,45,17}}
2921 Failure: badarg if Localtime denotes an invalid date and time.
2923 make_ref() -> reference()
2925 Returns a unique reference. The reference is unique among con‐
2927 nected nodes.
2928 Warning:
2930 Known issue: When a node is restarted multiple times with the
2931 same node name, references created on a newer node can be mis‐
2932 taken for a reference created on an older node with the same
2933 node name.
2934 erlang:make_tuple(Arity, InitialValue) -> tuple()
2937 Types:
2939 Arity = arity()
2941 InitialValue = term()
2942 Creates a new tuple of the specified Arity, where all elements
2944 are InitialValue, for example:
2945 > erlang:make_tuple(4, []).
2947 {[],[],[],[]}
2948 erlang:make_tuple(Arity, DefaultValue, InitList) -> tuple()
2950 Types:
2952 Arity = arity()
2954 DefaultValue = term()
2955 InitList = [{Position :: integer() >= 1, term()}]
2956 Creates a tuple of size Arity, where each element has value
2958 DefaultValue, and then fills in values from InitList. Each list
2959 element in InitList must be a two-tuple, where the first element
2960 is a position in the newly created tuple and the second element
2961 is any term. If a position occurs more than once in the list,
2962 the term corresponding to the last occurrence is used. Example:
2963 > erlang:make_tuple(5, [], [{2,ignored},{5,zz},{2,aa}]).
2965 {[],aa,[],[],zz}
2966 map_get(Key, Map) -> Value
2968 Types:
2970 Map = map()
2972 Key = Value = any()
2973 Returns value Value associated with Key if Map contains Key.
2975 The call fails with a {badmap,Map} exception if Map is not a
2977 map, or with a {badkey,Key} exception if no value is associated
2978 with Key.
2979 Example:
2981 > Key = 1337,
2983 Map = #{42 => value_two,1337 => "value one","a" => 1},
2984 map_get(Key,Map).
2985 "value one"
2986 map_size(Map) -> integer() >= 0
2988 Types:
2990 Map = map()
2992 Returns an integer, which is the number of key-value pairs in
2994 Map, for example:
2995 > map_size(#{a=>1, b=>2, c=>3}).
2997 3
2998 Allowed in guard tests.
3000 erlang:match_spec_test(MatchAgainst, MatchSpec, Type) ->
3002 TestResult
3003 Types:
3005 MatchAgainst = [term()] | tuple()
3007 MatchSpec = term()
3008 Type = table | trace
3009 TestResult =
3010 {ok, term(), [return_trace], [{error | warning,
3011 string()}]} |
3012 {error, [{error | warning, string()}]}
3013 Tests a match specification used in calls to ets:select/2 and
3015 erlang:trace_pattern/3. The function tests both a match specifi‐
3016 cation for "syntactic" correctness and runs the match specifica‐
3017 tion against the object. If the match specification contains
3018 errors, the tuple {error, Errors} is returned, where Errors is a
3019 list of natural language descriptions of what was wrong with the
3020 match specification.
3021 If Type is table, the object to match against is to be a tuple.
3023 The function then returns {ok,Result,[],Warnings}, where Result
3024 is what would have been the result in a real ets:select/2 call,
3025 or false if the match specification does not match the object
3026 tuple.
3027 If Type is trace, the object to match against is to be a list.
3029 The function returns {ok, Result, Flags, Warnings}, where Result
3030 is one of the following:
3031 * true if a trace message is to be emitted
3033 * false if a trace message is not to be emitted
3035 * The message term to be appended to the trace message
3037 Flags is a list containing all the trace flags to be enabled,
3039 currently this is only return_trace.
3040 This is a useful debugging and test tool, especially when writ‐
3042 ing complicated match specifications.
3043 See also ets:test_ms/2.
3045 max(Term1, Term2) -> Maximum
3047 Types:
3049 Term1 = Term2 = Maximum = term()
3051 Returns the largest of Term1 and Term2. If the terms are equal,
3053 Term1 is returned.
3054 erlang:md5(Data) -> Digest
3056 Types:
3058 Data = iodata()
3060 Digest = binary()
3061 Computes an MD5 message digest from Data, where the length of
3063 the digest is 128 bits (16 bytes). Data is a binary or a list of
3064 small integers and binaries.
3065 For more information about MD5, see RFC 1321 - The MD5 Message-
3067 Digest Algorithm.
3068 Warning:
3070 The MD5 Message-Digest Algorithm is not considered safe for
3071 code-signing or software-integrity purposes.
3072 erlang:md5_final(Context) -> Digest
3075 Types:
3077 Context = Digest = binary()
3079 Finishes the update of an MD5 Context and returns the computed
3081 MD5 message digest.
3082 erlang:md5_init() -> Context
3084 Types:
3086 Context = binary()
3088 Creates an MD5 context, to be used in the following calls to
3090 md5_update/2.
3091 erlang:md5_update(Context, Data) -> NewContext
3093 Types:
3095 Context = binary()
3097 Data = iodata()
3098 NewContext = binary()
3099 Update an MD5 Context with Data and returns a NewContext.
3101 erlang:memory() -> [{Type, Size}]
3103 Types:
3105 Type = memory_type()
3107 Size = integer() >= 0
3108 memory_type() =
3109 total |
3110 processes |
3111 processes_used |
3112 system |
3113 atom |
3114 atom_used |
3115 binary |
3116 code |
3117 ets
3118 Returns a list with information about memory dynamically allo‐
3120 cated by the Erlang emulator. Each list element is a tuple
3121 {Type, Size}. The first element Type is an atom describing mem‐
3122 ory type. The second element Size is the memory size in bytes.
3123 Memory types:
3125 total:
3127 The total amount of memory currently allocated. This is the
3128 same as the sum of the memory size for processes and system.
3129 processes:
3131 The total amount of memory currently allocated for the
3132 Erlang processes.
3133 processes_used:
3135 The total amount of memory currently used by the Erlang pro‐
3136 cesses. This is part of the memory presented as processes
3137 memory.
3138 system:
3140 The total amount of memory currently allocated for the emu‐
3141 lator that is not directly related to any Erlang process.
3142 Memory presented as processes is not included in this mem‐
3143 ory. instrument(3) can be used to get a more detailed break‐
3144 down of what memory is part of this type.
3145 atom:
3147 The total amount of memory currently allocated for atoms.
3148 This memory is part of the memory presented as system mem‐
3149 ory.
3150 atom_used:
3152 The total amount of memory currently used for atoms. This
3153 memory is part of the memory presented as atom memory.
3154 binary:
3156 The total amount of memory currently allocated for binaries.
3157 This memory is part of the memory presented as system mem‐
3158 ory.
3159 code:
3161 The total amount of memory currently allocated for Erlang
3162 code. This memory is part of the memory presented as system
3163 memory.
3164 ets:
3166 The total amount of memory currently allocated for ETS
3167 tables. This memory is part of the memory presented as sys‐
3168 tem memory.
3169 low:
3171 Only on 64-bit halfword emulator. The total amount of memory
3172 allocated in low memory areas that are restricted to < 4 GB,
3173 although the system can have more memory.
3174 Can be removed in a future release of the halfword emulator.
3176 maximum:
3178 The maximum total amount of memory allocated since the emu‐
3179 lator was started. This tuple is only present when the emu‐
3180 lator is run with instrumentation.
3181 For information on how to run the emulator with instrumenta‐
3183 tion, see instrument(3) and/or erl(1).
3184 Note:
3186 The system value is not complete. Some allocated memory that is
3187 to be part of this value is not.
3188 When the emulator is run with instrumentation, the system value
3190 is more accurate, but memory directly allocated for malloc (and
3191 friends) is still not part of the system value. Direct calls to
3192 malloc are only done from OS-specific runtime libraries and per‐
3193 haps from user-implemented Erlang drivers that do not use the
3194 memory allocation functions in the driver interface.
3195 As the total value is the sum of processes and system, the error
3197 in system propagates to the total value.
3198 The different amounts of memory that are summed are not gathered
3200 atomically, which introduces an error in the result.
3201 The different values have the following relation to each other.
3204 Values beginning with an uppercase letter is not part of the
3205 result.
3206 total = processes + system
3208 processes = processes_used + ProcessesNotUsed
3209 system = atom + binary + code + ets + OtherSystem
3210 atom = atom_used + AtomNotUsed
3211 RealTotal = processes + RealSystem
3212 RealSystem = system + MissedSystem
3213 More tuples in the returned list can be added in a future
3215 release.
3216 Note:
3218 The total value is supposed to be the total amount of memory
3219 dynamically allocated by the emulator. Shared libraries, the
3220 code of the emulator itself, and the emulator stacks are not
3221 supposed to be included. That is, the total value is not sup‐
3222 posed to be equal to the total size of all pages mapped to the
3223 emulator.
3224 Also, because of fragmentation and prereservation of memory
3226 areas, the size of the memory segments containing the dynami‐
3227 cally allocated memory blocks can be much larger than the total
3228 size of the dynamically allocated memory blocks.
3229 Note:
3232 As from ERTS 5.6.4, erlang:memory/0 requires that all
3233 erts_alloc(3) allocators are enabled (default behavior).
3234 Failure: notsup if an erts_alloc(3) allocator has been disabled.
3237 erlang:memory(Type :: memory_type()) -> integer() >= 0
3239 erlang:memory(TypeList :: [memory_type()]) ->
3241 [{memory_type(), integer() >= 0}]
3242 Types:
3244 memory_type() =
3246 total |
3247 processes |
3248 processes_used |
3249 system |
3250 atom |
3251 atom_used |
3252 binary |
3253 code |
3254 ets
3255 Returns the memory size in bytes allocated for memory of type
3257 Type. The argument can also be specified as a list of mem‐
3258 ory_type() atoms, in which case a corresponding list of {mem‐
3259 ory_type(), Size :: integer >= 0} tuples is returned.
3260 Note:
3262 As from ERTS 5.6.4, erlang:memory/1 requires that all
3263 erts_alloc(3) allocators are enabled (default behavior).
3264 Failures:
3267 badarg:
3269 If Type is not one of the memory types listed in the
3270 description of erlang:memory/0.
3271 badarg:
3273 If maximum is passed as Type and the emulator is not run in
3274 instrumented mode.
3275 notsup:
3277 If an erts_alloc(3) allocator has been disabled.
3278 See also erlang:memory/0.
3280 min(Term1, Term2) -> Minimum
3282 Types:
3284 Term1 = Term2 = Minimum = term()
3286 Returns the smallest of Term1 and Term2. If the terms are equal,
3288 Term1 is returned.
3289 module_loaded(Module) -> boolean()
3291 Types:
3293 Module = module()
3295 Returns true if the module Module is loaded, otherwise false. It
3297 does not attempt to load the module.
3298 Warning:
3300 This BIF is intended for the code server (see code(3)) and is
3301 not to be used elsewhere.
3302 monitor(Type :: process, Item :: monitor_process_identifier()) ->
3305 MonitorRef
3306 monitor(Type :: port, Item :: monitor_port_identifier()) ->
3308 MonitorRef
3309 monitor(Type :: time_offset, Item :: clock_service) -> MonitorRef
3311 Types:
3313 MonitorRef = reference()
3315 registered_name() = atom()
3316 registered_process_identifier() =
3317 registered_name() | {registered_name(), node()}
3318 monitor_process_identifier() =
3319 pid() | registered_process_identifier()
3320 monitor_port_identifier() = port() | registered_name()
3321 Sends a monitor request of type Type to the entity identified by
3323 Item. If the monitored entity does not exist or it changes moni‐
3324 tored state, the caller of monitor/2 is notified by a message on
3325 the following format:
3326 {Tag, MonitorRef, Type, Object, Info}
3328 Note:
3330 The monitor request is an asynchronous signal. That is, it takes
3331 time before the signal reaches its destination.
3332 Type can be one of the following atoms: process, port or
3335 time_offset.
3336 A process or port monitor is triggered only once, after that it
3338 is removed from both monitoring process and the monitored
3339 entity. Monitors are fired when the monitored process or port
3340 terminates, does not exist at the moment of creation, or if the
3341 connection to it is lost. If the connection to it is lost, we do
3342 not know if it still exists. The monitoring is also turned off
3343 when demonitor/1 is called.
3344 A process or port monitor by name resolves the RegisteredName to
3346 pid() or port() only once at the moment of monitor instantia‐
3347 tion, later changes to the name registration will not affect the
3348 existing monitor.
3349 When a process or port monitor is triggered, a 'DOWN' message is
3351 sent that has the following pattern:
3352 {'DOWN', MonitorRef, Type, Object, Info}
3354 In the monitor message MonitorRef and Type are the same as
3356 described earlier, and:
3357 Object:
3359 The monitored entity, which triggered the event. When moni‐
3360 toring a local process or port, Object will be equal to the
3361 pid() or port() that was being monitored. When monitoring
3362 process or port by name, Object will have format {Regis‐
3363 teredName, Node} where RegisteredName is the name which has
3364 been used with monitor/2 call and Node is local or remote
3365 node name (for ports monitored by name, Node is always local
3366 node name).
3367 Info:
3369 Either the exit reason of the process, noproc (process or
3370 port did not exist at the time of monitor creation), or
3371 noconnection (no connection to the node where the monitored
3372 process resides).
3373 Monitoring a process:
3375 Creates monitor between the current process and another
3376 process identified by Item, which can be a pid() (local or
3377 remote), an atom RegisteredName or a tuple {RegisteredName,
3378 Node} for a registered process, located elsewhere.
3379 Note:
3381 Before ERTS 10.0 (OTP 21.0), monitoring a process could fail
3382 with badarg if the monitored process resided on a primitive
3383 node (such as erl_interface or jinterface), where remote
3384 process monitoring is not implemented.
3385 Now, such a call to monitor will instead succeed and a monitor
3387 is created. But the monitor will only supervise the connec‐
3388 tion. That is, a {'DOWN', _, process, _, noconnection} is the
3389 only message that may be received, as the primitive node have
3390 no way of reporting the status of the monitored process.
3391 Monitoring a port:
3394 Creates monitor between the current process and a port iden‐
3395 tified by Item, which can be a port() (only local), an atom
3396 RegisteredName or a tuple {RegisteredName, Node} for a reg‐
3397 istered port, located on this node. Note, that attempt to
3398 monitor a remote port will result in badarg.
3399 Monitoring a time_offset:
3401 Monitors changes in time offset between Erlang monotonic
3402 time and Erlang system time. One valid Item exists in combi‐
3403 nation with the time_offset Type, namely the atom clock_ser‐
3404 vice. Notice that the atom clock_service is not the regis‐
3405 tered name of a process. In this case it serves as an iden‐
3406 tifier of the runtime system internal clock service at cur‐
3407 rent runtime system instance.
3408 The monitor is triggered when the time offset is changed.
3410 This either if the time offset value is changed, or if the
3411 offset is changed from preliminary to final during finaliza‐
3412 tion of the time offset when the single time warp mode is
3413 used. When a change from preliminary to final time offset is
3414 made, the monitor is triggered once regardless of whether
3415 the time offset value was changed or not.
3416 If the runtime system is in multi time warp mode, the time
3418 offset is changed when the runtime system detects that the
3419 OS system time has changed. The runtime system does, how‐
3420 ever, not detect this immediately when it occurs. A task
3421 checking the time offset is scheduled to execute at least
3422 once a minute, so under normal operation this is to be
3423 detected within a minute, but during heavy load it can take
3424 longer time.
3425 The monitor is not automatically removed after it has been
3427 triggered. That is, repeated changes of the time offset
3428 trigger the monitor repeatedly.
3429 When the monitor is triggered a 'CHANGE' message is sent to
3431 the monitoring process. A 'CHANGE' message has the following
3432 pattern:
3433 {'CHANGE', MonitorRef, Type, Item, NewTimeOffset}
3435 where MonitorRef, Type, and Item are the same as described
3437 above, and NewTimeOffset is the new time offset.
3438 When the 'CHANGE' message has been received you are guaran‐
3440 teed not to retrieve the old time offset when calling
3441 erlang:time_offset(). Notice that you can observe the change
3442 of the time offset when calling erlang:time_offset() before
3443 you get the 'CHANGE' message.
3444 Making several calls to monitor/2 for the same Item and/or Type
3446 is not an error; it results in as many independent monitoring
3447 instances.
3448 The monitor functionality is expected to be extended. That is,
3450 other Types and Items are expected to be supported in a future
3451 release.
3452 Note:
3454 If or when monitor/2 is extended, other possible values for Tag,
3455 Object, and Info in the monitor message will be introduced.
3456 monitor_node(Node, Flag) -> true
3459 Types:
3461 Node = node()
3463 Flag = boolean()
3464 Monitor the status of the node Node. If Flag is true, monitoring
3466 is turned on. If Flag is false, monitoring is turned off.
3467 Making several calls to monitor_node(Node, true) for the same
3469 Node is not an error; it results in as many independent monitor‐
3470 ing instances.
3471 If Node fails or does not exist, the message {nodedown, Node} is
3473 delivered to the process. If a process has made two calls to
3474 monitor_node(Node, true) and Node terminates, two nodedown mes‐
3475 sages are delivered to the process. If there is no connection to
3476 Node, an attempt is made to create one. If this fails, a node‐
3477 down message is delivered.
3478 Nodes connected through hidden connections can be monitored as
3480 any other nodes.
3481 Failure: badarg if the local node is not alive.
3483 erlang:monitor_node(Node, Flag, Options) -> true
3485 Types:
3487 Node = node()
3489 Flag = boolean()
3490 Options = [Option]
3491 Option = allow_passive_connect
3492 Behaves as monitor_node/2 except that it allows an extra option
3494 to be specified, namely allow_passive_connect. This option
3495 allows the BIF to wait the normal network connection time-out
3496 for the monitored node to connect itself, even if it cannot be
3497 actively connected from this node (that is, it is blocked). The
3498 state where this can be useful can only be achieved by using the
3499 Kernel option dist_auto_connect once. If that option is not
3500 used, option allow_passive_connect has no effect.
3501 Note:
3503 Option allow_passive_connect is used internally and is seldom
3504 needed in applications where the network topology and the Kernel
3505 options in effect are known in advance.
3506 Failure: badarg if the local node is not alive or the option
3509 list is malformed.
3510 erlang:monotonic_time() -> integer()
3512 Returns the current Erlang monotonic time in native time unit.
3514 This is a monotonically increasing time since some unspecified
3515 point in time.
3516 Note:
3518 This is a monotonically increasing time, but not a strictly
3519 monotonically increasing time. That is, consecutive calls to
3520 erlang:monotonic_time/0 can produce the same result.
3521 Different runtime system instances will use different unspeci‐
3523 fied points in time as base for their Erlang monotonic clocks.
3524 That is, it is pointless comparing monotonic times from differ‐
3525 ent runtime system instances. Different runtime system instances
3526 can also place this unspecified point in time different relative
3527 runtime system start. It can be placed in the future (time at
3528 start is a negative value), the past (time at start is a posi‐
3529 tive value), or the runtime system start (time at start is
3530 zero). The monotonic time at runtime system start can be
3531 retrieved by calling erlang:system_info(start_time).
3532 erlang:monotonic_time(Unit) -> integer()
3535 Types:
3537 Unit = time_unit()
3539 Returns the current Erlang monotonic time converted into the
3541 Unit passed as argument.
3542 Same as calling erlang:convert_time_unit(erlang:mono‐
3544 tonic_time(), native, Unit), however optimized for commonly used
3545 Units.
3546 erlang:nif_error(Reason) -> no_return()
3548 Types:
3550 Reason = term()
3552 Works exactly like error/1, but Dialyzer thinks that this BIF
3554 will return an arbitrary term. When used in a stub function for
3555 a NIF to generate an exception when the NIF library is not
3556 loaded, Dialyzer does not generate false warnings.
3557 erlang:nif_error(Reason, Args) -> no_return()
3559 Types:
3561 Reason = term()
3563 Args = [term()]
3564 Works exactly like error/2, but Dialyzer thinks that this BIF
3566 will return an arbitrary term. When used in a stub function for
3567 a NIF to generate an exception when the NIF library is not
3568 loaded, Dialyzer does not generate false warnings.
3569 node() -> Node
3571 Types:
3573 Node = node()
3575 Returns the name of the local node. If the node is not alive,
3577 nonode@nohost is returned instead.
3578 Allowed in guard tests.
3580 node(Arg) -> Node
3582 Types:
3584 Arg = pid() | port() | reference()
3586 Node = node()
3587 Returns the node where Arg originates. Arg can be a process
3589 identifier, a reference, or a port. If the local node is not
3590 alive, nonode@nohost is returned.
3591 Allowed in guard tests.
3593 nodes() -> Nodes
3595 Types:
3597 Nodes = [node()]
3599 Returns a list of all visible nodes in the system, except the
3601 local node. Same as nodes(visible).
3602 nodes(Arg) -> Nodes
3604 Types:
3606 Arg = NodeType | [NodeType]
3608 NodeType = visible | hidden | connected | this | known
3609 Nodes = [node()]
3610 Returns a list of nodes according to the argument specified. The
3612 returned result, when the argument is a list, is the list of
3613 nodes satisfying the disjunction(s) of the list elements.
3614 NodeTypes:
3616 visible:
3618 Nodes connected to this node through normal connections.
3619 hidden:
3621 Nodes connected to this node through hidden connections.
3622 connected:
3624 All nodes connected to this node.
3625 this:
3627 This node.
3628 known:
3630 Nodes that are known to this node. That is, connected nodes
3631 and nodes referred to by process identifiers, port identi‐
3632 fiers, and references located on this node. The set of known
3633 nodes is garbage collected. Notice that this garbage collec‐
3634 tion can be delayed. For more information, see erlang:sys‐
3635 tem_info(delayed_node_table_gc).
3636 Some equalities: [node()] = nodes(this), nodes(connected) =
3638 nodes([visible, hidden]), and nodes() = nodes(visible).
3639 now() -> Timestamp
3641 Types:
3643 Timestamp = timestamp()
3645 timestamp() =
3646 {MegaSecs :: integer() >= 0,
3647 Secs :: integer() >= 0,
3648 MicroSecs :: integer() >= 0}
3649 Warning:
3651 This function is deprecated. Do not use it.
3652 For more information, see section Time and Time Correction in
3654 the User's Guide. Specifically, section Dos and Dont's
3655 describes what to use instead of erlang:now/0.
3656 Returns the tuple {MegaSecs, Secs, MicroSecs}, which is the
3659 elapsed time since 00:00 GMT, January 1, 1970 (zero hour), if
3660 provided by the underlying OS. Otherwise some other point in
3661 time is chosen. It is also guaranteed that the following calls
3662 to this BIF return continuously increasing values. Hence, the
3663 return value from erlang:now/0 can be used to generate unique
3664 time stamps. If it is called in a tight loop on a fast machine,
3665 the time of the node can become skewed.
3666 Can only be used to check the local time of day if the time-zone
3668 information of the underlying OS is properly configured.
3669 open_port(PortName, PortSettings) -> port()
3671 Types:
3673 PortName =
3675 {spawn, Command :: string() | binary()} |
3676 {spawn_driver, Command :: string() | binary()} |
3677 {spawn_executable, FileName :: file:name()} |
3678 {fd, In :: integer() >= 0, Out :: integer() >= 0}
3679 PortSettings = [Opt]
3680 Opt =
3681 {packet, N :: 1 | 2 | 4} |
3682 stream |
3683 {line, L :: integer() >= 0} |
3684 {cd, Dir :: string() | binary()} |
3685 {env,
3686 Env ::
3687 [{Name :: os:env_var_name(),
3688 Val :: os:env_var_value() | false}]} |
3689 {args, [string() | binary()]} |
3690 {arg0, string() | binary()} |
3691 exit_status |
3692 use_stdio |
3693 nouse_stdio |
3694 stderr_to_stdout |
3695 in |
3696 out |
3697 binary |
3698 eof |
3699 {parallelism, Boolean :: boolean()} |
3700 hide
3701 Returns a port identifier as the result of opening a new Erlang
3703 port. A port can be seen as an external Erlang process.
3704 The name of the executable as well as the arguments specifed in
3706 cd, env, args, and arg0 are subject to Unicode filename transla‐
3707 tion if the system is running in Unicode filename mode. To avoid
3708 translation or to force, for example UTF-8, supply the exe‐
3709 cutable and/or arguments as a binary in the correct encoding.
3710 For details, see the module file(3), the function
3711 file:native_name_encoding/0 in Kernel, and the Using Unicode in
3712 Erlang User's Guide.
3713 Note:
3715 The characters in the name (if specified as a list) can only be
3716 > 255 if the Erlang virtual machine is started in Unicode file‐
3717 name translation mode. Otherwise the name of the executable is
3718 limited to the ISO Latin-1 character set.
3719 PortNames:
3722 {spawn, Command}:
3724 Starts an external program. Command is the name of the
3725 external program to be run. Command runs outside the Erlang
3726 work space unless an Erlang driver with the name Command is
3727 found. If found, that driver is started. A driver runs in
3728 the Erlang work space, which means that it is linked with
3729 the Erlang runtime system.
3730 For external programs, PATH is searched (or an equivalent
3732 method is used to find programs, depending on the OS). This
3733 is done by invoking the shell on certain platforms. The
3734 first space-separated token of the command is considered as
3735 the name of the executable (or driver). This (among other
3736 things) makes this option unsuitable for running programs
3737 with spaces in filenames or directory names. If spaces in
3738 executable filenames are desired, use {spawn_executable,
3739 Command} instead.
3740 {spawn_driver, Command}:
3742 Works like {spawn, Command}, but demands the first (space-
3743 separated) token of the command to be the name of a loaded
3744 driver. If no driver with that name is loaded, a badarg
3745 error is raised.
3746 {spawn_executable, FileName}:
3748 Works like {spawn, FileName}, but only runs external exe‐
3749 cutables. FileName in its whole is used as the name of the
3750 executable, including any spaces. If arguments are to be
3751 passed, the PortSettings args and arg0 can be used.
3752 The shell is usually not invoked to start the program, it is
3754 executed directly. PATH (or equivalent) is not searched. To
3755 find a program in PATH to execute, use os:find_executable/1.
3756 Only if a shell script or .bat file is executed, the appro‐
3758 priate command interpreter is invoked implicitly, but there
3759 is still no command-argument expansion or implicit PATH
3760 search.
3761 If FileName cannot be run, an error exception is raised,
3763 with the POSIX error code as the reason. The error reason
3764 can differ between OSs. Typically the error enoent is raised
3765 when an attempt is made to run a program that is not found
3766 and eacces is raised when the specified file is not exe‐
3767 cutable.
3768 {fd, In, Out}:
3770 Allows an Erlang process to access any currently opened file
3771 descriptors used by Erlang. The file descriptor In can be
3772 used for standard input, and the file descriptor Out for
3773 standard output. It is only used for various servers in the
3774 Erlang OS (shell and user). Hence, its use is limited.
3775 PortSettings is a list of settings for the port. The valid set‐
3777 tings are as follows:
3778 {packet, N}:
3780 Messages are preceded by their length, sent in N bytes, with
3781 the most significant byte first. The valid values for N are
3782 1, 2, and 4.
3783 stream:
3785 Output messages are sent without packet lengths. A user-
3786 defined protocol must be used between the Erlang process and
3787 the external object.
3788 {line, L}:
3790 Messages are delivered on a per line basis. Each line
3791 (delimited by the OS-dependent newline sequence) is deliv‐
3792 ered in a single message. The message data format is {Flag,
3793 Line}, where Flag is eol or noeol, and Line is the data
3794 delivered (without the newline sequence).
3795 L specifies the maximum line length in bytes. Lines longer
3797 than this are delivered in more than one message, with Flag
3798 set to noeol for all but the last message. If end of file is
3799 encountered anywhere else than immediately following a new‐
3800 line sequence, the last line is also delivered with Flag set
3801 to noeol. Otherwise lines are delivered with Flag set to
3802 eol.
3803 The {packet, N} and {line, L} settings are mutually exclu‐
3805 sive.
3806 {cd, Dir}:
3808 Only valid for {spawn, Command} and {spawn_executable, File‐
3809 Name}. The external program starts using Dir as its working
3810 directory. Dir must be a string.
3811 {env, Env}:
3813 Types:
3814 Name = os:env_var_name()
3815 Val = os:env_var_value() | false
3816 Env = [{Name, Val}]
3817 Only valid for {spawn, Command}, and {spawn_executable,
3819 FileName}. The environment of the started process is
3820 extended using the environment specifications in Env.
3821 Env is to be a list of tuples {Name, Val}, where Name is the
3823 name of an environment variable, and Val is the value it is
3824 to have in the spawned port process. Both Name and Val must
3825 be strings. The one exception is Val being the atom false
3826 (in analogy with os:getenv/1, which removes the environment
3827 variable.
3828 For information about encoding requirements, see documenta‐
3830 tion of the types for Name and Val.
3831 {args, [ string() | binary() ]}:
3833 Only valid for {spawn_executable, FileName} and specifies
3834 arguments to the executable. Each argument is specified as a
3835 separate string and (on Unix) eventually ends up as one ele‐
3836 ment each in the argument vector. On other platforms, a sim‐
3837 ilar behavior is mimicked.
3838 The arguments are not expanded by the shell before they are
3840 supplied to the executable. Most notably this means that
3841 file wildcard expansion does not occur. To expand wildcards
3842 for the arguments, use filelib:wildcard/1. Notice that even
3843 if the program is a Unix shell script, meaning that the
3844 shell ultimately is invoked, wildcard expansion does not
3845 occur, and the script is provided with the untouched argu‐
3846 ments. On Windows, wildcard expansion is always up to the
3847 program itself, therefore this is not an issue.
3848 The executable name (also known as argv[0]) is not to be
3850 specified in this list. The proper executable name is auto‐
3851 matically used as argv[0], where applicable.
3852 If you explicitly want to set the program name in the argu‐
3854 ment vector, option arg0 can be used.
3855 {arg0, string() | binary()}:
3857 Only valid for {spawn_executable, FileName} and explicitly
3858 specifies the program name argument when running an exe‐
3859 cutable. This can in some circumstances, on some OSs, be
3860 desirable. How the program responds to this is highly sys‐
3861 tem-dependent and no specific effect is guaranteed.
3862 exit_status:
3864 Only valid for {spawn, Command}, where Command refers to an
3865 external program, and for {spawn_executable, FileName}.
3866 When the external process connected to the port exits, a
3868 message of the form {Port,{exit_status,Status}} is sent to
3869 the connected process, where Status is the exit status of
3870 the external process. If the program aborts on Unix, the
3871 same convention is used as the shells do (that is, 128+sig‐
3872 nal).
3873 If option eof is specified also, the messages eof and
3875 exit_status appear in an unspecified order.
3876 If the port program closes its stdout without exiting,
3878 option exit_status does not work.
3879 use_stdio:
3881 Only valid for {spawn, Command} and {spawn_executable, File‐
3882 Name}. It allows the standard input and output (file
3883 descriptors 0 and 1) of the spawned (Unix) process for com‐
3884 munication with Erlang.
3885 nouse_stdio:
3887 The opposite of use_stdio. It uses file descriptors 3 and 4
3888 for communication with Erlang.
3889 stderr_to_stdout:
3891 Affects ports to external programs. The executed program
3892 gets its standard error file redirected to its standard out‐
3893 put file. stderr_to_stdout and nouse_stdio are mutually
3894 exclusive.
3895 overlapped_io:
3897 Affects ports to external programs on Windows only. The
3898 standard input and standard output handles of the port pro‐
3899 gram are, if this option is supplied, opened with flag
3900 FILE_FLAG_OVERLAPPED, so that the port program can (and
3901 must) do overlapped I/O on its standard handles. This is not
3902 normally the case for simple port programs, but an option of
3903 value for the experienced Windows programmer. On all other
3904 platforms, this option is silently discarded.
3905 in:
3907 The port can only be used for input.
3908 out:
3910 The port can only be used for output.
3911 binary:
3913 All I/O from the port is binary data objects as opposed to
3914 lists of bytes.
3915 eof:
3917 The port is not closed at the end of the file and does not
3918 produce an exit signal. Instead, it remains open and a
3919 {Port, eof} message is sent to the process holding the port.
3920 hide:
3922 When running on Windows, suppresses creation of a new con‐
3923 sole window when spawning the port program. (This option has
3924 no effect on other platforms.)
3925 {parallelism, Boolean}:
3927 Sets scheduler hint for port parallelism. If set to true,
3930 the virtual machine schedules port tasks; when doing so, it
3931 improves parallelism in the system. If set to false, the
3932 virtual machine tries to perform port tasks immediately,
3933 improving latency at the expense of parallelism. The default
3934 can be set at system startup by passing command-line argu‐
3935 ment +spp to erl(1).
3936 Default is stream for all port types and use_stdio for spawned
3938 ports.
3939 Failure: if the port cannot be opened, the exit reason is
3941 badarg, system_limit, or the POSIX error code that most closely
3942 describes the error, or einval if no POSIX code is appropriate:
3943 badarg:
3945 Bad input arguments to open_port.
3946 system_limit:
3948 All available ports in the Erlang emulator are in use.
3949 enomem:
3951 Not enough memory to create the port.
3952 eagain:
3954 No more available OS processes.
3955 enametoolong:
3957 Too long external command.
3958 emfile:
3960 No more available file descriptors (for the OS process that
3961 the Erlang emulator runs in).
3962 enfile:
3964 Full file table (for the entire OS).
3965 eacces:
3967 Command specified in {spawn_executable, Command} does not
3968 point out an executable file.
3969 enoent:
3971 FileName specified in {spawn_executable, FileName} does not
3972 point out an existing file.
3973 During use of a port opened using {spawn, Name}, {spawn_driver,
3975 Name}, or {spawn_executable, Name}, errors arising when sending
3976 messages to it are reported to the owning process using signals
3977 of the form {'EXIT', Port, PosixCode}. For the possible values
3978 of PosixCode, see file(3).
3979 The maximum number of ports that can be open at the same time
3981 can be configured by passing command-line flag +Q to erl(1).
3982 erlang:phash(Term, Range) -> Hash
3984 Types:
3986 Term = term()
3988 Range = Hash = integer() >= 1
3989 Range = 1..2^32, Hash = 1..Range
3990 Portable hash function that gives the same hash for the same
3992 Erlang term regardless of machine architecture and ERTS version
3993 (the BIF was introduced in ERTS 4.9.1.1). The function returns a
3994 hash value for Term within the range 1..Range. The maximum value
3995 for Range is 2^32.
3996 erlang:phash2(Term) -> Hash
3998 erlang:phash2(Term, Range) -> Hash
4000 Types:
4002 Term = term()
4004 Range = integer() >= 1
4005 1..2^32
4006 Hash = integer() >= 0
4007 0..Range-1
4008 Portable hash function that gives the same hash for the same
4010 Erlang term regardless of machine architecture and ERTS version
4011 (the BIF was introduced in ERTS 5.2). The function returns a
4012 hash value for Term within the range 0..Range-1. The maximum
4013 value for Range is 2^32. When without argument Range, a value in
4014 the range 0..2^27-1 is returned.
4015 This BIF is always to be used for hashing terms. It distributes
4017 small integers better than phash/2, and it is faster for bignums
4018 and binaries.
4019 Notice that the range 0..Range-1 is different from the range of
4021 phash/2, which is 1..Range.
4022 pid_to_list(Pid) -> string()
4024 Types:
4026 Pid = pid()
4028 Returns a string corresponding to the text representation of
4030 Pid.
4031 erlang:port_call(Port, Operation, Data) -> term()
4033 Types:
4035 Port = port() | atom()
4037 Operation = integer()
4038 Data = term()
4039 Performs a synchronous call to a port. The meaning of Operation
4041 and Data depends on the port, that is, on the port driver. Not
4042 all port drivers support this feature.
4043 Port is a port identifier, referring to a driver.
4045 Operation is an integer, which is passed on to the driver.
4047 Data is any Erlang term. This data is converted to binary term
4049 format and sent to the port.
4050 Returns a term from the driver. The meaning of the returned data
4052 also depends on the port driver.
4053 Failures:
4055 badarg:
4057 If Port is not an identifier of an open port, or the regis‐
4058 tered name of an open port. If the calling process was pre‐
4059 viously linked to the closed port, identified by Port, the
4060 exit signal from the port is guaranteed to be delivered
4061 before this badarg exception occurs.
4062 badarg:
4064 If Operation does not fit in a 32-bit integer.
4065 badarg:
4067 If the port driver does not support synchronous control
4068 operations.
4069 badarg:
4071 If the port driver so decides for any reason (probably some‐
4072 thing wrong with Operation or Data).
4073 Warning:
4075 Do not call port_call with an unknown Port identifier and
4076 expect badarg exception. Any undefined behavior is possible
4077 (including node crash) depending on how the port driver inter‐
4078 prets the supplied arguments.
4079 port_close(Port) -> true
4082 Types:
4084 Port = port() | atom()
4086 Closes an open port. Roughly the same as Port ! {self(), close}
4088 except for the error behavior (see below), being synchronous,
4089 and that the port does not reply with {Port, closed}. Any
4090 process can close a port with port_close/1, not only the port
4091 owner (the connected process). If the calling process is linked
4092 to the port identified by Port, the exit signal from the port is
4093 guaranteed to be delivered before port_close/1 returns.
4094 For comparison: Port ! {self(), close} only fails with badarg if
4096 Port does not refer to a port or a process. If Port is a closed
4097 port, nothing happens. If Port is an open port and the calling
4098 process is the port owner, the port replies with {Port, closed}
4099 when all buffers have been flushed and the port really closes.
4100 If the calling process is not the port owner, the port owner
4101 fails with badsig.
4102 Notice that any process can close a port using Port ! {Por‐
4104 tOwner, close} as if it itself was the port owner, but the reply
4105 always goes to the port owner.
4106 As from Erlang/OTP R16, Port ! {PortOwner, close} is truly asyn‐
4108 chronous. Notice that this operation has always been documented
4109 as an asynchronous operation, while the underlying implementa‐
4110 tion has been synchronous. port_close/1 is however still fully
4111 synchronous because of its error behavior.
4112 Failure: badarg if Port is not an identifier of an open port, or
4114 the registered name of an open port. If the calling process was
4115 previously linked to the closed port, identified by Port, the
4116 exit signal from the port is guaranteed to be delivered before
4117 this badarg exception occurs.
4118 port_command(Port, Data) -> true
4120 Types:
4122 Port = port() | atom()
4124 Data = iodata()
4125 Sends data to a port. Same as Port ! {PortOwner, {command,
4127 Data}} except for the error behavior and being synchronous (see
4128 below). Any process can send data to a port with port_command/2,
4129 not only the port owner (the connected process).
4130 For comparison: Port ! {PortOwner, {command, Data}} only fails
4132 with badarg if Port does not refer to a port or a process. If
4133 Port is a closed port, the data message disappears without a
4134 sound. If Port is open and the calling process is not the port
4135 owner, the port owner fails with badsig. The port owner fails
4136 with badsig also if Data is an invalid I/O list.
4137 Notice that any process can send to a port using Port ! {Por‐
4139 tOwner, {command, Data}} as if it itself was the port owner.
4140 If the port is busy, the calling process is suspended until the
4142 port is not busy any more.
4143 As from Erlang/OTP R16, Port ! {PortOwner, {command, Data}} is
4145 truly asynchronous. Notice that this operation has always been
4146 documented as an asynchronous operation, while the underlying
4147 implementation has been synchronous. port_command/2 is however
4148 still fully synchronous because of its error behavior.
4149 Failures:
4151 badarg:
4153 If Port is not an identifier of an open port, or the regis‐
4154 tered name of an open port. If the calling process was pre‐
4155 viously linked to the closed port, identified by Port, the
4156 exit signal from the port is guaranteed to be delivered
4157 before this badarg exception occurs.
4158 badarg:
4160 If Data is an invalid I/O list.
4161 Warning:
4163 Do not send data to an unknown port. Any undefined behavior is
4164 possible (including node crash) depending on how the port driver
4165 interprets the data.
4166 port_command(Port, Data, OptionList) -> boolean()
4169 Types:
4171 Port = port() | atom()
4173 Data = iodata()
4174 Option = force | nosuspend
4175 OptionList = [Option]
4176 Sends data to a port. port_command(Port, Data, []) equals
4178 port_command(Port, Data).
4179 If the port command is aborted, false is returned, otherwise
4181 true.
4182 If the port is busy, the calling process is suspended until the
4184 port is not busy anymore.
4185 Options:
4187 force:
4189 The calling process is not suspended if the port is busy,
4190 instead the port command is forced through. The call fails
4191 with a notsup exception if the driver of the port does not
4192 support this. For more information, see driver flag
4193 ![CDATA[ERL_DRV_FLAG_SOFT_BUSY]].
4194 nosuspend:
4196 The calling process is not suspended if the port is busy,
4197 instead the port command is aborted and false is returned.
4198 Note:
4200 More options can be added in a future release.
4201 Failures:
4204 badarg:
4206 If Port is not an identifier of an open port, or the regis‐
4207 tered name of an open port. If the calling process was pre‐
4208 viously linked to the closed port, identified by Port, the
4209 exit signal from the port is guaranteed to be delivered
4210 before this badarg exception occurs.
4211 badarg:
4213 If Data is an invalid I/O list.
4214 badarg:
4216 If OptionList is an invalid option list.
4217 notsup:
4219 If option force has been passed, but the driver of the port
4220 does not allow forcing through a busy port.
4221 Warning:
4223 Do not send data to an unknown port. Any undefined behavior is
4224 possible (including node crash) depending on how the port driver
4225 interprets the data.
4226 port_connect(Port, Pid) -> true
4229 Types:
4231 Port = port() | atom()
4233 Pid = pid()
4234 Sets the port owner (the connected port) to Pid. Roughly the
4236 same as Port ! {Owner, {connect, Pid}} except for the following:
4237 * The error behavior differs, see below.
4239 * The port does not reply with {Port,connected}.
4241 * port_connect/1 is synchronous, see below.
4243 * The new port owner gets linked to the port.
4245 The old port owner stays linked to the port and must call
4247 unlink(Port) if this is not desired. Any process can set the
4248 port owner to be any process with port_connect/2.
4249 For comparison: Port ! {self(), {connect, Pid}} only fails with
4251 badarg if Port does not refer to a port or a process. If Port is
4252 a closed port, nothing happens. If Port is an open port and the
4253 calling process is the port owner, the port replies with {Port,
4254 connected} to the old port owner. Notice that the old port owner
4255 is still linked to the port, while the new is not. If Port is an
4256 open port and the calling process is not the port owner, the
4257 port owner fails with badsig. The port owner fails with badsig
4258 also if Pid is not an existing local process identifier.
4259 Notice that any process can set the port owner using Port !
4261 {PortOwner, {connect, Pid}} as if it itself was the port owner,
4262 but the reply always goes to the port owner.
4263 As from Erlang/OTP R16, Port ! {PortOwner, {connect, Pid}} is
4265 truly asynchronous. Notice that this operation has always been
4266 documented as an asynchronous operation, while the underlying
4267 implementation has been synchronous. port_connect/2 is however
4268 still fully synchronous because of its error behavior.
4269 Failures:
4271 badarg:
4273 If Port is not an identifier of an open port, or the regis‐
4274 tered name of an open port. If the calling process was pre‐
4275 viously linked to the closed port, identified by Port, the
4276 exit signal from the port is guaranteed to be delivered
4277 before this badarg exception occurs.
4278 badarg:
4280 If the process identified by Pid is not an existing local
4281 process.
4282 port_control(Port, Operation, Data) -> iodata() | binary()
4284 Types:
4286 Port = port() | atom()
4288 Operation = integer()
4289 Data = iodata()
4290 Performs a synchronous control operation on a port. The meaning
4292 of Operation and Data depends on the port, that is, on the port
4293 driver. Not all port drivers support this control feature.
4294 Returns a list of integers in the range 0..255, or a binary,
4296 depending on the port driver. The meaning of the returned data
4297 also depends on the port driver.
4298 Failures:
4300 badarg:
4302 If Port is not an open port or the registered name of an
4303 open port.
4304 badarg:
4306 If Operation cannot fit in a 32-bit integer.
4307 badarg:
4309 If the port driver does not support synchronous control
4310 operations.
4311 badarg:
4313 If the port driver so decides for any reason (probably
4314 something wrong with Operation or Data).
4315 Warning:
4317 Do not call port_control/3 with an unknown Port identifier and
4318 expect badarg exception. Any undefined behavior is possible
4319 (including node crash) depending on how the port driver inter‐
4320 prets the supplied arguments.
4321 erlang:port_info(Port) -> Result
4324 Types:
4326 Port = port() | atom()
4328 ResultItem =
4329 {registered_name, RegisteredName :: atom()} |
4330 {id, Index :: integer() >= 0} |
4331 {connected, Pid :: pid()} |
4332 {links, Pids :: [pid()]} |
4333 {name, String :: string()} |
4334 {input, Bytes :: integer() >= 0} |
4335 {output, Bytes :: integer() >= 0} |
4336 {os_pid, OsPid :: integer() >= 0 | undefined}
4337 Result = [ResultItem] | undefined
4338 Returns a list containing tuples with information about Port, or
4340 undefined if the port is not open. The order of the tuples is
4341 undefined, and all the tuples are not mandatory. If the port is
4342 closed and the calling process was previously linked to the
4343 port, the exit signal from the port is guaranteed to be deliv‐
4344 ered before port_info/1 returns undefined.
4345 The result contains information about the following Items:
4347 * registered_name (if the port has a registered name)
4349 * id
4351 * connected
4353 * links
4355 * name
4357 * input
4359 * output
4361 For more information about the different Items, see port_info/2.
4363 Failure: badarg if Port is not a local port identifier, or an
4365 atom.
4366 erlang:port_info(Port, Item :: connected) ->
4368 {connected, Pid} | undefined
4369 Types:
4371 Port = port() | atom()
4373 Pid = pid()
4374 Pid is the process identifier of the process connected to the
4376 port.
4377 If the port identified by Port is not open, undefined is
4379 returned. If the port is closed and the calling process was pre‐
4380 viously linked to the port, the exit signal from the port is
4381 guaranteed to be delivered before port_info/2 returns undefined.
4382 Failure: badarg if Port is not a local port identifier, or an
4384 atom.
4385 erlang:port_info(Port, Item :: id) -> {id, Index} | undefined
4387 Types:
4389 Port = port() | atom()
4391 Index = integer() >= 0
4392 Index is the internal index of the port. This index can be used
4394 to separate ports.
4395 If the port identified by Port is not open, undefined is
4397 returned. If the port is closed and the calling process was pre‐
4398 viously linked to the port, the exit signal from the port is
4399 guaranteed to be delivered before port_info/2 returns undefined.
4400 Failure: badarg if Port is not a local port identifier, or an
4402 atom.
4403 erlang:port_info(Port, Item :: input) ->
4405 {input, Bytes} | undefined
4406 Types:
4408 Port = port() | atom()
4410 Bytes = integer() >= 0
4411 Bytes is the total number of bytes read from the port.
4413 If the port identified by Port is not open, undefined is
4415 returned. If the port is closed and the calling process was pre‐
4416 viously linked to the port, the exit signal from the port is
4417 guaranteed to be delivered before port_info/2 returns undefined.
4418 Failure: badarg if Port is not a local port identifier, or an
4420 atom.
4421 erlang:port_info(Port, Item :: links) -> {links, Pids} | undefined
4423 Types:
4425 Port = port() | atom()
4427 Pids = [pid()]
4428 Pids is a list of the process identifiers of the processes that
4430 the port is linked to.
4431 If the port identified by Port is not open, undefined is
4433 returned. If the port is closed and the calling process was pre‐
4434 viously linked to the port, the exit signal from the port is
4435 guaranteed to be delivered before port_info/2 returns undefined.
4436 Failure: badarg if Port is not a local port identifier, or an
4438 atom.
4439 erlang:port_info(Port, Item :: locking) ->
4441 {locking, Locking} | undefined
4442 Types:
4444 Port = port() | atom()
4446 Locking = false | port_level | driver_level
4447 Locking is one of the following:
4449 * port_level (port-specific locking)
4451 * driver_level (driver-specific locking)
4453 Notice that these results are highly implementation-specific and
4455 can change in a future release.
4456 If the port identified by Port is not open, undefined is
4458 returned. If the port is closed and the calling process was pre‐
4459 viously linked to the port, the exit signal from the port is
4460 guaranteed to be delivered before port_info/2 returns undefined.
4461 Failure: badarg if Port is not a local port identifier, or an
4463 atom.
4464 erlang:port_info(Port, Item :: memory) ->
4466 {memory, Bytes} | undefined
4467 Types:
4469 Port = port() | atom()
4471 Bytes = integer() >= 0
4472 Bytes is the total number of bytes allocated for this port by
4474 the runtime system. The port itself can have allocated memory
4475 that is not included in Bytes.
4476 If the port identified by Port is not open, undefined is
4478 returned. If the port is closed and the calling process was pre‐
4479 viously linked to the port, the exit signal from the port is
4480 guaranteed to be delivered before port_info/2 returns undefined.
4481 Failure: badarg if Port is not a local port identifier, or an
4483 atom.
4484 erlang:port_info(Port, Item :: monitors) ->
4486 {monitors, Monitors} | undefined
4487 Types:
4489 Port = port() | atom()
4491 Monitors = [{process, pid()}]
4492 Monitors represent processes monitored by this port.
4494 If the port identified by Port is not open, undefined is
4496 returned. If the port is closed and the calling process was pre‐
4497 viously linked to the port, the exit signal from the port is
4498 guaranteed to be delivered before port_info/2 returns undefined.
4499 Failure: badarg if Port is not a local port identifier, or an
4501 atom.
4502 erlang:port_info(Port, Item :: monitored_by) ->
4504 {monitored_by, MonitoredBy} | undefined
4505 Types:
4507 Port = port() | atom()
4509 MonitoredBy = [pid()]
4510 Returns list of pids that are monitoring given port at the
4512 moment.
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 :: name) -> {name, Name} | undefined
4523 Types:
4525 Port = port() | atom()
4527 Name = string()
4528 Name is the command name set by open_port/2.
4530 If the port identified by Port is not open, undefined is
4532 returned. If the port is closed and the calling process was pre‐
4533 viously linked to the port, the exit signal from the port is
4534 guaranteed to be delivered before port_info/2 returns undefined.
4535 Failure: badarg if Port is not a local port identifier, or an
4537 atom.
4538 erlang:port_info(Port, Item :: os_pid) ->
4540 {os_pid, OsPid} | undefined
4541 Types:
4543 Port = port() | atom()
4545 OsPid = integer() >= 0 | undefined
4546 OsPid is the process identifier (or equivalent) of an OS process
4548 created with open_port({spawn | spawn_executable, Command},
4549 Options). If the port is not the result of spawning an OS
4550 process, the value is undefined.
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 :: output) ->
4561 {output, Bytes} | undefined
4562 Types:
4564 Port = port() | atom()
4566 Bytes = integer() >= 0
4567 Bytes is the total number of bytes written to the port from
4569 Erlang processes using port_command/2, port_command/3, or Port !
4570 {Owner, {command, Data}.
4571 If the port identified by Port is not open, undefined is
4573 returned. If the port is closed and the calling process was pre‐
4574 viously linked to the port, the exit signal from the port is
4575 guaranteed to be delivered before port_info/2 returns undefined.
4576 Failure: badarg if Port is not a local port identifier, or an
4578 atom.
4579 erlang:port_info(Port, Item :: parallelism) ->
4581 {parallelism, Boolean} | undefined
4582 Types:
4584 Port = port() | atom()
4586 Boolean = boolean()
4587 Boolean corresponds to the port parallelism hint used by this
4589 port. For more information, see option parallelism of
4590 open_port/2.
4591 erlang:port_info(Port, Item :: queue_size) ->
4593 {queue_size, Bytes} | undefined
4594 Types:
4596 Port = port() | atom()
4598 Bytes = integer() >= 0
4599 Bytes is the total number of bytes queued by the port using the
4601 ERTS driver queue implementation.
4602 If the port identified by Port is not open, undefined is
4604 returned. If the port is closed and the calling process was pre‐
4605 viously linked to the port, the exit signal from the port is
4606 guaranteed to be delivered before port_info/2 returns undefined.
4607 Failure: badarg if Port is not a local port identifier, or an
4609 atom.
4610 erlang:port_info(Port, Item :: registered_name) ->
4612 {registered_name, RegisteredName} |
4613 [] |
4614 undefined
4615 Types:
4617 Port = port() | atom()
4619 RegisteredName = atom()
4620 RegisteredName is the registered name of the port. If the port
4622 has no registered name, [] is returned.
4623 If the port identified by Port is not open, undefined is
4625 returned. If the port is closed and the calling process was pre‐
4626 viously linked to the port, the exit signal from the port is
4627 guaranteed to be delivered before port_info/2 returns undefined.
4628 Failure: badarg if Port is not a local port identifier, or an
4630 atom.
4631 port_to_list(Port) -> string()
4633 Types:
4635 Port = port()
4637 Returns a string corresponding to the text representation of the
4639 port identifier Port.
4640 erlang:ports() -> [port()]
4642 Returns a list of port identifiers corresponding to all the
4644 ports existing on the local node.
4645 Notice that an exiting port exists, but is not open.
4647 pre_loaded() -> [module()]
4649 Returns a list of Erlang modules that are preloaded in the sys‐
4651 tem. As all loading of code is done through the file system, the
4652 file system must have been loaded previously. Hence, at least
4653 the module init must be preloaded.
4654 erlang:process_display(Pid, Type) -> true
4656 Types:
4658 Pid = pid()
4660 Type = backtrace
4661 Writes information about the local process Pid on standard
4663 error. The only allowed value for the atom Type is backtrace,
4664 which shows the contents of the call stack, including informa‐
4665 tion about the call chain, with the current function printed
4666 first. The format of the output is not further defined.
4667 process_flag(Flag :: trap_exit, Boolean) -> OldBoolean
4669 Types:
4671 Boolean = OldBoolean = boolean()
4673 When trap_exit is set to true, exit signals arriving to a
4675 process are converted to {'EXIT', From, Reason} messages, which
4676 can be received as ordinary messages. If trap_exit is set to
4677 false, the process exits if it receives an exit signal other
4678 than normal and the exit signal is propagated to its linked pro‐
4679 cesses. Application processes are normally not to trap exits.
4680 Returns the old value of the flag.
4682 See also exit/2.
4684 process_flag(Flag :: error_handler, Module) -> OldModule
4686 Types:
4688 Module = OldModule = atom()
4690 Used by a process to redefine the error handler for undefined
4692 function calls and undefined registered processes. Inexperienced
4693 users are not to use this flag, as code auto-loading depends on
4694 the correct operation of the error handling module.
4695 Returns the old value of the flag.
4697 process_flag(Flag :: min_heap_size, MinHeapSize) -> OldMinHeapSize
4699 Types:
4701 MinHeapSize = OldMinHeapSize = integer() >= 0
4703 Changes the minimum heap size for the calling process.
4705 Returns the old value of the flag.
4707 process_flag(Flag :: min_bin_vheap_size, MinBinVHeapSize) ->
4709 OldMinBinVHeapSize
4710 Types:
4712 MinBinVHeapSize = OldMinBinVHeapSize = integer() >= 0
4714 Changes the minimum binary virtual heap size for the calling
4716 process.
4717 Returns the old value of the flag.
4719 process_flag(Flag :: max_heap_size, MaxHeapSize) -> OldMaxHeapSize
4721 Types:
4723 MaxHeapSize = OldMaxHeapSize = max_heap_size()
4725 max_heap_size() =
4726 integer() >= 0 |
4727 #{size => integer() >= 0,
4728 kill => boolean(),
4729 error_logger => boolean()}
4730 This flag sets the maximum heap size for the calling process. If
4732 MaxHeapSize is an integer, the system default values for kill
4733 and error_logger are used.
4734 size:
4736 The maximum size in words of the process. If set to zero,
4737 the heap size limit is disabled. badarg is be thrown if the
4738 value is smaller than min_heap_size. The size check is only
4739 done when a garbage collection is triggered.
4740 size is the entire heap of the process when garbage collec‐
4742 tion is triggered. This includes all generational heaps, the
4743 process stack, any messages that are considered to be part
4744 of the heap, and any extra memory that the garbage collector
4745 needs during collection.
4746 size is the same as can be retrieved using
4748 erlang:process_info(Pid, total_heap_size), or by adding
4749 heap_block_size, old_heap_block_size and mbuf_size from
4750 erlang:process_info(Pid, garbage_collection_info).
4751 kill:
4753 When set to true, the runtime system sends an untrappable
4754 exit signal with reason kill to the process if the maximum
4755 heap size is reached. The garbage collection that triggered
4756 the kill is not completed, instead the process exits as soon
4757 as possible. When set to false, no exit signal is sent to
4758 the process, instead it continues executing.
4759 If kill is not defined in the map, the system default will
4761 be used. The default system default is true. It can be
4762 changed by either option +hmaxk in erl(1), or erlang:sys‐
4763 tem_flag(max_heap_size, MaxHeapSize).
4764 error_logger:
4766 When set to true, the runtime system logs an error event via
4767 logger, containing details about the process when the maxi‐
4768 mum heap size is reached. One log event is sent each time
4769 the limit is reached.
4770 If error_logger is not defined in the map, the system
4772 default is used. The default system default is true. It can
4773 be changed by either the option +hmaxel int erl(1), or
4774 erlang:system_flag(max_heap_size, MaxHeapSize).
4775 The heap size of a process is quite hard to predict, especially
4777 the amount of memory that is used during the garbage collection.
4778 When contemplating using this option, it is recommended to first
4779 run it in production with kill set to false and inspect the log
4780 events to see what the normal peak sizes of the processes in the
4781 system is and then tune the value accordingly.
4782 process_flag(Flag :: message_queue_data, MQD) -> OldMQD
4784 Types:
4786 MQD = OldMQD = message_queue_data()
4788 message_queue_data() = off_heap | on_heap
4789 This flag determines how messages in the message queue are
4791 stored, as follows:
4792 off_heap:
4794 All messages in the message queue will be stored outside of
4795 the process heap. This implies that no messages in the mes‐
4796 sage queue will be part of a garbage collection of the
4797 process.
4798 on_heap:
4800 All messages in the message queue will eventually be placed
4801 on heap. They can however temporarily be stored off heap.
4802 This is how messages always have been stored up until ERTS
4803 8.0.
4804 The default message_queue_data process flag is determined by
4806 command-line argument +hmqd in erl(1).
4807 If the process potentially can get many messages in its queue,
4809 you are advised to set the flag to off_heap. This because a
4810 garbage collection with many messages placed on the heap can
4811 become extremely expensive and the process can consume large
4812 amounts of memory. Performance of the actual message passing is
4813 however generally better when not using flag off_heap.
4814 When changing this flag messages will be moved. This work has
4816 been initiated but not completed when this function call
4817 returns.
4818 Returns the old value of the flag.
4820 process_flag(Flag :: priority, Level) -> OldLevel
4822 Types:
4824 Level = OldLevel = priority_level()
4826 priority_level() = low | normal | high | max
4827 Sets the process priority. Level is an atom. Four priority lev‐
4829 els exist: low, normal, high, and max. Default is normal.
4830 Note:
4832 Priority level max is reserved for internal use in the Erlang
4833 runtime system, and is not to be used by others.
4834 Internally in each priority level, processes are scheduled in a
4837 round robin fashion.
4838 Execution of processes on priority normal and low are inter‐
4840 leaved. Processes on priority low are selected for execution
4841 less frequently than processes on priority normal.
4842 When runnable processes on priority high exist, no processes on
4844 priority low or normal are selected for execution. Notice how‐
4845 ever that this does not mean that no processes on priority low
4846 or normal can run when processes are running on priority high.
4847 When using multiple schedulers, more processes can be running in
4848 parallel than processes on priority high. That is, a low and a
4849 high priority process can execute at the same time.
4850 When runnable processes on priority max exist, no processes on
4852 priority low, normal, or high are selected for execution. As
4853 with priority high, processes on lower priorities can execute in
4854 parallel with processes on priority max.
4855 Scheduling is pre-emptive. Regardless of priority, a process is
4857 pre-empted when it has consumed more than a certain number of
4858 reductions since the last time it was selected for execution.
4859 Note:
4861 Do not depend on the scheduling to remain exactly as it is
4862 today. Scheduling is likely to be changed in a future release to
4863 use available processor cores better.
4864 There is no automatic mechanism for avoiding priority inversion,
4867 such as priority inheritance or priority ceilings. When using
4868 priorities, take this into account and handle such scenarios by
4869 yourself.
4870 Making calls from a high priority process into code that you has
4872 no control over can cause the high priority process to wait for
4873 a process with lower priority. That is, effectively decreasing
4874 the priority of the high priority process during the call. Even
4875 if this is not the case with one version of the code that you
4876 have no control over, it can be the case in a future version of
4877 it. This can, for example, occur if a high priority process
4878 triggers code loading, as the code server runs on priority nor‐
4879 mal.
4880 Other priorities than normal are normally not needed. When other
4882 priorities are used, use them with care, especially priority
4883 high. A process on priority high is only to perform work for
4884 short periods. Busy looping for long periods in a high priority
4885 process causes most likely problems, as important OTP servers
4886 run on priority normal.
4887 Returns the old value of the flag.
4889 process_flag(Flag :: save_calls, N) -> OldN
4891 Types:
4893 N = OldN = 0..10000
4895 N must be an integer in the interval 0..10000. If N > 0, call
4897 saving is made active for the process. This means that informa‐
4898 tion about the N most recent global function calls, BIF calls,
4899 sends, and receives made by the process are saved in a list,
4900 which can be retrieved with process_info(Pid, last_calls). A
4901 global function call is one in which the module of the function
4902 is explicitly mentioned. Only a fixed amount of information is
4903 saved, as follows:
4904 * A tuple {Module, Function, Arity} for function calls
4906 * The atoms send, 'receive', and timeout for sends and
4908 receives ('receive' when a message is received and timeout
4909 when a receive times out)
4910 If N = 0, call saving is disabled for the process, which is the
4912 default. Whenever the size of the call saving list is set, its
4913 contents are reset.
4914 Returns the old value of the flag.
4916 process_flag(Flag :: sensitive, Boolean) -> OldBoolean
4918 Types:
4920 Boolean = OldBoolean = boolean()
4922 Sets or clears flag sensitive for the current process. When a
4924 process has been marked as sensitive by calling
4925 process_flag(sensitive, true), features in the runtime system
4926 that can be used for examining the data or inner working of the
4927 process are silently disabled.
4928 Features that are disabled include (but are not limited to) the
4930 following:
4931 * Tracing. Trace flags can still be set for the process, but
4933 no trace messages of any kind are generated. (If flag sensi‐
4934 tive is turned off, trace messages are again generated if
4935 any trace flags are set.)
4936 * Sequential tracing. The sequential trace token is propagated
4938 as usual, but no sequential trace messages are generated.
4939 process_info/1,2 cannot be used to read out the message queue or
4941 the process dictionary (both are returned as empty lists).
4942 Stack back-traces cannot be displayed for the process.
4944 In crash dumps, the stack, messages, and the process dictionary
4946 are omitted.
4947 If {save_calls,N} has been set for the process, no function
4949 calls are saved to the call saving list. (The call saving list
4950 is not cleared. Also, send, receive, and time-out events are
4951 still added to the list.)
4952 Returns the old value of the flag.
4954 process_flag(Pid, Flag, Value) -> OldValue
4956 Types:
4958 Pid = pid()
4960 Flag = save_calls
4961 Value = OldValue = integer() >= 0
4962 Sets certain flags for the process Pid, in the same manner as
4964 process_flag/2. Returns the old value of the flag. The valid
4965 values for Flag are only a subset of those allowed in
4966 process_flag/2, namely save_calls.
4967 Failure: badarg if Pid is not a local process.
4969 process_info(Pid) -> Info
4971 Types:
4973 Pid = pid()
4975 Info = [InfoTuple] | undefined
4976 InfoTuple = process_info_result_item()
4977 process_info_result_item() =
4978 {backtrace, Bin :: binary()} |
4979 {binary,
4980 BinInfo ::
4981 [{integer() >= 0,
4982 integer() >= 0,
4983 integer() >= 0}]} |
4984 {catchlevel, CatchLevel :: integer() >= 0} |
4985 {current_function,
4986 {Module :: module(), Function :: atom(), Arity :: arity()}} |
4987 {current_location,
4988 {Module :: module(),
4989 Function :: atom(),
4990 Arity :: arity(),
4991 Location ::
4992 [{file, Filename :: string()} |
4993 {line, Line :: integer() >= 1}]}} |
4994 {current_stacktrace, Stack :: [stack_item()]} |
4995 {dictionary, Dictionary :: [{Key :: term(), Value :: term()}]} |
4996 {error_handler, Module :: module()} |
4997 {garbage_collection, GCInfo :: [{atom(), integer() >= 0}]} |
4998 {garbage_collection_info,
4999 GCInfo :: [{atom(), integer() >= 0}]} |
5000 {group_leader, GroupLeader :: pid()} |
5001 {heap_size, Size :: integer() >= 0} |
5002 {initial_call, mfa()} |
5003 {links, PidsAndPorts :: [pid() | port()]} |
5004 {last_calls, false | (Calls :: [mfa()])} |
5005 {memory, Size :: integer() >= 0} |
5006 {message_queue_len, MessageQueueLen :: integer() >= 0} |
5007 {messages, MessageQueue :: [term()]} |
5008 {min_heap_size, MinHeapSize :: integer() >= 0} |
5009 {min_bin_vheap_size, MinBinVHeapSize :: integer() >= 0} |
5010 {max_heap_size, MaxHeapSize :: max_heap_size()} |
5011 {monitored_by,
5012 MonitoredBy :: [pid() | port() | nif_resource()]} |
5013 {monitors,
5014 Monitors ::
5015 [{process | port,
5016 Pid ::
5017 pid() |
5018 port() |
5019 {RegName :: atom(), Node :: node()}}]} |
5020 {message_queue_data, MQD :: message_queue_data()} |
5021 {priority, Level :: priority_level()} |
5022 {reductions, Number :: integer() >= 0} |
5023 {registered_name, [] | (Atom :: atom())} |
5024 {sequential_trace_token,
5025 [] | (SequentialTraceToken :: term())} |
5026 {stack_size, Size :: integer() >= 0} |
5027 {status,
5028 Status ::
5029 exiting |
5030 garbage_collecting |
5031 waiting |
5032 running |
5033 runnable |
5034 suspended} |
5035 {suspending,
5036 SuspendeeList ::
5037 [{Suspendee :: pid(),
5038 ActiveSuspendCount :: integer() >= 0,
5039 OutstandingSuspendCount :: integer() >= 0}]} |
5040 {total_heap_size, Size :: integer() >= 0} |
5041 {trace, InternalTraceFlags :: integer() >= 0} |
5042 {trap_exit, Boolean :: boolean()}
5043 priority_level() = low | normal | high | max
5044 stack_item() =
5045 {Module :: module(),
5046 Function :: atom(),
5047 Arity :: arity() | (Args :: [term()]),
5048 Location ::
5049 [{file, Filename :: string()} |
5050 {line, Line :: integer() >= 1}]}
5051 max_heap_size() =
5052 integer() >= 0 |
5053 #{size => integer() >= 0,
5054 kill => boolean(),
5055 error_logger => boolean()}
5056 message_queue_data() = off_heap | on_heap
5057 Returns a list containing InfoTuples with miscellaneous informa‐
5059 tion about the process identified by Pid, or undefined if the
5060 process is not alive.
5061 The order of the InfoTuples is undefined and all InfoTuples are
5063 not mandatory. The InfoTuples part of the result can be changed
5064 without prior notice.
5065 The InfoTuples with the following items are part of the result:
5067 * current_function
5069 * initial_call
5071 * status
5073 * message_queue_len
5075 * links
5077 * dictionary
5079 * trap_exit
5081 * error_handler
5083 * priority
5085 * group_leader
5087 * total_heap_size
5089 * heap_size
5091 * stack_size
5093 * reductions
5095 * garbage_collection
5097 If the process identified by Pid has a registered name, also an
5099 InfoTuple with item registered_name is included.
5100 For information about specific InfoTuples, see process_info/2.
5102 Warning:
5104 This BIF is intended for debugging only. For all other purposes,
5105 use process_info/2.
5106 Failure: badarg if Pid is not a local process.
5109 process_info(Pid, Item) -> InfoTuple | [] | undefined
5111 process_info(Pid, ItemList) -> InfoTupleList | [] | undefined
5113 Types:
5115 Pid = pid()
5117 ItemList = [Item]
5118 Item = process_info_item()
5119 InfoTupleList = [InfoTuple]
5120 InfoTuple = process_info_result_item()
5121 process_info_item() =
5122 backtrace |
5123 binary |
5124 catchlevel |
5125 current_function |
5126 current_location |
5127 current_stacktrace |
5128 dictionary |
5129 error_handler |
5130 garbage_collection |
5131 garbage_collection_info |
5132 group_leader |
5133 heap_size |
5134 initial_call |
5135 links |
5136 last_calls |
5137 memory |
5138 message_queue_len |
5139 messages |
5140 min_heap_size |
5141 min_bin_vheap_size |
5142 monitored_by |
5143 monitors |
5144 message_queue_data |
5145 priority |
5146 reductions |
5147 registered_name |
5148 sequential_trace_token |
5149 stack_size |
5150 status |
5151 suspending |
5152 total_heap_size |
5153 trace |
5154 trap_exit
5155 process_info_result_item() =
5156 {backtrace, Bin :: binary()} |
5157 {binary,
5158 BinInfo ::
5159 [{integer() >= 0,
5160 integer() >= 0,
5161 integer() >= 0}]} |
5162 {catchlevel, CatchLevel :: integer() >= 0} |
5163 {current_function,
5164 {Module :: module(), Function :: atom(), Arity :: arity()}} |
5165 {current_location,
5166 {Module :: module(),
5167 Function :: atom(),
5168 Arity :: arity(),
5169 Location ::
5170 [{file, Filename :: string()} |
5171 {line, Line :: integer() >= 1}]}} |
5172 {current_stacktrace, Stack :: [stack_item()]} |
5173 {dictionary, Dictionary :: [{Key :: term(), Value :: term()}]} |
5174 {error_handler, Module :: module()} |
5175 {garbage_collection, GCInfo :: [{atom(), integer() >= 0}]} |
5176 {garbage_collection_info,
5177 GCInfo :: [{atom(), integer() >= 0}]} |
5178 {group_leader, GroupLeader :: pid()} |
5179 {heap_size, Size :: integer() >= 0} |
5180 {initial_call, mfa()} |
5181 {links, PidsAndPorts :: [pid() | port()]} |
5182 {last_calls, false | (Calls :: [mfa()])} |
5183 {memory, Size :: integer() >= 0} |
5184 {message_queue_len, MessageQueueLen :: integer() >= 0} |
5185 {messages, MessageQueue :: [term()]} |
5186 {min_heap_size, MinHeapSize :: integer() >= 0} |
5187 {min_bin_vheap_size, MinBinVHeapSize :: integer() >= 0} |
5188 {max_heap_size, MaxHeapSize :: max_heap_size()} |
5189 {monitored_by,
5190 MonitoredBy :: [pid() | port() | nif_resource()]} |
5191 {monitors,
5192 Monitors ::
5193 [{process | port,
5194 Pid ::
5195 pid() |
5196 port() |
5197 {RegName :: atom(), Node :: node()}}]} |
5198 {message_queue_data, MQD :: message_queue_data()} |
5199 {priority, Level :: priority_level()} |
5200 {reductions, Number :: integer() >= 0} |
5201 {registered_name, [] | (Atom :: atom())} |
5202 {sequential_trace_token,
5203 [] | (SequentialTraceToken :: term())} |
5204 {stack_size, Size :: integer() >= 0} |
5205 {status,
5206 Status ::
5207 exiting |
5208 garbage_collecting |
5209 waiting |
5210 running |
5211 runnable |
5212 suspended} |
5213 {suspending,
5214 SuspendeeList ::
5215 [{Suspendee :: pid(),
5216 ActiveSuspendCount :: integer() >= 0,
5217 OutstandingSuspendCount :: integer() >= 0}]} |
5218 {total_heap_size, Size :: integer() >= 0} |
5219 {trace, InternalTraceFlags :: integer() >= 0} |
5220 {trap_exit, Boolean :: boolean()}
5221 stack_item() =
5222 {Module :: module(),
5223 Function :: atom(),
5224 Arity :: arity() | (Args :: [term()]),
5225 Location ::
5226 [{file, Filename :: string()} |
5227 {line, Line :: integer() >= 1}]}
5228 priority_level() = low | normal | high | max
5229 max_heap_size() =
5230 integer() >= 0 |
5231 #{size => integer() >= 0,
5232 kill => boolean(),
5233 error_logger => boolean()}
5234 message_queue_data() = off_heap | on_heap
5235 Returns information about the process identified by Pid, as
5237 specified by Item or ItemList. Returns undefined if the process
5238 is not alive.
5239 If the process is alive and a single Item is specified, the
5241 returned value is the corresponding InfoTuple, unless Item =:=
5242 registered_name and the process has no registered name. In this
5243 case, [] is returned. This strange behavior is because of his‐
5244 torical reasons, and is kept for backward compatibility.
5245 If ItemList is specified, the result is InfoTupleList. The Info‐
5247 Tuples in InfoTupleList are included with the corresponding
5248 Items in the same order as the Items were included in ItemList.
5249 Valid Items can be included multiple times in ItemList.
5250 Note:
5252 If registered_name is part of ItemList and the process has no
5253 name registered, a {registered_name, []}, InfoTuple will be
5254 included in the resulting InfoTupleList. This behavior is dif‐
5255 ferent when a single Item =:= registered_name is specified, and
5256 when process_info/1 is used.
5257 Valid InfoTuples with corresponding Items:
5260 {backtrace, Bin}:
5262 Binary Bin contains the same information as the output from
5263 erlang:process_display(Pid, backtrace). Use binary_to_list/1
5264 to obtain the string of characters from the binary.
5265 {binary, BinInfo}:
5267 BinInfo is a list containing miscellaneous information about
5268 binaries on the heap of this process. This InfoTuple can be
5269 changed or removed without prior notice. In the current
5270 implementation BinInfo is a list of tuples. The tuples con‐
5271 tain; BinaryId, BinarySize, BinaryRefcCount.
5272 The message queue is on the heap depending on the process
5274 flag message_queue_data.
5275 {catchlevel, CatchLevel}:
5277 CatchLevel is the number of currently active catches in this
5278 process. This InfoTuple can be changed or removed without
5279 prior notice.
5280 {current_function, {Module, Function, Arity}}:
5282 Module, Function, Arity is the current function call of the
5283 process.
5284 {current_location, {Module, Function, Arity, Location}}:
5286 Module, Function, Arity is the current function call of the
5287 process. Location is a list of two-tuples describing the
5288 location in the source code.
5289 {current_stacktrace, Stack}:
5291 Returns the current call stack back-trace (stacktrace) of
5292 the process. The stack has the same format as returned by
5293 erlang:get_stacktrace/0. The depth of the stacktrace is
5294 truncated according to the backtrace_depth system flag set‐
5295 ting.
5296 {dictionary, Dictionary}:
5298 Dictionary is the process dictionary.
5299 {error_handler, Module}:
5301 Module is the error handler module used by the process (for
5302 undefined function calls, for example).
5303 {garbage_collection, GCInfo}:
5305 GCInfo is a list containing miscellaneous information about
5306 garbage collection for this process. The content of GCInfo
5307 can be changed without prior notice.
5308 {garbage_collection_info, GCInfo}:
5310 GCInfo is a list containing miscellaneous detailed informa‐
5311 tion about garbage collection for this process. The content
5312 of GCInfo can be changed without prior notice. For details
5313 about the meaning of each item, see gc_minor_start in
5314 erlang:trace/3.
5315 {group_leader, GroupLeader}:
5317 GroupLeader is the group leader for the I/O of the process.
5318 {heap_size, Size}:
5320 Size is the size in words of the youngest heap generation of
5321 the process. This generation includes the process stack.
5322 This information is highly implementation-dependent, and can
5323 change if the implementation changes.
5324 {initial_call, {Module, Function, Arity}}:
5326 Module, Function, Arity is the initial function call with
5327 which the process was spawned.
5328 {links, PidsAndPorts}:
5330 PidsAndPorts is a list of process identifiers and port iden‐
5331 tifiers, with processes or ports to which the process has a
5332 link.
5333 {last_calls, false|Calls}:
5335 The value is false if call saving is not active for the
5336 process (see process_flag/3). If call saving is active, a
5337 list is returned, in which the last element is the most
5338 recent called.
5339 {memory, Size}:
5341 Size is the size in bytes of the process. This includes call
5342 stack, heap, and internal structures.
5343 {message_queue_len, MessageQueueLen}:
5345 MessageQueueLen is the number of messages currently in the
5346 message queue of the process. This is the length of the list
5347 MessageQueue returned as the information item messages (see
5348 below).
5349 {messages, MessageQueue}:
5351 MessageQueue is a list of the messages to the process, which
5352 have not yet been processed.
5353 {min_heap_size, MinHeapSize}:
5355 MinHeapSize is the minimum heap size for the process.
5356 {min_bin_vheap_size, MinBinVHeapSize}:
5358 MinBinVHeapSize is the minimum binary virtual heap size for
5359 the process.
5360 {monitored_by, MonitoredBy}:
5362 A list of identifiers for all the processes, ports and NIF
5363 resources, that are monitoring the process.
5364 {monitors, Monitors}:
5366 A list of monitors (started by monitor/2) that are active
5367 for the process. For a local process monitor or a remote
5368 process monitor by a process identifier, the list consists
5369 of:
5370 {process, Pid}:
5372 Process is monitored by pid.
5373 {process, {RegName, Node}}:
5375 Local or remote process is monitored by name.
5376 {port, PortId}:
5378 Local port is monitored by port id.
5379 {port, {RegName, Node}}:
5381 Local port is monitored by name. Please note, that remote
5382 port monitors are not supported, so Node will always be
5383 the local node name.
5384 {message_queue_data, MQD}:
5386 Returns the current state of process flag mes‐
5387 sage_queue_data. MQD is either off_heap or on_heap. For more
5388 information, see the documentation of process_flag(mes‐
5389 sage_queue_data, MQD).
5390 {priority, Level}:
5392 Level is the current priority level for the process. For
5393 more information on priorities, see process_flag(priority,
5394 Level).
5395 {reductions, Number}:
5397 Number is the number of reductions executed by the process.
5398 {registered_name, Atom}:
5400 Atom is the registered process name. If the process has no
5401 registered name, this tuple is not present in the list.
5402 {sequential_trace_token, [] | SequentialTraceToken}:
5404 SequentialTraceToken is the sequential trace token for the
5405 process. This InfoTuple can be changed or removed without
5406 prior notice.
5407 {stack_size, Size}:
5409 Size is the stack size, in words, of the process.
5410 {status, Status}:
5412 Status is the status of the process and is one of the fol‐
5413 lowing:
5414 * exiting
5416 * garbage_collecting
5418 * waiting (for a message)
5420 * running
5422 * runnable (ready to run, but another process is running)
5424 * suspended (suspended on a "busy" port or by the BIF
5426 erlang:suspend_process/1,2)
5427 {suspending, SuspendeeList}:
5429 SuspendeeList is a list of {Suspendee, ActiveSuspendCount,
5430 OutstandingSuspendCount} tuples. Suspendee is the process
5431 identifier of a process that has been, or is to be, sus‐
5432 pended by the process identified by Pid through the BIF
5433 erlang:suspend_process/2 or erlang:suspend_process/1.
5434 ActiveSuspendCount is the number of times Suspendee has been
5436 suspended by Pid. OutstandingSuspendCount is the number of
5437 not yet completed suspend requests sent by Pid, that is:
5438 * If ActiveSuspendCount =/= 0, Suspendee is currently in the
5440 suspended state.
5441 * If OutstandingSuspendCount =/= 0, option asynchronous of
5443 erlang:suspend_process/2 has been used and the suspendee
5444 has not yet been suspended by Pid.
5445 Notice that ActiveSuspendCount and OutstandingSuspendCount
5447 are not the total suspend count on Suspendee, only the parts
5448 contributed by Pid.
5449 {total_heap_size, Size}:
5451 Size is the total size, in words, of all heap fragments of
5452 the process. This includes the process stack and any unre‐
5453 ceived messages that are considered to be part of the heap.
5454 {trace, InternalTraceFlags}:
5456 InternalTraceFlags is an integer representing the internal
5457 trace flag for this process. This InfoTuple can be changed
5458 or removed without prior notice.
5459 {trap_exit, Boolean}:
5461 Boolean is true if the process is trapping exits, otherwise
5462 false.
5463 Notice that not all implementations support all these Items.
5465 Failures:
5467 badarg:
5469 If Pid is not a local process.
5470 badarg:
5472 If Item is an invalid item.
5473 processes() -> [pid()]
5475 Returns a list of process identifiers corresponding to all the
5477 processes currently existing on the local node.
5478 Notice that an exiting process exists, but is not alive. That
5480 is, is_process_alive/1 returns false for an exiting process, but
5481 its process identifier is part of the result returned from pro‐
5482 cesses/0.
5483 Example:
5485 > processes().
5487 [<0.0.0>,<0.2.0>,<0.4.0>,<0.5.0>,<0.7.0>,<0.8.0>]
5488 purge_module(Module) -> true
5490 Types:
5492 Module = atom()
5494 Removes old code for Module. Before this BIF is used,
5496 check_process_code/2is to be called to check that no processes
5497 execute old code in the module.
5498 Warning:
5500 This BIF is intended for the code server (see code(3)) and is
5501 not to be used elsewhere.
5502 Note:
5505 As from ERTS 8.0 (Erlang/OTP 19), any lingering processes that
5506 still execute the old code is killed by this function. In ear‐
5507 lier versions, such incorrect use could cause much more fatal
5508 failures, like emulator crash.
5509 Failure: badarg if there is no old code for Module.
5512 put(Key, Val) -> term()
5514 Types:
5516 Key = Val = term()
5518 Adds a new Key to the process dictionary, associated with the
5520 value Val, and returns undefined. If Key exists, the old value
5521 is deleted and replaced by Val, and the function returns the old
5522 value. Example:
5523 > X = put(name, walrus), Y = put(name, carpenter),
5525 Z = get(name),
5526 {X, Y, Z}.
5527 {undefined,walrus,carpenter}
5528 Note:
5530 The values stored when put is evaluated within the scope of a
5531 catch are not retracted if a throw is evaluated, or if an error
5532 occurs.
5533 erlang:raise(Class, Reason, Stacktrace) -> no_return()
5536 Types:
5538 Class = error | exit | throw
5540 Reason = term()
5541 Stacktrace = raise_stacktrace()
5542 raise_stacktrace() =
5543 [{module(), atom(), arity() | [term()]} |
5544 {function(), [term()]}] |
5545 [{module(), atom(), arity() | [term()], [{atom(), term()}]} |
5546 {function(), [term()], [{atom(), term()}]}]
5547 Stops the execution of the calling process with an exception of
5549 the specified class, reason, and call stack backtrace (stack‐
5550 trace).
5551 Class is error, exit, or throw. So, if it were not for the
5553 stacktrace, erlang:raise(Class, Reason, Stacktrace) is equiva‐
5554 lent to erlang:Class(Reason).
5555 Reason is any term. Stacktrace is a list as returned from
5557 get_stacktrace(), that is, a list of four-tuples {Module, Func‐
5558 tion, Arity | Args, Location}, where Module and Function are
5559 atoms, and the third element is an integer arity or an argument
5560 list. The stacktrace can also contain {Fun, Args, Location}
5561 tuples, where Fun is a local fun and Args is an argument list.
5562 Element Location at the end is optional. Omitting it is equiva‐
5564 lent to specifying an empty list.
5565 The stacktrace is used as the exception stacktrace for the call‐
5567 ing process; it is truncated to the current maximum stacktrace
5568 depth.
5569 As evaluating this function causes the process to terminate, it
5571 has no return value unless the arguments are invalid, in which
5572 case the function returns the error reason badarg. If you want
5573 to be sure not to return, you can call error(erlang:raise(Class,
5574 Reason, Stacktrace)) and hope to distinguish exceptions later.
5575 erlang:read_timer(TimerRef) -> Result
5577 Types:
5579 TimerRef = reference()
5581 Time = integer() >= 0
5582 Result = Time | false
5583 Reads the state of a timer. The same as calling
5585 erlang:read_timer(TimerRef, []).
5586 erlang:read_timer(TimerRef, Options) -> Result | ok
5588 Types:
5590 TimerRef = reference()
5592 Async = boolean()
5593 Option = {async, Async}
5594 Options = [Option]
5595 Time = integer() >= 0
5596 Result = Time | false
5597 Reads the state of a timer that has been created by either
5599 erlang:start_timer or erlang:send_after. TimerRef identifies the
5600 timer, and was returned by the BIF that created the timer.
5601 Options:
5603 {async, Async}:
5605 Asynchronous request for state information. Async defaults
5606 to false, which causes the operation to be performed syn‐
5607 chronously. In this case, the Result is returned by
5608 erlang:read_timer. When Async is true, erlang:read_timer
5609 sends an asynchronous request for the state information to
5610 the timer service that manages the timer, and then returns
5611 ok. A message on the format {read_timer, TimerRef, Result}
5612 is sent to the caller of erlang:read_timer when the opera‐
5613 tion has been processed.
5614 More Options can be added in the future.
5616 If Result is an integer, it represents the time in milliseconds
5618 left until the timer expires.
5619 If Result is false, a timer corresponding to TimerRef could not
5621 be found. This because the timer had expired, or been canceled,
5622 or because TimerRef never has corresponded to a timer. Even if
5623 the timer has expired, it does not tell you whether or not the
5624 time-out message has arrived at its destination yet.
5625 Note:
5627 The timer service that manages the timer can be co-located with
5628 another scheduler than the scheduler that the calling process is
5629 executing on. If so, communication with the timer service takes
5630 much longer time than if it is located locally. If the calling
5631 process is in a critical path, and can do other things while
5632 waiting for the result of this operation, you want to use option
5633 {async, true}. If using option {async, false}, the calling
5634 process is blocked until the operation has been performed.
5635 See also erlang:send_after/4, erlang:start_timer/4, and
5638 erlang:cancel_timer/2.
5639 ref_to_list(Ref) -> string()
5641 Types:
5643 Ref = reference()
5645 Returns a string corresponding to the text representation of
5647 Ref.
5648 Warning:
5650 This BIF is intended for debugging and is not to be used in
5651 application programs.
5652 register(RegName, PidOrPort) -> true
5655 Types:
5657 RegName = atom()
5659 PidOrPort = port() | pid()
5660 Associates the name RegName with a process identifier (pid) or a
5662 port identifier. RegName, which must be an atom, can be used
5663 instead of the pid or port identifier in send operator (RegName
5664 ! Message). Example:
5665 > register(db, Pid).
5667 true
5668 Failures:
5670 badarg:
5672 If PidOrPort is not an existing local process or port.
5673 badarg:
5675 If RegName is already in use.
5676 badarg:
5678 If the process or port is already registered (already has a
5679 name).
5680 badarg:
5682 If RegName is the atom undefined.
5683 registered() -> [RegName]
5685 Types:
5687 RegName = atom()
5689 Returns a list of names that have been registered using regis‐
5691 ter/2, for example:
5692 > registered().
5694 [code_server, file_server, init, user, my_db]
5695 erlang:resume_process(Suspendee) -> true
5697 Types:
5699 Suspendee = pid()
5701 Decreases the suspend count on the process identified by Sus‐
5703 pendee. Suspendee is previously to have been suspended through
5704 erlang:suspend_process/2 or erlang:suspend_process/1 by the
5705 process calling erlang:resume_process(Suspendee). When the sus‐
5706 pend count on Suspendee reaches zero, Suspendee is resumed, that
5707 is, its state is changed from suspended into the state it had
5708 before it was suspended.
5709 Warning:
5711 This BIF is intended for debugging only.
5712 Failures:
5715 badarg:
5717 If Suspendee is not a process identifier.
5718 badarg:
5720 If the process calling erlang:resume_process/1 had not pre‐
5721 viously increased the suspend count on the process identi‐
5722 fied by Suspendee.
5723 badarg:
5725 If the process identified by Suspendee is not alive.
5726 round(Number) -> integer()
5728 Types:
5730 Number = number()
5732 Returns an integer by rounding Number, for example:
5734 round(5.5).
5736 6
5737 Allowed in guard tests.
5739 self() -> pid()
5741 Returns the process identifier of the calling process, for exam‐
5743 ple:
5744 > self().
5746 <0.26.0>
5747 Allowed in guard tests.
5749 erlang:send(Dest, Msg) -> Msg
5751 Types:
5753 Dest = dst()
5755 Msg = term()
5756 dst() =
5757 pid() |
5758 port() |
5759 (RegName :: atom()) |
5760 {RegName :: atom(), Node :: node()}
5761 Sends a message and returns Msg. This is the same as using the
5763 send operator: Dest ! Msg.
5764 Dest can be a remote or local process identifier, a (local)
5766 port, a locally registered name, or a tuple {RegName, Node} for
5767 a registered name at another node.
5768 The function fails with a badarg run-time error if Dest is an
5770 atom name, but this name is not registered. This is the only
5771 case when send fails for an unreachable destination Dest (of
5772 correct type).
5773 erlang:send(Dest, Msg, Options) -> Res
5775 Types:
5777 Dest = dst()
5779 Msg = term()
5780 Options = [nosuspend | noconnect]
5781 Res = ok | nosuspend | noconnect
5782 dst() =
5783 pid() |
5784 port() |
5785 (RegName :: atom()) |
5786 {RegName :: atom(), Node :: node()}
5787 Either sends a message and returns ok, or does not send the mes‐
5789 sage but returns something else (see below). Otherwise the same
5790 as erlang:send/2. For more detailed explanation and warnings,
5791 see erlang:send_nosuspend/2,3.
5792 Options:
5794 nosuspend:
5796 If the sender would have to be suspended to do the send,
5797 nosuspend is returned instead.
5798 noconnect:
5800 If the destination node would have to be auto-connected to
5801 do the send, noconnect is returned instead.
5802 Warning:
5804 As with erlang:send_nosuspend/2,3: use with extreme care.
5805 erlang:send_after(Time, Dest, Msg) -> TimerRef
5808 Types:
5810 Time = integer() >= 0
5812 Dest = pid() | atom()
5813 Msg = term()
5814 TimerRef = reference()
5815 Starts a timer. The same as calling erlang:send_after(Time,
5817 Dest, Msg, []).
5818 erlang:send_after(Time, Dest, Msg, Options) -> TimerRef
5820 Types:
5822 Time = integer()
5824 Dest = pid() | atom()
5825 Msg = term()
5826 Options = [Option]
5827 Abs = boolean()
5828 Option = {abs, Abs}
5829 TimerRef = reference()
5830 Starts a timer. When the timer expires, the message Msg is sent
5832 to the process identified by Dest. Apart from the format of the
5833 time-out message, this function works exactly as
5834 erlang:start_timer/4.
5835 erlang:send_nosuspend(Dest, Msg) -> boolean()
5837 Types:
5839 Dest = dst()
5841 Msg = term()
5842 dst() =
5843 pid() |
5844 port() |
5845 (RegName :: atom()) |
5846 {RegName :: atom(), Node :: node()}
5847 The same as erlang:send(Dest, Msg, [nosuspend]), but returns
5849 true if the message was sent and false if the message was not
5850 sent because the sender would have had to be suspended.
5851 This function is intended for send operations to an unreliable
5853 remote node without ever blocking the sending (Erlang) process.
5854 If the connection to the remote node (usually not a real Erlang
5855 node, but a node written in C or Java) is overloaded, this func‐
5856 tion does not send the message and returns false.
5857 The same occurs if Dest refers to a local port that is busy. For
5859 all other destinations (allowed for the ordinary send operator
5860 '!'), this function sends the message and returns true.
5861 This function is only to be used in rare circumstances where a
5863 process communicates with Erlang nodes that can disappear with‐
5864 out any trace, causing the TCP buffers and the drivers queue to
5865 be over-full before the node is shut down (because of tick time-
5866 outs) by net_kernel. The normal reaction to take when this
5867 occurs is some kind of premature shutdown of the other node.
5868 Notice that ignoring the return value from this function would
5870 result in an unreliable message passing, which is contradictory
5871 to the Erlang programming model. The message is not sent if this
5872 function returns false.
5873 In many systems, transient states of overloaded queues are nor‐
5875 mal. Although this function returns false does not mean that the
5876 other node is guaranteed to be non-responsive, it could be a
5877 temporary overload. Also, a return value of true does only mean
5878 that the message can be sent on the (TCP) channel without block‐
5879 ing; the message is not guaranteed to arrive at the remote node.
5880 For a disconnected non-responsive node, the return value is true
5881 (mimics the behavior of operator !). The expected behavior and
5882 the actions to take when the function returns false are applica‐
5883 tion- and hardware-specific.
5884 Warning:
5886 Use with extreme care.
5887 erlang:send_nosuspend(Dest, Msg, Options) -> boolean()
5890 Types:
5892 Dest = dst()
5894 Msg = term()
5895 Options = [noconnect]
5896 dst() =
5897 pid() |
5898 port() |
5899 (RegName :: atom()) |
5900 {RegName :: atom(), Node :: node()}
5901 The same as erlang:send(Dest, Msg, [nosuspend | Options]), but
5903 with a Boolean return value.
5904 This function behaves like erlang:send_nosuspend/2, but takes a
5906 third parameter, a list of options. The only option is nocon‐
5907 nect, which makes the function return false if the remote node
5908 is not currently reachable by the local node. The normal behav‐
5909 ior is to try to connect to the node, which can stall the
5910 process during a short period. The use of option noconnect makes
5911 it possible to be sure not to get the slightest delay when send‐
5912 ing to a remote process. This is especially useful when communi‐
5913 cating with nodes that expect to always be the connecting part
5914 (that is, nodes written in C or Java).
5915 Whenever the function returns false (either when a suspend would
5917 occur or when noconnect was specified and the node was not
5918 already connected), the message is guaranteed not to have been
5919 sent.
5920 Warning:
5922 Use with extreme care.
5923 erlang:set_cookie(Node, Cookie) -> true
5926 Types:
5928 Node = node()
5930 Cookie = atom()
5931 Sets the magic cookie of Node to the atom Cookie. If Node is the
5933 local node, the function also sets the cookie of all other
5934 unknown nodes to Cookie (see section Distributed Erlang in the
5935 Erlang Reference Manual in System Documentation).
5936 Failure: function_clause if the local node is not alive.
5938 setelement(Index, Tuple1, Value) -> Tuple2
5940 Types:
5942 Index = integer() >= 1
5944 1..tuple_size(Tuple1
5945 Tuple1 = Tuple2 = tuple()
5946 Value = term()
5947 Returns a tuple that is a copy of argument Tuple1 with the ele‐
5949 ment specified by integer argument Index (the first element is
5950 the element with index 1) replaced by argument Value, for exam‐
5951 ple:
5952 > setelement(2, {10, green, bottles}, red).
5954 {10,red,bottles}
5955 size(Item) -> integer() >= 0
5957 Types:
5959 Item = tuple() | binary()
5961 Returns the number of elements in a tuple or the number of bytes
5963 in a binary or bitstring, for example:
5964 > size({morni, mulle, bwange}).
5966 3
5967 > size(<<11, 22, 33>>).
5968 3
5969 For bitstrings, the number of whole bytes is returned. That is,
5971 if the number of bits in the bitstring is not divisible by 8,
5972 the resulting number of bytes is rounded down.
5973 Allowed in guard tests.
5975 See also tuple_size/1, byte_size/1, and bit_size/1.
5977 spawn(Fun) -> pid()
5979 Types:
5981 Fun = function()
5983 Returns the process identifier of a new process started by the
5985 application of Fun to the empty list []. Otherwise works like
5986 spawn/3.
5987 spawn(Node, Fun) -> pid()
5989 Types:
5991 Node = node()
5993 Fun = function()
5994 Returns the process identifier of a new process started by the
5996 application of Fun to the empty list [] on Node. If Node does
5997 not exist, a useless pid is returned. Otherwise works like
5998 spawn/3.
5999 spawn(Module, Function, Args) -> pid()
6001 Types:
6003 Module = module()
6005 Function = atom()
6006 Args = [term()]
6007 Returns the process identifier of a new process started by the
6009 application of Module:Function to Args.
6010 error_handler:undefined_function(Module, Function, Args) is
6012 evaluated by the new process if Module:Function/Arity does not
6013 exist (where Arity is the length of Args). The error handler can
6014 be redefined (see process_flag/2). If error_handler is unde‐
6015 fined, or the user has redefined the default error_handler and
6016 its replacement is undefined, a failure with reason undef
6017 occurs.
6018 Example:
6020 > spawn(speed, regulator, [high_speed, thin_cut]).
6022 <0.13.1>
6023 spawn(Node, Module, Function, Args) -> pid()
6025 Types:
6027 Node = node()
6029 Module = module()
6030 Function = atom()
6031 Args = [term()]
6032 Returns the process identifier (pid) of a new process started by
6034 the application of Module:Function to Args on Node. If Node does
6035 not exist, a useless pid is returned. Otherwise works like
6036 spawn/3.
6037 spawn_link(Fun) -> pid()
6039 Types:
6041 Fun = function()
6043 Returns the process identifier of a new process started by the
6045 application of Fun to the empty list []. A link is created
6046 between the calling process and the new process, atomically.
6047 Otherwise works like spawn/3.
6048 spawn_link(Node, Fun) -> pid()
6050 Types:
6052 Node = node()
6054 Fun = function()
6055 Returns the process identifier (pid) of a new process started by
6057 the application of Fun to the empty list [] on Node. A link is
6058 created between the calling process and the new process, atomi‐
6059 cally. If Node does not exist, a useless pid is returned and an
6060 exit signal with reason noconnection is sent to the calling
6061 process. Otherwise works like spawn/3.
6062 spawn_link(Module, Function, Args) -> pid()
6064 Types:
6066 Module = module()
6068 Function = atom()
6069 Args = [term()]
6070 Returns the process identifier of a new process started by the
6072 application of Module:Function to Args. A link is created
6073 between the calling process and the new process, atomically.
6074 Otherwise works like spawn/3.
6075 spawn_link(Node, Module, Function, Args) -> pid()
6077 Types:
6079 Node = node()
6081 Module = module()
6082 Function = atom()
6083 Args = [term()]
6084 Returns the process identifier (pid) of a new process started by
6086 the application of Module:Function to Args 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_monitor(Fun) -> {pid(), reference()}
6093 Types:
6095 Fun = function()
6097 Returns the process identifier of a new process, started by the
6099 application of Fun to the empty list [], and a reference for a
6100 monitor created to the new process. Otherwise works like
6101 spawn/3.
6102 spawn_monitor(Module, Function, Args) -> {pid(), reference()}
6104 Types:
6106 Module = module()
6108 Function = atom()
6109 Args = [term()]
6110 A new process is started by the application of Module:Function
6112 to Args. The process is monitored at the same time. Returns the
6113 process identifier and a reference for the monitor. Otherwise
6114 works like spawn/3.
6115 spawn_opt(Fun, Options) -> pid() | {pid(), reference()}
6117 Types:
6119 Fun = function()
6121 Options = [spawn_opt_option()]
6122 priority_level() = low | normal | high | max
6123 max_heap_size() =
6124 integer() >= 0 |
6125 #{size => integer() >= 0,
6126 kill => boolean(),
6127 error_logger => boolean()}
6128 message_queue_data() = off_heap | on_heap
6129 spawn_opt_option() =
6130 link |
6131 monitor |
6132 {priority, Level :: priority_level()} |
6133 {fullsweep_after, Number :: integer() >= 0} |
6134 {min_heap_size, Size :: integer() >= 0} |
6135 {min_bin_vheap_size, VSize :: integer() >= 0} |
6136 {max_heap_size, Size :: max_heap_size()} |
6137 {message_queue_data, MQD :: message_queue_data()}
6138 Returns the process identifier (pid) of a new process started by
6140 the application of Fun to the empty list []. Otherwise works
6141 like spawn_opt/4.
6142 If option monitor is specified, the newly created process is
6144 monitored, and both the pid and reference for the monitor are
6145 returned.
6146 spawn_opt(Node, Fun, Options) -> pid() | {pid(), reference()}
6148 Types:
6150 Node = node()
6152 Fun = function()
6153 Options = [spawn_opt_option()]
6154 priority_level() = low | normal | high | max
6155 max_heap_size() =
6156 integer() >= 0 |
6157 #{size => integer() >= 0,
6158 kill => boolean(),
6159 error_logger => boolean()}
6160 message_queue_data() = off_heap | on_heap
6161 spawn_opt_option() =
6162 link |
6163 monitor |
6164 {priority, Level :: priority_level()} |
6165 {fullsweep_after, Number :: integer() >= 0} |
6166 {min_heap_size, Size :: integer() >= 0} |
6167 {min_bin_vheap_size, VSize :: integer() >= 0} |
6168 {max_heap_size, Size :: max_heap_size()} |
6169 {message_queue_data, MQD :: message_queue_data()}
6170 Returns the process identifier (pid) of a new process started by
6172 the application of Fun to the empty list [] on Node. If Node
6173 does not exist, a useless pid is returned. Otherwise works like
6174 spawn_opt/4.
6175 spawn_opt(Module, Function, Args, Options) ->
6177 pid() | {pid(), reference()}
6178 Types:
6180 Module = module()
6182 Function = atom()
6183 Args = [term()]
6184 Options = [spawn_opt_option()]
6185 priority_level() = low | normal | high | max
6186 max_heap_size() =
6187 integer() >= 0 |
6188 #{size => integer() >= 0,
6189 kill => boolean(),
6190 error_logger => boolean()}
6191 message_queue_data() = off_heap | on_heap
6192 spawn_opt_option() =
6193 link |
6194 monitor |
6195 {priority, Level :: priority_level()} |
6196 {fullsweep_after, Number :: integer() >= 0} |
6197 {min_heap_size, Size :: integer() >= 0} |
6198 {min_bin_vheap_size, VSize :: integer() >= 0} |
6199 {max_heap_size, Size :: max_heap_size()} |
6200 {message_queue_data, MQD :: message_queue_data()}
6201 Works as spawn/3, except that an extra option list is specified
6203 when creating the process.
6204 If option monitor is specified, the newly created process is
6206 monitored, and both the pid and reference for the monitor are
6207 returned.
6208 Options:
6210 link:
6212 Sets a link to the parent process (like spawn_link/3 does).
6213 monitor:
6215 Monitors the new process (like monitor/2 does).
6216 {priority, Level}:
6218 Sets the priority of the new process. Equivalent to execut‐
6219 ing process_flag(priority, Level) in the start function of
6220 the new process, except that the priority is set before the
6221 process is selected for execution for the first time. For
6222 more information on priorities, see process_flag(priority,
6223 Level).
6224 {fullsweep_after, Number}:
6226 Useful only for performance tuning. Do not use this option
6227 unless you know that there is problem with execution times
6228 or memory consumption, and ensure that the option improves
6229 matters.
6230 The Erlang runtime system uses a generational garbage col‐
6232 lection scheme, using an "old heap" for data that has sur‐
6233 vived at least one garbage collection. When there is no more
6234 room on the old heap, a fullsweep garbage collection is
6235 done.
6236 Option fullsweep_after makes it possible to specify the max‐
6238 imum number of generational collections before forcing a
6239 fullsweep, even if there is room on the old heap. Setting
6240 the number to zero disables the general collection algo‐
6241 rithm, that is, all live data is copied at every garbage
6242 collection.
6243 A few cases when it can be useful to change fullsweep_after:
6245 * If binaries that are no longer used are to be thrown away
6247 as soon as possible. (Set Number to zero.)
6248 * A process that mostly have short-lived data is fullsweeped
6250 seldom or never, that is, the old heap contains mostly
6251 garbage. To ensure a fullsweep occasionally, set Number to
6252 a suitable value, such as 10 or 20.
6253 * In embedded systems with a limited amount of RAM and no
6255 virtual memory, you might want to preserve memory by set‐
6256 ting Number to zero. (The value can be set globally, see
6257 erlang:system_flag/2.)
6258 {min_heap_size, Size}:
6260 Useful only for performance tuning. Do not use this option
6261 unless you know that there is problem with execution times
6262 or memory consumption, and ensure that the option improves
6263 matters.
6264 Gives a minimum heap size, in words. Setting this value
6266 higher than the system default can speed up some processes
6267 because less garbage collection is done. However, setting a
6268 too high value can waste memory and slow down the system
6269 because of worse data locality. Therefore, use this option
6270 only for fine-tuning an application and to measure the exe‐
6271 cution time with various Size values.
6272 {min_bin_vheap_size, VSize}:
6274 Useful only for performance tuning. Do not use this option
6275 unless you know that there is problem with execution times
6276 or memory consumption, and ensure that the option improves
6277 matters.
6278 Gives a minimum binary virtual heap size, in words. Setting
6280 this value higher than the system default can speed up some
6281 processes because less garbage collection is done. However,
6282 setting a too high value can waste memory. Therefore, use
6283 this option only for fine-tuning an application and to mea‐
6284 sure the execution time with various VSize values.
6285 {max_heap_size, Size}:
6287 Sets the max_heap_size process flag. The default
6288 max_heap_size is determined by command-line argument +hmax
6289 in erl(1). For more information, see the documentation of
6290 process_flag(max_heap_size, Size).
6291 {message_queue_data, MQD}:
6293 Sets the state of the message_queue_data process flag. MQD
6294 is to be either off_heap or on_heap. The default mes‐
6295 sage_queue_data process flag is determined by command-line
6296 argument +hmqd in erl(1). For more information, see the doc‐
6297 umentation of process_flag(message_queue_data, MQD).
6298 spawn_opt(Node, Module, Function, Args, Options) ->
6300 pid() | {pid(), reference()}
6301 Types:
6303 Node = node()
6305 Module = module()
6306 Function = atom()
6307 Args = [term()]
6308 Options = [spawn_opt_option()]
6309 priority_level() = low | normal | high | max
6310 max_heap_size() =
6311 integer() >= 0 |
6312 #{size => integer() >= 0,
6313 kill => boolean(),
6314 error_logger => boolean()}
6315 message_queue_data() = off_heap | on_heap
6316 spawn_opt_option() =
6317 link |
6318 monitor |
6319 {priority, Level :: priority_level()} |
6320 {fullsweep_after, Number :: integer() >= 0} |
6321 {min_heap_size, Size :: integer() >= 0} |
6322 {min_bin_vheap_size, VSize :: integer() >= 0} |
6323 {max_heap_size, Size :: max_heap_size()} |
6324 {message_queue_data, MQD :: message_queue_data()}
6325 Returns the process identifier (pid) of a new process started by
6327 the application of Module:Function to Args on Node. If Node does
6328 not exist, a useless pid is returned. Otherwise works like
6329 spawn_opt/4.
6330 Note:
6332 Option monitor is not supported by spawn_opt/5.
6333 split_binary(Bin, Pos) -> {binary(), binary()}
6336 Types:
6338 Bin = binary()
6340 Pos = integer() >= 0
6341 0..byte_size(Bin)
6342 Returns a tuple containing the binaries that are the result of
6344 splitting Bin into two parts at position Pos. This is not a
6345 destructive operation. After the operation, there are three
6346 binaries altogether. Example:
6347 > B = list_to_binary("0123456789").
6349 <<"0123456789">>
6350 > byte_size(B).
6351 10
6352 > {B1, B2} = split_binary(B,3).
6353 {<<"012">>,<<"3456789">>}
6354 > byte_size(B1).
6355 3
6356 > byte_size(B2).
6357 7
6358 erlang:start_timer(Time, Dest, Msg) -> TimerRef
6360 Types:
6362 Time = integer() >= 0
6364 Dest = pid() | atom()
6365 Msg = term()
6366 TimerRef = reference()
6367 Starts a timer. The same as calling erlang:start_timer(Time,
6369 Dest, Msg, []).
6370 erlang:start_timer(Time, Dest, Msg, Options) -> TimerRef
6372 Types:
6374 Time = integer()
6376 Dest = pid() | atom()
6377 Msg = term()
6378 Options = [Option]
6379 Abs = boolean()
6380 Option = {abs, Abs}
6381 TimerRef = reference()
6382 Starts a timer. When the timer expires, the message {timeout,
6384 TimerRef, Msg} is sent to the process identified by Dest.
6385 Options:
6387 {abs, false}:
6389 This is the default. It means the Time value is interpreted
6390 as a time in milliseconds relative current Erlang monotonic
6391 time.
6392 {abs, true}:
6394 Absolute Time value. The Time value is interpreted as an
6395 absolute Erlang monotonic time in milliseconds.
6396 More Options can be added in the future.
6398 The absolute point in time, the timer is set to expire on, must
6400 be in the interval [erlang:system_info(start_time), erlang:sys‐
6401 tem_info(end_time)]. If a relative time is specified, the Time
6402 value is not allowed to be negative.
6403 If Dest is a pid(), it must be a pid() of a process created on
6405 the current runtime system instance. This process has either
6406 terminated or not. If Dest is an atom(), it is interpreted as
6407 the name of a locally registered process. The process referred
6408 to by the name is looked up at the time of timer expiration. No
6409 error is returned if the name does not refer to a process.
6410 If Dest is a pid(), the timer is automatically canceled if the
6412 process referred to by the pid() is not alive, or if the process
6413 exits. This feature was introduced in ERTS 5.4.11. Notice that
6414 timers are not automatically canceled when Dest is an atom().
6415 See also erlang:send_after/4, erlang:cancel_timer/2, and
6417 erlang:read_timer/2.
6418 Failure: badarg if the arguments do not satisfy the requirements
6420 specified here.
6421 statistics(Item :: active_tasks) -> [ActiveTasks]
6423 Types:
6425 ActiveTasks = integer() >= 0
6427 Returns the same as statistics(active_tasks_all) with the excep‐
6429 tion that no information about the dirty IO run queue and its
6430 associated schedulers is part of the result. That is, only tasks
6431 that are expected to be CPU bound are part of the result.
6432 statistics(Item :: active_tasks_all) -> [ActiveTasks]
6434 Types:
6436 ActiveTasks = integer() >= 0
6438 Returns a list where each element represents the amount of
6440 active processes and ports on each run queue and its associated
6441 schedulers. That is, the number of processes and ports that are
6442 ready to run, or are currently running. Values for normal run
6443 queues and their associated schedulers are located first in the
6444 resulting list. The first element corresponds to scheduler num‐
6445 ber 1 and so on. If support for dirty schedulers exist, an ele‐
6446 ment with the value for the dirty CPU run queue and its associ‐
6447 ated dirty CPU schedulers follow and then as last element the
6448 value for the the dirty IO run queue and its associated dirty IO
6449 schedulers follow. The information is not gathered atomically.
6450 That is, the result is not necessarily a consistent snapshot of
6451 the state, but instead quite efficiently gathered.
6452 Note:
6454 Each normal scheduler has one run queue that it manages. If
6455 dirty schedulers schedulers are supported, all dirty CPU sched‐
6456 ulers share one run queue, and all dirty IO schedulers share one
6457 run queue. That is, we have multiple normal run queues, one
6458 dirty CPU run queue and one dirty IO run queue. Work can not
6459 migrate between the different types of run queues. Only work in
6460 normal run queues can migrate to other normal run queues. This
6461 has to be taken into account when evaluating the result.
6462 See also statistics(total_active_tasks), statis‐
6465 tics(run_queue_lengths), statistics(run_queue_lengths_all), sta‐
6466 tistics(total_run_queue_lengths), and statis‐
6467 tics(total_run_queue_lengths_all).
6468 statistics(Item :: context_switches) -> {ContextSwitches, 0}
6470 Types:
6472 ContextSwitches = integer() >= 0
6474 Returns the total number of context switches since the system
6476 started.
6477 statistics(Item :: exact_reductions) ->
6479 {Total_Exact_Reductions,
6480 Exact_Reductions_Since_Last_Call}
6481 Types:
6483 Total_Exact_Reductions = Exact_Reductions_Since_Last_Call =
6485 integer() >= 0
6486 Returns the number of exact reductions.
6488 Note:
6490 statistics(exact_reductions) is a more expensive operation than
6491 statistics(reductions).
6492 statistics(Item :: garbage_collection) ->
6495 {Number_of_GCs, Words_Reclaimed, 0}
6496 Types:
6498 Number_of_GCs = Words_Reclaimed = integer() >= 0
6500 Returns information about garbage collection, for example:
6502 > statistics(garbage_collection).
6504 {85,23961,0}
6505 This information can be invalid for some implementations.
6507 statistics(Item :: io) -> {{input, Input}, {output, Output}}
6509 Types:
6511 Input = Output = integer() >= 0
6513 Returns Input, which is the total number of bytes received
6515 through ports, and Output, which is the total number of bytes
6516 output to ports.
6517 statistics(Item :: microstate_accounting) ->
6519 [MSAcc_Thread] | undefined
6520 Types:
6522 MSAcc_Thread =
6524 #{type := MSAcc_Thread_Type,
6525 id := MSAcc_Thread_Id,
6526 counters := MSAcc_Counters}
6527 MSAcc_Thread_Type =
6528 async |
6529 aux |
6530 dirty_io_scheduler |
6531 dirty_cpu_scheduler |
6532 poll |
6533 scheduler
6534 MSAcc_Thread_Id = integer() >= 0
6535 MSAcc_Counters = #{MSAcc_Thread_State => integer() >= 0}
6536 MSAcc_Thread_State =
6537 alloc |
6538 aux |
6539 bif |
6540 busy_wait |
6541 check_io |
6542 emulator |
6543 ets |
6544 gc |
6545 gc_fullsweep |
6546 nif |
6547 other |
6548 port |
6549 send |
6550 sleep |
6551 timers
6552 Microstate accounting can be used to measure how much time the
6554 Erlang runtime system spends doing various tasks. It is designed
6555 to be as lightweight as possible, but some overhead exists when
6556 this is enabled. Microstate accounting is meant to be a profil‐
6557 ing tool to help finding performance bottlenecks. To
6558 start/stop/reset microstate accounting, use system flag
6559 microstate_accounting.
6560 statistics(microstate_accounting) returns a list of maps repre‐
6562 senting some of the OS threads within ERTS. Each map contains
6563 type and id fields that can be used to identify what thread it
6564 is, and also a counters field that contains data about how much
6565 time has been spent in the various states.
6566 Example:
6568 > erlang:statistics(microstate_accounting).
6570 [#{counters => #{aux => 1899182914,
6571 check_io => 2605863602,
6572 emulator => 45731880463,
6573 gc => 1512206910,
6574 other => 5421338456,
6575 port => 221631,
6576 sleep => 5150294100},
6577 id => 1,
6578 type => scheduler}|...]
6579 The time unit is the same as returned by os:perf_counter/0. So,
6581 to convert it to milliseconds, you can do something like this:
6582 lists:map(
6584 fun(#{ counters := Cnt } = M) ->
6585 MsCnt = maps:map(fun(_K, PerfCount) ->
6586 erlang:convert_time_unit(PerfCount, perf_counter, 1000)
6587 end, Cnt),
6588 M#{ counters := MsCnt }
6589 end, erlang:statistics(microstate_accounting)).
6590 Notice that these values are not guaranteed to be the exact time
6592 spent in each state. This is because of various optimisation
6593 done to keep the overhead as small as possible.
6594 MSAcc_Thread_Types:
6596 scheduler:
6598 The main execution threads that do most of the work. See erl
6599 +S for more details.
6600 dirty_cpu_scheduler:
6602 The threads for long running cpu intensive work. See erl
6603 +SDcpu for more details.
6604 dirty_io_scheduler:
6606 The threads for long running I/O work. See erl +SDio for
6607 more details.
6608 async:
6610 Async threads are used by various linked-in drivers (mainly
6611 the file drivers) do offload non-CPU intensive work. See erl
6612 +A for more details.
6613 aux:
6615 Takes care of any work that is not specifically assigned to
6616 a scheduler.
6617 poll:
6619 Does the IO polling for the emulator. See erl +IOt for more
6620 details.
6621 The following MSAcc_Thread_States are available. All states are
6623 exclusive, meaning that a thread cannot be in two states at
6624 once. So, if you add the numbers of all counters in a thread,
6625 you get the total runtime for that thread.
6626 aux:
6628 Time spent handling auxiliary jobs.
6629 check_io:
6631 Time spent checking for new I/O events.
6632 emulator:
6634 Time spent executing Erlang processes.
6635 gc:
6637 Time spent doing garbage collection. When extra states are
6638 enabled this is the time spent doing non-fullsweep garbage
6639 collections.
6640 other:
6642 Time spent doing unaccounted things.
6643 port:
6645 Time spent executing ports.
6646 sleep:
6648 Time spent sleeping.
6649 More fine-grained MSAcc_Thread_States can be added through con‐
6651 figure (such as ./configure --with-microstate-accounting=extra).
6652 Enabling these states causes performance degradation when
6653 microstate accounting is turned off and increases the overhead
6654 when it is turned on.
6655 alloc:
6657 Time spent managing memory. Without extra states this time
6658 is spread out over all other states.
6659 bif:
6661 Time spent in BIFs. Without extra states this time is part
6662 of the emulator state.
6663 busy_wait:
6665 Time spent busy waiting. This is also the state where a
6666 scheduler no longer reports that it is active when using
6667 statistics(scheduler_wall_time). So, if you add all other
6668 states but this and sleep, and then divide that by all time
6669 in the thread, you should get something very similar to the
6670 scheduler_wall_time fraction. Without extra states this time
6671 is part of the other state.
6672 ets:
6674 Time spent executing ETS BIFs. Without extra states this
6675 time is part of the emulator state.
6676 gc_full:
6678 Time spent doing fullsweep garbage collection. Without extra
6679 states this time is part of the gc state.
6680 nif:
6682 Time spent in NIFs. Without extra states this time is part
6683 of the emulator state.
6684 send:
6686 Time spent sending messages (processes only). Without extra
6687 states this time is part of the emulator state.
6688 timers:
6690 Time spent managing timers. Without extra states this time
6691 is part of the other state.
6692 The utility module msacc(3) can be used to more easily analyse
6694 these statistics.
6695 Returns undefined if system flag microstate_accounting is turned
6697 off.
6698 The list of thread information is unsorted and can appear in
6700 different order between calls.
6701 Note:
6703 The threads and states are subject to change without any prior
6704 notice.
6705 statistics(Item :: reductions) ->
6708 {Total_Reductions, Reductions_Since_Last_Call}
6709 Types:
6711 Total_Reductions = Reductions_Since_Last_Call = integer() >=
6713 0
6714 Returns information about reductions, for example:
6716 > statistics(reductions).
6718 {2046,11}
6719 Note:
6721 As from ERTS 5.5 (Erlang/OTP R11B), this value does not include
6722 reductions performed in current time slices of currently sched‐
6723 uled processes. If an exact value is wanted, use statis‐
6724 tics(exact_reductions).
6725 statistics(Item :: run_queue) -> integer() >= 0
6728 Returns the total length of all normal run-queues. That is, the
6730 number of processes and ports that are ready to run on all
6731 available normal run-queues. Dirty run queues are not part of
6732 the result. The information is gathered atomically. That is, the
6733 result is a consistent snapshot of the state, but this operation
6734 is much more expensive compared to statis‐
6735 tics(total_run_queue_lengths), especially when a large amount of
6736 schedulers is used.
6737 statistics(Item :: run_queue_lengths) -> [RunQueueLength]
6739 Types:
6741 RunQueueLength = integer() >= 0
6743 Returns the same as statistics(run_queue_lengths_all) with the
6745 exception that no information about the dirty IO run queue is
6746 part of the result. That is, only run queues with work that is
6747 expected to be CPU bound is part of the result.
6748 statistics(Item :: run_queue_lengths_all) -> [RunQueueLength]
6750 Types:
6752 RunQueueLength = integer() >= 0
6754 Returns a list where each element represents the amount of pro‐
6756 cesses and ports ready to run for each run queue. Values for
6757 normal run queues are located first in the resulting list. The
6758 first element corresponds to the normal run queue of scheduler
6759 number 1 and so on. If support for dirty schedulers exist, val‐
6760 ues for the dirty CPU run queue and the dirty IO run queue fol‐
6761 low (in that order) at the end. The information is not gathered
6762 atomically. That is, the result is not necessarily a consistent
6763 snapshot of the state, but instead quite efficiently gathered.
6764 Note:
6766 Each normal scheduler has one run queue that it manages. If
6767 dirty schedulers schedulers are supported, all dirty CPU sched‐
6768 ulers share one run queue, and all dirty IO schedulers share one
6769 run queue. That is, we have multiple normal run queues, one
6770 dirty CPU run queue and one dirty IO run queue. Work can not
6771 migrate between the different types of run queues. Only work in
6772 normal run queues can migrate to other normal run queues. This
6773 has to be taken into account when evaluating the result.
6774 See also statistics(run_queue_lengths), statis‐
6777 tics(total_run_queue_lengths_all), statis‐
6778 tics(total_run_queue_lengths), statistics(active_tasks), statis‐
6779 tics(active_tasks_all), and statistics(total_active_tasks), sta‐
6780 tistics(total_active_tasks_all).
6781 statistics(Item :: runtime) ->
6783 {Total_Run_Time, Time_Since_Last_Call}
6784 Types:
6786 Total_Run_Time = Time_Since_Last_Call = integer() >= 0
6788 Returns information about runtime, in milliseconds.
6790 This is the sum of the runtime for all threads in the Erlang
6792 runtime system and can therefore be greater than the wall clock
6793 time.
6794 Warning:
6796 This value might wrap due to limitations in the underlying func‐
6797 tionality provided by the operating system that is used.
6798 Example:
6801 > statistics(runtime).
6803 {1690,1620}
6804 statistics(Item :: scheduler_wall_time) ->
6806 [{SchedulerId, ActiveTime, TotalTime}] | undefined
6807 Types:
6809 SchedulerId = integer() >= 1
6811 ActiveTime = TotalTime = integer() >= 0
6812 Returns a list of tuples with {SchedulerId, ActiveTime, Total‐
6814 Time}, where SchedulerId is an integer ID of the scheduler,
6815 ActiveTime is the duration the scheduler has been busy, and
6816 TotalTime is the total time duration since scheduler_wall_time
6817 activation for the specific scheduler. Note that activation time
6818 can differ significantly between schedulers. Currently dirty
6819 schedulers are activated at system start while normal schedulers
6820 are activated some time after the scheduler_wall_time function‐
6821 ality is enabled. The time unit is undefined and can be subject
6822 to change between releases, OSs, and system restarts. sched‐
6823 uler_wall_time is only to be used to calculate relative values
6824 for scheduler utilization. ActiveTime can never exceed Total‐
6825 Time.
6826 The definition of a busy scheduler is when it is not idle and is
6828 not scheduling (selecting) a process or port, that is:
6829 * Executing process code
6831 * Executing linked-in driver or NIF code
6833 * Executing BIFs, or any other runtime handling
6835 * Garbage collecting
6837 * Handling any other memory management
6839 Notice that a scheduler can also be busy even if the OS has
6841 scheduled out the scheduler thread.
6842 Returns undefined if system flag scheduler_wall_time is turned
6844 off.
6845 The list of scheduler information is unsorted and can appear in
6847 different order between calls.
6848 As of ERTS version 9.0, also dirty CPU schedulers will be
6850 included in the result. That is, all scheduler threads that are
6851 expected to handle CPU bound work. If you also want information
6852 about dirty I/O schedulers, use statistics(sched‐
6853 uler_wall_time_all) instead.
6854 Normal schedulers will have scheduler identifiers in the range 1
6856 =< SchedulerId =< erlang:system_info(schedulers). Dirty CPU
6857 schedulers will have scheduler identifiers in the range
6858 erlang:system_info(schedulers) < SchedulerId =< erlang:sys‐
6859 tem_info(schedulers) + erlang:system_info(dirty_cpu_schedulers).
6860 Note:
6862 The different types of schedulers handle specific types of jobs.
6863 Every job is assigned to a specific scheduler type. Jobs can
6864 migrate between different schedulers of the same type, but never
6865 between schedulers of different types. This fact has to be taken
6866 under consideration when evaluating the result returned.
6867 Using scheduler_wall_time to calculate scheduler utilization:
6870 > erlang:system_flag(scheduler_wall_time, true).
6872 false
6873 > Ts0 = lists:sort(erlang:statistics(scheduler_wall_time)), ok.
6874 ok
6875 Some time later the user takes another snapshot and calculates
6877 scheduler utilization per scheduler, for example:
6878 > Ts1 = lists:sort(erlang:statistics(scheduler_wall_time)), ok.
6880 ok
6881 > lists:map(fun({{I, A0, T0}, {I, A1, T1}}) -> {I, (A1 - A0)/(T1 - T0)} end, lists:zip(Ts0,Ts1)).
6882 [{1,0.9743474730177548},
6883 {2,0.9744843782751444},
6884 {3,0.9995902361669045},
6885 {4,0.9738012596572161},
6886 {5,0.9717956667018103},
6887 {6,0.9739235846420741},
6888 {7,0.973237033077876},
6889 {8,0.9741297293248656}]
6890 Using the same snapshots to calculate a total scheduler utiliza‐
6892 tion:
6893 > {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.
6895 0.9769136803764825
6896 Total scheduler utilization will equal 1.0 when all schedulers
6898 have been active all the time between the two measurements.
6899 Another (probably more) useful value is to calculate total
6901 scheduler utilization weighted against maximum amount of avail‐
6902 able CPU time:
6903 > WeightedSchedulerUtilization = (TotalSchedulerUtilization * (erlang:system_info(schedulers) + erlang:system_info(dirty_cpu_schedulers))) / erlang:system_info(logical_processors_available).
6905 0.9769136803764825
6906 This weighted scheduler utilization will reach 1.0 when sched‐
6908 ulers are active the same amount of time as maximum available
6909 CPU time. If more schedulers exist than available logical pro‐
6910 cessors, this value may be greater than 1.0.
6911 As of ERTS version 9.0, the Erlang runtime system will as
6913 default have more schedulers than logical processors. This due
6914 to the dirty schedulers.
6915 Note:
6917 scheduler_wall_time is by default disabled. To enable it, use
6918 erlang:system_flag(scheduler_wall_time, true).
6919 statistics(Item :: scheduler_wall_time_all) ->
6922 [{SchedulerId, ActiveTime, TotalTime}] | undefined
6923 Types:
6925 SchedulerId = integer() >= 1
6927 ActiveTime = TotalTime = integer() >= 0
6928 The same as statistics(scheduler_wall_time), except that it also
6930 include information about all dirty I/O schedulers.
6931 Dirty IO schedulers will have scheduler identifiers in the range
6933 erlang:system_info(schedulers) + erlang:sys‐
6934 tem_info(dirty_cpu_schedulers) < SchedulerId =< erlang:sys‐
6935 tem_info(schedulers) + erlang:system_info(dirty_cpu_schedulers)
6936 + erlang:system_info(dirty_io_schedulers).
6937 Note:
6939 Note that work executing on dirty I/O schedulers are expected to
6940 mainly wait for I/O. That is, when you get high scheduler uti‐
6941 lization on dirty I/O schedulers, CPU utilization is not
6942 expected to be high due to this work.
6943 statistics(Item :: total_active_tasks) -> ActiveTasks
6946 Types:
6948 ActiveTasks = integer() >= 0
6950 The same as calling lists:sum(statistics(active_tasks)), but
6952 more efficient.
6953 statistics(Item :: total_active_tasks_all) -> ActiveTasks
6955 Types:
6957 ActiveTasks = integer() >= 0
6959 The same as calling lists:sum(statistics(active_tasks_all)), but
6961 more efficient.
6962 statistics(Item :: total_run_queue_lengths) ->
6964 TotalRunQueueLengths
6965 Types:
6967 TotalRunQueueLengths = integer() >= 0
6969 The same as calling lists:sum(statistics(run_queue_lengths)),
6971 but more efficient.
6972 statistics(Item :: total_run_queue_lengths_all) ->
6974 TotalRunQueueLengths
6975 Types:
6977 TotalRunQueueLengths = integer() >= 0
6979 The same as calling lists:sum(statis‐
6981 tics(run_queue_lengths_all)), but more efficient.
6982 statistics(Item :: wall_clock) ->
6984 {Total_Wallclock_Time,
6985 Wallclock_Time_Since_Last_Call}
6986 Types:
6988 Total_Wallclock_Time = Wallclock_Time_Since_Last_Call = inte‐
6990 ger() >= 0
6991 Returns information about wall clock. wall_clock can be used in
6993 the same manner as runtime, except that real time is measured as
6994 opposed to runtime or CPU time.
6995 erlang:suspend_process(Suspendee) -> true
6997 Types:
6999 Suspendee = pid()
7001 Suspends the process identified by Suspendee. The same as call‐
7003 ing erlang:suspend_process(Suspendee, []).
7004 Warning:
7006 This BIF is intended for debugging only.
7007 erlang:suspend_process(Suspendee, OptList) -> boolean()
7010 Types:
7012 Suspendee = pid()
7014 OptList = [Opt]
7015 Opt = unless_suspending | asynchronous | {asynchronous,
7016 term()}
7017 Increases the suspend count on the process identified by Sus‐
7019 pendee and puts it in the suspended state if it is not already
7020 in that state. A suspended process is not scheduled for execu‐
7021 tion until the process has been resumed.
7022 A process can be suspended by multiple processes and can be sus‐
7024 pended multiple times by a single process. A suspended process
7025 does not leave the suspended state until its suspend count
7026 reaches zero. The suspend count of Suspendee is decreased when
7027 erlang:resume_process(Suspendee) is called by the same process
7028 that called erlang:suspend_process(Suspendee). All increased
7029 suspend counts on other processes acquired by a process are
7030 automatically decreased when the process terminates.
7031 Options (Opts):
7033 asynchronous:
7035 A suspend request is sent to the process identified by Sus‐
7036 pendee. Suspendee eventually suspends unless it is resumed
7037 before it could suspend. The caller of erlang:sus‐
7038 pend_process/2 returns immediately, regardless of whether
7039 Suspendee has suspended yet or not. The point in time when
7040 Suspendee suspends cannot be deduced from other events in
7041 the system. It is only guaranteed that Suspendee eventually
7042 suspends (unless it is resumed). If no asynchronous options
7043 has been passed, the caller of erlang:suspend_process/2 is
7044 blocked until Suspendee has suspended.
7045 {asynchronous, ReplyTag}:
7047 A suspend request is sent to the process identified by Sus‐
7048 pendee. When the suspend request has been processed, a reply
7049 message is sent to the caller of this function. The reply is
7050 on the form {ReplyTag, State} where State is either:
7051 exited:
7053 Suspendee has exited.
7054 suspended:
7056 Suspendee is now suspended.
7057 not_suspended:
7059 Suspendee is not suspended. This can only happen when the
7060 process that issued this request, have called
7061 resume_process(Suspendee) before getting the reply.
7062 Appart from the reply message, the {asynchronous, ReplyTag}
7064 option behaves exactly the same as the asynchronous option
7065 without reply tag.
7066 unless_suspending:
7068 The process identified by Suspendee is suspended unless the
7069 calling process already is suspending Suspendee. If
7070 unless_suspending is combined with option asynchronous, a
7071 suspend request is sent unless the calling process already
7072 is suspending Suspendee or if a suspend request already has
7073 been sent and is in transit. If the calling process already
7074 is suspending Suspendee, or if combined with option asyn‐
7075 chronous and a send request already is in transit, false is
7076 returned and the suspend count on Suspendee remains
7077 unchanged.
7078 If the suspend count on the process identified by Suspendee is
7080 increased, true is returned, otherwise false.
7081 Warning:
7083 This BIF is intended for debugging only.
7084 Warning:
7087 You can easily create deadlocks if processes suspends each other
7088 (directly or in circles). In ERTS versions prior to ERTS version
7089 10.0, the runtime system prevented such deadlocks, but this pre‐
7090 vention has now been removed due to performance reasons.
7091 Failures:
7094 badarg:
7096 If Suspendee is not a process identifier.
7097 badarg:
7099 If the process identified by Suspendee is the same process
7100 as the process calling erlang:suspend_process/2.
7101 badarg:
7103 If the process identified by Suspendee is not alive.
7104 badarg:
7106 If the process identified by Suspendee resides on another
7107 node.
7108 badarg:
7110 If OptList is not a proper list of valid Opts.
7111 system_limit:
7113 If the process identified by Suspendee has been suspended
7114 more times by the calling process than can be represented by
7115 the currently used internal data structures. The system
7116 limit is > 2,000,000,000 suspends and will never be lower.
7117 erlang:system_flag(Flag :: backtrace_depth, Depth) -> OldDepth
7119 Types:
7121 Depth = OldDepth = integer() >= 0
7123 Sets the maximum depth of call stack back-traces in the exit
7125 reason element of 'EXIT' tuples. The flag also limits the stack‐
7126 trace depth returned by process_info item current_stacktrace.
7127 Returns the old value of the flag.
7129 erlang:system_flag(Flag :: cpu_topology, CpuTopology) ->
7131 OldCpuTopology
7132 Types:
7134 CpuTopology = OldCpuTopology = cpu_topology()
7136 cpu_topology() = [LevelEntry :: level_entry()] | undefined
7137 level_entry() =
7138 {LevelTag :: level_tag(), SubLevel :: sub_level()} |
7139 {LevelTag :: level_tag(),
7140 InfoList :: info_list(),
7141 SubLevel :: sub_level()}
7142 level_tag() = core | node | processor | thread
7143 sub_level() =
7144 [LevelEntry :: level_entry()] |
7145 (LogicalCpuId :: {logical, integer() >= 0})
7146 info_list() = []
7147 Warning:
7149 This argument is deprecated. Instead of using this argument, use
7150 command-line argument +sct in erl(1).
7151 When this argument is removed, a final CPU topology to use is
7153 determined at emulator boot time.
7154 Sets the user-defined CpuTopology. The user-defined CPU topology
7157 overrides any automatically detected CPU topology. By passing
7158 undefined as CpuTopology, the system reverts to the CPU topology
7159 automatically detected. The returned value equals the value
7160 returned from erlang:system_info(cpu_topology) before the change
7161 was made.
7162 Returns the old value of the flag.
7164 The CPU topology is used when binding schedulers to logical pro‐
7166 cessors. If schedulers are already bound when the CPU topology
7167 is changed, the schedulers are sent a request to rebind accord‐
7168 ing to the new CPU topology.
7169 The user-defined CPU topology can also be set by passing com‐
7171 mand-line argument +sct to erl(1).
7172 For information on type CpuTopology and more, see erlang:sys‐
7174 tem_info(cpu_topology) as well as command-line flags +sct and
7175 +sbt in erl(1).
7176 erlang:system_flag(Flag :: dirty_cpu_schedulers_online,
7178 DirtyCPUSchedulersOnline) ->
7179 OldDirtyCPUSchedulersOnline
7180 Types:
7182 DirtyCPUSchedulersOnline = OldDirtyCPUSchedulersOnline =
7184 integer() >= 1
7185 Sets the number of dirty CPU schedulers online. Range is 1 <=
7187 DirtyCPUSchedulersOnline <= N, where N is the smallest of the
7188 return values of erlang:system_info(dirty_cpu_schedulers) and
7189 erlang:system_info(schedulers_online).
7190 Returns the old value of the flag.
7192 The number of dirty CPU schedulers online can change if the num‐
7194 ber of schedulers online changes. For example, if 12 schedulers
7195 and 6 dirty CPU schedulers are online, and system_flag/2 is used
7196 to set the number of schedulers online to 6, then the number of
7197 dirty CPU schedulers online is automatically decreased by half
7198 as well, down to 3. Similarly, the number of dirty CPU sched‐
7199 ulers online increases proportionally to increases in the number
7200 of schedulers online.
7201 For more information, see erlang:system_info(dirty_cpu_sched‐
7203 ulers) and erlang:system_info(dirty_cpu_schedulers_online).
7204 erlang:system_flag(Flag :: erts_alloc, Value :: {Alloc, F, V}) ->
7206 ok | notsup
7207 Types:
7209 Alloc = F = atom()
7211 V = integer()
7212 Sets system flags for erts_alloc(3). Alloc is the allocator to
7214 affect, for example binary_alloc. F is the flag to change and V
7215 is the new value.
7216 Only a subset of all erts_alloc flags can be changed at run
7218 time. This subset is currently only the flag sbct.
7219 Returns ok if the flag was set or notsup if not supported by
7221 erts_alloc.
7222 erlang:system_flag(Flag :: fullsweep_after, Number) -> OldNumber
7224 Types:
7226 Number = OldNumber = integer() >= 0
7228 Sets system flag fullsweep_after. Number is a non-negative inte‐
7230 ger indicating how many times generational garbage collections
7231 can be done without forcing a fullsweep collection. The value
7232 applies to new processes, while processes already running are
7233 not affected.
7234 Returns the old value of the flag.
7236 In low-memory systems (especially without virtual memory), set‐
7238 ting the value to 0 can help to conserve memory.
7239 This value can also be set through (OS) environment variable
7241 ERL_FULLSWEEP_AFTER.
7242 erlang:system_flag(Flag :: microstate_accounting, Action) ->
7244 OldState
7245 Types:
7247 Action = true | false | reset
7249 OldState = true | false
7250 Turns on/off microstate accounting measurements. When passing
7252 reset, all counters are reset to 0.
7253 For more information see statistics(microstate_accounting).
7255 erlang:system_flag(Flag :: min_heap_size, MinHeapSize) ->
7257 OldMinHeapSize
7258 Types:
7260 MinHeapSize = OldMinHeapSize = integer() >= 0
7262 Sets the default minimum heap size for processes. The size is
7264 specified in words. The new min_heap_size effects only processes
7265 spawned after the change of min_heap_size has been made.
7266 min_heap_size can be set for individual processes by using
7267 spawn_opt/4 or process_flag/2.
7268 Returns the old value of the flag.
7270 erlang:system_flag(Flag :: min_bin_vheap_size, MinBinVHeapSize) ->
7272 OldMinBinVHeapSize
7273 Types:
7275 MinBinVHeapSize = OldMinBinVHeapSize = integer() >= 0
7277 Sets the default minimum binary virtual heap size for processes.
7279 The size is specified in words. The new min_bin_vhheap_size
7280 effects only processes spawned after the change of
7281 min_bin_vheap_size has been made. min_bin_vheap_size can be set
7282 for individual processes by using spawn_opt/2,3,4 or
7283 process_flag/2.
7284 Returns the old value of the flag.
7286 erlang:system_flag(Flag :: max_heap_size, MaxHeapSize) ->
7288 OldMaxHeapSize
7289 Types:
7291 MaxHeapSize = OldMaxHeapSize = max_heap_size()
7293 max_heap_size() =
7294 integer() >= 0 |
7295 #{size => integer() >= 0,
7296 kill => boolean(),
7297 error_logger => boolean()}
7298 Sets the default maximum heap size settings for processes. The
7300 size is specified in words. The new max_heap_size effects only
7301 processes spawned efter the change has been made. max_heap_size
7302 can be set for individual processes using spawn_opt/2,3,4 or
7303 process_flag/2.
7304 Returns the old value of the flag.
7306 erlang:system_flag(Flag :: multi_scheduling, BlockState) ->
7308 OldBlockState
7309 Types:
7311 BlockState = block | unblock | block_normal | unblock_normal
7313 OldBlockState = blocked | disabled | enabled
7314 If multi-scheduling is enabled, more than one scheduler thread
7316 is used by the emulator. Multi-scheduling can be blocked in two
7317 different ways. Either all schedulers but one is blocked, or all
7318 normal schedulers but one is blocked. When only normal sched‐
7319 ulers are blocked, dirty schedulers are free to continue to
7320 schedule processes.
7321 If BlockState =:= block, multi-scheduling is blocked. That is,
7323 one and only one scheduler thread will execute. If BlockState
7324 =:= unblock and no one else blocks multi-scheduling, and this
7325 process has blocked only once, multi-scheduling is unblocked.
7326 If BlockState =:= block_normal, normal multi-scheduling is
7328 blocked. That is, only one normal scheduler thread will execute,
7329 but multiple dirty schedulers can execute. If BlockState =:=
7330 unblock_normal and no one else blocks normal multi-scheduling,
7331 and this process has blocked only once, normal multi-scheduling
7332 is unblocked.
7333 One process can block multi-scheduling and normal multi-schedul‐
7335 ing multiple times. If a process has blocked multiple times, it
7336 must unblock exactly as many times as it has blocked before it
7337 has released its multi-scheduling block. If a process that has
7338 blocked multi-scheduling or normal multi-scheduling exits, it
7339 automatically releases its blocking of multi-scheduling and nor‐
7340 mal multi-scheduling.
7341 The return values are disabled, blocked, blocked_normal, or
7343 enabled. The returned value describes the state just after the
7344 call to erlang:system_flag(multi_scheduling, BlockState) has
7345 been made. For information about the return values, see
7346 erlang:system_info(multi_scheduling).
7347 Note:
7349 Blocking of multi-scheduling and normal multi-scheduling is nor‐
7350 mally not needed. If you feel that you need to use these fea‐
7351 tures, consider it a few more times again. Blocking multi-sched‐
7352 uling is only to be used as a last resort, as it is most likely
7353 a very inefficient way to solve the problem.
7354 See also erlang:system_info(multi_scheduling), erlang:sys‐
7357 tem_info(normal_multi_scheduling_blockers), erlang:sys‐
7358 tem_info(multi_scheduling_blockers), and erlang:sys‐
7359 tem_info(schedulers).
7360 erlang:system_flag(Flag :: scheduler_bind_type, How) ->
7362 OldBindType
7363 Types:
7365 How = scheduler_bind_type() | default_bind
7367 OldBindType = scheduler_bind_type()
7368 scheduler_bind_type() =
7369 no_node_processor_spread |
7370 no_node_thread_spread |
7371 no_spread |
7372 processor_spread |
7373 spread |
7374 thread_spread |
7375 thread_no_node_processor_spread |
7376 unbound
7377 Warning:
7379 This argument is deprecated. Instead of using this argument, use
7380 command-line argument +sbt in erl(1). When this argument is
7381 removed, a final scheduler bind type to use is determined at
7382 emulator boot time.
7383 Controls if and how schedulers are bound to logical processors.
7386 When erlang:system_flag(scheduler_bind_type, How) is called, an
7388 asynchronous signal is sent to all schedulers online, causing
7389 them to try to bind or unbind as requested.
7390 Note:
7392 If a scheduler fails to bind, this is often silently ignored, as
7393 it is not always possible to verify valid logical processor
7394 identifiers. If an error is reported, an error event is logged.
7395 To verify that the schedulers have bound as requested, call
7396 erlang:system_info(scheduler_bindings).
7397 Schedulers can be bound on newer Linux, Solaris, FreeBSD, and
7400 Windows systems, but more systems will be supported in future
7401 releases.
7402 In order for the runtime system to be able to bind schedulers,
7404 the CPU topology must be known. If the runtime system fails to
7405 detect the CPU topology automatically, it can be defined. For
7406 more information on how to define the CPU topology, see command-
7407 line flag +sct in erl(1).
7408 The runtime system does by default not bind schedulers to logi‐
7410 cal processors.
7411 Note:
7413 If the Erlang runtime system is the only OS process binding
7414 threads to logical processors, this improves the performance of
7415 the runtime system. However, if other OS processes (for example,
7416 another Erlang runtime system) also bind threads to logical pro‐
7417 cessors, there can be a performance penalty instead. Sometimes
7418 this performance penalty can be severe. If so, it is recommended
7419 to not bind the schedulers.
7420 Schedulers can be bound in different ways. Argument How deter‐
7423 mines how schedulers are bound and can be any of the following:
7424 unbound:
7426 Same as command-line argument +sbt u in erl(1).
7427 no_spread:
7429 Same as command-line argument +sbt ns in erl(1).
7430 thread_spread:
7432 Same as command-line argument +sbt ts in erl(1).
7433 processor_spread:
7435 Same as command-line argument +sbt ps in erl(1).
7436 spread:
7438 Same as command-line argument +sbt s in erl(1).
7439 no_node_thread_spread:
7441 Same as command-line argument +sbt nnts in erl(1).
7442 no_node_processor_spread:
7444 Same as command-line argument +sbt nnps in erl(1).
7445 thread_no_node_processor_spread:
7447 Same as command-line argument +sbt tnnps in erl(1).
7448 default_bind:
7450 Same as command-line argument +sbt db in erl(1).
7451 The returned value equals How before flag scheduler_bind_type
7453 was changed.
7454 Failures:
7456 notsup:
7458 If binding of schedulers is not supported.
7459 badarg:
7461 If How is not one of the documented alternatives.
7462 badarg:
7464 If CPU topology information is unavailable.
7465 The scheduler bind type can also be set by passing command-line
7467 argument +sbt to erl(1).
7468 For more information, see erlang:system_info(sched‐
7470 uler_bind_type), erlang:system_info(scheduler_bindings), as well
7471 as command-line flags +sbt and +sct in erl(1).
7472 erlang:system_flag(Flag :: scheduler_wall_time, Boolean) ->
7474 OldBoolean
7475 Types:
7477 Boolean = OldBoolean = boolean()
7479 Turns on or off scheduler wall time measurements.
7481 For more information, see statistics(scheduler_wall_time).
7483 erlang:system_flag(Flag :: schedulers_online, SchedulersOnline) ->
7485 OldSchedulersOnline
7486 Types:
7488 SchedulersOnline = OldSchedulersOnline = integer() >= 1
7490 Sets the number of schedulers online. Range is 1 <= Scheduler‐
7492 sOnline <= erlang:system_info(schedulers).
7493 Returns the old value of the flag.
7495 If the emulator was built with support for dirty schedulers,
7497 changing the number of schedulers online can also change the
7498 number of dirty CPU schedulers online. For example, if 12 sched‐
7499 ulers and 6 dirty CPU schedulers are online, and system_flag/2
7500 is used to set the number of schedulers online to 6, then the
7501 number of dirty CPU schedulers online is automatically decreased
7502 by half as well, down to 3. Similarly, the number of dirty CPU
7503 schedulers online increases proportionally to increases in the
7504 number of schedulers online.
7505 For more information, see erlang:system_info(schedulers) and
7507 erlang:system_info(schedulers_online).
7508 erlang:system_flag(Flag :: system_logger, Logger) -> PrevLogger
7510 Types:
7512 Logger = PrevLogger = logger | undefined | pid()
7514 Sets the process that will receive the logging messages gener‐
7516 ated by ERTS. If set to undefined, all logging messages gener‐
7517 ated by ERTS will be dropped. The messages will be in the for‐
7518 mat:
7519 {log,Level,Format,ArgList,Metadata} where
7521 Level = atom(),
7523 Format = string(),
7524 ArgList = list(term()),
7525 Metadata = #{ pid => pid(),
7526 group_leader => pid(),
7527 time := logger:timestamp(),
7528 error_logger := #{ emulator := true, tag := atom() }
7529 If the system_logger process dies, this flag will be reset to
7532 logger.
7533 The default is the process named logger.
7535 Returns the old value of the flag.
7537 Note:
7539 This function is designed to be used by the KERNEL logger. Be
7540 careful if you change it to something else as log messages may
7541 be lost. If you want to intercept emulator log messages, do it
7542 by adding a specialized handler to the KERNEL logger.
7543 erlang:system_flag(Flag :: trace_control_word, TCW) -> OldTCW
7546 Types:
7548 TCW = OldTCW = integer() >= 0
7550 Sets the value of the node trace control word to TCW, which is
7552 to be an unsigned integer. For more information, see function
7553 set_tcw in section "Match Specifications in Erlang" in the
7554 User's Guide.
7555 Returns the old value of the flag.
7557 erlang:system_flag(Flag :: time_offset, Value :: finalize) ->
7559 OldState
7560 Types:
7562 OldState = preliminary | final | volatile
7564 Finalizes the time offset when single time warp mode is used. If
7566 another time warp mode is used, the time offset state is left
7567 unchanged.
7568 Returns the old state identifier, that is:
7570 * If preliminary is returned, finalization was performed and
7572 the time offset is now final.
7573 * If final is returned, the time offset was already in the
7575 final state. This either because another erlang:sys‐
7576 tem_flag(time_offset, finalize) call or because no time warp
7577 mode is used.
7578 * If volatile is returned, the time offset cannot be finalized
7580 because multi-time warp mode is used.
7581 erlang:system_info(Item ::
7583 wordsize |
7584 {wordsize, internal} |
7585 {wordsize, external}) ->
7586 4 | 8
7587 Returns information about the current system. The documentation
7589 of this function is broken into the following sections in order
7590 to make it easier to navigate.
7591 Memory Allocation:
7593 allocated_areas, allocator, alloc_util_allocators, alloca‐
7594 tor_sizes, elib_malloc
7595 CPU Topology:
7597 cpu_topology, logical_processors, update_cpu_info
7598 Process Information:
7600 fullsweep_after, garbage_collection, heap_sizes, heap_type,
7601 max_heap_size, message_queue_data, min_heap_size,
7602 min_bin_vheap_size, procs
7603 System Limits:
7605 atom_count, atom_limit, ets_count, ets_limit, port_count,
7606 port_limit, process_count, process_limit
7607 System Time:
7609 end_time, os_monotonic_time_source, os_system_time_source,
7610 start_time, time_correction, time_offset, time_warp_mode,
7611 tolerant_timeofday
7612 Scheduler Information:
7614 dirty_cpu_schedulers, dirty_cpu_schedulers_online,
7615 dirty_io_schedulers, multi_scheduling, multi_schedul‐
7616 ing_blockers, normal_multi_scheduling_blockers, sched‐
7617 uler_bind_type, scheduler_bindings, scheduler_id, sched‐
7618 ulers, smp_support, threads, thread_pool_size
7619 Distribution Information:
7621 creation, delayed_node_table_gc, dist, dist_buf_busy_limit,
7622 dist_ctrl
7623 System Information:
7625 build_type, c_compiler_used, check_io, compat_rel,
7626 debug_compiled, driver_version, dynamic_trace,
7627 dynamic_trace_probes, info, kernel_poll, loaded, machine,
7628 modified_timing_level, nif_version, otp_release, port_paral‐
7629 lelism, system_architecture, system_logger, system_version,
7630 trace_control_word, version, wordsize
7631 erlang:system_info(Item :: allocated_areas) -> [tuple()]
7633 erlang:system_info(Item :: allocator) ->
7635 {Allocator, Version, Features, Settings}
7636 erlang:system_info(Item :: {allocator, Alloc}) -> [term()]
7638 erlang:system_info(Item :: alloc_util_allocators) -> [Alloc]
7640 erlang:system_info(Item :: {allocator_sizes, Alloc}) -> [term()]
7642 erlang:system_info(Item :: elib_malloc) -> false
7644 Types:
7646 Allocator = undefined | glibc
7648 Version = [integer() >= 0]
7649 Features = [atom()]
7650 Settings =
7651 [{Subsystem :: atom(),
7652 [{Parameter :: atom(), Value :: term()}]}]
7653 Alloc = atom()
7654 Returns various information about the memory allocators of the
7656 current system (emulator) as specified by Item:
7657 allocated_areas:
7659 Returns a list of tuples with information about miscella‐
7660 neous allocated memory areas.
7661 Each tuple contains an atom describing the type of memory as
7663 first element and the amount of allocated memory in bytes as
7664 second element. When information about allocated and used
7665 memory is present, also a third element is present, contain‐
7666 ing the amount of used memory in bytes.
7667 erlang:system_info(allocated_areas) is intended for debug‐
7669 ging, and the content is highly implementation-dependent.
7670 The content of the results therefore changes when needed
7671 without prior notice.
7672 Notice that the sum of these values is not the total amount
7674 of memory allocated by the emulator. Some values are part of
7675 other values, and some memory areas are not part of the
7676 result. For information about the total amount of memory
7677 allocated by the emulator, see erlang:memory/0,1.
7678 allocator:
7680 Returns {Allocator, Version, Features, Settings, where:
7681 * Allocator corresponds to the malloc() implementation used.
7683 If Allocator equals undefined, the malloc() implementation
7684 used cannot be identified. glibc can be identified.
7685 * Version is a list of integers (but not a string) repre‐
7687 senting the version of the malloc() implementation used.
7688 * Features is a list of atoms representing the allocation
7690 features used.
7691 * Settings is a list of subsystems, their configurable
7693 parameters, and used values. Settings can differ between
7694 different combinations of platforms, allocators, and allo‐
7695 cation features. Memory sizes are given in bytes.
7696 See also "System Flags Effecting erts_alloc" in
7698 erts_alloc(3).
7699 {allocator, Alloc}:
7701 Returns information about the specified allocator. As from
7702 ERTS 5.6.1, the return value is a list of {instance, Instan‐
7703 ceNo, InstanceInfo} tuples, where InstanceInfo contains
7704 information about a specific instance of the allocator. If
7705 Alloc is not a recognized allocator, undefined is returned.
7706 If Alloc is disabled, false is returned.
7707 Notice that the information returned is highly implementa‐
7709 tion-dependent and can be changed or removed at any time
7710 without prior notice. It was initially intended as a tool
7711 when developing new allocators, but as it can be of interest
7712 for others it has been briefly documented.
7713 The recognized allocators are listed in erts_alloc(3).
7715 Information about super carriers can be obtained from ERTS
7716 8.0 with {allocator, erts_mmap} or from ERTS 5.10.4; the
7717 returned list when calling with {allocator, mseg_alloc} also
7718 includes an {erts_mmap, _} tuple as one element in the list.
7719 After reading the erts_alloc(3) documentation, the returned
7721 information more or less speaks for itself, but it can be
7722 worth explaining some things. Call counts are presented by
7723 two values, the first value is giga calls, and the second
7724 value is calls. mbcs and sbcs denote multi-block carriers,
7725 and single-block carriers, respectively. Sizes are presented
7726 in bytes. When a size is not presented, it is the amount of
7727 something. Sizes and amounts are often presented by three
7728 values:
7729 * The first is the current value.
7731 * The second is the maximum value since the last call to
7733 erlang:system_info({allocator, Alloc}).
7734 * The third is the maximum value since the emulator was
7736 started.
7737 If only one value is present, it is the current value.
7739 fix_alloc memory block types are presented by two values.
7740 The first value is the memory pool size and the second value
7741 is the used memory size.
7742 alloc_util_allocators:
7744 Returns a list of the names of all allocators using the ERTS
7745 internal alloc_util framework as atoms. For more informa‐
7746 tion, see section The alloc_util framework in erts_alloc(3).
7747 {allocator_sizes, Alloc}:
7749 Returns various size information for the specified alloca‐
7750 tor. The information returned is a subset of the information
7751 returned by erlang:system_info({allocator, Alloc}).
7752 elib_malloc:
7754 This option will be removed in a future release. The return
7755 value will always be false, as the elib_malloc allocator has
7756 been removed.
7757 erlang:system_info(Item :: cpu_topology) -> CpuTopology
7759 erlang:system_info(Item ::
7761 {cpu_topology, defined | detected | used}) ->
7762 CpuTopology
7763 erlang:system_info(Item ::
7765 logical_processors |
7766 logical_processors_available |
7767 logical_processors_online) ->
7768 unknown | integer() >= 1
7769 erlang:system_info(Item :: update_cpu_info) -> changed | unchanged
7771 Types:
7773 cpu_topology() = [LevelEntry :: level_entry()] | undefined
7775 All LevelEntrys of a list must contain the same LevelTag,
7776 except on the top level where both node and processor‐
7777 LevelTags can coexist.
7778 level_entry() =
7779 {LevelTag :: level_tag(), SubLevel :: sub_level()} |
7780 {LevelTag :: level_tag(),
7781 InfoList :: info_list(),
7782 SubLevel :: sub_level()}
7783 {LevelTag, SubLevel} == {LevelTag, [], SubLevel}
7784 level_tag() = core | node | processor | thread
7785 More LevelTags can be introduced in a future release.
7786 sub_level() =
7787 [LevelEntry :: level_entry()] |
7788 (LogicalCpuId :: {logical, integer() >= 0})
7789 info_list() = []
7790 The info_list() can be extended in a future release.
7791 Returns various information about the CPU topology of the cur‐
7793 rent system (emulator) as specified by Item:
7794 cpu_topology:
7796 Returns the CpuTopology currently used by the emulator. The
7797 CPU topology is used when binding schedulers to logical pro‐
7798 cessors. The CPU topology used is the user-defined CPU
7799 topology, if such exists, otherwise the automatically
7800 detected CPU topology, if such exists. If no CPU topology
7801 exists, undefined is returned.
7802 node refers to Non-Uniform Memory Access (NUMA) nodes.
7804 thread refers to hardware threads (for example, Intel hyper-
7805 threads).
7806 A level in term CpuTopology can be omitted if only one entry
7808 exists and InfoList is empty.
7809 thread can only be a sublevel to core. core can be a sub‐
7811 level to processor or node. processor can be on the top
7812 level or a sublevel to node. node can be on the top level or
7813 a sublevel to processor. That is, NUMA nodes can be proces‐
7814 sor internal or processor external. A CPU topology can con‐
7815 sist of a mix of processor internal and external NUMA nodes,
7816 as long as each logical CPU belongs to one NUMA node. Cache
7817 hierarchy is not part of the CpuTopology type, but will be
7818 in a future release. Other things can also make it into the
7819 CPU topology in a future release. So, expect the CpuTopology
7820 type to change.
7821 {cpu_topology, defined}:
7823 Returns the user-defined CpuTopology. For more information,
7826 see command-line flag +sct in erl(1) and argument cpu_topol‐
7827 ogy.
7828 {cpu_topology, detected}:
7830 Returns the automatically detected CpuTopologyy. The emula‐
7833 tor detects the CPU topology on some newer Linux, Solaris,
7834 FreeBSD, and Windows systems. On Windows system with more
7835 than 32 logical processors, the CPU topology is not
7836 detected.
7837 For more information, see argument cpu_topology.
7839 {cpu_topology, used}:
7841 Returns CpuTopology used by the emulator. For more informa‐
7842 tion, see argument cpu_topology.
7843 logical_processors:
7845 Returns the detected number of logical processors configured
7846 in the system. The return value is either an integer, or the
7847 atom unknown if the emulator cannot detect the configured
7848 logical processors.
7849 logical_processors_available:
7851 Returns the detected number of logical processors available
7852 to the Erlang runtime system. The return value is either an
7853 integer, or the atom unknown if the emulator cannot detect
7854 the available logical processors. The number of available
7855 logical processors is less than or equal to the number of
7856 logical processors online.
7857 logical_processors_online:
7859 Returns the detected number of logical processors online on
7860 the system. The return value is either an integer, or the
7861 atom unknown if the emulator cannot detect logical proces‐
7862 sors online. The number of logical processors online is less
7863 than or equal to the number of logical processors config‐
7864 ured.
7865 update_cpu_info:
7867 The runtime system rereads the CPU information available and
7868 updates its internally stored information about the detected
7869 CPU topology and the number of logical processors config‐
7870 ured, online, and available.
7871 If the CPU information has changed since the last time it
7873 was read, the atom changed is returned, otherwise the atom
7874 unchanged. If the CPU information has changed, you probably
7875 want to adjust the number of schedulers online. You typi‐
7876 cally want to have as many schedulers online as logical pro‐
7877 cessors available.
7878 erlang:system_info(Item :: fullsweep_after) ->
7880 {fullsweep_after, integer() >= 0}
7881 erlang:system_info(Item :: garbage_collection) ->
7883 [{atom(), integer()}]
7884 erlang:system_info(Item :: heap_sizes) -> [integer() >= 0]
7886 erlang:system_info(Item :: heap_type) -> private
7888 erlang:system_info(Item :: max_heap_size) ->
7890 {max_heap_size,
7891 MaxHeapSize :: max_heap_size()}
7892 erlang:system_info(Item :: message_queue_data) ->
7894 message_queue_data()
7895 erlang:system_info(Item :: min_heap_size) ->
7897 {min_heap_size,
7898 MinHeapSize :: integer() >= 1}
7899 erlang:system_info(Item :: min_bin_vheap_size) ->
7901 {min_bin_vheap_size,
7902 MinBinVHeapSize :: integer() >= 1}
7903 erlang:system_info(Item :: procs) -> binary()
7905 Types:
7907 message_queue_data() = off_heap | on_heap
7909 max_heap_size() =
7910 integer() >= 0 |
7911 #{size => integer() >= 0,
7912 kill => boolean(),
7913 error_logger => boolean()}
7914 Returns information about the default process heap settings:
7916 fullsweep_after:
7918 Returns {fullsweep_after, integer() >= 0}, which is the
7919 fullsweep_after garbage collection setting used by default.
7920 For more information, see garbage_collection described
7921 below.
7922 garbage_collection:
7924 Returns a list describing the default garbage collection
7925 settings. A process spawned on the local node by a spawn or
7926 spawn_link uses these garbage collection settings. The
7927 default settings can be changed by using erlang:sys‐
7928 tem_flag/2. spawn_opt/2,3,4 can spawn a process that does
7929 not use the default settings.
7930 heap_sizes:
7932 Returns a list of integers representing valid heap sizes in
7933 words. All Erlang heaps are sized from sizes in this list.
7934 heap_type:
7936 Returns the heap type used by the current emulator. One heap
7937 type exists:
7938 private:
7940 Each process has a heap reserved for its use and no ref‐
7941 erences between heaps of different processes are allowed.
7942 Messages passed between processes are copied between
7943 heaps.
7944 max_heap_size:
7946 Returns {max_heap_size, MaxHeapSize}, where MaxHeapSize is
7947 the current system-wide maximum heap size settings for
7948 spawned processes. This setting can be set using the com‐
7949 mand-line flags +hmax, +hmaxk and +hmaxel in erl(1). It can
7950 also be changed at runtime using erlang:sys‐
7951 tem_flag(max_heap_size, MaxHeapSize). For more details about
7952 the max_heap_size process flag, see
7953 process_flag(max_heap_size, MaxHeapSize).
7954 message_queue_data:
7956 Returns the default value of the message_queue_data process
7957 flag, which is either off_heap or on_heap. This default is
7958 set by command-line argument +hmqd in erl(1). For more
7959 information on the message_queue_data process flag, see doc‐
7960 umentation of process_flag(message_queue_data, MQD).
7961 min_heap_size:
7963 Returns {min_heap_size, MinHeapSize}, where MinHeapSize is
7964 the current system-wide minimum heap size for spawned pro‐
7965 cesses.
7966 min_bin_vheap_size:
7968 Returns {min_bin_vheap_size, MinBinVHeapSize}, where MinBin‐
7969 VHeapSize is the current system-wide minimum binary virtual
7970 heap size for spawned processes.
7971 procs:
7973 Returns a binary containing a string of process and port
7974 information formatted as in Erlang crash dumps. For more
7975 information, see section How to interpret the Erlang crash
7976 dumps in the User's Guide.
7977 erlang:system_info(Item :: atom_count) -> integer() >= 1
7979 erlang:system_info(Item :: atom_limit) -> integer() >= 1
7981 erlang:system_info(Item :: ets_count) -> integer() >= 1
7983 erlang:system_info(Item :: ets_limit) -> integer() >= 1
7985 erlang:system_info(Item :: port_count) -> integer() >= 0
7987 erlang:system_info(Item :: port_limit) -> integer() >= 1
7989 erlang:system_info(Item :: process_count) -> integer() >= 1
7991 erlang:system_info(Item :: process_limit) -> integer() >= 1
7993 Returns information about the current system (emulator) limits
7995 as specified by Item:
7996 atom_count:
7998 Returns the number of atoms currently existing at the local
7999 node. The value is given as an integer.
8000 atom_limit:
8002 Returns the maximum number of atoms allowed. This limit can
8003 be increased at startup by passing command-line flag +t to
8004 erl(1).
8005 ets_count:
8007 Returns the number of ETS tables currently existing at the
8008 local node.
8009 ets_limit:
8011 Returns the limit for number of ETS tables. This limit is
8012 partially obsolete and number of tables are only limited by
8013 available memory.
8014 port_count:
8016 Returns the number of ports currently existing at the local
8017 node. The value is given as an integer. This is the same
8018 value as returned by length(erlang:ports()), but more effi‐
8019 cient.
8020 port_limit:
8022 Returns the maximum number of simultaneously existing ports
8023 at the local node as an integer. This limit can be config‐
8024 ured at startup by using command-line flag +Q in erl(1).
8025 process_count:
8027 Returns the number of processes currently existing at the
8028 local node. The value is given as an integer. This is the
8029 same value as returned by length(processes()), but more
8030 efficient.
8031 process_limit:
8033 Returns the maximum number of simultaneously existing pro‐
8034 cesses at the local node. The value is given as an integer.
8035 This limit can be configured at startup by using command-
8036 line flag +P in erl(1).
8037 erlang:system_info(Item :: end_time) -> integer() >= 0
8039 erlang:system_info(Item :: os_monotonic_time_source) ->
8041 [{atom(), term()}]
8042 erlang:system_info(Item :: os_system_time_source) ->
8044 [{atom(), term()}]
8045 erlang:system_info(Item :: start_time) -> integer()
8047 erlang:system_info(Item :: time_correction) -> true | false
8049 erlang:system_info(Item :: time_offset) ->
8051 preliminary | final | volatile
8052 erlang:system_info(Item :: time_warp_mode) ->
8054 no_time_warp |
8055 single_time_warp |
8056 multi_time_warp
8057 erlang:system_info(Item :: tolerant_timeofday) ->
8059 enabled | disabled
8060 Returns information about the current system (emulator) time as
8062 specified by Item:
8063 end_time:
8065 The last Erlang monotonic time in native time unit that can
8066 be represented internally in the current Erlang runtime sys‐
8067 tem instance. The time between the start time and the end
8068 time is at least a quarter of a millennium.
8069 os_monotonic_time_source:
8071 Returns a list containing information about the source of OS
8072 monotonic time that is used by the runtime system.
8073 If [] is returned, no OS monotonic time is available. The
8075 list contains two-tuples with Keys as first element, and
8076 Values as second element. The order of these tuples is unde‐
8077 fined. The following tuples can be part of the list, but
8078 more tuples can be introduced in the future:
8079 {function, Function}:
8081 Function is the name of the function used. This tuple
8082 always exists if OS monotonic time is available to the
8083 runtime system.
8084 {clock_id, ClockId}:
8086 This tuple only exists if Function can be used with dif‐
8087 ferent clocks. ClockId corresponds to the clock identifier
8088 used when calling Function.
8089 {resolution, OsMonotonicTimeResolution}:
8091 Highest possible resolution of current OS monotonic time
8092 source as parts per second. If no resolution information
8093 can be retrieved from the OS, OsMonotonicTimeResolution is
8094 set to the resolution of the time unit of Functions return
8095 value. That is, the actual resolution can be lower than
8096 OsMonotonicTimeResolution. Notice that the resolution does
8097 not say anything about the accuracy or whether the pre‐
8098 cision aligns with the resolution. You do, however, know
8099 that the precision is not better than OsMonotonicTimeReso‐
8100 lution.
8101 {extended, Extended}:
8103 Extended equals yes if the range of time values has been
8104 extended; otherwise Extended equals no. The range must be
8105 extended if Function returns values that wrap fast. This
8106 typically is the case when the return value is a 32-bit
8107 value.
8108 {parallel, Parallel}:
8110 Parallel equals yes if Function is called in parallel from
8111 multiple threads. If it is not called in parallel, because
8112 calls must be serialized, Parallel equals no.
8113 {time, OsMonotonicTime}:
8115 OsMonotonicTime equals current OS monotonic time in native
8116 time unit.
8117 os_system_time_source:
8119 Returns a list containing information about the source of OS
8120 system time that is used by the runtime system.
8121 The list contains two-tuples with Keys as first element, and
8123 Values as second element. The order of these tuples is unde‐
8124 fined. The following tuples can be part of the list, but
8125 more tuples can be introduced in the future:
8126 {function, Function}:
8128 Function is the name of the funcion used.
8129 {clock_id, ClockId}:
8131 Exists only if Function can be used with different clocks.
8132 ClockId corresponds to the clock identifier used when
8133 calling Function.
8134 {resolution, OsSystemTimeResolution}:
8136 Highest possible resolution of current OS system time
8137 source as parts per second. If no resolution information
8138 can be retrieved from the OS, OsSystemTimeResolution is
8139 set to the resolution of the time unit of Functions return
8140 value. That is, the actual resolution can be lower than
8141 OsSystemTimeResolution. Notice that the resolution does
8142 not say anything about the accuracy or whether the pre‐
8143 cision do align with the resolution. You do, however, know
8144 that the precision is not better than OsSystemTimeResolu‐
8145 tion.
8146 {parallel, Parallel}:
8148 Parallel equals yes if Function is called in parallel from
8149 multiple threads. If it is not called in parallel, because
8150 calls needs to be serialized, Parallel equals no.
8151 {time, OsSystemTime}:
8153 OsSystemTime equals current OS system time in native time
8154 unit.
8155 start_time:
8157 The Erlang monotonic time in native time unit at the time
8158 when current Erlang runtime system instance started.
8159 See also erlang:system_info(end_time).
8161 time_correction:
8163 Returns a boolean value indicating whether time correction
8164 is enabled or not.
8165 time_offset:
8167 Returns the state of the time offset:
8168 preliminary:
8170 The time offset is preliminary, and will be changed and
8171 finalized later. The preliminary time offset is used dur‐
8172 ing the preliminary phase of the single time warp mode.
8173 final:
8175 The time offset is final. This either because no time
8176 warp mode is used, or because the time offset have been
8177 finalized when single time warp mode is used.
8178 volatile:
8180 The time offset is volatile. That is, it can change at any
8181 time. This is because multi-time warp mode is used.
8182 time_warp_mode:
8184 Returns a value identifying the time warp mode that is
8185 used:
8186 no_time_warp:
8188 The no time warp mode is used.
8189 single_time_warp:
8191 The single time warp mode is used.
8192 multi_time_warp:
8194 The multi-time warp mode is used.
8195 tolerant_timeofday:
8197 Returns whether a pre ERTS 7.0 backwards compatible compen‐
8198 sation for sudden changes of system time is enabled or dis‐
8199 abled. Such compensation is enabled when the time offset is
8200 final, and time correction is enabled.
8201 erlang:system_info(Item :: dirty_cpu_schedulers) ->
8203 integer() >= 0
8204 erlang:system_info(Item :: dirty_cpu_schedulers_online) ->
8206 integer() >= 0
8207 erlang:system_info(Item :: dirty_io_schedulers) ->
8209 integer() >= 0
8210 erlang:system_info(Item :: multi_scheduling) ->
8212 disabled |
8213 blocked |
8214 blocked_normal |
8215 enabled
8216 erlang:system_info(Item :: multi_scheduling_blockers) ->
8218 [Pid :: pid()]
8219 erlang:system_info(Item :: otp_release) -> string()
8221 erlang:system_info(Item :: scheduler_bind_type) ->
8223 spread |
8224 processor_spread |
8225 thread_spread |
8226 thread_no_node_processor_spread |
8227 no_node_processor_spread |
8228 no_node_thread_spread |
8229 no_spread |
8230 unbound
8231 erlang:system_info(Item :: scheduler_bindings) -> tuple()
8233 erlang:system_info(Item :: scheduler_id) ->
8235 SchedulerId :: integer() >= 1
8236 erlang:system_info(Item :: schedulers | schedulers_online) ->
8238 integer() >= 1
8239 erlang:system_info(Item :: smp_support) -> boolean()
8241 erlang:system_info(Item :: threads) -> boolean()
8243 erlang:system_info(Item :: thread_pool_size) -> integer() >= 0
8245 Returns information about schedulers, scheduling and threads in
8247 the current system as specified by Item:
8248 dirty_cpu_schedulers:
8250 Returns the number of dirty CPU scheduler threads used by
8251 the emulator. Dirty CPU schedulers execute CPU-bound native
8252 functions, such as NIFs, linked-in driver code, and BIFs
8253 that cannot be managed cleanly by the normal emulator sched‐
8254 ulers.
8255 The number of dirty CPU scheduler threads is determined at
8257 emulator boot time and cannot be changed after that. How‐
8258 ever, the number of dirty CPU scheduler threads online can
8259 be changed at any time. The number of dirty CPU schedulers
8260 can be set at startup by passing command-line flag +SDcpu or
8261 +SDPcpu in erl(1).
8262 See also erlang:system_flag(dirty_cpu_schedulers_online,
8264 DirtyCPUSchedulersOnline), erlang:sys‐
8265 tem_info(dirty_cpu_schedulers_online), erlang:sys‐
8266 tem_info(dirty_io_schedulers), erlang:system_info(sched‐
8267 ulers), erlang:system_info(schedulers_online), and
8268 erlang:system_flag(schedulers_online, SchedulersOnline).
8269 dirty_cpu_schedulers_online:
8271 Returns the number of dirty CPU schedulers online. The
8272 return value satisfies 1 <= DirtyCPUSchedulersOnline <= N,
8273 where N is the smallest of the return values of erlang:sys‐
8274 tem_info(dirty_cpu_schedulers) and erlang:system_info(sched‐
8275 ulers_online).
8276 The number of dirty CPU schedulers online can be set at
8278 startup by passing command-line flag +SDcpu in erl(1).
8279 For more information, see erlang:sys‐
8281 tem_info(dirty_cpu_schedulers), erlang:sys‐
8282 tem_info(dirty_io_schedulers), erlang:system_info(sched‐
8283 ulers_online), and erlang:system_flag(dirty_cpu_sched‐
8284 ulers_online, DirtyCPUSchedulersOnline).
8285 dirty_io_schedulers:
8287 Returns the number of dirty I/O schedulers as an integer.
8288 Dirty I/O schedulers execute I/O-bound native functions,
8289 such as NIFs and linked-in driver code, which cannot be man‐
8290 aged cleanly by the normal emulator schedulers.
8291 This value can be set at startup by passing command-line
8293 argument +SDio in erl(1).
8294 For more information, see erlang:sys‐
8296 tem_info(dirty_cpu_schedulers), erlang:sys‐
8297 tem_info(dirty_cpu_schedulers_online), and erlang:sys‐
8298 tem_flag(dirty_cpu_schedulers_online, DirtyCPUSchedulersOn‐
8299 line).
8300 multi_scheduling:
8302 Returns one of the following:
8303 disabled:
8305 The emulator has been started with only one scheduler
8306 thread.
8307 blocked:
8309 The emulator has more than one scheduler thread, but all
8310 scheduler threads except one are blocked. That is, only
8311 one scheduler thread schedules Erlang processes and exe‐
8312 cutes Erlang code.
8313 blocked_normal:
8315 The emulator has more than one scheduler thread, but all
8316 normal scheduler threads except one are blocked. Notice
8317 that dirty schedulers are not blocked, and can schedule
8318 Erlang processes and execute native code.
8319 enabled:
8321 The emulator has more than one scheduler thread, and no
8322 scheduler threads are blocked. That is, all available
8323 scheduler threads schedule Erlang processes and execute
8324 Erlang code.
8325 See also erlang:system_flag(multi_scheduling, BlockState),
8327 erlang:system_info(multi_scheduling_blockers), erlang:sys‐
8328 tem_info(normal_multi_scheduling_blockers), and erlang:sys‐
8329 tem_info(schedulers).
8330 multi_scheduling_blockers:
8332 Returns a list of Pids when multi-scheduling is blocked,
8333 otherwise the empty list is returned. The Pids in the list
8334 represent all the processes currently blocking multi-sched‐
8335 uling. A Pid occurs only once in the list, even if the cor‐
8336 responding process has blocked multiple times.
8337 See also erlang:system_flag(multi_scheduling, BlockState),
8339 erlang:system_info(multi_scheduling), erlang:sys‐
8340 tem_info(normal_multi_scheduling_blockers), and erlang:sys‐
8341 tem_info(schedulers).
8342 normal_multi_scheduling_blockers:
8344 Returns a list of Pids when normal multi-scheduling is
8345 blocked (that is, all normal schedulers but one is blocked),
8346 otherwise the empty list is returned. The Pids in the list
8347 represent all the processes currently blocking normal multi-
8348 scheduling. A Pid occurs only once in the list, even if the
8349 corresponding process has blocked multiple times.
8350 See also erlang:system_flag(multi_scheduling, BlockState),
8352 erlang:system_info(multi_scheduling), erlang:sys‐
8353 tem_info(multi_scheduling_blockers), and erlang:sys‐
8354 tem_info(schedulers).
8355 scheduler_bind_type:
8357 Returns information about how the user has requested sched‐
8358 ulers to be bound or not bound.
8359 Notice that although a user has requested schedulers to be
8361 bound, they can silently have failed to bind. To inspect the
8362 scheduler bindings, call erlang:system_info(scheduler_bind‐
8363 ings).
8364 For more information, see command-line argument +sbt in
8366 erl(1) and erlang:system_info(scheduler_bindings).
8367 scheduler_bindings:
8369 Returns information about the currently used scheduler bind‐
8370 ings.
8371 A tuple of a size equal to erlang:system_info(schedulers) is
8373 returned. The tuple elements are integers or the atom
8374 unbound. Logical processor identifiers are represented as
8375 integers. The Nth element of the tuple equals the current
8376 binding for the scheduler with the scheduler identifier
8377 equal to N. For example, if the schedulers are bound, ele‐
8378 ment(erlang:system_info(scheduler_id), erlang:sys‐
8379 tem_info(scheduler_bindings)) returns the identifier of the
8380 logical processor that the calling process is executing on.
8381 Notice that only schedulers online can be bound to logical
8383 processors.
8384 For more information, see command-line argument +sbt in
8386 erl(1) and erlang:system_info(schedulers_online).
8387 scheduler_id:
8389 Returns the scheduler ID (SchedulerId) of the scheduler
8390 thread that the calling process is executing on. SchedulerId
8391 is a positive integer, where 1 <= SchedulerId <= erlang:sys‐
8392 tem_info(schedulers).
8393 See also erlang:system_info(schedulers).
8395 schedulers:
8397 Returns the number of scheduler threads used by the emula‐
8398 tor. Scheduler threads online schedules Erlang processes and
8399 Erlang ports, and execute Erlang code and Erlang linked-in
8400 driver code.
8401 The number of scheduler threads is determined at emulator
8403 boot time and cannot be changed later. However, the number
8404 of schedulers online can be changed at any time.
8405 See also erlang:system_flag(schedulers_online, SchedulersOn‐
8407 line), erlang:system_info(schedulers_online), erlang:sys‐
8408 tem_info(scheduler_id), erlang:system_flag(multi_scheduling,
8409 BlockState), erlang:system_info(multi_scheduling),
8410 erlang:system_info(normal_multi_scheduling_blockers) and
8411 erlang:system_info(multi_scheduling_blockers).
8412 schedulers_online:
8414 Returns the number of schedulers online. The scheduler iden‐
8415 tifiers of schedulers online satisfy the relationship 1 <=
8416 SchedulerId <= erlang:system_info(schedulers_online).
8417 For more information, see erlang:system_info(schedulers) and
8419 erlang:system_flag(schedulers_online, SchedulersOnline).
8420 smp_support:
8422 Returns true.
8423 threads:
8425 Returns true.
8426 thread_pool_size:
8428 Returns the number of async threads in the async thread pool
8431 used for asynchronous driver calls
8432 (erl_driver:driver_async()). The value is given as an inte‐
8433 ger.
8434 erlang:system_info(Item :: creation) -> integer()
8436 erlang:system_info(Item :: delayed_node_table_gc) ->
8438 infinity | integer() >= 0
8439 erlang:system_info(Item :: dist) -> binary()
8441 erlang:system_info(Item :: dist_buf_busy_limit) ->
8443 integer() >= 0
8444 erlang:system_info(Item :: dist_ctrl) ->
8446 {Node :: node(),
8447 ControllingEntity :: port() | pid()}
8448 Returns information about Erlang Distribution in the current
8450 system as specified by Item:
8451 creation:
8453 Returns the creation of the local node as an integer. The
8454 creation is changed when a node is restarted. The creation
8455 of a node is stored in process identifiers, port identi‐
8456 fiers, and references. This makes it (to some extent) possi‐
8457 ble to distinguish between identifiers from different incar‐
8458 nations of a node. The valid creations are integers in the
8459 range 1..3, but this will probably change in a future
8460 release. If the node is not alive, 0 is returned.
8461 delayed_node_table_gc:
8463 Returns the amount of time in seconds garbage collection of
8464 an entry in a node table is delayed. This limit can be set
8465 on startup by passing command-line flag +zdntgc to erl(1).
8466 For more information, see the documentation of the command-
8467 line flag.
8468 dist:
8470 Returns a binary containing a string of distribution infor‐
8471 mation formatted as in Erlang crash dumps. For more informa‐
8472 tion, see section How to interpret the Erlang crash dumps
8473 in the User's Guide.
8474 dist_buf_busy_limit:
8476 Returns the value of the distribution buffer busy limit in
8477 bytes. This limit can be set at startup by passing command-
8478 line flag +zdbbl to erl(1).
8479 dist_ctrl:
8481 Returns a list of tuples {Node, ControllingEntity}, one
8482 entry for each connected remote node. Node is the node name
8483 and ControllingEntity is the port or process identifier
8484 responsible for the communication to that node. More specif‐
8485 ically, ControllingEntity for nodes connected through TCP/IP
8486 (the normal case) is the socket used in communication with
8487 the specific node.
8488 erlang:system_info(Item :: build_type) ->
8490 opt |
8491 debug |
8492 purify |
8493 quantify |
8494 purecov |
8495 gcov |
8496 valgrind |
8497 gprof |
8498 lcnt |
8499 frmptr
8500 erlang:system_info(Item :: c_compiler_used) -> {atom(), term()}
8502 erlang:system_info(Item :: check_io) -> [term()]
8504 erlang:system_info(Item :: compat_rel) -> integer()
8506 erlang:system_info(Item :: debug_compiled) -> boolean()
8508 erlang:system_info(Item :: driver_version) -> string()
8510 erlang:system_info(Item :: dynamic_trace) ->
8512 none | dtrace | systemtap
8513 erlang:system_info(Item :: dynamic_trace_probes) -> boolean()
8515 erlang:system_info(Item :: info) -> binary()
8517 erlang:system_info(Item :: kernel_poll) -> boolean()
8519 erlang:system_info(Item :: loaded) -> binary()
8521 erlang:system_info(Item :: machine) -> string()
8523 erlang:system_info(Item :: modified_timing_level) ->
8525 integer() | undefined
8526 erlang:system_info(Item :: nif_version) -> string()
8528 erlang:system_info(Item :: otp_release) -> string()
8530 erlang:system_info(Item :: port_parallelism) -> boolean()
8532 erlang:system_info(Item :: system_architecture) -> string()
8534 erlang:system_info(Item :: system_logger) ->
8536 logger | undefined | pid()
8537 erlang:system_info(Item :: system_version) -> string()
8539 erlang:system_info(Item :: trace_control_word) ->
8541 integer() >= 0
8542 erlang:system_info(Item :: version) -> string()
8544 erlang:system_info(Item ::
8546 wordsize |
8547 {wordsize, internal} |
8548 {wordsize, external}) ->
8549 4 | 8
8550 Returns various information about the current system (emulator)
8552 as specified by Item:
8553 build_type:
8555 Returns an atom describing the build type of the runtime
8556 system. This is normally the atom opt for optimized. Other
8557 possible return values are debug, purify, quantify, purecov,
8558 gcov, valgrind, gprof, and lcnt. Possible return values can
8559 be added or removed at any time without prior notice.
8560 c_compiler_used:
8562 Returns a two-tuple describing the C compiler used when com‐
8563 piling the runtime system. The first element is an atom
8564 describing the name of the compiler, or undefined if
8565 unknown. The second element is a term describing the version
8566 of the compiler, or undefined if unknown.
8567 check_io:
8569 Returns a list containing miscellaneous information about
8570 the emulators internal I/O checking. Notice that the content
8571 of the returned list can vary between platforms and over
8572 time. It is only guaranteed that a list is returned.
8573 compat_rel:
8575 Returns the compatibility mode of the local node as an inte‐
8576 ger. The integer returned represents the Erlang/OTP release
8577 that the current emulator has been set to be backward com‐
8578 patible with. The compatibility mode can be configured at
8579 startup by using command-line flag +R in erl(1).
8580 debug_compiled:
8582 Returns true if the emulator has been debug-compiled, other‐
8583 wise false.
8584 driver_version:
8586 Returns a string containing the Erlang driver version used
8587 by the runtime system. It has the form "<major ver>.<minor
8588 ver>".
8589 dynamic_trace:
8591 Returns an atom describing the dynamic trace framework com‐
8592 piled into the virtual machine. It can be dtrace, systemtap,
8593 or none. For a commercial or standard build, it is always
8594 none. The other return values indicate a custom configura‐
8595 tion (for example, ./configure --with-dynamic-trace=dtrace).
8596 For more information about dynamic tracing, see dyntrace(3)
8597 manual page and the README.dtrace/README.systemtap files in
8598 the Erlang source code top directory.
8599 dynamic_trace_probes:
8601 Returns a boolean() indicating if dynamic trace probes
8602 (dtrace or systemtap) are built into the emulator. This can
8603 only be true if the virtual machine was built for dynamic
8604 tracing (that is, system_info(dynamic_trace) returns dtrace
8605 or systemtap).
8606 info:
8608 Returns a binary containing a string of miscellaneous system
8609 information formatted as in Erlang crash dumps. For more
8610 information, see section How to interpret the Erlang crash
8611 dumps in the User's Guide.
8612 kernel_poll:
8614 Returns true if the emulator uses some kind of kernel-poll
8615 implementation, otherwise false.
8616 loaded:
8618 Returns a binary containing a string of loaded module infor‐
8619 mation formatted as in Erlang crash dumps. For more informa‐
8620 tion, see section How to interpret the Erlang crash dumps in
8621 the User's Guide.
8622 machine:
8624 Returns a string containing the Erlang machine name.
8625 modified_timing_level:
8627 Returns the modified timing-level (an integer) if modified
8628 timing is enabled, otherwise undefined. For more information
8629 about modified timing, see command-line flag +T in erl(1)
8630 nif_version:
8632 Returns a string containing the version of the Erlang NIF
8633 interface used by the runtime system. It is on the form
8634 "<major ver>.<minor ver>".
8635 otp_release:
8637 Returns a string containing the OTP release number of the
8640 OTP release that the currently executing ERTS application is
8641 part of.
8642 As from Erlang/OTP 17, the OTP release number corresponds to
8644 the major OTP version number. No erlang:system_info() argu‐
8645 ment gives the exact OTP version. This is because the exact
8646 OTP version in the general case is difficult to determine.
8647 For more information, see the description of versions in
8648 System principles in System Documentation.
8649 port_parallelism:
8651 Returns the default port parallelism scheduling hint used.
8652 For more information, see command-line argument +spp in
8653 erl(1).
8654 system_architecture:
8656 Returns a string containing the processor and OS architec‐
8657 ture the emulator is built for.
8658 system_logger:
8660 Returns the current system_logger as set by erlang:sys‐
8661 tem_flag(system_logger, _).
8662 system_version:
8664 Returns a string containing version number and some impor‐
8665 tant properties, such as the number of schedulers.
8666 trace_control_word:
8668 Returns the value of the node trace control word. For more
8669 information, see function get_tcw in section Match Specifi‐
8670 cations in Erlang in the User's Guide.
8671 version:
8673 Returns a string containing the version number of the emula‐
8674 tor.
8675 wordsize:
8677 Same as {wordsize, internal}.
8678 {wordsize, internal}:
8680 Returns the size of Erlang term words in bytes as an inte‐
8681 ger, that is, 4 is returned on a 32-bit architecture, and 8
8682 is returned on a pure 64-bit architecture. On a halfword
8683 64-bit emulator, 4 is returned, as the Erlang terms are
8684 stored using a virtual word size of half the system word
8685 size.
8686 {wordsize, external}:
8688 Returns the true word size of the emulator, that is, the
8689 size of a pointer. The value is given in bytes as an inte‐
8690 ger. On a pure 32-bit architecture, 4 is returned. On both a
8691 half word and on a pure 64-bit architecture, 8 is returned.
8692 erlang:system_monitor() -> MonSettings
8694 Types:
8696 MonSettings = undefined | {MonitorPid, Options}
8698 MonitorPid = pid()
8699 Options = [system_monitor_option()]
8700 system_monitor_option() =
8701 busy_port |
8702 busy_dist_port |
8703 {long_gc, integer() >= 0} |
8704 {long_schedule, integer() >= 0} |
8705 {large_heap, integer() >= 0}
8706 Returns the current system monitoring settings set by
8708 erlang:system_monitor/2 as {MonitorPid, Options}, or undefined
8709 if no settings exist. The order of the options can be different
8710 from the one that was set.
8711 erlang:system_monitor(Arg) -> MonSettings
8713 Types:
8715 Arg = MonSettings = undefined | {MonitorPid, Options}
8717 MonitorPid = pid()
8718 Options = [system_monitor_option()]
8719 system_monitor_option() =
8720 busy_port |
8721 busy_dist_port |
8722 {long_gc, integer() >= 0} |
8723 {long_schedule, integer() >= 0} |
8724 {large_heap, integer() >= 0}
8725 When called with argument undefined, all system performance mon‐
8727 itoring settings are cleared.
8728 Calling the function with {MonitorPid, Options} as argument is
8730 the same as calling erlang:system_monitor(MonitorPid, Options).
8731 Returns the previous system monitor settings just like
8733 erlang:system_monitor/0.
8734 erlang:system_monitor(MonitorPid, Options) -> MonSettings
8736 Types:
8738 MonitorPid = pid()
8740 Options = [system_monitor_option()]
8741 MonSettings = undefined | {OldMonitorPid, OldOptions}
8742 OldMonitorPid = pid()
8743 OldOptions = [system_monitor_option()]
8744 system_monitor_option() =
8745 busy_port |
8746 busy_dist_port |
8747 {long_gc, integer() >= 0} |
8748 {long_schedule, integer() >= 0} |
8749 {large_heap, integer() >= 0}
8750 Sets the system performance monitoring options. MonitorPid is a
8752 local process identifier (pid) receiving system monitor mes‐
8753 sages. The second argument is a list of monitoring options:
8754 {long_gc, Time}:
8756 If a garbage collection in the system takes at least Time
8757 wall clock milliseconds, a message {monitor, GcPid, long_gc,
8758 Info} is sent to MonitorPid. GcPid is the pid that was
8759 garbage collected. Info is a list of two-element tuples
8760 describing the result of the garbage collection.
8761 One of the tuples is {timeout, GcTime}, where GcTime is the
8763 time for the garbage collection in milliseconds. The other
8764 tuples are tagged with heap_size, heap_block_size,
8765 stack_size, mbuf_size, old_heap_size, and
8766 old_heap_block_size. These tuples are explained in the
8767 description of trace message gc_minor_start (see
8768 erlang:trace/3). New tuples can be added, and the order of
8769 the tuples in the Info list can be changed at any time with‐
8770 out prior notice.
8771 {long_schedule, Time}:
8773 If a process or port in the system runs uninterrupted for at
8774 least Time wall clock milliseconds, a message {monitor,
8775 PidOrPort, long_schedule, Info} is sent to MonitorPid.
8776 PidOrPort is the process or port that was running. Info is a
8777 list of two-element tuples describing the event.
8778 If a pid(), the tuples {timeout, Millis}, {in, Location},
8780 and {out, Location} are present, where Location is either an
8781 MFA ({Module, Function, Arity}) describing the function
8782 where the process was scheduled in/out, or the atom unde‐
8783 fined.
8784 If a port(), the tuples {timeout, Millis} and {port_op,Op}
8786 are present. Op is one of proc_sig, timeout, input, output,
8787 event, or dist_cmd, depending on which driver callback was
8788 executing.
8789 proc_sig is an internal operation and is never to appear,
8791 while the others represent the corresponding driver call‐
8792 backs timeout, ready_input, ready_output, event, and outputv
8793 (when the port is used by distribution). Value Millis in
8794 tuple timeout informs about the uninterrupted execution time
8795 of the process or port, which always is equal to or higher
8796 than the Time value supplied when starting the trace. New
8797 tuples can be added to the Info list in a future release.
8798 The order of the tuples in the list can be changed at any
8799 time without prior notice.
8800 This can be used to detect problems with NIFs or drivers
8802 that take too long to execute. 1 ms is considered a good
8803 maximum time for a driver callback or a NIF. However, a
8804 time-sharing system is usually to consider everything < 100
8805 ms as "possible" and fairly "normal". However, longer sched‐
8806 ule times can indicate swapping or a misbehaving NIF/driver.
8807 Misbehaving NIFs and drivers can cause bad resource utiliza‐
8808 tion and bad overall system performance.
8809 {large_heap, Size}:
8811 If a garbage collection in the system results in the allo‐
8812 cated size of a heap being at least Size words, a message
8813 {monitor, GcPid, large_heap, Info} is sent to MonitorPid.
8814 GcPid and Info are the same as for long_gc earlier, except
8815 that the tuple tagged with timeout is not present.
8816 The monitor message is sent if the sum of the sizes of all
8818 memory blocks allocated for all heap generations after a
8819 garbage collection is equal to or higher than Size.
8820 When a process is killed by max_heap_size, it is killed
8822 before the garbage collection is complete and thus no large
8823 heap message is sent.
8824 busy_port:
8826 If a process in the system gets suspended because it sends
8827 to a busy port, a message {monitor, SusPid, busy_port, Port}
8828 is sent to MonitorPid. SusPid is the pid that got suspended
8829 when sending to Port.
8830 busy_dist_port:
8832 If a process in the system gets suspended because it sends
8833 to a process on a remote node whose inter-node communication
8834 was handled by a busy port, a message {monitor, SusPid,
8835 busy_dist_port, Port} is sent to MonitorPid. SusPid is the
8836 pid that got suspended when sending through the inter-node
8837 communication port Port.
8838 Returns the previous system monitor settings just like
8840 erlang:system_monitor/0.
8841 Note:
8843 If a monitoring process gets so large that it itself starts to
8844 cause system monitor messages when garbage collecting, the mes‐
8845 sages enlarge the process message queue and probably make the
8846 problem worse.
8847 Keep the monitoring process neat and do not set the system moni‐
8849 tor limits too tight.
8850 Failures:
8853 badarg:
8855 If MonitorPid does not exist.
8856 badarg:
8858 If MonitorPid is not a local process.
8859 erlang:system_profile() -> ProfilerSettings
8861 Types:
8863 ProfilerSettings = undefined | {ProfilerPid, Options}
8865 ProfilerPid = pid() | port()
8866 Options = [system_profile_option()]
8867 system_profile_option() =
8868 exclusive |
8869 runnable_ports |
8870 runnable_procs |
8871 scheduler |
8872 timestamp |
8873 monotonic_timestamp |
8874 strict_monotonic_timestamp
8875 Returns the current system profiling settings set by erlang:sys‐
8877 tem_profile/2 as {ProfilerPid, Options}, or undefined if there
8878 are no settings. The order of the options can be different from
8879 the one that was set.
8880 erlang:system_profile(ProfilerPid, Options) -> ProfilerSettings
8882 Types:
8884 ProfilerPid = pid() | port() | undefined
8886 Options = [system_profile_option()]
8887 ProfilerSettings =
8888 undefined | {pid() | port(), [system_profile_option()]}
8889 system_profile_option() =
8890 exclusive |
8891 runnable_ports |
8892 runnable_procs |
8893 scheduler |
8894 timestamp |
8895 monotonic_timestamp |
8896 strict_monotonic_timestamp
8897 Sets system profiler options. ProfilerPid is a local process
8899 identifier (pid) or port receiving profiling messages. The
8900 receiver is excluded from all profiling. The second argument is
8901 a list of profiling options:
8902 exclusive:
8904 If a synchronous call to a port from a process is done, the
8905 calling process is considered not runnable during the call
8906 runtime to the port. The calling process is notified as
8907 inactive, and later active when the port callback returns.
8908 monotonic_timestamp:
8910 Time stamps in profile messages use Erlang monotonic time.
8911 The time stamp (Ts) has the same format and value as pro‐
8912 duced by erlang:monotonic_time(nanosecond).
8913 runnable_procs:
8915 If a process is put into or removed from the run queue, a
8916 message, {profile, Pid, State, Mfa, Ts}, is sent to Profil‐
8917 erPid. Running processes that are reinserted into the run
8918 queue after having been pre-empted do not trigger this mes‐
8919 sage.
8920 runnable_ports:
8922 If a port is put into or removed from the run queue, a mes‐
8923 sage, {profile, Port, State, 0, Ts}, is sent to ProfilerPid.
8924 scheduler:
8926 If a scheduler is put to sleep or awoken, a message, {pro‐
8927 file, scheduler, Id, State, NoScheds, Ts}, is sent to Pro‐
8928 filerPid.
8929 strict_monotonic_timestamp:
8931 Time stamps in profile messages consist of Erlang monotonic
8932 time and a monotonically increasing integer. The time stamp
8933 (Ts) has the same format and value as produced by
8934 {erlang:monotonic_time(nanosecond), erlang:unique_inte‐
8935 ger([monotonic])}.
8936 timestamp:
8938 Time stamps in profile messages include a time stamp (Ts)
8939 that has the same form as returned by erlang:now(). This is
8940 also the default if no time stamp flag is specified. If
8941 cpu_timestamp has been enabled through erlang:trace/3, this
8942 also effects the time stamp produced in profiling messages
8943 when flag timestamp is enabled.
8944 Note:
8946 erlang:system_profile behavior can change in a future release.
8947 erlang:system_time() -> integer()
8950 Returns current Erlang system time in native time unit.
8952 Calling erlang:system_time() is equivalent to erlang:mono‐
8954 tonic_time() + erlang:time_offset().
8955 Note:
8957 This time is not a monotonically increasing time in the general
8958 case. For more information, see the documentation of time warp
8959 modes in the User's Guide.
8960 erlang:system_time(Unit) -> integer()
8963 Types:
8965 Unit = time_unit()
8967 Returns current Erlang system time converted into the Unit
8969 passed as argument.
8970 Calling erlang:system_time(Unit) is equivalent to erlang:con‐
8972 vert_time_unit(erlang:system_time(), native, Unit).
8973 Note:
8975 This time is not a monotonically increasing time in the general
8976 case. For more information, see the documentation of time warp
8977 modes in the User's Guide.
8978 term_to_binary(Term) -> ext_binary()
8981 Types:
8983 Term = term()
8985 Returns a binary data object that is the result of encoding Term
8987 according to the Erlang external term format.
8988 This can be used for various purposes, for example, writing a
8990 term to a file in an efficient way, or sending an Erlang term to
8991 some type of communications channel not supported by distributed
8992 Erlang.
8993 > Bin = term_to_binary(hello).
8995 <<131,100,0,5,104,101,108,108,111>>
8996 > hello = binary_to_term(Bin).
8997 hello
8998 See also binary_to_term/1.
9001 Note:
9003 There is no guarantee that this function will return the same
9004 encoded representation for the same term.
9005 term_to_binary(Term, Options) -> ext_binary()
9008 Types:
9010 Term = term()
9012 Options =
9013 [compressed |
9014 {compressed, Level :: 0..9} |
9015 {minor_version, Version :: 0..2}]
9016 Returns a binary data object that is the result of encoding Term
9018 according to the Erlang external term format.
9019 If option compressed is provided, the external term format is
9021 compressed. The compressed format is automatically recognized by
9022 binary_to_term/1 as from Erlang/OTP R7B.
9023 A compression level can be specified by giving option {com‐
9025 pressed, Level}. Level is an integer with range 0..9, where:
9026 * 0 - No compression is done (it is the same as giving no com‐
9028 pressed option).
9029 * 1 - Takes least time but may not compress as well as the
9031 higher levels.
9032 * 6 - Default level when option compressed is provided.
9034 * 9 - Takes most time and tries to produce a smaller result.
9036 Notice "tries" in the preceding sentence; depending on the
9037 input term, level 9 compression either does or does not pro‐
9038 duce a smaller result than level 1 compression.
9039 Option {minor_version, Version} can be used to control some
9041 encoding details. This option was introduced in Erlang/OTP
9042 R11B-4. The valid values for Version are:
9043 0:
9045 Floats are encoded using a textual representation. This
9046 option is useful to ensure that releases before Erlang/OTP
9047 R11B-4 can decode resulting binary.
9048 This version encode atoms that can be represented by a
9050 latin1 string using latin1 encoding while only atoms that
9051 cannot be represented by latin1 are encoded using utf8.
9052 1:
9054 This is as of Erlang/OTP 17.0 the default. It forces any
9055 floats in the term to be encoded in a more space-efficient
9056 and exact way (namely in the 64-bit IEEE format, rather than
9057 converted to a textual representation). As from Erlang/OTP
9058 R11B-4, binary_to_term/1 can decode this representation.
9059 This version encode atoms that can be represented by a
9061 latin1 string using latin1 encoding while only atoms that
9062 cannot be represented by latin1 are encoded using utf8.
9063 2:
9065 Drops usage of the latin1 atom encoding and unconditionally
9066 use utf8 encoding for all atoms. This will be changed to the
9067 default in a future major release of Erlang/OTP. Erlang/OTP
9068 systems as of R16B can decode this representation.
9069 See also binary_to_term/1.
9071 throw(Any) -> no_return()
9073 Types:
9075 Any = term()
9077 A non-local return from a function. If evaluated within a catch,
9079 catch returns value Any. Example:
9080 > catch throw({hello, there}).
9082 {hello,there}
9083 Failure: nocatch if not evaluated within a catch.
9085 time() -> Time
9087 Types:
9089 Time = calendar:time()
9091 Returns the current time as {Hour, Minute, Second}.
9093 The time zone and Daylight Saving Time correction depend on the
9095 underlying OS. Example:
9096 > time().
9098 {9,42,44}
9099 erlang:time_offset() -> integer()
9101 Returns the current time offset between Erlang monotonic time
9103 and Erlang system time in native time unit. Current time offset
9104 added to an Erlang monotonic time gives corresponding Erlang
9105 system time.
9106 The time offset may or may not change during operation depending
9108 on the time warp mode used.
9109 Note:
9111 A change in time offset can be observed at slightly different
9112 points in time by different processes.
9113 If the runtime system is in multi-time warp mode, the time off‐
9115 set is changed when the runtime system detects that the OS sys‐
9116 tem time has changed. The runtime system will, however, not
9117 detect this immediately when it occurs. A task checking the time
9118 offset is scheduled to execute at least once a minute; so, under
9119 normal operation this is to be detected within a minute, but
9120 during heavy load it can take longer time.
9121 erlang:time_offset(Unit) -> integer()
9124 Types:
9126 Unit = time_unit()
9128 Returns the current time offset between Erlang monotonic time
9130 and Erlang system time converted into the Unit passed as argu‐
9131 ment.
9132 Same as calling erlang:convert_time_unit(erlang:time_offset(),
9134 native, Unit) however optimized for commonly used Units.
9135 erlang:timestamp() -> Timestamp
9137 Types:
9139 Timestamp = timestamp()
9141 timestamp() =
9142 {MegaSecs :: integer() >= 0,
9143 Secs :: integer() >= 0,
9144 MicroSecs :: integer() >= 0}
9145 Returns current Erlang system time on the format {MegaSecs,
9147 Secs, MicroSecs}. This format is the same as os:timestamp/0 and
9148 the deprecated erlang:now/0 use. The reason for the existence of
9149 erlang:timestamp() is purely to simplify use for existing code
9150 that assumes this time stamp format. Current Erlang system time
9151 can more efficiently be retrieved in the time unit of your
9152 choice using erlang:system_time/1.
9153 The erlang:timestamp() BIF is equivalent to:
9155 timestamp() ->
9157 ErlangSystemTime = erlang:system_time(microsecond),
9158 MegaSecs = ErlangSystemTime div 1000000000000,
9159 Secs = ErlangSystemTime div 1000000 - MegaSecs*1000000,
9160 MicroSecs = ErlangSystemTime rem 1000000,
9161 {MegaSecs, Secs, MicroSecs}.
9162 It, however, uses a native implementation that does not build
9164 garbage on the heap and with slightly better performance.
9165 Note:
9167 This time is not a monotonically increasing time in the general
9168 case. For more information, see the documentation of time warp
9169 modes in the User's Guide.
9170 tl(List) -> term()
9173 Types:
9175 List = [term(), ...]
9177 Returns the tail of List, that is, the list minus the first ele‐
9179 ment, for example:
9180 > tl([geesties, guilies, beasties]).
9182 [guilies, beasties]
9183 Allowed in guard tests.
9185 Failure: badarg if List is the empty list [].
9187 erlang:trace(PidPortSpec, How, FlagList) -> integer()
9189 Types:
9191 PidPortSpec =
9193 pid() |
9194 port() |
9195 all |
9196 processes |
9197 ports |
9198 existing |
9199 existing_processes |
9200 existing_ports |
9201 new |
9202 new_processes |
9203 new_ports
9204 How = boolean()
9205 FlagList = [trace_flag()]
9206 trace_flag() =
9207 all |
9208 send |
9209 'receive' |
9210 procs |
9211 ports |
9212 call |
9213 arity |
9214 return_to |
9215 silent |
9216 running |
9217 exiting |
9218 running_procs |
9219 running_ports |
9220 garbage_collection |
9221 timestamp |
9222 cpu_timestamp |
9223 monotonic_timestamp |
9224 strict_monotonic_timestamp |
9225 set_on_spawn |
9226 set_on_first_spawn |
9227 set_on_link |
9228 set_on_first_link |
9229 {tracer, pid() | port()} |
9230 {tracer, module(), term()}
9231 Turns on (if How == true) or off (if How == false) the trace
9233 flags in FlagList for the process or processes represented by
9234 PidPortSpec.
9235 PidPortSpec is either a process identifier (pid) for a local
9237 process, a port identifier, or one of the following atoms:
9238 all:
9240 All currently existing processes and ports and all that will
9241 be created in the future.
9242 processes:
9244 All currently existing processes and all that will be cre‐
9245 ated in the future.
9246 ports:
9248 All currently existing ports and all that will be created in
9249 the future.
9250 existing:
9252 All currently existing processes and ports.
9253 existing_processes:
9255 All currently existing processes.
9256 existing_ports:
9258 All currently existing ports.
9259 new:
9261 All processes and ports that will be created in the future.
9262 new_processes:
9264 All processes that will be created in the future.
9265 new_ports:
9267 All ports that will be created in the future.
9268 FlagList can contain any number of the following flags (the
9270 "message tags" refers to the list of trace messages):
9271 all:
9273 Sets all trace flags except tracer and cpu_timestamp, which
9274 are in their nature different than the others.
9275 send:
9277 Traces sending of messages.
9278 Message tags: send and send_to_non_existing_process.
9280 'receive':
9282 Traces receiving of messages.
9283 Message tags: 'receive'.
9285 call:
9287 Traces certain function calls. Specify which function calls
9288 to trace by calling erlang:trace_pattern/3.
9289 Message tags: call and return_from.
9291 silent:
9293 Used with the call trace flag. The call, return_from, and
9294 return_to trace messages are inhibited if this flag is set,
9295 but they are executed as normal if there are match specifi‐
9296 cations.
9297 Silent mode is inhibited by executing erlang:trace(_, false,
9299 [silent|_]), or by a match specification executing the func‐
9300 tion {silent, false}.
9301 The silent trace flag facilitates setting up a trace on many
9303 or even all processes in the system. The trace can then be
9304 activated and deactivated using the match specification
9305 function {silent,Bool}, giving a high degree of control of
9306 which functions with which arguments that trigger the trace.
9307 Message tags: call, return_from, and return_to. Or rather,
9309 the absence of.
9310 return_to:
9312 Used with the call trace flag. Traces the return from a
9313 traced function back to its caller. Only works for functions
9314 traced with option local to erlang:trace_pattern/3.
9315 The semantics is that a trace message is sent when a call
9317 traced function returns, that is, when a chain of tail
9318 recursive calls ends. Only one trace message is sent per
9319 chain of tail recursive calls, so the properties of tail
9320 recursiveness for function calls are kept while tracing with
9321 this flag. Using call and return_to trace together makes it
9322 possible to know exactly in which function a process exe‐
9323 cutes at any time.
9324 To get trace messages containing return values from func‐
9326 tions, use the {return_trace} match specification action
9327 instead.
9328 Message tags: return_to.
9330 procs:
9332 Traces process-related events.
9333 Message tags: spawn, spawned, exit, register, unregister,
9335 link, unlink, getting_linked, and getting_unlinked.
9336 ports:
9338 Traces port-related events.
9339 Message tags: open, closed, register, unregister, get‐
9341 ting_linked, and getting_unlinked.
9342 running:
9344 Traces scheduling of processes.
9345 Message tags: in and out.
9347 exiting:
9349 Traces scheduling of exiting processes.
9350 Message tags: in_exiting, out_exiting, and out_exited.
9352 running_procs:
9354 Traces scheduling of processes just like running. However,
9355 this option also includes schedule events when the process
9356 executes within the context of a port without being sched‐
9357 uled out itself.
9358 Message tags: in and out.
9360 running_ports:
9362 Traces scheduling of ports.
9363 Message tags: in and out.
9365 garbage_collection:
9367 Traces garbage collections of processes.
9368 Message tags: gc_minor_start, gc_max_heap_size, and
9370 gc_minor_end.
9371 timestamp:
9373 Includes a time stamp in all trace messages. The time stamp
9374 (Ts) has the same form as returned by erlang:now().
9375 cpu_timestamp:
9377 A global trace flag for the Erlang node that makes all trace
9378 time stamps using flag timestamp to be in CPU time, not wall
9379 clock time. That is, cpu_timestamp is not be used if mono‐
9380 tonic_timestamp or strict_monotonic_timestamp is enabled.
9381 Only allowed with PidPortSpec==all. If the host machine OS
9382 does not support high-resolution CPU time measurements,
9383 trace/3 exits with badarg. Notice that most OS do not syn‐
9384 chronize this value across cores, so be prepared that time
9385 can seem to go backwards when using this option.
9386 monotonic_timestamp:
9388 Includes an Erlang monotonic time time stamp in all trace
9389 messages. The time stamp (Ts) has the same format and value
9390 as produced by erlang:monotonic_time(nanosecond). This flag
9391 overrides flag cpu_timestamp.
9392 strict_monotonic_timestamp:
9394 Includes an time stamp consisting of Erlang monotonic time
9395 and a monotonically increasing integer in all trace mes‐
9396 sages. The time stamp (Ts) has the same format and value as
9397 produced by { erlang:monotonic_time(nanosecond),
9398 erlang:unique_integer([monotonic])}. This flag overrides
9399 flag cpu_timestamp.
9400 arity:
9402 Used with the call trace flag. {M, F, Arity} is specified
9403 instead of {M, F, Args} in call trace messages.
9404 set_on_spawn:
9406 Makes any process created by a traced process inherit its
9407 trace flags, including flag set_on_spawn.
9408 set_on_first_spawn:
9410 Makes the first process created by a traced process inherit
9411 its trace flags, excluding flag set_on_first_spawn.
9412 set_on_link:
9414 Makes any process linked by a traced process inherit its
9415 trace flags, including flag set_on_link.
9416 set_on_first_link:
9418 Makes the first process linked to by a traced process
9419 inherit its trace flags, excluding flag set_on_first_link.
9420 {tracer, Tracer}:
9422 Specifies where to send the trace messages. Tracer must be
9423 the process identifier of a local process or the port iden‐
9424 tifier of a local port.
9425 {tracer, TracerModule, TracerState}:
9427 Specifies that a tracer module is to be called instead of
9428 sending a trace message. The tracer module can then ignore
9429 or change the trace message. For more details on how to
9430 write a tracer module, see erl_tracer(3).
9431 If no tracer is specified, the calling process receives all the
9433 trace messages.
9434 The effect of combining set_on_first_link with set_on_link is
9436 the same as set_on_first_link alone. Likewise for set_on_spawn
9437 and set_on_first_spawn.
9438 The tracing process receives the trace messages described in the
9440 following list. Pid is the process identifier of the traced
9441 process in which the traced event has occurred. The third tuple
9442 element is the message tag.
9443 If flag timestamp, strict_monotonic_timestamp, or mono‐
9445 tonic_timestamp is specified, the first tuple element is
9446 trace_ts instead, and the time stamp is added as an extra ele‐
9447 ment last in the message tuple. If multiple time stamp flags are
9448 passed, timestamp has precedence over strict_monotonic_time‐
9449 stamp, which in turn has precedence over monotonic_timestamp.
9450 All time stamp flags are remembered, so if two are passed and
9451 the one with highest precedence later is disabled, the other one
9452 becomes active.
9453 Trace messages:
9455 {trace, PidPort, send, Msg, To}:
9457 When PidPort sends message Msg to process To.
9458 {trace, PidPort, send_to_non_existing_process, Msg, To}:
9460 When PidPort sends message Msg to the non-existing process
9461 To.
9462 {trace, PidPort, 'receive', Msg}:
9464 When PidPort receives message Msg. If Msg is set to time-
9465 out, a receive statement can have timed out, or the process
9466 received a message with the payload timeout.
9467 {trace, Pid, call, {M, F, Args}}:
9469 When Pid calls a traced function. The return values of calls
9470 are never supplied, only the call and its arguments.
9471 Trace flag arity can be used to change the contents of this
9473 message, so that Arity is specified instead of Args.
9474 {trace, Pid, return_to, {M, F, Arity}}:
9476 When Pid returns to the specified function. This trace mes‐
9477 sage is sent if both the flags call and return_to are set,
9478 and the function is set to be traced on local function
9479 calls. The message is only sent when returning from a chain
9480 of tail recursive function calls, where at least one call
9481 generated a call trace message (that is, the functions match
9482 specification matched, and {message, false} was not an
9483 action).
9484 {trace, Pid, return_from, {M, F, Arity}, ReturnValue}:
9486 When Pid returns from the specified function. This trace
9487 message is sent if flag call is set, and the function has a
9488 match specification with a return_trace or exception_trace
9489 action.
9490 {trace, Pid, exception_from, {M, F, Arity}, {Class, Value}}:
9492 When Pid exits from the specified function because of an
9493 exception. This trace message is sent if flag call is set,
9494 and the function has a match specification with an excep‐
9495 tion_trace action.
9496 {trace, Pid, spawn, Pid2, {M, F, Args}}:
9498 When Pid spawns a new process Pid2 with the specified func‐
9499 tion call as entry point.
9500 Args is supposed to be the argument list, but can be any
9502 term if the spawn is erroneous.
9503 {trace, Pid, spawned, Pid2, {M, F, Args}}:
9505 When Pid is spawned by process Pid2 with the specified func‐
9506 tion call as entry point.
9507 Args is supposed to be the argument list, but can be any
9509 term if the spawn is erroneous.
9510 {trace, Pid, exit, Reason}:
9512 When Pid exits with reason Reason.
9513 {trace, PidPort, register, RegName}:
9515 When PidPort gets the name RegName registered.
9516 {trace, PidPort, unregister, RegName}:
9518 When PidPort gets the name RegName unregistered. This is
9519 done automatically when a registered process or port exits.
9520 {trace, Pid, link, Pid2}:
9522 When Pid links to a process Pid2.
9523 {trace, Pid, unlink, Pid2}:
9525 When Pid removes the link from a process Pid2.
9526 {trace, PidPort, getting_linked, Pid2}:
9528 When PidPort gets linked to a process Pid2.
9529 {trace, PidPort, getting_unlinked, Pid2}:
9531 When PidPort gets unlinked from a process Pid2.
9532 {trace, Pid, exit, Reason}:
9534 When Pid exits with reason Reason.
9535 {trace, Port, open, Pid, Driver}:
9537 When Pid opens a new port Port with the running Driver.
9538 Driver is the name of the driver as an atom.
9540 {trace, Port, closed, Reason}:
9542 When Port closes with Reason.
9543 {trace, Pid, in | in_exiting, {M, F, Arity} | 0}:
9545 When Pid is scheduled to run. The process runs in function
9546 {M, F, Arity}. On some rare occasions, the current function
9547 cannot be determined, then the last element is 0.
9548 {trace, Pid, out | out_exiting | out_exited, {M, F, Arity} |
9550 0}:
9551 When Pid is scheduled out. The process was running in func‐
9552 tion {M, F, Arity}. On some rare occasions, the current
9553 function cannot be determined, then the last element is 0.
9554 {trace, Port, in, Command | 0}:
9556 When Port is scheduled to run. Command is the first thing
9557 the port will execute, it can however run several commands
9558 before being scheduled out. On some rare occasions, the cur‐
9559 rent function cannot be determined, then the last element is
9560 0.
9561 The possible commands are call, close, command, connect,
9563 control, flush, info, link, open, and unlink.
9564 {trace, Port, out, Command | 0}:
9566 When Port is scheduled out. The last command run was Com‐
9567 mand. On some rare occasions, the current function cannot be
9568 determined, then the last element is 0. Command can contain
9569 the same commands as in
9570 {trace, Pid, gc_minor_start, Info}:
9572 Sent when a young garbage collection is about to be started.
9575 Info is a list of two-element tuples, where the first ele‐
9576 ment is a key, and the second is the value. Do not depend on
9577 any order of the tuples. The following keys are defined:
9578 heap_size:
9580 The size of the used part of the heap.
9581 heap_block_size:
9583 The size of the memory block used for storing the heap and
9584 the stack.
9585 old_heap_size:
9587 The size of the used part of the old heap.
9588 old_heap_block_size:
9590 The size of the memory block used for storing the old
9591 heap.
9592 stack_size:
9594 The size of the stack.
9595 recent_size:
9597 The size of the data that survived the previous garbage
9598 collection.
9599 mbuf_size:
9601 The combined size of message buffers associated with the
9602 process.
9603 bin_vheap_size:
9605 The total size of unique off-heap binaries referenced from
9606 the process heap.
9607 bin_vheap_block_size:
9609 The total size of binaries allowed in the virtual heap in
9610 the process before doing a garbage collection.
9611 bin_old_vheap_size:
9613 The total size of unique off-heap binaries referenced from
9614 the process old heap.
9615 bin_old_vheap_block_size:
9617 The total size of binaries allowed in the virtual old heap
9618 in the process before doing a garbage collection.
9619 All sizes are in words.
9621 {trace, Pid, gc_max_heap_size, Info}:
9623 Sent when the max_heap_size is reached during garbage col‐
9624 lection. Info contains the same kind of list as in message
9625 gc_start, but the sizes reflect the sizes that triggered
9626 max_heap_size to be reached.
9627 {trace, Pid, gc_minor_end, Info}:
9629 Sent when young garbage collection is finished. Info con‐
9630 tains the same kind of list as in message gc_minor_start,
9631 but the sizes reflect the new sizes after garbage collec‐
9632 tion.
9633 {trace, Pid, gc_major_start, Info}:
9635 Sent when fullsweep garbage collection is about to be
9636 started. Info contains the same kind of list as in message
9637 gc_minor_start.
9638 {trace, Pid, gc_major_end, Info}:
9640 Sent when fullsweep garbage collection is finished. Info
9641 contains the same kind of list as in message gc_minor_start,
9642 but the sizes reflect the new sizes after a fullsweep
9643 garbage collection.
9644 If the tracing process/port dies or the tracer module returns
9646 remove, the flags are silently removed.
9647 Each process can only be traced by one tracer. Therefore,
9649 attempts to trace an already traced process fail.
9650 Returns a number indicating the number of processes that matched
9652 PidPortSpec. If PidPortSpec is a process identifier, the return
9653 value is 1. If PidPortSpec is all or existing, the return value
9654 is the number of processes running. If PidPortSpec is new, the
9655 return value is 0.
9656 Failure: badarg if the specified arguments are not supported.
9658 For example, cpu_timestamp is not supported on all platforms.
9659 erlang:trace_delivered(Tracee) -> Ref
9661 Types:
9663 Tracee = pid() | all
9665 Ref = reference()
9666 The delivery of trace messages (generated by erlang:trace/3,
9668 seq_trace(3), or erlang:system_profile/2) is dislocated on the
9669 time-line compared to other events in the system. If you know
9670 that Tracee has passed some specific point in its execution, and
9671 you want to know when at least all trace messages corresponding
9672 to events up to this point have reached the tracer, use
9673 erlang:trace_delivered(Tracee).
9674 When it is guaranteed that all trace messages are delivered to
9676 the tracer up to the point that Tracee reached at the time of
9677 the call to erlang:trace_delivered(Tracee), then a {trace_deliv‐
9678 ered, Tracee, Ref} message is sent to the caller of
9679 erlang:trace_delivered(Tracee) .
9680 Notice that message trace_delivered does not imply that trace
9682 messages have been delivered. Instead it implies that all trace
9683 messages that are to be delivered have been delivered. It is not
9684 an error if Tracee is not, and has not been traced by someone,
9685 but if this is the case, no trace messages have been delivered
9686 when the trace_delivered message arrives.
9687 Notice that Tracee must refer to a process currently or previ‐
9689 ously existing on the same node as the caller of
9690 erlang:trace_delivered(Tracee) resides on. The special Tracee
9691 atom all denotes all processes that currently are traced in the
9692 node.
9693 When used together with a Tracer Module, any message sent in
9695 the trace callback is guaranteed to have reached its recipient
9696 before the trace_delivered message is sent.
9697 Example: Process A is Tracee, port B is tracer, and process C is
9699 the port owner of B. C wants to close B when A exits. To ensure
9700 that the trace is not truncated, C can call erlang:trace_deliv‐
9701 ered(A) when A exits, and wait for message {trace_delivered, A,
9702 Ref} before closing B.
9703 Failure: badarg if Tracee does not refer to a process (dead or
9705 alive) on the same node as the caller of erlang:trace_deliv‐
9706 ered(Tracee) resides on.
9707 erlang:trace_info(PidPortFuncEvent, Item) -> Res
9709 Types:
9711 PidPortFuncEvent =
9713 pid() |
9714 port() |
9715 new |
9716 new_processes |
9717 new_ports |
9718 {Module, Function, Arity} |
9719 on_load |
9720 send |
9721 'receive'
9722 Module = module()
9723 Function = atom()
9724 Arity = arity()
9725 Item =
9726 flags |
9727 tracer |
9728 traced |
9729 match_spec |
9730 meta |
9731 meta_match_spec |
9732 call_count |
9733 call_time |
9734 all
9735 Res = trace_info_return()
9736 trace_info_return() =
9737 undefined |
9738 {flags, [trace_info_flag()]} |
9739 {tracer, pid() | port() | []} |
9740 {tracer, module(), term()} |
9741 trace_info_item_result() |
9742 {all, [trace_info_item_result()] | false | undefined}
9743 trace_info_item_result() =
9744 {traced, global | local | false | undefined} |
9745 {match_spec, trace_match_spec() | false | undefined} |
9746 {meta, pid() | port() | false | undefined | []} |
9747 {meta, module(), term()} |
9748 {meta_match_spec, trace_match_spec() | false | undefined} |
9749 {call_count, integer() >= 0 | boolean() | undefined} |
9750 {call_time,
9751 [{pid(),
9752 integer() >= 0,
9753 integer() >= 0,
9754 integer() >= 0}] |
9755 boolean() |
9756 undefined}
9757 trace_info_flag() =
9758 send |
9759 'receive' |
9760 set_on_spawn |
9761 call |
9762 return_to |
9763 procs |
9764 set_on_first_spawn |
9765 set_on_link |
9766 running |
9767 garbage_collection |
9768 timestamp |
9769 monotonic_timestamp |
9770 strict_monotonic_timestamp |
9771 arity
9772 trace_match_spec() =
9773 [{[term()] | '_' | match_variable(), [term()], [term()]}]
9774 match_variable() = atom()
9775 Approximation of '$1' | '$2' | '$3' | ...
9776 Returns trace information about a port, process, function, or
9778 event.
9779 To get information about a port or process, PidPortFuncEvent is
9781 to be a process identifier (pid), port identifier, or one of the
9782 atoms new, new_processes, or new_ports. The atom new or new_pro‐
9783 cesses means that the default trace state for processes to be
9784 created is returned. The atom new_ports means that the default
9785 trace state for ports to be created is returned.
9786 Valid Items for ports and processes:
9788 flags:
9790 Returns a list of atoms indicating what kind of traces is
9791 enabled for the process. The list is empty if no traces are
9792 enabled, and one or more of the followings atoms if traces
9793 are enabled: send, 'receive', set_on_spawn, call, return_to,
9794 procs, ports, set_on_first_spawn, set_on_link, running, run‐
9795 ning_procs, running_ports, silent, exiting, monotonic_time‐
9796 stamp, strict_monotonic_timestamp, garbage_collection, time‐
9797 stamp, and arity. The order is arbitrary.
9798 tracer:
9800 Returns the identifier for process, port, or a tuple con‐
9801 taining the tracer module and tracer state tracing this
9802 process. If this process is not traced, the return value is
9803 [].
9804 To get information about a function, PidPortFuncEvent is to be
9806 the three-element tuple {Module, Function, Arity} or the atom
9807 on_load. No wildcards are allowed. Returns undefined if the
9808 function does not exist, or false if the function is not traced.
9809 If PidPortFuncEvent is on_load, the information returned refers
9810 to the default value for code that will be loaded.
9811 Valid Items for functions:
9813 traced:
9815 Returns global if this function is traced on global function
9816 calls, local if this function is traced on local function
9817 calls (that is, local and global function calls), and false
9818 if local or global function calls are not traced.
9819 match_spec:
9821 Returns the match specification for this function, if it has
9822 one. If the function is locally or globally traced but has
9823 no match specification defined, the returned value is [].
9824 meta:
9826 Returns the meta-trace tracer process, port, or trace module
9827 for this function, if it has one. If the function is not
9828 meta-traced, the returned value is false. If the function is
9829 meta-traced but has once detected that the tracer process is
9830 invalid, the returned value is [].
9831 meta_match_spec:
9833 Returns the meta-trace match specification for this func‐
9834 tion, if it has one. If the function is meta-traced but has
9835 no match specification defined, the returned value is [].
9836 call_count:
9838 Returns the call count value for this function or true for
9839 the pseudo function on_load if call count tracing is active.
9840 Otherwise false is returned.
9841 See also erlang:trace_pattern/3.
9843 call_time:
9845 Returns the call time values for this function or true for
9846 the pseudo function on_load if call time tracing is active.
9847 Otherwise false is returned. The call time values returned,
9848 [{Pid, Count, S, Us}], is a list of each process that exe‐
9849 cuted the function and its specific counters.
9850 See also erlang:trace_pattern/3.
9852 all:
9854 Returns a list containing the {Item, Value} tuples for all
9855 other items, or returns false if no tracing is active for
9856 this function.
9857 To get information about an event, PidPortFuncEvent is to be one
9859 of the atoms send or 'receive'.
9860 One valid Item for events exists:
9862 match_spec:
9864 Returns the match specification for this event, if it has
9865 one, or true if no match specification has been set.
9866 The return value is {Item, Value}, where Value is the requested
9868 information as described earlier. If a pid for a dead process
9869 was specified, or the name of a non-existing function, Value is
9870 undefined.
9871 erlang:trace_pattern(MFA, MatchSpec) -> integer() >= 0
9873 Types:
9875 MFA = trace_pattern_mfa() | send | 'receive'
9877 MatchSpec =
9878 (MatchSpecList :: trace_match_spec()) |
9879 boolean() |
9880 restart |
9881 pause
9882 trace_pattern_mfa() = {atom(), atom(), arity() | '_'} | on_load
9883 trace_match_spec() =
9884 [{[term()] | '_' | match_variable(), [term()], [term()]}]
9885 match_variable() = atom()
9886 Approximation of '$1' | '$2' | '$3' | ...
9887 The same as erlang:trace_pattern(Event, MatchSpec, []), retained
9889 for backward compatibility.
9890 erlang:trace_pattern(MFA :: send, MatchSpec, FlagList :: []) ->
9892 integer() >= 0
9893 Types:
9895 MatchSpec = (MatchSpecList :: trace_match_spec()) | boolean()
9897 trace_match_spec() =
9898 [{[term()] | '_' | match_variable(), [term()], [term()]}]
9899 match_variable() = atom()
9900 Approximation of '$1' | '$2' | '$3' | ...
9901 Sets trace pattern for message sending. Must be combined with
9903 erlang:trace/3 to set the send trace flag for one or more pro‐
9904 cesses. By default all messages sent from send traced processes
9905 are traced. To limit traced send events based on the message
9906 content, the sender and/or the receiver, use erlang:trace_pat‐
9907 tern/3.
9908 Argument MatchSpec can take the following forms:
9910 MatchSpecList:
9912 A list of match specifications. The matching is done on the
9913 list [Receiver, Msg]. Receiver is the process or port iden‐
9914 tity of the receiver and Msg is the message term. The pid of
9915 the sending process can be accessed with the guard function
9916 self/0. An empty list is the same as true. For more informa‐
9917 tion, see section Match Specifications in Erlang in the
9918 User's Guide.
9919 true:
9921 Enables tracing for all sent messages (from send traced pro‐
9922 cesses). Any match specification is removed. This is the
9923 default.
9924 false:
9926 Disables tracing for all sent messages. Any match specifica‐
9927 tion is removed.
9928 Argument FlagList must be [] for send tracing.
9930 The return value is always 1.
9932 Examples:
9934 Only trace messages to a specific process Pid:
9936 > erlang:trace_pattern(send, [{[Pid, '_'],[],[]}], []).
9938 1
9939 Only trace messages matching {reply, _}:
9941 > erlang:trace_pattern(send, [{['_', {reply,'_'}],[],[]}], []).
9943 1
9944 Only trace messages sent to the sender itself:
9946 > erlang:trace_pattern(send, [{['$1', '_'],[{'=:=','$1',{self}}],[]}], []).
9948 1
9949 Only trace messages sent to other nodes:
9951 > erlang:trace_pattern(send, [{['$1', '_'],[{'=/=',{node,'$1'},{node}}],[]}], []).
9953 1
9954 Note:
9956 A match specification for send trace can use all guard and body
9957 functions except caller.
9958 erlang:trace_pattern(MFA :: 'receive', MatchSpec, FlagList :: []) ->
9961 integer() >= 0
9962 Types:
9964 MatchSpec = (MatchSpecList :: trace_match_spec()) | boolean()
9966 trace_match_spec() =
9967 [{[term()] | '_' | match_variable(), [term()], [term()]}]
9968 match_variable() = atom()
9969 Approximation of '$1' | '$2' | '$3' | ...
9970 Sets trace pattern for message receiving. Must be combined with
9972 erlang:trace/3 to set the 'receive' trace flag for one or more
9973 processes. By default all messages received by 'receive' traced
9974 processes are traced. To limit traced receive events based on
9975 the message content, the sender and/or the receiver, use
9976 erlang:trace_pattern/3.
9977 Argument MatchSpec can take the following forms:
9979 MatchSpecList:
9981 A list of match specifications. The matching is done on the
9982 list [Node, Sender, Msg]. Node is the node name of the
9983 sender. Sender is the process or port identity of the
9984 sender, or the atom undefined if the sender is not known
9985 (which can be the case for remote senders). Msg is the mes‐
9986 sage term. The pid of the receiving process can be accessed
9987 with the guard function self/0. An empty list is the same as
9988 true. For more information, see section Match Specifica‐
9989 tions in Erlang in the User's Guide.
9990 true:
9992 Enables tracing for all received messages (to 'receive'
9993 traced processes). Any match specification is removed. This
9994 is the default.
9995 false:
9997 Disables tracing for all received messages. Any match speci‐
9998 fication is removed.
9999 Argument FlagList must be [] for receive tracing.
10001 The return value is always 1.
10003 Examples:
10005 Only trace messages from a specific process Pid:
10007 > erlang:trace_pattern('receive', [{['_',Pid, '_'],[],[]}], []).
10009 1
10010 Only trace messages matching {reply, _}:
10012 > erlang:trace_pattern('receive', [{['_','_', {reply,'_'}],[],[]}], []).
10014 1
10015 Only trace messages from other nodes:
10017 > erlang:trace_pattern('receive', [{['$1', '_', '_'],[{'=/=','$1',{node}}],[]}], []).
10019 1
10020 Note:
10022 A match specification for 'receive' trace can use all guard and
10023 body functions except caller, is_seq_trace, get_seq_token,
10024 set_seq_token, enable_trace, disable_trace, trace, silent, and
10025 process_dump.
10026 erlang:trace_pattern(MFA, MatchSpec, FlagList) ->
10029 integer() >= 0
10030 Types:
10032 MFA = trace_pattern_mfa()
10034 MatchSpec =
10035 (MatchSpecList :: trace_match_spec()) |
10036 boolean() |
10037 restart |
10038 pause
10039 FlagList = [trace_pattern_flag()]
10040 trace_pattern_mfa() = {atom(), atom(), arity() | '_'} | on_load
10041 trace_match_spec() =
10042 [{[term()] | '_' | match_variable(), [term()], [term()]}]
10043 trace_pattern_flag() =
10044 global |
10045 local |
10046 meta |
10047 {meta, Pid :: pid()} |
10048 {meta, TracerModule :: module(), TracerState :: term()} |
10049 call_count |
10050 call_time
10051 match_variable() = atom()
10052 Approximation of '$1' | '$2' | '$3' | ...
10053 Enables or disables call tracing for one or more functions. Must
10055 be combined with erlang:trace/3 to set the call trace flag for
10056 one or more processes.
10057 Conceptually, call tracing works as follows. Inside the Erlang
10059 virtual machine, a set of processes and a set of functions are
10060 to be traced. If a traced process calls a traced function, the
10061 trace action is taken. Otherwise, nothing happens.
10062 To add or remove one or more processes to the set of traced pro‐
10064 cesses, use erlang:trace/3.
10065 To add or remove functions to the set of traced functions, use
10067 erlang:trace_pattern/3.
10068 The BIF erlang:trace_pattern/3 can also add match specifications
10070 to a function. A match specification comprises a pattern that
10071 the function arguments must match, a guard expression that must
10072 evaluate to true, and an action to be performed. The default
10073 action is to send a trace message. If the pattern does not match
10074 or the guard fails, the action is not executed.
10075 Argument MFA is to be a tuple, such as {Module, Function,
10077 Arity}, or the atom on_load (described below). It can be the
10078 module, function, and arity for a function (or a BIF in any mod‐
10079 ule). The atom '_' can be used as a wildcard in any of the fol‐
10080 lowing ways:
10081 {Module,Function,'_'}:
10083 All functions of any arity named Function in module Module.
10084 {Module,'_','_'}:
10086 All functions in module Module.
10087 {'_','_','_'}:
10089 All functions in all loaded modules.
10090 Other combinations, such as {Module,'_',Arity}, are not allowed.
10092 Local functions match wildcards only if option local is in
10093 FlagList.
10094 If argument MFA is the atom on_load, the match specification and
10096 flag list are used on all modules that are newly loaded.
10097 Argument MatchSpec can take the following forms:
10099 false:
10101 Disables tracing for the matching functions. Any match spec‐
10102 ification is removed.
10103 true:
10105 Enables tracing for the matching functions. Any match speci‐
10106 fication is removed.
10107 MatchSpecList:
10109 A list of match specifications. An empty list is equivalent
10110 to true. For a description of match specifications, see sec‐
10111 tion Match Specifications in Erlang in the User's Guide.
10112 restart:
10114 For the FlagList options call_count and call_time: restarts
10115 the existing counters. The behavior is undefined for other
10116 FlagList options.
10117 pause:
10119 For the FlagList options call_count and call_time: pauses
10120 the existing counters. The behavior is undefined for other
10121 FlagList options.
10122 Parameter FlagList is a list of options. The following are the
10124 valid options:
10125 global:
10127 Turns on or off call tracing for global function calls (that
10128 is, calls specifying the module explicitly). Only exported
10129 functions match and only global calls generate trace mes‐
10130 sages. This is the default.
10131 local:
10133 Turns on or off call tracing for all types of function
10134 calls. Trace messages are sent whenever any of the specified
10135 functions are called, regardless of how they are called. If
10136 flag return_to is set for the process, a return_to message
10137 is also sent when this function returns to its caller.
10138 meta | {meta, Pid} | {meta, TracerModule, TracerState}:
10140 Turns on or off meta-tracing for all types of function
10141 calls. Trace messages are sent to the tracer whenever any of
10142 the specified functions are called. If no tracer is speci‐
10143 fied, self() is used as a default tracer process.
10144 Meta-tracing traces all processes and does not care about
10146 the process trace flags set by erlang:trace/3, the trace
10147 flags are instead fixed to [call, timestamp].
10148 The match specification function {return_trace} works with
10150 meta-trace and sends its trace message to the same tracer.
10151 call_count:
10153 Starts (MatchSpec == true) or stops (MatchSpec == false)
10154 call count tracing for all types of function calls. For
10155 every function, a counter is incremented when the function
10156 is called, in any process. No process trace flags need to be
10157 activated.
10158 If call count tracing is started while already running, the
10160 count is restarted from zero. To pause running counters, use
10161 MatchSpec == pause. Paused and running counters can be
10162 restarted from zero with MatchSpec == restart.
10163 To read the counter value, use erlang:trace_info/2.
10165 call_time:
10167 Starts (MatchSpec == true) or stops (MatchSpec == false)
10168 call time tracing for all types of function calls. For every
10169 function, a counter is incremented when the function is
10170 called. Time spent in the function is accumulated in two
10171 other counters, seconds and microseconds. The counters are
10172 stored for each call traced process.
10173 If call time tracing is started while already running, the
10175 count and time restart from zero. To pause running counters,
10176 use MatchSpec == pause. Paused and running counters can be
10177 restarted from zero with MatchSpec == restart.
10178 To read the counter value, use erlang:trace_info/2.
10180 The options global and local are mutually exclusive, and global
10182 is the default (if no options are specified). The options
10183 call_count and meta perform a kind of local tracing, and cannot
10184 be combined with global. A function can be globally or locally
10185 traced. If global tracing is specified for a set of functions,
10186 then local, meta, call time, and call count tracing for the
10187 matching set of local functions is disabled, and conversely.
10188 When disabling trace, the option must match the type of trace
10190 set on the function. That is, local tracing must be disabled
10191 with option local and global tracing with option global (or no
10192 option), and so on.
10193 Part of a match specification list cannot be changed directly.
10195 If a function has a match specification, it can be replaced with
10196 a new one. To change an existing match specification, use the
10197 BIF erlang:trace_info/2 to retrieve the existing match specifi‐
10198 cation.
10199 Returns the number of functions matching argument MFA. This is
10201 zero if none matched.
10202 trunc(Number) -> integer()
10204 Types:
10206 Number = number()
10208 Returns an integer by truncating Number, for example:
10210 > trunc(5.5).
10212 5
10213 Allowed in guard tests.
10215 tuple_size(Tuple) -> integer() >= 0
10217 Types:
10219 Tuple = tuple()
10221 Returns an integer that is the number of elements in Tuple, for
10223 example:
10224 > tuple_size({morni, mulle, bwange}).
10226 3
10227 Allowed in guard tests.
10229 tuple_to_list(Tuple) -> [term()]
10231 Types:
10233 Tuple = tuple()
10235 Returns a list corresponding to Tuple. Tuple can contain any
10237 Erlang terms. Example:
10238 > tuple_to_list({share, {'Ericsson_B', 163}}).
10240 [share,{'Ericsson_B',163}]
10241 erlang:unique_integer() -> integer()
10243 Generates and returns an integer unique on current runtime sys‐
10245 tem instance. The same as calling erlang:unique_integer([]).
10246 erlang:unique_integer(ModifierList) -> integer()
10248 Types:
10250 ModifierList = [Modifier]
10252 Modifier = positive | monotonic
10253 Generates and returns an integer unique on current runtime sys‐
10255 tem instance. The integer is unique in the sense that this BIF,
10256 using the same set of modifiers, does not return the same inte‐
10257 ger more than once on the current runtime system instance. Each
10258 integer value can of course be constructed by other means.
10259 By default, when [] is passed as ModifierList, both negative and
10261 positive integers can be returned. This to use the range of
10262 integers that do not need heap memory allocation as much as pos‐
10263 sible. By default the returned integers are also only guaranteed
10264 to be unique, that is, any returned integer can be smaller or
10265 larger than previously returned integers.
10266 Modifiers:
10268 positive:
10270 Returns only positive integers.
10271 Notice that by passing the positive modifier you will get
10273 heap allocated integers (bignums) quicker.
10274 monotonic:
10276 Returns strictly monotonically increasing integers corre‐
10277 sponding to creation time. That is, the integer returned is
10278 always larger than previously returned integers on the cur‐
10279 rent runtime system instance.
10280 These values can be used to determine order between events
10282 on the runtime system instance. That is, if both X =
10283 erlang:unique_integer([monotonic]) and Y =
10284 erlang:unique_integer([monotonic]) are executed by different
10285 processes (or the same process) on the same runtime system
10286 instance and X < Y, we know that X was created before Y.
10287 Warning:
10289 Strictly monotonically increasing values are inherently quite
10290 expensive to generate and scales poorly. This is because the
10291 values need to be synchronized between CPU cores. That is, do
10292 not pass the monotonic modifier unless you really need
10293 strictly monotonically increasing values.
10294 All valid Modifiers can be combined. Repeated (valid) Modifiers
10297 in the ModifierList are ignored.
10298 Note:
10300 The set of integers returned by erlang:unique_integer/1 using
10301 different sets of Modifiers will overlap. For example, by call‐
10302 ing unique_integer([monotonic]), and unique_integer([positive,
10303 monotonic]) repeatedly, you will eventually see some integers
10304 that are returned by both calls.
10305 Failures:
10308 badarg:
10310 if ModifierList is not a proper list.
10311 badarg:
10313 if Modifier is not a valid modifier.
10314 erlang:universaltime() -> DateTime
10316 Types:
10318 DateTime = calendar:datetime()
10320 Returns the current date and time according to Universal Time
10322 Coordinated (UTC) in the form {{Year, Month, Day}, {Hour,
10323 Minute, Second}} if supported by the underlying OS. Otherwise
10324 erlang:universaltime() is equivalent to erlang:localtime().
10325 Example:
10326 > erlang:universaltime().
10328 {{1996,11,6},{14,18,43}}
10329 erlang:universaltime_to_localtime(Universaltime) -> Localtime
10331 Types:
10333 Localtime = Universaltime = calendar:datetime()
10335 Converts Universal Time Coordinated (UTC) date and time to local
10337 date and time in the form {{Year, Month, Day}, {Hour, Minute,
10338 Second}} if supported by the underlying OS. Otherwise no conver‐
10339 sion is done, and Universaltime is returned. Example:
10340 > erlang:universaltime_to_localtime({{1996,11,6},{14,18,43}}).
10342 {{1996,11,7},{15,18,43}}
10343 Failure: badarg if Universaltime denotes an invalid date and
10345 time.
10346 unlink(Id) -> true
10348 Types:
10350 Id = pid() | port()
10352 Removes the link, if there is one, between the calling process
10354 and the process or port referred to by Id.
10355 Returns true and does not fail, even if there is no link to Id,
10357 or if Id does not exist.
10358 Once unlink(Id) has returned, it is guaranteed that the link
10360 between the caller and the entity referred to by Id has no
10361 effect on the caller in the future (unless the link is setup
10362 again). If the caller is trapping exits, an {'EXIT', Id, _} mes‐
10363 sage from the link can have been placed in the caller's message
10364 queue before the call.
10365 Notice that the {'EXIT', Id, _} message can be the result of the
10367 link, but can also be the result of Id calling exit/2. There‐
10368 fore, it can be appropriate to clean up the message queue when
10369 trapping exits after the call to unlink(Id), as follows:
10370 unlink(Id),
10372 receive
10373 {'EXIT', Id, _} ->
10374 true
10375 after 0 ->
10376 true
10377 end
10378 Note:
10380 Before Erlang/OTP R11B (ERTS 5.5) unlink/1 behaved completely
10381 asynchronously, that is, the link was active until the "unlink
10382 signal" reached the linked entity. This had an undesirable
10383 effect, as you could never know when you were guaranteed not to
10384 be effected by the link.
10385 The current behavior can be viewed as two combined operations:
10387 asynchronously send an "unlink signal" to the linked entity and
10388 ignore any future results of the link.
10389 unregister(RegName) -> true
10392 Types:
10394 RegName = atom()
10396 Removes the registered name RegName associated with a process
10398 identifier or a port identifier, for example:
10399 > unregister(db).
10401 true
10402 Users are advised not to unregister system processes.
10404 Failure: badarg if RegName is not a registered name.
10406 whereis(RegName) -> pid() | port() | undefined
10408 Types:
10410 RegName = atom()
10412 Returns the process identifier or port identifier with the reg‐
10414 istered name RegName. Returns undefined if the name is not reg‐
10415 istered. Example:
10416 > whereis(db).
10418 <0.43.0>
10419 erlang:yield() -> true
10421 Voluntarily lets other processes (if any) get a chance to exe‐
10423 cute. Using this function is similar to receive after 1 -> ok
10424 end, except that yield() is faster.
10425 Warning:
10427 There is seldom or never any need to use this BIF as other pro‐
10428 cesses have a chance to run in another scheduler thread anyway.
10429 Using this BIF without a thorough grasp of how the scheduler
10430 works can cause performance degradation.
10431Ericsson AB erts 10.3.5.2 erlang(3)