1erlang(3) Erlang Module Definition erlang(3)
2
6 erlang - The Erlang BIFs and predefined types.
7
9 By convention, most Built-In Functions (BIFs) and all predefined types
10 are included in this module. Some of the BIFs and all of the predefined
11 types are viewed more or less as part of the Erlang programming lan‐
12 guage and are auto-imported. Thus, it is not necessary to specify the
13 module name. For example, the calls atom_to_list(erlang) and er‐
14 lang:atom_to_list(erlang) are identical.
15 Auto-imported BIFs are listed without module prefix. BIFs listed with
17 module prefix are not auto-imported.
18 Predefined types are listed in the Predefined datatypes section of this
20 reference manual and in the Types and Function Specifications section
21 of the Erlang Reference Manual.
22 BIFs can fail for various reasons. All BIFs fail with reason badarg if
24 they are called with arguments of an incorrect type. The other reasons
25 are described in the description of each individual BIF.
26 Some BIFs can be used in guard tests and are marked with "Allowed in
28 guard tests".
29
31 Predefined datatypes
32 any() = any()
33 All possible Erlang terms. Synonym for term().
35 arity() = arity()
37 The arity of a function or type.
39 atom() = atom()
41 An Erlang atom.
43 binary() = <<_:_*8>>
45 An Erlang binary, that is, a bitstring with a size divisible by
47 8.
48 bitstring() = <<_:_*1>>
50 An Erlang bitstring.
52 boolean() = true | false
54 A boolean value.
56 byte() = 0..255
58 A byte of data represented by an integer.
60 char() = 0..1114111
62 An ASCII character or a unicode codepoint presented by an inte‐
64 ger.
65 float() = float()
67 An Erlang float.
69 function() = function()
71 An Erlang fun.
73 identifier() = pid() | port() | reference()
75 An unique identifier for some entity, for example a process,
77 port or monitor.
78 integer() = integer()
80 An Erlang integer.
82 iodata() = iolist() | binary()
84 A binary or list containing bytes and/or iodata. This datatype
86 is used to represent data that is meant to be output using any
87 I/O module. For example: file:write/2 or gen_tcp:send/2.
88 To convert an iodata() term to binary() you can use
90 iolist_to_binary/2. To transcode a string() or unicode:char‐
91 data() to iodata() you can use unicode:characters_to_binary/1.
92 iolist() =
94 maybe_improper_list(byte() | binary() | iolist(),
95 binary() | [])
96 A list containing bytes and/or iodata. This datatype is used to
98 represent data that is meant to be output using any I/O module.
99 For example: file:write/2 or gen_tcp:send/2.
100 In most use cases you want to use iodata() instead of this type.
102 list() = [any()]
104 An Erlang list containing terms of any type.
106 list(ContentType) = [ContentType]
108 An Erlang list containing terms of the type ContentType.
110 map() = #{any() => any()}
112 An Erlang map containing any number of key and value associa‐
114 tions.
115 maybe_improper_list() = maybe_improper_list(any(), any())
117 An Erlang list that is not guaranteed to end with a [], and
119 where the list elements can be of any type.
120 maybe_improper_list(ContentType, TerminationType) =
122 maybe_improper_list(ContentType, TerminationType)
123 An Erlang list, that is not guaranteed to end with a [], and
125 where the list elements are of the type ContentType.
126 mfa() = {module(), atom(), arity()}
128 A three-tuple representing a Module:Function/Arity function sig‐
130 nature.
131 module() = atom()
133 An Erlang module represented by an atom.
135 neg_integer() = integer() =< -1
137 A negative integer.
139 nil() = []
141 The empty list().
143 no_return() = none()
145 The type used to show that a function will never return a value,
147 that is it will always throw an exception.
148 node() = atom()
150 An Erlang node represented by an atom.
152 non_neg_integer() = integer() >= 0
154 A non-negative integer, that is any positive integer or 0.
156 none() = none()
158 This type is used to show that a function will never return a
160 value; that is it will always throw an exception. In a spec, use
161 no_return() for the sake of clarity.
162 nonempty_binary() = <<_:8, _:_*8>>
164 A binary() that contains some data.
166 nonempty_bitstring() = <<_:1, _:_*1>>
168 A bitstring() that contains some data.
170 nonempty_improper_list(ContentType, TerminationType) =
172 nonempty_improper_list(ContentType, TerminationType)
173 A maybe_improper_list/2 that contains some items.
175 nonempty_list() = [any(), ...]
177 A list() that contains some items.
179 nonempty_list(ContentType) = [ContentType, ...]
181 A list(ContentType) that contains some items.
183 nonempty_maybe_improper_list() =
185 nonempty_maybe_improper_list(any(), any())
186 A maybe_improper_list() that contains some items.
188 nonempty_maybe_improper_list(ContentType, TerminationType) =
190 nonempty_maybe_improper_list(ContentType, TerminationType)
191 A maybe_improper_list(ContentType, TerminationType) that con‐
193 tains some items.
194 nonempty_string() = [char(), ...]
196 A string() that contains some characters.
198 number() = integer() | float()
200 An Erlang number.
202 pid() = pid()
204 An Erlang process identifier.
206 port() = port()
208 An Erlang port identifier.
210 pos_integer() = integer() >= 1
212 An integer greater than zero.
214 reference() = reference()
216 An Erlang reference.
218 string() = [char()]
220 A character string represented by a list of ASCII characters or
222 unicode codepoints.
223 term() = any()
225 All possible Erlang terms. Synonym for any().
227 timeout() = infinity | integer() >= 0
229 A timeout value that can be passed to a receive expression.
231 tuple() = tuple()
233 An Erlang tuple.
235 Other Datatypes
237 ext_binary() = binary()
238 A binary data object, structured according to the Erlang exter‐
240 nal term format.
241 ext_iovec() = iovec()
243 A term of type iovec(), structured according to the Erlang ex‐
245 ternal term format.
246 iovec() = [binary()]
248 A list of binaries. This datatype is useful to use together with
250 enif_inspect_iovec.
251 message_queue_data() = off_heap | on_heap
253 See process_flag(message_queue_data, MQD).
255 monitor_option() =
257 {alias, explicit_unalias | demonitor | reply_demonitor} |
258 {tag, term()}
259 See monitor/3.
261 timestamp() =
263 {MegaSecs :: integer() >= 0,
264 Secs :: integer() >= 0,
265 MicroSecs :: integer() >= 0}
266 See erlang:timestamp/0.
268 time_unit() =
270 integer() >= 1 |
271 second | millisecond | microsecond | nanosecond | native |
272 perf_counter |
273 deprecated_time_unit()
274 Supported time unit representations:
276 PartsPerSecond :: integer() >= 1:
278 Time unit expressed in parts per second. That is, the time
279 unit equals 1/PartsPerSecond second.
280 second:
282 Symbolic representation of the time unit represented by the
283 integer 1.
284 millisecond:
286 Symbolic representation of the time unit represented by the
287 integer 1000.
288 microsecond:
290 Symbolic representation of the time unit represented by the
291 integer 1000_000.
292 nanosecond:
294 Symbolic representation of the time unit represented by the
295 integer 1000_000_000.
296 native:
298 Symbolic representation of the native time unit used by the
299 Erlang runtime system.
300 The native time unit is determined at runtime system start,
302 and remains the same until the runtime system terminates. If
303 a runtime system is stopped and then started again (even on
304 the same machine), the native time unit of the new runtime
305 system instance can differ from the native time unit of the
306 old runtime system instance.
307 One can get an approximation of the native time unit by
309 calling erlang:convert_time_unit(1, second, native). The re‐
310 sult equals the number of whole native time units per sec‐
311 ond. If the number of native time units per second does not
312 add up to a whole number, the result is rounded downwards.
313 Note:
315 The value of the native time unit gives you more or less no
316 information about the quality of time values. It sets a limit
317 for the resolution and for the precision of time values, but
318 it gives no information about the accuracy of time values.
319 The resolution of the native time unit and the resolution of
320 time values can differ significantly.
321 perf_counter:
324 Symbolic representation of the performance counter time unit
325 used by the Erlang runtime system.
326 The perf_counter time unit behaves much in the same way as
328 the native time unit. That is, it can differ between runtime
329 restarts. To get values of this type, call
330 os:perf_counter/0.
331 deprecated_time_unit():
333 Deprecated symbolic representations kept for backwards-com‐
334 patibility.
335 The time_unit/0 type can be extended. To convert time values be‐
337 tween time units, use erlang:convert_time_unit/3.
338 deprecated_time_unit() =
340 seconds | milli_seconds | micro_seconds | nano_seconds
341 The time_unit() type also consist of the following deprecated
343 symbolic time units:
344 seconds:
346 Same as second.
347 milli_seconds:
349 Same as millisecond.
350 micro_seconds:
352 Same as microsecond.
353 nano_seconds:
355 Same as nanosecond.
356 dist_handle()
358 An opaque handle identifying a distribution channel.
360 nif_resource()
362 An opaque handle identifying a NIF resource object .
364 spawn_opt_option() =
366 link | monitor |
367 {monitor, MonitorOpts :: [monitor_option()]} |
368 {priority, Level :: priority_level()} |
369 {fullsweep_after, Number :: integer() >= 0} |
370 {min_heap_size, Size :: integer() >= 0} |
371 {min_bin_vheap_size, VSize :: integer() >= 0} |
372 {max_heap_size, Size :: max_heap_size()} |
373 {message_queue_data, MQD :: message_queue_data()} |
374 {async_dist, Enabled :: boolean()}
375 Options for spawn_opt().
377 priority_level() = low | normal | high | max
379 Process priority level. For more info see process_flag(priority,
381 Level)
382 max_heap_size() =
384 integer() >= 0 |
385 #{size => integer() >= 0,
386 kill => boolean(),
387 error_logger => boolean(),
388 include_shared_binaries => boolean()}
389 Process max heap size configuration. For more info see
391 process_flag(max_heap_size, MaxHeapSize)
392 message_queue_data() = off_heap | on_heap
394 Process message queue data configuration. For more information,
396 see process_flag(message_queue_data, MQD)
397 stacktrace() =
399 [{module(),
400 atom(),
401 arity() | [term()],
402 [stacktrace_extrainfo()]} |
403 {function(), arity() | [term()], [stacktrace_extrainfo()]}]
404 stacktrace_extrainfo() =
406 {line, integer() >= 1} |
407 {file, unicode:chardata()} |
408 {error_info,
409 #{module => module(), function => atom(), cause => term()}} |
410 {atom(), term()}
411 An Erlang stacktrace as described by Errors and Error Handling
413 section in the Erlang Reference Manual.
414 send_destination() =
416 pid() |
417 reference() |
418 port() |
419 (RegName :: atom()) |
420 {RegName :: atom(), Node :: node()}
421 The destination for a send operation, can be a remote or local
423 process identifier, a (local) port, a reference denoting a
424 process alias, a locally registered name, or a tuple {RegName,
425 Node} for a registered name at another node.
426
428 abs(Float) -> float()
429 abs(Int) -> integer() >= 0
431 Types:
433 Int = integer()
435 Returns an integer or float that is the arithmetical absolute
437 value of Float or Int, for example:
438 > abs(-3.33).
440 3.33
441 > abs(-3).
442 3
443 Allowed in guard tests.
445 erlang:adler32(Data) -> integer() >= 0
447 Types:
449 Data = iodata()
451 Computes and returns the adler32 checksum for Data.
453 erlang:adler32(OldAdler, Data) -> integer() >= 0
455 Types:
457 OldAdler = integer() >= 0
459 Data = iodata()
460 Continues computing the adler32 checksum by combining the previ‐
462 ous checksum, OldAdler, with the checksum of Data.
463 The following code:
465 X = erlang:adler32(Data1),
467 Y = erlang:adler32(X,Data2).
468 assigns the same value to Y as this:
470 Y = erlang:adler32([Data1,Data2]).
472 erlang:adler32_combine(FirstAdler, SecondAdler, SecondSize) ->
474 integer() >= 0
475 Types:
477 FirstAdler = SecondAdler = SecondSize = integer() >= 0
479 Combines two previously computed adler32 checksums. This compu‐
481 tation requires the size of the data object for the second
482 checksum to be known.
483 The following code:
485 Y = erlang:adler32(Data1),
487 Z = erlang:adler32(Y,Data2).
488 assigns the same value to Z as this:
490 X = erlang:adler32(Data1),
492 Y = erlang:adler32(Data2),
493 Z = erlang:adler32_combine(X,Y,iolist_size(Data2)).
494 alias() -> Alias
496 alias(Opts) -> Alias
498 Types:
500 Alias = reference()
502 Opts = [explicit_unalias | reply]
503 Create an alias which can be used when sending messages to the
505 process that created the alias. When the alias has been deacti‐
506 vated, messages sent using the alias will be dropped. An alias
507 can be deactivated using unalias/1. Currently available options
508 for alias/1:
509 explicit_unalias:
511 The alias can only be deactivated via a call to unalias/1.
512 This is also the default behaviour if no options are passed
513 or if alias/0 is called.
514 reply:
516 The alias will be automatically deactivated when a reply
517 message sent via the alias is received. The alias can also
518 still be deactivated via a call to unalias/1.
519 Example:
521 server() ->
523 receive
524 {request, AliasReqId, Request} ->
525 Result = perform_request(Request),
526 AliasReqId ! {reply, AliasReqId, Result}
527 end,
528 server().
529 client(ServerPid, Request) ->
531 AliasReqId = alias([reply]),
532 ServerPid ! {request, AliasReqId, Request},
533 %% Alias will be automatically deactivated if we receive a reply
534 %% since we used the 'reply' option...
535 receive
536 {reply, AliasReqId, Result} -> Result
537 after 5000 ->
538 unalias(AliasReqId),
539 %% Flush message queue in case the reply arrived
540 %% just before the alias was deactivated...
541 receive {reply, AliasReqId, Result} -> Result
542 after 0 -> exit(timeout)
543 end
544 end.
545 Note that both the server and the client in this example must be
548 executing on at least OTP 24 systems in order for this to work.
549 For more information on process aliases see the Process Aliases
551 section of the Erlang Reference Manual .
552 erlang:append_element(Tuple1, Term) -> Tuple2
554 Types:
556 Tuple1 = Tuple2 = tuple()
558 Term = term()
559 Returns a new tuple that has one element more than Tuple1, and
561 contains the elements in Tuple1 followed by Term as the last el‐
562 ement. Semantically equivalent to list_to_tuple(tu‐
563 ple_to_list(Tuple1) ++ [Term]), but much faster. Example:
564 > erlang:append_element({one, two}, three).
566 {one,two,three}
567 apply(Fun, Args) -> term()
569 Types:
571 Fun = function()
573 Args = [term()]
574 Calls a fun, passing the elements in Args as arguments.
576 If the number of elements in the arguments are known at compile
578 time, the call is better written as Fun(Arg1, Arg2, ... ArgN).
579 Warning:
581 Earlier, Fun could also be specified as {Module, Function},
582 equivalent to apply(Module, Function, Args). This use is depre‐
583 cated and will stop working in a future release.
584 apply(Module, Function, Args) -> term()
587 Types:
589 Module = module()
591 Function = atom()
592 Args = [term()]
593 Returns the result of applying Function in Module to Args. The
595 applied function must be exported from Module. The arity of the
596 function is the length of Args. Example:
597 > apply(lists, reverse, [[a, b, c]]).
599 [c,b,a]
600 > apply(erlang, atom_to_list, ['Erlang']).
601 "Erlang"
602 If the number of arguments are known at compile time, the call
604 is better written as Module:Function(Arg1, Arg2, ..., ArgN).
605 Failure: error_handler:undefined_function/3 is called if the ap‐
607 plied function is not exported. The error handler can be rede‐
608 fined (see process_flag/2). If error_handler is undefined, or if
609 the user has redefined the default error_handler so the replace‐
610 ment module is undefined, an error with reason undef is gener‐
611 ated.
612 atom_to_binary(Atom) -> binary()
614 Types:
616 Atom = atom()
618 The same as atom_to_binary(Atom, utf8).
620 atom_to_binary(Atom, Encoding) -> binary()
622 Types:
624 Atom = atom()
626 Encoding = latin1 | unicode | utf8
627 Returns a binary corresponding to the text representation of
629 Atom. If Encoding is latin1, one byte exists for each character
630 in the text representation. If Encoding is utf8 or unicode, the
631 characters are encoded using UTF-8 where characters may require
632 multiple bytes.
633 Change:
635 As from Erlang/OTP 20, atoms can contain any Unicode character
636 and atom_to_binary(Atom, latin1) may fail if the text represen‐
637 tation for Atom contains a Unicode character > 255.
638 Example:
641 > atom_to_binary('Erlang', latin1).
643 <<"Erlang">>
644 atom_to_list(Atom) -> string()
646 Types:
648 Atom = atom()
650 Returns a list of unicode code points corresponding to the text
652 representation of Atom, for example:
653 > atom_to_list('Erlang').
655 "Erlang"
656 > atom_to_list('你好').
658 [20320,22909]
659 See unicode(3) for how to convert the resulting list to differ‐
661 ent formats.
662 binary_part(Subject, PosLen) -> binary()
664 Types:
666 Subject = binary()
668 PosLen = {Start :: integer() >= 0, Length :: integer()}
669 Extracts the part of the binary described by PosLen.
671 Negative length can be used to extract bytes at the end of a bi‐
673 nary, for example:
674 1> Bin = <<1,2,3,4,5,6,7,8,9,10>>.
676 2> binary_part(Bin,{byte_size(Bin), -5}).
677 <<6,7,8,9,10>>
678 Failure: badarg if PosLen in any way references outside the bi‐
680 nary.
681 Start is zero-based, that is:
683 1> Bin = <<1,2,3>>
685 2> binary_part(Bin,{0,2}).
686 <<1,2>>
687 For details about the PosLen semantics, see binary(3).
689 Allowed in guard tests.
691 binary_part(Subject, Start, Length) -> binary()
693 Types:
695 Subject = binary()
697 Start = integer() >= 0
698 Length = integer()
699 The same as binary_part(Subject, {Start, Length}).
701 Allowed in guard tests.
703 binary_to_atom(Binary) -> atom()
705 Types:
707 Binary = binary()
709 The same as binary_to_atom(Binary, utf8).
711 binary_to_atom(Binary, Encoding) -> atom()
713 Types:
715 Binary = binary()
717 Encoding = latin1 | unicode | utf8
718 Returns the atom whose text representation is Binary. If Encod‐
720 ing is utf8 or unicode, the binary must contain valid UTF-8 se‐
721 quences.
722 Change:
724 As from Erlang/OTP 20, binary_to_atom(Binary, utf8) is capable
725 of decoding any Unicode character. Earlier versions would fail
726 if the binary contained Unicode characters > 255.
727 Note:
730 The number of characters that are permitted in an atom name is
731 limited. The default limits can be found in the efficiency
732 guide (section Advanced).
733 Note:
736 There is configurable limit on how many atoms that can exist and
737 atoms are not garbage collected. Therefore, it is recommended to
738 consider whether binary_to_existing_atom/2 is a better option
739 than binary_to_atom/2. The default limits can be found in effi‐
740 ciency guide (section Advanced).
741 Examples:
744 > binary_to_atom(<<"Erlang">>, latin1).
746 > binary_to_atom(<<1024/utf8>>, utf8).
748 binary_to_existing_atom(Binary) -> atom()
750 Types:
752 Binary = binary()
754 The same as binary_to_existing_atom (Binary, utf8).
756 binary_to_existing_atom(Binary, Encoding) -> atom()
758 Types:
760 Binary = binary()
762 Encoding = latin1 | unicode | utf8
763 As binary_to_atom/2, but the atom must exist.
765 The Erlang system has a configurable limit for the total number
767 of atoms that can exist, and atoms are not garbage collected.
768 Therefore, it is not safe to create many atoms from binaries
769 that come from an untrusted source (for example, a file fetched
770 from the Internet), for example, using binary_to_atom/2. This
771 function is thus the appropriate option when the input binary
772 comes from an untrusted source.
773 An atom exists in an Erlang system when included in a loaded Er‐
775 lang module or when created programmatically (for example, by
776 binary_to_atom/2). See the next note for an example of when an
777 atom exists in the source code for an Erlang module but not in
778 the compiled version of the same module.
779 Failure: badarg if the atom does not exist.
781 Note:
783 Note that the compiler may optimize away atoms. For example, the
784 compiler will rewrite atom_to_list(some_atom) to "some_atom". If
785 that expression is the only mention of the atom some_atom in the
786 containing module, the atom will not be created when the module
787 is loaded, and a subsequent call to binary_to_exist‐
788 ing_atom(<<"some_atom">>, utf8) will fail.
789 Note:
792 The number of characters that are permitted in an atom name is
793 limited. The default limits can be found in the efficiency
794 guide (section Advanced).
795 binary_to_float(Binary) -> float()
798 Types:
800 Binary = binary()
802 Returns the float whose text representation is Binary, for exam‐
804 ple:
805 > binary_to_float(<<"2.2017764e+0">>).
807 2.2017764
808 The float string format is the same as the format for Erlang
810 float literals except for that underscores are not permitted.
811 Failure: badarg if Binary contains a bad representation of a
813 float.
814 binary_to_integer(Binary) -> integer()
816 Types:
818 Binary = binary()
820 Returns an integer whose text representation is Binary, for ex‐
822 ample:
823 > binary_to_integer(<<"123">>).
825 123
826 binary_to_integer/1 accepts the same string formats as
828 list_to_integer/1.
829 Failure: badarg if Binary contains a bad representation of an
831 integer.
832 binary_to_integer(Binary, Base) -> integer()
834 Types:
836 Binary = binary()
838 Base = 2..36
839 Returns an integer whose text representation in base Base is Bi‐
841 nary, for example:
842 > binary_to_integer(<<"3FF">>, 16).
844 1023
845 binary_to_integer/2 accepts the same string formats as
847 list_to_integer/2.
848 Failure: badarg if Binary contains a bad representation of an
850 integer.
851 binary_to_list(Binary) -> [byte()]
853 Types:
855 Binary = binary()
857 Returns a list of integers corresponding to the bytes of Binary.
859 binary_to_list(Binary, Start, Stop) -> [byte()]
861 Types:
863 Binary = binary()
865 Start = Stop = integer() >= 1
866 1..byte_size(Binary)
867 As binary_to_list/1, but returns a list of integers correspond‐
869 ing to the bytes from position Start to position Stop in Binary.
870 The positions in the binary are numbered starting from 1.
871 Note:
873 The one-based indexing for binaries used by this function is
874 deprecated. New code is to use binary:bin_to_list/3 in STDLIB
875 instead. All functions in module binary consistently use zero-
876 based indexing.
877 binary_to_term(Binary) -> term()
880 Types:
882 Binary = ext_binary()
884 Returns an Erlang term that is the result of decoding binary ob‐
886 ject Binary, which must be encoded according to the Erlang ex‐
887 ternal term format.
888 > Bin = term_to_binary(hello).
890 <<131,100,0,5,104,101,108,108,111>>
891 > hello = binary_to_term(Bin).
892 hello
893 Warning:
896 When decoding binaries from untrusted sources, the untrusted
897 source may submit data in a way to create resources, such as
898 atoms and remote references, that cannot be garbage collected
899 and lead to Denial of Service attack. In such cases, consider
900 using binary_to_term/2 with the safe option.
901 See also term_to_binary/1 and binary_to_term/2.
904 binary_to_term(Binary, Opts) -> term() | {term(), Used}
906 Types:
908 Binary = ext_binary()
910 Opt = safe | used
911 Opts = [Opt]
912 Used = integer() >= 1
913 As binary_to_term/1, but takes these options:
915 safe:
917 Use this option when receiving binaries from an untrusted
918 source.
919 When enabled, it prevents decoding data that can be used to
921 attack the Erlang runtime. In the event of receiving unsafe
922 data, decoding fails with a badarg error.
923 This prevents creation of new atoms directly, creation of
925 new atoms indirectly (as they are embedded in certain struc‐
926 tures, such as process identifiers, refs, and funs), and
927 creation of new external function references. None of those
928 resources are garbage collected, so unchecked creation of
929 them can exhaust available memory.
930 > binary_to_term(<<131,100,0,5,"hello">>, [safe]).
932 ** exception error: bad argument
933 > hello.
934 hello
935 > binary_to_term(<<131,100,0,5,"hello">>, [safe]).
936 hello
937 Warning:
940 The safe option ensures the data is safely processed by the
941 Erlang runtime but it does not guarantee the data is safe to
942 your application. You must always validate data from untrusted
943 sources. If the binary is stored or transits through untrusted
944 sources, you should also consider cryptographically signing
945 it.
946 used:
949 Changes the return value to {Term, Used} where Used is the
950 number of bytes actually read from Binary.
951 > Input = <<131,100,0,5,"hello","world">>.
953 <<131,100,0,5,104,101,108,108,111,119,111,114,108,100>>
954 > {Term, Used} = binary_to_term(Input, [used]).
955 {hello, 9}
956 > split_binary(Input, Used).
957 {<<131,100,0,5,104,101,108,108,111>>, <<"world">>}
958 Failure: badarg if safe is specified and unsafe data is decoded.
961 See also term_to_binary/1, binary_to_term/1, and list_to_exist‐
963 ing_atom/1.
964 bit_size(Bitstring) -> integer() >= 0
966 Types:
968 Bitstring = bitstring()
970 Returns an integer that is the size in bits of Bitstring, for
972 example:
973 > bit_size(<<433:16,3:3>>).
975 19
976 > bit_size(<<1,2,3>>).
977 24
978 Allowed in guard tests.
980 bitstring_to_list(Bitstring) -> [byte() | bitstring()]
982 Types:
984 Bitstring = bitstring()
986 Returns a list of integers corresponding to the bytes of Bit‐
988 string. If the number of bits in the binary is not divisible by
989 8, the last element of the list is a bitstring containing the
990 remaining 1-7 bits. Examples:
991 > bitstring_to_list(<<433:16>>).
993 [1,177]
994 > bitstring_to_list(<<433:16,3:3>>).
996 [1,177,<<3:3>>]
997 erlang:bump_reductions(Reductions) -> true
999 Types:
1001 Reductions = integer() >= 1
1003 This implementation-dependent function increments the reduction
1005 counter for the calling process. In the Beam emulator, the re‐
1006 duction counter is normally incremented by one for each function
1007 and BIF call. A context switch is forced when the counter
1008 reaches the maximum number of reductions for a process (4000 re‐
1009 ductions in Erlang/OTP 19.2 and later).
1010 Warning:
1012 This BIF can be removed in a future version of the Beam machine
1013 without prior warning. It is unlikely to be implemented in other
1014 Erlang implementations.
1015 byte_size(Bitstring) -> integer() >= 0
1018 Types:
1020 Bitstring = bitstring()
1022 Returns an integer that is the number of bytes needed to contain
1024 Bitstring. That is, if the number of bits in Bitstring is not
1025 divisible by 8, the resulting number of bytes is rounded up. Ex‐
1026 amples:
1027 > byte_size(<<433:16,3:3>>).
1029 3
1030 > byte_size(<<1,2,3>>).
1031 3
1032 Allowed in guard tests.
1034 erlang:cancel_timer(TimerRef) -> Result
1036 Types:
1038 TimerRef = reference()
1040 Time = integer() >= 0
1041 Result = Time | false
1042 Cancels a timer. The same as calling erlang:cancel_timer(Timer‐
1044 Ref, []).
1045 erlang:cancel_timer(TimerRef, Options) -> Result | ok
1047 Types:
1049 TimerRef = reference()
1051 Async = Info = boolean()
1052 Option = {async, Async} | {info, Info}
1053 Options = [Option]
1054 Time = integer() >= 0
1055 Result = Time | false
1056 Cancels a timer that has been created by erlang:start_timer or
1058 erlang:send_after. TimerRef identifies the timer, and was re‐
1059 turned by the BIF that created the timer.
1060 Options:
1062 {async, Async}:
1064 Asynchronous request for cancellation. Async defaults to
1065 false, which causes the cancellation to be performed syn‐
1066 chronously. When Async is set to true, the cancel operation
1067 is performed asynchronously. That is, cancel_timer() sends
1068 an asynchronous request for cancellation to the timer ser‐
1069 vice that manages the timer, and then returns ok.
1070 {info, Info}:
1072 Requests information about the Result of the cancellation.
1073 Info defaults to true, which means the Result is given. When
1074 Info is set to false, no information about the result of the
1075 cancellation is given.
1076 * When Async is false: if Info is true, the Result is re‐
1078 turned by erlang:cancel_timer(). otherwise ok is returned.
1079 * When Async is true: if Info is true, a message on the form
1081 {cancel_timer, TimerRef, Result} is sent to the caller of
1082 erlang:cancel_timer() when the cancellation operation has
1083 been performed, otherwise no message is sent.
1084 More Options may be added in the future.
1086 If Result is an integer, it represents the time in milliseconds
1088 left until the canceled timer would have expired.
1089 If Result is false, a timer corresponding to TimerRef could not
1091 be found. This can be either because the timer had expired, al‐
1092 ready had been canceled, or because TimerRef never corresponded
1093 to a timer. Even if the timer had expired, it does not tell you
1094 if the time-out message has arrived at its destination yet.
1095 Note:
1097 The timer service that manages the timer can be co-located with
1098 another scheduler than the scheduler that the calling process is
1099 executing on. If so, communication with the timer service takes
1100 much longer time than if it is located locally. If the calling
1101 process is in critical path, and can do other things while wait‐
1102 ing for the result of this operation, or is not interested in
1103 the result of the operation, you want to use option {async,
1104 true}. If using option {async, false}, the calling process
1105 blocks until the operation has been performed.
1106 See also erlang:send_after/4, erlang:start_timer/4, and er‐
1109 lang:read_timer/2.
1110 ceil(Number) -> integer()
1112 Types:
1114 Number = number()
1116 Returns the smallest integer not less than Number. For example:
1118 > ceil(5.5).
1120 6
1121 Allowed in guard tests.
1123 check_old_code(Module) -> boolean()
1125 Types:
1127 Module = module()
1129 Returns true if Module has old code, otherwise false.
1131 See also code(3).
1133 check_process_code(Pid, Module) -> CheckResult
1135 Types:
1137 Pid = pid()
1139 Module = module()
1140 CheckResult = boolean()
1141 The same as check_process_code(Pid, Module, []).
1143 check_process_code(Pid, Module, OptionList) -> CheckResult | async
1145 Types:
1147 Pid = pid()
1149 Module = module()
1150 RequestId = term()
1151 Option = {async, RequestId} | {allow_gc, boolean()}
1152 OptionList = [Option]
1153 CheckResult = boolean() | aborted
1154 Checks if the node local process identified by Pid executes old
1156 code for Module.
1157 Options:
1159 {allow_gc, boolean()}:
1161 Determines if garbage collection is allowed when performing
1162 the operation. If {allow_gc, false} is passed, and a garbage
1163 collection is needed to determine the result of the opera‐
1164 tion, the operation is aborted (see information on CheckRe‐
1165 sult below). The default is to allow garbage collection,
1166 that is, {allow_gc, true}.
1167 {async, RequestId}:
1169 The function check_process_code/3 returns the value async
1170 immediately after the request has been sent. When the re‐
1171 quest has been processed, the process that called this func‐
1172 tion is passed a message on the form {check_process_code,
1173 RequestId, CheckResult}.
1174 If Pid equals self(), and no async option has been passed, the
1176 operation is performed at once. Otherwise a request for the op‐
1177 eration is sent to the process identified by Pid, and is handled
1178 when appropriate. If no async option has been passed, the caller
1179 blocks until CheckResult is available and can be returned.
1180 CheckResult informs about the result of the request as follows:
1182 true:
1184 The process identified by Pid executes old code for Module.
1185 That is, the current call of the process executes old code
1186 for this module, or the process has references to old code
1187 for this module, or the process contains funs that refer‐
1188 ences old code for this module.
1189 false:
1191 The process identified by Pid does not execute old code for
1192 Module.
1193 aborted:
1195 The operation was aborted, as the process needed to be
1196 garbage collected to determine the operation result, and the
1197 operation was requested by passing option {allow_gc, false}.
1198 Change:
1200 Up until ERTS version 8.*, the check process code operation
1201 checks for all types of references to the old code. That is, di‐
1202 rect references (e.g. return addresses on the process stack),
1203 indirect references (funs in process context), and references to
1204 literals in the code.
1205 As of ERTS version 9.0, the check process code operation only
1207 checks for direct references to the code. Indirect references
1208 via funs will be ignored. If such funs exist and are used after
1209 a purge of the old code, an exception will be raised upon usage
1210 (same as the case when the fun is received by the process after
1211 the purge). Literals will be taken care of (copied) at a later
1212 stage. This behavior can as of ERTS version 8.1 be enabled when
1213 building OTP, and will automatically be enabled if dirty sched‐
1214 uler support is enabled.
1215 See also code(3).
1218 Failures:
1220 badarg:
1222 If Pid is not a node local process identifier.
1223 badarg:
1225 If Module is not an atom.
1226 badarg:
1228 If OptionList is an invalid list of options.
1229 erlang:convert_time_unit(Time, FromUnit, ToUnit) -> ConvertedTime
1231 Types:
1233 Time = ConvertedTime = integer()
1235 FromUnit = ToUnit = time_unit()
1236 Converts the Time value of time unit FromUnit to the correspond‐
1238 ing ConvertedTime value of time unit ToUnit. The result is
1239 rounded using the floor function.
1240 Warning:
1242 You can lose accuracy and precision when converting between time
1243 units. To minimize such loss, collect all data at native time
1244 unit and do the conversion on the end result.
1245 erlang:crc32(Data) -> integer() >= 0
1248 Types:
1250 Data = iodata()
1252 Computes and returns the crc32 (IEEE 802.3 style) checksum for
1254 Data.
1255 erlang:crc32(OldCrc, Data) -> integer() >= 0
1257 Types:
1259 OldCrc = integer() >= 0
1261 Data = iodata()
1262 Continues computing the crc32 checksum by combining the previous
1264 checksum, OldCrc, with the checksum of Data.
1265 The following code:
1267 X = erlang:crc32(Data1),
1269 Y = erlang:crc32(X,Data2).
1270 assigns the same value to Y as this:
1272 Y = erlang:crc32([Data1,Data2]).
1274 erlang:crc32_combine(FirstCrc, SecondCrc, SecondSize) ->
1276 integer() >= 0
1277 Types:
1279 FirstCrc = SecondCrc = SecondSize = integer() >= 0
1281 Combines two previously computed crc32 checksums. This computa‐
1283 tion requires the size of the data object for the second check‐
1284 sum to be known.
1285 The following code:
1287 Y = erlang:crc32(Data1),
1289 Z = erlang:crc32(Y,Data2).
1290 assigns the same value to Z as this:
1292 X = erlang:crc32(Data1),
1294 Y = erlang:crc32(Data2),
1295 Z = erlang:crc32_combine(X,Y,iolist_size(Data2)).
1296 date() -> Date
1298 Types:
1300 Date = calendar:date()
1302 Returns the current date as {Year, Month, Day}.
1304 The time zone and Daylight Saving Time correction depend on the
1306 underlying OS. The return value is based on the OS System Time.
1307 Example:
1308 > date().
1310 {1995,2,19}
1311 erlang:decode_packet(Type, Bin, Options) ->
1313 {ok, Packet, Rest} |
1314 {more, Length} |
1315 {error, Reason}
1316 Types:
1318 Type =
1320 raw | 0 | 1 | 2 | 4 | asn1 | cdr | sunrm | fcgi | tpkt |
1321 line | http | http_bin | httph | httph_bin
1322 Bin = binary()
1323 Options = [Opt]
1324 Opt =
1325 {packet_size, integer() >= 0} |
1326 {line_length, integer() >= 0}
1327 Packet = binary() | HttpPacket
1328 Rest = binary()
1329 Length = integer() >= 0 | undefined
1330 Reason = term()
1331 HttpPacket =
1332 HttpRequest | HttpResponse | HttpHeader | http_eoh |
1333 HttpError
1334 HttpRequest = {http_request, HttpMethod, HttpUri, HttpVer‐
1335 sion}
1336 HttpResponse =
1337 {http_response, HttpVersion, integer(), HttpString}
1338 HttpHeader =
1339 {http_header,
1340 integer(),
1341 HttpField,
1342 UnmodifiedField :: HttpString,
1343 Value :: HttpString}
1344 HttpError = {http_error, HttpString}
1345 HttpMethod =
1346 'OPTIONS' | 'GET' | 'HEAD' | 'POST' | 'PUT' | 'DELETE' |
1347 'TRACE' | HttpString
1348 HttpUri =
1349 '*' |
1350 {absoluteURI,
1351 http | https,
1352 Host :: HttpString,
1353 Port :: inet:port_number() | undefined,
1354 Path :: HttpString} |
1355 {scheme, Scheme :: HttpString, HttpString} |
1356 {abs_path, HttpString} |
1357 HttpString
1358 HttpVersion =
1359 {Major :: integer() >= 0, Minor :: integer() >= 0}
1360 HttpField =
1361 'Cache-Control' | 'Connection' | 'Date' | 'Pragma' |
1362 'Transfer-Encoding' | 'Upgrade' | 'Via' | 'Accept' |
1363 'Accept-Charset' | 'Accept-Encoding' | 'Accept-Language'
1364 |
1365 'Authorization' | 'From' | 'Host' | 'If-Modified-Since' |
1366 'If-Match' | 'If-None-Match' | 'If-Range' |
1367 'If-Unmodified-Since' | 'Max-Forwards' |
1368 'Proxy-Authorization' | 'Range' | 'Referer' | 'User-
1369 Agent' |
1370 'Age' | 'Location' | 'Proxy-Authenticate' | 'Public' |
1371 'Retry-After' | 'Server' | 'Vary' | 'Warning' |
1372 'Www-Authenticate' | 'Allow' | 'Content-Base' |
1373 'Content-Encoding' | 'Content-Language' | 'Content-
1374 Length' |
1375 'Content-Location' | 'Content-Md5' | 'Content-Range' |
1376 'Content-Type' | 'Etag' | 'Expires' | 'Last-Modified' |
1377 'Accept-Ranges' | 'Set-Cookie' | 'Set-Cookie2' |
1378 'X-Forwarded-For' | 'Cookie' | 'Keep-Alive' |
1379 'Proxy-Connection' | HttpString
1380 HttpString = string() | binary()
1381 Decodes the binary Bin according to the packet protocol speci‐
1383 fied by Type. Similar to the packet handling done by sockets
1384 with option {packet,Type}.
1385 If an entire packet is contained in Bin, it is returned together
1387 with the remainder of the binary as {ok,Packet,Rest}.
1388 If Bin does not contain the entire packet, {more,Length} is re‐
1390 turned. Length is either the expected total size of the packet,
1391 or undefined if the expected packet size is unknown. de‐
1392 code_packet can then be called again with more data added.
1393 If the packet does not conform to the protocol format, {er‐
1395 ror,Reason} is returned.
1396 Types:
1398 raw | 0:
1400 No packet handling is done. The entire binary is returned
1401 unless it is empty.
1402 1 | 2 | 4:
1404 Packets consist of a header specifying the number of bytes
1405 in the packet, followed by that number of bytes. The length
1406 of the header can be one, two, or four bytes; the order of
1407 the bytes is big-endian. The header is stripped off when the
1408 packet is returned.
1409 line:
1411 A packet is a line-terminated by a delimiter byte, default
1412 is the latin-1 newline character. The delimiter byte is in‐
1413 cluded in the returned packet unless the line was truncated
1414 according to option line_length.
1415 asn1 | cdr | sunrm | fcgi | tpkt:
1417 The header is not stripped off.
1418 The meanings of the packet types are as follows:
1420 asn1 - ASN.1 BER:
1422 sunrm - Sun's RPC encoding:
1425 cdr - CORBA (GIOP 1.1):
1428 fcgi - Fast CGI:
1431 tpkt - TPKT format [RFC1006]:
1434 http | httph | http_bin | httph_bin:
1437 The Hypertext Transfer Protocol. The packets are returned
1438 with the format according to HttpPacket described earlier. A
1439 packet is either a request, a response, a header, or an end
1440 of header mark. Invalid lines are returned as HttpError.
1441 Recognized request methods and header fields are returned as
1443 atoms. Others are returned as strings. Strings of unrecog‐
1444 nized header fields are formatted with only capital letters
1445 first and after hyphen characters, for example, "Sec-Web‐
1446 socket-Key". Header field names are also returned in Unmodi‐
1447 fiedField as strings, without any conversion or formatting.
1448 The protocol type http is only to be used for the first line
1450 when an HttpRequest or an HttpResponse is expected. The fol‐
1451 lowing calls are to use httph to get HttpHeaders until
1452 http_eoh is returned, which marks the end of the headers and
1453 the beginning of any following message body.
1454 The variants http_bin and httph_bin return strings (Http‐
1456 String) as binaries instead of lists.
1457 Since OTP 26.0, Host may be an IPv6 address enclosed in [],
1459 as defined in RFC2732 .
1460 Options:
1462 {packet_size, integer() >= 0}:
1464 Sets the maximum allowed size of the packet body. If the
1465 packet header indicates that the length of the packet is
1466 longer than the maximum allowed length, the packet is con‐
1467 sidered invalid. Defaults to 0, which means no size limit.
1468 {line_length, integer() >= 0}:
1470 For packet type line, lines longer than the indicated length
1471 are truncated.
1472 Option line_length also applies to http* packet types as an
1474 alias for option packet_size if packet_size itself is not
1475 set. This use is only intended for backward compatibility.
1476 {line_delimiter, 0 =< byte() =< 255}:
1478 For packet type line, sets the delimiting byte. Default is
1479 the latin-1 character $\n.
1480 Examples:
1482 > erlang:decode_packet(1,<<3,"abcd">>,[]).
1484 {ok,<<"abc">>,<<"d">>}
1485 > erlang:decode_packet(1,<<5,"abcd">>,[]).
1486 {more,6}
1487 erlang:delete_element(Index, Tuple1) -> Tuple2
1489 Types:
1491 Index = integer() >= 1
1493 1..tuple_size(Tuple1)
1494 Tuple1 = Tuple2 = tuple()
1495 Returns a new tuple with element at Index removed from tuple Tu‐
1497 ple1, for example:
1498 > erlang:delete_element(2, {one, two, three}).
1500 {one,three}
1501 delete_module(Module) -> true | undefined
1503 Types:
1505 Module = module()
1507 Makes the current code for Module become old code and deletes
1509 all references for this module from the export table. Returns
1510 undefined if the module does not exist, otherwise true.
1511 Warning:
1513 This BIF is intended for the code server (see code(3)) and is
1514 not to be used elsewhere.
1515 Failure: badarg if there already is an old version of Module.
1518 demonitor(MonitorRef) -> true
1520 Types:
1522 MonitorRef = reference()
1524 If MonitorRef is a reference that the calling process obtained
1526 by calling monitor/2, this monitoring is turned off. If the mon‐
1527 itoring is already turned off, nothing happens.
1528 Once demonitor(MonitorRef) has returned, it is guaranteed that
1530 no {'DOWN', MonitorRef, _, _, _} message, because of the moni‐
1531 tor, will be placed in the caller message queue in the future.
1532 However, a {'DOWN', MonitorRef, _, _, _} message can have been
1533 placed in the caller message queue before the call. It is there‐
1534 fore usually advisable to remove such a 'DOWN' message from the
1535 message queue after monitoring has been stopped. demonitor(Moni‐
1536 torRef, [flush]) can be used instead of demonitor(MonitorRef) if
1537 this cleanup is wanted.
1538 Note:
1540 For some important information about distributed signals, see
1541 the Blocking Signaling Over Distribution section in the Pro‐
1542 cesses chapter of the Erlang Reference Manual .
1543 Change:
1546 Before Erlang/OTP R11B (ERTS 5.5) demonitor/1 behaved completely
1547 asynchronously, that is, the monitor was active until the "de‐
1548 monitor signal" reached the monitored entity. This had one unde‐
1549 sirable effect. You could never know when you were guaranteed
1550 not to receive a DOWN message because of the monitor.
1551 The current behavior can be viewed as two combined operations:
1553 asynchronously send a "demonitor signal" to the monitored entity
1554 and ignore any future results of the monitor.
1555 Failure: It is an error if MonitorRef refers to a monitoring
1558 started by another process. Not all such cases are cheap to
1559 check. If checking is cheap, the call fails with badarg, for ex‐
1560 ample if MonitorRef is a remote reference.
1561 demonitor(MonitorRef, OptionList) -> boolean()
1563 Types:
1565 MonitorRef = reference()
1567 OptionList = [Option]
1568 Option = flush | info
1569 The returned value is true unless info is part of OptionList.
1571 demonitor(MonitorRef, []) is equivalent to demonitor(Monitor‐
1573 Ref).
1574 Options:
1576 flush:
1578 Removes (one) {_, MonitorRef, _, _, _} message, if there is
1579 one, from the caller message queue after monitoring has been
1580 stopped.
1581 Calling demonitor(MonitorRef, [flush]) is equivalent to the
1583 following, but more efficient:
1584 demonitor(MonitorRef),
1586 receive
1587 {_, MonitorRef, _, _, _} ->
1588 true
1589 after 0 ->
1590 true
1591 end
1592 info:
1594 The returned value is one of the following:
1595 true:
1597 The monitor was found and removed. In this case, no 'DOWN'
1598 message corresponding to this monitor has been delivered
1599 and will not be delivered.
1600 false:
1602 The monitor was not found and could not be removed. This
1603 probably because someone already has placed a 'DOWN' mes‐
1604 sage corresponding to this monitor in the caller message
1605 queue.
1606 If option info is combined with option flush, false is re‐
1608 turned if a flush was needed, otherwise true.
1609 Change:
1611 More options can be added in a future release.
1612 Failures:
1615 badarg:
1617 If OptionList is not a list.
1618 badarg:
1620 If Option is an invalid option.
1621 badarg:
1623 The same failure as for demonitor/1.
1624 disconnect_node(Node) -> boolean() | ignored
1626 Types:
1628 Node = node()
1630 Forces the disconnection of a node. This appears to the node
1632 Node as if the local node has crashed. This BIF is mainly used
1633 in the Erlang network authentication protocols.
1634 Returns true if disconnection succeeds, otherwise false. If the
1636 local node is not alive, ignored is returned.
1637 Note:
1639 This function may return before nodedown messages have been de‐
1640 livered.
1641 erlang:display(Term) -> true
1644 Types:
1646 Term = term()
1648 Prints a text representation of Term on the standard output.
1650 Warning:
1652 This BIF is intended for debugging only. The printed representa‐
1653 tion may contain internal details that do not match the high-
1654 level representation of the term in Erlang.
1655 erlang:dist_ctrl_get_data(DHandle) -> {Size, Data} | Data | none
1658 Types:
1660 Size = integer() >= 0
1662 DHandle = dist_handle()
1663 Data = iovec()
1664 Get distribution channel data from the local node that is to be
1666 passed to the remote node. The distribution channel is identi‐
1667 fied by DHandle. If no data is available, the atom none is re‐
1668 turned. One can request to be informed by a message when more
1669 data is available by calling erlang:dist_ctrl_get_data_notifica‐
1670 tion(DHandle).
1671 The returned value when there are data available depends on the
1673 value of the get_size option configured on the distribution
1674 channel identified by DHandle. For more information see the doc‐
1675 umentation of the get_size option for the er‐
1676 lang:dist_ctrl_set_opt/3 function.
1677 Note:
1679 Only the process registered as distribution controller for the
1680 distribution channel identified by DHandle is allowed to call
1681 this function.
1682 This function is used when implementing an alternative distribu‐
1685 tion carrier using processes as distribution controllers. DHan‐
1686 dle is retrieved via the callback f_handshake_complete. More in‐
1687 formation can be found in the documentation of ERTS User's Guide
1688 ➜ How to implement an Alternative Carrier for the Erlang Distri‐
1689 bution ➜ Distribution Module.
1690 erlang:dist_ctrl_get_opt(DHandle, Opt :: get_size) -> Value
1692 Types:
1694 DHandle = dist_handle()
1696 Value = boolean()
1697 Returns the value of the get_size option on the distribution
1699 channel identified by DHandle. For more information see the doc‐
1700 umentation of the get_size option for the er‐
1701 lang:dist_ctrl_set_opt/3 function.
1702 Note:
1704 Only the process registered as distribution controller for the
1705 distribution channel identified by DHandle is allowed to call
1706 this function.
1707 This function is used when implementing an alternative distribu‐
1710 tion carrier using processes as distribution controllers. DHan‐
1711 dle is retrieved via the callback f_handshake_complete. More in‐
1712 formation can be found in the documentation of ERTS User's Guide
1713 ➜ How to implement an Alternative Carrier for the Erlang Distri‐
1714 bution ➜ Distribution Module.
1715 erlang:dist_ctrl_get_data_notification(DHandle) -> ok
1717 Types:
1719 DHandle = dist_handle()
1721 Request notification when more data is available to fetch using
1723 erlang:dist_ctrl_get_data(DHandle) for the distribution channel
1724 identified by DHandle. When more data is present, the caller
1725 will be sent the message dist_data. Once a dist_data messages
1726 has been sent, no more dist_data messages will be sent until the
1727 dist_ctrl_get_data_notification/1 function has been called
1728 again.
1729 Note:
1731 Only the process registered as distribution controller for the
1732 distribution channel identified by DHandle is allowed to call
1733 this function.
1734 This function is used when implementing an alternative distribu‐
1737 tion carrier using processes as distribution controllers. DHan‐
1738 dle is retrieved via the callback f_handshake_complete. More in‐
1739 formation can be found in the documentation of ERTS User's Guide
1740 ➜ How to implement an Alternative Carrier for the Erlang Distri‐
1741 bution ➜ Distribution Module.
1742 erlang:dist_ctrl_input_handler(DHandle, InputHandler) -> ok
1744 Types:
1746 DHandle = dist_handle()
1748 InputHandler = pid()
1749 Register an alternate input handler process for the distribution
1751 channel identified by DHandle. Once this function has been
1752 called, InputHandler is the only process allowed to call er‐
1753 lang:dist_ctrl_put_data(DHandle, Data) with the DHandle identi‐
1754 fying this distribution channel.
1755 Note:
1757 Only the process registered as distribution controller for the
1758 distribution channel identified by DHandle is allowed to call
1759 this function.
1760 This function is used when implementing an alternative distribu‐
1763 tion carrier using processes as distribution controllers. DHan‐
1764 dle is retrieved via the callback f_handshake_complete. More in‐
1765 formation can be found in the documentation of ERTS User's Guide
1766 ➜ How to implement an Alternative Carrier for the Erlang Distri‐
1767 bution ➜ Distribution Module.
1768 erlang:dist_ctrl_put_data(DHandle, Data) -> ok
1770 Types:
1772 DHandle = dist_handle()
1774 Data = iodata()
1775 Deliver distribution channel data from a remote node to the lo‐
1777 cal node.
1778 Note:
1780 Only the process registered as distribution controller for the
1781 distribution channel identified by DHandle is allowed to call
1782 this function unless an alternate input handler process has been
1783 registered using erlang:dist_ctrl_input_handler(DHandle, In‐
1784 putHandler). If an alternate input handler has been registered,
1785 only the registered input handler process is allowed to call
1786 this function.
1787 This function is used when implementing an alternative distribu‐
1790 tion carrier using processes as distribution controllers. DHan‐
1791 dle is retrieved via the callback f_handshake_complete. More in‐
1792 formation can be found in the documentation of ERTS User's Guide
1793 ➜ How to implement an Alternative Carrier for the Erlang Distri‐
1794 bution ➜ Distribution Module.
1795 erlang:dist_ctrl_set_opt(DHandle, Opt :: get_size, Value) ->
1797 OldValue
1798 Types:
1800 DHandle = dist_handle()
1802 Value = OldValue = boolean()
1803 Sets the value of the get_size option on the distribution chan‐
1805 nel identified by DHandle. This option controls the return value
1806 of calls to erlang:dist_ctrl_get_data(DHandle) where DHandle
1807 equals DHandle used when setting this option. When the get_size
1808 option is:
1809 false:
1811 and there are distribution data available, a call to er‐
1812 lang:dist_ctrl_get_data(DHandle) will just return Data to
1813 pass over the channel. This is the default value of the
1814 get_size option.
1815 true:
1817 and there are distribution data available, a call to er‐
1818 lang:dist_ctrl_get_data(DHandle) will return Data to pass
1819 over the channel as well as the Size of Data in bytes. This
1820 is returned as a tuple on the form {Size, Data}.
1821 All options are set to default when a channel is closed.
1823 Note:
1825 Only the process registered as distribution controller for the
1826 distribution channel identified by DHandle is allowed to call
1827 this function.
1828 This function is used when implementing an alternative distribu‐
1831 tion carrier using processes as distribution controllers. DHan‐
1832 dle is retrieved via the callback f_handshake_complete. More in‐
1833 formation can be found in the documentation of ERTS User's Guide
1834 ➜ How to implement an Alternative Carrier for the Erlang Distri‐
1835 bution ➜ Distribution Module.
1836 element(N, Tuple) -> term()
1838 Types:
1840 N = integer() >= 1
1842 1..tuple_size(Tuple)
1843 Tuple = tuple()
1844 Returns the Nth element (numbering from 1) of Tuple, for exam‐
1846 ple:
1847 > element(2, {a, b, c}).
1849 b
1850 Allowed in guard tests.
1852 erase() -> [{Key, Val}]
1854 Types:
1856 Key = Val = term()
1858 Returns the process dictionary and deletes it, for example:
1860 > put(key1, {1, 2, 3}),
1862 put(key2, [a, b, c]),
1863 erase().
1864 [{key1,{1,2,3}},{key2,[a,b,c]}]
1865 erase(Key) -> Val | undefined
1867 Types:
1869 Key = Val = term()
1871 Returns the value Val associated with Key and deletes it from
1873 the process dictionary. Returns undefined if no value is associ‐
1874 ated with Key. The average time complexity for the current im‐
1875 plementation of this function is O(1) and the worst case time
1876 complexity is O(N), where N is the number of items in the
1877 process dictionary. Example:
1878 > put(key1, {merry, lambs, are, playing}),
1880 X = erase(key1),
1881 {X, erase(key1)}.
1882 {{merry,lambs,are,playing},undefined}
1883 error(Reason) -> no_return()
1885 Types:
1887 Reason = term()
1889 Raises an exception of class error with the reason Reason. As
1891 evaluating this function causes an exception to be thrown, it
1892 has no return value.
1893 The intent of the exception class error is to signal that an un‐
1895 expected error has happened (for example, a function is called
1896 with a parameter that has an incorrect type). See the guide
1897 about errors and error handling for additional information. Ex‐
1898 ample:
1899 > catch error(foobar).
1901 {'EXIT',{foobar,[{shell,apply_fun,3,
1902 [{file,"shell.erl"},{line,906}]},
1903 {erl_eval,do_apply,6,[{file,"erl_eval.erl"},{line,677}]},
1904 {erl_eval,expr,5,[{file,"erl_eval.erl"},{line,430}]},
1905 {shell,exprs,7,[{file,"shell.erl"},{line,687}]},
1906 {shell,eval_exprs,7,[{file,"shell.erl"},{line,642}]},
1907 {shell,eval_loop,3,[{file,"shell.erl"},{line,627}]}]}}
1908 error(Reason, Args) -> no_return()
1911 Types:
1913 Reason = term()
1915 Args = [term()] | none
1916 Raises an exception of class error with the reason Reason. Args
1918 is expected to be the list of arguments for the current function
1919 or the atom none. If it is a list, it is used to provide the ar‐
1920 guments for the current function in the stack back-trace. If it
1921 is none, the arity of the calling function is used in the stack‐
1922 trace. As evaluating this function causes an exception to be
1923 raised, it has no return value.
1924 The intent of the exception class error is to signal that an un‐
1926 expected error has happened (for example, a function is called
1927 with a parameter that has an incorrect type). See the guide
1928 about errors and error handling for additional information. Ex‐
1929 ample:
1930 test.erl:
1932 -module(test).
1934 -export([example_fun/2]).
1935 example_fun(A1, A2) ->
1937 erlang:error(my_error, [A1, A2]).
1938 Erlang shell:
1941 6> c(test).
1943 {ok,test}
1944 7> test:example_fun(arg1,"this is the second argument").
1945 ** exception error: my_error
1946 in function test:example_fun/2
1947 called as test:example_fun(arg1,"this is the second argument")
1948 error(Reason, Args, Options) -> no_return()
1951 Types:
1953 Reason = term()
1955 Args = [term()] | none
1956 Options = [Option]
1957 Option = {error_info, ErrorInfoMap}
1958 ErrorInfoMap =
1959 #{cause => term(), module => module(), function =>
1960 atom()}
1961 Raises an exception of class error with the reason Reason. Args
1963 is expected to be the list of arguments for the current function
1964 or the atom none. If it is a list, it is used to provide the ar‐
1965 guments for the current function in the stack back-trace. If it
1966 is none, the arity of the calling function is used in the stack‐
1967 trace. As evaluating this function causes an exception to be
1968 raised, it has no return value.
1969 If the error_info option is given, the ErrorInfoMap will be in‐
1971 serted into the stacktrace. The information given in the Error‐
1972 InfoMap is to be used by error formatters such as erl_error to
1973 provide more context around an error.
1974 The default module of the ErrorInfoMap is the module that the
1976 call to error/3 is made. The default function is format_error.
1977 See format_error/2 for more details on how this Module:Func‐
1978 tion/2 is to be used
1979 The intent of the exception class error is to signal that an un‐
1981 expected error has happened (for example, a function is called
1982 with a parameter that has an incorrect type). See the guide
1983 about errors and error handling for additional information.
1984 exit(Reason) -> no_return()
1986 Types:
1988 Reason = term()
1990 Raises an exception of class exit with exit reason Reason. As
1992 evaluating this function causes an exception to be raised, it
1993 has no return value.
1994 The intent of the exception class exit is that the current
1996 process should be stopped (for example when a message telling a
1997 process to stop is received).
1998 This function differ from error/1,2,3 by causing an exception of
2000 a different class and by having a reason that does not include
2001 the list of functions from the call stack.
2002 See the guide about errors and error handling for additional in‐
2004 formation.
2005 Example:
2007 > exit(foobar).
2009 ** exception exit: foobar
2010 > catch exit(foobar).
2011 {'EXIT',foobar}
2012 Note:
2014 If a process calls exit(kill) and does not catch the exception,
2015 it will terminate with exit reason kill and also emit exit sig‐
2016 nals with exit reason kill (not killed) to all linked processes.
2017 Such exit signals with exit reason kill can be trapped by the
2018 linked processes. Note that this means that signals with exit
2019 reason kill behave differently depending on how they are sent
2020 because the signal will be untrappable if a process sends such a
2021 signal to another process with erlang:exit/2.
2022 exit(Pid, Reason) -> true
2025 Types:
2027 Pid = pid() | port()
2029 Reason = term()
2030 Sends an exit signal with exit reason Reason to the process or
2032 port identified by Pid.
2033 The following behavior applies if Reason is any term, except
2035 normal or kill, and P is the process or port identified by Pid:
2036 * If P is not trapping exits, P exits with exit reason Reason.
2038 * If P is trapping exits, the exit signal is transformed into
2040 a message {'EXIT', From, Reason}, where From is the process
2041 identifier of the process that sent the exit signal, and de‐
2042 livered to the message queue of P.
2043 The following behavior applies if Reason is the term normal and
2045 Pid is the identifier of a process P which is not the same as
2046 the process that invoked erlang:exit(Pid, normal) (the behavior
2047 when a process sends a signal with the normal reason to itself
2048 is described in the warning):
2049 * If P is trapping exits, the exit signal is transformed into
2051 a message {'EXIT', From, normal}, where From is the process
2052 identifier of the process that sent the exit signal, and de‐
2053 livered to P's message queue.
2054 * The signal has no effect if P is not trapping exits.
2056 If Reason is the atom kill, that is, if exit(Pid, kill) is
2058 called, an untrappable exit signal is sent to the process that
2059 is identified by Pid, which unconditionally exits with exit rea‐
2060 son killed. The exit reason is changed from kill to killed to
2061 hint to linked processes that the killed process got killed by a
2062 call to exit(Pid, kill).
2063 Note:
2065 The functions erlang:exit/1 and erlang:exit/2 are named simi‐
2066 larly but provide very different functionalities. The er‐
2067 lang:exit/1 function should be used when the intent is to stop
2068 the current process while erlang:exit/2 should be used when the
2069 intent is to send an exit signal to another process. Note also
2070 that erlang:exit/1 raises an exception that can be caught while
2071 erlang:exit/2 does not cause any exception to be raised.
2072 Warning:
2075 The only scenario that has not been covered by the description
2076 above is when a process P sends an exit signal with reason nor‐
2077 mal to itself, that is erlang:exit(self(), normal). The behavior
2078 in this scenario is as follows:
2079 * If P is trapping exits, the exit signal is transformed into
2081 a message {'EXIT', From, normal}, where From is P's process
2082 identifier, and delivered to P's message queue.
2083 * P exits with reason normal if P is not trapping exits.
2085 Note that the behavior described above is different from when a
2087 process sends an exit signal with reason normal to another
2088 process. This is arguably strange but this behavior is kept for
2089 backward compatibility reasons.
2090 Note:
2093 For some important information about distributed signals, see
2094 the Blocking Signaling Over Distribution section in the Pro‐
2095 cesses chapter of the Erlang Reference Manual .
2096 erlang:external_size(Term) -> integer() >= 0
2099 Types:
2101 Term = term()
2103 Calculates, without doing the encoding, the maximum byte size
2105 for a term encoded in the Erlang external term format. The fol‐
2106 lowing condition applies always:
2107 > Size1 = byte_size(term_to_binary(Term)),
2109 > Size2 = erlang:external_size(Term),
2110 > true = Size1 =< Size2.
2111 true
2112 This is equivalent to a call to:
2114 erlang:external_size(Term, [])
2116 erlang:external_size(Term, Options) -> integer() >= 0
2118 Types:
2120 Term = term()
2122 Options =
2123 [compressed |
2124 {compressed, Level :: 0..9} |
2125 deterministic |
2126 {minor_version, Version :: 0..2} |
2127 local]
2128 Calculates, without doing the encoding, the maximum byte size
2130 for a term encoded in the Erlang external term format. The fol‐
2131 lowing condition applies always:
2132 > Size1 = byte_size(term_to_binary(Term, Options)),
2134 > Size2 = erlang:external_size(Term, Options),
2135 > true = Size1 =< Size2.
2136 true
2137 Option {minor_version, Version} specifies how floats are en‐
2139 coded. For a detailed description, see term_to_binary/2.
2140 float(Number) -> float()
2142 Types:
2144 Number = number()
2146 Returns a float by converting Number to a float, for example:
2148 > float(55).
2150 55.0
2151 Allowed in guard tests.
2153 Note:
2155 If used on the top level in a guard, it tests whether the argu‐
2156 ment is a floating point number; for clarity, use is_float/1 in‐
2157 stead.
2158 When float/1 is used in an expression in a guard, such as
2160 'float(A) == 4.0', it converts a number as described earlier.
2161 float_to_binary(Float) -> binary()
2164 Types:
2166 Float = float()
2168 The same as float_to_binary(Float,[{scientific,20}]).
2170 float_to_binary(Float, Options) -> binary()
2172 Types:
2174 Float = float()
2176 Options = [Option]
2177 Option =
2178 {decimals, Decimals :: 0..253} |
2179 {scientific, Decimals :: 0..249} |
2180 compact | short
2181 Returns a binary corresponding to the text representation of
2183 Float using fixed decimal point formatting. Options behaves in
2184 the same way as float_to_list/2. Examples:
2185 > float_to_binary(7.12, [{decimals, 4}]).
2187 <<"7.1200">>
2188 > float_to_binary(7.12, [{decimals, 4}, compact]).
2189 <<"7.12">>
2190 > float_to_binary(7.12, [{scientific, 3}]).
2191 <<"7.120e+00">>
2192 > float_to_binary(7.12, [short]).
2193 <<"7.12">>
2194 > float_to_binary(0.1+0.2, [short]).
2195 <<"0.30000000000000004">>
2196 > float_to_binary(0.1+0.2)
2197 <<"3.00000000000000044409e-01">>
2198 float_to_list(Float) -> string()
2201 Types:
2203 Float = float()
2205 The same as float_to_list(Float,[{scientific,20}]).
2207 float_to_list(Float, Options) -> string()
2209 Types:
2211 Float = float()
2213 Options = [Option]
2214 Option =
2215 {decimals, Decimals :: 0..253} |
2216 {scientific, Decimals :: 0..249} |
2217 compact | short
2218 Returns a string corresponding to the text representation of
2220 Float using fixed decimal point formatting.
2221 Available options:
2223 * If option decimals is specified, the returned value contains
2225 at most Decimals number of digits past the decimal point. If
2226 the number does not fit in the internal static buffer of 256
2227 bytes, the function throws badarg.
2228 * If option compact is specified, the trailing zeros at the
2230 end of the list are truncated. This option is only meaning‐
2231 ful together with option decimals.
2232 * If option scientific is specified, the float is formatted
2234 using scientific notation with Decimals digits of precision.
2235 * If option short is specified, the float is formatted with
2237 the smallest number of digits that still guarantees that F
2238 =:= list_to_float(float_to_list(F, [short])). When the float
2239 is inside the range (-2⁵³, 2⁵³), the notation that yields
2240 the smallest number of characters is used (scientific nota‐
2241 tion or normal decimal notation). Floats outside the range
2242 (-2⁵³, 2⁵³) are always formatted using scientific notation
2243 to avoid confusing results when doing arithmetic operations.
2244 * If Options is [], the function behaves as float_to_list/1.
2246 Examples:
2248 > float_to_list(7.12, [{decimals, 4}]).
2250 "7.1200"
2251 > float_to_list(7.12, [{decimals, 4}, compact]).
2252 "7.12"
2253 > float_to_list(7.12, [{scientific, 3}]).
2254 "7.120e+00"
2255 > float_to_list(7.12, [short]).
2256 "7.12"
2257 > float_to_list(0.1+0.2, [short]).
2258 "0.30000000000000004"
2259 > float_to_list(0.1+0.2)
2260 "3.00000000000000044409e-01"
2261 In the last example, float_to_list(0.1+0.2) evaluates to
2264 "3.00000000000000044409e-01". The reason for this is explained
2265 in Representation of Floating Point Numbers.
2266 floor(Number) -> integer()
2268 Types:
2270 Number = number()
2272 Returns the largest integer not greater than Number. For exam‐
2274 ple:
2275 > floor(-10.5).
2277 -11
2278 Allowed in guard tests.
2280 erlang:fun_info(Fun) -> [{Item, Info}]
2282 Types:
2284 Fun = function()
2286 Item =
2287 arity | env | index | name | module | new_index |
2288 new_uniq |
2289 pid | type | uniq
2290 Info = term()
2291 Returns a list with information about the fun Fun. Each list el‐
2293 ement is a tuple. The order of the tuples is undefined, and more
2294 tuples can be added in a future release.
2295 Warning:
2297 This BIF is mainly intended for debugging, but it can sometimes
2298 be useful in library functions that need to verify, for example,
2299 the arity of a fun.
2300 Two types of funs have slightly different semantics:
2303 * A fun created by fun M:F/A is called an external fun. Call‐
2305 ing it will always call the function F with arity A in the
2306 latest code for module M. Notice that module M does not even
2307 need to be loaded when the fun fun M:F/A is created.
2308 * All other funs are called local. When a local fun is called,
2310 the same version of the code that created the fun is called
2311 (even if a newer version of the module has been loaded).
2312 The following elements are always present in the list for both
2314 local and external funs:
2315 {type, Type}:
2317 Type is local or external.
2318 {module, Module}:
2320 Module (an atom) is the module name.
2321 If Fun is a local fun, Module is the module in which the fun
2323 is defined.
2324 If Fun is an external fun, Module is the module that the fun
2326 refers to.
2327 {name, Name}:
2329 Name (an atom) is a function name.
2330 If Fun is a local fun, Name is the name of the local func‐
2332 tion that implements the fun. (This name was generated by
2333 the compiler, and is only of informational use. As it is a
2334 local function, it cannot be called directly.) If no code is
2335 currently loaded for the fun, [] is returned instead of an
2336 atom.
2337 If Fun is an external fun, Name is the name of the exported
2339 function that the fun refers to.
2340 {arity, Arity}:
2342 Arity is the number of arguments that the fun is to be
2343 called with.
2344 {env, Env}:
2346 Env (a list) is the environment or free variables for the
2347 fun. For external funs, the returned list is always empty.
2348 The following elements are only present in the list if Fun is
2350 local:
2351 {pid, Pid}:
2353 Pid is the process identifier of the process that originally
2354 created the fun.
2355 It might point to the init process if the Fun was statically
2357 allocated when module was loaded (this optimisation is per‐
2358 formed for local functions that do not capture the environ‐
2359 ment).
2360 Change:
2362 In Erlang/OTP 27, we plan to change the return value so that
2363 it always points to the local init process, regardless of
2364 which process or node the fun was originally created on. See
2365 Upcoming Potential Incompatibilities .
2366 {index, Index}:
2369 Index (an integer) is an index into the module fun table.
2370 {new_index, Index}:
2372 Index (an integer) is an index into the module fun table.
2373 {new_uniq, Uniq}:
2375 Uniq (a binary) is a unique value for this fun. It is calcu‐
2376 lated from the compiled code for the entire module.
2377 {uniq, Uniq}:
2379 Uniq (an integer) is a unique value for this fun. As from
2380 Erlang/OTP R15, this integer is calculated from the compiled
2381 code for the entire module. Before Erlang/OTP R15, this in‐
2382 teger was based on only the body of the fun.
2383 erlang:fun_info(Fun, Item) -> {Item, Info}
2385 Types:
2387 Fun = function()
2389 Item = fun_info_item()
2390 Info = term()
2391 fun_info_item() =
2392 arity | env | index | name | module | new_index | new_uniq |
2393 pid | type | uniq
2394 Returns information about Fun as specified by Item, in the form
2396 {Item,Info}.
2397 For any fun, Item can be any of the atoms module, name, arity,
2399 env, or type.
2400 For a local fun, Item can also be any of the atoms index,
2402 new_index, new_uniq, uniq, and pid. For an external fun, the
2403 value of any of these items is always the atom undefined.
2404 See erlang:fun_info/1.
2406 erlang:fun_to_list(Fun) -> String :: string()
2408 Types:
2410 Fun = function()
2412 Returns String that represents the code that created Fun.
2414 String has the following form, if Fun was created by a fun ex‐
2416 pression of the form fun ModuleName:FuncName/Arity:
2417 "fun ModuleName:FuncName/Arity"
2419 The form of String when Fun is created from other types of fun
2421 expressions differs depending on if the fun expression was exe‐
2422 cuted while executing compiled code or if the fun expression was
2423 executed while executing uncompiled code (uncompiled escripts,
2424 the Erlang shell, and other code executed by the erl_eval mod‐
2425 ule):
2426 compiled code:
2428 "#Fun<M.I.U>", where M, I and U correspond to the values
2429 named module, index and uniq in the result of er‐
2430 lang:fun_info(Fun).
2431 uncompiled code:
2433 All funs created from fun expressions in uncompiled code
2434 with the same arity are mapped to the same list by
2435 fun_to_list/1.
2436 Note:
2438 Generally, one can not use fun_to_list/1 to check if two funs
2439 are equal as fun_to_list/1 does not take the fun's environment
2440 into account. See erlang:fun_info/1 for how to get the environ‐
2441 ment of a fun.
2442 Change:
2445 The output of fun_to_list/1 can differ between Erlang implemen‐
2446 tations and may change in future versions.
2447 Examples:
2450 -module(test).
2452 -export([add/1, add2/0, fun_tuple/0]).
2453 add(A) -> fun(B) -> A + B end.
2454 add2() -> fun add/1.
2455 fun_tuple() -> {fun() -> 1 end, fun() -> 1 end}.
2456 > {fun test:add/1, test:add2()}.
2459 {fun test:add/1,#Fun<test.1.107738983>}
2460 Explanation: fun test:add/1 is upgradable but test:add2() is not
2463 upgradable.
2464 > {test:add(1), test:add(42)}.
2466 {#Fun<test.0.107738983>,#Fun<test.0.107738983>}
2467 Explanation: test:add(1) and test:add(42) has the same string
2470 representation as the environment is not taken into account.
2471 >test:fun_tuple().
2473 {#Fun<test.2.107738983>,#Fun<test.3.107738983>}
2474 Explanation: The string representations differ because the funs
2477 come from different fun expressions.
2478 > {fun() -> 1 end, fun() -> 1 end}. >
2480 {#Fun<erl_eval.45.97283095>,#Fun<erl_eval.45.97283095>}
2481 Explanation: All funs created from fun expressions of this form
2484 in uncompiled code with the same arity are mapped to the same
2485 list by fun_to_list/1.
2486 erlang:function_exported(Module, Function, Arity) -> boolean()
2488 Types:
2490 Module = module()
2492 Function = atom()
2493 Arity = arity()
2494 Returns true if the module Module is current and contains an ex‐
2496 ported function Function/Arity, or if there is a BIF (a built-in
2497 function implemented in C) with the specified name, otherwise
2498 returns false.
2499 garbage_collect() -> true
2501 Forces an immediate garbage collection of the executing process.
2503 The function is not to be used unless it has been noticed (or
2504 there are good reasons to suspect) that the spontaneous garbage
2505 collection will occur too late or not at all.
2506 Warning:
2508 Improper use can seriously degrade system performance.
2509 garbage_collect(Pid) -> GCResult
2512 Types:
2514 Pid = pid()
2516 GCResult = boolean()
2517 The same as garbage_collect(Pid, []).
2519 garbage_collect(Pid, OptionList) -> GCResult | async
2521 Types:
2523 Pid = pid()
2525 RequestId = term()
2526 Option = {async, RequestId} | {type, major | minor}
2527 OptionList = [Option]
2528 GCResult = boolean()
2529 Garbage collects the node local process identified by Pid.
2531 Option:
2533 {async, RequestId}:
2535 The function garbage_collect/2 returns the value async imme‐
2536 diately after the request has been sent. When the request
2537 has been processed, the process that called this function is
2538 passed a message on the form {garbage_collect, RequestId,
2539 GCResult}.
2540 {type, 'major' | 'minor'}:
2542 Triggers garbage collection of requested type. Default value
2543 is 'major', which would trigger a fullsweep GC. The option
2544 'minor' is considered a hint and may lead to either minor or
2545 major GC run.
2546 If Pid equals self(), and no async option has been passed, the
2548 garbage collection is performed at once, that is, the same as
2549 calling garbage_collect/0. Otherwise a request for garbage col‐
2550 lection is sent to the process identified by Pid, and will be
2551 handled when appropriate. If no async option has been passed,
2552 the caller blocks until GCResult is available and can be re‐
2553 turned.
2554 GCResult informs about the result of the garbage collection re‐
2556 quest as follows:
2557 true:
2559 The process identified by Pid has been garbage collected.
2560 false:
2562 No garbage collection was performed, as the process identi‐
2563 fied by Pid terminated before the request could be satis‐
2564 fied.
2565 Notice that the same caveats apply as for garbage_collect/0.
2567 Failures:
2569 badarg:
2571 If Pid is not a node local process identifier.
2572 badarg:
2574 If OptionList is an invalid list of options.
2575 get() -> [{Key, Val}]
2577 Types:
2579 Key = Val = term()
2581 Returns the process dictionary as a list of {Key, Val} tuples.
2583 The items in the returned list can be in any order. Example:
2584 > put(key1, merry),
2586 put(key2, lambs),
2587 put(key3, {are, playing}),
2588 get().
2589 [{key1,merry},{key2,lambs},{key3,{are,playing}}]
2590 get(Key) -> Val | undefined
2592 Types:
2594 Key = Val = term()
2596 Returns the value Val associated with Key in the process dictio‐
2598 nary, or undefined if Key does not exist. The expected time com‐
2599 plexity for the current implementation of this function is O(1)
2600 and the worst case time complexity is O(N), where N is the num‐
2601 ber of items in the process dictionary. Example:
2602 > put(key1, merry),
2604 put(key2, lambs),
2605 put({any, [valid, term]}, {are, playing}),
2606 get({any, [valid, term]}).
2607 {are,playing}
2608 erlang:get_cookie() -> Cookie | nocookie
2610 Types:
2612 Cookie = atom()
2614 Returns the magic cookie of the local node if the node is alive,
2616 otherwise the atom nocookie. This value is set by set_cookie/1.
2617 erlang:get_cookie(Node) -> Cookie | nocookie
2619 Types:
2621 Node = node()
2623 Cookie = atom()
2624 Returns the magic cookie for node Node if the local node is
2626 alive, otherwise the atom nocookie. This value is set by
2627 set_cookie/2.
2628 get_keys() -> [Key]
2630 Types:
2632 Key = term()
2634 Returns a list of all keys present in the process dictionary.
2636 The items in the returned list can be in any order. Example:
2637 > put(dog, {animal,1}),
2639 put(cow, {animal,2}),
2640 put(lamb, {animal,3}),
2641 get_keys().
2642 [dog,cow,lamb]
2643 get_keys(Val) -> [Key]
2645 Types:
2647 Val = Key = term()
2649 Returns a list of keys that are associated with the value Val in
2651 the process dictionary. The items in the returned list can be in
2652 any order. Example:
2653 > put(mary, {1, 2}),
2655 put(had, {1, 2}),
2656 put(a, {1, 2}),
2657 put(little, {1, 2}),
2658 put(dog, {1, 3}),
2659 put(lamb, {1, 2}),
2660 get_keys({1, 2}).
2661 [mary,had,a,little,lamb]
2662 group_leader() -> pid()
2664 Returns the process identifier of the group leader for the
2666 process evaluating the function.
2667 Every process is a member of some process group and all groups
2669 have a group leader. All I/O from the group is channeled to the
2670 group leader. When a new process is spawned, it gets the same
2671 group leader as the spawning process.
2672 Initially, at system startup, init is both its own group leader
2674 and the group leader of all processes. During the boot of a sys‐
2675 tem the group leader for processes will be changed depending on
2676 the need of the system. Some examples where this is done are:
2677 * When an application is started, the top supervisor of that
2679 application will have its group leader set to the applica‐
2680 tion master. See application:start/2 for more details.
2681 * When running tests, both common_test and eunit set the group
2683 leader in order to capture any I/O from the testcase.
2684 * The interactive shell sets the group leader to intercept
2686 I/O.
2687 group_leader(GroupLeader, Pid) -> true
2689 Types:
2691 GroupLeader = Pid = pid()
2693 Sets the group leader of Pid to GroupLeader. Typically, this is
2695 used when a process started from a certain shell is to have an‐
2696 other group leader than init.
2697 The group leader should be rarely changed in applications with a
2699 supervision tree, because OTP assumes the group leader of their
2700 processes is their application master.
2701 Setting the group leader follows the signal ordering guarantees
2703 described in the Processes Chapter in the Erlang Reference Man‐
2704 ual .
2705 See also group_leader/0 and OTP design principles related to
2707 starting and stopping applications.
2708 Note:
2710 For some important information about distributed signals, see
2711 the Blocking Signaling Over Distribution section in the Pro‐
2712 cesses chapter of the Erlang Reference Manual .
2713 halt() -> no_return()
2716 The same as calling halt(0, []). Example:
2718 > halt().
2720 os_prompt%
2721 halt(Status :: integer() >= 0) -> no_return()
2723 The same as calling halt(Status, []). Example:
2725 > halt(17).
2727 os_prompt% echo $?
2728 17
2729 os_prompt%
2730 halt(Abort :: abort) -> no_return()
2732 The same as calling halt(abort, []).
2734 halt(CrashDumpSlogan :: string()) -> no_return()
2736 The same as calling halt(CrashDumpSlogan, []).
2738 halt(Status :: integer() >= 0, Options :: halt_options()) ->
2740 no_return()
2741 Types:
2743 halt_options() = [{flush, boolean()}]
2745 Halt the runtime system with status code Status.
2747 Note:
2749 On many platforms, the OS supports only status codes 0-255. A
2750 too large status code is truncated by clearing the high bits.
2751 Currently the following options are valid:
2754 {flush, EnableFlushing}:
2756 If EnableFlushing equals true, which also is the default be‐
2757 havior, the runtime system will perform the following opera‐
2758 tions before terminating:
2759 * Flush all outstanding output.
2761 * Send all Erlang ports exit signals and wait for them to
2763 exit.
2764 * Wait for all async threads to complete all outstanding
2766 async jobs.
2767 * Call all installed NIF on halt callbacks.
2769 * Wait for all ongoing NIF calls with the delay halt set‐
2771 ting enabled to return.
2772 * Call all installed atexit/on_exit callbacks.
2774 If EnableFlushing equals false, the runtime system will ter‐
2776 minate immediately without performing any of the above
2777 listed operations.
2778 Change:
2780 Runtime systems prior to OTP 26.0 called all installed
2781 atexit/on_exit callbacks also when flush was disabled, but as
2782 of OTP 26.0 this is no longer the case.
2783 halt(Abort :: abort, Options :: halt_options()) -> no_return()
2786 Types:
2788 halt_options() = [{flush, boolean()}]
2790 Halt the Erlang runtime system by aborting and produce a core
2792 dump if core dumping has been enabled in the environment that
2793 the runtime system is executing in.
2794 Note:
2796 The {flush, boolean()} option will be ignored, and flushing will
2797 be disabled.
2798 halt(CrashDumpSlogan :: string(), Options :: halt_options()) ->
2801 no_return()
2802 Types:
2804 halt_options() = [{flush, boolean()}]
2806 Halt the Erlang runtime system and generate an Erlang crash
2808 dump. The string CrashDumpSlogan will be used as slogan in the
2809 Erlang crash dump created. The slogan will be trunkated if
2810 CrashDumpSlogan is longer than 1023 characters.
2811 Note:
2813 The {flush, boolean()} option will be ignored, and flushing will
2814 be disabled.
2815 Behavior changes compared to earlier versions:
2818 * Before OTP 24.2, the slogan was truncated if CrashDumpSlogan
2820 was longer than 200 characters. Now it will be truncated if
2821 longer than 1023 characters.
2822 * Before OTP 20.1, only code points in the range 0-255 were
2824 accepted in the slogan. Now any Unicode string is valid.
2825 hd(List) -> Head
2827 Types:
2829 List = nonempty_maybe_improper_list()
2831 Head = term()
2832 Returns the head of List, that is, the first element.
2834 It works with improper lists.
2836 Examples:
2838 > hd([1,2,3,4,5]).
2840 1
2841 > hd([first, second, third, so_on | improper_end]).
2843 first
2844 Allowed in guard tests.
2846 Failure: badarg if List is an empty list [].
2848 erlang:hibernate(Module, Function, Args) -> no_return()
2850 Types:
2852 Module = module()
2854 Function = atom()
2855 Args = [term()]
2856 Puts the calling process into a wait state where its memory al‐
2858 location has been reduced as much as possible. This is useful if
2859 the process does not expect to receive any messages soon.
2860 The process is awaken when a message is sent to it, and control
2862 resumes in Module:Function with the arguments specified by Args
2863 with the call stack emptied, meaning that the process terminates
2864 when that function returns. Thus erlang:hibernate/3 never re‐
2865 turns to its caller. The resume function Module:Function/Arity
2866 must be exported (Arity =:= length(Args)).
2867 If the process has any message in its message queue, the process
2869 is awakened immediately in the same way as described earlier.
2870 In more technical terms, erlang:hibernate/3 discards the call
2872 stack for the process, and then garbage collects the process.
2873 After this, all live data is in one continuous heap. The heap is
2874 then shrunken to the exact same size as the live data that it
2875 holds (even if that size is less than the minimum heap size for
2876 the process).
2877 If the size of the live data in the process is less than the
2879 minimum heap size, the first garbage collection occurring after
2880 the process is awakened ensures that the heap size is changed to
2881 a size not smaller than the minimum heap size.
2882 Notice that emptying the call stack means that any surrounding
2884 catch is removed and must be re-inserted after hibernation. One
2885 effect of this is that processes started using proc_lib (also
2886 indirectly, such as gen_server processes), are to use
2887 proc_lib:hibernate/3 instead, to ensure that the exception han‐
2888 dler continues to work when the process wakes up.
2889 erlang:insert_element(Index, Tuple1, Term) -> Tuple2
2891 Types:
2893 Index = integer() >= 1
2895 1..tuple_size(Tuple1) + 1
2896 Tuple1 = Tuple2 = tuple()
2897 Term = term()
2898 Returns a new tuple with element Term inserted at position Index
2900 in tuple Tuple1. All elements from position Index and upwards
2901 are pushed one step higher in the new tuple Tuple2. Example:
2902 > erlang:insert_element(2, {one, two, three}, new).
2904 {one,new,two,three}
2905 integer_to_binary(Integer) -> binary()
2907 Types:
2909 Integer = integer()
2911 Returns a binary corresponding to the text representation of In‐
2913 teger, for example:
2914 > integer_to_binary(77).
2916 <<"77">>
2917 integer_to_binary(Integer, Base) -> binary()
2919 Types:
2921 Integer = integer()
2923 Base = 2..36
2924 Returns a binary corresponding to the text representation of In‐
2926 teger in base Base, for example:
2927 > integer_to_binary(1023, 16).
2929 <<"3FF">>
2930 integer_to_list(Integer) -> string()
2932 Types:
2934 Integer = integer()
2936 Returns a string corresponding to the text representation of In‐
2938 teger, for example:
2939 > integer_to_list(77).
2941 "77"
2942 integer_to_list(Integer, Base) -> string()
2944 Types:
2946 Integer = integer()
2948 Base = 2..36
2949 Returns a string corresponding to the text representation of In‐
2951 teger in base Base, for example:
2952 > integer_to_list(1023, 16).
2954 "3FF"
2955 iolist_size(Item) -> integer() >= 0
2957 Types:
2959 Item = iolist() | binary()
2961 Returns an integer, that is the size in bytes, of the binary
2963 that would be the result of iolist_to_binary(Item), for example:
2964 > iolist_size([1,2|<<3,4>>]).
2966 4
2967 iolist_to_binary(IoListOrBinary) -> binary()
2969 Types:
2971 IoListOrBinary = iolist() | binary()
2973 Returns a binary that is made from the integers and binaries in
2975 IoListOrBinary, for example:
2976 > Bin1 = <<1,2,3>>.
2978 <<1,2,3>>
2979 > Bin2 = <<4,5>>.
2980 <<4,5>>
2981 > Bin3 = <<6>>.
2982 <<6>>
2983 > iolist_to_binary([Bin1,1,[2,3,Bin2],4|Bin3]).
2984 <<1,2,3,1,2,3,4,5,4,6>>
2985 erlang:iolist_to_iovec(IoListOrBinary) -> iovec()
2987 Types:
2989 IoListOrBinary = iolist() | binary()
2991 Returns an iovec that is made from the integers and binaries in
2993 IoListOrBinary. This function is useful when you want to flatten
2994 an iolist but you do not need a single binary. This can be use‐
2995 ful for passing the data to nif functions such as enif_in‐
2996 spect_iovec or do more efficient message passing. The advantage
2997 of using this function over iolist_to_binary/1 is that it does
2998 not have to copy off-heap binaries. Example:
2999 > Bin1 = <<1,2,3>>.
3001 <<1,2,3>>
3002 > Bin2 = <<4,5>>.
3003 <<4,5>>
3004 > Bin3 = <<6>>.
3005 <<6>>
3006 %% If you pass small binaries and integers it works as iolist_to_binary
3007 > erlang:iolist_to_iovec([Bin1,1,[2,3,Bin2],4|Bin3]).
3008 [<<1,2,3,1,2,3,4,5,4,6>>]
3009 %% If you pass larger binaries, they are split and returned in a form
3010 %% optimized for calling the C function writev.
3011 > erlang:iolist_to_iovec([<<1>>,<<2:8096>>,<<3:8096>>]).
3012 [<<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,
3013 0,...>>,
3014 <<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,
3015 ...>>,
3016 <<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,...>>]
3017 is_alive() -> boolean()
3019 Returns true if the local node is alive (that is, if the node
3021 can be part of a distributed system), otherwise false. A node is
3022 alive if it is started with:
3023 * "erl -name LONGNAME" or,
3025 * "erl -sname SHORTNAME".
3027 A node can also be alive if it has got a name from a call to
3029 net_kernel:start/2 and has not been stopped by a call to
3030 net_kernel:stop/0.
3031 is_atom(Term) -> boolean()
3033 Types:
3035 Term = term()
3037 Returns true if Term is an atom, otherwise false.
3039 Allowed in guard tests.
3041 is_binary(Term) -> boolean()
3043 Types:
3045 Term = term()
3047 Returns true if Term is a binary, otherwise false.
3049 A binary always contains a complete number of bytes.
3051 Allowed in guard tests.
3053 is_bitstring(Term) -> boolean()
3055 Types:
3057 Term = term()
3059 Returns true if Term is a bitstring (including a binary), other‐
3061 wise false.
3062 Allowed in guard tests.
3064 is_boolean(Term) -> boolean()
3066 Types:
3068 Term = term()
3070 Returns true if Term is the atom true or the atom false (that
3072 is, a boolean). Otherwise returns false.
3073 Allowed in guard tests.
3075 erlang:is_builtin(Module, Function, Arity) -> boolean()
3077 Types:
3079 Module = module()
3081 Function = atom()
3082 Arity = arity()
3083 This BIF is useful for builders of cross-reference tools.
3085 Returns true if Module:Function/Arity is a BIF implemented in C,
3087 otherwise false.
3088 is_float(Term) -> boolean()
3090 Types:
3092 Term = term()
3094 Returns true if Term is a floating point number, otherwise
3096 false.
3097 Allowed in guard tests.
3099 is_function(Term) -> boolean()
3101 Types:
3103 Term = term()
3105 Returns true if Term is a fun, otherwise false.
3107 Allowed in guard tests.
3109 is_function(Term, Arity) -> boolean()
3111 Types:
3113 Term = term()
3115 Arity = arity()
3116 Returns true if Term is a fun that can be applied with Arity
3118 number of arguments, otherwise false.
3119 Allowed in guard tests.
3121 is_integer(Term) -> boolean()
3123 Types:
3125 Term = term()
3127 Returns true if Term is an integer, otherwise false.
3129 Allowed in guard tests.
3131 is_list(Term) -> boolean()
3133 Types:
3135 Term = term()
3137 Returns true if Term is a list with zero or more elements, oth‐
3139 erwise false.
3140 Allowed in guard tests.
3142 is_map(Term) -> boolean()
3144 Types:
3146 Term = term()
3148 Returns true if Term is a map, otherwise false.
3150 Allowed in guard tests.
3152 is_map_key(Key, Map) -> boolean()
3154 Types:
3156 Key = term()
3158 Map = map()
3159 Returns true if map Map contains Key and returns false if it
3161 does not contain the Key.
3162 The call fails with a {badmap,Map} exception if Map is not a
3164 map.
3165 Example:
3167 > Map = #{"42" => value}.
3169 #{"42" => value}
3170 > is_map_key("42",Map).
3171 true
3172 > is_map_key(value,Map).
3173 false
3174 Allowed in guard tests.
3176 is_number(Term) -> boolean()
3178 Types:
3180 Term = term()
3182 Returns true if Term is an integer or a floating point number.
3184 Otherwise returns false.
3185 Allowed in guard tests.
3187 is_pid(Term) -> boolean()
3189 Types:
3191 Term = term()
3193 Returns true if Term is a process identifier, otherwise false.
3195 Allowed in guard tests.
3197 is_port(Term) -> boolean()
3199 Types:
3201 Term = term()
3203 Returns true if Term is a port identifier, otherwise false.
3205 Allowed in guard tests.
3207 is_process_alive(Pid) -> boolean()
3209 Types:
3211 Pid = pid()
3213 Pid must refer to a process at the local node.
3215 Returns true if the process exists and is alive, that is, is not
3217 exiting and has not exited. Otherwise returns false.
3218 If process P1 calls is_process_alive(P2Pid) it is guaranteed
3220 that all signals, sent from P1 to P2 (P2 is the process with
3221 identifier P2Pid) before the call, will be delivered to P2 be‐
3222 fore the aliveness of P2 is checked. This guarantee means that
3223 one can use is_process_alive/1 to let a process P1 wait until a
3224 process P2, which has got an exit signal with reason kill from
3225 P1, is killed. Example:
3226 exit(P2Pid, kill),
3228 % P2 might not be killed
3229 is_process_alive(P2Pid),
3230 % P2 is not alive (the call above always return false)
3231 See the documentation about signals and erlang:exit/2 for more
3234 information about signals and exit signals.
3235 is_record(Term, RecordTag) -> boolean()
3237 Types:
3239 Term = term()
3241 RecordTag = atom()
3242 Returns true if Term is a tuple and its first element is Record‐
3244 Tag. Otherwise returns false.
3245 Note:
3247 Normally the compiler treats calls to is_record/2 especially. It
3248 emits code to verify that Term is a tuple, that its first ele‐
3249 ment is RecordTag, and that the size is correct. However, if
3250 RecordTag is not a literal atom, the BIF is_record/2 is called
3251 instead and the size of the tuple is not verified.
3252 Allowed in guard tests, if RecordTag is a literal atom.
3255 is_record(Term, RecordTag, Size) -> boolean()
3257 Types:
3259 Term = term()
3261 RecordTag = atom()
3262 Size = integer() >= 0
3263 RecordTag must be an atom.
3265 Returns true if Term is a tuple, its first element is RecordTag,
3267 and its size is Size. Otherwise returns false.
3268 Allowed in guard tests if RecordTag is a literal atom and Size
3270 is a literal integer.
3271 Note:
3273 This BIF is documented for completeness. Usually is_record/2 is
3274 to be used.
3275 is_reference(Term) -> boolean()
3278 Types:
3280 Term = term()
3282 Returns true if Term is a reference, otherwise false.
3284 Allowed in guard tests.
3286 is_tuple(Term) -> boolean()
3288 Types:
3290 Term = term()
3292 Returns true if Term is a tuple, otherwise false.
3294 Allowed in guard tests.
3296 length(List) -> integer() >= 0
3298 Types:
3300 List = [term()]
3302 Returns the length of List, for example:
3304 > length([1,2,3,4,5,6,7,8,9]).
3306 9
3307 Allowed in guard tests.
3309 link(PidOrPort) -> true
3311 Types:
3313 PidOrPort = pid() | port()
3315 Sets up and activates a link between the calling process and an‐
3317 other process or a port identified by PidOrPort. We will from
3318 here on call the identified process or port linkee. If the lin‐
3319 kee is a port, it must reside on the same node as the caller.
3320 If one of the participants of a link terminates, it will send an
3322 exit signal to the other participant. The exit signal will con‐
3323 tain the exit reason of the terminated participant. Other cases
3324 when exit signals are triggered due to a link are when no linkee
3325 exist (noproc exit reason) and when the connection between
3326 linked processes on different nodes is lost or cannot be estab‐
3327 lished (noconnection exit reason).
3328 An existing link can be removed by calling unlink/1. For more
3330 information on links and exit signals due to links, see the Pro‐
3331 cesses chapter in the Erlang Reference Manual :
3332 * Links
3334 * Sending Exit Signals
3336 * Receiving Exit Signals
3338 For historical reasons, link/1 has a strange semi-synchronous
3340 behavior when it is "cheap" to check if the linkee exists or
3341 not, and the caller does not trap exits. If the above is true
3342 and the linkee does not exist, link/1 will raise a noproc error
3343 exception. The expected behavior would instead have been that
3344 link/1 returned true, and the caller later was sent an exit sig‐
3345 nal with noproc exit reason, but this is unfortunately not the
3346 case. The noproc exception is not to be confused with an exit
3347 signal with exit reason noproc. Currently it is "cheap" to check
3348 if the linkee exists when it is supposed to reside on the same
3349 node as the calling process.
3350 The link setup and activation is performed asynchronously. If
3352 the link already exists, or if the caller attempts to create a
3353 link to itself, nothing is done. A detailed description of the
3354 link protocol can be found in the Distribution Protocol chapter
3355 of the ERTS User's Guide .
3356 Note:
3358 For some important information about distributed signals, see
3359 the Blocking Signaling Over Distribution section in the Pro‐
3360 cesses chapter of the Erlang Reference Manual .
3361 Failure:
3364 * badarg if PidOrPort does not identify a process or a node
3366 local port.
3367 * noproc linkee does not exist and it is "cheap" to check if
3369 it exists as described above.
3370 list_to_atom(String) -> atom()
3372 Types:
3374 String = string()
3376 Returns the atom whose text representation is String.
3378 As from Erlang/OTP 20, String may contain any Unicode character.
3380 Earlier versions allowed only ISO-latin-1 characters as the im‐
3381 plementation did not allow Unicode characters above 255.
3382 Note:
3384 The number of characters that are permitted in an atom name is
3385 limited. The default limits can be found in the efficiency
3386 guide (section Advanced).
3387 Note:
3390 There is configurable limit on how many atoms that can exist and
3391 atoms are not garbage collected. Therefore, it is recommended to
3392 consider if list_to_existing_atom/1 is a better option than
3393 list_to_atom/1. The default limits can be found in the effi‐
3394 ciency guide (section Advanced).
3395 Example:
3398 > list_to_atom("Erlang").
3400 list_to_binary(IoList) -> binary()
3402 Types:
3404 IoList = iolist()
3406 Returns a binary that is made from the integers and binaries in
3408 IoList, for example:
3409 > Bin1 = <<1,2,3>>.
3411 <<1,2,3>>
3412 > Bin2 = <<4,5>>.
3413 <<4,5>>
3414 > Bin3 = <<6>>.
3415 <<6>>
3416 > list_to_binary([Bin1,1,[2,3,Bin2],4|Bin3]).
3417 <<1,2,3,1,2,3,4,5,4,6>>
3418 list_to_bitstring(BitstringList) -> bitstring()
3420 Types:
3422 BitstringList = bitstring_list()
3424 bitstring_list() =
3425 maybe_improper_list(byte() | bitstring() | bitstring_list(),
3426 bitstring() | [])
3427 Returns a bitstring that is made from the integers and bit‐
3429 strings in BitstringList. (The last tail in BitstringList is al‐
3430 lowed to be a bitstring.) Example:
3431 > Bin1 = <<1,2,3>>.
3433 <<1,2,3>>
3434 > Bin2 = <<4,5>>.
3435 <<4,5>>
3436 > Bin3 = <<6,7:4>>.
3437 <<6,7:4>>
3438 > list_to_bitstring([Bin1,1,[2,3,Bin2],4|Bin3]).
3439 <<1,2,3,1,2,3,4,5,4,6,7:4>>
3440 list_to_existing_atom(String) -> atom()
3442 Types:
3444 String = string()
3446 Returns the atom whose text representation is String, but only
3448 if there already exists such atom. An atom exists if it has been
3449 created by the run-time system by either loading code or creat‐
3450 ing a term in which the atom is part.
3451 Failure: badarg if there does not already exist an atom whose
3453 text representation is String.
3454 Note:
3456 Note that the compiler may optimize away atoms. For example, the
3457 compiler will rewrite atom_to_list(some_atom) to "some_atom". If
3458 that expression is the only mention of the atom some_atom in the
3459 containing module, the atom will not be created when the module
3460 is loaded, and a subsequent call to list_to_exist‐
3461 ing_atom("some_atom") will fail.
3462 list_to_float(String) -> float()
3465 Types:
3467 String = string()
3469 Returns the float whose text representation is String, for exam‐
3471 ple:
3472 > list_to_float("2.2017764e+0").
3474 2.2017764
3475 The float string format is the same as the format for Erlang
3477 float literals except for that underscores are not permitted.
3478 Failure: badarg if String contains a bad representation of a
3480 float.
3481 list_to_integer(String) -> integer()
3483 Types:
3485 String = string()
3487 Returns an integer whose text representation is String, for ex‐
3489 ample:
3490 > list_to_integer("123").
3492 123
3493 > list_to_integer("-123").
3495 -123
3496 > list_to_integer("+123234982304982309482093833234234").
3498 123234982304982309482093833234234
3499 String must contain at least one digit character and can have an
3501 optional prefix consisting of a single "+" or "-" character
3502 (that is, String must match the regular expression
3503 "^[+-]?[0-9]+$").
3504 Failure: badarg if String contains a bad representation of an
3506 integer.
3507 list_to_integer(String, Base) -> integer()
3509 Types:
3511 String = string()
3513 Base = 2..36
3514 Returns an integer whose text representation in base Base is
3516 String, for example:
3517 > list_to_integer("3FF", 16).
3519 1023
3520 > list_to_integer("+3FF", 16).
3522 1023
3523 > list_to_integer("3ff", 16).
3525 1023
3526 > list_to_integer("3fF", 16).
3528 1023
3529 > list_to_integer("-3FF", 16).
3531 -1023
3532 For example, when Base is 16, String must match the regular ex‐
3534 pression "^[+-]?([0-9]|[A-F]|[a-f])+$".
3535 Failure: badarg if String contains a bad representation of an
3537 integer.
3538 list_to_pid(String) -> pid()
3540 Types:
3542 String = string()
3544 Returns a process identifier whose text representation is a
3546 String, for example:
3547 > list_to_pid("<0.4.1>").
3549 <0.4.1>
3550 Failure: badarg if String contains a bad representation of a
3552 process identifier.
3553 Warning:
3555 This BIF is intended for debugging and is not to be used in ap‐
3556 plication programs.
3557 list_to_port(String) -> port()
3560 Types:
3562 String = string()
3564 Returns a port identifier whose text representation is a String,
3566 for example:
3567 > list_to_port("#Port<0.4>").
3569 #Port<0.4>
3570 Failure: badarg if String contains a bad representation of a
3572 port identifier.
3573 Warning:
3575 This BIF is intended for debugging and is not to be used in ap‐
3576 plication programs.
3577 list_to_ref(String) -> reference()
3580 Types:
3582 String = string()
3584 Returns a reference whose text representation is a String, for
3586 example:
3587 > list_to_ref("#Ref<0.4192537678.4073193475.71181>").
3589 #Ref<0.4192537678.4073193475.71181>
3590 Failure: badarg if String contains a bad representation of a
3592 reference.
3593 Warning:
3595 This BIF is intended for debugging and is not to be used in ap‐
3596 plication programs.
3597 list_to_tuple(List) -> tuple()
3600 Types:
3602 List = [term()]
3604 Returns a tuple corresponding to List, for example
3606 > list_to_tuple([share, ['Ericsson_B', 163]]).
3608 {share, ['Ericsson_B', 163]}
3609 List can contain any Erlang terms.
3611 load_module(Module, Binary) -> {module, Module} | {error, Reason}
3613 Types:
3615 Module = module()
3617 Binary = binary()
3618 Reason =
3619 badfile | not_purged | on_load |
3620 {features_not_allowed, [atom()]}
3621 If Binary contains the object code for module Module, this BIF
3623 loads that object code. If the code for module Module already
3624 exists, all export references are replaced so they point to the
3625 newly loaded code. The previously loaded code is kept in the
3626 system as old code, as there can still be processes executing
3627 that code.
3628 Returns either {module, Module}, or {error, Reason} if loading
3630 fails. Reason is one of the following:
3631 badfile:
3633 The object code in Binary has an incorrect format or the ob‐
3634 ject code contains code for another module than Module.
3635 not_purged:
3637 Binary contains a module that cannot be loaded because old
3638 code for this module already exists.
3639 on_load:
3641 The code in Binary contains an on_load declaration that must
3642 be executed before Binary can become the current code. Any
3643 previous current code for Module will remain until the
3644 on_load call has finished.
3645 not_allowed:
3647 The code in Binary has been compiled with features that are
3648 currently not enabled in the runtime system.
3649 Warning:
3651 This BIF is intended for the code server (see code(3)) and is
3652 not to be used elsewhere.
3653 erlang:load_nif(Path, LoadInfo) -> ok | Error
3656 Types:
3658 Path = string()
3660 LoadInfo = term()
3661 Error = {error, {Reason, Text :: string()}}
3662 Reason =
3663 load_failed | bad_lib | load | reload | upgrade |
3664 old_code
3665 Loads and links a dynamic library containing native implemented
3667 functions (NIFs) for a module. Path is a file path to the share‐
3668 able object/dynamic library file minus the OS-dependent file ex‐
3669 tension (.so for Unix and .dll for Windows). Notice that on most
3670 OSs the library has to have a different name on disc when an up‐
3671 grade of the nif is done. If the name is the same, but the con‐
3672 tents differ, the old library may be loaded instead. For infor‐
3673 mation on how to implement a NIF library, see erl_nif(3).
3674 LoadInfo can be any term. It is passed on to the library as part
3676 of the initialization. A good practice is to include a module
3677 version number to support future code upgrade scenarios.
3678 The call to load_nif/2 must be made directly from the Erlang
3680 code of the module that the NIF library belongs to. It returns
3681 either ok, or {error,{Reason,Text}} if loading fails. Reason is
3682 one of the following atoms while Text is a human readable string
3683 that can give more information about the failure:
3684 load_failed:
3686 The OS failed to load the NIF library.
3687 bad_lib:
3689 The library did not fulfill the requirements as a NIF li‐
3690 brary of the calling module.
3691 load | upgrade:
3693 The corresponding library callback was unsuccessful.
3694 reload:
3696 A NIF library is already loaded for this module instance.
3697 The previously deprecated reload feature was removed in OTP
3698 20.
3699 old_code:
3701 The call to load_nif/2 was made from the old code of a mod‐
3702 ule that has been upgraded; this is not allowed.
3703 If the -nifs() attribute is used (which is recommended), all
3705 NIFs in the dynamic library much be declared as such for
3706 load_nif/2 to succeed. On the other hand, all functions declared
3707 with the -nifs() attribute do not have to be implemented by the
3708 dynamic library. This allows a target independent Erlang file to
3709 contain fallback implementations for functions that may lack NIF
3710 support depending on target OS/hardware platform.
3711 erlang:loaded() -> [Module]
3713 Types:
3715 Module = module()
3717 Returns a list of all loaded Erlang modules (current and old
3719 code), including preloaded modules.
3720 See also code(3).
3722 erlang:localtime() -> DateTime
3724 Types:
3726 DateTime = calendar:datetime()
3728 Returns the current local date and time, {{Year, Month, Day},
3730 {Hour, Minute, Second}}, for example:
3731 > erlang:localtime().
3733 {{1996,11,6},{14,45,17}}
3734 The time zone and Daylight Saving Time correction depend on the
3736 underlying OS. The return value is based on the OS System Time.
3737 erlang:localtime_to_universaltime(Localtime) -> Universaltime
3739 Types:
3741 Localtime = Universaltime = calendar:datetime()
3743 Converts local date and time to Universal Time Coordinated
3745 (UTC), if supported by the underlying OS. Otherwise no conver‐
3746 sion is done and Localtime is returned. Example:
3747 > erlang:localtime_to_universaltime({{1996,11,6},{14,45,17}}).
3749 {{1996,11,6},{13,45,17}}
3750 Failure: badarg if Localtime denotes an invalid date and time.
3752 erlang:localtime_to_universaltime(Localtime, IsDst) ->
3754 Universaltime
3755 Types:
3757 Localtime = Universaltime = calendar:datetime()
3759 IsDst = true | false | undefined
3760 Converts local date and time to Universal Time Coordinated (UTC)
3762 as erlang:localtime_to_universaltime/1, but the caller decides
3763 if Daylight Saving Time is active.
3764 If IsDst == true, Localtime is during Daylight Saving Time, if
3766 IsDst == false it is not. If IsDst == undefined, the underlying
3767 OS can guess, which is the same as calling erlang:local‐
3768 time_to_universaltime(Localtime).
3769 Examples:
3771 > erlang:localtime_to_universaltime({{1996,11,6},{14,45,17}}, true).
3773 {{1996,11,6},{12,45,17}}
3774 > erlang:localtime_to_universaltime({{1996,11,6},{14,45,17}}, false).
3775 {{1996,11,6},{13,45,17}}
3776 > erlang:localtime_to_universaltime({{1996,11,6},{14,45,17}}, undefined).
3777 {{1996,11,6},{13,45,17}}
3778 Failure: badarg if Localtime denotes an invalid date and time.
3780 make_ref() -> reference()
3782 Returns a unique reference. The reference is unique among con‐
3784 nected nodes.
3785 Warning:
3787 Before OTP-23 when a node is restarted multiple times with the
3788 same node name, references created on a newer node can be mis‐
3789 taken for a reference created on an older node with the same
3790 node name.
3791 erlang:make_tuple(Arity, InitialValue) -> tuple()
3794 Types:
3796 Arity = arity()
3798 InitialValue = term()
3799 Creates a new tuple of the specified Arity, where all elements
3801 are InitialValue, for example:
3802 > erlang:make_tuple(4, []).
3804 {[],[],[],[]}
3805 erlang:make_tuple(Arity, DefaultValue, InitList) -> tuple()
3807 Types:
3809 Arity = arity()
3811 DefaultValue = term()
3812 InitList = [{Position :: integer() >= 1, term()}]
3813 Creates a tuple of size Arity, where each element has value De‐
3815 faultValue, and then fills in values from InitList. Each list
3816 element in InitList must be a two-tuple, where the first element
3817 is a position in the newly created tuple and the second element
3818 is any term. If a position occurs more than once in the list,
3819 the term corresponding to the last occurrence is used. Example:
3820 > erlang:make_tuple(5, [], [{2,ignored},{5,zz},{2,aa}]).
3822 {[],aa,[],[],zz}
3823 map_get(Key, Map) -> Value
3825 Types:
3827 Map = map()
3829 Key = Value = any()
3830 Returns value Value associated with Key if Map contains Key.
3832 The call fails with a {badmap,Map} exception if Map is not a
3834 map, or with a {badkey,Key} exception if no value is associated
3835 with Key.
3836 Example:
3838 > Key = 1337,
3840 Map = #{42 => value_two,1337 => "value one","a" => 1},
3841 map_get(Key,Map).
3842 "value one"
3843 Allowed in guard tests.
3845 map_size(Map) -> integer() >= 0
3847 Types:
3849 Map = map()
3851 Returns an integer, which is the number of key-value pairs in
3853 Map, for example:
3854 > map_size(#{a=>1, b=>2, c=>3}).
3856 3
3857 Allowed in guard tests.
3859 erlang:match_spec_test(MatchAgainst, MatchSpec, Type) ->
3861 TestResult
3862 Types:
3864 MatchAgainst = [term()] | tuple()
3866 MatchSpec = term()
3867 Type = table | trace
3868 TestResult =
3869 {ok, term(), [return_trace], [{error | warning,
3870 string()}]} |
3871 {error, [{error | warning, string()}]}
3872 Tests a match specification used in calls to ets:select/2 and
3874 erlang:trace_pattern/3. The function tests both a match specifi‐
3875 cation for "syntactic" correctness and runs the match specifica‐
3876 tion against the object. If the match specification contains er‐
3877 rors, the tuple {error, Errors} is returned, where Errors is a
3878 list of natural language descriptions of what was wrong with the
3879 match specification.
3880 If Type is table, the object to match against is to be a tuple.
3882 The function then returns {ok,Result,[],Warnings}, where Result
3883 is what would have been the result in a real ets:select/2 call,
3884 or false if the match specification does not match the object
3885 tuple.
3886 If Type is trace, the object to match against is to be a list.
3888 The function returns {ok, Result, Flags, Warnings}, where Result
3889 is one of the following:
3890 * true if a trace message is to be emitted
3892 * false if a trace message is not to be emitted
3894 * The message term to be appended to the trace message
3896 Flags is a list containing all the trace flags to be enabled,
3898 currently this is only return_trace.
3899 This is a useful debugging and test tool, especially when writ‐
3901 ing complicated match specifications.
3902 See also ets:test_ms/2.
3904 max(Term1, Term2) -> Maximum
3906 Types:
3908 Term1 = Term2 = Maximum = term()
3910 Returns the largest of Term1 and Term2. If the terms compare
3912 equal with the == operator, Term1 is returned.
3913 The Expressions section contains descriptions of the == opera‐
3915 tor and how terms are ordered.
3916 Examples:
3918 > max(1, 2).
3920 2
3921 > max(1.0, 1).
3923 1.0
3924 > max(1, 1.0).
3926 1
3927 > max("abc", "b").
3929 "b"
3930 Allowed in guard tests.
3932 Change:
3934 Allowed in guards tests from Erlang/OTP 26.
3935 erlang:md5(Data) -> Digest
3938 Types:
3940 Data = iodata()
3942 Digest = binary()
3943 Computes an MD5 message digest from Data, where the length of
3945 the digest is 128 bits (16 bytes). Data is a binary or a list of
3946 small integers and binaries.
3947 For more information about MD5, see RFC 1321 - The MD5 Message-
3949 Digest Algorithm.
3950 Warning:
3952 The MD5 Message-Digest Algorithm is not considered safe for
3953 code-signing or software-integrity purposes.
3954 erlang:md5_final(Context) -> Digest
3957 Types:
3959 Context = Digest = binary()
3961 Finishes the update of an MD5 Context and returns the computed
3963 MD5 message digest.
3964 erlang:md5_init() -> Context
3966 Types:
3968 Context = binary()
3970 Creates an MD5 context, to be used in the following calls to
3972 md5_update/2.
3973 erlang:md5_update(Context, Data) -> NewContext
3975 Types:
3977 Context = binary()
3979 Data = iodata()
3980 NewContext = binary()
3981 Update an MD5 Context with Data and returns a NewContext.
3983 erlang:memory() -> [{Type, Size}]
3985 Types:
3987 Type = memory_type()
3989 Size = integer() >= 0
3990 memory_type() =
3991 total | processes | processes_used | system | atom |
3992 atom_used | binary | code | ets
3993 Returns a list with information about memory dynamically allo‐
3995 cated by the Erlang emulator. Each list element is a tuple
3996 {Type, Size}. The first element Type is an atom describing mem‐
3997 ory type. The second element Size is the memory size in bytes.
3998 Memory types:
4000 total:
4002 The total amount of memory currently allocated. This is the
4003 same as the sum of the memory size for processes and system.
4004 processes:
4006 The total amount of memory currently allocated for the Er‐
4007 lang processes.
4008 processes_used:
4010 The total amount of memory currently used by the Erlang pro‐
4011 cesses. This is part of the memory presented as processes
4012 memory.
4013 system:
4015 The total amount of memory currently allocated for the emu‐
4016 lator that is not directly related to any Erlang process.
4017 Memory presented as processes is not included in this mem‐
4018 ory. instrument(3) can be used to get a more detailed break‐
4019 down of what memory is part of this type.
4020 atom:
4022 The total amount of memory currently allocated for atoms.
4023 This memory is part of the memory presented as system mem‐
4024 ory.
4025 atom_used:
4027 The total amount of memory currently used for atoms. This
4028 memory is part of the memory presented as atom memory.
4029 binary:
4031 The total amount of memory currently allocated for binaries.
4032 This memory is part of the memory presented as system mem‐
4033 ory.
4034 code:
4036 The total amount of memory currently allocated for Erlang
4037 code. This memory is part of the memory presented as system
4038 memory.
4039 ets:
4041 The total amount of memory currently allocated for ETS ta‐
4042 bles. This memory is part of the memory presented as system
4043 memory.
4044 maximum:
4046 The maximum total amount of memory allocated since the emu‐
4047 lator was started. This tuple is only present when the emu‐
4048 lator is run with instrumentation.
4049 For information on how to run the emulator with instrumenta‐
4051 tion, see instrument(3) and/or erl(1).
4052 Note:
4054 The system value is not complete. Some allocated memory that is
4055 to be part of this value is not.
4056 When the emulator is run with instrumentation, the system value
4058 is more accurate, but memory directly allocated for malloc (and
4059 friends) is still not part of the system value. Direct calls to
4060 malloc are only done from OS-specific runtime libraries and per‐
4061 haps from user-implemented Erlang drivers that do not use the
4062 memory allocation functions in the driver interface.
4063 As the total value is the sum of processes and system, the error
4065 in system propagates to the total value.
4066 The different amounts of memory that are summed are not gathered
4068 atomically, which introduces an error in the result.
4069 The different values have the following relation to each other.
4072 Values beginning with an uppercase letter is not part of the re‐
4073 sult.
4074 total = processes + system
4076 processes = processes_used + ProcessesNotUsed
4077 system = atom + binary + code + ets + OtherSystem
4078 atom = atom_used + AtomNotUsed
4079 RealTotal = processes + RealSystem
4080 RealSystem = system + MissedSystem
4081 More tuples in the returned list can be added in a future re‐
4083 lease.
4084 Note:
4086 The total value is supposed to be the total amount of memory dy‐
4087 namically allocated by the emulator. Shared libraries, the code
4088 of the emulator itself, and the emulator stacks are not supposed
4089 to be included. That is, the total value is not supposed to be
4090 equal to the total size of all pages mapped to the emulator.
4091 Also, because of fragmentation and prereservation of memory ar‐
4093 eas, the size of the memory segments containing the dynamically
4094 allocated memory blocks can be much larger than the total size
4095 of the dynamically allocated memory blocks.
4096 Change:
4099 As from ERTS 5.6.4, erlang:memory/0 requires that all erts_al‐
4100 loc(3) allocators are enabled (default behavior).
4101 Failure: notsup if an erts_alloc(3) allocator has been disabled.
4104 erlang:memory(Type :: memory_type()) -> integer() >= 0
4106 erlang:memory(TypeList :: [memory_type()]) ->
4108 [{memory_type(), integer() >= 0}]
4109 Types:
4111 memory_type() =
4113 total | processes | processes_used | system | atom |
4114 atom_used | binary | code | ets
4115 Returns the memory size in bytes allocated for memory of type
4117 Type. The argument can also be specified as a list of mem‐
4118 ory_type() atoms, in which case a corresponding list of {mem‐
4119 ory_type(), Size :: integer >= 0} tuples is returned.
4120 Change:
4122 As from ERTS 5.6.4, erlang:memory/1 requires that all erts_al‐
4123 loc(3) allocators are enabled (default behavior).
4124 Failures:
4127 badarg:
4129 If Type is not one of the memory types listed in the de‐
4130 scription of erlang:memory/0.
4131 badarg:
4133 If maximum is passed as Type and the emulator is not run in
4134 instrumented mode.
4135 notsup:
4137 If an erts_alloc(3) allocator has been disabled.
4138 See also erlang:memory/0.
4140 min(Term1, Term2) -> Minimum
4142 Types:
4144 Term1 = Term2 = Minimum = term()
4146 Returns the smallest of Term1 and Term2. If the terms compare
4148 equal with the == operator, Term1 is returned.
4149 The Expressions section contains descriptions of the == opera‐
4151 tor and how terms are ordered.
4152 Examples:
4154 > min(1, 2).
4156 1
4157 > min(1.0, 1).
4159 1.0
4160 > min(1, 1.0).
4162 1
4163 > min("abc", "b").
4165 "abc"
4166 Allowed in guard tests.
4168 Change:
4170 Allowed in guards tests from Erlang/OTP 26.
4171 module_loaded(Module) -> boolean()
4174 Types:
4176 Module = module()
4178 Returns true if the module Module is loaded as current code ;
4180 otherwise, false. It does not attempt to load the module.
4181 monitor(Type :: process, Item :: monitor_process_identifier()) ->
4183 MonitorRef
4184 monitor(Type :: port, Item :: monitor_port_identifier()) ->
4186 MonitorRef
4187 monitor(Type :: time_offset, Item :: clock_service) -> MonitorRef
4189 Types:
4191 MonitorRef = reference()
4193 registered_name() = atom()
4194 registered_process_identifier() =
4195 registered_name() | {registered_name(), node()}
4196 monitor_process_identifier() =
4197 pid() | registered_process_identifier()
4198 monitor_port_identifier() = port() | registered_name()
4199 Sends a monitor request of type Type to the entity identified by
4201 Item. If the monitored entity does not exist or it changes moni‐
4202 tored state, the caller of monitor/2 is notified by a message on
4203 the following format:
4204 {Tag, MonitorRef, Type, Object, Info}
4206 Note:
4208 The monitor request is an asynchronous signal. That is, it takes
4209 time before the signal reaches its destination.
4210 Type can be one of the following atoms: process, port or
4213 time_offset.
4214 A process or port monitor is triggered only once, after that it
4216 is removed from both monitoring process and the monitored en‐
4217 tity. Monitors are fired when the monitored process or port ter‐
4218 minates, does not exist at the moment of creation, or if the
4219 connection to it is lost. If the connection to it is lost, we do
4220 not know if it still exists. The monitoring is also turned off
4221 when demonitor/1 is called.
4222 A process or port monitor by name resolves the RegisteredName to
4224 pid() or port() only once at the moment of monitor instantia‐
4225 tion, later changes to the name registration will not affect the
4226 existing monitor.
4227 When a process or port monitor is triggered, a 'DOWN' message is
4229 sent that has the following pattern:
4230 {'DOWN', MonitorRef, Type, Object, Info}
4232 In the monitor message MonitorRef and Type are the same as de‐
4234 scribed earlier, and:
4235 Object:
4237 The monitored entity, which triggered the event. When moni‐
4238 toring a process or a local port, Object will be equal to
4239 the pid() or port() that was being monitored. When monitor‐
4240 ing process or port by name, Object will have format {Regis‐
4241 teredName, Node} where RegisteredName is the name which has
4242 been used with monitor/2 call and Node is local or remote
4243 node name (for ports monitored by name, Node is always local
4244 node name).
4245 Info:
4247 Either the exit reason of the process, noproc (process or
4248 port did not exist at the time of monitor creation), or no‐
4249 connection (no connection to the node where the monitored
4250 process resides).
4251 Monitoring a process:
4253 Creates monitor between the current process and another
4254 process identified by Item, which can be a pid() (local or
4255 remote), an atom RegisteredName or a tuple {RegisteredName,
4256 Node} for a registered process, located elsewhere.
4257 Change:
4259 Before ERTS 10.0 (OTP 21.0), monitoring a process could fail
4260 with badarg if the monitored process resided on a primitive
4261 node (such as erl_interface or jinterface), where remote
4262 process monitoring is not implemented.
4263 Now, such a call to monitor will instead succeed and a monitor
4265 is created. But the monitor will only supervise the connec‐
4266 tion. That is, a {'DOWN', _, process, _, noconnection} is the
4267 only message that may be received, as the primitive node have
4268 no way of reporting the status of the monitored process.
4269 Monitoring a port:
4272 Creates monitor between the current process and a port iden‐
4273 tified by Item, which can be a port() (only local), an atom
4274 RegisteredName or a tuple {RegisteredName, Node} for a reg‐
4275 istered port, located on this node. Note, that attempt to
4276 monitor a remote port will result in badarg.
4277 Monitoring a time_offset:
4279 Monitors changes in time offset between Erlang monotonic
4280 time and Erlang system time. One valid Item exists in combi‐
4281 nation with the time_offset Type, namely the atom clock_ser‐
4282 vice. Notice that the atom clock_service is not the regis‐
4283 tered name of a process. In this case it serves as an iden‐
4284 tifier of the runtime system internal clock service at cur‐
4285 rent runtime system instance.
4286 The monitor is triggered when the time offset is changed.
4288 This either if the time offset value is changed, or if the
4289 offset is changed from preliminary to final during finaliza‐
4290 tion of the time offset when the single time warp mode is
4291 used. When a change from preliminary to final time offset is
4292 made, the monitor is triggered once regardless of whether
4293 the time offset value was changed or not.
4294 If the runtime system is in multi time warp mode, the time
4296 offset is changed when the runtime system detects that the
4297 OS system time has changed. The runtime system does, how‐
4298 ever, not detect this immediately when it occurs. A task
4299 checking the time offset is scheduled to execute at least
4300 once a minute, so under normal operation this is to be de‐
4301 tected within a minute, but during heavy load it can take
4302 longer time.
4303 The monitor is not automatically removed after it has been
4305 triggered. That is, repeated changes of the time offset
4306 trigger the monitor repeatedly.
4307 When the monitor is triggered a 'CHANGE' message is sent to
4309 the monitoring process. A 'CHANGE' message has the following
4310 pattern:
4311 {'CHANGE', MonitorRef, Type, Item, NewTimeOffset}
4313 where MonitorRef, Type, and Item are the same as described
4315 above, and NewTimeOffset is the new time offset.
4316 When the 'CHANGE' message has been received you are guaran‐
4318 teed not to retrieve the old time offset when calling er‐
4319 lang:time_offset(). Notice that you can observe the change
4320 of the time offset when calling erlang:time_offset() before
4321 you get the 'CHANGE' message.
4322 Making several calls to monitor/2 for the same Item and/or Type
4324 is not an error; it results in as many independent monitoring
4325 instances.
4326 The monitor functionality is expected to be extended. That is,
4328 other Types and Items are expected to be supported in a future
4329 release.
4330 Note:
4332 If or when monitor/2 is extended, other possible values for Tag,
4333 Object, and Info in the monitor message will be introduced.
4334 Note:
4337 For some important information about distributed signals, see
4338 the Blocking Signaling Over Distribution section in the Pro‐
4339 cesses chapter of the Erlang Reference Manual .
4340 monitor(Type :: process,
4343 Item :: monitor_process_identifier(),
4344 Opts :: [monitor_option()]) ->
4345 MonitorRef
4346 monitor(Type :: port,
4348 Item :: monitor_port_identifier(),
4349 Opts :: [monitor_option()]) ->
4350 MonitorRef
4351 monitor(Type :: time_offset,
4353 Item :: clock_service,
4354 Opts :: [monitor_option()]) ->
4355 MonitorRef
4356 Types:
4358 MonitorRef = reference()
4360 registered_name() = atom()
4361 registered_process_identifier() =
4362 registered_name() | {registered_name(), node()}
4363 monitor_process_identifier() =
4364 pid() | registered_process_identifier()
4365 monitor_port_identifier() = port() | registered_name()
4366 Provides an option list for modification of monitoring function‐
4368 ality provided by monitor/2. The Type and Item arguments have
4369 the same meaning as when passed to monitor/2. Currently avail‐
4370 able options:
4371 {alias, UnaliasOpt}:
4373 The returned monitor reference will also become an alias for
4374 the calling process. That is, the returned reference can be
4375 used for sending messages to the calling process. See also
4376 alias/0. The UnaliasOpt determines how the alias should be
4377 deactivated.
4378 explicit_unalias:
4380 Only an explicit call to unalias/1 will deactivate the
4381 alias.
4382 demonitor:
4384 The alias will be automatically deactivated when the moni‐
4385 tor is removed. This either via an explicit call to demon‐
4386 itor/1 or when it is automatically removed at the same
4387 time as a 'DOWN' message is delivered due to the monitor.
4388 The alias can also still be deactivated via a call to una‐
4389 lias/1.
4390 reply_demonitor:
4392 The alias will be automatically deactivated when the moni‐
4393 tor is removed (see demonitor option above) or a reply
4394 message sent via the alias is received. When a reply mes‐
4395 sage is received via the alias the monitor will also be
4396 automatically removed. This is useful in client/server
4397 scenarios when a client monitors the server and will get
4398 the reply via the alias. Once the response is received
4399 both the alias and the monitor will be automatically re‐
4400 moved regardless of whether the response is a reply or a
4401 'DOWN' message. The alias can also still be deactivated
4402 via a call to unalias/1. Note that if the alias is removed
4403 using the unalias/1 BIF, the monitor will still be left
4404 active.
4405 Example:
4407 server() ->
4409 receive
4410 {request, AliasReqId, Request} ->
4411 Result = perform_request(Request),
4412 AliasReqId ! {reply, AliasReqId, Result}
4413 end,
4414 server().
4415 client(ServerPid, Request) ->
4417 AliasMonReqId = monitor(process, ServerPid, [{alias, reply_demonitor}]),
4418 ServerPid ! {request, AliasMonReqId, Request},
4419 %% Alias as well as monitor will be automatically deactivated if we
4420 %% receive a reply or a 'DOWN' message since we used 'reply_demonitor'
4421 %% as unalias option...
4422 receive
4423 {reply, AliasMonReqId, Result} ->
4424 Result;
4425 {'DOWN', AliasMonReqId, process, ServerPid, ExitReason} ->
4426 error(ExitReason)
4427 end.
4428 Note that both the server and the client in this example
4431 must be executing on at least OTP 24 systems in order for
4432 this to work.
4433 For more information on process aliases see the Process
4435 Aliases section of the Erlang Reference Manual .
4436 {tag, UserDefinedTag}:
4438 Replace the default Tag with UserDefinedTag in the monitor
4439 message delivered when the monitor is triggered. For exam‐
4440 ple, when monitoring a process, the 'DOWN' tag in the down
4441 message will be replaced by UserDefinedTag.
4442 An example of how the {tag, UserDefinedTag} option can be
4444 used in order to enable the new selective receive optimiza‐
4445 tion, introduced in OTP 24, when making multiple requests to
4446 different servers:
4447 server() ->
4449 receive
4450 {request, From, ReqId, Request} ->
4451 Result = perform_request(Request),
4452 From ! {reply, self(), ReqId, Result}
4453 end,
4454 server().
4455 client(ServerPids, Request) when is_list(ServerPids) ->
4457 ReqId = make_ref(),
4458 lists:foreach(fun (ServerPid) ->
4459 _ = monitor(process, ServerPid,
4460 [{tag, {'DOWN', ReqId}}]),
4461 ServerPid ! {request, self(), ReqId, Request}
4462 end,
4463 ServerPids),
4464 receive_replies(ReqId, length(ServerPids), []).
4465 receive_replies(_ReqId, 0, Acc) ->
4467 Acc;
4468 receive_replies(ReqId, N, Acc) ->
4469 %% The compiler will detect that we match on the 'ReqId'
4470 %% reference in all clauses, and will enable the selective
4471 %% receive optimization which makes the receive able to
4472 %% skip past all messages present in the message queue at
4473 %% the time when the 'ReqId' reference was created...
4474 Res = receive
4475 {reply, ServerPid, ReqId, Result} ->
4476 %% Here we typically would have deactivated the
4477 %% monitor by a call to demonitor(Mon, [flush]) but
4478 %% we ignore this in this example for simplicity...
4479 {ok, ServerPid, Result};
4480 {{'DOWN', ReqId}, _Mon, process, ServerPid, ExitReason} ->
4481 {error, ServerPid, ExitReason}
4482 end,
4483 receive_replies(ReqId, N-1, [Res | Acc]).
4484 In order for this example to work as intended, the client
4487 must be executing on at least an OTP 24 system, but the
4488 servers may execute on older systems.
4489 monitor_node(Node, Flag) -> true
4491 Types:
4493 Node = node()
4495 Flag = boolean()
4496 Monitor the status of the node Node. If Flag is true, monitoring
4498 is turned on. If Flag is false, monitoring is turned off.
4499 Making several calls to monitor_node(Node, true) for the same
4501 Node is not an error; it results in as many independent monitor‐
4502 ing instances.
4503 If Node fails or does not exist, the message {nodedown, Node} is
4505 delivered to the process. If a process has made two calls to
4506 monitor_node(Node, true) and Node terminates, two nodedown mes‐
4507 sages are delivered to the process. If there is no connection to
4508 Node, an attempt is made to create one. If this fails, a node‐
4509 down message is delivered.
4510 The delivery of the nodedown signal is not ordered with respect
4512 to other link or monitor signals from the node that goes down.
4513 If you need a guarantee that all signals from the remote node
4514 has been delivered before the nodedown signal is sent, you
4515 should use net_kernel:monitor_nodes/1.
4516 Nodes connected through hidden connections can be monitored as
4518 any other nodes.
4519 Failure: notalive if the local node is not alive.
4521 erlang:monitor_node(Node, Flag, Options) -> true
4523 Types:
4525 Node = node()
4527 Flag = boolean()
4528 Options = [Option]
4529 Option = allow_passive_connect
4530 Behaves as monitor_node/2 except that it allows an extra option
4532 to be specified, namely allow_passive_connect. This option al‐
4533 lows the BIF to wait the normal network connection time-out for
4534 the monitored node to connect itself, even if it cannot be ac‐
4535 tively connected from this node (that is, it is blocked). The
4536 state where this can be useful can only be achieved by using the
4537 Kernel option dist_auto_connect once. If that option is not
4538 used, option allow_passive_connect has no effect.
4539 Note:
4541 Option allow_passive_connect is used internally and is seldom
4542 needed in applications where the network topology and the Kernel
4543 options in effect are known in advance.
4544 Failure: badarg if the local node is not alive or the option
4547 list is malformed.
4548 erlang:monotonic_time() -> integer()
4550 Returns the current Erlang monotonic time in native time unit.
4552 This is a monotonically increasing time since some unspecified
4553 point in time.
4554 Note:
4556 This is a monotonically increasing time, but not a strictly
4557 monotonically increasing time. That is, consecutive calls to er‐
4558 lang:monotonic_time/0 can produce the same result.
4559 Different runtime system instances will use different unspeci‐
4561 fied points in time as base for their Erlang monotonic clocks.
4562 That is, it is pointless comparing monotonic times from differ‐
4563 ent runtime system instances. Different runtime system instances
4564 can also place this unspecified point in time different relative
4565 runtime system start. It can be placed in the future (time at
4566 start is a negative value), the past (time at start is a posi‐
4567 tive value), or the runtime system start (time at start is
4568 zero). The monotonic time at runtime system start can be re‐
4569 trieved by calling erlang:system_info(start_time).
4570 erlang:monotonic_time(Unit) -> integer()
4573 Types:
4575 Unit = time_unit()
4577 Returns the current Erlang monotonic time converted into the
4579 Unit passed as argument.
4580 Same as calling erlang:convert_time_unit(erlang:mono‐
4582 tonic_time(), native, Unit), however optimized for commonly used
4583 Units.
4584 erlang:nif_error(Reason) -> no_return()
4586 Types:
4588 Reason = term()
4590 Works exactly like error/1, but Dialyzer thinks that this BIF
4592 will return an arbitrary term. When used in a stub function for
4593 a NIF to generate an exception when the NIF library is not
4594 loaded, Dialyzer does not generate false warnings.
4595 erlang:nif_error(Reason, Args) -> no_return()
4597 Types:
4599 Reason = term()
4601 Args = [term()]
4602 Works exactly like error/2, but Dialyzer thinks that this BIF
4604 will return an arbitrary term. When used in a stub function for
4605 a NIF to generate an exception when the NIF library is not
4606 loaded, Dialyzer does not generate false warnings.
4607 node() -> Node
4609 Types:
4611 Node = node()
4613 Returns the name of the local node. If the node is not alive,
4615 nonode@nohost is returned instead.
4616 Allowed in guard tests.
4618 node(Arg) -> Node
4620 Types:
4622 Arg = pid() | port() | reference()
4624 Node = node()
4625 Returns the node where Arg originates. Arg can be a process
4627 identifier, a reference, or a port. If Arg originates from the
4628 local node and the local node is not alive, nonode@nohost is re‐
4629 turned.
4630 Allowed in guard tests.
4632 nodes() -> Nodes
4634 Types:
4636 Nodes = [node()]
4638 Returns a list of all nodes connected to this node through nor‐
4640 mal connections (that is, hidden nodes are not listed). Same as
4641 nodes(visible).
4642 nodes(Arg) -> Nodes
4644 Types:
4646 Arg = NodeType | [NodeType]
4648 NodeType = visible | hidden | connected | this | known
4649 Nodes = [node()]
4650 Returns a list of nodes according to the argument specified. The
4652 returned result, when the argument is a list, is the list of
4653 nodes satisfying the disjunction(s) of the list elements.
4654 NodeTypes:
4656 visible:
4658 Nodes connected to this node through normal connections.
4659 hidden:
4661 Nodes connected to this node through hidden connections.
4662 connected:
4664 All nodes connected to this node.
4665 this:
4667 This node.
4668 known:
4670 Nodes that are known to this node. That is, connected nodes
4671 and nodes referred to by process identifiers, port identi‐
4672 fiers, and references located on this node. The set of known
4673 nodes is garbage collected. Notice that this garbage collec‐
4674 tion can be delayed. For more information, see erlang:sys‐
4675 tem_info(delayed_node_table_gc).
4676 Some equalities: [node()] = nodes(this), nodes(connected) =
4678 nodes([visible, hidden]), and nodes() = nodes(visible).
4679 nodes(Arg, InfoOpts) -> [NodeInfo]
4681 Types:
4683 NodeType = visible | hidden | connected | this | known
4685 Arg = NodeType | [NodeType]
4686 InfoOpts =
4687 #{connection_id => boolean(), node_type => boolean()}
4688 NodeTypeInfo = visible | hidden | this | known
4689 ConnectionId = undefined | integer()
4690 Info =
4691 #{connection_id => ConnectionId, node_type => NodeType‐
4692 Info}
4693 NodeInfo = {node(), Info}
4694 Returns a list of NodeInfo tuples. The first element is the node
4696 name. Nodes to be included in the list are determined by the
4697 first argument Arg in the same way as for nodes(Arg). The second
4698 element of NodeInfo tuples is a map containing further informa‐
4699 tion about the node identified by the first element. The infor‐
4700 mation present in this map is determined by the InfoOpts map
4701 passed as the second argument. Currently the following associa‐
4702 tions are allowed in the InfoOpts map:
4703 connection_id => boolean():
4705 If the value of the association equals true, the Info map in
4706 the returned result will contain the key connection_id asso‐
4707 ciated with the value ConnectionId. If ConnectionId equals
4708 undefined, the node is not connected to the node which the
4709 caller is executing on, or is the node which the caller is
4710 executing on. If ConnectionId is an integer, the node is
4711 currently connected to the node which the caller is execut‐
4712 ing on.
4713 The integer connection identifier value together with a node
4715 name identifies a specific connection instance to the node
4716 with that node name. The connection identifier value is node
4717 local. That is, on the other node the connection identifier
4718 will not be the same value. If a connection is taken down
4719 and then taken up again, the connection identifier value
4720 will change for the connection to that node. The amount of
4721 values for connection identifiers are limited, so it is pos‐
4722 sible to see the same value for different instances, but
4723 quite unlikely. It is undefined how the value change between
4724 two consecutive connection instances.
4725 node_type => boolean():
4727 If the value of the association equals true, the Info map in
4728 the returned result will contain the key node_type associ‐
4729 ated with the value NodeTypeInfo. Currently the following
4730 node types exist:
4731 visible:
4733 The node is connected to the node of the calling process
4734 through an ordinary visible connection. That is, the node
4735 name would appear in the result returned by nodes/0.
4736 hidden:
4738 The node is connected to the node of the calling process
4739 through a hidden connection. That is, the node name would
4740 not appear in the result returned by nodes/0.
4741 this:
4743 This is the node of the calling process.
4744 known:
4746 The node is not connected but known to the node of the
4747 calling process.
4748 Example:
4750 (a@localhost)1> nodes([this, connected], #{connection_id=>true, node_type=>true}).
4752 [{c@localhost,#{connection_id => 13892108,node_type => hidden}},
4753 {b@localhost,#{connection_id => 3067553,node_type => visible}},
4754 {a@localhost,#{connection_id => undefined,node_type => this}}]
4755 (a@localhost)2>
4756 now() -> Timestamp
4759 Types:
4761 Timestamp = timestamp()
4763 timestamp() =
4764 {MegaSecs :: integer() >= 0,
4765 Secs :: integer() >= 0,
4766 MicroSecs :: integer() >= 0}
4767 Warning:
4769 This function is deprecated. Do not use it.
4770 For more information, see section Time and Time Correction in
4772 the User's Guide. Specifically, section Dos and Dont's de‐
4773 scribes what to use instead of erlang:now/0.
4774 Returns the tuple {MegaSecs, Secs, MicroSecs}, which is the
4777 elapsed time since 00:00 GMT, January 1, 1970 (zero hour), if
4778 provided by the underlying OS. Otherwise some other point in
4779 time is chosen. It is also guaranteed that the following calls
4780 to this BIF return continuously increasing values. Hence, the
4781 return value from erlang:now/0 can be used to generate unique
4782 time stamps. If it is called in a tight loop on a fast machine,
4783 the time of the node can become skewed.
4784 Can only be used to check the local time of day if the time-zone
4786 information of the underlying OS is properly configured.
4787 open_port(PortName, PortSettings) -> port()
4789 Types:
4791 PortName =
4793 {spawn, Command :: string() | binary()} |
4794 {spawn_driver, Command :: string() | binary()} |
4795 {spawn_executable, FileName :: file:name_all()} |
4796 {fd, In :: integer() >= 0, Out :: integer() >= 0}
4797 PortSettings = [Opt]
4798 Opt =
4799 {packet, N :: 1 | 2 | 4} |
4800 stream |
4801 {line, L :: integer() >= 0} |
4802 {cd, Dir :: string() | binary()} |
4803 {env,
4804 Env ::
4805 [{Name :: os:env_var_name(),
4806 Val :: os:env_var_value() | false}]} |
4807 {args, [string() | binary()]} |
4808 {arg0, string() | binary()} |
4809 exit_status | use_stdio | nouse_stdio | stderr_to_stdout
4810 |
4811 in | out | binary | eof |
4812 {parallelism, Boolean :: boolean()} |
4813 hide |
4814 {busy_limits_port,
4815 {integer() >= 0, integer() >= 0} | disabled} |
4816 {busy_limits_msgq,
4817 {integer() >= 0, integer() >= 0} | disabled}
4818 Returns a port identifier as the result of opening a new Erlang
4820 port. A port can be seen as an external Erlang process.
4821 The name of the executable as well as the arguments specified in
4823 cd, env, args, and arg0 are subject to Unicode filename transla‐
4824 tion if the system is running in Unicode filename mode. To avoid
4825 translation or to force, for example UTF-8, supply the exe‐
4826 cutable and/or arguments as a binary in the correct encoding.
4827 For details, see the module file(3), the function file:na‐
4828 tive_name_encoding/0 in Kernel, and the Using Unicode in Erlang
4829 User's Guide.
4830 Note:
4832 The characters in the name (if specified as a list) can only be
4833 > 255 if the Erlang virtual machine is started in Unicode file‐
4834 name translation mode. Otherwise the name of the executable is
4835 limited to the ISO Latin-1 character set.
4836 PortNames:
4839 {spawn, Command}:
4841 Starts an external program. Command is the name of the ex‐
4842 ternal program to be run. Command runs outside the Erlang
4843 work space unless an Erlang driver with the name Command is
4844 found. If found, that driver is started. A driver runs in
4845 the Erlang work space, which means that it is linked with
4846 the Erlang runtime system.
4847 For external programs, PATH is searched (or an equivalent
4849 method is used to find programs, depending on the OS). This
4850 is done by invoking the shell on certain platforms. The
4851 first space-separated token of the command is considered as
4852 the name of the executable (or driver). This (among other
4853 things) makes this option unsuitable for running programs
4854 with spaces in filenames or directory names. If spaces in
4855 executable filenames are desired, use {spawn_executable,
4856 Command} instead.
4857 {spawn_driver, Command}:
4859 Works like {spawn, Command}, but demands the first (space-
4860 separated) token of the command to be the name of a loaded
4861 driver. If no driver with that name is loaded, a badarg er‐
4862 ror is raised.
4863 {spawn_executable, FileName}:
4865 Works like {spawn, FileName}, but only runs external exe‐
4866 cutables. FileName in its whole is used as the name of the
4867 executable, including any spaces. If arguments are to be
4868 passed, the PortSettings args and arg0 can be used.
4869 The shell is usually not invoked to start the program, it is
4871 executed directly. PATH (or equivalent) is not searched. To
4872 find a program in PATH to execute, use os:find_executable/1.
4873 Only if a shell script or .bat file is executed, the appro‐
4875 priate command interpreter is invoked implicitly, but there
4876 is still no command-argument expansion or implicit PATH
4877 search.
4878 If FileName cannot be run, an error exception is raised,
4880 with the POSIX error code as the reason. The error reason
4881 can differ between OSs. Typically the error enoent is raised
4882 when an attempt is made to run a program that is not found
4883 and eacces is raised when the specified file is not exe‐
4884 cutable.
4885 {fd, In, Out}:
4887 Allows an Erlang process to access any currently opened file
4888 descriptors used by Erlang. The file descriptor In can be
4889 used for standard input, and the file descriptor Out for
4890 standard output. It is only used for various servers in the
4891 Erlang OS (shell and user). Hence, its use is limited.
4892 PortSettings is a list of settings for the port. The valid set‐
4894 tings are as follows:
4895 {packet, N}:
4897 Messages are preceded by their length, sent in N bytes, with
4898 the most significant byte first. The valid values for N are
4899 1, 2, and 4.
4900 stream:
4902 Output messages are sent without packet lengths. A user-de‐
4903 fined protocol must be used between the Erlang process and
4904 the external object.
4905 {line, L}:
4907 Messages are delivered on a per line basis. Each line (de‐
4908 limited by the OS-dependent newline sequence) is delivered
4909 in a single message. The message data format is {Flag,
4910 Line}, where Flag is eol or noeol, and Line is the data de‐
4911 livered (without the newline sequence).
4912 L specifies the maximum line length in bytes. Lines longer
4914 than this are delivered in more than one message, with Flag
4915 set to noeol for all but the last message. If end of file is
4916 encountered anywhere else than immediately following a new‐
4917 line sequence, the last line is also delivered with Flag set
4918 to noeol. Otherwise lines are delivered with Flag set to
4919 eol.
4920 The {packet, N} and {line, L} settings are mutually exclu‐
4922 sive.
4923 {cd, Dir}:
4925 Only valid for {spawn, Command} and {spawn_executable, File‐
4926 Name}. The external program starts using Dir as its working
4927 directory. Dir must be a string.
4928 {env, Env}:
4930 Types:
4931 Name = os:env_var_name()
4932 Val = os:env_var_value() | false
4933 Env = [{Name, Val}]
4934 Only valid for {spawn, Command}, and {spawn_executable,
4936 FileName}. The environment of the started process is ex‐
4937 tended using the environment specifications in Env.
4938 Env is to be a list of tuples {Name, Val}, where Name is the
4940 name of an environment variable, and Val is the value it is
4941 to have in the spawned port process. Both Name and Val must
4942 be strings. The one exception is Val being the atom false
4943 (in analogy with os:getenv/1), which removes the environment
4944 variable.
4945 For information about encoding requirements, see documenta‐
4947 tion of the types for Name and Val.
4948 {args, [ string() | binary() ]}:
4950 Only valid for {spawn_executable, FileName} and specifies
4951 arguments to the executable. Each argument is specified as a
4952 separate string and (on Unix) eventually ends up as one ele‐
4953 ment each in the argument vector. On other platforms, a sim‐
4954 ilar behavior is mimicked.
4955 The arguments are not expanded by the shell before they are
4957 supplied to the executable. Most notably this means that
4958 file wildcard expansion does not occur. To expand wildcards
4959 for the arguments, use filelib:wildcard/1. Notice that even
4960 if the program is a Unix shell script, meaning that the
4961 shell ultimately is invoked, wildcard expansion does not oc‐
4962 cur, and the script is provided with the untouched argu‐
4963 ments. On Windows, wildcard expansion is always up to the
4964 program itself, therefore this is not an issue.
4965 The executable name (also known as argv[0]) is not to be
4967 specified in this list. The proper executable name is auto‐
4968 matically used as argv[0], where applicable.
4969 If you explicitly want to set the program name in the argu‐
4971 ment vector, option arg0 can be used.
4972 {arg0, string() | binary()}:
4974 Only valid for {spawn_executable, FileName} and explicitly
4975 specifies the program name argument when running an exe‐
4976 cutable. This can in some circumstances, on some OSs, be de‐
4977 sirable. How the program responds to this is highly system-
4978 dependent and no specific effect is guaranteed.
4979 exit_status:
4981 Only valid for {spawn, Command}, where Command refers to an
4982 external program, and for {spawn_executable, FileName}.
4983 When the external process connected to the port exits, a
4985 message of the form {Port,{exit_status,Status}} is sent to
4986 the connected process, where Status is the exit status of
4987 the external process. If the program aborts on Unix, the
4988 same convention is used as the shells do (that is, 128+sig‐
4989 nal).
4990 If option eof is specified also, the messages eof and
4992 exit_status appear in an unspecified order.
4993 If the port program closes its stdout without exiting, op‐
4995 tion exit_status does not work.
4996 use_stdio:
4998 Only valid for {spawn, Command} and {spawn_executable, File‐
4999 Name}. It allows the standard input and output (file de‐
5000 scriptors 0 and 1) of the spawned (Unix) process for commu‐
5001 nication with Erlang.
5002 nouse_stdio:
5004 The opposite of use_stdio. It uses file descriptors 3 and 4
5005 for communication with Erlang.
5006 stderr_to_stdout:
5008 Affects ports to external programs. The executed program
5009 gets its standard error file redirected to its standard out‐
5010 put file. stderr_to_stdout and nouse_stdio are mutually ex‐
5011 clusive.
5012 overlapped_io:
5014 Affects ports to external programs on Windows only. The
5015 standard input and standard output handles of the port pro‐
5016 gram are, if this option is supplied, opened with flag
5017 FILE_FLAG_OVERLAPPED, so that the port program can (and
5018 must) do overlapped I/O on its standard handles. This is not
5019 normally the case for simple port programs, but an option of
5020 value for the experienced Windows programmer. On all other
5021 platforms, this option is silently discarded.
5022 in:
5024 The port can only be used for input.
5025 out:
5027 The port can only be used for output.
5028 binary:
5030 All I/O from the port is binary data objects as opposed to
5031 lists of bytes.
5032 eof:
5034 The port is not closed at the end of the file and does not
5035 produce an exit signal. Instead, it remains open and a
5036 {Port, eof} message is sent to the process holding the port.
5037 hide:
5039 When running on Windows, suppresses creation of a new con‐
5040 sole window when spawning the port program. (This option has
5041 no effect on other platforms.)
5042 {parallelism, Boolean}:
5044 Sets scheduler hint for port parallelism. If set to true,
5047 the virtual machine schedules port tasks; when doing so, it
5048 improves parallelism in the system. If set to false, the
5049 virtual machine tries to perform port tasks immediately, im‐
5050 proving latency at the expense of parallelism. The default
5051 can be set at system startup by passing command-line argu‐
5052 ment +spp to erl(1).
5053 {busy_limits_port, {Low, High} | disabled}:
5055 Sets limits that will be used for controlling the busy state
5056 of the port.
5057 When the ports internal output queue size becomes larger
5059 than or equal to High bytes, it enters the busy state. When
5060 it becomes less than Low bytes it leaves the busy state.
5061 When the port is in the busy state, processes sending com‐
5062 mands to it will be suspended until the port leaves the busy
5063 state. Commands are in this context either Port ! {Owner,
5064 {command, Data}} or port_command/[2,3].
5065 The Low limit is automatically adjusted to the same as High
5067 if it is set larger then High. Valid range of values for Low
5068 and High is [1, (1 bsl (8*erlang:system_info(wordsize)))-2].
5069 If the atom disabled is passed, the port will never enter
5070 the busy state.
5071 The defaults are Low = 4096 and High = 8192.
5073 Note that this option is only valid when spawning an exe‐
5075 cutable (port program) by opening the spawn driver and when
5076 opening the fd driver. This option will cause a failure with
5077 a badarg exception when opening other drivers.
5078 {busy_limits_msgq, {Low, High} | disabled}:
5080 Sets limits that will be used for controlling the busy state
5081 of the port message queue.
5082 When the ports message queue size becomes larger than or
5084 equal to High bytes it enters the busy state. When it be‐
5085 comes less than Low bytes it leaves the busy state. When the
5086 port message queue is in the busy state, processes sending
5087 commands to it will be suspended until the port message
5088 queue leaves the busy state. Commands are in this context
5089 either Port ! {Owner, {command, Data}} or port_com‐
5090 mand/[2,3].
5091 The Low limit is automatically adjusted to the same as High
5093 if it is set larger then High. Valid range of values for Low
5094 and High is [1, (1 bsl (8*erlang:system_info(wordsize)))-2].
5095 If the atom disabled is passed, the port message queue will
5096 never enter the busy state.
5097 Note that if the driver statically has disabled the use of
5099 this feature, a failure with a badarg exception will be
5100 raised unless this option also is set to disable or not
5101 passed at all.
5102 The defaults are Low = 4096 and High = 8192 unless the
5104 driver itself does modifications of these values.
5105 Note that the driver might fail if it also adjust these lim‐
5107 its by itself and you have disabled this feature.
5108 The spawn driver (used when spawning an executable) and the
5110 fd driver do not disable this feature and do not adjust
5111 these limits by themselves.
5112 For more information see the documentation
5114 erl_drv_busy_msgq_limits().
5115 Default is stream for all port types and use_stdio for spawned
5117 ports.
5118 Failure: if the port cannot be opened, the exit reason is
5120 badarg, system_limit, or the POSIX error code that most closely
5121 describes the error, or einval if no POSIX code is appropriate:
5122 badarg:
5124 Bad input arguments to open_port.
5125 system_limit:
5127 All available ports in the Erlang emulator are in use.
5128 enomem:
5130 Not enough memory to create the port.
5131 eagain:
5133 No more available OS processes.
5134 enametoolong:
5136 Too long external command.
5137 emfile:
5139 No more available file descriptors (for the OS process that
5140 the Erlang emulator runs in).
5141 enfile:
5143 Full file table (for the entire OS).
5144 eacces:
5146 Command specified in {spawn_executable, Command} does not
5147 point out an executable file.
5148 enoent:
5150 FileName specified in {spawn_executable, FileName} does not
5151 point out an existing file.
5152 During use of a port opened using {spawn, Name}, {spawn_driver,
5154 Name}, or {spawn_executable, Name}, errors arising when sending
5155 messages to it are reported to the owning process using signals
5156 of the form {'EXIT', Port, PosixCode}. For the possible values
5157 of PosixCode, see file(3).
5158 The maximum number of ports that can be open at the same time
5160 can be configured by passing command-line flag +Q to erl(1).
5161 erlang:phash(Term, Range) -> Hash
5163 Types:
5165 Term = term()
5167 Range = Hash = integer() >= 1
5168 Range = 1..2^32, Hash = 1..Range
5169 Warning:
5171 This function is deprecated as erlang:phash2/2 should be used
5172 for new code. Note that erlang:phash(X,N) is not necessary equal
5173 to erlang:phash2(X,N)
5174 Portable hash function that gives the same hash for the same Er‐
5177 lang term regardless of machine architecture and ERTS version
5178 (the BIF was introduced in ERTS 4.9.1.1). The function returns a
5179 hash value for Term within the range 1..Range. The maximum value
5180 for Range is 2^32.
5181 erlang:phash2(Term) -> Hash
5183 erlang:phash2(Term, Range) -> Hash
5185 Types:
5187 Term = term()
5189 Range = integer() >= 1
5190 1..2^32
5191 Hash = integer() >= 0
5192 0..Range-1
5193 Portable hash function that gives the same hash for the same Er‐
5195 lang term regardless of machine architecture and ERTS version
5196 (the BIF was introduced in ERTS 5.2). The function returns a
5197 hash value for Term within the range 0..Range-1. The maximum
5198 value for Range is 2^32. When without argument Range, a value in
5199 the range 0..2^27-1 is returned.
5200 This BIF is always to be used for hashing terms. It distributes
5202 small integers better than phash/2, and it is faster for bignums
5203 and binaries.
5204 Notice that the range 0..Range-1 is different from the range of
5206 phash/2, which is 1..Range.
5207 pid_to_list(Pid) -> string()
5209 Types:
5211 Pid = pid()
5213 Returns a string corresponding to the text representation of
5215 Pid. Example:
5216 > erlang:pid_to_list(self()).
5218 "<0.85.0>"
5219 Note:
5221 The creation for the node is not included in the list represen‐
5222 tation of Pid. This means that processes in different incarna‐
5223 tions of a node with a specific name can get the same list rep‐
5224 resentation.
5225 erlang:port_call(Port, Operation, Data) -> term()
5228 Types:
5230 Port = port() | atom()
5232 Operation = integer()
5233 Data = term()
5234 Performs a synchronous call to a port. The meaning of Operation
5236 and Data depends on the port, that is, on the port driver. Not
5237 all port drivers support this feature.
5238 Port is a port identifier, referring to a driver.
5240 Operation is an integer, which is passed on to the driver.
5242 Data is any Erlang term. This data is converted to binary term
5244 format and sent to the port.
5245 Returns a term from the driver. The meaning of the returned data
5247 also depends on the port driver.
5248 Failures:
5250 badarg:
5252 If Port is not an identifier of an open port, or the regis‐
5253 tered name of an open port. If the calling process was pre‐
5254 viously linked to the closed port, identified by Port, the
5255 exit signal from the port is guaranteed to be delivered be‐
5256 fore this badarg exception occurs.
5257 badarg:
5259 If Operation does not fit in a 32-bit integer.
5260 badarg:
5262 If the port driver does not support synchronous control op‐
5263 erations.
5264 badarg:
5266 If the port driver so decides for any reason (probably some‐
5267 thing wrong with Operation or Data).
5268 Warning:
5270 Do not call port_call with an unknown Port identifier and ex‐
5271 pect badarg exception. Any undefined behavior is possible (in‐
5272 cluding node crash) depending on how the port driver inter‐
5273 prets the supplied arguments.
5274 port_close(Port) -> true
5277 Types:
5279 Port = port() | atom()
5281 Closes an open port. Roughly the same as Port ! {self(), close}
5283 except for the error behavior (see below), being synchronous,
5284 and that the port does not reply with {Port, closed}. Any
5285 process can close a port with port_close/1, not only the port
5286 owner (the connected process). If the calling process is linked
5287 to the port identified by Port, the exit signal from the port is
5288 guaranteed to be delivered before port_close/1 returns.
5289 For comparison: Port ! {self(), close} only fails with badarg if
5291 Port does not refer to a port or a process. If Port is a closed
5292 port, nothing happens. If Port is an open port and the calling
5293 process is the port owner, the port replies with {Port, closed}
5294 when all buffers have been flushed and the port really closes.
5295 If the calling process is not the port owner, the port owner
5296 fails with badsig.
5297 Notice that any process can close a port using Port ! {Por‐
5299 tOwner, close} as if it itself was the port owner, but the reply
5300 always goes to the port owner.
5301 As from Erlang/OTP R16, Port ! {PortOwner, close} is truly asyn‐
5303 chronous. Notice that this operation has always been documented
5304 as an asynchronous operation, while the underlying implementa‐
5305 tion has been synchronous. port_close/1 is however still fully
5306 synchronous because of its error behavior.
5307 Failure: badarg if Port is not an identifier of an open port, or
5309 the registered name of an open port. If the calling process was
5310 previously linked to the closed port, identified by Port, the
5311 exit signal from the port is guaranteed to be delivered before
5312 this badarg exception occurs.
5313 port_command(Port, Data) -> true
5315 Types:
5317 Port = port() | atom()
5319 Data = iodata()
5320 Sends data to a port. Same as Port ! {PortOwner, {command,
5322 Data}} except for the error behavior and being synchronous (see
5323 below). Any process can send data to a port with port_command/2,
5324 not only the port owner (the connected process).
5325 For comparison: Port ! {PortOwner, {command, Data}} only fails
5327 with badarg if Port does not refer to a port or a process. If
5328 Port is a closed port, the data message disappears without a
5329 sound. If Port is open and the calling process is not the port
5330 owner, the port owner fails with badsig. The port owner fails
5331 with badsig also if Data is an invalid I/O list.
5332 Notice that any process can send to a port using Port ! {Por‐
5334 tOwner, {command, Data}} as if it itself was the port owner.
5335 If the port is busy, the calling process is suspended until the
5337 port is not busy any more.
5338 As from Erlang/OTP R16, Port ! {PortOwner, {command, Data}} is
5340 truly asynchronous. Notice that this operation has always been
5341 documented as an asynchronous operation, while the underlying
5342 implementation has been synchronous. port_command/2 is however
5343 still fully synchronous because of its error behavior.
5344 Failures:
5346 badarg:
5348 If Port is not an identifier of an open port, or the regis‐
5349 tered name of an open port. If the calling process was pre‐
5350 viously linked to the closed port, identified by Port, the
5351 exit signal from the port is guaranteed to be delivered be‐
5352 fore this badarg exception occurs.
5353 badarg:
5355 If Data is an invalid I/O list.
5356 Warning:
5358 Do not send data to an unknown port. Any undefined behavior is
5359 possible (including node crash) depending on how the port driver
5360 interprets the data.
5361 port_command(Port, Data, OptionList) -> boolean()
5364 Types:
5366 Port = port() | atom()
5368 Data = iodata()
5369 Option = force | nosuspend
5370 OptionList = [Option]
5371 Sends data to a port. port_command(Port, Data, []) equals
5373 port_command(Port, Data).
5374 If the port command is aborted, false is returned, otherwise
5376 true.
5377 If the port is busy, the calling process is suspended until the
5379 port is not busy anymore.
5380 Options:
5382 force:
5384 The calling process is not suspended if the port is busy,
5385 instead the port command is forced through. The call fails
5386 with a notsup exception if the driver of the port does not
5387 support this. For more information, see driver flag
5388 ERL_DRV_FLAG_SOFT_BUSY.
5389 nosuspend:
5391 The calling process is not suspended if the port is busy,
5392 instead the port command is aborted and false is returned.
5393 Change:
5395 More options can be added in a future release.
5396 Failures:
5399 badarg:
5401 If Port is not an identifier of an open port, or the regis‐
5402 tered name of an open port. If the calling process was pre‐
5403 viously linked to the closed port, identified by Port, the
5404 exit signal from the port is guaranteed to be delivered be‐
5405 fore this badarg exception occurs.
5406 badarg:
5408 If Data is an invalid I/O list.
5409 badarg:
5411 If OptionList is an invalid option list.
5412 notsup:
5414 If option force has been passed, but the driver of the port
5415 does not allow forcing through a busy port.
5416 Warning:
5418 Do not send data to an unknown port. Any undefined behavior is
5419 possible (including node crash) depending on how the port driver
5420 interprets the data.
5421 port_connect(Port, Pid) -> true
5424 Types:
5426 Port = port() | atom()
5428 Pid = pid()
5429 Sets the port owner (the connected port) to Pid. Roughly the
5431 same as Port ! {Owner, {connect, Pid}} except for the following:
5432 * The error behavior differs, see below.
5434 * The port does not reply with {Port,connected}.
5436 * port_connect/1 is synchronous, see below.
5438 * The new port owner gets linked to the port.
5440 The old port owner stays linked to the port and must call un‐
5442 link(Port) if this is not desired. Any process can set the port
5443 owner to be any process with port_connect/2.
5444 For comparison: Port ! {self(), {connect, Pid}} only fails with
5446 badarg if Port does not refer to a port or a process. If Port is
5447 a closed port, nothing happens. If Port is an open port and the
5448 calling process is the port owner, the port replies with {Port,
5449 connected} to the old port owner. Notice that the old port owner
5450 is still linked to the port, while the new is not. If Port is an
5451 open port and the calling process is not the port owner, the
5452 port owner fails with badsig. The port owner fails with badsig
5453 also if Pid is not an existing local process identifier.
5454 Notice that any process can set the port owner using Port !
5456 {PortOwner, {connect, Pid}} as if it itself was the port owner,
5457 but the reply always goes to the port owner.
5458 As from Erlang/OTP R16, Port ! {PortOwner, {connect, Pid}} is
5460 truly asynchronous. Notice that this operation has always been
5461 documented as an asynchronous operation, while the underlying
5462 implementation has been synchronous. port_connect/2 is however
5463 still fully synchronous because of its error behavior.
5464 Failures:
5466 badarg:
5468 If Port is not an identifier of an open port, or the regis‐
5469 tered name of an open port. If the calling process was pre‐
5470 viously linked to the closed port, identified by Port, the
5471 exit signal from the port is guaranteed to be delivered be‐
5472 fore this badarg exception occurs.
5473 badarg:
5475 If the process identified by Pid is not an existing local
5476 process.
5477 port_control(Port, Operation, Data) -> iodata() | binary()
5479 Types:
5481 Port = port() | atom()
5483 Operation = integer()
5484 Data = iodata()
5485 Performs a synchronous control operation on a port. The meaning
5487 of Operation and Data depends on the port, that is, on the port
5488 driver. Not all port drivers support this control feature.
5489 Returns a list of integers in the range 0..255, or a binary, de‐
5491 pending on the port driver. The meaning of the returned data
5492 also depends on the port driver.
5493 Failures:
5495 badarg:
5497 If Port is not an open port or the registered name of an
5498 open port.
5499 badarg:
5501 If Operation cannot fit in a 32-bit integer.
5502 badarg:
5504 If the port driver does not support synchronous control op‐
5505 erations.
5506 badarg:
5508 If the port driver so decides for any reason (probably
5509 something wrong with Operation or Data).
5510 Warning:
5512 Do not call port_control/3 with an unknown Port identifier and
5513 expect badarg exception. Any undefined behavior is possible
5514 (including node crash) depending on how the port driver inter‐
5515 prets the supplied arguments.
5516 erlang:port_info(Port) -> Result
5519 Types:
5521 Port = port() | atom()
5523 ResultItem =
5524 {registered_name, RegisteredName :: atom()} |
5525 {id, Index :: integer() >= 0} |
5526 {connected, Pid :: pid()} |
5527 {links, Pids :: [pid()]} |
5528 {name, String :: string()} |
5529 {input, Bytes :: integer() >= 0} |
5530 {output, Bytes :: integer() >= 0} |
5531 {os_pid, OsPid :: integer() >= 0 | undefined}
5532 Result = [ResultItem] | undefined
5533 Returns a list containing tuples with information about Port, or
5535 undefined if the port is not open. The order of the tuples is
5536 undefined, and all the tuples are not mandatory. If the port is
5537 closed and the calling process was previously linked to the
5538 port, the exit signal from the port is guaranteed to be deliv‐
5539 ered before port_info/1 returns undefined.
5540 The result contains information about the following Items:
5542 * registered_name (if the port has a registered name)
5544 * id
5546 * connected
5548 * links
5550 * name
5552 * input
5554 * output
5556 For more information about the different Items, see port_info/2.
5558 Failure: badarg if Port is not a local port identifier, or an
5560 atom.
5561 erlang:port_info(Port, Item :: connected) ->
5563 {connected, Pid} | undefined
5564 Types:
5566 Port = port() | atom()
5568 Pid = pid()
5569 Pid is the process identifier of the process connected to the
5571 port.
5572 If the port identified by Port is not open, undefined is re‐
5574 turned. If the port is closed and the calling process was previ‐
5575 ously linked to the port, the exit signal from the port is guar‐
5576 anteed to be delivered before port_info/2 returns undefined.
5577 Failure: badarg if Port is not a local port identifier, or an
5579 atom.
5580 erlang:port_info(Port, Item :: id) -> {id, Index} | undefined
5582 Types:
5584 Port = port() | atom()
5586 Index = integer() >= 0
5587 Index is the internal index of the port. This index can be used
5589 to separate ports.
5590 If the port identified by Port is not open, undefined is re‐
5592 turned. If the port is closed and the calling process was previ‐
5593 ously linked to the port, the exit signal from the port is guar‐
5594 anteed to be delivered before port_info/2 returns undefined.
5595 Failure: badarg if Port is not a local port identifier, or an
5597 atom.
5598 erlang:port_info(Port, Item :: input) ->
5600 {input, Bytes} | undefined
5601 Types:
5603 Port = port() | atom()
5605 Bytes = integer() >= 0
5606 Bytes is the total number of bytes read from the port.
5608 If the port identified by Port is not open, undefined is re‐
5610 turned. If the port is closed and the calling process was previ‐
5611 ously linked to the port, the exit signal from the port is guar‐
5612 anteed to be delivered before port_info/2 returns undefined.
5613 Failure: badarg if Port is not a local port identifier, or an
5615 atom.
5616 erlang:port_info(Port, Item :: links) -> {links, Pids} | undefined
5618 Types:
5620 Port = port() | atom()
5622 Pids = [pid()]
5623 Pids is a list of the process identifiers of the processes that
5625 the port is linked to.
5626 If the port identified by Port is not open, undefined is re‐
5628 turned. If the port is closed and the calling process was previ‐
5629 ously linked to the port, the exit signal from the port is guar‐
5630 anteed to be delivered before port_info/2 returns undefined.
5631 Failure: badarg if Port is not a local port identifier, or an
5633 atom.
5634 erlang:port_info(Port, Item :: locking) ->
5636 {locking, Locking} | undefined
5637 Types:
5639 Port = port() | atom()
5641 Locking = false | port_level | driver_level
5642 Locking is one of the following:
5644 * port_level (port-specific locking)
5646 * driver_level (driver-specific locking)
5648 Notice that these results are highly implementation-specific and
5650 can change in a future release.
5651 If the port identified by Port is not open, undefined is re‐
5653 turned. If the port is closed and the calling process was previ‐
5654 ously linked to the port, the exit signal from the port is guar‐
5655 anteed to be delivered before port_info/2 returns undefined.
5656 Failure: badarg if Port is not a local port identifier, or an
5658 atom.
5659 erlang:port_info(Port, Item :: memory) ->
5661 {memory, Bytes} | undefined
5662 Types:
5664 Port = port() | atom()
5666 Bytes = integer() >= 0
5667 Bytes is the total number of bytes allocated for this port by
5669 the runtime system. The port itself can have allocated memory
5670 that is not included in Bytes.
5671 If the port identified by Port is not open, undefined is re‐
5673 turned. If the port is closed and the calling process was previ‐
5674 ously linked to the port, the exit signal from the port is guar‐
5675 anteed to be delivered before port_info/2 returns undefined.
5676 Failure: badarg if Port is not a local port identifier, or an
5678 atom.
5679 erlang:port_info(Port, Item :: monitors) ->
5681 {monitors, Monitors} | undefined
5682 Types:
5684 Port = port() | atom()
5686 Monitors = [{process, pid()}]
5687 Monitors represent processes monitored by this port.
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 erlang:port_info(Port, Item :: monitored_by) ->
5699 {monitored_by, MonitoredBy} | undefined
5700 Types:
5702 Port = port() | atom()
5704 MonitoredBy = [pid()]
5705 Returns list of pids that are monitoring given port at the mo‐
5707 ment.
5708 If the port identified by Port is not open, undefined is re‐
5710 turned. If the port is closed and the calling process was previ‐
5711 ously linked to the port, the exit signal from the port is guar‐
5712 anteed to be delivered before port_info/2 returns undefined.
5713 Failure: badarg if Port is not a local port identifier, or an
5715 atom.
5716 erlang:port_info(Port, Item :: name) -> {name, Name} | undefined
5718 Types:
5720 Port = port() | atom()
5722 Name = string()
5723 Name is the command name set by open_port/2.
5725 If the port identified by Port is not open, undefined is re‐
5727 turned. If the port is closed and the calling process was previ‐
5728 ously linked to the port, the exit signal from the port is guar‐
5729 anteed to be delivered before port_info/2 returns undefined.
5730 Failure: badarg if Port is not a local port identifier, or an
5732 atom.
5733 erlang:port_info(Port, Item :: os_pid) ->
5735 {os_pid, OsPid} | undefined
5736 Types:
5738 Port = port() | atom()
5740 OsPid = integer() >= 0 | undefined
5741 OsPid is the process identifier (or equivalent) of an OS process
5743 created with open_port({spawn | spawn_executable, Command}, Op‐
5744 tions). If the port is not the result of spawning an OS process,
5745 the value is undefined.
5746 If the port identified by Port is not open, undefined is re‐
5748 turned. If the port is closed and the calling process was previ‐
5749 ously linked to the port, the exit signal from the port is guar‐
5750 anteed to be delivered before port_info/2 returns undefined.
5751 Failure: badarg if Port is not a local port identifier, or an
5753 atom.
5754 erlang:port_info(Port, Item :: output) ->
5756 {output, Bytes} | undefined
5757 Types:
5759 Port = port() | atom()
5761 Bytes = integer() >= 0
5762 Bytes is the total number of bytes written to the port from Er‐
5764 lang processes using port_command/2, port_command/3, or Port !
5765 {Owner, {command, Data}.
5766 If the port identified by Port is not open, undefined is re‐
5768 turned. If the port is closed and the calling process was previ‐
5769 ously linked to the port, the exit signal from the port is guar‐
5770 anteed to be delivered before port_info/2 returns undefined.
5771 Failure: badarg if Port is not a local port identifier, or an
5773 atom.
5774 erlang:port_info(Port, Item :: parallelism) ->
5776 {parallelism, Boolean} | undefined
5777 Types:
5779 Port = port() | atom()
5781 Boolean = boolean()
5782 Boolean corresponds to the port parallelism hint used by this
5784 port. For more information, see option parallelism of
5785 open_port/2.
5786 erlang:port_info(Port, Item :: queue_size) ->
5788 {queue_size, Bytes} | undefined
5789 Types:
5791 Port = port() | atom()
5793 Bytes = integer() >= 0
5794 Bytes is the total number of bytes queued by the port using the
5796 ERTS driver queue implementation.
5797 If the port identified by Port is not open, undefined is re‐
5799 turned. If the port is closed and the calling process was previ‐
5800 ously linked to the port, the exit signal from the port is guar‐
5801 anteed to be delivered before port_info/2 returns undefined.
5802 Failure: badarg if Port is not a local port identifier, or an
5804 atom.
5805 erlang:port_info(Port, Item :: registered_name) ->
5807 {registered_name, RegisteredName} |
5808 [] | undefined
5809 Types:
5811 Port = port() | atom()
5813 RegisteredName = atom()
5814 RegisteredName is the registered name of the port. If the port
5816 has no registered name, [] is returned.
5817 If the port identified by Port is not open, undefined is re‐
5819 turned. If the port is closed and the calling process was previ‐
5820 ously linked to the port, the exit signal from the port is guar‐
5821 anteed to be delivered before port_info/2 returns undefined.
5822 Failure: badarg if Port is not a local port identifier, or an
5824 atom.
5825 port_to_list(Port) -> string()
5827 Types:
5829 Port = port()
5831 Returns a string corresponding to the text representation of the
5833 port identifier Port.
5834 erlang:ports() -> [port()]
5836 Returns a list of port identifiers corresponding to all the
5838 ports existing on the local node.
5839 Notice that an exiting port exists, but is not open.
5841 pre_loaded() -> [module()]
5843 Returns a list of Erlang modules that are preloaded in the run-
5845 time system. Pre-loaded modules are Erlang modules that are
5846 needed to bootstrap the system to load the first Erlang modules
5847 from either disk or by using erl_boot_server.
5848 erlang:process_display(Pid, Type) -> true
5850 Types:
5852 Pid = pid()
5854 Type = backtrace
5855 Writes information about the local process Pid on standard er‐
5857 ror. The only allowed value for the atom Type is backtrace,
5858 which shows the contents of the call stack, including informa‐
5859 tion about the call chain, with the current function printed
5860 first. The format of the output is not further defined.
5861 process_flag(Flag :: async_dist, Boolean) -> OldBoolean
5863 Types:
5865 Boolean = OldBoolean = boolean()
5867 Enable or disable fully asynchronous distributed signaling for
5869 the calling process. When disabled, which is the default, the
5870 process sending a distributed signal will block in the send op‐
5871 eration if the buffer for the distribution channel reach the
5872 distribution buffer busy limit. The process will remain blocked
5873 until the buffer shrinks enough. This might in some cases take a
5874 substantial amount of time. When async_dist is enabled, send op‐
5875 erations of distributed signals will always buffer the signal on
5876 the outgoing distribution channel and then immediately return.
5877 That is, these send operations will never block the sending
5878 process.
5879 Note:
5881 Since no flow control is enforced by the runtime system when
5882 async_dist process flag is enabled, you need to make sure that
5883 flow control for such data is implemented, or that the amount of
5884 such data is known to always be limited. Unlimited signaling
5885 with async_dist enabled in the absence of flow control will typ‐
5886 ically cause the sending runtime system to crash on an out of
5887 memory condition.
5888 Blocking due to disabled async_dist can be monitored by er‐
5891 lang:system_monitor() using the busy_dist_port option. Only data
5892 buffered by processes which (at the time of sending a signal)
5893 have disabled async_dist will be counted when determining
5894 whether or not an operation should block the caller.
5895 The async_dist flag can also be set on a new process when spawn‐
5897 ing it using the spawn_opt() BIF with the option {async_dist,
5898 Enable}. The default async_dist flag to use on newly spawned
5899 processes can be set by passing the command line argument +pad
5900 <boolean> when starting the runtime system. If the +pad <bool‐
5901 ean> command line argument is not passed, the default value of
5902 the async_dist flag will be false.
5903 You can inspect the state of the async_dist process flag of a
5905 process by calling process_info(Pid, async_dist).
5906 Returns the old value of the async_dist flag.
5908 process_flag(Flag :: trap_exit, Boolean) -> OldBoolean
5910 Types:
5912 Boolean = OldBoolean = boolean()
5914 When trap_exit is set to true, exit signals arriving to a
5916 process are converted to {'EXIT', From, Reason} messages, which
5917 can be received as ordinary messages. If trap_exit is set to
5918 false, the process exits if it receives an exit signal other
5919 than normal and the exit signal is propagated to its linked pro‐
5920 cesses. Application processes are normally not to trap exits.
5921 Returns the old value of the flag.
5923 See also exit/2.
5925 process_flag(Flag :: error_handler, Module) -> OldModule
5927 Types:
5929 Module = OldModule = atom()
5931 Used by a process to redefine the error handler for undefined
5933 function calls and undefined registered processes. Use this flag
5934 with substantial caution, as code auto-loading depends on the
5935 correct operation of the error handling module.
5936 Returns the old value of the flag.
5938 process_flag(Flag :: fullsweep_after, FullsweepAfter) ->
5940 OldFullsweepAfter
5941 Types:
5943 FullsweepAfter = OldFullsweepAfter = integer() >= 0
5945 Changes the maximum number of generational collections before
5947 forcing a fullsweep for the calling process.
5948 Returns the old value of the flag.
5950 process_flag(Flag :: min_heap_size, MinHeapSize) -> OldMinHeapSize
5952 Types:
5954 MinHeapSize = OldMinHeapSize = integer() >= 0
5956 Changes the minimum heap size for the calling process.
5958 Returns the old value of the flag.
5960 process_flag(Flag :: min_bin_vheap_size, MinBinVHeapSize) ->
5962 OldMinBinVHeapSize
5963 Types:
5965 MinBinVHeapSize = OldMinBinVHeapSize = integer() >= 0
5967 Changes the minimum binary virtual heap size for the calling
5969 process.
5970 Returns the old value of the flag.
5972 process_flag(Flag :: max_heap_size, MaxHeapSize) -> OldMaxHeapSize
5974 Types:
5976 MaxHeapSize = OldMaxHeapSize = max_heap_size()
5978 max_heap_size() =
5979 integer() >= 0 |
5980 #{size => integer() >= 0,
5981 kill => boolean(),
5982 error_logger => boolean(),
5983 include_shared_binaries => boolean()}
5984 This flag sets the maximum heap size for the calling process. If
5986 MaxHeapSize is an integer, the system default values for kill
5987 and error_logger are used.
5988 For details on how the heap grows, see Sizing the heap in the
5990 ERTS internal documentation.
5991 size:
5993 The maximum size in words of the process. If set to zero,
5994 the heap size limit is disabled. badarg is be thrown if the
5995 value is smaller than min_heap_size. The size check is only
5996 done when a garbage collection is triggered.
5997 size is the entire heap of the process when garbage collec‐
5999 tion is triggered. This includes all generational heaps, the
6000 process stack, any messages that are considered to be part
6001 of the heap, and any extra memory that the garbage collector
6002 needs during collection.
6003 size is the same as can be retrieved using er‐
6005 lang:process_info(Pid, total_heap_size), or by adding
6006 heap_block_size, old_heap_block_size and mbuf_size from er‐
6007 lang:process_info(Pid, garbage_collection_info).
6008 kill:
6010 When set to true, the runtime system sends an untrappable
6011 exit signal with reason kill to the process if the maximum
6012 heap size is reached. The garbage collection that triggered
6013 the kill is not completed, instead the process exits as soon
6014 as possible. When set to false, no exit signal is sent to
6015 the process, instead it continues executing.
6016 If kill is not defined in the map, the system default will
6018 be used. The default system default is true. It can be
6019 changed by either option +hmaxk in erl(1), or erlang:sys‐
6020 tem_flag(max_heap_size, MaxHeapSize).
6021 error_logger:
6023 When set to true, the runtime system logs an error event via
6024 logger, containing details about the process when the maxi‐
6025 mum heap size is reached. One log event is sent each time
6026 the limit is reached.
6027 If error_logger is not defined in the map, the system de‐
6029 fault is used. The default system default is true. It can be
6030 changed by either the option +hmaxel int erl(1), or er‐
6031 lang:system_flag(max_heap_size, MaxHeapSize).
6032 include_shared_binaries:
6034 When set to true, off-heap binaries are included in the to‐
6035 tal sum compared against the size limit. Off-heap binaries
6036 are typically larger binaries that may be shared between
6037 processes. The size of a shared binary is included by all
6038 processes that are referring it. Also, the entire size of a
6039 large binary may be included even if only a smaller part of
6040 it is referred by the process.
6041 If include_shared_binaries is not defined in the map, the
6043 system default is used. The default system default is false.
6044 It can be changed by either the option +hmaxib in erl(1), or
6045 erlang:system_flag(max_heap_size, MaxHeapSize).
6046 The heap size of a process is quite hard to predict, especially
6048 the amount of memory that is used during the garbage collection.
6049 When contemplating using this option, it is recommended to first
6050 run it in production with kill set to false and inspect the log
6051 events to see what the normal peak sizes of the processes in the
6052 system is and then tune the value accordingly.
6053 process_flag(Flag :: message_queue_data, MQD) -> OldMQD
6055 Types:
6057 MQD = OldMQD = message_queue_data()
6059 message_queue_data() = off_heap | on_heap
6060 Determines how messages in the message queue are stored, as fol‐
6062 lows:
6063 off_heap:
6065 All messages in the message queue will be stored outside the
6066 process heap. This implies that no messages in the message
6067 queue will be part of a garbage collection of the process.
6068 on_heap:
6070 All messages in the message queue will eventually be placed
6071 on the process heap. They can, however, be temporarily
6072 stored off the heap. This is how messages have always been
6073 stored up until ERTS 8.0.
6074 The default value of the message_queue_data process flag is de‐
6076 termined by the command-line argument +hmqd in erl(1).
6077 If the process may potentially accumulate a large number of mes‐
6079 sages in its queue it is recommended to set the flag value to
6080 off_heap. This is due to the fact that the garbage collection of
6081 a process that has a large number of messages stored on the heap
6082 can become extremely expensive and the process can consume large
6083 amounts of memory. The performance of the actual message passing
6084 is, however, generally better when the flag value is on_heap.
6085 Changing the flag value causes any existing messages to be
6087 moved. The move operation is initiated, but not necessarily com‐
6088 pleted, by the time the function returns.
6089 Returns the old value of the flag.
6091 process_flag(Flag :: priority, Level) -> OldLevel
6093 Types:
6095 Level = OldLevel = priority_level()
6097 priority_level() = low | normal | high | max
6098 Sets the process priority. Level is an atom. Four priority lev‐
6100 els exist: low, normal, high, and max. Default is normal.
6101 Note:
6103 Priority level max is reserved for internal use in the Erlang
6104 runtime system, and is not to be used by others.
6105 Internally in each priority level, processes are scheduled in a
6108 round robin fashion.
6109 Execution of processes on priority normal and low are inter‐
6111 leaved. Processes on priority low are selected for execution
6112 less frequently than processes on priority normal.
6113 When runnable processes on priority high exist, no processes on
6115 priority low or normal are selected for execution. Notice how‐
6116 ever that this does not mean that no processes on priority low
6117 or normal can run when processes are running on priority high.
6118 When using multiple schedulers, more processes can be running in
6119 parallel than processes on priority high. That is, a low and a
6120 high priority process can execute at the same time.
6121 When runnable processes on priority max exist, no processes on
6123 priority low, normal, or high are selected for execution. As
6124 with priority high, processes on lower priorities can execute in
6125 parallel with processes on priority max.
6126 Scheduling is pre-emptive. Regardless of priority, a process is
6128 pre-empted when it has consumed more than a certain number of
6129 reductions since the last time it was selected for execution.
6130 Note:
6132 Do not depend on the scheduling to remain exactly as it is to‐
6133 day. Scheduling is likely to be changed in a future release to
6134 use available processor cores better.
6135 There is no automatic mechanism for avoiding priority inversion,
6138 such as priority inheritance or priority ceilings. When using
6139 priorities, take this into account and handle such scenarios by
6140 yourself.
6141 Making calls from a high priority process into code that you has
6143 no control over can cause the high priority process to wait for
6144 a process with lower priority. That is, effectively decreasing
6145 the priority of the high priority process during the call. Even
6146 if this is not the case with one version of the code that you
6147 have no control over, it can be the case in a future version of
6148 it. This can, for example, occur if a high priority process
6149 triggers code loading, as the code server runs on priority nor‐
6150 mal.
6151 Other priorities than normal are normally not needed. When other
6153 priorities are used, use them with care, especially priority
6154 high. A process on priority high is only to perform work for
6155 short periods. Busy looping for long periods in a high priority
6156 process causes most likely problems, as important OTP servers
6157 run on priority normal.
6158 Returns the old value of the flag.
6160 process_flag(Flag :: save_calls, N) -> OldN
6162 Types:
6164 N = OldN = 0..10000
6166 N must be an integer in the interval 0..10000. If N > 0, call
6168 saving is made active for the process. This means that informa‐
6169 tion about the N most recent global function calls, BIF calls,
6170 sends, and receives made by the process are saved in a list,
6171 which can be retrieved with process_info(Pid, last_calls). A
6172 global function call is one in which the module of the function
6173 is explicitly mentioned. Only a fixed amount of information is
6174 saved, as follows:
6175 * A tuple {Module, Function, Arity} for function calls
6177 * The atoms send, 'receive', and timeout for sends and re‐
6179 ceives ('receive' when a message is received and timeout
6180 when a receive times out)
6181 If N = 0, call saving is disabled for the process, which is the
6183 default. Whenever the size of the call saving list is set, its
6184 contents are reset.
6185 Returns the old value of the flag.
6187 process_flag(Flag :: sensitive, Boolean) -> OldBoolean
6189 Types:
6191 Boolean = OldBoolean = boolean()
6193 Sets or clears flag sensitive for the current process. When a
6195 process has been marked as sensitive by calling
6196 process_flag(sensitive, true), features in the runtime system
6197 that can be used for examining the data or inner working of the
6198 process are silently disabled.
6199 Features that are disabled include (but are not limited to) the
6201 following:
6202 * Tracing. Trace flags can still be set for the process, but
6204 no trace messages of any kind are generated. (If flag sensi‐
6205 tive is turned off, trace messages are again generated if
6206 any trace flags are set.)
6207 * Sequential tracing. The sequential trace token is propagated
6209 as usual, but no sequential trace messages are generated.
6210 process_info/1,2 cannot be used to read out the message queue or
6212 the process dictionary (both are returned as empty lists).
6213 Stack back-traces cannot be displayed for the process.
6215 In crash dumps, the stack, messages, and the process dictionary
6217 are omitted.
6218 If {save_calls,N} has been set for the process, no function
6220 calls are saved to the call saving list. (The call saving list
6221 is not cleared. Also, send, receive, and time-out events are
6222 still added to the list.)
6223 Returns the old value of the flag.
6225 process_flag(Pid, Flag, Value) -> OldValue
6227 Types:
6229 Pid = pid()
6231 Flag = save_calls
6232 Value = OldValue = integer() >= 0
6233 Sets certain flags for the process Pid, in the same manner as
6235 process_flag/2. Returns the old value of the flag. The valid
6236 values for Flag are only a subset of those allowed in
6237 process_flag/2, namely save_calls.
6238 Failure: badarg if Pid is not a local process.
6240 process_info(Pid) -> Info
6242 Types:
6244 Pid = pid()
6246 Info = [InfoTuple] | undefined
6247 InfoTuple = process_info_result_item()
6248 process_info_result_item() =
6249 {async_dist, Enabled :: boolean()} |
6250 {backtrace, Bin :: binary()} |
6251 {binary,
6252 BinInfo ::
6253 [{integer() >= 0,
6254 integer() >= 0,
6255 integer() >= 0}]} |
6256 {catchlevel, CatchLevel :: integer() >= 0} |
6257 {current_function,
6258 {Module :: module(), Function :: atom(), Arity :: arity()} |
6259 undefined} |
6260 {current_location,
6261 {Module :: module(),
6262 Function :: atom(),
6263 Arity :: arity(),
6264 Location ::
6265 [{file, Filename :: string()} |
6266 {line, Line :: integer() >= 1}]}} |
6267 {current_stacktrace, Stack :: [stack_item()]} |
6268 {dictionary, Dictionary :: [{Key :: term(), Value :: term()}]} |
6269 {error_handler, Module :: module()} |
6270 {garbage_collection, GCInfo :: [{atom(), integer() >= 0}]} |
6271 {garbage_collection_info,
6272 GCInfo :: [{atom(), integer() >= 0}]} |
6273 {group_leader, GroupLeader :: pid()} |
6274 {heap_size, Size :: integer() >= 0} |
6275 {initial_call, mfa()} |
6276 {links, PidsAndPorts :: [pid() | port()]} |
6277 {last_calls, false | (Calls :: [mfa()])} |
6278 {memory, Size :: integer() >= 0} |
6279 {message_queue_len, MessageQueueLen :: integer() >= 0} |
6280 {messages, MessageQueue :: [term()]} |
6281 {min_heap_size, MinHeapSize :: integer() >= 0} |
6282 {min_bin_vheap_size, MinBinVHeapSize :: integer() >= 0} |
6283 {max_heap_size, MaxHeapSize :: max_heap_size()} |
6284 {monitored_by,
6285 MonitoredBy :: [pid() | port() | nif_resource()]} |
6286 {monitors,
6287 Monitors ::
6288 [{process | port,
6289 Pid ::
6290 pid() |
6291 port() |
6292 {RegName :: atom(), Node :: node()}}]} |
6293 {message_queue_data, MQD :: message_queue_data()} |
6294 {parent, pid() | undefined} |
6295 {priority, Level :: priority_level()} |
6296 {reductions, Number :: integer() >= 0} |
6297 {registered_name, [] | (Atom :: atom())} |
6298 {sequential_trace_token,
6299 [] | (SequentialTraceToken :: term())} |
6300 {stack_size, Size :: integer() >= 0} |
6301 {status,
6302 Status ::
6303 exiting | garbage_collecting | waiting | running |
6304 runnable | suspended} |
6305 {suspending,
6306 SuspendeeList ::
6307 [{Suspendee :: pid(),
6308 ActiveSuspendCount :: integer() >= 0,
6309 OutstandingSuspendCount :: integer() >= 0}]} |
6310 {total_heap_size, Size :: integer() >= 0} |
6311 {trace, InternalTraceFlags :: integer() >= 0} |
6312 {trap_exit, Boolean :: boolean()}
6313 priority_level() = low | normal | high | max
6314 stack_item() =
6315 {Module :: module(),
6316 Function :: atom(),
6317 Arity :: arity() | (Args :: [term()]),
6318 Location ::
6319 [{file, Filename :: string()} |
6320 {line, Line :: integer() >= 1}]}
6321 max_heap_size() =
6322 integer() >= 0 |
6323 #{size => integer() >= 0,
6324 kill => boolean(),
6325 error_logger => boolean(),
6326 include_shared_binaries => boolean()}
6327 message_queue_data() = off_heap | on_heap
6328 Returns a list containing InfoTuples with miscellaneous informa‐
6330 tion about the process identified by Pid, or undefined if the
6331 process is not alive.
6332 The order of the InfoTuples is undefined and all InfoTuples are
6334 not mandatory. The InfoTuples part of the result can be changed
6335 without prior notice.
6336 The InfoTuples with the following items are part of the result:
6338 * current_function
6340 * initial_call
6342 * status
6344 * message_queue_len
6346 * links
6348 * dictionary
6350 * trap_exit
6352 * error_handler
6354 * priority
6356 * group_leader
6358 * total_heap_size
6360 * heap_size
6362 * stack_size
6364 * reductions
6366 * garbage_collection
6368 If the process identified by Pid has a registered name, also an
6370 InfoTuple with item registered_name is included.
6371 For information about specific InfoTuples, see process_info/2.
6373 Warning:
6375 This BIF is intended for debugging only. For all other purposes,
6376 use process_info/2.
6377 Failure: badarg if Pid is not a local process.
6380 process_info(Pid, Item) -> InfoTuple | [] | undefined
6382 process_info(Pid, ItemList) -> InfoTupleList | [] | undefined
6384 Types:
6386 Pid = pid()
6388 ItemList = [Item]
6389 Item = process_info_item()
6390 InfoTupleList = [InfoTuple]
6391 InfoTuple = process_info_result_item()
6392 process_info_item() =
6393 async_dist | backtrace | binary | catchlevel |
6394 current_function | current_location | current_stacktrace |
6395 dictionary | error_handler | garbage_collection |
6396 garbage_collection_info | group_leader | heap_size |
6397 initial_call | links | last_calls | memory |
6398 message_queue_len | messages | min_heap_size |
6399 min_bin_vheap_size | monitored_by | monitors |
6400 message_queue_data | parent | priority | reductions |
6401 registered_name | sequential_trace_token | stack_size |
6402 status | suspending | total_heap_size | trace | trap_exit
6403 process_info_result_item() =
6404 {async_dist, Enabled :: boolean()} |
6405 {backtrace, Bin :: binary()} |
6406 {binary,
6407 BinInfo ::
6408 [{integer() >= 0,
6409 integer() >= 0,
6410 integer() >= 0}]} |
6411 {catchlevel, CatchLevel :: integer() >= 0} |
6412 {current_function,
6413 {Module :: module(), Function :: atom(), Arity :: arity()} |
6414 undefined} |
6415 {current_location,
6416 {Module :: module(),
6417 Function :: atom(),
6418 Arity :: arity(),
6419 Location ::
6420 [{file, Filename :: string()} |
6421 {line, Line :: integer() >= 1}]}} |
6422 {current_stacktrace, Stack :: [stack_item()]} |
6423 {dictionary, Dictionary :: [{Key :: term(), Value :: term()}]} |
6424 {error_handler, Module :: module()} |
6425 {garbage_collection, GCInfo :: [{atom(), integer() >= 0}]} |
6426 {garbage_collection_info,
6427 GCInfo :: [{atom(), integer() >= 0}]} |
6428 {group_leader, GroupLeader :: pid()} |
6429 {heap_size, Size :: integer() >= 0} |
6430 {initial_call, mfa()} |
6431 {links, PidsAndPorts :: [pid() | port()]} |
6432 {last_calls, false | (Calls :: [mfa()])} |
6433 {memory, Size :: integer() >= 0} |
6434 {message_queue_len, MessageQueueLen :: integer() >= 0} |
6435 {messages, MessageQueue :: [term()]} |
6436 {min_heap_size, MinHeapSize :: integer() >= 0} |
6437 {min_bin_vheap_size, MinBinVHeapSize :: integer() >= 0} |
6438 {max_heap_size, MaxHeapSize :: max_heap_size()} |
6439 {monitored_by,
6440 MonitoredBy :: [pid() | port() | nif_resource()]} |
6441 {monitors,
6442 Monitors ::
6443 [{process | port,
6444 Pid ::
6445 pid() |
6446 port() |
6447 {RegName :: atom(), Node :: node()}}]} |
6448 {message_queue_data, MQD :: message_queue_data()} |
6449 {parent, pid() | undefined} |
6450 {priority, Level :: priority_level()} |
6451 {reductions, Number :: integer() >= 0} |
6452 {registered_name, [] | (Atom :: atom())} |
6453 {sequential_trace_token,
6454 [] | (SequentialTraceToken :: term())} |
6455 {stack_size, Size :: integer() >= 0} |
6456 {status,
6457 Status ::
6458 exiting | garbage_collecting | waiting | running |
6459 runnable | suspended} |
6460 {suspending,
6461 SuspendeeList ::
6462 [{Suspendee :: pid(),
6463 ActiveSuspendCount :: integer() >= 0,
6464 OutstandingSuspendCount :: integer() >= 0}]} |
6465 {total_heap_size, Size :: integer() >= 0} |
6466 {trace, InternalTraceFlags :: integer() >= 0} |
6467 {trap_exit, Boolean :: boolean()}
6468 stack_item() =
6469 {Module :: module(),
6470 Function :: atom(),
6471 Arity :: arity() | (Args :: [term()]),
6472 Location ::
6473 [{file, Filename :: string()} |
6474 {line, Line :: integer() >= 1}]}
6475 priority_level() = low | normal | high | max
6476 max_heap_size() =
6477 integer() >= 0 |
6478 #{size => integer() >= 0,
6479 kill => boolean(),
6480 error_logger => boolean(),
6481 include_shared_binaries => boolean()}
6482 message_queue_data() = off_heap | on_heap
6483 Returns information about the process identified by Pid, as
6485 specified by Item or ItemList. Returns undefined if the process
6486 is not alive.
6487 If the process is alive and a single Item is specified, the re‐
6489 turned value is the corresponding InfoTuple, unless Item =:=
6490 registered_name and the process has no registered name. In this
6491 case, [] is returned. This strange behavior is because of his‐
6492 torical reasons, and is kept for backward compatibility.
6493 If ItemList is specified, the result is InfoTupleList. The Info‐
6495 Tuples in InfoTupleList are included with the corresponding
6496 Items in the same order as the Items were included in ItemList.
6497 Valid Items can be included multiple times in ItemList.
6498 Getting process information follows the signal ordering guaran‐
6500 tees described in the Processes Chapter in the Erlang Reference
6501 Manual .
6502 Note:
6504 If registered_name is part of ItemList and the process has no
6505 name registered, a {registered_name, []}, InfoTuple will be in‐
6506 cluded in the resulting InfoTupleList. This behavior is differ‐
6507 ent when a single Item =:= registered_name is specified, and
6508 when process_info/1 is used.
6509 Valid InfoTuples with corresponding Items:
6512 {async_dist, Enabled}:
6514 Since: OTP 25.3
6515 Current value of the async_dist process flag.
6517 {backtrace, Bin}:
6519 Binary Bin contains the same information as the output from
6520 erlang:process_display(Pid, backtrace). Use binary_to_list/1
6521 to obtain the string of characters from the binary.
6522 {binary, BinInfo}:
6524 BinInfo is a list containing miscellaneous information about
6525 binaries on the heap of this process. This InfoTuple can be
6526 changed or removed without prior notice. In the current im‐
6527 plementation BinInfo is a list of tuples. The tuples con‐
6528 tain; BinaryId, BinarySize, BinaryRefcCount.
6529 Depending on the value of the message_queue_data process
6531 flag the message queue may be stored on the heap.
6532 {catchlevel, CatchLevel}:
6534 CatchLevel is the number of currently active catches in this
6535 process. This InfoTuple can be changed or removed without
6536 prior notice.
6537 {current_function, {Module, Function, Arity} | undefined}:
6539 Module, Function, Arity is the current function call of the
6540 process. The value undefined can be returned if the process
6541 is currently executing native compiled code.
6542 {current_location, {Module, Function, Arity, Location}}:
6544 Module, Function, Arity is the current function call of the
6545 process. Location is a list of two-tuples describing the lo‐
6546 cation in the source code.
6547 {current_stacktrace, Stack}:
6549 Returns the current call stack back-trace (stacktrace) of
6550 the process. The stack has the same format as in the catch
6551 part of a try. See The call-stack back trace (stacktrace).
6552 The depth of the stacktrace is truncated according to the
6553 backtrace_depth system flag setting.
6554 {dictionary, Dictionary}:
6556 Dictionary is the process dictionary.
6557 {error_handler, Module}:
6559 Module is the error handler module used by the process (for
6560 undefined function calls, for example).
6561 {garbage_collection, GCInfo}:
6563 GCInfo is a list containing miscellaneous information about
6564 garbage collection for this process. The content of GCInfo
6565 can be changed without prior notice.
6566 {garbage_collection_info, GCInfo}:
6568 GCInfo is a list containing miscellaneous detailed informa‐
6569 tion about garbage collection for this process. The content
6570 of GCInfo can be changed without prior notice. For details
6571 about the meaning of each item, see gc_minor_start in er‐
6572 lang:trace/3.
6573 {group_leader, GroupLeader}:
6575 GroupLeader is the group leader for the I/O of the process.
6576 {heap_size, Size}:
6578 Size is the size in words of the youngest heap generation of
6579 the process. This generation includes the process stack.
6580 This information is highly implementation-dependent, and can
6581 change if the implementation changes.
6582 {initial_call, {Module, Function, Arity}}:
6584 Module, Function, Arity is the initial function call with
6585 which the process was spawned.
6586 {links, PidsAndPorts}:
6588 PidsAndPorts is a list of process identifiers and port iden‐
6589 tifiers, with processes or ports to which the process has a
6590 link.
6591 {last_calls, false|Calls}:
6593 The value is false if call saving is not active for the
6594 process (see process_flag/3). If call saving is active, a
6595 list is returned, in which the last element is the most re‐
6596 cent called.
6597 {memory, Size}:
6599 Size is the size in bytes of the process. This includes call
6602 stack, heap, and internal structures.
6603 {message_queue_len, MessageQueueLen}:
6605 MessageQueueLen is the number of messages currently in the
6606 message queue of the process. This is the length of the list
6607 MessageQueue returned as the information item messages (see
6608 below).
6609 {messages, MessageQueue}:
6611 MessageQueue is a list of the messages to the process, which
6612 have not yet been processed.
6613 {min_heap_size, MinHeapSize}:
6615 MinHeapSize is the minimum heap size for the process.
6616 {min_bin_vheap_size, MinBinVHeapSize}:
6618 MinBinVHeapSize is the minimum binary virtual heap size for
6619 the process.
6620 {monitored_by, MonitoredBy}:
6622 A list of identifiers for all the processes, ports and NIF
6623 resources, that are monitoring the process.
6624 {monitors, Monitors}:
6626 A list of monitors (started by monitor/2) that are active
6627 for the process. For a local process monitor or a remote
6628 process monitor by a process identifier, the list consists
6629 of:
6630 {process, Pid}:
6632 Process is monitored by pid.
6633 {process, {RegName, Node}}:
6635 Local or remote process is monitored by name.
6636 {port, PortId}:
6638 Local port is monitored by port id.
6639 {port, {RegName, Node}}:
6641 Local port is monitored by name. Please note, that remote
6642 port monitors are not supported, so Node will always be
6643 the local node name.
6644 {message_queue_data, MQD}:
6646 MQD is the current value of the message_queue_data process
6647 flag, which can be either off_heap or on_heap. For more in‐
6648 formation, see the documentation of process_flag(mes‐
6649 sage_queue_data, MQD).
6650 {parent, Pid}:
6652 Pid is the identifier of the parent process, the one that
6653 spawned current process. When the process does not have a
6654 parent undefined is returned. Only the initial process
6655 (init) on a node lacks a parent, though.
6656 {priority, Level}:
6658 Level is the current priority level for the process. For
6659 more information on priorities, see process_flag(priority,
6660 Level).
6661 {reductions, Number}:
6663 Number is the number of reductions executed by the process.
6664 {registered_name, Atom}:
6666 Atom is the registered process name. If the process has no
6667 registered name, this tuple is not present in the list.
6668 {sequential_trace_token, [] | SequentialTraceToken}:
6670 SequentialTraceToken is the sequential trace token for the
6671 process. This InfoTuple can be changed or removed without
6672 prior notice.
6673 {stack_size, Size}:
6675 Size is the stack size, in words, of the process.
6676 {status, Status}:
6678 Status is the status of the process and is one of the fol‐
6679 lowing:
6680 * exiting
6682 * garbage_collecting
6684 * waiting (for a message)
6686 * running
6688 * runnable (ready to run, but another process is running)
6690 * suspended (suspended on a "busy" port or by the BIF er‐
6692 lang:suspend_process/1,2)
6693 {suspending, SuspendeeList}:
6695 SuspendeeList is a list of {Suspendee, ActiveSuspendCount,
6696 OutstandingSuspendCount} tuples. Suspendee is the process
6697 identifier of a process that has been, or is to be, sus‐
6698 pended by the process identified by Pid through the BIF er‐
6699 lang:suspend_process/2 or erlang:suspend_process/1.
6700 ActiveSuspendCount is the number of times Suspendee has been
6702 suspended by Pid. OutstandingSuspendCount is the number of
6703 not yet completed suspend requests sent by Pid, that is:
6704 * If ActiveSuspendCount =/= 0, Suspendee is currently in the
6706 suspended state.
6707 * If OutstandingSuspendCount =/= 0, option asynchronous of
6709 erlang:suspend_process/2 has been used and the suspendee
6710 has not yet been suspended by Pid.
6711 Notice that ActiveSuspendCount and OutstandingSuspendCount
6713 are not the total suspend count on Suspendee, only the parts
6714 contributed by Pid.
6715 {total_heap_size, Size}:
6717 Size is the total size, in words, of all heap fragments of
6718 the process. This includes the process stack and any unre‐
6719 ceived messages that are considered to be part of the heap.
6720 {trace, InternalTraceFlags}:
6722 InternalTraceFlags is an integer representing the internal
6723 trace flag for this process. This InfoTuple can be changed
6724 or removed without prior notice.
6725 {trap_exit, Boolean}:
6727 Boolean is true if the process is trapping exits, otherwise
6728 false.
6729 Notice that not all implementations support all these Items.
6731 Failures:
6733 badarg:
6735 If Pid is not a local process.
6736 badarg:
6738 If Item is an invalid item.
6739 processes() -> [pid()]
6741 Returns a list of process identifiers corresponding to all the
6743 processes currently existing on the local node.
6744 Notice that an exiting process exists, but is not alive. That
6746 is, is_process_alive/1 returns false for an exiting process, but
6747 its process identifier is part of the result returned from pro‐
6748 cesses/0.
6749 Example:
6751 > processes().
6753 [<0.0.0>,<0.2.0>,<0.4.0>,<0.5.0>,<0.7.0>,<0.8.0>]
6754 purge_module(Module) -> true
6756 Types:
6758 Module = atom()
6760 Removes old code for Module. Before this BIF is used,
6762 check_process_code/2 is to be called to check that no processes
6763 execute old code in the module.
6764 Warning:
6766 This BIF is intended for the code server (see code(3)) and is
6767 not to be used elsewhere.
6768 Change:
6771 As from ERTS 8.0 (Erlang/OTP 19), any lingering processes that
6772 still execute the old code is killed by this function. In ear‐
6773 lier versions, such incorrect use could cause much more fatal
6774 failures, like emulator crash.
6775 Failure: badarg if there is no old code for Module.
6778 put(Key, Val) -> term()
6780 Types:
6782 Key = Val = term()
6784 Adds a new Key to the process dictionary, associated with the
6786 value Val, and returns undefined. If Key exists, the old value
6787 is deleted and replaced by Val, and the function returns the old
6788 value. The average time complexity for the current implementa‐
6789 tion of this function is O(1) and the worst case time complexity
6790 is O(N), where N is the number of items in the process dictio‐
6791 nary. Example:
6792 > X = put(name, walrus), Y = put(name, carpenter),
6794 Z = get(name),
6795 {X, Y, Z}.
6796 {undefined,walrus,carpenter}
6797 Note:
6799 The values stored when put is evaluated within the scope of a
6800 catch are not retracted if a throw is evaluated, or if an error
6801 occurs.
6802 erlang:raise(Class, Reason, Stacktrace) -> badarg
6805 Types:
6807 Class = error | exit | throw
6809 Reason = term()
6810 Stacktrace = raise_stacktrace() | stacktrace()
6811 raise_stacktrace() =
6812 [{module(), atom(), arity() | [term()]} |
6813 {function(), arity() | [term()]}]
6814 Raises an exception of the specified class, reason, and call
6816 stack backtrace (stacktrace).
6817 Class is error, exit, or throw. So, if it were not for the
6819 stacktrace, erlang:raise(Class, Reason, Stacktrace) is equiva‐
6820 lent to erlang:Class(Reason) (given that Class is a valid
6821 class).
6822 Reason can be any term.
6824 Stacktrace is a list as provided in a try-catch clause.
6826 try
6828 ...
6829 catch Class:Reason:Stacktrace ->
6830 ...
6831 end
6832 That is, a list of four-tuples {Module, Function, Arity | Args,
6834 ExtraInfo}, where Module and Function are atoms, and the third
6835 element is an integer arity or an argument list. The stacktrace
6836 can also contain {Fun, Args, ExtraInfo} tuples, where Fun is a
6837 local fun and Args is an argument list.
6838 Element ExtraInfo at the end is optional. Omitting it is equiva‐
6840 lent to specifying an empty list.
6841 The stacktrace is used as the exception stacktrace for the call‐
6843 ing process; it is truncated to the current maximum stacktrace
6844 depth.
6845 As evaluating this function causes the process to terminate, it
6847 has no return value unless the arguments are invalid, in which
6848 case the function returns the error reason badarg. If you want
6849 to be sure not to return, you can call error(erlang:raise(Class,
6850 Reason, Stacktrace)) and hope to distinguish exceptions later.
6851 See the reference manual about errors and error handling for
6853 more information about exception classes and how to catch excep‐
6854 tions.
6855 erlang:read_timer(TimerRef) -> Result
6857 Types:
6859 TimerRef = reference()
6861 Time = integer() >= 0
6862 Result = Time | false
6863 Reads the state of a timer. The same as calling er‐
6865 lang:read_timer(TimerRef, []).
6866 erlang:read_timer(TimerRef, Options) -> Result | ok
6868 Types:
6870 TimerRef = reference()
6872 Async = boolean()
6873 Option = {async, Async}
6874 Options = [Option]
6875 Time = integer() >= 0
6876 Result = Time | false
6877 Reads the state of a timer that has been created by either er‐
6879 lang:start_timer or erlang:send_after. TimerRef identifies the
6880 timer, and was returned by the BIF that created the timer.
6881 Options:
6883 {async, Async}:
6885 Asynchronous request for state information. Async defaults
6886 to false, which causes the operation to be performed syn‐
6887 chronously. In this case, the Result is returned by er‐
6888 lang:read_timer. When Async is true, erlang:read_timer sends
6889 an asynchronous request for the state information to the
6890 timer service that manages the timer, and then returns ok. A
6891 message on the format {read_timer, TimerRef, Result} is sent
6892 to the caller of erlang:read_timer when the operation has
6893 been processed.
6894 More Options can be added in the future.
6896 If Result is an integer, it represents the time in milliseconds
6898 left until the timer expires.
6899 If Result is false, a timer corresponding to TimerRef could not
6901 be found. This because the timer had expired, or been canceled,
6902 or because TimerRef never has corresponded to a timer. Even if
6903 the timer has expired, it does not tell you whether or not the
6904 time-out message has arrived at its destination yet.
6905 Note:
6907 The timer service that manages the timer can be co-located with
6908 another scheduler than the scheduler that the calling process is
6909 executing on. If so, communication with the timer service takes
6910 much longer time than if it is located locally. If the calling
6911 process is in a critical path, and can do other things while
6912 waiting for the result of this operation, you want to use option
6913 {async, true}. If using option {async, false}, the calling
6914 process is blocked until the operation has been performed.
6915 See also erlang:send_after/4, erlang:start_timer/4, and er‐
6918 lang:cancel_timer/2.
6919 ref_to_list(Ref) -> string()
6921 Types:
6923 Ref = reference()
6925 Returns a string corresponding to the text representation of
6927 Ref.
6928 Warning:
6930 This BIF is intended for debugging and is not to be used in ap‐
6931 plication programs.
6932 register(RegName, PidOrPort) -> true
6935 Types:
6937 RegName = atom()
6939 PidOrPort = port() | pid()
6940 Registers the name RegName with a process identifier (pid) or a
6942 port identifier in the name registry. RegName, which must be an
6943 atom, can be used instead of the pid or port identifier in send
6944 operator (RegName ! Message) and most other BIFs that take a pid
6945 or port identifies as an argument. Example:
6946 > register(db, Pid).
6948 true
6949 The registered name is considered a Directly Visible Erlang Re‐
6951 source and is automatically unregistered when the process termi‐
6952 nates.
6953 Failures:
6955 badarg:
6957 If PidOrPort is not an existing local process or port.
6958 badarg:
6960 If RegName is already in use.
6961 badarg:
6963 If the process or port is already registered (already has a
6964 name).
6965 badarg:
6967 If RegName is the atom undefined.
6968 registered() -> [RegName]
6970 Types:
6972 RegName = atom()
6974 Returns a list of names that have been registered using regis‐
6976 ter/2, for example:
6977 > registered().
6979 [code_server, file_server, init, user, my_db]
6980 erlang:resume_process(Suspendee) -> true
6982 Types:
6984 Suspendee = pid()
6986 Decreases the suspend count on the process identified by Sus‐
6988 pendee. Suspendee is previously to have been suspended through
6989 erlang:suspend_process/2 or erlang:suspend_process/1 by the
6990 process calling erlang:resume_process(Suspendee). When the sus‐
6991 pend count on Suspendee reaches zero, Suspendee is resumed, that
6992 is, its state is changed from suspended into the state it had
6993 before it was suspended.
6994 Warning:
6996 This BIF is intended for debugging only.
6997 Failures:
7000 badarg:
7002 If Suspendee is not a process identifier.
7003 badarg:
7005 If the process calling erlang:resume_process/1 had not pre‐
7006 viously increased the suspend count on the process identi‐
7007 fied by Suspendee.
7008 badarg:
7010 If the process identified by Suspendee is not alive.
7011 round(Number) -> integer()
7013 Types:
7015 Number = number()
7017 Returns an integer by rounding Number, for example:
7019 round(42.1).
7021 42
7022 round(5.5).
7024 6
7025 round(-5.5).
7027 -6
7028 round(36028797018963969.0).
7030 36028797018963968
7031 In the last example, round(36028797018963969.0) evaluates to
7033 36028797018963968. The reason for this is that the number
7034 36028797018963969.0 cannot be represented exactly as a float
7035 value. Instead, the float literal is represented as
7036 36028797018963968.0, which is the closest number that can be
7037 represented exactly as a float value. See Representation of
7038 Floating Point Numbers for additional information.
7039 Allowed in guard tests.
7041 self() -> pid()
7043 Returns the process identifier of the calling process, for exam‐
7045 ple:
7046 > self().
7048 <0.26.0>
7049 Allowed in guard tests.
7051 erlang:send(Dest, Msg) -> Msg
7053 Types:
7055 Dest = send_destination()
7057 Msg = term()
7058 Sends a message and returns Msg. This is the same as using the
7060 send operator: Dest ! Msg.
7061 Dest can be a remote or local process identifier, an alias, a
7063 (local) port, a locally registered name, or a tuple {RegName,
7064 Node} for a registered name at another node.
7065 The function fails with a badarg run-time error if Dest is an
7067 atom name, but this name is not registered. This is the only
7068 case when send fails for an unreachable destination Dest (of
7069 correct type).
7070 Note:
7072 For some important information about distributed signals, see
7073 the Blocking Signaling Over Distribution section in the Pro‐
7074 cesses chapter of the Erlang Reference Manual .
7075 erlang:send(Dest, Msg, Options) -> Res
7078 Types:
7080 Dest = send_destination()
7082 Msg = term()
7083 Options = [nosuspend | noconnect]
7084 Res = ok | nosuspend | noconnect
7085 Either sends a message and returns ok, or does not send the mes‐
7087 sage but returns something else (see below). Otherwise the same
7088 as erlang:send/2. For more detailed explanation and warnings,
7089 see erlang:send_nosuspend/2,3.
7090 Options:
7092 nosuspend:
7094 If the sender would have to be suspended to do the send, no‐
7095 suspend is returned instead.
7096 noconnect:
7098 If the destination node would have to be auto-connected to
7099 do the send, noconnect is returned instead.
7100 Note:
7102 For some important information about distributed signals, see
7103 the Blocking Signaling Over Distribution section in the Pro‐
7104 cesses chapter of the Erlang Reference Manual .
7105 Warning:
7108 As with erlang:send_nosuspend/2,3: use with extreme care.
7109 erlang:send_after(Time, Dest, Msg) -> TimerRef
7112 Types:
7114 Time = integer() >= 0
7116 Dest = pid() | atom()
7117 Msg = term()
7118 TimerRef = reference()
7119 Starts a timer. The same as calling erlang:send_after(Time,
7121 Dest, Msg, []).
7122 erlang:send_after(Time, Dest, Msg, Options) -> TimerRef
7124 Types:
7126 Time = integer()
7128 Dest = pid() | atom()
7129 Msg = term()
7130 Options = [Option]
7131 Abs = boolean()
7132 Option = {abs, Abs}
7133 TimerRef = reference()
7134 Starts a timer. When the timer expires, the message Msg is sent
7136 to the process identified by Dest. Apart from the format of the
7137 time-out message, this function works exactly as er‐
7138 lang:start_timer/4.
7139 erlang:send_nosuspend(Dest, Msg) -> boolean()
7141 Types:
7143 Dest = send_destination()
7145 Msg = term()
7146 The same as erlang:send(Dest, Msg, [nosuspend]), but returns
7148 true if the message was sent and false if the message was not
7149 sent because the sender would have had to be suspended.
7150 This function is intended for send operations to an unreliable
7152 remote node without ever blocking the sending (Erlang) process.
7153 If the connection to the remote node (usually not a real Erlang
7154 node, but a node written in C or Java) is overloaded, this func‐
7155 tion does not send the message and returns false.
7156 The same occurs if Dest refers to a local port that is busy. For
7158 all other destinations (allowed for the ordinary send operator
7159 '!'), this function sends the message and returns true.
7160 This function is only to be used in rare circumstances where a
7162 process communicates with Erlang nodes that can disappear with‐
7163 out any trace, causing the TCP buffers and the drivers queue to
7164 be over-full before the node is shut down (because of tick time-
7165 outs) by net_kernel. The normal reaction to take when this oc‐
7166 curs is some kind of premature shutdown of the other node.
7167 Notice that ignoring the return value from this function would
7169 result in an unreliable message passing, which is contradictory
7170 to the Erlang programming model. The message is not sent if this
7171 function returns false.
7172 In many systems, transient states of overloaded queues are nor‐
7174 mal. Although this function returns false does not mean that the
7175 other node is guaranteed to be non-responsive, it could be a
7176 temporary overload. Also, a return value of true does only mean
7177 that the message can be sent on the (TCP) channel without block‐
7178 ing; the message is not guaranteed to arrive at the remote node.
7179 For a disconnected non-responsive node, the return value is true
7180 (mimics the behavior of operator !). The expected behavior and
7181 the actions to take when the function returns false are applica‐
7182 tion- and hardware-specific.
7183 Warning:
7185 Use with extreme care.
7186 erlang:send_nosuspend(Dest, Msg, Options) -> boolean()
7189 Types:
7191 Dest = send_destination()
7193 Msg = term()
7194 Options = [noconnect]
7195 The same as erlang:send(Dest, Msg, [nosuspend | Options]), but
7197 with a Boolean return value.
7198 This function behaves like erlang:send_nosuspend/2, but takes a
7200 third parameter, a list of options. The only option is nocon‐
7201 nect, which makes the function return false if the remote node
7202 is not currently reachable by the local node. The normal behav‐
7203 ior is to try to connect to the node, which can stall the
7204 process during a short period. The use of option noconnect makes
7205 it possible to be sure not to get the slightest delay when send‐
7206 ing to a remote process. This is especially useful when communi‐
7207 cating with nodes that expect to always be the connecting part
7208 (that is, nodes written in C or Java).
7209 Whenever the function returns false (either when a suspend would
7211 occur or when noconnect was specified and the node was not al‐
7212 ready connected), the message is guaranteed not to have been
7213 sent.
7214 Warning:
7216 Use with extreme care.
7217 erlang:set_cookie(Cookie) -> true
7220 Types:
7222 Cookie = atom()
7224 Sets the magic cookie of the local node to the atom Cookie,
7226 which is also the cookie for all nodes that have no explicit
7227 cookie set with set_cookie/2 Cookie (see section Distributed
7228 Erlang in the Erlang Reference Manual in System Documentation).
7229 You can get this value using get_cookie/0.
7231 Failure: function_clause if the local node is not alive.
7233 erlang:set_cookie(Node, Cookie) -> true
7235 Types:
7237 Node = node()
7239 Cookie = atom()
7240 Sets the magic cookie for Node to the atom Cookie. If Node is
7242 the local node, the function sets the cookie of all other nodes
7243 (that have no explicit cookie set with this function) to Cookie
7244 (see section Distributed Erlang in the Erlang Reference Manual
7245 in System Documentation).
7246 You can get this value using get_cookie/1.
7248 Failure: function_clause if the local node is not alive.
7250 setelement(Index, Tuple1, Value) -> Tuple2
7252 Types:
7254 Index = integer() >= 1
7256 1..tuple_size(Tuple1)
7257 Tuple1 = Tuple2 = tuple()
7258 Value = term()
7259 Returns a tuple that is a copy of argument Tuple1 with the ele‐
7261 ment specified by integer argument Index (the first element is
7262 the element with index 1) replaced by argument Value, for exam‐
7263 ple:
7264 > setelement(2, {10, green, bottles}, red).
7266 {10,red,bottles}
7267 size(Item) -> integer() >= 0
7269 Types:
7271 Item = tuple() | binary()
7273 Returns the number of elements in a tuple or the number of bytes
7275 in a binary or bitstring, for example:
7276 > size({morni, mulle, bwange}).
7278 3
7279 > size(<<11, 22, 33>>).
7280 3
7281 For bitstrings, the number of whole bytes is returned. That is,
7283 if the number of bits in the bitstring is not divisible by 8,
7284 the resulting number of bytes is rounded down.
7285 Allowed in guard tests.
7287 See also tuple_size/1, byte_size/1, and bit_size/1.
7289 spawn(Fun) -> pid()
7291 Types:
7293 Fun = function()
7295 Returns the process identifier of a new process started by the
7297 application of Fun to the empty list []. Otherwise works like
7298 spawn/3.
7299 spawn(Node, Fun) -> pid()
7301 Types:
7303 Node = node()
7305 Fun = function()
7306 Returns the process identifier of a new process started by the
7308 application of Fun to the empty list [] on Node. If Node does
7309 not exist, a useless pid is returned. Otherwise works like
7310 spawn/3.
7311 spawn(Module, Function, Args) -> pid()
7313 Types:
7315 Module = module()
7317 Function = atom()
7318 Args = [term()]
7319 Returns the process identifier of a new process started by the
7321 application of Module:Function to Args.
7322 error_handler:undefined_function(Module, Function, Args) is
7324 evaluated by the new process if Module:Function/Arity does not
7325 exist (where Arity is the length of Args). The error handler can
7326 be redefined (see process_flag/2). If error_handler is unde‐
7327 fined, or the user has redefined the default error_handler and
7328 its replacement is undefined, a failure with reason undef oc‐
7329 curs.
7330 Example:
7332 > spawn(speed, regulator, [high_speed, thin_cut]).
7334 <0.13.1>
7335 spawn(Node, Module, Function, Args) -> pid()
7337 Types:
7339 Node = node()
7341 Module = module()
7342 Function = atom()
7343 Args = [term()]
7344 Returns the process identifier (pid) of a new process started by
7346 the application of Module:Function to Args on Node. If Node does
7347 not exist, a useless pid is returned. Otherwise works like
7348 spawn/3.
7349 spawn_link(Fun) -> pid()
7351 Types:
7353 Fun = function()
7355 Returns the process identifier of a new process started by the
7357 application of Fun to the empty list []. A link is created be‐
7358 tween the calling process and the new process, atomically. Oth‐
7359 erwise works like spawn/3.
7360 spawn_link(Node, Fun) -> pid()
7362 Types:
7364 Node = node()
7366 Fun = function()
7367 Returns the process identifier (pid) of a new process started by
7369 the application of Fun to the empty list [] on Node. A link is
7370 created between the calling process and the new process, atomi‐
7371 cally. If Node does not exist, a useless pid is returned and an
7372 exit signal with reason noconnection is sent to the calling
7373 process. Otherwise works like spawn/3.
7374 spawn_link(Module, Function, Args) -> pid()
7376 Types:
7378 Module = module()
7380 Function = atom()
7381 Args = [term()]
7382 Returns the process identifier of a new process started by the
7384 application of Module:Function to Args. A link is created be‐
7385 tween the calling process and the new process, atomically. Oth‐
7386 erwise works like spawn/3.
7387 spawn_link(Node, Module, Function, Args) -> pid()
7389 Types:
7391 Node = node()
7393 Module = module()
7394 Function = atom()
7395 Args = [term()]
7396 Returns the process identifier (pid) of a new process started by
7398 the application of Module:Function to Args on Node. A link is
7399 created between the calling process and the new process, atomi‐
7400 cally. If Node does not exist, a useless pid is returned and an
7401 exit signal with reason noconnection is sent to the calling
7402 process. Otherwise works like spawn/3.
7403 spawn_monitor(Fun) -> {pid(), reference()}
7405 Types:
7407 Fun = function()
7409 Returns the process identifier of a new process, started by the
7411 application of Fun to the empty list [], and a reference for a
7412 monitor created to the new process. Otherwise works like
7413 spawn/3.
7414 spawn_monitor(Node, Fun) -> {pid(), reference()}
7416 Types:
7418 Node = node()
7420 Fun = function()
7421 Returns the process identifier of a new process, started by the
7423 application of Fun to the empty list [] on the node Node, and a
7424 reference for a monitor created to the new process. Otherwise
7425 works like spawn/3.
7426 If the node identified by Node does not support distributed
7428 spawn_monitor(), the call will fail with a notsup exception.
7429 spawn_monitor(Module, Function, Args) -> {pid(), reference()}
7431 Types:
7433 Module = module()
7435 Function = atom()
7436 Args = [term()]
7437 A new process is started by the application of Module:Function
7439 to Args. The process is monitored at the same time. Returns the
7440 process identifier and a reference for the monitor. Otherwise
7441 works like spawn/3.
7442 spawn_monitor(Node, Module, Function, Args) ->
7444 {pid(), reference()}
7445 Types:
7447 Node = node()
7449 Module = module()
7450 Function = atom()
7451 Args = [term()]
7452 A new process is started by the application of Module:Function
7454 to Args on the node Node. The process is monitored at the same
7455 time. Returns the process identifier and a reference for the
7456 monitor. Otherwise works like spawn/3.
7457 If the node identified by Node does not support distributed
7459 spawn_monitor(), the call will fail with a notsup exception.
7460 spawn_opt(Fun, Options) -> pid() | {pid(), reference()}
7462 Types:
7464 Fun = function()
7466 Options = [spawn_opt_option()]
7467 priority_level() = low | normal | high | max
7468 max_heap_size() =
7469 integer() >= 0 |
7470 #{size => integer() >= 0,
7471 kill => boolean(),
7472 error_logger => boolean(),
7473 include_shared_binaries => boolean()}
7474 message_queue_data() = off_heap | on_heap
7475 spawn_opt_option() =
7476 link | monitor |
7477 {monitor, MonitorOpts :: [monitor_option()]} |
7478 {priority, Level :: priority_level()} |
7479 {fullsweep_after, Number :: integer() >= 0} |
7480 {min_heap_size, Size :: integer() >= 0} |
7481 {min_bin_vheap_size, VSize :: integer() >= 0} |
7482 {max_heap_size, Size :: max_heap_size()} |
7483 {message_queue_data, MQD :: message_queue_data()} |
7484 {async_dist, Enabled :: boolean()}
7485 Returns the process identifier (pid) of a new process started by
7487 the application of Fun to the empty list []. Otherwise works
7488 like spawn_opt/4.
7489 If option monitor is specified, the newly created process is
7491 monitored, and both the pid and reference for the monitor are
7492 returned.
7493 spawn_opt(Node, Fun, Options) -> pid() | {pid(), reference()}
7495 Types:
7497 Node = node()
7499 Fun = function()
7500 Options =
7501 [monitor | {monitor, [monitor_option()]} | link | Oth‐
7502 erOption]
7503 OtherOption = term()
7504 Returns the process identifier (pid) of a new process started by
7506 the application of Fun to the empty list [] on Node. If Node
7507 does not exist, a useless pid is returned. Otherwise works like
7508 spawn_opt/4.
7509 Valid options depends on what options are supported by the node
7511 identified by Node. A description of valid Options for the local
7512 node of current OTP version can be found in the documentation of
7513 spawn_opt/4.
7514 spawn_opt(Module, Function, Args, Options) ->
7516 Pid | {Pid, MonitorRef}
7517 Types:
7519 Module = module()
7521 Function = atom()
7522 Args = [term()]
7523 Options = [spawn_opt_option()]
7524 Pid = pid()
7525 MonitorRef = reference()
7526 priority_level() = low | normal | high | max
7527 max_heap_size() =
7528 integer() >= 0 |
7529 #{size => integer() >= 0,
7530 kill => boolean(),
7531 error_logger => boolean(),
7532 include_shared_binaries => boolean()}
7533 message_queue_data() = off_heap | on_heap
7534 spawn_opt_option() =
7535 link | monitor |
7536 {monitor, MonitorOpts :: [monitor_option()]} |
7537 {priority, Level :: priority_level()} |
7538 {fullsweep_after, Number :: integer() >= 0} |
7539 {min_heap_size, Size :: integer() >= 0} |
7540 {min_bin_vheap_size, VSize :: integer() >= 0} |
7541 {max_heap_size, Size :: max_heap_size()} |
7542 {message_queue_data, MQD :: message_queue_data()} |
7543 {async_dist, Enabled :: boolean()}
7544 Works as spawn/3, except that an extra option list is specified
7546 when creating the process.
7547 If option monitor is specified, the newly created process is
7549 monitored, and both the pid and reference for the monitor are
7550 returned.
7551 Options:
7553 link:
7555 Sets a link to the parent process (like spawn_link/3 does).
7556 monitor:
7558 Monitors the new process (like monitor(process, Pid) does).
7559 A {Pid, MonitorRef} tuple will be returned instead of just a
7560 Pid.
7561 {monitor, MonitorOpts}:
7563 Monitors the new process with options (like monitor(process,
7564 Pid, MonitorOpts) does). A {Pid, MonitorRef} tuple will be
7565 returned instead of just a Pid.
7566 {priority, Level}:
7568 Sets the priority of the new process. Equivalent to execut‐
7569 ing process_flag(priority, Level) in the start function of
7570 the new process, except that the priority is set before the
7571 process is selected for execution for the first time. For
7572 more information on priorities, see process_flag(priority,
7573 Level).
7574 {fullsweep_after, Number}:
7576 Useful only for performance tuning. Do not use this option
7577 unless you know that there is problem with execution times
7578 or memory consumption, and ensure that the option improves
7579 matters.
7580 The Erlang runtime system uses a generational garbage col‐
7582 lection scheme, using an "old heap" for data that has sur‐
7583 vived at least one garbage collection. When there is no more
7584 room on the old heap, a fullsweep garbage collection is
7585 done.
7586 Option fullsweep_after makes it possible to specify the max‐
7588 imum number of generational collections before forcing a
7589 fullsweep, even if there is room on the old heap. Setting
7590 the number to zero disables the general collection algo‐
7591 rithm, that is, all live data is copied at every garbage
7592 collection.
7593 A few cases when it can be useful to change fullsweep_after:
7595 * If binaries that are no longer used are to be thrown away
7597 as soon as possible. (Set Number to zero.)
7598 * A process that mostly have short-lived data is fullsweeped
7600 seldom or never, that is, the old heap contains mostly
7601 garbage. To ensure a fullsweep occasionally, set Number to
7602 a suitable value, such as 10 or 20.
7603 * In embedded systems with a limited amount of RAM and no
7605 virtual memory, you might want to preserve memory by set‐
7606 ting Number to zero. (The value can be set globally, see
7607 erlang:system_flag/2.)
7608 {min_heap_size, Size}:
7610 Useful only for performance tuning. Do not use this option
7611 unless you know that there is problem with execution times
7612 or memory consumption, and ensure that the option improves
7613 matters.
7614 Gives a minimum heap size, in words. Setting this value
7616 higher than the system default can speed up some processes
7617 because less garbage collection is done. However, setting a
7618 too high value can waste memory and slow down the system be‐
7619 cause of worse data locality. Therefore, use this option
7620 only for fine-tuning an application and to measure the exe‐
7621 cution time with various Size values.
7622 {min_bin_vheap_size, VSize}:
7624 Useful only for performance tuning. Do not use this option
7625 unless you know that there is problem with execution times
7626 or memory consumption, and ensure that the option improves
7627 matters.
7628 Gives a minimum binary virtual heap size, in words. Setting
7630 this value higher than the system default can speed up some
7631 processes because less garbage collection is done. However,
7632 setting a too high value can waste memory. Therefore, use
7633 this option only for fine-tuning an application and to mea‐
7634 sure the execution time with various VSize values.
7635 {max_heap_size, Size}:
7637 Sets the max_heap_size process flag. The default
7638 max_heap_size is determined by command-line argument +hmax
7639 in erl(1). For more information, see the documentation of
7640 process_flag(max_heap_size, Size).
7641 {message_queue_data, MQD}:
7643 Sets the value of the message_queue_data process flag. MQD
7644 can be either off_heap or on_heap. The default value of the
7645 message_queue_data process flag is determined by the com‐
7646 mand-line argument +hmqd in erl(1). For more information,
7647 see the documentation of process_flag(message_queue_data,
7648 MQD).
7649 {async_dist, Enabled}:
7651 Since: OTP 25.3
7652 Set the async_dist process flag of the spawned process. This
7654 option will override the default value set by the command
7655 line argument +pad <boolean>.
7656 spawn_opt(Node, Module, Function, Args, Options) ->
7658 pid() | {pid(), reference()}
7659 Types:
7661 Node = node()
7663 Module = module()
7664 Function = atom()
7665 Args = [term()]
7666 Options =
7667 [monitor | {monitor, [monitor_option()]} | link | Oth‐
7668 erOption]
7669 OtherOption = term()
7670 Returns the process identifier (pid) of a new process started by
7672 the application of Module:Function to Args on Node. If Node does
7673 not exist, a useless pid is returned. Otherwise works like
7674 spawn_opt/4.
7675 Valid options depends on what options are supported by the node
7677 identified by Node. A description of valid Options for the local
7678 node of current OTP version can be found in the documentation of
7679 spawn_opt/4.
7680 spawn_request(Fun) -> ReqId
7682 Types:
7684 Fun = function()
7686 ReqId = reference()
7687 The same as the call spawn_request(node(),Fun,[]). That is, a
7689 spawn request on the local node with no options.
7690 spawn_request(Fun, Options) -> ReqId
7692 Types:
7694 Fun = function()
7696 Option =
7697 {reply_tag, ReplyTag} | {reply, Reply} | spawn_opt_op‐
7698 tion()
7699 ReplyTag = term()
7700 Reply = yes | no | error_only | success_only
7701 Options = [Option]
7702 ReqId = reference()
7703 The same as the call spawn_request(node(),Fun,Options). That is,
7705 a spawn request on the local node.
7706 spawn_request(Node, Fun) -> ReqId
7708 Types:
7710 Node = node()
7712 Fun = function()
7713 ReqId = reference()
7714 The same as the call spawn_request(Node,Fun,[]). That is, a
7716 spawn request with no options.
7717 spawn_request(Node, Fun, Options) -> ReqId
7719 Types:
7721 Node = node()
7723 Fun = function()
7724 Options = [Option]
7725 Option =
7726 monitor |
7727 {monitor, [monitor_option()]} |
7728 link |
7729 {reply_tag, ReplyTag} |
7730 {reply, Reply} |
7731 OtherOption
7732 ReplyTag = term()
7733 Reply = yes | no | error_only | success_only
7734 OtherOption = term()
7735 ReqId = reference()
7736 The same as spawn_request(Node,erlang,apply,[Fun,[]],Options).
7738 That is, a spawn request using the fun Fun of arity zero as en‐
7739 try point.
7740 This function will fail with a badarg exception if:
7742 * Node is not an atom.
7744 * Fun is not a fun of arity zero.
7746 * Options is not a proper list of terms.
7748 spawn_request(Module, Function, Args) -> ReqId
7750 Types:
7752 Module = module()
7754 Function = atom()
7755 Args = [term()]
7756 ReqId = reference()
7757 The same as the call spawn_request(node(),Module,Func‐
7759 tion,Args,[]). That is, a spawn request on the local node with
7760 no options.
7761 spawn_request(Node, Module, Function, Args) -> ReqId
7763 Types:
7765 Node = node()
7767 Module = module()
7768 Function = atom()
7769 Args = [term()]
7770 ReqId = reference()
7771 The same as the call spawn_request(Node,Module,Func‐
7773 tion,Args,[]). That is, a spawn request with no options.
7774 spawn_request(Module, Function, Args, Options) -> ReqId
7776 Types:
7778 Module = module()
7780 Function = atom()
7781 Args = [term()]
7782 Option =
7783 {reply_tag, ReplyTag} | {reply, Reply} | spawn_opt_op‐
7784 tion()
7785 ReplyTag = term()
7786 Reply = yes | no | error_only | success_only
7787 Options = [Option]
7788 ReqId = reference()
7789 The same as the call spawn_request(node(),Module,Func‐
7791 tion,Args,Options). That is, a spawn request on the local node.
7792 spawn_request(Node, Module, Function, Args, Options) -> ReqId
7794 Types:
7796 Node = node()
7798 Module = module()
7799 Function = atom()
7800 Args = [term()]
7801 Options = [Option]
7802 Option =
7803 monitor |
7804 {monitor, [monitor_option()]} |
7805 link |
7806 {reply_tag, ReplyTag} |
7807 {reply, Reply} |
7808 OtherOption
7809 ReplyTag = term()
7810 Reply = yes | no | error_only | success_only
7811 OtherOption = term()
7812 ReqId = reference()
7813 Asynchronously send a spawn request. Returns a request identi‐
7815 fier ReqId.
7816 If the spawn operation succeeds, a new process is created on the
7818 node identified by Node. When a spawn operation succeeds, the
7819 caller will by default be sent a message on the form {ReplyTag,
7820 ReqId, ok, Pid} where Pid is the process identifier of the newly
7821 created process. Such a message is referred to as a success mes‐
7822 sage below in the text. ReplyTag is by default the atom
7823 spawn_reply unless modified by the {reply_tag, ReplyTag} option.
7824 The new process is started by the application of Module:Function
7825 to Args.
7826 The spawn operation fails either if creation of a new process
7828 failed or if the spawn operation was interrupted by a connection
7829 failure. When a spawn operation fails, the caller will by de‐
7830 fault be sent a message on the form {ReplyTag, ReqId, error,
7831 Reason} where Reason is the error reason. Such a message is re‐
7832 ferred to as an error message below in the text. Currently the
7833 following spawn error Reasons are defined, but other reasons can
7834 appear at any time without prior notice:
7835 badopt:
7837 An invalid Option was passed as argument. Note that differ‐
7838 ent runtime systems may support different options.
7839 notsup:
7841 The node identified by Node does not support spawn opera‐
7842 tions issued by spawn_request().
7843 noconnection:
7845 Failure to set up a connection to the node identified by
7846 Node or the connection to that node was lost during the
7847 spawn operation. In the case the connection was lost, a
7848 process may or may not have been created.
7849 system_limit:
7851 Could not create a new process due to that some system limit
7852 was reached. Typically the process table was full.
7853 Valid Options:
7855 monitor:
7857 In the absence of spawn operation failures, atomically sets
7858 up a monitor to the newly created process. That is, as if
7859 the calling process had called monitor(process, Pid) where
7860 Pid is the process identifier of the newly created process.
7861 The ReqId returned by spawn_request() is also used as moni‐
7862 tor reference as if it was returned from monitor(process,
7863 Pid).
7864 The monitor will not be activated for the calling process
7866 until the spawn operation has succeeded. The monitor can not
7867 be demonitored before the operation has succeeded. A 'DOWN'
7868 message for the corresponding monitor is guaranteed not to
7869 be delivered before a success message that corresponds to
7870 the spawn operation. If the spawn operation fails, no 'DOWN'
7871 message will be delivered.
7872 If the connection between the nodes involved in the spawn
7874 operation is lost during the spawn operation, the spawn op‐
7875 eration will fail with an error reason of noconnection. A
7876 new process may or may not have been created.
7877 {monitor, MonitorOpts}:
7879 In the absence of spawn operation failures, atomically sets
7880 up a monitor to the newly created process. That is, as if
7881 the calling process had called monitor(process, Pid, Moni‐
7882 torOpts) where Pid is the process identifier of the newly
7883 created process. See the monitor option above for more in‐
7884 formation.
7885 Note that the monitor will not be activated for the calling
7887 process until the spawn operation has succeeded. For exam‐
7888 ple, in the case that an alias is created using the monitor
7889 option, the alias will not be active until the monitor is
7890 activated.
7891 link:
7893 In absence of spawn operation failures, atomically sets up a
7894 link between the calling process and the newly created
7895 process. That is, as if the calling process had called
7896 link(Pid) where Pid is the process identifier of the newly
7897 created process.
7898 The link will not be activated for the calling process until
7900 the spawn operation has succeeded. The link can not be re‐
7901 moved before the operation has succeeded. An exit signal due
7902 to the link is guaranteed not to be delivered before a suc‐
7903 cess message that corresponds to the spawn operation. If
7904 the spawn operation fails, no exit signal due to the link
7905 will be delivered to the caller of spawn_request().
7906 If the connection between the nodes involved in the spawn
7908 operation is lost during the spawn operation, the spawn op‐
7909 eration will fail with an error reason of noconnection. A
7910 new process may or may not have been created. If it has been
7911 created, it will be delivered an exit signal with an exit
7912 reason of noconnection.
7913 {reply, Reply}:
7915 Valid Reply values:
7916 yes:
7918 A spawn reply message will be sent to the caller regard‐
7919 less of whether the operation succeeds or not. If the call
7920 to spawn_request() returns without raising an exception
7921 and the reply option is set to yes, the caller is guaran‐
7922 teed to be delivered either a success message or an error
7923 message . The reply option is by default set to yes.
7924 no:
7926 No spawn reply message will be sent to the caller when the
7927 spawn operation completes. This regardless of whether the
7928 operation succeeds or not.
7929 error_only:
7931 No spawn reply message will be sent to the caller if the
7932 spawn operation succeeds, but an error message will be
7933 sent to the caller if the operation fails.
7934 success_only:
7936 No spawn reply message will be sent to the caller if the
7937 spawn operation fails, but a success message will be sent
7938 to the caller if the operation succeeds.
7939 {reply_tag, ReplyTag}:
7941 Sets the reply tag to ReplyTag in the reply message. That
7942 is, in the success or error message that is sent to the
7943 caller due to the spawn operation. The default reply tag is
7944 the atom spawn_reply.
7945 OtherOption:
7947 Other valid options depends on what options are supported by
7948 the node identified by Node. A description of other valid
7949 Options for the local node of current OTP version can be
7950 found in the documentation of spawn_opt/4.
7951 If a spawn reply message is delivered, it is guaranteed to be
7953 delivered before any other signals from the newly spawned
7954 process are delivered to the process issuing the spawn request.
7955 This function will fail with a badarg exception if:
7957 * Node is not an atom.
7959 * Module is not an atom.
7961 * Function is not an atom.
7963 * Args is not a proper list of terms.
7965 * Options is not a proper list of terms.
7967 Note that not all individual Options are checked when the spawn
7969 request is sent. Some Options can only be checked on reception
7970 of the request. Therefore an invalid option does not cause a
7971 badarg exception, but will cause the spawn operation to fail
7972 with an error reason of badopt.
7973 A spawn request can be abandoned by calling spawn_request_aban‐
7975 don/1.
7976 Note:
7978 For some important information about distributed signals, see
7979 the Blocking Signaling Over Distribution section in the Pro‐
7980 cesses chapter of the Erlang Reference Manual .
7981 spawn_request_abandon(ReqId :: reference()) -> boolean()
7984 Abandon a previously issued spawn request. ReqId corresponds to
7986 a request identifier previously returned by spawn_request() in a
7987 call from current process. That is, only the process that has
7988 made the request can abandon the request.
7989 A spawn request can only be successfully abandoned until the
7991 spawn request has completed. When a spawn request has been suc‐
7992 cessfully abandoned, the caller will not be effected by future
7993 direct effects of the spawn request itself. For example, it will
7994 not receive a spawn reply message. The request is however not
7995 withdrawn, so a new process may or may not be created due to the
7996 request. If a new process is created after the spawn request was
7997 abandoned, no monitors nor links will be set up to the caller of
7998 spawn_request_abandon/1 due to the spawn request. If the spawn
7999 request included the link option, the process created due to
8000 this request will be sent an exit signal from its parent with
8001 the exit reason abandoned when it is detected that the spawn op‐
8002 eration has succeeded.
8003 Note:
8005 A process created due to a spawn request that has been abandoned
8006 may communicate with its parent as any other process. It is only
8007 the direct effects on the parent of the actual spawn request,
8008 that will be canceled by abandoning a spawn request.
8009 Return values:
8012 true:
8014 The spawn request was successfully abandoned.
8015 false:
8017 No spawn request was abandoned. The ReqId request identifier
8018 did not correspond to an outstanding spawn request issued by
8019 the calling process. The reason for this is either:
8020 * ReqId corresponds to a spawn request previoulsy made by
8022 the calling process. The spawn operation has completed and
8023 a spawn reply has already been delivered to the calling
8024 process unless the spawn reply was disabled in the re‐
8025 quest.
8026 * ReqId does not correspond to a spawn request that has been
8028 made by the calling process.
8029 This function fail with a badarg exception if ReqId is not a
8031 reference.
8032 split_binary(Bin, Pos) -> {binary(), binary()}
8034 Types:
8036 Bin = binary()
8038 Pos = integer() >= 0
8039 0..byte_size(Bin)
8040 Returns a tuple containing the binaries that are the result of
8042 splitting Bin into two parts at position Pos. This is not a de‐
8043 structive operation. After the operation, there are three bina‐
8044 ries altogether. Example:
8045 > B = list_to_binary("0123456789").
8047 <<"0123456789">>
8048 > byte_size(B).
8049 10
8050 > {B1, B2} = split_binary(B,3).
8051 {<<"012">>,<<"3456789">>}
8052 > byte_size(B1).
8053 3
8054 > byte_size(B2).
8055 7
8056 erlang:start_timer(Time, Dest, Msg) -> TimerRef
8058 Types:
8060 Time = integer() >= 0
8062 Dest = pid() | atom()
8063 Msg = term()
8064 TimerRef = reference()
8065 Starts a timer. The same as calling erlang:start_timer(Time,
8067 Dest, Msg, []).
8068 erlang:start_timer(Time, Dest, Msg, Options) -> TimerRef
8070 Types:
8072 Time = integer()
8074 Dest = pid() | atom()
8075 Msg = term()
8076 Options = [Option]
8077 Abs = boolean()
8078 Option = {abs, Abs}
8079 TimerRef = reference()
8080 Starts a timer. When the timer expires, the message {timeout,
8082 TimerRef, Msg} is sent to the process identified by Dest.
8083 Options:
8085 {abs, false}:
8087 This is the default. It means the Time value is interpreted
8088 as a time in milliseconds relative current Erlang monotonic
8089 time.
8090 {abs, true}:
8092 Absolute Time value. The Time value is interpreted as an ab‐
8093 solute Erlang monotonic time in milliseconds.
8094 More Options can be added in the future.
8096 The absolute point in time, the timer is set to expire on, must
8098 be in the interval [ erlang:convert_time_unit(erlang:sys‐
8099 tem_info(start_time), native, millisecond), erlang:con‐
8100 vert_time_unit(erlang:system_info(end_time), native, millisec‐
8101 ond) ]. If a relative time is specified, the Time value is not
8102 allowed to be negative.
8103 If Dest is a pid(), it must be a pid() of a process created on
8105 the current runtime system instance. This process has either
8106 terminated or not. If Dest is an atom(), it is interpreted as
8107 the name of a locally registered process. The process referred
8108 to by the name is looked up at the time of timer expiration. No
8109 error is returned if the name does not refer to a process.
8110 If Dest is a pid(), the timer is automatically canceled if the
8112 process referred to by the pid() is not alive, or if the process
8113 exits. This feature was introduced in ERTS 5.4.11. Notice that
8114 timers are not automatically canceled when Dest is an atom().
8115 See also erlang:send_after/4, erlang:cancel_timer/2, and er‐
8117 lang:read_timer/2.
8118 Failure: badarg if the arguments do not satisfy the requirements
8120 specified here.
8121 statistics(Item :: active_tasks) -> [ActiveTasks]
8123 Types:
8125 ActiveTasks = integer() >= 0
8127 Returns the same as statistics(active_tasks_all) with the excep‐
8129 tion that no information about the dirty IO run queue and its
8130 associated schedulers is part of the result. That is, only tasks
8131 that are expected to be CPU bound are part of the result.
8132 statistics(Item :: active_tasks_all) -> [ActiveTasks]
8134 Types:
8136 ActiveTasks = integer() >= 0
8138 Returns a list where each element represents the amount of ac‐
8140 tive processes and ports on each run queue and its associated
8141 schedulers. That is, the number of processes and ports that are
8142 ready to run, or are currently running. Values for normal run
8143 queues and their associated schedulers are located first in the
8144 resulting list. The first element corresponds to scheduler num‐
8145 ber 1 and so on. If support for dirty schedulers exist, an ele‐
8146 ment with the value for the dirty CPU run queue and its associ‐
8147 ated dirty CPU schedulers follow and then as last element the
8148 value for the the dirty IO run queue and its associated dirty IO
8149 schedulers follow. The information is not gathered atomically.
8150 That is, the result is not necessarily a consistent snapshot of
8151 the state, but instead quite efficiently gathered.
8152 Note:
8154 Each normal scheduler has one run queue that it manages. If
8155 dirty schedulers schedulers are supported, all dirty CPU sched‐
8156 ulers share one run queue, and all dirty IO schedulers share one
8157 run queue. That is, we have multiple normal run queues, one
8158 dirty CPU run queue and one dirty IO run queue. Work can not mi‐
8159 grate between the different types of run queues. Only work in
8160 normal run queues can migrate to other normal run queues. This
8161 has to be taken into account when evaluating the result.
8162 See also statistics(total_active_tasks), statis‐
8165 tics(run_queue_lengths), statistics(run_queue_lengths_all), sta‐
8166 tistics(total_run_queue_lengths), and statistics(to‐
8167 tal_run_queue_lengths_all).
8168 statistics(Item :: context_switches) -> {ContextSwitches, 0}
8170 Types:
8172 ContextSwitches = integer() >= 0
8174 Returns the total number of context switches since the system
8176 started.
8177 statistics(Item :: exact_reductions) ->
8179 {Total_Exact_Reductions,
8180 Exact_Reductions_Since_Last_Call}
8181 Types:
8183 Total_Exact_Reductions = Exact_Reductions_Since_Last_Call =
8185 integer() >= 0
8186 Returns the number of exact reductions.
8188 Note:
8190 statistics(exact_reductions) is a more expensive operation than
8191 statistics(reductions).
8192 statistics(Item :: garbage_collection) ->
8195 {Number_of_GCs, Words_Reclaimed, 0}
8196 Types:
8198 Number_of_GCs = Words_Reclaimed = integer() >= 0
8200 Returns information about garbage collection, for example:
8202 > statistics(garbage_collection).
8204 {85,23961,0}
8205 This information can be invalid for some implementations.
8207 statistics(Item :: io) -> {{input, Input}, {output, Output}}
8209 Types:
8211 Input = Output = integer() >= 0
8213 Returns Input, which is the total number of bytes received
8215 through ports, and Output, which is the total number of bytes
8216 output to ports.
8217 statistics(Item :: microstate_accounting) ->
8219 [MSAcc_Thread] | undefined
8220 Types:
8222 MSAcc_Thread =
8224 #{type := MSAcc_Thread_Type,
8225 id := MSAcc_Thread_Id,
8226 counters := MSAcc_Counters}
8227 MSAcc_Thread_Type =
8228 async | aux | dirty_io_scheduler | dirty_cpu_scheduler |
8229 poll | scheduler
8230 MSAcc_Thread_Id = integer() >= 0
8231 MSAcc_Counters = #{MSAcc_Thread_State => integer() >= 0}
8232 MSAcc_Thread_State =
8233 alloc | aux | bif | busy_wait | check_io | emulator | ets
8234 |
8235 gc | gc_fullsweep | nif | other | port | send | sleep |
8236 timers
8237 Microstate accounting can be used to measure how much time the
8239 Erlang runtime system spends doing various tasks. It is designed
8240 to be as lightweight as possible, but some overhead exists when
8241 this is enabled. Microstate accounting is meant to be a profil‐
8242 ing tool to help finding performance bottlenecks. To
8243 start/stop/reset microstate accounting, use system flag mi‐
8244 crostate_accounting.
8245 statistics(microstate_accounting) returns a list of maps repre‐
8247 senting some of the OS threads within ERTS. Each map contains
8248 type and id fields that can be used to identify what thread it
8249 is, and also a counters field that contains data about how much
8250 time has been spent in the various states.
8251 Example:
8253 > erlang:statistics(microstate_accounting).
8255 [#{counters => #{aux => 1899182914,
8256 check_io => 2605863602,
8257 emulator => 45731880463,
8258 gc => 1512206910,
8259 other => 5421338456,
8260 port => 221631,
8261 sleep => 5150294100},
8262 id => 1,
8263 type => scheduler}|...]
8264 The time unit is the same as returned by os:perf_counter/0. So,
8266 to convert it to milliseconds, you can do something like this:
8267 lists:map(
8269 fun(#{ counters := Cnt } = M) ->
8270 MsCnt = maps:map(fun(_K, PerfCount) ->
8271 erlang:convert_time_unit(PerfCount, perf_counter, 1000)
8272 end, Cnt),
8273 M#{ counters := MsCnt }
8274 end, erlang:statistics(microstate_accounting)).
8275 Notice that these values are not guaranteed to be the exact time
8277 spent in each state. This is because of various optimisation
8278 done to keep the overhead as small as possible.
8279 MSAcc_Thread_Types:
8281 scheduler:
8283 The main execution threads that do most of the work. See erl
8284 +S for more details.
8285 dirty_cpu_scheduler:
8287 The threads for long running cpu intensive work. See erl
8288 +SDcpu for more details.
8289 dirty_io_scheduler:
8291 The threads for long running I/O work. See erl +SDio for
8292 more details.
8293 async:
8295 Async threads are used by various linked-in drivers (mainly
8296 the file drivers) do offload non-CPU intensive work. See erl
8297 +A for more details.
8298 aux:
8300 Takes care of any work that is not specifically assigned to
8301 a scheduler.
8302 poll:
8304 Does the IO polling for the emulator. See erl +IOt for more
8305 details.
8306 The following MSAcc_Thread_States are available. All states are
8308 exclusive, meaning that a thread cannot be in two states at
8309 once. So, if you add the numbers of all counters in a thread,
8310 you get the total runtime for that thread.
8311 aux:
8313 Time spent handling auxiliary jobs.
8314 check_io:
8316 Time spent checking for new I/O events.
8317 emulator:
8319 Time spent executing Erlang processes.
8320 gc:
8322 Time spent doing garbage collection. When extra states are
8323 enabled this is the time spent doing non-fullsweep garbage
8324 collections.
8325 other:
8327 Time spent doing unaccounted things.
8328 port:
8330 Time spent executing ports.
8331 sleep:
8333 Time spent sleeping.
8334 More fine-grained MSAcc_Thread_States can be added through con‐
8336 figure (such as ./configure --with-microstate-accounting=extra).
8337 Enabling these states causes performance degradation when mi‐
8338 crostate accounting is turned off and increases the overhead
8339 when it is turned on.
8340 alloc:
8342 Time spent managing memory. Without extra states this time
8343 is spread out over all other states.
8344 bif:
8346 Time spent in BIFs. Without extra states this time is part
8347 of the emulator state.
8348 busy_wait:
8350 Time spent busy waiting. This is also the state where a
8351 scheduler no longer reports that it is active when using
8352 statistics(scheduler_wall_time). So, if you add all other
8353 states but this and sleep, and then divide that by all time
8354 in the thread, you should get something very similar to the
8355 scheduler_wall_time fraction. Without extra states this time
8356 is part of the other state.
8357 ets:
8359 Time spent executing ETS BIFs. Without extra states this
8360 time is part of the emulator state.
8361 gc_full:
8363 Time spent doing fullsweep garbage collection. Without extra
8364 states this time is part of the gc state.
8365 nif:
8367 Time spent in NIFs. Without extra states this time is part
8368 of the emulator state.
8369 send:
8371 Time spent sending messages (processes only). Without extra
8372 states this time is part of the emulator state.
8373 timers:
8375 Time spent managing timers. Without extra states this time
8376 is part of the other state.
8377 The utility module msacc(3) can be used to more easily analyse
8379 these statistics.
8380 Returns undefined if system flag microstate_accounting is turned
8382 off.
8383 The list of thread information is unsorted and can appear in
8385 different order between calls.
8386 Note:
8388 The threads and states are subject to change without any prior
8389 notice.
8390 statistics(Item :: reductions) ->
8393 {Total_Reductions, Reductions_Since_Last_Call}
8394 Types:
8396 Total_Reductions = Reductions_Since_Last_Call = integer() >=
8398 0
8399 Returns information about reductions, for example:
8401 > statistics(reductions).
8403 {2046,11}
8404 Change:
8406 As from ERTS 5.5 (Erlang/OTP R11B), this value does not include
8407 reductions performed in current time slices of currently sched‐
8408 uled processes. If an exact value is wanted, use statistics(ex‐
8409 act_reductions).
8410 statistics(Item :: run_queue) -> integer() >= 0
8413 Returns the total length of all normal and dirty CPU run queues.
8415 That is, queued work that is expected to be CPU bound. The in‐
8416 formation is gathered atomically. That is, the result is a con‐
8417 sistent snapshot of the state, but this operation is much more
8418 expensive compared to statistics(total_run_queue_lengths), espe‐
8419 cially when a large amount of schedulers is used.
8420 statistics(Item :: run_queue_lengths) -> [RunQueueLength]
8422 Types:
8424 RunQueueLength = integer() >= 0
8426 Returns the same as statistics(run_queue_lengths_all) with the
8428 exception that no information about the dirty IO run queue is
8429 part of the result. That is, only run queues with work that is
8430 expected to be CPU bound is part of the result.
8431 statistics(Item :: run_queue_lengths_all) -> [RunQueueLength]
8433 Types:
8435 RunQueueLength = integer() >= 0
8437 Returns a list where each element represents the amount of pro‐
8439 cesses and ports ready to run for each run queue. Values for
8440 normal run queues are located first in the resulting list. The
8441 first element corresponds to the normal run queue of scheduler
8442 number 1 and so on. If support for dirty schedulers exist, val‐
8443 ues for the dirty CPU run queue and the dirty IO run queue fol‐
8444 low (in that order) at the end. The information is not gathered
8445 atomically. That is, the result is not necessarily a consistent
8446 snapshot of the state, but instead quite efficiently gathered.
8447 Note:
8449 Each normal scheduler has one run queue that it manages. If
8450 dirty schedulers schedulers are supported, all dirty CPU sched‐
8451 ulers share one run queue, and all dirty IO schedulers share one
8452 run queue. That is, we have multiple normal run queues, one
8453 dirty CPU run queue and one dirty IO run queue. Work can not mi‐
8454 grate between the different types of run queues. Only work in
8455 normal run queues can migrate to other normal run queues. This
8456 has to be taken into account when evaluating the result.
8457 See also statistics(run_queue_lengths), statistics(to‐
8460 tal_run_queue_lengths_all), statistics(total_run_queue_lengths),
8461 statistics(active_tasks), statistics(active_tasks_all), and sta‐
8462 tistics(total_active_tasks), statistics(total_active_tasks_all).
8463 statistics(Item :: runtime) ->
8465 {Total_Run_Time, Time_Since_Last_Call}
8466 Types:
8468 Total_Run_Time = Time_Since_Last_Call = integer() >= 0
8470 Returns information about runtime, in milliseconds.
8472 This is the sum of the runtime for all threads in the Erlang
8474 runtime system and can therefore be greater than the wall clock
8475 time.
8476 Warning:
8478 This value might wrap due to limitations in the underlying func‐
8479 tionality provided by the operating system that is used.
8480 Example:
8483 > statistics(runtime).
8485 {1690,1620}
8486 statistics(Item :: scheduler_wall_time) ->
8488 [{SchedulerId, ActiveTime, TotalTime}] | undefined
8489 Types:
8491 SchedulerId = integer() >= 1
8493 ActiveTime = TotalTime = integer() >= 0
8494 Returns information describing how much time normal and dirty
8496 CPU schedulers in the system have been busy. This value is nor‐
8497 mally a better indicator of how much load an Erlang node is un‐
8498 der instead of looking at the CPU utilization provided by tools
8499 such as top or sysstat. This is because scheduler_wall_time also
8500 includes time where the scheduler is waiting for some other rea‐
8501 source (such as an internal mutex) to be available but does not
8502 use the CPU. In order to better understand what a scheduler is
8503 busy doing you can use microstate accounting.
8504 The definition of a busy scheduler is when it is not idle and
8506 not busy waiting for new work, that is:
8507 * Executing process code
8509 * Executing linked-in driver or NIF code
8511 * Executing BIFs, or any other runtime handling
8513 * Garbage collecting
8515 * Handling any other memory management
8517 Notice that a scheduler can also be busy even if the OS has
8519 scheduled out the scheduler thread.
8520 Note:
8522 It is recommended to use the module scheduler instead of this
8523 function directly as it provides an easier way to get the infor‐
8524 mation that you usually want.
8525 If enabled this function returns a list of tuples with {Schedu‐
8528 lerId, ActiveTime, TotalTime}, where SchedulerId is an integer
8529 ID of the scheduler, ActiveTime is the duration the scheduler
8530 has been busy, and TotalTime is the total time duration since
8531 scheduler_wall_time activation for the specific scheduler. The
8532 time unit returned is undefined and can be subject to change be‐
8533 tween releases, OSs, and system restarts. scheduler_wall_time is
8534 only to be used to calculate relative values for scheduler uti‐
8535 lization. The ActiveTime can never exceed TotalTime. The list of
8536 scheduler information is unsorted and can appear in different
8537 order between calls.
8538 The disabled this function returns undefined.
8540 The activation time can differ significantly between schedulers.
8542 Currently dirty schedulers are activated at system start while
8543 normal schedulers are activated some time after the sched‐
8544 uler_wall_time functionality is enabled.
8545 Only information about schedulers that are expected to handle
8547 CPU bound work is included in the return values from this func‐
8548 tion. If you also want information about dirty I/O schedulers,
8549 use statistics(scheduler_wall_time_all) instead.
8550 Normal schedulers will have scheduler identifiers in the range 1
8552 =< SchedulerId =< erlang:system_info(schedulers). Dirty CPU
8553 schedulers will have scheduler identifiers in the range er‐
8554 lang:system_info(schedulers) < SchedulerId =< erlang:sys‐
8555 tem_info(schedulers) + erlang:system_info(dirty_cpu_schedulers).
8556 Note:
8558 The different types of schedulers handle specific types of jobs.
8559 Every job is assigned to a specific scheduler type. Jobs can mi‐
8560 grate between different schedulers of the same type, but never
8561 between schedulers of different types. This fact has to be taken
8562 under consideration when evaluating the result returned.
8563 You can use scheduler_wall_time to calculate scheduler utiliza‐
8566 tion. First you take a sample of the values returned by er‐
8567 lang:statistics(scheduler_wall_time).
8568 > erlang:system_flag(scheduler_wall_time, true).
8570 false
8571 > Ts0 = lists:sort(erlang:statistics(scheduler_wall_time)), ok.
8572 ok
8573 Some time later the user takes another snapshot and calculates
8575 scheduler utilization per scheduler, for example:
8576 > Ts1 = lists:sort(erlang:statistics(scheduler_wall_time)), ok.
8578 ok
8579 > lists:map(fun({{I, A0, T0}, {I, A1, T1}}) -> {I, (A1 - A0)/(T1 - T0)} end, lists:zip(Ts0,Ts1)).
8580 [{1,0.9743474730177548},
8581 {2,0.9744843782751444},
8582 {3,0.9995902361669045},
8583 {4,0.9738012596572161},
8584 {5,0.9717956667018103},
8585 {6,0.9739235846420741},
8586 {7,0.973237033077876},
8587 {8,0.9741297293248656}]
8588 Using the same snapshots to calculate a total scheduler utiliza‐
8590 tion:
8591 > {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.
8593 0.9769136803764825
8594 Total scheduler utilization will equal 1.0 when all schedulers
8596 have been active all the time between the two measurements.
8597 Another (probably more) useful value is to calculate total
8599 scheduler utilization weighted against maximum amount of avail‐
8600 able CPU time:
8601 > WeightedSchedulerUtilization = (TotalSchedulerUtilization * (erlang:system_info(schedulers) + erlang:system_info(dirty_cpu_schedulers))) / erlang:system_info(logical_processors_available).
8603 0.9769136803764825
8604 This weighted scheduler utilization will reach 1.0 when sched‐
8606 ulers are active the same amount of time as maximum available
8607 CPU time. If more schedulers exist than available logical pro‐
8608 cessors, this value may be greater than 1.0.
8609 As of ERTS version 9.0, the Erlang runtime system will as de‐
8611 fault have more schedulers than logical processors. This due to
8612 the dirty schedulers.
8613 Note:
8615 scheduler_wall_time is by default disabled. To enable it, use
8616 erlang:system_flag(scheduler_wall_time, true).
8617 statistics(Item :: scheduler_wall_time_all) ->
8620 [{SchedulerId, ActiveTime, TotalTime}] | undefined
8621 Types:
8623 SchedulerId = integer() >= 1
8625 ActiveTime = TotalTime = integer() >= 0
8626 The same as statistics(scheduler_wall_time), except that it also
8628 include information about all dirty I/O schedulers.
8629 Dirty IO schedulers will have scheduler identifiers in the range
8631 erlang:system_info(schedulers) + erlang:sys‐
8632 tem_info(dirty_cpu_schedulers) < SchedulerId =< erlang:sys‐
8633 tem_info(schedulers) + erlang:system_info(dirty_cpu_schedulers)
8634 + erlang:system_info(dirty_io_schedulers).
8635 Note:
8637 Note that work executing on dirty I/O schedulers are expected to
8638 mainly wait for I/O. That is, when you get high scheduler uti‐
8639 lization on dirty I/O schedulers, CPU utilization is not ex‐
8640 pected to be high due to this work.
8641 statistics(Item :: total_active_tasks) -> ActiveTasks
8644 Types:
8646 ActiveTasks = integer() >= 0
8648 The same as calling lists:sum(statistics(active_tasks)), but
8650 more efficient.
8651 statistics(Item :: total_active_tasks_all) -> ActiveTasks
8653 Types:
8655 ActiveTasks = integer() >= 0
8657 The same as calling lists:sum(statistics(active_tasks_all)), but
8659 more efficient.
8660 statistics(Item :: total_run_queue_lengths) ->
8662 TotalRunQueueLengths
8663 Types:
8665 TotalRunQueueLengths = integer() >= 0
8667 The same as calling lists:sum(statistics(run_queue_lengths)),
8669 but more efficient.
8670 statistics(Item :: total_run_queue_lengths_all) ->
8672 TotalRunQueueLengths
8673 Types:
8675 TotalRunQueueLengths = integer() >= 0
8677 The same as calling lists:sum(statis‐
8679 tics(run_queue_lengths_all)), but more efficient.
8680 statistics(Item :: wall_clock) ->
8682 {Total_Wallclock_Time,
8683 Wallclock_Time_Since_Last_Call}
8684 Types:
8686 Total_Wallclock_Time = Wallclock_Time_Since_Last_Call = inte‐
8688 ger() >= 0
8689 Returns information about wall clock. wall_clock can be used in
8691 the same manner as runtime, except that real time is measured as
8692 opposed to runtime or CPU time.
8693 erlang:suspend_process(Suspendee) -> true
8695 Types:
8697 Suspendee = pid()
8699 Suspends the process identified by Suspendee. The same as call‐
8701 ing erlang:suspend_process(Suspendee, []).
8702 Warning:
8704 This BIF is intended for debugging only.
8705 erlang:suspend_process(Suspendee, OptList) -> boolean()
8708 Types:
8710 Suspendee = pid()
8712 OptList = [Opt]
8713 Opt = unless_suspending | asynchronous | {asynchronous,
8714 term()}
8715 Increases the suspend count on the process identified by Sus‐
8717 pendee and puts it in the suspended state if it is not already
8718 in that state. A suspended process is not scheduled for execu‐
8719 tion until the process has been resumed.
8720 A process can be suspended by multiple processes and can be sus‐
8722 pended multiple times by a single process. A suspended process
8723 does not leave the suspended state until its suspend count
8724 reaches zero. The suspend count of Suspendee is decreased when
8725 erlang:resume_process(Suspendee) is called by the same process
8726 that called erlang:suspend_process(Suspendee). All increased
8727 suspend counts on other processes acquired by a process are au‐
8728 tomatically decreased when the process terminates.
8729 Options (Opts):
8731 asynchronous:
8733 A suspend request is sent to the process identified by Sus‐
8734 pendee. Suspendee eventually suspends unless it is resumed
8735 before it could suspend. The caller of erlang:sus‐
8736 pend_process/2 returns immediately, regardless of whether
8737 Suspendee has suspended yet or not. The point in time when
8738 Suspendee suspends cannot be deduced from other events in
8739 the system. It is only guaranteed that Suspendee eventually
8740 suspends (unless it is resumed). If no asynchronous options
8741 has been passed, the caller of erlang:suspend_process/2 is
8742 blocked until Suspendee has suspended.
8743 {asynchronous, ReplyTag}:
8745 A suspend request is sent to the process identified by Sus‐
8746 pendee. When the suspend request has been processed, a reply
8747 message is sent to the caller of this function. The reply is
8748 on the form {ReplyTag, State} where State is either:
8749 exited:
8751 Suspendee has exited.
8752 suspended:
8754 Suspendee is now suspended.
8755 not_suspended:
8757 Suspendee is not suspended. This can only happen when the
8758 process that issued this request, have called re‐
8759 sume_process(Suspendee) before getting the reply.
8760 Apart from the reply message, the {asynchronous, ReplyTag}
8762 option behaves exactly the same as the asynchronous option
8763 without reply tag.
8764 unless_suspending:
8766 The process identified by Suspendee is suspended unless the
8767 calling process already is suspending Suspendee. If un‐
8768 less_suspending is combined with option asynchronous, a sus‐
8769 pend request is sent unless the calling process already is
8770 suspending Suspendee or if a suspend request already has
8771 been sent and is in transit. If the calling process already
8772 is suspending Suspendee, or if combined with option asyn‐
8773 chronous and a send request already is in transit, false is
8774 returned and the suspend count on Suspendee remains un‐
8775 changed.
8776 If the suspend count on the process identified by Suspendee is
8778 increased, true is returned, otherwise false.
8779 Warning:
8781 This BIF is intended for debugging only.
8782 Warning:
8785 You can easily create deadlocks if processes suspends each other
8786 (directly or in circles). In ERTS versions prior to ERTS version
8787 10.0, the runtime system prevented such deadlocks, but this pre‐
8788 vention has now been removed due to performance reasons.
8789 Failures:
8792 badarg:
8794 If Suspendee is not a process identifier.
8795 badarg:
8797 If the process identified by Suspendee is the same process
8798 as the process calling erlang:suspend_process/2.
8799 badarg:
8801 If the process identified by Suspendee is not alive.
8802 badarg:
8804 If the process identified by Suspendee resides on another
8805 node.
8806 badarg:
8808 If OptList is not a proper list of valid Opts.
8809 system_limit:
8811 If the process identified by Suspendee has been suspended
8812 more times by the calling process than can be represented by
8813 the currently used internal data structures. The system
8814 limit is greater than 2,000,000,000 suspends and will never
8815 be lower.
8816 erlang:system_flag(Flag :: backtrace_depth, Depth) -> OldDepth
8818 Types:
8820 Depth = OldDepth = integer() >= 0
8822 Sets the maximum depth of call stack back-traces in the exit
8824 reason element of 'EXIT' tuples. The flag also limits the stack‐
8825 trace depth returned by process_info item current_stacktrace.
8826 Returns the old value of the flag.
8828 erlang:system_flag(Flag :: cpu_topology, CpuTopology) ->
8830 OldCpuTopology
8831 Types:
8833 CpuTopology = OldCpuTopology = cpu_topology()
8835 cpu_topology() = [LevelEntry :: level_entry()] | undefined
8836 level_entry() =
8837 {LevelTag :: level_tag(), SubLevel :: sub_level()} |
8838 {LevelTag :: level_tag(),
8839 InfoList :: info_list(),
8840 SubLevel :: sub_level()}
8841 level_tag() = core | node | processor | thread
8842 sub_level() =
8843 [LevelEntry :: level_entry()] |
8844 (LogicalCpuId :: {logical, integer() >= 0})
8845 info_list() = []
8846 Warning:
8848 This argument is deprecated. Instead of using this argument, use
8849 command-line argument +sct in erl(1).
8850 When this argument is removed, a final CPU topology to use is
8852 determined at emulator boot time.
8853 Sets the user-defined CpuTopology. The user-defined CPU topology
8856 overrides any automatically detected CPU topology. By passing
8857 undefined as CpuTopology, the system reverts to the CPU topology
8858 automatically detected. The returned value equals the value re‐
8859 turned from erlang:system_info(cpu_topology) before the change
8860 was made.
8861 Returns the old value of the flag.
8863 The CPU topology is used when binding schedulers to logical pro‐
8865 cessors. If schedulers are already bound when the CPU topology
8866 is changed, the schedulers are sent a request to rebind accord‐
8867 ing to the new CPU topology.
8868 The user-defined CPU topology can also be set by passing com‐
8870 mand-line argument +sct to erl(1).
8871 For information on type CpuTopology and more, see erlang:sys‐
8873 tem_info(cpu_topology) as well as command-line flags +sct and
8874 +sbt in erl(1).
8875 erlang:system_flag(Flag :: dirty_cpu_schedulers_online,
8877 DirtyCPUSchedulersOnline) ->
8878 OldDirtyCPUSchedulersOnline
8879 Types:
8881 DirtyCPUSchedulersOnline = OldDirtyCPUSchedulersOnline = in‐
8883 teger() >= 1
8884 Sets the number of dirty CPU schedulers online. Range is 1 <=
8886 DirtyCPUSchedulersOnline <= N, where N is the smallest of the
8887 return values of erlang:system_info(dirty_cpu_schedulers) and
8888 erlang:system_info(schedulers_online).
8889 Returns the old value of the flag.
8891 The number of dirty CPU schedulers online can change if the num‐
8893 ber of schedulers online changes. For example, if 12 schedulers
8894 and 6 dirty CPU schedulers are online, and system_flag/2 is used
8895 to set the number of schedulers online to 6, then the number of
8896 dirty CPU schedulers online is automatically decreased by half
8897 as well, down to 3. Similarly, the number of dirty CPU sched‐
8898 ulers online increases proportionally to increases in the number
8899 of schedulers online.
8900 For more information, see erlang:system_info(dirty_cpu_sched‐
8902 ulers) and erlang:system_info(dirty_cpu_schedulers_online).
8903 erlang:system_flag(Flag :: erts_alloc, Value :: {Alloc, F, V}) ->
8905 ok | notsup
8906 Types:
8908 Alloc = F = atom()
8910 V = integer()
8911 Sets system flags for erts_alloc(3). Alloc is the allocator to
8913 affect, for example binary_alloc. F is the flag to change and V
8914 is the new value.
8915 Only a subset of all erts_alloc flags can be changed at run
8917 time. This subset is currently only the flag sbct.
8918 Returns ok if the flag was set or notsup if not supported by
8920 erts_alloc.
8921 erlang:system_flag(Flag :: fullsweep_after, Number) -> OldNumber
8923 Types:
8925 Number = OldNumber = integer() >= 0
8927 Sets system flag fullsweep_after. Number is a non-negative inte‐
8929 ger indicating how many times generational garbage collections
8930 can be done without forcing a fullsweep collection. The value
8931 applies to new processes, while processes already running are
8932 not affected.
8933 Returns the old value of the flag.
8935 In low-memory systems (especially without virtual memory), set‐
8937 ting the value to 0 can help to conserve memory.
8938 This value can also be set through (OS) environment variable
8940 ERL_FULLSWEEP_AFTER.
8941 erlang:system_flag(Flag :: microstate_accounting, Action) ->
8943 OldState
8944 Types:
8946 Action = true | false | reset
8948 OldState = true | false
8949 Turns on/off microstate accounting measurements. When passing
8951 reset, all counters are reset to 0.
8952 For more information see statistics(microstate_accounting).
8954 erlang:system_flag(Flag :: min_heap_size, MinHeapSize) ->
8956 OldMinHeapSize
8957 Types:
8959 MinHeapSize = OldMinHeapSize = integer() >= 0
8961 Sets the default minimum heap size for processes. The size is
8963 specified in words. The new min_heap_size effects only processes
8964 spawned after the change of min_heap_size has been made.
8965 min_heap_size can be set for individual processes by using
8966 spawn_opt/4 or process_flag/2.
8967 Returns the old value of the flag.
8969 erlang:system_flag(Flag :: min_bin_vheap_size, MinBinVHeapSize) ->
8971 OldMinBinVHeapSize
8972 Types:
8974 MinBinVHeapSize = OldMinBinVHeapSize = integer() >= 0
8976 Sets the default minimum binary virtual heap size for processes.
8978 The size is specified in words. The new min_bin_vhheap_size ef‐
8979 fects only processes spawned after the change of
8980 min_bin_vheap_size has been made. min_bin_vheap_size can be set
8981 for individual processes by using spawn_opt/2,3,4 or
8982 process_flag/2.
8983 Returns the old value of the flag.
8985 erlang:system_flag(Flag :: max_heap_size, MaxHeapSize) ->
8987 OldMaxHeapSize
8988 Types:
8990 MaxHeapSize = OldMaxHeapSize = max_heap_size()
8992 max_heap_size() =
8993 integer() >= 0 |
8994 #{size => integer() >= 0,
8995 kill => boolean(),
8996 error_logger => boolean(),
8997 include_shared_binaries => boolean()}
8998 Sets the default maximum heap size settings for processes. The
9000 size is specified in words. The new max_heap_size effects only
9001 processes spawned after the change has been made. max_heap_size
9002 can be set for individual processes using spawn_opt/2,3,4 or
9003 process_flag/2.
9004 Returns the old value of the flag.
9006 For details on how the heap grows, see Sizing the heap in the
9008 ERTS internal documentation.
9009 erlang:system_flag(Flag :: multi_scheduling, BlockState) ->
9011 OldBlockState
9012 Types:
9014 BlockState = block | unblock | block_normal | unblock_normal
9016 OldBlockState = blocked | disabled | enabled
9017 If multi-scheduling is enabled, more than one scheduler thread
9019 is used by the emulator. Multi-scheduling can be blocked in two
9020 different ways. Either all schedulers but one is blocked, or all
9021 normal schedulers but one is blocked. When only normal sched‐
9022 ulers are blocked, dirty schedulers are free to continue to
9023 schedule processes.
9024 If BlockState =:= block, multi-scheduling is blocked. That is,
9026 one and only one scheduler thread will execute. If BlockState
9027 =:= unblock and no one else blocks multi-scheduling, and this
9028 process has blocked only once, multi-scheduling is unblocked.
9029 If BlockState =:= block_normal, normal multi-scheduling is
9031 blocked. That is, only one normal scheduler thread will execute,
9032 but multiple dirty schedulers can execute. If BlockState =:= un‐
9033 block_normal and no one else blocks normal multi-scheduling, and
9034 this process has blocked only once, normal multi-scheduling is
9035 unblocked.
9036 One process can block multi-scheduling and normal multi-schedul‐
9038 ing multiple times. If a process has blocked multiple times, it
9039 must unblock exactly as many times as it has blocked before it
9040 has released its multi-scheduling block. If a process that has
9041 blocked multi-scheduling or normal multi-scheduling exits, it
9042 automatically releases its blocking of multi-scheduling and nor‐
9043 mal multi-scheduling.
9044 The return values are disabled, blocked, blocked_normal, or en‐
9046 abled. The returned value describes the state just after the
9047 call to erlang:system_flag(multi_scheduling, BlockState) has
9048 been made. For information about the return values, see er‐
9049 lang:system_info(multi_scheduling).
9050 Note:
9052 Blocking of multi-scheduling and normal multi-scheduling is nor‐
9053 mally not needed. If you feel that you need to use these fea‐
9054 tures, consider it a few more times again. Blocking multi-sched‐
9055 uling is only to be used as a last resort, as it is most likely
9056 a very inefficient way to solve the problem.
9057 See also erlang:system_info(multi_scheduling), erlang:sys‐
9060 tem_info(normal_multi_scheduling_blockers), erlang:sys‐
9061 tem_info(multi_scheduling_blockers), and erlang:sys‐
9062 tem_info(schedulers).
9063 erlang:system_flag(Flag :: outstanding_system_requests_limit,
9065 NewLimit) ->
9066 OldLimit
9067 Types:
9069 NewLimit = OldLimit = 1..134217727
9071 Sets a limit on the amount of outstanding requests made by a
9073 system process orchestrating system wide changes. Currently
9074 there are two such processes:
9075 The Code Purger:
9077 The code purger orchestrates checking of references to old
9078 code before old code is removed from the system.
9079 The Literal Area Collector:
9081 The literal area collector orchestrates copying of refer‐
9082 ences from old literal areas before removal of such areas
9083 from the system.
9084 Each of these processes are allowed to have as many outstanding
9086 requests as this limit is set to. By default this limit is set
9087 to twice the amount of schedulers on the system. This will en‐
9088 sure that schedulers will have enough work scheduled to perform
9089 these operations as quickly as possible at the same time as
9090 other work will be interleaved with this work. Currently used
9091 limit can be checked by calling erlang:system_info(outstand‐
9092 ing_system_requests_limit).
9093 This limit can also be set by passing the command line argument
9095 +zosrl <Limit> to erl.
9096 erlang:system_flag(Flag :: scheduler_bind_type, How) ->
9098 OldBindType
9099 Types:
9101 How = scheduler_bind_type() | default_bind
9103 OldBindType = scheduler_bind_type()
9104 scheduler_bind_type() =
9105 no_node_processor_spread | no_node_thread_spread | no_spread |
9106 processor_spread | spread | thread_spread |
9107 thread_no_node_processor_spread | unbound
9108 Warning:
9110 This argument is deprecated. Instead of using this argument, use
9111 command-line argument +sbt in erl(1). When this argument is re‐
9112 moved, a final scheduler bind type to use is determined at emu‐
9113 lator boot time.
9114 Controls if and how schedulers are bound to logical processors.
9117 When erlang:system_flag(scheduler_bind_type, How) is called, an
9119 asynchronous signal is sent to all schedulers online, causing
9120 them to try to bind or unbind as requested.
9121 Note:
9123 If a scheduler fails to bind, this is often silently ignored, as
9124 it is not always possible to verify valid logical processor
9125 identifiers. If an error is reported, an error event is logged.
9126 To verify that the schedulers have bound as requested, call er‐
9127 lang:system_info(scheduler_bindings).
9128 Schedulers can be bound on newer Linux, Solaris, FreeBSD, and
9131 Windows systems, but more systems will be supported in future
9132 releases.
9133 In order for the runtime system to be able to bind schedulers,
9135 the CPU topology must be known. If the runtime system fails to
9136 detect the CPU topology automatically, it can be defined. For
9137 more information on how to define the CPU topology, see command-
9138 line flag +sct in erl(1).
9139 The runtime system does by default not bind schedulers to logi‐
9141 cal processors.
9142 Note:
9144 If the Erlang runtime system is the only OS process binding
9145 threads to logical processors, this improves the performance of
9146 the runtime system. However, if other OS processes (for example,
9147 another Erlang runtime system) also bind threads to logical pro‐
9148 cessors, there can be a performance penalty instead. Sometimes
9149 this performance penalty can be severe. If so, it is recommended
9150 to not bind the schedulers.
9151 Schedulers can be bound in different ways. Argument How deter‐
9154 mines how schedulers are bound and can be any of the following:
9155 unbound:
9157 Same as command-line argument +sbt u in erl(1).
9158 no_spread:
9160 Same as command-line argument +sbt ns in erl(1).
9161 thread_spread:
9163 Same as command-line argument +sbt ts in erl(1).
9164 processor_spread:
9166 Same as command-line argument +sbt ps in erl(1).
9167 spread:
9169 Same as command-line argument +sbt s in erl(1).
9170 no_node_thread_spread:
9172 Same as command-line argument +sbt nnts in erl(1).
9173 no_node_processor_spread:
9175 Same as command-line argument +sbt nnps in erl(1).
9176 thread_no_node_processor_spread:
9178 Same as command-line argument +sbt tnnps in erl(1).
9179 default_bind:
9181 Same as command-line argument +sbt db in erl(1).
9182 The returned value equals How before flag scheduler_bind_type
9184 was changed.
9185 Failures:
9187 notsup:
9189 If binding of schedulers is not supported.
9190 badarg:
9192 If How is not one of the documented alternatives.
9193 badarg:
9195 If CPU topology information is unavailable.
9196 The scheduler bind type can also be set by passing command-line
9198 argument +sbt to erl(1).
9199 For more information, see erlang:system_info(sched‐
9201 uler_bind_type), erlang:system_info(scheduler_bindings), as well
9202 as command-line flags +sbt and +sct in erl(1).
9203 erlang:system_flag(Flag :: scheduler_wall_time, Boolean) ->
9205 OldBoolean
9206 Types:
9208 Boolean = OldBoolean = boolean()
9210 Try enable or disable scheduler wall time measurements by pass‐
9212 ing Boolean as either true or false.
9213 For more information about how to use scheduler wall time mea‐
9215 surements, see statistics(scheduler_wall_time).
9216 Scheduler wall time measurements has a node global state. It is
9218 either enabled for all processes on the node or disabled for all
9219 processes. Each process has a logical counter initialized as
9220 zero. A call with Boolean as true will increase that counter one
9221 step for the calling process. A call with false will decrease it
9222 one step unless it already is zero. The node global state for
9223 scheduler_wall_time will be enabled as long as there is at least
9224 one process alive with a counter value larger than zero. When a
9225 process terminates, its counter will also disappear. To ensure
9226 scheduler_wall_time is kept enabled, the process that enabled it
9227 must therefore be kept alive.
9228 Returns the old value of the node global state, true if sched‐
9230 uler wall time measurements were enabled, false if it were dis‐
9231 abled.
9232 Scheduler wall time measurements do consume some cpu overhead
9234 and should not be left turned on unless used.
9235 erlang:system_flag(Flag :: schedulers_online, SchedulersOnline) ->
9237 OldSchedulersOnline
9238 Types:
9240 SchedulersOnline = OldSchedulersOnline = integer() >= 1
9242 Sets the number of schedulers online. Range is 1 <= Scheduler‐
9244 sOnline <= erlang:system_info(schedulers).
9245 Returns the old value of the flag.
9247 If the emulator was built with support for dirty schedulers,
9249 changing the number of schedulers online can also change the
9250 number of dirty CPU schedulers online. For example, if 12 sched‐
9251 ulers and 6 dirty CPU schedulers are online, and system_flag/2
9252 is used to set the number of schedulers online to 6, then the
9253 number of dirty CPU schedulers online is automatically decreased
9254 by half as well, down to 3. Similarly, the number of dirty CPU
9255 schedulers online increases proportionally to increases in the
9256 number of schedulers online.
9257 For more information, see erlang:system_info(schedulers) and er‐
9259 lang:system_info(schedulers_online).
9260 erlang:system_flag(Flag :: system_logger, Logger) -> PrevLogger
9262 Types:
9264 Logger = PrevLogger = logger | undefined | pid()
9266 Sets the process that will receive the logging messages gener‐
9268 ated by ERTS. If set to undefined, all logging messages gener‐
9269 ated by ERTS will be dropped. The messages will be in the for‐
9270 mat:
9271 {log,Level,Format,ArgList,Metadata} where
9273 Level = atom(),
9275 Format = string(),
9276 ArgList = list(term()),
9277 Metadata = #{ pid => pid(),
9278 group_leader => pid(),
9279 time := logger:timestamp(),
9280 error_logger := #{ emulator := true, tag := atom() }
9281 If the system_logger process dies, this flag will be reset to
9284 logger.
9285 The default is the process named logger.
9287 Returns the old value of the flag.
9289 Note:
9291 This function is designed to be used by the KERNEL logger. Be
9292 careful if you change it to something else as log messages may
9293 be lost. If you want to intercept emulator log messages, do it
9294 by adding a specialized handler to the KERNEL logger.
9295 erlang:system_flag(Flag :: trace_control_word, TCW) -> OldTCW
9298 Types:
9300 TCW = OldTCW = integer() >= 0
9302 Sets the value of the node trace control word to TCW, which is
9304 to be an unsigned integer. For more information, see function
9305 set_tcw in section "Match Specifications in Erlang" in the
9306 User's Guide.
9307 Returns the old value of the flag.
9309 erlang:system_flag(Flag :: time_offset, Value :: finalize) ->
9311 OldState
9312 Types:
9314 OldState = preliminary | final | volatile
9316 Finalizes the time offset when single time warp mode is used. If
9318 another time warp mode is used, the time offset state is left
9319 unchanged.
9320 Returns the old state identifier, that is:
9322 * If preliminary is returned, finalization was performed and
9324 the time offset is now final.
9325 * If final is returned, the time offset was already in the fi‐
9327 nal state. This either because another erlang:sys‐
9328 tem_flag(time_offset, finalize) call or because no time warp
9329 mode is used.
9330 * If volatile is returned, the time offset cannot be finalized
9332 because multi-time warp mode is used.
9333 erlang:system_info(Item :: overview) -> boolean()
9335 Returns information about the current system. The documentation
9337 of this function is broken into the following sections in order
9338 to make it easier to navigate.
9339 Memory Allocation:
9341 allocated_areas, allocator, alloc_util_allocators, alloca‐
9342 tor_sizes
9343 CPU Topology:
9345 cpu_topology, logical_processors, cpu_quota, update_cpu_info
9346 Process Information:
9348 fullsweep_after, garbage_collection, heap_sizes, heap_type,
9349 max_heap_size, message_queue_data, min_heap_size,
9350 min_bin_vheap_size, procs
9351 System Limits:
9353 atom_count, atom_limit, ets_count, ets_limit, port_count,
9354 port_limit, process_count, process_limit
9355 System Time:
9357 end_time, os_monotonic_time_source, os_system_time_source,
9358 start_time, time_correction, time_offset, time_warp_mode,
9359 tolerant_timeofday
9360 Scheduler Information:
9362 dirty_cpu_schedulers, dirty_cpu_schedulers_online,
9363 dirty_io_schedulers, multi_scheduling, multi_schedul‐
9364 ing_blockers, normal_multi_scheduling_blockers, sched‐
9365 uler_bind_type, scheduler_bindings, scheduler_id, sched‐
9366 ulers, smp_support, threads, thread_pool_size
9367 Distribution Information:
9369 async_dist, creation, delayed_node_table_gc, dist,
9370 dist_buf_busy_limit, dist_ctrl
9371 System Information:
9373 c_compiler_used, check_io, compat_rel, debug_compiled,
9374 driver_version, dynamic_trace, dynamic_trace_probes,
9375 emu_flavor, emu_type, info, kernel_poll, loaded, machine,
9376 modified_timing_level, nif_version, otp_release, outstand‐
9377 ing_system_requests_limit, port_parallelism, system_archi‐
9378 tecture, system_logger, system_version, trace_control_word,
9379 version, wordsize
9380 erlang:system_info(Item :: allocated_areas) -> [tuple()]
9382 erlang:system_info(Item :: allocator) ->
9384 {Allocator, Version, Features, Settings}
9385 erlang:system_info(Item :: {allocator, Alloc}) -> [term()]
9387 erlang:system_info(Item :: alloc_util_allocators) -> [Alloc]
9389 erlang:system_info(Item :: {allocator_sizes, Alloc}) -> [term()]
9391 Types:
9393 Allocator = undefined | glibc
9395 Version = [integer() >= 0]
9396 Features = [atom()]
9397 Settings =
9398 [{Subsystem :: atom(),
9399 [{Parameter :: atom(), Value :: term()}]}]
9400 Alloc = atom()
9401 Returns various information about the memory allocators of the
9403 current system (emulator) as specified by Item:
9404 allocated_areas:
9406 Returns a list of tuples with information about miscella‐
9407 neous allocated memory areas.
9408 Each tuple contains an atom describing the type of memory as
9410 first element and the amount of allocated memory in bytes as
9411 second element. When information about allocated and used
9412 memory is present, also a third element is present, contain‐
9413 ing the amount of used memory in bytes.
9414 erlang:system_info(allocated_areas) is intended for debug‐
9416 ging, and the content is highly implementation-dependent.
9417 The content of the results therefore changes when needed
9418 without prior notice.
9419 Notice that the sum of these values is not the total amount
9421 of memory allocated by the emulator. Some values are part of
9422 other values, and some memory areas are not part of the re‐
9423 sult. For information about the total amount of memory allo‐
9424 cated by the emulator, see erlang:memory/0,1.
9425 allocator:
9427 Returns {Allocator, Version, Features, Settings, where:
9428 * Allocator corresponds to the malloc() implementation used.
9430 If Allocator equals undefined, the malloc() implementation
9431 used cannot be identified. glibc can be identified.
9432 * Version is a list of integers (but not a string) repre‐
9434 senting the version of the malloc() implementation used.
9435 * Features is a list of atoms representing the allocation
9437 features used.
9438 * Settings is a list of subsystems, their configurable pa‐
9440 rameters, and used values. Settings can differ between
9441 different combinations of platforms, allocators, and allo‐
9442 cation features. Memory sizes are given in bytes.
9443 See also "System Flags Effecting erts_alloc" in erts_al‐
9445 loc(3).
9446 {allocator, Alloc}:
9448 Returns information about the specified allocator. As from
9449 ERTS 5.6.1, the return value is a list of {instance, Instan‐
9450 ceNo, InstanceInfo} tuples, where InstanceInfo contains in‐
9451 formation about a specific instance of the allocator. If Al‐
9452 loc is not a recognized allocator, undefined is returned. If
9453 Alloc is disabled, false is returned.
9454 Notice that the information returned is highly implementa‐
9456 tion-dependent and can be changed or removed at any time
9457 without prior notice. It was initially intended as a tool
9458 when developing new allocators, but as it can be of interest
9459 for others it has been briefly documented.
9460 The recognized allocators are listed in erts_alloc(3). In‐
9462 formation about super carriers can be obtained from ERTS 8.0
9463 with {allocator, erts_mmap} or from ERTS 5.10.4; the re‐
9464 turned list when calling with {allocator, mseg_alloc} also
9465 includes an {erts_mmap, _} tuple as one element in the list.
9466 After reading the erts_alloc(3) documentation, the returned
9468 information more or less speaks for itself, but it can be
9469 worth explaining some things. Call counts are presented by
9470 two values, the first value is giga calls, and the second
9471 value is calls. mbcs and sbcs denote multi-block carriers,
9472 and single-block carriers, respectively. Sizes are presented
9473 in bytes. When a size is not presented, it is the amount of
9474 something. Sizes and amounts are often presented by three
9475 values:
9476 * The first is the current value.
9478 * The second is the maximum value since the last call to er‐
9480 lang:system_info({allocator, Alloc}).
9481 * The third is the maximum value since the emulator was
9483 started.
9484 If only one value is present, it is the current value.
9486 fix_alloc memory block types are presented by two values.
9487 The first value is the memory pool size and the second value
9488 is the used memory size.
9489 alloc_util_allocators:
9491 Returns a list of the names of all allocators using the ERTS
9492 internal alloc_util framework as atoms. For more informa‐
9493 tion, see section The alloc_util framework in erts_alloc(3).
9494 {allocator_sizes, Alloc}:
9496 Returns various size information for the specified alloca‐
9497 tor. The information returned is a subset of the information
9498 returned by erlang:system_info({allocator, Alloc}).
9499 erlang:system_info(Item :: cpu_topology) -> CpuTopology
9501 erlang:system_info(Item ::
9503 {cpu_topology, defined | detected | used}) ->
9504 CpuTopology
9505 erlang:system_info(Item :: cpu_quota) -> integer() >= 1 | unknown
9507 erlang:system_info(Item ::
9509 logical_processors |
9510 logical_processors_available |
9511 logical_processors_online) ->
9512 unknown | integer() >= 1
9513 erlang:system_info(Item :: update_cpu_info) -> changed | unchanged
9515 Types:
9517 cpu_topology() = [LevelEntry :: level_entry()] | undefined
9519 All LevelEntrys of a list must contain the same LevelTag,
9520 except on the top level where both node and processor‐
9521 LevelTags can coexist.
9522 level_entry() =
9523 {LevelTag :: level_tag(), SubLevel :: sub_level()} |
9524 {LevelTag :: level_tag(),
9525 InfoList :: info_list(),
9526 SubLevel :: sub_level()}
9527 {LevelTag, SubLevel} == {LevelTag, [], SubLevel}
9528 level_tag() = core | node | processor | thread
9529 More LevelTags can be introduced in a future release.
9530 sub_level() =
9531 [LevelEntry :: level_entry()] |
9532 (LogicalCpuId :: {logical, integer() >= 0})
9533 info_list() = []
9534 The info_list() can be extended in a future release.
9535 Returns various information about the CPU topology of the cur‐
9537 rent system (emulator) as specified by Item:
9538 cpu_topology:
9540 Returns the CpuTopology currently used by the emulator. The
9541 CPU topology is used when binding schedulers to logical pro‐
9542 cessors. The CPU topology used is the user-defined CPU
9543 topology, if such exists, otherwise the automatically de‐
9544 tected CPU topology, if such exists. If no CPU topology ex‐
9545 ists, undefined is returned.
9546 node refers to Non-Uniform Memory Access (NUMA) nodes.
9548 thread refers to hardware threads (for example, Intel hyper-
9549 threads).
9550 A level in term CpuTopology can be omitted if only one entry
9552 exists and InfoList is empty.
9553 thread can only be a sublevel to core. core can be a sub‐
9555 level to processor or node. processor can be on the top
9556 level or a sublevel to node. node can be on the top level or
9557 a sublevel to processor. That is, NUMA nodes can be proces‐
9558 sor internal or processor external. A CPU topology can con‐
9559 sist of a mix of processor internal and external NUMA nodes,
9560 as long as each logical CPU belongs to one NUMA node. Cache
9561 hierarchy is not part of the CpuTopology type, but will be
9562 in a future release. Other things can also make it into the
9563 CPU topology in a future release. So, expect the CpuTopology
9564 type to change.
9565 {cpu_topology, defined}:
9567 Returns the user-defined CpuTopology. For more information,
9570 see command-line flag +sct in erl(1) and argument cpu_topol‐
9571 ogy.
9572 {cpu_topology, detected}:
9574 Returns the automatically detected CpuTopologyy. The emula‐
9577 tor detects the CPU topology on some newer Linux, Solaris,
9578 FreeBSD, and Windows systems. On Windows system with more
9579 than 32 logical processors, the CPU topology is not de‐
9580 tected.
9581 For more information, see argument cpu_topology.
9583 {cpu_topology, used}:
9585 Returns CpuTopology used by the emulator. For more informa‐
9586 tion, see argument cpu_topology.
9587 logical_processors:
9589 Returns the detected number of logical processors configured
9590 in the system. The return value is either an integer, or the
9591 atom unknown if the emulator cannot detect the configured
9592 logical processors.
9593 logical_processors_available:
9595 Returns the detected number of logical processors available
9596 to the Erlang runtime system. The return value is either an
9597 integer, or the atom unknown if the emulator cannot detect
9598 the available logical processors. The number of available
9599 logical processors is less than or equal to the number of
9600 logical processors online.
9601 logical_processors_online:
9603 Returns the detected number of logical processors online on
9604 the system. The return value is either an integer, or the
9605 atom unknown if the emulator cannot detect logical proces‐
9606 sors online. The number of logical processors online is less
9607 than or equal to the number of logical processors config‐
9608 ured.
9609 cpu_quota:
9611 Returns the detected CPU quota the emulator is limited by.
9612 The return value is an integer saying how many processors'
9613 worth of runtime we get (between 1 and the number of logical
9614 processors), or the atom unknown if the emulator cannot de‐
9615 tect a quota.
9616 update_cpu_info:
9618 The runtime system rereads the CPU information available and
9619 updates its internally stored information about the detected
9620 CPU topology and the number of logical processors config‐
9621 ured, online, available, and cpu quota.
9622 If the CPU information has changed since the last time it
9624 was read, the atom changed is returned, otherwise the atom
9625 unchanged. If the CPU information has changed, you probably
9626 want to adjust the number of schedulers online. You typi‐
9627 cally want to have as many schedulers online as logical pro‐
9628 cessors available.
9629 erlang:system_info(Item :: fullsweep_after) ->
9631 {fullsweep_after, integer() >= 0}
9632 erlang:system_info(Item :: garbage_collection) ->
9634 [{atom(), integer()}]
9635 erlang:system_info(Item :: heap_sizes) -> [integer() >= 0]
9637 erlang:system_info(Item :: heap_type) -> private
9639 erlang:system_info(Item :: max_heap_size) ->
9641 {max_heap_size,
9642 MaxHeapSize :: max_heap_size()}
9643 erlang:system_info(Item :: message_queue_data) ->
9645 message_queue_data()
9646 erlang:system_info(Item :: min_heap_size) ->
9648 {min_heap_size,
9649 MinHeapSize :: integer() >= 1}
9650 erlang:system_info(Item :: min_bin_vheap_size) ->
9652 {min_bin_vheap_size,
9653 MinBinVHeapSize :: integer() >= 1}
9654 erlang:system_info(Item :: procs) -> binary()
9656 Types:
9658 message_queue_data() = off_heap | on_heap
9660 max_heap_size() =
9661 integer() >= 0 |
9662 #{size => integer() >= 0,
9663 kill => boolean(),
9664 error_logger => boolean(),
9665 include_shared_binaries => boolean()}
9666 Returns information about the default process heap settings:
9668 fullsweep_after:
9670 Returns {fullsweep_after, integer() >= 0}, which is the
9671 fullsweep_after garbage collection setting used by default.
9672 For more information, see garbage_collection described be‐
9673 low.
9674 garbage_collection:
9676 Returns a list describing the default garbage collection
9677 settings. A process spawned on the local node by a spawn or
9678 spawn_link uses these garbage collection settings. The de‐
9679 fault settings can be changed by using erlang:system_flag/2.
9680 spawn_opt/2,3,4 can spawn a process that does not use the
9681 default settings.
9682 heap_sizes:
9684 Returns a list of integers representing valid heap sizes in
9685 words. All Erlang heaps are sized from sizes in this list.
9686 heap_type:
9688 Returns the heap type used by the current emulator. One heap
9689 type exists:
9690 private:
9692 Each process has a heap reserved for its use and no ref‐
9693 erences between heaps of different processes are allowed.
9694 Messages passed between processes are copied between
9695 heaps.
9696 max_heap_size:
9698 Returns {max_heap_size, MaxHeapSize}, where MaxHeapSize is
9699 the current system-wide maximum heap size settings for
9700 spawned processes. This setting can be set using the com‐
9701 mand-line flags +hmax, +hmaxk, +hmaxel and +hmaxibl in
9702 erl(1). It can also be changed at runtime using erlang:sys‐
9703 tem_flag(max_heap_size, MaxHeapSize). For more details about
9704 the max_heap_size process flag, see
9705 process_flag(max_heap_size, MaxHeapSize).
9706 message_queue_data:
9708 Returns the default value of the message_queue_data process
9709 flag, which can be either off_heap or on_heap. The default
9710 value is set by the command-line argument +hmqd in erl(1).
9711 For more information, see the documentation of
9712 process_flag(message_queue_data, MQD).
9713 min_heap_size:
9715 Returns {min_heap_size, MinHeapSize}, where MinHeapSize is
9716 the current system-wide minimum heap size for spawned pro‐
9717 cesses.
9718 min_bin_vheap_size:
9720 Returns {min_bin_vheap_size, MinBinVHeapSize}, where MinBin‐
9721 VHeapSize is the current system-wide minimum binary virtual
9722 heap size for spawned processes.
9723 procs:
9725 Returns a binary containing a string of process and port in‐
9726 formation formatted as in Erlang crash dumps. For more in‐
9727 formation, see section How to interpret the Erlang crash
9728 dumps in the User's Guide.
9729 erlang:system_info(Item :: atom_count) -> integer() >= 1
9731 erlang:system_info(Item :: atom_limit) -> integer() >= 1
9733 erlang:system_info(Item :: ets_count) -> integer() >= 1
9735 erlang:system_info(Item :: ets_limit) -> integer() >= 1
9737 erlang:system_info(Item :: port_parallelism) -> boolean()
9739 erlang:system_info(Item :: port_count) -> integer() >= 0
9741 erlang:system_info(Item :: port_limit) -> integer() >= 1
9743 erlang:system_info(Item :: process_count) -> integer() >= 1
9745 Returns information about the current system (emulator) limits
9747 as specified by Item:
9748 atom_count:
9750 Returns the number of atoms currently existing at the local
9751 node. The value is given as an integer.
9752 atom_limit:
9754 Returns the maximum number of atoms allowed. This limit can
9755 be increased at startup by passing command-line flag +t to
9756 erl(1).
9757 ets_count:
9759 Returns the number of ETS tables currently existing at the
9760 local node.
9761 ets_limit:
9763 Returns the limit for number of ETS tables. This limit is
9764 partially obsolete and number of tables are only limited by
9765 available memory.
9766 port_count:
9768 Returns the number of ports currently existing at the local
9769 node. The value is given as an integer. This is the same
9770 value as returned by length(erlang:ports()), but more effi‐
9771 cient.
9772 port_limit:
9774 Returns the maximum number of simultaneously existing ports
9775 at the local node as an integer. This limit can be config‐
9776 ured at startup by using command-line flag +Q in erl(1).
9777 process_count:
9779 Returns the number of processes currently existing at the
9780 local node. The value is given as an integer. This is the
9781 same value as returned by length(processes()), but more ef‐
9782 ficient.
9783 process_limit:
9785 Returns the maximum number of simultaneously existing pro‐
9786 cesses at the local node. The value is given as an integer.
9787 This limit can be configured at startup by using command-
9788 line flag +P in erl(1).
9789 erlang:system_info(Item :: end_time) -> integer() >= 0
9791 erlang:system_info(Item :: os_monotonic_time_source) ->
9793 [{atom(), term()}]
9794 erlang:system_info(Item :: os_system_time_source) ->
9796 [{atom(), term()}]
9797 erlang:system_info(Item :: start_time) -> integer()
9799 erlang:system_info(Item :: time_correction) -> true | false
9801 erlang:system_info(Item :: time_offset) ->
9803 preliminary | final | volatile
9804 erlang:system_info(Item :: time_warp_mode) ->
9806 no_time_warp | single_time_warp |
9807 multi_time_warp
9808 erlang:system_info(Item :: tolerant_timeofday) ->
9810 enabled | disabled
9811 Returns information about the current system (emulator) time as
9813 specified by Item:
9814 end_time:
9816 The last Erlang monotonic time in native time unit that can
9817 be represented internally in the current Erlang runtime sys‐
9818 tem instance. The time between the start time and the end
9819 time is at least a quarter of a millennium.
9820 os_monotonic_time_source:
9822 Returns a list containing information about the source of OS
9823 monotonic time that is used by the runtime system.
9824 If [] is returned, no OS monotonic time is available. The
9826 list contains two-tuples with Keys as first element, and
9827 Values as second element. The order of these tuples is unde‐
9828 fined. The following tuples can be part of the list, but
9829 more tuples can be introduced in the future:
9830 {function, Function}:
9832 Function is the name of the function used. This tuple al‐
9833 ways exists if OS monotonic time is available to the run‐
9834 time system.
9835 {clock_id, ClockId}:
9837 This tuple only exists if Function can be used with dif‐
9838 ferent clocks. ClockId corresponds to the clock identifier
9839 used when calling Function.
9840 {resolution, OsMonotonicTimeResolution}:
9842 Highest possible resolution of current OS monotonic time
9843 source as parts per second. If no resolution information
9844 can be retrieved from the OS, OsMonotonicTimeResolution is
9845 set to the resolution of the time unit of Functions return
9846 value. That is, the actual resolution can be lower than
9847 OsMonotonicTimeResolution. Notice that the resolution does
9848 not say anything about the accuracy or whether the pre‐
9849 cision aligns with the resolution. You do, however, know
9850 that the precision is not better than OsMonotonicTimeReso‐
9851 lution.
9852 {extended, Extended}:
9854 Extended equals yes if the range of time values has been
9855 extended; otherwise Extended equals no. The range must be
9856 extended if Function returns values that wrap fast. This
9857 typically is the case when the return value is a 32-bit
9858 value.
9859 {parallel, Parallel}:
9861 Parallel equals yes if Function is called in parallel from
9862 multiple threads. If it is not called in parallel, because
9863 calls must be serialized, Parallel equals no.
9864 {time, OsMonotonicTime}:
9866 OsMonotonicTime equals current OS monotonic time in native
9867 time unit.
9868 os_system_time_source:
9870 Returns a list containing information about the source of OS
9871 system time that is used by the runtime system.
9872 The list contains two-tuples with Keys as first element, and
9874 Values as second element. The order of these tuples is unde‐
9875 fined. The following tuples can be part of the list, but
9876 more tuples can be introduced in the future:
9877 {function, Function}:
9879 Function is the name of the function used.
9880 {clock_id, ClockId}:
9882 Exists only if Function can be used with different clocks.
9883 ClockId corresponds to the clock identifier used when
9884 calling Function.
9885 {resolution, OsSystemTimeResolution}:
9887 Highest possible resolution of current OS system time
9888 source as parts per second. If no resolution information
9889 can be retrieved from the OS, OsSystemTimeResolution is
9890 set to the resolution of the time unit of Functions return
9891 value. That is, the actual resolution can be lower than
9892 OsSystemTimeResolution. Notice that the resolution does
9893 not say anything about the accuracy or whether the pre‐
9894 cision do align with the resolution. You do, however, know
9895 that the precision is not better than OsSystemTimeResolu‐
9896 tion.
9897 {parallel, Parallel}:
9899 Parallel equals yes if Function is called in parallel from
9900 multiple threads. If it is not called in parallel, because
9901 calls needs to be serialized, Parallel equals no.
9902 {time, OsSystemTime}:
9904 OsSystemTime equals current OS system time in native time
9905 unit.
9906 start_time:
9908 The Erlang monotonic time in native time unit at the time
9909 when current Erlang runtime system instance started.
9910 See also erlang:system_info(end_time).
9912 time_correction:
9914 Returns a boolean value indicating whether time correction
9915 is enabled or not.
9916 time_offset:
9918 Returns the state of the time offset:
9919 preliminary:
9921 The time offset is preliminary, and will be changed and
9922 finalized later. The preliminary time offset is used dur‐
9923 ing the preliminary phase of the single time warp mode.
9924 final:
9926 The time offset is final. This either because no time
9927 warp mode is used, or because the time offset have been
9928 finalized when single time warp mode is used.
9929 volatile:
9931 The time offset is volatile. That is, it can change at any
9932 time. This is because multi-time warp mode is used.
9933 time_warp_mode:
9935 Returns a value identifying the time warp mode that is
9936 used:
9937 no_time_warp:
9939 The no time warp mode is used.
9940 single_time_warp:
9942 The single time warp mode is used.
9943 multi_time_warp:
9945 The multi-time warp mode is used.
9946 tolerant_timeofday:
9948 Returns whether a pre ERTS 7.0 backwards compatible compen‐
9949 sation for sudden changes of system time is enabled or dis‐
9950 abled. Such compensation is enabled when the time offset is
9951 final, and time correction is enabled.
9952 erlang:system_info(Item :: dirty_cpu_schedulers) ->
9954 integer() >= 0
9955 erlang:system_info(Item :: dirty_cpu_schedulers_online) ->
9957 integer() >= 0
9958 erlang:system_info(Item :: dirty_io_schedulers) ->
9960 integer() >= 0
9961 erlang:system_info(Item :: multi_scheduling) ->
9963 disabled | blocked | blocked_normal |
9964 enabled
9965 erlang:system_info(Item :: multi_scheduling_blockers) ->
9967 [Pid :: pid()]
9968 erlang:system_info(Item :: normal_multi_scheduling_blockers) ->
9970 [Pid :: pid()]
9971 erlang:system_info(Item :: scheduler_bind_type) ->
9973 spread | processor_spread | thread_spread |
9974 thread_no_node_processor_spread |
9975 no_node_processor_spread |
9976 no_node_thread_spread | no_spread | unbound
9977 erlang:system_info(Item :: scheduler_bindings) -> tuple()
9979 erlang:system_info(Item :: scheduler_id) ->
9981 SchedulerId :: integer() >= 1
9982 erlang:system_info(Item :: schedulers | schedulers_online) ->
9984 integer() >= 1
9985 erlang:system_info(Item :: smp_support) -> boolean()
9987 erlang:system_info(Item :: threads) -> boolean()
9989 erlang:system_info(Item :: thread_pool_size) -> integer() >= 0
9991 Returns information about schedulers, scheduling and threads in
9993 the current system as specified by Item:
9994 dirty_cpu_schedulers:
9996 Returns the number of dirty CPU scheduler threads used by
9997 the emulator. Dirty CPU schedulers execute CPU-bound native
9998 functions, such as NIFs, linked-in driver code, and BIFs
9999 that cannot be managed cleanly by the normal emulator sched‐
10000 ulers.
10001 The number of dirty CPU scheduler threads is determined at
10003 emulator boot time and cannot be changed after that. How‐
10004 ever, the number of dirty CPU scheduler threads online can
10005 be changed at any time. The number of dirty CPU schedulers
10006 can be set at startup by passing command-line flag +SDcpu or
10007 +SDPcpu in erl(1).
10008 See also erlang:system_flag(dirty_cpu_schedulers_online,
10010 DirtyCPUSchedulersOnline), erlang:sys‐
10011 tem_info(dirty_cpu_schedulers_online), erlang:sys‐
10012 tem_info(dirty_io_schedulers), erlang:system_info(sched‐
10013 ulers), erlang:system_info(schedulers_online), and er‐
10014 lang:system_flag(schedulers_online, SchedulersOnline).
10015 dirty_cpu_schedulers_online:
10017 Returns the number of dirty CPU schedulers online. The re‐
10018 turn value satisfies 1 <= DirtyCPUSchedulersOnline <= N,
10019 where N is the smallest of the return values of erlang:sys‐
10020 tem_info(dirty_cpu_schedulers) and erlang:system_info(sched‐
10021 ulers_online).
10022 The number of dirty CPU schedulers online can be set at
10024 startup by passing command-line flag +SDcpu in erl(1).
10025 For more information, see erlang:sys‐
10027 tem_info(dirty_cpu_schedulers), erlang:sys‐
10028 tem_info(dirty_io_schedulers), erlang:system_info(sched‐
10029 ulers_online), and erlang:system_flag(dirty_cpu_sched‐
10030 ulers_online, DirtyCPUSchedulersOnline).
10031 dirty_io_schedulers:
10033 Returns the number of dirty I/O schedulers as an integer.
10034 Dirty I/O schedulers execute I/O-bound native functions,
10035 such as NIFs and linked-in driver code, which cannot be man‐
10036 aged cleanly by the normal emulator schedulers.
10037 This value can be set at startup by passing command-line ar‐
10039 gument +SDio in erl(1).
10040 For more information, see erlang:sys‐
10042 tem_info(dirty_cpu_schedulers), erlang:sys‐
10043 tem_info(dirty_cpu_schedulers_online), and erlang:sys‐
10044 tem_flag(dirty_cpu_schedulers_online, DirtyCPUSchedulersOn‐
10045 line).
10046 multi_scheduling:
10048 Returns one of the following:
10049 disabled:
10051 The emulator has been started with only one scheduler
10052 thread.
10053 blocked:
10055 The emulator has more than one scheduler thread, but all
10056 scheduler threads except one are blocked. That is, only
10057 one scheduler thread schedules Erlang processes and exe‐
10058 cutes Erlang code.
10059 blocked_normal:
10061 The emulator has more than one scheduler thread, but all
10062 normal scheduler threads except one are blocked. Notice
10063 that dirty schedulers are not blocked, and can schedule
10064 Erlang processes and execute native code.
10065 enabled:
10067 The emulator has more than one scheduler thread, and no
10068 scheduler threads are blocked. That is, all available
10069 scheduler threads schedule Erlang processes and execute
10070 Erlang code.
10071 See also erlang:system_flag(multi_scheduling, BlockState),
10073 erlang:system_info(multi_scheduling_blockers), erlang:sys‐
10074 tem_info(normal_multi_scheduling_blockers), and erlang:sys‐
10075 tem_info(schedulers).
10076 multi_scheduling_blockers:
10078 Returns a list of Pids when multi-scheduling is blocked,
10079 otherwise the empty list is returned. The Pids in the list
10080 represent all the processes currently blocking multi-sched‐
10081 uling. A Pid occurs only once in the list, even if the cor‐
10082 responding process has blocked multiple times.
10083 See also erlang:system_flag(multi_scheduling, BlockState),
10085 erlang:system_info(multi_scheduling), erlang:sys‐
10086 tem_info(normal_multi_scheduling_blockers), and erlang:sys‐
10087 tem_info(schedulers).
10088 normal_multi_scheduling_blockers:
10090 Returns a list of Pids when normal multi-scheduling is
10091 blocked (that is, all normal schedulers but one is blocked),
10092 otherwise the empty list is returned. The Pids in the list
10093 represent all the processes currently blocking normal multi-
10094 scheduling. A Pid occurs only once in the list, even if the
10095 corresponding process has blocked multiple times.
10096 See also erlang:system_flag(multi_scheduling, BlockState),
10098 erlang:system_info(multi_scheduling), erlang:sys‐
10099 tem_info(multi_scheduling_blockers), and erlang:sys‐
10100 tem_info(schedulers).
10101 scheduler_bind_type:
10103 Returns information about how the user has requested sched‐
10104 ulers to be bound or not bound.
10105 Notice that although a user has requested schedulers to be
10107 bound, they can silently have failed to bind. To inspect the
10108 scheduler bindings, call erlang:system_info(scheduler_bind‐
10109 ings).
10110 For more information, see command-line argument +sbt in
10112 erl(1) and erlang:system_info(scheduler_bindings).
10113 scheduler_bindings:
10115 Returns information about the currently used scheduler bind‐
10116 ings.
10117 A tuple of a size equal to erlang:system_info(schedulers) is
10119 returned. The tuple elements are integers or the atom un‐
10120 bound. Logical processor identifiers are represented as in‐
10121 tegers. The Nth element of the tuple equals the current
10122 binding for the scheduler with the scheduler identifier
10123 equal to N. For example, if the schedulers are bound, ele‐
10124 ment(erlang:system_info(scheduler_id), erlang:sys‐
10125 tem_info(scheduler_bindings)) returns the identifier of the
10126 logical processor that the calling process is executing on.
10127 Notice that only schedulers online can be bound to logical
10129 processors.
10130 For more information, see command-line argument +sbt in
10132 erl(1) and erlang:system_info(schedulers_online).
10133 scheduler_id:
10135 Returns the scheduler ID (SchedulerId) of the scheduler
10136 thread that the calling process is executing on. SchedulerId
10137 is a positive integer, where 1 <= SchedulerId <= erlang:sys‐
10138 tem_info(schedulers).
10139 See also erlang:system_info(schedulers).
10141 schedulers:
10143 Returns the number of scheduler threads used by the emula‐
10144 tor. Scheduler threads online schedules Erlang processes and
10145 Erlang ports, and execute Erlang code and Erlang linked-in
10146 driver code.
10147 The number of scheduler threads is determined at emulator
10149 boot time and cannot be changed later. However, the number
10150 of schedulers online can be changed at any time.
10151 See also erlang:system_flag(schedulers_online, SchedulersOn‐
10153 line), erlang:system_info(schedulers_online), erlang:sys‐
10154 tem_info(scheduler_id), erlang:system_flag(multi_scheduling,
10155 BlockState), erlang:system_info(multi_scheduling), er‐
10156 lang:system_info(normal_multi_scheduling_blockers) and er‐
10157 lang:system_info(multi_scheduling_blockers).
10158 schedulers_online:
10160 Returns the number of schedulers online. The scheduler iden‐
10161 tifiers of schedulers online satisfy the relationship 1 <=
10162 SchedulerId <= erlang:system_info(schedulers_online).
10163 For more information, see erlang:system_info(schedulers) and
10165 erlang:system_flag(schedulers_online, SchedulersOnline).
10166 smp_support:
10168 Returns true.
10169 threads:
10171 Returns true.
10172 thread_pool_size:
10174 Returns the number of async threads in the async thread pool
10177 used for asynchronous driver calls
10178 (erl_driver:driver_async()). The value is given as an inte‐
10179 ger.
10180 erlang:system_info(Item :: async_dist) -> boolean()
10182 erlang:system_info(Item :: creation) -> integer()
10184 erlang:system_info(Item :: delayed_node_table_gc) ->
10186 infinity | integer() >= 0
10187 erlang:system_info(Item :: dist) -> binary()
10189 erlang:system_info(Item :: dist_buf_busy_limit) ->
10191 integer() >= 0
10192 erlang:system_info(Item :: dist_ctrl) ->
10194 [{Node :: node(),
10195 ControllingEntity :: port() | pid()}]
10196 Returns information about Erlang Distribution in the current
10198 system as specified by Item:
10199 async_dist:
10201 Since: OTP 25.3
10202 Returns the value of the command line argument +pad <bool‐
10204 ean> which the runtime system use. This value determines the
10205 default async_dist value for newly spawned processes.
10206 creation:
10208 Returns the "creation" value of the local node as an inte‐
10209 ger. The creation is changed when a node is restarted. The
10210 creation of a node is stored in process identifiers, port
10211 identifiers, and references. This makes it possible to dis‐
10212 tinguish between identifiers from different incarnations of
10213 a node. Creation values are currently 32-bit positive inte‐
10214 gers, but this may change in future releases. If the node is
10215 not alive, 0 is returned.
10216 delayed_node_table_gc:
10218 Returns the amount of time in seconds garbage collection of
10219 an entry in a node table is delayed. This limit can be set
10220 on startup by passing command-line flag +zdntgc to erl(1).
10221 For more information, see the documentation of the command-
10222 line flag.
10223 dist:
10225 Returns a binary containing a string of distribution infor‐
10226 mation formatted as in Erlang crash dumps. For more informa‐
10227 tion, see section How to interpret the Erlang crash dumps
10228 in the User's Guide.
10229 dist_buf_busy_limit:
10231 Returns the value of the distribution buffer busy limit in
10232 bytes. This limit can be set at startup by passing command-
10233 line flag +zdbbl to erl(1).
10234 dist_ctrl:
10236 Returns a list of tuples {Node, ControllingEntity}, one en‐
10237 try for each connected remote node. Node is the node name
10238 and ControllingEntity is the port or process identifier re‐
10239 sponsible for the communication to that node. More specifi‐
10240 cally, ControllingEntity for nodes connected through TCP/IP
10241 (the normal case) is the socket used in communication with
10242 the specific node.
10243 erlang:system_info(Item :: c_compiler_used) -> {atom(), term()}
10245 erlang:system_info(Item :: check_io) -> [term()]
10247 erlang:system_info(Item :: compat_rel) -> integer()
10249 erlang:system_info(Item :: debug_compiled) -> boolean()
10251 erlang:system_info(Item :: driver_version) -> string()
10253 erlang:system_info(Item :: dynamic_trace) ->
10255 none | dtrace | systemtap
10256 erlang:system_info(Item :: dynamic_trace_probes) -> boolean()
10258 erlang:system_info(Item :: emu_flavor) -> emu | jit
10260 erlang:system_info(Item :: emu_type) ->
10262 opt | debug | gcov | valgrind | gprof |
10263 lcnt | frmptr
10264 erlang:system_info(Item :: info) -> binary()
10266 erlang:system_info(Item :: kernel_poll) -> boolean()
10268 erlang:system_info(Item :: loaded) -> binary()
10270 erlang:system_info(Item :: machine) -> string()
10272 erlang:system_info(Item :: modified_timing_level) ->
10274 integer() | undefined
10275 erlang:system_info(Item :: nif_version) -> string()
10277 erlang:system_info(Item :: otp_release) -> string()
10279 erlang:system_info(Item :: outstanding_system_requests_limit) ->
10281 1..134217727
10282 erlang:system_info(Item :: port_parallelism) -> boolean()
10284 erlang:system_info(Item :: system_architecture) -> string()
10286 erlang:system_info(Item :: system_logger) ->
10288 logger | undefined | pid()
10289 erlang:system_info(Item :: system_version) -> string()
10291 erlang:system_info(Item :: trace_control_word) ->
10293 integer() >= 0
10294 erlang:system_info(Item :: version) -> string()
10296 erlang:system_info(Item ::
10298 wordsize |
10299 {wordsize, internal} |
10300 {wordsize, external}) ->
10301 4 | 8
10302 Returns various information about the current system (emulator)
10304 as specified by Item:
10305 build_type:
10307 Deprecated, use emu_type instead
10308 c_compiler_used:
10310 Returns a two-tuple describing the C compiler used when com‐
10311 piling the runtime system. The first element is an atom de‐
10312 scribing the name of the compiler, or undefined if unknown.
10313 The second element is a term describing the version of the
10314 compiler, or undefined if unknown.
10315 check_io:
10317 Returns a list containing miscellaneous information about
10318 the emulators internal I/O checking. Notice that the content
10319 of the returned list can vary between platforms and over
10320 time. It is only guaranteed that a list is returned.
10321 compat_rel:
10323 Returns the compatibility mode of the local node as an inte‐
10324 ger. The integer returned represents the Erlang/OTP release
10325 that the current emulator has been set to be backward com‐
10326 patible with. The compatibility mode can be configured at
10327 startup by using command-line flag +R in erl(1).
10328 debug_compiled:
10330 Returns true if the emulator has been debug-compiled, other‐
10331 wise false.
10332 driver_version:
10334 Returns a string containing the Erlang driver version used
10335 by the runtime system. It has the form "<major ver>.<minor
10336 ver>".
10337 dynamic_trace:
10339 Returns an atom describing the dynamic trace framework com‐
10340 piled into the virtual machine. It can be dtrace, systemtap,
10341 or none. For a commercial or standard build, it is always
10342 none. The other return values indicate a custom configura‐
10343 tion (for example, ./configure --with-dynamic-trace=dtrace).
10344 For more information about dynamic tracing, see dyntrace(3)
10345 manual page and the README.dtrace/README.systemtap files in
10346 the Erlang source code top directory.
10347 dynamic_trace_probes:
10349 Returns a boolean() indicating if dynamic trace probes
10350 (dtrace or systemtap) are built into the emulator. This can
10351 only be true if the virtual machine was built for dynamic
10352 tracing (that is, system_info(dynamic_trace) returns dtrace
10353 or systemtap).
10354 emu_flavor:
10356 Returns an atom describing the flavor of the runtime system.
10357 This will be either emu or jit. Possible return values can
10358 be added or removed at any time without prior notice.
10359 emu_type:
10361 Returns an atom describing the build type of the runtime
10362 system. This is normally the atom opt for optimized. Other
10363 possible return values are debug, gcov, valgrind, gprof, and
10364 lcnt. Possible return values can be added or removed at any
10365 time without prior notice.
10366 info:
10368 Returns a binary containing a string of miscellaneous system
10369 information formatted as in Erlang crash dumps. For more in‐
10370 formation, see section How to interpret the Erlang crash
10371 dumps in the User's Guide.
10372 kernel_poll:
10374 Returns true if the emulator uses some kind of kernel-poll
10375 implementation, otherwise false.
10376 loaded:
10378 Returns a binary containing a string of loaded module infor‐
10379 mation formatted as in Erlang crash dumps. For more informa‐
10380 tion, see section How to interpret the Erlang crash dumps in
10381 the User's Guide.
10382 machine:
10384 Returns a string containing the Erlang machine name.
10385 modified_timing_level:
10387 Returns the modified timing-level (an integer) if modified
10388 timing is enabled, otherwise undefined. For more information
10389 about modified timing, see command-line flag +T in erl(1)
10390 nif_version:
10392 Returns a string containing the version of the Erlang NIF
10393 interface used by the runtime system. It is on the form
10394 "<major ver>.<minor ver>".
10395 otp_release:
10397 Returns a string containing the OTP release number of the
10400 OTP release that the currently executing ERTS application is
10401 part of.
10402 As from Erlang/OTP 17, the OTP release number corresponds to
10404 the major OTP version number. No erlang:system_info() argu‐
10405 ment gives the exact OTP version. This is because the exact
10406 OTP version in the general case is difficult to determine.
10407 For more information, see the description of versions in
10408 System principles in System Documentation.
10409 outstanding_system_requests_limit:
10411 Returns the limit on the amount of outstanding requests made
10412 by a system process orchestrating system wide changes. See
10413 erlang:system_flag(outstanding_system_requests_limit, Limit)
10414 for more information.
10415 port_parallelism:
10417 Returns the default port parallelism scheduling hint used.
10418 For more information, see command-line argument +spp in
10419 erl(1).
10420 system_architecture:
10422 Returns a string containing the processor and OS architec‐
10423 ture the emulator is built for.
10424 system_logger:
10426 Returns the current system_logger as set by erlang:sys‐
10427 tem_flag(system_logger, _).
10428 system_version:
10430 Returns a string containing version number and some impor‐
10431 tant properties, such as the number of schedulers.
10432 trace_control_word:
10434 Returns the value of the node trace control word. For more
10435 information, see function get_tcw in section Match Specifi‐
10436 cations in Erlang in the User's Guide.
10437 version:
10439 Returns a string containing the version number of the emula‐
10440 tor.
10441 wordsize:
10443 Same as {wordsize, internal}.
10444 {wordsize, internal}:
10446 Returns the size of Erlang term words in bytes as an inte‐
10447 ger, that is, 4 is returned on a 32-bit architecture, and 8
10448 is returned on a 64-bit architecture.
10449 {wordsize, external}:
10451 Returns the true word size of the emulator, that is, the
10452 size of a pointer. The value is given in bytes as an inte‐
10453 ger. On a pure 32-bit architecture, 4 is returned. On a
10454 64-bit architecture, 8 is returned.
10455 erlang:system_monitor() -> MonSettings
10457 Types:
10459 MonSettings = undefined | {MonitorPid, Options}
10461 MonitorPid = pid()
10462 Options = [system_monitor_option()]
10463 system_monitor_option() =
10464 busy_port | busy_dist_port |
10465 {long_gc, integer() >= 0} |
10466 {long_schedule, integer() >= 0} |
10467 {large_heap, integer() >= 0}
10468 Returns the current system monitoring settings set by er‐
10470 lang:system_monitor/2 as {MonitorPid, Options}, or undefined if
10471 no settings exist. The order of the options can be different
10472 from the one that was set.
10473 erlang:system_monitor(Arg) -> MonSettings
10475 Types:
10477 Arg = MonSettings = undefined | {MonitorPid, Options}
10479 MonitorPid = pid()
10480 Options = [system_monitor_option()]
10481 system_monitor_option() =
10482 busy_port | busy_dist_port |
10483 {long_gc, integer() >= 0} |
10484 {long_schedule, integer() >= 0} |
10485 {large_heap, integer() >= 0}
10486 When called with argument undefined, all system performance mon‐
10488 itoring settings are cleared.
10489 Calling the function with {MonitorPid, Options} as argument is
10491 the same as calling erlang:system_monitor(MonitorPid, Options).
10492 Returns the previous system monitor settings just like er‐
10494 lang:system_monitor/0.
10495 erlang:system_monitor(MonitorPid, Options) -> MonSettings
10497 Types:
10499 MonitorPid = pid()
10501 Options = [system_monitor_option()]
10502 MonSettings = undefined | {OldMonitorPid, OldOptions}
10503 OldMonitorPid = pid()
10504 OldOptions = [system_monitor_option()]
10505 system_monitor_option() =
10506 busy_port | busy_dist_port |
10507 {long_gc, integer() >= 0} |
10508 {long_schedule, integer() >= 0} |
10509 {large_heap, integer() >= 0}
10510 Sets the system performance monitoring options. MonitorPid is a
10512 local process identifier (pid) receiving system monitor mes‐
10513 sages. The second argument is a list of monitoring options:
10514 {long_gc, Time}:
10516 If a garbage collection in the system takes at least Time
10517 wall clock milliseconds, a message {monitor, GcPid, long_gc,
10518 Info} is sent to MonitorPid. GcPid is the pid that was
10519 garbage collected. Info is a list of two-element tuples de‐
10520 scribing the result of the garbage collection.
10521 One of the tuples is {timeout, GcTime}, where GcTime is the
10523 time for the garbage collection in milliseconds. The other
10524 tuples are tagged with heap_size, heap_block_size,
10525 stack_size, mbuf_size, old_heap_size, and
10526 old_heap_block_size. These tuples are explained in the de‐
10527 scription of trace message gc_minor_start (see er‐
10528 lang:trace/3). New tuples can be added, and the order of the
10529 tuples in the Info list can be changed at any time without
10530 prior notice.
10531 {long_schedule, Time}:
10533 If a process or port in the system runs uninterrupted for at
10534 least Time wall clock milliseconds, a message {monitor, Pi‐
10535 dOrPort, long_schedule, Info} is sent to MonitorPid. PidOr‐
10536 Port is the process or port that was running. Info is a list
10537 of two-element tuples describing the event.
10538 If a pid(), the tuples {timeout, Millis}, {in, Location},
10540 and {out, Location} are present, where Location is either an
10541 MFA ({Module, Function, Arity}) describing the function
10542 where the process was scheduled in/out, or the atom unde‐
10543 fined.
10544 If a port(), the tuples {timeout, Millis} and {port_op,Op}
10546 are present. Op is one of proc_sig, timeout, input, output,
10547 event, or dist_cmd, depending on which driver callback was
10548 executing.
10549 proc_sig is an internal operation and is never to appear,
10551 while the others represent the corresponding driver call‐
10552 backs timeout, ready_input, ready_output, event, and outputv
10553 (when the port is used by distribution). Value Millis in tu‐
10554 ple timeout informs about the uninterrupted execution time
10555 of the process or port, which always is equal to or higher
10556 than the Time value supplied when starting the trace. New
10557 tuples can be added to the Info list in a future release.
10558 The order of the tuples in the list can be changed at any
10559 time without prior notice.
10560 This can be used to detect problems with NIFs or drivers
10562 that take too long to execute. 1 ms is considered a good
10563 maximum time for a driver callback or a NIF. However, a
10564 time-sharing system is usually to consider everything < 100
10565 ms as "possible" and fairly "normal". However, longer sched‐
10566 ule times can indicate swapping or a misbehaving NIF/driver.
10567 Misbehaving NIFs and drivers can cause bad resource utiliza‐
10568 tion and bad overall system performance.
10569 {large_heap, Size}:
10571 If a garbage collection in the system results in the allo‐
10572 cated size of a heap being at least Size words, a message
10573 {monitor, GcPid, large_heap, Info} is sent to MonitorPid.
10574 GcPid and Info are the same as for long_gc earlier, except
10575 that the tuple tagged with timeout is not present.
10576 The monitor message is sent if the sum of the sizes of all
10578 memory blocks allocated for all heap generations after a
10579 garbage collection is equal to or higher than Size.
10580 When a process is killed by max_heap_size, it is killed be‐
10582 fore the garbage collection is complete and thus no large
10583 heap message is sent.
10584 busy_port:
10586 If a process in the system gets suspended because it sends
10587 to a busy port, a message {monitor, SusPid, busy_port, Port}
10588 is sent to MonitorPid. SusPid is the pid that got suspended
10589 when sending to Port.
10590 busy_dist_port:
10592 If a process in the system gets suspended because it sends
10593 to a process on a remote node whose inter-node communication
10594 was handled by a busy port, a message {monitor, SusPid,
10595 busy_dist_port, Port} is sent to MonitorPid. SusPid is the
10596 pid that got suspended when sending through the inter-node
10597 communication port Port.
10598 Returns the previous system monitor settings just like er‐
10600 lang:system_monitor/0.
10601 The arguments to system_monitor/2 specifies how all system moni‐
10603 toring on the node should be done, not how it should be changed.
10604 This means only one process at a time (MonitorPid) can be the
10605 receiver of system monitor messages. Also, the way to clear a
10606 specific monitor option is to not include it in the list Op‐
10607 tions. All system monitoring will, however, be cleared if the
10608 process identified by MonitorPid terminates.
10609 There are no special option values (like zero) to clear an op‐
10611 tion. Some of the options have a unspecified minimum value.
10612 Lower values will be adjusted to the minimum value. For example,
10613 it is currently not possible to monitor all garbage collections
10614 with {long_gc, 0}.
10615 Note:
10617 If a monitoring process gets so large that it itself starts to
10618 cause system monitor messages when garbage collecting, the mes‐
10619 sages enlarge the process message queue and probably make the
10620 problem worse.
10621 Keep the monitoring process neat and do not set the system moni‐
10623 tor limits too tight.
10624 Failures:
10627 badarg:
10629 If MonitorPid does not exist.
10630 badarg:
10632 If MonitorPid is not a local process.
10633 erlang:system_profile() -> ProfilerSettings
10635 Types:
10637 ProfilerSettings = undefined | {ProfilerPid, Options}
10639 ProfilerPid = pid() | port()
10640 Options = [system_profile_option()]
10641 system_profile_option() =
10642 exclusive | runnable_ports | runnable_procs | scheduler |
10643 timestamp | monotonic_timestamp | strict_monotonic_timestamp
10644 Returns the current system profiling settings set by erlang:sys‐
10646 tem_profile/2 as {ProfilerPid, Options}, or undefined if there
10647 are no settings. The order of the options can be different from
10648 the one that was set.
10649 erlang:system_profile(ProfilerPid, Options) -> ProfilerSettings
10651 Types:
10653 ProfilerPid = pid() | port() | undefined
10655 Options = [system_profile_option()]
10656 ProfilerSettings =
10657 undefined | {pid() | port(), [system_profile_option()]}
10658 system_profile_option() =
10659 exclusive | runnable_ports | runnable_procs | scheduler |
10660 timestamp | monotonic_timestamp | strict_monotonic_timestamp
10661 Sets system profiler options. ProfilerPid is a local process
10663 identifier (pid) or port receiving profiling messages. The re‐
10664 ceiver is excluded from all profiling. The second argument is a
10665 list of profiling options:
10666 exclusive:
10668 If a synchronous call to a port from a process is done, the
10669 calling process is considered not runnable during the call
10670 runtime to the port. The calling process is notified as in‐
10671 active, and later active when the port callback returns.
10672 monotonic_timestamp:
10674 Time stamps in profile messages use Erlang monotonic time.
10675 The time stamp (Ts) has the same format and value as pro‐
10676 duced by erlang:monotonic_time(nanosecond).
10677 runnable_procs:
10679 If a process is put into or removed from the run queue, a
10680 message, {profile, Pid, State, Mfa, Ts}, is sent to Profil‐
10681 erPid. Running processes that are reinserted into the run
10682 queue after having been pre-empted do not trigger this mes‐
10683 sage.
10684 runnable_ports:
10686 If a port is put into or removed from the run queue, a mes‐
10687 sage, {profile, Port, State, 0, Ts}, is sent to ProfilerPid.
10688 scheduler:
10690 If a scheduler is put to sleep or awoken, a message, {pro‐
10691 file, scheduler, Id, State, NoScheds, Ts}, is sent to Pro‐
10692 filerPid.
10693 strict_monotonic_timestamp:
10695 Time stamps in profile messages consist of Erlang monotonic
10696 time and a monotonically increasing integer. The time stamp
10697 (Ts) has the same format and value as produced by {er‐
10698 lang:monotonic_time(nanosecond), erlang:unique_inte‐
10699 ger([monotonic])}.
10700 timestamp:
10702 Time stamps in profile messages include a time stamp (Ts)
10703 that has the same form as returned by erlang:now(). This is
10704 also the default if no time stamp flag is specified. If
10705 cpu_timestamp has been enabled through erlang:trace/3, this
10706 also effects the time stamp produced in profiling messages
10707 when flag timestamp is enabled.
10708 Note:
10710 erlang:system_profile behavior can change in a future release.
10711 erlang:system_time() -> integer()
10714 Returns current Erlang system time in native time unit.
10716 Calling erlang:system_time() is equivalent to erlang:mono‐
10718 tonic_time() + erlang:time_offset().
10719 Note:
10721 This time is not a monotonically increasing time in the general
10722 case. For more information, see the documentation of time warp
10723 modes in the User's Guide.
10724 erlang:system_time(Unit) -> integer()
10727 Types:
10729 Unit = time_unit()
10731 Returns current Erlang system time converted into the Unit
10733 passed as argument.
10734 Calling erlang:system_time(Unit) is equivalent to erlang:con‐
10736 vert_time_unit(erlang:system_time(), native, Unit).
10737 Note:
10739 This time is not a monotonically increasing time in the general
10740 case. For more information, see the documentation of time warp
10741 modes in the User's Guide.
10742 term_to_binary(Term) -> ext_binary()
10745 Types:
10747 Term = term()
10749 Returns a binary data object that is the result of encoding Term
10751 according to the Erlang external term format.
10752 This can be used for various purposes, for example, writing a
10754 term to a file in an efficient way, or sending an Erlang term to
10755 some type of communications channel not supported by distributed
10756 Erlang.
10757 > Bin = term_to_binary(hello).
10759 <<131,100,0,5,104,101,108,108,111>>
10760 > hello = binary_to_term(Bin).
10761 hello
10762 See also binary_to_term/1.
10765 Note:
10767 There is no guarantee that this function will return the same
10768 encoded representation for the same term.
10769 term_to_binary(Term, Options) -> ext_binary()
10772 Types:
10774 Term = term()
10776 Options =
10777 [compressed |
10778 {compressed, Level :: 0..9} |
10779 deterministic |
10780 {minor_version, Version :: 0..2} |
10781 local]
10782 Returns a binary data object that is the result of encoding Term
10784 according to the Erlang external term format.
10785 Currently supported options:
10787 compressed:
10789 Compress the external term format. The compressed format is
10790 automatically recognized by binary_to_term/1 as from Er‐
10791 lang/OTP R7B.
10792 {compressed, Level}:
10794 Compress the external term format to a given level. The com‐
10795 pression level is specified by Level which is an integer in
10796 the range 0..9, where:
10797 0:
10799 No compression is done (it is the same as giving no com‐
10800 pressed option).
10801 1:
10803 Takes least time but may not compress as well as the
10804 higher levels.
10805 6:
10807 Default level when option compressed is provided.
10808 9:
10810 Takes most time and tries to produce a smaller result. No‐
10811 tice "tries" in the preceding sentence; depending on the
10812 input term, level 9 compression either does or does not
10813 produce a smaller result than level 1 compression.
10814 {minor_version, Version}:
10816 The option can be used to control some encoding details.
10817 Valid values for Version are:
10818 0:
10820 Floats are encoded using a textual representation.
10821 Atoms that can be represented by a latin1 string are en‐
10823 coded using latin1 while only atoms that cannot be repre‐
10824 sented by latin1 are encoded using utf8.
10825 1:
10827 Floats are encoded in a more space-efficient and exact way
10828 (namely in the 64-bit IEEE format, rather than converted
10829 to a textual representation). As from Erlang/OTP R11B-4,
10830 binary_to_term/1 can decode this representation.
10831 Atoms that can be represented by a latin1 string are en‐
10833 coded using latin1 while only atoms that cannot be repre‐
10834 sented by latin1 are encoded using utf8.
10835 2:
10837 This is as of Erlang/OTP 26.0 the default. Atoms are un‐
10838 conditionally encoded using utf8. Erlang/OTP systems as of
10839 R16B can decode this representation.
10840 deterministic:
10842 This option can be used to ensure that, within the same ma‐
10843 jor release of Erlang/OTP, the same encoded representation
10844 is returned for the same term. There is still no guarantee
10845 that the encoded representation remains the same between ma‐
10846 jor releases of Erlang/OTP.
10847 This option cannot be combined with the local option.
10849 local:
10851 This option will cause encoding of Term to an alternative
10852 local version of the external term format which when decoded
10853 by the same runtime system instance will produce a term
10854 identical to the encoded term even when the node name and/or
10855 creation of the current runtime system instance have changed
10856 between encoding and decoding. When encoding without the lo‐
10857 cal option, local identifiers such as pids, ports and refer‐
10858 ences will not be the same if node name and/or creation of
10859 the current runtime system instance changed between encoding
10860 and decoding. This since such identifiers refer to a spe‐
10861 cific node by node name and creation.
10862 Node name and creation of a runtime system instance change
10864 when the distribution is started or stopped. The distribu‐
10865 tion is started when the runtime system is started using the
10866 -name or -sname command line arguments. Note that the actual
10867 start of the distribution happens after other code in the
10868 startup phase has begun executing. The distribution can also
10869 be started by calling net_kernel:start/2 and stopped by
10870 calling net_kernel:stop/1 if it has not been started via the
10871 command line.
10872 The decoding of a term encoded with the local option, using
10874 for example binary_to_term(), will try to verify that the
10875 term actually was encoded by the same runtime system in‐
10876 stance, and will in the vast majority of cases fail if the
10877 encoding was performed by another runtime system instance.
10878 You should however not trust that this verification will
10879 work in all cases. You should make sure to only decode terms
10880 encoded with the local option on the same Erlang runtime
10881 system instance as the one that encoded the terms.
10882 Since it is only the runtime system that encoded a term us‐
10884 ing the local option that can decode it, the local encoding
10885 is typically pieced together with something else to produce
10886 a reply to where the local encoding originates from. If a
10887 term encoded using the local option is stripped of its lead‐
10888 ing version number, it can be added as part of a larger term
10889 (for example as an element in a tuple) when encoding on the
10890 external term format using, for example, ei. In the ei case,
10891 you would strip it of the version number using ei_de‐
10892 code_version() and then add the remaining local encoding to
10893 what you are encoding using for example ei_x_append_buf().
10894 A good example of when you want to use the local option, is
10896 when you want to make a request from a process to a port
10897 driver and utilize the selective receive optimization when
10898 receiving the reply. In this scenario you want to create a
10899 reference, serialize the reference on the external term for‐
10900 mat using the local option, pass this to the driver in the
10901 request, and then wait for the reply message in a selective
10902 receive matching on the reference. The driver should send
10903 the reply using either erl_drv_output_term() or
10904 erl_drv_send_term() using the term type ERL_DRV_EXT2TERM for
10905 the, in the request, previously received reference on the
10906 external term format. Note that you should not strip the
10907 leading version number from the local encoding when using
10908 the term type ERL_DRV_EXT2TERM of this functionality. If you
10909 in this example do not encode the reference using the local
10910 option, and the distribution is started or stopped while the
10911 request is ongoing, the process that made the request will
10912 hang indefinitely since the reference in the reply message
10913 will never match.
10914 This option cannot be combined with the deterministic op‐
10916 tion.
10917 For more information see the LOCAL_EXT tag in the documenta‐
10919 tion of the external term format.
10920 See also binary_to_term/1.
10922 term_to_iovec(Term) -> ext_iovec()
10924 Types:
10926 Term = term()
10928 Returns the encoding of Term according to the Erlang external
10930 term format as ext_iovec().
10931 This function produce the same encoding as term_to_binary/1, but
10933 with another return type. The call iolist_to_bi‐
10934 nary(term_to_iovec(Term)) will produce exactly the same result
10935 as the call term_to_binary(Term).
10936 term_to_iovec() is a pure optimization of the functionality
10938 term_to_binary() provide. term_to_iovec() can for example refer
10939 directly to off heap binaries instead of copying the binary data
10940 into the result.
10941 See also term_to_binary/1.
10943 term_to_iovec(Term, Options) -> ext_iovec()
10945 Types:
10947 Term = term()
10949 Options =
10950 [compressed |
10951 {compressed, Level :: 0..9} |
10952 deterministic |
10953 {minor_version, Version :: 0..2} |
10954 local]
10955 Returns the encoding of Term according to the Erlang external
10957 term format as ext_iovec().
10958 This function produce the same encoding as term_to_binary/2, but
10960 with another return type. The call iolist_to_bi‐
10961 nary(term_to_iovec(Term, Opts)) will produce exactly the same
10962 result as term_to_binary(Term, Opts).
10963 Currently recognised options are all options recognised by
10965 term_to_binary/2.
10966 term_to_iovec() is a pure optimization of the functionality
10968 term_to_binary() provide. term_to_iovec() can for example refer
10969 directly to off heap binaries instead of copying the binary data
10970 into the result.
10971 See also term_to_binary/2.
10973 throw(Any) -> no_return()
10975 Types:
10977 Any = term()
10979 Raises an exception of class throw. Intended to be used to do
10981 non-local returns from functions.
10982 If evaluated within a catch expression, the catch expression
10984 returns value Any. Example:
10985 > catch throw({hello, there}).
10987 {hello,there}
10988 If evaluated within a try-block of a try expression, the value
10990 Any can be caught within the catch block. Example:
10991 try
10993 throw({my_exception, "Something happened"})
10994 catch
10995 throw:{my_exception, Desc} ->
10996 io:format(standard_error, "Error: ~s~n", [Desc])
10997 end
10998 Failure: nocatch if not caught by an exception handler.
11000 See the guide about errors and error handling for additional in‐
11002 formation.
11003 time() -> Time
11005 Types:
11007 Time = calendar:time()
11009 Returns the current time as {Hour, Minute, Second}.
11011 The time zone and Daylight Saving Time correction depend on the
11013 underlying OS. The return value is based on the OS System Time.
11014 Example:
11015 > time().
11017 {9,42,44}
11018 erlang:time_offset() -> integer()
11020 Returns the current time offset between Erlang monotonic time
11022 and Erlang system time in native time unit. Current time offset
11023 added to an Erlang monotonic time gives corresponding Erlang
11024 system time.
11025 The time offset may or may not change during operation depending
11027 on the time warp mode used.
11028 Note:
11030 A change in time offset can be observed at slightly different
11031 points in time by different processes.
11032 If the runtime system is in multi-time warp mode, the time off‐
11034 set is changed when the runtime system detects that the OS sys‐
11035 tem time has changed. The runtime system will, however, not de‐
11036 tect this immediately when it occurs. A task checking the time
11037 offset is scheduled to execute at least once a minute; so, under
11038 normal operation this is to be detected within a minute, but
11039 during heavy load it can take longer time.
11040 erlang:time_offset(Unit) -> integer()
11043 Types:
11045 Unit = time_unit()
11047 Returns the current time offset between Erlang monotonic time
11049 and Erlang system time converted into the Unit passed as argu‐
11050 ment.
11051 Same as calling erlang:convert_time_unit(erlang:time_offset(),
11053 native, Unit) however optimized for commonly used Units.
11054 erlang:timestamp() -> Timestamp
11056 Types:
11058 Timestamp = timestamp()
11060 timestamp() =
11061 {MegaSecs :: integer() >= 0,
11062 Secs :: integer() >= 0,
11063 MicroSecs :: integer() >= 0}
11064 Returns current Erlang system time on the format {MegaSecs,
11066 Secs, MicroSecs}. This format is the same as os:timestamp/0 and
11067 the deprecated erlang:now/0 use. The reason for the existence of
11068 erlang:timestamp() is purely to simplify use for existing code
11069 that assumes this time stamp format. Current Erlang system time
11070 can more efficiently be retrieved in the time unit of your
11071 choice using erlang:system_time/1.
11072 The erlang:timestamp() BIF is equivalent to:
11074 timestamp() ->
11076 ErlangSystemTime = erlang:system_time(microsecond),
11077 MegaSecs = ErlangSystemTime div 1000_000_000_000,
11078 Secs = ErlangSystemTime div 1000_000 - MegaSecs*1000_000,
11079 MicroSecs = ErlangSystemTime rem 1000_000,
11080 {MegaSecs, Secs, MicroSecs}.
11081 It, however, uses a native implementation that does not build
11083 garbage on the heap and with slightly better performance.
11084 Note:
11086 This time is not a monotonically increasing time in the general
11087 case. For more information, see the documentation of time warp
11088 modes in the User's Guide.
11089 tl(List) -> Tail
11092 Types:
11094 List = nonempty_maybe_improper_list()
11096 Tail = term()
11097 Returns the tail of List, that is, the list minus the first ele‐
11099 ment
11100 It works with improper lists.
11102 Examples:
11104 > tl([geesties, guilies, beasties]).
11106 [guilies, beasties]
11107 > tl([geesties]).
11109 []
11110 > tl([geesties, guilies, beasties | improper_end]).
11112 [guilies, beasties | improper_end]
11113 > tl([geesties | improper_end]).
11115 improper_end
11116 Allowed in guard tests.
11118 Failure: badarg if List is an empty list [].
11120 erlang:trace(PidPortSpec, How, FlagList) -> integer()
11122 Types:
11124 PidPortSpec =
11126 pid() |
11127 port() |
11128 all | processes | ports | existing | existing_processes |
11129 existing_ports | new | new_processes | new_ports
11130 How = boolean()
11131 FlagList = [trace_flag()]
11132 trace_flag() =
11133 all | send | 'receive' | procs | ports | call | arity |
11134 return_to | silent | running | exiting | running_procs |
11135 running_ports | garbage_collection | timestamp |
11136 cpu_timestamp | monotonic_timestamp |
11137 strict_monotonic_timestamp | set_on_spawn |
11138 set_on_first_spawn | set_on_link | set_on_first_link |
11139 {tracer, pid() | port()} |
11140 {tracer, module(), term()}
11141 Turns on (if How == true) or off (if How == false) the trace
11143 flags in FlagList for the process or processes represented by
11144 PidPortSpec.
11145 PidPortSpec is either a process identifier (pid) for a local
11147 process, a port identifier, or one of the following atoms:
11148 all:
11150 All currently existing processes and ports and all that will
11151 be created in the future.
11152 processes:
11154 All currently existing processes and all that will be cre‐
11155 ated in the future.
11156 ports:
11158 All currently existing ports and all that will be created in
11159 the future.
11160 existing:
11162 All currently existing processes and ports.
11163 existing_processes:
11165 All currently existing processes.
11166 existing_ports:
11168 All currently existing ports.
11169 new:
11171 All processes and ports that will be created in the future.
11172 new_processes:
11174 All processes that will be created in the future.
11175 new_ports:
11177 All ports that will be created in the future.
11178 FlagList can contain any number of the following flags (the
11180 "message tags" refers to the list of trace messages):
11181 all:
11183 Sets all trace flags except tracer and cpu_timestamp, which
11184 are in their nature different than the others.
11185 send:
11187 Traces sending of messages.
11188 Message tags: send and send_to_non_existing_process.
11190 'receive':
11192 Traces receiving of messages.
11193 Message tags: 'receive'.
11195 call:
11197 Traces certain function calls. Specify which function calls
11198 to trace by calling erlang:trace_pattern/3.
11199 Message tags: call and return_from.
11201 silent:
11203 Used with the call trace flag. The call, return_from, and
11204 return_to trace messages are inhibited if this flag is set,
11205 but they are executed as normal if there are match specifi‐
11206 cations.
11207 Silent mode is inhibited by executing erlang:trace(_, false,
11209 [silent|_]), or by a match specification executing the func‐
11210 tion {silent, false}.
11211 The silent trace flag facilitates setting up a trace on many
11213 or even all processes in the system. The trace can then be
11214 activated and deactivated using the match specification
11215 function {silent,Bool}, giving a high degree of control of
11216 which functions with which arguments that trigger the trace.
11217 Message tags: call, return_from, and return_to. Or rather,
11219 the absence of.
11220 return_to:
11222 Used with the call trace flag. Traces the return from a
11223 traced function back to its caller. Only works for functions
11224 traced with option local to erlang:trace_pattern/3.
11225 The semantics is that a trace message is sent when a call
11227 traced function returns, that is, when a chain of tail re‐
11228 cursive calls ends. Only one trace message is sent per chain
11229 of tail recursive calls, so the properties of tail recur‐
11230 siveness for function calls are kept while tracing with this
11231 flag. Using call and return_to trace together makes it pos‐
11232 sible to know exactly in which function a process executes
11233 at any time.
11234 To get trace messages containing return values from func‐
11236 tions, use the {return_trace} match specification action in‐
11237 stead.
11238 Message tags: return_to.
11240 procs:
11242 Traces process-related events.
11243 Message tags: spawn, spawned, exit, register, unregister,
11245 link, unlink, getting_linked, and getting_unlinked.
11246 ports:
11248 Traces port-related events.
11249 Message tags: open, closed, register, unregister, get‐
11251 ting_linked, and getting_unlinked.
11252 running:
11254 Traces scheduling of processes.
11255 Message tags: in and out.
11257 exiting:
11259 Traces scheduling of exiting processes.
11260 Message tags: in_exiting, out_exiting, and out_exited.
11262 running_procs:
11264 Traces scheduling of processes just like running. However,
11265 this option also includes schedule events when the process
11266 executes within the context of a port without being sched‐
11267 uled out itself.
11268 Message tags: in and out.
11270 running_ports:
11272 Traces scheduling of ports.
11273 Message tags: in and out.
11275 garbage_collection:
11277 Traces garbage collections of processes.
11278 Message tags: gc_minor_start, gc_max_heap_size, and gc_mi‐
11280 nor_end.
11281 timestamp:
11283 Includes a time stamp in all trace messages. The time stamp
11284 (Ts) has the same form as returned by erlang:now().
11285 cpu_timestamp:
11287 A global trace flag for the Erlang node that makes all trace
11288 time stamps using flag timestamp to be in CPU time, not wall
11289 clock time. That is, cpu_timestamp is not be used if mono‐
11290 tonic_timestamp or strict_monotonic_timestamp is enabled.
11291 Only allowed with PidPortSpec==all. If the host machine OS
11292 does not support high-resolution CPU time measurements,
11293 trace/3 exits with badarg. Notice that most OS do not syn‐
11294 chronize this value across cores, so be prepared that time
11295 can seem to go backwards when using this option.
11296 monotonic_timestamp:
11298 Includes an Erlang monotonic time time stamp in all trace
11299 messages. The time stamp (Ts) has the same format and value
11300 as produced by erlang:monotonic_time(nanosecond). This flag
11301 overrides flag cpu_timestamp.
11302 strict_monotonic_timestamp:
11304 Includes an time stamp consisting of Erlang monotonic time
11305 and a monotonically increasing integer in all trace mes‐
11306 sages. The time stamp (Ts) has the same format and value as
11307 produced by { erlang:monotonic_time(nanosecond), er‐
11308 lang:unique_integer([monotonic])}. This flag overrides flag
11309 cpu_timestamp.
11310 arity:
11312 Used with the call trace flag. {M, F, Arity} is specified
11313 instead of {M, F, Args} in call trace messages.
11314 set_on_spawn:
11316 Makes any process created by a traced process inherit its
11317 trace flags, including flag set_on_spawn.
11318 set_on_first_spawn:
11320 Makes the first process created by a traced process inherit
11321 its trace flags, excluding flag set_on_first_spawn.
11322 set_on_link:
11324 Makes any process linked by a traced process inherit its
11325 trace flags, including flag set_on_link.
11326 set_on_first_link:
11328 Makes the first process linked to by a traced process in‐
11329 herit its trace flags, excluding flag set_on_first_link.
11330 {tracer, Tracer}:
11332 Specifies where to send the trace messages. Tracer must be
11333 the process identifier of a local process or the port iden‐
11334 tifier of a local port.
11335 {tracer, TracerModule, TracerState}:
11337 Specifies that a tracer module is to be called instead of
11338 sending a trace message. The tracer module can then ignore
11339 or change the trace message. For more details on how to
11340 write a tracer module, see erl_tracer(3).
11341 If no tracer is specified, the calling process receives all the
11343 trace messages.
11344 The effect of combining set_on_first_link with set_on_link is
11346 the same as set_on_first_link alone. Likewise for set_on_spawn
11347 and set_on_first_spawn.
11348 The tracing process receives the trace messages described in the
11350 following list. Pid is the process identifier of the traced
11351 process in which the traced event has occurred. The third tuple
11352 element is the message tag.
11353 If flag timestamp, strict_monotonic_timestamp, or mono‐
11355 tonic_timestamp is specified, the first tuple element is
11356 trace_ts instead, and the time stamp is added as an extra ele‐
11357 ment last in the message tuple. If multiple time stamp flags are
11358 passed, timestamp has precedence over strict_monotonic_time‐
11359 stamp, which in turn has precedence over monotonic_timestamp.
11360 All time stamp flags are remembered, so if two are passed and
11361 the one with highest precedence later is disabled, the other one
11362 becomes active.
11363 If a match specification (applicable only for call, send and
11365 'receive' tracing) contains a {message} action function with a
11366 non-boolean value, that value is added as an extra element to
11367 the message tuple either in the last position or before the
11368 timestamp (if it is present).
11369 Trace messages:
11371 {trace, PidPort, send, Msg, To}:
11373 When PidPort sends message Msg to process To.
11374 {trace, PidPort, send_to_non_existing_process, Msg, To}:
11376 When PidPort sends message Msg to the non-existing process
11377 To.
11378 {trace, PidPort, 'receive', Msg}:
11380 When PidPort receives message Msg. If Msg is set to time-
11381 out, a receive statement can have timed out, or the process
11382 received a message with the payload timeout.
11383 {trace, Pid, call, {M, F, Args}}:
11385 When Pid calls a traced function. The return values of calls
11386 are never supplied, only the call and its arguments.
11387 Trace flag arity can be used to change the contents of this
11389 message, so that Arity is specified instead of Args.
11390 {trace, Pid, return_to, {M, F, Arity}}:
11392 When Pid returns to the specified function. This trace mes‐
11393 sage is sent if both the flags call and return_to are set,
11394 and the function is set to be traced on local function
11395 calls. The message is only sent when returning from a chain
11396 of tail recursive function calls, where at least one call
11397 generated a call trace message (that is, the functions match
11398 specification matched, and {message, false} was not an ac‐
11399 tion).
11400 {trace, Pid, return_from, {M, F, Arity}, ReturnValue}:
11402 When Pid returns from the specified function. This trace
11403 message is sent if flag call is set, and the function has a
11404 match specification with a return_trace or exception_trace
11405 action.
11406 {trace, Pid, exception_from, {M, F, Arity}, {Class, Value}}:
11408 When Pid exits from the specified function because of an ex‐
11409 ception. This trace message is sent if flag call is set, and
11410 the function has a match specification with an excep‐
11411 tion_trace action.
11412 {trace, Pid, spawn, Pid2, {M, F, Args}}:
11414 When Pid spawns a new process Pid2 with the specified func‐
11415 tion call as entry point.
11416 Args is supposed to be the argument list, but can be any
11418 term if the spawn is erroneous.
11419 {trace, Pid, spawned, Pid2, {M, F, Args}}:
11421 When Pid is spawned by process Pid2 with the specified func‐
11422 tion call as entry point.
11423 Args is supposed to be the argument list, but can be any
11425 term if the spawn is erroneous.
11426 {trace, Pid, exit, Reason}:
11428 When Pid exits with reason Reason.
11429 {trace, PidPort, register, RegName}:
11431 When PidPort gets the name RegName registered.
11432 {trace, PidPort, unregister, RegName}:
11434 When PidPort gets the name RegName unregistered. This is
11435 done automatically when a registered process or port exits.
11436 {trace, Pid, link, Pid2}:
11438 When Pid links to a process Pid2.
11439 {trace, Pid, unlink, Pid2}:
11441 When Pid removes the link from a process Pid2.
11442 {trace, PidPort, getting_linked, Pid2}:
11444 When PidPort gets linked to a process Pid2.
11445 {trace, PidPort, getting_unlinked, Pid2}:
11447 When PidPort gets unlinked from a process Pid2.
11448 {trace, Port, open, Pid, Driver}:
11450 When Pid opens a new port Port with the running Driver.
11451 Driver is the name of the driver as an atom.
11453 {trace, Port, closed, Reason}:
11455 When Port closes with Reason.
11456 {trace, Pid, in | in_exiting, {M, F, Arity} | 0}:
11458 When Pid is scheduled to run. The process runs in function
11459 {M, F, Arity}. On some rare occasions, the current function
11460 cannot be determined, then the last element is 0.
11461 {trace, Pid, out | out_exiting | out_exited, {M, F, Arity} |
11463 0}:
11464 When Pid is scheduled out. The process was running in func‐
11465 tion {M, F, Arity}. On some rare occasions, the current
11466 function cannot be determined, then the last element is 0.
11467 {trace, Port, in, Command | 0}:
11469 When Port is scheduled to run. Command is the first thing
11470 the port will execute, it can however run several commands
11471 before being scheduled out. On some rare occasions, the cur‐
11472 rent function cannot be determined, then the last element is
11473 0.
11474 The possible commands are call, close, command, connect,
11476 control, flush, info, link, open, and unlink.
11477 {trace, Port, out, Command | 0}:
11479 When Port is scheduled out. The last command run was Com‐
11480 mand. On some rare occasions, the current function cannot be
11481 determined, then the last element is 0. Command can contain
11482 the same commands as in
11483 {trace, Pid, gc_minor_start, Info}:
11485 Sent when a young garbage collection is about to be started.
11488 Info is a list of two-element tuples, where the first ele‐
11489 ment is a key, and the second is the value. Do not depend on
11490 any order of the tuples. The following keys are defined:
11491 heap_size:
11493 The size of the used part of the heap.
11494 heap_block_size:
11496 The size of the memory block used for storing the heap and
11497 the stack.
11498 old_heap_size:
11500 The size of the used part of the old heap.
11501 old_heap_block_size:
11503 The size of the memory block used for storing the old
11504 heap.
11505 stack_size:
11507 The size of the stack.
11508 recent_size:
11510 The size of the data that survived the previous garbage
11511 collection.
11512 mbuf_size:
11514 The combined size of message buffers associated with the
11515 process.
11516 bin_vheap_size:
11518 The total size of unique off-heap binaries referenced from
11519 the process heap.
11520 bin_vheap_block_size:
11522 The total size of binaries allowed in the virtual heap in
11523 the process before doing a garbage collection.
11524 bin_old_vheap_size:
11526 The total size of unique off-heap binaries referenced from
11527 the process old heap.
11528 bin_old_vheap_block_size:
11530 The total size of binaries allowed in the virtual old heap
11531 in the process before doing a garbage collection.
11532 wordsize:
11534 For the gc_minor_start event it is the size of the need
11535 that triggered the GC. For the corresponding gc_minor_end
11536 event it is the size of reclaimed memory = start heap_size
11537 - end heap_size.
11538 All sizes are in words.
11540 {trace, Pid, gc_max_heap_size, Info}:
11542 Sent when the max_heap_size is reached during garbage col‐
11543 lection. Info contains the same kind of list as in message
11544 gc_start, but the sizes reflect the sizes that triggered
11545 max_heap_size to be reached.
11546 {trace, Pid, gc_minor_end, Info}:
11548 Sent when young garbage collection is finished. Info con‐
11549 tains the same kind of list as in message gc_minor_start,
11550 but the sizes reflect the new sizes after garbage collec‐
11551 tion.
11552 {trace, Pid, gc_major_start, Info}:
11554 Sent when fullsweep garbage collection is about to be
11555 started. Info contains the same kind of list as in message
11556 gc_minor_start.
11557 {trace, Pid, gc_major_end, Info}:
11559 Sent when fullsweep garbage collection is finished. Info
11560 contains the same kind of list as in message gc_minor_start,
11561 but the sizes reflect the new sizes after a fullsweep
11562 garbage collection.
11563 If the tracing process/port dies or the tracer module returns
11565 remove, the flags are silently removed.
11566 Each process can only be traced by one tracer. Therefore, at‐
11568 tempts to trace an already traced process fail.
11569 Returns a number indicating the number of processes that matched
11571 PidPortSpec. If PidPortSpec is a process identifier, the return
11572 value is 1. If PidPortSpec is all or existing, the return value
11573 is the number of processes running. If PidPortSpec is new, the
11574 return value is 0.
11575 Failure: badarg if the specified arguments are not supported.
11577 For example, cpu_timestamp is not supported on all platforms.
11578 erlang:trace_delivered(Tracee) -> Ref
11580 Types:
11582 Tracee = pid() | all
11584 Ref = reference()
11585 The delivery of trace messages (generated by erlang:trace/3,
11587 seq_trace(3), or erlang:system_profile/2) is dislocated on the
11588 time-line compared to other events in the system. If you know
11589 that Tracee has passed some specific point in its execution, and
11590 you want to know when at least all trace messages corresponding
11591 to events up to this point have reached the tracer, use er‐
11592 lang:trace_delivered(Tracee).
11593 When it is guaranteed that all trace messages are delivered to
11595 the tracer up to the point that Tracee reached at the time of
11596 the call to erlang:trace_delivered(Tracee), then a {trace_deliv‐
11597 ered, Tracee, Ref} message is sent to the caller of er‐
11598 lang:trace_delivered(Tracee) .
11599 Notice that message trace_delivered does not imply that trace
11601 messages have been delivered. Instead it implies that all trace
11602 messages that are to be delivered have been delivered. It is not
11603 an error if Tracee is not, and has not been traced by someone,
11604 but if this is the case, no trace messages have been delivered
11605 when the trace_delivered message arrives.
11606 Notice that Tracee must refer to a process currently or previ‐
11608 ously existing on the same node as the caller of er‐
11609 lang:trace_delivered(Tracee) resides on. The special Tracee atom
11610 all denotes all processes that currently are traced in the node.
11611 When used together with a Tracer Module, any message sent in
11613 the trace callback is guaranteed to have reached its recipient
11614 before the trace_delivered message is sent.
11615 Example: Process A is Tracee, port B is tracer, and process C is
11617 the port owner of B. C wants to close B when A exits. To ensure
11618 that the trace is not truncated, C can call erlang:trace_deliv‐
11619 ered(A) when A exits, and wait for message {trace_delivered, A,
11620 Ref} before closing B.
11621 Failure: badarg if Tracee does not refer to a process (dead or
11623 alive) on the same node as the caller of erlang:trace_deliv‐
11624 ered(Tracee) resides on.
11625 erlang:trace_info(PidPortFuncEvent, Item) -> Res
11627 Types:
11629 PidPortFuncEvent =
11631 pid() |
11632 port() |
11633 new | new_processes | new_ports |
11634 {Module, Function, Arity} |
11635 on_load | send | 'receive'
11636 Module = module()
11637 Function = atom()
11638 Arity = arity()
11639 Item =
11640 flags | tracer | traced | match_spec | meta |
11641 meta_match_spec | call_count | call_time | call_memory |
11642 all
11643 Res = trace_info_return()
11644 trace_info_return() =
11645 undefined |
11646 {flags, [trace_info_flag()]} |
11647 {tracer, pid() | port() | []} |
11648 {tracer, module(), term()} |
11649 trace_info_item_result() |
11650 {all, [trace_info_item_result()] | false | undefined}
11651 trace_info_item_result() =
11652 {traced, global | local | false | undefined} |
11653 {match_spec, trace_match_spec() | false | undefined} |
11654 {meta, pid() | port() | false | undefined | []} |
11655 {meta, module(), term()} |
11656 {meta_match_spec, trace_match_spec() | false | undefined} |
11657 {call_count, integer() >= 0 | boolean() | undefined} |
11658 {call_time | call_memory,
11659 [{pid(),
11660 integer() >= 0,
11661 integer() >= 0,
11662 integer() >= 0}] |
11663 boolean() |
11664 undefined}
11665 trace_info_flag() =
11666 send | 'receive' | set_on_spawn | call | return_to | procs |
11667 set_on_first_spawn | set_on_link | running |
11668 garbage_collection | timestamp | monotonic_timestamp |
11669 strict_monotonic_timestamp | arity
11670 trace_match_spec() =
11671 [{[term()] | '_' | match_variable(), [term()], [term()]}]
11672 match_variable() = atom()
11673 Approximation of '$1' | '$2' | '$3' | ...
11674 Returns trace information about a port, process, function, or
11676 event.
11677 To get information about a port or process, PidPortFuncEvent is
11679 to be a process identifier (pid), port identifier, or one of the
11680 atoms new, new_processes, or new_ports. The atom new or new_pro‐
11681 cesses means that the default trace state for processes to be
11682 created is returned. The atom new_ports means that the default
11683 trace state for ports to be created is returned.
11684 Valid Items for ports and processes:
11686 flags:
11688 Returns a list of atoms indicating what kind of traces is
11689 enabled for the process. The list is empty if no traces are
11690 enabled, and one or more of the following atoms if traces
11691 are enabled: send, 'receive', set_on_spawn, call, return_to,
11692 procs, ports, set_on_first_spawn, set_on_link, running, run‐
11693 ning_procs, running_ports, silent, exiting, monotonic_time‐
11694 stamp, strict_monotonic_timestamp, garbage_collection, time‐
11695 stamp, and arity. The order is arbitrary.
11696 tracer:
11698 Returns the identifier for process, port, or a tuple con‐
11699 taining the tracer module and tracer state tracing this
11700 process. If this process is not traced, the return value is
11701 [].
11702 To get information about a function, PidPortFuncEvent is to be
11704 the three-element tuple {Module, Function, Arity} or the atom
11705 on_load. No wildcards are allowed. Returns undefined if the
11706 function does not exist, or false if the function is not traced.
11707 If PidPortFuncEvent is on_load, the information returned refers
11708 to the default value for code that will be loaded.
11709 Valid Items for functions:
11711 traced:
11713 Returns global if this function is traced on global function
11714 calls, local if this function is traced on local function
11715 calls (that is, local and global function calls), and false
11716 if local or global function calls are not traced.
11717 match_spec:
11719 Returns the match specification for this function, if it has
11720 one. If the function is locally or globally traced but has
11721 no match specification defined, the returned value is [].
11722 meta:
11724 Returns the meta-trace tracer process, port, or trace module
11725 for this function, if it has one. If the function is not
11726 meta-traced, the returned value is false. If the function is
11727 meta-traced but has once detected that the tracer process is
11728 invalid, the returned value is [].
11729 meta_match_spec:
11731 Returns the meta-trace match specification for this func‐
11732 tion, if it has one. If the function is meta-traced but has
11733 no match specification defined, the returned value is [].
11734 call_count:
11736 Returns the call count value for this function or true for
11737 the pseudo function on_load if call count tracing is active.
11738 Otherwise false is returned.
11739 See also erlang:trace_pattern/3.
11741 call_time:
11743 Returns the call time values for this function or true for
11744 the pseudo function on_load if call time tracing is active.
11745 Otherwise false is returned. The call time values returned,
11746 [{Pid, Count, S, Us}], is a list of each process that exe‐
11747 cuted the function and its specific counters.
11748 See also erlang:trace_pattern/3.
11750 call_memory:
11752 Returns the accumulated number of words allocated by this
11753 function. Accumulation stops at the next memory traced func‐
11754 tion: if there are outer, middle and inner functions each
11755 allocating 3 words, but only outer is traced, it will report
11756 9 allocated words. If outer and inner are traced, 6 words
11757 are reported for outer and 3 for inner. When function is not
11758 traced, false is returned. Returned tuple is [{Pid, Count,
11759 Words}], for each process that executed the function.
11760 See also erlang:trace_pattern/3.
11762 all:
11764 Returns a list containing the {Item, Value} tuples for all
11765 other items, or returns false if no tracing is active for
11766 this function.
11767 To get information about an event, PidPortFuncEvent is to be one
11769 of the atoms send or 'receive'.
11770 One valid Item for events exists:
11772 match_spec:
11774 Returns the match specification for this event, if it has
11775 one, or true if no match specification has been set.
11776 The return value is {Item, Value}, where Value is the requested
11778 information as described earlier. If a pid for a dead process
11779 was specified, or the name of a non-existing function, Value is
11780 undefined.
11781 erlang:trace_pattern(MFA, MatchSpec) -> integer() >= 0
11783 Types:
11785 MFA = trace_pattern_mfa() | send | 'receive'
11787 MatchSpec =
11788 (MatchSpecList :: trace_match_spec()) |
11789 boolean() |
11790 restart | pause
11791 trace_pattern_mfa() = {atom(), atom(), arity() | '_'} | on_load
11792 trace_match_spec() =
11793 [{[term()] | '_' | match_variable(), [term()], [term()]}]
11794 match_variable() = atom()
11795 Approximation of '$1' | '$2' | '$3' | ...
11796 The same as erlang:trace_pattern(Event, MatchSpec, []), retained
11798 for backward compatibility.
11799 erlang:trace_pattern(MFA :: send, MatchSpec, FlagList :: []) ->
11801 integer() >= 0
11802 Types:
11804 MatchSpec = (MatchSpecList :: trace_match_spec()) | boolean()
11806 trace_match_spec() =
11807 [{[term()] | '_' | match_variable(), [term()], [term()]}]
11808 match_variable() = atom()
11809 Approximation of '$1' | '$2' | '$3' | ...
11810 Sets trace pattern for message sending. Must be combined with
11812 erlang:trace/3 to set the send trace flag for one or more pro‐
11813 cesses. By default all messages sent from send traced processes
11814 are traced. To limit traced send events based on the message
11815 content, the sender and/or the receiver, use erlang:trace_pat‐
11816 tern/3.
11817 Argument MatchSpec can take the following forms:
11819 MatchSpecList:
11821 A list of match specifications. The matching is done on the
11822 list [Receiver, Msg]. Receiver is the process or port iden‐
11823 tity of the receiver and Msg is the message term. The pid of
11824 the sending process can be accessed with the guard function
11825 self/0. An empty list is the same as true. For more informa‐
11826 tion, see section Match Specifications in Erlang in the
11827 User's Guide.
11828 true:
11830 Enables tracing for all sent messages (from send traced pro‐
11831 cesses). Any match specification is removed. This is the de‐
11832 fault.
11833 false:
11835 Disables tracing for all sent messages. Any match specifica‐
11836 tion is removed.
11837 Argument FlagList must be [] for send tracing.
11839 The return value is always 1.
11841 Examples:
11843 Only trace messages to a specific process Pid:
11845 > erlang:trace_pattern(send, [{[Pid, '_'],[],[]}], []).
11847 1
11848 Only trace messages matching {reply, _}:
11850 > erlang:trace_pattern(send, [{['_', {reply,'_'}],[],[]}], []).
11852 1
11853 Only trace messages sent to the sender itself:
11855 > erlang:trace_pattern(send, [{['$1', '_'],[{'=:=','$1',{self}}],[]}], []).
11857 1
11858 Only trace messages sent to other nodes:
11860 > erlang:trace_pattern(send, [{['$1', '_'],[{'=/=',{node,'$1'},{node}}],[]}], []).
11862 1
11863 Note:
11865 A match specification for send trace can use all guard and body
11866 functions except caller.
11867 Fails by raising an error exception with an error reason of:
11870 badarg:
11872 If an argument is invalid.
11873 system_limit:
11875 If a match specification passed as argument has excessive
11876 nesting which causes scheduler stack exhaustion for the
11877 scheduler that the calling process is executing on. Sched‐
11878 uler stack size can be configured when starting the runtime
11879 system.
11880 erlang:trace_pattern(MFA :: 'receive', MatchSpec, FlagList :: []) ->
11882 integer() >= 0
11883 Types:
11885 MatchSpec = (MatchSpecList :: trace_match_spec()) | boolean()
11887 trace_match_spec() =
11888 [{[term()] | '_' | match_variable(), [term()], [term()]}]
11889 match_variable() = atom()
11890 Approximation of '$1' | '$2' | '$3' | ...
11891 Sets trace pattern for message receiving. Must be combined with
11893 erlang:trace/3 to set the 'receive' trace flag for one or more
11894 processes. By default all messages received by 'receive' traced
11895 processes are traced. To limit traced receive events based on
11896 the message content, the sender and/or the receiver, use er‐
11897 lang:trace_pattern/3.
11898 Argument MatchSpec can take the following forms:
11900 MatchSpecList:
11902 A list of match specifications. The matching is done on the
11903 list [Node, Sender, Msg]. Node is the node name of the
11904 sender. Sender is the process or port identity of the
11905 sender, or the atom undefined if the sender is not known
11906 (which can be the case for remote senders). Msg is the mes‐
11907 sage term. The pid of the receiving process can be accessed
11908 with the guard function self/0. An empty list is the same as
11909 true. For more information, see section Match Specifica‐
11910 tions in Erlang in the User's Guide.
11911 true:
11913 Enables tracing for all received messages (to 'receive'
11914 traced processes). Any match specification is removed. This
11915 is the default.
11916 false:
11918 Disables tracing for all received messages. Any match speci‐
11919 fication is removed.
11920 Argument FlagList must be [] for receive tracing.
11922 The return value is always 1.
11924 Examples:
11926 Only trace messages from a specific process Pid:
11928 > erlang:trace_pattern('receive', [{['_',Pid, '_'],[],[]}], []).
11930 1
11931 Only trace messages matching {reply, _}:
11933 > erlang:trace_pattern('receive', [{['_','_', {reply,'_'}],[],[]}], []).
11935 1
11936 Only trace messages from other nodes:
11938 > erlang:trace_pattern('receive', [{['$1', '_', '_'],[{'=/=','$1',{node}}],[]}], []).
11940 1
11941 Note:
11943 A match specification for 'receive' trace can use all guard and
11944 body functions except caller, is_seq_trace, get_seq_token,
11945 set_seq_token, enable_trace, disable_trace, trace, silent, and
11946 process_dump.
11947 Fails by raising an error exception with an error reason of:
11950 badarg:
11952 If an argument is invalid.
11953 system_limit:
11955 If a match specification passed as argument has excessive
11956 nesting which causes scheduler stack exhaustion for the
11957 scheduler that the calling process is executing on. Sched‐
11958 uler stack size can be configured when starting the runtime
11959 system.
11960 erlang:trace_pattern(MFA, MatchSpec, FlagList) ->
11962 integer() >= 0
11963 Types:
11965 MFA = trace_pattern_mfa()
11967 MatchSpec =
11968 (MatchSpecList :: trace_match_spec()) |
11969 boolean() |
11970 restart | pause
11971 FlagList = [trace_pattern_flag()]
11972 trace_pattern_mfa() = {atom(), atom(), arity() | '_'} | on_load
11973 trace_match_spec() =
11974 [{[term()] | '_' | match_variable(), [term()], [term()]}]
11975 trace_pattern_flag() =
11976 global | local | meta |
11977 {meta, Pid :: pid()} |
11978 {meta, TracerModule :: module(), TracerState :: term()} |
11979 call_count | call_time | call_memory
11980 match_variable() = atom()
11981 Approximation of '$1' | '$2' | '$3' | ...
11982 Enables or disables call tracing for one or more functions. Must
11984 be combined with erlang:trace/3 to set the call trace flag for
11985 one or more processes.
11986 Conceptually, call tracing works as follows. Inside the Erlang
11988 virtual machine, a set of processes and a set of functions are
11989 to be traced. If a traced process calls a traced function, the
11990 trace action is taken. Otherwise, nothing happens.
11991 To add or remove one or more processes to the set of traced pro‐
11993 cesses, use erlang:trace/3.
11994 To add or remove functions to the set of traced functions, use
11996 erlang:trace_pattern/3.
11997 The BIF erlang:trace_pattern/3 can also add match specifications
11999 to a function. A match specification comprises a pattern that
12000 the function arguments must match, a guard expression that must
12001 evaluate to true, and an action to be performed. The default ac‐
12002 tion is to send a trace message. If the pattern does not match
12003 or the guard fails, the action is not executed.
12004 Argument MFA is to be a tuple, such as {Module, Function, Ar‐
12006 ity}, or the atom on_load (described below). It can be the mod‐
12007 ule, function, and arity for a function (or a BIF in any mod‐
12008 ule). The atom '_' can be used as a wildcard in any of the fol‐
12009 lowing ways:
12010 {Module,Function,'_'}:
12012 All functions of any arity named Function in module Module.
12013 {Module,'_','_'}:
12015 All functions in module Module.
12016 {'_','_','_'}:
12018 All functions in all loaded modules.
12019 Other combinations, such as {Module,'_',Arity}, are not allowed.
12021 Local functions match wildcards only if option local is in
12022 FlagList.
12023 If argument MFA is the atom on_load, the match specification and
12025 flag list are used on all modules that are newly loaded.
12026 Argument MatchSpec can take the following forms:
12028 false:
12030 Disables tracing for the matching functions. Any match spec‐
12031 ification is removed.
12032 true:
12034 Enables tracing for the matching functions. Any match speci‐
12035 fication is removed.
12036 MatchSpecList:
12038 A list of match specifications. An empty list is equivalent
12039 to true. For a description of match specifications, see sec‐
12040 tion Match Specifications in Erlang in the User's Guide.
12041 restart:
12043 For the FlagList options call_count, call_time and call_mem‐
12044 ory: restarts the existing counters. The behavior is unde‐
12045 fined for other FlagList options.
12046 pause:
12048 For the FlagList options call_count, call_time and call_mem‐
12049 ory: pauses the existing counters. The behavior is undefined
12050 for other FlagList options.
12051 Parameter FlagList is a list of options. The following are the
12053 valid options:
12054 global:
12056 Turns on or off call tracing for global function calls (that
12057 is, calls specifying the module explicitly). Only exported
12058 functions match and only global calls generate trace mes‐
12059 sages. This is the default.
12060 local:
12062 Turns on or off call tracing for all types of function
12063 calls. Trace messages are sent whenever any of the specified
12064 functions are called, regardless of how they are called. If
12065 flag return_to is set for the process, a return_to message
12066 is also sent when this function returns to its caller.
12067 meta | {meta, Pid} | {meta, TracerModule, TracerState}:
12069 Turns on or off meta-tracing for all types of function
12070 calls. Trace messages are sent to the tracer whenever any of
12071 the specified functions are called. If no tracer is speci‐
12072 fied, self() is used as a default tracer process.
12073 Meta-tracing traces all processes and does not care about
12075 the process trace flags set by erlang:trace/3, the trace
12076 flags are instead fixed to [call, timestamp].
12077 The match specification function {return_trace} works with
12079 meta-trace and sends its trace message to the same tracer.
12080 call_count:
12082 Starts (MatchSpec == true) or stops (MatchSpec == false)
12083 call count tracing for all types of function calls. For ev‐
12084 ery function, a counter is incremented when the function is
12085 called, in any process. No process trace flags need to be
12086 activated.
12087 If call count tracing is started while already running, the
12089 count is restarted from zero. To pause running counters, use
12090 MatchSpec == pause. Paused and running counters can be
12091 restarted from zero with MatchSpec == restart.
12092 To read the counter value, use erlang:trace_info/2.
12094 call_time:
12096 Starts (MatchSpec == true) or stops (MatchSpec == false)
12097 call time tracing for all types of function calls. For every
12098 function, a counter is incremented when the function is
12099 called. Time spent in the function is accumulated in two
12100 other counters, seconds and microseconds. The counters are
12101 stored for each call traced process.
12102 If call time tracing is started while already running, the
12104 count and time restart from zero. To pause running counters,
12105 use MatchSpec == pause. Paused and running counters can be
12106 restarted from zero with MatchSpec == restart.
12107 To read the counter value, use erlang:trace_info/2.
12109 call_memory:
12111 Starts (MatchSpec == true) or stops (MatchSpec == false)
12112 call memory tracing for all types of function calls.
12113 If call memory tracing is started while already running,
12115 counters and allocations restart from zero. To pause running
12116 counters, use MatchSpec == pause. Paused and running coun‐
12117 ters can be restarted from zero with MatchSpec == restart.
12118 To read the counter value, use erlang:trace_info/2.
12120 The options global and local are mutually exclusive, and global
12122 is the default (if no options are specified). The options
12123 call_count and meta perform a kind of local tracing, and cannot
12124 be combined with global. A function can be globally or locally
12125 traced. If global tracing is specified for a set of functions,
12126 then local, meta, call time, and call count tracing for the
12127 matching set of local functions is disabled, and conversely.
12128 When disabling trace, the option must match the type of trace
12130 set on the function. That is, local tracing must be disabled
12131 with option local and global tracing with option global (or no
12132 option), and so on.
12133 Part of a match specification list cannot be changed directly.
12135 If a function has a match specification, it can be replaced with
12136 a new one. To change an existing match specification, use the
12137 BIF erlang:trace_info/2 to retrieve the existing match specifi‐
12138 cation.
12139 Returns the number of functions matching argument MFA. This is
12141 zero if none matched.
12142 Fails by raising an error exception with an error reason of:
12144 badarg:
12146 If an argument is invalid.
12147 system_limit:
12149 If a match specification passed as argument has excessive
12150 nesting which causes scheduler stack exhaustion for the
12151 scheduler that the calling process is executing on. Sched‐
12152 uler stack size can be configured when starting the runtime
12153 system.
12154 trunc(Number) -> integer()
12156 Types:
12158 Number = number()
12160 Truncates the decimals of Number, for example:
12162 > trunc(5.7).
12164 5
12165 > trunc(-5.7).
12167 -5
12168 > trunc(5).
12170 5
12171 > trunc(36028797018963969.0).
12173 36028797018963968
12174 In the last example, trunc(36028797018963969.0) evaluates to
12176 36028797018963968. The reason for this is that the number
12177 36028797018963969.0 cannot be represented exactly as a float
12178 value. Instead, the float literal is represented as
12179 36028797018963968.0, which is the closest number that can be
12180 represented exactly as a float value. See Representation of
12181 Floating Point Numbers for additional information.
12182 Allowed in guard tests.
12184 tuple_size(Tuple) -> integer() >= 0
12186 Types:
12188 Tuple = tuple()
12190 Returns an integer that is the number of elements in Tuple, for
12192 example:
12193 > tuple_size({morni, mulle, bwange}).
12195 3
12196 Allowed in guard tests.
12198 tuple_to_list(Tuple) -> [term()]
12200 Types:
12202 Tuple = tuple()
12204 Returns a list corresponding to Tuple. Tuple can contain any Er‐
12206 lang terms. Example:
12207 > tuple_to_list({share, {'Ericsson_B', 163}}).
12209 [share,{'Ericsson_B',163}]
12210 unalias(Alias) -> boolean()
12212 Types:
12214 Alias = reference()
12216 Deactivate the alias Alias previously created by the calling
12218 process. An alias can for example be created via alias/0, or
12219 monitor/3. unalias/1 will always deactivate the alias regardless
12220 of options used when creating the alias.
12221 Returns true if Alias was a currently active alias for current
12223 processes; otherwise, false.
12224 For more information on process aliases see the Process Aliases
12226 section of the Erlang Reference Manual .
12227 erlang:unique_integer() -> integer()
12229 Generates and returns an integer unique on current runtime sys‐
12231 tem instance. The same as calling erlang:unique_integer([]).
12232 erlang:unique_integer(ModifierList) -> integer()
12234 Types:
12236 ModifierList = [Modifier]
12238 Modifier = positive | monotonic
12239 Generates and returns an integer unique on current runtime sys‐
12241 tem instance. The integer is unique in the sense that this BIF,
12242 using the same set of modifiers, does not return the same inte‐
12243 ger more than once on the current runtime system instance. Each
12244 integer value can of course be constructed by other means.
12245 By default, when [] is passed as ModifierList, both negative and
12247 positive integers can be returned. This to use the range of in‐
12248 tegers that do not need heap memory allocation as much as possi‐
12249 ble. By default the returned integers are also only guaranteed
12250 to be unique, that is, any returned integer can be smaller or
12251 larger than previously returned integers.
12252 Modifiers:
12254 positive:
12256 Returns only positive integers.
12257 Notice that by passing the positive modifier you will get
12259 heap allocated integers (bignums) quicker.
12260 monotonic:
12262 Returns strictly monotonically increasing integers corre‐
12263 sponding to creation time. That is, the integer returned is
12264 always larger than previously returned integers on the cur‐
12265 rent runtime system instance.
12266 These values can be used to determine order between events
12268 on the runtime system instance. That is, if both X = er‐
12269 lang:unique_integer([monotonic]) and Y = erlang:unique_inte‐
12270 ger([monotonic]) are executed by different processes (or the
12271 same process) on the same runtime system instance and X < Y,
12272 we know that X was created before Y.
12273 Warning:
12275 Strictly monotonically increasing values are inherently quite
12276 expensive to generate and scales poorly. This is because the
12277 values need to be synchronized between CPU cores. That is, do
12278 not pass the monotonic modifier unless you really need
12279 strictly monotonically increasing values.
12280 All valid Modifiers can be combined. Repeated (valid) Modifiers
12283 in the ModifierList are ignored.
12284 Note:
12286 The set of integers returned by erlang:unique_integer/1 using
12287 different sets of Modifiers will overlap. For example, by call‐
12288 ing unique_integer([monotonic]), and unique_integer([positive,
12289 monotonic]) repeatedly, you will eventually see some integers
12290 that are returned by both calls.
12291 Failures:
12294 badarg:
12296 if ModifierList is not a proper list.
12297 badarg:
12299 if Modifier is not a valid modifier.
12300 erlang:universaltime() -> DateTime
12302 Types:
12304 DateTime = calendar:datetime()
12306 Returns the current date and time according to Universal Time
12308 Coordinated (UTC) in the form {{Year, Month, Day}, {Hour,
12309 Minute, Second}} if supported by the underlying OS. Otherwise
12310 erlang:universaltime() is equivalent to erlang:localtime(). The
12311 return value is based on the OS System Time. Example:
12312 > erlang:universaltime().
12314 {{1996,11,6},{14,18,43}}
12315 erlang:universaltime_to_localtime(Universaltime) -> Localtime
12317 Types:
12319 Localtime = Universaltime = calendar:datetime()
12321 Converts Universal Time Coordinated (UTC) date and time to local
12323 date and time in the form {{Year, Month, Day}, {Hour, Minute,
12324 Second}} if supported by the underlying OS. Otherwise no conver‐
12325 sion is done, and Universaltime is returned. Example:
12326 > erlang:universaltime_to_localtime({{1996,11,6},{14,18,43}}).
12328 {{1996,11,7},{15,18,43}}
12329 Failure: badarg if Universaltime denotes an invalid date and
12331 time.
12332 unlink(Id) -> true
12334 Types:
12336 Id = pid() | port()
12338 Removes a link between the calling process and another process
12340 or a port identified by Id. We will from here on call the iden‐
12341 tified process or port unlinkee.
12342 A link can be set up using the link/1 BIF. For more information
12344 on links and exit signals due to links, see the Processes chap‐
12345 ter in the Erlang Reference Manual :
12346 * Links
12348 * Sending Exit Signals
12350 * Receiving Exit Signals
12352 Once unlink(Id) has returned, it is guaranteed that the link be‐
12354 tween the caller and the unlinkee has no effect on the caller in
12355 the future (unless the link is setup again). Note that if the
12356 caller is trapping exits, an {'EXIT', Id, ExitReason} message
12357 due to the link may have been placed in the message queue of the
12358 caller before the unlink(Id) call completed. Also note that the
12359 {'EXIT', Id, ExitReason} message may be the result of the link,
12360 but may also be the result of the unlikee sending the caller an
12361 exit signal by calling the exit/2 BIF. Therefore, it may or may
12362 not be appropriate to clean up the message queue after a call to
12363 unlink(Id) as follows, when trapping exits:
12364 unlink(Id),
12366 receive
12367 {'EXIT', Id, _} ->
12368 true
12369 after 0 ->
12370 true
12371 end
12372 The link removal is performed asynchronously. If such a link
12374 does not exist, nothing is done. A detailed description of the
12375 link protocol can be found in the Distribution Protocol chapter
12376 of the ERTS User's Guide .
12377 Note:
12379 For some important information about distributed signals, see
12380 the Blocking Signaling Over Distribution section in the Pro‐
12381 cesses chapter of the Erlang Reference Manual .
12382 Failure: badarg if Id does not identify a process or a node lo‐
12385 cal port.
12386 unregister(RegName) -> true
12388 Types:
12390 RegName = atom()
12392 Removes the registered name RegName associated with a process
12394 identifier or a port identifier from the name registry. For ex‐
12395 ample:
12396 > unregister(db).
12398 true
12399 Keep in mind that you can still receive signals associated with
12401 the registered name after it has been unregistered as the sender
12402 may have looked up the name before sending to it.
12403 Users are advised not to unregister system processes.
12405 Failure: badarg if RegName is not a registered name.
12407 whereis(RegName) -> pid() | port() | undefined
12409 Types:
12411 RegName = atom()
12413 Returns the process identifier or port identifier with the reg‐
12415 istered name RegName from the name registry. Returns undefined
12416 if the name is not registered. Example:
12417 > whereis(db).
12419 <0.43.0>
12420 erlang:yield() -> true
12422 Tries to give other processes with the same or higher priority
12424 (if any) a chance to execute before returning. There is no guar‐
12425 antee that any other process runs between the invocation and re‐
12426 turn of erlang:yield/0.
12427 See the documentation for receive-after expressions for how to
12429 make the current process sleep for a specific number of mil‐
12430 liseconds.
12431 Warning:
12433 There is seldom or never any need to use this BIF. Using this
12434 BIF without a thorough grasp of how the scheduler works can
12435 cause performance degradation. The current implementation of
12436 this function puts the current process last in the current
12437 scheduler's queue for processes of the same priority as the cur‐
12438 rent process.
12439Ericsson AB erts 14.1.1 erlang(3)