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() = [any()]
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 identifying a distribution channel.
360 nif_resource()
362 An opaque handle identifying 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 {async_dist, Enabled :: boolean()}
375 Options for spawn_opt().
377 priority_level() = low | normal | high | max
379 Process priority level. For more info see process_flag(priority,
381 Level)
382 max_heap_size() =
384 integer() >= 0 |
385 #{size => integer() >= 0,
386 kill => boolean(),
387 error_logger => boolean()}
388 Process max heap size configuration. For more info see
390 process_flag(max_heap_size, MaxHeapSize)
391 message_queue_data() = off_heap | on_heap
393 Process message queue data configuration. For more information,
395 see process_flag(message_queue_data, MQD)
396 stacktrace() =
398 [{module(),
399 atom(),
400 arity() | [term()],
401 [stacktrace_extrainfo()]} |
402 {function(), arity() | [term()], [stacktrace_extrainfo()]}]
403 stacktrace_extrainfo() =
405 {line, integer() >= 1} |
406 {file, unicode:chardata()} |
407 {error_info,
408 #{module => module(), function => atom(), cause => term()}} |
409 {atom(), term()}
410 An Erlang stacktrace as described by Errors and Error Handling
412 section in the Erlang Reference Manual.
413 send_destination() =
415 pid() |
416 reference() |
417 port() |
418 (RegName :: atom()) |
419 {RegName :: atom(), Node :: node()}
420 The destination for a send operation, can be a remote or local
422 process identifier, a (local) port, a reference denoting a
423 process alias, a locally registered name, or a tuple {RegName,
424 Node} for a registered name at another node.
425
427 abs(Float) -> float()
428 abs(Int) -> integer() >= 0
430 Types:
432 Int = integer()
434 Returns an integer or float that is the arithmetical absolute
436 value of Float or Int, for example:
437 > abs(-3.33).
439 3.33
440 > abs(-3).
441 3
442 Allowed in guard tests.
444 erlang:adler32(Data) -> integer() >= 0
446 Types:
448 Data = iodata()
450 Computes and returns the adler32 checksum for Data.
452 erlang:adler32(OldAdler, Data) -> integer() >= 0
454 Types:
456 OldAdler = integer() >= 0
458 Data = iodata()
459 Continues computing the adler32 checksum by combining the previ‐
461 ous checksum, OldAdler, with the checksum of Data.
462 The following code:
464 X = erlang:adler32(Data1),
466 Y = erlang:adler32(X,Data2).
467 assigns the same value to Y as this:
469 Y = erlang:adler32([Data1,Data2]).
471 erlang:adler32_combine(FirstAdler, SecondAdler, SecondSize) ->
473 integer() >= 0
474 Types:
476 FirstAdler = SecondAdler = SecondSize = integer() >= 0
478 Combines two previously computed adler32 checksums. This compu‐
480 tation requires the size of the data object for the second
481 checksum to be known.
482 The following code:
484 Y = erlang:adler32(Data1),
486 Z = erlang:adler32(Y,Data2).
487 assigns the same value to Z as this:
489 X = erlang:adler32(Data1),
491 Y = erlang:adler32(Data2),
492 Z = erlang:adler32_combine(X,Y,iolist_size(Data2)).
493 alias() -> Alias
495 alias(Opts) -> Alias
497 Types:
499 Alias = reference()
501 Opts = [explicit_unalias | reply]
502 Create an alias which can be used when sending messages to the
504 process that created the alias. When the alias has been deacti‐
505 vated, messages sent using the alias will be dropped. An alias
506 can be deactivated using unalias/1. Currently available options
507 for alias/1:
508 explicit_unalias:
510 The alias can only be deactivated via a call to unalias/1.
511 This is also the default behaviour if no options are passed
512 or if alias/0 is called.
513 reply:
515 The alias will be automatically deactivated when a reply
516 message sent via the alias is received. The alias can also
517 still be deactivated via a call to unalias/1.
518 Example:
520 server() ->
522 receive
523 {request, AliasReqId, Request} ->
524 Result = perform_request(Request),
525 AliasReqId ! {reply, AliasReqId, Result}
526 end,
527 server().
528 client(ServerPid, Request) ->
530 AliasReqId = alias([reply]),
531 ServerPid ! {request, AliasReqId, Request},
532 %% Alias will be automatically deactivated if we receive a reply
533 %% since we used the 'reply' option...
534 receive
535 {reply, AliasReqId, Result} -> Result
536 after 5000 ->
537 unalias(AliasReqId),
538 %% Flush message queue in case the reply arrived
539 %% just before the alias was deactivated...
540 receive {reply, AliasReqId, Result} -> Result
541 after 0 -> exit(timeout)
542 end
543 end.
544 Note that both the server and the client in this example must be
547 executing on at least OTP 24 systems in order for this to work.
548 For more information on process aliases see the Process Aliases
550 section of the Erlang Reference Manual .
551 erlang:append_element(Tuple1, Term) -> Tuple2
553 Types:
555 Tuple1 = Tuple2 = tuple()
557 Term = term()
558 Returns a new tuple that has one element more than Tuple1, and
560 contains the elements in Tuple1 followed by Term as the last el‐
561 ement. Semantically equivalent to list_to_tuple(tu‐
562 ple_to_list(Tuple1) ++ [Term]), but much faster. Example:
563 > erlang:append_element({one, two}, three).
565 {one,two,three}
566 apply(Fun, Args) -> term()
568 Types:
570 Fun = function()
572 Args = [term()]
573 Calls a fun, passing the elements in Args as arguments.
575 If the number of elements in the arguments are known at compile
577 time, the call is better written as Fun(Arg1, Arg2, ... ArgN).
578 Warning:
580 Earlier, Fun could also be specified as {Module, Function},
581 equivalent to apply(Module, Function, Args). This use is depre‐
582 cated and will stop working in a future release.
583 apply(Module, Function, Args) -> term()
586 Types:
588 Module = module()
590 Function = atom()
591 Args = [term()]
592 Returns the result of applying Function in Module to Args. The
594 applied function must be exported from Module. The arity of the
595 function is the length of Args. Example:
596 > apply(lists, reverse, [[a, b, c]]).
598 [c,b,a]
599 > apply(erlang, atom_to_list, ['Erlang']).
600 "Erlang"
601 If the number of arguments are known at compile time, the call
603 is better written as Module:Function(Arg1, Arg2, ..., ArgN).
604 Failure: error_handler:undefined_function/3 is called if the ap‐
606 plied function is not exported. The error handler can be rede‐
607 fined (see process_flag/2). If error_handler is undefined, or if
608 the user has redefined the default error_handler so the replace‐
609 ment module is undefined, an error with reason undef is gener‐
610 ated.
611 atom_to_binary(Atom) -> binary()
613 Types:
615 Atom = atom()
617 The same as atom_to_binary(Atom, utf8).
619 atom_to_binary(Atom, Encoding) -> binary()
621 Types:
623 Atom = atom()
625 Encoding = latin1 | unicode | utf8
626 Returns a binary corresponding to the text representation of
628 Atom. If Encoding is latin1, one byte exists for each character
629 in the text representation. If Encoding is utf8 or unicode, the
630 characters are encoded using UTF-8 where characters may require
631 multiple bytes.
632 Note:
634 As from Erlang/OTP 20, atoms can contain any Unicode character
635 and atom_to_binary(Atom, latin1) may fail if the text represen‐
636 tation for Atom contains a Unicode character > 255.
637 Example:
640 > atom_to_binary('Erlang', latin1).
642 <<"Erlang">>
643 atom_to_list(Atom) -> string()
645 Types:
647 Atom = atom()
649 Returns a list of unicode code points corresponding to the text
651 representation of Atom, for example:
652 > atom_to_list('Erlang').
654 "Erlang"
655 > atom_to_list('你好').
657 [20320,22909]
658 See unicode(3) for how to convert the resulting list to differ‐
660 ent formats.
661 binary_part(Subject, PosLen) -> binary()
663 Types:
665 Subject = binary()
667 PosLen = {Start :: integer() >= 0, Length :: integer()}
668 Extracts the part of the binary described by PosLen.
670 Negative length can be used to extract bytes at the end of a bi‐
672 nary, for example:
673 1> Bin = <<1,2,3,4,5,6,7,8,9,10>>.
675 2> binary_part(Bin,{byte_size(Bin), -5}).
676 <<6,7,8,9,10>>
677 Failure: badarg if PosLen in any way references outside the bi‐
679 nary.
680 Start is zero-based, that is:
682 1> Bin = <<1,2,3>>
684 2> binary_part(Bin,{0,2}).
685 <<1,2>>
686 For details about the PosLen semantics, see binary(3).
688 Allowed in guard tests.
690 binary_part(Subject, Start, Length) -> binary()
692 Types:
694 Subject = binary()
696 Start = integer() >= 0
697 Length = integer()
698 The same as binary_part(Subject, {Start, Length}).
700 Allowed in guard tests.
702 binary_to_atom(Binary) -> atom()
704 Types:
706 Binary = binary()
708 The same as binary_to_atom(Binary, utf8).
710 binary_to_atom(Binary, Encoding) -> atom()
712 Types:
714 Binary = binary()
716 Encoding = latin1 | unicode | utf8
717 Returns the atom whose text representation is Binary. If Encod‐
719 ing is utf8 or unicode, the binary must contain valid UTF-8 se‐
720 quences.
721 Note:
723 As from Erlang/OTP 20, binary_to_atom(Binary, utf8) is capable
724 of decoding any Unicode character. Earlier versions would fail
725 if the binary contained Unicode characters > 255.
726 Note:
729 The number of characters that are permitted in an atom name is
730 limited. The default limits can be found in the efficiency
731 guide (section Advanced).
732 Note:
735 There is configurable limit on how many atoms that can exist and
736 atoms are not garbage collected. Therefore, it is recommended to
737 consider whether binary_to_existing_atom/2 is a better option
738 than binary_to_atom/2. The default limits can be found in effi‐
739 ciency guide (section Advanced).
740 Examples:
743 > binary_to_atom(<<"Erlang">>, latin1).
745 > binary_to_atom(<<1024/utf8>>, utf8).
747 binary_to_existing_atom(Binary) -> atom()
749 Types:
751 Binary = binary()
753 The same as binary_to_existing_atom (Binary, utf8).
755 binary_to_existing_atom(Binary, Encoding) -> atom()
757 Types:
759 Binary = binary()
761 Encoding = latin1 | unicode | utf8
762 As binary_to_atom/2, but the atom must exist.
764 The Erlang system has a configurable limit for the total number
766 of atoms that can exist, and atoms are not garbage collected.
767 Therefore, it is not safe to create many atoms from binaries
768 that come from an untrusted source (for example, a file fetched
769 from the Internet), for example, using binary_to_atom/2. This
770 function is thus the appropriate option when the input binary
771 comes from an untrusted source.
772 An atom exists in an Erlang system when included in a loaded Er‐
774 lang module or when created programmatically (for example, by
775 binary_to_atom/2). See the next note for an example of when an
776 atom exists in the source code for an Erlang module but not in
777 the compiled version of the same module.
778 Failure: badarg if the atom does not exist.
780 Note:
782 Note that the compiler may optimize away atoms. For example, the
783 compiler will rewrite atom_to_list(some_atom) to "some_atom". If
784 that expression is the only mention of the atom some_atom in the
785 containing module, the atom will not be created when the module
786 is loaded, and a subsequent call to binary_to_exist‐
787 ing_atom(<<"some_atom">>, utf8) will fail.
788 Note:
791 The number of characters that are permitted in an atom name is
792 limited. The default limits can be found in the efficiency
793 guide (section Advanced).
794 binary_to_float(Binary) -> float()
797 Types:
799 Binary = binary()
801 Returns the float whose text representation is Binary, for exam‐
803 ple:
804 > binary_to_float(<<"2.2017764e+0">>).
806 2.2017764
807 The float string format is the same as the format for Erlang
809 float literals except for that underscores are not permitted.
810 Failure: badarg if Binary contains a bad representation of a
812 float.
813 binary_to_integer(Binary) -> integer()
815 Types:
817 Binary = binary()
819 Returns an integer whose text representation is Binary, for ex‐
821 ample:
822 > binary_to_integer(<<"123">>).
824 123
825 binary_to_integer/1 accepts the same string formats as
827 list_to_integer/1.
828 Failure: badarg if Binary contains a bad representation of an
830 integer.
831 binary_to_integer(Binary, Base) -> integer()
833 Types:
835 Binary = binary()
837 Base = 2..36
838 Returns an integer whose text representation in base Base is Bi‐
840 nary, for example:
841 > binary_to_integer(<<"3FF">>, 16).
843 1023
844 binary_to_integer/2 accepts the same string formats as
846 list_to_integer/2.
847 Failure: badarg if Binary contains a bad representation of an
849 integer.
850 binary_to_list(Binary) -> [byte()]
852 Types:
854 Binary = binary()
856 Returns a list of integers corresponding to the bytes of Binary.
858 binary_to_list(Binary, Start, Stop) -> [byte()]
860 Types:
862 Binary = binary()
864 Start = Stop = integer() >= 1
865 1..byte_size(Binary)
866 As binary_to_list/1, but returns a list of integers correspond‐
868 ing to the bytes from position Start to position Stop in Binary.
869 The positions in the binary are numbered starting from 1.
870 Note:
872 The one-based indexing for binaries used by this function is
873 deprecated. New code is to use binary:bin_to_list/3 in STDLIB
874 instead. All functions in module binary consistently use zero-
875 based indexing.
876 binary_to_term(Binary) -> term()
879 Types:
881 Binary = ext_binary()
883 Returns an Erlang term that is the result of decoding binary ob‐
885 ject Binary, which must be encoded according to the Erlang ex‐
886 ternal term format.
887 > Bin = term_to_binary(hello).
889 <<131,100,0,5,104,101,108,108,111>>
890 > hello = binary_to_term(Bin).
891 hello
892 Warning:
895 When decoding binaries from untrusted sources, the untrusted
896 source may submit data in a way to create resources, such as
897 atoms and remote references, that cannot be garbage collected
898 and lead to Denial of Service attack. In such cases, consider
899 using binary_to_term/2 with the safe option.
900 See also term_to_binary/1 and binary_to_term/2.
903 binary_to_term(Binary, Opts) -> term() | {term(), Used}
905 Types:
907 Binary = ext_binary()
909 Opt = safe | used
910 Opts = [Opt]
911 Used = integer() >= 1
912 As binary_to_term/1, but takes these options:
914 safe:
916 Use this option when receiving binaries from an untrusted
917 source.
918 When enabled, it prevents decoding data that can be used to
920 attack the Erlang runtime. In the event of receiving unsafe
921 data, decoding fails with a badarg error.
922 This prevents creation of new atoms directly, creation of
924 new atoms indirectly (as they are embedded in certain struc‐
925 tures, such as process identifiers, refs, and funs), and
926 creation of new external function references. None of those
927 resources are garbage collected, so unchecked creation of
928 them can exhaust available memory.
929 > binary_to_term(<<131,100,0,5,"hello">>, [safe]).
931 ** exception error: bad argument
932 > hello.
933 hello
934 > binary_to_term(<<131,100,0,5,"hello">>, [safe]).
935 hello
936 Warning:
939 The safe option ensures the data is safely processed by the
940 Erlang runtime but it does not guarantee the data is safe to
941 your application. You must always validate data from untrusted
942 sources. If the binary is stored or transits through untrusted
943 sources, you should also consider cryptographically signing
944 it.
945 used:
948 Changes the return value to {Term, Used} where Used is the
949 number of bytes actually read from Binary.
950 > Input = <<131,100,0,5,"hello","world">>.
952 <<131,100,0,5,104,101,108,108,111,119,111,114,108,100>>
953 > {Term, Used} = binary_to_term(Input, [used]).
954 {hello, 9}
955 > split_binary(Input, Used).
956 {<<131,100,0,5,104,101,108,108,111>>, <<"world">>}
957 Failure: badarg if safe is specified and unsafe data is decoded.
960 See also term_to_binary/1, binary_to_term/1, and list_to_exist‐
962 ing_atom/1.
963 bit_size(Bitstring) -> integer() >= 0
965 Types:
967 Bitstring = bitstring()
969 Returns an integer that is the size in bits of Bitstring, for
971 example:
972 > bit_size(<<433:16,3:3>>).
974 19
975 > bit_size(<<1,2,3>>).
976 24
977 Allowed in guard tests.
979 bitstring_to_list(Bitstring) -> [byte() | bitstring()]
981 Types:
983 Bitstring = bitstring()
985 Returns a list of integers corresponding to the bytes of Bit‐
987 string. If the number of bits in the binary is not divisible by
988 8, the last element of the list is a bitstring containing the
989 remaining 1-7 bits. Examples:
990 > bitstring_to_list(<<433:16>>).
992 [1,177]
993 > bitstring_to_list(<<433:16,3:3>>).
995 [1,177,<<3:3>>]
996 erlang:bump_reductions(Reductions) -> true
998 Types:
1000 Reductions = integer() >= 1
1002 This implementation-dependent function increments the reduction
1004 counter for the calling process. In the Beam emulator, the re‐
1005 duction counter is normally incremented by one for each function
1006 and BIF call. A context switch is forced when the counter
1007 reaches the maximum number of reductions for a process (4000 re‐
1008 ductions in Erlang/OTP 19.2 and later).
1009 Warning:
1011 This BIF can be removed in a future version of the Beam machine
1012 without prior warning. It is unlikely to be implemented in other
1013 Erlang implementations.
1014 byte_size(Bitstring) -> integer() >= 0
1017 Types:
1019 Bitstring = bitstring()
1021 Returns an integer that is the number of bytes needed to contain
1023 Bitstring. That is, if the number of bits in Bitstring is not
1024 divisible by 8, the resulting number of bytes is rounded up. Ex‐
1025 amples:
1026 > byte_size(<<433:16,3:3>>).
1028 3
1029 > byte_size(<<1,2,3>>).
1030 3
1031 Allowed in guard tests.
1033 erlang:cancel_timer(TimerRef) -> Result
1035 Types:
1037 TimerRef = reference()
1039 Time = integer() >= 0
1040 Result = Time | false
1041 Cancels a timer. The same as calling erlang:cancel_timer(Timer‐
1043 Ref, []).
1044 erlang:cancel_timer(TimerRef, Options) -> Result | ok
1046 Types:
1048 TimerRef = reference()
1050 Async = Info = boolean()
1051 Option = {async, Async} | {info, Info}
1052 Options = [Option]
1053 Time = integer() >= 0
1054 Result = Time | false
1055 Cancels a timer that has been created by erlang:start_timer or
1057 erlang:send_after. TimerRef identifies the timer, and was re‐
1058 turned by the BIF that created the timer.
1059 Options:
1061 {async, Async}:
1063 Asynchronous request for cancellation. Async defaults to
1064 false, which causes the cancellation to be performed syn‐
1065 chronously. When Async is set to true, the cancel operation
1066 is performed asynchronously. That is, cancel_timer() sends
1067 an asynchronous request for cancellation to the timer ser‐
1068 vice that manages the timer, and then returns ok.
1069 {info, Info}:
1071 Requests information about the Result of the cancellation.
1072 Info defaults to true, which means the Result is given. When
1073 Info is set to false, no information about the result of the
1074 cancellation is given.
1075 * When Async is false: if Info is true, the Result is re‐
1077 turned by erlang:cancel_timer(). otherwise ok is returned.
1078 * When Async is true: if Info is true, a message on the form
1080 {cancel_timer, TimerRef, Result} is sent to the caller of
1081 erlang:cancel_timer() when the cancellation operation has
1082 been performed, otherwise no message is sent.
1083 More Options may be added in the future.
1085 If Result is an integer, it represents the time in milliseconds
1087 left until the canceled timer would have expired.
1088 If Result is false, a timer corresponding to TimerRef could not
1090 be found. This can be either because the timer had expired, al‐
1091 ready had been canceled, or because TimerRef never corresponded
1092 to a timer. Even if the timer had expired, it does not tell you
1093 if the time-out message has arrived at its destination yet.
1094 Note:
1096 The timer service that manages the timer can be co-located with
1097 another scheduler than the scheduler that the calling process is
1098 executing on. If so, communication with the timer service takes
1099 much longer time than if it is located locally. If the calling
1100 process is in critical path, and can do other things while wait‐
1101 ing for the result of this operation, or is not interested in
1102 the result of the operation, you want to use option {async,
1103 true}. If using option {async, false}, the calling process
1104 blocks until the operation has been performed.
1105 See also erlang:send_after/4, erlang:start_timer/4, and er‐
1108 lang:read_timer/2.
1109 ceil(Number) -> integer()
1111 Types:
1113 Number = number()
1115 Returns the smallest integer not less than Number. For example:
1117 > ceil(5.5).
1119 6
1120 Allowed in guard tests.
1122 check_old_code(Module) -> boolean()
1124 Types:
1126 Module = module()
1128 Returns true if Module has old code, otherwise false.
1130 See also code(3).
1132 check_process_code(Pid, Module) -> CheckResult
1134 Types:
1136 Pid = pid()
1138 Module = module()
1139 CheckResult = boolean()
1140 The same as check_process_code(Pid, Module, []).
1142 check_process_code(Pid, Module, OptionList) -> CheckResult | async
1144 Types:
1146 Pid = pid()
1148 Module = module()
1149 RequestId = term()
1150 Option = {async, RequestId} | {allow_gc, boolean()}
1151 OptionList = [Option]
1152 CheckResult = boolean() | aborted
1153 Checks if the node local process identified by Pid executes old
1155 code for Module.
1156 Options:
1158 {allow_gc, boolean()}:
1160 Determines if garbage collection is allowed when performing
1161 the operation. If {allow_gc, false} is passed, and a garbage
1162 collection is needed to determine the result of the opera‐
1163 tion, the operation is aborted (see information on CheckRe‐
1164 sult below). The default is to allow garbage collection,
1165 that is, {allow_gc, true}.
1166 {async, RequestId}:
1168 The function check_process_code/3 returns the value async
1169 immediately after the request has been sent. When the re‐
1170 quest has been processed, the process that called this func‐
1171 tion is passed a message on the form {check_process_code,
1172 RequestId, CheckResult}.
1173 If Pid equals self(), and no async option has been passed, the
1175 operation is performed at once. Otherwise a request for the op‐
1176 eration is sent to the process identified by Pid, and is handled
1177 when appropriate. If no async option has been passed, the caller
1178 blocks until CheckResult is available and can be returned.
1179 CheckResult informs about the result of the request as follows:
1181 true:
1183 The process identified by Pid executes old code for Module.
1184 That is, the current call of the process executes old code
1185 for this module, or the process has references to old code
1186 for this module, or the process contains funs that refer‐
1187 ences old code for this module.
1188 false:
1190 The process identified by Pid does not execute old code for
1191 Module.
1192 aborted:
1194 The operation was aborted, as the process needed to be
1195 garbage collected to determine the operation result, and the
1196 operation was requested by passing option {allow_gc, false}.
1197 Note:
1199 Up until ERTS version 8.*, the check process code operation
1200 checks for all types of references to the old code. That is, di‐
1201 rect references (e.g. return addresses on the process stack),
1202 indirect references (funs in process context), and references to
1203 literals in the code.
1204 As of ERTS version 9.0, the check process code operation only
1206 checks for direct references to the code. Indirect references
1207 via funs will be ignored. If such funs exist and are used after
1208 a purge of the old code, an exception will be raised upon usage
1209 (same as the case when the fun is received by the process after
1210 the purge). Literals will be taken care of (copied) at a later
1211 stage. This behavior can as of ERTS version 8.1 be enabled when
1212 building OTP, and will automatically be enabled if dirty sched‐
1213 uler support is enabled.
1214 See also code(3).
1217 Failures:
1219 badarg:
1221 If Pid is not a node local process identifier.
1222 badarg:
1224 If Module is not an atom.
1225 badarg:
1227 If OptionList is an invalid list of options.
1228 erlang:convert_time_unit(Time, FromUnit, ToUnit) -> ConvertedTime
1230 Types:
1232 Time = ConvertedTime = integer()
1234 FromUnit = ToUnit = time_unit()
1235 Converts the Time value of time unit FromUnit to the correspond‐
1237 ing ConvertedTime value of time unit ToUnit. The result is
1238 rounded using the floor function.
1239 Warning:
1241 You can lose accuracy and precision when converting between time
1242 units. To minimize such loss, collect all data at native time
1243 unit and do the conversion on the end result.
1244 erlang:crc32(Data) -> integer() >= 0
1247 Types:
1249 Data = iodata()
1251 Computes and returns the crc32 (IEEE 802.3 style) checksum for
1253 Data.
1254 erlang:crc32(OldCrc, Data) -> integer() >= 0
1256 Types:
1258 OldCrc = integer() >= 0
1260 Data = iodata()
1261 Continues computing the crc32 checksum by combining the previous
1263 checksum, OldCrc, with the checksum of Data.
1264 The following code:
1266 X = erlang:crc32(Data1),
1268 Y = erlang:crc32(X,Data2).
1269 assigns the same value to Y as this:
1271 Y = erlang:crc32([Data1,Data2]).
1273 erlang:crc32_combine(FirstCrc, SecondCrc, SecondSize) ->
1275 integer() >= 0
1276 Types:
1278 FirstCrc = SecondCrc = SecondSize = integer() >= 0
1280 Combines two previously computed crc32 checksums. This computa‐
1282 tion requires the size of the data object for the second check‐
1283 sum to be known.
1284 The following code:
1286 Y = erlang:crc32(Data1),
1288 Z = erlang:crc32(Y,Data2).
1289 assigns the same value to Z as this:
1291 X = erlang:crc32(Data1),
1293 Y = erlang:crc32(Data2),
1294 Z = erlang:crc32_combine(X,Y,iolist_size(Data2)).
1295 date() -> Date
1297 Types:
1299 Date = calendar:date()
1301 Returns the current date as {Year, Month, Day}.
1303 The time zone and Daylight Saving Time correction depend on the
1305 underlying OS. The return value is based on the OS System Time.
1306 Example:
1307 > date().
1309 {1995,2,19}
1310 erlang:decode_packet(Type, Bin, Options) ->
1312 {ok, Packet, Rest} |
1313 {more, Length} |
1314 {error, Reason}
1315 Types:
1317 Type =
1319 raw | 0 | 1 | 2 | 4 | asn1 | cdr | sunrm | fcgi | tpkt |
1320 line | http | http_bin | httph | httph_bin
1321 Bin = binary()
1322 Options = [Opt]
1323 Opt =
1324 {packet_size, integer() >= 0} |
1325 {line_length, integer() >= 0}
1326 Packet = binary() | HttpPacket
1327 Rest = binary()
1328 Length = integer() >= 0 | undefined
1329 Reason = term()
1330 HttpPacket =
1331 HttpRequest | HttpResponse | HttpHeader | http_eoh |
1332 HttpError
1333 HttpRequest = {http_request, HttpMethod, HttpUri, HttpVer‐
1334 sion}
1335 HttpResponse =
1336 {http_response, HttpVersion, integer(), HttpString}
1337 HttpHeader =
1338 {http_header,
1339 integer(),
1340 HttpField,
1341 UnmodifiedField :: HttpString,
1342 Value :: HttpString}
1343 HttpError = {http_error, HttpString}
1344 HttpMethod =
1345 'OPTIONS' | 'GET' | 'HEAD' | 'POST' | 'PUT' | 'DELETE' |
1346 'TRACE' | HttpString
1347 HttpUri =
1348 '*' |
1349 {absoluteURI,
1350 http | https,
1351 Host :: HttpString,
1352 Port :: inet:port_number() | undefined,
1353 Path :: HttpString} |
1354 {scheme, Scheme :: HttpString, HttpString} |
1355 {abs_path, HttpString} |
1356 HttpString
1357 HttpVersion =
1358 {Major :: integer() >= 0, Minor :: integer() >= 0}
1359 HttpField =
1360 'Cache-Control' | 'Connection' | 'Date' | 'Pragma' |
1361 'Transfer-Encoding' | 'Upgrade' | 'Via' | 'Accept' |
1362 'Accept-Charset' | 'Accept-Encoding' | 'Accept-Language'
1363 |
1364 'Authorization' | 'From' | 'Host' | 'If-Modified-Since' |
1365 'If-Match' | 'If-None-Match' | 'If-Range' |
1366 'If-Unmodified-Since' | 'Max-Forwards' |
1367 'Proxy-Authorization' | 'Range' | 'Referer' | 'User-
1368 Agent' |
1369 'Age' | 'Location' | 'Proxy-Authenticate' | 'Public' |
1370 'Retry-After' | 'Server' | 'Vary' | 'Warning' |
1371 'Www-Authenticate' | 'Allow' | 'Content-Base' |
1372 'Content-Encoding' | 'Content-Language' | 'Content-
1373 Length' |
1374 'Content-Location' | 'Content-Md5' | 'Content-Range' |
1375 'Content-Type' | 'Etag' | 'Expires' | 'Last-Modified' |
1376 'Accept-Ranges' | 'Set-Cookie' | 'Set-Cookie2' |
1377 'X-Forwarded-For' | 'Cookie' | 'Keep-Alive' |
1378 'Proxy-Connection' | HttpString
1379 HttpString = string() | binary()
1380 Decodes the binary Bin according to the packet protocol speci‐
1382 fied by Type. Similar to the packet handling done by sockets
1383 with option {packet,Type}.
1384 If an entire packet is contained in Bin, it is returned together
1386 with the remainder of the binary as {ok,Packet,Rest}.
1387 If Bin does not contain the entire packet, {more,Length} is re‐
1389 turned. Length is either the expected total size of the packet,
1390 or undefined if the expected packet size is unknown. de‐
1391 code_packet can then be called again with more data added.
1392 If the packet does not conform to the protocol format, {er‐
1394 ror,Reason} is returned.
1395 Types:
1397 raw | 0:
1399 No packet handling is done. The entire binary is returned
1400 unless it is empty.
1401 1 | 2 | 4:
1403 Packets consist of a header specifying the number of bytes
1404 in the packet, followed by that number of bytes. The length
1405 of the header can be one, two, or four bytes; the order of
1406 the bytes is big-endian. The header is stripped off when the
1407 packet is returned.
1408 line:
1410 A packet is a line-terminated by a delimiter byte, default
1411 is the latin-1 newline character. The delimiter byte is in‐
1412 cluded in the returned packet unless the line was truncated
1413 according to option line_length.
1414 asn1 | cdr | sunrm | fcgi | tpkt:
1416 The header is not stripped off.
1417 The meanings of the packet types are as follows:
1419 asn1 - ASN.1 BER:
1421 sunrm - Sun's RPC encoding:
1424 cdr - CORBA (GIOP 1.1):
1427 fcgi - Fast CGI:
1430 tpkt - TPKT format [RFC1006]:
1433 http | httph | http_bin | httph_bin:
1436 The Hypertext Transfer Protocol. The packets are returned
1437 with the format according to HttpPacket described earlier. A
1438 packet is either a request, a response, a header, or an end
1439 of header mark. Invalid lines are returned as HttpError.
1440 Recognized request methods and header fields are returned as
1442 atoms. Others are returned as strings. Strings of unrecog‐
1443 nized header fields are formatted with only capital letters
1444 first and after hyphen characters, for example, "Sec-Web‐
1445 socket-Key". Header field names are also returned in Unmodi‐
1446 fiedField as strings, without any conversion or formatting.
1447 The protocol type http is only to be used for the first line
1449 when an HttpRequest or an HttpResponse is expected. The fol‐
1450 lowing calls are to use httph to get HttpHeaders until
1451 http_eoh is returned, which marks the end of the headers and
1452 the beginning of any following message body.
1453 The variants http_bin and httph_bin return strings (Http‐
1455 String) as binaries instead of lists.
1456 Options:
1458 {packet_size, integer() >= 0}:
1460 Sets the maximum allowed size of the packet body. If the
1461 packet header indicates that the length of the packet is
1462 longer than the maximum allowed length, the packet is con‐
1463 sidered invalid. Defaults to 0, which means no size limit.
1464 {line_length, integer() >= 0}:
1466 For packet type line, lines longer than the indicated length
1467 are truncated.
1468 Option line_length also applies to http* packet types as an
1470 alias for option packet_size if packet_size itself is not
1471 set. This use is only intended for backward compatibility.
1472 {line_delimiter, 0 =< byte() =< 255}:
1474 For packet type line, sets the delimiting byte. Default is
1475 the latin-1 character $\n.
1476 Examples:
1478 > erlang:decode_packet(1,<<3,"abcd">>,[]).
1480 {ok,<<"abc">>,<<"d">>}
1481 > erlang:decode_packet(1,<<5,"abcd">>,[]).
1482 {more,6}
1483 erlang:delete_element(Index, Tuple1) -> Tuple2
1485 Types:
1487 Index = integer() >= 1
1489 1..tuple_size(Tuple1)
1490 Tuple1 = Tuple2 = tuple()
1491 Returns a new tuple with element at Index removed from tuple Tu‐
1493 ple1, for example:
1494 > erlang:delete_element(2, {one, two, three}).
1496 {one,three}
1497 delete_module(Module) -> true | undefined
1499 Types:
1501 Module = module()
1503 Makes the current code for Module become old code and deletes
1505 all references for this module from the export table. Returns
1506 undefined if the module does not exist, otherwise true.
1507 Warning:
1509 This BIF is intended for the code server (see code(3)) and is
1510 not to be used elsewhere.
1511 Failure: badarg if there already is an old version of Module.
1514 demonitor(MonitorRef) -> true
1516 Types:
1518 MonitorRef = reference()
1520 If MonitorRef is a reference that the calling process obtained
1522 by calling monitor/2, this monitoring is turned off. If the mon‐
1523 itoring is already turned off, nothing happens.
1524 Once demonitor(MonitorRef) has returned, it is guaranteed that
1526 no {'DOWN', MonitorRef, _, _, _} message, because of the moni‐
1527 tor, will be placed in the caller message queue in the future.
1528 However, a {'DOWN', MonitorRef, _, _, _} message can have been
1529 placed in the caller message queue before the call. It is there‐
1530 fore usually advisable to remove such a 'DOWN' message from the
1531 message queue after monitoring has been stopped. demonitor(Moni‐
1532 torRef, [flush]) can be used instead of demonitor(MonitorRef) if
1533 this cleanup is wanted.
1534 Note:
1536 Before Erlang/OTP R11B (ERTS 5.5) demonitor/1 behaved completely
1537 asynchronously, that is, the monitor was active until the "de‐
1538 monitor signal" reached the monitored entity. This had one unde‐
1539 sirable effect. You could never know when you were guaranteed
1540 not to receive a DOWN message because of the monitor.
1541 The current behavior can be viewed as two combined operations:
1543 asynchronously send a "demonitor signal" to the monitored entity
1544 and ignore any future results of the monitor.
1545 Failure: It is an error if MonitorRef refers to a monitoring
1548 started by another process. Not all such cases are cheap to
1549 check. If checking is cheap, the call fails with badarg, for ex‐
1550 ample if MonitorRef is a remote reference.
1551 demonitor(MonitorRef, OptionList) -> boolean()
1553 Types:
1555 MonitorRef = reference()
1557 OptionList = [Option]
1558 Option = flush | info
1559 The returned value is true unless info is part of OptionList.
1561 demonitor(MonitorRef, []) is equivalent to demonitor(Monitor‐
1563 Ref).
1564 Options:
1566 flush:
1568 Removes (one) {_, MonitorRef, _, _, _} message, if there is
1569 one, from the caller message queue after monitoring has been
1570 stopped.
1571 Calling demonitor(MonitorRef, [flush]) is equivalent to the
1573 following, but more efficient:
1574 demonitor(MonitorRef),
1576 receive
1577 {_, MonitorRef, _, _, _} ->
1578 true
1579 after 0 ->
1580 true
1581 end
1582 info:
1584 The returned value is one of the following:
1585 true:
1587 The monitor was found and removed. In this case, no 'DOWN'
1588 message corresponding to this monitor has been delivered
1589 and will not be delivered.
1590 false:
1592 The monitor was not found and could not be removed. This
1593 probably because someone already has placed a 'DOWN' mes‐
1594 sage corresponding to this monitor in the caller message
1595 queue.
1596 If option info is combined with option flush, false is re‐
1598 turned if a flush was needed, otherwise true.
1599 Note:
1601 More options can be added in a future release.
1602 Failures:
1605 badarg:
1607 If OptionList is not a list.
1608 badarg:
1610 If Option is an invalid option.
1611 badarg:
1613 The same failure as for demonitor/1.
1614 disconnect_node(Node) -> boolean() | ignored
1616 Types:
1618 Node = node()
1620 Forces the disconnection of a node. This appears to the node
1622 Node as if the local node has crashed. This BIF is mainly used
1623 in the Erlang network authentication protocols.
1624 Returns true if disconnection succeeds, otherwise false. If the
1626 local node is not alive, ignored is returned.
1627 Note:
1629 This function may return before nodedown messages have been de‐
1630 livered.
1631 erlang:display(Term) -> true
1634 Types:
1636 Term = term()
1638 Prints a text representation of Term on the standard output.
1640 Warning:
1642 This BIF is intended for debugging only. The printed representa‐
1643 tion may contain internal details that do not match the high-
1644 level representation of the term in Erlang.
1645 erlang:dist_ctrl_get_data(DHandle) -> {Size, Data} | Data | none
1648 Types:
1650 Size = integer() >= 0
1652 DHandle = dist_handle()
1653 Data = iovec()
1654 Get distribution channel data from the local node that is to be
1656 passed to the remote node. The distribution channel is identi‐
1657 fied by DHandle. If no data is available, the atom none is re‐
1658 turned. One can request to be informed by a message when more
1659 data is available by calling erlang:dist_ctrl_get_data_notifica‐
1660 tion(DHandle).
1661 The returned value when there are data available depends on the
1663 value of the get_size option configured on the distribution
1664 channel identified by DHandle. For more information see the doc‐
1665 umentation of the get_size option for the er‐
1666 lang:dist_ctrl_set_opt/3 function.
1667 Note:
1669 Only the process registered as distribution controller for the
1670 distribution channel identified by DHandle is allowed to call
1671 this function.
1672 This function is used when implementing an alternative distribu‐
1675 tion carrier using processes as distribution controllers. DHan‐
1676 dle is retrieved via the callback f_handshake_complete. More in‐
1677 formation can be found in the documentation of ERTS User's Guide
1678 ➜ How to implement an Alternative Carrier for the Erlang Distri‐
1679 bution ➜ Distribution Module.
1680 erlang:dist_ctrl_get_opt(DHandle, Opt :: get_size) -> Value
1682 Types:
1684 DHandle = dist_handle()
1686 Value = boolean()
1687 Returns the value of the get_size option on the distribution
1689 channel identified by DHandle. For more information see the doc‐
1690 umentation of the get_size option for the er‐
1691 lang:dist_ctrl_set_opt/3 function.
1692 Note:
1694 Only the process registered as distribution controller for the
1695 distribution channel identified by DHandle is allowed to call
1696 this function.
1697 This function is used when implementing an alternative distribu‐
1700 tion carrier using processes as distribution controllers. DHan‐
1701 dle is retrieved via the callback f_handshake_complete. More in‐
1702 formation can be found in the documentation of ERTS User's Guide
1703 ➜ How to implement an Alternative Carrier for the Erlang Distri‐
1704 bution ➜ Distribution Module.
1705 erlang:dist_ctrl_get_data_notification(DHandle) -> ok
1707 Types:
1709 DHandle = dist_handle()
1711 Request notification when more data is available to fetch using
1713 erlang:dist_ctrl_get_data(DHandle) for the distribution channel
1714 identified by DHandle. When more data is present, the caller
1715 will be sent the message dist_data. Once a dist_data messages
1716 has been sent, no more dist_data messages will be sent until the
1717 dist_ctrl_get_data_notification/1 function has been called
1718 again.
1719 Note:
1721 Only the process registered as distribution controller for the
1722 distribution channel identified by DHandle is allowed to call
1723 this function.
1724 This function is used when implementing an alternative distribu‐
1727 tion carrier using processes as distribution controllers. DHan‐
1728 dle is retrieved via the callback f_handshake_complete. More in‐
1729 formation can be found in the documentation of ERTS User's Guide
1730 ➜ How to implement an Alternative Carrier for the Erlang Distri‐
1731 bution ➜ Distribution Module.
1732 erlang:dist_ctrl_input_handler(DHandle, InputHandler) -> ok
1734 Types:
1736 DHandle = dist_handle()
1738 InputHandler = pid()
1739 Register an alternate input handler process for the distribution
1741 channel identified by DHandle. Once this function has been
1742 called, InputHandler is the only process allowed to call er‐
1743 lang:dist_ctrl_put_data(DHandle, Data) with the DHandle identi‐
1744 fying this distribution channel.
1745 Note:
1747 Only the process registered as distribution controller for the
1748 distribution channel identified by DHandle is allowed to call
1749 this function.
1750 This function is used when implementing an alternative distribu‐
1753 tion carrier using processes as distribution controllers. DHan‐
1754 dle is retrieved via the callback f_handshake_complete. More in‐
1755 formation can be found in the documentation of ERTS User's Guide
1756 ➜ How to implement an Alternative Carrier for the Erlang Distri‐
1757 bution ➜ Distribution Module.
1758 erlang:dist_ctrl_put_data(DHandle, Data) -> ok
1760 Types:
1762 DHandle = dist_handle()
1764 Data = iodata()
1765 Deliver distribution channel data from a remote node to the lo‐
1767 cal node.
1768 Note:
1770 Only the process registered as distribution controller for the
1771 distribution channel identified by DHandle is allowed to call
1772 this function unless an alternate input handler process has been
1773 registered using erlang:dist_ctrl_input_handler(DHandle, In‐
1774 putHandler). If an alternate input handler has been registered,
1775 only the registered input handler process is allowed to call
1776 this function.
1777 This function is used when implementing an alternative distribu‐
1780 tion carrier using processes as distribution controllers. DHan‐
1781 dle is retrieved via the callback f_handshake_complete. More in‐
1782 formation can be found in the documentation of ERTS User's Guide
1783 ➜ How to implement an Alternative Carrier for the Erlang Distri‐
1784 bution ➜ Distribution Module.
1785 erlang:dist_ctrl_set_opt(DHandle, Opt :: get_size, Value) ->
1787 OldValue
1788 Types:
1790 DHandle = dist_handle()
1792 Value = OldValue = boolean()
1793 Sets the value of the get_size option on the distribution chan‐
1795 nel identified by DHandle. This option controls the return value
1796 of calls to erlang:dist_ctrl_get_data(DHandle) where DHandle
1797 equals DHandle used when setting this option. When the get_size
1798 option is:
1799 false:
1801 and there are distribution data available, a call to er‐
1802 lang:dist_ctrl_get_data(DHandle) will just return Data to
1803 pass over the channel. This is the default value of the
1804 get_size option.
1805 true:
1807 and there are distribution data available, a call to er‐
1808 lang:dist_ctrl_get_data(DHandle) will return Data to pass
1809 over the channel as well as the Size of Data in bytes. This
1810 is returned as a tuple on the form {Size, Data}.
1811 All options are set to default when a channel is closed.
1813 Note:
1815 Only the process registered as distribution controller for the
1816 distribution channel identified by DHandle is allowed to call
1817 this function.
1818 This function is used when implementing an alternative distribu‐
1821 tion carrier using processes as distribution controllers. DHan‐
1822 dle is retrieved via the callback f_handshake_complete. More in‐
1823 formation can be found in the documentation of ERTS User's Guide
1824 ➜ How to implement an Alternative Carrier for the Erlang Distri‐
1825 bution ➜ Distribution Module.
1826 element(N, Tuple) -> term()
1828 Types:
1830 N = integer() >= 1
1832 1..tuple_size(Tuple)
1833 Tuple = tuple()
1834 Returns the Nth element (numbering from 1) of Tuple, for exam‐
1836 ple:
1837 > element(2, {a, b, c}).
1839 b
1840 Allowed in guard tests.
1842 erase() -> [{Key, Val}]
1844 Types:
1846 Key = Val = term()
1848 Returns the process dictionary and deletes it, for example:
1850 > put(key1, {1, 2, 3}),
1852 put(key2, [a, b, c]),
1853 erase().
1854 [{key1,{1,2,3}},{key2,[a,b,c]}]
1855 erase(Key) -> Val | undefined
1857 Types:
1859 Key = Val = term()
1861 Returns the value Val associated with Key and deletes it from
1863 the process dictionary. Returns undefined if no value is associ‐
1864 ated with Key. The average time complexity for the current im‐
1865 plementation of this function is O(1) and the worst case time
1866 complexity is O(N), where N is the number of items in the
1867 process dictionary. Example:
1868 > put(key1, {merry, lambs, are, playing}),
1870 X = erase(key1),
1871 {X, erase(key1)}.
1872 {{merry,lambs,are,playing},undefined}
1873 error(Reason) -> no_return()
1875 Types:
1877 Reason = term()
1879 Raises an exception of class error with the reason Reason. As
1881 evaluating this function causes an exception to be thrown, it
1882 has no return value.
1883 The intent of the exception class error is to signal that an un‐
1885 expected error has happened (for example, a function is called
1886 with a parameter that has an incorrect type). See the guide
1887 about errors and error handling for additional information. Ex‐
1888 ample:
1889 > catch error(foobar).
1891 {'EXIT',{foobar,[{shell,apply_fun,3,
1892 [{file,"shell.erl"},{line,906}]},
1893 {erl_eval,do_apply,6,[{file,"erl_eval.erl"},{line,677}]},
1894 {erl_eval,expr,5,[{file,"erl_eval.erl"},{line,430}]},
1895 {shell,exprs,7,[{file,"shell.erl"},{line,687}]},
1896 {shell,eval_exprs,7,[{file,"shell.erl"},{line,642}]},
1897 {shell,eval_loop,3,[{file,"shell.erl"},{line,627}]}]}}
1898 error(Reason, Args) -> no_return()
1901 Types:
1903 Reason = term()
1905 Args = [term()] | none
1906 Raises an exception of class error with the reason Reason. Args
1908 is expected to be the list of arguments for the current function
1909 or the atom none. If it is a list, it is used to provide the ar‐
1910 guments for the current function in the stack back-trace. If it
1911 is none, the arity of the calling function is used in the stack‐
1912 trace. As evaluating this function causes an exception to be
1913 raised, it has no return value.
1914 The intent of the exception class error is to signal that an un‐
1916 expected error has happened (for example, a function is called
1917 with a parameter that has an incorrect type). See the guide
1918 about errors and error handling for additional information. Ex‐
1919 ample:
1920 test.erl:
1922 -module(test).
1924 -export([example_fun/2]).
1925 example_fun(A1, A2) ->
1927 erlang:error(my_error, [A1, A2]).
1928 Erlang shell:
1931 6> c(test).
1933 {ok,test}
1934 7> test:example_fun(arg1,"this is the second argument").
1935 ** exception error: my_error
1936 in function test:example_fun/2
1937 called as test:example_fun(arg1,"this is the second argument")
1938 error(Reason, Args, Options) -> no_return()
1941 Types:
1943 Reason = term()
1945 Args = [term()] | none
1946 Options = [Option]
1947 Option = {error_info, ErrorInfoMap}
1948 ErrorInfoMap =
1949 #{cause => term(), module => module(), function =>
1950 atom()}
1951 Raises an exception of class error with the reason Reason. Args
1953 is expected to be the list of arguments for the current function
1954 or the atom none. If it is a list, it is used to provide the ar‐
1955 guments for the current function in the stack back-trace. If it
1956 is none, the arity of the calling function is used in the stack‐
1957 trace. As evaluating this function causes an exception to be
1958 raised, it has no return value.
1959 If the error_info option is given, the ErrorInfoMap will be in‐
1961 serted into the stacktrace. The information given in the Error‐
1962 InfoMap is to be used by error formatters such as erl_error to
1963 provide more context around an error.
1964 The default module of the ErrorInfoMap is the module that the
1966 call to error/3 is made. The default function is format_error.
1967 See format_error/2 for more details on how this Module:Func‐
1968 tion/2 is to be used
1969 The intent of the exception class error is to signal that an un‐
1971 expected error has happened (for example, a function is called
1972 with a parameter that has an incorrect type). See the guide
1973 about errors and error handling for additional information.
1974 exit(Reason) -> no_return()
1976 Types:
1978 Reason = term()
1980 Raises an exception of class exit with exit reason Reason. As
1982 evaluating this function causes an exception to be raised, it
1983 has no return value.
1984 The intent of the exception class exit is that the current
1986 process should be stopped (for example when a message telling a
1987 process to stop is received).
1988 This function differ from error/1,2,3 by causing an exception of
1990 a different class and by having a reason that does not include
1991 the list of functions from the call stack.
1992 See the guide about errors and error handling for additional in‐
1994 formation.
1995 Example:
1997 > exit(foobar).
1999 ** exception exit: foobar
2000 > catch exit(foobar).
2001 {'EXIT',foobar}
2002 Note:
2004 If a process calls exit(kill) and does not catch the exception,
2005 it will terminate with exit reason kill and also emit exit sig‐
2006 nals with exit reason kill (not killed) to all linked processes.
2007 Such exit signals with exit reason kill can be trapped by the
2008 linked processes. Note that this means that signals with exit
2009 reason kill behave differently depending on how they are sent
2010 because the signal will be untrappable if a process sends such a
2011 signal to another process with erlang:exit/2.
2012 exit(Pid, Reason) -> true
2015 Types:
2017 Pid = pid() | port()
2019 Reason = term()
2020 Sends an exit signal with exit reason Reason to the process or
2022 port identified by Pid.
2023 The following behavior applies if Reason is any term, except
2025 normal or kill, and P is the process or port identified by Pid:
2026 * If P is not trapping exits, P exits with exit reason Reason.
2028 * If P is trapping exits, the exit signal is transformed into
2030 a message {'EXIT', From, Reason}, where From is the process
2031 identifier of the process that sent the exit signal, and de‐
2032 livered to the message queue of P.
2033 The following behavior applies if Reason is the term normal and
2035 Pid is the identifier of a process P which is not the same as
2036 the process that invoked erlang:exit(Pid, normal) (the behavior
2037 when a process sends a signal with the normal reason to itself
2038 is described in the warning):
2039 * If P is trapping exits, the exit signal is transformed into
2041 a message {'EXIT', From, normal}, where From is the process
2042 identifier of the process that sent the exit signal, and de‐
2043 livered to P's message queue.
2044 * The signal has no effect if P is not trapping exits.
2046 If Reason is the atom kill, that is, if exit(Pid, kill) is
2048 called, an untrappable exit signal is sent to the process that
2049 is identified by Pid, which unconditionally exits with exit rea‐
2050 son killed. The exit reason is changed from kill to killed to
2051 hint to linked processes that the killed process got killed by a
2052 call to exit(Pid, kill).
2053 Note:
2055 The functions erlang:exit/1 and erlang:exit/2 are named simi‐
2056 larly but provide very different functionalities. The er‐
2057 lang:exit/1 function should be used when the intent is to stop
2058 the current process while erlang:exit/2 should be used when the
2059 intent is to send an exit signal to another process. Note also
2060 that erlang:exit/1 raises an exception that can be caught while
2061 erlang:exit/2 does not cause any exception to be raised.
2062 Warning:
2065 The only scenario that has not been covered by the description
2066 above is when a process P sends an exit signal with reason nor‐
2067 mal to itself, that is erlang:exit(self(), normal). The behavior
2068 in this scenario is as follows:
2069 * If P is trapping exits, the exit signal is transformed into
2071 a message {'EXIT', From, normal}, where From is P's process
2072 identifier, and delivered to P's message queue.
2073 * P exits with reason normal if P is not trapping exits.
2075 Note that the behavior described above is different from when a
2077 process sends an exit signal with reason normal to another
2078 process. This is arguably strange but this behavior is kept for
2079 backward compatibility reasons.
2080 erlang:external_size(Term) -> integer() >= 0
2083 Types:
2085 Term = term()
2087 Calculates, without doing the encoding, the maximum byte size
2089 for a term encoded in the Erlang external term format. The fol‐
2090 lowing condition applies always:
2091 > Size1 = byte_size(term_to_binary(Term)),
2093 > Size2 = erlang:external_size(Term),
2094 > true = Size1 =< Size2.
2095 true
2096 This is equivalent to a call to:
2098 erlang:external_size(Term, [])
2100 erlang:external_size(Term, Options) -> integer() >= 0
2102 Types:
2104 Term = term()
2106 Options = [{minor_version, Version :: integer() >= 0}]
2107 Calculates, without doing the encoding, the maximum byte size
2109 for a term encoded in the Erlang external term format. The fol‐
2110 lowing condition applies always:
2111 > Size1 = byte_size(term_to_binary(Term, Options)),
2113 > Size2 = erlang:external_size(Term, Options),
2114 > true = Size1 =< Size2.
2115 true
2116 Option {minor_version, Version} specifies how floats are en‐
2118 coded. For a detailed description, see term_to_binary/2.
2119 float(Number) -> float()
2121 Types:
2123 Number = number()
2125 Returns a float by converting Number to a float, for example:
2127 > float(55).
2129 55.0
2130 Allowed in guard tests.
2132 Note:
2134 If used on the top level in a guard, it tests whether the argu‐
2135 ment is a floating point number; for clarity, use is_float/1 in‐
2136 stead.
2137 When float/1 is used in an expression in a guard, such as
2139 'float(A) == 4.0', it converts a number as described earlier.
2140 float_to_binary(Float) -> binary()
2143 Types:
2145 Float = float()
2147 The same as float_to_binary(Float,[{scientific,20}]).
2149 float_to_binary(Float, Options) -> binary()
2151 Types:
2153 Float = float()
2155 Options = [Option]
2156 Option =
2157 {decimals, Decimals :: 0..253} |
2158 {scientific, Decimals :: 0..249} |
2159 compact | short
2160 Returns a binary corresponding to the text representation of
2162 Float using fixed decimal point formatting. Options behaves in
2163 the same way as float_to_list/2. Examples:
2164 > float_to_binary(7.12, [{decimals, 4}]).
2166 <<"7.1200">>
2167 > float_to_binary(7.12, [{decimals, 4}, compact]).
2168 <<"7.12">>
2169 > float_to_binary(7.12, [{scientific, 3}]).
2170 <<"7.120e+00">>
2171 > float_to_binary(7.12, [short]).
2172 <<"7.12">>
2173 > float_to_binary(0.1+0.2, [short]).
2174 <<"0.30000000000000004">>
2175 > float_to_binary(0.1+0.2)
2176 <<"3.00000000000000044409e-01">>
2177 float_to_list(Float) -> string()
2180 Types:
2182 Float = float()
2184 The same as float_to_list(Float,[{scientific,20}]).
2186 float_to_list(Float, Options) -> string()
2188 Types:
2190 Float = float()
2192 Options = [Option]
2193 Option =
2194 {decimals, Decimals :: 0..253} |
2195 {scientific, Decimals :: 0..249} |
2196 compact | short
2197 Returns a string corresponding to the text representation of
2199 Float using fixed decimal point formatting.
2200 Available options:
2202 * If option decimals is specified, the returned value contains
2204 at most Decimals number of digits past the decimal point. If
2205 the number does not fit in the internal static buffer of 256
2206 bytes, the function throws badarg.
2207 * If option compact is specified, the trailing zeros at the
2209 end of the list are truncated. This option is only meaning‐
2210 ful together with option decimals.
2211 * If option scientific is specified, the float is formatted
2213 using scientific notation with Decimals digits of precision.
2214 * If option short is specified, the float is formatted with
2216 the smallest number of digits that still guarantees that F
2217 =:= list_to_float(float_to_list(F, [short])). When the float
2218 is inside the range (-2⁵³, 2⁵³), the notation that yields
2219 the smallest number of characters is used (scientific nota‐
2220 tion or normal decimal notation). Floats outside the range
2221 (-2⁵³, 2⁵³) are always formatted using scientific notation
2222 to avoid confusing results when doing arithmetic operations.
2223 * If Options is [], the function behaves as float_to_list/1.
2225 Examples:
2227 > float_to_list(7.12, [{decimals, 4}]).
2229 "7.1200"
2230 > float_to_list(7.12, [{decimals, 4}, compact]).
2231 "7.12"
2232 > float_to_list(7.12, [{scientific, 3}]).
2233 "7.120e+00"
2234 > float_to_list(7.12, [short]).
2235 "7.12"
2236 > float_to_list(0.1+0.2, [short]).
2237 "0.30000000000000004"
2238 > float_to_list(0.1+0.2)
2239 "3.00000000000000044409e-01"
2240 In the last example, float_to_list(0.1+0.2) evaluates to
2243 "3.00000000000000044409e-01". The reason for this is explained
2244 in Representation of Floating Point Numbers.
2245 floor(Number) -> integer()
2247 Types:
2249 Number = number()
2251 Returns the largest integer not greater than Number. For exam‐
2253 ple:
2254 > floor(-10.5).
2256 -11
2257 Allowed in guard tests.
2259 erlang:fun_info(Fun) -> [{Item, Info}]
2261 Types:
2263 Fun = function()
2265 Item =
2266 arity | env | index | name | module | new_index |
2267 new_uniq |
2268 pid | type | uniq
2269 Info = term()
2270 Returns a list with information about the fun Fun. Each list el‐
2272 ement is a tuple. The order of the tuples is undefined, and more
2273 tuples can be added in a future release.
2274 Warning:
2276 This BIF is mainly intended for debugging, but it can sometimes
2277 be useful in library functions that need to verify, for example,
2278 the arity of a fun.
2279 Two types of funs have slightly different semantics:
2282 * A fun created by fun M:F/A is called an external fun. Call‐
2284 ing it will always call the function F with arity A in the
2285 latest code for module M. Notice that module M does not even
2286 need to be loaded when the fun fun M:F/A is created.
2287 * All other funs are called local. When a local fun is called,
2289 the same version of the code that created the fun is called
2290 (even if a newer version of the module has been loaded).
2291 The following elements are always present in the list for both
2293 local and external funs:
2294 {type, Type}:
2296 Type is local or external.
2297 {module, Module}:
2299 Module (an atom) is the module name.
2300 If Fun is a local fun, Module is the module in which the fun
2302 is defined.
2303 If Fun is an external fun, Module is the module that the fun
2305 refers to.
2306 {name, Name}:
2308 Name (an atom) is a function name.
2309 If Fun is a local fun, Name is the name of the local func‐
2311 tion that implements the fun. (This name was generated by
2312 the compiler, and is only of informational use. As it is a
2313 local function, it cannot be called directly.) If no code is
2314 currently loaded for the fun, [] is returned instead of an
2315 atom.
2316 If Fun is an external fun, Name is the name of the exported
2318 function that the fun refers to.
2319 {arity, Arity}:
2321 Arity is the number of arguments that the fun is to be
2322 called with.
2323 {env, Env}:
2325 Env (a list) is the environment or free variables for the
2326 fun. For external funs, the returned list is always empty.
2327 The following elements are only present in the list if Fun is
2329 local:
2330 {pid, Pid}:
2332 Pid is the process identifier of the process that originally
2333 created the fun.
2334 It might point to the init process if the Fun was statically
2336 allocated when module was loaded (this optimisation is per‐
2337 formed for local functions that do not capture the environ‐
2338 ment).
2339 {index, Index}:
2341 Index (an integer) is an index into the module fun table.
2342 {new_index, Index}:
2344 Index (an integer) is an index into the module fun table.
2345 {new_uniq, Uniq}:
2347 Uniq (a binary) is a unique value for this fun. It is calcu‐
2348 lated from the compiled code for the entire module.
2349 {uniq, Uniq}:
2351 Uniq (an integer) is a unique value for this fun. As from
2352 Erlang/OTP R15, this integer is calculated from the compiled
2353 code for the entire module. Before Erlang/OTP R15, this in‐
2354 teger was based on only the body of the fun.
2355 erlang:fun_info(Fun, Item) -> {Item, Info}
2357 Types:
2359 Fun = function()
2361 Item = fun_info_item()
2362 Info = term()
2363 fun_info_item() =
2364 arity | env | index | name | module | new_index | new_uniq |
2365 pid | type | uniq
2366 Returns information about Fun as specified by Item, in the form
2368 {Item,Info}.
2369 For any fun, Item can be any of the atoms module, name, arity,
2371 env, or type.
2372 For a local fun, Item can also be any of the atoms index,
2374 new_index, new_uniq, uniq, and pid. For an external fun, the
2375 value of any of these items is always the atom undefined.
2376 See erlang:fun_info/1.
2378 erlang:fun_to_list(Fun) -> String :: string()
2380 Types:
2382 Fun = function()
2384 Returns String that represents the code that created Fun.
2386 String has the following form, if Fun was created by a fun ex‐
2388 pression of the form fun ModuleName:FuncName/Arity:
2389 "fun ModuleName:FuncName/Arity"
2391 The form of String when Fun is created from other types of fun
2393 expressions differs depending on if the fun expression was exe‐
2394 cuted while executing compiled code or if the fun expression was
2395 executed while executing uncompiled code (uncompiled escripts,
2396 the Erlang shell, and other code executed by the erl_eval mod‐
2397 ule):
2398 compiled code:
2400 "#Fun<M.I.U>", where M, I and U correspond to the values
2401 named module, index and uniq in the result of er‐
2402 lang:fun_info(Fun).
2403 uncompiled code:
2405 All funs created from fun expressions in uncompiled code
2406 with the same arity are mapped to the same list by
2407 fun_to_list/1.
2408 Note:
2410 Generally, one can not use fun_to_list/1 to check if two funs
2411 are equal as fun_to_list/1 does not take the fun's environment
2412 into account. See erlang:fun_info/1 for how to get the environ‐
2413 ment of a fun.
2414 Note:
2417 The output of fun_to_list/1 can differ between Erlang implemen‐
2418 tations and may change in future versions.
2419 Examples:
2422 -module(test).
2424 -export([add/1, add2/0, fun_tuple/0]).
2425 add(A) -> fun(B) -> A + B end.
2426 add2() -> fun add/1.
2427 fun_tuple() -> {fun() -> 1 end, fun() -> 1 end}.
2428 > {fun test:add/1, test:add2()}.
2431 {fun test:add/1,#Fun<test.1.107738983>}
2432 Explanation: fun test:add/1 is upgradable but test:add2() is not
2435 upgradable.
2436 > {test:add(1), test:add(42)}.
2438 {#Fun<test.0.107738983>,#Fun<test.0.107738983>}
2439 Explanation: test:add(1) and test:add(42) has the same string
2442 representation as the environment is not taken into account.
2443 >test:fun_tuple().
2445 {#Fun<test.2.107738983>,#Fun<test.3.107738983>}
2446 Explanation: The string representations differ because the funs
2449 come from different fun expressions.
2450 > {fun() -> 1 end, fun() -> 1 end}. >
2452 {#Fun<erl_eval.45.97283095>,#Fun<erl_eval.45.97283095>}
2453 Explanation: All funs created from fun expressions of this form
2456 in uncompiled code with the same arity are mapped to the same
2457 list by fun_to_list/1.
2458 erlang:function_exported(Module, Function, Arity) -> boolean()
2460 Types:
2462 Module = module()
2464 Function = atom()
2465 Arity = arity()
2466 Returns true if the module Module is current and contains an ex‐
2468 ported function Function/Arity, or if there is a BIF (a built-in
2469 function implemented in C) with the specified name, otherwise
2470 returns false.
2471 garbage_collect() -> true
2473 Forces an immediate garbage collection of the executing process.
2475 The function is not to be used unless it has been noticed (or
2476 there are good reasons to suspect) that the spontaneous garbage
2477 collection will occur too late or not at all.
2478 Warning:
2480 Improper use can seriously degrade system performance.
2481 garbage_collect(Pid) -> GCResult
2484 Types:
2486 Pid = pid()
2488 GCResult = boolean()
2489 The same as garbage_collect(Pid, []).
2491 garbage_collect(Pid, OptionList) -> GCResult | async
2493 Types:
2495 Pid = pid()
2497 RequestId = term()
2498 Option = {async, RequestId} | {type, major | minor}
2499 OptionList = [Option]
2500 GCResult = boolean()
2501 Garbage collects the node local process identified by Pid.
2503 Option:
2505 {async, RequestId}:
2507 The function garbage_collect/2 returns the value async imme‐
2508 diately after the request has been sent. When the request
2509 has been processed, the process that called this function is
2510 passed a message on the form {garbage_collect, RequestId,
2511 GCResult}.
2512 {type, 'major' | 'minor'}:
2514 Triggers garbage collection of requested type. Default value
2515 is 'major', which would trigger a fullsweep GC. The option
2516 'minor' is considered a hint and may lead to either minor or
2517 major GC run.
2518 If Pid equals self(), and no async option has been passed, the
2520 garbage collection is performed at once, that is, the same as
2521 calling garbage_collect/0. Otherwise a request for garbage col‐
2522 lection is sent to the process identified by Pid, and will be
2523 handled when appropriate. If no async option has been passed,
2524 the caller blocks until GCResult is available and can be re‐
2525 turned.
2526 GCResult informs about the result of the garbage collection re‐
2528 quest as follows:
2529 true:
2531 The process identified by Pid has been garbage collected.
2532 false:
2534 No garbage collection was performed, as the process identi‐
2535 fied by Pid terminated before the request could be satis‐
2536 fied.
2537 Notice that the same caveats apply as for garbage_collect/0.
2539 Failures:
2541 badarg:
2543 If Pid is not a node local process identifier.
2544 badarg:
2546 If OptionList is an invalid list of options.
2547 get() -> [{Key, Val}]
2549 Types:
2551 Key = Val = term()
2553 Returns the process dictionary as a list of {Key, Val} tuples.
2555 The items in the returned list can be in any order. Example:
2556 > put(key1, merry),
2558 put(key2, lambs),
2559 put(key3, {are, playing}),
2560 get().
2561 [{key1,merry},{key2,lambs},{key3,{are,playing}}]
2562 get(Key) -> Val | undefined
2564 Types:
2566 Key = Val = term()
2568 Returns the value Val associated with Key in the process dictio‐
2570 nary, or undefined if Key does not exist. The expected time com‐
2571 plexity for the current implementation of this function is O(1)
2572 and the worst case time complexity is O(N), where N is the num‐
2573 ber of items in the process dictionary. Example:
2574 > put(key1, merry),
2576 put(key2, lambs),
2577 put({any, [valid, term]}, {are, playing}),
2578 get({any, [valid, term]}).
2579 {are,playing}
2580 erlang:get_cookie() -> Cookie | nocookie
2582 Types:
2584 Cookie = atom()
2586 Returns the magic cookie of the local node if the node is alive,
2588 otherwise the atom nocookie. This value is set by set_cookie/1.
2589 erlang:get_cookie(Node) -> Cookie | nocookie
2591 Types:
2593 Node = node()
2595 Cookie = atom()
2596 Returns the magic cookie for node Node if the local node is
2598 alive, otherwise the atom nocookie. This value is set by
2599 set_cookie/2.
2600 get_keys() -> [Key]
2602 Types:
2604 Key = term()
2606 Returns a list of all keys present in the process dictionary.
2608 The items in the returned list can be in any order. Example:
2609 > put(dog, {animal,1}),
2611 put(cow, {animal,2}),
2612 put(lamb, {animal,3}),
2613 get_keys().
2614 [dog,cow,lamb]
2615 get_keys(Val) -> [Key]
2617 Types:
2619 Val = Key = term()
2621 Returns a list of keys that are associated with the value Val in
2623 the process dictionary. The items in the returned list can be in
2624 any order. Example:
2625 > put(mary, {1, 2}),
2627 put(had, {1, 2}),
2628 put(a, {1, 2}),
2629 put(little, {1, 2}),
2630 put(dog, {1, 3}),
2631 put(lamb, {1, 2}),
2632 get_keys({1, 2}).
2633 [mary,had,a,little,lamb]
2634 group_leader() -> pid()
2636 Returns the process identifier of the group leader for the
2638 process evaluating the function.
2639 Every process is a member of some process group and all groups
2641 have a group leader. All I/O from the group is channeled to the
2642 group leader. When a new process is spawned, it gets the same
2643 group leader as the spawning process. Initially, at system
2644 startup, init is both its own group leader and the group leader
2645 of all processes.
2646 group_leader(GroupLeader, Pid) -> true
2648 Types:
2650 GroupLeader = Pid = pid()
2652 Sets the group leader of Pid to GroupLeader. Typically, this is
2654 used when a process started from a certain shell is to have an‐
2655 other group leader than init.
2656 The group leader should be rarely changed in applications with a
2658 supervision tree, because OTP assumes the group leader of their
2659 processes is their application master.
2660 Setting the group leader follows the signal ordering guarantees
2662 described in the Processes Chapter in the Erlang Reference Man‐
2663 ual .
2664 See also group_leader/0 and OTP design principles related to
2666 starting and stopping applications.
2667 halt() -> no_return()
2669 The same as halt(0, []). Example:
2671 > halt().
2673 os_prompt%
2674 halt(Status) -> no_return()
2676 Types:
2678 Status = integer() >= 0 | abort | string()
2680 The same as halt(Status, []). Example:
2682 > halt(17).
2684 os_prompt% echo $?
2685 17
2686 os_prompt%
2687 halt(Status, Options) -> no_return()
2689 Types:
2691 Status = integer() >= 0 | abort | string()
2693 Options = [Option]
2694 Option = {flush, boolean()}
2695 Status must be a non-negative integer, a string, or the atom
2697 abort. Halts the Erlang runtime system. Has no return value. De‐
2698 pending on Status, the following occurs:
2699 integer():
2701 The runtime system exits with integer value Status as status
2702 code to the calling environment (OS).
2703 Note:
2705 On many platforms, the OS supports only status codes 0-255. A
2706 too large status code is truncated by clearing the high bits.
2707 string():
2710 An Erlang crash dump is produced with Status as slogan. Then
2711 the runtime system exits with status code 1. The string will
2712 be truncated if longer than 200 characters.
2713 Note:
2715 Before ERTS 9.1 (OTP-20.1) only code points in the range 0-255
2716 was accepted in the string. Now any unicode string is valid.
2717 abort:
2720 The runtime system aborts producing a core dump, if that is
2721 enabled in the OS.
2722 For integer Status, the Erlang runtime system closes all ports
2724 and allows async threads to finish their operations before exit‐
2725 ing. To exit without such flushing, use Option as {flush,false}.
2726 For statuses string() and abort, option flush is ignored and
2728 flushing is not done.
2729 hd(List) -> term()
2731 Types:
2733 List = [term(), ...]
2735 Returns the head of List, that is, the first element, for exam‐
2737 ple:
2738 > hd([1,2,3,4,5]).
2740 1
2741 Allowed in guard tests.
2743 Failure: badarg if List is the empty list [].
2745 erlang:hibernate(Module, Function, Args) -> no_return()
2747 Types:
2749 Module = module()
2751 Function = atom()
2752 Args = [term()]
2753 Puts the calling process into a wait state where its memory al‐
2755 location has been reduced as much as possible. This is useful if
2756 the process does not expect to receive any messages soon.
2757 The process is awaken when a message is sent to it, and control
2759 resumes in Module:Function with the arguments specified by Args
2760 with the call stack emptied, meaning that the process terminates
2761 when that function returns. Thus erlang:hibernate/3 never re‐
2762 turns to its caller. The resume function Module:Function/Arity
2763 must be exported (Arity =:= length(Args)).
2764 If the process has any message in its message queue, the process
2766 is awakened immediately in the same way as described earlier.
2767 In more technical terms, erlang:hibernate/3 discards the call
2769 stack for the process, and then garbage collects the process.
2770 After this, all live data is in one continuous heap. The heap is
2771 then shrunken to the exact same size as the live data that it
2772 holds (even if that size is less than the minimum heap size for
2773 the process).
2774 If the size of the live data in the process is less than the
2776 minimum heap size, the first garbage collection occurring after
2777 the process is awakened ensures that the heap size is changed to
2778 a size not smaller than the minimum heap size.
2779 Notice that emptying the call stack means that any surrounding
2781 catch is removed and must be re-inserted after hibernation. One
2782 effect of this is that processes started using proc_lib (also
2783 indirectly, such as gen_server processes), are to use
2784 proc_lib:hibernate/3 instead, to ensure that the exception han‐
2785 dler continues to work when the process wakes up.
2786 erlang:insert_element(Index, Tuple1, Term) -> Tuple2
2788 Types:
2790 Index = integer() >= 1
2792 1..tuple_size(Tuple1) + 1
2793 Tuple1 = Tuple2 = tuple()
2794 Term = term()
2795 Returns a new tuple with element Term inserted at position Index
2797 in tuple Tuple1. All elements from position Index and upwards
2798 are pushed one step higher in the new tuple Tuple2. Example:
2799 > erlang:insert_element(2, {one, two, three}, new).
2801 {one,new,two,three}
2802 integer_to_binary(Integer) -> binary()
2804 Types:
2806 Integer = integer()
2808 Returns a binary corresponding to the text representation of In‐
2810 teger, for example:
2811 > integer_to_binary(77).
2813 <<"77">>
2814 integer_to_binary(Integer, Base) -> binary()
2816 Types:
2818 Integer = integer()
2820 Base = 2..36
2821 Returns a binary corresponding to the text representation of In‐
2823 teger in base Base, for example:
2824 > integer_to_binary(1023, 16).
2826 <<"3FF">>
2827 integer_to_list(Integer) -> string()
2829 Types:
2831 Integer = integer()
2833 Returns a string corresponding to the text representation of In‐
2835 teger, for example:
2836 > integer_to_list(77).
2838 "77"
2839 integer_to_list(Integer, Base) -> string()
2841 Types:
2843 Integer = integer()
2845 Base = 2..36
2846 Returns a string corresponding to the text representation of In‐
2848 teger in base Base, for example:
2849 > integer_to_list(1023, 16).
2851 "3FF"
2852 iolist_size(Item) -> integer() >= 0
2854 Types:
2856 Item = iolist() | binary()
2858 Returns an integer, that is the size in bytes, of the binary
2860 that would be the result of iolist_to_binary(Item), for example:
2861 > iolist_size([1,2|<<3,4>>]).
2863 4
2864 iolist_to_binary(IoListOrBinary) -> binary()
2866 Types:
2868 IoListOrBinary = iolist() | binary()
2870 Returns a binary that is made from the integers and binaries in
2872 IoListOrBinary, for example:
2873 > Bin1 = <<1,2,3>>.
2875 <<1,2,3>>
2876 > Bin2 = <<4,5>>.
2877 <<4,5>>
2878 > Bin3 = <<6>>.
2879 <<6>>
2880 > iolist_to_binary([Bin1,1,[2,3,Bin2],4|Bin3]).
2881 <<1,2,3,1,2,3,4,5,4,6>>
2882 erlang:iolist_to_iovec(IoListOrBinary) -> iovec()
2884 Types:
2886 IoListOrBinary = iolist() | binary()
2888 Returns an iovec that is made from the integers and binaries in
2890 IoListOrBinary. This function is useful when you want to flatten
2891 an iolist but you do not need a single binary. This can be use‐
2892 ful for passing the data to nif functions such as enif_in‐
2893 spect_iovec or do more efficient message passing. The advantage
2894 of using this function over iolist_to_binary/1 is that it does
2895 not have to copy off-heap binaries. Example:
2896 > Bin1 = <<1,2,3>>.
2898 <<1,2,3>>
2899 > Bin2 = <<4,5>>.
2900 <<4,5>>
2901 > Bin3 = <<6>>.
2902 <<6>>
2903 %% If you pass small binaries and integers it works as iolist_to_binary
2904 > erlang:iolist_to_iovec([Bin1,1,[2,3,Bin2],4|Bin3]).
2905 [<<1,2,3,1,2,3,4,5,4,6>>]
2906 %% If you pass larger binaries, they are split and returned in a form
2907 %% optimized for calling the C function writev.
2908 > erlang:iolist_to_iovec([<<1>>,<<2:8096>>,<<3:8096>>]).
2909 [<<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,
2910 0,...>>,
2911 <<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,
2912 ...>>,
2913 <<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,...>>]
2914 is_alive() -> boolean()
2916 Returns true if the local node is alive (that is, if the node
2918 can be part of a distributed system), otherwise false. A node is
2919 alive if it is started with:
2920 * "erl -name LONGNAME" or,
2922 * "erl -sname SHORTNAME".
2924 A node can also be alive if it has got a name from a call to
2926 net_kernel:start/1 and has not been stopped by a call to
2927 net_kernel:stop/0.
2928 is_atom(Term) -> boolean()
2930 Types:
2932 Term = term()
2934 Returns true if Term is an atom, otherwise false.
2936 Allowed in guard tests.
2938 is_binary(Term) -> boolean()
2940 Types:
2942 Term = term()
2944 Returns true if Term is a binary, otherwise false.
2946 A binary always contains a complete number of bytes.
2948 Allowed in guard tests.
2950 is_bitstring(Term) -> boolean()
2952 Types:
2954 Term = term()
2956 Returns true if Term is a bitstring (including a binary), other‐
2958 wise false.
2959 Allowed in guard tests.
2961 is_boolean(Term) -> boolean()
2963 Types:
2965 Term = term()
2967 Returns true if Term is the atom true or the atom false (that
2969 is, a boolean). Otherwise returns false.
2970 Allowed in guard tests.
2972 erlang:is_builtin(Module, Function, Arity) -> boolean()
2974 Types:
2976 Module = module()
2978 Function = atom()
2979 Arity = arity()
2980 This BIF is useful for builders of cross-reference tools.
2982 Returns true if Module:Function/Arity is a BIF implemented in C,
2984 otherwise false.
2985 is_float(Term) -> boolean()
2987 Types:
2989 Term = term()
2991 Returns true if Term is a floating point number, otherwise
2993 false.
2994 Allowed in guard tests.
2996 is_function(Term) -> boolean()
2998 Types:
3000 Term = term()
3002 Returns true if Term is a fun, otherwise false.
3004 Allowed in guard tests.
3006 is_function(Term, Arity) -> boolean()
3008 Types:
3010 Term = term()
3012 Arity = arity()
3013 Returns true if Term is a fun that can be applied with Arity
3015 number of arguments, otherwise false.
3016 Allowed in guard tests.
3018 is_integer(Term) -> boolean()
3020 Types:
3022 Term = term()
3024 Returns true if Term is an integer, otherwise false.
3026 Allowed in guard tests.
3028 is_list(Term) -> boolean()
3030 Types:
3032 Term = term()
3034 Returns true if Term is a list with zero or more elements, oth‐
3036 erwise false.
3037 Allowed in guard tests.
3039 is_map(Term) -> boolean()
3041 Types:
3043 Term = term()
3045 Returns true if Term is a map, otherwise false.
3047 Allowed in guard tests.
3049 is_map_key(Key, Map) -> boolean()
3051 Types:
3053 Key = term()
3055 Map = map()
3056 Returns true if map Map contains Key and returns false if it
3058 does not contain the Key.
3059 The call fails with a {badmap,Map} exception if Map is not a
3061 map.
3062 Example:
3064 > Map = #{"42" => value}.
3066 #{"42" => value}
3067 > is_map_key("42",Map).
3068 true
3069 > is_map_key(value,Map).
3070 false
3071 Allowed in guard tests.
3073 is_number(Term) -> boolean()
3075 Types:
3077 Term = term()
3079 Returns true if Term is an integer or a floating point number.
3081 Otherwise returns false.
3082 Allowed in guard tests.
3084 is_pid(Term) -> boolean()
3086 Types:
3088 Term = term()
3090 Returns true if Term is a process identifier, otherwise false.
3092 Allowed in guard tests.
3094 is_port(Term) -> boolean()
3096 Types:
3098 Term = term()
3100 Returns true if Term is a port identifier, otherwise false.
3102 Allowed in guard tests.
3104 is_process_alive(Pid) -> boolean()
3106 Types:
3108 Pid = pid()
3110 Pid must refer to a process at the local node.
3112 Returns true if the process exists and is alive, that is, is not
3114 exiting and has not exited. Otherwise returns false.
3115 If process P1 calls is_process_alive(P2Pid) it is guaranteed
3117 that all signals, sent from P1 to P2 (P2 is the process with
3118 identifier P2Pid) before the call, will be delivered to P2 be‐
3119 fore the aliveness of P2 is checked. This guarantee means that
3120 one can use is_process_alive/1 to let a process P1 wait until a
3121 process P2, which has got an exit signal with reason kill from
3122 P1, is killed. Example:
3123 exit(P2Pid, kill),
3125 % P2 might not be killed
3126 is_process_alive(P2Pid),
3127 % P2 is not alive (the call above always return false)
3128 See the documentation about signals and erlang:exit/2 for more
3131 information about signals and exit signals.
3132 is_record(Term, RecordTag) -> boolean()
3134 Types:
3136 Term = term()
3138 RecordTag = atom()
3139 Returns true if Term is a tuple and its first element is Record‐
3141 Tag. Otherwise returns false.
3142 Note:
3144 Normally the compiler treats calls to is_record/2 especially. It
3145 emits code to verify that Term is a tuple, that its first ele‐
3146 ment is RecordTag, and that the size is correct. However, if
3147 RecordTag is not a literal atom, the BIF is_record/2 is called
3148 instead and the size of the tuple is not verified.
3149 Allowed in guard tests, if RecordTag is a literal atom.
3152 is_record(Term, RecordTag, Size) -> boolean()
3154 Types:
3156 Term = term()
3158 RecordTag = atom()
3159 Size = integer() >= 0
3160 RecordTag must be an atom.
3162 Returns true if Term is a tuple, its first element is RecordTag,
3164 and its size is Size. Otherwise returns false.
3165 Allowed in guard tests if RecordTag is a literal atom and Size
3167 is a literal integer.
3168 Note:
3170 This BIF is documented for completeness. Usually is_record/2 is
3171 to be used.
3172 is_reference(Term) -> boolean()
3175 Types:
3177 Term = term()
3179 Returns true if Term is a reference, otherwise false.
3181 Allowed in guard tests.
3183 is_tuple(Term) -> boolean()
3185 Types:
3187 Term = term()
3189 Returns true if Term is a tuple, otherwise false.
3191 Allowed in guard tests.
3193 length(List) -> integer() >= 0
3195 Types:
3197 List = [term()]
3199 Returns the length of List, for example:
3201 > length([1,2,3,4,5,6,7,8,9]).
3203 9
3204 Allowed in guard tests.
3206 link(PidOrPort) -> true
3208 Types:
3210 PidOrPort = pid() | port()
3212 Sets up and activates a link between the calling process and an‐
3214 other process or a port identified by PidOrPort. We will from
3215 here on call the identified process or port linkee. If the lin‐
3216 kee is a port, it must reside on the same node as the caller.
3217 If one of the participants of a link terminates, it will send an
3219 exit signal to the other participant. The exit signal will con‐
3220 tain the exit reason of the terminated participant. Other cases
3221 when exit signals are triggered due to a link are when no linkee
3222 exist (noproc exit reason) and when the connection between
3223 linked processes on different nodes is lost or cannot be estab‐
3224 lished (noconnection exit reason).
3225 An existing link can be removed by calling unlink/1. For more
3227 information on links and exit signals due to links, see the Pro‐
3228 cesses chapter in the Erlang Reference Manual :
3229 * Links
3231 * Sending Exit Signals
3233 * Receiving Exit Signals
3235 For historical reasons, link/1 has a strange semi-synchronous
3237 behavior when it is "cheap" to check if the linkee exists or
3238 not, and the caller does not trap exits. If the above is true
3239 and the linkee does not exist, link/1 will raise a noproc error
3240 exception. The expected behavior would instead have been that
3241 link/1 returned true, and the caller later was sent an exit sig‐
3242 nal with noproc exit reason, but this is unfortunately not the
3243 case. The noproc exception is not to be confused with an exit
3244 signal with exit reason noproc. Currently it is "cheap" to check
3245 if the linkee exists when it is supposed to reside on the same
3246 node as the calling process.
3247 The link setup and activation is performed asynchronously. If
3249 the link already exists, or if the caller attempts to create a
3250 link to itself, nothing is done. A detailed description of the
3251 link protocol can be found in the Distribution Protocol chapter
3252 of the ERTS User's Guide .
3253 Failure:
3255 * badarg if PidOrPort does not identify a process or a node
3257 local port.
3258 * noproc linkee does not exist and it is "cheap" to check if
3260 it exists as described above.
3261 list_to_atom(String) -> atom()
3263 Types:
3265 String = string()
3267 Returns the atom whose text representation is String.
3269 As from Erlang/OTP 20, String may contain any Unicode character.
3271 Earlier versions allowed only ISO-latin-1 characters as the im‐
3272 plementation did not allow Unicode characters above 255.
3273 Note:
3275 The number of characters that are permitted in an atom name is
3276 limited. The default limits can be found in the efficiency
3277 guide (section Advanced).
3278 Note:
3281 There is configurable limit on how many atoms that can exist and
3282 atoms are not garbage collected. Therefore, it is recommended to
3283 consider if list_to_existing_atom/1 is a better option than
3284 list_to_atom/1. The default limits can be found in the effi‐
3285 ciency guide (section Advanced).
3286 Example:
3289 > list_to_atom("Erlang").
3291 list_to_binary(IoList) -> binary()
3293 Types:
3295 IoList = iolist()
3297 Returns a binary that is made from the integers and binaries in
3299 IoList, for example:
3300 > Bin1 = <<1,2,3>>.
3302 <<1,2,3>>
3303 > Bin2 = <<4,5>>.
3304 <<4,5>>
3305 > Bin3 = <<6>>.
3306 <<6>>
3307 > list_to_binary([Bin1,1,[2,3,Bin2],4|Bin3]).
3308 <<1,2,3,1,2,3,4,5,4,6>>
3309 list_to_bitstring(BitstringList) -> bitstring()
3311 Types:
3313 BitstringList = bitstring_list()
3315 bitstring_list() =
3316 maybe_improper_list(byte() | bitstring() | bitstring_list(),
3317 bitstring() | [])
3318 Returns a bitstring that is made from the integers and bit‐
3320 strings in BitstringList. (The last tail in BitstringList is al‐
3321 lowed to be a bitstring.) Example:
3322 > Bin1 = <<1,2,3>>.
3324 <<1,2,3>>
3325 > Bin2 = <<4,5>>.
3326 <<4,5>>
3327 > Bin3 = <<6,7:4>>.
3328 <<6,7:4>>
3329 > list_to_bitstring([Bin1,1,[2,3,Bin2],4|Bin3]).
3330 <<1,2,3,1,2,3,4,5,4,6,7:4>>
3331 list_to_existing_atom(String) -> atom()
3333 Types:
3335 String = string()
3337 Returns the atom whose text representation is String, but only
3339 if there already exists such atom. An atom exists if it has been
3340 created by the run-time system by either loading code or creat‐
3341 ing a term in which the atom is part.
3342 Failure: badarg if there does not already exist an atom whose
3344 text representation is String.
3345 Note:
3347 Note that the compiler may optimize away atoms. For example, the
3348 compiler will rewrite atom_to_list(some_atom) to "some_atom". If
3349 that expression is the only mention of the atom some_atom in the
3350 containing module, the atom will not be created when the module
3351 is loaded, and a subsequent call to list_to_exist‐
3352 ing_atom("some_atom") will fail.
3353 list_to_float(String) -> float()
3356 Types:
3358 String = string()
3360 Returns the float whose text representation is String, for exam‐
3362 ple:
3363 > list_to_float("2.2017764e+0").
3365 2.2017764
3366 The float string format is the same as the format for Erlang
3368 float literals except for that underscores are not permitted.
3369 Failure: badarg if String contains a bad representation of a
3371 float.
3372 list_to_integer(String) -> integer()
3374 Types:
3376 String = string()
3378 Returns an integer whose text representation is String, for ex‐
3380 ample:
3381 > list_to_integer("123").
3383 123
3384 > list_to_integer("-123").
3386 -123
3387 > list_to_integer("+123234982304982309482093833234234").
3389 123234982304982309482093833234234
3390 String must contain at least one digit character and can have an
3392 optional prefix consisting of a single "+" or "-" character
3393 (that is, String must match the regular expression
3394 "^[+-]?[0-9]+$").
3395 Failure: badarg if String contains a bad representation of an
3397 integer.
3398 list_to_integer(String, Base) -> integer()
3400 Types:
3402 String = string()
3404 Base = 2..36
3405 Returns an integer whose text representation in base Base is
3407 String, for example:
3408 > list_to_integer("3FF", 16).
3410 1023
3411 > list_to_integer("+3FF", 16).
3413 1023
3414 > list_to_integer("3ff", 16).
3416 1023
3417 > list_to_integer("3fF", 16).
3419 1023
3420 > list_to_integer("-3FF", 16).
3422 -1023
3423 For example, when Base is 16, String must match the regular ex‐
3425 pression "^[+-]?([0-9]|[A-F]|[a-f])+$".
3426 Failure: badarg if String contains a bad representation of an
3428 integer.
3429 list_to_pid(String) -> pid()
3431 Types:
3433 String = string()
3435 Returns a process identifier whose text representation is a
3437 String, for example:
3438 > list_to_pid("<0.4.1>").
3440 <0.4.1>
3441 Failure: badarg if String contains a bad representation of a
3443 process identifier.
3444 Warning:
3446 This BIF is intended for debugging and is not to be used in ap‐
3447 plication programs.
3448 list_to_port(String) -> port()
3451 Types:
3453 String = string()
3455 Returns a port identifier whose text representation is a String,
3457 for example:
3458 > list_to_port("#Port<0.4>").
3460 #Port<0.4>
3461 Failure: badarg if String contains a bad representation of a
3463 port identifier.
3464 Warning:
3466 This BIF is intended for debugging and is not to be used in ap‐
3467 plication programs.
3468 list_to_ref(String) -> reference()
3471 Types:
3473 String = string()
3475 Returns a reference whose text representation is a String, for
3477 example:
3478 > list_to_ref("#Ref<0.4192537678.4073193475.71181>").
3480 #Ref<0.4192537678.4073193475.71181>
3481 Failure: badarg if String contains a bad representation of a
3483 reference.
3484 Warning:
3486 This BIF is intended for debugging and is not to be used in ap‐
3487 plication programs.
3488 list_to_tuple(List) -> tuple()
3491 Types:
3493 List = [term()]
3495 Returns a tuple corresponding to List, for example
3497 > list_to_tuple([share, ['Ericsson_B', 163]]).
3499 {share, ['Ericsson_B', 163]}
3500 List can contain any Erlang terms.
3502 load_module(Module, Binary) -> {module, Module} | {error, Reason}
3504 Types:
3506 Module = module()
3508 Binary = binary()
3509 Reason =
3510 badfile | not_purged | on_load |
3511 {features_not_allowed, [atom()]}
3512 If Binary contains the object code for module Module, this BIF
3514 loads that object code. If the code for module Module already
3515 exists, all export references are replaced so they point to the
3516 newly loaded code. The previously loaded code is kept in the
3517 system as old code, as there can still be processes executing
3518 that code.
3519 Returns either {module, Module}, or {error, Reason} if loading
3521 fails. Reason is one of the following:
3522 badfile:
3524 The object code in Binary has an incorrect format or the ob‐
3525 ject code contains code for another module than Module.
3526 not_purged:
3528 Binary contains a module that cannot be loaded because old
3529 code for this module already exists.
3530 on_load:
3532 The code in Binary contains an on_load declaration that must
3533 be executed before Binary can become the current code. Any
3534 previous current code for Module will remain until the
3535 on_load call has finished.
3536 not_allowed:
3538 The code in Binary has been compiled with features that are
3539 currently not enabled in the runtime system.
3540 Warning:
3542 This BIF is intended for the code server (see code(3)) and is
3543 not to be used elsewhere.
3544 erlang:load_nif(Path, LoadInfo) -> ok | Error
3547 Types:
3549 Path = string()
3551 LoadInfo = term()
3552 Error = {error, {Reason, Text :: string()}}
3553 Reason =
3554 load_failed | bad_lib | load | reload | upgrade |
3555 old_code
3556 Loads and links a dynamic library containing native implemented
3558 functions (NIFs) for a module. Path is a file path to the share‐
3559 able object/dynamic library file minus the OS-dependent file ex‐
3560 tension (.so for Unix and .dll for Windows). Notice that on most
3561 OSs the library has to have a different name on disc when an up‐
3562 grade of the nif is done. If the name is the same, but the con‐
3563 tents differ, the old library may be loaded instead. For infor‐
3564 mation on how to implement a NIF library, see erl_nif(3).
3565 LoadInfo can be any term. It is passed on to the library as part
3567 of the initialization. A good practice is to include a module
3568 version number to support future code upgrade scenarios.
3569 The call to load_nif/2 must be made directly from the Erlang
3571 code of the module that the NIF library belongs to. It returns
3572 either ok, or {error,{Reason,Text}} if loading fails. Reason is
3573 one of the following atoms while Text is a human readable string
3574 that can give more information about the failure:
3575 load_failed:
3577 The OS failed to load the NIF library.
3578 bad_lib:
3580 The library did not fulfill the requirements as a NIF li‐
3581 brary of the calling module.
3582 load | upgrade:
3584 The corresponding library callback was unsuccessful.
3585 reload:
3587 A NIF library is already loaded for this module instance.
3588 The previously deprecated reload feature was removed in OTP
3589 20.
3590 old_code:
3592 The call to load_nif/2 was made from the old code of a mod‐
3593 ule that has been upgraded; this is not allowed.
3594 If the -nifs() attribute is used (which is recommended), all
3596 NIFs in the dynamic library much be declared as such for
3597 load_nif/2 to succeed. On the other hand, all functions declared
3598 with the -nifs() attribute do not have to be implemented by the
3599 dynamic library. This allows a target independent Erlang file to
3600 contain fallback implementations for functions that may lack NIF
3601 support depending on target OS/hardware platform.
3602 erlang:loaded() -> [Module]
3604 Types:
3606 Module = module()
3608 Returns a list of all loaded Erlang modules (current and old
3610 code), including preloaded modules.
3611 See also code(3).
3613 erlang:localtime() -> DateTime
3615 Types:
3617 DateTime = calendar:datetime()
3619 Returns the current local date and time, {{Year, Month, Day},
3621 {Hour, Minute, Second}}, for example:
3622 > erlang:localtime().
3624 {{1996,11,6},{14,45,17}}
3625 The time zone and Daylight Saving Time correction depend on the
3627 underlying OS. The return value is based on the OS System Time.
3628 erlang:localtime_to_universaltime(Localtime) -> Universaltime
3630 Types:
3632 Localtime = Universaltime = calendar:datetime()
3634 Converts local date and time to Universal Time Coordinated
3636 (UTC), if supported by the underlying OS. Otherwise no conver‐
3637 sion is done and Localtime is returned. Example:
3638 > erlang:localtime_to_universaltime({{1996,11,6},{14,45,17}}).
3640 {{1996,11,6},{13,45,17}}
3641 Failure: badarg if Localtime denotes an invalid date and time.
3643 erlang:localtime_to_universaltime(Localtime, IsDst) ->
3645 Universaltime
3646 Types:
3648 Localtime = Universaltime = calendar:datetime()
3650 IsDst = true | false | undefined
3651 Converts local date and time to Universal Time Coordinated (UTC)
3653 as erlang:localtime_to_universaltime/1, but the caller decides
3654 if Daylight Saving Time is active.
3655 If IsDst == true, Localtime is during Daylight Saving Time, if
3657 IsDst == false it is not. If IsDst == undefined, the underlying
3658 OS can guess, which is the same as calling erlang:local‐
3659 time_to_universaltime(Localtime).
3660 Examples:
3662 > erlang:localtime_to_universaltime({{1996,11,6},{14,45,17}}, true).
3664 {{1996,11,6},{12,45,17}}
3665 > erlang:localtime_to_universaltime({{1996,11,6},{14,45,17}}, false).
3666 {{1996,11,6},{13,45,17}}
3667 > erlang:localtime_to_universaltime({{1996,11,6},{14,45,17}}, undefined).
3668 {{1996,11,6},{13,45,17}}
3669 Failure: badarg if Localtime denotes an invalid date and time.
3671 make_ref() -> reference()
3673 Returns a unique reference. The reference is unique among con‐
3675 nected nodes.
3676 Warning:
3678 Before OTP-23 when a node is restarted multiple times with the
3679 same node name, references created on a newer node can be mis‐
3680 taken for a reference created on an older node with the same
3681 node name.
3682 erlang:make_tuple(Arity, InitialValue) -> tuple()
3685 Types:
3687 Arity = arity()
3689 InitialValue = term()
3690 Creates a new tuple of the specified Arity, where all elements
3692 are InitialValue, for example:
3693 > erlang:make_tuple(4, []).
3695 {[],[],[],[]}
3696 erlang:make_tuple(Arity, DefaultValue, InitList) -> tuple()
3698 Types:
3700 Arity = arity()
3702 DefaultValue = term()
3703 InitList = [{Position :: integer() >= 1, term()}]
3704 Creates a tuple of size Arity, where each element has value De‐
3706 faultValue, and then fills in values from InitList. Each list
3707 element in InitList must be a two-tuple, where the first element
3708 is a position in the newly created tuple and the second element
3709 is any term. If a position occurs more than once in the list,
3710 the term corresponding to the last occurrence is used. Example:
3711 > erlang:make_tuple(5, [], [{2,ignored},{5,zz},{2,aa}]).
3713 {[],aa,[],[],zz}
3714 map_get(Key, Map) -> Value
3716 Types:
3718 Map = map()
3720 Key = Value = any()
3721 Returns value Value associated with Key if Map contains Key.
3723 The call fails with a {badmap,Map} exception if Map is not a
3725 map, or with a {badkey,Key} exception if no value is associated
3726 with Key.
3727 Example:
3729 > Key = 1337,
3731 Map = #{42 => value_two,1337 => "value one","a" => 1},
3732 map_get(Key,Map).
3733 "value one"
3734 Allowed in guard tests.
3736 map_size(Map) -> integer() >= 0
3738 Types:
3740 Map = map()
3742 Returns an integer, which is the number of key-value pairs in
3744 Map, for example:
3745 > map_size(#{a=>1, b=>2, c=>3}).
3747 3
3748 Allowed in guard tests.
3750 erlang:match_spec_test(MatchAgainst, MatchSpec, Type) ->
3752 TestResult
3753 Types:
3755 MatchAgainst = [term()] | tuple()
3757 MatchSpec = term()
3758 Type = table | trace
3759 TestResult =
3760 {ok, term(), [return_trace], [{error | warning,
3761 string()}]} |
3762 {error, [{error | warning, string()}]}
3763 Tests a match specification used in calls to ets:select/2 and
3765 erlang:trace_pattern/3. The function tests both a match specifi‐
3766 cation for "syntactic" correctness and runs the match specifica‐
3767 tion against the object. If the match specification contains er‐
3768 rors, the tuple {error, Errors} is returned, where Errors is a
3769 list of natural language descriptions of what was wrong with the
3770 match specification.
3771 If Type is table, the object to match against is to be a tuple.
3773 The function then returns {ok,Result,[],Warnings}, where Result
3774 is what would have been the result in a real ets:select/2 call,
3775 or false if the match specification does not match the object
3776 tuple.
3777 If Type is trace, the object to match against is to be a list.
3779 The function returns {ok, Result, Flags, Warnings}, where Result
3780 is one of the following:
3781 * true if a trace message is to be emitted
3783 * false if a trace message is not to be emitted
3785 * The message term to be appended to the trace message
3787 Flags is a list containing all the trace flags to be enabled,
3789 currently this is only return_trace.
3790 This is a useful debugging and test tool, especially when writ‐
3792 ing complicated match specifications.
3793 See also ets:test_ms/2.
3795 max(Term1, Term2) -> Maximum
3797 Types:
3799 Term1 = Term2 = Maximum = term()
3801 Returns the largest of Term1 and Term2. If the terms compare
3803 equal with the == operator, Term1 is returned.
3804 The Expressions section contains descriptions of the == opera‐
3806 tor and how terms are ordered.
3807 Examples:
3809 > max(1, 2).
3811 2
3812 > max(1.0, 1).
3814 1.0
3815 > max(1, 1.0).
3817 1
3818 > max("abc", "b").
3820 "b"
3821 erlang:md5(Data) -> Digest
3823 Types:
3825 Data = iodata()
3827 Digest = binary()
3828 Computes an MD5 message digest from Data, where the length of
3830 the digest is 128 bits (16 bytes). Data is a binary or a list of
3831 small integers and binaries.
3832 For more information about MD5, see RFC 1321 - The MD5 Message-
3834 Digest Algorithm.
3835 Warning:
3837 The MD5 Message-Digest Algorithm is not considered safe for
3838 code-signing or software-integrity purposes.
3839 erlang:md5_final(Context) -> Digest
3842 Types:
3844 Context = Digest = binary()
3846 Finishes the update of an MD5 Context and returns the computed
3848 MD5 message digest.
3849 erlang:md5_init() -> Context
3851 Types:
3853 Context = binary()
3855 Creates an MD5 context, to be used in the following calls to
3857 md5_update/2.
3858 erlang:md5_update(Context, Data) -> NewContext
3860 Types:
3862 Context = binary()
3864 Data = iodata()
3865 NewContext = binary()
3866 Update an MD5 Context with Data and returns a NewContext.
3868 erlang:memory() -> [{Type, Size}]
3870 Types:
3872 Type = memory_type()
3874 Size = integer() >= 0
3875 memory_type() =
3876 total | processes | processes_used | system | atom |
3877 atom_used | binary | code | ets
3878 Returns a list with information about memory dynamically allo‐
3880 cated by the Erlang emulator. Each list element is a tuple
3881 {Type, Size}. The first element Type is an atom describing mem‐
3882 ory type. The second element Size is the memory size in bytes.
3883 Memory types:
3885 total:
3887 The total amount of memory currently allocated. This is the
3888 same as the sum of the memory size for processes and system.
3889 processes:
3891 The total amount of memory currently allocated for the Er‐
3892 lang processes.
3893 processes_used:
3895 The total amount of memory currently used by the Erlang pro‐
3896 cesses. This is part of the memory presented as processes
3897 memory.
3898 system:
3900 The total amount of memory currently allocated for the emu‐
3901 lator that is not directly related to any Erlang process.
3902 Memory presented as processes is not included in this mem‐
3903 ory. instrument(3) can be used to get a more detailed break‐
3904 down of what memory is part of this type.
3905 atom:
3907 The total amount of memory currently allocated for atoms.
3908 This memory is part of the memory presented as system mem‐
3909 ory.
3910 atom_used:
3912 The total amount of memory currently used for atoms. This
3913 memory is part of the memory presented as atom memory.
3914 binary:
3916 The total amount of memory currently allocated for binaries.
3917 This memory is part of the memory presented as system mem‐
3918 ory.
3919 code:
3921 The total amount of memory currently allocated for Erlang
3922 code. This memory is part of the memory presented as system
3923 memory.
3924 ets:
3926 The total amount of memory currently allocated for ETS ta‐
3927 bles. This memory is part of the memory presented as system
3928 memory.
3929 maximum:
3931 The maximum total amount of memory allocated since the emu‐
3932 lator was started. This tuple is only present when the emu‐
3933 lator is run with instrumentation.
3934 For information on how to run the emulator with instrumenta‐
3936 tion, see instrument(3) and/or erl(1).
3937 Note:
3939 The system value is not complete. Some allocated memory that is
3940 to be part of this value is not.
3941 When the emulator is run with instrumentation, the system value
3943 is more accurate, but memory directly allocated for malloc (and
3944 friends) is still not part of the system value. Direct calls to
3945 malloc are only done from OS-specific runtime libraries and per‐
3946 haps from user-implemented Erlang drivers that do not use the
3947 memory allocation functions in the driver interface.
3948 As the total value is the sum of processes and system, the error
3950 in system propagates to the total value.
3951 The different amounts of memory that are summed are not gathered
3953 atomically, which introduces an error in the result.
3954 The different values have the following relation to each other.
3957 Values beginning with an uppercase letter is not part of the re‐
3958 sult.
3959 total = processes + system
3961 processes = processes_used + ProcessesNotUsed
3962 system = atom + binary + code + ets + OtherSystem
3963 atom = atom_used + AtomNotUsed
3964 RealTotal = processes + RealSystem
3965 RealSystem = system + MissedSystem
3966 More tuples in the returned list can be added in a future re‐
3968 lease.
3969 Note:
3971 The total value is supposed to be the total amount of memory dy‐
3972 namically allocated by the emulator. Shared libraries, the code
3973 of the emulator itself, and the emulator stacks are not supposed
3974 to be included. That is, the total value is not supposed to be
3975 equal to the total size of all pages mapped to the emulator.
3976 Also, because of fragmentation and prereservation of memory ar‐
3978 eas, the size of the memory segments containing the dynamically
3979 allocated memory blocks can be much larger than the total size
3980 of the dynamically allocated memory blocks.
3981 Note:
3984 As from ERTS 5.6.4, erlang:memory/0 requires that all erts_al‐
3985 loc(3) allocators are enabled (default behavior).
3986 Failure: notsup if an erts_alloc(3) allocator has been disabled.
3989 erlang:memory(Type :: memory_type()) -> integer() >= 0
3991 erlang:memory(TypeList :: [memory_type()]) ->
3993 [{memory_type(), integer() >= 0}]
3994 Types:
3996 memory_type() =
3998 total | processes | processes_used | system | atom |
3999 atom_used | binary | code | ets
4000 Returns the memory size in bytes allocated for memory of type
4002 Type. The argument can also be specified as a list of mem‐
4003 ory_type() atoms, in which case a corresponding list of {mem‐
4004 ory_type(), Size :: integer >= 0} tuples is returned.
4005 Note:
4007 As from ERTS 5.6.4, erlang:memory/1 requires that all erts_al‐
4008 loc(3) allocators are enabled (default behavior).
4009 Failures:
4012 badarg:
4014 If Type is not one of the memory types listed in the de‐
4015 scription of erlang:memory/0.
4016 badarg:
4018 If maximum is passed as Type and the emulator is not run in
4019 instrumented mode.
4020 notsup:
4022 If an erts_alloc(3) allocator has been disabled.
4023 See also erlang:memory/0.
4025 min(Term1, Term2) -> Minimum
4027 Types:
4029 Term1 = Term2 = Minimum = term()
4031 Returns the smallest of Term1 and Term2. If the terms compare
4033 equal with the == operator, Term1 is returned.
4034 The Expressions section contains descriptions of the == opera‐
4036 tor and how terms are ordered.
4037 Examples:
4039 > min(1, 2).
4041 1
4042 > min(1.0, 1).
4044 1.0
4045 > min(1, 1.0).
4047 1
4048 > min("abc", "b").
4050 "abc"
4051 module_loaded(Module) -> boolean()
4053 Types:
4055 Module = module()
4057 Returns true if the module Module is loaded as current code ;
4059 otherwise, false. It does not attempt to load the module.
4060 monitor(Type :: process, Item :: monitor_process_identifier()) ->
4062 MonitorRef
4063 monitor(Type :: port, Item :: monitor_port_identifier()) ->
4065 MonitorRef
4066 monitor(Type :: time_offset, Item :: clock_service) -> MonitorRef
4068 Types:
4070 MonitorRef = reference()
4072 registered_name() = atom()
4073 registered_process_identifier() =
4074 registered_name() | {registered_name(), node()}
4075 monitor_process_identifier() =
4076 pid() | registered_process_identifier()
4077 monitor_port_identifier() = port() | registered_name()
4078 Sends a monitor request of type Type to the entity identified by
4080 Item. If the monitored entity does not exist or it changes moni‐
4081 tored state, the caller of monitor/2 is notified by a message on
4082 the following format:
4083 {Tag, MonitorRef, Type, Object, Info}
4085 Note:
4087 The monitor request is an asynchronous signal. That is, it takes
4088 time before the signal reaches its destination.
4089 Type can be one of the following atoms: process, port or
4092 time_offset.
4093 A process or port monitor is triggered only once, after that it
4095 is removed from both monitoring process and the monitored en‐
4096 tity. Monitors are fired when the monitored process or port ter‐
4097 minates, does not exist at the moment of creation, or if the
4098 connection to it is lost. If the connection to it is lost, we do
4099 not know if it still exists. The monitoring is also turned off
4100 when demonitor/1 is called.
4101 A process or port monitor by name resolves the RegisteredName to
4103 pid() or port() only once at the moment of monitor instantia‐
4104 tion, later changes to the name registration will not affect the
4105 existing monitor.
4106 When a process or port monitor is triggered, a 'DOWN' message is
4108 sent that has the following pattern:
4109 {'DOWN', MonitorRef, Type, Object, Info}
4111 In the monitor message MonitorRef and Type are the same as de‐
4113 scribed earlier, and:
4114 Object:
4116 The monitored entity, which triggered the event. When moni‐
4117 toring a process or a local port, Object will be equal to
4118 the pid() or port() that was being monitored. When monitor‐
4119 ing process or port by name, Object will have format {Regis‐
4120 teredName, Node} where RegisteredName is the name which has
4121 been used with monitor/2 call and Node is local or remote
4122 node name (for ports monitored by name, Node is always local
4123 node name).
4124 Info:
4126 Either the exit reason of the process, noproc (process or
4127 port did not exist at the time of monitor creation), or no‐
4128 connection (no connection to the node where the monitored
4129 process resides).
4130 Monitoring a process:
4132 Creates monitor between the current process and another
4133 process identified by Item, which can be a pid() (local or
4134 remote), an atom RegisteredName or a tuple {RegisteredName,
4135 Node} for a registered process, located elsewhere.
4136 Note:
4138 Before ERTS 10.0 (OTP 21.0), monitoring a process could fail
4139 with badarg if the monitored process resided on a primitive
4140 node (such as erl_interface or jinterface), where remote
4141 process monitoring is not implemented.
4142 Now, such a call to monitor will instead succeed and a monitor
4144 is created. But the monitor will only supervise the connec‐
4145 tion. That is, a {'DOWN', _, process, _, noconnection} is the
4146 only message that may be received, as the primitive node have
4147 no way of reporting the status of the monitored process.
4148 Monitoring a port:
4151 Creates monitor between the current process and a port iden‐
4152 tified by Item, which can be a port() (only local), an atom
4153 RegisteredName or a tuple {RegisteredName, Node} for a reg‐
4154 istered port, located on this node. Note, that attempt to
4155 monitor a remote port will result in badarg.
4156 Monitoring a time_offset:
4158 Monitors changes in time offset between Erlang monotonic
4159 time and Erlang system time. One valid Item exists in combi‐
4160 nation with the time_offset Type, namely the atom clock_ser‐
4161 vice. Notice that the atom clock_service is not the regis‐
4162 tered name of a process. In this case it serves as an iden‐
4163 tifier of the runtime system internal clock service at cur‐
4164 rent runtime system instance.
4165 The monitor is triggered when the time offset is changed.
4167 This either if the time offset value is changed, or if the
4168 offset is changed from preliminary to final during finaliza‐
4169 tion of the time offset when the single time warp mode is
4170 used. When a change from preliminary to final time offset is
4171 made, the monitor is triggered once regardless of whether
4172 the time offset value was changed or not.
4173 If the runtime system is in multi time warp mode, the time
4175 offset is changed when the runtime system detects that the
4176 OS system time has changed. The runtime system does, how‐
4177 ever, not detect this immediately when it occurs. A task
4178 checking the time offset is scheduled to execute at least
4179 once a minute, so under normal operation this is to be de‐
4180 tected within a minute, but during heavy load it can take
4181 longer time.
4182 The monitor is not automatically removed after it has been
4184 triggered. That is, repeated changes of the time offset
4185 trigger the monitor repeatedly.
4186 When the monitor is triggered a 'CHANGE' message is sent to
4188 the monitoring process. A 'CHANGE' message has the following
4189 pattern:
4190 {'CHANGE', MonitorRef, Type, Item, NewTimeOffset}
4192 where MonitorRef, Type, and Item are the same as described
4194 above, and NewTimeOffset is the new time offset.
4195 When the 'CHANGE' message has been received you are guaran‐
4197 teed not to retrieve the old time offset when calling er‐
4198 lang:time_offset(). Notice that you can observe the change
4199 of the time offset when calling erlang:time_offset() before
4200 you get the 'CHANGE' message.
4201 Making several calls to monitor/2 for the same Item and/or Type
4203 is not an error; it results in as many independent monitoring
4204 instances.
4205 The monitor functionality is expected to be extended. That is,
4207 other Types and Items are expected to be supported in a future
4208 release.
4209 Note:
4211 If or when monitor/2 is extended, other possible values for Tag,
4212 Object, and Info in the monitor message will be introduced.
4213 monitor(Type :: process,
4216 Item :: monitor_process_identifier(),
4217 Opts :: [monitor_option()]) ->
4218 MonitorRef
4219 monitor(Type :: port,
4221 Item :: monitor_port_identifier(),
4222 Opts :: [monitor_option()]) ->
4223 MonitorRef
4224 monitor(Type :: time_offset,
4226 Item :: clock_service,
4227 Opts :: [monitor_option()]) ->
4228 MonitorRef
4229 Types:
4231 MonitorRef = reference()
4233 registered_name() = atom()
4234 registered_process_identifier() =
4235 registered_name() | {registered_name(), node()}
4236 monitor_process_identifier() =
4237 pid() | registered_process_identifier()
4238 monitor_port_identifier() = port() | registered_name()
4239 Provides an option list for modification of monitoring function‐
4241 ality provided by monitor/2. The Type and Item arguments have
4242 the same meaning as when passed to monitor/2. Currently avail‐
4243 able options:
4244 {alias, UnaliasOpt}:
4246 The returned monitor reference will also become an alias for
4247 the calling process. That is, the returned reference can be
4248 used for sending messages to the calling process. See also
4249 alias/0. The UnaliasOpt determines how the alias should be
4250 deactivated.
4251 explicit_unalias:
4253 Only an explicit call to unalias/1 will deactivate the
4254 alias.
4255 demonitor:
4257 The alias will be automatically deactivated when the moni‐
4258 tor is removed. This either via an explicit call to demon‐
4259 itor/1 or when it is automatically removed at the same
4260 time as a 'DOWN' message is delivered due to the monitor.
4261 The alias can also still be deactivated via a call to una‐
4262 lias/1.
4263 reply_demonitor:
4265 The alias will be automatically deactivated when the moni‐
4266 tor is removed (see demonitor option above) or a reply
4267 message sent via the alias is received. When a reply mes‐
4268 sage is received via the alias the monitor will also be
4269 automatically removed. This is useful in client/server
4270 scenarios when a client monitors the server and will get
4271 the reply via the alias. Once the response is received
4272 both the alias and the monitor will be automatically re‐
4273 moved regardless of whether the response is a reply or a
4274 'DOWN' message. The alias can also still be deactivated
4275 via a call to unalias/1. Note that if the alias is removed
4276 using the unalias/1 BIF, the monitor will still be left
4277 active.
4278 Example:
4280 server() ->
4282 receive
4283 {request, AliasReqId, Request} ->
4284 Result = perform_request(Request),
4285 AliasReqId ! {reply, AliasReqId, Result}
4286 end,
4287 server().
4288 client(ServerPid, Request) ->
4290 AliasMonReqId = monitor(process, ServerPid, [{alias, reply_demonitor}]),
4291 ServerPid ! {request, AliasMonReqId, Request},
4292 %% Alias as well as monitor will be automatically deactivated if we
4293 %% receive a reply or a 'DOWN' message since we used 'reply_demonitor'
4294 %% as unalias option...
4295 receive
4296 {reply, AliasMonReqId, Result} ->
4297 Result;
4298 {'DOWN', AliasMonReqId, process, ServerPid, ExitReason} ->
4299 error(ExitReason)
4300 end.
4301 Note that both the server and the client in this example
4304 must be executing on at least OTP 24 systems in order for
4305 this to work.
4306 For more information on process aliases see the Process
4308 Aliases section of the Erlang Reference Manual .
4309 {tag, UserDefinedTag}:
4311 Replace the default Tag with UserDefinedTag in the monitor
4312 message delivered when the monitor is triggered. For exam‐
4313 ple, when monitoring a process, the 'DOWN' tag in the down
4314 message will be replaced by UserDefinedTag.
4315 An example of how the {tag, UserDefinedTag} option can be
4317 used in order to enable the new selective receive optimiza‐
4318 tion, introduced in OTP 24, when making multiple requests to
4319 different servers:
4320 server() ->
4322 receive
4323 {request, From, ReqId, Request} ->
4324 Result = perform_request(Request),
4325 From ! {reply, self(), ReqId, Result}
4326 end,
4327 server().
4328 client(ServerPids, Request) when is_list(ServerPids) ->
4330 ReqId = make_ref(),
4331 lists:foreach(fun (ServerPid) ->
4332 _ = monitor(process, ServerPid,
4333 [{tag, {'DOWN', ReqId}}]),
4334 ServerPid ! {request, self(), ReqId, Request}
4335 end,
4336 ServerPids),
4337 receive_replies(ReqId, length(ServerPids), []).
4338 receive_replies(_ReqId, 0, Acc) ->
4340 Acc;
4341 receive_replies(ReqId, N, Acc) ->
4342 %% The compiler will detect that we match on the 'ReqId'
4343 %% reference in all clauses, and will enable the selective
4344 %% receive optimization which makes the receive able to
4345 %% skip past all messages present in the message queue at
4346 %% the time when the 'ReqId' reference was created...
4347 Res = receive
4348 {reply, ServerPid, ReqId, Result} ->
4349 %% Here we typically would have deactivated the
4350 %% monitor by a call to demonitor(Mon, [flush]) but
4351 %% we ignore this in this example for simplicity...
4352 {ok, ServerPid, Result};
4353 {{'DOWN', ReqId}, _Mon, process, ServerPid, ExitReason} ->
4354 {error, ServerPid, ExitReason}
4355 end,
4356 receive_replies(ReqId, N-1, [Res | Acc]).
4357 In order for this example to work as intended, the client
4360 must be executing on at least an OTP 24 system, but the
4361 servers may execute on older systems.
4362 monitor_node(Node, Flag) -> true
4364 Types:
4366 Node = node()
4368 Flag = boolean()
4369 Monitor the status of the node Node. If Flag is true, monitoring
4371 is turned on. If Flag is false, monitoring is turned off.
4372 Making several calls to monitor_node(Node, true) for the same
4374 Node is not an error; it results in as many independent monitor‐
4375 ing instances.
4376 If Node fails or does not exist, the message {nodedown, Node} is
4378 delivered to the process. If a process has made two calls to
4379 monitor_node(Node, true) and Node terminates, two nodedown mes‐
4380 sages are delivered to the process. If there is no connection to
4381 Node, an attempt is made to create one. If this fails, a node‐
4382 down message is delivered.
4383 The delivery of the nodedown signal is not ordered with respect
4385 to other link or monitor signals from the node that goes down.
4386 If you need a guarantee that all signals from the remote node
4387 has been delivered before the nodedown signal is sent, you
4388 should use net_kernel:monitor_nodes/1.
4389 Nodes connected through hidden connections can be monitored as
4391 any other nodes.
4392 Failure: notalive if the local node is not alive.
4394 erlang:monitor_node(Node, Flag, Options) -> true
4396 Types:
4398 Node = node()
4400 Flag = boolean()
4401 Options = [Option]
4402 Option = allow_passive_connect
4403 Behaves as monitor_node/2 except that it allows an extra option
4405 to be specified, namely allow_passive_connect. This option al‐
4406 lows the BIF to wait the normal network connection time-out for
4407 the monitored node to connect itself, even if it cannot be ac‐
4408 tively connected from this node (that is, it is blocked). The
4409 state where this can be useful can only be achieved by using the
4410 Kernel option dist_auto_connect once. If that option is not
4411 used, option allow_passive_connect has no effect.
4412 Note:
4414 Option allow_passive_connect is used internally and is seldom
4415 needed in applications where the network topology and the Kernel
4416 options in effect are known in advance.
4417 Failure: badarg if the local node is not alive or the option
4420 list is malformed.
4421 erlang:monotonic_time() -> integer()
4423 Returns the current Erlang monotonic time in native time unit.
4425 This is a monotonically increasing time since some unspecified
4426 point in time.
4427 Note:
4429 This is a monotonically increasing time, but not a strictly
4430 monotonically increasing time. That is, consecutive calls to er‐
4431 lang:monotonic_time/0 can produce the same result.
4432 Different runtime system instances will use different unspeci‐
4434 fied points in time as base for their Erlang monotonic clocks.
4435 That is, it is pointless comparing monotonic times from differ‐
4436 ent runtime system instances. Different runtime system instances
4437 can also place this unspecified point in time different relative
4438 runtime system start. It can be placed in the future (time at
4439 start is a negative value), the past (time at start is a posi‐
4440 tive value), or the runtime system start (time at start is
4441 zero). The monotonic time at runtime system start can be re‐
4442 trieved by calling erlang:system_info(start_time).
4443 erlang:monotonic_time(Unit) -> integer()
4446 Types:
4448 Unit = time_unit()
4450 Returns the current Erlang monotonic time converted into the
4452 Unit passed as argument.
4453 Same as calling erlang:convert_time_unit(erlang:mono‐
4455 tonic_time(), native, Unit), however optimized for commonly used
4456 Units.
4457 erlang:nif_error(Reason) -> no_return()
4459 Types:
4461 Reason = term()
4463 Works exactly like error/1, but Dialyzer thinks that this BIF
4465 will return an arbitrary term. When used in a stub function for
4466 a NIF to generate an exception when the NIF library is not
4467 loaded, Dialyzer does not generate false warnings.
4468 erlang:nif_error(Reason, Args) -> no_return()
4470 Types:
4472 Reason = term()
4474 Args = [term()]
4475 Works exactly like error/2, but Dialyzer thinks that this BIF
4477 will return an arbitrary term. When used in a stub function for
4478 a NIF to generate an exception when the NIF library is not
4479 loaded, Dialyzer does not generate false warnings.
4480 node() -> Node
4482 Types:
4484 Node = node()
4486 Returns the name of the local node. If the node is not alive,
4488 nonode@nohost is returned instead.
4489 Allowed in guard tests.
4491 node(Arg) -> Node
4493 Types:
4495 Arg = pid() | port() | reference()
4497 Node = node()
4498 Returns the node where Arg originates. Arg can be a process
4500 identifier, a reference, or a port. If Arg originates from the
4501 local node and the local node is not alive, nonode@nohost is re‐
4502 turned.
4503 Allowed in guard tests.
4505 nodes() -> Nodes
4507 Types:
4509 Nodes = [node()]
4511 Returns a list of all nodes connected to this node through nor‐
4513 mal connections (that is, hidden nodes are not listed). Same as
4514 nodes(visible).
4515 nodes(Arg) -> Nodes
4517 Types:
4519 Arg = NodeType | [NodeType]
4521 NodeType = visible | hidden | connected | this | known
4522 Nodes = [node()]
4523 Returns a list of nodes according to the argument specified. The
4525 returned result, when the argument is a list, is the list of
4526 nodes satisfying the disjunction(s) of the list elements.
4527 NodeTypes:
4529 visible:
4531 Nodes connected to this node through normal connections.
4532 hidden:
4534 Nodes connected to this node through hidden connections.
4535 connected:
4537 All nodes connected to this node.
4538 this:
4540 This node.
4541 known:
4543 Nodes that are known to this node. That is, connected nodes
4544 and nodes referred to by process identifiers, port identi‐
4545 fiers, and references located on this node. The set of known
4546 nodes is garbage collected. Notice that this garbage collec‐
4547 tion can be delayed. For more information, see erlang:sys‐
4548 tem_info(delayed_node_table_gc).
4549 Some equalities: [node()] = nodes(this), nodes(connected) =
4551 nodes([visible, hidden]), and nodes() = nodes(visible).
4552 nodes(Arg, InfoOpts) -> [NodeInfo]
4554 Types:
4556 NodeType = visible | hidden | connected | this | known
4558 Arg = NodeType | [NodeType]
4559 InfoOpts =
4560 #{connection_id => boolean(), node_type => boolean()}
4561 NodeTypeInfo = visible | hidden | this | known
4562 ConnectionId = undefined | integer()
4563 Info =
4564 #{connection_id => ConnectionId, node_type => NodeType‐
4565 Info}
4566 NodeInfo = {node(), Info}
4567 Returns a list of NodeInfo tuples. The first element is the node
4569 name. Nodes to be included in the list are determined by the
4570 first argument Arg in the same way as for nodes(Arg). The second
4571 element of NodeInfo tuples is a map containing further informa‐
4572 tion about the node identified by the first element. The infor‐
4573 mation present in this map is determined by the InfoOpts map
4574 passed as the second argument. Currently the following associa‐
4575 tions are allowed in the InfoOpts map:
4576 connection_id => boolean():
4578 If the value of the association equals true, the Info map in
4579 the returned result will contain the key connection_id asso‐
4580 ciated with the value ConnectionId. If ConnectionId equals
4581 undefined, the node is not connected to the node which the
4582 caller is executing on, or is the node which the caller is
4583 executing on. If ConnectionId is an integer, the node is
4584 currently connected to the node which the caller is execut‐
4585 ing on.
4586 The integer connection identifier value together with a node
4588 name identifies a specific connection instance to the node
4589 with that node name. The connection identifier value is node
4590 local. That is, on the other node the connection identifier
4591 will not be the same value. If a connection is taken down
4592 and then taken up again, the connection identifier value
4593 will change for the connection to that node. The amount of
4594 values for connection identifiers are limited, so it is pos‐
4595 sible to see the same value for different instances, but
4596 quite unlikely. It is undefined how the value change between
4597 two consecutive connection instances.
4598 node_type => boolean():
4600 If the value of the association equals true, the Info map in
4601 the returned result will contain the key node_type associ‐
4602 ated with the value NodeTypeInfo. Currently the following
4603 node types exist:
4604 visible:
4606 The node is connected to the node of the calling process
4607 through an ordinary visible connection. That is, the node
4608 name would appear in the result returned by nodes/0.
4609 hidden:
4611 The node is connected to the node of the calling process
4612 through a hidden connection. That is, the node name would
4613 not appear in the result returned by nodes/0.
4614 this:
4616 This is the node of the calling process.
4617 known:
4619 The node is not connected but known to the node of the
4620 calling process.
4621 Example:
4623 (a@localhost)1> nodes([this, connected], #{connection_id=>true, node_type=>true}).
4625 [{c@localhost,#{connection_id => 13892108,node_type => hidden}},
4626 {b@localhost,#{connection_id => 3067553,node_type => visible}},
4627 {a@localhost,#{connection_id => undefined,node_type => this}}]
4628 (a@localhost)2>
4629 now() -> Timestamp
4632 Types:
4634 Timestamp = timestamp()
4636 timestamp() =
4637 {MegaSecs :: integer() >= 0,
4638 Secs :: integer() >= 0,
4639 MicroSecs :: integer() >= 0}
4640 Warning:
4642 This function is deprecated. Do not use it.
4643 For more information, see section Time and Time Correction in
4645 the User's Guide. Specifically, section Dos and Dont's de‐
4646 scribes what to use instead of erlang:now/0.
4647 Returns the tuple {MegaSecs, Secs, MicroSecs}, which is the
4650 elapsed time since 00:00 GMT, January 1, 1970 (zero hour), if
4651 provided by the underlying OS. Otherwise some other point in
4652 time is chosen. It is also guaranteed that the following calls
4653 to this BIF return continuously increasing values. Hence, the
4654 return value from erlang:now/0 can be used to generate unique
4655 time stamps. If it is called in a tight loop on a fast machine,
4656 the time of the node can become skewed.
4657 Can only be used to check the local time of day if the time-zone
4659 information of the underlying OS is properly configured.
4660 open_port(PortName, PortSettings) -> port()
4662 Types:
4664 PortName =
4666 {spawn, Command :: string() | binary()} |
4667 {spawn_driver, Command :: string() | binary()} |
4668 {spawn_executable, FileName :: file:name_all()} |
4669 {fd, In :: integer() >= 0, Out :: integer() >= 0}
4670 PortSettings = [Opt]
4671 Opt =
4672 {packet, N :: 1 | 2 | 4} |
4673 stream |
4674 {line, L :: integer() >= 0} |
4675 {cd, Dir :: string() | binary()} |
4676 {env,
4677 Env ::
4678 [{Name :: os:env_var_name(),
4679 Val :: os:env_var_value() | false}]} |
4680 {args, [string() | binary()]} |
4681 {arg0, string() | binary()} |
4682 exit_status | use_stdio | nouse_stdio | stderr_to_stdout
4683 |
4684 in | out | binary | eof |
4685 {parallelism, Boolean :: boolean()} |
4686 hide |
4687 {busy_limits_port,
4688 {integer() >= 0, integer() >= 0} | disabled} |
4689 {busy_limits_msgq,
4690 {integer() >= 0, integer() >= 0} | disabled}
4691 Returns a port identifier as the result of opening a new Erlang
4693 port. A port can be seen as an external Erlang process.
4694 The name of the executable as well as the arguments specified in
4696 cd, env, args, and arg0 are subject to Unicode filename transla‐
4697 tion if the system is running in Unicode filename mode. To avoid
4698 translation or to force, for example UTF-8, supply the exe‐
4699 cutable and/or arguments as a binary in the correct encoding.
4700 For details, see the module file(3), the function file:na‐
4701 tive_name_encoding/0 in Kernel, and the Using Unicode in Erlang
4702 User's Guide.
4703 Note:
4705 The characters in the name (if specified as a list) can only be
4706 > 255 if the Erlang virtual machine is started in Unicode file‐
4707 name translation mode. Otherwise the name of the executable is
4708 limited to the ISO Latin-1 character set.
4709 PortNames:
4712 {spawn, Command}:
4714 Starts an external program. Command is the name of the ex‐
4715 ternal program to be run. Command runs outside the Erlang
4716 work space unless an Erlang driver with the name Command is
4717 found. If found, that driver is started. A driver runs in
4718 the Erlang work space, which means that it is linked with
4719 the Erlang runtime system.
4720 For external programs, PATH is searched (or an equivalent
4722 method is used to find programs, depending on the OS). This
4723 is done by invoking the shell on certain platforms. The
4724 first space-separated token of the command is considered as
4725 the name of the executable (or driver). This (among other
4726 things) makes this option unsuitable for running programs
4727 with spaces in filenames or directory names. If spaces in
4728 executable filenames are desired, use {spawn_executable,
4729 Command} instead.
4730 {spawn_driver, Command}:
4732 Works like {spawn, Command}, but demands the first (space-
4733 separated) token of the command to be the name of a loaded
4734 driver. If no driver with that name is loaded, a badarg er‐
4735 ror is raised.
4736 {spawn_executable, FileName}:
4738 Works like {spawn, FileName}, but only runs external exe‐
4739 cutables. FileName in its whole is used as the name of the
4740 executable, including any spaces. If arguments are to be
4741 passed, the PortSettings args and arg0 can be used.
4742 The shell is usually not invoked to start the program, it is
4744 executed directly. PATH (or equivalent) is not searched. To
4745 find a program in PATH to execute, use os:find_executable/1.
4746 Only if a shell script or .bat file is executed, the appro‐
4748 priate command interpreter is invoked implicitly, but there
4749 is still no command-argument expansion or implicit PATH
4750 search.
4751 If FileName cannot be run, an error exception is raised,
4753 with the POSIX error code as the reason. The error reason
4754 can differ between OSs. Typically the error enoent is raised
4755 when an attempt is made to run a program that is not found
4756 and eacces is raised when the specified file is not exe‐
4757 cutable.
4758 {fd, In, Out}:
4760 Allows an Erlang process to access any currently opened file
4761 descriptors used by Erlang. The file descriptor In can be
4762 used for standard input, and the file descriptor Out for
4763 standard output. It is only used for various servers in the
4764 Erlang OS (shell and user). Hence, its use is limited.
4765 PortSettings is a list of settings for the port. The valid set‐
4767 tings are as follows:
4768 {packet, N}:
4770 Messages are preceded by their length, sent in N bytes, with
4771 the most significant byte first. The valid values for N are
4772 1, 2, and 4.
4773 stream:
4775 Output messages are sent without packet lengths. A user-de‐
4776 fined protocol must be used between the Erlang process and
4777 the external object.
4778 {line, L}:
4780 Messages are delivered on a per line basis. Each line (de‐
4781 limited by the OS-dependent newline sequence) is delivered
4782 in a single message. The message data format is {Flag,
4783 Line}, where Flag is eol or noeol, and Line is the data de‐
4784 livered (without the newline sequence).
4785 L specifies the maximum line length in bytes. Lines longer
4787 than this are delivered in more than one message, with Flag
4788 set to noeol for all but the last message. If end of file is
4789 encountered anywhere else than immediately following a new‐
4790 line sequence, the last line is also delivered with Flag set
4791 to noeol. Otherwise lines are delivered with Flag set to
4792 eol.
4793 The {packet, N} and {line, L} settings are mutually exclu‐
4795 sive.
4796 {cd, Dir}:
4798 Only valid for {spawn, Command} and {spawn_executable, File‐
4799 Name}. The external program starts using Dir as its working
4800 directory. Dir must be a string.
4801 {env, Env}:
4803 Types:
4804 Name = os:env_var_name()
4805 Val = os:env_var_value() | false
4806 Env = [{Name, Val}]
4807 Only valid for {spawn, Command}, and {spawn_executable,
4809 FileName}. The environment of the started process is ex‐
4810 tended using the environment specifications in Env.
4811 Env is to be a list of tuples {Name, Val}, where Name is the
4813 name of an environment variable, and Val is the value it is
4814 to have in the spawned port process. Both Name and Val must
4815 be strings. The one exception is Val being the atom false
4816 (in analogy with os:getenv/1, which removes the environment
4817 variable.
4818 For information about encoding requirements, see documenta‐
4820 tion of the types for Name and Val.
4821 {args, [ string() | binary() ]}:
4823 Only valid for {spawn_executable, FileName} and specifies
4824 arguments to the executable. Each argument is specified as a
4825 separate string and (on Unix) eventually ends up as one ele‐
4826 ment each in the argument vector. On other platforms, a sim‐
4827 ilar behavior is mimicked.
4828 The arguments are not expanded by the shell before they are
4830 supplied to the executable. Most notably this means that
4831 file wildcard expansion does not occur. To expand wildcards
4832 for the arguments, use filelib:wildcard/1. Notice that even
4833 if the program is a Unix shell script, meaning that the
4834 shell ultimately is invoked, wildcard expansion does not oc‐
4835 cur, and the script is provided with the untouched argu‐
4836 ments. On Windows, wildcard expansion is always up to the
4837 program itself, therefore this is not an issue.
4838 The executable name (also known as argv[0]) is not to be
4840 specified in this list. The proper executable name is auto‐
4841 matically used as argv[0], where applicable.
4842 If you explicitly want to set the program name in the argu‐
4844 ment vector, option arg0 can be used.
4845 {arg0, string() | binary()}:
4847 Only valid for {spawn_executable, FileName} and explicitly
4848 specifies the program name argument when running an exe‐
4849 cutable. This can in some circumstances, on some OSs, be de‐
4850 sirable. How the program responds to this is highly system-
4851 dependent and no specific effect is guaranteed.
4852 exit_status:
4854 Only valid for {spawn, Command}, where Command refers to an
4855 external program, and for {spawn_executable, FileName}.
4856 When the external process connected to the port exits, a
4858 message of the form {Port,{exit_status,Status}} is sent to
4859 the connected process, where Status is the exit status of
4860 the external process. If the program aborts on Unix, the
4861 same convention is used as the shells do (that is, 128+sig‐
4862 nal).
4863 If option eof is specified also, the messages eof and
4865 exit_status appear in an unspecified order.
4866 If the port program closes its stdout without exiting, op‐
4868 tion exit_status does not work.
4869 use_stdio:
4871 Only valid for {spawn, Command} and {spawn_executable, File‐
4872 Name}. It allows the standard input and output (file de‐
4873 scriptors 0 and 1) of the spawned (Unix) process for commu‐
4874 nication with Erlang.
4875 nouse_stdio:
4877 The opposite of use_stdio. It uses file descriptors 3 and 4
4878 for communication with Erlang.
4879 stderr_to_stdout:
4881 Affects ports to external programs. The executed program
4882 gets its standard error file redirected to its standard out‐
4883 put file. stderr_to_stdout and nouse_stdio are mutually ex‐
4884 clusive.
4885 overlapped_io:
4887 Affects ports to external programs on Windows only. The
4888 standard input and standard output handles of the port pro‐
4889 gram are, if this option is supplied, opened with flag
4890 FILE_FLAG_OVERLAPPED, so that the port program can (and
4891 must) do overlapped I/O on its standard handles. This is not
4892 normally the case for simple port programs, but an option of
4893 value for the experienced Windows programmer. On all other
4894 platforms, this option is silently discarded.
4895 in:
4897 The port can only be used for input.
4898 out:
4900 The port can only be used for output.
4901 binary:
4903 All I/O from the port is binary data objects as opposed to
4904 lists of bytes.
4905 eof:
4907 The port is not closed at the end of the file and does not
4908 produce an exit signal. Instead, it remains open and a
4909 {Port, eof} message is sent to the process holding the port.
4910 hide:
4912 When running on Windows, suppresses creation of a new con‐
4913 sole window when spawning the port program. (This option has
4914 no effect on other platforms.)
4915 {parallelism, Boolean}:
4917 Sets scheduler hint for port parallelism. If set to true,
4920 the virtual machine schedules port tasks; when doing so, it
4921 improves parallelism in the system. If set to false, the
4922 virtual machine tries to perform port tasks immediately, im‐
4923 proving latency at the expense of parallelism. The default
4924 can be set at system startup by passing command-line argu‐
4925 ment +spp to erl(1).
4926 {busy_limits_port, {Low, High} | disabled}:
4928 Sets limits that will be used for controlling the busy state
4929 of the port.
4930 When the ports internal output queue size becomes larger
4932 than or equal to High bytes, it enters the busy state. When
4933 it becomes less than Low bytes it leaves the busy state.
4934 When the port is in the busy state, processes sending com‐
4935 mands to it will be suspended until the port leaves the busy
4936 state. Commands are in this context either Port ! {Owner,
4937 {command, Data}} or port_command/[2,3].
4938 The Low limit is automatically adjusted to the same as High
4940 if it is set larger then High. Valid range of values for Low
4941 and High is [1, (1 bsl (8*erlang:system_info(wordsize)))-2].
4942 If the atom disabled is passed, the port will never enter
4943 the busy state.
4944 The defaults are Low = 4096 and High = 8192.
4946 Note that this option is only valid when spawning an exe‐
4948 cutable (port program) by opening the spawn driver and when
4949 opening the fd driver. This option will cause a failure with
4950 a badarg exception when opening other drivers.
4951 {busy_limits_msgq, {Low, High} | disabled}:
4953 Sets limits that will be used for controlling the busy state
4954 of the port message queue.
4955 When the ports message queue size becomes larger than or
4957 equal to High bytes it enters the busy state. When it be‐
4958 comes less than Low bytes it leaves the busy state. When the
4959 port message queue is in the busy state, processes sending
4960 commands to it will be suspended until the port message
4961 queue leaves the busy state. Commands are in this context
4962 either Port ! {Owner, {command, Data}} or port_com‐
4963 mand/[2,3].
4964 The Low limit is automatically adjusted to the same as High
4966 if it is set larger then High. Valid range of values for Low
4967 and High is [1, (1 bsl (8*erlang:system_info(wordsize)))-2].
4968 If the atom disabled is passed, the port message queue will
4969 never enter the busy state.
4970 Note that if the driver statically has disabled the use of
4972 this feature, a failure with a badarg exception will be
4973 raised unless this option also is set to disable or not
4974 passed at all.
4975 The defaults are Low = 4096 and High = 8192 unless the
4977 driver itself does modifications of these values.
4978 Note that the driver might fail if it also adjust these lim‐
4980 its by itself and you have disabled this feature.
4981 The spawn driver (used when spawning an executable) and the
4983 fd driver do not disable this feature and do not adjust
4984 these limits by themselves.
4985 For more information see the documentation
4987 erl_drv_busy_msgq_limits().
4988 Default is stream for all port types and use_stdio for spawned
4990 ports.
4991 Failure: if the port cannot be opened, the exit reason is
4993 badarg, system_limit, or the POSIX error code that most closely
4994 describes the error, or einval if no POSIX code is appropriate:
4995 badarg:
4997 Bad input arguments to open_port.
4998 system_limit:
5000 All available ports in the Erlang emulator are in use.
5001 enomem:
5003 Not enough memory to create the port.
5004 eagain:
5006 No more available OS processes.
5007 enametoolong:
5009 Too long external command.
5010 emfile:
5012 No more available file descriptors (for the OS process that
5013 the Erlang emulator runs in).
5014 enfile:
5016 Full file table (for the entire OS).
5017 eacces:
5019 Command specified in {spawn_executable, Command} does not
5020 point out an executable file.
5021 enoent:
5023 FileName specified in {spawn_executable, FileName} does not
5024 point out an existing file.
5025 During use of a port opened using {spawn, Name}, {spawn_driver,
5027 Name}, or {spawn_executable, Name}, errors arising when sending
5028 messages to it are reported to the owning process using signals
5029 of the form {'EXIT', Port, PosixCode}. For the possible values
5030 of PosixCode, see file(3).
5031 The maximum number of ports that can be open at the same time
5033 can be configured by passing command-line flag +Q to erl(1).
5034 erlang:phash(Term, Range) -> Hash
5036 Types:
5038 Term = term()
5040 Range = Hash = integer() >= 1
5041 Range = 1..2^32, Hash = 1..Range
5042 Warning:
5044 This function is deprecated as erlang:phash2/2 should be used
5045 for new code. Note that erlang:phash(X,N) is not necessary equal
5046 to erlang:phash2(X,N)
5047 Portable hash function that gives the same hash for the same Er‐
5050 lang term regardless of machine architecture and ERTS version
5051 (the BIF was introduced in ERTS 4.9.1.1). The function returns a
5052 hash value for Term within the range 1..Range. The maximum value
5053 for Range is 2^32.
5054 erlang:phash2(Term) -> Hash
5056 erlang:phash2(Term, Range) -> Hash
5058 Types:
5060 Term = term()
5062 Range = integer() >= 1
5063 1..2^32
5064 Hash = integer() >= 0
5065 0..Range-1
5066 Portable hash function that gives the same hash for the same Er‐
5068 lang term regardless of machine architecture and ERTS version
5069 (the BIF was introduced in ERTS 5.2). The function returns a
5070 hash value for Term within the range 0..Range-1. The maximum
5071 value for Range is 2^32. When without argument Range, a value in
5072 the range 0..2^27-1 is returned.
5073 This BIF is always to be used for hashing terms. It distributes
5075 small integers better than phash/2, and it is faster for bignums
5076 and binaries.
5077 Notice that the range 0..Range-1 is different from the range of
5079 phash/2, which is 1..Range.
5080 pid_to_list(Pid) -> string()
5082 Types:
5084 Pid = pid()
5086 Returns a string corresponding to the text representation of
5088 Pid. Example:
5089 > erlang:pid_to_list(self()).
5091 "<0.85.0>"
5092 Note:
5094 The creation for the node is not included in the list represen‐
5095 tation of Pid. This means that processes in different incarna‐
5096 tions of a node with a specific name can get the same list rep‐
5097 resentation.
5098 erlang:port_call(Port, Operation, Data) -> term()
5101 Types:
5103 Port = port() | atom()
5105 Operation = integer()
5106 Data = term()
5107 Performs a synchronous call to a port. The meaning of Operation
5109 and Data depends on the port, that is, on the port driver. Not
5110 all port drivers support this feature.
5111 Port is a port identifier, referring to a driver.
5113 Operation is an integer, which is passed on to the driver.
5115 Data is any Erlang term. This data is converted to binary term
5117 format and sent to the port.
5118 Returns a term from the driver. The meaning of the returned data
5120 also depends on the port driver.
5121 Failures:
5123 badarg:
5125 If Port is not an identifier of an open port, or the regis‐
5126 tered name of an open port. If the calling process was pre‐
5127 viously linked to the closed port, identified by Port, the
5128 exit signal from the port is guaranteed to be delivered be‐
5129 fore this badarg exception occurs.
5130 badarg:
5132 If Operation does not fit in a 32-bit integer.
5133 badarg:
5135 If the port driver does not support synchronous control op‐
5136 erations.
5137 badarg:
5139 If the port driver so decides for any reason (probably some‐
5140 thing wrong with Operation or Data).
5141 Warning:
5143 Do not call port_call with an unknown Port identifier and ex‐
5144 pect badarg exception. Any undefined behavior is possible (in‐
5145 cluding node crash) depending on how the port driver inter‐
5146 prets the supplied arguments.
5147 port_close(Port) -> true
5150 Types:
5152 Port = port() | atom()
5154 Closes an open port. Roughly the same as Port ! {self(), close}
5156 except for the error behavior (see below), being synchronous,
5157 and that the port does not reply with {Port, closed}. Any
5158 process can close a port with port_close/1, not only the port
5159 owner (the connected process). If the calling process is linked
5160 to the port identified by Port, the exit signal from the port is
5161 guaranteed to be delivered before port_close/1 returns.
5162 For comparison: Port ! {self(), close} only fails with badarg if
5164 Port does not refer to a port or a process. If Port is a closed
5165 port, nothing happens. If Port is an open port and the calling
5166 process is the port owner, the port replies with {Port, closed}
5167 when all buffers have been flushed and the port really closes.
5168 If the calling process is not the port owner, the port owner
5169 fails with badsig.
5170 Notice that any process can close a port using Port ! {Por‐
5172 tOwner, close} as if it itself was the port owner, but the reply
5173 always goes to the port owner.
5174 As from Erlang/OTP R16, Port ! {PortOwner, close} is truly asyn‐
5176 chronous. Notice that this operation has always been documented
5177 as an asynchronous operation, while the underlying implementa‐
5178 tion has been synchronous. port_close/1 is however still fully
5179 synchronous because of its error behavior.
5180 Failure: badarg if Port is not an identifier of an open port, or
5182 the registered name of an open port. If the calling process was
5183 previously linked to the closed port, identified by Port, the
5184 exit signal from the port is guaranteed to be delivered before
5185 this badarg exception occurs.
5186 port_command(Port, Data) -> true
5188 Types:
5190 Port = port() | atom()
5192 Data = iodata()
5193 Sends data to a port. Same as Port ! {PortOwner, {command,
5195 Data}} except for the error behavior and being synchronous (see
5196 below). Any process can send data to a port with port_command/2,
5197 not only the port owner (the connected process).
5198 For comparison: Port ! {PortOwner, {command, Data}} only fails
5200 with badarg if Port does not refer to a port or a process. If
5201 Port is a closed port, the data message disappears without a
5202 sound. If Port is open and the calling process is not the port
5203 owner, the port owner fails with badsig. The port owner fails
5204 with badsig also if Data is an invalid I/O list.
5205 Notice that any process can send to a port using Port ! {Por‐
5207 tOwner, {command, Data}} as if it itself was the port owner.
5208 If the port is busy, the calling process is suspended until the
5210 port is not busy any more.
5211 As from Erlang/OTP R16, Port ! {PortOwner, {command, Data}} is
5213 truly asynchronous. Notice that this operation has always been
5214 documented as an asynchronous operation, while the underlying
5215 implementation has been synchronous. port_command/2 is however
5216 still fully synchronous because of its error behavior.
5217 Failures:
5219 badarg:
5221 If Port is not an identifier of an open port, or the regis‐
5222 tered name of an open port. If the calling process was pre‐
5223 viously linked to the closed port, identified by Port, the
5224 exit signal from the port is guaranteed to be delivered be‐
5225 fore this badarg exception occurs.
5226 badarg:
5228 If Data is an invalid I/O list.
5229 Warning:
5231 Do not send data to an unknown port. Any undefined behavior is
5232 possible (including node crash) depending on how the port driver
5233 interprets the data.
5234 port_command(Port, Data, OptionList) -> boolean()
5237 Types:
5239 Port = port() | atom()
5241 Data = iodata()
5242 Option = force | nosuspend
5243 OptionList = [Option]
5244 Sends data to a port. port_command(Port, Data, []) equals
5246 port_command(Port, Data).
5247 If the port command is aborted, false is returned, otherwise
5249 true.
5250 If the port is busy, the calling process is suspended until the
5252 port is not busy anymore.
5253 Options:
5255 force:
5257 The calling process is not suspended if the port is busy,
5258 instead the port command is forced through. The call fails
5259 with a notsup exception if the driver of the port does not
5260 support this. For more information, see driver flag
5261 ERL_DRV_FLAG_SOFT_BUSY.
5262 nosuspend:
5264 The calling process is not suspended if the port is busy,
5265 instead the port command is aborted and false is returned.
5266 Note:
5268 More options can be added in a future release.
5269 Failures:
5272 badarg:
5274 If Port is not an identifier of an open port, or the regis‐
5275 tered name of an open port. If the calling process was pre‐
5276 viously linked to the closed port, identified by Port, the
5277 exit signal from the port is guaranteed to be delivered be‐
5278 fore this badarg exception occurs.
5279 badarg:
5281 If Data is an invalid I/O list.
5282 badarg:
5284 If OptionList is an invalid option list.
5285 notsup:
5287 If option force has been passed, but the driver of the port
5288 does not allow forcing through a busy port.
5289 Warning:
5291 Do not send data to an unknown port. Any undefined behavior is
5292 possible (including node crash) depending on how the port driver
5293 interprets the data.
5294 port_connect(Port, Pid) -> true
5297 Types:
5299 Port = port() | atom()
5301 Pid = pid()
5302 Sets the port owner (the connected port) to Pid. Roughly the
5304 same as Port ! {Owner, {connect, Pid}} except for the following:
5305 * The error behavior differs, see below.
5307 * The port does not reply with {Port,connected}.
5309 * port_connect/1 is synchronous, see below.
5311 * The new port owner gets linked to the port.
5313 The old port owner stays linked to the port and must call un‐
5315 link(Port) if this is not desired. Any process can set the port
5316 owner to be any process with port_connect/2.
5317 For comparison: Port ! {self(), {connect, Pid}} only fails with
5319 badarg if Port does not refer to a port or a process. If Port is
5320 a closed port, nothing happens. If Port is an open port and the
5321 calling process is the port owner, the port replies with {Port,
5322 connected} to the old port owner. Notice that the old port owner
5323 is still linked to the port, while the new is not. If Port is an
5324 open port and the calling process is not the port owner, the
5325 port owner fails with badsig. The port owner fails with badsig
5326 also if Pid is not an existing local process identifier.
5327 Notice that any process can set the port owner using Port !
5329 {PortOwner, {connect, Pid}} as if it itself was the port owner,
5330 but the reply always goes to the port owner.
5331 As from Erlang/OTP R16, Port ! {PortOwner, {connect, Pid}} is
5333 truly asynchronous. Notice that this operation has always been
5334 documented as an asynchronous operation, while the underlying
5335 implementation has been synchronous. port_connect/2 is however
5336 still fully synchronous because of its error behavior.
5337 Failures:
5339 badarg:
5341 If Port is not an identifier of an open port, or the regis‐
5342 tered name of an open port. If the calling process was pre‐
5343 viously linked to the closed port, identified by Port, the
5344 exit signal from the port is guaranteed to be delivered be‐
5345 fore this badarg exception occurs.
5346 badarg:
5348 If the process identified by Pid is not an existing local
5349 process.
5350 port_control(Port, Operation, Data) -> iodata() | binary()
5352 Types:
5354 Port = port() | atom()
5356 Operation = integer()
5357 Data = iodata()
5358 Performs a synchronous control operation on a port. The meaning
5360 of Operation and Data depends on the port, that is, on the port
5361 driver. Not all port drivers support this control feature.
5362 Returns a list of integers in the range 0..255, or a binary, de‐
5364 pending on the port driver. The meaning of the returned data
5365 also depends on the port driver.
5366 Failures:
5368 badarg:
5370 If Port is not an open port or the registered name of an
5371 open port.
5372 badarg:
5374 If Operation cannot fit in a 32-bit integer.
5375 badarg:
5377 If the port driver does not support synchronous control op‐
5378 erations.
5379 badarg:
5381 If the port driver so decides for any reason (probably
5382 something wrong with Operation or Data).
5383 Warning:
5385 Do not call port_control/3 with an unknown Port identifier and
5386 expect badarg exception. Any undefined behavior is possible
5387 (including node crash) depending on how the port driver inter‐
5388 prets the supplied arguments.
5389 erlang:port_info(Port) -> Result
5392 Types:
5394 Port = port() | atom()
5396 ResultItem =
5397 {registered_name, RegisteredName :: atom()} |
5398 {id, Index :: integer() >= 0} |
5399 {connected, Pid :: pid()} |
5400 {links, Pids :: [pid()]} |
5401 {name, String :: string()} |
5402 {input, Bytes :: integer() >= 0} |
5403 {output, Bytes :: integer() >= 0} |
5404 {os_pid, OsPid :: integer() >= 0 | undefined}
5405 Result = [ResultItem] | undefined
5406 Returns a list containing tuples with information about Port, or
5408 undefined if the port is not open. The order of the tuples is
5409 undefined, and all the tuples are not mandatory. If the port is
5410 closed and the calling process was previously linked to the
5411 port, the exit signal from the port is guaranteed to be deliv‐
5412 ered before port_info/1 returns undefined.
5413 The result contains information about the following Items:
5415 * registered_name (if the port has a registered name)
5417 * id
5419 * connected
5421 * links
5423 * name
5425 * input
5427 * output
5429 For more information about the different Items, see port_info/2.
5431 Failure: badarg if Port is not a local port identifier, or an
5433 atom.
5434 erlang:port_info(Port, Item :: connected) ->
5436 {connected, Pid} | undefined
5437 Types:
5439 Port = port() | atom()
5441 Pid = pid()
5442 Pid is the process identifier of the process connected to the
5444 port.
5445 If the port identified by Port is not open, undefined is re‐
5447 turned. If the port is closed and the calling process was previ‐
5448 ously linked to the port, the exit signal from the port is guar‐
5449 anteed to be delivered before port_info/2 returns undefined.
5450 Failure: badarg if Port is not a local port identifier, or an
5452 atom.
5453 erlang:port_info(Port, Item :: id) -> {id, Index} | undefined
5455 Types:
5457 Port = port() | atom()
5459 Index = integer() >= 0
5460 Index is the internal index of the port. This index can be used
5462 to separate ports.
5463 If the port identified by Port is not open, undefined is re‐
5465 turned. If the port is closed and the calling process was previ‐
5466 ously linked to the port, the exit signal from the port is guar‐
5467 anteed to be delivered before port_info/2 returns undefined.
5468 Failure: badarg if Port is not a local port identifier, or an
5470 atom.
5471 erlang:port_info(Port, Item :: input) ->
5473 {input, Bytes} | undefined
5474 Types:
5476 Port = port() | atom()
5478 Bytes = integer() >= 0
5479 Bytes is the total number of bytes read from the port.
5481 If the port identified by Port is not open, undefined is re‐
5483 turned. If the port is closed and the calling process was previ‐
5484 ously linked to the port, the exit signal from the port is guar‐
5485 anteed to be delivered before port_info/2 returns undefined.
5486 Failure: badarg if Port is not a local port identifier, or an
5488 atom.
5489 erlang:port_info(Port, Item :: links) -> {links, Pids} | undefined
5491 Types:
5493 Port = port() | atom()
5495 Pids = [pid()]
5496 Pids is a list of the process identifiers of the processes that
5498 the port is linked to.
5499 If the port identified by Port is not open, undefined is re‐
5501 turned. If the port is closed and the calling process was previ‐
5502 ously linked to the port, the exit signal from the port is guar‐
5503 anteed to be delivered before port_info/2 returns undefined.
5504 Failure: badarg if Port is not a local port identifier, or an
5506 atom.
5507 erlang:port_info(Port, Item :: locking) ->
5509 {locking, Locking} | undefined
5510 Types:
5512 Port = port() | atom()
5514 Locking = false | port_level | driver_level
5515 Locking is one of the following:
5517 * port_level (port-specific locking)
5519 * driver_level (driver-specific locking)
5521 Notice that these results are highly implementation-specific and
5523 can change in a future release.
5524 If the port identified by Port is not open, undefined is re‐
5526 turned. If the port is closed and the calling process was previ‐
5527 ously linked to the port, the exit signal from the port is guar‐
5528 anteed to be delivered before port_info/2 returns undefined.
5529 Failure: badarg if Port is not a local port identifier, or an
5531 atom.
5532 erlang:port_info(Port, Item :: memory) ->
5534 {memory, Bytes} | undefined
5535 Types:
5537 Port = port() | atom()
5539 Bytes = integer() >= 0
5540 Bytes is the total number of bytes allocated for this port by
5542 the runtime system. The port itself can have allocated memory
5543 that is not included in Bytes.
5544 If the port identified by Port is not open, undefined is re‐
5546 turned. If the port is closed and the calling process was previ‐
5547 ously linked to the port, the exit signal from the port is guar‐
5548 anteed to be delivered before port_info/2 returns undefined.
5549 Failure: badarg if Port is not a local port identifier, or an
5551 atom.
5552 erlang:port_info(Port, Item :: monitors) ->
5554 {monitors, Monitors} | undefined
5555 Types:
5557 Port = port() | atom()
5559 Monitors = [{process, pid()}]
5560 Monitors represent processes monitored by this port.
5562 If the port identified by Port is not open, undefined is re‐
5564 turned. If the port is closed and the calling process was previ‐
5565 ously linked to the port, the exit signal from the port is guar‐
5566 anteed to be delivered before port_info/2 returns undefined.
5567 Failure: badarg if Port is not a local port identifier, or an
5569 atom.
5570 erlang:port_info(Port, Item :: monitored_by) ->
5572 {monitored_by, MonitoredBy} | undefined
5573 Types:
5575 Port = port() | atom()
5577 MonitoredBy = [pid()]
5578 Returns list of pids that are monitoring given port at the mo‐
5580 ment.
5581 If the port identified by Port is not open, undefined is re‐
5583 turned. If the port is closed and the calling process was previ‐
5584 ously linked to the port, the exit signal from the port is guar‐
5585 anteed to be delivered before port_info/2 returns undefined.
5586 Failure: badarg if Port is not a local port identifier, or an
5588 atom.
5589 erlang:port_info(Port, Item :: name) -> {name, Name} | undefined
5591 Types:
5593 Port = port() | atom()
5595 Name = string()
5596 Name is the command name set by open_port/2.
5598 If the port identified by Port is not open, undefined is re‐
5600 turned. If the port is closed and the calling process was previ‐
5601 ously linked to the port, the exit signal from the port is guar‐
5602 anteed to be delivered before port_info/2 returns undefined.
5603 Failure: badarg if Port is not a local port identifier, or an
5605 atom.
5606 erlang:port_info(Port, Item :: os_pid) ->
5608 {os_pid, OsPid} | undefined
5609 Types:
5611 Port = port() | atom()
5613 OsPid = integer() >= 0 | undefined
5614 OsPid is the process identifier (or equivalent) of an OS process
5616 created with open_port({spawn | spawn_executable, Command}, Op‐
5617 tions). If the port is not the result of spawning an OS process,
5618 the value is undefined.
5619 If the port identified by Port is not open, undefined is re‐
5621 turned. If the port is closed and the calling process was previ‐
5622 ously linked to the port, the exit signal from the port is guar‐
5623 anteed to be delivered before port_info/2 returns undefined.
5624 Failure: badarg if Port is not a local port identifier, or an
5626 atom.
5627 erlang:port_info(Port, Item :: output) ->
5629 {output, Bytes} | undefined
5630 Types:
5632 Port = port() | atom()
5634 Bytes = integer() >= 0
5635 Bytes is the total number of bytes written to the port from Er‐
5637 lang processes using port_command/2, port_command/3, or Port !
5638 {Owner, {command, Data}.
5639 If the port identified by Port is not open, undefined is re‐
5641 turned. If the port is closed and the calling process was previ‐
5642 ously linked to the port, the exit signal from the port is guar‐
5643 anteed to be delivered before port_info/2 returns undefined.
5644 Failure: badarg if Port is not a local port identifier, or an
5646 atom.
5647 erlang:port_info(Port, Item :: parallelism) ->
5649 {parallelism, Boolean} | undefined
5650 Types:
5652 Port = port() | atom()
5654 Boolean = boolean()
5655 Boolean corresponds to the port parallelism hint used by this
5657 port. For more information, see option parallelism of
5658 open_port/2.
5659 erlang:port_info(Port, Item :: queue_size) ->
5661 {queue_size, Bytes} | undefined
5662 Types:
5664 Port = port() | atom()
5666 Bytes = integer() >= 0
5667 Bytes is the total number of bytes queued by the port using the
5669 ERTS driver queue implementation.
5670 If the port identified by Port is not open, undefined is re‐
5672 turned. If the port is closed and the calling process was previ‐
5673 ously linked to the port, the exit signal from the port is guar‐
5674 anteed to be delivered before port_info/2 returns undefined.
5675 Failure: badarg if Port is not a local port identifier, or an
5677 atom.
5678 erlang:port_info(Port, Item :: registered_name) ->
5680 {registered_name, RegisteredName} |
5681 [] | undefined
5682 Types:
5684 Port = port() | atom()
5686 RegisteredName = atom()
5687 RegisteredName is the registered name of the port. If the port
5689 has no registered name, [] is returned.
5690 If the port identified by Port is not open, undefined is re‐
5692 turned. If the port is closed and the calling process was previ‐
5693 ously linked to the port, the exit signal from the port is guar‐
5694 anteed to be delivered before port_info/2 returns undefined.
5695 Failure: badarg if Port is not a local port identifier, or an
5697 atom.
5698 port_to_list(Port) -> string()
5700 Types:
5702 Port = port()
5704 Returns a string corresponding to the text representation of the
5706 port identifier Port.
5707 erlang:ports() -> [port()]
5709 Returns a list of port identifiers corresponding to all the
5711 ports existing on the local node.
5712 Notice that an exiting port exists, but is not open.
5714 pre_loaded() -> [module()]
5716 Returns a list of Erlang modules that are preloaded in the run-
5718 time system. Pre-loaded modules are Erlang modules that are
5719 needed to bootstrap the system to load the first Erlang modules
5720 from either disk or by using erl_boot_server.
5721 erlang:process_display(Pid, Type) -> true
5723 Types:
5725 Pid = pid()
5727 Type = backtrace
5728 Writes information about the local process Pid on standard er‐
5730 ror. The only allowed value for the atom Type is backtrace,
5731 which shows the contents of the call stack, including informa‐
5732 tion about the call chain, with the current function printed
5733 first. The format of the output is not further defined.
5734 process_flag(Flag :: async_dist, Boolean) -> OldBoolean
5736 Types:
5738 Boolean = OldBoolean = boolean()
5740 Enable or disable fully asynchronous distributed signaling for
5742 the calling process. When disabled, which is the default, the
5743 process sending a distributed signal will block in the send op‐
5744 eration if the buffer for the distribution channel reach the
5745 distribution buffer busy limit. The process will remain blocked
5746 until the buffer shrinks enough. This might in some cases take a
5747 substantial amount of time. When async_dist is enabled, send op‐
5748 erations of distributed signals will always buffer the signal on
5749 the outgoing distribution channel and then immediately return.
5750 That is, these send operations will never block the sending
5751 process.
5752 Note:
5754 Since no flow control is enforced by the runtime system when
5755 async_dist process flag is enabled, you need to make sure that
5756 flow control for such data is implemented, or that the amount of
5757 such data is known to always be limited. Unlimited signaling
5758 with async_dist enabled in the absence of flow control will typ‐
5759 ically cause the sending runtime system to crash on an out of
5760 memory condition.
5761 Blocking due to disabled async_dist can be monitored by er‐
5764 lang:system_montor() using the busy_dist_port option. Only data
5765 buffered by processes which (at the time of sending a signal)
5766 have disabled async_dist will be counted when determining
5767 whether or not an operation should block the caller.
5768 The async_dist flag can also be set on a new process when spawn‐
5770 ing it using the spawn_opt() BIF with the option {async_dist,
5771 Enable}. The default async_dist flag to use on newly spawned
5772 processes can be set by passing the command line argument +pad
5773 <boolean> when starting the runtime system. If the +pad <bool‐
5774 ean> command line argument is not passed, the default value of
5775 the async_dist flag will be false.
5776 You can inspect the state of the async_dist process flag of a
5778 process by calling process_info(Pid, async_dist).
5779 Returns the old value of the async_dist flag.
5781 process_flag(Flag :: trap_exit, Boolean) -> OldBoolean
5783 Types:
5785 Boolean = OldBoolean = boolean()
5787 When trap_exit is set to true, exit signals arriving to a
5789 process are converted to {'EXIT', From, Reason} messages, which
5790 can be received as ordinary messages. If trap_exit is set to
5791 false, the process exits if it receives an exit signal other
5792 than normal and the exit signal is propagated to its linked pro‐
5793 cesses. Application processes are normally not to trap exits.
5794 Returns the old value of the flag.
5796 See also exit/2.
5798 process_flag(Flag :: error_handler, Module) -> OldModule
5800 Types:
5802 Module = OldModule = atom()
5804 Used by a process to redefine the error handler for undefined
5806 function calls and undefined registered processes. Inexperienced
5807 users are not to use this flag, as code auto-loading depends on
5808 the correct operation of the error handling module.
5809 Returns the old value of the flag.
5811 process_flag(Flag :: fullsweep_after, FullsweepAfter) ->
5813 OldFullsweepAfter
5814 Types:
5816 FullsweepAfter = OldFullsweepAfter = integer() >= 0
5818 Changes the maximum number of generational collections before
5820 forcing a fullsweep for the calling process.
5821 Returns the old value of the flag.
5823 process_flag(Flag :: min_heap_size, MinHeapSize) -> OldMinHeapSize
5825 Types:
5827 MinHeapSize = OldMinHeapSize = integer() >= 0
5829 Changes the minimum heap size for the calling process.
5831 Returns the old value of the flag.
5833 process_flag(Flag :: min_bin_vheap_size, MinBinVHeapSize) ->
5835 OldMinBinVHeapSize
5836 Types:
5838 MinBinVHeapSize = OldMinBinVHeapSize = integer() >= 0
5840 Changes the minimum binary virtual heap size for the calling
5842 process.
5843 Returns the old value of the flag.
5845 process_flag(Flag :: max_heap_size, MaxHeapSize) -> OldMaxHeapSize
5847 Types:
5849 MaxHeapSize = OldMaxHeapSize = max_heap_size()
5851 max_heap_size() =
5852 integer() >= 0 |
5853 #{size => integer() >= 0,
5854 kill => boolean(),
5855 error_logger => boolean()}
5856 This flag sets the maximum heap size for the calling process. If
5858 MaxHeapSize is an integer, the system default values for kill
5859 and error_logger are used.
5860 For details on how the heap grows, see Sizing the heap in the
5862 ERTS internal documentation.
5863 size:
5865 The maximum size in words of the process. If set to zero,
5866 the heap size limit is disabled. badarg is be thrown if the
5867 value is smaller than min_heap_size. The size check is only
5868 done when a garbage collection is triggered.
5869 size is the entire heap of the process when garbage collec‐
5871 tion is triggered. This includes all generational heaps, the
5872 process stack, any messages that are considered to be part
5873 of the heap, and any extra memory that the garbage collector
5874 needs during collection.
5875 size is the same as can be retrieved using er‐
5877 lang:process_info(Pid, total_heap_size), or by adding
5878 heap_block_size, old_heap_block_size and mbuf_size from er‐
5879 lang:process_info(Pid, garbage_collection_info).
5880 kill:
5882 When set to true, the runtime system sends an untrappable
5883 exit signal with reason kill to the process if the maximum
5884 heap size is reached. The garbage collection that triggered
5885 the kill is not completed, instead the process exits as soon
5886 as possible. When set to false, no exit signal is sent to
5887 the process, instead it continues executing.
5888 If kill is not defined in the map, the system default will
5890 be used. The default system default is true. It can be
5891 changed by either option +hmaxk in erl(1), or erlang:sys‐
5892 tem_flag(max_heap_size, MaxHeapSize).
5893 error_logger:
5895 When set to true, the runtime system logs an error event via
5896 logger, containing details about the process when the maxi‐
5897 mum heap size is reached. One log event is sent each time
5898 the limit is reached.
5899 If error_logger is not defined in the map, the system de‐
5901 fault is used. The default system default is true. It can be
5902 changed by either the option +hmaxel int erl(1), or er‐
5903 lang:system_flag(max_heap_size, MaxHeapSize).
5904 The heap size of a process is quite hard to predict, especially
5906 the amount of memory that is used during the garbage collection.
5907 When contemplating using this option, it is recommended to first
5908 run it in production with kill set to false and inspect the log
5909 events to see what the normal peak sizes of the processes in the
5910 system is and then tune the value accordingly.
5911 process_flag(Flag :: message_queue_data, MQD) -> OldMQD
5913 Types:
5915 MQD = OldMQD = message_queue_data()
5917 message_queue_data() = off_heap | on_heap
5918 Determines how messages in the message queue are stored, as fol‐
5920 lows:
5921 off_heap:
5923 All messages in the message queue will be stored outside the
5924 process heap. This implies that no messages in the message
5925 queue will be part of a garbage collection of the process.
5926 on_heap:
5928 All messages in the message queue will eventually be placed
5929 on the process heap. They can, however, be temporarily
5930 stored off the heap. This is how messages have always been
5931 stored up until ERTS 8.0.
5932 The default value of the message_queue_data process flag is de‐
5934 termined by the command-line argument +hmqd in erl(1).
5935 If the process may potentially accumulate a large number of mes‐
5937 sages in its queue it is recommended to set the flag value to
5938 off_heap. This is due to the fact that the garbage collection of
5939 a process that has a large number of messages stored on the heap
5940 can become extremely expensive and the process can consume large
5941 amounts of memory. The performance of the actual message passing
5942 is, however, generally better when the flag value is on_heap.
5943 Changing the flag value causes any existing messages to be
5945 moved. The move operation is initiated, but not necessarily com‐
5946 pleted, by the time the function returns.
5947 Returns the old value of the flag.
5949 process_flag(Flag :: priority, Level) -> OldLevel
5951 Types:
5953 Level = OldLevel = priority_level()
5955 priority_level() = low | normal | high | max
5956 Sets the process priority. Level is an atom. Four priority lev‐
5958 els exist: low, normal, high, and max. Default is normal.
5959 Note:
5961 Priority level max is reserved for internal use in the Erlang
5962 runtime system, and is not to be used by others.
5963 Internally in each priority level, processes are scheduled in a
5966 round robin fashion.
5967 Execution of processes on priority normal and low are inter‐
5969 leaved. Processes on priority low are selected for execution
5970 less frequently than processes on priority normal.
5971 When runnable processes on priority high exist, no processes on
5973 priority low or normal are selected for execution. Notice how‐
5974 ever that this does not mean that no processes on priority low
5975 or normal can run when processes are running on priority high.
5976 When using multiple schedulers, more processes can be running in
5977 parallel than processes on priority high. That is, a low and a
5978 high priority process can execute at the same time.
5979 When runnable processes on priority max exist, no processes on
5981 priority low, normal, or high are selected for execution. As
5982 with priority high, processes on lower priorities can execute in
5983 parallel with processes on priority max.
5984 Scheduling is pre-emptive. Regardless of priority, a process is
5986 pre-empted when it has consumed more than a certain number of
5987 reductions since the last time it was selected for execution.
5988 Note:
5990 Do not depend on the scheduling to remain exactly as it is to‐
5991 day. Scheduling is likely to be changed in a future release to
5992 use available processor cores better.
5993 There is no automatic mechanism for avoiding priority inversion,
5996 such as priority inheritance or priority ceilings. When using
5997 priorities, take this into account and handle such scenarios by
5998 yourself.
5999 Making calls from a high priority process into code that you has
6001 no control over can cause the high priority process to wait for
6002 a process with lower priority. That is, effectively decreasing
6003 the priority of the high priority process during the call. Even
6004 if this is not the case with one version of the code that you
6005 have no control over, it can be the case in a future version of
6006 it. This can, for example, occur if a high priority process
6007 triggers code loading, as the code server runs on priority nor‐
6008 mal.
6009 Other priorities than normal are normally not needed. When other
6011 priorities are used, use them with care, especially priority
6012 high. A process on priority high is only to perform work for
6013 short periods. Busy looping for long periods in a high priority
6014 process causes most likely problems, as important OTP servers
6015 run on priority normal.
6016 Returns the old value of the flag.
6018 process_flag(Flag :: save_calls, N) -> OldN
6020 Types:
6022 N = OldN = 0..10000
6024 N must be an integer in the interval 0..10000. If N > 0, call
6026 saving is made active for the process. This means that informa‐
6027 tion about the N most recent global function calls, BIF calls,
6028 sends, and receives made by the process are saved in a list,
6029 which can be retrieved with process_info(Pid, last_calls). A
6030 global function call is one in which the module of the function
6031 is explicitly mentioned. Only a fixed amount of information is
6032 saved, as follows:
6033 * A tuple {Module, Function, Arity} for function calls
6035 * The atoms send, 'receive', and timeout for sends and re‐
6037 ceives ('receive' when a message is received and timeout
6038 when a receive times out)
6039 If N = 0, call saving is disabled for the process, which is the
6041 default. Whenever the size of the call saving list is set, its
6042 contents are reset.
6043 Returns the old value of the flag.
6045 process_flag(Flag :: sensitive, Boolean) -> OldBoolean
6047 Types:
6049 Boolean = OldBoolean = boolean()
6051 Sets or clears flag sensitive for the current process. When a
6053 process has been marked as sensitive by calling
6054 process_flag(sensitive, true), features in the runtime system
6055 that can be used for examining the data or inner working of the
6056 process are silently disabled.
6057 Features that are disabled include (but are not limited to) the
6059 following:
6060 * Tracing. Trace flags can still be set for the process, but
6062 no trace messages of any kind are generated. (If flag sensi‐
6063 tive is turned off, trace messages are again generated if
6064 any trace flags are set.)
6065 * Sequential tracing. The sequential trace token is propagated
6067 as usual, but no sequential trace messages are generated.
6068 process_info/1,2 cannot be used to read out the message queue or
6070 the process dictionary (both are returned as empty lists).
6071 Stack back-traces cannot be displayed for the process.
6073 In crash dumps, the stack, messages, and the process dictionary
6075 are omitted.
6076 If {save_calls,N} has been set for the process, no function
6078 calls are saved to the call saving list. (The call saving list
6079 is not cleared. Also, send, receive, and time-out events are
6080 still added to the list.)
6081 Returns the old value of the flag.
6083 process_flag(Pid, Flag, Value) -> OldValue
6085 Types:
6087 Pid = pid()
6089 Flag = save_calls
6090 Value = OldValue = integer() >= 0
6091 Sets certain flags for the process Pid, in the same manner as
6093 process_flag/2. Returns the old value of the flag. The valid
6094 values for Flag are only a subset of those allowed in
6095 process_flag/2, namely save_calls.
6096 Failure: badarg if Pid is not a local process.
6098 process_info(Pid) -> Info
6100 Types:
6102 Pid = pid()
6104 Info = [InfoTuple] | undefined
6105 InfoTuple = process_info_result_item()
6106 process_info_result_item() =
6107 {async_dist, Enabled :: boolean()} |
6108 {backtrace, Bin :: binary()} |
6109 {binary,
6110 BinInfo ::
6111 [{integer() >= 0,
6112 integer() >= 0,
6113 integer() >= 0}]} |
6114 {catchlevel, CatchLevel :: integer() >= 0} |
6115 {current_function,
6116 {Module :: module(), Function :: atom(), Arity :: arity()} |
6117 undefined} |
6118 {current_location,
6119 {Module :: module(),
6120 Function :: atom(),
6121 Arity :: arity(),
6122 Location ::
6123 [{file, Filename :: string()} |
6124 {line, Line :: integer() >= 1}]}} |
6125 {current_stacktrace, Stack :: [stack_item()]} |
6126 {dictionary, Dictionary :: [{Key :: term(), Value :: term()}]} |
6127 {error_handler, Module :: module()} |
6128 {garbage_collection, GCInfo :: [{atom(), integer() >= 0}]} |
6129 {garbage_collection_info,
6130 GCInfo :: [{atom(), integer() >= 0}]} |
6131 {group_leader, GroupLeader :: pid()} |
6132 {heap_size, Size :: integer() >= 0} |
6133 {initial_call, mfa()} |
6134 {links, PidsAndPorts :: [pid() | port()]} |
6135 {last_calls, false | (Calls :: [mfa()])} |
6136 {memory, Size :: integer() >= 0} |
6137 {message_queue_len, MessageQueueLen :: integer() >= 0} |
6138 {messages, MessageQueue :: [term()]} |
6139 {min_heap_size, MinHeapSize :: integer() >= 0} |
6140 {min_bin_vheap_size, MinBinVHeapSize :: integer() >= 0} |
6141 {max_heap_size, MaxHeapSize :: max_heap_size()} |
6142 {monitored_by,
6143 MonitoredBy :: [pid() | port() | nif_resource()]} |
6144 {monitors,
6145 Monitors ::
6146 [{process | port,
6147 Pid ::
6148 pid() |
6149 port() |
6150 {RegName :: atom(), Node :: node()}}]} |
6151 {message_queue_data, MQD :: message_queue_data()} |
6152 {parent, pid() | undefined} |
6153 {priority, Level :: priority_level()} |
6154 {reductions, Number :: integer() >= 0} |
6155 {registered_name, [] | (Atom :: atom())} |
6156 {sequential_trace_token,
6157 [] | (SequentialTraceToken :: term())} |
6158 {stack_size, Size :: integer() >= 0} |
6159 {status,
6160 Status ::
6161 exiting | garbage_collecting | waiting | running |
6162 runnable | suspended} |
6163 {suspending,
6164 SuspendeeList ::
6165 [{Suspendee :: pid(),
6166 ActiveSuspendCount :: integer() >= 0,
6167 OutstandingSuspendCount :: integer() >= 0}]} |
6168 {total_heap_size, Size :: integer() >= 0} |
6169 {trace, InternalTraceFlags :: integer() >= 0} |
6170 {trap_exit, Boolean :: boolean()}
6171 priority_level() = low | normal | high | max
6172 stack_item() =
6173 {Module :: module(),
6174 Function :: atom(),
6175 Arity :: arity() | (Args :: [term()]),
6176 Location ::
6177 [{file, Filename :: string()} |
6178 {line, Line :: integer() >= 1}]}
6179 max_heap_size() =
6180 integer() >= 0 |
6181 #{size => integer() >= 0,
6182 kill => boolean(),
6183 error_logger => boolean()}
6184 message_queue_data() = off_heap | on_heap
6185 Returns a list containing InfoTuples with miscellaneous informa‐
6187 tion about the process identified by Pid, or undefined if the
6188 process is not alive.
6189 The order of the InfoTuples is undefined and all InfoTuples are
6191 not mandatory. The InfoTuples part of the result can be changed
6192 without prior notice.
6193 The InfoTuples with the following items are part of the result:
6195 * current_function
6197 * initial_call
6199 * status
6201 * message_queue_len
6203 * links
6205 * dictionary
6207 * trap_exit
6209 * error_handler
6211 * priority
6213 * group_leader
6215 * total_heap_size
6217 * heap_size
6219 * stack_size
6221 * reductions
6223 * garbage_collection
6225 If the process identified by Pid has a registered name, also an
6227 InfoTuple with item registered_name is included.
6228 For information about specific InfoTuples, see process_info/2.
6230 Warning:
6232 This BIF is intended for debugging only. For all other purposes,
6233 use process_info/2.
6234 Failure: badarg if Pid is not a local process.
6237 process_info(Pid, Item) -> InfoTuple | [] | undefined
6239 process_info(Pid, ItemList) -> InfoTupleList | [] | undefined
6241 Types:
6243 Pid = pid()
6245 ItemList = [Item]
6246 Item = process_info_item()
6247 InfoTupleList = [InfoTuple]
6248 InfoTuple = process_info_result_item()
6249 process_info_item() =
6250 async_dist | backtrace | binary | catchlevel |
6251 current_function | current_location | current_stacktrace |
6252 dictionary | error_handler | garbage_collection |
6253 garbage_collection_info | group_leader | heap_size |
6254 initial_call | links | last_calls | memory |
6255 message_queue_len | messages | min_heap_size |
6256 min_bin_vheap_size | monitored_by | monitors |
6257 message_queue_data | parent | priority | reductions |
6258 registered_name | sequential_trace_token | stack_size |
6259 status | suspending | total_heap_size | trace | trap_exit
6260 process_info_result_item() =
6261 {async_dist, Enabled :: boolean()} |
6262 {backtrace, Bin :: binary()} |
6263 {binary,
6264 BinInfo ::
6265 [{integer() >= 0,
6266 integer() >= 0,
6267 integer() >= 0}]} |
6268 {catchlevel, CatchLevel :: integer() >= 0} |
6269 {current_function,
6270 {Module :: module(), Function :: atom(), Arity :: arity()} |
6271 undefined} |
6272 {current_location,
6273 {Module :: module(),
6274 Function :: atom(),
6275 Arity :: arity(),
6276 Location ::
6277 [{file, Filename :: string()} |
6278 {line, Line :: integer() >= 1}]}} |
6279 {current_stacktrace, Stack :: [stack_item()]} |
6280 {dictionary, Dictionary :: [{Key :: term(), Value :: term()}]} |
6281 {error_handler, Module :: module()} |
6282 {garbage_collection, GCInfo :: [{atom(), integer() >= 0}]} |
6283 {garbage_collection_info,
6284 GCInfo :: [{atom(), integer() >= 0}]} |
6285 {group_leader, GroupLeader :: pid()} |
6286 {heap_size, Size :: integer() >= 0} |
6287 {initial_call, mfa()} |
6288 {links, PidsAndPorts :: [pid() | port()]} |
6289 {last_calls, false | (Calls :: [mfa()])} |
6290 {memory, Size :: integer() >= 0} |
6291 {message_queue_len, MessageQueueLen :: integer() >= 0} |
6292 {messages, MessageQueue :: [term()]} |
6293 {min_heap_size, MinHeapSize :: integer() >= 0} |
6294 {min_bin_vheap_size, MinBinVHeapSize :: integer() >= 0} |
6295 {max_heap_size, MaxHeapSize :: max_heap_size()} |
6296 {monitored_by,
6297 MonitoredBy :: [pid() | port() | nif_resource()]} |
6298 {monitors,
6299 Monitors ::
6300 [{process | port,
6301 Pid ::
6302 pid() |
6303 port() |
6304 {RegName :: atom(), Node :: node()}}]} |
6305 {message_queue_data, MQD :: message_queue_data()} |
6306 {parent, pid() | undefined} |
6307 {priority, Level :: priority_level()} |
6308 {reductions, Number :: integer() >= 0} |
6309 {registered_name, [] | (Atom :: atom())} |
6310 {sequential_trace_token,
6311 [] | (SequentialTraceToken :: term())} |
6312 {stack_size, Size :: integer() >= 0} |
6313 {status,
6314 Status ::
6315 exiting | garbage_collecting | waiting | running |
6316 runnable | suspended} |
6317 {suspending,
6318 SuspendeeList ::
6319 [{Suspendee :: pid(),
6320 ActiveSuspendCount :: integer() >= 0,
6321 OutstandingSuspendCount :: integer() >= 0}]} |
6322 {total_heap_size, Size :: integer() >= 0} |
6323 {trace, InternalTraceFlags :: integer() >= 0} |
6324 {trap_exit, Boolean :: boolean()}
6325 stack_item() =
6326 {Module :: module(),
6327 Function :: atom(),
6328 Arity :: arity() | (Args :: [term()]),
6329 Location ::
6330 [{file, Filename :: string()} |
6331 {line, Line :: integer() >= 1}]}
6332 priority_level() = low | normal | high | max
6333 max_heap_size() =
6334 integer() >= 0 |
6335 #{size => integer() >= 0,
6336 kill => boolean(),
6337 error_logger => boolean()}
6338 message_queue_data() = off_heap | on_heap
6339 Returns information about the process identified by Pid, as
6341 specified by Item or ItemList. Returns undefined if the process
6342 is not alive.
6343 If the process is alive and a single Item is specified, the re‐
6345 turned value is the corresponding InfoTuple, unless Item =:=
6346 registered_name and the process has no registered name. In this
6347 case, [] is returned. This strange behavior is because of his‐
6348 torical reasons, and is kept for backward compatibility.
6349 If ItemList is specified, the result is InfoTupleList. The Info‐
6351 Tuples in InfoTupleList are included with the corresponding
6352 Items in the same order as the Items were included in ItemList.
6353 Valid Items can be included multiple times in ItemList.
6354 Getting process information follows the signal ordering guaran‐
6356 tees described in the Processes Chapter in the Erlang Reference
6357 Manual .
6358 Note:
6360 If registered_name is part of ItemList and the process has no
6361 name registered, a {registered_name, []}, InfoTuple will be in‐
6362 cluded in the resulting InfoTupleList. This behavior is differ‐
6363 ent when a single Item =:= registered_name is specified, and
6364 when process_info/1 is used.
6365 Valid InfoTuples with corresponding Items:
6368 {async_dist, Enabled}:
6370 Since: OTP 25.3
6371 Current value of the async_dist process flag.
6373 {backtrace, Bin}:
6375 Binary Bin contains the same information as the output from
6376 erlang:process_display(Pid, backtrace). Use binary_to_list/1
6377 to obtain the string of characters from the binary.
6378 {binary, BinInfo}:
6380 BinInfo is a list containing miscellaneous information about
6381 binaries on the heap of this process. This InfoTuple can be
6382 changed or removed without prior notice. In the current im‐
6383 plementation BinInfo is a list of tuples. The tuples con‐
6384 tain; BinaryId, BinarySize, BinaryRefcCount.
6385 Depending on the value of the message_queue_data process
6387 flag the message queue may be stored on the heap.
6388 {catchlevel, CatchLevel}:
6390 CatchLevel is the number of currently active catches in this
6391 process. This InfoTuple can be changed or removed without
6392 prior notice.
6393 {current_function, {Module, Function, Arity} | undefined}:
6395 Module, Function, Arity is the current function call of the
6396 process. The value undefined can be returned if the process
6397 is currently executing native compiled code.
6398 {current_location, {Module, Function, Arity, Location}}:
6400 Module, Function, Arity is the current function call of the
6401 process. Location is a list of two-tuples describing the lo‐
6402 cation in the source code.
6403 {current_stacktrace, Stack}:
6405 Returns the current call stack back-trace (stacktrace) of
6406 the process. The stack has the same format as in the catch
6407 part of a try. See The call-stack back trace (stacktrace).
6408 The depth of the stacktrace is truncated according to the
6409 backtrace_depth system flag setting.
6410 {dictionary, Dictionary}:
6412 Dictionary is the process dictionary.
6413 {error_handler, Module}:
6415 Module is the error handler module used by the process (for
6416 undefined function calls, for example).
6417 {garbage_collection, GCInfo}:
6419 GCInfo is a list containing miscellaneous information about
6420 garbage collection for this process. The content of GCInfo
6421 can be changed without prior notice.
6422 {garbage_collection_info, GCInfo}:
6424 GCInfo is a list containing miscellaneous detailed informa‐
6425 tion about garbage collection for this process. The content
6426 of GCInfo can be changed without prior notice. For details
6427 about the meaning of each item, see gc_minor_start in er‐
6428 lang:trace/3.
6429 {group_leader, GroupLeader}:
6431 GroupLeader is the group leader for the I/O of the process.
6432 {heap_size, Size}:
6434 Size is the size in words of the youngest heap generation of
6435 the process. This generation includes the process stack.
6436 This information is highly implementation-dependent, and can
6437 change if the implementation changes.
6438 {initial_call, {Module, Function, Arity}}:
6440 Module, Function, Arity is the initial function call with
6441 which the process was spawned.
6442 {links, PidsAndPorts}:
6444 PidsAndPorts is a list of process identifiers and port iden‐
6445 tifiers, with processes or ports to which the process has a
6446 link.
6447 {last_calls, false|Calls}:
6449 The value is false if call saving is not active for the
6450 process (see process_flag/3). If call saving is active, a
6451 list is returned, in which the last element is the most re‐
6452 cent called.
6453 {memory, Size}:
6455 Size is the size in bytes of the process. This includes call
6458 stack, heap, and internal structures.
6459 {message_queue_len, MessageQueueLen}:
6461 MessageQueueLen is the number of messages currently in the
6462 message queue of the process. This is the length of the list
6463 MessageQueue returned as the information item messages (see
6464 below).
6465 {messages, MessageQueue}:
6467 MessageQueue is a list of the messages to the process, which
6468 have not yet been processed.
6469 {min_heap_size, MinHeapSize}:
6471 MinHeapSize is the minimum heap size for the process.
6472 {min_bin_vheap_size, MinBinVHeapSize}:
6474 MinBinVHeapSize is the minimum binary virtual heap size for
6475 the process.
6476 {monitored_by, MonitoredBy}:
6478 A list of identifiers for all the processes, ports and NIF
6479 resources, that are monitoring the process.
6480 {monitors, Monitors}:
6482 A list of monitors (started by monitor/2) that are active
6483 for the process. For a local process monitor or a remote
6484 process monitor by a process identifier, the list consists
6485 of:
6486 {process, Pid}:
6488 Process is monitored by pid.
6489 {process, {RegName, Node}}:
6491 Local or remote process is monitored by name.
6492 {port, PortId}:
6494 Local port is monitored by port id.
6495 {port, {RegName, Node}}:
6497 Local port is monitored by name. Please note, that remote
6498 port monitors are not supported, so Node will always be
6499 the local node name.
6500 {message_queue_data, MQD}:
6502 MQD is the current value of the message_queue_data process
6503 flag, which can be either off_heap or on_heap. For more in‐
6504 formation, see the documentation of process_flag(mes‐
6505 sage_queue_data, MQD).
6506 {parent, Pid}:
6508 Pid is the identifier of the parent process, the one that
6509 spawned current process. When the process does not have a
6510 parent undefined is returned. Only the initial process
6511 (init) on a node lacks a parent, though.
6512 {priority, Level}:
6514 Level is the current priority level for the process. For
6515 more information on priorities, see process_flag(priority,
6516 Level).
6517 {reductions, Number}:
6519 Number is the number of reductions executed by the process.
6520 {registered_name, Atom}:
6522 Atom is the registered process name. If the process has no
6523 registered name, this tuple is not present in the list.
6524 {sequential_trace_token, [] | SequentialTraceToken}:
6526 SequentialTraceToken is the sequential trace token for the
6527 process. This InfoTuple can be changed or removed without
6528 prior notice.
6529 {stack_size, Size}:
6531 Size is the stack size, in words, of the process.
6532 {status, Status}:
6534 Status is the status of the process and is one of the fol‐
6535 lowing:
6536 * exiting
6538 * garbage_collecting
6540 * waiting (for a message)
6542 * running
6544 * runnable (ready to run, but another process is running)
6546 * suspended (suspended on a "busy" port or by the BIF er‐
6548 lang:suspend_process/1,2)
6549 {suspending, SuspendeeList}:
6551 SuspendeeList is a list of {Suspendee, ActiveSuspendCount,
6552 OutstandingSuspendCount} tuples. Suspendee is the process
6553 identifier of a process that has been, or is to be, sus‐
6554 pended by the process identified by Pid through the BIF er‐
6555 lang:suspend_process/2 or erlang:suspend_process/1.
6556 ActiveSuspendCount is the number of times Suspendee has been
6558 suspended by Pid. OutstandingSuspendCount is the number of
6559 not yet completed suspend requests sent by Pid, that is:
6560 * If ActiveSuspendCount =/= 0, Suspendee is currently in the
6562 suspended state.
6563 * If OutstandingSuspendCount =/= 0, option asynchronous of
6565 erlang:suspend_process/2 has been used and the suspendee
6566 has not yet been suspended by Pid.
6567 Notice that ActiveSuspendCount and OutstandingSuspendCount
6569 are not the total suspend count on Suspendee, only the parts
6570 contributed by Pid.
6571 {total_heap_size, Size}:
6573 Size is the total size, in words, of all heap fragments of
6574 the process. This includes the process stack and any unre‐
6575 ceived messages that are considered to be part of the heap.
6576 {trace, InternalTraceFlags}:
6578 InternalTraceFlags is an integer representing the internal
6579 trace flag for this process. This InfoTuple can be changed
6580 or removed without prior notice.
6581 {trap_exit, Boolean}:
6583 Boolean is true if the process is trapping exits, otherwise
6584 false.
6585 Notice that not all implementations support all these Items.
6587 Failures:
6589 badarg:
6591 If Pid is not a local process.
6592 badarg:
6594 If Item is an invalid item.
6595 processes() -> [pid()]
6597 Returns a list of process identifiers corresponding to all the
6599 processes currently existing on the local node.
6600 Notice that an exiting process exists, but is not alive. That
6602 is, is_process_alive/1 returns false for an exiting process, but
6603 its process identifier is part of the result returned from pro‐
6604 cesses/0.
6605 Example:
6607 > processes().
6609 [<0.0.0>,<0.2.0>,<0.4.0>,<0.5.0>,<0.7.0>,<0.8.0>]
6610 purge_module(Module) -> true
6612 Types:
6614 Module = atom()
6616 Removes old code for Module. Before this BIF is used,
6618 check_process_code/2 is to be called to check that no processes
6619 execute old code in the module.
6620 Warning:
6622 This BIF is intended for the code server (see code(3)) and is
6623 not to be used elsewhere.
6624 Note:
6627 As from ERTS 8.0 (Erlang/OTP 19), any lingering processes that
6628 still execute the old code is killed by this function. In ear‐
6629 lier versions, such incorrect use could cause much more fatal
6630 failures, like emulator crash.
6631 Failure: badarg if there is no old code for Module.
6634 put(Key, Val) -> term()
6636 Types:
6638 Key = Val = term()
6640 Adds a new Key to the process dictionary, associated with the
6642 value Val, and returns undefined. If Key exists, the old value
6643 is deleted and replaced by Val, and the function returns the old
6644 value. The average time complexity for the current implementa‐
6645 tion of this function is O(1) and the worst case time complexity
6646 is O(N), where N is the number of items in the process dictio‐
6647 nary. Example:
6648 > X = put(name, walrus), Y = put(name, carpenter),
6650 Z = get(name),
6651 {X, Y, Z}.
6652 {undefined,walrus,carpenter}
6653 Note:
6655 The values stored when put is evaluated within the scope of a
6656 catch are not retracted if a throw is evaluated, or if an error
6657 occurs.
6658 erlang:raise(Class, Reason, Stacktrace) -> badarg
6661 Types:
6663 Class = error | exit | throw
6665 Reason = term()
6666 Stacktrace = raise_stacktrace() | stacktrace()
6667 raise_stacktrace() =
6668 [{module(), atom(), arity() | [term()]} |
6669 {function(), arity() | [term()]}]
6670 Raises an exception of the specified class, reason, and call
6672 stack backtrace (stacktrace).
6673 Class is error, exit, or throw. So, if it were not for the
6675 stacktrace, erlang:raise(Class, Reason, Stacktrace) is equiva‐
6676 lent to erlang:Class(Reason) (given that Class is a valid
6677 class).
6678 Reason can be any term.
6680 Stacktrace is a list as provided in a try-catch clause.
6682 try
6684 ...
6685 catch Class:Reason:Stacktrace ->
6686 ...
6687 end
6688 That is, a list of four-tuples {Module, Function, Arity | Args,
6690 ExtraInfo}, where Module and Function are atoms, and the third
6691 element is an integer arity or an argument list. The stacktrace
6692 can also contain {Fun, Args, ExtraInfo} tuples, where Fun is a
6693 local fun and Args is an argument list.
6694 Element ExtraInfo at the end is optional. Omitting it is equiva‐
6696 lent to specifying an empty list.
6697 The stacktrace is used as the exception stacktrace for the call‐
6699 ing process; it is truncated to the current maximum stacktrace
6700 depth.
6701 As evaluating this function causes the process to terminate, it
6703 has no return value unless the arguments are invalid, in which
6704 case the function returns the error reason badarg. If you want
6705 to be sure not to return, you can call error(erlang:raise(Class,
6706 Reason, Stacktrace)) and hope to distinguish exceptions later.
6707 See the reference manual about errors and error handling for
6709 more information about exception classes and how to catch excep‐
6710 tions.
6711 erlang:read_timer(TimerRef) -> Result
6713 Types:
6715 TimerRef = reference()
6717 Time = integer() >= 0
6718 Result = Time | false
6719 Reads the state of a timer. The same as calling er‐
6721 lang:read_timer(TimerRef, []).
6722 erlang:read_timer(TimerRef, Options) -> Result | ok
6724 Types:
6726 TimerRef = reference()
6728 Async = boolean()
6729 Option = {async, Async}
6730 Options = [Option]
6731 Time = integer() >= 0
6732 Result = Time | false
6733 Reads the state of a timer that has been created by either er‐
6735 lang:start_timer or erlang:send_after. TimerRef identifies the
6736 timer, and was returned by the BIF that created the timer.
6737 Options:
6739 {async, Async}:
6741 Asynchronous request for state information. Async defaults
6742 to false, which causes the operation to be performed syn‐
6743 chronously. In this case, the Result is returned by er‐
6744 lang:read_timer. When Async is true, erlang:read_timer sends
6745 an asynchronous request for the state information to the
6746 timer service that manages the timer, and then returns ok. A
6747 message on the format {read_timer, TimerRef, Result} is sent
6748 to the caller of erlang:read_timer when the operation has
6749 been processed.
6750 More Options can be added in the future.
6752 If Result is an integer, it represents the time in milliseconds
6754 left until the timer expires.
6755 If Result is false, a timer corresponding to TimerRef could not
6757 be found. This because the timer had expired, or been canceled,
6758 or because TimerRef never has corresponded to a timer. Even if
6759 the timer has expired, it does not tell you whether or not the
6760 time-out message has arrived at its destination yet.
6761 Note:
6763 The timer service that manages the timer can be co-located with
6764 another scheduler than the scheduler that the calling process is
6765 executing on. If so, communication with the timer service takes
6766 much longer time than if it is located locally. If the calling
6767 process is in a critical path, and can do other things while
6768 waiting for the result of this operation, you want to use option
6769 {async, true}. If using option {async, false}, the calling
6770 process is blocked until the operation has been performed.
6771 See also erlang:send_after/4, erlang:start_timer/4, and er‐
6774 lang:cancel_timer/2.
6775 ref_to_list(Ref) -> string()
6777 Types:
6779 Ref = reference()
6781 Returns a string corresponding to the text representation of
6783 Ref.
6784 Warning:
6786 This BIF is intended for debugging and is not to be used in ap‐
6787 plication programs.
6788 register(RegName, PidOrPort) -> true
6791 Types:
6793 RegName = atom()
6795 PidOrPort = port() | pid()
6796 Registers the name RegName with a process identifier (pid) or a
6798 port identifier in the name registry. RegName, which must be an
6799 atom, can be used instead of the pid or port identifier in send
6800 operator (RegName ! Message) and most other BIFs that take a pid
6801 or port identifies as an argument. Example:
6802 > register(db, Pid).
6804 true
6805 The registered name is considered a Directly Visible Erlang Re‐
6807 source and is automatically unregistered when the process termi‐
6808 nates.
6809 Failures:
6811 badarg:
6813 If PidOrPort is not an existing local process or port.
6814 badarg:
6816 If RegName is already in use.
6817 badarg:
6819 If the process or port is already registered (already has a
6820 name).
6821 badarg:
6823 If RegName is the atom undefined.
6824 registered() -> [RegName]
6826 Types:
6828 RegName = atom()
6830 Returns a list of names that have been registered using regis‐
6832 ter/2, for example:
6833 > registered().
6835 [code_server, file_server, init, user, my_db]
6836 erlang:resume_process(Suspendee) -> true
6838 Types:
6840 Suspendee = pid()
6842 Decreases the suspend count on the process identified by Sus‐
6844 pendee. Suspendee is previously to have been suspended through
6845 erlang:suspend_process/2 or erlang:suspend_process/1 by the
6846 process calling erlang:resume_process(Suspendee). When the sus‐
6847 pend count on Suspendee reaches zero, Suspendee is resumed, that
6848 is, its state is changed from suspended into the state it had
6849 before it was suspended.
6850 Warning:
6852 This BIF is intended for debugging only.
6853 Failures:
6856 badarg:
6858 If Suspendee is not a process identifier.
6859 badarg:
6861 If the process calling erlang:resume_process/1 had not pre‐
6862 viously increased the suspend count on the process identi‐
6863 fied by Suspendee.
6864 badarg:
6866 If the process identified by Suspendee is not alive.
6867 round(Number) -> integer()
6869 Types:
6871 Number = number()
6873 Returns an integer by rounding Number, for example:
6875 round(42.1).
6877 42
6878 round(5.5).
6880 6
6881 round(-5.5).
6883 -6
6884 round(36028797018963969.0).
6886 36028797018963968
6887 In the last example, round(36028797018963969.0) evaluates to
6889 36028797018963968. The reason for this is that the number
6890 36028797018963969.0 cannot be represented exactly as a float
6891 value. Instead, the float literal is represented as
6892 36028797018963968.0, which is the closest number that can be
6893 represented exactly as a float value. See Representation of
6894 Floating Point Numbers for additional information.
6895 Allowed in guard tests.
6897 self() -> pid()
6899 Returns the process identifier of the calling process, for exam‐
6901 ple:
6902 > self().
6904 <0.26.0>
6905 Allowed in guard tests.
6907 erlang:send(Dest, Msg) -> Msg
6909 Types:
6911 Dest = send_destination()
6913 Msg = term()
6914 Sends a message and returns Msg. This is the same as using the
6916 send operator: Dest ! Msg.
6917 Dest can be a remote or local process identifier, an alias, a
6919 (local) port, a locally registered name, or a tuple {RegName,
6920 Node} for a registered name at another node.
6921 The function fails with a badarg run-time error if Dest is an
6923 atom name, but this name is not registered. This is the only
6924 case when send fails for an unreachable destination Dest (of
6925 correct type).
6926 erlang:send(Dest, Msg, Options) -> Res
6928 Types:
6930 Dest = send_destination()
6932 Msg = term()
6933 Options = [nosuspend | noconnect]
6934 Res = ok | nosuspend | noconnect
6935 Either sends a message and returns ok, or does not send the mes‐
6937 sage but returns something else (see below). Otherwise the same
6938 as erlang:send/2. For more detailed explanation and warnings,
6939 see erlang:send_nosuspend/2,3.
6940 Options:
6942 nosuspend:
6944 If the sender would have to be suspended to do the send, no‐
6945 suspend is returned instead.
6946 noconnect:
6948 If the destination node would have to be auto-connected to
6949 do the send, noconnect is returned instead.
6950 Warning:
6952 As with erlang:send_nosuspend/2,3: use with extreme care.
6953 erlang:send_after(Time, Dest, Msg) -> TimerRef
6956 Types:
6958 Time = integer() >= 0
6960 Dest = pid() | atom()
6961 Msg = term()
6962 TimerRef = reference()
6963 Starts a timer. The same as calling erlang:send_after(Time,
6965 Dest, Msg, []).
6966 erlang:send_after(Time, Dest, Msg, Options) -> TimerRef
6968 Types:
6970 Time = integer()
6972 Dest = pid() | atom()
6973 Msg = term()
6974 Options = [Option]
6975 Abs = boolean()
6976 Option = {abs, Abs}
6977 TimerRef = reference()
6978 Starts a timer. When the timer expires, the message Msg is sent
6980 to the process identified by Dest. Apart from the format of the
6981 time-out message, this function works exactly as er‐
6982 lang:start_timer/4.
6983 erlang:send_nosuspend(Dest, Msg) -> boolean()
6985 Types:
6987 Dest = send_destination()
6989 Msg = term()
6990 The same as erlang:send(Dest, Msg, [nosuspend]), but returns
6992 true if the message was sent and false if the message was not
6993 sent because the sender would have had to be suspended.
6994 This function is intended for send operations to an unreliable
6996 remote node without ever blocking the sending (Erlang) process.
6997 If the connection to the remote node (usually not a real Erlang
6998 node, but a node written in C or Java) is overloaded, this func‐
6999 tion does not send the message and returns false.
7000 The same occurs if Dest refers to a local port that is busy. For
7002 all other destinations (allowed for the ordinary send operator
7003 '!'), this function sends the message and returns true.
7004 This function is only to be used in rare circumstances where a
7006 process communicates with Erlang nodes that can disappear with‐
7007 out any trace, causing the TCP buffers and the drivers queue to
7008 be over-full before the node is shut down (because of tick time-
7009 outs) by net_kernel. The normal reaction to take when this oc‐
7010 curs is some kind of premature shutdown of the other node.
7011 Notice that ignoring the return value from this function would
7013 result in an unreliable message passing, which is contradictory
7014 to the Erlang programming model. The message is not sent if this
7015 function returns false.
7016 In many systems, transient states of overloaded queues are nor‐
7018 mal. Although this function returns false does not mean that the
7019 other node is guaranteed to be non-responsive, it could be a
7020 temporary overload. Also, a return value of true does only mean
7021 that the message can be sent on the (TCP) channel without block‐
7022 ing; the message is not guaranteed to arrive at the remote node.
7023 For a disconnected non-responsive node, the return value is true
7024 (mimics the behavior of operator !). The expected behavior and
7025 the actions to take when the function returns false are applica‐
7026 tion- and hardware-specific.
7027 Warning:
7029 Use with extreme care.
7030 erlang:send_nosuspend(Dest, Msg, Options) -> boolean()
7033 Types:
7035 Dest = send_destination()
7037 Msg = term()
7038 Options = [noconnect]
7039 The same as erlang:send(Dest, Msg, [nosuspend | Options]), but
7041 with a Boolean return value.
7042 This function behaves like erlang:send_nosuspend/2, but takes a
7044 third parameter, a list of options. The only option is nocon‐
7045 nect, which makes the function return false if the remote node
7046 is not currently reachable by the local node. The normal behav‐
7047 ior is to try to connect to the node, which can stall the
7048 process during a short period. The use of option noconnect makes
7049 it possible to be sure not to get the slightest delay when send‐
7050 ing to a remote process. This is especially useful when communi‐
7051 cating with nodes that expect to always be the connecting part
7052 (that is, nodes written in C or Java).
7053 Whenever the function returns false (either when a suspend would
7055 occur or when noconnect was specified and the node was not al‐
7056 ready connected), the message is guaranteed not to have been
7057 sent.
7058 Warning:
7060 Use with extreme care.
7061 erlang:set_cookie(Cookie) -> true
7064 Types:
7066 Cookie = atom()
7068 Sets the magic cookie of the local node to the atom Cookie,
7070 which is also the cookie for all nodes that have no explicit
7071 cookie set with set_cookie/2 Cookie (see section Distributed
7072 Erlang in the Erlang Reference Manual in System Documentation).
7073 You can get this value using get_cookie/0.
7075 Failure: function_clause if the local node is not alive.
7077 erlang:set_cookie(Node, Cookie) -> true
7079 Types:
7081 Node = node()
7083 Cookie = atom()
7084 Sets the magic cookie for Node to the atom Cookie. If Node is
7086 the local node, the function sets the cookie of all other nodes
7087 (that have no explicit cookie set with this function) to Cookie
7088 (see section Distributed Erlang in the Erlang Reference Manual
7089 in System Documentation).
7090 You can get this value using get_cookie/1.
7092 Failure: function_clause if the local node is not alive.
7094 setelement(Index, Tuple1, Value) -> Tuple2
7096 Types:
7098 Index = integer() >= 1
7100 1..tuple_size(Tuple1)
7101 Tuple1 = Tuple2 = tuple()
7102 Value = term()
7103 Returns a tuple that is a copy of argument Tuple1 with the ele‐
7105 ment specified by integer argument Index (the first element is
7106 the element with index 1) replaced by argument Value, for exam‐
7107 ple:
7108 > setelement(2, {10, green, bottles}, red).
7110 {10,red,bottles}
7111 size(Item) -> integer() >= 0
7113 Types:
7115 Item = tuple() | binary()
7117 Returns the number of elements in a tuple or the number of bytes
7119 in a binary or bitstring, for example:
7120 > size({morni, mulle, bwange}).
7122 3
7123 > size(<<11, 22, 33>>).
7124 3
7125 For bitstrings, the number of whole bytes is returned. That is,
7127 if the number of bits in the bitstring is not divisible by 8,
7128 the resulting number of bytes is rounded down.
7129 Allowed in guard tests.
7131 See also tuple_size/1, byte_size/1, and bit_size/1.
7133 spawn(Fun) -> pid()
7135 Types:
7137 Fun = function()
7139 Returns the process identifier of a new process started by the
7141 application of Fun to the empty list []. Otherwise works like
7142 spawn/3.
7143 spawn(Node, Fun) -> pid()
7145 Types:
7147 Node = node()
7149 Fun = function()
7150 Returns the process identifier of a new process started by the
7152 application of Fun to the empty list [] on Node. If Node does
7153 not exist, a useless pid is returned. Otherwise works like
7154 spawn/3.
7155 spawn(Module, Function, Args) -> pid()
7157 Types:
7159 Module = module()
7161 Function = atom()
7162 Args = [term()]
7163 Returns the process identifier of a new process started by the
7165 application of Module:Function to Args.
7166 error_handler:undefined_function(Module, Function, Args) is
7168 evaluated by the new process if Module:Function/Arity does not
7169 exist (where Arity is the length of Args). The error handler can
7170 be redefined (see process_flag/2). If error_handler is unde‐
7171 fined, or the user has redefined the default error_handler and
7172 its replacement is undefined, a failure with reason undef oc‐
7173 curs.
7174 Example:
7176 > spawn(speed, regulator, [high_speed, thin_cut]).
7178 <0.13.1>
7179 spawn(Node, Module, Function, Args) -> pid()
7181 Types:
7183 Node = node()
7185 Module = module()
7186 Function = atom()
7187 Args = [term()]
7188 Returns the process identifier (pid) of a new process started by
7190 the application of Module:Function to Args on Node. If Node does
7191 not exist, a useless pid is returned. Otherwise works like
7192 spawn/3.
7193 spawn_link(Fun) -> pid()
7195 Types:
7197 Fun = function()
7199 Returns the process identifier of a new process started by the
7201 application of Fun to the empty list []. A link is created be‐
7202 tween the calling process and the new process, atomically. Oth‐
7203 erwise works like spawn/3.
7204 spawn_link(Node, Fun) -> pid()
7206 Types:
7208 Node = node()
7210 Fun = function()
7211 Returns the process identifier (pid) of a new process started by
7213 the application of Fun to the empty list [] on Node. A link is
7214 created between the calling process and the new process, atomi‐
7215 cally. If Node does not exist, a useless pid is returned and an
7216 exit signal with reason noconnection is sent to the calling
7217 process. Otherwise works like spawn/3.
7218 spawn_link(Module, Function, Args) -> pid()
7220 Types:
7222 Module = module()
7224 Function = atom()
7225 Args = [term()]
7226 Returns the process identifier of a new process started by the
7228 application of Module:Function to Args. A link is created be‐
7229 tween the calling process and the new process, atomically. Oth‐
7230 erwise works like spawn/3.
7231 spawn_link(Node, Module, Function, Args) -> pid()
7233 Types:
7235 Node = node()
7237 Module = module()
7238 Function = atom()
7239 Args = [term()]
7240 Returns the process identifier (pid) of a new process started by
7242 the application of Module:Function to Args on Node. A link is
7243 created between the calling process and the new process, atomi‐
7244 cally. If Node does not exist, a useless pid is returned and an
7245 exit signal with reason noconnection is sent to the calling
7246 process. Otherwise works like spawn/3.
7247 spawn_monitor(Fun) -> {pid(), reference()}
7249 Types:
7251 Fun = function()
7253 Returns the process identifier of a new process, started by the
7255 application of Fun to the empty list [], and a reference for a
7256 monitor created to the new process. Otherwise works like
7257 spawn/3.
7258 spawn_monitor(Node, Fun) -> {pid(), reference()}
7260 Types:
7262 Node = node()
7264 Fun = function()
7265 Returns the process identifier of a new process, started by the
7267 application of Fun to the empty list [] on the node Node, and a
7268 reference for a monitor created to the new process. Otherwise
7269 works like spawn/3.
7270 If the node identified by Node does not support distributed
7272 spawn_monitor(), the call will fail with a notsup exception.
7273 spawn_monitor(Module, Function, Args) -> {pid(), reference()}
7275 Types:
7277 Module = module()
7279 Function = atom()
7280 Args = [term()]
7281 A new process is started by the application of Module:Function
7283 to Args. The process is monitored at the same time. Returns the
7284 process identifier and a reference for the monitor. Otherwise
7285 works like spawn/3.
7286 spawn_monitor(Node, Module, Function, Args) ->
7288 {pid(), reference()}
7289 Types:
7291 Node = node()
7293 Module = module()
7294 Function = atom()
7295 Args = [term()]
7296 A new process is started by the application of Module:Function
7298 to Args on the node Node. The process is monitored at the same
7299 time. Returns the process identifier and a reference for the
7300 monitor. Otherwise works like spawn/3.
7301 If the node identified by Node does not support distributed
7303 spawn_monitor(), the call will fail with a notsup exception.
7304 spawn_opt(Fun, Options) -> pid() | {pid(), reference()}
7306 Types:
7308 Fun = function()
7310 Options = [spawn_opt_option()]
7311 priority_level() = low | normal | high | max
7312 max_heap_size() =
7313 integer() >= 0 |
7314 #{size => integer() >= 0,
7315 kill => boolean(),
7316 error_logger => boolean()}
7317 message_queue_data() = off_heap | on_heap
7318 spawn_opt_option() =
7319 link | monitor |
7320 {monitor, MonitorOpts :: [monitor_option()]} |
7321 {priority, Level :: priority_level()} |
7322 {fullsweep_after, Number :: integer() >= 0} |
7323 {min_heap_size, Size :: integer() >= 0} |
7324 {min_bin_vheap_size, VSize :: integer() >= 0} |
7325 {max_heap_size, Size :: max_heap_size()} |
7326 {message_queue_data, MQD :: message_queue_data()} |
7327 {async_dist, Enabled :: boolean()}
7328 Returns the process identifier (pid) of a new process started by
7330 the application of Fun to the empty list []. Otherwise works
7331 like spawn_opt/4.
7332 If option monitor is specified, the newly created process is
7334 monitored, and both the pid and reference for the monitor are
7335 returned.
7336 spawn_opt(Node, Fun, Options) -> pid() | {pid(), reference()}
7338 Types:
7340 Node = node()
7342 Fun = function()
7343 Options =
7344 [monitor | {monitor, [monitor_option()]} | link | Oth‐
7345 erOption]
7346 OtherOption = term()
7347 Returns the process identifier (pid) of a new process started by
7349 the application of Fun to the empty list [] on Node. If Node
7350 does not exist, a useless pid is returned. Otherwise works like
7351 spawn_opt/4.
7352 Valid options depends on what options are supported by the node
7354 identified by Node. A description of valid Options for the local
7355 node of current OTP version can be found in the documentation of
7356 spawn_opt/4.
7357 spawn_opt(Module, Function, Args, Options) ->
7359 Pid | {Pid, MonitorRef}
7360 Types:
7362 Module = module()
7364 Function = atom()
7365 Args = [term()]
7366 Options = [spawn_opt_option()]
7367 Pid = pid()
7368 MonitorRef = reference()
7369 priority_level() = low | normal | high | max
7370 max_heap_size() =
7371 integer() >= 0 |
7372 #{size => integer() >= 0,
7373 kill => boolean(),
7374 error_logger => boolean()}
7375 message_queue_data() = off_heap | on_heap
7376 spawn_opt_option() =
7377 link | monitor |
7378 {monitor, MonitorOpts :: [monitor_option()]} |
7379 {priority, Level :: priority_level()} |
7380 {fullsweep_after, Number :: integer() >= 0} |
7381 {min_heap_size, Size :: integer() >= 0} |
7382 {min_bin_vheap_size, VSize :: integer() >= 0} |
7383 {max_heap_size, Size :: max_heap_size()} |
7384 {message_queue_data, MQD :: message_queue_data()} |
7385 {async_dist, Enabled :: boolean()}
7386 Works as spawn/3, except that an extra option list is specified
7388 when creating the process.
7389 If option monitor is specified, the newly created process is
7391 monitored, and both the pid and reference for the monitor are
7392 returned.
7393 Options:
7395 link:
7397 Sets a link to the parent process (like spawn_link/3 does).
7398 monitor:
7400 Monitors the new process (like monitor(process, Pid) does).
7401 A {Pid, MonitorRef} tuple will be returned instead of just a
7402 Pid.
7403 {monitor, MonitorOpts}:
7405 Monitors the new process with options (like monitor(process,
7406 Pid, MonitorOpts) does). A {Pid, MonitorRef} tuple will be
7407 returned instead of just a Pid.
7408 {priority, Level}:
7410 Sets the priority of the new process. Equivalent to execut‐
7411 ing process_flag(priority, Level) in the start function of
7412 the new process, except that the priority is set before the
7413 process is selected for execution for the first time. For
7414 more information on priorities, see process_flag(priority,
7415 Level).
7416 {fullsweep_after, Number}:
7418 Useful only for performance tuning. Do not use this option
7419 unless you know that there is problem with execution times
7420 or memory consumption, and ensure that the option improves
7421 matters.
7422 The Erlang runtime system uses a generational garbage col‐
7424 lection scheme, using an "old heap" for data that has sur‐
7425 vived at least one garbage collection. When there is no more
7426 room on the old heap, a fullsweep garbage collection is
7427 done.
7428 Option fullsweep_after makes it possible to specify the max‐
7430 imum number of generational collections before forcing a
7431 fullsweep, even if there is room on the old heap. Setting
7432 the number to zero disables the general collection algo‐
7433 rithm, that is, all live data is copied at every garbage
7434 collection.
7435 A few cases when it can be useful to change fullsweep_after:
7437 * If binaries that are no longer used are to be thrown away
7439 as soon as possible. (Set Number to zero.)
7440 * A process that mostly have short-lived data is fullsweeped
7442 seldom or never, that is, the old heap contains mostly
7443 garbage. To ensure a fullsweep occasionally, set Number to
7444 a suitable value, such as 10 or 20.
7445 * In embedded systems with a limited amount of RAM and no
7447 virtual memory, you might want to preserve memory by set‐
7448 ting Number to zero. (The value can be set globally, see
7449 erlang:system_flag/2.)
7450 {min_heap_size, Size}:
7452 Useful only for performance tuning. Do not use this option
7453 unless you know that there is problem with execution times
7454 or memory consumption, and ensure that the option improves
7455 matters.
7456 Gives a minimum heap size, in words. Setting this value
7458 higher than the system default can speed up some processes
7459 because less garbage collection is done. However, setting a
7460 too high value can waste memory and slow down the system be‐
7461 cause of worse data locality. Therefore, use this option
7462 only for fine-tuning an application and to measure the exe‐
7463 cution time with various Size values.
7464 {min_bin_vheap_size, VSize}:
7466 Useful only for performance tuning. Do not use this option
7467 unless you know that there is problem with execution times
7468 or memory consumption, and ensure that the option improves
7469 matters.
7470 Gives a minimum binary virtual heap size, in words. Setting
7472 this value higher than the system default can speed up some
7473 processes because less garbage collection is done. However,
7474 setting a too high value can waste memory. Therefore, use
7475 this option only for fine-tuning an application and to mea‐
7476 sure the execution time with various VSize values.
7477 {max_heap_size, Size}:
7479 Sets the max_heap_size process flag. The default
7480 max_heap_size is determined by command-line argument +hmax
7481 in erl(1). For more information, see the documentation of
7482 process_flag(max_heap_size, Size).
7483 {message_queue_data, MQD}:
7485 Sets the value of the message_queue_data process flag. MQD
7486 can be either off_heap or on_heap. The default value of the
7487 message_queue_data process flag is determined by the com‐
7488 mand-line argument +hmqd in erl(1). For more information,
7489 see the documentation of process_flag(message_queue_data,
7490 MQD).
7491 {async_dist, Enabled}:
7493 Since: OTP 25.3
7494 Set the async_dist process flag of the spawned process. This
7496 option will override the default value set by the command
7497 line argument +pad <boolean>.
7498 spawn_opt(Node, Module, Function, Args, Options) ->
7500 pid() | {pid(), reference()}
7501 Types:
7503 Node = node()
7505 Module = module()
7506 Function = atom()
7507 Args = [term()]
7508 Options =
7509 [monitor | {monitor, [monitor_option()]} | link | Oth‐
7510 erOption]
7511 OtherOption = term()
7512 Returns the process identifier (pid) of a new process started by
7514 the application of Module:Function to Args on Node. If Node does
7515 not exist, a useless pid is returned. Otherwise works like
7516 spawn_opt/4.
7517 Valid options depends on what options are supported by the node
7519 identified by Node. A description of valid Options for the local
7520 node of current OTP version can be found in the documentation of
7521 spawn_opt/4.
7522 spawn_request(Fun) -> ReqId
7524 Types:
7526 Fun = function()
7528 ReqId = reference()
7529 The same as the call spawn_request(node(),Fun,[]). That is, a
7531 spawn request on the local node with no options.
7532 spawn_request(Fun, Options) -> ReqId
7534 Types:
7536 Fun = function()
7538 Option =
7539 {reply_tag, ReplyTag} | {reply, Reply} | spawn_opt_op‐
7540 tion()
7541 ReplyTag = term()
7542 Reply = yes | no | error_only | success_only
7543 Options = [Option]
7544 ReqId = reference()
7545 The same as the call spawn_request(node(),Fun,Options). That is,
7547 a spawn request on the local node.
7548 spawn_request(Node, Fun) -> ReqId
7550 Types:
7552 Node = node()
7554 Fun = function()
7555 ReqId = reference()
7556 The same as the call spawn_request(Node,Fun,[]). That is, a
7558 spawn request with no options.
7559 spawn_request(Node, Fun, Options) -> ReqId
7561 Types:
7563 Node = node()
7565 Fun = function()
7566 Options = [Option]
7567 Option =
7568 monitor |
7569 {monitor, [monitor_option()]} |
7570 link |
7571 {reply_tag, ReplyTag} |
7572 {reply, Reply} |
7573 OtherOption
7574 ReplyTag = term()
7575 Reply = yes | no | error_only | success_only
7576 OtherOption = term()
7577 ReqId = reference()
7578 The same as spawn_request(Node,erlang,apply,[Fun,[]],Options).
7580 That is, a spawn request using the fun Fun of arity zero as en‐
7581 try point.
7582 This function will fail with a badarg exception if:
7584 * Node is not an atom.
7586 * Fun is not a fun of arity zero.
7588 * Options is not a proper list of terms.
7590 spawn_request(Module, Function, Args) -> ReqId
7592 Types:
7594 Module = module()
7596 Function = atom()
7597 Args = [term()]
7598 ReqId = reference()
7599 The same as the call spawn_request(node(),Module,Func‐
7601 tion,Args,[]). That is, a spawn request on the local node with
7602 no options.
7603 spawn_request(Node, Module, Function, Args) -> ReqId
7605 Types:
7607 Node = node()
7609 Module = module()
7610 Function = atom()
7611 Args = [term()]
7612 ReqId = reference()
7613 The same as the call spawn_request(Node,Module,Func‐
7615 tion,Args,[]). That is, a spawn request with no options.
7616 spawn_request(Module, Function, Args, Options) -> ReqId
7618 Types:
7620 Module = module()
7622 Function = atom()
7623 Args = [term()]
7624 Option =
7625 {reply_tag, ReplyTag} | {reply, Reply} | spawn_opt_op‐
7626 tion()
7627 ReplyTag = term()
7628 Reply = yes | no | error_only | success_only
7629 Options = [Option]
7630 ReqId = reference()
7631 The same as the call spawn_request(node(),Module,Func‐
7633 tion,Args,Options). That is, a spawn request on the local node.
7634 spawn_request(Node, Module, Function, Args, Options) -> ReqId
7636 Types:
7638 Node = node()
7640 Module = module()
7641 Function = atom()
7642 Args = [term()]
7643 Options = [Option]
7644 Option =
7645 monitor |
7646 {monitor, [monitor_option()]} |
7647 link |
7648 {reply_tag, ReplyTag} |
7649 {reply, Reply} |
7650 OtherOption
7651 ReplyTag = term()
7652 Reply = yes | no | error_only | success_only
7653 OtherOption = term()
7654 ReqId = reference()
7655 Asynchronously send a spawn request. Returns a request identi‐
7657 fier ReqId.
7658 If the spawn operation succeeds, a new process is created on the
7660 node identified by Node. When a spawn operation succeeds, the
7661 caller will by default be sent a message on the form {ReplyTag,
7662 ReqId, ok, Pid} where Pid is the process identifier of the newly
7663 created process. Such a message is referred to as a success mes‐
7664 sage below in the text. ReplyTag is by default the atom
7665 spawn_reply unless modified by the {reply_tag, ReplyTag} option.
7666 The new process is started by the application of Module:Function
7667 to Args.
7668 The spawn operation fails either if creation of a new process
7670 failed or if the spawn operation was interrupted by a connection
7671 failure. When a spawn operation fails, the caller will by de‐
7672 fault be sent a message on the form {ReplyTag, ReqId, error,
7673 Reason} where Reason is the error reason. Such a message is re‐
7674 ferred to as an error message below in the text. Currently the
7675 following spawn error Reasons are defined, but other reasons can
7676 appear at any time without prior notice:
7677 badopt:
7679 An invalid Option was passed as argument. Note that differ‐
7680 ent runtime systems may support different options.
7681 notsup:
7683 The node identified by Node does not support spawn opera‐
7684 tions issued by spawn_request().
7685 noconnection:
7687 Failure to set up a connection to the node identified by
7688 Node or the connection to that node was lost during the
7689 spawn operation. In the case the connection was lost, a
7690 process may or may not have been created.
7691 system_limit:
7693 Could not create a new process due to that some system limit
7694 was reached. Typically the process table was full.
7695 Valid Options:
7697 monitor:
7699 In the absence of spawn operation failures, atomically sets
7700 up a monitor to the newly created process. That is, as if
7701 the calling process had called monitor(process, Pid) where
7702 Pid is the process identifier of the newly created process.
7703 The ReqId returned by spawn_request() is also used as moni‐
7704 tor reference as if it was returned from monitor(process,
7705 Pid).
7706 The monitor will not be activated for the calling process
7708 until the spawn operation has succeeded. The monitor can not
7709 be demonitored before the operation has succeeded. A 'DOWN'
7710 message for the corresponding monitor is guaranteed not to
7711 be delivered before a success message that corresponds to
7712 the spawn operation. If the spawn operation fails, no 'DOWN'
7713 message will be delivered.
7714 If the connection between the nodes involved in the spawn
7716 operation is lost during the spawn operation, the spawn op‐
7717 eration will fail with an error reason of noconnection. A
7718 new process may or may not have been created.
7719 {monitor, MonitorOpts}:
7721 In the absence of spawn operation failures, atomically sets
7722 up a monitor to the newly created process. That is, as if
7723 the calling process had called monitor(process, Pid, Moni‐
7724 torOpts) where Pid is the process identifier of the newly
7725 created process. See the monitor option above for more in‐
7726 formation.
7727 Note that the monitor will not be activated for the calling
7729 process until the spawn operation has succeeded. For exam‐
7730 ple, in the case that an alias is created using the monitor
7731 option, the alias will not be active until the monitor is
7732 activated.
7733 link:
7735 In absence of spawn operation failures, atomically sets up a
7736 link between the calling process and the newly created
7737 process. That is, as if the calling process had called
7738 link(Pid) where Pid is the process identifier of the newly
7739 created process.
7740 The link will not be activated for the calling process until
7742 the spawn operation has succeeded. The link can not be re‐
7743 moved before the operation has succeeded. An exit signal due
7744 to the link is guaranteed not to be delivered before a suc‐
7745 cess message that corresponds to the spawn operation. If
7746 the spawn operation fails, no exit signal due to the link
7747 will be delivered to the caller of spawn_request().
7748 If the connection between the nodes involved in the spawn
7750 operation is lost during the spawn operation, the spawn op‐
7751 eration will fail with an error reason of noconnection. A
7752 new process may or may not have been created. If it has been
7753 created, it will be delivered an exit signal with an exit
7754 reason of noconnection.
7755 {reply, Reply}:
7757 Valid Reply values:
7758 yes:
7760 A spawn reply message will be sent to the caller regard‐
7761 less of whether the operation succeeds or not. If the call
7762 to spawn_request() returns without raising an exception
7763 and the reply option is set to yes, the caller is guaran‐
7764 teed to be delivered either a success message or an error
7765 message . The reply option is by default set to yes.
7766 no:
7768 No spawn reply message will be sent to the caller when the
7769 spawn operation completes. This regardless of whether the
7770 operation succeeds or not.
7771 error_only:
7773 No spawn reply message will be sent to the caller if the
7774 spawn operation succeeds, but an error message will be
7775 sent to the caller if the operation fails.
7776 success_only:
7778 No spawn reply message will be sent to the caller if the
7779 spawn operation fails, but a success message will be sent
7780 to the caller if the operation succeeds.
7781 {reply_tag, ReplyTag}:
7783 Sets the reply tag to ReplyTag in the reply message. That
7784 is, in the success or error message that is sent to the
7785 caller due to the spawn operation. The default reply tag is
7786 the atom spawn_reply.
7787 OtherOption:
7789 Other valid options depends on what options are supported by
7790 the node identified by Node. A description of other valid
7791 Options for the local node of current OTP version can be
7792 found in the documentation of spawn_opt/4.
7793 If a spawn reply message is delivered, it is guaranteed to be
7795 delivered before any other signals from the newly spawned
7796 process are delivered to the process issuing the spawn request.
7797 This function will fail with a badarg exception if:
7799 * Node is not an atom.
7801 * Module is not an atom.
7803 * Function is not an atom.
7805 * Args is not a proper list of terms.
7807 * Options is not a proper list of terms.
7809 Note that not all individual Options are checked when the spawn
7811 request is sent. Some Options can only be checked on reception
7812 of the request. Therefore an invalid option does not cause a
7813 badarg exception, but will cause the spawn operation to fail
7814 with an error reason of badopt.
7815 A spawn request can be abandoned by calling spawn_request_aban‐
7817 don/1.
7818 spawn_request_abandon(ReqId :: reference()) -> boolean()
7820 Abandon a previously issued spawn request. ReqId corresponds to
7822 a request identifier previously returned by spawn_request() in a
7823 call from current process. That is, only the process that has
7824 made the request can abandon the request.
7825 A spawn request can only be successfully abandoned until the
7827 spawn request has completed. When a spawn request has been suc‐
7828 cessfully abandoned, the caller will not be effected by future
7829 direct effects of the spawn request itself. For example, it will
7830 not receive a spawn reply message. The request is however not
7831 withdrawn, so a new process may or may not be created due to the
7832 request. If a new process is created after the spawn request was
7833 abandoned, no monitors nor links will be set up to the caller of
7834 spawn_request_abandon/1 due to the spawn request. If the spawn
7835 request included the link option, the process created due to
7836 this request will be sent an exit signal from its parent with
7837 the exit reason abandoned when it is detected that the spawn op‐
7838 eration has succeeded.
7839 Note:
7841 A process created due to a spawn request that has been abandoned
7842 may communicate with its parent as any other process. It is only
7843 the direct effects on the parent of the actual spawn request,
7844 that will be canceled by abandoning a spawn request.
7845 Return values:
7848 true:
7850 The spawn request was successfully abandoned.
7851 false:
7853 No spawn request was abandoned. The ReqId request identifier
7854 did not correspond to an outstanding spawn request issued by
7855 the calling process. The reason for this is either:
7856 * ReqId corresponds to a spawn request previoulsy made by
7858 the calling process. The spawn operation has completed and
7859 a spawn reply has already been delivered to the calling
7860 process unless the spawn reply was disabled in the re‐
7861 quest.
7862 * ReqId does not correspond to a spawn request that has been
7864 made by the calling process.
7865 This function fail with a badarg exception if ReqId is not a
7867 reference.
7868 split_binary(Bin, Pos) -> {binary(), binary()}
7870 Types:
7872 Bin = binary()
7874 Pos = integer() >= 0
7875 0..byte_size(Bin)
7876 Returns a tuple containing the binaries that are the result of
7878 splitting Bin into two parts at position Pos. This is not a de‐
7879 structive operation. After the operation, there are three bina‐
7880 ries altogether. Example:
7881 > B = list_to_binary("0123456789").
7883 <<"0123456789">>
7884 > byte_size(B).
7885 10
7886 > {B1, B2} = split_binary(B,3).
7887 {<<"012">>,<<"3456789">>}
7888 > byte_size(B1).
7889 3
7890 > byte_size(B2).
7891 7
7892 erlang:start_timer(Time, Dest, Msg) -> TimerRef
7894 Types:
7896 Time = integer() >= 0
7898 Dest = pid() | atom()
7899 Msg = term()
7900 TimerRef = reference()
7901 Starts a timer. The same as calling erlang:start_timer(Time,
7903 Dest, Msg, []).
7904 erlang:start_timer(Time, Dest, Msg, Options) -> TimerRef
7906 Types:
7908 Time = integer()
7910 Dest = pid() | atom()
7911 Msg = term()
7912 Options = [Option]
7913 Abs = boolean()
7914 Option = {abs, Abs}
7915 TimerRef = reference()
7916 Starts a timer. When the timer expires, the message {timeout,
7918 TimerRef, Msg} is sent to the process identified by Dest.
7919 Options:
7921 {abs, false}:
7923 This is the default. It means the Time value is interpreted
7924 as a time in milliseconds relative current Erlang monotonic
7925 time.
7926 {abs, true}:
7928 Absolute Time value. The Time value is interpreted as an ab‐
7929 solute Erlang monotonic time in milliseconds.
7930 More Options can be added in the future.
7932 The absolute point in time, the timer is set to expire on, must
7934 be in the interval [ erlang:convert_time_unit(erlang:sys‐
7935 tem_info(start_time), native, millisecond), erlang:con‐
7936 vert_time_unit(erlang:system_info(end_time), native, millisec‐
7937 ond) ]. If a relative time is specified, the Time value is not
7938 allowed to be negative.
7939 If Dest is a pid(), it must be a pid() of a process created on
7941 the current runtime system instance. This process has either
7942 terminated or not. If Dest is an atom(), it is interpreted as
7943 the name of a locally registered process. The process referred
7944 to by the name is looked up at the time of timer expiration. No
7945 error is returned if the name does not refer to a process.
7946 If Dest is a pid(), the timer is automatically canceled if the
7948 process referred to by the pid() is not alive, or if the process
7949 exits. This feature was introduced in ERTS 5.4.11. Notice that
7950 timers are not automatically canceled when Dest is an atom().
7951 See also erlang:send_after/4, erlang:cancel_timer/2, and er‐
7953 lang:read_timer/2.
7954 Failure: badarg if the arguments do not satisfy the requirements
7956 specified here.
7957 statistics(Item :: active_tasks) -> [ActiveTasks]
7959 Types:
7961 ActiveTasks = integer() >= 0
7963 Returns the same as statistics(active_tasks_all) with the excep‐
7965 tion that no information about the dirty IO run queue and its
7966 associated schedulers is part of the result. That is, only tasks
7967 that are expected to be CPU bound are part of the result.
7968 statistics(Item :: active_tasks_all) -> [ActiveTasks]
7970 Types:
7972 ActiveTasks = integer() >= 0
7974 Returns a list where each element represents the amount of ac‐
7976 tive processes and ports on each run queue and its associated
7977 schedulers. That is, the number of processes and ports that are
7978 ready to run, or are currently running. Values for normal run
7979 queues and their associated schedulers are located first in the
7980 resulting list. The first element corresponds to scheduler num‐
7981 ber 1 and so on. If support for dirty schedulers exist, an ele‐
7982 ment with the value for the dirty CPU run queue and its associ‐
7983 ated dirty CPU schedulers follow and then as last element the
7984 value for the the dirty IO run queue and its associated dirty IO
7985 schedulers follow. The information is not gathered atomically.
7986 That is, the result is not necessarily a consistent snapshot of
7987 the state, but instead quite efficiently gathered.
7988 Note:
7990 Each normal scheduler has one run queue that it manages. If
7991 dirty schedulers schedulers are supported, all dirty CPU sched‐
7992 ulers share one run queue, and all dirty IO schedulers share one
7993 run queue. That is, we have multiple normal run queues, one
7994 dirty CPU run queue and one dirty IO run queue. Work can not mi‐
7995 grate between the different types of run queues. Only work in
7996 normal run queues can migrate to other normal run queues. This
7997 has to be taken into account when evaluating the result.
7998 See also statistics(total_active_tasks), statis‐
8001 tics(run_queue_lengths), statistics(run_queue_lengths_all), sta‐
8002 tistics(total_run_queue_lengths), and statistics(to‐
8003 tal_run_queue_lengths_all).
8004 statistics(Item :: context_switches) -> {ContextSwitches, 0}
8006 Types:
8008 ContextSwitches = integer() >= 0
8010 Returns the total number of context switches since the system
8012 started.
8013 statistics(Item :: exact_reductions) ->
8015 {Total_Exact_Reductions,
8016 Exact_Reductions_Since_Last_Call}
8017 Types:
8019 Total_Exact_Reductions = Exact_Reductions_Since_Last_Call =
8021 integer() >= 0
8022 Returns the number of exact reductions.
8024 Note:
8026 statistics(exact_reductions) is a more expensive operation than
8027 statistics(reductions).
8028 statistics(Item :: garbage_collection) ->
8031 {Number_of_GCs, Words_Reclaimed, 0}
8032 Types:
8034 Number_of_GCs = Words_Reclaimed = integer() >= 0
8036 Returns information about garbage collection, for example:
8038 > statistics(garbage_collection).
8040 {85,23961,0}
8041 This information can be invalid for some implementations.
8043 statistics(Item :: io) -> {{input, Input}, {output, Output}}
8045 Types:
8047 Input = Output = integer() >= 0
8049 Returns Input, which is the total number of bytes received
8051 through ports, and Output, which is the total number of bytes
8052 output to ports.
8053 statistics(Item :: microstate_accounting) ->
8055 [MSAcc_Thread] | undefined
8056 Types:
8058 MSAcc_Thread =
8060 #{type := MSAcc_Thread_Type,
8061 id := MSAcc_Thread_Id,
8062 counters := MSAcc_Counters}
8063 MSAcc_Thread_Type =
8064 async | aux | dirty_io_scheduler | dirty_cpu_scheduler |
8065 poll | scheduler
8066 MSAcc_Thread_Id = integer() >= 0
8067 MSAcc_Counters = #{MSAcc_Thread_State => integer() >= 0}
8068 MSAcc_Thread_State =
8069 alloc | aux | bif | busy_wait | check_io | emulator | ets
8070 |
8071 gc | gc_fullsweep | nif | other | port | send | sleep |
8072 timers
8073 Microstate accounting can be used to measure how much time the
8075 Erlang runtime system spends doing various tasks. It is designed
8076 to be as lightweight as possible, but some overhead exists when
8077 this is enabled. Microstate accounting is meant to be a profil‐
8078 ing tool to help finding performance bottlenecks. To
8079 start/stop/reset microstate accounting, use system flag mi‐
8080 crostate_accounting.
8081 statistics(microstate_accounting) returns a list of maps repre‐
8083 senting some of the OS threads within ERTS. Each map contains
8084 type and id fields that can be used to identify what thread it
8085 is, and also a counters field that contains data about how much
8086 time has been spent in the various states.
8087 Example:
8089 > erlang:statistics(microstate_accounting).
8091 [#{counters => #{aux => 1899182914,
8092 check_io => 2605863602,
8093 emulator => 45731880463,
8094 gc => 1512206910,
8095 other => 5421338456,
8096 port => 221631,
8097 sleep => 5150294100},
8098 id => 1,
8099 type => scheduler}|...]
8100 The time unit is the same as returned by os:perf_counter/0. So,
8102 to convert it to milliseconds, you can do something like this:
8103 lists:map(
8105 fun(#{ counters := Cnt } = M) ->
8106 MsCnt = maps:map(fun(_K, PerfCount) ->
8107 erlang:convert_time_unit(PerfCount, perf_counter, 1000)
8108 end, Cnt),
8109 M#{ counters := MsCnt }
8110 end, erlang:statistics(microstate_accounting)).
8111 Notice that these values are not guaranteed to be the exact time
8113 spent in each state. This is because of various optimisation
8114 done to keep the overhead as small as possible.
8115 MSAcc_Thread_Types:
8117 scheduler:
8119 The main execution threads that do most of the work. See erl
8120 +S for more details.
8121 dirty_cpu_scheduler:
8123 The threads for long running cpu intensive work. See erl
8124 +SDcpu for more details.
8125 dirty_io_scheduler:
8127 The threads for long running I/O work. See erl +SDio for
8128 more details.
8129 async:
8131 Async threads are used by various linked-in drivers (mainly
8132 the file drivers) do offload non-CPU intensive work. See erl
8133 +A for more details.
8134 aux:
8136 Takes care of any work that is not specifically assigned to
8137 a scheduler.
8138 poll:
8140 Does the IO polling for the emulator. See erl +IOt for more
8141 details.
8142 The following MSAcc_Thread_States are available. All states are
8144 exclusive, meaning that a thread cannot be in two states at
8145 once. So, if you add the numbers of all counters in a thread,
8146 you get the total runtime for that thread.
8147 aux:
8149 Time spent handling auxiliary jobs.
8150 check_io:
8152 Time spent checking for new I/O events.
8153 emulator:
8155 Time spent executing Erlang processes.
8156 gc:
8158 Time spent doing garbage collection. When extra states are
8159 enabled this is the time spent doing non-fullsweep garbage
8160 collections.
8161 other:
8163 Time spent doing unaccounted things.
8164 port:
8166 Time spent executing ports.
8167 sleep:
8169 Time spent sleeping.
8170 More fine-grained MSAcc_Thread_States can be added through con‐
8172 figure (such as ./configure --with-microstate-accounting=extra).
8173 Enabling these states causes performance degradation when mi‐
8174 crostate accounting is turned off and increases the overhead
8175 when it is turned on.
8176 alloc:
8178 Time spent managing memory. Without extra states this time
8179 is spread out over all other states.
8180 bif:
8182 Time spent in BIFs. Without extra states this time is part
8183 of the emulator state.
8184 busy_wait:
8186 Time spent busy waiting. This is also the state where a
8187 scheduler no longer reports that it is active when using
8188 statistics(scheduler_wall_time). So, if you add all other
8189 states but this and sleep, and then divide that by all time
8190 in the thread, you should get something very similar to the
8191 scheduler_wall_time fraction. Without extra states this time
8192 is part of the other state.
8193 ets:
8195 Time spent executing ETS BIFs. Without extra states this
8196 time is part of the emulator state.
8197 gc_full:
8199 Time spent doing fullsweep garbage collection. Without extra
8200 states this time is part of the gc state.
8201 nif:
8203 Time spent in NIFs. Without extra states this time is part
8204 of the emulator state.
8205 send:
8207 Time spent sending messages (processes only). Without extra
8208 states this time is part of the emulator state.
8209 timers:
8211 Time spent managing timers. Without extra states this time
8212 is part of the other state.
8213 The utility module msacc(3) can be used to more easily analyse
8215 these statistics.
8216 Returns undefined if system flag microstate_accounting is turned
8218 off.
8219 The list of thread information is unsorted and can appear in
8221 different order between calls.
8222 Note:
8224 The threads and states are subject to change without any prior
8225 notice.
8226 statistics(Item :: reductions) ->
8229 {Total_Reductions, Reductions_Since_Last_Call}
8230 Types:
8232 Total_Reductions = Reductions_Since_Last_Call = integer() >=
8234 0
8235 Returns information about reductions, for example:
8237 > statistics(reductions).
8239 {2046,11}
8240 Note:
8242 As from ERTS 5.5 (Erlang/OTP R11B), this value does not include
8243 reductions performed in current time slices of currently sched‐
8244 uled processes. If an exact value is wanted, use statistics(ex‐
8245 act_reductions).
8246 statistics(Item :: run_queue) -> integer() >= 0
8249 Returns the total length of all normal and dirty CPU run queues.
8251 That is, queued work that is expected to be CPU bound. The in‐
8252 formation is gathered atomically. That is, the result is a con‐
8253 sistent snapshot of the state, but this operation is much more
8254 expensive compared to statistics(total_run_queue_lengths), espe‐
8255 cially when a large amount of schedulers is used.
8256 statistics(Item :: run_queue_lengths) -> [RunQueueLength]
8258 Types:
8260 RunQueueLength = integer() >= 0
8262 Returns the same as statistics(run_queue_lengths_all) with the
8264 exception that no information about the dirty IO run queue is
8265 part of the result. That is, only run queues with work that is
8266 expected to be CPU bound is part of the result.
8267 statistics(Item :: run_queue_lengths_all) -> [RunQueueLength]
8269 Types:
8271 RunQueueLength = integer() >= 0
8273 Returns a list where each element represents the amount of pro‐
8275 cesses and ports ready to run for each run queue. Values for
8276 normal run queues are located first in the resulting list. The
8277 first element corresponds to the normal run queue of scheduler
8278 number 1 and so on. If support for dirty schedulers exist, val‐
8279 ues for the dirty CPU run queue and the dirty IO run queue fol‐
8280 low (in that order) at the end. The information is not gathered
8281 atomically. That is, the result is not necessarily a consistent
8282 snapshot of the state, but instead quite efficiently gathered.
8283 Note:
8285 Each normal scheduler has one run queue that it manages. If
8286 dirty schedulers schedulers are supported, all dirty CPU sched‐
8287 ulers share one run queue, and all dirty IO schedulers share one
8288 run queue. That is, we have multiple normal run queues, one
8289 dirty CPU run queue and one dirty IO run queue. Work can not mi‐
8290 grate between the different types of run queues. Only work in
8291 normal run queues can migrate to other normal run queues. This
8292 has to be taken into account when evaluating the result.
8293 See also statistics(run_queue_lengths), statistics(to‐
8296 tal_run_queue_lengths_all), statistics(total_run_queue_lengths),
8297 statistics(active_tasks), statistics(active_tasks_all), and sta‐
8298 tistics(total_active_tasks), statistics(total_active_tasks_all).
8299 statistics(Item :: runtime) ->
8301 {Total_Run_Time, Time_Since_Last_Call}
8302 Types:
8304 Total_Run_Time = Time_Since_Last_Call = integer() >= 0
8306 Returns information about runtime, in milliseconds.
8308 This is the sum of the runtime for all threads in the Erlang
8310 runtime system and can therefore be greater than the wall clock
8311 time.
8312 Warning:
8314 This value might wrap due to limitations in the underlying func‐
8315 tionality provided by the operating system that is used.
8316 Example:
8319 > statistics(runtime).
8321 {1690,1620}
8322 statistics(Item :: scheduler_wall_time) ->
8324 [{SchedulerId, ActiveTime, TotalTime}] | undefined
8325 Types:
8327 SchedulerId = integer() >= 1
8329 ActiveTime = TotalTime = integer() >= 0
8330 Returns information describing how much time normal and dirty
8332 CPU schedulers in the system have been busy. This value is nor‐
8333 mally a better indicator of how much load an Erlang node is un‐
8334 der instead of looking at the CPU utilization provided by tools
8335 such as top or sysstat. This is because scheduler_wall_time also
8336 includes time where the scheduler is waiting for some other rea‐
8337 source (such as an internal mutex) to be available but does not
8338 use the CPU. In order to better understand what a scheduler is
8339 busy doing you can use microstate accounting.
8340 The definition of a busy scheduler is when it is not idle and
8342 not busy waiting for new work, that is:
8343 * Executing process code
8345 * Executing linked-in driver or NIF code
8347 * Executing BIFs, or any other runtime handling
8349 * Garbage collecting
8351 * Handling any other memory management
8353 Notice that a scheduler can also be busy even if the OS has
8355 scheduled out the scheduler thread.
8356 Note:
8358 It is recommended to use the module scheduler instead of this
8359 function directly as it provides an easier way to get the infor‐
8360 mation that you usually want.
8361 If enabled this function returns a list of tuples with {Schedu‐
8364 lerId, ActiveTime, TotalTime}, where SchedulerId is an integer
8365 ID of the scheduler, ActiveTime is the duration the scheduler
8366 has been busy, and TotalTime is the total time duration since
8367 scheduler_wall_time activation for the specific scheduler. The
8368 time unit returned is undefined and can be subject to change be‐
8369 tween releases, OSs, and system restarts. scheduler_wall_time is
8370 only to be used to calculate relative values for scheduler uti‐
8371 lization. The ActiveTime can never exceed TotalTime. The list of
8372 scheduler information is unsorted and can appear in different
8373 order between calls.
8374 The disabled this function returns undefined.
8376 The activation time can differ significantly between schedulers.
8378 Currently dirty schedulers are activated at system start while
8379 normal schedulers are activated some time after the sched‐
8380 uler_wall_time functionality is enabled.
8381 Only information about schedulers that are expected to handle
8383 CPU bound work is included in the return values from this func‐
8384 tion. If you also want information about dirty I/O schedulers,
8385 use statistics(scheduler_wall_time_all) instead.
8386 Normal schedulers will have scheduler identifiers in the range 1
8388 =< SchedulerId =< erlang:system_info(schedulers). Dirty CPU
8389 schedulers will have scheduler identifiers in the range er‐
8390 lang:system_info(schedulers) < SchedulerId =< erlang:sys‐
8391 tem_info(schedulers) + erlang:system_info(dirty_cpu_schedulers).
8392 Note:
8394 The different types of schedulers handle specific types of jobs.
8395 Every job is assigned to a specific scheduler type. Jobs can mi‐
8396 grate between different schedulers of the same type, but never
8397 between schedulers of different types. This fact has to be taken
8398 under consideration when evaluating the result returned.
8399 You can use scheduler_wall_time to calculate scheduler utiliza‐
8402 tion. First you take a sample of the values returned by er‐
8403 lang:statistics(scheduler_wall_time).
8404 > erlang:system_flag(scheduler_wall_time, true).
8406 false
8407 > Ts0 = lists:sort(erlang:statistics(scheduler_wall_time)), ok.
8408 ok
8409 Some time later the user takes another snapshot and calculates
8411 scheduler utilization per scheduler, for example:
8412 > Ts1 = lists:sort(erlang:statistics(scheduler_wall_time)), ok.
8414 ok
8415 > lists:map(fun({{I, A0, T0}, {I, A1, T1}}) -> {I, (A1 - A0)/(T1 - T0)} end, lists:zip(Ts0,Ts1)).
8416 [{1,0.9743474730177548},
8417 {2,0.9744843782751444},
8418 {3,0.9995902361669045},
8419 {4,0.9738012596572161},
8420 {5,0.9717956667018103},
8421 {6,0.9739235846420741},
8422 {7,0.973237033077876},
8423 {8,0.9741297293248656}]
8424 Using the same snapshots to calculate a total scheduler utiliza‐
8426 tion:
8427 > {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.
8429 0.9769136803764825
8430 Total scheduler utilization will equal 1.0 when all schedulers
8432 have been active all the time between the two measurements.
8433 Another (probably more) useful value is to calculate total
8435 scheduler utilization weighted against maximum amount of avail‐
8436 able CPU time:
8437 > WeightedSchedulerUtilization = (TotalSchedulerUtilization * (erlang:system_info(schedulers) + erlang:system_info(dirty_cpu_schedulers))) / erlang:system_info(logical_processors_available).
8439 0.9769136803764825
8440 This weighted scheduler utilization will reach 1.0 when sched‐
8442 ulers are active the same amount of time as maximum available
8443 CPU time. If more schedulers exist than available logical pro‐
8444 cessors, this value may be greater than 1.0.
8445 As of ERTS version 9.0, the Erlang runtime system will as de‐
8447 fault have more schedulers than logical processors. This due to
8448 the dirty schedulers.
8449 Note:
8451 scheduler_wall_time is by default disabled. To enable it, use
8452 erlang:system_flag(scheduler_wall_time, true).
8453 statistics(Item :: scheduler_wall_time_all) ->
8456 [{SchedulerId, ActiveTime, TotalTime}] | undefined
8457 Types:
8459 SchedulerId = integer() >= 1
8461 ActiveTime = TotalTime = integer() >= 0
8462 The same as statistics(scheduler_wall_time), except that it also
8464 include information about all dirty I/O schedulers.
8465 Dirty IO schedulers will have scheduler identifiers in the range
8467 erlang:system_info(schedulers) + erlang:sys‐
8468 tem_info(dirty_cpu_schedulers) < SchedulerId =< erlang:sys‐
8469 tem_info(schedulers) + erlang:system_info(dirty_cpu_schedulers)
8470 + erlang:system_info(dirty_io_schedulers).
8471 Note:
8473 Note that work executing on dirty I/O schedulers are expected to
8474 mainly wait for I/O. That is, when you get high scheduler uti‐
8475 lization on dirty I/O schedulers, CPU utilization is not ex‐
8476 pected to be high due to this work.
8477 statistics(Item :: total_active_tasks) -> ActiveTasks
8480 Types:
8482 ActiveTasks = integer() >= 0
8484 The same as calling lists:sum(statistics(active_tasks)), but
8486 more efficient.
8487 statistics(Item :: total_active_tasks_all) -> ActiveTasks
8489 Types:
8491 ActiveTasks = integer() >= 0
8493 The same as calling lists:sum(statistics(active_tasks_all)), but
8495 more efficient.
8496 statistics(Item :: total_run_queue_lengths) ->
8498 TotalRunQueueLengths
8499 Types:
8501 TotalRunQueueLengths = integer() >= 0
8503 The same as calling lists:sum(statistics(run_queue_lengths)),
8505 but more efficient.
8506 statistics(Item :: total_run_queue_lengths_all) ->
8508 TotalRunQueueLengths
8509 Types:
8511 TotalRunQueueLengths = integer() >= 0
8513 The same as calling lists:sum(statis‐
8515 tics(run_queue_lengths_all)), but more efficient.
8516 statistics(Item :: wall_clock) ->
8518 {Total_Wallclock_Time,
8519 Wallclock_Time_Since_Last_Call}
8520 Types:
8522 Total_Wallclock_Time = Wallclock_Time_Since_Last_Call = inte‐
8524 ger() >= 0
8525 Returns information about wall clock. wall_clock can be used in
8527 the same manner as runtime, except that real time is measured as
8528 opposed to runtime or CPU time.
8529 erlang:suspend_process(Suspendee) -> true
8531 Types:
8533 Suspendee = pid()
8535 Suspends the process identified by Suspendee. The same as call‐
8537 ing erlang:suspend_process(Suspendee, []).
8538 Warning:
8540 This BIF is intended for debugging only.
8541 erlang:suspend_process(Suspendee, OptList) -> boolean()
8544 Types:
8546 Suspendee = pid()
8548 OptList = [Opt]
8549 Opt = unless_suspending | asynchronous | {asynchronous,
8550 term()}
8551 Increases the suspend count on the process identified by Sus‐
8553 pendee and puts it in the suspended state if it is not already
8554 in that state. A suspended process is not scheduled for execu‐
8555 tion until the process has been resumed.
8556 A process can be suspended by multiple processes and can be sus‐
8558 pended multiple times by a single process. A suspended process
8559 does not leave the suspended state until its suspend count
8560 reaches zero. The suspend count of Suspendee is decreased when
8561 erlang:resume_process(Suspendee) is called by the same process
8562 that called erlang:suspend_process(Suspendee). All increased
8563 suspend counts on other processes acquired by a process are au‐
8564 tomatically decreased when the process terminates.
8565 Options (Opts):
8567 asynchronous:
8569 A suspend request is sent to the process identified by Sus‐
8570 pendee. Suspendee eventually suspends unless it is resumed
8571 before it could suspend. The caller of erlang:sus‐
8572 pend_process/2 returns immediately, regardless of whether
8573 Suspendee has suspended yet or not. The point in time when
8574 Suspendee suspends cannot be deduced from other events in
8575 the system. It is only guaranteed that Suspendee eventually
8576 suspends (unless it is resumed). If no asynchronous options
8577 has been passed, the caller of erlang:suspend_process/2 is
8578 blocked until Suspendee has suspended.
8579 {asynchronous, ReplyTag}:
8581 A suspend request is sent to the process identified by Sus‐
8582 pendee. When the suspend request has been processed, a reply
8583 message is sent to the caller of this function. The reply is
8584 on the form {ReplyTag, State} where State is either:
8585 exited:
8587 Suspendee has exited.
8588 suspended:
8590 Suspendee is now suspended.
8591 not_suspended:
8593 Suspendee is not suspended. This can only happen when the
8594 process that issued this request, have called re‐
8595 sume_process(Suspendee) before getting the reply.
8596 Apart from the reply message, the {asynchronous, ReplyTag}
8598 option behaves exactly the same as the asynchronous option
8599 without reply tag.
8600 unless_suspending:
8602 The process identified by Suspendee is suspended unless the
8603 calling process already is suspending Suspendee. If un‐
8604 less_suspending is combined with option asynchronous, a sus‐
8605 pend request is sent unless the calling process already is
8606 suspending Suspendee or if a suspend request already has
8607 been sent and is in transit. If the calling process already
8608 is suspending Suspendee, or if combined with option asyn‐
8609 chronous and a send request already is in transit, false is
8610 returned and the suspend count on Suspendee remains un‐
8611 changed.
8612 If the suspend count on the process identified by Suspendee is
8614 increased, true is returned, otherwise false.
8615 Warning:
8617 This BIF is intended for debugging only.
8618 Warning:
8621 You can easily create deadlocks if processes suspends each other
8622 (directly or in circles). In ERTS versions prior to ERTS version
8623 10.0, the runtime system prevented such deadlocks, but this pre‐
8624 vention has now been removed due to performance reasons.
8625 Failures:
8628 badarg:
8630 If Suspendee is not a process identifier.
8631 badarg:
8633 If the process identified by Suspendee is the same process
8634 as the process calling erlang:suspend_process/2.
8635 badarg:
8637 If the process identified by Suspendee is not alive.
8638 badarg:
8640 If the process identified by Suspendee resides on another
8641 node.
8642 badarg:
8644 If OptList is not a proper list of valid Opts.
8645 system_limit:
8647 If the process identified by Suspendee has been suspended
8648 more times by the calling process than can be represented by
8649 the currently used internal data structures. The system
8650 limit is greater than 2,000,000,000 suspends and will never
8651 be lower.
8652 erlang:system_flag(Flag :: backtrace_depth, Depth) -> OldDepth
8654 Types:
8656 Depth = OldDepth = integer() >= 0
8658 Sets the maximum depth of call stack back-traces in the exit
8660 reason element of 'EXIT' tuples. The flag also limits the stack‐
8661 trace depth returned by process_info item current_stacktrace.
8662 Returns the old value of the flag.
8664 erlang:system_flag(Flag :: cpu_topology, CpuTopology) ->
8666 OldCpuTopology
8667 Types:
8669 CpuTopology = OldCpuTopology = cpu_topology()
8671 cpu_topology() = [LevelEntry :: level_entry()] | undefined
8672 level_entry() =
8673 {LevelTag :: level_tag(), SubLevel :: sub_level()} |
8674 {LevelTag :: level_tag(),
8675 InfoList :: info_list(),
8676 SubLevel :: sub_level()}
8677 level_tag() = core | node | processor | thread
8678 sub_level() =
8679 [LevelEntry :: level_entry()] |
8680 (LogicalCpuId :: {logical, integer() >= 0})
8681 info_list() = []
8682 Warning:
8684 This argument is deprecated. Instead of using this argument, use
8685 command-line argument +sct in erl(1).
8686 When this argument is removed, a final CPU topology to use is
8688 determined at emulator boot time.
8689 Sets the user-defined CpuTopology. The user-defined CPU topology
8692 overrides any automatically detected CPU topology. By passing
8693 undefined as CpuTopology, the system reverts to the CPU topology
8694 automatically detected. The returned value equals the value re‐
8695 turned from erlang:system_info(cpu_topology) before the change
8696 was made.
8697 Returns the old value of the flag.
8699 The CPU topology is used when binding schedulers to logical pro‐
8701 cessors. If schedulers are already bound when the CPU topology
8702 is changed, the schedulers are sent a request to rebind accord‐
8703 ing to the new CPU topology.
8704 The user-defined CPU topology can also be set by passing com‐
8706 mand-line argument +sct to erl(1).
8707 For information on type CpuTopology and more, see erlang:sys‐
8709 tem_info(cpu_topology) as well as command-line flags +sct and
8710 +sbt in erl(1).
8711 erlang:system_flag(Flag :: dirty_cpu_schedulers_online,
8713 DirtyCPUSchedulersOnline) ->
8714 OldDirtyCPUSchedulersOnline
8715 Types:
8717 DirtyCPUSchedulersOnline = OldDirtyCPUSchedulersOnline = in‐
8719 teger() >= 1
8720 Sets the number of dirty CPU schedulers online. Range is 1 <=
8722 DirtyCPUSchedulersOnline <= N, where N is the smallest of the
8723 return values of erlang:system_info(dirty_cpu_schedulers) and
8724 erlang:system_info(schedulers_online).
8725 Returns the old value of the flag.
8727 The number of dirty CPU schedulers online can change if the num‐
8729 ber of schedulers online changes. For example, if 12 schedulers
8730 and 6 dirty CPU schedulers are online, and system_flag/2 is used
8731 to set the number of schedulers online to 6, then the number of
8732 dirty CPU schedulers online is automatically decreased by half
8733 as well, down to 3. Similarly, the number of dirty CPU sched‐
8734 ulers online increases proportionally to increases in the number
8735 of schedulers online.
8736 For more information, see erlang:system_info(dirty_cpu_sched‐
8738 ulers) and erlang:system_info(dirty_cpu_schedulers_online).
8739 erlang:system_flag(Flag :: erts_alloc, Value :: {Alloc, F, V}) ->
8741 ok | notsup
8742 Types:
8744 Alloc = F = atom()
8746 V = integer()
8747 Sets system flags for erts_alloc(3). Alloc is the allocator to
8749 affect, for example binary_alloc. F is the flag to change and V
8750 is the new value.
8751 Only a subset of all erts_alloc flags can be changed at run
8753 time. This subset is currently only the flag sbct.
8754 Returns ok if the flag was set or notsup if not supported by
8756 erts_alloc.
8757 erlang:system_flag(Flag :: fullsweep_after, Number) -> OldNumber
8759 Types:
8761 Number = OldNumber = integer() >= 0
8763 Sets system flag fullsweep_after. Number is a non-negative inte‐
8765 ger indicating how many times generational garbage collections
8766 can be done without forcing a fullsweep collection. The value
8767 applies to new processes, while processes already running are
8768 not affected.
8769 Returns the old value of the flag.
8771 In low-memory systems (especially without virtual memory), set‐
8773 ting the value to 0 can help to conserve memory.
8774 This value can also be set through (OS) environment variable
8776 ERL_FULLSWEEP_AFTER.
8777 erlang:system_flag(Flag :: microstate_accounting, Action) ->
8779 OldState
8780 Types:
8782 Action = true | false | reset
8784 OldState = true | false
8785 Turns on/off microstate accounting measurements. When passing
8787 reset, all counters are reset to 0.
8788 For more information see statistics(microstate_accounting).
8790 erlang:system_flag(Flag :: min_heap_size, MinHeapSize) ->
8792 OldMinHeapSize
8793 Types:
8795 MinHeapSize = OldMinHeapSize = integer() >= 0
8797 Sets the default minimum heap size for processes. The size is
8799 specified in words. The new min_heap_size effects only processes
8800 spawned after the change of min_heap_size has been made.
8801 min_heap_size can be set for individual processes by using
8802 spawn_opt/4 or process_flag/2.
8803 Returns the old value of the flag.
8805 erlang:system_flag(Flag :: min_bin_vheap_size, MinBinVHeapSize) ->
8807 OldMinBinVHeapSize
8808 Types:
8810 MinBinVHeapSize = OldMinBinVHeapSize = integer() >= 0
8812 Sets the default minimum binary virtual heap size for processes.
8814 The size is specified in words. The new min_bin_vhheap_size ef‐
8815 fects only processes spawned after the change of
8816 min_bin_vheap_size has been made. min_bin_vheap_size can be set
8817 for individual processes by using spawn_opt/2,3,4 or
8818 process_flag/2.
8819 Returns the old value of the flag.
8821 erlang:system_flag(Flag :: max_heap_size, MaxHeapSize) ->
8823 OldMaxHeapSize
8824 Types:
8826 MaxHeapSize = OldMaxHeapSize = max_heap_size()
8828 max_heap_size() =
8829 integer() >= 0 |
8830 #{size => integer() >= 0,
8831 kill => boolean(),
8832 error_logger => boolean()}
8833 Sets the default maximum heap size settings for processes. The
8835 size is specified in words. The new max_heap_size effects only
8836 processes spawned efter the change has been made. max_heap_size
8837 can be set for individual processes using spawn_opt/2,3,4 or
8838 process_flag/2.
8839 Returns the old value of the flag.
8841 For details on how the heap grows, see Sizing the heap in the
8843 ERTS internal documentation.
8844 erlang:system_flag(Flag :: multi_scheduling, BlockState) ->
8846 OldBlockState
8847 Types:
8849 BlockState = block | unblock | block_normal | unblock_normal
8851 OldBlockState = blocked | disabled | enabled
8852 If multi-scheduling is enabled, more than one scheduler thread
8854 is used by the emulator. Multi-scheduling can be blocked in two
8855 different ways. Either all schedulers but one is blocked, or all
8856 normal schedulers but one is blocked. When only normal sched‐
8857 ulers are blocked, dirty schedulers are free to continue to
8858 schedule processes.
8859 If BlockState =:= block, multi-scheduling is blocked. That is,
8861 one and only one scheduler thread will execute. If BlockState
8862 =:= unblock and no one else blocks multi-scheduling, and this
8863 process has blocked only once, multi-scheduling is unblocked.
8864 If BlockState =:= block_normal, normal multi-scheduling is
8866 blocked. That is, only one normal scheduler thread will execute,
8867 but multiple dirty schedulers can execute. If BlockState =:= un‐
8868 block_normal and no one else blocks normal multi-scheduling, and
8869 this process has blocked only once, normal multi-scheduling is
8870 unblocked.
8871 One process can block multi-scheduling and normal multi-schedul‐
8873 ing multiple times. If a process has blocked multiple times, it
8874 must unblock exactly as many times as it has blocked before it
8875 has released its multi-scheduling block. If a process that has
8876 blocked multi-scheduling or normal multi-scheduling exits, it
8877 automatically releases its blocking of multi-scheduling and nor‐
8878 mal multi-scheduling.
8879 The return values are disabled, blocked, blocked_normal, or en‐
8881 abled. The returned value describes the state just after the
8882 call to erlang:system_flag(multi_scheduling, BlockState) has
8883 been made. For information about the return values, see er‐
8884 lang:system_info(multi_scheduling).
8885 Note:
8887 Blocking of multi-scheduling and normal multi-scheduling is nor‐
8888 mally not needed. If you feel that you need to use these fea‐
8889 tures, consider it a few more times again. Blocking multi-sched‐
8890 uling is only to be used as a last resort, as it is most likely
8891 a very inefficient way to solve the problem.
8892 See also erlang:system_info(multi_scheduling), erlang:sys‐
8895 tem_info(normal_multi_scheduling_blockers), erlang:sys‐
8896 tem_info(multi_scheduling_blockers), and erlang:sys‐
8897 tem_info(schedulers).
8898 erlang:system_flag(Flag :: outstanding_system_requests_limit,
8900 NewLimit) ->
8901 OldLimit
8902 Types:
8904 NewLimit = OldLimit = 1..134217727
8906 Sets a limit on the amount of outstanding requests made by a
8908 system process orchestrating system wide changes. Currently
8909 there are two such processes:
8910 The Code Purger:
8912 The code purger orchestrates checking of references to old
8913 code before old code is removed from the system.
8914 The Literal Area Collector:
8916 The literal area collector orchestrates copying of refer‐
8917 ences from old literal areas before removal of such areas
8918 from the system.
8919 Each of these processes are allowed to have as many outstanding
8921 requests as this limit is set to. By default this limit is set
8922 to twice the amount of schedulers on the system. This will en‐
8923 sure that schedulers will have enough work scheduled to perform
8924 these operations as quickly as possible at the same time as
8925 other work will be interleaved with this work. Currently used
8926 limit can be checked by calling erlang:system_info(outstand‐
8927 ing_system_requests_limit).
8928 This limit can also be set by passing the command line argument
8930 +zosrl <Limit> to erl.
8931 erlang:system_flag(Flag :: scheduler_bind_type, How) ->
8933 OldBindType
8934 Types:
8936 How = scheduler_bind_type() | default_bind
8938 OldBindType = scheduler_bind_type()
8939 scheduler_bind_type() =
8940 no_node_processor_spread | no_node_thread_spread | no_spread |
8941 processor_spread | spread | thread_spread |
8942 thread_no_node_processor_spread | unbound
8943 Warning:
8945 This argument is deprecated. Instead of using this argument, use
8946 command-line argument +sbt in erl(1). When this argument is re‐
8947 moved, a final scheduler bind type to use is determined at emu‐
8948 lator boot time.
8949 Controls if and how schedulers are bound to logical processors.
8952 When erlang:system_flag(scheduler_bind_type, How) is called, an
8954 asynchronous signal is sent to all schedulers online, causing
8955 them to try to bind or unbind as requested.
8956 Note:
8958 If a scheduler fails to bind, this is often silently ignored, as
8959 it is not always possible to verify valid logical processor
8960 identifiers. If an error is reported, an error event is logged.
8961 To verify that the schedulers have bound as requested, call er‐
8962 lang:system_info(scheduler_bindings).
8963 Schedulers can be bound on newer Linux, Solaris, FreeBSD, and
8966 Windows systems, but more systems will be supported in future
8967 releases.
8968 In order for the runtime system to be able to bind schedulers,
8970 the CPU topology must be known. If the runtime system fails to
8971 detect the CPU topology automatically, it can be defined. For
8972 more information on how to define the CPU topology, see command-
8973 line flag +sct in erl(1).
8974 The runtime system does by default not bind schedulers to logi‐
8976 cal processors.
8977 Note:
8979 If the Erlang runtime system is the only OS process binding
8980 threads to logical processors, this improves the performance of
8981 the runtime system. However, if other OS processes (for example,
8982 another Erlang runtime system) also bind threads to logical pro‐
8983 cessors, there can be a performance penalty instead. Sometimes
8984 this performance penalty can be severe. If so, it is recommended
8985 to not bind the schedulers.
8986 Schedulers can be bound in different ways. Argument How deter‐
8989 mines how schedulers are bound and can be any of the following:
8990 unbound:
8992 Same as command-line argument +sbt u in erl(1).
8993 no_spread:
8995 Same as command-line argument +sbt ns in erl(1).
8996 thread_spread:
8998 Same as command-line argument +sbt ts in erl(1).
8999 processor_spread:
9001 Same as command-line argument +sbt ps in erl(1).
9002 spread:
9004 Same as command-line argument +sbt s in erl(1).
9005 no_node_thread_spread:
9007 Same as command-line argument +sbt nnts in erl(1).
9008 no_node_processor_spread:
9010 Same as command-line argument +sbt nnps in erl(1).
9011 thread_no_node_processor_spread:
9013 Same as command-line argument +sbt tnnps in erl(1).
9014 default_bind:
9016 Same as command-line argument +sbt db in erl(1).
9017 The returned value equals How before flag scheduler_bind_type
9019 was changed.
9020 Failures:
9022 notsup:
9024 If binding of schedulers is not supported.
9025 badarg:
9027 If How is not one of the documented alternatives.
9028 badarg:
9030 If CPU topology information is unavailable.
9031 The scheduler bind type can also be set by passing command-line
9033 argument +sbt to erl(1).
9034 For more information, see erlang:system_info(sched‐
9036 uler_bind_type), erlang:system_info(scheduler_bindings), as well
9037 as command-line flags +sbt and +sct in erl(1).
9038 erlang:system_flag(Flag :: scheduler_wall_time, Boolean) ->
9040 OldBoolean
9041 Types:
9043 Boolean = OldBoolean = boolean()
9045 Try enable or disable scheduler wall time measurements by pass‐
9047 ing Boolean as either true or false.
9048 For more information about how to use scheduler wall time mea‐
9050 surements, see statistics(scheduler_wall_time).
9051 Scheduler wall time measurements has a node global state. It is
9053 either enabled for all processes on the node or disabled for all
9054 processes. Each process has a logical counter initialized as
9055 zero. A call with Boolean as true will increase that counter one
9056 step for the calling process. A call with false will decrease it
9057 one step unless it already is zero. The node global state for
9058 scheduler_wall_time will be enabled as long as there is at least
9059 one process alive with a counter value larger than zero. When a
9060 process terminates, its counter will also disappear. To ensure
9061 scheduler_wall_time is kept enabled, the process that enabled it
9062 must therefore be kept alive.
9063 Returns the old value of the node global state, true if sched‐
9065 uler wall time measurements were enabled, false if it were dis‐
9066 abled.
9067 Scheduler wall time measurements do consume some cpu overhead
9069 and should not be left turned on unless used.
9070 erlang:system_flag(Flag :: schedulers_online, SchedulersOnline) ->
9072 OldSchedulersOnline
9073 Types:
9075 SchedulersOnline = OldSchedulersOnline = integer() >= 1
9077 Sets the number of schedulers online. Range is 1 <= Scheduler‐
9079 sOnline <= erlang:system_info(schedulers).
9080 Returns the old value of the flag.
9082 If the emulator was built with support for dirty schedulers,
9084 changing the number of schedulers online can also change the
9085 number of dirty CPU schedulers online. For example, if 12 sched‐
9086 ulers and 6 dirty CPU schedulers are online, and system_flag/2
9087 is used to set the number of schedulers online to 6, then the
9088 number of dirty CPU schedulers online is automatically decreased
9089 by half as well, down to 3. Similarly, the number of dirty CPU
9090 schedulers online increases proportionally to increases in the
9091 number of schedulers online.
9092 For more information, see erlang:system_info(schedulers) and er‐
9094 lang:system_info(schedulers_online).
9095 erlang:system_flag(Flag :: system_logger, Logger) -> PrevLogger
9097 Types:
9099 Logger = PrevLogger = logger | undefined | pid()
9101 Sets the process that will receive the logging messages gener‐
9103 ated by ERTS. If set to undefined, all logging messages gener‐
9104 ated by ERTS will be dropped. The messages will be in the for‐
9105 mat:
9106 {log,Level,Format,ArgList,Metadata} where
9108 Level = atom(),
9110 Format = string(),
9111 ArgList = list(term()),
9112 Metadata = #{ pid => pid(),
9113 group_leader => pid(),
9114 time := logger:timestamp(),
9115 error_logger := #{ emulator := true, tag := atom() }
9116 If the system_logger process dies, this flag will be reset to
9119 logger.
9120 The default is the process named logger.
9122 Returns the old value of the flag.
9124 Note:
9126 This function is designed to be used by the KERNEL logger. Be
9127 careful if you change it to something else as log messages may
9128 be lost. If you want to intercept emulator log messages, do it
9129 by adding a specialized handler to the KERNEL logger.
9130 erlang:system_flag(Flag :: trace_control_word, TCW) -> OldTCW
9133 Types:
9135 TCW = OldTCW = integer() >= 0
9137 Sets the value of the node trace control word to TCW, which is
9139 to be an unsigned integer. For more information, see function
9140 set_tcw in section "Match Specifications in Erlang" in the
9141 User's Guide.
9142 Returns the old value of the flag.
9144 erlang:system_flag(Flag :: time_offset, Value :: finalize) ->
9146 OldState
9147 Types:
9149 OldState = preliminary | final | volatile
9151 Finalizes the time offset when single time warp mode is used. If
9153 another time warp mode is used, the time offset state is left
9154 unchanged.
9155 Returns the old state identifier, that is:
9157 * If preliminary is returned, finalization was performed and
9159 the time offset is now final.
9160 * If final is returned, the time offset was already in the fi‐
9162 nal state. This either because another erlang:sys‐
9163 tem_flag(time_offset, finalize) call or because no time warp
9164 mode is used.
9165 * If volatile is returned, the time offset cannot be finalized
9167 because multi-time warp mode is used.
9168 erlang:system_info(Item :: update_cpu_info) -> changed | unchanged
9170 Returns information about the current system. The documentation
9172 of this function is broken into the following sections in order
9173 to make it easier to navigate.
9174 Memory Allocation:
9176 allocated_areas, allocator, alloc_util_allocators, alloca‐
9177 tor_sizes
9178 CPU Topology:
9180 cpu_topology, logical_processors, update_cpu_info
9181 Process Information:
9183 fullsweep_after, garbage_collection, heap_sizes, heap_type,
9184 max_heap_size, message_queue_data, min_heap_size,
9185 min_bin_vheap_size, procs
9186 System Limits:
9188 atom_count, atom_limit, ets_count, ets_limit, port_count,
9189 port_limit, process_count, process_limit
9190 System Time:
9192 end_time, os_monotonic_time_source, os_system_time_source,
9193 start_time, time_correction, time_offset, time_warp_mode,
9194 tolerant_timeofday
9195 Scheduler Information:
9197 dirty_cpu_schedulers, dirty_cpu_schedulers_online,
9198 dirty_io_schedulers, multi_scheduling, multi_schedul‐
9199 ing_blockers, normal_multi_scheduling_blockers, sched‐
9200 uler_bind_type, scheduler_bindings, scheduler_id, sched‐
9201 ulers, smp_support, threads, thread_pool_size
9202 Distribution Information:
9204 creation, delayed_node_table_gc, dist, dist_buf_busy_limit,
9205 dist_ctrl
9206 System Information:
9208 c_compiler_used, check_io, compat_rel, debug_compiled,
9209 driver_version, dynamic_trace, dynamic_trace_probes,
9210 emu_flavor, emu_type, info, kernel_poll, loaded, machine,
9211 modified_timing_level, nif_version, otp_release, outstand‐
9212 ing_system_requests_limit, port_parallelism, system_archi‐
9213 tecture, system_logger, system_version, trace_control_word,
9214 version, wordsize
9215 erlang:system_info(Item :: allocated_areas) -> [tuple()]
9217 erlang:system_info(Item :: allocator) ->
9219 {Allocator, Version, Features, Settings}
9220 erlang:system_info(Item :: {allocator, Alloc}) -> [term()]
9222 erlang:system_info(Item :: alloc_util_allocators) -> [Alloc]
9224 erlang:system_info(Item :: {allocator_sizes, Alloc}) -> [term()]
9226 Types:
9228 Allocator = undefined | glibc
9230 Version = [integer() >= 0]
9231 Features = [atom()]
9232 Settings =
9233 [{Subsystem :: atom(),
9234 [{Parameter :: atom(), Value :: term()}]}]
9235 Alloc = atom()
9236 Returns various information about the memory allocators of the
9238 current system (emulator) as specified by Item:
9239 allocated_areas:
9241 Returns a list of tuples with information about miscella‐
9242 neous allocated memory areas.
9243 Each tuple contains an atom describing the type of memory as
9245 first element and the amount of allocated memory in bytes as
9246 second element. When information about allocated and used
9247 memory is present, also a third element is present, contain‐
9248 ing the amount of used memory in bytes.
9249 erlang:system_info(allocated_areas) is intended for debug‐
9251 ging, and the content is highly implementation-dependent.
9252 The content of the results therefore changes when needed
9253 without prior notice.
9254 Notice that the sum of these values is not the total amount
9256 of memory allocated by the emulator. Some values are part of
9257 other values, and some memory areas are not part of the re‐
9258 sult. For information about the total amount of memory allo‐
9259 cated by the emulator, see erlang:memory/0,1.
9260 allocator:
9262 Returns {Allocator, Version, Features, Settings, where:
9263 * Allocator corresponds to the malloc() implementation used.
9265 If Allocator equals undefined, the malloc() implementation
9266 used cannot be identified. glibc can be identified.
9267 * Version is a list of integers (but not a string) repre‐
9269 senting the version of the malloc() implementation used.
9270 * Features is a list of atoms representing the allocation
9272 features used.
9273 * Settings is a list of subsystems, their configurable pa‐
9275 rameters, and used values. Settings can differ between
9276 different combinations of platforms, allocators, and allo‐
9277 cation features. Memory sizes are given in bytes.
9278 See also "System Flags Effecting erts_alloc" in erts_al‐
9280 loc(3).
9281 {allocator, Alloc}:
9283 Returns information about the specified allocator. As from
9284 ERTS 5.6.1, the return value is a list of {instance, Instan‐
9285 ceNo, InstanceInfo} tuples, where InstanceInfo contains in‐
9286 formation about a specific instance of the allocator. If Al‐
9287 loc is not a recognized allocator, undefined is returned. If
9288 Alloc is disabled, false is returned.
9289 Notice that the information returned is highly implementa‐
9291 tion-dependent and can be changed or removed at any time
9292 without prior notice. It was initially intended as a tool
9293 when developing new allocators, but as it can be of interest
9294 for others it has been briefly documented.
9295 The recognized allocators are listed in erts_alloc(3). In‐
9297 formation about super carriers can be obtained from ERTS 8.0
9298 with {allocator, erts_mmap} or from ERTS 5.10.4; the re‐
9299 turned list when calling with {allocator, mseg_alloc} also
9300 includes an {erts_mmap, _} tuple as one element in the list.
9301 After reading the erts_alloc(3) documentation, the returned
9303 information more or less speaks for itself, but it can be
9304 worth explaining some things. Call counts are presented by
9305 two values, the first value is giga calls, and the second
9306 value is calls. mbcs and sbcs denote multi-block carriers,
9307 and single-block carriers, respectively. Sizes are presented
9308 in bytes. When a size is not presented, it is the amount of
9309 something. Sizes and amounts are often presented by three
9310 values:
9311 * The first is the current value.
9313 * The second is the maximum value since the last call to er‐
9315 lang:system_info({allocator, Alloc}).
9316 * The third is the maximum value since the emulator was
9318 started.
9319 If only one value is present, it is the current value.
9321 fix_alloc memory block types are presented by two values.
9322 The first value is the memory pool size and the second value
9323 is the used memory size.
9324 alloc_util_allocators:
9326 Returns a list of the names of all allocators using the ERTS
9327 internal alloc_util framework as atoms. For more informa‐
9328 tion, see section The alloc_util framework in erts_alloc(3).
9329 {allocator_sizes, Alloc}:
9331 Returns various size information for the specified alloca‐
9332 tor. The information returned is a subset of the information
9333 returned by erlang:system_info({allocator, Alloc}).
9334 erlang:system_info(Item :: cpu_topology) -> CpuTopology
9336 erlang:system_info(Item ::
9338 {cpu_topology, defined | detected | used}) ->
9339 CpuTopology
9340 erlang:system_info(Item ::
9342 logical_processors |
9343 logical_processors_available |
9344 logical_processors_online) ->
9345 unknown | integer() >= 1
9346 erlang:system_info(Item :: trace_control_word) ->
9348 integer() >= 0
9349 Types:
9351 cpu_topology() = [LevelEntry :: level_entry()] | undefined
9353 All LevelEntrys of a list must contain the same LevelTag,
9354 except on the top level where both node and processor‐
9355 LevelTags can coexist.
9356 level_entry() =
9357 {LevelTag :: level_tag(), SubLevel :: sub_level()} |
9358 {LevelTag :: level_tag(),
9359 InfoList :: info_list(),
9360 SubLevel :: sub_level()}
9361 {LevelTag, SubLevel} == {LevelTag, [], SubLevel}
9362 level_tag() = core | node | processor | thread
9363 More LevelTags can be introduced in a future release.
9364 sub_level() =
9365 [LevelEntry :: level_entry()] |
9366 (LogicalCpuId :: {logical, integer() >= 0})
9367 info_list() = []
9368 The info_list() can be extended in a future release.
9369 Returns various information about the CPU topology of the cur‐
9371 rent system (emulator) as specified by Item:
9372 cpu_topology:
9374 Returns the CpuTopology currently used by the emulator. The
9375 CPU topology is used when binding schedulers to logical pro‐
9376 cessors. The CPU topology used is the user-defined CPU
9377 topology, if such exists, otherwise the automatically de‐
9378 tected CPU topology, if such exists. If no CPU topology ex‐
9379 ists, undefined is returned.
9380 node refers to Non-Uniform Memory Access (NUMA) nodes.
9382 thread refers to hardware threads (for example, Intel hyper-
9383 threads).
9384 A level in term CpuTopology can be omitted if only one entry
9386 exists and InfoList is empty.
9387 thread can only be a sublevel to core. core can be a sub‐
9389 level to processor or node. processor can be on the top
9390 level or a sublevel to node. node can be on the top level or
9391 a sublevel to processor. That is, NUMA nodes can be proces‐
9392 sor internal or processor external. A CPU topology can con‐
9393 sist of a mix of processor internal and external NUMA nodes,
9394 as long as each logical CPU belongs to one NUMA node. Cache
9395 hierarchy is not part of the CpuTopology type, but will be
9396 in a future release. Other things can also make it into the
9397 CPU topology in a future release. So, expect the CpuTopology
9398 type to change.
9399 {cpu_topology, defined}:
9401 Returns the user-defined CpuTopology. For more information,
9404 see command-line flag +sct in erl(1) and argument cpu_topol‐
9405 ogy.
9406 {cpu_topology, detected}:
9408 Returns the automatically detected CpuTopologyy. The emula‐
9411 tor detects the CPU topology on some newer Linux, Solaris,
9412 FreeBSD, and Windows systems. On Windows system with more
9413 than 32 logical processors, the CPU topology is not de‐
9414 tected.
9415 For more information, see argument cpu_topology.
9417 {cpu_topology, used}:
9419 Returns CpuTopology used by the emulator. For more informa‐
9420 tion, see argument cpu_topology.
9421 logical_processors:
9423 Returns the detected number of logical processors configured
9424 in the system. The return value is either an integer, or the
9425 atom unknown if the emulator cannot detect the configured
9426 logical processors.
9427 logical_processors_available:
9429 Returns the detected number of logical processors available
9430 to the Erlang runtime system. The return value is either an
9431 integer, or the atom unknown if the emulator cannot detect
9432 the available logical processors. The number of available
9433 logical processors is less than or equal to the number of
9434 logical processors online.
9435 logical_processors_online:
9437 Returns the detected number of logical processors online on
9438 the system. The return value is either an integer, or the
9439 atom unknown if the emulator cannot detect logical proces‐
9440 sors online. The number of logical processors online is less
9441 than or equal to the number of logical processors config‐
9442 ured.
9443 cpu_quota:
9445 Returns the detected CPU quota the emulator is limited by.
9446 The return value is an integer saying how many processors'
9447 worth of runtime we get (between 1 and the number of logical
9448 processors), or the atom unknown if the emulator cannot de‐
9449 tect a quota.
9450 update_cpu_info:
9452 The runtime system rereads the CPU information available and
9453 updates its internally stored information about the detected
9454 CPU topology and the number of logical processors config‐
9455 ured, online, available, and cpu quota.
9456 If the CPU information has changed since the last time it
9458 was read, the atom changed is returned, otherwise the atom
9459 unchanged. If the CPU information has changed, you probably
9460 want to adjust the number of schedulers online. You typi‐
9461 cally want to have as many schedulers online as logical pro‐
9462 cessors available.
9463 erlang:system_info(Item :: fullsweep_after) ->
9465 {fullsweep_after, integer() >= 0}
9466 erlang:system_info(Item :: garbage_collection) ->
9468 [{atom(), integer()}]
9469 erlang:system_info(Item :: heap_sizes) -> [integer() >= 0]
9471 erlang:system_info(Item :: heap_type) -> private
9473 erlang:system_info(Item :: max_heap_size) ->
9475 {max_heap_size,
9476 MaxHeapSize :: max_heap_size()}
9477 erlang:system_info(Item :: message_queue_data) ->
9479 message_queue_data()
9480 erlang:system_info(Item :: min_heap_size) ->
9482 {min_heap_size,
9483 MinHeapSize :: integer() >= 1}
9484 erlang:system_info(Item :: min_bin_vheap_size) ->
9486 {min_bin_vheap_size,
9487 MinBinVHeapSize :: integer() >= 1}
9488 erlang:system_info(Item :: process_limit) -> integer() >= 1
9490 Types:
9492 message_queue_data() = off_heap | on_heap
9494 max_heap_size() =
9495 integer() >= 0 |
9496 #{size => integer() >= 0,
9497 kill => boolean(),
9498 error_logger => boolean()}
9499 Returns information about the default process heap settings:
9501 fullsweep_after:
9503 Returns {fullsweep_after, integer() >= 0}, which is the
9504 fullsweep_after garbage collection setting used by default.
9505 For more information, see garbage_collection described be‐
9506 low.
9507 garbage_collection:
9509 Returns a list describing the default garbage collection
9510 settings. A process spawned on the local node by a spawn or
9511 spawn_link uses these garbage collection settings. The de‐
9512 fault settings can be changed by using erlang:system_flag/2.
9513 spawn_opt/2,3,4 can spawn a process that does not use the
9514 default settings.
9515 heap_sizes:
9517 Returns a list of integers representing valid heap sizes in
9518 words. All Erlang heaps are sized from sizes in this list.
9519 heap_type:
9521 Returns the heap type used by the current emulator. One heap
9522 type exists:
9523 private:
9525 Each process has a heap reserved for its use and no ref‐
9526 erences between heaps of different processes are allowed.
9527 Messages passed between processes are copied between
9528 heaps.
9529 max_heap_size:
9531 Returns {max_heap_size, MaxHeapSize}, where MaxHeapSize is
9532 the current system-wide maximum heap size settings for
9533 spawned processes. This setting can be set using the com‐
9534 mand-line flags +hmax, +hmaxk and +hmaxel in erl(1). It can
9535 also be changed at runtime using erlang:sys‐
9536 tem_flag(max_heap_size, MaxHeapSize). For more details about
9537 the max_heap_size process flag, see
9538 process_flag(max_heap_size, MaxHeapSize).
9539 message_queue_data:
9541 Returns the default value of the message_queue_data process
9542 flag, which can be either off_heap or on_heap. The default
9543 value is set by the command-line argument +hmqd in erl(1).
9544 For more information, see the documentation of
9545 process_flag(message_queue_data, MQD).
9546 min_heap_size:
9548 Returns {min_heap_size, MinHeapSize}, where MinHeapSize is
9549 the current system-wide minimum heap size for spawned pro‐
9550 cesses.
9551 min_bin_vheap_size:
9553 Returns {min_bin_vheap_size, MinBinVHeapSize}, where MinBin‐
9554 VHeapSize is the current system-wide minimum binary virtual
9555 heap size for spawned processes.
9556 procs:
9558 Returns a binary containing a string of process and port in‐
9559 formation formatted as in Erlang crash dumps. For more in‐
9560 formation, see section How to interpret the Erlang crash
9561 dumps in the User's Guide.
9562 erlang:system_info(Item :: atom_count) -> integer() >= 1
9564 erlang:system_info(Item :: atom_limit) -> integer() >= 1
9566 erlang:system_info(Item :: ets_count) -> integer() >= 1
9568 erlang:system_info(Item :: ets_limit) -> integer() >= 1
9570 erlang:system_info(Item :: port_parallelism) -> boolean()
9572 erlang:system_info(Item :: port_count) -> integer() >= 0
9574 erlang:system_info(Item :: port_limit) -> integer() >= 1
9576 erlang:system_info(Item :: process_count) -> integer() >= 1
9578 Returns information about the current system (emulator) limits
9580 as specified by Item:
9581 atom_count:
9583 Returns the number of atoms currently existing at the local
9584 node. The value is given as an integer.
9585 atom_limit:
9587 Returns the maximum number of atoms allowed. This limit can
9588 be increased at startup by passing command-line flag +t to
9589 erl(1).
9590 ets_count:
9592 Returns the number of ETS tables currently existing at the
9593 local node.
9594 ets_limit:
9596 Returns the limit for number of ETS tables. This limit is
9597 partially obsolete and number of tables are only limited by
9598 available memory.
9599 port_count:
9601 Returns the number of ports currently existing at the local
9602 node. The value is given as an integer. This is the same
9603 value as returned by length(erlang:ports()), but more effi‐
9604 cient.
9605 port_limit:
9607 Returns the maximum number of simultaneously existing ports
9608 at the local node as an integer. This limit can be config‐
9609 ured at startup by using command-line flag +Q in erl(1).
9610 process_count:
9612 Returns the number of processes currently existing at the
9613 local node. The value is given as an integer. This is the
9614 same value as returned by length(processes()), but more ef‐
9615 ficient.
9616 process_limit:
9618 Returns the maximum number of simultaneously existing pro‐
9619 cesses at the local node. The value is given as an integer.
9620 This limit can be configured at startup by using command-
9621 line flag +P in erl(1).
9622 erlang:system_info(Item :: end_time) -> integer() >= 0
9624 erlang:system_info(Item :: os_monotonic_time_source) ->
9626 [{atom(), term()}]
9627 erlang:system_info(Item :: os_system_time_source) ->
9629 [{atom(), term()}]
9630 erlang:system_info(Item :: smp_support) -> boolean()
9632 erlang:system_info(Item :: thread_pool_size) -> integer() >= 0
9634 erlang:system_info(Item :: time_correction) -> true | false
9636 erlang:system_info(Item :: time_offset) ->
9638 preliminary | final | volatile
9639 erlang:system_info(Item :: time_warp_mode) ->
9641 no_time_warp | single_time_warp |
9642 multi_time_warp
9643 Returns information about the current system (emulator) time as
9645 specified by Item:
9646 end_time:
9648 The last Erlang monotonic time in native time unit that can
9649 be represented internally in the current Erlang runtime sys‐
9650 tem instance. The time between the start time and the end
9651 time is at least a quarter of a millennium.
9652 os_monotonic_time_source:
9654 Returns a list containing information about the source of OS
9655 monotonic time that is used by the runtime system.
9656 If [] is returned, no OS monotonic time is available. The
9658 list contains two-tuples with Keys as first element, and
9659 Values as second element. The order of these tuples is unde‐
9660 fined. The following tuples can be part of the list, but
9661 more tuples can be introduced in the future:
9662 {function, Function}:
9664 Function is the name of the function used. This tuple al‐
9665 ways exists if OS monotonic time is available to the run‐
9666 time system.
9667 {clock_id, ClockId}:
9669 This tuple only exists if Function can be used with dif‐
9670 ferent clocks. ClockId corresponds to the clock identifier
9671 used when calling Function.
9672 {resolution, OsMonotonicTimeResolution}:
9674 Highest possible resolution of current OS monotonic time
9675 source as parts per second. If no resolution information
9676 can be retrieved from the OS, OsMonotonicTimeResolution is
9677 set to the resolution of the time unit of Functions return
9678 value. That is, the actual resolution can be lower than
9679 OsMonotonicTimeResolution. Notice that the resolution does
9680 not say anything about the accuracy or whether the pre‐
9681 cision aligns with the resolution. You do, however, know
9682 that the precision is not better than OsMonotonicTimeReso‐
9683 lution.
9684 {extended, Extended}:
9686 Extended equals yes if the range of time values has been
9687 extended; otherwise Extended equals no. The range must be
9688 extended if Function returns values that wrap fast. This
9689 typically is the case when the return value is a 32-bit
9690 value.
9691 {parallel, Parallel}:
9693 Parallel equals yes if Function is called in parallel from
9694 multiple threads. If it is not called in parallel, because
9695 calls must be serialized, Parallel equals no.
9696 {time, OsMonotonicTime}:
9698 OsMonotonicTime equals current OS monotonic time in native
9699 time unit.
9700 os_system_time_source:
9702 Returns a list containing information about the source of OS
9703 system time that is used by the runtime system.
9704 The list contains two-tuples with Keys as first element, and
9706 Values as second element. The order of these tuples is unde‐
9707 fined. The following tuples can be part of the list, but
9708 more tuples can be introduced in the future:
9709 {function, Function}:
9711 Function is the name of the function used.
9712 {clock_id, ClockId}:
9714 Exists only if Function can be used with different clocks.
9715 ClockId corresponds to the clock identifier used when
9716 calling Function.
9717 {resolution, OsSystemTimeResolution}:
9719 Highest possible resolution of current OS system time
9720 source as parts per second. If no resolution information
9721 can be retrieved from the OS, OsSystemTimeResolution is
9722 set to the resolution of the time unit of Functions return
9723 value. That is, the actual resolution can be lower than
9724 OsSystemTimeResolution. Notice that the resolution does
9725 not say anything about the accuracy or whether the pre‐
9726 cision do align with the resolution. You do, however, know
9727 that the precision is not better than OsSystemTimeResolu‐
9728 tion.
9729 {parallel, Parallel}:
9731 Parallel equals yes if Function is called in parallel from
9732 multiple threads. If it is not called in parallel, because
9733 calls needs to be serialized, Parallel equals no.
9734 {time, OsSystemTime}:
9736 OsSystemTime equals current OS system time in native time
9737 unit.
9738 start_time:
9740 The Erlang monotonic time in native time unit at the time
9741 when current Erlang runtime system instance started.
9742 See also erlang:system_info(end_time).
9744 time_correction:
9746 Returns a boolean value indicating whether time correction
9747 is enabled or not.
9748 time_offset:
9750 Returns the state of the time offset:
9751 preliminary:
9753 The time offset is preliminary, and will be changed and
9754 finalized later. The preliminary time offset is used dur‐
9755 ing the preliminary phase of the single time warp mode.
9756 final:
9758 The time offset is final. This either because no time
9759 warp mode is used, or because the time offset have been
9760 finalized when single time warp mode is used.
9761 volatile:
9763 The time offset is volatile. That is, it can change at any
9764 time. This is because multi-time warp mode is used.
9765 time_warp_mode:
9767 Returns a value identifying the time warp mode that is
9768 used:
9769 no_time_warp:
9771 The no time warp mode is used.
9772 single_time_warp:
9774 The single time warp mode is used.
9775 multi_time_warp:
9777 The multi-time warp mode is used.
9778 tolerant_timeofday:
9780 Returns whether a pre ERTS 7.0 backwards compatible compen‐
9781 sation for sudden changes of system time is enabled or dis‐
9782 abled. Such compensation is enabled when the time offset is
9783 final, and time correction is enabled.
9784 erlang:system_info(Item :: dirty_cpu_schedulers) ->
9786 integer() >= 0
9787 erlang:system_info(Item :: dirty_cpu_schedulers_online) ->
9789 integer() >= 0
9790 erlang:system_info(Item :: dirty_io_schedulers) ->
9792 integer() >= 0
9793 erlang:system_info(Item :: multi_scheduling) ->
9795 disabled | blocked | blocked_normal |
9796 enabled
9797 erlang:system_info(Item :: multi_scheduling_blockers) ->
9799 [Pid :: pid()]
9800 erlang:system_info(Item :: normal_multi_scheduling_blockers) ->
9802 [Pid :: pid()]
9803 erlang:system_info(Item :: procs) -> binary()
9805 erlang:system_info(Item :: scheduler_bind_type) ->
9807 spread | processor_spread | thread_spread |
9808 thread_no_node_processor_spread |
9809 no_node_processor_spread |
9810 no_node_thread_spread | no_spread | unbound
9811 erlang:system_info(Item :: scheduler_bindings) -> tuple()
9813 erlang:system_info(Item :: scheduler_id) ->
9815 SchedulerId :: integer() >= 1
9816 erlang:system_info(Item :: schedulers | schedulers_online) ->
9818 integer() >= 1
9819 erlang:system_info(Item :: system_version) -> string()
9821 erlang:system_info(Item :: threads) -> boolean()
9823 Returns information about schedulers, scheduling and threads in
9825 the current system as specified by Item:
9826 dirty_cpu_schedulers:
9828 Returns the number of dirty CPU scheduler threads used by
9829 the emulator. Dirty CPU schedulers execute CPU-bound native
9830 functions, such as NIFs, linked-in driver code, and BIFs
9831 that cannot be managed cleanly by the normal emulator sched‐
9832 ulers.
9833 The number of dirty CPU scheduler threads is determined at
9835 emulator boot time and cannot be changed after that. How‐
9836 ever, the number of dirty CPU scheduler threads online can
9837 be changed at any time. The number of dirty CPU schedulers
9838 can be set at startup by passing command-line flag +SDcpu or
9839 +SDPcpu in erl(1).
9840 See also erlang:system_flag(dirty_cpu_schedulers_online,
9842 DirtyCPUSchedulersOnline), erlang:sys‐
9843 tem_info(dirty_cpu_schedulers_online), erlang:sys‐
9844 tem_info(dirty_io_schedulers), erlang:system_info(sched‐
9845 ulers), erlang:system_info(schedulers_online), and er‐
9846 lang:system_flag(schedulers_online, SchedulersOnline).
9847 dirty_cpu_schedulers_online:
9849 Returns the number of dirty CPU schedulers online. The re‐
9850 turn value satisfies 1 <= DirtyCPUSchedulersOnline <= N,
9851 where N is the smallest of the return values of erlang:sys‐
9852 tem_info(dirty_cpu_schedulers) and erlang:system_info(sched‐
9853 ulers_online).
9854 The number of dirty CPU schedulers online can be set at
9856 startup by passing command-line flag +SDcpu in erl(1).
9857 For more information, see erlang:sys‐
9859 tem_info(dirty_cpu_schedulers), erlang:sys‐
9860 tem_info(dirty_io_schedulers), erlang:system_info(sched‐
9861 ulers_online), and erlang:system_flag(dirty_cpu_sched‐
9862 ulers_online, DirtyCPUSchedulersOnline).
9863 dirty_io_schedulers:
9865 Returns the number of dirty I/O schedulers as an integer.
9866 Dirty I/O schedulers execute I/O-bound native functions,
9867 such as NIFs and linked-in driver code, which cannot be man‐
9868 aged cleanly by the normal emulator schedulers.
9869 This value can be set at startup by passing command-line ar‐
9871 gument +SDio in erl(1).
9872 For more information, see erlang:sys‐
9874 tem_info(dirty_cpu_schedulers), erlang:sys‐
9875 tem_info(dirty_cpu_schedulers_online), and erlang:sys‐
9876 tem_flag(dirty_cpu_schedulers_online, DirtyCPUSchedulersOn‐
9877 line).
9878 multi_scheduling:
9880 Returns one of the following:
9881 disabled:
9883 The emulator has been started with only one scheduler
9884 thread.
9885 blocked:
9887 The emulator has more than one scheduler thread, but all
9888 scheduler threads except one are blocked. That is, only
9889 one scheduler thread schedules Erlang processes and exe‐
9890 cutes Erlang code.
9891 blocked_normal:
9893 The emulator has more than one scheduler thread, but all
9894 normal scheduler threads except one are blocked. Notice
9895 that dirty schedulers are not blocked, and can schedule
9896 Erlang processes and execute native code.
9897 enabled:
9899 The emulator has more than one scheduler thread, and no
9900 scheduler threads are blocked. That is, all available
9901 scheduler threads schedule Erlang processes and execute
9902 Erlang code.
9903 See also erlang:system_flag(multi_scheduling, BlockState),
9905 erlang:system_info(multi_scheduling_blockers), erlang:sys‐
9906 tem_info(normal_multi_scheduling_blockers), and erlang:sys‐
9907 tem_info(schedulers).
9908 multi_scheduling_blockers:
9910 Returns a list of Pids when multi-scheduling is blocked,
9911 otherwise the empty list is returned. The Pids in the list
9912 represent all the processes currently blocking multi-sched‐
9913 uling. A Pid occurs only once in the list, even if the cor‐
9914 responding process has blocked multiple times.
9915 See also erlang:system_flag(multi_scheduling, BlockState),
9917 erlang:system_info(multi_scheduling), erlang:sys‐
9918 tem_info(normal_multi_scheduling_blockers), and erlang:sys‐
9919 tem_info(schedulers).
9920 normal_multi_scheduling_blockers:
9922 Returns a list of Pids when normal multi-scheduling is
9923 blocked (that is, all normal schedulers but one is blocked),
9924 otherwise the empty list is returned. The Pids in the list
9925 represent all the processes currently blocking normal multi-
9926 scheduling. A Pid occurs only once in the list, even if the
9927 corresponding process has blocked multiple times.
9928 See also erlang:system_flag(multi_scheduling, BlockState),
9930 erlang:system_info(multi_scheduling), erlang:sys‐
9931 tem_info(multi_scheduling_blockers), and erlang:sys‐
9932 tem_info(schedulers).
9933 scheduler_bind_type:
9935 Returns information about how the user has requested sched‐
9936 ulers to be bound or not bound.
9937 Notice that although a user has requested schedulers to be
9939 bound, they can silently have failed to bind. To inspect the
9940 scheduler bindings, call erlang:system_info(scheduler_bind‐
9941 ings).
9942 For more information, see command-line argument +sbt in
9944 erl(1) and erlang:system_info(scheduler_bindings).
9945 scheduler_bindings:
9947 Returns information about the currently used scheduler bind‐
9948 ings.
9949 A tuple of a size equal to erlang:system_info(schedulers) is
9951 returned. The tuple elements are integers or the atom un‐
9952 bound. Logical processor identifiers are represented as in‐
9953 tegers. The Nth element of the tuple equals the current
9954 binding for the scheduler with the scheduler identifier
9955 equal to N. For example, if the schedulers are bound, ele‐
9956 ment(erlang:system_info(scheduler_id), erlang:sys‐
9957 tem_info(scheduler_bindings)) returns the identifier of the
9958 logical processor that the calling process is executing on.
9959 Notice that only schedulers online can be bound to logical
9961 processors.
9962 For more information, see command-line argument +sbt in
9964 erl(1) and erlang:system_info(schedulers_online).
9965 scheduler_id:
9967 Returns the scheduler ID (SchedulerId) of the scheduler
9968 thread that the calling process is executing on. SchedulerId
9969 is a positive integer, where 1 <= SchedulerId <= erlang:sys‐
9970 tem_info(schedulers).
9971 See also erlang:system_info(schedulers).
9973 schedulers:
9975 Returns the number of scheduler threads used by the emula‐
9976 tor. Scheduler threads online schedules Erlang processes and
9977 Erlang ports, and execute Erlang code and Erlang linked-in
9978 driver code.
9979 The number of scheduler threads is determined at emulator
9981 boot time and cannot be changed later. However, the number
9982 of schedulers online can be changed at any time.
9983 See also erlang:system_flag(schedulers_online, SchedulersOn‐
9985 line), erlang:system_info(schedulers_online), erlang:sys‐
9986 tem_info(scheduler_id), erlang:system_flag(multi_scheduling,
9987 BlockState), erlang:system_info(multi_scheduling), er‐
9988 lang:system_info(normal_multi_scheduling_blockers) and er‐
9989 lang:system_info(multi_scheduling_blockers).
9990 schedulers_online:
9992 Returns the number of schedulers online. The scheduler iden‐
9993 tifiers of schedulers online satisfy the relationship 1 <=
9994 SchedulerId <= erlang:system_info(schedulers_online).
9995 For more information, see erlang:system_info(schedulers) and
9997 erlang:system_flag(schedulers_online, SchedulersOnline).
9998 smp_support:
10000 Returns true.
10001 threads:
10003 Returns true.
10004 thread_pool_size:
10006 Returns the number of async threads in the async thread pool
10009 used for asynchronous driver calls
10010 (erl_driver:driver_async()). The value is given as an inte‐
10011 ger.
10012 erlang:system_info(Item :: async_dist) -> boolean()
10014 erlang:system_info(Item :: creation) -> integer()
10016 erlang:system_info(Item :: delayed_node_table_gc) ->
10018 infinity | integer() >= 0
10019 erlang:system_info(Item :: dist) -> binary()
10021 erlang:system_info(Item :: dist_buf_busy_limit) ->
10023 integer() >= 0
10024 erlang:system_info(Item :: dist_ctrl) ->
10026 [{Node :: node(),
10027 ControllingEntity :: port() | pid()}]
10028 Returns information about Erlang Distribution in the current
10030 system as specified by Item:
10031 async_dist:
10033 Since: OTP 25.3
10034 Returns the value of the command line argument +pad <bool‐
10036 ean> which the runtime system use. This value determines the
10037 default async_dist value for newly spawned processes.
10038 creation:
10040 Returns the creation of the local node as an integer. The
10041 creation is changed when a node is restarted. The creation
10042 of a node is stored in process identifiers, port identi‐
10043 fiers, and references. This makes it (to some extent) possi‐
10044 ble to distinguish between identifiers from different incar‐
10045 nations of a node. The valid creations are integers in the
10046 range 1..3, but this will probably change in a future re‐
10047 lease. If the node is not alive, 0 is returned.
10048 delayed_node_table_gc:
10050 Returns the amount of time in seconds garbage collection of
10051 an entry in a node table is delayed. This limit can be set
10052 on startup by passing command-line flag +zdntgc to erl(1).
10053 For more information, see the documentation of the command-
10054 line flag.
10055 dist:
10057 Returns a binary containing a string of distribution infor‐
10058 mation formatted as in Erlang crash dumps. For more informa‐
10059 tion, see section How to interpret the Erlang crash dumps
10060 in the User's Guide.
10061 dist_buf_busy_limit:
10063 Returns the value of the distribution buffer busy limit in
10064 bytes. This limit can be set at startup by passing command-
10065 line flag +zdbbl to erl(1).
10066 dist_ctrl:
10068 Returns a list of tuples {Node, ControllingEntity}, one en‐
10069 try for each connected remote node. Node is the node name
10070 and ControllingEntity is the port or process identifier re‐
10071 sponsible for the communication to that node. More specifi‐
10072 cally, ControllingEntity for nodes connected through TCP/IP
10073 (the normal case) is the socket used in communication with
10074 the specific node.
10075 erlang:system_info(Item :: c_compiler_used) -> {atom(), term()}
10077 erlang:system_info(Item :: check_io) -> [term()]
10079 erlang:system_info(Item :: compat_rel) -> integer()
10081 erlang:system_info(Item :: debug_compiled) -> boolean()
10083 erlang:system_info(Item :: driver_version) -> string()
10085 erlang:system_info(Item :: dynamic_trace) ->
10087 none | dtrace | systemtap
10088 erlang:system_info(Item :: dynamic_trace_probes) -> boolean()
10090 erlang:system_info(Item :: emu_flavor) -> emu | jit
10092 erlang:system_info(Item :: emu_type) ->
10094 opt | debug | gcov | valgrind | gprof |
10095 lcnt | frmptr
10096 erlang:system_info(Item :: info) -> binary()
10098 erlang:system_info(Item :: kernel_poll) -> boolean()
10100 erlang:system_info(Item :: loaded) -> binary()
10102 erlang:system_info(Item :: machine) -> string()
10104 erlang:system_info(Item :: modified_timing_level) ->
10106 integer() | undefined
10107 erlang:system_info(Item :: nif_version) -> string()
10109 erlang:system_info(Item :: otp_release) -> string()
10111 erlang:system_info(Item :: outstanding_system_requests_limit) ->
10113 1..134217727
10114 erlang:system_info(Item :: port_parallelism) -> boolean()
10116 erlang:system_info(Item :: system_architecture) -> string()
10118 erlang:system_info(Item :: system_logger) ->
10120 logger | undefined | pid()
10121 erlang:system_info(Item :: system_version) -> string()
10123 erlang:system_info(Item :: trace_control_word) ->
10125 integer() >= 0
10126 erlang:system_info(Item :: version) -> string()
10128 erlang:system_info(Item ::
10130 wordsize |
10131 {wordsize, internal} |
10132 {wordsize, external}) ->
10133 4 | 8
10134 Returns various information about the current system (emulator)
10136 as specified by Item:
10137 build_type:
10139 Deprecated, use emu_type instead
10140 c_compiler_used:
10142 Returns a two-tuple describing the C compiler used when com‐
10143 piling the runtime system. The first element is an atom de‐
10144 scribing the name of the compiler, or undefined if unknown.
10145 The second element is a term describing the version of the
10146 compiler, or undefined if unknown.
10147 check_io:
10149 Returns a list containing miscellaneous information about
10150 the emulators internal I/O checking. Notice that the content
10151 of the returned list can vary between platforms and over
10152 time. It is only guaranteed that a list is returned.
10153 compat_rel:
10155 Returns the compatibility mode of the local node as an inte‐
10156 ger. The integer returned represents the Erlang/OTP release
10157 that the current emulator has been set to be backward com‐
10158 patible with. The compatibility mode can be configured at
10159 startup by using command-line flag +R in erl(1).
10160 debug_compiled:
10162 Returns true if the emulator has been debug-compiled, other‐
10163 wise false.
10164 driver_version:
10166 Returns a string containing the Erlang driver version used
10167 by the runtime system. It has the form "<major ver>.<minor
10168 ver>".
10169 dynamic_trace:
10171 Returns an atom describing the dynamic trace framework com‐
10172 piled into the virtual machine. It can be dtrace, systemtap,
10173 or none. For a commercial or standard build, it is always
10174 none. The other return values indicate a custom configura‐
10175 tion (for example, ./configure --with-dynamic-trace=dtrace).
10176 For more information about dynamic tracing, see dyntrace(3)
10177 manual page and the README.dtrace/README.systemtap files in
10178 the Erlang source code top directory.
10179 dynamic_trace_probes:
10181 Returns a boolean() indicating if dynamic trace probes
10182 (dtrace or systemtap) are built into the emulator. This can
10183 only be true if the virtual machine was built for dynamic
10184 tracing (that is, system_info(dynamic_trace) returns dtrace
10185 or systemtap).
10186 emu_flavor:
10188 Returns an atom describing the flavor of the runtime system.
10189 This will be either emu or jit. Possible return values can
10190 be added or removed at any time without prior notice.
10191 emu_type:
10193 Returns an atom describing the build type of the runtime
10194 system. This is normally the atom opt for optimized. Other
10195 possible return values are debug, gcov, valgrind, gprof, and
10196 lcnt. Possible return values can be added or removed at any
10197 time without prior notice.
10198 info:
10200 Returns a binary containing a string of miscellaneous system
10201 information formatted as in Erlang crash dumps. For more in‐
10202 formation, see section How to interpret the Erlang crash
10203 dumps in the User's Guide.
10204 kernel_poll:
10206 Returns true if the emulator uses some kind of kernel-poll
10207 implementation, otherwise false.
10208 loaded:
10210 Returns a binary containing a string of loaded module infor‐
10211 mation formatted as in Erlang crash dumps. For more informa‐
10212 tion, see section How to interpret the Erlang crash dumps in
10213 the User's Guide.
10214 machine:
10216 Returns a string containing the Erlang machine name.
10217 modified_timing_level:
10219 Returns the modified timing-level (an integer) if modified
10220 timing is enabled, otherwise undefined. For more information
10221 about modified timing, see command-line flag +T in erl(1)
10222 nif_version:
10224 Returns a string containing the version of the Erlang NIF
10225 interface used by the runtime system. It is on the form
10226 "<major ver>.<minor ver>".
10227 otp_release:
10229 Returns a string containing the OTP release number of the
10232 OTP release that the currently executing ERTS application is
10233 part of.
10234 As from Erlang/OTP 17, the OTP release number corresponds to
10236 the major OTP version number. No erlang:system_info() argu‐
10237 ment gives the exact OTP version. This is because the exact
10238 OTP version in the general case is difficult to determine.
10239 For more information, see the description of versions in
10240 System principles in System Documentation.
10241 outstanding_system_requests_limit:
10243 Returns the limit on the amount of outstanding requests made
10244 by a system process orchestrating system wide changes. See
10245 erlang:system_flag(outstanding_system_requests_limit, Limit)
10246 for more information.
10247 port_parallelism:
10249 Returns the default port parallelism scheduling hint used.
10250 For more information, see command-line argument +spp in
10251 erl(1).
10252 system_architecture:
10254 Returns a string containing the processor and OS architec‐
10255 ture the emulator is built for.
10256 system_logger:
10258 Returns the current system_logger as set by erlang:sys‐
10259 tem_flag(system_logger, _).
10260 system_version:
10262 Returns a string containing version number and some impor‐
10263 tant properties, such as the number of schedulers.
10264 trace_control_word:
10266 Returns the value of the node trace control word. For more
10267 information, see function get_tcw in section Match Specifi‐
10268 cations in Erlang in the User's Guide.
10269 version:
10271 Returns a string containing the version number of the emula‐
10272 tor.
10273 wordsize:
10275 Same as {wordsize, internal}.
10276 {wordsize, internal}:
10278 Returns the size of Erlang term words in bytes as an inte‐
10279 ger, that is, 4 is returned on a 32-bit architecture, and 8
10280 is returned on a 64-bit architecture.
10281 {wordsize, external}:
10283 Returns the true word size of the emulator, that is, the
10284 size of a pointer. The value is given in bytes as an inte‐
10285 ger. On a pure 32-bit architecture, 4 is returned. On a
10286 64-bit architecture, 8 is returned.
10287 erlang:system_monitor() -> MonSettings
10289 Types:
10291 MonSettings = undefined | {MonitorPid, Options}
10293 MonitorPid = pid()
10294 Options = [system_monitor_option()]
10295 system_monitor_option() =
10296 busy_port | busy_dist_port |
10297 {long_gc, integer() >= 0} |
10298 {long_schedule, integer() >= 0} |
10299 {large_heap, integer() >= 0}
10300 Returns the current system monitoring settings set by er‐
10302 lang:system_monitor/2 as {MonitorPid, Options}, or undefined if
10303 no settings exist. The order of the options can be different
10304 from the one that was set.
10305 erlang:system_monitor(Arg) -> MonSettings
10307 Types:
10309 Arg = MonSettings = undefined | {MonitorPid, Options}
10311 MonitorPid = pid()
10312 Options = [system_monitor_option()]
10313 system_monitor_option() =
10314 busy_port | busy_dist_port |
10315 {long_gc, integer() >= 0} |
10316 {long_schedule, integer() >= 0} |
10317 {large_heap, integer() >= 0}
10318 When called with argument undefined, all system performance mon‐
10320 itoring settings are cleared.
10321 Calling the function with {MonitorPid, Options} as argument is
10323 the same as calling erlang:system_monitor(MonitorPid, Options).
10324 Returns the previous system monitor settings just like er‐
10326 lang:system_monitor/0.
10327 erlang:system_monitor(MonitorPid, Options) -> MonSettings
10329 Types:
10331 MonitorPid = pid()
10333 Options = [system_monitor_option()]
10334 MonSettings = undefined | {OldMonitorPid, OldOptions}
10335 OldMonitorPid = pid()
10336 OldOptions = [system_monitor_option()]
10337 system_monitor_option() =
10338 busy_port | busy_dist_port |
10339 {long_gc, integer() >= 0} |
10340 {long_schedule, integer() >= 0} |
10341 {large_heap, integer() >= 0}
10342 Sets the system performance monitoring options. MonitorPid is a
10344 local process identifier (pid) receiving system monitor mes‐
10345 sages. The second argument is a list of monitoring options:
10346 {long_gc, Time}:
10348 If a garbage collection in the system takes at least Time
10349 wall clock milliseconds, a message {monitor, GcPid, long_gc,
10350 Info} is sent to MonitorPid. GcPid is the pid that was
10351 garbage collected. Info is a list of two-element tuples de‐
10352 scribing the result of the garbage collection.
10353 One of the tuples is {timeout, GcTime}, where GcTime is the
10355 time for the garbage collection in milliseconds. The other
10356 tuples are tagged with heap_size, heap_block_size,
10357 stack_size, mbuf_size, old_heap_size, and
10358 old_heap_block_size. These tuples are explained in the de‐
10359 scription of trace message gc_minor_start (see er‐
10360 lang:trace/3). New tuples can be added, and the order of the
10361 tuples in the Info list can be changed at any time without
10362 prior notice.
10363 {long_schedule, Time}:
10365 If a process or port in the system runs uninterrupted for at
10366 least Time wall clock milliseconds, a message {monitor, Pi‐
10367 dOrPort, long_schedule, Info} is sent to MonitorPid. PidOr‐
10368 Port is the process or port that was running. Info is a list
10369 of two-element tuples describing the event.
10370 If a pid(), the tuples {timeout, Millis}, {in, Location},
10372 and {out, Location} are present, where Location is either an
10373 MFA ({Module, Function, Arity}) describing the function
10374 where the process was scheduled in/out, or the atom unde‐
10375 fined.
10376 If a port(), the tuples {timeout, Millis} and {port_op,Op}
10378 are present. Op is one of proc_sig, timeout, input, output,
10379 event, or dist_cmd, depending on which driver callback was
10380 executing.
10381 proc_sig is an internal operation and is never to appear,
10383 while the others represent the corresponding driver call‐
10384 backs timeout, ready_input, ready_output, event, and outputv
10385 (when the port is used by distribution). Value Millis in tu‐
10386 ple timeout informs about the uninterrupted execution time
10387 of the process or port, which always is equal to or higher
10388 than the Time value supplied when starting the trace. New
10389 tuples can be added to the Info list in a future release.
10390 The order of the tuples in the list can be changed at any
10391 time without prior notice.
10392 This can be used to detect problems with NIFs or drivers
10394 that take too long to execute. 1 ms is considered a good
10395 maximum time for a driver callback or a NIF. However, a
10396 time-sharing system is usually to consider everything < 100
10397 ms as "possible" and fairly "normal". However, longer sched‐
10398 ule times can indicate swapping or a misbehaving NIF/driver.
10399 Misbehaving NIFs and drivers can cause bad resource utiliza‐
10400 tion and bad overall system performance.
10401 {large_heap, Size}:
10403 If a garbage collection in the system results in the allo‐
10404 cated size of a heap being at least Size words, a message
10405 {monitor, GcPid, large_heap, Info} is sent to MonitorPid.
10406 GcPid and Info are the same as for long_gc earlier, except
10407 that the tuple tagged with timeout is not present.
10408 The monitor message is sent if the sum of the sizes of all
10410 memory blocks allocated for all heap generations after a
10411 garbage collection is equal to or higher than Size.
10412 When a process is killed by max_heap_size, it is killed be‐
10414 fore the garbage collection is complete and thus no large
10415 heap message is sent.
10416 busy_port:
10418 If a process in the system gets suspended because it sends
10419 to a busy port, a message {monitor, SusPid, busy_port, Port}
10420 is sent to MonitorPid. SusPid is the pid that got suspended
10421 when sending to Port.
10422 busy_dist_port:
10424 If a process in the system gets suspended because it sends
10425 to a process on a remote node whose inter-node communication
10426 was handled by a busy port, a message {monitor, SusPid,
10427 busy_dist_port, Port} is sent to MonitorPid. SusPid is the
10428 pid that got suspended when sending through the inter-node
10429 communication port Port.
10430 Returns the previous system monitor settings just like er‐
10432 lang:system_monitor/0.
10433 The arguments to system_monitor/2 specifies how all system moni‐
10435 toring on the node should be done, not how it should be changed.
10436 This means only one process at a time (MonitorPid) can be the
10437 receiver of system monitor messages. Also, the way to clear a
10438 specific monitor option is to not include it in the list Op‐
10439 tions. All system monitoring will, however, be cleared if the
10440 process identified by MonitorPid terminates.
10441 There are no special option values (like zero) to clear an op‐
10443 tion. Some of the options have a unspecified minimum value.
10444 Lower values will be adjusted to the minimum value. For example,
10445 it is currently not possible to monitor all garbage collections
10446 with {long_gc, 0}.
10447 Note:
10449 If a monitoring process gets so large that it itself starts to
10450 cause system monitor messages when garbage collecting, the mes‐
10451 sages enlarge the process message queue and probably make the
10452 problem worse.
10453 Keep the monitoring process neat and do not set the system moni‐
10455 tor limits too tight.
10456 Failures:
10459 badarg:
10461 If MonitorPid does not exist.
10462 badarg:
10464 If MonitorPid is not a local process.
10465 erlang:system_profile() -> ProfilerSettings
10467 Types:
10469 ProfilerSettings = undefined | {ProfilerPid, Options}
10471 ProfilerPid = pid() | port()
10472 Options = [system_profile_option()]
10473 system_profile_option() =
10474 exclusive | runnable_ports | runnable_procs | scheduler |
10475 timestamp | monotonic_timestamp | strict_monotonic_timestamp
10476 Returns the current system profiling settings set by erlang:sys‐
10478 tem_profile/2 as {ProfilerPid, Options}, or undefined if there
10479 are no settings. The order of the options can be different from
10480 the one that was set.
10481 erlang:system_profile(ProfilerPid, Options) -> ProfilerSettings
10483 Types:
10485 ProfilerPid = pid() | port() | undefined
10487 Options = [system_profile_option()]
10488 ProfilerSettings =
10489 undefined | {pid() | port(), [system_profile_option()]}
10490 system_profile_option() =
10491 exclusive | runnable_ports | runnable_procs | scheduler |
10492 timestamp | monotonic_timestamp | strict_monotonic_timestamp
10493 Sets system profiler options. ProfilerPid is a local process
10495 identifier (pid) or port receiving profiling messages. The re‐
10496 ceiver is excluded from all profiling. The second argument is a
10497 list of profiling options:
10498 exclusive:
10500 If a synchronous call to a port from a process is done, the
10501 calling process is considered not runnable during the call
10502 runtime to the port. The calling process is notified as in‐
10503 active, and later active when the port callback returns.
10504 monotonic_timestamp:
10506 Time stamps in profile messages use Erlang monotonic time.
10507 The time stamp (Ts) has the same format and value as pro‐
10508 duced by erlang:monotonic_time(nanosecond).
10509 runnable_procs:
10511 If a process is put into or removed from the run queue, a
10512 message, {profile, Pid, State, Mfa, Ts}, is sent to Profil‐
10513 erPid. Running processes that are reinserted into the run
10514 queue after having been pre-empted do not trigger this mes‐
10515 sage.
10516 runnable_ports:
10518 If a port is put into or removed from the run queue, a mes‐
10519 sage, {profile, Port, State, 0, Ts}, is sent to ProfilerPid.
10520 scheduler:
10522 If a scheduler is put to sleep or awoken, a message, {pro‐
10523 file, scheduler, Id, State, NoScheds, Ts}, is sent to Pro‐
10524 filerPid.
10525 strict_monotonic_timestamp:
10527 Time stamps in profile messages consist of Erlang monotonic
10528 time and a monotonically increasing integer. The time stamp
10529 (Ts) has the same format and value as produced by {er‐
10530 lang:monotonic_time(nanosecond), erlang:unique_inte‐
10531 ger([monotonic])}.
10532 timestamp:
10534 Time stamps in profile messages include a time stamp (Ts)
10535 that has the same form as returned by erlang:now(). This is
10536 also the default if no time stamp flag is specified. If
10537 cpu_timestamp has been enabled through erlang:trace/3, this
10538 also effects the time stamp produced in profiling messages
10539 when flag timestamp is enabled.
10540 Note:
10542 erlang:system_profile behavior can change in a future release.
10543 erlang:system_time() -> integer()
10546 Returns current Erlang system time in native time unit.
10548 Calling erlang:system_time() is equivalent to erlang:mono‐
10550 tonic_time() + erlang:time_offset().
10551 Note:
10553 This time is not a monotonically increasing time in the general
10554 case. For more information, see the documentation of time warp
10555 modes in the User's Guide.
10556 erlang:system_time(Unit) -> integer()
10559 Types:
10561 Unit = time_unit()
10563 Returns current Erlang system time converted into the Unit
10565 passed as argument.
10566 Calling erlang:system_time(Unit) is equivalent to erlang:con‐
10568 vert_time_unit(erlang:system_time(), native, Unit).
10569 Note:
10571 This time is not a monotonically increasing time in the general
10572 case. For more information, see the documentation of time warp
10573 modes in the User's Guide.
10574 term_to_binary(Term) -> ext_binary()
10577 Types:
10579 Term = term()
10581 Returns a binary data object that is the result of encoding Term
10583 according to the Erlang external term format.
10584 This can be used for various purposes, for example, writing a
10586 term to a file in an efficient way, or sending an Erlang term to
10587 some type of communications channel not supported by distributed
10588 Erlang.
10589 > Bin = term_to_binary(hello).
10591 <<131,100,0,5,104,101,108,108,111>>
10592 > hello = binary_to_term(Bin).
10593 hello
10594 See also binary_to_term/1.
10597 Note:
10599 There is no guarantee that this function will return the same
10600 encoded representation for the same term.
10601 term_to_binary(Term, Options) -> ext_binary()
10604 Types:
10606 Term = term()
10608 Options =
10609 [compressed |
10610 {compressed, Level :: 0..9} |
10611 deterministic |
10612 {minor_version, Version :: 0..2}]
10613 Returns a binary data object that is the result of encoding Term
10615 according to the Erlang external term format.
10616 If option compressed is provided, the external term format is
10618 compressed. The compressed format is automatically recognized by
10619 binary_to_term/1 as from Erlang/OTP R7B.
10620 A compression level can be specified by giving option {com‐
10622 pressed, Level}. Level is an integer with range 0..9, where:
10623 * 0 - No compression is done (it is the same as giving no com‐
10625 pressed option).
10626 * 1 - Takes least time but may not compress as well as the
10628 higher levels.
10629 * 6 - Default level when option compressed is provided.
10631 * 9 - Takes most time and tries to produce a smaller result.
10633 Notice "tries" in the preceding sentence; depending on the
10634 input term, level 9 compression either does or does not pro‐
10635 duce a smaller result than level 1 compression.
10636 Option {minor_version, Version} can be used to control some en‐
10638 coding details. This option was introduced in Erlang/OTP R11B-4.
10639 The valid values for Version are:
10640 0:
10642 Floats are encoded using a textual representation. This op‐
10643 tion is useful to ensure that releases before Erlang/OTP
10644 R11B-4 can decode resulting binary.
10645 This version encode atoms that can be represented by a
10647 latin1 string using latin1 encoding while only atoms that
10648 cannot be represented by latin1 are encoded using utf8.
10649 1:
10651 This is as of Erlang/OTP 17.0 the default. It forces any
10652 floats in the term to be encoded in a more space-efficient
10653 and exact way (namely in the 64-bit IEEE format, rather than
10654 converted to a textual representation). As from Erlang/OTP
10655 R11B-4, binary_to_term/1 can decode this representation.
10656 This version encode atoms that can be represented by a
10658 latin1 string using latin1 encoding while only atoms that
10659 cannot be represented by latin1 are encoded using utf8.
10660 2:
10662 Drops usage of the latin1 atom encoding and unconditionally
10663 use utf8 encoding for all atoms. Erlang/OTP systems as of
10664 R16B can decode this representation.
10665 Note:
10667 In Erlang/OTP 26, the default minor_version is planned to
10668 change from 1 to 2. See Upcoming Potential Incompatibilities
10669 .
10670 Option deterministic (introduced in OTP 24.1) can be used to en‐
10673 sure that within the same major release of Erlang/OTP, the same
10674 encoded representation is returned for the same term. There is
10675 still no guarantee that the encoded representation remains the
10676 same between major releases of Erlang/OTP.
10677 See also binary_to_term/1.
10679 term_to_iovec(Term) -> ext_iovec()
10681 Types:
10683 Term = term()
10685 Returns the encoding of Term according to the Erlang external
10687 term format as ext_iovec().
10688 This function produce the same encoding as term_to_binary/1, but
10690 with another return type. The call iolist_to_bi‐
10691 nary(term_to_iovec(Term)) will produce exactly the same result
10692 as the call term_to_binary(Term).
10693 term_to_iovec() is a pure optimization of the functionality
10695 term_to_binary() provide. term_to_iovec() can for example refer
10696 directly to off heap binaries instead of copying the binary data
10697 into the result.
10698 See also term_to_binary/1.
10700 term_to_iovec(Term, Options) -> ext_iovec()
10702 Types:
10704 Term = term()
10706 Options =
10707 [compressed |
10708 {compressed, Level :: 0..9} |
10709 deterministic |
10710 {minor_version, Version :: 0..2}]
10711 Returns the encoding of Term according to the Erlang external
10713 term format as ext_iovec().
10714 This function produce the same encoding as term_to_binary/2, but
10716 with another return type. The call iolist_to_bi‐
10717 nary(term_to_iovec(Term, Opts)) will produce exactly the same
10718 result as term_to_binary(Term, Opts).
10719 Currently recognised options are all options recognised by
10721 term_to_binary/2.
10722 term_to_iovec() is a pure optimization of the functionality
10724 term_to_binary() provide. term_to_iovec() can for example refer
10725 directly to off heap binaries instead of copying the binary data
10726 into the result.
10727 See also term_to_binary/2.
10729 throw(Any) -> no_return()
10731 Types:
10733 Any = term()
10735 Raises an exception of class throw. Intended to be used to do
10737 non-local returns from functions.
10738 If evaluated within a catch expression, the catch expression
10740 returns value Any. Example:
10741 > catch throw({hello, there}).
10743 {hello,there}
10744 If evaluated within a try-block of a try expression, the value
10746 Any can be caught within the catch block. Example:
10747 try
10749 throw({my_exception, "Something happened"})
10750 catch
10751 throw:{my_exception, Desc} ->
10752 io:format(standard_error, "Error: ~s~n", [Desc])
10753 end
10754 Failure: nocatch if not caught by an exception handler.
10756 See the guide about errors and error handling for additional in‐
10758 formation.
10759 time() -> Time
10761 Types:
10763 Time = calendar:time()
10765 Returns the current time as {Hour, Minute, Second}.
10767 The time zone and Daylight Saving Time correction depend on the
10769 underlying OS. The return value is based on the OS System Time.
10770 Example:
10771 > time().
10773 {9,42,44}
10774 erlang:time_offset() -> integer()
10776 Returns the current time offset between Erlang monotonic time
10778 and Erlang system time in native time unit. Current time offset
10779 added to an Erlang monotonic time gives corresponding Erlang
10780 system time.
10781 The time offset may or may not change during operation depending
10783 on the time warp mode used.
10784 Note:
10786 A change in time offset can be observed at slightly different
10787 points in time by different processes.
10788 If the runtime system is in multi-time warp mode, the time off‐
10790 set is changed when the runtime system detects that the OS sys‐
10791 tem time has changed. The runtime system will, however, not de‐
10792 tect this immediately when it occurs. A task checking the time
10793 offset is scheduled to execute at least once a minute; so, under
10794 normal operation this is to be detected within a minute, but
10795 during heavy load it can take longer time.
10796 erlang:time_offset(Unit) -> integer()
10799 Types:
10801 Unit = time_unit()
10803 Returns the current time offset between Erlang monotonic time
10805 and Erlang system time converted into the Unit passed as argu‐
10806 ment.
10807 Same as calling erlang:convert_time_unit(erlang:time_offset(),
10809 native, Unit) however optimized for commonly used Units.
10810 erlang:timestamp() -> Timestamp
10812 Types:
10814 Timestamp = timestamp()
10816 timestamp() =
10817 {MegaSecs :: integer() >= 0,
10818 Secs :: integer() >= 0,
10819 MicroSecs :: integer() >= 0}
10820 Returns current Erlang system time on the format {MegaSecs,
10822 Secs, MicroSecs}. This format is the same as os:timestamp/0 and
10823 the deprecated erlang:now/0 use. The reason for the existence of
10824 erlang:timestamp() is purely to simplify use for existing code
10825 that assumes this time stamp format. Current Erlang system time
10826 can more efficiently be retrieved in the time unit of your
10827 choice using erlang:system_time/1.
10828 The erlang:timestamp() BIF is equivalent to:
10830 timestamp() ->
10832 ErlangSystemTime = erlang:system_time(microsecond),
10833 MegaSecs = ErlangSystemTime div 1000_000_000_000,
10834 Secs = ErlangSystemTime div 1000_000 - MegaSecs*1000_000,
10835 MicroSecs = ErlangSystemTime rem 1000_000,
10836 {MegaSecs, Secs, MicroSecs}.
10837 It, however, uses a native implementation that does not build
10839 garbage on the heap and with slightly better performance.
10840 Note:
10842 This time is not a monotonically increasing time in the general
10843 case. For more information, see the documentation of time warp
10844 modes in the User's Guide.
10845 tl(List) -> term()
10848 Types:
10850 List = nonempty_maybe_improper_list()
10852 Returns the tail of List, that is, the list minus the first ele‐
10854 ment, for example:
10855 > tl([geesties, guilies, beasties]).
10857 [guilies, beasties]
10858 > tl([geesties]).
10860 []
10861 > tl([geesties, guilies, beasties | improper_end]).
10863 [guilies, beasties | improper_end]
10864 > tl([geesties | improper_end]).
10866 improper_end
10867 Allowed in guard tests.
10869 Failure: badarg if List is the empty list [].
10871 erlang:trace(PidPortSpec, How, FlagList) -> integer()
10873 Types:
10875 PidPortSpec =
10877 pid() |
10878 port() |
10879 all | processes | ports | existing | existing_processes |
10880 existing_ports | new | new_processes | new_ports
10881 How = boolean()
10882 FlagList = [trace_flag()]
10883 trace_flag() =
10884 all | send | 'receive' | procs | ports | call | arity |
10885 return_to | silent | running | exiting | running_procs |
10886 running_ports | garbage_collection | timestamp |
10887 cpu_timestamp | monotonic_timestamp |
10888 strict_monotonic_timestamp | set_on_spawn |
10889 set_on_first_spawn | set_on_link | set_on_first_link |
10890 {tracer, pid() | port()} |
10891 {tracer, module(), term()}
10892 Turns on (if How == true) or off (if How == false) the trace
10894 flags in FlagList for the process or processes represented by
10895 PidPortSpec.
10896 PidPortSpec is either a process identifier (pid) for a local
10898 process, a port identifier, or one of the following atoms:
10899 all:
10901 All currently existing processes and ports and all that will
10902 be created in the future.
10903 processes:
10905 All currently existing processes and all that will be cre‐
10906 ated in the future.
10907 ports:
10909 All currently existing ports and all that will be created in
10910 the future.
10911 existing:
10913 All currently existing processes and ports.
10914 existing_processes:
10916 All currently existing processes.
10917 existing_ports:
10919 All currently existing ports.
10920 new:
10922 All processes and ports that will be created in the future.
10923 new_processes:
10925 All processes that will be created in the future.
10926 new_ports:
10928 All ports that will be created in the future.
10929 FlagList can contain any number of the following flags (the
10931 "message tags" refers to the list of trace messages):
10932 all:
10934 Sets all trace flags except tracer and cpu_timestamp, which
10935 are in their nature different than the others.
10936 send:
10938 Traces sending of messages.
10939 Message tags: send and send_to_non_existing_process.
10941 'receive':
10943 Traces receiving of messages.
10944 Message tags: 'receive'.
10946 call:
10948 Traces certain function calls. Specify which function calls
10949 to trace by calling erlang:trace_pattern/3.
10950 Message tags: call and return_from.
10952 silent:
10954 Used with the call trace flag. The call, return_from, and
10955 return_to trace messages are inhibited if this flag is set,
10956 but they are executed as normal if there are match specifi‐
10957 cations.
10958 Silent mode is inhibited by executing erlang:trace(_, false,
10960 [silent|_]), or by a match specification executing the func‐
10961 tion {silent, false}.
10962 The silent trace flag facilitates setting up a trace on many
10964 or even all processes in the system. The trace can then be
10965 activated and deactivated using the match specification
10966 function {silent,Bool}, giving a high degree of control of
10967 which functions with which arguments that trigger the trace.
10968 Message tags: call, return_from, and return_to. Or rather,
10970 the absence of.
10971 return_to:
10973 Used with the call trace flag. Traces the return from a
10974 traced function back to its caller. Only works for functions
10975 traced with option local to erlang:trace_pattern/3.
10976 The semantics is that a trace message is sent when a call
10978 traced function returns, that is, when a chain of tail re‐
10979 cursive calls ends. Only one trace message is sent per chain
10980 of tail recursive calls, so the properties of tail recur‐
10981 siveness for function calls are kept while tracing with this
10982 flag. Using call and return_to trace together makes it pos‐
10983 sible to know exactly in which function a process executes
10984 at any time.
10985 To get trace messages containing return values from func‐
10987 tions, use the {return_trace} match specification action in‐
10988 stead.
10989 Message tags: return_to.
10991 procs:
10993 Traces process-related events.
10994 Message tags: spawn, spawned, exit, register, unregister,
10996 link, unlink, getting_linked, and getting_unlinked.
10997 ports:
10999 Traces port-related events.
11000 Message tags: open, closed, register, unregister, get‐
11002 ting_linked, and getting_unlinked.
11003 running:
11005 Traces scheduling of processes.
11006 Message tags: in and out.
11008 exiting:
11010 Traces scheduling of exiting processes.
11011 Message tags: in_exiting, out_exiting, and out_exited.
11013 running_procs:
11015 Traces scheduling of processes just like running. However,
11016 this option also includes schedule events when the process
11017 executes within the context of a port without being sched‐
11018 uled out itself.
11019 Message tags: in and out.
11021 running_ports:
11023 Traces scheduling of ports.
11024 Message tags: in and out.
11026 garbage_collection:
11028 Traces garbage collections of processes.
11029 Message tags: gc_minor_start, gc_max_heap_size, and gc_mi‐
11031 nor_end.
11032 timestamp:
11034 Includes a time stamp in all trace messages. The time stamp
11035 (Ts) has the same form as returned by erlang:now().
11036 cpu_timestamp:
11038 A global trace flag for the Erlang node that makes all trace
11039 time stamps using flag timestamp to be in CPU time, not wall
11040 clock time. That is, cpu_timestamp is not be used if mono‐
11041 tonic_timestamp or strict_monotonic_timestamp is enabled.
11042 Only allowed with PidPortSpec==all. If the host machine OS
11043 does not support high-resolution CPU time measurements,
11044 trace/3 exits with badarg. Notice that most OS do not syn‐
11045 chronize this value across cores, so be prepared that time
11046 can seem to go backwards when using this option.
11047 monotonic_timestamp:
11049 Includes an Erlang monotonic time time stamp in all trace
11050 messages. The time stamp (Ts) has the same format and value
11051 as produced by erlang:monotonic_time(nanosecond). This flag
11052 overrides flag cpu_timestamp.
11053 strict_monotonic_timestamp:
11055 Includes an time stamp consisting of Erlang monotonic time
11056 and a monotonically increasing integer in all trace mes‐
11057 sages. The time stamp (Ts) has the same format and value as
11058 produced by { erlang:monotonic_time(nanosecond), er‐
11059 lang:unique_integer([monotonic])}. This flag overrides flag
11060 cpu_timestamp.
11061 arity:
11063 Used with the call trace flag. {M, F, Arity} is specified
11064 instead of {M, F, Args} in call trace messages.
11065 set_on_spawn:
11067 Makes any process created by a traced process inherit its
11068 trace flags, including flag set_on_spawn.
11069 set_on_first_spawn:
11071 Makes the first process created by a traced process inherit
11072 its trace flags, excluding flag set_on_first_spawn.
11073 set_on_link:
11075 Makes any process linked by a traced process inherit its
11076 trace flags, including flag set_on_link.
11077 set_on_first_link:
11079 Makes the first process linked to by a traced process in‐
11080 herit its trace flags, excluding flag set_on_first_link.
11081 {tracer, Tracer}:
11083 Specifies where to send the trace messages. Tracer must be
11084 the process identifier of a local process or the port iden‐
11085 tifier of a local port.
11086 {tracer, TracerModule, TracerState}:
11088 Specifies that a tracer module is to be called instead of
11089 sending a trace message. The tracer module can then ignore
11090 or change the trace message. For more details on how to
11091 write a tracer module, see erl_tracer(3).
11092 If no tracer is specified, the calling process receives all the
11094 trace messages.
11095 The effect of combining set_on_first_link with set_on_link is
11097 the same as set_on_first_link alone. Likewise for set_on_spawn
11098 and set_on_first_spawn.
11099 The tracing process receives the trace messages described in the
11101 following list. Pid is the process identifier of the traced
11102 process in which the traced event has occurred. The third tuple
11103 element is the message tag.
11104 If flag timestamp, strict_monotonic_timestamp, or mono‐
11106 tonic_timestamp is specified, the first tuple element is
11107 trace_ts instead, and the time stamp is added as an extra ele‐
11108 ment last in the message tuple. If multiple time stamp flags are
11109 passed, timestamp has precedence over strict_monotonic_time‐
11110 stamp, which in turn has precedence over monotonic_timestamp.
11111 All time stamp flags are remembered, so if two are passed and
11112 the one with highest precedence later is disabled, the other one
11113 becomes active.
11114 If a match specification (applicable only for call, send and
11116 'receive' tracing) contains a {message} action function with a
11117 non-boolean value, that value is added as an extra element to
11118 the message tuple either in the last position or before the
11119 timestamp (if it is present).
11120 Trace messages:
11122 {trace, PidPort, send, Msg, To}:
11124 When PidPort sends message Msg to process To.
11125 {trace, PidPort, send_to_non_existing_process, Msg, To}:
11127 When PidPort sends message Msg to the non-existing process
11128 To.
11129 {trace, PidPort, 'receive', Msg}:
11131 When PidPort receives message Msg. If Msg is set to time-
11132 out, a receive statement can have timed out, or the process
11133 received a message with the payload timeout.
11134 {trace, Pid, call, {M, F, Args}}:
11136 When Pid calls a traced function. The return values of calls
11137 are never supplied, only the call and its arguments.
11138 Trace flag arity can be used to change the contents of this
11140 message, so that Arity is specified instead of Args.
11141 {trace, Pid, return_to, {M, F, Arity}}:
11143 When Pid returns to the specified function. This trace mes‐
11144 sage is sent if both the flags call and return_to are set,
11145 and the function is set to be traced on local function
11146 calls. The message is only sent when returning from a chain
11147 of tail recursive function calls, where at least one call
11148 generated a call trace message (that is, the functions match
11149 specification matched, and {message, false} was not an ac‐
11150 tion).
11151 {trace, Pid, return_from, {M, F, Arity}, ReturnValue}:
11153 When Pid returns from the specified function. This trace
11154 message is sent if flag call is set, and the function has a
11155 match specification with a return_trace or exception_trace
11156 action.
11157 {trace, Pid, exception_from, {M, F, Arity}, {Class, Value}}:
11159 When Pid exits from the specified function because of an ex‐
11160 ception. This trace message is sent if flag call is set, and
11161 the function has a match specification with an excep‐
11162 tion_trace action.
11163 {trace, Pid, spawn, Pid2, {M, F, Args}}:
11165 When Pid spawns a new process Pid2 with the specified func‐
11166 tion call as entry point.
11167 Args is supposed to be the argument list, but can be any
11169 term if the spawn is erroneous.
11170 {trace, Pid, spawned, Pid2, {M, F, Args}}:
11172 When Pid is spawned by process Pid2 with the specified func‐
11173 tion call as entry point.
11174 Args is supposed to be the argument list, but can be any
11176 term if the spawn is erroneous.
11177 {trace, Pid, exit, Reason}:
11179 When Pid exits with reason Reason.
11180 {trace, PidPort, register, RegName}:
11182 When PidPort gets the name RegName registered.
11183 {trace, PidPort, unregister, RegName}:
11185 When PidPort gets the name RegName unregistered. This is
11186 done automatically when a registered process or port exits.
11187 {trace, Pid, link, Pid2}:
11189 When Pid links to a process Pid2.
11190 {trace, Pid, unlink, Pid2}:
11192 When Pid removes the link from a process Pid2.
11193 {trace, PidPort, getting_linked, Pid2}:
11195 When PidPort gets linked to a process Pid2.
11196 {trace, PidPort, getting_unlinked, Pid2}:
11198 When PidPort gets unlinked from a process Pid2.
11199 {trace, Port, open, Pid, Driver}:
11201 When Pid opens a new port Port with the running Driver.
11202 Driver is the name of the driver as an atom.
11204 {trace, Port, closed, Reason}:
11206 When Port closes with Reason.
11207 {trace, Pid, in | in_exiting, {M, F, Arity} | 0}:
11209 When Pid is scheduled to run. The process runs in function
11210 {M, F, Arity}. On some rare occasions, the current function
11211 cannot be determined, then the last element is 0.
11212 {trace, Pid, out | out_exiting | out_exited, {M, F, Arity} |
11214 0}:
11215 When Pid is scheduled out. The process was running in func‐
11216 tion {M, F, Arity}. On some rare occasions, the current
11217 function cannot be determined, then the last element is 0.
11218 {trace, Port, in, Command | 0}:
11220 When Port is scheduled to run. Command is the first thing
11221 the port will execute, it can however run several commands
11222 before being scheduled out. On some rare occasions, the cur‐
11223 rent function cannot be determined, then the last element is
11224 0.
11225 The possible commands are call, close, command, connect,
11227 control, flush, info, link, open, and unlink.
11228 {trace, Port, out, Command | 0}:
11230 When Port is scheduled out. The last command run was Com‐
11231 mand. On some rare occasions, the current function cannot be
11232 determined, then the last element is 0. Command can contain
11233 the same commands as in
11234 {trace, Pid, gc_minor_start, Info}:
11236 Sent when a young garbage collection is about to be started.
11239 Info is a list of two-element tuples, where the first ele‐
11240 ment is a key, and the second is the value. Do not depend on
11241 any order of the tuples. The following keys are defined:
11242 heap_size:
11244 The size of the used part of the heap.
11245 heap_block_size:
11247 The size of the memory block used for storing the heap and
11248 the stack.
11249 old_heap_size:
11251 The size of the used part of the old heap.
11252 old_heap_block_size:
11254 The size of the memory block used for storing the old
11255 heap.
11256 stack_size:
11258 The size of the stack.
11259 recent_size:
11261 The size of the data that survived the previous garbage
11262 collection.
11263 mbuf_size:
11265 The combined size of message buffers associated with the
11266 process.
11267 bin_vheap_size:
11269 The total size of unique off-heap binaries referenced from
11270 the process heap.
11271 bin_vheap_block_size:
11273 The total size of binaries allowed in the virtual heap in
11274 the process before doing a garbage collection.
11275 bin_old_vheap_size:
11277 The total size of unique off-heap binaries referenced from
11278 the process old heap.
11279 bin_old_vheap_block_size:
11281 The total size of binaries allowed in the virtual old heap
11282 in the process before doing a garbage collection.
11283 wordsize:
11285 For the gc_minor_start event it is the size of the need
11286 that triggered the GC. For the corresponding gc_minor_end
11287 event it is the size of reclaimed memory = start heap_size
11288 - end heap_size.
11289 All sizes are in words.
11291 {trace, Pid, gc_max_heap_size, Info}:
11293 Sent when the max_heap_size is reached during garbage col‐
11294 lection. Info contains the same kind of list as in message
11295 gc_start, but the sizes reflect the sizes that triggered
11296 max_heap_size to be reached.
11297 {trace, Pid, gc_minor_end, Info}:
11299 Sent when young garbage collection is finished. Info con‐
11300 tains the same kind of list as in message gc_minor_start,
11301 but the sizes reflect the new sizes after garbage collec‐
11302 tion.
11303 {trace, Pid, gc_major_start, Info}:
11305 Sent when fullsweep garbage collection is about to be
11306 started. Info contains the same kind of list as in message
11307 gc_minor_start.
11308 {trace, Pid, gc_major_end, Info}:
11310 Sent when fullsweep garbage collection is finished. Info
11311 contains the same kind of list as in message gc_minor_start,
11312 but the sizes reflect the new sizes after a fullsweep
11313 garbage collection.
11314 If the tracing process/port dies or the tracer module returns
11316 remove, the flags are silently removed.
11317 Each process can only be traced by one tracer. Therefore, at‐
11319 tempts to trace an already traced process fail.
11320 Returns a number indicating the number of processes that matched
11322 PidPortSpec. If PidPortSpec is a process identifier, the return
11323 value is 1. If PidPortSpec is all or existing, the return value
11324 is the number of processes running. If PidPortSpec is new, the
11325 return value is 0.
11326 Failure: badarg if the specified arguments are not supported.
11328 For example, cpu_timestamp is not supported on all platforms.
11329 erlang:trace_delivered(Tracee) -> Ref
11331 Types:
11333 Tracee = pid() | all
11335 Ref = reference()
11336 The delivery of trace messages (generated by erlang:trace/3,
11338 seq_trace(3), or erlang:system_profile/2) is dislocated on the
11339 time-line compared to other events in the system. If you know
11340 that Tracee has passed some specific point in its execution, and
11341 you want to know when at least all trace messages corresponding
11342 to events up to this point have reached the tracer, use er‐
11343 lang:trace_delivered(Tracee).
11344 When it is guaranteed that all trace messages are delivered to
11346 the tracer up to the point that Tracee reached at the time of
11347 the call to erlang:trace_delivered(Tracee), then a {trace_deliv‐
11348 ered, Tracee, Ref} message is sent to the caller of er‐
11349 lang:trace_delivered(Tracee) .
11350 Notice that message trace_delivered does not imply that trace
11352 messages have been delivered. Instead it implies that all trace
11353 messages that are to be delivered have been delivered. It is not
11354 an error if Tracee is not, and has not been traced by someone,
11355 but if this is the case, no trace messages have been delivered
11356 when the trace_delivered message arrives.
11357 Notice that Tracee must refer to a process currently or previ‐
11359 ously existing on the same node as the caller of er‐
11360 lang:trace_delivered(Tracee) resides on. The special Tracee atom
11361 all denotes all processes that currently are traced in the node.
11362 When used together with a Tracer Module, any message sent in
11364 the trace callback is guaranteed to have reached its recipient
11365 before the trace_delivered message is sent.
11366 Example: Process A is Tracee, port B is tracer, and process C is
11368 the port owner of B. C wants to close B when A exits. To ensure
11369 that the trace is not truncated, C can call erlang:trace_deliv‐
11370 ered(A) when A exits, and wait for message {trace_delivered, A,
11371 Ref} before closing B.
11372 Failure: badarg if Tracee does not refer to a process (dead or
11374 alive) on the same node as the caller of erlang:trace_deliv‐
11375 ered(Tracee) resides on.
11376 erlang:trace_info(PidPortFuncEvent, Item) -> Res
11378 Types:
11380 PidPortFuncEvent =
11382 pid() |
11383 port() |
11384 new | new_processes | new_ports |
11385 {Module, Function, Arity} |
11386 on_load | send | 'receive'
11387 Module = module()
11388 Function = atom()
11389 Arity = arity()
11390 Item =
11391 flags | tracer | traced | match_spec | meta |
11392 meta_match_spec | call_count | call_time | all
11393 Res = trace_info_return()
11394 trace_info_return() =
11395 undefined |
11396 {flags, [trace_info_flag()]} |
11397 {tracer, pid() | port() | []} |
11398 {tracer, module(), term()} |
11399 trace_info_item_result() |
11400 {all, [trace_info_item_result()] | false | undefined}
11401 trace_info_item_result() =
11402 {traced, global | local | false | undefined} |
11403 {match_spec, trace_match_spec() | false | undefined} |
11404 {meta, pid() | port() | false | undefined | []} |
11405 {meta, module(), term()} |
11406 {meta_match_spec, trace_match_spec() | false | undefined} |
11407 {call_count, integer() >= 0 | boolean() | undefined} |
11408 {call_time,
11409 [{pid(),
11410 integer() >= 0,
11411 integer() >= 0,
11412 integer() >= 0}] |
11413 boolean() |
11414 undefined}
11415 trace_info_flag() =
11416 send | 'receive' | set_on_spawn | call | return_to | procs |
11417 set_on_first_spawn | set_on_link | running |
11418 garbage_collection | timestamp | monotonic_timestamp |
11419 strict_monotonic_timestamp | arity
11420 trace_match_spec() =
11421 [{[term()] | '_' | match_variable(), [term()], [term()]}]
11422 match_variable() = atom()
11423 Approximation of '$1' | '$2' | '$3' | ...
11424 Returns trace information about a port, process, function, or
11426 event.
11427 To get information about a port or process, PidPortFuncEvent is
11429 to be a process identifier (pid), port identifier, or one of the
11430 atoms new, new_processes, or new_ports. The atom new or new_pro‐
11431 cesses means that the default trace state for processes to be
11432 created is returned. The atom new_ports means that the default
11433 trace state for ports to be created is returned.
11434 Valid Items for ports and processes:
11436 flags:
11438 Returns a list of atoms indicating what kind of traces is
11439 enabled for the process. The list is empty if no traces are
11440 enabled, and one or more of the following atoms if traces
11441 are enabled: send, 'receive', set_on_spawn, call, return_to,
11442 procs, ports, set_on_first_spawn, set_on_link, running, run‐
11443 ning_procs, running_ports, silent, exiting, monotonic_time‐
11444 stamp, strict_monotonic_timestamp, garbage_collection, time‐
11445 stamp, and arity. The order is arbitrary.
11446 tracer:
11448 Returns the identifier for process, port, or a tuple con‐
11449 taining the tracer module and tracer state tracing this
11450 process. If this process is not traced, the return value is
11451 [].
11452 To get information about a function, PidPortFuncEvent is to be
11454 the three-element tuple {Module, Function, Arity} or the atom
11455 on_load. No wildcards are allowed. Returns undefined if the
11456 function does not exist, or false if the function is not traced.
11457 If PidPortFuncEvent is on_load, the information returned refers
11458 to the default value for code that will be loaded.
11459 Valid Items for functions:
11461 traced:
11463 Returns global if this function is traced on global function
11464 calls, local if this function is traced on local function
11465 calls (that is, local and global function calls), and false
11466 if local or global function calls are not traced.
11467 match_spec:
11469 Returns the match specification for this function, if it has
11470 one. If the function is locally or globally traced but has
11471 no match specification defined, the returned value is [].
11472 meta:
11474 Returns the meta-trace tracer process, port, or trace module
11475 for this function, if it has one. If the function is not
11476 meta-traced, the returned value is false. If the function is
11477 meta-traced but has once detected that the tracer process is
11478 invalid, the returned value is [].
11479 meta_match_spec:
11481 Returns the meta-trace match specification for this func‐
11482 tion, if it has one. If the function is meta-traced but has
11483 no match specification defined, the returned value is [].
11484 call_count:
11486 Returns the call count value for this function or true for
11487 the pseudo function on_load if call count tracing is active.
11488 Otherwise false is returned.
11489 See also erlang:trace_pattern/3.
11491 call_time:
11493 Returns the call time values for this function or true for
11494 the pseudo function on_load if call time tracing is active.
11495 Otherwise false is returned. The call time values returned,
11496 [{Pid, Count, S, Us}], is a list of each process that exe‐
11497 cuted the function and its specific counters.
11498 See also erlang:trace_pattern/3.
11500 all:
11502 Returns a list containing the {Item, Value} tuples for all
11503 other items, or returns false if no tracing is active for
11504 this function.
11505 To get information about an event, PidPortFuncEvent is to be one
11507 of the atoms send or 'receive'.
11508 One valid Item for events exists:
11510 match_spec:
11512 Returns the match specification for this event, if it has
11513 one, or true if no match specification has been set.
11514 The return value is {Item, Value}, where Value is the requested
11516 information as described earlier. If a pid for a dead process
11517 was specified, or the name of a non-existing function, Value is
11518 undefined.
11519 erlang:trace_pattern(MFA, MatchSpec) -> integer() >= 0
11521 Types:
11523 MFA = trace_pattern_mfa() | send | 'receive'
11525 MatchSpec =
11526 (MatchSpecList :: trace_match_spec()) |
11527 boolean() |
11528 restart | pause
11529 trace_pattern_mfa() = {atom(), atom(), arity() | '_'} | on_load
11530 trace_match_spec() =
11531 [{[term()] | '_' | match_variable(), [term()], [term()]}]
11532 match_variable() = atom()
11533 Approximation of '$1' | '$2' | '$3' | ...
11534 The same as erlang:trace_pattern(Event, MatchSpec, []), retained
11536 for backward compatibility.
11537 erlang:trace_pattern(MFA :: send, MatchSpec, FlagList :: []) ->
11539 integer() >= 0
11540 Types:
11542 MatchSpec = (MatchSpecList :: trace_match_spec()) | boolean()
11544 trace_match_spec() =
11545 [{[term()] | '_' | match_variable(), [term()], [term()]}]
11546 match_variable() = atom()
11547 Approximation of '$1' | '$2' | '$3' | ...
11548 Sets trace pattern for message sending. Must be combined with
11550 erlang:trace/3 to set the send trace flag for one or more pro‐
11551 cesses. By default all messages sent from send traced processes
11552 are traced. To limit traced send events based on the message
11553 content, the sender and/or the receiver, use erlang:trace_pat‐
11554 tern/3.
11555 Argument MatchSpec can take the following forms:
11557 MatchSpecList:
11559 A list of match specifications. The matching is done on the
11560 list [Receiver, Msg]. Receiver is the process or port iden‐
11561 tity of the receiver and Msg is the message term. The pid of
11562 the sending process can be accessed with the guard function
11563 self/0. An empty list is the same as true. For more informa‐
11564 tion, see section Match Specifications in Erlang in the
11565 User's Guide.
11566 true:
11568 Enables tracing for all sent messages (from send traced pro‐
11569 cesses). Any match specification is removed. This is the de‐
11570 fault.
11571 false:
11573 Disables tracing for all sent messages. Any match specifica‐
11574 tion is removed.
11575 Argument FlagList must be [] for send tracing.
11577 The return value is always 1.
11579 Examples:
11581 Only trace messages to a specific process Pid:
11583 > erlang:trace_pattern(send, [{[Pid, '_'],[],[]}], []).
11585 1
11586 Only trace messages matching {reply, _}:
11588 > erlang:trace_pattern(send, [{['_', {reply,'_'}],[],[]}], []).
11590 1
11591 Only trace messages sent to the sender itself:
11593 > erlang:trace_pattern(send, [{['$1', '_'],[{'=:=','$1',{self}}],[]}], []).
11595 1
11596 Only trace messages sent to other nodes:
11598 > erlang:trace_pattern(send, [{['$1', '_'],[{'=/=',{node,'$1'},{node}}],[]}], []).
11600 1
11601 Note:
11603 A match specification for send trace can use all guard and body
11604 functions except caller.
11605 Fails by raising an error exception with an error reason of:
11608 badarg:
11610 If an argument is invalid.
11611 system_limit:
11613 If a match specification passed as argument has excessive
11614 nesting which causes scheduler stack exhaustion for the
11615 scheduler that the calling process is executing on. Sched‐
11616 uler stack size can be configured when starting the runtime
11617 system.
11618 erlang:trace_pattern(MFA :: 'receive', MatchSpec, FlagList :: []) ->
11620 integer() >= 0
11621 Types:
11623 MatchSpec = (MatchSpecList :: trace_match_spec()) | boolean()
11625 trace_match_spec() =
11626 [{[term()] | '_' | match_variable(), [term()], [term()]}]
11627 match_variable() = atom()
11628 Approximation of '$1' | '$2' | '$3' | ...
11629 Sets trace pattern for message receiving. Must be combined with
11631 erlang:trace/3 to set the 'receive' trace flag for one or more
11632 processes. By default all messages received by 'receive' traced
11633 processes are traced. To limit traced receive events based on
11634 the message content, the sender and/or the receiver, use er‐
11635 lang:trace_pattern/3.
11636 Argument MatchSpec can take the following forms:
11638 MatchSpecList:
11640 A list of match specifications. The matching is done on the
11641 list [Node, Sender, Msg]. Node is the node name of the
11642 sender. Sender is the process or port identity of the
11643 sender, or the atom undefined if the sender is not known
11644 (which can be the case for remote senders). Msg is the mes‐
11645 sage term. The pid of the receiving process can be accessed
11646 with the guard function self/0. An empty list is the same as
11647 true. For more information, see section Match Specifica‐
11648 tions in Erlang in the User's Guide.
11649 true:
11651 Enables tracing for all received messages (to 'receive'
11652 traced processes). Any match specification is removed. This
11653 is the default.
11654 false:
11656 Disables tracing for all received messages. Any match speci‐
11657 fication is removed.
11658 Argument FlagList must be [] for receive tracing.
11660 The return value is always 1.
11662 Examples:
11664 Only trace messages from a specific process Pid:
11666 > erlang:trace_pattern('receive', [{['_',Pid, '_'],[],[]}], []).
11668 1
11669 Only trace messages matching {reply, _}:
11671 > erlang:trace_pattern('receive', [{['_','_', {reply,'_'}],[],[]}], []).
11673 1
11674 Only trace messages from other nodes:
11676 > erlang:trace_pattern('receive', [{['$1', '_', '_'],[{'=/=','$1',{node}}],[]}], []).
11678 1
11679 Note:
11681 A match specification for 'receive' trace can use all guard and
11682 body functions except caller, is_seq_trace, get_seq_token,
11683 set_seq_token, enable_trace, disable_trace, trace, silent, and
11684 process_dump.
11685 Fails by raising an error exception with an error reason of:
11688 badarg:
11690 If an argument is invalid.
11691 system_limit:
11693 If a match specification passed as argument has excessive
11694 nesting which causes scheduler stack exhaustion for the
11695 scheduler that the calling process is executing on. Sched‐
11696 uler stack size can be configured when starting the runtime
11697 system.
11698 erlang:trace_pattern(MFA, MatchSpec, FlagList) ->
11700 integer() >= 0
11701 Types:
11703 MFA = trace_pattern_mfa()
11705 MatchSpec =
11706 (MatchSpecList :: trace_match_spec()) |
11707 boolean() |
11708 restart | pause
11709 FlagList = [trace_pattern_flag()]
11710 trace_pattern_mfa() = {atom(), atom(), arity() | '_'} | on_load
11711 trace_match_spec() =
11712 [{[term()] | '_' | match_variable(), [term()], [term()]}]
11713 trace_pattern_flag() =
11714 global | local | meta |
11715 {meta, Pid :: pid()} |
11716 {meta, TracerModule :: module(), TracerState :: term()} |
11717 call_count | call_time
11718 match_variable() = atom()
11719 Approximation of '$1' | '$2' | '$3' | ...
11720 Enables or disables call tracing for one or more functions. Must
11722 be combined with erlang:trace/3 to set the call trace flag for
11723 one or more processes.
11724 Conceptually, call tracing works as follows. Inside the Erlang
11726 virtual machine, a set of processes and a set of functions are
11727 to be traced. If a traced process calls a traced function, the
11728 trace action is taken. Otherwise, nothing happens.
11729 To add or remove one or more processes to the set of traced pro‐
11731 cesses, use erlang:trace/3.
11732 To add or remove functions to the set of traced functions, use
11734 erlang:trace_pattern/3.
11735 The BIF erlang:trace_pattern/3 can also add match specifications
11737 to a function. A match specification comprises a pattern that
11738 the function arguments must match, a guard expression that must
11739 evaluate to true, and an action to be performed. The default ac‐
11740 tion is to send a trace message. If the pattern does not match
11741 or the guard fails, the action is not executed.
11742 Argument MFA is to be a tuple, such as {Module, Function, Ar‐
11744 ity}, or the atom on_load (described below). It can be the mod‐
11745 ule, function, and arity for a function (or a BIF in any mod‐
11746 ule). The atom '_' can be used as a wildcard in any of the fol‐
11747 lowing ways:
11748 {Module,Function,'_'}:
11750 All functions of any arity named Function in module Module.
11751 {Module,'_','_'}:
11753 All functions in module Module.
11754 {'_','_','_'}:
11756 All functions in all loaded modules.
11757 Other combinations, such as {Module,'_',Arity}, are not allowed.
11759 Local functions match wildcards only if option local is in
11760 FlagList.
11761 If argument MFA is the atom on_load, the match specification and
11763 flag list are used on all modules that are newly loaded.
11764 Argument MatchSpec can take the following forms:
11766 false:
11768 Disables tracing for the matching functions. Any match spec‐
11769 ification is removed.
11770 true:
11772 Enables tracing for the matching functions. Any match speci‐
11773 fication is removed.
11774 MatchSpecList:
11776 A list of match specifications. An empty list is equivalent
11777 to true. For a description of match specifications, see sec‐
11778 tion Match Specifications in Erlang in the User's Guide.
11779 restart:
11781 For the FlagList options call_count and call_time: restarts
11782 the existing counters. The behavior is undefined for other
11783 FlagList options.
11784 pause:
11786 For the FlagList options call_count and call_time: pauses
11787 the existing counters. The behavior is undefined for other
11788 FlagList options.
11789 Parameter FlagList is a list of options. The following are the
11791 valid options:
11792 global:
11794 Turns on or off call tracing for global function calls (that
11795 is, calls specifying the module explicitly). Only exported
11796 functions match and only global calls generate trace mes‐
11797 sages. This is the default.
11798 local:
11800 Turns on or off call tracing for all types of function
11801 calls. Trace messages are sent whenever any of the specified
11802 functions are called, regardless of how they are called. If
11803 flag return_to is set for the process, a return_to message
11804 is also sent when this function returns to its caller.
11805 meta | {meta, Pid} | {meta, TracerModule, TracerState}:
11807 Turns on or off meta-tracing for all types of function
11808 calls. Trace messages are sent to the tracer whenever any of
11809 the specified functions are called. If no tracer is speci‐
11810 fied, self() is used as a default tracer process.
11811 Meta-tracing traces all processes and does not care about
11813 the process trace flags set by erlang:trace/3, the trace
11814 flags are instead fixed to [call, timestamp].
11815 The match specification function {return_trace} works with
11817 meta-trace and sends its trace message to the same tracer.
11818 call_count:
11820 Starts (MatchSpec == true) or stops (MatchSpec == false)
11821 call count tracing for all types of function calls. For ev‐
11822 ery function, a counter is incremented when the function is
11823 called, in any process. No process trace flags need to be
11824 activated.
11825 If call count tracing is started while already running, the
11827 count is restarted from zero. To pause running counters, use
11828 MatchSpec == pause. Paused and running counters can be
11829 restarted from zero with MatchSpec == restart.
11830 To read the counter value, use erlang:trace_info/2.
11832 call_time:
11834 Starts (MatchSpec == true) or stops (MatchSpec == false)
11835 call time tracing for all types of function calls. For every
11836 function, a counter is incremented when the function is
11837 called. Time spent in the function is accumulated in two
11838 other counters, seconds and microseconds. The counters are
11839 stored for each call traced process.
11840 If call time tracing is started while already running, the
11842 count and time restart from zero. To pause running counters,
11843 use MatchSpec == pause. Paused and running counters can be
11844 restarted from zero with MatchSpec == restart.
11845 To read the counter value, use erlang:trace_info/2.
11847 The options global and local are mutually exclusive, and global
11849 is the default (if no options are specified). The options
11850 call_count and meta perform a kind of local tracing, and cannot
11851 be combined with global. A function can be globally or locally
11852 traced. If global tracing is specified for a set of functions,
11853 then local, meta, call time, and call count tracing for the
11854 matching set of local functions is disabled, and conversely.
11855 When disabling trace, the option must match the type of trace
11857 set on the function. That is, local tracing must be disabled
11858 with option local and global tracing with option global (or no
11859 option), and so on.
11860 Part of a match specification list cannot be changed directly.
11862 If a function has a match specification, it can be replaced with
11863 a new one. To change an existing match specification, use the
11864 BIF erlang:trace_info/2 to retrieve the existing match specifi‐
11865 cation.
11866 Returns the number of functions matching argument MFA. This is
11868 zero if none matched.
11869 Fails by raising an error exception with an error reason of:
11871 badarg:
11873 If an argument is invalid.
11874 system_limit:
11876 If a match specification passed as argument has excessive
11877 nesting which causes scheduler stack exhaustion for the
11878 scheduler that the calling process is executing on. Sched‐
11879 uler stack size can be configured when starting the runtime
11880 system.
11881 trunc(Number) -> integer()
11883 Types:
11885 Number = number()
11887 Truncates the decimals of Number, for example:
11889 > trunc(5.7).
11891 5
11892 > trunc(-5.7).
11894 -5
11895 > trunc(5).
11897 5
11898 > trunc(36028797018963969.0).
11900 36028797018963968
11901 In the last example, trunc(36028797018963969.0) evaluates to
11903 36028797018963968. The reason for this is that the number
11904 36028797018963969.0 cannot be represented exactly as a float
11905 value. Instead, the float literal is represented as
11906 36028797018963968.0, which is the closest number that can be
11907 represented exactly as a float value. See Representation of
11908 Floating Point Numbers for additional information.
11909 Allowed in guard tests.
11911 tuple_size(Tuple) -> integer() >= 0
11913 Types:
11915 Tuple = tuple()
11917 Returns an integer that is the number of elements in Tuple, for
11919 example:
11920 > tuple_size({morni, mulle, bwange}).
11922 3
11923 Allowed in guard tests.
11925 tuple_to_list(Tuple) -> [term()]
11927 Types:
11929 Tuple = tuple()
11931 Returns a list corresponding to Tuple. Tuple can contain any Er‐
11933 lang terms. Example:
11934 > tuple_to_list({share, {'Ericsson_B', 163}}).
11936 [share,{'Ericsson_B',163}]
11937 unalias(Alias) -> boolean()
11939 Types:
11941 Alias = reference()
11943 Deactivate the alias Alias previously created by the calling
11945 process. An alias can for example be created via alias/0, or
11946 monitor/3. unalias/1 will always deactivate the alias regardless
11947 of options used when creating the alias.
11948 Returns true if Alias was a currently active alias for current
11950 processes; otherwise, false.
11951 For more information on process aliases see the Process Aliases
11953 section of the Erlang Reference Manual .
11954 erlang:unique_integer() -> integer()
11956 Generates and returns an integer unique on current runtime sys‐
11958 tem instance. The same as calling erlang:unique_integer([]).
11959 erlang:unique_integer(ModifierList) -> integer()
11961 Types:
11963 ModifierList = [Modifier]
11965 Modifier = positive | monotonic
11966 Generates and returns an integer unique on current runtime sys‐
11968 tem instance. The integer is unique in the sense that this BIF,
11969 using the same set of modifiers, does not return the same inte‐
11970 ger more than once on the current runtime system instance. Each
11971 integer value can of course be constructed by other means.
11972 By default, when [] is passed as ModifierList, both negative and
11974 positive integers can be returned. This to use the range of in‐
11975 tegers that do not need heap memory allocation as much as possi‐
11976 ble. By default the returned integers are also only guaranteed
11977 to be unique, that is, any returned integer can be smaller or
11978 larger than previously returned integers.
11979 Modifiers:
11981 positive:
11983 Returns only positive integers.
11984 Notice that by passing the positive modifier you will get
11986 heap allocated integers (bignums) quicker.
11987 monotonic:
11989 Returns strictly monotonically increasing integers corre‐
11990 sponding to creation time. That is, the integer returned is
11991 always larger than previously returned integers on the cur‐
11992 rent runtime system instance.
11993 These values can be used to determine order between events
11995 on the runtime system instance. That is, if both X = er‐
11996 lang:unique_integer([monotonic]) and Y = erlang:unique_inte‐
11997 ger([monotonic]) are executed by different processes (or the
11998 same process) on the same runtime system instance and X < Y,
11999 we know that X was created before Y.
12000 Warning:
12002 Strictly monotonically increasing values are inherently quite
12003 expensive to generate and scales poorly. This is because the
12004 values need to be synchronized between CPU cores. That is, do
12005 not pass the monotonic modifier unless you really need
12006 strictly monotonically increasing values.
12007 All valid Modifiers can be combined. Repeated (valid) Modifiers
12010 in the ModifierList are ignored.
12011 Note:
12013 The set of integers returned by erlang:unique_integer/1 using
12014 different sets of Modifiers will overlap. For example, by call‐
12015 ing unique_integer([monotonic]), and unique_integer([positive,
12016 monotonic]) repeatedly, you will eventually see some integers
12017 that are returned by both calls.
12018 Failures:
12021 badarg:
12023 if ModifierList is not a proper list.
12024 badarg:
12026 if Modifier is not a valid modifier.
12027 erlang:universaltime() -> DateTime
12029 Types:
12031 DateTime = calendar:datetime()
12033 Returns the current date and time according to Universal Time
12035 Coordinated (UTC) in the form {{Year, Month, Day}, {Hour,
12036 Minute, Second}} if supported by the underlying OS. Otherwise
12037 erlang:universaltime() is equivalent to erlang:localtime(). The
12038 return value is based on the OS System Time. Example:
12039 > erlang:universaltime().
12041 {{1996,11,6},{14,18,43}}
12042 erlang:universaltime_to_localtime(Universaltime) -> Localtime
12044 Types:
12046 Localtime = Universaltime = calendar:datetime()
12048 Converts Universal Time Coordinated (UTC) date and time to local
12050 date and time in the form {{Year, Month, Day}, {Hour, Minute,
12051 Second}} if supported by the underlying OS. Otherwise no conver‐
12052 sion is done, and Universaltime is returned. Example:
12053 > erlang:universaltime_to_localtime({{1996,11,6},{14,18,43}}).
12055 {{1996,11,7},{15,18,43}}
12056 Failure: badarg if Universaltime denotes an invalid date and
12058 time.
12059 unlink(Id) -> true
12061 Types:
12063 Id = pid() | port()
12065 Removes a link between the calling process and another process
12067 or a port identified by Id. We will from here on call the iden‐
12068 tified process or port unlinkee.
12069 A link can be set up using the link/1 BIF. For more information
12071 on links and exit signals due to links, see the Processes chap‐
12072 ter in the Erlang Reference Manual :
12073 * Links
12075 * Sending Exit Signals
12077 * Receiving Exit Signals
12079 Once unlink(Id) has returned, it is guaranteed that the link be‐
12081 tween the caller and the unlinkee has no effect on the caller in
12082 the future (unless the link is setup again). Note that if the
12083 caller is trapping exits, an {'EXIT', Id, ExitReason} message
12084 due to the link may have been placed in the message queue of the
12085 caller before the unlink(Id) call completed. Also note that the
12086 {'EXIT', Id, ExitReason} message may be the result of the link,
12087 but may also be the result of the unlikee sending the caller an
12088 exit signal by calling the exit/2 BIF. Therefore, it may or may
12089 not be appropriate to clean up the message queue after a call to
12090 unlink(Id) as follows, when trapping exits:
12091 unlink(Id),
12093 receive
12094 {'EXIT', Id, _} ->
12095 true
12096 after 0 ->
12097 true
12098 end
12099 The link removal is performed asynchronously. If such a link
12101 does not exist, nothing is done. A detailed description of the
12102 link protocol can be found in the Distribution Protocol chapter
12103 of the ERTS User's Guide .
12104 Failure: badarg if Id does not identify a process or a node lo‐
12106 cal port.
12107 unregister(RegName) -> true
12109 Types:
12111 RegName = atom()
12113 Removes the registered name RegName associated with a process
12115 identifier or a port identifier from the name registry. For ex‐
12116 ample:
12117 > unregister(db).
12119 true
12120 Keep in mind that you can still receive signals associated with
12122 the registered name after it has been unregistered as the sender
12123 may have looked up the name before sending to it.
12124 Users are advised not to unregister system processes.
12126 Failure: badarg if RegName is not a registered name.
12128 whereis(RegName) -> pid() | port() | undefined
12130 Types:
12132 RegName = atom()
12134 Returns the process identifier or port identifier with the reg‐
12136 istered name RegName from the name registry. Returns undefined
12137 if the name is not registered. Example:
12138 > whereis(db).
12140 <0.43.0>
12141 erlang:yield() -> true
12143 Tries to give other processes with the same or higher priority
12145 (if any) a chance to execute before returning. There is no guar‐
12146 antee that any other process runs between the invocation and re‐
12147 turn of erlang:yield/0.
12148 See the documentation for receive-after expressions for how to
12150 make the current process sleep for a specific number of mil‐
12151 liseconds.
12152 Warning:
12154 There is seldom or never any need to use this BIF. Using this
12155 BIF without a thorough grasp of how the scheduler works can
12156 cause performance degradation. The current implementation of
12157 this function puts the current process last in the current
12158 scheduler's queue for processes of the same priority as the cur‐
12159 rent process.
12160Ericsson AB erts 13.2.2.4 erlang(3)