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 Options for spawn_opt().
376 priority_level() = low | normal | high | max
378 Process priority level. For more info see process_flag(priority,
380 Level)
381 max_heap_size() =
383 integer() >= 0 |
384 #{size => integer() >= 0,
385 kill => boolean(),
386 error_logger => boolean()}
387 Process max heap size configuration. For more info see
389 process_flag(max_heap_size, MaxHeapSize)
390 message_queue_data() = off_heap | on_heap
392 Process message queue data configuration. For more information,
394 see process_flag(message_queue_data, MQD)
395 stacktrace() =
397 [{module(),
398 atom(),
399 arity() | [term()],
400 [stacktrace_extrainfo()]} |
401 {function(), arity() | [term()], [stacktrace_extrainfo()]}]
402 stacktrace_extrainfo() =
404 {line, integer() >= 1} |
405 {file, unicode:chardata()} |
406 {error_info,
407 #{module => module(), function => atom(), cause => term()}} |
408 {atom(), term()}
409 An Erlang stacktrace as described by Errors and Error Handling
411 section in the Erlang Reference Manual.
412 send_destination() =
414 pid() |
415 reference() |
416 port() |
417 (RegName :: atom()) |
418 {RegName :: atom(), Node :: node()}
419 The destination for a send operation, can be a remote or local
421 process identifier, a (local) port, a reference denoting a
422 process alias, a locally registered name, or a tuple {RegName,
423 Node} for a registered name at another node.
424
426 abs(Float) -> float()
427 abs(Int) -> integer() >= 0
429 Types:
431 Int = integer()
433 Returns an integer or float that is the arithmetical absolute
435 value of Float or Int, for example:
436 > abs(-3.33).
438 3.33
439 > abs(-3).
440 3
441 Allowed in guard tests.
443 erlang:adler32(Data) -> integer() >= 0
445 Types:
447 Data = iodata()
449 Computes and returns the adler32 checksum for Data.
451 erlang:adler32(OldAdler, Data) -> integer() >= 0
453 Types:
455 OldAdler = integer() >= 0
457 Data = iodata()
458 Continues computing the adler32 checksum by combining the previ‐
460 ous checksum, OldAdler, with the checksum of Data.
461 The following code:
463 X = erlang:adler32(Data1),
465 Y = erlang:adler32(X,Data2).
466 assigns the same value to Y as this:
468 Y = erlang:adler32([Data1,Data2]).
470 erlang:adler32_combine(FirstAdler, SecondAdler, SecondSize) ->
472 integer() >= 0
473 Types:
475 FirstAdler = SecondAdler = SecondSize = integer() >= 0
477 Combines two previously computed adler32 checksums. This compu‐
479 tation requires the size of the data object for the second
480 checksum to be known.
481 The following code:
483 Y = erlang:adler32(Data1),
485 Z = erlang:adler32(Y,Data2).
486 assigns the same value to Z as this:
488 X = erlang:adler32(Data1),
490 Y = erlang:adler32(Data2),
491 Z = erlang:adler32_combine(X,Y,iolist_size(Data2)).
492 alias() -> Alias
494 alias(Opts) -> Alias
496 Types:
498 Alias = reference()
500 Opts = [explicit_unalias | reply]
501 Create an alias which can be used when sending messages to the
503 process that created the alias. When the alias has been deacti‐
504 vated, messages sent using the alias will be dropped. An alias
505 can be deactivated using unalias/1. Currently available options
506 for alias/1:
507 explicit_unalias:
509 The alias can only be deactivated via a call to unalias/1.
510 This is also the default behaviour if no options are passed
511 or if alias/0 is called.
512 reply:
514 The alias will be automatically deactivated when a reply
515 message sent via the alias is received. The alias can also
516 still be deactivated via a call to unalias/1.
517 Example:
519 server() ->
521 receive
522 {request, AliasReqId, Request} ->
523 Result = perform_request(Request),
524 AliasReqId ! {reply, AliasReqId, Result}
525 end,
526 server().
527 client(ServerPid, Request) ->
529 AliasReqId = alias([reply]),
530 ServerPid ! {request, AliasReqId, Request},
531 %% Alias will be automatically deactivated if we receive a reply
532 %% since we used the 'reply' option...
533 receive
534 {reply, AliasReqId, Result} -> Result
535 after 5000 ->
536 unalias(AliasReqId),
537 %% Flush message queue in case the reply arrived
538 %% just before the alias was deactivated...
539 receive {reply, AliasReqId, Result} -> Result
540 after 0 -> exit(timeout)
541 end
542 end.
543 Note that both the server and the client in this example must be
546 executing on at least OTP 24 systems in order for this to work.
547 For more information on process aliases see the Process Aliases
549 section of the Erlang Reference Manual .
550 erlang:append_element(Tuple1, Term) -> Tuple2
552 Types:
554 Tuple1 = Tuple2 = tuple()
556 Term = term()
557 Returns a new tuple that has one element more than Tuple1, and
559 contains the elements in Tuple1 followed by Term as the last el‐
560 ement. Semantically equivalent to list_to_tuple(tu‐
561 ple_to_list(Tuple1) ++ [Term]), but much faster. Example:
562 > erlang:append_element({one, two}, three).
564 {one,two,three}
565 apply(Fun, Args) -> term()
567 Types:
569 Fun = function()
571 Args = [term()]
572 Calls a fun, passing the elements in Args as arguments.
574 If the number of elements in the arguments are known at compile
576 time, the call is better written as Fun(Arg1, Arg2, ... ArgN).
577 Warning:
579 Earlier, Fun could also be specified as {Module, Function},
580 equivalent to apply(Module, Function, Args). This use is depre‐
581 cated and will stop working in a future release.
582 apply(Module, Function, Args) -> term()
585 Types:
587 Module = module()
589 Function = atom()
590 Args = [term()]
591 Returns the result of applying Function in Module to Args. The
593 applied function must be exported from Module. The arity of the
594 function is the length of Args. Example:
595 > apply(lists, reverse, [[a, b, c]]).
597 [c,b,a]
598 > apply(erlang, atom_to_list, ['Erlang']).
599 "Erlang"
600 If the number of arguments are known at compile time, the call
602 is better written as Module:Function(Arg1, Arg2, ..., ArgN).
603 Failure: error_handler:undefined_function/3 is called if the ap‐
605 plied function is not exported. The error handler can be rede‐
606 fined (see process_flag/2). If error_handler is undefined, or if
607 the user has redefined the default error_handler so the replace‐
608 ment module is undefined, an error with reason undef is gener‐
609 ated.
610 atom_to_binary(Atom) -> binary()
612 Types:
614 Atom = atom()
616 The same as atom_to_binary(Atom, utf8).
618 atom_to_binary(Atom, Encoding) -> binary()
620 Types:
622 Atom = atom()
624 Encoding = latin1 | unicode | utf8
625 Returns a binary corresponding to the text representation of
627 Atom. If Encoding is latin1, one byte exists for each character
628 in the text representation. If Encoding is utf8 or unicode, the
629 characters are encoded using UTF-8 where characters may require
630 multiple bytes.
631 Note:
633 As from Erlang/OTP 20, atoms can contain any Unicode character
634 and atom_to_binary(Atom, latin1) may fail if the text represen‐
635 tation for Atom contains a Unicode character > 255.
636 Example:
639 > atom_to_binary('Erlang', latin1).
641 <<"Erlang">>
642 atom_to_list(Atom) -> string()
644 Types:
646 Atom = atom()
648 Returns a list of unicode code points corresponding to the text
650 representation of Atom, for example:
651 > atom_to_list('Erlang').
653 "Erlang"
654 > atom_to_list('你好').
656 [20320,22909]
657 See unicode(3) for how to convert the resulting list to differ‐
659 ent formats.
660 binary_part(Subject, PosLen) -> binary()
662 Types:
664 Subject = binary()
666 PosLen = {Start :: integer() >= 0, Length :: integer()}
667 Extracts the part of the binary described by PosLen.
669 Negative length can be used to extract bytes at the end of a bi‐
671 nary, for example:
672 1> Bin = <<1,2,3,4,5,6,7,8,9,10>>.
674 2> binary_part(Bin,{byte_size(Bin), -5}).
675 <<6,7,8,9,10>>
676 Failure: badarg if PosLen in any way references outside the bi‐
678 nary.
679 Start is zero-based, that is:
681 1> Bin = <<1,2,3>>
683 2> binary_part(Bin,{0,2}).
684 <<1,2>>
685 For details about the PosLen semantics, see binary(3).
687 Allowed in guard tests.
689 binary_part(Subject, Start, Length) -> binary()
691 Types:
693 Subject = binary()
695 Start = integer() >= 0
696 Length = integer()
697 The same as binary_part(Subject, {Start, Length}).
699 Allowed in guard tests.
701 binary_to_atom(Binary) -> atom()
703 Types:
705 Binary = binary()
707 The same as binary_to_atom(Binary, utf8).
709 binary_to_atom(Binary, Encoding) -> atom()
711 Types:
713 Binary = binary()
715 Encoding = latin1 | unicode | utf8
716 Returns the atom whose text representation is Binary. If Encod‐
718 ing is utf8 or unicode, the binary must contain valid UTF-8 se‐
719 quences.
720 Note:
722 As from Erlang/OTP 20, binary_to_atom(Binary, utf8) is capable
723 of decoding any Unicode character. Earlier versions would fail
724 if the binary contained Unicode characters > 255.
725 Note:
728 The number of characters that are permitted in an atom name is
729 limited. The default limits can be found in the efficiency
730 guide (section Advanced).
731 Note:
734 There is configurable limit on how many atoms that can exist and
735 atoms are not garbage collected. Therefore, it is recommended to
736 consider whether binary_to_existing_atom/2 is a better option
737 than binary_to_atom/2. The default limits can be found in effi‐
738 ciency guide (section Advanced).
739 Examples:
742 > binary_to_atom(<<"Erlang">>, latin1).
744 > binary_to_atom(<<1024/utf8>>, utf8).
746 binary_to_existing_atom(Binary) -> atom()
748 Types:
750 Binary = binary()
752 The same as binary_to_existing_atom (Binary, utf8).
754 binary_to_existing_atom(Binary, Encoding) -> atom()
756 Types:
758 Binary = binary()
760 Encoding = latin1 | unicode | utf8
761 As binary_to_atom/2, but the atom must exist.
763 The Erlang system has a configurable limit for the total number
765 of atoms that can exist, and atoms are not garbage collected.
766 Therefore, it is not safe to create many atoms from binaries
767 that come from an untrusted source (for example, a file fetched
768 from the Internet), for example, using binary_to_atom/2. This
769 function is thus the appropriate option when the input binary
770 comes from an untrusted source.
771 An atom exists in an Erlang system when included in a loaded Er‐
773 lang module or when created programmatically (for example, by
774 binary_to_atom/2). See the next note for an example of when an
775 atom exists in the source code for an Erlang module but not in
776 the compiled version of the same module.
777 Failure: badarg if the atom does not exist.
779 Note:
781 Note that the compiler may optimize away atoms. For example, the
782 compiler will rewrite atom_to_list(some_atom) to "some_atom". If
783 that expression is the only mention of the atom some_atom in the
784 containing module, the atom will not be created when the module
785 is loaded, and a subsequent call to binary_to_exist‐
786 ing_atom(<<"some_atom">>, utf8) will fail.
787 Note:
790 The number of characters that are permitted in an atom name is
791 limited. The default limits can be found in the efficiency
792 guide (section Advanced).
793 binary_to_float(Binary) -> float()
796 Types:
798 Binary = binary()
800 Returns the float whose text representation is Binary, for exam‐
802 ple:
803 > binary_to_float(<<"2.2017764e+0">>).
805 2.2017764
806 The float string format is the same as the format for Erlang
808 float literals except for that underscores are not permitted.
809 Failure: badarg if Binary contains a bad representation of a
811 float.
812 binary_to_integer(Binary) -> integer()
814 Types:
816 Binary = binary()
818 Returns an integer whose text representation is Binary, for ex‐
820 ample:
821 > binary_to_integer(<<"123">>).
823 123
824 binary_to_integer/1 accepts the same string formats as
826 list_to_integer/1.
827 Failure: badarg if Binary contains a bad representation of an
829 integer.
830 binary_to_integer(Binary, Base) -> integer()
832 Types:
834 Binary = binary()
836 Base = 2..36
837 Returns an integer whose text representation in base Base is Bi‐
839 nary, for example:
840 > binary_to_integer(<<"3FF">>, 16).
842 1023
843 binary_to_integer/2 accepts the same string formats as
845 list_to_integer/2.
846 Failure: badarg if Binary contains a bad representation of an
848 integer.
849 binary_to_list(Binary) -> [byte()]
851 Types:
853 Binary = binary()
855 Returns a list of integers corresponding to the bytes of Binary.
857 binary_to_list(Binary, Start, Stop) -> [byte()]
859 Types:
861 Binary = binary()
863 Start = Stop = integer() >= 1
864 1..byte_size(Binary)
865 As binary_to_list/1, but returns a list of integers correspond‐
867 ing to the bytes from position Start to position Stop in Binary.
868 The positions in the binary are numbered starting from 1.
869 Note:
871 The one-based indexing for binaries used by this function is
872 deprecated. New code is to use binary:bin_to_list/3 in STDLIB
873 instead. All functions in module binary consistently use zero-
874 based indexing.
875 binary_to_term(Binary) -> term()
878 Types:
880 Binary = ext_binary()
882 Returns an Erlang term that is the result of decoding binary ob‐
884 ject Binary, which must be encoded according to the Erlang ex‐
885 ternal term format.
886 > Bin = term_to_binary(hello).
888 <<131,100,0,5,104,101,108,108,111>>
889 > hello = binary_to_term(Bin).
890 hello
891 Warning:
894 When decoding binaries from untrusted sources, the untrusted
895 source may submit data in a way to create resources, such as
896 atoms and remote references, that cannot be garbage collected
897 and lead to Denial of Service attack. In such cases, consider
898 using binary_to_term/2 with the safe option.
899 See also term_to_binary/1 and binary_to_term/2.
902 binary_to_term(Binary, Opts) -> term() | {term(), Used}
904 Types:
906 Binary = ext_binary()
908 Opt = safe | used
909 Opts = [Opt]
910 Used = integer() >= 1
911 As binary_to_term/1, but takes these options:
913 safe:
915 Use this option when receiving binaries from an untrusted
916 source.
917 When enabled, it prevents decoding data that can be used to
919 attack the Erlang runtime. In the event of receiving unsafe
920 data, decoding fails with a badarg error.
921 This prevents creation of new atoms directly, creation of
923 new atoms indirectly (as they are embedded in certain struc‐
924 tures, such as process identifiers, refs, and funs), and
925 creation of new external function references. None of those
926 resources are garbage collected, so unchecked creation of
927 them can exhaust available memory.
928 > binary_to_term(<<131,100,0,5,"hello">>, [safe]).
930 ** exception error: bad argument
931 > hello.
932 hello
933 > binary_to_term(<<131,100,0,5,"hello">>, [safe]).
934 hello
935 Warning:
938 The safe option ensures the data is safely processed by the
939 Erlang runtime but it does not guarantee the data is safe to
940 your application. You must always validate data from untrusted
941 sources. If the binary is stored or transits through untrusted
942 sources, you should also consider cryptographically signing
943 it.
944 used:
947 Changes the return value to {Term, Used} where Used is the
948 number of bytes actually read from Binary.
949 > Input = <<131,100,0,5,"hello","world">>.
951 <<131,100,0,5,104,101,108,108,111,119,111,114,108,100>>
952 > {Term, Used} = binary_to_term(Input, [used]).
953 {hello, 9}
954 > split_binary(Input, Used).
955 {<<131,100,0,5,104,101,108,108,111>>, <<"world">>}
956 Failure: badarg if safe is specified and unsafe data is decoded.
959 See also term_to_binary/1, binary_to_term/1, and list_to_exist‐
961 ing_atom/1.
962 bit_size(Bitstring) -> integer() >= 0
964 Types:
966 Bitstring = bitstring()
968 Returns an integer that is the size in bits of Bitstring, for
970 example:
971 > bit_size(<<433:16,3:3>>).
973 19
974 > bit_size(<<1,2,3>>).
975 24
976 Allowed in guard tests.
978 bitstring_to_list(Bitstring) -> [byte() | bitstring()]
980 Types:
982 Bitstring = bitstring()
984 Returns a list of integers corresponding to the bytes of Bit‐
986 string. If the number of bits in the binary is not divisible by
987 8, the last element of the list is a bitstring containing the
988 remaining 1-7 bits. Examples:
989 > bitstring_to_list(<<433:16>>).
991 [1,177]
992 > bitstring_to_list(<<433:16,3:3>>).
994 [1,177,<<3:3>>]
995 erlang:bump_reductions(Reductions) -> true
997 Types:
999 Reductions = integer() >= 1
1001 This implementation-dependent function increments the reduction
1003 counter for the calling process. In the Beam emulator, the re‐
1004 duction counter is normally incremented by one for each function
1005 and BIF call. A context switch is forced when the counter
1006 reaches the maximum number of reductions for a process (4000 re‐
1007 ductions in Erlang/OTP 19.2 and later).
1008 Warning:
1010 This BIF can be removed in a future version of the Beam machine
1011 without prior warning. It is unlikely to be implemented in other
1012 Erlang implementations.
1013 byte_size(Bitstring) -> integer() >= 0
1016 Types:
1018 Bitstring = bitstring()
1020 Returns an integer that is the number of bytes needed to contain
1022 Bitstring. That is, if the number of bits in Bitstring is not
1023 divisible by 8, the resulting number of bytes is rounded up. Ex‐
1024 amples:
1025 > byte_size(<<433:16,3:3>>).
1027 3
1028 > byte_size(<<1,2,3>>).
1029 3
1030 Allowed in guard tests.
1032 erlang:cancel_timer(TimerRef) -> Result
1034 Types:
1036 TimerRef = reference()
1038 Time = integer() >= 0
1039 Result = Time | false
1040 Cancels a timer. The same as calling erlang:cancel_timer(Timer‐
1042 Ref, []).
1043 erlang:cancel_timer(TimerRef, Options) -> Result | ok
1045 Types:
1047 TimerRef = reference()
1049 Async = Info = boolean()
1050 Option = {async, Async} | {info, Info}
1051 Options = [Option]
1052 Time = integer() >= 0
1053 Result = Time | false
1054 Cancels a timer that has been created by erlang:start_timer or
1056 erlang:send_after. TimerRef identifies the timer, and was re‐
1057 turned by the BIF that created the timer.
1058 Options:
1060 {async, Async}:
1062 Asynchronous request for cancellation. Async defaults to
1063 false, which causes the cancellation to be performed syn‐
1064 chronously. When Async is set to true, the cancel operation
1065 is performed asynchronously. That is, cancel_timer() sends
1066 an asynchronous request for cancellation to the timer ser‐
1067 vice that manages the timer, and then returns ok.
1068 {info, Info}:
1070 Requests information about the Result of the cancellation.
1071 Info defaults to true, which means the Result is given. When
1072 Info is set to false, no information about the result of the
1073 cancellation is given.
1074 * When Async is false: if Info is true, the Result is re‐
1076 turned by erlang:cancel_timer(). otherwise ok is returned.
1077 * When Async is true: if Info is true, a message on the form
1079 {cancel_timer, TimerRef, Result} is sent to the caller of
1080 erlang:cancel_timer() when the cancellation operation has
1081 been performed, otherwise no message is sent.
1082 More Options may be added in the future.
1084 If Result is an integer, it represents the time in milliseconds
1086 left until the canceled timer would have expired.
1087 If Result is false, a timer corresponding to TimerRef could not
1089 be found. This can be either because the timer had expired, al‐
1090 ready had been canceled, or because TimerRef never corresponded
1091 to a timer. Even if the timer had expired, it does not tell you
1092 if the time-out message has arrived at its destination yet.
1093 Note:
1095 The timer service that manages the timer can be co-located with
1096 another scheduler than the scheduler that the calling process is
1097 executing on. If so, communication with the timer service takes
1098 much longer time than if it is located locally. If the calling
1099 process is in critical path, and can do other things while wait‐
1100 ing for the result of this operation, or is not interested in
1101 the result of the operation, you want to use option {async,
1102 true}. If using option {async, false}, the calling process
1103 blocks until the operation has been performed.
1104 See also erlang:send_after/4, erlang:start_timer/4, and er‐
1107 lang:read_timer/2.
1108 ceil(Number) -> integer()
1110 Types:
1112 Number = number()
1114 Returns the smallest integer not less than Number. For example:
1116 > ceil(5.5).
1118 6
1119 Allowed in guard tests.
1121 check_old_code(Module) -> boolean()
1123 Types:
1125 Module = module()
1127 Returns true if Module has old code, otherwise false.
1129 See also code(3).
1131 check_process_code(Pid, Module) -> CheckResult
1133 Types:
1135 Pid = pid()
1137 Module = module()
1138 CheckResult = boolean()
1139 The same as check_process_code(Pid, Module, []).
1141 check_process_code(Pid, Module, OptionList) -> CheckResult | async
1143 Types:
1145 Pid = pid()
1147 Module = module()
1148 RequestId = term()
1149 Option = {async, RequestId} | {allow_gc, boolean()}
1150 OptionList = [Option]
1151 CheckResult = boolean() | aborted
1152 Checks if the node local process identified by Pid executes old
1154 code for Module.
1155 Options:
1157 {allow_gc, boolean()}:
1159 Determines if garbage collection is allowed when performing
1160 the operation. If {allow_gc, false} is passed, and a garbage
1161 collection is needed to determine the result of the opera‐
1162 tion, the operation is aborted (see information on CheckRe‐
1163 sult below). The default is to allow garbage collection,
1164 that is, {allow_gc, true}.
1165 {async, RequestId}:
1167 The function check_process_code/3 returns the value async
1168 immediately after the request has been sent. When the re‐
1169 quest has been processed, the process that called this func‐
1170 tion is passed a message on the form {check_process_code,
1171 RequestId, CheckResult}.
1172 If Pid equals self(), and no async option has been passed, the
1174 operation is performed at once. Otherwise a request for the op‐
1175 eration is sent to the process identified by Pid, and is handled
1176 when appropriate. If no async option has been passed, the caller
1177 blocks until CheckResult is available and can be returned.
1178 CheckResult informs about the result of the request as follows:
1180 true:
1182 The process identified by Pid executes old code for Module.
1183 That is, the current call of the process executes old code
1184 for this module, or the process has references to old code
1185 for this module, or the process contains funs that refer‐
1186 ences old code for this module.
1187 false:
1189 The process identified by Pid does not execute old code for
1190 Module.
1191 aborted:
1193 The operation was aborted, as the process needed to be
1194 garbage collected to determine the operation result, and the
1195 operation was requested by passing option {allow_gc, false}.
1196 Note:
1198 Up until ERTS version 8.*, the check process code operation
1199 checks for all types of references to the old code. That is, di‐
1200 rect references (e.g. return addresses on the process stack),
1201 indirect references (funs in process context), and references to
1202 literals in the code.
1203 As of ERTS version 9.0, the check process code operation only
1205 checks for direct references to the code. Indirect references
1206 via funs will be ignored. If such funs exist and are used after
1207 a purge of the old code, an exception will be raised upon usage
1208 (same as the case when the fun is received by the process after
1209 the purge). Literals will be taken care of (copied) at a later
1210 stage. This behavior can as of ERTS version 8.1 be enabled when
1211 building OTP, and will automatically be enabled if dirty sched‐
1212 uler support is enabled.
1213 See also code(3).
1216 Failures:
1218 badarg:
1220 If Pid is not a node local process identifier.
1221 badarg:
1223 If Module is not an atom.
1224 badarg:
1226 If OptionList is an invalid list of options.
1227 erlang:convert_time_unit(Time, FromUnit, ToUnit) -> ConvertedTime
1229 Types:
1231 Time = ConvertedTime = integer()
1233 FromUnit = ToUnit = time_unit()
1234 Converts the Time value of time unit FromUnit to the correspond‐
1236 ing ConvertedTime value of time unit ToUnit. The result is
1237 rounded using the floor function.
1238 Warning:
1240 You can lose accuracy and precision when converting between time
1241 units. To minimize such loss, collect all data at native time
1242 unit and do the conversion on the end result.
1243 erlang:crc32(Data) -> integer() >= 0
1246 Types:
1248 Data = iodata()
1250 Computes and returns the crc32 (IEEE 802.3 style) checksum for
1252 Data.
1253 erlang:crc32(OldCrc, Data) -> integer() >= 0
1255 Types:
1257 OldCrc = integer() >= 0
1259 Data = iodata()
1260 Continues computing the crc32 checksum by combining the previous
1262 checksum, OldCrc, with the checksum of Data.
1263 The following code:
1265 X = erlang:crc32(Data1),
1267 Y = erlang:crc32(X,Data2).
1268 assigns the same value to Y as this:
1270 Y = erlang:crc32([Data1,Data2]).
1272 erlang:crc32_combine(FirstCrc, SecondCrc, SecondSize) ->
1274 integer() >= 0
1275 Types:
1277 FirstCrc = SecondCrc = SecondSize = integer() >= 0
1279 Combines two previously computed crc32 checksums. This computa‐
1281 tion requires the size of the data object for the second check‐
1282 sum to be known.
1283 The following code:
1285 Y = erlang:crc32(Data1),
1287 Z = erlang:crc32(Y,Data2).
1288 assigns the same value to Z as this:
1290 X = erlang:crc32(Data1),
1292 Y = erlang:crc32(Data2),
1293 Z = erlang:crc32_combine(X,Y,iolist_size(Data2)).
1294 date() -> Date
1296 Types:
1298 Date = calendar:date()
1300 Returns the current date as {Year, Month, Day}.
1302 The time zone and Daylight Saving Time correction depend on the
1304 underlying OS. The return value is based on the OS System Time.
1305 Example:
1306 > date().
1308 {1995,2,19}
1309 erlang:decode_packet(Type, Bin, Options) ->
1311 {ok, Packet, Rest} |
1312 {more, Length} |
1313 {error, Reason}
1314 Types:
1316 Type =
1318 raw | 0 | 1 | 2 | 4 | asn1 | cdr | sunrm | fcgi | tpkt |
1319 line | http | http_bin | httph | httph_bin
1320 Bin = binary()
1321 Options = [Opt]
1322 Opt =
1323 {packet_size, integer() >= 0} |
1324 {line_length, integer() >= 0}
1325 Packet = binary() | HttpPacket
1326 Rest = binary()
1327 Length = integer() >= 0 | undefined
1328 Reason = term()
1329 HttpPacket =
1330 HttpRequest | HttpResponse | HttpHeader | http_eoh |
1331 HttpError
1332 HttpRequest = {http_request, HttpMethod, HttpUri, HttpVer‐
1333 sion}
1334 HttpResponse =
1335 {http_response, HttpVersion, integer(), HttpString}
1336 HttpHeader =
1337 {http_header,
1338 integer(),
1339 HttpField,
1340 UnmodifiedField :: HttpString,
1341 Value :: HttpString}
1342 HttpError = {http_error, HttpString}
1343 HttpMethod =
1344 'OPTIONS' | 'GET' | 'HEAD' | 'POST' | 'PUT' | 'DELETE' |
1345 'TRACE' | HttpString
1346 HttpUri =
1347 '*' |
1348 {absoluteURI,
1349 http | https,
1350 Host :: HttpString,
1351 Port :: inet:port_number() | undefined,
1352 Path :: HttpString} |
1353 {scheme, Scheme :: HttpString, HttpString} |
1354 {abs_path, HttpString} |
1355 HttpString
1356 HttpVersion =
1357 {Major :: integer() >= 0, Minor :: integer() >= 0}
1358 HttpField =
1359 'Cache-Control' | 'Connection' | 'Date' | 'Pragma' |
1360 'Transfer-Encoding' | 'Upgrade' | 'Via' | 'Accept' |
1361 'Accept-Charset' | 'Accept-Encoding' | 'Accept-Language'
1362 |
1363 'Authorization' | 'From' | 'Host' | 'If-Modified-Since' |
1364 'If-Match' | 'If-None-Match' | 'If-Range' |
1365 'If-Unmodified-Since' | 'Max-Forwards' |
1366 'Proxy-Authorization' | 'Range' | 'Referer' | 'User-
1367 Agent' |
1368 'Age' | 'Location' | 'Proxy-Authenticate' | 'Public' |
1369 'Retry-After' | 'Server' | 'Vary' | 'Warning' |
1370 'Www-Authenticate' | 'Allow' | 'Content-Base' |
1371 'Content-Encoding' | 'Content-Language' | 'Content-
1372 Length' |
1373 'Content-Location' | 'Content-Md5' | 'Content-Range' |
1374 'Content-Type' | 'Etag' | 'Expires' | 'Last-Modified' |
1375 'Accept-Ranges' | 'Set-Cookie' | 'Set-Cookie2' |
1376 'X-Forwarded-For' | 'Cookie' | 'Keep-Alive' |
1377 'Proxy-Connection' | HttpString
1378 HttpString = string() | binary()
1379 Decodes the binary Bin according to the packet protocol speci‐
1381 fied by Type. Similar to the packet handling done by sockets
1382 with option {packet,Type}.
1383 If an entire packet is contained in Bin, it is returned together
1385 with the remainder of the binary as {ok,Packet,Rest}.
1386 If Bin does not contain the entire packet, {more,Length} is re‐
1388 turned. Length is either the expected total size of the packet,
1389 or undefined if the expected packet size is unknown. de‐
1390 code_packet can then be called again with more data added.
1391 If the packet does not conform to the protocol format, {er‐
1393 ror,Reason} is returned.
1394 Types:
1396 raw | 0:
1398 No packet handling is done. The entire binary is returned
1399 unless it is empty.
1400 1 | 2 | 4:
1402 Packets consist of a header specifying the number of bytes
1403 in the packet, followed by that number of bytes. The length
1404 of the header can be one, two, or four bytes; the order of
1405 the bytes is big-endian. The header is stripped off when the
1406 packet is returned.
1407 line:
1409 A packet is a line-terminated by a delimiter byte, default
1410 is the latin-1 newline character. The delimiter byte is in‐
1411 cluded in the returned packet unless the line was truncated
1412 according to option line_length.
1413 asn1 | cdr | sunrm | fcgi | tpkt:
1415 The header is not stripped off.
1416 The meanings of the packet types are as follows:
1418 asn1 - ASN.1 BER:
1420 sunrm - Sun's RPC encoding:
1423 cdr - CORBA (GIOP 1.1):
1426 fcgi - Fast CGI:
1429 tpkt - TPKT format [RFC1006]:
1432 http | httph | http_bin | httph_bin:
1435 The Hypertext Transfer Protocol. The packets are returned
1436 with the format according to HttpPacket described earlier. A
1437 packet is either a request, a response, a header, or an end
1438 of header mark. Invalid lines are returned as HttpError.
1439 Recognized request methods and header fields are returned as
1441 atoms. Others are returned as strings. Strings of unrecog‐
1442 nized header fields are formatted with only capital letters
1443 first and after hyphen characters, for example, "Sec-Web‐
1444 socket-Key". Header field names are also returned in Unmodi‐
1445 fiedField as strings, without any conversion or formatting.
1446 The protocol type http is only to be used for the first line
1448 when an HttpRequest or an HttpResponse is expected. The fol‐
1449 lowing calls are to use httph to get HttpHeaders until
1450 http_eoh is returned, which marks the end of the headers and
1451 the beginning of any following message body.
1452 The variants http_bin and httph_bin return strings (Http‐
1454 String) as binaries instead of lists.
1455 Options:
1457 {packet_size, integer() >= 0}:
1459 Sets the maximum allowed size of the packet body. If the
1460 packet header indicates that the length of the packet is
1461 longer than the maximum allowed length, the packet is con‐
1462 sidered invalid. Defaults to 0, which means no size limit.
1463 {line_length, integer() >= 0}:
1465 For packet type line, lines longer than the indicated length
1466 are truncated.
1467 Option line_length also applies to http* packet types as an
1469 alias for option packet_size if packet_size itself is not
1470 set. This use is only intended for backward compatibility.
1471 {line_delimiter, 0 =< byte() =< 255}:
1473 For packet type line, sets the delimiting byte. Default is
1474 the latin-1 character $\n.
1475 Examples:
1477 > erlang:decode_packet(1,<<3,"abcd">>,[]).
1479 {ok,<<"abc">>,<<"d">>}
1480 > erlang:decode_packet(1,<<5,"abcd">>,[]).
1481 {more,6}
1482 erlang:delete_element(Index, Tuple1) -> Tuple2
1484 Types:
1486 Index = integer() >= 1
1488 1..tuple_size(Tuple1)
1489 Tuple1 = Tuple2 = tuple()
1490 Returns a new tuple with element at Index removed from tuple Tu‐
1492 ple1, for example:
1493 > erlang:delete_element(2, {one, two, three}).
1495 {one,three}
1496 delete_module(Module) -> true | undefined
1498 Types:
1500 Module = module()
1502 Makes the current code for Module become old code and deletes
1504 all references for this module from the export table. Returns
1505 undefined if the module does not exist, otherwise true.
1506 Warning:
1508 This BIF is intended for the code server (see code(3)) and is
1509 not to be used elsewhere.
1510 Failure: badarg if there already is an old version of Module.
1513 demonitor(MonitorRef) -> true
1515 Types:
1517 MonitorRef = reference()
1519 If MonitorRef is a reference that the calling process obtained
1521 by calling monitor/2, this monitoring is turned off. If the mon‐
1522 itoring is already turned off, nothing happens.
1523 Once demonitor(MonitorRef) has returned, it is guaranteed that
1525 no {'DOWN', MonitorRef, _, _, _} message, because of the moni‐
1526 tor, will be placed in the caller message queue in the future.
1527 However, a {'DOWN', MonitorRef, _, _, _} message can have been
1528 placed in the caller message queue before the call. It is there‐
1529 fore usually advisable to remove such a 'DOWN' message from the
1530 message queue after monitoring has been stopped. demonitor(Moni‐
1531 torRef, [flush]) can be used instead of demonitor(MonitorRef) if
1532 this cleanup is wanted.
1533 Note:
1535 Before Erlang/OTP R11B (ERTS 5.5) demonitor/1 behaved completely
1536 asynchronously, that is, the monitor was active until the "de‐
1537 monitor signal" reached the monitored entity. This had one unde‐
1538 sirable effect. You could never know when you were guaranteed
1539 not to receive a DOWN message because of the monitor.
1540 The current behavior can be viewed as two combined operations:
1542 asynchronously send a "demonitor signal" to the monitored entity
1543 and ignore any future results of the monitor.
1544 Failure: It is an error if MonitorRef refers to a monitoring
1547 started by another process. Not all such cases are cheap to
1548 check. If checking is cheap, the call fails with badarg, for ex‐
1549 ample if MonitorRef is a remote reference.
1550 demonitor(MonitorRef, OptionList) -> boolean()
1552 Types:
1554 MonitorRef = reference()
1556 OptionList = [Option]
1557 Option = flush | info
1558 The returned value is true unless info is part of OptionList.
1560 demonitor(MonitorRef, []) is equivalent to demonitor(Monitor‐
1562 Ref).
1563 Options:
1565 flush:
1567 Removes (one) {_, MonitorRef, _, _, _} message, if there is
1568 one, from the caller message queue after monitoring has been
1569 stopped.
1570 Calling demonitor(MonitorRef, [flush]) is equivalent to the
1572 following, but more efficient:
1573 demonitor(MonitorRef),
1575 receive
1576 {_, MonitorRef, _, _, _} ->
1577 true
1578 after 0 ->
1579 true
1580 end
1581 info:
1583 The returned value is one of the following:
1584 true:
1586 The monitor was found and removed. In this case, no 'DOWN'
1587 message corresponding to this monitor has been delivered
1588 and will not be delivered.
1589 false:
1591 The monitor was not found and could not be removed. This
1592 probably because someone already has placed a 'DOWN' mes‐
1593 sage corresponding to this monitor in the caller message
1594 queue.
1595 If option info is combined with option flush, false is re‐
1597 turned if a flush was needed, otherwise true.
1598 Note:
1600 More options can be added in a future release.
1601 Failures:
1604 badarg:
1606 If OptionList is not a list.
1607 badarg:
1609 If Option is an invalid option.
1610 badarg:
1612 The same failure as for demonitor/1.
1613 disconnect_node(Node) -> boolean() | ignored
1615 Types:
1617 Node = node()
1619 Forces the disconnection of a node. This appears to the node
1621 Node as if the local node has crashed. This BIF is mainly used
1622 in the Erlang network authentication protocols.
1623 Returns true if disconnection succeeds, otherwise false. If the
1625 local node is not alive, ignored is returned.
1626 Note:
1628 This function may return before nodedown messages have been de‐
1629 livered.
1630 erlang:display(Term) -> true
1633 Types:
1635 Term = term()
1637 Prints a text representation of Term on the standard output.
1639 Warning:
1641 This BIF is intended for debugging only. The printed representa‐
1642 tion may contain internal details that do not match the high-
1643 level representation of the term in Erlang.
1644 erlang:dist_ctrl_get_data(DHandle) -> {Size, Data} | Data | none
1647 Types:
1649 Size = integer() >= 0
1651 DHandle = dist_handle()
1652 Data = iovec()
1653 Get distribution channel data from the local node that is to be
1655 passed to the remote node. The distribution channel is identi‐
1656 fied by DHandle. If no data is available, the atom none is re‐
1657 turned. One can request to be informed by a message when more
1658 data is available by calling erlang:dist_ctrl_get_data_notifica‐
1659 tion(DHandle).
1660 The returned value when there are data available depends on the
1662 value of the get_size option configured on the distribution
1663 channel identified by DHandle. For more information see the doc‐
1664 umentation of the get_size option for the er‐
1665 lang:dist_ctrl_set_opt/3 function.
1666 Note:
1668 Only the process registered as distribution controller for the
1669 distribution channel identified by DHandle is allowed to call
1670 this function.
1671 This function is used when implementing an alternative distribu‐
1674 tion carrier using processes as distribution controllers. DHan‐
1675 dle is retrieved via the callback f_handshake_complete. More in‐
1676 formation can be found in the documentation of ERTS User's Guide
1677 ➜ How to implement an Alternative Carrier for the Erlang Distri‐
1678 bution ➜ Distribution Module.
1679 erlang:dist_ctrl_get_opt(DHandle, Opt :: get_size) -> Value
1681 Types:
1683 DHandle = dist_handle()
1685 Value = boolean()
1686 Returns the value of the get_size option on the distribution
1688 channel identified by DHandle. For more information see the doc‐
1689 umentation of the get_size option for the er‐
1690 lang:dist_ctrl_set_opt/3 function.
1691 Note:
1693 Only the process registered as distribution controller for the
1694 distribution channel identified by DHandle is allowed to call
1695 this function.
1696 This function is used when implementing an alternative distribu‐
1699 tion carrier using processes as distribution controllers. DHan‐
1700 dle is retrieved via the callback f_handshake_complete. More in‐
1701 formation can be found in the documentation of ERTS User's Guide
1702 ➜ How to implement an Alternative Carrier for the Erlang Distri‐
1703 bution ➜ Distribution Module.
1704 erlang:dist_ctrl_get_data_notification(DHandle) -> ok
1706 Types:
1708 DHandle = dist_handle()
1710 Request notification when more data is available to fetch using
1712 erlang:dist_ctrl_get_data(DHandle) for the distribution channel
1713 identified by DHandle. When more data is present, the caller
1714 will be sent the message dist_data. Once a dist_data messages
1715 has been sent, no more dist_data messages will be sent until the
1716 dist_ctrl_get_data_notification/1 function has been called
1717 again.
1718 Note:
1720 Only the process registered as distribution controller for the
1721 distribution channel identified by DHandle is allowed to call
1722 this function.
1723 This function is used when implementing an alternative distribu‐
1726 tion carrier using processes as distribution controllers. DHan‐
1727 dle is retrieved via the callback f_handshake_complete. More in‐
1728 formation can be found in the documentation of ERTS User's Guide
1729 ➜ How to implement an Alternative Carrier for the Erlang Distri‐
1730 bution ➜ Distribution Module.
1731 erlang:dist_ctrl_input_handler(DHandle, InputHandler) -> ok
1733 Types:
1735 DHandle = dist_handle()
1737 InputHandler = pid()
1738 Register an alternate input handler process for the distribution
1740 channel identified by DHandle. Once this function has been
1741 called, InputHandler is the only process allowed to call er‐
1742 lang:dist_ctrl_put_data(DHandle, Data) with the DHandle identi‐
1743 fying this distribution channel.
1744 Note:
1746 Only the process registered as distribution controller for the
1747 distribution channel identified by DHandle is allowed to call
1748 this function.
1749 This function is used when implementing an alternative distribu‐
1752 tion carrier using processes as distribution controllers. DHan‐
1753 dle is retrieved via the callback f_handshake_complete. More in‐
1754 formation can be found in the documentation of ERTS User's Guide
1755 ➜ How to implement an Alternative Carrier for the Erlang Distri‐
1756 bution ➜ Distribution Module.
1757 erlang:dist_ctrl_put_data(DHandle, Data) -> ok
1759 Types:
1761 DHandle = dist_handle()
1763 Data = iodata()
1764 Deliver distribution channel data from a remote node to the lo‐
1766 cal node.
1767 Note:
1769 Only the process registered as distribution controller for the
1770 distribution channel identified by DHandle is allowed to call
1771 this function unless an alternate input handler process has been
1772 registered using erlang:dist_ctrl_input_handler(DHandle, In‐
1773 putHandler). If an alternate input handler has been registered,
1774 only the registered input handler process is allowed to call
1775 this function.
1776 This function is used when implementing an alternative distribu‐
1779 tion carrier using processes as distribution controllers. DHan‐
1780 dle is retrieved via the callback f_handshake_complete. More in‐
1781 formation can be found in the documentation of ERTS User's Guide
1782 ➜ How to implement an Alternative Carrier for the Erlang Distri‐
1783 bution ➜ Distribution Module.
1784 erlang:dist_ctrl_set_opt(DHandle, Opt :: get_size, Value) ->
1786 OldValue
1787 Types:
1789 DHandle = dist_handle()
1791 Value = OldValue = boolean()
1792 Sets the value of the get_size option on the distribution chan‐
1794 nel identified by DHandle. This option controls the return value
1795 of calls to erlang:dist_ctrl_get_data(DHandle) where DHandle
1796 equals DHandle used when setting this option. When the get_size
1797 option is:
1798 false:
1800 and there are distribution data available, a call to er‐
1801 lang:dist_ctrl_get_data(DHandle) will just return Data to
1802 pass over the channel. This is the default value of the
1803 get_size option.
1804 true:
1806 and there are distribution data available, a call to er‐
1807 lang:dist_ctrl_get_data(DHandle) will return Data to pass
1808 over the channel as well as the Size of Data in bytes. This
1809 is returned as a tuple on the form {Size, Data}.
1810 All options are set to default when a channel is closed.
1812 Note:
1814 Only the process registered as distribution controller for the
1815 distribution channel identified by DHandle is allowed to call
1816 this function.
1817 This function is used when implementing an alternative distribu‐
1820 tion carrier using processes as distribution controllers. DHan‐
1821 dle is retrieved via the callback f_handshake_complete. More in‐
1822 formation can be found in the documentation of ERTS User's Guide
1823 ➜ How to implement an Alternative Carrier for the Erlang Distri‐
1824 bution ➜ Distribution Module.
1825 element(N, Tuple) -> term()
1827 Types:
1829 N = integer() >= 1
1831 1..tuple_size(Tuple)
1832 Tuple = tuple()
1833 Returns the Nth element (numbering from 1) of Tuple, for exam‐
1835 ple:
1836 > element(2, {a, b, c}).
1838 b
1839 Allowed in guard tests.
1841 erase() -> [{Key, Val}]
1843 Types:
1845 Key = Val = term()
1847 Returns the process dictionary and deletes it, for example:
1849 > put(key1, {1, 2, 3}),
1851 put(key2, [a, b, c]),
1852 erase().
1853 [{key1,{1,2,3}},{key2,[a,b,c]}]
1854 erase(Key) -> Val | undefined
1856 Types:
1858 Key = Val = term()
1860 Returns the value Val associated with Key and deletes it from
1862 the process dictionary. Returns undefined if no value is associ‐
1863 ated with Key. The average time complexity for the current im‐
1864 plementation of this function is O(1) and the worst case time
1865 complexity is O(N), where N is the number of items in the
1866 process dictionary. Example:
1867 > put(key1, {merry, lambs, are, playing}),
1869 X = erase(key1),
1870 {X, erase(key1)}.
1871 {{merry,lambs,are,playing},undefined}
1872 error(Reason) -> no_return()
1874 Types:
1876 Reason = term()
1878 Raises an exception of class error with the reason Reason. As
1880 evaluating this function causes an exception to be thrown, it
1881 has no return value.
1882 The intent of the exception class error is to signal that an un‐
1884 expected error has happened (for example, a function is called
1885 with a parameter that has an incorrect type). See the guide
1886 about errors and error handling for additional information. Ex‐
1887 ample:
1888 > catch error(foobar).
1890 {'EXIT',{foobar,[{shell,apply_fun,3,
1891 [{file,"shell.erl"},{line,906}]},
1892 {erl_eval,do_apply,6,[{file,"erl_eval.erl"},{line,677}]},
1893 {erl_eval,expr,5,[{file,"erl_eval.erl"},{line,430}]},
1894 {shell,exprs,7,[{file,"shell.erl"},{line,687}]},
1895 {shell,eval_exprs,7,[{file,"shell.erl"},{line,642}]},
1896 {shell,eval_loop,3,[{file,"shell.erl"},{line,627}]}]}}
1897 error(Reason, Args) -> no_return()
1900 Types:
1902 Reason = term()
1904 Args = [term()] | none
1905 Raises an exception of class error with the reason Reason. Args
1907 is expected to be the list of arguments for the current function
1908 or the atom none. If it is a list, it is used to provide the ar‐
1909 guments for the current function in the stack back-trace. If it
1910 is none, the arity of the calling function is used in the stack‐
1911 trace. As evaluating this function causes an exception to be
1912 raised, it has no return value.
1913 The intent of the exception class error is to signal that an un‐
1915 expected error has happened (for example, a function is called
1916 with a parameter that has an incorrect type). See the guide
1917 about errors and error handling for additional information. Ex‐
1918 ample:
1919 test.erl:
1921 -module(test).
1923 -export([example_fun/2]).
1924 example_fun(A1, A2) ->
1926 erlang:error(my_error, [A1, A2]).
1927 Erlang shell:
1930 6> c(test).
1932 {ok,test}
1933 7> test:example_fun(arg1,"this is the second argument").
1934 ** exception error: my_error
1935 in function test:example_fun/2
1936 called as test:example_fun(arg1,"this is the second argument")
1937 error(Reason, Args, Options) -> no_return()
1940 Types:
1942 Reason = term()
1944 Args = [term()] | none
1945 Options = [Option]
1946 Option = {error_info, ErrorInfoMap}
1947 ErrorInfoMap =
1948 #{cause => term(), module => module(), function =>
1949 atom()}
1950 Raises an exception of class error with the reason Reason. Args
1952 is expected to be the list of arguments for the current function
1953 or the atom none. If it is a list, it is used to provide the ar‐
1954 guments for the current function in the stack back-trace. If it
1955 is none, the arity of the calling function is used in the stack‐
1956 trace. As evaluating this function causes an exception to be
1957 raised, it has no return value.
1958 If the error_info option is given, the ErrorInfoMap will be in‐
1960 serted into the stacktrace. The information given in the Error‐
1961 InfoMap is to be used by error formatters such as erl_error to
1962 provide more context around an error.
1963 The default module of the ErrorInfoMap is the module that the
1965 call to error/3 is made. The default function is format_error.
1966 See format_error/2 for more details on how this Module:Func‐
1967 tion/2 is to be used
1968 The intent of the exception class error is to signal that an un‐
1970 expected error has happened (for example, a function is called
1971 with a parameter that has an incorrect type). See the guide
1972 about errors and error handling for additional information.
1973 exit(Reason) -> no_return()
1975 Types:
1977 Reason = term()
1979 Raises an exception of class exit with exit reason Reason. As
1981 evaluating this function causes an exception to be raised, it
1982 has no return value.
1983 The intent of the exception class exit is that the current
1985 process should be stopped (for example when a message telling a
1986 process to stop is received).
1987 This function differ from error/1,2,3 by causing an exception of
1989 a different class and by having a reason that does not include
1990 the list of functions from the call stack.
1991 See the guide about errors and error handling for additional in‐
1993 formation.
1994 Example:
1996 > exit(foobar).
1998 ** exception exit: foobar
1999 > catch exit(foobar).
2000 {'EXIT',foobar}
2001 Note:
2003 If a process calls exit(kill) and does not catch the exception,
2004 it will terminate with exit reason kill and also emit exit sig‐
2005 nals with exit reason kill (not killed) to all linked processes.
2006 Such exit signals with exit reason kill can be trapped by the
2007 linked processes. Note that this means that signals with exit
2008 reason kill behave differently depending on how they are sent
2009 because the signal will be untrappable if a process sends such a
2010 signal to another process with erlang:exit/2.
2011 exit(Pid, Reason) -> true
2014 Types:
2016 Pid = pid() | port()
2018 Reason = term()
2019 Sends an exit signal with exit reason Reason to the process or
2021 port identified by Pid.
2022 The following behavior applies if Reason is any term, except
2024 normal or kill, and P is the process or port identified by Pid:
2025 * If P is not trapping exits, P exits with exit reason Reason.
2027 * If P is trapping exits, the exit signal is transformed into
2029 a message {'EXIT', From, Reason}, where From is the process
2030 identifier of the process that sent the exit signal, and de‐
2031 livered to the message queue of P.
2032 The following behavior applies if Reason is the term normal and
2034 Pid is the identifier of a process P which is not the same as
2035 the process that invoked erlang:exit(Pid, normal) (the behavior
2036 when a process sends a signal with the normal reason to itself
2037 is described in the warning):
2038 * If P is trapping exits, the exit signal is transformed into
2040 a message {'EXIT', From, normal}, where From is the process
2041 identifier of the process that sent the exit signal, and de‐
2042 livered to P's message queue.
2043 * The signal has no effect if P is not trapping exits.
2045 If Reason is the atom kill, that is, if exit(Pid, kill) is
2047 called, an untrappable exit signal is sent to the process that
2048 is identified by Pid, which unconditionally exits with exit rea‐
2049 son killed. The exit reason is changed from kill to killed to
2050 hint to linked processes that the killed process got killed by a
2051 call to exit(Pid, kill).
2052 Note:
2054 The functions erlang:exit/1 and erlang:exit/2 are named simi‐
2055 larly but provide very different functionalities. The er‐
2056 lang:exit/1 function should be used when the intent is to stop
2057 the current process while erlang:exit/2 should be used when the
2058 intent is to send an exit signal to another process. Note also
2059 that erlang:exit/1 raises an exception that can be caught while
2060 erlang:exit/2 does not cause any exception to be raised.
2061 Warning:
2064 The only scenario that has not been covered by the description
2065 above is when a process P sends an exit signal with reason nor‐
2066 mal to itself, that is erlang:exit(self(), normal). The behavior
2067 in this scenario is as follows:
2068 * If P is trapping exits, the exit signal is transformed into
2070 a message {'EXIT', From, normal}, where From is P's process
2071 identifier, and delivered to P's message queue.
2072 * P exits with reason normal if P is not trapping exits.
2074 Note that the behavior described above is different from when a
2076 process sends an exit signal with reason normal to another
2077 process. This is arguably strange but this behavior is kept for
2078 backward compatibility reasons.
2079 erlang:external_size(Term) -> integer() >= 0
2082 Types:
2084 Term = term()
2086 Calculates, without doing the encoding, the maximum byte size
2088 for a term encoded in the Erlang external term format. The fol‐
2089 lowing condition applies always:
2090 > Size1 = byte_size(term_to_binary(Term)),
2092 > Size2 = erlang:external_size(Term),
2093 > true = Size1 =< Size2.
2094 true
2095 This is equivalent to a call to:
2097 erlang:external_size(Term, [])
2099 erlang:external_size(Term, Options) -> integer() >= 0
2101 Types:
2103 Term = term()
2105 Options = [{minor_version, Version :: integer() >= 0}]
2106 Calculates, without doing the encoding, the maximum byte size
2108 for a term encoded in the Erlang external term format. The fol‐
2109 lowing condition applies always:
2110 > Size1 = byte_size(term_to_binary(Term, Options)),
2112 > Size2 = erlang:external_size(Term, Options),
2113 > true = Size1 =< Size2.
2114 true
2115 Option {minor_version, Version} specifies how floats are en‐
2117 coded. For a detailed description, see term_to_binary/2.
2118 float(Number) -> float()
2120 Types:
2122 Number = number()
2124 Returns a float by converting Number to a float, for example:
2126 > float(55).
2128 55.0
2129 Allowed in guard tests.
2131 Note:
2133 If used on the top level in a guard, it tests whether the argu‐
2134 ment is a floating point number; for clarity, use is_float/1 in‐
2135 stead.
2136 When float/1 is used in an expression in a guard, such as
2138 'float(A) == 4.0', it converts a number as described earlier.
2139 float_to_binary(Float) -> binary()
2142 Types:
2144 Float = float()
2146 The same as float_to_binary(Float,[{scientific,20}]).
2148 float_to_binary(Float, Options) -> binary()
2150 Types:
2152 Float = float()
2154 Options = [Option]
2155 Option =
2156 {decimals, Decimals :: 0..253} |
2157 {scientific, Decimals :: 0..249} |
2158 compact | short
2159 Returns a binary corresponding to the text representation of
2161 Float using fixed decimal point formatting. Options behaves in
2162 the same way as float_to_list/2. Examples:
2163 > float_to_binary(7.12, [{decimals, 4}]).
2165 <<"7.1200">>
2166 > float_to_binary(7.12, [{decimals, 4}, compact]).
2167 <<"7.12">>
2168 > float_to_binary(7.12, [{scientific, 3}]).
2169 <<"7.120e+00">>
2170 > float_to_binary(7.12, [short]).
2171 <<"7.12">>
2172 > float_to_binary(0.1+0.2, [short]).
2173 <<"0.30000000000000004">>
2174 > float_to_binary(0.1+0.2)
2175 <<"3.00000000000000044409e-01">>
2176 float_to_list(Float) -> string()
2179 Types:
2181 Float = float()
2183 The same as float_to_list(Float,[{scientific,20}]).
2185 float_to_list(Float, Options) -> string()
2187 Types:
2189 Float = float()
2191 Options = [Option]
2192 Option =
2193 {decimals, Decimals :: 0..253} |
2194 {scientific, Decimals :: 0..249} |
2195 compact | short
2196 Returns a string corresponding to the text representation of
2198 Float using fixed decimal point formatting.
2199 Available options:
2201 * If option decimals is specified, the returned value contains
2203 at most Decimals number of digits past the decimal point. If
2204 the number does not fit in the internal static buffer of 256
2205 bytes, the function throws badarg.
2206 * If option compact is specified, the trailing zeros at the
2208 end of the list are truncated. This option is only meaning‐
2209 ful together with option decimals.
2210 * If option scientific is specified, the float is formatted
2212 using scientific notation with Decimals digits of precision.
2213 * If option short is specified, the float is formatted with
2215 the smallest number of digits that still guarantees that F
2216 =:= list_to_float(float_to_list(F, [short])). When the float
2217 is inside the range (-2⁵³, 2⁵³), the notation that yields
2218 the smallest number of characters is used (scientific nota‐
2219 tion or normal decimal notation). Floats outside the range
2220 (-2⁵³, 2⁵³) are always formatted using scientific notation
2221 to avoid confusing results when doing arithmetic operations.
2222 * If Options is [], the function behaves as float_to_list/1.
2224 Examples:
2226 > float_to_list(7.12, [{decimals, 4}]).
2228 "7.1200"
2229 > float_to_list(7.12, [{decimals, 4}, compact]).
2230 "7.12"
2231 > float_to_list(7.12, [{scientific, 3}]).
2232 "7.120e+00"
2233 > float_to_list(7.12, [short]).
2234 "7.12"
2235 > float_to_list(0.1+0.2, [short]).
2236 "0.30000000000000004"
2237 > float_to_list(0.1+0.2)
2238 "3.00000000000000044409e-01"
2239 In the last example, float_to_list(0.1+0.2) evaluates to
2242 "3.00000000000000044409e-01". The reason for this is explained
2243 in Representation of Floating Point Numbers.
2244 floor(Number) -> integer()
2246 Types:
2248 Number = number()
2250 Returns the largest integer not greater than Number. For exam‐
2252 ple:
2253 > floor(-10.5).
2255 -11
2256 Allowed in guard tests.
2258 erlang:fun_info(Fun) -> [{Item, Info}]
2260 Types:
2262 Fun = function()
2264 Item =
2265 arity | env | index | name | module | new_index |
2266 new_uniq |
2267 pid | type | uniq
2268 Info = term()
2269 Returns a list with information about the fun Fun. Each list el‐
2271 ement is a tuple. The order of the tuples is undefined, and more
2272 tuples can be added in a future release.
2273 Warning:
2275 This BIF is mainly intended for debugging, but it can sometimes
2276 be useful in library functions that need to verify, for example,
2277 the arity of a fun.
2278 Two types of funs have slightly different semantics:
2281 * A fun created by fun M:F/A is called an external fun. Call‐
2283 ing it will always call the function F with arity A in the
2284 latest code for module M. Notice that module M does not even
2285 need to be loaded when the fun fun M:F/A is created.
2286 * All other funs are called local. When a local fun is called,
2288 the same version of the code that created the fun is called
2289 (even if a newer version of the module has been loaded).
2290 The following elements are always present in the list for both
2292 local and external funs:
2293 {type, Type}:
2295 Type is local or external.
2296 {module, Module}:
2298 Module (an atom) is the module name.
2299 If Fun is a local fun, Module is the module in which the fun
2301 is defined.
2302 If Fun is an external fun, Module is the module that the fun
2304 refers to.
2305 {name, Name}:
2307 Name (an atom) is a function name.
2308 If Fun is a local fun, Name is the name of the local func‐
2310 tion that implements the fun. (This name was generated by
2311 the compiler, and is only of informational use. As it is a
2312 local function, it cannot be called directly.) If no code is
2313 currently loaded for the fun, [] is returned instead of an
2314 atom.
2315 If Fun is an external fun, Name is the name of the exported
2317 function that the fun refers to.
2318 {arity, Arity}:
2320 Arity is the number of arguments that the fun is to be
2321 called with.
2322 {env, Env}:
2324 Env (a list) is the environment or free variables for the
2325 fun. For external funs, the returned list is always empty.
2326 The following elements are only present in the list if Fun is
2328 local:
2329 {pid, Pid}:
2331 Pid is the process identifier of the process that originally
2332 created the fun.
2333 It might point to the init process if the Fun was statically
2335 allocated when module was loaded (this optimisation is per‐
2336 formed for local functions that do not capture the environ‐
2337 ment).
2338 {index, Index}:
2340 Index (an integer) is an index into the module fun table.
2341 {new_index, Index}:
2343 Index (an integer) is an index into the module fun table.
2344 {new_uniq, Uniq}:
2346 Uniq (a binary) is a unique value for this fun. It is calcu‐
2347 lated from the compiled code for the entire module.
2348 {uniq, Uniq}:
2350 Uniq (an integer) is a unique value for this fun. As from
2351 Erlang/OTP R15, this integer is calculated from the compiled
2352 code for the entire module. Before Erlang/OTP R15, this in‐
2353 teger was based on only the body of the fun.
2354 erlang:fun_info(Fun, Item) -> {Item, Info}
2356 Types:
2358 Fun = function()
2360 Item = fun_info_item()
2361 Info = term()
2362 fun_info_item() =
2363 arity | env | index | name | module | new_index | new_uniq |
2364 pid | type | uniq
2365 Returns information about Fun as specified by Item, in the form
2367 {Item,Info}.
2368 For any fun, Item can be any of the atoms module, name, arity,
2370 env, or type.
2371 For a local fun, Item can also be any of the atoms index,
2373 new_index, new_uniq, uniq, and pid. For an external fun, the
2374 value of any of these items is always the atom undefined.
2375 See erlang:fun_info/1.
2377 erlang:fun_to_list(Fun) -> String :: string()
2379 Types:
2381 Fun = function()
2383 Returns String that represents the code that created Fun.
2385 String has the following form, if Fun was created by a fun ex‐
2387 pression of the form fun ModuleName:FuncName/Arity:
2388 "fun ModuleName:FuncName/Arity"
2390 The form of String when Fun is created from other types of fun
2392 expressions differs depending on if the fun expression was exe‐
2393 cuted while executing compiled code or if the fun expression was
2394 executed while executing uncompiled code (uncompiled escripts,
2395 the Erlang shell, and other code executed by the erl_eval mod‐
2396 ule):
2397 compiled code:
2399 "#Fun<M.I.U>", where M, I and U correspond to the values
2400 named module, index and uniq in the result of er‐
2401 lang:fun_info(Fun).
2402 uncompiled code:
2404 All funs created from fun expressions in uncompiled code
2405 with the same arity are mapped to the same list by
2406 fun_to_list/1.
2407 Note:
2409 Generally, one can not use fun_to_list/1 to check if two funs
2410 are equal as fun_to_list/1 does not take the fun's environment
2411 into account. See erlang:fun_info/1 for how to get the environ‐
2412 ment of a fun.
2413 Note:
2416 The output of fun_to_list/1 can differ between Erlang implemen‐
2417 tations and may change in future versions.
2418 Examples:
2421 -module(test).
2423 -export([add/1, add2/0, fun_tuple/0]).
2424 add(A) -> fun(B) -> A + B end.
2425 add2() -> fun add/1.
2426 fun_tuple() -> {fun() -> 1 end, fun() -> 1 end}.
2427 > {fun test:add/1, test:add2()}.
2430 {fun test:add/1,#Fun<test.1.107738983>}
2431 Explanation: fun test:add/1 is upgradable but test:add2() is not
2434 upgradable.
2435 > {test:add(1), test:add(42)}.
2437 {#Fun<test.0.107738983>,#Fun<test.0.107738983>}
2438 Explanation: test:add(1) and test:add(42) has the same string
2441 representation as the environment is not taken into account.
2442 >test:fun_tuple().
2444 {#Fun<test.2.107738983>,#Fun<test.3.107738983>}
2445 Explanation: The string representations differ because the funs
2448 come from different fun expressions.
2449 > {fun() -> 1 end, fun() -> 1 end}. >
2451 {#Fun<erl_eval.45.97283095>,#Fun<erl_eval.45.97283095>}
2452 Explanation: All funs created from fun expressions of this form
2455 in uncompiled code with the same arity are mapped to the same
2456 list by fun_to_list/1.
2457 erlang:function_exported(Module, Function, Arity) -> boolean()
2459 Types:
2461 Module = module()
2463 Function = atom()
2464 Arity = arity()
2465 Returns true if the module Module is current and contains an ex‐
2467 ported function Function/Arity, or if there is a BIF (a built-in
2468 function implemented in C) with the specified name, otherwise
2469 returns false.
2470 garbage_collect() -> true
2472 Forces an immediate garbage collection of the executing process.
2474 The function is not to be used unless it has been noticed (or
2475 there are good reasons to suspect) that the spontaneous garbage
2476 collection will occur too late or not at all.
2477 Warning:
2479 Improper use can seriously degrade system performance.
2480 garbage_collect(Pid) -> GCResult
2483 Types:
2485 Pid = pid()
2487 GCResult = boolean()
2488 The same as garbage_collect(Pid, []).
2490 garbage_collect(Pid, OptionList) -> GCResult | async
2492 Types:
2494 Pid = pid()
2496 RequestId = term()
2497 Option = {async, RequestId} | {type, major | minor}
2498 OptionList = [Option]
2499 GCResult = boolean()
2500 Garbage collects the node local process identified by Pid.
2502 Option:
2504 {async, RequestId}:
2506 The function garbage_collect/2 returns the value async imme‐
2507 diately after the request has been sent. When the request
2508 has been processed, the process that called this function is
2509 passed a message on the form {garbage_collect, RequestId,
2510 GCResult}.
2511 {type, 'major' | 'minor'}:
2513 Triggers garbage collection of requested type. Default value
2514 is 'major', which would trigger a fullsweep GC. The option
2515 'minor' is considered a hint and may lead to either minor or
2516 major GC run.
2517 If Pid equals self(), and no async option has been passed, the
2519 garbage collection is performed at once, that is, the same as
2520 calling garbage_collect/0. Otherwise a request for garbage col‐
2521 lection is sent to the process identified by Pid, and will be
2522 handled when appropriate. If no async option has been passed,
2523 the caller blocks until GCResult is available and can be re‐
2524 turned.
2525 GCResult informs about the result of the garbage collection re‐
2527 quest as follows:
2528 true:
2530 The process identified by Pid has been garbage collected.
2531 false:
2533 No garbage collection was performed, as the process identi‐
2534 fied by Pid terminated before the request could be satis‐
2535 fied.
2536 Notice that the same caveats apply as for garbage_collect/0.
2538 Failures:
2540 badarg:
2542 If Pid is not a node local process identifier.
2543 badarg:
2545 If OptionList is an invalid list of options.
2546 get() -> [{Key, Val}]
2548 Types:
2550 Key = Val = term()
2552 Returns the process dictionary as a list of {Key, Val} tuples.
2554 The items in the returned list can be in any order. Example:
2555 > put(key1, merry),
2557 put(key2, lambs),
2558 put(key3, {are, playing}),
2559 get().
2560 [{key1,merry},{key2,lambs},{key3,{are,playing}}]
2561 get(Key) -> Val | undefined
2563 Types:
2565 Key = Val = term()
2567 Returns the value Val associated with Key in the process dictio‐
2569 nary, or undefined if Key does not exist. The expected time com‐
2570 plexity for the current implementation of this function is O(1)
2571 and the worst case time complexity is O(N), where N is the num‐
2572 ber of items in the process dictionary. Example:
2573 > put(key1, merry),
2575 put(key2, lambs),
2576 put({any, [valid, term]}, {are, playing}),
2577 get({any, [valid, term]}).
2578 {are,playing}
2579 erlang:get_cookie() -> Cookie | nocookie
2581 Types:
2583 Cookie = atom()
2585 Returns the magic cookie of the local node if the node is alive,
2587 otherwise the atom nocookie. This value is set by set_cookie/1.
2588 erlang:get_cookie(Node) -> Cookie | nocookie
2590 Types:
2592 Node = node()
2594 Cookie = atom()
2595 Returns the magic cookie for node Node if the local node is
2597 alive, otherwise the atom nocookie. This value is set by
2598 set_cookie/2.
2599 get_keys() -> [Key]
2601 Types:
2603 Key = term()
2605 Returns a list of all keys present in the process dictionary.
2607 The items in the returned list can be in any order. Example:
2608 > put(dog, {animal,1}),
2610 put(cow, {animal,2}),
2611 put(lamb, {animal,3}),
2612 get_keys().
2613 [dog,cow,lamb]
2614 get_keys(Val) -> [Key]
2616 Types:
2618 Val = Key = term()
2620 Returns a list of keys that are associated with the value Val in
2622 the process dictionary. The items in the returned list can be in
2623 any order. Example:
2624 > put(mary, {1, 2}),
2626 put(had, {1, 2}),
2627 put(a, {1, 2}),
2628 put(little, {1, 2}),
2629 put(dog, {1, 3}),
2630 put(lamb, {1, 2}),
2631 get_keys({1, 2}).
2632 [mary,had,a,little,lamb]
2633 group_leader() -> pid()
2635 Returns the process identifier of the group leader for the
2637 process evaluating the function.
2638 Every process is a member of some process group and all groups
2640 have a group leader. All I/O from the group is channeled to the
2641 group leader. When a new process is spawned, it gets the same
2642 group leader as the spawning process. Initially, at system
2643 startup, init is both its own group leader and the group leader
2644 of all processes.
2645 group_leader(GroupLeader, Pid) -> true
2647 Types:
2649 GroupLeader = Pid = pid()
2651 Sets the group leader of Pid to GroupLeader. Typically, this is
2653 used when a process started from a certain shell is to have an‐
2654 other group leader than init.
2655 The group leader should be rarely changed in applications with a
2657 supervision tree, because OTP assumes the group leader of their
2658 processes is their application master.
2659 Setting the group leader follows the signal ordering guarantees
2661 described in the Processes Chapter in the Erlang Reference Man‐
2662 ual .
2663 See also group_leader/0 and OTP design principles related to
2665 starting and stopping applications.
2666 halt() -> no_return()
2668 The same as halt(0, []). Example:
2670 > halt().
2672 os_prompt%
2673 halt(Status) -> no_return()
2675 Types:
2677 Status = integer() >= 0 | abort | string()
2679 The same as halt(Status, []). Example:
2681 > halt(17).
2683 os_prompt% echo $?
2684 17
2685 os_prompt%
2686 halt(Status, Options) -> no_return()
2688 Types:
2690 Status = integer() >= 0 | abort | string()
2692 Options = [Option]
2693 Option = {flush, boolean()}
2694 Status must be a non-negative integer, a string, or the atom
2696 abort. Halts the Erlang runtime system. Has no return value. De‐
2697 pending on Status, the following occurs:
2698 integer():
2700 The runtime system exits with integer value Status as status
2701 code to the calling environment (OS).
2702 Note:
2704 On many platforms, the OS supports only status codes 0-255. A
2705 too large status code is truncated by clearing the high bits.
2706 string():
2709 An Erlang crash dump is produced with Status as slogan. Then
2710 the runtime system exits with status code 1. The string will
2711 be truncated if longer than 200 characters.
2712 Note:
2714 Before ERTS 9.1 (OTP-20.1) only code points in the range 0-255
2715 was accepted in the string. Now any unicode string is valid.
2716 abort:
2719 The runtime system aborts producing a core dump, if that is
2720 enabled in the OS.
2721 For integer Status, the Erlang runtime system closes all ports
2723 and allows async threads to finish their operations before exit‐
2724 ing. To exit without such flushing, use Option as {flush,false}.
2725 For statuses string() and abort, option flush is ignored and
2727 flushing is not done.
2728 hd(List) -> term()
2730 Types:
2732 List = [term(), ...]
2734 Returns the head of List, that is, the first element, for exam‐
2736 ple:
2737 > hd([1,2,3,4,5]).
2739 1
2740 Allowed in guard tests.
2742 Failure: badarg if List is the empty list [].
2744 erlang:hibernate(Module, Function, Args) -> no_return()
2746 Types:
2748 Module = module()
2750 Function = atom()
2751 Args = [term()]
2752 Puts the calling process into a wait state where its memory al‐
2754 location has been reduced as much as possible. This is useful if
2755 the process does not expect to receive any messages soon.
2756 The process is awaken when a message is sent to it, and control
2758 resumes in Module:Function with the arguments specified by Args
2759 with the call stack emptied, meaning that the process terminates
2760 when that function returns. Thus erlang:hibernate/3 never re‐
2761 turns to its caller. The resume function Module:Function/Arity
2762 must be exported (Arity =:= length(Args)).
2763 If the process has any message in its message queue, the process
2765 is awakened immediately in the same way as described earlier.
2766 In more technical terms, erlang:hibernate/3 discards the call
2768 stack for the process, and then garbage collects the process.
2769 After this, all live data is in one continuous heap. The heap is
2770 then shrunken to the exact same size as the live data that it
2771 holds (even if that size is less than the minimum heap size for
2772 the process).
2773 If the size of the live data in the process is less than the
2775 minimum heap size, the first garbage collection occurring after
2776 the process is awakened ensures that the heap size is changed to
2777 a size not smaller than the minimum heap size.
2778 Notice that emptying the call stack means that any surrounding
2780 catch is removed and must be re-inserted after hibernation. One
2781 effect of this is that processes started using proc_lib (also
2782 indirectly, such as gen_server processes), are to use
2783 proc_lib:hibernate/3 instead, to ensure that the exception han‐
2784 dler continues to work when the process wakes up.
2785 erlang:insert_element(Index, Tuple1, Term) -> Tuple2
2787 Types:
2789 Index = integer() >= 1
2791 1..tuple_size(Tuple1) + 1
2792 Tuple1 = Tuple2 = tuple()
2793 Term = term()
2794 Returns a new tuple with element Term inserted at position Index
2796 in tuple Tuple1. All elements from position Index and upwards
2797 are pushed one step higher in the new tuple Tuple2. Example:
2798 > erlang:insert_element(2, {one, two, three}, new).
2800 {one,new,two,three}
2801 integer_to_binary(Integer) -> binary()
2803 Types:
2805 Integer = integer()
2807 Returns a binary corresponding to the text representation of In‐
2809 teger, for example:
2810 > integer_to_binary(77).
2812 <<"77">>
2813 integer_to_binary(Integer, Base) -> binary()
2815 Types:
2817 Integer = integer()
2819 Base = 2..36
2820 Returns a binary corresponding to the text representation of In‐
2822 teger in base Base, for example:
2823 > integer_to_binary(1023, 16).
2825 <<"3FF">>
2826 integer_to_list(Integer) -> string()
2828 Types:
2830 Integer = integer()
2832 Returns a string corresponding to the text representation of In‐
2834 teger, for example:
2835 > integer_to_list(77).
2837 "77"
2838 integer_to_list(Integer, Base) -> string()
2840 Types:
2842 Integer = integer()
2844 Base = 2..36
2845 Returns a string corresponding to the text representation of In‐
2847 teger in base Base, for example:
2848 > integer_to_list(1023, 16).
2850 "3FF"
2851 iolist_size(Item) -> integer() >= 0
2853 Types:
2855 Item = iolist() | binary()
2857 Returns an integer, that is the size in bytes, of the binary
2859 that would be the result of iolist_to_binary(Item), for example:
2860 > iolist_size([1,2|<<3,4>>]).
2862 4
2863 iolist_to_binary(IoListOrBinary) -> binary()
2865 Types:
2867 IoListOrBinary = iolist() | binary()
2869 Returns a binary that is made from the integers and binaries in
2871 IoListOrBinary, for example:
2872 > Bin1 = <<1,2,3>>.
2874 <<1,2,3>>
2875 > Bin2 = <<4,5>>.
2876 <<4,5>>
2877 > Bin3 = <<6>>.
2878 <<6>>
2879 > iolist_to_binary([Bin1,1,[2,3,Bin2],4|Bin3]).
2880 <<1,2,3,1,2,3,4,5,4,6>>
2881 erlang:iolist_to_iovec(IoListOrBinary) -> iovec()
2883 Types:
2885 IoListOrBinary = iolist() | binary()
2887 Returns an iovec that is made from the integers and binaries in
2889 IoListOrBinary. This function is useful when you want to flatten
2890 an iolist but you do not need a single binary. This can be use‐
2891 ful for passing the data to nif functions such as enif_in‐
2892 spect_iovec or do more efficient message passing. The advantage
2893 of using this function over iolist_to_binary/1 is that it does
2894 not have to copy off-heap binaries. Example:
2895 > Bin1 = <<1,2,3>>.
2897 <<1,2,3>>
2898 > Bin2 = <<4,5>>.
2899 <<4,5>>
2900 > Bin3 = <<6>>.
2901 <<6>>
2902 %% If you pass small binaries and integers it works as iolist_to_binary
2903 > erlang:iolist_to_iovec([Bin1,1,[2,3,Bin2],4|Bin3]).
2904 [<<1,2,3,1,2,3,4,5,4,6>>]
2905 %% If you pass larger binaries, they are split and returned in a form
2906 %% optimized for calling the C function writev.
2907 > erlang:iolist_to_iovec([<<1>>,<<2:8096>>,<<3:8096>>]).
2908 [<<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,
2909 0,...>>,
2910 <<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,
2911 ...>>,
2912 <<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,...>>]
2913 is_alive() -> boolean()
2915 Returns true if the local node is alive (that is, if the node
2917 can be part of a distributed system), otherwise false. A node is
2918 alive if it is started with:
2919 * "erl -name LONGNAME" or,
2921 * "erl -sname SHORTNAME".
2923 A node can also be alive if it has got a name from a call to
2925 net_kernel:start/1 and has not been stopped by a call to
2926 net_kernel:stop/0.
2927 is_atom(Term) -> boolean()
2929 Types:
2931 Term = term()
2933 Returns true if Term is an atom, otherwise false.
2935 Allowed in guard tests.
2937 is_binary(Term) -> boolean()
2939 Types:
2941 Term = term()
2943 Returns true if Term is a binary, otherwise false.
2945 A binary always contains a complete number of bytes.
2947 Allowed in guard tests.
2949 is_bitstring(Term) -> boolean()
2951 Types:
2953 Term = term()
2955 Returns true if Term is a bitstring (including a binary), other‐
2957 wise false.
2958 Allowed in guard tests.
2960 is_boolean(Term) -> boolean()
2962 Types:
2964 Term = term()
2966 Returns true if Term is the atom true or the atom false (that
2968 is, a boolean). Otherwise returns false.
2969 Allowed in guard tests.
2971 erlang:is_builtin(Module, Function, Arity) -> boolean()
2973 Types:
2975 Module = module()
2977 Function = atom()
2978 Arity = arity()
2979 This BIF is useful for builders of cross-reference tools.
2981 Returns true if Module:Function/Arity is a BIF implemented in C,
2983 otherwise false.
2984 is_float(Term) -> boolean()
2986 Types:
2988 Term = term()
2990 Returns true if Term is a floating point number, otherwise
2992 false.
2993 Allowed in guard tests.
2995 is_function(Term) -> boolean()
2997 Types:
2999 Term = term()
3001 Returns true if Term is a fun, otherwise false.
3003 Allowed in guard tests.
3005 is_function(Term, Arity) -> boolean()
3007 Types:
3009 Term = term()
3011 Arity = arity()
3012 Returns true if Term is a fun that can be applied with Arity
3014 number of arguments, otherwise false.
3015 Allowed in guard tests.
3017 is_integer(Term) -> boolean()
3019 Types:
3021 Term = term()
3023 Returns true if Term is an integer, otherwise false.
3025 Allowed in guard tests.
3027 is_list(Term) -> boolean()
3029 Types:
3031 Term = term()
3033 Returns true if Term is a list with zero or more elements, oth‐
3035 erwise false.
3036 Allowed in guard tests.
3038 is_map(Term) -> boolean()
3040 Types:
3042 Term = term()
3044 Returns true if Term is a map, otherwise false.
3046 Allowed in guard tests.
3048 is_map_key(Key, Map) -> boolean()
3050 Types:
3052 Key = term()
3054 Map = map()
3055 Returns true if map Map contains Key and returns false if it
3057 does not contain the Key.
3058 The call fails with a {badmap,Map} exception if Map is not a
3060 map.
3061 Example:
3063 > Map = #{"42" => value}.
3065 #{"42" => value}
3066 > is_map_key("42",Map).
3067 true
3068 > is_map_key(value,Map).
3069 false
3070 Allowed in guard tests.
3072 is_number(Term) -> boolean()
3074 Types:
3076 Term = term()
3078 Returns true if Term is an integer or a floating point number.
3080 Otherwise returns false.
3081 Allowed in guard tests.
3083 is_pid(Term) -> boolean()
3085 Types:
3087 Term = term()
3089 Returns true if Term is a process identifier, otherwise false.
3091 Allowed in guard tests.
3093 is_port(Term) -> boolean()
3095 Types:
3097 Term = term()
3099 Returns true if Term is a port identifier, otherwise false.
3101 Allowed in guard tests.
3103 is_process_alive(Pid) -> boolean()
3105 Types:
3107 Pid = pid()
3109 Pid must refer to a process at the local node.
3111 Returns true if the process exists and is alive, that is, is not
3113 exiting and has not exited. Otherwise returns false.
3114 If process P1 calls is_process_alive(P2Pid) it is guaranteed
3116 that all signals, sent from P1 to P2 (P2 is the process with
3117 identifier P2Pid) before the call, will be delivered to P2 be‐
3118 fore the aliveness of P2 is checked. This guarantee means that
3119 one can use is_process_alive/1 to let a process P1 wait until a
3120 process P2, which has got an exit signal with reason kill from
3121 P1, is killed. Example:
3122 exit(P2Pid, kill),
3124 % P2 might not be killed
3125 is_process_alive(P2Pid),
3126 % P2 is not alive (the call above always return false)
3127 See the documentation about signals and erlang:exit/2 for more
3130 information about signals and exit signals.
3131 is_record(Term, RecordTag) -> boolean()
3133 Types:
3135 Term = term()
3137 RecordTag = atom()
3138 Returns true if Term is a tuple and its first element is Record‐
3140 Tag. Otherwise returns false.
3141 Note:
3143 Normally the compiler treats calls to is_record/2 especially. It
3144 emits code to verify that Term is a tuple, that its first ele‐
3145 ment is RecordTag, and that the size is correct. However, if
3146 RecordTag is not a literal atom, the BIF is_record/2 is called
3147 instead and the size of the tuple is not verified.
3148 Allowed in guard tests, if RecordTag is a literal atom.
3151 is_record(Term, RecordTag, Size) -> boolean()
3153 Types:
3155 Term = term()
3157 RecordTag = atom()
3158 Size = integer() >= 0
3159 RecordTag must be an atom.
3161 Returns true if Term is a tuple, its first element is RecordTag,
3163 and its size is Size. Otherwise returns false.
3164 Allowed in guard tests if RecordTag is a literal atom and Size
3166 is a literal integer.
3167 Note:
3169 This BIF is documented for completeness. Usually is_record/2 is
3170 to be used.
3171 is_reference(Term) -> boolean()
3174 Types:
3176 Term = term()
3178 Returns true if Term is a reference, otherwise false.
3180 Allowed in guard tests.
3182 is_tuple(Term) -> boolean()
3184 Types:
3186 Term = term()
3188 Returns true if Term is a tuple, otherwise false.
3190 Allowed in guard tests.
3192 length(List) -> integer() >= 0
3194 Types:
3196 List = [term()]
3198 Returns the length of List, for example:
3200 > length([1,2,3,4,5,6,7,8,9]).
3202 9
3203 Allowed in guard tests.
3205 link(PidOrPort) -> true
3207 Types:
3209 PidOrPort = pid() | port()
3211 Sets up and activates a link between the calling process and an‐
3213 other process or a port identified by PidOrPort. We will from
3214 here on call the identified process or port linkee. If the lin‐
3215 kee is a port, it must reside on the same node as the caller.
3216 If one of the participants of a link terminates, it will send an
3218 exit signal to the other participant. The exit signal will con‐
3219 tain the exit reason of the terminated participant. Other cases
3220 when exit signals are triggered due to a link are when no linkee
3221 exist (noproc exit reason) and when the connection between
3222 linked processes on different nodes is lost or cannot be estab‐
3223 lished (noconnection exit reason).
3224 An existing link can be removed by calling unlink/1. For more
3226 information on links and exit signals due to links, see the Pro‐
3227 cesses chapter in the Erlang Reference Manual :
3228 * Links
3230 * Sending Exit Signals
3232 * Receiving Exit Signals
3234 For historical reasons, link/1 has a strange semi-synchronous
3236 behavior when it is "cheap" to check if the linkee exists or
3237 not, and the caller does not trap exits. If the above is true
3238 and the linkee does not exist, link/1 will raise a noproc error
3239 exception. The expected behavior would instead have been that
3240 link/1 returned true, and the caller later was sent an exit sig‐
3241 nal with noproc exit reason, but this is unfortunately not the
3242 case. The noproc exception is not to be confused with an exit
3243 signal with exit reason noproc. Currently it is "cheap" to check
3244 if the linkee exists when it is supposed to reside on the same
3245 node as the calling process.
3246 The link setup and activation is performed asynchronously. If
3248 the link already exists, or if the caller attempts to create a
3249 link to itself, nothing is done. A detailed description of the
3250 link protocol can be found in the Distribution Protocol chapter
3251 of the ERTS User's Guide .
3252 Failure:
3254 * badarg if PidOrPort does not identify a process or a node
3256 local port.
3257 * noproc linkee does not exist and it is "cheap" to check if
3259 it exists as described above.
3260 list_to_atom(String) -> atom()
3262 Types:
3264 String = string()
3266 Returns the atom whose text representation is String.
3268 As from Erlang/OTP 20, String may contain any Unicode character.
3270 Earlier versions allowed only ISO-latin-1 characters as the im‐
3271 plementation did not allow Unicode characters above 255.
3272 Note:
3274 The number of characters that are permitted in an atom name is
3275 limited. The default limits can be found in the efficiency
3276 guide (section Advanced).
3277 Note:
3280 There is configurable limit on how many atoms that can exist and
3281 atoms are not garbage collected. Therefore, it is recommended to
3282 consider if list_to_existing_atom/1 is a better option than
3283 list_to_atom/1. The default limits can be found in the effi‐
3284 ciency guide (section Advanced).
3285 Example:
3288 > list_to_atom("Erlang").
3290 list_to_binary(IoList) -> binary()
3292 Types:
3294 IoList = iolist()
3296 Returns a binary that is made from the integers and binaries in
3298 IoList, for example:
3299 > Bin1 = <<1,2,3>>.
3301 <<1,2,3>>
3302 > Bin2 = <<4,5>>.
3303 <<4,5>>
3304 > Bin3 = <<6>>.
3305 <<6>>
3306 > list_to_binary([Bin1,1,[2,3,Bin2],4|Bin3]).
3307 <<1,2,3,1,2,3,4,5,4,6>>
3308 list_to_bitstring(BitstringList) -> bitstring()
3310 Types:
3312 BitstringList = bitstring_list()
3314 bitstring_list() =
3315 maybe_improper_list(byte() | bitstring() | bitstring_list(),
3316 bitstring() | [])
3317 Returns a bitstring that is made from the integers and bit‐
3319 strings in BitstringList. (The last tail in BitstringList is al‐
3320 lowed to be a bitstring.) Example:
3321 > Bin1 = <<1,2,3>>.
3323 <<1,2,3>>
3324 > Bin2 = <<4,5>>.
3325 <<4,5>>
3326 > Bin3 = <<6,7:4>>.
3327 <<6,7:4>>
3328 > list_to_bitstring([Bin1,1,[2,3,Bin2],4|Bin3]).
3329 <<1,2,3,1,2,3,4,5,4,6,7:4>>
3330 list_to_existing_atom(String) -> atom()
3332 Types:
3334 String = string()
3336 Returns the atom whose text representation is String, but only
3338 if there already exists such atom. An atom exists if it has been
3339 created by the run-time system by either loading code or creat‐
3340 ing a term in which the atom is part.
3341 Failure: badarg if there does not already exist an atom whose
3343 text representation is String.
3344 Note:
3346 Note that the compiler may optimize away atoms. For example, the
3347 compiler will rewrite atom_to_list(some_atom) to "some_atom". If
3348 that expression is the only mention of the atom some_atom in the
3349 containing module, the atom will not be created when the module
3350 is loaded, and a subsequent call to list_to_exist‐
3351 ing_atom("some_atom") will fail.
3352 list_to_float(String) -> float()
3355 Types:
3357 String = string()
3359 Returns the float whose text representation is String, for exam‐
3361 ple:
3362 > list_to_float("2.2017764e+0").
3364 2.2017764
3365 The float string format is the same as the format for Erlang
3367 float literals except for that underscores are not permitted.
3368 Failure: badarg if String contains a bad representation of a
3370 float.
3371 list_to_integer(String) -> integer()
3373 Types:
3375 String = string()
3377 Returns an integer whose text representation is String, for ex‐
3379 ample:
3380 > list_to_integer("123").
3382 123
3383 > list_to_integer("-123").
3385 -123
3386 > list_to_integer("+123234982304982309482093833234234").
3388 123234982304982309482093833234234
3389 String must contain at least one digit character and can have an
3391 optional prefix consisting of a single "+" or "-" character
3392 (that is, String must match the regular expression
3393 "^[+-]?[0-9]+$").
3394 Failure: badarg if String contains a bad representation of an
3396 integer.
3397 list_to_integer(String, Base) -> integer()
3399 Types:
3401 String = string()
3403 Base = 2..36
3404 Returns an integer whose text representation in base Base is
3406 String, for example:
3407 > list_to_integer("3FF", 16).
3409 1023
3410 > list_to_integer("+3FF", 16).
3412 1023
3413 > list_to_integer("3ff", 16).
3415 1023
3416 > list_to_integer("3fF", 16).
3418 1023
3419 > list_to_integer("-3FF", 16).
3421 -1023
3422 For example, when Base is 16, String must match the regular ex‐
3424 pression "^[+-]?([0-9]|[A-F]|[a-f])+$".
3425 Failure: badarg if String contains a bad representation of an
3427 integer.
3428 list_to_pid(String) -> pid()
3430 Types:
3432 String = string()
3434 Returns a process identifier whose text representation is a
3436 String, for example:
3437 > list_to_pid("<0.4.1>").
3439 <0.4.1>
3440 Failure: badarg if String contains a bad representation of a
3442 process identifier.
3443 Warning:
3445 This BIF is intended for debugging and is not to be used in ap‐
3446 plication programs.
3447 list_to_port(String) -> port()
3450 Types:
3452 String = string()
3454 Returns a port identifier whose text representation is a String,
3456 for example:
3457 > list_to_port("#Port<0.4>").
3459 #Port<0.4>
3460 Failure: badarg if String contains a bad representation of a
3462 port identifier.
3463 Warning:
3465 This BIF is intended for debugging and is not to be used in ap‐
3466 plication programs.
3467 list_to_ref(String) -> reference()
3470 Types:
3472 String = string()
3474 Returns a reference whose text representation is a String, for
3476 example:
3477 > list_to_ref("#Ref<0.4192537678.4073193475.71181>").
3479 #Ref<0.4192537678.4073193475.71181>
3480 Failure: badarg if String contains a bad representation of a
3482 reference.
3483 Warning:
3485 This BIF is intended for debugging and is not to be used in ap‐
3486 plication programs.
3487 list_to_tuple(List) -> tuple()
3490 Types:
3492 List = [term()]
3494 Returns a tuple corresponding to List, for example
3496 > list_to_tuple([share, ['Ericsson_B', 163]]).
3498 {share, ['Ericsson_B', 163]}
3499 List can contain any Erlang terms.
3501 load_module(Module, Binary) -> {module, Module} | {error, Reason}
3503 Types:
3505 Module = module()
3507 Binary = binary()
3508 Reason =
3509 badfile | not_purged | on_load |
3510 {features_not_allowed, [atom()]}
3511 If Binary contains the object code for module Module, this BIF
3513 loads that object code. If the code for module Module already
3514 exists, all export references are replaced so they point to the
3515 newly loaded code. The previously loaded code is kept in the
3516 system as old code, as there can still be processes executing
3517 that code.
3518 Returns either {module, Module}, or {error, Reason} if loading
3520 fails. Reason is one of the following:
3521 badfile:
3523 The object code in Binary has an incorrect format or the ob‐
3524 ject code contains code for another module than Module.
3525 not_purged:
3527 Binary contains a module that cannot be loaded because old
3528 code for this module already exists.
3529 on_load:
3531 The code in Binary contains an on_load declaration that must
3532 be executed before Binary can become the current code. Any
3533 previous current code for Module will remain until the
3534 on_load call has finished.
3535 not_allowed:
3537 The code in Binary has been compiled with features that are
3538 currently not enabled in the runtime system.
3539 Warning:
3541 This BIF is intended for the code server (see code(3)) and is
3542 not to be used elsewhere.
3543 erlang:load_nif(Path, LoadInfo) -> ok | Error
3546 Types:
3548 Path = string()
3550 LoadInfo = term()
3551 Error = {error, {Reason, Text :: string()}}
3552 Reason =
3553 load_failed | bad_lib | load | reload | upgrade |
3554 old_code
3555 Loads and links a dynamic library containing native implemented
3557 functions (NIFs) for a module. Path is a file path to the share‐
3558 able object/dynamic library file minus the OS-dependent file ex‐
3559 tension (.so for Unix and .dll for Windows). Notice that on most
3560 OSs the library has to have a different name on disc when an up‐
3561 grade of the nif is done. If the name is the same, but the con‐
3562 tents differ, the old library may be loaded instead. For infor‐
3563 mation on how to implement a NIF library, see erl_nif(3).
3564 LoadInfo can be any term. It is passed on to the library as part
3566 of the initialization. A good practice is to include a module
3567 version number to support future code upgrade scenarios.
3568 The call to load_nif/2 must be made directly from the Erlang
3570 code of the module that the NIF library belongs to. It returns
3571 either ok, or {error,{Reason,Text}} if loading fails. Reason is
3572 one of the following atoms while Text is a human readable string
3573 that can give more information about the failure:
3574 load_failed:
3576 The OS failed to load the NIF library.
3577 bad_lib:
3579 The library did not fulfill the requirements as a NIF li‐
3580 brary of the calling module.
3581 load | upgrade:
3583 The corresponding library callback was unsuccessful.
3584 reload:
3586 A NIF library is already loaded for this module instance.
3587 The previously deprecated reload feature was removed in OTP
3588 20.
3589 old_code:
3591 The call to load_nif/2 was made from the old code of a mod‐
3592 ule that has been upgraded; this is not allowed.
3593 If the -nifs() attribute is used (which is recommended), all
3595 NIFs in the dynamic library much be declared as such for
3596 load_nif/2 to succeed. On the other hand, all functions declared
3597 with the -nifs() attribute do not have to be implemented by the
3598 dynamic library. This allows a target independent Erlang file to
3599 contain fallback implementations for functions that may lack NIF
3600 support depending on target OS/hardware platform.
3601 erlang:loaded() -> [Module]
3603 Types:
3605 Module = module()
3607 Returns a list of all loaded Erlang modules (current and old
3609 code), including preloaded modules.
3610 See also code(3).
3612 erlang:localtime() -> DateTime
3614 Types:
3616 DateTime = calendar:datetime()
3618 Returns the current local date and time, {{Year, Month, Day},
3620 {Hour, Minute, Second}}, for example:
3621 > erlang:localtime().
3623 {{1996,11,6},{14,45,17}}
3624 The time zone and Daylight Saving Time correction depend on the
3626 underlying OS. The return value is based on the OS System Time.
3627 erlang:localtime_to_universaltime(Localtime) -> Universaltime
3629 Types:
3631 Localtime = Universaltime = calendar:datetime()
3633 Converts local date and time to Universal Time Coordinated
3635 (UTC), if supported by the underlying OS. Otherwise no conver‐
3636 sion is done and Localtime is returned. Example:
3637 > erlang:localtime_to_universaltime({{1996,11,6},{14,45,17}}).
3639 {{1996,11,6},{13,45,17}}
3640 Failure: badarg if Localtime denotes an invalid date and time.
3642 erlang:localtime_to_universaltime(Localtime, IsDst) ->
3644 Universaltime
3645 Types:
3647 Localtime = Universaltime = calendar:datetime()
3649 IsDst = true | false | undefined
3650 Converts local date and time to Universal Time Coordinated (UTC)
3652 as erlang:localtime_to_universaltime/1, but the caller decides
3653 if Daylight Saving Time is active.
3654 If IsDst == true, Localtime is during Daylight Saving Time, if
3656 IsDst == false it is not. If IsDst == undefined, the underlying
3657 OS can guess, which is the same as calling erlang:local‐
3658 time_to_universaltime(Localtime).
3659 Examples:
3661 > erlang:localtime_to_universaltime({{1996,11,6},{14,45,17}}, true).
3663 {{1996,11,6},{12,45,17}}
3664 > erlang:localtime_to_universaltime({{1996,11,6},{14,45,17}}, false).
3665 {{1996,11,6},{13,45,17}}
3666 > erlang:localtime_to_universaltime({{1996,11,6},{14,45,17}}, undefined).
3667 {{1996,11,6},{13,45,17}}
3668 Failure: badarg if Localtime denotes an invalid date and time.
3670 make_ref() -> reference()
3672 Returns a unique reference. The reference is unique among con‐
3674 nected nodes.
3675 Warning:
3677 Before OTP-23 when a node is restarted multiple times with the
3678 same node name, references created on a newer node can be mis‐
3679 taken for a reference created on an older node with the same
3680 node name.
3681 erlang:make_tuple(Arity, InitialValue) -> tuple()
3684 Types:
3686 Arity = arity()
3688 InitialValue = term()
3689 Creates a new tuple of the specified Arity, where all elements
3691 are InitialValue, for example:
3692 > erlang:make_tuple(4, []).
3694 {[],[],[],[]}
3695 erlang:make_tuple(Arity, DefaultValue, InitList) -> tuple()
3697 Types:
3699 Arity = arity()
3701 DefaultValue = term()
3702 InitList = [{Position :: integer() >= 1, term()}]
3703 Creates a tuple of size Arity, where each element has value De‐
3705 faultValue, and then fills in values from InitList. Each list
3706 element in InitList must be a two-tuple, where the first element
3707 is a position in the newly created tuple and the second element
3708 is any term. If a position occurs more than once in the list,
3709 the term corresponding to the last occurrence is used. Example:
3710 > erlang:make_tuple(5, [], [{2,ignored},{5,zz},{2,aa}]).
3712 {[],aa,[],[],zz}
3713 map_get(Key, Map) -> Value
3715 Types:
3717 Map = map()
3719 Key = Value = any()
3720 Returns value Value associated with Key if Map contains Key.
3722 The call fails with a {badmap,Map} exception if Map is not a
3724 map, or with a {badkey,Key} exception if no value is associated
3725 with Key.
3726 Example:
3728 > Key = 1337,
3730 Map = #{42 => value_two,1337 => "value one","a" => 1},
3731 map_get(Key,Map).
3732 "value one"
3733 Allowed in guard tests.
3735 map_size(Map) -> integer() >= 0
3737 Types:
3739 Map = map()
3741 Returns an integer, which is the number of key-value pairs in
3743 Map, for example:
3744 > map_size(#{a=>1, b=>2, c=>3}).
3746 3
3747 Allowed in guard tests.
3749 erlang:match_spec_test(MatchAgainst, MatchSpec, Type) ->
3751 TestResult
3752 Types:
3754 MatchAgainst = [term()] | tuple()
3756 MatchSpec = term()
3757 Type = table | trace
3758 TestResult =
3759 {ok, term(), [return_trace], [{error | warning,
3760 string()}]} |
3761 {error, [{error | warning, string()}]}
3762 Tests a match specification used in calls to ets:select/2 and
3764 erlang:trace_pattern/3. The function tests both a match specifi‐
3765 cation for "syntactic" correctness and runs the match specifica‐
3766 tion against the object. If the match specification contains er‐
3767 rors, the tuple {error, Errors} is returned, where Errors is a
3768 list of natural language descriptions of what was wrong with the
3769 match specification.
3770 If Type is table, the object to match against is to be a tuple.
3772 The function then returns {ok,Result,[],Warnings}, where Result
3773 is what would have been the result in a real ets:select/2 call,
3774 or false if the match specification does not match the object
3775 tuple.
3776 If Type is trace, the object to match against is to be a list.
3778 The function returns {ok, Result, Flags, Warnings}, where Result
3779 is one of the following:
3780 * true if a trace message is to be emitted
3782 * false if a trace message is not to be emitted
3784 * The message term to be appended to the trace message
3786 Flags is a list containing all the trace flags to be enabled,
3788 currently this is only return_trace.
3789 This is a useful debugging and test tool, especially when writ‐
3791 ing complicated match specifications.
3792 See also ets:test_ms/2.
3794 max(Term1, Term2) -> Maximum
3796 Types:
3798 Term1 = Term2 = Maximum = term()
3800 Returns the largest of Term1 and Term2. If the terms compare
3802 equal with the == operator, Term1 is returned.
3803 The Expressions section contains descriptions of the == opera‐
3805 tor and how terms are ordered.
3806 Examples:
3808 > max(1, 2).
3810 2
3811 > max(1.0, 1).
3813 1.0
3814 > max(1, 1.0).
3816 1
3817 > max("abc", "b").
3819 "b"
3820 erlang:md5(Data) -> Digest
3822 Types:
3824 Data = iodata()
3826 Digest = binary()
3827 Computes an MD5 message digest from Data, where the length of
3829 the digest is 128 bits (16 bytes). Data is a binary or a list of
3830 small integers and binaries.
3831 For more information about MD5, see RFC 1321 - The MD5 Message-
3833 Digest Algorithm.
3834 Warning:
3836 The MD5 Message-Digest Algorithm is not considered safe for
3837 code-signing or software-integrity purposes.
3838 erlang:md5_final(Context) -> Digest
3841 Types:
3843 Context = Digest = binary()
3845 Finishes the update of an MD5 Context and returns the computed
3847 MD5 message digest.
3848 erlang:md5_init() -> Context
3850 Types:
3852 Context = binary()
3854 Creates an MD5 context, to be used in the following calls to
3856 md5_update/2.
3857 erlang:md5_update(Context, Data) -> NewContext
3859 Types:
3861 Context = binary()
3863 Data = iodata()
3864 NewContext = binary()
3865 Update an MD5 Context with Data and returns a NewContext.
3867 erlang:memory() -> [{Type, Size}]
3869 Types:
3871 Type = memory_type()
3873 Size = integer() >= 0
3874 memory_type() =
3875 total | processes | processes_used | system | atom |
3876 atom_used | binary | code | ets
3877 Returns a list with information about memory dynamically allo‐
3879 cated by the Erlang emulator. Each list element is a tuple
3880 {Type, Size}. The first element Type is an atom describing mem‐
3881 ory type. The second element Size is the memory size in bytes.
3882 Memory types:
3884 total:
3886 The total amount of memory currently allocated. This is the
3887 same as the sum of the memory size for processes and system.
3888 processes:
3890 The total amount of memory currently allocated for the Er‐
3891 lang processes.
3892 processes_used:
3894 The total amount of memory currently used by the Erlang pro‐
3895 cesses. This is part of the memory presented as processes
3896 memory.
3897 system:
3899 The total amount of memory currently allocated for the emu‐
3900 lator that is not directly related to any Erlang process.
3901 Memory presented as processes is not included in this mem‐
3902 ory. instrument(3) can be used to get a more detailed break‐
3903 down of what memory is part of this type.
3904 atom:
3906 The total amount of memory currently allocated for atoms.
3907 This memory is part of the memory presented as system mem‐
3908 ory.
3909 atom_used:
3911 The total amount of memory currently used for atoms. This
3912 memory is part of the memory presented as atom memory.
3913 binary:
3915 The total amount of memory currently allocated for binaries.
3916 This memory is part of the memory presented as system mem‐
3917 ory.
3918 code:
3920 The total amount of memory currently allocated for Erlang
3921 code. This memory is part of the memory presented as system
3922 memory.
3923 ets:
3925 The total amount of memory currently allocated for ETS ta‐
3926 bles. This memory is part of the memory presented as system
3927 memory.
3928 maximum:
3930 The maximum total amount of memory allocated since the emu‐
3931 lator was started. This tuple is only present when the emu‐
3932 lator is run with instrumentation.
3933 For information on how to run the emulator with instrumenta‐
3935 tion, see instrument(3) and/or erl(1).
3936 Note:
3938 The system value is not complete. Some allocated memory that is
3939 to be part of this value is not.
3940 When the emulator is run with instrumentation, the system value
3942 is more accurate, but memory directly allocated for malloc (and
3943 friends) is still not part of the system value. Direct calls to
3944 malloc are only done from OS-specific runtime libraries and per‐
3945 haps from user-implemented Erlang drivers that do not use the
3946 memory allocation functions in the driver interface.
3947 As the total value is the sum of processes and system, the error
3949 in system propagates to the total value.
3950 The different amounts of memory that are summed are not gathered
3952 atomically, which introduces an error in the result.
3953 The different values have the following relation to each other.
3956 Values beginning with an uppercase letter is not part of the re‐
3957 sult.
3958 total = processes + system
3960 processes = processes_used + ProcessesNotUsed
3961 system = atom + binary + code + ets + OtherSystem
3962 atom = atom_used + AtomNotUsed
3963 RealTotal = processes + RealSystem
3964 RealSystem = system + MissedSystem
3965 More tuples in the returned list can be added in a future re‐
3967 lease.
3968 Note:
3970 The total value is supposed to be the total amount of memory dy‐
3971 namically allocated by the emulator. Shared libraries, the code
3972 of the emulator itself, and the emulator stacks are not supposed
3973 to be included. That is, the total value is not supposed to be
3974 equal to the total size of all pages mapped to the emulator.
3975 Also, because of fragmentation and prereservation of memory ar‐
3977 eas, the size of the memory segments containing the dynamically
3978 allocated memory blocks can be much larger than the total size
3979 of the dynamically allocated memory blocks.
3980 Note:
3983 As from ERTS 5.6.4, erlang:memory/0 requires that all erts_al‐
3984 loc(3) allocators are enabled (default behavior).
3985 Failure: notsup if an erts_alloc(3) allocator has been disabled.
3988 erlang:memory(Type :: memory_type()) -> integer() >= 0
3990 erlang:memory(TypeList :: [memory_type()]) ->
3992 [{memory_type(), integer() >= 0}]
3993 Types:
3995 memory_type() =
3997 total | processes | processes_used | system | atom |
3998 atom_used | binary | code | ets
3999 Returns the memory size in bytes allocated for memory of type
4001 Type. The argument can also be specified as a list of mem‐
4002 ory_type() atoms, in which case a corresponding list of {mem‐
4003 ory_type(), Size :: integer >= 0} tuples is returned.
4004 Note:
4006 As from ERTS 5.6.4, erlang:memory/1 requires that all erts_al‐
4007 loc(3) allocators are enabled (default behavior).
4008 Failures:
4011 badarg:
4013 If Type is not one of the memory types listed in the de‐
4014 scription of erlang:memory/0.
4015 badarg:
4017 If maximum is passed as Type and the emulator is not run in
4018 instrumented mode.
4019 notsup:
4021 If an erts_alloc(3) allocator has been disabled.
4022 See also erlang:memory/0.
4024 min(Term1, Term2) -> Minimum
4026 Types:
4028 Term1 = Term2 = Minimum = term()
4030 Returns the smallest of Term1 and Term2. If the terms compare
4032 equal with the == operator, Term1 is returned.
4033 The Expressions section contains descriptions of the == opera‐
4035 tor and how terms are ordered.
4036 Examples:
4038 > min(1, 2).
4040 1
4041 > min(1.0, 1).
4043 1.0
4044 > min(1, 1.0).
4046 1
4047 > min("abc", "b").
4049 "abc"
4050 module_loaded(Module) -> boolean()
4052 Types:
4054 Module = module()
4056 Returns true if the module Module is loaded as current code ;
4058 otherwise, false. It does not attempt to load the module.
4059 monitor(Type :: process, Item :: monitor_process_identifier()) ->
4061 MonitorRef
4062 monitor(Type :: port, Item :: monitor_port_identifier()) ->
4064 MonitorRef
4065 monitor(Type :: time_offset, Item :: clock_service) -> MonitorRef
4067 Types:
4069 MonitorRef = reference()
4071 registered_name() = atom()
4072 registered_process_identifier() =
4073 registered_name() | {registered_name(), node()}
4074 monitor_process_identifier() =
4075 pid() | registered_process_identifier()
4076 monitor_port_identifier() = port() | registered_name()
4077 Sends a monitor request of type Type to the entity identified by
4079 Item. If the monitored entity does not exist or it changes moni‐
4080 tored state, the caller of monitor/2 is notified by a message on
4081 the following format:
4082 {Tag, MonitorRef, Type, Object, Info}
4084 Note:
4086 The monitor request is an asynchronous signal. That is, it takes
4087 time before the signal reaches its destination.
4088 Type can be one of the following atoms: process, port or
4091 time_offset.
4092 A process or port monitor is triggered only once, after that it
4094 is removed from both monitoring process and the monitored en‐
4095 tity. Monitors are fired when the monitored process or port ter‐
4096 minates, does not exist at the moment of creation, or if the
4097 connection to it is lost. If the connection to it is lost, we do
4098 not know if it still exists. The monitoring is also turned off
4099 when demonitor/1 is called.
4100 A process or port monitor by name resolves the RegisteredName to
4102 pid() or port() only once at the moment of monitor instantia‐
4103 tion, later changes to the name registration will not affect the
4104 existing monitor.
4105 When a process or port monitor is triggered, a 'DOWN' message is
4107 sent that has the following pattern:
4108 {'DOWN', MonitorRef, Type, Object, Info}
4110 In the monitor message MonitorRef and Type are the same as de‐
4112 scribed earlier, and:
4113 Object:
4115 The monitored entity, which triggered the event. When moni‐
4116 toring a process or a local port, Object will be equal to
4117 the pid() or port() that was being monitored. When monitor‐
4118 ing process or port by name, Object will have format {Regis‐
4119 teredName, Node} where RegisteredName is the name which has
4120 been used with monitor/2 call and Node is local or remote
4121 node name (for ports monitored by name, Node is always local
4122 node name).
4123 Info:
4125 Either the exit reason of the process, noproc (process or
4126 port did not exist at the time of monitor creation), or no‐
4127 connection (no connection to the node where the monitored
4128 process resides).
4129 Monitoring a process:
4131 Creates monitor between the current process and another
4132 process identified by Item, which can be a pid() (local or
4133 remote), an atom RegisteredName or a tuple {RegisteredName,
4134 Node} for a registered process, located elsewhere.
4135 Note:
4137 Before ERTS 10.0 (OTP 21.0), monitoring a process could fail
4138 with badarg if the monitored process resided on a primitive
4139 node (such as erl_interface or jinterface), where remote
4140 process monitoring is not implemented.
4141 Now, such a call to monitor will instead succeed and a monitor
4143 is created. But the monitor will only supervise the connec‐
4144 tion. That is, a {'DOWN', _, process, _, noconnection} is the
4145 only message that may be received, as the primitive node have
4146 no way of reporting the status of the monitored process.
4147 Monitoring a port:
4150 Creates monitor between the current process and a port iden‐
4151 tified by Item, which can be a port() (only local), an atom
4152 RegisteredName or a tuple {RegisteredName, Node} for a reg‐
4153 istered port, located on this node. Note, that attempt to
4154 monitor a remote port will result in badarg.
4155 Monitoring a time_offset:
4157 Monitors changes in time offset between Erlang monotonic
4158 time and Erlang system time. One valid Item exists in combi‐
4159 nation with the time_offset Type, namely the atom clock_ser‐
4160 vice. Notice that the atom clock_service is not the regis‐
4161 tered name of a process. In this case it serves as an iden‐
4162 tifier of the runtime system internal clock service at cur‐
4163 rent runtime system instance.
4164 The monitor is triggered when the time offset is changed.
4166 This either if the time offset value is changed, or if the
4167 offset is changed from preliminary to final during finaliza‐
4168 tion of the time offset when the single time warp mode is
4169 used. When a change from preliminary to final time offset is
4170 made, the monitor is triggered once regardless of whether
4171 the time offset value was changed or not.
4172 If the runtime system is in multi time warp mode, the time
4174 offset is changed when the runtime system detects that the
4175 OS system time has changed. The runtime system does, how‐
4176 ever, not detect this immediately when it occurs. A task
4177 checking the time offset is scheduled to execute at least
4178 once a minute, so under normal operation this is to be de‐
4179 tected within a minute, but during heavy load it can take
4180 longer time.
4181 The monitor is not automatically removed after it has been
4183 triggered. That is, repeated changes of the time offset
4184 trigger the monitor repeatedly.
4185 When the monitor is triggered a 'CHANGE' message is sent to
4187 the monitoring process. A 'CHANGE' message has the following
4188 pattern:
4189 {'CHANGE', MonitorRef, Type, Item, NewTimeOffset}
4191 where MonitorRef, Type, and Item are the same as described
4193 above, and NewTimeOffset is the new time offset.
4194 When the 'CHANGE' message has been received you are guaran‐
4196 teed not to retrieve the old time offset when calling er‐
4197 lang:time_offset(). Notice that you can observe the change
4198 of the time offset when calling erlang:time_offset() before
4199 you get the 'CHANGE' message.
4200 Making several calls to monitor/2 for the same Item and/or Type
4202 is not an error; it results in as many independent monitoring
4203 instances.
4204 The monitor functionality is expected to be extended. That is,
4206 other Types and Items are expected to be supported in a future
4207 release.
4208 Note:
4210 If or when monitor/2 is extended, other possible values for Tag,
4211 Object, and Info in the monitor message will be introduced.
4212 monitor(Type :: process,
4215 Item :: monitor_process_identifier(),
4216 Opts :: [monitor_option()]) ->
4217 MonitorRef
4218 monitor(Type :: port,
4220 Item :: monitor_port_identifier(),
4221 Opts :: [monitor_option()]) ->
4222 MonitorRef
4223 monitor(Type :: time_offset,
4225 Item :: clock_service,
4226 Opts :: [monitor_option()]) ->
4227 MonitorRef
4228 Types:
4230 MonitorRef = reference()
4232 registered_name() = atom()
4233 registered_process_identifier() =
4234 registered_name() | {registered_name(), node()}
4235 monitor_process_identifier() =
4236 pid() | registered_process_identifier()
4237 monitor_port_identifier() = port() | registered_name()
4238 Provides an option list for modification of monitoring function‐
4240 ality provided by monitor/2. The Type and Item arguments have
4241 the same meaning as when passed to monitor/2. Currently avail‐
4242 able options:
4243 {alias, UnaliasOpt}:
4245 The returned monitor reference will also become an alias for
4246 the calling process. That is, the returned reference can be
4247 used for sending messages to the calling process. See also
4248 alias/0. The UnaliasOpt determines how the alias should be
4249 deactivated.
4250 explicit_unalias:
4252 Only an explicit call to unalias/1 will deactivate the
4253 alias.
4254 demonitor:
4256 The alias will be automatically deactivated when the moni‐
4257 tor is removed. This either via an explicit call to demon‐
4258 itor/1 or when it is automatically removed at the same
4259 time as a 'DOWN' message is delivered due to the monitor.
4260 The alias can also still be deactivated via a call to una‐
4261 lias/1.
4262 reply_demonitor:
4264 The alias will be automatically deactivated when the moni‐
4265 tor is removed (see demonitor option above) or a reply
4266 message sent via the alias is received. When a reply mes‐
4267 sage is received via the alias the monitor will also be
4268 automatically removed. This is useful in client/server
4269 scenarios when a client monitors the server and will get
4270 the reply via the alias. Once the response is received
4271 both the alias and the monitor will be automatically re‐
4272 moved regardless of whether the response is a reply or a
4273 'DOWN' message. The alias can also still be deactivated
4274 via a call to unalias/1. Note that if the alias is removed
4275 using the unalias/1 BIF, the monitor will still be left
4276 active.
4277 Example:
4279 server() ->
4281 receive
4282 {request, AliasReqId, Request} ->
4283 Result = perform_request(Request),
4284 AliasReqId ! {reply, AliasReqId, Result}
4285 end,
4286 server().
4287 client(ServerPid, Request) ->
4289 AliasMonReqId = monitor(process, ServerPid, [{alias, reply_demonitor}]),
4290 ServerPid ! {request, AliasMonReqId, Request},
4291 %% Alias as well as monitor will be automatically deactivated if we
4292 %% receive a reply or a 'DOWN' message since we used 'reply_demonitor'
4293 %% as unalias option...
4294 receive
4295 {reply, AliasMonReqId, Result} ->
4296 Result;
4297 {'DOWN', AliasMonReqId, process, ServerPid, ExitReason} ->
4298 error(ExitReason)
4299 end.
4300 Note that both the server and the client in this example
4303 must be executing on at least OTP 24 systems in order for
4304 this to work.
4305 For more information on process aliases see the Process
4307 Aliases section of the Erlang Reference Manual .
4308 {tag, UserDefinedTag}:
4310 Replace the default Tag with UserDefinedTag in the monitor
4311 message delivered when the monitor is triggered. For exam‐
4312 ple, when monitoring a process, the 'DOWN' tag in the down
4313 message will be replaced by UserDefinedTag.
4314 An example of how the {tag, UserDefinedTag} option can be
4316 used in order to enable the new selective receive optimiza‐
4317 tion, introduced in OTP 24, when making multiple requests to
4318 different servers:
4319 server() ->
4321 receive
4322 {request, From, ReqId, Request} ->
4323 Result = perform_request(Request),
4324 From ! {reply, self(), ReqId, Result}
4325 end,
4326 server().
4327 client(ServerPids, Request) when is_list(ServerPids) ->
4329 ReqId = make_ref(),
4330 lists:foreach(fun (ServerPid) ->
4331 _ = monitor(process, ServerPid,
4332 [{tag, {'DOWN', ReqId}}]),
4333 ServerPid ! {request, self(), ReqId, Request}
4334 end,
4335 ServerPids),
4336 receive_replies(ReqId, length(ServerPids), []).
4337 receive_replies(_ReqId, 0, Acc) ->
4339 Acc;
4340 receive_replies(ReqId, N, Acc) ->
4341 %% The compiler will detect that we match on the 'ReqId'
4342 %% reference in all clauses, and will enable the selective
4343 %% receive optimization which makes the receive able to
4344 %% skip past all messages present in the message queue at
4345 %% the time when the 'ReqId' reference was created...
4346 Res = receive
4347 {reply, ServerPid, ReqId, Result} ->
4348 %% Here we typically would have deactivated the
4349 %% monitor by a call to demonitor(Mon, [flush]) but
4350 %% we ignore this in this example for simplicity...
4351 {ok, ServerPid, Result};
4352 {{'DOWN', ReqId}, _Mon, process, ServerPid, ExitReason} ->
4353 {error, ServerPid, ExitReason}
4354 end,
4355 receive_replies(ReqId, N-1, [Res | Acc]).
4356 In order for this example to work as intended, the client
4359 must be executing on at least an OTP 24 system, but the
4360 servers may execute on older systems.
4361 monitor_node(Node, Flag) -> true
4363 Types:
4365 Node = node()
4367 Flag = boolean()
4368 Monitor the status of the node Node. If Flag is true, monitoring
4370 is turned on. If Flag is false, monitoring is turned off.
4371 Making several calls to monitor_node(Node, true) for the same
4373 Node is not an error; it results in as many independent monitor‐
4374 ing instances.
4375 If Node fails or does not exist, the message {nodedown, Node} is
4377 delivered to the process. If a process has made two calls to
4378 monitor_node(Node, true) and Node terminates, two nodedown mes‐
4379 sages are delivered to the process. If there is no connection to
4380 Node, an attempt is made to create one. If this fails, a node‐
4381 down message is delivered.
4382 The delivery of the nodedown signal is not ordered with respect
4384 to other link or monitor signals from the node that goes down.
4385 If you need a guarantee that all signals from the remote node
4386 has been delivered before the nodedown signal is sent, you
4387 should use net_kernel:monitor_nodes/1.
4388 Nodes connected through hidden connections can be monitored as
4390 any other nodes.
4391 Failure: notalive if the local node is not alive.
4393 erlang:monitor_node(Node, Flag, Options) -> true
4395 Types:
4397 Node = node()
4399 Flag = boolean()
4400 Options = [Option]
4401 Option = allow_passive_connect
4402 Behaves as monitor_node/2 except that it allows an extra option
4404 to be specified, namely allow_passive_connect. This option al‐
4405 lows the BIF to wait the normal network connection time-out for
4406 the monitored node to connect itself, even if it cannot be ac‐
4407 tively connected from this node (that is, it is blocked). The
4408 state where this can be useful can only be achieved by using the
4409 Kernel option dist_auto_connect once. If that option is not
4410 used, option allow_passive_connect has no effect.
4411 Note:
4413 Option allow_passive_connect is used internally and is seldom
4414 needed in applications where the network topology and the Kernel
4415 options in effect are known in advance.
4416 Failure: badarg if the local node is not alive or the option
4419 list is malformed.
4420 erlang:monotonic_time() -> integer()
4422 Returns the current Erlang monotonic time in native time unit.
4424 This is a monotonically increasing time since some unspecified
4425 point in time.
4426 Note:
4428 This is a monotonically increasing time, but not a strictly
4429 monotonically increasing time. That is, consecutive calls to er‐
4430 lang:monotonic_time/0 can produce the same result.
4431 Different runtime system instances will use different unspeci‐
4433 fied points in time as base for their Erlang monotonic clocks.
4434 That is, it is pointless comparing monotonic times from differ‐
4435 ent runtime system instances. Different runtime system instances
4436 can also place this unspecified point in time different relative
4437 runtime system start. It can be placed in the future (time at
4438 start is a negative value), the past (time at start is a posi‐
4439 tive value), or the runtime system start (time at start is
4440 zero). The monotonic time at runtime system start can be re‐
4441 trieved by calling erlang:system_info(start_time).
4442 erlang:monotonic_time(Unit) -> integer()
4445 Types:
4447 Unit = time_unit()
4449 Returns the current Erlang monotonic time converted into the
4451 Unit passed as argument.
4452 Same as calling erlang:convert_time_unit(erlang:mono‐
4454 tonic_time(), native, Unit), however optimized for commonly used
4455 Units.
4456 erlang:nif_error(Reason) -> no_return()
4458 Types:
4460 Reason = term()
4462 Works exactly like error/1, but Dialyzer thinks that this BIF
4464 will return an arbitrary term. When used in a stub function for
4465 a NIF to generate an exception when the NIF library is not
4466 loaded, Dialyzer does not generate false warnings.
4467 erlang:nif_error(Reason, Args) -> no_return()
4469 Types:
4471 Reason = term()
4473 Args = [term()]
4474 Works exactly like error/2, but Dialyzer thinks that this BIF
4476 will return an arbitrary term. When used in a stub function for
4477 a NIF to generate an exception when the NIF library is not
4478 loaded, Dialyzer does not generate false warnings.
4479 node() -> Node
4481 Types:
4483 Node = node()
4485 Returns the name of the local node. If the node is not alive,
4487 nonode@nohost is returned instead.
4488 Allowed in guard tests.
4490 node(Arg) -> Node
4492 Types:
4494 Arg = pid() | port() | reference()
4496 Node = node()
4497 Returns the node where Arg originates. Arg can be a process
4499 identifier, a reference, or a port. If Arg originates from the
4500 local node and the local node is not alive, nonode@nohost is re‐
4501 turned.
4502 Allowed in guard tests.
4504 nodes() -> Nodes
4506 Types:
4508 Nodes = [node()]
4510 Returns a list of all nodes connected to this node through nor‐
4512 mal connections (that is, hidden nodes are not listed). Same as
4513 nodes(visible).
4514 nodes(Arg) -> Nodes
4516 Types:
4518 Arg = NodeType | [NodeType]
4520 NodeType = visible | hidden | connected | this | known
4521 Nodes = [node()]
4522 Returns a list of nodes according to the argument specified. The
4524 returned result, when the argument is a list, is the list of
4525 nodes satisfying the disjunction(s) of the list elements.
4526 NodeTypes:
4528 visible:
4530 Nodes connected to this node through normal connections.
4531 hidden:
4533 Nodes connected to this node through hidden connections.
4534 connected:
4536 All nodes connected to this node.
4537 this:
4539 This node.
4540 known:
4542 Nodes that are known to this node. That is, connected nodes
4543 and nodes referred to by process identifiers, port identi‐
4544 fiers, and references located on this node. The set of known
4545 nodes is garbage collected. Notice that this garbage collec‐
4546 tion can be delayed. For more information, see erlang:sys‐
4547 tem_info(delayed_node_table_gc).
4548 Some equalities: [node()] = nodes(this), nodes(connected) =
4550 nodes([visible, hidden]), and nodes() = nodes(visible).
4551 nodes(Arg, InfoOpts) -> [NodeInfo]
4553 Types:
4555 NodeType = visible | hidden | connected | this | known
4557 Arg = NodeType | [NodeType]
4558 InfoOpts =
4559 #{connection_id => boolean(), node_type => boolean()}
4560 NodeTypeInfo = visible | hidden | this | known
4561 ConnectionId = undefined | integer()
4562 Info =
4563 #{connection_id => ConnectionId, node_type => NodeType‐
4564 Info}
4565 NodeInfo = {node(), Info}
4566 Returns a list of NodeInfo tuples. The first element is the node
4568 name. Nodes to be included in the list are determined by the
4569 first argument Arg in the same way as for nodes(Arg). The second
4570 element of NodeInfo tuples is a map containing further informa‐
4571 tion about the node identified by the first element. The infor‐
4572 mation present in this map is determined by the InfoOpts map
4573 passed as the second argument. Currently the following associa‐
4574 tions are allowed in the InfoOpts map:
4575 connection_id => boolean():
4577 If the value of the association equals true, the Info map in
4578 the returned result will contain the key connection_id asso‐
4579 ciated with the value ConnectionId. If ConnectionId equals
4580 undefined, the node is not connected to the node which the
4581 caller is executing on, or is the node which the caller is
4582 executing on. If ConnectionId is an integer, the node is
4583 currently connected to the node which the caller is execut‐
4584 ing on.
4585 The integer connection identifier value together with a node
4587 name identifies a specific connection instance to the node
4588 with that node name. The connection identifier value is node
4589 local. That is, on the other node the connection identifier
4590 will not be the same value. If a connection is taken down
4591 and then taken up again, the connection identifier value
4592 will change for the connection to that node. The amount of
4593 values for connection identifiers are limited, so it is pos‐
4594 sible to see the same value for different instances, but
4595 quite unlikely. It is undefined how the value change between
4596 two consecutive connection instances.
4597 node_type => boolean():
4599 If the value of the association equals true, the Info map in
4600 the returned result will contain the key node_type associ‐
4601 ated with the value NodeTypeInfo. Currently the following
4602 node types exist:
4603 visible:
4605 The node is connected to the node of the calling process
4606 through an ordinary visible connection. That is, the node
4607 name would appear in the result returned by nodes/0.
4608 hidden:
4610 The node is connected to the node of the calling process
4611 through a hidden connection. That is, the node name would
4612 not appear in the result returned by nodes/0.
4613 this:
4615 This is the node of the calling process.
4616 known:
4618 The node is not connected but known to the node of the
4619 calling process.
4620 Example:
4622 (a@localhost)1> nodes([this, connected], #{connection_id=>true, node_type=>true}).
4624 [{c@localhost,#{connection_id => 13892108,node_type => hidden}},
4625 {b@localhost,#{connection_id => 3067553,node_type => visible}},
4626 {a@localhost,#{connection_id => undefined,node_type => this}}]
4627 (a@localhost)2>
4628 now() -> Timestamp
4631 Types:
4633 Timestamp = timestamp()
4635 timestamp() =
4636 {MegaSecs :: integer() >= 0,
4637 Secs :: integer() >= 0,
4638 MicroSecs :: integer() >= 0}
4639 Warning:
4641 This function is deprecated. Do not use it.
4642 For more information, see section Time and Time Correction in
4644 the User's Guide. Specifically, section Dos and Dont's de‐
4645 scribes what to use instead of erlang:now/0.
4646 Returns the tuple {MegaSecs, Secs, MicroSecs}, which is the
4649 elapsed time since 00:00 GMT, January 1, 1970 (zero hour), if
4650 provided by the underlying OS. Otherwise some other point in
4651 time is chosen. It is also guaranteed that the following calls
4652 to this BIF return continuously increasing values. Hence, the
4653 return value from erlang:now/0 can be used to generate unique
4654 time stamps. If it is called in a tight loop on a fast machine,
4655 the time of the node can become skewed.
4656 Can only be used to check the local time of day if the time-zone
4658 information of the underlying OS is properly configured.
4659 open_port(PortName, PortSettings) -> port()
4661 Types:
4663 PortName =
4665 {spawn, Command :: string() | binary()} |
4666 {spawn_driver, Command :: string() | binary()} |
4667 {spawn_executable, FileName :: file:name_all()} |
4668 {fd, In :: integer() >= 0, Out :: integer() >= 0}
4669 PortSettings = [Opt]
4670 Opt =
4671 {packet, N :: 1 | 2 | 4} |
4672 stream |
4673 {line, L :: integer() >= 0} |
4674 {cd, Dir :: string() | binary()} |
4675 {env,
4676 Env ::
4677 [{Name :: os:env_var_name(),
4678 Val :: os:env_var_value() | false}]} |
4679 {args, [string() | binary()]} |
4680 {arg0, string() | binary()} |
4681 exit_status | use_stdio | nouse_stdio | stderr_to_stdout
4682 |
4683 in | out | binary | eof |
4684 {parallelism, Boolean :: boolean()} |
4685 hide |
4686 {busy_limits_port,
4687 {integer() >= 0, integer() >= 0} | disabled} |
4688 {busy_limits_msgq,
4689 {integer() >= 0, integer() >= 0} | disabled}
4690 Returns a port identifier as the result of opening a new Erlang
4692 port. A port can be seen as an external Erlang process.
4693 The name of the executable as well as the arguments specified in
4695 cd, env, args, and arg0 are subject to Unicode filename transla‐
4696 tion if the system is running in Unicode filename mode. To avoid
4697 translation or to force, for example UTF-8, supply the exe‐
4698 cutable and/or arguments as a binary in the correct encoding.
4699 For details, see the module file(3), the function file:na‐
4700 tive_name_encoding/0 in Kernel, and the Using Unicode in Erlang
4701 User's Guide.
4702 Note:
4704 The characters in the name (if specified as a list) can only be
4705 > 255 if the Erlang virtual machine is started in Unicode file‐
4706 name translation mode. Otherwise the name of the executable is
4707 limited to the ISO Latin-1 character set.
4708 PortNames:
4711 {spawn, Command}:
4713 Starts an external program. Command is the name of the ex‐
4714 ternal program to be run. Command runs outside the Erlang
4715 work space unless an Erlang driver with the name Command is
4716 found. If found, that driver is started. A driver runs in
4717 the Erlang work space, which means that it is linked with
4718 the Erlang runtime system.
4719 For external programs, PATH is searched (or an equivalent
4721 method is used to find programs, depending on the OS). This
4722 is done by invoking the shell on certain platforms. The
4723 first space-separated token of the command is considered as
4724 the name of the executable (or driver). This (among other
4725 things) makes this option unsuitable for running programs
4726 with spaces in filenames or directory names. If spaces in
4727 executable filenames are desired, use {spawn_executable,
4728 Command} instead.
4729 {spawn_driver, Command}:
4731 Works like {spawn, Command}, but demands the first (space-
4732 separated) token of the command to be the name of a loaded
4733 driver. If no driver with that name is loaded, a badarg er‐
4734 ror is raised.
4735 {spawn_executable, FileName}:
4737 Works like {spawn, FileName}, but only runs external exe‐
4738 cutables. FileName in its whole is used as the name of the
4739 executable, including any spaces. If arguments are to be
4740 passed, the PortSettings args and arg0 can be used.
4741 The shell is usually not invoked to start the program, it is
4743 executed directly. PATH (or equivalent) is not searched. To
4744 find a program in PATH to execute, use os:find_executable/1.
4745 Only if a shell script or .bat file is executed, the appro‐
4747 priate command interpreter is invoked implicitly, but there
4748 is still no command-argument expansion or implicit PATH
4749 search.
4750 If FileName cannot be run, an error exception is raised,
4752 with the POSIX error code as the reason. The error reason
4753 can differ between OSs. Typically the error enoent is raised
4754 when an attempt is made to run a program that is not found
4755 and eacces is raised when the specified file is not exe‐
4756 cutable.
4757 {fd, In, Out}:
4759 Allows an Erlang process to access any currently opened file
4760 descriptors used by Erlang. The file descriptor In can be
4761 used for standard input, and the file descriptor Out for
4762 standard output. It is only used for various servers in the
4763 Erlang OS (shell and user). Hence, its use is limited.
4764 PortSettings is a list of settings for the port. The valid set‐
4766 tings are as follows:
4767 {packet, N}:
4769 Messages are preceded by their length, sent in N bytes, with
4770 the most significant byte first. The valid values for N are
4771 1, 2, and 4.
4772 stream:
4774 Output messages are sent without packet lengths. A user-de‐
4775 fined protocol must be used between the Erlang process and
4776 the external object.
4777 {line, L}:
4779 Messages are delivered on a per line basis. Each line (de‐
4780 limited by the OS-dependent newline sequence) is delivered
4781 in a single message. The message data format is {Flag,
4782 Line}, where Flag is eol or noeol, and Line is the data de‐
4783 livered (without the newline sequence).
4784 L specifies the maximum line length in bytes. Lines longer
4786 than this are delivered in more than one message, with Flag
4787 set to noeol for all but the last message. If end of file is
4788 encountered anywhere else than immediately following a new‐
4789 line sequence, the last line is also delivered with Flag set
4790 to noeol. Otherwise lines are delivered with Flag set to
4791 eol.
4792 The {packet, N} and {line, L} settings are mutually exclu‐
4794 sive.
4795 {cd, Dir}:
4797 Only valid for {spawn, Command} and {spawn_executable, File‐
4798 Name}. The external program starts using Dir as its working
4799 directory. Dir must be a string.
4800 {env, Env}:
4802 Types:
4803 Name = os:env_var_name()
4804 Val = os:env_var_value() | false
4805 Env = [{Name, Val}]
4806 Only valid for {spawn, Command}, and {spawn_executable,
4808 FileName}. The environment of the started process is ex‐
4809 tended using the environment specifications in Env.
4810 Env is to be a list of tuples {Name, Val}, where Name is the
4812 name of an environment variable, and Val is the value it is
4813 to have in the spawned port process. Both Name and Val must
4814 be strings. The one exception is Val being the atom false
4815 (in analogy with os:getenv/1, which removes the environment
4816 variable.
4817 For information about encoding requirements, see documenta‐
4819 tion of the types for Name and Val.
4820 {args, [ string() | binary() ]}:
4822 Only valid for {spawn_executable, FileName} and specifies
4823 arguments to the executable. Each argument is specified as a
4824 separate string and (on Unix) eventually ends up as one ele‐
4825 ment each in the argument vector. On other platforms, a sim‐
4826 ilar behavior is mimicked.
4827 The arguments are not expanded by the shell before they are
4829 supplied to the executable. Most notably this means that
4830 file wildcard expansion does not occur. To expand wildcards
4831 for the arguments, use filelib:wildcard/1. Notice that even
4832 if the program is a Unix shell script, meaning that the
4833 shell ultimately is invoked, wildcard expansion does not oc‐
4834 cur, and the script is provided with the untouched argu‐
4835 ments. On Windows, wildcard expansion is always up to the
4836 program itself, therefore this is not an issue.
4837 The executable name (also known as argv[0]) is not to be
4839 specified in this list. The proper executable name is auto‐
4840 matically used as argv[0], where applicable.
4841 If you explicitly want to set the program name in the argu‐
4843 ment vector, option arg0 can be used.
4844 {arg0, string() | binary()}:
4846 Only valid for {spawn_executable, FileName} and explicitly
4847 specifies the program name argument when running an exe‐
4848 cutable. This can in some circumstances, on some OSs, be de‐
4849 sirable. How the program responds to this is highly system-
4850 dependent and no specific effect is guaranteed.
4851 exit_status:
4853 Only valid for {spawn, Command}, where Command refers to an
4854 external program, and for {spawn_executable, FileName}.
4855 When the external process connected to the port exits, a
4857 message of the form {Port,{exit_status,Status}} is sent to
4858 the connected process, where Status is the exit status of
4859 the external process. If the program aborts on Unix, the
4860 same convention is used as the shells do (that is, 128+sig‐
4861 nal).
4862 If option eof is specified also, the messages eof and
4864 exit_status appear in an unspecified order.
4865 If the port program closes its stdout without exiting, op‐
4867 tion exit_status does not work.
4868 use_stdio:
4870 Only valid for {spawn, Command} and {spawn_executable, File‐
4871 Name}. It allows the standard input and output (file de‐
4872 scriptors 0 and 1) of the spawned (Unix) process for commu‐
4873 nication with Erlang.
4874 nouse_stdio:
4876 The opposite of use_stdio. It uses file descriptors 3 and 4
4877 for communication with Erlang.
4878 stderr_to_stdout:
4880 Affects ports to external programs. The executed program
4881 gets its standard error file redirected to its standard out‐
4882 put file. stderr_to_stdout and nouse_stdio are mutually ex‐
4883 clusive.
4884 overlapped_io:
4886 Affects ports to external programs on Windows only. The
4887 standard input and standard output handles of the port pro‐
4888 gram are, if this option is supplied, opened with flag
4889 FILE_FLAG_OVERLAPPED, so that the port program can (and
4890 must) do overlapped I/O on its standard handles. This is not
4891 normally the case for simple port programs, but an option of
4892 value for the experienced Windows programmer. On all other
4893 platforms, this option is silently discarded.
4894 in:
4896 The port can only be used for input.
4897 out:
4899 The port can only be used for output.
4900 binary:
4902 All I/O from the port is binary data objects as opposed to
4903 lists of bytes.
4904 eof:
4906 The port is not closed at the end of the file and does not
4907 produce an exit signal. Instead, it remains open and a
4908 {Port, eof} message is sent to the process holding the port.
4909 hide:
4911 When running on Windows, suppresses creation of a new con‐
4912 sole window when spawning the port program. (This option has
4913 no effect on other platforms.)
4914 {parallelism, Boolean}:
4916 Sets scheduler hint for port parallelism. If set to true,
4919 the virtual machine schedules port tasks; when doing so, it
4920 improves parallelism in the system. If set to false, the
4921 virtual machine tries to perform port tasks immediately, im‐
4922 proving latency at the expense of parallelism. The default
4923 can be set at system startup by passing command-line argu‐
4924 ment +spp to erl(1).
4925 {busy_limits_port, {Low, High} | disabled}:
4927 Sets limits that will be used for controlling the busy state
4928 of the port.
4929 When the ports internal output queue size becomes larger
4931 than or equal to High bytes, it enters the busy state. When
4932 it becomes less than Low bytes it leaves the busy state.
4933 When the port is in the busy state, processes sending com‐
4934 mands to it will be suspended until the port leaves the busy
4935 state. Commands are in this context either Port ! {Owner,
4936 {command, Data}} or port_command/[2,3].
4937 The Low limit is automatically adjusted to the same as High
4939 if it is set larger then High. Valid range of values for Low
4940 and High is [1, (1 bsl (8*erlang:system_info(wordsize)))-2].
4941 If the atom disabled is passed, the port will never enter
4942 the busy state.
4943 The defaults are Low = 4096 and High = 8192.
4945 Note that this option is only valid when spawning an exe‐
4947 cutable (port program) by opening the spawn driver and when
4948 opening the fd driver. This option will cause a failure with
4949 a badarg exception when opening other drivers.
4950 {busy_limits_msgq, {Low, High} | disabled}:
4952 Sets limits that will be used for controlling the busy state
4953 of the port message queue.
4954 When the ports message queue size becomes larger than or
4956 equal to High bytes it enters the busy state. When it be‐
4957 comes less than Low bytes it leaves the busy state. When the
4958 port message queue is in the busy state, processes sending
4959 commands to it will be suspended until the port message
4960 queue leaves the busy state. Commands are in this context
4961 either Port ! {Owner, {command, Data}} or port_com‐
4962 mand/[2,3].
4963 The Low limit is automatically adjusted to the same as High
4965 if it is set larger then High. Valid range of values for Low
4966 and High is [1, (1 bsl (8*erlang:system_info(wordsize)))-2].
4967 If the atom disabled is passed, the port message queue will
4968 never enter the busy state.
4969 Note that if the driver statically has disabled the use of
4971 this feature, a failure with a badarg exception will be
4972 raised unless this option also is set to disable or not
4973 passed at all.
4974 The defaults are Low = 4096 and High = 8192 unless the
4976 driver itself does modifications of these values.
4977 Note that the driver might fail if it also adjust these lim‐
4979 its by itself and you have disabled this feature.
4980 The spawn driver (used when spawning an executable) and the
4982 fd driver do not disable this feature and do not adjust
4983 these limits by themselves.
4984 For more information see the documentation
4986 erl_drv_busy_msgq_limits().
4987 Default is stream for all port types and use_stdio for spawned
4989 ports.
4990 Failure: if the port cannot be opened, the exit reason is
4992 badarg, system_limit, or the POSIX error code that most closely
4993 describes the error, or einval if no POSIX code is appropriate:
4994 badarg:
4996 Bad input arguments to open_port.
4997 system_limit:
4999 All available ports in the Erlang emulator are in use.
5000 enomem:
5002 Not enough memory to create the port.
5003 eagain:
5005 No more available OS processes.
5006 enametoolong:
5008 Too long external command.
5009 emfile:
5011 No more available file descriptors (for the OS process that
5012 the Erlang emulator runs in).
5013 enfile:
5015 Full file table (for the entire OS).
5016 eacces:
5018 Command specified in {spawn_executable, Command} does not
5019 point out an executable file.
5020 enoent:
5022 FileName specified in {spawn_executable, FileName} does not
5023 point out an existing file.
5024 During use of a port opened using {spawn, Name}, {spawn_driver,
5026 Name}, or {spawn_executable, Name}, errors arising when sending
5027 messages to it are reported to the owning process using signals
5028 of the form {'EXIT', Port, PosixCode}. For the possible values
5029 of PosixCode, see file(3).
5030 The maximum number of ports that can be open at the same time
5032 can be configured by passing command-line flag +Q to erl(1).
5033 erlang:phash(Term, Range) -> Hash
5035 Types:
5037 Term = term()
5039 Range = Hash = integer() >= 1
5040 Range = 1..2^32, Hash = 1..Range
5041 Warning:
5043 This function is deprecated as erlang:phash2/2 should be used
5044 for new code. Note that erlang:phash(X,N) is not necessary equal
5045 to erlang:phash2(X,N)
5046 Portable hash function that gives the same hash for the same Er‐
5049 lang term regardless of machine architecture and ERTS version
5050 (the BIF was introduced in ERTS 4.9.1.1). The function returns a
5051 hash value for Term within the range 1..Range. The maximum value
5052 for Range is 2^32.
5053 erlang:phash2(Term) -> Hash
5055 erlang:phash2(Term, Range) -> Hash
5057 Types:
5059 Term = term()
5061 Range = integer() >= 1
5062 1..2^32
5063 Hash = integer() >= 0
5064 0..Range-1
5065 Portable hash function that gives the same hash for the same Er‐
5067 lang term regardless of machine architecture and ERTS version
5068 (the BIF was introduced in ERTS 5.2). The function returns a
5069 hash value for Term within the range 0..Range-1. The maximum
5070 value for Range is 2^32. When without argument Range, a value in
5071 the range 0..2^27-1 is returned.
5072 This BIF is always to be used for hashing terms. It distributes
5074 small integers better than phash/2, and it is faster for bignums
5075 and binaries.
5076 Notice that the range 0..Range-1 is different from the range of
5078 phash/2, which is 1..Range.
5079 pid_to_list(Pid) -> string()
5081 Types:
5083 Pid = pid()
5085 Returns a string corresponding to the text representation of
5087 Pid. Example:
5088 > erlang:pid_to_list(self()).
5090 "<0.85.0>"
5091 Note:
5093 The creation for the node is not included in the list represen‐
5094 tation of Pid. This means that processes in different incarna‐
5095 tions of a node with a specific name can get the same list rep‐
5096 resentation.
5097 erlang:port_call(Port, Operation, Data) -> term()
5100 Types:
5102 Port = port() | atom()
5104 Operation = integer()
5105 Data = term()
5106 Performs a synchronous call to a port. The meaning of Operation
5108 and Data depends on the port, that is, on the port driver. Not
5109 all port drivers support this feature.
5110 Port is a port identifier, referring to a driver.
5112 Operation is an integer, which is passed on to the driver.
5114 Data is any Erlang term. This data is converted to binary term
5116 format and sent to the port.
5117 Returns a term from the driver. The meaning of the returned data
5119 also depends on the port driver.
5120 Failures:
5122 badarg:
5124 If Port is not an identifier of an open port, or the regis‐
5125 tered name of an open port. If the calling process was pre‐
5126 viously linked to the closed port, identified by Port, the
5127 exit signal from the port is guaranteed to be delivered be‐
5128 fore this badarg exception occurs.
5129 badarg:
5131 If Operation does not fit in a 32-bit integer.
5132 badarg:
5134 If the port driver does not support synchronous control op‐
5135 erations.
5136 badarg:
5138 If the port driver so decides for any reason (probably some‐
5139 thing wrong with Operation or Data).
5140 Warning:
5142 Do not call port_call with an unknown Port identifier and ex‐
5143 pect badarg exception. Any undefined behavior is possible (in‐
5144 cluding node crash) depending on how the port driver inter‐
5145 prets the supplied arguments.
5146 port_close(Port) -> true
5149 Types:
5151 Port = port() | atom()
5153 Closes an open port. Roughly the same as Port ! {self(), close}
5155 except for the error behavior (see below), being synchronous,
5156 and that the port does not reply with {Port, closed}. Any
5157 process can close a port with port_close/1, not only the port
5158 owner (the connected process). If the calling process is linked
5159 to the port identified by Port, the exit signal from the port is
5160 guaranteed to be delivered before port_close/1 returns.
5161 For comparison: Port ! {self(), close} only fails with badarg if
5163 Port does not refer to a port or a process. If Port is a closed
5164 port, nothing happens. If Port is an open port and the calling
5165 process is the port owner, the port replies with {Port, closed}
5166 when all buffers have been flushed and the port really closes.
5167 If the calling process is not the port owner, the port owner
5168 fails with badsig.
5169 Notice that any process can close a port using Port ! {Por‐
5171 tOwner, close} as if it itself was the port owner, but the reply
5172 always goes to the port owner.
5173 As from Erlang/OTP R16, Port ! {PortOwner, close} is truly asyn‐
5175 chronous. Notice that this operation has always been documented
5176 as an asynchronous operation, while the underlying implementa‐
5177 tion has been synchronous. port_close/1 is however still fully
5178 synchronous because of its error behavior.
5179 Failure: badarg if Port is not an identifier of an open port, or
5181 the registered name of an open port. If the calling process was
5182 previously linked to the closed port, identified by Port, the
5183 exit signal from the port is guaranteed to be delivered before
5184 this badarg exception occurs.
5185 port_command(Port, Data) -> true
5187 Types:
5189 Port = port() | atom()
5191 Data = iodata()
5192 Sends data to a port. Same as Port ! {PortOwner, {command,
5194 Data}} except for the error behavior and being synchronous (see
5195 below). Any process can send data to a port with port_command/2,
5196 not only the port owner (the connected process).
5197 For comparison: Port ! {PortOwner, {command, Data}} only fails
5199 with badarg if Port does not refer to a port or a process. If
5200 Port is a closed port, the data message disappears without a
5201 sound. If Port is open and the calling process is not the port
5202 owner, the port owner fails with badsig. The port owner fails
5203 with badsig also if Data is an invalid I/O list.
5204 Notice that any process can send to a port using Port ! {Por‐
5206 tOwner, {command, Data}} as if it itself was the port owner.
5207 If the port is busy, the calling process is suspended until the
5209 port is not busy any more.
5210 As from Erlang/OTP R16, Port ! {PortOwner, {command, Data}} is
5212 truly asynchronous. Notice that this operation has always been
5213 documented as an asynchronous operation, while the underlying
5214 implementation has been synchronous. port_command/2 is however
5215 still fully synchronous because of its error behavior.
5216 Failures:
5218 badarg:
5220 If Port is not an identifier of an open port, or the regis‐
5221 tered name of an open port. If the calling process was pre‐
5222 viously linked to the closed port, identified by Port, the
5223 exit signal from the port is guaranteed to be delivered be‐
5224 fore this badarg exception occurs.
5225 badarg:
5227 If Data is an invalid I/O list.
5228 Warning:
5230 Do not send data to an unknown port. Any undefined behavior is
5231 possible (including node crash) depending on how the port driver
5232 interprets the data.
5233 port_command(Port, Data, OptionList) -> boolean()
5236 Types:
5238 Port = port() | atom()
5240 Data = iodata()
5241 Option = force | nosuspend
5242 OptionList = [Option]
5243 Sends data to a port. port_command(Port, Data, []) equals
5245 port_command(Port, Data).
5246 If the port command is aborted, false is returned, otherwise
5248 true.
5249 If the port is busy, the calling process is suspended until the
5251 port is not busy anymore.
5252 Options:
5254 force:
5256 The calling process is not suspended if the port is busy,
5257 instead the port command is forced through. The call fails
5258 with a notsup exception if the driver of the port does not
5259 support this. For more information, see driver flag
5260 ERL_DRV_FLAG_SOFT_BUSY.
5261 nosuspend:
5263 The calling process is not suspended if the port is busy,
5264 instead the port command is aborted and false is returned.
5265 Note:
5267 More options can be added in a future release.
5268 Failures:
5271 badarg:
5273 If Port is not an identifier of an open port, or the regis‐
5274 tered name of an open port. If the calling process was pre‐
5275 viously linked to the closed port, identified by Port, the
5276 exit signal from the port is guaranteed to be delivered be‐
5277 fore this badarg exception occurs.
5278 badarg:
5280 If Data is an invalid I/O list.
5281 badarg:
5283 If OptionList is an invalid option list.
5284 notsup:
5286 If option force has been passed, but the driver of the port
5287 does not allow forcing through a busy port.
5288 Warning:
5290 Do not send data to an unknown port. Any undefined behavior is
5291 possible (including node crash) depending on how the port driver
5292 interprets the data.
5293 port_connect(Port, Pid) -> true
5296 Types:
5298 Port = port() | atom()
5300 Pid = pid()
5301 Sets the port owner (the connected port) to Pid. Roughly the
5303 same as Port ! {Owner, {connect, Pid}} except for the following:
5304 * The error behavior differs, see below.
5306 * The port does not reply with {Port,connected}.
5308 * port_connect/1 is synchronous, see below.
5310 * The new port owner gets linked to the port.
5312 The old port owner stays linked to the port and must call un‐
5314 link(Port) if this is not desired. Any process can set the port
5315 owner to be any process with port_connect/2.
5316 For comparison: Port ! {self(), {connect, Pid}} only fails with
5318 badarg if Port does not refer to a port or a process. If Port is
5319 a closed port, nothing happens. If Port is an open port and the
5320 calling process is the port owner, the port replies with {Port,
5321 connected} to the old port owner. Notice that the old port owner
5322 is still linked to the port, while the new is not. If Port is an
5323 open port and the calling process is not the port owner, the
5324 port owner fails with badsig. The port owner fails with badsig
5325 also if Pid is not an existing local process identifier.
5326 Notice that any process can set the port owner using Port !
5328 {PortOwner, {connect, Pid}} as if it itself was the port owner,
5329 but the reply always goes to the port owner.
5330 As from Erlang/OTP R16, Port ! {PortOwner, {connect, Pid}} is
5332 truly asynchronous. Notice that this operation has always been
5333 documented as an asynchronous operation, while the underlying
5334 implementation has been synchronous. port_connect/2 is however
5335 still fully synchronous because of its error behavior.
5336 Failures:
5338 badarg:
5340 If Port is not an identifier of an open port, or the regis‐
5341 tered name of an open port. If the calling process was pre‐
5342 viously linked to the closed port, identified by Port, the
5343 exit signal from the port is guaranteed to be delivered be‐
5344 fore this badarg exception occurs.
5345 badarg:
5347 If the process identified by Pid is not an existing local
5348 process.
5349 port_control(Port, Operation, Data) -> iodata() | binary()
5351 Types:
5353 Port = port() | atom()
5355 Operation = integer()
5356 Data = iodata()
5357 Performs a synchronous control operation on a port. The meaning
5359 of Operation and Data depends on the port, that is, on the port
5360 driver. Not all port drivers support this control feature.
5361 Returns a list of integers in the range 0..255, or a binary, de‐
5363 pending on the port driver. The meaning of the returned data
5364 also depends on the port driver.
5365 Failures:
5367 badarg:
5369 If Port is not an open port or the registered name of an
5370 open port.
5371 badarg:
5373 If Operation cannot fit in a 32-bit integer.
5374 badarg:
5376 If the port driver does not support synchronous control op‐
5377 erations.
5378 badarg:
5380 If the port driver so decides for any reason (probably
5381 something wrong with Operation or Data).
5382 Warning:
5384 Do not call port_control/3 with an unknown Port identifier and
5385 expect badarg exception. Any undefined behavior is possible
5386 (including node crash) depending on how the port driver inter‐
5387 prets the supplied arguments.
5388 erlang:port_info(Port) -> Result
5391 Types:
5393 Port = port() | atom()
5395 ResultItem =
5396 {registered_name, RegisteredName :: atom()} |
5397 {id, Index :: integer() >= 0} |
5398 {connected, Pid :: pid()} |
5399 {links, Pids :: [pid()]} |
5400 {name, String :: string()} |
5401 {input, Bytes :: integer() >= 0} |
5402 {output, Bytes :: integer() >= 0} |
5403 {os_pid, OsPid :: integer() >= 0 | undefined}
5404 Result = [ResultItem] | undefined
5405 Returns a list containing tuples with information about Port, or
5407 undefined if the port is not open. The order of the tuples is
5408 undefined, and all the tuples are not mandatory. If the port is
5409 closed and the calling process was previously linked to the
5410 port, the exit signal from the port is guaranteed to be deliv‐
5411 ered before port_info/1 returns undefined.
5412 The result contains information about the following Items:
5414 * registered_name (if the port has a registered name)
5416 * id
5418 * connected
5420 * links
5422 * name
5424 * input
5426 * output
5428 For more information about the different Items, see port_info/2.
5430 Failure: badarg if Port is not a local port identifier, or an
5432 atom.
5433 erlang:port_info(Port, Item :: connected) ->
5435 {connected, Pid} | undefined
5436 Types:
5438 Port = port() | atom()
5440 Pid = pid()
5441 Pid is the process identifier of the process connected to the
5443 port.
5444 If the port identified by Port is not open, undefined is re‐
5446 turned. If the port is closed and the calling process was previ‐
5447 ously linked to the port, the exit signal from the port is guar‐
5448 anteed to be delivered before port_info/2 returns undefined.
5449 Failure: badarg if Port is not a local port identifier, or an
5451 atom.
5452 erlang:port_info(Port, Item :: id) -> {id, Index} | undefined
5454 Types:
5456 Port = port() | atom()
5458 Index = integer() >= 0
5459 Index is the internal index of the port. This index can be used
5461 to separate ports.
5462 If the port identified by Port is not open, undefined is re‐
5464 turned. If the port is closed and the calling process was previ‐
5465 ously linked to the port, the exit signal from the port is guar‐
5466 anteed to be delivered before port_info/2 returns undefined.
5467 Failure: badarg if Port is not a local port identifier, or an
5469 atom.
5470 erlang:port_info(Port, Item :: input) ->
5472 {input, Bytes} | undefined
5473 Types:
5475 Port = port() | atom()
5477 Bytes = integer() >= 0
5478 Bytes is the total number of bytes read from the port.
5480 If the port identified by Port is not open, undefined is re‐
5482 turned. If the port is closed and the calling process was previ‐
5483 ously linked to the port, the exit signal from the port is guar‐
5484 anteed to be delivered before port_info/2 returns undefined.
5485 Failure: badarg if Port is not a local port identifier, or an
5487 atom.
5488 erlang:port_info(Port, Item :: links) -> {links, Pids} | undefined
5490 Types:
5492 Port = port() | atom()
5494 Pids = [pid()]
5495 Pids is a list of the process identifiers of the processes that
5497 the port is linked to.
5498 If the port identified by Port is not open, undefined is re‐
5500 turned. If the port is closed and the calling process was previ‐
5501 ously linked to the port, the exit signal from the port is guar‐
5502 anteed to be delivered before port_info/2 returns undefined.
5503 Failure: badarg if Port is not a local port identifier, or an
5505 atom.
5506 erlang:port_info(Port, Item :: locking) ->
5508 {locking, Locking} | undefined
5509 Types:
5511 Port = port() | atom()
5513 Locking = false | port_level | driver_level
5514 Locking is one of the following:
5516 * port_level (port-specific locking)
5518 * driver_level (driver-specific locking)
5520 Notice that these results are highly implementation-specific and
5522 can change in a future release.
5523 If the port identified by Port is not open, undefined is re‐
5525 turned. If the port is closed and the calling process was previ‐
5526 ously linked to the port, the exit signal from the port is guar‐
5527 anteed to be delivered before port_info/2 returns undefined.
5528 Failure: badarg if Port is not a local port identifier, or an
5530 atom.
5531 erlang:port_info(Port, Item :: memory) ->
5533 {memory, Bytes} | undefined
5534 Types:
5536 Port = port() | atom()
5538 Bytes = integer() >= 0
5539 Bytes is the total number of bytes allocated for this port by
5541 the runtime system. The port itself can have allocated memory
5542 that is not included in Bytes.
5543 If the port identified by Port is not open, undefined is re‐
5545 turned. If the port is closed and the calling process was previ‐
5546 ously linked to the port, the exit signal from the port is guar‐
5547 anteed to be delivered before port_info/2 returns undefined.
5548 Failure: badarg if Port is not a local port identifier, or an
5550 atom.
5551 erlang:port_info(Port, Item :: monitors) ->
5553 {monitors, Monitors} | undefined
5554 Types:
5556 Port = port() | atom()
5558 Monitors = [{process, pid()}]
5559 Monitors represent processes monitored by this port.
5561 If the port identified by Port is not open, undefined is re‐
5563 turned. If the port is closed and the calling process was previ‐
5564 ously linked to the port, the exit signal from the port is guar‐
5565 anteed to be delivered before port_info/2 returns undefined.
5566 Failure: badarg if Port is not a local port identifier, or an
5568 atom.
5569 erlang:port_info(Port, Item :: monitored_by) ->
5571 {monitored_by, MonitoredBy} | undefined
5572 Types:
5574 Port = port() | atom()
5576 MonitoredBy = [pid()]
5577 Returns list of pids that are monitoring given port at the mo‐
5579 ment.
5580 If the port identified by Port is not open, undefined is re‐
5582 turned. If the port is closed and the calling process was previ‐
5583 ously linked to the port, the exit signal from the port is guar‐
5584 anteed to be delivered before port_info/2 returns undefined.
5585 Failure: badarg if Port is not a local port identifier, or an
5587 atom.
5588 erlang:port_info(Port, Item :: name) -> {name, Name} | undefined
5590 Types:
5592 Port = port() | atom()
5594 Name = string()
5595 Name is the command name set by open_port/2.
5597 If the port identified by Port is not open, undefined is re‐
5599 turned. If the port is closed and the calling process was previ‐
5600 ously linked to the port, the exit signal from the port is guar‐
5601 anteed to be delivered before port_info/2 returns undefined.
5602 Failure: badarg if Port is not a local port identifier, or an
5604 atom.
5605 erlang:port_info(Port, Item :: os_pid) ->
5607 {os_pid, OsPid} | undefined
5608 Types:
5610 Port = port() | atom()
5612 OsPid = integer() >= 0 | undefined
5613 OsPid is the process identifier (or equivalent) of an OS process
5615 created with open_port({spawn | spawn_executable, Command}, Op‐
5616 tions). If the port is not the result of spawning an OS process,
5617 the value is undefined.
5618 If the port identified by Port is not open, undefined is re‐
5620 turned. If the port is closed and the calling process was previ‐
5621 ously linked to the port, the exit signal from the port is guar‐
5622 anteed to be delivered before port_info/2 returns undefined.
5623 Failure: badarg if Port is not a local port identifier, or an
5625 atom.
5626 erlang:port_info(Port, Item :: output) ->
5628 {output, Bytes} | undefined
5629 Types:
5631 Port = port() | atom()
5633 Bytes = integer() >= 0
5634 Bytes is the total number of bytes written to the port from Er‐
5636 lang processes using port_command/2, port_command/3, or Port !
5637 {Owner, {command, Data}.
5638 If the port identified by Port is not open, undefined is re‐
5640 turned. If the port is closed and the calling process was previ‐
5641 ously linked to the port, the exit signal from the port is guar‐
5642 anteed to be delivered before port_info/2 returns undefined.
5643 Failure: badarg if Port is not a local port identifier, or an
5645 atom.
5646 erlang:port_info(Port, Item :: parallelism) ->
5648 {parallelism, Boolean} | undefined
5649 Types:
5651 Port = port() | atom()
5653 Boolean = boolean()
5654 Boolean corresponds to the port parallelism hint used by this
5656 port. For more information, see option parallelism of
5657 open_port/2.
5658 erlang:port_info(Port, Item :: queue_size) ->
5660 {queue_size, Bytes} | undefined
5661 Types:
5663 Port = port() | atom()
5665 Bytes = integer() >= 0
5666 Bytes is the total number of bytes queued by the port using the
5668 ERTS driver queue implementation.
5669 If the port identified by Port is not open, undefined is re‐
5671 turned. If the port is closed and the calling process was previ‐
5672 ously linked to the port, the exit signal from the port is guar‐
5673 anteed to be delivered before port_info/2 returns undefined.
5674 Failure: badarg if Port is not a local port identifier, or an
5676 atom.
5677 erlang:port_info(Port, Item :: registered_name) ->
5679 {registered_name, RegisteredName} |
5680 [] | undefined
5681 Types:
5683 Port = port() | atom()
5685 RegisteredName = atom()
5686 RegisteredName is the registered name of the port. If the port
5688 has no registered name, [] is returned.
5689 If the port identified by Port is not open, undefined is re‐
5691 turned. If the port is closed and the calling process was previ‐
5692 ously linked to the port, the exit signal from the port is guar‐
5693 anteed to be delivered before port_info/2 returns undefined.
5694 Failure: badarg if Port is not a local port identifier, or an
5696 atom.
5697 port_to_list(Port) -> string()
5699 Types:
5701 Port = port()
5703 Returns a string corresponding to the text representation of the
5705 port identifier Port.
5706 erlang:ports() -> [port()]
5708 Returns a list of port identifiers corresponding to all the
5710 ports existing on the local node.
5711 Notice that an exiting port exists, but is not open.
5713 pre_loaded() -> [module()]
5715 Returns a list of Erlang modules that are preloaded in the run-
5717 time system. Pre-loaded modules are Erlang modules that are
5718 needed to bootstrap the system to load the first Erlang modules
5719 from either disk or by using erl_boot_server.
5720 erlang:process_display(Pid, Type) -> true
5722 Types:
5724 Pid = pid()
5726 Type = backtrace
5727 Writes information about the local process Pid on standard er‐
5729 ror. The only allowed value for the atom Type is backtrace,
5730 which shows the contents of the call stack, including informa‐
5731 tion about the call chain, with the current function printed
5732 first. The format of the output is not further defined.
5733 process_flag(Flag :: trap_exit, Boolean) -> OldBoolean
5735 Types:
5737 Boolean = OldBoolean = boolean()
5739 When trap_exit is set to true, exit signals arriving to a
5741 process are converted to {'EXIT', From, Reason} messages, which
5742 can be received as ordinary messages. If trap_exit is set to
5743 false, the process exits if it receives an exit signal other
5744 than normal and the exit signal is propagated to its linked pro‐
5745 cesses. Application processes are normally not to trap exits.
5746 Returns the old value of the flag.
5748 See also exit/2.
5750 process_flag(Flag :: error_handler, Module) -> OldModule
5752 Types:
5754 Module = OldModule = atom()
5756 Used by a process to redefine the error handler for undefined
5758 function calls and undefined registered processes. Inexperienced
5759 users are not to use this flag, as code auto-loading depends on
5760 the correct operation of the error handling module.
5761 Returns the old value of the flag.
5763 process_flag(Flag :: fullsweep_after, FullsweepAfter) ->
5765 OldFullsweepAfter
5766 Types:
5768 FullsweepAfter = OldFullsweepAfter = integer() >= 0
5770 Changes the maximum number of generational collections before
5772 forcing a fullsweep for the calling process.
5773 Returns the old value of the flag.
5775 process_flag(Flag :: min_heap_size, MinHeapSize) -> OldMinHeapSize
5777 Types:
5779 MinHeapSize = OldMinHeapSize = integer() >= 0
5781 Changes the minimum heap size for the calling process.
5783 Returns the old value of the flag.
5785 process_flag(Flag :: min_bin_vheap_size, MinBinVHeapSize) ->
5787 OldMinBinVHeapSize
5788 Types:
5790 MinBinVHeapSize = OldMinBinVHeapSize = integer() >= 0
5792 Changes the minimum binary virtual heap size for the calling
5794 process.
5795 Returns the old value of the flag.
5797 process_flag(Flag :: max_heap_size, MaxHeapSize) -> OldMaxHeapSize
5799 Types:
5801 MaxHeapSize = OldMaxHeapSize = max_heap_size()
5803 max_heap_size() =
5804 integer() >= 0 |
5805 #{size => integer() >= 0,
5806 kill => boolean(),
5807 error_logger => boolean()}
5808 This flag sets the maximum heap size for the calling process. If
5810 MaxHeapSize is an integer, the system default values for kill
5811 and error_logger are used.
5812 For details on how the heap grows, see Sizing the heap in the
5814 ERTS internal documentation.
5815 size:
5817 The maximum size in words of the process. If set to zero,
5818 the heap size limit is disabled. badarg is be thrown if the
5819 value is smaller than min_heap_size. The size check is only
5820 done when a garbage collection is triggered.
5821 size is the entire heap of the process when garbage collec‐
5823 tion is triggered. This includes all generational heaps, the
5824 process stack, any messages that are considered to be part
5825 of the heap, and any extra memory that the garbage collector
5826 needs during collection.
5827 size is the same as can be retrieved using er‐
5829 lang:process_info(Pid, total_heap_size), or by adding
5830 heap_block_size, old_heap_block_size and mbuf_size from er‐
5831 lang:process_info(Pid, garbage_collection_info).
5832 kill:
5834 When set to true, the runtime system sends an untrappable
5835 exit signal with reason kill to the process if the maximum
5836 heap size is reached. The garbage collection that triggered
5837 the kill is not completed, instead the process exits as soon
5838 as possible. When set to false, no exit signal is sent to
5839 the process, instead it continues executing.
5840 If kill is not defined in the map, the system default will
5842 be used. The default system default is true. It can be
5843 changed by either option +hmaxk in erl(1), or erlang:sys‐
5844 tem_flag(max_heap_size, MaxHeapSize).
5845 error_logger:
5847 When set to true, the runtime system logs an error event via
5848 logger, containing details about the process when the maxi‐
5849 mum heap size is reached. One log event is sent each time
5850 the limit is reached.
5851 If error_logger is not defined in the map, the system de‐
5853 fault is used. The default system default is true. It can be
5854 changed by either the option +hmaxel int erl(1), or er‐
5855 lang:system_flag(max_heap_size, MaxHeapSize).
5856 The heap size of a process is quite hard to predict, especially
5858 the amount of memory that is used during the garbage collection.
5859 When contemplating using this option, it is recommended to first
5860 run it in production with kill set to false and inspect the log
5861 events to see what the normal peak sizes of the processes in the
5862 system is and then tune the value accordingly.
5863 process_flag(Flag :: message_queue_data, MQD) -> OldMQD
5865 Types:
5867 MQD = OldMQD = message_queue_data()
5869 message_queue_data() = off_heap | on_heap
5870 Determines how messages in the message queue are stored, as fol‐
5872 lows:
5873 off_heap:
5875 All messages in the message queue will be stored outside the
5876 process heap. This implies that no messages in the message
5877 queue will be part of a garbage collection of the process.
5878 on_heap:
5880 All messages in the message queue will eventually be placed
5881 on the process heap. They can, however, be temporarily
5882 stored off the heap. This is how messages have always been
5883 stored up until ERTS 8.0.
5884 The default value of the message_queue_data process flag is de‐
5886 termined by the command-line argument +hmqd in erl(1).
5887 If the process may potentially accumulate a large number of mes‐
5889 sages in its queue it is recommended to set the flag value to
5890 off_heap. This is due to the fact that the garbage collection of
5891 a process that has a large number of messages stored on the heap
5892 can become extremely expensive and the process can consume large
5893 amounts of memory. The performance of the actual message passing
5894 is, however, generally better when the flag value is on_heap.
5895 Changing the flag value causes any existing messages to be
5897 moved. The move operation is initiated, but not necessarily com‐
5898 pleted, by the time the function returns.
5899 Returns the old value of the flag.
5901 process_flag(Flag :: priority, Level) -> OldLevel
5903 Types:
5905 Level = OldLevel = priority_level()
5907 priority_level() = low | normal | high | max
5908 Sets the process priority. Level is an atom. Four priority lev‐
5910 els exist: low, normal, high, and max. Default is normal.
5911 Note:
5913 Priority level max is reserved for internal use in the Erlang
5914 runtime system, and is not to be used by others.
5915 Internally in each priority level, processes are scheduled in a
5918 round robin fashion.
5919 Execution of processes on priority normal and low are inter‐
5921 leaved. Processes on priority low are selected for execution
5922 less frequently than processes on priority normal.
5923 When runnable processes on priority high exist, no processes on
5925 priority low or normal are selected for execution. Notice how‐
5926 ever that this does not mean that no processes on priority low
5927 or normal can run when processes are running on priority high.
5928 When using multiple schedulers, more processes can be running in
5929 parallel than processes on priority high. That is, a low and a
5930 high priority process can execute at the same time.
5931 When runnable processes on priority max exist, no processes on
5933 priority low, normal, or high are selected for execution. As
5934 with priority high, processes on lower priorities can execute in
5935 parallel with processes on priority max.
5936 Scheduling is pre-emptive. Regardless of priority, a process is
5938 pre-empted when it has consumed more than a certain number of
5939 reductions since the last time it was selected for execution.
5940 Note:
5942 Do not depend on the scheduling to remain exactly as it is to‐
5943 day. Scheduling is likely to be changed in a future release to
5944 use available processor cores better.
5945 There is no automatic mechanism for avoiding priority inversion,
5948 such as priority inheritance or priority ceilings. When using
5949 priorities, take this into account and handle such scenarios by
5950 yourself.
5951 Making calls from a high priority process into code that you has
5953 no control over can cause the high priority process to wait for
5954 a process with lower priority. That is, effectively decreasing
5955 the priority of the high priority process during the call. Even
5956 if this is not the case with one version of the code that you
5957 have no control over, it can be the case in a future version of
5958 it. This can, for example, occur if a high priority process
5959 triggers code loading, as the code server runs on priority nor‐
5960 mal.
5961 Other priorities than normal are normally not needed. When other
5963 priorities are used, use them with care, especially priority
5964 high. A process on priority high is only to perform work for
5965 short periods. Busy looping for long periods in a high priority
5966 process causes most likely problems, as important OTP servers
5967 run on priority normal.
5968 Returns the old value of the flag.
5970 process_flag(Flag :: save_calls, N) -> OldN
5972 Types:
5974 N = OldN = 0..10000
5976 N must be an integer in the interval 0..10000. If N > 0, call
5978 saving is made active for the process. This means that informa‐
5979 tion about the N most recent global function calls, BIF calls,
5980 sends, and receives made by the process are saved in a list,
5981 which can be retrieved with process_info(Pid, last_calls). A
5982 global function call is one in which the module of the function
5983 is explicitly mentioned. Only a fixed amount of information is
5984 saved, as follows:
5985 * A tuple {Module, Function, Arity} for function calls
5987 * The atoms send, 'receive', and timeout for sends and re‐
5989 ceives ('receive' when a message is received and timeout
5990 when a receive times out)
5991 If N = 0, call saving is disabled for the process, which is the
5993 default. Whenever the size of the call saving list is set, its
5994 contents are reset.
5995 Returns the old value of the flag.
5997 process_flag(Flag :: sensitive, Boolean) -> OldBoolean
5999 Types:
6001 Boolean = OldBoolean = boolean()
6003 Sets or clears flag sensitive for the current process. When a
6005 process has been marked as sensitive by calling
6006 process_flag(sensitive, true), features in the runtime system
6007 that can be used for examining the data or inner working of the
6008 process are silently disabled.
6009 Features that are disabled include (but are not limited to) the
6011 following:
6012 * Tracing. Trace flags can still be set for the process, but
6014 no trace messages of any kind are generated. (If flag sensi‐
6015 tive is turned off, trace messages are again generated if
6016 any trace flags are set.)
6017 * Sequential tracing. The sequential trace token is propagated
6019 as usual, but no sequential trace messages are generated.
6020 process_info/1,2 cannot be used to read out the message queue or
6022 the process dictionary (both are returned as empty lists).
6023 Stack back-traces cannot be displayed for the process.
6025 In crash dumps, the stack, messages, and the process dictionary
6027 are omitted.
6028 If {save_calls,N} has been set for the process, no function
6030 calls are saved to the call saving list. (The call saving list
6031 is not cleared. Also, send, receive, and time-out events are
6032 still added to the list.)
6033 Returns the old value of the flag.
6035 process_flag(Pid, Flag, Value) -> OldValue
6037 Types:
6039 Pid = pid()
6041 Flag = save_calls
6042 Value = OldValue = integer() >= 0
6043 Sets certain flags for the process Pid, in the same manner as
6045 process_flag/2. Returns the old value of the flag. The valid
6046 values for Flag are only a subset of those allowed in
6047 process_flag/2, namely save_calls.
6048 Failure: badarg if Pid is not a local process.
6050 process_info(Pid) -> Info
6052 Types:
6054 Pid = pid()
6056 Info = [InfoTuple] | undefined
6057 InfoTuple = process_info_result_item()
6058 process_info_result_item() =
6059 {backtrace, Bin :: binary()} |
6060 {binary,
6061 BinInfo ::
6062 [{integer() >= 0,
6063 integer() >= 0,
6064 integer() >= 0}]} |
6065 {catchlevel, CatchLevel :: integer() >= 0} |
6066 {current_function,
6067 {Module :: module(), Function :: atom(), Arity :: arity()} |
6068 undefined} |
6069 {current_location,
6070 {Module :: module(),
6071 Function :: atom(),
6072 Arity :: arity(),
6073 Location ::
6074 [{file, Filename :: string()} |
6075 {line, Line :: integer() >= 1}]}} |
6076 {current_stacktrace, Stack :: [stack_item()]} |
6077 {dictionary, Dictionary :: [{Key :: term(), Value :: term()}]} |
6078 {error_handler, Module :: module()} |
6079 {garbage_collection, GCInfo :: [{atom(), integer() >= 0}]} |
6080 {garbage_collection_info,
6081 GCInfo :: [{atom(), integer() >= 0}]} |
6082 {group_leader, GroupLeader :: pid()} |
6083 {heap_size, Size :: integer() >= 0} |
6084 {initial_call, mfa()} |
6085 {links, PidsAndPorts :: [pid() | port()]} |
6086 {last_calls, false | (Calls :: [mfa()])} |
6087 {memory, Size :: integer() >= 0} |
6088 {message_queue_len, MessageQueueLen :: integer() >= 0} |
6089 {messages, MessageQueue :: [term()]} |
6090 {min_heap_size, MinHeapSize :: integer() >= 0} |
6091 {min_bin_vheap_size, MinBinVHeapSize :: integer() >= 0} |
6092 {max_heap_size, MaxHeapSize :: max_heap_size()} |
6093 {monitored_by,
6094 MonitoredBy :: [pid() | port() | nif_resource()]} |
6095 {monitors,
6096 Monitors ::
6097 [{process | port,
6098 Pid ::
6099 pid() |
6100 port() |
6101 {RegName :: atom(), Node :: node()}}]} |
6102 {message_queue_data, MQD :: message_queue_data()} |
6103 {parent, pid() | undefined} |
6104 {priority, Level :: priority_level()} |
6105 {reductions, Number :: integer() >= 0} |
6106 {registered_name, [] | (Atom :: atom())} |
6107 {sequential_trace_token,
6108 [] | (SequentialTraceToken :: term())} |
6109 {stack_size, Size :: integer() >= 0} |
6110 {status,
6111 Status ::
6112 exiting | garbage_collecting | waiting | running |
6113 runnable | suspended} |
6114 {suspending,
6115 SuspendeeList ::
6116 [{Suspendee :: pid(),
6117 ActiveSuspendCount :: integer() >= 0,
6118 OutstandingSuspendCount :: integer() >= 0}]} |
6119 {total_heap_size, Size :: integer() >= 0} |
6120 {trace, InternalTraceFlags :: integer() >= 0} |
6121 {trap_exit, Boolean :: boolean()}
6122 priority_level() = low | normal | high | max
6123 stack_item() =
6124 {Module :: module(),
6125 Function :: atom(),
6126 Arity :: arity() | (Args :: [term()]),
6127 Location ::
6128 [{file, Filename :: string()} |
6129 {line, Line :: integer() >= 1}]}
6130 max_heap_size() =
6131 integer() >= 0 |
6132 #{size => integer() >= 0,
6133 kill => boolean(),
6134 error_logger => boolean()}
6135 message_queue_data() = off_heap | on_heap
6136 Returns a list containing InfoTuples with miscellaneous informa‐
6138 tion about the process identified by Pid, or undefined if the
6139 process is not alive.
6140 The order of the InfoTuples is undefined and all InfoTuples are
6142 not mandatory. The InfoTuples part of the result can be changed
6143 without prior notice.
6144 The InfoTuples with the following items are part of the result:
6146 * current_function
6148 * initial_call
6150 * status
6152 * message_queue_len
6154 * links
6156 * dictionary
6158 * trap_exit
6160 * error_handler
6162 * priority
6164 * group_leader
6166 * total_heap_size
6168 * heap_size
6170 * stack_size
6172 * reductions
6174 * garbage_collection
6176 If the process identified by Pid has a registered name, also an
6178 InfoTuple with item registered_name is included.
6179 For information about specific InfoTuples, see process_info/2.
6181 Warning:
6183 This BIF is intended for debugging only. For all other purposes,
6184 use process_info/2.
6185 Failure: badarg if Pid is not a local process.
6188 process_info(Pid, Item) -> InfoTuple | [] | undefined
6190 process_info(Pid, ItemList) -> InfoTupleList | [] | undefined
6192 Types:
6194 Pid = pid()
6196 ItemList = [Item]
6197 Item = process_info_item()
6198 InfoTupleList = [InfoTuple]
6199 InfoTuple = process_info_result_item()
6200 process_info_item() =
6201 backtrace | binary | catchlevel | current_function |
6202 current_location | current_stacktrace | dictionary |
6203 error_handler | garbage_collection | garbage_collection_info |
6204 group_leader | heap_size | initial_call | links | last_calls |
6205 memory | message_queue_len | messages | min_heap_size |
6206 min_bin_vheap_size | monitored_by | monitors |
6207 message_queue_data | parent | priority | reductions |
6208 registered_name | sequential_trace_token | stack_size |
6209 status | suspending | total_heap_size | trace | trap_exit
6210 process_info_result_item() =
6211 {backtrace, Bin :: binary()} |
6212 {binary,
6213 BinInfo ::
6214 [{integer() >= 0,
6215 integer() >= 0,
6216 integer() >= 0}]} |
6217 {catchlevel, CatchLevel :: integer() >= 0} |
6218 {current_function,
6219 {Module :: module(), Function :: atom(), Arity :: arity()} |
6220 undefined} |
6221 {current_location,
6222 {Module :: module(),
6223 Function :: atom(),
6224 Arity :: arity(),
6225 Location ::
6226 [{file, Filename :: string()} |
6227 {line, Line :: integer() >= 1}]}} |
6228 {current_stacktrace, Stack :: [stack_item()]} |
6229 {dictionary, Dictionary :: [{Key :: term(), Value :: term()}]} |
6230 {error_handler, Module :: module()} |
6231 {garbage_collection, GCInfo :: [{atom(), integer() >= 0}]} |
6232 {garbage_collection_info,
6233 GCInfo :: [{atom(), integer() >= 0}]} |
6234 {group_leader, GroupLeader :: pid()} |
6235 {heap_size, Size :: integer() >= 0} |
6236 {initial_call, mfa()} |
6237 {links, PidsAndPorts :: [pid() | port()]} |
6238 {last_calls, false | (Calls :: [mfa()])} |
6239 {memory, Size :: integer() >= 0} |
6240 {message_queue_len, MessageQueueLen :: integer() >= 0} |
6241 {messages, MessageQueue :: [term()]} |
6242 {min_heap_size, MinHeapSize :: integer() >= 0} |
6243 {min_bin_vheap_size, MinBinVHeapSize :: integer() >= 0} |
6244 {max_heap_size, MaxHeapSize :: max_heap_size()} |
6245 {monitored_by,
6246 MonitoredBy :: [pid() | port() | nif_resource()]} |
6247 {monitors,
6248 Monitors ::
6249 [{process | port,
6250 Pid ::
6251 pid() |
6252 port() |
6253 {RegName :: atom(), Node :: node()}}]} |
6254 {message_queue_data, MQD :: message_queue_data()} |
6255 {parent, pid() | undefined} |
6256 {priority, Level :: priority_level()} |
6257 {reductions, Number :: integer() >= 0} |
6258 {registered_name, [] | (Atom :: atom())} |
6259 {sequential_trace_token,
6260 [] | (SequentialTraceToken :: term())} |
6261 {stack_size, Size :: integer() >= 0} |
6262 {status,
6263 Status ::
6264 exiting | garbage_collecting | waiting | running |
6265 runnable | suspended} |
6266 {suspending,
6267 SuspendeeList ::
6268 [{Suspendee :: pid(),
6269 ActiveSuspendCount :: integer() >= 0,
6270 OutstandingSuspendCount :: integer() >= 0}]} |
6271 {total_heap_size, Size :: integer() >= 0} |
6272 {trace, InternalTraceFlags :: integer() >= 0} |
6273 {trap_exit, Boolean :: boolean()}
6274 stack_item() =
6275 {Module :: module(),
6276 Function :: atom(),
6277 Arity :: arity() | (Args :: [term()]),
6278 Location ::
6279 [{file, Filename :: string()} |
6280 {line, Line :: integer() >= 1}]}
6281 priority_level() = low | normal | high | max
6282 max_heap_size() =
6283 integer() >= 0 |
6284 #{size => integer() >= 0,
6285 kill => boolean(),
6286 error_logger => boolean()}
6287 message_queue_data() = off_heap | on_heap
6288 Returns information about the process identified by Pid, as
6290 specified by Item or ItemList. Returns undefined if the process
6291 is not alive.
6292 If the process is alive and a single Item is specified, the re‐
6294 turned value is the corresponding InfoTuple, unless Item =:=
6295 registered_name and the process has no registered name. In this
6296 case, [] is returned. This strange behavior is because of his‐
6297 torical reasons, and is kept for backward compatibility.
6298 If ItemList is specified, the result is InfoTupleList. The Info‐
6300 Tuples in InfoTupleList are included with the corresponding
6301 Items in the same order as the Items were included in ItemList.
6302 Valid Items can be included multiple times in ItemList.
6303 Getting process information follows the signal ordering guaran‐
6305 tees described in the Processes Chapter in the Erlang Reference
6306 Manual .
6307 Note:
6309 If registered_name is part of ItemList and the process has no
6310 name registered, a {registered_name, []}, InfoTuple will be in‐
6311 cluded in the resulting InfoTupleList. This behavior is differ‐
6312 ent when a single Item =:= registered_name is specified, and
6313 when process_info/1 is used.
6314 Valid InfoTuples with corresponding Items:
6317 {backtrace, Bin}:
6319 Binary Bin contains the same information as the output from
6320 erlang:process_display(Pid, backtrace). Use binary_to_list/1
6321 to obtain the string of characters from the binary.
6322 {binary, BinInfo}:
6324 BinInfo is a list containing miscellaneous information about
6325 binaries on the heap of this process. This InfoTuple can be
6326 changed or removed without prior notice. In the current im‐
6327 plementation BinInfo is a list of tuples. The tuples con‐
6328 tain; BinaryId, BinarySize, BinaryRefcCount.
6329 Depending on the value of the message_queue_data process
6331 flag the message queue may be stored on the heap.
6332 {catchlevel, CatchLevel}:
6334 CatchLevel is the number of currently active catches in this
6335 process. This InfoTuple can be changed or removed without
6336 prior notice.
6337 {current_function, {Module, Function, Arity} | undefined}:
6339 Module, Function, Arity is the current function call of the
6340 process. The value undefined can be returned if the process
6341 is currently executing native compiled code.
6342 {current_location, {Module, Function, Arity, Location}}:
6344 Module, Function, Arity is the current function call of the
6345 process. Location is a list of two-tuples describing the lo‐
6346 cation in the source code.
6347 {current_stacktrace, Stack}:
6349 Returns the current call stack back-trace (stacktrace) of
6350 the process. The stack has the same format as in the catch
6351 part of a try. See The call-stack back trace (stacktrace).
6352 The depth of the stacktrace is truncated according to the
6353 backtrace_depth system flag setting.
6354 {dictionary, Dictionary}:
6356 Dictionary is the process dictionary.
6357 {error_handler, Module}:
6359 Module is the error handler module used by the process (for
6360 undefined function calls, for example).
6361 {garbage_collection, GCInfo}:
6363 GCInfo is a list containing miscellaneous information about
6364 garbage collection for this process. The content of GCInfo
6365 can be changed without prior notice.
6366 {garbage_collection_info, GCInfo}:
6368 GCInfo is a list containing miscellaneous detailed informa‐
6369 tion about garbage collection for this process. The content
6370 of GCInfo can be changed without prior notice. For details
6371 about the meaning of each item, see gc_minor_start in er‐
6372 lang:trace/3.
6373 {group_leader, GroupLeader}:
6375 GroupLeader is the group leader for the I/O of the process.
6376 {heap_size, Size}:
6378 Size is the size in words of the youngest heap generation of
6379 the process. This generation includes the process stack.
6380 This information is highly implementation-dependent, and can
6381 change if the implementation changes.
6382 {initial_call, {Module, Function, Arity}}:
6384 Module, Function, Arity is the initial function call with
6385 which the process was spawned.
6386 {links, PidsAndPorts}:
6388 PidsAndPorts is a list of process identifiers and port iden‐
6389 tifiers, with processes or ports to which the process has a
6390 link.
6391 {last_calls, false|Calls}:
6393 The value is false if call saving is not active for the
6394 process (see process_flag/3). If call saving is active, a
6395 list is returned, in which the last element is the most re‐
6396 cent called.
6397 {memory, Size}:
6399 Size is the size in bytes of the process. This includes call
6402 stack, heap, and internal structures.
6403 {message_queue_len, MessageQueueLen}:
6405 MessageQueueLen is the number of messages currently in the
6406 message queue of the process. This is the length of the list
6407 MessageQueue returned as the information item messages (see
6408 below).
6409 {messages, MessageQueue}:
6411 MessageQueue is a list of the messages to the process, which
6412 have not yet been processed.
6413 {min_heap_size, MinHeapSize}:
6415 MinHeapSize is the minimum heap size for the process.
6416 {min_bin_vheap_size, MinBinVHeapSize}:
6418 MinBinVHeapSize is the minimum binary virtual heap size for
6419 the process.
6420 {monitored_by, MonitoredBy}:
6422 A list of identifiers for all the processes, ports and NIF
6423 resources, that are monitoring the process.
6424 {monitors, Monitors}:
6426 A list of monitors (started by monitor/2) that are active
6427 for the process. For a local process monitor or a remote
6428 process monitor by a process identifier, the list consists
6429 of:
6430 {process, Pid}:
6432 Process is monitored by pid.
6433 {process, {RegName, Node}}:
6435 Local or remote process is monitored by name.
6436 {port, PortId}:
6438 Local port is monitored by port id.
6439 {port, {RegName, Node}}:
6441 Local port is monitored by name. Please note, that remote
6442 port monitors are not supported, so Node will always be
6443 the local node name.
6444 {message_queue_data, MQD}:
6446 MQD is the current value of the message_queue_data process
6447 flag, which can be either off_heap or on_heap. For more in‐
6448 formation, see the documentation of process_flag(mes‐
6449 sage_queue_data, MQD).
6450 {parent, Pid}:
6452 Pid is the identifier of the parent process, the one that
6453 spawned current process. When the process does not have a
6454 parent undefined is returned. Only the initial process
6455 (init) on a node lacks a parent, though.
6456 {priority, Level}:
6458 Level is the current priority level for the process. For
6459 more information on priorities, see process_flag(priority,
6460 Level).
6461 {reductions, Number}:
6463 Number is the number of reductions executed by the process.
6464 {registered_name, Atom}:
6466 Atom is the registered process name. If the process has no
6467 registered name, this tuple is not present in the list.
6468 {sequential_trace_token, [] | SequentialTraceToken}:
6470 SequentialTraceToken is the sequential trace token for the
6471 process. This InfoTuple can be changed or removed without
6472 prior notice.
6473 {stack_size, Size}:
6475 Size is the stack size, in words, of the process.
6476 {status, Status}:
6478 Status is the status of the process and is one of the fol‐
6479 lowing:
6480 * exiting
6482 * garbage_collecting
6484 * waiting (for a message)
6486 * running
6488 * runnable (ready to run, but another process is running)
6490 * suspended (suspended on a "busy" port or by the BIF er‐
6492 lang:suspend_process/1,2)
6493 {suspending, SuspendeeList}:
6495 SuspendeeList is a list of {Suspendee, ActiveSuspendCount,
6496 OutstandingSuspendCount} tuples. Suspendee is the process
6497 identifier of a process that has been, or is to be, sus‐
6498 pended by the process identified by Pid through the BIF er‐
6499 lang:suspend_process/2 or erlang:suspend_process/1.
6500 ActiveSuspendCount is the number of times Suspendee has been
6502 suspended by Pid. OutstandingSuspendCount is the number of
6503 not yet completed suspend requests sent by Pid, that is:
6504 * If ActiveSuspendCount =/= 0, Suspendee is currently in the
6506 suspended state.
6507 * If OutstandingSuspendCount =/= 0, option asynchronous of
6509 erlang:suspend_process/2 has been used and the suspendee
6510 has not yet been suspended by Pid.
6511 Notice that ActiveSuspendCount and OutstandingSuspendCount
6513 are not the total suspend count on Suspendee, only the parts
6514 contributed by Pid.
6515 {total_heap_size, Size}:
6517 Size is the total size, in words, of all heap fragments of
6518 the process. This includes the process stack and any unre‐
6519 ceived messages that are considered to be part of the heap.
6520 {trace, InternalTraceFlags}:
6522 InternalTraceFlags is an integer representing the internal
6523 trace flag for this process. This InfoTuple can be changed
6524 or removed without prior notice.
6525 {trap_exit, Boolean}:
6527 Boolean is true if the process is trapping exits, otherwise
6528 false.
6529 Notice that not all implementations support all these Items.
6531 Failures:
6533 badarg:
6535 If Pid is not a local process.
6536 badarg:
6538 If Item is an invalid item.
6539 processes() -> [pid()]
6541 Returns a list of process identifiers corresponding to all the
6543 processes currently existing on the local node.
6544 Notice that an exiting process exists, but is not alive. That
6546 is, is_process_alive/1 returns false for an exiting process, but
6547 its process identifier is part of the result returned from pro‐
6548 cesses/0.
6549 Example:
6551 > processes().
6553 [<0.0.0>,<0.2.0>,<0.4.0>,<0.5.0>,<0.7.0>,<0.8.0>]
6554 purge_module(Module) -> true
6556 Types:
6558 Module = atom()
6560 Removes old code for Module. Before this BIF is used,
6562 check_process_code/2 is to be called to check that no processes
6563 execute old code in the module.
6564 Warning:
6566 This BIF is intended for the code server (see code(3)) and is
6567 not to be used elsewhere.
6568 Note:
6571 As from ERTS 8.0 (Erlang/OTP 19), any lingering processes that
6572 still execute the old code is killed by this function. In ear‐
6573 lier versions, such incorrect use could cause much more fatal
6574 failures, like emulator crash.
6575 Failure: badarg if there is no old code for Module.
6578 put(Key, Val) -> term()
6580 Types:
6582 Key = Val = term()
6584 Adds a new Key to the process dictionary, associated with the
6586 value Val, and returns undefined. If Key exists, the old value
6587 is deleted and replaced by Val, and the function returns the old
6588 value. The average time complexity for the current implementa‐
6589 tion of this function is O(1) and the worst case time complexity
6590 is O(N), where N is the number of items in the process dictio‐
6591 nary. Example:
6592 > X = put(name, walrus), Y = put(name, carpenter),
6594 Z = get(name),
6595 {X, Y, Z}.
6596 {undefined,walrus,carpenter}
6597 Note:
6599 The values stored when put is evaluated within the scope of a
6600 catch are not retracted if a throw is evaluated, or if an error
6601 occurs.
6602 erlang:raise(Class, Reason, Stacktrace) -> badarg
6605 Types:
6607 Class = error | exit | throw
6609 Reason = term()
6610 Stacktrace = raise_stacktrace() | stacktrace()
6611 raise_stacktrace() =
6612 [{module(), atom(), arity() | [term()]} |
6613 {function(), arity() | [term()]}]
6614 Raises an exception of the specified class, reason, and call
6616 stack backtrace (stacktrace).
6617 Class is error, exit, or throw. So, if it were not for the
6619 stacktrace, erlang:raise(Class, Reason, Stacktrace) is equiva‐
6620 lent to erlang:Class(Reason) (given that Class is a valid
6621 class).
6622 Reason can be any term.
6624 Stacktrace is a list as provided in a try-catch clause.
6626 try
6628 ...
6629 catch Class:Reason:Stacktrace ->
6630 ...
6631 end
6632 That is, a list of four-tuples {Module, Function, Arity | Args,
6634 ExtraInfo}, where Module and Function are atoms, and the third
6635 element is an integer arity or an argument list. The stacktrace
6636 can also contain {Fun, Args, ExtraInfo} tuples, where Fun is a
6637 local fun and Args is an argument list.
6638 Element ExtraInfo at the end is optional. Omitting it is equiva‐
6640 lent to specifying an empty list.
6641 The stacktrace is used as the exception stacktrace for the call‐
6643 ing process; it is truncated to the current maximum stacktrace
6644 depth.
6645 As evaluating this function causes the process to terminate, it
6647 has no return value unless the arguments are invalid, in which
6648 case the function returns the error reason badarg. If you want
6649 to be sure not to return, you can call error(erlang:raise(Class,
6650 Reason, Stacktrace)) and hope to distinguish exceptions later.
6651 See the reference manual about errors and error handling for
6653 more information about exception classes and how to catch excep‐
6654 tions.
6655 erlang:read_timer(TimerRef) -> Result
6657 Types:
6659 TimerRef = reference()
6661 Time = integer() >= 0
6662 Result = Time | false
6663 Reads the state of a timer. The same as calling er‐
6665 lang:read_timer(TimerRef, []).
6666 erlang:read_timer(TimerRef, Options) -> Result | ok
6668 Types:
6670 TimerRef = reference()
6672 Async = boolean()
6673 Option = {async, Async}
6674 Options = [Option]
6675 Time = integer() >= 0
6676 Result = Time | false
6677 Reads the state of a timer that has been created by either er‐
6679 lang:start_timer or erlang:send_after. TimerRef identifies the
6680 timer, and was returned by the BIF that created the timer.
6681 Options:
6683 {async, Async}:
6685 Asynchronous request for state information. Async defaults
6686 to false, which causes the operation to be performed syn‐
6687 chronously. In this case, the Result is returned by er‐
6688 lang:read_timer. When Async is true, erlang:read_timer sends
6689 an asynchronous request for the state information to the
6690 timer service that manages the timer, and then returns ok. A
6691 message on the format {read_timer, TimerRef, Result} is sent
6692 to the caller of erlang:read_timer when the operation has
6693 been processed.
6694 More Options can be added in the future.
6696 If Result is an integer, it represents the time in milliseconds
6698 left until the timer expires.
6699 If Result is false, a timer corresponding to TimerRef could not
6701 be found. This because the timer had expired, or been canceled,
6702 or because TimerRef never has corresponded to a timer. Even if
6703 the timer has expired, it does not tell you whether or not the
6704 time-out message has arrived at its destination yet.
6705 Note:
6707 The timer service that manages the timer can be co-located with
6708 another scheduler than the scheduler that the calling process is
6709 executing on. If so, communication with the timer service takes
6710 much longer time than if it is located locally. If the calling
6711 process is in a critical path, and can do other things while
6712 waiting for the result of this operation, you want to use option
6713 {async, true}. If using option {async, false}, the calling
6714 process is blocked until the operation has been performed.
6715 See also erlang:send_after/4, erlang:start_timer/4, and er‐
6718 lang:cancel_timer/2.
6719 ref_to_list(Ref) -> string()
6721 Types:
6723 Ref = reference()
6725 Returns a string corresponding to the text representation of
6727 Ref.
6728 Warning:
6730 This BIF is intended for debugging and is not to be used in ap‐
6731 plication programs.
6732 register(RegName, PidOrPort) -> true
6735 Types:
6737 RegName = atom()
6739 PidOrPort = port() | pid()
6740 Registers the name RegName with a process identifier (pid) or a
6742 port identifier in the name registry. RegName, which must be an
6743 atom, can be used instead of the pid or port identifier in send
6744 operator (RegName ! Message) and most other BIFs that take a pid
6745 or port identifies as an argument. Example:
6746 > register(db, Pid).
6748 true
6749 The registered name is considered a Directly Visible Erlang Re‐
6751 source and is automatically unregistered when the process termi‐
6752 nates.
6753 Failures:
6755 badarg:
6757 If PidOrPort is not an existing local process or port.
6758 badarg:
6760 If RegName is already in use.
6761 badarg:
6763 If the process or port is already registered (already has a
6764 name).
6765 badarg:
6767 If RegName is the atom undefined.
6768 registered() -> [RegName]
6770 Types:
6772 RegName = atom()
6774 Returns a list of names that have been registered using regis‐
6776 ter/2, for example:
6777 > registered().
6779 [code_server, file_server, init, user, my_db]
6780 erlang:resume_process(Suspendee) -> true
6782 Types:
6784 Suspendee = pid()
6786 Decreases the suspend count on the process identified by Sus‐
6788 pendee. Suspendee is previously to have been suspended through
6789 erlang:suspend_process/2 or erlang:suspend_process/1 by the
6790 process calling erlang:resume_process(Suspendee). When the sus‐
6791 pend count on Suspendee reaches zero, Suspendee is resumed, that
6792 is, its state is changed from suspended into the state it had
6793 before it was suspended.
6794 Warning:
6796 This BIF is intended for debugging only.
6797 Failures:
6800 badarg:
6802 If Suspendee is not a process identifier.
6803 badarg:
6805 If the process calling erlang:resume_process/1 had not pre‐
6806 viously increased the suspend count on the process identi‐
6807 fied by Suspendee.
6808 badarg:
6810 If the process identified by Suspendee is not alive.
6811 round(Number) -> integer()
6813 Types:
6815 Number = number()
6817 Returns an integer by rounding Number, for example:
6819 round(42.1).
6821 42
6822 round(5.5).
6824 6
6825 round(-5.5).
6827 -6
6828 round(36028797018963969.0).
6830 36028797018963968
6831 In the last example, round(36028797018963969.0) evaluates to
6833 36028797018963968. The reason for this is that the number
6834 36028797018963969.0 cannot be represented exactly as a float
6835 value. Instead, the float literal is represented as
6836 36028797018963968.0, which is the closest number that can be
6837 represented exactly as a float value. See Representation of
6838 Floating Point Numbers for additional information.
6839 Allowed in guard tests.
6841 self() -> pid()
6843 Returns the process identifier of the calling process, for exam‐
6845 ple:
6846 > self().
6848 <0.26.0>
6849 Allowed in guard tests.
6851 erlang:send(Dest, Msg) -> Msg
6853 Types:
6855 Dest = send_destination()
6857 Msg = term()
6858 Sends a message and returns Msg. This is the same as using the
6860 send operator: Dest ! Msg.
6861 Dest can be a remote or local process identifier, an alias, a
6863 (local) port, a locally registered name, or a tuple {RegName,
6864 Node} for a registered name at another node.
6865 The function fails with a badarg run-time error if Dest is an
6867 atom name, but this name is not registered. This is the only
6868 case when send fails for an unreachable destination Dest (of
6869 correct type).
6870 erlang:send(Dest, Msg, Options) -> Res
6872 Types:
6874 Dest = send_destination()
6876 Msg = term()
6877 Options = [nosuspend | noconnect]
6878 Res = ok | nosuspend | noconnect
6879 Either sends a message and returns ok, or does not send the mes‐
6881 sage but returns something else (see below). Otherwise the same
6882 as erlang:send/2. For more detailed explanation and warnings,
6883 see erlang:send_nosuspend/2,3.
6884 Options:
6886 nosuspend:
6888 If the sender would have to be suspended to do the send, no‐
6889 suspend is returned instead.
6890 noconnect:
6892 If the destination node would have to be auto-connected to
6893 do the send, noconnect is returned instead.
6894 Warning:
6896 As with erlang:send_nosuspend/2,3: use with extreme care.
6897 erlang:send_after(Time, Dest, Msg) -> TimerRef
6900 Types:
6902 Time = integer() >= 0
6904 Dest = pid() | atom()
6905 Msg = term()
6906 TimerRef = reference()
6907 Starts a timer. The same as calling erlang:send_after(Time,
6909 Dest, Msg, []).
6910 erlang:send_after(Time, Dest, Msg, Options) -> TimerRef
6912 Types:
6914 Time = integer()
6916 Dest = pid() | atom()
6917 Msg = term()
6918 Options = [Option]
6919 Abs = boolean()
6920 Option = {abs, Abs}
6921 TimerRef = reference()
6922 Starts a timer. When the timer expires, the message Msg is sent
6924 to the process identified by Dest. Apart from the format of the
6925 time-out message, this function works exactly as er‐
6926 lang:start_timer/4.
6927 erlang:send_nosuspend(Dest, Msg) -> boolean()
6929 Types:
6931 Dest = send_destination()
6933 Msg = term()
6934 The same as erlang:send(Dest, Msg, [nosuspend]), but returns
6936 true if the message was sent and false if the message was not
6937 sent because the sender would have had to be suspended.
6938 This function is intended for send operations to an unreliable
6940 remote node without ever blocking the sending (Erlang) process.
6941 If the connection to the remote node (usually not a real Erlang
6942 node, but a node written in C or Java) is overloaded, this func‐
6943 tion does not send the message and returns false.
6944 The same occurs if Dest refers to a local port that is busy. For
6946 all other destinations (allowed for the ordinary send operator
6947 '!'), this function sends the message and returns true.
6948 This function is only to be used in rare circumstances where a
6950 process communicates with Erlang nodes that can disappear with‐
6951 out any trace, causing the TCP buffers and the drivers queue to
6952 be over-full before the node is shut down (because of tick time-
6953 outs) by net_kernel. The normal reaction to take when this oc‐
6954 curs is some kind of premature shutdown of the other node.
6955 Notice that ignoring the return value from this function would
6957 result in an unreliable message passing, which is contradictory
6958 to the Erlang programming model. The message is not sent if this
6959 function returns false.
6960 In many systems, transient states of overloaded queues are nor‐
6962 mal. Although this function returns false does not mean that the
6963 other node is guaranteed to be non-responsive, it could be a
6964 temporary overload. Also, a return value of true does only mean
6965 that the message can be sent on the (TCP) channel without block‐
6966 ing; the message is not guaranteed to arrive at the remote node.
6967 For a disconnected non-responsive node, the return value is true
6968 (mimics the behavior of operator !). The expected behavior and
6969 the actions to take when the function returns false are applica‐
6970 tion- and hardware-specific.
6971 Warning:
6973 Use with extreme care.
6974 erlang:send_nosuspend(Dest, Msg, Options) -> boolean()
6977 Types:
6979 Dest = send_destination()
6981 Msg = term()
6982 Options = [noconnect]
6983 The same as erlang:send(Dest, Msg, [nosuspend | Options]), but
6985 with a Boolean return value.
6986 This function behaves like erlang:send_nosuspend/2, but takes a
6988 third parameter, a list of options. The only option is nocon‐
6989 nect, which makes the function return false if the remote node
6990 is not currently reachable by the local node. The normal behav‐
6991 ior is to try to connect to the node, which can stall the
6992 process during a short period. The use of option noconnect makes
6993 it possible to be sure not to get the slightest delay when send‐
6994 ing to a remote process. This is especially useful when communi‐
6995 cating with nodes that expect to always be the connecting part
6996 (that is, nodes written in C or Java).
6997 Whenever the function returns false (either when a suspend would
6999 occur or when noconnect was specified and the node was not al‐
7000 ready connected), the message is guaranteed not to have been
7001 sent.
7002 Warning:
7004 Use with extreme care.
7005 erlang:set_cookie(Cookie) -> true
7008 Types:
7010 Cookie = atom()
7012 Sets the magic cookie of the local node to the atom Cookie,
7014 which is also the cookie for all nodes that have no explicit
7015 cookie set with set_cookie/2 Cookie (see section Distributed
7016 Erlang in the Erlang Reference Manual in System Documentation).
7017 You can get this value using get_cookie/0.
7019 Failure: function_clause if the local node is not alive.
7021 erlang:set_cookie(Node, Cookie) -> true
7023 Types:
7025 Node = node()
7027 Cookie = atom()
7028 Sets the magic cookie for Node to the atom Cookie. If Node is
7030 the local node, the function sets the cookie of all other nodes
7031 (that have no explicit cookie set with this function) to Cookie
7032 (see section Distributed Erlang in the Erlang Reference Manual
7033 in System Documentation).
7034 You can get this value using get_cookie/1.
7036 Failure: function_clause if the local node is not alive.
7038 setelement(Index, Tuple1, Value) -> Tuple2
7040 Types:
7042 Index = integer() >= 1
7044 1..tuple_size(Tuple1)
7045 Tuple1 = Tuple2 = tuple()
7046 Value = term()
7047 Returns a tuple that is a copy of argument Tuple1 with the ele‐
7049 ment specified by integer argument Index (the first element is
7050 the element with index 1) replaced by argument Value, for exam‐
7051 ple:
7052 > setelement(2, {10, green, bottles}, red).
7054 {10,red,bottles}
7055 size(Item) -> integer() >= 0
7057 Types:
7059 Item = tuple() | binary()
7061 Returns the number of elements in a tuple or the number of bytes
7063 in a binary or bitstring, for example:
7064 > size({morni, mulle, bwange}).
7066 3
7067 > size(<<11, 22, 33>>).
7068 3
7069 For bitstrings, the number of whole bytes is returned. That is,
7071 if the number of bits in the bitstring is not divisible by 8,
7072 the resulting number of bytes is rounded down.
7073 Allowed in guard tests.
7075 See also tuple_size/1, byte_size/1, and bit_size/1.
7077 spawn(Fun) -> pid()
7079 Types:
7081 Fun = function()
7083 Returns the process identifier of a new process started by the
7085 application of Fun to the empty list []. Otherwise works like
7086 spawn/3.
7087 spawn(Node, Fun) -> pid()
7089 Types:
7091 Node = node()
7093 Fun = function()
7094 Returns the process identifier of a new process started by the
7096 application of Fun to the empty list [] on Node. If Node does
7097 not exist, a useless pid is returned. Otherwise works like
7098 spawn/3.
7099 spawn(Module, Function, Args) -> pid()
7101 Types:
7103 Module = module()
7105 Function = atom()
7106 Args = [term()]
7107 Returns the process identifier of a new process started by the
7109 application of Module:Function to Args.
7110 error_handler:undefined_function(Module, Function, Args) is
7112 evaluated by the new process if Module:Function/Arity does not
7113 exist (where Arity is the length of Args). The error handler can
7114 be redefined (see process_flag/2). If error_handler is unde‐
7115 fined, or the user has redefined the default error_handler and
7116 its replacement is undefined, a failure with reason undef oc‐
7117 curs.
7118 Example:
7120 > spawn(speed, regulator, [high_speed, thin_cut]).
7122 <0.13.1>
7123 spawn(Node, Module, Function, Args) -> pid()
7125 Types:
7127 Node = node()
7129 Module = module()
7130 Function = atom()
7131 Args = [term()]
7132 Returns the process identifier (pid) of a new process started by
7134 the application of Module:Function to Args on Node. If Node does
7135 not exist, a useless pid is returned. Otherwise works like
7136 spawn/3.
7137 spawn_link(Fun) -> pid()
7139 Types:
7141 Fun = function()
7143 Returns the process identifier of a new process started by the
7145 application of Fun to the empty list []. A link is created be‐
7146 tween the calling process and the new process, atomically. Oth‐
7147 erwise works like spawn/3.
7148 spawn_link(Node, Fun) -> pid()
7150 Types:
7152 Node = node()
7154 Fun = function()
7155 Returns the process identifier (pid) of a new process started by
7157 the application of Fun to the empty list [] on Node. A link is
7158 created between the calling process and the new process, atomi‐
7159 cally. If Node does not exist, a useless pid is returned and an
7160 exit signal with reason noconnection is sent to the calling
7161 process. Otherwise works like spawn/3.
7162 spawn_link(Module, Function, Args) -> pid()
7164 Types:
7166 Module = module()
7168 Function = atom()
7169 Args = [term()]
7170 Returns the process identifier of a new process started by the
7172 application of Module:Function to Args. A link is created be‐
7173 tween the calling process and the new process, atomically. Oth‐
7174 erwise works like spawn/3.
7175 spawn_link(Node, Module, Function, Args) -> pid()
7177 Types:
7179 Node = node()
7181 Module = module()
7182 Function = atom()
7183 Args = [term()]
7184 Returns the process identifier (pid) of a new process started by
7186 the application of Module:Function to Args on Node. A link is
7187 created between the calling process and the new process, atomi‐
7188 cally. If Node does not exist, a useless pid is returned and an
7189 exit signal with reason noconnection is sent to the calling
7190 process. Otherwise works like spawn/3.
7191 spawn_monitor(Fun) -> {pid(), reference()}
7193 Types:
7195 Fun = function()
7197 Returns the process identifier of a new process, started by the
7199 application of Fun to the empty list [], and a reference for a
7200 monitor created to the new process. Otherwise works like
7201 spawn/3.
7202 spawn_monitor(Node, Fun) -> {pid(), reference()}
7204 Types:
7206 Node = node()
7208 Fun = function()
7209 Returns the process identifier of a new process, started by the
7211 application of Fun to the empty list [] on the node Node, and a
7212 reference for a monitor created to the new process. Otherwise
7213 works like spawn/3.
7214 If the node identified by Node does not support distributed
7216 spawn_monitor(), the call will fail with a notsup exception.
7217 spawn_monitor(Module, Function, Args) -> {pid(), reference()}
7219 Types:
7221 Module = module()
7223 Function = atom()
7224 Args = [term()]
7225 A new process is started by the application of Module:Function
7227 to Args. The process is monitored at the same time. Returns the
7228 process identifier and a reference for the monitor. Otherwise
7229 works like spawn/3.
7230 spawn_monitor(Node, Module, Function, Args) ->
7232 {pid(), reference()}
7233 Types:
7235 Node = node()
7237 Module = module()
7238 Function = atom()
7239 Args = [term()]
7240 A new process is started by the application of Module:Function
7242 to Args on the node Node. The process is monitored at the same
7243 time. Returns the process identifier and a reference for the
7244 monitor. Otherwise works like spawn/3.
7245 If the node identified by Node does not support distributed
7247 spawn_monitor(), the call will fail with a notsup exception.
7248 spawn_opt(Fun, Options) -> pid() | {pid(), reference()}
7250 Types:
7252 Fun = function()
7254 Options = [spawn_opt_option()]
7255 priority_level() = low | normal | high | max
7256 max_heap_size() =
7257 integer() >= 0 |
7258 #{size => integer() >= 0,
7259 kill => boolean(),
7260 error_logger => boolean()}
7261 message_queue_data() = off_heap | on_heap
7262 spawn_opt_option() =
7263 link | monitor |
7264 {monitor, MonitorOpts :: [monitor_option()]} |
7265 {priority, Level :: priority_level()} |
7266 {fullsweep_after, Number :: integer() >= 0} |
7267 {min_heap_size, Size :: integer() >= 0} |
7268 {min_bin_vheap_size, VSize :: integer() >= 0} |
7269 {max_heap_size, Size :: max_heap_size()} |
7270 {message_queue_data, MQD :: message_queue_data()}
7271 Returns the process identifier (pid) of a new process started by
7273 the application of Fun to the empty list []. Otherwise works
7274 like spawn_opt/4.
7275 If option monitor is specified, the newly created process is
7277 monitored, and both the pid and reference for the monitor are
7278 returned.
7279 spawn_opt(Node, Fun, Options) -> pid() | {pid(), reference()}
7281 Types:
7283 Node = node()
7285 Fun = function()
7286 Options =
7287 [monitor | {monitor, [monitor_option()]} | link | Oth‐
7288 erOption]
7289 OtherOption = term()
7290 Returns the process identifier (pid) of a new process started by
7292 the application of Fun to the empty list [] on Node. If Node
7293 does not exist, a useless pid is returned. Otherwise works like
7294 spawn_opt/4.
7295 Valid options depends on what options are supported by the node
7297 identified by Node. A description of valid Options for the local
7298 node of current OTP version can be found in the documentation of
7299 spawn_opt/4.
7300 spawn_opt(Module, Function, Args, Options) ->
7302 Pid | {Pid, MonitorRef}
7303 Types:
7305 Module = module()
7307 Function = atom()
7308 Args = [term()]
7309 Options = [spawn_opt_option()]
7310 Pid = pid()
7311 MonitorRef = reference()
7312 priority_level() = low | normal | high | max
7313 max_heap_size() =
7314 integer() >= 0 |
7315 #{size => integer() >= 0,
7316 kill => boolean(),
7317 error_logger => boolean()}
7318 message_queue_data() = off_heap | on_heap
7319 spawn_opt_option() =
7320 link | monitor |
7321 {monitor, MonitorOpts :: [monitor_option()]} |
7322 {priority, Level :: priority_level()} |
7323 {fullsweep_after, Number :: integer() >= 0} |
7324 {min_heap_size, Size :: integer() >= 0} |
7325 {min_bin_vheap_size, VSize :: integer() >= 0} |
7326 {max_heap_size, Size :: max_heap_size()} |
7327 {message_queue_data, MQD :: message_queue_data()}
7328 Works as spawn/3, except that an extra option list is specified
7330 when creating the process.
7331 If option monitor is specified, the newly created process is
7333 monitored, and both the pid and reference for the monitor are
7334 returned.
7335 Options:
7337 link:
7339 Sets a link to the parent process (like spawn_link/3 does).
7340 monitor:
7342 Monitors the new process (like monitor(process, Pid) does).
7343 A {Pid, MonitorRef} tuple will be returned instead of just a
7344 Pid.
7345 {monitor, MonitorOpts}:
7347 Monitors the new process with options (like monitor(process,
7348 Pid, MonitorOpts) does). A {Pid, MonitorRef} tuple will be
7349 returned instead of just a Pid.
7350 {priority, Level}:
7352 Sets the priority of the new process. Equivalent to execut‐
7353 ing process_flag(priority, Level) in the start function of
7354 the new process, except that the priority is set before the
7355 process is selected for execution for the first time. For
7356 more information on priorities, see process_flag(priority,
7357 Level).
7358 {fullsweep_after, Number}:
7360 Useful only for performance tuning. Do not use this option
7361 unless you know that there is problem with execution times
7362 or memory consumption, and ensure that the option improves
7363 matters.
7364 The Erlang runtime system uses a generational garbage col‐
7366 lection scheme, using an "old heap" for data that has sur‐
7367 vived at least one garbage collection. When there is no more
7368 room on the old heap, a fullsweep garbage collection is
7369 done.
7370 Option fullsweep_after makes it possible to specify the max‐
7372 imum number of generational collections before forcing a
7373 fullsweep, even if there is room on the old heap. Setting
7374 the number to zero disables the general collection algo‐
7375 rithm, that is, all live data is copied at every garbage
7376 collection.
7377 A few cases when it can be useful to change fullsweep_after:
7379 * If binaries that are no longer used are to be thrown away
7381 as soon as possible. (Set Number to zero.)
7382 * A process that mostly have short-lived data is fullsweeped
7384 seldom or never, that is, the old heap contains mostly
7385 garbage. To ensure a fullsweep occasionally, set Number to
7386 a suitable value, such as 10 or 20.
7387 * In embedded systems with a limited amount of RAM and no
7389 virtual memory, you might want to preserve memory by set‐
7390 ting Number to zero. (The value can be set globally, see
7391 erlang:system_flag/2.)
7392 {min_heap_size, Size}:
7394 Useful only for performance tuning. Do not use this option
7395 unless you know that there is problem with execution times
7396 or memory consumption, and ensure that the option improves
7397 matters.
7398 Gives a minimum heap size, in words. Setting this value
7400 higher than the system default can speed up some processes
7401 because less garbage collection is done. However, setting a
7402 too high value can waste memory and slow down the system be‐
7403 cause of worse data locality. Therefore, use this option
7404 only for fine-tuning an application and to measure the exe‐
7405 cution time with various Size values.
7406 {min_bin_vheap_size, VSize}:
7408 Useful only for performance tuning. Do not use this option
7409 unless you know that there is problem with execution times
7410 or memory consumption, and ensure that the option improves
7411 matters.
7412 Gives a minimum binary virtual heap size, in words. Setting
7414 this value higher than the system default can speed up some
7415 processes because less garbage collection is done. However,
7416 setting a too high value can waste memory. Therefore, use
7417 this option only for fine-tuning an application and to mea‐
7418 sure the execution time with various VSize values.
7419 {max_heap_size, Size}:
7421 Sets the max_heap_size process flag. The default
7422 max_heap_size is determined by command-line argument +hmax
7423 in erl(1). For more information, see the documentation of
7424 process_flag(max_heap_size, Size).
7425 {message_queue_data, MQD}:
7427 Sets the value of the message_queue_data process flag. MQD
7428 can be either off_heap or on_heap. The default value of the
7429 message_queue_data process flag is determined by the com‐
7430 mand-line argument +hmqd in erl(1). For more information,
7431 see the documentation of process_flag(message_queue_data,
7432 MQD).
7433 spawn_opt(Node, Module, Function, Args, Options) ->
7435 pid() | {pid(), reference()}
7436 Types:
7438 Node = node()
7440 Module = module()
7441 Function = atom()
7442 Args = [term()]
7443 Options =
7444 [monitor | {monitor, [monitor_option()]} | link | Oth‐
7445 erOption]
7446 OtherOption = term()
7447 Returns the process identifier (pid) of a new process started by
7449 the application of Module:Function to Args on Node. If Node does
7450 not exist, a useless pid is returned. Otherwise works like
7451 spawn_opt/4.
7452 Valid options depends on what options are supported by the node
7454 identified by Node. A description of valid Options for the local
7455 node of current OTP version can be found in the documentation of
7456 spawn_opt/4.
7457 spawn_request(Fun) -> ReqId
7459 Types:
7461 Fun = function()
7463 ReqId = reference()
7464 The same as the call spawn_request(node(),Fun,[]). That is, a
7466 spawn request on the local node with no options.
7467 spawn_request(Fun, Options) -> ReqId
7469 Types:
7471 Fun = function()
7473 Option =
7474 {reply_tag, ReplyTag} | {reply, Reply} | spawn_opt_op‐
7475 tion()
7476 ReplyTag = term()
7477 Reply = yes | no | error_only | success_only
7478 Options = [Option]
7479 ReqId = reference()
7480 The same as the call spawn_request(node(),Fun,Options). That is,
7482 a spawn request on the local node.
7483 spawn_request(Node, Fun) -> ReqId
7485 Types:
7487 Node = node()
7489 Fun = function()
7490 ReqId = reference()
7491 The same as the call spawn_request(Node,Fun,[]). That is, a
7493 spawn request with no options.
7494 spawn_request(Node, Fun, Options) -> ReqId
7496 Types:
7498 Node = node()
7500 Fun = function()
7501 Options = [Option]
7502 Option =
7503 monitor |
7504 {monitor, [monitor_option()]} |
7505 link |
7506 {reply_tag, ReplyTag} |
7507 {reply, Reply} |
7508 OtherOption
7509 ReplyTag = term()
7510 Reply = yes | no | error_only | success_only
7511 OtherOption = term()
7512 ReqId = reference()
7513 The same as spawn_request(Node,erlang,apply,[Fun,[]],Options).
7515 That is, a spawn request using the fun Fun of arity zero as en‐
7516 try point.
7517 This function will fail with a badarg exception if:
7519 * Node is not an atom.
7521 * Fun is not a fun of arity zero.
7523 * Options is not a proper list of terms.
7525 spawn_request(Module, Function, Args) -> ReqId
7527 Types:
7529 Module = module()
7531 Function = atom()
7532 Args = [term()]
7533 ReqId = reference()
7534 The same as the call spawn_request(node(),Module,Func‐
7536 tion,Args,[]). That is, a spawn request on the local node with
7537 no options.
7538 spawn_request(Node, Module, Function, Args) -> ReqId
7540 Types:
7542 Node = node()
7544 Module = module()
7545 Function = atom()
7546 Args = [term()]
7547 ReqId = reference()
7548 The same as the call spawn_request(Node,Module,Func‐
7550 tion,Args,[]). That is, a spawn request with no options.
7551 spawn_request(Module, Function, Args, Options) -> ReqId
7553 Types:
7555 Module = module()
7557 Function = atom()
7558 Args = [term()]
7559 Option =
7560 {reply_tag, ReplyTag} | {reply, Reply} | spawn_opt_op‐
7561 tion()
7562 ReplyTag = term()
7563 Reply = yes | no | error_only | success_only
7564 Options = [Option]
7565 ReqId = reference()
7566 The same as the call spawn_request(node(),Module,Func‐
7568 tion,Args,Options). That is, a spawn request on the local node.
7569 spawn_request(Node, Module, Function, Args, Options) -> ReqId
7571 Types:
7573 Node = node()
7575 Module = module()
7576 Function = atom()
7577 Args = [term()]
7578 Options = [Option]
7579 Option =
7580 monitor |
7581 {monitor, [monitor_option()]} |
7582 link |
7583 {reply_tag, ReplyTag} |
7584 {reply, Reply} |
7585 OtherOption
7586 ReplyTag = term()
7587 Reply = yes | no | error_only | success_only
7588 OtherOption = term()
7589 ReqId = reference()
7590 Asynchronously send a spawn request. Returns a request identi‐
7592 fier ReqId.
7593 If the spawn operation succeeds, a new process is created on the
7595 node identified by Node. When a spawn operation succeeds, the
7596 caller will by default be sent a message on the form {ReplyTag,
7597 ReqId, ok, Pid} where Pid is the process identifier of the newly
7598 created process. Such a message is referred to as a success mes‐
7599 sage below in the text. ReplyTag is by default the atom
7600 spawn_reply unless modified by the {reply_tag, ReplyTag} option.
7601 The new process is started by the application of Module:Function
7602 to Args.
7603 The spawn operation fails either if creation of a new process
7605 failed or if the spawn operation was interrupted by a connection
7606 failure. When a spawn operation fails, the caller will by de‐
7607 fault be sent a message on the form {ReplyTag, ReqId, error,
7608 Reason} where Reason is the error reason. Such a message is re‐
7609 ferred to as an error message below in the text. Currently the
7610 following spawn error Reasons are defined, but other reasons can
7611 appear at any time without prior notice:
7612 badopt:
7614 An invalid Option was passed as argument. Note that differ‐
7615 ent runtime systems may support different options.
7616 notsup:
7618 The node identified by Node does not support spawn opera‐
7619 tions issued by spawn_request().
7620 noconnection:
7622 Failure to set up a connection to the node identified by
7623 Node or the connection to that node was lost during the
7624 spawn operation. In the case the connection was lost, a
7625 process may or may not have been created.
7626 system_limit:
7628 Could not create a new process due to that some system limit
7629 was reached. Typically the process table was full.
7630 Valid Options:
7632 monitor:
7634 In the absence of spawn operation failures, atomically sets
7635 up a monitor to the newly created process. That is, as if
7636 the calling process had called monitor(process, Pid) where
7637 Pid is the process identifier of the newly created process.
7638 The ReqId returned by spawn_request() is also used as moni‐
7639 tor reference as if it was returned from monitor(process,
7640 Pid).
7641 The monitor will not be activated for the calling process
7643 until the spawn operation has succeeded. The monitor can not
7644 be demonitored before the operation has succeeded. A 'DOWN'
7645 message for the corresponding monitor is guaranteed not to
7646 be delivered before a success message that corresponds to
7647 the spawn operation. If the spawn operation fails, no 'DOWN'
7648 message will be delivered.
7649 If the connection between the nodes involved in the spawn
7651 operation is lost during the spawn operation, the spawn op‐
7652 eration will fail with an error reason of noconnection. A
7653 new process may or may not have been created.
7654 {monitor, MonitorOpts}:
7656 In the absence of spawn operation failures, atomically sets
7657 up a monitor to the newly created process. That is, as if
7658 the calling process had called monitor(process, Pid, Moni‐
7659 torOpts) where Pid is the process identifier of the newly
7660 created process. See the monitor option above for more in‐
7661 formation.
7662 Note that the monitor will not be activated for the calling
7664 process until the spawn operation has succeeded. For exam‐
7665 ple, in the case that an alias is created using the monitor
7666 option, the alias will not be active until the monitor is
7667 activated.
7668 link:
7670 In absence of spawn operation failures, atomically sets up a
7671 link between the calling process and the newly created
7672 process. That is, as if the calling process had called
7673 link(Pid) where Pid is the process identifier of the newly
7674 created process.
7675 The link will not be activated for the calling process until
7677 the spawn operation has succeeded. The link can not be re‐
7678 moved before the operation has succeeded. An exit signal due
7679 to the link is guaranteed not to be delivered before a suc‐
7680 cess message that corresponds to the spawn operation. If
7681 the spawn operation fails, no exit signal due to the link
7682 will be delivered to the caller of spawn_request().
7683 If the connection between the nodes involved in the spawn
7685 operation is lost during the spawn operation, the spawn op‐
7686 eration will fail with an error reason of noconnection. A
7687 new process may or may not have been created. If it has been
7688 created, it will be delivered an exit signal with an exit
7689 reason of noconnection.
7690 {reply, Reply}:
7692 Valid Reply values:
7693 yes:
7695 A spawn reply message will be sent to the caller regard‐
7696 less of whether the operation succeeds or not. If the call
7697 to spawn_request() returns without raising an exception
7698 and the reply option is set to yes, the caller is guaran‐
7699 teed to be delivered either a success message or an error
7700 message . The reply option is by default set to yes.
7701 no:
7703 No spawn reply message will be sent to the caller when the
7704 spawn operation completes. This regardless of whether the
7705 operation succeeds or not.
7706 error_only:
7708 No spawn reply message will be sent to the caller if the
7709 spawn operation succeeds, but an error message will be
7710 sent to the caller if the operation fails.
7711 success_only:
7713 No spawn reply message will be sent to the caller if the
7714 spawn operation fails, but a success message will be sent
7715 to the caller if the operation succeeds.
7716 {reply_tag, ReplyTag}:
7718 Sets the reply tag to ReplyTag in the reply message. That
7719 is, in the success or error message that is sent to the
7720 caller due to the spawn operation. The default reply tag is
7721 the atom spawn_reply.
7722 OtherOption:
7724 Other valid options depends on what options are supported by
7725 the node identified by Node. A description of other valid
7726 Options for the local node of current OTP version can be
7727 found in the documentation of spawn_opt/4.
7728 If a spawn reply message is delivered, it is guaranteed to be
7730 delivered before any other signals from the newly spawned
7731 process are delivered to the process issuing the spawn request.
7732 This function will fail with a badarg exception if:
7734 * Node is not an atom.
7736 * Module is not an atom.
7738 * Function is not an atom.
7740 * Args is not a proper list of terms.
7742 * Options is not a proper list of terms.
7744 Note that not all individual Options are checked when the spawn
7746 request is sent. Some Options can only be checked on reception
7747 of the request. Therefore an invalid option does not cause a
7748 badarg exception, but will cause the spawn operation to fail
7749 with an error reason of badopt.
7750 A spawn request can be abandoned by calling spawn_request_aban‐
7752 don/1.
7753 spawn_request_abandon(ReqId :: reference()) -> boolean()
7755 Abandon a previously issued spawn request. ReqId corresponds to
7757 a request identifier previously returned by spawn_request() in a
7758 call from current process. That is, only the process that has
7759 made the request can abandon the request.
7760 A spawn request can only be successfully abandoned until the
7762 spawn request has completed. When a spawn request has been suc‐
7763 cessfully abandoned, the caller will not be effected by future
7764 direct effects of the spawn request itself. For example, it will
7765 not receive a spawn reply message. The request is however not
7766 withdrawn, so a new process may or may not be created due to the
7767 request. If a new process is created after the spawn request was
7768 abandoned, no monitors nor links will be set up to the caller of
7769 spawn_request_abandon/1 due to the spawn request. If the spawn
7770 request included the link option, the process created due to
7771 this request will be sent an exit signal from its parent with
7772 the exit reason abandoned when it is detected that the spawn op‐
7773 eration has succeeded.
7774 Note:
7776 A process created due to a spawn request that has been abandoned
7777 may communicate with its parent as any other process. It is only
7778 the direct effects on the parent of the actual spawn request,
7779 that will be canceled by abandoning a spawn request.
7780 Return values:
7783 true:
7785 The spawn request was successfully abandoned.
7786 false:
7788 No spawn request was abandoned. The ReqId request identifier
7789 did not correspond to an outstanding spawn request issued by
7790 the calling process. The reason for this is either:
7791 * ReqId corresponds to a spawn request previoulsy made by
7793 the calling process. The spawn operation has completed and
7794 a spawn reply has already been delivered to the calling
7795 process unless the spawn reply was disabled in the re‐
7796 quest.
7797 * ReqId does not correspond to a spawn request that has been
7799 made by the calling process.
7800 This function fail with a badarg exception if ReqId is not a
7802 reference.
7803 split_binary(Bin, Pos) -> {binary(), binary()}
7805 Types:
7807 Bin = binary()
7809 Pos = integer() >= 0
7810 0..byte_size(Bin)
7811 Returns a tuple containing the binaries that are the result of
7813 splitting Bin into two parts at position Pos. This is not a de‐
7814 structive operation. After the operation, there are three bina‐
7815 ries altogether. Example:
7816 > B = list_to_binary("0123456789").
7818 <<"0123456789">>
7819 > byte_size(B).
7820 10
7821 > {B1, B2} = split_binary(B,3).
7822 {<<"012">>,<<"3456789">>}
7823 > byte_size(B1).
7824 3
7825 > byte_size(B2).
7826 7
7827 erlang:start_timer(Time, Dest, Msg) -> TimerRef
7829 Types:
7831 Time = integer() >= 0
7833 Dest = pid() | atom()
7834 Msg = term()
7835 TimerRef = reference()
7836 Starts a timer. The same as calling erlang:start_timer(Time,
7838 Dest, Msg, []).
7839 erlang:start_timer(Time, Dest, Msg, Options) -> TimerRef
7841 Types:
7843 Time = integer()
7845 Dest = pid() | atom()
7846 Msg = term()
7847 Options = [Option]
7848 Abs = boolean()
7849 Option = {abs, Abs}
7850 TimerRef = reference()
7851 Starts a timer. When the timer expires, the message {timeout,
7853 TimerRef, Msg} is sent to the process identified by Dest.
7854 Options:
7856 {abs, false}:
7858 This is the default. It means the Time value is interpreted
7859 as a time in milliseconds relative current Erlang monotonic
7860 time.
7861 {abs, true}:
7863 Absolute Time value. The Time value is interpreted as an ab‐
7864 solute Erlang monotonic time in milliseconds.
7865 More Options can be added in the future.
7867 The absolute point in time, the timer is set to expire on, must
7869 be in the interval [ erlang:convert_time_unit(erlang:sys‐
7870 tem_info(start_time), native, millisecond), erlang:con‐
7871 vert_time_unit(erlang:system_info(end_time), native, millisec‐
7872 ond) ]. If a relative time is specified, the Time value is not
7873 allowed to be negative.
7874 If Dest is a pid(), it must be a pid() of a process created on
7876 the current runtime system instance. This process has either
7877 terminated or not. If Dest is an atom(), it is interpreted as
7878 the name of a locally registered process. The process referred
7879 to by the name is looked up at the time of timer expiration. No
7880 error is returned if the name does not refer to a process.
7881 If Dest is a pid(), the timer is automatically canceled if the
7883 process referred to by the pid() is not alive, or if the process
7884 exits. This feature was introduced in ERTS 5.4.11. Notice that
7885 timers are not automatically canceled when Dest is an atom().
7886 See also erlang:send_after/4, erlang:cancel_timer/2, and er‐
7888 lang:read_timer/2.
7889 Failure: badarg if the arguments do not satisfy the requirements
7891 specified here.
7892 statistics(Item :: active_tasks) -> [ActiveTasks]
7894 Types:
7896 ActiveTasks = integer() >= 0
7898 Returns the same as statistics(active_tasks_all) with the excep‐
7900 tion that no information about the dirty IO run queue and its
7901 associated schedulers is part of the result. That is, only tasks
7902 that are expected to be CPU bound are part of the result.
7903 statistics(Item :: active_tasks_all) -> [ActiveTasks]
7905 Types:
7907 ActiveTasks = integer() >= 0
7909 Returns a list where each element represents the amount of ac‐
7911 tive processes and ports on each run queue and its associated
7912 schedulers. That is, the number of processes and ports that are
7913 ready to run, or are currently running. Values for normal run
7914 queues and their associated schedulers are located first in the
7915 resulting list. The first element corresponds to scheduler num‐
7916 ber 1 and so on. If support for dirty schedulers exist, an ele‐
7917 ment with the value for the dirty CPU run queue and its associ‐
7918 ated dirty CPU schedulers follow and then as last element the
7919 value for the the dirty IO run queue and its associated dirty IO
7920 schedulers follow. The information is not gathered atomically.
7921 That is, the result is not necessarily a consistent snapshot of
7922 the state, but instead quite efficiently gathered.
7923 Note:
7925 Each normal scheduler has one run queue that it manages. If
7926 dirty schedulers schedulers are supported, all dirty CPU sched‐
7927 ulers share one run queue, and all dirty IO schedulers share one
7928 run queue. That is, we have multiple normal run queues, one
7929 dirty CPU run queue and one dirty IO run queue. Work can not mi‐
7930 grate between the different types of run queues. Only work in
7931 normal run queues can migrate to other normal run queues. This
7932 has to be taken into account when evaluating the result.
7933 See also statistics(total_active_tasks), statis‐
7936 tics(run_queue_lengths), statistics(run_queue_lengths_all), sta‐
7937 tistics(total_run_queue_lengths), and statistics(to‐
7938 tal_run_queue_lengths_all).
7939 statistics(Item :: context_switches) -> {ContextSwitches, 0}
7941 Types:
7943 ContextSwitches = integer() >= 0
7945 Returns the total number of context switches since the system
7947 started.
7948 statistics(Item :: exact_reductions) ->
7950 {Total_Exact_Reductions,
7951 Exact_Reductions_Since_Last_Call}
7952 Types:
7954 Total_Exact_Reductions = Exact_Reductions_Since_Last_Call =
7956 integer() >= 0
7957 Returns the number of exact reductions.
7959 Note:
7961 statistics(exact_reductions) is a more expensive operation than
7962 statistics(reductions).
7963 statistics(Item :: garbage_collection) ->
7966 {Number_of_GCs, Words_Reclaimed, 0}
7967 Types:
7969 Number_of_GCs = Words_Reclaimed = integer() >= 0
7971 Returns information about garbage collection, for example:
7973 > statistics(garbage_collection).
7975 {85,23961,0}
7976 This information can be invalid for some implementations.
7978 statistics(Item :: io) -> {{input, Input}, {output, Output}}
7980 Types:
7982 Input = Output = integer() >= 0
7984 Returns Input, which is the total number of bytes received
7986 through ports, and Output, which is the total number of bytes
7987 output to ports.
7988 statistics(Item :: microstate_accounting) ->
7990 [MSAcc_Thread] | undefined
7991 Types:
7993 MSAcc_Thread =
7995 #{type := MSAcc_Thread_Type,
7996 id := MSAcc_Thread_Id,
7997 counters := MSAcc_Counters}
7998 MSAcc_Thread_Type =
7999 async | aux | dirty_io_scheduler | dirty_cpu_scheduler |
8000 poll | scheduler
8001 MSAcc_Thread_Id = integer() >= 0
8002 MSAcc_Counters = #{MSAcc_Thread_State => integer() >= 0}
8003 MSAcc_Thread_State =
8004 alloc | aux | bif | busy_wait | check_io | emulator | ets
8005 |
8006 gc | gc_fullsweep | nif | other | port | send | sleep |
8007 timers
8008 Microstate accounting can be used to measure how much time the
8010 Erlang runtime system spends doing various tasks. It is designed
8011 to be as lightweight as possible, but some overhead exists when
8012 this is enabled. Microstate accounting is meant to be a profil‐
8013 ing tool to help finding performance bottlenecks. To
8014 start/stop/reset microstate accounting, use system flag mi‐
8015 crostate_accounting.
8016 statistics(microstate_accounting) returns a list of maps repre‐
8018 senting some of the OS threads within ERTS. Each map contains
8019 type and id fields that can be used to identify what thread it
8020 is, and also a counters field that contains data about how much
8021 time has been spent in the various states.
8022 Example:
8024 > erlang:statistics(microstate_accounting).
8026 [#{counters => #{aux => 1899182914,
8027 check_io => 2605863602,
8028 emulator => 45731880463,
8029 gc => 1512206910,
8030 other => 5421338456,
8031 port => 221631,
8032 sleep => 5150294100},
8033 id => 1,
8034 type => scheduler}|...]
8035 The time unit is the same as returned by os:perf_counter/0. So,
8037 to convert it to milliseconds, you can do something like this:
8038 lists:map(
8040 fun(#{ counters := Cnt } = M) ->
8041 MsCnt = maps:map(fun(_K, PerfCount) ->
8042 erlang:convert_time_unit(PerfCount, perf_counter, 1000)
8043 end, Cnt),
8044 M#{ counters := MsCnt }
8045 end, erlang:statistics(microstate_accounting)).
8046 Notice that these values are not guaranteed to be the exact time
8048 spent in each state. This is because of various optimisation
8049 done to keep the overhead as small as possible.
8050 MSAcc_Thread_Types:
8052 scheduler:
8054 The main execution threads that do most of the work. See erl
8055 +S for more details.
8056 dirty_cpu_scheduler:
8058 The threads for long running cpu intensive work. See erl
8059 +SDcpu for more details.
8060 dirty_io_scheduler:
8062 The threads for long running I/O work. See erl +SDio for
8063 more details.
8064 async:
8066 Async threads are used by various linked-in drivers (mainly
8067 the file drivers) do offload non-CPU intensive work. See erl
8068 +A for more details.
8069 aux:
8071 Takes care of any work that is not specifically assigned to
8072 a scheduler.
8073 poll:
8075 Does the IO polling for the emulator. See erl +IOt for more
8076 details.
8077 The following MSAcc_Thread_States are available. All states are
8079 exclusive, meaning that a thread cannot be in two states at
8080 once. So, if you add the numbers of all counters in a thread,
8081 you get the total runtime for that thread.
8082 aux:
8084 Time spent handling auxiliary jobs.
8085 check_io:
8087 Time spent checking for new I/O events.
8088 emulator:
8090 Time spent executing Erlang processes.
8091 gc:
8093 Time spent doing garbage collection. When extra states are
8094 enabled this is the time spent doing non-fullsweep garbage
8095 collections.
8096 other:
8098 Time spent doing unaccounted things.
8099 port:
8101 Time spent executing ports.
8102 sleep:
8104 Time spent sleeping.
8105 More fine-grained MSAcc_Thread_States can be added through con‐
8107 figure (such as ./configure --with-microstate-accounting=extra).
8108 Enabling these states causes performance degradation when mi‐
8109 crostate accounting is turned off and increases the overhead
8110 when it is turned on.
8111 alloc:
8113 Time spent managing memory. Without extra states this time
8114 is spread out over all other states.
8115 bif:
8117 Time spent in BIFs. Without extra states this time is part
8118 of the emulator state.
8119 busy_wait:
8121 Time spent busy waiting. This is also the state where a
8122 scheduler no longer reports that it is active when using
8123 statistics(scheduler_wall_time). So, if you add all other
8124 states but this and sleep, and then divide that by all time
8125 in the thread, you should get something very similar to the
8126 scheduler_wall_time fraction. Without extra states this time
8127 is part of the other state.
8128 ets:
8130 Time spent executing ETS BIFs. Without extra states this
8131 time is part of the emulator state.
8132 gc_full:
8134 Time spent doing fullsweep garbage collection. Without extra
8135 states this time is part of the gc state.
8136 nif:
8138 Time spent in NIFs. Without extra states this time is part
8139 of the emulator state.
8140 send:
8142 Time spent sending messages (processes only). Without extra
8143 states this time is part of the emulator state.
8144 timers:
8146 Time spent managing timers. Without extra states this time
8147 is part of the other state.
8148 The utility module msacc(3) can be used to more easily analyse
8150 these statistics.
8151 Returns undefined if system flag microstate_accounting is turned
8153 off.
8154 The list of thread information is unsorted and can appear in
8156 different order between calls.
8157 Note:
8159 The threads and states are subject to change without any prior
8160 notice.
8161 statistics(Item :: reductions) ->
8164 {Total_Reductions, Reductions_Since_Last_Call}
8165 Types:
8167 Total_Reductions = Reductions_Since_Last_Call = integer() >=
8169 0
8170 Returns information about reductions, for example:
8172 > statistics(reductions).
8174 {2046,11}
8175 Note:
8177 As from ERTS 5.5 (Erlang/OTP R11B), this value does not include
8178 reductions performed in current time slices of currently sched‐
8179 uled processes. If an exact value is wanted, use statistics(ex‐
8180 act_reductions).
8181 statistics(Item :: run_queue) -> integer() >= 0
8184 Returns the total length of all normal and dirty CPU run queues.
8186 That is, queued work that is expected to be CPU bound. The in‐
8187 formation is gathered atomically. That is, the result is a con‐
8188 sistent snapshot of the state, but this operation is much more
8189 expensive compared to statistics(total_run_queue_lengths), espe‐
8190 cially when a large amount of schedulers is used.
8191 statistics(Item :: run_queue_lengths) -> [RunQueueLength]
8193 Types:
8195 RunQueueLength = integer() >= 0
8197 Returns the same as statistics(run_queue_lengths_all) with the
8199 exception that no information about the dirty IO run queue is
8200 part of the result. That is, only run queues with work that is
8201 expected to be CPU bound is part of the result.
8202 statistics(Item :: run_queue_lengths_all) -> [RunQueueLength]
8204 Types:
8206 RunQueueLength = integer() >= 0
8208 Returns a list where each element represents the amount of pro‐
8210 cesses and ports ready to run for each run queue. Values for
8211 normal run queues are located first in the resulting list. The
8212 first element corresponds to the normal run queue of scheduler
8213 number 1 and so on. If support for dirty schedulers exist, val‐
8214 ues for the dirty CPU run queue and the dirty IO run queue fol‐
8215 low (in that order) at the end. The information is not gathered
8216 atomically. That is, the result is not necessarily a consistent
8217 snapshot of the state, but instead quite efficiently gathered.
8218 Note:
8220 Each normal scheduler has one run queue that it manages. If
8221 dirty schedulers schedulers are supported, all dirty CPU sched‐
8222 ulers share one run queue, and all dirty IO schedulers share one
8223 run queue. That is, we have multiple normal run queues, one
8224 dirty CPU run queue and one dirty IO run queue. Work can not mi‐
8225 grate between the different types of run queues. Only work in
8226 normal run queues can migrate to other normal run queues. This
8227 has to be taken into account when evaluating the result.
8228 See also statistics(run_queue_lengths), statistics(to‐
8231 tal_run_queue_lengths_all), statistics(total_run_queue_lengths),
8232 statistics(active_tasks), statistics(active_tasks_all), and sta‐
8233 tistics(total_active_tasks), statistics(total_active_tasks_all).
8234 statistics(Item :: runtime) ->
8236 {Total_Run_Time, Time_Since_Last_Call}
8237 Types:
8239 Total_Run_Time = Time_Since_Last_Call = integer() >= 0
8241 Returns information about runtime, in milliseconds.
8243 This is the sum of the runtime for all threads in the Erlang
8245 runtime system and can therefore be greater than the wall clock
8246 time.
8247 Warning:
8249 This value might wrap due to limitations in the underlying func‐
8250 tionality provided by the operating system that is used.
8251 Example:
8254 > statistics(runtime).
8256 {1690,1620}
8257 statistics(Item :: scheduler_wall_time) ->
8259 [{SchedulerId, ActiveTime, TotalTime}] | undefined
8260 Types:
8262 SchedulerId = integer() >= 1
8264 ActiveTime = TotalTime = integer() >= 0
8265 Returns information describing how much time normal and dirty
8267 CPU schedulers in the system have been busy. This value is nor‐
8268 mally a better indicator of how much load an Erlang node is un‐
8269 der instead of looking at the CPU utilization provided by tools
8270 such as top or sysstat. This is because scheduler_wall_time also
8271 includes time where the scheduler is waiting for some other rea‐
8272 source (such as an internal mutex) to be available but does not
8273 use the CPU. In order to better understand what a scheduler is
8274 busy doing you can use microstate accounting.
8275 The definition of a busy scheduler is when it is not idle and
8277 not busy waiting for new work, that is:
8278 * Executing process code
8280 * Executing linked-in driver or NIF code
8282 * Executing BIFs, or any other runtime handling
8284 * Garbage collecting
8286 * Handling any other memory management
8288 Notice that a scheduler can also be busy even if the OS has
8290 scheduled out the scheduler thread.
8291 Note:
8293 It is recommended to use the module scheduler instead of this
8294 function directly as it provides an easier way to get the infor‐
8295 mation that you usually want.
8296 If enabled this function returns a list of tuples with {Schedu‐
8299 lerId, ActiveTime, TotalTime}, where SchedulerId is an integer
8300 ID of the scheduler, ActiveTime is the duration the scheduler
8301 has been busy, and TotalTime is the total time duration since
8302 scheduler_wall_time activation for the specific scheduler. The
8303 time unit returned is undefined and can be subject to change be‐
8304 tween releases, OSs, and system restarts. scheduler_wall_time is
8305 only to be used to calculate relative values for scheduler uti‐
8306 lization. The ActiveTime can never exceed TotalTime. The list of
8307 scheduler information is unsorted and can appear in different
8308 order between calls.
8309 The disabled this function returns undefined.
8311 The activation time can differ significantly between schedulers.
8313 Currently dirty schedulers are activated at system start while
8314 normal schedulers are activated some time after the sched‐
8315 uler_wall_time functionality is enabled.
8316 Only information about schedulers that are expected to handle
8318 CPU bound work is included in the return values from this func‐
8319 tion. If you also want information about dirty I/O schedulers,
8320 use statistics(scheduler_wall_time_all) instead.
8321 Normal schedulers will have scheduler identifiers in the range 1
8323 =< SchedulerId =< erlang:system_info(schedulers). Dirty CPU
8324 schedulers will have scheduler identifiers in the range er‐
8325 lang:system_info(schedulers) < SchedulerId =< erlang:sys‐
8326 tem_info(schedulers) + erlang:system_info(dirty_cpu_schedulers).
8327 Note:
8329 The different types of schedulers handle specific types of jobs.
8330 Every job is assigned to a specific scheduler type. Jobs can mi‐
8331 grate between different schedulers of the same type, but never
8332 between schedulers of different types. This fact has to be taken
8333 under consideration when evaluating the result returned.
8334 You can use scheduler_wall_time to calculate scheduler utiliza‐
8337 tion. First you take a sample of the values returned by er‐
8338 lang:statistics(scheduler_wall_time).
8339 > erlang:system_flag(scheduler_wall_time, true).
8341 false
8342 > Ts0 = lists:sort(erlang:statistics(scheduler_wall_time)), ok.
8343 ok
8344 Some time later the user takes another snapshot and calculates
8346 scheduler utilization per scheduler, for example:
8347 > Ts1 = lists:sort(erlang:statistics(scheduler_wall_time)), ok.
8349 ok
8350 > lists:map(fun({{I, A0, T0}, {I, A1, T1}}) -> {I, (A1 - A0)/(T1 - T0)} end, lists:zip(Ts0,Ts1)).
8351 [{1,0.9743474730177548},
8352 {2,0.9744843782751444},
8353 {3,0.9995902361669045},
8354 {4,0.9738012596572161},
8355 {5,0.9717956667018103},
8356 {6,0.9739235846420741},
8357 {7,0.973237033077876},
8358 {8,0.9741297293248656}]
8359 Using the same snapshots to calculate a total scheduler utiliza‐
8361 tion:
8362 > {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.
8364 0.9769136803764825
8365 Total scheduler utilization will equal 1.0 when all schedulers
8367 have been active all the time between the two measurements.
8368 Another (probably more) useful value is to calculate total
8370 scheduler utilization weighted against maximum amount of avail‐
8371 able CPU time:
8372 > WeightedSchedulerUtilization = (TotalSchedulerUtilization * (erlang:system_info(schedulers) + erlang:system_info(dirty_cpu_schedulers))) / erlang:system_info(logical_processors_available).
8374 0.9769136803764825
8375 This weighted scheduler utilization will reach 1.0 when sched‐
8377 ulers are active the same amount of time as maximum available
8378 CPU time. If more schedulers exist than available logical pro‐
8379 cessors, this value may be greater than 1.0.
8380 As of ERTS version 9.0, the Erlang runtime system will as de‐
8382 fault have more schedulers than logical processors. This due to
8383 the dirty schedulers.
8384 Note:
8386 scheduler_wall_time is by default disabled. To enable it, use
8387 erlang:system_flag(scheduler_wall_time, true).
8388 statistics(Item :: scheduler_wall_time_all) ->
8391 [{SchedulerId, ActiveTime, TotalTime}] | undefined
8392 Types:
8394 SchedulerId = integer() >= 1
8396 ActiveTime = TotalTime = integer() >= 0
8397 The same as statistics(scheduler_wall_time), except that it also
8399 include information about all dirty I/O schedulers.
8400 Dirty IO schedulers will have scheduler identifiers in the range
8402 erlang:system_info(schedulers) + erlang:sys‐
8403 tem_info(dirty_cpu_schedulers) < SchedulerId =< erlang:sys‐
8404 tem_info(schedulers) + erlang:system_info(dirty_cpu_schedulers)
8405 + erlang:system_info(dirty_io_schedulers).
8406 Note:
8408 Note that work executing on dirty I/O schedulers are expected to
8409 mainly wait for I/O. That is, when you get high scheduler uti‐
8410 lization on dirty I/O schedulers, CPU utilization is not ex‐
8411 pected to be high due to this work.
8412 statistics(Item :: total_active_tasks) -> ActiveTasks
8415 Types:
8417 ActiveTasks = integer() >= 0
8419 The same as calling lists:sum(statistics(active_tasks)), but
8421 more efficient.
8422 statistics(Item :: total_active_tasks_all) -> ActiveTasks
8424 Types:
8426 ActiveTasks = integer() >= 0
8428 The same as calling lists:sum(statistics(active_tasks_all)), but
8430 more efficient.
8431 statistics(Item :: total_run_queue_lengths) ->
8433 TotalRunQueueLengths
8434 Types:
8436 TotalRunQueueLengths = integer() >= 0
8438 The same as calling lists:sum(statistics(run_queue_lengths)),
8440 but more efficient.
8441 statistics(Item :: total_run_queue_lengths_all) ->
8443 TotalRunQueueLengths
8444 Types:
8446 TotalRunQueueLengths = integer() >= 0
8448 The same as calling lists:sum(statis‐
8450 tics(run_queue_lengths_all)), but more efficient.
8451 statistics(Item :: wall_clock) ->
8453 {Total_Wallclock_Time,
8454 Wallclock_Time_Since_Last_Call}
8455 Types:
8457 Total_Wallclock_Time = Wallclock_Time_Since_Last_Call = inte‐
8459 ger() >= 0
8460 Returns information about wall clock. wall_clock can be used in
8462 the same manner as runtime, except that real time is measured as
8463 opposed to runtime or CPU time.
8464 erlang:suspend_process(Suspendee) -> true
8466 Types:
8468 Suspendee = pid()
8470 Suspends the process identified by Suspendee. The same as call‐
8472 ing erlang:suspend_process(Suspendee, []).
8473 Warning:
8475 This BIF is intended for debugging only.
8476 erlang:suspend_process(Suspendee, OptList) -> boolean()
8479 Types:
8481 Suspendee = pid()
8483 OptList = [Opt]
8484 Opt = unless_suspending | asynchronous | {asynchronous,
8485 term()}
8486 Increases the suspend count on the process identified by Sus‐
8488 pendee and puts it in the suspended state if it is not already
8489 in that state. A suspended process is not scheduled for execu‐
8490 tion until the process has been resumed.
8491 A process can be suspended by multiple processes and can be sus‐
8493 pended multiple times by a single process. A suspended process
8494 does not leave the suspended state until its suspend count
8495 reaches zero. The suspend count of Suspendee is decreased when
8496 erlang:resume_process(Suspendee) is called by the same process
8497 that called erlang:suspend_process(Suspendee). All increased
8498 suspend counts on other processes acquired by a process are au‐
8499 tomatically decreased when the process terminates.
8500 Options (Opts):
8502 asynchronous:
8504 A suspend request is sent to the process identified by Sus‐
8505 pendee. Suspendee eventually suspends unless it is resumed
8506 before it could suspend. The caller of erlang:sus‐
8507 pend_process/2 returns immediately, regardless of whether
8508 Suspendee has suspended yet or not. The point in time when
8509 Suspendee suspends cannot be deduced from other events in
8510 the system. It is only guaranteed that Suspendee eventually
8511 suspends (unless it is resumed). If no asynchronous options
8512 has been passed, the caller of erlang:suspend_process/2 is
8513 blocked until Suspendee has suspended.
8514 {asynchronous, ReplyTag}:
8516 A suspend request is sent to the process identified by Sus‐
8517 pendee. When the suspend request has been processed, a reply
8518 message is sent to the caller of this function. The reply is
8519 on the form {ReplyTag, State} where State is either:
8520 exited:
8522 Suspendee has exited.
8523 suspended:
8525 Suspendee is now suspended.
8526 not_suspended:
8528 Suspendee is not suspended. This can only happen when the
8529 process that issued this request, have called re‐
8530 sume_process(Suspendee) before getting the reply.
8531 Apart from the reply message, the {asynchronous, ReplyTag}
8533 option behaves exactly the same as the asynchronous option
8534 without reply tag.
8535 unless_suspending:
8537 The process identified by Suspendee is suspended unless the
8538 calling process already is suspending Suspendee. If un‐
8539 less_suspending is combined with option asynchronous, a sus‐
8540 pend request is sent unless the calling process already is
8541 suspending Suspendee or if a suspend request already has
8542 been sent and is in transit. If the calling process already
8543 is suspending Suspendee, or if combined with option asyn‐
8544 chronous and a send request already is in transit, false is
8545 returned and the suspend count on Suspendee remains un‐
8546 changed.
8547 If the suspend count on the process identified by Suspendee is
8549 increased, true is returned, otherwise false.
8550 Warning:
8552 This BIF is intended for debugging only.
8553 Warning:
8556 You can easily create deadlocks if processes suspends each other
8557 (directly or in circles). In ERTS versions prior to ERTS version
8558 10.0, the runtime system prevented such deadlocks, but this pre‐
8559 vention has now been removed due to performance reasons.
8560 Failures:
8563 badarg:
8565 If Suspendee is not a process identifier.
8566 badarg:
8568 If the process identified by Suspendee is the same process
8569 as the process calling erlang:suspend_process/2.
8570 badarg:
8572 If the process identified by Suspendee is not alive.
8573 badarg:
8575 If the process identified by Suspendee resides on another
8576 node.
8577 badarg:
8579 If OptList is not a proper list of valid Opts.
8580 system_limit:
8582 If the process identified by Suspendee has been suspended
8583 more times by the calling process than can be represented by
8584 the currently used internal data structures. The system
8585 limit is greater than 2,000,000,000 suspends and will never
8586 be lower.
8587 erlang:system_flag(Flag :: backtrace_depth, Depth) -> OldDepth
8589 Types:
8591 Depth = OldDepth = integer() >= 0
8593 Sets the maximum depth of call stack back-traces in the exit
8595 reason element of 'EXIT' tuples. The flag also limits the stack‐
8596 trace depth returned by process_info item current_stacktrace.
8597 Returns the old value of the flag.
8599 erlang:system_flag(Flag :: cpu_topology, CpuTopology) ->
8601 OldCpuTopology
8602 Types:
8604 CpuTopology = OldCpuTopology = cpu_topology()
8606 cpu_topology() = [LevelEntry :: level_entry()] | undefined
8607 level_entry() =
8608 {LevelTag :: level_tag(), SubLevel :: sub_level()} |
8609 {LevelTag :: level_tag(),
8610 InfoList :: info_list(),
8611 SubLevel :: sub_level()}
8612 level_tag() = core | node | processor | thread
8613 sub_level() =
8614 [LevelEntry :: level_entry()] |
8615 (LogicalCpuId :: {logical, integer() >= 0})
8616 info_list() = []
8617 Warning:
8619 This argument is deprecated. Instead of using this argument, use
8620 command-line argument +sct in erl(1).
8621 When this argument is removed, a final CPU topology to use is
8623 determined at emulator boot time.
8624 Sets the user-defined CpuTopology. The user-defined CPU topology
8627 overrides any automatically detected CPU topology. By passing
8628 undefined as CpuTopology, the system reverts to the CPU topology
8629 automatically detected. The returned value equals the value re‐
8630 turned from erlang:system_info(cpu_topology) before the change
8631 was made.
8632 Returns the old value of the flag.
8634 The CPU topology is used when binding schedulers to logical pro‐
8636 cessors. If schedulers are already bound when the CPU topology
8637 is changed, the schedulers are sent a request to rebind accord‐
8638 ing to the new CPU topology.
8639 The user-defined CPU topology can also be set by passing com‐
8641 mand-line argument +sct to erl(1).
8642 For information on type CpuTopology and more, see erlang:sys‐
8644 tem_info(cpu_topology) as well as command-line flags +sct and
8645 +sbt in erl(1).
8646 erlang:system_flag(Flag :: dirty_cpu_schedulers_online,
8648 DirtyCPUSchedulersOnline) ->
8649 OldDirtyCPUSchedulersOnline
8650 Types:
8652 DirtyCPUSchedulersOnline = OldDirtyCPUSchedulersOnline = in‐
8654 teger() >= 1
8655 Sets the number of dirty CPU schedulers online. Range is 1 <=
8657 DirtyCPUSchedulersOnline <= N, where N is the smallest of the
8658 return values of erlang:system_info(dirty_cpu_schedulers) and
8659 erlang:system_info(schedulers_online).
8660 Returns the old value of the flag.
8662 The number of dirty CPU schedulers online can change if the num‐
8664 ber of schedulers online changes. For example, if 12 schedulers
8665 and 6 dirty CPU schedulers are online, and system_flag/2 is used
8666 to set the number of schedulers online to 6, then the number of
8667 dirty CPU schedulers online is automatically decreased by half
8668 as well, down to 3. Similarly, the number of dirty CPU sched‐
8669 ulers online increases proportionally to increases in the number
8670 of schedulers online.
8671 For more information, see erlang:system_info(dirty_cpu_sched‐
8673 ulers) and erlang:system_info(dirty_cpu_schedulers_online).
8674 erlang:system_flag(Flag :: erts_alloc, Value :: {Alloc, F, V}) ->
8676 ok | notsup
8677 Types:
8679 Alloc = F = atom()
8681 V = integer()
8682 Sets system flags for erts_alloc(3). Alloc is the allocator to
8684 affect, for example binary_alloc. F is the flag to change and V
8685 is the new value.
8686 Only a subset of all erts_alloc flags can be changed at run
8688 time. This subset is currently only the flag sbct.
8689 Returns ok if the flag was set or notsup if not supported by
8691 erts_alloc.
8692 erlang:system_flag(Flag :: fullsweep_after, Number) -> OldNumber
8694 Types:
8696 Number = OldNumber = integer() >= 0
8698 Sets system flag fullsweep_after. Number is a non-negative inte‐
8700 ger indicating how many times generational garbage collections
8701 can be done without forcing a fullsweep collection. The value
8702 applies to new processes, while processes already running are
8703 not affected.
8704 Returns the old value of the flag.
8706 In low-memory systems (especially without virtual memory), set‐
8708 ting the value to 0 can help to conserve memory.
8709 This value can also be set through (OS) environment variable
8711 ERL_FULLSWEEP_AFTER.
8712 erlang:system_flag(Flag :: microstate_accounting, Action) ->
8714 OldState
8715 Types:
8717 Action = true | false | reset
8719 OldState = true | false
8720 Turns on/off microstate accounting measurements. When passing
8722 reset, all counters are reset to 0.
8723 For more information see statistics(microstate_accounting).
8725 erlang:system_flag(Flag :: min_heap_size, MinHeapSize) ->
8727 OldMinHeapSize
8728 Types:
8730 MinHeapSize = OldMinHeapSize = integer() >= 0
8732 Sets the default minimum heap size for processes. The size is
8734 specified in words. The new min_heap_size effects only processes
8735 spawned after the change of min_heap_size has been made.
8736 min_heap_size can be set for individual processes by using
8737 spawn_opt/4 or process_flag/2.
8738 Returns the old value of the flag.
8740 erlang:system_flag(Flag :: min_bin_vheap_size, MinBinVHeapSize) ->
8742 OldMinBinVHeapSize
8743 Types:
8745 MinBinVHeapSize = OldMinBinVHeapSize = integer() >= 0
8747 Sets the default minimum binary virtual heap size for processes.
8749 The size is specified in words. The new min_bin_vhheap_size ef‐
8750 fects only processes spawned after the change of
8751 min_bin_vheap_size has been made. min_bin_vheap_size can be set
8752 for individual processes by using spawn_opt/2,3,4 or
8753 process_flag/2.
8754 Returns the old value of the flag.
8756 erlang:system_flag(Flag :: max_heap_size, MaxHeapSize) ->
8758 OldMaxHeapSize
8759 Types:
8761 MaxHeapSize = OldMaxHeapSize = max_heap_size()
8763 max_heap_size() =
8764 integer() >= 0 |
8765 #{size => integer() >= 0,
8766 kill => boolean(),
8767 error_logger => boolean()}
8768 Sets the default maximum heap size settings for processes. The
8770 size is specified in words. The new max_heap_size effects only
8771 processes spawned efter the change has been made. max_heap_size
8772 can be set for individual processes using spawn_opt/2,3,4 or
8773 process_flag/2.
8774 Returns the old value of the flag.
8776 For details on how the heap grows, see Sizing the heap in the
8778 ERTS internal documentation.
8779 erlang:system_flag(Flag :: multi_scheduling, BlockState) ->
8781 OldBlockState
8782 Types:
8784 BlockState = block | unblock | block_normal | unblock_normal
8786 OldBlockState = blocked | disabled | enabled
8787 If multi-scheduling is enabled, more than one scheduler thread
8789 is used by the emulator. Multi-scheduling can be blocked in two
8790 different ways. Either all schedulers but one is blocked, or all
8791 normal schedulers but one is blocked. When only normal sched‐
8792 ulers are blocked, dirty schedulers are free to continue to
8793 schedule processes.
8794 If BlockState =:= block, multi-scheduling is blocked. That is,
8796 one and only one scheduler thread will execute. If BlockState
8797 =:= unblock and no one else blocks multi-scheduling, and this
8798 process has blocked only once, multi-scheduling is unblocked.
8799 If BlockState =:= block_normal, normal multi-scheduling is
8801 blocked. That is, only one normal scheduler thread will execute,
8802 but multiple dirty schedulers can execute. If BlockState =:= un‐
8803 block_normal and no one else blocks normal multi-scheduling, and
8804 this process has blocked only once, normal multi-scheduling is
8805 unblocked.
8806 One process can block multi-scheduling and normal multi-schedul‐
8808 ing multiple times. If a process has blocked multiple times, it
8809 must unblock exactly as many times as it has blocked before it
8810 has released its multi-scheduling block. If a process that has
8811 blocked multi-scheduling or normal multi-scheduling exits, it
8812 automatically releases its blocking of multi-scheduling and nor‐
8813 mal multi-scheduling.
8814 The return values are disabled, blocked, blocked_normal, or en‐
8816 abled. The returned value describes the state just after the
8817 call to erlang:system_flag(multi_scheduling, BlockState) has
8818 been made. For information about the return values, see er‐
8819 lang:system_info(multi_scheduling).
8820 Note:
8822 Blocking of multi-scheduling and normal multi-scheduling is nor‐
8823 mally not needed. If you feel that you need to use these fea‐
8824 tures, consider it a few more times again. Blocking multi-sched‐
8825 uling is only to be used as a last resort, as it is most likely
8826 a very inefficient way to solve the problem.
8827 See also erlang:system_info(multi_scheduling), erlang:sys‐
8830 tem_info(normal_multi_scheduling_blockers), erlang:sys‐
8831 tem_info(multi_scheduling_blockers), and erlang:sys‐
8832 tem_info(schedulers).
8833 erlang:system_flag(Flag :: outstanding_system_requests_limit,
8835 NewLimit) ->
8836 OldLimit
8837 Types:
8839 NewLimit = OldLimit = 1..134217727
8841 Sets a limit on the amount of outstanding requests made by a
8843 system process orchestrating system wide changes. Currently
8844 there are two such processes:
8845 The Code Purger:
8847 The code purger orchestrates checking of references to old
8848 code before old code is removed from the system.
8849 The Literal Area Collector:
8851 The literal area collector orchestrates copying of refer‐
8852 ences from old literal areas before removal of such areas
8853 from the system.
8854 Each of these processes are allowed to have as many outstanding
8856 requests as this limit is set to. By default this limit is set
8857 to twice the amount of schedulers on the system. This will en‐
8858 sure that schedulers will have enough work scheduled to perform
8859 these operations as quickly as possible at the same time as
8860 other work will be interleaved with this work. Currently used
8861 limit can be checked by calling erlang:system_info(outstand‐
8862 ing_system_requests_limit).
8863 This limit can also be set by passing the command line argument
8865 +zosrl <Limit> to erl.
8866 erlang:system_flag(Flag :: scheduler_bind_type, How) ->
8868 OldBindType
8869 Types:
8871 How = scheduler_bind_type() | default_bind
8873 OldBindType = scheduler_bind_type()
8874 scheduler_bind_type() =
8875 no_node_processor_spread | no_node_thread_spread | no_spread |
8876 processor_spread | spread | thread_spread |
8877 thread_no_node_processor_spread | unbound
8878 Warning:
8880 This argument is deprecated. Instead of using this argument, use
8881 command-line argument +sbt in erl(1). When this argument is re‐
8882 moved, a final scheduler bind type to use is determined at emu‐
8883 lator boot time.
8884 Controls if and how schedulers are bound to logical processors.
8887 When erlang:system_flag(scheduler_bind_type, How) is called, an
8889 asynchronous signal is sent to all schedulers online, causing
8890 them to try to bind or unbind as requested.
8891 Note:
8893 If a scheduler fails to bind, this is often silently ignored, as
8894 it is not always possible to verify valid logical processor
8895 identifiers. If an error is reported, an error event is logged.
8896 To verify that the schedulers have bound as requested, call er‐
8897 lang:system_info(scheduler_bindings).
8898 Schedulers can be bound on newer Linux, Solaris, FreeBSD, and
8901 Windows systems, but more systems will be supported in future
8902 releases.
8903 In order for the runtime system to be able to bind schedulers,
8905 the CPU topology must be known. If the runtime system fails to
8906 detect the CPU topology automatically, it can be defined. For
8907 more information on how to define the CPU topology, see command-
8908 line flag +sct in erl(1).
8909 The runtime system does by default not bind schedulers to logi‐
8911 cal processors.
8912 Note:
8914 If the Erlang runtime system is the only OS process binding
8915 threads to logical processors, this improves the performance of
8916 the runtime system. However, if other OS processes (for example,
8917 another Erlang runtime system) also bind threads to logical pro‐
8918 cessors, there can be a performance penalty instead. Sometimes
8919 this performance penalty can be severe. If so, it is recommended
8920 to not bind the schedulers.
8921 Schedulers can be bound in different ways. Argument How deter‐
8924 mines how schedulers are bound and can be any of the following:
8925 unbound:
8927 Same as command-line argument +sbt u in erl(1).
8928 no_spread:
8930 Same as command-line argument +sbt ns in erl(1).
8931 thread_spread:
8933 Same as command-line argument +sbt ts in erl(1).
8934 processor_spread:
8936 Same as command-line argument +sbt ps in erl(1).
8937 spread:
8939 Same as command-line argument +sbt s in erl(1).
8940 no_node_thread_spread:
8942 Same as command-line argument +sbt nnts in erl(1).
8943 no_node_processor_spread:
8945 Same as command-line argument +sbt nnps in erl(1).
8946 thread_no_node_processor_spread:
8948 Same as command-line argument +sbt tnnps in erl(1).
8949 default_bind:
8951 Same as command-line argument +sbt db in erl(1).
8952 The returned value equals How before flag scheduler_bind_type
8954 was changed.
8955 Failures:
8957 notsup:
8959 If binding of schedulers is not supported.
8960 badarg:
8962 If How is not one of the documented alternatives.
8963 badarg:
8965 If CPU topology information is unavailable.
8966 The scheduler bind type can also be set by passing command-line
8968 argument +sbt to erl(1).
8969 For more information, see erlang:system_info(sched‐
8971 uler_bind_type), erlang:system_info(scheduler_bindings), as well
8972 as command-line flags +sbt and +sct in erl(1).
8973 erlang:system_flag(Flag :: scheduler_wall_time, Boolean) ->
8975 OldBoolean
8976 Types:
8978 Boolean = OldBoolean = boolean()
8980 Try enable or disable scheduler wall time measurements by pass‐
8982 ing Boolean as either true or false.
8983 For more information about how to use scheduler wall time mea‐
8985 surements, see statistics(scheduler_wall_time).
8986 Scheduler wall time measurements has a node global state. It is
8988 either enabled for all processes on the node or disabled for all
8989 processes. Each process has a logical counter initialized as
8990 zero. A call with Boolean as true will increase that counter one
8991 step for the calling process. A call with false will decrease it
8992 one step unless it already is zero. The node global state for
8993 scheduler_wall_time will be enabled as long as there is at least
8994 one process alive with a counter value larger than zero. When a
8995 process terminates, its counter will also disappear. To ensure
8996 scheduler_wall_time is kept enabled, the process that enabled it
8997 must therefore be kept alive.
8998 Returns the old value of the node global state, true if sched‐
9000 uler wall time measurements were enabled, false if it were dis‐
9001 abled.
9002 Scheduler wall time measurements do consume some cpu overhead
9004 and should not be left turned on unless used.
9005 erlang:system_flag(Flag :: schedulers_online, SchedulersOnline) ->
9007 OldSchedulersOnline
9008 Types:
9010 SchedulersOnline = OldSchedulersOnline = integer() >= 1
9012 Sets the number of schedulers online. Range is 1 <= Scheduler‐
9014 sOnline <= erlang:system_info(schedulers).
9015 Returns the old value of the flag.
9017 If the emulator was built with support for dirty schedulers,
9019 changing the number of schedulers online can also change the
9020 number of dirty CPU schedulers online. For example, if 12 sched‐
9021 ulers and 6 dirty CPU schedulers are online, and system_flag/2
9022 is used to set the number of schedulers online to 6, then the
9023 number of dirty CPU schedulers online is automatically decreased
9024 by half as well, down to 3. Similarly, the number of dirty CPU
9025 schedulers online increases proportionally to increases in the
9026 number of schedulers online.
9027 For more information, see erlang:system_info(schedulers) and er‐
9029 lang:system_info(schedulers_online).
9030 erlang:system_flag(Flag :: system_logger, Logger) -> PrevLogger
9032 Types:
9034 Logger = PrevLogger = logger | undefined | pid()
9036 Sets the process that will receive the logging messages gener‐
9038 ated by ERTS. If set to undefined, all logging messages gener‐
9039 ated by ERTS will be dropped. The messages will be in the for‐
9040 mat:
9041 {log,Level,Format,ArgList,Metadata} where
9043 Level = atom(),
9045 Format = string(),
9046 ArgList = list(term()),
9047 Metadata = #{ pid => pid(),
9048 group_leader => pid(),
9049 time := logger:timestamp(),
9050 error_logger := #{ emulator := true, tag := atom() }
9051 If the system_logger process dies, this flag will be reset to
9054 logger.
9055 The default is the process named logger.
9057 Returns the old value of the flag.
9059 Note:
9061 This function is designed to be used by the KERNEL logger. Be
9062 careful if you change it to something else as log messages may
9063 be lost. If you want to intercept emulator log messages, do it
9064 by adding a specialized handler to the KERNEL logger.
9065 erlang:system_flag(Flag :: trace_control_word, TCW) -> OldTCW
9068 Types:
9070 TCW = OldTCW = integer() >= 0
9072 Sets the value of the node trace control word to TCW, which is
9074 to be an unsigned integer. For more information, see function
9075 set_tcw in section "Match Specifications in Erlang" in the
9076 User's Guide.
9077 Returns the old value of the flag.
9079 erlang:system_flag(Flag :: time_offset, Value :: finalize) ->
9081 OldState
9082 Types:
9084 OldState = preliminary | final | volatile
9086 Finalizes the time offset when single time warp mode is used. If
9088 another time warp mode is used, the time offset state is left
9089 unchanged.
9090 Returns the old state identifier, that is:
9092 * If preliminary is returned, finalization was performed and
9094 the time offset is now final.
9095 * If final is returned, the time offset was already in the fi‐
9097 nal state. This either because another erlang:sys‐
9098 tem_flag(time_offset, finalize) call or because no time warp
9099 mode is used.
9100 * If volatile is returned, the time offset cannot be finalized
9102 because multi-time warp mode is used.
9103 erlang:system_info(Item :: update_cpu_info) -> changed | unchanged
9105 Returns information about the current system. The documentation
9107 of this function is broken into the following sections in order
9108 to make it easier to navigate.
9109 Memory Allocation:
9111 allocated_areas, allocator, alloc_util_allocators, alloca‐
9112 tor_sizes
9113 CPU Topology:
9115 cpu_topology, logical_processors, update_cpu_info
9116 Process Information:
9118 fullsweep_after, garbage_collection, heap_sizes, heap_type,
9119 max_heap_size, message_queue_data, min_heap_size,
9120 min_bin_vheap_size, procs
9121 System Limits:
9123 atom_count, atom_limit, ets_count, ets_limit, port_count,
9124 port_limit, process_count, process_limit
9125 System Time:
9127 end_time, os_monotonic_time_source, os_system_time_source,
9128 start_time, time_correction, time_offset, time_warp_mode,
9129 tolerant_timeofday
9130 Scheduler Information:
9132 dirty_cpu_schedulers, dirty_cpu_schedulers_online,
9133 dirty_io_schedulers, multi_scheduling, multi_schedul‐
9134 ing_blockers, normal_multi_scheduling_blockers, sched‐
9135 uler_bind_type, scheduler_bindings, scheduler_id, sched‐
9136 ulers, smp_support, threads, thread_pool_size
9137 Distribution Information:
9139 creation, delayed_node_table_gc, dist, dist_buf_busy_limit,
9140 dist_ctrl
9141 System Information:
9143 c_compiler_used, check_io, compat_rel, debug_compiled,
9144 driver_version, dynamic_trace, dynamic_trace_probes,
9145 emu_flavor, emu_type, info, kernel_poll, loaded, machine,
9146 modified_timing_level, nif_version, otp_release, outstand‐
9147 ing_system_requests_limit, port_parallelism, system_archi‐
9148 tecture, system_logger, system_version, trace_control_word,
9149 version, wordsize
9150 erlang:system_info(Item :: allocated_areas) -> [tuple()]
9152 erlang:system_info(Item :: allocator) ->
9154 {Allocator, Version, Features, Settings}
9155 erlang:system_info(Item :: {allocator, Alloc}) -> [term()]
9157 erlang:system_info(Item :: alloc_util_allocators) -> [Alloc]
9159 erlang:system_info(Item :: {allocator_sizes, Alloc}) -> [term()]
9161 Types:
9163 Allocator = undefined | glibc
9165 Version = [integer() >= 0]
9166 Features = [atom()]
9167 Settings =
9168 [{Subsystem :: atom(),
9169 [{Parameter :: atom(), Value :: term()}]}]
9170 Alloc = atom()
9171 Returns various information about the memory allocators of the
9173 current system (emulator) as specified by Item:
9174 allocated_areas:
9176 Returns a list of tuples with information about miscella‐
9177 neous allocated memory areas.
9178 Each tuple contains an atom describing the type of memory as
9180 first element and the amount of allocated memory in bytes as
9181 second element. When information about allocated and used
9182 memory is present, also a third element is present, contain‐
9183 ing the amount of used memory in bytes.
9184 erlang:system_info(allocated_areas) is intended for debug‐
9186 ging, and the content is highly implementation-dependent.
9187 The content of the results therefore changes when needed
9188 without prior notice.
9189 Notice that the sum of these values is not the total amount
9191 of memory allocated by the emulator. Some values are part of
9192 other values, and some memory areas are not part of the re‐
9193 sult. For information about the total amount of memory allo‐
9194 cated by the emulator, see erlang:memory/0,1.
9195 allocator:
9197 Returns {Allocator, Version, Features, Settings, where:
9198 * Allocator corresponds to the malloc() implementation used.
9200 If Allocator equals undefined, the malloc() implementation
9201 used cannot be identified. glibc can be identified.
9202 * Version is a list of integers (but not a string) repre‐
9204 senting the version of the malloc() implementation used.
9205 * Features is a list of atoms representing the allocation
9207 features used.
9208 * Settings is a list of subsystems, their configurable pa‐
9210 rameters, and used values. Settings can differ between
9211 different combinations of platforms, allocators, and allo‐
9212 cation features. Memory sizes are given in bytes.
9213 See also "System Flags Effecting erts_alloc" in erts_al‐
9215 loc(3).
9216 {allocator, Alloc}:
9218 Returns information about the specified allocator. As from
9219 ERTS 5.6.1, the return value is a list of {instance, Instan‐
9220 ceNo, InstanceInfo} tuples, where InstanceInfo contains in‐
9221 formation about a specific instance of the allocator. If Al‐
9222 loc is not a recognized allocator, undefined is returned. If
9223 Alloc is disabled, false is returned.
9224 Notice that the information returned is highly implementa‐
9226 tion-dependent and can be changed or removed at any time
9227 without prior notice. It was initially intended as a tool
9228 when developing new allocators, but as it can be of interest
9229 for others it has been briefly documented.
9230 The recognized allocators are listed in erts_alloc(3). In‐
9232 formation about super carriers can be obtained from ERTS 8.0
9233 with {allocator, erts_mmap} or from ERTS 5.10.4; the re‐
9234 turned list when calling with {allocator, mseg_alloc} also
9235 includes an {erts_mmap, _} tuple as one element in the list.
9236 After reading the erts_alloc(3) documentation, the returned
9238 information more or less speaks for itself, but it can be
9239 worth explaining some things. Call counts are presented by
9240 two values, the first value is giga calls, and the second
9241 value is calls. mbcs and sbcs denote multi-block carriers,
9242 and single-block carriers, respectively. Sizes are presented
9243 in bytes. When a size is not presented, it is the amount of
9244 something. Sizes and amounts are often presented by three
9245 values:
9246 * The first is the current value.
9248 * The second is the maximum value since the last call to er‐
9250 lang:system_info({allocator, Alloc}).
9251 * The third is the maximum value since the emulator was
9253 started.
9254 If only one value is present, it is the current value.
9256 fix_alloc memory block types are presented by two values.
9257 The first value is the memory pool size and the second value
9258 is the used memory size.
9259 alloc_util_allocators:
9261 Returns a list of the names of all allocators using the ERTS
9262 internal alloc_util framework as atoms. For more informa‐
9263 tion, see section The alloc_util framework in erts_alloc(3).
9264 {allocator_sizes, Alloc}:
9266 Returns various size information for the specified alloca‐
9267 tor. The information returned is a subset of the information
9268 returned by erlang:system_info({allocator, Alloc}).
9269 erlang:system_info(Item :: cpu_topology) -> CpuTopology
9271 erlang:system_info(Item ::
9273 {cpu_topology, defined | detected | used}) ->
9274 CpuTopology
9275 erlang:system_info(Item ::
9277 logical_processors |
9278 logical_processors_available |
9279 logical_processors_online) ->
9280 unknown | integer() >= 1
9281 erlang:system_info(Item :: trace_control_word) ->
9283 integer() >= 0
9284 Types:
9286 cpu_topology() = [LevelEntry :: level_entry()] | undefined
9288 All LevelEntrys of a list must contain the same LevelTag,
9289 except on the top level where both node and processor‐
9290 LevelTags can coexist.
9291 level_entry() =
9292 {LevelTag :: level_tag(), SubLevel :: sub_level()} |
9293 {LevelTag :: level_tag(),
9294 InfoList :: info_list(),
9295 SubLevel :: sub_level()}
9296 {LevelTag, SubLevel} == {LevelTag, [], SubLevel}
9297 level_tag() = core | node | processor | thread
9298 More LevelTags can be introduced in a future release.
9299 sub_level() =
9300 [LevelEntry :: level_entry()] |
9301 (LogicalCpuId :: {logical, integer() >= 0})
9302 info_list() = []
9303 The info_list() can be extended in a future release.
9304 Returns various information about the CPU topology of the cur‐
9306 rent system (emulator) as specified by Item:
9307 cpu_topology:
9309 Returns the CpuTopology currently used by the emulator. The
9310 CPU topology is used when binding schedulers to logical pro‐
9311 cessors. The CPU topology used is the user-defined CPU
9312 topology, if such exists, otherwise the automatically de‐
9313 tected CPU topology, if such exists. If no CPU topology ex‐
9314 ists, undefined is returned.
9315 node refers to Non-Uniform Memory Access (NUMA) nodes.
9317 thread refers to hardware threads (for example, Intel hyper-
9318 threads).
9319 A level in term CpuTopology can be omitted if only one entry
9321 exists and InfoList is empty.
9322 thread can only be a sublevel to core. core can be a sub‐
9324 level to processor or node. processor can be on the top
9325 level or a sublevel to node. node can be on the top level or
9326 a sublevel to processor. That is, NUMA nodes can be proces‐
9327 sor internal or processor external. A CPU topology can con‐
9328 sist of a mix of processor internal and external NUMA nodes,
9329 as long as each logical CPU belongs to one NUMA node. Cache
9330 hierarchy is not part of the CpuTopology type, but will be
9331 in a future release. Other things can also make it into the
9332 CPU topology in a future release. So, expect the CpuTopology
9333 type to change.
9334 {cpu_topology, defined}:
9336 Returns the user-defined CpuTopology. For more information,
9339 see command-line flag +sct in erl(1) and argument cpu_topol‐
9340 ogy.
9341 {cpu_topology, detected}:
9343 Returns the automatically detected CpuTopologyy. The emula‐
9346 tor detects the CPU topology on some newer Linux, Solaris,
9347 FreeBSD, and Windows systems. On Windows system with more
9348 than 32 logical processors, the CPU topology is not de‐
9349 tected.
9350 For more information, see argument cpu_topology.
9352 {cpu_topology, used}:
9354 Returns CpuTopology used by the emulator. For more informa‐
9355 tion, see argument cpu_topology.
9356 logical_processors:
9358 Returns the detected number of logical processors configured
9359 in the system. The return value is either an integer, or the
9360 atom unknown if the emulator cannot detect the configured
9361 logical processors.
9362 logical_processors_available:
9364 Returns the detected number of logical processors available
9365 to the Erlang runtime system. The return value is either an
9366 integer, or the atom unknown if the emulator cannot detect
9367 the available logical processors. The number of available
9368 logical processors is less than or equal to the number of
9369 logical processors online.
9370 logical_processors_online:
9372 Returns the detected number of logical processors online on
9373 the system. The return value is either an integer, or the
9374 atom unknown if the emulator cannot detect logical proces‐
9375 sors online. The number of logical processors online is less
9376 than or equal to the number of logical processors config‐
9377 ured.
9378 cpu_quota:
9380 Returns the detected CPU quota the emulator is limited by.
9381 The return value is an integer saying how many processors'
9382 worth of runtime we get (between 1 and the number of logical
9383 processors), or the atom unknown if the emulator cannot de‐
9384 tect a quota.
9385 update_cpu_info:
9387 The runtime system rereads the CPU information available and
9388 updates its internally stored information about the detected
9389 CPU topology and the number of logical processors config‐
9390 ured, online, available, and cpu quota.
9391 If the CPU information has changed since the last time it
9393 was read, the atom changed is returned, otherwise the atom
9394 unchanged. If the CPU information has changed, you probably
9395 want to adjust the number of schedulers online. You typi‐
9396 cally want to have as many schedulers online as logical pro‐
9397 cessors available.
9398 erlang:system_info(Item :: fullsweep_after) ->
9400 {fullsweep_after, integer() >= 0}
9401 erlang:system_info(Item :: garbage_collection) ->
9403 [{atom(), integer()}]
9404 erlang:system_info(Item :: heap_sizes) -> [integer() >= 0]
9406 erlang:system_info(Item :: heap_type) -> private
9408 erlang:system_info(Item :: max_heap_size) ->
9410 {max_heap_size,
9411 MaxHeapSize :: max_heap_size()}
9412 erlang:system_info(Item :: message_queue_data) ->
9414 message_queue_data()
9415 erlang:system_info(Item :: min_heap_size) ->
9417 {min_heap_size,
9418 MinHeapSize :: integer() >= 1}
9419 erlang:system_info(Item :: min_bin_vheap_size) ->
9421 {min_bin_vheap_size,
9422 MinBinVHeapSize :: integer() >= 1}
9423 erlang:system_info(Item :: process_limit) -> integer() >= 1
9425 Types:
9427 message_queue_data() = off_heap | on_heap
9429 max_heap_size() =
9430 integer() >= 0 |
9431 #{size => integer() >= 0,
9432 kill => boolean(),
9433 error_logger => boolean()}
9434 Returns information about the default process heap settings:
9436 fullsweep_after:
9438 Returns {fullsweep_after, integer() >= 0}, which is the
9439 fullsweep_after garbage collection setting used by default.
9440 For more information, see garbage_collection described be‐
9441 low.
9442 garbage_collection:
9444 Returns a list describing the default garbage collection
9445 settings. A process spawned on the local node by a spawn or
9446 spawn_link uses these garbage collection settings. The de‐
9447 fault settings can be changed by using erlang:system_flag/2.
9448 spawn_opt/2,3,4 can spawn a process that does not use the
9449 default settings.
9450 heap_sizes:
9452 Returns a list of integers representing valid heap sizes in
9453 words. All Erlang heaps are sized from sizes in this list.
9454 heap_type:
9456 Returns the heap type used by the current emulator. One heap
9457 type exists:
9458 private:
9460 Each process has a heap reserved for its use and no ref‐
9461 erences between heaps of different processes are allowed.
9462 Messages passed between processes are copied between
9463 heaps.
9464 max_heap_size:
9466 Returns {max_heap_size, MaxHeapSize}, where MaxHeapSize is
9467 the current system-wide maximum heap size settings for
9468 spawned processes. This setting can be set using the com‐
9469 mand-line flags +hmax, +hmaxk and +hmaxel in erl(1). It can
9470 also be changed at runtime using erlang:sys‐
9471 tem_flag(max_heap_size, MaxHeapSize). For more details about
9472 the max_heap_size process flag, see
9473 process_flag(max_heap_size, MaxHeapSize).
9474 message_queue_data:
9476 Returns the default value of the message_queue_data process
9477 flag, which can be either off_heap or on_heap. The default
9478 value is set by the command-line argument +hmqd in erl(1).
9479 For more information, see the documentation of
9480 process_flag(message_queue_data, MQD).
9481 min_heap_size:
9483 Returns {min_heap_size, MinHeapSize}, where MinHeapSize is
9484 the current system-wide minimum heap size for spawned pro‐
9485 cesses.
9486 min_bin_vheap_size:
9488 Returns {min_bin_vheap_size, MinBinVHeapSize}, where MinBin‐
9489 VHeapSize is the current system-wide minimum binary virtual
9490 heap size for spawned processes.
9491 procs:
9493 Returns a binary containing a string of process and port in‐
9494 formation formatted as in Erlang crash dumps. For more in‐
9495 formation, see section How to interpret the Erlang crash
9496 dumps in the User's Guide.
9497 erlang:system_info(Item :: atom_count) -> integer() >= 1
9499 erlang:system_info(Item :: atom_limit) -> integer() >= 1
9501 erlang:system_info(Item :: ets_count) -> integer() >= 1
9503 erlang:system_info(Item :: ets_limit) -> integer() >= 1
9505 erlang:system_info(Item :: port_parallelism) -> boolean()
9507 erlang:system_info(Item :: port_count) -> integer() >= 0
9509 erlang:system_info(Item :: port_limit) -> integer() >= 1
9511 erlang:system_info(Item :: process_count) -> integer() >= 1
9513 Returns information about the current system (emulator) limits
9515 as specified by Item:
9516 atom_count:
9518 Returns the number of atoms currently existing at the local
9519 node. The value is given as an integer.
9520 atom_limit:
9522 Returns the maximum number of atoms allowed. This limit can
9523 be increased at startup by passing command-line flag +t to
9524 erl(1).
9525 ets_count:
9527 Returns the number of ETS tables currently existing at the
9528 local node.
9529 ets_limit:
9531 Returns the limit for number of ETS tables. This limit is
9532 partially obsolete and number of tables are only limited by
9533 available memory.
9534 port_count:
9536 Returns the number of ports currently existing at the local
9537 node. The value is given as an integer. This is the same
9538 value as returned by length(erlang:ports()), but more effi‐
9539 cient.
9540 port_limit:
9542 Returns the maximum number of simultaneously existing ports
9543 at the local node as an integer. This limit can be config‐
9544 ured at startup by using command-line flag +Q in erl(1).
9545 process_count:
9547 Returns the number of processes currently existing at the
9548 local node. The value is given as an integer. This is the
9549 same value as returned by length(processes()), but more ef‐
9550 ficient.
9551 process_limit:
9553 Returns the maximum number of simultaneously existing pro‐
9554 cesses at the local node. The value is given as an integer.
9555 This limit can be configured at startup by using command-
9556 line flag +P in erl(1).
9557 erlang:system_info(Item :: end_time) -> integer() >= 0
9559 erlang:system_info(Item :: os_monotonic_time_source) ->
9561 [{atom(), term()}]
9562 erlang:system_info(Item :: os_system_time_source) ->
9564 [{atom(), term()}]
9565 erlang:system_info(Item :: smp_support) -> boolean()
9567 erlang:system_info(Item :: thread_pool_size) -> integer() >= 0
9569 erlang:system_info(Item :: time_correction) -> true | false
9571 erlang:system_info(Item :: time_offset) ->
9573 preliminary | final | volatile
9574 erlang:system_info(Item :: time_warp_mode) ->
9576 no_time_warp | single_time_warp |
9577 multi_time_warp
9578 Returns information about the current system (emulator) time as
9580 specified by Item:
9581 end_time:
9583 The last Erlang monotonic time in native time unit that can
9584 be represented internally in the current Erlang runtime sys‐
9585 tem instance. The time between the start time and the end
9586 time is at least a quarter of a millennium.
9587 os_monotonic_time_source:
9589 Returns a list containing information about the source of OS
9590 monotonic time that is used by the runtime system.
9591 If [] is returned, no OS monotonic time is available. The
9593 list contains two-tuples with Keys as first element, and
9594 Values as second element. The order of these tuples is unde‐
9595 fined. The following tuples can be part of the list, but
9596 more tuples can be introduced in the future:
9597 {function, Function}:
9599 Function is the name of the function used. This tuple al‐
9600 ways exists if OS monotonic time is available to the run‐
9601 time system.
9602 {clock_id, ClockId}:
9604 This tuple only exists if Function can be used with dif‐
9605 ferent clocks. ClockId corresponds to the clock identifier
9606 used when calling Function.
9607 {resolution, OsMonotonicTimeResolution}:
9609 Highest possible resolution of current OS monotonic time
9610 source as parts per second. If no resolution information
9611 can be retrieved from the OS, OsMonotonicTimeResolution is
9612 set to the resolution of the time unit of Functions return
9613 value. That is, the actual resolution can be lower than
9614 OsMonotonicTimeResolution. Notice that the resolution does
9615 not say anything about the accuracy or whether the pre‐
9616 cision aligns with the resolution. You do, however, know
9617 that the precision is not better than OsMonotonicTimeReso‐
9618 lution.
9619 {extended, Extended}:
9621 Extended equals yes if the range of time values has been
9622 extended; otherwise Extended equals no. The range must be
9623 extended if Function returns values that wrap fast. This
9624 typically is the case when the return value is a 32-bit
9625 value.
9626 {parallel, Parallel}:
9628 Parallel equals yes if Function is called in parallel from
9629 multiple threads. If it is not called in parallel, because
9630 calls must be serialized, Parallel equals no.
9631 {time, OsMonotonicTime}:
9633 OsMonotonicTime equals current OS monotonic time in native
9634 time unit.
9635 os_system_time_source:
9637 Returns a list containing information about the source of OS
9638 system time that is used by the runtime system.
9639 The list contains two-tuples with Keys as first element, and
9641 Values as second element. The order of these tuples is unde‐
9642 fined. The following tuples can be part of the list, but
9643 more tuples can be introduced in the future:
9644 {function, Function}:
9646 Function is the name of the function used.
9647 {clock_id, ClockId}:
9649 Exists only if Function can be used with different clocks.
9650 ClockId corresponds to the clock identifier used when
9651 calling Function.
9652 {resolution, OsSystemTimeResolution}:
9654 Highest possible resolution of current OS system time
9655 source as parts per second. If no resolution information
9656 can be retrieved from the OS, OsSystemTimeResolution is
9657 set to the resolution of the time unit of Functions return
9658 value. That is, the actual resolution can be lower than
9659 OsSystemTimeResolution. Notice that the resolution does
9660 not say anything about the accuracy or whether the pre‐
9661 cision do align with the resolution. You do, however, know
9662 that the precision is not better than OsSystemTimeResolu‐
9663 tion.
9664 {parallel, Parallel}:
9666 Parallel equals yes if Function is called in parallel from
9667 multiple threads. If it is not called in parallel, because
9668 calls needs to be serialized, Parallel equals no.
9669 {time, OsSystemTime}:
9671 OsSystemTime equals current OS system time in native time
9672 unit.
9673 start_time:
9675 The Erlang monotonic time in native time unit at the time
9676 when current Erlang runtime system instance started.
9677 See also erlang:system_info(end_time).
9679 time_correction:
9681 Returns a boolean value indicating whether time correction
9682 is enabled or not.
9683 time_offset:
9685 Returns the state of the time offset:
9686 preliminary:
9688 The time offset is preliminary, and will be changed and
9689 finalized later. The preliminary time offset is used dur‐
9690 ing the preliminary phase of the single time warp mode.
9691 final:
9693 The time offset is final. This either because no time
9694 warp mode is used, or because the time offset have been
9695 finalized when single time warp mode is used.
9696 volatile:
9698 The time offset is volatile. That is, it can change at any
9699 time. This is because multi-time warp mode is used.
9700 time_warp_mode:
9702 Returns a value identifying the time warp mode that is
9703 used:
9704 no_time_warp:
9706 The no time warp mode is used.
9707 single_time_warp:
9709 The single time warp mode is used.
9710 multi_time_warp:
9712 The multi-time warp mode is used.
9713 tolerant_timeofday:
9715 Returns whether a pre ERTS 7.0 backwards compatible compen‐
9716 sation for sudden changes of system time is enabled or dis‐
9717 abled. Such compensation is enabled when the time offset is
9718 final, and time correction is enabled.
9719 erlang:system_info(Item :: dirty_cpu_schedulers) ->
9721 integer() >= 0
9722 erlang:system_info(Item :: dirty_cpu_schedulers_online) ->
9724 integer() >= 0
9725 erlang:system_info(Item :: dirty_io_schedulers) ->
9727 integer() >= 0
9728 erlang:system_info(Item :: multi_scheduling) ->
9730 disabled | blocked | blocked_normal |
9731 enabled
9732 erlang:system_info(Item :: multi_scheduling_blockers) ->
9734 [Pid :: pid()]
9735 erlang:system_info(Item :: normal_multi_scheduling_blockers) ->
9737 [Pid :: pid()]
9738 erlang:system_info(Item :: procs) -> binary()
9740 erlang:system_info(Item :: scheduler_bind_type) ->
9742 spread | processor_spread | thread_spread |
9743 thread_no_node_processor_spread |
9744 no_node_processor_spread |
9745 no_node_thread_spread | no_spread | unbound
9746 erlang:system_info(Item :: scheduler_bindings) -> tuple()
9748 erlang:system_info(Item :: scheduler_id) ->
9750 SchedulerId :: integer() >= 1
9751 erlang:system_info(Item :: schedulers | schedulers_online) ->
9753 integer() >= 1
9754 erlang:system_info(Item :: system_version) -> string()
9756 erlang:system_info(Item :: threads) -> boolean()
9758 Returns information about schedulers, scheduling and threads in
9760 the current system as specified by Item:
9761 dirty_cpu_schedulers:
9763 Returns the number of dirty CPU scheduler threads used by
9764 the emulator. Dirty CPU schedulers execute CPU-bound native
9765 functions, such as NIFs, linked-in driver code, and BIFs
9766 that cannot be managed cleanly by the normal emulator sched‐
9767 ulers.
9768 The number of dirty CPU scheduler threads is determined at
9770 emulator boot time and cannot be changed after that. How‐
9771 ever, the number of dirty CPU scheduler threads online can
9772 be changed at any time. The number of dirty CPU schedulers
9773 can be set at startup by passing command-line flag +SDcpu or
9774 +SDPcpu in erl(1).
9775 See also erlang:system_flag(dirty_cpu_schedulers_online,
9777 DirtyCPUSchedulersOnline), erlang:sys‐
9778 tem_info(dirty_cpu_schedulers_online), erlang:sys‐
9779 tem_info(dirty_io_schedulers), erlang:system_info(sched‐
9780 ulers), erlang:system_info(schedulers_online), and er‐
9781 lang:system_flag(schedulers_online, SchedulersOnline).
9782 dirty_cpu_schedulers_online:
9784 Returns the number of dirty CPU schedulers online. The re‐
9785 turn value satisfies 1 <= DirtyCPUSchedulersOnline <= N,
9786 where N is the smallest of the return values of erlang:sys‐
9787 tem_info(dirty_cpu_schedulers) and erlang:system_info(sched‐
9788 ulers_online).
9789 The number of dirty CPU schedulers online can be set at
9791 startup by passing command-line flag +SDcpu in erl(1).
9792 For more information, see erlang:sys‐
9794 tem_info(dirty_cpu_schedulers), erlang:sys‐
9795 tem_info(dirty_io_schedulers), erlang:system_info(sched‐
9796 ulers_online), and erlang:system_flag(dirty_cpu_sched‐
9797 ulers_online, DirtyCPUSchedulersOnline).
9798 dirty_io_schedulers:
9800 Returns the number of dirty I/O schedulers as an integer.
9801 Dirty I/O schedulers execute I/O-bound native functions,
9802 such as NIFs and linked-in driver code, which cannot be man‐
9803 aged cleanly by the normal emulator schedulers.
9804 This value can be set at startup by passing command-line ar‐
9806 gument +SDio in erl(1).
9807 For more information, see erlang:sys‐
9809 tem_info(dirty_cpu_schedulers), erlang:sys‐
9810 tem_info(dirty_cpu_schedulers_online), and erlang:sys‐
9811 tem_flag(dirty_cpu_schedulers_online, DirtyCPUSchedulersOn‐
9812 line).
9813 multi_scheduling:
9815 Returns one of the following:
9816 disabled:
9818 The emulator has been started with only one scheduler
9819 thread.
9820 blocked:
9822 The emulator has more than one scheduler thread, but all
9823 scheduler threads except one are blocked. That is, only
9824 one scheduler thread schedules Erlang processes and exe‐
9825 cutes Erlang code.
9826 blocked_normal:
9828 The emulator has more than one scheduler thread, but all
9829 normal scheduler threads except one are blocked. Notice
9830 that dirty schedulers are not blocked, and can schedule
9831 Erlang processes and execute native code.
9832 enabled:
9834 The emulator has more than one scheduler thread, and no
9835 scheduler threads are blocked. That is, all available
9836 scheduler threads schedule Erlang processes and execute
9837 Erlang code.
9838 See also erlang:system_flag(multi_scheduling, BlockState),
9840 erlang:system_info(multi_scheduling_blockers), erlang:sys‐
9841 tem_info(normal_multi_scheduling_blockers), and erlang:sys‐
9842 tem_info(schedulers).
9843 multi_scheduling_blockers:
9845 Returns a list of Pids when multi-scheduling is blocked,
9846 otherwise the empty list is returned. The Pids in the list
9847 represent all the processes currently blocking multi-sched‐
9848 uling. A Pid occurs only once in the list, even if the cor‐
9849 responding process has blocked multiple times.
9850 See also erlang:system_flag(multi_scheduling, BlockState),
9852 erlang:system_info(multi_scheduling), erlang:sys‐
9853 tem_info(normal_multi_scheduling_blockers), and erlang:sys‐
9854 tem_info(schedulers).
9855 normal_multi_scheduling_blockers:
9857 Returns a list of Pids when normal multi-scheduling is
9858 blocked (that is, all normal schedulers but one is blocked),
9859 otherwise the empty list is returned. The Pids in the list
9860 represent all the processes currently blocking normal multi-
9861 scheduling. A Pid occurs only once in the list, even if the
9862 corresponding process has blocked multiple times.
9863 See also erlang:system_flag(multi_scheduling, BlockState),
9865 erlang:system_info(multi_scheduling), erlang:sys‐
9866 tem_info(multi_scheduling_blockers), and erlang:sys‐
9867 tem_info(schedulers).
9868 scheduler_bind_type:
9870 Returns information about how the user has requested sched‐
9871 ulers to be bound or not bound.
9872 Notice that although a user has requested schedulers to be
9874 bound, they can silently have failed to bind. To inspect the
9875 scheduler bindings, call erlang:system_info(scheduler_bind‐
9876 ings).
9877 For more information, see command-line argument +sbt in
9879 erl(1) and erlang:system_info(scheduler_bindings).
9880 scheduler_bindings:
9882 Returns information about the currently used scheduler bind‐
9883 ings.
9884 A tuple of a size equal to erlang:system_info(schedulers) is
9886 returned. The tuple elements are integers or the atom un‐
9887 bound. Logical processor identifiers are represented as in‐
9888 tegers. The Nth element of the tuple equals the current
9889 binding for the scheduler with the scheduler identifier
9890 equal to N. For example, if the schedulers are bound, ele‐
9891 ment(erlang:system_info(scheduler_id), erlang:sys‐
9892 tem_info(scheduler_bindings)) returns the identifier of the
9893 logical processor that the calling process is executing on.
9894 Notice that only schedulers online can be bound to logical
9896 processors.
9897 For more information, see command-line argument +sbt in
9899 erl(1) and erlang:system_info(schedulers_online).
9900 scheduler_id:
9902 Returns the scheduler ID (SchedulerId) of the scheduler
9903 thread that the calling process is executing on. SchedulerId
9904 is a positive integer, where 1 <= SchedulerId <= erlang:sys‐
9905 tem_info(schedulers).
9906 See also erlang:system_info(schedulers).
9908 schedulers:
9910 Returns the number of scheduler threads used by the emula‐
9911 tor. Scheduler threads online schedules Erlang processes and
9912 Erlang ports, and execute Erlang code and Erlang linked-in
9913 driver code.
9914 The number of scheduler threads is determined at emulator
9916 boot time and cannot be changed later. However, the number
9917 of schedulers online can be changed at any time.
9918 See also erlang:system_flag(schedulers_online, SchedulersOn‐
9920 line), erlang:system_info(schedulers_online), erlang:sys‐
9921 tem_info(scheduler_id), erlang:system_flag(multi_scheduling,
9922 BlockState), erlang:system_info(multi_scheduling), er‐
9923 lang:system_info(normal_multi_scheduling_blockers) and er‐
9924 lang:system_info(multi_scheduling_blockers).
9925 schedulers_online:
9927 Returns the number of schedulers online. The scheduler iden‐
9928 tifiers of schedulers online satisfy the relationship 1 <=
9929 SchedulerId <= erlang:system_info(schedulers_online).
9930 For more information, see erlang:system_info(schedulers) and
9932 erlang:system_flag(schedulers_online, SchedulersOnline).
9933 smp_support:
9935 Returns true.
9936 threads:
9938 Returns true.
9939 thread_pool_size:
9941 Returns the number of async threads in the async thread pool
9944 used for asynchronous driver calls
9945 (erl_driver:driver_async()). The value is given as an inte‐
9946 ger.
9947 erlang:system_info(Item :: creation) -> integer()
9949 erlang:system_info(Item :: delayed_node_table_gc) ->
9951 infinity | integer() >= 0
9952 erlang:system_info(Item :: dist) -> binary()
9954 erlang:system_info(Item :: dist_buf_busy_limit) ->
9956 integer() >= 0
9957 erlang:system_info(Item :: dist_ctrl) ->
9959 [{Node :: node(),
9960 ControllingEntity :: port() | pid()}]
9961 Returns information about Erlang Distribution in the current
9963 system as specified by Item:
9964 creation:
9966 Returns the creation of the local node as an integer. The
9967 creation is changed when a node is restarted. The creation
9968 of a node is stored in process identifiers, port identi‐
9969 fiers, and references. This makes it (to some extent) possi‐
9970 ble to distinguish between identifiers from different incar‐
9971 nations of a node. The valid creations are integers in the
9972 range 1..3, but this will probably change in a future re‐
9973 lease. If the node is not alive, 0 is returned.
9974 delayed_node_table_gc:
9976 Returns the amount of time in seconds garbage collection of
9977 an entry in a node table is delayed. This limit can be set
9978 on startup by passing command-line flag +zdntgc to erl(1).
9979 For more information, see the documentation of the command-
9980 line flag.
9981 dist:
9983 Returns a binary containing a string of distribution infor‐
9984 mation formatted as in Erlang crash dumps. For more informa‐
9985 tion, see section How to interpret the Erlang crash dumps
9986 in the User's Guide.
9987 dist_buf_busy_limit:
9989 Returns the value of the distribution buffer busy limit in
9990 bytes. This limit can be set at startup by passing command-
9991 line flag +zdbbl to erl(1).
9992 dist_ctrl:
9994 Returns a list of tuples {Node, ControllingEntity}, one en‐
9995 try for each connected remote node. Node is the node name
9996 and ControllingEntity is the port or process identifier re‐
9997 sponsible for the communication to that node. More specifi‐
9998 cally, ControllingEntity for nodes connected through TCP/IP
9999 (the normal case) is the socket used in communication with
10000 the specific node.
10001 erlang:system_info(Item :: c_compiler_used) -> {atom(), term()}
10003 erlang:system_info(Item :: check_io) -> [term()]
10005 erlang:system_info(Item :: compat_rel) -> integer()
10007 erlang:system_info(Item :: debug_compiled) -> boolean()
10009 erlang:system_info(Item :: driver_version) -> string()
10011 erlang:system_info(Item :: dynamic_trace) ->
10013 none | dtrace | systemtap
10014 erlang:system_info(Item :: dynamic_trace_probes) -> boolean()
10016 erlang:system_info(Item :: emu_flavor) -> emu | jit
10018 erlang:system_info(Item :: emu_type) ->
10020 opt | debug | gcov | valgrind | gprof |
10021 lcnt | frmptr
10022 erlang:system_info(Item :: info) -> binary()
10024 erlang:system_info(Item :: kernel_poll) -> boolean()
10026 erlang:system_info(Item :: loaded) -> binary()
10028 erlang:system_info(Item :: machine) -> string()
10030 erlang:system_info(Item :: modified_timing_level) ->
10032 integer() | undefined
10033 erlang:system_info(Item :: nif_version) -> string()
10035 erlang:system_info(Item :: otp_release) -> string()
10037 erlang:system_info(Item :: outstanding_system_requests_limit) ->
10039 1..134217727
10040 erlang:system_info(Item :: port_parallelism) -> boolean()
10042 erlang:system_info(Item :: system_architecture) -> string()
10044 erlang:system_info(Item :: system_logger) ->
10046 logger | undefined | pid()
10047 erlang:system_info(Item :: system_version) -> string()
10049 erlang:system_info(Item :: trace_control_word) ->
10051 integer() >= 0
10052 erlang:system_info(Item :: version) -> string()
10054 erlang:system_info(Item ::
10056 wordsize |
10057 {wordsize, internal} |
10058 {wordsize, external}) ->
10059 4 | 8
10060 Returns various information about the current system (emulator)
10062 as specified by Item:
10063 build_type:
10065 Deprecated, use emu_type instead
10066 c_compiler_used:
10068 Returns a two-tuple describing the C compiler used when com‐
10069 piling the runtime system. The first element is an atom de‐
10070 scribing the name of the compiler, or undefined if unknown.
10071 The second element is a term describing the version of the
10072 compiler, or undefined if unknown.
10073 check_io:
10075 Returns a list containing miscellaneous information about
10076 the emulators internal I/O checking. Notice that the content
10077 of the returned list can vary between platforms and over
10078 time. It is only guaranteed that a list is returned.
10079 compat_rel:
10081 Returns the compatibility mode of the local node as an inte‐
10082 ger. The integer returned represents the Erlang/OTP release
10083 that the current emulator has been set to be backward com‐
10084 patible with. The compatibility mode can be configured at
10085 startup by using command-line flag +R in erl(1).
10086 debug_compiled:
10088 Returns true if the emulator has been debug-compiled, other‐
10089 wise false.
10090 driver_version:
10092 Returns a string containing the Erlang driver version used
10093 by the runtime system. It has the form "<major ver>.<minor
10094 ver>".
10095 dynamic_trace:
10097 Returns an atom describing the dynamic trace framework com‐
10098 piled into the virtual machine. It can be dtrace, systemtap,
10099 or none. For a commercial or standard build, it is always
10100 none. The other return values indicate a custom configura‐
10101 tion (for example, ./configure --with-dynamic-trace=dtrace).
10102 For more information about dynamic tracing, see dyntrace(3)
10103 manual page and the README.dtrace/README.systemtap files in
10104 the Erlang source code top directory.
10105 dynamic_trace_probes:
10107 Returns a boolean() indicating if dynamic trace probes
10108 (dtrace or systemtap) are built into the emulator. This can
10109 only be true if the virtual machine was built for dynamic
10110 tracing (that is, system_info(dynamic_trace) returns dtrace
10111 or systemtap).
10112 emu_flavor:
10114 Returns an atom describing the flavor of the runtime system.
10115 This will be either emu or jit. Possible return values can
10116 be added or removed at any time without prior notice.
10117 emu_type:
10119 Returns an atom describing the build type of the runtime
10120 system. This is normally the atom opt for optimized. Other
10121 possible return values are debug, gcov, valgrind, gprof, and
10122 lcnt. Possible return values can be added or removed at any
10123 time without prior notice.
10124 info:
10126 Returns a binary containing a string of miscellaneous system
10127 information formatted as in Erlang crash dumps. For more in‐
10128 formation, see section How to interpret the Erlang crash
10129 dumps in the User's Guide.
10130 kernel_poll:
10132 Returns true if the emulator uses some kind of kernel-poll
10133 implementation, otherwise false.
10134 loaded:
10136 Returns a binary containing a string of loaded module infor‐
10137 mation formatted as in Erlang crash dumps. For more informa‐
10138 tion, see section How to interpret the Erlang crash dumps in
10139 the User's Guide.
10140 machine:
10142 Returns a string containing the Erlang machine name.
10143 modified_timing_level:
10145 Returns the modified timing-level (an integer) if modified
10146 timing is enabled, otherwise undefined. For more information
10147 about modified timing, see command-line flag +T in erl(1)
10148 nif_version:
10150 Returns a string containing the version of the Erlang NIF
10151 interface used by the runtime system. It is on the form
10152 "<major ver>.<minor ver>".
10153 otp_release:
10155 Returns a string containing the OTP release number of the
10158 OTP release that the currently executing ERTS application is
10159 part of.
10160 As from Erlang/OTP 17, the OTP release number corresponds to
10162 the major OTP version number. No erlang:system_info() argu‐
10163 ment gives the exact OTP version. This is because the exact
10164 OTP version in the general case is difficult to determine.
10165 For more information, see the description of versions in
10166 System principles in System Documentation.
10167 outstanding_system_requests_limit:
10169 Returns the limit on the amount of outstanding requests made
10170 by a system process orchestrating system wide changes. See
10171 erlang:system_flag(outstanding_system_requests_limit, Limit)
10172 for more information.
10173 port_parallelism:
10175 Returns the default port parallelism scheduling hint used.
10176 For more information, see command-line argument +spp in
10177 erl(1).
10178 system_architecture:
10180 Returns a string containing the processor and OS architec‐
10181 ture the emulator is built for.
10182 system_logger:
10184 Returns the current system_logger as set by erlang:sys‐
10185 tem_flag(system_logger, _).
10186 system_version:
10188 Returns a string containing version number and some impor‐
10189 tant properties, such as the number of schedulers.
10190 trace_control_word:
10192 Returns the value of the node trace control word. For more
10193 information, see function get_tcw in section Match Specifi‐
10194 cations in Erlang in the User's Guide.
10195 version:
10197 Returns a string containing the version number of the emula‐
10198 tor.
10199 wordsize:
10201 Same as {wordsize, internal}.
10202 {wordsize, internal}:
10204 Returns the size of Erlang term words in bytes as an inte‐
10205 ger, that is, 4 is returned on a 32-bit architecture, and 8
10206 is returned on a 64-bit architecture.
10207 {wordsize, external}:
10209 Returns the true word size of the emulator, that is, the
10210 size of a pointer. The value is given in bytes as an inte‐
10211 ger. On a pure 32-bit architecture, 4 is returned. On a
10212 64-bit architecture, 8 is returned.
10213 erlang:system_monitor() -> MonSettings
10215 Types:
10217 MonSettings = undefined | {MonitorPid, Options}
10219 MonitorPid = pid()
10220 Options = [system_monitor_option()]
10221 system_monitor_option() =
10222 busy_port | busy_dist_port |
10223 {long_gc, integer() >= 0} |
10224 {long_schedule, integer() >= 0} |
10225 {large_heap, integer() >= 0}
10226 Returns the current system monitoring settings set by er‐
10228 lang:system_monitor/2 as {MonitorPid, Options}, or undefined if
10229 no settings exist. The order of the options can be different
10230 from the one that was set.
10231 erlang:system_monitor(Arg) -> MonSettings
10233 Types:
10235 Arg = MonSettings = undefined | {MonitorPid, Options}
10237 MonitorPid = pid()
10238 Options = [system_monitor_option()]
10239 system_monitor_option() =
10240 busy_port | busy_dist_port |
10241 {long_gc, integer() >= 0} |
10242 {long_schedule, integer() >= 0} |
10243 {large_heap, integer() >= 0}
10244 When called with argument undefined, all system performance mon‐
10246 itoring settings are cleared.
10247 Calling the function with {MonitorPid, Options} as argument is
10249 the same as calling erlang:system_monitor(MonitorPid, Options).
10250 Returns the previous system monitor settings just like er‐
10252 lang:system_monitor/0.
10253 erlang:system_monitor(MonitorPid, Options) -> MonSettings
10255 Types:
10257 MonitorPid = pid()
10259 Options = [system_monitor_option()]
10260 MonSettings = undefined | {OldMonitorPid, OldOptions}
10261 OldMonitorPid = pid()
10262 OldOptions = [system_monitor_option()]
10263 system_monitor_option() =
10264 busy_port | busy_dist_port |
10265 {long_gc, integer() >= 0} |
10266 {long_schedule, integer() >= 0} |
10267 {large_heap, integer() >= 0}
10268 Sets the system performance monitoring options. MonitorPid is a
10270 local process identifier (pid) receiving system monitor mes‐
10271 sages. The second argument is a list of monitoring options:
10272 {long_gc, Time}:
10274 If a garbage collection in the system takes at least Time
10275 wall clock milliseconds, a message {monitor, GcPid, long_gc,
10276 Info} is sent to MonitorPid. GcPid is the pid that was
10277 garbage collected. Info is a list of two-element tuples de‐
10278 scribing the result of the garbage collection.
10279 One of the tuples is {timeout, GcTime}, where GcTime is the
10281 time for the garbage collection in milliseconds. The other
10282 tuples are tagged with heap_size, heap_block_size,
10283 stack_size, mbuf_size, old_heap_size, and
10284 old_heap_block_size. These tuples are explained in the de‐
10285 scription of trace message gc_minor_start (see er‐
10286 lang:trace/3). New tuples can be added, and the order of the
10287 tuples in the Info list can be changed at any time without
10288 prior notice.
10289 {long_schedule, Time}:
10291 If a process or port in the system runs uninterrupted for at
10292 least Time wall clock milliseconds, a message {monitor, Pi‐
10293 dOrPort, long_schedule, Info} is sent to MonitorPid. PidOr‐
10294 Port is the process or port that was running. Info is a list
10295 of two-element tuples describing the event.
10296 If a pid(), the tuples {timeout, Millis}, {in, Location},
10298 and {out, Location} are present, where Location is either an
10299 MFA ({Module, Function, Arity}) describing the function
10300 where the process was scheduled in/out, or the atom unde‐
10301 fined.
10302 If a port(), the tuples {timeout, Millis} and {port_op,Op}
10304 are present. Op is one of proc_sig, timeout, input, output,
10305 event, or dist_cmd, depending on which driver callback was
10306 executing.
10307 proc_sig is an internal operation and is never to appear,
10309 while the others represent the corresponding driver call‐
10310 backs timeout, ready_input, ready_output, event, and outputv
10311 (when the port is used by distribution). Value Millis in tu‐
10312 ple timeout informs about the uninterrupted execution time
10313 of the process or port, which always is equal to or higher
10314 than the Time value supplied when starting the trace. New
10315 tuples can be added to the Info list in a future release.
10316 The order of the tuples in the list can be changed at any
10317 time without prior notice.
10318 This can be used to detect problems with NIFs or drivers
10320 that take too long to execute. 1 ms is considered a good
10321 maximum time for a driver callback or a NIF. However, a
10322 time-sharing system is usually to consider everything < 100
10323 ms as "possible" and fairly "normal". However, longer sched‐
10324 ule times can indicate swapping or a misbehaving NIF/driver.
10325 Misbehaving NIFs and drivers can cause bad resource utiliza‐
10326 tion and bad overall system performance.
10327 {large_heap, Size}:
10329 If a garbage collection in the system results in the allo‐
10330 cated size of a heap being at least Size words, a message
10331 {monitor, GcPid, large_heap, Info} is sent to MonitorPid.
10332 GcPid and Info are the same as for long_gc earlier, except
10333 that the tuple tagged with timeout is not present.
10334 The monitor message is sent if the sum of the sizes of all
10336 memory blocks allocated for all heap generations after a
10337 garbage collection is equal to or higher than Size.
10338 When a process is killed by max_heap_size, it is killed be‐
10340 fore the garbage collection is complete and thus no large
10341 heap message is sent.
10342 busy_port:
10344 If a process in the system gets suspended because it sends
10345 to a busy port, a message {monitor, SusPid, busy_port, Port}
10346 is sent to MonitorPid. SusPid is the pid that got suspended
10347 when sending to Port.
10348 busy_dist_port:
10350 If a process in the system gets suspended because it sends
10351 to a process on a remote node whose inter-node communication
10352 was handled by a busy port, a message {monitor, SusPid,
10353 busy_dist_port, Port} is sent to MonitorPid. SusPid is the
10354 pid that got suspended when sending through the inter-node
10355 communication port Port.
10356 Returns the previous system monitor settings just like er‐
10358 lang:system_monitor/0.
10359 The arguments to system_monitor/2 specifies how all system moni‐
10361 toring on the node should be done, not how it should be changed.
10362 This means only one process at a time (MonitorPid) can be the
10363 receiver of system monitor messages. Also, the way to clear a
10364 specific monitor option is to not include it in the list Op‐
10365 tions. All system monitoring will, however, be cleared if the
10366 process identified by MonitorPid terminates.
10367 There are no special option values (like zero) to clear an op‐
10369 tion. Some of the options have a unspecified minimum value.
10370 Lower values will be adjusted to the minimum value. For example,
10371 it is currently not possible to monitor all garbage collections
10372 with {long_gc, 0}.
10373 Note:
10375 If a monitoring process gets so large that it itself starts to
10376 cause system monitor messages when garbage collecting, the mes‐
10377 sages enlarge the process message queue and probably make the
10378 problem worse.
10379 Keep the monitoring process neat and do not set the system moni‐
10381 tor limits too tight.
10382 Failures:
10385 badarg:
10387 If MonitorPid does not exist.
10388 badarg:
10390 If MonitorPid is not a local process.
10391 erlang:system_profile() -> ProfilerSettings
10393 Types:
10395 ProfilerSettings = undefined | {ProfilerPid, Options}
10397 ProfilerPid = pid() | port()
10398 Options = [system_profile_option()]
10399 system_profile_option() =
10400 exclusive | runnable_ports | runnable_procs | scheduler |
10401 timestamp | monotonic_timestamp | strict_monotonic_timestamp
10402 Returns the current system profiling settings set by erlang:sys‐
10404 tem_profile/2 as {ProfilerPid, Options}, or undefined if there
10405 are no settings. The order of the options can be different from
10406 the one that was set.
10407 erlang:system_profile(ProfilerPid, Options) -> ProfilerSettings
10409 Types:
10411 ProfilerPid = pid() | port() | undefined
10413 Options = [system_profile_option()]
10414 ProfilerSettings =
10415 undefined | {pid() | port(), [system_profile_option()]}
10416 system_profile_option() =
10417 exclusive | runnable_ports | runnable_procs | scheduler |
10418 timestamp | monotonic_timestamp | strict_monotonic_timestamp
10419 Sets system profiler options. ProfilerPid is a local process
10421 identifier (pid) or port receiving profiling messages. The re‐
10422 ceiver is excluded from all profiling. The second argument is a
10423 list of profiling options:
10424 exclusive:
10426 If a synchronous call to a port from a process is done, the
10427 calling process is considered not runnable during the call
10428 runtime to the port. The calling process is notified as in‐
10429 active, and later active when the port callback returns.
10430 monotonic_timestamp:
10432 Time stamps in profile messages use Erlang monotonic time.
10433 The time stamp (Ts) has the same format and value as pro‐
10434 duced by erlang:monotonic_time(nanosecond).
10435 runnable_procs:
10437 If a process is put into or removed from the run queue, a
10438 message, {profile, Pid, State, Mfa, Ts}, is sent to Profil‐
10439 erPid. Running processes that are reinserted into the run
10440 queue after having been pre-empted do not trigger this mes‐
10441 sage.
10442 runnable_ports:
10444 If a port is put into or removed from the run queue, a mes‐
10445 sage, {profile, Port, State, 0, Ts}, is sent to ProfilerPid.
10446 scheduler:
10448 If a scheduler is put to sleep or awoken, a message, {pro‐
10449 file, scheduler, Id, State, NoScheds, Ts}, is sent to Pro‐
10450 filerPid.
10451 strict_monotonic_timestamp:
10453 Time stamps in profile messages consist of Erlang monotonic
10454 time and a monotonically increasing integer. The time stamp
10455 (Ts) has the same format and value as produced by {er‐
10456 lang:monotonic_time(nanosecond), erlang:unique_inte‐
10457 ger([monotonic])}.
10458 timestamp:
10460 Time stamps in profile messages include a time stamp (Ts)
10461 that has the same form as returned by erlang:now(). This is
10462 also the default if no time stamp flag is specified. If
10463 cpu_timestamp has been enabled through erlang:trace/3, this
10464 also effects the time stamp produced in profiling messages
10465 when flag timestamp is enabled.
10466 Note:
10468 erlang:system_profile behavior can change in a future release.
10469 erlang:system_time() -> integer()
10472 Returns current Erlang system time in native time unit.
10474 Calling erlang:system_time() is equivalent to erlang:mono‐
10476 tonic_time() + erlang:time_offset().
10477 Note:
10479 This time is not a monotonically increasing time in the general
10480 case. For more information, see the documentation of time warp
10481 modes in the User's Guide.
10482 erlang:system_time(Unit) -> integer()
10485 Types:
10487 Unit = time_unit()
10489 Returns current Erlang system time converted into the Unit
10491 passed as argument.
10492 Calling erlang:system_time(Unit) is equivalent to erlang:con‐
10494 vert_time_unit(erlang:system_time(), native, Unit).
10495 Note:
10497 This time is not a monotonically increasing time in the general
10498 case. For more information, see the documentation of time warp
10499 modes in the User's Guide.
10500 term_to_binary(Term) -> ext_binary()
10503 Types:
10505 Term = term()
10507 Returns a binary data object that is the result of encoding Term
10509 according to the Erlang external term format.
10510 This can be used for various purposes, for example, writing a
10512 term to a file in an efficient way, or sending an Erlang term to
10513 some type of communications channel not supported by distributed
10514 Erlang.
10515 > Bin = term_to_binary(hello).
10517 <<131,100,0,5,104,101,108,108,111>>
10518 > hello = binary_to_term(Bin).
10519 hello
10520 See also binary_to_term/1.
10523 Note:
10525 There is no guarantee that this function will return the same
10526 encoded representation for the same term.
10527 term_to_binary(Term, Options) -> ext_binary()
10530 Types:
10532 Term = term()
10534 Options =
10535 [compressed |
10536 {compressed, Level :: 0..9} |
10537 deterministic |
10538 {minor_version, Version :: 0..2}]
10539 Returns a binary data object that is the result of encoding Term
10541 according to the Erlang external term format.
10542 If option compressed is provided, the external term format is
10544 compressed. The compressed format is automatically recognized by
10545 binary_to_term/1 as from Erlang/OTP R7B.
10546 A compression level can be specified by giving option {com‐
10548 pressed, Level}. Level is an integer with range 0..9, where:
10549 * 0 - No compression is done (it is the same as giving no com‐
10551 pressed option).
10552 * 1 - Takes least time but may not compress as well as the
10554 higher levels.
10555 * 6 - Default level when option compressed is provided.
10557 * 9 - Takes most time and tries to produce a smaller result.
10559 Notice "tries" in the preceding sentence; depending on the
10560 input term, level 9 compression either does or does not pro‐
10561 duce a smaller result than level 1 compression.
10562 Option {minor_version, Version} can be used to control some en‐
10564 coding details. This option was introduced in Erlang/OTP R11B-4.
10565 The valid values for Version are:
10566 0:
10568 Floats are encoded using a textual representation. This op‐
10569 tion is useful to ensure that releases before Erlang/OTP
10570 R11B-4 can decode resulting binary.
10571 This version encode atoms that can be represented by a
10573 latin1 string using latin1 encoding while only atoms that
10574 cannot be represented by latin1 are encoded using utf8.
10575 1:
10577 This is as of Erlang/OTP 17.0 the default. It forces any
10578 floats in the term to be encoded in a more space-efficient
10579 and exact way (namely in the 64-bit IEEE format, rather than
10580 converted to a textual representation). As from Erlang/OTP
10581 R11B-4, binary_to_term/1 can decode this representation.
10582 This version encode atoms that can be represented by a
10584 latin1 string using latin1 encoding while only atoms that
10585 cannot be represented by latin1 are encoded using utf8.
10586 2:
10588 Drops usage of the latin1 atom encoding and unconditionally
10589 use utf8 encoding for all atoms. Erlang/OTP systems as of
10590 R16B can decode this representation.
10591 Note:
10593 In Erlang/OTP 26, the default minor_version is planned to
10594 change from 1 to 2. See Upcoming Potential Incompatibilities
10595 .
10596 Option deterministic (introduced in OTP 24.1) can be used to en‐
10599 sure that within the same major release of Erlang/OTP, the same
10600 encoded representation is returned for the same term. There is
10601 still no guarantee that the encoded representation remains the
10602 same between major releases of Erlang/OTP.
10603 See also binary_to_term/1.
10605 term_to_iovec(Term) -> ext_iovec()
10607 Types:
10609 Term = term()
10611 Returns the encoding of Term according to the Erlang external
10613 term format as ext_iovec().
10614 This function produce the same encoding as term_to_binary/1, but
10616 with another return type. The call iolist_to_bi‐
10617 nary(term_to_iovec(Term)) will produce exactly the same result
10618 as the call term_to_binary(Term).
10619 term_to_iovec() is a pure optimization of the functionality
10621 term_to_binary() provide. term_to_iovec() can for example refer
10622 directly to off heap binaries instead of copying the binary data
10623 into the result.
10624 See also term_to_binary/1.
10626 term_to_iovec(Term, Options) -> ext_iovec()
10628 Types:
10630 Term = term()
10632 Options =
10633 [compressed |
10634 {compressed, Level :: 0..9} |
10635 deterministic |
10636 {minor_version, Version :: 0..2}]
10637 Returns the encoding of Term according to the Erlang external
10639 term format as ext_iovec().
10640 This function produce the same encoding as term_to_binary/2, but
10642 with another return type. The call iolist_to_bi‐
10643 nary(term_to_iovec(Term, Opts)) will produce exactly the same
10644 result as term_to_binary(Term, Opts).
10645 Currently recognised options are all options recognised by
10647 term_to_binary/2.
10648 term_to_iovec() is a pure optimization of the functionality
10650 term_to_binary() provide. term_to_iovec() can for example refer
10651 directly to off heap binaries instead of copying the binary data
10652 into the result.
10653 See also term_to_binary/2.
10655 throw(Any) -> no_return()
10657 Types:
10659 Any = term()
10661 Raises an exception of class throw. Intended to be used to do
10663 non-local returns from functions.
10664 If evaluated within a catch expression, the catch expression
10666 returns value Any. Example:
10667 > catch throw({hello, there}).
10669 {hello,there}
10670 If evaluated within a try-block of a try expression, the value
10672 Any can be caught within the catch block. Example:
10673 try
10675 throw({my_exception, "Something happened"})
10676 catch
10677 throw:{my_exception, Desc} ->
10678 io:format(standard_error, "Error: ~s~n", [Desc])
10679 end
10680 Failure: nocatch if not caught by an exception handler.
10682 See the guide about errors and error handling for additional in‐
10684 formation.
10685 time() -> Time
10687 Types:
10689 Time = calendar:time()
10691 Returns the current time as {Hour, Minute, Second}.
10693 The time zone and Daylight Saving Time correction depend on the
10695 underlying OS. The return value is based on the OS System Time.
10696 Example:
10697 > time().
10699 {9,42,44}
10700 erlang:time_offset() -> integer()
10702 Returns the current time offset between Erlang monotonic time
10704 and Erlang system time in native time unit. Current time offset
10705 added to an Erlang monotonic time gives corresponding Erlang
10706 system time.
10707 The time offset may or may not change during operation depending
10709 on the time warp mode used.
10710 Note:
10712 A change in time offset can be observed at slightly different
10713 points in time by different processes.
10714 If the runtime system is in multi-time warp mode, the time off‐
10716 set is changed when the runtime system detects that the OS sys‐
10717 tem time has changed. The runtime system will, however, not de‐
10718 tect this immediately when it occurs. A task checking the time
10719 offset is scheduled to execute at least once a minute; so, under
10720 normal operation this is to be detected within a minute, but
10721 during heavy load it can take longer time.
10722 erlang:time_offset(Unit) -> integer()
10725 Types:
10727 Unit = time_unit()
10729 Returns the current time offset between Erlang monotonic time
10731 and Erlang system time converted into the Unit passed as argu‐
10732 ment.
10733 Same as calling erlang:convert_time_unit(erlang:time_offset(),
10735 native, Unit) however optimized for commonly used Units.
10736 erlang:timestamp() -> Timestamp
10738 Types:
10740 Timestamp = timestamp()
10742 timestamp() =
10743 {MegaSecs :: integer() >= 0,
10744 Secs :: integer() >= 0,
10745 MicroSecs :: integer() >= 0}
10746 Returns current Erlang system time on the format {MegaSecs,
10748 Secs, MicroSecs}. This format is the same as os:timestamp/0 and
10749 the deprecated erlang:now/0 use. The reason for the existence of
10750 erlang:timestamp() is purely to simplify use for existing code
10751 that assumes this time stamp format. Current Erlang system time
10752 can more efficiently be retrieved in the time unit of your
10753 choice using erlang:system_time/1.
10754 The erlang:timestamp() BIF is equivalent to:
10756 timestamp() ->
10758 ErlangSystemTime = erlang:system_time(microsecond),
10759 MegaSecs = ErlangSystemTime div 1000_000_000_000,
10760 Secs = ErlangSystemTime div 1000_000 - MegaSecs*1000_000,
10761 MicroSecs = ErlangSystemTime rem 1000_000,
10762 {MegaSecs, Secs, MicroSecs}.
10763 It, however, uses a native implementation that does not build
10765 garbage on the heap and with slightly better performance.
10766 Note:
10768 This time is not a monotonically increasing time in the general
10769 case. For more information, see the documentation of time warp
10770 modes in the User's Guide.
10771 tl(List) -> term()
10774 Types:
10776 List = nonempty_maybe_improper_list()
10778 Returns the tail of List, that is, the list minus the first ele‐
10780 ment, for example:
10781 > tl([geesties, guilies, beasties]).
10783 [guilies, beasties]
10784 > tl([geesties]).
10786 []
10787 > tl([geesties, guilies, beasties | improper_end]).
10789 [guilies, beasties | improper_end]
10790 > tl([geesties | improper_end]).
10792 improper_end
10793 Allowed in guard tests.
10795 Failure: badarg if List is the empty list [].
10797 erlang:trace(PidPortSpec, How, FlagList) -> integer()
10799 Types:
10801 PidPortSpec =
10803 pid() |
10804 port() |
10805 all | processes | ports | existing | existing_processes |
10806 existing_ports | new | new_processes | new_ports
10807 How = boolean()
10808 FlagList = [trace_flag()]
10809 trace_flag() =
10810 all | send | 'receive' | procs | ports | call | arity |
10811 return_to | silent | running | exiting | running_procs |
10812 running_ports | garbage_collection | timestamp |
10813 cpu_timestamp | monotonic_timestamp |
10814 strict_monotonic_timestamp | set_on_spawn |
10815 set_on_first_spawn | set_on_link | set_on_first_link |
10816 {tracer, pid() | port()} |
10817 {tracer, module(), term()}
10818 Turns on (if How == true) or off (if How == false) the trace
10820 flags in FlagList for the process or processes represented by
10821 PidPortSpec.
10822 PidPortSpec is either a process identifier (pid) for a local
10824 process, a port identifier, or one of the following atoms:
10825 all:
10827 All currently existing processes and ports and all that will
10828 be created in the future.
10829 processes:
10831 All currently existing processes and all that will be cre‐
10832 ated in the future.
10833 ports:
10835 All currently existing ports and all that will be created in
10836 the future.
10837 existing:
10839 All currently existing processes and ports.
10840 existing_processes:
10842 All currently existing processes.
10843 existing_ports:
10845 All currently existing ports.
10846 new:
10848 All processes and ports that will be created in the future.
10849 new_processes:
10851 All processes that will be created in the future.
10852 new_ports:
10854 All ports that will be created in the future.
10855 FlagList can contain any number of the following flags (the
10857 "message tags" refers to the list of trace messages):
10858 all:
10860 Sets all trace flags except tracer and cpu_timestamp, which
10861 are in their nature different than the others.
10862 send:
10864 Traces sending of messages.
10865 Message tags: send and send_to_non_existing_process.
10867 'receive':
10869 Traces receiving of messages.
10870 Message tags: 'receive'.
10872 call:
10874 Traces certain function calls. Specify which function calls
10875 to trace by calling erlang:trace_pattern/3.
10876 Message tags: call and return_from.
10878 silent:
10880 Used with the call trace flag. The call, return_from, and
10881 return_to trace messages are inhibited if this flag is set,
10882 but they are executed as normal if there are match specifi‐
10883 cations.
10884 Silent mode is inhibited by executing erlang:trace(_, false,
10886 [silent|_]), or by a match specification executing the func‐
10887 tion {silent, false}.
10888 The silent trace flag facilitates setting up a trace on many
10890 or even all processes in the system. The trace can then be
10891 activated and deactivated using the match specification
10892 function {silent,Bool}, giving a high degree of control of
10893 which functions with which arguments that trigger the trace.
10894 Message tags: call, return_from, and return_to. Or rather,
10896 the absence of.
10897 return_to:
10899 Used with the call trace flag. Traces the return from a
10900 traced function back to its caller. Only works for functions
10901 traced with option local to erlang:trace_pattern/3.
10902 The semantics is that a trace message is sent when a call
10904 traced function returns, that is, when a chain of tail re‐
10905 cursive calls ends. Only one trace message is sent per chain
10906 of tail recursive calls, so the properties of tail recur‐
10907 siveness for function calls are kept while tracing with this
10908 flag. Using call and return_to trace together makes it pos‐
10909 sible to know exactly in which function a process executes
10910 at any time.
10911 To get trace messages containing return values from func‐
10913 tions, use the {return_trace} match specification action in‐
10914 stead.
10915 Message tags: return_to.
10917 procs:
10919 Traces process-related events.
10920 Message tags: spawn, spawned, exit, register, unregister,
10922 link, unlink, getting_linked, and getting_unlinked.
10923 ports:
10925 Traces port-related events.
10926 Message tags: open, closed, register, unregister, get‐
10928 ting_linked, and getting_unlinked.
10929 running:
10931 Traces scheduling of processes.
10932 Message tags: in and out.
10934 exiting:
10936 Traces scheduling of exiting processes.
10937 Message tags: in_exiting, out_exiting, and out_exited.
10939 running_procs:
10941 Traces scheduling of processes just like running. However,
10942 this option also includes schedule events when the process
10943 executes within the context of a port without being sched‐
10944 uled out itself.
10945 Message tags: in and out.
10947 running_ports:
10949 Traces scheduling of ports.
10950 Message tags: in and out.
10952 garbage_collection:
10954 Traces garbage collections of processes.
10955 Message tags: gc_minor_start, gc_max_heap_size, and gc_mi‐
10957 nor_end.
10958 timestamp:
10960 Includes a time stamp in all trace messages. The time stamp
10961 (Ts) has the same form as returned by erlang:now().
10962 cpu_timestamp:
10964 A global trace flag for the Erlang node that makes all trace
10965 time stamps using flag timestamp to be in CPU time, not wall
10966 clock time. That is, cpu_timestamp is not be used if mono‐
10967 tonic_timestamp or strict_monotonic_timestamp is enabled.
10968 Only allowed with PidPortSpec==all. If the host machine OS
10969 does not support high-resolution CPU time measurements,
10970 trace/3 exits with badarg. Notice that most OS do not syn‐
10971 chronize this value across cores, so be prepared that time
10972 can seem to go backwards when using this option.
10973 monotonic_timestamp:
10975 Includes an Erlang monotonic time time stamp in all trace
10976 messages. The time stamp (Ts) has the same format and value
10977 as produced by erlang:monotonic_time(nanosecond). This flag
10978 overrides flag cpu_timestamp.
10979 strict_monotonic_timestamp:
10981 Includes an time stamp consisting of Erlang monotonic time
10982 and a monotonically increasing integer in all trace mes‐
10983 sages. The time stamp (Ts) has the same format and value as
10984 produced by { erlang:monotonic_time(nanosecond), er‐
10985 lang:unique_integer([monotonic])}. This flag overrides flag
10986 cpu_timestamp.
10987 arity:
10989 Used with the call trace flag. {M, F, Arity} is specified
10990 instead of {M, F, Args} in call trace messages.
10991 set_on_spawn:
10993 Makes any process created by a traced process inherit its
10994 trace flags, including flag set_on_spawn.
10995 set_on_first_spawn:
10997 Makes the first process created by a traced process inherit
10998 its trace flags, excluding flag set_on_first_spawn.
10999 set_on_link:
11001 Makes any process linked by a traced process inherit its
11002 trace flags, including flag set_on_link.
11003 set_on_first_link:
11005 Makes the first process linked to by a traced process in‐
11006 herit its trace flags, excluding flag set_on_first_link.
11007 {tracer, Tracer}:
11009 Specifies where to send the trace messages. Tracer must be
11010 the process identifier of a local process or the port iden‐
11011 tifier of a local port.
11012 {tracer, TracerModule, TracerState}:
11014 Specifies that a tracer module is to be called instead of
11015 sending a trace message. The tracer module can then ignore
11016 or change the trace message. For more details on how to
11017 write a tracer module, see erl_tracer(3).
11018 If no tracer is specified, the calling process receives all the
11020 trace messages.
11021 The effect of combining set_on_first_link with set_on_link is
11023 the same as set_on_first_link alone. Likewise for set_on_spawn
11024 and set_on_first_spawn.
11025 The tracing process receives the trace messages described in the
11027 following list. Pid is the process identifier of the traced
11028 process in which the traced event has occurred. The third tuple
11029 element is the message tag.
11030 If flag timestamp, strict_monotonic_timestamp, or mono‐
11032 tonic_timestamp is specified, the first tuple element is
11033 trace_ts instead, and the time stamp is added as an extra ele‐
11034 ment last in the message tuple. If multiple time stamp flags are
11035 passed, timestamp has precedence over strict_monotonic_time‐
11036 stamp, which in turn has precedence over monotonic_timestamp.
11037 All time stamp flags are remembered, so if two are passed and
11038 the one with highest precedence later is disabled, the other one
11039 becomes active.
11040 If a match specification (applicable only for call, send and
11042 'receive' tracing) contains a {message} action function with a
11043 non-boolean value, that value is added as an extra element to
11044 the message tuple either in the last position or before the
11045 timestamp (if it is present).
11046 Trace messages:
11048 {trace, PidPort, send, Msg, To}:
11050 When PidPort sends message Msg to process To.
11051 {trace, PidPort, send_to_non_existing_process, Msg, To}:
11053 When PidPort sends message Msg to the non-existing process
11054 To.
11055 {trace, PidPort, 'receive', Msg}:
11057 When PidPort receives message Msg. If Msg is set to time-
11058 out, a receive statement can have timed out, or the process
11059 received a message with the payload timeout.
11060 {trace, Pid, call, {M, F, Args}}:
11062 When Pid calls a traced function. The return values of calls
11063 are never supplied, only the call and its arguments.
11064 Trace flag arity can be used to change the contents of this
11066 message, so that Arity is specified instead of Args.
11067 {trace, Pid, return_to, {M, F, Arity}}:
11069 When Pid returns to the specified function. This trace mes‐
11070 sage is sent if both the flags call and return_to are set,
11071 and the function is set to be traced on local function
11072 calls. The message is only sent when returning from a chain
11073 of tail recursive function calls, where at least one call
11074 generated a call trace message (that is, the functions match
11075 specification matched, and {message, false} was not an ac‐
11076 tion).
11077 {trace, Pid, return_from, {M, F, Arity}, ReturnValue}:
11079 When Pid returns from the specified function. This trace
11080 message is sent if flag call is set, and the function has a
11081 match specification with a return_trace or exception_trace
11082 action.
11083 {trace, Pid, exception_from, {M, F, Arity}, {Class, Value}}:
11085 When Pid exits from the specified function because of an ex‐
11086 ception. This trace message is sent if flag call is set, and
11087 the function has a match specification with an excep‐
11088 tion_trace action.
11089 {trace, Pid, spawn, Pid2, {M, F, Args}}:
11091 When Pid spawns a new process Pid2 with the specified func‐
11092 tion call as entry point.
11093 Args is supposed to be the argument list, but can be any
11095 term if the spawn is erroneous.
11096 {trace, Pid, spawned, Pid2, {M, F, Args}}:
11098 When Pid is spawned by process Pid2 with the specified func‐
11099 tion call as entry point.
11100 Args is supposed to be the argument list, but can be any
11102 term if the spawn is erroneous.
11103 {trace, Pid, exit, Reason}:
11105 When Pid exits with reason Reason.
11106 {trace, PidPort, register, RegName}:
11108 When PidPort gets the name RegName registered.
11109 {trace, PidPort, unregister, RegName}:
11111 When PidPort gets the name RegName unregistered. This is
11112 done automatically when a registered process or port exits.
11113 {trace, Pid, link, Pid2}:
11115 When Pid links to a process Pid2.
11116 {trace, Pid, unlink, Pid2}:
11118 When Pid removes the link from a process Pid2.
11119 {trace, PidPort, getting_linked, Pid2}:
11121 When PidPort gets linked to a process Pid2.
11122 {trace, PidPort, getting_unlinked, Pid2}:
11124 When PidPort gets unlinked from a process Pid2.
11125 {trace, Port, open, Pid, Driver}:
11127 When Pid opens a new port Port with the running Driver.
11128 Driver is the name of the driver as an atom.
11130 {trace, Port, closed, Reason}:
11132 When Port closes with Reason.
11133 {trace, Pid, in | in_exiting, {M, F, Arity} | 0}:
11135 When Pid is scheduled to run. The process runs in function
11136 {M, F, Arity}. On some rare occasions, the current function
11137 cannot be determined, then the last element is 0.
11138 {trace, Pid, out | out_exiting | out_exited, {M, F, Arity} |
11140 0}:
11141 When Pid is scheduled out. The process was running in func‐
11142 tion {M, F, Arity}. On some rare occasions, the current
11143 function cannot be determined, then the last element is 0.
11144 {trace, Port, in, Command | 0}:
11146 When Port is scheduled to run. Command is the first thing
11147 the port will execute, it can however run several commands
11148 before being scheduled out. On some rare occasions, the cur‐
11149 rent function cannot be determined, then the last element is
11150 0.
11151 The possible commands are call, close, command, connect,
11153 control, flush, info, link, open, and unlink.
11154 {trace, Port, out, Command | 0}:
11156 When Port is scheduled out. The last command run was Com‐
11157 mand. On some rare occasions, the current function cannot be
11158 determined, then the last element is 0. Command can contain
11159 the same commands as in
11160 {trace, Pid, gc_minor_start, Info}:
11162 Sent when a young garbage collection is about to be started.
11165 Info is a list of two-element tuples, where the first ele‐
11166 ment is a key, and the second is the value. Do not depend on
11167 any order of the tuples. The following keys are defined:
11168 heap_size:
11170 The size of the used part of the heap.
11171 heap_block_size:
11173 The size of the memory block used for storing the heap and
11174 the stack.
11175 old_heap_size:
11177 The size of the used part of the old heap.
11178 old_heap_block_size:
11180 The size of the memory block used for storing the old
11181 heap.
11182 stack_size:
11184 The size of the stack.
11185 recent_size:
11187 The size of the data that survived the previous garbage
11188 collection.
11189 mbuf_size:
11191 The combined size of message buffers associated with the
11192 process.
11193 bin_vheap_size:
11195 The total size of unique off-heap binaries referenced from
11196 the process heap.
11197 bin_vheap_block_size:
11199 The total size of binaries allowed in the virtual heap in
11200 the process before doing a garbage collection.
11201 bin_old_vheap_size:
11203 The total size of unique off-heap binaries referenced from
11204 the process old heap.
11205 bin_old_vheap_block_size:
11207 The total size of binaries allowed in the virtual old heap
11208 in the process before doing a garbage collection.
11209 wordsize:
11211 For the gc_minor_start event it is the size of the need
11212 that triggered the GC. For the corresponding gc_minor_end
11213 event it is the size of reclaimed memory = start heap_size
11214 - end heap_size.
11215 All sizes are in words.
11217 {trace, Pid, gc_max_heap_size, Info}:
11219 Sent when the max_heap_size is reached during garbage col‐
11220 lection. Info contains the same kind of list as in message
11221 gc_start, but the sizes reflect the sizes that triggered
11222 max_heap_size to be reached.
11223 {trace, Pid, gc_minor_end, Info}:
11225 Sent when young garbage collection is finished. Info con‐
11226 tains the same kind of list as in message gc_minor_start,
11227 but the sizes reflect the new sizes after garbage collec‐
11228 tion.
11229 {trace, Pid, gc_major_start, Info}:
11231 Sent when fullsweep garbage collection is about to be
11232 started. Info contains the same kind of list as in message
11233 gc_minor_start.
11234 {trace, Pid, gc_major_end, Info}:
11236 Sent when fullsweep garbage collection is finished. Info
11237 contains the same kind of list as in message gc_minor_start,
11238 but the sizes reflect the new sizes after a fullsweep
11239 garbage collection.
11240 If the tracing process/port dies or the tracer module returns
11242 remove, the flags are silently removed.
11243 Each process can only be traced by one tracer. Therefore, at‐
11245 tempts to trace an already traced process fail.
11246 Returns a number indicating the number of processes that matched
11248 PidPortSpec. If PidPortSpec is a process identifier, the return
11249 value is 1. If PidPortSpec is all or existing, the return value
11250 is the number of processes running. If PidPortSpec is new, the
11251 return value is 0.
11252 Failure: badarg if the specified arguments are not supported.
11254 For example, cpu_timestamp is not supported on all platforms.
11255 erlang:trace_delivered(Tracee) -> Ref
11257 Types:
11259 Tracee = pid() | all
11261 Ref = reference()
11262 The delivery of trace messages (generated by erlang:trace/3,
11264 seq_trace(3), or erlang:system_profile/2) is dislocated on the
11265 time-line compared to other events in the system. If you know
11266 that Tracee has passed some specific point in its execution, and
11267 you want to know when at least all trace messages corresponding
11268 to events up to this point have reached the tracer, use er‐
11269 lang:trace_delivered(Tracee).
11270 When it is guaranteed that all trace messages are delivered to
11272 the tracer up to the point that Tracee reached at the time of
11273 the call to erlang:trace_delivered(Tracee), then a {trace_deliv‐
11274 ered, Tracee, Ref} message is sent to the caller of er‐
11275 lang:trace_delivered(Tracee) .
11276 Notice that message trace_delivered does not imply that trace
11278 messages have been delivered. Instead it implies that all trace
11279 messages that are to be delivered have been delivered. It is not
11280 an error if Tracee is not, and has not been traced by someone,
11281 but if this is the case, no trace messages have been delivered
11282 when the trace_delivered message arrives.
11283 Notice that Tracee must refer to a process currently or previ‐
11285 ously existing on the same node as the caller of er‐
11286 lang:trace_delivered(Tracee) resides on. The special Tracee atom
11287 all denotes all processes that currently are traced in the node.
11288 When used together with a Tracer Module, any message sent in
11290 the trace callback is guaranteed to have reached its recipient
11291 before the trace_delivered message is sent.
11292 Example: Process A is Tracee, port B is tracer, and process C is
11294 the port owner of B. C wants to close B when A exits. To ensure
11295 that the trace is not truncated, C can call erlang:trace_deliv‐
11296 ered(A) when A exits, and wait for message {trace_delivered, A,
11297 Ref} before closing B.
11298 Failure: badarg if Tracee does not refer to a process (dead or
11300 alive) on the same node as the caller of erlang:trace_deliv‐
11301 ered(Tracee) resides on.
11302 erlang:trace_info(PidPortFuncEvent, Item) -> Res
11304 Types:
11306 PidPortFuncEvent =
11308 pid() |
11309 port() |
11310 new | new_processes | new_ports |
11311 {Module, Function, Arity} |
11312 on_load | send | 'receive'
11313 Module = module()
11314 Function = atom()
11315 Arity = arity()
11316 Item =
11317 flags | tracer | traced | match_spec | meta |
11318 meta_match_spec | call_count | call_time | all
11319 Res = trace_info_return()
11320 trace_info_return() =
11321 undefined |
11322 {flags, [trace_info_flag()]} |
11323 {tracer, pid() | port() | []} |
11324 {tracer, module(), term()} |
11325 trace_info_item_result() |
11326 {all, [trace_info_item_result()] | false | undefined}
11327 trace_info_item_result() =
11328 {traced, global | local | false | undefined} |
11329 {match_spec, trace_match_spec() | false | undefined} |
11330 {meta, pid() | port() | false | undefined | []} |
11331 {meta, module(), term()} |
11332 {meta_match_spec, trace_match_spec() | false | undefined} |
11333 {call_count, integer() >= 0 | boolean() | undefined} |
11334 {call_time,
11335 [{pid(),
11336 integer() >= 0,
11337 integer() >= 0,
11338 integer() >= 0}] |
11339 boolean() |
11340 undefined}
11341 trace_info_flag() =
11342 send | 'receive' | set_on_spawn | call | return_to | procs |
11343 set_on_first_spawn | set_on_link | running |
11344 garbage_collection | timestamp | monotonic_timestamp |
11345 strict_monotonic_timestamp | arity
11346 trace_match_spec() =
11347 [{[term()] | '_' | match_variable(), [term()], [term()]}]
11348 match_variable() = atom()
11349 Approximation of '$1' | '$2' | '$3' | ...
11350 Returns trace information about a port, process, function, or
11352 event.
11353 To get information about a port or process, PidPortFuncEvent is
11355 to be a process identifier (pid), port identifier, or one of the
11356 atoms new, new_processes, or new_ports. The atom new or new_pro‐
11357 cesses means that the default trace state for processes to be
11358 created is returned. The atom new_ports means that the default
11359 trace state for ports to be created is returned.
11360 Valid Items for ports and processes:
11362 flags:
11364 Returns a list of atoms indicating what kind of traces is
11365 enabled for the process. The list is empty if no traces are
11366 enabled, and one or more of the following atoms if traces
11367 are enabled: send, 'receive', set_on_spawn, call, return_to,
11368 procs, ports, set_on_first_spawn, set_on_link, running, run‐
11369 ning_procs, running_ports, silent, exiting, monotonic_time‐
11370 stamp, strict_monotonic_timestamp, garbage_collection, time‐
11371 stamp, and arity. The order is arbitrary.
11372 tracer:
11374 Returns the identifier for process, port, or a tuple con‐
11375 taining the tracer module and tracer state tracing this
11376 process. If this process is not traced, the return value is
11377 [].
11378 To get information about a function, PidPortFuncEvent is to be
11380 the three-element tuple {Module, Function, Arity} or the atom
11381 on_load. No wildcards are allowed. Returns undefined if the
11382 function does not exist, or false if the function is not traced.
11383 If PidPortFuncEvent is on_load, the information returned refers
11384 to the default value for code that will be loaded.
11385 Valid Items for functions:
11387 traced:
11389 Returns global if this function is traced on global function
11390 calls, local if this function is traced on local function
11391 calls (that is, local and global function calls), and false
11392 if local or global function calls are not traced.
11393 match_spec:
11395 Returns the match specification for this function, if it has
11396 one. If the function is locally or globally traced but has
11397 no match specification defined, the returned value is [].
11398 meta:
11400 Returns the meta-trace tracer process, port, or trace module
11401 for this function, if it has one. If the function is not
11402 meta-traced, the returned value is false. If the function is
11403 meta-traced but has once detected that the tracer process is
11404 invalid, the returned value is [].
11405 meta_match_spec:
11407 Returns the meta-trace match specification for this func‐
11408 tion, if it has one. If the function is meta-traced but has
11409 no match specification defined, the returned value is [].
11410 call_count:
11412 Returns the call count value for this function or true for
11413 the pseudo function on_load if call count tracing is active.
11414 Otherwise false is returned.
11415 See also erlang:trace_pattern/3.
11417 call_time:
11419 Returns the call time values for this function or true for
11420 the pseudo function on_load if call time tracing is active.
11421 Otherwise false is returned. The call time values returned,
11422 [{Pid, Count, S, Us}], is a list of each process that exe‐
11423 cuted the function and its specific counters.
11424 See also erlang:trace_pattern/3.
11426 all:
11428 Returns a list containing the {Item, Value} tuples for all
11429 other items, or returns false if no tracing is active for
11430 this function.
11431 To get information about an event, PidPortFuncEvent is to be one
11433 of the atoms send or 'receive'.
11434 One valid Item for events exists:
11436 match_spec:
11438 Returns the match specification for this event, if it has
11439 one, or true if no match specification has been set.
11440 The return value is {Item, Value}, where Value is the requested
11442 information as described earlier. If a pid for a dead process
11443 was specified, or the name of a non-existing function, Value is
11444 undefined.
11445 erlang:trace_pattern(MFA, MatchSpec) -> integer() >= 0
11447 Types:
11449 MFA = trace_pattern_mfa() | send | 'receive'
11451 MatchSpec =
11452 (MatchSpecList :: trace_match_spec()) |
11453 boolean() |
11454 restart | pause
11455 trace_pattern_mfa() = {atom(), atom(), arity() | '_'} | on_load
11456 trace_match_spec() =
11457 [{[term()] | '_' | match_variable(), [term()], [term()]}]
11458 match_variable() = atom()
11459 Approximation of '$1' | '$2' | '$3' | ...
11460 The same as erlang:trace_pattern(Event, MatchSpec, []), retained
11462 for backward compatibility.
11463 erlang:trace_pattern(MFA :: send, MatchSpec, FlagList :: []) ->
11465 integer() >= 0
11466 Types:
11468 MatchSpec = (MatchSpecList :: trace_match_spec()) | boolean()
11470 trace_match_spec() =
11471 [{[term()] | '_' | match_variable(), [term()], [term()]}]
11472 match_variable() = atom()
11473 Approximation of '$1' | '$2' | '$3' | ...
11474 Sets trace pattern for message sending. Must be combined with
11476 erlang:trace/3 to set the send trace flag for one or more pro‐
11477 cesses. By default all messages sent from send traced processes
11478 are traced. To limit traced send events based on the message
11479 content, the sender and/or the receiver, use erlang:trace_pat‐
11480 tern/3.
11481 Argument MatchSpec can take the following forms:
11483 MatchSpecList:
11485 A list of match specifications. The matching is done on the
11486 list [Receiver, Msg]. Receiver is the process or port iden‐
11487 tity of the receiver and Msg is the message term. The pid of
11488 the sending process can be accessed with the guard function
11489 self/0. An empty list is the same as true. For more informa‐
11490 tion, see section Match Specifications in Erlang in the
11491 User's Guide.
11492 true:
11494 Enables tracing for all sent messages (from send traced pro‐
11495 cesses). Any match specification is removed. This is the de‐
11496 fault.
11497 false:
11499 Disables tracing for all sent messages. Any match specifica‐
11500 tion is removed.
11501 Argument FlagList must be [] for send tracing.
11503 The return value is always 1.
11505 Examples:
11507 Only trace messages to a specific process Pid:
11509 > erlang:trace_pattern(send, [{[Pid, '_'],[],[]}], []).
11511 1
11512 Only trace messages matching {reply, _}:
11514 > erlang:trace_pattern(send, [{['_', {reply,'_'}],[],[]}], []).
11516 1
11517 Only trace messages sent to the sender itself:
11519 > erlang:trace_pattern(send, [{['$1', '_'],[{'=:=','$1',{self}}],[]}], []).
11521 1
11522 Only trace messages sent to other nodes:
11524 > erlang:trace_pattern(send, [{['$1', '_'],[{'=/=',{node,'$1'},{node}}],[]}], []).
11526 1
11527 Note:
11529 A match specification for send trace can use all guard and body
11530 functions except caller.
11531 Fails by raising an error exception with an error reason of:
11534 badarg:
11536 If an argument is invalid.
11537 system_limit:
11539 If a match specification passed as argument has excessive
11540 nesting which causes scheduler stack exhaustion for the
11541 scheduler that the calling process is executing on. Sched‐
11542 uler stack size can be configured when starting the runtime
11543 system.
11544 erlang:trace_pattern(MFA :: 'receive', MatchSpec, FlagList :: []) ->
11546 integer() >= 0
11547 Types:
11549 MatchSpec = (MatchSpecList :: trace_match_spec()) | boolean()
11551 trace_match_spec() =
11552 [{[term()] | '_' | match_variable(), [term()], [term()]}]
11553 match_variable() = atom()
11554 Approximation of '$1' | '$2' | '$3' | ...
11555 Sets trace pattern for message receiving. Must be combined with
11557 erlang:trace/3 to set the 'receive' trace flag for one or more
11558 processes. By default all messages received by 'receive' traced
11559 processes are traced. To limit traced receive events based on
11560 the message content, the sender and/or the receiver, use er‐
11561 lang:trace_pattern/3.
11562 Argument MatchSpec can take the following forms:
11564 MatchSpecList:
11566 A list of match specifications. The matching is done on the
11567 list [Node, Sender, Msg]. Node is the node name of the
11568 sender. Sender is the process or port identity of the
11569 sender, or the atom undefined if the sender is not known
11570 (which can be the case for remote senders). Msg is the mes‐
11571 sage term. The pid of the receiving process can be accessed
11572 with the guard function self/0. An empty list is the same as
11573 true. For more information, see section Match Specifica‐
11574 tions in Erlang in the User's Guide.
11575 true:
11577 Enables tracing for all received messages (to 'receive'
11578 traced processes). Any match specification is removed. This
11579 is the default.
11580 false:
11582 Disables tracing for all received messages. Any match speci‐
11583 fication is removed.
11584 Argument FlagList must be [] for receive tracing.
11586 The return value is always 1.
11588 Examples:
11590 Only trace messages from a specific process Pid:
11592 > erlang:trace_pattern('receive', [{['_',Pid, '_'],[],[]}], []).
11594 1
11595 Only trace messages matching {reply, _}:
11597 > erlang:trace_pattern('receive', [{['_','_', {reply,'_'}],[],[]}], []).
11599 1
11600 Only trace messages from other nodes:
11602 > erlang:trace_pattern('receive', [{['$1', '_', '_'],[{'=/=','$1',{node}}],[]}], []).
11604 1
11605 Note:
11607 A match specification for 'receive' trace can use all guard and
11608 body functions except caller, is_seq_trace, get_seq_token,
11609 set_seq_token, enable_trace, disable_trace, trace, silent, and
11610 process_dump.
11611 Fails by raising an error exception with an error reason of:
11614 badarg:
11616 If an argument is invalid.
11617 system_limit:
11619 If a match specification passed as argument has excessive
11620 nesting which causes scheduler stack exhaustion for the
11621 scheduler that the calling process is executing on. Sched‐
11622 uler stack size can be configured when starting the runtime
11623 system.
11624 erlang:trace_pattern(MFA, MatchSpec, FlagList) ->
11626 integer() >= 0
11627 Types:
11629 MFA = trace_pattern_mfa()
11631 MatchSpec =
11632 (MatchSpecList :: trace_match_spec()) |
11633 boolean() |
11634 restart | pause
11635 FlagList = [trace_pattern_flag()]
11636 trace_pattern_mfa() = {atom(), atom(), arity() | '_'} | on_load
11637 trace_match_spec() =
11638 [{[term()] | '_' | match_variable(), [term()], [term()]}]
11639 trace_pattern_flag() =
11640 global | local | meta |
11641 {meta, Pid :: pid()} |
11642 {meta, TracerModule :: module(), TracerState :: term()} |
11643 call_count | call_time
11644 match_variable() = atom()
11645 Approximation of '$1' | '$2' | '$3' | ...
11646 Enables or disables call tracing for one or more functions. Must
11648 be combined with erlang:trace/3 to set the call trace flag for
11649 one or more processes.
11650 Conceptually, call tracing works as follows. Inside the Erlang
11652 virtual machine, a set of processes and a set of functions are
11653 to be traced. If a traced process calls a traced function, the
11654 trace action is taken. Otherwise, nothing happens.
11655 To add or remove one or more processes to the set of traced pro‐
11657 cesses, use erlang:trace/3.
11658 To add or remove functions to the set of traced functions, use
11660 erlang:trace_pattern/3.
11661 The BIF erlang:trace_pattern/3 can also add match specifications
11663 to a function. A match specification comprises a pattern that
11664 the function arguments must match, a guard expression that must
11665 evaluate to true, and an action to be performed. The default ac‐
11666 tion is to send a trace message. If the pattern does not match
11667 or the guard fails, the action is not executed.
11668 Argument MFA is to be a tuple, such as {Module, Function, Ar‐
11670 ity}, or the atom on_load (described below). It can be the mod‐
11671 ule, function, and arity for a function (or a BIF in any mod‐
11672 ule). The atom '_' can be used as a wildcard in any of the fol‐
11673 lowing ways:
11674 {Module,Function,'_'}:
11676 All functions of any arity named Function in module Module.
11677 {Module,'_','_'}:
11679 All functions in module Module.
11680 {'_','_','_'}:
11682 All functions in all loaded modules.
11683 Other combinations, such as {Module,'_',Arity}, are not allowed.
11685 Local functions match wildcards only if option local is in
11686 FlagList.
11687 If argument MFA is the atom on_load, the match specification and
11689 flag list are used on all modules that are newly loaded.
11690 Argument MatchSpec can take the following forms:
11692 false:
11694 Disables tracing for the matching functions. Any match spec‐
11695 ification is removed.
11696 true:
11698 Enables tracing for the matching functions. Any match speci‐
11699 fication is removed.
11700 MatchSpecList:
11702 A list of match specifications. An empty list is equivalent
11703 to true. For a description of match specifications, see sec‐
11704 tion Match Specifications in Erlang in the User's Guide.
11705 restart:
11707 For the FlagList options call_count and call_time: restarts
11708 the existing counters. The behavior is undefined for other
11709 FlagList options.
11710 pause:
11712 For the FlagList options call_count and call_time: pauses
11713 the existing counters. The behavior is undefined for other
11714 FlagList options.
11715 Parameter FlagList is a list of options. The following are the
11717 valid options:
11718 global:
11720 Turns on or off call tracing for global function calls (that
11721 is, calls specifying the module explicitly). Only exported
11722 functions match and only global calls generate trace mes‐
11723 sages. This is the default.
11724 local:
11726 Turns on or off call tracing for all types of function
11727 calls. Trace messages are sent whenever any of the specified
11728 functions are called, regardless of how they are called. If
11729 flag return_to is set for the process, a return_to message
11730 is also sent when this function returns to its caller.
11731 meta | {meta, Pid} | {meta, TracerModule, TracerState}:
11733 Turns on or off meta-tracing for all types of function
11734 calls. Trace messages are sent to the tracer whenever any of
11735 the specified functions are called. If no tracer is speci‐
11736 fied, self() is used as a default tracer process.
11737 Meta-tracing traces all processes and does not care about
11739 the process trace flags set by erlang:trace/3, the trace
11740 flags are instead fixed to [call, timestamp].
11741 The match specification function {return_trace} works with
11743 meta-trace and sends its trace message to the same tracer.
11744 call_count:
11746 Starts (MatchSpec == true) or stops (MatchSpec == false)
11747 call count tracing for all types of function calls. For ev‐
11748 ery function, a counter is incremented when the function is
11749 called, in any process. No process trace flags need to be
11750 activated.
11751 If call count tracing is started while already running, the
11753 count is restarted from zero. To pause running counters, use
11754 MatchSpec == pause. Paused and running counters can be
11755 restarted from zero with MatchSpec == restart.
11756 To read the counter value, use erlang:trace_info/2.
11758 call_time:
11760 Starts (MatchSpec == true) or stops (MatchSpec == false)
11761 call time tracing for all types of function calls. For every
11762 function, a counter is incremented when the function is
11763 called. Time spent in the function is accumulated in two
11764 other counters, seconds and microseconds. The counters are
11765 stored for each call traced process.
11766 If call time tracing is started while already running, the
11768 count and time restart from zero. To pause running counters,
11769 use MatchSpec == pause. Paused and running counters can be
11770 restarted from zero with MatchSpec == restart.
11771 To read the counter value, use erlang:trace_info/2.
11773 The options global and local are mutually exclusive, and global
11775 is the default (if no options are specified). The options
11776 call_count and meta perform a kind of local tracing, and cannot
11777 be combined with global. A function can be globally or locally
11778 traced. If global tracing is specified for a set of functions,
11779 then local, meta, call time, and call count tracing for the
11780 matching set of local functions is disabled, and conversely.
11781 When disabling trace, the option must match the type of trace
11783 set on the function. That is, local tracing must be disabled
11784 with option local and global tracing with option global (or no
11785 option), and so on.
11786 Part of a match specification list cannot be changed directly.
11788 If a function has a match specification, it can be replaced with
11789 a new one. To change an existing match specification, use the
11790 BIF erlang:trace_info/2 to retrieve the existing match specifi‐
11791 cation.
11792 Returns the number of functions matching argument MFA. This is
11794 zero if none matched.
11795 Fails by raising an error exception with an error reason of:
11797 badarg:
11799 If an argument is invalid.
11800 system_limit:
11802 If a match specification passed as argument has excessive
11803 nesting which causes scheduler stack exhaustion for the
11804 scheduler that the calling process is executing on. Sched‐
11805 uler stack size can be configured when starting the runtime
11806 system.
11807 trunc(Number) -> integer()
11809 Types:
11811 Number = number()
11813 Truncates the decimals of Number, for example:
11815 > trunc(5.7).
11817 5
11818 > trunc(-5.7).
11820 -5
11821 > trunc(5).
11823 5
11824 > trunc(36028797018963969.0).
11826 36028797018963968
11827 In the last example, trunc(36028797018963969.0) evaluates to
11829 36028797018963968. The reason for this is that the number
11830 36028797018963969.0 cannot be represented exactly as a float
11831 value. Instead, the float literal is represented as
11832 36028797018963968.0, which is the closest number that can be
11833 represented exactly as a float value. See Representation of
11834 Floating Point Numbers for additional information.
11835 Allowed in guard tests.
11837 tuple_size(Tuple) -> integer() >= 0
11839 Types:
11841 Tuple = tuple()
11843 Returns an integer that is the number of elements in Tuple, for
11845 example:
11846 > tuple_size({morni, mulle, bwange}).
11848 3
11849 Allowed in guard tests.
11851 tuple_to_list(Tuple) -> [term()]
11853 Types:
11855 Tuple = tuple()
11857 Returns a list corresponding to Tuple. Tuple can contain any Er‐
11859 lang terms. Example:
11860 > tuple_to_list({share, {'Ericsson_B', 163}}).
11862 [share,{'Ericsson_B',163}]
11863 unalias(Alias) -> boolean()
11865 Types:
11867 Alias = reference()
11869 Deactivate the alias Alias previously created by the calling
11871 process. An alias can for example be created via alias/0, or
11872 monitor/3. unalias/1 will always deactivate the alias regardless
11873 of options used when creating the alias.
11874 Returns true if Alias was a currently active alias for current
11876 processes; otherwise, false.
11877 For more information on process aliases see the Process Aliases
11879 section of the Erlang Reference Manual .
11880 erlang:unique_integer() -> integer()
11882 Generates and returns an integer unique on current runtime sys‐
11884 tem instance. The same as calling erlang:unique_integer([]).
11885 erlang:unique_integer(ModifierList) -> integer()
11887 Types:
11889 ModifierList = [Modifier]
11891 Modifier = positive | monotonic
11892 Generates and returns an integer unique on current runtime sys‐
11894 tem instance. The integer is unique in the sense that this BIF,
11895 using the same set of modifiers, does not return the same inte‐
11896 ger more than once on the current runtime system instance. Each
11897 integer value can of course be constructed by other means.
11898 By default, when [] is passed as ModifierList, both negative and
11900 positive integers can be returned. This to use the range of in‐
11901 tegers that do not need heap memory allocation as much as possi‐
11902 ble. By default the returned integers are also only guaranteed
11903 to be unique, that is, any returned integer can be smaller or
11904 larger than previously returned integers.
11905 Modifiers:
11907 positive:
11909 Returns only positive integers.
11910 Notice that by passing the positive modifier you will get
11912 heap allocated integers (bignums) quicker.
11913 monotonic:
11915 Returns strictly monotonically increasing integers corre‐
11916 sponding to creation time. That is, the integer returned is
11917 always larger than previously returned integers on the cur‐
11918 rent runtime system instance.
11919 These values can be used to determine order between events
11921 on the runtime system instance. That is, if both X = er‐
11922 lang:unique_integer([monotonic]) and Y = erlang:unique_inte‐
11923 ger([monotonic]) are executed by different processes (or the
11924 same process) on the same runtime system instance and X < Y,
11925 we know that X was created before Y.
11926 Warning:
11928 Strictly monotonically increasing values are inherently quite
11929 expensive to generate and scales poorly. This is because the
11930 values need to be synchronized between CPU cores. That is, do
11931 not pass the monotonic modifier unless you really need
11932 strictly monotonically increasing values.
11933 All valid Modifiers can be combined. Repeated (valid) Modifiers
11936 in the ModifierList are ignored.
11937 Note:
11939 The set of integers returned by erlang:unique_integer/1 using
11940 different sets of Modifiers will overlap. For example, by call‐
11941 ing unique_integer([monotonic]), and unique_integer([positive,
11942 monotonic]) repeatedly, you will eventually see some integers
11943 that are returned by both calls.
11944 Failures:
11947 badarg:
11949 if ModifierList is not a proper list.
11950 badarg:
11952 if Modifier is not a valid modifier.
11953 erlang:universaltime() -> DateTime
11955 Types:
11957 DateTime = calendar:datetime()
11959 Returns the current date and time according to Universal Time
11961 Coordinated (UTC) in the form {{Year, Month, Day}, {Hour,
11962 Minute, Second}} if supported by the underlying OS. Otherwise
11963 erlang:universaltime() is equivalent to erlang:localtime(). The
11964 return value is based on the OS System Time. Example:
11965 > erlang:universaltime().
11967 {{1996,11,6},{14,18,43}}
11968 erlang:universaltime_to_localtime(Universaltime) -> Localtime
11970 Types:
11972 Localtime = Universaltime = calendar:datetime()
11974 Converts Universal Time Coordinated (UTC) date and time to local
11976 date and time in the form {{Year, Month, Day}, {Hour, Minute,
11977 Second}} if supported by the underlying OS. Otherwise no conver‐
11978 sion is done, and Universaltime is returned. Example:
11979 > erlang:universaltime_to_localtime({{1996,11,6},{14,18,43}}).
11981 {{1996,11,7},{15,18,43}}
11982 Failure: badarg if Universaltime denotes an invalid date and
11984 time.
11985 unlink(Id) -> true
11987 Types:
11989 Id = pid() | port()
11991 Removes a link between the calling process and another process
11993 or a port identified by Id. We will from here on call the iden‐
11994 tified process or port unlinkee.
11995 A link can be set up using the link/1 BIF. For more information
11997 on links and exit signals due to links, see the Processes chap‐
11998 ter in the Erlang Reference Manual :
11999 * Links
12001 * Sending Exit Signals
12003 * Receiving Exit Signals
12005 Once unlink(Id) has returned, it is guaranteed that the link be‐
12007 tween the caller and the unlinkee has no effect on the caller in
12008 the future (unless the link is setup again). Note that if the
12009 caller is trapping exits, an {'EXIT', Id, ExitReason} message
12010 due to the link may have been placed in the message queue of the
12011 caller before the unlink(Id) call completed. Also note that the
12012 {'EXIT', Id, ExitReason} message may be the result of the link,
12013 but may also be the result of the unlikee sending the caller an
12014 exit signal by calling the exit/2 BIF. Therefore, it may or may
12015 not be appropriate to clean up the message queue after a call to
12016 unlink(Id) as follows, when trapping exits:
12017 unlink(Id),
12019 receive
12020 {'EXIT', Id, _} ->
12021 true
12022 after 0 ->
12023 true
12024 end
12025 The link removal is performed asynchronously. If such a link
12027 does not exist, nothing is done. A detailed description of the
12028 link protocol can be found in the Distribution Protocol chapter
12029 of the ERTS User's Guide .
12030 Failure: badarg if Id does not identify a process or a node lo‐
12032 cal port.
12033 unregister(RegName) -> true
12035 Types:
12037 RegName = atom()
12039 Removes the registered name RegName associated with a process
12041 identifier or a port identifier from the name registry. For ex‐
12042 ample:
12043 > unregister(db).
12045 true
12046 Keep in mind that you can still receive signals associated with
12048 the registered name after it has been unregistered as the sender
12049 may have looked up the name before sending to it.
12050 Users are advised not to unregister system processes.
12052 Failure: badarg if RegName is not a registered name.
12054 whereis(RegName) -> pid() | port() | undefined
12056 Types:
12058 RegName = atom()
12060 Returns the process identifier or port identifier with the reg‐
12062 istered name RegName from the name registry. Returns undefined
12063 if the name is not registered. Example:
12064 > whereis(db).
12066 <0.43.0>
12067 erlang:yield() -> true
12069 Tries to give other processes with the same or higher priority
12071 (if any) a chance to execute before returning. There is no guar‐
12072 antee that any other process runs between the invocation and re‐
12073 turn of erlang:yield/0.
12074 See the documentation for receive-after expressions for how to
12076 make the current process sleep for a specific number of mil‐
12077 liseconds.
12078 Warning:
12080 There is seldom or never any need to use this BIF. Using this
12081 BIF without a thorough grasp of how the scheduler works can
12082 cause performance degradation. The current implementation of
12083 this function puts the current process last in the current
12084 scheduler's queue for processes of the same priority as the cur‐
12085 rent process.
12086Ericsson AB erts 13.1.4 erlang(3)