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 ext_iovec() = iovec()
32 A term of type iovec(), structured according to the Erlang
34 external term format.
35 iovec() = [binary()]
37 A list of binaries. This datatype is useful to use together with
39 enif_inspect_iovec.
40 message_queue_data() = off_heap | on_heap
42 See process_flag(message_queue_data, MQD).
44 timestamp() =
46 {MegaSecs :: integer() >= 0,
47 Secs :: integer() >= 0,
48 MicroSecs :: integer() >= 0}
49 See erlang:timestamp/0.
51 time_unit() =
53 integer() >= 1 |
54 second | millisecond | microsecond | nanosecond | native |
55 perf_counter |
56 deprecated_time_unit()
57 Supported time unit representations:
59 PartsPerSecond :: integer() >= 1:
61 Time unit expressed in parts per second. That is, the time
62 unit equals 1/PartsPerSecond second.
63 second:
65 Symbolic representation of the time unit represented by the
66 integer 1.
67 millisecond:
69 Symbolic representation of the time unit represented by the
70 integer 1000.
71 microsecond:
73 Symbolic representation of the time unit represented by the
74 integer 1000_000.
75 nanosecond:
77 Symbolic representation of the time unit represented by the
78 integer 1000_000_000.
79 native:
81 Symbolic representation of the native time unit used by the
82 Erlang runtime system.
83 The native time unit is determined at runtime system start,
85 and remains the same until the runtime system terminates. If
86 a runtime system is stopped and then started again (even on
87 the same machine), the native time unit of the new runtime
88 system instance can differ from the native time unit of the
89 old runtime system instance.
90 One can get an approximation of the native time unit by
92 calling erlang:convert_time_unit(1, second, native). The
93 result equals the number of whole native time units per sec‐
94 ond. If the number of native time units per second does not
95 add up to a whole number, the result is rounded downwards.
96 Note:
98 The value of the native time unit gives you more or less no
99 information about the quality of time values. It sets a limit
100 for the resolution and for the precision of time values, but
101 it gives no information about the accuracy of time values.
102 The resolution of the native time unit and the resolution of
103 time values can differ significantly.
104 perf_counter:
107 Symbolic representation of the performance counter time unit
108 used by the Erlang runtime system.
109 The perf_counter time unit behaves much in the same way as
111 the native time unit. That is, it can differ between runtime
112 restarts. To get values of this type, call
113 os:perf_counter/0.
114 deprecated_time_unit():
116 Deprecated symbolic representations kept for backwards-com‐
117 patibility.
118 The time_unit/0 type can be extended. To convert time values
120 between time units, use erlang:convert_time_unit/3.
121 deprecated_time_unit() =
123 seconds | milli_seconds | micro_seconds | nano_seconds
124 The time_unit() type also consist of the following deprecated
126 symbolic time units:
127 seconds:
129 Same as second.
130 milli_seconds:
132 Same as millisecond.
133 micro_seconds:
135 Same as microsecond.
136 nano_seconds:
138 Same as nanosecond.
139 dist_handle()
141 An opaque handle identifing a distribution channel.
143 nif_resource()
145 An opaque handle identifing a NIF resource object .
147 spawn_opt_option() =
149 link | monitor |
150 {priority, Level :: priority_level()} |
151 {fullsweep_after, Number :: integer() >= 0} |
152 {min_heap_size, Size :: integer() >= 0} |
153 {min_bin_vheap_size, VSize :: integer() >= 0} |
154 {max_heap_size, Size :: max_heap_size()} |
155 {message_queue_data, MQD :: message_queue_data()}
156 Options for spawn_opt().
158 priority_level() = low | normal | high | max
160 Process priority level. For more info see process_flag(priority,
162 Level)
163 max_heap_size() =
165 integer() >= 0 |
166 #{size => integer() >= 0,
167 kill => boolean(),
168 error_logger => boolean()}
169 Process max heap size configuration. For more info see
171 process_flag(max_heap_size, MaxHeapSize)
172 message_queue_data() = off_heap | on_heap
174 Process message queue data configuration. For more information,
176 see process_flag(message_queue_data, MQD)
177
179 abs(Float) -> float()
180 abs(Int) -> integer() >= 0
182 Types:
184 Int = integer()
186 Returns an integer or float that is the arithmetical absolute
188 value of Float or Int, for example:
189 > abs(-3.33).
191 3.33
192 > abs(-3).
193 3
194 Allowed in guard tests.
196 erlang:adler32(Data) -> integer() >= 0
198 Types:
200 Data = iodata()
202 Computes and returns the adler32 checksum for Data.
204 erlang:adler32(OldAdler, Data) -> integer() >= 0
206 Types:
208 OldAdler = integer() >= 0
210 Data = iodata()
211 Continues computing the adler32 checksum by combining the previ‐
213 ous checksum, OldAdler, with the checksum of Data.
214 The following code:
216 X = erlang:adler32(Data1),
218 Y = erlang:adler32(X,Data2).
219 assigns the same value to Y as this:
221 Y = erlang:adler32([Data1,Data2]).
223 erlang:adler32_combine(FirstAdler, SecondAdler, SecondSize) ->
225 integer() >= 0
226 Types:
228 FirstAdler = SecondAdler = SecondSize = integer() >= 0
230 Combines two previously computed adler32 checksums. This compu‐
232 tation requires the size of the data object for the second
233 checksum to be known.
234 The following code:
236 Y = erlang:adler32(Data1),
238 Z = erlang:adler32(Y,Data2).
239 assigns the same value to Z as this:
241 X = erlang:adler32(Data1),
243 Y = erlang:adler32(Data2),
244 Z = erlang:adler32_combine(X,Y,iolist_size(Data2)).
245 erlang:append_element(Tuple1, Term) -> Tuple2
247 Types:
249 Tuple1 = Tuple2 = tuple()
251 Term = term()
252 Returns a new tuple that has one element more than Tuple1, and
254 contains the elements in Tuple1 followed by Term as the last
255 element. Semantically equivalent to
256 list_to_tuple(tuple_to_list(Tuple1) ++ [Term]), but much faster.
257 Example:
258 > erlang:append_element({one, two}, three).
260 {one,two,three}
261 apply(Fun, Args) -> term()
263 Types:
265 Fun = function()
267 Args = [term()]
268 Calls a fun, passing the elements in Args as arguments.
270 If the number of elements in the arguments are known at compile
272 time, the call is better written as Fun(Arg1, Arg2, ... ArgN).
273 Warning:
275 Earlier, Fun could also be specified as {Module, Function},
276 equivalent to apply(Module, Function, Args). This use is depre‐
277 cated and will stop working in a future release.
278 apply(Module, Function, Args) -> term()
281 Types:
283 Module = module()
285 Function = atom()
286 Args = [term()]
287 Returns the result of applying Function in Module to Args. The
289 applied function must be exported from Module. The arity of the
290 function is the length of Args. Example:
291 > apply(lists, reverse, [[a, b, c]]).
293 [c,b,a]
294 > apply(erlang, atom_to_list, ['Erlang']).
295 "Erlang"
296 If the number of arguments are known at compile time, the call
298 is better written as Module:Function(Arg1, Arg2, ..., ArgN).
299 Failure: error_handler:undefined_function/3 is called if the
301 applied function is not exported. The error handler can be rede‐
302 fined (see process_flag/2). If error_handler is undefined, or if
303 the user has redefined the default error_handler so the replace‐
304 ment module is undefined, an error with reason undef is gener‐
305 ated.
306 atom_to_binary(Atom) -> binary()
308 Types:
310 Atom = atom()
312 The same as atom_to_binary(Atom, utf8).
314 atom_to_binary(Atom, Encoding) -> binary()
316 Types:
318 Atom = atom()
320 Encoding = latin1 | unicode | utf8
321 Returns a binary corresponding to the text representation of
323 Atom. If Encoding is latin1, one byte exists for each character
324 in the text representation. If Encoding is utf8 or unicode, the
325 characters are encoded using UTF-8 where characters may require
326 multiple bytes.
327 Note:
329 As from Erlang/OTP 20, atoms can contain any Unicode character
330 and atom_to_binary(Atom, latin1) may fail if the text represen‐
331 tation for Atom contains a Unicode character > 255.
332 Example:
335 > atom_to_binary('Erlang', latin1).
337 <<"Erlang">>
338 atom_to_list(Atom) -> string()
340 Types:
342 Atom = atom()
344 Returns a string corresponding to the text representation of
346 Atom, for example:
347 > atom_to_list('Erlang').
349 "Erlang"
350 binary_part(Subject, PosLen) -> binary()
352 Types:
354 Subject = binary()
356 PosLen = {Start :: integer() >= 0, Length :: integer()}
357 Extracts the part of the binary described by PosLen.
359 Negative length can be used to extract bytes at the end of a
361 binary, for example:
362 1> Bin = <<1,2,3,4,5,6,7,8,9,10>>.
364 2> binary_part(Bin,{byte_size(Bin), -5}).
365 <<6,7,8,9,10>>
366 Failure: badarg if PosLen in any way references outside the
368 binary.
369 Start is zero-based, that is:
371 1> Bin = <<1,2,3>>
373 2> binary_part(Bin,{0,2}).
374 <<1,2>>
375 For details about the PosLen semantics, see binary(3).
377 Allowed in guard tests.
379 binary_part(Subject, Start, Length) -> binary()
381 Types:
383 Subject = binary()
385 Start = integer() >= 0
386 Length = integer()
387 The same as binary_part(Subject, {Start, Length}).
389 Allowed in guard tests.
391 binary_to_atom(Binary) -> atom()
393 Types:
395 Binary = binary()
397 The same as binary_to_atom(Binary, utf8).
399 binary_to_atom(Binary, Encoding) -> atom()
401 Types:
403 Binary = binary()
405 Encoding = latin1 | unicode | utf8
406 Returns the atom whose text representation is Binary. If Encod‐
408 ing is utf8 or unicode, the binary must contain valid UTF-8
409 sequences.
410 Note:
412 As from Erlang/OTP 20, binary_to_atom(Binary, utf8) is capable
413 of encoding any Unicode character. Earlier versions would fail
414 if the binary contained Unicode characters > 255. For more
415 information about Unicode support in atoms, see the note on
416 UTF-8 encoded atoms in section "External Term Format" in the
417 User's Guide.
418 Examples:
421 > binary_to_atom(<<"Erlang">>, latin1).
423 > binary_to_atom(<<1024/utf8>>, utf8).
424 binary_to_existing_atom(Binary) -> atom()
426 Types:
428 Binary = binary()
430 The same as binary_to_existing_atom (Binary, utf8).
432 binary_to_existing_atom(Binary, Encoding) -> atom()
434 Types:
436 Binary = binary()
438 Encoding = latin1 | unicode | utf8
439 As binary_to_atom/2, but the atom must exist.
441 Failure: badarg if the atom does not exist.
443 Note:
445 Note that the compiler may optimize away atoms. For example, the
446 compiler will rewrite atom_to_list(some_atom) to "some_atom". If
447 that expression is the only mention of the atom some_atom in the
448 containing module, the atom will not be created when the module
449 is loaded, and a subsequent call to binary_to_exist‐
450 ing_atom(<<"some_atom">>, utf8) will fail.
451 binary_to_float(Binary) -> float()
454 Types:
456 Binary = binary()
458 Returns the float whose text representation is Binary, for exam‐
460 ple:
461 > binary_to_float(<<"2.2017764e+0">>).
463 2.2017764
464 Failure: badarg if Binary contains a bad representation of a
466 float.
467 binary_to_integer(Binary) -> integer()
469 Types:
471 Binary = binary()
473 Returns an integer whose text representation is Binary, for
475 example:
476 > binary_to_integer(<<"123">>).
478 123
479 Failure: badarg if Binary contains a bad representation of an
481 integer.
482 binary_to_integer(Binary, Base) -> integer()
484 Types:
486 Binary = binary()
488 Base = 2..36
489 Returns an integer whose text representation in base Base is
491 Binary, for example:
492 > binary_to_integer(<<"3FF">>, 16).
494 1023
495 Failure: badarg if Binary contains a bad representation of an
497 integer.
498 binary_to_list(Binary) -> [byte()]
500 Types:
502 Binary = binary()
504 Returns a list of integers corresponding to the bytes of Binary.
506 binary_to_list(Binary, Start, Stop) -> [byte()]
508 Types:
510 Binary = binary()
512 Start = Stop = integer() >= 1
513 1..byte_size(Binary)
514 As binary_to_list/1, but returns a list of integers correspond‐
516 ing to the bytes from position Start to position Stop in Binary.
517 The positions in the binary are numbered starting from 1.
518 Note:
520 The one-based indexing for binaries used by this function is
521 deprecated. New code is to use binary:bin_to_list/3 in STDLIB
522 instead. All functions in module binary consistently use zero-
523 based indexing.
524 binary_to_term(Binary) -> term()
527 Types:
529 Binary = ext_binary()
531 Returns an Erlang term that is the result of decoding binary
533 object Binary, which must be encoded according to the Erlang
534 external term format.
535 > Bin = term_to_binary(hello).
537 <<131,100,0,5,104,101,108,108,111>>
538 > hello = binary_to_term(Bin).
539 hello
540 Warning:
543 When decoding binaries from untrusted sources, consider using
544 binary_to_term/2 to prevent Denial of Service attacks.
545 See also term_to_binary/1 and binary_to_term/2.
548 binary_to_term(Binary, Opts) -> term() | {term(), Used}
550 Types:
552 Binary = ext_binary()
554 Opt = safe | used
555 Opts = [Opt]
556 Used = integer() >= 1
557 As binary_to_term/1, but takes these options:
559 safe:
561 Use this option when receiving binaries from an untrusted
562 source.
563 When enabled, it prevents decoding data that can be used to
565 attack the Erlang system. In the event of receiving unsafe
566 data, decoding fails with a badarg error.
567 This prevents creation of new atoms directly, creation of
569 new atoms indirectly (as they are embedded in certain struc‐
570 tures, such as process identifiers, refs, and funs), and
571 creation of new external function references. None of those
572 resources are garbage collected, so unchecked creation of
573 them can exhaust available memory.
574 > binary_to_term(<<131,100,0,5,"hello">>, [safe]).
576 ** exception error: bad argument
577 > hello.
578 hello
579 > binary_to_term(<<131,100,0,5,"hello">>, [safe]).
580 hello
581 used:
584 Changes the return value to {Term, Used} where Used is the
585 number of bytes actually read from Binary.
586 > Input = <<131,100,0,5,"hello","world">>.
588 <<131,100,0,5,104,101,108,108,111,119,111,114,108,100>>
589 > {Term, Used} = binary_to_term(Input, [used]).
590 {hello, 9}
591 > split_binary(Input, Used).
592 {<<131,100,0,5,104,101,108,108,111>>, <<"world">>}
593 Failure: badarg if safe is specified and unsafe data is decoded.
596 See also term_to_binary/1, binary_to_term/1, and list_to_exist‐
598 ing_atom/1.
599 bit_size(Bitstring) -> integer() >= 0
601 Types:
603 Bitstring = bitstring()
605 Returns an integer that is the size in bits of Bitstring, for
607 example:
608 > bit_size(<<433:16,3:3>>).
610 19
611 > bit_size(<<1,2,3>>).
612 24
613 Allowed in guard tests.
615 bitstring_to_list(Bitstring) -> [byte() | bitstring()]
617 Types:
619 Bitstring = bitstring()
621 Returns a list of integers corresponding to the bytes of Bit‐
623 string. If the number of bits in the binary is not divisible by
624 8, the last element of the list is a bitstring containing the
625 remaining 1-7 bits.
626 erlang:bump_reductions(Reductions) -> true
628 Types:
630 Reductions = integer() >= 1
632 This implementation-dependent function increments the reduction
634 counter for the calling process. In the Beam emulator, the
635 reduction counter is normally incremented by one for each func‐
636 tion and BIF call. A context switch is forced when the counter
637 reaches the maximum number of reductions for a process (2000
638 reductions in Erlang/OTP R12B).
639 Warning:
641 This BIF can be removed in a future version of the Beam machine
642 without prior warning. It is unlikely to be implemented in other
643 Erlang implementations.
644 byte_size(Bitstring) -> integer() >= 0
647 Types:
649 Bitstring = bitstring()
651 Returns an integer that is the number of bytes needed to contain
653 Bitstring. That is, if the number of bits in Bitstring is not
654 divisible by 8, the resulting number of bytes is rounded up.
655 Examples:
656 > byte_size(<<433:16,3:3>>).
658 3
659 > byte_size(<<1,2,3>>).
660 3
661 Allowed in guard tests.
663 erlang:cancel_timer(TimerRef) -> Result
665 Types:
667 TimerRef = reference()
669 Time = integer() >= 0
670 Result = Time | false
671 Cancels a timer. The same as calling erlang:cancel_timer(Timer‐
673 Ref, []).
674 erlang:cancel_timer(TimerRef, Options) -> Result | ok
676 Types:
678 TimerRef = reference()
680 Async = Info = boolean()
681 Option = {async, Async} | {info, Info}
682 Options = [Option]
683 Time = integer() >= 0
684 Result = Time | false
685 Cancels a timer that has been created by erlang:start_timer or
687 erlang:send_after. TimerRef identifies the timer, and was
688 returned by the BIF that created the timer.
689 Options:
691 {async, Async}:
693 Asynchronous request for cancellation. Async defaults to
694 false, which causes the cancellation to be performed syn‐
695 chronously. When Async is set to true, the cancel operation
696 is performed asynchronously. That is, cancel_timer() sends
697 an asynchronous request for cancellation to the timer ser‐
698 vice that manages the timer, and then returns ok.
699 {info, Info}:
701 Requests information about the Result of the cancellation.
702 Info defaults to true, which means the Result is given. When
703 Info is set to false, no information about the result of the
704 cancellation is given.
705 * When Async is false: if Info is true, the Result is
707 returned by erlang:cancel_timer(). otherwise ok is
708 returned.
709 * When Async is true: if Info is true, a message on the form
711 {cancel_timer, TimerRef, Result} is sent to the caller of
712 erlang:cancel_timer() when the cancellation operation has
713 been performed, otherwise no message is sent.
714 More Options may be added in the future.
716 If Result is an integer, it represents the time in milliseconds
718 left until the canceled timer would have expired.
719 If Result is false, a timer corresponding to TimerRef could not
721 be found. This can be either because the timer had expired,
722 already had been canceled, or because TimerRef never corre‐
723 sponded to a timer. Even if the timer had expired, it does not
724 tell you if the time-out message has arrived at its destination
725 yet.
726 Note:
728 The timer service that manages the timer can be co-located with
729 another scheduler than the scheduler that the calling process is
730 executing on. If so, communication with the timer service takes
731 much longer time than if it is located locally. If the calling
732 process is in critical path, and can do other things while wait‐
733 ing for the result of this operation, or is not interested in
734 the result of the operation, you want to use option {async,
735 true}. If using option {async, false}, the calling process
736 blocks until the operation has been performed.
737 See also erlang:send_after/4, erlang:start_timer/4, and
740 erlang:read_timer/2.
741 ceil(Number) -> integer()
743 Types:
745 Number = number()
747 Returns the smallest integer not less than Number. For example:
749 > ceil(5.5).
751 6
752 Allowed in guard tests.
754 check_old_code(Module) -> boolean()
756 Types:
758 Module = module()
760 Returns true if Module has old code, otherwise false.
762 See also code(3).
764 check_process_code(Pid, Module) -> CheckResult
766 Types:
768 Pid = pid()
770 Module = module()
771 CheckResult = boolean()
772 The same as check_process_code(Pid, Module, []).
774 check_process_code(Pid, Module, OptionList) -> CheckResult | async
776 Types:
778 Pid = pid()
780 Module = module()
781 RequestId = term()
782 Option = {async, RequestId} | {allow_gc, boolean()}
783 OptionList = [Option]
784 CheckResult = boolean() | aborted
785 Checks if the node local process identified by Pid executes old
787 code for Module.
788 Options:
790 {allow_gc, boolean()}:
792 Determines if garbage collection is allowed when performing
793 the operation. If {allow_gc, false} is passed, and a garbage
794 collection is needed to determine the result of the opera‐
795 tion, the operation is aborted (see information on CheckRe‐
796 sult below). The default is to allow garbage collection,
797 that is, {allow_gc, true}.
798 {async, RequestId}:
800 The function check_process_code/3 returns the value async
801 immediately after the request has been sent. When the
802 request has been processed, the process that called this
803 function is passed a message on the form
804 {check_process_code, RequestId, CheckResult}.
805 If Pid equals self(), and no async option has been passed, the
807 operation is performed at once. Otherwise a request for the
808 operation is sent to the process identified by Pid, and is han‐
809 dled when appropriate. If no async option has been passed, the
810 caller blocks until CheckResult is available and can be
811 returned.
812 CheckResult informs about the result of the request as follows:
814 true:
816 The process identified by Pid executes old code for Module.
817 That is, the current call of the process executes old code
818 for this module, or the process has references to old code
819 for this module, or the process contains funs that refer‐
820 ences old code for this module.
821 false:
823 The process identified by Pid does not execute old code for
824 Module.
825 aborted:
827 The operation was aborted, as the process needed to be
828 garbage collected to determine the operation result, and the
829 operation was requested by passing option {allow_gc, false}.
830 Note:
832 Up until ERTS version 8.*, the check process code operation
833 checks for all types of references to the old code. That is,
834 direct references (e.g. return addresses on the process stack),
835 indirect references (funs in process context), and references to
836 literals in the code.
837 As of ERTS version 9.0, the check process code operation only
839 checks for direct references to the code. Indirect references
840 via funs will be ignored. If such funs exist and are used after
841 a purge of the old code, an exception will be raised upon usage
842 (same as the case when the fun is received by the process after
843 the purge). Literals will be taken care of (copied) at a later
844 stage. This behavior can as of ERTS version 8.1 be enabled when
845 building OTP, and will automatically be enabled if dirty sched‐
846 uler support is enabled.
847 See also code(3).
850 Failures:
852 badarg:
854 If Pid is not a node local process identifier.
855 badarg:
857 If Module is not an atom.
858 badarg:
860 If OptionList is an invalid list of options.
861 erlang:convert_time_unit(Time, FromUnit, ToUnit) -> ConvertedTime
863 Types:
865 Time = ConvertedTime = integer()
867 FromUnit = ToUnit = time_unit()
868 Converts the Time value of time unit FromUnit to the correspond‐
870 ing ConvertedTime value of time unit ToUnit. The result is
871 rounded using the floor function.
872 Warning:
874 You can lose accuracy and precision when converting between time
875 units. To minimize such loss, collect all data at native time
876 unit and do the conversion on the end result.
877 erlang:crc32(Data) -> integer() >= 0
880 Types:
882 Data = iodata()
884 Computes and returns the crc32 (IEEE 802.3 style) checksum for
886 Data.
887 erlang:crc32(OldCrc, Data) -> integer() >= 0
889 Types:
891 OldCrc = integer() >= 0
893 Data = iodata()
894 Continues computing the crc32 checksum by combining the previous
896 checksum, OldCrc, with the checksum of Data.
897 The following code:
899 X = erlang:crc32(Data1),
901 Y = erlang:crc32(X,Data2).
902 assigns the same value to Y as this:
904 Y = erlang:crc32([Data1,Data2]).
906 erlang:crc32_combine(FirstCrc, SecondCrc, SecondSize) ->
908 integer() >= 0
909 Types:
911 FirstCrc = SecondCrc = SecondSize = integer() >= 0
913 Combines two previously computed crc32 checksums. This computa‐
915 tion requires the size of the data object for the second check‐
916 sum to be known.
917 The following code:
919 Y = erlang:crc32(Data1),
921 Z = erlang:crc32(Y,Data2).
922 assigns the same value to Z as this:
924 X = erlang:crc32(Data1),
926 Y = erlang:crc32(Data2),
927 Z = erlang:crc32_combine(X,Y,iolist_size(Data2)).
928 date() -> Date
930 Types:
932 Date = calendar:date()
934 Returns the current date as {Year, Month, Day}.
936 The time zone and Daylight Saving Time correction depend on the
938 underlying OS. Example:
939 > date().
941 {1995,2,19}
942 erlang:decode_packet(Type, Bin, Options) ->
944 {ok, Packet, Rest} |
945 {more, Length} |
946 {error, Reason}
947 Types:
949 Type =
951 raw | 0 | 1 | 2 | 4 | asn1 | cdr | sunrm | fcgi | tpkt |
952 line | http | http_bin | httph | httph_bin
953 Bin = binary()
954 Options = [Opt]
955 Opt =
956 {packet_size, integer() >= 0} |
957 {line_length, integer() >= 0}
958 Packet = binary() | HttpPacket
959 Rest = binary()
960 Length = integer() >= 0 | undefined
961 Reason = term()
962 HttpPacket =
963 HttpRequest | HttpResponse | HttpHeader | http_eoh |
964 HttpError
965 HttpRequest = {http_request, HttpMethod, HttpUri, HttpVer‐
966 sion}
967 HttpResponse =
968 {http_response, HttpVersion, integer(), HttpString}
969 HttpHeader =
970 {http_header,
971 integer(),
972 HttpField,
973 UnmodifiedField :: HttpString,
974 Value :: HttpString}
975 HttpError = {http_error, HttpString}
976 HttpMethod =
977 'OPTIONS' | 'GET' | 'HEAD' | 'POST' | 'PUT' | 'DELETE' |
978 'TRACE' | HttpString
979 HttpUri =
980 '*' |
981 {absoluteURI,
982 http | https,
983 Host :: HttpString,
984 Port :: inet:port_number() | undefined,
985 Path :: HttpString} |
986 {scheme, Scheme :: HttpString, HttpString} |
987 {abs_path, HttpString} |
988 HttpString
989 HttpVersion =
990 {Major :: integer() >= 0, Minor :: integer() >= 0}
991 HttpField =
992 'Cache-Control' | 'Connection' | 'Date' | 'Pragma' |
993 'Transfer-Encoding' | 'Upgrade' | 'Via' | 'Accept' |
994 'Accept-Charset' | 'Accept-Encoding' | 'Accept-Language'
995 |
996 'Authorization' | 'From' | 'Host' | 'If-Modified-Since' |
997 'If-Match' | 'If-None-Match' | 'If-Range' |
998 'If-Unmodified-Since' | 'Max-Forwards' |
999 'Proxy-Authorization' | 'Range' | 'Referer' | 'User-
1000 Agent' |
1001 'Age' | 'Location' | 'Proxy-Authenticate' | 'Public' |
1002 'Retry-After' | 'Server' | 'Vary' | 'Warning' |
1003 'Www-Authenticate' | 'Allow' | 'Content-Base' |
1004 'Content-Encoding' | 'Content-Language' | 'Content-
1005 Length' |
1006 'Content-Location' | 'Content-Md5' | 'Content-Range' |
1007 'Content-Type' | 'Etag' | 'Expires' | 'Last-Modified' |
1008 'Accept-Ranges' | 'Set-Cookie' | 'Set-Cookie2' |
1009 'X-Forwarded-For' | 'Cookie' | 'Keep-Alive' |
1010 'Proxy-Connection' | HttpString
1011 HttpString = string() | binary()
1012 Decodes the binary Bin according to the packet protocol speci‐
1014 fied by Type. Similar to the packet handling done by sockets
1015 with option {packet,Type}.
1016 If an entire packet is contained in Bin, it is returned together
1018 with the remainder of the binary as {ok,Packet,Rest}.
1019 If Bin does not contain the entire packet, {more,Length} is
1021 returned. Length is either the expected total size of the
1022 packet, or undefined if the expected packet size is unknown.
1023 decode_packet can then be called again with more data added.
1024 If the packet does not conform to the protocol format,
1026 {error,Reason} is returned.
1027 Types:
1029 raw | 0:
1031 No packet handling is done. The entire binary is returned
1032 unless it is empty.
1033 1 | 2 | 4:
1035 Packets consist of a header specifying the number of bytes
1036 in the packet, followed by that number of bytes. The length
1037 of the header can be one, two, or four bytes; the order of
1038 the bytes is big-endian. The header is stripped off when the
1039 packet is returned.
1040 line:
1042 A packet is a line-terminated by a delimiter byte, default
1043 is the latin-1 newline character. The delimiter byte is
1044 included in the returned packet unless the line was trun‐
1045 cated according to option line_length.
1046 asn1 | cdr | sunrm | fcgi | tpkt:
1048 The header is not stripped off.
1049 The meanings of the packet types are as follows:
1051 asn1 - ASN.1 BER:
1053 sunrm - Sun's RPC encoding:
1056 cdr - CORBA (GIOP 1.1):
1059 fcgi - Fast CGI:
1062 tpkt - TPKT format [RFC1006]:
1065 http | httph | http_bin | httph_bin:
1068 The Hypertext Transfer Protocol. The packets are returned
1069 with the format according to HttpPacket described earlier. A
1070 packet is either a request, a response, a header, or an end
1071 of header mark. Invalid lines are returned as HttpError.
1072 Recognized request methods and header fields are returned as
1074 atoms. Others are returned as strings. Strings of unrecog‐
1075 nized header fields are formatted with only capital letters
1076 first and after hyphen characters, for example, "Sec-Web‐
1077 socket-Key". Header field names are also returned in Unmodi‐
1078 fiedField as strings, without any conversion or formatting.
1079 The protocol type http is only to be used for the first line
1081 when an HttpRequest or an HttpResponse is expected. The fol‐
1082 lowing calls are to use httph to get HttpHeaders until
1083 http_eoh is returned, which marks the end of the headers and
1084 the beginning of any following message body.
1085 The variants http_bin and httph_bin return strings (Http‐
1087 String) as binaries instead of lists.
1088 Options:
1090 {packet_size, integer() >= 0}:
1092 Sets the maximum allowed size of the packet body. If the
1093 packet header indicates that the length of the packet is
1094 longer than the maximum allowed length, the packet is con‐
1095 sidered invalid. Defaults to 0, which means no size limit.
1096 {line_length, integer() >= 0}:
1098 For packet type line, lines longer than the indicated length
1099 are truncated.
1100 Option line_length also applies to http* packet types as an
1102 alias for option packet_size if packet_size itself is not
1103 set. This use is only intended for backward compatibility.
1104 {line_delimiter, 0 =< byte() =< 255}:
1106 For packet type line, sets the delimiting byte. Default is
1107 the latin-1 character $\n.
1108 Examples:
1110 > erlang:decode_packet(1,<<3,"abcd">>,[]).
1112 {ok,<<"abc">>,<<"d">>}
1113 > erlang:decode_packet(1,<<5,"abcd">>,[]).
1114 {more,6}
1115 erlang:delete_element(Index, Tuple1) -> Tuple2
1117 Types:
1119 Index = integer() >= 1
1121 1..tuple_size(Tuple1)
1122 Tuple1 = Tuple2 = tuple()
1123 Returns a new tuple with element at Index removed from tuple
1125 Tuple1, for example:
1126 > erlang:delete_element(2, {one, two, three}).
1128 {one,three}
1129 delete_module(Module) -> true | undefined
1131 Types:
1133 Module = module()
1135 Makes the current code for Module become old code and deletes
1137 all references for this module from the export table. Returns
1138 undefined if the module does not exist, otherwise true.
1139 Warning:
1141 This BIF is intended for the code server (see code(3)) and is
1142 not to be used elsewhere.
1143 Failure: badarg if there already is an old version of Module.
1146 demonitor(MonitorRef) -> true
1148 Types:
1150 MonitorRef = reference()
1152 If MonitorRef is a reference that the calling process obtained
1154 by calling monitor/2, this monitoring is turned off. If the mon‐
1155 itoring is already turned off, nothing happens.
1156 Once demonitor(MonitorRef) has returned, it is guaranteed that
1158 no {'DOWN', MonitorRef, _, _, _} message, because of the moni‐
1159 tor, will be placed in the caller message queue in the future.
1160 However, a {'DOWN', MonitorRef, _, _, _} message can have been
1161 placed in the caller message queue before the call. It is there‐
1162 fore usually advisable to remove such a 'DOWN' message from the
1163 message queue after monitoring has been stopped. demonitor(Moni‐
1164 torRef, [flush]) can be used instead of demonitor(MonitorRef) if
1165 this cleanup is wanted.
1166 Note:
1168 Before Erlang/OTP R11B (ERTS 5.5) demonitor/1 behaved completely
1169 asynchronously, that is, the monitor was active until the
1170 "demonitor signal" reached the monitored entity. This had one
1171 undesirable effect. You could never know when you were guaran‐
1172 teed not to receive a DOWN message because of the monitor.
1173 The current behavior can be viewed as two combined operations:
1175 asynchronously send a "demonitor signal" to the monitored entity
1176 and ignore any future results of the monitor.
1177 Failure: It is an error if MonitorRef refers to a monitoring
1180 started by another process. Not all such cases are cheap to
1181 check. If checking is cheap, the call fails with badarg, for
1182 example if MonitorRef is a remote reference.
1183 demonitor(MonitorRef, OptionList) -> boolean()
1185 Types:
1187 MonitorRef = reference()
1189 OptionList = [Option]
1190 Option = flush | info
1191 The returned value is true unless info is part of OptionList.
1193 demonitor(MonitorRef, []) is equivalent to demonitor(Monitor‐
1195 Ref).
1196 Options:
1198 flush:
1200 Removes (one) {_, MonitorRef, _, _, _} message, if there is
1201 one, from the caller message queue after monitoring has been
1202 stopped.
1203 Calling demonitor(MonitorRef, [flush]) is equivalent to the
1205 following, but more efficient:
1206 demonitor(MonitorRef),
1208 receive
1209 {_, MonitorRef, _, _, _} ->
1210 true
1211 after 0 ->
1212 true
1213 end
1214 info:
1216 The returned value is one of the following:
1217 true:
1219 The monitor was found and removed. In this case, no 'DOWN'
1220 message corresponding to this monitor has been delivered
1221 and will not be delivered.
1222 false:
1224 The monitor was not found and could not be removed. This
1225 probably because someone already has placed a 'DOWN' mes‐
1226 sage corresponding to this monitor in the caller message
1227 queue.
1228 If option info is combined with option flush, false is
1230 returned if a flush was needed, otherwise true.
1231 Note:
1233 More options can be added in a future release.
1234 Failures:
1237 badarg:
1239 If OptionList is not a list.
1240 badarg:
1242 If Option is an invalid option.
1243 badarg:
1245 The same failure as for demonitor/1.
1246 disconnect_node(Node) -> boolean() | ignored
1248 Types:
1250 Node = node()
1252 Forces the disconnection of a node. This appears to the node
1254 Node as if the local node has crashed. This BIF is mainly used
1255 in the Erlang network authentication protocols.
1256 Returns true if disconnection succeeds, otherwise false. If the
1258 local node is not alive, ignored is returned.
1259 erlang:display(Term) -> true
1261 Types:
1263 Term = term()
1265 Prints a text representation of Term on the standard output.
1267 Warning:
1269 This BIF is intended for debugging only.
1270 erlang:dist_ctrl_get_data(DHandle) -> {Size, Data} | Data | none
1273 Types:
1275 Size = integer() >= 0
1277 DHandle = dist_handle()
1278 Data = iovec()
1279 Get distribution channel data from the local node that is to be
1281 passed to the remote node. The distribution channel is identi‐
1282 fied by DHandle. If no data is available, the atom none is
1283 returned. One can request to be informed by a message when more
1284 data is available by calling erlang:dist_ctrl_get_data_notifica‐
1285 tion(DHandle).
1286 The returned value when there are data available depends on the
1288 value of the get_size option configured on the distribution
1289 channel identified by DHandle. For more information see the doc‐
1290 umentation of the get_size option for the
1291 erlang:dist_ctrl_set_opt/3 function.
1292 Note:
1294 Only the process registered as distribution controller for the
1295 distribution channel identified by DHandle is allowed to call
1296 this function.
1297 This function is used when implementing an alternative distribu‐
1300 tion carrier using processes as distribution controllers. DHan‐
1301 dle is retrived via the callback f_handshake_complete. More
1302 information can be found in the documentation of ERTS User's
1303 Guide ➜ How to implement an Alternative Carrier for the Erlang
1304 Distribution ➜ Distribution Module.
1305 erlang:dist_ctrl_get_opt(DHandle, Opt :: get_size) -> Value
1307 Types:
1309 DHandle = dist_handle()
1311 Value = boolean()
1312 Returns the value of the get_size option on the distribution
1314 channel identified by DHandle. For more information see the doc‐
1315 umentation of the get_size option for the
1316 erlang:dist_ctrl_set_opt/3 function.
1317 Note:
1319 Only the process registered as distribution controller for the
1320 distribution channel identified by DHandle is allowed to call
1321 this function.
1322 This function is used when implementing an alternative distribu‐
1325 tion carrier using processes as distribution controllers. DHan‐
1326 dle is retrived via the callback f_handshake_complete. More
1327 information can be found in the documentation of ERTS User's
1328 Guide ➜ How to implement an Alternative Carrier for the Erlang
1329 Distribution ➜ Distribution Module.
1330 erlang:dist_ctrl_get_data_notification(DHandle) -> ok
1332 Types:
1334 DHandle = dist_handle()
1336 Request notification when more data is available to fetch using
1338 erlang:dist_ctrl_get_data(DHandle) for the distribution channel
1339 identified by DHandle. When more data is present, the caller
1340 will be sent the message dist_data. Once a dist_data messages
1341 has been sent, no more dist_data messages will be sent until the
1342 dist_ctrl_get_data_notification/1 function has been called
1343 again.
1344 Note:
1346 Only the process registered as distribution controller for the
1347 distribution channel identified by DHandle is allowed to call
1348 this function.
1349 This function is used when implementing an alternative distribu‐
1352 tion carrier using processes as distribution controllers. DHan‐
1353 dle is retrived via the callback f_handshake_complete. More
1354 information can be found in the documentation of ERTS User's
1355 Guide ➜ How to implement an Alternative Carrier for the Erlang
1356 Distribution ➜ Distribution Module.
1357 erlang:dist_ctrl_input_handler(DHandle, InputHandler) -> ok
1359 Types:
1361 DHandle = dist_handle()
1363 InputHandler = pid()
1364 Register an alternate input handler process for the distribution
1366 channel identified by DHandle. Once this function has been
1367 called, InputHandler is the only process allowed to call
1368 erlang:dist_ctrl_put_data(DHandle, Data) with the DHandle iden‐
1369 tifing this distribution channel.
1370 Note:
1372 Only the process registered as distribution controller for the
1373 distribution channel identified by DHandle is allowed to call
1374 this function.
1375 This function is used when implementing an alternative distribu‐
1378 tion carrier using processes as distribution controllers. DHan‐
1379 dle is retrived via the callback f_handshake_complete. More
1380 information can be found in the documentation of ERTS User's
1381 Guide ➜ How to implement an Alternative Carrier for the Erlang
1382 Distribution ➜ Distribution Module.
1383 erlang:dist_ctrl_put_data(DHandle, Data) -> ok
1385 Types:
1387 DHandle = dist_handle()
1389 Data = iodata()
1390 Deliver distribution channel data from a remote node to the
1392 local node.
1393 Note:
1395 Only the process registered as distribution controller for the
1396 distribution channel identified by DHandle is allowed to call
1397 this function unless an alternate input handler process has been
1398 registered using erlang:dist_ctrl_input_handler(DHandle,
1399 InputHandler). If an alternate input handler has been regis‐
1400 tered, only the registered input handler process is allowed to
1401 call this function.
1402 This function is used when implementing an alternative distribu‐
1405 tion carrier using processes as distribution controllers. DHan‐
1406 dle is retrived via the callback f_handshake_complete. More
1407 information can be found in the documentation of ERTS User's
1408 Guide ➜ How to implement an Alternative Carrier for the Erlang
1409 Distribution ➜ Distribution Module.
1410 erlang:dist_ctrl_set_opt(DHandle, Opt :: get_size, Value) ->
1412 OldValue
1413 Types:
1415 DHandle = dist_handle()
1417 Value = OldValue = boolean()
1418 Sets the value of the get_size option on the distribution chan‐
1420 nel identified by DHandle. This option controls the return value
1421 of calls to erlang:dist_ctrl_get_data(DHandle) where DHandle
1422 equals DHandle used when setting this option. When the get_size
1423 option is:
1424 false:
1426 and there are distribution data available, a call to
1427 erlang:dist_ctrl_get_data(DHandle) will just return Data to
1428 pass over the channel. This is the default value of the
1429 get_size option.
1430 true:
1432 and there are distribution data available, a call to
1433 erlang:dist_ctrl_get_data(DHandle) will return Data to pass
1434 over the channel as well as the Size of Data in bytes. This
1435 is returned as a tuple on the form {Size, Data}.
1436 All options are set to default when a channel is closed.
1438 Note:
1440 Only the process registered as distribution controller for the
1441 distribution channel identified by DHandle is allowed to call
1442 this function.
1443 This function is used when implementing an alternative distribu‐
1446 tion carrier using processes as distribution controllers. DHan‐
1447 dle is retrived via the callback f_handshake_complete. More
1448 information can be found in the documentation of ERTS User's
1449 Guide ➜ How to implement an Alternative Carrier for the Erlang
1450 Distribution ➜ Distribution Module.
1451 element(N, Tuple) -> term()
1453 Types:
1455 N = integer() >= 1
1457 1..tuple_size(Tuple)
1458 Tuple = tuple()
1459 Returns the Nth element (numbering from 1) of Tuple, for exam‐
1461 ple:
1462 > element(2, {a, b, c}).
1464 b
1465 Allowed in guard tests.
1467 erase() -> [{Key, Val}]
1469 Types:
1471 Key = Val = term()
1473 Returns the process dictionary and deletes it, for example:
1475 > put(key1, {1, 2, 3}),
1477 put(key2, [a, b, c]),
1478 erase().
1479 [{key1,{1,2,3}},{key2,[a,b,c]}]
1480 erase(Key) -> Val | undefined
1482 Types:
1484 Key = Val = term()
1486 Returns the value Val associated with Key and deletes it from
1488 the process dictionary. Returns undefined if no value is associ‐
1489 ated with Key. Example:
1490 > put(key1, {merry, lambs, are, playing}),
1492 X = erase(key1),
1493 {X, erase(key1)}.
1494 {{merry,lambs,are,playing},undefined}
1495 error(Reason) -> no_return()
1497 Types:
1499 Reason = term()
1501 Stops the execution of the calling process with the reason Rea‐
1503 son, where Reason is any term. The exit reason is {Reason,
1504 Where}, where Where is a list of the functions most recently
1505 called (the current function first). As evaluating this function
1506 causes the process to terminate, it has no return value. Exam‐
1507 ple:
1508 > catch error(foobar).
1510 {'EXIT',{foobar,[{shell,apply_fun,3,
1511 [{file,"shell.erl"},{line,906}]},
1512 {erl_eval,do_apply,6,[{file,"erl_eval.erl"},{line,677}]},
1513 {erl_eval,expr,5,[{file,"erl_eval.erl"},{line,430}]},
1514 {shell,exprs,7,[{file,"shell.erl"},{line,687}]},
1515 {shell,eval_exprs,7,[{file,"shell.erl"},{line,642}]},
1516 {shell,eval_loop,3,[{file,"shell.erl"},{line,627}]}]}}
1517 error(Reason, Args) -> no_return()
1520 Types:
1522 Reason = term()
1524 Args = [term()]
1525 Stops the execution of the calling process with the reason Rea‐
1527 son, where Reason is any term. The exit reason is {Reason,
1528 Where}, where Where is a list of the functions most recently
1529 called (the current function first). Args is expected to be the
1530 list of arguments for the current function; in Beam it is used
1531 to provide the arguments for the current function in the term
1532 Where. As evaluating this function causes the process to termi‐
1533 nate, it has no return value.
1534 exit(Reason) -> no_return()
1536 Types:
1538 Reason = term()
1540 Stops the execution of the calling process with exit reason Rea‐
1542 son, where Reason is any term. As evaluating this function
1543 causes the process to terminate, it has no return value. Exam‐
1544 ple:
1545 > exit(foobar).
1547 ** exception exit: foobar
1548 > catch exit(foobar).
1549 {'EXIT',foobar}
1550 exit(Pid, Reason) -> true
1552 Types:
1554 Pid = pid() | port()
1556 Reason = term()
1557 Sends an exit signal with exit reason Reason to the process or
1559 port identified by Pid.
1560 The following behavior applies if Reason is any term, except
1562 normal or kill:
1563 * If Pid is not trapping exits, Pid itself exits with exit
1565 reason Reason.
1566 * If Pid is trapping exits, the exit signal is transformed
1568 into a message {'EXIT', From, Reason} and delivered to the
1569 message queue of Pid.
1570 * From is the process identifier of the process that sent the
1572 exit signal. See also process_flag/2.
1573 If Reason is the atom normal, Pid does not exit. If it is trap‐
1575 ping exits, the exit signal is transformed into a message
1576 {'EXIT', From, normal} and delivered to its message queue.
1577 If Reason is the atom kill, that is, if exit(Pid, kill) is
1579 called, an untrappable exit signal is sent to Pid, which uncon‐
1580 ditionally exits with exit reason killed.
1581 erlang:external_size(Term) -> integer() >= 0
1583 Types:
1585 Term = term()
1587 Calculates, without doing the encoding, the maximum byte size
1589 for a term encoded in the Erlang external term format. The fol‐
1590 lowing condition applies always:
1591 > Size1 = byte_size(term_to_binary(Term)),
1593 > Size2 = erlang:external_size(Term),
1594 > true = Size1 =< Size2.
1595 true
1596 This is equivalent to a call to:
1598 erlang:external_size(Term, [])
1600 erlang:external_size(Term, Options) -> integer() >= 0
1602 Types:
1604 Term = term()
1606 Options = [{minor_version, Version :: integer() >= 0}]
1607 Calculates, without doing the encoding, the maximum byte size
1609 for a term encoded in the Erlang external term format. The fol‐
1610 lowing condition applies always:
1611 > Size1 = byte_size(term_to_binary(Term, Options)),
1613 > Size2 = erlang:external_size(Term, Options),
1614 > true = Size1 =< Size2.
1615 true
1616 Option {minor_version, Version} specifies how floats are
1618 encoded. For a detailed description, see term_to_binary/2.
1619 float(Number) -> float()
1621 Types:
1623 Number = number()
1625 Returns a float by converting Number to a float, for example:
1627 > float(55).
1629 55.0
1630 Allowed in guard tests.
1632 Note:
1634 If used on the top level in a guard, it tests whether the argu‐
1635 ment is a floating point number; for clarity, use is_float/1
1636 instead.
1637 When float/1 is used in an expression in a guard, such as
1639 'float(A) == 4.0', it converts a number as described earlier.
1640 float_to_binary(Float) -> binary()
1643 Types:
1645 Float = float()
1647 The same as float_to_binary(Float,[{scientific,20}]).
1649 float_to_binary(Float, Options) -> binary()
1651 Types:
1653 Float = float()
1655 Options = [Option]
1656 Option =
1657 {decimals, Decimals :: 0..253} |
1658 {scientific, Decimals :: 0..249} |
1659 compact
1660 Returns a binary corresponding to the text representation of
1662 Float using fixed decimal point formatting. Options behaves in
1663 the same way as float_to_list/2. Examples:
1664 > float_to_binary(7.12, [{decimals, 4}]).
1666 <<"7.1200">>
1667 > float_to_binary(7.12, [{decimals, 4}, compact]).
1668 <<"7.12">>
1669 float_to_list(Float) -> string()
1671 Types:
1673 Float = float()
1675 The same as float_to_list(Float,[{scientific,20}]).
1677 float_to_list(Float, Options) -> string()
1679 Types:
1681 Float = float()
1683 Options = [Option]
1684 Option =
1685 {decimals, Decimals :: 0..253} |
1686 {scientific, Decimals :: 0..249} |
1687 compact
1688 Returns a string corresponding to the text representation of
1690 Float using fixed decimal point formatting.
1691 Available options:
1693 * If option decimals is specified, the returned value contains
1695 at most Decimals number of digits past the decimal point. If
1696 the number does not fit in the internal static buffer of 256
1697 bytes, the function throws badarg.
1698 * If option compact is specified, the trailing zeros at the
1700 end of the list are truncated. This option is only meaning‐
1701 ful together with option decimals.
1702 * If option scientific is specified, the float is formatted
1704 using scientific notation with Decimals digits of precision.
1705 * If Options is [], the function behaves as float_to_list/1.
1707 Examples:
1709 > float_to_list(7.12, [{decimals, 4}]).
1711 "7.1200"
1712 > float_to_list(7.12, [{decimals, 4}, compact]).
1713 "7.12"
1714 floor(Number) -> integer()
1716 Types:
1718 Number = number()
1720 Returns the largest integer not greater than Number. For exam‐
1722 ple:
1723 > floor(-10.5).
1725 -11
1726 Allowed in guard tests.
1728 erlang:fun_info(Fun) -> [{Item, Info}]
1730 Types:
1732 Fun = function()
1734 Item =
1735 arity | env | index | name | module | new_index |
1736 new_uniq |
1737 pid | type | uniq
1738 Info = term()
1739 Returns a list with information about the fun Fun. Each list
1741 element is a tuple. The order of the tuples is undefined, and
1742 more tuples can be added in a future release.
1743 Warning:
1745 This BIF is mainly intended for debugging, but it can sometimes
1746 be useful in library functions that need to verify, for example,
1747 the arity of a fun.
1748 Two types of funs have slightly different semantics:
1751 * A fun created by fun M:F/A is called an external fun. Call‐
1753 ing it will always call the function F with arity A in the
1754 latest code for module M. Notice that module M does not even
1755 need to be loaded when the fun fun M:F/A is created.
1756 * All other funs are called local. When a local fun is called,
1758 the same version of the code that created the fun is called
1759 (even if a newer version of the module has been loaded).
1760 The following elements are always present in the list for both
1762 local and external funs:
1763 {type, Type}:
1765 Type is local or external.
1766 {module, Module}:
1768 Module (an atom) is the module name.
1769 If Fun is a local fun, Module is the module in which the fun
1771 is defined.
1772 If Fun is an external fun, Module is the module that the fun
1774 refers to.
1775 {name, Name}:
1777 Name (an atom) is a function name.
1778 If Fun is a local fun, Name is the name of the local func‐
1780 tion that implements the fun. (This name was generated by
1781 the compiler, and is only of informational use. As it is a
1782 local function, it cannot be called directly.) If no code is
1783 currently loaded for the fun, [] is returned instead of an
1784 atom.
1785 If Fun is an external fun, Name is the name of the exported
1787 function that the fun refers to.
1788 {arity, Arity}:
1790 Arity is the number of arguments that the fun is to be
1791 called with.
1792 {env, Env}:
1794 Env (a list) is the environment or free variables for the
1795 fun. For external funs, the returned list is always empty.
1796 The following elements are only present in the list if Fun is
1798 local:
1799 {pid, Pid}:
1801 Pid is the process identifier of the process that originally
1802 created the fun.
1803 It might point to the init process if the Fun was statically
1805 allocated when module was loaded (this optimisation is per‐
1806 formed for local functions that do not capture the environ‐
1807 ment).
1808 {index, Index}:
1810 Index (an integer) is an index into the module fun table.
1811 {new_index, Index}:
1813 Index (an integer) is an index into the module fun table.
1814 {new_uniq, Uniq}:
1816 Uniq (a binary) is a unique value for this fun. It is calcu‐
1817 lated from the compiled code for the entire module.
1818 {uniq, Uniq}:
1820 Uniq (an integer) is a unique value for this fun. As from
1821 Erlang/OTP R15, this integer is calculated from the compiled
1822 code for the entire module. Before Erlang/OTP R15, this
1823 integer was based on only the body of the fun.
1824 erlang:fun_info(Fun, Item) -> {Item, Info}
1826 Types:
1828 Fun = function()
1830 Item = fun_info_item()
1831 Info = term()
1832 fun_info_item() =
1833 arity | env | index | name | module | new_index | new_uniq |
1834 pid | type | uniq
1835 Returns information about Fun as specified by Item, in the form
1837 {Item,Info}.
1838 For any fun, Item can be any of the atoms module, name, arity,
1840 env, or type.
1841 For a local fun, Item can also be any of the atoms index,
1843 new_index, new_uniq, uniq, and pid. For an external fun, the
1844 value of any of these items is always the atom undefined.
1845 See erlang:fun_info/1.
1847 erlang:fun_to_list(Fun) -> string()
1849 Types:
1851 Fun = function()
1853 Returns a string corresponding to the text representation of
1855 Fun.
1856 erlang:function_exported(Module, Function, Arity) -> boolean()
1858 Types:
1860 Module = module()
1862 Function = atom()
1863 Arity = arity()
1864 Returns true if the module Module is loaded and contains an
1866 exported function Function/Arity, or if there is a BIF (a built-
1867 in function implemented in C) with the specified name, otherwise
1868 returns false.
1869 Note:
1871 This function used to return false for BIFs before Erlang/OTP
1872 18.0.
1873 garbage_collect() -> true
1876 Forces an immediate garbage collection of the executing process.
1878 The function is not to be used unless it has been noticed (or
1879 there are good reasons to suspect) that the spontaneous garbage
1880 collection will occur too late or not at all.
1881 Warning:
1883 Improper use can seriously degrade system performance.
1884 garbage_collect(Pid) -> GCResult
1887 Types:
1889 Pid = pid()
1891 GCResult = boolean()
1892 The same as garbage_collect(Pid, []).
1894 garbage_collect(Pid, OptionList) -> GCResult | async
1896 Types:
1898 Pid = pid()
1900 RequestId = term()
1901 Option = {async, RequestId} | {type, major | minor}
1902 OptionList = [Option]
1903 GCResult = boolean()
1904 Garbage collects the node local process identified by Pid.
1906 Option:
1908 {async, RequestId}:
1910 The function garbage_collect/2 returns the value async imme‐
1911 diately after the request has been sent. When the request
1912 has been processed, the process that called this function is
1913 passed a message on the form {garbage_collect, RequestId,
1914 GCResult}.
1915 {type, 'major' | 'minor'}:
1917 Triggers garbage collection of requested type. Default value
1918 is 'major', which would trigger a fullsweep GC. The option
1919 'minor' is considered a hint and may lead to either minor or
1920 major GC run.
1921 If Pid equals self(), and no async option has been passed, the
1923 garbage collection is performed at once, that is, the same as
1924 calling garbage_collect/0. Otherwise a request for garbage col‐
1925 lection is sent to the process identified by Pid, and will be
1926 handled when appropriate. If no async option has been passed,
1927 the caller blocks until GCResult is available and can be
1928 returned.
1929 GCResult informs about the result of the garbage collection
1931 request as follows:
1932 true:
1934 The process identified by Pid has been garbage collected.
1935 false:
1937 No garbage collection was performed, as the process identi‐
1938 fied by Pid terminated before the request could be satis‐
1939 fied.
1940 Notice that the same caveats apply as for garbage_collect/0.
1942 Failures:
1944 badarg:
1946 If Pid is not a node local process identifier.
1947 badarg:
1949 If OptionList is an invalid list of options.
1950 get() -> [{Key, Val}]
1952 Types:
1954 Key = Val = term()
1956 Returns the process dictionary as a list of {Key, Val} tuples,
1958 for example:
1959 > put(key1, merry),
1961 put(key2, lambs),
1962 put(key3, {are, playing}),
1963 get().
1964 [{key1,merry},{key2,lambs},{key3,{are,playing}}]
1965 get(Key) -> Val | undefined
1967 Types:
1969 Key = Val = term()
1971 Returns the value Val associated with Key in the process dictio‐
1973 nary, or undefined if Key does not exist. Example:
1974 > put(key1, merry),
1976 put(key2, lambs),
1977 put({any, [valid, term]}, {are, playing}),
1978 get({any, [valid, term]}).
1979 {are,playing}
1980 erlang:get_cookie() -> Cookie | nocookie
1982 Types:
1984 Cookie = atom()
1986 Returns the magic cookie of the local node if the node is alive,
1988 otherwise the atom nocookie.
1989 get_keys() -> [Key]
1991 Types:
1993 Key = term()
1995 Returns a list of all keys present in the process dictionary,
1997 for example:
1998 > put(dog, {animal,1}),
2000 put(cow, {animal,2}),
2001 put(lamb, {animal,3}),
2002 get_keys().
2003 [dog,cow,lamb]
2004 get_keys(Val) -> [Key]
2006 Types:
2008 Val = Key = term()
2010 Returns a list of keys that are associated with the value Val in
2012 the process dictionary, for example:
2013 > put(mary, {1, 2}),
2015 put(had, {1, 2}),
2016 put(a, {1, 2}),
2017 put(little, {1, 2}),
2018 put(dog, {1, 3}),
2019 put(lamb, {1, 2}),
2020 get_keys({1, 2}).
2021 [mary,had,a,little,lamb]
2022 erlang:get_stacktrace() -> [stack_item()]
2024 Types:
2026 stack_item() =
2028 {Module :: module(),
2029 Function :: atom(),
2030 Arity :: arity() | (Args :: [term()]),
2031 Location ::
2032 [{file, Filename :: string()} |
2033 {line, Line :: integer() >= 1}]}
2034 Warning:
2036 erlang:get_stacktrace/0 is deprecated and will be removed in OTP
2037 24. Starting from OTP 23, erlang:get_stacktrace/0 returns [].
2038 Instead of using erlang:get_stacktrace/0 to retrieve the call
2041 stack back-trace, use the following syntax:
2042 try Expr
2044 catch
2045 Class:Reason:Stacktrace ->
2046 {Class,Reason,Stacktrace}
2047 end
2048 group_leader() -> pid()
2050 Returns the process identifier of the group leader for the
2052 process evaluating the function.
2053 Every process is a member of some process group and all groups
2055 have a group leader. All I/O from the group is channeled to the
2056 group leader. When a new process is spawned, it gets the same
2057 group leader as the spawning process. Initially, at system
2058 startup, init is both its own group leader and the group leader
2059 of all processes.
2060 group_leader(GroupLeader, Pid) -> true
2062 Types:
2064 GroupLeader = Pid = pid()
2066 Sets the group leader of Pid to GroupLeader. Typically, this is
2068 used when a process started from a certain shell is to have
2069 another group leader than init.
2070 The group leader should be rarely changed in applications with a
2072 supervision tree, because OTP assumes the group leader of their
2073 processes is their application master.
2074 See also group_leader/0 and OTP design principles related to
2076 starting and stopping applications.
2077 halt() -> no_return()
2079 The same as halt(0, []). Example:
2081 > halt().
2083 os_prompt%
2084 halt(Status) -> no_return()
2086 Types:
2088 Status = integer() >= 0 | abort | string()
2090 The same as halt(Status, []). Example:
2092 > halt(17).
2094 os_prompt% echo $?
2095 17
2096 os_prompt%
2097 halt(Status, Options) -> no_return()
2099 Types:
2101 Status = integer() >= 0 | abort | string()
2103 Options = [Option]
2104 Option = {flush, boolean()}
2105 Status must be a non-negative integer, a string, or the atom
2107 abort. Halts the Erlang runtime system. Has no return value.
2108 Depending on Status, the following occurs:
2109 integer():
2111 The runtime system exits with integer value Status as status
2112 code to the calling environment (OS).
2113 Note:
2115 On many platforms, the OS supports only status codes 0-255. A
2116 too large status code is truncated by clearing the high bits.
2117 string():
2120 An Erlang crash dump is produced with Status as slogan. Then
2121 the runtime system exits with status code 1. The string will
2122 be truncated if longer than 200 characters.
2123 Note:
2125 Before ERTS 9.1 (OTP-20.1) only code points in the range 0-255
2126 was accepted in the string. Now any unicode string is valid.
2127 abort:
2130 The runtime system aborts producing a core dump, if that is
2131 enabled in the OS.
2132 For integer Status, the Erlang runtime system closes all ports
2134 and allows async threads to finish their operations before exit‐
2135 ing. To exit without such flushing, use Option as {flush,false}.
2136 For statuses string() and abort, option flush is ignored and
2138 flushing is not done.
2139 hd(List) -> term()
2141 Types:
2143 List = [term(), ...]
2145 Returns the head of List, that is, the first element, for exam‐
2147 ple:
2148 > hd([1,2,3,4,5]).
2150 1
2151 Allowed in guard tests.
2153 Failure: badarg if List is the empty list [].
2155 erlang:hibernate(Module, Function, Args) -> no_return()
2157 Types:
2159 Module = module()
2161 Function = atom()
2162 Args = [term()]
2163 Puts the calling process into a wait state where its memory
2165 allocation has been reduced as much as possible. This is useful
2166 if the process does not expect to receive any messages soon.
2167 The process is awaken when a message is sent to it, and control
2169 resumes in Module:Function with the arguments specified by Args
2170 with the call stack emptied, meaning that the process terminates
2171 when that function returns. Thus erlang:hibernate/3 never
2172 returns to its caller.
2173 If the process has any message in its message queue, the process
2175 is awakened immediately in the same way as described earlier.
2176 In more technical terms, erlang:hibernate/3 discards the call
2178 stack for the process, and then garbage collects the process.
2179 After this, all live data is in one continuous heap. The heap is
2180 then shrunken to the exact same size as the live data that it
2181 holds (even if that size is less than the minimum heap size for
2182 the process).
2183 If the size of the live data in the process is less than the
2185 minimum heap size, the first garbage collection occurring after
2186 the process is awakened ensures that the heap size is changed to
2187 a size not smaller than the minimum heap size.
2188 Notice that emptying the call stack means that any surrounding
2190 catch is removed and must be re-inserted after hibernation. One
2191 effect of this is that processes started using proc_lib (also
2192 indirectly, such as gen_server processes), are to use
2193 proc_lib:hibernate/3 instead, to ensure that the exception han‐
2194 dler continues to work when the process wakes up.
2195 erlang:insert_element(Index, Tuple1, Term) -> Tuple2
2197 Types:
2199 Index = integer() >= 1
2201 1..tuple_size(Tuple1) + 1
2202 Tuple1 = Tuple2 = tuple()
2203 Term = term()
2204 Returns a new tuple with element Term inserted at position Index
2206 in tuple Tuple1. All elements from position Index and upwards
2207 are pushed one step higher in the new tuple Tuple2. Example:
2208 > erlang:insert_element(2, {one, two, three}, new).
2210 {one,new,two,three}
2211 integer_to_binary(Integer) -> binary()
2213 Types:
2215 Integer = integer()
2217 Returns a binary corresponding to the text representation of
2219 Integer, for example:
2220 > integer_to_binary(77).
2222 <<"77">>
2223 integer_to_binary(Integer, Base) -> binary()
2225 Types:
2227 Integer = integer()
2229 Base = 2..36
2230 Returns a binary corresponding to the text representation of
2232 Integer in base Base, for example:
2233 > integer_to_binary(1023, 16).
2235 <<"3FF">>
2236 integer_to_list(Integer) -> string()
2238 Types:
2240 Integer = integer()
2242 Returns a string corresponding to the text representation of
2244 Integer, for example:
2245 > integer_to_list(77).
2247 "77"
2248 integer_to_list(Integer, Base) -> string()
2250 Types:
2252 Integer = integer()
2254 Base = 2..36
2255 Returns a string corresponding to the text representation of
2257 Integer in base Base, for example:
2258 > integer_to_list(1023, 16).
2260 "3FF"
2261 iolist_size(Item) -> integer() >= 0
2263 Types:
2265 Item = iolist() | binary()
2267 Returns an integer, that is the size in bytes, of the binary
2269 that would be the result of iolist_to_binary(Item), for example:
2270 > iolist_size([1,2|<<3,4>>]).
2272 4
2273 iolist_to_binary(IoListOrBinary) -> binary()
2275 Types:
2277 IoListOrBinary = iolist() | binary()
2279 Returns a binary that is made from the integers and binaries in
2281 IoListOrBinary, for example:
2282 > Bin1 = <<1,2,3>>.
2284 <<1,2,3>>
2285 > Bin2 = <<4,5>>.
2286 <<4,5>>
2287 > Bin3 = <<6>>.
2288 <<6>>
2289 > iolist_to_binary([Bin1,1,[2,3,Bin2],4|Bin3]).
2290 <<1,2,3,1,2,3,4,5,4,6>>
2291 erlang:iolist_to_iovec(IoListOrBinary) -> iovec()
2293 Types:
2295 IoListOrBinary = iolist() | binary()
2297 Returns an iovec that is made from the integers and binaries in
2299 IoListOrBinary.
2300 is_alive() -> boolean()
2302 Returns true if the local node is alive (that is, if the node
2304 can be part of a distributed system), otherwise false.
2305 is_atom(Term) -> boolean()
2307 Types:
2309 Term = term()
2311 Returns true if Term is an atom, otherwise false.
2313 Allowed in guard tests.
2315 is_binary(Term) -> boolean()
2317 Types:
2319 Term = term()
2321 Returns true if Term is a binary, otherwise false.
2323 A binary always contains a complete number of bytes.
2325 Allowed in guard tests.
2327 is_bitstring(Term) -> boolean()
2329 Types:
2331 Term = term()
2333 Returns true if Term is a bitstring (including a binary), other‐
2335 wise false.
2336 Allowed in guard tests.
2338 is_boolean(Term) -> boolean()
2340 Types:
2342 Term = term()
2344 Returns true if Term is the atom true or the atom false (that
2346 is, a boolean). Otherwise returns false.
2347 Allowed in guard tests.
2349 erlang:is_builtin(Module, Function, Arity) -> boolean()
2351 Types:
2353 Module = module()
2355 Function = atom()
2356 Arity = arity()
2357 This BIF is useful for builders of cross-reference tools.
2359 Returns true if Module:Function/Arity is a BIF implemented in C,
2361 otherwise false.
2362 is_float(Term) -> boolean()
2364 Types:
2366 Term = term()
2368 Returns true if Term is a floating point number, otherwise
2370 false.
2371 Allowed in guard tests.
2373 is_function(Term) -> boolean()
2375 Types:
2377 Term = term()
2379 Returns true if Term is a fun, otherwise false.
2381 Allowed in guard tests.
2383 is_function(Term, Arity) -> boolean()
2385 Types:
2387 Term = term()
2389 Arity = arity()
2390 Returns true if Term is a fun that can be applied with Arity
2392 number of arguments, otherwise false.
2393 Allowed in guard tests.
2395 is_integer(Term) -> boolean()
2397 Types:
2399 Term = term()
2401 Returns true if Term is an integer, otherwise false.
2403 Allowed in guard tests.
2405 is_list(Term) -> boolean()
2407 Types:
2409 Term = term()
2411 Returns true if Term is a list with zero or more elements, oth‐
2413 erwise false.
2414 Allowed in guard tests.
2416 is_map(Term) -> boolean()
2418 Types:
2420 Term = term()
2422 Returns true if Term is a map, otherwise false.
2424 Allowed in guard tests.
2426 is_map_key(Key, Map) -> boolean()
2428 Types:
2430 Key = term()
2432 Map = map()
2433 Returns true if map Map contains Key and returns false if it
2435 does not contain the Key.
2436 The call fails with a {badmap,Map} exception if Map is not a
2438 map.
2439 Example:
2441 > Map = #{"42" => value}.
2443 #{"42" => value}
2444 > is_map_key("42",Map).
2445 true
2446 > is_map_key(value,Map).
2447 false
2448 Allowed in guard tests.
2450 is_number(Term) -> boolean()
2452 Types:
2454 Term = term()
2456 Returns true if Term is an integer or a floating point number.
2458 Otherwise returns false.
2459 Allowed in guard tests.
2461 is_pid(Term) -> boolean()
2463 Types:
2465 Term = term()
2467 Returns true if Term is a process identifier, otherwise false.
2469 Allowed in guard tests.
2471 is_port(Term) -> boolean()
2473 Types:
2475 Term = term()
2477 Returns true if Term is a port identifier, otherwise false.
2479 Allowed in guard tests.
2481 is_process_alive(Pid) -> boolean()
2483 Types:
2485 Pid = pid()
2487 Pid must refer to a process at the local node.
2489 Returns true if the process exists and is alive, that is, is not
2491 exiting and has not exited. Otherwise returns false.
2492 is_record(Term, RecordTag) -> boolean()
2494 Types:
2496 Term = term()
2498 RecordTag = atom()
2499 Returns true if Term is a tuple and its first element is Record‐
2501 Tag. Otherwise returns false.
2502 Note:
2504 Normally the compiler treats calls to is_record/2 especially. It
2505 emits code to verify that Term is a tuple, that its first ele‐
2506 ment is RecordTag, and that the size is correct. However, if
2507 RecordTag is not a literal atom, the BIF is_record/2 is called
2508 instead and the size of the tuple is not verified.
2509 Allowed in guard tests, if RecordTag is a literal atom.
2512 is_record(Term, RecordTag, Size) -> boolean()
2514 Types:
2516 Term = term()
2518 RecordTag = atom()
2519 Size = integer() >= 0
2520 RecordTag must be an atom.
2522 Returns true if Term is a tuple, its first element is RecordTag,
2524 and its size is Size. Otherwise returns false.
2525 Allowed in guard tests if RecordTag is a literal atom and Size
2527 is a literal integer.
2528 Note:
2530 This BIF is documented for completeness. Usually is_record/2 is
2531 to be used.
2532 is_reference(Term) -> boolean()
2535 Types:
2537 Term = term()
2539 Returns true if Term is a reference, otherwise false.
2541 Allowed in guard tests.
2543 is_tuple(Term) -> boolean()
2545 Types:
2547 Term = term()
2549 Returns true if Term is a tuple, otherwise false.
2551 Allowed in guard tests.
2553 length(List) -> integer() >= 0
2555 Types:
2557 List = [term()]
2559 Returns the length of List, for example:
2561 > length([1,2,3,4,5,6,7,8,9]).
2563 9
2564 Allowed in guard tests.
2566 link(PidOrPort) -> true
2568 Types:
2570 PidOrPort = pid() | port()
2572 Sets up and activates a link between the calling process and
2574 another process or a port identified by PidOrPort. We will from
2575 here on call the identified process or port linkee. If the lin‐
2576 kee is a port, it must reside on the same node as the caller.
2577 If one of the participants of a link terminates, it will send an
2579 exit signal to the other participant. The exit signal will con‐
2580 tain the exit reason of the terminated participant. Other cases
2581 when exit signals are triggered due to a link are when no linkee
2582 exist (noproc exit reason) and when the connection between
2583 linked processes on different nodes is lost or cannot be estab‐
2584 lished (noconnection exit reason).
2585 An existing link can be removed by calling unlink/1. For more
2587 information on links and exit signals due to links, see the Pro‐
2588 cesses chapter in the Erlang Reference Manual :
2589 * Links
2591 * Sending Exit Signals
2593 * Receiving Exit Signals
2595 For historical reasons, link/1 has a strange semi-synchronous
2597 behavior when it is "cheap" to check if the linkee exists or
2598 not, and the caller does not trap exits. If the above is true
2599 and the linkee does not exist, link/1 will raise a noproc error
2600 exception. The expected behavior would instead have been that
2601 link/1 returned true, and the caller later was sent an exit sig‐
2602 nal with noproc exit reason, but this is unfortunately not the
2603 case. The noproc exception is not to be confused with an exit
2604 signal with exit reason noproc. Currently it is "cheap" to check
2605 if the linkee exists when it is supposed to reside on the same
2606 node as the calling process.
2607 The link setup and activation is performed asynchronously. If
2609 the link already exists, or if the caller attempts to create a
2610 link to itself, nothing is done. A detailed description of the
2611 link protocol can be found in the Distribution Protocol chapter
2612 of the ERTS User's Guide .
2613 Failure:
2615 * badarg if PidOrPort does not identify a process or a node
2617 local port.
2618 * noproc linkee does not exist and it is "cheap" to check if
2620 it exists as described above.
2621 list_to_atom(String) -> atom()
2623 Types:
2625 String = string()
2627 Returns the atom whose text representation is String.
2629 As from Erlang/OTP 20, String may contain any Unicode character.
2631 Earlier versions allowed only ISO-latin-1 characters as the
2632 implementation did not allow Unicode characters above 255. For
2633 more information on Unicode support in atoms, see note on UTF-8
2634 encoded atoms in section "External Term Format" in the User's
2635 Guide.
2636 Example:
2638 > list_to_atom("Erlang").
2640 list_to_binary(IoList) -> binary()
2642 Types:
2644 IoList = iolist()
2646 Returns a binary that is made from the integers and binaries in
2648 IoList, for example:
2649 > Bin1 = <<1,2,3>>.
2651 <<1,2,3>>
2652 > Bin2 = <<4,5>>.
2653 <<4,5>>
2654 > Bin3 = <<6>>.
2655 <<6>>
2656 > list_to_binary([Bin1,1,[2,3,Bin2],4|Bin3]).
2657 <<1,2,3,1,2,3,4,5,4,6>>
2658 list_to_bitstring(BitstringList) -> bitstring()
2660 Types:
2662 BitstringList = bitstring_list()
2664 bitstring_list() =
2665 maybe_improper_list(byte() | bitstring() | bitstring_list(),
2666 bitstring() | [])
2667 Returns a bitstring that is made from the integers and bit‐
2669 strings in BitstringList. (The last tail in BitstringList is
2670 allowed to be a bitstring.) Example:
2671 > Bin1 = <<1,2,3>>.
2673 <<1,2,3>>
2674 > Bin2 = <<4,5>>.
2675 <<4,5>>
2676 > Bin3 = <<6,7:4>>.
2677 <<6,7:4>>
2678 > list_to_bitstring([Bin1,1,[2,3,Bin2],4|Bin3]).
2679 <<1,2,3,1,2,3,4,5,4,6,7:4>>
2680 list_to_existing_atom(String) -> atom()
2682 Types:
2684 String = string()
2686 Returns the atom whose text representation is String, but only
2688 if there already exists such atom.
2689 Failure: badarg if there does not already exist an atom whose
2691 text representation is String.
2692 Note:
2694 Note that the compiler may optimize away atoms. For example, the
2695 compiler will rewrite atom_to_list(some_atom) to "some_atom". If
2696 that expression is the only mention of the atom some_atom in the
2697 containing module, the atom will not be created when the module
2698 is loaded, and a subsequent call to list_to_exist‐
2699 ing_atom("some_atom") will fail.
2700 list_to_float(String) -> float()
2703 Types:
2705 String = string()
2707 Returns the float whose text representation is String, for exam‐
2709 ple:
2710 > list_to_float("2.2017764e+0").
2712 2.2017764
2713 Failure: badarg if String contains a bad representation of a
2715 float.
2716 list_to_integer(String) -> integer()
2718 Types:
2720 String = string()
2722 Returns an integer whose text representation is String, for
2724 example:
2725 > list_to_integer("123").
2727 123
2728 Failure: badarg if String contains a bad representation of an
2730 integer.
2731 list_to_integer(String, Base) -> integer()
2733 Types:
2735 String = string()
2737 Base = 2..36
2738 Returns an integer whose text representation in base Base is
2740 String, for example:
2741 > list_to_integer("3FF", 16).
2743 1023
2744 Failure: badarg if String contains a bad representation of an
2746 integer.
2747 list_to_pid(String) -> pid()
2749 Types:
2751 String = string()
2753 Returns a process identifier whose text representation is a
2755 String, for example:
2756 > list_to_pid("<0.4.1>").
2758 <0.4.1>
2759 Failure: badarg if String contains a bad representation of a
2761 process identifier.
2762 Warning:
2764 This BIF is intended for debugging and is not to be used in
2765 application programs.
2766 list_to_port(String) -> port()
2769 Types:
2771 String = string()
2773 Returns a port identifier whose text representation is a String,
2775 for example:
2776 > list_to_port("#Port<0.4>").
2778 #Port<0.4>
2779 Failure: badarg if String contains a bad representation of a
2781 port identifier.
2782 Warning:
2784 This BIF is intended for debugging and is not to be used in
2785 application programs.
2786 list_to_ref(String) -> reference()
2789 Types:
2791 String = string()
2793 Returns a reference whose text representation is a String, for
2795 example:
2796 > list_to_ref("#Ref<0.4192537678.4073193475.71181>").
2798 #Ref<0.4192537678.4073193475.71181>
2799 Failure: badarg if String contains a bad representation of a
2801 reference.
2802 Warning:
2804 This BIF is intended for debugging and is not to be used in
2805 application programs.
2806 list_to_tuple(List) -> tuple()
2809 Types:
2811 List = [term()]
2813 Returns a tuple corresponding to List, for example
2815 > list_to_tuple([share, ['Ericsson_B', 163]]).
2817 {share, ['Ericsson_B', 163]}
2818 List can contain any Erlang terms.
2820 load_module(Module, Binary) -> {module, Module} | {error, Reason}
2822 Types:
2824 Module = module()
2826 Binary = binary()
2827 Reason = badfile | not_purged | on_load
2828 If Binary contains the object code for module Module, this BIF
2830 loads that object code. If the code for module Module already
2831 exists, all export references are replaced so they point to the
2832 newly loaded code. The previously loaded code is kept in the
2833 system as old code, as there can still be processes executing
2834 that code.
2835 Returns either {module, Module}, or {error, Reason} if loading
2837 fails. Reason is one of the following:
2838 badfile:
2840 The object code in Binary has an incorrect format or the
2841 object code contains code for another module than Module.
2842 not_purged:
2844 Binary contains a module that cannot be loaded because old
2845 code for this module already exists.
2846 Warning:
2848 This BIF is intended for the code server (see code(3)) and is
2849 not to be used elsewhere.
2850 erlang:load_nif(Path, LoadInfo) -> ok | Error
2853 Types:
2855 Path = string()
2857 LoadInfo = term()
2858 Error = {error, {Reason, Text :: string()}}
2859 Reason =
2860 load_failed | bad_lib | load | reload | upgrade |
2861 old_code
2862 Loads and links a dynamic library containing native implemented
2864 functions (NIFs) for a module. Path is a file path to the share‐
2865 able object/dynamic library file minus the OS-dependent file
2866 extension (.so for Unix and .dll for Windows). Notice that on
2867 most OSs the library has to have a different name on disc when
2868 an upgrade of the nif is done. If the name is the same, but the
2869 contents differ, the old library may be loaded instead. For
2870 information on how to implement a NIF library, see erl_nif(3).
2871 LoadInfo can be any term. It is passed on to the library as part
2873 of the initialization. A good practice is to include a module
2874 version number to support future code upgrade scenarios.
2875 The call to load_nif/2 must be made directly from the Erlang
2877 code of the module that the NIF library belongs to. It returns
2878 either ok, or {error,{Reason,Text}} if loading fails. Reason is
2879 one of the following atoms while Text is a human readable string
2880 that can give more information about the failure:
2881 load_failed:
2883 The OS failed to load the NIF library.
2884 bad_lib:
2886 The library did not fulfill the requirements as a NIF
2887 library of the calling module.
2888 load | upgrade:
2890 The corresponding library callback was unsuccessful.
2891 reload:
2893 A NIF library is already loaded for this module instance.
2894 The previously deprecated reload feature was removed in OTP
2895 20.
2896 old_code:
2898 The call to load_nif/2 was made from the old code of a mod‐
2899 ule that has been upgraded; this is not allowed.
2900 notsup:
2902 Lack of support. Such as loading NIF library for a HiPE com‐
2903 piled module.
2904 erlang:loaded() -> [Module]
2906 Types:
2908 Module = module()
2910 Returns a list of all loaded Erlang modules (current and old
2912 code), including preloaded modules.
2913 See also code(3).
2915 erlang:localtime() -> DateTime
2917 Types:
2919 DateTime = calendar:datetime()
2921 Returns the current local date and time, {{Year, Month, Day},
2923 {Hour, Minute, Second}}, for example:
2924 > erlang:localtime().
2926 {{1996,11,6},{14,45,17}}
2927 The time zone and Daylight Saving Time correction depend on the
2929 underlying OS.
2930 erlang:localtime_to_universaltime(Localtime) -> Universaltime
2932 Types:
2934 Localtime = Universaltime = calendar:datetime()
2936 Converts local date and time to Universal Time Coordinated
2938 (UTC), if supported by the underlying OS. Otherwise no conver‐
2939 sion is done and Localtime is returned. Example:
2940 > erlang:localtime_to_universaltime({{1996,11,6},{14,45,17}}).
2942 {{1996,11,6},{13,45,17}}
2943 Failure: badarg if Localtime denotes an invalid date and time.
2945 erlang:localtime_to_universaltime(Localtime, IsDst) ->
2947 Universaltime
2948 Types:
2950 Localtime = Universaltime = calendar:datetime()
2952 IsDst = true | false | undefined
2953 Converts local date and time to Universal Time Coordinated (UTC)
2955 as erlang:localtime_to_universaltime/1, but the caller decides
2956 if Daylight Saving Time is active.
2957 If IsDst == true, Localtime is during Daylight Saving Time, if
2959 IsDst == false it is not. If IsDst == undefined, the underlying
2960 OS can guess, which is the same as calling erlang:local‐
2961 time_to_universaltime(Localtime).
2962 Examples:
2964 > erlang:localtime_to_universaltime({{1996,11,6},{14,45,17}}, true).
2966 {{1996,11,6},{12,45,17}}
2967 > erlang:localtime_to_universaltime({{1996,11,6},{14,45,17}}, false).
2968 {{1996,11,6},{13,45,17}}
2969 > erlang:localtime_to_universaltime({{1996,11,6},{14,45,17}}, undefined).
2970 {{1996,11,6},{13,45,17}}
2971 Failure: badarg if Localtime denotes an invalid date and time.
2973 make_ref() -> reference()
2975 Returns a unique reference. The reference is unique among con‐
2977 nected nodes.
2978 Warning:
2980 Known issue: When a node is restarted multiple times with the
2981 same node name, references created on a newer node can be mis‐
2982 taken for a reference created on an older node with the same
2983 node name.
2984 erlang:make_tuple(Arity, InitialValue) -> tuple()
2987 Types:
2989 Arity = arity()
2991 InitialValue = term()
2992 Creates a new tuple of the specified Arity, where all elements
2994 are InitialValue, for example:
2995 > erlang:make_tuple(4, []).
2997 {[],[],[],[]}
2998 erlang:make_tuple(Arity, DefaultValue, InitList) -> tuple()
3000 Types:
3002 Arity = arity()
3004 DefaultValue = term()
3005 InitList = [{Position :: integer() >= 1, term()}]
3006 Creates a tuple of size Arity, where each element has value
3008 DefaultValue, and then fills in values from InitList. Each list
3009 element in InitList must be a two-tuple, where the first element
3010 is a position in the newly created tuple and the second element
3011 is any term. If a position occurs more than once in the list,
3012 the term corresponding to the last occurrence is used. Example:
3013 > erlang:make_tuple(5, [], [{2,ignored},{5,zz},{2,aa}]).
3015 {[],aa,[],[],zz}
3016 map_get(Key, Map) -> Value
3018 Types:
3020 Map = map()
3022 Key = Value = any()
3023 Returns value Value associated with Key if Map contains Key.
3025 The call fails with a {badmap,Map} exception if Map is not a
3027 map, or with a {badkey,Key} exception if no value is associated
3028 with Key.
3029 Example:
3031 > Key = 1337,
3033 Map = #{42 => value_two,1337 => "value one","a" => 1},
3034 map_get(Key,Map).
3035 "value one"
3036 Allowed in guard tests.
3038 map_size(Map) -> integer() >= 0
3040 Types:
3042 Map = map()
3044 Returns an integer, which is the number of key-value pairs in
3046 Map, for example:
3047 > map_size(#{a=>1, b=>2, c=>3}).
3049 3
3050 Allowed in guard tests.
3052 erlang:match_spec_test(MatchAgainst, MatchSpec, Type) ->
3054 TestResult
3055 Types:
3057 MatchAgainst = [term()] | tuple()
3059 MatchSpec = term()
3060 Type = table | trace
3061 TestResult =
3062 {ok, term(), [return_trace], [{error | warning,
3063 string()}]} |
3064 {error, [{error | warning, string()}]}
3065 Tests a match specification used in calls to ets:select/2 and
3067 erlang:trace_pattern/3. The function tests both a match specifi‐
3068 cation for "syntactic" correctness and runs the match specifica‐
3069 tion against the object. If the match specification contains
3070 errors, the tuple {error, Errors} is returned, where Errors is a
3071 list of natural language descriptions of what was wrong with the
3072 match specification.
3073 If Type is table, the object to match against is to be a tuple.
3075 The function then returns {ok,Result,[],Warnings}, where Result
3076 is what would have been the result in a real ets:select/2 call,
3077 or false if the match specification does not match the object
3078 tuple.
3079 If Type is trace, the object to match against is to be a list.
3081 The function returns {ok, Result, Flags, Warnings}, where Result
3082 is one of the following:
3083 * true if a trace message is to be emitted
3085 * false if a trace message is not to be emitted
3087 * The message term to be appended to the trace message
3089 Flags is a list containing all the trace flags to be enabled,
3091 currently this is only return_trace.
3092 This is a useful debugging and test tool, especially when writ‐
3094 ing complicated match specifications.
3095 See also ets:test_ms/2.
3097 max(Term1, Term2) -> Maximum
3099 Types:
3101 Term1 = Term2 = Maximum = term()
3103 Returns the largest of Term1 and Term2. If the terms are equal,
3105 Term1 is returned.
3106 erlang:md5(Data) -> Digest
3108 Types:
3110 Data = iodata()
3112 Digest = binary()
3113 Computes an MD5 message digest from Data, where the length of
3115 the digest is 128 bits (16 bytes). Data is a binary or a list of
3116 small integers and binaries.
3117 For more information about MD5, see RFC 1321 - The MD5 Message-
3119 Digest Algorithm.
3120 Warning:
3122 The MD5 Message-Digest Algorithm is not considered safe for
3123 code-signing or software-integrity purposes.
3124 erlang:md5_final(Context) -> Digest
3127 Types:
3129 Context = Digest = binary()
3131 Finishes the update of an MD5 Context and returns the computed
3133 MD5 message digest.
3134 erlang:md5_init() -> Context
3136 Types:
3138 Context = binary()
3140 Creates an MD5 context, to be used in the following calls to
3142 md5_update/2.
3143 erlang:md5_update(Context, Data) -> NewContext
3145 Types:
3147 Context = binary()
3149 Data = iodata()
3150 NewContext = binary()
3151 Update an MD5 Context with Data and returns a NewContext.
3153 erlang:memory() -> [{Type, Size}]
3155 Types:
3157 Type = memory_type()
3159 Size = integer() >= 0
3160 memory_type() =
3161 total | processes | processes_used | system | atom |
3162 atom_used | binary | code | ets
3163 Returns a list with information about memory dynamically allo‐
3165 cated by the Erlang emulator. Each list element is a tuple
3166 {Type, Size}. The first element Type is an atom describing mem‐
3167 ory type. The second element Size is the memory size in bytes.
3168 Memory types:
3170 total:
3172 The total amount of memory currently allocated. This is the
3173 same as the sum of the memory size for processes and system.
3174 processes:
3176 The total amount of memory currently allocated for the
3177 Erlang processes.
3178 processes_used:
3180 The total amount of memory currently used by the Erlang pro‐
3181 cesses. This is part of the memory presented as processes
3182 memory.
3183 system:
3185 The total amount of memory currently allocated for the emu‐
3186 lator that is not directly related to any Erlang process.
3187 Memory presented as processes is not included in this mem‐
3188 ory. instrument(3) can be used to get a more detailed break‐
3189 down of what memory is part of this type.
3190 atom:
3192 The total amount of memory currently allocated for atoms.
3193 This memory is part of the memory presented as system mem‐
3194 ory.
3195 atom_used:
3197 The total amount of memory currently used for atoms. This
3198 memory is part of the memory presented as atom memory.
3199 binary:
3201 The total amount of memory currently allocated for binaries.
3202 This memory is part of the memory presented as system mem‐
3203 ory.
3204 code:
3206 The total amount of memory currently allocated for Erlang
3207 code. This memory is part of the memory presented as system
3208 memory.
3209 ets:
3211 The total amount of memory currently allocated for ETS
3212 tables. This memory is part of the memory presented as sys‐
3213 tem memory.
3214 low:
3216 Only on 64-bit halfword emulator. The total amount of memory
3217 allocated in low memory areas that are restricted to < 4 GB,
3218 although the system can have more memory.
3219 Can be removed in a future release of the halfword emulator.
3221 maximum:
3223 The maximum total amount of memory allocated since the emu‐
3224 lator was started. This tuple is only present when the emu‐
3225 lator is run with instrumentation.
3226 For information on how to run the emulator with instrumenta‐
3228 tion, see instrument(3) and/or erl(1).
3229 Note:
3231 The system value is not complete. Some allocated memory that is
3232 to be part of this value is not.
3233 When the emulator is run with instrumentation, the system value
3235 is more accurate, but memory directly allocated for malloc (and
3236 friends) is still not part of the system value. Direct calls to
3237 malloc are only done from OS-specific runtime libraries and per‐
3238 haps from user-implemented Erlang drivers that do not use the
3239 memory allocation functions in the driver interface.
3240 As the total value is the sum of processes and system, the error
3242 in system propagates to the total value.
3243 The different amounts of memory that are summed are not gathered
3245 atomically, which introduces an error in the result.
3246 The different values have the following relation to each other.
3249 Values beginning with an uppercase letter is not part of the
3250 result.
3251 total = processes + system
3253 processes = processes_used + ProcessesNotUsed
3254 system = atom + binary + code + ets + OtherSystem
3255 atom = atom_used + AtomNotUsed
3256 RealTotal = processes + RealSystem
3257 RealSystem = system + MissedSystem
3258 More tuples in the returned list can be added in a future
3260 release.
3261 Note:
3263 The total value is supposed to be the total amount of memory
3264 dynamically allocated by the emulator. Shared libraries, the
3265 code of the emulator itself, and the emulator stacks are not
3266 supposed to be included. That is, the total value is not sup‐
3267 posed to be equal to the total size of all pages mapped to the
3268 emulator.
3269 Also, because of fragmentation and prereservation of memory
3271 areas, the size of the memory segments containing the dynami‐
3272 cally allocated memory blocks can be much larger than the total
3273 size of the dynamically allocated memory blocks.
3274 Note:
3277 As from ERTS 5.6.4, erlang:memory/0 requires that all
3278 erts_alloc(3) allocators are enabled (default behavior).
3279 Failure: notsup if an erts_alloc(3) allocator has been disabled.
3282 erlang:memory(Type :: memory_type()) -> integer() >= 0
3284 erlang:memory(TypeList :: [memory_type()]) ->
3286 [{memory_type(), integer() >= 0}]
3287 Types:
3289 memory_type() =
3291 total | processes | processes_used | system | atom |
3292 atom_used | binary | code | ets
3293 Returns the memory size in bytes allocated for memory of type
3295 Type. The argument can also be specified as a list of mem‐
3296 ory_type() atoms, in which case a corresponding list of {mem‐
3297 ory_type(), Size :: integer >= 0} tuples is returned.
3298 Note:
3300 As from ERTS 5.6.4, erlang:memory/1 requires that all
3301 erts_alloc(3) allocators are enabled (default behavior).
3302 Failures:
3305 badarg:
3307 If Type is not one of the memory types listed in the
3308 description of erlang:memory/0.
3309 badarg:
3311 If maximum is passed as Type and the emulator is not run in
3312 instrumented mode.
3313 notsup:
3315 If an erts_alloc(3) allocator has been disabled.
3316 See also erlang:memory/0.
3318 min(Term1, Term2) -> Minimum
3320 Types:
3322 Term1 = Term2 = Minimum = term()
3324 Returns the smallest of Term1 and Term2. If the terms are equal,
3326 Term1 is returned.
3327 module_loaded(Module) -> boolean()
3329 Types:
3331 Module = module()
3333 Returns true if the module Module is loaded, otherwise false. It
3335 does not attempt to load the module.
3336 Warning:
3338 This BIF is intended for the code server (see code(3)) and is
3339 not to be used elsewhere.
3340 monitor(Type :: process, Item :: monitor_process_identifier()) ->
3343 MonitorRef
3344 monitor(Type :: port, Item :: monitor_port_identifier()) ->
3346 MonitorRef
3347 monitor(Type :: time_offset, Item :: clock_service) -> MonitorRef
3349 Types:
3351 MonitorRef = reference()
3353 registered_name() = atom()
3354 registered_process_identifier() =
3355 registered_name() | {registered_name(), node()}
3356 monitor_process_identifier() =
3357 pid() | registered_process_identifier()
3358 monitor_port_identifier() = port() | registered_name()
3359 Sends a monitor request of type Type to the entity identified by
3361 Item. If the monitored entity does not exist or it changes moni‐
3362 tored state, the caller of monitor/2 is notified by a message on
3363 the following format:
3364 {Tag, MonitorRef, Type, Object, Info}
3366 Note:
3368 The monitor request is an asynchronous signal. That is, it takes
3369 time before the signal reaches its destination.
3370 Type can be one of the following atoms: process, port or
3373 time_offset.
3374 A process or port monitor is triggered only once, after that it
3376 is removed from both monitoring process and the monitored
3377 entity. Monitors are fired when the monitored process or port
3378 terminates, does not exist at the moment of creation, or if the
3379 connection to it is lost. If the connection to it is lost, we do
3380 not know if it still exists. The monitoring is also turned off
3381 when demonitor/1 is called.
3382 A process or port monitor by name resolves the RegisteredName to
3384 pid() or port() only once at the moment of monitor instantia‐
3385 tion, later changes to the name registration will not affect the
3386 existing monitor.
3387 When a process or port monitor is triggered, a 'DOWN' message is
3389 sent that has the following pattern:
3390 {'DOWN', MonitorRef, Type, Object, Info}
3392 In the monitor message MonitorRef and Type are the same as
3394 described earlier, and:
3395 Object:
3397 The monitored entity, which triggered the event. When moni‐
3398 toring a local process or port, Object will be equal to the
3399 pid() or port() that was being monitored. When monitoring
3400 process or port by name, Object will have format {Regis‐
3401 teredName, Node} where RegisteredName is the name which has
3402 been used with monitor/2 call and Node is local or remote
3403 node name (for ports monitored by name, Node is always local
3404 node name).
3405 Info:
3407 Either the exit reason of the process, noproc (process or
3408 port did not exist at the time of monitor creation), or
3409 noconnection (no connection to the node where the monitored
3410 process resides).
3411 Monitoring a process:
3413 Creates monitor between the current process and another
3414 process identified by Item, which can be a pid() (local or
3415 remote), an atom RegisteredName or a tuple {RegisteredName,
3416 Node} for a registered process, located elsewhere.
3417 Note:
3419 Before ERTS 10.0 (OTP 21.0), monitoring a process could fail
3420 with badarg if the monitored process resided on a primitive
3421 node (such as erl_interface or jinterface), where remote
3422 process monitoring is not implemented.
3423 Now, such a call to monitor will instead succeed and a monitor
3425 is created. But the monitor will only supervise the connec‐
3426 tion. That is, a {'DOWN', _, process, _, noconnection} is the
3427 only message that may be received, as the primitive node have
3428 no way of reporting the status of the monitored process.
3429 Monitoring a port:
3432 Creates monitor between the current process and a port iden‐
3433 tified by Item, which can be a port() (only local), an atom
3434 RegisteredName or a tuple {RegisteredName, Node} for a reg‐
3435 istered port, located on this node. Note, that attempt to
3436 monitor a remote port will result in badarg.
3437 Monitoring a time_offset:
3439 Monitors changes in time offset between Erlang monotonic
3440 time and Erlang system time. One valid Item exists in combi‐
3441 nation with the time_offset Type, namely the atom clock_ser‐
3442 vice. Notice that the atom clock_service is not the regis‐
3443 tered name of a process. In this case it serves as an iden‐
3444 tifier of the runtime system internal clock service at cur‐
3445 rent runtime system instance.
3446 The monitor is triggered when the time offset is changed.
3448 This either if the time offset value is changed, or if the
3449 offset is changed from preliminary to final during finaliza‐
3450 tion of the time offset when the single time warp mode is
3451 used. When a change from preliminary to final time offset is
3452 made, the monitor is triggered once regardless of whether
3453 the time offset value was changed or not.
3454 If the runtime system is in multi time warp mode, the time
3456 offset is changed when the runtime system detects that the
3457 OS system time has changed. The runtime system does, how‐
3458 ever, not detect this immediately when it occurs. A task
3459 checking the time offset is scheduled to execute at least
3460 once a minute, so under normal operation this is to be
3461 detected within a minute, but during heavy load it can take
3462 longer time.
3463 The monitor is not automatically removed after it has been
3465 triggered. That is, repeated changes of the time offset
3466 trigger the monitor repeatedly.
3467 When the monitor is triggered a 'CHANGE' message is sent to
3469 the monitoring process. A 'CHANGE' message has the following
3470 pattern:
3471 {'CHANGE', MonitorRef, Type, Item, NewTimeOffset}
3473 where MonitorRef, Type, and Item are the same as described
3475 above, and NewTimeOffset is the new time offset.
3476 When the 'CHANGE' message has been received you are guaran‐
3478 teed not to retrieve the old time offset when calling
3479 erlang:time_offset(). Notice that you can observe the change
3480 of the time offset when calling erlang:time_offset() before
3481 you get the 'CHANGE' message.
3482 Making several calls to monitor/2 for the same Item and/or Type
3484 is not an error; it results in as many independent monitoring
3485 instances.
3486 The monitor functionality is expected to be extended. That is,
3488 other Types and Items are expected to be supported in a future
3489 release.
3490 Note:
3492 If or when monitor/2 is extended, other possible values for Tag,
3493 Object, and Info in the monitor message will be introduced.
3494 monitor_node(Node, Flag) -> true
3497 Types:
3499 Node = node()
3501 Flag = boolean()
3502 Monitor the status of the node Node. If Flag is true, monitoring
3504 is turned on. If Flag is false, monitoring is turned off.
3505 Making several calls to monitor_node(Node, true) for the same
3507 Node is not an error; it results in as many independent monitor‐
3508 ing instances.
3509 If Node fails or does not exist, the message {nodedown, Node} is
3511 delivered to the process. If a process has made two calls to
3512 monitor_node(Node, true) and Node terminates, two nodedown mes‐
3513 sages are delivered to the process. If there is no connection to
3514 Node, an attempt is made to create one. If this fails, a node‐
3515 down message is delivered.
3516 Nodes connected through hidden connections can be monitored as
3518 any other nodes.
3519 Failure: badarg if the local node is not alive.
3521 erlang:monitor_node(Node, Flag, Options) -> true
3523 Types:
3525 Node = node()
3527 Flag = boolean()
3528 Options = [Option]
3529 Option = allow_passive_connect
3530 Behaves as monitor_node/2 except that it allows an extra option
3532 to be specified, namely allow_passive_connect. This option
3533 allows the BIF to wait the normal network connection time-out
3534 for the monitored node to connect itself, even if it cannot be
3535 actively connected from this node (that is, it is blocked). The
3536 state where this can be useful can only be achieved by using the
3537 Kernel option dist_auto_connect once. If that option is not
3538 used, option allow_passive_connect has no effect.
3539 Note:
3541 Option allow_passive_connect is used internally and is seldom
3542 needed in applications where the network topology and the Kernel
3543 options in effect are known in advance.
3544 Failure: badarg if the local node is not alive or the option
3547 list is malformed.
3548 erlang:monotonic_time() -> integer()
3550 Returns the current Erlang monotonic time in native time unit.
3552 This is a monotonically increasing time since some unspecified
3553 point in time.
3554 Note:
3556 This is a monotonically increasing time, but not a strictly
3557 monotonically increasing time. That is, consecutive calls to
3558 erlang:monotonic_time/0 can produce the same result.
3559 Different runtime system instances will use different unspeci‐
3561 fied points in time as base for their Erlang monotonic clocks.
3562 That is, it is pointless comparing monotonic times from differ‐
3563 ent runtime system instances. Different runtime system instances
3564 can also place this unspecified point in time different relative
3565 runtime system start. It can be placed in the future (time at
3566 start is a negative value), the past (time at start is a posi‐
3567 tive value), or the runtime system start (time at start is
3568 zero). The monotonic time at runtime system start can be
3569 retrieved by calling erlang:system_info(start_time).
3570 erlang:monotonic_time(Unit) -> integer()
3573 Types:
3575 Unit = time_unit()
3577 Returns the current Erlang monotonic time converted into the
3579 Unit passed as argument.
3580 Same as calling erlang:convert_time_unit(erlang:mono‐
3582 tonic_time(), native, Unit), however optimized for commonly used
3583 Units.
3584 erlang:nif_error(Reason) -> no_return()
3586 Types:
3588 Reason = term()
3590 Works exactly like error/1, but Dialyzer thinks that this BIF
3592 will return an arbitrary term. When used in a stub function for
3593 a NIF to generate an exception when the NIF library is not
3594 loaded, Dialyzer does not generate false warnings.
3595 erlang:nif_error(Reason, Args) -> no_return()
3597 Types:
3599 Reason = term()
3601 Args = [term()]
3602 Works exactly like error/2, but Dialyzer thinks that this BIF
3604 will return an arbitrary term. When used in a stub function for
3605 a NIF to generate an exception when the NIF library is not
3606 loaded, Dialyzer does not generate false warnings.
3607 node() -> Node
3609 Types:
3611 Node = node()
3613 Returns the name of the local node. If the node is not alive,
3615 nonode@nohost is returned instead.
3616 Allowed in guard tests.
3618 node(Arg) -> Node
3620 Types:
3622 Arg = pid() | port() | reference()
3624 Node = node()
3625 Returns the node where Arg originates. Arg can be a process
3627 identifier, a reference, or a port. If the local node is not
3628 alive, nonode@nohost is returned.
3629 Allowed in guard tests.
3631 nodes() -> Nodes
3633 Types:
3635 Nodes = [node()]
3637 Returns a list of all visible nodes in the system, except the
3639 local node. Same as nodes(visible).
3640 nodes(Arg) -> Nodes
3642 Types:
3644 Arg = NodeType | [NodeType]
3646 NodeType = visible | hidden | connected | this | known
3647 Nodes = [node()]
3648 Returns a list of nodes according to the argument specified. The
3650 returned result, when the argument is a list, is the list of
3651 nodes satisfying the disjunction(s) of the list elements.
3652 NodeTypes:
3654 visible:
3656 Nodes connected to this node through normal connections.
3657 hidden:
3659 Nodes connected to this node through hidden connections.
3660 connected:
3662 All nodes connected to this node.
3663 this:
3665 This node.
3666 known:
3668 Nodes that are known to this node. That is, connected nodes
3669 and nodes referred to by process identifiers, port identi‐
3670 fiers, and references located on this node. The set of known
3671 nodes is garbage collected. Notice that this garbage collec‐
3672 tion can be delayed. For more information, see erlang:sys‐
3673 tem_info(delayed_node_table_gc).
3674 Some equalities: [node()] = nodes(this), nodes(connected) =
3676 nodes([visible, hidden]), and nodes() = nodes(visible).
3677 now() -> Timestamp
3679 Types:
3681 Timestamp = timestamp()
3683 timestamp() =
3684 {MegaSecs :: integer() >= 0,
3685 Secs :: integer() >= 0,
3686 MicroSecs :: integer() >= 0}
3687 Warning:
3689 This function is deprecated. Do not use it.
3690 For more information, see section Time and Time Correction in
3692 the User's Guide. Specifically, section Dos and Dont's
3693 describes what to use instead of erlang:now/0.
3694 Returns the tuple {MegaSecs, Secs, MicroSecs}, which is the
3697 elapsed time since 00:00 GMT, January 1, 1970 (zero hour), if
3698 provided by the underlying OS. Otherwise some other point in
3699 time is chosen. It is also guaranteed that the following calls
3700 to this BIF return continuously increasing values. Hence, the
3701 return value from erlang:now/0 can be used to generate unique
3702 time stamps. If it is called in a tight loop on a fast machine,
3703 the time of the node can become skewed.
3704 Can only be used to check the local time of day if the time-zone
3706 information of the underlying OS is properly configured.
3707 open_port(PortName, PortSettings) -> port()
3709 Types:
3711 PortName =
3713 {spawn, Command :: string() | binary()} |
3714 {spawn_driver, Command :: string() | binary()} |
3715 {spawn_executable, FileName :: file:name_all()} |
3716 {fd, In :: integer() >= 0, Out :: integer() >= 0}
3717 PortSettings = [Opt]
3718 Opt =
3719 {packet, N :: 1 | 2 | 4} |
3720 stream |
3721 {line, L :: integer() >= 0} |
3722 {cd, Dir :: string() | binary()} |
3723 {env,
3724 Env ::
3725 [{Name :: os:env_var_name(),
3726 Val :: os:env_var_value() | false}]} |
3727 {args, [string() | binary()]} |
3728 {arg0, string() | binary()} |
3729 exit_status | use_stdio | nouse_stdio | stderr_to_stdout
3730 |
3731 in | out | binary | eof |
3732 {parallelism, Boolean :: boolean()} |
3733 hide |
3734 {busy_limits_port,
3735 {integer() >= 0, integer() >= 0} | disabled} |
3736 {busy_limits_msgq,
3737 {integer() >= 0, integer() >= 0} | disabled}
3738 Returns a port identifier as the result of opening a new Erlang
3740 port. A port can be seen as an external Erlang process.
3741 The name of the executable as well as the arguments specifed in
3743 cd, env, args, and arg0 are subject to Unicode filename transla‐
3744 tion if the system is running in Unicode filename mode. To avoid
3745 translation or to force, for example UTF-8, supply the exe‐
3746 cutable and/or arguments as a binary in the correct encoding.
3747 For details, see the module file(3), the function
3748 file:native_name_encoding/0 in Kernel, and the Using Unicode in
3749 Erlang User's Guide.
3750 Note:
3752 The characters in the name (if specified as a list) can only be
3753 > 255 if the Erlang virtual machine is started in Unicode file‐
3754 name translation mode. Otherwise the name of the executable is
3755 limited to the ISO Latin-1 character set.
3756 PortNames:
3759 {spawn, Command}:
3761 Starts an external program. Command is the name of the
3762 external program to be run. Command runs outside the Erlang
3763 work space unless an Erlang driver with the name Command is
3764 found. If found, that driver is started. A driver runs in
3765 the Erlang work space, which means that it is linked with
3766 the Erlang runtime system.
3767 For external programs, PATH is searched (or an equivalent
3769 method is used to find programs, depending on the OS). This
3770 is done by invoking the shell on certain platforms. The
3771 first space-separated token of the command is considered as
3772 the name of the executable (or driver). This (among other
3773 things) makes this option unsuitable for running programs
3774 with spaces in filenames or directory names. If spaces in
3775 executable filenames are desired, use {spawn_executable,
3776 Command} instead.
3777 {spawn_driver, Command}:
3779 Works like {spawn, Command}, but demands the first (space-
3780 separated) token of the command to be the name of a loaded
3781 driver. If no driver with that name is loaded, a badarg
3782 error is raised.
3783 {spawn_executable, FileName}:
3785 Works like {spawn, FileName}, but only runs external exe‐
3786 cutables. FileName in its whole is used as the name of the
3787 executable, including any spaces. If arguments are to be
3788 passed, the PortSettings args and arg0 can be used.
3789 The shell is usually not invoked to start the program, it is
3791 executed directly. PATH (or equivalent) is not searched. To
3792 find a program in PATH to execute, use os:find_executable/1.
3793 Only if a shell script or .bat file is executed, the appro‐
3795 priate command interpreter is invoked implicitly, but there
3796 is still no command-argument expansion or implicit PATH
3797 search.
3798 If FileName cannot be run, an error exception is raised,
3800 with the POSIX error code as the reason. The error reason
3801 can differ between OSs. Typically the error enoent is raised
3802 when an attempt is made to run a program that is not found
3803 and eacces is raised when the specified file is not exe‐
3804 cutable.
3805 {fd, In, Out}:
3807 Allows an Erlang process to access any currently opened file
3808 descriptors used by Erlang. The file descriptor In can be
3809 used for standard input, and the file descriptor Out for
3810 standard output. It is only used for various servers in the
3811 Erlang OS (shell and user). Hence, its use is limited.
3812 PortSettings is a list of settings for the port. The valid set‐
3814 tings are as follows:
3815 {packet, N}:
3817 Messages are preceded by their length, sent in N bytes, with
3818 the most significant byte first. The valid values for N are
3819 1, 2, and 4.
3820 stream:
3822 Output messages are sent without packet lengths. A user-
3823 defined protocol must be used between the Erlang process and
3824 the external object.
3825 {line, L}:
3827 Messages are delivered on a per line basis. Each line
3828 (delimited by the OS-dependent newline sequence) is deliv‐
3829 ered in a single message. The message data format is {Flag,
3830 Line}, where Flag is eol or noeol, and Line is the data
3831 delivered (without the newline sequence).
3832 L specifies the maximum line length in bytes. Lines longer
3834 than this are delivered in more than one message, with Flag
3835 set to noeol for all but the last message. If end of file is
3836 encountered anywhere else than immediately following a new‐
3837 line sequence, the last line is also delivered with Flag set
3838 to noeol. Otherwise lines are delivered with Flag set to
3839 eol.
3840 The {packet, N} and {line, L} settings are mutually exclu‐
3842 sive.
3843 {cd, Dir}:
3845 Only valid for {spawn, Command} and {spawn_executable, File‐
3846 Name}. The external program starts using Dir as its working
3847 directory. Dir must be a string.
3848 {env, Env}:
3850 Types:
3851 Name = os:env_var_name()
3852 Val = os:env_var_value() | false
3853 Env = [{Name, Val}]
3854 Only valid for {spawn, Command}, and {spawn_executable,
3856 FileName}. The environment of the started process is
3857 extended using the environment specifications in Env.
3858 Env is to be a list of tuples {Name, Val}, where Name is the
3860 name of an environment variable, and Val is the value it is
3861 to have in the spawned port process. Both Name and Val must
3862 be strings. The one exception is Val being the atom false
3863 (in analogy with os:getenv/1, which removes the environment
3864 variable.
3865 For information about encoding requirements, see documenta‐
3867 tion of the types for Name and Val.
3868 {args, [ string() | binary() ]}:
3870 Only valid for {spawn_executable, FileName} and specifies
3871 arguments to the executable. Each argument is specified as a
3872 separate string and (on Unix) eventually ends up as one ele‐
3873 ment each in the argument vector. On other platforms, a sim‐
3874 ilar behavior is mimicked.
3875 The arguments are not expanded by the shell before they are
3877 supplied to the executable. Most notably this means that
3878 file wildcard expansion does not occur. To expand wildcards
3879 for the arguments, use filelib:wildcard/1. Notice that even
3880 if the program is a Unix shell script, meaning that the
3881 shell ultimately is invoked, wildcard expansion does not
3882 occur, and the script is provided with the untouched argu‐
3883 ments. On Windows, wildcard expansion is always up to the
3884 program itself, therefore this is not an issue.
3885 The executable name (also known as argv[0]) is not to be
3887 specified in this list. The proper executable name is auto‐
3888 matically used as argv[0], where applicable.
3889 If you explicitly want to set the program name in the argu‐
3891 ment vector, option arg0 can be used.
3892 {arg0, string() | binary()}:
3894 Only valid for {spawn_executable, FileName} and explicitly
3895 specifies the program name argument when running an exe‐
3896 cutable. This can in some circumstances, on some OSs, be
3897 desirable. How the program responds to this is highly sys‐
3898 tem-dependent and no specific effect is guaranteed.
3899 exit_status:
3901 Only valid for {spawn, Command}, where Command refers to an
3902 external program, and for {spawn_executable, FileName}.
3903 When the external process connected to the port exits, a
3905 message of the form {Port,{exit_status,Status}} is sent to
3906 the connected process, where Status is the exit status of
3907 the external process. If the program aborts on Unix, the
3908 same convention is used as the shells do (that is, 128+sig‐
3909 nal).
3910 If option eof is specified also, the messages eof and
3912 exit_status appear in an unspecified order.
3913 If the port program closes its stdout without exiting,
3915 option exit_status does not work.
3916 use_stdio:
3918 Only valid for {spawn, Command} and {spawn_executable, File‐
3919 Name}. It allows the standard input and output (file
3920 descriptors 0 and 1) of the spawned (Unix) process for com‐
3921 munication with Erlang.
3922 nouse_stdio:
3924 The opposite of use_stdio. It uses file descriptors 3 and 4
3925 for communication with Erlang.
3926 stderr_to_stdout:
3928 Affects ports to external programs. The executed program
3929 gets its standard error file redirected to its standard out‐
3930 put file. stderr_to_stdout and nouse_stdio are mutually
3931 exclusive.
3932 overlapped_io:
3934 Affects ports to external programs on Windows only. The
3935 standard input and standard output handles of the port pro‐
3936 gram are, if this option is supplied, opened with flag
3937 FILE_FLAG_OVERLAPPED, so that the port program can (and
3938 must) do overlapped I/O on its standard handles. This is not
3939 normally the case for simple port programs, but an option of
3940 value for the experienced Windows programmer. On all other
3941 platforms, this option is silently discarded.
3942 in:
3944 The port can only be used for input.
3945 out:
3947 The port can only be used for output.
3948 binary:
3950 All I/O from the port is binary data objects as opposed to
3951 lists of bytes.
3952 eof:
3954 The port is not closed at the end of the file and does not
3955 produce an exit signal. Instead, it remains open and a
3956 {Port, eof} message is sent to the process holding the port.
3957 hide:
3959 When running on Windows, suppresses creation of a new con‐
3960 sole window when spawning the port program. (This option has
3961 no effect on other platforms.)
3962 {parallelism, Boolean}:
3964 Sets scheduler hint for port parallelism. If set to true,
3967 the virtual machine schedules port tasks; when doing so, it
3968 improves parallelism in the system. If set to false, the
3969 virtual machine tries to perform port tasks immediately,
3970 improving latency at the expense of parallelism. The default
3971 can be set at system startup by passing command-line argu‐
3972 ment +spp to erl(1).
3973 {busy_limits_port, {Low, High} | disabled}:
3975 Sets limits that will be used for controlling the busy state
3976 of the port.
3977 When the ports internal output queue size becomes larger
3979 than or equal to High bytes, it enters the busy state. When
3980 it becomes less than Low bytes it leaves the busy state.
3981 When the port is in the busy state, processes sending com‐
3982 mands to it will be suspended until the port leaves the busy
3983 state. Commands are in this context either Port ! {Owner,
3984 {command, Data}} or port_command/[2,3].
3985 The Low limit is automatically adjusted to the same as High
3987 if it is set larger then High. Valid range of values for Low
3988 and High is [1, (1 bsl (8*erlang:system_info(wordsize)))-2].
3989 If the atom disabled is passed, the port will never enter
3990 the busy state.
3991 The defaults are Low = 4096 and High = 8192.
3993 Note that this option is only valid when spawning an exe‐
3995 cutable (port program) by opening the spawn driver and when
3996 opening the fd driver. This option will cause a failure with
3997 a badarg exception when opening other drivers.
3998 {busy_limits_msgq, {Low, High} | disabled}:
4000 Sets limits that will be used for controlling the busy state
4001 of the port message queue.
4002 When the ports message queue size becomes larger than or
4004 equal to High bytes it enters the busy state. When it
4005 becomes less than Low bytes it leaves the busy state. When
4006 the port message queue is in the busy state, processes send‐
4007 ing commands to it will be suspended until the port message
4008 queue leaves the busy state. Commands are in this context
4009 either Port ! {Owner, {command, Data}} or port_com‐
4010 mand/[2,3].
4011 The Low limit is automatically adjusted to the same as High
4013 if it is set larger then High. Valid range of values for Low
4014 and High is [1, (1 bsl (8*erlang:system_info(wordsize)))-2].
4015 If the atom disabled is passed, the port message queue will
4016 never enter the busy state.
4017 Note that if the driver statically has disabled the use of
4019 this feature, a failure with a badarg exception will be
4020 raised unless this option also is set to disable or not
4021 passed at all.
4022 The defaults are Low = 4096 and High = 8192 unless the
4024 driver itself does modifications of these values.
4025 Note that the driver might fail if it also adjust these lim‐
4027 its by itself and you have disabled this feature.
4028 The spawn driver (used when spawning an executable) and the
4030 fd driver do not disable this feature and do not adjust
4031 these limits by themselves.
4032 For more information see the documentation
4034 erl_drv_busy_msgq_limits().
4035 Default is stream for all port types and use_stdio for spawned
4037 ports.
4038 Failure: if the port cannot be opened, the exit reason is
4040 badarg, system_limit, or the POSIX error code that most closely
4041 describes the error, or einval if no POSIX code is appropriate:
4042 badarg:
4044 Bad input arguments to open_port.
4045 system_limit:
4047 All available ports in the Erlang emulator are in use.
4048 enomem:
4050 Not enough memory to create the port.
4051 eagain:
4053 No more available OS processes.
4054 enametoolong:
4056 Too long external command.
4057 emfile:
4059 No more available file descriptors (for the OS process that
4060 the Erlang emulator runs in).
4061 enfile:
4063 Full file table (for the entire OS).
4064 eacces:
4066 Command specified in {spawn_executable, Command} does not
4067 point out an executable file.
4068 enoent:
4070 FileName specified in {spawn_executable, FileName} does not
4071 point out an existing file.
4072 During use of a port opened using {spawn, Name}, {spawn_driver,
4074 Name}, or {spawn_executable, Name}, errors arising when sending
4075 messages to it are reported to the owning process using signals
4076 of the form {'EXIT', Port, PosixCode}. For the possible values
4077 of PosixCode, see file(3).
4078 The maximum number of ports that can be open at the same time
4080 can be configured by passing command-line flag +Q to erl(1).
4081 erlang:phash(Term, Range) -> Hash
4083 Types:
4085 Term = term()
4087 Range = Hash = integer() >= 1
4088 Range = 1..2^32, Hash = 1..Range
4089 Portable hash function that gives the same hash for the same
4091 Erlang term regardless of machine architecture and ERTS version
4092 (the BIF was introduced in ERTS 4.9.1.1). The function returns a
4093 hash value for Term within the range 1..Range. The maximum value
4094 for Range is 2^32.
4095 erlang:phash2(Term) -> Hash
4097 erlang:phash2(Term, Range) -> Hash
4099 Types:
4101 Term = term()
4103 Range = integer() >= 1
4104 1..2^32
4105 Hash = integer() >= 0
4106 0..Range-1
4107 Portable hash function that gives the same hash for the same
4109 Erlang term regardless of machine architecture and ERTS version
4110 (the BIF was introduced in ERTS 5.2). The function returns a
4111 hash value for Term within the range 0..Range-1. The maximum
4112 value for Range is 2^32. When without argument Range, a value in
4113 the range 0..2^27-1 is returned.
4114 This BIF is always to be used for hashing terms. It distributes
4116 small integers better than phash/2, and it is faster for bignums
4117 and binaries.
4118 Notice that the range 0..Range-1 is different from the range of
4120 phash/2, which is 1..Range.
4121 pid_to_list(Pid) -> string()
4123 Types:
4125 Pid = pid()
4127 Returns a string corresponding to the text representation of
4129 Pid.
4130 erlang:port_call(Port, Operation, Data) -> term()
4132 Types:
4134 Port = port() | atom()
4136 Operation = integer()
4137 Data = term()
4138 Performs a synchronous call to a port. The meaning of Operation
4140 and Data depends on the port, that is, on the port driver. Not
4141 all port drivers support this feature.
4142 Port is a port identifier, referring to a driver.
4144 Operation is an integer, which is passed on to the driver.
4146 Data is any Erlang term. This data is converted to binary term
4148 format and sent to the port.
4149 Returns a term from the driver. The meaning of the returned data
4151 also depends on the port driver.
4152 Failures:
4154 badarg:
4156 If Port is not an identifier of an open port, or the regis‐
4157 tered name of an open port. If the calling process was pre‐
4158 viously linked to the closed port, identified by Port, the
4159 exit signal from the port is guaranteed to be delivered
4160 before this badarg exception occurs.
4161 badarg:
4163 If Operation does not fit in a 32-bit integer.
4164 badarg:
4166 If the port driver does not support synchronous control
4167 operations.
4168 badarg:
4170 If the port driver so decides for any reason (probably some‐
4171 thing wrong with Operation or Data).
4172 Warning:
4174 Do not call port_call with an unknown Port identifier and
4175 expect badarg exception. Any undefined behavior is possible
4176 (including node crash) depending on how the port driver inter‐
4177 prets the supplied arguments.
4178 port_close(Port) -> true
4181 Types:
4183 Port = port() | atom()
4185 Closes an open port. Roughly the same as Port ! {self(), close}
4187 except for the error behavior (see below), being synchronous,
4188 and that the port does not reply with {Port, closed}. Any
4189 process can close a port with port_close/1, not only the port
4190 owner (the connected process). If the calling process is linked
4191 to the port identified by Port, the exit signal from the port is
4192 guaranteed to be delivered before port_close/1 returns.
4193 For comparison: Port ! {self(), close} only fails with badarg if
4195 Port does not refer to a port or a process. If Port is a closed
4196 port, nothing happens. If Port is an open port and the calling
4197 process is the port owner, the port replies with {Port, closed}
4198 when all buffers have been flushed and the port really closes.
4199 If the calling process is not the port owner, the port owner
4200 fails with badsig.
4201 Notice that any process can close a port using Port ! {Por‐
4203 tOwner, close} as if it itself was the port owner, but the reply
4204 always goes to the port owner.
4205 As from Erlang/OTP R16, Port ! {PortOwner, close} is truly asyn‐
4207 chronous. Notice that this operation has always been documented
4208 as an asynchronous operation, while the underlying implementa‐
4209 tion has been synchronous. port_close/1 is however still fully
4210 synchronous because of its error behavior.
4211 Failure: badarg if Port is not an identifier of an open port, or
4213 the registered name of an open port. If the calling process was
4214 previously linked to the closed port, identified by Port, the
4215 exit signal from the port is guaranteed to be delivered before
4216 this badarg exception occurs.
4217 port_command(Port, Data) -> true
4219 Types:
4221 Port = port() | atom()
4223 Data = iodata()
4224 Sends data to a port. Same as Port ! {PortOwner, {command,
4226 Data}} except for the error behavior and being synchronous (see
4227 below). Any process can send data to a port with port_command/2,
4228 not only the port owner (the connected process).
4229 For comparison: Port ! {PortOwner, {command, Data}} only fails
4231 with badarg if Port does not refer to a port or a process. If
4232 Port is a closed port, the data message disappears without a
4233 sound. If Port is open and the calling process is not the port
4234 owner, the port owner fails with badsig. The port owner fails
4235 with badsig also if Data is an invalid I/O list.
4236 Notice that any process can send to a port using Port ! {Por‐
4238 tOwner, {command, Data}} as if it itself was the port owner.
4239 If the port is busy, the calling process is suspended until the
4241 port is not busy any more.
4242 As from Erlang/OTP R16, Port ! {PortOwner, {command, Data}} is
4244 truly asynchronous. Notice that this operation has always been
4245 documented as an asynchronous operation, while the underlying
4246 implementation has been synchronous. port_command/2 is however
4247 still fully synchronous because of its error behavior.
4248 Failures:
4250 badarg:
4252 If Port is not an identifier of an open port, or the regis‐
4253 tered name of an open port. If the calling process was pre‐
4254 viously linked to the closed port, identified by Port, the
4255 exit signal from the port is guaranteed to be delivered
4256 before this badarg exception occurs.
4257 badarg:
4259 If Data is an invalid I/O list.
4260 Warning:
4262 Do not send data to an unknown port. Any undefined behavior is
4263 possible (including node crash) depending on how the port driver
4264 interprets the data.
4265 port_command(Port, Data, OptionList) -> boolean()
4268 Types:
4270 Port = port() | atom()
4272 Data = iodata()
4273 Option = force | nosuspend
4274 OptionList = [Option]
4275 Sends data to a port. port_command(Port, Data, []) equals
4277 port_command(Port, Data).
4278 If the port command is aborted, false is returned, otherwise
4280 true.
4281 If the port is busy, the calling process is suspended until the
4283 port is not busy anymore.
4284 Options:
4286 force:
4288 The calling process is not suspended if the port is busy,
4289 instead the port command is forced through. The call fails
4290 with a notsup exception if the driver of the port does not
4291 support this. For more information, see driver flag
4292 ERL_DRV_FLAG_SOFT_BUSY.
4293 nosuspend:
4295 The calling process is not suspended if the port is busy,
4296 instead the port command is aborted and false is returned.
4297 Note:
4299 More options can be added in a future release.
4300 Failures:
4303 badarg:
4305 If Port is not an identifier of an open port, or the regis‐
4306 tered name of an open port. If the calling process was pre‐
4307 viously linked to the closed port, identified by Port, the
4308 exit signal from the port is guaranteed to be delivered
4309 before this badarg exception occurs.
4310 badarg:
4312 If Data is an invalid I/O list.
4313 badarg:
4315 If OptionList is an invalid option list.
4316 notsup:
4318 If option force has been passed, but the driver of the port
4319 does not allow forcing through a busy port.
4320 Warning:
4322 Do not send data to an unknown port. Any undefined behavior is
4323 possible (including node crash) depending on how the port driver
4324 interprets the data.
4325 port_connect(Port, Pid) -> true
4328 Types:
4330 Port = port() | atom()
4332 Pid = pid()
4333 Sets the port owner (the connected port) to Pid. Roughly the
4335 same as Port ! {Owner, {connect, Pid}} except for the following:
4336 * The error behavior differs, see below.
4338 * The port does not reply with {Port,connected}.
4340 * port_connect/1 is synchronous, see below.
4342 * The new port owner gets linked to the port.
4344 The old port owner stays linked to the port and must call
4346 unlink(Port) if this is not desired. Any process can set the
4347 port owner to be any process with port_connect/2.
4348 For comparison: Port ! {self(), {connect, Pid}} only fails with
4350 badarg if Port does not refer to a port or a process. If Port is
4351 a closed port, nothing happens. If Port is an open port and the
4352 calling process is the port owner, the port replies with {Port,
4353 connected} to the old port owner. Notice that the old port owner
4354 is still linked to the port, while the new is not. If Port is an
4355 open port and the calling process is not the port owner, the
4356 port owner fails with badsig. The port owner fails with badsig
4357 also if Pid is not an existing local process identifier.
4358 Notice that any process can set the port owner using Port !
4360 {PortOwner, {connect, Pid}} as if it itself was the port owner,
4361 but the reply always goes to the port owner.
4362 As from Erlang/OTP R16, Port ! {PortOwner, {connect, Pid}} is
4364 truly asynchronous. Notice that this operation has always been
4365 documented as an asynchronous operation, while the underlying
4366 implementation has been synchronous. port_connect/2 is however
4367 still fully synchronous because of its error behavior.
4368 Failures:
4370 badarg:
4372 If Port is not an identifier of an open port, or the regis‐
4373 tered name of an open port. If the calling process was pre‐
4374 viously linked to the closed port, identified by Port, the
4375 exit signal from the port is guaranteed to be delivered
4376 before this badarg exception occurs.
4377 badarg:
4379 If the process identified by Pid is not an existing local
4380 process.
4381 port_control(Port, Operation, Data) -> iodata() | binary()
4383 Types:
4385 Port = port() | atom()
4387 Operation = integer()
4388 Data = iodata()
4389 Performs a synchronous control operation on a port. The meaning
4391 of Operation and Data depends on the port, that is, on the port
4392 driver. Not all port drivers support this control feature.
4393 Returns a list of integers in the range 0..255, or a binary,
4395 depending on the port driver. The meaning of the returned data
4396 also depends on the port driver.
4397 Failures:
4399 badarg:
4401 If Port is not an open port or the registered name of an
4402 open port.
4403 badarg:
4405 If Operation cannot fit in a 32-bit integer.
4406 badarg:
4408 If the port driver does not support synchronous control
4409 operations.
4410 badarg:
4412 If the port driver so decides for any reason (probably
4413 something wrong with Operation or Data).
4414 Warning:
4416 Do not call port_control/3 with an unknown Port identifier and
4417 expect badarg exception. Any undefined behavior is possible
4418 (including node crash) depending on how the port driver inter‐
4419 prets the supplied arguments.
4420 erlang:port_info(Port) -> Result
4423 Types:
4425 Port = port() | atom()
4427 ResultItem =
4428 {registered_name, RegisteredName :: atom()} |
4429 {id, Index :: integer() >= 0} |
4430 {connected, Pid :: pid()} |
4431 {links, Pids :: [pid()]} |
4432 {name, String :: string()} |
4433 {input, Bytes :: integer() >= 0} |
4434 {output, Bytes :: integer() >= 0} |
4435 {os_pid, OsPid :: integer() >= 0 | undefined}
4436 Result = [ResultItem] | undefined
4437 Returns a list containing tuples with information about Port, or
4439 undefined if the port is not open. The order of the tuples is
4440 undefined, and all the tuples are not mandatory. If the port is
4441 closed and the calling process was previously linked to the
4442 port, the exit signal from the port is guaranteed to be deliv‐
4443 ered before port_info/1 returns undefined.
4444 The result contains information about the following Items:
4446 * registered_name (if the port has a registered name)
4448 * id
4450 * connected
4452 * links
4454 * name
4456 * input
4458 * output
4460 For more information about the different Items, see port_info/2.
4462 Failure: badarg if Port is not a local port identifier, or an
4464 atom.
4465 erlang:port_info(Port, Item :: connected) ->
4467 {connected, Pid} | undefined
4468 Types:
4470 Port = port() | atom()
4472 Pid = pid()
4473 Pid is the process identifier of the process connected to the
4475 port.
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 :: id) -> {id, Index} | undefined
4486 Types:
4488 Port = port() | atom()
4490 Index = integer() >= 0
4491 Index is the internal index of the port. This index can be used
4493 to separate ports.
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 :: input) ->
4504 {input, Bytes} | undefined
4505 Types:
4507 Port = port() | atom()
4509 Bytes = integer() >= 0
4510 Bytes is the total number of bytes read from the port.
4512 If the port identified by Port is not open, undefined is
4514 returned. If the port is closed and the calling process was pre‐
4515 viously linked to the port, the exit signal from the port is
4516 guaranteed to be delivered before port_info/2 returns undefined.
4517 Failure: badarg if Port is not a local port identifier, or an
4519 atom.
4520 erlang:port_info(Port, Item :: links) -> {links, Pids} | undefined
4522 Types:
4524 Port = port() | atom()
4526 Pids = [pid()]
4527 Pids is a list of the process identifiers of the processes that
4529 the port is linked to.
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 :: locking) ->
4540 {locking, Locking} | undefined
4541 Types:
4543 Port = port() | atom()
4545 Locking = false | port_level | driver_level
4546 Locking is one of the following:
4548 * port_level (port-specific locking)
4550 * driver_level (driver-specific locking)
4552 Notice that these results are highly implementation-specific and
4554 can change in a future release.
4555 If the port identified by Port is not open, undefined is
4557 returned. If the port is closed and the calling process was pre‐
4558 viously linked to the port, the exit signal from the port is
4559 guaranteed to be delivered before port_info/2 returns undefined.
4560 Failure: badarg if Port is not a local port identifier, or an
4562 atom.
4563 erlang:port_info(Port, Item :: memory) ->
4565 {memory, Bytes} | undefined
4566 Types:
4568 Port = port() | atom()
4570 Bytes = integer() >= 0
4571 Bytes is the total number of bytes allocated for this port by
4573 the runtime system. The port itself can have allocated memory
4574 that is not included in Bytes.
4575 If the port identified by Port is not open, undefined is
4577 returned. If the port is closed and the calling process was pre‐
4578 viously linked to the port, the exit signal from the port is
4579 guaranteed to be delivered before port_info/2 returns undefined.
4580 Failure: badarg if Port is not a local port identifier, or an
4582 atom.
4583 erlang:port_info(Port, Item :: monitors) ->
4585 {monitors, Monitors} | undefined
4586 Types:
4588 Port = port() | atom()
4590 Monitors = [{process, pid()}]
4591 Monitors represent processes monitored by this port.
4593 If the port identified by Port is not open, undefined is
4595 returned. If the port is closed and the calling process was pre‐
4596 viously linked to the port, the exit signal from the port is
4597 guaranteed to be delivered before port_info/2 returns undefined.
4598 Failure: badarg if Port is not a local port identifier, or an
4600 atom.
4601 erlang:port_info(Port, Item :: monitored_by) ->
4603 {monitored_by, MonitoredBy} | undefined
4604 Types:
4606 Port = port() | atom()
4608 MonitoredBy = [pid()]
4609 Returns list of pids that are monitoring given port at the
4611 moment.
4612 If the port identified by Port is not open, undefined is
4614 returned. If the port is closed and the calling process was pre‐
4615 viously linked to the port, the exit signal from the port is
4616 guaranteed to be delivered before port_info/2 returns undefined.
4617 Failure: badarg if Port is not a local port identifier, or an
4619 atom.
4620 erlang:port_info(Port, Item :: name) -> {name, Name} | undefined
4622 Types:
4624 Port = port() | atom()
4626 Name = string()
4627 Name is the command name set by open_port/2.
4629 If the port identified by Port is not open, undefined is
4631 returned. If the port is closed and the calling process was pre‐
4632 viously linked to the port, the exit signal from the port is
4633 guaranteed to be delivered before port_info/2 returns undefined.
4634 Failure: badarg if Port is not a local port identifier, or an
4636 atom.
4637 erlang:port_info(Port, Item :: os_pid) ->
4639 {os_pid, OsPid} | undefined
4640 Types:
4642 Port = port() | atom()
4644 OsPid = integer() >= 0 | undefined
4645 OsPid is the process identifier (or equivalent) of an OS process
4647 created with open_port({spawn | spawn_executable, Command},
4648 Options). If the port is not the result of spawning an OS
4649 process, the value is undefined.
4650 If the port identified by Port is not open, undefined is
4652 returned. If the port is closed and the calling process was pre‐
4653 viously linked to the port, the exit signal from the port is
4654 guaranteed to be delivered before port_info/2 returns undefined.
4655 Failure: badarg if Port is not a local port identifier, or an
4657 atom.
4658 erlang:port_info(Port, Item :: output) ->
4660 {output, Bytes} | undefined
4661 Types:
4663 Port = port() | atom()
4665 Bytes = integer() >= 0
4666 Bytes is the total number of bytes written to the port from
4668 Erlang processes using port_command/2, port_command/3, or Port !
4669 {Owner, {command, Data}.
4670 If the port identified by Port is not open, undefined is
4672 returned. If the port is closed and the calling process was pre‐
4673 viously linked to the port, the exit signal from the port is
4674 guaranteed to be delivered before port_info/2 returns undefined.
4675 Failure: badarg if Port is not a local port identifier, or an
4677 atom.
4678 erlang:port_info(Port, Item :: parallelism) ->
4680 {parallelism, Boolean} | undefined
4681 Types:
4683 Port = port() | atom()
4685 Boolean = boolean()
4686 Boolean corresponds to the port parallelism hint used by this
4688 port. For more information, see option parallelism of
4689 open_port/2.
4690 erlang:port_info(Port, Item :: queue_size) ->
4692 {queue_size, Bytes} | undefined
4693 Types:
4695 Port = port() | atom()
4697 Bytes = integer() >= 0
4698 Bytes is the total number of bytes queued by the port using the
4700 ERTS driver queue implementation.
4701 If the port identified by Port is not open, undefined is
4703 returned. If the port is closed and the calling process was pre‐
4704 viously linked to the port, the exit signal from the port is
4705 guaranteed to be delivered before port_info/2 returns undefined.
4706 Failure: badarg if Port is not a local port identifier, or an
4708 atom.
4709 erlang:port_info(Port, Item :: registered_name) ->
4711 {registered_name, RegisteredName} |
4712 [] | undefined
4713 Types:
4715 Port = port() | atom()
4717 RegisteredName = atom()
4718 RegisteredName is the registered name of the port. If the port
4720 has no registered name, [] is returned.
4721 If the port identified by Port is not open, undefined is
4723 returned. If the port is closed and the calling process was pre‐
4724 viously linked to the port, the exit signal from the port is
4725 guaranteed to be delivered before port_info/2 returns undefined.
4726 Failure: badarg if Port is not a local port identifier, or an
4728 atom.
4729 port_to_list(Port) -> string()
4731 Types:
4733 Port = port()
4735 Returns a string corresponding to the text representation of the
4737 port identifier Port.
4738 erlang:ports() -> [port()]
4740 Returns a list of port identifiers corresponding to all the
4742 ports existing on the local node.
4743 Notice that an exiting port exists, but is not open.
4745 pre_loaded() -> [module()]
4747 Returns a list of Erlang modules that are preloaded in the sys‐
4749 tem. As all loading of code is done through the file system, the
4750 file system must have been loaded previously. Hence, at least
4751 the module init must be preloaded.
4752 erlang:process_display(Pid, Type) -> true
4754 Types:
4756 Pid = pid()
4758 Type = backtrace
4759 Writes information about the local process Pid on standard
4761 error. The only allowed value for the atom Type is backtrace,
4762 which shows the contents of the call stack, including informa‐
4763 tion about the call chain, with the current function printed
4764 first. The format of the output is not further defined.
4765 process_flag(Flag :: trap_exit, Boolean) -> OldBoolean
4767 Types:
4769 Boolean = OldBoolean = boolean()
4771 When trap_exit is set to true, exit signals arriving to a
4773 process are converted to {'EXIT', From, Reason} messages, which
4774 can be received as ordinary messages. If trap_exit is set to
4775 false, the process exits if it receives an exit signal other
4776 than normal and the exit signal is propagated to its linked pro‐
4777 cesses. Application processes are normally not to trap exits.
4778 Returns the old value of the flag.
4780 See also exit/2.
4782 process_flag(Flag :: error_handler, Module) -> OldModule
4784 Types:
4786 Module = OldModule = atom()
4788 Used by a process to redefine the error handler for undefined
4790 function calls and undefined registered processes. Inexperienced
4791 users are not to use this flag, as code auto-loading depends on
4792 the correct operation of the error handling module.
4793 Returns the old value of the flag.
4795 process_flag(Flag :: min_heap_size, MinHeapSize) -> OldMinHeapSize
4797 Types:
4799 MinHeapSize = OldMinHeapSize = integer() >= 0
4801 Changes the minimum heap size for the calling process.
4803 Returns the old value of the flag.
4805 process_flag(Flag :: min_bin_vheap_size, MinBinVHeapSize) ->
4807 OldMinBinVHeapSize
4808 Types:
4810 MinBinVHeapSize = OldMinBinVHeapSize = integer() >= 0
4812 Changes the minimum binary virtual heap size for the calling
4814 process.
4815 Returns the old value of the flag.
4817 process_flag(Flag :: max_heap_size, MaxHeapSize) -> OldMaxHeapSize
4819 Types:
4821 MaxHeapSize = OldMaxHeapSize = max_heap_size()
4823 max_heap_size() =
4824 integer() >= 0 |
4825 #{size => integer() >= 0,
4826 kill => boolean(),
4827 error_logger => boolean()}
4828 This flag sets the maximum heap size for the calling process. If
4830 MaxHeapSize is an integer, the system default values for kill
4831 and error_logger are used.
4832 size:
4834 The maximum size in words of the process. If set to zero,
4835 the heap size limit is disabled. badarg is be thrown if the
4836 value is smaller than min_heap_size. The size check is only
4837 done when a garbage collection is triggered.
4838 size is the entire heap of the process when garbage collec‐
4840 tion is triggered. This includes all generational heaps, the
4841 process stack, any messages that are considered to be part
4842 of the heap, and any extra memory that the garbage collector
4843 needs during collection.
4844 size is the same as can be retrieved using
4846 erlang:process_info(Pid, total_heap_size), or by adding
4847 heap_block_size, old_heap_block_size and mbuf_size from
4848 erlang:process_info(Pid, garbage_collection_info).
4849 kill:
4851 When set to true, the runtime system sends an untrappable
4852 exit signal with reason kill to the process if the maximum
4853 heap size is reached. The garbage collection that triggered
4854 the kill is not completed, instead the process exits as soon
4855 as possible. When set to false, no exit signal is sent to
4856 the process, instead it continues executing.
4857 If kill is not defined in the map, the system default will
4859 be used. The default system default is true. It can be
4860 changed by either option +hmaxk in erl(1), or erlang:sys‐
4861 tem_flag(max_heap_size, MaxHeapSize).
4862 error_logger:
4864 When set to true, the runtime system logs an error event via
4865 logger, containing details about the process when the maxi‐
4866 mum heap size is reached. One log event is sent each time
4867 the limit is reached.
4868 If error_logger is not defined in the map, the system
4870 default is used. The default system default is true. It can
4871 be changed by either the option +hmaxel int erl(1), or
4872 erlang:system_flag(max_heap_size, MaxHeapSize).
4873 The heap size of a process is quite hard to predict, especially
4875 the amount of memory that is used during the garbage collection.
4876 When contemplating using this option, it is recommended to first
4877 run it in production with kill set to false and inspect the log
4878 events to see what the normal peak sizes of the processes in the
4879 system is and then tune the value accordingly.
4880 process_flag(Flag :: message_queue_data, MQD) -> OldMQD
4882 Types:
4884 MQD = OldMQD = message_queue_data()
4886 message_queue_data() = off_heap | on_heap
4887 Determines how messages in the message queue are stored, as fol‐
4889 lows:
4890 off_heap:
4892 All messages in the message queue will be stored outside the
4893 process heap. This implies that no messages in the message
4894 queue will be part of a garbage collection of the process.
4895 on_heap:
4897 All messages in the message queue will eventually be placed
4898 on the process heap. They can, however, be temporarily
4899 stored off the heap. This is how messages have always been
4900 stored up until ERTS 8.0.
4901 The default value of the message_queue_data process flag is
4903 determined by the command-line argument +hmqd in erl(1).
4904 If the process may potentially accumulate a large number of mes‐
4906 sages in its queue it is recommended to set the flag value to
4907 off_heap. This is due to the fact that the garbage collection of
4908 a process that has a large number of messages stored on the heap
4909 can become extremely expensive and the process can consume large
4910 amounts of memory. The performance of the actual message passing
4911 is, however, generally better when the flag value is on_heap.
4912 Changing the flag value causes any existing messages to be
4914 moved. The move operation is initiated, but not necessarily com‐
4915 pleted, by the time the function returns.
4916 Returns the old value of the flag.
4918 process_flag(Flag :: priority, Level) -> OldLevel
4920 Types:
4922 Level = OldLevel = priority_level()
4924 priority_level() = low | normal | high | max
4925 Sets the process priority. Level is an atom. Four priority lev‐
4927 els exist: low, normal, high, and max. Default is normal.
4928 Note:
4930 Priority level max is reserved for internal use in the Erlang
4931 runtime system, and is not to be used by others.
4932 Internally in each priority level, processes are scheduled in a
4935 round robin fashion.
4936 Execution of processes on priority normal and low are inter‐
4938 leaved. Processes on priority low are selected for execution
4939 less frequently than processes on priority normal.
4940 When runnable processes on priority high exist, no processes on
4942 priority low or normal are selected for execution. Notice how‐
4943 ever that this does not mean that no processes on priority low
4944 or normal can run when processes are running on priority high.
4945 When using multiple schedulers, more processes can be running in
4946 parallel than processes on priority high. That is, a low and a
4947 high priority process can execute at the same time.
4948 When runnable processes on priority max exist, no processes on
4950 priority low, normal, or high are selected for execution. As
4951 with priority high, processes on lower priorities can execute in
4952 parallel with processes on priority max.
4953 Scheduling is pre-emptive. Regardless of priority, a process is
4955 pre-empted when it has consumed more than a certain number of
4956 reductions since the last time it was selected for execution.
4957 Note:
4959 Do not depend on the scheduling to remain exactly as it is
4960 today. Scheduling is likely to be changed in a future release to
4961 use available processor cores better.
4962 There is no automatic mechanism for avoiding priority inversion,
4965 such as priority inheritance or priority ceilings. When using
4966 priorities, take this into account and handle such scenarios by
4967 yourself.
4968 Making calls from a high priority process into code that you has
4970 no control over can cause the high priority process to wait for
4971 a process with lower priority. That is, effectively decreasing
4972 the priority of the high priority process during the call. Even
4973 if this is not the case with one version of the code that you
4974 have no control over, it can be the case in a future version of
4975 it. This can, for example, occur if a high priority process
4976 triggers code loading, as the code server runs on priority nor‐
4977 mal.
4978 Other priorities than normal are normally not needed. When other
4980 priorities are used, use them with care, especially priority
4981 high. A process on priority high is only to perform work for
4982 short periods. Busy looping for long periods in a high priority
4983 process causes most likely problems, as important OTP servers
4984 run on priority normal.
4985 Returns the old value of the flag.
4987 process_flag(Flag :: save_calls, N) -> OldN
4989 Types:
4991 N = OldN = 0..10000
4993 N must be an integer in the interval 0..10000. If N > 0, call
4995 saving is made active for the process. This means that informa‐
4996 tion about the N most recent global function calls, BIF calls,
4997 sends, and receives made by the process are saved in a list,
4998 which can be retrieved with process_info(Pid, last_calls). A
4999 global function call is one in which the module of the function
5000 is explicitly mentioned. Only a fixed amount of information is
5001 saved, as follows:
5002 * A tuple {Module, Function, Arity} for function calls
5004 * The atoms send, 'receive', and timeout for sends and
5006 receives ('receive' when a message is received and timeout
5007 when a receive times out)
5008 If N = 0, call saving is disabled for the process, which is the
5010 default. Whenever the size of the call saving list is set, its
5011 contents are reset.
5012 Returns the old value of the flag.
5014 process_flag(Flag :: sensitive, Boolean) -> OldBoolean
5016 Types:
5018 Boolean = OldBoolean = boolean()
5020 Sets or clears flag sensitive for the current process. When a
5022 process has been marked as sensitive by calling
5023 process_flag(sensitive, true), features in the runtime system
5024 that can be used for examining the data or inner working of the
5025 process are silently disabled.
5026 Features that are disabled include (but are not limited to) the
5028 following:
5029 * Tracing. Trace flags can still be set for the process, but
5031 no trace messages of any kind are generated. (If flag sensi‐
5032 tive is turned off, trace messages are again generated if
5033 any trace flags are set.)
5034 * Sequential tracing. The sequential trace token is propagated
5036 as usual, but no sequential trace messages are generated.
5037 process_info/1,2 cannot be used to read out the message queue or
5039 the process dictionary (both are returned as empty lists).
5040 Stack back-traces cannot be displayed for the process.
5042 In crash dumps, the stack, messages, and the process dictionary
5044 are omitted.
5045 If {save_calls,N} has been set for the process, no function
5047 calls are saved to the call saving list. (The call saving list
5048 is not cleared. Also, send, receive, and time-out events are
5049 still added to the list.)
5050 Returns the old value of the flag.
5052 process_flag(Pid, Flag, Value) -> OldValue
5054 Types:
5056 Pid = pid()
5058 Flag = save_calls
5059 Value = OldValue = integer() >= 0
5060 Sets certain flags for the process Pid, in the same manner as
5062 process_flag/2. Returns the old value of the flag. The valid
5063 values for Flag are only a subset of those allowed in
5064 process_flag/2, namely save_calls.
5065 Failure: badarg if Pid is not a local process.
5067 process_info(Pid) -> Info
5069 Types:
5071 Pid = pid()
5073 Info = [InfoTuple] | undefined
5074 InfoTuple = process_info_result_item()
5075 process_info_result_item() =
5076 {backtrace, Bin :: binary()} |
5077 {binary,
5078 BinInfo ::
5079 [{integer() >= 0,
5080 integer() >= 0,
5081 integer() >= 0}]} |
5082 {catchlevel, CatchLevel :: integer() >= 0} |
5083 {current_function,
5084 {Module :: module(), Function :: atom(), Arity :: arity()} |
5085 undefined} |
5086 {current_location,
5087 {Module :: module(),
5088 Function :: atom(),
5089 Arity :: arity(),
5090 Location ::
5091 [{file, Filename :: string()} |
5092 {line, Line :: integer() >= 1}]}} |
5093 {current_stacktrace, Stack :: [stack_item()]} |
5094 {dictionary, Dictionary :: [{Key :: term(), Value :: term()}]} |
5095 {error_handler, Module :: module()} |
5096 {garbage_collection, GCInfo :: [{atom(), integer() >= 0}]} |
5097 {garbage_collection_info,
5098 GCInfo :: [{atom(), integer() >= 0}]} |
5099 {group_leader, GroupLeader :: pid()} |
5100 {heap_size, Size :: integer() >= 0} |
5101 {initial_call, mfa()} |
5102 {links, PidsAndPorts :: [pid() | port()]} |
5103 {last_calls, false | (Calls :: [mfa()])} |
5104 {memory, Size :: integer() >= 0} |
5105 {message_queue_len, MessageQueueLen :: integer() >= 0} |
5106 {messages, MessageQueue :: [term()]} |
5107 {min_heap_size, MinHeapSize :: integer() >= 0} |
5108 {min_bin_vheap_size, MinBinVHeapSize :: integer() >= 0} |
5109 {max_heap_size, MaxHeapSize :: max_heap_size()} |
5110 {monitored_by,
5111 MonitoredBy :: [pid() | port() | nif_resource()]} |
5112 {monitors,
5113 Monitors ::
5114 [{process | port,
5115 Pid ::
5116 pid() |
5117 port() |
5118 {RegName :: atom(), Node :: node()}}]} |
5119 {message_queue_data, MQD :: message_queue_data()} |
5120 {priority, Level :: priority_level()} |
5121 {reductions, Number :: integer() >= 0} |
5122 {registered_name, [] | (Atom :: atom())} |
5123 {sequential_trace_token,
5124 [] | (SequentialTraceToken :: term())} |
5125 {stack_size, Size :: integer() >= 0} |
5126 {status,
5127 Status ::
5128 exiting | garbage_collecting | waiting | running |
5129 runnable | suspended} |
5130 {suspending,
5131 SuspendeeList ::
5132 [{Suspendee :: pid(),
5133 ActiveSuspendCount :: integer() >= 0,
5134 OutstandingSuspendCount :: integer() >= 0}]} |
5135 {total_heap_size, Size :: integer() >= 0} |
5136 {trace, InternalTraceFlags :: integer() >= 0} |
5137 {trap_exit, Boolean :: boolean()}
5138 priority_level() = low | normal | high | max
5139 stack_item() =
5140 {Module :: module(),
5141 Function :: atom(),
5142 Arity :: arity() | (Args :: [term()]),
5143 Location ::
5144 [{file, Filename :: string()} |
5145 {line, Line :: integer() >= 1}]}
5146 max_heap_size() =
5147 integer() >= 0 |
5148 #{size => integer() >= 0,
5149 kill => boolean(),
5150 error_logger => boolean()}
5151 message_queue_data() = off_heap | on_heap
5152 Returns a list containing InfoTuples with miscellaneous informa‐
5154 tion about the process identified by Pid, or undefined if the
5155 process is not alive.
5156 The order of the InfoTuples is undefined and all InfoTuples are
5158 not mandatory. The InfoTuples part of the result can be changed
5159 without prior notice.
5160 The InfoTuples with the following items are part of the result:
5162 * current_function
5164 * initial_call
5166 * status
5168 * message_queue_len
5170 * links
5172 * dictionary
5174 * trap_exit
5176 * error_handler
5178 * priority
5180 * group_leader
5182 * total_heap_size
5184 * heap_size
5186 * stack_size
5188 * reductions
5190 * garbage_collection
5192 If the process identified by Pid has a registered name, also an
5194 InfoTuple with item registered_name is included.
5195 For information about specific InfoTuples, see process_info/2.
5197 Warning:
5199 This BIF is intended for debugging only. For all other purposes,
5200 use process_info/2.
5201 Failure: badarg if Pid is not a local process.
5204 process_info(Pid, Item) -> InfoTuple | [] | undefined
5206 process_info(Pid, ItemList) -> InfoTupleList | [] | undefined
5208 Types:
5210 Pid = pid()
5212 ItemList = [Item]
5213 Item = process_info_item()
5214 InfoTupleList = [InfoTuple]
5215 InfoTuple = process_info_result_item()
5216 process_info_item() =
5217 backtrace | binary | catchlevel | current_function |
5218 current_location | current_stacktrace | dictionary |
5219 error_handler | garbage_collection | garbage_collection_info |
5220 group_leader | heap_size | initial_call | links | last_calls |
5221 memory | message_queue_len | messages | min_heap_size |
5222 min_bin_vheap_size | monitored_by | monitors |
5223 message_queue_data | priority | reductions | registered_name |
5224 sequential_trace_token | stack_size | status | suspending |
5225 total_heap_size | trace | trap_exit
5226 process_info_result_item() =
5227 {backtrace, Bin :: binary()} |
5228 {binary,
5229 BinInfo ::
5230 [{integer() >= 0,
5231 integer() >= 0,
5232 integer() >= 0}]} |
5233 {catchlevel, CatchLevel :: integer() >= 0} |
5234 {current_function,
5235 {Module :: module(), Function :: atom(), Arity :: arity()} |
5236 undefined} |
5237 {current_location,
5238 {Module :: module(),
5239 Function :: atom(),
5240 Arity :: arity(),
5241 Location ::
5242 [{file, Filename :: string()} |
5243 {line, Line :: integer() >= 1}]}} |
5244 {current_stacktrace, Stack :: [stack_item()]} |
5245 {dictionary, Dictionary :: [{Key :: term(), Value :: term()}]} |
5246 {error_handler, Module :: module()} |
5247 {garbage_collection, GCInfo :: [{atom(), integer() >= 0}]} |
5248 {garbage_collection_info,
5249 GCInfo :: [{atom(), integer() >= 0}]} |
5250 {group_leader, GroupLeader :: pid()} |
5251 {heap_size, Size :: integer() >= 0} |
5252 {initial_call, mfa()} |
5253 {links, PidsAndPorts :: [pid() | port()]} |
5254 {last_calls, false | (Calls :: [mfa()])} |
5255 {memory, Size :: integer() >= 0} |
5256 {message_queue_len, MessageQueueLen :: integer() >= 0} |
5257 {messages, MessageQueue :: [term()]} |
5258 {min_heap_size, MinHeapSize :: integer() >= 0} |
5259 {min_bin_vheap_size, MinBinVHeapSize :: integer() >= 0} |
5260 {max_heap_size, MaxHeapSize :: max_heap_size()} |
5261 {monitored_by,
5262 MonitoredBy :: [pid() | port() | nif_resource()]} |
5263 {monitors,
5264 Monitors ::
5265 [{process | port,
5266 Pid ::
5267 pid() |
5268 port() |
5269 {RegName :: atom(), Node :: node()}}]} |
5270 {message_queue_data, MQD :: message_queue_data()} |
5271 {priority, Level :: priority_level()} |
5272 {reductions, Number :: integer() >= 0} |
5273 {registered_name, [] | (Atom :: atom())} |
5274 {sequential_trace_token,
5275 [] | (SequentialTraceToken :: term())} |
5276 {stack_size, Size :: integer() >= 0} |
5277 {status,
5278 Status ::
5279 exiting | garbage_collecting | waiting | running |
5280 runnable | suspended} |
5281 {suspending,
5282 SuspendeeList ::
5283 [{Suspendee :: pid(),
5284 ActiveSuspendCount :: integer() >= 0,
5285 OutstandingSuspendCount :: integer() >= 0}]} |
5286 {total_heap_size, Size :: integer() >= 0} |
5287 {trace, InternalTraceFlags :: integer() >= 0} |
5288 {trap_exit, Boolean :: boolean()}
5289 stack_item() =
5290 {Module :: module(),
5291 Function :: atom(),
5292 Arity :: arity() | (Args :: [term()]),
5293 Location ::
5294 [{file, Filename :: string()} |
5295 {line, Line :: integer() >= 1}]}
5296 priority_level() = low | normal | high | max
5297 max_heap_size() =
5298 integer() >= 0 |
5299 #{size => integer() >= 0,
5300 kill => boolean(),
5301 error_logger => boolean()}
5302 message_queue_data() = off_heap | on_heap
5303 Returns information about the process identified by Pid, as
5305 specified by Item or ItemList. Returns undefined if the process
5306 is not alive.
5307 If the process is alive and a single Item is specified, the
5309 returned value is the corresponding InfoTuple, unless Item =:=
5310 registered_name and the process has no registered name. In this
5311 case, [] is returned. This strange behavior is because of his‐
5312 torical reasons, and is kept for backward compatibility.
5313 If ItemList is specified, the result is InfoTupleList. The Info‐
5315 Tuples in InfoTupleList are included with the corresponding
5316 Items in the same order as the Items were included in ItemList.
5317 Valid Items can be included multiple times in ItemList.
5318 Note:
5320 If registered_name is part of ItemList and the process has no
5321 name registered, a {registered_name, []}, InfoTuple will be
5322 included in the resulting InfoTupleList. This behavior is dif‐
5323 ferent when a single Item =:= registered_name is specified, and
5324 when process_info/1 is used.
5325 Valid InfoTuples with corresponding Items:
5328 {backtrace, Bin}:
5330 Binary Bin contains the same information as the output from
5331 erlang:process_display(Pid, backtrace). Use binary_to_list/1
5332 to obtain the string of characters from the binary.
5333 {binary, BinInfo}:
5335 BinInfo is a list containing miscellaneous information about
5336 binaries on the heap of this process. This InfoTuple can be
5337 changed or removed without prior notice. In the current
5338 implementation BinInfo is a list of tuples. The tuples con‐
5339 tain; BinaryId, BinarySize, BinaryRefcCount.
5340 Depending on the value of the message_queue_data process
5342 flag the message queue may be stored on the heap.
5343 {catchlevel, CatchLevel}:
5345 CatchLevel is the number of currently active catches in this
5346 process. This InfoTuple can be changed or removed without
5347 prior notice.
5348 {current_function, {Module, Function, Arity} | undefined}:
5350 Module, Function, Arity is the current function call of the
5351 process. The value undefined can be returned if the process
5352 is currently executing native compiled code.
5353 {current_location, {Module, Function, Arity, Location}}:
5355 Module, Function, Arity is the current function call of the
5356 process. Location is a list of two-tuples describing the
5357 location in the source code.
5358 {current_stacktrace, Stack}:
5360 Returns the current call stack back-trace (stacktrace) of
5361 the process. The stack has the same format as in the catch
5362 part of a try. See The call-stack back trace (stacktrace).
5363 The depth of the stacktrace is truncated according to the
5364 backtrace_depth system flag setting.
5365 {dictionary, Dictionary}:
5367 Dictionary is the process dictionary.
5368 {error_handler, Module}:
5370 Module is the error handler module used by the process (for
5371 undefined function calls, for example).
5372 {garbage_collection, GCInfo}:
5374 GCInfo is a list containing miscellaneous information about
5375 garbage collection for this process. The content of GCInfo
5376 can be changed without prior notice.
5377 {garbage_collection_info, GCInfo}:
5379 GCInfo is a list containing miscellaneous detailed informa‐
5380 tion about garbage collection for this process. The content
5381 of GCInfo can be changed without prior notice. For details
5382 about the meaning of each item, see gc_minor_start in
5383 erlang:trace/3.
5384 {group_leader, GroupLeader}:
5386 GroupLeader is the group leader for the I/O of the process.
5387 {heap_size, Size}:
5389 Size is the size in words of the youngest heap generation of
5390 the process. This generation includes the process stack.
5391 This information is highly implementation-dependent, and can
5392 change if the implementation changes.
5393 {initial_call, {Module, Function, Arity}}:
5395 Module, Function, Arity is the initial function call with
5396 which the process was spawned.
5397 {links, PidsAndPorts}:
5399 PidsAndPorts is a list of process identifiers and port iden‐
5400 tifiers, with processes or ports to which the process has a
5401 link.
5402 {last_calls, false|Calls}:
5404 The value is false if call saving is not active for the
5405 process (see process_flag/3). If call saving is active, a
5406 list is returned, in which the last element is the most
5407 recent called.
5408 {memory, Size}:
5410 Size is the size in bytes of the process. This includes call
5413 stack, heap, and internal structures.
5414 {message_queue_len, MessageQueueLen}:
5416 MessageQueueLen is the number of messages currently in the
5417 message queue of the process. This is the length of the list
5418 MessageQueue returned as the information item messages (see
5419 below).
5420 {messages, MessageQueue}:
5422 MessageQueue is a list of the messages to the process, which
5423 have not yet been processed.
5424 {min_heap_size, MinHeapSize}:
5426 MinHeapSize is the minimum heap size for the process.
5427 {min_bin_vheap_size, MinBinVHeapSize}:
5429 MinBinVHeapSize is the minimum binary virtual heap size for
5430 the process.
5431 {monitored_by, MonitoredBy}:
5433 A list of identifiers for all the processes, ports and NIF
5434 resources, that are monitoring the process.
5435 {monitors, Monitors}:
5437 A list of monitors (started by monitor/2) that are active
5438 for the process. For a local process monitor or a remote
5439 process monitor by a process identifier, the list consists
5440 of:
5441 {process, Pid}:
5443 Process is monitored by pid.
5444 {process, {RegName, Node}}:
5446 Local or remote process is monitored by name.
5447 {port, PortId}:
5449 Local port is monitored by port id.
5450 {port, {RegName, Node}}:
5452 Local port is monitored by name. Please note, that remote
5453 port monitors are not supported, so Node will always be
5454 the local node name.
5455 {message_queue_data, MQD}:
5457 MQD is the current value of the message_queue_data process
5458 flag, which can be either off_heap or on_heap. For more
5459 information, see the documentation of process_flag(mes‐
5460 sage_queue_data, MQD).
5461 {priority, Level}:
5463 Level is the current priority level for the process. For
5464 more information on priorities, see process_flag(priority,
5465 Level).
5466 {reductions, Number}:
5468 Number is the number of reductions executed by the process.
5469 {registered_name, Atom}:
5471 Atom is the registered process name. If the process has no
5472 registered name, this tuple is not present in the list.
5473 {sequential_trace_token, [] | SequentialTraceToken}:
5475 SequentialTraceToken is the sequential trace token for the
5476 process. This InfoTuple can be changed or removed without
5477 prior notice.
5478 {stack_size, Size}:
5480 Size is the stack size, in words, of the process.
5481 {status, Status}:
5483 Status is the status of the process and is one of the fol‐
5484 lowing:
5485 * exiting
5487 * garbage_collecting
5489 * waiting (for a message)
5491 * running
5493 * runnable (ready to run, but another process is running)
5495 * suspended (suspended on a "busy" port or by the BIF
5497 erlang:suspend_process/1,2)
5498 {suspending, SuspendeeList}:
5500 SuspendeeList is a list of {Suspendee, ActiveSuspendCount,
5501 OutstandingSuspendCount} tuples. Suspendee is the process
5502 identifier of a process that has been, or is to be, sus‐
5503 pended by the process identified by Pid through the BIF
5504 erlang:suspend_process/2 or erlang:suspend_process/1.
5505 ActiveSuspendCount is the number of times Suspendee has been
5507 suspended by Pid. OutstandingSuspendCount is the number of
5508 not yet completed suspend requests sent by Pid, that is:
5509 * If ActiveSuspendCount =/= 0, Suspendee is currently in the
5511 suspended state.
5512 * If OutstandingSuspendCount =/= 0, option asynchronous of
5514 erlang:suspend_process/2 has been used and the suspendee
5515 has not yet been suspended by Pid.
5516 Notice that ActiveSuspendCount and OutstandingSuspendCount
5518 are not the total suspend count on Suspendee, only the parts
5519 contributed by Pid.
5520 {total_heap_size, Size}:
5522 Size is the total size, in words, of all heap fragments of
5523 the process. This includes the process stack and any unre‐
5524 ceived messages that are considered to be part of the heap.
5525 {trace, InternalTraceFlags}:
5527 InternalTraceFlags is an integer representing the internal
5528 trace flag for this process. This InfoTuple can be changed
5529 or removed without prior notice.
5530 {trap_exit, Boolean}:
5532 Boolean is true if the process is trapping exits, otherwise
5533 false.
5534 Notice that not all implementations support all these Items.
5536 Failures:
5538 badarg:
5540 If Pid is not a local process.
5541 badarg:
5543 If Item is an invalid item.
5544 processes() -> [pid()]
5546 Returns a list of process identifiers corresponding to all the
5548 processes currently existing on the local node.
5549 Notice that an exiting process exists, but is not alive. That
5551 is, is_process_alive/1 returns false for an exiting process, but
5552 its process identifier is part of the result returned from pro‐
5553 cesses/0.
5554 Example:
5556 > processes().
5558 [<0.0.0>,<0.2.0>,<0.4.0>,<0.5.0>,<0.7.0>,<0.8.0>]
5559 purge_module(Module) -> true
5561 Types:
5563 Module = atom()
5565 Removes old code for Module. Before this BIF is used,
5567 check_process_code/2 is to be called to check that no processes
5568 execute old code in the module.
5569 Warning:
5571 This BIF is intended for the code server (see code(3)) and is
5572 not to be used elsewhere.
5573 Note:
5576 As from ERTS 8.0 (Erlang/OTP 19), any lingering processes that
5577 still execute the old code is killed by this function. In ear‐
5578 lier versions, such incorrect use could cause much more fatal
5579 failures, like emulator crash.
5580 Failure: badarg if there is no old code for Module.
5583 put(Key, Val) -> term()
5585 Types:
5587 Key = Val = term()
5589 Adds a new Key to the process dictionary, associated with the
5591 value Val, and returns undefined. If Key exists, the old value
5592 is deleted and replaced by Val, and the function returns the old
5593 value. Example:
5594 > X = put(name, walrus), Y = put(name, carpenter),
5596 Z = get(name),
5597 {X, Y, Z}.
5598 {undefined,walrus,carpenter}
5599 Note:
5601 The values stored when put is evaluated within the scope of a
5602 catch are not retracted if a throw is evaluated, or if an error
5603 occurs.
5604 erlang:raise(Class, Reason, Stacktrace) -> no_return()
5607 Types:
5609 Class = error | exit | throw
5611 Reason = term()
5612 Stacktrace = raise_stacktrace()
5613 raise_stacktrace() =
5614 [{module(), atom(), arity() | [term()]} |
5615 {function(), [term()]}] |
5616 [{module(), atom(), arity() | [term()], [{atom(), term()}]} |
5617 {function(), [term()], [{atom(), term()}]}]
5618 Stops the execution of the calling process with an exception of
5620 the specified class, reason, and call stack backtrace (stack‐
5621 trace).
5622 Class is error, exit, or throw. So, if it were not for the
5624 stacktrace, erlang:raise(Class, Reason, Stacktrace) is equiva‐
5625 lent to erlang:Class(Reason).
5626 Reason can be any term.
5628 Stacktrace is a list as provided in a try-catch clause.
5630 try
5632 ...
5633 catch Class:Reason:Stacktrace ->
5634 ...
5635 end
5636 That is, a list of four-tuples {Module, Function, Arity | Args,
5638 Location}, where Module and Function are atoms, and the third
5639 element is an integer arity or an argument list. The stacktrace
5640 can also contain {Fun, Args, Location} tuples, where Fun is a
5641 local fun and Args is an argument list.
5642 Element Location at the end is optional. Omitting it is equiva‐
5644 lent to specifying an empty list.
5645 The stacktrace is used as the exception stacktrace for the call‐
5647 ing process; it is truncated to the current maximum stacktrace
5648 depth.
5649 As evaluating this function causes the process to terminate, it
5651 has no return value unless the arguments are invalid, in which
5652 case the function returns the error reason badarg. If you want
5653 to be sure not to return, you can call error(erlang:raise(Class,
5654 Reason, Stacktrace)) and hope to distinguish exceptions later.
5655 erlang:read_timer(TimerRef) -> Result
5657 Types:
5659 TimerRef = reference()
5661 Time = integer() >= 0
5662 Result = Time | false
5663 Reads the state of a timer. The same as calling
5665 erlang:read_timer(TimerRef, []).
5666 erlang:read_timer(TimerRef, Options) -> Result | ok
5668 Types:
5670 TimerRef = reference()
5672 Async = boolean()
5673 Option = {async, Async}
5674 Options = [Option]
5675 Time = integer() >= 0
5676 Result = Time | false
5677 Reads the state of a timer that has been created by either
5679 erlang:start_timer or erlang:send_after. TimerRef identifies the
5680 timer, and was returned by the BIF that created the timer.
5681 Options:
5683 {async, Async}:
5685 Asynchronous request for state information. Async defaults
5686 to false, which causes the operation to be performed syn‐
5687 chronously. In this case, the Result is returned by
5688 erlang:read_timer. When Async is true, erlang:read_timer
5689 sends an asynchronous request for the state information to
5690 the timer service that manages the timer, and then returns
5691 ok. A message on the format {read_timer, TimerRef, Result}
5692 is sent to the caller of erlang:read_timer when the opera‐
5693 tion has been processed.
5694 More Options can be added in the future.
5696 If Result is an integer, it represents the time in milliseconds
5698 left until the timer expires.
5699 If Result is false, a timer corresponding to TimerRef could not
5701 be found. This because the timer had expired, or been canceled,
5702 or because TimerRef never has corresponded to a timer. Even if
5703 the timer has expired, it does not tell you whether or not the
5704 time-out message has arrived at its destination yet.
5705 Note:
5707 The timer service that manages the timer can be co-located with
5708 another scheduler than the scheduler that the calling process is
5709 executing on. If so, communication with the timer service takes
5710 much longer time than if it is located locally. If the calling
5711 process is in a critical path, and can do other things while
5712 waiting for the result of this operation, you want to use option
5713 {async, true}. If using option {async, false}, the calling
5714 process is blocked until the operation has been performed.
5715 See also erlang:send_after/4, erlang:start_timer/4, and
5718 erlang:cancel_timer/2.
5719 ref_to_list(Ref) -> string()
5721 Types:
5723 Ref = reference()
5725 Returns a string corresponding to the text representation of
5727 Ref.
5728 Warning:
5730 This BIF is intended for debugging and is not to be used in
5731 application programs.
5732 register(RegName, PidOrPort) -> true
5735 Types:
5737 RegName = atom()
5739 PidOrPort = port() | pid()
5740 Associates the name RegName with a process identifier (pid) or a
5742 port identifier. RegName, which must be an atom, can be used
5743 instead of the pid or port identifier in send operator (RegName
5744 ! Message). Example:
5745 > register(db, Pid).
5747 true
5748 Failures:
5750 badarg:
5752 If PidOrPort is not an existing local process or port.
5753 badarg:
5755 If RegName is already in use.
5756 badarg:
5758 If the process or port is already registered (already has a
5759 name).
5760 badarg:
5762 If RegName is the atom undefined.
5763 registered() -> [RegName]
5765 Types:
5767 RegName = atom()
5769 Returns a list of names that have been registered using regis‐
5771 ter/2, for example:
5772 > registered().
5774 [code_server, file_server, init, user, my_db]
5775 erlang:resume_process(Suspendee) -> true
5777 Types:
5779 Suspendee = pid()
5781 Decreases the suspend count on the process identified by Sus‐
5783 pendee. Suspendee is previously to have been suspended through
5784 erlang:suspend_process/2 or erlang:suspend_process/1 by the
5785 process calling erlang:resume_process(Suspendee). When the sus‐
5786 pend count on Suspendee reaches zero, Suspendee is resumed, that
5787 is, its state is changed from suspended into the state it had
5788 before it was suspended.
5789 Warning:
5791 This BIF is intended for debugging only.
5792 Failures:
5795 badarg:
5797 If Suspendee is not a process identifier.
5798 badarg:
5800 If the process calling erlang:resume_process/1 had not pre‐
5801 viously increased the suspend count on the process identi‐
5802 fied by Suspendee.
5803 badarg:
5805 If the process identified by Suspendee is not alive.
5806 round(Number) -> integer()
5808 Types:
5810 Number = number()
5812 Returns an integer by rounding Number, for example:
5814 round(5.5).
5816 6
5817 Allowed in guard tests.
5819 self() -> pid()
5821 Returns the process identifier of the calling process, for exam‐
5823 ple:
5824 > self().
5826 <0.26.0>
5827 Allowed in guard tests.
5829 erlang:send(Dest, Msg) -> Msg
5831 Types:
5833 Dest = dst()
5835 Msg = term()
5836 dst() =
5837 pid() |
5838 port() |
5839 (RegName :: atom()) |
5840 {RegName :: atom(), Node :: node()}
5841 Sends a message and returns Msg. This is the same as using the
5843 send operator: Dest ! Msg.
5844 Dest can be a remote or local process identifier, a (local)
5846 port, a locally registered name, or a tuple {RegName, Node} for
5847 a registered name at another node.
5848 The function fails with a badarg run-time error if Dest is an
5850 atom name, but this name is not registered. This is the only
5851 case when send fails for an unreachable destination Dest (of
5852 correct type).
5853 erlang:send(Dest, Msg, Options) -> Res
5855 Types:
5857 Dest = dst()
5859 Msg = term()
5860 Options = [nosuspend | noconnect]
5861 Res = ok | nosuspend | noconnect
5862 dst() =
5863 pid() |
5864 port() |
5865 (RegName :: atom()) |
5866 {RegName :: atom(), Node :: node()}
5867 Either sends a message and returns ok, or does not send the mes‐
5869 sage but returns something else (see below). Otherwise the same
5870 as erlang:send/2. For more detailed explanation and warnings,
5871 see erlang:send_nosuspend/2,3.
5872 Options:
5874 nosuspend:
5876 If the sender would have to be suspended to do the send,
5877 nosuspend is returned instead.
5878 noconnect:
5880 If the destination node would have to be auto-connected to
5881 do the send, noconnect is returned instead.
5882 Warning:
5884 As with erlang:send_nosuspend/2,3: use with extreme care.
5885 erlang:send_after(Time, Dest, Msg) -> TimerRef
5888 Types:
5890 Time = integer() >= 0
5892 Dest = pid() | atom()
5893 Msg = term()
5894 TimerRef = reference()
5895 Starts a timer. The same as calling erlang:send_after(Time,
5897 Dest, Msg, []).
5898 erlang:send_after(Time, Dest, Msg, Options) -> TimerRef
5900 Types:
5902 Time = integer()
5904 Dest = pid() | atom()
5905 Msg = term()
5906 Options = [Option]
5907 Abs = boolean()
5908 Option = {abs, Abs}
5909 TimerRef = reference()
5910 Starts a timer. When the timer expires, the message Msg is sent
5912 to the process identified by Dest. Apart from the format of the
5913 time-out message, this function works exactly as
5914 erlang:start_timer/4.
5915 erlang:send_nosuspend(Dest, Msg) -> boolean()
5917 Types:
5919 Dest = dst()
5921 Msg = term()
5922 dst() =
5923 pid() |
5924 port() |
5925 (RegName :: atom()) |
5926 {RegName :: atom(), Node :: node()}
5927 The same as erlang:send(Dest, Msg, [nosuspend]), but returns
5929 true if the message was sent and false if the message was not
5930 sent because the sender would have had to be suspended.
5931 This function is intended for send operations to an unreliable
5933 remote node without ever blocking the sending (Erlang) process.
5934 If the connection to the remote node (usually not a real Erlang
5935 node, but a node written in C or Java) is overloaded, this func‐
5936 tion does not send the message and returns false.
5937 The same occurs if Dest refers to a local port that is busy. For
5939 all other destinations (allowed for the ordinary send operator
5940 '!'), this function sends the message and returns true.
5941 This function is only to be used in rare circumstances where a
5943 process communicates with Erlang nodes that can disappear with‐
5944 out any trace, causing the TCP buffers and the drivers queue to
5945 be over-full before the node is shut down (because of tick time-
5946 outs) by net_kernel. The normal reaction to take when this
5947 occurs is some kind of premature shutdown of the other node.
5948 Notice that ignoring the return value from this function would
5950 result in an unreliable message passing, which is contradictory
5951 to the Erlang programming model. The message is not sent if this
5952 function returns false.
5953 In many systems, transient states of overloaded queues are nor‐
5955 mal. Although this function returns false does not mean that the
5956 other node is guaranteed to be non-responsive, it could be a
5957 temporary overload. Also, a return value of true does only mean
5958 that the message can be sent on the (TCP) channel without block‐
5959 ing; the message is not guaranteed to arrive at the remote node.
5960 For a disconnected non-responsive node, the return value is true
5961 (mimics the behavior of operator !). The expected behavior and
5962 the actions to take when the function returns false are applica‐
5963 tion- and hardware-specific.
5964 Warning:
5966 Use with extreme care.
5967 erlang:send_nosuspend(Dest, Msg, Options) -> boolean()
5970 Types:
5972 Dest = dst()
5974 Msg = term()
5975 Options = [noconnect]
5976 dst() =
5977 pid() |
5978 port() |
5979 (RegName :: atom()) |
5980 {RegName :: atom(), Node :: node()}
5981 The same as erlang:send(Dest, Msg, [nosuspend | Options]), but
5983 with a Boolean return value.
5984 This function behaves like erlang:send_nosuspend/2, but takes a
5986 third parameter, a list of options. The only option is nocon‐
5987 nect, which makes the function return false if the remote node
5988 is not currently reachable by the local node. The normal behav‐
5989 ior is to try to connect to the node, which can stall the
5990 process during a short period. The use of option noconnect makes
5991 it possible to be sure not to get the slightest delay when send‐
5992 ing to a remote process. This is especially useful when communi‐
5993 cating with nodes that expect to always be the connecting part
5994 (that is, nodes written in C or Java).
5995 Whenever the function returns false (either when a suspend would
5997 occur or when noconnect was specified and the node was not
5998 already connected), the message is guaranteed not to have been
5999 sent.
6000 Warning:
6002 Use with extreme care.
6003 erlang:set_cookie(Node, Cookie) -> true
6006 Types:
6008 Node = node()
6010 Cookie = atom()
6011 Sets the magic cookie of Node to the atom Cookie. If Node is the
6013 local node, the function also sets the cookie of all other
6014 unknown nodes to Cookie (see section Distributed Erlang in the
6015 Erlang Reference Manual in System Documentation).
6016 Failure: function_clause if the local node is not alive.
6018 setelement(Index, Tuple1, Value) -> Tuple2
6020 Types:
6022 Index = integer() >= 1
6024 1..tuple_size(Tuple1
6025 Tuple1 = Tuple2 = tuple()
6026 Value = term()
6027 Returns a tuple that is a copy of argument Tuple1 with the ele‐
6029 ment specified by integer argument Index (the first element is
6030 the element with index 1) replaced by argument Value, for exam‐
6031 ple:
6032 > setelement(2, {10, green, bottles}, red).
6034 {10,red,bottles}
6035 size(Item) -> integer() >= 0
6037 Types:
6039 Item = tuple() | binary()
6041 Returns the number of elements in a tuple or the number of bytes
6043 in a binary or bitstring, for example:
6044 > size({morni, mulle, bwange}).
6046 3
6047 > size(<<11, 22, 33>>).
6048 3
6049 For bitstrings, the number of whole bytes is returned. That is,
6051 if the number of bits in the bitstring is not divisible by 8,
6052 the resulting number of bytes is rounded down.
6053 Allowed in guard tests.
6055 See also tuple_size/1, byte_size/1, and bit_size/1.
6057 spawn(Fun) -> pid()
6059 Types:
6061 Fun = function()
6063 Returns the process identifier of a new process started by the
6065 application of Fun to the empty list []. Otherwise works like
6066 spawn/3.
6067 spawn(Node, Fun) -> pid()
6069 Types:
6071 Node = node()
6073 Fun = function()
6074 Returns the process identifier of a new process started by the
6076 application of Fun to the empty list [] on Node. If Node does
6077 not exist, a useless pid is returned. Otherwise works like
6078 spawn/3.
6079 spawn(Module, Function, Args) -> pid()
6081 Types:
6083 Module = module()
6085 Function = atom()
6086 Args = [term()]
6087 Returns the process identifier of a new process started by the
6089 application of Module:Function to Args.
6090 error_handler:undefined_function(Module, Function, Args) is
6092 evaluated by the new process if Module:Function/Arity does not
6093 exist (where Arity is the length of Args). The error handler can
6094 be redefined (see process_flag/2). If error_handler is unde‐
6095 fined, or the user has redefined the default error_handler and
6096 its replacement is undefined, a failure with reason undef
6097 occurs.
6098 Example:
6100 > spawn(speed, regulator, [high_speed, thin_cut]).
6102 <0.13.1>
6103 spawn(Node, Module, Function, Args) -> pid()
6105 Types:
6107 Node = node()
6109 Module = module()
6110 Function = atom()
6111 Args = [term()]
6112 Returns the process identifier (pid) of a new process started by
6114 the application of Module:Function to Args on Node. If Node does
6115 not exist, a useless pid is returned. Otherwise works like
6116 spawn/3.
6117 spawn_link(Fun) -> pid()
6119 Types:
6121 Fun = function()
6123 Returns the process identifier of a new process started by the
6125 application of Fun to the empty list []. A link is created
6126 between the calling process and the new process, atomically.
6127 Otherwise works like spawn/3.
6128 spawn_link(Node, Fun) -> pid()
6130 Types:
6132 Node = node()
6134 Fun = function()
6135 Returns the process identifier (pid) of a new process started by
6137 the application of Fun to the empty list [] on Node. A link is
6138 created between the calling process and the new process, atomi‐
6139 cally. If Node does not exist, a useless pid is returned and an
6140 exit signal with reason noconnection is sent to the calling
6141 process. Otherwise works like spawn/3.
6142 spawn_link(Module, Function, Args) -> pid()
6144 Types:
6146 Module = module()
6148 Function = atom()
6149 Args = [term()]
6150 Returns the process identifier of a new process started by the
6152 application of Module:Function to Args. A link is created
6153 between the calling process and the new process, atomically.
6154 Otherwise works like spawn/3.
6155 spawn_link(Node, Module, Function, Args) -> pid()
6157 Types:
6159 Node = node()
6161 Module = module()
6162 Function = atom()
6163 Args = [term()]
6164 Returns the process identifier (pid) of a new process started by
6166 the application of Module:Function to Args on Node. A link is
6167 created between the calling process and the new process, atomi‐
6168 cally. If Node does not exist, a useless pid is returned and an
6169 exit signal with reason noconnection is sent to the calling
6170 process. Otherwise works like spawn/3.
6171 spawn_monitor(Fun) -> {pid(), reference()}
6173 Types:
6175 Fun = function()
6177 Returns the process identifier of a new process, started by the
6179 application of Fun to the empty list [], and a reference for a
6180 monitor created to the new process. Otherwise works like
6181 spawn/3.
6182 spawn_monitor(Node, Fun) -> {pid(), reference()}
6184 Types:
6186 Node = node()
6188 Fun = function()
6189 Returns the process identifier of a new process, started by the
6191 application of Fun to the empty list [] on the node Node, and a
6192 reference for a monitor created to the new process. Otherwise
6193 works like spawn/3.
6194 If the node identified by Node does not support distributed
6196 spawn_monitor(), the call will fail with a notsup exception.
6197 spawn_monitor(Module, Function, Args) -> {pid(), reference()}
6199 Types:
6201 Module = module()
6203 Function = atom()
6204 Args = [term()]
6205 A new process is started by the application of Module:Function
6207 to Args. The process is monitored at the same time. Returns the
6208 process identifier and a reference for the monitor. Otherwise
6209 works like spawn/3.
6210 spawn_monitor(Node, Module, Function, Args) ->
6212 {pid(), reference()}
6213 Types:
6215 Node = node()
6217 Module = module()
6218 Function = atom()
6219 Args = [term()]
6220 A new process is started by the application of Module:Function
6222 to Args on the node Node. The process is monitored at the same
6223 time. Returns the process identifier and a reference for the
6224 monitor. Otherwise works like spawn/3.
6225 If the node identified by Node does not support distributed
6227 spawn_monitor(), the call will fail with a notsup exception.
6228 spawn_opt(Fun, Options) -> pid() | {pid(), reference()}
6230 Types:
6232 Fun = function()
6234 Options = [spawn_opt_option()]
6235 priority_level() = low | normal | high | max
6236 max_heap_size() =
6237 integer() >= 0 |
6238 #{size => integer() >= 0,
6239 kill => boolean(),
6240 error_logger => boolean()}
6241 message_queue_data() = off_heap | on_heap
6242 spawn_opt_option() =
6243 link | monitor |
6244 {priority, Level :: priority_level()} |
6245 {fullsweep_after, Number :: integer() >= 0} |
6246 {min_heap_size, Size :: integer() >= 0} |
6247 {min_bin_vheap_size, VSize :: integer() >= 0} |
6248 {max_heap_size, Size :: max_heap_size()} |
6249 {message_queue_data, MQD :: message_queue_data()}
6250 Returns the process identifier (pid) of a new process started by
6252 the application of Fun to the empty list []. Otherwise works
6253 like spawn_opt/4.
6254 If option monitor is specified, the newly created process is
6256 monitored, and both the pid and reference for the monitor are
6257 returned.
6258 spawn_opt(Node, Fun, Options) -> pid() | {pid(), reference()}
6260 Types:
6262 Node = node()
6264 Fun = function()
6265 Options = [monitor | link | OtherOption]
6266 OtherOption = term()
6267 Returns the process identifier (pid) of a new process started by
6269 the application of Fun to the empty list [] on Node. If Node
6270 does not exist, a useless pid is returned. Otherwise works like
6271 spawn_opt/4.
6272 Valid options depends on what options are supported by the node
6274 identified by Node. A description of valid Options for the local
6275 node of current OTP version can be found in the documentation of
6276 spawn_opt/4.
6277 spawn_opt(Module, Function, Args, Options) ->
6279 pid() | {pid(), reference()}
6280 Types:
6282 Module = module()
6284 Function = atom()
6285 Args = [term()]
6286 Options = [spawn_opt_option()]
6287 priority_level() = low | normal | high | max
6288 max_heap_size() =
6289 integer() >= 0 |
6290 #{size => integer() >= 0,
6291 kill => boolean(),
6292 error_logger => boolean()}
6293 message_queue_data() = off_heap | on_heap
6294 spawn_opt_option() =
6295 link | monitor |
6296 {priority, Level :: priority_level()} |
6297 {fullsweep_after, Number :: integer() >= 0} |
6298 {min_heap_size, Size :: integer() >= 0} |
6299 {min_bin_vheap_size, VSize :: integer() >= 0} |
6300 {max_heap_size, Size :: max_heap_size()} |
6301 {message_queue_data, MQD :: message_queue_data()}
6302 Works as spawn/3, except that an extra option list is specified
6304 when creating the process.
6305 If option monitor is specified, the newly created process is
6307 monitored, and both the pid and reference for the monitor are
6308 returned.
6309 Options:
6311 link:
6313 Sets a link to the parent process (like spawn_link/3 does).
6314 monitor:
6316 Monitors the new process (like monitor/2 does).
6317 {priority, Level}:
6319 Sets the priority of the new process. Equivalent to execut‐
6320 ing process_flag(priority, Level) in the start function of
6321 the new process, except that the priority is set before the
6322 process is selected for execution for the first time. For
6323 more information on priorities, see process_flag(priority,
6324 Level).
6325 {fullsweep_after, Number}:
6327 Useful only for performance tuning. Do not use this option
6328 unless you know that there is problem with execution times
6329 or memory consumption, and ensure that the option improves
6330 matters.
6331 The Erlang runtime system uses a generational garbage col‐
6333 lection scheme, using an "old heap" for data that has sur‐
6334 vived at least one garbage collection. When there is no more
6335 room on the old heap, a fullsweep garbage collection is
6336 done.
6337 Option fullsweep_after makes it possible to specify the max‐
6339 imum number of generational collections before forcing a
6340 fullsweep, even if there is room on the old heap. Setting
6341 the number to zero disables the general collection algo‐
6342 rithm, that is, all live data is copied at every garbage
6343 collection.
6344 A few cases when it can be useful to change fullsweep_after:
6346 * If binaries that are no longer used are to be thrown away
6348 as soon as possible. (Set Number to zero.)
6349 * A process that mostly have short-lived data is fullsweeped
6351 seldom or never, that is, the old heap contains mostly
6352 garbage. To ensure a fullsweep occasionally, set Number to
6353 a suitable value, such as 10 or 20.
6354 * In embedded systems with a limited amount of RAM and no
6356 virtual memory, you might want to preserve memory by set‐
6357 ting Number to zero. (The value can be set globally, see
6358 erlang:system_flag/2.)
6359 {min_heap_size, Size}:
6361 Useful only for performance tuning. Do not use this option
6362 unless you know that there is problem with execution times
6363 or memory consumption, and ensure that the option improves
6364 matters.
6365 Gives a minimum heap size, in words. Setting this value
6367 higher than the system default can speed up some processes
6368 because less garbage collection is done. However, setting a
6369 too high value can waste memory and slow down the system
6370 because of worse data locality. Therefore, use this option
6371 only for fine-tuning an application and to measure the exe‐
6372 cution time with various Size values.
6373 {min_bin_vheap_size, VSize}:
6375 Useful only for performance tuning. Do not use this option
6376 unless you know that there is problem with execution times
6377 or memory consumption, and ensure that the option improves
6378 matters.
6379 Gives a minimum binary virtual heap size, in words. Setting
6381 this value higher than the system default can speed up some
6382 processes because less garbage collection is done. However,
6383 setting a too high value can waste memory. Therefore, use
6384 this option only for fine-tuning an application and to mea‐
6385 sure the execution time with various VSize values.
6386 {max_heap_size, Size}:
6388 Sets the max_heap_size process flag. The default
6389 max_heap_size is determined by command-line argument +hmax
6390 in erl(1). For more information, see the documentation of
6391 process_flag(max_heap_size, Size).
6392 {message_queue_data, MQD}:
6394 Sets the value of the message_queue_data process flag. MQD
6395 can be either off_heap or on_heap. The default value of the
6396 message_queue_data process flag is determined by the com‐
6397 mand-line argument +hmqd in erl(1). For more information,
6398 see the documentation of process_flag(message_queue_data,
6399 MQD).
6400 spawn_opt(Node, Module, Function, Args, Options) ->
6402 pid() | {pid(), reference()}
6403 Types:
6405 Node = node()
6407 Module = module()
6408 Function = atom()
6409 Args = [term()]
6410 Options = [monitor | link | OtherOption]
6411 OtherOption = term()
6412 Returns the process identifier (pid) of a new process started by
6414 the application of Module:Function to Args on Node. If Node does
6415 not exist, a useless pid is returned. Otherwise works like
6416 spawn_opt/4.
6417 Valid options depends on what options are supported by the node
6419 identified by Node. A description of valid Options for the local
6420 node of current OTP version can be found in the documentation of
6421 spawn_opt/4.
6422 spawn_request(Fun) -> ReqId
6424 Types:
6426 Fun = function()
6428 ReqId = reference()
6429 The same as the call spawn_request(node(),Fun,[]). That is, a
6431 spawn request on the local node with no options.
6432 spawn_request(Fun, Options) -> ReqId
6434 Types:
6436 Fun = function()
6438 Option =
6439 {reply_tag, ReplyTag} | {reply, Reply} |
6440 spawn_opt_option()
6441 ReplyTag = term()
6442 Reply = yes | no | error_only | success_only
6443 Options = [Option]
6444 ReqId = reference()
6445 The same as the call spawn_request(node(),Fun,Options). That is,
6447 a spawn request on the local node.
6448 spawn_request(Node, Fun) -> ReqId
6450 Types:
6452 Node = node()
6454 Fun = function()
6455 ReqId = reference()
6456 The same as the call spawn_request(Node,Fun,[]). That is, a
6458 spawn request with no options.
6459 spawn_request(Node, Fun, Options) -> ReqId
6461 Types:
6463 Node = node()
6465 Fun = function()
6466 Options = [Option]
6467 Option =
6468 monitor | link |
6469 {reply_tag, ReplyTag} |
6470 {reply, Reply} |
6471 OtherOption
6472 ReplyTag = term()
6473 Reply = yes | no | error_only | success_only
6474 OtherOption = term()
6475 ReqId = reference()
6476 The same as spawn_request(Node,erlang,apply,[Fun,[]],Options).
6478 That is, a spawn request using the fun Fun of arity zero as
6479 entry point.
6480 This function will fail with a badarg exception if:
6482 * Node is not an atom.
6484 * Fun is not a fun of arity zero.
6486 * Options is not a proper list of terms.
6488 spawn_request(Module, Function, Args) -> ReqId
6490 Types:
6492 Module = module()
6494 Function = atom()
6495 Args = [term()]
6496 ReqId = reference()
6497 The same as the call spawn_request(node(),Module,Func‐
6499 tion,Args,[]). That is, a spawn request on the local node with
6500 no options.
6501 spawn_request(Node, Module, Function, Args) -> ReqId
6503 Types:
6505 Node = node()
6507 Module = module()
6508 Function = atom()
6509 Args = [term()]
6510 ReqId = reference()
6511 The same as the call spawn_request(Node,Module,Func‐
6513 tion,Args,[]). That is, a spawn request with no options.
6514 spawn_request(Module, Function, Args, Options) -> ReqId
6516 Types:
6518 Module = module()
6520 Function = atom()
6521 Args = [term()]
6522 Option =
6523 {reply_tag, ReplyTag} | {reply, Reply} |
6524 spawn_opt_option()
6525 ReplyTag = term()
6526 Reply = yes | no | error_only | success_only
6527 Options = [Option]
6528 ReqId = reference()
6529 The same as the call spawn_request(node(),Module,Func‐
6531 tion,Args,Options). That is, a spawn request on the local node.
6532 spawn_request(Node, Module, Function, Args, Options) -> ReqId
6534 Types:
6536 Node = node()
6538 Module = module()
6539 Function = atom()
6540 Args = [term()]
6541 Options = [Option]
6542 Option =
6543 monitor | link |
6544 {reply_tag, ReplyTag} |
6545 {reply, Reply} |
6546 OtherOption
6547 ReplyTag = term()
6548 Reply = yes | no | error_only | success_only
6549 OtherOption = term()
6550 ReqId = reference()
6551 Asynchronously send a spawn request. Returns a request identi‐
6553 fier ReqId.
6554 If the spawn operation succeeds, a new process is created on the
6556 node identified by Node. When a spawn operation succeeds, the
6557 caller will by default be sent a message on the form {ReplyTag,
6558 ReqId, ok, Pid} where Pid is the process identifier of the newly
6559 created process. Such a message is referred to as a success mes‐
6560 sage below in the text. ReplyTag is by default the atom
6561 spawn_reply unless modified by the {reply_tag, ReplyTag} option.
6562 The new process is started by the application of Module:Function
6563 to Args.
6564 The spawn operation fails either if creation of a new process
6566 failed or if the spawn operation was interrupted by a connection
6567 failure. When a spawn operation fails, the caller will by
6568 default be sent a message on the form {ReplyTag, ReqId, error,
6569 Reason} where Reason is the error reason. Such a message is
6570 referred to as an error message below in the text. Currently
6571 the following spawn error Reasons are defined, but other reasons
6572 can appear at any time without prior notice:
6573 badopt:
6575 An invalid Option was passed as argument. Note that differ‐
6576 ent runtime systems may support different options.
6577 notsup:
6579 The node identified by Node does not support spawn opera‐
6580 tions issued by spawn_request().
6581 noconnection:
6583 Failure to set up a connection to the node identified by
6584 Node or the connection to that node was lost during the
6585 spawn operation. In the case the connection was lost, a
6586 process may or may not have been created.
6587 system_limit:
6589 Could not create a new process due to that some system limit
6590 was reached. Typically the process table was full.
6591 Valid Options:
6593 monitor:
6595 In the absence of spawn operation failures, atomically sets
6596 up a monitor to the newly created process. That is, as if
6597 the calling process had called monitor(process, Pid) where
6598 Pid is the process identifier of the newly created process.
6599 The ReqId returned by spawn_request() is also used as moni‐
6600 tor reference as if it was returned from monitor(process,
6601 Pid).
6602 The monitor will not be activated for the calling process
6604 until the spawn operation has succeeded. The monitor can not
6605 be demonitored before the operation has succeeded. A 'DOWN'
6606 message for the corresponding monitor is guaranteed not to
6607 be delivered before a success message that corresponds to
6608 the spawn operation. If the spawn operation fails, no 'DOWN'
6609 message will be delivered.
6610 If the connection between the nodes involved in the spawn
6612 operation is lost during the spawn operation, the spawn
6613 operation will fail with an error reason of noconnection. A
6614 new process may or may not have been created.
6615 link:
6617 In absence of spawn operation failures, atomically sets up a
6618 link between the calling process and the newly created
6619 process. That is, as if the calling process had called
6620 link(Pid) where Pid is the process identifier of the newly
6621 created process.
6622 The link will not be activated for the calling process until
6624 the spawn operation has succeeded. The link can not be
6625 removed before the operation has succeeded. An exit signal
6626 due to the link is guaranteed not to be delivered before a
6627 success message that corresponds to the spawn operation. If
6628 the spawn operation fails, no exit signal due to the link
6629 will be delivered to the caller of spawn_request().
6630 If the connection between the nodes involved in the spawn
6632 operation is lost during the spawn operation, the spawn
6633 operation will fail with an error reason of noconnection. A
6634 new process may or may not have been created. If it has been
6635 created, it will be delivered an exit signal with an exit
6636 reason of noconnection.
6637 {reply, Reply}:
6639 Valid Reply values:
6640 yes:
6642 A spawn reply message will be sent to the caller regard‐
6643 less of whether the operation succeeds or not. If the call
6644 to spawn_request() returns without raising an exception
6645 and the reply option is set to yes, the caller is guaran‐
6646 teed to be delivered either a success message or an error
6647 message . The reply option is by default set to yes.
6648 no:
6650 No spawn reply message will be sent to the caller when the
6651 spawn operation completes. This regardless of whether the
6652 operation succeeds or not.
6653 error_only:
6655 No spawn reply message will be sent to the caller if the
6656 spawn operation succeeds, but an error message will be
6657 sent to the caller if the operation fails.
6658 success_only:
6660 No spawn reply message will be sent to the caller if the
6661 spawn operation fails, but a success message will be sent
6662 to the caller if the operation succeeds.
6663 {reply_tag, ReplyTag}:
6665 Sets the reply tag to ReplyTag in the reply message. That
6666 is, in the success or error message that is sent to the
6667 caller due to the spawn operation. The default reply tag is
6668 the atom spawn_reply.
6669 OtherOption:
6671 Other valid options depends on what options are supported by
6672 the node identified by Node. A description of other valid
6673 Options for the local node of current OTP version can be
6674 found in the documentation of spawn_opt/4.
6675 This function will fail with a badarg exception if:
6677 * Node is not an atom.
6679 * Module is not an atom.
6681 * Function is not an atom.
6683 * Args is not a proper list of terms.
6685 * Options is not a proper list of terms.
6687 Note that not all individual Options are checked when the spawn
6689 request is sent. Some Options can only be checked on reception
6690 of the request. Therefore an invalid option does not cause a
6691 badarg exception, but will cause the spawn operation to fail
6692 with an error reason of badopt.
6693 A spawn request can be abandoned by calling spawn_request_aban‐
6695 don/1.
6696 spawn_request_abandon(ReqId :: reference()) -> boolean()
6698 Abandon a previously issued spawn request. ReqId corresponds to
6700 a request identifier previously returned by spawn_request() in a
6701 call from current process. That is, only the process that has
6702 made the request can abandon the request.
6703 A spawn request can only be successfully abandoned until the
6705 spawn request has completed. When a spawn request has been suc‐
6706 cessfully abandoned, the caller will not be effected by future
6707 direct effects of the spawn request itself. For example, it will
6708 not receive a spawn reply message. The request is however not
6709 withdrawn, so a new process may or may not be created due to the
6710 request. If a new process is created after the spawn request was
6711 abandoned, no monitors nor links will be set up to the caller of
6712 spawn_request_abandon/1 due to the spawn request. If the spawn
6713 request included the link option, the process created due to
6714 this request will be sent an exit signal from its parent with
6715 the exit reason abandoned when it is detected that the spawn
6716 operation has succeeded.
6717 Note:
6719 A process created due to a spawn request that has been abandoned
6720 may communicate with its parent as any other process. It is only
6721 the direct effects on the parent of the actual spawn request,
6722 that will be canceled by abandoning a spawn request.
6723 Return values:
6726 true:
6728 The spawn request was successfully abandoned.
6729 false:
6731 No spawn request was abandoned. The ReqId request identifier
6732 did not correspond to an outstanding spawn request issued by
6733 the calling process. The reason for this is either:
6734 * ReqId corresponds to a spawn request previoulsy made by
6736 the calling process. The spawn operation has completed and
6737 a spawn reply has already been delivered to the calling
6738 process unless the spawn reply was disabled in the
6739 request.
6740 * ReqId does not correspond to a spawn request that has been
6742 made by the calling process.
6743 This function fail with a badarg exception if ReqId is not a
6745 reference.
6746 split_binary(Bin, Pos) -> {binary(), binary()}
6748 Types:
6750 Bin = binary()
6752 Pos = integer() >= 0
6753 0..byte_size(Bin)
6754 Returns a tuple containing the binaries that are the result of
6756 splitting Bin into two parts at position Pos. This is not a
6757 destructive operation. After the operation, there are three
6758 binaries altogether. Example:
6759 > B = list_to_binary("0123456789").
6761 <<"0123456789">>
6762 > byte_size(B).
6763 10
6764 > {B1, B2} = split_binary(B,3).
6765 {<<"012">>,<<"3456789">>}
6766 > byte_size(B1).
6767 3
6768 > byte_size(B2).
6769 7
6770 erlang:start_timer(Time, Dest, Msg) -> TimerRef
6772 Types:
6774 Time = integer() >= 0
6776 Dest = pid() | atom()
6777 Msg = term()
6778 TimerRef = reference()
6779 Starts a timer. The same as calling erlang:start_timer(Time,
6781 Dest, Msg, []).
6782 erlang:start_timer(Time, Dest, Msg, Options) -> TimerRef
6784 Types:
6786 Time = integer()
6788 Dest = pid() | atom()
6789 Msg = term()
6790 Options = [Option]
6791 Abs = boolean()
6792 Option = {abs, Abs}
6793 TimerRef = reference()
6794 Starts a timer. When the timer expires, the message {timeout,
6796 TimerRef, Msg} is sent to the process identified by Dest.
6797 Options:
6799 {abs, false}:
6801 This is the default. It means the Time value is interpreted
6802 as a time in milliseconds relative current Erlang monotonic
6803 time.
6804 {abs, true}:
6806 Absolute Time value. The Time value is interpreted as an
6807 absolute Erlang monotonic time in milliseconds.
6808 More Options can be added in the future.
6810 The absolute point in time, the timer is set to expire on, must
6812 be in the interval [erlang:system_info(start_time), erlang:sys‐
6813 tem_info(end_time)]. If a relative time is specified, the Time
6814 value is not allowed to be negative.
6815 If Dest is a pid(), it must be a pid() of a process created on
6817 the current runtime system instance. This process has either
6818 terminated or not. If Dest is an atom(), it is interpreted as
6819 the name of a locally registered process. The process referred
6820 to by the name is looked up at the time of timer expiration. No
6821 error is returned if the name does not refer to a process.
6822 If Dest is a pid(), the timer is automatically canceled if the
6824 process referred to by the pid() is not alive, or if the process
6825 exits. This feature was introduced in ERTS 5.4.11. Notice that
6826 timers are not automatically canceled when Dest is an atom().
6827 See also erlang:send_after/4, erlang:cancel_timer/2, and
6829 erlang:read_timer/2.
6830 Failure: badarg if the arguments do not satisfy the requirements
6832 specified here.
6833 statistics(Item :: active_tasks) -> [ActiveTasks]
6835 Types:
6837 ActiveTasks = integer() >= 0
6839 Returns the same as statistics(active_tasks_all) with the excep‐
6841 tion that no information about the dirty IO run queue and its
6842 associated schedulers is part of the result. That is, only tasks
6843 that are expected to be CPU bound are part of the result.
6844 statistics(Item :: active_tasks_all) -> [ActiveTasks]
6846 Types:
6848 ActiveTasks = integer() >= 0
6850 Returns a list where each element represents the amount of
6852 active processes and ports on each run queue and its associated
6853 schedulers. That is, the number of processes and ports that are
6854 ready to run, or are currently running. Values for normal run
6855 queues and their associated schedulers are located first in the
6856 resulting list. The first element corresponds to scheduler num‐
6857 ber 1 and so on. If support for dirty schedulers exist, an ele‐
6858 ment with the value for the dirty CPU run queue and its associ‐
6859 ated dirty CPU schedulers follow and then as last element the
6860 value for the the dirty IO run queue and its associated dirty IO
6861 schedulers follow. The information is not gathered atomically.
6862 That is, the result is not necessarily a consistent snapshot of
6863 the state, but instead quite efficiently gathered.
6864 Note:
6866 Each normal scheduler has one run queue that it manages. If
6867 dirty schedulers schedulers are supported, all dirty CPU sched‐
6868 ulers share one run queue, and all dirty IO schedulers share one
6869 run queue. That is, we have multiple normal run queues, one
6870 dirty CPU run queue and one dirty IO run queue. Work can not
6871 migrate between the different types of run queues. Only work in
6872 normal run queues can migrate to other normal run queues. This
6873 has to be taken into account when evaluating the result.
6874 See also statistics(total_active_tasks), statis‐
6877 tics(run_queue_lengths), statistics(run_queue_lengths_all), sta‐
6878 tistics(total_run_queue_lengths), and statis‐
6879 tics(total_run_queue_lengths_all).
6880 statistics(Item :: context_switches) -> {ContextSwitches, 0}
6882 Types:
6884 ContextSwitches = integer() >= 0
6886 Returns the total number of context switches since the system
6888 started.
6889 statistics(Item :: exact_reductions) ->
6891 {Total_Exact_Reductions,
6892 Exact_Reductions_Since_Last_Call}
6893 Types:
6895 Total_Exact_Reductions = Exact_Reductions_Since_Last_Call =
6897 integer() >= 0
6898 Returns the number of exact reductions.
6900 Note:
6902 statistics(exact_reductions) is a more expensive operation than
6903 statistics(reductions).
6904 statistics(Item :: garbage_collection) ->
6907 {Number_of_GCs, Words_Reclaimed, 0}
6908 Types:
6910 Number_of_GCs = Words_Reclaimed = integer() >= 0
6912 Returns information about garbage collection, for example:
6914 > statistics(garbage_collection).
6916 {85,23961,0}
6917 This information can be invalid for some implementations.
6919 statistics(Item :: io) -> {{input, Input}, {output, Output}}
6921 Types:
6923 Input = Output = integer() >= 0
6925 Returns Input, which is the total number of bytes received
6927 through ports, and Output, which is the total number of bytes
6928 output to ports.
6929 statistics(Item :: microstate_accounting) ->
6931 [MSAcc_Thread] | undefined
6932 Types:
6934 MSAcc_Thread =
6936 #{type := MSAcc_Thread_Type,
6937 id := MSAcc_Thread_Id,
6938 counters := MSAcc_Counters}
6939 MSAcc_Thread_Type =
6940 async | aux | dirty_io_scheduler | dirty_cpu_scheduler |
6941 poll | scheduler
6942 MSAcc_Thread_Id = integer() >= 0
6943 MSAcc_Counters = #{MSAcc_Thread_State => integer() >= 0}
6944 MSAcc_Thread_State =
6945 alloc | aux | bif | busy_wait | check_io | emulator | ets
6946 |
6947 gc | gc_fullsweep | nif | other | port | send | sleep |
6948 timers
6949 Microstate accounting can be used to measure how much time the
6951 Erlang runtime system spends doing various tasks. It is designed
6952 to be as lightweight as possible, but some overhead exists when
6953 this is enabled. Microstate accounting is meant to be a profil‐
6954 ing tool to help finding performance bottlenecks. To
6955 start/stop/reset microstate accounting, use system flag
6956 microstate_accounting.
6957 statistics(microstate_accounting) returns a list of maps repre‐
6959 senting some of the OS threads within ERTS. Each map contains
6960 type and id fields that can be used to identify what thread it
6961 is, and also a counters field that contains data about how much
6962 time has been spent in the various states.
6963 Example:
6965 > erlang:statistics(microstate_accounting).
6967 [#{counters => #{aux => 1899182914,
6968 check_io => 2605863602,
6969 emulator => 45731880463,
6970 gc => 1512206910,
6971 other => 5421338456,
6972 port => 221631,
6973 sleep => 5150294100},
6974 id => 1,
6975 type => scheduler}|...]
6976 The time unit is the same as returned by os:perf_counter/0. So,
6978 to convert it to milliseconds, you can do something like this:
6979 lists:map(
6981 fun(#{ counters := Cnt } = M) ->
6982 MsCnt = maps:map(fun(_K, PerfCount) ->
6983 erlang:convert_time_unit(PerfCount, perf_counter, 1000)
6984 end, Cnt),
6985 M#{ counters := MsCnt }
6986 end, erlang:statistics(microstate_accounting)).
6987 Notice that these values are not guaranteed to be the exact time
6989 spent in each state. This is because of various optimisation
6990 done to keep the overhead as small as possible.
6991 MSAcc_Thread_Types:
6993 scheduler:
6995 The main execution threads that do most of the work. See erl
6996 +S for more details.
6997 dirty_cpu_scheduler:
6999 The threads for long running cpu intensive work. See erl
7000 +SDcpu for more details.
7001 dirty_io_scheduler:
7003 The threads for long running I/O work. See erl +SDio for
7004 more details.
7005 async:
7007 Async threads are used by various linked-in drivers (mainly
7008 the file drivers) do offload non-CPU intensive work. See erl
7009 +A for more details.
7010 aux:
7012 Takes care of any work that is not specifically assigned to
7013 a scheduler.
7014 poll:
7016 Does the IO polling for the emulator. See erl +IOt for more
7017 details.
7018 The following MSAcc_Thread_States are available. All states are
7020 exclusive, meaning that a thread cannot be in two states at
7021 once. So, if you add the numbers of all counters in a thread,
7022 you get the total runtime for that thread.
7023 aux:
7025 Time spent handling auxiliary jobs.
7026 check_io:
7028 Time spent checking for new I/O events.
7029 emulator:
7031 Time spent executing Erlang processes.
7032 gc:
7034 Time spent doing garbage collection. When extra states are
7035 enabled this is the time spent doing non-fullsweep garbage
7036 collections.
7037 other:
7039 Time spent doing unaccounted things.
7040 port:
7042 Time spent executing ports.
7043 sleep:
7045 Time spent sleeping.
7046 More fine-grained MSAcc_Thread_States can be added through con‐
7048 figure (such as ./configure --with-microstate-accounting=extra).
7049 Enabling these states causes performance degradation when
7050 microstate accounting is turned off and increases the overhead
7051 when it is turned on.
7052 alloc:
7054 Time spent managing memory. Without extra states this time
7055 is spread out over all other states.
7056 bif:
7058 Time spent in BIFs. Without extra states this time is part
7059 of the emulator state.
7060 busy_wait:
7062 Time spent busy waiting. This is also the state where a
7063 scheduler no longer reports that it is active when using
7064 statistics(scheduler_wall_time). So, if you add all other
7065 states but this and sleep, and then divide that by all time
7066 in the thread, you should get something very similar to the
7067 scheduler_wall_time fraction. Without extra states this time
7068 is part of the other state.
7069 ets:
7071 Time spent executing ETS BIFs. Without extra states this
7072 time is part of the emulator state.
7073 gc_full:
7075 Time spent doing fullsweep garbage collection. Without extra
7076 states this time is part of the gc state.
7077 nif:
7079 Time spent in NIFs. Without extra states this time is part
7080 of the emulator state.
7081 send:
7083 Time spent sending messages (processes only). Without extra
7084 states this time is part of the emulator state.
7085 timers:
7087 Time spent managing timers. Without extra states this time
7088 is part of the other state.
7089 The utility module msacc(3) can be used to more easily analyse
7091 these statistics.
7092 Returns undefined if system flag microstate_accounting is turned
7094 off.
7095 The list of thread information is unsorted and can appear in
7097 different order between calls.
7098 Note:
7100 The threads and states are subject to change without any prior
7101 notice.
7102 statistics(Item :: reductions) ->
7105 {Total_Reductions, Reductions_Since_Last_Call}
7106 Types:
7108 Total_Reductions = Reductions_Since_Last_Call = integer() >=
7110 0
7111 Returns information about reductions, for example:
7113 > statistics(reductions).
7115 {2046,11}
7116 Note:
7118 As from ERTS 5.5 (Erlang/OTP R11B), this value does not include
7119 reductions performed in current time slices of currently sched‐
7120 uled processes. If an exact value is wanted, use statis‐
7121 tics(exact_reductions).
7122 statistics(Item :: run_queue) -> integer() >= 0
7125 Returns the total length of all normal and dirty CPU run queues.
7127 That is, queued work that is expected to be CPU bound. The
7128 information is gathered atomically. That is, the result is a
7129 consistent snapshot of the state, but this operation is much
7130 more expensive compared to statistics(total_run_queue_lengths),
7131 especially when a large amount of schedulers is used.
7132 statistics(Item :: run_queue_lengths) -> [RunQueueLength]
7134 Types:
7136 RunQueueLength = integer() >= 0
7138 Returns the same as statistics(run_queue_lengths_all) with the
7140 exception that no information about the dirty IO run queue is
7141 part of the result. That is, only run queues with work that is
7142 expected to be CPU bound is part of the result.
7143 statistics(Item :: run_queue_lengths_all) -> [RunQueueLength]
7145 Types:
7147 RunQueueLength = integer() >= 0
7149 Returns a list where each element represents the amount of pro‐
7151 cesses and ports ready to run for each run queue. Values for
7152 normal run queues are located first in the resulting list. The
7153 first element corresponds to the normal run queue of scheduler
7154 number 1 and so on. If support for dirty schedulers exist, val‐
7155 ues for the dirty CPU run queue and the dirty IO run queue fol‐
7156 low (in that order) at the end. The information is not gathered
7157 atomically. That is, the result is not necessarily a consistent
7158 snapshot of the state, but instead quite efficiently gathered.
7159 Note:
7161 Each normal scheduler has one run queue that it manages. If
7162 dirty schedulers schedulers are supported, all dirty CPU sched‐
7163 ulers share one run queue, and all dirty IO schedulers share one
7164 run queue. That is, we have multiple normal run queues, one
7165 dirty CPU run queue and one dirty IO run queue. Work can not
7166 migrate between the different types of run queues. Only work in
7167 normal run queues can migrate to other normal run queues. This
7168 has to be taken into account when evaluating the result.
7169 See also statistics(run_queue_lengths), statis‐
7172 tics(total_run_queue_lengths_all), statis‐
7173 tics(total_run_queue_lengths), statistics(active_tasks), statis‐
7174 tics(active_tasks_all), and statistics(total_active_tasks), sta‐
7175 tistics(total_active_tasks_all).
7176 statistics(Item :: runtime) ->
7178 {Total_Run_Time, Time_Since_Last_Call}
7179 Types:
7181 Total_Run_Time = Time_Since_Last_Call = integer() >= 0
7183 Returns information about runtime, in milliseconds.
7185 This is the sum of the runtime for all threads in the Erlang
7187 runtime system and can therefore be greater than the wall clock
7188 time.
7189 Warning:
7191 This value might wrap due to limitations in the underlying func‐
7192 tionality provided by the operating system that is used.
7193 Example:
7196 > statistics(runtime).
7198 {1690,1620}
7199 statistics(Item :: scheduler_wall_time) ->
7201 [{SchedulerId, ActiveTime, TotalTime}] | undefined
7202 Types:
7204 SchedulerId = integer() >= 1
7206 ActiveTime = TotalTime = integer() >= 0
7207 Returns a list of tuples with {SchedulerId, ActiveTime, Total‐
7209 Time}, where SchedulerId is an integer ID of the scheduler,
7210 ActiveTime is the duration the scheduler has been busy, and
7211 TotalTime is the total time duration since scheduler_wall_time
7212 activation for the specific scheduler. Note that activation time
7213 can differ significantly between schedulers. Currently dirty
7214 schedulers are activated at system start while normal schedulers
7215 are activated some time after the scheduler_wall_time function‐
7216 ality is enabled. The time unit is undefined and can be subject
7217 to change between releases, OSs, and system restarts. sched‐
7218 uler_wall_time is only to be used to calculate relative values
7219 for scheduler utilization. ActiveTime can never exceed Total‐
7220 Time.
7221 The definition of a busy scheduler is when it is not idle and is
7223 not scheduling (selecting) a process or port, that is:
7224 * Executing process code
7226 * Executing linked-in driver or NIF code
7228 * Executing BIFs, or any other runtime handling
7230 * Garbage collecting
7232 * Handling any other memory management
7234 Notice that a scheduler can also be busy even if the OS has
7236 scheduled out the scheduler thread.
7237 Returns undefined if system flag scheduler_wall_time is turned
7239 off.
7240 The list of scheduler information is unsorted and can appear in
7242 different order between calls.
7243 As of ERTS version 9.0, also dirty CPU schedulers will be
7245 included in the result. That is, all scheduler threads that are
7246 expected to handle CPU bound work. If you also want information
7247 about dirty I/O schedulers, use statistics(sched‐
7248 uler_wall_time_all) instead.
7249 Normal schedulers will have scheduler identifiers in the range 1
7251 =< SchedulerId =< erlang:system_info(schedulers). Dirty CPU
7252 schedulers will have scheduler identifiers in the range
7253 erlang:system_info(schedulers) < SchedulerId =< erlang:sys‐
7254 tem_info(schedulers) + erlang:system_info(dirty_cpu_schedulers).
7255 Note:
7257 The different types of schedulers handle specific types of jobs.
7258 Every job is assigned to a specific scheduler type. Jobs can
7259 migrate between different schedulers of the same type, but never
7260 between schedulers of different types. This fact has to be taken
7261 under consideration when evaluating the result returned.
7262 Using scheduler_wall_time to calculate scheduler utilization:
7265 > erlang:system_flag(scheduler_wall_time, true).
7267 false
7268 > Ts0 = lists:sort(erlang:statistics(scheduler_wall_time)), ok.
7269 ok
7270 Some time later the user takes another snapshot and calculates
7272 scheduler utilization per scheduler, for example:
7273 > Ts1 = lists:sort(erlang:statistics(scheduler_wall_time)), ok.
7275 ok
7276 > lists:map(fun({{I, A0, T0}, {I, A1, T1}}) -> {I, (A1 - A0)/(T1 - T0)} end, lists:zip(Ts0,Ts1)).
7277 [{1,0.9743474730177548},
7278 {2,0.9744843782751444},
7279 {3,0.9995902361669045},
7280 {4,0.9738012596572161},
7281 {5,0.9717956667018103},
7282 {6,0.9739235846420741},
7283 {7,0.973237033077876},
7284 {8,0.9741297293248656}]
7285 Using the same snapshots to calculate a total scheduler utiliza‐
7287 tion:
7288 > {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.
7290 0.9769136803764825
7291 Total scheduler utilization will equal 1.0 when all schedulers
7293 have been active all the time between the two measurements.
7294 Another (probably more) useful value is to calculate total
7296 scheduler utilization weighted against maximum amount of avail‐
7297 able CPU time:
7298 > WeightedSchedulerUtilization = (TotalSchedulerUtilization * (erlang:system_info(schedulers) + erlang:system_info(dirty_cpu_schedulers))) / erlang:system_info(logical_processors_available).
7300 0.9769136803764825
7301 This weighted scheduler utilization will reach 1.0 when sched‐
7303 ulers are active the same amount of time as maximum available
7304 CPU time. If more schedulers exist than available logical pro‐
7305 cessors, this value may be greater than 1.0.
7306 As of ERTS version 9.0, the Erlang runtime system will as
7308 default have more schedulers than logical processors. This due
7309 to the dirty schedulers.
7310 Note:
7312 scheduler_wall_time is by default disabled. To enable it, use
7313 erlang:system_flag(scheduler_wall_time, true).
7314 statistics(Item :: scheduler_wall_time_all) ->
7317 [{SchedulerId, ActiveTime, TotalTime}] | undefined
7318 Types:
7320 SchedulerId = integer() >= 1
7322 ActiveTime = TotalTime = integer() >= 0
7323 The same as statistics(scheduler_wall_time), except that it also
7325 include information about all dirty I/O schedulers.
7326 Dirty IO schedulers will have scheduler identifiers in the range
7328 erlang:system_info(schedulers) + erlang:sys‐
7329 tem_info(dirty_cpu_schedulers) < SchedulerId =< erlang:sys‐
7330 tem_info(schedulers) + erlang:system_info(dirty_cpu_schedulers)
7331 + erlang:system_info(dirty_io_schedulers).
7332 Note:
7334 Note that work executing on dirty I/O schedulers are expected to
7335 mainly wait for I/O. That is, when you get high scheduler uti‐
7336 lization on dirty I/O schedulers, CPU utilization is not
7337 expected to be high due to this work.
7338 statistics(Item :: total_active_tasks) -> ActiveTasks
7341 Types:
7343 ActiveTasks = integer() >= 0
7345 The same as calling lists:sum(statistics(active_tasks)), but
7347 more efficient.
7348 statistics(Item :: total_active_tasks_all) -> ActiveTasks
7350 Types:
7352 ActiveTasks = integer() >= 0
7354 The same as calling lists:sum(statistics(active_tasks_all)), but
7356 more efficient.
7357 statistics(Item :: total_run_queue_lengths) ->
7359 TotalRunQueueLengths
7360 Types:
7362 TotalRunQueueLengths = integer() >= 0
7364 The same as calling lists:sum(statistics(run_queue_lengths)),
7366 but more efficient.
7367 statistics(Item :: total_run_queue_lengths_all) ->
7369 TotalRunQueueLengths
7370 Types:
7372 TotalRunQueueLengths = integer() >= 0
7374 The same as calling lists:sum(statis‐
7376 tics(run_queue_lengths_all)), but more efficient.
7377 statistics(Item :: wall_clock) ->
7379 {Total_Wallclock_Time,
7380 Wallclock_Time_Since_Last_Call}
7381 Types:
7383 Total_Wallclock_Time = Wallclock_Time_Since_Last_Call = inte‐
7385 ger() >= 0
7386 Returns information about wall clock. wall_clock can be used in
7388 the same manner as runtime, except that real time is measured as
7389 opposed to runtime or CPU time.
7390 erlang:suspend_process(Suspendee) -> true
7392 Types:
7394 Suspendee = pid()
7396 Suspends the process identified by Suspendee. The same as call‐
7398 ing erlang:suspend_process(Suspendee, []).
7399 Warning:
7401 This BIF is intended for debugging only.
7402 erlang:suspend_process(Suspendee, OptList) -> boolean()
7405 Types:
7407 Suspendee = pid()
7409 OptList = [Opt]
7410 Opt = unless_suspending | asynchronous | {asynchronous,
7411 term()}
7412 Increases the suspend count on the process identified by Sus‐
7414 pendee and puts it in the suspended state if it is not already
7415 in that state. A suspended process is not scheduled for execu‐
7416 tion until the process has been resumed.
7417 A process can be suspended by multiple processes and can be sus‐
7419 pended multiple times by a single process. A suspended process
7420 does not leave the suspended state until its suspend count
7421 reaches zero. The suspend count of Suspendee is decreased when
7422 erlang:resume_process(Suspendee) is called by the same process
7423 that called erlang:suspend_process(Suspendee). All increased
7424 suspend counts on other processes acquired by a process are
7425 automatically decreased when the process terminates.
7426 Options (Opts):
7428 asynchronous:
7430 A suspend request is sent to the process identified by Sus‐
7431 pendee. Suspendee eventually suspends unless it is resumed
7432 before it could suspend. The caller of erlang:sus‐
7433 pend_process/2 returns immediately, regardless of whether
7434 Suspendee has suspended yet or not. The point in time when
7435 Suspendee suspends cannot be deduced from other events in
7436 the system. It is only guaranteed that Suspendee eventually
7437 suspends (unless it is resumed). If no asynchronous options
7438 has been passed, the caller of erlang:suspend_process/2 is
7439 blocked until Suspendee has suspended.
7440 {asynchronous, ReplyTag}:
7442 A suspend request is sent to the process identified by Sus‐
7443 pendee. When the suspend request has been processed, a reply
7444 message is sent to the caller of this function. The reply is
7445 on the form {ReplyTag, State} where State is either:
7446 exited:
7448 Suspendee has exited.
7449 suspended:
7451 Suspendee is now suspended.
7452 not_suspended:
7454 Suspendee is not suspended. This can only happen when the
7455 process that issued this request, have called
7456 resume_process(Suspendee) before getting the reply.
7457 Appart from the reply message, the {asynchronous, ReplyTag}
7459 option behaves exactly the same as the asynchronous option
7460 without reply tag.
7461 unless_suspending:
7463 The process identified by Suspendee is suspended unless the
7464 calling process already is suspending Suspendee. If
7465 unless_suspending is combined with option asynchronous, a
7466 suspend request is sent unless the calling process already
7467 is suspending Suspendee or if a suspend request already has
7468 been sent and is in transit. If the calling process already
7469 is suspending Suspendee, or if combined with option asyn‐
7470 chronous and a send request already is in transit, false is
7471 returned and the suspend count on Suspendee remains
7472 unchanged.
7473 If the suspend count on the process identified by Suspendee is
7475 increased, true is returned, otherwise false.
7476 Warning:
7478 This BIF is intended for debugging only.
7479 Warning:
7482 You can easily create deadlocks if processes suspends each other
7483 (directly or in circles). In ERTS versions prior to ERTS version
7484 10.0, the runtime system prevented such deadlocks, but this pre‐
7485 vention has now been removed due to performance reasons.
7486 Failures:
7489 badarg:
7491 If Suspendee is not a process identifier.
7492 badarg:
7494 If the process identified by Suspendee is the same process
7495 as the process calling erlang:suspend_process/2.
7496 badarg:
7498 If the process identified by Suspendee is not alive.
7499 badarg:
7501 If the process identified by Suspendee resides on another
7502 node.
7503 badarg:
7505 If OptList is not a proper list of valid Opts.
7506 system_limit:
7508 If the process identified by Suspendee has been suspended
7509 more times by the calling process than can be represented by
7510 the currently used internal data structures. The system
7511 limit is greater than 2,000,000,000 suspends and will never
7512 be lower.
7513 erlang:system_flag(Flag :: backtrace_depth, Depth) -> OldDepth
7515 Types:
7517 Depth = OldDepth = integer() >= 0
7519 Sets the maximum depth of call stack back-traces in the exit
7521 reason element of 'EXIT' tuples. The flag also limits the stack‐
7522 trace depth returned by process_info item current_stacktrace.
7523 Returns the old value of the flag.
7525 erlang:system_flag(Flag :: cpu_topology, CpuTopology) ->
7527 OldCpuTopology
7528 Types:
7530 CpuTopology = OldCpuTopology = cpu_topology()
7532 cpu_topology() = [LevelEntry :: level_entry()] | undefined
7533 level_entry() =
7534 {LevelTag :: level_tag(), SubLevel :: sub_level()} |
7535 {LevelTag :: level_tag(),
7536 InfoList :: info_list(),
7537 SubLevel :: sub_level()}
7538 level_tag() = core | node | processor | thread
7539 sub_level() =
7540 [LevelEntry :: level_entry()] |
7541 (LogicalCpuId :: {logical, integer() >= 0})
7542 info_list() = []
7543 Warning:
7545 This argument is deprecated. Instead of using this argument, use
7546 command-line argument +sct in erl(1).
7547 When this argument is removed, a final CPU topology to use is
7549 determined at emulator boot time.
7550 Sets the user-defined CpuTopology. The user-defined CPU topology
7553 overrides any automatically detected CPU topology. By passing
7554 undefined as CpuTopology, the system reverts to the CPU topology
7555 automatically detected. The returned value equals the value
7556 returned from erlang:system_info(cpu_topology) before the change
7557 was made.
7558 Returns the old value of the flag.
7560 The CPU topology is used when binding schedulers to logical pro‐
7562 cessors. If schedulers are already bound when the CPU topology
7563 is changed, the schedulers are sent a request to rebind accord‐
7564 ing to the new CPU topology.
7565 The user-defined CPU topology can also be set by passing com‐
7567 mand-line argument +sct to erl(1).
7568 For information on type CpuTopology and more, see erlang:sys‐
7570 tem_info(cpu_topology) as well as command-line flags +sct and
7571 +sbt in erl(1).
7572 erlang:system_flag(Flag :: dirty_cpu_schedulers_online,
7574 DirtyCPUSchedulersOnline) ->
7575 OldDirtyCPUSchedulersOnline
7576 Types:
7578 DirtyCPUSchedulersOnline = OldDirtyCPUSchedulersOnline =
7580 integer() >= 1
7581 Sets the number of dirty CPU schedulers online. Range is 1 <=
7583 DirtyCPUSchedulersOnline <= N, where N is the smallest of the
7584 return values of erlang:system_info(dirty_cpu_schedulers) and
7585 erlang:system_info(schedulers_online).
7586 Returns the old value of the flag.
7588 The number of dirty CPU schedulers online can change if the num‐
7590 ber of schedulers online changes. For example, if 12 schedulers
7591 and 6 dirty CPU schedulers are online, and system_flag/2 is used
7592 to set the number of schedulers online to 6, then the number of
7593 dirty CPU schedulers online is automatically decreased by half
7594 as well, down to 3. Similarly, the number of dirty CPU sched‐
7595 ulers online increases proportionally to increases in the number
7596 of schedulers online.
7597 For more information, see erlang:system_info(dirty_cpu_sched‐
7599 ulers) and erlang:system_info(dirty_cpu_schedulers_online).
7600 erlang:system_flag(Flag :: erts_alloc, Value :: {Alloc, F, V}) ->
7602 ok | notsup
7603 Types:
7605 Alloc = F = atom()
7607 V = integer()
7608 Sets system flags for erts_alloc(3). Alloc is the allocator to
7610 affect, for example binary_alloc. F is the flag to change and V
7611 is the new value.
7612 Only a subset of all erts_alloc flags can be changed at run
7614 time. This subset is currently only the flag sbct.
7615 Returns ok if the flag was set or notsup if not supported by
7617 erts_alloc.
7618 erlang:system_flag(Flag :: fullsweep_after, Number) -> OldNumber
7620 Types:
7622 Number = OldNumber = integer() >= 0
7624 Sets system flag fullsweep_after. Number is a non-negative inte‐
7626 ger indicating how many times generational garbage collections
7627 can be done without forcing a fullsweep collection. The value
7628 applies to new processes, while processes already running are
7629 not affected.
7630 Returns the old value of the flag.
7632 In low-memory systems (especially without virtual memory), set‐
7634 ting the value to 0 can help to conserve memory.
7635 This value can also be set through (OS) environment variable
7637 ERL_FULLSWEEP_AFTER.
7638 erlang:system_flag(Flag :: microstate_accounting, Action) ->
7640 OldState
7641 Types:
7643 Action = true | false | reset
7645 OldState = true | false
7646 Turns on/off microstate accounting measurements. When passing
7648 reset, all counters are reset to 0.
7649 For more information see statistics(microstate_accounting).
7651 erlang:system_flag(Flag :: min_heap_size, MinHeapSize) ->
7653 OldMinHeapSize
7654 Types:
7656 MinHeapSize = OldMinHeapSize = integer() >= 0
7658 Sets the default minimum heap size for processes. The size is
7660 specified in words. The new min_heap_size effects only processes
7661 spawned after the change of min_heap_size has been made.
7662 min_heap_size can be set for individual processes by using
7663 spawn_opt/4 or process_flag/2.
7664 Returns the old value of the flag.
7666 erlang:system_flag(Flag :: min_bin_vheap_size, MinBinVHeapSize) ->
7668 OldMinBinVHeapSize
7669 Types:
7671 MinBinVHeapSize = OldMinBinVHeapSize = integer() >= 0
7673 Sets the default minimum binary virtual heap size for processes.
7675 The size is specified in words. The new min_bin_vhheap_size
7676 effects only processes spawned after the change of
7677 min_bin_vheap_size has been made. min_bin_vheap_size can be set
7678 for individual processes by using spawn_opt/2,3,4 or
7679 process_flag/2.
7680 Returns the old value of the flag.
7682 erlang:system_flag(Flag :: max_heap_size, MaxHeapSize) ->
7684 OldMaxHeapSize
7685 Types:
7687 MaxHeapSize = OldMaxHeapSize = max_heap_size()
7689 max_heap_size() =
7690 integer() >= 0 |
7691 #{size => integer() >= 0,
7692 kill => boolean(),
7693 error_logger => boolean()}
7694 Sets the default maximum heap size settings for processes. The
7696 size is specified in words. The new max_heap_size effects only
7697 processes spawned efter the change has been made. max_heap_size
7698 can be set for individual processes using spawn_opt/2,3,4 or
7699 process_flag/2.
7700 Returns the old value of the flag.
7702 erlang:system_flag(Flag :: multi_scheduling, BlockState) ->
7704 OldBlockState
7705 Types:
7707 BlockState = block | unblock | block_normal | unblock_normal
7709 OldBlockState = blocked | disabled | enabled
7710 If multi-scheduling is enabled, more than one scheduler thread
7712 is used by the emulator. Multi-scheduling can be blocked in two
7713 different ways. Either all schedulers but one is blocked, or all
7714 normal schedulers but one is blocked. When only normal sched‐
7715 ulers are blocked, dirty schedulers are free to continue to
7716 schedule processes.
7717 If BlockState =:= block, multi-scheduling is blocked. That is,
7719 one and only one scheduler thread will execute. If BlockState
7720 =:= unblock and no one else blocks multi-scheduling, and this
7721 process has blocked only once, multi-scheduling is unblocked.
7722 If BlockState =:= block_normal, normal multi-scheduling is
7724 blocked. That is, only one normal scheduler thread will execute,
7725 but multiple dirty schedulers can execute. If BlockState =:=
7726 unblock_normal and no one else blocks normal multi-scheduling,
7727 and this process has blocked only once, normal multi-scheduling
7728 is unblocked.
7729 One process can block multi-scheduling and normal multi-schedul‐
7731 ing multiple times. If a process has blocked multiple times, it
7732 must unblock exactly as many times as it has blocked before it
7733 has released its multi-scheduling block. If a process that has
7734 blocked multi-scheduling or normal multi-scheduling exits, it
7735 automatically releases its blocking of multi-scheduling and nor‐
7736 mal multi-scheduling.
7737 The return values are disabled, blocked, blocked_normal, or
7739 enabled. The returned value describes the state just after the
7740 call to erlang:system_flag(multi_scheduling, BlockState) has
7741 been made. For information about the return values, see
7742 erlang:system_info(multi_scheduling).
7743 Note:
7745 Blocking of multi-scheduling and normal multi-scheduling is nor‐
7746 mally not needed. If you feel that you need to use these fea‐
7747 tures, consider it a few more times again. Blocking multi-sched‐
7748 uling is only to be used as a last resort, as it is most likely
7749 a very inefficient way to solve the problem.
7750 See also erlang:system_info(multi_scheduling), erlang:sys‐
7753 tem_info(normal_multi_scheduling_blockers), erlang:sys‐
7754 tem_info(multi_scheduling_blockers), and erlang:sys‐
7755 tem_info(schedulers).
7756 erlang:system_flag(Flag :: scheduler_bind_type, How) ->
7758 OldBindType
7759 Types:
7761 How = scheduler_bind_type() | default_bind
7763 OldBindType = scheduler_bind_type()
7764 scheduler_bind_type() =
7765 no_node_processor_spread | no_node_thread_spread | no_spread |
7766 processor_spread | spread | thread_spread |
7767 thread_no_node_processor_spread | unbound
7768 Warning:
7770 This argument is deprecated. Instead of using this argument, use
7771 command-line argument +sbt in erl(1). When this argument is
7772 removed, a final scheduler bind type to use is determined at
7773 emulator boot time.
7774 Controls if and how schedulers are bound to logical processors.
7777 When erlang:system_flag(scheduler_bind_type, How) is called, an
7779 asynchronous signal is sent to all schedulers online, causing
7780 them to try to bind or unbind as requested.
7781 Note:
7783 If a scheduler fails to bind, this is often silently ignored, as
7784 it is not always possible to verify valid logical processor
7785 identifiers. If an error is reported, an error event is logged.
7786 To verify that the schedulers have bound as requested, call
7787 erlang:system_info(scheduler_bindings).
7788 Schedulers can be bound on newer Linux, Solaris, FreeBSD, and
7791 Windows systems, but more systems will be supported in future
7792 releases.
7793 In order for the runtime system to be able to bind schedulers,
7795 the CPU topology must be known. If the runtime system fails to
7796 detect the CPU topology automatically, it can be defined. For
7797 more information on how to define the CPU topology, see command-
7798 line flag +sct in erl(1).
7799 The runtime system does by default not bind schedulers to logi‐
7801 cal processors.
7802 Note:
7804 If the Erlang runtime system is the only OS process binding
7805 threads to logical processors, this improves the performance of
7806 the runtime system. However, if other OS processes (for example,
7807 another Erlang runtime system) also bind threads to logical pro‐
7808 cessors, there can be a performance penalty instead. Sometimes
7809 this performance penalty can be severe. If so, it is recommended
7810 to not bind the schedulers.
7811 Schedulers can be bound in different ways. Argument How deter‐
7814 mines how schedulers are bound and can be any of the following:
7815 unbound:
7817 Same as command-line argument +sbt u in erl(1).
7818 no_spread:
7820 Same as command-line argument +sbt ns in erl(1).
7821 thread_spread:
7823 Same as command-line argument +sbt ts in erl(1).
7824 processor_spread:
7826 Same as command-line argument +sbt ps in erl(1).
7827 spread:
7829 Same as command-line argument +sbt s in erl(1).
7830 no_node_thread_spread:
7832 Same as command-line argument +sbt nnts in erl(1).
7833 no_node_processor_spread:
7835 Same as command-line argument +sbt nnps in erl(1).
7836 thread_no_node_processor_spread:
7838 Same as command-line argument +sbt tnnps in erl(1).
7839 default_bind:
7841 Same as command-line argument +sbt db in erl(1).
7842 The returned value equals How before flag scheduler_bind_type
7844 was changed.
7845 Failures:
7847 notsup:
7849 If binding of schedulers is not supported.
7850 badarg:
7852 If How is not one of the documented alternatives.
7853 badarg:
7855 If CPU topology information is unavailable.
7856 The scheduler bind type can also be set by passing command-line
7858 argument +sbt to erl(1).
7859 For more information, see erlang:system_info(sched‐
7861 uler_bind_type), erlang:system_info(scheduler_bindings), as well
7862 as command-line flags +sbt and +sct in erl(1).
7863 erlang:system_flag(Flag :: scheduler_wall_time, Boolean) ->
7865 OldBoolean
7866 Types:
7868 Boolean = OldBoolean = boolean()
7870 Turns on or off scheduler wall time measurements.
7872 For more information, see statistics(scheduler_wall_time).
7874 erlang:system_flag(Flag :: schedulers_online, SchedulersOnline) ->
7876 OldSchedulersOnline
7877 Types:
7879 SchedulersOnline = OldSchedulersOnline = integer() >= 1
7881 Sets the number of schedulers online. Range is 1 <= Scheduler‐
7883 sOnline <= erlang:system_info(schedulers).
7884 Returns the old value of the flag.
7886 If the emulator was built with support for dirty schedulers,
7888 changing the number of schedulers online can also change the
7889 number of dirty CPU schedulers online. For example, if 12 sched‐
7890 ulers and 6 dirty CPU schedulers are online, and system_flag/2
7891 is used to set the number of schedulers online to 6, then the
7892 number of dirty CPU schedulers online is automatically decreased
7893 by half as well, down to 3. Similarly, the number of dirty CPU
7894 schedulers online increases proportionally to increases in the
7895 number of schedulers online.
7896 For more information, see erlang:system_info(schedulers) and
7898 erlang:system_info(schedulers_online).
7899 erlang:system_flag(Flag :: system_logger, Logger) -> PrevLogger
7901 Types:
7903 Logger = PrevLogger = logger | undefined | pid()
7905 Sets the process that will receive the logging messages gener‐
7907 ated by ERTS. If set to undefined, all logging messages gener‐
7908 ated by ERTS will be dropped. The messages will be in the for‐
7909 mat:
7910 {log,Level,Format,ArgList,Metadata} where
7912 Level = atom(),
7914 Format = string(),
7915 ArgList = list(term()),
7916 Metadata = #{ pid => pid(),
7917 group_leader => pid(),
7918 time := logger:timestamp(),
7919 error_logger := #{ emulator := true, tag := atom() }
7920 If the system_logger process dies, this flag will be reset to
7923 logger.
7924 The default is the process named logger.
7926 Returns the old value of the flag.
7928 Note:
7930 This function is designed to be used by the KERNEL logger. Be
7931 careful if you change it to something else as log messages may
7932 be lost. If you want to intercept emulator log messages, do it
7933 by adding a specialized handler to the KERNEL logger.
7934 erlang:system_flag(Flag :: trace_control_word, TCW) -> OldTCW
7937 Types:
7939 TCW = OldTCW = integer() >= 0
7941 Sets the value of the node trace control word to TCW, which is
7943 to be an unsigned integer. For more information, see function
7944 set_tcw in section "Match Specifications in Erlang" in the
7945 User's Guide.
7946 Returns the old value of the flag.
7948 erlang:system_flag(Flag :: time_offset, Value :: finalize) ->
7950 OldState
7951 Types:
7953 OldState = preliminary | final | volatile
7955 Finalizes the time offset when single time warp mode is used. If
7957 another time warp mode is used, the time offset state is left
7958 unchanged.
7959 Returns the old state identifier, that is:
7961 * If preliminary is returned, finalization was performed and
7963 the time offset is now final.
7964 * If final is returned, the time offset was already in the
7966 final state. This either because another erlang:sys‐
7967 tem_flag(time_offset, finalize) call or because no time warp
7968 mode is used.
7969 * If volatile is returned, the time offset cannot be finalized
7971 because multi-time warp mode is used.
7972 erlang:system_info(Item :: overview) -> boolean()
7974 Returns information about the current system. The documentation
7976 of this function is broken into the following sections in order
7977 to make it easier to navigate.
7978 Memory Allocation:
7980 allocated_areas, allocator, alloc_util_allocators, alloca‐
7981 tor_sizes, elib_malloc
7982 CPU Topology:
7984 cpu_topology, logical_processors, update_cpu_info
7985 Process Information:
7987 fullsweep_after, garbage_collection, heap_sizes, heap_type,
7988 max_heap_size, message_queue_data, min_heap_size,
7989 min_bin_vheap_size, procs
7990 System Limits:
7992 atom_count, atom_limit, ets_count, ets_limit, port_count,
7993 port_limit, process_count, process_limit
7994 System Time:
7996 end_time, os_monotonic_time_source, os_system_time_source,
7997 start_time, time_correction, time_offset, time_warp_mode,
7998 tolerant_timeofday
7999 Scheduler Information:
8001 dirty_cpu_schedulers, dirty_cpu_schedulers_online,
8002 dirty_io_schedulers, multi_scheduling, multi_schedul‐
8003 ing_blockers, normal_multi_scheduling_blockers, sched‐
8004 uler_bind_type, scheduler_bindings, scheduler_id, sched‐
8005 ulers, smp_support, threads, thread_pool_size
8006 Distribution Information:
8008 creation, delayed_node_table_gc, dist, dist_buf_busy_limit,
8009 dist_ctrl
8010 System Information:
8012 build_type, c_compiler_used, check_io, compat_rel,
8013 debug_compiled, driver_version, dynamic_trace,
8014 dynamic_trace_probes, info, kernel_poll, loaded, machine,
8015 modified_timing_level, nif_version, otp_release, port_paral‐
8016 lelism, system_architecture, system_logger, system_version,
8017 trace_control_word, version, wordsize
8018 erlang:system_info(Item :: allocated_areas) -> [tuple()]
8020 erlang:system_info(Item :: allocator) ->
8022 {Allocator, Version, Features, Settings}
8023 erlang:system_info(Item :: {allocator, Alloc}) -> [term()]
8025 erlang:system_info(Item :: alloc_util_allocators) -> [Alloc]
8027 erlang:system_info(Item :: {allocator_sizes, Alloc}) -> [term()]
8029 erlang:system_info(Item :: elib_malloc) -> false
8031 Types:
8033 Allocator = undefined | glibc
8035 Version = [integer() >= 0]
8036 Features = [atom()]
8037 Settings =
8038 [{Subsystem :: atom(),
8039 [{Parameter :: atom(), Value :: term()}]}]
8040 Alloc = atom()
8041 Returns various information about the memory allocators of the
8043 current system (emulator) as specified by Item:
8044 allocated_areas:
8046 Returns a list of tuples with information about miscella‐
8047 neous allocated memory areas.
8048 Each tuple contains an atom describing the type of memory as
8050 first element and the amount of allocated memory in bytes as
8051 second element. When information about allocated and used
8052 memory is present, also a third element is present, contain‐
8053 ing the amount of used memory in bytes.
8054 erlang:system_info(allocated_areas) is intended for debug‐
8056 ging, and the content is highly implementation-dependent.
8057 The content of the results therefore changes when needed
8058 without prior notice.
8059 Notice that the sum of these values is not the total amount
8061 of memory allocated by the emulator. Some values are part of
8062 other values, and some memory areas are not part of the
8063 result. For information about the total amount of memory
8064 allocated by the emulator, see erlang:memory/0,1.
8065 allocator:
8067 Returns {Allocator, Version, Features, Settings, where:
8068 * Allocator corresponds to the malloc() implementation used.
8070 If Allocator equals undefined, the malloc() implementation
8071 used cannot be identified. glibc can be identified.
8072 * Version is a list of integers (but not a string) repre‐
8074 senting the version of the malloc() implementation used.
8075 * Features is a list of atoms representing the allocation
8077 features used.
8078 * Settings is a list of subsystems, their configurable
8080 parameters, and used values. Settings can differ between
8081 different combinations of platforms, allocators, and allo‐
8082 cation features. Memory sizes are given in bytes.
8083 See also "System Flags Effecting erts_alloc" in
8085 erts_alloc(3).
8086 {allocator, Alloc}:
8088 Returns information about the specified allocator. As from
8089 ERTS 5.6.1, the return value is a list of {instance, Instan‐
8090 ceNo, InstanceInfo} tuples, where InstanceInfo contains
8091 information about a specific instance of the allocator. If
8092 Alloc is not a recognized allocator, undefined is returned.
8093 If Alloc is disabled, false is returned.
8094 Notice that the information returned is highly implementa‐
8096 tion-dependent and can be changed or removed at any time
8097 without prior notice. It was initially intended as a tool
8098 when developing new allocators, but as it can be of interest
8099 for others it has been briefly documented.
8100 The recognized allocators are listed in erts_alloc(3).
8102 Information about super carriers can be obtained from ERTS
8103 8.0 with {allocator, erts_mmap} or from ERTS 5.10.4; the
8104 returned list when calling with {allocator, mseg_alloc} also
8105 includes an {erts_mmap, _} tuple as one element in the list.
8106 After reading the erts_alloc(3) documentation, the returned
8108 information more or less speaks for itself, but it can be
8109 worth explaining some things. Call counts are presented by
8110 two values, the first value is giga calls, and the second
8111 value is calls. mbcs and sbcs denote multi-block carriers,
8112 and single-block carriers, respectively. Sizes are presented
8113 in bytes. When a size is not presented, it is the amount of
8114 something. Sizes and amounts are often presented by three
8115 values:
8116 * The first is the current value.
8118 * The second is the maximum value since the last call to
8120 erlang:system_info({allocator, Alloc}).
8121 * The third is the maximum value since the emulator was
8123 started.
8124 If only one value is present, it is the current value.
8126 fix_alloc memory block types are presented by two values.
8127 The first value is the memory pool size and the second value
8128 is the used memory size.
8129 alloc_util_allocators:
8131 Returns a list of the names of all allocators using the ERTS
8132 internal alloc_util framework as atoms. For more informa‐
8133 tion, see section The alloc_util framework in erts_alloc(3).
8134 {allocator_sizes, Alloc}:
8136 Returns various size information for the specified alloca‐
8137 tor. The information returned is a subset of the information
8138 returned by erlang:system_info({allocator, Alloc}).
8139 elib_malloc:
8141 This option will be removed in a future release. The return
8142 value will always be false, as the elib_malloc allocator has
8143 been removed.
8144 erlang:system_info(Item :: cpu_topology) -> CpuTopology
8146 erlang:system_info(Item ::
8148 {cpu_topology, defined | detected | used}) ->
8149 CpuTopology
8150 erlang:system_info(Item ::
8152 logical_processors |
8153 logical_processors_available |
8154 logical_processors_online) ->
8155 unknown | integer() >= 1
8156 erlang:system_info(Item :: update_cpu_info) -> changed | unchanged
8158 Types:
8160 cpu_topology() = [LevelEntry :: level_entry()] | undefined
8162 All LevelEntrys of a list must contain the same LevelTag,
8163 except on the top level where both node and processor‐
8164 LevelTags can coexist.
8165 level_entry() =
8166 {LevelTag :: level_tag(), SubLevel :: sub_level()} |
8167 {LevelTag :: level_tag(),
8168 InfoList :: info_list(),
8169 SubLevel :: sub_level()}
8170 {LevelTag, SubLevel} == {LevelTag, [], SubLevel}
8171 level_tag() = core | node | processor | thread
8172 More LevelTags can be introduced in a future release.
8173 sub_level() =
8174 [LevelEntry :: level_entry()] |
8175 (LogicalCpuId :: {logical, integer() >= 0})
8176 info_list() = []
8177 The info_list() can be extended in a future release.
8178 Returns various information about the CPU topology of the cur‐
8180 rent system (emulator) as specified by Item:
8181 cpu_topology:
8183 Returns the CpuTopology currently used by the emulator. The
8184 CPU topology is used when binding schedulers to logical pro‐
8185 cessors. The CPU topology used is the user-defined CPU
8186 topology, if such exists, otherwise the automatically
8187 detected CPU topology, if such exists. If no CPU topology
8188 exists, undefined is returned.
8189 node refers to Non-Uniform Memory Access (NUMA) nodes.
8191 thread refers to hardware threads (for example, Intel hyper-
8192 threads).
8193 A level in term CpuTopology can be omitted if only one entry
8195 exists and InfoList is empty.
8196 thread can only be a sublevel to core. core can be a sub‐
8198 level to processor or node. processor can be on the top
8199 level or a sublevel to node. node can be on the top level or
8200 a sublevel to processor. That is, NUMA nodes can be proces‐
8201 sor internal or processor external. A CPU topology can con‐
8202 sist of a mix of processor internal and external NUMA nodes,
8203 as long as each logical CPU belongs to one NUMA node. Cache
8204 hierarchy is not part of the CpuTopology type, but will be
8205 in a future release. Other things can also make it into the
8206 CPU topology in a future release. So, expect the CpuTopology
8207 type to change.
8208 {cpu_topology, defined}:
8210 Returns the user-defined CpuTopology. For more information,
8213 see command-line flag +sct in erl(1) and argument cpu_topol‐
8214 ogy.
8215 {cpu_topology, detected}:
8217 Returns the automatically detected CpuTopologyy. The emula‐
8220 tor detects the CPU topology on some newer Linux, Solaris,
8221 FreeBSD, and Windows systems. On Windows system with more
8222 than 32 logical processors, the CPU topology is not
8223 detected.
8224 For more information, see argument cpu_topology.
8226 {cpu_topology, used}:
8228 Returns CpuTopology used by the emulator. For more informa‐
8229 tion, see argument cpu_topology.
8230 logical_processors:
8232 Returns the detected number of logical processors configured
8233 in the system. The return value is either an integer, or the
8234 atom unknown if the emulator cannot detect the configured
8235 logical processors.
8236 logical_processors_available:
8238 Returns the detected number of logical processors available
8239 to the Erlang runtime system. The return value is either an
8240 integer, or the atom unknown if the emulator cannot detect
8241 the available logical processors. The number of available
8242 logical processors is less than or equal to the number of
8243 logical processors online.
8244 logical_processors_online:
8246 Returns the detected number of logical processors online on
8247 the system. The return value is either an integer, or the
8248 atom unknown if the emulator cannot detect logical proces‐
8249 sors online. The number of logical processors online is less
8250 than or equal to the number of logical processors config‐
8251 ured.
8252 cpu_quota:
8254 Returns the detected CPU quota the emulator is limited by.
8255 The return value is an integer saying how many processors'
8256 worth of runtime we get (between 1 and the number of logical
8257 processors), or the atom unknown if the emulator cannot
8258 detect a quota.
8259 update_cpu_info:
8261 The runtime system rereads the CPU information available and
8262 updates its internally stored information about the detected
8263 CPU topology and the number of logical processors config‐
8264 ured, online, available, and cpu quota.
8265 If the CPU information has changed since the last time it
8267 was read, the atom changed is returned, otherwise the atom
8268 unchanged. If the CPU information has changed, you probably
8269 want to adjust the number of schedulers online. You typi‐
8270 cally want to have as many schedulers online as logical pro‐
8271 cessors available.
8272 erlang:system_info(Item :: fullsweep_after) ->
8274 {fullsweep_after, integer() >= 0}
8275 erlang:system_info(Item :: garbage_collection) ->
8277 [{atom(), integer()}]
8278 erlang:system_info(Item :: heap_sizes) -> [integer() >= 0]
8280 erlang:system_info(Item :: heap_type) -> private
8282 erlang:system_info(Item :: max_heap_size) ->
8284 {max_heap_size,
8285 MaxHeapSize :: max_heap_size()}
8286 erlang:system_info(Item :: message_queue_data) ->
8288 message_queue_data()
8289 erlang:system_info(Item :: min_heap_size) ->
8291 {min_heap_size,
8292 MinHeapSize :: integer() >= 1}
8293 erlang:system_info(Item :: min_bin_vheap_size) ->
8295 {min_bin_vheap_size,
8296 MinBinVHeapSize :: integer() >= 1}
8297 erlang:system_info(Item :: procs) -> binary()
8299 Types:
8301 message_queue_data() = off_heap | on_heap
8303 max_heap_size() =
8304 integer() >= 0 |
8305 #{size => integer() >= 0,
8306 kill => boolean(),
8307 error_logger => boolean()}
8308 Returns information about the default process heap settings:
8310 fullsweep_after:
8312 Returns {fullsweep_after, integer() >= 0}, which is the
8313 fullsweep_after garbage collection setting used by default.
8314 For more information, see garbage_collection described
8315 below.
8316 garbage_collection:
8318 Returns a list describing the default garbage collection
8319 settings. A process spawned on the local node by a spawn or
8320 spawn_link uses these garbage collection settings. The
8321 default settings can be changed by using erlang:sys‐
8322 tem_flag/2. spawn_opt/2,3,4 can spawn a process that does
8323 not use the default settings.
8324 heap_sizes:
8326 Returns a list of integers representing valid heap sizes in
8327 words. All Erlang heaps are sized from sizes in this list.
8328 heap_type:
8330 Returns the heap type used by the current emulator. One heap
8331 type exists:
8332 private:
8334 Each process has a heap reserved for its use and no ref‐
8335 erences between heaps of different processes are allowed.
8336 Messages passed between processes are copied between
8337 heaps.
8338 max_heap_size:
8340 Returns {max_heap_size, MaxHeapSize}, where MaxHeapSize is
8341 the current system-wide maximum heap size settings for
8342 spawned processes. This setting can be set using the com‐
8343 mand-line flags +hmax, +hmaxk and +hmaxel in erl(1). It can
8344 also be changed at runtime using erlang:sys‐
8345 tem_flag(max_heap_size, MaxHeapSize). For more details about
8346 the max_heap_size process flag, see
8347 process_flag(max_heap_size, MaxHeapSize).
8348 message_queue_data:
8350 Returns the default value of the message_queue_data process
8351 flag, which can be either off_heap or on_heap. The default
8352 value is set by the command-line argument +hmqd in erl(1).
8353 For more information, see the documentation of
8354 process_flag(message_queue_data, MQD).
8355 min_heap_size:
8357 Returns {min_heap_size, MinHeapSize}, where MinHeapSize is
8358 the current system-wide minimum heap size for spawned pro‐
8359 cesses.
8360 min_bin_vheap_size:
8362 Returns {min_bin_vheap_size, MinBinVHeapSize}, where MinBin‐
8363 VHeapSize is the current system-wide minimum binary virtual
8364 heap size for spawned processes.
8365 procs:
8367 Returns a binary containing a string of process and port
8368 information formatted as in Erlang crash dumps. For more
8369 information, see section How to interpret the Erlang crash
8370 dumps in the User's Guide.
8371 erlang:system_info(Item :: atom_count) -> integer() >= 1
8373 erlang:system_info(Item :: atom_limit) -> integer() >= 1
8375 erlang:system_info(Item :: ets_count) -> integer() >= 1
8377 erlang:system_info(Item :: ets_limit) -> integer() >= 1
8379 erlang:system_info(Item :: port_count) -> integer() >= 0
8381 erlang:system_info(Item :: port_limit) -> integer() >= 1
8383 erlang:system_info(Item :: process_count) -> integer() >= 1
8385 erlang:system_info(Item :: process_limit) -> integer() >= 1
8387 Returns information about the current system (emulator) limits
8389 as specified by Item:
8390 atom_count:
8392 Returns the number of atoms currently existing at the local
8393 node. The value is given as an integer.
8394 atom_limit:
8396 Returns the maximum number of atoms allowed. This limit can
8397 be increased at startup by passing command-line flag +t to
8398 erl(1).
8399 ets_count:
8401 Returns the number of ETS tables currently existing at the
8402 local node.
8403 ets_limit:
8405 Returns the limit for number of ETS tables. This limit is
8406 partially obsolete and number of tables are only limited by
8407 available memory.
8408 port_count:
8410 Returns the number of ports currently existing at the local
8411 node. The value is given as an integer. This is the same
8412 value as returned by length(erlang:ports()), but more effi‐
8413 cient.
8414 port_limit:
8416 Returns the maximum number of simultaneously existing ports
8417 at the local node as an integer. This limit can be config‐
8418 ured at startup by using command-line flag +Q in erl(1).
8419 process_count:
8421 Returns the number of processes currently existing at the
8422 local node. The value is given as an integer. This is the
8423 same value as returned by length(processes()), but more
8424 efficient.
8425 process_limit:
8427 Returns the maximum number of simultaneously existing pro‐
8428 cesses at the local node. The value is given as an integer.
8429 This limit can be configured at startup by using command-
8430 line flag +P in erl(1).
8431 erlang:system_info(Item :: end_time) -> integer() >= 0
8433 erlang:system_info(Item :: os_monotonic_time_source) ->
8435 [{atom(), term()}]
8436 erlang:system_info(Item :: os_system_time_source) ->
8438 [{atom(), term()}]
8439 erlang:system_info(Item :: start_time) -> integer()
8441 erlang:system_info(Item :: time_correction) -> true | false
8443 erlang:system_info(Item :: time_offset) ->
8445 preliminary | final | volatile
8446 erlang:system_info(Item :: time_warp_mode) ->
8448 no_time_warp | single_time_warp |
8449 multi_time_warp
8450 erlang:system_info(Item :: tolerant_timeofday) ->
8452 enabled | disabled
8453 Returns information about the current system (emulator) time as
8455 specified by Item:
8456 end_time:
8458 The last Erlang monotonic time in native time unit that can
8459 be represented internally in the current Erlang runtime sys‐
8460 tem instance. The time between the start time and the end
8461 time is at least a quarter of a millennium.
8462 os_monotonic_time_source:
8464 Returns a list containing information about the source of OS
8465 monotonic time that is used by the runtime system.
8466 If [] is returned, no OS monotonic time is available. The
8468 list contains two-tuples with Keys as first element, and
8469 Values as second element. The order of these tuples is unde‐
8470 fined. The following tuples can be part of the list, but
8471 more tuples can be introduced in the future:
8472 {function, Function}:
8474 Function is the name of the function used. This tuple
8475 always exists if OS monotonic time is available to the
8476 runtime system.
8477 {clock_id, ClockId}:
8479 This tuple only exists if Function can be used with dif‐
8480 ferent clocks. ClockId corresponds to the clock identifier
8481 used when calling Function.
8482 {resolution, OsMonotonicTimeResolution}:
8484 Highest possible resolution of current OS monotonic time
8485 source as parts per second. If no resolution information
8486 can be retrieved from the OS, OsMonotonicTimeResolution is
8487 set to the resolution of the time unit of Functions return
8488 value. That is, the actual resolution can be lower than
8489 OsMonotonicTimeResolution. Notice that the resolution does
8490 not say anything about the accuracy or whether the pre‐
8491 cision aligns with the resolution. You do, however, know
8492 that the precision is not better than OsMonotonicTimeReso‐
8493 lution.
8494 {extended, Extended}:
8496 Extended equals yes if the range of time values has been
8497 extended; otherwise Extended equals no. The range must be
8498 extended if Function returns values that wrap fast. This
8499 typically is the case when the return value is a 32-bit
8500 value.
8501 {parallel, Parallel}:
8503 Parallel equals yes if Function is called in parallel from
8504 multiple threads. If it is not called in parallel, because
8505 calls must be serialized, Parallel equals no.
8506 {time, OsMonotonicTime}:
8508 OsMonotonicTime equals current OS monotonic time in native
8509 time unit.
8510 os_system_time_source:
8512 Returns a list containing information about the source of OS
8513 system time that is used by the runtime system.
8514 The list contains two-tuples with Keys as first element, and
8516 Values as second element. The order of these tuples is unde‐
8517 fined. The following tuples can be part of the list, but
8518 more tuples can be introduced in the future:
8519 {function, Function}:
8521 Function is the name of the funcion used.
8522 {clock_id, ClockId}:
8524 Exists only if Function can be used with different clocks.
8525 ClockId corresponds to the clock identifier used when
8526 calling Function.
8527 {resolution, OsSystemTimeResolution}:
8529 Highest possible resolution of current OS system time
8530 source as parts per second. If no resolution information
8531 can be retrieved from the OS, OsSystemTimeResolution is
8532 set to the resolution of the time unit of Functions return
8533 value. That is, the actual resolution can be lower than
8534 OsSystemTimeResolution. Notice that the resolution does
8535 not say anything about the accuracy or whether the pre‐
8536 cision do align with the resolution. You do, however, know
8537 that the precision is not better than OsSystemTimeResolu‐
8538 tion.
8539 {parallel, Parallel}:
8541 Parallel equals yes if Function is called in parallel from
8542 multiple threads. If it is not called in parallel, because
8543 calls needs to be serialized, Parallel equals no.
8544 {time, OsSystemTime}:
8546 OsSystemTime equals current OS system time in native time
8547 unit.
8548 start_time:
8550 The Erlang monotonic time in native time unit at the time
8551 when current Erlang runtime system instance started.
8552 See also erlang:system_info(end_time).
8554 time_correction:
8556 Returns a boolean value indicating whether time correction
8557 is enabled or not.
8558 time_offset:
8560 Returns the state of the time offset:
8561 preliminary:
8563 The time offset is preliminary, and will be changed and
8564 finalized later. The preliminary time offset is used dur‐
8565 ing the preliminary phase of the single time warp mode.
8566 final:
8568 The time offset is final. This either because no time
8569 warp mode is used, or because the time offset have been
8570 finalized when single time warp mode is used.
8571 volatile:
8573 The time offset is volatile. That is, it can change at any
8574 time. This is because multi-time warp mode is used.
8575 time_warp_mode:
8577 Returns a value identifying the time warp mode that is
8578 used:
8579 no_time_warp:
8581 The no time warp mode is used.
8582 single_time_warp:
8584 The single time warp mode is used.
8585 multi_time_warp:
8587 The multi-time warp mode is used.
8588 tolerant_timeofday:
8590 Returns whether a pre ERTS 7.0 backwards compatible compen‐
8591 sation for sudden changes of system time is enabled or dis‐
8592 abled. Such compensation is enabled when the time offset is
8593 final, and time correction is enabled.
8594 erlang:system_info(Item :: dirty_cpu_schedulers) ->
8596 integer() >= 0
8597 erlang:system_info(Item :: dirty_cpu_schedulers_online) ->
8599 integer() >= 0
8600 erlang:system_info(Item :: dirty_io_schedulers) ->
8602 integer() >= 0
8603 erlang:system_info(Item :: multi_scheduling) ->
8605 disabled | blocked | blocked_normal |
8606 enabled
8607 erlang:system_info(Item :: multi_scheduling_blockers) ->
8609 [Pid :: pid()]
8610 erlang:system_info(Item :: otp_release) -> string()
8612 erlang:system_info(Item :: scheduler_bind_type) ->
8614 spread | processor_spread | thread_spread |
8615 thread_no_node_processor_spread |
8616 no_node_processor_spread |
8617 no_node_thread_spread | no_spread | unbound
8618 erlang:system_info(Item :: scheduler_bindings) -> tuple()
8620 erlang:system_info(Item :: scheduler_id) ->
8622 SchedulerId :: integer() >= 1
8623 erlang:system_info(Item :: schedulers | schedulers_online) ->
8625 integer() >= 1
8626 erlang:system_info(Item :: smp_support) -> boolean()
8628 erlang:system_info(Item :: threads) -> boolean()
8630 erlang:system_info(Item :: thread_pool_size) -> integer() >= 0
8632 Returns information about schedulers, scheduling and threads in
8634 the current system as specified by Item:
8635 dirty_cpu_schedulers:
8637 Returns the number of dirty CPU scheduler threads used by
8638 the emulator. Dirty CPU schedulers execute CPU-bound native
8639 functions, such as NIFs, linked-in driver code, and BIFs
8640 that cannot be managed cleanly by the normal emulator sched‐
8641 ulers.
8642 The number of dirty CPU scheduler threads is determined at
8644 emulator boot time and cannot be changed after that. How‐
8645 ever, the number of dirty CPU scheduler threads online can
8646 be changed at any time. The number of dirty CPU schedulers
8647 can be set at startup by passing command-line flag +SDcpu or
8648 +SDPcpu in erl(1).
8649 See also erlang:system_flag(dirty_cpu_schedulers_online,
8651 DirtyCPUSchedulersOnline), erlang:sys‐
8652 tem_info(dirty_cpu_schedulers_online), erlang:sys‐
8653 tem_info(dirty_io_schedulers), erlang:system_info(sched‐
8654 ulers), erlang:system_info(schedulers_online), and
8655 erlang:system_flag(schedulers_online, SchedulersOnline).
8656 dirty_cpu_schedulers_online:
8658 Returns the number of dirty CPU schedulers online. The
8659 return value satisfies 1 <= DirtyCPUSchedulersOnline <= N,
8660 where N is the smallest of the return values of erlang:sys‐
8661 tem_info(dirty_cpu_schedulers) and erlang:system_info(sched‐
8662 ulers_online).
8663 The number of dirty CPU schedulers online can be set at
8665 startup by passing command-line flag +SDcpu in erl(1).
8666 For more information, see erlang:sys‐
8668 tem_info(dirty_cpu_schedulers), erlang:sys‐
8669 tem_info(dirty_io_schedulers), erlang:system_info(sched‐
8670 ulers_online), and erlang:system_flag(dirty_cpu_sched‐
8671 ulers_online, DirtyCPUSchedulersOnline).
8672 dirty_io_schedulers:
8674 Returns the number of dirty I/O schedulers as an integer.
8675 Dirty I/O schedulers execute I/O-bound native functions,
8676 such as NIFs and linked-in driver code, which cannot be man‐
8677 aged cleanly by the normal emulator schedulers.
8678 This value can be set at startup by passing command-line
8680 argument +SDio in erl(1).
8681 For more information, see erlang:sys‐
8683 tem_info(dirty_cpu_schedulers), erlang:sys‐
8684 tem_info(dirty_cpu_schedulers_online), and erlang:sys‐
8685 tem_flag(dirty_cpu_schedulers_online, DirtyCPUSchedulersOn‐
8686 line).
8687 multi_scheduling:
8689 Returns one of the following:
8690 disabled:
8692 The emulator has been started with only one scheduler
8693 thread.
8694 blocked:
8696 The emulator has more than one scheduler thread, but all
8697 scheduler threads except one are blocked. That is, only
8698 one scheduler thread schedules Erlang processes and exe‐
8699 cutes Erlang code.
8700 blocked_normal:
8702 The emulator has more than one scheduler thread, but all
8703 normal scheduler threads except one are blocked. Notice
8704 that dirty schedulers are not blocked, and can schedule
8705 Erlang processes and execute native code.
8706 enabled:
8708 The emulator has more than one scheduler thread, and no
8709 scheduler threads are blocked. That is, all available
8710 scheduler threads schedule Erlang processes and execute
8711 Erlang code.
8712 See also erlang:system_flag(multi_scheduling, BlockState),
8714 erlang:system_info(multi_scheduling_blockers), erlang:sys‐
8715 tem_info(normal_multi_scheduling_blockers), and erlang:sys‐
8716 tem_info(schedulers).
8717 multi_scheduling_blockers:
8719 Returns a list of Pids when multi-scheduling is blocked,
8720 otherwise the empty list is returned. The Pids in the list
8721 represent all the processes currently blocking multi-sched‐
8722 uling. A Pid occurs only once in the list, even if the cor‐
8723 responding process has blocked multiple times.
8724 See also erlang:system_flag(multi_scheduling, BlockState),
8726 erlang:system_info(multi_scheduling), erlang:sys‐
8727 tem_info(normal_multi_scheduling_blockers), and erlang:sys‐
8728 tem_info(schedulers).
8729 normal_multi_scheduling_blockers:
8731 Returns a list of Pids when normal multi-scheduling is
8732 blocked (that is, all normal schedulers but one is blocked),
8733 otherwise the empty list is returned. The Pids in the list
8734 represent all the processes currently blocking normal multi-
8735 scheduling. A Pid occurs only once in the list, even if the
8736 corresponding process has blocked multiple times.
8737 See also erlang:system_flag(multi_scheduling, BlockState),
8739 erlang:system_info(multi_scheduling), erlang:sys‐
8740 tem_info(multi_scheduling_blockers), and erlang:sys‐
8741 tem_info(schedulers).
8742 scheduler_bind_type:
8744 Returns information about how the user has requested sched‐
8745 ulers to be bound or not bound.
8746 Notice that although a user has requested schedulers to be
8748 bound, they can silently have failed to bind. To inspect the
8749 scheduler bindings, call erlang:system_info(scheduler_bind‐
8750 ings).
8751 For more information, see command-line argument +sbt in
8753 erl(1) and erlang:system_info(scheduler_bindings).
8754 scheduler_bindings:
8756 Returns information about the currently used scheduler bind‐
8757 ings.
8758 A tuple of a size equal to erlang:system_info(schedulers) is
8760 returned. The tuple elements are integers or the atom
8761 unbound. Logical processor identifiers are represented as
8762 integers. The Nth element of the tuple equals the current
8763 binding for the scheduler with the scheduler identifier
8764 equal to N. For example, if the schedulers are bound, ele‐
8765 ment(erlang:system_info(scheduler_id), erlang:sys‐
8766 tem_info(scheduler_bindings)) returns the identifier of the
8767 logical processor that the calling process is executing on.
8768 Notice that only schedulers online can be bound to logical
8770 processors.
8771 For more information, see command-line argument +sbt in
8773 erl(1) and erlang:system_info(schedulers_online).
8774 scheduler_id:
8776 Returns the scheduler ID (SchedulerId) of the scheduler
8777 thread that the calling process is executing on. SchedulerId
8778 is a positive integer, where 1 <= SchedulerId <= erlang:sys‐
8779 tem_info(schedulers).
8780 See also erlang:system_info(schedulers).
8782 schedulers:
8784 Returns the number of scheduler threads used by the emula‐
8785 tor. Scheduler threads online schedules Erlang processes and
8786 Erlang ports, and execute Erlang code and Erlang linked-in
8787 driver code.
8788 The number of scheduler threads is determined at emulator
8790 boot time and cannot be changed later. However, the number
8791 of schedulers online can be changed at any time.
8792 See also erlang:system_flag(schedulers_online, SchedulersOn‐
8794 line), erlang:system_info(schedulers_online), erlang:sys‐
8795 tem_info(scheduler_id), erlang:system_flag(multi_scheduling,
8796 BlockState), erlang:system_info(multi_scheduling),
8797 erlang:system_info(normal_multi_scheduling_blockers) and
8798 erlang:system_info(multi_scheduling_blockers).
8799 schedulers_online:
8801 Returns the number of schedulers online. The scheduler iden‐
8802 tifiers of schedulers online satisfy the relationship 1 <=
8803 SchedulerId <= erlang:system_info(schedulers_online).
8804 For more information, see erlang:system_info(schedulers) and
8806 erlang:system_flag(schedulers_online, SchedulersOnline).
8807 smp_support:
8809 Returns true.
8810 threads:
8812 Returns true.
8813 thread_pool_size:
8815 Returns the number of async threads in the async thread pool
8818 used for asynchronous driver calls
8819 (erl_driver:driver_async()). The value is given as an inte‐
8820 ger.
8821 erlang:system_info(Item :: creation) -> integer()
8823 erlang:system_info(Item :: delayed_node_table_gc) ->
8825 infinity | integer() >= 0
8826 erlang:system_info(Item :: dist) -> binary()
8828 erlang:system_info(Item :: dist_buf_busy_limit) ->
8830 integer() >= 0
8831 erlang:system_info(Item :: dist_ctrl) ->
8833 {Node :: node(),
8834 ControllingEntity :: port() | pid()}
8835 Returns information about Erlang Distribution in the current
8837 system as specified by Item:
8838 creation:
8840 Returns the creation of the local node as an integer. The
8841 creation is changed when a node is restarted. The creation
8842 of a node is stored in process identifiers, port identi‐
8843 fiers, and references. This makes it (to some extent) possi‐
8844 ble to distinguish between identifiers from different incar‐
8845 nations of a node. The valid creations are integers in the
8846 range 1..3, but this will probably change in a future
8847 release. If the node is not alive, 0 is returned.
8848 delayed_node_table_gc:
8850 Returns the amount of time in seconds garbage collection of
8851 an entry in a node table is delayed. This limit can be set
8852 on startup by passing command-line flag +zdntgc to erl(1).
8853 For more information, see the documentation of the command-
8854 line flag.
8855 dist:
8857 Returns a binary containing a string of distribution infor‐
8858 mation formatted as in Erlang crash dumps. For more informa‐
8859 tion, see section How to interpret the Erlang crash dumps
8860 in the User's Guide.
8861 dist_buf_busy_limit:
8863 Returns the value of the distribution buffer busy limit in
8864 bytes. This limit can be set at startup by passing command-
8865 line flag +zdbbl to erl(1).
8866 dist_ctrl:
8868 Returns a list of tuples {Node, ControllingEntity}, one
8869 entry for each connected remote node. Node is the node name
8870 and ControllingEntity is the port or process identifier
8871 responsible for the communication to that node. More specif‐
8872 ically, ControllingEntity for nodes connected through TCP/IP
8873 (the normal case) is the socket used in communication with
8874 the specific node.
8875 erlang:system_info(Item :: build_type) ->
8877 opt | debug | purify | quantify | purecov |
8878 gcov | valgrind | gprof | lcnt | frmptr
8879 erlang:system_info(Item :: c_compiler_used) -> {atom(), term()}
8881 erlang:system_info(Item :: check_io) -> [term()]
8883 erlang:system_info(Item :: compat_rel) -> integer()
8885 erlang:system_info(Item :: debug_compiled) -> boolean()
8887 erlang:system_info(Item :: driver_version) -> string()
8889 erlang:system_info(Item :: dynamic_trace) ->
8891 none | dtrace | systemtap
8892 erlang:system_info(Item :: dynamic_trace_probes) -> boolean()
8894 erlang:system_info(Item :: info) -> binary()
8896 erlang:system_info(Item :: kernel_poll) -> boolean()
8898 erlang:system_info(Item :: loaded) -> binary()
8900 erlang:system_info(Item :: machine) -> string()
8902 erlang:system_info(Item :: modified_timing_level) ->
8904 integer() | undefined
8905 erlang:system_info(Item :: nif_version) -> string()
8907 erlang:system_info(Item :: otp_release) -> string()
8909 erlang:system_info(Item :: port_parallelism) -> boolean()
8911 erlang:system_info(Item :: system_architecture) -> string()
8913 erlang:system_info(Item :: system_logger) ->
8915 logger | undefined | pid()
8916 erlang:system_info(Item :: system_version) -> string()
8918 erlang:system_info(Item :: trace_control_word) ->
8920 integer() >= 0
8921 erlang:system_info(Item :: version) -> string()
8923 erlang:system_info(Item ::
8925 wordsize |
8926 {wordsize, internal} |
8927 {wordsize, external}) ->
8928 4 | 8
8929 Returns various information about the current system (emulator)
8931 as specified by Item:
8932 build_type:
8934 Returns an atom describing the build type of the runtime
8935 system. This is normally the atom opt for optimized. Other
8936 possible return values are debug, purify, quantify, purecov,
8937 gcov, valgrind, gprof, and lcnt. Possible return values can
8938 be added or removed at any time without prior notice.
8939 c_compiler_used:
8941 Returns a two-tuple describing the C compiler used when com‐
8942 piling the runtime system. The first element is an atom
8943 describing the name of the compiler, or undefined if
8944 unknown. The second element is a term describing the version
8945 of the compiler, or undefined if unknown.
8946 check_io:
8948 Returns a list containing miscellaneous information about
8949 the emulators internal I/O checking. Notice that the content
8950 of the returned list can vary between platforms and over
8951 time. It is only guaranteed that a list is returned.
8952 compat_rel:
8954 Returns the compatibility mode of the local node as an inte‐
8955 ger. The integer returned represents the Erlang/OTP release
8956 that the current emulator has been set to be backward com‐
8957 patible with. The compatibility mode can be configured at
8958 startup by using command-line flag +R in erl(1).
8959 debug_compiled:
8961 Returns true if the emulator has been debug-compiled, other‐
8962 wise false.
8963 driver_version:
8965 Returns a string containing the Erlang driver version used
8966 by the runtime system. It has the form "<major ver>.<minor
8967 ver>".
8968 dynamic_trace:
8970 Returns an atom describing the dynamic trace framework com‐
8971 piled into the virtual machine. It can be dtrace, systemtap,
8972 or none. For a commercial or standard build, it is always
8973 none. The other return values indicate a custom configura‐
8974 tion (for example, ./configure --with-dynamic-trace=dtrace).
8975 For more information about dynamic tracing, see dyntrace(3)
8976 manual page and the README.dtrace/README.systemtap files in
8977 the Erlang source code top directory.
8978 dynamic_trace_probes:
8980 Returns a boolean() indicating if dynamic trace probes
8981 (dtrace or systemtap) are built into the emulator. This can
8982 only be true if the virtual machine was built for dynamic
8983 tracing (that is, system_info(dynamic_trace) returns dtrace
8984 or systemtap).
8985 info:
8987 Returns a binary containing a string of miscellaneous system
8988 information formatted as in Erlang crash dumps. For more
8989 information, see section How to interpret the Erlang crash
8990 dumps in the User's Guide.
8991 kernel_poll:
8993 Returns true if the emulator uses some kind of kernel-poll
8994 implementation, otherwise false.
8995 loaded:
8997 Returns a binary containing a string of loaded module infor‐
8998 mation formatted as in Erlang crash dumps. For more informa‐
8999 tion, see section How to interpret the Erlang crash dumps in
9000 the User's Guide.
9001 machine:
9003 Returns a string containing the Erlang machine name.
9004 modified_timing_level:
9006 Returns the modified timing-level (an integer) if modified
9007 timing is enabled, otherwise undefined. For more information
9008 about modified timing, see command-line flag +T in erl(1)
9009 nif_version:
9011 Returns a string containing the version of the Erlang NIF
9012 interface used by the runtime system. It is on the form
9013 "<major ver>.<minor ver>".
9014 otp_release:
9016 Returns a string containing the OTP release number of the
9019 OTP release that the currently executing ERTS application is
9020 part of.
9021 As from Erlang/OTP 17, the OTP release number corresponds to
9023 the major OTP version number. No erlang:system_info() argu‐
9024 ment gives the exact OTP version. This is because the exact
9025 OTP version in the general case is difficult to determine.
9026 For more information, see the description of versions in
9027 System principles in System Documentation.
9028 port_parallelism:
9030 Returns the default port parallelism scheduling hint used.
9031 For more information, see command-line argument +spp in
9032 erl(1).
9033 system_architecture:
9035 Returns a string containing the processor and OS architec‐
9036 ture the emulator is built for.
9037 system_logger:
9039 Returns the current system_logger as set by erlang:sys‐
9040 tem_flag(system_logger, _).
9041 system_version:
9043 Returns a string containing version number and some impor‐
9044 tant properties, such as the number of schedulers.
9045 trace_control_word:
9047 Returns the value of the node trace control word. For more
9048 information, see function get_tcw in section Match Specifi‐
9049 cations in Erlang in the User's Guide.
9050 version:
9052 Returns a string containing the version number of the emula‐
9053 tor.
9054 wordsize:
9056 Same as {wordsize, internal}.
9057 {wordsize, internal}:
9059 Returns the size of Erlang term words in bytes as an inte‐
9060 ger, that is, 4 is returned on a 32-bit architecture, and 8
9061 is returned on a pure 64-bit architecture. On a halfword
9062 64-bit emulator, 4 is returned, as the Erlang terms are
9063 stored using a virtual word size of half the system word
9064 size.
9065 {wordsize, external}:
9067 Returns the true word size of the emulator, that is, the
9068 size of a pointer. The value is given in bytes as an inte‐
9069 ger. On a pure 32-bit architecture, 4 is returned. On both a
9070 half word and on a pure 64-bit architecture, 8 is returned.
9071 erlang:system_monitor() -> MonSettings
9073 Types:
9075 MonSettings = undefined | {MonitorPid, Options}
9077 MonitorPid = pid()
9078 Options = [system_monitor_option()]
9079 system_monitor_option() =
9080 busy_port | busy_dist_port |
9081 {long_gc, integer() >= 0} |
9082 {long_schedule, integer() >= 0} |
9083 {large_heap, integer() >= 0}
9084 Returns the current system monitoring settings set by
9086 erlang:system_monitor/2 as {MonitorPid, Options}, or undefined
9087 if no settings exist. The order of the options can be different
9088 from the one that was set.
9089 erlang:system_monitor(Arg) -> MonSettings
9091 Types:
9093 Arg = MonSettings = undefined | {MonitorPid, Options}
9095 MonitorPid = pid()
9096 Options = [system_monitor_option()]
9097 system_monitor_option() =
9098 busy_port | busy_dist_port |
9099 {long_gc, integer() >= 0} |
9100 {long_schedule, integer() >= 0} |
9101 {large_heap, integer() >= 0}
9102 When called with argument undefined, all system performance mon‐
9104 itoring settings are cleared.
9105 Calling the function with {MonitorPid, Options} as argument is
9107 the same as calling erlang:system_monitor(MonitorPid, Options).
9108 Returns the previous system monitor settings just like
9110 erlang:system_monitor/0.
9111 erlang:system_monitor(MonitorPid, Options) -> MonSettings
9113 Types:
9115 MonitorPid = pid()
9117 Options = [system_monitor_option()]
9118 MonSettings = undefined | {OldMonitorPid, OldOptions}
9119 OldMonitorPid = pid()
9120 OldOptions = [system_monitor_option()]
9121 system_monitor_option() =
9122 busy_port | busy_dist_port |
9123 {long_gc, integer() >= 0} |
9124 {long_schedule, integer() >= 0} |
9125 {large_heap, integer() >= 0}
9126 Sets the system performance monitoring options. MonitorPid is a
9128 local process identifier (pid) receiving system monitor mes‐
9129 sages. The second argument is a list of monitoring options:
9130 {long_gc, Time}:
9132 If a garbage collection in the system takes at least Time
9133 wall clock milliseconds, a message {monitor, GcPid, long_gc,
9134 Info} is sent to MonitorPid. GcPid is the pid that was
9135 garbage collected. Info is a list of two-element tuples
9136 describing the result of the garbage collection.
9137 One of the tuples is {timeout, GcTime}, where GcTime is the
9139 time for the garbage collection in milliseconds. The other
9140 tuples are tagged with heap_size, heap_block_size,
9141 stack_size, mbuf_size, old_heap_size, and
9142 old_heap_block_size. These tuples are explained in the
9143 description of trace message gc_minor_start (see
9144 erlang:trace/3). New tuples can be added, and the order of
9145 the tuples in the Info list can be changed at any time with‐
9146 out prior notice.
9147 {long_schedule, Time}:
9149 If a process or port in the system runs uninterrupted for at
9150 least Time wall clock milliseconds, a message {monitor,
9151 PidOrPort, long_schedule, Info} is sent to MonitorPid.
9152 PidOrPort is the process or port that was running. Info is a
9153 list of two-element tuples describing the event.
9154 If a pid(), the tuples {timeout, Millis}, {in, Location},
9156 and {out, Location} are present, where Location is either an
9157 MFA ({Module, Function, Arity}) describing the function
9158 where the process was scheduled in/out, or the atom unde‐
9159 fined.
9160 If a port(), the tuples {timeout, Millis} and {port_op,Op}
9162 are present. Op is one of proc_sig, timeout, input, output,
9163 event, or dist_cmd, depending on which driver callback was
9164 executing.
9165 proc_sig is an internal operation and is never to appear,
9167 while the others represent the corresponding driver call‐
9168 backs timeout, ready_input, ready_output, event, and outputv
9169 (when the port is used by distribution). Value Millis in
9170 tuple timeout informs about the uninterrupted execution time
9171 of the process or port, which always is equal to or higher
9172 than the Time value supplied when starting the trace. New
9173 tuples can be added to the Info list in a future release.
9174 The order of the tuples in the list can be changed at any
9175 time without prior notice.
9176 This can be used to detect problems with NIFs or drivers
9178 that take too long to execute. 1 ms is considered a good
9179 maximum time for a driver callback or a NIF. However, a
9180 time-sharing system is usually to consider everything < 100
9181 ms as "possible" and fairly "normal". However, longer sched‐
9182 ule times can indicate swapping or a misbehaving NIF/driver.
9183 Misbehaving NIFs and drivers can cause bad resource utiliza‐
9184 tion and bad overall system performance.
9185 {large_heap, Size}:
9187 If a garbage collection in the system results in the allo‐
9188 cated size of a heap being at least Size words, a message
9189 {monitor, GcPid, large_heap, Info} is sent to MonitorPid.
9190 GcPid and Info are the same as for long_gc earlier, except
9191 that the tuple tagged with timeout is not present.
9192 The monitor message is sent if the sum of the sizes of all
9194 memory blocks allocated for all heap generations after a
9195 garbage collection is equal to or higher than Size.
9196 When a process is killed by max_heap_size, it is killed
9198 before the garbage collection is complete and thus no large
9199 heap message is sent.
9200 busy_port:
9202 If a process in the system gets suspended because it sends
9203 to a busy port, a message {monitor, SusPid, busy_port, Port}
9204 is sent to MonitorPid. SusPid is the pid that got suspended
9205 when sending to Port.
9206 busy_dist_port:
9208 If a process in the system gets suspended because it sends
9209 to a process on a remote node whose inter-node communication
9210 was handled by a busy port, a message {monitor, SusPid,
9211 busy_dist_port, Port} is sent to MonitorPid. SusPid is the
9212 pid that got suspended when sending through the inter-node
9213 communication port Port.
9214 Returns the previous system monitor settings just like
9216 erlang:system_monitor/0.
9217 The arguments to system_monitor/2 specifies how all system moni‐
9219 toring on the node should be done, not how it should be changed.
9220 This means only one process at a time (MonitorPid) can be the
9221 receiver of system monitor messages. Also, the way to clear a
9222 specific monitor option is to not include it in the list
9223 Options. All system monitoring will, however, be cleared if the
9224 process identified by MonitorPid terminates.
9225 There are no special option values (like zero) to clear an
9227 option. Some of the options have a unspecified minimum value.
9228 Lower values will be adjusted to the minimum value. For example,
9229 it is currently not possible to monitor all garbage collections
9230 with {long_gc, 0}.
9231 Note:
9233 If a monitoring process gets so large that it itself starts to
9234 cause system monitor messages when garbage collecting, the mes‐
9235 sages enlarge the process message queue and probably make the
9236 problem worse.
9237 Keep the monitoring process neat and do not set the system moni‐
9239 tor limits too tight.
9240 Failures:
9243 badarg:
9245 If MonitorPid does not exist.
9246 badarg:
9248 If MonitorPid is not a local process.
9249 erlang:system_profile() -> ProfilerSettings
9251 Types:
9253 ProfilerSettings = undefined | {ProfilerPid, Options}
9255 ProfilerPid = pid() | port()
9256 Options = [system_profile_option()]
9257 system_profile_option() =
9258 exclusive | runnable_ports | runnable_procs | scheduler |
9259 timestamp | monotonic_timestamp | strict_monotonic_timestamp
9260 Returns the current system profiling settings set by erlang:sys‐
9262 tem_profile/2 as {ProfilerPid, Options}, or undefined if there
9263 are no settings. The order of the options can be different from
9264 the one that was set.
9265 erlang:system_profile(ProfilerPid, Options) -> ProfilerSettings
9267 Types:
9269 ProfilerPid = pid() | port() | undefined
9271 Options = [system_profile_option()]
9272 ProfilerSettings =
9273 undefined | {pid() | port(), [system_profile_option()]}
9274 system_profile_option() =
9275 exclusive | runnable_ports | runnable_procs | scheduler |
9276 timestamp | monotonic_timestamp | strict_monotonic_timestamp
9277 Sets system profiler options. ProfilerPid is a local process
9279 identifier (pid) or port receiving profiling messages. The
9280 receiver is excluded from all profiling. The second argument is
9281 a list of profiling options:
9282 exclusive:
9284 If a synchronous call to a port from a process is done, the
9285 calling process is considered not runnable during the call
9286 runtime to the port. The calling process is notified as
9287 inactive, and later active when the port callback returns.
9288 monotonic_timestamp:
9290 Time stamps in profile messages use Erlang monotonic time.
9291 The time stamp (Ts) has the same format and value as pro‐
9292 duced by erlang:monotonic_time(nanosecond).
9293 runnable_procs:
9295 If a process is put into or removed from the run queue, a
9296 message, {profile, Pid, State, Mfa, Ts}, is sent to Profil‐
9297 erPid. Running processes that are reinserted into the run
9298 queue after having been pre-empted do not trigger this mes‐
9299 sage.
9300 runnable_ports:
9302 If a port is put into or removed from the run queue, a mes‐
9303 sage, {profile, Port, State, 0, Ts}, is sent to ProfilerPid.
9304 scheduler:
9306 If a scheduler is put to sleep or awoken, a message, {pro‐
9307 file, scheduler, Id, State, NoScheds, Ts}, is sent to Pro‐
9308 filerPid.
9309 strict_monotonic_timestamp:
9311 Time stamps in profile messages consist of Erlang monotonic
9312 time and a monotonically increasing integer. The time stamp
9313 (Ts) has the same format and value as produced by
9314 {erlang:monotonic_time(nanosecond), erlang:unique_inte‐
9315 ger([monotonic])}.
9316 timestamp:
9318 Time stamps in profile messages include a time stamp (Ts)
9319 that has the same form as returned by erlang:now(). This is
9320 also the default if no time stamp flag is specified. If
9321 cpu_timestamp has been enabled through erlang:trace/3, this
9322 also effects the time stamp produced in profiling messages
9323 when flag timestamp is enabled.
9324 Note:
9326 erlang:system_profile behavior can change in a future release.
9327 erlang:system_time() -> integer()
9330 Returns current Erlang system time in native time unit.
9332 Calling erlang:system_time() is equivalent to erlang:mono‐
9334 tonic_time() + erlang:time_offset().
9335 Note:
9337 This time is not a monotonically increasing time in the general
9338 case. For more information, see the documentation of time warp
9339 modes in the User's Guide.
9340 erlang:system_time(Unit) -> integer()
9343 Types:
9345 Unit = time_unit()
9347 Returns current Erlang system time converted into the Unit
9349 passed as argument.
9350 Calling erlang:system_time(Unit) is equivalent to erlang:con‐
9352 vert_time_unit(erlang:system_time(), native, Unit).
9353 Note:
9355 This time is not a monotonically increasing time in the general
9356 case. For more information, see the documentation of time warp
9357 modes in the User's Guide.
9358 term_to_binary(Term) -> ext_binary()
9361 Types:
9363 Term = term()
9365 Returns a binary data object that is the result of encoding Term
9367 according to the Erlang external term format.
9368 This can be used for various purposes, for example, writing a
9370 term to a file in an efficient way, or sending an Erlang term to
9371 some type of communications channel not supported by distributed
9372 Erlang.
9373 > Bin = term_to_binary(hello).
9375 <<131,100,0,5,104,101,108,108,111>>
9376 > hello = binary_to_term(Bin).
9377 hello
9378 See also binary_to_term/1.
9381 Note:
9383 There is no guarantee that this function will return the same
9384 encoded representation for the same term.
9385 term_to_binary(Term, Options) -> ext_binary()
9388 Types:
9390 Term = term()
9392 Options =
9393 [compressed |
9394 {compressed, Level :: 0..9} |
9395 {minor_version, Version :: 0..2}]
9396 Returns a binary data object that is the result of encoding Term
9398 according to the Erlang external term format.
9399 If option compressed is provided, the external term format is
9401 compressed. The compressed format is automatically recognized by
9402 binary_to_term/1 as from Erlang/OTP R7B.
9403 A compression level can be specified by giving option {com‐
9405 pressed, Level}. Level is an integer with range 0..9, where:
9406 * 0 - No compression is done (it is the same as giving no com‐
9408 pressed option).
9409 * 1 - Takes least time but may not compress as well as the
9411 higher levels.
9412 * 6 - Default level when option compressed is provided.
9414 * 9 - Takes most time and tries to produce a smaller result.
9416 Notice "tries" in the preceding sentence; depending on the
9417 input term, level 9 compression either does or does not pro‐
9418 duce a smaller result than level 1 compression.
9419 Option {minor_version, Version} can be used to control some
9421 encoding details. This option was introduced in Erlang/OTP
9422 R11B-4. The valid values for Version are:
9423 0:
9425 Floats are encoded using a textual representation. This
9426 option is useful to ensure that releases before Erlang/OTP
9427 R11B-4 can decode resulting binary.
9428 This version encode atoms that can be represented by a
9430 latin1 string using latin1 encoding while only atoms that
9431 cannot be represented by latin1 are encoded using utf8.
9432 1:
9434 This is as of Erlang/OTP 17.0 the default. It forces any
9435 floats in the term to be encoded in a more space-efficient
9436 and exact way (namely in the 64-bit IEEE format, rather than
9437 converted to a textual representation). As from Erlang/OTP
9438 R11B-4, binary_to_term/1 can decode this representation.
9439 This version encode atoms that can be represented by a
9441 latin1 string using latin1 encoding while only atoms that
9442 cannot be represented by latin1 are encoded using utf8.
9443 2:
9445 Drops usage of the latin1 atom encoding and unconditionally
9446 use utf8 encoding for all atoms. This will be changed to the
9447 default in a future major release of Erlang/OTP. Erlang/OTP
9448 systems as of R16B can decode this representation.
9449 See also binary_to_term/1.
9451 term_to_iovec(Term) -> ext_iovec()
9453 Types:
9455 Term = term()
9457 Returns the encoding of Term according to the Erlang external
9459 term format as ext_iovec().
9460 This function produce the same encoding as term_to_binary/1, but
9462 with another return type. The call
9463 iolist_to_binary(term_to_iovec(Term)) will produce exactly the
9464 same result as the call term_to_binary(Term).
9465 term_to_iovec() is a pure optimization of the functionality
9467 term_to_binary() provide. term_to_iovec() can for example refer
9468 directly to off heap binaries instead of copying the binary data
9469 into the result.
9470 See also term_to_binary/1.
9472 term_to_iovec(Term, Options) -> ext_iovec()
9474 Types:
9476 Term = term()
9478 Options =
9479 [compressed |
9480 {compressed, Level :: 0..9} |
9481 {minor_version, Version :: 0..2}]
9482 Returns the encoding of Term according to the Erlang external
9484 term format as ext_iovec().
9485 This function produce the same encoding as term_to_binary/2, but
9487 with another return type. The call
9488 iolist_to_binary(term_to_iovec(Term, Opts)) will produce exactly
9489 the same result as term_to_binary(Term, Opts).
9490 Currently recognised options are all options recognised by
9492 term_to_binary/2.
9493 term_to_iovec() is a pure optimization of the functionality
9495 term_to_binary() provide. term_to_iovec() can for example refer
9496 directly to off heap binaries instead of copying the binary data
9497 into the result.
9498 See also term_to_binary/2.
9500 throw(Any) -> no_return()
9502 Types:
9504 Any = term()
9506 A non-local return from a function. If evaluated within a catch,
9508 catch returns value Any. Example:
9509 > catch throw({hello, there}).
9511 {hello,there}
9512 Failure: nocatch if not evaluated within a catch.
9514 time() -> Time
9516 Types:
9518 Time = calendar:time()
9520 Returns the current time as {Hour, Minute, Second}.
9522 The time zone and Daylight Saving Time correction depend on the
9524 underlying OS. Example:
9525 > time().
9527 {9,42,44}
9528 erlang:time_offset() -> integer()
9530 Returns the current time offset between Erlang monotonic time
9532 and Erlang system time in native time unit. Current time offset
9533 added to an Erlang monotonic time gives corresponding Erlang
9534 system time.
9535 The time offset may or may not change during operation depending
9537 on the time warp mode used.
9538 Note:
9540 A change in time offset can be observed at slightly different
9541 points in time by different processes.
9542 If the runtime system is in multi-time warp mode, the time off‐
9544 set is changed when the runtime system detects that the OS sys‐
9545 tem time has changed. The runtime system will, however, not
9546 detect this immediately when it occurs. A task checking the time
9547 offset is scheduled to execute at least once a minute; so, under
9548 normal operation this is to be detected within a minute, but
9549 during heavy load it can take longer time.
9550 erlang:time_offset(Unit) -> integer()
9553 Types:
9555 Unit = time_unit()
9557 Returns the current time offset between Erlang monotonic time
9559 and Erlang system time converted into the Unit passed as argu‐
9560 ment.
9561 Same as calling erlang:convert_time_unit(erlang:time_offset(),
9563 native, Unit) however optimized for commonly used Units.
9564 erlang:timestamp() -> Timestamp
9566 Types:
9568 Timestamp = timestamp()
9570 timestamp() =
9571 {MegaSecs :: integer() >= 0,
9572 Secs :: integer() >= 0,
9573 MicroSecs :: integer() >= 0}
9574 Returns current Erlang system time on the format {MegaSecs,
9576 Secs, MicroSecs}. This format is the same as os:timestamp/0 and
9577 the deprecated erlang:now/0 use. The reason for the existence of
9578 erlang:timestamp() is purely to simplify use for existing code
9579 that assumes this time stamp format. Current Erlang system time
9580 can more efficiently be retrieved in the time unit of your
9581 choice using erlang:system_time/1.
9582 The erlang:timestamp() BIF is equivalent to:
9584 timestamp() ->
9586 ErlangSystemTime = erlang:system_time(microsecond),
9587 MegaSecs = ErlangSystemTime div 1000_000_000_000,
9588 Secs = ErlangSystemTime div 1000_000 - MegaSecs*1000_000,
9589 MicroSecs = ErlangSystemTime rem 1000_000,
9590 {MegaSecs, Secs, MicroSecs}.
9591 It, however, uses a native implementation that does not build
9593 garbage on the heap and with slightly better performance.
9594 Note:
9596 This time is not a monotonically increasing time in the general
9597 case. For more information, see the documentation of time warp
9598 modes in the User's Guide.
9599 tl(List) -> term()
9602 Types:
9604 List = [term(), ...]
9606 Returns the tail of List, that is, the list minus the first ele‐
9608 ment, for example:
9609 > tl([geesties, guilies, beasties]).
9611 [guilies, beasties]
9612 Allowed in guard tests.
9614 Failure: badarg if List is the empty list [].
9616 erlang:trace(PidPortSpec, How, FlagList) -> integer()
9618 Types:
9620 PidPortSpec =
9622 pid() |
9623 port() |
9624 all | processes | ports | existing | existing_processes |
9625 existing_ports | new | new_processes | new_ports
9626 How = boolean()
9627 FlagList = [trace_flag()]
9628 trace_flag() =
9629 all | send | 'receive' | procs | ports | call | arity |
9630 return_to | silent | running | exiting | running_procs |
9631 running_ports | garbage_collection | timestamp |
9632 cpu_timestamp | monotonic_timestamp |
9633 strict_monotonic_timestamp | set_on_spawn |
9634 set_on_first_spawn | set_on_link | set_on_first_link |
9635 {tracer, pid() | port()} |
9636 {tracer, module(), term()}
9637 Turns on (if How == true) or off (if How == false) the trace
9639 flags in FlagList for the process or processes represented by
9640 PidPortSpec.
9641 PidPortSpec is either a process identifier (pid) for a local
9643 process, a port identifier, or one of the following atoms:
9644 all:
9646 All currently existing processes and ports and all that will
9647 be created in the future.
9648 processes:
9650 All currently existing processes and all that will be cre‐
9651 ated in the future.
9652 ports:
9654 All currently existing ports and all that will be created in
9655 the future.
9656 existing:
9658 All currently existing processes and ports.
9659 existing_processes:
9661 All currently existing processes.
9662 existing_ports:
9664 All currently existing ports.
9665 new:
9667 All processes and ports that will be created in the future.
9668 new_processes:
9670 All processes that will be created in the future.
9671 new_ports:
9673 All ports that will be created in the future.
9674 FlagList can contain any number of the following flags (the
9676 "message tags" refers to the list of trace messages):
9677 all:
9679 Sets all trace flags except tracer and cpu_timestamp, which
9680 are in their nature different than the others.
9681 send:
9683 Traces sending of messages.
9684 Message tags: send and send_to_non_existing_process.
9686 'receive':
9688 Traces receiving of messages.
9689 Message tags: 'receive'.
9691 call:
9693 Traces certain function calls. Specify which function calls
9694 to trace by calling erlang:trace_pattern/3.
9695 Message tags: call and return_from.
9697 silent:
9699 Used with the call trace flag. The call, return_from, and
9700 return_to trace messages are inhibited if this flag is set,
9701 but they are executed as normal if there are match specifi‐
9702 cations.
9703 Silent mode is inhibited by executing erlang:trace(_, false,
9705 [silent|_]), or by a match specification executing the func‐
9706 tion {silent, false}.
9707 The silent trace flag facilitates setting up a trace on many
9709 or even all processes in the system. The trace can then be
9710 activated and deactivated using the match specification
9711 function {silent,Bool}, giving a high degree of control of
9712 which functions with which arguments that trigger the trace.
9713 Message tags: call, return_from, and return_to. Or rather,
9715 the absence of.
9716 return_to:
9718 Used with the call trace flag. Traces the return from a
9719 traced function back to its caller. Only works for functions
9720 traced with option local to erlang:trace_pattern/3.
9721 The semantics is that a trace message is sent when a call
9723 traced function returns, that is, when a chain of tail
9724 recursive calls ends. Only one trace message is sent per
9725 chain of tail recursive calls, so the properties of tail
9726 recursiveness for function calls are kept while tracing with
9727 this flag. Using call and return_to trace together makes it
9728 possible to know exactly in which function a process exe‐
9729 cutes at any time.
9730 To get trace messages containing return values from func‐
9732 tions, use the {return_trace} match specification action
9733 instead.
9734 Message tags: return_to.
9736 procs:
9738 Traces process-related events.
9739 Message tags: spawn, spawned, exit, register, unregister,
9741 link, unlink, getting_linked, and getting_unlinked.
9742 ports:
9744 Traces port-related events.
9745 Message tags: open, closed, register, unregister, get‐
9747 ting_linked, and getting_unlinked.
9748 running:
9750 Traces scheduling of processes.
9751 Message tags: in and out.
9753 exiting:
9755 Traces scheduling of exiting processes.
9756 Message tags: in_exiting, out_exiting, and out_exited.
9758 running_procs:
9760 Traces scheduling of processes just like running. However,
9761 this option also includes schedule events when the process
9762 executes within the context of a port without being sched‐
9763 uled out itself.
9764 Message tags: in and out.
9766 running_ports:
9768 Traces scheduling of ports.
9769 Message tags: in and out.
9771 garbage_collection:
9773 Traces garbage collections of processes.
9774 Message tags: gc_minor_start, gc_max_heap_size, and
9776 gc_minor_end.
9777 timestamp:
9779 Includes a time stamp in all trace messages. The time stamp
9780 (Ts) has the same form as returned by erlang:now().
9781 cpu_timestamp:
9783 A global trace flag for the Erlang node that makes all trace
9784 time stamps using flag timestamp to be in CPU time, not wall
9785 clock time. That is, cpu_timestamp is not be used if mono‐
9786 tonic_timestamp or strict_monotonic_timestamp is enabled.
9787 Only allowed with PidPortSpec==all. If the host machine OS
9788 does not support high-resolution CPU time measurements,
9789 trace/3 exits with badarg. Notice that most OS do not syn‐
9790 chronize this value across cores, so be prepared that time
9791 can seem to go backwards when using this option.
9792 monotonic_timestamp:
9794 Includes an Erlang monotonic time time stamp in all trace
9795 messages. The time stamp (Ts) has the same format and value
9796 as produced by erlang:monotonic_time(nanosecond). This flag
9797 overrides flag cpu_timestamp.
9798 strict_monotonic_timestamp:
9800 Includes an time stamp consisting of Erlang monotonic time
9801 and a monotonically increasing integer in all trace mes‐
9802 sages. The time stamp (Ts) has the same format and value as
9803 produced by { erlang:monotonic_time(nanosecond),
9804 erlang:unique_integer([monotonic])}. This flag overrides
9805 flag cpu_timestamp.
9806 arity:
9808 Used with the call trace flag. {M, F, Arity} is specified
9809 instead of {M, F, Args} in call trace messages.
9810 set_on_spawn:
9812 Makes any process created by a traced process inherit its
9813 trace flags, including flag set_on_spawn.
9814 set_on_first_spawn:
9816 Makes the first process created by a traced process inherit
9817 its trace flags, excluding flag set_on_first_spawn.
9818 set_on_link:
9820 Makes any process linked by a traced process inherit its
9821 trace flags, including flag set_on_link.
9822 set_on_first_link:
9824 Makes the first process linked to by a traced process
9825 inherit its trace flags, excluding flag set_on_first_link.
9826 {tracer, Tracer}:
9828 Specifies where to send the trace messages. Tracer must be
9829 the process identifier of a local process or the port iden‐
9830 tifier of a local port.
9831 {tracer, TracerModule, TracerState}:
9833 Specifies that a tracer module is to be called instead of
9834 sending a trace message. The tracer module can then ignore
9835 or change the trace message. For more details on how to
9836 write a tracer module, see erl_tracer(3).
9837 If no tracer is specified, the calling process receives all the
9839 trace messages.
9840 The effect of combining set_on_first_link with set_on_link is
9842 the same as set_on_first_link alone. Likewise for set_on_spawn
9843 and set_on_first_spawn.
9844 The tracing process receives the trace messages described in the
9846 following list. Pid is the process identifier of the traced
9847 process in which the traced event has occurred. The third tuple
9848 element is the message tag.
9849 If flag timestamp, strict_monotonic_timestamp, or mono‐
9851 tonic_timestamp is specified, the first tuple element is
9852 trace_ts instead, and the time stamp is added as an extra ele‐
9853 ment last in the message tuple. If multiple time stamp flags are
9854 passed, timestamp has precedence over strict_monotonic_time‐
9855 stamp, which in turn has precedence over monotonic_timestamp.
9856 All time stamp flags are remembered, so if two are passed and
9857 the one with highest precedence later is disabled, the other one
9858 becomes active.
9859 If a match specification (applicable only for call, send and
9861 'receive' tracing) contains a {message} action function with a
9862 non-boolean value, that value is added as an extra element to
9863 the message tuple either in the last position or before the
9864 timestamp (if it is present).
9865 Trace messages:
9867 {trace, PidPort, send, Msg, To}:
9869 When PidPort sends message Msg to process To.
9870 {trace, PidPort, send_to_non_existing_process, Msg, To}:
9872 When PidPort sends message Msg to the non-existing process
9873 To.
9874 {trace, PidPort, 'receive', Msg}:
9876 When PidPort receives message Msg. If Msg is set to time-
9877 out, a receive statement can have timed out, or the process
9878 received a message with the payload timeout.
9879 {trace, Pid, call, {M, F, Args}}:
9881 When Pid calls a traced function. The return values of calls
9882 are never supplied, only the call and its arguments.
9883 Trace flag arity can be used to change the contents of this
9885 message, so that Arity is specified instead of Args.
9886 {trace, Pid, return_to, {M, F, Arity}}:
9888 When Pid returns to the specified function. This trace mes‐
9889 sage is sent if both the flags call and return_to are set,
9890 and the function is set to be traced on local function
9891 calls. The message is only sent when returning from a chain
9892 of tail recursive function calls, where at least one call
9893 generated a call trace message (that is, the functions match
9894 specification matched, and {message, false} was not an
9895 action).
9896 {trace, Pid, return_from, {M, F, Arity}, ReturnValue}:
9898 When Pid returns from the specified function. This trace
9899 message is sent if flag call is set, and the function has a
9900 match specification with a return_trace or exception_trace
9901 action.
9902 {trace, Pid, exception_from, {M, F, Arity}, {Class, Value}}:
9904 When Pid exits from the specified function because of an
9905 exception. This trace message is sent if flag call is set,
9906 and the function has a match specification with an excep‐
9907 tion_trace action.
9908 {trace, Pid, spawn, Pid2, {M, F, Args}}:
9910 When Pid spawns a new process Pid2 with the specified func‐
9911 tion call as entry point.
9912 Args is supposed to be the argument list, but can be any
9914 term if the spawn is erroneous.
9915 {trace, Pid, spawned, Pid2, {M, F, Args}}:
9917 When Pid is spawned by process Pid2 with the specified func‐
9918 tion call as entry point.
9919 Args is supposed to be the argument list, but can be any
9921 term if the spawn is erroneous.
9922 {trace, Pid, exit, Reason}:
9924 When Pid exits with reason Reason.
9925 {trace, PidPort, register, RegName}:
9927 When PidPort gets the name RegName registered.
9928 {trace, PidPort, unregister, RegName}:
9930 When PidPort gets the name RegName unregistered. This is
9931 done automatically when a registered process or port exits.
9932 {trace, Pid, link, Pid2}:
9934 When Pid links to a process Pid2.
9935 {trace, Pid, unlink, Pid2}:
9937 When Pid removes the link from a process Pid2.
9938 {trace, PidPort, getting_linked, Pid2}:
9940 When PidPort gets linked to a process Pid2.
9941 {trace, PidPort, getting_unlinked, Pid2}:
9943 When PidPort gets unlinked from a process Pid2.
9944 {trace, Pid, exit, Reason}:
9946 When Pid exits with reason Reason.
9947 {trace, Port, open, Pid, Driver}:
9949 When Pid opens a new port Port with the running Driver.
9950 Driver is the name of the driver as an atom.
9952 {trace, Port, closed, Reason}:
9954 When Port closes with Reason.
9955 {trace, Pid, in | in_exiting, {M, F, Arity} | 0}:
9957 When Pid is scheduled to run. The process runs in function
9958 {M, F, Arity}. On some rare occasions, the current function
9959 cannot be determined, then the last element is 0.
9960 {trace, Pid, out | out_exiting | out_exited, {M, F, Arity} |
9962 0}:
9963 When Pid is scheduled out. The process was running in func‐
9964 tion {M, F, Arity}. On some rare occasions, the current
9965 function cannot be determined, then the last element is 0.
9966 {trace, Port, in, Command | 0}:
9968 When Port is scheduled to run. Command is the first thing
9969 the port will execute, it can however run several commands
9970 before being scheduled out. On some rare occasions, the cur‐
9971 rent function cannot be determined, then the last element is
9972 0.
9973 The possible commands are call, close, command, connect,
9975 control, flush, info, link, open, and unlink.
9976 {trace, Port, out, Command | 0}:
9978 When Port is scheduled out. The last command run was Com‐
9979 mand. On some rare occasions, the current function cannot be
9980 determined, then the last element is 0. Command can contain
9981 the same commands as in
9982 {trace, Pid, gc_minor_start, Info}:
9984 Sent when a young garbage collection is about to be started.
9987 Info is a list of two-element tuples, where the first ele‐
9988 ment is a key, and the second is the value. Do not depend on
9989 any order of the tuples. The following keys are defined:
9990 heap_size:
9992 The size of the used part of the heap.
9993 heap_block_size:
9995 The size of the memory block used for storing the heap and
9996 the stack.
9997 old_heap_size:
9999 The size of the used part of the old heap.
10000 old_heap_block_size:
10002 The size of the memory block used for storing the old
10003 heap.
10004 stack_size:
10006 The size of the stack.
10007 recent_size:
10009 The size of the data that survived the previous garbage
10010 collection.
10011 mbuf_size:
10013 The combined size of message buffers associated with the
10014 process.
10015 bin_vheap_size:
10017 The total size of unique off-heap binaries referenced from
10018 the process heap.
10019 bin_vheap_block_size:
10021 The total size of binaries allowed in the virtual heap in
10022 the process before doing a garbage collection.
10023 bin_old_vheap_size:
10025 The total size of unique off-heap binaries referenced from
10026 the process old heap.
10027 bin_old_vheap_block_size:
10029 The total size of binaries allowed in the virtual old heap
10030 in the process before doing a garbage collection.
10031 All sizes are in words.
10033 {trace, Pid, gc_max_heap_size, Info}:
10035 Sent when the max_heap_size is reached during garbage col‐
10036 lection. Info contains the same kind of list as in message
10037 gc_start, but the sizes reflect the sizes that triggered
10038 max_heap_size to be reached.
10039 {trace, Pid, gc_minor_end, Info}:
10041 Sent when young garbage collection is finished. Info con‐
10042 tains the same kind of list as in message gc_minor_start,
10043 but the sizes reflect the new sizes after garbage collec‐
10044 tion.
10045 {trace, Pid, gc_major_start, Info}:
10047 Sent when fullsweep garbage collection is about to be
10048 started. Info contains the same kind of list as in message
10049 gc_minor_start.
10050 {trace, Pid, gc_major_end, Info}:
10052 Sent when fullsweep garbage collection is finished. Info
10053 contains the same kind of list as in message gc_minor_start,
10054 but the sizes reflect the new sizes after a fullsweep
10055 garbage collection.
10056 If the tracing process/port dies or the tracer module returns
10058 remove, the flags are silently removed.
10059 Each process can only be traced by one tracer. Therefore,
10061 attempts to trace an already traced process fail.
10062 Returns a number indicating the number of processes that matched
10064 PidPortSpec. If PidPortSpec is a process identifier, the return
10065 value is 1. If PidPortSpec is all or existing, the return value
10066 is the number of processes running. If PidPortSpec is new, the
10067 return value is 0.
10068 Failure: badarg if the specified arguments are not supported.
10070 For example, cpu_timestamp is not supported on all platforms.
10071 erlang:trace_delivered(Tracee) -> Ref
10073 Types:
10075 Tracee = pid() | all
10077 Ref = reference()
10078 The delivery of trace messages (generated by erlang:trace/3,
10080 seq_trace(3), or erlang:system_profile/2) is dislocated on the
10081 time-line compared to other events in the system. If you know
10082 that Tracee has passed some specific point in its execution, and
10083 you want to know when at least all trace messages corresponding
10084 to events up to this point have reached the tracer, use
10085 erlang:trace_delivered(Tracee).
10086 When it is guaranteed that all trace messages are delivered to
10088 the tracer up to the point that Tracee reached at the time of
10089 the call to erlang:trace_delivered(Tracee), then a {trace_deliv‐
10090 ered, Tracee, Ref} message is sent to the caller of
10091 erlang:trace_delivered(Tracee) .
10092 Notice that message trace_delivered does not imply that trace
10094 messages have been delivered. Instead it implies that all trace
10095 messages that are to be delivered have been delivered. It is not
10096 an error if Tracee is not, and has not been traced by someone,
10097 but if this is the case, no trace messages have been delivered
10098 when the trace_delivered message arrives.
10099 Notice that Tracee must refer to a process currently or previ‐
10101 ously existing on the same node as the caller of
10102 erlang:trace_delivered(Tracee) resides on. The special Tracee
10103 atom all denotes all processes that currently are traced in the
10104 node.
10105 When used together with a Tracer Module, any message sent in
10107 the trace callback is guaranteed to have reached its recipient
10108 before the trace_delivered message is sent.
10109 Example: Process A is Tracee, port B is tracer, and process C is
10111 the port owner of B. C wants to close B when A exits. To ensure
10112 that the trace is not truncated, C can call erlang:trace_deliv‐
10113 ered(A) when A exits, and wait for message {trace_delivered, A,
10114 Ref} before closing B.
10115 Failure: badarg if Tracee does not refer to a process (dead or
10117 alive) on the same node as the caller of erlang:trace_deliv‐
10118 ered(Tracee) resides on.
10119 erlang:trace_info(PidPortFuncEvent, Item) -> Res
10121 Types:
10123 PidPortFuncEvent =
10125 pid() |
10126 port() |
10127 new | new_processes | new_ports |
10128 {Module, Function, Arity} |
10129 on_load | send | 'receive'
10130 Module = module()
10131 Function = atom()
10132 Arity = arity()
10133 Item =
10134 flags | tracer | traced | match_spec | meta |
10135 meta_match_spec | call_count | call_time | all
10136 Res = trace_info_return()
10137 trace_info_return() =
10138 undefined |
10139 {flags, [trace_info_flag()]} |
10140 {tracer, pid() | port() | []} |
10141 {tracer, module(), term()} |
10142 trace_info_item_result() |
10143 {all, [trace_info_item_result()] | false | undefined}
10144 trace_info_item_result() =
10145 {traced, global | local | false | undefined} |
10146 {match_spec, trace_match_spec() | false | undefined} |
10147 {meta, pid() | port() | false | undefined | []} |
10148 {meta, module(), term()} |
10149 {meta_match_spec, trace_match_spec() | false | undefined} |
10150 {call_count, integer() >= 0 | boolean() | undefined} |
10151 {call_time,
10152 [{pid(),
10153 integer() >= 0,
10154 integer() >= 0,
10155 integer() >= 0}] |
10156 boolean() |
10157 undefined}
10158 trace_info_flag() =
10159 send | 'receive' | set_on_spawn | call | return_to | procs |
10160 set_on_first_spawn | set_on_link | running |
10161 garbage_collection | timestamp | monotonic_timestamp |
10162 strict_monotonic_timestamp | arity
10163 trace_match_spec() =
10164 [{[term()] | '_' | match_variable(), [term()], [term()]}]
10165 match_variable() = atom()
10166 Approximation of '$1' | '$2' | '$3' | ...
10167 Returns trace information about a port, process, function, or
10169 event.
10170 To get information about a port or process, PidPortFuncEvent is
10172 to be a process identifier (pid), port identifier, or one of the
10173 atoms new, new_processes, or new_ports. The atom new or new_pro‐
10174 cesses means that the default trace state for processes to be
10175 created is returned. The atom new_ports means that the default
10176 trace state for ports to be created is returned.
10177 Valid Items for ports and processes:
10179 flags:
10181 Returns a list of atoms indicating what kind of traces is
10182 enabled for the process. The list is empty if no traces are
10183 enabled, and one or more of the followings atoms if traces
10184 are enabled: send, 'receive', set_on_spawn, call, return_to,
10185 procs, ports, set_on_first_spawn, set_on_link, running, run‐
10186 ning_procs, running_ports, silent, exiting, monotonic_time‐
10187 stamp, strict_monotonic_timestamp, garbage_collection, time‐
10188 stamp, and arity. The order is arbitrary.
10189 tracer:
10191 Returns the identifier for process, port, or a tuple con‐
10192 taining the tracer module and tracer state tracing this
10193 process. If this process is not traced, the return value is
10194 [].
10195 To get information about a function, PidPortFuncEvent is to be
10197 the three-element tuple {Module, Function, Arity} or the atom
10198 on_load. No wildcards are allowed. Returns undefined if the
10199 function does not exist, or false if the function is not traced.
10200 If PidPortFuncEvent is on_load, the information returned refers
10201 to the default value for code that will be loaded.
10202 Valid Items for functions:
10204 traced:
10206 Returns global if this function is traced on global function
10207 calls, local if this function is traced on local function
10208 calls (that is, local and global function calls), and false
10209 if local or global function calls are not traced.
10210 match_spec:
10212 Returns the match specification for this function, if it has
10213 one. If the function is locally or globally traced but has
10214 no match specification defined, the returned value is [].
10215 meta:
10217 Returns the meta-trace tracer process, port, or trace module
10218 for this function, if it has one. If the function is not
10219 meta-traced, the returned value is false. If the function is
10220 meta-traced but has once detected that the tracer process is
10221 invalid, the returned value is [].
10222 meta_match_spec:
10224 Returns the meta-trace match specification for this func‐
10225 tion, if it has one. If the function is meta-traced but has
10226 no match specification defined, the returned value is [].
10227 call_count:
10229 Returns the call count value for this function or true for
10230 the pseudo function on_load if call count tracing is active.
10231 Otherwise false is returned.
10232 See also erlang:trace_pattern/3.
10234 call_time:
10236 Returns the call time values for this function or true for
10237 the pseudo function on_load if call time tracing is active.
10238 Otherwise false is returned. The call time values returned,
10239 [{Pid, Count, S, Us}], is a list of each process that exe‐
10240 cuted the function and its specific counters.
10241 See also erlang:trace_pattern/3.
10243 all:
10245 Returns a list containing the {Item, Value} tuples for all
10246 other items, or returns false if no tracing is active for
10247 this function.
10248 To get information about an event, PidPortFuncEvent is to be one
10250 of the atoms send or 'receive'.
10251 One valid Item for events exists:
10253 match_spec:
10255 Returns the match specification for this event, if it has
10256 one, or true if no match specification has been set.
10257 The return value is {Item, Value}, where Value is the requested
10259 information as described earlier. If a pid for a dead process
10260 was specified, or the name of a non-existing function, Value is
10261 undefined.
10262 erlang:trace_pattern(MFA, MatchSpec) -> integer() >= 0
10264 Types:
10266 MFA = trace_pattern_mfa() | send | 'receive'
10268 MatchSpec =
10269 (MatchSpecList :: trace_match_spec()) |
10270 boolean() |
10271 restart | pause
10272 trace_pattern_mfa() = {atom(), atom(), arity() | '_'} | on_load
10273 trace_match_spec() =
10274 [{[term()] | '_' | match_variable(), [term()], [term()]}]
10275 match_variable() = atom()
10276 Approximation of '$1' | '$2' | '$3' | ...
10277 The same as erlang:trace_pattern(Event, MatchSpec, []), retained
10279 for backward compatibility.
10280 erlang:trace_pattern(MFA :: send, MatchSpec, FlagList :: []) ->
10282 integer() >= 0
10283 Types:
10285 MatchSpec = (MatchSpecList :: trace_match_spec()) | boolean()
10287 trace_match_spec() =
10288 [{[term()] | '_' | match_variable(), [term()], [term()]}]
10289 match_variable() = atom()
10290 Approximation of '$1' | '$2' | '$3' | ...
10291 Sets trace pattern for message sending. Must be combined with
10293 erlang:trace/3 to set the send trace flag for one or more pro‐
10294 cesses. By default all messages sent from send traced processes
10295 are traced. To limit traced send events based on the message
10296 content, the sender and/or the receiver, use erlang:trace_pat‐
10297 tern/3.
10298 Argument MatchSpec can take the following forms:
10300 MatchSpecList:
10302 A list of match specifications. The matching is done on the
10303 list [Receiver, Msg]. Receiver is the process or port iden‐
10304 tity of the receiver and Msg is the message term. The pid of
10305 the sending process can be accessed with the guard function
10306 self/0. An empty list is the same as true. For more informa‐
10307 tion, see section Match Specifications in Erlang in the
10308 User's Guide.
10309 true:
10311 Enables tracing for all sent messages (from send traced pro‐
10312 cesses). Any match specification is removed. This is the
10313 default.
10314 false:
10316 Disables tracing for all sent messages. Any match specifica‐
10317 tion is removed.
10318 Argument FlagList must be [] for send tracing.
10320 The return value is always 1.
10322 Examples:
10324 Only trace messages to a specific process Pid:
10326 > erlang:trace_pattern(send, [{[Pid, '_'],[],[]}], []).
10328 1
10329 Only trace messages matching {reply, _}:
10331 > erlang:trace_pattern(send, [{['_', {reply,'_'}],[],[]}], []).
10333 1
10334 Only trace messages sent to the sender itself:
10336 > erlang:trace_pattern(send, [{['$1', '_'],[{'=:=','$1',{self}}],[]}], []).
10338 1
10339 Only trace messages sent to other nodes:
10341 > erlang:trace_pattern(send, [{['$1', '_'],[{'=/=',{node,'$1'},{node}}],[]}], []).
10343 1
10344 Note:
10346 A match specification for send trace can use all guard and body
10347 functions except caller.
10348 Fails by raising an error exception with an error reason of:
10351 badarg:
10353 If an argument is invalid.
10354 system_limit:
10356 If a match specification passed as argument has excessive
10357 nesting which causes scheduler stack exhaustion for the
10358 scheduler that the calling process is executing on. Sched‐
10359 uler stack size can be configured when starting the runtime
10360 system.
10361 erlang:trace_pattern(MFA :: 'receive', MatchSpec, FlagList :: []) ->
10363 integer() >= 0
10364 Types:
10366 MatchSpec = (MatchSpecList :: trace_match_spec()) | boolean()
10368 trace_match_spec() =
10369 [{[term()] | '_' | match_variable(), [term()], [term()]}]
10370 match_variable() = atom()
10371 Approximation of '$1' | '$2' | '$3' | ...
10372 Sets trace pattern for message receiving. Must be combined with
10374 erlang:trace/3 to set the 'receive' trace flag for one or more
10375 processes. By default all messages received by 'receive' traced
10376 processes are traced. To limit traced receive events based on
10377 the message content, the sender and/or the receiver, use
10378 erlang:trace_pattern/3.
10379 Argument MatchSpec can take the following forms:
10381 MatchSpecList:
10383 A list of match specifications. The matching is done on the
10384 list [Node, Sender, Msg]. Node is the node name of the
10385 sender. Sender is the process or port identity of the
10386 sender, or the atom undefined if the sender is not known
10387 (which can be the case for remote senders). Msg is the mes‐
10388 sage term. The pid of the receiving process can be accessed
10389 with the guard function self/0. An empty list is the same as
10390 true. For more information, see section Match Specifica‐
10391 tions in Erlang in the User's Guide.
10392 true:
10394 Enables tracing for all received messages (to 'receive'
10395 traced processes). Any match specification is removed. This
10396 is the default.
10397 false:
10399 Disables tracing for all received messages. Any match speci‐
10400 fication is removed.
10401 Argument FlagList must be [] for receive tracing.
10403 The return value is always 1.
10405 Examples:
10407 Only trace messages from a specific process Pid:
10409 > erlang:trace_pattern('receive', [{['_',Pid, '_'],[],[]}], []).
10411 1
10412 Only trace messages matching {reply, _}:
10414 > erlang:trace_pattern('receive', [{['_','_', {reply,'_'}],[],[]}], []).
10416 1
10417 Only trace messages from other nodes:
10419 > erlang:trace_pattern('receive', [{['$1', '_', '_'],[{'=/=','$1',{node}}],[]}], []).
10421 1
10422 Note:
10424 A match specification for 'receive' trace can use all guard and
10425 body functions except caller, is_seq_trace, get_seq_token,
10426 set_seq_token, enable_trace, disable_trace, trace, silent, and
10427 process_dump.
10428 Fails by raising an error exception with an error reason of:
10431 badarg:
10433 If an argument is invalid.
10434 system_limit:
10436 If a match specification passed as argument has excessive
10437 nesting which causes scheduler stack exhaustion for the
10438 scheduler that the calling process is executing on. Sched‐
10439 uler stack size can be configured when starting the runtime
10440 system.
10441 erlang:trace_pattern(MFA, MatchSpec, FlagList) ->
10443 integer() >= 0
10444 Types:
10446 MFA = trace_pattern_mfa()
10448 MatchSpec =
10449 (MatchSpecList :: trace_match_spec()) |
10450 boolean() |
10451 restart | pause
10452 FlagList = [trace_pattern_flag()]
10453 trace_pattern_mfa() = {atom(), atom(), arity() | '_'} | on_load
10454 trace_match_spec() =
10455 [{[term()] | '_' | match_variable(), [term()], [term()]}]
10456 trace_pattern_flag() =
10457 global | local | meta |
10458 {meta, Pid :: pid()} |
10459 {meta, TracerModule :: module(), TracerState :: term()} |
10460 call_count | call_time
10461 match_variable() = atom()
10462 Approximation of '$1' | '$2' | '$3' | ...
10463 Enables or disables call tracing for one or more functions. Must
10465 be combined with erlang:trace/3 to set the call trace flag for
10466 one or more processes.
10467 Conceptually, call tracing works as follows. Inside the Erlang
10469 virtual machine, a set of processes and a set of functions are
10470 to be traced. If a traced process calls a traced function, the
10471 trace action is taken. Otherwise, nothing happens.
10472 To add or remove one or more processes to the set of traced pro‐
10474 cesses, use erlang:trace/3.
10475 To add or remove functions to the set of traced functions, use
10477 erlang:trace_pattern/3.
10478 The BIF erlang:trace_pattern/3 can also add match specifications
10480 to a function. A match specification comprises a pattern that
10481 the function arguments must match, a guard expression that must
10482 evaluate to true, and an action to be performed. The default
10483 action is to send a trace message. If the pattern does not match
10484 or the guard fails, the action is not executed.
10485 Argument MFA is to be a tuple, such as {Module, Function,
10487 Arity}, or the atom on_load (described below). It can be the
10488 module, function, and arity for a function (or a BIF in any mod‐
10489 ule). The atom '_' can be used as a wildcard in any of the fol‐
10490 lowing ways:
10491 {Module,Function,'_'}:
10493 All functions of any arity named Function in module Module.
10494 {Module,'_','_'}:
10496 All functions in module Module.
10497 {'_','_','_'}:
10499 All functions in all loaded modules.
10500 Other combinations, such as {Module,'_',Arity}, are not allowed.
10502 Local functions match wildcards only if option local is in
10503 FlagList.
10504 If argument MFA is the atom on_load, the match specification and
10506 flag list are used on all modules that are newly loaded.
10507 Argument MatchSpec can take the following forms:
10509 false:
10511 Disables tracing for the matching functions. Any match spec‐
10512 ification is removed.
10513 true:
10515 Enables tracing for the matching functions. Any match speci‐
10516 fication is removed.
10517 MatchSpecList:
10519 A list of match specifications. An empty list is equivalent
10520 to true. For a description of match specifications, see sec‐
10521 tion Match Specifications in Erlang in the User's Guide.
10522 restart:
10524 For the FlagList options call_count and call_time: restarts
10525 the existing counters. The behavior is undefined for other
10526 FlagList options.
10527 pause:
10529 For the FlagList options call_count and call_time: pauses
10530 the existing counters. The behavior is undefined for other
10531 FlagList options.
10532 Parameter FlagList is a list of options. The following are the
10534 valid options:
10535 global:
10537 Turns on or off call tracing for global function calls (that
10538 is, calls specifying the module explicitly). Only exported
10539 functions match and only global calls generate trace mes‐
10540 sages. This is the default.
10541 local:
10543 Turns on or off call tracing for all types of function
10544 calls. Trace messages are sent whenever any of the specified
10545 functions are called, regardless of how they are called. If
10546 flag return_to is set for the process, a return_to message
10547 is also sent when this function returns to its caller.
10548 meta | {meta, Pid} | {meta, TracerModule, TracerState}:
10550 Turns on or off meta-tracing for all types of function
10551 calls. Trace messages are sent to the tracer whenever any of
10552 the specified functions are called. If no tracer is speci‐
10553 fied, self() is used as a default tracer process.
10554 Meta-tracing traces all processes and does not care about
10556 the process trace flags set by erlang:trace/3, the trace
10557 flags are instead fixed to [call, timestamp].
10558 The match specification function {return_trace} works with
10560 meta-trace and sends its trace message to the same tracer.
10561 call_count:
10563 Starts (MatchSpec == true) or stops (MatchSpec == false)
10564 call count tracing for all types of function calls. For
10565 every function, a counter is incremented when the function
10566 is called, in any process. No process trace flags need to be
10567 activated.
10568 If call count tracing is started while already running, the
10570 count is restarted from zero. To pause running counters, use
10571 MatchSpec == pause. Paused and running counters can be
10572 restarted from zero with MatchSpec == restart.
10573 To read the counter value, use erlang:trace_info/2.
10575 call_time:
10577 Starts (MatchSpec == true) or stops (MatchSpec == false)
10578 call time tracing for all types of function calls. For every
10579 function, a counter is incremented when the function is
10580 called. Time spent in the function is accumulated in two
10581 other counters, seconds and microseconds. The counters are
10582 stored for each call traced process.
10583 If call time tracing is started while already running, the
10585 count and time restart from zero. To pause running counters,
10586 use MatchSpec == pause. Paused and running counters can be
10587 restarted from zero with MatchSpec == restart.
10588 To read the counter value, use erlang:trace_info/2.
10590 The options global and local are mutually exclusive, and global
10592 is the default (if no options are specified). The options
10593 call_count and meta perform a kind of local tracing, and cannot
10594 be combined with global. A function can be globally or locally
10595 traced. If global tracing is specified for a set of functions,
10596 then local, meta, call time, and call count tracing for the
10597 matching set of local functions is disabled, and conversely.
10598 When disabling trace, the option must match the type of trace
10600 set on the function. That is, local tracing must be disabled
10601 with option local and global tracing with option global (or no
10602 option), and so on.
10603 Part of a match specification list cannot be changed directly.
10605 If a function has a match specification, it can be replaced with
10606 a new one. To change an existing match specification, use the
10607 BIF erlang:trace_info/2 to retrieve the existing match specifi‐
10608 cation.
10609 Returns the number of functions matching argument MFA. This is
10611 zero if none matched.
10612 Fails by raising an error exception with an error reason of:
10614 badarg:
10616 If an argument is invalid.
10617 system_limit:
10619 If a match specification passed as argument has excessive
10620 nesting which causes scheduler stack exhaustion for the
10621 scheduler that the calling process is executing on. Sched‐
10622 uler stack size can be configured when starting the runtime
10623 system.
10624 trunc(Number) -> integer()
10626 Types:
10628 Number = number()
10630 Returns an integer by truncating Number, for example:
10632 > trunc(5.5).
10634 5
10635 Allowed in guard tests.
10637 tuple_size(Tuple) -> integer() >= 0
10639 Types:
10641 Tuple = tuple()
10643 Returns an integer that is the number of elements in Tuple, for
10645 example:
10646 > tuple_size({morni, mulle, bwange}).
10648 3
10649 Allowed in guard tests.
10651 tuple_to_list(Tuple) -> [term()]
10653 Types:
10655 Tuple = tuple()
10657 Returns a list corresponding to Tuple. Tuple can contain any
10659 Erlang terms. Example:
10660 > tuple_to_list({share, {'Ericsson_B', 163}}).
10662 [share,{'Ericsson_B',163}]
10663 erlang:unique_integer() -> integer()
10665 Generates and returns an integer unique on current runtime sys‐
10667 tem instance. The same as calling erlang:unique_integer([]).
10668 erlang:unique_integer(ModifierList) -> integer()
10670 Types:
10672 ModifierList = [Modifier]
10674 Modifier = positive | monotonic
10675 Generates and returns an integer unique on current runtime sys‐
10677 tem instance. The integer is unique in the sense that this BIF,
10678 using the same set of modifiers, does not return the same inte‐
10679 ger more than once on the current runtime system instance. Each
10680 integer value can of course be constructed by other means.
10681 By default, when [] is passed as ModifierList, both negative and
10683 positive integers can be returned. This to use the range of
10684 integers that do not need heap memory allocation as much as pos‐
10685 sible. By default the returned integers are also only guaranteed
10686 to be unique, that is, any returned integer can be smaller or
10687 larger than previously returned integers.
10688 Modifiers:
10690 positive:
10692 Returns only positive integers.
10693 Notice that by passing the positive modifier you will get
10695 heap allocated integers (bignums) quicker.
10696 monotonic:
10698 Returns strictly monotonically increasing integers corre‐
10699 sponding to creation time. That is, the integer returned is
10700 always larger than previously returned integers on the cur‐
10701 rent runtime system instance.
10702 These values can be used to determine order between events
10704 on the runtime system instance. That is, if both X =
10705 erlang:unique_integer([monotonic]) and Y =
10706 erlang:unique_integer([monotonic]) are executed by different
10707 processes (or the same process) on the same runtime system
10708 instance and X < Y, we know that X was created before Y.
10709 Warning:
10711 Strictly monotonically increasing values are inherently quite
10712 expensive to generate and scales poorly. This is because the
10713 values need to be synchronized between CPU cores. That is, do
10714 not pass the monotonic modifier unless you really need
10715 strictly monotonically increasing values.
10716 All valid Modifiers can be combined. Repeated (valid) Modifiers
10719 in the ModifierList are ignored.
10720 Note:
10722 The set of integers returned by erlang:unique_integer/1 using
10723 different sets of Modifiers will overlap. For example, by call‐
10724 ing unique_integer([monotonic]), and unique_integer([positive,
10725 monotonic]) repeatedly, you will eventually see some integers
10726 that are returned by both calls.
10727 Failures:
10730 badarg:
10732 if ModifierList is not a proper list.
10733 badarg:
10735 if Modifier is not a valid modifier.
10736 erlang:universaltime() -> DateTime
10738 Types:
10740 DateTime = calendar:datetime()
10742 Returns the current date and time according to Universal Time
10744 Coordinated (UTC) in the form {{Year, Month, Day}, {Hour,
10745 Minute, Second}} if supported by the underlying OS. Otherwise
10746 erlang:universaltime() is equivalent to erlang:localtime().
10747 Example:
10748 > erlang:universaltime().
10750 {{1996,11,6},{14,18,43}}
10751 erlang:universaltime_to_localtime(Universaltime) -> Localtime
10753 Types:
10755 Localtime = Universaltime = calendar:datetime()
10757 Converts Universal Time Coordinated (UTC) date and time to local
10759 date and time in the form {{Year, Month, Day}, {Hour, Minute,
10760 Second}} if supported by the underlying OS. Otherwise no conver‐
10761 sion is done, and Universaltime is returned. Example:
10762 > erlang:universaltime_to_localtime({{1996,11,6},{14,18,43}}).
10764 {{1996,11,7},{15,18,43}}
10765 Failure: badarg if Universaltime denotes an invalid date and
10767 time.
10768 unlink(Id) -> true
10770 Types:
10772 Id = pid() | port()
10774 Removes a link between the calling process and another process
10776 or a port identified by Id. We will from here on call the iden‐
10777 tified process or port unlinkee.
10778 A link can be set up using the link/1 BIF. For more information
10780 on links and exit signals due to links, see the Processes chap‐
10781 ter in the Erlang Reference Manual :
10782 * Links
10784 * Sending Exit Signals
10786 * Receiving Exit Signals
10788 Once unlink(Id) has returned, it is guaranteed that the link
10790 between the caller and the unlinkee has no effect on the caller
10791 in the future (unless the link is setup again). Note that if the
10792 caller is trapping exits, an {'EXIT', Id, ExitReason} message
10793 due to the link may have been placed in the message queue of the
10794 caller before the unlink(Id) call completed. Also note that the
10795 {'EXIT', Id, ExitReason} message may be the result of the link,
10796 but may also be the result of the unlikee sending the caller an
10797 exit signal by calling the exit/2 BIF. Therefore, it may or may
10798 not be appropriate to clean up the message queue after a call to
10799 unlink(Id) as follows, when trapping exits:
10800 unlink(Id),
10802 receive
10803 {'EXIT', Id, _} ->
10804 true
10805 after 0 ->
10806 true
10807 end
10808 The link removal is performed asynchronously. If such a link
10810 does not exist, nothing is done. A detailed description of the
10811 link protocol can be found in the Distribution Protocol chapter
10812 of the ERTS User's Guide .
10813 Failure: badarg if Id does not identify a process or a node
10815 local port.
10816 unregister(RegName) -> true
10818 Types:
10820 RegName = atom()
10822 Removes the registered name RegName associated with a process
10824 identifier or a port identifier, for example:
10825 > unregister(db).
10827 true
10828 Users are advised not to unregister system processes.
10830 Failure: badarg if RegName is not a registered name.
10832 whereis(RegName) -> pid() | port() | undefined
10834 Types:
10836 RegName = atom()
10838 Returns the process identifier or port identifier with the reg‐
10840 istered name RegName. Returns undefined if the name is not reg‐
10841 istered. Example:
10842 > whereis(db).
10844 <0.43.0>
10845 erlang:yield() -> true
10847 Voluntarily lets other processes (if any) get a chance to exe‐
10849 cute. Using this function is similar to receive after 1 -> true
10850 end, except that yield() is faster.
10851 Warning:
10853 There is seldom or never any need to use this BIF as other pro‐
10854 cesses have a chance to run in another scheduler thread anyway.
10855 Using this BIF without a thorough grasp of how the scheduler
10856 works can cause performance degradation.
10857Ericsson AB erts 11.2 erlang(3)