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 ex‐
34 ternal 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 monitor_option() =
46 {alias, explicit_unalias | demonitor | reply_demonitor} |
47 {tag, term()}
48 See monitor/3.
50 timestamp() =
52 {MegaSecs :: integer() >= 0,
53 Secs :: integer() >= 0,
54 MicroSecs :: integer() >= 0}
55 See erlang:timestamp/0.
57 time_unit() =
59 integer() >= 1 |
60 second | millisecond | microsecond | nanosecond | native |
61 perf_counter |
62 deprecated_time_unit()
63 Supported time unit representations:
65 PartsPerSecond :: integer() >= 1:
67 Time unit expressed in parts per second. That is, the time
68 unit equals 1/PartsPerSecond second.
69 second:
71 Symbolic representation of the time unit represented by the
72 integer 1.
73 millisecond:
75 Symbolic representation of the time unit represented by the
76 integer 1000.
77 microsecond:
79 Symbolic representation of the time unit represented by the
80 integer 1000_000.
81 nanosecond:
83 Symbolic representation of the time unit represented by the
84 integer 1000_000_000.
85 native:
87 Symbolic representation of the native time unit used by the
88 Erlang runtime system.
89 The native time unit is determined at runtime system start,
91 and remains the same until the runtime system terminates. If
92 a runtime system is stopped and then started again (even on
93 the same machine), the native time unit of the new runtime
94 system instance can differ from the native time unit of the
95 old runtime system instance.
96 One can get an approximation of the native time unit by
98 calling erlang:convert_time_unit(1, second, native). The re‐
99 sult equals the number of whole native time units per sec‐
100 ond. If the number of native time units per second does not
101 add up to a whole number, the result is rounded downwards.
102 Note:
104 The value of the native time unit gives you more or less no
105 information about the quality of time values. It sets a limit
106 for the resolution and for the precision of time values, but
107 it gives no information about the accuracy of time values.
108 The resolution of the native time unit and the resolution of
109 time values can differ significantly.
110 perf_counter:
113 Symbolic representation of the performance counter time unit
114 used by the Erlang runtime system.
115 The perf_counter time unit behaves much in the same way as
117 the native time unit. That is, it can differ between runtime
118 restarts. To get values of this type, call
119 os:perf_counter/0.
120 deprecated_time_unit():
122 Deprecated symbolic representations kept for backwards-com‐
123 patibility.
124 The time_unit/0 type can be extended. To convert time values be‐
126 tween time units, use erlang:convert_time_unit/3.
127 deprecated_time_unit() =
129 seconds | milli_seconds | micro_seconds | nano_seconds
130 The time_unit() type also consist of the following deprecated
132 symbolic time units:
133 seconds:
135 Same as second.
136 milli_seconds:
138 Same as millisecond.
139 micro_seconds:
141 Same as microsecond.
142 nano_seconds:
144 Same as nanosecond.
145 dist_handle()
147 An opaque handle identifing a distribution channel.
149 nif_resource()
151 An opaque handle identifing a NIF resource object .
153 spawn_opt_option() =
155 link | monitor |
156 {monitor, MonitorOpts :: [monitor_option()]} |
157 {priority, Level :: priority_level()} |
158 {fullsweep_after, Number :: integer() >= 0} |
159 {min_heap_size, Size :: integer() >= 0} |
160 {min_bin_vheap_size, VSize :: integer() >= 0} |
161 {max_heap_size, Size :: max_heap_size()} |
162 {message_queue_data, MQD :: message_queue_data()}
163 Options for spawn_opt().
165 priority_level() = low | normal | high | max
167 Process priority level. For more info see process_flag(priority,
169 Level)
170 max_heap_size() =
172 integer() >= 0 |
173 #{size => integer() >= 0,
174 kill => boolean(),
175 error_logger => boolean()}
176 Process max heap size configuration. For more info see
178 process_flag(max_heap_size, MaxHeapSize)
179 message_queue_data() = off_heap | on_heap
181 Process message queue data configuration. For more information,
183 see process_flag(message_queue_data, MQD)
184 stacktrace() =
186 [{module(),
187 atom(),
188 arity() | [term()],
189 [stacktrace_extrainfo()]} |
190 {function(), arity() | [term()], [stacktrace_extrainfo()]}]
191 stacktrace_extrainfo() =
193 {line, integer() >= 1} |
194 {file, unicode:chardata()} |
195 {error_info,
196 #{module => module(), function => atom(), cause => term()}} |
197 {atom(), term()}
198 An Erlang stacktrace as described by Errors and Error Handling
200 section in the Erlang Reference Manual.
201
203 abs(Float) -> float()
204 abs(Int) -> integer() >= 0
206 Types:
208 Int = integer()
210 Returns an integer or float that is the arithmetical absolute
212 value of Float or Int, for example:
213 > abs(-3.33).
215 3.33
216 > abs(-3).
217 3
218 Allowed in guard tests.
220 erlang:adler32(Data) -> integer() >= 0
222 Types:
224 Data = iodata()
226 Computes and returns the adler32 checksum for Data.
228 erlang:adler32(OldAdler, Data) -> integer() >= 0
230 Types:
232 OldAdler = integer() >= 0
234 Data = iodata()
235 Continues computing the adler32 checksum by combining the previ‐
237 ous checksum, OldAdler, with the checksum of Data.
238 The following code:
240 X = erlang:adler32(Data1),
242 Y = erlang:adler32(X,Data2).
243 assigns the same value to Y as this:
245 Y = erlang:adler32([Data1,Data2]).
247 erlang:adler32_combine(FirstAdler, SecondAdler, SecondSize) ->
249 integer() >= 0
250 Types:
252 FirstAdler = SecondAdler = SecondSize = integer() >= 0
254 Combines two previously computed adler32 checksums. This compu‐
256 tation requires the size of the data object for the second
257 checksum to be known.
258 The following code:
260 Y = erlang:adler32(Data1),
262 Z = erlang:adler32(Y,Data2).
263 assigns the same value to Z as this:
265 X = erlang:adler32(Data1),
267 Y = erlang:adler32(Data2),
268 Z = erlang:adler32_combine(X,Y,iolist_size(Data2)).
269 alias() -> Alias
271 alias(Opts) -> Alias
273 Types:
275 Alias = reference()
277 Opts = [explicit_unalias | reply]
278 Create an alias which can be used when sending messages to the
280 process that created the alias. When the alias has been deacti‐
281 vated, messages sent using the alias will be dropped. An alias
282 can be deactivated using unalias/1. Currently available options
283 for alias/1:
284 explicit_unalias:
286 The alias can only be deactivated via a call to unalias/1.
287 This is also the default behaviour if no options are passed
288 or if alias/0 is called.
289 reply:
291 The alias will be automatically deactivated when a reply
292 message sent via the alias is received. The alias can also
293 still be deactivated via a call to unalias/1.
294 Example:
296 server() ->
298 receive
299 {request, AliasReqId, Request} ->
300 Result = perform_request(Request),
301 AliasReqId ! {reply, AliasReqId, Result}
302 end,
303 server().
304 client(ServerPid, Request) ->
306 AliasReqId = alias([reply]),
307 ServerPid ! {request, AliasReqId, Request},
308 %% Alias will be automatically deactivated if we receive a reply
309 %% since we used the 'reply' option...
310 receive
311 {reply, AliasReqId, Result} -> Result
312 after 5000 ->
313 unalias(AliasReqId),
314 %% Flush message queue in case the reply arrived
315 %% just before the alias was deactivated...
316 receive {reply, AliasReqId, Result} -> Result
317 after 0 -> exit(timeout)
318 end
319 end.
320 Note that both the server and the client in this example must be
323 executing on at least OTP 24 systems in order for this to work.
324 For more information on process aliases see the Process Aliases
326 section of the Erlang Reference Manual .
327 erlang:append_element(Tuple1, Term) -> Tuple2
329 Types:
331 Tuple1 = Tuple2 = tuple()
333 Term = term()
334 Returns a new tuple that has one element more than Tuple1, and
336 contains the elements in Tuple1 followed by Term as the last el‐
337 ement. Semantically equivalent to list_to_tuple(tu‐
338 ple_to_list(Tuple1) ++ [Term]), but much faster. Example:
339 > erlang:append_element({one, two}, three).
341 {one,two,three}
342 apply(Fun, Args) -> term()
344 Types:
346 Fun = function()
348 Args = [term()]
349 Calls a fun, passing the elements in Args as arguments.
351 If the number of elements in the arguments are known at compile
353 time, the call is better written as Fun(Arg1, Arg2, ... ArgN).
354 Warning:
356 Earlier, Fun could also be specified as {Module, Function},
357 equivalent to apply(Module, Function, Args). This use is depre‐
358 cated and will stop working in a future release.
359 apply(Module, Function, Args) -> term()
362 Types:
364 Module = module()
366 Function = atom()
367 Args = [term()]
368 Returns the result of applying Function in Module to Args. The
370 applied function must be exported from Module. The arity of the
371 function is the length of Args. Example:
372 > apply(lists, reverse, [[a, b, c]]).
374 [c,b,a]
375 > apply(erlang, atom_to_list, ['Erlang']).
376 "Erlang"
377 If the number of arguments are known at compile time, the call
379 is better written as Module:Function(Arg1, Arg2, ..., ArgN).
380 Failure: error_handler:undefined_function/3 is called if the ap‐
382 plied function is not exported. The error handler can be rede‐
383 fined (see process_flag/2). If error_handler is undefined, or if
384 the user has redefined the default error_handler so the replace‐
385 ment module is undefined, an error with reason undef is gener‐
386 ated.
387 atom_to_binary(Atom) -> binary()
389 Types:
391 Atom = atom()
393 The same as atom_to_binary(Atom, utf8).
395 atom_to_binary(Atom, Encoding) -> binary()
397 Types:
399 Atom = atom()
401 Encoding = latin1 | unicode | utf8
402 Returns a binary corresponding to the text representation of
404 Atom. If Encoding is latin1, one byte exists for each character
405 in the text representation. If Encoding is utf8 or unicode, the
406 characters are encoded using UTF-8 where characters may require
407 multiple bytes.
408 Note:
410 As from Erlang/OTP 20, atoms can contain any Unicode character
411 and atom_to_binary(Atom, latin1) may fail if the text represen‐
412 tation for Atom contains a Unicode character > 255.
413 Example:
416 > atom_to_binary('Erlang', latin1).
418 <<"Erlang">>
419 atom_to_list(Atom) -> string()
421 Types:
423 Atom = atom()
425 Returns a list of unicode code points corresponding to the text
427 representation of Atom, for example:
428 > atom_to_list('Erlang').
430 "Erlang"
431 > atom_to_list('你好').
433 [20320,22909]
434 See unicode(3) for how to convert the resulting list to differ‐
436 ent formats.
437 binary_part(Subject, PosLen) -> binary()
439 Types:
441 Subject = binary()
443 PosLen = {Start :: integer() >= 0, Length :: integer()}
444 Extracts the part of the binary described by PosLen.
446 Negative length can be used to extract bytes at the end of a bi‐
448 nary, for example:
449 1> Bin = <<1,2,3,4,5,6,7,8,9,10>>.
451 2> binary_part(Bin,{byte_size(Bin), -5}).
452 <<6,7,8,9,10>>
453 Failure: badarg if PosLen in any way references outside the bi‐
455 nary.
456 Start is zero-based, that is:
458 1> Bin = <<1,2,3>>
460 2> binary_part(Bin,{0,2}).
461 <<1,2>>
462 For details about the PosLen semantics, see binary(3).
464 Allowed in guard tests.
466 binary_part(Subject, Start, Length) -> binary()
468 Types:
470 Subject = binary()
472 Start = integer() >= 0
473 Length = integer()
474 The same as binary_part(Subject, {Start, Length}).
476 Allowed in guard tests.
478 binary_to_atom(Binary) -> atom()
480 Types:
482 Binary = binary()
484 The same as binary_to_atom(Binary, utf8).
486 binary_to_atom(Binary, Encoding) -> atom()
488 Types:
490 Binary = binary()
492 Encoding = latin1 | unicode | utf8
493 Returns the atom whose text representation is Binary. If Encod‐
495 ing is utf8 or unicode, the binary must contain valid UTF-8 se‐
496 quences.
497 Note:
499 As from Erlang/OTP 20, binary_to_atom(Binary, utf8) is capable
500 of encoding any Unicode character. Earlier versions would fail
501 if the binary contained Unicode characters > 255. For more in‐
502 formation about Unicode support in atoms, see the note on UTF-8
503 encoded atoms in section "External Term Format" in the User's
504 Guide.
505 Note:
508 The number of characters that are permitted in an atom name is
509 limited. The default limits can be found in the efficiency
510 guide (section Advanced).
511 Note:
514 There is configurable limit on how many atoms that can exist and
515 atoms are not garbage collected. Therefore, it is recommended to
516 consider whether binary_to_existing_atom/2 is a better option
517 than binary_to_atom/2. The default limits can be found in effi‐
518 ciency guide (section Advanced).
519 Examples:
522 > binary_to_atom(<<"Erlang">>, latin1).
524 > binary_to_atom(<<1024/utf8>>, utf8).
526 binary_to_existing_atom(Binary) -> atom()
528 Types:
530 Binary = binary()
532 The same as binary_to_existing_atom (Binary, utf8).
534 binary_to_existing_atom(Binary, Encoding) -> atom()
536 Types:
538 Binary = binary()
540 Encoding = latin1 | unicode | utf8
541 As binary_to_atom/2, but the atom must exist.
543 The Erlang system has a configurable limit for the total number
545 of atoms that can exist, and atoms are not garbage collected.
546 Therefore, it is not safe to create many atoms from binaries
547 that come from an untrusted source (for example, a file fetched
548 from the Internet), for example, using binary_to_atom/2. This
549 function is thus the appropriate option when the input binary
550 comes from an untrusted source.
551 An atom exists in an Erlang system when included in a loaded Er‐
553 lang module or when created programmatically (for example, by
554 binary_to_atom/2). See the next note for an example of when an
555 atom exists in the source code for an Erlang module but not in
556 the compiled version of the same module.
557 Failure: badarg if the atom does not exist.
559 Note:
561 Note that the compiler may optimize away atoms. For example, the
562 compiler will rewrite atom_to_list(some_atom) to "some_atom". If
563 that expression is the only mention of the atom some_atom in the
564 containing module, the atom will not be created when the module
565 is loaded, and a subsequent call to binary_to_exist‐
566 ing_atom(<<"some_atom">>, utf8) will fail.
567 Note:
570 The number of characters that are permitted in an atom name is
571 limited. The default limits can be found in the efficiency
572 guide (section Advanced).
573 binary_to_float(Binary) -> float()
576 Types:
578 Binary = binary()
580 Returns the float whose text representation is Binary, for exam‐
582 ple:
583 > binary_to_float(<<"2.2017764e+0">>).
585 2.2017764
586 The float string format is the same as the format for Erlang
588 float literals except for that underscores are not permitted.
589 Failure: badarg if Binary contains a bad representation of a
591 float.
592 binary_to_integer(Binary) -> integer()
594 Types:
596 Binary = binary()
598 Returns an integer whose text representation is Binary, for ex‐
600 ample:
601 > binary_to_integer(<<"123">>).
603 123
604 binary_to_integer/1 accepts the same string formats as
606 list_to_integer/1.
607 Failure: badarg if Binary contains a bad representation of an
609 integer.
610 binary_to_integer(Binary, Base) -> integer()
612 Types:
614 Binary = binary()
616 Base = 2..36
617 Returns an integer whose text representation in base Base is Bi‐
619 nary, for example:
620 > binary_to_integer(<<"3FF">>, 16).
622 1023
623 binary_to_integer/2 accepts the same string formats as
625 list_to_integer/2.
626 Failure: badarg if Binary contains a bad representation of an
628 integer.
629 binary_to_list(Binary) -> [byte()]
631 Types:
633 Binary = binary()
635 Returns a list of integers corresponding to the bytes of Binary.
637 binary_to_list(Binary, Start, Stop) -> [byte()]
639 Types:
641 Binary = binary()
643 Start = Stop = integer() >= 1
644 1..byte_size(Binary)
645 As binary_to_list/1, but returns a list of integers correspond‐
647 ing to the bytes from position Start to position Stop in Binary.
648 The positions in the binary are numbered starting from 1.
649 Note:
651 The one-based indexing for binaries used by this function is
652 deprecated. New code is to use binary:bin_to_list/3 in STDLIB
653 instead. All functions in module binary consistently use zero-
654 based indexing.
655 binary_to_term(Binary) -> term()
658 Types:
660 Binary = ext_binary()
662 Returns an Erlang term that is the result of decoding binary ob‐
664 ject Binary, which must be encoded according to the Erlang ex‐
665 ternal term format.
666 > Bin = term_to_binary(hello).
668 <<131,100,0,5,104,101,108,108,111>>
669 > hello = binary_to_term(Bin).
670 hello
671 Warning:
674 When decoding binaries from untrusted sources, the untrusted
675 source may submit data in a way to create resources, such as
676 atoms and remote references, that cannot be garbage collected
677 and lead to Denial of Service attack. In such cases, consider
678 using binary_to_term/2 with the safe option.
679 See also term_to_binary/1 and binary_to_term/2.
682 binary_to_term(Binary, Opts) -> term() | {term(), Used}
684 Types:
686 Binary = ext_binary()
688 Opt = safe | used
689 Opts = [Opt]
690 Used = integer() >= 1
691 As binary_to_term/1, but takes these options:
693 safe:
695 Use this option when receiving binaries from an untrusted
696 source.
697 When enabled, it prevents decoding data that can be used to
699 attack the Erlang runtime. In the event of receiving unsafe
700 data, decoding fails with a badarg error.
701 This prevents creation of new atoms directly, creation of
703 new atoms indirectly (as they are embedded in certain struc‐
704 tures, such as process identifiers, refs, and funs), and
705 creation of new external function references. None of those
706 resources are garbage collected, so unchecked creation of
707 them can exhaust available memory.
708 > binary_to_term(<<131,100,0,5,"hello">>, [safe]).
710 ** exception error: bad argument
711 > hello.
712 hello
713 > binary_to_term(<<131,100,0,5,"hello">>, [safe]).
714 hello
715 Warning:
718 The safe option ensures the data is safely processed by the
719 Erlang runtime but it does not guarantee the data is safe to
720 your application. You must always validate data from untrusted
721 sources. If the binary is stored or transits through untrusted
722 sources, you should also consider cryptographically signing
723 it.
724 used:
727 Changes the return value to {Term, Used} where Used is the
728 number of bytes actually read from Binary.
729 > Input = <<131,100,0,5,"hello","world">>.
731 <<131,100,0,5,104,101,108,108,111,119,111,114,108,100>>
732 > {Term, Used} = binary_to_term(Input, [used]).
733 {hello, 9}
734 > split_binary(Input, Used).
735 {<<131,100,0,5,104,101,108,108,111>>, <<"world">>}
736 Failure: badarg if safe is specified and unsafe data is decoded.
739 See also term_to_binary/1, binary_to_term/1, and list_to_exist‐
741 ing_atom/1.
742 bit_size(Bitstring) -> integer() >= 0
744 Types:
746 Bitstring = bitstring()
748 Returns an integer that is the size in bits of Bitstring, for
750 example:
751 > bit_size(<<433:16,3:3>>).
753 19
754 > bit_size(<<1,2,3>>).
755 24
756 Allowed in guard tests.
758 bitstring_to_list(Bitstring) -> [byte() | bitstring()]
760 Types:
762 Bitstring = bitstring()
764 Returns a list of integers corresponding to the bytes of Bit‐
766 string. If the number of bits in the binary is not divisible by
767 8, the last element of the list is a bitstring containing the
768 remaining 1-7 bits. Examples:
769 > bitstring_to_list(<<433:16>>).
771 [1,177]
772 > bitstring_to_list(<<433:16,3:3>>).
774 [1,177,<<3:3>>]
775 erlang:bump_reductions(Reductions) -> true
777 Types:
779 Reductions = integer() >= 1
781 This implementation-dependent function increments the reduction
783 counter for the calling process. In the Beam emulator, the re‐
784 duction counter is normally incremented by one for each function
785 and BIF call. A context switch is forced when the counter
786 reaches the maximum number of reductions for a process (4000 re‐
787 ductions in Erlang/OTP 19.2 and later).
788 Warning:
790 This BIF can be removed in a future version of the Beam machine
791 without prior warning. It is unlikely to be implemented in other
792 Erlang implementations.
793 byte_size(Bitstring) -> integer() >= 0
796 Types:
798 Bitstring = bitstring()
800 Returns an integer that is the number of bytes needed to contain
802 Bitstring. That is, if the number of bits in Bitstring is not
803 divisible by 8, the resulting number of bytes is rounded up. Ex‐
804 amples:
805 > byte_size(<<433:16,3:3>>).
807 3
808 > byte_size(<<1,2,3>>).
809 3
810 Allowed in guard tests.
812 erlang:cancel_timer(TimerRef) -> Result
814 Types:
816 TimerRef = reference()
818 Time = integer() >= 0
819 Result = Time | false
820 Cancels a timer. The same as calling erlang:cancel_timer(Timer‐
822 Ref, []).
823 erlang:cancel_timer(TimerRef, Options) -> Result | ok
825 Types:
827 TimerRef = reference()
829 Async = Info = boolean()
830 Option = {async, Async} | {info, Info}
831 Options = [Option]
832 Time = integer() >= 0
833 Result = Time | false
834 Cancels a timer that has been created by erlang:start_timer or
836 erlang:send_after. TimerRef identifies the timer, and was re‐
837 turned by the BIF that created the timer.
838 Options:
840 {async, Async}:
842 Asynchronous request for cancellation. Async defaults to
843 false, which causes the cancellation to be performed syn‐
844 chronously. When Async is set to true, the cancel operation
845 is performed asynchronously. That is, cancel_timer() sends
846 an asynchronous request for cancellation to the timer ser‐
847 vice that manages the timer, and then returns ok.
848 {info, Info}:
850 Requests information about the Result of the cancellation.
851 Info defaults to true, which means the Result is given. When
852 Info is set to false, no information about the result of the
853 cancellation is given.
854 * When Async is false: if Info is true, the Result is re‐
856 turned by erlang:cancel_timer(). otherwise ok is returned.
857 * When Async is true: if Info is true, a message on the form
859 {cancel_timer, TimerRef, Result} is sent to the caller of
860 erlang:cancel_timer() when the cancellation operation has
861 been performed, otherwise no message is sent.
862 More Options may be added in the future.
864 If Result is an integer, it represents the time in milliseconds
866 left until the canceled timer would have expired.
867 If Result is false, a timer corresponding to TimerRef could not
869 be found. This can be either because the timer had expired, al‐
870 ready had been canceled, or because TimerRef never corresponded
871 to a timer. Even if the timer had expired, it does not tell you
872 if the time-out message has arrived at its destination yet.
873 Note:
875 The timer service that manages the timer can be co-located with
876 another scheduler than the scheduler that the calling process is
877 executing on. If so, communication with the timer service takes
878 much longer time than if it is located locally. If the calling
879 process is in critical path, and can do other things while wait‐
880 ing for the result of this operation, or is not interested in
881 the result of the operation, you want to use option {async,
882 true}. If using option {async, false}, the calling process
883 blocks until the operation has been performed.
884 See also erlang:send_after/4, erlang:start_timer/4, and er‐
887 lang:read_timer/2.
888 ceil(Number) -> integer()
890 Types:
892 Number = number()
894 Returns the smallest integer not less than Number. For example:
896 > ceil(5.5).
898 6
899 Allowed in guard tests.
901 check_old_code(Module) -> boolean()
903 Types:
905 Module = module()
907 Returns true if Module has old code, otherwise false.
909 See also code(3).
911 check_process_code(Pid, Module) -> CheckResult
913 Types:
915 Pid = pid()
917 Module = module()
918 CheckResult = boolean()
919 The same as check_process_code(Pid, Module, []).
921 check_process_code(Pid, Module, OptionList) -> CheckResult | async
923 Types:
925 Pid = pid()
927 Module = module()
928 RequestId = term()
929 Option = {async, RequestId} | {allow_gc, boolean()}
930 OptionList = [Option]
931 CheckResult = boolean() | aborted
932 Checks if the node local process identified by Pid executes old
934 code for Module.
935 Options:
937 {allow_gc, boolean()}:
939 Determines if garbage collection is allowed when performing
940 the operation. If {allow_gc, false} is passed, and a garbage
941 collection is needed to determine the result of the opera‐
942 tion, the operation is aborted (see information on CheckRe‐
943 sult below). The default is to allow garbage collection,
944 that is, {allow_gc, true}.
945 {async, RequestId}:
947 The function check_process_code/3 returns the value async
948 immediately after the request has been sent. When the re‐
949 quest has been processed, the process that called this func‐
950 tion is passed a message on the form {check_process_code,
951 RequestId, CheckResult}.
952 If Pid equals self(), and no async option has been passed, the
954 operation is performed at once. Otherwise a request for the op‐
955 eration is sent to the process identified by Pid, and is handled
956 when appropriate. If no async option has been passed, the caller
957 blocks until CheckResult is available and can be returned.
958 CheckResult informs about the result of the request as follows:
960 true:
962 The process identified by Pid executes old code for Module.
963 That is, the current call of the process executes old code
964 for this module, or the process has references to old code
965 for this module, or the process contains funs that refer‐
966 ences old code for this module.
967 false:
969 The process identified by Pid does not execute old code for
970 Module.
971 aborted:
973 The operation was aborted, as the process needed to be
974 garbage collected to determine the operation result, and the
975 operation was requested by passing option {allow_gc, false}.
976 Note:
978 Up until ERTS version 8.*, the check process code operation
979 checks for all types of references to the old code. That is, di‐
980 rect references (e.g. return addresses on the process stack),
981 indirect references (funs in process context), and references to
982 literals in the code.
983 As of ERTS version 9.0, the check process code operation only
985 checks for direct references to the code. Indirect references
986 via funs will be ignored. If such funs exist and are used after
987 a purge of the old code, an exception will be raised upon usage
988 (same as the case when the fun is received by the process after
989 the purge). Literals will be taken care of (copied) at a later
990 stage. This behavior can as of ERTS version 8.1 be enabled when
991 building OTP, and will automatically be enabled if dirty sched‐
992 uler support is enabled.
993 See also code(3).
996 Failures:
998 badarg:
1000 If Pid is not a node local process identifier.
1001 badarg:
1003 If Module is not an atom.
1004 badarg:
1006 If OptionList is an invalid list of options.
1007 erlang:convert_time_unit(Time, FromUnit, ToUnit) -> ConvertedTime
1009 Types:
1011 Time = ConvertedTime = integer()
1013 FromUnit = ToUnit = time_unit()
1014 Converts the Time value of time unit FromUnit to the correspond‐
1016 ing ConvertedTime value of time unit ToUnit. The result is
1017 rounded using the floor function.
1018 Warning:
1020 You can lose accuracy and precision when converting between time
1021 units. To minimize such loss, collect all data at native time
1022 unit and do the conversion on the end result.
1023 erlang:crc32(Data) -> integer() >= 0
1026 Types:
1028 Data = iodata()
1030 Computes and returns the crc32 (IEEE 802.3 style) checksum for
1032 Data.
1033 erlang:crc32(OldCrc, Data) -> integer() >= 0
1035 Types:
1037 OldCrc = integer() >= 0
1039 Data = iodata()
1040 Continues computing the crc32 checksum by combining the previous
1042 checksum, OldCrc, with the checksum of Data.
1043 The following code:
1045 X = erlang:crc32(Data1),
1047 Y = erlang:crc32(X,Data2).
1048 assigns the same value to Y as this:
1050 Y = erlang:crc32([Data1,Data2]).
1052 erlang:crc32_combine(FirstCrc, SecondCrc, SecondSize) ->
1054 integer() >= 0
1055 Types:
1057 FirstCrc = SecondCrc = SecondSize = integer() >= 0
1059 Combines two previously computed crc32 checksums. This computa‐
1061 tion requires the size of the data object for the second check‐
1062 sum to be known.
1063 The following code:
1065 Y = erlang:crc32(Data1),
1067 Z = erlang:crc32(Y,Data2).
1068 assigns the same value to Z as this:
1070 X = erlang:crc32(Data1),
1072 Y = erlang:crc32(Data2),
1073 Z = erlang:crc32_combine(X,Y,iolist_size(Data2)).
1074 date() -> Date
1076 Types:
1078 Date = calendar:date()
1080 Returns the current date as {Year, Month, Day}.
1082 The time zone and Daylight Saving Time correction depend on the
1084 underlying OS. The return value is based on the OS System Time.
1085 Example:
1086 > date().
1088 {1995,2,19}
1089 erlang:decode_packet(Type, Bin, Options) ->
1091 {ok, Packet, Rest} |
1092 {more, Length} |
1093 {error, Reason}
1094 Types:
1096 Type =
1098 raw | 0 | 1 | 2 | 4 | asn1 | cdr | sunrm | fcgi | tpkt |
1099 line | http | http_bin | httph | httph_bin
1100 Bin = binary()
1101 Options = [Opt]
1102 Opt =
1103 {packet_size, integer() >= 0} |
1104 {line_length, integer() >= 0}
1105 Packet = binary() | HttpPacket
1106 Rest = binary()
1107 Length = integer() >= 0 | undefined
1108 Reason = term()
1109 HttpPacket =
1110 HttpRequest | HttpResponse | HttpHeader | http_eoh |
1111 HttpError
1112 HttpRequest = {http_request, HttpMethod, HttpUri, HttpVer‐
1113 sion}
1114 HttpResponse =
1115 {http_response, HttpVersion, integer(), HttpString}
1116 HttpHeader =
1117 {http_header,
1118 integer(),
1119 HttpField,
1120 UnmodifiedField :: HttpString,
1121 Value :: HttpString}
1122 HttpError = {http_error, HttpString}
1123 HttpMethod =
1124 'OPTIONS' | 'GET' | 'HEAD' | 'POST' | 'PUT' | 'DELETE' |
1125 'TRACE' | HttpString
1126 HttpUri =
1127 '*' |
1128 {absoluteURI,
1129 http | https,
1130 Host :: HttpString,
1131 Port :: inet:port_number() | undefined,
1132 Path :: HttpString} |
1133 {scheme, Scheme :: HttpString, HttpString} |
1134 {abs_path, HttpString} |
1135 HttpString
1136 HttpVersion =
1137 {Major :: integer() >= 0, Minor :: integer() >= 0}
1138 HttpField =
1139 'Cache-Control' | 'Connection' | 'Date' | 'Pragma' |
1140 'Transfer-Encoding' | 'Upgrade' | 'Via' | 'Accept' |
1141 'Accept-Charset' | 'Accept-Encoding' | 'Accept-Language'
1142 |
1143 'Authorization' | 'From' | 'Host' | 'If-Modified-Since' |
1144 'If-Match' | 'If-None-Match' | 'If-Range' |
1145 'If-Unmodified-Since' | 'Max-Forwards' |
1146 'Proxy-Authorization' | 'Range' | 'Referer' | 'User-
1147 Agent' |
1148 'Age' | 'Location' | 'Proxy-Authenticate' | 'Public' |
1149 'Retry-After' | 'Server' | 'Vary' | 'Warning' |
1150 'Www-Authenticate' | 'Allow' | 'Content-Base' |
1151 'Content-Encoding' | 'Content-Language' | 'Content-
1152 Length' |
1153 'Content-Location' | 'Content-Md5' | 'Content-Range' |
1154 'Content-Type' | 'Etag' | 'Expires' | 'Last-Modified' |
1155 'Accept-Ranges' | 'Set-Cookie' | 'Set-Cookie2' |
1156 'X-Forwarded-For' | 'Cookie' | 'Keep-Alive' |
1157 'Proxy-Connection' | HttpString
1158 HttpString = string() | binary()
1159 Decodes the binary Bin according to the packet protocol speci‐
1161 fied by Type. Similar to the packet handling done by sockets
1162 with option {packet,Type}.
1163 If an entire packet is contained in Bin, it is returned together
1165 with the remainder of the binary as {ok,Packet,Rest}.
1166 If Bin does not contain the entire packet, {more,Length} is re‐
1168 turned. Length is either the expected total size of the packet,
1169 or undefined if the expected packet size is unknown. de‐
1170 code_packet can then be called again with more data added.
1171 If the packet does not conform to the protocol format, {er‐
1173 ror,Reason} is returned.
1174 Types:
1176 raw | 0:
1178 No packet handling is done. The entire binary is returned
1179 unless it is empty.
1180 1 | 2 | 4:
1182 Packets consist of a header specifying the number of bytes
1183 in the packet, followed by that number of bytes. The length
1184 of the header can be one, two, or four bytes; the order of
1185 the bytes is big-endian. The header is stripped off when the
1186 packet is returned.
1187 line:
1189 A packet is a line-terminated by a delimiter byte, default
1190 is the latin-1 newline character. The delimiter byte is in‐
1191 cluded in the returned packet unless the line was truncated
1192 according to option line_length.
1193 asn1 | cdr | sunrm | fcgi | tpkt:
1195 The header is not stripped off.
1196 The meanings of the packet types are as follows:
1198 asn1 - ASN.1 BER:
1200 sunrm - Sun's RPC encoding:
1203 cdr - CORBA (GIOP 1.1):
1206 fcgi - Fast CGI:
1209 tpkt - TPKT format [RFC1006]:
1212 http | httph | http_bin | httph_bin:
1215 The Hypertext Transfer Protocol. The packets are returned
1216 with the format according to HttpPacket described earlier. A
1217 packet is either a request, a response, a header, or an end
1218 of header mark. Invalid lines are returned as HttpError.
1219 Recognized request methods and header fields are returned as
1221 atoms. Others are returned as strings. Strings of unrecog‐
1222 nized header fields are formatted with only capital letters
1223 first and after hyphen characters, for example, "Sec-Web‐
1224 socket-Key". Header field names are also returned in Unmodi‐
1225 fiedField as strings, without any conversion or formatting.
1226 The protocol type http is only to be used for the first line
1228 when an HttpRequest or an HttpResponse is expected. The fol‐
1229 lowing calls are to use httph to get HttpHeaders until
1230 http_eoh is returned, which marks the end of the headers and
1231 the beginning of any following message body.
1232 The variants http_bin and httph_bin return strings (Http‐
1234 String) as binaries instead of lists.
1235 Options:
1237 {packet_size, integer() >= 0}:
1239 Sets the maximum allowed size of the packet body. If the
1240 packet header indicates that the length of the packet is
1241 longer than the maximum allowed length, the packet is con‐
1242 sidered invalid. Defaults to 0, which means no size limit.
1243 {line_length, integer() >= 0}:
1245 For packet type line, lines longer than the indicated length
1246 are truncated.
1247 Option line_length also applies to http* packet types as an
1249 alias for option packet_size if packet_size itself is not
1250 set. This use is only intended for backward compatibility.
1251 {line_delimiter, 0 =< byte() =< 255}:
1253 For packet type line, sets the delimiting byte. Default is
1254 the latin-1 character $\n.
1255 Examples:
1257 > erlang:decode_packet(1,<<3,"abcd">>,[]).
1259 {ok,<<"abc">>,<<"d">>}
1260 > erlang:decode_packet(1,<<5,"abcd">>,[]).
1261 {more,6}
1262 erlang:delete_element(Index, Tuple1) -> Tuple2
1264 Types:
1266 Index = integer() >= 1
1268 1..tuple_size(Tuple1)
1269 Tuple1 = Tuple2 = tuple()
1270 Returns a new tuple with element at Index removed from tuple Tu‐
1272 ple1, for example:
1273 > erlang:delete_element(2, {one, two, three}).
1275 {one,three}
1276 delete_module(Module) -> true | undefined
1278 Types:
1280 Module = module()
1282 Makes the current code for Module become old code and deletes
1284 all references for this module from the export table. Returns
1285 undefined if the module does not exist, otherwise true.
1286 Warning:
1288 This BIF is intended for the code server (see code(3)) and is
1289 not to be used elsewhere.
1290 Failure: badarg if there already is an old version of Module.
1293 demonitor(MonitorRef) -> true
1295 Types:
1297 MonitorRef = reference()
1299 If MonitorRef is a reference that the calling process obtained
1301 by calling monitor/2, this monitoring is turned off. If the mon‐
1302 itoring is already turned off, nothing happens.
1303 Once demonitor(MonitorRef) has returned, it is guaranteed that
1305 no {'DOWN', MonitorRef, _, _, _} message, because of the moni‐
1306 tor, will be placed in the caller message queue in the future.
1307 However, a {'DOWN', MonitorRef, _, _, _} message can have been
1308 placed in the caller message queue before the call. It is there‐
1309 fore usually advisable to remove such a 'DOWN' message from the
1310 message queue after monitoring has been stopped. demonitor(Moni‐
1311 torRef, [flush]) can be used instead of demonitor(MonitorRef) if
1312 this cleanup is wanted.
1313 Note:
1315 Before Erlang/OTP R11B (ERTS 5.5) demonitor/1 behaved completely
1316 asynchronously, that is, the monitor was active until the "de‐
1317 monitor signal" reached the monitored entity. This had one unde‐
1318 sirable effect. You could never know when you were guaranteed
1319 not to receive a DOWN message because of the monitor.
1320 The current behavior can be viewed as two combined operations:
1322 asynchronously send a "demonitor signal" to the monitored entity
1323 and ignore any future results of the monitor.
1324 Failure: It is an error if MonitorRef refers to a monitoring
1327 started by another process. Not all such cases are cheap to
1328 check. If checking is cheap, the call fails with badarg, for ex‐
1329 ample if MonitorRef is a remote reference.
1330 demonitor(MonitorRef, OptionList) -> boolean()
1332 Types:
1334 MonitorRef = reference()
1336 OptionList = [Option]
1337 Option = flush | info
1338 The returned value is true unless info is part of OptionList.
1340 demonitor(MonitorRef, []) is equivalent to demonitor(Monitor‐
1342 Ref).
1343 Options:
1345 flush:
1347 Removes (one) {_, MonitorRef, _, _, _} message, if there is
1348 one, from the caller message queue after monitoring has been
1349 stopped.
1350 Calling demonitor(MonitorRef, [flush]) is equivalent to the
1352 following, but more efficient:
1353 demonitor(MonitorRef),
1355 receive
1356 {_, MonitorRef, _, _, _} ->
1357 true
1358 after 0 ->
1359 true
1360 end
1361 info:
1363 The returned value is one of the following:
1364 true:
1366 The monitor was found and removed. In this case, no 'DOWN'
1367 message corresponding to this monitor has been delivered
1368 and will not be delivered.
1369 false:
1371 The monitor was not found and could not be removed. This
1372 probably because someone already has placed a 'DOWN' mes‐
1373 sage corresponding to this monitor in the caller message
1374 queue.
1375 If option info is combined with option flush, false is re‐
1377 turned if a flush was needed, otherwise true.
1378 Note:
1380 More options can be added in a future release.
1381 Failures:
1384 badarg:
1386 If OptionList is not a list.
1387 badarg:
1389 If Option is an invalid option.
1390 badarg:
1392 The same failure as for demonitor/1.
1393 disconnect_node(Node) -> boolean() | ignored
1395 Types:
1397 Node = node()
1399 Forces the disconnection of a node. This appears to the node
1401 Node as if the local node has crashed. This BIF is mainly used
1402 in the Erlang network authentication protocols.
1403 Returns true if disconnection succeeds, otherwise false. If the
1405 local node is not alive, ignored is returned.
1406 Note:
1408 This function may return before nodedown messages have been de‐
1409 livered.
1410 erlang:display(Term) -> true
1413 Types:
1415 Term = term()
1417 Prints a text representation of Term on the standard output.
1419 Warning:
1421 This BIF is intended for debugging only.
1422 erlang:dist_ctrl_get_data(DHandle) -> {Size, Data} | Data | none
1425 Types:
1427 Size = integer() >= 0
1429 DHandle = dist_handle()
1430 Data = iovec()
1431 Get distribution channel data from the local node that is to be
1433 passed to the remote node. The distribution channel is identi‐
1434 fied by DHandle. If no data is available, the atom none is re‐
1435 turned. One can request to be informed by a message when more
1436 data is available by calling erlang:dist_ctrl_get_data_notifica‐
1437 tion(DHandle).
1438 The returned value when there are data available depends on the
1440 value of the get_size option configured on the distribution
1441 channel identified by DHandle. For more information see the doc‐
1442 umentation of the get_size option for the er‐
1443 lang:dist_ctrl_set_opt/3 function.
1444 Note:
1446 Only the process registered as distribution controller for the
1447 distribution channel identified by DHandle is allowed to call
1448 this function.
1449 This function is used when implementing an alternative distribu‐
1452 tion carrier using processes as distribution controllers. DHan‐
1453 dle is retrived via the callback f_handshake_complete. More in‐
1454 formation can be found in the documentation of ERTS User's Guide
1455 ➜ How to implement an Alternative Carrier for the Erlang Distri‐
1456 bution ➜ Distribution Module.
1457 erlang:dist_ctrl_get_opt(DHandle, Opt :: get_size) -> Value
1459 Types:
1461 DHandle = dist_handle()
1463 Value = boolean()
1464 Returns the value of the get_size option on the distribution
1466 channel identified by DHandle. For more information see the doc‐
1467 umentation of the get_size option for the er‐
1468 lang:dist_ctrl_set_opt/3 function.
1469 Note:
1471 Only the process registered as distribution controller for the
1472 distribution channel identified by DHandle is allowed to call
1473 this function.
1474 This function is used when implementing an alternative distribu‐
1477 tion carrier using processes as distribution controllers. DHan‐
1478 dle is retrived via the callback f_handshake_complete. More in‐
1479 formation can be found in the documentation of ERTS User's Guide
1480 ➜ How to implement an Alternative Carrier for the Erlang Distri‐
1481 bution ➜ Distribution Module.
1482 erlang:dist_ctrl_get_data_notification(DHandle) -> ok
1484 Types:
1486 DHandle = dist_handle()
1488 Request notification when more data is available to fetch using
1490 erlang:dist_ctrl_get_data(DHandle) for the distribution channel
1491 identified by DHandle. When more data is present, the caller
1492 will be sent the message dist_data. Once a dist_data messages
1493 has been sent, no more dist_data messages will be sent until the
1494 dist_ctrl_get_data_notification/1 function has been called
1495 again.
1496 Note:
1498 Only the process registered as distribution controller for the
1499 distribution channel identified by DHandle is allowed to call
1500 this function.
1501 This function is used when implementing an alternative distribu‐
1504 tion carrier using processes as distribution controllers. DHan‐
1505 dle is retrived via the callback f_handshake_complete. More in‐
1506 formation can be found in the documentation of ERTS User's Guide
1507 ➜ How to implement an Alternative Carrier for the Erlang Distri‐
1508 bution ➜ Distribution Module.
1509 erlang:dist_ctrl_input_handler(DHandle, InputHandler) -> ok
1511 Types:
1513 DHandle = dist_handle()
1515 InputHandler = pid()
1516 Register an alternate input handler process for the distribution
1518 channel identified by DHandle. Once this function has been
1519 called, InputHandler is the only process allowed to call er‐
1520 lang:dist_ctrl_put_data(DHandle, Data) with the DHandle identi‐
1521 fing this distribution channel.
1522 Note:
1524 Only the process registered as distribution controller for the
1525 distribution channel identified by DHandle is allowed to call
1526 this function.
1527 This function is used when implementing an alternative distribu‐
1530 tion carrier using processes as distribution controllers. DHan‐
1531 dle is retrived via the callback f_handshake_complete. More in‐
1532 formation can be found in the documentation of ERTS User's Guide
1533 ➜ How to implement an Alternative Carrier for the Erlang Distri‐
1534 bution ➜ Distribution Module.
1535 erlang:dist_ctrl_put_data(DHandle, Data) -> ok
1537 Types:
1539 DHandle = dist_handle()
1541 Data = iodata()
1542 Deliver distribution channel data from a remote node to the lo‐
1544 cal node.
1545 Note:
1547 Only the process registered as distribution controller for the
1548 distribution channel identified by DHandle is allowed to call
1549 this function unless an alternate input handler process has been
1550 registered using erlang:dist_ctrl_input_handler(DHandle, In‐
1551 putHandler). If an alternate input handler has been registered,
1552 only the registered input handler process is allowed to call
1553 this function.
1554 This function is used when implementing an alternative distribu‐
1557 tion carrier using processes as distribution controllers. DHan‐
1558 dle is retrived via the callback f_handshake_complete. More in‐
1559 formation can be found in the documentation of ERTS User's Guide
1560 ➜ How to implement an Alternative Carrier for the Erlang Distri‐
1561 bution ➜ Distribution Module.
1562 erlang:dist_ctrl_set_opt(DHandle, Opt :: get_size, Value) ->
1564 OldValue
1565 Types:
1567 DHandle = dist_handle()
1569 Value = OldValue = boolean()
1570 Sets the value of the get_size option on the distribution chan‐
1572 nel identified by DHandle. This option controls the return value
1573 of calls to erlang:dist_ctrl_get_data(DHandle) where DHandle
1574 equals DHandle used when setting this option. When the get_size
1575 option is:
1576 false:
1578 and there are distribution data available, a call to er‐
1579 lang:dist_ctrl_get_data(DHandle) will just return Data to
1580 pass over the channel. This is the default value of the
1581 get_size option.
1582 true:
1584 and there are distribution data available, a call to er‐
1585 lang:dist_ctrl_get_data(DHandle) will return Data to pass
1586 over the channel as well as the Size of Data in bytes. This
1587 is returned as a tuple on the form {Size, Data}.
1588 All options are set to default when a channel is closed.
1590 Note:
1592 Only the process registered as distribution controller for the
1593 distribution channel identified by DHandle is allowed to call
1594 this function.
1595 This function is used when implementing an alternative distribu‐
1598 tion carrier using processes as distribution controllers. DHan‐
1599 dle is retrived via the callback f_handshake_complete. More in‐
1600 formation can be found in the documentation of ERTS User's Guide
1601 ➜ How to implement an Alternative Carrier for the Erlang Distri‐
1602 bution ➜ Distribution Module.
1603 element(N, Tuple) -> term()
1605 Types:
1607 N = integer() >= 1
1609 1..tuple_size(Tuple)
1610 Tuple = tuple()
1611 Returns the Nth element (numbering from 1) of Tuple, for exam‐
1613 ple:
1614 > element(2, {a, b, c}).
1616 b
1617 Allowed in guard tests.
1619 erase() -> [{Key, Val}]
1621 Types:
1623 Key = Val = term()
1625 Returns the process dictionary and deletes it, for example:
1627 > put(key1, {1, 2, 3}),
1629 put(key2, [a, b, c]),
1630 erase().
1631 [{key1,{1,2,3}},{key2,[a,b,c]}]
1632 erase(Key) -> Val | undefined
1634 Types:
1636 Key = Val = term()
1638 Returns the value Val associated with Key and deletes it from
1640 the process dictionary. Returns undefined if no value is associ‐
1641 ated with Key. The average time complexity for the current im‐
1642 plementation of this function is O(1) and the worst case time
1643 complexity is O(N), where N is the number of items in the
1644 process dictionary. Example:
1645 > put(key1, {merry, lambs, are, playing}),
1647 X = erase(key1),
1648 {X, erase(key1)}.
1649 {{merry,lambs,are,playing},undefined}
1650 error(Reason) -> no_return()
1652 Types:
1654 Reason = term()
1656 Raises an exception of class error with the reason Reason. As
1658 evaluating this function causes an exception to be thrown, it
1659 has no return value.
1660 The intent of the exception class error is to signal that an un‐
1662 expected error has happened (for example, a function is called
1663 with a parameter that has an incorrect type). See the guide
1664 about errors and error handling for additional information. Ex‐
1665 ample:
1666 > catch error(foobar).
1668 {'EXIT',{foobar,[{shell,apply_fun,3,
1669 [{file,"shell.erl"},{line,906}]},
1670 {erl_eval,do_apply,6,[{file,"erl_eval.erl"},{line,677}]},
1671 {erl_eval,expr,5,[{file,"erl_eval.erl"},{line,430}]},
1672 {shell,exprs,7,[{file,"shell.erl"},{line,687}]},
1673 {shell,eval_exprs,7,[{file,"shell.erl"},{line,642}]},
1674 {shell,eval_loop,3,[{file,"shell.erl"},{line,627}]}]}}
1675 error(Reason, Args) -> no_return()
1678 Types:
1680 Reason = term()
1682 Args = [term()] | none
1683 Raises an exception of class error with the reason Reason. Args
1685 is expected to be the list of arguments for the current function
1686 or the atom none. If it is a list, it is used to provide the ar‐
1687 guments for the current function in the stack back-trace. If it
1688 is none, the arity of the calling function is used in the stack‐
1689 trace. As evaluating this function causes an exception to be
1690 raised, it has no return value.
1691 The intent of the exception class error is to signal that an un‐
1693 expected error has happened (for example, a function is called
1694 with a parameter that has an incorrect type). See the guide
1695 about errors and error handling for additional information. Ex‐
1696 ample:
1697 test.erl:
1699 -module(test).
1701 -export([example_fun/2]).
1702 example_fun(A1, A2) ->
1704 erlang:error(my_error, [A1, A2]).
1705 Erlang shell:
1708 6> c(test).
1710 {ok,test}
1711 7> test:example_fun(arg1,"this is the second argument").
1712 ** exception error: my_error
1713 in function test:example_fun/2
1714 called as test:example_fun(arg1,"this is the second argument")
1715 error(Reason, Args, Options) -> no_return()
1718 Types:
1720 Reason = term()
1722 Args = [term()] | none
1723 Options = [Option]
1724 Option = {error_info, ErrorInfoMap}
1725 ErrorInfoMap =
1726 #{cause => term(), module => module(), function =>
1727 atom()}
1728 Raises an exception of class error with the reason Reason. Args
1730 is expected to be the list of arguments for the current function
1731 or the atom none. If it is a list, it is used to provide the ar‐
1732 guments for the current function in the stack back-trace. If it
1733 is none, the arity of the calling function is used in the stack‐
1734 trace. As evaluating this function causes an exception to be
1735 raised, it has no return value.
1736 If the error_info option is given, the ErrorInfoMap will be in‐
1738 serted into the stacktrace. The information given in the Error‐
1739 InfoMap is to be used by error formatters such as erl_error to
1740 provide more context around an error.
1741 The default module of the ErrorInfoMap is the module that the
1743 call to error/3 is made. The default function is format_error.
1744 See format_error/2 for more details on how this Module:Func‐
1745 tion/2 is to be used
1746 The intent of the exception class error is to signal that an un‐
1748 expected error has happened (for example, a function is called
1749 with a parameter that has an incorrect type). See the guide
1750 about errors and error handling for additional information.
1751 exit(Reason) -> no_return()
1753 Types:
1755 Reason = term()
1757 Raises an exception of class exit with exit reason Reason. As
1759 evaluating this function causes an exception to be raised, it
1760 has no return value.
1761 The intent of the exception class exit is that the current
1763 process should be stopped (for example when a message telling a
1764 process to stop is received).
1765 This function differ from error/1,2,3 by causing an exception of
1767 a different class and by having a reason that does not include
1768 the list of functions from the call stack.
1769 See the guide about errors and error handling for additional in‐
1771 formation.
1772 Example:
1774 > exit(foobar).
1776 ** exception exit: foobar
1777 > catch exit(foobar).
1778 {'EXIT',foobar}
1779 Note:
1781 If a process calls exit(kill) and does not catch the exception,
1782 it will terminate with exit reason kill and also emit exit sig‐
1783 nals with exit reason kill (not killed) to all linked processes.
1784 Such exit signals with exit reason kill can be trapped by the
1785 linked processes. Note that this means that signals with exit
1786 reason kill behave differently depending on how they are sent
1787 because the signal will be untrappable if a process sends such a
1788 signal to another process with erlang:exit/2.
1789 exit(Pid, Reason) -> true
1792 Types:
1794 Pid = pid() | port()
1796 Reason = term()
1797 Sends an exit signal with exit reason Reason to the process or
1799 port identified by Pid.
1800 The following behavior applies if Reason is any term, except
1802 normal or kill, and P is the process or port identified by Pid:
1803 * If P is not trapping exits, P exits with exit reason Reason.
1805 * If P is trapping exits, the exit signal is transformed into
1807 a message {'EXIT', From, Reason}, where From is the process
1808 identifier of the process that sent the exit signal, and de‐
1809 livered to the message queue of P.
1810 The following behavior applies if Reason is the term normal and
1812 Pid is the identifier of a process P which is not the same as
1813 the process that invoked erlang:exit(Pid, normal) (the behavior
1814 when a process sends a signal with the normal reason to itself
1815 is described in the warning):
1816 * If P is trapping exits, the exit signal is transformed into
1818 a message {'EXIT', From, normal}, where From is the process
1819 identifier of the process that sent the exit signal, and de‐
1820 livered to P's message queue.
1821 * The signal has no effect if P is not trapping exits.
1823 If Reason is the atom kill, that is, if exit(Pid, kill) is
1825 called, an untrappable exit signal is sent to the process that
1826 is identified by Pid, which unconditionally exits with exit rea‐
1827 son killed. The exit reason is changed from kill to killed to
1828 hint to linked processes that the killed process got killed by a
1829 call to exit(Pid, kill).
1830 Note:
1832 The functions erlang:exit/1 and erlang:exit/2 are named simi‐
1833 larly but provide very different functionalities. The er‐
1834 lang:exit/1 function should be used when the intent is to stop
1835 the current process while erlang:exit/2 should be used when the
1836 intent is to send an exit signal to another process. Note also
1837 that erlang:exit/1 raises an exception that can be caught while
1838 erlang:exit/2 does not cause any exception to be raised.
1839 Warning:
1842 The only scenario that has not been covered by the description
1843 above is when a process P sends an exit signal with reason nor‐
1844 mal to itself, that is erlang:exit(self(), normal). The behavior
1845 in this scenario is as follows:
1846 * If P is trapping exits, the exit signal is transformed into
1848 a message {'EXIT', From, normal}, where From is P's process
1849 identifier, and delivered to P's message queue.
1850 * P exits with reason normal if P is not trapping exits.
1852 Note that the behavior described above is different from when a
1854 process sends an exit signal with reason normal to another
1855 process. This is arguably strange but this behavior is kept for
1856 backward compatibility reasons.
1857 erlang:external_size(Term) -> integer() >= 0
1860 Types:
1862 Term = term()
1864 Calculates, without doing the encoding, the maximum byte size
1866 for a term encoded in the Erlang external term format. The fol‐
1867 lowing condition applies always:
1868 > Size1 = byte_size(term_to_binary(Term)),
1870 > Size2 = erlang:external_size(Term),
1871 > true = Size1 =< Size2.
1872 true
1873 This is equivalent to a call to:
1875 erlang:external_size(Term, [])
1877 erlang:external_size(Term, Options) -> integer() >= 0
1879 Types:
1881 Term = term()
1883 Options = [{minor_version, Version :: integer() >= 0}]
1884 Calculates, without doing the encoding, the maximum byte size
1886 for a term encoded in the Erlang external term format. The fol‐
1887 lowing condition applies always:
1888 > Size1 = byte_size(term_to_binary(Term, Options)),
1890 > Size2 = erlang:external_size(Term, Options),
1891 > true = Size1 =< Size2.
1892 true
1893 Option {minor_version, Version} specifies how floats are en‐
1895 coded. For a detailed description, see term_to_binary/2.
1896 float(Number) -> float()
1898 Types:
1900 Number = number()
1902 Returns a float by converting Number to a float, for example:
1904 > float(55).
1906 55.0
1907 Allowed in guard tests.
1909 Note:
1911 If used on the top level in a guard, it tests whether the argu‐
1912 ment is a floating point number; for clarity, use is_float/1 in‐
1913 stead.
1914 When float/1 is used in an expression in a guard, such as
1916 'float(A) == 4.0', it converts a number as described earlier.
1917 float_to_binary(Float) -> binary()
1920 Types:
1922 Float = float()
1924 The same as float_to_binary(Float,[{scientific,20}]).
1926 float_to_binary(Float, Options) -> binary()
1928 Types:
1930 Float = float()
1932 Options = [Option]
1933 Option =
1934 {decimals, Decimals :: 0..253} |
1935 {scientific, Decimals :: 0..249} |
1936 compact
1937 Returns a binary corresponding to the text representation of
1939 Float using fixed decimal point formatting. Options behaves in
1940 the same way as float_to_list/2. Examples:
1941 > float_to_binary(7.12, [{decimals, 4}]).
1943 <<"7.1200">>
1944 > float_to_binary(7.12, [{decimals, 4}, compact]).
1945 <<"7.12">>
1946 > float_to_binary(7.12, [{scientific, 3}]).
1947 <<"7.120e+00">>
1948 float_to_list(Float) -> string()
1950 Types:
1952 Float = float()
1954 The same as float_to_list(Float,[{scientific,20}]).
1956 float_to_list(Float, Options) -> string()
1958 Types:
1960 Float = float()
1962 Options = [Option]
1963 Option =
1964 {decimals, Decimals :: 0..253} |
1965 {scientific, Decimals :: 0..249} |
1966 compact
1967 Returns a string corresponding to the text representation of
1969 Float using fixed decimal point formatting.
1970 Available options:
1972 * If option decimals is specified, the returned value contains
1974 at most Decimals number of digits past the decimal point. If
1975 the number does not fit in the internal static buffer of 256
1976 bytes, the function throws badarg.
1977 * If option compact is specified, the trailing zeros at the
1979 end of the list are truncated. This option is only meaning‐
1980 ful together with option decimals.
1981 * If option scientific is specified, the float is formatted
1983 using scientific notation with Decimals digits of precision.
1984 * If Options is [], the function behaves as float_to_list/1.
1986 Examples:
1988 > float_to_list(7.12, [{decimals, 4}]).
1990 "7.1200"
1991 > float_to_list(7.12, [{decimals, 4}, compact]).
1992 "7.12"
1993 > float_to_list(7.12, [{scientific, 3}]).
1994 "7.120e+00"
1995 > float_to_list(0.1+0.2)
1996 "3.00000000000000044409e-01"
1997 In the last example, float_to_list(0.1+0.2) evaluates to
2000 "3.00000000000000044409e-01". The reason for this is explained
2001 in Representation of Floating Point Numbers.
2002 floor(Number) -> integer()
2004 Types:
2006 Number = number()
2008 Returns the largest integer not greater than Number. For exam‐
2010 ple:
2011 > floor(-10.5).
2013 -11
2014 Allowed in guard tests.
2016 erlang:fun_info(Fun) -> [{Item, Info}]
2018 Types:
2020 Fun = function()
2022 Item =
2023 arity | env | index | name | module | new_index |
2024 new_uniq |
2025 pid | type | uniq
2026 Info = term()
2027 Returns a list with information about the fun Fun. Each list el‐
2029 ement is a tuple. The order of the tuples is undefined, and more
2030 tuples can be added in a future release.
2031 Warning:
2033 This BIF is mainly intended for debugging, but it can sometimes
2034 be useful in library functions that need to verify, for example,
2035 the arity of a fun.
2036 Two types of funs have slightly different semantics:
2039 * A fun created by fun M:F/A is called an external fun. Call‐
2041 ing it will always call the function F with arity A in the
2042 latest code for module M. Notice that module M does not even
2043 need to be loaded when the fun fun M:F/A is created.
2044 * All other funs are called local. When a local fun is called,
2046 the same version of the code that created the fun is called
2047 (even if a newer version of the module has been loaded).
2048 The following elements are always present in the list for both
2050 local and external funs:
2051 {type, Type}:
2053 Type is local or external.
2054 {module, Module}:
2056 Module (an atom) is the module name.
2057 If Fun is a local fun, Module is the module in which the fun
2059 is defined.
2060 If Fun is an external fun, Module is the module that the fun
2062 refers to.
2063 {name, Name}:
2065 Name (an atom) is a function name.
2066 If Fun is a local fun, Name is the name of the local func‐
2068 tion that implements the fun. (This name was generated by
2069 the compiler, and is only of informational use. As it is a
2070 local function, it cannot be called directly.) If no code is
2071 currently loaded for the fun, [] is returned instead of an
2072 atom.
2073 If Fun is an external fun, Name is the name of the exported
2075 function that the fun refers to.
2076 {arity, Arity}:
2078 Arity is the number of arguments that the fun is to be
2079 called with.
2080 {env, Env}:
2082 Env (a list) is the environment or free variables for the
2083 fun. For external funs, the returned list is always empty.
2084 The following elements are only present in the list if Fun is
2086 local:
2087 {pid, Pid}:
2089 Pid is the process identifier of the process that originally
2090 created the fun.
2091 It might point to the init process if the Fun was statically
2093 allocated when module was loaded (this optimisation is per‐
2094 formed for local functions that do not capture the environ‐
2095 ment).
2096 {index, Index}:
2098 Index (an integer) is an index into the module fun table.
2099 {new_index, Index}:
2101 Index (an integer) is an index into the module fun table.
2102 {new_uniq, Uniq}:
2104 Uniq (a binary) is a unique value for this fun. It is calcu‐
2105 lated from the compiled code for the entire module.
2106 {uniq, Uniq}:
2108 Uniq (an integer) is a unique value for this fun. As from
2109 Erlang/OTP R15, this integer is calculated from the compiled
2110 code for the entire module. Before Erlang/OTP R15, this in‐
2111 teger was based on only the body of the fun.
2112 erlang:fun_info(Fun, Item) -> {Item, Info}
2114 Types:
2116 Fun = function()
2118 Item = fun_info_item()
2119 Info = term()
2120 fun_info_item() =
2121 arity | env | index | name | module | new_index | new_uniq |
2122 pid | type | uniq
2123 Returns information about Fun as specified by Item, in the form
2125 {Item,Info}.
2126 For any fun, Item can be any of the atoms module, name, arity,
2128 env, or type.
2129 For a local fun, Item can also be any of the atoms index,
2131 new_index, new_uniq, uniq, and pid. For an external fun, the
2132 value of any of these items is always the atom undefined.
2133 See erlang:fun_info/1.
2135 erlang:fun_to_list(Fun) -> String :: string()
2137 Types:
2139 Fun = function()
2141 Returns String that represents the code that created Fun.
2143 String has the following form, if Fun was created by a fun ex‐
2145 pression of the form fun ModuleName:FuncName/Arity:
2146 "fun ModuleName:FuncName/Arity"
2148 The form of String when Fun is created from other types of fun
2150 expressions differs depending on if the fun expression was exe‐
2151 cuted while executing compiled code or if the fun expression was
2152 executed while executing uncompiled code (uncompiled escripts,
2153 the Erlang shell, and other code executed by the erl_eval mod‐
2154 ule):
2155 compiled code:
2157 "#Fun<M.I.U>", where M, I and U correspond to the values
2158 named module, index and uniq in the result of er‐
2159 lang:fun_info(Fun).
2160 uncompiled code:
2162 All funs created from fun expressions in uncompiled code
2163 with the same arity are mapped to the same list by
2164 fun_to_list/1.
2165 Note:
2167 Generally, one can not use fun_to_list/1 to check if two funs
2168 are equal as fun_to_list/1 does not take the fun's environment
2169 into account. See erlang:fun_info/1 for how to get the environ‐
2170 ment of a fun.
2171 Note:
2174 The output of fun_to_list/1 can differ between Erlang implemen‐
2175 tations and may change in future versions.
2176 Examples:
2179 -module(test).
2181 -export([add/1, add2/0, fun_tuple/0]).
2182 add(A) -> fun(B) -> A + B end.
2183 add2() -> fun add/1.
2184 fun_tuple() -> {fun() -> 1 end, fun() -> 1 end}.
2185 > {fun test:add/1, test:add2()}.
2188 {fun test:add/1,#Fun<test.1.107738983>}
2189 Explanation: fun test:add/1 is upgradable but test:add2() is not
2192 upgradable.
2193 > {test:add(1), test:add(42)}.
2195 {#Fun<test.0.107738983>,#Fun<test.0.107738983>}
2196 Explanation: test:add(1) and test:add(42) has the same string
2199 representation as the environment is not taken into account.
2200 >test:fun_tuple().
2202 {#Fun<test.2.107738983>,#Fun<test.3.107738983>}
2203 Explanation: The string representations differ because the funs
2206 come from different fun experssions.
2207 > {fun() -> 1 end, fun() -> 1 end}. >
2209 {#Fun<erl_eval.45.97283095>,#Fun<erl_eval.45.97283095>}
2210 Explanation: All funs created from fun expressions of this form
2213 in uncompiled code with the same arity are mapped to the same
2214 list by fun_to_list/1.
2215 erlang:function_exported(Module, Function, Arity) -> boolean()
2217 Types:
2219 Module = module()
2221 Function = atom()
2222 Arity = arity()
2223 Returns true if the module Module is current and contains an ex‐
2225 ported function Function/Arity, or if there is a BIF (a built-in
2226 function implemented in C) with the specified name, otherwise
2227 returns false.
2228 garbage_collect() -> true
2230 Forces an immediate garbage collection of the executing process.
2232 The function is not to be used unless it has been noticed (or
2233 there are good reasons to suspect) that the spontaneous garbage
2234 collection will occur too late or not at all.
2235 Warning:
2237 Improper use can seriously degrade system performance.
2238 garbage_collect(Pid) -> GCResult
2241 Types:
2243 Pid = pid()
2245 GCResult = boolean()
2246 The same as garbage_collect(Pid, []).
2248 garbage_collect(Pid, OptionList) -> GCResult | async
2250 Types:
2252 Pid = pid()
2254 RequestId = term()
2255 Option = {async, RequestId} | {type, major | minor}
2256 OptionList = [Option]
2257 GCResult = boolean()
2258 Garbage collects the node local process identified by Pid.
2260 Option:
2262 {async, RequestId}:
2264 The function garbage_collect/2 returns the value async imme‐
2265 diately after the request has been sent. When the request
2266 has been processed, the process that called this function is
2267 passed a message on the form {garbage_collect, RequestId,
2268 GCResult}.
2269 {type, 'major' | 'minor'}:
2271 Triggers garbage collection of requested type. Default value
2272 is 'major', which would trigger a fullsweep GC. The option
2273 'minor' is considered a hint and may lead to either minor or
2274 major GC run.
2275 If Pid equals self(), and no async option has been passed, the
2277 garbage collection is performed at once, that is, the same as
2278 calling garbage_collect/0. Otherwise a request for garbage col‐
2279 lection is sent to the process identified by Pid, and will be
2280 handled when appropriate. If no async option has been passed,
2281 the caller blocks until GCResult is available and can be re‐
2282 turned.
2283 GCResult informs about the result of the garbage collection re‐
2285 quest as follows:
2286 true:
2288 The process identified by Pid has been garbage collected.
2289 false:
2291 No garbage collection was performed, as the process identi‐
2292 fied by Pid terminated before the request could be satis‐
2293 fied.
2294 Notice that the same caveats apply as for garbage_collect/0.
2296 Failures:
2298 badarg:
2300 If Pid is not a node local process identifier.
2301 badarg:
2303 If OptionList is an invalid list of options.
2304 get() -> [{Key, Val}]
2306 Types:
2308 Key = Val = term()
2310 Returns the process dictionary as a list of {Key, Val} tuples.
2312 The items in the returned list can be in any order. Example:
2313 > put(key1, merry),
2315 put(key2, lambs),
2316 put(key3, {are, playing}),
2317 get().
2318 [{key1,merry},{key2,lambs},{key3,{are,playing}}]
2319 get(Key) -> Val | undefined
2321 Types:
2323 Key = Val = term()
2325 Returns the value Val associated with Key in the process dictio‐
2327 nary, or undefined if Key does not exist. The expected time com‐
2328 plexity for the current implementation of this function is O(1)
2329 and the worst case time complexity is O(N), where N is the num‐
2330 ber of items in the process dictionary. Example:
2331 > put(key1, merry),
2333 put(key2, lambs),
2334 put({any, [valid, term]}, {are, playing}),
2335 get({any, [valid, term]}).
2336 {are,playing}
2337 erlang:get_cookie() -> Cookie | nocookie
2339 Types:
2341 Cookie = atom()
2343 Returns the magic cookie of the local node if the node is alive,
2345 otherwise the atom nocookie.
2346 erlang:get_cookie(Node) -> Cookie | nocookie
2348 Types:
2350 Node = node()
2352 Cookie = atom()
2353 Returns the magic cookie for node Node if the local node is
2355 alive, otherwise the atom nocookie.
2356 get_keys() -> [Key]
2358 Types:
2360 Key = term()
2362 Returns a list of all keys present in the process dictionary.
2364 The items in the returned list can be in any order. Example:
2365 > put(dog, {animal,1}),
2367 put(cow, {animal,2}),
2368 put(lamb, {animal,3}),
2369 get_keys().
2370 [dog,cow,lamb]
2371 get_keys(Val) -> [Key]
2373 Types:
2375 Val = Key = term()
2377 Returns a list of keys that are associated with the value Val in
2379 the process dictionary. The items in the returned list can be in
2380 any order. Example:
2381 > put(mary, {1, 2}),
2383 put(had, {1, 2}),
2384 put(a, {1, 2}),
2385 put(little, {1, 2}),
2386 put(dog, {1, 3}),
2387 put(lamb, {1, 2}),
2388 get_keys({1, 2}).
2389 [mary,had,a,little,lamb]
2390 group_leader() -> pid()
2392 Returns the process identifier of the group leader for the
2394 process evaluating the function.
2395 Every process is a member of some process group and all groups
2397 have a group leader. All I/O from the group is channeled to the
2398 group leader. When a new process is spawned, it gets the same
2399 group leader as the spawning process. Initially, at system
2400 startup, init is both its own group leader and the group leader
2401 of all processes.
2402 group_leader(GroupLeader, Pid) -> true
2404 Types:
2406 GroupLeader = Pid = pid()
2408 Sets the group leader of Pid to GroupLeader. Typically, this is
2410 used when a process started from a certain shell is to have an‐
2411 other group leader than init.
2412 The group leader should be rarely changed in applications with a
2414 supervision tree, because OTP assumes the group leader of their
2415 processes is their application master.
2416 Setting the group leader follows the signal ordering guarentees
2418 described in the Processes Chapter in the Erlang Reference Man‐
2419 ual .
2420 See also group_leader/0 and OTP design principles related to
2422 starting and stopping applications.
2423 halt() -> no_return()
2425 The same as halt(0, []). Example:
2427 > halt().
2429 os_prompt%
2430 halt(Status) -> no_return()
2432 Types:
2434 Status = integer() >= 0 | abort | string()
2436 The same as halt(Status, []). Example:
2438 > halt(17).
2440 os_prompt% echo $?
2441 17
2442 os_prompt%
2443 halt(Status, Options) -> no_return()
2445 Types:
2447 Status = integer() >= 0 | abort | string()
2449 Options = [Option]
2450 Option = {flush, boolean()}
2451 Status must be a non-negative integer, a string, or the atom
2453 abort. Halts the Erlang runtime system. Has no return value. De‐
2454 pending on Status, the following occurs:
2455 integer():
2457 The runtime system exits with integer value Status as status
2458 code to the calling environment (OS).
2459 Note:
2461 On many platforms, the OS supports only status codes 0-255. A
2462 too large status code is truncated by clearing the high bits.
2463 string():
2466 An Erlang crash dump is produced with Status as slogan. Then
2467 the runtime system exits with status code 1. The string will
2468 be truncated if longer than 200 characters.
2469 Note:
2471 Before ERTS 9.1 (OTP-20.1) only code points in the range 0-255
2472 was accepted in the string. Now any unicode string is valid.
2473 abort:
2476 The runtime system aborts producing a core dump, if that is
2477 enabled in the OS.
2478 For integer Status, the Erlang runtime system closes all ports
2480 and allows async threads to finish their operations before exit‐
2481 ing. To exit without such flushing, use Option as {flush,false}.
2482 For statuses string() and abort, option flush is ignored and
2484 flushing is not done.
2485 hd(List) -> term()
2487 Types:
2489 List = [term(), ...]
2491 Returns the head of List, that is, the first element, for exam‐
2493 ple:
2494 > hd([1,2,3,4,5]).
2496 1
2497 Allowed in guard tests.
2499 Failure: badarg if List is the empty list [].
2501 erlang:hibernate(Module, Function, Args) -> no_return()
2503 Types:
2505 Module = module()
2507 Function = atom()
2508 Args = [term()]
2509 Puts the calling process into a wait state where its memory al‐
2511 location has been reduced as much as possible. This is useful if
2512 the process does not expect to receive any messages soon.
2513 The process is awaken when a message is sent to it, and control
2515 resumes in Module:Function with the arguments specified by Args
2516 with the call stack emptied, meaning that the process terminates
2517 when that function returns. Thus erlang:hibernate/3 never re‐
2518 turns to its caller. The resume function Module:Function/Arity
2519 must be exported (Arity =:= length(Args)).
2520 If the process has any message in its message queue, the process
2522 is awakened immediately in the same way as described earlier.
2523 In more technical terms, erlang:hibernate/3 discards the call
2525 stack for the process, and then garbage collects the process.
2526 After this, all live data is in one continuous heap. The heap is
2527 then shrunken to the exact same size as the live data that it
2528 holds (even if that size is less than the minimum heap size for
2529 the process).
2530 If the size of the live data in the process is less than the
2532 minimum heap size, the first garbage collection occurring after
2533 the process is awakened ensures that the heap size is changed to
2534 a size not smaller than the minimum heap size.
2535 Notice that emptying the call stack means that any surrounding
2537 catch is removed and must be re-inserted after hibernation. One
2538 effect of this is that processes started using proc_lib (also
2539 indirectly, such as gen_server processes), are to use
2540 proc_lib:hibernate/3 instead, to ensure that the exception han‐
2541 dler continues to work when the process wakes up.
2542 erlang:insert_element(Index, Tuple1, Term) -> Tuple2
2544 Types:
2546 Index = integer() >= 1
2548 1..tuple_size(Tuple1) + 1
2549 Tuple1 = Tuple2 = tuple()
2550 Term = term()
2551 Returns a new tuple with element Term inserted at position Index
2553 in tuple Tuple1. All elements from position Index and upwards
2554 are pushed one step higher in the new tuple Tuple2. Example:
2555 > erlang:insert_element(2, {one, two, three}, new).
2557 {one,new,two,three}
2558 integer_to_binary(Integer) -> binary()
2560 Types:
2562 Integer = integer()
2564 Returns a binary corresponding to the text representation of In‐
2566 teger, for example:
2567 > integer_to_binary(77).
2569 <<"77">>
2570 integer_to_binary(Integer, Base) -> binary()
2572 Types:
2574 Integer = integer()
2576 Base = 2..36
2577 Returns a binary corresponding to the text representation of In‐
2579 teger in base Base, for example:
2580 > integer_to_binary(1023, 16).
2582 <<"3FF">>
2583 integer_to_list(Integer) -> string()
2585 Types:
2587 Integer = integer()
2589 Returns a string corresponding to the text representation of In‐
2591 teger, for example:
2592 > integer_to_list(77).
2594 "77"
2595 integer_to_list(Integer, Base) -> string()
2597 Types:
2599 Integer = integer()
2601 Base = 2..36
2602 Returns a string corresponding to the text representation of In‐
2604 teger in base Base, for example:
2605 > integer_to_list(1023, 16).
2607 "3FF"
2608 iolist_size(Item) -> integer() >= 0
2610 Types:
2612 Item = iolist() | binary()
2614 Returns an integer, that is the size in bytes, of the binary
2616 that would be the result of iolist_to_binary(Item), for example:
2617 > iolist_size([1,2|<<3,4>>]).
2619 4
2620 iolist_to_binary(IoListOrBinary) -> binary()
2622 Types:
2624 IoListOrBinary = iolist() | binary()
2626 Returns a binary that is made from the integers and binaries in
2628 IoListOrBinary, for example:
2629 > Bin1 = <<1,2,3>>.
2631 <<1,2,3>>
2632 > Bin2 = <<4,5>>.
2633 <<4,5>>
2634 > Bin3 = <<6>>.
2635 <<6>>
2636 > iolist_to_binary([Bin1,1,[2,3,Bin2],4|Bin3]).
2637 <<1,2,3,1,2,3,4,5,4,6>>
2638 erlang:iolist_to_iovec(IoListOrBinary) -> iovec()
2640 Types:
2642 IoListOrBinary = iolist() | binary()
2644 Returns an iovec that is made from the integers and binaries in
2646 IoListOrBinary. This function is useful when you want to flatten
2647 an iolist but you do not need a single binary. This can be use‐
2648 ful for passing the data to nif functions such as enif_in‐
2649 spect_iovec or do more efficient message passing. The advantage
2650 of using this function over iolist_to_binary/1 is that it does
2651 not have to copy off-heap binaries. Example:
2652 > Bin1 = <<1,2,3>>.
2654 <<1,2,3>>
2655 > Bin2 = <<4,5>>.
2656 <<4,5>>
2657 > Bin3 = <<6>>.
2658 <<6>>
2659 %% If you pass small binaries and integers it works as iolist_to_binary
2660 > erlang:iolist_to_iovec([Bin1,1,[2,3,Bin2],4|Bin3]).
2661 [<<1,2,3,1,2,3,4,5,4,6>>]
2662 %% If you pass larger binaries, they are split and returned in a form
2663 %% optimized for calling the C function writev.
2664 > erlang:iolist_to_iovec([<<1>>,<<2:8096>>,<<3:8096>>]).
2665 [<<1,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,
2666 0,...>>,
2667 <<0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,
2668 ...>>,
2669 <<0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,...>>]
2670 is_alive() -> boolean()
2672 Returns true if the local node is alive (that is, if the node
2674 can be part of a distributed system), otherwise false. A node is
2675 alive if it is started with:
2676 * "erl -name LONGNAME" or,
2678 * "erl -sname SHORTNAME".
2680 A node can also be alive if it has got a name from a call to
2682 net_kernel:start/1 and has not been stopped by a call to
2683 net_kernel:stop/0.
2684 is_atom(Term) -> boolean()
2686 Types:
2688 Term = term()
2690 Returns true if Term is an atom, otherwise false.
2692 Allowed in guard tests.
2694 is_binary(Term) -> boolean()
2696 Types:
2698 Term = term()
2700 Returns true if Term is a binary, otherwise false.
2702 A binary always contains a complete number of bytes.
2704 Allowed in guard tests.
2706 is_bitstring(Term) -> boolean()
2708 Types:
2710 Term = term()
2712 Returns true if Term is a bitstring (including a binary), other‐
2714 wise false.
2715 Allowed in guard tests.
2717 is_boolean(Term) -> boolean()
2719 Types:
2721 Term = term()
2723 Returns true if Term is the atom true or the atom false (that
2725 is, a boolean). Otherwise returns false.
2726 Allowed in guard tests.
2728 erlang:is_builtin(Module, Function, Arity) -> boolean()
2730 Types:
2732 Module = module()
2734 Function = atom()
2735 Arity = arity()
2736 This BIF is useful for builders of cross-reference tools.
2738 Returns true if Module:Function/Arity is a BIF implemented in C,
2740 otherwise false.
2741 is_float(Term) -> boolean()
2743 Types:
2745 Term = term()
2747 Returns true if Term is a floating point number, otherwise
2749 false.
2750 Allowed in guard tests.
2752 is_function(Term) -> boolean()
2754 Types:
2756 Term = term()
2758 Returns true if Term is a fun, otherwise false.
2760 Allowed in guard tests.
2762 is_function(Term, Arity) -> boolean()
2764 Types:
2766 Term = term()
2768 Arity = arity()
2769 Returns true if Term is a fun that can be applied with Arity
2771 number of arguments, otherwise false.
2772 Allowed in guard tests.
2774 is_integer(Term) -> boolean()
2776 Types:
2778 Term = term()
2780 Returns true if Term is an integer, otherwise false.
2782 Allowed in guard tests.
2784 is_list(Term) -> boolean()
2786 Types:
2788 Term = term()
2790 Returns true if Term is a list with zero or more elements, oth‐
2792 erwise false.
2793 Allowed in guard tests.
2795 is_map(Term) -> boolean()
2797 Types:
2799 Term = term()
2801 Returns true if Term is a map, otherwise false.
2803 Allowed in guard tests.
2805 is_map_key(Key, Map) -> boolean()
2807 Types:
2809 Key = term()
2811 Map = map()
2812 Returns true if map Map contains Key and returns false if it
2814 does not contain the Key.
2815 The call fails with a {badmap,Map} exception if Map is not a
2817 map.
2818 Example:
2820 > Map = #{"42" => value}.
2822 #{"42" => value}
2823 > is_map_key("42",Map).
2824 true
2825 > is_map_key(value,Map).
2826 false
2827 Allowed in guard tests.
2829 is_number(Term) -> boolean()
2831 Types:
2833 Term = term()
2835 Returns true if Term is an integer or a floating point number.
2837 Otherwise returns false.
2838 Allowed in guard tests.
2840 is_pid(Term) -> boolean()
2842 Types:
2844 Term = term()
2846 Returns true if Term is a process identifier, otherwise false.
2848 Allowed in guard tests.
2850 is_port(Term) -> boolean()
2852 Types:
2854 Term = term()
2856 Returns true if Term is a port identifier, otherwise false.
2858 Allowed in guard tests.
2860 is_process_alive(Pid) -> boolean()
2862 Types:
2864 Pid = pid()
2866 Pid must refer to a process at the local node.
2868 Returns true if the process exists and is alive, that is, is not
2870 exiting and has not exited. Otherwise returns false.
2871 If process P1 calls is_process_alive(P2Pid) it is guaranteed
2873 that all signals, sent from P1 to P2 (P2 is the process with
2874 identifier P2Pid) before the call, will be delivered to P2 be‐
2875 fore the aliveness of P2 is checked. This guarantee means that
2876 one can use is_process_alive/1 to let a process P1 wait until a
2877 process P2, which has got an exit signal with reason kill from
2878 P1, is killed. Example:
2879 exit(P2Pid, kill),
2881 % P2 might not be killed
2882 is_process_alive(P2Pid),
2883 % P2 is not alive (the call above always return false)
2884 See the documentation about signals and erlang:exit/2 for more
2887 information about signals and exit singnals.
2888 is_record(Term, RecordTag) -> boolean()
2890 Types:
2892 Term = term()
2894 RecordTag = atom()
2895 Returns true if Term is a tuple and its first element is Record‐
2897 Tag. Otherwise returns false.
2898 Note:
2900 Normally the compiler treats calls to is_record/2 especially. It
2901 emits code to verify that Term is a tuple, that its first ele‐
2902 ment is RecordTag, and that the size is correct. However, if
2903 RecordTag is not a literal atom, the BIF is_record/2 is called
2904 instead and the size of the tuple is not verified.
2905 Allowed in guard tests, if RecordTag is a literal atom.
2908 is_record(Term, RecordTag, Size) -> boolean()
2910 Types:
2912 Term = term()
2914 RecordTag = atom()
2915 Size = integer() >= 0
2916 RecordTag must be an atom.
2918 Returns true if Term is a tuple, its first element is RecordTag,
2920 and its size is Size. Otherwise returns false.
2921 Allowed in guard tests if RecordTag is a literal atom and Size
2923 is a literal integer.
2924 Note:
2926 This BIF is documented for completeness. Usually is_record/2 is
2927 to be used.
2928 is_reference(Term) -> boolean()
2931 Types:
2933 Term = term()
2935 Returns true if Term is a reference, otherwise false.
2937 Allowed in guard tests.
2939 is_tuple(Term) -> boolean()
2941 Types:
2943 Term = term()
2945 Returns true if Term is a tuple, otherwise false.
2947 Allowed in guard tests.
2949 length(List) -> integer() >= 0
2951 Types:
2953 List = [term()]
2955 Returns the length of List, for example:
2957 > length([1,2,3,4,5,6,7,8,9]).
2959 9
2960 Allowed in guard tests.
2962 link(PidOrPort) -> true
2964 Types:
2966 PidOrPort = pid() | port()
2968 Sets up and activates a link between the calling process and an‐
2970 other process or a port identified by PidOrPort. We will from
2971 here on call the identified process or port linkee. If the lin‐
2972 kee is a port, it must reside on the same node as the caller.
2973 If one of the participants of a link terminates, it will send an
2975 exit signal to the other participant. The exit signal will con‐
2976 tain the exit reason of the terminated participant. Other cases
2977 when exit signals are triggered due to a link are when no linkee
2978 exist (noproc exit reason) and when the connection between
2979 linked processes on different nodes is lost or cannot be estab‐
2980 lished (noconnection exit reason).
2981 An existing link can be removed by calling unlink/1. For more
2983 information on links and exit signals due to links, see the Pro‐
2984 cesses chapter in the Erlang Reference Manual :
2985 * Links
2987 * Sending Exit Signals
2989 * Receiving Exit Signals
2991 For historical reasons, link/1 has a strange semi-synchronous
2993 behavior when it is "cheap" to check if the linkee exists or
2994 not, and the caller does not trap exits. If the above is true
2995 and the linkee does not exist, link/1 will raise a noproc error
2996 exception. The expected behavior would instead have been that
2997 link/1 returned true, and the caller later was sent an exit sig‐
2998 nal with noproc exit reason, but this is unfortunately not the
2999 case. The noproc exception is not to be confused with an exit
3000 signal with exit reason noproc. Currently it is "cheap" to check
3001 if the linkee exists when it is supposed to reside on the same
3002 node as the calling process.
3003 The link setup and activation is performed asynchronously. If
3005 the link already exists, or if the caller attempts to create a
3006 link to itself, nothing is done. A detailed description of the
3007 link protocol can be found in the Distribution Protocol chapter
3008 of the ERTS User's Guide .
3009 Failure:
3011 * badarg if PidOrPort does not identify a process or a node
3013 local port.
3014 * noproc linkee does not exist and it is "cheap" to check if
3016 it exists as described above.
3017 list_to_atom(String) -> atom()
3019 Types:
3021 String = string()
3023 Returns the atom whose text representation is String.
3025 As from Erlang/OTP 20, String may contain any Unicode character.
3027 Earlier versions allowed only ISO-latin-1 characters as the im‐
3028 plementation did not allow Unicode characters above 255. For
3029 more information on Unicode support in atoms, see note on UTF-8
3030 encoded atoms in section "External Term Format" in the User's
3031 Guide.
3032 Note:
3034 The number of characters that are permitted in an atom name is
3035 limited. The default limits can be found in the efficiency
3036 guide (section Advanced).
3037 Note:
3040 There is configurable limit on how many atoms that can exist and
3041 atoms are not garbage collected. Therefore, it is recommended to
3042 consider if list_to_existing_atom/1 is a better option than
3043 list_to_atom/1. The default limits can be found in the effi‐
3044 ciency guide (section Advanced).
3045 Example:
3048 > list_to_atom("Erlang").
3050 list_to_binary(IoList) -> binary()
3052 Types:
3054 IoList = iolist()
3056 Returns a binary that is made from the integers and binaries in
3058 IoList, for example:
3059 > Bin1 = <<1,2,3>>.
3061 <<1,2,3>>
3062 > Bin2 = <<4,5>>.
3063 <<4,5>>
3064 > Bin3 = <<6>>.
3065 <<6>>
3066 > list_to_binary([Bin1,1,[2,3,Bin2],4|Bin3]).
3067 <<1,2,3,1,2,3,4,5,4,6>>
3068 list_to_bitstring(BitstringList) -> bitstring()
3070 Types:
3072 BitstringList = bitstring_list()
3074 bitstring_list() =
3075 maybe_improper_list(byte() | bitstring() | bitstring_list(),
3076 bitstring() | [])
3077 Returns a bitstring that is made from the integers and bit‐
3079 strings in BitstringList. (The last tail in BitstringList is al‐
3080 lowed to be a bitstring.) Example:
3081 > Bin1 = <<1,2,3>>.
3083 <<1,2,3>>
3084 > Bin2 = <<4,5>>.
3085 <<4,5>>
3086 > Bin3 = <<6,7:4>>.
3087 <<6,7:4>>
3088 > list_to_bitstring([Bin1,1,[2,3,Bin2],4|Bin3]).
3089 <<1,2,3,1,2,3,4,5,4,6,7:4>>
3090 list_to_existing_atom(String) -> atom()
3092 Types:
3094 String = string()
3096 Returns the atom whose text representation is String, but only
3098 if there already exists such atom. An atom exists if it has been
3099 created by the run-time system by either loading code or creat‐
3100 ing a term in which the atom is part.
3101 Failure: badarg if there does not already exist an atom whose
3103 text representation is String.
3104 Note:
3106 Note that the compiler may optimize away atoms. For example, the
3107 compiler will rewrite atom_to_list(some_atom) to "some_atom". If
3108 that expression is the only mention of the atom some_atom in the
3109 containing module, the atom will not be created when the module
3110 is loaded, and a subsequent call to list_to_exist‐
3111 ing_atom("some_atom") will fail.
3112 list_to_float(String) -> float()
3115 Types:
3117 String = string()
3119 Returns the float whose text representation is String, for exam‐
3121 ple:
3122 > list_to_float("2.2017764e+0").
3124 2.2017764
3125 The float string format is the same as the format for Erlang
3127 float literals except for that underscores are not permitted.
3128 Failure: badarg if String contains a bad representation of a
3130 float.
3131 list_to_integer(String) -> integer()
3133 Types:
3135 String = string()
3137 Returns an integer whose text representation is String, for ex‐
3139 ample:
3140 > list_to_integer("123").
3142 123
3143 > list_to_integer("-123").
3145 -123
3146 > list_to_integer("+123234982304982309482093833234234").
3148 123234982304982309482093833234234
3149 String must contain at least one digit character and can have an
3151 optional prefix consisting of a single "+" or "-" character
3152 (that is, String must match the regular expression
3153 "^[+-]?[0-9]+$").
3154 Failure: badarg if String contains a bad representation of an
3156 integer.
3157 list_to_integer(String, Base) -> integer()
3159 Types:
3161 String = string()
3163 Base = 2..36
3164 Returns an integer whose text representation in base Base is
3166 String, for example:
3167 > list_to_integer("3FF", 16).
3169 1023
3170 > list_to_integer("+3FF", 16).
3172 1023
3173 > list_to_integer("3ff", 16).
3175 1023
3176 > list_to_integer("3fF", 16).
3178 1023
3179 > list_to_integer("-3FF", 16).
3181 -1023
3182 For example, when Base is 16, String must match the regular ex‐
3184 pression "^[+-]?([0-9]|[A-F]|[a-f])+$".
3185 Failure: badarg if String contains a bad representation of an
3187 integer.
3188 list_to_pid(String) -> pid()
3190 Types:
3192 String = string()
3194 Returns a process identifier whose text representation is a
3196 String, for example:
3197 > list_to_pid("<0.4.1>").
3199 <0.4.1>
3200 Failure: badarg if String contains a bad representation of a
3202 process identifier.
3203 Warning:
3205 This BIF is intended for debugging and is not to be used in ap‐
3206 plication programs.
3207 list_to_port(String) -> port()
3210 Types:
3212 String = string()
3214 Returns a port identifier whose text representation is a String,
3216 for example:
3217 > list_to_port("#Port<0.4>").
3219 #Port<0.4>
3220 Failure: badarg if String contains a bad representation of a
3222 port identifier.
3223 Warning:
3225 This BIF is intended for debugging and is not to be used in ap‐
3226 plication programs.
3227 list_to_ref(String) -> reference()
3230 Types:
3232 String = string()
3234 Returns a reference whose text representation is a String, for
3236 example:
3237 > list_to_ref("#Ref<0.4192537678.4073193475.71181>").
3239 #Ref<0.4192537678.4073193475.71181>
3240 Failure: badarg if String contains a bad representation of a
3242 reference.
3243 Warning:
3245 This BIF is intended for debugging and is not to be used in ap‐
3246 plication programs.
3247 list_to_tuple(List) -> tuple()
3250 Types:
3252 List = [term()]
3254 Returns a tuple corresponding to List, for example
3256 > list_to_tuple([share, ['Ericsson_B', 163]]).
3258 {share, ['Ericsson_B', 163]}
3259 List can contain any Erlang terms.
3261 load_module(Module, Binary) -> {module, Module} | {error, Reason}
3263 Types:
3265 Module = module()
3267 Binary = binary()
3268 Reason = badfile | not_purged | on_load
3269 If Binary contains the object code for module Module, this BIF
3271 loads that object code. If the code for module Module already
3272 exists, all export references are replaced so they point to the
3273 newly loaded code. The previously loaded code is kept in the
3274 system as old code, as there can still be processes executing
3275 that code.
3276 Returns either {module, Module}, or {error, Reason} if loading
3278 fails. Reason is one of the following:
3279 badfile:
3281 The object code in Binary has an incorrect format or the ob‐
3282 ject code contains code for another module than Module.
3283 not_purged:
3285 Binary contains a module that cannot be loaded because old
3286 code for this module already exists.
3287 on_load:
3289 The code in Binary contains an on_load declaration that must
3290 be executed before Binary can become the current code. Any
3291 previous current code for Module will remain until the
3292 on_load call has finished.
3293 Warning:
3295 This BIF is intended for the code server (see code(3)) and is
3296 not to be used elsewhere.
3297 erlang:load_nif(Path, LoadInfo) -> ok | Error
3300 Types:
3302 Path = string()
3304 LoadInfo = term()
3305 Error = {error, {Reason, Text :: string()}}
3306 Reason =
3307 load_failed | bad_lib | load | reload | upgrade |
3308 old_code
3309 Loads and links a dynamic library containing native implemented
3311 functions (NIFs) for a module. Path is a file path to the share‐
3312 able object/dynamic library file minus the OS-dependent file ex‐
3313 tension (.so for Unix and .dll for Windows). Notice that on most
3314 OSs the library has to have a different name on disc when an up‐
3315 grade of the nif is done. If the name is the same, but the con‐
3316 tents differ, the old library may be loaded instead. For infor‐
3317 mation on how to implement a NIF library, see erl_nif(3).
3318 LoadInfo can be any term. It is passed on to the library as part
3320 of the initialization. A good practice is to include a module
3321 version number to support future code upgrade scenarios.
3322 The call to load_nif/2 must be made directly from the Erlang
3324 code of the module that the NIF library belongs to. It returns
3325 either ok, or {error,{Reason,Text}} if loading fails. Reason is
3326 one of the following atoms while Text is a human readable string
3327 that can give more information about the failure:
3328 load_failed:
3330 The OS failed to load the NIF library.
3331 bad_lib:
3333 The library did not fulfill the requirements as a NIF li‐
3334 brary of the calling module.
3335 load | upgrade:
3337 The corresponding library callback was unsuccessful.
3338 reload:
3340 A NIF library is already loaded for this module instance.
3341 The previously deprecated reload feature was removed in OTP
3342 20.
3343 old_code:
3345 The call to load_nif/2 was made from the old code of a mod‐
3346 ule that has been upgraded; this is not allowed.
3347 erlang:loaded() -> [Module]
3349 Types:
3351 Module = module()
3353 Returns a list of all loaded Erlang modules (current and old
3355 code), including preloaded modules.
3356 See also code(3).
3358 erlang:localtime() -> DateTime
3360 Types:
3362 DateTime = calendar:datetime()
3364 Returns the current local date and time, {{Year, Month, Day},
3366 {Hour, Minute, Second}}, for example:
3367 > erlang:localtime().
3369 {{1996,11,6},{14,45,17}}
3370 The time zone and Daylight Saving Time correction depend on the
3372 underlying OS. The return value is based on the OS System Time.
3373 erlang:localtime_to_universaltime(Localtime) -> Universaltime
3375 Types:
3377 Localtime = Universaltime = calendar:datetime()
3379 Converts local date and time to Universal Time Coordinated
3381 (UTC), if supported by the underlying OS. Otherwise no conver‐
3382 sion is done and Localtime is returned. Example:
3383 > erlang:localtime_to_universaltime({{1996,11,6},{14,45,17}}).
3385 {{1996,11,6},{13,45,17}}
3386 Failure: badarg if Localtime denotes an invalid date and time.
3388 erlang:localtime_to_universaltime(Localtime, IsDst) ->
3390 Universaltime
3391 Types:
3393 Localtime = Universaltime = calendar:datetime()
3395 IsDst = true | false | undefined
3396 Converts local date and time to Universal Time Coordinated (UTC)
3398 as erlang:localtime_to_universaltime/1, but the caller decides
3399 if Daylight Saving Time is active.
3400 If IsDst == true, Localtime is during Daylight Saving Time, if
3402 IsDst == false it is not. If IsDst == undefined, the underlying
3403 OS can guess, which is the same as calling erlang:local‐
3404 time_to_universaltime(Localtime).
3405 Examples:
3407 > erlang:localtime_to_universaltime({{1996,11,6},{14,45,17}}, true).
3409 {{1996,11,6},{12,45,17}}
3410 > erlang:localtime_to_universaltime({{1996,11,6},{14,45,17}}, false).
3411 {{1996,11,6},{13,45,17}}
3412 > erlang:localtime_to_universaltime({{1996,11,6},{14,45,17}}, undefined).
3413 {{1996,11,6},{13,45,17}}
3414 Failure: badarg if Localtime denotes an invalid date and time.
3416 make_ref() -> reference()
3418 Returns a unique reference. The reference is unique among con‐
3420 nected nodes.
3421 Warning:
3423 Before OTP-23 when a node is restarted multiple times with the
3424 same node name, references created on a newer node can be mis‐
3425 taken for a reference created on an older node with the same
3426 node name.
3427 erlang:make_tuple(Arity, InitialValue) -> tuple()
3430 Types:
3432 Arity = arity()
3434 InitialValue = term()
3435 Creates a new tuple of the specified Arity, where all elements
3437 are InitialValue, for example:
3438 > erlang:make_tuple(4, []).
3440 {[],[],[],[]}
3441 erlang:make_tuple(Arity, DefaultValue, InitList) -> tuple()
3443 Types:
3445 Arity = arity()
3447 DefaultValue = term()
3448 InitList = [{Position :: integer() >= 1, term()}]
3449 Creates a tuple of size Arity, where each element has value De‐
3451 faultValue, and then fills in values from InitList. Each list
3452 element in InitList must be a two-tuple, where the first element
3453 is a position in the newly created tuple and the second element
3454 is any term. If a position occurs more than once in the list,
3455 the term corresponding to the last occurrence is used. Example:
3456 > erlang:make_tuple(5, [], [{2,ignored},{5,zz},{2,aa}]).
3458 {[],aa,[],[],zz}
3459 map_get(Key, Map) -> Value
3461 Types:
3463 Map = map()
3465 Key = Value = any()
3466 Returns value Value associated with Key if Map contains Key.
3468 The call fails with a {badmap,Map} exception if Map is not a
3470 map, or with a {badkey,Key} exception if no value is associated
3471 with Key.
3472 Example:
3474 > Key = 1337,
3476 Map = #{42 => value_two,1337 => "value one","a" => 1},
3477 map_get(Key,Map).
3478 "value one"
3479 Allowed in guard tests.
3481 map_size(Map) -> integer() >= 0
3483 Types:
3485 Map = map()
3487 Returns an integer, which is the number of key-value pairs in
3489 Map, for example:
3490 > map_size(#{a=>1, b=>2, c=>3}).
3492 3
3493 Allowed in guard tests.
3495 erlang:match_spec_test(MatchAgainst, MatchSpec, Type) ->
3497 TestResult
3498 Types:
3500 MatchAgainst = [term()] | tuple()
3502 MatchSpec = term()
3503 Type = table | trace
3504 TestResult =
3505 {ok, term(), [return_trace], [{error | warning,
3506 string()}]} |
3507 {error, [{error | warning, string()}]}
3508 Tests a match specification used in calls to ets:select/2 and
3510 erlang:trace_pattern/3. The function tests both a match specifi‐
3511 cation for "syntactic" correctness and runs the match specifica‐
3512 tion against the object. If the match specification contains er‐
3513 rors, the tuple {error, Errors} is returned, where Errors is a
3514 list of natural language descriptions of what was wrong with the
3515 match specification.
3516 If Type is table, the object to match against is to be a tuple.
3518 The function then returns {ok,Result,[],Warnings}, where Result
3519 is what would have been the result in a real ets:select/2 call,
3520 or false if the match specification does not match the object
3521 tuple.
3522 If Type is trace, the object to match against is to be a list.
3524 The function returns {ok, Result, Flags, Warnings}, where Result
3525 is one of the following:
3526 * true if a trace message is to be emitted
3528 * false if a trace message is not to be emitted
3530 * The message term to be appended to the trace message
3532 Flags is a list containing all the trace flags to be enabled,
3534 currently this is only return_trace.
3535 This is a useful debugging and test tool, especially when writ‐
3537 ing complicated match specifications.
3538 See also ets:test_ms/2.
3540 max(Term1, Term2) -> Maximum
3542 Types:
3544 Term1 = Term2 = Maximum = term()
3546 Returns the largest of Term1 and Term2. If the terms compare
3548 equal with the == operator, Term1 is returned.
3549 The Expressions section contains descriptions of the == opera‐
3551 tor and how terms are ordered.
3552 Examples:
3554 > max(1, 2).
3556 2
3557 > max(1.0, 1).
3559 1.0
3560 > max(1, 1.0).
3562 1
3563 > max("abc", "b").
3565 "b"
3566 erlang:md5(Data) -> Digest
3568 Types:
3570 Data = iodata()
3572 Digest = binary()
3573 Computes an MD5 message digest from Data, where the length of
3575 the digest is 128 bits (16 bytes). Data is a binary or a list of
3576 small integers and binaries.
3577 For more information about MD5, see RFC 1321 - The MD5 Message-
3579 Digest Algorithm.
3580 Warning:
3582 The MD5 Message-Digest Algorithm is not considered safe for
3583 code-signing or software-integrity purposes.
3584 erlang:md5_final(Context) -> Digest
3587 Types:
3589 Context = Digest = binary()
3591 Finishes the update of an MD5 Context and returns the computed
3593 MD5 message digest.
3594 erlang:md5_init() -> Context
3596 Types:
3598 Context = binary()
3600 Creates an MD5 context, to be used in the following calls to
3602 md5_update/2.
3603 erlang:md5_update(Context, Data) -> NewContext
3605 Types:
3607 Context = binary()
3609 Data = iodata()
3610 NewContext = binary()
3611 Update an MD5 Context with Data and returns a NewContext.
3613 erlang:memory() -> [{Type, Size}]
3615 Types:
3617 Type = memory_type()
3619 Size = integer() >= 0
3620 memory_type() =
3621 total | processes | processes_used | system | atom |
3622 atom_used | binary | code | ets
3623 Returns a list with information about memory dynamically allo‐
3625 cated by the Erlang emulator. Each list element is a tuple
3626 {Type, Size}. The first element Type is an atom describing mem‐
3627 ory type. The second element Size is the memory size in bytes.
3628 Memory types:
3630 total:
3632 The total amount of memory currently allocated. This is the
3633 same as the sum of the memory size for processes and system.
3634 processes:
3636 The total amount of memory currently allocated for the Er‐
3637 lang processes.
3638 processes_used:
3640 The total amount of memory currently used by the Erlang pro‐
3641 cesses. This is part of the memory presented as processes
3642 memory.
3643 system:
3645 The total amount of memory currently allocated for the emu‐
3646 lator that is not directly related to any Erlang process.
3647 Memory presented as processes is not included in this mem‐
3648 ory. instrument(3) can be used to get a more detailed break‐
3649 down of what memory is part of this type.
3650 atom:
3652 The total amount of memory currently allocated for atoms.
3653 This memory is part of the memory presented as system mem‐
3654 ory.
3655 atom_used:
3657 The total amount of memory currently used for atoms. This
3658 memory is part of the memory presented as atom memory.
3659 binary:
3661 The total amount of memory currently allocated for binaries.
3662 This memory is part of the memory presented as system mem‐
3663 ory.
3664 code:
3666 The total amount of memory currently allocated for Erlang
3667 code. This memory is part of the memory presented as system
3668 memory.
3669 ets:
3671 The total amount of memory currently allocated for ETS ta‐
3672 bles. This memory is part of the memory presented as system
3673 memory.
3674 maximum:
3676 The maximum total amount of memory allocated since the emu‐
3677 lator was started. This tuple is only present when the emu‐
3678 lator is run with instrumentation.
3679 For information on how to run the emulator with instrumenta‐
3681 tion, see instrument(3) and/or erl(1).
3682 Note:
3684 The system value is not complete. Some allocated memory that is
3685 to be part of this value is not.
3686 When the emulator is run with instrumentation, the system value
3688 is more accurate, but memory directly allocated for malloc (and
3689 friends) is still not part of the system value. Direct calls to
3690 malloc are only done from OS-specific runtime libraries and per‐
3691 haps from user-implemented Erlang drivers that do not use the
3692 memory allocation functions in the driver interface.
3693 As the total value is the sum of processes and system, the error
3695 in system propagates to the total value.
3696 The different amounts of memory that are summed are not gathered
3698 atomically, which introduces an error in the result.
3699 The different values have the following relation to each other.
3702 Values beginning with an uppercase letter is not part of the re‐
3703 sult.
3704 total = processes + system
3706 processes = processes_used + ProcessesNotUsed
3707 system = atom + binary + code + ets + OtherSystem
3708 atom = atom_used + AtomNotUsed
3709 RealTotal = processes + RealSystem
3710 RealSystem = system + MissedSystem
3711 More tuples in the returned list can be added in a future re‐
3713 lease.
3714 Note:
3716 The total value is supposed to be the total amount of memory dy‐
3717 namically allocated by the emulator. Shared libraries, the code
3718 of the emulator itself, and the emulator stacks are not supposed
3719 to be included. That is, the total value is not supposed to be
3720 equal to the total size of all pages mapped to the emulator.
3721 Also, because of fragmentation and prereservation of memory ar‐
3723 eas, the size of the memory segments containing the dynamically
3724 allocated memory blocks can be much larger than the total size
3725 of the dynamically allocated memory blocks.
3726 Note:
3729 As from ERTS 5.6.4, erlang:memory/0 requires that all erts_al‐
3730 loc(3) allocators are enabled (default behavior).
3731 Failure: notsup if an erts_alloc(3) allocator has been disabled.
3734 erlang:memory(Type :: memory_type()) -> integer() >= 0
3736 erlang:memory(TypeList :: [memory_type()]) ->
3738 [{memory_type(), integer() >= 0}]
3739 Types:
3741 memory_type() =
3743 total | processes | processes_used | system | atom |
3744 atom_used | binary | code | ets
3745 Returns the memory size in bytes allocated for memory of type
3747 Type. The argument can also be specified as a list of mem‐
3748 ory_type() atoms, in which case a corresponding list of {mem‐
3749 ory_type(), Size :: integer >= 0} tuples is returned.
3750 Note:
3752 As from ERTS 5.6.4, erlang:memory/1 requires that all erts_al‐
3753 loc(3) allocators are enabled (default behavior).
3754 Failures:
3757 badarg:
3759 If Type is not one of the memory types listed in the de‐
3760 scription of erlang:memory/0.
3761 badarg:
3763 If maximum is passed as Type and the emulator is not run in
3764 instrumented mode.
3765 notsup:
3767 If an erts_alloc(3) allocator has been disabled.
3768 See also erlang:memory/0.
3770 min(Term1, Term2) -> Minimum
3772 Types:
3774 Term1 = Term2 = Minimum = term()
3776 Returns the smallest of Term1 and Term2. If the terms compare
3778 equal with the == operator, Term1 is returned.
3779 The Expressions section contains descriptions of the == opera‐
3781 tor and how terms are ordered.
3782 Examples:
3784 > min(1, 2).
3786 1
3787 > min(1.0, 1).
3789 1.0
3790 > min(1, 1.0).
3792 1
3793 > min("abc", "b").
3795 "abc"
3796 module_loaded(Module) -> boolean()
3798 Types:
3800 Module = module()
3802 Returns true if the module Module is loaded, otherwise false. It
3804 does not attempt to load the module.
3805 Warning:
3807 This BIF is intended for the code server (see code(3)) and is
3808 not to be used elsewhere.
3809 monitor(Type :: process, Item :: monitor_process_identifier()) ->
3812 MonitorRef
3813 monitor(Type :: port, Item :: monitor_port_identifier()) ->
3815 MonitorRef
3816 monitor(Type :: time_offset, Item :: clock_service) -> MonitorRef
3818 Types:
3820 MonitorRef = reference()
3822 registered_name() = atom()
3823 registered_process_identifier() =
3824 registered_name() | {registered_name(), node()}
3825 monitor_process_identifier() =
3826 pid() | registered_process_identifier()
3827 monitor_port_identifier() = port() | registered_name()
3828 Sends a monitor request of type Type to the entity identified by
3830 Item. If the monitored entity does not exist or it changes moni‐
3831 tored state, the caller of monitor/2 is notified by a message on
3832 the following format:
3833 {Tag, MonitorRef, Type, Object, Info}
3835 Note:
3837 The monitor request is an asynchronous signal. That is, it takes
3838 time before the signal reaches its destination.
3839 Type can be one of the following atoms: process, port or
3842 time_offset.
3843 A process or port monitor is triggered only once, after that it
3845 is removed from both monitoring process and the monitored en‐
3846 tity. Monitors are fired when the monitored process or port ter‐
3847 minates, does not exist at the moment of creation, or if the
3848 connection to it is lost. If the connection to it is lost, we do
3849 not know if it still exists. The monitoring is also turned off
3850 when demonitor/1 is called.
3851 A process or port monitor by name resolves the RegisteredName to
3853 pid() or port() only once at the moment of monitor instantia‐
3854 tion, later changes to the name registration will not affect the
3855 existing monitor.
3856 When a process or port monitor is triggered, a 'DOWN' message is
3858 sent that has the following pattern:
3859 {'DOWN', MonitorRef, Type, Object, Info}
3861 In the monitor message MonitorRef and Type are the same as de‐
3863 scribed earlier, and:
3864 Object:
3866 The monitored entity, which triggered the event. When moni‐
3867 toring a process or a local port, Object will be equal to
3868 the pid() or port() that was being monitored. When monitor‐
3869 ing process or port by name, Object will have format {Regis‐
3870 teredName, Node} where RegisteredName is the name which has
3871 been used with monitor/2 call and Node is local or remote
3872 node name (for ports monitored by name, Node is always local
3873 node name).
3874 Info:
3876 Either the exit reason of the process, noproc (process or
3877 port did not exist at the time of monitor creation), or no‐
3878 connection (no connection to the node where the monitored
3879 process resides).
3880 Monitoring a process:
3882 Creates monitor between the current process and another
3883 process identified by Item, which can be a pid() (local or
3884 remote), an atom RegisteredName or a tuple {RegisteredName,
3885 Node} for a registered process, located elsewhere.
3886 Note:
3888 Before ERTS 10.0 (OTP 21.0), monitoring a process could fail
3889 with badarg if the monitored process resided on a primitive
3890 node (such as erl_interface or jinterface), where remote
3891 process monitoring is not implemented.
3892 Now, such a call to monitor will instead succeed and a monitor
3894 is created. But the monitor will only supervise the connec‐
3895 tion. That is, a {'DOWN', _, process, _, noconnection} is the
3896 only message that may be received, as the primitive node have
3897 no way of reporting the status of the monitored process.
3898 Monitoring a port:
3901 Creates monitor between the current process and a port iden‐
3902 tified by Item, which can be a port() (only local), an atom
3903 RegisteredName or a tuple {RegisteredName, Node} for a reg‐
3904 istered port, located on this node. Note, that attempt to
3905 monitor a remote port will result in badarg.
3906 Monitoring a time_offset:
3908 Monitors changes in time offset between Erlang monotonic
3909 time and Erlang system time. One valid Item exists in combi‐
3910 nation with the time_offset Type, namely the atom clock_ser‐
3911 vice. Notice that the atom clock_service is not the regis‐
3912 tered name of a process. In this case it serves as an iden‐
3913 tifier of the runtime system internal clock service at cur‐
3914 rent runtime system instance.
3915 The monitor is triggered when the time offset is changed.
3917 This either if the time offset value is changed, or if the
3918 offset is changed from preliminary to final during finaliza‐
3919 tion of the time offset when the single time warp mode is
3920 used. When a change from preliminary to final time offset is
3921 made, the monitor is triggered once regardless of whether
3922 the time offset value was changed or not.
3923 If the runtime system is in multi time warp mode, the time
3925 offset is changed when the runtime system detects that the
3926 OS system time has changed. The runtime system does, how‐
3927 ever, not detect this immediately when it occurs. A task
3928 checking the time offset is scheduled to execute at least
3929 once a minute, so under normal operation this is to be de‐
3930 tected within a minute, but during heavy load it can take
3931 longer time.
3932 The monitor is not automatically removed after it has been
3934 triggered. That is, repeated changes of the time offset
3935 trigger the monitor repeatedly.
3936 When the monitor is triggered a 'CHANGE' message is sent to
3938 the monitoring process. A 'CHANGE' message has the following
3939 pattern:
3940 {'CHANGE', MonitorRef, Type, Item, NewTimeOffset}
3942 where MonitorRef, Type, and Item are the same as described
3944 above, and NewTimeOffset is the new time offset.
3945 When the 'CHANGE' message has been received you are guaran‐
3947 teed not to retrieve the old time offset when calling er‐
3948 lang:time_offset(). Notice that you can observe the change
3949 of the time offset when calling erlang:time_offset() before
3950 you get the 'CHANGE' message.
3951 Making several calls to monitor/2 for the same Item and/or Type
3953 is not an error; it results in as many independent monitoring
3954 instances.
3955 The monitor functionality is expected to be extended. That is,
3957 other Types and Items are expected to be supported in a future
3958 release.
3959 Note:
3961 If or when monitor/2 is extended, other possible values for Tag,
3962 Object, and Info in the monitor message will be introduced.
3963 monitor(Type :: process,
3966 Item :: monitor_process_identifier(),
3967 Opts :: [monitor_option()]) ->
3968 MonitorRef
3969 monitor(Type :: port,
3971 Item :: monitor_port_identifier(),
3972 Opts :: [monitor_option()]) ->
3973 MonitorRef
3974 monitor(Type :: time_offset,
3976 Item :: clock_service,
3977 Opts :: [monitor_option()]) ->
3978 MonitorRef
3979 Types:
3981 MonitorRef = reference()
3983 registered_name() = atom()
3984 registered_process_identifier() =
3985 registered_name() | {registered_name(), node()}
3986 monitor_process_identifier() =
3987 pid() | registered_process_identifier()
3988 monitor_port_identifier() = port() | registered_name()
3989 Provides an option list for modification of monitoring function‐
3991 ality provided by monitor/2. The Type and Item arguments have
3992 the same meaning as when passed to monitor/2. Currently avail‐
3993 able options:
3994 {alias, UnaliasOpt}:
3996 The returned monitor reference will also become an alias for
3997 the calling process. That is, the returned reference can be
3998 used for sending messages to the calling process. See also
3999 alias/0. The UnaliasOpt determines how the alias should be
4000 deactivated.
4001 explicit_unalias:
4003 Only an explicit call to unalias/1 will deactivate the
4004 alias.
4005 demonitor:
4007 The alias will be automatically deactivated when the moni‐
4008 tor is removed. This either via an explicit call to demon‐
4009 itor/1 or when it is automatically removed at the same
4010 time as a 'DOWN' message is delivered due to the monitor.
4011 The alias can also still be deactivated via a call to una‐
4012 lias/1.
4013 reply_demonitor:
4015 The alias will be automatically deactivated when the moni‐
4016 tor is removed (see demonitor option above) or a reply
4017 message sent via the alias is received. When a reply mes‐
4018 sage is received via the alias the monitor will also be
4019 automatically removed. This is useful in client/server
4020 scenarios when a client monitors the server and will get
4021 the reply via the alias. Once the response is received
4022 both the alias and the monitor will be automatically re‐
4023 moved regardless of whether the response is a reply or a
4024 'DOWN' message. The alias can also still be deactivated
4025 via a call to unalias/1. Note that if the alias is removed
4026 using the unalias/1 BIF, the monitor will still be left
4027 active.
4028 Example:
4030 server() ->
4032 receive
4033 {request, AliasReqId, Request} ->
4034 Result = perform_request(Request),
4035 AliasReqId ! {reply, AliasReqId, Result}
4036 end,
4037 server().
4038 client(ServerPid, Request) ->
4040 AliasMonReqId = monitor(process, ServerPid, [{alias, reply_demonitor}]),
4041 ServerPid ! {request, AliasMonReqId, Request},
4042 %% Alias as well as monitor will be automatically deactivated if we
4043 %% receive a reply or a 'DOWN' message since we used 'reply_demonitor'
4044 %% as unalias option...
4045 receive
4046 {reply, AliasMonReqId, Result} ->
4047 Result;
4048 {'DOWN', AliasMonReqId, process, ServerPid, ExitReason} ->
4049 error(ExitReason)
4050 end.
4051 Note that both the server and the client in this example
4054 must be executing on at least OTP 24 systems in order for
4055 this to work.
4056 For more information on process aliases see the Process
4058 Aliases section of the Erlang Reference Manual .
4059 {tag, UserDefinedTag}:
4061 Replace the default Tag with UserDefinedTag in the monitor
4062 message delivered when the monitor is triggered. For exam‐
4063 ple, when monitoring a process, the 'DOWN' tag in the down
4064 message will be replaced by UserDefinedTag.
4065 An example of how the {tag, UserDefinedTag} option can be
4067 used in order to enable the new selective receive optimiza‐
4068 tion, introduced in OTP 24, when making multiple requests to
4069 different servers:
4070 server() ->
4072 receive
4073 {request, From, ReqId, Request} ->
4074 Result = perform_request(Request),
4075 From ! {reply, self(), ReqId, Result}
4076 end,
4077 server().
4078 client(ServerPids, Request) when is_list(ServerPids) ->
4080 ReqId = make_ref(),
4081 lists:foreach(fun (ServerPid) ->
4082 _ = monitor(process, ServerPid,
4083 [{tag, {'DOWN', ReqId}}]),
4084 ServerPid ! {request, self(), ReqId, Request}
4085 end,
4086 ServerPids),
4087 receive_replies(ReqId, length(ServerPids), []).
4088 receive_replies(_ReqId, 0, Acc) ->
4090 Acc;
4091 receive_replies(ReqId, N, Acc) ->
4092 %% The compiler will detect that we match on the 'ReqId'
4093 %% reference in all clauses, and will enable the selective
4094 %% receive optimization which makes the receive able to
4095 %% skip past all messages present in the message queue at
4096 %% the time when the 'ReqId' reference was created...
4097 Res = receive
4098 {reply, ServerPid, ReqId, Result} ->
4099 %% Here we typically would have deactivated the
4100 %% monitor by a call to demonitor(Mon, [flush]) but
4101 %% we ignore this in this example for simplicity...
4102 {ok, ServerPid, Result};
4103 {{'DOWN', ReqId}, _Mon, process, ServerPid, ExitReason} ->
4104 {error, ServerPid, ExitReason}
4105 end,
4106 receive_replies(ReqId, N-1, [Res | Acc]).
4107 In order for this example to work as intended, the client
4110 must be executing on at least an OTP 24 system, but the
4111 servers may execute on older systems.
4112 monitor_node(Node, Flag) -> true
4114 Types:
4116 Node = node()
4118 Flag = boolean()
4119 Monitor the status of the node Node. If Flag is true, monitoring
4121 is turned on. If Flag is false, monitoring is turned off.
4122 Making several calls to monitor_node(Node, true) for the same
4124 Node is not an error; it results in as many independent monitor‐
4125 ing instances.
4126 If Node fails or does not exist, the message {nodedown, Node} is
4128 delivered to the process. If a process has made two calls to
4129 monitor_node(Node, true) and Node terminates, two nodedown mes‐
4130 sages are delivered to the process. If there is no connection to
4131 Node, an attempt is made to create one. If this fails, a node‐
4132 down message is delivered.
4133 The delivery of the nodedown signal is not ordered with respect
4135 to other link or monitor signals from the node that goes down.
4136 If you need a guarantee that all signals from the remote node
4137 has been delivered before the nodedown signal is sent, you
4138 should use net_kernel:monitor_nodes/1.
4139 Nodes connected through hidden connections can be monitored as
4141 any other nodes.
4142 Failure: notalive if the local node is not alive.
4144 erlang:monitor_node(Node, Flag, Options) -> true
4146 Types:
4148 Node = node()
4150 Flag = boolean()
4151 Options = [Option]
4152 Option = allow_passive_connect
4153 Behaves as monitor_node/2 except that it allows an extra option
4155 to be specified, namely allow_passive_connect. This option al‐
4156 lows the BIF to wait the normal network connection time-out for
4157 the monitored node to connect itself, even if it cannot be ac‐
4158 tively connected from this node (that is, it is blocked). The
4159 state where this can be useful can only be achieved by using the
4160 Kernel option dist_auto_connect once. If that option is not
4161 used, option allow_passive_connect has no effect.
4162 Note:
4164 Option allow_passive_connect is used internally and is seldom
4165 needed in applications where the network topology and the Kernel
4166 options in effect are known in advance.
4167 Failure: badarg if the local node is not alive or the option
4170 list is malformed.
4171 erlang:monotonic_time() -> integer()
4173 Returns the current Erlang monotonic time in native time unit.
4175 This is a monotonically increasing time since some unspecified
4176 point in time.
4177 Note:
4179 This is a monotonically increasing time, but not a strictly
4180 monotonically increasing time. That is, consecutive calls to er‐
4181 lang:monotonic_time/0 can produce the same result.
4182 Different runtime system instances will use different unspeci‐
4184 fied points in time as base for their Erlang monotonic clocks.
4185 That is, it is pointless comparing monotonic times from differ‐
4186 ent runtime system instances. Different runtime system instances
4187 can also place this unspecified point in time different relative
4188 runtime system start. It can be placed in the future (time at
4189 start is a negative value), the past (time at start is a posi‐
4190 tive value), or the runtime system start (time at start is
4191 zero). The monotonic time at runtime system start can be re‐
4192 trieved by calling erlang:system_info(start_time).
4193 erlang:monotonic_time(Unit) -> integer()
4196 Types:
4198 Unit = time_unit()
4200 Returns the current Erlang monotonic time converted into the
4202 Unit passed as argument.
4203 Same as calling erlang:convert_time_unit(erlang:mono‐
4205 tonic_time(), native, Unit), however optimized for commonly used
4206 Units.
4207 erlang:nif_error(Reason) -> no_return()
4209 Types:
4211 Reason = term()
4213 Works exactly like error/1, but Dialyzer thinks that this BIF
4215 will return an arbitrary term. When used in a stub function for
4216 a NIF to generate an exception when the NIF library is not
4217 loaded, Dialyzer does not generate false warnings.
4218 erlang:nif_error(Reason, Args) -> no_return()
4220 Types:
4222 Reason = term()
4224 Args = [term()]
4225 Works exactly like error/2, but Dialyzer thinks that this BIF
4227 will return an arbitrary term. When used in a stub function for
4228 a NIF to generate an exception when the NIF library is not
4229 loaded, Dialyzer does not generate false warnings.
4230 node() -> Node
4232 Types:
4234 Node = node()
4236 Returns the name of the local node. If the node is not alive,
4238 nonode@nohost is returned instead.
4239 Allowed in guard tests.
4241 node(Arg) -> Node
4243 Types:
4245 Arg = pid() | port() | reference()
4247 Node = node()
4248 Returns the node where Arg originates. Arg can be a process
4250 identifier, a reference, or a port. If Arg originates from the
4251 local node and the local node is not alive, nonode@nohost is re‐
4252 turned.
4253 Allowed in guard tests.
4255 nodes() -> Nodes
4257 Types:
4259 Nodes = [node()]
4261 Returns a list of all nodes connected to this node through nor‐
4263 mal connections (that is, hidden nodes are not listed). Same as
4264 nodes(visible).
4265 nodes(Arg) -> Nodes
4267 Types:
4269 Arg = NodeType | [NodeType]
4271 NodeType = visible | hidden | connected | this | known
4272 Nodes = [node()]
4273 Returns a list of nodes according to the argument specified. The
4275 returned result, when the argument is a list, is the list of
4276 nodes satisfying the disjunction(s) of the list elements.
4277 NodeTypes:
4279 visible:
4281 Nodes connected to this node through normal connections.
4282 hidden:
4284 Nodes connected to this node through hidden connections.
4285 connected:
4287 All nodes connected to this node.
4288 this:
4290 This node.
4291 known:
4293 Nodes that are known to this node. That is, connected nodes
4294 and nodes referred to by process identifiers, port identi‐
4295 fiers, and references located on this node. The set of known
4296 nodes is garbage collected. Notice that this garbage collec‐
4297 tion can be delayed. For more information, see erlang:sys‐
4298 tem_info(delayed_node_table_gc).
4299 Some equalities: [node()] = nodes(this), nodes(connected) =
4301 nodes([visible, hidden]), and nodes() = nodes(visible).
4302 now() -> Timestamp
4304 Types:
4306 Timestamp = timestamp()
4308 timestamp() =
4309 {MegaSecs :: integer() >= 0,
4310 Secs :: integer() >= 0,
4311 MicroSecs :: integer() >= 0}
4312 Warning:
4314 This function is deprecated. Do not use it.
4315 For more information, see section Time and Time Correction in
4317 the User's Guide. Specifically, section Dos and Dont's de‐
4318 scribes what to use instead of erlang:now/0.
4319 Returns the tuple {MegaSecs, Secs, MicroSecs}, which is the
4322 elapsed time since 00:00 GMT, January 1, 1970 (zero hour), if
4323 provided by the underlying OS. Otherwise some other point in
4324 time is chosen. It is also guaranteed that the following calls
4325 to this BIF return continuously increasing values. Hence, the
4326 return value from erlang:now/0 can be used to generate unique
4327 time stamps. If it is called in a tight loop on a fast machine,
4328 the time of the node can become skewed.
4329 Can only be used to check the local time of day if the time-zone
4331 information of the underlying OS is properly configured.
4332 open_port(PortName, PortSettings) -> port()
4334 Types:
4336 PortName =
4338 {spawn, Command :: string() | binary()} |
4339 {spawn_driver, Command :: string() | binary()} |
4340 {spawn_executable, FileName :: file:name_all()} |
4341 {fd, In :: integer() >= 0, Out :: integer() >= 0}
4342 PortSettings = [Opt]
4343 Opt =
4344 {packet, N :: 1 | 2 | 4} |
4345 stream |
4346 {line, L :: integer() >= 0} |
4347 {cd, Dir :: string() | binary()} |
4348 {env,
4349 Env ::
4350 [{Name :: os:env_var_name(),
4351 Val :: os:env_var_value() | false}]} |
4352 {args, [string() | binary()]} |
4353 {arg0, string() | binary()} |
4354 exit_status | use_stdio | nouse_stdio | stderr_to_stdout
4355 |
4356 in | out | binary | eof |
4357 {parallelism, Boolean :: boolean()} |
4358 hide |
4359 {busy_limits_port,
4360 {integer() >= 0, integer() >= 0} | disabled} |
4361 {busy_limits_msgq,
4362 {integer() >= 0, integer() >= 0} | disabled}
4363 Returns a port identifier as the result of opening a new Erlang
4365 port. A port can be seen as an external Erlang process.
4366 The name of the executable as well as the arguments specifed in
4368 cd, env, args, and arg0 are subject to Unicode filename transla‐
4369 tion if the system is running in Unicode filename mode. To avoid
4370 translation or to force, for example UTF-8, supply the exe‐
4371 cutable and/or arguments as a binary in the correct encoding.
4372 For details, see the module file(3), the function file:na‐
4373 tive_name_encoding/0 in Kernel, and the Using Unicode in Erlang
4374 User's Guide.
4375 Note:
4377 The characters in the name (if specified as a list) can only be
4378 > 255 if the Erlang virtual machine is started in Unicode file‐
4379 name translation mode. Otherwise the name of the executable is
4380 limited to the ISO Latin-1 character set.
4381 PortNames:
4384 {spawn, Command}:
4386 Starts an external program. Command is the name of the ex‐
4387 ternal program to be run. Command runs outside the Erlang
4388 work space unless an Erlang driver with the name Command is
4389 found. If found, that driver is started. A driver runs in
4390 the Erlang work space, which means that it is linked with
4391 the Erlang runtime system.
4392 For external programs, PATH is searched (or an equivalent
4394 method is used to find programs, depending on the OS). This
4395 is done by invoking the shell on certain platforms. The
4396 first space-separated token of the command is considered as
4397 the name of the executable (or driver). This (among other
4398 things) makes this option unsuitable for running programs
4399 with spaces in filenames or directory names. If spaces in
4400 executable filenames are desired, use {spawn_executable,
4401 Command} instead.
4402 {spawn_driver, Command}:
4404 Works like {spawn, Command}, but demands the first (space-
4405 separated) token of the command to be the name of a loaded
4406 driver. If no driver with that name is loaded, a badarg er‐
4407 ror is raised.
4408 {spawn_executable, FileName}:
4410 Works like {spawn, FileName}, but only runs external exe‐
4411 cutables. FileName in its whole is used as the name of the
4412 executable, including any spaces. If arguments are to be
4413 passed, the PortSettings args and arg0 can be used.
4414 The shell is usually not invoked to start the program, it is
4416 executed directly. PATH (or equivalent) is not searched. To
4417 find a program in PATH to execute, use os:find_executable/1.
4418 Only if a shell script or .bat file is executed, the appro‐
4420 priate command interpreter is invoked implicitly, but there
4421 is still no command-argument expansion or implicit PATH
4422 search.
4423 If FileName cannot be run, an error exception is raised,
4425 with the POSIX error code as the reason. The error reason
4426 can differ between OSs. Typically the error enoent is raised
4427 when an attempt is made to run a program that is not found
4428 and eacces is raised when the specified file is not exe‐
4429 cutable.
4430 {fd, In, Out}:
4432 Allows an Erlang process to access any currently opened file
4433 descriptors used by Erlang. The file descriptor In can be
4434 used for standard input, and the file descriptor Out for
4435 standard output. It is only used for various servers in the
4436 Erlang OS (shell and user). Hence, its use is limited.
4437 PortSettings is a list of settings for the port. The valid set‐
4439 tings are as follows:
4440 {packet, N}:
4442 Messages are preceded by their length, sent in N bytes, with
4443 the most significant byte first. The valid values for N are
4444 1, 2, and 4.
4445 stream:
4447 Output messages are sent without packet lengths. A user-de‐
4448 fined protocol must be used between the Erlang process and
4449 the external object.
4450 {line, L}:
4452 Messages are delivered on a per line basis. Each line (de‐
4453 limited by the OS-dependent newline sequence) is delivered
4454 in a single message. The message data format is {Flag,
4455 Line}, where Flag is eol or noeol, and Line is the data de‐
4456 livered (without the newline sequence).
4457 L specifies the maximum line length in bytes. Lines longer
4459 than this are delivered in more than one message, with Flag
4460 set to noeol for all but the last message. If end of file is
4461 encountered anywhere else than immediately following a new‐
4462 line sequence, the last line is also delivered with Flag set
4463 to noeol. Otherwise lines are delivered with Flag set to
4464 eol.
4465 The {packet, N} and {line, L} settings are mutually exclu‐
4467 sive.
4468 {cd, Dir}:
4470 Only valid for {spawn, Command} and {spawn_executable, File‐
4471 Name}. The external program starts using Dir as its working
4472 directory. Dir must be a string.
4473 {env, Env}:
4475 Types:
4476 Name = os:env_var_name()
4477 Val = os:env_var_value() | false
4478 Env = [{Name, Val}]
4479 Only valid for {spawn, Command}, and {spawn_executable,
4481 FileName}. The environment of the started process is ex‐
4482 tended using the environment specifications in Env.
4483 Env is to be a list of tuples {Name, Val}, where Name is the
4485 name of an environment variable, and Val is the value it is
4486 to have in the spawned port process. Both Name and Val must
4487 be strings. The one exception is Val being the atom false
4488 (in analogy with os:getenv/1, which removes the environment
4489 variable.
4490 For information about encoding requirements, see documenta‐
4492 tion of the types for Name and Val.
4493 {args, [ string() | binary() ]}:
4495 Only valid for {spawn_executable, FileName} and specifies
4496 arguments to the executable. Each argument is specified as a
4497 separate string and (on Unix) eventually ends up as one ele‐
4498 ment each in the argument vector. On other platforms, a sim‐
4499 ilar behavior is mimicked.
4500 The arguments are not expanded by the shell before they are
4502 supplied to the executable. Most notably this means that
4503 file wildcard expansion does not occur. To expand wildcards
4504 for the arguments, use filelib:wildcard/1. Notice that even
4505 if the program is a Unix shell script, meaning that the
4506 shell ultimately is invoked, wildcard expansion does not oc‐
4507 cur, and the script is provided with the untouched argu‐
4508 ments. On Windows, wildcard expansion is always up to the
4509 program itself, therefore this is not an issue.
4510 The executable name (also known as argv[0]) is not to be
4512 specified in this list. The proper executable name is auto‐
4513 matically used as argv[0], where applicable.
4514 If you explicitly want to set the program name in the argu‐
4516 ment vector, option arg0 can be used.
4517 {arg0, string() | binary()}:
4519 Only valid for {spawn_executable, FileName} and explicitly
4520 specifies the program name argument when running an exe‐
4521 cutable. This can in some circumstances, on some OSs, be de‐
4522 sirable. How the program responds to this is highly system-
4523 dependent and no specific effect is guaranteed.
4524 exit_status:
4526 Only valid for {spawn, Command}, where Command refers to an
4527 external program, and for {spawn_executable, FileName}.
4528 When the external process connected to the port exits, a
4530 message of the form {Port,{exit_status,Status}} is sent to
4531 the connected process, where Status is the exit status of
4532 the external process. If the program aborts on Unix, the
4533 same convention is used as the shells do (that is, 128+sig‐
4534 nal).
4535 If option eof is specified also, the messages eof and
4537 exit_status appear in an unspecified order.
4538 If the port program closes its stdout without exiting, op‐
4540 tion exit_status does not work.
4541 use_stdio:
4543 Only valid for {spawn, Command} and {spawn_executable, File‐
4544 Name}. It allows the standard input and output (file de‐
4545 scriptors 0 and 1) of the spawned (Unix) process for commu‐
4546 nication with Erlang.
4547 nouse_stdio:
4549 The opposite of use_stdio. It uses file descriptors 3 and 4
4550 for communication with Erlang.
4551 stderr_to_stdout:
4553 Affects ports to external programs. The executed program
4554 gets its standard error file redirected to its standard out‐
4555 put file. stderr_to_stdout and nouse_stdio are mutually ex‐
4556 clusive.
4557 overlapped_io:
4559 Affects ports to external programs on Windows only. The
4560 standard input and standard output handles of the port pro‐
4561 gram are, if this option is supplied, opened with flag
4562 FILE_FLAG_OVERLAPPED, so that the port program can (and
4563 must) do overlapped I/O on its standard handles. This is not
4564 normally the case for simple port programs, but an option of
4565 value for the experienced Windows programmer. On all other
4566 platforms, this option is silently discarded.
4567 in:
4569 The port can only be used for input.
4570 out:
4572 The port can only be used for output.
4573 binary:
4575 All I/O from the port is binary data objects as opposed to
4576 lists of bytes.
4577 eof:
4579 The port is not closed at the end of the file and does not
4580 produce an exit signal. Instead, it remains open and a
4581 {Port, eof} message is sent to the process holding the port.
4582 hide:
4584 When running on Windows, suppresses creation of a new con‐
4585 sole window when spawning the port program. (This option has
4586 no effect on other platforms.)
4587 {parallelism, Boolean}:
4589 Sets scheduler hint for port parallelism. If set to true,
4592 the virtual machine schedules port tasks; when doing so, it
4593 improves parallelism in the system. If set to false, the
4594 virtual machine tries to perform port tasks immediately, im‐
4595 proving latency at the expense of parallelism. The default
4596 can be set at system startup by passing command-line argu‐
4597 ment +spp to erl(1).
4598 {busy_limits_port, {Low, High} | disabled}:
4600 Sets limits that will be used for controlling the busy state
4601 of the port.
4602 When the ports internal output queue size becomes larger
4604 than or equal to High bytes, it enters the busy state. When
4605 it becomes less than Low bytes it leaves the busy state.
4606 When the port is in the busy state, processes sending com‐
4607 mands to it will be suspended until the port leaves the busy
4608 state. Commands are in this context either Port ! {Owner,
4609 {command, Data}} or port_command/[2,3].
4610 The Low limit is automatically adjusted to the same as High
4612 if it is set larger then High. Valid range of values for Low
4613 and High is [1, (1 bsl (8*erlang:system_info(wordsize)))-2].
4614 If the atom disabled is passed, the port will never enter
4615 the busy state.
4616 The defaults are Low = 4096 and High = 8192.
4618 Note that this option is only valid when spawning an exe‐
4620 cutable (port program) by opening the spawn driver and when
4621 opening the fd driver. This option will cause a failure with
4622 a badarg exception when opening other drivers.
4623 {busy_limits_msgq, {Low, High} | disabled}:
4625 Sets limits that will be used for controlling the busy state
4626 of the port message queue.
4627 When the ports message queue size becomes larger than or
4629 equal to High bytes it enters the busy state. When it be‐
4630 comes less than Low bytes it leaves the busy state. When the
4631 port message queue is in the busy state, processes sending
4632 commands to it will be suspended until the port message
4633 queue leaves the busy state. Commands are in this context
4634 either Port ! {Owner, {command, Data}} or port_com‐
4635 mand/[2,3].
4636 The Low limit is automatically adjusted to the same as High
4638 if it is set larger then High. Valid range of values for Low
4639 and High is [1, (1 bsl (8*erlang:system_info(wordsize)))-2].
4640 If the atom disabled is passed, the port message queue will
4641 never enter the busy state.
4642 Note that if the driver statically has disabled the use of
4644 this feature, a failure with a badarg exception will be
4645 raised unless this option also is set to disable or not
4646 passed at all.
4647 The defaults are Low = 4096 and High = 8192 unless the
4649 driver itself does modifications of these values.
4650 Note that the driver might fail if it also adjust these lim‐
4652 its by itself and you have disabled this feature.
4653 The spawn driver (used when spawning an executable) and the
4655 fd driver do not disable this feature and do not adjust
4656 these limits by themselves.
4657 For more information see the documentation
4659 erl_drv_busy_msgq_limits().
4660 Default is stream for all port types and use_stdio for spawned
4662 ports.
4663 Failure: if the port cannot be opened, the exit reason is
4665 badarg, system_limit, or the POSIX error code that most closely
4666 describes the error, or einval if no POSIX code is appropriate:
4667 badarg:
4669 Bad input arguments to open_port.
4670 system_limit:
4672 All available ports in the Erlang emulator are in use.
4673 enomem:
4675 Not enough memory to create the port.
4676 eagain:
4678 No more available OS processes.
4679 enametoolong:
4681 Too long external command.
4682 emfile:
4684 No more available file descriptors (for the OS process that
4685 the Erlang emulator runs in).
4686 enfile:
4688 Full file table (for the entire OS).
4689 eacces:
4691 Command specified in {spawn_executable, Command} does not
4692 point out an executable file.
4693 enoent:
4695 FileName specified in {spawn_executable, FileName} does not
4696 point out an existing file.
4697 During use of a port opened using {spawn, Name}, {spawn_driver,
4699 Name}, or {spawn_executable, Name}, errors arising when sending
4700 messages to it are reported to the owning process using signals
4701 of the form {'EXIT', Port, PosixCode}. For the possible values
4702 of PosixCode, see file(3).
4703 The maximum number of ports that can be open at the same time
4705 can be configured by passing command-line flag +Q to erl(1).
4706 erlang:phash(Term, Range) -> Hash
4708 Types:
4710 Term = term()
4712 Range = Hash = integer() >= 1
4713 Range = 1..2^32, Hash = 1..Range
4714 Warning:
4716 This function is deprecated as erlang:phash2/2 should be used
4717 for new code. Note that erlang:phash(X,N) is not necessary equal
4718 to erlang:phash2(X,N)
4719 Portable hash function that gives the same hash for the same Er‐
4722 lang term regardless of machine architecture and ERTS version
4723 (the BIF was introduced in ERTS 4.9.1.1). The function returns a
4724 hash value for Term within the range 1..Range. The maximum value
4725 for Range is 2^32.
4726 erlang:phash2(Term) -> Hash
4728 erlang:phash2(Term, Range) -> Hash
4730 Types:
4732 Term = term()
4734 Range = integer() >= 1
4735 1..2^32
4736 Hash = integer() >= 0
4737 0..Range-1
4738 Portable hash function that gives the same hash for the same Er‐
4740 lang term regardless of machine architecture and ERTS version
4741 (the BIF was introduced in ERTS 5.2). The function returns a
4742 hash value for Term within the range 0..Range-1. The maximum
4743 value for Range is 2^32. When without argument Range, a value in
4744 the range 0..2^27-1 is returned.
4745 This BIF is always to be used for hashing terms. It distributes
4747 small integers better than phash/2, and it is faster for bignums
4748 and binaries.
4749 Notice that the range 0..Range-1 is different from the range of
4751 phash/2, which is 1..Range.
4752 pid_to_list(Pid) -> string()
4754 Types:
4756 Pid = pid()
4758 Returns a string corresponding to the text representation of
4760 Pid. Example:
4761 > erlang:pid_to_list(self()).
4763 "<0.85.0>"
4764 Note:
4766 The creation for the node is not included in the list represen‐
4767 tation of Pid. This means that processes in different incarna‐
4768 tions of a node with a specific name can get the same list rep‐
4769 resentation.
4770 erlang:port_call(Port, Operation, Data) -> term()
4773 Types:
4775 Port = port() | atom()
4777 Operation = integer()
4778 Data = term()
4779 Performs a synchronous call to a port. The meaning of Operation
4781 and Data depends on the port, that is, on the port driver. Not
4782 all port drivers support this feature.
4783 Port is a port identifier, referring to a driver.
4785 Operation is an integer, which is passed on to the driver.
4787 Data is any Erlang term. This data is converted to binary term
4789 format and sent to the port.
4790 Returns a term from the driver. The meaning of the returned data
4792 also depends on the port driver.
4793 Failures:
4795 badarg:
4797 If Port is not an identifier of an open port, or the regis‐
4798 tered name of an open port. If the calling process was pre‐
4799 viously linked to the closed port, identified by Port, the
4800 exit signal from the port is guaranteed to be delivered be‐
4801 fore this badarg exception occurs.
4802 badarg:
4804 If Operation does not fit in a 32-bit integer.
4805 badarg:
4807 If the port driver does not support synchronous control op‐
4808 erations.
4809 badarg:
4811 If the port driver so decides for any reason (probably some‐
4812 thing wrong with Operation or Data).
4813 Warning:
4815 Do not call port_call with an unknown Port identifier and ex‐
4816 pect badarg exception. Any undefined behavior is possible (in‐
4817 cluding node crash) depending on how the port driver inter‐
4818 prets the supplied arguments.
4819 port_close(Port) -> true
4822 Types:
4824 Port = port() | atom()
4826 Closes an open port. Roughly the same as Port ! {self(), close}
4828 except for the error behavior (see below), being synchronous,
4829 and that the port does not reply with {Port, closed}. Any
4830 process can close a port with port_close/1, not only the port
4831 owner (the connected process). If the calling process is linked
4832 to the port identified by Port, the exit signal from the port is
4833 guaranteed to be delivered before port_close/1 returns.
4834 For comparison: Port ! {self(), close} only fails with badarg if
4836 Port does not refer to a port or a process. If Port is a closed
4837 port, nothing happens. If Port is an open port and the calling
4838 process is the port owner, the port replies with {Port, closed}
4839 when all buffers have been flushed and the port really closes.
4840 If the calling process is not the port owner, the port owner
4841 fails with badsig.
4842 Notice that any process can close a port using Port ! {Por‐
4844 tOwner, close} as if it itself was the port owner, but the reply
4845 always goes to the port owner.
4846 As from Erlang/OTP R16, Port ! {PortOwner, close} is truly asyn‐
4848 chronous. Notice that this operation has always been documented
4849 as an asynchronous operation, while the underlying implementa‐
4850 tion has been synchronous. port_close/1 is however still fully
4851 synchronous because of its error behavior.
4852 Failure: badarg if Port is not an identifier of an open port, or
4854 the registered name of an open port. If the calling process was
4855 previously linked to the closed port, identified by Port, the
4856 exit signal from the port is guaranteed to be delivered before
4857 this badarg exception occurs.
4858 port_command(Port, Data) -> true
4860 Types:
4862 Port = port() | atom()
4864 Data = iodata()
4865 Sends data to a port. Same as Port ! {PortOwner, {command,
4867 Data}} except for the error behavior and being synchronous (see
4868 below). Any process can send data to a port with port_command/2,
4869 not only the port owner (the connected process).
4870 For comparison: Port ! {PortOwner, {command, Data}} only fails
4872 with badarg if Port does not refer to a port or a process. If
4873 Port is a closed port, the data message disappears without a
4874 sound. If Port is open and the calling process is not the port
4875 owner, the port owner fails with badsig. The port owner fails
4876 with badsig also if Data is an invalid I/O list.
4877 Notice that any process can send to a port using Port ! {Por‐
4879 tOwner, {command, Data}} as if it itself was the port owner.
4880 If the port is busy, the calling process is suspended until the
4882 port is not busy any more.
4883 As from Erlang/OTP R16, Port ! {PortOwner, {command, Data}} is
4885 truly asynchronous. Notice that this operation has always been
4886 documented as an asynchronous operation, while the underlying
4887 implementation has been synchronous. port_command/2 is however
4888 still fully synchronous because of its error behavior.
4889 Failures:
4891 badarg:
4893 If Port is not an identifier of an open port, or the regis‐
4894 tered name of an open port. If the calling process was pre‐
4895 viously linked to the closed port, identified by Port, the
4896 exit signal from the port is guaranteed to be delivered be‐
4897 fore this badarg exception occurs.
4898 badarg:
4900 If Data is an invalid I/O list.
4901 Warning:
4903 Do not send data to an unknown port. Any undefined behavior is
4904 possible (including node crash) depending on how the port driver
4905 interprets the data.
4906 port_command(Port, Data, OptionList) -> boolean()
4909 Types:
4911 Port = port() | atom()
4913 Data = iodata()
4914 Option = force | nosuspend
4915 OptionList = [Option]
4916 Sends data to a port. port_command(Port, Data, []) equals
4918 port_command(Port, Data).
4919 If the port command is aborted, false is returned, otherwise
4921 true.
4922 If the port is busy, the calling process is suspended until the
4924 port is not busy anymore.
4925 Options:
4927 force:
4929 The calling process is not suspended if the port is busy,
4930 instead the port command is forced through. The call fails
4931 with a notsup exception if the driver of the port does not
4932 support this. For more information, see driver flag
4933 ERL_DRV_FLAG_SOFT_BUSY.
4934 nosuspend:
4936 The calling process is not suspended if the port is busy,
4937 instead the port command is aborted and false is returned.
4938 Note:
4940 More options can be added in a future release.
4941 Failures:
4944 badarg:
4946 If Port is not an identifier of an open port, or the regis‐
4947 tered name of an open port. If the calling process was pre‐
4948 viously linked to the closed port, identified by Port, the
4949 exit signal from the port is guaranteed to be delivered be‐
4950 fore this badarg exception occurs.
4951 badarg:
4953 If Data is an invalid I/O list.
4954 badarg:
4956 If OptionList is an invalid option list.
4957 notsup:
4959 If option force has been passed, but the driver of the port
4960 does not allow forcing through a busy port.
4961 Warning:
4963 Do not send data to an unknown port. Any undefined behavior is
4964 possible (including node crash) depending on how the port driver
4965 interprets the data.
4966 port_connect(Port, Pid) -> true
4969 Types:
4971 Port = port() | atom()
4973 Pid = pid()
4974 Sets the port owner (the connected port) to Pid. Roughly the
4976 same as Port ! {Owner, {connect, Pid}} except for the following:
4977 * The error behavior differs, see below.
4979 * The port does not reply with {Port,connected}.
4981 * port_connect/1 is synchronous, see below.
4983 * The new port owner gets linked to the port.
4985 The old port owner stays linked to the port and must call un‐
4987 link(Port) if this is not desired. Any process can set the port
4988 owner to be any process with port_connect/2.
4989 For comparison: Port ! {self(), {connect, Pid}} only fails with
4991 badarg if Port does not refer to a port or a process. If Port is
4992 a closed port, nothing happens. If Port is an open port and the
4993 calling process is the port owner, the port replies with {Port,
4994 connected} to the old port owner. Notice that the old port owner
4995 is still linked to the port, while the new is not. If Port is an
4996 open port and the calling process is not the port owner, the
4997 port owner fails with badsig. The port owner fails with badsig
4998 also if Pid is not an existing local process identifier.
4999 Notice that any process can set the port owner using Port !
5001 {PortOwner, {connect, Pid}} as if it itself was the port owner,
5002 but the reply always goes to the port owner.
5003 As from Erlang/OTP R16, Port ! {PortOwner, {connect, Pid}} is
5005 truly asynchronous. Notice that this operation has always been
5006 documented as an asynchronous operation, while the underlying
5007 implementation has been synchronous. port_connect/2 is however
5008 still fully synchronous because of its error behavior.
5009 Failures:
5011 badarg:
5013 If Port is not an identifier of an open port, or the regis‐
5014 tered name of an open port. If the calling process was pre‐
5015 viously linked to the closed port, identified by Port, the
5016 exit signal from the port is guaranteed to be delivered be‐
5017 fore this badarg exception occurs.
5018 badarg:
5020 If the process identified by Pid is not an existing local
5021 process.
5022 port_control(Port, Operation, Data) -> iodata() | binary()
5024 Types:
5026 Port = port() | atom()
5028 Operation = integer()
5029 Data = iodata()
5030 Performs a synchronous control operation on a port. The meaning
5032 of Operation and Data depends on the port, that is, on the port
5033 driver. Not all port drivers support this control feature.
5034 Returns a list of integers in the range 0..255, or a binary, de‐
5036 pending on the port driver. The meaning of the returned data
5037 also depends on the port driver.
5038 Failures:
5040 badarg:
5042 If Port is not an open port or the registered name of an
5043 open port.
5044 badarg:
5046 If Operation cannot fit in a 32-bit integer.
5047 badarg:
5049 If the port driver does not support synchronous control op‐
5050 erations.
5051 badarg:
5053 If the port driver so decides for any reason (probably
5054 something wrong with Operation or Data).
5055 Warning:
5057 Do not call port_control/3 with an unknown Port identifier and
5058 expect badarg exception. Any undefined behavior is possible
5059 (including node crash) depending on how the port driver inter‐
5060 prets the supplied arguments.
5061 erlang:port_info(Port) -> Result
5064 Types:
5066 Port = port() | atom()
5068 ResultItem =
5069 {registered_name, RegisteredName :: atom()} |
5070 {id, Index :: integer() >= 0} |
5071 {connected, Pid :: pid()} |
5072 {links, Pids :: [pid()]} |
5073 {name, String :: string()} |
5074 {input, Bytes :: integer() >= 0} |
5075 {output, Bytes :: integer() >= 0} |
5076 {os_pid, OsPid :: integer() >= 0 | undefined}
5077 Result = [ResultItem] | undefined
5078 Returns a list containing tuples with information about Port, or
5080 undefined if the port is not open. The order of the tuples is
5081 undefined, and all the tuples are not mandatory. If the port is
5082 closed and the calling process was previously linked to the
5083 port, the exit signal from the port is guaranteed to be deliv‐
5084 ered before port_info/1 returns undefined.
5085 The result contains information about the following Items:
5087 * registered_name (if the port has a registered name)
5089 * id
5091 * connected
5093 * links
5095 * name
5097 * input
5099 * output
5101 For more information about the different Items, see port_info/2.
5103 Failure: badarg if Port is not a local port identifier, or an
5105 atom.
5106 erlang:port_info(Port, Item :: connected) ->
5108 {connected, Pid} | undefined
5109 Types:
5111 Port = port() | atom()
5113 Pid = pid()
5114 Pid is the process identifier of the process connected to the
5116 port.
5117 If the port identified by Port is not open, undefined is re‐
5119 turned. If the port is closed and the calling process was previ‐
5120 ously linked to the port, the exit signal from the port is guar‐
5121 anteed to be delivered before port_info/2 returns undefined.
5122 Failure: badarg if Port is not a local port identifier, or an
5124 atom.
5125 erlang:port_info(Port, Item :: id) -> {id, Index} | undefined
5127 Types:
5129 Port = port() | atom()
5131 Index = integer() >= 0
5132 Index is the internal index of the port. This index can be used
5134 to separate ports.
5135 If the port identified by Port is not open, undefined is re‐
5137 turned. If the port is closed and the calling process was previ‐
5138 ously linked to the port, the exit signal from the port is guar‐
5139 anteed to be delivered before port_info/2 returns undefined.
5140 Failure: badarg if Port is not a local port identifier, or an
5142 atom.
5143 erlang:port_info(Port, Item :: input) ->
5145 {input, Bytes} | undefined
5146 Types:
5148 Port = port() | atom()
5150 Bytes = integer() >= 0
5151 Bytes is the total number of bytes read from the port.
5153 If the port identified by Port is not open, undefined is re‐
5155 turned. If the port is closed and the calling process was previ‐
5156 ously linked to the port, the exit signal from the port is guar‐
5157 anteed to be delivered before port_info/2 returns undefined.
5158 Failure: badarg if Port is not a local port identifier, or an
5160 atom.
5161 erlang:port_info(Port, Item :: links) -> {links, Pids} | undefined
5163 Types:
5165 Port = port() | atom()
5167 Pids = [pid()]
5168 Pids is a list of the process identifiers of the processes that
5170 the port is linked to.
5171 If the port identified by Port is not open, undefined is re‐
5173 turned. If the port is closed and the calling process was previ‐
5174 ously linked to the port, the exit signal from the port is guar‐
5175 anteed to be delivered before port_info/2 returns undefined.
5176 Failure: badarg if Port is not a local port identifier, or an
5178 atom.
5179 erlang:port_info(Port, Item :: locking) ->
5181 {locking, Locking} | undefined
5182 Types:
5184 Port = port() | atom()
5186 Locking = false | port_level | driver_level
5187 Locking is one of the following:
5189 * port_level (port-specific locking)
5191 * driver_level (driver-specific locking)
5193 Notice that these results are highly implementation-specific and
5195 can change in a future release.
5196 If the port identified by Port is not open, undefined is re‐
5198 turned. If the port is closed and the calling process was previ‐
5199 ously linked to the port, the exit signal from the port is guar‐
5200 anteed to be delivered before port_info/2 returns undefined.
5201 Failure: badarg if Port is not a local port identifier, or an
5203 atom.
5204 erlang:port_info(Port, Item :: memory) ->
5206 {memory, Bytes} | undefined
5207 Types:
5209 Port = port() | atom()
5211 Bytes = integer() >= 0
5212 Bytes is the total number of bytes allocated for this port by
5214 the runtime system. The port itself can have allocated memory
5215 that is not included in Bytes.
5216 If the port identified by Port is not open, undefined is re‐
5218 turned. If the port is closed and the calling process was previ‐
5219 ously linked to the port, the exit signal from the port is guar‐
5220 anteed to be delivered before port_info/2 returns undefined.
5221 Failure: badarg if Port is not a local port identifier, or an
5223 atom.
5224 erlang:port_info(Port, Item :: monitors) ->
5226 {monitors, Monitors} | undefined
5227 Types:
5229 Port = port() | atom()
5231 Monitors = [{process, pid()}]
5232 Monitors represent processes monitored by this port.
5234 If the port identified by Port is not open, undefined is re‐
5236 turned. If the port is closed and the calling process was previ‐
5237 ously linked to the port, the exit signal from the port is guar‐
5238 anteed to be delivered before port_info/2 returns undefined.
5239 Failure: badarg if Port is not a local port identifier, or an
5241 atom.
5242 erlang:port_info(Port, Item :: monitored_by) ->
5244 {monitored_by, MonitoredBy} | undefined
5245 Types:
5247 Port = port() | atom()
5249 MonitoredBy = [pid()]
5250 Returns list of pids that are monitoring given port at the mo‐
5252 ment.
5253 If the port identified by Port is not open, undefined is re‐
5255 turned. If the port is closed and the calling process was previ‐
5256 ously linked to the port, the exit signal from the port is guar‐
5257 anteed to be delivered before port_info/2 returns undefined.
5258 Failure: badarg if Port is not a local port identifier, or an
5260 atom.
5261 erlang:port_info(Port, Item :: name) -> {name, Name} | undefined
5263 Types:
5265 Port = port() | atom()
5267 Name = string()
5268 Name is the command name set by open_port/2.
5270 If the port identified by Port is not open, undefined is re‐
5272 turned. If the port is closed and the calling process was previ‐
5273 ously linked to the port, the exit signal from the port is guar‐
5274 anteed to be delivered before port_info/2 returns undefined.
5275 Failure: badarg if Port is not a local port identifier, or an
5277 atom.
5278 erlang:port_info(Port, Item :: os_pid) ->
5280 {os_pid, OsPid} | undefined
5281 Types:
5283 Port = port() | atom()
5285 OsPid = integer() >= 0 | undefined
5286 OsPid is the process identifier (or equivalent) of an OS process
5288 created with open_port({spawn | spawn_executable, Command}, Op‐
5289 tions). If the port is not the result of spawning an OS process,
5290 the value is undefined.
5291 If the port identified by Port is not open, undefined is re‐
5293 turned. If the port is closed and the calling process was previ‐
5294 ously linked to the port, the exit signal from the port is guar‐
5295 anteed to be delivered before port_info/2 returns undefined.
5296 Failure: badarg if Port is not a local port identifier, or an
5298 atom.
5299 erlang:port_info(Port, Item :: output) ->
5301 {output, Bytes} | undefined
5302 Types:
5304 Port = port() | atom()
5306 Bytes = integer() >= 0
5307 Bytes is the total number of bytes written to the port from Er‐
5309 lang processes using port_command/2, port_command/3, or Port !
5310 {Owner, {command, Data}.
5311 If the port identified by Port is not open, undefined is re‐
5313 turned. If the port is closed and the calling process was previ‐
5314 ously linked to the port, the exit signal from the port is guar‐
5315 anteed to be delivered before port_info/2 returns undefined.
5316 Failure: badarg if Port is not a local port identifier, or an
5318 atom.
5319 erlang:port_info(Port, Item :: parallelism) ->
5321 {parallelism, Boolean} | undefined
5322 Types:
5324 Port = port() | atom()
5326 Boolean = boolean()
5327 Boolean corresponds to the port parallelism hint used by this
5329 port. For more information, see option parallelism of
5330 open_port/2.
5331 erlang:port_info(Port, Item :: queue_size) ->
5333 {queue_size, Bytes} | undefined
5334 Types:
5336 Port = port() | atom()
5338 Bytes = integer() >= 0
5339 Bytes is the total number of bytes queued by the port using the
5341 ERTS driver queue implementation.
5342 If the port identified by Port is not open, undefined is re‐
5344 turned. If the port is closed and the calling process was previ‐
5345 ously linked to the port, the exit signal from the port is guar‐
5346 anteed to be delivered before port_info/2 returns undefined.
5347 Failure: badarg if Port is not a local port identifier, or an
5349 atom.
5350 erlang:port_info(Port, Item :: registered_name) ->
5352 {registered_name, RegisteredName} |
5353 [] | undefined
5354 Types:
5356 Port = port() | atom()
5358 RegisteredName = atom()
5359 RegisteredName is the registered name of the port. If the port
5361 has no registered name, [] is returned.
5362 If the port identified by Port is not open, undefined is re‐
5364 turned. If the port is closed and the calling process was previ‐
5365 ously linked to the port, the exit signal from the port is guar‐
5366 anteed to be delivered before port_info/2 returns undefined.
5367 Failure: badarg if Port is not a local port identifier, or an
5369 atom.
5370 port_to_list(Port) -> string()
5372 Types:
5374 Port = port()
5376 Returns a string corresponding to the text representation of the
5378 port identifier Port.
5379 erlang:ports() -> [port()]
5381 Returns a list of port identifiers corresponding to all the
5383 ports existing on the local node.
5384 Notice that an exiting port exists, but is not open.
5386 pre_loaded() -> [module()]
5388 Returns a list of Erlang modules that are preloaded in the run-
5390 time system. Pre-loaded modules are Erlang modules that are
5391 needed to bootstrap the system to load the first Erlang modules
5392 from either disk or by using erl_boot_server.
5393 erlang:process_display(Pid, Type) -> true
5395 Types:
5397 Pid = pid()
5399 Type = backtrace
5400 Writes information about the local process Pid on standard er‐
5402 ror. The only allowed value for the atom Type is backtrace,
5403 which shows the contents of the call stack, including informa‐
5404 tion about the call chain, with the current function printed
5405 first. The format of the output is not further defined.
5406 process_flag(Flag :: trap_exit, Boolean) -> OldBoolean
5408 Types:
5410 Boolean = OldBoolean = boolean()
5412 When trap_exit is set to true, exit signals arriving to a
5414 process are converted to {'EXIT', From, Reason} messages, which
5415 can be received as ordinary messages. If trap_exit is set to
5416 false, the process exits if it receives an exit signal other
5417 than normal and the exit signal is propagated to its linked pro‐
5418 cesses. Application processes are normally not to trap exits.
5419 Returns the old value of the flag.
5421 See also exit/2.
5423 process_flag(Flag :: error_handler, Module) -> OldModule
5425 Types:
5427 Module = OldModule = atom()
5429 Used by a process to redefine the error handler for undefined
5431 function calls and undefined registered processes. Inexperienced
5432 users are not to use this flag, as code auto-loading depends on
5433 the correct operation of the error handling module.
5434 Returns the old value of the flag.
5436 process_flag(Flag :: fullsweep_after, FullsweepAfter) ->
5438 OldFullsweepAfter
5439 Types:
5441 FullsweepAfter = OldFullsweepAfter = integer() >= 0
5443 Changes the maximum number of generational collections before
5445 forcing a fullsweep for the calling process.
5446 Returns the old value of the flag.
5448 process_flag(Flag :: min_heap_size, MinHeapSize) -> OldMinHeapSize
5450 Types:
5452 MinHeapSize = OldMinHeapSize = integer() >= 0
5454 Changes the minimum heap size for the calling process.
5456 Returns the old value of the flag.
5458 process_flag(Flag :: min_bin_vheap_size, MinBinVHeapSize) ->
5460 OldMinBinVHeapSize
5461 Types:
5463 MinBinVHeapSize = OldMinBinVHeapSize = integer() >= 0
5465 Changes the minimum binary virtual heap size for the calling
5467 process.
5468 Returns the old value of the flag.
5470 process_flag(Flag :: max_heap_size, MaxHeapSize) -> OldMaxHeapSize
5472 Types:
5474 MaxHeapSize = OldMaxHeapSize = max_heap_size()
5476 max_heap_size() =
5477 integer() >= 0 |
5478 #{size => integer() >= 0,
5479 kill => boolean(),
5480 error_logger => boolean()}
5481 This flag sets the maximum heap size for the calling process. If
5483 MaxHeapSize is an integer, the system default values for kill
5484 and error_logger are used.
5485 size:
5487 The maximum size in words of the process. If set to zero,
5488 the heap size limit is disabled. badarg is be thrown if the
5489 value is smaller than min_heap_size. The size check is only
5490 done when a garbage collection is triggered.
5491 size is the entire heap of the process when garbage collec‐
5493 tion is triggered. This includes all generational heaps, the
5494 process stack, any messages that are considered to be part
5495 of the heap, and any extra memory that the garbage collector
5496 needs during collection.
5497 size is the same as can be retrieved using er‐
5499 lang:process_info(Pid, total_heap_size), or by adding
5500 heap_block_size, old_heap_block_size and mbuf_size from er‐
5501 lang:process_info(Pid, garbage_collection_info).
5502 kill:
5504 When set to true, the runtime system sends an untrappable
5505 exit signal with reason kill to the process if the maximum
5506 heap size is reached. The garbage collection that triggered
5507 the kill is not completed, instead the process exits as soon
5508 as possible. When set to false, no exit signal is sent to
5509 the process, instead it continues executing.
5510 If kill is not defined in the map, the system default will
5512 be used. The default system default is true. It can be
5513 changed by either option +hmaxk in erl(1), or erlang:sys‐
5514 tem_flag(max_heap_size, MaxHeapSize).
5515 error_logger:
5517 When set to true, the runtime system logs an error event via
5518 logger, containing details about the process when the maxi‐
5519 mum heap size is reached. One log event is sent each time
5520 the limit is reached.
5521 If error_logger is not defined in the map, the system de‐
5523 fault is used. The default system default is true. It can be
5524 changed by either the option +hmaxel int erl(1), or er‐
5525 lang:system_flag(max_heap_size, MaxHeapSize).
5526 The heap size of a process is quite hard to predict, especially
5528 the amount of memory that is used during the garbage collection.
5529 When contemplating using this option, it is recommended to first
5530 run it in production with kill set to false and inspect the log
5531 events to see what the normal peak sizes of the processes in the
5532 system is and then tune the value accordingly.
5533 process_flag(Flag :: message_queue_data, MQD) -> OldMQD
5535 Types:
5537 MQD = OldMQD = message_queue_data()
5539 message_queue_data() = off_heap | on_heap
5540 Determines how messages in the message queue are stored, as fol‐
5542 lows:
5543 off_heap:
5545 All messages in the message queue will be stored outside the
5546 process heap. This implies that no messages in the message
5547 queue will be part of a garbage collection of the process.
5548 on_heap:
5550 All messages in the message queue will eventually be placed
5551 on the process heap. They can, however, be temporarily
5552 stored off the heap. This is how messages have always been
5553 stored up until ERTS 8.0.
5554 The default value of the message_queue_data process flag is de‐
5556 termined by the command-line argument +hmqd in erl(1).
5557 If the process may potentially accumulate a large number of mes‐
5559 sages in its queue it is recommended to set the flag value to
5560 off_heap. This is due to the fact that the garbage collection of
5561 a process that has a large number of messages stored on the heap
5562 can become extremely expensive and the process can consume large
5563 amounts of memory. The performance of the actual message passing
5564 is, however, generally better when the flag value is on_heap.
5565 Changing the flag value causes any existing messages to be
5567 moved. The move operation is initiated, but not necessarily com‐
5568 pleted, by the time the function returns.
5569 Returns the old value of the flag.
5571 process_flag(Flag :: priority, Level) -> OldLevel
5573 Types:
5575 Level = OldLevel = priority_level()
5577 priority_level() = low | normal | high | max
5578 Sets the process priority. Level is an atom. Four priority lev‐
5580 els exist: low, normal, high, and max. Default is normal.
5581 Note:
5583 Priority level max is reserved for internal use in the Erlang
5584 runtime system, and is not to be used by others.
5585 Internally in each priority level, processes are scheduled in a
5588 round robin fashion.
5589 Execution of processes on priority normal and low are inter‐
5591 leaved. Processes on priority low are selected for execution
5592 less frequently than processes on priority normal.
5593 When runnable processes on priority high exist, no processes on
5595 priority low or normal are selected for execution. Notice how‐
5596 ever that this does not mean that no processes on priority low
5597 or normal can run when processes are running on priority high.
5598 When using multiple schedulers, more processes can be running in
5599 parallel than processes on priority high. That is, a low and a
5600 high priority process can execute at the same time.
5601 When runnable processes on priority max exist, no processes on
5603 priority low, normal, or high are selected for execution. As
5604 with priority high, processes on lower priorities can execute in
5605 parallel with processes on priority max.
5606 Scheduling is pre-emptive. Regardless of priority, a process is
5608 pre-empted when it has consumed more than a certain number of
5609 reductions since the last time it was selected for execution.
5610 Note:
5612 Do not depend on the scheduling to remain exactly as it is to‐
5613 day. Scheduling is likely to be changed in a future release to
5614 use available processor cores better.
5615 There is no automatic mechanism for avoiding priority inversion,
5618 such as priority inheritance or priority ceilings. When using
5619 priorities, take this into account and handle such scenarios by
5620 yourself.
5621 Making calls from a high priority process into code that you has
5623 no control over can cause the high priority process to wait for
5624 a process with lower priority. That is, effectively decreasing
5625 the priority of the high priority process during the call. Even
5626 if this is not the case with one version of the code that you
5627 have no control over, it can be the case in a future version of
5628 it. This can, for example, occur if a high priority process
5629 triggers code loading, as the code server runs on priority nor‐
5630 mal.
5631 Other priorities than normal are normally not needed. When other
5633 priorities are used, use them with care, especially priority
5634 high. A process on priority high is only to perform work for
5635 short periods. Busy looping for long periods in a high priority
5636 process causes most likely problems, as important OTP servers
5637 run on priority normal.
5638 Returns the old value of the flag.
5640 process_flag(Flag :: save_calls, N) -> OldN
5642 Types:
5644 N = OldN = 0..10000
5646 N must be an integer in the interval 0..10000. If N > 0, call
5648 saving is made active for the process. This means that informa‐
5649 tion about the N most recent global function calls, BIF calls,
5650 sends, and receives made by the process are saved in a list,
5651 which can be retrieved with process_info(Pid, last_calls). A
5652 global function call is one in which the module of the function
5653 is explicitly mentioned. Only a fixed amount of information is
5654 saved, as follows:
5655 * A tuple {Module, Function, Arity} for function calls
5657 * The atoms send, 'receive', and timeout for sends and re‐
5659 ceives ('receive' when a message is received and timeout
5660 when a receive times out)
5661 If N = 0, call saving is disabled for the process, which is the
5663 default. Whenever the size of the call saving list is set, its
5664 contents are reset.
5665 Returns the old value of the flag.
5667 process_flag(Flag :: sensitive, Boolean) -> OldBoolean
5669 Types:
5671 Boolean = OldBoolean = boolean()
5673 Sets or clears flag sensitive for the current process. When a
5675 process has been marked as sensitive by calling
5676 process_flag(sensitive, true), features in the runtime system
5677 that can be used for examining the data or inner working of the
5678 process are silently disabled.
5679 Features that are disabled include (but are not limited to) the
5681 following:
5682 * Tracing. Trace flags can still be set for the process, but
5684 no trace messages of any kind are generated. (If flag sensi‐
5685 tive is turned off, trace messages are again generated if
5686 any trace flags are set.)
5687 * Sequential tracing. The sequential trace token is propagated
5689 as usual, but no sequential trace messages are generated.
5690 process_info/1,2 cannot be used to read out the message queue or
5692 the process dictionary (both are returned as empty lists).
5693 Stack back-traces cannot be displayed for the process.
5695 In crash dumps, the stack, messages, and the process dictionary
5697 are omitted.
5698 If {save_calls,N} has been set for the process, no function
5700 calls are saved to the call saving list. (The call saving list
5701 is not cleared. Also, send, receive, and time-out events are
5702 still added to the list.)
5703 Returns the old value of the flag.
5705 process_flag(Pid, Flag, Value) -> OldValue
5707 Types:
5709 Pid = pid()
5711 Flag = save_calls
5712 Value = OldValue = integer() >= 0
5713 Sets certain flags for the process Pid, in the same manner as
5715 process_flag/2. Returns the old value of the flag. The valid
5716 values for Flag are only a subset of those allowed in
5717 process_flag/2, namely save_calls.
5718 Failure: badarg if Pid is not a local process.
5720 process_info(Pid) -> Info
5722 Types:
5724 Pid = pid()
5726 Info = [InfoTuple] | undefined
5727 InfoTuple = process_info_result_item()
5728 process_info_result_item() =
5729 {backtrace, Bin :: binary()} |
5730 {binary,
5731 BinInfo ::
5732 [{integer() >= 0,
5733 integer() >= 0,
5734 integer() >= 0}]} |
5735 {catchlevel, CatchLevel :: integer() >= 0} |
5736 {current_function,
5737 {Module :: module(), Function :: atom(), Arity :: arity()} |
5738 undefined} |
5739 {current_location,
5740 {Module :: module(),
5741 Function :: atom(),
5742 Arity :: arity(),
5743 Location ::
5744 [{file, Filename :: string()} |
5745 {line, Line :: integer() >= 1}]}} |
5746 {current_stacktrace, Stack :: [stack_item()]} |
5747 {dictionary, Dictionary :: [{Key :: term(), Value :: term()}]} |
5748 {error_handler, Module :: module()} |
5749 {garbage_collection, GCInfo :: [{atom(), integer() >= 0}]} |
5750 {garbage_collection_info,
5751 GCInfo :: [{atom(), integer() >= 0}]} |
5752 {group_leader, GroupLeader :: pid()} |
5753 {heap_size, Size :: integer() >= 0} |
5754 {initial_call, mfa()} |
5755 {links, PidsAndPorts :: [pid() | port()]} |
5756 {last_calls, false | (Calls :: [mfa()])} |
5757 {memory, Size :: integer() >= 0} |
5758 {message_queue_len, MessageQueueLen :: integer() >= 0} |
5759 {messages, MessageQueue :: [term()]} |
5760 {min_heap_size, MinHeapSize :: integer() >= 0} |
5761 {min_bin_vheap_size, MinBinVHeapSize :: integer() >= 0} |
5762 {max_heap_size, MaxHeapSize :: max_heap_size()} |
5763 {monitored_by,
5764 MonitoredBy :: [pid() | port() | nif_resource()]} |
5765 {monitors,
5766 Monitors ::
5767 [{process | port,
5768 Pid ::
5769 pid() |
5770 port() |
5771 {RegName :: atom(), Node :: node()}}]} |
5772 {message_queue_data, MQD :: message_queue_data()} |
5773 {priority, Level :: priority_level()} |
5774 {reductions, Number :: integer() >= 0} |
5775 {registered_name, [] | (Atom :: atom())} |
5776 {sequential_trace_token,
5777 [] | (SequentialTraceToken :: term())} |
5778 {stack_size, Size :: integer() >= 0} |
5779 {status,
5780 Status ::
5781 exiting | garbage_collecting | waiting | running |
5782 runnable | suspended} |
5783 {suspending,
5784 SuspendeeList ::
5785 [{Suspendee :: pid(),
5786 ActiveSuspendCount :: integer() >= 0,
5787 OutstandingSuspendCount :: integer() >= 0}]} |
5788 {total_heap_size, Size :: integer() >= 0} |
5789 {trace, InternalTraceFlags :: integer() >= 0} |
5790 {trap_exit, Boolean :: boolean()}
5791 priority_level() = low | normal | high | max
5792 stack_item() =
5793 {Module :: module(),
5794 Function :: atom(),
5795 Arity :: arity() | (Args :: [term()]),
5796 Location ::
5797 [{file, Filename :: string()} |
5798 {line, Line :: integer() >= 1}]}
5799 max_heap_size() =
5800 integer() >= 0 |
5801 #{size => integer() >= 0,
5802 kill => boolean(),
5803 error_logger => boolean()}
5804 message_queue_data() = off_heap | on_heap
5805 Returns a list containing InfoTuples with miscellaneous informa‐
5807 tion about the process identified by Pid, or undefined if the
5808 process is not alive.
5809 The order of the InfoTuples is undefined and all InfoTuples are
5811 not mandatory. The InfoTuples part of the result can be changed
5812 without prior notice.
5813 The InfoTuples with the following items are part of the result:
5815 * current_function
5817 * initial_call
5819 * status
5821 * message_queue_len
5823 * links
5825 * dictionary
5827 * trap_exit
5829 * error_handler
5831 * priority
5833 * group_leader
5835 * total_heap_size
5837 * heap_size
5839 * stack_size
5841 * reductions
5843 * garbage_collection
5845 If the process identified by Pid has a registered name, also an
5847 InfoTuple with item registered_name is included.
5848 For information about specific InfoTuples, see process_info/2.
5850 Warning:
5852 This BIF is intended for debugging only. For all other purposes,
5853 use process_info/2.
5854 Failure: badarg if Pid is not a local process.
5857 process_info(Pid, Item) -> InfoTuple | [] | undefined
5859 process_info(Pid, ItemList) -> InfoTupleList | [] | undefined
5861 Types:
5863 Pid = pid()
5865 ItemList = [Item]
5866 Item = process_info_item()
5867 InfoTupleList = [InfoTuple]
5868 InfoTuple = process_info_result_item()
5869 process_info_item() =
5870 backtrace | binary | catchlevel | current_function |
5871 current_location | current_stacktrace | dictionary |
5872 error_handler | garbage_collection | garbage_collection_info |
5873 group_leader | heap_size | initial_call | links | last_calls |
5874 memory | message_queue_len | messages | min_heap_size |
5875 min_bin_vheap_size | monitored_by | monitors |
5876 message_queue_data | priority | reductions | registered_name |
5877 sequential_trace_token | stack_size | status | suspending |
5878 total_heap_size | trace | trap_exit
5879 process_info_result_item() =
5880 {backtrace, Bin :: binary()} |
5881 {binary,
5882 BinInfo ::
5883 [{integer() >= 0,
5884 integer() >= 0,
5885 integer() >= 0}]} |
5886 {catchlevel, CatchLevel :: integer() >= 0} |
5887 {current_function,
5888 {Module :: module(), Function :: atom(), Arity :: arity()} |
5889 undefined} |
5890 {current_location,
5891 {Module :: module(),
5892 Function :: atom(),
5893 Arity :: arity(),
5894 Location ::
5895 [{file, Filename :: string()} |
5896 {line, Line :: integer() >= 1}]}} |
5897 {current_stacktrace, Stack :: [stack_item()]} |
5898 {dictionary, Dictionary :: [{Key :: term(), Value :: term()}]} |
5899 {error_handler, Module :: module()} |
5900 {garbage_collection, GCInfo :: [{atom(), integer() >= 0}]} |
5901 {garbage_collection_info,
5902 GCInfo :: [{atom(), integer() >= 0}]} |
5903 {group_leader, GroupLeader :: pid()} |
5904 {heap_size, Size :: integer() >= 0} |
5905 {initial_call, mfa()} |
5906 {links, PidsAndPorts :: [pid() | port()]} |
5907 {last_calls, false | (Calls :: [mfa()])} |
5908 {memory, Size :: integer() >= 0} |
5909 {message_queue_len, MessageQueueLen :: integer() >= 0} |
5910 {messages, MessageQueue :: [term()]} |
5911 {min_heap_size, MinHeapSize :: integer() >= 0} |
5912 {min_bin_vheap_size, MinBinVHeapSize :: integer() >= 0} |
5913 {max_heap_size, MaxHeapSize :: max_heap_size()} |
5914 {monitored_by,
5915 MonitoredBy :: [pid() | port() | nif_resource()]} |
5916 {monitors,
5917 Monitors ::
5918 [{process | port,
5919 Pid ::
5920 pid() |
5921 port() |
5922 {RegName :: atom(), Node :: node()}}]} |
5923 {message_queue_data, MQD :: message_queue_data()} |
5924 {priority, Level :: priority_level()} |
5925 {reductions, Number :: integer() >= 0} |
5926 {registered_name, [] | (Atom :: atom())} |
5927 {sequential_trace_token,
5928 [] | (SequentialTraceToken :: term())} |
5929 {stack_size, Size :: integer() >= 0} |
5930 {status,
5931 Status ::
5932 exiting | garbage_collecting | waiting | running |
5933 runnable | suspended} |
5934 {suspending,
5935 SuspendeeList ::
5936 [{Suspendee :: pid(),
5937 ActiveSuspendCount :: integer() >= 0,
5938 OutstandingSuspendCount :: integer() >= 0}]} |
5939 {total_heap_size, Size :: integer() >= 0} |
5940 {trace, InternalTraceFlags :: integer() >= 0} |
5941 {trap_exit, Boolean :: boolean()}
5942 stack_item() =
5943 {Module :: module(),
5944 Function :: atom(),
5945 Arity :: arity() | (Args :: [term()]),
5946 Location ::
5947 [{file, Filename :: string()} |
5948 {line, Line :: integer() >= 1}]}
5949 priority_level() = low | normal | high | max
5950 max_heap_size() =
5951 integer() >= 0 |
5952 #{size => integer() >= 0,
5953 kill => boolean(),
5954 error_logger => boolean()}
5955 message_queue_data() = off_heap | on_heap
5956 Returns information about the process identified by Pid, as
5958 specified by Item or ItemList. Returns undefined if the process
5959 is not alive.
5960 If the process is alive and a single Item is specified, the re‐
5962 turned value is the corresponding InfoTuple, unless Item =:=
5963 registered_name and the process has no registered name. In this
5964 case, [] is returned. This strange behavior is because of his‐
5965 torical reasons, and is kept for backward compatibility.
5966 If ItemList is specified, the result is InfoTupleList. The Info‐
5968 Tuples in InfoTupleList are included with the corresponding
5969 Items in the same order as the Items were included in ItemList.
5970 Valid Items can be included multiple times in ItemList.
5971 Getting process informations follows the signal ordering guaran‐
5973 tees described in the Processes Chapter in the Erlang Reference
5974 Manual .
5975 Note:
5977 If registered_name is part of ItemList and the process has no
5978 name registered, a {registered_name, []}, InfoTuple will be in‐
5979 cluded in the resulting InfoTupleList. This behavior is differ‐
5980 ent when a single Item =:= registered_name is specified, and
5981 when process_info/1 is used.
5982 Valid InfoTuples with corresponding Items:
5985 {backtrace, Bin}:
5987 Binary Bin contains the same information as the output from
5988 erlang:process_display(Pid, backtrace). Use binary_to_list/1
5989 to obtain the string of characters from the binary.
5990 {binary, BinInfo}:
5992 BinInfo is a list containing miscellaneous information about
5993 binaries on the heap of this process. This InfoTuple can be
5994 changed or removed without prior notice. In the current im‐
5995 plementation BinInfo is a list of tuples. The tuples con‐
5996 tain; BinaryId, BinarySize, BinaryRefcCount.
5997 Depending on the value of the message_queue_data process
5999 flag the message queue may be stored on the heap.
6000 {catchlevel, CatchLevel}:
6002 CatchLevel is the number of currently active catches in this
6003 process. This InfoTuple can be changed or removed without
6004 prior notice.
6005 {current_function, {Module, Function, Arity} | undefined}:
6007 Module, Function, Arity is the current function call of the
6008 process. The value undefined can be returned if the process
6009 is currently executing native compiled code.
6010 {current_location, {Module, Function, Arity, Location}}:
6012 Module, Function, Arity is the current function call of the
6013 process. Location is a list of two-tuples describing the lo‐
6014 cation in the source code.
6015 {current_stacktrace, Stack}:
6017 Returns the current call stack back-trace (stacktrace) of
6018 the process. The stack has the same format as in the catch
6019 part of a try. See The call-stack back trace (stacktrace).
6020 The depth of the stacktrace is truncated according to the
6021 backtrace_depth system flag setting.
6022 {dictionary, Dictionary}:
6024 Dictionary is the process dictionary.
6025 {error_handler, Module}:
6027 Module is the error handler module used by the process (for
6028 undefined function calls, for example).
6029 {garbage_collection, GCInfo}:
6031 GCInfo is a list containing miscellaneous information about
6032 garbage collection for this process. The content of GCInfo
6033 can be changed without prior notice.
6034 {garbage_collection_info, GCInfo}:
6036 GCInfo is a list containing miscellaneous detailed informa‐
6037 tion about garbage collection for this process. The content
6038 of GCInfo can be changed without prior notice. For details
6039 about the meaning of each item, see gc_minor_start in er‐
6040 lang:trace/3.
6041 {group_leader, GroupLeader}:
6043 GroupLeader is the group leader for the I/O of the process.
6044 {heap_size, Size}:
6046 Size is the size in words of the youngest heap generation of
6047 the process. This generation includes the process stack.
6048 This information is highly implementation-dependent, and can
6049 change if the implementation changes.
6050 {initial_call, {Module, Function, Arity}}:
6052 Module, Function, Arity is the initial function call with
6053 which the process was spawned.
6054 {links, PidsAndPorts}:
6056 PidsAndPorts is a list of process identifiers and port iden‐
6057 tifiers, with processes or ports to which the process has a
6058 link.
6059 {last_calls, false|Calls}:
6061 The value is false if call saving is not active for the
6062 process (see process_flag/3). If call saving is active, a
6063 list is returned, in which the last element is the most re‐
6064 cent called.
6065 {memory, Size}:
6067 Size is the size in bytes of the process. This includes call
6070 stack, heap, and internal structures.
6071 {message_queue_len, MessageQueueLen}:
6073 MessageQueueLen is the number of messages currently in the
6074 message queue of the process. This is the length of the list
6075 MessageQueue returned as the information item messages (see
6076 below).
6077 {messages, MessageQueue}:
6079 MessageQueue is a list of the messages to the process, which
6080 have not yet been processed.
6081 {min_heap_size, MinHeapSize}:
6083 MinHeapSize is the minimum heap size for the process.
6084 {min_bin_vheap_size, MinBinVHeapSize}:
6086 MinBinVHeapSize is the minimum binary virtual heap size for
6087 the process.
6088 {monitored_by, MonitoredBy}:
6090 A list of identifiers for all the processes, ports and NIF
6091 resources, that are monitoring the process.
6092 {monitors, Monitors}:
6094 A list of monitors (started by monitor/2) that are active
6095 for the process. For a local process monitor or a remote
6096 process monitor by a process identifier, the list consists
6097 of:
6098 {process, Pid}:
6100 Process is monitored by pid.
6101 {process, {RegName, Node}}:
6103 Local or remote process is monitored by name.
6104 {port, PortId}:
6106 Local port is monitored by port id.
6107 {port, {RegName, Node}}:
6109 Local port is monitored by name. Please note, that remote
6110 port monitors are not supported, so Node will always be
6111 the local node name.
6112 {message_queue_data, MQD}:
6114 MQD is the current value of the message_queue_data process
6115 flag, which can be either off_heap or on_heap. For more in‐
6116 formation, see the documentation of process_flag(mes‐
6117 sage_queue_data, MQD).
6118 {priority, Level}:
6120 Level is the current priority level for the process. For
6121 more information on priorities, see process_flag(priority,
6122 Level).
6123 {reductions, Number}:
6125 Number is the number of reductions executed by the process.
6126 {registered_name, Atom}:
6128 Atom is the registered process name. If the process has no
6129 registered name, this tuple is not present in the list.
6130 {sequential_trace_token, [] | SequentialTraceToken}:
6132 SequentialTraceToken is the sequential trace token for the
6133 process. This InfoTuple can be changed or removed without
6134 prior notice.
6135 {stack_size, Size}:
6137 Size is the stack size, in words, of the process.
6138 {status, Status}:
6140 Status is the status of the process and is one of the fol‐
6141 lowing:
6142 * exiting
6144 * garbage_collecting
6146 * waiting (for a message)
6148 * running
6150 * runnable (ready to run, but another process is running)
6152 * suspended (suspended on a "busy" port or by the BIF er‐
6154 lang:suspend_process/1,2)
6155 {suspending, SuspendeeList}:
6157 SuspendeeList is a list of {Suspendee, ActiveSuspendCount,
6158 OutstandingSuspendCount} tuples. Suspendee is the process
6159 identifier of a process that has been, or is to be, sus‐
6160 pended by the process identified by Pid through the BIF er‐
6161 lang:suspend_process/2 or erlang:suspend_process/1.
6162 ActiveSuspendCount is the number of times Suspendee has been
6164 suspended by Pid. OutstandingSuspendCount is the number of
6165 not yet completed suspend requests sent by Pid, that is:
6166 * If ActiveSuspendCount =/= 0, Suspendee is currently in the
6168 suspended state.
6169 * If OutstandingSuspendCount =/= 0, option asynchronous of
6171 erlang:suspend_process/2 has been used and the suspendee
6172 has not yet been suspended by Pid.
6173 Notice that ActiveSuspendCount and OutstandingSuspendCount
6175 are not the total suspend count on Suspendee, only the parts
6176 contributed by Pid.
6177 {total_heap_size, Size}:
6179 Size is the total size, in words, of all heap fragments of
6180 the process. This includes the process stack and any unre‐
6181 ceived messages that are considered to be part of the heap.
6182 {trace, InternalTraceFlags}:
6184 InternalTraceFlags is an integer representing the internal
6185 trace flag for this process. This InfoTuple can be changed
6186 or removed without prior notice.
6187 {trap_exit, Boolean}:
6189 Boolean is true if the process is trapping exits, otherwise
6190 false.
6191 Notice that not all implementations support all these Items.
6193 Failures:
6195 badarg:
6197 If Pid is not a local process.
6198 badarg:
6200 If Item is an invalid item.
6201 processes() -> [pid()]
6203 Returns a list of process identifiers corresponding to all the
6205 processes currently existing on the local node.
6206 Notice that an exiting process exists, but is not alive. That
6208 is, is_process_alive/1 returns false for an exiting process, but
6209 its process identifier is part of the result returned from pro‐
6210 cesses/0.
6211 Example:
6213 > processes().
6215 [<0.0.0>,<0.2.0>,<0.4.0>,<0.5.0>,<0.7.0>,<0.8.0>]
6216 purge_module(Module) -> true
6218 Types:
6220 Module = atom()
6222 Removes old code for Module. Before this BIF is used,
6224 check_process_code/2 is to be called to check that no processes
6225 execute old code in the module.
6226 Warning:
6228 This BIF is intended for the code server (see code(3)) and is
6229 not to be used elsewhere.
6230 Note:
6233 As from ERTS 8.0 (Erlang/OTP 19), any lingering processes that
6234 still execute the old code is killed by this function. In ear‐
6235 lier versions, such incorrect use could cause much more fatal
6236 failures, like emulator crash.
6237 Failure: badarg if there is no old code for Module.
6240 put(Key, Val) -> term()
6242 Types:
6244 Key = Val = term()
6246 Adds a new Key to the process dictionary, associated with the
6248 value Val, and returns undefined. If Key exists, the old value
6249 is deleted and replaced by Val, and the function returns the old
6250 value. The average time complexity for the current implementa‐
6251 tion of this function is O(1) and the worst case time complexity
6252 is O(N), where N is the number of items in the process dictio‐
6253 nary. Example:
6254 > X = put(name, walrus), Y = put(name, carpenter),
6256 Z = get(name),
6257 {X, Y, Z}.
6258 {undefined,walrus,carpenter}
6259 Note:
6261 The values stored when put is evaluated within the scope of a
6262 catch are not retracted if a throw is evaluated, or if an error
6263 occurs.
6264 erlang:raise(Class, Reason, Stacktrace) -> badarg
6267 Types:
6269 Class = error | exit | throw
6271 Reason = term()
6272 Stacktrace = raise_stacktrace() | stacktrace()
6273 raise_stacktrace() =
6274 [{module(), atom(), arity() | [term()]} |
6275 {function(), arity() | [term()]}]
6276 Raises an exception of the specified class, reason, and call
6278 stack backtrace (stacktrace).
6279 Class is error, exit, or throw. So, if it were not for the
6281 stacktrace, erlang:raise(Class, Reason, Stacktrace) is equiva‐
6282 lent to erlang:Class(Reason) (given that Class is a valid
6283 class).
6284 Reason can be any term.
6286 Stacktrace is a list as provided in a try-catch clause.
6288 try
6290 ...
6291 catch Class:Reason:Stacktrace ->
6292 ...
6293 end
6294 That is, a list of four-tuples {Module, Function, Arity | Args,
6296 ExtraInfo}, where Module and Function are atoms, and the third
6297 element is an integer arity or an argument list. The stacktrace
6298 can also contain {Fun, Args, ExtraInfo} tuples, where Fun is a
6299 local fun and Args is an argument list.
6300 Element ExtraInfo at the end is optional. Omitting it is equiva‐
6302 lent to specifying an empty list.
6303 The stacktrace is used as the exception stacktrace for the call‐
6305 ing process; it is truncated to the current maximum stacktrace
6306 depth.
6307 As evaluating this function causes the process to terminate, it
6309 has no return value unless the arguments are invalid, in which
6310 case the function returns the error reason badarg. If you want
6311 to be sure not to return, you can call error(erlang:raise(Class,
6312 Reason, Stacktrace)) and hope to distinguish exceptions later.
6313 See the reference manual about errors and error handling for
6315 more information about exception classes and how to catch excep‐
6316 tions.
6317 erlang:read_timer(TimerRef) -> Result
6319 Types:
6321 TimerRef = reference()
6323 Time = integer() >= 0
6324 Result = Time | false
6325 Reads the state of a timer. The same as calling er‐
6327 lang:read_timer(TimerRef, []).
6328 erlang:read_timer(TimerRef, Options) -> Result | ok
6330 Types:
6332 TimerRef = reference()
6334 Async = boolean()
6335 Option = {async, Async}
6336 Options = [Option]
6337 Time = integer() >= 0
6338 Result = Time | false
6339 Reads the state of a timer that has been created by either er‐
6341 lang:start_timer or erlang:send_after. TimerRef identifies the
6342 timer, and was returned by the BIF that created the timer.
6343 Options:
6345 {async, Async}:
6347 Asynchronous request for state information. Async defaults
6348 to false, which causes the operation to be performed syn‐
6349 chronously. In this case, the Result is returned by er‐
6350 lang:read_timer. When Async is true, erlang:read_timer sends
6351 an asynchronous request for the state information to the
6352 timer service that manages the timer, and then returns ok. A
6353 message on the format {read_timer, TimerRef, Result} is sent
6354 to the caller of erlang:read_timer when the operation has
6355 been processed.
6356 More Options can be added in the future.
6358 If Result is an integer, it represents the time in milliseconds
6360 left until the timer expires.
6361 If Result is false, a timer corresponding to TimerRef could not
6363 be found. This because the timer had expired, or been canceled,
6364 or because TimerRef never has corresponded to a timer. Even if
6365 the timer has expired, it does not tell you whether or not the
6366 time-out message has arrived at its destination yet.
6367 Note:
6369 The timer service that manages the timer can be co-located with
6370 another scheduler than the scheduler that the calling process is
6371 executing on. If so, communication with the timer service takes
6372 much longer time than if it is located locally. If the calling
6373 process is in a critical path, and can do other things while
6374 waiting for the result of this operation, you want to use option
6375 {async, true}. If using option {async, false}, the calling
6376 process is blocked until the operation has been performed.
6377 See also erlang:send_after/4, erlang:start_timer/4, and er‐
6380 lang:cancel_timer/2.
6381 ref_to_list(Ref) -> string()
6383 Types:
6385 Ref = reference()
6387 Returns a string corresponding to the text representation of
6389 Ref.
6390 Warning:
6392 This BIF is intended for debugging and is not to be used in ap‐
6393 plication programs.
6394 register(RegName, PidOrPort) -> true
6397 Types:
6399 RegName = atom()
6401 PidOrPort = port() | pid()
6402 Registers the name RegName with a process identifier (pid) or a
6404 port identifier in the name registry. RegName, which must be an
6405 atom, can be used instead of the pid or port identifier in send
6406 operator (RegName ! Message) and most other BIFs that take a pid
6407 or port identifies as an argument. Example:
6408 > register(db, Pid).
6410 true
6411 The registered name is considered a Directly Visible Erlang Re‐
6413 source and is automatically unregistered when the process termi‐
6414 nates.
6415 Failures:
6417 badarg:
6419 If PidOrPort is not an existing local process or port.
6420 badarg:
6422 If RegName is already in use.
6423 badarg:
6425 If the process or port is already registered (already has a
6426 name).
6427 badarg:
6429 If RegName is the atom undefined.
6430 registered() -> [RegName]
6432 Types:
6434 RegName = atom()
6436 Returns a list of names that have been registered using regis‐
6438 ter/2, for example:
6439 > registered().
6441 [code_server, file_server, init, user, my_db]
6442 erlang:resume_process(Suspendee) -> true
6444 Types:
6446 Suspendee = pid()
6448 Decreases the suspend count on the process identified by Sus‐
6450 pendee. Suspendee is previously to have been suspended through
6451 erlang:suspend_process/2 or erlang:suspend_process/1 by the
6452 process calling erlang:resume_process(Suspendee). When the sus‐
6453 pend count on Suspendee reaches zero, Suspendee is resumed, that
6454 is, its state is changed from suspended into the state it had
6455 before it was suspended.
6456 Warning:
6458 This BIF is intended for debugging only.
6459 Failures:
6462 badarg:
6464 If Suspendee is not a process identifier.
6465 badarg:
6467 If the process calling erlang:resume_process/1 had not pre‐
6468 viously increased the suspend count on the process identi‐
6469 fied by Suspendee.
6470 badarg:
6472 If the process identified by Suspendee is not alive.
6473 round(Number) -> integer()
6475 Types:
6477 Number = number()
6479 Returns an integer by rounding Number, for example:
6481 round(42.1).
6483 42
6484 round(5.5).
6486 6
6487 round(-5.5).
6489 -6
6490 round(36028797018963969.0).
6492 36028797018963968
6493 In the last example, round(36028797018963969.0) evaluates to
6495 36028797018963968. The reason for this is that the number
6496 36028797018963969.0 cannot be represented exactly as a float
6497 value. Instead, the float literal is represented as
6498 36028797018963968.0, which is the closest number that can be
6499 represented exactly as a float value. See Representation of
6500 Floating Point Numbers for additional information.
6501 Allowed in guard tests.
6503 self() -> pid()
6505 Returns the process identifier of the calling process, for exam‐
6507 ple:
6508 > self().
6510 <0.26.0>
6511 Allowed in guard tests.
6513 erlang:send(Dest, Msg) -> Msg
6515 Types:
6517 Dest = dst()
6519 Msg = term()
6520 dst() =
6521 pid() |
6522 reference() |
6523 port() |
6524 (RegName :: atom()) |
6525 {RegName :: atom(), Node :: node()}
6526 Sends a message and returns Msg. This is the same as using the
6528 send operator: Dest ! Msg.
6529 Dest can be a remote or local process identifier, an alias, a
6531 (local) port, a locally registered name, or a tuple {RegName,
6532 Node} for a registered name at another node.
6533 The function fails with a badarg run-time error if Dest is an
6535 atom name, but this name is not registered. This is the only
6536 case when send fails for an unreachable destination Dest (of
6537 correct type).
6538 erlang:send(Dest, Msg, Options) -> Res
6540 Types:
6542 Dest = dst()
6544 Msg = term()
6545 Options = [nosuspend | noconnect]
6546 Res = ok | nosuspend | noconnect
6547 dst() =
6548 pid() |
6549 reference() |
6550 port() |
6551 (RegName :: atom()) |
6552 {RegName :: atom(), Node :: node()}
6553 Either sends a message and returns ok, or does not send the mes‐
6555 sage but returns something else (see below). Otherwise the same
6556 as erlang:send/2. For more detailed explanation and warnings,
6557 see erlang:send_nosuspend/2,3.
6558 Options:
6560 nosuspend:
6562 If the sender would have to be suspended to do the send, no‐
6563 suspend is returned instead.
6564 noconnect:
6566 If the destination node would have to be auto-connected to
6567 do the send, noconnect is returned instead.
6568 Warning:
6570 As with erlang:send_nosuspend/2,3: use with extreme care.
6571 erlang:send_after(Time, Dest, Msg) -> TimerRef
6574 Types:
6576 Time = integer() >= 0
6578 Dest = pid() | atom()
6579 Msg = term()
6580 TimerRef = reference()
6581 Starts a timer. The same as calling erlang:send_after(Time,
6583 Dest, Msg, []).
6584 erlang:send_after(Time, Dest, Msg, Options) -> TimerRef
6586 Types:
6588 Time = integer()
6590 Dest = pid() | atom()
6591 Msg = term()
6592 Options = [Option]
6593 Abs = boolean()
6594 Option = {abs, Abs}
6595 TimerRef = reference()
6596 Starts a timer. When the timer expires, the message Msg is sent
6598 to the process identified by Dest. Apart from the format of the
6599 time-out message, this function works exactly as er‐
6600 lang:start_timer/4.
6601 erlang:send_nosuspend(Dest, Msg) -> boolean()
6603 Types:
6605 Dest = dst()
6607 Msg = term()
6608 dst() =
6609 pid() |
6610 reference() |
6611 port() |
6612 (RegName :: atom()) |
6613 {RegName :: atom(), Node :: node()}
6614 The same as erlang:send(Dest, Msg, [nosuspend]), but returns
6616 true if the message was sent and false if the message was not
6617 sent because the sender would have had to be suspended.
6618 This function is intended for send operations to an unreliable
6620 remote node without ever blocking the sending (Erlang) process.
6621 If the connection to the remote node (usually not a real Erlang
6622 node, but a node written in C or Java) is overloaded, this func‐
6623 tion does not send the message and returns false.
6624 The same occurs if Dest refers to a local port that is busy. For
6626 all other destinations (allowed for the ordinary send operator
6627 '!'), this function sends the message and returns true.
6628 This function is only to be used in rare circumstances where a
6630 process communicates with Erlang nodes that can disappear with‐
6631 out any trace, causing the TCP buffers and the drivers queue to
6632 be over-full before the node is shut down (because of tick time-
6633 outs) by net_kernel. The normal reaction to take when this oc‐
6634 curs is some kind of premature shutdown of the other node.
6635 Notice that ignoring the return value from this function would
6637 result in an unreliable message passing, which is contradictory
6638 to the Erlang programming model. The message is not sent if this
6639 function returns false.
6640 In many systems, transient states of overloaded queues are nor‐
6642 mal. Although this function returns false does not mean that the
6643 other node is guaranteed to be non-responsive, it could be a
6644 temporary overload. Also, a return value of true does only mean
6645 that the message can be sent on the (TCP) channel without block‐
6646 ing; the message is not guaranteed to arrive at the remote node.
6647 For a disconnected non-responsive node, the return value is true
6648 (mimics the behavior of operator !). The expected behavior and
6649 the actions to take when the function returns false are applica‐
6650 tion- and hardware-specific.
6651 Warning:
6653 Use with extreme care.
6654 erlang:send_nosuspend(Dest, Msg, Options) -> boolean()
6657 Types:
6659 Dest = dst()
6661 Msg = term()
6662 Options = [noconnect]
6663 dst() =
6664 pid() |
6665 reference() |
6666 port() |
6667 (RegName :: atom()) |
6668 {RegName :: atom(), Node :: node()}
6669 The same as erlang:send(Dest, Msg, [nosuspend | Options]), but
6671 with a Boolean return value.
6672 This function behaves like erlang:send_nosuspend/2, but takes a
6674 third parameter, a list of options. The only option is nocon‐
6675 nect, which makes the function return false if the remote node
6676 is not currently reachable by the local node. The normal behav‐
6677 ior is to try to connect to the node, which can stall the
6678 process during a short period. The use of option noconnect makes
6679 it possible to be sure not to get the slightest delay when send‐
6680 ing to a remote process. This is especially useful when communi‐
6681 cating with nodes that expect to always be the connecting part
6682 (that is, nodes written in C or Java).
6683 Whenever the function returns false (either when a suspend would
6685 occur or when noconnect was specified and the node was not al‐
6686 ready connected), the message is guaranteed not to have been
6687 sent.
6688 Warning:
6690 Use with extreme care.
6691 erlang:set_cookie(Cookie) -> true
6694 Types:
6696 Cookie = atom()
6698 Sets the magic cookie of the local node to the atom Cookie,
6700 which is also the cookie for all nodes that have no explicit
6701 cookie set with set_cookie/2 Cookie (see section Distributed
6702 Erlang in the Erlang Reference Manual in System Documentation).
6703 Failure: function_clause if the local node is not alive.
6705 erlang:set_cookie(Node, Cookie) -> true
6707 Types:
6709 Node = node()
6711 Cookie = atom()
6712 Sets the magic cookie for Node to the atom Cookie. If Node is
6714 the local node, the function sets the cookie of all other nodes
6715 (that have no explicit cookie set with this function) to Cookie
6716 (see section Distributed Erlang in the Erlang Reference Manual
6717 in System Documentation).
6718 Failure: function_clause if the local node is not alive.
6720 setelement(Index, Tuple1, Value) -> Tuple2
6722 Types:
6724 Index = integer() >= 1
6726 1..tuple_size(Tuple1
6727 Tuple1 = Tuple2 = tuple()
6728 Value = term()
6729 Returns a tuple that is a copy of argument Tuple1 with the ele‐
6731 ment specified by integer argument Index (the first element is
6732 the element with index 1) replaced by argument Value, for exam‐
6733 ple:
6734 > setelement(2, {10, green, bottles}, red).
6736 {10,red,bottles}
6737 size(Item) -> integer() >= 0
6739 Types:
6741 Item = tuple() | binary()
6743 Returns the number of elements in a tuple or the number of bytes
6745 in a binary or bitstring, for example:
6746 > size({morni, mulle, bwange}).
6748 3
6749 > size(<<11, 22, 33>>).
6750 3
6751 For bitstrings, the number of whole bytes is returned. That is,
6753 if the number of bits in the bitstring is not divisible by 8,
6754 the resulting number of bytes is rounded down.
6755 Allowed in guard tests.
6757 See also tuple_size/1, byte_size/1, and bit_size/1.
6759 spawn(Fun) -> pid()
6761 Types:
6763 Fun = function()
6765 Returns the process identifier of a new process started by the
6767 application of Fun to the empty list []. Otherwise works like
6768 spawn/3.
6769 spawn(Node, Fun) -> pid()
6771 Types:
6773 Node = node()
6775 Fun = function()
6776 Returns the process identifier of a new process started by the
6778 application of Fun to the empty list [] on Node. If Node does
6779 not exist, a useless pid is returned. Otherwise works like
6780 spawn/3.
6781 spawn(Module, Function, Args) -> pid()
6783 Types:
6785 Module = module()
6787 Function = atom()
6788 Args = [term()]
6789 Returns the process identifier of a new process started by the
6791 application of Module:Function to Args.
6792 error_handler:undefined_function(Module, Function, Args) is
6794 evaluated by the new process if Module:Function/Arity does not
6795 exist (where Arity is the length of Args). The error handler can
6796 be redefined (see process_flag/2). If error_handler is unde‐
6797 fined, or the user has redefined the default error_handler and
6798 its replacement is undefined, a failure with reason undef oc‐
6799 curs.
6800 Example:
6802 > spawn(speed, regulator, [high_speed, thin_cut]).
6804 <0.13.1>
6805 spawn(Node, Module, Function, Args) -> pid()
6807 Types:
6809 Node = node()
6811 Module = module()
6812 Function = atom()
6813 Args = [term()]
6814 Returns the process identifier (pid) of a new process started by
6816 the application of Module:Function to Args on Node. If Node does
6817 not exist, a useless pid is returned. Otherwise works like
6818 spawn/3.
6819 spawn_link(Fun) -> pid()
6821 Types:
6823 Fun = function()
6825 Returns the process identifier of a new process started by the
6827 application of Fun to the empty list []. A link is created be‐
6828 tween the calling process and the new process, atomically. Oth‐
6829 erwise works like spawn/3.
6830 spawn_link(Node, Fun) -> pid()
6832 Types:
6834 Node = node()
6836 Fun = function()
6837 Returns the process identifier (pid) of a new process started by
6839 the application of Fun to the empty list [] on Node. A link is
6840 created between the calling process and the new process, atomi‐
6841 cally. If Node does not exist, a useless pid is returned and an
6842 exit signal with reason noconnection is sent to the calling
6843 process. Otherwise works like spawn/3.
6844 spawn_link(Module, Function, Args) -> pid()
6846 Types:
6848 Module = module()
6850 Function = atom()
6851 Args = [term()]
6852 Returns the process identifier of a new process started by the
6854 application of Module:Function to Args. A link is created be‐
6855 tween the calling process and the new process, atomically. Oth‐
6856 erwise works like spawn/3.
6857 spawn_link(Node, Module, Function, Args) -> pid()
6859 Types:
6861 Node = node()
6863 Module = module()
6864 Function = atom()
6865 Args = [term()]
6866 Returns the process identifier (pid) of a new process started by
6868 the application of Module:Function to Args on Node. A link is
6869 created between the calling process and the new process, atomi‐
6870 cally. If Node does not exist, a useless pid is returned and an
6871 exit signal with reason noconnection is sent to the calling
6872 process. Otherwise works like spawn/3.
6873 spawn_monitor(Fun) -> {pid(), reference()}
6875 Types:
6877 Fun = function()
6879 Returns the process identifier of a new process, started by the
6881 application of Fun to the empty list [], and a reference for a
6882 monitor created to the new process. Otherwise works like
6883 spawn/3.
6884 spawn_monitor(Node, Fun) -> {pid(), reference()}
6886 Types:
6888 Node = node()
6890 Fun = function()
6891 Returns the process identifier of a new process, started by the
6893 application of Fun to the empty list [] on the node Node, and a
6894 reference for a monitor created to the new process. Otherwise
6895 works like spawn/3.
6896 If the node identified by Node does not support distributed
6898 spawn_monitor(), the call will fail with a notsup exception.
6899 spawn_monitor(Module, Function, Args) -> {pid(), reference()}
6901 Types:
6903 Module = module()
6905 Function = atom()
6906 Args = [term()]
6907 A new process is started by the application of Module:Function
6909 to Args. The process is monitored at the same time. Returns the
6910 process identifier and a reference for the monitor. Otherwise
6911 works like spawn/3.
6912 spawn_monitor(Node, Module, Function, Args) ->
6914 {pid(), reference()}
6915 Types:
6917 Node = node()
6919 Module = module()
6920 Function = atom()
6921 Args = [term()]
6922 A new process is started by the application of Module:Function
6924 to Args on the node Node. The process is monitored at the same
6925 time. Returns the process identifier and a reference for the
6926 monitor. Otherwise works like spawn/3.
6927 If the node identified by Node does not support distributed
6929 spawn_monitor(), the call will fail with a notsup exception.
6930 spawn_opt(Fun, Options) -> pid() | {pid(), reference()}
6932 Types:
6934 Fun = function()
6936 Options = [spawn_opt_option()]
6937 priority_level() = low | normal | high | max
6938 max_heap_size() =
6939 integer() >= 0 |
6940 #{size => integer() >= 0,
6941 kill => boolean(),
6942 error_logger => boolean()}
6943 message_queue_data() = off_heap | on_heap
6944 spawn_opt_option() =
6945 link | monitor |
6946 {monitor, MonitorOpts :: [monitor_option()]} |
6947 {priority, Level :: priority_level()} |
6948 {fullsweep_after, Number :: integer() >= 0} |
6949 {min_heap_size, Size :: integer() >= 0} |
6950 {min_bin_vheap_size, VSize :: integer() >= 0} |
6951 {max_heap_size, Size :: max_heap_size()} |
6952 {message_queue_data, MQD :: message_queue_data()}
6953 Returns the process identifier (pid) of a new process started by
6955 the application of Fun to the empty list []. Otherwise works
6956 like spawn_opt/4.
6957 If option monitor is specified, the newly created process is
6959 monitored, and both the pid and reference for the monitor are
6960 returned.
6961 spawn_opt(Node, Fun, Options) -> pid() | {pid(), reference()}
6963 Types:
6965 Node = node()
6967 Fun = function()
6968 Options =
6969 [monitor | {monitor, [monitor_option()]} | link | Oth‐
6970 erOption]
6971 OtherOption = term()
6972 Returns the process identifier (pid) of a new process started by
6974 the application of Fun to the empty list [] on Node. If Node
6975 does not exist, a useless pid is returned. Otherwise works like
6976 spawn_opt/4.
6977 Valid options depends on what options are supported by the node
6979 identified by Node. A description of valid Options for the local
6980 node of current OTP version can be found in the documentation of
6981 spawn_opt/4.
6982 spawn_opt(Module, Function, Args, Options) ->
6984 Pid | {Pid, MonitorRef}
6985 Types:
6987 Module = module()
6989 Function = atom()
6990 Args = [term()]
6991 Options = [spawn_opt_option()]
6992 Pid = pid()
6993 MonitorRef = reference()
6994 priority_level() = low | normal | high | max
6995 max_heap_size() =
6996 integer() >= 0 |
6997 #{size => integer() >= 0,
6998 kill => boolean(),
6999 error_logger => boolean()}
7000 message_queue_data() = off_heap | on_heap
7001 spawn_opt_option() =
7002 link | monitor |
7003 {monitor, MonitorOpts :: [monitor_option()]} |
7004 {priority, Level :: priority_level()} |
7005 {fullsweep_after, Number :: integer() >= 0} |
7006 {min_heap_size, Size :: integer() >= 0} |
7007 {min_bin_vheap_size, VSize :: integer() >= 0} |
7008 {max_heap_size, Size :: max_heap_size()} |
7009 {message_queue_data, MQD :: message_queue_data()}
7010 Works as spawn/3, except that an extra option list is specified
7012 when creating the process.
7013 If option monitor is specified, the newly created process is
7015 monitored, and both the pid and reference for the monitor are
7016 returned.
7017 Options:
7019 link:
7021 Sets a link to the parent process (like spawn_link/3 does).
7022 monitor:
7024 Monitors the new process (like monitor(process, Pid) does).
7025 A {Pid, MonitorRef} tuple will be returned instead of just a
7026 Pid.
7027 {monitor, MonitorOpts}:
7029 Monitors the new process with options (like monitor(process,
7030 Pid, MonitorOpts) does). A {Pid, MonitorRef} tuple will be
7031 returned instead of just a Pid.
7032 {priority, Level}:
7034 Sets the priority of the new process. Equivalent to execut‐
7035 ing process_flag(priority, Level) in the start function of
7036 the new process, except that the priority is set before the
7037 process is selected for execution for the first time. For
7038 more information on priorities, see process_flag(priority,
7039 Level).
7040 {fullsweep_after, Number}:
7042 Useful only for performance tuning. Do not use this option
7043 unless you know that there is problem with execution times
7044 or memory consumption, and ensure that the option improves
7045 matters.
7046 The Erlang runtime system uses a generational garbage col‐
7048 lection scheme, using an "old heap" for data that has sur‐
7049 vived at least one garbage collection. When there is no more
7050 room on the old heap, a fullsweep garbage collection is
7051 done.
7052 Option fullsweep_after makes it possible to specify the max‐
7054 imum number of generational collections before forcing a
7055 fullsweep, even if there is room on the old heap. Setting
7056 the number to zero disables the general collection algo‐
7057 rithm, that is, all live data is copied at every garbage
7058 collection.
7059 A few cases when it can be useful to change fullsweep_after:
7061 * If binaries that are no longer used are to be thrown away
7063 as soon as possible. (Set Number to zero.)
7064 * A process that mostly have short-lived data is fullsweeped
7066 seldom or never, that is, the old heap contains mostly
7067 garbage. To ensure a fullsweep occasionally, set Number to
7068 a suitable value, such as 10 or 20.
7069 * In embedded systems with a limited amount of RAM and no
7071 virtual memory, you might want to preserve memory by set‐
7072 ting Number to zero. (The value can be set globally, see
7073 erlang:system_flag/2.)
7074 {min_heap_size, Size}:
7076 Useful only for performance tuning. Do not use this option
7077 unless you know that there is problem with execution times
7078 or memory consumption, and ensure that the option improves
7079 matters.
7080 Gives a minimum heap size, in words. Setting this value
7082 higher than the system default can speed up some processes
7083 because less garbage collection is done. However, setting a
7084 too high value can waste memory and slow down the system be‐
7085 cause of worse data locality. Therefore, use this option
7086 only for fine-tuning an application and to measure the exe‐
7087 cution time with various Size values.
7088 {min_bin_vheap_size, VSize}:
7090 Useful only for performance tuning. Do not use this option
7091 unless you know that there is problem with execution times
7092 or memory consumption, and ensure that the option improves
7093 matters.
7094 Gives a minimum binary virtual heap size, in words. Setting
7096 this value higher than the system default can speed up some
7097 processes because less garbage collection is done. However,
7098 setting a too high value can waste memory. Therefore, use
7099 this option only for fine-tuning an application and to mea‐
7100 sure the execution time with various VSize values.
7101 {max_heap_size, Size}:
7103 Sets the max_heap_size process flag. The default
7104 max_heap_size is determined by command-line argument +hmax
7105 in erl(1). For more information, see the documentation of
7106 process_flag(max_heap_size, Size).
7107 {message_queue_data, MQD}:
7109 Sets the value of the message_queue_data process flag. MQD
7110 can be either off_heap or on_heap. The default value of the
7111 message_queue_data process flag is determined by the com‐
7112 mand-line argument +hmqd in erl(1). For more information,
7113 see the documentation of process_flag(message_queue_data,
7114 MQD).
7115 spawn_opt(Node, Module, Function, Args, Options) ->
7117 pid() | {pid(), reference()}
7118 Types:
7120 Node = node()
7122 Module = module()
7123 Function = atom()
7124 Args = [term()]
7125 Options =
7126 [monitor | {monitor, [monitor_option()]} | link | Oth‐
7127 erOption]
7128 OtherOption = term()
7129 Returns the process identifier (pid) of a new process started by
7131 the application of Module:Function to Args on Node. If Node does
7132 not exist, a useless pid is returned. Otherwise works like
7133 spawn_opt/4.
7134 Valid options depends on what options are supported by the node
7136 identified by Node. A description of valid Options for the local
7137 node of current OTP version can be found in the documentation of
7138 spawn_opt/4.
7139 spawn_request(Fun) -> ReqId
7141 Types:
7143 Fun = function()
7145 ReqId = reference()
7146 The same as the call spawn_request(node(),Fun,[]). That is, a
7148 spawn request on the local node with no options.
7149 spawn_request(Fun, Options) -> ReqId
7151 Types:
7153 Fun = function()
7155 Option =
7156 {reply_tag, ReplyTag} | {reply, Reply} | spawn_opt_op‐
7157 tion()
7158 ReplyTag = term()
7159 Reply = yes | no | error_only | success_only
7160 Options = [Option]
7161 ReqId = reference()
7162 The same as the call spawn_request(node(),Fun,Options). That is,
7164 a spawn request on the local node.
7165 spawn_request(Node, Fun) -> ReqId
7167 Types:
7169 Node = node()
7171 Fun = function()
7172 ReqId = reference()
7173 The same as the call spawn_request(Node,Fun,[]). That is, a
7175 spawn request with no options.
7176 spawn_request(Node, Fun, Options) -> ReqId
7178 Types:
7180 Node = node()
7182 Fun = function()
7183 Options = [Option]
7184 Option =
7185 monitor |
7186 {monitor, [monitor_option()]} |
7187 link |
7188 {reply_tag, ReplyTag} |
7189 {reply, Reply} |
7190 OtherOption
7191 ReplyTag = term()
7192 Reply = yes | no | error_only | success_only
7193 OtherOption = term()
7194 ReqId = reference()
7195 The same as spawn_request(Node,erlang,apply,[Fun,[]],Options).
7197 That is, a spawn request using the fun Fun of arity zero as en‐
7198 try point.
7199 This function will fail with a badarg exception if:
7201 * Node is not an atom.
7203 * Fun is not a fun of arity zero.
7205 * Options is not a proper list of terms.
7207 spawn_request(Module, Function, Args) -> ReqId
7209 Types:
7211 Module = module()
7213 Function = atom()
7214 Args = [term()]
7215 ReqId = reference()
7216 The same as the call spawn_request(node(),Module,Func‐
7218 tion,Args,[]). That is, a spawn request on the local node with
7219 no options.
7220 spawn_request(Node, Module, Function, Args) -> ReqId
7222 Types:
7224 Node = node()
7226 Module = module()
7227 Function = atom()
7228 Args = [term()]
7229 ReqId = reference()
7230 The same as the call spawn_request(Node,Module,Func‐
7232 tion,Args,[]). That is, a spawn request with no options.
7233 spawn_request(Module, Function, Args, Options) -> ReqId
7235 Types:
7237 Module = module()
7239 Function = atom()
7240 Args = [term()]
7241 Option =
7242 {reply_tag, ReplyTag} | {reply, Reply} | spawn_opt_op‐
7243 tion()
7244 ReplyTag = term()
7245 Reply = yes | no | error_only | success_only
7246 Options = [Option]
7247 ReqId = reference()
7248 The same as the call spawn_request(node(),Module,Func‐
7250 tion,Args,Options). That is, a spawn request on the local node.
7251 spawn_request(Node, Module, Function, Args, Options) -> ReqId
7253 Types:
7255 Node = node()
7257 Module = module()
7258 Function = atom()
7259 Args = [term()]
7260 Options = [Option]
7261 Option =
7262 monitor |
7263 {monitor, [monitor_option()]} |
7264 link |
7265 {reply_tag, ReplyTag} |
7266 {reply, Reply} |
7267 OtherOption
7268 ReplyTag = term()
7269 Reply = yes | no | error_only | success_only
7270 OtherOption = term()
7271 ReqId = reference()
7272 Asynchronously send a spawn request. Returns a request identi‐
7274 fier ReqId.
7275 If the spawn operation succeeds, a new process is created on the
7277 node identified by Node. When a spawn operation succeeds, the
7278 caller will by default be sent a message on the form {ReplyTag,
7279 ReqId, ok, Pid} where Pid is the process identifier of the newly
7280 created process. Such a message is referred to as a success mes‐
7281 sage below in the text. ReplyTag is by default the atom
7282 spawn_reply unless modified by the {reply_tag, ReplyTag} option.
7283 The new process is started by the application of Module:Function
7284 to Args.
7285 The spawn operation fails either if creation of a new process
7287 failed or if the spawn operation was interrupted by a connection
7288 failure. When a spawn operation fails, the caller will by de‐
7289 fault be sent a message on the form {ReplyTag, ReqId, error,
7290 Reason} where Reason is the error reason. Such a message is re‐
7291 ferred to as an error message below in the text. Currently the
7292 following spawn error Reasons are defined, but other reasons can
7293 appear at any time without prior notice:
7294 badopt:
7296 An invalid Option was passed as argument. Note that differ‐
7297 ent runtime systems may support different options.
7298 notsup:
7300 The node identified by Node does not support spawn opera‐
7301 tions issued by spawn_request().
7302 noconnection:
7304 Failure to set up a connection to the node identified by
7305 Node or the connection to that node was lost during the
7306 spawn operation. In the case the connection was lost, a
7307 process may or may not have been created.
7308 system_limit:
7310 Could not create a new process due to that some system limit
7311 was reached. Typically the process table was full.
7312 Valid Options:
7314 monitor:
7316 In the absence of spawn operation failures, atomically sets
7317 up a monitor to the newly created process. That is, as if
7318 the calling process had called monitor(process, Pid) where
7319 Pid is the process identifier of the newly created process.
7320 The ReqId returned by spawn_request() is also used as moni‐
7321 tor reference as if it was returned from monitor(process,
7322 Pid).
7323 The monitor will not be activated for the calling process
7325 until the spawn operation has succeeded. The monitor can not
7326 be demonitored before the operation has succeeded. A 'DOWN'
7327 message for the corresponding monitor is guaranteed not to
7328 be delivered before a success message that corresponds to
7329 the spawn operation. If the spawn operation fails, no 'DOWN'
7330 message will be delivered.
7331 If the connection between the nodes involved in the spawn
7333 operation is lost during the spawn operation, the spawn op‐
7334 eration will fail with an error reason of noconnection. A
7335 new process may or may not have been created.
7336 {monitor, MonitorOpts}:
7338 In the absence of spawn operation failures, atomically sets
7339 up a monitor to the newly created process. That is, as if
7340 the calling process had called monitor(process, Pid, Moni‐
7341 torOpts) where Pid is the process identifier of the newly
7342 created process. See the monitor option above for more in‐
7343 formation.
7344 Note that the monitor will not be activated for the calling
7346 process until the spawn operation has succeeded. For exam‐
7347 ple, in the case that an alias is created using the monitor
7348 option, the alias will not be active until the monitor is
7349 activated.
7350 link:
7352 In absence of spawn operation failures, atomically sets up a
7353 link between the calling process and the newly created
7354 process. That is, as if the calling process had called
7355 link(Pid) where Pid is the process identifier of the newly
7356 created process.
7357 The link will not be activated for the calling process until
7359 the spawn operation has succeeded. The link can not be re‐
7360 moved before the operation has succeeded. An exit signal due
7361 to the link is guaranteed not to be delivered before a suc‐
7362 cess message that corresponds to the spawn operation. If
7363 the spawn operation fails, no exit signal due to the link
7364 will be delivered to the caller of spawn_request().
7365 If the connection between the nodes involved in the spawn
7367 operation is lost during the spawn operation, the spawn op‐
7368 eration will fail with an error reason of noconnection. A
7369 new process may or may not have been created. If it has been
7370 created, it will be delivered an exit signal with an exit
7371 reason of noconnection.
7372 {reply, Reply}:
7374 Valid Reply values:
7375 yes:
7377 A spawn reply message will be sent to the caller regard‐
7378 less of whether the operation succeeds or not. If the call
7379 to spawn_request() returns without raising an exception
7380 and the reply option is set to yes, the caller is guaran‐
7381 teed to be delivered either a success message or an error
7382 message . The reply option is by default set to yes.
7383 no:
7385 No spawn reply message will be sent to the caller when the
7386 spawn operation completes. This regardless of whether the
7387 operation succeeds or not.
7388 error_only:
7390 No spawn reply message will be sent to the caller if the
7391 spawn operation succeeds, but an error message will be
7392 sent to the caller if the operation fails.
7393 success_only:
7395 No spawn reply message will be sent to the caller if the
7396 spawn operation fails, but a success message will be sent
7397 to the caller if the operation succeeds.
7398 {reply_tag, ReplyTag}:
7400 Sets the reply tag to ReplyTag in the reply message. That
7401 is, in the success or error message that is sent to the
7402 caller due to the spawn operation. The default reply tag is
7403 the atom spawn_reply.
7404 OtherOption:
7406 Other valid options depends on what options are supported by
7407 the node identified by Node. A description of other valid
7408 Options for the local node of current OTP version can be
7409 found in the documentation of spawn_opt/4.
7410 This function will fail with a badarg exception if:
7412 * Node is not an atom.
7414 * Module is not an atom.
7416 * Function is not an atom.
7418 * Args is not a proper list of terms.
7420 * Options is not a proper list of terms.
7422 Note that not all individual Options are checked when the spawn
7424 request is sent. Some Options can only be checked on reception
7425 of the request. Therefore an invalid option does not cause a
7426 badarg exception, but will cause the spawn operation to fail
7427 with an error reason of badopt.
7428 A spawn request can be abandoned by calling spawn_request_aban‐
7430 don/1.
7431 spawn_request_abandon(ReqId :: reference()) -> boolean()
7433 Abandon a previously issued spawn request. ReqId corresponds to
7435 a request identifier previously returned by spawn_request() in a
7436 call from current process. That is, only the process that has
7437 made the request can abandon the request.
7438 A spawn request can only be successfully abandoned until the
7440 spawn request has completed. When a spawn request has been suc‐
7441 cessfully abandoned, the caller will not be effected by future
7442 direct effects of the spawn request itself. For example, it will
7443 not receive a spawn reply message. The request is however not
7444 withdrawn, so a new process may or may not be created due to the
7445 request. If a new process is created after the spawn request was
7446 abandoned, no monitors nor links will be set up to the caller of
7447 spawn_request_abandon/1 due to the spawn request. If the spawn
7448 request included the link option, the process created due to
7449 this request will be sent an exit signal from its parent with
7450 the exit reason abandoned when it is detected that the spawn op‐
7451 eration has succeeded.
7452 Note:
7454 A process created due to a spawn request that has been abandoned
7455 may communicate with its parent as any other process. It is only
7456 the direct effects on the parent of the actual spawn request,
7457 that will be canceled by abandoning a spawn request.
7458 Return values:
7461 true:
7463 The spawn request was successfully abandoned.
7464 false:
7466 No spawn request was abandoned. The ReqId request identifier
7467 did not correspond to an outstanding spawn request issued by
7468 the calling process. The reason for this is either:
7469 * ReqId corresponds to a spawn request previoulsy made by
7471 the calling process. The spawn operation has completed and
7472 a spawn reply has already been delivered to the calling
7473 process unless the spawn reply was disabled in the re‐
7474 quest.
7475 * ReqId does not correspond to a spawn request that has been
7477 made by the calling process.
7478 This function fail with a badarg exception if ReqId is not a
7480 reference.
7481 split_binary(Bin, Pos) -> {binary(), binary()}
7483 Types:
7485 Bin = binary()
7487 Pos = integer() >= 0
7488 0..byte_size(Bin)
7489 Returns a tuple containing the binaries that are the result of
7491 splitting Bin into two parts at position Pos. This is not a de‐
7492 structive operation. After the operation, there are three bina‐
7493 ries altogether. Example:
7494 > B = list_to_binary("0123456789").
7496 <<"0123456789">>
7497 > byte_size(B).
7498 10
7499 > {B1, B2} = split_binary(B,3).
7500 {<<"012">>,<<"3456789">>}
7501 > byte_size(B1).
7502 3
7503 > byte_size(B2).
7504 7
7505 erlang:start_timer(Time, Dest, Msg) -> TimerRef
7507 Types:
7509 Time = integer() >= 0
7511 Dest = pid() | atom()
7512 Msg = term()
7513 TimerRef = reference()
7514 Starts a timer. The same as calling erlang:start_timer(Time,
7516 Dest, Msg, []).
7517 erlang:start_timer(Time, Dest, Msg, Options) -> TimerRef
7519 Types:
7521 Time = integer()
7523 Dest = pid() | atom()
7524 Msg = term()
7525 Options = [Option]
7526 Abs = boolean()
7527 Option = {abs, Abs}
7528 TimerRef = reference()
7529 Starts a timer. When the timer expires, the message {timeout,
7531 TimerRef, Msg} is sent to the process identified by Dest.
7532 Options:
7534 {abs, false}:
7536 This is the default. It means the Time value is interpreted
7537 as a time in milliseconds relative current Erlang monotonic
7538 time.
7539 {abs, true}:
7541 Absolute Time value. The Time value is interpreted as an ab‐
7542 solute Erlang monotonic time in milliseconds.
7543 More Options can be added in the future.
7545 The absolute point in time, the timer is set to expire on, must
7547 be in the interval [ erlang:convert_time_unit(erlang:sys‐
7548 tem_info(start_time), native, millisecond), erlang:con‐
7549 vert_time_unit(erlang:system_info(end_time), native, millisec‐
7550 ond) ]. If a relative time is specified, the Time value is not
7551 allowed to be negative.
7552 If Dest is a pid(), it must be a pid() of a process created on
7554 the current runtime system instance. This process has either
7555 terminated or not. If Dest is an atom(), it is interpreted as
7556 the name of a locally registered process. The process referred
7557 to by the name is looked up at the time of timer expiration. No
7558 error is returned if the name does not refer to a process.
7559 If Dest is a pid(), the timer is automatically canceled if the
7561 process referred to by the pid() is not alive, or if the process
7562 exits. This feature was introduced in ERTS 5.4.11. Notice that
7563 timers are not automatically canceled when Dest is an atom().
7564 See also erlang:send_after/4, erlang:cancel_timer/2, and er‐
7566 lang:read_timer/2.
7567 Failure: badarg if the arguments do not satisfy the requirements
7569 specified here.
7570 statistics(Item :: active_tasks) -> [ActiveTasks]
7572 Types:
7574 ActiveTasks = integer() >= 0
7576 Returns the same as statistics(active_tasks_all) with the excep‐
7578 tion that no information about the dirty IO run queue and its
7579 associated schedulers is part of the result. That is, only tasks
7580 that are expected to be CPU bound are part of the result.
7581 statistics(Item :: active_tasks_all) -> [ActiveTasks]
7583 Types:
7585 ActiveTasks = integer() >= 0
7587 Returns a list where each element represents the amount of ac‐
7589 tive processes and ports on each run queue and its associated
7590 schedulers. That is, the number of processes and ports that are
7591 ready to run, or are currently running. Values for normal run
7592 queues and their associated schedulers are located first in the
7593 resulting list. The first element corresponds to scheduler num‐
7594 ber 1 and so on. If support for dirty schedulers exist, an ele‐
7595 ment with the value for the dirty CPU run queue and its associ‐
7596 ated dirty CPU schedulers follow and then as last element the
7597 value for the the dirty IO run queue and its associated dirty IO
7598 schedulers follow. The information is not gathered atomically.
7599 That is, the result is not necessarily a consistent snapshot of
7600 the state, but instead quite efficiently gathered.
7601 Note:
7603 Each normal scheduler has one run queue that it manages. If
7604 dirty schedulers schedulers are supported, all dirty CPU sched‐
7605 ulers share one run queue, and all dirty IO schedulers share one
7606 run queue. That is, we have multiple normal run queues, one
7607 dirty CPU run queue and one dirty IO run queue. Work can not mi‐
7608 grate between the different types of run queues. Only work in
7609 normal run queues can migrate to other normal run queues. This
7610 has to be taken into account when evaluating the result.
7611 See also statistics(total_active_tasks), statis‐
7614 tics(run_queue_lengths), statistics(run_queue_lengths_all), sta‐
7615 tistics(total_run_queue_lengths), and statistics(to‐
7616 tal_run_queue_lengths_all).
7617 statistics(Item :: context_switches) -> {ContextSwitches, 0}
7619 Types:
7621 ContextSwitches = integer() >= 0
7623 Returns the total number of context switches since the system
7625 started.
7626 statistics(Item :: exact_reductions) ->
7628 {Total_Exact_Reductions,
7629 Exact_Reductions_Since_Last_Call}
7630 Types:
7632 Total_Exact_Reductions = Exact_Reductions_Since_Last_Call =
7634 integer() >= 0
7635 Returns the number of exact reductions.
7637 Note:
7639 statistics(exact_reductions) is a more expensive operation than
7640 statistics(reductions).
7641 statistics(Item :: garbage_collection) ->
7644 {Number_of_GCs, Words_Reclaimed, 0}
7645 Types:
7647 Number_of_GCs = Words_Reclaimed = integer() >= 0
7649 Returns information about garbage collection, for example:
7651 > statistics(garbage_collection).
7653 {85,23961,0}
7654 This information can be invalid for some implementations.
7656 statistics(Item :: io) -> {{input, Input}, {output, Output}}
7658 Types:
7660 Input = Output = integer() >= 0
7662 Returns Input, which is the total number of bytes received
7664 through ports, and Output, which is the total number of bytes
7665 output to ports.
7666 statistics(Item :: microstate_accounting) ->
7668 [MSAcc_Thread] | undefined
7669 Types:
7671 MSAcc_Thread =
7673 #{type := MSAcc_Thread_Type,
7674 id := MSAcc_Thread_Id,
7675 counters := MSAcc_Counters}
7676 MSAcc_Thread_Type =
7677 async | aux | dirty_io_scheduler | dirty_cpu_scheduler |
7678 poll | scheduler
7679 MSAcc_Thread_Id = integer() >= 0
7680 MSAcc_Counters = #{MSAcc_Thread_State => integer() >= 0}
7681 MSAcc_Thread_State =
7682 alloc | aux | bif | busy_wait | check_io | emulator | ets
7683 |
7684 gc | gc_fullsweep | nif | other | port | send | sleep |
7685 timers
7686 Microstate accounting can be used to measure how much time the
7688 Erlang runtime system spends doing various tasks. It is designed
7689 to be as lightweight as possible, but some overhead exists when
7690 this is enabled. Microstate accounting is meant to be a profil‐
7691 ing tool to help finding performance bottlenecks. To
7692 start/stop/reset microstate accounting, use system flag mi‐
7693 crostate_accounting.
7694 statistics(microstate_accounting) returns a list of maps repre‐
7696 senting some of the OS threads within ERTS. Each map contains
7697 type and id fields that can be used to identify what thread it
7698 is, and also a counters field that contains data about how much
7699 time has been spent in the various states.
7700 Example:
7702 > erlang:statistics(microstate_accounting).
7704 [#{counters => #{aux => 1899182914,
7705 check_io => 2605863602,
7706 emulator => 45731880463,
7707 gc => 1512206910,
7708 other => 5421338456,
7709 port => 221631,
7710 sleep => 5150294100},
7711 id => 1,
7712 type => scheduler}|...]
7713 The time unit is the same as returned by os:perf_counter/0. So,
7715 to convert it to milliseconds, you can do something like this:
7716 lists:map(
7718 fun(#{ counters := Cnt } = M) ->
7719 MsCnt = maps:map(fun(_K, PerfCount) ->
7720 erlang:convert_time_unit(PerfCount, perf_counter, 1000)
7721 end, Cnt),
7722 M#{ counters := MsCnt }
7723 end, erlang:statistics(microstate_accounting)).
7724 Notice that these values are not guaranteed to be the exact time
7726 spent in each state. This is because of various optimisation
7727 done to keep the overhead as small as possible.
7728 MSAcc_Thread_Types:
7730 scheduler:
7732 The main execution threads that do most of the work. See erl
7733 +S for more details.
7734 dirty_cpu_scheduler:
7736 The threads for long running cpu intensive work. See erl
7737 +SDcpu for more details.
7738 dirty_io_scheduler:
7740 The threads for long running I/O work. See erl +SDio for
7741 more details.
7742 async:
7744 Async threads are used by various linked-in drivers (mainly
7745 the file drivers) do offload non-CPU intensive work. See erl
7746 +A for more details.
7747 aux:
7749 Takes care of any work that is not specifically assigned to
7750 a scheduler.
7751 poll:
7753 Does the IO polling for the emulator. See erl +IOt for more
7754 details.
7755 The following MSAcc_Thread_States are available. All states are
7757 exclusive, meaning that a thread cannot be in two states at
7758 once. So, if you add the numbers of all counters in a thread,
7759 you get the total runtime for that thread.
7760 aux:
7762 Time spent handling auxiliary jobs.
7763 check_io:
7765 Time spent checking for new I/O events.
7766 emulator:
7768 Time spent executing Erlang processes.
7769 gc:
7771 Time spent doing garbage collection. When extra states are
7772 enabled this is the time spent doing non-fullsweep garbage
7773 collections.
7774 other:
7776 Time spent doing unaccounted things.
7777 port:
7779 Time spent executing ports.
7780 sleep:
7782 Time spent sleeping.
7783 More fine-grained MSAcc_Thread_States can be added through con‐
7785 figure (such as ./configure --with-microstate-accounting=extra).
7786 Enabling these states causes performance degradation when mi‐
7787 crostate accounting is turned off and increases the overhead
7788 when it is turned on.
7789 alloc:
7791 Time spent managing memory. Without extra states this time
7792 is spread out over all other states.
7793 bif:
7795 Time spent in BIFs. Without extra states this time is part
7796 of the emulator state.
7797 busy_wait:
7799 Time spent busy waiting. This is also the state where a
7800 scheduler no longer reports that it is active when using
7801 statistics(scheduler_wall_time). So, if you add all other
7802 states but this and sleep, and then divide that by all time
7803 in the thread, you should get something very similar to the
7804 scheduler_wall_time fraction. Without extra states this time
7805 is part of the other state.
7806 ets:
7808 Time spent executing ETS BIFs. Without extra states this
7809 time is part of the emulator state.
7810 gc_full:
7812 Time spent doing fullsweep garbage collection. Without extra
7813 states this time is part of the gc state.
7814 nif:
7816 Time spent in NIFs. Without extra states this time is part
7817 of the emulator state.
7818 send:
7820 Time spent sending messages (processes only). Without extra
7821 states this time is part of the emulator state.
7822 timers:
7824 Time spent managing timers. Without extra states this time
7825 is part of the other state.
7826 The utility module msacc(3) can be used to more easily analyse
7828 these statistics.
7829 Returns undefined if system flag microstate_accounting is turned
7831 off.
7832 The list of thread information is unsorted and can appear in
7834 different order between calls.
7835 Note:
7837 The threads and states are subject to change without any prior
7838 notice.
7839 statistics(Item :: reductions) ->
7842 {Total_Reductions, Reductions_Since_Last_Call}
7843 Types:
7845 Total_Reductions = Reductions_Since_Last_Call = integer() >=
7847 0
7848 Returns information about reductions, for example:
7850 > statistics(reductions).
7852 {2046,11}
7853 Note:
7855 As from ERTS 5.5 (Erlang/OTP R11B), this value does not include
7856 reductions performed in current time slices of currently sched‐
7857 uled processes. If an exact value is wanted, use statistics(ex‐
7858 act_reductions).
7859 statistics(Item :: run_queue) -> integer() >= 0
7862 Returns the total length of all normal and dirty CPU run queues.
7864 That is, queued work that is expected to be CPU bound. The in‐
7865 formation is gathered atomically. That is, the result is a con‐
7866 sistent snapshot of the state, but this operation is much more
7867 expensive compared to statistics(total_run_queue_lengths), espe‐
7868 cially when a large amount of schedulers is used.
7869 statistics(Item :: run_queue_lengths) -> [RunQueueLength]
7871 Types:
7873 RunQueueLength = integer() >= 0
7875 Returns the same as statistics(run_queue_lengths_all) with the
7877 exception that no information about the dirty IO run queue is
7878 part of the result. That is, only run queues with work that is
7879 expected to be CPU bound is part of the result.
7880 statistics(Item :: run_queue_lengths_all) -> [RunQueueLength]
7882 Types:
7884 RunQueueLength = integer() >= 0
7886 Returns a list where each element represents the amount of pro‐
7888 cesses and ports ready to run for each run queue. Values for
7889 normal run queues are located first in the resulting list. The
7890 first element corresponds to the normal run queue of scheduler
7891 number 1 and so on. If support for dirty schedulers exist, val‐
7892 ues for the dirty CPU run queue and the dirty IO run queue fol‐
7893 low (in that order) at the end. The information is not gathered
7894 atomically. That is, the result is not necessarily a consistent
7895 snapshot of the state, but instead quite efficiently gathered.
7896 Note:
7898 Each normal scheduler has one run queue that it manages. If
7899 dirty schedulers schedulers are supported, all dirty CPU sched‐
7900 ulers share one run queue, and all dirty IO schedulers share one
7901 run queue. That is, we have multiple normal run queues, one
7902 dirty CPU run queue and one dirty IO run queue. Work can not mi‐
7903 grate between the different types of run queues. Only work in
7904 normal run queues can migrate to other normal run queues. This
7905 has to be taken into account when evaluating the result.
7906 See also statistics(run_queue_lengths), statistics(to‐
7909 tal_run_queue_lengths_all), statistics(total_run_queue_lengths),
7910 statistics(active_tasks), statistics(active_tasks_all), and sta‐
7911 tistics(total_active_tasks), statistics(total_active_tasks_all).
7912 statistics(Item :: runtime) ->
7914 {Total_Run_Time, Time_Since_Last_Call}
7915 Types:
7917 Total_Run_Time = Time_Since_Last_Call = integer() >= 0
7919 Returns information about runtime, in milliseconds.
7921 This is the sum of the runtime for all threads in the Erlang
7923 runtime system and can therefore be greater than the wall clock
7924 time.
7925 Warning:
7927 This value might wrap due to limitations in the underlying func‐
7928 tionality provided by the operating system that is used.
7929 Example:
7932 > statistics(runtime).
7934 {1690,1620}
7935 statistics(Item :: scheduler_wall_time) ->
7937 [{SchedulerId, ActiveTime, TotalTime}] | undefined
7938 Types:
7940 SchedulerId = integer() >= 1
7942 ActiveTime = TotalTime = integer() >= 0
7943 Returns information describing how much time normal and dirty
7945 CPU schedulers in the system have been busy. This value is nor‐
7946 mally a better indicator of how much load an Erlang node is un‐
7947 der instead of looking at the CPU utilization privided by tools
7948 such as top or sysstat. This is because scheduler_wall_time also
7949 includes time where the scheduler is waiting for some other rea‐
7950 source (such as an internal mutex) to be available but does not
7951 use the CPU. In order to better understand what a scheduler is
7952 busy doing you can use microstate accounting.
7953 The definition of a busy scheduler is when it is not idle and
7955 not busy waiting for new work, that is:
7956 * Executing process code
7958 * Executing linked-in driver or NIF code
7960 * Executing BIFs, or any other runtime handling
7962 * Garbage collecting
7964 * Handling any other memory management
7966 Notice that a scheduler can also be busy even if the OS has
7968 scheduled out the scheduler thread.
7969 Note:
7971 It is recommended to use the module scheduler instead of this
7972 function directly as it provides an easier way to get the infor‐
7973 mation that you usually want.
7974 If enabled this function returns a list of tuples with {Schedu‐
7977 lerId, ActiveTime, TotalTime}, where SchedulerId is an integer
7978 ID of the scheduler, ActiveTime is the duration the scheduler
7979 has been busy, and TotalTime is the total time duration since
7980 scheduler_wall_time activation for the specific scheduler. The
7981 time unit returned is undefined and can be subject to change be‐
7982 tween releases, OSs, and system restarts. scheduler_wall_time is
7983 only to be used to calculate relative values for scheduler uti‐
7984 lization. The ActiveTime can never exceed TotalTime. The list of
7985 scheduler information is unsorted and can appear in different
7986 order between calls.
7987 The disabled this function returns undefined.
7989 The activation time can differ significantly between schedulers.
7991 Currently dirty schedulers are activated at system start while
7992 normal schedulers are activated some time after the sched‐
7993 uler_wall_time functionality is enabled.
7994 Only information about schedulers that are expected to handle
7996 CPU bound work is included in the return values from this func‐
7997 tion. If you also want information about dirty I/O schedulers,
7998 use statistics(scheduler_wall_time_all) instead.
7999 Normal schedulers will have scheduler identifiers in the range 1
8001 =< SchedulerId =< erlang:system_info(schedulers). Dirty CPU
8002 schedulers will have scheduler identifiers in the range er‐
8003 lang:system_info(schedulers) < SchedulerId =< erlang:sys‐
8004 tem_info(schedulers) + erlang:system_info(dirty_cpu_schedulers).
8005 Note:
8007 The different types of schedulers handle specific types of jobs.
8008 Every job is assigned to a specific scheduler type. Jobs can mi‐
8009 grate between different schedulers of the same type, but never
8010 between schedulers of different types. This fact has to be taken
8011 under consideration when evaluating the result returned.
8012 You can use scheduler_wall_time to calculate scheduler utiliza‐
8015 tion. First you take a sample of the values returned by er‐
8016 lang:statistics(scheduler_wall_time).
8017 > erlang:system_flag(scheduler_wall_time, true).
8019 false
8020 > Ts0 = lists:sort(erlang:statistics(scheduler_wall_time)), ok.
8021 ok
8022 Some time later the user takes another snapshot and calculates
8024 scheduler utilization per scheduler, for example:
8025 > Ts1 = lists:sort(erlang:statistics(scheduler_wall_time)), ok.
8027 ok
8028 > lists:map(fun({{I, A0, T0}, {I, A1, T1}}) -> {I, (A1 - A0)/(T1 - T0)} end, lists:zip(Ts0,Ts1)).
8029 [{1,0.9743474730177548},
8030 {2,0.9744843782751444},
8031 {3,0.9995902361669045},
8032 {4,0.9738012596572161},
8033 {5,0.9717956667018103},
8034 {6,0.9739235846420741},
8035 {7,0.973237033077876},
8036 {8,0.9741297293248656}]
8037 Using the same snapshots to calculate a total scheduler utiliza‐
8039 tion:
8040 > {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.
8042 0.9769136803764825
8043 Total scheduler utilization will equal 1.0 when all schedulers
8045 have been active all the time between the two measurements.
8046 Another (probably more) useful value is to calculate total
8048 scheduler utilization weighted against maximum amount of avail‐
8049 able CPU time:
8050 > WeightedSchedulerUtilization = (TotalSchedulerUtilization * (erlang:system_info(schedulers) + erlang:system_info(dirty_cpu_schedulers))) / erlang:system_info(logical_processors_available).
8052 0.9769136803764825
8053 This weighted scheduler utilization will reach 1.0 when sched‐
8055 ulers are active the same amount of time as maximum available
8056 CPU time. If more schedulers exist than available logical pro‐
8057 cessors, this value may be greater than 1.0.
8058 As of ERTS version 9.0, the Erlang runtime system will as de‐
8060 fault have more schedulers than logical processors. This due to
8061 the dirty schedulers.
8062 Note:
8064 scheduler_wall_time is by default disabled. To enable it, use
8065 erlang:system_flag(scheduler_wall_time, true).
8066 statistics(Item :: scheduler_wall_time_all) ->
8069 [{SchedulerId, ActiveTime, TotalTime}] | undefined
8070 Types:
8072 SchedulerId = integer() >= 1
8074 ActiveTime = TotalTime = integer() >= 0
8075 The same as statistics(scheduler_wall_time), except that it also
8077 include information about all dirty I/O schedulers.
8078 Dirty IO schedulers will have scheduler identifiers in the range
8080 erlang:system_info(schedulers) + erlang:sys‐
8081 tem_info(dirty_cpu_schedulers) < SchedulerId =< erlang:sys‐
8082 tem_info(schedulers) + erlang:system_info(dirty_cpu_schedulers)
8083 + erlang:system_info(dirty_io_schedulers).
8084 Note:
8086 Note that work executing on dirty I/O schedulers are expected to
8087 mainly wait for I/O. That is, when you get high scheduler uti‐
8088 lization on dirty I/O schedulers, CPU utilization is not ex‐
8089 pected to be high due to this work.
8090 statistics(Item :: total_active_tasks) -> ActiveTasks
8093 Types:
8095 ActiveTasks = integer() >= 0
8097 The same as calling lists:sum(statistics(active_tasks)), but
8099 more efficient.
8100 statistics(Item :: total_active_tasks_all) -> ActiveTasks
8102 Types:
8104 ActiveTasks = integer() >= 0
8106 The same as calling lists:sum(statistics(active_tasks_all)), but
8108 more efficient.
8109 statistics(Item :: total_run_queue_lengths) ->
8111 TotalRunQueueLengths
8112 Types:
8114 TotalRunQueueLengths = integer() >= 0
8116 The same as calling lists:sum(statistics(run_queue_lengths)),
8118 but more efficient.
8119 statistics(Item :: total_run_queue_lengths_all) ->
8121 TotalRunQueueLengths
8122 Types:
8124 TotalRunQueueLengths = integer() >= 0
8126 The same as calling lists:sum(statis‐
8128 tics(run_queue_lengths_all)), but more efficient.
8129 statistics(Item :: wall_clock) ->
8131 {Total_Wallclock_Time,
8132 Wallclock_Time_Since_Last_Call}
8133 Types:
8135 Total_Wallclock_Time = Wallclock_Time_Since_Last_Call = inte‐
8137 ger() >= 0
8138 Returns information about wall clock. wall_clock can be used in
8140 the same manner as runtime, except that real time is measured as
8141 opposed to runtime or CPU time.
8142 erlang:suspend_process(Suspendee) -> true
8144 Types:
8146 Suspendee = pid()
8148 Suspends the process identified by Suspendee. The same as call‐
8150 ing erlang:suspend_process(Suspendee, []).
8151 Warning:
8153 This BIF is intended for debugging only.
8154 erlang:suspend_process(Suspendee, OptList) -> boolean()
8157 Types:
8159 Suspendee = pid()
8161 OptList = [Opt]
8162 Opt = unless_suspending | asynchronous | {asynchronous,
8163 term()}
8164 Increases the suspend count on the process identified by Sus‐
8166 pendee and puts it in the suspended state if it is not already
8167 in that state. A suspended process is not scheduled for execu‐
8168 tion until the process has been resumed.
8169 A process can be suspended by multiple processes and can be sus‐
8171 pended multiple times by a single process. A suspended process
8172 does not leave the suspended state until its suspend count
8173 reaches zero. The suspend count of Suspendee is decreased when
8174 erlang:resume_process(Suspendee) is called by the same process
8175 that called erlang:suspend_process(Suspendee). All increased
8176 suspend counts on other processes acquired by a process are au‐
8177 tomatically decreased when the process terminates.
8178 Options (Opts):
8180 asynchronous:
8182 A suspend request is sent to the process identified by Sus‐
8183 pendee. Suspendee eventually suspends unless it is resumed
8184 before it could suspend. The caller of erlang:sus‐
8185 pend_process/2 returns immediately, regardless of whether
8186 Suspendee has suspended yet or not. The point in time when
8187 Suspendee suspends cannot be deduced from other events in
8188 the system. It is only guaranteed that Suspendee eventually
8189 suspends (unless it is resumed). If no asynchronous options
8190 has been passed, the caller of erlang:suspend_process/2 is
8191 blocked until Suspendee has suspended.
8192 {asynchronous, ReplyTag}:
8194 A suspend request is sent to the process identified by Sus‐
8195 pendee. When the suspend request has been processed, a reply
8196 message is sent to the caller of this function. The reply is
8197 on the form {ReplyTag, State} where State is either:
8198 exited:
8200 Suspendee has exited.
8201 suspended:
8203 Suspendee is now suspended.
8204 not_suspended:
8206 Suspendee is not suspended. This can only happen when the
8207 process that issued this request, have called re‐
8208 sume_process(Suspendee) before getting the reply.
8209 Appart from the reply message, the {asynchronous, ReplyTag}
8211 option behaves exactly the same as the asynchronous option
8212 without reply tag.
8213 unless_suspending:
8215 The process identified by Suspendee is suspended unless the
8216 calling process already is suspending Suspendee. If un‐
8217 less_suspending is combined with option asynchronous, a sus‐
8218 pend request is sent unless the calling process already is
8219 suspending Suspendee or if a suspend request already has
8220 been sent and is in transit. If the calling process already
8221 is suspending Suspendee, or if combined with option asyn‐
8222 chronous and a send request already is in transit, false is
8223 returned and the suspend count on Suspendee remains un‐
8224 changed.
8225 If the suspend count on the process identified by Suspendee is
8227 increased, true is returned, otherwise false.
8228 Warning:
8230 This BIF is intended for debugging only.
8231 Warning:
8234 You can easily create deadlocks if processes suspends each other
8235 (directly or in circles). In ERTS versions prior to ERTS version
8236 10.0, the runtime system prevented such deadlocks, but this pre‐
8237 vention has now been removed due to performance reasons.
8238 Failures:
8241 badarg:
8243 If Suspendee is not a process identifier.
8244 badarg:
8246 If the process identified by Suspendee is the same process
8247 as the process calling erlang:suspend_process/2.
8248 badarg:
8250 If the process identified by Suspendee is not alive.
8251 badarg:
8253 If the process identified by Suspendee resides on another
8254 node.
8255 badarg:
8257 If OptList is not a proper list of valid Opts.
8258 system_limit:
8260 If the process identified by Suspendee has been suspended
8261 more times by the calling process than can be represented by
8262 the currently used internal data structures. The system
8263 limit is greater than 2,000,000,000 suspends and will never
8264 be lower.
8265 erlang:system_flag(Flag :: backtrace_depth, Depth) -> OldDepth
8267 Types:
8269 Depth = OldDepth = integer() >= 0
8271 Sets the maximum depth of call stack back-traces in the exit
8273 reason element of 'EXIT' tuples. The flag also limits the stack‐
8274 trace depth returned by process_info item current_stacktrace.
8275 Returns the old value of the flag.
8277 erlang:system_flag(Flag :: cpu_topology, CpuTopology) ->
8279 OldCpuTopology
8280 Types:
8282 CpuTopology = OldCpuTopology = cpu_topology()
8284 cpu_topology() = [LevelEntry :: level_entry()] | undefined
8285 level_entry() =
8286 {LevelTag :: level_tag(), SubLevel :: sub_level()} |
8287 {LevelTag :: level_tag(),
8288 InfoList :: info_list(),
8289 SubLevel :: sub_level()}
8290 level_tag() = core | node | processor | thread
8291 sub_level() =
8292 [LevelEntry :: level_entry()] |
8293 (LogicalCpuId :: {logical, integer() >= 0})
8294 info_list() = []
8295 Warning:
8297 This argument is deprecated. Instead of using this argument, use
8298 command-line argument +sct in erl(1).
8299 When this argument is removed, a final CPU topology to use is
8301 determined at emulator boot time.
8302 Sets the user-defined CpuTopology. The user-defined CPU topology
8305 overrides any automatically detected CPU topology. By passing
8306 undefined as CpuTopology, the system reverts to the CPU topology
8307 automatically detected. The returned value equals the value re‐
8308 turned from erlang:system_info(cpu_topology) before the change
8309 was made.
8310 Returns the old value of the flag.
8312 The CPU topology is used when binding schedulers to logical pro‐
8314 cessors. If schedulers are already bound when the CPU topology
8315 is changed, the schedulers are sent a request to rebind accord‐
8316 ing to the new CPU topology.
8317 The user-defined CPU topology can also be set by passing com‐
8319 mand-line argument +sct to erl(1).
8320 For information on type CpuTopology and more, see erlang:sys‐
8322 tem_info(cpu_topology) as well as command-line flags +sct and
8323 +sbt in erl(1).
8324 erlang:system_flag(Flag :: dirty_cpu_schedulers_online,
8326 DirtyCPUSchedulersOnline) ->
8327 OldDirtyCPUSchedulersOnline
8328 Types:
8330 DirtyCPUSchedulersOnline = OldDirtyCPUSchedulersOnline = in‐
8332 teger() >= 1
8333 Sets the number of dirty CPU schedulers online. Range is 1 <=
8335 DirtyCPUSchedulersOnline <= N, where N is the smallest of the
8336 return values of erlang:system_info(dirty_cpu_schedulers) and
8337 erlang:system_info(schedulers_online).
8338 Returns the old value of the flag.
8340 The number of dirty CPU schedulers online can change if the num‐
8342 ber of schedulers online changes. For example, if 12 schedulers
8343 and 6 dirty CPU schedulers are online, and system_flag/2 is used
8344 to set the number of schedulers online to 6, then the number of
8345 dirty CPU schedulers online is automatically decreased by half
8346 as well, down to 3. Similarly, the number of dirty CPU sched‐
8347 ulers online increases proportionally to increases in the number
8348 of schedulers online.
8349 For more information, see erlang:system_info(dirty_cpu_sched‐
8351 ulers) and erlang:system_info(dirty_cpu_schedulers_online).
8352 erlang:system_flag(Flag :: erts_alloc, Value :: {Alloc, F, V}) ->
8354 ok | notsup
8355 Types:
8357 Alloc = F = atom()
8359 V = integer()
8360 Sets system flags for erts_alloc(3). Alloc is the allocator to
8362 affect, for example binary_alloc. F is the flag to change and V
8363 is the new value.
8364 Only a subset of all erts_alloc flags can be changed at run
8366 time. This subset is currently only the flag sbct.
8367 Returns ok if the flag was set or notsup if not supported by
8369 erts_alloc.
8370 erlang:system_flag(Flag :: fullsweep_after, Number) -> OldNumber
8372 Types:
8374 Number = OldNumber = integer() >= 0
8376 Sets system flag fullsweep_after. Number is a non-negative inte‐
8378 ger indicating how many times generational garbage collections
8379 can be done without forcing a fullsweep collection. The value
8380 applies to new processes, while processes already running are
8381 not affected.
8382 Returns the old value of the flag.
8384 In low-memory systems (especially without virtual memory), set‐
8386 ting the value to 0 can help to conserve memory.
8387 This value can also be set through (OS) environment variable
8389 ERL_FULLSWEEP_AFTER.
8390 erlang:system_flag(Flag :: microstate_accounting, Action) ->
8392 OldState
8393 Types:
8395 Action = true | false | reset
8397 OldState = true | false
8398 Turns on/off microstate accounting measurements. When passing
8400 reset, all counters are reset to 0.
8401 For more information see statistics(microstate_accounting).
8403 erlang:system_flag(Flag :: min_heap_size, MinHeapSize) ->
8405 OldMinHeapSize
8406 Types:
8408 MinHeapSize = OldMinHeapSize = integer() >= 0
8410 Sets the default minimum heap size for processes. The size is
8412 specified in words. The new min_heap_size effects only processes
8413 spawned after the change of min_heap_size has been made.
8414 min_heap_size can be set for individual processes by using
8415 spawn_opt/4 or process_flag/2.
8416 Returns the old value of the flag.
8418 erlang:system_flag(Flag :: min_bin_vheap_size, MinBinVHeapSize) ->
8420 OldMinBinVHeapSize
8421 Types:
8423 MinBinVHeapSize = OldMinBinVHeapSize = integer() >= 0
8425 Sets the default minimum binary virtual heap size for processes.
8427 The size is specified in words. The new min_bin_vhheap_size ef‐
8428 fects only processes spawned after the change of
8429 min_bin_vheap_size has been made. min_bin_vheap_size can be set
8430 for individual processes by using spawn_opt/2,3,4 or
8431 process_flag/2.
8432 Returns the old value of the flag.
8434 erlang:system_flag(Flag :: max_heap_size, MaxHeapSize) ->
8436 OldMaxHeapSize
8437 Types:
8439 MaxHeapSize = OldMaxHeapSize = max_heap_size()
8441 max_heap_size() =
8442 integer() >= 0 |
8443 #{size => integer() >= 0,
8444 kill => boolean(),
8445 error_logger => boolean()}
8446 Sets the default maximum heap size settings for processes. The
8448 size is specified in words. The new max_heap_size effects only
8449 processes spawned efter the change has been made. max_heap_size
8450 can be set for individual processes using spawn_opt/2,3,4 or
8451 process_flag/2.
8452 Returns the old value of the flag.
8454 erlang:system_flag(Flag :: multi_scheduling, BlockState) ->
8456 OldBlockState
8457 Types:
8459 BlockState = block | unblock | block_normal | unblock_normal
8461 OldBlockState = blocked | disabled | enabled
8462 If multi-scheduling is enabled, more than one scheduler thread
8464 is used by the emulator. Multi-scheduling can be blocked in two
8465 different ways. Either all schedulers but one is blocked, or all
8466 normal schedulers but one is blocked. When only normal sched‐
8467 ulers are blocked, dirty schedulers are free to continue to
8468 schedule processes.
8469 If BlockState =:= block, multi-scheduling is blocked. That is,
8471 one and only one scheduler thread will execute. If BlockState
8472 =:= unblock and no one else blocks multi-scheduling, and this
8473 process has blocked only once, multi-scheduling is unblocked.
8474 If BlockState =:= block_normal, normal multi-scheduling is
8476 blocked. That is, only one normal scheduler thread will execute,
8477 but multiple dirty schedulers can execute. If BlockState =:= un‐
8478 block_normal and no one else blocks normal multi-scheduling, and
8479 this process has blocked only once, normal multi-scheduling is
8480 unblocked.
8481 One process can block multi-scheduling and normal multi-schedul‐
8483 ing multiple times. If a process has blocked multiple times, it
8484 must unblock exactly as many times as it has blocked before it
8485 has released its multi-scheduling block. If a process that has
8486 blocked multi-scheduling or normal multi-scheduling exits, it
8487 automatically releases its blocking of multi-scheduling and nor‐
8488 mal multi-scheduling.
8489 The return values are disabled, blocked, blocked_normal, or en‐
8491 abled. The returned value describes the state just after the
8492 call to erlang:system_flag(multi_scheduling, BlockState) has
8493 been made. For information about the return values, see er‐
8494 lang:system_info(multi_scheduling).
8495 Note:
8497 Blocking of multi-scheduling and normal multi-scheduling is nor‐
8498 mally not needed. If you feel that you need to use these fea‐
8499 tures, consider it a few more times again. Blocking multi-sched‐
8500 uling is only to be used as a last resort, as it is most likely
8501 a very inefficient way to solve the problem.
8502 See also erlang:system_info(multi_scheduling), erlang:sys‐
8505 tem_info(normal_multi_scheduling_blockers), erlang:sys‐
8506 tem_info(multi_scheduling_blockers), and erlang:sys‐
8507 tem_info(schedulers).
8508 erlang:system_flag(Flag :: scheduler_bind_type, How) ->
8510 OldBindType
8511 Types:
8513 How = scheduler_bind_type() | default_bind
8515 OldBindType = scheduler_bind_type()
8516 scheduler_bind_type() =
8517 no_node_processor_spread | no_node_thread_spread | no_spread |
8518 processor_spread | spread | thread_spread |
8519 thread_no_node_processor_spread | unbound
8520 Warning:
8522 This argument is deprecated. Instead of using this argument, use
8523 command-line argument +sbt in erl(1). When this argument is re‐
8524 moved, a final scheduler bind type to use is determined at emu‐
8525 lator boot time.
8526 Controls if and how schedulers are bound to logical processors.
8529 When erlang:system_flag(scheduler_bind_type, How) is called, an
8531 asynchronous signal is sent to all schedulers online, causing
8532 them to try to bind or unbind as requested.
8533 Note:
8535 If a scheduler fails to bind, this is often silently ignored, as
8536 it is not always possible to verify valid logical processor
8537 identifiers. If an error is reported, an error event is logged.
8538 To verify that the schedulers have bound as requested, call er‐
8539 lang:system_info(scheduler_bindings).
8540 Schedulers can be bound on newer Linux, Solaris, FreeBSD, and
8543 Windows systems, but more systems will be supported in future
8544 releases.
8545 In order for the runtime system to be able to bind schedulers,
8547 the CPU topology must be known. If the runtime system fails to
8548 detect the CPU topology automatically, it can be defined. For
8549 more information on how to define the CPU topology, see command-
8550 line flag +sct in erl(1).
8551 The runtime system does by default not bind schedulers to logi‐
8553 cal processors.
8554 Note:
8556 If the Erlang runtime system is the only OS process binding
8557 threads to logical processors, this improves the performance of
8558 the runtime system. However, if other OS processes (for example,
8559 another Erlang runtime system) also bind threads to logical pro‐
8560 cessors, there can be a performance penalty instead. Sometimes
8561 this performance penalty can be severe. If so, it is recommended
8562 to not bind the schedulers.
8563 Schedulers can be bound in different ways. Argument How deter‐
8566 mines how schedulers are bound and can be any of the following:
8567 unbound:
8569 Same as command-line argument +sbt u in erl(1).
8570 no_spread:
8572 Same as command-line argument +sbt ns in erl(1).
8573 thread_spread:
8575 Same as command-line argument +sbt ts in erl(1).
8576 processor_spread:
8578 Same as command-line argument +sbt ps in erl(1).
8579 spread:
8581 Same as command-line argument +sbt s in erl(1).
8582 no_node_thread_spread:
8584 Same as command-line argument +sbt nnts in erl(1).
8585 no_node_processor_spread:
8587 Same as command-line argument +sbt nnps in erl(1).
8588 thread_no_node_processor_spread:
8590 Same as command-line argument +sbt tnnps in erl(1).
8591 default_bind:
8593 Same as command-line argument +sbt db in erl(1).
8594 The returned value equals How before flag scheduler_bind_type
8596 was changed.
8597 Failures:
8599 notsup:
8601 If binding of schedulers is not supported.
8602 badarg:
8604 If How is not one of the documented alternatives.
8605 badarg:
8607 If CPU topology information is unavailable.
8608 The scheduler bind type can also be set by passing command-line
8610 argument +sbt to erl(1).
8611 For more information, see erlang:system_info(sched‐
8613 uler_bind_type), erlang:system_info(scheduler_bindings), as well
8614 as command-line flags +sbt and +sct in erl(1).
8615 erlang:system_flag(Flag :: scheduler_wall_time, Boolean) ->
8617 OldBoolean
8618 Types:
8620 Boolean = OldBoolean = boolean()
8622 Turns on or off scheduler wall time measurements.
8624 For more information, see statistics(scheduler_wall_time).
8626 erlang:system_flag(Flag :: schedulers_online, SchedulersOnline) ->
8628 OldSchedulersOnline
8629 Types:
8631 SchedulersOnline = OldSchedulersOnline = integer() >= 1
8633 Sets the number of schedulers online. Range is 1 <= Scheduler‐
8635 sOnline <= erlang:system_info(schedulers).
8636 Returns the old value of the flag.
8638 If the emulator was built with support for dirty schedulers,
8640 changing the number of schedulers online can also change the
8641 number of dirty CPU schedulers online. For example, if 12 sched‐
8642 ulers and 6 dirty CPU schedulers are online, and system_flag/2
8643 is used to set the number of schedulers online to 6, then the
8644 number of dirty CPU schedulers online is automatically decreased
8645 by half as well, down to 3. Similarly, the number of dirty CPU
8646 schedulers online increases proportionally to increases in the
8647 number of schedulers online.
8648 For more information, see erlang:system_info(schedulers) and er‐
8650 lang:system_info(schedulers_online).
8651 erlang:system_flag(Flag :: system_logger, Logger) -> PrevLogger
8653 Types:
8655 Logger = PrevLogger = logger | undefined | pid()
8657 Sets the process that will receive the logging messages gener‐
8659 ated by ERTS. If set to undefined, all logging messages gener‐
8660 ated by ERTS will be dropped. The messages will be in the for‐
8661 mat:
8662 {log,Level,Format,ArgList,Metadata} where
8664 Level = atom(),
8666 Format = string(),
8667 ArgList = list(term()),
8668 Metadata = #{ pid => pid(),
8669 group_leader => pid(),
8670 time := logger:timestamp(),
8671 error_logger := #{ emulator := true, tag := atom() }
8672 If the system_logger process dies, this flag will be reset to
8675 logger.
8676 The default is the process named logger.
8678 Returns the old value of the flag.
8680 Note:
8682 This function is designed to be used by the KERNEL logger. Be
8683 careful if you change it to something else as log messages may
8684 be lost. If you want to intercept emulator log messages, do it
8685 by adding a specialized handler to the KERNEL logger.
8686 erlang:system_flag(Flag :: trace_control_word, TCW) -> OldTCW
8689 Types:
8691 TCW = OldTCW = integer() >= 0
8693 Sets the value of the node trace control word to TCW, which is
8695 to be an unsigned integer. For more information, see function
8696 set_tcw in section "Match Specifications in Erlang" in the
8697 User's Guide.
8698 Returns the old value of the flag.
8700 erlang:system_flag(Flag :: time_offset, Value :: finalize) ->
8702 OldState
8703 Types:
8705 OldState = preliminary | final | volatile
8707 Finalizes the time offset when single time warp mode is used. If
8709 another time warp mode is used, the time offset state is left
8710 unchanged.
8711 Returns the old state identifier, that is:
8713 * If preliminary is returned, finalization was performed and
8715 the time offset is now final.
8716 * If final is returned, the time offset was already in the fi‐
8718 nal state. This either because another erlang:sys‐
8719 tem_flag(time_offset, finalize) call or because no time warp
8720 mode is used.
8721 * If volatile is returned, the time offset cannot be finalized
8723 because multi-time warp mode is used.
8724 erlang:system_info(Item :: version) -> string()
8726 Returns information about the current system. The documentation
8728 of this function is broken into the following sections in order
8729 to make it easier to navigate.
8730 Memory Allocation:
8732 allocated_areas, allocator, alloc_util_allocators, alloca‐
8733 tor_sizes
8734 CPU Topology:
8736 cpu_topology, logical_processors, update_cpu_info
8737 Process Information:
8739 fullsweep_after, garbage_collection, heap_sizes, heap_type,
8740 max_heap_size, message_queue_data, min_heap_size,
8741 min_bin_vheap_size, procs
8742 System Limits:
8744 atom_count, atom_limit, ets_count, ets_limit, port_count,
8745 port_limit, process_count, process_limit
8746 System Time:
8748 end_time, os_monotonic_time_source, os_system_time_source,
8749 start_time, time_correction, time_offset, time_warp_mode,
8750 tolerant_timeofday
8751 Scheduler Information:
8753 dirty_cpu_schedulers, dirty_cpu_schedulers_online,
8754 dirty_io_schedulers, multi_scheduling, multi_schedul‐
8755 ing_blockers, normal_multi_scheduling_blockers, sched‐
8756 uler_bind_type, scheduler_bindings, scheduler_id, sched‐
8757 ulers, smp_support, threads, thread_pool_size
8758 Distribution Information:
8760 creation, delayed_node_table_gc, dist, dist_buf_busy_limit,
8761 dist_ctrl
8762 System Information:
8764 c_compiler_used, check_io, compat_rel, debug_compiled,
8765 driver_version, dynamic_trace, dynamic_trace_probes,
8766 emu_flavor, emu_type, info, kernel_poll, loaded, machine,
8767 modified_timing_level, nif_version, otp_release, port_paral‐
8768 lelism, system_architecture, system_logger, system_version,
8769 trace_control_word, version, wordsize
8770 erlang:system_info(Item :: allocated_areas) -> [tuple()]
8772 erlang:system_info(Item :: allocator) ->
8774 {Allocator, Version, Features, Settings}
8775 erlang:system_info(Item :: {allocator, Alloc}) -> [term()]
8777 erlang:system_info(Item :: alloc_util_allocators) -> [Alloc]
8779 erlang:system_info(Item :: {allocator_sizes, Alloc}) -> [term()]
8781 Types:
8783 Allocator = undefined | glibc
8785 Version = [integer() >= 0]
8786 Features = [atom()]
8787 Settings =
8788 [{Subsystem :: atom(),
8789 [{Parameter :: atom(), Value :: term()}]}]
8790 Alloc = atom()
8791 Returns various information about the memory allocators of the
8793 current system (emulator) as specified by Item:
8794 allocated_areas:
8796 Returns a list of tuples with information about miscella‐
8797 neous allocated memory areas.
8798 Each tuple contains an atom describing the type of memory as
8800 first element and the amount of allocated memory in bytes as
8801 second element. When information about allocated and used
8802 memory is present, also a third element is present, contain‐
8803 ing the amount of used memory in bytes.
8804 erlang:system_info(allocated_areas) is intended for debug‐
8806 ging, and the content is highly implementation-dependent.
8807 The content of the results therefore changes when needed
8808 without prior notice.
8809 Notice that the sum of these values is not the total amount
8811 of memory allocated by the emulator. Some values are part of
8812 other values, and some memory areas are not part of the re‐
8813 sult. For information about the total amount of memory allo‐
8814 cated by the emulator, see erlang:memory/0,1.
8815 allocator:
8817 Returns {Allocator, Version, Features, Settings, where:
8818 * Allocator corresponds to the malloc() implementation used.
8820 If Allocator equals undefined, the malloc() implementation
8821 used cannot be identified. glibc can be identified.
8822 * Version is a list of integers (but not a string) repre‐
8824 senting the version of the malloc() implementation used.
8825 * Features is a list of atoms representing the allocation
8827 features used.
8828 * Settings is a list of subsystems, their configurable pa‐
8830 rameters, and used values. Settings can differ between
8831 different combinations of platforms, allocators, and allo‐
8832 cation features. Memory sizes are given in bytes.
8833 See also "System Flags Effecting erts_alloc" in erts_al‐
8835 loc(3).
8836 {allocator, Alloc}:
8838 Returns information about the specified allocator. As from
8839 ERTS 5.6.1, the return value is a list of {instance, Instan‐
8840 ceNo, InstanceInfo} tuples, where InstanceInfo contains in‐
8841 formation about a specific instance of the allocator. If Al‐
8842 loc is not a recognized allocator, undefined is returned. If
8843 Alloc is disabled, false is returned.
8844 Notice that the information returned is highly implementa‐
8846 tion-dependent and can be changed or removed at any time
8847 without prior notice. It was initially intended as a tool
8848 when developing new allocators, but as it can be of interest
8849 for others it has been briefly documented.
8850 The recognized allocators are listed in erts_alloc(3). In‐
8852 formation about super carriers can be obtained from ERTS 8.0
8853 with {allocator, erts_mmap} or from ERTS 5.10.4; the re‐
8854 turned list when calling with {allocator, mseg_alloc} also
8855 includes an {erts_mmap, _} tuple as one element in the list.
8856 After reading the erts_alloc(3) documentation, the returned
8858 information more or less speaks for itself, but it can be
8859 worth explaining some things. Call counts are presented by
8860 two values, the first value is giga calls, and the second
8861 value is calls. mbcs and sbcs denote multi-block carriers,
8862 and single-block carriers, respectively. Sizes are presented
8863 in bytes. When a size is not presented, it is the amount of
8864 something. Sizes and amounts are often presented by three
8865 values:
8866 * The first is the current value.
8868 * The second is the maximum value since the last call to er‐
8870 lang:system_info({allocator, Alloc}).
8871 * The third is the maximum value since the emulator was
8873 started.
8874 If only one value is present, it is the current value.
8876 fix_alloc memory block types are presented by two values.
8877 The first value is the memory pool size and the second value
8878 is the used memory size.
8879 alloc_util_allocators:
8881 Returns a list of the names of all allocators using the ERTS
8882 internal alloc_util framework as atoms. For more informa‐
8883 tion, see section The alloc_util framework in erts_alloc(3).
8884 {allocator_sizes, Alloc}:
8886 Returns various size information for the specified alloca‐
8887 tor. The information returned is a subset of the information
8888 returned by erlang:system_info({allocator, Alloc}).
8889 erlang:system_info(Item :: cpu_topology) -> CpuTopology
8891 erlang:system_info(Item ::
8893 {cpu_topology, defined | detected | used}) ->
8894 CpuTopology
8895 erlang:system_info(Item ::
8897 logical_processors |
8898 logical_processors_available |
8899 logical_processors_online) ->
8900 unknown | integer() >= 1
8901 erlang:system_info(Item :: update_cpu_info) -> changed | unchanged
8903 Types:
8905 cpu_topology() = [LevelEntry :: level_entry()] | undefined
8907 All LevelEntrys of a list must contain the same LevelTag,
8908 except on the top level where both node and processor‐
8909 LevelTags can coexist.
8910 level_entry() =
8911 {LevelTag :: level_tag(), SubLevel :: sub_level()} |
8912 {LevelTag :: level_tag(),
8913 InfoList :: info_list(),
8914 SubLevel :: sub_level()}
8915 {LevelTag, SubLevel} == {LevelTag, [], SubLevel}
8916 level_tag() = core | node | processor | thread
8917 More LevelTags can be introduced in a future release.
8918 sub_level() =
8919 [LevelEntry :: level_entry()] |
8920 (LogicalCpuId :: {logical, integer() >= 0})
8921 info_list() = []
8922 The info_list() can be extended in a future release.
8923 Returns various information about the CPU topology of the cur‐
8925 rent system (emulator) as specified by Item:
8926 cpu_topology:
8928 Returns the CpuTopology currently used by the emulator. The
8929 CPU topology is used when binding schedulers to logical pro‐
8930 cessors. The CPU topology used is the user-defined CPU
8931 topology, if such exists, otherwise the automatically de‐
8932 tected CPU topology, if such exists. If no CPU topology ex‐
8933 ists, undefined is returned.
8934 node refers to Non-Uniform Memory Access (NUMA) nodes.
8936 thread refers to hardware threads (for example, Intel hyper-
8937 threads).
8938 A level in term CpuTopology can be omitted if only one entry
8940 exists and InfoList is empty.
8941 thread can only be a sublevel to core. core can be a sub‐
8943 level to processor or node. processor can be on the top
8944 level or a sublevel to node. node can be on the top level or
8945 a sublevel to processor. That is, NUMA nodes can be proces‐
8946 sor internal or processor external. A CPU topology can con‐
8947 sist of a mix of processor internal and external NUMA nodes,
8948 as long as each logical CPU belongs to one NUMA node. Cache
8949 hierarchy is not part of the CpuTopology type, but will be
8950 in a future release. Other things can also make it into the
8951 CPU topology in a future release. So, expect the CpuTopology
8952 type to change.
8953 {cpu_topology, defined}:
8955 Returns the user-defined CpuTopology. For more information,
8958 see command-line flag +sct in erl(1) and argument cpu_topol‐
8959 ogy.
8960 {cpu_topology, detected}:
8962 Returns the automatically detected CpuTopologyy. The emula‐
8965 tor detects the CPU topology on some newer Linux, Solaris,
8966 FreeBSD, and Windows systems. On Windows system with more
8967 than 32 logical processors, the CPU topology is not de‐
8968 tected.
8969 For more information, see argument cpu_topology.
8971 {cpu_topology, used}:
8973 Returns CpuTopology used by the emulator. For more informa‐
8974 tion, see argument cpu_topology.
8975 logical_processors:
8977 Returns the detected number of logical processors configured
8978 in the system. The return value is either an integer, or the
8979 atom unknown if the emulator cannot detect the configured
8980 logical processors.
8981 logical_processors_available:
8983 Returns the detected number of logical processors available
8984 to the Erlang runtime system. The return value is either an
8985 integer, or the atom unknown if the emulator cannot detect
8986 the available logical processors. The number of available
8987 logical processors is less than or equal to the number of
8988 logical processors online.
8989 logical_processors_online:
8991 Returns the detected number of logical processors online on
8992 the system. The return value is either an integer, or the
8993 atom unknown if the emulator cannot detect logical proces‐
8994 sors online. The number of logical processors online is less
8995 than or equal to the number of logical processors config‐
8996 ured.
8997 cpu_quota:
8999 Returns the detected CPU quota the emulator is limited by.
9000 The return value is an integer saying how many processors'
9001 worth of runtime we get (between 1 and the number of logical
9002 processors), or the atom unknown if the emulator cannot de‐
9003 tect a quota.
9004 update_cpu_info:
9006 The runtime system rereads the CPU information available and
9007 updates its internally stored information about the detected
9008 CPU topology and the number of logical processors config‐
9009 ured, online, available, and cpu quota.
9010 If the CPU information has changed since the last time it
9012 was read, the atom changed is returned, otherwise the atom
9013 unchanged. If the CPU information has changed, you probably
9014 want to adjust the number of schedulers online. You typi‐
9015 cally want to have as many schedulers online as logical pro‐
9016 cessors available.
9017 erlang:system_info(Item :: fullsweep_after) ->
9019 {fullsweep_after, integer() >= 0}
9020 erlang:system_info(Item :: garbage_collection) ->
9022 [{atom(), integer()}]
9023 erlang:system_info(Item :: heap_sizes) -> [integer() >= 0]
9025 erlang:system_info(Item :: heap_type) -> private
9027 erlang:system_info(Item :: max_heap_size) ->
9029 {max_heap_size,
9030 MaxHeapSize :: max_heap_size()}
9031 erlang:system_info(Item :: message_queue_data) ->
9033 message_queue_data()
9034 erlang:system_info(Item :: min_heap_size) ->
9036 {min_heap_size,
9037 MinHeapSize :: integer() >= 1}
9038 erlang:system_info(Item :: min_bin_vheap_size) ->
9040 {min_bin_vheap_size,
9041 MinBinVHeapSize :: integer() >= 1}
9042 erlang:system_info(Item :: procs) -> binary()
9044 Types:
9046 message_queue_data() = off_heap | on_heap
9048 max_heap_size() =
9049 integer() >= 0 |
9050 #{size => integer() >= 0,
9051 kill => boolean(),
9052 error_logger => boolean()}
9053 Returns information about the default process heap settings:
9055 fullsweep_after:
9057 Returns {fullsweep_after, integer() >= 0}, which is the
9058 fullsweep_after garbage collection setting used by default.
9059 For more information, see garbage_collection described be‐
9060 low.
9061 garbage_collection:
9063 Returns a list describing the default garbage collection
9064 settings. A process spawned on the local node by a spawn or
9065 spawn_link uses these garbage collection settings. The de‐
9066 fault settings can be changed by using erlang:system_flag/2.
9067 spawn_opt/2,3,4 can spawn a process that does not use the
9068 default settings.
9069 heap_sizes:
9071 Returns a list of integers representing valid heap sizes in
9072 words. All Erlang heaps are sized from sizes in this list.
9073 heap_type:
9075 Returns the heap type used by the current emulator. One heap
9076 type exists:
9077 private:
9079 Each process has a heap reserved for its use and no ref‐
9080 erences between heaps of different processes are allowed.
9081 Messages passed between processes are copied between
9082 heaps.
9083 max_heap_size:
9085 Returns {max_heap_size, MaxHeapSize}, where MaxHeapSize is
9086 the current system-wide maximum heap size settings for
9087 spawned processes. This setting can be set using the com‐
9088 mand-line flags +hmax, +hmaxk and +hmaxel in erl(1). It can
9089 also be changed at runtime using erlang:sys‐
9090 tem_flag(max_heap_size, MaxHeapSize). For more details about
9091 the max_heap_size process flag, see
9092 process_flag(max_heap_size, MaxHeapSize).
9093 message_queue_data:
9095 Returns the default value of the message_queue_data process
9096 flag, which can be either off_heap or on_heap. The default
9097 value is set by the command-line argument +hmqd in erl(1).
9098 For more information, see the documentation of
9099 process_flag(message_queue_data, MQD).
9100 min_heap_size:
9102 Returns {min_heap_size, MinHeapSize}, where MinHeapSize is
9103 the current system-wide minimum heap size for spawned pro‐
9104 cesses.
9105 min_bin_vheap_size:
9107 Returns {min_bin_vheap_size, MinBinVHeapSize}, where MinBin‐
9108 VHeapSize is the current system-wide minimum binary virtual
9109 heap size for spawned processes.
9110 procs:
9112 Returns a binary containing a string of process and port in‐
9113 formation formatted as in Erlang crash dumps. For more in‐
9114 formation, see section How to interpret the Erlang crash
9115 dumps in the User's Guide.
9116 erlang:system_info(Item :: atom_count) -> integer() >= 1
9118 erlang:system_info(Item :: atom_limit) -> integer() >= 1
9120 erlang:system_info(Item :: ets_count) -> integer() >= 1
9122 erlang:system_info(Item :: ets_limit) -> integer() >= 1
9124 erlang:system_info(Item :: port_count) -> integer() >= 0
9126 erlang:system_info(Item :: port_limit) -> integer() >= 1
9128 erlang:system_info(Item :: process_count) -> integer() >= 1
9130 erlang:system_info(Item :: process_limit) -> integer() >= 1
9132 Returns information about the current system (emulator) limits
9134 as specified by Item:
9135 atom_count:
9137 Returns the number of atoms currently existing at the local
9138 node. The value is given as an integer.
9139 atom_limit:
9141 Returns the maximum number of atoms allowed. This limit can
9142 be increased at startup by passing command-line flag +t to
9143 erl(1).
9144 ets_count:
9146 Returns the number of ETS tables currently existing at the
9147 local node.
9148 ets_limit:
9150 Returns the limit for number of ETS tables. This limit is
9151 partially obsolete and number of tables are only limited by
9152 available memory.
9153 port_count:
9155 Returns the number of ports currently existing at the local
9156 node. The value is given as an integer. This is the same
9157 value as returned by length(erlang:ports()), but more effi‐
9158 cient.
9159 port_limit:
9161 Returns the maximum number of simultaneously existing ports
9162 at the local node as an integer. This limit can be config‐
9163 ured at startup by using command-line flag +Q in erl(1).
9164 process_count:
9166 Returns the number of processes currently existing at the
9167 local node. The value is given as an integer. This is the
9168 same value as returned by length(processes()), but more ef‐
9169 ficient.
9170 process_limit:
9172 Returns the maximum number of simultaneously existing pro‐
9173 cesses at the local node. The value is given as an integer.
9174 This limit can be configured at startup by using command-
9175 line flag +P in erl(1).
9176 erlang:system_info(Item :: end_time) -> integer() >= 0
9178 erlang:system_info(Item :: os_monotonic_time_source) ->
9180 [{atom(), term()}]
9181 erlang:system_info(Item :: os_system_time_source) ->
9183 [{atom(), term()}]
9184 erlang:system_info(Item :: start_time) -> integer()
9186 erlang:system_info(Item :: time_correction) -> true | false
9188 erlang:system_info(Item :: time_offset) ->
9190 preliminary | final | volatile
9191 erlang:system_info(Item :: time_warp_mode) ->
9193 no_time_warp | single_time_warp |
9194 multi_time_warp
9195 erlang:system_info(Item :: tolerant_timeofday) ->
9197 enabled | disabled
9198 Returns information about the current system (emulator) time as
9200 specified by Item:
9201 end_time:
9203 The last Erlang monotonic time in native time unit that can
9204 be represented internally in the current Erlang runtime sys‐
9205 tem instance. The time between the start time and the end
9206 time is at least a quarter of a millennium.
9207 os_monotonic_time_source:
9209 Returns a list containing information about the source of OS
9210 monotonic time that is used by the runtime system.
9211 If [] is returned, no OS monotonic time is available. The
9213 list contains two-tuples with Keys as first element, and
9214 Values as second element. The order of these tuples is unde‐
9215 fined. The following tuples can be part of the list, but
9216 more tuples can be introduced in the future:
9217 {function, Function}:
9219 Function is the name of the function used. This tuple al‐
9220 ways exists if OS monotonic time is available to the run‐
9221 time system.
9222 {clock_id, ClockId}:
9224 This tuple only exists if Function can be used with dif‐
9225 ferent clocks. ClockId corresponds to the clock identifier
9226 used when calling Function.
9227 {resolution, OsMonotonicTimeResolution}:
9229 Highest possible resolution of current OS monotonic time
9230 source as parts per second. If no resolution information
9231 can be retrieved from the OS, OsMonotonicTimeResolution is
9232 set to the resolution of the time unit of Functions return
9233 value. That is, the actual resolution can be lower than
9234 OsMonotonicTimeResolution. Notice that the resolution does
9235 not say anything about the accuracy or whether the pre‐
9236 cision aligns with the resolution. You do, however, know
9237 that the precision is not better than OsMonotonicTimeReso‐
9238 lution.
9239 {extended, Extended}:
9241 Extended equals yes if the range of time values has been
9242 extended; otherwise Extended equals no. The range must be
9243 extended if Function returns values that wrap fast. This
9244 typically is the case when the return value is a 32-bit
9245 value.
9246 {parallel, Parallel}:
9248 Parallel equals yes if Function is called in parallel from
9249 multiple threads. If it is not called in parallel, because
9250 calls must be serialized, Parallel equals no.
9251 {time, OsMonotonicTime}:
9253 OsMonotonicTime equals current OS monotonic time in native
9254 time unit.
9255 os_system_time_source:
9257 Returns a list containing information about the source of OS
9258 system time that is used by the runtime system.
9259 The list contains two-tuples with Keys as first element, and
9261 Values as second element. The order of these tuples is unde‐
9262 fined. The following tuples can be part of the list, but
9263 more tuples can be introduced in the future:
9264 {function, Function}:
9266 Function is the name of the funcion used.
9267 {clock_id, ClockId}:
9269 Exists only if Function can be used with different clocks.
9270 ClockId corresponds to the clock identifier used when
9271 calling Function.
9272 {resolution, OsSystemTimeResolution}:
9274 Highest possible resolution of current OS system time
9275 source as parts per second. If no resolution information
9276 can be retrieved from the OS, OsSystemTimeResolution is
9277 set to the resolution of the time unit of Functions return
9278 value. That is, the actual resolution can be lower than
9279 OsSystemTimeResolution. Notice that the resolution does
9280 not say anything about the accuracy or whether the pre‐
9281 cision do align with the resolution. You do, however, know
9282 that the precision is not better than OsSystemTimeResolu‐
9283 tion.
9284 {parallel, Parallel}:
9286 Parallel equals yes if Function is called in parallel from
9287 multiple threads. If it is not called in parallel, because
9288 calls needs to be serialized, Parallel equals no.
9289 {time, OsSystemTime}:
9291 OsSystemTime equals current OS system time in native time
9292 unit.
9293 start_time:
9295 The Erlang monotonic time in native time unit at the time
9296 when current Erlang runtime system instance started.
9297 See also erlang:system_info(end_time).
9299 time_correction:
9301 Returns a boolean value indicating whether time correction
9302 is enabled or not.
9303 time_offset:
9305 Returns the state of the time offset:
9306 preliminary:
9308 The time offset is preliminary, and will be changed and
9309 finalized later. The preliminary time offset is used dur‐
9310 ing the preliminary phase of the single time warp mode.
9311 final:
9313 The time offset is final. This either because no time
9314 warp mode is used, or because the time offset have been
9315 finalized when single time warp mode is used.
9316 volatile:
9318 The time offset is volatile. That is, it can change at any
9319 time. This is because multi-time warp mode is used.
9320 time_warp_mode:
9322 Returns a value identifying the time warp mode that is
9323 used:
9324 no_time_warp:
9326 The no time warp mode is used.
9327 single_time_warp:
9329 The single time warp mode is used.
9330 multi_time_warp:
9332 The multi-time warp mode is used.
9333 tolerant_timeofday:
9335 Returns whether a pre ERTS 7.0 backwards compatible compen‐
9336 sation for sudden changes of system time is enabled or dis‐
9337 abled. Such compensation is enabled when the time offset is
9338 final, and time correction is enabled.
9339 erlang:system_info(Item :: dirty_cpu_schedulers) ->
9341 integer() >= 0
9342 erlang:system_info(Item :: dirty_cpu_schedulers_online) ->
9344 integer() >= 0
9345 erlang:system_info(Item :: dirty_io_schedulers) ->
9347 integer() >= 0
9348 erlang:system_info(Item :: multi_scheduling) ->
9350 disabled | blocked | blocked_normal |
9351 enabled
9352 erlang:system_info(Item :: multi_scheduling_blockers) ->
9354 [Pid :: pid()]
9355 erlang:system_info(Item :: normal_multi_scheduling_blockers) ->
9357 [Pid :: pid()]
9358 erlang:system_info(Item :: scheduler_bind_type) ->
9360 spread | processor_spread | thread_spread |
9361 thread_no_node_processor_spread |
9362 no_node_processor_spread |
9363 no_node_thread_spread | no_spread | unbound
9364 erlang:system_info(Item :: scheduler_bindings) -> tuple()
9366 erlang:system_info(Item :: scheduler_id) ->
9368 SchedulerId :: integer() >= 1
9369 erlang:system_info(Item :: schedulers | schedulers_online) ->
9371 integer() >= 1
9372 erlang:system_info(Item :: smp_support) -> boolean()
9374 erlang:system_info(Item :: threads) -> boolean()
9376 erlang:system_info(Item :: thread_pool_size) -> integer() >= 0
9378 Returns information about schedulers, scheduling and threads in
9380 the current system as specified by Item:
9381 dirty_cpu_schedulers:
9383 Returns the number of dirty CPU scheduler threads used by
9384 the emulator. Dirty CPU schedulers execute CPU-bound native
9385 functions, such as NIFs, linked-in driver code, and BIFs
9386 that cannot be managed cleanly by the normal emulator sched‐
9387 ulers.
9388 The number of dirty CPU scheduler threads is determined at
9390 emulator boot time and cannot be changed after that. How‐
9391 ever, the number of dirty CPU scheduler threads online can
9392 be changed at any time. The number of dirty CPU schedulers
9393 can be set at startup by passing command-line flag +SDcpu or
9394 +SDPcpu in erl(1).
9395 See also erlang:system_flag(dirty_cpu_schedulers_online,
9397 DirtyCPUSchedulersOnline), erlang:sys‐
9398 tem_info(dirty_cpu_schedulers_online), erlang:sys‐
9399 tem_info(dirty_io_schedulers), erlang:system_info(sched‐
9400 ulers), erlang:system_info(schedulers_online), and er‐
9401 lang:system_flag(schedulers_online, SchedulersOnline).
9402 dirty_cpu_schedulers_online:
9404 Returns the number of dirty CPU schedulers online. The re‐
9405 turn value satisfies 1 <= DirtyCPUSchedulersOnline <= N,
9406 where N is the smallest of the return values of erlang:sys‐
9407 tem_info(dirty_cpu_schedulers) and erlang:system_info(sched‐
9408 ulers_online).
9409 The number of dirty CPU schedulers online can be set at
9411 startup by passing command-line flag +SDcpu in erl(1).
9412 For more information, see erlang:sys‐
9414 tem_info(dirty_cpu_schedulers), erlang:sys‐
9415 tem_info(dirty_io_schedulers), erlang:system_info(sched‐
9416 ulers_online), and erlang:system_flag(dirty_cpu_sched‐
9417 ulers_online, DirtyCPUSchedulersOnline).
9418 dirty_io_schedulers:
9420 Returns the number of dirty I/O schedulers as an integer.
9421 Dirty I/O schedulers execute I/O-bound native functions,
9422 such as NIFs and linked-in driver code, which cannot be man‐
9423 aged cleanly by the normal emulator schedulers.
9424 This value can be set at startup by passing command-line ar‐
9426 gument +SDio in erl(1).
9427 For more information, see erlang:sys‐
9429 tem_info(dirty_cpu_schedulers), erlang:sys‐
9430 tem_info(dirty_cpu_schedulers_online), and erlang:sys‐
9431 tem_flag(dirty_cpu_schedulers_online, DirtyCPUSchedulersOn‐
9432 line).
9433 multi_scheduling:
9435 Returns one of the following:
9436 disabled:
9438 The emulator has been started with only one scheduler
9439 thread.
9440 blocked:
9442 The emulator has more than one scheduler thread, but all
9443 scheduler threads except one are blocked. That is, only
9444 one scheduler thread schedules Erlang processes and exe‐
9445 cutes Erlang code.
9446 blocked_normal:
9448 The emulator has more than one scheduler thread, but all
9449 normal scheduler threads except one are blocked. Notice
9450 that dirty schedulers are not blocked, and can schedule
9451 Erlang processes and execute native code.
9452 enabled:
9454 The emulator has more than one scheduler thread, and no
9455 scheduler threads are blocked. That is, all available
9456 scheduler threads schedule Erlang processes and execute
9457 Erlang code.
9458 See also erlang:system_flag(multi_scheduling, BlockState),
9460 erlang:system_info(multi_scheduling_blockers), erlang:sys‐
9461 tem_info(normal_multi_scheduling_blockers), and erlang:sys‐
9462 tem_info(schedulers).
9463 multi_scheduling_blockers:
9465 Returns a list of Pids when multi-scheduling is blocked,
9466 otherwise the empty list is returned. The Pids in the list
9467 represent all the processes currently blocking multi-sched‐
9468 uling. A Pid occurs only once in the list, even if the cor‐
9469 responding process has blocked multiple times.
9470 See also erlang:system_flag(multi_scheduling, BlockState),
9472 erlang:system_info(multi_scheduling), erlang:sys‐
9473 tem_info(normal_multi_scheduling_blockers), and erlang:sys‐
9474 tem_info(schedulers).
9475 normal_multi_scheduling_blockers:
9477 Returns a list of Pids when normal multi-scheduling is
9478 blocked (that is, all normal schedulers but one is blocked),
9479 otherwise the empty list is returned. The Pids in the list
9480 represent all the processes currently blocking normal multi-
9481 scheduling. A Pid occurs only once in the list, even if the
9482 corresponding process has blocked multiple times.
9483 See also erlang:system_flag(multi_scheduling, BlockState),
9485 erlang:system_info(multi_scheduling), erlang:sys‐
9486 tem_info(multi_scheduling_blockers), and erlang:sys‐
9487 tem_info(schedulers).
9488 scheduler_bind_type:
9490 Returns information about how the user has requested sched‐
9491 ulers to be bound or not bound.
9492 Notice that although a user has requested schedulers to be
9494 bound, they can silently have failed to bind. To inspect the
9495 scheduler bindings, call erlang:system_info(scheduler_bind‐
9496 ings).
9497 For more information, see command-line argument +sbt in
9499 erl(1) and erlang:system_info(scheduler_bindings).
9500 scheduler_bindings:
9502 Returns information about the currently used scheduler bind‐
9503 ings.
9504 A tuple of a size equal to erlang:system_info(schedulers) is
9506 returned. The tuple elements are integers or the atom un‐
9507 bound. Logical processor identifiers are represented as in‐
9508 tegers. The Nth element of the tuple equals the current
9509 binding for the scheduler with the scheduler identifier
9510 equal to N. For example, if the schedulers are bound, ele‐
9511 ment(erlang:system_info(scheduler_id), erlang:sys‐
9512 tem_info(scheduler_bindings)) returns the identifier of the
9513 logical processor that the calling process is executing on.
9514 Notice that only schedulers online can be bound to logical
9516 processors.
9517 For more information, see command-line argument +sbt in
9519 erl(1) and erlang:system_info(schedulers_online).
9520 scheduler_id:
9522 Returns the scheduler ID (SchedulerId) of the scheduler
9523 thread that the calling process is executing on. SchedulerId
9524 is a positive integer, where 1 <= SchedulerId <= erlang:sys‐
9525 tem_info(schedulers).
9526 See also erlang:system_info(schedulers).
9528 schedulers:
9530 Returns the number of scheduler threads used by the emula‐
9531 tor. Scheduler threads online schedules Erlang processes and
9532 Erlang ports, and execute Erlang code and Erlang linked-in
9533 driver code.
9534 The number of scheduler threads is determined at emulator
9536 boot time and cannot be changed later. However, the number
9537 of schedulers online can be changed at any time.
9538 See also erlang:system_flag(schedulers_online, SchedulersOn‐
9540 line), erlang:system_info(schedulers_online), erlang:sys‐
9541 tem_info(scheduler_id), erlang:system_flag(multi_scheduling,
9542 BlockState), erlang:system_info(multi_scheduling), er‐
9543 lang:system_info(normal_multi_scheduling_blockers) and er‐
9544 lang:system_info(multi_scheduling_blockers).
9545 schedulers_online:
9547 Returns the number of schedulers online. The scheduler iden‐
9548 tifiers of schedulers online satisfy the relationship 1 <=
9549 SchedulerId <= erlang:system_info(schedulers_online).
9550 For more information, see erlang:system_info(schedulers) and
9552 erlang:system_flag(schedulers_online, SchedulersOnline).
9553 smp_support:
9555 Returns true.
9556 threads:
9558 Returns true.
9559 thread_pool_size:
9561 Returns the number of async threads in the async thread pool
9564 used for asynchronous driver calls
9565 (erl_driver:driver_async()). The value is given as an inte‐
9566 ger.
9567 erlang:system_info(Item :: creation) -> integer()
9569 erlang:system_info(Item :: delayed_node_table_gc) ->
9571 infinity | integer() >= 0
9572 erlang:system_info(Item :: dist) -> binary()
9574 erlang:system_info(Item :: dist_buf_busy_limit) ->
9576 integer() >= 0
9577 erlang:system_info(Item :: dist_ctrl) ->
9579 {Node :: node(),
9580 ControllingEntity :: port() | pid()}
9581 Returns information about Erlang Distribution in the current
9583 system as specified by Item:
9584 creation:
9586 Returns the creation of the local node as an integer. The
9587 creation is changed when a node is restarted. The creation
9588 of a node is stored in process identifiers, port identi‐
9589 fiers, and references. This makes it (to some extent) possi‐
9590 ble to distinguish between identifiers from different incar‐
9591 nations of a node. The valid creations are integers in the
9592 range 1..3, but this will probably change in a future re‐
9593 lease. If the node is not alive, 0 is returned.
9594 delayed_node_table_gc:
9596 Returns the amount of time in seconds garbage collection of
9597 an entry in a node table is delayed. This limit can be set
9598 on startup by passing command-line flag +zdntgc to erl(1).
9599 For more information, see the documentation of the command-
9600 line flag.
9601 dist:
9603 Returns a binary containing a string of distribution infor‐
9604 mation formatted as in Erlang crash dumps. For more informa‐
9605 tion, see section How to interpret the Erlang crash dumps
9606 in the User's Guide.
9607 dist_buf_busy_limit:
9609 Returns the value of the distribution buffer busy limit in
9610 bytes. This limit can be set at startup by passing command-
9611 line flag +zdbbl to erl(1).
9612 dist_ctrl:
9614 Returns a list of tuples {Node, ControllingEntity}, one en‐
9615 try for each connected remote node. Node is the node name
9616 and ControllingEntity is the port or process identifier re‐
9617 sponsible for the communication to that node. More specifi‐
9618 cally, ControllingEntity for nodes connected through TCP/IP
9619 (the normal case) is the socket used in communication with
9620 the specific node.
9621 erlang:system_info(Item :: c_compiler_used) -> {atom(), term()}
9623 erlang:system_info(Item :: check_io) -> [term()]
9625 erlang:system_info(Item :: compat_rel) -> integer()
9627 erlang:system_info(Item :: debug_compiled) -> boolean()
9629 erlang:system_info(Item :: driver_version) -> string()
9631 erlang:system_info(Item :: dynamic_trace) ->
9633 none | dtrace | systemtap
9634 erlang:system_info(Item :: dynamic_trace_probes) -> boolean()
9636 erlang:system_info(Item :: emu_flavor) -> emu | jit
9638 erlang:system_info(Item :: emu_type) ->
9640 opt | debug | gcov | valgrind | gprof |
9641 lcnt | frmptr
9642 erlang:system_info(Item :: info) -> binary()
9644 erlang:system_info(Item :: kernel_poll) -> boolean()
9646 erlang:system_info(Item :: loaded) -> binary()
9648 erlang:system_info(Item :: machine) -> string()
9650 erlang:system_info(Item :: modified_timing_level) ->
9652 integer() | undefined
9653 erlang:system_info(Item :: nif_version) -> string()
9655 erlang:system_info(Item :: otp_release) -> string()
9657 erlang:system_info(Item :: port_parallelism) -> boolean()
9659 erlang:system_info(Item :: system_architecture) -> string()
9661 erlang:system_info(Item :: system_logger) ->
9663 logger | undefined | pid()
9664 erlang:system_info(Item :: system_version) -> string()
9666 erlang:system_info(Item :: trace_control_word) ->
9668 integer() >= 0
9669 erlang:system_info(Item :: version) -> string()
9671 erlang:system_info(Item ::
9673 wordsize |
9674 {wordsize, internal} |
9675 {wordsize, external}) ->
9676 4 | 8
9677 Returns various information about the current system (emulator)
9679 as specified by Item:
9680 build_type:
9682 Deprecated, use emu_type instead
9683 c_compiler_used:
9685 Returns a two-tuple describing the C compiler used when com‐
9686 piling the runtime system. The first element is an atom de‐
9687 scribing the name of the compiler, or undefined if unknown.
9688 The second element is a term describing the version of the
9689 compiler, or undefined if unknown.
9690 check_io:
9692 Returns a list containing miscellaneous information about
9693 the emulators internal I/O checking. Notice that the content
9694 of the returned list can vary between platforms and over
9695 time. It is only guaranteed that a list is returned.
9696 compat_rel:
9698 Returns the compatibility mode of the local node as an inte‐
9699 ger. The integer returned represents the Erlang/OTP release
9700 that the current emulator has been set to be backward com‐
9701 patible with. The compatibility mode can be configured at
9702 startup by using command-line flag +R in erl(1).
9703 debug_compiled:
9705 Returns true if the emulator has been debug-compiled, other‐
9706 wise false.
9707 driver_version:
9709 Returns a string containing the Erlang driver version used
9710 by the runtime system. It has the form "<major ver>.<minor
9711 ver>".
9712 dynamic_trace:
9714 Returns an atom describing the dynamic trace framework com‐
9715 piled into the virtual machine. It can be dtrace, systemtap,
9716 or none. For a commercial or standard build, it is always
9717 none. The other return values indicate a custom configura‐
9718 tion (for example, ./configure --with-dynamic-trace=dtrace).
9719 For more information about dynamic tracing, see dyntrace(3)
9720 manual page and the README.dtrace/README.systemtap files in
9721 the Erlang source code top directory.
9722 dynamic_trace_probes:
9724 Returns a boolean() indicating if dynamic trace probes
9725 (dtrace or systemtap) are built into the emulator. This can
9726 only be true if the virtual machine was built for dynamic
9727 tracing (that is, system_info(dynamic_trace) returns dtrace
9728 or systemtap).
9729 emu_flavor:
9731 Returns an atom describing the flavor of the runtime system.
9732 This will be either emu or jit. Possible return values can
9733 be added or removed at any time without prior notice.
9734 emu_type:
9736 Returns an atom describing the build type of the runtime
9737 system. This is normally the atom opt for optimized. Other
9738 possible return values are debug, gcov, valgrind, gprof, and
9739 lcnt. Possible return values can be added or removed at any
9740 time without prior notice.
9741 info:
9743 Returns a binary containing a string of miscellaneous system
9744 information formatted as in Erlang crash dumps. For more in‐
9745 formation, see section How to interpret the Erlang crash
9746 dumps in the User's Guide.
9747 kernel_poll:
9749 Returns true if the emulator uses some kind of kernel-poll
9750 implementation, otherwise false.
9751 loaded:
9753 Returns a binary containing a string of loaded module infor‐
9754 mation formatted as in Erlang crash dumps. For more informa‐
9755 tion, see section How to interpret the Erlang crash dumps in
9756 the User's Guide.
9757 machine:
9759 Returns a string containing the Erlang machine name.
9760 modified_timing_level:
9762 Returns the modified timing-level (an integer) if modified
9763 timing is enabled, otherwise undefined. For more information
9764 about modified timing, see command-line flag +T in erl(1)
9765 nif_version:
9767 Returns a string containing the version of the Erlang NIF
9768 interface used by the runtime system. It is on the form
9769 "<major ver>.<minor ver>".
9770 otp_release:
9772 Returns a string containing the OTP release number of the
9775 OTP release that the currently executing ERTS application is
9776 part of.
9777 As from Erlang/OTP 17, the OTP release number corresponds to
9779 the major OTP version number. No erlang:system_info() argu‐
9780 ment gives the exact OTP version. This is because the exact
9781 OTP version in the general case is difficult to determine.
9782 For more information, see the description of versions in
9783 System principles in System Documentation.
9784 port_parallelism:
9786 Returns the default port parallelism scheduling hint used.
9787 For more information, see command-line argument +spp in
9788 erl(1).
9789 system_architecture:
9791 Returns a string containing the processor and OS architec‐
9792 ture the emulator is built for.
9793 system_logger:
9795 Returns the current system_logger as set by erlang:sys‐
9796 tem_flag(system_logger, _).
9797 system_version:
9799 Returns a string containing version number and some impor‐
9800 tant properties, such as the number of schedulers.
9801 trace_control_word:
9803 Returns the value of the node trace control word. For more
9804 information, see function get_tcw in section Match Specifi‐
9805 cations in Erlang in the User's Guide.
9806 version:
9808 Returns a string containing the version number of the emula‐
9809 tor.
9810 wordsize:
9812 Same as {wordsize, internal}.
9813 {wordsize, internal}:
9815 Returns the size of Erlang term words in bytes as an inte‐
9816 ger, that is, 4 is returned on a 32-bit architecture, and 8
9817 is returned on a 64-bit architecture.
9818 {wordsize, external}:
9820 Returns the true word size of the emulator, that is, the
9821 size of a pointer. The value is given in bytes as an inte‐
9822 ger. On a pure 32-bit architecture, 4 is returned. On a
9823 64-bit architecture, 8 is returned.
9824 erlang:system_monitor() -> MonSettings
9826 Types:
9828 MonSettings = undefined | {MonitorPid, Options}
9830 MonitorPid = pid()
9831 Options = [system_monitor_option()]
9832 system_monitor_option() =
9833 busy_port | busy_dist_port |
9834 {long_gc, integer() >= 0} |
9835 {long_schedule, integer() >= 0} |
9836 {large_heap, integer() >= 0}
9837 Returns the current system monitoring settings set by er‐
9839 lang:system_monitor/2 as {MonitorPid, Options}, or undefined if
9840 no settings exist. The order of the options can be different
9841 from the one that was set.
9842 erlang:system_monitor(Arg) -> MonSettings
9844 Types:
9846 Arg = MonSettings = undefined | {MonitorPid, Options}
9848 MonitorPid = pid()
9849 Options = [system_monitor_option()]
9850 system_monitor_option() =
9851 busy_port | busy_dist_port |
9852 {long_gc, integer() >= 0} |
9853 {long_schedule, integer() >= 0} |
9854 {large_heap, integer() >= 0}
9855 When called with argument undefined, all system performance mon‐
9857 itoring settings are cleared.
9858 Calling the function with {MonitorPid, Options} as argument is
9860 the same as calling erlang:system_monitor(MonitorPid, Options).
9861 Returns the previous system monitor settings just like er‐
9863 lang:system_monitor/0.
9864 erlang:system_monitor(MonitorPid, Options) -> MonSettings
9866 Types:
9868 MonitorPid = pid()
9870 Options = [system_monitor_option()]
9871 MonSettings = undefined | {OldMonitorPid, OldOptions}
9872 OldMonitorPid = pid()
9873 OldOptions = [system_monitor_option()]
9874 system_monitor_option() =
9875 busy_port | busy_dist_port |
9876 {long_gc, integer() >= 0} |
9877 {long_schedule, integer() >= 0} |
9878 {large_heap, integer() >= 0}
9879 Sets the system performance monitoring options. MonitorPid is a
9881 local process identifier (pid) receiving system monitor mes‐
9882 sages. The second argument is a list of monitoring options:
9883 {long_gc, Time}:
9885 If a garbage collection in the system takes at least Time
9886 wall clock milliseconds, a message {monitor, GcPid, long_gc,
9887 Info} is sent to MonitorPid. GcPid is the pid that was
9888 garbage collected. Info is a list of two-element tuples de‐
9889 scribing the result of the garbage collection.
9890 One of the tuples is {timeout, GcTime}, where GcTime is the
9892 time for the garbage collection in milliseconds. The other
9893 tuples are tagged with heap_size, heap_block_size,
9894 stack_size, mbuf_size, old_heap_size, and
9895 old_heap_block_size. These tuples are explained in the de‐
9896 scription of trace message gc_minor_start (see er‐
9897 lang:trace/3). New tuples can be added, and the order of the
9898 tuples in the Info list can be changed at any time without
9899 prior notice.
9900 {long_schedule, Time}:
9902 If a process or port in the system runs uninterrupted for at
9903 least Time wall clock milliseconds, a message {monitor, Pi‐
9904 dOrPort, long_schedule, Info} is sent to MonitorPid. PidOr‐
9905 Port is the process or port that was running. Info is a list
9906 of two-element tuples describing the event.
9907 If a pid(), the tuples {timeout, Millis}, {in, Location},
9909 and {out, Location} are present, where Location is either an
9910 MFA ({Module, Function, Arity}) describing the function
9911 where the process was scheduled in/out, or the atom unde‐
9912 fined.
9913 If a port(), the tuples {timeout, Millis} and {port_op,Op}
9915 are present. Op is one of proc_sig, timeout, input, output,
9916 event, or dist_cmd, depending on which driver callback was
9917 executing.
9918 proc_sig is an internal operation and is never to appear,
9920 while the others represent the corresponding driver call‐
9921 backs timeout, ready_input, ready_output, event, and outputv
9922 (when the port is used by distribution). Value Millis in tu‐
9923 ple timeout informs about the uninterrupted execution time
9924 of the process or port, which always is equal to or higher
9925 than the Time value supplied when starting the trace. New
9926 tuples can be added to the Info list in a future release.
9927 The order of the tuples in the list can be changed at any
9928 time without prior notice.
9929 This can be used to detect problems with NIFs or drivers
9931 that take too long to execute. 1 ms is considered a good
9932 maximum time for a driver callback or a NIF. However, a
9933 time-sharing system is usually to consider everything < 100
9934 ms as "possible" and fairly "normal". However, longer sched‐
9935 ule times can indicate swapping or a misbehaving NIF/driver.
9936 Misbehaving NIFs and drivers can cause bad resource utiliza‐
9937 tion and bad overall system performance.
9938 {large_heap, Size}:
9940 If a garbage collection in the system results in the allo‐
9941 cated size of a heap being at least Size words, a message
9942 {monitor, GcPid, large_heap, Info} is sent to MonitorPid.
9943 GcPid and Info are the same as for long_gc earlier, except
9944 that the tuple tagged with timeout is not present.
9945 The monitor message is sent if the sum of the sizes of all
9947 memory blocks allocated for all heap generations after a
9948 garbage collection is equal to or higher than Size.
9949 When a process is killed by max_heap_size, it is killed be‐
9951 fore the garbage collection is complete and thus no large
9952 heap message is sent.
9953 busy_port:
9955 If a process in the system gets suspended because it sends
9956 to a busy port, a message {monitor, SusPid, busy_port, Port}
9957 is sent to MonitorPid. SusPid is the pid that got suspended
9958 when sending to Port.
9959 busy_dist_port:
9961 If a process in the system gets suspended because it sends
9962 to a process on a remote node whose inter-node communication
9963 was handled by a busy port, a message {monitor, SusPid,
9964 busy_dist_port, Port} is sent to MonitorPid. SusPid is the
9965 pid that got suspended when sending through the inter-node
9966 communication port Port.
9967 Returns the previous system monitor settings just like er‐
9969 lang:system_monitor/0.
9970 The arguments to system_monitor/2 specifies how all system moni‐
9972 toring on the node should be done, not how it should be changed.
9973 This means only one process at a time (MonitorPid) can be the
9974 receiver of system monitor messages. Also, the way to clear a
9975 specific monitor option is to not include it in the list Op‐
9976 tions. All system monitoring will, however, be cleared if the
9977 process identified by MonitorPid terminates.
9978 There are no special option values (like zero) to clear an op‐
9980 tion. Some of the options have a unspecified minimum value.
9981 Lower values will be adjusted to the minimum value. For example,
9982 it is currently not possible to monitor all garbage collections
9983 with {long_gc, 0}.
9984 Note:
9986 If a monitoring process gets so large that it itself starts to
9987 cause system monitor messages when garbage collecting, the mes‐
9988 sages enlarge the process message queue and probably make the
9989 problem worse.
9990 Keep the monitoring process neat and do not set the system moni‐
9992 tor limits too tight.
9993 Failures:
9996 badarg:
9998 If MonitorPid does not exist.
9999 badarg:
10001 If MonitorPid is not a local process.
10002 erlang:system_profile() -> ProfilerSettings
10004 Types:
10006 ProfilerSettings = undefined | {ProfilerPid, Options}
10008 ProfilerPid = pid() | port()
10009 Options = [system_profile_option()]
10010 system_profile_option() =
10011 exclusive | runnable_ports | runnable_procs | scheduler |
10012 timestamp | monotonic_timestamp | strict_monotonic_timestamp
10013 Returns the current system profiling settings set by erlang:sys‐
10015 tem_profile/2 as {ProfilerPid, Options}, or undefined if there
10016 are no settings. The order of the options can be different from
10017 the one that was set.
10018 erlang:system_profile(ProfilerPid, Options) -> ProfilerSettings
10020 Types:
10022 ProfilerPid = pid() | port() | undefined
10024 Options = [system_profile_option()]
10025 ProfilerSettings =
10026 undefined | {pid() | port(), [system_profile_option()]}
10027 system_profile_option() =
10028 exclusive | runnable_ports | runnable_procs | scheduler |
10029 timestamp | monotonic_timestamp | strict_monotonic_timestamp
10030 Sets system profiler options. ProfilerPid is a local process
10032 identifier (pid) or port receiving profiling messages. The re‐
10033 ceiver is excluded from all profiling. The second argument is a
10034 list of profiling options:
10035 exclusive:
10037 If a synchronous call to a port from a process is done, the
10038 calling process is considered not runnable during the call
10039 runtime to the port. The calling process is notified as in‐
10040 active, and later active when the port callback returns.
10041 monotonic_timestamp:
10043 Time stamps in profile messages use Erlang monotonic time.
10044 The time stamp (Ts) has the same format and value as pro‐
10045 duced by erlang:monotonic_time(nanosecond).
10046 runnable_procs:
10048 If a process is put into or removed from the run queue, a
10049 message, {profile, Pid, State, Mfa, Ts}, is sent to Profil‐
10050 erPid. Running processes that are reinserted into the run
10051 queue after having been pre-empted do not trigger this mes‐
10052 sage.
10053 runnable_ports:
10055 If a port is put into or removed from the run queue, a mes‐
10056 sage, {profile, Port, State, 0, Ts}, is sent to ProfilerPid.
10057 scheduler:
10059 If a scheduler is put to sleep or awoken, a message, {pro‐
10060 file, scheduler, Id, State, NoScheds, Ts}, is sent to Pro‐
10061 filerPid.
10062 strict_monotonic_timestamp:
10064 Time stamps in profile messages consist of Erlang monotonic
10065 time and a monotonically increasing integer. The time stamp
10066 (Ts) has the same format and value as produced by {er‐
10067 lang:monotonic_time(nanosecond), erlang:unique_inte‐
10068 ger([monotonic])}.
10069 timestamp:
10071 Time stamps in profile messages include a time stamp (Ts)
10072 that has the same form as returned by erlang:now(). This is
10073 also the default if no time stamp flag is specified. If
10074 cpu_timestamp has been enabled through erlang:trace/3, this
10075 also effects the time stamp produced in profiling messages
10076 when flag timestamp is enabled.
10077 Note:
10079 erlang:system_profile behavior can change in a future release.
10080 erlang:system_time() -> integer()
10083 Returns current Erlang system time in native time unit.
10085 Calling erlang:system_time() is equivalent to erlang:mono‐
10087 tonic_time() + erlang:time_offset().
10088 Note:
10090 This time is not a monotonically increasing time in the general
10091 case. For more information, see the documentation of time warp
10092 modes in the User's Guide.
10093 erlang:system_time(Unit) -> integer()
10096 Types:
10098 Unit = time_unit()
10100 Returns current Erlang system time converted into the Unit
10102 passed as argument.
10103 Calling erlang:system_time(Unit) is equivalent to erlang:con‐
10105 vert_time_unit(erlang:system_time(), native, Unit).
10106 Note:
10108 This time is not a monotonically increasing time in the general
10109 case. For more information, see the documentation of time warp
10110 modes in the User's Guide.
10111 term_to_binary(Term) -> ext_binary()
10114 Types:
10116 Term = term()
10118 Returns a binary data object that is the result of encoding Term
10120 according to the Erlang external term format.
10121 This can be used for various purposes, for example, writing a
10123 term to a file in an efficient way, or sending an Erlang term to
10124 some type of communications channel not supported by distributed
10125 Erlang.
10126 > Bin = term_to_binary(hello).
10128 <<131,100,0,5,104,101,108,108,111>>
10129 > hello = binary_to_term(Bin).
10130 hello
10131 See also binary_to_term/1.
10134 Note:
10136 There is no guarantee that this function will return the same
10137 encoded representation for the same term.
10138 term_to_binary(Term, Options) -> ext_binary()
10141 Types:
10143 Term = term()
10145 Options =
10146 [compressed |
10147 {compressed, Level :: 0..9} |
10148 deterministic |
10149 {minor_version, Version :: 0..2}]
10150 Returns a binary data object that is the result of encoding Term
10152 according to the Erlang external term format.
10153 If option compressed is provided, the external term format is
10155 compressed. The compressed format is automatically recognized by
10156 binary_to_term/1 as from Erlang/OTP R7B.
10157 A compression level can be specified by giving option {com‐
10159 pressed, Level}. Level is an integer with range 0..9, where:
10160 * 0 - No compression is done (it is the same as giving no com‐
10162 pressed option).
10163 * 1 - Takes least time but may not compress as well as the
10165 higher levels.
10166 * 6 - Default level when option compressed is provided.
10168 * 9 - Takes most time and tries to produce a smaller result.
10170 Notice "tries" in the preceding sentence; depending on the
10171 input term, level 9 compression either does or does not pro‐
10172 duce a smaller result than level 1 compression.
10173 Option {minor_version, Version} can be used to control some en‐
10175 coding details. This option was introduced in Erlang/OTP R11B-4.
10176 The valid values for Version are:
10177 0:
10179 Floats are encoded using a textual representation. This op‐
10180 tion is useful to ensure that releases before Erlang/OTP
10181 R11B-4 can decode resulting binary.
10182 This version encode atoms that can be represented by a
10184 latin1 string using latin1 encoding while only atoms that
10185 cannot be represented by latin1 are encoded using utf8.
10186 1:
10188 This is as of Erlang/OTP 17.0 the default. It forces any
10189 floats in the term to be encoded in a more space-efficient
10190 and exact way (namely in the 64-bit IEEE format, rather than
10191 converted to a textual representation). As from Erlang/OTP
10192 R11B-4, binary_to_term/1 can decode this representation.
10193 This version encode atoms that can be represented by a
10195 latin1 string using latin1 encoding while only atoms that
10196 cannot be represented by latin1 are encoded using utf8.
10197 2:
10199 Drops usage of the latin1 atom encoding and unconditionally
10200 use utf8 encoding for all atoms. This will be changed to the
10201 default in a future major release of Erlang/OTP. Erlang/OTP
10202 systems as of R16B can decode this representation.
10203 Option deterministic (introduced in OTP 24.1) can be used to en‐
10205 sure that within the same major release of Erlang/OTP, the same
10206 encoded representation is returned for the same term. There is
10207 still no guarantee that the encoded representation remains the
10208 same between major releases of Erlang/OTP.
10209 See also binary_to_term/1.
10211 term_to_iovec(Term) -> ext_iovec()
10213 Types:
10215 Term = term()
10217 Returns the encoding of Term according to the Erlang external
10219 term format as ext_iovec().
10220 This function produce the same encoding as term_to_binary/1, but
10222 with another return type. The call iolist_to_bi‐
10223 nary(term_to_iovec(Term)) will produce exactly the same result
10224 as the call term_to_binary(Term).
10225 term_to_iovec() is a pure optimization of the functionality
10227 term_to_binary() provide. term_to_iovec() can for example refer
10228 directly to off heap binaries instead of copying the binary data
10229 into the result.
10230 See also term_to_binary/1.
10232 term_to_iovec(Term, Options) -> ext_iovec()
10234 Types:
10236 Term = term()
10238 Options =
10239 [compressed |
10240 {compressed, Level :: 0..9} |
10241 deterministic |
10242 {minor_version, Version :: 0..2}]
10243 Returns the encoding of Term according to the Erlang external
10245 term format as ext_iovec().
10246 This function produce the same encoding as term_to_binary/2, but
10248 with another return type. The call iolist_to_bi‐
10249 nary(term_to_iovec(Term, Opts)) will produce exactly the same
10250 result as term_to_binary(Term, Opts).
10251 Currently recognised options are all options recognised by
10253 term_to_binary/2.
10254 term_to_iovec() is a pure optimization of the functionality
10256 term_to_binary() provide. term_to_iovec() can for example refer
10257 directly to off heap binaries instead of copying the binary data
10258 into the result.
10259 See also term_to_binary/2.
10261 throw(Any) -> no_return()
10263 Types:
10265 Any = term()
10267 Raises an exception of class throw. Intended to be used to do
10269 non-local returns from functions.
10270 If evaluated within a catch expression, the catch expression
10272 returns value Any. Example:
10273 > catch throw({hello, there}).
10275 {hello,there}
10276 If evaluated within a try-block of a try expression, the value
10278 Any can be caught within the catch block. Example:
10279 try
10281 throw({my_exception, "Something happened"})
10282 catch
10283 throw:{my_exception, Desc} ->
10284 io:format(standard_error, "Error: ~s~n", [Desc])
10285 end
10286 Failure: nocatch if not caught by an exception handler.
10288 See the guide about errors and error handling for additional in‐
10290 formation.
10291 time() -> Time
10293 Types:
10295 Time = calendar:time()
10297 Returns the current time as {Hour, Minute, Second}.
10299 The time zone and Daylight Saving Time correction depend on the
10301 underlying OS. The return value is based on the OS System Time.
10302 Example:
10303 > time().
10305 {9,42,44}
10306 erlang:time_offset() -> integer()
10308 Returns the current time offset between Erlang monotonic time
10310 and Erlang system time in native time unit. Current time offset
10311 added to an Erlang monotonic time gives corresponding Erlang
10312 system time.
10313 The time offset may or may not change during operation depending
10315 on the time warp mode used.
10316 Note:
10318 A change in time offset can be observed at slightly different
10319 points in time by different processes.
10320 If the runtime system is in multi-time warp mode, the time off‐
10322 set is changed when the runtime system detects that the OS sys‐
10323 tem time has changed. The runtime system will, however, not de‐
10324 tect this immediately when it occurs. A task checking the time
10325 offset is scheduled to execute at least once a minute; so, under
10326 normal operation this is to be detected within a minute, but
10327 during heavy load it can take longer time.
10328 erlang:time_offset(Unit) -> integer()
10331 Types:
10333 Unit = time_unit()
10335 Returns the current time offset between Erlang monotonic time
10337 and Erlang system time converted into the Unit passed as argu‐
10338 ment.
10339 Same as calling erlang:convert_time_unit(erlang:time_offset(),
10341 native, Unit) however optimized for commonly used Units.
10342 erlang:timestamp() -> Timestamp
10344 Types:
10346 Timestamp = timestamp()
10348 timestamp() =
10349 {MegaSecs :: integer() >= 0,
10350 Secs :: integer() >= 0,
10351 MicroSecs :: integer() >= 0}
10352 Returns current Erlang system time on the format {MegaSecs,
10354 Secs, MicroSecs}. This format is the same as os:timestamp/0 and
10355 the deprecated erlang:now/0 use. The reason for the existence of
10356 erlang:timestamp() is purely to simplify use for existing code
10357 that assumes this time stamp format. Current Erlang system time
10358 can more efficiently be retrieved in the time unit of your
10359 choice using erlang:system_time/1.
10360 The erlang:timestamp() BIF is equivalent to:
10362 timestamp() ->
10364 ErlangSystemTime = erlang:system_time(microsecond),
10365 MegaSecs = ErlangSystemTime div 1000_000_000_000,
10366 Secs = ErlangSystemTime div 1000_000 - MegaSecs*1000_000,
10367 MicroSecs = ErlangSystemTime rem 1000_000,
10368 {MegaSecs, Secs, MicroSecs}.
10369 It, however, uses a native implementation that does not build
10371 garbage on the heap and with slightly better performance.
10372 Note:
10374 This time is not a monotonically increasing time in the general
10375 case. For more information, see the documentation of time warp
10376 modes in the User's Guide.
10377 tl(List) -> term()
10380 Types:
10382 List = nonempty_maybe_improper_list()
10384 Returns the tail of List, that is, the list minus the first ele‐
10386 ment, for example:
10387 > tl([geesties, guilies, beasties]).
10389 [guilies, beasties]
10390 > tl([geesties]).
10392 []
10393 > tl([geesties, guilies, beasties | improper_end]).
10395 [guilies, beasties | improper_end]
10396 > tl([geesties | improper_end]).
10398 improper_end
10399 Allowed in guard tests.
10401 Failure: badarg if List is the empty list [].
10403 erlang:trace(PidPortSpec, How, FlagList) -> integer()
10405 Types:
10407 PidPortSpec =
10409 pid() |
10410 port() |
10411 all | processes | ports | existing | existing_processes |
10412 existing_ports | new | new_processes | new_ports
10413 How = boolean()
10414 FlagList = [trace_flag()]
10415 trace_flag() =
10416 all | send | 'receive' | procs | ports | call | arity |
10417 return_to | silent | running | exiting | running_procs |
10418 running_ports | garbage_collection | timestamp |
10419 cpu_timestamp | monotonic_timestamp |
10420 strict_monotonic_timestamp | set_on_spawn |
10421 set_on_first_spawn | set_on_link | set_on_first_link |
10422 {tracer, pid() | port()} |
10423 {tracer, module(), term()}
10424 Turns on (if How == true) or off (if How == false) the trace
10426 flags in FlagList for the process or processes represented by
10427 PidPortSpec.
10428 PidPortSpec is either a process identifier (pid) for a local
10430 process, a port identifier, or one of the following atoms:
10431 all:
10433 All currently existing processes and ports and all that will
10434 be created in the future.
10435 processes:
10437 All currently existing processes and all that will be cre‐
10438 ated in the future.
10439 ports:
10441 All currently existing ports and all that will be created in
10442 the future.
10443 existing:
10445 All currently existing processes and ports.
10446 existing_processes:
10448 All currently existing processes.
10449 existing_ports:
10451 All currently existing ports.
10452 new:
10454 All processes and ports that will be created in the future.
10455 new_processes:
10457 All processes that will be created in the future.
10458 new_ports:
10460 All ports that will be created in the future.
10461 FlagList can contain any number of the following flags (the
10463 "message tags" refers to the list of trace messages):
10464 all:
10466 Sets all trace flags except tracer and cpu_timestamp, which
10467 are in their nature different than the others.
10468 send:
10470 Traces sending of messages.
10471 Message tags: send and send_to_non_existing_process.
10473 'receive':
10475 Traces receiving of messages.
10476 Message tags: 'receive'.
10478 call:
10480 Traces certain function calls. Specify which function calls
10481 to trace by calling erlang:trace_pattern/3.
10482 Message tags: call and return_from.
10484 silent:
10486 Used with the call trace flag. The call, return_from, and
10487 return_to trace messages are inhibited if this flag is set,
10488 but they are executed as normal if there are match specifi‐
10489 cations.
10490 Silent mode is inhibited by executing erlang:trace(_, false,
10492 [silent|_]), or by a match specification executing the func‐
10493 tion {silent, false}.
10494 The silent trace flag facilitates setting up a trace on many
10496 or even all processes in the system. The trace can then be
10497 activated and deactivated using the match specification
10498 function {silent,Bool}, giving a high degree of control of
10499 which functions with which arguments that trigger the trace.
10500 Message tags: call, return_from, and return_to. Or rather,
10502 the absence of.
10503 return_to:
10505 Used with the call trace flag. Traces the return from a
10506 traced function back to its caller. Only works for functions
10507 traced with option local to erlang:trace_pattern/3.
10508 The semantics is that a trace message is sent when a call
10510 traced function returns, that is, when a chain of tail re‐
10511 cursive calls ends. Only one trace message is sent per chain
10512 of tail recursive calls, so the properties of tail recur‐
10513 siveness for function calls are kept while tracing with this
10514 flag. Using call and return_to trace together makes it pos‐
10515 sible to know exactly in which function a process executes
10516 at any time.
10517 To get trace messages containing return values from func‐
10519 tions, use the {return_trace} match specification action in‐
10520 stead.
10521 Message tags: return_to.
10523 procs:
10525 Traces process-related events.
10526 Message tags: spawn, spawned, exit, register, unregister,
10528 link, unlink, getting_linked, and getting_unlinked.
10529 ports:
10531 Traces port-related events.
10532 Message tags: open, closed, register, unregister, get‐
10534 ting_linked, and getting_unlinked.
10535 running:
10537 Traces scheduling of processes.
10538 Message tags: in and out.
10540 exiting:
10542 Traces scheduling of exiting processes.
10543 Message tags: in_exiting, out_exiting, and out_exited.
10545 running_procs:
10547 Traces scheduling of processes just like running. However,
10548 this option also includes schedule events when the process
10549 executes within the context of a port without being sched‐
10550 uled out itself.
10551 Message tags: in and out.
10553 running_ports:
10555 Traces scheduling of ports.
10556 Message tags: in and out.
10558 garbage_collection:
10560 Traces garbage collections of processes.
10561 Message tags: gc_minor_start, gc_max_heap_size, and gc_mi‐
10563 nor_end.
10564 timestamp:
10566 Includes a time stamp in all trace messages. The time stamp
10567 (Ts) has the same form as returned by erlang:now().
10568 cpu_timestamp:
10570 A global trace flag for the Erlang node that makes all trace
10571 time stamps using flag timestamp to be in CPU time, not wall
10572 clock time. That is, cpu_timestamp is not be used if mono‐
10573 tonic_timestamp or strict_monotonic_timestamp is enabled.
10574 Only allowed with PidPortSpec==all. If the host machine OS
10575 does not support high-resolution CPU time measurements,
10576 trace/3 exits with badarg. Notice that most OS do not syn‐
10577 chronize this value across cores, so be prepared that time
10578 can seem to go backwards when using this option.
10579 monotonic_timestamp:
10581 Includes an Erlang monotonic time time stamp in all trace
10582 messages. The time stamp (Ts) has the same format and value
10583 as produced by erlang:monotonic_time(nanosecond). This flag
10584 overrides flag cpu_timestamp.
10585 strict_monotonic_timestamp:
10587 Includes an time stamp consisting of Erlang monotonic time
10588 and a monotonically increasing integer in all trace mes‐
10589 sages. The time stamp (Ts) has the same format and value as
10590 produced by { erlang:monotonic_time(nanosecond), er‐
10591 lang:unique_integer([monotonic])}. This flag overrides flag
10592 cpu_timestamp.
10593 arity:
10595 Used with the call trace flag. {M, F, Arity} is specified
10596 instead of {M, F, Args} in call trace messages.
10597 set_on_spawn:
10599 Makes any process created by a traced process inherit its
10600 trace flags, including flag set_on_spawn.
10601 set_on_first_spawn:
10603 Makes the first process created by a traced process inherit
10604 its trace flags, excluding flag set_on_first_spawn.
10605 set_on_link:
10607 Makes any process linked by a traced process inherit its
10608 trace flags, including flag set_on_link.
10609 set_on_first_link:
10611 Makes the first process linked to by a traced process in‐
10612 herit its trace flags, excluding flag set_on_first_link.
10613 {tracer, Tracer}:
10615 Specifies where to send the trace messages. Tracer must be
10616 the process identifier of a local process or the port iden‐
10617 tifier of a local port.
10618 {tracer, TracerModule, TracerState}:
10620 Specifies that a tracer module is to be called instead of
10621 sending a trace message. The tracer module can then ignore
10622 or change the trace message. For more details on how to
10623 write a tracer module, see erl_tracer(3).
10624 If no tracer is specified, the calling process receives all the
10626 trace messages.
10627 The effect of combining set_on_first_link with set_on_link is
10629 the same as set_on_first_link alone. Likewise for set_on_spawn
10630 and set_on_first_spawn.
10631 The tracing process receives the trace messages described in the
10633 following list. Pid is the process identifier of the traced
10634 process in which the traced event has occurred. The third tuple
10635 element is the message tag.
10636 If flag timestamp, strict_monotonic_timestamp, or mono‐
10638 tonic_timestamp is specified, the first tuple element is
10639 trace_ts instead, and the time stamp is added as an extra ele‐
10640 ment last in the message tuple. If multiple time stamp flags are
10641 passed, timestamp has precedence over strict_monotonic_time‐
10642 stamp, which in turn has precedence over monotonic_timestamp.
10643 All time stamp flags are remembered, so if two are passed and
10644 the one with highest precedence later is disabled, the other one
10645 becomes active.
10646 If a match specification (applicable only for call, send and
10648 'receive' tracing) contains a {message} action function with a
10649 non-boolean value, that value is added as an extra element to
10650 the message tuple either in the last position or before the
10651 timestamp (if it is present).
10652 Trace messages:
10654 {trace, PidPort, send, Msg, To}:
10656 When PidPort sends message Msg to process To.
10657 {trace, PidPort, send_to_non_existing_process, Msg, To}:
10659 When PidPort sends message Msg to the non-existing process
10660 To.
10661 {trace, PidPort, 'receive', Msg}:
10663 When PidPort receives message Msg. If Msg is set to time-
10664 out, a receive statement can have timed out, or the process
10665 received a message with the payload timeout.
10666 {trace, Pid, call, {M, F, Args}}:
10668 When Pid calls a traced function. The return values of calls
10669 are never supplied, only the call and its arguments.
10670 Trace flag arity can be used to change the contents of this
10672 message, so that Arity is specified instead of Args.
10673 {trace, Pid, return_to, {M, F, Arity}}:
10675 When Pid returns to the specified function. This trace mes‐
10676 sage is sent if both the flags call and return_to are set,
10677 and the function is set to be traced on local function
10678 calls. The message is only sent when returning from a chain
10679 of tail recursive function calls, where at least one call
10680 generated a call trace message (that is, the functions match
10681 specification matched, and {message, false} was not an ac‐
10682 tion).
10683 {trace, Pid, return_from, {M, F, Arity}, ReturnValue}:
10685 When Pid returns from the specified function. This trace
10686 message is sent if flag call is set, and the function has a
10687 match specification with a return_trace or exception_trace
10688 action.
10689 {trace, Pid, exception_from, {M, F, Arity}, {Class, Value}}:
10691 When Pid exits from the specified function because of an ex‐
10692 ception. This trace message is sent if flag call is set, and
10693 the function has a match specification with an excep‐
10694 tion_trace action.
10695 {trace, Pid, spawn, Pid2, {M, F, Args}}:
10697 When Pid spawns a new process Pid2 with the specified func‐
10698 tion call as entry point.
10699 Args is supposed to be the argument list, but can be any
10701 term if the spawn is erroneous.
10702 {trace, Pid, spawned, Pid2, {M, F, Args}}:
10704 When Pid is spawned by process Pid2 with the specified func‐
10705 tion call as entry point.
10706 Args is supposed to be the argument list, but can be any
10708 term if the spawn is erroneous.
10709 {trace, Pid, exit, Reason}:
10711 When Pid exits with reason Reason.
10712 {trace, PidPort, register, RegName}:
10714 When PidPort gets the name RegName registered.
10715 {trace, PidPort, unregister, RegName}:
10717 When PidPort gets the name RegName unregistered. This is
10718 done automatically when a registered process or port exits.
10719 {trace, Pid, link, Pid2}:
10721 When Pid links to a process Pid2.
10722 {trace, Pid, unlink, Pid2}:
10724 When Pid removes the link from a process Pid2.
10725 {trace, PidPort, getting_linked, Pid2}:
10727 When PidPort gets linked to a process Pid2.
10728 {trace, PidPort, getting_unlinked, Pid2}:
10730 When PidPort gets unlinked from a process Pid2.
10731 {trace, Port, open, Pid, Driver}:
10733 When Pid opens a new port Port with the running Driver.
10734 Driver is the name of the driver as an atom.
10736 {trace, Port, closed, Reason}:
10738 When Port closes with Reason.
10739 {trace, Pid, in | in_exiting, {M, F, Arity} | 0}:
10741 When Pid is scheduled to run. The process runs in function
10742 {M, F, Arity}. On some rare occasions, the current function
10743 cannot be determined, then the last element is 0.
10744 {trace, Pid, out | out_exiting | out_exited, {M, F, Arity} |
10746 0}:
10747 When Pid is scheduled out. The process was running in func‐
10748 tion {M, F, Arity}. On some rare occasions, the current
10749 function cannot be determined, then the last element is 0.
10750 {trace, Port, in, Command | 0}:
10752 When Port is scheduled to run. Command is the first thing
10753 the port will execute, it can however run several commands
10754 before being scheduled out. On some rare occasions, the cur‐
10755 rent function cannot be determined, then the last element is
10756 0.
10757 The possible commands are call, close, command, connect,
10759 control, flush, info, link, open, and unlink.
10760 {trace, Port, out, Command | 0}:
10762 When Port is scheduled out. The last command run was Com‐
10763 mand. On some rare occasions, the current function cannot be
10764 determined, then the last element is 0. Command can contain
10765 the same commands as in
10766 {trace, Pid, gc_minor_start, Info}:
10768 Sent when a young garbage collection is about to be started.
10771 Info is a list of two-element tuples, where the first ele‐
10772 ment is a key, and the second is the value. Do not depend on
10773 any order of the tuples. The following keys are defined:
10774 heap_size:
10776 The size of the used part of the heap.
10777 heap_block_size:
10779 The size of the memory block used for storing the heap and
10780 the stack.
10781 old_heap_size:
10783 The size of the used part of the old heap.
10784 old_heap_block_size:
10786 The size of the memory block used for storing the old
10787 heap.
10788 stack_size:
10790 The size of the stack.
10791 recent_size:
10793 The size of the data that survived the previous garbage
10794 collection.
10795 mbuf_size:
10797 The combined size of message buffers associated with the
10798 process.
10799 bin_vheap_size:
10801 The total size of unique off-heap binaries referenced from
10802 the process heap.
10803 bin_vheap_block_size:
10805 The total size of binaries allowed in the virtual heap in
10806 the process before doing a garbage collection.
10807 bin_old_vheap_size:
10809 The total size of unique off-heap binaries referenced from
10810 the process old heap.
10811 bin_old_vheap_block_size:
10813 The total size of binaries allowed in the virtual old heap
10814 in the process before doing a garbage collection.
10815 wordsize:
10817 For the gc_minor_start event it is the size of the need
10818 that triggered the GC. For the corresponding gc_minor_end
10819 event it is the size of reclaimed memory = start heap_size
10820 - end heap_size.
10821 All sizes are in words.
10823 {trace, Pid, gc_max_heap_size, Info}:
10825 Sent when the max_heap_size is reached during garbage col‐
10826 lection. Info contains the same kind of list as in message
10827 gc_start, but the sizes reflect the sizes that triggered
10828 max_heap_size to be reached.
10829 {trace, Pid, gc_minor_end, Info}:
10831 Sent when young garbage collection is finished. Info con‐
10832 tains the same kind of list as in message gc_minor_start,
10833 but the sizes reflect the new sizes after garbage collec‐
10834 tion.
10835 {trace, Pid, gc_major_start, Info}:
10837 Sent when fullsweep garbage collection is about to be
10838 started. Info contains the same kind of list as in message
10839 gc_minor_start.
10840 {trace, Pid, gc_major_end, Info}:
10842 Sent when fullsweep garbage collection is finished. Info
10843 contains the same kind of list as in message gc_minor_start,
10844 but the sizes reflect the new sizes after a fullsweep
10845 garbage collection.
10846 If the tracing process/port dies or the tracer module returns
10848 remove, the flags are silently removed.
10849 Each process can only be traced by one tracer. Therefore, at‐
10851 tempts to trace an already traced process fail.
10852 Returns a number indicating the number of processes that matched
10854 PidPortSpec. If PidPortSpec is a process identifier, the return
10855 value is 1. If PidPortSpec is all or existing, the return value
10856 is the number of processes running. If PidPortSpec is new, the
10857 return value is 0.
10858 Failure: badarg if the specified arguments are not supported.
10860 For example, cpu_timestamp is not supported on all platforms.
10861 erlang:trace_delivered(Tracee) -> Ref
10863 Types:
10865 Tracee = pid() | all
10867 Ref = reference()
10868 The delivery of trace messages (generated by erlang:trace/3,
10870 seq_trace(3), or erlang:system_profile/2) is dislocated on the
10871 time-line compared to other events in the system. If you know
10872 that Tracee has passed some specific point in its execution, and
10873 you want to know when at least all trace messages corresponding
10874 to events up to this point have reached the tracer, use er‐
10875 lang:trace_delivered(Tracee).
10876 When it is guaranteed that all trace messages are delivered to
10878 the tracer up to the point that Tracee reached at the time of
10879 the call to erlang:trace_delivered(Tracee), then a {trace_deliv‐
10880 ered, Tracee, Ref} message is sent to the caller of er‐
10881 lang:trace_delivered(Tracee) .
10882 Notice that message trace_delivered does not imply that trace
10884 messages have been delivered. Instead it implies that all trace
10885 messages that are to be delivered have been delivered. It is not
10886 an error if Tracee is not, and has not been traced by someone,
10887 but if this is the case, no trace messages have been delivered
10888 when the trace_delivered message arrives.
10889 Notice that Tracee must refer to a process currently or previ‐
10891 ously existing on the same node as the caller of er‐
10892 lang:trace_delivered(Tracee) resides on. The special Tracee atom
10893 all denotes all processes that currently are traced in the node.
10894 When used together with a Tracer Module, any message sent in
10896 the trace callback is guaranteed to have reached its recipient
10897 before the trace_delivered message is sent.
10898 Example: Process A is Tracee, port B is tracer, and process C is
10900 the port owner of B. C wants to close B when A exits. To ensure
10901 that the trace is not truncated, C can call erlang:trace_deliv‐
10902 ered(A) when A exits, and wait for message {trace_delivered, A,
10903 Ref} before closing B.
10904 Failure: badarg if Tracee does not refer to a process (dead or
10906 alive) on the same node as the caller of erlang:trace_deliv‐
10907 ered(Tracee) resides on.
10908 erlang:trace_info(PidPortFuncEvent, Item) -> Res
10910 Types:
10912 PidPortFuncEvent =
10914 pid() |
10915 port() |
10916 new | new_processes | new_ports |
10917 {Module, Function, Arity} |
10918 on_load | send | 'receive'
10919 Module = module()
10920 Function = atom()
10921 Arity = arity()
10922 Item =
10923 flags | tracer | traced | match_spec | meta |
10924 meta_match_spec | call_count | call_time | all
10925 Res = trace_info_return()
10926 trace_info_return() =
10927 undefined |
10928 {flags, [trace_info_flag()]} |
10929 {tracer, pid() | port() | []} |
10930 {tracer, module(), term()} |
10931 trace_info_item_result() |
10932 {all, [trace_info_item_result()] | false | undefined}
10933 trace_info_item_result() =
10934 {traced, global | local | false | undefined} |
10935 {match_spec, trace_match_spec() | false | undefined} |
10936 {meta, pid() | port() | false | undefined | []} |
10937 {meta, module(), term()} |
10938 {meta_match_spec, trace_match_spec() | false | undefined} |
10939 {call_count, integer() >= 0 | boolean() | undefined} |
10940 {call_time,
10941 [{pid(),
10942 integer() >= 0,
10943 integer() >= 0,
10944 integer() >= 0}] |
10945 boolean() |
10946 undefined}
10947 trace_info_flag() =
10948 send | 'receive' | set_on_spawn | call | return_to | procs |
10949 set_on_first_spawn | set_on_link | running |
10950 garbage_collection | timestamp | monotonic_timestamp |
10951 strict_monotonic_timestamp | arity
10952 trace_match_spec() =
10953 [{[term()] | '_' | match_variable(), [term()], [term()]}]
10954 match_variable() = atom()
10955 Approximation of '$1' | '$2' | '$3' | ...
10956 Returns trace information about a port, process, function, or
10958 event.
10959 To get information about a port or process, PidPortFuncEvent is
10961 to be a process identifier (pid), port identifier, or one of the
10962 atoms new, new_processes, or new_ports. The atom new or new_pro‐
10963 cesses means that the default trace state for processes to be
10964 created is returned. The atom new_ports means that the default
10965 trace state for ports to be created is returned.
10966 Valid Items for ports and processes:
10968 flags:
10970 Returns a list of atoms indicating what kind of traces is
10971 enabled for the process. The list is empty if no traces are
10972 enabled, and one or more of the followings atoms if traces
10973 are enabled: send, 'receive', set_on_spawn, call, return_to,
10974 procs, ports, set_on_first_spawn, set_on_link, running, run‐
10975 ning_procs, running_ports, silent, exiting, monotonic_time‐
10976 stamp, strict_monotonic_timestamp, garbage_collection, time‐
10977 stamp, and arity. The order is arbitrary.
10978 tracer:
10980 Returns the identifier for process, port, or a tuple con‐
10981 taining the tracer module and tracer state tracing this
10982 process. If this process is not traced, the return value is
10983 [].
10984 To get information about a function, PidPortFuncEvent is to be
10986 the three-element tuple {Module, Function, Arity} or the atom
10987 on_load. No wildcards are allowed. Returns undefined if the
10988 function does not exist, or false if the function is not traced.
10989 If PidPortFuncEvent is on_load, the information returned refers
10990 to the default value for code that will be loaded.
10991 Valid Items for functions:
10993 traced:
10995 Returns global if this function is traced on global function
10996 calls, local if this function is traced on local function
10997 calls (that is, local and global function calls), and false
10998 if local or global function calls are not traced.
10999 match_spec:
11001 Returns the match specification for this function, if it has
11002 one. If the function is locally or globally traced but has
11003 no match specification defined, the returned value is [].
11004 meta:
11006 Returns the meta-trace tracer process, port, or trace module
11007 for this function, if it has one. If the function is not
11008 meta-traced, the returned value is false. If the function is
11009 meta-traced but has once detected that the tracer process is
11010 invalid, the returned value is [].
11011 meta_match_spec:
11013 Returns the meta-trace match specification for this func‐
11014 tion, if it has one. If the function is meta-traced but has
11015 no match specification defined, the returned value is [].
11016 call_count:
11018 Returns the call count value for this function or true for
11019 the pseudo function on_load if call count tracing is active.
11020 Otherwise false is returned.
11021 See also erlang:trace_pattern/3.
11023 call_time:
11025 Returns the call time values for this function or true for
11026 the pseudo function on_load if call time tracing is active.
11027 Otherwise false is returned. The call time values returned,
11028 [{Pid, Count, S, Us}], is a list of each process that exe‐
11029 cuted the function and its specific counters.
11030 See also erlang:trace_pattern/3.
11032 all:
11034 Returns a list containing the {Item, Value} tuples for all
11035 other items, or returns false if no tracing is active for
11036 this function.
11037 To get information about an event, PidPortFuncEvent is to be one
11039 of the atoms send or 'receive'.
11040 One valid Item for events exists:
11042 match_spec:
11044 Returns the match specification for this event, if it has
11045 one, or true if no match specification has been set.
11046 The return value is {Item, Value}, where Value is the requested
11048 information as described earlier. If a pid for a dead process
11049 was specified, or the name of a non-existing function, Value is
11050 undefined.
11051 erlang:trace_pattern(MFA, MatchSpec) -> integer() >= 0
11053 Types:
11055 MFA = trace_pattern_mfa() | send | 'receive'
11057 MatchSpec =
11058 (MatchSpecList :: trace_match_spec()) |
11059 boolean() |
11060 restart | pause
11061 trace_pattern_mfa() = {atom(), atom(), arity() | '_'} | on_load
11062 trace_match_spec() =
11063 [{[term()] | '_' | match_variable(), [term()], [term()]}]
11064 match_variable() = atom()
11065 Approximation of '$1' | '$2' | '$3' | ...
11066 The same as erlang:trace_pattern(Event, MatchSpec, []), retained
11068 for backward compatibility.
11069 erlang:trace_pattern(MFA :: send, MatchSpec, FlagList :: []) ->
11071 integer() >= 0
11072 Types:
11074 MatchSpec = (MatchSpecList :: trace_match_spec()) | boolean()
11076 trace_match_spec() =
11077 [{[term()] | '_' | match_variable(), [term()], [term()]}]
11078 match_variable() = atom()
11079 Approximation of '$1' | '$2' | '$3' | ...
11080 Sets trace pattern for message sending. Must be combined with
11082 erlang:trace/3 to set the send trace flag for one or more pro‐
11083 cesses. By default all messages sent from send traced processes
11084 are traced. To limit traced send events based on the message
11085 content, the sender and/or the receiver, use erlang:trace_pat‐
11086 tern/3.
11087 Argument MatchSpec can take the following forms:
11089 MatchSpecList:
11091 A list of match specifications. The matching is done on the
11092 list [Receiver, Msg]. Receiver is the process or port iden‐
11093 tity of the receiver and Msg is the message term. The pid of
11094 the sending process can be accessed with the guard function
11095 self/0. An empty list is the same as true. For more informa‐
11096 tion, see section Match Specifications in Erlang in the
11097 User's Guide.
11098 true:
11100 Enables tracing for all sent messages (from send traced pro‐
11101 cesses). Any match specification is removed. This is the de‐
11102 fault.
11103 false:
11105 Disables tracing for all sent messages. Any match specifica‐
11106 tion is removed.
11107 Argument FlagList must be [] for send tracing.
11109 The return value is always 1.
11111 Examples:
11113 Only trace messages to a specific process Pid:
11115 > erlang:trace_pattern(send, [{[Pid, '_'],[],[]}], []).
11117 1
11118 Only trace messages matching {reply, _}:
11120 > erlang:trace_pattern(send, [{['_', {reply,'_'}],[],[]}], []).
11122 1
11123 Only trace messages sent to the sender itself:
11125 > erlang:trace_pattern(send, [{['$1', '_'],[{'=:=','$1',{self}}],[]}], []).
11127 1
11128 Only trace messages sent to other nodes:
11130 > erlang:trace_pattern(send, [{['$1', '_'],[{'=/=',{node,'$1'},{node}}],[]}], []).
11132 1
11133 Note:
11135 A match specification for send trace can use all guard and body
11136 functions except caller.
11137 Fails by raising an error exception with an error reason of:
11140 badarg:
11142 If an argument is invalid.
11143 system_limit:
11145 If a match specification passed as argument has excessive
11146 nesting which causes scheduler stack exhaustion for the
11147 scheduler that the calling process is executing on. Sched‐
11148 uler stack size can be configured when starting the runtime
11149 system.
11150 erlang:trace_pattern(MFA :: 'receive', MatchSpec, FlagList :: []) ->
11152 integer() >= 0
11153 Types:
11155 MatchSpec = (MatchSpecList :: trace_match_spec()) | boolean()
11157 trace_match_spec() =
11158 [{[term()] | '_' | match_variable(), [term()], [term()]}]
11159 match_variable() = atom()
11160 Approximation of '$1' | '$2' | '$3' | ...
11161 Sets trace pattern for message receiving. Must be combined with
11163 erlang:trace/3 to set the 'receive' trace flag for one or more
11164 processes. By default all messages received by 'receive' traced
11165 processes are traced. To limit traced receive events based on
11166 the message content, the sender and/or the receiver, use er‐
11167 lang:trace_pattern/3.
11168 Argument MatchSpec can take the following forms:
11170 MatchSpecList:
11172 A list of match specifications. The matching is done on the
11173 list [Node, Sender, Msg]. Node is the node name of the
11174 sender. Sender is the process or port identity of the
11175 sender, or the atom undefined if the sender is not known
11176 (which can be the case for remote senders). Msg is the mes‐
11177 sage term. The pid of the receiving process can be accessed
11178 with the guard function self/0. An empty list is the same as
11179 true. For more information, see section Match Specifica‐
11180 tions in Erlang in the User's Guide.
11181 true:
11183 Enables tracing for all received messages (to 'receive'
11184 traced processes). Any match specification is removed. This
11185 is the default.
11186 false:
11188 Disables tracing for all received messages. Any match speci‐
11189 fication is removed.
11190 Argument FlagList must be [] for receive tracing.
11192 The return value is always 1.
11194 Examples:
11196 Only trace messages from a specific process Pid:
11198 > erlang:trace_pattern('receive', [{['_',Pid, '_'],[],[]}], []).
11200 1
11201 Only trace messages matching {reply, _}:
11203 > erlang:trace_pattern('receive', [{['_','_', {reply,'_'}],[],[]}], []).
11205 1
11206 Only trace messages from other nodes:
11208 > erlang:trace_pattern('receive', [{['$1', '_', '_'],[{'=/=','$1',{node}}],[]}], []).
11210 1
11211 Note:
11213 A match specification for 'receive' trace can use all guard and
11214 body functions except caller, is_seq_trace, get_seq_token,
11215 set_seq_token, enable_trace, disable_trace, trace, silent, and
11216 process_dump.
11217 Fails by raising an error exception with an error reason of:
11220 badarg:
11222 If an argument is invalid.
11223 system_limit:
11225 If a match specification passed as argument has excessive
11226 nesting which causes scheduler stack exhaustion for the
11227 scheduler that the calling process is executing on. Sched‐
11228 uler stack size can be configured when starting the runtime
11229 system.
11230 erlang:trace_pattern(MFA, MatchSpec, FlagList) ->
11232 integer() >= 0
11233 Types:
11235 MFA = trace_pattern_mfa()
11237 MatchSpec =
11238 (MatchSpecList :: trace_match_spec()) |
11239 boolean() |
11240 restart | pause
11241 FlagList = [trace_pattern_flag()]
11242 trace_pattern_mfa() = {atom(), atom(), arity() | '_'} | on_load
11243 trace_match_spec() =
11244 [{[term()] | '_' | match_variable(), [term()], [term()]}]
11245 trace_pattern_flag() =
11246 global | local | meta |
11247 {meta, Pid :: pid()} |
11248 {meta, TracerModule :: module(), TracerState :: term()} |
11249 call_count | call_time
11250 match_variable() = atom()
11251 Approximation of '$1' | '$2' | '$3' | ...
11252 Enables or disables call tracing for one or more functions. Must
11254 be combined with erlang:trace/3 to set the call trace flag for
11255 one or more processes.
11256 Conceptually, call tracing works as follows. Inside the Erlang
11258 virtual machine, a set of processes and a set of functions are
11259 to be traced. If a traced process calls a traced function, the
11260 trace action is taken. Otherwise, nothing happens.
11261 To add or remove one or more processes to the set of traced pro‐
11263 cesses, use erlang:trace/3.
11264 To add or remove functions to the set of traced functions, use
11266 erlang:trace_pattern/3.
11267 The BIF erlang:trace_pattern/3 can also add match specifications
11269 to a function. A match specification comprises a pattern that
11270 the function arguments must match, a guard expression that must
11271 evaluate to true, and an action to be performed. The default ac‐
11272 tion is to send a trace message. If the pattern does not match
11273 or the guard fails, the action is not executed.
11274 Argument MFA is to be a tuple, such as {Module, Function, Ar‐
11276 ity}, or the atom on_load (described below). It can be the mod‐
11277 ule, function, and arity for a function (or a BIF in any mod‐
11278 ule). The atom '_' can be used as a wildcard in any of the fol‐
11279 lowing ways:
11280 {Module,Function,'_'}:
11282 All functions of any arity named Function in module Module.
11283 {Module,'_','_'}:
11285 All functions in module Module.
11286 {'_','_','_'}:
11288 All functions in all loaded modules.
11289 Other combinations, such as {Module,'_',Arity}, are not allowed.
11291 Local functions match wildcards only if option local is in
11292 FlagList.
11293 If argument MFA is the atom on_load, the match specification and
11295 flag list are used on all modules that are newly loaded.
11296 Argument MatchSpec can take the following forms:
11298 false:
11300 Disables tracing for the matching functions. Any match spec‐
11301 ification is removed.
11302 true:
11304 Enables tracing for the matching functions. Any match speci‐
11305 fication is removed.
11306 MatchSpecList:
11308 A list of match specifications. An empty list is equivalent
11309 to true. For a description of match specifications, see sec‐
11310 tion Match Specifications in Erlang in the User's Guide.
11311 restart:
11313 For the FlagList options call_count and call_time: restarts
11314 the existing counters. The behavior is undefined for other
11315 FlagList options.
11316 pause:
11318 For the FlagList options call_count and call_time: pauses
11319 the existing counters. The behavior is undefined for other
11320 FlagList options.
11321 Parameter FlagList is a list of options. The following are the
11323 valid options:
11324 global:
11326 Turns on or off call tracing for global function calls (that
11327 is, calls specifying the module explicitly). Only exported
11328 functions match and only global calls generate trace mes‐
11329 sages. This is the default.
11330 local:
11332 Turns on or off call tracing for all types of function
11333 calls. Trace messages are sent whenever any of the specified
11334 functions are called, regardless of how they are called. If
11335 flag return_to is set for the process, a return_to message
11336 is also sent when this function returns to its caller.
11337 meta | {meta, Pid} | {meta, TracerModule, TracerState}:
11339 Turns on or off meta-tracing for all types of function
11340 calls. Trace messages are sent to the tracer whenever any of
11341 the specified functions are called. If no tracer is speci‐
11342 fied, self() is used as a default tracer process.
11343 Meta-tracing traces all processes and does not care about
11345 the process trace flags set by erlang:trace/3, the trace
11346 flags are instead fixed to [call, timestamp].
11347 The match specification function {return_trace} works with
11349 meta-trace and sends its trace message to the same tracer.
11350 call_count:
11352 Starts (MatchSpec == true) or stops (MatchSpec == false)
11353 call count tracing for all types of function calls. For ev‐
11354 ery function, a counter is incremented when the function is
11355 called, in any process. No process trace flags need to be
11356 activated.
11357 If call count tracing is started while already running, the
11359 count is restarted from zero. To pause running counters, use
11360 MatchSpec == pause. Paused and running counters can be
11361 restarted from zero with MatchSpec == restart.
11362 To read the counter value, use erlang:trace_info/2.
11364 call_time:
11366 Starts (MatchSpec == true) or stops (MatchSpec == false)
11367 call time tracing for all types of function calls. For every
11368 function, a counter is incremented when the function is
11369 called. Time spent in the function is accumulated in two
11370 other counters, seconds and microseconds. The counters are
11371 stored for each call traced process.
11372 If call time tracing is started while already running, the
11374 count and time restart from zero. To pause running counters,
11375 use MatchSpec == pause. Paused and running counters can be
11376 restarted from zero with MatchSpec == restart.
11377 To read the counter value, use erlang:trace_info/2.
11379 The options global and local are mutually exclusive, and global
11381 is the default (if no options are specified). The options
11382 call_count and meta perform a kind of local tracing, and cannot
11383 be combined with global. A function can be globally or locally
11384 traced. If global tracing is specified for a set of functions,
11385 then local, meta, call time, and call count tracing for the
11386 matching set of local functions is disabled, and conversely.
11387 When disabling trace, the option must match the type of trace
11389 set on the function. That is, local tracing must be disabled
11390 with option local and global tracing with option global (or no
11391 option), and so on.
11392 Part of a match specification list cannot be changed directly.
11394 If a function has a match specification, it can be replaced with
11395 a new one. To change an existing match specification, use the
11396 BIF erlang:trace_info/2 to retrieve the existing match specifi‐
11397 cation.
11398 Returns the number of functions matching argument MFA. This is
11400 zero if none matched.
11401 Fails by raising an error exception with an error reason of:
11403 badarg:
11405 If an argument is invalid.
11406 system_limit:
11408 If a match specification passed as argument has excessive
11409 nesting which causes scheduler stack exhaustion for the
11410 scheduler that the calling process is executing on. Sched‐
11411 uler stack size can be configured when starting the runtime
11412 system.
11413 trunc(Number) -> integer()
11415 Types:
11417 Number = number()
11419 Truncates the decimals of Number, for example:
11421 > trunc(5.7).
11423 5
11424 > trunc(-5.7).
11426 -5
11427 > trunc(5).
11429 5
11430 > trunc(36028797018963969.0).
11432 36028797018963968
11433 In the last example, trunc(36028797018963969.0) evaluates to
11435 36028797018963968. The reason for this is that the number
11436 36028797018963969.0 cannot be represented exactly as a float
11437 value. Instead, the float literal is represented as
11438 36028797018963968.0, which is the closest number that can be
11439 represented exactly as a float value. See Representation of
11440 Floating Point Numbers for additional information.
11441 Allowed in guard tests.
11443 tuple_size(Tuple) -> integer() >= 0
11445 Types:
11447 Tuple = tuple()
11449 Returns an integer that is the number of elements in Tuple, for
11451 example:
11452 > tuple_size({morni, mulle, bwange}).
11454 3
11455 Allowed in guard tests.
11457 tuple_to_list(Tuple) -> [term()]
11459 Types:
11461 Tuple = tuple()
11463 Returns a list corresponding to Tuple. Tuple can contain any Er‐
11465 lang terms. Example:
11466 > tuple_to_list({share, {'Ericsson_B', 163}}).
11468 [share,{'Ericsson_B',163}]
11469 unalias(Alias) -> boolean()
11471 Types:
11473 Alias = reference()
11475 Deactivate the alias Alias previously created by the calling
11477 process. An alias can for example be created via alias/0, or
11478 monitor/3. unalias/1 will always deactivate the alias regardless
11479 of options used when creating the alias.
11480 Returns true if Alias was a currently active alias for current
11482 processes; otherwise, false.
11483 For more information on process aliases see the Process Aliases
11485 section of the Erlang Reference Manual .
11486 erlang:unique_integer() -> integer()
11488 Generates and returns an integer unique on current runtime sys‐
11490 tem instance. The same as calling erlang:unique_integer([]).
11491 erlang:unique_integer(ModifierList) -> integer()
11493 Types:
11495 ModifierList = [Modifier]
11497 Modifier = positive | monotonic
11498 Generates and returns an integer unique on current runtime sys‐
11500 tem instance. The integer is unique in the sense that this BIF,
11501 using the same set of modifiers, does not return the same inte‐
11502 ger more than once on the current runtime system instance. Each
11503 integer value can of course be constructed by other means.
11504 By default, when [] is passed as ModifierList, both negative and
11506 positive integers can be returned. This to use the range of in‐
11507 tegers that do not need heap memory allocation as much as possi‐
11508 ble. By default the returned integers are also only guaranteed
11509 to be unique, that is, any returned integer can be smaller or
11510 larger than previously returned integers.
11511 Modifiers:
11513 positive:
11515 Returns only positive integers.
11516 Notice that by passing the positive modifier you will get
11518 heap allocated integers (bignums) quicker.
11519 monotonic:
11521 Returns strictly monotonically increasing integers corre‐
11522 sponding to creation time. That is, the integer returned is
11523 always larger than previously returned integers on the cur‐
11524 rent runtime system instance.
11525 These values can be used to determine order between events
11527 on the runtime system instance. That is, if both X = er‐
11528 lang:unique_integer([monotonic]) and Y = erlang:unique_inte‐
11529 ger([monotonic]) are executed by different processes (or the
11530 same process) on the same runtime system instance and X < Y,
11531 we know that X was created before Y.
11532 Warning:
11534 Strictly monotonically increasing values are inherently quite
11535 expensive to generate and scales poorly. This is because the
11536 values need to be synchronized between CPU cores. That is, do
11537 not pass the monotonic modifier unless you really need
11538 strictly monotonically increasing values.
11539 All valid Modifiers can be combined. Repeated (valid) Modifiers
11542 in the ModifierList are ignored.
11543 Note:
11545 The set of integers returned by erlang:unique_integer/1 using
11546 different sets of Modifiers will overlap. For example, by call‐
11547 ing unique_integer([monotonic]), and unique_integer([positive,
11548 monotonic]) repeatedly, you will eventually see some integers
11549 that are returned by both calls.
11550 Failures:
11553 badarg:
11555 if ModifierList is not a proper list.
11556 badarg:
11558 if Modifier is not a valid modifier.
11559 erlang:universaltime() -> DateTime
11561 Types:
11563 DateTime = calendar:datetime()
11565 Returns the current date and time according to Universal Time
11567 Coordinated (UTC) in the form {{Year, Month, Day}, {Hour,
11568 Minute, Second}} if supported by the underlying OS. Otherwise
11569 erlang:universaltime() is equivalent to erlang:localtime(). The
11570 return value is based on the OS System Time. Example:
11571 > erlang:universaltime().
11573 {{1996,11,6},{14,18,43}}
11574 erlang:universaltime_to_localtime(Universaltime) -> Localtime
11576 Types:
11578 Localtime = Universaltime = calendar:datetime()
11580 Converts Universal Time Coordinated (UTC) date and time to local
11582 date and time in the form {{Year, Month, Day}, {Hour, Minute,
11583 Second}} if supported by the underlying OS. Otherwise no conver‐
11584 sion is done, and Universaltime is returned. Example:
11585 > erlang:universaltime_to_localtime({{1996,11,6},{14,18,43}}).
11587 {{1996,11,7},{15,18,43}}
11588 Failure: badarg if Universaltime denotes an invalid date and
11590 time.
11591 unlink(Id) -> true
11593 Types:
11595 Id = pid() | port()
11597 Removes a link between the calling process and another process
11599 or a port identified by Id. We will from here on call the iden‐
11600 tified process or port unlinkee.
11601 A link can be set up using the link/1 BIF. For more information
11603 on links and exit signals due to links, see the Processes chap‐
11604 ter in the Erlang Reference Manual :
11605 * Links
11607 * Sending Exit Signals
11609 * Receiving Exit Signals
11611 Once unlink(Id) has returned, it is guaranteed that the link be‐
11613 tween the caller and the unlinkee has no effect on the caller in
11614 the future (unless the link is setup again). Note that if the
11615 caller is trapping exits, an {'EXIT', Id, ExitReason} message
11616 due to the link may have been placed in the message queue of the
11617 caller before the unlink(Id) call completed. Also note that the
11618 {'EXIT', Id, ExitReason} message may be the result of the link,
11619 but may also be the result of the unlikee sending the caller an
11620 exit signal by calling the exit/2 BIF. Therefore, it may or may
11621 not be appropriate to clean up the message queue after a call to
11622 unlink(Id) as follows, when trapping exits:
11623 unlink(Id),
11625 receive
11626 {'EXIT', Id, _} ->
11627 true
11628 after 0 ->
11629 true
11630 end
11631 The link removal is performed asynchronously. If such a link
11633 does not exist, nothing is done. A detailed description of the
11634 link protocol can be found in the Distribution Protocol chapter
11635 of the ERTS User's Guide .
11636 Failure: badarg if Id does not identify a process or a node lo‐
11638 cal port.
11639 unregister(RegName) -> true
11641 Types:
11643 RegName = atom()
11645 Removes the registered name RegName associated with a process
11647 identifier or a port identifier from the name registry. For ex‐
11648 ample:
11649 > unregister(db).
11651 true
11652 Keep in mind that you can still receive signals associated with
11654 the registered name after it has been unregistered as the sender
11655 may have looked up the name before sending to it.
11656 Users are advised not to unregister system processes.
11658 Failure: badarg if RegName is not a registered name.
11660 whereis(RegName) -> pid() | port() | undefined
11662 Types:
11664 RegName = atom()
11666 Returns the process identifier or port identifier with the reg‐
11668 istered name RegName from the name registry. Returns undefined
11669 if the name is not registered. Example:
11670 > whereis(db).
11672 <0.43.0>
11673 erlang:yield() -> true
11675 Tries to give other processes with the same or higher priority
11677 (if any) a chance to execute before returning. There is no guar‐
11678 antee that any other process runs between the invocation and re‐
11679 turn of erlang:yield/0.
11680 See the documentation for receive-after expressions for how to
11682 make the current process sleep for a specific number of mil‐
11683 liseconds.
11684 Warning:
11686 There is seldom or never any need to use this BIF. Using this
11687 BIF without a thorough grasp of how the scheduler works can
11688 cause performance degradation. The current implementation of
11689 this function puts the current process last in the current
11690 scheduler's queue for processes of the same priority as the cur‐
11691 rent process.
11692Ericsson AB erts 12.1.5 erlang(3)