1erlang(3) Erlang Module Definition erlang(3)
2
6 erlang - The Erlang BIFs and predefined types.
7
9 By convention, most Built-In Functions (BIFs) and all predefined types
10 are included in this module. Some of the BIFs and all of the predefined
11 types are viewed more or less as part of the Erlang programming lan‐
12 guage and are auto-imported. Thus, it is not necessary to specify the
13 module name. For example, the calls atom_to_list(erlang) and er‐
14 lang:atom_to_list(erlang) are identical.
15 Auto-imported BIFs are listed without module prefix. BIFs listed with
17 module prefix are not auto-imported.
18 Predefined types are listed in the Predefined datatypes section of this
20 reference manual and in the Types and Function Specifications section
21 of the Erlang Reference Manual.
22 BIFs can fail for various reasons. All BIFs fail with reason badarg if
24 they are called with arguments of an incorrect type. The other reasons
25 are described in the description of each individual BIF.
26 Some BIFs can be used in guard tests and are marked with "Allowed in
28 guard tests".
29
31 Predefined datatypes
32 any() = any()
33 All possible Erlang terms. Synonym for term().
35 arity() = arity()
37 The arity of a function or type.
39 atom() = atom()
41 An Erlang atom.
43 binary() = <<_:_*8>>
45 An Erlang binary, that is, a bitstring with a size divisible by
47 8.
48 bitstring() = <<_:_*1>>
50 An Erlang bitstring.
52 boolean() = true | false
54 A boolean value.
56 byte() = 0..255
58 A byte of data represented by an integer.
60 char() = 0..1114111
62 An ASCII character or a unicode codepoint presented by an inte‐
64 ger.
65 float() = float()
67 An Erlang float.
69 function() = function()
71 An Erlang fun.
73 identifier() = pid() | port() | reference()
75 An unique identifier for some entity, for example a process,
77 port or monitor.
78 integer() = integer()
80 An Erlang integer.
82 iodata() = iolist() | binary()
84 A binary or list containing bytes and/or iodata. This datatype
86 is used to represent data that is meant to be output using any
87 I/O module. For example: file:write/2 or gen_tcp:send/2.
88 To convert an iodata() term to binary() you can use
90 iolist_to_binary/2. To transcode a string() or unicode:char‐
91 data() to iodata() you can use unicode:characters_to_binary/1.
92 iolist() =
94 maybe_improper_list(byte() | binary() | iolist(),
95 binary() | [])
96 A list containing bytes and/or iodata. This datatype is used to
98 represent data that is meant to be output using any I/O module.
99 For example: file:write/2 or gen_tcp:send/2.
100 In most use cases you want to use iodata() instead of this type.
102 list() = list()
104 An Erlang list containing terms of any type.
106 list(ContentType) = [ContentType]
108 An Erlang list containing terms of the type ContentType.
110 map() = #{any() => any()}
112 An Erlang map containing any number of key and value associa‐
114 tions.
115 maybe_improper_list() = maybe_improper_list(any(), any())
117 An Erlang list that is not guaranteed to end with a [], and
119 where the list elements can be of any type.
120 maybe_improper_list(ContentType, TerminationType) =
122 maybe_improper_list(ContentType, TerminationType)
123 An Erlang list, that is not guaranteed to end with a [], and
125 where the list elements are of the type ContentType.
126 mfa() = {module(), atom(), arity()}
128 A three-tuple representing a Module:Function/Arity function sig‐
130 nature.
131 module() = atom()
133 An Erlang module represented by an atom.
135 neg_integer() = integer() =< -1
137 A negative integer.
139 nil() = []
141 The empty list().
143 no_return() = none()
145 The type used to show that a function will never return a value,
147 that is it will always throw an exception.
148 node() = atom()
150 An Erlang node represented by an atom.
152 non_neg_integer() = integer() >= 0
154 A non-negative integer, that is any positive integer or 0.
156 none() = none()
158 This type is used to show that a function will never return a
160 value; that is it will always throw an exception. In a spec, use
161 no_return() for the sake of clarity.
162 nonempty_binary() = <<_:8, _:_*8>>
164 A binary() that contains some data.
166 nonempty_bitstring() = <<_:1, _:_*1>>
168 A bitstring() that contains some data.
170 nonempty_improper_list(ContentType, TerminationType) =
172 nonempty_improper_list(ContentType, TerminationType)
173 A maybe_improper_list/2 that contains some items.
175 nonempty_list() = [any(), ...]
177 A list() that contains some items.
179 nonempty_list(ContentType) = [ContentType, ...]
181 A list(ContentType) that contains some items.
183 nonempty_maybe_improper_list() =
185 nonempty_maybe_improper_list(any(), any())
186 A maybe_improper_list() that contains some items.
188 nonempty_maybe_improper_list(ContentType, TerminationType) =
190 nonempty_maybe_improper_list(ContentType, TerminationType)
191 A maybe_improper_list(ContentType, TerminationType) that con‐
193 tains some items.
194 nonempty_string() = [char(), ...]
196 A string() that contains some characters.
198 number() = integer() | float()
200 An Erlang number.
202 pid() = pid()
204 An Erlang process identifier.
206 port() = port()
208 An Erlang port identifier.
210 pos_integer() = integer() >= 1
212 An integer greater than zero.
214 reference() = reference()
216 An Erlang reference.
218 string() = [char()]
220 A character string represented by a list of ASCII characters or
222 unicode codepoints.
223 term() = any()
225 All possible Erlang terms. Synonym for any().
227 timeout() = infinity | integer() >= 0
229 A timeout value that can be passed to a receive expression.
231 tuple() = tuple()
233 An Erlang tuple.
235 Other Datatypes
237 ext_binary() = binary()
238 A binary data object, structured according to the Erlang exter‐
240 nal term format.
241 ext_iovec() = iovec()
243 A term of type iovec(), structured according to the Erlang ex‐
245 ternal term format.
246 iovec() = [binary()]
248 A list of binaries. This datatype is useful to use together with
250 enif_inspect_iovec.
251 message_queue_data() = off_heap | on_heap
253 See process_flag(message_queue_data, MQD).
255 monitor_option() =
257 {alias, explicit_unalias | demonitor | reply_demonitor} |
258 {tag, term()}
259 See monitor/3.
261 timestamp() =
263 {MegaSecs :: integer() >= 0,
264 Secs :: integer() >= 0,
265 MicroSecs :: integer() >= 0}
266 See erlang:timestamp/0.
268 time_unit() =
270 integer() >= 1 |
271 second | millisecond | microsecond | nanosecond | native |
272 perf_counter |
273 deprecated_time_unit()
274 Supported time unit representations:
276 PartsPerSecond :: integer() >= 1:
278 Time unit expressed in parts per second. That is, the time
279 unit equals 1/PartsPerSecond second.
280 second:
282 Symbolic representation of the time unit represented by the
283 integer 1.
284 millisecond:
286 Symbolic representation of the time unit represented by the
287 integer 1000.
288 microsecond:
290 Symbolic representation of the time unit represented by the
291 integer 1000_000.
292 nanosecond:
294 Symbolic representation of the time unit represented by the
295 integer 1000_000_000.
296 native:
298 Symbolic representation of the native time unit used by the
299 Erlang runtime system.
300 The native time unit is determined at runtime system start,
302 and remains the same until the runtime system terminates. If
303 a runtime system is stopped and then started again (even on
304 the same machine), the native time unit of the new runtime
305 system instance can differ from the native time unit of the
306 old runtime system instance.
307 One can get an approximation of the native time unit by
309 calling erlang:convert_time_unit(1, second, native). The re‐
310 sult equals the number of whole native time units per sec‐
311 ond. If the number of native time units per second does not
312 add up to a whole number, the result is rounded downwards.
313 Note:
315 The value of the native time unit gives you more or less no
316 information about the quality of time values. It sets a limit
317 for the resolution and for the precision of time values, but
318 it gives no information about the accuracy of time values.
319 The resolution of the native time unit and the resolution of
320 time values can differ significantly.
321 perf_counter:
324 Symbolic representation of the performance counter time unit
325 used by the Erlang runtime system.
326 The perf_counter time unit behaves much in the same way as
328 the native time unit. That is, it can differ between runtime
329 restarts. To get values of this type, call
330 os:perf_counter/0.
331 deprecated_time_unit():
333 Deprecated symbolic representations kept for backwards-com‐
334 patibility.
335 The time_unit/0 type can be extended. To convert time values be‐
337 tween time units, use erlang:convert_time_unit/3.
338 deprecated_time_unit() =
340 seconds | milli_seconds | micro_seconds | nano_seconds
341 The time_unit() type also consist of the following deprecated
343 symbolic time units:
344 seconds:
346 Same as second.
347 milli_seconds:
349 Same as millisecond.
350 micro_seconds:
352 Same as microsecond.
353 nano_seconds:
355 Same as nanosecond.
356 dist_handle()
358 An opaque handle identifing a distribution channel.
360 nif_resource()
362 An opaque handle identifing a NIF resource object .
364 spawn_opt_option() =
366 link | monitor |
367 {monitor, MonitorOpts :: [monitor_option()]} |
368 {priority, Level :: priority_level()} |
369 {fullsweep_after, Number :: integer() >= 0} |
370 {min_heap_size, Size :: integer() >= 0} |
371 {min_bin_vheap_size, VSize :: integer() >= 0} |
372 {max_heap_size, Size :: max_heap_size()} |
373 {message_queue_data, MQD :: message_queue_data()}
374 Options for spawn_opt().
376 priority_level() = low | normal | high | max
378 Process priority level. For more info see process_flag(priority,
380 Level)
381 max_heap_size() =
383 integer() >= 0 |
384 #{size => integer() >= 0,
385 kill => boolean(),
386 error_logger => boolean()}
387 Process max heap size configuration. For more info see
389 process_flag(max_heap_size, MaxHeapSize)
390 message_queue_data() = off_heap | on_heap
392 Process message queue data configuration. For more information,
394 see process_flag(message_queue_data, MQD)
395 stacktrace() =
397 [{module(),
398 atom(),
399 arity() | [term()],
400 [stacktrace_extrainfo()]} |
401 {function(), arity() | [term()], [stacktrace_extrainfo()]}]
402 stacktrace_extrainfo() =
404 {line, integer() >= 1} |
405 {file, unicode:chardata()} |
406 {error_info,
407 #{module => module(), function => atom(), cause => term()}} |
408 {atom(), term()}
409 An Erlang stacktrace as described by Errors and Error Handling
411 section in the Erlang Reference Manual.
412
414 abs(Float) -> float()
415 abs(Int) -> integer() >= 0
417 Types:
419 Int = integer()
421 Returns an integer or float that is the arithmetical absolute
423 value of Float or Int, for example:
424 > abs(-3.33).
426 3.33
427 > abs(-3).
428 3
429 Allowed in guard tests.
431 erlang:adler32(Data) -> integer() >= 0
433 Types:
435 Data = iodata()
437 Computes and returns the adler32 checksum for Data.
439 erlang:adler32(OldAdler, Data) -> integer() >= 0
441 Types:
443 OldAdler = integer() >= 0
445 Data = iodata()
446 Continues computing the adler32 checksum by combining the previ‐
448 ous checksum, OldAdler, with the checksum of Data.
449 The following code:
451 X = erlang:adler32(Data1),
453 Y = erlang:adler32(X,Data2).
454 assigns the same value to Y as this:
456 Y = erlang:adler32([Data1,Data2]).
458 erlang:adler32_combine(FirstAdler, SecondAdler, SecondSize) ->
460 integer() >= 0
461 Types:
463 FirstAdler = SecondAdler = SecondSize = integer() >= 0
465 Combines two previously computed adler32 checksums. This compu‐
467 tation requires the size of the data object for the second
468 checksum to be known.
469 The following code:
471 Y = erlang:adler32(Data1),
473 Z = erlang:adler32(Y,Data2).
474 assigns the same value to Z as this:
476 X = erlang:adler32(Data1),
478 Y = erlang:adler32(Data2),
479 Z = erlang:adler32_combine(X,Y,iolist_size(Data2)).
480 alias() -> Alias
482 alias(Opts) -> Alias
484 Types:
486 Alias = reference()
488 Opts = [explicit_unalias | reply]
489 Create an alias which can be used when sending messages to the
491 process that created the alias. When the alias has been deacti‐
492 vated, messages sent using the alias will be dropped. An alias
493 can be deactivated using unalias/1. Currently available options
494 for alias/1:
495 explicit_unalias:
497 The alias can only be deactivated via a call to unalias/1.
498 This is also the default behaviour if no options are passed
499 or if alias/0 is called.
500 reply:
502 The alias will be automatically deactivated when a reply
503 message sent via the alias is received. The alias can also
504 still be deactivated via a call to unalias/1.
505 Example:
507 server() ->
509 receive
510 {request, AliasReqId, Request} ->
511 Result = perform_request(Request),
512 AliasReqId ! {reply, AliasReqId, Result}
513 end,
514 server().
515 client(ServerPid, Request) ->
517 AliasReqId = alias([reply]),
518 ServerPid ! {request, AliasReqId, Request},
519 %% Alias will be automatically deactivated if we receive a reply
520 %% since we used the 'reply' option...
521 receive
522 {reply, AliasReqId, Result} -> Result
523 after 5000 ->
524 unalias(AliasReqId),
525 %% Flush message queue in case the reply arrived
526 %% just before the alias was deactivated...
527 receive {reply, AliasReqId, Result} -> Result
528 after 0 -> exit(timeout)
529 end
530 end.
531 Note that both the server and the client in this example must be
534 executing on at least OTP 24 systems in order for this to work.
535 For more information on process aliases see the Process Aliases
537 section of the Erlang Reference Manual .
538 erlang:append_element(Tuple1, Term) -> Tuple2
540 Types:
542 Tuple1 = Tuple2 = tuple()
544 Term = term()
545 Returns a new tuple that has one element more than Tuple1, and
547 contains the elements in Tuple1 followed by Term as the last el‐
548 ement. Semantically equivalent to list_to_tuple(tu‐
549 ple_to_list(Tuple1) ++ [Term]), but much faster. Example:
550 > erlang:append_element({one, two}, three).
552 {one,two,three}
553 apply(Fun, Args) -> term()
555 Types:
557 Fun = function()
559 Args = [term()]
560 Calls a fun, passing the elements in Args as arguments.
562 If the number of elements in the arguments are known at compile
564 time, the call is better written as Fun(Arg1, Arg2, ... ArgN).
565 Warning:
567 Earlier, Fun could also be specified as {Module, Function},
568 equivalent to apply(Module, Function, Args). This use is depre‐
569 cated and will stop working in a future release.
570 apply(Module, Function, Args) -> term()
573 Types:
575 Module = module()
577 Function = atom()
578 Args = [term()]
579 Returns the result of applying Function in Module to Args. The
581 applied function must be exported from Module. The arity of the
582 function is the length of Args. Example:
583 > apply(lists, reverse, [[a, b, c]]).
585 [c,b,a]
586 > apply(erlang, atom_to_list, ['Erlang']).
587 "Erlang"
588 If the number of arguments are known at compile time, the call
590 is better written as Module:Function(Arg1, Arg2, ..., ArgN).
591 Failure: error_handler:undefined_function/3 is called if the ap‐
593 plied function is not exported. The error handler can be rede‐
594 fined (see process_flag/2). If error_handler is undefined, or if
595 the user has redefined the default error_handler so the replace‐
596 ment module is undefined, an error with reason undef is gener‐
597 ated.
598 atom_to_binary(Atom) -> binary()
600 Types:
602 Atom = atom()
604 The same as atom_to_binary(Atom, utf8).
606 atom_to_binary(Atom, Encoding) -> binary()
608 Types:
610 Atom = atom()
612 Encoding = latin1 | unicode | utf8
613 Returns a binary corresponding to the text representation of
615 Atom. If Encoding is latin1, one byte exists for each character
616 in the text representation. If Encoding is utf8 or unicode, the
617 characters are encoded using UTF-8 where characters may require
618 multiple bytes.
619 Note:
621 As from Erlang/OTP 20, atoms can contain any Unicode character
622 and atom_to_binary(Atom, latin1) may fail if the text represen‐
623 tation for Atom contains a Unicode character > 255.
624 Example:
627 > atom_to_binary('Erlang', latin1).
629 <<"Erlang">>
630 atom_to_list(Atom) -> string()
632 Types:
634 Atom = atom()
636 Returns a list of unicode code points corresponding to the text
638 representation of Atom, for example:
639 > atom_to_list('Erlang').
641 "Erlang"
642 > atom_to_list('你好').
644 [20320,22909]
645 See unicode(3) for how to convert the resulting list to differ‐
647 ent formats.
648 binary_part(Subject, PosLen) -> binary()
650 Types:
652 Subject = binary()
654 PosLen = {Start :: integer() >= 0, Length :: integer()}
655 Extracts the part of the binary described by PosLen.
657 Negative length can be used to extract bytes at the end of a bi‐
659 nary, for example:
660 1> Bin = <<1,2,3,4,5,6,7,8,9,10>>.
662 2> binary_part(Bin,{byte_size(Bin), -5}).
663 <<6,7,8,9,10>>
664 Failure: badarg if PosLen in any way references outside the bi‐
666 nary.
667 Start is zero-based, that is:
669 1> Bin = <<1,2,3>>
671 2> binary_part(Bin,{0,2}).
672 <<1,2>>
673 For details about the PosLen semantics, see binary(3).
675 Allowed in guard tests.
677 binary_part(Subject, Start, Length) -> binary()
679 Types:
681 Subject = binary()
683 Start = integer() >= 0
684 Length = integer()
685 The same as binary_part(Subject, {Start, Length}).
687 Allowed in guard tests.
689 binary_to_atom(Binary) -> atom()
691 Types:
693 Binary = binary()
695 The same as binary_to_atom(Binary, utf8).
697 binary_to_atom(Binary, Encoding) -> atom()
699 Types:
701 Binary = binary()
703 Encoding = latin1 | unicode | utf8
704 Returns the atom whose text representation is Binary. If Encod‐
706 ing is utf8 or unicode, the binary must contain valid UTF-8 se‐
707 quences.
708 Note:
710 As from Erlang/OTP 20, binary_to_atom(Binary, utf8) is capable
711 of decoding any Unicode character. Earlier versions would fail
712 if the binary contained Unicode characters > 255.
713 Note:
716 The number of characters that are permitted in an atom name is
717 limited. The default limits can be found in the efficiency
718 guide (section Advanced).
719 Note:
722 There is configurable limit on how many atoms that can exist and
723 atoms are not garbage collected. Therefore, it is recommended to
724 consider whether binary_to_existing_atom/2 is a better option
725 than binary_to_atom/2. The default limits can be found in effi‐
726 ciency guide (section Advanced).
727 Examples:
730 > binary_to_atom(<<"Erlang">>, latin1).
732 > binary_to_atom(<<1024/utf8>>, utf8).
734 binary_to_existing_atom(Binary) -> atom()
736 Types:
738 Binary = binary()
740 The same as binary_to_existing_atom (Binary, utf8).
742 binary_to_existing_atom(Binary, Encoding) -> atom()
744 Types:
746 Binary = binary()
748 Encoding = latin1 | unicode | utf8
749 As binary_to_atom/2, but the atom must exist.
751 The Erlang system has a configurable limit for the total number
753 of atoms that can exist, and atoms are not garbage collected.
754 Therefore, it is not safe to create many atoms from binaries
755 that come from an untrusted source (for example, a file fetched
756 from the Internet), for example, using binary_to_atom/2. This
757 function is thus the appropriate option when the input binary
758 comes from an untrusted source.
759 An atom exists in an Erlang system when included in a loaded Er‐
761 lang module or when created programmatically (for example, by
762 binary_to_atom/2). See the next note for an example of when an
763 atom exists in the source code for an Erlang module but not in
764 the compiled version of the same module.
765 Failure: badarg if the atom does not exist.
767 Note:
769 Note that the compiler may optimize away atoms. For example, the
770 compiler will rewrite atom_to_list(some_atom) to "some_atom". If
771 that expression is the only mention of the atom some_atom in the
772 containing module, the atom will not be created when the module
773 is loaded, and a subsequent call to binary_to_exist‐
774 ing_atom(<<"some_atom">>, utf8) will fail.
775 Note:
778 The number of characters that are permitted in an atom name is
779 limited. The default limits can be found in the efficiency
780 guide (section Advanced).
781 binary_to_float(Binary) -> float()
784 Types:
786 Binary = binary()
788 Returns the float whose text representation is Binary, for exam‐
790 ple:
791 > binary_to_float(<<"2.2017764e+0">>).
793 2.2017764
794 The float string format is the same as the format for Erlang
796 float literals except for that underscores are not permitted.
797 Failure: badarg if Binary contains a bad representation of a
799 float.
800 binary_to_integer(Binary) -> integer()
802 Types:
804 Binary = binary()
806 Returns an integer whose text representation is Binary, for ex‐
808 ample:
809 > binary_to_integer(<<"123">>).
811 123
812 binary_to_integer/1 accepts the same string formats as
814 list_to_integer/1.
815 Failure: badarg if Binary contains a bad representation of an
817 integer.
818 binary_to_integer(Binary, Base) -> integer()
820 Types:
822 Binary = binary()
824 Base = 2..36
825 Returns an integer whose text representation in base Base is Bi‐
827 nary, for example:
828 > binary_to_integer(<<"3FF">>, 16).
830 1023
831 binary_to_integer/2 accepts the same string formats as
833 list_to_integer/2.
834 Failure: badarg if Binary contains a bad representation of an
836 integer.
837 binary_to_list(Binary) -> [byte()]
839 Types:
841 Binary = binary()
843 Returns a list of integers corresponding to the bytes of Binary.
845 binary_to_list(Binary, Start, Stop) -> [byte()]
847 Types:
849 Binary = binary()
851 Start = Stop = integer() >= 1
852 1..byte_size(Binary)
853 As binary_to_list/1, but returns a list of integers correspond‐
855 ing to the bytes from position Start to position Stop in Binary.
856 The positions in the binary are numbered starting from 1.
857 Note:
859 The one-based indexing for binaries used by this function is
860 deprecated. New code is to use binary:bin_to_list/3 in STDLIB
861 instead. All functions in module binary consistently use zero-
862 based indexing.
863 binary_to_term(Binary) -> term()
866 Types:
868 Binary = ext_binary()
870 Returns an Erlang term that is the result of decoding binary ob‐
872 ject Binary, which must be encoded according to the Erlang ex‐
873 ternal term format.
874 > Bin = term_to_binary(hello).
876 <<131,100,0,5,104,101,108,108,111>>
877 > hello = binary_to_term(Bin).
878 hello
879 Warning:
882 When decoding binaries from untrusted sources, the untrusted
883 source may submit data in a way to create resources, such as
884 atoms and remote references, that cannot be garbage collected
885 and lead to Denial of Service attack. In such cases, consider
886 using binary_to_term/2 with the safe option.
887 See also term_to_binary/1 and binary_to_term/2.
890 binary_to_term(Binary, Opts) -> term() | {term(), Used}
892 Types:
894 Binary = ext_binary()
896 Opt = safe | used
897 Opts = [Opt]
898 Used = integer() >= 1
899 As binary_to_term/1, but takes these options:
901 safe:
903 Use this option when receiving binaries from an untrusted
904 source.
905 When enabled, it prevents decoding data that can be used to
907 attack the Erlang runtime. In the event of receiving unsafe
908 data, decoding fails with a badarg error.
909 This prevents creation of new atoms directly, creation of
911 new atoms indirectly (as they are embedded in certain struc‐
912 tures, such as process identifiers, refs, and funs), and
913 creation of new external function references. None of those
914 resources are garbage collected, so unchecked creation of
915 them can exhaust available memory.
916 > binary_to_term(<<131,100,0,5,"hello">>, [safe]).
918 ** exception error: bad argument
919 > hello.
920 hello
921 > binary_to_term(<<131,100,0,5,"hello">>, [safe]).
922 hello
923 Warning:
926 The safe option ensures the data is safely processed by the
927 Erlang runtime but it does not guarantee the data is safe to
928 your application. You must always validate data from untrusted
929 sources. If the binary is stored or transits through untrusted
930 sources, you should also consider cryptographically signing
931 it.
932 used:
935 Changes the return value to {Term, Used} where Used is the
936 number of bytes actually read from Binary.
937 > Input = <<131,100,0,5,"hello","world">>.
939 <<131,100,0,5,104,101,108,108,111,119,111,114,108,100>>
940 > {Term, Used} = binary_to_term(Input, [used]).
941 {hello, 9}
942 > split_binary(Input, Used).
943 {<<131,100,0,5,104,101,108,108,111>>, <<"world">>}
944 Failure: badarg if safe is specified and unsafe data is decoded.
947 See also term_to_binary/1, binary_to_term/1, and list_to_exist‐
949 ing_atom/1.
950 bit_size(Bitstring) -> integer() >= 0
952 Types:
954 Bitstring = bitstring()
956 Returns an integer that is the size in bits of Bitstring, for
958 example:
959 > bit_size(<<433:16,3:3>>).
961 19
962 > bit_size(<<1,2,3>>).
963 24
964 Allowed in guard tests.
966 bitstring_to_list(Bitstring) -> [byte() | bitstring()]
968 Types:
970 Bitstring = bitstring()
972 Returns a list of integers corresponding to the bytes of Bit‐
974 string. If the number of bits in the binary is not divisible by
975 8, the last element of the list is a bitstring containing the
976 remaining 1-7 bits. Examples:
977 > bitstring_to_list(<<433:16>>).
979 [1,177]
980 > bitstring_to_list(<<433:16,3:3>>).
982 [1,177,<<3:3>>]
983 erlang:bump_reductions(Reductions) -> true
985 Types:
987 Reductions = integer() >= 1
989 This implementation-dependent function increments the reduction
991 counter for the calling process. In the Beam emulator, the re‐
992 duction counter is normally incremented by one for each function
993 and BIF call. A context switch is forced when the counter
994 reaches the maximum number of reductions for a process (4000 re‐
995 ductions in Erlang/OTP 19.2 and later).
996 Warning:
998 This BIF can be removed in a future version of the Beam machine
999 without prior warning. It is unlikely to be implemented in other
1000 Erlang implementations.
1001 byte_size(Bitstring) -> integer() >= 0
1004 Types:
1006 Bitstring = bitstring()
1008 Returns an integer that is the number of bytes needed to contain
1010 Bitstring. That is, if the number of bits in Bitstring is not
1011 divisible by 8, the resulting number of bytes is rounded up. Ex‐
1012 amples:
1013 > byte_size(<<433:16,3:3>>).
1015 3
1016 > byte_size(<<1,2,3>>).
1017 3
1018 Allowed in guard tests.
1020 erlang:cancel_timer(TimerRef) -> Result
1022 Types:
1024 TimerRef = reference()
1026 Time = integer() >= 0
1027 Result = Time | false
1028 Cancels a timer. The same as calling erlang:cancel_timer(Timer‐
1030 Ref, []).
1031 erlang:cancel_timer(TimerRef, Options) -> Result | ok
1033 Types:
1035 TimerRef = reference()
1037 Async = Info = boolean()
1038 Option = {async, Async} | {info, Info}
1039 Options = [Option]
1040 Time = integer() >= 0
1041 Result = Time | false
1042 Cancels a timer that has been created by erlang:start_timer or
1044 erlang:send_after. TimerRef identifies the timer, and was re‐
1045 turned by the BIF that created the timer.
1046 Options:
1048 {async, Async}:
1050 Asynchronous request for cancellation. Async defaults to
1051 false, which causes the cancellation to be performed syn‐
1052 chronously. When Async is set to true, the cancel operation
1053 is performed asynchronously. That is, cancel_timer() sends
1054 an asynchronous request for cancellation to the timer ser‐
1055 vice that manages the timer, and then returns ok.
1056 {info, Info}:
1058 Requests information about the Result of the cancellation.
1059 Info defaults to true, which means the Result is given. When
1060 Info is set to false, no information about the result of the
1061 cancellation is given.
1062 * When Async is false: if Info is true, the Result is re‐
1064 turned by erlang:cancel_timer(). otherwise ok is returned.
1065 * When Async is true: if Info is true, a message on the form
1067 {cancel_timer, TimerRef, Result} is sent to the caller of
1068 erlang:cancel_timer() when the cancellation operation has
1069 been performed, otherwise no message is sent.
1070 More Options may be added in the future.
1072 If Result is an integer, it represents the time in milliseconds
1074 left until the canceled timer would have expired.
1075 If Result is false, a timer corresponding to TimerRef could not
1077 be found. This can be either because the timer had expired, al‐
1078 ready had been canceled, or because TimerRef never corresponded
1079 to a timer. Even if the timer had expired, it does not tell you
1080 if the time-out message has arrived at its destination yet.
1081 Note:
1083 The timer service that manages the timer can be co-located with
1084 another scheduler than the scheduler that the calling process is
1085 executing on. If so, communication with the timer service takes
1086 much longer time than if it is located locally. If the calling
1087 process is in critical path, and can do other things while wait‐
1088 ing for the result of this operation, or is not interested in
1089 the result of the operation, you want to use option {async,
1090 true}. If using option {async, false}, the calling process
1091 blocks until the operation has been performed.
1092 See also erlang:send_after/4, erlang:start_timer/4, and er‐
1095 lang:read_timer/2.
1096 ceil(Number) -> integer()
1098 Types:
1100 Number = number()
1102 Returns the smallest integer not less than Number. For example:
1104 > ceil(5.5).
1106 6
1107 Allowed in guard tests.
1109 check_old_code(Module) -> boolean()
1111 Types:
1113 Module = module()
1115 Returns true if Module has old code, otherwise false.
1117 See also code(3).
1119 check_process_code(Pid, Module) -> CheckResult
1121 Types:
1123 Pid = pid()
1125 Module = module()
1126 CheckResult = boolean()
1127 The same as check_process_code(Pid, Module, []).
1129 check_process_code(Pid, Module, OptionList) -> CheckResult | async
1131 Types:
1133 Pid = pid()
1135 Module = module()
1136 RequestId = term()
1137 Option = {async, RequestId} | {allow_gc, boolean()}
1138 OptionList = [Option]
1139 CheckResult = boolean() | aborted
1140 Checks if the node local process identified by Pid executes old
1142 code for Module.
1143 Options:
1145 {allow_gc, boolean()}:
1147 Determines if garbage collection is allowed when performing
1148 the operation. If {allow_gc, false} is passed, and a garbage
1149 collection is needed to determine the result of the opera‐
1150 tion, the operation is aborted (see information on CheckRe‐
1151 sult below). The default is to allow garbage collection,
1152 that is, {allow_gc, true}.
1153 {async, RequestId}:
1155 The function check_process_code/3 returns the value async
1156 immediately after the request has been sent. When the re‐
1157 quest has been processed, the process that called this func‐
1158 tion is passed a message on the form {check_process_code,
1159 RequestId, CheckResult}.
1160 If Pid equals self(), and no async option has been passed, the
1162 operation is performed at once. Otherwise a request for the op‐
1163 eration is sent to the process identified by Pid, and is handled
1164 when appropriate. If no async option has been passed, the caller
1165 blocks until CheckResult is available and can be returned.
1166 CheckResult informs about the result of the request as follows:
1168 true:
1170 The process identified by Pid executes old code for Module.
1171 That is, the current call of the process executes old code
1172 for this module, or the process has references to old code
1173 for this module, or the process contains funs that refer‐
1174 ences old code for this module.
1175 false:
1177 The process identified by Pid does not execute old code for
1178 Module.
1179 aborted:
1181 The operation was aborted, as the process needed to be
1182 garbage collected to determine the operation result, and the
1183 operation was requested by passing option {allow_gc, false}.
1184 Note:
1186 Up until ERTS version 8.*, the check process code operation
1187 checks for all types of references to the old code. That is, di‐
1188 rect references (e.g. return addresses on the process stack),
1189 indirect references (funs in process context), and references to
1190 literals in the code.
1191 As of ERTS version 9.0, the check process code operation only
1193 checks for direct references to the code. Indirect references
1194 via funs will be ignored. If such funs exist and are used after
1195 a purge of the old code, an exception will be raised upon usage
1196 (same as the case when the fun is received by the process after
1197 the purge). Literals will be taken care of (copied) at a later
1198 stage. This behavior can as of ERTS version 8.1 be enabled when
1199 building OTP, and will automatically be enabled if dirty sched‐
1200 uler support is enabled.
1201 See also code(3).
1204 Failures:
1206 badarg:
1208 If Pid is not a node local process identifier.
1209 badarg:
1211 If Module is not an atom.
1212 badarg:
1214 If OptionList is an invalid list of options.
1215 erlang:convert_time_unit(Time, FromUnit, ToUnit) -> ConvertedTime
1217 Types:
1219 Time = ConvertedTime = integer()
1221 FromUnit = ToUnit = time_unit()
1222 Converts the Time value of time unit FromUnit to the correspond‐
1224 ing ConvertedTime value of time unit ToUnit. The result is
1225 rounded using the floor function.
1226 Warning:
1228 You can lose accuracy and precision when converting between time
1229 units. To minimize such loss, collect all data at native time
1230 unit and do the conversion on the end result.
1231 erlang:crc32(Data) -> integer() >= 0
1234 Types:
1236 Data = iodata()
1238 Computes and returns the crc32 (IEEE 802.3 style) checksum for
1240 Data.
1241 erlang:crc32(OldCrc, Data) -> integer() >= 0
1243 Types:
1245 OldCrc = integer() >= 0
1247 Data = iodata()
1248 Continues computing the crc32 checksum by combining the previous
1250 checksum, OldCrc, with the checksum of Data.
1251 The following code:
1253 X = erlang:crc32(Data1),
1255 Y = erlang:crc32(X,Data2).
1256 assigns the same value to Y as this:
1258 Y = erlang:crc32([Data1,Data2]).
1260 erlang:crc32_combine(FirstCrc, SecondCrc, SecondSize) ->
1262 integer() >= 0
1263 Types:
1265 FirstCrc = SecondCrc = SecondSize = integer() >= 0
1267 Combines two previously computed crc32 checksums. This computa‐
1269 tion requires the size of the data object for the second check‐
1270 sum to be known.
1271 The following code:
1273 Y = erlang:crc32(Data1),
1275 Z = erlang:crc32(Y,Data2).
1276 assigns the same value to Z as this:
1278 X = erlang:crc32(Data1),
1280 Y = erlang:crc32(Data2),
1281 Z = erlang:crc32_combine(X,Y,iolist_size(Data2)).
1282 date() -> Date
1284 Types:
1286 Date = calendar:date()
1288 Returns the current date as {Year, Month, Day}.
1290 The time zone and Daylight Saving Time correction depend on the
1292 underlying OS. The return value is based on the OS System Time.
1293 Example:
1294 > date().
1296 {1995,2,19}
1297 erlang:decode_packet(Type, Bin, Options) ->
1299 {ok, Packet, Rest} |
1300 {more, Length} |
1301 {error, Reason}
1302 Types:
1304 Type =
1306 raw | 0 | 1 | 2 | 4 | asn1 | cdr | sunrm | fcgi | tpkt |
1307 line | http | http_bin | httph | httph_bin
1308 Bin = binary()
1309 Options = [Opt]
1310 Opt =
1311 {packet_size, integer() >= 0} |
1312 {line_length, integer() >= 0}
1313 Packet = binary() | HttpPacket
1314 Rest = binary()
1315 Length = integer() >= 0 | undefined
1316 Reason = term()
1317 HttpPacket =
1318 HttpRequest | HttpResponse | HttpHeader | http_eoh |
1319 HttpError
1320 HttpRequest = {http_request, HttpMethod, HttpUri, HttpVer‐
1321 sion}
1322 HttpResponse =
1323 {http_response, HttpVersion, integer(), HttpString}
1324 HttpHeader =
1325 {http_header,
1326 integer(),
1327 HttpField,
1328 UnmodifiedField :: HttpString,
1329 Value :: HttpString}
1330 HttpError = {http_error, HttpString}
1331 HttpMethod =
1332 'OPTIONS' | 'GET' | 'HEAD' | 'POST' | 'PUT' | 'DELETE' |
1333 'TRACE' | HttpString
1334 HttpUri =
1335 '*' |
1336 {absoluteURI,
1337 http | https,
1338 Host :: HttpString,
1339 Port :: inet:port_number() | undefined,
1340 Path :: HttpString} |
1341 {scheme, Scheme :: HttpString, HttpString} |
1342 {abs_path, HttpString} |
1343 HttpString
1344 HttpVersion =
1345 {Major :: integer() >= 0, Minor :: integer() >= 0}
1346 HttpField =
1347 'Cache-Control' | 'Connection' | 'Date' | 'Pragma' |
1348 'Transfer-Encoding' | 'Upgrade' | 'Via' | 'Accept' |
1349 'Accept-Charset' | 'Accept-Encoding' | 'Accept-Language'
1350 |
1351 'Authorization' | 'From' | 'Host' | 'If-Modified-Since' |
1352 'If-Match' | 'If-None-Match' | 'If-Range' |
1353 'If-Unmodified-Since' | 'Max-Forwards' |
1354 'Proxy-Authorization' | 'Range' | 'Referer' | 'User-
1355 Agent' |
1356 'Age' | 'Location' | 'Proxy-Authenticate' | 'Public' |
1357 'Retry-After' | 'Server' | 'Vary' | 'Warning' |
1358 'Www-Authenticate' | 'Allow' | 'Content-Base' |
1359 'Content-Encoding' | 'Content-Language' | 'Content-
1360 Length' |
1361 'Content-Location' | 'Content-Md5' | 'Content-Range' |
1362 'Content-Type' | 'Etag' | 'Expires' | 'Last-Modified' |
1363 'Accept-Ranges' | 'Set-Cookie' | 'Set-Cookie2' |
1364 'X-Forwarded-For' | 'Cookie' | 'Keep-Alive' |
1365 'Proxy-Connection' | HttpString
1366 HttpString = string() | binary()
1367 Decodes the binary Bin according to the packet protocol speci‐
1369 fied by Type. Similar to the packet handling done by sockets
1370 with option {packet,Type}.
1371 If an entire packet is contained in Bin, it is returned together
1373 with the remainder of the binary as {ok,Packet,Rest}.
1374 If Bin does not contain the entire packet, {more,Length} is re‐
1376 turned. Length is either the expected total size of the packet,
1377 or undefined if the expected packet size is unknown. de‐
1378 code_packet can then be called again with more data added.
1379 If the packet does not conform to the protocol format, {er‐
1381 ror,Reason} is returned.
1382 Types:
1384 raw | 0:
1386 No packet handling is done. The entire binary is returned
1387 unless it is empty.
1388 1 | 2 | 4:
1390 Packets consist of a header specifying the number of bytes
1391 in the packet, followed by that number of bytes. The length
1392 of the header can be one, two, or four bytes; the order of
1393 the bytes is big-endian. The header is stripped off when the
1394 packet is returned.
1395 line:
1397 A packet is a line-terminated by a delimiter byte, default
1398 is the latin-1 newline character. The delimiter byte is in‐
1399 cluded in the returned packet unless the line was truncated
1400 according to option line_length.
1401 asn1 | cdr | sunrm | fcgi | tpkt:
1403 The header is not stripped off.
1404 The meanings of the packet types are as follows:
1406 asn1 - ASN.1 BER:
1408 sunrm - Sun's RPC encoding:
1411 cdr - CORBA (GIOP 1.1):
1414 fcgi - Fast CGI:
1417 tpkt - TPKT format [RFC1006]:
1420 http | httph | http_bin | httph_bin:
1423 The Hypertext Transfer Protocol. The packets are returned
1424 with the format according to HttpPacket described earlier. A
1425 packet is either a request, a response, a header, or an end
1426 of header mark. Invalid lines are returned as HttpError.
1427 Recognized request methods and header fields are returned as
1429 atoms. Others are returned as strings. Strings of unrecog‐
1430 nized header fields are formatted with only capital letters
1431 first and after hyphen characters, for example, "Sec-Web‐
1432 socket-Key". Header field names are also returned in Unmodi‐
1433 fiedField as strings, without any conversion or formatting.
1434 The protocol type http is only to be used for the first line
1436 when an HttpRequest or an HttpResponse is expected. The fol‐
1437 lowing calls are to use httph to get HttpHeaders until
1438 http_eoh is returned, which marks the end of the headers and
1439 the beginning of any following message body.
1440 The variants http_bin and httph_bin return strings (Http‐
1442 String) as binaries instead of lists.
1443 Options:
1445 {packet_size, integer() >= 0}:
1447 Sets the maximum allowed size of the packet body. If the
1448 packet header indicates that the length of the packet is
1449 longer than the maximum allowed length, the packet is con‐
1450 sidered invalid. Defaults to 0, which means no size limit.
1451 {line_length, integer() >= 0}:
1453 For packet type line, lines longer than the indicated length
1454 are truncated.
1455 Option line_length also applies to http* packet types as an
1457 alias for option packet_size if packet_size itself is not
1458 set. This use is only intended for backward compatibility.
1459 {line_delimiter, 0 =< byte() =< 255}:
1461 For packet type line, sets the delimiting byte. Default is
1462 the latin-1 character $\n.
1463 Examples:
1465 > erlang:decode_packet(1,<<3,"abcd">>,[]).
1467 {ok,<<"abc">>,<<"d">>}
1468 > erlang:decode_packet(1,<<5,"abcd">>,[]).
1469 {more,6}
1470 erlang:delete_element(Index, Tuple1) -> Tuple2
1472 Types:
1474 Index = integer() >= 1
1476 1..tuple_size(Tuple1)
1477 Tuple1 = Tuple2 = tuple()
1478 Returns a new tuple with element at Index removed from tuple Tu‐
1480 ple1, for example:
1481 > erlang:delete_element(2, {one, two, three}).
1483 {one,three}
1484 delete_module(Module) -> true | undefined
1486 Types:
1488 Module = module()
1490 Makes the current code for Module become old code and deletes
1492 all references for this module from the export table. Returns
1493 undefined if the module does not exist, otherwise true.
1494 Warning:
1496 This BIF is intended for the code server (see code(3)) and is
1497 not to be used elsewhere.
1498 Failure: badarg if there already is an old version of Module.
1501 demonitor(MonitorRef) -> true
1503 Types:
1505 MonitorRef = reference()
1507 If MonitorRef is a reference that the calling process obtained
1509 by calling monitor/2, this monitoring is turned off. If the mon‐
1510 itoring is already turned off, nothing happens.
1511 Once demonitor(MonitorRef) has returned, it is guaranteed that
1513 no {'DOWN', MonitorRef, _, _, _} message, because of the moni‐
1514 tor, will be placed in the caller message queue in the future.
1515 However, a {'DOWN', MonitorRef, _, _, _} message can have been
1516 placed in the caller message queue before the call. It is there‐
1517 fore usually advisable to remove such a 'DOWN' message from the
1518 message queue after monitoring has been stopped. demonitor(Moni‐
1519 torRef, [flush]) can be used instead of demonitor(MonitorRef) if
1520 this cleanup is wanted.
1521 Note:
1523 Before Erlang/OTP R11B (ERTS 5.5) demonitor/1 behaved completely
1524 asynchronously, that is, the monitor was active until the "de‐
1525 monitor signal" reached the monitored entity. This had one unde‐
1526 sirable effect. You could never know when you were guaranteed
1527 not to receive a DOWN message because of the monitor.
1528 The current behavior can be viewed as two combined operations:
1530 asynchronously send a "demonitor signal" to the monitored entity
1531 and ignore any future results of the monitor.
1532 Failure: It is an error if MonitorRef refers to a monitoring
1535 started by another process. Not all such cases are cheap to
1536 check. If checking is cheap, the call fails with badarg, for ex‐
1537 ample if MonitorRef is a remote reference.
1538 demonitor(MonitorRef, OptionList) -> boolean()
1540 Types:
1542 MonitorRef = reference()
1544 OptionList = [Option]
1545 Option = flush | info
1546 The returned value is true unless info is part of OptionList.
1548 demonitor(MonitorRef, []) is equivalent to demonitor(Monitor‐
1550 Ref).
1551 Options:
1553 flush:
1555 Removes (one) {_, MonitorRef, _, _, _} message, if there is
1556 one, from the caller message queue after monitoring has been
1557 stopped.
1558 Calling demonitor(MonitorRef, [flush]) is equivalent to the
1560 following, but more efficient:
1561 demonitor(MonitorRef),
1563 receive
1564 {_, MonitorRef, _, _, _} ->
1565 true
1566 after 0 ->
1567 true
1568 end
1569 info:
1571 The returned value is one of the following:
1572 true:
1574 The monitor was found and removed. In this case, no 'DOWN'
1575 message corresponding to this monitor has been delivered
1576 and will not be delivered.
1577 false:
1579 The monitor was not found and could not be removed. This
1580 probably because someone already has placed a 'DOWN' mes‐
1581 sage corresponding to this monitor in the caller message
1582 queue.
1583 If option info is combined with option flush, false is re‐
1585 turned if a flush was needed, otherwise true.
1586 Note:
1588 More options can be added in a future release.
1589 Failures:
1592 badarg:
1594 If OptionList is not a list.
1595 badarg:
1597 If Option is an invalid option.
1598 badarg:
1600 The same failure as for demonitor/1.
1601 disconnect_node(Node) -> boolean() | ignored
1603 Types:
1605 Node = node()
1607 Forces the disconnection of a node. This appears to the node
1609 Node as if the local node has crashed. This BIF is mainly used
1610 in the Erlang network authentication protocols.
1611 Returns true if disconnection succeeds, otherwise false. If the
1613 local node is not alive, ignored is returned.
1614 Note:
1616 This function may return before nodedown messages have been de‐
1617 livered.
1618 erlang:display(Term) -> true
1621 Types:
1623 Term = term()
1625 Prints a text representation of Term on the standard output.
1627 Warning:
1629 This BIF is intended for debugging only.
1630 erlang:dist_ctrl_get_data(DHandle) -> {Size, Data} | Data | none
1633 Types:
1635 Size = integer() >= 0
1637 DHandle = dist_handle()
1638 Data = iovec()
1639 Get distribution channel data from the local node that is to be
1641 passed to the remote node. The distribution channel is identi‐
1642 fied by DHandle. If no data is available, the atom none is re‐
1643 turned. One can request to be informed by a message when more
1644 data is available by calling erlang:dist_ctrl_get_data_notifica‐
1645 tion(DHandle).
1646 The returned value when there are data available depends on the
1648 value of the get_size option configured on the distribution
1649 channel identified by DHandle. For more information see the doc‐
1650 umentation of the get_size option for the er‐
1651 lang:dist_ctrl_set_opt/3 function.
1652 Note:
1654 Only the process registered as distribution controller for the
1655 distribution channel identified by DHandle is allowed to call
1656 this function.
1657 This function is used when implementing an alternative distribu‐
1660 tion carrier using processes as distribution controllers. DHan‐
1661 dle is retrived via the callback f_handshake_complete. More in‐
1662 formation can be found in the documentation of ERTS User's Guide
1663 ➜ How to implement an Alternative Carrier for the Erlang Distri‐
1664 bution ➜ Distribution Module.
1665 erlang:dist_ctrl_get_opt(DHandle, Opt :: get_size) -> Value
1667 Types:
1669 DHandle = dist_handle()
1671 Value = boolean()
1672 Returns the value of the get_size option on the distribution
1674 channel identified by DHandle. For more information see the doc‐
1675 umentation of the get_size option for the er‐
1676 lang:dist_ctrl_set_opt/3 function.
1677 Note:
1679 Only the process registered as distribution controller for the
1680 distribution channel identified by DHandle is allowed to call
1681 this function.
1682 This function is used when implementing an alternative distribu‐
1685 tion carrier using processes as distribution controllers. DHan‐
1686 dle is retrived via the callback f_handshake_complete. More in‐
1687 formation can be found in the documentation of ERTS User's Guide
1688 ➜ How to implement an Alternative Carrier for the Erlang Distri‐
1689 bution ➜ Distribution Module.
1690 erlang:dist_ctrl_get_data_notification(DHandle) -> ok
1692 Types:
1694 DHandle = dist_handle()
1696 Request notification when more data is available to fetch using
1698 erlang:dist_ctrl_get_data(DHandle) for the distribution channel
1699 identified by DHandle. When more data is present, the caller
1700 will be sent the message dist_data. Once a dist_data messages
1701 has been sent, no more dist_data messages will be sent until the
1702 dist_ctrl_get_data_notification/1 function has been called
1703 again.
1704 Note:
1706 Only the process registered as distribution controller for the
1707 distribution channel identified by DHandle is allowed to call
1708 this function.
1709 This function is used when implementing an alternative distribu‐
1712 tion carrier using processes as distribution controllers. DHan‐
1713 dle is retrived via the callback f_handshake_complete. More in‐
1714 formation can be found in the documentation of ERTS User's Guide
1715 ➜ How to implement an Alternative Carrier for the Erlang Distri‐
1716 bution ➜ Distribution Module.
1717 erlang:dist_ctrl_input_handler(DHandle, InputHandler) -> ok
1719 Types:
1721 DHandle = dist_handle()
1723 InputHandler = pid()
1724 Register an alternate input handler process for the distribution
1726 channel identified by DHandle. Once this function has been
1727 called, InputHandler is the only process allowed to call er‐
1728 lang:dist_ctrl_put_data(DHandle, Data) with the DHandle identi‐
1729 fing this distribution channel.
1730 Note:
1732 Only the process registered as distribution controller for the
1733 distribution channel identified by DHandle is allowed to call
1734 this function.
1735 This function is used when implementing an alternative distribu‐
1738 tion carrier using processes as distribution controllers. DHan‐
1739 dle is retrived via the callback f_handshake_complete. More in‐
1740 formation can be found in the documentation of ERTS User's Guide
1741 ➜ How to implement an Alternative Carrier for the Erlang Distri‐
1742 bution ➜ Distribution Module.
1743 erlang:dist_ctrl_put_data(DHandle, Data) -> ok
1745 Types:
1747 DHandle = dist_handle()
1749 Data = iodata()
1750 Deliver distribution channel data from a remote node to the lo‐
1752 cal node.
1753 Note:
1755 Only the process registered as distribution controller for the
1756 distribution channel identified by DHandle is allowed to call
1757 this function unless an alternate input handler process has been
1758 registered using erlang:dist_ctrl_input_handler(DHandle, In‐
1759 putHandler). If an alternate input handler has been registered,
1760 only the registered input handler process is allowed to call
1761 this function.
1762 This function is used when implementing an alternative distribu‐
1765 tion carrier using processes as distribution controllers. DHan‐
1766 dle is retrived via the callback f_handshake_complete. More in‐
1767 formation can be found in the documentation of ERTS User's Guide
1768 ➜ How to implement an Alternative Carrier for the Erlang Distri‐
1769 bution ➜ Distribution Module.
1770 erlang:dist_ctrl_set_opt(DHandle, Opt :: get_size, Value) ->
1772 OldValue
1773 Types:
1775 DHandle = dist_handle()
1777 Value = OldValue = boolean()
1778 Sets the value of the get_size option on the distribution chan‐
1780 nel identified by DHandle. This option controls the return value
1781 of calls to erlang:dist_ctrl_get_data(DHandle) where DHandle
1782 equals DHandle used when setting this option. When the get_size
1783 option is:
1784 false:
1786 and there are distribution data available, a call to er‐
1787 lang:dist_ctrl_get_data(DHandle) will just return Data to
1788 pass over the channel. This is the default value of the
1789 get_size option.
1790 true:
1792 and there are distribution data available, a call to er‐
1793 lang:dist_ctrl_get_data(DHandle) will return Data to pass
1794 over the channel as well as the Size of Data in bytes. This
1795 is returned as a tuple on the form {Size, Data}.
1796 All options are set to default when a channel is closed.
1798 Note:
1800 Only the process registered as distribution controller for the
1801 distribution channel identified by DHandle is allowed to call
1802 this function.
1803 This function is used when implementing an alternative distribu‐
1806 tion carrier using processes as distribution controllers. DHan‐
1807 dle is retrived via the callback f_handshake_complete. More in‐
1808 formation can be found in the documentation of ERTS User's Guide
1809 ➜ How to implement an Alternative Carrier for the Erlang Distri‐
1810 bution ➜ Distribution Module.
1811 element(N, Tuple) -> term()
1813 Types:
1815 N = integer() >= 1
1817 1..tuple_size(Tuple)
1818 Tuple = tuple()
1819 Returns the Nth element (numbering from 1) of Tuple, for exam‐
1821 ple:
1822 > element(2, {a, b, c}).
1824 b
1825 Allowed in guard tests.
1827 erase() -> [{Key, Val}]
1829 Types:
1831 Key = Val = term()
1833 Returns the process dictionary and deletes it, for example:
1835 > put(key1, {1, 2, 3}),
1837 put(key2, [a, b, c]),
1838 erase().
1839 [{key1,{1,2,3}},{key2,[a,b,c]}]
1840 erase(Key) -> Val | undefined
1842 Types:
1844 Key = Val = term()
1846 Returns the value Val associated with Key and deletes it from
1848 the process dictionary. Returns undefined if no value is associ‐
1849 ated with Key. The average time complexity for the current im‐
1850 plementation of this function is O(1) and the worst case time
1851 complexity is O(N), where N is the number of items in the
1852 process dictionary. Example:
1853 > put(key1, {merry, lambs, are, playing}),
1855 X = erase(key1),
1856 {X, erase(key1)}.
1857 {{merry,lambs,are,playing},undefined}
1858 error(Reason) -> no_return()
1860 Types:
1862 Reason = term()
1864 Raises an exception of class error with the reason Reason. As
1866 evaluating this function causes an exception to be thrown, it
1867 has no return value.
1868 The intent of the exception class error is to signal that an un‐
1870 expected error has happened (for example, a function is called
1871 with a parameter that has an incorrect type). See the guide
1872 about errors and error handling for additional information. Ex‐
1873 ample:
1874 > catch error(foobar).
1876 {'EXIT',{foobar,[{shell,apply_fun,3,
1877 [{file,"shell.erl"},{line,906}]},
1878 {erl_eval,do_apply,6,[{file,"erl_eval.erl"},{line,677}]},
1879 {erl_eval,expr,5,[{file,"erl_eval.erl"},{line,430}]},
1880 {shell,exprs,7,[{file,"shell.erl"},{line,687}]},
1881 {shell,eval_exprs,7,[{file,"shell.erl"},{line,642}]},
1882 {shell,eval_loop,3,[{file,"shell.erl"},{line,627}]}]}}
1883 error(Reason, Args) -> no_return()
1886 Types:
1888 Reason = term()
1890 Args = [term()] | none
1891 Raises an exception of class error with the reason Reason. Args
1893 is expected to be the list of arguments for the current function
1894 or the atom none. If it is a list, it is used to provide the ar‐
1895 guments for the current function in the stack back-trace. If it
1896 is none, the arity of the calling function is used in the stack‐
1897 trace. As evaluating this function causes an exception to be
1898 raised, it has no return value.
1899 The intent of the exception class error is to signal that an un‐
1901 expected error has happened (for example, a function is called
1902 with a parameter that has an incorrect type). See the guide
1903 about errors and error handling for additional information. Ex‐
1904 ample:
1905 test.erl:
1907 -module(test).
1909 -export([example_fun/2]).
1910 example_fun(A1, A2) ->
1912 erlang:error(my_error, [A1, A2]).
1913 Erlang shell:
1916 6> c(test).
1918 {ok,test}
1919 7> test:example_fun(arg1,"this is the second argument").
1920 ** exception error: my_error
1921 in function test:example_fun/2
1922 called as test:example_fun(arg1,"this is the second argument")
1923 error(Reason, Args, Options) -> no_return()
1926 Types:
1928 Reason = term()
1930 Args = [term()] | none
1931 Options = [Option]
1932 Option = {error_info, ErrorInfoMap}
1933 ErrorInfoMap =
1934 #{cause => term(), module => module(), function =>
1935 atom()}
1936 Raises an exception of class error with the reason Reason. Args
1938 is expected to be the list of arguments for the current function
1939 or the atom none. If it is a list, it is used to provide the ar‐
1940 guments for the current function in the stack back-trace. If it
1941 is none, the arity of the calling function is used in the stack‐
1942 trace. As evaluating this function causes an exception to be
1943 raised, it has no return value.
1944 If the error_info option is given, the ErrorInfoMap will be in‐
1946 serted into the stacktrace. The information given in the Error‐
1947 InfoMap is to be used by error formatters such as erl_error to
1948 provide more context around an error.
1949 The default module of the ErrorInfoMap is the module that the
1951 call to error/3 is made. The default function is format_error.
1952 See format_error/2 for more details on how this Module:Func‐
1953 tion/2 is to be used
1954 The intent of the exception class error is to signal that an un‐
1956 expected error has happened (for example, a function is called
1957 with a parameter that has an incorrect type). See the guide
1958 about errors and error handling for additional information.
1959 exit(Reason) -> no_return()
1961 Types:
1963 Reason = term()
1965 Raises an exception of class exit with exit reason Reason. As
1967 evaluating this function causes an exception to be raised, it
1968 has no return value.
1969 The intent of the exception class exit is that the current
1971 process should be stopped (for example when a message telling a
1972 process to stop is received).
1973 This function differ from error/1,2,3 by causing an exception of
1975 a different class and by having a reason that does not include
1976 the list of functions from the call stack.
1977 See the guide about errors and error handling for additional in‐
1979 formation.
1980 Example:
1982 > exit(foobar).
1984 ** exception exit: foobar
1985 > catch exit(foobar).
1986 {'EXIT',foobar}
1987 Note:
1989 If a process calls exit(kill) and does not catch the exception,
1990 it will terminate with exit reason kill and also emit exit sig‐
1991 nals with exit reason kill (not killed) to all linked processes.
1992 Such exit signals with exit reason kill can be trapped by the
1993 linked processes. Note that this means that signals with exit
1994 reason kill behave differently depending on how they are sent
1995 because the signal will be untrappable if a process sends such a
1996 signal to another process with erlang:exit/2.
1997 exit(Pid, Reason) -> true
2000 Types:
2002 Pid = pid() | port()
2004 Reason = term()
2005 Sends an exit signal with exit reason Reason to the process or
2007 port identified by Pid.
2008 The following behavior applies if Reason is any term, except
2010 normal or kill, and P is the process or port identified by Pid:
2011 * If P is not trapping exits, P exits with exit reason Reason.
2013 * If P is trapping exits, the exit signal is transformed into
2015 a message {'EXIT', From, Reason}, where From is the process
2016 identifier of the process that sent the exit signal, and de‐
2017 livered to the message queue of P.
2018 The following behavior applies if Reason is the term normal and
2020 Pid is the identifier of a process P which is not the same as
2021 the process that invoked erlang:exit(Pid, normal) (the behavior
2022 when a process sends a signal with the normal reason to itself
2023 is described in the warning):
2024 * If P is trapping exits, the exit signal is transformed into
2026 a message {'EXIT', From, normal}, where From is the process
2027 identifier of the process that sent the exit signal, and de‐
2028 livered to P's message queue.
2029 * The signal has no effect if P is not trapping exits.
2031 If Reason is the atom kill, that is, if exit(Pid, kill) is
2033 called, an untrappable exit signal is sent to the process that
2034 is identified by Pid, which unconditionally exits with exit rea‐
2035 son killed. The exit reason is changed from kill to killed to
2036 hint to linked processes that the killed process got killed by a
2037 call to exit(Pid, kill).
2038 Note:
2040 The functions erlang:exit/1 and erlang:exit/2 are named simi‐
2041 larly but provide very different functionalities. The er‐
2042 lang:exit/1 function should be used when the intent is to stop
2043 the current process while erlang:exit/2 should be used when the
2044 intent is to send an exit signal to another process. Note also
2045 that erlang:exit/1 raises an exception that can be caught while
2046 erlang:exit/2 does not cause any exception to be raised.
2047 Warning:
2050 The only scenario that has not been covered by the description
2051 above is when a process P sends an exit signal with reason nor‐
2052 mal to itself, that is erlang:exit(self(), normal). The behavior
2053 in this scenario is as follows:
2054 * If P is trapping exits, the exit signal is transformed into
2056 a message {'EXIT', From, normal}, where From is P's process
2057 identifier, and delivered to P's message queue.
2058 * P exits with reason normal if P is not trapping exits.
2060 Note that the behavior described above is different from when a
2062 process sends an exit signal with reason normal to another
2063 process. This is arguably strange but this behavior is kept for
2064 backward compatibility reasons.
2065 erlang:external_size(Term) -> integer() >= 0
2068 Types:
2070 Term = term()
2072 Calculates, without doing the encoding, the maximum byte size
2074 for a term encoded in the Erlang external term format. The fol‐
2075 lowing condition applies always:
2076 > Size1 = byte_size(term_to_binary(Term)),
2078 > Size2 = erlang:external_size(Term),
2079 > true = Size1 =< Size2.
2080 true
2081 This is equivalent to a call to:
2083 erlang:external_size(Term, [])
2085 erlang:external_size(Term, Options) -> integer() >= 0
2087 Types:
2089 Term = term()
2091 Options = [{minor_version, Version :: integer() >= 0}]
2092 Calculates, without doing the encoding, the maximum byte size
2094 for a term encoded in the Erlang external term format. The fol‐
2095 lowing condition applies always:
2096 > Size1 = byte_size(term_to_binary(Term, Options)),
2098 > Size2 = erlang:external_size(Term, Options),
2099 > true = Size1 =< Size2.
2100 true
2101 Option {minor_version, Version} specifies how floats are en‐
2103 coded. For a detailed description, see term_to_binary/2.
2104 float(Number) -> float()
2106 Types:
2108 Number = number()
2110 Returns a float by converting Number to a float, for example:
2112 > float(55).
2114 55.0
2115 Allowed in guard tests.
2117 Note:
2119 If used on the top level in a guard, it tests whether the argu‐
2120 ment is a floating point number; for clarity, use is_float/1 in‐
2121 stead.
2122 When float/1 is used in an expression in a guard, such as
2124 'float(A) == 4.0', it converts a number as described earlier.
2125 float_to_binary(Float) -> binary()
2128 Types:
2130 Float = float()
2132 The same as float_to_binary(Float,[{scientific,20}]).
2134 float_to_binary(Float, Options) -> binary()
2136 Types:
2138 Float = float()
2140 Options = [Option]
2141 Option =
2142 {decimals, Decimals :: 0..253} |
2143 {scientific, Decimals :: 0..249} |
2144 compact
2145 Returns a binary corresponding to the text representation of
2147 Float using fixed decimal point formatting. Options behaves in
2148 the same way as float_to_list/2. Examples:
2149 > float_to_binary(7.12, [{decimals, 4}]).
2151 <<"7.1200">>
2152 > float_to_binary(7.12, [{decimals, 4}, compact]).
2153 <<"7.12">>
2154 > float_to_binary(7.12, [{scientific, 3}]).
2155 <<"7.120e+00">>
2156 float_to_list(Float) -> string()
2158 Types:
2160 Float = float()
2162 The same as float_to_list(Float,[{scientific,20}]).
2164 float_to_list(Float, Options) -> string()
2166 Types:
2168 Float = float()
2170 Options = [Option]
2171 Option =
2172 {decimals, Decimals :: 0..253} |
2173 {scientific, Decimals :: 0..249} |
2174 compact
2175 Returns a string corresponding to the text representation of
2177 Float using fixed decimal point formatting.
2178 Available options:
2180 * If option decimals is specified, the returned value contains
2182 at most Decimals number of digits past the decimal point. If
2183 the number does not fit in the internal static buffer of 256
2184 bytes, the function throws badarg.
2185 * If option compact is specified, the trailing zeros at the
2187 end of the list are truncated. This option is only meaning‐
2188 ful together with option decimals.
2189 * If option scientific is specified, the float is formatted
2191 using scientific notation with Decimals digits of precision.
2192 * If Options is [], the function behaves as float_to_list/1.
2194 Examples:
2196 > float_to_list(7.12, [{decimals, 4}]).
2198 "7.1200"
2199 > float_to_list(7.12, [{decimals, 4}, compact]).
2200 "7.12"
2201 > float_to_list(7.12, [{scientific, 3}]).
2202 "7.120e+00"
2203 > float_to_list(0.1+0.2)
2204 "3.00000000000000044409e-01"
2205 In the last example, float_to_list(0.1+0.2) evaluates to
2208 "3.00000000000000044409e-01". The reason for this is explained
2209 in Representation of Floating Point Numbers.
2210 floor(Number) -> integer()
2212 Types:
2214 Number = number()
2216 Returns the largest integer not greater than Number. For exam‐
2218 ple:
2219 > floor(-10.5).
2221 -11
2222 Allowed in guard tests.
2224 erlang:fun_info(Fun) -> [{Item, Info}]
2226 Types:
2228 Fun = function()
2230 Item =
2231 arity | env | index | name | module | new_index |
2232 new_uniq |
2233 pid | type | uniq
2234 Info = term()
2235 Returns a list with information about the fun Fun. Each list el‐
2237 ement is a tuple. The order of the tuples is undefined, and more
2238 tuples can be added in a future release.
2239 Warning:
2241 This BIF is mainly intended for debugging, but it can sometimes
2242 be useful in library functions that need to verify, for example,
2243 the arity of a fun.
2244 Two types of funs have slightly different semantics:
2247 * A fun created by fun M:F/A is called an external fun. Call‐
2249 ing it will always call the function F with arity A in the
2250 latest code for module M. Notice that module M does not even
2251 need to be loaded when the fun fun M:F/A is created.
2252 * All other funs are called local. When a local fun is called,
2254 the same version of the code that created the fun is called
2255 (even if a newer version of the module has been loaded).
2256 The following elements are always present in the list for both
2258 local and external funs:
2259 {type, Type}:
2261 Type is local or external.
2262 {module, Module}:
2264 Module (an atom) is the module name.
2265 If Fun is a local fun, Module is the module in which the fun
2267 is defined.
2268 If Fun is an external fun, Module is the module that the fun
2270 refers to.
2271 {name, Name}:
2273 Name (an atom) is a function name.
2274 If Fun is a local fun, Name is the name of the local func‐
2276 tion that implements the fun. (This name was generated by
2277 the compiler, and is only of informational use. As it is a
2278 local function, it cannot be called directly.) If no code is
2279 currently loaded for the fun, [] is returned instead of an
2280 atom.
2281 If Fun is an external fun, Name is the name of the exported
2283 function that the fun refers to.
2284 {arity, Arity}:
2286 Arity is the number of arguments that the fun is to be
2287 called with.
2288 {env, Env}:
2290 Env (a list) is the environment or free variables for the
2291 fun. For external funs, the returned list is always empty.
2292 The following elements are only present in the list if Fun is
2294 local:
2295 {pid, Pid}:
2297 Pid is the process identifier of the process that originally
2298 created the fun.
2299 It might point to the init process if the Fun was statically
2301 allocated when module was loaded (this optimisation is per‐
2302 formed for local functions that do not capture the environ‐
2303 ment).
2304 {index, Index}:
2306 Index (an integer) is an index into the module fun table.
2307 {new_index, Index}:
2309 Index (an integer) is an index into the module fun table.
2310 {new_uniq, Uniq}:
2312 Uniq (a binary) is a unique value for this fun. It is calcu‐
2313 lated from the compiled code for the entire module.
2314 {uniq, Uniq}:
2316 Uniq (an integer) is a unique value for this fun. As from
2317 Erlang/OTP R15, this integer is calculated from the compiled
2318 code for the entire module. Before Erlang/OTP R15, this in‐
2319 teger was based on only the body of the fun.
2320 erlang:fun_info(Fun, Item) -> {Item, Info}
2322 Types:
2324 Fun = function()
2326 Item = fun_info_item()
2327 Info = term()
2328 fun_info_item() =
2329 arity | env | index | name | module | new_index | new_uniq |
2330 pid | type | uniq
2331 Returns information about Fun as specified by Item, in the form
2333 {Item,Info}.
2334 For any fun, Item can be any of the atoms module, name, arity,
2336 env, or type.
2337 For a local fun, Item can also be any of the atoms index,
2339 new_index, new_uniq, uniq, and pid. For an external fun, the
2340 value of any of these items is always the atom undefined.
2341 See erlang:fun_info/1.
2343 erlang:fun_to_list(Fun) -> String :: string()
2345 Types:
2347 Fun = function()
2349 Returns String that represents the code that created Fun.
2351 String has the following form, if Fun was created by a fun ex‐
2353 pression of the form fun ModuleName:FuncName/Arity:
2354 "fun ModuleName:FuncName/Arity"
2356 The form of String when Fun is created from other types of fun
2358 expressions differs depending on if the fun expression was exe‐
2359 cuted while executing compiled code or if the fun expression was
2360 executed while executing uncompiled code (uncompiled escripts,
2361 the Erlang shell, and other code executed by the erl_eval mod‐
2362 ule):
2363 compiled code:
2365 "#Fun<M.I.U>", where M, I and U correspond to the values
2366 named module, index and uniq in the result of er‐
2367 lang:fun_info(Fun).
2368 uncompiled code:
2370 All funs created from fun expressions in uncompiled code
2371 with the same arity are mapped to the same list by
2372 fun_to_list/1.
2373 Note:
2375 Generally, one can not use fun_to_list/1 to check if two funs
2376 are equal as fun_to_list/1 does not take the fun's environment
2377 into account. See erlang:fun_info/1 for how to get the environ‐
2378 ment of a fun.
2379 Note:
2382 The output of fun_to_list/1 can differ between Erlang implemen‐
2383 tations and may change in future versions.
2384 Examples:
2387 -module(test).
2389 -export([add/1, add2/0, fun_tuple/0]).
2390 add(A) -> fun(B) -> A + B end.
2391 add2() -> fun add/1.
2392 fun_tuple() -> {fun() -> 1 end, fun() -> 1 end}.
2393 > {fun test:add/1, test:add2()}.
2396 {fun test:add/1,#Fun<test.1.107738983>}
2397 Explanation: fun test:add/1 is upgradable but test:add2() is not
2400 upgradable.
2401 > {test:add(1), test:add(42)}.
2403 {#Fun<test.0.107738983>,#Fun<test.0.107738983>}
2404 Explanation: test:add(1) and test:add(42) has the same string
2407 representation as the environment is not taken into account.
2408 >test:fun_tuple().
2410 {#Fun<test.2.107738983>,#Fun<test.3.107738983>}
2411 Explanation: The string representations differ because the funs
2414 come from different fun experssions.
2415 > {fun() -> 1 end, fun() -> 1 end}. >
2417 {#Fun<erl_eval.45.97283095>,#Fun<erl_eval.45.97283095>}
2418 Explanation: All funs created from fun expressions of this form
2421 in uncompiled code with the same arity are mapped to the same
2422 list by fun_to_list/1.
2423 erlang:function_exported(Module, Function, Arity) -> boolean()
2425 Types:
2427 Module = module()
2429 Function = atom()
2430 Arity = arity()
2431 Returns true if the module Module is current and contains an ex‐
2433 ported function Function/Arity, or if there is a BIF (a built-in
2434 function implemented in C) with the specified name, otherwise
2435 returns false.
2436 garbage_collect() -> true
2438 Forces an immediate garbage collection of the executing process.
2440 The function is not to be used unless it has been noticed (or
2441 there are good reasons to suspect) that the spontaneous garbage
2442 collection will occur too late or not at all.
2443 Warning:
2445 Improper use can seriously degrade system performance.
2446 garbage_collect(Pid) -> GCResult
2449 Types:
2451 Pid = pid()
2453 GCResult = boolean()
2454 The same as garbage_collect(Pid, []).
2456 garbage_collect(Pid, OptionList) -> GCResult | async
2458 Types:
2460 Pid = pid()
2462 RequestId = term()
2463 Option = {async, RequestId} | {type, major | minor}
2464 OptionList = [Option]
2465 GCResult = boolean()
2466 Garbage collects the node local process identified by Pid.
2468 Option:
2470 {async, RequestId}:
2472 The function garbage_collect/2 returns the value async imme‐
2473 diately after the request has been sent. When the request
2474 has been processed, the process that called this function is
2475 passed a message on the form {garbage_collect, RequestId,
2476 GCResult}.
2477 {type, 'major' | 'minor'}:
2479 Triggers garbage collection of requested type. Default value
2480 is 'major', which would trigger a fullsweep GC. The option
2481 'minor' is considered a hint and may lead to either minor or
2482 major GC run.
2483 If Pid equals self(), and no async option has been passed, the
2485 garbage collection is performed at once, that is, the same as
2486 calling garbage_collect/0. Otherwise a request for garbage col‐
2487 lection is sent to the process identified by Pid, and will be
2488 handled when appropriate. If no async option has been passed,
2489 the caller blocks until GCResult is available and can be re‐
2490 turned.
2491 GCResult informs about the result of the garbage collection re‐
2493 quest as follows:
2494 true:
2496 The process identified by Pid has been garbage collected.
2497 false:
2499 No garbage collection was performed, as the process identi‐
2500 fied by Pid terminated before the request could be satis‐
2501 fied.
2502 Notice that the same caveats apply as for garbage_collect/0.
2504 Failures:
2506 badarg:
2508 If Pid is not a node local process identifier.
2509 badarg:
2511 If OptionList is an invalid list of options.
2512 get() -> [{Key, Val}]
2514 Types:
2516 Key = Val = term()
2518 Returns the process dictionary as a list of {Key, Val} tuples.
2520 The items in the returned list can be in any order. Example:
2521 > put(key1, merry),
2523 put(key2, lambs),
2524 put(key3, {are, playing}),
2525 get().
2526 [{key1,merry},{key2,lambs},{key3,{are,playing}}]
2527 get(Key) -> Val | undefined
2529 Types:
2531 Key = Val = term()
2533 Returns the value Val associated with Key in the process dictio‐
2535 nary, or undefined if Key does not exist. The expected time com‐
2536 plexity for the current implementation of this function is O(1)
2537 and the worst case time complexity is O(N), where N is the num‐
2538 ber of items in the process dictionary. Example:
2539 > put(key1, merry),
2541 put(key2, lambs),
2542 put({any, [valid, term]}, {are, playing}),
2543 get({any, [valid, term]}).
2544 {are,playing}
2545 erlang:get_cookie() -> Cookie | nocookie
2547 Types:
2549 Cookie = atom()
2551 Returns the magic cookie of the local node if the node is alive,
2553 otherwise the atom nocookie.
2554 erlang:get_cookie(Node) -> Cookie | nocookie
2556 Types:
2558 Node = node()
2560 Cookie = atom()
2561 Returns the magic cookie for node Node if the local node is
2563 alive, otherwise the atom nocookie.
2564 get_keys() -> [Key]
2566 Types:
2568 Key = term()
2570 Returns a list of all keys present in the process dictionary.
2572 The items in the returned list can be in any order. Example:
2573 > put(dog, {animal,1}),
2575 put(cow, {animal,2}),
2576 put(lamb, {animal,3}),
2577 get_keys().
2578 [dog,cow,lamb]
2579 get_keys(Val) -> [Key]
2581 Types:
2583 Val = Key = term()
2585 Returns a list of keys that are associated with the value Val in
2587 the process dictionary. The items in the returned list can be in
2588 any order. Example:
2589 > put(mary, {1, 2}),
2591 put(had, {1, 2}),
2592 put(a, {1, 2}),
2593 put(little, {1, 2}),
2594 put(dog, {1, 3}),
2595 put(lamb, {1, 2}),
2596 get_keys({1, 2}).
2597 [mary,had,a,little,lamb]
2598 group_leader() -> pid()
2600 Returns the process identifier of the group leader for the
2602 process evaluating the function.
2603 Every process is a member of some process group and all groups
2605 have a group leader. All I/O from the group is channeled to the
2606 group leader. When a new process is spawned, it gets the same
2607 group leader as the spawning process. Initially, at system
2608 startup, init is both its own group leader and the group leader
2609 of all processes.
2610 group_leader(GroupLeader, Pid) -> true
2612 Types:
2614 GroupLeader = Pid = pid()
2616 Sets the group leader of Pid to GroupLeader. Typically, this is
2618 used when a process started from a certain shell is to have an‐
2619 other group leader than init.
2620 The group leader should be rarely changed in applications with a
2622 supervision tree, because OTP assumes the group leader of their
2623 processes is their application master.
2624 Setting the group leader follows the signal ordering guarentees
2626 described in the Processes Chapter in the Erlang Reference Man‐
2627 ual .
2628 See also group_leader/0 and OTP design principles related to
2630 starting and stopping applications.
2631 halt() -> no_return()
2633 The same as halt(0, []). Example:
2635 > halt().
2637 os_prompt%
2638 halt(Status) -> no_return()
2640 Types:
2642 Status = integer() >= 0 | abort | string()
2644 The same as halt(Status, []). Example:
2646 > halt(17).
2648 os_prompt% echo $?
2649 17
2650 os_prompt%
2651 halt(Status, Options) -> no_return()
2653 Types:
2655 Status = integer() >= 0 | abort | string()
2657 Options = [Option]
2658 Option = {flush, boolean()}
2659 Status must be a non-negative integer, a string, or the atom
2661 abort. Halts the Erlang runtime system. Has no return value. De‐
2662 pending on Status, the following occurs:
2663 integer():
2665 The runtime system exits with integer value Status as status
2666 code to the calling environment (OS).
2667 Note:
2669 On many platforms, the OS supports only status codes 0-255. A
2670 too large status code is truncated by clearing the high bits.
2671 string():
2674 An Erlang crash dump is produced with Status as slogan. Then
2675 the runtime system exits with status code 1. The string will
2676 be truncated if longer than 200 characters.
2677 Note:
2679 Before ERTS 9.1 (OTP-20.1) only code points in the range 0-255
2680 was accepted in the string. Now any unicode string is valid.
2681 abort:
2684 The runtime system aborts producing a core dump, if that is
2685 enabled in the OS.
2686 For integer Status, the Erlang runtime system closes all ports
2688 and allows async threads to finish their operations before exit‐
2689 ing. To exit without such flushing, use Option as {flush,false}.
2690 For statuses string() and abort, option flush is ignored and
2692 flushing is not done.
2693 hd(List) -> term()
2695 Types:
2697 List = [term(), ...]
2699 Returns the head of List, that is, the first element, for exam‐
2701 ple:
2702 > hd([1,2,3,4,5]).
2704 1
2705 Allowed in guard tests.
2707 Failure: badarg if List is the empty list [].
2709 erlang:hibernate(Module, Function, Args) -> no_return()
2711 Types:
2713 Module = module()
2715 Function = atom()
2716 Args = [term()]
2717 Puts the calling process into a wait state where its memory al‐
2719 location has been reduced as much as possible. This is useful if
2720 the process does not expect to receive any messages soon.
2721 The process is awaken when a message is sent to it, and control
2723 resumes in Module:Function with the arguments specified by Args
2724 with the call stack emptied, meaning that the process terminates
2725 when that function returns. Thus erlang:hibernate/3 never re‐
2726 turns to its caller. The resume function Module:Function/Arity
2727 must be exported (Arity =:= length(Args)).
2728 If the process has any message in its message queue, the process
2730 is awakened immediately in the same way as described earlier.
2731 In more technical terms, erlang:hibernate/3 discards the call
2733 stack for the process, and then garbage collects the process.
2734 After this, all live data is in one continuous heap. The heap is
2735 then shrunken to the exact same size as the live data that it
2736 holds (even if that size is less than the minimum heap size for
2737 the process).
2738 If the size of the live data in the process is less than the
2740 minimum heap size, the first garbage collection occurring after
2741 the process is awakened ensures that the heap size is changed to
2742 a size not smaller than the minimum heap size.
2743 Notice that emptying the call stack means that any surrounding
2745 catch is removed and must be re-inserted after hibernation. One
2746 effect of this is that processes started using proc_lib (also
2747 indirectly, such as gen_server processes), are to use
2748 proc_lib:hibernate/3 instead, to ensure that the exception han‐
2749 dler continues to work when the process wakes up.
2750 erlang:insert_element(Index, Tuple1, Term) -> Tuple2
2752 Types:
2754 Index = integer() >= 1
2756 1..tuple_size(Tuple1) + 1
2757 Tuple1 = Tuple2 = tuple()
2758 Term = term()
2759 Returns a new tuple with element Term inserted at position Index
2761 in tuple Tuple1. All elements from position Index and upwards
2762 are pushed one step higher in the new tuple Tuple2. Example:
2763 > erlang:insert_element(2, {one, two, three}, new).
2765 {one,new,two,three}
2766 integer_to_binary(Integer) -> binary()
2768 Types:
2770 Integer = integer()
2772 Returns a binary corresponding to the text representation of In‐
2774 teger, for example:
2775 > integer_to_binary(77).
2777 <<"77">>
2778 integer_to_binary(Integer, Base) -> binary()
2780 Types:
2782 Integer = integer()
2784 Base = 2..36
2785 Returns a binary corresponding to the text representation of In‐
2787 teger in base Base, for example:
2788 > integer_to_binary(1023, 16).
2790 <<"3FF">>
2791 integer_to_list(Integer) -> string()
2793 Types:
2795 Integer = integer()
2797 Returns a string corresponding to the text representation of In‐
2799 teger, for example:
2800 > integer_to_list(77).
2802 "77"
2803 integer_to_list(Integer, Base) -> string()
2805 Types:
2807 Integer = integer()
2809 Base = 2..36
2810 Returns a string corresponding to the text representation of In‐
2812 teger in base Base, for example:
2813 > integer_to_list(1023, 16).
2815 "3FF"
2816 iolist_size(Item) -> integer() >= 0
2818 Types:
2820 Item = iolist() | binary()
2822 Returns an integer, that is the size in bytes, of the binary
2824 that would be the result of iolist_to_binary(Item), for example:
2825 > iolist_size([1,2|<<3,4>>]).
2827 4
2828 iolist_to_binary(IoListOrBinary) -> binary()
2830 Types:
2832 IoListOrBinary = iolist() | binary()
2834 Returns a binary that is made from the integers and binaries in
2836 IoListOrBinary, for example:
2837 > Bin1 = <<1,2,3>>.
2839 <<1,2,3>>
2840 > Bin2 = <<4,5>>.
2841 <<4,5>>
2842 > Bin3 = <<6>>.
2843 <<6>>
2844 > iolist_to_binary([Bin1,1,[2,3,Bin2],4|Bin3]).
2845 <<1,2,3,1,2,3,4,5,4,6>>
2846 erlang:iolist_to_iovec(IoListOrBinary) -> iovec()
2848 Types:
2850 IoListOrBinary = iolist() | binary()
2852 Returns an iovec that is made from the integers and binaries in
2854 IoListOrBinary. This function is useful when you want to flatten
2855 an iolist but you do not need a single binary. This can be use‐
2856 ful for passing the data to nif functions such as enif_in‐
2857 spect_iovec or do more efficient message passing. The advantage
2858 of using this function over iolist_to_binary/1 is that it does
2859 not have to copy off-heap binaries. Example:
2860 > Bin1 = <<1,2,3>>.
2862 <<1,2,3>>
2863 > Bin2 = <<4,5>>.
2864 <<4,5>>
2865 > Bin3 = <<6>>.
2866 <<6>>
2867 %% If you pass small binaries and integers it works as iolist_to_binary
2868 > erlang:iolist_to_iovec([Bin1,1,[2,3,Bin2],4|Bin3]).
2869 [<<1,2,3,1,2,3,4,5,4,6>>]
2870 %% If you pass larger binaries, they are split and returned in a form
2871 %% optimized for calling the C function writev.
2872 > erlang:iolist_to_iovec([<<1>>,<<2:8096>>,<<3:8096>>]).
2873 [<<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,
2874 0,...>>,
2875 <<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,
2876 ...>>,
2877 <<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,...>>]
2878 is_alive() -> boolean()
2880 Returns true if the local node is alive (that is, if the node
2882 can be part of a distributed system), otherwise false. A node is
2883 alive if it is started with:
2884 * "erl -name LONGNAME" or,
2886 * "erl -sname SHORTNAME".
2888 A node can also be alive if it has got a name from a call to
2890 net_kernel:start/1 and has not been stopped by a call to
2891 net_kernel:stop/0.
2892 is_atom(Term) -> boolean()
2894 Types:
2896 Term = term()
2898 Returns true if Term is an atom, otherwise false.
2900 Allowed in guard tests.
2902 is_binary(Term) -> boolean()
2904 Types:
2906 Term = term()
2908 Returns true if Term is a binary, otherwise false.
2910 A binary always contains a complete number of bytes.
2912 Allowed in guard tests.
2914 is_bitstring(Term) -> boolean()
2916 Types:
2918 Term = term()
2920 Returns true if Term is a bitstring (including a binary), other‐
2922 wise false.
2923 Allowed in guard tests.
2925 is_boolean(Term) -> boolean()
2927 Types:
2929 Term = term()
2931 Returns true if Term is the atom true or the atom false (that
2933 is, a boolean). Otherwise returns false.
2934 Allowed in guard tests.
2936 erlang:is_builtin(Module, Function, Arity) -> boolean()
2938 Types:
2940 Module = module()
2942 Function = atom()
2943 Arity = arity()
2944 This BIF is useful for builders of cross-reference tools.
2946 Returns true if Module:Function/Arity is a BIF implemented in C,
2948 otherwise false.
2949 is_float(Term) -> boolean()
2951 Types:
2953 Term = term()
2955 Returns true if Term is a floating point number, otherwise
2957 false.
2958 Allowed in guard tests.
2960 is_function(Term) -> boolean()
2962 Types:
2964 Term = term()
2966 Returns true if Term is a fun, otherwise false.
2968 Allowed in guard tests.
2970 is_function(Term, Arity) -> boolean()
2972 Types:
2974 Term = term()
2976 Arity = arity()
2977 Returns true if Term is a fun that can be applied with Arity
2979 number of arguments, otherwise false.
2980 Allowed in guard tests.
2982 is_integer(Term) -> boolean()
2984 Types:
2986 Term = term()
2988 Returns true if Term is an integer, otherwise false.
2990 Allowed in guard tests.
2992 is_list(Term) -> boolean()
2994 Types:
2996 Term = term()
2998 Returns true if Term is a list with zero or more elements, oth‐
3000 erwise false.
3001 Allowed in guard tests.
3003 is_map(Term) -> boolean()
3005 Types:
3007 Term = term()
3009 Returns true if Term is a map, otherwise false.
3011 Allowed in guard tests.
3013 is_map_key(Key, Map) -> boolean()
3015 Types:
3017 Key = term()
3019 Map = map()
3020 Returns true if map Map contains Key and returns false if it
3022 does not contain the Key.
3023 The call fails with a {badmap,Map} exception if Map is not a
3025 map.
3026 Example:
3028 > Map = #{"42" => value}.
3030 #{"42" => value}
3031 > is_map_key("42",Map).
3032 true
3033 > is_map_key(value,Map).
3034 false
3035 Allowed in guard tests.
3037 is_number(Term) -> boolean()
3039 Types:
3041 Term = term()
3043 Returns true if Term is an integer or a floating point number.
3045 Otherwise returns false.
3046 Allowed in guard tests.
3048 is_pid(Term) -> boolean()
3050 Types:
3052 Term = term()
3054 Returns true if Term is a process identifier, otherwise false.
3056 Allowed in guard tests.
3058 is_port(Term) -> boolean()
3060 Types:
3062 Term = term()
3064 Returns true if Term is a port identifier, otherwise false.
3066 Allowed in guard tests.
3068 is_process_alive(Pid) -> boolean()
3070 Types:
3072 Pid = pid()
3074 Pid must refer to a process at the local node.
3076 Returns true if the process exists and is alive, that is, is not
3078 exiting and has not exited. Otherwise returns false.
3079 If process P1 calls is_process_alive(P2Pid) it is guaranteed
3081 that all signals, sent from P1 to P2 (P2 is the process with
3082 identifier P2Pid) before the call, will be delivered to P2 be‐
3083 fore the aliveness of P2 is checked. This guarantee means that
3084 one can use is_process_alive/1 to let a process P1 wait until a
3085 process P2, which has got an exit signal with reason kill from
3086 P1, is killed. Example:
3087 exit(P2Pid, kill),
3089 % P2 might not be killed
3090 is_process_alive(P2Pid),
3091 % P2 is not alive (the call above always return false)
3092 See the documentation about signals and erlang:exit/2 for more
3095 information about signals and exit singnals.
3096 is_record(Term, RecordTag) -> boolean()
3098 Types:
3100 Term = term()
3102 RecordTag = atom()
3103 Returns true if Term is a tuple and its first element is Record‐
3105 Tag. Otherwise returns false.
3106 Note:
3108 Normally the compiler treats calls to is_record/2 especially. It
3109 emits code to verify that Term is a tuple, that its first ele‐
3110 ment is RecordTag, and that the size is correct. However, if
3111 RecordTag is not a literal atom, the BIF is_record/2 is called
3112 instead and the size of the tuple is not verified.
3113 Allowed in guard tests, if RecordTag is a literal atom.
3116 is_record(Term, RecordTag, Size) -> boolean()
3118 Types:
3120 Term = term()
3122 RecordTag = atom()
3123 Size = integer() >= 0
3124 RecordTag must be an atom.
3126 Returns true if Term is a tuple, its first element is RecordTag,
3128 and its size is Size. Otherwise returns false.
3129 Allowed in guard tests if RecordTag is a literal atom and Size
3131 is a literal integer.
3132 Note:
3134 This BIF is documented for completeness. Usually is_record/2 is
3135 to be used.
3136 is_reference(Term) -> boolean()
3139 Types:
3141 Term = term()
3143 Returns true if Term is a reference, otherwise false.
3145 Allowed in guard tests.
3147 is_tuple(Term) -> boolean()
3149 Types:
3151 Term = term()
3153 Returns true if Term is a tuple, otherwise false.
3155 Allowed in guard tests.
3157 length(List) -> integer() >= 0
3159 Types:
3161 List = [term()]
3163 Returns the length of List, for example:
3165 > length([1,2,3,4,5,6,7,8,9]).
3167 9
3168 Allowed in guard tests.
3170 link(PidOrPort) -> true
3172 Types:
3174 PidOrPort = pid() | port()
3176 Sets up and activates a link between the calling process and an‐
3178 other process or a port identified by PidOrPort. We will from
3179 here on call the identified process or port linkee. If the lin‐
3180 kee is a port, it must reside on the same node as the caller.
3181 If one of the participants of a link terminates, it will send an
3183 exit signal to the other participant. The exit signal will con‐
3184 tain the exit reason of the terminated participant. Other cases
3185 when exit signals are triggered due to a link are when no linkee
3186 exist (noproc exit reason) and when the connection between
3187 linked processes on different nodes is lost or cannot be estab‐
3188 lished (noconnection exit reason).
3189 An existing link can be removed by calling unlink/1. For more
3191 information on links and exit signals due to links, see the Pro‐
3192 cesses chapter in the Erlang Reference Manual :
3193 * Links
3195 * Sending Exit Signals
3197 * Receiving Exit Signals
3199 For historical reasons, link/1 has a strange semi-synchronous
3201 behavior when it is "cheap" to check if the linkee exists or
3202 not, and the caller does not trap exits. If the above is true
3203 and the linkee does not exist, link/1 will raise a noproc error
3204 exception. The expected behavior would instead have been that
3205 link/1 returned true, and the caller later was sent an exit sig‐
3206 nal with noproc exit reason, but this is unfortunately not the
3207 case. The noproc exception is not to be confused with an exit
3208 signal with exit reason noproc. Currently it is "cheap" to check
3209 if the linkee exists when it is supposed to reside on the same
3210 node as the calling process.
3211 The link setup and activation is performed asynchronously. If
3213 the link already exists, or if the caller attempts to create a
3214 link to itself, nothing is done. A detailed description of the
3215 link protocol can be found in the Distribution Protocol chapter
3216 of the ERTS User's Guide .
3217 Failure:
3219 * badarg if PidOrPort does not identify a process or a node
3221 local port.
3222 * noproc linkee does not exist and it is "cheap" to check if
3224 it exists as described above.
3225 list_to_atom(String) -> atom()
3227 Types:
3229 String = string()
3231 Returns the atom whose text representation is String.
3233 As from Erlang/OTP 20, String may contain any Unicode character.
3235 Earlier versions allowed only ISO-latin-1 characters as the im‐
3236 plementation did not allow Unicode characters above 255.
3237 Note:
3239 The number of characters that are permitted in an atom name is
3240 limited. The default limits can be found in the efficiency
3241 guide (section Advanced).
3242 Note:
3245 There is configurable limit on how many atoms that can exist and
3246 atoms are not garbage collected. Therefore, it is recommended to
3247 consider if list_to_existing_atom/1 is a better option than
3248 list_to_atom/1. The default limits can be found in the effi‐
3249 ciency guide (section Advanced).
3250 Example:
3253 > list_to_atom("Erlang").
3255 list_to_binary(IoList) -> binary()
3257 Types:
3259 IoList = iolist()
3261 Returns a binary that is made from the integers and binaries in
3263 IoList, for example:
3264 > Bin1 = <<1,2,3>>.
3266 <<1,2,3>>
3267 > Bin2 = <<4,5>>.
3268 <<4,5>>
3269 > Bin3 = <<6>>.
3270 <<6>>
3271 > list_to_binary([Bin1,1,[2,3,Bin2],4|Bin3]).
3272 <<1,2,3,1,2,3,4,5,4,6>>
3273 list_to_bitstring(BitstringList) -> bitstring()
3275 Types:
3277 BitstringList = bitstring_list()
3279 bitstring_list() =
3280 maybe_improper_list(byte() | bitstring() | bitstring_list(),
3281 bitstring() | [])
3282 Returns a bitstring that is made from the integers and bit‐
3284 strings in BitstringList. (The last tail in BitstringList is al‐
3285 lowed to be a bitstring.) Example:
3286 > Bin1 = <<1,2,3>>.
3288 <<1,2,3>>
3289 > Bin2 = <<4,5>>.
3290 <<4,5>>
3291 > Bin3 = <<6,7:4>>.
3292 <<6,7:4>>
3293 > list_to_bitstring([Bin1,1,[2,3,Bin2],4|Bin3]).
3294 <<1,2,3,1,2,3,4,5,4,6,7:4>>
3295 list_to_existing_atom(String) -> atom()
3297 Types:
3299 String = string()
3301 Returns the atom whose text representation is String, but only
3303 if there already exists such atom. An atom exists if it has been
3304 created by the run-time system by either loading code or creat‐
3305 ing a term in which the atom is part.
3306 Failure: badarg if there does not already exist an atom whose
3308 text representation is String.
3309 Note:
3311 Note that the compiler may optimize away atoms. For example, the
3312 compiler will rewrite atom_to_list(some_atom) to "some_atom". If
3313 that expression is the only mention of the atom some_atom in the
3314 containing module, the atom will not be created when the module
3315 is loaded, and a subsequent call to list_to_exist‐
3316 ing_atom("some_atom") will fail.
3317 list_to_float(String) -> float()
3320 Types:
3322 String = string()
3324 Returns the float whose text representation is String, for exam‐
3326 ple:
3327 > list_to_float("2.2017764e+0").
3329 2.2017764
3330 The float string format is the same as the format for Erlang
3332 float literals except for that underscores are not permitted.
3333 Failure: badarg if String contains a bad representation of a
3335 float.
3336 list_to_integer(String) -> integer()
3338 Types:
3340 String = string()
3342 Returns an integer whose text representation is String, for ex‐
3344 ample:
3345 > list_to_integer("123").
3347 123
3348 > list_to_integer("-123").
3350 -123
3351 > list_to_integer("+123234982304982309482093833234234").
3353 123234982304982309482093833234234
3354 String must contain at least one digit character and can have an
3356 optional prefix consisting of a single "+" or "-" character
3357 (that is, String must match the regular expression
3358 "^[+-]?[0-9]+$").
3359 Failure: badarg if String contains a bad representation of an
3361 integer.
3362 list_to_integer(String, Base) -> integer()
3364 Types:
3366 String = string()
3368 Base = 2..36
3369 Returns an integer whose text representation in base Base is
3371 String, for example:
3372 > list_to_integer("3FF", 16).
3374 1023
3375 > list_to_integer("+3FF", 16).
3377 1023
3378 > list_to_integer("3ff", 16).
3380 1023
3381 > list_to_integer("3fF", 16).
3383 1023
3384 > list_to_integer("-3FF", 16).
3386 -1023
3387 For example, when Base is 16, String must match the regular ex‐
3389 pression "^[+-]?([0-9]|[A-F]|[a-f])+$".
3390 Failure: badarg if String contains a bad representation of an
3392 integer.
3393 list_to_pid(String) -> pid()
3395 Types:
3397 String = string()
3399 Returns a process identifier whose text representation is a
3401 String, for example:
3402 > list_to_pid("<0.4.1>").
3404 <0.4.1>
3405 Failure: badarg if String contains a bad representation of a
3407 process identifier.
3408 Warning:
3410 This BIF is intended for debugging and is not to be used in ap‐
3411 plication programs.
3412 list_to_port(String) -> port()
3415 Types:
3417 String = string()
3419 Returns a port identifier whose text representation is a String,
3421 for example:
3422 > list_to_port("#Port<0.4>").
3424 #Port<0.4>
3425 Failure: badarg if String contains a bad representation of a
3427 port identifier.
3428 Warning:
3430 This BIF is intended for debugging and is not to be used in ap‐
3431 plication programs.
3432 list_to_ref(String) -> reference()
3435 Types:
3437 String = string()
3439 Returns a reference whose text representation is a String, for
3441 example:
3442 > list_to_ref("#Ref<0.4192537678.4073193475.71181>").
3444 #Ref<0.4192537678.4073193475.71181>
3445 Failure: badarg if String contains a bad representation of a
3447 reference.
3448 Warning:
3450 This BIF is intended for debugging and is not to be used in ap‐
3451 plication programs.
3452 list_to_tuple(List) -> tuple()
3455 Types:
3457 List = [term()]
3459 Returns a tuple corresponding to List, for example
3461 > list_to_tuple([share, ['Ericsson_B', 163]]).
3463 {share, ['Ericsson_B', 163]}
3464 List can contain any Erlang terms.
3466 load_module(Module, Binary) -> {module, Module} | {error, Reason}
3468 Types:
3470 Module = module()
3472 Binary = binary()
3473 Reason = badfile | not_purged | on_load
3474 If Binary contains the object code for module Module, this BIF
3476 loads that object code. If the code for module Module already
3477 exists, all export references are replaced so they point to the
3478 newly loaded code. The previously loaded code is kept in the
3479 system as old code, as there can still be processes executing
3480 that code.
3481 Returns either {module, Module}, or {error, Reason} if loading
3483 fails. Reason is one of the following:
3484 badfile:
3486 The object code in Binary has an incorrect format or the ob‐
3487 ject code contains code for another module than Module.
3488 not_purged:
3490 Binary contains a module that cannot be loaded because old
3491 code for this module already exists.
3492 on_load:
3494 The code in Binary contains an on_load declaration that must
3495 be executed before Binary can become the current code. Any
3496 previous current code for Module will remain until the
3497 on_load call has finished.
3498 Warning:
3500 This BIF is intended for the code server (see code(3)) and is
3501 not to be used elsewhere.
3502 erlang:load_nif(Path, LoadInfo) -> ok | Error
3505 Types:
3507 Path = string()
3509 LoadInfo = term()
3510 Error = {error, {Reason, Text :: string()}}
3511 Reason =
3512 load_failed | bad_lib | load | reload | upgrade |
3513 old_code
3514 Loads and links a dynamic library containing native implemented
3516 functions (NIFs) for a module. Path is a file path to the share‐
3517 able object/dynamic library file minus the OS-dependent file ex‐
3518 tension (.so for Unix and .dll for Windows). Notice that on most
3519 OSs the library has to have a different name on disc when an up‐
3520 grade of the nif is done. If the name is the same, but the con‐
3521 tents differ, the old library may be loaded instead. For infor‐
3522 mation on how to implement a NIF library, see erl_nif(3).
3523 LoadInfo can be any term. It is passed on to the library as part
3525 of the initialization. A good practice is to include a module
3526 version number to support future code upgrade scenarios.
3527 The call to load_nif/2 must be made directly from the Erlang
3529 code of the module that the NIF library belongs to. It returns
3530 either ok, or {error,{Reason,Text}} if loading fails. Reason is
3531 one of the following atoms while Text is a human readable string
3532 that can give more information about the failure:
3533 load_failed:
3535 The OS failed to load the NIF library.
3536 bad_lib:
3538 The library did not fulfill the requirements as a NIF li‐
3539 brary of the calling module.
3540 load | upgrade:
3542 The corresponding library callback was unsuccessful.
3543 reload:
3545 A NIF library is already loaded for this module instance.
3546 The previously deprecated reload feature was removed in OTP
3547 20.
3548 old_code:
3550 The call to load_nif/2 was made from the old code of a mod‐
3551 ule that has been upgraded; this is not allowed.
3552 erlang:loaded() -> [Module]
3554 Types:
3556 Module = module()
3558 Returns a list of all loaded Erlang modules (current and old
3560 code), including preloaded modules.
3561 See also code(3).
3563 erlang:localtime() -> DateTime
3565 Types:
3567 DateTime = calendar:datetime()
3569 Returns the current local date and time, {{Year, Month, Day},
3571 {Hour, Minute, Second}}, for example:
3572 > erlang:localtime().
3574 {{1996,11,6},{14,45,17}}
3575 The time zone and Daylight Saving Time correction depend on the
3577 underlying OS. The return value is based on the OS System Time.
3578 erlang:localtime_to_universaltime(Localtime) -> Universaltime
3580 Types:
3582 Localtime = Universaltime = calendar:datetime()
3584 Converts local date and time to Universal Time Coordinated
3586 (UTC), if supported by the underlying OS. Otherwise no conver‐
3587 sion is done and Localtime is returned. Example:
3588 > erlang:localtime_to_universaltime({{1996,11,6},{14,45,17}}).
3590 {{1996,11,6},{13,45,17}}
3591 Failure: badarg if Localtime denotes an invalid date and time.
3593 erlang:localtime_to_universaltime(Localtime, IsDst) ->
3595 Universaltime
3596 Types:
3598 Localtime = Universaltime = calendar:datetime()
3600 IsDst = true | false | undefined
3601 Converts local date and time to Universal Time Coordinated (UTC)
3603 as erlang:localtime_to_universaltime/1, but the caller decides
3604 if Daylight Saving Time is active.
3605 If IsDst == true, Localtime is during Daylight Saving Time, if
3607 IsDst == false it is not. If IsDst == undefined, the underlying
3608 OS can guess, which is the same as calling erlang:local‐
3609 time_to_universaltime(Localtime).
3610 Examples:
3612 > erlang:localtime_to_universaltime({{1996,11,6},{14,45,17}}, true).
3614 {{1996,11,6},{12,45,17}}
3615 > erlang:localtime_to_universaltime({{1996,11,6},{14,45,17}}, false).
3616 {{1996,11,6},{13,45,17}}
3617 > erlang:localtime_to_universaltime({{1996,11,6},{14,45,17}}, undefined).
3618 {{1996,11,6},{13,45,17}}
3619 Failure: badarg if Localtime denotes an invalid date and time.
3621 make_ref() -> reference()
3623 Returns a unique reference. The reference is unique among con‐
3625 nected nodes.
3626 Warning:
3628 Before OTP-23 when a node is restarted multiple times with the
3629 same node name, references created on a newer node can be mis‐
3630 taken for a reference created on an older node with the same
3631 node name.
3632 erlang:make_tuple(Arity, InitialValue) -> tuple()
3635 Types:
3637 Arity = arity()
3639 InitialValue = term()
3640 Creates a new tuple of the specified Arity, where all elements
3642 are InitialValue, for example:
3643 > erlang:make_tuple(4, []).
3645 {[],[],[],[]}
3646 erlang:make_tuple(Arity, DefaultValue, InitList) -> tuple()
3648 Types:
3650 Arity = arity()
3652 DefaultValue = term()
3653 InitList = [{Position :: integer() >= 1, term()}]
3654 Creates a tuple of size Arity, where each element has value De‐
3656 faultValue, and then fills in values from InitList. Each list
3657 element in InitList must be a two-tuple, where the first element
3658 is a position in the newly created tuple and the second element
3659 is any term. If a position occurs more than once in the list,
3660 the term corresponding to the last occurrence is used. Example:
3661 > erlang:make_tuple(5, [], [{2,ignored},{5,zz},{2,aa}]).
3663 {[],aa,[],[],zz}
3664 map_get(Key, Map) -> Value
3666 Types:
3668 Map = map()
3670 Key = Value = any()
3671 Returns value Value associated with Key if Map contains Key.
3673 The call fails with a {badmap,Map} exception if Map is not a
3675 map, or with a {badkey,Key} exception if no value is associated
3676 with Key.
3677 Example:
3679 > Key = 1337,
3681 Map = #{42 => value_two,1337 => "value one","a" => 1},
3682 map_get(Key,Map).
3683 "value one"
3684 Allowed in guard tests.
3686 map_size(Map) -> integer() >= 0
3688 Types:
3690 Map = map()
3692 Returns an integer, which is the number of key-value pairs in
3694 Map, for example:
3695 > map_size(#{a=>1, b=>2, c=>3}).
3697 3
3698 Allowed in guard tests.
3700 erlang:match_spec_test(MatchAgainst, MatchSpec, Type) ->
3702 TestResult
3703 Types:
3705 MatchAgainst = [term()] | tuple()
3707 MatchSpec = term()
3708 Type = table | trace
3709 TestResult =
3710 {ok, term(), [return_trace], [{error | warning,
3711 string()}]} |
3712 {error, [{error | warning, string()}]}
3713 Tests a match specification used in calls to ets:select/2 and
3715 erlang:trace_pattern/3. The function tests both a match specifi‐
3716 cation for "syntactic" correctness and runs the match specifica‐
3717 tion against the object. If the match specification contains er‐
3718 rors, the tuple {error, Errors} is returned, where Errors is a
3719 list of natural language descriptions of what was wrong with the
3720 match specification.
3721 If Type is table, the object to match against is to be a tuple.
3723 The function then returns {ok,Result,[],Warnings}, where Result
3724 is what would have been the result in a real ets:select/2 call,
3725 or false if the match specification does not match the object
3726 tuple.
3727 If Type is trace, the object to match against is to be a list.
3729 The function returns {ok, Result, Flags, Warnings}, where Result
3730 is one of the following:
3731 * true if a trace message is to be emitted
3733 * false if a trace message is not to be emitted
3735 * The message term to be appended to the trace message
3737 Flags is a list containing all the trace flags to be enabled,
3739 currently this is only return_trace.
3740 This is a useful debugging and test tool, especially when writ‐
3742 ing complicated match specifications.
3743 See also ets:test_ms/2.
3745 max(Term1, Term2) -> Maximum
3747 Types:
3749 Term1 = Term2 = Maximum = term()
3751 Returns the largest of Term1 and Term2. If the terms compare
3753 equal with the == operator, Term1 is returned.
3754 The Expressions section contains descriptions of the == opera‐
3756 tor and how terms are ordered.
3757 Examples:
3759 > max(1, 2).
3761 2
3762 > max(1.0, 1).
3764 1.0
3765 > max(1, 1.0).
3767 1
3768 > max("abc", "b").
3770 "b"
3771 erlang:md5(Data) -> Digest
3773 Types:
3775 Data = iodata()
3777 Digest = binary()
3778 Computes an MD5 message digest from Data, where the length of
3780 the digest is 128 bits (16 bytes). Data is a binary or a list of
3781 small integers and binaries.
3782 For more information about MD5, see RFC 1321 - The MD5 Message-
3784 Digest Algorithm.
3785 Warning:
3787 The MD5 Message-Digest Algorithm is not considered safe for
3788 code-signing or software-integrity purposes.
3789 erlang:md5_final(Context) -> Digest
3792 Types:
3794 Context = Digest = binary()
3796 Finishes the update of an MD5 Context and returns the computed
3798 MD5 message digest.
3799 erlang:md5_init() -> Context
3801 Types:
3803 Context = binary()
3805 Creates an MD5 context, to be used in the following calls to
3807 md5_update/2.
3808 erlang:md5_update(Context, Data) -> NewContext
3810 Types:
3812 Context = binary()
3814 Data = iodata()
3815 NewContext = binary()
3816 Update an MD5 Context with Data and returns a NewContext.
3818 erlang:memory() -> [{Type, Size}]
3820 Types:
3822 Type = memory_type()
3824 Size = integer() >= 0
3825 memory_type() =
3826 total | processes | processes_used | system | atom |
3827 atom_used | binary | code | ets
3828 Returns a list with information about memory dynamically allo‐
3830 cated by the Erlang emulator. Each list element is a tuple
3831 {Type, Size}. The first element Type is an atom describing mem‐
3832 ory type. The second element Size is the memory size in bytes.
3833 Memory types:
3835 total:
3837 The total amount of memory currently allocated. This is the
3838 same as the sum of the memory size for processes and system.
3839 processes:
3841 The total amount of memory currently allocated for the Er‐
3842 lang processes.
3843 processes_used:
3845 The total amount of memory currently used by the Erlang pro‐
3846 cesses. This is part of the memory presented as processes
3847 memory.
3848 system:
3850 The total amount of memory currently allocated for the emu‐
3851 lator that is not directly related to any Erlang process.
3852 Memory presented as processes is not included in this mem‐
3853 ory. instrument(3) can be used to get a more detailed break‐
3854 down of what memory is part of this type.
3855 atom:
3857 The total amount of memory currently allocated for atoms.
3858 This memory is part of the memory presented as system mem‐
3859 ory.
3860 atom_used:
3862 The total amount of memory currently used for atoms. This
3863 memory is part of the memory presented as atom memory.
3864 binary:
3866 The total amount of memory currently allocated for binaries.
3867 This memory is part of the memory presented as system mem‐
3868 ory.
3869 code:
3871 The total amount of memory currently allocated for Erlang
3872 code. This memory is part of the memory presented as system
3873 memory.
3874 ets:
3876 The total amount of memory currently allocated for ETS ta‐
3877 bles. This memory is part of the memory presented as system
3878 memory.
3879 maximum:
3881 The maximum total amount of memory allocated since the emu‐
3882 lator was started. This tuple is only present when the emu‐
3883 lator is run with instrumentation.
3884 For information on how to run the emulator with instrumenta‐
3886 tion, see instrument(3) and/or erl(1).
3887 Note:
3889 The system value is not complete. Some allocated memory that is
3890 to be part of this value is not.
3891 When the emulator is run with instrumentation, the system value
3893 is more accurate, but memory directly allocated for malloc (and
3894 friends) is still not part of the system value. Direct calls to
3895 malloc are only done from OS-specific runtime libraries and per‐
3896 haps from user-implemented Erlang drivers that do not use the
3897 memory allocation functions in the driver interface.
3898 As the total value is the sum of processes and system, the error
3900 in system propagates to the total value.
3901 The different amounts of memory that are summed are not gathered
3903 atomically, which introduces an error in the result.
3904 The different values have the following relation to each other.
3907 Values beginning with an uppercase letter is not part of the re‐
3908 sult.
3909 total = processes + system
3911 processes = processes_used + ProcessesNotUsed
3912 system = atom + binary + code + ets + OtherSystem
3913 atom = atom_used + AtomNotUsed
3914 RealTotal = processes + RealSystem
3915 RealSystem = system + MissedSystem
3916 More tuples in the returned list can be added in a future re‐
3918 lease.
3919 Note:
3921 The total value is supposed to be the total amount of memory dy‐
3922 namically allocated by the emulator. Shared libraries, the code
3923 of the emulator itself, and the emulator stacks are not supposed
3924 to be included. That is, the total value is not supposed to be
3925 equal to the total size of all pages mapped to the emulator.
3926 Also, because of fragmentation and prereservation of memory ar‐
3928 eas, the size of the memory segments containing the dynamically
3929 allocated memory blocks can be much larger than the total size
3930 of the dynamically allocated memory blocks.
3931 Note:
3934 As from ERTS 5.6.4, erlang:memory/0 requires that all erts_al‐
3935 loc(3) allocators are enabled (default behavior).
3936 Failure: notsup if an erts_alloc(3) allocator has been disabled.
3939 erlang:memory(Type :: memory_type()) -> integer() >= 0
3941 erlang:memory(TypeList :: [memory_type()]) ->
3943 [{memory_type(), integer() >= 0}]
3944 Types:
3946 memory_type() =
3948 total | processes | processes_used | system | atom |
3949 atom_used | binary | code | ets
3950 Returns the memory size in bytes allocated for memory of type
3952 Type. The argument can also be specified as a list of mem‐
3953 ory_type() atoms, in which case a corresponding list of {mem‐
3954 ory_type(), Size :: integer >= 0} tuples is returned.
3955 Note:
3957 As from ERTS 5.6.4, erlang:memory/1 requires that all erts_al‐
3958 loc(3) allocators are enabled (default behavior).
3959 Failures:
3962 badarg:
3964 If Type is not one of the memory types listed in the de‐
3965 scription of erlang:memory/0.
3966 badarg:
3968 If maximum is passed as Type and the emulator is not run in
3969 instrumented mode.
3970 notsup:
3972 If an erts_alloc(3) allocator has been disabled.
3973 See also erlang:memory/0.
3975 min(Term1, Term2) -> Minimum
3977 Types:
3979 Term1 = Term2 = Minimum = term()
3981 Returns the smallest of Term1 and Term2. If the terms compare
3983 equal with the == operator, Term1 is returned.
3984 The Expressions section contains descriptions of the == opera‐
3986 tor and how terms are ordered.
3987 Examples:
3989 > min(1, 2).
3991 1
3992 > min(1.0, 1).
3994 1.0
3995 > min(1, 1.0).
3997 1
3998 > min("abc", "b").
4000 "abc"
4001 module_loaded(Module) -> boolean()
4003 Types:
4005 Module = module()
4007 Returns true if the module Module is loaded, otherwise false. It
4009 does not attempt to load the module.
4010 Warning:
4012 This BIF is intended for the code server (see code(3)) and is
4013 not to be used elsewhere.
4014 monitor(Type :: process, Item :: monitor_process_identifier()) ->
4017 MonitorRef
4018 monitor(Type :: port, Item :: monitor_port_identifier()) ->
4020 MonitorRef
4021 monitor(Type :: time_offset, Item :: clock_service) -> MonitorRef
4023 Types:
4025 MonitorRef = reference()
4027 registered_name() = atom()
4028 registered_process_identifier() =
4029 registered_name() | {registered_name(), node()}
4030 monitor_process_identifier() =
4031 pid() | registered_process_identifier()
4032 monitor_port_identifier() = port() | registered_name()
4033 Sends a monitor request of type Type to the entity identified by
4035 Item. If the monitored entity does not exist or it changes moni‐
4036 tored state, the caller of monitor/2 is notified by a message on
4037 the following format:
4038 {Tag, MonitorRef, Type, Object, Info}
4040 Note:
4042 The monitor request is an asynchronous signal. That is, it takes
4043 time before the signal reaches its destination.
4044 Type can be one of the following atoms: process, port or
4047 time_offset.
4048 A process or port monitor is triggered only once, after that it
4050 is removed from both monitoring process and the monitored en‐
4051 tity. Monitors are fired when the monitored process or port ter‐
4052 minates, does not exist at the moment of creation, or if the
4053 connection to it is lost. If the connection to it is lost, we do
4054 not know if it still exists. The monitoring is also turned off
4055 when demonitor/1 is called.
4056 A process or port monitor by name resolves the RegisteredName to
4058 pid() or port() only once at the moment of monitor instantia‐
4059 tion, later changes to the name registration will not affect the
4060 existing monitor.
4061 When a process or port monitor is triggered, a 'DOWN' message is
4063 sent that has the following pattern:
4064 {'DOWN', MonitorRef, Type, Object, Info}
4066 In the monitor message MonitorRef and Type are the same as de‐
4068 scribed earlier, and:
4069 Object:
4071 The monitored entity, which triggered the event. When moni‐
4072 toring a process or a local port, Object will be equal to
4073 the pid() or port() that was being monitored. When monitor‐
4074 ing process or port by name, Object will have format {Regis‐
4075 teredName, Node} where RegisteredName is the name which has
4076 been used with monitor/2 call and Node is local or remote
4077 node name (for ports monitored by name, Node is always local
4078 node name).
4079 Info:
4081 Either the exit reason of the process, noproc (process or
4082 port did not exist at the time of monitor creation), or no‐
4083 connection (no connection to the node where the monitored
4084 process resides).
4085 Monitoring a process:
4087 Creates monitor between the current process and another
4088 process identified by Item, which can be a pid() (local or
4089 remote), an atom RegisteredName or a tuple {RegisteredName,
4090 Node} for a registered process, located elsewhere.
4091 Note:
4093 Before ERTS 10.0 (OTP 21.0), monitoring a process could fail
4094 with badarg if the monitored process resided on a primitive
4095 node (such as erl_interface or jinterface), where remote
4096 process monitoring is not implemented.
4097 Now, such a call to monitor will instead succeed and a monitor
4099 is created. But the monitor will only supervise the connec‐
4100 tion. That is, a {'DOWN', _, process, _, noconnection} is the
4101 only message that may be received, as the primitive node have
4102 no way of reporting the status of the monitored process.
4103 Monitoring a port:
4106 Creates monitor between the current process and a port iden‐
4107 tified by Item, which can be a port() (only local), an atom
4108 RegisteredName or a tuple {RegisteredName, Node} for a reg‐
4109 istered port, located on this node. Note, that attempt to
4110 monitor a remote port will result in badarg.
4111 Monitoring a time_offset:
4113 Monitors changes in time offset between Erlang monotonic
4114 time and Erlang system time. One valid Item exists in combi‐
4115 nation with the time_offset Type, namely the atom clock_ser‐
4116 vice. Notice that the atom clock_service is not the regis‐
4117 tered name of a process. In this case it serves as an iden‐
4118 tifier of the runtime system internal clock service at cur‐
4119 rent runtime system instance.
4120 The monitor is triggered when the time offset is changed.
4122 This either if the time offset value is changed, or if the
4123 offset is changed from preliminary to final during finaliza‐
4124 tion of the time offset when the single time warp mode is
4125 used. When a change from preliminary to final time offset is
4126 made, the monitor is triggered once regardless of whether
4127 the time offset value was changed or not.
4128 If the runtime system is in multi time warp mode, the time
4130 offset is changed when the runtime system detects that the
4131 OS system time has changed. The runtime system does, how‐
4132 ever, not detect this immediately when it occurs. A task
4133 checking the time offset is scheduled to execute at least
4134 once a minute, so under normal operation this is to be de‐
4135 tected within a minute, but during heavy load it can take
4136 longer time.
4137 The monitor is not automatically removed after it has been
4139 triggered. That is, repeated changes of the time offset
4140 trigger the monitor repeatedly.
4141 When the monitor is triggered a 'CHANGE' message is sent to
4143 the monitoring process. A 'CHANGE' message has the following
4144 pattern:
4145 {'CHANGE', MonitorRef, Type, Item, NewTimeOffset}
4147 where MonitorRef, Type, and Item are the same as described
4149 above, and NewTimeOffset is the new time offset.
4150 When the 'CHANGE' message has been received you are guaran‐
4152 teed not to retrieve the old time offset when calling er‐
4153 lang:time_offset(). Notice that you can observe the change
4154 of the time offset when calling erlang:time_offset() before
4155 you get the 'CHANGE' message.
4156 Making several calls to monitor/2 for the same Item and/or Type
4158 is not an error; it results in as many independent monitoring
4159 instances.
4160 The monitor functionality is expected to be extended. That is,
4162 other Types and Items are expected to be supported in a future
4163 release.
4164 Note:
4166 If or when monitor/2 is extended, other possible values for Tag,
4167 Object, and Info in the monitor message will be introduced.
4168 monitor(Type :: process,
4171 Item :: monitor_process_identifier(),
4172 Opts :: [monitor_option()]) ->
4173 MonitorRef
4174 monitor(Type :: port,
4176 Item :: monitor_port_identifier(),
4177 Opts :: [monitor_option()]) ->
4178 MonitorRef
4179 monitor(Type :: time_offset,
4181 Item :: clock_service,
4182 Opts :: [monitor_option()]) ->
4183 MonitorRef
4184 Types:
4186 MonitorRef = reference()
4188 registered_name() = atom()
4189 registered_process_identifier() =
4190 registered_name() | {registered_name(), node()}
4191 monitor_process_identifier() =
4192 pid() | registered_process_identifier()
4193 monitor_port_identifier() = port() | registered_name()
4194 Provides an option list for modification of monitoring function‐
4196 ality provided by monitor/2. The Type and Item arguments have
4197 the same meaning as when passed to monitor/2. Currently avail‐
4198 able options:
4199 {alias, UnaliasOpt}:
4201 The returned monitor reference will also become an alias for
4202 the calling process. That is, the returned reference can be
4203 used for sending messages to the calling process. See also
4204 alias/0. The UnaliasOpt determines how the alias should be
4205 deactivated.
4206 explicit_unalias:
4208 Only an explicit call to unalias/1 will deactivate the
4209 alias.
4210 demonitor:
4212 The alias will be automatically deactivated when the moni‐
4213 tor is removed. This either via an explicit call to demon‐
4214 itor/1 or when it is automatically removed at the same
4215 time as a 'DOWN' message is delivered due to the monitor.
4216 The alias can also still be deactivated via a call to una‐
4217 lias/1.
4218 reply_demonitor:
4220 The alias will be automatically deactivated when the moni‐
4221 tor is removed (see demonitor option above) or a reply
4222 message sent via the alias is received. When a reply mes‐
4223 sage is received via the alias the monitor will also be
4224 automatically removed. This is useful in client/server
4225 scenarios when a client monitors the server and will get
4226 the reply via the alias. Once the response is received
4227 both the alias and the monitor will be automatically re‐
4228 moved regardless of whether the response is a reply or a
4229 'DOWN' message. The alias can also still be deactivated
4230 via a call to unalias/1. Note that if the alias is removed
4231 using the unalias/1 BIF, the monitor will still be left
4232 active.
4233 Example:
4235 server() ->
4237 receive
4238 {request, AliasReqId, Request} ->
4239 Result = perform_request(Request),
4240 AliasReqId ! {reply, AliasReqId, Result}
4241 end,
4242 server().
4243 client(ServerPid, Request) ->
4245 AliasMonReqId = monitor(process, ServerPid, [{alias, reply_demonitor}]),
4246 ServerPid ! {request, AliasMonReqId, Request},
4247 %% Alias as well as monitor will be automatically deactivated if we
4248 %% receive a reply or a 'DOWN' message since we used 'reply_demonitor'
4249 %% as unalias option...
4250 receive
4251 {reply, AliasMonReqId, Result} ->
4252 Result;
4253 {'DOWN', AliasMonReqId, process, ServerPid, ExitReason} ->
4254 error(ExitReason)
4255 end.
4256 Note that both the server and the client in this example
4259 must be executing on at least OTP 24 systems in order for
4260 this to work.
4261 For more information on process aliases see the Process
4263 Aliases section of the Erlang Reference Manual .
4264 {tag, UserDefinedTag}:
4266 Replace the default Tag with UserDefinedTag in the monitor
4267 message delivered when the monitor is triggered. For exam‐
4268 ple, when monitoring a process, the 'DOWN' tag in the down
4269 message will be replaced by UserDefinedTag.
4270 An example of how the {tag, UserDefinedTag} option can be
4272 used in order to enable the new selective receive optimiza‐
4273 tion, introduced in OTP 24, when making multiple requests to
4274 different servers:
4275 server() ->
4277 receive
4278 {request, From, ReqId, Request} ->
4279 Result = perform_request(Request),
4280 From ! {reply, self(), ReqId, Result}
4281 end,
4282 server().
4283 client(ServerPids, Request) when is_list(ServerPids) ->
4285 ReqId = make_ref(),
4286 lists:foreach(fun (ServerPid) ->
4287 _ = monitor(process, ServerPid,
4288 [{tag, {'DOWN', ReqId}}]),
4289 ServerPid ! {request, self(), ReqId, Request}
4290 end,
4291 ServerPids),
4292 receive_replies(ReqId, length(ServerPids), []).
4293 receive_replies(_ReqId, 0, Acc) ->
4295 Acc;
4296 receive_replies(ReqId, N, Acc) ->
4297 %% The compiler will detect that we match on the 'ReqId'
4298 %% reference in all clauses, and will enable the selective
4299 %% receive optimization which makes the receive able to
4300 %% skip past all messages present in the message queue at
4301 %% the time when the 'ReqId' reference was created...
4302 Res = receive
4303 {reply, ServerPid, ReqId, Result} ->
4304 %% Here we typically would have deactivated the
4305 %% monitor by a call to demonitor(Mon, [flush]) but
4306 %% we ignore this in this example for simplicity...
4307 {ok, ServerPid, Result};
4308 {{'DOWN', ReqId}, _Mon, process, ServerPid, ExitReason} ->
4309 {error, ServerPid, ExitReason}
4310 end,
4311 receive_replies(ReqId, N-1, [Res | Acc]).
4312 In order for this example to work as intended, the client
4315 must be executing on at least an OTP 24 system, but the
4316 servers may execute on older systems.
4317 monitor_node(Node, Flag) -> true
4319 Types:
4321 Node = node()
4323 Flag = boolean()
4324 Monitor the status of the node Node. If Flag is true, monitoring
4326 is turned on. If Flag is false, monitoring is turned off.
4327 Making several calls to monitor_node(Node, true) for the same
4329 Node is not an error; it results in as many independent monitor‐
4330 ing instances.
4331 If Node fails or does not exist, the message {nodedown, Node} is
4333 delivered to the process. If a process has made two calls to
4334 monitor_node(Node, true) and Node terminates, two nodedown mes‐
4335 sages are delivered to the process. If there is no connection to
4336 Node, an attempt is made to create one. If this fails, a node‐
4337 down message is delivered.
4338 The delivery of the nodedown signal is not ordered with respect
4340 to other link or monitor signals from the node that goes down.
4341 If you need a guarantee that all signals from the remote node
4342 has been delivered before the nodedown signal is sent, you
4343 should use net_kernel:monitor_nodes/1.
4344 Nodes connected through hidden connections can be monitored as
4346 any other nodes.
4347 Failure: notalive if the local node is not alive.
4349 erlang:monitor_node(Node, Flag, Options) -> true
4351 Types:
4353 Node = node()
4355 Flag = boolean()
4356 Options = [Option]
4357 Option = allow_passive_connect
4358 Behaves as monitor_node/2 except that it allows an extra option
4360 to be specified, namely allow_passive_connect. This option al‐
4361 lows the BIF to wait the normal network connection time-out for
4362 the monitored node to connect itself, even if it cannot be ac‐
4363 tively connected from this node (that is, it is blocked). The
4364 state where this can be useful can only be achieved by using the
4365 Kernel option dist_auto_connect once. If that option is not
4366 used, option allow_passive_connect has no effect.
4367 Note:
4369 Option allow_passive_connect is used internally and is seldom
4370 needed in applications where the network topology and the Kernel
4371 options in effect are known in advance.
4372 Failure: badarg if the local node is not alive or the option
4375 list is malformed.
4376 erlang:monotonic_time() -> integer()
4378 Returns the current Erlang monotonic time in native time unit.
4380 This is a monotonically increasing time since some unspecified
4381 point in time.
4382 Note:
4384 This is a monotonically increasing time, but not a strictly
4385 monotonically increasing time. That is, consecutive calls to er‐
4386 lang:monotonic_time/0 can produce the same result.
4387 Different runtime system instances will use different unspeci‐
4389 fied points in time as base for their Erlang monotonic clocks.
4390 That is, it is pointless comparing monotonic times from differ‐
4391 ent runtime system instances. Different runtime system instances
4392 can also place this unspecified point in time different relative
4393 runtime system start. It can be placed in the future (time at
4394 start is a negative value), the past (time at start is a posi‐
4395 tive value), or the runtime system start (time at start is
4396 zero). The monotonic time at runtime system start can be re‐
4397 trieved by calling erlang:system_info(start_time).
4398 erlang:monotonic_time(Unit) -> integer()
4401 Types:
4403 Unit = time_unit()
4405 Returns the current Erlang monotonic time converted into the
4407 Unit passed as argument.
4408 Same as calling erlang:convert_time_unit(erlang:mono‐
4410 tonic_time(), native, Unit), however optimized for commonly used
4411 Units.
4412 erlang:nif_error(Reason) -> no_return()
4414 Types:
4416 Reason = term()
4418 Works exactly like error/1, but Dialyzer thinks that this BIF
4420 will return an arbitrary term. When used in a stub function for
4421 a NIF to generate an exception when the NIF library is not
4422 loaded, Dialyzer does not generate false warnings.
4423 erlang:nif_error(Reason, Args) -> no_return()
4425 Types:
4427 Reason = term()
4429 Args = [term()]
4430 Works exactly like error/2, but Dialyzer thinks that this BIF
4432 will return an arbitrary term. When used in a stub function for
4433 a NIF to generate an exception when the NIF library is not
4434 loaded, Dialyzer does not generate false warnings.
4435 node() -> Node
4437 Types:
4439 Node = node()
4441 Returns the name of the local node. If the node is not alive,
4443 nonode@nohost is returned instead.
4444 Allowed in guard tests.
4446 node(Arg) -> Node
4448 Types:
4450 Arg = pid() | port() | reference()
4452 Node = node()
4453 Returns the node where Arg originates. Arg can be a process
4455 identifier, a reference, or a port. If Arg originates from the
4456 local node and the local node is not alive, nonode@nohost is re‐
4457 turned.
4458 Allowed in guard tests.
4460 nodes() -> Nodes
4462 Types:
4464 Nodes = [node()]
4466 Returns a list of all nodes connected to this node through nor‐
4468 mal connections (that is, hidden nodes are not listed). Same as
4469 nodes(visible).
4470 nodes(Arg) -> Nodes
4472 Types:
4474 Arg = NodeType | [NodeType]
4476 NodeType = visible | hidden | connected | this | known
4477 Nodes = [node()]
4478 Returns a list of nodes according to the argument specified. The
4480 returned result, when the argument is a list, is the list of
4481 nodes satisfying the disjunction(s) of the list elements.
4482 NodeTypes:
4484 visible:
4486 Nodes connected to this node through normal connections.
4487 hidden:
4489 Nodes connected to this node through hidden connections.
4490 connected:
4492 All nodes connected to this node.
4493 this:
4495 This node.
4496 known:
4498 Nodes that are known to this node. That is, connected nodes
4499 and nodes referred to by process identifiers, port identi‐
4500 fiers, and references located on this node. The set of known
4501 nodes is garbage collected. Notice that this garbage collec‐
4502 tion can be delayed. For more information, see erlang:sys‐
4503 tem_info(delayed_node_table_gc).
4504 Some equalities: [node()] = nodes(this), nodes(connected) =
4506 nodes([visible, hidden]), and nodes() = nodes(visible).
4507 now() -> Timestamp
4509 Types:
4511 Timestamp = timestamp()
4513 timestamp() =
4514 {MegaSecs :: integer() >= 0,
4515 Secs :: integer() >= 0,
4516 MicroSecs :: integer() >= 0}
4517 Warning:
4519 This function is deprecated. Do not use it.
4520 For more information, see section Time and Time Correction in
4522 the User's Guide. Specifically, section Dos and Dont's de‐
4523 scribes what to use instead of erlang:now/0.
4524 Returns the tuple {MegaSecs, Secs, MicroSecs}, which is the
4527 elapsed time since 00:00 GMT, January 1, 1970 (zero hour), if
4528 provided by the underlying OS. Otherwise some other point in
4529 time is chosen. It is also guaranteed that the following calls
4530 to this BIF return continuously increasing values. Hence, the
4531 return value from erlang:now/0 can be used to generate unique
4532 time stamps. If it is called in a tight loop on a fast machine,
4533 the time of the node can become skewed.
4534 Can only be used to check the local time of day if the time-zone
4536 information of the underlying OS is properly configured.
4537 open_port(PortName, PortSettings) -> port()
4539 Types:
4541 PortName =
4543 {spawn, Command :: string() | binary()} |
4544 {spawn_driver, Command :: string() | binary()} |
4545 {spawn_executable, FileName :: file:name_all()} |
4546 {fd, In :: integer() >= 0, Out :: integer() >= 0}
4547 PortSettings = [Opt]
4548 Opt =
4549 {packet, N :: 1 | 2 | 4} |
4550 stream |
4551 {line, L :: integer() >= 0} |
4552 {cd, Dir :: string() | binary()} |
4553 {env,
4554 Env ::
4555 [{Name :: os:env_var_name(),
4556 Val :: os:env_var_value() | false}]} |
4557 {args, [string() | binary()]} |
4558 {arg0, string() | binary()} |
4559 exit_status | use_stdio | nouse_stdio | stderr_to_stdout
4560 |
4561 in | out | binary | eof |
4562 {parallelism, Boolean :: boolean()} |
4563 hide |
4564 {busy_limits_port,
4565 {integer() >= 0, integer() >= 0} | disabled} |
4566 {busy_limits_msgq,
4567 {integer() >= 0, integer() >= 0} | disabled}
4568 Returns a port identifier as the result of opening a new Erlang
4570 port. A port can be seen as an external Erlang process.
4571 The name of the executable as well as the arguments specifed in
4573 cd, env, args, and arg0 are subject to Unicode filename transla‐
4574 tion if the system is running in Unicode filename mode. To avoid
4575 translation or to force, for example UTF-8, supply the exe‐
4576 cutable and/or arguments as a binary in the correct encoding.
4577 For details, see the module file(3), the function file:na‐
4578 tive_name_encoding/0 in Kernel, and the Using Unicode in Erlang
4579 User's Guide.
4580 Note:
4582 The characters in the name (if specified as a list) can only be
4583 > 255 if the Erlang virtual machine is started in Unicode file‐
4584 name translation mode. Otherwise the name of the executable is
4585 limited to the ISO Latin-1 character set.
4586 PortNames:
4589 {spawn, Command}:
4591 Starts an external program. Command is the name of the ex‐
4592 ternal program to be run. Command runs outside the Erlang
4593 work space unless an Erlang driver with the name Command is
4594 found. If found, that driver is started. A driver runs in
4595 the Erlang work space, which means that it is linked with
4596 the Erlang runtime system.
4597 For external programs, PATH is searched (or an equivalent
4599 method is used to find programs, depending on the OS). This
4600 is done by invoking the shell on certain platforms. The
4601 first space-separated token of the command is considered as
4602 the name of the executable (or driver). This (among other
4603 things) makes this option unsuitable for running programs
4604 with spaces in filenames or directory names. If spaces in
4605 executable filenames are desired, use {spawn_executable,
4606 Command} instead.
4607 {spawn_driver, Command}:
4609 Works like {spawn, Command}, but demands the first (space-
4610 separated) token of the command to be the name of a loaded
4611 driver. If no driver with that name is loaded, a badarg er‐
4612 ror is raised.
4613 {spawn_executable, FileName}:
4615 Works like {spawn, FileName}, but only runs external exe‐
4616 cutables. FileName in its whole is used as the name of the
4617 executable, including any spaces. If arguments are to be
4618 passed, the PortSettings args and arg0 can be used.
4619 The shell is usually not invoked to start the program, it is
4621 executed directly. PATH (or equivalent) is not searched. To
4622 find a program in PATH to execute, use os:find_executable/1.
4623 Only if a shell script or .bat file is executed, the appro‐
4625 priate command interpreter is invoked implicitly, but there
4626 is still no command-argument expansion or implicit PATH
4627 search.
4628 If FileName cannot be run, an error exception is raised,
4630 with the POSIX error code as the reason. The error reason
4631 can differ between OSs. Typically the error enoent is raised
4632 when an attempt is made to run a program that is not found
4633 and eacces is raised when the specified file is not exe‐
4634 cutable.
4635 {fd, In, Out}:
4637 Allows an Erlang process to access any currently opened file
4638 descriptors used by Erlang. The file descriptor In can be
4639 used for standard input, and the file descriptor Out for
4640 standard output. It is only used for various servers in the
4641 Erlang OS (shell and user). Hence, its use is limited.
4642 PortSettings is a list of settings for the port. The valid set‐
4644 tings are as follows:
4645 {packet, N}:
4647 Messages are preceded by their length, sent in N bytes, with
4648 the most significant byte first. The valid values for N are
4649 1, 2, and 4.
4650 stream:
4652 Output messages are sent without packet lengths. A user-de‐
4653 fined protocol must be used between the Erlang process and
4654 the external object.
4655 {line, L}:
4657 Messages are delivered on a per line basis. Each line (de‐
4658 limited by the OS-dependent newline sequence) is delivered
4659 in a single message. The message data format is {Flag,
4660 Line}, where Flag is eol or noeol, and Line is the data de‐
4661 livered (without the newline sequence).
4662 L specifies the maximum line length in bytes. Lines longer
4664 than this are delivered in more than one message, with Flag
4665 set to noeol for all but the last message. If end of file is
4666 encountered anywhere else than immediately following a new‐
4667 line sequence, the last line is also delivered with Flag set
4668 to noeol. Otherwise lines are delivered with Flag set to
4669 eol.
4670 The {packet, N} and {line, L} settings are mutually exclu‐
4672 sive.
4673 {cd, Dir}:
4675 Only valid for {spawn, Command} and {spawn_executable, File‐
4676 Name}. The external program starts using Dir as its working
4677 directory. Dir must be a string.
4678 {env, Env}:
4680 Types:
4681 Name = os:env_var_name()
4682 Val = os:env_var_value() | false
4683 Env = [{Name, Val}]
4684 Only valid for {spawn, Command}, and {spawn_executable,
4686 FileName}. The environment of the started process is ex‐
4687 tended using the environment specifications in Env.
4688 Env is to be a list of tuples {Name, Val}, where Name is the
4690 name of an environment variable, and Val is the value it is
4691 to have in the spawned port process. Both Name and Val must
4692 be strings. The one exception is Val being the atom false
4693 (in analogy with os:getenv/1, which removes the environment
4694 variable.
4695 For information about encoding requirements, see documenta‐
4697 tion of the types for Name and Val.
4698 {args, [ string() | binary() ]}:
4700 Only valid for {spawn_executable, FileName} and specifies
4701 arguments to the executable. Each argument is specified as a
4702 separate string and (on Unix) eventually ends up as one ele‐
4703 ment each in the argument vector. On other platforms, a sim‐
4704 ilar behavior is mimicked.
4705 The arguments are not expanded by the shell before they are
4707 supplied to the executable. Most notably this means that
4708 file wildcard expansion does not occur. To expand wildcards
4709 for the arguments, use filelib:wildcard/1. Notice that even
4710 if the program is a Unix shell script, meaning that the
4711 shell ultimately is invoked, wildcard expansion does not oc‐
4712 cur, and the script is provided with the untouched argu‐
4713 ments. On Windows, wildcard expansion is always up to the
4714 program itself, therefore this is not an issue.
4715 The executable name (also known as argv[0]) is not to be
4717 specified in this list. The proper executable name is auto‐
4718 matically used as argv[0], where applicable.
4719 If you explicitly want to set the program name in the argu‐
4721 ment vector, option arg0 can be used.
4722 {arg0, string() | binary()}:
4724 Only valid for {spawn_executable, FileName} and explicitly
4725 specifies the program name argument when running an exe‐
4726 cutable. This can in some circumstances, on some OSs, be de‐
4727 sirable. How the program responds to this is highly system-
4728 dependent and no specific effect is guaranteed.
4729 exit_status:
4731 Only valid for {spawn, Command}, where Command refers to an
4732 external program, and for {spawn_executable, FileName}.
4733 When the external process connected to the port exits, a
4735 message of the form {Port,{exit_status,Status}} is sent to
4736 the connected process, where Status is the exit status of
4737 the external process. If the program aborts on Unix, the
4738 same convention is used as the shells do (that is, 128+sig‐
4739 nal).
4740 If option eof is specified also, the messages eof and
4742 exit_status appear in an unspecified order.
4743 If the port program closes its stdout without exiting, op‐
4745 tion exit_status does not work.
4746 use_stdio:
4748 Only valid for {spawn, Command} and {spawn_executable, File‐
4749 Name}. It allows the standard input and output (file de‐
4750 scriptors 0 and 1) of the spawned (Unix) process for commu‐
4751 nication with Erlang.
4752 nouse_stdio:
4754 The opposite of use_stdio. It uses file descriptors 3 and 4
4755 for communication with Erlang.
4756 stderr_to_stdout:
4758 Affects ports to external programs. The executed program
4759 gets its standard error file redirected to its standard out‐
4760 put file. stderr_to_stdout and nouse_stdio are mutually ex‐
4761 clusive.
4762 overlapped_io:
4764 Affects ports to external programs on Windows only. The
4765 standard input and standard output handles of the port pro‐
4766 gram are, if this option is supplied, opened with flag
4767 FILE_FLAG_OVERLAPPED, so that the port program can (and
4768 must) do overlapped I/O on its standard handles. This is not
4769 normally the case for simple port programs, but an option of
4770 value for the experienced Windows programmer. On all other
4771 platforms, this option is silently discarded.
4772 in:
4774 The port can only be used for input.
4775 out:
4777 The port can only be used for output.
4778 binary:
4780 All I/O from the port is binary data objects as opposed to
4781 lists of bytes.
4782 eof:
4784 The port is not closed at the end of the file and does not
4785 produce an exit signal. Instead, it remains open and a
4786 {Port, eof} message is sent to the process holding the port.
4787 hide:
4789 When running on Windows, suppresses creation of a new con‐
4790 sole window when spawning the port program. (This option has
4791 no effect on other platforms.)
4792 {parallelism, Boolean}:
4794 Sets scheduler hint for port parallelism. If set to true,
4797 the virtual machine schedules port tasks; when doing so, it
4798 improves parallelism in the system. If set to false, the
4799 virtual machine tries to perform port tasks immediately, im‐
4800 proving latency at the expense of parallelism. The default
4801 can be set at system startup by passing command-line argu‐
4802 ment +spp to erl(1).
4803 {busy_limits_port, {Low, High} | disabled}:
4805 Sets limits that will be used for controlling the busy state
4806 of the port.
4807 When the ports internal output queue size becomes larger
4809 than or equal to High bytes, it enters the busy state. When
4810 it becomes less than Low bytes it leaves the busy state.
4811 When the port is in the busy state, processes sending com‐
4812 mands to it will be suspended until the port leaves the busy
4813 state. Commands are in this context either Port ! {Owner,
4814 {command, Data}} or port_command/[2,3].
4815 The Low limit is automatically adjusted to the same as High
4817 if it is set larger then High. Valid range of values for Low
4818 and High is [1, (1 bsl (8*erlang:system_info(wordsize)))-2].
4819 If the atom disabled is passed, the port will never enter
4820 the busy state.
4821 The defaults are Low = 4096 and High = 8192.
4823 Note that this option is only valid when spawning an exe‐
4825 cutable (port program) by opening the spawn driver and when
4826 opening the fd driver. This option will cause a failure with
4827 a badarg exception when opening other drivers.
4828 {busy_limits_msgq, {Low, High} | disabled}:
4830 Sets limits that will be used for controlling the busy state
4831 of the port message queue.
4832 When the ports message queue size becomes larger than or
4834 equal to High bytes it enters the busy state. When it be‐
4835 comes less than Low bytes it leaves the busy state. When the
4836 port message queue is in the busy state, processes sending
4837 commands to it will be suspended until the port message
4838 queue leaves the busy state. Commands are in this context
4839 either Port ! {Owner, {command, Data}} or port_com‐
4840 mand/[2,3].
4841 The Low limit is automatically adjusted to the same as High
4843 if it is set larger then High. Valid range of values for Low
4844 and High is [1, (1 bsl (8*erlang:system_info(wordsize)))-2].
4845 If the atom disabled is passed, the port message queue will
4846 never enter the busy state.
4847 Note that if the driver statically has disabled the use of
4849 this feature, a failure with a badarg exception will be
4850 raised unless this option also is set to disable or not
4851 passed at all.
4852 The defaults are Low = 4096 and High = 8192 unless the
4854 driver itself does modifications of these values.
4855 Note that the driver might fail if it also adjust these lim‐
4857 its by itself and you have disabled this feature.
4858 The spawn driver (used when spawning an executable) and the
4860 fd driver do not disable this feature and do not adjust
4861 these limits by themselves.
4862 For more information see the documentation
4864 erl_drv_busy_msgq_limits().
4865 Default is stream for all port types and use_stdio for spawned
4867 ports.
4868 Failure: if the port cannot be opened, the exit reason is
4870 badarg, system_limit, or the POSIX error code that most closely
4871 describes the error, or einval if no POSIX code is appropriate:
4872 badarg:
4874 Bad input arguments to open_port.
4875 system_limit:
4877 All available ports in the Erlang emulator are in use.
4878 enomem:
4880 Not enough memory to create the port.
4881 eagain:
4883 No more available OS processes.
4884 enametoolong:
4886 Too long external command.
4887 emfile:
4889 No more available file descriptors (for the OS process that
4890 the Erlang emulator runs in).
4891 enfile:
4893 Full file table (for the entire OS).
4894 eacces:
4896 Command specified in {spawn_executable, Command} does not
4897 point out an executable file.
4898 enoent:
4900 FileName specified in {spawn_executable, FileName} does not
4901 point out an existing file.
4902 During use of a port opened using {spawn, Name}, {spawn_driver,
4904 Name}, or {spawn_executable, Name}, errors arising when sending
4905 messages to it are reported to the owning process using signals
4906 of the form {'EXIT', Port, PosixCode}. For the possible values
4907 of PosixCode, see file(3).
4908 The maximum number of ports that can be open at the same time
4910 can be configured by passing command-line flag +Q to erl(1).
4911 erlang:phash(Term, Range) -> Hash
4913 Types:
4915 Term = term()
4917 Range = Hash = integer() >= 1
4918 Range = 1..2^32, Hash = 1..Range
4919 Warning:
4921 This function is deprecated as erlang:phash2/2 should be used
4922 for new code. Note that erlang:phash(X,N) is not necessary equal
4923 to erlang:phash2(X,N)
4924 Portable hash function that gives the same hash for the same Er‐
4927 lang term regardless of machine architecture and ERTS version
4928 (the BIF was introduced in ERTS 4.9.1.1). The function returns a
4929 hash value for Term within the range 1..Range. The maximum value
4930 for Range is 2^32.
4931 erlang:phash2(Term) -> Hash
4933 erlang:phash2(Term, Range) -> Hash
4935 Types:
4937 Term = term()
4939 Range = integer() >= 1
4940 1..2^32
4941 Hash = integer() >= 0
4942 0..Range-1
4943 Portable hash function that gives the same hash for the same Er‐
4945 lang term regardless of machine architecture and ERTS version
4946 (the BIF was introduced in ERTS 5.2). The function returns a
4947 hash value for Term within the range 0..Range-1. The maximum
4948 value for Range is 2^32. When without argument Range, a value in
4949 the range 0..2^27-1 is returned.
4950 This BIF is always to be used for hashing terms. It distributes
4952 small integers better than phash/2, and it is faster for bignums
4953 and binaries.
4954 Notice that the range 0..Range-1 is different from the range of
4956 phash/2, which is 1..Range.
4957 pid_to_list(Pid) -> string()
4959 Types:
4961 Pid = pid()
4963 Returns a string corresponding to the text representation of
4965 Pid. Example:
4966 > erlang:pid_to_list(self()).
4968 "<0.85.0>"
4969 Note:
4971 The creation for the node is not included in the list represen‐
4972 tation of Pid. This means that processes in different incarna‐
4973 tions of a node with a specific name can get the same list rep‐
4974 resentation.
4975 erlang:port_call(Port, Operation, Data) -> term()
4978 Types:
4980 Port = port() | atom()
4982 Operation = integer()
4983 Data = term()
4984 Performs a synchronous call to a port. The meaning of Operation
4986 and Data depends on the port, that is, on the port driver. Not
4987 all port drivers support this feature.
4988 Port is a port identifier, referring to a driver.
4990 Operation is an integer, which is passed on to the driver.
4992 Data is any Erlang term. This data is converted to binary term
4994 format and sent to the port.
4995 Returns a term from the driver. The meaning of the returned data
4997 also depends on the port driver.
4998 Failures:
5000 badarg:
5002 If Port is not an identifier of an open port, or the regis‐
5003 tered name of an open port. If the calling process was pre‐
5004 viously linked to the closed port, identified by Port, the
5005 exit signal from the port is guaranteed to be delivered be‐
5006 fore this badarg exception occurs.
5007 badarg:
5009 If Operation does not fit in a 32-bit integer.
5010 badarg:
5012 If the port driver does not support synchronous control op‐
5013 erations.
5014 badarg:
5016 If the port driver so decides for any reason (probably some‐
5017 thing wrong with Operation or Data).
5018 Warning:
5020 Do not call port_call with an unknown Port identifier and ex‐
5021 pect badarg exception. Any undefined behavior is possible (in‐
5022 cluding node crash) depending on how the port driver inter‐
5023 prets the supplied arguments.
5024 port_close(Port) -> true
5027 Types:
5029 Port = port() | atom()
5031 Closes an open port. Roughly the same as Port ! {self(), close}
5033 except for the error behavior (see below), being synchronous,
5034 and that the port does not reply with {Port, closed}. Any
5035 process can close a port with port_close/1, not only the port
5036 owner (the connected process). If the calling process is linked
5037 to the port identified by Port, the exit signal from the port is
5038 guaranteed to be delivered before port_close/1 returns.
5039 For comparison: Port ! {self(), close} only fails with badarg if
5041 Port does not refer to a port or a process. If Port is a closed
5042 port, nothing happens. If Port is an open port and the calling
5043 process is the port owner, the port replies with {Port, closed}
5044 when all buffers have been flushed and the port really closes.
5045 If the calling process is not the port owner, the port owner
5046 fails with badsig.
5047 Notice that any process can close a port using Port ! {Por‐
5049 tOwner, close} as if it itself was the port owner, but the reply
5050 always goes to the port owner.
5051 As from Erlang/OTP R16, Port ! {PortOwner, close} is truly asyn‐
5053 chronous. Notice that this operation has always been documented
5054 as an asynchronous operation, while the underlying implementa‐
5055 tion has been synchronous. port_close/1 is however still fully
5056 synchronous because of its error behavior.
5057 Failure: badarg if Port is not an identifier of an open port, or
5059 the registered name of an open port. If the calling process was
5060 previously linked to the closed port, identified by Port, the
5061 exit signal from the port is guaranteed to be delivered before
5062 this badarg exception occurs.
5063 port_command(Port, Data) -> true
5065 Types:
5067 Port = port() | atom()
5069 Data = iodata()
5070 Sends data to a port. Same as Port ! {PortOwner, {command,
5072 Data}} except for the error behavior and being synchronous (see
5073 below). Any process can send data to a port with port_command/2,
5074 not only the port owner (the connected process).
5075 For comparison: Port ! {PortOwner, {command, Data}} only fails
5077 with badarg if Port does not refer to a port or a process. If
5078 Port is a closed port, the data message disappears without a
5079 sound. If Port is open and the calling process is not the port
5080 owner, the port owner fails with badsig. The port owner fails
5081 with badsig also if Data is an invalid I/O list.
5082 Notice that any process can send to a port using Port ! {Por‐
5084 tOwner, {command, Data}} as if it itself was the port owner.
5085 If the port is busy, the calling process is suspended until the
5087 port is not busy any more.
5088 As from Erlang/OTP R16, Port ! {PortOwner, {command, Data}} is
5090 truly asynchronous. Notice that this operation has always been
5091 documented as an asynchronous operation, while the underlying
5092 implementation has been synchronous. port_command/2 is however
5093 still fully synchronous because of its error behavior.
5094 Failures:
5096 badarg:
5098 If Port is not an identifier of an open port, or the regis‐
5099 tered name of an open port. If the calling process was pre‐
5100 viously linked to the closed port, identified by Port, the
5101 exit signal from the port is guaranteed to be delivered be‐
5102 fore this badarg exception occurs.
5103 badarg:
5105 If Data is an invalid I/O list.
5106 Warning:
5108 Do not send data to an unknown port. Any undefined behavior is
5109 possible (including node crash) depending on how the port driver
5110 interprets the data.
5111 port_command(Port, Data, OptionList) -> boolean()
5114 Types:
5116 Port = port() | atom()
5118 Data = iodata()
5119 Option = force | nosuspend
5120 OptionList = [Option]
5121 Sends data to a port. port_command(Port, Data, []) equals
5123 port_command(Port, Data).
5124 If the port command is aborted, false is returned, otherwise
5126 true.
5127 If the port is busy, the calling process is suspended until the
5129 port is not busy anymore.
5130 Options:
5132 force:
5134 The calling process is not suspended if the port is busy,
5135 instead the port command is forced through. The call fails
5136 with a notsup exception if the driver of the port does not
5137 support this. For more information, see driver flag
5138 ERL_DRV_FLAG_SOFT_BUSY.
5139 nosuspend:
5141 The calling process is not suspended if the port is busy,
5142 instead the port command is aborted and false is returned.
5143 Note:
5145 More options can be added in a future release.
5146 Failures:
5149 badarg:
5151 If Port is not an identifier of an open port, or the regis‐
5152 tered name of an open port. If the calling process was pre‐
5153 viously linked to the closed port, identified by Port, the
5154 exit signal from the port is guaranteed to be delivered be‐
5155 fore this badarg exception occurs.
5156 badarg:
5158 If Data is an invalid I/O list.
5159 badarg:
5161 If OptionList is an invalid option list.
5162 notsup:
5164 If option force has been passed, but the driver of the port
5165 does not allow forcing through a busy port.
5166 Warning:
5168 Do not send data to an unknown port. Any undefined behavior is
5169 possible (including node crash) depending on how the port driver
5170 interprets the data.
5171 port_connect(Port, Pid) -> true
5174 Types:
5176 Port = port() | atom()
5178 Pid = pid()
5179 Sets the port owner (the connected port) to Pid. Roughly the
5181 same as Port ! {Owner, {connect, Pid}} except for the following:
5182 * The error behavior differs, see below.
5184 * The port does not reply with {Port,connected}.
5186 * port_connect/1 is synchronous, see below.
5188 * The new port owner gets linked to the port.
5190 The old port owner stays linked to the port and must call un‐
5192 link(Port) if this is not desired. Any process can set the port
5193 owner to be any process with port_connect/2.
5194 For comparison: Port ! {self(), {connect, Pid}} only fails with
5196 badarg if Port does not refer to a port or a process. If Port is
5197 a closed port, nothing happens. If Port is an open port and the
5198 calling process is the port owner, the port replies with {Port,
5199 connected} to the old port owner. Notice that the old port owner
5200 is still linked to the port, while the new is not. If Port is an
5201 open port and the calling process is not the port owner, the
5202 port owner fails with badsig. The port owner fails with badsig
5203 also if Pid is not an existing local process identifier.
5204 Notice that any process can set the port owner using Port !
5206 {PortOwner, {connect, Pid}} as if it itself was the port owner,
5207 but the reply always goes to the port owner.
5208 As from Erlang/OTP R16, Port ! {PortOwner, {connect, Pid}} is
5210 truly asynchronous. Notice that this operation has always been
5211 documented as an asynchronous operation, while the underlying
5212 implementation has been synchronous. port_connect/2 is however
5213 still fully synchronous because of its error behavior.
5214 Failures:
5216 badarg:
5218 If Port is not an identifier of an open port, or the regis‐
5219 tered name of an open port. If the calling process was pre‐
5220 viously linked to the closed port, identified by Port, the
5221 exit signal from the port is guaranteed to be delivered be‐
5222 fore this badarg exception occurs.
5223 badarg:
5225 If the process identified by Pid is not an existing local
5226 process.
5227 port_control(Port, Operation, Data) -> iodata() | binary()
5229 Types:
5231 Port = port() | atom()
5233 Operation = integer()
5234 Data = iodata()
5235 Performs a synchronous control operation on a port. The meaning
5237 of Operation and Data depends on the port, that is, on the port
5238 driver. Not all port drivers support this control feature.
5239 Returns a list of integers in the range 0..255, or a binary, de‐
5241 pending on the port driver. The meaning of the returned data
5242 also depends on the port driver.
5243 Failures:
5245 badarg:
5247 If Port is not an open port or the registered name of an
5248 open port.
5249 badarg:
5251 If Operation cannot fit in a 32-bit integer.
5252 badarg:
5254 If the port driver does not support synchronous control op‐
5255 erations.
5256 badarg:
5258 If the port driver so decides for any reason (probably
5259 something wrong with Operation or Data).
5260 Warning:
5262 Do not call port_control/3 with an unknown Port identifier and
5263 expect badarg exception. Any undefined behavior is possible
5264 (including node crash) depending on how the port driver inter‐
5265 prets the supplied arguments.
5266 erlang:port_info(Port) -> Result
5269 Types:
5271 Port = port() | atom()
5273 ResultItem =
5274 {registered_name, RegisteredName :: atom()} |
5275 {id, Index :: integer() >= 0} |
5276 {connected, Pid :: pid()} |
5277 {links, Pids :: [pid()]} |
5278 {name, String :: string()} |
5279 {input, Bytes :: integer() >= 0} |
5280 {output, Bytes :: integer() >= 0} |
5281 {os_pid, OsPid :: integer() >= 0 | undefined}
5282 Result = [ResultItem] | undefined
5283 Returns a list containing tuples with information about Port, or
5285 undefined if the port is not open. The order of the tuples is
5286 undefined, and all the tuples are not mandatory. If the port is
5287 closed and the calling process was previously linked to the
5288 port, the exit signal from the port is guaranteed to be deliv‐
5289 ered before port_info/1 returns undefined.
5290 The result contains information about the following Items:
5292 * registered_name (if the port has a registered name)
5294 * id
5296 * connected
5298 * links
5300 * name
5302 * input
5304 * output
5306 For more information about the different Items, see port_info/2.
5308 Failure: badarg if Port is not a local port identifier, or an
5310 atom.
5311 erlang:port_info(Port, Item :: connected) ->
5313 {connected, Pid} | undefined
5314 Types:
5316 Port = port() | atom()
5318 Pid = pid()
5319 Pid is the process identifier of the process connected to the
5321 port.
5322 If the port identified by Port is not open, undefined is re‐
5324 turned. If the port is closed and the calling process was previ‐
5325 ously linked to the port, the exit signal from the port is guar‐
5326 anteed to be delivered before port_info/2 returns undefined.
5327 Failure: badarg if Port is not a local port identifier, or an
5329 atom.
5330 erlang:port_info(Port, Item :: id) -> {id, Index} | undefined
5332 Types:
5334 Port = port() | atom()
5336 Index = integer() >= 0
5337 Index is the internal index of the port. This index can be used
5339 to separate ports.
5340 If the port identified by Port is not open, undefined is re‐
5342 turned. If the port is closed and the calling process was previ‐
5343 ously linked to the port, the exit signal from the port is guar‐
5344 anteed to be delivered before port_info/2 returns undefined.
5345 Failure: badarg if Port is not a local port identifier, or an
5347 atom.
5348 erlang:port_info(Port, Item :: input) ->
5350 {input, Bytes} | undefined
5351 Types:
5353 Port = port() | atom()
5355 Bytes = integer() >= 0
5356 Bytes is the total number of bytes read from the port.
5358 If the port identified by Port is not open, undefined is re‐
5360 turned. If the port is closed and the calling process was previ‐
5361 ously linked to the port, the exit signal from the port is guar‐
5362 anteed to be delivered before port_info/2 returns undefined.
5363 Failure: badarg if Port is not a local port identifier, or an
5365 atom.
5366 erlang:port_info(Port, Item :: links) -> {links, Pids} | undefined
5368 Types:
5370 Port = port() | atom()
5372 Pids = [pid()]
5373 Pids is a list of the process identifiers of the processes that
5375 the port is linked to.
5376 If the port identified by Port is not open, undefined is re‐
5378 turned. If the port is closed and the calling process was previ‐
5379 ously linked to the port, the exit signal from the port is guar‐
5380 anteed to be delivered before port_info/2 returns undefined.
5381 Failure: badarg if Port is not a local port identifier, or an
5383 atom.
5384 erlang:port_info(Port, Item :: locking) ->
5386 {locking, Locking} | undefined
5387 Types:
5389 Port = port() | atom()
5391 Locking = false | port_level | driver_level
5392 Locking is one of the following:
5394 * port_level (port-specific locking)
5396 * driver_level (driver-specific locking)
5398 Notice that these results are highly implementation-specific and
5400 can change in a future release.
5401 If the port identified by Port is not open, undefined is re‐
5403 turned. If the port is closed and the calling process was previ‐
5404 ously linked to the port, the exit signal from the port is guar‐
5405 anteed to be delivered before port_info/2 returns undefined.
5406 Failure: badarg if Port is not a local port identifier, or an
5408 atom.
5409 erlang:port_info(Port, Item :: memory) ->
5411 {memory, Bytes} | undefined
5412 Types:
5414 Port = port() | atom()
5416 Bytes = integer() >= 0
5417 Bytes is the total number of bytes allocated for this port by
5419 the runtime system. The port itself can have allocated memory
5420 that is not included in Bytes.
5421 If the port identified by Port is not open, undefined is re‐
5423 turned. If the port is closed and the calling process was previ‐
5424 ously linked to the port, the exit signal from the port is guar‐
5425 anteed to be delivered before port_info/2 returns undefined.
5426 Failure: badarg if Port is not a local port identifier, or an
5428 atom.
5429 erlang:port_info(Port, Item :: monitors) ->
5431 {monitors, Monitors} | undefined
5432 Types:
5434 Port = port() | atom()
5436 Monitors = [{process, pid()}]
5437 Monitors represent processes monitored by this port.
5439 If the port identified by Port is not open, undefined is re‐
5441 turned. If the port is closed and the calling process was previ‐
5442 ously linked to the port, the exit signal from the port is guar‐
5443 anteed to be delivered before port_info/2 returns undefined.
5444 Failure: badarg if Port is not a local port identifier, or an
5446 atom.
5447 erlang:port_info(Port, Item :: monitored_by) ->
5449 {monitored_by, MonitoredBy} | undefined
5450 Types:
5452 Port = port() | atom()
5454 MonitoredBy = [pid()]
5455 Returns list of pids that are monitoring given port at the mo‐
5457 ment.
5458 If the port identified by Port is not open, undefined is re‐
5460 turned. If the port is closed and the calling process was previ‐
5461 ously linked to the port, the exit signal from the port is guar‐
5462 anteed to be delivered before port_info/2 returns undefined.
5463 Failure: badarg if Port is not a local port identifier, or an
5465 atom.
5466 erlang:port_info(Port, Item :: name) -> {name, Name} | undefined
5468 Types:
5470 Port = port() | atom()
5472 Name = string()
5473 Name is the command name set by open_port/2.
5475 If the port identified by Port is not open, undefined is re‐
5477 turned. If the port is closed and the calling process was previ‐
5478 ously linked to the port, the exit signal from the port is guar‐
5479 anteed to be delivered before port_info/2 returns undefined.
5480 Failure: badarg if Port is not a local port identifier, or an
5482 atom.
5483 erlang:port_info(Port, Item :: os_pid) ->
5485 {os_pid, OsPid} | undefined
5486 Types:
5488 Port = port() | atom()
5490 OsPid = integer() >= 0 | undefined
5491 OsPid is the process identifier (or equivalent) of an OS process
5493 created with open_port({spawn | spawn_executable, Command}, Op‐
5494 tions). If the port is not the result of spawning an OS process,
5495 the value is undefined.
5496 If the port identified by Port is not open, undefined is re‐
5498 turned. If the port is closed and the calling process was previ‐
5499 ously linked to the port, the exit signal from the port is guar‐
5500 anteed to be delivered before port_info/2 returns undefined.
5501 Failure: badarg if Port is not a local port identifier, or an
5503 atom.
5504 erlang:port_info(Port, Item :: output) ->
5506 {output, Bytes} | undefined
5507 Types:
5509 Port = port() | atom()
5511 Bytes = integer() >= 0
5512 Bytes is the total number of bytes written to the port from Er‐
5514 lang processes using port_command/2, port_command/3, or Port !
5515 {Owner, {command, Data}.
5516 If the port identified by Port is not open, undefined is re‐
5518 turned. If the port is closed and the calling process was previ‐
5519 ously linked to the port, the exit signal from the port is guar‐
5520 anteed to be delivered before port_info/2 returns undefined.
5521 Failure: badarg if Port is not a local port identifier, or an
5523 atom.
5524 erlang:port_info(Port, Item :: parallelism) ->
5526 {parallelism, Boolean} | undefined
5527 Types:
5529 Port = port() | atom()
5531 Boolean = boolean()
5532 Boolean corresponds to the port parallelism hint used by this
5534 port. For more information, see option parallelism of
5535 open_port/2.
5536 erlang:port_info(Port, Item :: queue_size) ->
5538 {queue_size, Bytes} | undefined
5539 Types:
5541 Port = port() | atom()
5543 Bytes = integer() >= 0
5544 Bytes is the total number of bytes queued by the port using the
5546 ERTS driver queue implementation.
5547 If the port identified by Port is not open, undefined is re‐
5549 turned. If the port is closed and the calling process was previ‐
5550 ously linked to the port, the exit signal from the port is guar‐
5551 anteed to be delivered before port_info/2 returns undefined.
5552 Failure: badarg if Port is not a local port identifier, or an
5554 atom.
5555 erlang:port_info(Port, Item :: registered_name) ->
5557 {registered_name, RegisteredName} |
5558 [] | undefined
5559 Types:
5561 Port = port() | atom()
5563 RegisteredName = atom()
5564 RegisteredName is the registered name of the port. If the port
5566 has no registered name, [] is returned.
5567 If the port identified by Port is not open, undefined is re‐
5569 turned. If the port is closed and the calling process was previ‐
5570 ously linked to the port, the exit signal from the port is guar‐
5571 anteed to be delivered before port_info/2 returns undefined.
5572 Failure: badarg if Port is not a local port identifier, or an
5574 atom.
5575 port_to_list(Port) -> string()
5577 Types:
5579 Port = port()
5581 Returns a string corresponding to the text representation of the
5583 port identifier Port.
5584 erlang:ports() -> [port()]
5586 Returns a list of port identifiers corresponding to all the
5588 ports existing on the local node.
5589 Notice that an exiting port exists, but is not open.
5591 pre_loaded() -> [module()]
5593 Returns a list of Erlang modules that are preloaded in the run-
5595 time system. Pre-loaded modules are Erlang modules that are
5596 needed to bootstrap the system to load the first Erlang modules
5597 from either disk or by using erl_boot_server.
5598 erlang:process_display(Pid, Type) -> true
5600 Types:
5602 Pid = pid()
5604 Type = backtrace
5605 Writes information about the local process Pid on standard er‐
5607 ror. The only allowed value for the atom Type is backtrace,
5608 which shows the contents of the call stack, including informa‐
5609 tion about the call chain, with the current function printed
5610 first. The format of the output is not further defined.
5611 process_flag(Flag :: trap_exit, Boolean) -> OldBoolean
5613 Types:
5615 Boolean = OldBoolean = boolean()
5617 When trap_exit is set to true, exit signals arriving to a
5619 process are converted to {'EXIT', From, Reason} messages, which
5620 can be received as ordinary messages. If trap_exit is set to
5621 false, the process exits if it receives an exit signal other
5622 than normal and the exit signal is propagated to its linked pro‐
5623 cesses. Application processes are normally not to trap exits.
5624 Returns the old value of the flag.
5626 See also exit/2.
5628 process_flag(Flag :: error_handler, Module) -> OldModule
5630 Types:
5632 Module = OldModule = atom()
5634 Used by a process to redefine the error handler for undefined
5636 function calls and undefined registered processes. Inexperienced
5637 users are not to use this flag, as code auto-loading depends on
5638 the correct operation of the error handling module.
5639 Returns the old value of the flag.
5641 process_flag(Flag :: fullsweep_after, FullsweepAfter) ->
5643 OldFullsweepAfter
5644 Types:
5646 FullsweepAfter = OldFullsweepAfter = integer() >= 0
5648 Changes the maximum number of generational collections before
5650 forcing a fullsweep for the calling process.
5651 Returns the old value of the flag.
5653 process_flag(Flag :: min_heap_size, MinHeapSize) -> OldMinHeapSize
5655 Types:
5657 MinHeapSize = OldMinHeapSize = integer() >= 0
5659 Changes the minimum heap size for the calling process.
5661 Returns the old value of the flag.
5663 process_flag(Flag :: min_bin_vheap_size, MinBinVHeapSize) ->
5665 OldMinBinVHeapSize
5666 Types:
5668 MinBinVHeapSize = OldMinBinVHeapSize = integer() >= 0
5670 Changes the minimum binary virtual heap size for the calling
5672 process.
5673 Returns the old value of the flag.
5675 process_flag(Flag :: max_heap_size, MaxHeapSize) -> OldMaxHeapSize
5677 Types:
5679 MaxHeapSize = OldMaxHeapSize = max_heap_size()
5681 max_heap_size() =
5682 integer() >= 0 |
5683 #{size => integer() >= 0,
5684 kill => boolean(),
5685 error_logger => boolean()}
5686 This flag sets the maximum heap size for the calling process. If
5688 MaxHeapSize is an integer, the system default values for kill
5689 and error_logger are used.
5690 size:
5692 The maximum size in words of the process. If set to zero,
5693 the heap size limit is disabled. badarg is be thrown if the
5694 value is smaller than min_heap_size. The size check is only
5695 done when a garbage collection is triggered.
5696 size is the entire heap of the process when garbage collec‐
5698 tion is triggered. This includes all generational heaps, the
5699 process stack, any messages that are considered to be part
5700 of the heap, and any extra memory that the garbage collector
5701 needs during collection.
5702 size is the same as can be retrieved using er‐
5704 lang:process_info(Pid, total_heap_size), or by adding
5705 heap_block_size, old_heap_block_size and mbuf_size from er‐
5706 lang:process_info(Pid, garbage_collection_info).
5707 kill:
5709 When set to true, the runtime system sends an untrappable
5710 exit signal with reason kill to the process if the maximum
5711 heap size is reached. The garbage collection that triggered
5712 the kill is not completed, instead the process exits as soon
5713 as possible. When set to false, no exit signal is sent to
5714 the process, instead it continues executing.
5715 If kill is not defined in the map, the system default will
5717 be used. The default system default is true. It can be
5718 changed by either option +hmaxk in erl(1), or erlang:sys‐
5719 tem_flag(max_heap_size, MaxHeapSize).
5720 error_logger:
5722 When set to true, the runtime system logs an error event via
5723 logger, containing details about the process when the maxi‐
5724 mum heap size is reached. One log event is sent each time
5725 the limit is reached.
5726 If error_logger is not defined in the map, the system de‐
5728 fault is used. The default system default is true. It can be
5729 changed by either the option +hmaxel int erl(1), or er‐
5730 lang:system_flag(max_heap_size, MaxHeapSize).
5731 The heap size of a process is quite hard to predict, especially
5733 the amount of memory that is used during the garbage collection.
5734 When contemplating using this option, it is recommended to first
5735 run it in production with kill set to false and inspect the log
5736 events to see what the normal peak sizes of the processes in the
5737 system is and then tune the value accordingly.
5738 process_flag(Flag :: message_queue_data, MQD) -> OldMQD
5740 Types:
5742 MQD = OldMQD = message_queue_data()
5744 message_queue_data() = off_heap | on_heap
5745 Determines how messages in the message queue are stored, as fol‐
5747 lows:
5748 off_heap:
5750 All messages in the message queue will be stored outside the
5751 process heap. This implies that no messages in the message
5752 queue will be part of a garbage collection of the process.
5753 on_heap:
5755 All messages in the message queue will eventually be placed
5756 on the process heap. They can, however, be temporarily
5757 stored off the heap. This is how messages have always been
5758 stored up until ERTS 8.0.
5759 The default value of the message_queue_data process flag is de‐
5761 termined by the command-line argument +hmqd in erl(1).
5762 If the process may potentially accumulate a large number of mes‐
5764 sages in its queue it is recommended to set the flag value to
5765 off_heap. This is due to the fact that the garbage collection of
5766 a process that has a large number of messages stored on the heap
5767 can become extremely expensive and the process can consume large
5768 amounts of memory. The performance of the actual message passing
5769 is, however, generally better when the flag value is on_heap.
5770 Changing the flag value causes any existing messages to be
5772 moved. The move operation is initiated, but not necessarily com‐
5773 pleted, by the time the function returns.
5774 Returns the old value of the flag.
5776 process_flag(Flag :: priority, Level) -> OldLevel
5778 Types:
5780 Level = OldLevel = priority_level()
5782 priority_level() = low | normal | high | max
5783 Sets the process priority. Level is an atom. Four priority lev‐
5785 els exist: low, normal, high, and max. Default is normal.
5786 Note:
5788 Priority level max is reserved for internal use in the Erlang
5789 runtime system, and is not to be used by others.
5790 Internally in each priority level, processes are scheduled in a
5793 round robin fashion.
5794 Execution of processes on priority normal and low are inter‐
5796 leaved. Processes on priority low are selected for execution
5797 less frequently than processes on priority normal.
5798 When runnable processes on priority high exist, no processes on
5800 priority low or normal are selected for execution. Notice how‐
5801 ever that this does not mean that no processes on priority low
5802 or normal can run when processes are running on priority high.
5803 When using multiple schedulers, more processes can be running in
5804 parallel than processes on priority high. That is, a low and a
5805 high priority process can execute at the same time.
5806 When runnable processes on priority max exist, no processes on
5808 priority low, normal, or high are selected for execution. As
5809 with priority high, processes on lower priorities can execute in
5810 parallel with processes on priority max.
5811 Scheduling is pre-emptive. Regardless of priority, a process is
5813 pre-empted when it has consumed more than a certain number of
5814 reductions since the last time it was selected for execution.
5815 Note:
5817 Do not depend on the scheduling to remain exactly as it is to‐
5818 day. Scheduling is likely to be changed in a future release to
5819 use available processor cores better.
5820 There is no automatic mechanism for avoiding priority inversion,
5823 such as priority inheritance or priority ceilings. When using
5824 priorities, take this into account and handle such scenarios by
5825 yourself.
5826 Making calls from a high priority process into code that you has
5828 no control over can cause the high priority process to wait for
5829 a process with lower priority. That is, effectively decreasing
5830 the priority of the high priority process during the call. Even
5831 if this is not the case with one version of the code that you
5832 have no control over, it can be the case in a future version of
5833 it. This can, for example, occur if a high priority process
5834 triggers code loading, as the code server runs on priority nor‐
5835 mal.
5836 Other priorities than normal are normally not needed. When other
5838 priorities are used, use them with care, especially priority
5839 high. A process on priority high is only to perform work for
5840 short periods. Busy looping for long periods in a high priority
5841 process causes most likely problems, as important OTP servers
5842 run on priority normal.
5843 Returns the old value of the flag.
5845 process_flag(Flag :: save_calls, N) -> OldN
5847 Types:
5849 N = OldN = 0..10000
5851 N must be an integer in the interval 0..10000. If N > 0, call
5853 saving is made active for the process. This means that informa‐
5854 tion about the N most recent global function calls, BIF calls,
5855 sends, and receives made by the process are saved in a list,
5856 which can be retrieved with process_info(Pid, last_calls). A
5857 global function call is one in which the module of the function
5858 is explicitly mentioned. Only a fixed amount of information is
5859 saved, as follows:
5860 * A tuple {Module, Function, Arity} for function calls
5862 * The atoms send, 'receive', and timeout for sends and re‐
5864 ceives ('receive' when a message is received and timeout
5865 when a receive times out)
5866 If N = 0, call saving is disabled for the process, which is the
5868 default. Whenever the size of the call saving list is set, its
5869 contents are reset.
5870 Returns the old value of the flag.
5872 process_flag(Flag :: sensitive, Boolean) -> OldBoolean
5874 Types:
5876 Boolean = OldBoolean = boolean()
5878 Sets or clears flag sensitive for the current process. When a
5880 process has been marked as sensitive by calling
5881 process_flag(sensitive, true), features in the runtime system
5882 that can be used for examining the data or inner working of the
5883 process are silently disabled.
5884 Features that are disabled include (but are not limited to) the
5886 following:
5887 * Tracing. Trace flags can still be set for the process, but
5889 no trace messages of any kind are generated. (If flag sensi‐
5890 tive is turned off, trace messages are again generated if
5891 any trace flags are set.)
5892 * Sequential tracing. The sequential trace token is propagated
5894 as usual, but no sequential trace messages are generated.
5895 process_info/1,2 cannot be used to read out the message queue or
5897 the process dictionary (both are returned as empty lists).
5898 Stack back-traces cannot be displayed for the process.
5900 In crash dumps, the stack, messages, and the process dictionary
5902 are omitted.
5903 If {save_calls,N} has been set for the process, no function
5905 calls are saved to the call saving list. (The call saving list
5906 is not cleared. Also, send, receive, and time-out events are
5907 still added to the list.)
5908 Returns the old value of the flag.
5910 process_flag(Pid, Flag, Value) -> OldValue
5912 Types:
5914 Pid = pid()
5916 Flag = save_calls
5917 Value = OldValue = integer() >= 0
5918 Sets certain flags for the process Pid, in the same manner as
5920 process_flag/2. Returns the old value of the flag. The valid
5921 values for Flag are only a subset of those allowed in
5922 process_flag/2, namely save_calls.
5923 Failure: badarg if Pid is not a local process.
5925 process_info(Pid) -> Info
5927 Types:
5929 Pid = pid()
5931 Info = [InfoTuple] | undefined
5932 InfoTuple = process_info_result_item()
5933 process_info_result_item() =
5934 {backtrace, Bin :: binary()} |
5935 {binary,
5936 BinInfo ::
5937 [{integer() >= 0,
5938 integer() >= 0,
5939 integer() >= 0}]} |
5940 {catchlevel, CatchLevel :: integer() >= 0} |
5941 {current_function,
5942 {Module :: module(), Function :: atom(), Arity :: arity()} |
5943 undefined} |
5944 {current_location,
5945 {Module :: module(),
5946 Function :: atom(),
5947 Arity :: arity(),
5948 Location ::
5949 [{file, Filename :: string()} |
5950 {line, Line :: integer() >= 1}]}} |
5951 {current_stacktrace, Stack :: [stack_item()]} |
5952 {dictionary, Dictionary :: [{Key :: term(), Value :: term()}]} |
5953 {error_handler, Module :: module()} |
5954 {garbage_collection, GCInfo :: [{atom(), integer() >= 0}]} |
5955 {garbage_collection_info,
5956 GCInfo :: [{atom(), integer() >= 0}]} |
5957 {group_leader, GroupLeader :: pid()} |
5958 {heap_size, Size :: integer() >= 0} |
5959 {initial_call, mfa()} |
5960 {links, PidsAndPorts :: [pid() | port()]} |
5961 {last_calls, false | (Calls :: [mfa()])} |
5962 {memory, Size :: integer() >= 0} |
5963 {message_queue_len, MessageQueueLen :: integer() >= 0} |
5964 {messages, MessageQueue :: [term()]} |
5965 {min_heap_size, MinHeapSize :: integer() >= 0} |
5966 {min_bin_vheap_size, MinBinVHeapSize :: integer() >= 0} |
5967 {max_heap_size, MaxHeapSize :: max_heap_size()} |
5968 {monitored_by,
5969 MonitoredBy :: [pid() | port() | nif_resource()]} |
5970 {monitors,
5971 Monitors ::
5972 [{process | port,
5973 Pid ::
5974 pid() |
5975 port() |
5976 {RegName :: atom(), Node :: node()}}]} |
5977 {message_queue_data, MQD :: message_queue_data()} |
5978 {priority, Level :: priority_level()} |
5979 {reductions, Number :: integer() >= 0} |
5980 {registered_name, [] | (Atom :: atom())} |
5981 {sequential_trace_token,
5982 [] | (SequentialTraceToken :: term())} |
5983 {stack_size, Size :: integer() >= 0} |
5984 {status,
5985 Status ::
5986 exiting | garbage_collecting | waiting | running |
5987 runnable | suspended} |
5988 {suspending,
5989 SuspendeeList ::
5990 [{Suspendee :: pid(),
5991 ActiveSuspendCount :: integer() >= 0,
5992 OutstandingSuspendCount :: integer() >= 0}]} |
5993 {total_heap_size, Size :: integer() >= 0} |
5994 {trace, InternalTraceFlags :: integer() >= 0} |
5995 {trap_exit, Boolean :: boolean()}
5996 priority_level() = low | normal | high | max
5997 stack_item() =
5998 {Module :: module(),
5999 Function :: atom(),
6000 Arity :: arity() | (Args :: [term()]),
6001 Location ::
6002 [{file, Filename :: string()} |
6003 {line, Line :: integer() >= 1}]}
6004 max_heap_size() =
6005 integer() >= 0 |
6006 #{size => integer() >= 0,
6007 kill => boolean(),
6008 error_logger => boolean()}
6009 message_queue_data() = off_heap | on_heap
6010 Returns a list containing InfoTuples with miscellaneous informa‐
6012 tion about the process identified by Pid, or undefined if the
6013 process is not alive.
6014 The order of the InfoTuples is undefined and all InfoTuples are
6016 not mandatory. The InfoTuples part of the result can be changed
6017 without prior notice.
6018 The InfoTuples with the following items are part of the result:
6020 * current_function
6022 * initial_call
6024 * status
6026 * message_queue_len
6028 * links
6030 * dictionary
6032 * trap_exit
6034 * error_handler
6036 * priority
6038 * group_leader
6040 * total_heap_size
6042 * heap_size
6044 * stack_size
6046 * reductions
6048 * garbage_collection
6050 If the process identified by Pid has a registered name, also an
6052 InfoTuple with item registered_name is included.
6053 For information about specific InfoTuples, see process_info/2.
6055 Warning:
6057 This BIF is intended for debugging only. For all other purposes,
6058 use process_info/2.
6059 Failure: badarg if Pid is not a local process.
6062 process_info(Pid, Item) -> InfoTuple | [] | undefined
6064 process_info(Pid, ItemList) -> InfoTupleList | [] | undefined
6066 Types:
6068 Pid = pid()
6070 ItemList = [Item]
6071 Item = process_info_item()
6072 InfoTupleList = [InfoTuple]
6073 InfoTuple = process_info_result_item()
6074 process_info_item() =
6075 backtrace | binary | catchlevel | current_function |
6076 current_location | current_stacktrace | dictionary |
6077 error_handler | garbage_collection | garbage_collection_info |
6078 group_leader | heap_size | initial_call | links | last_calls |
6079 memory | message_queue_len | messages | min_heap_size |
6080 min_bin_vheap_size | monitored_by | monitors |
6081 message_queue_data | priority | reductions | registered_name |
6082 sequential_trace_token | stack_size | status | suspending |
6083 total_heap_size | trace | trap_exit
6084 process_info_result_item() =
6085 {backtrace, Bin :: binary()} |
6086 {binary,
6087 BinInfo ::
6088 [{integer() >= 0,
6089 integer() >= 0,
6090 integer() >= 0}]} |
6091 {catchlevel, CatchLevel :: integer() >= 0} |
6092 {current_function,
6093 {Module :: module(), Function :: atom(), Arity :: arity()} |
6094 undefined} |
6095 {current_location,
6096 {Module :: module(),
6097 Function :: atom(),
6098 Arity :: arity(),
6099 Location ::
6100 [{file, Filename :: string()} |
6101 {line, Line :: integer() >= 1}]}} |
6102 {current_stacktrace, Stack :: [stack_item()]} |
6103 {dictionary, Dictionary :: [{Key :: term(), Value :: term()}]} |
6104 {error_handler, Module :: module()} |
6105 {garbage_collection, GCInfo :: [{atom(), integer() >= 0}]} |
6106 {garbage_collection_info,
6107 GCInfo :: [{atom(), integer() >= 0}]} |
6108 {group_leader, GroupLeader :: pid()} |
6109 {heap_size, Size :: integer() >= 0} |
6110 {initial_call, mfa()} |
6111 {links, PidsAndPorts :: [pid() | port()]} |
6112 {last_calls, false | (Calls :: [mfa()])} |
6113 {memory, Size :: integer() >= 0} |
6114 {message_queue_len, MessageQueueLen :: integer() >= 0} |
6115 {messages, MessageQueue :: [term()]} |
6116 {min_heap_size, MinHeapSize :: integer() >= 0} |
6117 {min_bin_vheap_size, MinBinVHeapSize :: integer() >= 0} |
6118 {max_heap_size, MaxHeapSize :: max_heap_size()} |
6119 {monitored_by,
6120 MonitoredBy :: [pid() | port() | nif_resource()]} |
6121 {monitors,
6122 Monitors ::
6123 [{process | port,
6124 Pid ::
6125 pid() |
6126 port() |
6127 {RegName :: atom(), Node :: node()}}]} |
6128 {message_queue_data, MQD :: message_queue_data()} |
6129 {priority, Level :: priority_level()} |
6130 {reductions, Number :: integer() >= 0} |
6131 {registered_name, [] | (Atom :: atom())} |
6132 {sequential_trace_token,
6133 [] | (SequentialTraceToken :: term())} |
6134 {stack_size, Size :: integer() >= 0} |
6135 {status,
6136 Status ::
6137 exiting | garbage_collecting | waiting | running |
6138 runnable | suspended} |
6139 {suspending,
6140 SuspendeeList ::
6141 [{Suspendee :: pid(),
6142 ActiveSuspendCount :: integer() >= 0,
6143 OutstandingSuspendCount :: integer() >= 0}]} |
6144 {total_heap_size, Size :: integer() >= 0} |
6145 {trace, InternalTraceFlags :: integer() >= 0} |
6146 {trap_exit, Boolean :: boolean()}
6147 stack_item() =
6148 {Module :: module(),
6149 Function :: atom(),
6150 Arity :: arity() | (Args :: [term()]),
6151 Location ::
6152 [{file, Filename :: string()} |
6153 {line, Line :: integer() >= 1}]}
6154 priority_level() = low | normal | high | max
6155 max_heap_size() =
6156 integer() >= 0 |
6157 #{size => integer() >= 0,
6158 kill => boolean(),
6159 error_logger => boolean()}
6160 message_queue_data() = off_heap | on_heap
6161 Returns information about the process identified by Pid, as
6163 specified by Item or ItemList. Returns undefined if the process
6164 is not alive.
6165 If the process is alive and a single Item is specified, the re‐
6167 turned value is the corresponding InfoTuple, unless Item =:=
6168 registered_name and the process has no registered name. In this
6169 case, [] is returned. This strange behavior is because of his‐
6170 torical reasons, and is kept for backward compatibility.
6171 If ItemList is specified, the result is InfoTupleList. The Info‐
6173 Tuples in InfoTupleList are included with the corresponding
6174 Items in the same order as the Items were included in ItemList.
6175 Valid Items can be included multiple times in ItemList.
6176 Getting process informations follows the signal ordering guaran‐
6178 tees described in the Processes Chapter in the Erlang Reference
6179 Manual .
6180 Note:
6182 If registered_name is part of ItemList and the process has no
6183 name registered, a {registered_name, []}, InfoTuple will be in‐
6184 cluded in the resulting InfoTupleList. This behavior is differ‐
6185 ent when a single Item =:= registered_name is specified, and
6186 when process_info/1 is used.
6187 Valid InfoTuples with corresponding Items:
6190 {backtrace, Bin}:
6192 Binary Bin contains the same information as the output from
6193 erlang:process_display(Pid, backtrace). Use binary_to_list/1
6194 to obtain the string of characters from the binary.
6195 {binary, BinInfo}:
6197 BinInfo is a list containing miscellaneous information about
6198 binaries on the heap of this process. This InfoTuple can be
6199 changed or removed without prior notice. In the current im‐
6200 plementation BinInfo is a list of tuples. The tuples con‐
6201 tain; BinaryId, BinarySize, BinaryRefcCount.
6202 Depending on the value of the message_queue_data process
6204 flag the message queue may be stored on the heap.
6205 {catchlevel, CatchLevel}:
6207 CatchLevel is the number of currently active catches in this
6208 process. This InfoTuple can be changed or removed without
6209 prior notice.
6210 {current_function, {Module, Function, Arity} | undefined}:
6212 Module, Function, Arity is the current function call of the
6213 process. The value undefined can be returned if the process
6214 is currently executing native compiled code.
6215 {current_location, {Module, Function, Arity, Location}}:
6217 Module, Function, Arity is the current function call of the
6218 process. Location is a list of two-tuples describing the lo‐
6219 cation in the source code.
6220 {current_stacktrace, Stack}:
6222 Returns the current call stack back-trace (stacktrace) of
6223 the process. The stack has the same format as in the catch
6224 part of a try. See The call-stack back trace (stacktrace).
6225 The depth of the stacktrace is truncated according to the
6226 backtrace_depth system flag setting.
6227 {dictionary, Dictionary}:
6229 Dictionary is the process dictionary.
6230 {error_handler, Module}:
6232 Module is the error handler module used by the process (for
6233 undefined function calls, for example).
6234 {garbage_collection, GCInfo}:
6236 GCInfo is a list containing miscellaneous information about
6237 garbage collection for this process. The content of GCInfo
6238 can be changed without prior notice.
6239 {garbage_collection_info, GCInfo}:
6241 GCInfo is a list containing miscellaneous detailed informa‐
6242 tion about garbage collection for this process. The content
6243 of GCInfo can be changed without prior notice. For details
6244 about the meaning of each item, see gc_minor_start in er‐
6245 lang:trace/3.
6246 {group_leader, GroupLeader}:
6248 GroupLeader is the group leader for the I/O of the process.
6249 {heap_size, Size}:
6251 Size is the size in words of the youngest heap generation of
6252 the process. This generation includes the process stack.
6253 This information is highly implementation-dependent, and can
6254 change if the implementation changes.
6255 {initial_call, {Module, Function, Arity}}:
6257 Module, Function, Arity is the initial function call with
6258 which the process was spawned.
6259 {links, PidsAndPorts}:
6261 PidsAndPorts is a list of process identifiers and port iden‐
6262 tifiers, with processes or ports to which the process has a
6263 link.
6264 {last_calls, false|Calls}:
6266 The value is false if call saving is not active for the
6267 process (see process_flag/3). If call saving is active, a
6268 list is returned, in which the last element is the most re‐
6269 cent called.
6270 {memory, Size}:
6272 Size is the size in bytes of the process. This includes call
6275 stack, heap, and internal structures.
6276 {message_queue_len, MessageQueueLen}:
6278 MessageQueueLen is the number of messages currently in the
6279 message queue of the process. This is the length of the list
6280 MessageQueue returned as the information item messages (see
6281 below).
6282 {messages, MessageQueue}:
6284 MessageQueue is a list of the messages to the process, which
6285 have not yet been processed.
6286 {min_heap_size, MinHeapSize}:
6288 MinHeapSize is the minimum heap size for the process.
6289 {min_bin_vheap_size, MinBinVHeapSize}:
6291 MinBinVHeapSize is the minimum binary virtual heap size for
6292 the process.
6293 {monitored_by, MonitoredBy}:
6295 A list of identifiers for all the processes, ports and NIF
6296 resources, that are monitoring the process.
6297 {monitors, Monitors}:
6299 A list of monitors (started by monitor/2) that are active
6300 for the process. For a local process monitor or a remote
6301 process monitor by a process identifier, the list consists
6302 of:
6303 {process, Pid}:
6305 Process is monitored by pid.
6306 {process, {RegName, Node}}:
6308 Local or remote process is monitored by name.
6309 {port, PortId}:
6311 Local port is monitored by port id.
6312 {port, {RegName, Node}}:
6314 Local port is monitored by name. Please note, that remote
6315 port monitors are not supported, so Node will always be
6316 the local node name.
6317 {message_queue_data, MQD}:
6319 MQD is the current value of the message_queue_data process
6320 flag, which can be either off_heap or on_heap. For more in‐
6321 formation, see the documentation of process_flag(mes‐
6322 sage_queue_data, MQD).
6323 {priority, Level}:
6325 Level is the current priority level for the process. For
6326 more information on priorities, see process_flag(priority,
6327 Level).
6328 {reductions, Number}:
6330 Number is the number of reductions executed by the process.
6331 {registered_name, Atom}:
6333 Atom is the registered process name. If the process has no
6334 registered name, this tuple is not present in the list.
6335 {sequential_trace_token, [] | SequentialTraceToken}:
6337 SequentialTraceToken is the sequential trace token for the
6338 process. This InfoTuple can be changed or removed without
6339 prior notice.
6340 {stack_size, Size}:
6342 Size is the stack size, in words, of the process.
6343 {status, Status}:
6345 Status is the status of the process and is one of the fol‐
6346 lowing:
6347 * exiting
6349 * garbage_collecting
6351 * waiting (for a message)
6353 * running
6355 * runnable (ready to run, but another process is running)
6357 * suspended (suspended on a "busy" port or by the BIF er‐
6359 lang:suspend_process/1,2)
6360 {suspending, SuspendeeList}:
6362 SuspendeeList is a list of {Suspendee, ActiveSuspendCount,
6363 OutstandingSuspendCount} tuples. Suspendee is the process
6364 identifier of a process that has been, or is to be, sus‐
6365 pended by the process identified by Pid through the BIF er‐
6366 lang:suspend_process/2 or erlang:suspend_process/1.
6367 ActiveSuspendCount is the number of times Suspendee has been
6369 suspended by Pid. OutstandingSuspendCount is the number of
6370 not yet completed suspend requests sent by Pid, that is:
6371 * If ActiveSuspendCount =/= 0, Suspendee is currently in the
6373 suspended state.
6374 * If OutstandingSuspendCount =/= 0, option asynchronous of
6376 erlang:suspend_process/2 has been used and the suspendee
6377 has not yet been suspended by Pid.
6378 Notice that ActiveSuspendCount and OutstandingSuspendCount
6380 are not the total suspend count on Suspendee, only the parts
6381 contributed by Pid.
6382 {total_heap_size, Size}:
6384 Size is the total size, in words, of all heap fragments of
6385 the process. This includes the process stack and any unre‐
6386 ceived messages that are considered to be part of the heap.
6387 {trace, InternalTraceFlags}:
6389 InternalTraceFlags is an integer representing the internal
6390 trace flag for this process. This InfoTuple can be changed
6391 or removed without prior notice.
6392 {trap_exit, Boolean}:
6394 Boolean is true if the process is trapping exits, otherwise
6395 false.
6396 Notice that not all implementations support all these Items.
6398 Failures:
6400 badarg:
6402 If Pid is not a local process.
6403 badarg:
6405 If Item is an invalid item.
6406 processes() -> [pid()]
6408 Returns a list of process identifiers corresponding to all the
6410 processes currently existing on the local node.
6411 Notice that an exiting process exists, but is not alive. That
6413 is, is_process_alive/1 returns false for an exiting process, but
6414 its process identifier is part of the result returned from pro‐
6415 cesses/0.
6416 Example:
6418 > processes().
6420 [<0.0.0>,<0.2.0>,<0.4.0>,<0.5.0>,<0.7.0>,<0.8.0>]
6421 purge_module(Module) -> true
6423 Types:
6425 Module = atom()
6427 Removes old code for Module. Before this BIF is used,
6429 check_process_code/2 is to be called to check that no processes
6430 execute old code in the module.
6431 Warning:
6433 This BIF is intended for the code server (see code(3)) and is
6434 not to be used elsewhere.
6435 Note:
6438 As from ERTS 8.0 (Erlang/OTP 19), any lingering processes that
6439 still execute the old code is killed by this function. In ear‐
6440 lier versions, such incorrect use could cause much more fatal
6441 failures, like emulator crash.
6442 Failure: badarg if there is no old code for Module.
6445 put(Key, Val) -> term()
6447 Types:
6449 Key = Val = term()
6451 Adds a new Key to the process dictionary, associated with the
6453 value Val, and returns undefined. If Key exists, the old value
6454 is deleted and replaced by Val, and the function returns the old
6455 value. The average time complexity for the current implementa‐
6456 tion of this function is O(1) and the worst case time complexity
6457 is O(N), where N is the number of items in the process dictio‐
6458 nary. Example:
6459 > X = put(name, walrus), Y = put(name, carpenter),
6461 Z = get(name),
6462 {X, Y, Z}.
6463 {undefined,walrus,carpenter}
6464 Note:
6466 The values stored when put is evaluated within the scope of a
6467 catch are not retracted if a throw is evaluated, or if an error
6468 occurs.
6469 erlang:raise(Class, Reason, Stacktrace) -> badarg
6472 Types:
6474 Class = error | exit | throw
6476 Reason = term()
6477 Stacktrace = raise_stacktrace() | stacktrace()
6478 raise_stacktrace() =
6479 [{module(), atom(), arity() | [term()]} |
6480 {function(), arity() | [term()]}]
6481 Raises an exception of the specified class, reason, and call
6483 stack backtrace (stacktrace).
6484 Class is error, exit, or throw. So, if it were not for the
6486 stacktrace, erlang:raise(Class, Reason, Stacktrace) is equiva‐
6487 lent to erlang:Class(Reason) (given that Class is a valid
6488 class).
6489 Reason can be any term.
6491 Stacktrace is a list as provided in a try-catch clause.
6493 try
6495 ...
6496 catch Class:Reason:Stacktrace ->
6497 ...
6498 end
6499 That is, a list of four-tuples {Module, Function, Arity | Args,
6501 ExtraInfo}, where Module and Function are atoms, and the third
6502 element is an integer arity or an argument list. The stacktrace
6503 can also contain {Fun, Args, ExtraInfo} tuples, where Fun is a
6504 local fun and Args is an argument list.
6505 Element ExtraInfo at the end is optional. Omitting it is equiva‐
6507 lent to specifying an empty list.
6508 The stacktrace is used as the exception stacktrace for the call‐
6510 ing process; it is truncated to the current maximum stacktrace
6511 depth.
6512 As evaluating this function causes the process to terminate, it
6514 has no return value unless the arguments are invalid, in which
6515 case the function returns the error reason badarg. If you want
6516 to be sure not to return, you can call error(erlang:raise(Class,
6517 Reason, Stacktrace)) and hope to distinguish exceptions later.
6518 See the reference manual about errors and error handling for
6520 more information about exception classes and how to catch excep‐
6521 tions.
6522 erlang:read_timer(TimerRef) -> Result
6524 Types:
6526 TimerRef = reference()
6528 Time = integer() >= 0
6529 Result = Time | false
6530 Reads the state of a timer. The same as calling er‐
6532 lang:read_timer(TimerRef, []).
6533 erlang:read_timer(TimerRef, Options) -> Result | ok
6535 Types:
6537 TimerRef = reference()
6539 Async = boolean()
6540 Option = {async, Async}
6541 Options = [Option]
6542 Time = integer() >= 0
6543 Result = Time | false
6544 Reads the state of a timer that has been created by either er‐
6546 lang:start_timer or erlang:send_after. TimerRef identifies the
6547 timer, and was returned by the BIF that created the timer.
6548 Options:
6550 {async, Async}:
6552 Asynchronous request for state information. Async defaults
6553 to false, which causes the operation to be performed syn‐
6554 chronously. In this case, the Result is returned by er‐
6555 lang:read_timer. When Async is true, erlang:read_timer sends
6556 an asynchronous request for the state information to the
6557 timer service that manages the timer, and then returns ok. A
6558 message on the format {read_timer, TimerRef, Result} is sent
6559 to the caller of erlang:read_timer when the operation has
6560 been processed.
6561 More Options can be added in the future.
6563 If Result is an integer, it represents the time in milliseconds
6565 left until the timer expires.
6566 If Result is false, a timer corresponding to TimerRef could not
6568 be found. This because the timer had expired, or been canceled,
6569 or because TimerRef never has corresponded to a timer. Even if
6570 the timer has expired, it does not tell you whether or not the
6571 time-out message has arrived at its destination yet.
6572 Note:
6574 The timer service that manages the timer can be co-located with
6575 another scheduler than the scheduler that the calling process is
6576 executing on. If so, communication with the timer service takes
6577 much longer time than if it is located locally. If the calling
6578 process is in a critical path, and can do other things while
6579 waiting for the result of this operation, you want to use option
6580 {async, true}. If using option {async, false}, the calling
6581 process is blocked until the operation has been performed.
6582 See also erlang:send_after/4, erlang:start_timer/4, and er‐
6585 lang:cancel_timer/2.
6586 ref_to_list(Ref) -> string()
6588 Types:
6590 Ref = reference()
6592 Returns a string corresponding to the text representation of
6594 Ref.
6595 Warning:
6597 This BIF is intended for debugging and is not to be used in ap‐
6598 plication programs.
6599 register(RegName, PidOrPort) -> true
6602 Types:
6604 RegName = atom()
6606 PidOrPort = port() | pid()
6607 Registers the name RegName with a process identifier (pid) or a
6609 port identifier in the name registry. RegName, which must be an
6610 atom, can be used instead of the pid or port identifier in send
6611 operator (RegName ! Message) and most other BIFs that take a pid
6612 or port identifies as an argument. Example:
6613 > register(db, Pid).
6615 true
6616 The registered name is considered a Directly Visible Erlang Re‐
6618 source and is automatically unregistered when the process termi‐
6619 nates.
6620 Failures:
6622 badarg:
6624 If PidOrPort is not an existing local process or port.
6625 badarg:
6627 If RegName is already in use.
6628 badarg:
6630 If the process or port is already registered (already has a
6631 name).
6632 badarg:
6634 If RegName is the atom undefined.
6635 registered() -> [RegName]
6637 Types:
6639 RegName = atom()
6641 Returns a list of names that have been registered using regis‐
6643 ter/2, for example:
6644 > registered().
6646 [code_server, file_server, init, user, my_db]
6647 erlang:resume_process(Suspendee) -> true
6649 Types:
6651 Suspendee = pid()
6653 Decreases the suspend count on the process identified by Sus‐
6655 pendee. Suspendee is previously to have been suspended through
6656 erlang:suspend_process/2 or erlang:suspend_process/1 by the
6657 process calling erlang:resume_process(Suspendee). When the sus‐
6658 pend count on Suspendee reaches zero, Suspendee is resumed, that
6659 is, its state is changed from suspended into the state it had
6660 before it was suspended.
6661 Warning:
6663 This BIF is intended for debugging only.
6664 Failures:
6667 badarg:
6669 If Suspendee is not a process identifier.
6670 badarg:
6672 If the process calling erlang:resume_process/1 had not pre‐
6673 viously increased the suspend count on the process identi‐
6674 fied by Suspendee.
6675 badarg:
6677 If the process identified by Suspendee is not alive.
6678 round(Number) -> integer()
6680 Types:
6682 Number = number()
6684 Returns an integer by rounding Number, for example:
6686 round(42.1).
6688 42
6689 round(5.5).
6691 6
6692 round(-5.5).
6694 -6
6695 round(36028797018963969.0).
6697 36028797018963968
6698 In the last example, round(36028797018963969.0) evaluates to
6700 36028797018963968. The reason for this is that the number
6701 36028797018963969.0 cannot be represented exactly as a float
6702 value. Instead, the float literal is represented as
6703 36028797018963968.0, which is the closest number that can be
6704 represented exactly as a float value. See Representation of
6705 Floating Point Numbers for additional information.
6706 Allowed in guard tests.
6708 self() -> pid()
6710 Returns the process identifier of the calling process, for exam‐
6712 ple:
6713 > self().
6715 <0.26.0>
6716 Allowed in guard tests.
6718 erlang:send(Dest, Msg) -> Msg
6720 Types:
6722 Dest = dst()
6724 Msg = term()
6725 dst() =
6726 pid() |
6727 reference() |
6728 port() |
6729 (RegName :: atom()) |
6730 {RegName :: atom(), Node :: node()}
6731 Sends a message and returns Msg. This is the same as using the
6733 send operator: Dest ! Msg.
6734 Dest can be a remote or local process identifier, an alias, a
6736 (local) port, a locally registered name, or a tuple {RegName,
6737 Node} for a registered name at another node.
6738 The function fails with a badarg run-time error if Dest is an
6740 atom name, but this name is not registered. This is the only
6741 case when send fails for an unreachable destination Dest (of
6742 correct type).
6743 erlang:send(Dest, Msg, Options) -> Res
6745 Types:
6747 Dest = dst()
6749 Msg = term()
6750 Options = [nosuspend | noconnect]
6751 Res = ok | nosuspend | noconnect
6752 dst() =
6753 pid() |
6754 reference() |
6755 port() |
6756 (RegName :: atom()) |
6757 {RegName :: atom(), Node :: node()}
6758 Either sends a message and returns ok, or does not send the mes‐
6760 sage but returns something else (see below). Otherwise the same
6761 as erlang:send/2. For more detailed explanation and warnings,
6762 see erlang:send_nosuspend/2,3.
6763 Options:
6765 nosuspend:
6767 If the sender would have to be suspended to do the send, no‐
6768 suspend is returned instead.
6769 noconnect:
6771 If the destination node would have to be auto-connected to
6772 do the send, noconnect is returned instead.
6773 Warning:
6775 As with erlang:send_nosuspend/2,3: use with extreme care.
6776 erlang:send_after(Time, Dest, Msg) -> TimerRef
6779 Types:
6781 Time = integer() >= 0
6783 Dest = pid() | atom()
6784 Msg = term()
6785 TimerRef = reference()
6786 Starts a timer. The same as calling erlang:send_after(Time,
6788 Dest, Msg, []).
6789 erlang:send_after(Time, Dest, Msg, Options) -> TimerRef
6791 Types:
6793 Time = integer()
6795 Dest = pid() | atom()
6796 Msg = term()
6797 Options = [Option]
6798 Abs = boolean()
6799 Option = {abs, Abs}
6800 TimerRef = reference()
6801 Starts a timer. When the timer expires, the message Msg is sent
6803 to the process identified by Dest. Apart from the format of the
6804 time-out message, this function works exactly as er‐
6805 lang:start_timer/4.
6806 erlang:send_nosuspend(Dest, Msg) -> boolean()
6808 Types:
6810 Dest = dst()
6812 Msg = term()
6813 dst() =
6814 pid() |
6815 reference() |
6816 port() |
6817 (RegName :: atom()) |
6818 {RegName :: atom(), Node :: node()}
6819 The same as erlang:send(Dest, Msg, [nosuspend]), but returns
6821 true if the message was sent and false if the message was not
6822 sent because the sender would have had to be suspended.
6823 This function is intended for send operations to an unreliable
6825 remote node without ever blocking the sending (Erlang) process.
6826 If the connection to the remote node (usually not a real Erlang
6827 node, but a node written in C or Java) is overloaded, this func‐
6828 tion does not send the message and returns false.
6829 The same occurs if Dest refers to a local port that is busy. For
6831 all other destinations (allowed for the ordinary send operator
6832 '!'), this function sends the message and returns true.
6833 This function is only to be used in rare circumstances where a
6835 process communicates with Erlang nodes that can disappear with‐
6836 out any trace, causing the TCP buffers and the drivers queue to
6837 be over-full before the node is shut down (because of tick time-
6838 outs) by net_kernel. The normal reaction to take when this oc‐
6839 curs is some kind of premature shutdown of the other node.
6840 Notice that ignoring the return value from this function would
6842 result in an unreliable message passing, which is contradictory
6843 to the Erlang programming model. The message is not sent if this
6844 function returns false.
6845 In many systems, transient states of overloaded queues are nor‐
6847 mal. Although this function returns false does not mean that the
6848 other node is guaranteed to be non-responsive, it could be a
6849 temporary overload. Also, a return value of true does only mean
6850 that the message can be sent on the (TCP) channel without block‐
6851 ing; the message is not guaranteed to arrive at the remote node.
6852 For a disconnected non-responsive node, the return value is true
6853 (mimics the behavior of operator !). The expected behavior and
6854 the actions to take when the function returns false are applica‐
6855 tion- and hardware-specific.
6856 Warning:
6858 Use with extreme care.
6859 erlang:send_nosuspend(Dest, Msg, Options) -> boolean()
6862 Types:
6864 Dest = dst()
6866 Msg = term()
6867 Options = [noconnect]
6868 dst() =
6869 pid() |
6870 reference() |
6871 port() |
6872 (RegName :: atom()) |
6873 {RegName :: atom(), Node :: node()}
6874 The same as erlang:send(Dest, Msg, [nosuspend | Options]), but
6876 with a Boolean return value.
6877 This function behaves like erlang:send_nosuspend/2, but takes a
6879 third parameter, a list of options. The only option is nocon‐
6880 nect, which makes the function return false if the remote node
6881 is not currently reachable by the local node. The normal behav‐
6882 ior is to try to connect to the node, which can stall the
6883 process during a short period. The use of option noconnect makes
6884 it possible to be sure not to get the slightest delay when send‐
6885 ing to a remote process. This is especially useful when communi‐
6886 cating with nodes that expect to always be the connecting part
6887 (that is, nodes written in C or Java).
6888 Whenever the function returns false (either when a suspend would
6890 occur or when noconnect was specified and the node was not al‐
6891 ready connected), the message is guaranteed not to have been
6892 sent.
6893 Warning:
6895 Use with extreme care.
6896 erlang:set_cookie(Cookie) -> true
6899 Types:
6901 Cookie = atom()
6903 Sets the magic cookie of the local node to the atom Cookie,
6905 which is also the cookie for all nodes that have no explicit
6906 cookie set with set_cookie/2 Cookie (see section Distributed
6907 Erlang in the Erlang Reference Manual in System Documentation).
6908 Failure: function_clause if the local node is not alive.
6910 erlang:set_cookie(Node, Cookie) -> true
6912 Types:
6914 Node = node()
6916 Cookie = atom()
6917 Sets the magic cookie for Node to the atom Cookie. If Node is
6919 the local node, the function sets the cookie of all other nodes
6920 (that have no explicit cookie set with this function) to Cookie
6921 (see section Distributed Erlang in the Erlang Reference Manual
6922 in System Documentation).
6923 Failure: function_clause if the local node is not alive.
6925 setelement(Index, Tuple1, Value) -> Tuple2
6927 Types:
6929 Index = integer() >= 1
6931 1..tuple_size(Tuple1)
6932 Tuple1 = Tuple2 = tuple()
6933 Value = term()
6934 Returns a tuple that is a copy of argument Tuple1 with the ele‐
6936 ment specified by integer argument Index (the first element is
6937 the element with index 1) replaced by argument Value, for exam‐
6938 ple:
6939 > setelement(2, {10, green, bottles}, red).
6941 {10,red,bottles}
6942 size(Item) -> integer() >= 0
6944 Types:
6946 Item = tuple() | binary()
6948 Returns the number of elements in a tuple or the number of bytes
6950 in a binary or bitstring, for example:
6951 > size({morni, mulle, bwange}).
6953 3
6954 > size(<<11, 22, 33>>).
6955 3
6956 For bitstrings, the number of whole bytes is returned. That is,
6958 if the number of bits in the bitstring is not divisible by 8,
6959 the resulting number of bytes is rounded down.
6960 Allowed in guard tests.
6962 See also tuple_size/1, byte_size/1, and bit_size/1.
6964 spawn(Fun) -> pid()
6966 Types:
6968 Fun = function()
6970 Returns the process identifier of a new process started by the
6972 application of Fun to the empty list []. Otherwise works like
6973 spawn/3.
6974 spawn(Node, Fun) -> pid()
6976 Types:
6978 Node = node()
6980 Fun = function()
6981 Returns the process identifier of a new process started by the
6983 application of Fun to the empty list [] on Node. If Node does
6984 not exist, a useless pid is returned. Otherwise works like
6985 spawn/3.
6986 spawn(Module, Function, Args) -> pid()
6988 Types:
6990 Module = module()
6992 Function = atom()
6993 Args = [term()]
6994 Returns the process identifier of a new process started by the
6996 application of Module:Function to Args.
6997 error_handler:undefined_function(Module, Function, Args) is
6999 evaluated by the new process if Module:Function/Arity does not
7000 exist (where Arity is the length of Args). The error handler can
7001 be redefined (see process_flag/2). If error_handler is unde‐
7002 fined, or the user has redefined the default error_handler and
7003 its replacement is undefined, a failure with reason undef oc‐
7004 curs.
7005 Example:
7007 > spawn(speed, regulator, [high_speed, thin_cut]).
7009 <0.13.1>
7010 spawn(Node, Module, Function, Args) -> pid()
7012 Types:
7014 Node = node()
7016 Module = module()
7017 Function = atom()
7018 Args = [term()]
7019 Returns the process identifier (pid) of a new process started by
7021 the application of Module:Function to Args on Node. If Node does
7022 not exist, a useless pid is returned. Otherwise works like
7023 spawn/3.
7024 spawn_link(Fun) -> pid()
7026 Types:
7028 Fun = function()
7030 Returns the process identifier of a new process started by the
7032 application of Fun to the empty list []. A link is created be‐
7033 tween the calling process and the new process, atomically. Oth‐
7034 erwise works like spawn/3.
7035 spawn_link(Node, Fun) -> pid()
7037 Types:
7039 Node = node()
7041 Fun = function()
7042 Returns the process identifier (pid) of a new process started by
7044 the application of Fun to the empty list [] on Node. A link is
7045 created between the calling process and the new process, atomi‐
7046 cally. If Node does not exist, a useless pid is returned and an
7047 exit signal with reason noconnection is sent to the calling
7048 process. Otherwise works like spawn/3.
7049 spawn_link(Module, Function, Args) -> pid()
7051 Types:
7053 Module = module()
7055 Function = atom()
7056 Args = [term()]
7057 Returns the process identifier of a new process started by the
7059 application of Module:Function to Args. A link is created be‐
7060 tween the calling process and the new process, atomically. Oth‐
7061 erwise works like spawn/3.
7062 spawn_link(Node, Module, Function, Args) -> pid()
7064 Types:
7066 Node = node()
7068 Module = module()
7069 Function = atom()
7070 Args = [term()]
7071 Returns the process identifier (pid) of a new process started by
7073 the application of Module:Function to Args on Node. A link is
7074 created between the calling process and the new process, atomi‐
7075 cally. If Node does not exist, a useless pid is returned and an
7076 exit signal with reason noconnection is sent to the calling
7077 process. Otherwise works like spawn/3.
7078 spawn_monitor(Fun) -> {pid(), reference()}
7080 Types:
7082 Fun = function()
7084 Returns the process identifier of a new process, started by the
7086 application of Fun to the empty list [], and a reference for a
7087 monitor created to the new process. Otherwise works like
7088 spawn/3.
7089 spawn_monitor(Node, Fun) -> {pid(), reference()}
7091 Types:
7093 Node = node()
7095 Fun = function()
7096 Returns the process identifier of a new process, started by the
7098 application of Fun to the empty list [] on the node Node, and a
7099 reference for a monitor created to the new process. Otherwise
7100 works like spawn/3.
7101 If the node identified by Node does not support distributed
7103 spawn_monitor(), the call will fail with a notsup exception.
7104 spawn_monitor(Module, Function, Args) -> {pid(), reference()}
7106 Types:
7108 Module = module()
7110 Function = atom()
7111 Args = [term()]
7112 A new process is started by the application of Module:Function
7114 to Args. The process is monitored at the same time. Returns the
7115 process identifier and a reference for the monitor. Otherwise
7116 works like spawn/3.
7117 spawn_monitor(Node, Module, Function, Args) ->
7119 {pid(), reference()}
7120 Types:
7122 Node = node()
7124 Module = module()
7125 Function = atom()
7126 Args = [term()]
7127 A new process is started by the application of Module:Function
7129 to Args on the node Node. The process is monitored at the same
7130 time. Returns the process identifier and a reference for the
7131 monitor. Otherwise works like spawn/3.
7132 If the node identified by Node does not support distributed
7134 spawn_monitor(), the call will fail with a notsup exception.
7135 spawn_opt(Fun, Options) -> pid() | {pid(), reference()}
7137 Types:
7139 Fun = function()
7141 Options = [spawn_opt_option()]
7142 priority_level() = low | normal | high | max
7143 max_heap_size() =
7144 integer() >= 0 |
7145 #{size => integer() >= 0,
7146 kill => boolean(),
7147 error_logger => boolean()}
7148 message_queue_data() = off_heap | on_heap
7149 spawn_opt_option() =
7150 link | monitor |
7151 {monitor, MonitorOpts :: [monitor_option()]} |
7152 {priority, Level :: priority_level()} |
7153 {fullsweep_after, Number :: integer() >= 0} |
7154 {min_heap_size, Size :: integer() >= 0} |
7155 {min_bin_vheap_size, VSize :: integer() >= 0} |
7156 {max_heap_size, Size :: max_heap_size()} |
7157 {message_queue_data, MQD :: message_queue_data()}
7158 Returns the process identifier (pid) of a new process started by
7160 the application of Fun to the empty list []. Otherwise works
7161 like spawn_opt/4.
7162 If option monitor is specified, the newly created process is
7164 monitored, and both the pid and reference for the monitor are
7165 returned.
7166 spawn_opt(Node, Fun, Options) -> pid() | {pid(), reference()}
7168 Types:
7170 Node = node()
7172 Fun = function()
7173 Options =
7174 [monitor | {monitor, [monitor_option()]} | link | Oth‐
7175 erOption]
7176 OtherOption = term()
7177 Returns the process identifier (pid) of a new process started by
7179 the application of Fun to the empty list [] on Node. If Node
7180 does not exist, a useless pid is returned. Otherwise works like
7181 spawn_opt/4.
7182 Valid options depends on what options are supported by the node
7184 identified by Node. A description of valid Options for the local
7185 node of current OTP version can be found in the documentation of
7186 spawn_opt/4.
7187 spawn_opt(Module, Function, Args, Options) ->
7189 Pid | {Pid, MonitorRef}
7190 Types:
7192 Module = module()
7194 Function = atom()
7195 Args = [term()]
7196 Options = [spawn_opt_option()]
7197 Pid = pid()
7198 MonitorRef = reference()
7199 priority_level() = low | normal | high | max
7200 max_heap_size() =
7201 integer() >= 0 |
7202 #{size => integer() >= 0,
7203 kill => boolean(),
7204 error_logger => boolean()}
7205 message_queue_data() = off_heap | on_heap
7206 spawn_opt_option() =
7207 link | monitor |
7208 {monitor, MonitorOpts :: [monitor_option()]} |
7209 {priority, Level :: priority_level()} |
7210 {fullsweep_after, Number :: integer() >= 0} |
7211 {min_heap_size, Size :: integer() >= 0} |
7212 {min_bin_vheap_size, VSize :: integer() >= 0} |
7213 {max_heap_size, Size :: max_heap_size()} |
7214 {message_queue_data, MQD :: message_queue_data()}
7215 Works as spawn/3, except that an extra option list is specified
7217 when creating the process.
7218 If option monitor is specified, the newly created process is
7220 monitored, and both the pid and reference for the monitor are
7221 returned.
7222 Options:
7224 link:
7226 Sets a link to the parent process (like spawn_link/3 does).
7227 monitor:
7229 Monitors the new process (like monitor(process, Pid) does).
7230 A {Pid, MonitorRef} tuple will be returned instead of just a
7231 Pid.
7232 {monitor, MonitorOpts}:
7234 Monitors the new process with options (like monitor(process,
7235 Pid, MonitorOpts) does). A {Pid, MonitorRef} tuple will be
7236 returned instead of just a Pid.
7237 {priority, Level}:
7239 Sets the priority of the new process. Equivalent to execut‐
7240 ing process_flag(priority, Level) in the start function of
7241 the new process, except that the priority is set before the
7242 process is selected for execution for the first time. For
7243 more information on priorities, see process_flag(priority,
7244 Level).
7245 {fullsweep_after, Number}:
7247 Useful only for performance tuning. Do not use this option
7248 unless you know that there is problem with execution times
7249 or memory consumption, and ensure that the option improves
7250 matters.
7251 The Erlang runtime system uses a generational garbage col‐
7253 lection scheme, using an "old heap" for data that has sur‐
7254 vived at least one garbage collection. When there is no more
7255 room on the old heap, a fullsweep garbage collection is
7256 done.
7257 Option fullsweep_after makes it possible to specify the max‐
7259 imum number of generational collections before forcing a
7260 fullsweep, even if there is room on the old heap. Setting
7261 the number to zero disables the general collection algo‐
7262 rithm, that is, all live data is copied at every garbage
7263 collection.
7264 A few cases when it can be useful to change fullsweep_after:
7266 * If binaries that are no longer used are to be thrown away
7268 as soon as possible. (Set Number to zero.)
7269 * A process that mostly have short-lived data is fullsweeped
7271 seldom or never, that is, the old heap contains mostly
7272 garbage. To ensure a fullsweep occasionally, set Number to
7273 a suitable value, such as 10 or 20.
7274 * In embedded systems with a limited amount of RAM and no
7276 virtual memory, you might want to preserve memory by set‐
7277 ting Number to zero. (The value can be set globally, see
7278 erlang:system_flag/2.)
7279 {min_heap_size, Size}:
7281 Useful only for performance tuning. Do not use this option
7282 unless you know that there is problem with execution times
7283 or memory consumption, and ensure that the option improves
7284 matters.
7285 Gives a minimum heap size, in words. Setting this value
7287 higher than the system default can speed up some processes
7288 because less garbage collection is done. However, setting a
7289 too high value can waste memory and slow down the system be‐
7290 cause of worse data locality. Therefore, use this option
7291 only for fine-tuning an application and to measure the exe‐
7292 cution time with various Size values.
7293 {min_bin_vheap_size, VSize}:
7295 Useful only for performance tuning. Do not use this option
7296 unless you know that there is problem with execution times
7297 or memory consumption, and ensure that the option improves
7298 matters.
7299 Gives a minimum binary virtual heap size, in words. Setting
7301 this value higher than the system default can speed up some
7302 processes because less garbage collection is done. However,
7303 setting a too high value can waste memory. Therefore, use
7304 this option only for fine-tuning an application and to mea‐
7305 sure the execution time with various VSize values.
7306 {max_heap_size, Size}:
7308 Sets the max_heap_size process flag. The default
7309 max_heap_size is determined by command-line argument +hmax
7310 in erl(1). For more information, see the documentation of
7311 process_flag(max_heap_size, Size).
7312 {message_queue_data, MQD}:
7314 Sets the value of the message_queue_data process flag. MQD
7315 can be either off_heap or on_heap. The default value of the
7316 message_queue_data process flag is determined by the com‐
7317 mand-line argument +hmqd in erl(1). For more information,
7318 see the documentation of process_flag(message_queue_data,
7319 MQD).
7320 spawn_opt(Node, Module, Function, Args, Options) ->
7322 pid() | {pid(), reference()}
7323 Types:
7325 Node = node()
7327 Module = module()
7328 Function = atom()
7329 Args = [term()]
7330 Options =
7331 [monitor | {monitor, [monitor_option()]} | link | Oth‐
7332 erOption]
7333 OtherOption = term()
7334 Returns the process identifier (pid) of a new process started by
7336 the application of Module:Function to Args on Node. If Node does
7337 not exist, a useless pid is returned. Otherwise works like
7338 spawn_opt/4.
7339 Valid options depends on what options are supported by the node
7341 identified by Node. A description of valid Options for the local
7342 node of current OTP version can be found in the documentation of
7343 spawn_opt/4.
7344 spawn_request(Fun) -> ReqId
7346 Types:
7348 Fun = function()
7350 ReqId = reference()
7351 The same as the call spawn_request(node(),Fun,[]). That is, a
7353 spawn request on the local node with no options.
7354 spawn_request(Fun, Options) -> ReqId
7356 Types:
7358 Fun = function()
7360 Option =
7361 {reply_tag, ReplyTag} | {reply, Reply} | spawn_opt_op‐
7362 tion()
7363 ReplyTag = term()
7364 Reply = yes | no | error_only | success_only
7365 Options = [Option]
7366 ReqId = reference()
7367 The same as the call spawn_request(node(),Fun,Options). That is,
7369 a spawn request on the local node.
7370 spawn_request(Node, Fun) -> ReqId
7372 Types:
7374 Node = node()
7376 Fun = function()
7377 ReqId = reference()
7378 The same as the call spawn_request(Node,Fun,[]). That is, a
7380 spawn request with no options.
7381 spawn_request(Node, Fun, Options) -> ReqId
7383 Types:
7385 Node = node()
7387 Fun = function()
7388 Options = [Option]
7389 Option =
7390 monitor |
7391 {monitor, [monitor_option()]} |
7392 link |
7393 {reply_tag, ReplyTag} |
7394 {reply, Reply} |
7395 OtherOption
7396 ReplyTag = term()
7397 Reply = yes | no | error_only | success_only
7398 OtherOption = term()
7399 ReqId = reference()
7400 The same as spawn_request(Node,erlang,apply,[Fun,[]],Options).
7402 That is, a spawn request using the fun Fun of arity zero as en‐
7403 try point.
7404 This function will fail with a badarg exception if:
7406 * Node is not an atom.
7408 * Fun is not a fun of arity zero.
7410 * Options is not a proper list of terms.
7412 spawn_request(Module, Function, Args) -> ReqId
7414 Types:
7416 Module = module()
7418 Function = atom()
7419 Args = [term()]
7420 ReqId = reference()
7421 The same as the call spawn_request(node(),Module,Func‐
7423 tion,Args,[]). That is, a spawn request on the local node with
7424 no options.
7425 spawn_request(Node, Module, Function, Args) -> ReqId
7427 Types:
7429 Node = node()
7431 Module = module()
7432 Function = atom()
7433 Args = [term()]
7434 ReqId = reference()
7435 The same as the call spawn_request(Node,Module,Func‐
7437 tion,Args,[]). That is, a spawn request with no options.
7438 spawn_request(Module, Function, Args, Options) -> ReqId
7440 Types:
7442 Module = module()
7444 Function = atom()
7445 Args = [term()]
7446 Option =
7447 {reply_tag, ReplyTag} | {reply, Reply} | spawn_opt_op‐
7448 tion()
7449 ReplyTag = term()
7450 Reply = yes | no | error_only | success_only
7451 Options = [Option]
7452 ReqId = reference()
7453 The same as the call spawn_request(node(),Module,Func‐
7455 tion,Args,Options). That is, a spawn request on the local node.
7456 spawn_request(Node, Module, Function, Args, Options) -> ReqId
7458 Types:
7460 Node = node()
7462 Module = module()
7463 Function = atom()
7464 Args = [term()]
7465 Options = [Option]
7466 Option =
7467 monitor |
7468 {monitor, [monitor_option()]} |
7469 link |
7470 {reply_tag, ReplyTag} |
7471 {reply, Reply} |
7472 OtherOption
7473 ReplyTag = term()
7474 Reply = yes | no | error_only | success_only
7475 OtherOption = term()
7476 ReqId = reference()
7477 Asynchronously send a spawn request. Returns a request identi‐
7479 fier ReqId.
7480 If the spawn operation succeeds, a new process is created on the
7482 node identified by Node. When a spawn operation succeeds, the
7483 caller will by default be sent a message on the form {ReplyTag,
7484 ReqId, ok, Pid} where Pid is the process identifier of the newly
7485 created process. Such a message is referred to as a success mes‐
7486 sage below in the text. ReplyTag is by default the atom
7487 spawn_reply unless modified by the {reply_tag, ReplyTag} option.
7488 The new process is started by the application of Module:Function
7489 to Args.
7490 The spawn operation fails either if creation of a new process
7492 failed or if the spawn operation was interrupted by a connection
7493 failure. When a spawn operation fails, the caller will by de‐
7494 fault be sent a message on the form {ReplyTag, ReqId, error,
7495 Reason} where Reason is the error reason. Such a message is re‐
7496 ferred to as an error message below in the text. Currently the
7497 following spawn error Reasons are defined, but other reasons can
7498 appear at any time without prior notice:
7499 badopt:
7501 An invalid Option was passed as argument. Note that differ‐
7502 ent runtime systems may support different options.
7503 notsup:
7505 The node identified by Node does not support spawn opera‐
7506 tions issued by spawn_request().
7507 noconnection:
7509 Failure to set up a connection to the node identified by
7510 Node or the connection to that node was lost during the
7511 spawn operation. In the case the connection was lost, a
7512 process may or may not have been created.
7513 system_limit:
7515 Could not create a new process due to that some system limit
7516 was reached. Typically the process table was full.
7517 Valid Options:
7519 monitor:
7521 In the absence of spawn operation failures, atomically sets
7522 up a monitor to the newly created process. That is, as if
7523 the calling process had called monitor(process, Pid) where
7524 Pid is the process identifier of the newly created process.
7525 The ReqId returned by spawn_request() is also used as moni‐
7526 tor reference as if it was returned from monitor(process,
7527 Pid).
7528 The monitor will not be activated for the calling process
7530 until the spawn operation has succeeded. The monitor can not
7531 be demonitored before the operation has succeeded. A 'DOWN'
7532 message for the corresponding monitor is guaranteed not to
7533 be delivered before a success message that corresponds to
7534 the spawn operation. If the spawn operation fails, no 'DOWN'
7535 message will be delivered.
7536 If the connection between the nodes involved in the spawn
7538 operation is lost during the spawn operation, the spawn op‐
7539 eration will fail with an error reason of noconnection. A
7540 new process may or may not have been created.
7541 {monitor, MonitorOpts}:
7543 In the absence of spawn operation failures, atomically sets
7544 up a monitor to the newly created process. That is, as if
7545 the calling process had called monitor(process, Pid, Moni‐
7546 torOpts) where Pid is the process identifier of the newly
7547 created process. See the monitor option above for more in‐
7548 formation.
7549 Note that the monitor will not be activated for the calling
7551 process until the spawn operation has succeeded. For exam‐
7552 ple, in the case that an alias is created using the monitor
7553 option, the alias will not be active until the monitor is
7554 activated.
7555 link:
7557 In absence of spawn operation failures, atomically sets up a
7558 link between the calling process and the newly created
7559 process. That is, as if the calling process had called
7560 link(Pid) where Pid is the process identifier of the newly
7561 created process.
7562 The link will not be activated for the calling process until
7564 the spawn operation has succeeded. The link can not be re‐
7565 moved before the operation has succeeded. An exit signal due
7566 to the link is guaranteed not to be delivered before a suc‐
7567 cess message that corresponds to the spawn operation. If
7568 the spawn operation fails, no exit signal due to the link
7569 will be delivered to the caller of spawn_request().
7570 If the connection between the nodes involved in the spawn
7572 operation is lost during the spawn operation, the spawn op‐
7573 eration will fail with an error reason of noconnection. A
7574 new process may or may not have been created. If it has been
7575 created, it will be delivered an exit signal with an exit
7576 reason of noconnection.
7577 {reply, Reply}:
7579 Valid Reply values:
7580 yes:
7582 A spawn reply message will be sent to the caller regard‐
7583 less of whether the operation succeeds or not. If the call
7584 to spawn_request() returns without raising an exception
7585 and the reply option is set to yes, the caller is guaran‐
7586 teed to be delivered either a success message or an error
7587 message . The reply option is by default set to yes.
7588 no:
7590 No spawn reply message will be sent to the caller when the
7591 spawn operation completes. This regardless of whether the
7592 operation succeeds or not.
7593 error_only:
7595 No spawn reply message will be sent to the caller if the
7596 spawn operation succeeds, but an error message will be
7597 sent to the caller if the operation fails.
7598 success_only:
7600 No spawn reply message will be sent to the caller if the
7601 spawn operation fails, but a success message will be sent
7602 to the caller if the operation succeeds.
7603 {reply_tag, ReplyTag}:
7605 Sets the reply tag to ReplyTag in the reply message. That
7606 is, in the success or error message that is sent to the
7607 caller due to the spawn operation. The default reply tag is
7608 the atom spawn_reply.
7609 OtherOption:
7611 Other valid options depends on what options are supported by
7612 the node identified by Node. A description of other valid
7613 Options for the local node of current OTP version can be
7614 found in the documentation of spawn_opt/4.
7615 This function will fail with a badarg exception if:
7617 * Node is not an atom.
7619 * Module is not an atom.
7621 * Function is not an atom.
7623 * Args is not a proper list of terms.
7625 * Options is not a proper list of terms.
7627 Note that not all individual Options are checked when the spawn
7629 request is sent. Some Options can only be checked on reception
7630 of the request. Therefore an invalid option does not cause a
7631 badarg exception, but will cause the spawn operation to fail
7632 with an error reason of badopt.
7633 A spawn request can be abandoned by calling spawn_request_aban‐
7635 don/1.
7636 spawn_request_abandon(ReqId :: reference()) -> boolean()
7638 Abandon a previously issued spawn request. ReqId corresponds to
7640 a request identifier previously returned by spawn_request() in a
7641 call from current process. That is, only the process that has
7642 made the request can abandon the request.
7643 A spawn request can only be successfully abandoned until the
7645 spawn request has completed. When a spawn request has been suc‐
7646 cessfully abandoned, the caller will not be effected by future
7647 direct effects of the spawn request itself. For example, it will
7648 not receive a spawn reply message. The request is however not
7649 withdrawn, so a new process may or may not be created due to the
7650 request. If a new process is created after the spawn request was
7651 abandoned, no monitors nor links will be set up to the caller of
7652 spawn_request_abandon/1 due to the spawn request. If the spawn
7653 request included the link option, the process created due to
7654 this request will be sent an exit signal from its parent with
7655 the exit reason abandoned when it is detected that the spawn op‐
7656 eration has succeeded.
7657 Note:
7659 A process created due to a spawn request that has been abandoned
7660 may communicate with its parent as any other process. It is only
7661 the direct effects on the parent of the actual spawn request,
7662 that will be canceled by abandoning a spawn request.
7663 Return values:
7666 true:
7668 The spawn request was successfully abandoned.
7669 false:
7671 No spawn request was abandoned. The ReqId request identifier
7672 did not correspond to an outstanding spawn request issued by
7673 the calling process. The reason for this is either:
7674 * ReqId corresponds to a spawn request previoulsy made by
7676 the calling process. The spawn operation has completed and
7677 a spawn reply has already been delivered to the calling
7678 process unless the spawn reply was disabled in the re‐
7679 quest.
7680 * ReqId does not correspond to a spawn request that has been
7682 made by the calling process.
7683 This function fail with a badarg exception if ReqId is not a
7685 reference.
7686 split_binary(Bin, Pos) -> {binary(), binary()}
7688 Types:
7690 Bin = binary()
7692 Pos = integer() >= 0
7693 0..byte_size(Bin)
7694 Returns a tuple containing the binaries that are the result of
7696 splitting Bin into two parts at position Pos. This is not a de‐
7697 structive operation. After the operation, there are three bina‐
7698 ries altogether. Example:
7699 > B = list_to_binary("0123456789").
7701 <<"0123456789">>
7702 > byte_size(B).
7703 10
7704 > {B1, B2} = split_binary(B,3).
7705 {<<"012">>,<<"3456789">>}
7706 > byte_size(B1).
7707 3
7708 > byte_size(B2).
7709 7
7710 erlang:start_timer(Time, Dest, Msg) -> TimerRef
7712 Types:
7714 Time = integer() >= 0
7716 Dest = pid() | atom()
7717 Msg = term()
7718 TimerRef = reference()
7719 Starts a timer. The same as calling erlang:start_timer(Time,
7721 Dest, Msg, []).
7722 erlang:start_timer(Time, Dest, Msg, Options) -> TimerRef
7724 Types:
7726 Time = integer()
7728 Dest = pid() | atom()
7729 Msg = term()
7730 Options = [Option]
7731 Abs = boolean()
7732 Option = {abs, Abs}
7733 TimerRef = reference()
7734 Starts a timer. When the timer expires, the message {timeout,
7736 TimerRef, Msg} is sent to the process identified by Dest.
7737 Options:
7739 {abs, false}:
7741 This is the default. It means the Time value is interpreted
7742 as a time in milliseconds relative current Erlang monotonic
7743 time.
7744 {abs, true}:
7746 Absolute Time value. The Time value is interpreted as an ab‐
7747 solute Erlang monotonic time in milliseconds.
7748 More Options can be added in the future.
7750 The absolute point in time, the timer is set to expire on, must
7752 be in the interval [ erlang:convert_time_unit(erlang:sys‐
7753 tem_info(start_time), native, millisecond), erlang:con‐
7754 vert_time_unit(erlang:system_info(end_time), native, millisec‐
7755 ond) ]. If a relative time is specified, the Time value is not
7756 allowed to be negative.
7757 If Dest is a pid(), it must be a pid() of a process created on
7759 the current runtime system instance. This process has either
7760 terminated or not. If Dest is an atom(), it is interpreted as
7761 the name of a locally registered process. The process referred
7762 to by the name is looked up at the time of timer expiration. No
7763 error is returned if the name does not refer to a process.
7764 If Dest is a pid(), the timer is automatically canceled if the
7766 process referred to by the pid() is not alive, or if the process
7767 exits. This feature was introduced in ERTS 5.4.11. Notice that
7768 timers are not automatically canceled when Dest is an atom().
7769 See also erlang:send_after/4, erlang:cancel_timer/2, and er‐
7771 lang:read_timer/2.
7772 Failure: badarg if the arguments do not satisfy the requirements
7774 specified here.
7775 statistics(Item :: active_tasks) -> [ActiveTasks]
7777 Types:
7779 ActiveTasks = integer() >= 0
7781 Returns the same as statistics(active_tasks_all) with the excep‐
7783 tion that no information about the dirty IO run queue and its
7784 associated schedulers is part of the result. That is, only tasks
7785 that are expected to be CPU bound are part of the result.
7786 statistics(Item :: active_tasks_all) -> [ActiveTasks]
7788 Types:
7790 ActiveTasks = integer() >= 0
7792 Returns a list where each element represents the amount of ac‐
7794 tive processes and ports on each run queue and its associated
7795 schedulers. That is, the number of processes and ports that are
7796 ready to run, or are currently running. Values for normal run
7797 queues and their associated schedulers are located first in the
7798 resulting list. The first element corresponds to scheduler num‐
7799 ber 1 and so on. If support for dirty schedulers exist, an ele‐
7800 ment with the value for the dirty CPU run queue and its associ‐
7801 ated dirty CPU schedulers follow and then as last element the
7802 value for the the dirty IO run queue and its associated dirty IO
7803 schedulers follow. The information is not gathered atomically.
7804 That is, the result is not necessarily a consistent snapshot of
7805 the state, but instead quite efficiently gathered.
7806 Note:
7808 Each normal scheduler has one run queue that it manages. If
7809 dirty schedulers schedulers are supported, all dirty CPU sched‐
7810 ulers share one run queue, and all dirty IO schedulers share one
7811 run queue. That is, we have multiple normal run queues, one
7812 dirty CPU run queue and one dirty IO run queue. Work can not mi‐
7813 grate between the different types of run queues. Only work in
7814 normal run queues can migrate to other normal run queues. This
7815 has to be taken into account when evaluating the result.
7816 See also statistics(total_active_tasks), statis‐
7819 tics(run_queue_lengths), statistics(run_queue_lengths_all), sta‐
7820 tistics(total_run_queue_lengths), and statistics(to‐
7821 tal_run_queue_lengths_all).
7822 statistics(Item :: context_switches) -> {ContextSwitches, 0}
7824 Types:
7826 ContextSwitches = integer() >= 0
7828 Returns the total number of context switches since the system
7830 started.
7831 statistics(Item :: exact_reductions) ->
7833 {Total_Exact_Reductions,
7834 Exact_Reductions_Since_Last_Call}
7835 Types:
7837 Total_Exact_Reductions = Exact_Reductions_Since_Last_Call =
7839 integer() >= 0
7840 Returns the number of exact reductions.
7842 Note:
7844 statistics(exact_reductions) is a more expensive operation than
7845 statistics(reductions).
7846 statistics(Item :: garbage_collection) ->
7849 {Number_of_GCs, Words_Reclaimed, 0}
7850 Types:
7852 Number_of_GCs = Words_Reclaimed = integer() >= 0
7854 Returns information about garbage collection, for example:
7856 > statistics(garbage_collection).
7858 {85,23961,0}
7859 This information can be invalid for some implementations.
7861 statistics(Item :: io) -> {{input, Input}, {output, Output}}
7863 Types:
7865 Input = Output = integer() >= 0
7867 Returns Input, which is the total number of bytes received
7869 through ports, and Output, which is the total number of bytes
7870 output to ports.
7871 statistics(Item :: microstate_accounting) ->
7873 [MSAcc_Thread] | undefined
7874 Types:
7876 MSAcc_Thread =
7878 #{type := MSAcc_Thread_Type,
7879 id := MSAcc_Thread_Id,
7880 counters := MSAcc_Counters}
7881 MSAcc_Thread_Type =
7882 async | aux | dirty_io_scheduler | dirty_cpu_scheduler |
7883 poll | scheduler
7884 MSAcc_Thread_Id = integer() >= 0
7885 MSAcc_Counters = #{MSAcc_Thread_State => integer() >= 0}
7886 MSAcc_Thread_State =
7887 alloc | aux | bif | busy_wait | check_io | emulator | ets
7888 |
7889 gc | gc_fullsweep | nif | other | port | send | sleep |
7890 timers
7891 Microstate accounting can be used to measure how much time the
7893 Erlang runtime system spends doing various tasks. It is designed
7894 to be as lightweight as possible, but some overhead exists when
7895 this is enabled. Microstate accounting is meant to be a profil‐
7896 ing tool to help finding performance bottlenecks. To
7897 start/stop/reset microstate accounting, use system flag mi‐
7898 crostate_accounting.
7899 statistics(microstate_accounting) returns a list of maps repre‐
7901 senting some of the OS threads within ERTS. Each map contains
7902 type and id fields that can be used to identify what thread it
7903 is, and also a counters field that contains data about how much
7904 time has been spent in the various states.
7905 Example:
7907 > erlang:statistics(microstate_accounting).
7909 [#{counters => #{aux => 1899182914,
7910 check_io => 2605863602,
7911 emulator => 45731880463,
7912 gc => 1512206910,
7913 other => 5421338456,
7914 port => 221631,
7915 sleep => 5150294100},
7916 id => 1,
7917 type => scheduler}|...]
7918 The time unit is the same as returned by os:perf_counter/0. So,
7920 to convert it to milliseconds, you can do something like this:
7921 lists:map(
7923 fun(#{ counters := Cnt } = M) ->
7924 MsCnt = maps:map(fun(_K, PerfCount) ->
7925 erlang:convert_time_unit(PerfCount, perf_counter, 1000)
7926 end, Cnt),
7927 M#{ counters := MsCnt }
7928 end, erlang:statistics(microstate_accounting)).
7929 Notice that these values are not guaranteed to be the exact time
7931 spent in each state. This is because of various optimisation
7932 done to keep the overhead as small as possible.
7933 MSAcc_Thread_Types:
7935 scheduler:
7937 The main execution threads that do most of the work. See erl
7938 +S for more details.
7939 dirty_cpu_scheduler:
7941 The threads for long running cpu intensive work. See erl
7942 +SDcpu for more details.
7943 dirty_io_scheduler:
7945 The threads for long running I/O work. See erl +SDio for
7946 more details.
7947 async:
7949 Async threads are used by various linked-in drivers (mainly
7950 the file drivers) do offload non-CPU intensive work. See erl
7951 +A for more details.
7952 aux:
7954 Takes care of any work that is not specifically assigned to
7955 a scheduler.
7956 poll:
7958 Does the IO polling for the emulator. See erl +IOt for more
7959 details.
7960 The following MSAcc_Thread_States are available. All states are
7962 exclusive, meaning that a thread cannot be in two states at
7963 once. So, if you add the numbers of all counters in a thread,
7964 you get the total runtime for that thread.
7965 aux:
7967 Time spent handling auxiliary jobs.
7968 check_io:
7970 Time spent checking for new I/O events.
7971 emulator:
7973 Time spent executing Erlang processes.
7974 gc:
7976 Time spent doing garbage collection. When extra states are
7977 enabled this is the time spent doing non-fullsweep garbage
7978 collections.
7979 other:
7981 Time spent doing unaccounted things.
7982 port:
7984 Time spent executing ports.
7985 sleep:
7987 Time spent sleeping.
7988 More fine-grained MSAcc_Thread_States can be added through con‐
7990 figure (such as ./configure --with-microstate-accounting=extra).
7991 Enabling these states causes performance degradation when mi‐
7992 crostate accounting is turned off and increases the overhead
7993 when it is turned on.
7994 alloc:
7996 Time spent managing memory. Without extra states this time
7997 is spread out over all other states.
7998 bif:
8000 Time spent in BIFs. Without extra states this time is part
8001 of the emulator state.
8002 busy_wait:
8004 Time spent busy waiting. This is also the state where a
8005 scheduler no longer reports that it is active when using
8006 statistics(scheduler_wall_time). So, if you add all other
8007 states but this and sleep, and then divide that by all time
8008 in the thread, you should get something very similar to the
8009 scheduler_wall_time fraction. Without extra states this time
8010 is part of the other state.
8011 ets:
8013 Time spent executing ETS BIFs. Without extra states this
8014 time is part of the emulator state.
8015 gc_full:
8017 Time spent doing fullsweep garbage collection. Without extra
8018 states this time is part of the gc state.
8019 nif:
8021 Time spent in NIFs. Without extra states this time is part
8022 of the emulator state.
8023 send:
8025 Time spent sending messages (processes only). Without extra
8026 states this time is part of the emulator state.
8027 timers:
8029 Time spent managing timers. Without extra states this time
8030 is part of the other state.
8031 The utility module msacc(3) can be used to more easily analyse
8033 these statistics.
8034 Returns undefined if system flag microstate_accounting is turned
8036 off.
8037 The list of thread information is unsorted and can appear in
8039 different order between calls.
8040 Note:
8042 The threads and states are subject to change without any prior
8043 notice.
8044 statistics(Item :: reductions) ->
8047 {Total_Reductions, Reductions_Since_Last_Call}
8048 Types:
8050 Total_Reductions = Reductions_Since_Last_Call = integer() >=
8052 0
8053 Returns information about reductions, for example:
8055 > statistics(reductions).
8057 {2046,11}
8058 Note:
8060 As from ERTS 5.5 (Erlang/OTP R11B), this value does not include
8061 reductions performed in current time slices of currently sched‐
8062 uled processes. If an exact value is wanted, use statistics(ex‐
8063 act_reductions).
8064 statistics(Item :: run_queue) -> integer() >= 0
8067 Returns the total length of all normal and dirty CPU run queues.
8069 That is, queued work that is expected to be CPU bound. The in‐
8070 formation is gathered atomically. That is, the result is a con‐
8071 sistent snapshot of the state, but this operation is much more
8072 expensive compared to statistics(total_run_queue_lengths), espe‐
8073 cially when a large amount of schedulers is used.
8074 statistics(Item :: run_queue_lengths) -> [RunQueueLength]
8076 Types:
8078 RunQueueLength = integer() >= 0
8080 Returns the same as statistics(run_queue_lengths_all) with the
8082 exception that no information about the dirty IO run queue is
8083 part of the result. That is, only run queues with work that is
8084 expected to be CPU bound is part of the result.
8085 statistics(Item :: run_queue_lengths_all) -> [RunQueueLength]
8087 Types:
8089 RunQueueLength = integer() >= 0
8091 Returns a list where each element represents the amount of pro‐
8093 cesses and ports ready to run for each run queue. Values for
8094 normal run queues are located first in the resulting list. The
8095 first element corresponds to the normal run queue of scheduler
8096 number 1 and so on. If support for dirty schedulers exist, val‐
8097 ues for the dirty CPU run queue and the dirty IO run queue fol‐
8098 low (in that order) at the end. The information is not gathered
8099 atomically. That is, the result is not necessarily a consistent
8100 snapshot of the state, but instead quite efficiently gathered.
8101 Note:
8103 Each normal scheduler has one run queue that it manages. If
8104 dirty schedulers schedulers are supported, all dirty CPU sched‐
8105 ulers share one run queue, and all dirty IO schedulers share one
8106 run queue. That is, we have multiple normal run queues, one
8107 dirty CPU run queue and one dirty IO run queue. Work can not mi‐
8108 grate between the different types of run queues. Only work in
8109 normal run queues can migrate to other normal run queues. This
8110 has to be taken into account when evaluating the result.
8111 See also statistics(run_queue_lengths), statistics(to‐
8114 tal_run_queue_lengths_all), statistics(total_run_queue_lengths),
8115 statistics(active_tasks), statistics(active_tasks_all), and sta‐
8116 tistics(total_active_tasks), statistics(total_active_tasks_all).
8117 statistics(Item :: runtime) ->
8119 {Total_Run_Time, Time_Since_Last_Call}
8120 Types:
8122 Total_Run_Time = Time_Since_Last_Call = integer() >= 0
8124 Returns information about runtime, in milliseconds.
8126 This is the sum of the runtime for all threads in the Erlang
8128 runtime system and can therefore be greater than the wall clock
8129 time.
8130 Warning:
8132 This value might wrap due to limitations in the underlying func‐
8133 tionality provided by the operating system that is used.
8134 Example:
8137 > statistics(runtime).
8139 {1690,1620}
8140 statistics(Item :: scheduler_wall_time) ->
8142 [{SchedulerId, ActiveTime, TotalTime}] | undefined
8143 Types:
8145 SchedulerId = integer() >= 1
8147 ActiveTime = TotalTime = integer() >= 0
8148 Returns information describing how much time normal and dirty
8150 CPU schedulers in the system have been busy. This value is nor‐
8151 mally a better indicator of how much load an Erlang node is un‐
8152 der instead of looking at the CPU utilization privided by tools
8153 such as top or sysstat. This is because scheduler_wall_time also
8154 includes time where the scheduler is waiting for some other rea‐
8155 source (such as an internal mutex) to be available but does not
8156 use the CPU. In order to better understand what a scheduler is
8157 busy doing you can use microstate accounting.
8158 The definition of a busy scheduler is when it is not idle and
8160 not busy waiting for new work, that is:
8161 * Executing process code
8163 * Executing linked-in driver or NIF code
8165 * Executing BIFs, or any other runtime handling
8167 * Garbage collecting
8169 * Handling any other memory management
8171 Notice that a scheduler can also be busy even if the OS has
8173 scheduled out the scheduler thread.
8174 Note:
8176 It is recommended to use the module scheduler instead of this
8177 function directly as it provides an easier way to get the infor‐
8178 mation that you usually want.
8179 If enabled this function returns a list of tuples with {Schedu‐
8182 lerId, ActiveTime, TotalTime}, where SchedulerId is an integer
8183 ID of the scheduler, ActiveTime is the duration the scheduler
8184 has been busy, and TotalTime is the total time duration since
8185 scheduler_wall_time activation for the specific scheduler. The
8186 time unit returned is undefined and can be subject to change be‐
8187 tween releases, OSs, and system restarts. scheduler_wall_time is
8188 only to be used to calculate relative values for scheduler uti‐
8189 lization. The ActiveTime can never exceed TotalTime. The list of
8190 scheduler information is unsorted and can appear in different
8191 order between calls.
8192 The disabled this function returns undefined.
8194 The activation time can differ significantly between schedulers.
8196 Currently dirty schedulers are activated at system start while
8197 normal schedulers are activated some time after the sched‐
8198 uler_wall_time functionality is enabled.
8199 Only information about schedulers that are expected to handle
8201 CPU bound work is included in the return values from this func‐
8202 tion. If you also want information about dirty I/O schedulers,
8203 use statistics(scheduler_wall_time_all) instead.
8204 Normal schedulers will have scheduler identifiers in the range 1
8206 =< SchedulerId =< erlang:system_info(schedulers). Dirty CPU
8207 schedulers will have scheduler identifiers in the range er‐
8208 lang:system_info(schedulers) < SchedulerId =< erlang:sys‐
8209 tem_info(schedulers) + erlang:system_info(dirty_cpu_schedulers).
8210 Note:
8212 The different types of schedulers handle specific types of jobs.
8213 Every job is assigned to a specific scheduler type. Jobs can mi‐
8214 grate between different schedulers of the same type, but never
8215 between schedulers of different types. This fact has to be taken
8216 under consideration when evaluating the result returned.
8217 You can use scheduler_wall_time to calculate scheduler utiliza‐
8220 tion. First you take a sample of the values returned by er‐
8221 lang:statistics(scheduler_wall_time).
8222 > erlang:system_flag(scheduler_wall_time, true).
8224 false
8225 > Ts0 = lists:sort(erlang:statistics(scheduler_wall_time)), ok.
8226 ok
8227 Some time later the user takes another snapshot and calculates
8229 scheduler utilization per scheduler, for example:
8230 > Ts1 = lists:sort(erlang:statistics(scheduler_wall_time)), ok.
8232 ok
8233 > lists:map(fun({{I, A0, T0}, {I, A1, T1}}) -> {I, (A1 - A0)/(T1 - T0)} end, lists:zip(Ts0,Ts1)).
8234 [{1,0.9743474730177548},
8235 {2,0.9744843782751444},
8236 {3,0.9995902361669045},
8237 {4,0.9738012596572161},
8238 {5,0.9717956667018103},
8239 {6,0.9739235846420741},
8240 {7,0.973237033077876},
8241 {8,0.9741297293248656}]
8242 Using the same snapshots to calculate a total scheduler utiliza‐
8244 tion:
8245 > {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.
8247 0.9769136803764825
8248 Total scheduler utilization will equal 1.0 when all schedulers
8250 have been active all the time between the two measurements.
8251 Another (probably more) useful value is to calculate total
8253 scheduler utilization weighted against maximum amount of avail‐
8254 able CPU time:
8255 > WeightedSchedulerUtilization = (TotalSchedulerUtilization * (erlang:system_info(schedulers) + erlang:system_info(dirty_cpu_schedulers))) / erlang:system_info(logical_processors_available).
8257 0.9769136803764825
8258 This weighted scheduler utilization will reach 1.0 when sched‐
8260 ulers are active the same amount of time as maximum available
8261 CPU time. If more schedulers exist than available logical pro‐
8262 cessors, this value may be greater than 1.0.
8263 As of ERTS version 9.0, the Erlang runtime system will as de‐
8265 fault have more schedulers than logical processors. This due to
8266 the dirty schedulers.
8267 Note:
8269 scheduler_wall_time is by default disabled. To enable it, use
8270 erlang:system_flag(scheduler_wall_time, true).
8271 statistics(Item :: scheduler_wall_time_all) ->
8274 [{SchedulerId, ActiveTime, TotalTime}] | undefined
8275 Types:
8277 SchedulerId = integer() >= 1
8279 ActiveTime = TotalTime = integer() >= 0
8280 The same as statistics(scheduler_wall_time), except that it also
8282 include information about all dirty I/O schedulers.
8283 Dirty IO schedulers will have scheduler identifiers in the range
8285 erlang:system_info(schedulers) + erlang:sys‐
8286 tem_info(dirty_cpu_schedulers) < SchedulerId =< erlang:sys‐
8287 tem_info(schedulers) + erlang:system_info(dirty_cpu_schedulers)
8288 + erlang:system_info(dirty_io_schedulers).
8289 Note:
8291 Note that work executing on dirty I/O schedulers are expected to
8292 mainly wait for I/O. That is, when you get high scheduler uti‐
8293 lization on dirty I/O schedulers, CPU utilization is not ex‐
8294 pected to be high due to this work.
8295 statistics(Item :: total_active_tasks) -> ActiveTasks
8298 Types:
8300 ActiveTasks = integer() >= 0
8302 The same as calling lists:sum(statistics(active_tasks)), but
8304 more efficient.
8305 statistics(Item :: total_active_tasks_all) -> ActiveTasks
8307 Types:
8309 ActiveTasks = integer() >= 0
8311 The same as calling lists:sum(statistics(active_tasks_all)), but
8313 more efficient.
8314 statistics(Item :: total_run_queue_lengths) ->
8316 TotalRunQueueLengths
8317 Types:
8319 TotalRunQueueLengths = integer() >= 0
8321 The same as calling lists:sum(statistics(run_queue_lengths)),
8323 but more efficient.
8324 statistics(Item :: total_run_queue_lengths_all) ->
8326 TotalRunQueueLengths
8327 Types:
8329 TotalRunQueueLengths = integer() >= 0
8331 The same as calling lists:sum(statis‐
8333 tics(run_queue_lengths_all)), but more efficient.
8334 statistics(Item :: wall_clock) ->
8336 {Total_Wallclock_Time,
8337 Wallclock_Time_Since_Last_Call}
8338 Types:
8340 Total_Wallclock_Time = Wallclock_Time_Since_Last_Call = inte‐
8342 ger() >= 0
8343 Returns information about wall clock. wall_clock can be used in
8345 the same manner as runtime, except that real time is measured as
8346 opposed to runtime or CPU time.
8347 erlang:suspend_process(Suspendee) -> true
8349 Types:
8351 Suspendee = pid()
8353 Suspends the process identified by Suspendee. The same as call‐
8355 ing erlang:suspend_process(Suspendee, []).
8356 Warning:
8358 This BIF is intended for debugging only.
8359 erlang:suspend_process(Suspendee, OptList) -> boolean()
8362 Types:
8364 Suspendee = pid()
8366 OptList = [Opt]
8367 Opt = unless_suspending | asynchronous | {asynchronous,
8368 term()}
8369 Increases the suspend count on the process identified by Sus‐
8371 pendee and puts it in the suspended state if it is not already
8372 in that state. A suspended process is not scheduled for execu‐
8373 tion until the process has been resumed.
8374 A process can be suspended by multiple processes and can be sus‐
8376 pended multiple times by a single process. A suspended process
8377 does not leave the suspended state until its suspend count
8378 reaches zero. The suspend count of Suspendee is decreased when
8379 erlang:resume_process(Suspendee) is called by the same process
8380 that called erlang:suspend_process(Suspendee). All increased
8381 suspend counts on other processes acquired by a process are au‐
8382 tomatically decreased when the process terminates.
8383 Options (Opts):
8385 asynchronous:
8387 A suspend request is sent to the process identified by Sus‐
8388 pendee. Suspendee eventually suspends unless it is resumed
8389 before it could suspend. The caller of erlang:sus‐
8390 pend_process/2 returns immediately, regardless of whether
8391 Suspendee has suspended yet or not. The point in time when
8392 Suspendee suspends cannot be deduced from other events in
8393 the system. It is only guaranteed that Suspendee eventually
8394 suspends (unless it is resumed). If no asynchronous options
8395 has been passed, the caller of erlang:suspend_process/2 is
8396 blocked until Suspendee has suspended.
8397 {asynchronous, ReplyTag}:
8399 A suspend request is sent to the process identified by Sus‐
8400 pendee. When the suspend request has been processed, a reply
8401 message is sent to the caller of this function. The reply is
8402 on the form {ReplyTag, State} where State is either:
8403 exited:
8405 Suspendee has exited.
8406 suspended:
8408 Suspendee is now suspended.
8409 not_suspended:
8411 Suspendee is not suspended. This can only happen when the
8412 process that issued this request, have called re‐
8413 sume_process(Suspendee) before getting the reply.
8414 Appart from the reply message, the {asynchronous, ReplyTag}
8416 option behaves exactly the same as the asynchronous option
8417 without reply tag.
8418 unless_suspending:
8420 The process identified by Suspendee is suspended unless the
8421 calling process already is suspending Suspendee. If un‐
8422 less_suspending is combined with option asynchronous, a sus‐
8423 pend request is sent unless the calling process already is
8424 suspending Suspendee or if a suspend request already has
8425 been sent and is in transit. If the calling process already
8426 is suspending Suspendee, or if combined with option asyn‐
8427 chronous and a send request already is in transit, false is
8428 returned and the suspend count on Suspendee remains un‐
8429 changed.
8430 If the suspend count on the process identified by Suspendee is
8432 increased, true is returned, otherwise false.
8433 Warning:
8435 This BIF is intended for debugging only.
8436 Warning:
8439 You can easily create deadlocks if processes suspends each other
8440 (directly or in circles). In ERTS versions prior to ERTS version
8441 10.0, the runtime system prevented such deadlocks, but this pre‐
8442 vention has now been removed due to performance reasons.
8443 Failures:
8446 badarg:
8448 If Suspendee is not a process identifier.
8449 badarg:
8451 If the process identified by Suspendee is the same process
8452 as the process calling erlang:suspend_process/2.
8453 badarg:
8455 If the process identified by Suspendee is not alive.
8456 badarg:
8458 If the process identified by Suspendee resides on another
8459 node.
8460 badarg:
8462 If OptList is not a proper list of valid Opts.
8463 system_limit:
8465 If the process identified by Suspendee has been suspended
8466 more times by the calling process than can be represented by
8467 the currently used internal data structures. The system
8468 limit is greater than 2,000,000,000 suspends and will never
8469 be lower.
8470 erlang:system_flag(Flag :: backtrace_depth, Depth) -> OldDepth
8472 Types:
8474 Depth = OldDepth = integer() >= 0
8476 Sets the maximum depth of call stack back-traces in the exit
8478 reason element of 'EXIT' tuples. The flag also limits the stack‐
8479 trace depth returned by process_info item current_stacktrace.
8480 Returns the old value of the flag.
8482 erlang:system_flag(Flag :: cpu_topology, CpuTopology) ->
8484 OldCpuTopology
8485 Types:
8487 CpuTopology = OldCpuTopology = cpu_topology()
8489 cpu_topology() = [LevelEntry :: level_entry()] | undefined
8490 level_entry() =
8491 {LevelTag :: level_tag(), SubLevel :: sub_level()} |
8492 {LevelTag :: level_tag(),
8493 InfoList :: info_list(),
8494 SubLevel :: sub_level()}
8495 level_tag() = core | node | processor | thread
8496 sub_level() =
8497 [LevelEntry :: level_entry()] |
8498 (LogicalCpuId :: {logical, integer() >= 0})
8499 info_list() = []
8500 Warning:
8502 This argument is deprecated. Instead of using this argument, use
8503 command-line argument +sct in erl(1).
8504 When this argument is removed, a final CPU topology to use is
8506 determined at emulator boot time.
8507 Sets the user-defined CpuTopology. The user-defined CPU topology
8510 overrides any automatically detected CPU topology. By passing
8511 undefined as CpuTopology, the system reverts to the CPU topology
8512 automatically detected. The returned value equals the value re‐
8513 turned from erlang:system_info(cpu_topology) before the change
8514 was made.
8515 Returns the old value of the flag.
8517 The CPU topology is used when binding schedulers to logical pro‐
8519 cessors. If schedulers are already bound when the CPU topology
8520 is changed, the schedulers are sent a request to rebind accord‐
8521 ing to the new CPU topology.
8522 The user-defined CPU topology can also be set by passing com‐
8524 mand-line argument +sct to erl(1).
8525 For information on type CpuTopology and more, see erlang:sys‐
8527 tem_info(cpu_topology) as well as command-line flags +sct and
8528 +sbt in erl(1).
8529 erlang:system_flag(Flag :: dirty_cpu_schedulers_online,
8531 DirtyCPUSchedulersOnline) ->
8532 OldDirtyCPUSchedulersOnline
8533 Types:
8535 DirtyCPUSchedulersOnline = OldDirtyCPUSchedulersOnline = in‐
8537 teger() >= 1
8538 Sets the number of dirty CPU schedulers online. Range is 1 <=
8540 DirtyCPUSchedulersOnline <= N, where N is the smallest of the
8541 return values of erlang:system_info(dirty_cpu_schedulers) and
8542 erlang:system_info(schedulers_online).
8543 Returns the old value of the flag.
8545 The number of dirty CPU schedulers online can change if the num‐
8547 ber of schedulers online changes. For example, if 12 schedulers
8548 and 6 dirty CPU schedulers are online, and system_flag/2 is used
8549 to set the number of schedulers online to 6, then the number of
8550 dirty CPU schedulers online is automatically decreased by half
8551 as well, down to 3. Similarly, the number of dirty CPU sched‐
8552 ulers online increases proportionally to increases in the number
8553 of schedulers online.
8554 For more information, see erlang:system_info(dirty_cpu_sched‐
8556 ulers) and erlang:system_info(dirty_cpu_schedulers_online).
8557 erlang:system_flag(Flag :: erts_alloc, Value :: {Alloc, F, V}) ->
8559 ok | notsup
8560 Types:
8562 Alloc = F = atom()
8564 V = integer()
8565 Sets system flags for erts_alloc(3). Alloc is the allocator to
8567 affect, for example binary_alloc. F is the flag to change and V
8568 is the new value.
8569 Only a subset of all erts_alloc flags can be changed at run
8571 time. This subset is currently only the flag sbct.
8572 Returns ok if the flag was set or notsup if not supported by
8574 erts_alloc.
8575 erlang:system_flag(Flag :: fullsweep_after, Number) -> OldNumber
8577 Types:
8579 Number = OldNumber = integer() >= 0
8581 Sets system flag fullsweep_after. Number is a non-negative inte‐
8583 ger indicating how many times generational garbage collections
8584 can be done without forcing a fullsweep collection. The value
8585 applies to new processes, while processes already running are
8586 not affected.
8587 Returns the old value of the flag.
8589 In low-memory systems (especially without virtual memory), set‐
8591 ting the value to 0 can help to conserve memory.
8592 This value can also be set through (OS) environment variable
8594 ERL_FULLSWEEP_AFTER.
8595 erlang:system_flag(Flag :: microstate_accounting, Action) ->
8597 OldState
8598 Types:
8600 Action = true | false | reset
8602 OldState = true | false
8603 Turns on/off microstate accounting measurements. When passing
8605 reset, all counters are reset to 0.
8606 For more information see statistics(microstate_accounting).
8608 erlang:system_flag(Flag :: min_heap_size, MinHeapSize) ->
8610 OldMinHeapSize
8611 Types:
8613 MinHeapSize = OldMinHeapSize = integer() >= 0
8615 Sets the default minimum heap size for processes. The size is
8617 specified in words. The new min_heap_size effects only processes
8618 spawned after the change of min_heap_size has been made.
8619 min_heap_size can be set for individual processes by using
8620 spawn_opt/4 or process_flag/2.
8621 Returns the old value of the flag.
8623 erlang:system_flag(Flag :: min_bin_vheap_size, MinBinVHeapSize) ->
8625 OldMinBinVHeapSize
8626 Types:
8628 MinBinVHeapSize = OldMinBinVHeapSize = integer() >= 0
8630 Sets the default minimum binary virtual heap size for processes.
8632 The size is specified in words. The new min_bin_vhheap_size ef‐
8633 fects only processes spawned after the change of
8634 min_bin_vheap_size has been made. min_bin_vheap_size can be set
8635 for individual processes by using spawn_opt/2,3,4 or
8636 process_flag/2.
8637 Returns the old value of the flag.
8639 erlang:system_flag(Flag :: max_heap_size, MaxHeapSize) ->
8641 OldMaxHeapSize
8642 Types:
8644 MaxHeapSize = OldMaxHeapSize = max_heap_size()
8646 max_heap_size() =
8647 integer() >= 0 |
8648 #{size => integer() >= 0,
8649 kill => boolean(),
8650 error_logger => boolean()}
8651 Sets the default maximum heap size settings for processes. The
8653 size is specified in words. The new max_heap_size effects only
8654 processes spawned efter the change has been made. max_heap_size
8655 can be set for individual processes using spawn_opt/2,3,4 or
8656 process_flag/2.
8657 Returns the old value of the flag.
8659 erlang:system_flag(Flag :: multi_scheduling, BlockState) ->
8661 OldBlockState
8662 Types:
8664 BlockState = block | unblock | block_normal | unblock_normal
8666 OldBlockState = blocked | disabled | enabled
8667 If multi-scheduling is enabled, more than one scheduler thread
8669 is used by the emulator. Multi-scheduling can be blocked in two
8670 different ways. Either all schedulers but one is blocked, or all
8671 normal schedulers but one is blocked. When only normal sched‐
8672 ulers are blocked, dirty schedulers are free to continue to
8673 schedule processes.
8674 If BlockState =:= block, multi-scheduling is blocked. That is,
8676 one and only one scheduler thread will execute. If BlockState
8677 =:= unblock and no one else blocks multi-scheduling, and this
8678 process has blocked only once, multi-scheduling is unblocked.
8679 If BlockState =:= block_normal, normal multi-scheduling is
8681 blocked. That is, only one normal scheduler thread will execute,
8682 but multiple dirty schedulers can execute. If BlockState =:= un‐
8683 block_normal and no one else blocks normal multi-scheduling, and
8684 this process has blocked only once, normal multi-scheduling is
8685 unblocked.
8686 One process can block multi-scheduling and normal multi-schedul‐
8688 ing multiple times. If a process has blocked multiple times, it
8689 must unblock exactly as many times as it has blocked before it
8690 has released its multi-scheduling block. If a process that has
8691 blocked multi-scheduling or normal multi-scheduling exits, it
8692 automatically releases its blocking of multi-scheduling and nor‐
8693 mal multi-scheduling.
8694 The return values are disabled, blocked, blocked_normal, or en‐
8696 abled. The returned value describes the state just after the
8697 call to erlang:system_flag(multi_scheduling, BlockState) has
8698 been made. For information about the return values, see er‐
8699 lang:system_info(multi_scheduling).
8700 Note:
8702 Blocking of multi-scheduling and normal multi-scheduling is nor‐
8703 mally not needed. If you feel that you need to use these fea‐
8704 tures, consider it a few more times again. Blocking multi-sched‐
8705 uling is only to be used as a last resort, as it is most likely
8706 a very inefficient way to solve the problem.
8707 See also erlang:system_info(multi_scheduling), erlang:sys‐
8710 tem_info(normal_multi_scheduling_blockers), erlang:sys‐
8711 tem_info(multi_scheduling_blockers), and erlang:sys‐
8712 tem_info(schedulers).
8713 erlang:system_flag(Flag :: outstanding_system_requests_limit,
8715 NewLimit) ->
8716 OldLimit
8717 Types:
8719 NewLimit = OldLimit = 1..134217727
8721 Sets a limit on the amount of outstanding requests made by a
8723 system process orchestrating system wide changes. Currently
8724 there are two such processes:
8725 The Code Purger:
8727 The code purger orchestrates checking of references to old
8728 code before old code is removed from the system.
8729 The Literal Area Collector:
8731 The literal area collector orchestrates copying of refer‐
8732 ences from old literal areas before removal of such areas
8733 from the system.
8734 Each of these processes are allowed to have as many outstanding
8736 requests as this limit is set to. By default this limit is set
8737 to twice the amount of schedulers on the system. This will en‐
8738 sure that schedulers will have enough work scheduled to perform
8739 these operations as quickly as possible at the same time as
8740 other work will be interleaved with this work. Currently used
8741 limit can be checked by calling erlang:system_info(outstand‐
8742 ing_system_requests_limit).
8743 This limit can also be set by passing the command line argument
8745 +zosrl <Limit> to erl.
8746 erlang:system_flag(Flag :: scheduler_bind_type, How) ->
8748 OldBindType
8749 Types:
8751 How = scheduler_bind_type() | default_bind
8753 OldBindType = scheduler_bind_type()
8754 scheduler_bind_type() =
8755 no_node_processor_spread | no_node_thread_spread | no_spread |
8756 processor_spread | spread | thread_spread |
8757 thread_no_node_processor_spread | unbound
8758 Warning:
8760 This argument is deprecated. Instead of using this argument, use
8761 command-line argument +sbt in erl(1). When this argument is re‐
8762 moved, a final scheduler bind type to use is determined at emu‐
8763 lator boot time.
8764 Controls if and how schedulers are bound to logical processors.
8767 When erlang:system_flag(scheduler_bind_type, How) is called, an
8769 asynchronous signal is sent to all schedulers online, causing
8770 them to try to bind or unbind as requested.
8771 Note:
8773 If a scheduler fails to bind, this is often silently ignored, as
8774 it is not always possible to verify valid logical processor
8775 identifiers. If an error is reported, an error event is logged.
8776 To verify that the schedulers have bound as requested, call er‐
8777 lang:system_info(scheduler_bindings).
8778 Schedulers can be bound on newer Linux, Solaris, FreeBSD, and
8781 Windows systems, but more systems will be supported in future
8782 releases.
8783 In order for the runtime system to be able to bind schedulers,
8785 the CPU topology must be known. If the runtime system fails to
8786 detect the CPU topology automatically, it can be defined. For
8787 more information on how to define the CPU topology, see command-
8788 line flag +sct in erl(1).
8789 The runtime system does by default not bind schedulers to logi‐
8791 cal processors.
8792 Note:
8794 If the Erlang runtime system is the only OS process binding
8795 threads to logical processors, this improves the performance of
8796 the runtime system. However, if other OS processes (for example,
8797 another Erlang runtime system) also bind threads to logical pro‐
8798 cessors, there can be a performance penalty instead. Sometimes
8799 this performance penalty can be severe. If so, it is recommended
8800 to not bind the schedulers.
8801 Schedulers can be bound in different ways. Argument How deter‐
8804 mines how schedulers are bound and can be any of the following:
8805 unbound:
8807 Same as command-line argument +sbt u in erl(1).
8808 no_spread:
8810 Same as command-line argument +sbt ns in erl(1).
8811 thread_spread:
8813 Same as command-line argument +sbt ts in erl(1).
8814 processor_spread:
8816 Same as command-line argument +sbt ps in erl(1).
8817 spread:
8819 Same as command-line argument +sbt s in erl(1).
8820 no_node_thread_spread:
8822 Same as command-line argument +sbt nnts in erl(1).
8823 no_node_processor_spread:
8825 Same as command-line argument +sbt nnps in erl(1).
8826 thread_no_node_processor_spread:
8828 Same as command-line argument +sbt tnnps in erl(1).
8829 default_bind:
8831 Same as command-line argument +sbt db in erl(1).
8832 The returned value equals How before flag scheduler_bind_type
8834 was changed.
8835 Failures:
8837 notsup:
8839 If binding of schedulers is not supported.
8840 badarg:
8842 If How is not one of the documented alternatives.
8843 badarg:
8845 If CPU topology information is unavailable.
8846 The scheduler bind type can also be set by passing command-line
8848 argument +sbt to erl(1).
8849 For more information, see erlang:system_info(sched‐
8851 uler_bind_type), erlang:system_info(scheduler_bindings), as well
8852 as command-line flags +sbt and +sct in erl(1).
8853 erlang:system_flag(Flag :: scheduler_wall_time, Boolean) ->
8855 OldBoolean
8856 Types:
8858 Boolean = OldBoolean = boolean()
8860 Try enable or disable scheduler wall time measurements by pass‐
8862 ing Boolean as either true or false.
8863 For more information about how to use scheduler wall time mea‐
8865 surements, see statistics(scheduler_wall_time).
8866 Scheduler wall time measurements has a node global state. It is
8868 either enabled for all processes on the node or disabled for all
8869 processes. Each process has a logical counter initialized as
8870 zero. A call with Boolean as true will increase that counter one
8871 step for the calling process. A call with false will decrease it
8872 one step unless it already is zero. The node global state for
8873 scheduler_wall_time will be enabled as long as there is at least
8874 one process alive with a counter value larger than zero. When a
8875 process terminates, its counter will also disappear. To ensure
8876 scheduler_wall_time is kept enabled, the process that enabled it
8877 must therefore be kept alive.
8878 Returns the old value of the node global state, true if sched‐
8880 uler wall time measurements were enabled, false if it were dis‐
8881 abled.
8882 Scheduler wall time measurements do consume some cpu overhead
8884 and should not be left turned on unless used.
8885 erlang:system_flag(Flag :: schedulers_online, SchedulersOnline) ->
8887 OldSchedulersOnline
8888 Types:
8890 SchedulersOnline = OldSchedulersOnline = integer() >= 1
8892 Sets the number of schedulers online. Range is 1 <= Scheduler‐
8894 sOnline <= erlang:system_info(schedulers).
8895 Returns the old value of the flag.
8897 If the emulator was built with support for dirty schedulers,
8899 changing the number of schedulers online can also change the
8900 number of dirty CPU schedulers online. For example, if 12 sched‐
8901 ulers and 6 dirty CPU schedulers are online, and system_flag/2
8902 is used to set the number of schedulers online to 6, then the
8903 number of dirty CPU schedulers online is automatically decreased
8904 by half as well, down to 3. Similarly, the number of dirty CPU
8905 schedulers online increases proportionally to increases in the
8906 number of schedulers online.
8907 For more information, see erlang:system_info(schedulers) and er‐
8909 lang:system_info(schedulers_online).
8910 erlang:system_flag(Flag :: system_logger, Logger) -> PrevLogger
8912 Types:
8914 Logger = PrevLogger = logger | undefined | pid()
8916 Sets the process that will receive the logging messages gener‐
8918 ated by ERTS. If set to undefined, all logging messages gener‐
8919 ated by ERTS will be dropped. The messages will be in the for‐
8920 mat:
8921 {log,Level,Format,ArgList,Metadata} where
8923 Level = atom(),
8925 Format = string(),
8926 ArgList = list(term()),
8927 Metadata = #{ pid => pid(),
8928 group_leader => pid(),
8929 time := logger:timestamp(),
8930 error_logger := #{ emulator := true, tag := atom() }
8931 If the system_logger process dies, this flag will be reset to
8934 logger.
8935 The default is the process named logger.
8937 Returns the old value of the flag.
8939 Note:
8941 This function is designed to be used by the KERNEL logger. Be
8942 careful if you change it to something else as log messages may
8943 be lost. If you want to intercept emulator log messages, do it
8944 by adding a specialized handler to the KERNEL logger.
8945 erlang:system_flag(Flag :: trace_control_word, TCW) -> OldTCW
8948 Types:
8950 TCW = OldTCW = integer() >= 0
8952 Sets the value of the node trace control word to TCW, which is
8954 to be an unsigned integer. For more information, see function
8955 set_tcw in section "Match Specifications in Erlang" in the
8956 User's Guide.
8957 Returns the old value of the flag.
8959 erlang:system_flag(Flag :: time_offset, Value :: finalize) ->
8961 OldState
8962 Types:
8964 OldState = preliminary | final | volatile
8966 Finalizes the time offset when single time warp mode is used. If
8968 another time warp mode is used, the time offset state is left
8969 unchanged.
8970 Returns the old state identifier, that is:
8972 * If preliminary is returned, finalization was performed and
8974 the time offset is now final.
8975 * If final is returned, the time offset was already in the fi‐
8977 nal state. This either because another erlang:sys‐
8978 tem_flag(time_offset, finalize) call or because no time warp
8979 mode is used.
8980 * If volatile is returned, the time offset cannot be finalized
8982 because multi-time warp mode is used.
8983 erlang:system_info(Item :: update_cpu_info) -> changed | unchanged
8985 Returns information about the current system. The documentation
8987 of this function is broken into the following sections in order
8988 to make it easier to navigate.
8989 Memory Allocation:
8991 allocated_areas, allocator, alloc_util_allocators, alloca‐
8992 tor_sizes
8993 CPU Topology:
8995 cpu_topology, logical_processors, update_cpu_info
8996 Process Information:
8998 fullsweep_after, garbage_collection, heap_sizes, heap_type,
8999 max_heap_size, message_queue_data, min_heap_size,
9000 min_bin_vheap_size, procs
9001 System Limits:
9003 atom_count, atom_limit, ets_count, ets_limit, port_count,
9004 port_limit, process_count, process_limit
9005 System Time:
9007 end_time, os_monotonic_time_source, os_system_time_source,
9008 start_time, time_correction, time_offset, time_warp_mode,
9009 tolerant_timeofday
9010 Scheduler Information:
9012 dirty_cpu_schedulers, dirty_cpu_schedulers_online,
9013 dirty_io_schedulers, multi_scheduling, multi_schedul‐
9014 ing_blockers, normal_multi_scheduling_blockers, sched‐
9015 uler_bind_type, scheduler_bindings, scheduler_id, sched‐
9016 ulers, smp_support, threads, thread_pool_size
9017 Distribution Information:
9019 creation, delayed_node_table_gc, dist, dist_buf_busy_limit,
9020 dist_ctrl
9021 System Information:
9023 c_compiler_used, check_io, compat_rel, debug_compiled,
9024 driver_version, dynamic_trace, dynamic_trace_probes,
9025 emu_flavor, emu_type, info, kernel_poll, loaded, machine,
9026 modified_timing_level, nif_version, otp_release, outstand‐
9027 ing_system_requests_limit, port_parallelism, system_archi‐
9028 tecture, system_logger, system_version, trace_control_word,
9029 version, wordsize
9030 erlang:system_info(Item :: allocated_areas) -> [tuple()]
9032 erlang:system_info(Item :: allocator) ->
9034 {Allocator, Version, Features, Settings}
9035 erlang:system_info(Item :: {allocator, Alloc}) -> [term()]
9037 erlang:system_info(Item :: alloc_util_allocators) -> [Alloc]
9039 erlang:system_info(Item :: {allocator_sizes, Alloc}) -> [term()]
9041 Types:
9043 Allocator = undefined | glibc
9045 Version = [integer() >= 0]
9046 Features = [atom()]
9047 Settings =
9048 [{Subsystem :: atom(),
9049 [{Parameter :: atom(), Value :: term()}]}]
9050 Alloc = atom()
9051 Returns various information about the memory allocators of the
9053 current system (emulator) as specified by Item:
9054 allocated_areas:
9056 Returns a list of tuples with information about miscella‐
9057 neous allocated memory areas.
9058 Each tuple contains an atom describing the type of memory as
9060 first element and the amount of allocated memory in bytes as
9061 second element. When information about allocated and used
9062 memory is present, also a third element is present, contain‐
9063 ing the amount of used memory in bytes.
9064 erlang:system_info(allocated_areas) is intended for debug‐
9066 ging, and the content is highly implementation-dependent.
9067 The content of the results therefore changes when needed
9068 without prior notice.
9069 Notice that the sum of these values is not the total amount
9071 of memory allocated by the emulator. Some values are part of
9072 other values, and some memory areas are not part of the re‐
9073 sult. For information about the total amount of memory allo‐
9074 cated by the emulator, see erlang:memory/0,1.
9075 allocator:
9077 Returns {Allocator, Version, Features, Settings, where:
9078 * Allocator corresponds to the malloc() implementation used.
9080 If Allocator equals undefined, the malloc() implementation
9081 used cannot be identified. glibc can be identified.
9082 * Version is a list of integers (but not a string) repre‐
9084 senting the version of the malloc() implementation used.
9085 * Features is a list of atoms representing the allocation
9087 features used.
9088 * Settings is a list of subsystems, their configurable pa‐
9090 rameters, and used values. Settings can differ between
9091 different combinations of platforms, allocators, and allo‐
9092 cation features. Memory sizes are given in bytes.
9093 See also "System Flags Effecting erts_alloc" in erts_al‐
9095 loc(3).
9096 {allocator, Alloc}:
9098 Returns information about the specified allocator. As from
9099 ERTS 5.6.1, the return value is a list of {instance, Instan‐
9100 ceNo, InstanceInfo} tuples, where InstanceInfo contains in‐
9101 formation about a specific instance of the allocator. If Al‐
9102 loc is not a recognized allocator, undefined is returned. If
9103 Alloc is disabled, false is returned.
9104 Notice that the information returned is highly implementa‐
9106 tion-dependent and can be changed or removed at any time
9107 without prior notice. It was initially intended as a tool
9108 when developing new allocators, but as it can be of interest
9109 for others it has been briefly documented.
9110 The recognized allocators are listed in erts_alloc(3). In‐
9112 formation about super carriers can be obtained from ERTS 8.0
9113 with {allocator, erts_mmap} or from ERTS 5.10.4; the re‐
9114 turned list when calling with {allocator, mseg_alloc} also
9115 includes an {erts_mmap, _} tuple as one element in the list.
9116 After reading the erts_alloc(3) documentation, the returned
9118 information more or less speaks for itself, but it can be
9119 worth explaining some things. Call counts are presented by
9120 two values, the first value is giga calls, and the second
9121 value is calls. mbcs and sbcs denote multi-block carriers,
9122 and single-block carriers, respectively. Sizes are presented
9123 in bytes. When a size is not presented, it is the amount of
9124 something. Sizes and amounts are often presented by three
9125 values:
9126 * The first is the current value.
9128 * The second is the maximum value since the last call to er‐
9130 lang:system_info({allocator, Alloc}).
9131 * The third is the maximum value since the emulator was
9133 started.
9134 If only one value is present, it is the current value.
9136 fix_alloc memory block types are presented by two values.
9137 The first value is the memory pool size and the second value
9138 is the used memory size.
9139 alloc_util_allocators:
9141 Returns a list of the names of all allocators using the ERTS
9142 internal alloc_util framework as atoms. For more informa‐
9143 tion, see section The alloc_util framework in erts_alloc(3).
9144 {allocator_sizes, Alloc}:
9146 Returns various size information for the specified alloca‐
9147 tor. The information returned is a subset of the information
9148 returned by erlang:system_info({allocator, Alloc}).
9149 erlang:system_info(Item :: cpu_topology) -> CpuTopology
9151 erlang:system_info(Item ::
9153 {cpu_topology, defined | detected | used}) ->
9154 CpuTopology
9155 erlang:system_info(Item ::
9157 logical_processors |
9158 logical_processors_available |
9159 logical_processors_online) ->
9160 unknown | integer() >= 1
9161 erlang:system_info(Item :: trace_control_word) ->
9163 integer() >= 0
9164 Types:
9166 cpu_topology() = [LevelEntry :: level_entry()] | undefined
9168 All LevelEntrys of a list must contain the same LevelTag,
9169 except on the top level where both node and processor‐
9170 LevelTags can coexist.
9171 level_entry() =
9172 {LevelTag :: level_tag(), SubLevel :: sub_level()} |
9173 {LevelTag :: level_tag(),
9174 InfoList :: info_list(),
9175 SubLevel :: sub_level()}
9176 {LevelTag, SubLevel} == {LevelTag, [], SubLevel}
9177 level_tag() = core | node | processor | thread
9178 More LevelTags can be introduced in a future release.
9179 sub_level() =
9180 [LevelEntry :: level_entry()] |
9181 (LogicalCpuId :: {logical, integer() >= 0})
9182 info_list() = []
9183 The info_list() can be extended in a future release.
9184 Returns various information about the CPU topology of the cur‐
9186 rent system (emulator) as specified by Item:
9187 cpu_topology:
9189 Returns the CpuTopology currently used by the emulator. The
9190 CPU topology is used when binding schedulers to logical pro‐
9191 cessors. The CPU topology used is the user-defined CPU
9192 topology, if such exists, otherwise the automatically de‐
9193 tected CPU topology, if such exists. If no CPU topology ex‐
9194 ists, undefined is returned.
9195 node refers to Non-Uniform Memory Access (NUMA) nodes.
9197 thread refers to hardware threads (for example, Intel hyper-
9198 threads).
9199 A level in term CpuTopology can be omitted if only one entry
9201 exists and InfoList is empty.
9202 thread can only be a sublevel to core. core can be a sub‐
9204 level to processor or node. processor can be on the top
9205 level or a sublevel to node. node can be on the top level or
9206 a sublevel to processor. That is, NUMA nodes can be proces‐
9207 sor internal or processor external. A CPU topology can con‐
9208 sist of a mix of processor internal and external NUMA nodes,
9209 as long as each logical CPU belongs to one NUMA node. Cache
9210 hierarchy is not part of the CpuTopology type, but will be
9211 in a future release. Other things can also make it into the
9212 CPU topology in a future release. So, expect the CpuTopology
9213 type to change.
9214 {cpu_topology, defined}:
9216 Returns the user-defined CpuTopology. For more information,
9219 see command-line flag +sct in erl(1) and argument cpu_topol‐
9220 ogy.
9221 {cpu_topology, detected}:
9223 Returns the automatically detected CpuTopologyy. The emula‐
9226 tor detects the CPU topology on some newer Linux, Solaris,
9227 FreeBSD, and Windows systems. On Windows system with more
9228 than 32 logical processors, the CPU topology is not de‐
9229 tected.
9230 For more information, see argument cpu_topology.
9232 {cpu_topology, used}:
9234 Returns CpuTopology used by the emulator. For more informa‐
9235 tion, see argument cpu_topology.
9236 logical_processors:
9238 Returns the detected number of logical processors configured
9239 in the system. The return value is either an integer, or the
9240 atom unknown if the emulator cannot detect the configured
9241 logical processors.
9242 logical_processors_available:
9244 Returns the detected number of logical processors available
9245 to the Erlang runtime system. The return value is either an
9246 integer, or the atom unknown if the emulator cannot detect
9247 the available logical processors. The number of available
9248 logical processors is less than or equal to the number of
9249 logical processors online.
9250 logical_processors_online:
9252 Returns the detected number of logical processors online on
9253 the system. The return value is either an integer, or the
9254 atom unknown if the emulator cannot detect logical proces‐
9255 sors online. The number of logical processors online is less
9256 than or equal to the number of logical processors config‐
9257 ured.
9258 cpu_quota:
9260 Returns the detected CPU quota the emulator is limited by.
9261 The return value is an integer saying how many processors'
9262 worth of runtime we get (between 1 and the number of logical
9263 processors), or the atom unknown if the emulator cannot de‐
9264 tect a quota.
9265 update_cpu_info:
9267 The runtime system rereads the CPU information available and
9268 updates its internally stored information about the detected
9269 CPU topology and the number of logical processors config‐
9270 ured, online, available, and cpu quota.
9271 If the CPU information has changed since the last time it
9273 was read, the atom changed is returned, otherwise the atom
9274 unchanged. If the CPU information has changed, you probably
9275 want to adjust the number of schedulers online. You typi‐
9276 cally want to have as many schedulers online as logical pro‐
9277 cessors available.
9278 erlang:system_info(Item :: fullsweep_after) ->
9280 {fullsweep_after, integer() >= 0}
9281 erlang:system_info(Item :: garbage_collection) ->
9283 [{atom(), integer()}]
9284 erlang:system_info(Item :: heap_sizes) -> [integer() >= 0]
9286 erlang:system_info(Item :: heap_type) -> private
9288 erlang:system_info(Item :: max_heap_size) ->
9290 {max_heap_size,
9291 MaxHeapSize :: max_heap_size()}
9292 erlang:system_info(Item :: message_queue_data) ->
9294 message_queue_data()
9295 erlang:system_info(Item :: min_heap_size) ->
9297 {min_heap_size,
9298 MinHeapSize :: integer() >= 1}
9299 erlang:system_info(Item :: min_bin_vheap_size) ->
9301 {min_bin_vheap_size,
9302 MinBinVHeapSize :: integer() >= 1}
9303 erlang:system_info(Item :: process_limit) -> integer() >= 1
9305 Types:
9307 message_queue_data() = off_heap | on_heap
9309 max_heap_size() =
9310 integer() >= 0 |
9311 #{size => integer() >= 0,
9312 kill => boolean(),
9313 error_logger => boolean()}
9314 Returns information about the default process heap settings:
9316 fullsweep_after:
9318 Returns {fullsweep_after, integer() >= 0}, which is the
9319 fullsweep_after garbage collection setting used by default.
9320 For more information, see garbage_collection described be‐
9321 low.
9322 garbage_collection:
9324 Returns a list describing the default garbage collection
9325 settings. A process spawned on the local node by a spawn or
9326 spawn_link uses these garbage collection settings. The de‐
9327 fault settings can be changed by using erlang:system_flag/2.
9328 spawn_opt/2,3,4 can spawn a process that does not use the
9329 default settings.
9330 heap_sizes:
9332 Returns a list of integers representing valid heap sizes in
9333 words. All Erlang heaps are sized from sizes in this list.
9334 heap_type:
9336 Returns the heap type used by the current emulator. One heap
9337 type exists:
9338 private:
9340 Each process has a heap reserved for its use and no ref‐
9341 erences between heaps of different processes are allowed.
9342 Messages passed between processes are copied between
9343 heaps.
9344 max_heap_size:
9346 Returns {max_heap_size, MaxHeapSize}, where MaxHeapSize is
9347 the current system-wide maximum heap size settings for
9348 spawned processes. This setting can be set using the com‐
9349 mand-line flags +hmax, +hmaxk and +hmaxel in erl(1). It can
9350 also be changed at runtime using erlang:sys‐
9351 tem_flag(max_heap_size, MaxHeapSize). For more details about
9352 the max_heap_size process flag, see
9353 process_flag(max_heap_size, MaxHeapSize).
9354 message_queue_data:
9356 Returns the default value of the message_queue_data process
9357 flag, which can be either off_heap or on_heap. The default
9358 value is set by the command-line argument +hmqd in erl(1).
9359 For more information, see the documentation of
9360 process_flag(message_queue_data, MQD).
9361 min_heap_size:
9363 Returns {min_heap_size, MinHeapSize}, where MinHeapSize is
9364 the current system-wide minimum heap size for spawned pro‐
9365 cesses.
9366 min_bin_vheap_size:
9368 Returns {min_bin_vheap_size, MinBinVHeapSize}, where MinBin‐
9369 VHeapSize is the current system-wide minimum binary virtual
9370 heap size for spawned processes.
9371 procs:
9373 Returns a binary containing a string of process and port in‐
9374 formation formatted as in Erlang crash dumps. For more in‐
9375 formation, see section How to interpret the Erlang crash
9376 dumps in the User's Guide.
9377 erlang:system_info(Item :: atom_count) -> integer() >= 1
9379 erlang:system_info(Item :: atom_limit) -> integer() >= 1
9381 erlang:system_info(Item :: ets_count) -> integer() >= 1
9383 erlang:system_info(Item :: ets_limit) -> integer() >= 1
9385 erlang:system_info(Item :: port_parallelism) -> boolean()
9387 erlang:system_info(Item :: port_count) -> integer() >= 0
9389 erlang:system_info(Item :: port_limit) -> integer() >= 1
9391 erlang:system_info(Item :: process_count) -> integer() >= 1
9393 Returns information about the current system (emulator) limits
9395 as specified by Item:
9396 atom_count:
9398 Returns the number of atoms currently existing at the local
9399 node. The value is given as an integer.
9400 atom_limit:
9402 Returns the maximum number of atoms allowed. This limit can
9403 be increased at startup by passing command-line flag +t to
9404 erl(1).
9405 ets_count:
9407 Returns the number of ETS tables currently existing at the
9408 local node.
9409 ets_limit:
9411 Returns the limit for number of ETS tables. This limit is
9412 partially obsolete and number of tables are only limited by
9413 available memory.
9414 port_count:
9416 Returns the number of ports currently existing at the local
9417 node. The value is given as an integer. This is the same
9418 value as returned by length(erlang:ports()), but more effi‐
9419 cient.
9420 port_limit:
9422 Returns the maximum number of simultaneously existing ports
9423 at the local node as an integer. This limit can be config‐
9424 ured at startup by using command-line flag +Q in erl(1).
9425 process_count:
9427 Returns the number of processes currently existing at the
9428 local node. The value is given as an integer. This is the
9429 same value as returned by length(processes()), but more ef‐
9430 ficient.
9431 process_limit:
9433 Returns the maximum number of simultaneously existing pro‐
9434 cesses at the local node. The value is given as an integer.
9435 This limit can be configured at startup by using command-
9436 line flag +P in erl(1).
9437 erlang:system_info(Item :: end_time) -> integer() >= 0
9439 erlang:system_info(Item :: os_monotonic_time_source) ->
9441 [{atom(), term()}]
9442 erlang:system_info(Item :: os_system_time_source) ->
9444 [{atom(), term()}]
9445 erlang:system_info(Item :: smp_support) -> boolean()
9447 erlang:system_info(Item :: thread_pool_size) -> integer() >= 0
9449 erlang:system_info(Item :: time_correction) -> true | false
9451 erlang:system_info(Item :: time_offset) ->
9453 preliminary | final | volatile
9454 erlang:system_info(Item :: time_warp_mode) ->
9456 no_time_warp | single_time_warp |
9457 multi_time_warp
9458 Returns information about the current system (emulator) time as
9460 specified by Item:
9461 end_time:
9463 The last Erlang monotonic time in native time unit that can
9464 be represented internally in the current Erlang runtime sys‐
9465 tem instance. The time between the start time and the end
9466 time is at least a quarter of a millennium.
9467 os_monotonic_time_source:
9469 Returns a list containing information about the source of OS
9470 monotonic time that is used by the runtime system.
9471 If [] is returned, no OS monotonic time is available. The
9473 list contains two-tuples with Keys as first element, and
9474 Values as second element. The order of these tuples is unde‐
9475 fined. The following tuples can be part of the list, but
9476 more tuples can be introduced in the future:
9477 {function, Function}:
9479 Function is the name of the function used. This tuple al‐
9480 ways exists if OS monotonic time is available to the run‐
9481 time system.
9482 {clock_id, ClockId}:
9484 This tuple only exists if Function can be used with dif‐
9485 ferent clocks. ClockId corresponds to the clock identifier
9486 used when calling Function.
9487 {resolution, OsMonotonicTimeResolution}:
9489 Highest possible resolution of current OS monotonic time
9490 source as parts per second. If no resolution information
9491 can be retrieved from the OS, OsMonotonicTimeResolution is
9492 set to the resolution of the time unit of Functions return
9493 value. That is, the actual resolution can be lower than
9494 OsMonotonicTimeResolution. Notice that the resolution does
9495 not say anything about the accuracy or whether the pre‐
9496 cision aligns with the resolution. You do, however, know
9497 that the precision is not better than OsMonotonicTimeReso‐
9498 lution.
9499 {extended, Extended}:
9501 Extended equals yes if the range of time values has been
9502 extended; otherwise Extended equals no. The range must be
9503 extended if Function returns values that wrap fast. This
9504 typically is the case when the return value is a 32-bit
9505 value.
9506 {parallel, Parallel}:
9508 Parallel equals yes if Function is called in parallel from
9509 multiple threads. If it is not called in parallel, because
9510 calls must be serialized, Parallel equals no.
9511 {time, OsMonotonicTime}:
9513 OsMonotonicTime equals current OS monotonic time in native
9514 time unit.
9515 os_system_time_source:
9517 Returns a list containing information about the source of OS
9518 system time that is used by the runtime system.
9519 The list contains two-tuples with Keys as first element, and
9521 Values as second element. The order of these tuples is unde‐
9522 fined. The following tuples can be part of the list, but
9523 more tuples can be introduced in the future:
9524 {function, Function}:
9526 Function is the name of the funcion used.
9527 {clock_id, ClockId}:
9529 Exists only if Function can be used with different clocks.
9530 ClockId corresponds to the clock identifier used when
9531 calling Function.
9532 {resolution, OsSystemTimeResolution}:
9534 Highest possible resolution of current OS system time
9535 source as parts per second. If no resolution information
9536 can be retrieved from the OS, OsSystemTimeResolution is
9537 set to the resolution of the time unit of Functions return
9538 value. That is, the actual resolution can be lower than
9539 OsSystemTimeResolution. Notice that the resolution does
9540 not say anything about the accuracy or whether the pre‐
9541 cision do align with the resolution. You do, however, know
9542 that the precision is not better than OsSystemTimeResolu‐
9543 tion.
9544 {parallel, Parallel}:
9546 Parallel equals yes if Function is called in parallel from
9547 multiple threads. If it is not called in parallel, because
9548 calls needs to be serialized, Parallel equals no.
9549 {time, OsSystemTime}:
9551 OsSystemTime equals current OS system time in native time
9552 unit.
9553 start_time:
9555 The Erlang monotonic time in native time unit at the time
9556 when current Erlang runtime system instance started.
9557 See also erlang:system_info(end_time).
9559 time_correction:
9561 Returns a boolean value indicating whether time correction
9562 is enabled or not.
9563 time_offset:
9565 Returns the state of the time offset:
9566 preliminary:
9568 The time offset is preliminary, and will be changed and
9569 finalized later. The preliminary time offset is used dur‐
9570 ing the preliminary phase of the single time warp mode.
9571 final:
9573 The time offset is final. This either because no time
9574 warp mode is used, or because the time offset have been
9575 finalized when single time warp mode is used.
9576 volatile:
9578 The time offset is volatile. That is, it can change at any
9579 time. This is because multi-time warp mode is used.
9580 time_warp_mode:
9582 Returns a value identifying the time warp mode that is
9583 used:
9584 no_time_warp:
9586 The no time warp mode is used.
9587 single_time_warp:
9589 The single time warp mode is used.
9590 multi_time_warp:
9592 The multi-time warp mode is used.
9593 tolerant_timeofday:
9595 Returns whether a pre ERTS 7.0 backwards compatible compen‐
9596 sation for sudden changes of system time is enabled or dis‐
9597 abled. Such compensation is enabled when the time offset is
9598 final, and time correction is enabled.
9599 erlang:system_info(Item :: dirty_cpu_schedulers) ->
9601 integer() >= 0
9602 erlang:system_info(Item :: dirty_cpu_schedulers_online) ->
9604 integer() >= 0
9605 erlang:system_info(Item :: dirty_io_schedulers) ->
9607 integer() >= 0
9608 erlang:system_info(Item :: multi_scheduling) ->
9610 disabled | blocked | blocked_normal |
9611 enabled
9612 erlang:system_info(Item :: multi_scheduling_blockers) ->
9614 [Pid :: pid()]
9615 erlang:system_info(Item :: normal_multi_scheduling_blockers) ->
9617 [Pid :: pid()]
9618 erlang:system_info(Item :: procs) -> binary()
9620 erlang:system_info(Item :: scheduler_bind_type) ->
9622 spread | processor_spread | thread_spread |
9623 thread_no_node_processor_spread |
9624 no_node_processor_spread |
9625 no_node_thread_spread | no_spread | unbound
9626 erlang:system_info(Item :: scheduler_bindings) -> tuple()
9628 erlang:system_info(Item :: scheduler_id) ->
9630 SchedulerId :: integer() >= 1
9631 erlang:system_info(Item :: schedulers | schedulers_online) ->
9633 integer() >= 1
9634 erlang:system_info(Item :: system_version) -> string()
9636 erlang:system_info(Item :: threads) -> boolean()
9638 Returns information about schedulers, scheduling and threads in
9640 the current system as specified by Item:
9641 dirty_cpu_schedulers:
9643 Returns the number of dirty CPU scheduler threads used by
9644 the emulator. Dirty CPU schedulers execute CPU-bound native
9645 functions, such as NIFs, linked-in driver code, and BIFs
9646 that cannot be managed cleanly by the normal emulator sched‐
9647 ulers.
9648 The number of dirty CPU scheduler threads is determined at
9650 emulator boot time and cannot be changed after that. How‐
9651 ever, the number of dirty CPU scheduler threads online can
9652 be changed at any time. The number of dirty CPU schedulers
9653 can be set at startup by passing command-line flag +SDcpu or
9654 +SDPcpu in erl(1).
9655 See also erlang:system_flag(dirty_cpu_schedulers_online,
9657 DirtyCPUSchedulersOnline), erlang:sys‐
9658 tem_info(dirty_cpu_schedulers_online), erlang:sys‐
9659 tem_info(dirty_io_schedulers), erlang:system_info(sched‐
9660 ulers), erlang:system_info(schedulers_online), and er‐
9661 lang:system_flag(schedulers_online, SchedulersOnline).
9662 dirty_cpu_schedulers_online:
9664 Returns the number of dirty CPU schedulers online. The re‐
9665 turn value satisfies 1 <= DirtyCPUSchedulersOnline <= N,
9666 where N is the smallest of the return values of erlang:sys‐
9667 tem_info(dirty_cpu_schedulers) and erlang:system_info(sched‐
9668 ulers_online).
9669 The number of dirty CPU schedulers online can be set at
9671 startup by passing command-line flag +SDcpu in erl(1).
9672 For more information, see erlang:sys‐
9674 tem_info(dirty_cpu_schedulers), erlang:sys‐
9675 tem_info(dirty_io_schedulers), erlang:system_info(sched‐
9676 ulers_online), and erlang:system_flag(dirty_cpu_sched‐
9677 ulers_online, DirtyCPUSchedulersOnline).
9678 dirty_io_schedulers:
9680 Returns the number of dirty I/O schedulers as an integer.
9681 Dirty I/O schedulers execute I/O-bound native functions,
9682 such as NIFs and linked-in driver code, which cannot be man‐
9683 aged cleanly by the normal emulator schedulers.
9684 This value can be set at startup by passing command-line ar‐
9686 gument +SDio in erl(1).
9687 For more information, see erlang:sys‐
9689 tem_info(dirty_cpu_schedulers), erlang:sys‐
9690 tem_info(dirty_cpu_schedulers_online), and erlang:sys‐
9691 tem_flag(dirty_cpu_schedulers_online, DirtyCPUSchedulersOn‐
9692 line).
9693 multi_scheduling:
9695 Returns one of the following:
9696 disabled:
9698 The emulator has been started with only one scheduler
9699 thread.
9700 blocked:
9702 The emulator has more than one scheduler thread, but all
9703 scheduler threads except one are blocked. That is, only
9704 one scheduler thread schedules Erlang processes and exe‐
9705 cutes Erlang code.
9706 blocked_normal:
9708 The emulator has more than one scheduler thread, but all
9709 normal scheduler threads except one are blocked. Notice
9710 that dirty schedulers are not blocked, and can schedule
9711 Erlang processes and execute native code.
9712 enabled:
9714 The emulator has more than one scheduler thread, and no
9715 scheduler threads are blocked. That is, all available
9716 scheduler threads schedule Erlang processes and execute
9717 Erlang code.
9718 See also erlang:system_flag(multi_scheduling, BlockState),
9720 erlang:system_info(multi_scheduling_blockers), erlang:sys‐
9721 tem_info(normal_multi_scheduling_blockers), and erlang:sys‐
9722 tem_info(schedulers).
9723 multi_scheduling_blockers:
9725 Returns a list of Pids when multi-scheduling is blocked,
9726 otherwise the empty list is returned. The Pids in the list
9727 represent all the processes currently blocking multi-sched‐
9728 uling. A Pid occurs only once in the list, even if the cor‐
9729 responding process has blocked multiple times.
9730 See also erlang:system_flag(multi_scheduling, BlockState),
9732 erlang:system_info(multi_scheduling), erlang:sys‐
9733 tem_info(normal_multi_scheduling_blockers), and erlang:sys‐
9734 tem_info(schedulers).
9735 normal_multi_scheduling_blockers:
9737 Returns a list of Pids when normal multi-scheduling is
9738 blocked (that is, all normal schedulers but one is blocked),
9739 otherwise the empty list is returned. The Pids in the list
9740 represent all the processes currently blocking normal multi-
9741 scheduling. A Pid occurs only once in the list, even if the
9742 corresponding process has blocked multiple times.
9743 See also erlang:system_flag(multi_scheduling, BlockState),
9745 erlang:system_info(multi_scheduling), erlang:sys‐
9746 tem_info(multi_scheduling_blockers), and erlang:sys‐
9747 tem_info(schedulers).
9748 scheduler_bind_type:
9750 Returns information about how the user has requested sched‐
9751 ulers to be bound or not bound.
9752 Notice that although a user has requested schedulers to be
9754 bound, they can silently have failed to bind. To inspect the
9755 scheduler bindings, call erlang:system_info(scheduler_bind‐
9756 ings).
9757 For more information, see command-line argument +sbt in
9759 erl(1) and erlang:system_info(scheduler_bindings).
9760 scheduler_bindings:
9762 Returns information about the currently used scheduler bind‐
9763 ings.
9764 A tuple of a size equal to erlang:system_info(schedulers) is
9766 returned. The tuple elements are integers or the atom un‐
9767 bound. Logical processor identifiers are represented as in‐
9768 tegers. The Nth element of the tuple equals the current
9769 binding for the scheduler with the scheduler identifier
9770 equal to N. For example, if the schedulers are bound, ele‐
9771 ment(erlang:system_info(scheduler_id), erlang:sys‐
9772 tem_info(scheduler_bindings)) returns the identifier of the
9773 logical processor that the calling process is executing on.
9774 Notice that only schedulers online can be bound to logical
9776 processors.
9777 For more information, see command-line argument +sbt in
9779 erl(1) and erlang:system_info(schedulers_online).
9780 scheduler_id:
9782 Returns the scheduler ID (SchedulerId) of the scheduler
9783 thread that the calling process is executing on. SchedulerId
9784 is a positive integer, where 1 <= SchedulerId <= erlang:sys‐
9785 tem_info(schedulers).
9786 See also erlang:system_info(schedulers).
9788 schedulers:
9790 Returns the number of scheduler threads used by the emula‐
9791 tor. Scheduler threads online schedules Erlang processes and
9792 Erlang ports, and execute Erlang code and Erlang linked-in
9793 driver code.
9794 The number of scheduler threads is determined at emulator
9796 boot time and cannot be changed later. However, the number
9797 of schedulers online can be changed at any time.
9798 See also erlang:system_flag(schedulers_online, SchedulersOn‐
9800 line), erlang:system_info(schedulers_online), erlang:sys‐
9801 tem_info(scheduler_id), erlang:system_flag(multi_scheduling,
9802 BlockState), erlang:system_info(multi_scheduling), er‐
9803 lang:system_info(normal_multi_scheduling_blockers) and er‐
9804 lang:system_info(multi_scheduling_blockers).
9805 schedulers_online:
9807 Returns the number of schedulers online. The scheduler iden‐
9808 tifiers of schedulers online satisfy the relationship 1 <=
9809 SchedulerId <= erlang:system_info(schedulers_online).
9810 For more information, see erlang:system_info(schedulers) and
9812 erlang:system_flag(schedulers_online, SchedulersOnline).
9813 smp_support:
9815 Returns true.
9816 threads:
9818 Returns true.
9819 thread_pool_size:
9821 Returns the number of async threads in the async thread pool
9824 used for asynchronous driver calls
9825 (erl_driver:driver_async()). The value is given as an inte‐
9826 ger.
9827 erlang:system_info(Item :: creation) -> integer()
9829 erlang:system_info(Item :: delayed_node_table_gc) ->
9831 infinity | integer() >= 0
9832 erlang:system_info(Item :: dist) -> binary()
9834 erlang:system_info(Item :: dist_buf_busy_limit) ->
9836 integer() >= 0
9837 erlang:system_info(Item :: dist_ctrl) ->
9839 {Node :: node(),
9840 ControllingEntity :: port() | pid()}
9841 Returns information about Erlang Distribution in the current
9843 system as specified by Item:
9844 creation:
9846 Returns the creation of the local node as an integer. The
9847 creation is changed when a node is restarted. The creation
9848 of a node is stored in process identifiers, port identi‐
9849 fiers, and references. This makes it (to some extent) possi‐
9850 ble to distinguish between identifiers from different incar‐
9851 nations of a node. The valid creations are integers in the
9852 range 1..3, but this will probably change in a future re‐
9853 lease. If the node is not alive, 0 is returned.
9854 delayed_node_table_gc:
9856 Returns the amount of time in seconds garbage collection of
9857 an entry in a node table is delayed. This limit can be set
9858 on startup by passing command-line flag +zdntgc to erl(1).
9859 For more information, see the documentation of the command-
9860 line flag.
9861 dist:
9863 Returns a binary containing a string of distribution infor‐
9864 mation formatted as in Erlang crash dumps. For more informa‐
9865 tion, see section How to interpret the Erlang crash dumps
9866 in the User's Guide.
9867 dist_buf_busy_limit:
9869 Returns the value of the distribution buffer busy limit in
9870 bytes. This limit can be set at startup by passing command-
9871 line flag +zdbbl to erl(1).
9872 dist_ctrl:
9874 Returns a list of tuples {Node, ControllingEntity}, one en‐
9875 try for each connected remote node. Node is the node name
9876 and ControllingEntity is the port or process identifier re‐
9877 sponsible for the communication to that node. More specifi‐
9878 cally, ControllingEntity for nodes connected through TCP/IP
9879 (the normal case) is the socket used in communication with
9880 the specific node.
9881 erlang:system_info(Item :: c_compiler_used) -> {atom(), term()}
9883 erlang:system_info(Item :: check_io) -> [term()]
9885 erlang:system_info(Item :: compat_rel) -> integer()
9887 erlang:system_info(Item :: debug_compiled) -> boolean()
9889 erlang:system_info(Item :: driver_version) -> string()
9891 erlang:system_info(Item :: dynamic_trace) ->
9893 none | dtrace | systemtap
9894 erlang:system_info(Item :: dynamic_trace_probes) -> boolean()
9896 erlang:system_info(Item :: emu_flavor) -> emu | jit
9898 erlang:system_info(Item :: emu_type) ->
9900 opt | debug | gcov | valgrind | gprof |
9901 lcnt | frmptr
9902 erlang:system_info(Item :: info) -> binary()
9904 erlang:system_info(Item :: kernel_poll) -> boolean()
9906 erlang:system_info(Item :: loaded) -> binary()
9908 erlang:system_info(Item :: machine) -> string()
9910 erlang:system_info(Item :: modified_timing_level) ->
9912 integer() | undefined
9913 erlang:system_info(Item :: nif_version) -> string()
9915 erlang:system_info(Item :: otp_release) -> string()
9917 erlang:system_info(Item :: outstanding_system_requests_limit) ->
9919 1..134217727
9920 erlang:system_info(Item :: port_parallelism) -> boolean()
9922 erlang:system_info(Item :: system_architecture) -> string()
9924 erlang:system_info(Item :: system_logger) ->
9926 logger | undefined | pid()
9927 erlang:system_info(Item :: system_version) -> string()
9929 erlang:system_info(Item :: trace_control_word) ->
9931 integer() >= 0
9932 erlang:system_info(Item :: version) -> string()
9934 erlang:system_info(Item ::
9936 wordsize |
9937 {wordsize, internal} |
9938 {wordsize, external}) ->
9939 4 | 8
9940 Returns various information about the current system (emulator)
9942 as specified by Item:
9943 build_type:
9945 Deprecated, use emu_type instead
9946 c_compiler_used:
9948 Returns a two-tuple describing the C compiler used when com‐
9949 piling the runtime system. The first element is an atom de‐
9950 scribing the name of the compiler, or undefined if unknown.
9951 The second element is a term describing the version of the
9952 compiler, or undefined if unknown.
9953 check_io:
9955 Returns a list containing miscellaneous information about
9956 the emulators internal I/O checking. Notice that the content
9957 of the returned list can vary between platforms and over
9958 time. It is only guaranteed that a list is returned.
9959 compat_rel:
9961 Returns the compatibility mode of the local node as an inte‐
9962 ger. The integer returned represents the Erlang/OTP release
9963 that the current emulator has been set to be backward com‐
9964 patible with. The compatibility mode can be configured at
9965 startup by using command-line flag +R in erl(1).
9966 debug_compiled:
9968 Returns true if the emulator has been debug-compiled, other‐
9969 wise false.
9970 driver_version:
9972 Returns a string containing the Erlang driver version used
9973 by the runtime system. It has the form "<major ver>.<minor
9974 ver>".
9975 dynamic_trace:
9977 Returns an atom describing the dynamic trace framework com‐
9978 piled into the virtual machine. It can be dtrace, systemtap,
9979 or none. For a commercial or standard build, it is always
9980 none. The other return values indicate a custom configura‐
9981 tion (for example, ./configure --with-dynamic-trace=dtrace).
9982 For more information about dynamic tracing, see dyntrace(3)
9983 manual page and the README.dtrace/README.systemtap files in
9984 the Erlang source code top directory.
9985 dynamic_trace_probes:
9987 Returns a boolean() indicating if dynamic trace probes
9988 (dtrace or systemtap) are built into the emulator. This can
9989 only be true if the virtual machine was built for dynamic
9990 tracing (that is, system_info(dynamic_trace) returns dtrace
9991 or systemtap).
9992 emu_flavor:
9994 Returns an atom describing the flavor of the runtime system.
9995 This will be either emu or jit. Possible return values can
9996 be added or removed at any time without prior notice.
9997 emu_type:
9999 Returns an atom describing the build type of the runtime
10000 system. This is normally the atom opt for optimized. Other
10001 possible return values are debug, gcov, valgrind, gprof, and
10002 lcnt. Possible return values can be added or removed at any
10003 time without prior notice.
10004 info:
10006 Returns a binary containing a string of miscellaneous system
10007 information formatted as in Erlang crash dumps. For more in‐
10008 formation, see section How to interpret the Erlang crash
10009 dumps in the User's Guide.
10010 kernel_poll:
10012 Returns true if the emulator uses some kind of kernel-poll
10013 implementation, otherwise false.
10014 loaded:
10016 Returns a binary containing a string of loaded module infor‐
10017 mation formatted as in Erlang crash dumps. For more informa‐
10018 tion, see section How to interpret the Erlang crash dumps in
10019 the User's Guide.
10020 machine:
10022 Returns a string containing the Erlang machine name.
10023 modified_timing_level:
10025 Returns the modified timing-level (an integer) if modified
10026 timing is enabled, otherwise undefined. For more information
10027 about modified timing, see command-line flag +T in erl(1)
10028 nif_version:
10030 Returns a string containing the version of the Erlang NIF
10031 interface used by the runtime system. It is on the form
10032 "<major ver>.<minor ver>".
10033 otp_release:
10035 Returns a string containing the OTP release number of the
10038 OTP release that the currently executing ERTS application is
10039 part of.
10040 As from Erlang/OTP 17, the OTP release number corresponds to
10042 the major OTP version number. No erlang:system_info() argu‐
10043 ment gives the exact OTP version. This is because the exact
10044 OTP version in the general case is difficult to determine.
10045 For more information, see the description of versions in
10046 System principles in System Documentation.
10047 outstanding_system_requests_limit:
10049 Returns the limit on the amount of outstanding requests made
10050 by a system process orchestrating system wide changes. See
10051 erlang:system_flag(outstanding_system_requests_limit, Limit)
10052 for more information.
10053 port_parallelism:
10055 Returns the default port parallelism scheduling hint used.
10056 For more information, see command-line argument +spp in
10057 erl(1).
10058 system_architecture:
10060 Returns a string containing the processor and OS architec‐
10061 ture the emulator is built for.
10062 system_logger:
10064 Returns the current system_logger as set by erlang:sys‐
10065 tem_flag(system_logger, _).
10066 system_version:
10068 Returns a string containing version number and some impor‐
10069 tant properties, such as the number of schedulers.
10070 trace_control_word:
10072 Returns the value of the node trace control word. For more
10073 information, see function get_tcw in section Match Specifi‐
10074 cations in Erlang in the User's Guide.
10075 version:
10077 Returns a string containing the version number of the emula‐
10078 tor.
10079 wordsize:
10081 Same as {wordsize, internal}.
10082 {wordsize, internal}:
10084 Returns the size of Erlang term words in bytes as an inte‐
10085 ger, that is, 4 is returned on a 32-bit architecture, and 8
10086 is returned on a 64-bit architecture.
10087 {wordsize, external}:
10089 Returns the true word size of the emulator, that is, the
10090 size of a pointer. The value is given in bytes as an inte‐
10091 ger. On a pure 32-bit architecture, 4 is returned. On a
10092 64-bit architecture, 8 is returned.
10093 erlang:system_monitor() -> MonSettings
10095 Types:
10097 MonSettings = undefined | {MonitorPid, Options}
10099 MonitorPid = pid()
10100 Options = [system_monitor_option()]
10101 system_monitor_option() =
10102 busy_port | busy_dist_port |
10103 {long_gc, integer() >= 0} |
10104 {long_schedule, integer() >= 0} |
10105 {large_heap, integer() >= 0}
10106 Returns the current system monitoring settings set by er‐
10108 lang:system_monitor/2 as {MonitorPid, Options}, or undefined if
10109 no settings exist. The order of the options can be different
10110 from the one that was set.
10111 erlang:system_monitor(Arg) -> MonSettings
10113 Types:
10115 Arg = MonSettings = undefined | {MonitorPid, Options}
10117 MonitorPid = pid()
10118 Options = [system_monitor_option()]
10119 system_monitor_option() =
10120 busy_port | busy_dist_port |
10121 {long_gc, integer() >= 0} |
10122 {long_schedule, integer() >= 0} |
10123 {large_heap, integer() >= 0}
10124 When called with argument undefined, all system performance mon‐
10126 itoring settings are cleared.
10127 Calling the function with {MonitorPid, Options} as argument is
10129 the same as calling erlang:system_monitor(MonitorPid, Options).
10130 Returns the previous system monitor settings just like er‐
10132 lang:system_monitor/0.
10133 erlang:system_monitor(MonitorPid, Options) -> MonSettings
10135 Types:
10137 MonitorPid = pid()
10139 Options = [system_monitor_option()]
10140 MonSettings = undefined | {OldMonitorPid, OldOptions}
10141 OldMonitorPid = pid()
10142 OldOptions = [system_monitor_option()]
10143 system_monitor_option() =
10144 busy_port | busy_dist_port |
10145 {long_gc, integer() >= 0} |
10146 {long_schedule, integer() >= 0} |
10147 {large_heap, integer() >= 0}
10148 Sets the system performance monitoring options. MonitorPid is a
10150 local process identifier (pid) receiving system monitor mes‐
10151 sages. The second argument is a list of monitoring options:
10152 {long_gc, Time}:
10154 If a garbage collection in the system takes at least Time
10155 wall clock milliseconds, a message {monitor, GcPid, long_gc,
10156 Info} is sent to MonitorPid. GcPid is the pid that was
10157 garbage collected. Info is a list of two-element tuples de‐
10158 scribing the result of the garbage collection.
10159 One of the tuples is {timeout, GcTime}, where GcTime is the
10161 time for the garbage collection in milliseconds. The other
10162 tuples are tagged with heap_size, heap_block_size,
10163 stack_size, mbuf_size, old_heap_size, and
10164 old_heap_block_size. These tuples are explained in the de‐
10165 scription of trace message gc_minor_start (see er‐
10166 lang:trace/3). New tuples can be added, and the order of the
10167 tuples in the Info list can be changed at any time without
10168 prior notice.
10169 {long_schedule, Time}:
10171 If a process or port in the system runs uninterrupted for at
10172 least Time wall clock milliseconds, a message {monitor, Pi‐
10173 dOrPort, long_schedule, Info} is sent to MonitorPid. PidOr‐
10174 Port is the process or port that was running. Info is a list
10175 of two-element tuples describing the event.
10176 If a pid(), the tuples {timeout, Millis}, {in, Location},
10178 and {out, Location} are present, where Location is either an
10179 MFA ({Module, Function, Arity}) describing the function
10180 where the process was scheduled in/out, or the atom unde‐
10181 fined.
10182 If a port(), the tuples {timeout, Millis} and {port_op,Op}
10184 are present. Op is one of proc_sig, timeout, input, output,
10185 event, or dist_cmd, depending on which driver callback was
10186 executing.
10187 proc_sig is an internal operation and is never to appear,
10189 while the others represent the corresponding driver call‐
10190 backs timeout, ready_input, ready_output, event, and outputv
10191 (when the port is used by distribution). Value Millis in tu‐
10192 ple timeout informs about the uninterrupted execution time
10193 of the process or port, which always is equal to or higher
10194 than the Time value supplied when starting the trace. New
10195 tuples can be added to the Info list in a future release.
10196 The order of the tuples in the list can be changed at any
10197 time without prior notice.
10198 This can be used to detect problems with NIFs or drivers
10200 that take too long to execute. 1 ms is considered a good
10201 maximum time for a driver callback or a NIF. However, a
10202 time-sharing system is usually to consider everything < 100
10203 ms as "possible" and fairly "normal". However, longer sched‐
10204 ule times can indicate swapping or a misbehaving NIF/driver.
10205 Misbehaving NIFs and drivers can cause bad resource utiliza‐
10206 tion and bad overall system performance.
10207 {large_heap, Size}:
10209 If a garbage collection in the system results in the allo‐
10210 cated size of a heap being at least Size words, a message
10211 {monitor, GcPid, large_heap, Info} is sent to MonitorPid.
10212 GcPid and Info are the same as for long_gc earlier, except
10213 that the tuple tagged with timeout is not present.
10214 The monitor message is sent if the sum of the sizes of all
10216 memory blocks allocated for all heap generations after a
10217 garbage collection is equal to or higher than Size.
10218 When a process is killed by max_heap_size, it is killed be‐
10220 fore the garbage collection is complete and thus no large
10221 heap message is sent.
10222 busy_port:
10224 If a process in the system gets suspended because it sends
10225 to a busy port, a message {monitor, SusPid, busy_port, Port}
10226 is sent to MonitorPid. SusPid is the pid that got suspended
10227 when sending to Port.
10228 busy_dist_port:
10230 If a process in the system gets suspended because it sends
10231 to a process on a remote node whose inter-node communication
10232 was handled by a busy port, a message {monitor, SusPid,
10233 busy_dist_port, Port} is sent to MonitorPid. SusPid is the
10234 pid that got suspended when sending through the inter-node
10235 communication port Port.
10236 Returns the previous system monitor settings just like er‐
10238 lang:system_monitor/0.
10239 The arguments to system_monitor/2 specifies how all system moni‐
10241 toring on the node should be done, not how it should be changed.
10242 This means only one process at a time (MonitorPid) can be the
10243 receiver of system monitor messages. Also, the way to clear a
10244 specific monitor option is to not include it in the list Op‐
10245 tions. All system monitoring will, however, be cleared if the
10246 process identified by MonitorPid terminates.
10247 There are no special option values (like zero) to clear an op‐
10249 tion. Some of the options have a unspecified minimum value.
10250 Lower values will be adjusted to the minimum value. For example,
10251 it is currently not possible to monitor all garbage collections
10252 with {long_gc, 0}.
10253 Note:
10255 If a monitoring process gets so large that it itself starts to
10256 cause system monitor messages when garbage collecting, the mes‐
10257 sages enlarge the process message queue and probably make the
10258 problem worse.
10259 Keep the monitoring process neat and do not set the system moni‐
10261 tor limits too tight.
10262 Failures:
10265 badarg:
10267 If MonitorPid does not exist.
10268 badarg:
10270 If MonitorPid is not a local process.
10271 erlang:system_profile() -> ProfilerSettings
10273 Types:
10275 ProfilerSettings = undefined | {ProfilerPid, Options}
10277 ProfilerPid = pid() | port()
10278 Options = [system_profile_option()]
10279 system_profile_option() =
10280 exclusive | runnable_ports | runnable_procs | scheduler |
10281 timestamp | monotonic_timestamp | strict_monotonic_timestamp
10282 Returns the current system profiling settings set by erlang:sys‐
10284 tem_profile/2 as {ProfilerPid, Options}, or undefined if there
10285 are no settings. The order of the options can be different from
10286 the one that was set.
10287 erlang:system_profile(ProfilerPid, Options) -> ProfilerSettings
10289 Types:
10291 ProfilerPid = pid() | port() | undefined
10293 Options = [system_profile_option()]
10294 ProfilerSettings =
10295 undefined | {pid() | port(), [system_profile_option()]}
10296 system_profile_option() =
10297 exclusive | runnable_ports | runnable_procs | scheduler |
10298 timestamp | monotonic_timestamp | strict_monotonic_timestamp
10299 Sets system profiler options. ProfilerPid is a local process
10301 identifier (pid) or port receiving profiling messages. The re‐
10302 ceiver is excluded from all profiling. The second argument is a
10303 list of profiling options:
10304 exclusive:
10306 If a synchronous call to a port from a process is done, the
10307 calling process is considered not runnable during the call
10308 runtime to the port. The calling process is notified as in‐
10309 active, and later active when the port callback returns.
10310 monotonic_timestamp:
10312 Time stamps in profile messages use Erlang monotonic time.
10313 The time stamp (Ts) has the same format and value as pro‐
10314 duced by erlang:monotonic_time(nanosecond).
10315 runnable_procs:
10317 If a process is put into or removed from the run queue, a
10318 message, {profile, Pid, State, Mfa, Ts}, is sent to Profil‐
10319 erPid. Running processes that are reinserted into the run
10320 queue after having been pre-empted do not trigger this mes‐
10321 sage.
10322 runnable_ports:
10324 If a port is put into or removed from the run queue, a mes‐
10325 sage, {profile, Port, State, 0, Ts}, is sent to ProfilerPid.
10326 scheduler:
10328 If a scheduler is put to sleep or awoken, a message, {pro‐
10329 file, scheduler, Id, State, NoScheds, Ts}, is sent to Pro‐
10330 filerPid.
10331 strict_monotonic_timestamp:
10333 Time stamps in profile messages consist of Erlang monotonic
10334 time and a monotonically increasing integer. The time stamp
10335 (Ts) has the same format and value as produced by {er‐
10336 lang:monotonic_time(nanosecond), erlang:unique_inte‐
10337 ger([monotonic])}.
10338 timestamp:
10340 Time stamps in profile messages include a time stamp (Ts)
10341 that has the same form as returned by erlang:now(). This is
10342 also the default if no time stamp flag is specified. If
10343 cpu_timestamp has been enabled through erlang:trace/3, this
10344 also effects the time stamp produced in profiling messages
10345 when flag timestamp is enabled.
10346 Note:
10348 erlang:system_profile behavior can change in a future release.
10349 erlang:system_time() -> integer()
10352 Returns current Erlang system time in native time unit.
10354 Calling erlang:system_time() is equivalent to erlang:mono‐
10356 tonic_time() + erlang:time_offset().
10357 Note:
10359 This time is not a monotonically increasing time in the general
10360 case. For more information, see the documentation of time warp
10361 modes in the User's Guide.
10362 erlang:system_time(Unit) -> integer()
10365 Types:
10367 Unit = time_unit()
10369 Returns current Erlang system time converted into the Unit
10371 passed as argument.
10372 Calling erlang:system_time(Unit) is equivalent to erlang:con‐
10374 vert_time_unit(erlang:system_time(), native, Unit).
10375 Note:
10377 This time is not a monotonically increasing time in the general
10378 case. For more information, see the documentation of time warp
10379 modes in the User's Guide.
10380 term_to_binary(Term) -> ext_binary()
10383 Types:
10385 Term = term()
10387 Returns a binary data object that is the result of encoding Term
10389 according to the Erlang external term format.
10390 This can be used for various purposes, for example, writing a
10392 term to a file in an efficient way, or sending an Erlang term to
10393 some type of communications channel not supported by distributed
10394 Erlang.
10395 > Bin = term_to_binary(hello).
10397 <<131,100,0,5,104,101,108,108,111>>
10398 > hello = binary_to_term(Bin).
10399 hello
10400 See also binary_to_term/1.
10403 Note:
10405 There is no guarantee that this function will return the same
10406 encoded representation for the same term.
10407 term_to_binary(Term, Options) -> ext_binary()
10410 Types:
10412 Term = term()
10414 Options =
10415 [compressed |
10416 {compressed, Level :: 0..9} |
10417 deterministic |
10418 {minor_version, Version :: 0..2}]
10419 Returns a binary data object that is the result of encoding Term
10421 according to the Erlang external term format.
10422 If option compressed is provided, the external term format is
10424 compressed. The compressed format is automatically recognized by
10425 binary_to_term/1 as from Erlang/OTP R7B.
10426 A compression level can be specified by giving option {com‐
10428 pressed, Level}. Level is an integer with range 0..9, where:
10429 * 0 - No compression is done (it is the same as giving no com‐
10431 pressed option).
10432 * 1 - Takes least time but may not compress as well as the
10434 higher levels.
10435 * 6 - Default level when option compressed is provided.
10437 * 9 - Takes most time and tries to produce a smaller result.
10439 Notice "tries" in the preceding sentence; depending on the
10440 input term, level 9 compression either does or does not pro‐
10441 duce a smaller result than level 1 compression.
10442 Option {minor_version, Version} can be used to control some en‐
10444 coding details. This option was introduced in Erlang/OTP R11B-4.
10445 The valid values for Version are:
10446 0:
10448 Floats are encoded using a textual representation. This op‐
10449 tion is useful to ensure that releases before Erlang/OTP
10450 R11B-4 can decode resulting binary.
10451 This version encode atoms that can be represented by a
10453 latin1 string using latin1 encoding while only atoms that
10454 cannot be represented by latin1 are encoded using utf8.
10455 1:
10457 This is as of Erlang/OTP 17.0 the default. It forces any
10458 floats in the term to be encoded in a more space-efficient
10459 and exact way (namely in the 64-bit IEEE format, rather than
10460 converted to a textual representation). As from Erlang/OTP
10461 R11B-4, binary_to_term/1 can decode this representation.
10462 This version encode atoms that can be represented by a
10464 latin1 string using latin1 encoding while only atoms that
10465 cannot be represented by latin1 are encoded using utf8.
10466 2:
10468 Drops usage of the latin1 atom encoding and unconditionally
10469 use utf8 encoding for all atoms. Erlang/OTP systems as of
10470 R16B can decode this representation.
10471 Note:
10473 In Erlang/OTP 26, the default minor_version is planned to
10474 change from 1 to 2. See Upcoming Potential Incompatibilities
10475 .
10476 Option deterministic (introduced in OTP 24.1) can be used to en‐
10479 sure that within the same major release of Erlang/OTP, the same
10480 encoded representation is returned for the same term. There is
10481 still no guarantee that the encoded representation remains the
10482 same between major releases of Erlang/OTP.
10483 See also binary_to_term/1.
10485 term_to_iovec(Term) -> ext_iovec()
10487 Types:
10489 Term = term()
10491 Returns the encoding of Term according to the Erlang external
10493 term format as ext_iovec().
10494 This function produce the same encoding as term_to_binary/1, but
10496 with another return type. The call iolist_to_bi‐
10497 nary(term_to_iovec(Term)) will produce exactly the same result
10498 as the call term_to_binary(Term).
10499 term_to_iovec() is a pure optimization of the functionality
10501 term_to_binary() provide. term_to_iovec() can for example refer
10502 directly to off heap binaries instead of copying the binary data
10503 into the result.
10504 See also term_to_binary/1.
10506 term_to_iovec(Term, Options) -> ext_iovec()
10508 Types:
10510 Term = term()
10512 Options =
10513 [compressed |
10514 {compressed, Level :: 0..9} |
10515 deterministic |
10516 {minor_version, Version :: 0..2}]
10517 Returns the encoding of Term according to the Erlang external
10519 term format as ext_iovec().
10520 This function produce the same encoding as term_to_binary/2, but
10522 with another return type. The call iolist_to_bi‐
10523 nary(term_to_iovec(Term, Opts)) will produce exactly the same
10524 result as term_to_binary(Term, Opts).
10525 Currently recognised options are all options recognised by
10527 term_to_binary/2.
10528 term_to_iovec() is a pure optimization of the functionality
10530 term_to_binary() provide. term_to_iovec() can for example refer
10531 directly to off heap binaries instead of copying the binary data
10532 into the result.
10533 See also term_to_binary/2.
10535 throw(Any) -> no_return()
10537 Types:
10539 Any = term()
10541 Raises an exception of class throw. Intended to be used to do
10543 non-local returns from functions.
10544 If evaluated within a catch expression, the catch expression
10546 returns value Any. Example:
10547 > catch throw({hello, there}).
10549 {hello,there}
10550 If evaluated within a try-block of a try expression, the value
10552 Any can be caught within the catch block. Example:
10553 try
10555 throw({my_exception, "Something happened"})
10556 catch
10557 throw:{my_exception, Desc} ->
10558 io:format(standard_error, "Error: ~s~n", [Desc])
10559 end
10560 Failure: nocatch if not caught by an exception handler.
10562 See the guide about errors and error handling for additional in‐
10564 formation.
10565 time() -> Time
10567 Types:
10569 Time = calendar:time()
10571 Returns the current time as {Hour, Minute, Second}.
10573 The time zone and Daylight Saving Time correction depend on the
10575 underlying OS. The return value is based on the OS System Time.
10576 Example:
10577 > time().
10579 {9,42,44}
10580 erlang:time_offset() -> integer()
10582 Returns the current time offset between Erlang monotonic time
10584 and Erlang system time in native time unit. Current time offset
10585 added to an Erlang monotonic time gives corresponding Erlang
10586 system time.
10587 The time offset may or may not change during operation depending
10589 on the time warp mode used.
10590 Note:
10592 A change in time offset can be observed at slightly different
10593 points in time by different processes.
10594 If the runtime system is in multi-time warp mode, the time off‐
10596 set is changed when the runtime system detects that the OS sys‐
10597 tem time has changed. The runtime system will, however, not de‐
10598 tect this immediately when it occurs. A task checking the time
10599 offset is scheduled to execute at least once a minute; so, under
10600 normal operation this is to be detected within a minute, but
10601 during heavy load it can take longer time.
10602 erlang:time_offset(Unit) -> integer()
10605 Types:
10607 Unit = time_unit()
10609 Returns the current time offset between Erlang monotonic time
10611 and Erlang system time converted into the Unit passed as argu‐
10612 ment.
10613 Same as calling erlang:convert_time_unit(erlang:time_offset(),
10615 native, Unit) however optimized for commonly used Units.
10616 erlang:timestamp() -> Timestamp
10618 Types:
10620 Timestamp = timestamp()
10622 timestamp() =
10623 {MegaSecs :: integer() >= 0,
10624 Secs :: integer() >= 0,
10625 MicroSecs :: integer() >= 0}
10626 Returns current Erlang system time on the format {MegaSecs,
10628 Secs, MicroSecs}. This format is the same as os:timestamp/0 and
10629 the deprecated erlang:now/0 use. The reason for the existence of
10630 erlang:timestamp() is purely to simplify use for existing code
10631 that assumes this time stamp format. Current Erlang system time
10632 can more efficiently be retrieved in the time unit of your
10633 choice using erlang:system_time/1.
10634 The erlang:timestamp() BIF is equivalent to:
10636 timestamp() ->
10638 ErlangSystemTime = erlang:system_time(microsecond),
10639 MegaSecs = ErlangSystemTime div 1000_000_000_000,
10640 Secs = ErlangSystemTime div 1000_000 - MegaSecs*1000_000,
10641 MicroSecs = ErlangSystemTime rem 1000_000,
10642 {MegaSecs, Secs, MicroSecs}.
10643 It, however, uses a native implementation that does not build
10645 garbage on the heap and with slightly better performance.
10646 Note:
10648 This time is not a monotonically increasing time in the general
10649 case. For more information, see the documentation of time warp
10650 modes in the User's Guide.
10651 tl(List) -> term()
10654 Types:
10656 List = nonempty_maybe_improper_list()
10658 Returns the tail of List, that is, the list minus the first ele‐
10660 ment, for example:
10661 > tl([geesties, guilies, beasties]).
10663 [guilies, beasties]
10664 > tl([geesties]).
10666 []
10667 > tl([geesties, guilies, beasties | improper_end]).
10669 [guilies, beasties | improper_end]
10670 > tl([geesties | improper_end]).
10672 improper_end
10673 Allowed in guard tests.
10675 Failure: badarg if List is the empty list [].
10677 erlang:trace(PidPortSpec, How, FlagList) -> integer()
10679 Types:
10681 PidPortSpec =
10683 pid() |
10684 port() |
10685 all | processes | ports | existing | existing_processes |
10686 existing_ports | new | new_processes | new_ports
10687 How = boolean()
10688 FlagList = [trace_flag()]
10689 trace_flag() =
10690 all | send | 'receive' | procs | ports | call | arity |
10691 return_to | silent | running | exiting | running_procs |
10692 running_ports | garbage_collection | timestamp |
10693 cpu_timestamp | monotonic_timestamp |
10694 strict_monotonic_timestamp | set_on_spawn |
10695 set_on_first_spawn | set_on_link | set_on_first_link |
10696 {tracer, pid() | port()} |
10697 {tracer, module(), term()}
10698 Turns on (if How == true) or off (if How == false) the trace
10700 flags in FlagList for the process or processes represented by
10701 PidPortSpec.
10702 PidPortSpec is either a process identifier (pid) for a local
10704 process, a port identifier, or one of the following atoms:
10705 all:
10707 All currently existing processes and ports and all that will
10708 be created in the future.
10709 processes:
10711 All currently existing processes and all that will be cre‐
10712 ated in the future.
10713 ports:
10715 All currently existing ports and all that will be created in
10716 the future.
10717 existing:
10719 All currently existing processes and ports.
10720 existing_processes:
10722 All currently existing processes.
10723 existing_ports:
10725 All currently existing ports.
10726 new:
10728 All processes and ports that will be created in the future.
10729 new_processes:
10731 All processes that will be created in the future.
10732 new_ports:
10734 All ports that will be created in the future.
10735 FlagList can contain any number of the following flags (the
10737 "message tags" refers to the list of trace messages):
10738 all:
10740 Sets all trace flags except tracer and cpu_timestamp, which
10741 are in their nature different than the others.
10742 send:
10744 Traces sending of messages.
10745 Message tags: send and send_to_non_existing_process.
10747 'receive':
10749 Traces receiving of messages.
10750 Message tags: 'receive'.
10752 call:
10754 Traces certain function calls. Specify which function calls
10755 to trace by calling erlang:trace_pattern/3.
10756 Message tags: call and return_from.
10758 silent:
10760 Used with the call trace flag. The call, return_from, and
10761 return_to trace messages are inhibited if this flag is set,
10762 but they are executed as normal if there are match specifi‐
10763 cations.
10764 Silent mode is inhibited by executing erlang:trace(_, false,
10766 [silent|_]), or by a match specification executing the func‐
10767 tion {silent, false}.
10768 The silent trace flag facilitates setting up a trace on many
10770 or even all processes in the system. The trace can then be
10771 activated and deactivated using the match specification
10772 function {silent,Bool}, giving a high degree of control of
10773 which functions with which arguments that trigger the trace.
10774 Message tags: call, return_from, and return_to. Or rather,
10776 the absence of.
10777 return_to:
10779 Used with the call trace flag. Traces the return from a
10780 traced function back to its caller. Only works for functions
10781 traced with option local to erlang:trace_pattern/3.
10782 The semantics is that a trace message is sent when a call
10784 traced function returns, that is, when a chain of tail re‐
10785 cursive calls ends. Only one trace message is sent per chain
10786 of tail recursive calls, so the properties of tail recur‐
10787 siveness for function calls are kept while tracing with this
10788 flag. Using call and return_to trace together makes it pos‐
10789 sible to know exactly in which function a process executes
10790 at any time.
10791 To get trace messages containing return values from func‐
10793 tions, use the {return_trace} match specification action in‐
10794 stead.
10795 Message tags: return_to.
10797 procs:
10799 Traces process-related events.
10800 Message tags: spawn, spawned, exit, register, unregister,
10802 link, unlink, getting_linked, and getting_unlinked.
10803 ports:
10805 Traces port-related events.
10806 Message tags: open, closed, register, unregister, get‐
10808 ting_linked, and getting_unlinked.
10809 running:
10811 Traces scheduling of processes.
10812 Message tags: in and out.
10814 exiting:
10816 Traces scheduling of exiting processes.
10817 Message tags: in_exiting, out_exiting, and out_exited.
10819 running_procs:
10821 Traces scheduling of processes just like running. However,
10822 this option also includes schedule events when the process
10823 executes within the context of a port without being sched‐
10824 uled out itself.
10825 Message tags: in and out.
10827 running_ports:
10829 Traces scheduling of ports.
10830 Message tags: in and out.
10832 garbage_collection:
10834 Traces garbage collections of processes.
10835 Message tags: gc_minor_start, gc_max_heap_size, and gc_mi‐
10837 nor_end.
10838 timestamp:
10840 Includes a time stamp in all trace messages. The time stamp
10841 (Ts) has the same form as returned by erlang:now().
10842 cpu_timestamp:
10844 A global trace flag for the Erlang node that makes all trace
10845 time stamps using flag timestamp to be in CPU time, not wall
10846 clock time. That is, cpu_timestamp is not be used if mono‐
10847 tonic_timestamp or strict_monotonic_timestamp is enabled.
10848 Only allowed with PidPortSpec==all. If the host machine OS
10849 does not support high-resolution CPU time measurements,
10850 trace/3 exits with badarg. Notice that most OS do not syn‐
10851 chronize this value across cores, so be prepared that time
10852 can seem to go backwards when using this option.
10853 monotonic_timestamp:
10855 Includes an Erlang monotonic time time stamp in all trace
10856 messages. The time stamp (Ts) has the same format and value
10857 as produced by erlang:monotonic_time(nanosecond). This flag
10858 overrides flag cpu_timestamp.
10859 strict_monotonic_timestamp:
10861 Includes an time stamp consisting of Erlang monotonic time
10862 and a monotonically increasing integer in all trace mes‐
10863 sages. The time stamp (Ts) has the same format and value as
10864 produced by { erlang:monotonic_time(nanosecond), er‐
10865 lang:unique_integer([monotonic])}. This flag overrides flag
10866 cpu_timestamp.
10867 arity:
10869 Used with the call trace flag. {M, F, Arity} is specified
10870 instead of {M, F, Args} in call trace messages.
10871 set_on_spawn:
10873 Makes any process created by a traced process inherit its
10874 trace flags, including flag set_on_spawn.
10875 set_on_first_spawn:
10877 Makes the first process created by a traced process inherit
10878 its trace flags, excluding flag set_on_first_spawn.
10879 set_on_link:
10881 Makes any process linked by a traced process inherit its
10882 trace flags, including flag set_on_link.
10883 set_on_first_link:
10885 Makes the first process linked to by a traced process in‐
10886 herit its trace flags, excluding flag set_on_first_link.
10887 {tracer, Tracer}:
10889 Specifies where to send the trace messages. Tracer must be
10890 the process identifier of a local process or the port iden‐
10891 tifier of a local port.
10892 {tracer, TracerModule, TracerState}:
10894 Specifies that a tracer module is to be called instead of
10895 sending a trace message. The tracer module can then ignore
10896 or change the trace message. For more details on how to
10897 write a tracer module, see erl_tracer(3).
10898 If no tracer is specified, the calling process receives all the
10900 trace messages.
10901 The effect of combining set_on_first_link with set_on_link is
10903 the same as set_on_first_link alone. Likewise for set_on_spawn
10904 and set_on_first_spawn.
10905 The tracing process receives the trace messages described in the
10907 following list. Pid is the process identifier of the traced
10908 process in which the traced event has occurred. The third tuple
10909 element is the message tag.
10910 If flag timestamp, strict_monotonic_timestamp, or mono‐
10912 tonic_timestamp is specified, the first tuple element is
10913 trace_ts instead, and the time stamp is added as an extra ele‐
10914 ment last in the message tuple. If multiple time stamp flags are
10915 passed, timestamp has precedence over strict_monotonic_time‐
10916 stamp, which in turn has precedence over monotonic_timestamp.
10917 All time stamp flags are remembered, so if two are passed and
10918 the one with highest precedence later is disabled, the other one
10919 becomes active.
10920 If a match specification (applicable only for call, send and
10922 'receive' tracing) contains a {message} action function with a
10923 non-boolean value, that value is added as an extra element to
10924 the message tuple either in the last position or before the
10925 timestamp (if it is present).
10926 Trace messages:
10928 {trace, PidPort, send, Msg, To}:
10930 When PidPort sends message Msg to process To.
10931 {trace, PidPort, send_to_non_existing_process, Msg, To}:
10933 When PidPort sends message Msg to the non-existing process
10934 To.
10935 {trace, PidPort, 'receive', Msg}:
10937 When PidPort receives message Msg. If Msg is set to time-
10938 out, a receive statement can have timed out, or the process
10939 received a message with the payload timeout.
10940 {trace, Pid, call, {M, F, Args}}:
10942 When Pid calls a traced function. The return values of calls
10943 are never supplied, only the call and its arguments.
10944 Trace flag arity can be used to change the contents of this
10946 message, so that Arity is specified instead of Args.
10947 {trace, Pid, return_to, {M, F, Arity}}:
10949 When Pid returns to the specified function. This trace mes‐
10950 sage is sent if both the flags call and return_to are set,
10951 and the function is set to be traced on local function
10952 calls. The message is only sent when returning from a chain
10953 of tail recursive function calls, where at least one call
10954 generated a call trace message (that is, the functions match
10955 specification matched, and {message, false} was not an ac‐
10956 tion).
10957 {trace, Pid, return_from, {M, F, Arity}, ReturnValue}:
10959 When Pid returns from the specified function. This trace
10960 message is sent if flag call is set, and the function has a
10961 match specification with a return_trace or exception_trace
10962 action.
10963 {trace, Pid, exception_from, {M, F, Arity}, {Class, Value}}:
10965 When Pid exits from the specified function because of an ex‐
10966 ception. This trace message is sent if flag call is set, and
10967 the function has a match specification with an excep‐
10968 tion_trace action.
10969 {trace, Pid, spawn, Pid2, {M, F, Args}}:
10971 When Pid spawns a new process Pid2 with the specified func‐
10972 tion call as entry point.
10973 Args is supposed to be the argument list, but can be any
10975 term if the spawn is erroneous.
10976 {trace, Pid, spawned, Pid2, {M, F, Args}}:
10978 When Pid is spawned by process Pid2 with the specified func‐
10979 tion call as entry point.
10980 Args is supposed to be the argument list, but can be any
10982 term if the spawn is erroneous.
10983 {trace, Pid, exit, Reason}:
10985 When Pid exits with reason Reason.
10986 {trace, PidPort, register, RegName}:
10988 When PidPort gets the name RegName registered.
10989 {trace, PidPort, unregister, RegName}:
10991 When PidPort gets the name RegName unregistered. This is
10992 done automatically when a registered process or port exits.
10993 {trace, Pid, link, Pid2}:
10995 When Pid links to a process Pid2.
10996 {trace, Pid, unlink, Pid2}:
10998 When Pid removes the link from a process Pid2.
10999 {trace, PidPort, getting_linked, Pid2}:
11001 When PidPort gets linked to a process Pid2.
11002 {trace, PidPort, getting_unlinked, Pid2}:
11004 When PidPort gets unlinked from a process Pid2.
11005 {trace, Port, open, Pid, Driver}:
11007 When Pid opens a new port Port with the running Driver.
11008 Driver is the name of the driver as an atom.
11010 {trace, Port, closed, Reason}:
11012 When Port closes with Reason.
11013 {trace, Pid, in | in_exiting, {M, F, Arity} | 0}:
11015 When Pid is scheduled to run. The process runs in function
11016 {M, F, Arity}. On some rare occasions, the current function
11017 cannot be determined, then the last element is 0.
11018 {trace, Pid, out | out_exiting | out_exited, {M, F, Arity} |
11020 0}:
11021 When Pid is scheduled out. The process was running in func‐
11022 tion {M, F, Arity}. On some rare occasions, the current
11023 function cannot be determined, then the last element is 0.
11024 {trace, Port, in, Command | 0}:
11026 When Port is scheduled to run. Command is the first thing
11027 the port will execute, it can however run several commands
11028 before being scheduled out. On some rare occasions, the cur‐
11029 rent function cannot be determined, then the last element is
11030 0.
11031 The possible commands are call, close, command, connect,
11033 control, flush, info, link, open, and unlink.
11034 {trace, Port, out, Command | 0}:
11036 When Port is scheduled out. The last command run was Com‐
11037 mand. On some rare occasions, the current function cannot be
11038 determined, then the last element is 0. Command can contain
11039 the same commands as in
11040 {trace, Pid, gc_minor_start, Info}:
11042 Sent when a young garbage collection is about to be started.
11045 Info is a list of two-element tuples, where the first ele‐
11046 ment is a key, and the second is the value. Do not depend on
11047 any order of the tuples. The following keys are defined:
11048 heap_size:
11050 The size of the used part of the heap.
11051 heap_block_size:
11053 The size of the memory block used for storing the heap and
11054 the stack.
11055 old_heap_size:
11057 The size of the used part of the old heap.
11058 old_heap_block_size:
11060 The size of the memory block used for storing the old
11061 heap.
11062 stack_size:
11064 The size of the stack.
11065 recent_size:
11067 The size of the data that survived the previous garbage
11068 collection.
11069 mbuf_size:
11071 The combined size of message buffers associated with the
11072 process.
11073 bin_vheap_size:
11075 The total size of unique off-heap binaries referenced from
11076 the process heap.
11077 bin_vheap_block_size:
11079 The total size of binaries allowed in the virtual heap in
11080 the process before doing a garbage collection.
11081 bin_old_vheap_size:
11083 The total size of unique off-heap binaries referenced from
11084 the process old heap.
11085 bin_old_vheap_block_size:
11087 The total size of binaries allowed in the virtual old heap
11088 in the process before doing a garbage collection.
11089 wordsize:
11091 For the gc_minor_start event it is the size of the need
11092 that triggered the GC. For the corresponding gc_minor_end
11093 event it is the size of reclaimed memory = start heap_size
11094 - end heap_size.
11095 All sizes are in words.
11097 {trace, Pid, gc_max_heap_size, Info}:
11099 Sent when the max_heap_size is reached during garbage col‐
11100 lection. Info contains the same kind of list as in message
11101 gc_start, but the sizes reflect the sizes that triggered
11102 max_heap_size to be reached.
11103 {trace, Pid, gc_minor_end, Info}:
11105 Sent when young garbage collection is finished. Info con‐
11106 tains the same kind of list as in message gc_minor_start,
11107 but the sizes reflect the new sizes after garbage collec‐
11108 tion.
11109 {trace, Pid, gc_major_start, Info}:
11111 Sent when fullsweep garbage collection is about to be
11112 started. Info contains the same kind of list as in message
11113 gc_minor_start.
11114 {trace, Pid, gc_major_end, Info}:
11116 Sent when fullsweep garbage collection is finished. Info
11117 contains the same kind of list as in message gc_minor_start,
11118 but the sizes reflect the new sizes after a fullsweep
11119 garbage collection.
11120 If the tracing process/port dies or the tracer module returns
11122 remove, the flags are silently removed.
11123 Each process can only be traced by one tracer. Therefore, at‐
11125 tempts to trace an already traced process fail.
11126 Returns a number indicating the number of processes that matched
11128 PidPortSpec. If PidPortSpec is a process identifier, the return
11129 value is 1. If PidPortSpec is all or existing, the return value
11130 is the number of processes running. If PidPortSpec is new, the
11131 return value is 0.
11132 Failure: badarg if the specified arguments are not supported.
11134 For example, cpu_timestamp is not supported on all platforms.
11135 erlang:trace_delivered(Tracee) -> Ref
11137 Types:
11139 Tracee = pid() | all
11141 Ref = reference()
11142 The delivery of trace messages (generated by erlang:trace/3,
11144 seq_trace(3), or erlang:system_profile/2) is dislocated on the
11145 time-line compared to other events in the system. If you know
11146 that Tracee has passed some specific point in its execution, and
11147 you want to know when at least all trace messages corresponding
11148 to events up to this point have reached the tracer, use er‐
11149 lang:trace_delivered(Tracee).
11150 When it is guaranteed that all trace messages are delivered to
11152 the tracer up to the point that Tracee reached at the time of
11153 the call to erlang:trace_delivered(Tracee), then a {trace_deliv‐
11154 ered, Tracee, Ref} message is sent to the caller of er‐
11155 lang:trace_delivered(Tracee) .
11156 Notice that message trace_delivered does not imply that trace
11158 messages have been delivered. Instead it implies that all trace
11159 messages that are to be delivered have been delivered. It is not
11160 an error if Tracee is not, and has not been traced by someone,
11161 but if this is the case, no trace messages have been delivered
11162 when the trace_delivered message arrives.
11163 Notice that Tracee must refer to a process currently or previ‐
11165 ously existing on the same node as the caller of er‐
11166 lang:trace_delivered(Tracee) resides on. The special Tracee atom
11167 all denotes all processes that currently are traced in the node.
11168 When used together with a Tracer Module, any message sent in
11170 the trace callback is guaranteed to have reached its recipient
11171 before the trace_delivered message is sent.
11172 Example: Process A is Tracee, port B is tracer, and process C is
11174 the port owner of B. C wants to close B when A exits. To ensure
11175 that the trace is not truncated, C can call erlang:trace_deliv‐
11176 ered(A) when A exits, and wait for message {trace_delivered, A,
11177 Ref} before closing B.
11178 Failure: badarg if Tracee does not refer to a process (dead or
11180 alive) on the same node as the caller of erlang:trace_deliv‐
11181 ered(Tracee) resides on.
11182 erlang:trace_info(PidPortFuncEvent, Item) -> Res
11184 Types:
11186 PidPortFuncEvent =
11188 pid() |
11189 port() |
11190 new | new_processes | new_ports |
11191 {Module, Function, Arity} |
11192 on_load | send | 'receive'
11193 Module = module()
11194 Function = atom()
11195 Arity = arity()
11196 Item =
11197 flags | tracer | traced | match_spec | meta |
11198 meta_match_spec | call_count | call_time | all
11199 Res = trace_info_return()
11200 trace_info_return() =
11201 undefined |
11202 {flags, [trace_info_flag()]} |
11203 {tracer, pid() | port() | []} |
11204 {tracer, module(), term()} |
11205 trace_info_item_result() |
11206 {all, [trace_info_item_result()] | false | undefined}
11207 trace_info_item_result() =
11208 {traced, global | local | false | undefined} |
11209 {match_spec, trace_match_spec() | false | undefined} |
11210 {meta, pid() | port() | false | undefined | []} |
11211 {meta, module(), term()} |
11212 {meta_match_spec, trace_match_spec() | false | undefined} |
11213 {call_count, integer() >= 0 | boolean() | undefined} |
11214 {call_time,
11215 [{pid(),
11216 integer() >= 0,
11217 integer() >= 0,
11218 integer() >= 0}] |
11219 boolean() |
11220 undefined}
11221 trace_info_flag() =
11222 send | 'receive' | set_on_spawn | call | return_to | procs |
11223 set_on_first_spawn | set_on_link | running |
11224 garbage_collection | timestamp | monotonic_timestamp |
11225 strict_monotonic_timestamp | arity
11226 trace_match_spec() =
11227 [{[term()] | '_' | match_variable(), [term()], [term()]}]
11228 match_variable() = atom()
11229 Approximation of '$1' | '$2' | '$3' | ...
11230 Returns trace information about a port, process, function, or
11232 event.
11233 To get information about a port or process, PidPortFuncEvent is
11235 to be a process identifier (pid), port identifier, or one of the
11236 atoms new, new_processes, or new_ports. The atom new or new_pro‐
11237 cesses means that the default trace state for processes to be
11238 created is returned. The atom new_ports means that the default
11239 trace state for ports to be created is returned.
11240 Valid Items for ports and processes:
11242 flags:
11244 Returns a list of atoms indicating what kind of traces is
11245 enabled for the process. The list is empty if no traces are
11246 enabled, and one or more of the followings atoms if traces
11247 are enabled: send, 'receive', set_on_spawn, call, return_to,
11248 procs, ports, set_on_first_spawn, set_on_link, running, run‐
11249 ning_procs, running_ports, silent, exiting, monotonic_time‐
11250 stamp, strict_monotonic_timestamp, garbage_collection, time‐
11251 stamp, and arity. The order is arbitrary.
11252 tracer:
11254 Returns the identifier for process, port, or a tuple con‐
11255 taining the tracer module and tracer state tracing this
11256 process. If this process is not traced, the return value is
11257 [].
11258 To get information about a function, PidPortFuncEvent is to be
11260 the three-element tuple {Module, Function, Arity} or the atom
11261 on_load. No wildcards are allowed. Returns undefined if the
11262 function does not exist, or false if the function is not traced.
11263 If PidPortFuncEvent is on_load, the information returned refers
11264 to the default value for code that will be loaded.
11265 Valid Items for functions:
11267 traced:
11269 Returns global if this function is traced on global function
11270 calls, local if this function is traced on local function
11271 calls (that is, local and global function calls), and false
11272 if local or global function calls are not traced.
11273 match_spec:
11275 Returns the match specification for this function, if it has
11276 one. If the function is locally or globally traced but has
11277 no match specification defined, the returned value is [].
11278 meta:
11280 Returns the meta-trace tracer process, port, or trace module
11281 for this function, if it has one. If the function is not
11282 meta-traced, the returned value is false. If the function is
11283 meta-traced but has once detected that the tracer process is
11284 invalid, the returned value is [].
11285 meta_match_spec:
11287 Returns the meta-trace match specification for this func‐
11288 tion, if it has one. If the function is meta-traced but has
11289 no match specification defined, the returned value is [].
11290 call_count:
11292 Returns the call count value for this function or true for
11293 the pseudo function on_load if call count tracing is active.
11294 Otherwise false is returned.
11295 See also erlang:trace_pattern/3.
11297 call_time:
11299 Returns the call time values for this function or true for
11300 the pseudo function on_load if call time tracing is active.
11301 Otherwise false is returned. The call time values returned,
11302 [{Pid, Count, S, Us}], is a list of each process that exe‐
11303 cuted the function and its specific counters.
11304 See also erlang:trace_pattern/3.
11306 all:
11308 Returns a list containing the {Item, Value} tuples for all
11309 other items, or returns false if no tracing is active for
11310 this function.
11311 To get information about an event, PidPortFuncEvent is to be one
11313 of the atoms send or 'receive'.
11314 One valid Item for events exists:
11316 match_spec:
11318 Returns the match specification for this event, if it has
11319 one, or true if no match specification has been set.
11320 The return value is {Item, Value}, where Value is the requested
11322 information as described earlier. If a pid for a dead process
11323 was specified, or the name of a non-existing function, Value is
11324 undefined.
11325 erlang:trace_pattern(MFA, MatchSpec) -> integer() >= 0
11327 Types:
11329 MFA = trace_pattern_mfa() | send | 'receive'
11331 MatchSpec =
11332 (MatchSpecList :: trace_match_spec()) |
11333 boolean() |
11334 restart | pause
11335 trace_pattern_mfa() = {atom(), atom(), arity() | '_'} | on_load
11336 trace_match_spec() =
11337 [{[term()] | '_' | match_variable(), [term()], [term()]}]
11338 match_variable() = atom()
11339 Approximation of '$1' | '$2' | '$3' | ...
11340 The same as erlang:trace_pattern(Event, MatchSpec, []), retained
11342 for backward compatibility.
11343 erlang:trace_pattern(MFA :: send, MatchSpec, FlagList :: []) ->
11345 integer() >= 0
11346 Types:
11348 MatchSpec = (MatchSpecList :: trace_match_spec()) | boolean()
11350 trace_match_spec() =
11351 [{[term()] | '_' | match_variable(), [term()], [term()]}]
11352 match_variable() = atom()
11353 Approximation of '$1' | '$2' | '$3' | ...
11354 Sets trace pattern for message sending. Must be combined with
11356 erlang:trace/3 to set the send trace flag for one or more pro‐
11357 cesses. By default all messages sent from send traced processes
11358 are traced. To limit traced send events based on the message
11359 content, the sender and/or the receiver, use erlang:trace_pat‐
11360 tern/3.
11361 Argument MatchSpec can take the following forms:
11363 MatchSpecList:
11365 A list of match specifications. The matching is done on the
11366 list [Receiver, Msg]. Receiver is the process or port iden‐
11367 tity of the receiver and Msg is the message term. The pid of
11368 the sending process can be accessed with the guard function
11369 self/0. An empty list is the same as true. For more informa‐
11370 tion, see section Match Specifications in Erlang in the
11371 User's Guide.
11372 true:
11374 Enables tracing for all sent messages (from send traced pro‐
11375 cesses). Any match specification is removed. This is the de‐
11376 fault.
11377 false:
11379 Disables tracing for all sent messages. Any match specifica‐
11380 tion is removed.
11381 Argument FlagList must be [] for send tracing.
11383 The return value is always 1.
11385 Examples:
11387 Only trace messages to a specific process Pid:
11389 > erlang:trace_pattern(send, [{[Pid, '_'],[],[]}], []).
11391 1
11392 Only trace messages matching {reply, _}:
11394 > erlang:trace_pattern(send, [{['_', {reply,'_'}],[],[]}], []).
11396 1
11397 Only trace messages sent to the sender itself:
11399 > erlang:trace_pattern(send, [{['$1', '_'],[{'=:=','$1',{self}}],[]}], []).
11401 1
11402 Only trace messages sent to other nodes:
11404 > erlang:trace_pattern(send, [{['$1', '_'],[{'=/=',{node,'$1'},{node}}],[]}], []).
11406 1
11407 Note:
11409 A match specification for send trace can use all guard and body
11410 functions except caller.
11411 Fails by raising an error exception with an error reason of:
11414 badarg:
11416 If an argument is invalid.
11417 system_limit:
11419 If a match specification passed as argument has excessive
11420 nesting which causes scheduler stack exhaustion for the
11421 scheduler that the calling process is executing on. Sched‐
11422 uler stack size can be configured when starting the runtime
11423 system.
11424 erlang:trace_pattern(MFA :: 'receive', MatchSpec, FlagList :: []) ->
11426 integer() >= 0
11427 Types:
11429 MatchSpec = (MatchSpecList :: trace_match_spec()) | boolean()
11431 trace_match_spec() =
11432 [{[term()] | '_' | match_variable(), [term()], [term()]}]
11433 match_variable() = atom()
11434 Approximation of '$1' | '$2' | '$3' | ...
11435 Sets trace pattern for message receiving. Must be combined with
11437 erlang:trace/3 to set the 'receive' trace flag for one or more
11438 processes. By default all messages received by 'receive' traced
11439 processes are traced. To limit traced receive events based on
11440 the message content, the sender and/or the receiver, use er‐
11441 lang:trace_pattern/3.
11442 Argument MatchSpec can take the following forms:
11444 MatchSpecList:
11446 A list of match specifications. The matching is done on the
11447 list [Node, Sender, Msg]. Node is the node name of the
11448 sender. Sender is the process or port identity of the
11449 sender, or the atom undefined if the sender is not known
11450 (which can be the case for remote senders). Msg is the mes‐
11451 sage term. The pid of the receiving process can be accessed
11452 with the guard function self/0. An empty list is the same as
11453 true. For more information, see section Match Specifica‐
11454 tions in Erlang in the User's Guide.
11455 true:
11457 Enables tracing for all received messages (to 'receive'
11458 traced processes). Any match specification is removed. This
11459 is the default.
11460 false:
11462 Disables tracing for all received messages. Any match speci‐
11463 fication is removed.
11464 Argument FlagList must be [] for receive tracing.
11466 The return value is always 1.
11468 Examples:
11470 Only trace messages from a specific process Pid:
11472 > erlang:trace_pattern('receive', [{['_',Pid, '_'],[],[]}], []).
11474 1
11475 Only trace messages matching {reply, _}:
11477 > erlang:trace_pattern('receive', [{['_','_', {reply,'_'}],[],[]}], []).
11479 1
11480 Only trace messages from other nodes:
11482 > erlang:trace_pattern('receive', [{['$1', '_', '_'],[{'=/=','$1',{node}}],[]}], []).
11484 1
11485 Note:
11487 A match specification for 'receive' trace can use all guard and
11488 body functions except caller, is_seq_trace, get_seq_token,
11489 set_seq_token, enable_trace, disable_trace, trace, silent, and
11490 process_dump.
11491 Fails by raising an error exception with an error reason of:
11494 badarg:
11496 If an argument is invalid.
11497 system_limit:
11499 If a match specification passed as argument has excessive
11500 nesting which causes scheduler stack exhaustion for the
11501 scheduler that the calling process is executing on. Sched‐
11502 uler stack size can be configured when starting the runtime
11503 system.
11504 erlang:trace_pattern(MFA, MatchSpec, FlagList) ->
11506 integer() >= 0
11507 Types:
11509 MFA = trace_pattern_mfa()
11511 MatchSpec =
11512 (MatchSpecList :: trace_match_spec()) |
11513 boolean() |
11514 restart | pause
11515 FlagList = [trace_pattern_flag()]
11516 trace_pattern_mfa() = {atom(), atom(), arity() | '_'} | on_load
11517 trace_match_spec() =
11518 [{[term()] | '_' | match_variable(), [term()], [term()]}]
11519 trace_pattern_flag() =
11520 global | local | meta |
11521 {meta, Pid :: pid()} |
11522 {meta, TracerModule :: module(), TracerState :: term()} |
11523 call_count | call_time
11524 match_variable() = atom()
11525 Approximation of '$1' | '$2' | '$3' | ...
11526 Enables or disables call tracing for one or more functions. Must
11528 be combined with erlang:trace/3 to set the call trace flag for
11529 one or more processes.
11530 Conceptually, call tracing works as follows. Inside the Erlang
11532 virtual machine, a set of processes and a set of functions are
11533 to be traced. If a traced process calls a traced function, the
11534 trace action is taken. Otherwise, nothing happens.
11535 To add or remove one or more processes to the set of traced pro‐
11537 cesses, use erlang:trace/3.
11538 To add or remove functions to the set of traced functions, use
11540 erlang:trace_pattern/3.
11541 The BIF erlang:trace_pattern/3 can also add match specifications
11543 to a function. A match specification comprises a pattern that
11544 the function arguments must match, a guard expression that must
11545 evaluate to true, and an action to be performed. The default ac‐
11546 tion is to send a trace message. If the pattern does not match
11547 or the guard fails, the action is not executed.
11548 Argument MFA is to be a tuple, such as {Module, Function, Ar‐
11550 ity}, or the atom on_load (described below). It can be the mod‐
11551 ule, function, and arity for a function (or a BIF in any mod‐
11552 ule). The atom '_' can be used as a wildcard in any of the fol‐
11553 lowing ways:
11554 {Module,Function,'_'}:
11556 All functions of any arity named Function in module Module.
11557 {Module,'_','_'}:
11559 All functions in module Module.
11560 {'_','_','_'}:
11562 All functions in all loaded modules.
11563 Other combinations, such as {Module,'_',Arity}, are not allowed.
11565 Local functions match wildcards only if option local is in
11566 FlagList.
11567 If argument MFA is the atom on_load, the match specification and
11569 flag list are used on all modules that are newly loaded.
11570 Argument MatchSpec can take the following forms:
11572 false:
11574 Disables tracing for the matching functions. Any match spec‐
11575 ification is removed.
11576 true:
11578 Enables tracing for the matching functions. Any match speci‐
11579 fication is removed.
11580 MatchSpecList:
11582 A list of match specifications. An empty list is equivalent
11583 to true. For a description of match specifications, see sec‐
11584 tion Match Specifications in Erlang in the User's Guide.
11585 restart:
11587 For the FlagList options call_count and call_time: restarts
11588 the existing counters. The behavior is undefined for other
11589 FlagList options.
11590 pause:
11592 For the FlagList options call_count and call_time: pauses
11593 the existing counters. The behavior is undefined for other
11594 FlagList options.
11595 Parameter FlagList is a list of options. The following are the
11597 valid options:
11598 global:
11600 Turns on or off call tracing for global function calls (that
11601 is, calls specifying the module explicitly). Only exported
11602 functions match and only global calls generate trace mes‐
11603 sages. This is the default.
11604 local:
11606 Turns on or off call tracing for all types of function
11607 calls. Trace messages are sent whenever any of the specified
11608 functions are called, regardless of how they are called. If
11609 flag return_to is set for the process, a return_to message
11610 is also sent when this function returns to its caller.
11611 meta | {meta, Pid} | {meta, TracerModule, TracerState}:
11613 Turns on or off meta-tracing for all types of function
11614 calls. Trace messages are sent to the tracer whenever any of
11615 the specified functions are called. If no tracer is speci‐
11616 fied, self() is used as a default tracer process.
11617 Meta-tracing traces all processes and does not care about
11619 the process trace flags set by erlang:trace/3, the trace
11620 flags are instead fixed to [call, timestamp].
11621 The match specification function {return_trace} works with
11623 meta-trace and sends its trace message to the same tracer.
11624 call_count:
11626 Starts (MatchSpec == true) or stops (MatchSpec == false)
11627 call count tracing for all types of function calls. For ev‐
11628 ery function, a counter is incremented when the function is
11629 called, in any process. No process trace flags need to be
11630 activated.
11631 If call count tracing is started while already running, the
11633 count is restarted from zero. To pause running counters, use
11634 MatchSpec == pause. Paused and running counters can be
11635 restarted from zero with MatchSpec == restart.
11636 To read the counter value, use erlang:trace_info/2.
11638 call_time:
11640 Starts (MatchSpec == true) or stops (MatchSpec == false)
11641 call time tracing for all types of function calls. For every
11642 function, a counter is incremented when the function is
11643 called. Time spent in the function is accumulated in two
11644 other counters, seconds and microseconds. The counters are
11645 stored for each call traced process.
11646 If call time tracing is started while already running, the
11648 count and time restart from zero. To pause running counters,
11649 use MatchSpec == pause. Paused and running counters can be
11650 restarted from zero with MatchSpec == restart.
11651 To read the counter value, use erlang:trace_info/2.
11653 The options global and local are mutually exclusive, and global
11655 is the default (if no options are specified). The options
11656 call_count and meta perform a kind of local tracing, and cannot
11657 be combined with global. A function can be globally or locally
11658 traced. If global tracing is specified for a set of functions,
11659 then local, meta, call time, and call count tracing for the
11660 matching set of local functions is disabled, and conversely.
11661 When disabling trace, the option must match the type of trace
11663 set on the function. That is, local tracing must be disabled
11664 with option local and global tracing with option global (or no
11665 option), and so on.
11666 Part of a match specification list cannot be changed directly.
11668 If a function has a match specification, it can be replaced with
11669 a new one. To change an existing match specification, use the
11670 BIF erlang:trace_info/2 to retrieve the existing match specifi‐
11671 cation.
11672 Returns the number of functions matching argument MFA. This is
11674 zero if none matched.
11675 Fails by raising an error exception with an error reason of:
11677 badarg:
11679 If an argument is invalid.
11680 system_limit:
11682 If a match specification passed as argument has excessive
11683 nesting which causes scheduler stack exhaustion for the
11684 scheduler that the calling process is executing on. Sched‐
11685 uler stack size can be configured when starting the runtime
11686 system.
11687 trunc(Number) -> integer()
11689 Types:
11691 Number = number()
11693 Truncates the decimals of Number, for example:
11695 > trunc(5.7).
11697 5
11698 > trunc(-5.7).
11700 -5
11701 > trunc(5).
11703 5
11704 > trunc(36028797018963969.0).
11706 36028797018963968
11707 In the last example, trunc(36028797018963969.0) evaluates to
11709 36028797018963968. The reason for this is that the number
11710 36028797018963969.0 cannot be represented exactly as a float
11711 value. Instead, the float literal is represented as
11712 36028797018963968.0, which is the closest number that can be
11713 represented exactly as a float value. See Representation of
11714 Floating Point Numbers for additional information.
11715 Allowed in guard tests.
11717 tuple_size(Tuple) -> integer() >= 0
11719 Types:
11721 Tuple = tuple()
11723 Returns an integer that is the number of elements in Tuple, for
11725 example:
11726 > tuple_size({morni, mulle, bwange}).
11728 3
11729 Allowed in guard tests.
11731 tuple_to_list(Tuple) -> [term()]
11733 Types:
11735 Tuple = tuple()
11737 Returns a list corresponding to Tuple. Tuple can contain any Er‐
11739 lang terms. Example:
11740 > tuple_to_list({share, {'Ericsson_B', 163}}).
11742 [share,{'Ericsson_B',163}]
11743 unalias(Alias) -> boolean()
11745 Types:
11747 Alias = reference()
11749 Deactivate the alias Alias previously created by the calling
11751 process. An alias can for example be created via alias/0, or
11752 monitor/3. unalias/1 will always deactivate the alias regardless
11753 of options used when creating the alias.
11754 Returns true if Alias was a currently active alias for current
11756 processes; otherwise, false.
11757 For more information on process aliases see the Process Aliases
11759 section of the Erlang Reference Manual .
11760 erlang:unique_integer() -> integer()
11762 Generates and returns an integer unique on current runtime sys‐
11764 tem instance. The same as calling erlang:unique_integer([]).
11765 erlang:unique_integer(ModifierList) -> integer()
11767 Types:
11769 ModifierList = [Modifier]
11771 Modifier = positive | monotonic
11772 Generates and returns an integer unique on current runtime sys‐
11774 tem instance. The integer is unique in the sense that this BIF,
11775 using the same set of modifiers, does not return the same inte‐
11776 ger more than once on the current runtime system instance. Each
11777 integer value can of course be constructed by other means.
11778 By default, when [] is passed as ModifierList, both negative and
11780 positive integers can be returned. This to use the range of in‐
11781 tegers that do not need heap memory allocation as much as possi‐
11782 ble. By default the returned integers are also only guaranteed
11783 to be unique, that is, any returned integer can be smaller or
11784 larger than previously returned integers.
11785 Modifiers:
11787 positive:
11789 Returns only positive integers.
11790 Notice that by passing the positive modifier you will get
11792 heap allocated integers (bignums) quicker.
11793 monotonic:
11795 Returns strictly monotonically increasing integers corre‐
11796 sponding to creation time. That is, the integer returned is
11797 always larger than previously returned integers on the cur‐
11798 rent runtime system instance.
11799 These values can be used to determine order between events
11801 on the runtime system instance. That is, if both X = er‐
11802 lang:unique_integer([monotonic]) and Y = erlang:unique_inte‐
11803 ger([monotonic]) are executed by different processes (or the
11804 same process) on the same runtime system instance and X < Y,
11805 we know that X was created before Y.
11806 Warning:
11808 Strictly monotonically increasing values are inherently quite
11809 expensive to generate and scales poorly. This is because the
11810 values need to be synchronized between CPU cores. That is, do
11811 not pass the monotonic modifier unless you really need
11812 strictly monotonically increasing values.
11813 All valid Modifiers can be combined. Repeated (valid) Modifiers
11816 in the ModifierList are ignored.
11817 Note:
11819 The set of integers returned by erlang:unique_integer/1 using
11820 different sets of Modifiers will overlap. For example, by call‐
11821 ing unique_integer([monotonic]), and unique_integer([positive,
11822 monotonic]) repeatedly, you will eventually see some integers
11823 that are returned by both calls.
11824 Failures:
11827 badarg:
11829 if ModifierList is not a proper list.
11830 badarg:
11832 if Modifier is not a valid modifier.
11833 erlang:universaltime() -> DateTime
11835 Types:
11837 DateTime = calendar:datetime()
11839 Returns the current date and time according to Universal Time
11841 Coordinated (UTC) in the form {{Year, Month, Day}, {Hour,
11842 Minute, Second}} if supported by the underlying OS. Otherwise
11843 erlang:universaltime() is equivalent to erlang:localtime(). The
11844 return value is based on the OS System Time. Example:
11845 > erlang:universaltime().
11847 {{1996,11,6},{14,18,43}}
11848 erlang:universaltime_to_localtime(Universaltime) -> Localtime
11850 Types:
11852 Localtime = Universaltime = calendar:datetime()
11854 Converts Universal Time Coordinated (UTC) date and time to local
11856 date and time in the form {{Year, Month, Day}, {Hour, Minute,
11857 Second}} if supported by the underlying OS. Otherwise no conver‐
11858 sion is done, and Universaltime is returned. Example:
11859 > erlang:universaltime_to_localtime({{1996,11,6},{14,18,43}}).
11861 {{1996,11,7},{15,18,43}}
11862 Failure: badarg if Universaltime denotes an invalid date and
11864 time.
11865 unlink(Id) -> true
11867 Types:
11869 Id = pid() | port()
11871 Removes a link between the calling process and another process
11873 or a port identified by Id. We will from here on call the iden‐
11874 tified process or port unlinkee.
11875 A link can be set up using the link/1 BIF. For more information
11877 on links and exit signals due to links, see the Processes chap‐
11878 ter in the Erlang Reference Manual :
11879 * Links
11881 * Sending Exit Signals
11883 * Receiving Exit Signals
11885 Once unlink(Id) has returned, it is guaranteed that the link be‐
11887 tween the caller and the unlinkee has no effect on the caller in
11888 the future (unless the link is setup again). Note that if the
11889 caller is trapping exits, an {'EXIT', Id, ExitReason} message
11890 due to the link may have been placed in the message queue of the
11891 caller before the unlink(Id) call completed. Also note that the
11892 {'EXIT', Id, ExitReason} message may be the result of the link,
11893 but may also be the result of the unlikee sending the caller an
11894 exit signal by calling the exit/2 BIF. Therefore, it may or may
11895 not be appropriate to clean up the message queue after a call to
11896 unlink(Id) as follows, when trapping exits:
11897 unlink(Id),
11899 receive
11900 {'EXIT', Id, _} ->
11901 true
11902 after 0 ->
11903 true
11904 end
11905 The link removal is performed asynchronously. If such a link
11907 does not exist, nothing is done. A detailed description of the
11908 link protocol can be found in the Distribution Protocol chapter
11909 of the ERTS User's Guide .
11910 Failure: badarg if Id does not identify a process or a node lo‐
11912 cal port.
11913 unregister(RegName) -> true
11915 Types:
11917 RegName = atom()
11919 Removes the registered name RegName associated with a process
11921 identifier or a port identifier from the name registry. For ex‐
11922 ample:
11923 > unregister(db).
11925 true
11926 Keep in mind that you can still receive signals associated with
11928 the registered name after it has been unregistered as the sender
11929 may have looked up the name before sending to it.
11930 Users are advised not to unregister system processes.
11932 Failure: badarg if RegName is not a registered name.
11934 whereis(RegName) -> pid() | port() | undefined
11936 Types:
11938 RegName = atom()
11940 Returns the process identifier or port identifier with the reg‐
11942 istered name RegName from the name registry. Returns undefined
11943 if the name is not registered. Example:
11944 > whereis(db).
11946 <0.43.0>
11947 erlang:yield() -> true
11949 Tries to give other processes with the same or higher priority
11951 (if any) a chance to execute before returning. There is no guar‐
11952 antee that any other process runs between the invocation and re‐
11953 turn of erlang:yield/0.
11954 See the documentation for receive-after expressions for how to
11956 make the current process sleep for a specific number of mil‐
11957 liseconds.
11958 Warning:
11960 There is seldom or never any need to use this BIF. Using this
11961 BIF without a thorough grasp of how the scheduler works can
11962 cause performance degradation. The current implementation of
11963 this function puts the current process last in the current
11964 scheduler's queue for processes of the same priority as the cur‐
11965 rent process.
11966Ericsson AB erts 12.3.2.1 erlang(3)