1erlang(3) Erlang Module Definition erlang(3)
2
3
4
6 erlang - The Erlang BIFs.
7
9 By convention, most Built-In Functions (BIFs) are included in this mod‐
10 ule. Some of the BIFs are viewed more or less as part of the Erlang
11 programming language and are auto-imported. Thus, it is not necessary
12 to specify the module name. For example, the calls atom_to_list(erlang)
13 and erlang:atom_to_list(erlang) are identical.
14
15 Auto-imported BIFs are listed without module prefix. BIFs listed with
16 module prefix are not auto-imported.
17
18 BIFs can fail for various reasons. All BIFs fail with reason badarg if
19 they are called with arguments of an incorrect type. The other reasons
20 are described in the description of each individual BIF.
21
22 Some BIFs can be used in guard tests and are marked with "Allowed in
23 guard tests".
24
26 ext_binary() = binary()
27
28 A binary data object, structured according to the Erlang exter‐
29 nal term format.
30
31 iovec() = [binary()]
32
33 A list of binaries. This datatype is useful to use together with
34 enif_inspect_iovec.
35
36 message_queue_data() = off_heap | on_heap
37
38 See process_flag(message_queue_data, MQD).
39
40 timestamp() =
41 {MegaSecs :: integer() >= 0,
42 Secs :: integer() >= 0,
43 MicroSecs :: integer() >= 0}
44
45 See erlang:timestamp/0.
46
47 time_unit() =
48 integer() >= 1 |
49 second | millisecond | microsecond | nanosecond | native |
50 perf_counter |
51 deprecated_time_unit()
52
53 Supported time unit representations:
54
55 PartsPerSecond :: integer() >= 1:
56 Time unit expressed in parts per second. That is, the time
57 unit equals 1/PartsPerSecond second.
58
59 second:
60 Symbolic representation of the time unit represented by the
61 integer 1.
62
63 millisecond:
64 Symbolic representation of the time unit represented by the
65 integer 1000.
66
67 microsecond:
68 Symbolic representation of the time unit represented by the
69 integer 1000000.
70
71 nanosecond:
72 Symbolic representation of the time unit represented by the
73 integer 1000000000.
74
75 native:
76 Symbolic representation of the native time unit used by the
77 Erlang runtime system.
78
79 The native time unit is determined at runtime system start,
80 and remains the same until the runtime system terminates. If
81 a runtime system is stopped and then started again (even on
82 the same machine), the native time unit of the new runtime
83 system instance can differ from the native time unit of the
84 old runtime system instance.
85
86 One can get an approximation of the native time unit by
87 calling erlang:convert_time_unit(1, second, native). The
88 result equals the number of whole native time units per sec‐
89 ond. If the number of native time units per second does not
90 add up to a whole number, the result is rounded downwards.
91
92 Note:
93 The value of the native time unit gives you more or less no
94 information about the quality of time values. It sets a limit
95 for the resolution and for the precision of time values, but
96 it gives no information about the accuracy of time values.
97 The resolution of the native time unit and the resolution of
98 time values can differ significantly.
99
100
101 perf_counter:
102 Symbolic representation of the performance counter time unit
103 used by the Erlang runtime system.
104
105 The perf_counter time unit behaves much in the same way as
106 the native time unit. That is, it can differ between runtime
107 restarts. To get values of this type, call
108 os:perf_counter/0.
109
110 deprecated_time_unit():
111 Deprecated symbolic representations kept for backwards-com‐
112 patibility.
113
114 The time_unit/0 type can be extended. To convert time values
115 between time units, use erlang:convert_time_unit/3.
116
117 deprecated_time_unit() =
118 seconds | milli_seconds | micro_seconds | nano_seconds
119
120 The time_unit() type also consist of the following deprecated
121 symbolic time units:
122
123 seconds:
124 Same as second.
125
126 milli_seconds:
127 Same as millisecond.
128
129 micro_seconds:
130 Same as microsecond.
131
132 nano_seconds:
133 Same as nanosecond.
134
135 dist_handle()
136
137 An opaque handle identifing a distribution channel.
138
139 nif_resource()
140
141 An opaque handle identifing a NIF resource object .
142
144 abs(Float) -> float()
145
146 abs(Int) -> integer() >= 0
147
148 Types:
149
150 Int = integer()
151
152 Returns an integer or float that is the arithmetical absolute
153 value of Float or Int, for example:
154
155 > abs(-3.33).
156 3.33
157 > abs(-3).
158 3
159
160 Allowed in guard tests.
161
162 erlang:adler32(Data) -> integer() >= 0
163
164 Types:
165
166 Data = iodata()
167
168 Computes and returns the adler32 checksum for Data.
169
170 erlang:adler32(OldAdler, Data) -> integer() >= 0
171
172 Types:
173
174 OldAdler = integer() >= 0
175 Data = iodata()
176
177 Continues computing the adler32 checksum by combining the previ‐
178 ous checksum, OldAdler, with the checksum of Data.
179
180 The following code:
181
182 X = erlang:adler32(Data1),
183 Y = erlang:adler32(X,Data2).
184
185 assigns the same value to Y as this:
186
187 Y = erlang:adler32([Data1,Data2]).
188
189 erlang:adler32_combine(FirstAdler, SecondAdler, SecondSize) ->
190 integer() >= 0
191
192 Types:
193
194 FirstAdler = SecondAdler = SecondSize = integer() >= 0
195
196 Combines two previously computed adler32 checksums. This compu‐
197 tation requires the size of the data object for the second
198 checksum to be known.
199
200 The following code:
201
202 Y = erlang:adler32(Data1),
203 Z = erlang:adler32(Y,Data2).
204
205 assigns the same value to Z as this:
206
207 X = erlang:adler32(Data1),
208 Y = erlang:adler32(Data2),
209 Z = erlang:adler32_combine(X,Y,iolist_size(Data2)).
210
211 erlang:append_element(Tuple1, Term) -> Tuple2
212
213 Types:
214
215 Tuple1 = Tuple2 = tuple()
216 Term = term()
217
218 Returns a new tuple that has one element more than Tuple1, and
219 contains the elements in Tuple1 followed by Term as the last
220 element. Semantically equivalent to
221 list_to_tuple(tuple_to_list(Tuple1) ++ [Term]), but much faster.
222 Example:
223
224 > erlang:append_element({one, two}, three).
225 {one,two,three}
226
227 apply(Fun, Args) -> term()
228
229 Types:
230
231 Fun = function()
232 Args = [term()]
233
234 Calls a fun, passing the elements in Args as arguments.
235
236 If the number of elements in the arguments are known at compile
237 time, the call is better written as Fun(Arg1, Arg2, ... ArgN).
238
239 Warning:
240 Earlier, Fun could also be specified as {Module, Function},
241 equivalent to apply(Module, Function, Args). This use is depre‐
242 cated and will stop working in a future release.
243
244
245 apply(Module, Function, Args) -> term()
246
247 Types:
248
249 Module = module()
250 Function = atom()
251 Args = [term()]
252
253 Returns the result of applying Function in Module to Args. The
254 applied function must be exported from Module. The arity of the
255 function is the length of Args. Example:
256
257 > apply(lists, reverse, [[a, b, c]]).
258 [c,b,a]
259 > apply(erlang, atom_to_list, ['Erlang']).
260 "Erlang"
261
262 If the number of arguments are known at compile time, the call
263 is better written as Module:Function(Arg1, Arg2, ..., ArgN).
264
265 Failure: error_handler:undefined_function/3 is called if the
266 applied function is not exported. The error handler can be rede‐
267 fined (see process_flag/2). If error_handler is undefined, or if
268 the user has redefined the default error_handler so the replace‐
269 ment module is undefined, an error with reason undef is gener‐
270 ated.
271
272 atom_to_binary(Atom, Encoding) -> binary()
273
274 Types:
275
276 Atom = atom()
277 Encoding = latin1 | unicode | utf8
278
279 Returns a binary corresponding to the text representation of
280 Atom. If Encoding is latin1, one byte exists for each character
281 in the text representation. If Encoding is utf8 or unicode, the
282 characters are encoded using UTF-8 where characters may require
283 multiple bytes.
284
285 Note:
286 As from Erlang/OTP 20, atoms can contain any Unicode character
287 and atom_to_binary(Atom, latin1) may fail if the text represen‐
288 tation for Atom contains a Unicode character > 255.
289
290
291 Example:
292
293 > atom_to_binary('Erlang', latin1).
294 <<"Erlang">>
295
296 atom_to_list(Atom) -> string()
297
298 Types:
299
300 Atom = atom()
301
302 Returns a string corresponding to the text representation of
303 Atom, for example:
304
305 > atom_to_list('Erlang').
306 "Erlang"
307
308 binary_part(Subject, PosLen) -> binary()
309
310 Types:
311
312 Subject = binary()
313 PosLen = {Start :: integer() >= 0, Length :: integer()}
314
315 Extracts the part of the binary described by PosLen.
316
317 Negative length can be used to extract bytes at the end of a
318 binary, for example:
319
320 1> Bin = <<1,2,3,4,5,6,7,8,9,10>>.
321 2> binary_part(Bin,{byte_size(Bin), -5}).
322 <<6,7,8,9,10>>
323
324 Failure: badarg if PosLen in any way references outside the
325 binary.
326
327 Start is zero-based, that is:
328
329 1> Bin = <<1,2,3>>
330 2> binary_part(Bin,{0,2}).
331 <<1,2>>
332
333 For details about the PosLen semantics, see binary(3).
334
335 Allowed in guard tests.
336
337 binary_part(Subject, Start, Length) -> binary()
338
339 Types:
340
341 Subject = binary()
342 Start = integer() >= 0
343 Length = integer()
344
345 The same as binary_part(Subject, {Start, Length}).
346
347 Allowed in guard tests.
348
349 binary_to_atom(Binary, Encoding) -> atom()
350
351 Types:
352
353 Binary = binary()
354 Encoding = latin1 | unicode | utf8
355
356 Returns the atom whose text representation is Binary. If Encod‐
357 ing is latin1, no translation of bytes in the binary is done. If
358 Encoding is utf8 or unicode, the binary must contain valid UTF-8
359 sequences.
360
361 Note:
362 As from Erlang/OTP 20, binary_to_atom(Binary, utf8) is capable
363 of encoding any Unicode character. Earlier versions would fail
364 if the binary contained Unicode characters > 255. For more
365 information about Unicode support in atoms, see the note on
366 UTF-8 encoded atoms in section "External Term Format" in the
367 User's Guide.
368
369
370 Examples:
371
372 > binary_to_atom(<<"Erlang">>, latin1).
373 > binary_to_atom(<<1024/utf8>>, utf8).
374
375 binary_to_existing_atom(Binary, Encoding) -> atom()
376
377 Types:
378
379 Binary = binary()
380 Encoding = latin1 | unicode | utf8
381
382 As binary_to_atom/2, but the atom must exist.
383
384 Failure: badarg if the atom does not exist.
385
386 Note:
387 Note that the compiler may optimize away atoms. For example, the
388 compiler will rewrite atom_to_list(some_atom) to "some_atom". If
389 that expression is the only mention of the atom some_atom in the
390 containing module, the atom will not be created when the module
391 is loaded, and a subsequent call to binary_to_exist‐
392 ing_atom(<<"some_atom">>, utf8) will fail.
393
394
395 binary_to_float(Binary) -> float()
396
397 Types:
398
399 Binary = binary()
400
401 Returns the float whose text representation is Binary, for exam‐
402 ple:
403
404 > binary_to_float(<<"2.2017764e+0">>).
405 2.2017764
406
407 Failure: badarg if Binary contains a bad representation of a
408 float.
409
410 binary_to_integer(Binary) -> integer()
411
412 Types:
413
414 Binary = binary()
415
416 Returns an integer whose text representation is Binary, for
417 example:
418
419 > binary_to_integer(<<"123">>).
420 123
421
422 Failure: badarg if Binary contains a bad representation of an
423 integer.
424
425 binary_to_integer(Binary, Base) -> integer()
426
427 Types:
428
429 Binary = binary()
430 Base = 2..36
431
432 Returns an integer whose text representation in base Base is
433 Binary, for example:
434
435 > binary_to_integer(<<"3FF">>, 16).
436 1023
437
438 Failure: badarg if Binary contains a bad representation of an
439 integer.
440
441 binary_to_list(Binary) -> [byte()]
442
443 Types:
444
445 Binary = binary()
446
447 Returns a list of integers corresponding to the bytes of Binary.
448
449 binary_to_list(Binary, Start, Stop) -> [byte()]
450
451 Types:
452
453 Binary = binary()
454 Start = Stop = integer() >= 1
455 1..byte_size(Binary)
456
457 As binary_to_list/1, but returns a list of integers correspond‐
458 ing to the bytes from position Start to position Stop in Binary.
459 The positions in the binary are numbered starting from 1.
460
461 Note:
462 The one-based indexing for binaries used by this function is
463 deprecated. New code is to use binary:bin_to_list/3 in STDLIB
464 instead. All functions in module binary consistently use zero-
465 based indexing.
466
467
468 binary_to_term(Binary) -> term()
469
470 Types:
471
472 Binary = ext_binary()
473
474 Returns an Erlang term that is the result of decoding binary
475 object Binary, which must be encoded according to the Erlang
476 external term format.
477
478 > Bin = term_to_binary(hello).
479 <<131,100,0,5,104,101,108,108,111>>
480 > hello = binary_to_term(Bin).
481 hello
482
483
484 Warning:
485 When decoding binaries from untrusted sources, consider using
486 binary_to_term/2 to prevent Denial of Service attacks.
487
488
489 See also term_to_binary/1 and binary_to_term/2.
490
491 binary_to_term(Binary, Opts) -> term() | {term(), Used}
492
493 Types:
494
495 Binary = ext_binary()
496 Opt = safe | used
497 Opts = [Opt]
498 Used = integer() >= 1
499
500 As binary_to_term/1, but takes these options:
501
502 safe:
503 Use this option when receiving binaries from an untrusted
504 source.
505
506 When enabled, it prevents decoding data that can be used to
507 attack the Erlang system. In the event of receiving unsafe
508 data, decoding fails with a badarg error.
509
510 This prevents creation of new atoms directly, creation of
511 new atoms indirectly (as they are embedded in certain struc‐
512 tures, such as process identifiers, refs, and funs), and
513 creation of new external function references. None of those
514 resources are garbage collected, so unchecked creation of
515 them can exhaust available memory.
516
517 > binary_to_term(<<131,100,0,5,"hello">>, [safe]).
518 ** exception error: bad argument
519 > hello.
520 hello
521 > binary_to_term(<<131,100,0,5,"hello">>, [safe]).
522 hello
523
524
525 used:
526 Changes the return value to {Term, Used} where Used is the
527 number of bytes actually read from Binary.
528
529 > Input = <<131,100,0,5,"hello","world">>.
530 <<131,100,0,5,104,101,108,108,111,119,111,114,108,100>>
531 > {Term, Used} = binary_to_term(Input, [used]).
532 {hello, 9}
533 > split_binary(Input, Used).
534 {<<131,100,0,5,104,101,108,108,111>>, <<"world">>}
535
536
537 Failure: badarg if safe is specified and unsafe data is decoded.
538
539 See also term_to_binary/1, binary_to_term/1, and list_to_exist‐
540 ing_atom/1.
541
542 bit_size(Bitstring) -> integer() >= 0
543
544 Types:
545
546 Bitstring = bitstring()
547
548 Returns an integer that is the size in bits of Bitstring, for
549 example:
550
551 > bit_size(<<433:16,3:3>>).
552 19
553 > bit_size(<<1,2,3>>).
554 24
555
556 Allowed in guard tests.
557
558 bitstring_to_list(Bitstring) -> [byte() | bitstring()]
559
560 Types:
561
562 Bitstring = bitstring()
563
564 Returns a list of integers corresponding to the bytes of Bit‐
565 string. If the number of bits in the binary is not divisible by
566 8, the last element of the list is a bitstring containing the
567 remaining 1-7 bits.
568
569 erlang:bump_reductions(Reductions) -> true
570
571 Types:
572
573 Reductions = integer() >= 1
574
575 This implementation-dependent function increments the reduction
576 counter for the calling process. In the Beam emulator, the
577 reduction counter is normally incremented by one for each func‐
578 tion and BIF call. A context switch is forced when the counter
579 reaches the maximum number of reductions for a process (2000
580 reductions in Erlang/OTP R12B).
581
582 Warning:
583 This BIF can be removed in a future version of the Beam machine
584 without prior warning. It is unlikely to be implemented in other
585 Erlang implementations.
586
587
588 byte_size(Bitstring) -> integer() >= 0
589
590 Types:
591
592 Bitstring = bitstring()
593
594 Returns an integer that is the number of bytes needed to contain
595 Bitstring. That is, if the number of bits in Bitstring is not
596 divisible by 8, the resulting number of bytes is rounded up.
597 Examples:
598
599 > byte_size(<<433:16,3:3>>).
600 3
601 > byte_size(<<1,2,3>>).
602 3
603
604 Allowed in guard tests.
605
606 erlang:cancel_timer(TimerRef) -> Result
607
608 Types:
609
610 TimerRef = reference()
611 Time = integer() >= 0
612 Result = Time | false
613
614 Cancels a timer. The same as calling erlang:cancel_timer(Timer‐
615 Ref, []).
616
617 erlang:cancel_timer(TimerRef, Options) -> Result | ok
618
619 Types:
620
621 TimerRef = reference()
622 Async = Info = boolean()
623 Option = {async, Async} | {info, Info}
624 Options = [Option]
625 Time = integer() >= 0
626 Result = Time | false
627
628 Cancels a timer that has been created by erlang:start_timer or
629 erlang:send_after. TimerRef identifies the timer, and was
630 returned by the BIF that created the timer.
631
632 Options:
633
634 {async, Async}:
635 Asynchronous request for cancellation. Async defaults to
636 false, which causes the cancellation to be performed syn‐
637 chronously. When Async is set to true, the cancel operation
638 is performed asynchronously. That is, cancel_timer() sends
639 an asynchronous request for cancellation to the timer ser‐
640 vice that manages the timer, and then returns ok.
641
642 {info, Info}:
643 Requests information about the Result of the cancellation.
644 Info defaults to true, which means the Result is given. When
645 Info is set to false, no information about the result of the
646 cancellation is given.
647
648 * When Async is false: if Info is true, the Result is
649 returned by erlang:cancel_timer(). otherwise ok is
650 returned.
651
652 * When Async is true: if Info is true, a message on the form
653 {cancel_timer, TimerRef, Result} is sent to the caller of
654 erlang:cancel_timer() when the cancellation operation has
655 been performed, otherwise no message is sent.
656
657 More Options may be added in the future.
658
659 If Result is an integer, it represents the time in milliseconds
660 left until the canceled timer would have expired.
661
662 If Result is false, a timer corresponding to TimerRef could not
663 be found. This can be either because the timer had expired,
664 already had been canceled, or because TimerRef never corre‐
665 sponded to a timer. Even if the timer had expired, it does not
666 tell you if the time-out message has arrived at its destination
667 yet.
668
669 Note:
670 The timer service that manages the timer can be co-located with
671 another scheduler than the scheduler that the calling process is
672 executing on. If so, communication with the timer service takes
673 much longer time than if it is located locally. If the calling
674 process is in critical path, and can do other things while wait‐
675 ing for the result of this operation, or is not interested in
676 the result of the operation, you want to use option {async,
677 true}. If using option {async, false}, the calling process
678 blocks until the operation has been performed.
679
680
681 See also erlang:send_after/4, erlang:start_timer/4, and
682 erlang:read_timer/2.
683
684 ceil(Number) -> integer()
685
686 Types:
687
688 Number = number()
689
690 Returns the smallest integer not less than Number. For example:
691
692 > ceil(5.5).
693 6
694
695 Allowed in guard tests.
696
697 check_old_code(Module) -> boolean()
698
699 Types:
700
701 Module = module()
702
703 Returns true if Module has old code, otherwise false.
704
705 See also code(3).
706
707 check_process_code(Pid, Module) -> CheckResult
708
709 Types:
710
711 Pid = pid()
712 Module = module()
713 CheckResult = boolean()
714
715 The same as check_process_code(Pid, Module, []).
716
717 check_process_code(Pid, Module, OptionList) -> CheckResult | async
718
719 Types:
720
721 Pid = pid()
722 Module = module()
723 RequestId = term()
724 Option = {async, RequestId} | {allow_gc, boolean()}
725 OptionList = [Option]
726 CheckResult = boolean() | aborted
727
728 Checks if the node local process identified by Pid executes old
729 code for Module.
730
731 Options:
732
733 {allow_gc, boolean()}:
734 Determines if garbage collection is allowed when performing
735 the operation. If {allow_gc, false} is passed, and a garbage
736 collection is needed to determine the result of the opera‐
737 tion, the operation is aborted (see information on CheckRe‐
738 sult below). The default is to allow garbage collection,
739 that is, {allow_gc, true}.
740
741 {async, RequestId}:
742 The function check_process_code/3 returns the value async
743 immediately after the request has been sent. When the
744 request has been processed, the process that called this
745 function is passed a message on the form
746 {check_process_code, RequestId, CheckResult}.
747
748 If Pid equals self(), and no async option has been passed, the
749 operation is performed at once. Otherwise a request for the
750 operation is sent to the process identified by Pid, and is han‐
751 dled when appropriate. If no async option has been passed, the
752 caller blocks until CheckResult is available and can be
753 returned.
754
755 CheckResult informs about the result of the request as follows:
756
757 true:
758 The process identified by Pid executes old code for Module.
759 That is, the current call of the process executes old code
760 for this module, or the process has references to old code
761 for this module, or the process contains funs that refer‐
762 ences old code for this module.
763
764 false:
765 The process identified by Pid does not execute old code for
766 Module.
767
768 aborted:
769 The operation was aborted, as the process needed to be
770 garbage collected to determine the operation result, and the
771 operation was requested by passing option {allow_gc, false}.
772
773 Note:
774 Up until ERTS version 8.*, the check process code operation
775 checks for all types of references to the old code. That is,
776 direct references (e.g. return addresses on the process stack),
777 indirect references (funs in process context), and references to
778 literals in the code.
779
780 As of ERTS version 9.0, the check process code operation only
781 checks for direct references to the code. Indirect references
782 via funs will be ignored. If such funs exist and are used after
783 a purge of the old code, an exception will be raised upon usage
784 (same as the case when the fun is received by the process after
785 the purge). Literals will be taken care of (copied) at a later
786 stage. This behavior can as of ERTS version 8.1 be enabled when
787 building OTP, and will automatically be enabled if dirty sched‐
788 uler support is enabled.
789
790
791 See also code(3).
792
793 Failures:
794
795 badarg:
796 If Pid is not a node local process identifier.
797
798 badarg:
799 If Module is not an atom.
800
801 badarg:
802 If OptionList is an invalid list of options.
803
804 erlang:convert_time_unit(Time, FromUnit, ToUnit) -> ConvertedTime
805
806 Types:
807
808 Time = ConvertedTime = integer()
809 FromUnit = ToUnit = time_unit()
810
811 Converts the Time value of time unit FromUnit to the correspond‐
812 ing ConvertedTime value of time unit ToUnit. The result is
813 rounded using the floor function.
814
815 Warning:
816 You can lose accuracy and precision when converting between time
817 units. To minimize such loss, collect all data at native time
818 unit and do the conversion on the end result.
819
820
821 erlang:crc32(Data) -> integer() >= 0
822
823 Types:
824
825 Data = iodata()
826
827 Computes and returns the crc32 (IEEE 802.3 style) checksum for
828 Data.
829
830 erlang:crc32(OldCrc, Data) -> integer() >= 0
831
832 Types:
833
834 OldCrc = integer() >= 0
835 Data = iodata()
836
837 Continues computing the crc32 checksum by combining the previous
838 checksum, OldCrc, with the checksum of Data.
839
840 The following code:
841
842 X = erlang:crc32(Data1),
843 Y = erlang:crc32(X,Data2).
844
845 assigns the same value to Y as this:
846
847 Y = erlang:crc32([Data1,Data2]).
848
849 erlang:crc32_combine(FirstCrc, SecondCrc, SecondSize) ->
850 integer() >= 0
851
852 Types:
853
854 FirstCrc = SecondCrc = SecondSize = integer() >= 0
855
856 Combines two previously computed crc32 checksums. This computa‐
857 tion requires the size of the data object for the second check‐
858 sum to be known.
859
860 The following code:
861
862 Y = erlang:crc32(Data1),
863 Z = erlang:crc32(Y,Data2).
864
865 assigns the same value to Z as this:
866
867 X = erlang:crc32(Data1),
868 Y = erlang:crc32(Data2),
869 Z = erlang:crc32_combine(X,Y,iolist_size(Data2)).
870
871 date() -> Date
872
873 Types:
874
875 Date = calendar:date()
876
877 Returns the current date as {Year, Month, Day}.
878
879 The time zone and Daylight Saving Time correction depend on the
880 underlying OS. Example:
881
882 > date().
883 {1995,2,19}
884
885 erlang:decode_packet(Type, Bin, Options) ->
886 {ok, Packet, Rest} |
887 {more, Length} |
888 {error, Reason}
889
890 Types:
891
892 Type =
893 raw | 0 | 1 | 2 | 4 | asn1 | cdr | sunrm | fcgi | tpkt |
894 line | http | http_bin | httph | httph_bin
895 Bin = binary()
896 Options = [Opt]
897 Opt =
898 {packet_size, integer() >= 0} |
899 {line_length, integer() >= 0}
900 Packet = binary() | HttpPacket
901 Rest = binary()
902 Length = integer() >= 0 | undefined
903 Reason = term()
904 HttpPacket =
905 HttpRequest | HttpResponse | HttpHeader | http_eoh |
906 HttpError
907 HttpRequest = {http_request, HttpMethod, HttpUri, HttpVer‐
908 sion}
909 HttpResponse =
910 {http_response, HttpVersion, integer(), HttpString}
911 HttpHeader =
912 {http_header,
913 integer(),
914 HttpField,
915 Reserved :: term(),
916 Value :: HttpString}
917 HttpError = {http_error, HttpString}
918 HttpMethod =
919 'OPTIONS' | 'GET' | 'HEAD' | 'POST' | 'PUT' | 'DELETE' |
920 'TRACE' | HttpString
921 HttpUri =
922 '*' |
923 {absoluteURI,
924 http | https,
925 Host :: HttpString,
926 Port :: inet:port_number() | undefined,
927 Path :: HttpString} |
928 {scheme, Scheme :: HttpString, HttpString} |
929 {abs_path, HttpString} |
930 HttpString
931 HttpVersion =
932 {Major :: integer() >= 0, Minor :: integer() >= 0}
933 HttpField =
934 'Cache-Control' | 'Connection' | 'Date' | 'Pragma' |
935 'Transfer-Encoding' | 'Upgrade' | 'Via' | 'Accept' |
936 'Accept-Charset' | 'Accept-Encoding' | 'Accept-Language'
937 |
938 'Authorization' | 'From' | 'Host' | 'If-Modified-Since' |
939 'If-Match' | 'If-None-Match' | 'If-Range' |
940 'If-Unmodified-Since' | 'Max-Forwards' |
941 'Proxy-Authorization' | 'Range' | 'Referer' | 'User-
942 Agent' |
943 'Age' | 'Location' | 'Proxy-Authenticate' | 'Public' |
944 'Retry-After' | 'Server' | 'Vary' | 'Warning' |
945 'Www-Authenticate' | 'Allow' | 'Content-Base' |
946 'Content-Encoding' | 'Content-Language' | 'Content-
947 Length' |
948 'Content-Location' | 'Content-Md5' | 'Content-Range' |
949 'Content-Type' | 'Etag' | 'Expires' | 'Last-Modified' |
950 'Accept-Ranges' | 'Set-Cookie' | 'Set-Cookie2' |
951 'X-Forwarded-For' | 'Cookie' | 'Keep-Alive' |
952 'Proxy-Connection' | HttpString
953 HttpString = string() | binary()
954
955 Decodes the binary Bin according to the packet protocol speci‐
956 fied by Type. Similar to the packet handling done by sockets
957 with option {packet,Type}.
958
959 If an entire packet is contained in Bin, it is returned together
960 with the remainder of the binary as {ok,Packet,Rest}.
961
962 If Bin does not contain the entire packet, {more,Length} is
963 returned. Length is either the expected total size of the
964 packet, or undefined if the expected packet size is unknown.
965 decode_packet can then be called again with more data added.
966
967 If the packet does not conform to the protocol format,
968 {error,Reason} is returned.
969
970 Types:
971
972 raw | 0:
973 No packet handling is done. The entire binary is returned
974 unless it is empty.
975
976 1 | 2 | 4:
977 Packets consist of a header specifying the number of bytes
978 in the packet, followed by that number of bytes. The length
979 of the header can be one, two, or four bytes; the order of
980 the bytes is big-endian. The header is stripped off when the
981 packet is returned.
982
983 line:
984 A packet is a line-terminated by a delimiter byte, default
985 is the latin-1 newline character. The delimiter byte is
986 included in the returned packet unless the line was trun‐
987 cated according to option line_length.
988
989 asn1 | cdr | sunrm | fcgi | tpkt:
990 The header is not stripped off.
991
992 The meanings of the packet types are as follows:
993
994 asn1 - ASN.1 BER:
995
996
997 sunrm - Sun's RPC encoding:
998
999
1000 cdr - CORBA (GIOP 1.1):
1001
1002
1003 fcgi - Fast CGI:
1004
1005
1006 tpkt - TPKT format [RFC1006]:
1007
1008
1009 http | httph | http_bin | httph_bin:
1010 The Hypertext Transfer Protocol. The packets are returned
1011 with the format according to HttpPacket described earlier. A
1012 packet is either a request, a response, a header, or an end
1013 of header mark. Invalid lines are returned as HttpError.
1014
1015 Recognized request methods and header fields are returned as
1016 atoms. Others are returned as strings. Strings of unrecog‐
1017 nized header fields are formatted with only capital letters
1018 first and after hyphen characters, for example, "Sec-Web‐
1019 socket-Key".
1020
1021 The protocol type http is only to be used for the first line
1022 when an HttpRequest or an HttpResponse is expected. The fol‐
1023 lowing calls are to use httph to get HttpHeaders until
1024 http_eoh is returned, which marks the end of the headers and
1025 the beginning of any following message body.
1026
1027 The variants http_bin and httph_bin return strings (Http‐
1028 String) as binaries instead of lists.
1029
1030 Options:
1031
1032 {packet_size, integer() >= 0}:
1033 Sets the maximum allowed size of the packet body. If the
1034 packet header indicates that the length of the packet is
1035 longer than the maximum allowed length, the packet is con‐
1036 sidered invalid. Defaults to 0, which means no size limit.
1037
1038 {line_length, integer() >= 0}:
1039 For packet type line, lines longer than the indicated length
1040 are truncated.
1041
1042 Option line_length also applies to http* packet types as an
1043 alias for option packet_size if packet_size itself is not
1044 set. This use is only intended for backward compatibility.
1045
1046 {line_delimiter, 0 =< byte() =< 255}:
1047 For packet type line, sets the delimiting byte. Default is
1048 the latin-1 character $\n.
1049
1050 Examples:
1051
1052 > erlang:decode_packet(1,<<3,"abcd">>,[]).
1053 {ok,<<"abc">>,<<"d">>}
1054 > erlang:decode_packet(1,<<5,"abcd">>,[]).
1055 {more,6}
1056
1057 erlang:delete_element(Index, Tuple1) -> Tuple2
1058
1059 Types:
1060
1061 Index = integer() >= 1
1062 1..tuple_size(Tuple1)
1063 Tuple1 = Tuple2 = tuple()
1064
1065 Returns a new tuple with element at Index removed from tuple
1066 Tuple1, for example:
1067
1068 > erlang:delete_element(2, {one, two, three}).
1069 {one,three}
1070
1071 delete_module(Module) -> true | undefined
1072
1073 Types:
1074
1075 Module = module()
1076
1077 Makes the current code for Module become old code and deletes
1078 all references for this module from the export table. Returns
1079 undefined if the module does not exist, otherwise true.
1080
1081 Warning:
1082 This BIF is intended for the code server (see code(3)) and is
1083 not to be used elsewhere.
1084
1085
1086 Failure: badarg if there already is an old version of Module.
1087
1088 demonitor(MonitorRef) -> true
1089
1090 Types:
1091
1092 MonitorRef = reference()
1093
1094 If MonitorRef is a reference that the calling process obtained
1095 by calling monitor/2, this monitoring is turned off. If the mon‐
1096 itoring is already turned off, nothing happens.
1097
1098 Once demonitor(MonitorRef) has returned, it is guaranteed that
1099 no {'DOWN', MonitorRef, _, _, _} message, because of the moni‐
1100 tor, will be placed in the caller message queue in the future.
1101 However, a {'DOWN', MonitorRef, _, _, _} message can have been
1102 placed in the caller message queue before the call. It is there‐
1103 fore usually advisable to remove such a 'DOWN' message from the
1104 message queue after monitoring has been stopped. demonitor(Moni‐
1105 torRef, [flush]) can be used instead of demonitor(MonitorRef) if
1106 this cleanup is wanted.
1107
1108 Note:
1109 Before Erlang/OTP R11B (ERTS 5.5) demonitor/1 behaved completely
1110 asynchronously, that is, the monitor was active until the
1111 "demonitor signal" reached the monitored entity. This had one
1112 undesirable effect. You could never know when you were guaran‐
1113 teed not to receive a DOWN message because of the monitor.
1114
1115 The current behavior can be viewed as two combined operations:
1116 asynchronously send a "demonitor signal" to the monitored entity
1117 and ignore any future results of the monitor.
1118
1119
1120 Failure: It is an error if MonitorRef refers to a monitoring
1121 started by another process. Not all such cases are cheap to
1122 check. If checking is cheap, the call fails with badarg, for
1123 example if MonitorRef is a remote reference.
1124
1125 demonitor(MonitorRef, OptionList) -> boolean()
1126
1127 Types:
1128
1129 MonitorRef = reference()
1130 OptionList = [Option]
1131 Option = flush | info
1132
1133 The returned value is true unless info is part of OptionList.
1134
1135 demonitor(MonitorRef, []) is equivalent to demonitor(Monitor‐
1136 Ref).
1137
1138 Options:
1139
1140 flush:
1141 Removes (one) {_, MonitorRef, _, _, _} message, if there is
1142 one, from the caller message queue after monitoring has been
1143 stopped.
1144
1145 Calling demonitor(MonitorRef, [flush]) is equivalent to the
1146 following, but more efficient:
1147
1148 demonitor(MonitorRef),
1149 receive
1150 {_, MonitorRef, _, _, _} ->
1151 true
1152 after 0 ->
1153 true
1154 end
1155
1156 info:
1157 The returned value is one of the following:
1158
1159 true:
1160 The monitor was found and removed. In this case, no 'DOWN'
1161 message corresponding to this monitor has been delivered
1162 and will not be delivered.
1163
1164 false:
1165 The monitor was not found and could not be removed. This
1166 probably because someone already has placed a 'DOWN' mes‐
1167 sage corresponding to this monitor in the caller message
1168 queue.
1169
1170 If option info is combined with option flush, false is
1171 returned if a flush was needed, otherwise true.
1172
1173 Note:
1174 More options can be added in a future release.
1175
1176
1177 Failures:
1178
1179 badarg:
1180 If OptionList is not a list.
1181
1182 badarg:
1183 If Option is an invalid option.
1184
1185 badarg:
1186 The same failure as for demonitor/1.
1187
1188 disconnect_node(Node) -> boolean() | ignored
1189
1190 Types:
1191
1192 Node = node()
1193
1194 Forces the disconnection of a node. This appears to the node
1195 Node as if the local node has crashed. This BIF is mainly used
1196 in the Erlang network authentication protocols.
1197
1198 Returns true if disconnection succeeds, otherwise false. If the
1199 local node is not alive, ignored is returned.
1200
1201 erlang:display(Term) -> true
1202
1203 Types:
1204
1205 Term = term()
1206
1207 Prints a text representation of Term on the standard output.
1208
1209 Warning:
1210 This BIF is intended for debugging only.
1211
1212
1213 erlang:dist_ctrl_get_data(DHandle) -> {Size, Data} | Data | none
1214
1215 Types:
1216
1217 Size = integer() >= 0
1218 DHandle = dist_handle()
1219 Data = iodata()
1220
1221 Get distribution channel data from the local node that is to be
1222 passed to the remote node. The distribution channel is identi‐
1223 fied by DHandle. If no data is available, the atom none is
1224 returned. One can request to be informed by a message when more
1225 data is available by calling erlang:dist_ctrl_get_data_notifica‐
1226 tion(DHandle).
1227
1228 The returned value when there are data available depends on the
1229 value of the get_size option configured on the distribution
1230 channel identified by DHandle. For more information see the doc‐
1231 umentation of the get_size option for the
1232 erlang:dist_ctrl_set_opt/3 function.
1233
1234 Note:
1235 Only the process registered as distribution controller for the
1236 distribution channel identified by DHandle is allowed to call
1237 this function.
1238
1239
1240 This function is used when implementing an alternative distribu‐
1241 tion carrier using processes as distribution controllers. DHan‐
1242 dle is retrived via the callback f_handshake_complete. More
1243 information can be found in the documentation of ERTS User's
1244 Guide ➜ How to implement an Alternative Carrier for the Erlang
1245 Distribution ➜ Distribution Module.
1246
1247 erlang:dist_ctrl_get_opt(DHandle, Opt :: get_size) -> Value
1248
1249 Types:
1250
1251 DHandle = dist_handle()
1252 Value = boolean()
1253
1254 Returns the value of the get_size option on the distribution
1255 channel identified by DHandle. For more information see the doc‐
1256 umentation of the get_size option for the
1257 erlang:dist_ctrl_set_opt/3 function.
1258
1259 Note:
1260 Only the process registered as distribution controller for the
1261 distribution channel identified by DHandle is allowed to call
1262 this function.
1263
1264
1265 This function is used when implementing an alternative distribu‐
1266 tion carrier using processes as distribution controllers. DHan‐
1267 dle is retrived via the callback f_handshake_complete. More
1268 information can be found in the documentation of ERTS User's
1269 Guide ➜ How to implement an Alternative Carrier for the Erlang
1270 Distribution ➜ Distribution Module.
1271
1272 erlang:dist_ctrl_get_data_notification(DHandle) -> ok
1273
1274 Types:
1275
1276 DHandle = dist_handle()
1277
1278 Request notification when more data is available to fetch using
1279 erlang:dist_ctrl_get_data(DHandle) for the distribution channel
1280 identified by DHandle. When more data is present, the caller
1281 will be sent the message dist_data. Once a dist_data messages
1282 has been sent, no more dist_data messages will be sent until the
1283 dist_ctrl_get_data_notification/1 function has been called
1284 again.
1285
1286 Note:
1287 Only the process registered as distribution controller for the
1288 distribution channel identified by DHandle is allowed to call
1289 this function.
1290
1291
1292 This function is used when implementing an alternative distribu‐
1293 tion carrier using processes as distribution controllers. DHan‐
1294 dle is retrived via the callback f_handshake_complete. More
1295 information can be found in the documentation of ERTS User's
1296 Guide ➜ How to implement an Alternative Carrier for the Erlang
1297 Distribution ➜ Distribution Module.
1298
1299 erlang:dist_ctrl_input_handler(DHandle, InputHandler) -> ok
1300
1301 Types:
1302
1303 DHandle = dist_handle()
1304 InputHandler = pid()
1305
1306 Register an alternate input handler process for the distribution
1307 channel identified by DHandle. Once this function has been
1308 called, InputHandler is the only process allowed to call
1309 erlang:dist_ctrl_put_data(DHandle, Data) with the DHandle iden‐
1310 tifing this distribution channel.
1311
1312 Note:
1313 Only the process registered as distribution controller for the
1314 distribution channel identified by DHandle is allowed to call
1315 this function.
1316
1317
1318 This function is used when implementing an alternative distribu‐
1319 tion carrier using processes as distribution controllers. DHan‐
1320 dle is retrived via the callback f_handshake_complete. More
1321 information can be found in the documentation of ERTS User's
1322 Guide ➜ How to implement an Alternative Carrier for the Erlang
1323 Distribution ➜ Distribution Module.
1324
1325 erlang:dist_ctrl_put_data(DHandle, Data) -> ok
1326
1327 Types:
1328
1329 DHandle = dist_handle()
1330 Data = iodata()
1331
1332 Deliver distribution channel data from a remote node to the
1333 local node.
1334
1335 Note:
1336 Only the process registered as distribution controller for the
1337 distribution channel identified by DHandle is allowed to call
1338 this function unless an alternate input handler process has been
1339 registered using erlang:dist_ctrl_input_handler(DHandle,
1340 InputHandler). If an alternate input handler has been regis‐
1341 tered, only the registered input handler process is allowed to
1342 call this function.
1343
1344
1345 This function is used when implementing an alternative distribu‐
1346 tion carrier using processes as distribution controllers. DHan‐
1347 dle is retrived via the callback f_handshake_complete. More
1348 information can be found in the documentation of ERTS User's
1349 Guide ➜ How to implement an Alternative Carrier for the Erlang
1350 Distribution ➜ Distribution Module.
1351
1352 erlang:dist_ctrl_set_opt(DHandle, Opt :: get_size, Value) ->
1353 OldValue
1354
1355 Types:
1356
1357 DHandle = dist_handle()
1358 Value = OldValue = boolean()
1359
1360 Sets the value of the get_size option on the distribution chan‐
1361 nel identified by DHandle. This option controls the return value
1362 of calls to erlang:dist_ctrl_get_data(DHandle) where DHandle
1363 equals DHandle used when setting this option. When the get_size
1364 option is:
1365
1366 false:
1367 and there are distribution data available, a call to
1368 erlang:dist_ctrl_get_data(DHandle) will just return Data to
1369 pass over the channel. This is the default value of the
1370 get_size option.
1371
1372 true:
1373 and there are distribution data available, a call to
1374 erlang:dist_ctrl_get_data(DHandle) will return Data to pass
1375 over the channel as well as the Size of Data in bytes. This
1376 is returned as a tuple on the form {Size, Data}.
1377
1378 All options are set to default when a channel is closed.
1379
1380 Note:
1381 Only the process registered as distribution controller for the
1382 distribution channel identified by DHandle is allowed to call
1383 this function.
1384
1385
1386 This function is used when implementing an alternative distribu‐
1387 tion carrier using processes as distribution controllers. DHan‐
1388 dle is retrived via the callback f_handshake_complete. More
1389 information can be found in the documentation of ERTS User's
1390 Guide ➜ How to implement an Alternative Carrier for the Erlang
1391 Distribution ➜ Distribution Module.
1392
1393 element(N, Tuple) -> term()
1394
1395 Types:
1396
1397 N = integer() >= 1
1398 1..tuple_size(Tuple)
1399 Tuple = tuple()
1400
1401 Returns the Nth element (numbering from 1) of Tuple, for exam‐
1402 ple:
1403
1404 > element(2, {a, b, c}).
1405 b
1406
1407 Allowed in guard tests.
1408
1409 erase() -> [{Key, Val}]
1410
1411 Types:
1412
1413 Key = Val = term()
1414
1415 Returns the process dictionary and deletes it, for example:
1416
1417 > put(key1, {1, 2, 3}),
1418 put(key2, [a, b, c]),
1419 erase().
1420 [{key1,{1,2,3}},{key2,[a,b,c]}]
1421
1422 erase(Key) -> Val | undefined
1423
1424 Types:
1425
1426 Key = Val = term()
1427
1428 Returns the value Val associated with Key and deletes it from
1429 the process dictionary. Returns undefined if no value is associ‐
1430 ated with Key. Example:
1431
1432 > put(key1, {merry, lambs, are, playing}),
1433 X = erase(key1),
1434 {X, erase(key1)}.
1435 {{merry,lambs,are,playing},undefined}
1436
1437 error(Reason) -> no_return()
1438
1439 Types:
1440
1441 Reason = term()
1442
1443 Stops the execution of the calling process with the reason Rea‐
1444 son, where Reason is any term. The exit reason is {Reason,
1445 Where}, where Where is a list of the functions most recently
1446 called (the current function first). As evaluating this function
1447 causes the process to terminate, it has no return value. Exam‐
1448 ple:
1449
1450 > catch error(foobar).
1451 {'EXIT',{foobar,[{shell,apply_fun,3,
1452 [{file,"shell.erl"},{line,906}]},
1453 {erl_eval,do_apply,6,[{file,"erl_eval.erl"},{line,677}]},
1454 {erl_eval,expr,5,[{file,"erl_eval.erl"},{line,430}]},
1455 {shell,exprs,7,[{file,"shell.erl"},{line,687}]},
1456 {shell,eval_exprs,7,[{file,"shell.erl"},{line,642}]},
1457 {shell,eval_loop,3,[{file,"shell.erl"},{line,627}]}]}}
1458
1459
1460 error(Reason, Args) -> no_return()
1461
1462 Types:
1463
1464 Reason = term()
1465 Args = [term()]
1466
1467 Stops the execution of the calling process with the reason Rea‐
1468 son, where Reason is any term. The exit reason is {Reason,
1469 Where}, where Where is a list of the functions most recently
1470 called (the current function first). Args is expected to be the
1471 list of arguments for the current function; in Beam it is used
1472 to provide the arguments for the current function in the term
1473 Where. As evaluating this function causes the process to termi‐
1474 nate, it has no return value.
1475
1476 exit(Reason) -> no_return()
1477
1478 Types:
1479
1480 Reason = term()
1481
1482 Stops the execution of the calling process with exit reason Rea‐
1483 son, where Reason is any term. As evaluating this function
1484 causes the process to terminate, it has no return value. Exam‐
1485 ple:
1486
1487 > exit(foobar).
1488 ** exception exit: foobar
1489 > catch exit(foobar).
1490 {'EXIT',foobar}
1491
1492 exit(Pid, Reason) -> true
1493
1494 Types:
1495
1496 Pid = pid() | port()
1497 Reason = term()
1498
1499 Sends an exit signal with exit reason Reason to the process or
1500 port identified by Pid.
1501
1502 The following behavior applies if Reason is any term, except
1503 normal or kill:
1504
1505 * If Pid is not trapping exits, Pid itself exits with exit
1506 reason Reason.
1507
1508 * If Pid is trapping exits, the exit signal is transformed
1509 into a message {'EXIT', From, Reason} and delivered to the
1510 message queue of Pid.
1511
1512 * From is the process identifier of the process that sent the
1513 exit signal. See also process_flag/2.
1514
1515 If Reason is the atom normal, Pid does not exit. If it is trap‐
1516 ping exits, the exit signal is transformed into a message
1517 {'EXIT', From, normal} and delivered to its message queue.
1518
1519 If Reason is the atom kill, that is, if exit(Pid, kill) is
1520 called, an untrappable exit signal is sent to Pid, which uncon‐
1521 ditionally exits with exit reason killed.
1522
1523 erlang:external_size(Term) -> integer() >= 0
1524
1525 Types:
1526
1527 Term = term()
1528
1529 Calculates, without doing the encoding, the maximum byte size
1530 for a term encoded in the Erlang external term format. The fol‐
1531 lowing condition applies always:
1532
1533 > Size1 = byte_size(term_to_binary(Term)),
1534 > Size2 = erlang:external_size(Term),
1535 > true = Size1 =< Size2.
1536 true
1537
1538 This is equivalent to a call to:
1539
1540 erlang:external_size(Term, [])
1541
1542 erlang:external_size(Term, Options) -> integer() >= 0
1543
1544 Types:
1545
1546 Term = term()
1547 Options = [{minor_version, Version :: integer() >= 0}]
1548
1549 Calculates, without doing the encoding, the maximum byte size
1550 for a term encoded in the Erlang external term format. The fol‐
1551 lowing condition applies always:
1552
1553 > Size1 = byte_size(term_to_binary(Term, Options)),
1554 > Size2 = erlang:external_size(Term, Options),
1555 > true = Size1 =< Size2.
1556 true
1557
1558 Option {minor_version, Version} specifies how floats are
1559 encoded. For a detailed description, see term_to_binary/2.
1560
1561 float(Number) -> float()
1562
1563 Types:
1564
1565 Number = number()
1566
1567 Returns a float by converting Number to a float, for example:
1568
1569 > float(55).
1570 55.0
1571
1572 Allowed in guard tests.
1573
1574 Note:
1575 If used on the top level in a guard, it tests whether the argu‐
1576 ment is a floating point number; for clarity, use is_float/1
1577 instead.
1578
1579 When float/1 is used in an expression in a guard, such as
1580 'float(A) == 4.0', it converts a number as described earlier.
1581
1582
1583 float_to_binary(Float) -> binary()
1584
1585 Types:
1586
1587 Float = float()
1588
1589 The same as float_to_binary(Float,[{scientific,20}]).
1590
1591 float_to_binary(Float, Options) -> binary()
1592
1593 Types:
1594
1595 Float = float()
1596 Options = [Option]
1597 Option =
1598 {decimals, Decimals :: 0..253} |
1599 {scientific, Decimals :: 0..249} |
1600 compact
1601
1602 Returns a binary corresponding to the text representation of
1603 Float using fixed decimal point formatting. Options behaves in
1604 the same way as float_to_list/2. Examples:
1605
1606 > float_to_binary(7.12, [{decimals, 4}]).
1607 <<"7.1200">>
1608 > float_to_binary(7.12, [{decimals, 4}, compact]).
1609 <<"7.12">>
1610
1611 float_to_list(Float) -> string()
1612
1613 Types:
1614
1615 Float = float()
1616
1617 The same as float_to_list(Float,[{scientific,20}]).
1618
1619 float_to_list(Float, Options) -> string()
1620
1621 Types:
1622
1623 Float = float()
1624 Options = [Option]
1625 Option =
1626 {decimals, Decimals :: 0..253} |
1627 {scientific, Decimals :: 0..249} |
1628 compact
1629
1630 Returns a string corresponding to the text representation of
1631 Float using fixed decimal point formatting.
1632
1633 Available options:
1634
1635 * If option decimals is specified, the returned value contains
1636 at most Decimals number of digits past the decimal point. If
1637 the number does not fit in the internal static buffer of 256
1638 bytes, the function throws badarg.
1639
1640 * If option compact is specified, the trailing zeros at the
1641 end of the list are truncated. This option is only meaning‐
1642 ful together with option decimals.
1643
1644 * If option scientific is specified, the float is formatted
1645 using scientific notation with Decimals digits of precision.
1646
1647 * If Options is [], the function behaves as float_to_list/1.
1648
1649 Examples:
1650
1651 > float_to_list(7.12, [{decimals, 4}]).
1652 "7.1200"
1653 > float_to_list(7.12, [{decimals, 4}, compact]).
1654 "7.12"
1655
1656 floor(Number) -> integer()
1657
1658 Types:
1659
1660 Number = number()
1661
1662 Returns the largest integer not greater than Number. For exam‐
1663 ple:
1664
1665 > floor(-10.5).
1666 -11
1667
1668 Allowed in guard tests.
1669
1670 erlang:fun_info(Fun) -> [{Item, Info}]
1671
1672 Types:
1673
1674 Fun = function()
1675 Item =
1676 arity | env | index | name | module | new_index |
1677 new_uniq |
1678 pid | type | uniq
1679 Info = term()
1680
1681 Returns a list with information about the fun Fun. Each list
1682 element is a tuple. The order of the tuples is undefined, and
1683 more tuples can be added in a future release.
1684
1685 Warning:
1686 This BIF is mainly intended for debugging, but it can sometimes
1687 be useful in library functions that need to verify, for example,
1688 the arity of a fun.
1689
1690
1691 Two types of funs have slightly different semantics:
1692
1693 * A fun created by fun M:F/A is called an external fun. Call‐
1694 ing it will always call the function F with arity A in the
1695 latest code for module M. Notice that module M does not even
1696 need to be loaded when the fun fun M:F/A is created.
1697
1698 * All other funs are called local. When a local fun is called,
1699 the same version of the code that created the fun is called
1700 (even if a newer version of the module has been loaded).
1701
1702 The following elements are always present in the list for both
1703 local and external funs:
1704
1705 {type, Type}:
1706 Type is local or external.
1707
1708 {module, Module}:
1709 Module (an atom) is the module name.
1710
1711 If Fun is a local fun, Module is the module in which the fun
1712 is defined.
1713
1714 If Fun is an external fun, Module is the module that the fun
1715 refers to.
1716
1717 {name, Name}:
1718 Name (an atom) is a function name.
1719
1720 If Fun is a local fun, Name is the name of the local func‐
1721 tion that implements the fun. (This name was generated by
1722 the compiler, and is only of informational use. As it is a
1723 local function, it cannot be called directly.) If no code is
1724 currently loaded for the fun, [] is returned instead of an
1725 atom.
1726
1727 If Fun is an external fun, Name is the name of the exported
1728 function that the fun refers to.
1729
1730 {arity, Arity}:
1731 Arity is the number of arguments that the fun is to be
1732 called with.
1733
1734 {env, Env}:
1735 Env (a list) is the environment or free variables for the
1736 fun. For external funs, the returned list is always empty.
1737
1738 The following elements are only present in the list if Fun is
1739 local:
1740
1741 {pid, Pid}:
1742 Pid is the process identifier of the process that originally
1743 created the fun.
1744
1745 It might point to the init process if the Fun was statically
1746 allocated when module was loaded (this optimisation is per‐
1747 formed for local functions that do not capture the enviorn‐
1748 ment).
1749
1750 {index, Index}:
1751 Index (an integer) is an index into the module fun table.
1752
1753 {new_index, Index}:
1754 Index (an integer) is an index into the module fun table.
1755
1756 {new_uniq, Uniq}:
1757 Uniq (a binary) is a unique value for this fun. It is calcu‐
1758 lated from the compiled code for the entire module.
1759
1760 {uniq, Uniq}:
1761 Uniq (an integer) is a unique value for this fun. As from
1762 Erlang/OTP R15, this integer is calculated from the compiled
1763 code for the entire module. Before Erlang/OTP R15, this
1764 integer was based on only the body of the fun.
1765
1766 erlang:fun_info(Fun, Item) -> {Item, Info}
1767
1768 Types:
1769
1770 Fun = function()
1771 Item = fun_info_item()
1772 Info = term()
1773 fun_info_item() =
1774 arity | env | index | name | module | new_index | new_uniq |
1775 pid | type | uniq
1776
1777 Returns information about Fun as specified by Item, in the form
1778 {Item,Info}.
1779
1780 For any fun, Item can be any of the atoms module, name, arity,
1781 env, or type.
1782
1783 For a local fun, Item can also be any of the atoms index,
1784 new_index, new_uniq, uniq, and pid. For an external fun, the
1785 value of any of these items is always the atom undefined.
1786
1787 See erlang:fun_info/1.
1788
1789 erlang:fun_to_list(Fun) -> string()
1790
1791 Types:
1792
1793 Fun = function()
1794
1795 Returns a string corresponding to the text representation of
1796 Fun.
1797
1798 erlang:function_exported(Module, Function, Arity) -> boolean()
1799
1800 Types:
1801
1802 Module = module()
1803 Function = atom()
1804 Arity = arity()
1805
1806 Returns true if the module Module is loaded and contains an
1807 exported function Function/Arity, or if there is a BIF (a built-
1808 in function implemented in C) with the specified name, otherwise
1809 returns false.
1810
1811 Note:
1812 This function used to return false for BIFs before Erlang/OTP
1813 18.0.
1814
1815
1816 garbage_collect() -> true
1817
1818 Forces an immediate garbage collection of the executing process.
1819 The function is not to be used unless it has been noticed (or
1820 there are good reasons to suspect) that the spontaneous garbage
1821 collection will occur too late or not at all.
1822
1823 Warning:
1824 Improper use can seriously degrade system performance.
1825
1826
1827 garbage_collect(Pid) -> GCResult
1828
1829 Types:
1830
1831 Pid = pid()
1832 GCResult = boolean()
1833
1834 The same as garbage_collect(Pid, []).
1835
1836 garbage_collect(Pid, OptionList) -> GCResult | async
1837
1838 Types:
1839
1840 Pid = pid()
1841 RequestId = term()
1842 Option = {async, RequestId} | {type, major | minor}
1843 OptionList = [Option]
1844 GCResult = boolean()
1845
1846 Garbage collects the node local process identified by Pid.
1847
1848 Option:
1849
1850 {async, RequestId}:
1851 The function garbage_collect/2 returns the value async imme‐
1852 diately after the request has been sent. When the request
1853 has been processed, the process that called this function is
1854 passed a message on the form {garbage_collect, RequestId,
1855 GCResult}.
1856
1857 {type, 'major' | 'minor'}:
1858 Triggers garbage collection of requested type. Default value
1859 is 'major', which would trigger a fullsweep GC. The option
1860 'minor' is considered a hint and may lead to either minor or
1861 major GC run.
1862
1863 If Pid equals self(), and no async option has been passed, the
1864 garbage collection is performed at once, that is, the same as
1865 calling garbage_collect/0. Otherwise a request for garbage col‐
1866 lection is sent to the process identified by Pid, and will be
1867 handled when appropriate. If no async option has been passed,
1868 the caller blocks until GCResult is available and can be
1869 returned.
1870
1871 GCResult informs about the result of the garbage collection
1872 request as follows:
1873
1874 true:
1875 The process identified by Pid has been garbage collected.
1876
1877 false:
1878 No garbage collection was performed, as the process identi‐
1879 fied by Pid terminated before the request could be satis‐
1880 fied.
1881
1882 Notice that the same caveats apply as for garbage_collect/0.
1883
1884 Failures:
1885
1886 badarg:
1887 If Pid is not a node local process identifier.
1888
1889 badarg:
1890 If OptionList is an invalid list of options.
1891
1892 get() -> [{Key, Val}]
1893
1894 Types:
1895
1896 Key = Val = term()
1897
1898 Returns the process dictionary as a list of {Key, Val} tuples,
1899 for example:
1900
1901 > put(key1, merry),
1902 put(key2, lambs),
1903 put(key3, {are, playing}),
1904 get().
1905 [{key1,merry},{key2,lambs},{key3,{are,playing}}]
1906
1907 get(Key) -> Val | undefined
1908
1909 Types:
1910
1911 Key = Val = term()
1912
1913 Returns the value Val associated with Key in the process dictio‐
1914 nary, or undefined if Key does not exist. Example:
1915
1916 > put(key1, merry),
1917 put(key2, lambs),
1918 put({any, [valid, term]}, {are, playing}),
1919 get({any, [valid, term]}).
1920 {are,playing}
1921
1922 erlang:get_cookie() -> Cookie | nocookie
1923
1924 Types:
1925
1926 Cookie = atom()
1927
1928 Returns the magic cookie of the local node if the node is alive,
1929 otherwise the atom nocookie.
1930
1931 get_keys() -> [Key]
1932
1933 Types:
1934
1935 Key = term()
1936
1937 Returns a list of all keys present in the process dictionary,
1938 for example:
1939
1940 > put(dog, {animal,1}),
1941 put(cow, {animal,2}),
1942 put(lamb, {animal,3}),
1943 get_keys().
1944 [dog,cow,lamb]
1945
1946 get_keys(Val) -> [Key]
1947
1948 Types:
1949
1950 Val = Key = term()
1951
1952 Returns a list of keys that are associated with the value Val in
1953 the process dictionary, for example:
1954
1955 > put(mary, {1, 2}),
1956 put(had, {1, 2}),
1957 put(a, {1, 2}),
1958 put(little, {1, 2}),
1959 put(dog, {1, 3}),
1960 put(lamb, {1, 2}),
1961 get_keys({1, 2}).
1962 [mary,had,a,little,lamb]
1963
1964 erlang:get_stacktrace() -> [stack_item()]
1965
1966 Types:
1967
1968 stack_item() =
1969 {Module :: module(),
1970 Function :: atom(),
1971 Arity :: arity() | (Args :: [term()]),
1972 Location ::
1973 [{file, Filename :: string()} |
1974 {line, Line :: integer() >= 1}]}
1975
1976 Warning:
1977 erlang:get_stacktrace/0 is deprecated and will stop working in a
1978 future release.
1979
1980
1981 Instead of using erlang:get_stacktrace/0 to retrieve the call
1982 stack back-trace, use the following syntax:
1983
1984 try Expr
1985 catch
1986 Class:Reason:Stacktrace ->
1987 {Class,Reason,Stacktrace}
1988 end
1989
1990 erlang:get_stacktrace/0 retrieves the call stack back-trace
1991 (stacktrace) for an exception that has just been caught in the
1992 calling process as a list of {Module,Function,Arity,Location}
1993 tuples. Field Arity in the first tuple can be the argument list
1994 of that function call instead of an arity integer, depending on
1995 the exception.
1996
1997 If there has not been any exceptions in a process, the stack‐
1998 trace is []. After a code change for the process, the stacktrace
1999 can also be reset to [].
2000
2001 The stacktrace is the same data as operator catch returns, for
2002 example:
2003
2004 {'EXIT',{badarg,Stacktrace}} = catch abs(x)
2005
2006 Location is a (possibly empty) list of two-tuples that can indi‐
2007 cate the location in the source code of the function. The first
2008 element is an atom describing the type of information in the
2009 second element. The following items can occur:
2010
2011 file:
2012 The second element of the tuple is a string (list of charac‐
2013 ters) representing the filename of the source file of the
2014 function.
2015
2016 line:
2017 The second element of the tuple is the line number (an inte‐
2018 ger > 0) in the source file where the exception occurred or
2019 the function was called.
2020
2021 Warning:
2022 Developers should rely on stacktrace entries only for debugging
2023 purposes.
2024
2025 The VM performs tail call optimization, which does not add new
2026 entries to the stacktrace, and also limits stacktraces to a cer‐
2027 tain depth. Furthermore, compiler options, optimizations and
2028 future changes may add or remove stacktrace entries, causing any
2029 code that expects the stacktrace to be in a certain order or
2030 contain specific items to fail.
2031
2032 The only exception to this rule is error:undef which guarantees
2033 to include the Module, Function and Arity of the attempted func‐
2034 tion as the first stacktrace entry.
2035
2036
2037 See also error/1 and error/2.
2038
2039 group_leader() -> pid()
2040
2041 Returns the process identifier of the group leader for the
2042 process evaluating the function.
2043
2044 Every process is a member of some process group and all groups
2045 have a group leader. All I/O from the group is channeled to the
2046 group leader. When a new process is spawned, it gets the same
2047 group leader as the spawning process. Initially, at system
2048 startup, init is both its own group leader and the group leader
2049 of all processes.
2050
2051 group_leader(GroupLeader, Pid) -> true
2052
2053 Types:
2054
2055 GroupLeader = Pid = pid()
2056
2057 Sets the group leader of Pid to GroupLeader. Typically, this is
2058 used when a process started from a certain shell is to have
2059 another group leader than init.
2060
2061 The group leader should be rarely changed in applications with a
2062 supervision tree, because OTP assumes the group leader of their
2063 processes is their application master.
2064
2065 See also group_leader/0 and OTP design principles related to
2066 starting and stopping applications.
2067
2068 halt() -> no_return()
2069
2070 The same as halt(0, []). Example:
2071
2072 > halt().
2073 os_prompt%
2074
2075 halt(Status) -> no_return()
2076
2077 Types:
2078
2079 Status = integer() >= 0 | abort | string()
2080
2081 The same as halt(Status, []). Example:
2082
2083 > halt(17).
2084 os_prompt% echo $?
2085 17
2086 os_prompt%
2087
2088 halt(Status, Options) -> no_return()
2089
2090 Types:
2091
2092 Status = integer() >= 0 | abort | string()
2093 Options = [Option]
2094 Option = {flush, boolean()}
2095
2096 Status must be a non-negative integer, a string, or the atom
2097 abort. Halts the Erlang runtime system. Has no return value.
2098 Depending on Status, the following occurs:
2099
2100 integer():
2101 The runtime system exits with integer value Status as status
2102 code to the calling environment (OS).
2103
2104 Note:
2105 On many platforms, the OS supports only status codes 0-255. A
2106 too large status code is truncated by clearing the high bits.
2107
2108
2109 string():
2110 An Erlang crash dump is produced with Status as slogan. Then
2111 the runtime system exits with status code 1. The string will
2112 be truncated if longer than 200 characters.
2113
2114 Note:
2115 Before ERTS 9.1 (OTP-20.1) only code points in the range 0-255
2116 was accepted in the string. Now any unicode string is valid.
2117
2118
2119 abort:
2120 The runtime system aborts producing a core dump, if that is
2121 enabled in the OS.
2122
2123 For integer Status, the Erlang runtime system closes all ports
2124 and allows async threads to finish their operations before exit‐
2125 ing. To exit without such flushing, use Option as {flush,false}.
2126
2127 For statuses string() and abort, option flush is ignored and
2128 flushing is not done.
2129
2130 hd(List) -> term()
2131
2132 Types:
2133
2134 List = [term(), ...]
2135
2136 Returns the head of List, that is, the first element, for exam‐
2137 ple:
2138
2139 > hd([1,2,3,4,5]).
2140 1
2141
2142 Allowed in guard tests.
2143
2144 Failure: badarg if List is the empty list [].
2145
2146 erlang:hibernate(Module, Function, Args) -> no_return()
2147
2148 Types:
2149
2150 Module = module()
2151 Function = atom()
2152 Args = [term()]
2153
2154 Puts the calling process into a wait state where its memory
2155 allocation has been reduced as much as possible. This is useful
2156 if the process does not expect to receive any messages soon.
2157
2158 The process is awaken when a message is sent to it, and control
2159 resumes in Module:Function with the arguments specified by Args
2160 with the call stack emptied, meaning that the process terminates
2161 when that function returns. Thus erlang:hibernate/3 never
2162 returns to its caller.
2163
2164 If the process has any message in its message queue, the process
2165 is awakened immediately in the same way as described earlier.
2166
2167 In more technical terms, erlang:hibernate/3 discards the call
2168 stack for the process, and then garbage collects the process.
2169 After this, all live data is in one continuous heap. The heap is
2170 then shrunken to the exact same size as the live data that it
2171 holds (even if that size is less than the minimum heap size for
2172 the process).
2173
2174 If the size of the live data in the process is less than the
2175 minimum heap size, the first garbage collection occurring after
2176 the process is awakened ensures that the heap size is changed to
2177 a size not smaller than the minimum heap size.
2178
2179 Notice that emptying the call stack means that any surrounding
2180 catch is removed and must be re-inserted after hibernation. One
2181 effect of this is that processes started using proc_lib (also
2182 indirectly, such as gen_server processes), are to use
2183 proc_lib:hibernate/3 instead, to ensure that the exception han‐
2184 dler continues to work when the process wakes up.
2185
2186 erlang:insert_element(Index, Tuple1, Term) -> Tuple2
2187
2188 Types:
2189
2190 Index = integer() >= 1
2191 1..tuple_size(Tuple1) + 1
2192 Tuple1 = Tuple2 = tuple()
2193 Term = term()
2194
2195 Returns a new tuple with element Term inserted at position Index
2196 in tuple Tuple1. All elements from position Index and upwards
2197 are pushed one step higher in the new tuple Tuple2. Example:
2198
2199 > erlang:insert_element(2, {one, two, three}, new).
2200 {one,new,two,three}
2201
2202 integer_to_binary(Integer) -> binary()
2203
2204 Types:
2205
2206 Integer = integer()
2207
2208 Returns a binary corresponding to the text representation of
2209 Integer, for example:
2210
2211 > integer_to_binary(77).
2212 <<"77">>
2213
2214 integer_to_binary(Integer, Base) -> binary()
2215
2216 Types:
2217
2218 Integer = integer()
2219 Base = 2..36
2220
2221 Returns a binary corresponding to the text representation of
2222 Integer in base Base, for example:
2223
2224 > integer_to_binary(1023, 16).
2225 <<"3FF">>
2226
2227 integer_to_list(Integer) -> string()
2228
2229 Types:
2230
2231 Integer = integer()
2232
2233 Returns a string corresponding to the text representation of
2234 Integer, for example:
2235
2236 > integer_to_list(77).
2237 "77"
2238
2239 integer_to_list(Integer, Base) -> string()
2240
2241 Types:
2242
2243 Integer = integer()
2244 Base = 2..36
2245
2246 Returns a string corresponding to the text representation of
2247 Integer in base Base, for example:
2248
2249 > integer_to_list(1023, 16).
2250 "3FF"
2251
2252 iolist_size(Item) -> integer() >= 0
2253
2254 Types:
2255
2256 Item = iolist() | binary()
2257
2258 Returns an integer, that is the size in bytes, of the binary
2259 that would be the result of iolist_to_binary(Item), for example:
2260
2261 > iolist_size([1,2|<<3,4>>]).
2262 4
2263
2264 iolist_to_binary(IoListOrBinary) -> binary()
2265
2266 Types:
2267
2268 IoListOrBinary = iolist() | binary()
2269
2270 Returns a binary that is made from the integers and binaries in
2271 IoListOrBinary, for example:
2272
2273 > Bin1 = <<1,2,3>>.
2274 <<1,2,3>>
2275 > Bin2 = <<4,5>>.
2276 <<4,5>>
2277 > Bin3 = <<6>>.
2278 <<6>>
2279 > iolist_to_binary([Bin1,1,[2,3,Bin2],4|Bin3]).
2280 <<1,2,3,1,2,3,4,5,4,6>>
2281
2282 erlang:iolist_to_iovec(IoListOrBinary) -> iovec()
2283
2284 Types:
2285
2286 IoListOrBinary = iolist() | binary()
2287
2288 Returns an iovec that is made from the integers and binaries in
2289 IoListOrBinary.
2290
2291 is_alive() -> boolean()
2292
2293 Returns true if the local node is alive (that is, if the node
2294 can be part of a distributed system), otherwise false.
2295
2296 is_atom(Term) -> boolean()
2297
2298 Types:
2299
2300 Term = term()
2301
2302 Returns true if Term is an atom, otherwise false.
2303
2304 Allowed in guard tests.
2305
2306 is_binary(Term) -> boolean()
2307
2308 Types:
2309
2310 Term = term()
2311
2312 Returns true if Term is a binary, otherwise false.
2313
2314 A binary always contains a complete number of bytes.
2315
2316 Allowed in guard tests.
2317
2318 is_bitstring(Term) -> boolean()
2319
2320 Types:
2321
2322 Term = term()
2323
2324 Returns true if Term is a bitstring (including a binary), other‐
2325 wise false.
2326
2327 Allowed in guard tests.
2328
2329 is_boolean(Term) -> boolean()
2330
2331 Types:
2332
2333 Term = term()
2334
2335 Returns true if Term is the atom true or the atom false (that
2336 is, a boolean). Otherwise returns false.
2337
2338 Allowed in guard tests.
2339
2340 erlang:is_builtin(Module, Function, Arity) -> boolean()
2341
2342 Types:
2343
2344 Module = module()
2345 Function = atom()
2346 Arity = arity()
2347
2348 This BIF is useful for builders of cross-reference tools.
2349
2350 Returns true if Module:Function/Arity is a BIF implemented in C,
2351 otherwise false.
2352
2353 is_float(Term) -> boolean()
2354
2355 Types:
2356
2357 Term = term()
2358
2359 Returns true if Term is a floating point number, otherwise
2360 false.
2361
2362 Allowed in guard tests.
2363
2364 is_function(Term) -> boolean()
2365
2366 Types:
2367
2368 Term = term()
2369
2370 Returns true if Term is a fun, otherwise false.
2371
2372 Allowed in guard tests.
2373
2374 is_function(Term, Arity) -> boolean()
2375
2376 Types:
2377
2378 Term = term()
2379 Arity = arity()
2380
2381 Returns true if Term is a fun that can be applied with Arity
2382 number of arguments, otherwise false.
2383
2384 Allowed in guard tests.
2385
2386 is_integer(Term) -> boolean()
2387
2388 Types:
2389
2390 Term = term()
2391
2392 Returns true if Term is an integer, otherwise false.
2393
2394 Allowed in guard tests.
2395
2396 is_list(Term) -> boolean()
2397
2398 Types:
2399
2400 Term = term()
2401
2402 Returns true if Term is a list with zero or more elements, oth‐
2403 erwise false.
2404
2405 Allowed in guard tests.
2406
2407 is_map(Term) -> boolean()
2408
2409 Types:
2410
2411 Term = term()
2412
2413 Returns true if Term is a map, otherwise false.
2414
2415 Allowed in guard tests.
2416
2417 is_map_key(Key, Map) -> boolean()
2418
2419 Types:
2420
2421 Key = term()
2422 Map = map()
2423
2424 Returns true if map Map contains Key and returns false if it
2425 does not contain the Key.
2426
2427 The call fails with a {badmap,Map} exception if Map is not a
2428 map.
2429
2430 Example:
2431
2432 > Map = #{"42" => value}.
2433 #{"42" => value}
2434 > is_map_key("42",Map).
2435 true
2436 > is_map_key(value,Map).
2437 false
2438
2439 Allowed in guard tests.
2440
2441 is_number(Term) -> boolean()
2442
2443 Types:
2444
2445 Term = term()
2446
2447 Returns true if Term is an integer or a floating point number.
2448 Otherwise returns false.
2449
2450 Allowed in guard tests.
2451
2452 is_pid(Term) -> boolean()
2453
2454 Types:
2455
2456 Term = term()
2457
2458 Returns true if Term is a process identifier, otherwise false.
2459
2460 Allowed in guard tests.
2461
2462 is_port(Term) -> boolean()
2463
2464 Types:
2465
2466 Term = term()
2467
2468 Returns true if Term is a port identifier, otherwise false.
2469
2470 Allowed in guard tests.
2471
2472 is_process_alive(Pid) -> boolean()
2473
2474 Types:
2475
2476 Pid = pid()
2477
2478 Pid must refer to a process at the local node.
2479
2480 Returns true if the process exists and is alive, that is, is not
2481 exiting and has not exited. Otherwise returns false.
2482
2483 is_record(Term, RecordTag) -> boolean()
2484
2485 Types:
2486
2487 Term = term()
2488 RecordTag = atom()
2489
2490 Returns true if Term is a tuple and its first element is Record‐
2491 Tag. Otherwise returns false.
2492
2493 Note:
2494 Normally the compiler treats calls to is_record/2 especially. It
2495 emits code to verify that Term is a tuple, that its first ele‐
2496 ment is RecordTag, and that the size is correct. However, if
2497 RecordTag is not a literal atom, the BIF is_record/2 is called
2498 instead and the size of the tuple is not verified.
2499
2500
2501 Allowed in guard tests, if RecordTag is a literal atom.
2502
2503 is_record(Term, RecordTag, Size) -> boolean()
2504
2505 Types:
2506
2507 Term = term()
2508 RecordTag = atom()
2509 Size = integer() >= 0
2510
2511 RecordTag must be an atom.
2512
2513 Returns true if Term is a tuple, its first element is RecordTag,
2514 and its size is Size. Otherwise returns false.
2515
2516 Allowed in guard tests if RecordTag is a literal atom and Size
2517 is a literal integer.
2518
2519 Note:
2520 This BIF is documented for completeness. Usually is_record/2 is
2521 to be used.
2522
2523
2524 is_reference(Term) -> boolean()
2525
2526 Types:
2527
2528 Term = term()
2529
2530 Returns true if Term is a reference, otherwise false.
2531
2532 Allowed in guard tests.
2533
2534 is_tuple(Term) -> boolean()
2535
2536 Types:
2537
2538 Term = term()
2539
2540 Returns true if Term is a tuple, otherwise false.
2541
2542 Allowed in guard tests.
2543
2544 length(List) -> integer() >= 0
2545
2546 Types:
2547
2548 List = [term()]
2549
2550 Returns the length of List, for example:
2551
2552 > length([1,2,3,4,5,6,7,8,9]).
2553 9
2554
2555 Allowed in guard tests.
2556
2557 link(PidOrPort) -> true
2558
2559 Types:
2560
2561 PidOrPort = pid() | port()
2562
2563 Creates a link between the calling process and another process
2564 (or port) PidOrPort, if there is not such a link already. If a
2565 process attempts to create a link to itself, nothing is done.
2566 Returns true.
2567
2568 If PidOrPort does not exist, the behavior of the BIF depends on
2569 if the calling process is trapping exits or not (see
2570 process_flag/2):
2571
2572 * If the calling process is not trapping exits, and checking
2573 PidOrPort is cheap (that is, if PidOrPort is local), link/1
2574 fails with reason noproc.
2575
2576 * Otherwise, if the calling process is trapping exits, and/or
2577 PidOrPort is remote, link/1 returns true, but an exit signal
2578 with reason noproc is sent to the calling process.
2579
2580 list_to_atom(String) -> atom()
2581
2582 Types:
2583
2584 String = string()
2585
2586 Returns the atom whose text representation is String.
2587
2588 As from Erlang/OTP 20, String may contain any Unicode character.
2589 Earlier versions allowed only ISO-latin-1 characters as the
2590 implementation did not allow Unicode characters above 255. For
2591 more information on Unicode support in atoms, see note on UTF-8
2592 encoded atoms in section "External Term Format" in the User's
2593 Guide.
2594
2595 Example:
2596
2597 > list_to_atom("Erlang").
2598
2599 list_to_binary(IoList) -> binary()
2600
2601 Types:
2602
2603 IoList = iolist()
2604
2605 Returns a binary that is made from the integers and binaries in
2606 IoList, for example:
2607
2608 > Bin1 = <<1,2,3>>.
2609 <<1,2,3>>
2610 > Bin2 = <<4,5>>.
2611 <<4,5>>
2612 > Bin3 = <<6>>.
2613 <<6>>
2614 > list_to_binary([Bin1,1,[2,3,Bin2],4|Bin3]).
2615 <<1,2,3,1,2,3,4,5,4,6>>
2616
2617 list_to_bitstring(BitstringList) -> bitstring()
2618
2619 Types:
2620
2621 BitstringList = bitstring_list()
2622 bitstring_list() =
2623 maybe_improper_list(byte() | bitstring() | bitstring_list(),
2624 bitstring() | [])
2625
2626 Returns a bitstring that is made from the integers and bit‐
2627 strings in BitstringList. (The last tail in BitstringList is
2628 allowed to be a bitstring.) Example:
2629
2630 > Bin1 = <<1,2,3>>.
2631 <<1,2,3>>
2632 > Bin2 = <<4,5>>.
2633 <<4,5>>
2634 > Bin3 = <<6,7:4>>.
2635 <<6,7:4>>
2636 > list_to_bitstring([Bin1,1,[2,3,Bin2],4|Bin3]).
2637 <<1,2,3,1,2,3,4,5,4,6,7:4>>
2638
2639 list_to_existing_atom(String) -> atom()
2640
2641 Types:
2642
2643 String = string()
2644
2645 Returns the atom whose text representation is String, but only
2646 if there already exists such atom.
2647
2648 Failure: badarg if there does not already exist an atom whose
2649 text representation is String.
2650
2651 Note:
2652 Note that the compiler may optimize away atoms. For example, the
2653 compiler will rewrite atom_to_list(some_atom) to "some_atom". If
2654 that expression is the only mention of the atom some_atom in the
2655 containing module, the atom will not be created when the module
2656 is loaded, and a subsequent call to list_to_exist‐
2657 ing_atom("some_atom") will fail.
2658
2659
2660 list_to_float(String) -> float()
2661
2662 Types:
2663
2664 String = string()
2665
2666 Returns the float whose text representation is String, for exam‐
2667 ple:
2668
2669 > list_to_float("2.2017764e+0").
2670 2.2017764
2671
2672 Failure: badarg if String contains a bad representation of a
2673 float.
2674
2675 list_to_integer(String) -> integer()
2676
2677 Types:
2678
2679 String = string()
2680
2681 Returns an integer whose text representation is String, for
2682 example:
2683
2684 > list_to_integer("123").
2685 123
2686
2687 Failure: badarg if String contains a bad representation of an
2688 integer.
2689
2690 list_to_integer(String, Base) -> integer()
2691
2692 Types:
2693
2694 String = string()
2695 Base = 2..36
2696
2697 Returns an integer whose text representation in base Base is
2698 String, for example:
2699
2700 > list_to_integer("3FF", 16).
2701 1023
2702
2703 Failure: badarg if String contains a bad representation of an
2704 integer.
2705
2706 list_to_pid(String) -> pid()
2707
2708 Types:
2709
2710 String = string()
2711
2712 Returns a process identifier whose text representation is a
2713 String, for example:
2714
2715 > list_to_pid("<0.4.1>").
2716 <0.4.1>
2717
2718 Failure: badarg if String contains a bad representation of a
2719 process identifier.
2720
2721 Warning:
2722 This BIF is intended for debugging and is not to be used in
2723 application programs.
2724
2725
2726 list_to_port(String) -> port()
2727
2728 Types:
2729
2730 String = string()
2731
2732 Returns a port identifier whose text representation is a String,
2733 for example:
2734
2735 > list_to_port("#Port<0.4>").
2736 #Port<0.4>
2737
2738 Failure: badarg if String contains a bad representation of a
2739 port identifier.
2740
2741 Warning:
2742 This BIF is intended for debugging and is not to be used in
2743 application programs.
2744
2745
2746 list_to_ref(String) -> reference()
2747
2748 Types:
2749
2750 String = string()
2751
2752 Returns a reference whose text representation is a String, for
2753 example:
2754
2755 > list_to_ref("#Ref<0.4192537678.4073193475.71181>").
2756 #Ref<0.4192537678.4073193475.71181>
2757
2758 Failure: badarg if String contains a bad representation of a
2759 reference.
2760
2761 Warning:
2762 This BIF is intended for debugging and is not to be used in
2763 application programs.
2764
2765
2766 list_to_tuple(List) -> tuple()
2767
2768 Types:
2769
2770 List = [term()]
2771
2772 Returns a tuple corresponding to List, for example
2773
2774 > list_to_tuple([share, ['Ericsson_B', 163]]).
2775 {share, ['Ericsson_B', 163]}
2776
2777 List can contain any Erlang terms.
2778
2779 load_module(Module, Binary) -> {module, Module} | {error, Reason}
2780
2781 Types:
2782
2783 Module = module()
2784 Binary = binary()
2785 Reason = badfile | not_purged | on_load
2786
2787 If Binary contains the object code for module Module, this BIF
2788 loads that object code. If the code for module Module already
2789 exists, all export references are replaced so they point to the
2790 newly loaded code. The previously loaded code is kept in the
2791 system as old code, as there can still be processes executing
2792 that code.
2793
2794 Returns either {module, Module}, or {error, Reason} if loading
2795 fails. Reason is one of the following:
2796
2797 badfile:
2798 The object code in Binary has an incorrect format or the
2799 object code contains code for another module than Module.
2800
2801 not_purged:
2802 Binary contains a module that cannot be loaded because old
2803 code for this module already exists.
2804
2805 Warning:
2806 This BIF is intended for the code server (see code(3)) and is
2807 not to be used elsewhere.
2808
2809
2810 erlang:load_nif(Path, LoadInfo) -> ok | Error
2811
2812 Types:
2813
2814 Path = string()
2815 LoadInfo = term()
2816 Error = {error, {Reason, Text :: string()}}
2817 Reason =
2818 load_failed | bad_lib | load | reload | upgrade |
2819 old_code
2820
2821 Loads and links a dynamic library containing native implemented
2822 functions (NIFs) for a module. Path is a file path to the share‐
2823 able object/dynamic library file minus the OS-dependent file
2824 extension (.so for Unix and .dll for Windows). Notice that on
2825 most OSs the library has to have a different name on disc when
2826 an upgrade of the nif is done. If the name is the same, but the
2827 contents differ, the old library may be loaded instead. For
2828 information on how to implement a NIF library, see erl_nif(3).
2829
2830 LoadInfo can be any term. It is passed on to the library as part
2831 of the initialization. A good practice is to include a module
2832 version number to support future code upgrade scenarios.
2833
2834 The call to load_nif/2 must be made directly from the Erlang
2835 code of the module that the NIF library belongs to. It returns
2836 either ok, or {error,{Reason,Text}} if loading fails. Reason is
2837 one of the following atoms while Text is a human readable string
2838 that can give more information about the failure:
2839
2840 load_failed:
2841 The OS failed to load the NIF library.
2842
2843 bad_lib:
2844 The library did not fulfill the requirements as a NIF
2845 library of the calling module.
2846
2847 load | upgrade:
2848 The corresponding library callback was unsuccessful.
2849
2850 reload:
2851 A NIF library is already loaded for this module instance.
2852 The previously deprecated reload feature was removed in OTP
2853 20.
2854
2855 old_code:
2856 The call to load_nif/2 was made from the old code of a mod‐
2857 ule that has been upgraded; this is not allowed.
2858
2859 notsup:
2860 Lack of support. Such as loading NIF library for a HiPE com‐
2861 piled module.
2862
2863 erlang:loaded() -> [Module]
2864
2865 Types:
2866
2867 Module = module()
2868
2869 Returns a list of all loaded Erlang modules (current and old
2870 code), including preloaded modules.
2871
2872 See also code(3).
2873
2874 erlang:localtime() -> DateTime
2875
2876 Types:
2877
2878 DateTime = calendar:datetime()
2879
2880 Returns the current local date and time, {{Year, Month, Day},
2881 {Hour, Minute, Second}}, for example:
2882
2883 > erlang:localtime().
2884 {{1996,11,6},{14,45,17}}
2885
2886 The time zone and Daylight Saving Time correction depend on the
2887 underlying OS.
2888
2889 erlang:localtime_to_universaltime(Localtime) -> Universaltime
2890
2891 Types:
2892
2893 Localtime = Universaltime = calendar:datetime()
2894
2895 Converts local date and time to Universal Time Coordinated
2896 (UTC), if supported by the underlying OS. Otherwise no conver‐
2897 sion is done and Localtime is returned. Example:
2898
2899 > erlang:localtime_to_universaltime({{1996,11,6},{14,45,17}}).
2900 {{1996,11,6},{13,45,17}}
2901
2902 Failure: badarg if Localtime denotes an invalid date and time.
2903
2904 erlang:localtime_to_universaltime(Localtime, IsDst) ->
2905 Universaltime
2906
2907 Types:
2908
2909 Localtime = Universaltime = calendar:datetime()
2910 IsDst = true | false | undefined
2911
2912 Converts local date and time to Universal Time Coordinated (UTC)
2913 as erlang:localtime_to_universaltime/1, but the caller decides
2914 if Daylight Saving Time is active.
2915
2916 If IsDst == true, Localtime is during Daylight Saving Time, if
2917 IsDst == false it is not. If IsDst == undefined, the underlying
2918 OS can guess, which is the same as calling erlang:local‐
2919 time_to_universaltime(Localtime).
2920
2921 Examples:
2922
2923 > erlang:localtime_to_universaltime({{1996,11,6},{14,45,17}}, true).
2924 {{1996,11,6},{12,45,17}}
2925 > erlang:localtime_to_universaltime({{1996,11,6},{14,45,17}}, false).
2926 {{1996,11,6},{13,45,17}}
2927 > erlang:localtime_to_universaltime({{1996,11,6},{14,45,17}}, undefined).
2928 {{1996,11,6},{13,45,17}}
2929
2930 Failure: badarg if Localtime denotes an invalid date and time.
2931
2932 make_ref() -> reference()
2933
2934 Returns a unique reference. The reference is unique among con‐
2935 nected nodes.
2936
2937 Warning:
2938 Known issue: When a node is restarted multiple times with the
2939 same node name, references created on a newer node can be mis‐
2940 taken for a reference created on an older node with the same
2941 node name.
2942
2943
2944 erlang:make_tuple(Arity, InitialValue) -> tuple()
2945
2946 Types:
2947
2948 Arity = arity()
2949 InitialValue = term()
2950
2951 Creates a new tuple of the specified Arity, where all elements
2952 are InitialValue, for example:
2953
2954 > erlang:make_tuple(4, []).
2955 {[],[],[],[]}
2956
2957 erlang:make_tuple(Arity, DefaultValue, InitList) -> tuple()
2958
2959 Types:
2960
2961 Arity = arity()
2962 DefaultValue = term()
2963 InitList = [{Position :: integer() >= 1, term()}]
2964
2965 Creates a tuple of size Arity, where each element has value
2966 DefaultValue, and then fills in values from InitList. Each list
2967 element in InitList must be a two-tuple, where the first element
2968 is a position in the newly created tuple and the second element
2969 is any term. If a position occurs more than once in the list,
2970 the term corresponding to the last occurrence is used. Example:
2971
2972 > erlang:make_tuple(5, [], [{2,ignored},{5,zz},{2,aa}]).
2973 {[],aa,[],[],zz}
2974
2975 map_get(Key, Map) -> Value
2976
2977 Types:
2978
2979 Map = map()
2980 Key = Value = any()
2981
2982 Returns value Value associated with Key if Map contains Key.
2983
2984 The call fails with a {badmap,Map} exception if Map is not a
2985 map, or with a {badkey,Key} exception if no value is associated
2986 with Key.
2987
2988 Example:
2989
2990 > Key = 1337,
2991 Map = #{42 => value_two,1337 => "value one","a" => 1},
2992 map_get(Key,Map).
2993 "value one"
2994
2995 Allowed in guard tests.
2996
2997 map_size(Map) -> integer() >= 0
2998
2999 Types:
3000
3001 Map = map()
3002
3003 Returns an integer, which is the number of key-value pairs in
3004 Map, for example:
3005
3006 > map_size(#{a=>1, b=>2, c=>3}).
3007 3
3008
3009 Allowed in guard tests.
3010
3011 erlang:match_spec_test(MatchAgainst, MatchSpec, Type) ->
3012 TestResult
3013
3014 Types:
3015
3016 MatchAgainst = [term()] | tuple()
3017 MatchSpec = term()
3018 Type = table | trace
3019 TestResult =
3020 {ok, term(), [return_trace], [{error | warning,
3021 string()}]} |
3022 {error, [{error | warning, string()}]}
3023
3024 Tests a match specification used in calls to ets:select/2 and
3025 erlang:trace_pattern/3. The function tests both a match specifi‐
3026 cation for "syntactic" correctness and runs the match specifica‐
3027 tion against the object. If the match specification contains
3028 errors, the tuple {error, Errors} is returned, where Errors is a
3029 list of natural language descriptions of what was wrong with the
3030 match specification.
3031
3032 If Type is table, the object to match against is to be a tuple.
3033 The function then returns {ok,Result,[],Warnings}, where Result
3034 is what would have been the result in a real ets:select/2 call,
3035 or false if the match specification does not match the object
3036 tuple.
3037
3038 If Type is trace, the object to match against is to be a list.
3039 The function returns {ok, Result, Flags, Warnings}, where Result
3040 is one of the following:
3041
3042 * true if a trace message is to be emitted
3043
3044 * false if a trace message is not to be emitted
3045
3046 * The message term to be appended to the trace message
3047
3048 Flags is a list containing all the trace flags to be enabled,
3049 currently this is only return_trace.
3050
3051 This is a useful debugging and test tool, especially when writ‐
3052 ing complicated match specifications.
3053
3054 See also ets:test_ms/2.
3055
3056 max(Term1, Term2) -> Maximum
3057
3058 Types:
3059
3060 Term1 = Term2 = Maximum = term()
3061
3062 Returns the largest of Term1 and Term2. If the terms are equal,
3063 Term1 is returned.
3064
3065 erlang:md5(Data) -> Digest
3066
3067 Types:
3068
3069 Data = iodata()
3070 Digest = binary()
3071
3072 Computes an MD5 message digest from Data, where the length of
3073 the digest is 128 bits (16 bytes). Data is a binary or a list of
3074 small integers and binaries.
3075
3076 For more information about MD5, see RFC 1321 - The MD5 Message-
3077 Digest Algorithm.
3078
3079 Warning:
3080 The MD5 Message-Digest Algorithm is not considered safe for
3081 code-signing or software-integrity purposes.
3082
3083
3084 erlang:md5_final(Context) -> Digest
3085
3086 Types:
3087
3088 Context = Digest = binary()
3089
3090 Finishes the update of an MD5 Context and returns the computed
3091 MD5 message digest.
3092
3093 erlang:md5_init() -> Context
3094
3095 Types:
3096
3097 Context = binary()
3098
3099 Creates an MD5 context, to be used in the following calls to
3100 md5_update/2.
3101
3102 erlang:md5_update(Context, Data) -> NewContext
3103
3104 Types:
3105
3106 Context = binary()
3107 Data = iodata()
3108 NewContext = binary()
3109
3110 Update an MD5 Context with Data and returns a NewContext.
3111
3112 erlang:memory() -> [{Type, Size}]
3113
3114 Types:
3115
3116 Type = memory_type()
3117 Size = integer() >= 0
3118 memory_type() =
3119 total | processes | processes_used | system | atom |
3120 atom_used | binary | code | ets
3121
3122 Returns a list with information about memory dynamically allo‐
3123 cated by the Erlang emulator. Each list element is a tuple
3124 {Type, Size}. The first element Type is an atom describing mem‐
3125 ory type. The second element Size is the memory size in bytes.
3126
3127 Memory types:
3128
3129 total:
3130 The total amount of memory currently allocated. This is the
3131 same as the sum of the memory size for processes and system.
3132
3133 processes:
3134 The total amount of memory currently allocated for the
3135 Erlang processes.
3136
3137 processes_used:
3138 The total amount of memory currently used by the Erlang pro‐
3139 cesses. This is part of the memory presented as processes
3140 memory.
3141
3142 system:
3143 The total amount of memory currently allocated for the emu‐
3144 lator that is not directly related to any Erlang process.
3145 Memory presented as processes is not included in this mem‐
3146 ory. instrument(3) can be used to get a more detailed break‐
3147 down of what memory is part of this type.
3148
3149 atom:
3150 The total amount of memory currently allocated for atoms.
3151 This memory is part of the memory presented as system mem‐
3152 ory.
3153
3154 atom_used:
3155 The total amount of memory currently used for atoms. This
3156 memory is part of the memory presented as atom memory.
3157
3158 binary:
3159 The total amount of memory currently allocated for binaries.
3160 This memory is part of the memory presented as system mem‐
3161 ory.
3162
3163 code:
3164 The total amount of memory currently allocated for Erlang
3165 code. This memory is part of the memory presented as system
3166 memory.
3167
3168 ets:
3169 The total amount of memory currently allocated for ETS
3170 tables. This memory is part of the memory presented as sys‐
3171 tem memory.
3172
3173 low:
3174 Only on 64-bit halfword emulator. The total amount of memory
3175 allocated in low memory areas that are restricted to < 4 GB,
3176 although the system can have more memory.
3177
3178 Can be removed in a future release of the halfword emulator.
3179
3180 maximum:
3181 The maximum total amount of memory allocated since the emu‐
3182 lator was started. This tuple is only present when the emu‐
3183 lator is run with instrumentation.
3184
3185 For information on how to run the emulator with instrumenta‐
3186 tion, see instrument(3) and/or erl(1).
3187
3188 Note:
3189 The system value is not complete. Some allocated memory that is
3190 to be part of this value is not.
3191
3192 When the emulator is run with instrumentation, the system value
3193 is more accurate, but memory directly allocated for malloc (and
3194 friends) is still not part of the system value. Direct calls to
3195 malloc are only done from OS-specific runtime libraries and per‐
3196 haps from user-implemented Erlang drivers that do not use the
3197 memory allocation functions in the driver interface.
3198
3199 As the total value is the sum of processes and system, the error
3200 in system propagates to the total value.
3201
3202 The different amounts of memory that are summed are not gathered
3203 atomically, which introduces an error in the result.
3204
3205
3206 The different values have the following relation to each other.
3207 Values beginning with an uppercase letter is not part of the
3208 result.
3209
3210 total = processes + system
3211 processes = processes_used + ProcessesNotUsed
3212 system = atom + binary + code + ets + OtherSystem
3213 atom = atom_used + AtomNotUsed
3214 RealTotal = processes + RealSystem
3215 RealSystem = system + MissedSystem
3216
3217 More tuples in the returned list can be added in a future
3218 release.
3219
3220 Note:
3221 The total value is supposed to be the total amount of memory
3222 dynamically allocated by the emulator. Shared libraries, the
3223 code of the emulator itself, and the emulator stacks are not
3224 supposed to be included. That is, the total value is not sup‐
3225 posed to be equal to the total size of all pages mapped to the
3226 emulator.
3227
3228 Also, because of fragmentation and prereservation of memory
3229 areas, the size of the memory segments containing the dynami‐
3230 cally allocated memory blocks can be much larger than the total
3231 size of the dynamically allocated memory blocks.
3232
3233
3234 Note:
3235 As from ERTS 5.6.4, erlang:memory/0 requires that all
3236 erts_alloc(3) allocators are enabled (default behavior).
3237
3238
3239 Failure: notsup if an erts_alloc(3) allocator has been disabled.
3240
3241 erlang:memory(Type :: memory_type()) -> integer() >= 0
3242
3243 erlang:memory(TypeList :: [memory_type()]) ->
3244 [{memory_type(), integer() >= 0}]
3245
3246 Types:
3247
3248 memory_type() =
3249 total | processes | processes_used | system | atom |
3250 atom_used | binary | code | ets
3251
3252 Returns the memory size in bytes allocated for memory of type
3253 Type. The argument can also be specified as a list of mem‐
3254 ory_type() atoms, in which case a corresponding list of {mem‐
3255 ory_type(), Size :: integer >= 0} tuples is returned.
3256
3257 Note:
3258 As from ERTS 5.6.4, erlang:memory/1 requires that all
3259 erts_alloc(3) allocators are enabled (default behavior).
3260
3261
3262 Failures:
3263
3264 badarg:
3265 If Type is not one of the memory types listed in the
3266 description of erlang:memory/0.
3267
3268 badarg:
3269 If maximum is passed as Type and the emulator is not run in
3270 instrumented mode.
3271
3272 notsup:
3273 If an erts_alloc(3) allocator has been disabled.
3274
3275 See also erlang:memory/0.
3276
3277 min(Term1, Term2) -> Minimum
3278
3279 Types:
3280
3281 Term1 = Term2 = Minimum = term()
3282
3283 Returns the smallest of Term1 and Term2. If the terms are equal,
3284 Term1 is returned.
3285
3286 module_loaded(Module) -> boolean()
3287
3288 Types:
3289
3290 Module = module()
3291
3292 Returns true if the module Module is loaded, otherwise false. It
3293 does not attempt to load the module.
3294
3295 Warning:
3296 This BIF is intended for the code server (see code(3)) and is
3297 not to be used elsewhere.
3298
3299
3300 monitor(Type :: process, Item :: monitor_process_identifier()) ->
3301 MonitorRef
3302
3303 monitor(Type :: port, Item :: monitor_port_identifier()) ->
3304 MonitorRef
3305
3306 monitor(Type :: time_offset, Item :: clock_service) -> MonitorRef
3307
3308 Types:
3309
3310 MonitorRef = reference()
3311 registered_name() = atom()
3312 registered_process_identifier() =
3313 registered_name() | {registered_name(), node()}
3314 monitor_process_identifier() =
3315 pid() | registered_process_identifier()
3316 monitor_port_identifier() = port() | registered_name()
3317
3318 Sends a monitor request of type Type to the entity identified by
3319 Item. If the monitored entity does not exist or it changes moni‐
3320 tored state, the caller of monitor/2 is notified by a message on
3321 the following format:
3322
3323 {Tag, MonitorRef, Type, Object, Info}
3324
3325 Note:
3326 The monitor request is an asynchronous signal. That is, it takes
3327 time before the signal reaches its destination.
3328
3329
3330 Type can be one of the following atoms: process, port or
3331 time_offset.
3332
3333 A process or port monitor is triggered only once, after that it
3334 is removed from both monitoring process and the monitored
3335 entity. Monitors are fired when the monitored process or port
3336 terminates, does not exist at the moment of creation, or if the
3337 connection to it is lost. If the connection to it is lost, we do
3338 not know if it still exists. The monitoring is also turned off
3339 when demonitor/1 is called.
3340
3341 A process or port monitor by name resolves the RegisteredName to
3342 pid() or port() only once at the moment of monitor instantia‐
3343 tion, later changes to the name registration will not affect the
3344 existing monitor.
3345
3346 When a process or port monitor is triggered, a 'DOWN' message is
3347 sent that has the following pattern:
3348
3349 {'DOWN', MonitorRef, Type, Object, Info}
3350
3351 In the monitor message MonitorRef and Type are the same as
3352 described earlier, and:
3353
3354 Object:
3355 The monitored entity, which triggered the event. When moni‐
3356 toring a local process or port, Object will be equal to the
3357 pid() or port() that was being monitored. When monitoring
3358 process or port by name, Object will have format {Regis‐
3359 teredName, Node} where RegisteredName is the name which has
3360 been used with monitor/2 call and Node is local or remote
3361 node name (for ports monitored by name, Node is always local
3362 node name).
3363
3364 Info:
3365 Either the exit reason of the process, noproc (process or
3366 port did not exist at the time of monitor creation), or
3367 noconnection (no connection to the node where the monitored
3368 process resides).
3369
3370 Monitoring a process:
3371 Creates monitor between the current process and another
3372 process identified by Item, which can be a pid() (local or
3373 remote), an atom RegisteredName or a tuple {RegisteredName,
3374 Node} for a registered process, located elsewhere.
3375
3376 Note:
3377 Before ERTS 10.0 (OTP 21.0), monitoring a process could fail
3378 with badarg if the monitored process resided on a primitive
3379 node (such as erl_interface or jinterface), where remote
3380 process monitoring is not implemented.
3381
3382 Now, such a call to monitor will instead succeed and a monitor
3383 is created. But the monitor will only supervise the connec‐
3384 tion. That is, a {'DOWN', _, process, _, noconnection} is the
3385 only message that may be received, as the primitive node have
3386 no way of reporting the status of the monitored process.
3387
3388
3389 Monitoring a port:
3390 Creates monitor between the current process and a port iden‐
3391 tified by Item, which can be a port() (only local), an atom
3392 RegisteredName or a tuple {RegisteredName, Node} for a reg‐
3393 istered port, located on this node. Note, that attempt to
3394 monitor a remote port will result in badarg.
3395
3396 Monitoring a time_offset:
3397 Monitors changes in time offset between Erlang monotonic
3398 time and Erlang system time. One valid Item exists in combi‐
3399 nation with the time_offset Type, namely the atom clock_ser‐
3400 vice. Notice that the atom clock_service is not the regis‐
3401 tered name of a process. In this case it serves as an iden‐
3402 tifier of the runtime system internal clock service at cur‐
3403 rent runtime system instance.
3404
3405 The monitor is triggered when the time offset is changed.
3406 This either if the time offset value is changed, or if the
3407 offset is changed from preliminary to final during finaliza‐
3408 tion of the time offset when the single time warp mode is
3409 used. When a change from preliminary to final time offset is
3410 made, the monitor is triggered once regardless of whether
3411 the time offset value was changed or not.
3412
3413 If the runtime system is in multi time warp mode, the time
3414 offset is changed when the runtime system detects that the
3415 OS system time has changed. The runtime system does, how‐
3416 ever, not detect this immediately when it occurs. A task
3417 checking the time offset is scheduled to execute at least
3418 once a minute, so under normal operation this is to be
3419 detected within a minute, but during heavy load it can take
3420 longer time.
3421
3422 The monitor is not automatically removed after it has been
3423 triggered. That is, repeated changes of the time offset
3424 trigger the monitor repeatedly.
3425
3426 When the monitor is triggered a 'CHANGE' message is sent to
3427 the monitoring process. A 'CHANGE' message has the following
3428 pattern:
3429
3430 {'CHANGE', MonitorRef, Type, Item, NewTimeOffset}
3431
3432 where MonitorRef, Type, and Item are the same as described
3433 above, and NewTimeOffset is the new time offset.
3434
3435 When the 'CHANGE' message has been received you are guaran‐
3436 teed not to retrieve the old time offset when calling
3437 erlang:time_offset(). Notice that you can observe the change
3438 of the time offset when calling erlang:time_offset() before
3439 you get the 'CHANGE' message.
3440
3441 Making several calls to monitor/2 for the same Item and/or Type
3442 is not an error; it results in as many independent monitoring
3443 instances.
3444
3445 The monitor functionality is expected to be extended. That is,
3446 other Types and Items are expected to be supported in a future
3447 release.
3448
3449 Note:
3450 If or when monitor/2 is extended, other possible values for Tag,
3451 Object, and Info in the monitor message will be introduced.
3452
3453
3454 monitor_node(Node, Flag) -> true
3455
3456 Types:
3457
3458 Node = node()
3459 Flag = boolean()
3460
3461 Monitor the status of the node Node. If Flag is true, monitoring
3462 is turned on. If Flag is false, monitoring is turned off.
3463
3464 Making several calls to monitor_node(Node, true) for the same
3465 Node is not an error; it results in as many independent monitor‐
3466 ing instances.
3467
3468 If Node fails or does not exist, the message {nodedown, Node} is
3469 delivered to the process. If a process has made two calls to
3470 monitor_node(Node, true) and Node terminates, two nodedown mes‐
3471 sages are delivered to the process. If there is no connection to
3472 Node, an attempt is made to create one. If this fails, a node‐
3473 down message is delivered.
3474
3475 Nodes connected through hidden connections can be monitored as
3476 any other nodes.
3477
3478 Failure: badarg if the local node is not alive.
3479
3480 erlang:monitor_node(Node, Flag, Options) -> true
3481
3482 Types:
3483
3484 Node = node()
3485 Flag = boolean()
3486 Options = [Option]
3487 Option = allow_passive_connect
3488
3489 Behaves as monitor_node/2 except that it allows an extra option
3490 to be specified, namely allow_passive_connect. This option
3491 allows the BIF to wait the normal network connection time-out
3492 for the monitored node to connect itself, even if it cannot be
3493 actively connected from this node (that is, it is blocked). The
3494 state where this can be useful can only be achieved by using the
3495 Kernel option dist_auto_connect once. If that option is not
3496 used, option allow_passive_connect has no effect.
3497
3498 Note:
3499 Option allow_passive_connect is used internally and is seldom
3500 needed in applications where the network topology and the Kernel
3501 options in effect are known in advance.
3502
3503
3504 Failure: badarg if the local node is not alive or the option
3505 list is malformed.
3506
3507 erlang:monotonic_time() -> integer()
3508
3509 Returns the current Erlang monotonic time in native time unit.
3510 This is a monotonically increasing time since some unspecified
3511 point in time.
3512
3513 Note:
3514 This is a monotonically increasing time, but not a strictly
3515 monotonically increasing time. That is, consecutive calls to
3516 erlang:monotonic_time/0 can produce the same result.
3517
3518 Different runtime system instances will use different unspeci‐
3519 fied points in time as base for their Erlang monotonic clocks.
3520 That is, it is pointless comparing monotonic times from differ‐
3521 ent runtime system instances. Different runtime system instances
3522 can also place this unspecified point in time different relative
3523 runtime system start. It can be placed in the future (time at
3524 start is a negative value), the past (time at start is a posi‐
3525 tive value), or the runtime system start (time at start is
3526 zero). The monotonic time at runtime system start can be
3527 retrieved by calling erlang:system_info(start_time).
3528
3529
3530 erlang:monotonic_time(Unit) -> integer()
3531
3532 Types:
3533
3534 Unit = time_unit()
3535
3536 Returns the current Erlang monotonic time converted into the
3537 Unit passed as argument.
3538
3539 Same as calling erlang:convert_time_unit(erlang:mono‐
3540 tonic_time(), native, Unit), however optimized for commonly used
3541 Units.
3542
3543 erlang:nif_error(Reason) -> no_return()
3544
3545 Types:
3546
3547 Reason = term()
3548
3549 Works exactly like error/1, but Dialyzer thinks that this BIF
3550 will return an arbitrary term. When used in a stub function for
3551 a NIF to generate an exception when the NIF library is not
3552 loaded, Dialyzer does not generate false warnings.
3553
3554 erlang:nif_error(Reason, Args) -> no_return()
3555
3556 Types:
3557
3558 Reason = term()
3559 Args = [term()]
3560
3561 Works exactly like error/2, but Dialyzer thinks that this BIF
3562 will return an arbitrary term. When used in a stub function for
3563 a NIF to generate an exception when the NIF library is not
3564 loaded, Dialyzer does not generate false warnings.
3565
3566 node() -> Node
3567
3568 Types:
3569
3570 Node = node()
3571
3572 Returns the name of the local node. If the node is not alive,
3573 nonode@nohost is returned instead.
3574
3575 Allowed in guard tests.
3576
3577 node(Arg) -> Node
3578
3579 Types:
3580
3581 Arg = pid() | port() | reference()
3582 Node = node()
3583
3584 Returns the node where Arg originates. Arg can be a process
3585 identifier, a reference, or a port. If the local node is not
3586 alive, nonode@nohost is returned.
3587
3588 Allowed in guard tests.
3589
3590 nodes() -> Nodes
3591
3592 Types:
3593
3594 Nodes = [node()]
3595
3596 Returns a list of all visible nodes in the system, except the
3597 local node. Same as nodes(visible).
3598
3599 nodes(Arg) -> Nodes
3600
3601 Types:
3602
3603 Arg = NodeType | [NodeType]
3604 NodeType = visible | hidden | connected | this | known
3605 Nodes = [node()]
3606
3607 Returns a list of nodes according to the argument specified. The
3608 returned result, when the argument is a list, is the list of
3609 nodes satisfying the disjunction(s) of the list elements.
3610
3611 NodeTypes:
3612
3613 visible:
3614 Nodes connected to this node through normal connections.
3615
3616 hidden:
3617 Nodes connected to this node through hidden connections.
3618
3619 connected:
3620 All nodes connected to this node.
3621
3622 this:
3623 This node.
3624
3625 known:
3626 Nodes that are known to this node. That is, connected nodes
3627 and nodes referred to by process identifiers, port identi‐
3628 fiers, and references located on this node. The set of known
3629 nodes is garbage collected. Notice that this garbage collec‐
3630 tion can be delayed. For more information, see erlang:sys‐
3631 tem_info(delayed_node_table_gc).
3632
3633 Some equalities: [node()] = nodes(this), nodes(connected) =
3634 nodes([visible, hidden]), and nodes() = nodes(visible).
3635
3636 now() -> Timestamp
3637
3638 Types:
3639
3640 Timestamp = timestamp()
3641 timestamp() =
3642 {MegaSecs :: integer() >= 0,
3643 Secs :: integer() >= 0,
3644 MicroSecs :: integer() >= 0}
3645
3646 Warning:
3647 This function is deprecated. Do not use it.
3648
3649 For more information, see section Time and Time Correction in
3650 the User's Guide. Specifically, section Dos and Dont's
3651 describes what to use instead of erlang:now/0.
3652
3653
3654 Returns the tuple {MegaSecs, Secs, MicroSecs}, which is the
3655 elapsed time since 00:00 GMT, January 1, 1970 (zero hour), if
3656 provided by the underlying OS. Otherwise some other point in
3657 time is chosen. It is also guaranteed that the following calls
3658 to this BIF return continuously increasing values. Hence, the
3659 return value from erlang:now/0 can be used to generate unique
3660 time stamps. If it is called in a tight loop on a fast machine,
3661 the time of the node can become skewed.
3662
3663 Can only be used to check the local time of day if the time-zone
3664 information of the underlying OS is properly configured.
3665
3666 open_port(PortName, PortSettings) -> port()
3667
3668 Types:
3669
3670 PortName =
3671 {spawn, Command :: string() | binary()} |
3672 {spawn_driver, Command :: string() | binary()} |
3673 {spawn_executable, FileName :: file:name()} |
3674 {fd, In :: integer() >= 0, Out :: integer() >= 0}
3675 PortSettings = [Opt]
3676 Opt =
3677 {packet, N :: 1 | 2 | 4} |
3678 stream |
3679 {line, L :: integer() >= 0} |
3680 {cd, Dir :: string() | binary()} |
3681 {env,
3682 Env ::
3683 [{Name :: os:env_var_name(),
3684 Val :: os:env_var_value() | false}]} |
3685 {args, [string() | binary()]} |
3686 {arg0, string() | binary()} |
3687 exit_status | use_stdio | nouse_stdio | stderr_to_stdout
3688 |
3689 in | out | binary | eof |
3690 {parallelism, Boolean :: boolean()} |
3691 hide
3692
3693 Returns a port identifier as the result of opening a new Erlang
3694 port. A port can be seen as an external Erlang process.
3695
3696 The name of the executable as well as the arguments specifed in
3697 cd, env, args, and arg0 are subject to Unicode filename transla‐
3698 tion if the system is running in Unicode filename mode. To avoid
3699 translation or to force, for example UTF-8, supply the exe‐
3700 cutable and/or arguments as a binary in the correct encoding.
3701 For details, see the module file(3), the function
3702 file:native_name_encoding/0 in Kernel, and the Using Unicode in
3703 Erlang User's Guide.
3704
3705 Note:
3706 The characters in the name (if specified as a list) can only be
3707 > 255 if the Erlang virtual machine is started in Unicode file‐
3708 name translation mode. Otherwise the name of the executable is
3709 limited to the ISO Latin-1 character set.
3710
3711
3712 PortNames:
3713
3714 {spawn, Command}:
3715 Starts an external program. Command is the name of the
3716 external program to be run. Command runs outside the Erlang
3717 work space unless an Erlang driver with the name Command is
3718 found. If found, that driver is started. A driver runs in
3719 the Erlang work space, which means that it is linked with
3720 the Erlang runtime system.
3721
3722 For external programs, PATH is searched (or an equivalent
3723 method is used to find programs, depending on the OS). This
3724 is done by invoking the shell on certain platforms. The
3725 first space-separated token of the command is considered as
3726 the name of the executable (or driver). This (among other
3727 things) makes this option unsuitable for running programs
3728 with spaces in filenames or directory names. If spaces in
3729 executable filenames are desired, use {spawn_executable,
3730 Command} instead.
3731
3732 {spawn_driver, Command}:
3733 Works like {spawn, Command}, but demands the first (space-
3734 separated) token of the command to be the name of a loaded
3735 driver. If no driver with that name is loaded, a badarg
3736 error is raised.
3737
3738 {spawn_executable, FileName}:
3739 Works like {spawn, FileName}, but only runs external exe‐
3740 cutables. FileName in its whole is used as the name of the
3741 executable, including any spaces. If arguments are to be
3742 passed, the PortSettings args and arg0 can be used.
3743
3744 The shell is usually not invoked to start the program, it is
3745 executed directly. PATH (or equivalent) is not searched. To
3746 find a program in PATH to execute, use os:find_executable/1.
3747
3748 Only if a shell script or .bat file is executed, the appro‐
3749 priate command interpreter is invoked implicitly, but there
3750 is still no command-argument expansion or implicit PATH
3751 search.
3752
3753 If FileName cannot be run, an error exception is raised,
3754 with the POSIX error code as the reason. The error reason
3755 can differ between OSs. Typically the error enoent is raised
3756 when an attempt is made to run a program that is not found
3757 and eacces is raised when the specified file is not exe‐
3758 cutable.
3759
3760 {fd, In, Out}:
3761 Allows an Erlang process to access any currently opened file
3762 descriptors used by Erlang. The file descriptor In can be
3763 used for standard input, and the file descriptor Out for
3764 standard output. It is only used for various servers in the
3765 Erlang OS (shell and user). Hence, its use is limited.
3766
3767 PortSettings is a list of settings for the port. The valid set‐
3768 tings are as follows:
3769
3770 {packet, N}:
3771 Messages are preceded by their length, sent in N bytes, with
3772 the most significant byte first. The valid values for N are
3773 1, 2, and 4.
3774
3775 stream:
3776 Output messages are sent without packet lengths. A user-
3777 defined protocol must be used between the Erlang process and
3778 the external object.
3779
3780 {line, L}:
3781 Messages are delivered on a per line basis. Each line
3782 (delimited by the OS-dependent newline sequence) is deliv‐
3783 ered in a single message. The message data format is {Flag,
3784 Line}, where Flag is eol or noeol, and Line is the data
3785 delivered (without the newline sequence).
3786
3787 L specifies the maximum line length in bytes. Lines longer
3788 than this are delivered in more than one message, with Flag
3789 set to noeol for all but the last message. If end of file is
3790 encountered anywhere else than immediately following a new‐
3791 line sequence, the last line is also delivered with Flag set
3792 to noeol. Otherwise lines are delivered with Flag set to
3793 eol.
3794
3795 The {packet, N} and {line, L} settings are mutually exclu‐
3796 sive.
3797
3798 {cd, Dir}:
3799 Only valid for {spawn, Command} and {spawn_executable, File‐
3800 Name}. The external program starts using Dir as its working
3801 directory. Dir must be a string.
3802
3803 {env, Env}:
3804 Types:
3805 Name = os:env_var_name()
3806 Val = os:env_var_value() | false
3807 Env = [{Name, Val}]
3808
3809 Only valid for {spawn, Command}, and {spawn_executable,
3810 FileName}. The environment of the started process is
3811 extended using the environment specifications in Env.
3812
3813 Env is to be a list of tuples {Name, Val}, where Name is the
3814 name of an environment variable, and Val is the value it is
3815 to have in the spawned port process. Both Name and Val must
3816 be strings. The one exception is Val being the atom false
3817 (in analogy with os:getenv/1, which removes the environment
3818 variable.
3819
3820 For information about encoding requirements, see documenta‐
3821 tion of the types for Name and Val.
3822
3823 {args, [ string() | binary() ]}:
3824 Only valid for {spawn_executable, FileName} and specifies
3825 arguments to the executable. Each argument is specified as a
3826 separate string and (on Unix) eventually ends up as one ele‐
3827 ment each in the argument vector. On other platforms, a sim‐
3828 ilar behavior is mimicked.
3829
3830 The arguments are not expanded by the shell before they are
3831 supplied to the executable. Most notably this means that
3832 file wildcard expansion does not occur. To expand wildcards
3833 for the arguments, use filelib:wildcard/1. Notice that even
3834 if the program is a Unix shell script, meaning that the
3835 shell ultimately is invoked, wildcard expansion does not
3836 occur, and the script is provided with the untouched argu‐
3837 ments. On Windows, wildcard expansion is always up to the
3838 program itself, therefore this is not an issue.
3839
3840 The executable name (also known as argv[0]) is not to be
3841 specified in this list. The proper executable name is auto‐
3842 matically used as argv[0], where applicable.
3843
3844 If you explicitly want to set the program name in the argu‐
3845 ment vector, option arg0 can be used.
3846
3847 {arg0, string() | binary()}:
3848 Only valid for {spawn_executable, FileName} and explicitly
3849 specifies the program name argument when running an exe‐
3850 cutable. This can in some circumstances, on some OSs, be
3851 desirable. How the program responds to this is highly sys‐
3852 tem-dependent and no specific effect is guaranteed.
3853
3854 exit_status:
3855 Only valid for {spawn, Command}, where Command refers to an
3856 external program, and for {spawn_executable, FileName}.
3857
3858 When the external process connected to the port exits, a
3859 message of the form {Port,{exit_status,Status}} is sent to
3860 the connected process, where Status is the exit status of
3861 the external process. If the program aborts on Unix, the
3862 same convention is used as the shells do (that is, 128+sig‐
3863 nal).
3864
3865 If option eof is specified also, the messages eof and
3866 exit_status appear in an unspecified order.
3867
3868 If the port program closes its stdout without exiting,
3869 option exit_status does not work.
3870
3871 use_stdio:
3872 Only valid for {spawn, Command} and {spawn_executable, File‐
3873 Name}. It allows the standard input and output (file
3874 descriptors 0 and 1) of the spawned (Unix) process for com‐
3875 munication with Erlang.
3876
3877 nouse_stdio:
3878 The opposite of use_stdio. It uses file descriptors 3 and 4
3879 for communication with Erlang.
3880
3881 stderr_to_stdout:
3882 Affects ports to external programs. The executed program
3883 gets its standard error file redirected to its standard out‐
3884 put file. stderr_to_stdout and nouse_stdio are mutually
3885 exclusive.
3886
3887 overlapped_io:
3888 Affects ports to external programs on Windows only. The
3889 standard input and standard output handles of the port pro‐
3890 gram are, if this option is supplied, opened with flag
3891 FILE_FLAG_OVERLAPPED, so that the port program can (and
3892 must) do overlapped I/O on its standard handles. This is not
3893 normally the case for simple port programs, but an option of
3894 value for the experienced Windows programmer. On all other
3895 platforms, this option is silently discarded.
3896
3897 in:
3898 The port can only be used for input.
3899
3900 out:
3901 The port can only be used for output.
3902
3903 binary:
3904 All I/O from the port is binary data objects as opposed to
3905 lists of bytes.
3906
3907 eof:
3908 The port is not closed at the end of the file and does not
3909 produce an exit signal. Instead, it remains open and a
3910 {Port, eof} message is sent to the process holding the port.
3911
3912 hide:
3913 When running on Windows, suppresses creation of a new con‐
3914 sole window when spawning the port program. (This option has
3915 no effect on other platforms.)
3916
3917 {parallelism, Boolean}:
3918
3919
3920 Sets scheduler hint for port parallelism. If set to true,
3921 the virtual machine schedules port tasks; when doing so, it
3922 improves parallelism in the system. If set to false, the
3923 virtual machine tries to perform port tasks immediately,
3924 improving latency at the expense of parallelism. The default
3925 can be set at system startup by passing command-line argu‐
3926 ment +spp to erl(1).
3927
3928 Default is stream for all port types and use_stdio for spawned
3929 ports.
3930
3931 Failure: if the port cannot be opened, the exit reason is
3932 badarg, system_limit, or the POSIX error code that most closely
3933 describes the error, or einval if no POSIX code is appropriate:
3934
3935 badarg:
3936 Bad input arguments to open_port.
3937
3938 system_limit:
3939 All available ports in the Erlang emulator are in use.
3940
3941 enomem:
3942 Not enough memory to create the port.
3943
3944 eagain:
3945 No more available OS processes.
3946
3947 enametoolong:
3948 Too long external command.
3949
3950 emfile:
3951 No more available file descriptors (for the OS process that
3952 the Erlang emulator runs in).
3953
3954 enfile:
3955 Full file table (for the entire OS).
3956
3957 eacces:
3958 Command specified in {spawn_executable, Command} does not
3959 point out an executable file.
3960
3961 enoent:
3962 FileName specified in {spawn_executable, FileName} does not
3963 point out an existing file.
3964
3965 During use of a port opened using {spawn, Name}, {spawn_driver,
3966 Name}, or {spawn_executable, Name}, errors arising when sending
3967 messages to it are reported to the owning process using signals
3968 of the form {'EXIT', Port, PosixCode}. For the possible values
3969 of PosixCode, see file(3).
3970
3971 The maximum number of ports that can be open at the same time
3972 can be configured by passing command-line flag +Q to erl(1).
3973
3974 erlang:phash(Term, Range) -> Hash
3975
3976 Types:
3977
3978 Term = term()
3979 Range = Hash = integer() >= 1
3980 Range = 1..2^32, Hash = 1..Range
3981
3982 Portable hash function that gives the same hash for the same
3983 Erlang term regardless of machine architecture and ERTS version
3984 (the BIF was introduced in ERTS 4.9.1.1). The function returns a
3985 hash value for Term within the range 1..Range. The maximum value
3986 for Range is 2^32.
3987
3988 erlang:phash2(Term) -> Hash
3989
3990 erlang:phash2(Term, Range) -> Hash
3991
3992 Types:
3993
3994 Term = term()
3995 Range = integer() >= 1
3996 1..2^32
3997 Hash = integer() >= 0
3998 0..Range-1
3999
4000 Portable hash function that gives the same hash for the same
4001 Erlang term regardless of machine architecture and ERTS version
4002 (the BIF was introduced in ERTS 5.2). The function returns a
4003 hash value for Term within the range 0..Range-1. The maximum
4004 value for Range is 2^32. When without argument Range, a value in
4005 the range 0..2^27-1 is returned.
4006
4007 This BIF is always to be used for hashing terms. It distributes
4008 small integers better than phash/2, and it is faster for bignums
4009 and binaries.
4010
4011 Notice that the range 0..Range-1 is different from the range of
4012 phash/2, which is 1..Range.
4013
4014 pid_to_list(Pid) -> string()
4015
4016 Types:
4017
4018 Pid = pid()
4019
4020 Returns a string corresponding to the text representation of
4021 Pid.
4022
4023 erlang:port_call(Port, Operation, Data) -> term()
4024
4025 Types:
4026
4027 Port = port() | atom()
4028 Operation = integer()
4029 Data = term()
4030
4031 Performs a synchronous call to a port. The meaning of Operation
4032 and Data depends on the port, that is, on the port driver. Not
4033 all port drivers support this feature.
4034
4035 Port is a port identifier, referring to a driver.
4036
4037 Operation is an integer, which is passed on to the driver.
4038
4039 Data is any Erlang term. This data is converted to binary term
4040 format and sent to the port.
4041
4042 Returns a term from the driver. The meaning of the returned data
4043 also depends on the port driver.
4044
4045 Failures:
4046
4047 badarg:
4048 If Port is not an identifier of an open port, or the regis‐
4049 tered name of an open port. If the calling process was pre‐
4050 viously linked to the closed port, identified by Port, the
4051 exit signal from the port is guaranteed to be delivered
4052 before this badarg exception occurs.
4053
4054 badarg:
4055 If Operation does not fit in a 32-bit integer.
4056
4057 badarg:
4058 If the port driver does not support synchronous control
4059 operations.
4060
4061 badarg:
4062 If the port driver so decides for any reason (probably some‐
4063 thing wrong with Operation or Data).
4064
4065 Warning:
4066 Do not call port_call with an unknown Port identifier and
4067 expect badarg exception. Any undefined behavior is possible
4068 (including node crash) depending on how the port driver inter‐
4069 prets the supplied arguments.
4070
4071
4072 port_close(Port) -> true
4073
4074 Types:
4075
4076 Port = port() | atom()
4077
4078 Closes an open port. Roughly the same as Port ! {self(), close}
4079 except for the error behavior (see below), being synchronous,
4080 and that the port does not reply with {Port, closed}. Any
4081 process can close a port with port_close/1, not only the port
4082 owner (the connected process). If the calling process is linked
4083 to the port identified by Port, the exit signal from the port is
4084 guaranteed to be delivered before port_close/1 returns.
4085
4086 For comparison: Port ! {self(), close} only fails with badarg if
4087 Port does not refer to a port or a process. If Port is a closed
4088 port, nothing happens. If Port is an open port and the calling
4089 process is the port owner, the port replies with {Port, closed}
4090 when all buffers have been flushed and the port really closes.
4091 If the calling process is not the port owner, the port owner
4092 fails with badsig.
4093
4094 Notice that any process can close a port using Port ! {Por‐
4095 tOwner, close} as if it itself was the port owner, but the reply
4096 always goes to the port owner.
4097
4098 As from Erlang/OTP R16, Port ! {PortOwner, close} is truly asyn‐
4099 chronous. Notice that this operation has always been documented
4100 as an asynchronous operation, while the underlying implementa‐
4101 tion has been synchronous. port_close/1 is however still fully
4102 synchronous because of its error behavior.
4103
4104 Failure: badarg if Port is not an identifier of an open port, or
4105 the registered name of an open port. If the calling process was
4106 previously linked to the closed port, identified by Port, the
4107 exit signal from the port is guaranteed to be delivered before
4108 this badarg exception occurs.
4109
4110 port_command(Port, Data) -> true
4111
4112 Types:
4113
4114 Port = port() | atom()
4115 Data = iodata()
4116
4117 Sends data to a port. Same as Port ! {PortOwner, {command,
4118 Data}} except for the error behavior and being synchronous (see
4119 below). Any process can send data to a port with port_command/2,
4120 not only the port owner (the connected process).
4121
4122 For comparison: Port ! {PortOwner, {command, Data}} only fails
4123 with badarg if Port does not refer to a port or a process. If
4124 Port is a closed port, the data message disappears without a
4125 sound. If Port is open and the calling process is not the port
4126 owner, the port owner fails with badsig. The port owner fails
4127 with badsig also if Data is an invalid I/O list.
4128
4129 Notice that any process can send to a port using Port ! {Por‐
4130 tOwner, {command, Data}} as if it itself was the port owner.
4131
4132 If the port is busy, the calling process is suspended until the
4133 port is not busy any more.
4134
4135 As from Erlang/OTP R16, Port ! {PortOwner, {command, Data}} is
4136 truly asynchronous. Notice that this operation has always been
4137 documented as an asynchronous operation, while the underlying
4138 implementation has been synchronous. port_command/2 is however
4139 still fully synchronous because of its error behavior.
4140
4141 Failures:
4142
4143 badarg:
4144 If Port is not an identifier of an open port, or the regis‐
4145 tered name of an open port. If the calling process was pre‐
4146 viously linked to the closed port, identified by Port, the
4147 exit signal from the port is guaranteed to be delivered
4148 before this badarg exception occurs.
4149
4150 badarg:
4151 If Data is an invalid I/O list.
4152
4153 Warning:
4154 Do not send data to an unknown port. Any undefined behavior is
4155 possible (including node crash) depending on how the port driver
4156 interprets the data.
4157
4158
4159 port_command(Port, Data, OptionList) -> boolean()
4160
4161 Types:
4162
4163 Port = port() | atom()
4164 Data = iodata()
4165 Option = force | nosuspend
4166 OptionList = [Option]
4167
4168 Sends data to a port. port_command(Port, Data, []) equals
4169 port_command(Port, Data).
4170
4171 If the port command is aborted, false is returned, otherwise
4172 true.
4173
4174 If the port is busy, the calling process is suspended until the
4175 port is not busy anymore.
4176
4177 Options:
4178
4179 force:
4180 The calling process is not suspended if the port is busy,
4181 instead the port command is forced through. The call fails
4182 with a notsup exception if the driver of the port does not
4183 support this. For more information, see driver flag
4184 ![CDATA[ERL_DRV_FLAG_SOFT_BUSY]].
4185
4186 nosuspend:
4187 The calling process is not suspended if the port is busy,
4188 instead the port command is aborted and false is returned.
4189
4190 Note:
4191 More options can be added in a future release.
4192
4193
4194 Failures:
4195
4196 badarg:
4197 If Port is not an identifier of an open port, or the regis‐
4198 tered name of an open port. If the calling process was pre‐
4199 viously linked to the closed port, identified by Port, the
4200 exit signal from the port is guaranteed to be delivered
4201 before this badarg exception occurs.
4202
4203 badarg:
4204 If Data is an invalid I/O list.
4205
4206 badarg:
4207 If OptionList is an invalid option list.
4208
4209 notsup:
4210 If option force has been passed, but the driver of the port
4211 does not allow forcing through a busy port.
4212
4213 Warning:
4214 Do not send data to an unknown port. Any undefined behavior is
4215 possible (including node crash) depending on how the port driver
4216 interprets the data.
4217
4218
4219 port_connect(Port, Pid) -> true
4220
4221 Types:
4222
4223 Port = port() | atom()
4224 Pid = pid()
4225
4226 Sets the port owner (the connected port) to Pid. Roughly the
4227 same as Port ! {Owner, {connect, Pid}} except for the following:
4228
4229 * The error behavior differs, see below.
4230
4231 * The port does not reply with {Port,connected}.
4232
4233 * port_connect/1 is synchronous, see below.
4234
4235 * The new port owner gets linked to the port.
4236
4237 The old port owner stays linked to the port and must call
4238 unlink(Port) if this is not desired. Any process can set the
4239 port owner to be any process with port_connect/2.
4240
4241 For comparison: Port ! {self(), {connect, Pid}} only fails with
4242 badarg if Port does not refer to a port or a process. If Port is
4243 a closed port, nothing happens. If Port is an open port and the
4244 calling process is the port owner, the port replies with {Port,
4245 connected} to the old port owner. Notice that the old port owner
4246 is still linked to the port, while the new is not. If Port is an
4247 open port and the calling process is not the port owner, the
4248 port owner fails with badsig. The port owner fails with badsig
4249 also if Pid is not an existing local process identifier.
4250
4251 Notice that any process can set the port owner using Port !
4252 {PortOwner, {connect, Pid}} as if it itself was the port owner,
4253 but the reply always goes to the port owner.
4254
4255 As from Erlang/OTP R16, Port ! {PortOwner, {connect, Pid}} is
4256 truly asynchronous. Notice that this operation has always been
4257 documented as an asynchronous operation, while the underlying
4258 implementation has been synchronous. port_connect/2 is however
4259 still fully synchronous because of its error behavior.
4260
4261 Failures:
4262
4263 badarg:
4264 If Port is not an identifier of an open port, or the regis‐
4265 tered name of an open port. If the calling process was pre‐
4266 viously linked to the closed port, identified by Port, the
4267 exit signal from the port is guaranteed to be delivered
4268 before this badarg exception occurs.
4269
4270 badarg:
4271 If the process identified by Pid is not an existing local
4272 process.
4273
4274 port_control(Port, Operation, Data) -> iodata() | binary()
4275
4276 Types:
4277
4278 Port = port() | atom()
4279 Operation = integer()
4280 Data = iodata()
4281
4282 Performs a synchronous control operation on a port. The meaning
4283 of Operation and Data depends on the port, that is, on the port
4284 driver. Not all port drivers support this control feature.
4285
4286 Returns a list of integers in the range 0..255, or a binary,
4287 depending on the port driver. The meaning of the returned data
4288 also depends on the port driver.
4289
4290 Failures:
4291
4292 badarg:
4293 If Port is not an open port or the registered name of an
4294 open port.
4295
4296 badarg:
4297 If Operation cannot fit in a 32-bit integer.
4298
4299 badarg:
4300 If the port driver does not support synchronous control
4301 operations.
4302
4303 badarg:
4304 If the port driver so decides for any reason (probably
4305 something wrong with Operation or Data).
4306
4307 Warning:
4308 Do not call port_control/3 with an unknown Port identifier and
4309 expect badarg exception. Any undefined behavior is possible
4310 (including node crash) depending on how the port driver inter‐
4311 prets the supplied arguments.
4312
4313
4314 erlang:port_info(Port) -> Result
4315
4316 Types:
4317
4318 Port = port() | atom()
4319 ResultItem =
4320 {registered_name, RegisteredName :: atom()} |
4321 {id, Index :: integer() >= 0} |
4322 {connected, Pid :: pid()} |
4323 {links, Pids :: [pid()]} |
4324 {name, String :: string()} |
4325 {input, Bytes :: integer() >= 0} |
4326 {output, Bytes :: integer() >= 0} |
4327 {os_pid, OsPid :: integer() >= 0 | undefined}
4328 Result = [ResultItem] | undefined
4329
4330 Returns a list containing tuples with information about Port, or
4331 undefined if the port is not open. The order of the tuples is
4332 undefined, and all the tuples are not mandatory. If the port is
4333 closed and the calling process was previously linked to the
4334 port, the exit signal from the port is guaranteed to be deliv‐
4335 ered before port_info/1 returns undefined.
4336
4337 The result contains information about the following Items:
4338
4339 * registered_name (if the port has a registered name)
4340
4341 * id
4342
4343 * connected
4344
4345 * links
4346
4347 * name
4348
4349 * input
4350
4351 * output
4352
4353 For more information about the different Items, see port_info/2.
4354
4355 Failure: badarg if Port is not a local port identifier, or an
4356 atom.
4357
4358 erlang:port_info(Port, Item :: connected) ->
4359 {connected, Pid} | undefined
4360
4361 Types:
4362
4363 Port = port() | atom()
4364 Pid = pid()
4365
4366 Pid is the process identifier of the process connected to the
4367 port.
4368
4369 If the port identified by Port is not open, undefined is
4370 returned. If the port is closed and the calling process was pre‐
4371 viously linked to the port, the exit signal from the port is
4372 guaranteed to be delivered before port_info/2 returns undefined.
4373
4374 Failure: badarg if Port is not a local port identifier, or an
4375 atom.
4376
4377 erlang:port_info(Port, Item :: id) -> {id, Index} | undefined
4378
4379 Types:
4380
4381 Port = port() | atom()
4382 Index = integer() >= 0
4383
4384 Index is the internal index of the port. This index can be used
4385 to separate ports.
4386
4387 If the port identified by Port is not open, undefined is
4388 returned. If the port is closed and the calling process was pre‐
4389 viously linked to the port, the exit signal from the port is
4390 guaranteed to be delivered before port_info/2 returns undefined.
4391
4392 Failure: badarg if Port is not a local port identifier, or an
4393 atom.
4394
4395 erlang:port_info(Port, Item :: input) ->
4396 {input, Bytes} | undefined
4397
4398 Types:
4399
4400 Port = port() | atom()
4401 Bytes = integer() >= 0
4402
4403 Bytes is the total number of bytes read from the port.
4404
4405 If the port identified by Port is not open, undefined is
4406 returned. If the port is closed and the calling process was pre‐
4407 viously linked to the port, the exit signal from the port is
4408 guaranteed to be delivered before port_info/2 returns undefined.
4409
4410 Failure: badarg if Port is not a local port identifier, or an
4411 atom.
4412
4413 erlang:port_info(Port, Item :: links) -> {links, Pids} | undefined
4414
4415 Types:
4416
4417 Port = port() | atom()
4418 Pids = [pid()]
4419
4420 Pids is a list of the process identifiers of the processes that
4421 the port is linked to.
4422
4423 If the port identified by Port is not open, undefined is
4424 returned. If the port is closed and the calling process was pre‐
4425 viously linked to the port, the exit signal from the port is
4426 guaranteed to be delivered before port_info/2 returns undefined.
4427
4428 Failure: badarg if Port is not a local port identifier, or an
4429 atom.
4430
4431 erlang:port_info(Port, Item :: locking) ->
4432 {locking, Locking} | undefined
4433
4434 Types:
4435
4436 Port = port() | atom()
4437 Locking = false | port_level | driver_level
4438
4439 Locking is one of the following:
4440
4441 * port_level (port-specific locking)
4442
4443 * driver_level (driver-specific locking)
4444
4445 Notice that these results are highly implementation-specific and
4446 can change in a future release.
4447
4448 If the port identified by Port is not open, undefined is
4449 returned. If the port is closed and the calling process was pre‐
4450 viously linked to the port, the exit signal from the port is
4451 guaranteed to be delivered before port_info/2 returns undefined.
4452
4453 Failure: badarg if Port is not a local port identifier, or an
4454 atom.
4455
4456 erlang:port_info(Port, Item :: memory) ->
4457 {memory, Bytes} | undefined
4458
4459 Types:
4460
4461 Port = port() | atom()
4462 Bytes = integer() >= 0
4463
4464 Bytes is the total number of bytes allocated for this port by
4465 the runtime system. The port itself can have allocated memory
4466 that is not included in Bytes.
4467
4468 If the port identified by Port is not open, undefined is
4469 returned. If the port is closed and the calling process was pre‐
4470 viously linked to the port, the exit signal from the port is
4471 guaranteed to be delivered before port_info/2 returns undefined.
4472
4473 Failure: badarg if Port is not a local port identifier, or an
4474 atom.
4475
4476 erlang:port_info(Port, Item :: monitors) ->
4477 {monitors, Monitors} | undefined
4478
4479 Types:
4480
4481 Port = port() | atom()
4482 Monitors = [{process, pid()}]
4483
4484 Monitors represent processes monitored by this port.
4485
4486 If the port identified by Port is not open, undefined is
4487 returned. If the port is closed and the calling process was pre‐
4488 viously linked to the port, the exit signal from the port is
4489 guaranteed to be delivered before port_info/2 returns undefined.
4490
4491 Failure: badarg if Port is not a local port identifier, or an
4492 atom.
4493
4494 erlang:port_info(Port, Item :: monitored_by) ->
4495 {monitored_by, MonitoredBy} | undefined
4496
4497 Types:
4498
4499 Port = port() | atom()
4500 MonitoredBy = [pid()]
4501
4502 Returns list of pids that are monitoring given port at the
4503 moment.
4504
4505 If the port identified by Port is not open, undefined is
4506 returned. If the port is closed and the calling process was pre‐
4507 viously linked to the port, the exit signal from the port is
4508 guaranteed to be delivered before port_info/2 returns undefined.
4509
4510 Failure: badarg if Port is not a local port identifier, or an
4511 atom.
4512
4513 erlang:port_info(Port, Item :: name) -> {name, Name} | undefined
4514
4515 Types:
4516
4517 Port = port() | atom()
4518 Name = string()
4519
4520 Name is the command name set by open_port/2.
4521
4522 If the port identified by Port is not open, undefined is
4523 returned. If the port is closed and the calling process was pre‐
4524 viously linked to the port, the exit signal from the port is
4525 guaranteed to be delivered before port_info/2 returns undefined.
4526
4527 Failure: badarg if Port is not a local port identifier, or an
4528 atom.
4529
4530 erlang:port_info(Port, Item :: os_pid) ->
4531 {os_pid, OsPid} | undefined
4532
4533 Types:
4534
4535 Port = port() | atom()
4536 OsPid = integer() >= 0 | undefined
4537
4538 OsPid is the process identifier (or equivalent) of an OS process
4539 created with open_port({spawn | spawn_executable, Command},
4540 Options). If the port is not the result of spawning an OS
4541 process, the value is undefined.
4542
4543 If the port identified by Port is not open, undefined is
4544 returned. If the port is closed and the calling process was pre‐
4545 viously linked to the port, the exit signal from the port is
4546 guaranteed to be delivered before port_info/2 returns undefined.
4547
4548 Failure: badarg if Port is not a local port identifier, or an
4549 atom.
4550
4551 erlang:port_info(Port, Item :: output) ->
4552 {output, Bytes} | undefined
4553
4554 Types:
4555
4556 Port = port() | atom()
4557 Bytes = integer() >= 0
4558
4559 Bytes is the total number of bytes written to the port from
4560 Erlang processes using port_command/2, port_command/3, or Port !
4561 {Owner, {command, Data}.
4562
4563 If the port identified by Port is not open, undefined is
4564 returned. If the port is closed and the calling process was pre‐
4565 viously linked to the port, the exit signal from the port is
4566 guaranteed to be delivered before port_info/2 returns undefined.
4567
4568 Failure: badarg if Port is not a local port identifier, or an
4569 atom.
4570
4571 erlang:port_info(Port, Item :: parallelism) ->
4572 {parallelism, Boolean} | undefined
4573
4574 Types:
4575
4576 Port = port() | atom()
4577 Boolean = boolean()
4578
4579 Boolean corresponds to the port parallelism hint used by this
4580 port. For more information, see option parallelism of
4581 open_port/2.
4582
4583 erlang:port_info(Port, Item :: queue_size) ->
4584 {queue_size, Bytes} | undefined
4585
4586 Types:
4587
4588 Port = port() | atom()
4589 Bytes = integer() >= 0
4590
4591 Bytes is the total number of bytes queued by the port using the
4592 ERTS driver queue implementation.
4593
4594 If the port identified by Port is not open, undefined is
4595 returned. If the port is closed and the calling process was pre‐
4596 viously linked to the port, the exit signal from the port is
4597 guaranteed to be delivered before port_info/2 returns undefined.
4598
4599 Failure: badarg if Port is not a local port identifier, or an
4600 atom.
4601
4602 erlang:port_info(Port, Item :: registered_name) ->
4603 {registered_name, RegisteredName} |
4604 [] | undefined
4605
4606 Types:
4607
4608 Port = port() | atom()
4609 RegisteredName = atom()
4610
4611 RegisteredName is the registered name of the port. If the port
4612 has no registered name, [] is returned.
4613
4614 If the port identified by Port is not open, undefined is
4615 returned. If the port is closed and the calling process was pre‐
4616 viously linked to the port, the exit signal from the port is
4617 guaranteed to be delivered before port_info/2 returns undefined.
4618
4619 Failure: badarg if Port is not a local port identifier, or an
4620 atom.
4621
4622 port_to_list(Port) -> string()
4623
4624 Types:
4625
4626 Port = port()
4627
4628 Returns a string corresponding to the text representation of the
4629 port identifier Port.
4630
4631 erlang:ports() -> [port()]
4632
4633 Returns a list of port identifiers corresponding to all the
4634 ports existing on the local node.
4635
4636 Notice that an exiting port exists, but is not open.
4637
4638 pre_loaded() -> [module()]
4639
4640 Returns a list of Erlang modules that are preloaded in the sys‐
4641 tem. As all loading of code is done through the file system, the
4642 file system must have been loaded previously. Hence, at least
4643 the module init must be preloaded.
4644
4645 erlang:process_display(Pid, Type) -> true
4646
4647 Types:
4648
4649 Pid = pid()
4650 Type = backtrace
4651
4652 Writes information about the local process Pid on standard
4653 error. The only allowed value for the atom Type is backtrace,
4654 which shows the contents of the call stack, including informa‐
4655 tion about the call chain, with the current function printed
4656 first. The format of the output is not further defined.
4657
4658 process_flag(Flag :: trap_exit, Boolean) -> OldBoolean
4659
4660 Types:
4661
4662 Boolean = OldBoolean = boolean()
4663
4664 When trap_exit is set to true, exit signals arriving to a
4665 process are converted to {'EXIT', From, Reason} messages, which
4666 can be received as ordinary messages. If trap_exit is set to
4667 false, the process exits if it receives an exit signal other
4668 than normal and the exit signal is propagated to its linked pro‐
4669 cesses. Application processes are normally not to trap exits.
4670
4671 Returns the old value of the flag.
4672
4673 See also exit/2.
4674
4675 process_flag(Flag :: error_handler, Module) -> OldModule
4676
4677 Types:
4678
4679 Module = OldModule = atom()
4680
4681 Used by a process to redefine the error handler for undefined
4682 function calls and undefined registered processes. Inexperienced
4683 users are not to use this flag, as code auto-loading depends on
4684 the correct operation of the error handling module.
4685
4686 Returns the old value of the flag.
4687
4688 process_flag(Flag :: min_heap_size, MinHeapSize) -> OldMinHeapSize
4689
4690 Types:
4691
4692 MinHeapSize = OldMinHeapSize = integer() >= 0
4693
4694 Changes the minimum heap size for the calling process.
4695
4696 Returns the old value of the flag.
4697
4698 process_flag(Flag :: min_bin_vheap_size, MinBinVHeapSize) ->
4699 OldMinBinVHeapSize
4700
4701 Types:
4702
4703 MinBinVHeapSize = OldMinBinVHeapSize = integer() >= 0
4704
4705 Changes the minimum binary virtual heap size for the calling
4706 process.
4707
4708 Returns the old value of the flag.
4709
4710 process_flag(Flag :: max_heap_size, MaxHeapSize) -> OldMaxHeapSize
4711
4712 Types:
4713
4714 MaxHeapSize = OldMaxHeapSize = max_heap_size()
4715 max_heap_size() =
4716 integer() >= 0 |
4717 #{size => integer() >= 0,
4718 kill => boolean(),
4719 error_logger => boolean()}
4720
4721 This flag sets the maximum heap size for the calling process. If
4722 MaxHeapSize is an integer, the system default values for kill
4723 and error_logger are used.
4724
4725 size:
4726 The maximum size in words of the process. If set to zero,
4727 the heap size limit is disabled. badarg is be thrown if the
4728 value is smaller than min_heap_size. The size check is only
4729 done when a garbage collection is triggered.
4730
4731 size is the entire heap of the process when garbage collec‐
4732 tion is triggered. This includes all generational heaps, the
4733 process stack, any messages that are considered to be part
4734 of the heap, and any extra memory that the garbage collector
4735 needs during collection.
4736
4737 size is the same as can be retrieved using
4738 erlang:process_info(Pid, total_heap_size), or by adding
4739 heap_block_size, old_heap_block_size and mbuf_size from
4740 erlang:process_info(Pid, garbage_collection_info).
4741
4742 kill:
4743 When set to true, the runtime system sends an untrappable
4744 exit signal with reason kill to the process if the maximum
4745 heap size is reached. The garbage collection that triggered
4746 the kill is not completed, instead the process exits as soon
4747 as possible. When set to false, no exit signal is sent to
4748 the process, instead it continues executing.
4749
4750 If kill is not defined in the map, the system default will
4751 be used. The default system default is true. It can be
4752 changed by either option +hmaxk in erl(1), or erlang:sys‐
4753 tem_flag(max_heap_size, MaxHeapSize).
4754
4755 error_logger:
4756 When set to true, the runtime system logs an error event via
4757 logger, containing details about the process when the maxi‐
4758 mum heap size is reached. One log event is sent each time
4759 the limit is reached.
4760
4761 If error_logger is not defined in the map, the system
4762 default is used. The default system default is true. It can
4763 be changed by either the option +hmaxel int erl(1), or
4764 erlang:system_flag(max_heap_size, MaxHeapSize).
4765
4766 The heap size of a process is quite hard to predict, especially
4767 the amount of memory that is used during the garbage collection.
4768 When contemplating using this option, it is recommended to first
4769 run it in production with kill set to false and inspect the log
4770 events to see what the normal peak sizes of the processes in the
4771 system is and then tune the value accordingly.
4772
4773 process_flag(Flag :: message_queue_data, MQD) -> OldMQD
4774
4775 Types:
4776
4777 MQD = OldMQD = message_queue_data()
4778 message_queue_data() = off_heap | on_heap
4779
4780 This flag determines how messages in the message queue are
4781 stored, as follows:
4782
4783 off_heap:
4784 All messages in the message queue will be stored outside of
4785 the process heap. This implies that no messages in the mes‐
4786 sage queue will be part of a garbage collection of the
4787 process.
4788
4789 on_heap:
4790 All messages in the message queue will eventually be placed
4791 on heap. They can however temporarily be stored off heap.
4792 This is how messages always have been stored up until ERTS
4793 8.0.
4794
4795 The default message_queue_data process flag is determined by
4796 command-line argument +hmqd in erl(1).
4797
4798 If the process potentially can get many messages in its queue,
4799 you are advised to set the flag to off_heap. This because a
4800 garbage collection with many messages placed on the heap can
4801 become extremely expensive and the process can consume large
4802 amounts of memory. Performance of the actual message passing is
4803 however generally better when not using flag off_heap.
4804
4805 When changing this flag messages will be moved. This work has
4806 been initiated but not completed when this function call
4807 returns.
4808
4809 Returns the old value of the flag.
4810
4811 process_flag(Flag :: priority, Level) -> OldLevel
4812
4813 Types:
4814
4815 Level = OldLevel = priority_level()
4816 priority_level() = low | normal | high | max
4817
4818 Sets the process priority. Level is an atom. Four priority lev‐
4819 els exist: low, normal, high, and max. Default is normal.
4820
4821 Note:
4822 Priority level max is reserved for internal use in the Erlang
4823 runtime system, and is not to be used by others.
4824
4825
4826 Internally in each priority level, processes are scheduled in a
4827 round robin fashion.
4828
4829 Execution of processes on priority normal and low are inter‐
4830 leaved. Processes on priority low are selected for execution
4831 less frequently than processes on priority normal.
4832
4833 When runnable processes on priority high exist, no processes on
4834 priority low or normal are selected for execution. Notice how‐
4835 ever that this does not mean that no processes on priority low
4836 or normal can run when processes are running on priority high.
4837 When using multiple schedulers, more processes can be running in
4838 parallel than processes on priority high. That is, a low and a
4839 high priority process can execute at the same time.
4840
4841 When runnable processes on priority max exist, no processes on
4842 priority low, normal, or high are selected for execution. As
4843 with priority high, processes on lower priorities can execute in
4844 parallel with processes on priority max.
4845
4846 Scheduling is pre-emptive. Regardless of priority, a process is
4847 pre-empted when it has consumed more than a certain number of
4848 reductions since the last time it was selected for execution.
4849
4850 Note:
4851 Do not depend on the scheduling to remain exactly as it is
4852 today. Scheduling is likely to be changed in a future release to
4853 use available processor cores better.
4854
4855
4856 There is no automatic mechanism for avoiding priority inversion,
4857 such as priority inheritance or priority ceilings. When using
4858 priorities, take this into account and handle such scenarios by
4859 yourself.
4860
4861 Making calls from a high priority process into code that you has
4862 no control over can cause the high priority process to wait for
4863 a process with lower priority. That is, effectively decreasing
4864 the priority of the high priority process during the call. Even
4865 if this is not the case with one version of the code that you
4866 have no control over, it can be the case in a future version of
4867 it. This can, for example, occur if a high priority process
4868 triggers code loading, as the code server runs on priority nor‐
4869 mal.
4870
4871 Other priorities than normal are normally not needed. When other
4872 priorities are used, use them with care, especially priority
4873 high. A process on priority high is only to perform work for
4874 short periods. Busy looping for long periods in a high priority
4875 process causes most likely problems, as important OTP servers
4876 run on priority normal.
4877
4878 Returns the old value of the flag.
4879
4880 process_flag(Flag :: save_calls, N) -> OldN
4881
4882 Types:
4883
4884 N = OldN = 0..10000
4885
4886 N must be an integer in the interval 0..10000. If N > 0, call
4887 saving is made active for the process. This means that informa‐
4888 tion about the N most recent global function calls, BIF calls,
4889 sends, and receives made by the process are saved in a list,
4890 which can be retrieved with process_info(Pid, last_calls). A
4891 global function call is one in which the module of the function
4892 is explicitly mentioned. Only a fixed amount of information is
4893 saved, as follows:
4894
4895 * A tuple {Module, Function, Arity} for function calls
4896
4897 * The atoms send, 'receive', and timeout for sends and
4898 receives ('receive' when a message is received and timeout
4899 when a receive times out)
4900
4901 If N = 0, call saving is disabled for the process, which is the
4902 default. Whenever the size of the call saving list is set, its
4903 contents are reset.
4904
4905 Returns the old value of the flag.
4906
4907 process_flag(Flag :: sensitive, Boolean) -> OldBoolean
4908
4909 Types:
4910
4911 Boolean = OldBoolean = boolean()
4912
4913 Sets or clears flag sensitive for the current process. When a
4914 process has been marked as sensitive by calling
4915 process_flag(sensitive, true), features in the runtime system
4916 that can be used for examining the data or inner working of the
4917 process are silently disabled.
4918
4919 Features that are disabled include (but are not limited to) the
4920 following:
4921
4922 * Tracing. Trace flags can still be set for the process, but
4923 no trace messages of any kind are generated. (If flag sensi‐
4924 tive is turned off, trace messages are again generated if
4925 any trace flags are set.)
4926
4927 * Sequential tracing. The sequential trace token is propagated
4928 as usual, but no sequential trace messages are generated.
4929
4930 process_info/1,2 cannot be used to read out the message queue or
4931 the process dictionary (both are returned as empty lists).
4932
4933 Stack back-traces cannot be displayed for the process.
4934
4935 In crash dumps, the stack, messages, and the process dictionary
4936 are omitted.
4937
4938 If {save_calls,N} has been set for the process, no function
4939 calls are saved to the call saving list. (The call saving list
4940 is not cleared. Also, send, receive, and time-out events are
4941 still added to the list.)
4942
4943 Returns the old value of the flag.
4944
4945 process_flag(Pid, Flag, Value) -> OldValue
4946
4947 Types:
4948
4949 Pid = pid()
4950 Flag = save_calls
4951 Value = OldValue = integer() >= 0
4952
4953 Sets certain flags for the process Pid, in the same manner as
4954 process_flag/2. Returns the old value of the flag. The valid
4955 values for Flag are only a subset of those allowed in
4956 process_flag/2, namely save_calls.
4957
4958 Failure: badarg if Pid is not a local process.
4959
4960 process_info(Pid) -> Info
4961
4962 Types:
4963
4964 Pid = pid()
4965 Info = [InfoTuple] | undefined
4966 InfoTuple = process_info_result_item()
4967 process_info_result_item() =
4968 {backtrace, Bin :: binary()} |
4969 {binary,
4970 BinInfo ::
4971 [{integer() >= 0,
4972 integer() >= 0,
4973 integer() >= 0}]} |
4974 {catchlevel, CatchLevel :: integer() >= 0} |
4975 {current_function,
4976 {Module :: module(), Function :: atom(), Arity :: arity()} |
4977 undefined} |
4978 {current_location,
4979 {Module :: module(),
4980 Function :: atom(),
4981 Arity :: arity(),
4982 Location ::
4983 [{file, Filename :: string()} |
4984 {line, Line :: integer() >= 1}]}} |
4985 {current_stacktrace, Stack :: [stack_item()]} |
4986 {dictionary, Dictionary :: [{Key :: term(), Value :: term()}]} |
4987 {error_handler, Module :: module()} |
4988 {garbage_collection, GCInfo :: [{atom(), integer() >= 0}]} |
4989 {garbage_collection_info,
4990 GCInfo :: [{atom(), integer() >= 0}]} |
4991 {group_leader, GroupLeader :: pid()} |
4992 {heap_size, Size :: integer() >= 0} |
4993 {initial_call, mfa()} |
4994 {links, PidsAndPorts :: [pid() | port()]} |
4995 {last_calls, false | (Calls :: [mfa()])} |
4996 {memory, Size :: integer() >= 0} |
4997 {message_queue_len, MessageQueueLen :: integer() >= 0} |
4998 {messages, MessageQueue :: [term()]} |
4999 {min_heap_size, MinHeapSize :: integer() >= 0} |
5000 {min_bin_vheap_size, MinBinVHeapSize :: integer() >= 0} |
5001 {max_heap_size, MaxHeapSize :: max_heap_size()} |
5002 {monitored_by,
5003 MonitoredBy :: [pid() | port() | nif_resource()]} |
5004 {monitors,
5005 Monitors ::
5006 [{process | port,
5007 Pid ::
5008 pid() |
5009 port() |
5010 {RegName :: atom(), Node :: node()}}]} |
5011 {message_queue_data, MQD :: message_queue_data()} |
5012 {priority, Level :: priority_level()} |
5013 {reductions, Number :: integer() >= 0} |
5014 {registered_name, [] | (Atom :: atom())} |
5015 {sequential_trace_token,
5016 [] | (SequentialTraceToken :: term())} |
5017 {stack_size, Size :: integer() >= 0} |
5018 {status,
5019 Status ::
5020 exiting | garbage_collecting | waiting | running |
5021 runnable | suspended} |
5022 {suspending,
5023 SuspendeeList ::
5024 [{Suspendee :: pid(),
5025 ActiveSuspendCount :: integer() >= 0,
5026 OutstandingSuspendCount :: integer() >= 0}]} |
5027 {total_heap_size, Size :: integer() >= 0} |
5028 {trace, InternalTraceFlags :: integer() >= 0} |
5029 {trap_exit, Boolean :: boolean()}
5030 priority_level() = low | normal | high | max
5031 stack_item() =
5032 {Module :: module(),
5033 Function :: atom(),
5034 Arity :: arity() | (Args :: [term()]),
5035 Location ::
5036 [{file, Filename :: string()} |
5037 {line, Line :: integer() >= 1}]}
5038 max_heap_size() =
5039 integer() >= 0 |
5040 #{size => integer() >= 0,
5041 kill => boolean(),
5042 error_logger => boolean()}
5043 message_queue_data() = off_heap | on_heap
5044
5045 Returns a list containing InfoTuples with miscellaneous informa‐
5046 tion about the process identified by Pid, or undefined if the
5047 process is not alive.
5048
5049 The order of the InfoTuples is undefined and all InfoTuples are
5050 not mandatory. The InfoTuples part of the result can be changed
5051 without prior notice.
5052
5053 The InfoTuples with the following items are part of the result:
5054
5055 * current_function
5056
5057 * initial_call
5058
5059 * status
5060
5061 * message_queue_len
5062
5063 * links
5064
5065 * dictionary
5066
5067 * trap_exit
5068
5069 * error_handler
5070
5071 * priority
5072
5073 * group_leader
5074
5075 * total_heap_size
5076
5077 * heap_size
5078
5079 * stack_size
5080
5081 * reductions
5082
5083 * garbage_collection
5084
5085 If the process identified by Pid has a registered name, also an
5086 InfoTuple with item registered_name is included.
5087
5088 For information about specific InfoTuples, see process_info/2.
5089
5090 Warning:
5091 This BIF is intended for debugging only. For all other purposes,
5092 use process_info/2.
5093
5094
5095 Failure: badarg if Pid is not a local process.
5096
5097 process_info(Pid, Item) -> InfoTuple | [] | undefined
5098
5099 process_info(Pid, ItemList) -> InfoTupleList | [] | undefined
5100
5101 Types:
5102
5103 Pid = pid()
5104 ItemList = [Item]
5105 Item = process_info_item()
5106 InfoTupleList = [InfoTuple]
5107 InfoTuple = process_info_result_item()
5108 process_info_item() =
5109 backtrace | binary | catchlevel | current_function |
5110 current_location | current_stacktrace | dictionary |
5111 error_handler | garbage_collection | garbage_collection_info |
5112 group_leader | heap_size | initial_call | links | last_calls |
5113 memory | message_queue_len | messages | min_heap_size |
5114 min_bin_vheap_size | monitored_by | monitors |
5115 message_queue_data | priority | reductions | registered_name |
5116 sequential_trace_token | stack_size | status | suspending |
5117 total_heap_size | trace | trap_exit
5118 process_info_result_item() =
5119 {backtrace, Bin :: binary()} |
5120 {binary,
5121 BinInfo ::
5122 [{integer() >= 0,
5123 integer() >= 0,
5124 integer() >= 0}]} |
5125 {catchlevel, CatchLevel :: integer() >= 0} |
5126 {current_function,
5127 {Module :: module(), Function :: atom(), Arity :: arity()} |
5128 undefined} |
5129 {current_location,
5130 {Module :: module(),
5131 Function :: atom(),
5132 Arity :: arity(),
5133 Location ::
5134 [{file, Filename :: string()} |
5135 {line, Line :: integer() >= 1}]}} |
5136 {current_stacktrace, Stack :: [stack_item()]} |
5137 {dictionary, Dictionary :: [{Key :: term(), Value :: term()}]} |
5138 {error_handler, Module :: module()} |
5139 {garbage_collection, GCInfo :: [{atom(), integer() >= 0}]} |
5140 {garbage_collection_info,
5141 GCInfo :: [{atom(), integer() >= 0}]} |
5142 {group_leader, GroupLeader :: pid()} |
5143 {heap_size, Size :: integer() >= 0} |
5144 {initial_call, mfa()} |
5145 {links, PidsAndPorts :: [pid() | port()]} |
5146 {last_calls, false | (Calls :: [mfa()])} |
5147 {memory, Size :: integer() >= 0} |
5148 {message_queue_len, MessageQueueLen :: integer() >= 0} |
5149 {messages, MessageQueue :: [term()]} |
5150 {min_heap_size, MinHeapSize :: integer() >= 0} |
5151 {min_bin_vheap_size, MinBinVHeapSize :: integer() >= 0} |
5152 {max_heap_size, MaxHeapSize :: max_heap_size()} |
5153 {monitored_by,
5154 MonitoredBy :: [pid() | port() | nif_resource()]} |
5155 {monitors,
5156 Monitors ::
5157 [{process | port,
5158 Pid ::
5159 pid() |
5160 port() |
5161 {RegName :: atom(), Node :: node()}}]} |
5162 {message_queue_data, MQD :: message_queue_data()} |
5163 {priority, Level :: priority_level()} |
5164 {reductions, Number :: integer() >= 0} |
5165 {registered_name, [] | (Atom :: atom())} |
5166 {sequential_trace_token,
5167 [] | (SequentialTraceToken :: term())} |
5168 {stack_size, Size :: integer() >= 0} |
5169 {status,
5170 Status ::
5171 exiting | garbage_collecting | waiting | running |
5172 runnable | suspended} |
5173 {suspending,
5174 SuspendeeList ::
5175 [{Suspendee :: pid(),
5176 ActiveSuspendCount :: integer() >= 0,
5177 OutstandingSuspendCount :: integer() >= 0}]} |
5178 {total_heap_size, Size :: integer() >= 0} |
5179 {trace, InternalTraceFlags :: integer() >= 0} |
5180 {trap_exit, Boolean :: boolean()}
5181 stack_item() =
5182 {Module :: module(),
5183 Function :: atom(),
5184 Arity :: arity() | (Args :: [term()]),
5185 Location ::
5186 [{file, Filename :: string()} |
5187 {line, Line :: integer() >= 1}]}
5188 priority_level() = low | normal | high | max
5189 max_heap_size() =
5190 integer() >= 0 |
5191 #{size => integer() >= 0,
5192 kill => boolean(),
5193 error_logger => boolean()}
5194 message_queue_data() = off_heap | on_heap
5195
5196 Returns information about the process identified by Pid, as
5197 specified by Item or ItemList. Returns undefined if the process
5198 is not alive.
5199
5200 If the process is alive and a single Item is specified, the
5201 returned value is the corresponding InfoTuple, unless Item =:=
5202 registered_name and the process has no registered name. In this
5203 case, [] is returned. This strange behavior is because of his‐
5204 torical reasons, and is kept for backward compatibility.
5205
5206 If ItemList is specified, the result is InfoTupleList. The Info‐
5207 Tuples in InfoTupleList are included with the corresponding
5208 Items in the same order as the Items were included in ItemList.
5209 Valid Items can be included multiple times in ItemList.
5210
5211 Note:
5212 If registered_name is part of ItemList and the process has no
5213 name registered, a {registered_name, []}, InfoTuple will be
5214 included in the resulting InfoTupleList. This behavior is dif‐
5215 ferent when a single Item =:= registered_name is specified, and
5216 when process_info/1 is used.
5217
5218
5219 Valid InfoTuples with corresponding Items:
5220
5221 {backtrace, Bin}:
5222 Binary Bin contains the same information as the output from
5223 erlang:process_display(Pid, backtrace). Use binary_to_list/1
5224 to obtain the string of characters from the binary.
5225
5226 {binary, BinInfo}:
5227 BinInfo is a list containing miscellaneous information about
5228 binaries on the heap of this process. This InfoTuple can be
5229 changed or removed without prior notice. In the current
5230 implementation BinInfo is a list of tuples. The tuples con‐
5231 tain; BinaryId, BinarySize, BinaryRefcCount.
5232
5233 The message queue is on the heap depending on the process
5234 flag message_queue_data.
5235
5236 {catchlevel, CatchLevel}:
5237 CatchLevel is the number of currently active catches in this
5238 process. This InfoTuple can be changed or removed without
5239 prior notice.
5240
5241 {current_function, {Module, Function, Arity} | undefined}:
5242 Module, Function, Arity is the current function call of the
5243 process. The value undefined can be returned if the process
5244 is currently executing native compiled code.
5245
5246 {current_location, {Module, Function, Arity, Location}}:
5247 Module, Function, Arity is the current function call of the
5248 process. Location is a list of two-tuples describing the
5249 location in the source code.
5250
5251 {current_stacktrace, Stack}:
5252 Returns the current call stack back-trace (stacktrace) of
5253 the process. The stack has the same format as returned by
5254 erlang:get_stacktrace/0. The depth of the stacktrace is
5255 truncated according to the backtrace_depth system flag set‐
5256 ting.
5257
5258 {dictionary, Dictionary}:
5259 Dictionary is the process dictionary.
5260
5261 {error_handler, Module}:
5262 Module is the error handler module used by the process (for
5263 undefined function calls, for example).
5264
5265 {garbage_collection, GCInfo}:
5266 GCInfo is a list containing miscellaneous information about
5267 garbage collection for this process. The content of GCInfo
5268 can be changed without prior notice.
5269
5270 {garbage_collection_info, GCInfo}:
5271 GCInfo is a list containing miscellaneous detailed informa‐
5272 tion about garbage collection for this process. The content
5273 of GCInfo can be changed without prior notice. For details
5274 about the meaning of each item, see gc_minor_start in
5275 erlang:trace/3.
5276
5277 {group_leader, GroupLeader}:
5278 GroupLeader is the group leader for the I/O of the process.
5279
5280 {heap_size, Size}:
5281 Size is the size in words of the youngest heap generation of
5282 the process. This generation includes the process stack.
5283 This information is highly implementation-dependent, and can
5284 change if the implementation changes.
5285
5286 {initial_call, {Module, Function, Arity}}:
5287 Module, Function, Arity is the initial function call with
5288 which the process was spawned.
5289
5290 {links, PidsAndPorts}:
5291 PidsAndPorts is a list of process identifiers and port iden‐
5292 tifiers, with processes or ports to which the process has a
5293 link.
5294
5295 {last_calls, false|Calls}:
5296 The value is false if call saving is not active for the
5297 process (see process_flag/3). If call saving is active, a
5298 list is returned, in which the last element is the most
5299 recent called.
5300
5301 {memory, Size}:
5302
5303
5304 Size is the size in bytes of the process. This includes call
5305 stack, heap, and internal structures.
5306
5307 {message_queue_len, MessageQueueLen}:
5308 MessageQueueLen is the number of messages currently in the
5309 message queue of the process. This is the length of the list
5310 MessageQueue returned as the information item messages (see
5311 below).
5312
5313 {messages, MessageQueue}:
5314 MessageQueue is a list of the messages to the process, which
5315 have not yet been processed.
5316
5317 {min_heap_size, MinHeapSize}:
5318 MinHeapSize is the minimum heap size for the process.
5319
5320 {min_bin_vheap_size, MinBinVHeapSize}:
5321 MinBinVHeapSize is the minimum binary virtual heap size for
5322 the process.
5323
5324 {monitored_by, MonitoredBy}:
5325 A list of identifiers for all the processes, ports and NIF
5326 resources, that are monitoring the process.
5327
5328 {monitors, Monitors}:
5329 A list of monitors (started by monitor/2) that are active
5330 for the process. For a local process monitor or a remote
5331 process monitor by a process identifier, the list consists
5332 of:
5333
5334 {process, Pid}:
5335 Process is monitored by pid.
5336
5337 {process, {RegName, Node}}:
5338 Local or remote process is monitored by name.
5339
5340 {port, PortId}:
5341 Local port is monitored by port id.
5342
5343 {port, {RegName, Node}}:
5344 Local port is monitored by name. Please note, that remote
5345 port monitors are not supported, so Node will always be
5346 the local node name.
5347
5348 {message_queue_data, MQD}:
5349 Returns the current state of process flag mes‐
5350 sage_queue_data. MQD is either off_heap or on_heap. For more
5351 information, see the documentation of process_flag(mes‐
5352 sage_queue_data, MQD).
5353
5354 {priority, Level}:
5355 Level is the current priority level for the process. For
5356 more information on priorities, see process_flag(priority,
5357 Level).
5358
5359 {reductions, Number}:
5360 Number is the number of reductions executed by the process.
5361
5362 {registered_name, Atom}:
5363 Atom is the registered process name. If the process has no
5364 registered name, this tuple is not present in the list.
5365
5366 {sequential_trace_token, [] | SequentialTraceToken}:
5367 SequentialTraceToken is the sequential trace token for the
5368 process. This InfoTuple can be changed or removed without
5369 prior notice.
5370
5371 {stack_size, Size}:
5372 Size is the stack size, in words, of the process.
5373
5374 {status, Status}:
5375 Status is the status of the process and is one of the fol‐
5376 lowing:
5377
5378 * exiting
5379
5380 * garbage_collecting
5381
5382 * waiting (for a message)
5383
5384 * running
5385
5386 * runnable (ready to run, but another process is running)
5387
5388 * suspended (suspended on a "busy" port or by the BIF
5389 erlang:suspend_process/1,2)
5390
5391 {suspending, SuspendeeList}:
5392 SuspendeeList is a list of {Suspendee, ActiveSuspendCount,
5393 OutstandingSuspendCount} tuples. Suspendee is the process
5394 identifier of a process that has been, or is to be, sus‐
5395 pended by the process identified by Pid through the BIF
5396 erlang:suspend_process/2 or erlang:suspend_process/1.
5397
5398 ActiveSuspendCount is the number of times Suspendee has been
5399 suspended by Pid. OutstandingSuspendCount is the number of
5400 not yet completed suspend requests sent by Pid, that is:
5401
5402 * If ActiveSuspendCount =/= 0, Suspendee is currently in the
5403 suspended state.
5404
5405 * If OutstandingSuspendCount =/= 0, option asynchronous of
5406 erlang:suspend_process/2 has been used and the suspendee
5407 has not yet been suspended by Pid.
5408
5409 Notice that ActiveSuspendCount and OutstandingSuspendCount
5410 are not the total suspend count on Suspendee, only the parts
5411 contributed by Pid.
5412
5413 {total_heap_size, Size}:
5414 Size is the total size, in words, of all heap fragments of
5415 the process. This includes the process stack and any unre‐
5416 ceived messages that are considered to be part of the heap.
5417
5418 {trace, InternalTraceFlags}:
5419 InternalTraceFlags is an integer representing the internal
5420 trace flag for this process. This InfoTuple can be changed
5421 or removed without prior notice.
5422
5423 {trap_exit, Boolean}:
5424 Boolean is true if the process is trapping exits, otherwise
5425 false.
5426
5427 Notice that not all implementations support all these Items.
5428
5429 Failures:
5430
5431 badarg:
5432 If Pid is not a local process.
5433
5434 badarg:
5435 If Item is an invalid item.
5436
5437 processes() -> [pid()]
5438
5439 Returns a list of process identifiers corresponding to all the
5440 processes currently existing on the local node.
5441
5442 Notice that an exiting process exists, but is not alive. That
5443 is, is_process_alive/1 returns false for an exiting process, but
5444 its process identifier is part of the result returned from pro‐
5445 cesses/0.
5446
5447 Example:
5448
5449 > processes().
5450 [<0.0.0>,<0.2.0>,<0.4.0>,<0.5.0>,<0.7.0>,<0.8.0>]
5451
5452 purge_module(Module) -> true
5453
5454 Types:
5455
5456 Module = atom()
5457
5458 Removes old code for Module. Before this BIF is used,
5459 check_process_code/2is to be called to check that no processes
5460 execute old code in the module.
5461
5462 Warning:
5463 This BIF is intended for the code server (see code(3)) and is
5464 not to be used elsewhere.
5465
5466
5467 Note:
5468 As from ERTS 8.0 (Erlang/OTP 19), any lingering processes that
5469 still execute the old code is killed by this function. In ear‐
5470 lier versions, such incorrect use could cause much more fatal
5471 failures, like emulator crash.
5472
5473
5474 Failure: badarg if there is no old code for Module.
5475
5476 put(Key, Val) -> term()
5477
5478 Types:
5479
5480 Key = Val = term()
5481
5482 Adds a new Key to the process dictionary, associated with the
5483 value Val, and returns undefined. If Key exists, the old value
5484 is deleted and replaced by Val, and the function returns the old
5485 value. Example:
5486
5487 > X = put(name, walrus), Y = put(name, carpenter),
5488 Z = get(name),
5489 {X, Y, Z}.
5490 {undefined,walrus,carpenter}
5491
5492 Note:
5493 The values stored when put is evaluated within the scope of a
5494 catch are not retracted if a throw is evaluated, or if an error
5495 occurs.
5496
5497
5498 erlang:raise(Class, Reason, Stacktrace) -> no_return()
5499
5500 Types:
5501
5502 Class = error | exit | throw
5503 Reason = term()
5504 Stacktrace = raise_stacktrace()
5505 raise_stacktrace() =
5506 [{module(), atom(), arity() | [term()]} |
5507 {function(), [term()]}] |
5508 [{module(), atom(), arity() | [term()], [{atom(), term()}]} |
5509 {function(), [term()], [{atom(), term()}]}]
5510
5511 Stops the execution of the calling process with an exception of
5512 the specified class, reason, and call stack backtrace (stack‐
5513 trace).
5514
5515 Class is error, exit, or throw. So, if it were not for the
5516 stacktrace, erlang:raise(Class, Reason, Stacktrace) is equiva‐
5517 lent to erlang:Class(Reason).
5518
5519 Reason is any term. Stacktrace is a list as returned from
5520 get_stacktrace(), that is, a list of four-tuples {Module, Func‐
5521 tion, Arity | Args, Location}, where Module and Function are
5522 atoms, and the third element is an integer arity or an argument
5523 list. The stacktrace can also contain {Fun, Args, Location}
5524 tuples, where Fun is a local fun and Args is an argument list.
5525
5526 Element Location at the end is optional. Omitting it is equiva‐
5527 lent to specifying an empty list.
5528
5529 The stacktrace is used as the exception stacktrace for the call‐
5530 ing process; it is truncated to the current maximum stacktrace
5531 depth.
5532
5533 As evaluating this function causes the process to terminate, it
5534 has no return value unless the arguments are invalid, in which
5535 case the function returns the error reason badarg. If you want
5536 to be sure not to return, you can call error(erlang:raise(Class,
5537 Reason, Stacktrace)) and hope to distinguish exceptions later.
5538
5539 erlang:read_timer(TimerRef) -> Result
5540
5541 Types:
5542
5543 TimerRef = reference()
5544 Time = integer() >= 0
5545 Result = Time | false
5546
5547 Reads the state of a timer. The same as calling
5548 erlang:read_timer(TimerRef, []).
5549
5550 erlang:read_timer(TimerRef, Options) -> Result | ok
5551
5552 Types:
5553
5554 TimerRef = reference()
5555 Async = boolean()
5556 Option = {async, Async}
5557 Options = [Option]
5558 Time = integer() >= 0
5559 Result = Time | false
5560
5561 Reads the state of a timer that has been created by either
5562 erlang:start_timer or erlang:send_after. TimerRef identifies the
5563 timer, and was returned by the BIF that created the timer.
5564
5565 Options:
5566
5567 {async, Async}:
5568 Asynchronous request for state information. Async defaults
5569 to false, which causes the operation to be performed syn‐
5570 chronously. In this case, the Result is returned by
5571 erlang:read_timer. When Async is true, erlang:read_timer
5572 sends an asynchronous request for the state information to
5573 the timer service that manages the timer, and then returns
5574 ok. A message on the format {read_timer, TimerRef, Result}
5575 is sent to the caller of erlang:read_timer when the opera‐
5576 tion has been processed.
5577
5578 More Options can be added in the future.
5579
5580 If Result is an integer, it represents the time in milliseconds
5581 left until the timer expires.
5582
5583 If Result is false, a timer corresponding to TimerRef could not
5584 be found. This because the timer had expired, or been canceled,
5585 or because TimerRef never has corresponded to a timer. Even if
5586 the timer has expired, it does not tell you whether or not the
5587 time-out message has arrived at its destination yet.
5588
5589 Note:
5590 The timer service that manages the timer can be co-located with
5591 another scheduler than the scheduler that the calling process is
5592 executing on. If so, communication with the timer service takes
5593 much longer time than if it is located locally. If the calling
5594 process is in a critical path, and can do other things while
5595 waiting for the result of this operation, you want to use option
5596 {async, true}. If using option {async, false}, the calling
5597 process is blocked until the operation has been performed.
5598
5599
5600 See also erlang:send_after/4, erlang:start_timer/4, and
5601 erlang:cancel_timer/2.
5602
5603 ref_to_list(Ref) -> string()
5604
5605 Types:
5606
5607 Ref = reference()
5608
5609 Returns a string corresponding to the text representation of
5610 Ref.
5611
5612 Warning:
5613 This BIF is intended for debugging and is not to be used in
5614 application programs.
5615
5616
5617 register(RegName, PidOrPort) -> true
5618
5619 Types:
5620
5621 RegName = atom()
5622 PidOrPort = port() | pid()
5623
5624 Associates the name RegName with a process identifier (pid) or a
5625 port identifier. RegName, which must be an atom, can be used
5626 instead of the pid or port identifier in send operator (RegName
5627 ! Message). Example:
5628
5629 > register(db, Pid).
5630 true
5631
5632 Failures:
5633
5634 badarg:
5635 If PidOrPort is not an existing local process or port.
5636
5637 badarg:
5638 If RegName is already in use.
5639
5640 badarg:
5641 If the process or port is already registered (already has a
5642 name).
5643
5644 badarg:
5645 If RegName is the atom undefined.
5646
5647 registered() -> [RegName]
5648
5649 Types:
5650
5651 RegName = atom()
5652
5653 Returns a list of names that have been registered using regis‐
5654 ter/2, for example:
5655
5656 > registered().
5657 [code_server, file_server, init, user, my_db]
5658
5659 erlang:resume_process(Suspendee) -> true
5660
5661 Types:
5662
5663 Suspendee = pid()
5664
5665 Decreases the suspend count on the process identified by Sus‐
5666 pendee. Suspendee is previously to have been suspended through
5667 erlang:suspend_process/2 or erlang:suspend_process/1 by the
5668 process calling erlang:resume_process(Suspendee). When the sus‐
5669 pend count on Suspendee reaches zero, Suspendee is resumed, that
5670 is, its state is changed from suspended into the state it had
5671 before it was suspended.
5672
5673 Warning:
5674 This BIF is intended for debugging only.
5675
5676
5677 Failures:
5678
5679 badarg:
5680 If Suspendee is not a process identifier.
5681
5682 badarg:
5683 If the process calling erlang:resume_process/1 had not pre‐
5684 viously increased the suspend count on the process identi‐
5685 fied by Suspendee.
5686
5687 badarg:
5688 If the process identified by Suspendee is not alive.
5689
5690 round(Number) -> integer()
5691
5692 Types:
5693
5694 Number = number()
5695
5696 Returns an integer by rounding Number, for example:
5697
5698 round(5.5).
5699 6
5700
5701 Allowed in guard tests.
5702
5703 self() -> pid()
5704
5705 Returns the process identifier of the calling process, for exam‐
5706 ple:
5707
5708 > self().
5709 <0.26.0>
5710
5711 Allowed in guard tests.
5712
5713 erlang:send(Dest, Msg) -> Msg
5714
5715 Types:
5716
5717 Dest = dst()
5718 Msg = term()
5719 dst() =
5720 pid() |
5721 port() |
5722 (RegName :: atom()) |
5723 {RegName :: atom(), Node :: node()}
5724
5725 Sends a message and returns Msg. This is the same as using the
5726 send operator: Dest ! Msg.
5727
5728 Dest can be a remote or local process identifier, a (local)
5729 port, a locally registered name, or a tuple {RegName, Node} for
5730 a registered name at another node.
5731
5732 The function fails with a badarg run-time error if Dest is an
5733 atom name, but this name is not registered. This is the only
5734 case when send fails for an unreachable destination Dest (of
5735 correct type).
5736
5737 erlang:send(Dest, Msg, Options) -> Res
5738
5739 Types:
5740
5741 Dest = dst()
5742 Msg = term()
5743 Options = [nosuspend | noconnect]
5744 Res = ok | nosuspend | noconnect
5745 dst() =
5746 pid() |
5747 port() |
5748 (RegName :: atom()) |
5749 {RegName :: atom(), Node :: node()}
5750
5751 Either sends a message and returns ok, or does not send the mes‐
5752 sage but returns something else (see below). Otherwise the same
5753 as erlang:send/2. For more detailed explanation and warnings,
5754 see erlang:send_nosuspend/2,3.
5755
5756 Options:
5757
5758 nosuspend:
5759 If the sender would have to be suspended to do the send,
5760 nosuspend is returned instead.
5761
5762 noconnect:
5763 If the destination node would have to be auto-connected to
5764 do the send, noconnect is returned instead.
5765
5766 Warning:
5767 As with erlang:send_nosuspend/2,3: use with extreme care.
5768
5769
5770 erlang:send_after(Time, Dest, Msg) -> TimerRef
5771
5772 Types:
5773
5774 Time = integer() >= 0
5775 Dest = pid() | atom()
5776 Msg = term()
5777 TimerRef = reference()
5778
5779 Starts a timer. The same as calling erlang:send_after(Time,
5780 Dest, Msg, []).
5781
5782 erlang:send_after(Time, Dest, Msg, Options) -> TimerRef
5783
5784 Types:
5785
5786 Time = integer()
5787 Dest = pid() | atom()
5788 Msg = term()
5789 Options = [Option]
5790 Abs = boolean()
5791 Option = {abs, Abs}
5792 TimerRef = reference()
5793
5794 Starts a timer. When the timer expires, the message Msg is sent
5795 to the process identified by Dest. Apart from the format of the
5796 time-out message, this function works exactly as
5797 erlang:start_timer/4.
5798
5799 erlang:send_nosuspend(Dest, Msg) -> boolean()
5800
5801 Types:
5802
5803 Dest = dst()
5804 Msg = term()
5805 dst() =
5806 pid() |
5807 port() |
5808 (RegName :: atom()) |
5809 {RegName :: atom(), Node :: node()}
5810
5811 The same as erlang:send(Dest, Msg, [nosuspend]), but returns
5812 true if the message was sent and false if the message was not
5813 sent because the sender would have had to be suspended.
5814
5815 This function is intended for send operations to an unreliable
5816 remote node without ever blocking the sending (Erlang) process.
5817 If the connection to the remote node (usually not a real Erlang
5818 node, but a node written in C or Java) is overloaded, this func‐
5819 tion does not send the message and returns false.
5820
5821 The same occurs if Dest refers to a local port that is busy. For
5822 all other destinations (allowed for the ordinary send operator
5823 '!'), this function sends the message and returns true.
5824
5825 This function is only to be used in rare circumstances where a
5826 process communicates with Erlang nodes that can disappear with‐
5827 out any trace, causing the TCP buffers and the drivers queue to
5828 be over-full before the node is shut down (because of tick time-
5829 outs) by net_kernel. The normal reaction to take when this
5830 occurs is some kind of premature shutdown of the other node.
5831
5832 Notice that ignoring the return value from this function would
5833 result in an unreliable message passing, which is contradictory
5834 to the Erlang programming model. The message is not sent if this
5835 function returns false.
5836
5837 In many systems, transient states of overloaded queues are nor‐
5838 mal. Although this function returns false does not mean that the
5839 other node is guaranteed to be non-responsive, it could be a
5840 temporary overload. Also, a return value of true does only mean
5841 that the message can be sent on the (TCP) channel without block‐
5842 ing; the message is not guaranteed to arrive at the remote node.
5843 For a disconnected non-responsive node, the return value is true
5844 (mimics the behavior of operator !). The expected behavior and
5845 the actions to take when the function returns false are applica‐
5846 tion- and hardware-specific.
5847
5848 Warning:
5849 Use with extreme care.
5850
5851
5852 erlang:send_nosuspend(Dest, Msg, Options) -> boolean()
5853
5854 Types:
5855
5856 Dest = dst()
5857 Msg = term()
5858 Options = [noconnect]
5859 dst() =
5860 pid() |
5861 port() |
5862 (RegName :: atom()) |
5863 {RegName :: atom(), Node :: node()}
5864
5865 The same as erlang:send(Dest, Msg, [nosuspend | Options]), but
5866 with a Boolean return value.
5867
5868 This function behaves like erlang:send_nosuspend/2, but takes a
5869 third parameter, a list of options. The only option is nocon‐
5870 nect, which makes the function return false if the remote node
5871 is not currently reachable by the local node. The normal behav‐
5872 ior is to try to connect to the node, which can stall the
5873 process during a short period. The use of option noconnect makes
5874 it possible to be sure not to get the slightest delay when send‐
5875 ing to a remote process. This is especially useful when communi‐
5876 cating with nodes that expect to always be the connecting part
5877 (that is, nodes written in C or Java).
5878
5879 Whenever the function returns false (either when a suspend would
5880 occur or when noconnect was specified and the node was not
5881 already connected), the message is guaranteed not to have been
5882 sent.
5883
5884 Warning:
5885 Use with extreme care.
5886
5887
5888 erlang:set_cookie(Node, Cookie) -> true
5889
5890 Types:
5891
5892 Node = node()
5893 Cookie = atom()
5894
5895 Sets the magic cookie of Node to the atom Cookie. If Node is the
5896 local node, the function also sets the cookie of all other
5897 unknown nodes to Cookie (see section Distributed Erlang in the
5898 Erlang Reference Manual in System Documentation).
5899
5900 Failure: function_clause if the local node is not alive.
5901
5902 setelement(Index, Tuple1, Value) -> Tuple2
5903
5904 Types:
5905
5906 Index = integer() >= 1
5907 1..tuple_size(Tuple1
5908 Tuple1 = Tuple2 = tuple()
5909 Value = term()
5910
5911 Returns a tuple that is a copy of argument Tuple1 with the ele‐
5912 ment specified by integer argument Index (the first element is
5913 the element with index 1) replaced by argument Value, for exam‐
5914 ple:
5915
5916 > setelement(2, {10, green, bottles}, red).
5917 {10,red,bottles}
5918
5919 size(Item) -> integer() >= 0
5920
5921 Types:
5922
5923 Item = tuple() | binary()
5924
5925 Returns the number of elements in a tuple or the number of bytes
5926 in a binary or bitstring, for example:
5927
5928 > size({morni, mulle, bwange}).
5929 3
5930 > size(<<11, 22, 33>>).
5931 3
5932
5933 For bitstrings, the number of whole bytes is returned. That is,
5934 if the number of bits in the bitstring is not divisible by 8,
5935 the resulting number of bytes is rounded down.
5936
5937 Allowed in guard tests.
5938
5939 See also tuple_size/1, byte_size/1, and bit_size/1.
5940
5941 spawn(Fun) -> pid()
5942
5943 Types:
5944
5945 Fun = function()
5946
5947 Returns the process identifier of a new process started by the
5948 application of Fun to the empty list []. Otherwise works like
5949 spawn/3.
5950
5951 spawn(Node, Fun) -> pid()
5952
5953 Types:
5954
5955 Node = node()
5956 Fun = function()
5957
5958 Returns the process identifier of a new process started by the
5959 application of Fun to the empty list [] on Node. If Node does
5960 not exist, a useless pid is returned. Otherwise works like
5961 spawn/3.
5962
5963 spawn(Module, Function, Args) -> pid()
5964
5965 Types:
5966
5967 Module = module()
5968 Function = atom()
5969 Args = [term()]
5970
5971 Returns the process identifier of a new process started by the
5972 application of Module:Function to Args.
5973
5974 error_handler:undefined_function(Module, Function, Args) is
5975 evaluated by the new process if Module:Function/Arity does not
5976 exist (where Arity is the length of Args). The error handler can
5977 be redefined (see process_flag/2). If error_handler is unde‐
5978 fined, or the user has redefined the default error_handler and
5979 its replacement is undefined, a failure with reason undef
5980 occurs.
5981
5982 Example:
5983
5984 > spawn(speed, regulator, [high_speed, thin_cut]).
5985 <0.13.1>
5986
5987 spawn(Node, Module, Function, Args) -> pid()
5988
5989 Types:
5990
5991 Node = node()
5992 Module = module()
5993 Function = atom()
5994 Args = [term()]
5995
5996 Returns the process identifier (pid) of a new process started by
5997 the application of Module:Function to Args on Node. If Node does
5998 not exist, a useless pid is returned. Otherwise works like
5999 spawn/3.
6000
6001 spawn_link(Fun) -> pid()
6002
6003 Types:
6004
6005 Fun = function()
6006
6007 Returns the process identifier of a new process started by the
6008 application of Fun to the empty list []. A link is created
6009 between the calling process and the new process, atomically.
6010 Otherwise works like spawn/3.
6011
6012 spawn_link(Node, Fun) -> pid()
6013
6014 Types:
6015
6016 Node = node()
6017 Fun = function()
6018
6019 Returns the process identifier (pid) of a new process started by
6020 the application of Fun to the empty list [] on Node. A link is
6021 created between the calling process and the new process, atomi‐
6022 cally. If Node does not exist, a useless pid is returned and an
6023 exit signal with reason noconnection is sent to the calling
6024 process. Otherwise works like spawn/3.
6025
6026 spawn_link(Module, Function, Args) -> pid()
6027
6028 Types:
6029
6030 Module = module()
6031 Function = atom()
6032 Args = [term()]
6033
6034 Returns the process identifier of a new process started by the
6035 application of Module:Function to Args. A link is created
6036 between the calling process and the new process, atomically.
6037 Otherwise works like spawn/3.
6038
6039 spawn_link(Node, Module, Function, Args) -> pid()
6040
6041 Types:
6042
6043 Node = node()
6044 Module = module()
6045 Function = atom()
6046 Args = [term()]
6047
6048 Returns the process identifier (pid) of a new process started by
6049 the application of Module:Function to Args on Node. A link is
6050 created between the calling process and the new process, atomi‐
6051 cally. If Node does not exist, a useless pid is returned and an
6052 exit signal with reason noconnection is sent to the calling
6053 process. Otherwise works like spawn/3.
6054
6055 spawn_monitor(Fun) -> {pid(), reference()}
6056
6057 Types:
6058
6059 Fun = function()
6060
6061 Returns the process identifier of a new process, started by the
6062 application of Fun to the empty list [], and a reference for a
6063 monitor created to the new process. Otherwise works like
6064 spawn/3.
6065
6066 spawn_monitor(Module, Function, Args) -> {pid(), reference()}
6067
6068 Types:
6069
6070 Module = module()
6071 Function = atom()
6072 Args = [term()]
6073
6074 A new process is started by the application of Module:Function
6075 to Args. The process is monitored at the same time. Returns the
6076 process identifier and a reference for the monitor. Otherwise
6077 works like spawn/3.
6078
6079 spawn_opt(Fun, Options) -> pid() | {pid(), reference()}
6080
6081 Types:
6082
6083 Fun = function()
6084 Options = [spawn_opt_option()]
6085 priority_level() = low | normal | high | max
6086 max_heap_size() =
6087 integer() >= 0 |
6088 #{size => integer() >= 0,
6089 kill => boolean(),
6090 error_logger => boolean()}
6091 message_queue_data() = off_heap | on_heap
6092 spawn_opt_option() =
6093 link | monitor |
6094 {priority, Level :: priority_level()} |
6095 {fullsweep_after, Number :: integer() >= 0} |
6096 {min_heap_size, Size :: integer() >= 0} |
6097 {min_bin_vheap_size, VSize :: integer() >= 0} |
6098 {max_heap_size, Size :: max_heap_size()} |
6099 {message_queue_data, MQD :: message_queue_data()}
6100
6101 Returns the process identifier (pid) of a new process started by
6102 the application of Fun to the empty list []. Otherwise works
6103 like spawn_opt/4.
6104
6105 If option monitor is specified, the newly created process is
6106 monitored, and both the pid and reference for the monitor are
6107 returned.
6108
6109 spawn_opt(Node, Fun, Options) -> pid() | {pid(), reference()}
6110
6111 Types:
6112
6113 Node = node()
6114 Fun = function()
6115 Options = [spawn_opt_option()]
6116 priority_level() = low | normal | high | max
6117 max_heap_size() =
6118 integer() >= 0 |
6119 #{size => integer() >= 0,
6120 kill => boolean(),
6121 error_logger => boolean()}
6122 message_queue_data() = off_heap | on_heap
6123 spawn_opt_option() =
6124 link | monitor |
6125 {priority, Level :: priority_level()} |
6126 {fullsweep_after, Number :: integer() >= 0} |
6127 {min_heap_size, Size :: integer() >= 0} |
6128 {min_bin_vheap_size, VSize :: integer() >= 0} |
6129 {max_heap_size, Size :: max_heap_size()} |
6130 {message_queue_data, MQD :: message_queue_data()}
6131
6132 Returns the process identifier (pid) of a new process started by
6133 the application of Fun to the empty list [] on Node. If Node
6134 does not exist, a useless pid is returned. Otherwise works like
6135 spawn_opt/4.
6136
6137 spawn_opt(Module, Function, Args, Options) ->
6138 pid() | {pid(), reference()}
6139
6140 Types:
6141
6142 Module = module()
6143 Function = atom()
6144 Args = [term()]
6145 Options = [spawn_opt_option()]
6146 priority_level() = low | normal | high | max
6147 max_heap_size() =
6148 integer() >= 0 |
6149 #{size => integer() >= 0,
6150 kill => boolean(),
6151 error_logger => boolean()}
6152 message_queue_data() = off_heap | on_heap
6153 spawn_opt_option() =
6154 link | monitor |
6155 {priority, Level :: priority_level()} |
6156 {fullsweep_after, Number :: integer() >= 0} |
6157 {min_heap_size, Size :: integer() >= 0} |
6158 {min_bin_vheap_size, VSize :: integer() >= 0} |
6159 {max_heap_size, Size :: max_heap_size()} |
6160 {message_queue_data, MQD :: message_queue_data()}
6161
6162 Works as spawn/3, except that an extra option list is specified
6163 when creating the process.
6164
6165 If option monitor is specified, the newly created process is
6166 monitored, and both the pid and reference for the monitor are
6167 returned.
6168
6169 Options:
6170
6171 link:
6172 Sets a link to the parent process (like spawn_link/3 does).
6173
6174 monitor:
6175 Monitors the new process (like monitor/2 does).
6176
6177 {priority, Level}:
6178 Sets the priority of the new process. Equivalent to execut‐
6179 ing process_flag(priority, Level) in the start function of
6180 the new process, except that the priority is set before the
6181 process is selected for execution for the first time. For
6182 more information on priorities, see process_flag(priority,
6183 Level).
6184
6185 {fullsweep_after, Number}:
6186 Useful only for performance tuning. Do not use this option
6187 unless you know that there is problem with execution times
6188 or memory consumption, and ensure that the option improves
6189 matters.
6190
6191 The Erlang runtime system uses a generational garbage col‐
6192 lection scheme, using an "old heap" for data that has sur‐
6193 vived at least one garbage collection. When there is no more
6194 room on the old heap, a fullsweep garbage collection is
6195 done.
6196
6197 Option fullsweep_after makes it possible to specify the max‐
6198 imum number of generational collections before forcing a
6199 fullsweep, even if there is room on the old heap. Setting
6200 the number to zero disables the general collection algo‐
6201 rithm, that is, all live data is copied at every garbage
6202 collection.
6203
6204 A few cases when it can be useful to change fullsweep_after:
6205
6206 * If binaries that are no longer used are to be thrown away
6207 as soon as possible. (Set Number to zero.)
6208
6209 * A process that mostly have short-lived data is fullsweeped
6210 seldom or never, that is, the old heap contains mostly
6211 garbage. To ensure a fullsweep occasionally, set Number to
6212 a suitable value, such as 10 or 20.
6213
6214 * In embedded systems with a limited amount of RAM and no
6215 virtual memory, you might want to preserve memory by set‐
6216 ting Number to zero. (The value can be set globally, see
6217 erlang:system_flag/2.)
6218
6219 {min_heap_size, Size}:
6220 Useful only for performance tuning. Do not use this option
6221 unless you know that there is problem with execution times
6222 or memory consumption, and ensure that the option improves
6223 matters.
6224
6225 Gives a minimum heap size, in words. Setting this value
6226 higher than the system default can speed up some processes
6227 because less garbage collection is done. However, setting a
6228 too high value can waste memory and slow down the system
6229 because of worse data locality. Therefore, use this option
6230 only for fine-tuning an application and to measure the exe‐
6231 cution time with various Size values.
6232
6233 {min_bin_vheap_size, VSize}:
6234 Useful only for performance tuning. Do not use this option
6235 unless you know that there is problem with execution times
6236 or memory consumption, and ensure that the option improves
6237 matters.
6238
6239 Gives a minimum binary virtual heap size, in words. Setting
6240 this value higher than the system default can speed up some
6241 processes because less garbage collection is done. However,
6242 setting a too high value can waste memory. Therefore, use
6243 this option only for fine-tuning an application and to mea‐
6244 sure the execution time with various VSize values.
6245
6246 {max_heap_size, Size}:
6247 Sets the max_heap_size process flag. The default
6248 max_heap_size is determined by command-line argument +hmax
6249 in erl(1). For more information, see the documentation of
6250 process_flag(max_heap_size, Size).
6251
6252 {message_queue_data, MQD}:
6253 Sets the state of the message_queue_data process flag. MQD
6254 is to be either off_heap or on_heap. The default mes‐
6255 sage_queue_data process flag is determined by command-line
6256 argument +hmqd in erl(1). For more information, see the doc‐
6257 umentation of process_flag(message_queue_data, MQD).
6258
6259 spawn_opt(Node, Module, Function, Args, Options) ->
6260 pid() | {pid(), reference()}
6261
6262 Types:
6263
6264 Node = node()
6265 Module = module()
6266 Function = atom()
6267 Args = [term()]
6268 Options = [spawn_opt_option()]
6269 priority_level() = low | normal | high | max
6270 max_heap_size() =
6271 integer() >= 0 |
6272 #{size => integer() >= 0,
6273 kill => boolean(),
6274 error_logger => boolean()}
6275 message_queue_data() = off_heap | on_heap
6276 spawn_opt_option() =
6277 link | monitor |
6278 {priority, Level :: priority_level()} |
6279 {fullsweep_after, Number :: integer() >= 0} |
6280 {min_heap_size, Size :: integer() >= 0} |
6281 {min_bin_vheap_size, VSize :: integer() >= 0} |
6282 {max_heap_size, Size :: max_heap_size()} |
6283 {message_queue_data, MQD :: message_queue_data()}
6284
6285 Returns the process identifier (pid) of a new process started by
6286 the application of Module:Function to Args on Node. If Node does
6287 not exist, a useless pid is returned. Otherwise works like
6288 spawn_opt/4.
6289
6290 Note:
6291 Option monitor is not supported by spawn_opt/5.
6292
6293
6294 split_binary(Bin, Pos) -> {binary(), binary()}
6295
6296 Types:
6297
6298 Bin = binary()
6299 Pos = integer() >= 0
6300 0..byte_size(Bin)
6301
6302 Returns a tuple containing the binaries that are the result of
6303 splitting Bin into two parts at position Pos. This is not a
6304 destructive operation. After the operation, there are three
6305 binaries altogether. Example:
6306
6307 > B = list_to_binary("0123456789").
6308 <<"0123456789">>
6309 > byte_size(B).
6310 10
6311 > {B1, B2} = split_binary(B,3).
6312 {<<"012">>,<<"3456789">>}
6313 > byte_size(B1).
6314 3
6315 > byte_size(B2).
6316 7
6317
6318 erlang:start_timer(Time, Dest, Msg) -> TimerRef
6319
6320 Types:
6321
6322 Time = integer() >= 0
6323 Dest = pid() | atom()
6324 Msg = term()
6325 TimerRef = reference()
6326
6327 Starts a timer. The same as calling erlang:start_timer(Time,
6328 Dest, Msg, []).
6329
6330 erlang:start_timer(Time, Dest, Msg, Options) -> TimerRef
6331
6332 Types:
6333
6334 Time = integer()
6335 Dest = pid() | atom()
6336 Msg = term()
6337 Options = [Option]
6338 Abs = boolean()
6339 Option = {abs, Abs}
6340 TimerRef = reference()
6341
6342 Starts a timer. When the timer expires, the message {timeout,
6343 TimerRef, Msg} is sent to the process identified by Dest.
6344
6345 Options:
6346
6347 {abs, false}:
6348 This is the default. It means the Time value is interpreted
6349 as a time in milliseconds relative current Erlang monotonic
6350 time.
6351
6352 {abs, true}:
6353 Absolute Time value. The Time value is interpreted as an
6354 absolute Erlang monotonic time in milliseconds.
6355
6356 More Options can be added in the future.
6357
6358 The absolute point in time, the timer is set to expire on, must
6359 be in the interval [erlang:system_info(start_time), erlang:sys‐
6360 tem_info(end_time)]. If a relative time is specified, the Time
6361 value is not allowed to be negative.
6362
6363 If Dest is a pid(), it must be a pid() of a process created on
6364 the current runtime system instance. This process has either
6365 terminated or not. If Dest is an atom(), it is interpreted as
6366 the name of a locally registered process. The process referred
6367 to by the name is looked up at the time of timer expiration. No
6368 error is returned if the name does not refer to a process.
6369
6370 If Dest is a pid(), the timer is automatically canceled if the
6371 process referred to by the pid() is not alive, or if the process
6372 exits. This feature was introduced in ERTS 5.4.11. Notice that
6373 timers are not automatically canceled when Dest is an atom().
6374
6375 See also erlang:send_after/4, erlang:cancel_timer/2, and
6376 erlang:read_timer/2.
6377
6378 Failure: badarg if the arguments do not satisfy the requirements
6379 specified here.
6380
6381 statistics(Item :: active_tasks) -> [ActiveTasks]
6382
6383 Types:
6384
6385 ActiveTasks = integer() >= 0
6386
6387 Returns the same as statistics(active_tasks_all) with the excep‐
6388 tion that no information about the dirty IO run queue and its
6389 associated schedulers is part of the result. That is, only tasks
6390 that are expected to be CPU bound are part of the result.
6391
6392 statistics(Item :: active_tasks_all) -> [ActiveTasks]
6393
6394 Types:
6395
6396 ActiveTasks = integer() >= 0
6397
6398 Returns a list where each element represents the amount of
6399 active processes and ports on each run queue and its associated
6400 schedulers. That is, the number of processes and ports that are
6401 ready to run, or are currently running. Values for normal run
6402 queues and their associated schedulers are located first in the
6403 resulting list. The first element corresponds to scheduler num‐
6404 ber 1 and so on. If support for dirty schedulers exist, an ele‐
6405 ment with the value for the dirty CPU run queue and its associ‐
6406 ated dirty CPU schedulers follow and then as last element the
6407 value for the the dirty IO run queue and its associated dirty IO
6408 schedulers follow. The information is not gathered atomically.
6409 That is, the result is not necessarily a consistent snapshot of
6410 the state, but instead quite efficiently gathered.
6411
6412 Note:
6413 Each normal scheduler has one run queue that it manages. If
6414 dirty schedulers schedulers are supported, all dirty CPU sched‐
6415 ulers share one run queue, and all dirty IO schedulers share one
6416 run queue. That is, we have multiple normal run queues, one
6417 dirty CPU run queue and one dirty IO run queue. Work can not
6418 migrate between the different types of run queues. Only work in
6419 normal run queues can migrate to other normal run queues. This
6420 has to be taken into account when evaluating the result.
6421
6422
6423 See also statistics(total_active_tasks), statis‐
6424 tics(run_queue_lengths), statistics(run_queue_lengths_all), sta‐
6425 tistics(total_run_queue_lengths), and statis‐
6426 tics(total_run_queue_lengths_all).
6427
6428 statistics(Item :: context_switches) -> {ContextSwitches, 0}
6429
6430 Types:
6431
6432 ContextSwitches = integer() >= 0
6433
6434 Returns the total number of context switches since the system
6435 started.
6436
6437 statistics(Item :: exact_reductions) ->
6438 {Total_Exact_Reductions,
6439 Exact_Reductions_Since_Last_Call}
6440
6441 Types:
6442
6443 Total_Exact_Reductions = Exact_Reductions_Since_Last_Call =
6444 integer() >= 0
6445
6446 Returns the number of exact reductions.
6447
6448 Note:
6449 statistics(exact_reductions) is a more expensive operation than
6450 statistics(reductions).
6451
6452
6453 statistics(Item :: garbage_collection) ->
6454 {Number_of_GCs, Words_Reclaimed, 0}
6455
6456 Types:
6457
6458 Number_of_GCs = Words_Reclaimed = integer() >= 0
6459
6460 Returns information about garbage collection, for example:
6461
6462 > statistics(garbage_collection).
6463 {85,23961,0}
6464
6465 This information can be invalid for some implementations.
6466
6467 statistics(Item :: io) -> {{input, Input}, {output, Output}}
6468
6469 Types:
6470
6471 Input = Output = integer() >= 0
6472
6473 Returns Input, which is the total number of bytes received
6474 through ports, and Output, which is the total number of bytes
6475 output to ports.
6476
6477 statistics(Item :: microstate_accounting) ->
6478 [MSAcc_Thread] | undefined
6479
6480 Types:
6481
6482 MSAcc_Thread =
6483 #{type := MSAcc_Thread_Type,
6484 id := MSAcc_Thread_Id,
6485 counters := MSAcc_Counters}
6486 MSAcc_Thread_Type =
6487 async | aux | dirty_io_scheduler | dirty_cpu_scheduler |
6488 poll | scheduler
6489 MSAcc_Thread_Id = integer() >= 0
6490 MSAcc_Counters = #{MSAcc_Thread_State => integer() >= 0}
6491 MSAcc_Thread_State =
6492 alloc | aux | bif | busy_wait | check_io | emulator | ets
6493 |
6494 gc | gc_fullsweep | nif | other | port | send | sleep |
6495 timers
6496
6497 Microstate accounting can be used to measure how much time the
6498 Erlang runtime system spends doing various tasks. It is designed
6499 to be as lightweight as possible, but some overhead exists when
6500 this is enabled. Microstate accounting is meant to be a profil‐
6501 ing tool to help finding performance bottlenecks. To
6502 start/stop/reset microstate accounting, use system flag
6503 microstate_accounting.
6504
6505 statistics(microstate_accounting) returns a list of maps repre‐
6506 senting some of the OS threads within ERTS. Each map contains
6507 type and id fields that can be used to identify what thread it
6508 is, and also a counters field that contains data about how much
6509 time has been spent in the various states.
6510
6511 Example:
6512
6513 > erlang:statistics(microstate_accounting).
6514 [#{counters => #{aux => 1899182914,
6515 check_io => 2605863602,
6516 emulator => 45731880463,
6517 gc => 1512206910,
6518 other => 5421338456,
6519 port => 221631,
6520 sleep => 5150294100},
6521 id => 1,
6522 type => scheduler}|...]
6523
6524 The time unit is the same as returned by os:perf_counter/0. So,
6525 to convert it to milliseconds, you can do something like this:
6526
6527 lists:map(
6528 fun(#{ counters := Cnt } = M) ->
6529 MsCnt = maps:map(fun(_K, PerfCount) ->
6530 erlang:convert_time_unit(PerfCount, perf_counter, 1000)
6531 end, Cnt),
6532 M#{ counters := MsCnt }
6533 end, erlang:statistics(microstate_accounting)).
6534
6535 Notice that these values are not guaranteed to be the exact time
6536 spent in each state. This is because of various optimisation
6537 done to keep the overhead as small as possible.
6538
6539 MSAcc_Thread_Types:
6540
6541 scheduler:
6542 The main execution threads that do most of the work. See erl
6543 +S for more details.
6544
6545 dirty_cpu_scheduler:
6546 The threads for long running cpu intensive work. See erl
6547 +SDcpu for more details.
6548
6549 dirty_io_scheduler:
6550 The threads for long running I/O work. See erl +SDio for
6551 more details.
6552
6553 async:
6554 Async threads are used by various linked-in drivers (mainly
6555 the file drivers) do offload non-CPU intensive work. See erl
6556 +A for more details.
6557
6558 aux:
6559 Takes care of any work that is not specifically assigned to
6560 a scheduler.
6561
6562 poll:
6563 Does the IO polling for the emulator. See erl +IOt for more
6564 details.
6565
6566 The following MSAcc_Thread_States are available. All states are
6567 exclusive, meaning that a thread cannot be in two states at
6568 once. So, if you add the numbers of all counters in a thread,
6569 you get the total runtime for that thread.
6570
6571 aux:
6572 Time spent handling auxiliary jobs.
6573
6574 check_io:
6575 Time spent checking for new I/O events.
6576
6577 emulator:
6578 Time spent executing Erlang processes.
6579
6580 gc:
6581 Time spent doing garbage collection. When extra states are
6582 enabled this is the time spent doing non-fullsweep garbage
6583 collections.
6584
6585 other:
6586 Time spent doing unaccounted things.
6587
6588 port:
6589 Time spent executing ports.
6590
6591 sleep:
6592 Time spent sleeping.
6593
6594 More fine-grained MSAcc_Thread_States can be added through con‐
6595 figure (such as ./configure --with-microstate-accounting=extra).
6596 Enabling these states causes performance degradation when
6597 microstate accounting is turned off and increases the overhead
6598 when it is turned on.
6599
6600 alloc:
6601 Time spent managing memory. Without extra states this time
6602 is spread out over all other states.
6603
6604 bif:
6605 Time spent in BIFs. Without extra states this time is part
6606 of the emulator state.
6607
6608 busy_wait:
6609 Time spent busy waiting. This is also the state where a
6610 scheduler no longer reports that it is active when using
6611 statistics(scheduler_wall_time). So, if you add all other
6612 states but this and sleep, and then divide that by all time
6613 in the thread, you should get something very similar to the
6614 scheduler_wall_time fraction. Without extra states this time
6615 is part of the other state.
6616
6617 ets:
6618 Time spent executing ETS BIFs. Without extra states this
6619 time is part of the emulator state.
6620
6621 gc_full:
6622 Time spent doing fullsweep garbage collection. Without extra
6623 states this time is part of the gc state.
6624
6625 nif:
6626 Time spent in NIFs. Without extra states this time is part
6627 of the emulator state.
6628
6629 send:
6630 Time spent sending messages (processes only). Without extra
6631 states this time is part of the emulator state.
6632
6633 timers:
6634 Time spent managing timers. Without extra states this time
6635 is part of the other state.
6636
6637 The utility module msacc(3) can be used to more easily analyse
6638 these statistics.
6639
6640 Returns undefined if system flag microstate_accounting is turned
6641 off.
6642
6643 The list of thread information is unsorted and can appear in
6644 different order between calls.
6645
6646 Note:
6647 The threads and states are subject to change without any prior
6648 notice.
6649
6650
6651 statistics(Item :: reductions) ->
6652 {Total_Reductions, Reductions_Since_Last_Call}
6653
6654 Types:
6655
6656 Total_Reductions = Reductions_Since_Last_Call = integer() >=
6657 0
6658
6659 Returns information about reductions, for example:
6660
6661 > statistics(reductions).
6662 {2046,11}
6663
6664 Note:
6665 As from ERTS 5.5 (Erlang/OTP R11B), this value does not include
6666 reductions performed in current time slices of currently sched‐
6667 uled processes. If an exact value is wanted, use statis‐
6668 tics(exact_reductions).
6669
6670
6671 statistics(Item :: run_queue) -> integer() >= 0
6672
6673 Returns the total length of all normal run-queues. That is, the
6674 number of processes and ports that are ready to run on all
6675 available normal run-queues. Dirty run queues are not part of
6676 the result. The information is gathered atomically. That is, the
6677 result is a consistent snapshot of the state, but this operation
6678 is much more expensive compared to statis‐
6679 tics(total_run_queue_lengths), especially when a large amount of
6680 schedulers is used.
6681
6682 statistics(Item :: run_queue_lengths) -> [RunQueueLength]
6683
6684 Types:
6685
6686 RunQueueLength = integer() >= 0
6687
6688 Returns the same as statistics(run_queue_lengths_all) with the
6689 exception that no information about the dirty IO run queue is
6690 part of the result. That is, only run queues with work that is
6691 expected to be CPU bound is part of the result.
6692
6693 statistics(Item :: run_queue_lengths_all) -> [RunQueueLength]
6694
6695 Types:
6696
6697 RunQueueLength = integer() >= 0
6698
6699 Returns a list where each element represents the amount of pro‐
6700 cesses and ports ready to run for each run queue. Values for
6701 normal run queues are located first in the resulting list. The
6702 first element corresponds to the normal run queue of scheduler
6703 number 1 and so on. If support for dirty schedulers exist, val‐
6704 ues for the dirty CPU run queue and the dirty IO run queue fol‐
6705 low (in that order) at the end. The information is not gathered
6706 atomically. That is, the result is not necessarily a consistent
6707 snapshot of the state, but instead quite efficiently gathered.
6708
6709 Note:
6710 Each normal scheduler has one run queue that it manages. If
6711 dirty schedulers schedulers are supported, all dirty CPU sched‐
6712 ulers share one run queue, and all dirty IO schedulers share one
6713 run queue. That is, we have multiple normal run queues, one
6714 dirty CPU run queue and one dirty IO run queue. Work can not
6715 migrate between the different types of run queues. Only work in
6716 normal run queues can migrate to other normal run queues. This
6717 has to be taken into account when evaluating the result.
6718
6719
6720 See also statistics(run_queue_lengths), statis‐
6721 tics(total_run_queue_lengths_all), statis‐
6722 tics(total_run_queue_lengths), statistics(active_tasks), statis‐
6723 tics(active_tasks_all), and statistics(total_active_tasks), sta‐
6724 tistics(total_active_tasks_all).
6725
6726 statistics(Item :: runtime) ->
6727 {Total_Run_Time, Time_Since_Last_Call}
6728
6729 Types:
6730
6731 Total_Run_Time = Time_Since_Last_Call = integer() >= 0
6732
6733 Returns information about runtime, in milliseconds.
6734
6735 This is the sum of the runtime for all threads in the Erlang
6736 runtime system and can therefore be greater than the wall clock
6737 time.
6738
6739 Warning:
6740 This value might wrap due to limitations in the underlying func‐
6741 tionality provided by the operating system that is used.
6742
6743
6744 Example:
6745
6746 > statistics(runtime).
6747 {1690,1620}
6748
6749 statistics(Item :: scheduler_wall_time) ->
6750 [{SchedulerId, ActiveTime, TotalTime}] | undefined
6751
6752 Types:
6753
6754 SchedulerId = integer() >= 1
6755 ActiveTime = TotalTime = integer() >= 0
6756
6757 Returns a list of tuples with {SchedulerId, ActiveTime, Total‐
6758 Time}, where SchedulerId is an integer ID of the scheduler,
6759 ActiveTime is the duration the scheduler has been busy, and
6760 TotalTime is the total time duration since scheduler_wall_time
6761 activation for the specific scheduler. Note that activation time
6762 can differ significantly between schedulers. Currently dirty
6763 schedulers are activated at system start while normal schedulers
6764 are activated some time after the scheduler_wall_time function‐
6765 ality is enabled. The time unit is undefined and can be subject
6766 to change between releases, OSs, and system restarts. sched‐
6767 uler_wall_time is only to be used to calculate relative values
6768 for scheduler utilization. ActiveTime can never exceed Total‐
6769 Time.
6770
6771 The definition of a busy scheduler is when it is not idle and is
6772 not scheduling (selecting) a process or port, that is:
6773
6774 * Executing process code
6775
6776 * Executing linked-in driver or NIF code
6777
6778 * Executing BIFs, or any other runtime handling
6779
6780 * Garbage collecting
6781
6782 * Handling any other memory management
6783
6784 Notice that a scheduler can also be busy even if the OS has
6785 scheduled out the scheduler thread.
6786
6787 Returns undefined if system flag scheduler_wall_time is turned
6788 off.
6789
6790 The list of scheduler information is unsorted and can appear in
6791 different order between calls.
6792
6793 As of ERTS version 9.0, also dirty CPU schedulers will be
6794 included in the result. That is, all scheduler threads that are
6795 expected to handle CPU bound work. If you also want information
6796 about dirty I/O schedulers, use statistics(sched‐
6797 uler_wall_time_all) instead.
6798
6799 Normal schedulers will have scheduler identifiers in the range 1
6800 =< SchedulerId =< erlang:system_info(schedulers). Dirty CPU
6801 schedulers will have scheduler identifiers in the range
6802 erlang:system_info(schedulers) < SchedulerId =< erlang:sys‐
6803 tem_info(schedulers) + erlang:system_info(dirty_cpu_schedulers).
6804
6805 Note:
6806 The different types of schedulers handle specific types of jobs.
6807 Every job is assigned to a specific scheduler type. Jobs can
6808 migrate between different schedulers of the same type, but never
6809 between schedulers of different types. This fact has to be taken
6810 under consideration when evaluating the result returned.
6811
6812
6813 Using scheduler_wall_time to calculate scheduler utilization:
6814
6815 > erlang:system_flag(scheduler_wall_time, true).
6816 false
6817 > Ts0 = lists:sort(erlang:statistics(scheduler_wall_time)), ok.
6818 ok
6819
6820 Some time later the user takes another snapshot and calculates
6821 scheduler utilization per scheduler, for example:
6822
6823 > Ts1 = lists:sort(erlang:statistics(scheduler_wall_time)), ok.
6824 ok
6825 > lists:map(fun({{I, A0, T0}, {I, A1, T1}}) -> {I, (A1 - A0)/(T1 - T0)} end, lists:zip(Ts0,Ts1)).
6826 [{1,0.9743474730177548},
6827 {2,0.9744843782751444},
6828 {3,0.9995902361669045},
6829 {4,0.9738012596572161},
6830 {5,0.9717956667018103},
6831 {6,0.9739235846420741},
6832 {7,0.973237033077876},
6833 {8,0.9741297293248656}]
6834
6835 Using the same snapshots to calculate a total scheduler utiliza‐
6836 tion:
6837
6838 > {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.
6839 0.9769136803764825
6840
6841 Total scheduler utilization will equal 1.0 when all schedulers
6842 have been active all the time between the two measurements.
6843
6844 Another (probably more) useful value is to calculate total
6845 scheduler utilization weighted against maximum amount of avail‐
6846 able CPU time:
6847
6848 > WeightedSchedulerUtilization = (TotalSchedulerUtilization * (erlang:system_info(schedulers) + erlang:system_info(dirty_cpu_schedulers))) / erlang:system_info(logical_processors_available).
6849 0.9769136803764825
6850
6851 This weighted scheduler utilization will reach 1.0 when sched‐
6852 ulers are active the same amount of time as maximum available
6853 CPU time. If more schedulers exist than available logical pro‐
6854 cessors, this value may be greater than 1.0.
6855
6856 As of ERTS version 9.0, the Erlang runtime system will as
6857 default have more schedulers than logical processors. This due
6858 to the dirty schedulers.
6859
6860 Note:
6861 scheduler_wall_time is by default disabled. To enable it, use
6862 erlang:system_flag(scheduler_wall_time, true).
6863
6864
6865 statistics(Item :: scheduler_wall_time_all) ->
6866 [{SchedulerId, ActiveTime, TotalTime}] | undefined
6867
6868 Types:
6869
6870 SchedulerId = integer() >= 1
6871 ActiveTime = TotalTime = integer() >= 0
6872
6873 The same as statistics(scheduler_wall_time), except that it also
6874 include information about all dirty I/O schedulers.
6875
6876 Dirty IO schedulers will have scheduler identifiers in the range
6877 erlang:system_info(schedulers) + erlang:sys‐
6878 tem_info(dirty_cpu_schedulers) < SchedulerId =< erlang:sys‐
6879 tem_info(schedulers) + erlang:system_info(dirty_cpu_schedulers)
6880 + erlang:system_info(dirty_io_schedulers).
6881
6882 Note:
6883 Note that work executing on dirty I/O schedulers are expected to
6884 mainly wait for I/O. That is, when you get high scheduler uti‐
6885 lization on dirty I/O schedulers, CPU utilization is not
6886 expected to be high due to this work.
6887
6888
6889 statistics(Item :: total_active_tasks) -> ActiveTasks
6890
6891 Types:
6892
6893 ActiveTasks = integer() >= 0
6894
6895 The same as calling lists:sum(statistics(active_tasks)), but
6896 more efficient.
6897
6898 statistics(Item :: total_active_tasks_all) -> ActiveTasks
6899
6900 Types:
6901
6902 ActiveTasks = integer() >= 0
6903
6904 The same as calling lists:sum(statistics(active_tasks_all)), but
6905 more efficient.
6906
6907 statistics(Item :: total_run_queue_lengths) ->
6908 TotalRunQueueLengths
6909
6910 Types:
6911
6912 TotalRunQueueLengths = integer() >= 0
6913
6914 The same as calling lists:sum(statistics(run_queue_lengths)),
6915 but more efficient.
6916
6917 statistics(Item :: total_run_queue_lengths_all) ->
6918 TotalRunQueueLengths
6919
6920 Types:
6921
6922 TotalRunQueueLengths = integer() >= 0
6923
6924 The same as calling lists:sum(statis‐
6925 tics(run_queue_lengths_all)), but more efficient.
6926
6927 statistics(Item :: wall_clock) ->
6928 {Total_Wallclock_Time,
6929 Wallclock_Time_Since_Last_Call}
6930
6931 Types:
6932
6933 Total_Wallclock_Time = Wallclock_Time_Since_Last_Call = inte‐
6934 ger() >= 0
6935
6936 Returns information about wall clock. wall_clock can be used in
6937 the same manner as runtime, except that real time is measured as
6938 opposed to runtime or CPU time.
6939
6940 erlang:suspend_process(Suspendee) -> true
6941
6942 Types:
6943
6944 Suspendee = pid()
6945
6946 Suspends the process identified by Suspendee. The same as call‐
6947 ing erlang:suspend_process(Suspendee, []).
6948
6949 Warning:
6950 This BIF is intended for debugging only.
6951
6952
6953 erlang:suspend_process(Suspendee, OptList) -> boolean()
6954
6955 Types:
6956
6957 Suspendee = pid()
6958 OptList = [Opt]
6959 Opt = unless_suspending | asynchronous | {asynchronous,
6960 term()}
6961
6962 Increases the suspend count on the process identified by Sus‐
6963 pendee and puts it in the suspended state if it is not already
6964 in that state. A suspended process is not scheduled for execu‐
6965 tion until the process has been resumed.
6966
6967 A process can be suspended by multiple processes and can be sus‐
6968 pended multiple times by a single process. A suspended process
6969 does not leave the suspended state until its suspend count
6970 reaches zero. The suspend count of Suspendee is decreased when
6971 erlang:resume_process(Suspendee) is called by the same process
6972 that called erlang:suspend_process(Suspendee). All increased
6973 suspend counts on other processes acquired by a process are
6974 automatically decreased when the process terminates.
6975
6976 Options (Opts):
6977
6978 asynchronous:
6979 A suspend request is sent to the process identified by Sus‐
6980 pendee. Suspendee eventually suspends unless it is resumed
6981 before it could suspend. The caller of erlang:sus‐
6982 pend_process/2 returns immediately, regardless of whether
6983 Suspendee has suspended yet or not. The point in time when
6984 Suspendee suspends cannot be deduced from other events in
6985 the system. It is only guaranteed that Suspendee eventually
6986 suspends (unless it is resumed). If no asynchronous options
6987 has been passed, the caller of erlang:suspend_process/2 is
6988 blocked until Suspendee has suspended.
6989
6990 {asynchronous, ReplyTag}:
6991 A suspend request is sent to the process identified by Sus‐
6992 pendee. When the suspend request has been processed, a reply
6993 message is sent to the caller of this function. The reply is
6994 on the form {ReplyTag, State} where State is either:
6995
6996 exited:
6997 Suspendee has exited.
6998
6999 suspended:
7000 Suspendee is now suspended.
7001
7002 not_suspended:
7003 Suspendee is not suspended. This can only happen when the
7004 process that issued this request, have called
7005 resume_process(Suspendee) before getting the reply.
7006
7007 Appart from the reply message, the {asynchronous, ReplyTag}
7008 option behaves exactly the same as the asynchronous option
7009 without reply tag.
7010
7011 unless_suspending:
7012 The process identified by Suspendee is suspended unless the
7013 calling process already is suspending Suspendee. If
7014 unless_suspending is combined with option asynchronous, a
7015 suspend request is sent unless the calling process already
7016 is suspending Suspendee or if a suspend request already has
7017 been sent and is in transit. If the calling process already
7018 is suspending Suspendee, or if combined with option asyn‐
7019 chronous and a send request already is in transit, false is
7020 returned and the suspend count on Suspendee remains
7021 unchanged.
7022
7023 If the suspend count on the process identified by Suspendee is
7024 increased, true is returned, otherwise false.
7025
7026 Warning:
7027 This BIF is intended for debugging only.
7028
7029
7030 Warning:
7031 You can easily create deadlocks if processes suspends each other
7032 (directly or in circles). In ERTS versions prior to ERTS version
7033 10.0, the runtime system prevented such deadlocks, but this pre‐
7034 vention has now been removed due to performance reasons.
7035
7036
7037 Failures:
7038
7039 badarg:
7040 If Suspendee is not a process identifier.
7041
7042 badarg:
7043 If the process identified by Suspendee is the same process
7044 as the process calling erlang:suspend_process/2.
7045
7046 badarg:
7047 If the process identified by Suspendee is not alive.
7048
7049 badarg:
7050 If the process identified by Suspendee resides on another
7051 node.
7052
7053 badarg:
7054 If OptList is not a proper list of valid Opts.
7055
7056 system_limit:
7057 If the process identified by Suspendee has been suspended
7058 more times by the calling process than can be represented by
7059 the currently used internal data structures. The system
7060 limit is > 2,000,000,000 suspends and will never be lower.
7061
7062 erlang:system_flag(Flag :: backtrace_depth, Depth) -> OldDepth
7063
7064 Types:
7065
7066 Depth = OldDepth = integer() >= 0
7067
7068 Sets the maximum depth of call stack back-traces in the exit
7069 reason element of 'EXIT' tuples. The flag also limits the stack‐
7070 trace depth returned by process_info item current_stacktrace.
7071
7072 Returns the old value of the flag.
7073
7074 erlang:system_flag(Flag :: cpu_topology, CpuTopology) ->
7075 OldCpuTopology
7076
7077 Types:
7078
7079 CpuTopology = OldCpuTopology = cpu_topology()
7080 cpu_topology() = [LevelEntry :: level_entry()] | undefined
7081 level_entry() =
7082 {LevelTag :: level_tag(), SubLevel :: sub_level()} |
7083 {LevelTag :: level_tag(),
7084 InfoList :: info_list(),
7085 SubLevel :: sub_level()}
7086 level_tag() = core | node | processor | thread
7087 sub_level() =
7088 [LevelEntry :: level_entry()] |
7089 (LogicalCpuId :: {logical, integer() >= 0})
7090 info_list() = []
7091
7092 Warning:
7093 This argument is deprecated. Instead of using this argument, use
7094 command-line argument +sct in erl(1).
7095
7096 When this argument is removed, a final CPU topology to use is
7097 determined at emulator boot time.
7098
7099
7100 Sets the user-defined CpuTopology. The user-defined CPU topology
7101 overrides any automatically detected CPU topology. By passing
7102 undefined as CpuTopology, the system reverts to the CPU topology
7103 automatically detected. The returned value equals the value
7104 returned from erlang:system_info(cpu_topology) before the change
7105 was made.
7106
7107 Returns the old value of the flag.
7108
7109 The CPU topology is used when binding schedulers to logical pro‐
7110 cessors. If schedulers are already bound when the CPU topology
7111 is changed, the schedulers are sent a request to rebind accord‐
7112 ing to the new CPU topology.
7113
7114 The user-defined CPU topology can also be set by passing com‐
7115 mand-line argument +sct to erl(1).
7116
7117 For information on type CpuTopology and more, see erlang:sys‐
7118 tem_info(cpu_topology) as well as command-line flags +sct and
7119 +sbt in erl(1).
7120
7121 erlang:system_flag(Flag :: dirty_cpu_schedulers_online,
7122 DirtyCPUSchedulersOnline) ->
7123 OldDirtyCPUSchedulersOnline
7124
7125 Types:
7126
7127 DirtyCPUSchedulersOnline = OldDirtyCPUSchedulersOnline =
7128 integer() >= 1
7129
7130 Sets the number of dirty CPU schedulers online. Range is 1 <=
7131 DirtyCPUSchedulersOnline <= N, where N is the smallest of the
7132 return values of erlang:system_info(dirty_cpu_schedulers) and
7133 erlang:system_info(schedulers_online).
7134
7135 Returns the old value of the flag.
7136
7137 The number of dirty CPU schedulers online can change if the num‐
7138 ber of schedulers online changes. For example, if 12 schedulers
7139 and 6 dirty CPU schedulers are online, and system_flag/2 is used
7140 to set the number of schedulers online to 6, then the number of
7141 dirty CPU schedulers online is automatically decreased by half
7142 as well, down to 3. Similarly, the number of dirty CPU sched‐
7143 ulers online increases proportionally to increases in the number
7144 of schedulers online.
7145
7146 For more information, see erlang:system_info(dirty_cpu_sched‐
7147 ulers) and erlang:system_info(dirty_cpu_schedulers_online).
7148
7149 erlang:system_flag(Flag :: erts_alloc, Value :: {Alloc, F, V}) ->
7150 ok | notsup
7151
7152 Types:
7153
7154 Alloc = F = atom()
7155 V = integer()
7156
7157 Sets system flags for erts_alloc(3). Alloc is the allocator to
7158 affect, for example binary_alloc. F is the flag to change and V
7159 is the new value.
7160
7161 Only a subset of all erts_alloc flags can be changed at run
7162 time. This subset is currently only the flag sbct.
7163
7164 Returns ok if the flag was set or notsup if not supported by
7165 erts_alloc.
7166
7167 erlang:system_flag(Flag :: fullsweep_after, Number) -> OldNumber
7168
7169 Types:
7170
7171 Number = OldNumber = integer() >= 0
7172
7173 Sets system flag fullsweep_after. Number is a non-negative inte‐
7174 ger indicating how many times generational garbage collections
7175 can be done without forcing a fullsweep collection. The value
7176 applies to new processes, while processes already running are
7177 not affected.
7178
7179 Returns the old value of the flag.
7180
7181 In low-memory systems (especially without virtual memory), set‐
7182 ting the value to 0 can help to conserve memory.
7183
7184 This value can also be set through (OS) environment variable
7185 ERL_FULLSWEEP_AFTER.
7186
7187 erlang:system_flag(Flag :: microstate_accounting, Action) ->
7188 OldState
7189
7190 Types:
7191
7192 Action = true | false | reset
7193 OldState = true | false
7194
7195 Turns on/off microstate accounting measurements. When passing
7196 reset, all counters are reset to 0.
7197
7198 For more information see statistics(microstate_accounting).
7199
7200 erlang:system_flag(Flag :: min_heap_size, MinHeapSize) ->
7201 OldMinHeapSize
7202
7203 Types:
7204
7205 MinHeapSize = OldMinHeapSize = integer() >= 0
7206
7207 Sets the default minimum heap size for processes. The size is
7208 specified in words. The new min_heap_size effects only processes
7209 spawned after the change of min_heap_size has been made.
7210 min_heap_size can be set for individual processes by using
7211 spawn_opt/4 or process_flag/2.
7212
7213 Returns the old value of the flag.
7214
7215 erlang:system_flag(Flag :: min_bin_vheap_size, MinBinVHeapSize) ->
7216 OldMinBinVHeapSize
7217
7218 Types:
7219
7220 MinBinVHeapSize = OldMinBinVHeapSize = integer() >= 0
7221
7222 Sets the default minimum binary virtual heap size for processes.
7223 The size is specified in words. The new min_bin_vhheap_size
7224 effects only processes spawned after the change of
7225 min_bin_vheap_size has been made. min_bin_vheap_size can be set
7226 for individual processes by using spawn_opt/2,3,4 or
7227 process_flag/2.
7228
7229 Returns the old value of the flag.
7230
7231 erlang:system_flag(Flag :: max_heap_size, MaxHeapSize) ->
7232 OldMaxHeapSize
7233
7234 Types:
7235
7236 MaxHeapSize = OldMaxHeapSize = max_heap_size()
7237 max_heap_size() =
7238 integer() >= 0 |
7239 #{size => integer() >= 0,
7240 kill => boolean(),
7241 error_logger => boolean()}
7242
7243 Sets the default maximum heap size settings for processes. The
7244 size is specified in words. The new max_heap_size effects only
7245 processes spawned efter the change has been made. max_heap_size
7246 can be set for individual processes using spawn_opt/2,3,4 or
7247 process_flag/2.
7248
7249 Returns the old value of the flag.
7250
7251 erlang:system_flag(Flag :: multi_scheduling, BlockState) ->
7252 OldBlockState
7253
7254 Types:
7255
7256 BlockState = block | unblock | block_normal | unblock_normal
7257 OldBlockState = blocked | disabled | enabled
7258
7259 If multi-scheduling is enabled, more than one scheduler thread
7260 is used by the emulator. Multi-scheduling can be blocked in two
7261 different ways. Either all schedulers but one is blocked, or all
7262 normal schedulers but one is blocked. When only normal sched‐
7263 ulers are blocked, dirty schedulers are free to continue to
7264 schedule processes.
7265
7266 If BlockState =:= block, multi-scheduling is blocked. That is,
7267 one and only one scheduler thread will execute. If BlockState
7268 =:= unblock and no one else blocks multi-scheduling, and this
7269 process has blocked only once, multi-scheduling is unblocked.
7270
7271 If BlockState =:= block_normal, normal multi-scheduling is
7272 blocked. That is, only one normal scheduler thread will execute,
7273 but multiple dirty schedulers can execute. If BlockState =:=
7274 unblock_normal and no one else blocks normal multi-scheduling,
7275 and this process has blocked only once, normal multi-scheduling
7276 is unblocked.
7277
7278 One process can block multi-scheduling and normal multi-schedul‐
7279 ing multiple times. If a process has blocked multiple times, it
7280 must unblock exactly as many times as it has blocked before it
7281 has released its multi-scheduling block. If a process that has
7282 blocked multi-scheduling or normal multi-scheduling exits, it
7283 automatically releases its blocking of multi-scheduling and nor‐
7284 mal multi-scheduling.
7285
7286 The return values are disabled, blocked, blocked_normal, or
7287 enabled. The returned value describes the state just after the
7288 call to erlang:system_flag(multi_scheduling, BlockState) has
7289 been made. For information about the return values, see
7290 erlang:system_info(multi_scheduling).
7291
7292 Note:
7293 Blocking of multi-scheduling and normal multi-scheduling is nor‐
7294 mally not needed. If you feel that you need to use these fea‐
7295 tures, consider it a few more times again. Blocking multi-sched‐
7296 uling is only to be used as a last resort, as it is most likely
7297 a very inefficient way to solve the problem.
7298
7299
7300 See also erlang:system_info(multi_scheduling), erlang:sys‐
7301 tem_info(normal_multi_scheduling_blockers), erlang:sys‐
7302 tem_info(multi_scheduling_blockers), and erlang:sys‐
7303 tem_info(schedulers).
7304
7305 erlang:system_flag(Flag :: scheduler_bind_type, How) ->
7306 OldBindType
7307
7308 Types:
7309
7310 How = scheduler_bind_type() | default_bind
7311 OldBindType = scheduler_bind_type()
7312 scheduler_bind_type() =
7313 no_node_processor_spread | no_node_thread_spread | no_spread |
7314 processor_spread | spread | thread_spread |
7315 thread_no_node_processor_spread | unbound
7316
7317 Warning:
7318 This argument is deprecated. Instead of using this argument, use
7319 command-line argument +sbt in erl(1). When this argument is
7320 removed, a final scheduler bind type to use is determined at
7321 emulator boot time.
7322
7323
7324 Controls if and how schedulers are bound to logical processors.
7325
7326 When erlang:system_flag(scheduler_bind_type, How) is called, an
7327 asynchronous signal is sent to all schedulers online, causing
7328 them to try to bind or unbind as requested.
7329
7330 Note:
7331 If a scheduler fails to bind, this is often silently ignored, as
7332 it is not always possible to verify valid logical processor
7333 identifiers. If an error is reported, an error event is logged.
7334 To verify that the schedulers have bound as requested, call
7335 erlang:system_info(scheduler_bindings).
7336
7337
7338 Schedulers can be bound on newer Linux, Solaris, FreeBSD, and
7339 Windows systems, but more systems will be supported in future
7340 releases.
7341
7342 In order for the runtime system to be able to bind schedulers,
7343 the CPU topology must be known. If the runtime system fails to
7344 detect the CPU topology automatically, it can be defined. For
7345 more information on how to define the CPU topology, see command-
7346 line flag +sct in erl(1).
7347
7348 The runtime system does by default not bind schedulers to logi‐
7349 cal processors.
7350
7351 Note:
7352 If the Erlang runtime system is the only OS process binding
7353 threads to logical processors, this improves the performance of
7354 the runtime system. However, if other OS processes (for example,
7355 another Erlang runtime system) also bind threads to logical pro‐
7356 cessors, there can be a performance penalty instead. Sometimes
7357 this performance penalty can be severe. If so, it is recommended
7358 to not bind the schedulers.
7359
7360
7361 Schedulers can be bound in different ways. Argument How deter‐
7362 mines how schedulers are bound and can be any of the following:
7363
7364 unbound:
7365 Same as command-line argument +sbt u in erl(1).
7366
7367 no_spread:
7368 Same as command-line argument +sbt ns in erl(1).
7369
7370 thread_spread:
7371 Same as command-line argument +sbt ts in erl(1).
7372
7373 processor_spread:
7374 Same as command-line argument +sbt ps in erl(1).
7375
7376 spread:
7377 Same as command-line argument +sbt s in erl(1).
7378
7379 no_node_thread_spread:
7380 Same as command-line argument +sbt nnts in erl(1).
7381
7382 no_node_processor_spread:
7383 Same as command-line argument +sbt nnps in erl(1).
7384
7385 thread_no_node_processor_spread:
7386 Same as command-line argument +sbt tnnps in erl(1).
7387
7388 default_bind:
7389 Same as command-line argument +sbt db in erl(1).
7390
7391 The returned value equals How before flag scheduler_bind_type
7392 was changed.
7393
7394 Failures:
7395
7396 notsup:
7397 If binding of schedulers is not supported.
7398
7399 badarg:
7400 If How is not one of the documented alternatives.
7401
7402 badarg:
7403 If CPU topology information is unavailable.
7404
7405 The scheduler bind type can also be set by passing command-line
7406 argument +sbt to erl(1).
7407
7408 For more information, see erlang:system_info(sched‐
7409 uler_bind_type), erlang:system_info(scheduler_bindings), as well
7410 as command-line flags +sbt and +sct in erl(1).
7411
7412 erlang:system_flag(Flag :: scheduler_wall_time, Boolean) ->
7413 OldBoolean
7414
7415 Types:
7416
7417 Boolean = OldBoolean = boolean()
7418
7419 Turns on or off scheduler wall time measurements.
7420
7421 For more information, see statistics(scheduler_wall_time).
7422
7423 erlang:system_flag(Flag :: schedulers_online, SchedulersOnline) ->
7424 OldSchedulersOnline
7425
7426 Types:
7427
7428 SchedulersOnline = OldSchedulersOnline = integer() >= 1
7429
7430 Sets the number of schedulers online. Range is 1 <= Scheduler‐
7431 sOnline <= erlang:system_info(schedulers).
7432
7433 Returns the old value of the flag.
7434
7435 If the emulator was built with support for dirty schedulers,
7436 changing the number of schedulers online can also change the
7437 number of dirty CPU schedulers online. For example, if 12 sched‐
7438 ulers and 6 dirty CPU schedulers are online, and system_flag/2
7439 is used to set the number of schedulers online to 6, then the
7440 number of dirty CPU schedulers online is automatically decreased
7441 by half as well, down to 3. Similarly, the number of dirty CPU
7442 schedulers online increases proportionally to increases in the
7443 number of schedulers online.
7444
7445 For more information, see erlang:system_info(schedulers) and
7446 erlang:system_info(schedulers_online).
7447
7448 erlang:system_flag(Flag :: system_logger, Logger) -> PrevLogger
7449
7450 Types:
7451
7452 Logger = PrevLogger = logger | undefined | pid()
7453
7454 Sets the process that will receive the logging messages gener‐
7455 ated by ERTS. If set to undefined, all logging messages gener‐
7456 ated by ERTS will be dropped. The messages will be in the for‐
7457 mat:
7458
7459 {log,Level,Format,ArgList,Metadata} where
7460
7461 Level = atom(),
7462 Format = string(),
7463 ArgList = list(term()),
7464 Metadata = #{ pid => pid(),
7465 group_leader => pid(),
7466 time := logger:timestamp(),
7467 error_logger := #{ emulator := true, tag := atom() }
7468
7469
7470 If the system_logger process dies, this flag will be reset to
7471 logger.
7472
7473 The default is the process named logger.
7474
7475 Returns the old value of the flag.
7476
7477 Note:
7478 This function is designed to be used by the KERNEL logger. Be
7479 careful if you change it to something else as log messages may
7480 be lost. If you want to intercept emulator log messages, do it
7481 by adding a specialized handler to the KERNEL logger.
7482
7483
7484 erlang:system_flag(Flag :: trace_control_word, TCW) -> OldTCW
7485
7486 Types:
7487
7488 TCW = OldTCW = integer() >= 0
7489
7490 Sets the value of the node trace control word to TCW, which is
7491 to be an unsigned integer. For more information, see function
7492 set_tcw in section "Match Specifications in Erlang" in the
7493 User's Guide.
7494
7495 Returns the old value of the flag.
7496
7497 erlang:system_flag(Flag :: time_offset, Value :: finalize) ->
7498 OldState
7499
7500 Types:
7501
7502 OldState = preliminary | final | volatile
7503
7504 Finalizes the time offset when single time warp mode is used. If
7505 another time warp mode is used, the time offset state is left
7506 unchanged.
7507
7508 Returns the old state identifier, that is:
7509
7510 * If preliminary is returned, finalization was performed and
7511 the time offset is now final.
7512
7513 * If final is returned, the time offset was already in the
7514 final state. This either because another erlang:sys‐
7515 tem_flag(time_offset, finalize) call or because no time warp
7516 mode is used.
7517
7518 * If volatile is returned, the time offset cannot be finalized
7519 because multi-time warp mode is used.
7520
7521 erlang:system_info(Item ::
7522 wordsize |
7523 {wordsize, internal} |
7524 {wordsize, external}) ->
7525 4 | 8
7526
7527 Returns information about the current system. The documentation
7528 of this function is broken into the following sections in order
7529 to make it easier to navigate.
7530
7531 Memory Allocation:
7532 allocated_areas, allocator, alloc_util_allocators, alloca‐
7533 tor_sizes, elib_malloc
7534
7535 CPU Topology:
7536 cpu_topology, logical_processors, update_cpu_info
7537
7538 Process Information:
7539 fullsweep_after, garbage_collection, heap_sizes, heap_type,
7540 max_heap_size, message_queue_data, min_heap_size,
7541 min_bin_vheap_size, procs
7542
7543 System Limits:
7544 atom_count, atom_limit, ets_count, ets_limit, port_count,
7545 port_limit, process_count, process_limit
7546
7547 System Time:
7548 end_time, os_monotonic_time_source, os_system_time_source,
7549 start_time, time_correction, time_offset, time_warp_mode,
7550 tolerant_timeofday
7551
7552 Scheduler Information:
7553 dirty_cpu_schedulers, dirty_cpu_schedulers_online,
7554 dirty_io_schedulers, multi_scheduling, multi_schedul‐
7555 ing_blockers, normal_multi_scheduling_blockers, sched‐
7556 uler_bind_type, scheduler_bindings, scheduler_id, sched‐
7557 ulers, smp_support, threads, thread_pool_size
7558
7559 Distribution Information:
7560 creation, delayed_node_table_gc, dist, dist_buf_busy_limit,
7561 dist_ctrl
7562
7563 System Information:
7564 build_type, c_compiler_used, check_io, compat_rel,
7565 debug_compiled, driver_version, dynamic_trace,
7566 dynamic_trace_probes, info, kernel_poll, loaded, machine,
7567 modified_timing_level, nif_version, otp_release, port_paral‐
7568 lelism, system_architecture, system_logger, system_version,
7569 trace_control_word, version, wordsize
7570
7571 erlang:system_info(Item :: allocated_areas) -> [tuple()]
7572
7573 erlang:system_info(Item :: allocator) ->
7574 {Allocator, Version, Features, Settings}
7575
7576 erlang:system_info(Item :: {allocator, Alloc}) -> [term()]
7577
7578 erlang:system_info(Item :: alloc_util_allocators) -> [Alloc]
7579
7580 erlang:system_info(Item :: {allocator_sizes, Alloc}) -> [term()]
7581
7582 erlang:system_info(Item :: elib_malloc) -> false
7583
7584 Types:
7585
7586 Allocator = undefined | glibc
7587 Version = [integer() >= 0]
7588 Features = [atom()]
7589 Settings =
7590 [{Subsystem :: atom(),
7591 [{Parameter :: atom(), Value :: term()}]}]
7592 Alloc = atom()
7593
7594 Returns various information about the memory allocators of the
7595 current system (emulator) as specified by Item:
7596
7597 allocated_areas:
7598 Returns a list of tuples with information about miscella‐
7599 neous allocated memory areas.
7600
7601 Each tuple contains an atom describing the type of memory as
7602 first element and the amount of allocated memory in bytes as
7603 second element. When information about allocated and used
7604 memory is present, also a third element is present, contain‐
7605 ing the amount of used memory in bytes.
7606
7607 erlang:system_info(allocated_areas) is intended for debug‐
7608 ging, and the content is highly implementation-dependent.
7609 The content of the results therefore changes when needed
7610 without prior notice.
7611
7612 Notice that the sum of these values is not the total amount
7613 of memory allocated by the emulator. Some values are part of
7614 other values, and some memory areas are not part of the
7615 result. For information about the total amount of memory
7616 allocated by the emulator, see erlang:memory/0,1.
7617
7618 allocator:
7619 Returns {Allocator, Version, Features, Settings, where:
7620
7621 * Allocator corresponds to the malloc() implementation used.
7622 If Allocator equals undefined, the malloc() implementation
7623 used cannot be identified. glibc can be identified.
7624
7625 * Version is a list of integers (but not a string) repre‐
7626 senting the version of the malloc() implementation used.
7627
7628 * Features is a list of atoms representing the allocation
7629 features used.
7630
7631 * Settings is a list of subsystems, their configurable
7632 parameters, and used values. Settings can differ between
7633 different combinations of platforms, allocators, and allo‐
7634 cation features. Memory sizes are given in bytes.
7635
7636 See also "System Flags Effecting erts_alloc" in
7637 erts_alloc(3).
7638
7639 {allocator, Alloc}:
7640 Returns information about the specified allocator. As from
7641 ERTS 5.6.1, the return value is a list of {instance, Instan‐
7642 ceNo, InstanceInfo} tuples, where InstanceInfo contains
7643 information about a specific instance of the allocator. If
7644 Alloc is not a recognized allocator, undefined is returned.
7645 If Alloc is disabled, false is returned.
7646
7647 Notice that the information returned is highly implementa‐
7648 tion-dependent and can be changed or removed at any time
7649 without prior notice. It was initially intended as a tool
7650 when developing new allocators, but as it can be of interest
7651 for others it has been briefly documented.
7652
7653 The recognized allocators are listed in erts_alloc(3).
7654 Information about super carriers can be obtained from ERTS
7655 8.0 with {allocator, erts_mmap} or from ERTS 5.10.4; the
7656 returned list when calling with {allocator, mseg_alloc} also
7657 includes an {erts_mmap, _} tuple as one element in the list.
7658
7659 After reading the erts_alloc(3) documentation, the returned
7660 information more or less speaks for itself, but it can be
7661 worth explaining some things. Call counts are presented by
7662 two values, the first value is giga calls, and the second
7663 value is calls. mbcs and sbcs denote multi-block carriers,
7664 and single-block carriers, respectively. Sizes are presented
7665 in bytes. When a size is not presented, it is the amount of
7666 something. Sizes and amounts are often presented by three
7667 values:
7668
7669 * The first is the current value.
7670
7671 * The second is the maximum value since the last call to
7672 erlang:system_info({allocator, Alloc}).
7673
7674 * The third is the maximum value since the emulator was
7675 started.
7676
7677 If only one value is present, it is the current value.
7678 fix_alloc memory block types are presented by two values.
7679 The first value is the memory pool size and the second value
7680 is the used memory size.
7681
7682 alloc_util_allocators:
7683 Returns a list of the names of all allocators using the ERTS
7684 internal alloc_util framework as atoms. For more informa‐
7685 tion, see section The alloc_util framework in erts_alloc(3).
7686
7687 {allocator_sizes, Alloc}:
7688 Returns various size information for the specified alloca‐
7689 tor. The information returned is a subset of the information
7690 returned by erlang:system_info({allocator, Alloc}).
7691
7692 elib_malloc:
7693 This option will be removed in a future release. The return
7694 value will always be false, as the elib_malloc allocator has
7695 been removed.
7696
7697 erlang:system_info(Item :: cpu_topology) -> CpuTopology
7698
7699 erlang:system_info(Item ::
7700 {cpu_topology, defined | detected | used}) ->
7701 CpuTopology
7702
7703 erlang:system_info(Item ::
7704 logical_processors |
7705 logical_processors_available |
7706 logical_processors_online) ->
7707 unknown | integer() >= 1
7708
7709 erlang:system_info(Item :: update_cpu_info) -> changed | unchanged
7710
7711 Types:
7712
7713 cpu_topology() = [LevelEntry :: level_entry()] | undefined
7714 All LevelEntrys of a list must contain the same LevelTag,
7715 except on the top level where both node and processor‐
7716 LevelTags can coexist.
7717 level_entry() =
7718 {LevelTag :: level_tag(), SubLevel :: sub_level()} |
7719 {LevelTag :: level_tag(),
7720 InfoList :: info_list(),
7721 SubLevel :: sub_level()}
7722 {LevelTag, SubLevel} == {LevelTag, [], SubLevel}
7723 level_tag() = core | node | processor | thread
7724 More LevelTags can be introduced in a future release.
7725 sub_level() =
7726 [LevelEntry :: level_entry()] |
7727 (LogicalCpuId :: {logical, integer() >= 0})
7728 info_list() = []
7729 The info_list() can be extended in a future release.
7730
7731 Returns various information about the CPU topology of the cur‐
7732 rent system (emulator) as specified by Item:
7733
7734 cpu_topology:
7735 Returns the CpuTopology currently used by the emulator. The
7736 CPU topology is used when binding schedulers to logical pro‐
7737 cessors. The CPU topology used is the user-defined CPU
7738 topology, if such exists, otherwise the automatically
7739 detected CPU topology, if such exists. If no CPU topology
7740 exists, undefined is returned.
7741
7742 node refers to Non-Uniform Memory Access (NUMA) nodes.
7743 thread refers to hardware threads (for example, Intel hyper-
7744 threads).
7745
7746 A level in term CpuTopology can be omitted if only one entry
7747 exists and InfoList is empty.
7748
7749 thread can only be a sublevel to core. core can be a sub‐
7750 level to processor or node. processor can be on the top
7751 level or a sublevel to node. node can be on the top level or
7752 a sublevel to processor. That is, NUMA nodes can be proces‐
7753 sor internal or processor external. A CPU topology can con‐
7754 sist of a mix of processor internal and external NUMA nodes,
7755 as long as each logical CPU belongs to one NUMA node. Cache
7756 hierarchy is not part of the CpuTopology type, but will be
7757 in a future release. Other things can also make it into the
7758 CPU topology in a future release. So, expect the CpuTopology
7759 type to change.
7760
7761 {cpu_topology, defined}:
7762
7763
7764 Returns the user-defined CpuTopology. For more information,
7765 see command-line flag +sct in erl(1) and argument cpu_topol‐
7766 ogy.
7767
7768 {cpu_topology, detected}:
7769
7770
7771 Returns the automatically detected CpuTopologyy. The emula‐
7772 tor detects the CPU topology on some newer Linux, Solaris,
7773 FreeBSD, and Windows systems. On Windows system with more
7774 than 32 logical processors, the CPU topology is not
7775 detected.
7776
7777 For more information, see argument cpu_topology.
7778
7779 {cpu_topology, used}:
7780 Returns CpuTopology used by the emulator. For more informa‐
7781 tion, see argument cpu_topology.
7782
7783 logical_processors:
7784 Returns the detected number of logical processors configured
7785 in the system. The return value is either an integer, or the
7786 atom unknown if the emulator cannot detect the configured
7787 logical processors.
7788
7789 logical_processors_available:
7790 Returns the detected number of logical processors available
7791 to the Erlang runtime system. The return value is either an
7792 integer, or the atom unknown if the emulator cannot detect
7793 the available logical processors. The number of available
7794 logical processors is less than or equal to the number of
7795 logical processors online.
7796
7797 logical_processors_online:
7798 Returns the detected number of logical processors online on
7799 the system. The return value is either an integer, or the
7800 atom unknown if the emulator cannot detect logical proces‐
7801 sors online. The number of logical processors online is less
7802 than or equal to the number of logical processors config‐
7803 ured.
7804
7805 update_cpu_info:
7806 The runtime system rereads the CPU information available and
7807 updates its internally stored information about the detected
7808 CPU topology and the number of logical processors config‐
7809 ured, online, and available.
7810
7811 If the CPU information has changed since the last time it
7812 was read, the atom changed is returned, otherwise the atom
7813 unchanged. If the CPU information has changed, you probably
7814 want to adjust the number of schedulers online. You typi‐
7815 cally want to have as many schedulers online as logical pro‐
7816 cessors available.
7817
7818 erlang:system_info(Item :: fullsweep_after) ->
7819 {fullsweep_after, integer() >= 0}
7820
7821 erlang:system_info(Item :: garbage_collection) ->
7822 [{atom(), integer()}]
7823
7824 erlang:system_info(Item :: heap_sizes) -> [integer() >= 0]
7825
7826 erlang:system_info(Item :: heap_type) -> private
7827
7828 erlang:system_info(Item :: max_heap_size) ->
7829 {max_heap_size,
7830 MaxHeapSize :: max_heap_size()}
7831
7832 erlang:system_info(Item :: message_queue_data) ->
7833 message_queue_data()
7834
7835 erlang:system_info(Item :: min_heap_size) ->
7836 {min_heap_size,
7837 MinHeapSize :: integer() >= 1}
7838
7839 erlang:system_info(Item :: min_bin_vheap_size) ->
7840 {min_bin_vheap_size,
7841 MinBinVHeapSize :: integer() >= 1}
7842
7843 erlang:system_info(Item :: procs) -> binary()
7844
7845 Types:
7846
7847 message_queue_data() = off_heap | on_heap
7848 max_heap_size() =
7849 integer() >= 0 |
7850 #{size => integer() >= 0,
7851 kill => boolean(),
7852 error_logger => boolean()}
7853
7854 Returns information about the default process heap settings:
7855
7856 fullsweep_after:
7857 Returns {fullsweep_after, integer() >= 0}, which is the
7858 fullsweep_after garbage collection setting used by default.
7859 For more information, see garbage_collection described
7860 below.
7861
7862 garbage_collection:
7863 Returns a list describing the default garbage collection
7864 settings. A process spawned on the local node by a spawn or
7865 spawn_link uses these garbage collection settings. The
7866 default settings can be changed by using erlang:sys‐
7867 tem_flag/2. spawn_opt/2,3,4 can spawn a process that does
7868 not use the default settings.
7869
7870 heap_sizes:
7871 Returns a list of integers representing valid heap sizes in
7872 words. All Erlang heaps are sized from sizes in this list.
7873
7874 heap_type:
7875 Returns the heap type used by the current emulator. One heap
7876 type exists:
7877
7878 private:
7879 Each process has a heap reserved for its use and no ref‐
7880 erences between heaps of different processes are allowed.
7881 Messages passed between processes are copied between
7882 heaps.
7883
7884 max_heap_size:
7885 Returns {max_heap_size, MaxHeapSize}, where MaxHeapSize is
7886 the current system-wide maximum heap size settings for
7887 spawned processes. This setting can be set using the com‐
7888 mand-line flags +hmax, +hmaxk and +hmaxel in erl(1). It can
7889 also be changed at runtime using erlang:sys‐
7890 tem_flag(max_heap_size, MaxHeapSize). For more details about
7891 the max_heap_size process flag, see
7892 process_flag(max_heap_size, MaxHeapSize).
7893
7894 message_queue_data:
7895 Returns the default value of the message_queue_data process
7896 flag, which is either off_heap or on_heap. This default is
7897 set by command-line argument +hmqd in erl(1). For more
7898 information on the message_queue_data process flag, see doc‐
7899 umentation of process_flag(message_queue_data, MQD).
7900
7901 min_heap_size:
7902 Returns {min_heap_size, MinHeapSize}, where MinHeapSize is
7903 the current system-wide minimum heap size for spawned pro‐
7904 cesses.
7905
7906 min_bin_vheap_size:
7907 Returns {min_bin_vheap_size, MinBinVHeapSize}, where MinBin‐
7908 VHeapSize is the current system-wide minimum binary virtual
7909 heap size for spawned processes.
7910
7911 procs:
7912 Returns a binary containing a string of process and port
7913 information formatted as in Erlang crash dumps. For more
7914 information, see section How to interpret the Erlang crash
7915 dumps in the User's Guide.
7916
7917 erlang:system_info(Item :: atom_count) -> integer() >= 1
7918
7919 erlang:system_info(Item :: atom_limit) -> integer() >= 1
7920
7921 erlang:system_info(Item :: ets_count) -> integer() >= 1
7922
7923 erlang:system_info(Item :: ets_limit) -> integer() >= 1
7924
7925 erlang:system_info(Item :: port_count) -> integer() >= 0
7926
7927 erlang:system_info(Item :: port_limit) -> integer() >= 1
7928
7929 erlang:system_info(Item :: process_count) -> integer() >= 1
7930
7931 erlang:system_info(Item :: process_limit) -> integer() >= 1
7932
7933 Returns information about the current system (emulator) limits
7934 as specified by Item:
7935
7936 atom_count:
7937 Returns the number of atoms currently existing at the local
7938 node. The value is given as an integer.
7939
7940 atom_limit:
7941 Returns the maximum number of atoms allowed. This limit can
7942 be increased at startup by passing command-line flag +t to
7943 erl(1).
7944
7945 ets_count:
7946 Returns the number of ETS tables currently existing at the
7947 local node.
7948
7949 ets_limit:
7950 Returns the limit for number of ETS tables. This limit is
7951 partially obsolete and number of tables are only limited by
7952 available memory.
7953
7954 port_count:
7955 Returns the number of ports currently existing at the local
7956 node. The value is given as an integer. This is the same
7957 value as returned by length(erlang:ports()), but more effi‐
7958 cient.
7959
7960 port_limit:
7961 Returns the maximum number of simultaneously existing ports
7962 at the local node as an integer. This limit can be config‐
7963 ured at startup by using command-line flag +Q in erl(1).
7964
7965 process_count:
7966 Returns the number of processes currently existing at the
7967 local node. The value is given as an integer. This is the
7968 same value as returned by length(processes()), but more
7969 efficient.
7970
7971 process_limit:
7972 Returns the maximum number of simultaneously existing pro‐
7973 cesses at the local node. The value is given as an integer.
7974 This limit can be configured at startup by using command-
7975 line flag +P in erl(1).
7976
7977 erlang:system_info(Item :: end_time) -> integer() >= 0
7978
7979 erlang:system_info(Item :: os_monotonic_time_source) ->
7980 [{atom(), term()}]
7981
7982 erlang:system_info(Item :: os_system_time_source) ->
7983 [{atom(), term()}]
7984
7985 erlang:system_info(Item :: start_time) -> integer()
7986
7987 erlang:system_info(Item :: time_correction) -> true | false
7988
7989 erlang:system_info(Item :: time_offset) ->
7990 preliminary | final | volatile
7991
7992 erlang:system_info(Item :: time_warp_mode) ->
7993 no_time_warp | single_time_warp |
7994 multi_time_warp
7995
7996 erlang:system_info(Item :: tolerant_timeofday) ->
7997 enabled | disabled
7998
7999 Returns information about the current system (emulator) time as
8000 specified by Item:
8001
8002 end_time:
8003 The last Erlang monotonic time in native time unit that can
8004 be represented internally in the current Erlang runtime sys‐
8005 tem instance. The time between the start time and the end
8006 time is at least a quarter of a millennium.
8007
8008 os_monotonic_time_source:
8009 Returns a list containing information about the source of OS
8010 monotonic time that is used by the runtime system.
8011
8012 If [] is returned, no OS monotonic time is available. The
8013 list contains two-tuples with Keys as first element, and
8014 Values as second element. The order of these tuples is unde‐
8015 fined. The following tuples can be part of the list, but
8016 more tuples can be introduced in the future:
8017
8018 {function, Function}:
8019 Function is the name of the function used. This tuple
8020 always exists if OS monotonic time is available to the
8021 runtime system.
8022
8023 {clock_id, ClockId}:
8024 This tuple only exists if Function can be used with dif‐
8025 ferent clocks. ClockId corresponds to the clock identifier
8026 used when calling Function.
8027
8028 {resolution, OsMonotonicTimeResolution}:
8029 Highest possible resolution of current OS monotonic time
8030 source as parts per second. If no resolution information
8031 can be retrieved from the OS, OsMonotonicTimeResolution is
8032 set to the resolution of the time unit of Functions return
8033 value. That is, the actual resolution can be lower than
8034 OsMonotonicTimeResolution. Notice that the resolution does
8035 not say anything about the accuracy or whether the pre‐
8036 cision aligns with the resolution. You do, however, know
8037 that the precision is not better than OsMonotonicTimeReso‐
8038 lution.
8039
8040 {extended, Extended}:
8041 Extended equals yes if the range of time values has been
8042 extended; otherwise Extended equals no. The range must be
8043 extended if Function returns values that wrap fast. This
8044 typically is the case when the return value is a 32-bit
8045 value.
8046
8047 {parallel, Parallel}:
8048 Parallel equals yes if Function is called in parallel from
8049 multiple threads. If it is not called in parallel, because
8050 calls must be serialized, Parallel equals no.
8051
8052 {time, OsMonotonicTime}:
8053 OsMonotonicTime equals current OS monotonic time in native
8054 time unit.
8055
8056 os_system_time_source:
8057 Returns a list containing information about the source of OS
8058 system time that is used by the runtime system.
8059
8060 The list contains two-tuples with Keys as first element, and
8061 Values as second element. The order of these tuples is unde‐
8062 fined. The following tuples can be part of the list, but
8063 more tuples can be introduced in the future:
8064
8065 {function, Function}:
8066 Function is the name of the funcion used.
8067
8068 {clock_id, ClockId}:
8069 Exists only if Function can be used with different clocks.
8070 ClockId corresponds to the clock identifier used when
8071 calling Function.
8072
8073 {resolution, OsSystemTimeResolution}:
8074 Highest possible resolution of current OS system time
8075 source as parts per second. If no resolution information
8076 can be retrieved from the OS, OsSystemTimeResolution is
8077 set to the resolution of the time unit of Functions return
8078 value. That is, the actual resolution can be lower than
8079 OsSystemTimeResolution. Notice that the resolution does
8080 not say anything about the accuracy or whether the pre‐
8081 cision do align with the resolution. You do, however, know
8082 that the precision is not better than OsSystemTimeResolu‐
8083 tion.
8084
8085 {parallel, Parallel}:
8086 Parallel equals yes if Function is called in parallel from
8087 multiple threads. If it is not called in parallel, because
8088 calls needs to be serialized, Parallel equals no.
8089
8090 {time, OsSystemTime}:
8091 OsSystemTime equals current OS system time in native time
8092 unit.
8093
8094 start_time:
8095 The Erlang monotonic time in native time unit at the time
8096 when current Erlang runtime system instance started.
8097
8098 See also erlang:system_info(end_time).
8099
8100 time_correction:
8101 Returns a boolean value indicating whether time correction
8102 is enabled or not.
8103
8104 time_offset:
8105 Returns the state of the time offset:
8106
8107 preliminary:
8108 The time offset is preliminary, and will be changed and
8109 finalized later. The preliminary time offset is used dur‐
8110 ing the preliminary phase of the single time warp mode.
8111
8112 final:
8113 The time offset is final. This either because no time
8114 warp mode is used, or because the time offset have been
8115 finalized when single time warp mode is used.
8116
8117 volatile:
8118 The time offset is volatile. That is, it can change at any
8119 time. This is because multi-time warp mode is used.
8120
8121 time_warp_mode:
8122 Returns a value identifying the time warp mode that is
8123 used:
8124
8125 no_time_warp:
8126 The no time warp mode is used.
8127
8128 single_time_warp:
8129 The single time warp mode is used.
8130
8131 multi_time_warp:
8132 The multi-time warp mode is used.
8133
8134 tolerant_timeofday:
8135 Returns whether a pre ERTS 7.0 backwards compatible compen‐
8136 sation for sudden changes of system time is enabled or dis‐
8137 abled. Such compensation is enabled when the time offset is
8138 final, and time correction is enabled.
8139
8140 erlang:system_info(Item :: dirty_cpu_schedulers) ->
8141 integer() >= 0
8142
8143 erlang:system_info(Item :: dirty_cpu_schedulers_online) ->
8144 integer() >= 0
8145
8146 erlang:system_info(Item :: dirty_io_schedulers) ->
8147 integer() >= 0
8148
8149 erlang:system_info(Item :: multi_scheduling) ->
8150 disabled | blocked | blocked_normal |
8151 enabled
8152
8153 erlang:system_info(Item :: multi_scheduling_blockers) ->
8154 [Pid :: pid()]
8155
8156 erlang:system_info(Item :: otp_release) -> string()
8157
8158 erlang:system_info(Item :: scheduler_bind_type) ->
8159 spread | processor_spread | thread_spread |
8160 thread_no_node_processor_spread |
8161 no_node_processor_spread |
8162 no_node_thread_spread | no_spread | unbound
8163
8164 erlang:system_info(Item :: scheduler_bindings) -> tuple()
8165
8166 erlang:system_info(Item :: scheduler_id) ->
8167 SchedulerId :: integer() >= 1
8168
8169 erlang:system_info(Item :: schedulers | schedulers_online) ->
8170 integer() >= 1
8171
8172 erlang:system_info(Item :: smp_support) -> boolean()
8173
8174 erlang:system_info(Item :: threads) -> boolean()
8175
8176 erlang:system_info(Item :: thread_pool_size) -> integer() >= 0
8177
8178 Returns information about schedulers, scheduling and threads in
8179 the current system as specified by Item:
8180
8181 dirty_cpu_schedulers:
8182 Returns the number of dirty CPU scheduler threads used by
8183 the emulator. Dirty CPU schedulers execute CPU-bound native
8184 functions, such as NIFs, linked-in driver code, and BIFs
8185 that cannot be managed cleanly by the normal emulator sched‐
8186 ulers.
8187
8188 The number of dirty CPU scheduler threads is determined at
8189 emulator boot time and cannot be changed after that. How‐
8190 ever, the number of dirty CPU scheduler threads online can
8191 be changed at any time. The number of dirty CPU schedulers
8192 can be set at startup by passing command-line flag +SDcpu or
8193 +SDPcpu in erl(1).
8194
8195 See also erlang:system_flag(dirty_cpu_schedulers_online,
8196 DirtyCPUSchedulersOnline), erlang:sys‐
8197 tem_info(dirty_cpu_schedulers_online), erlang:sys‐
8198 tem_info(dirty_io_schedulers), erlang:system_info(sched‐
8199 ulers), erlang:system_info(schedulers_online), and
8200 erlang:system_flag(schedulers_online, SchedulersOnline).
8201
8202 dirty_cpu_schedulers_online:
8203 Returns the number of dirty CPU schedulers online. The
8204 return value satisfies 1 <= DirtyCPUSchedulersOnline <= N,
8205 where N is the smallest of the return values of erlang:sys‐
8206 tem_info(dirty_cpu_schedulers) and erlang:system_info(sched‐
8207 ulers_online).
8208
8209 The number of dirty CPU schedulers online can be set at
8210 startup by passing command-line flag +SDcpu in erl(1).
8211
8212 For more information, see erlang:sys‐
8213 tem_info(dirty_cpu_schedulers), erlang:sys‐
8214 tem_info(dirty_io_schedulers), erlang:system_info(sched‐
8215 ulers_online), and erlang:system_flag(dirty_cpu_sched‐
8216 ulers_online, DirtyCPUSchedulersOnline).
8217
8218 dirty_io_schedulers:
8219 Returns the number of dirty I/O schedulers as an integer.
8220 Dirty I/O schedulers execute I/O-bound native functions,
8221 such as NIFs and linked-in driver code, which cannot be man‐
8222 aged cleanly by the normal emulator schedulers.
8223
8224 This value can be set at startup by passing command-line
8225 argument +SDio in erl(1).
8226
8227 For more information, see erlang:sys‐
8228 tem_info(dirty_cpu_schedulers), erlang:sys‐
8229 tem_info(dirty_cpu_schedulers_online), and erlang:sys‐
8230 tem_flag(dirty_cpu_schedulers_online, DirtyCPUSchedulersOn‐
8231 line).
8232
8233 multi_scheduling:
8234 Returns one of the following:
8235
8236 disabled:
8237 The emulator has been started with only one scheduler
8238 thread.
8239
8240 blocked:
8241 The emulator has more than one scheduler thread, but all
8242 scheduler threads except one are blocked. That is, only
8243 one scheduler thread schedules Erlang processes and exe‐
8244 cutes Erlang code.
8245
8246 blocked_normal:
8247 The emulator has more than one scheduler thread, but all
8248 normal scheduler threads except one are blocked. Notice
8249 that dirty schedulers are not blocked, and can schedule
8250 Erlang processes and execute native code.
8251
8252 enabled:
8253 The emulator has more than one scheduler thread, and no
8254 scheduler threads are blocked. That is, all available
8255 scheduler threads schedule Erlang processes and execute
8256 Erlang code.
8257
8258 See also erlang:system_flag(multi_scheduling, BlockState),
8259 erlang:system_info(multi_scheduling_blockers), erlang:sys‐
8260 tem_info(normal_multi_scheduling_blockers), and erlang:sys‐
8261 tem_info(schedulers).
8262
8263 multi_scheduling_blockers:
8264 Returns a list of Pids when multi-scheduling is blocked,
8265 otherwise the empty list is returned. The Pids in the list
8266 represent all the processes currently blocking multi-sched‐
8267 uling. A Pid occurs only once in the list, even if the cor‐
8268 responding process has blocked multiple times.
8269
8270 See also erlang:system_flag(multi_scheduling, BlockState),
8271 erlang:system_info(multi_scheduling), erlang:sys‐
8272 tem_info(normal_multi_scheduling_blockers), and erlang:sys‐
8273 tem_info(schedulers).
8274
8275 normal_multi_scheduling_blockers:
8276 Returns a list of Pids when normal multi-scheduling is
8277 blocked (that is, all normal schedulers but one is blocked),
8278 otherwise the empty list is returned. The Pids in the list
8279 represent all the processes currently blocking normal multi-
8280 scheduling. A Pid occurs only once in the list, even if the
8281 corresponding process has blocked multiple times.
8282
8283 See also erlang:system_flag(multi_scheduling, BlockState),
8284 erlang:system_info(multi_scheduling), erlang:sys‐
8285 tem_info(multi_scheduling_blockers), and erlang:sys‐
8286 tem_info(schedulers).
8287
8288 scheduler_bind_type:
8289 Returns information about how the user has requested sched‐
8290 ulers to be bound or not bound.
8291
8292 Notice that although a user has requested schedulers to be
8293 bound, they can silently have failed to bind. To inspect the
8294 scheduler bindings, call erlang:system_info(scheduler_bind‐
8295 ings).
8296
8297 For more information, see command-line argument +sbt in
8298 erl(1) and erlang:system_info(scheduler_bindings).
8299
8300 scheduler_bindings:
8301 Returns information about the currently used scheduler bind‐
8302 ings.
8303
8304 A tuple of a size equal to erlang:system_info(schedulers) is
8305 returned. The tuple elements are integers or the atom
8306 unbound. Logical processor identifiers are represented as
8307 integers. The Nth element of the tuple equals the current
8308 binding for the scheduler with the scheduler identifier
8309 equal to N. For example, if the schedulers are bound, ele‐
8310 ment(erlang:system_info(scheduler_id), erlang:sys‐
8311 tem_info(scheduler_bindings)) returns the identifier of the
8312 logical processor that the calling process is executing on.
8313
8314 Notice that only schedulers online can be bound to logical
8315 processors.
8316
8317 For more information, see command-line argument +sbt in
8318 erl(1) and erlang:system_info(schedulers_online).
8319
8320 scheduler_id:
8321 Returns the scheduler ID (SchedulerId) of the scheduler
8322 thread that the calling process is executing on. SchedulerId
8323 is a positive integer, where 1 <= SchedulerId <= erlang:sys‐
8324 tem_info(schedulers).
8325
8326 See also erlang:system_info(schedulers).
8327
8328 schedulers:
8329 Returns the number of scheduler threads used by the emula‐
8330 tor. Scheduler threads online schedules Erlang processes and
8331 Erlang ports, and execute Erlang code and Erlang linked-in
8332 driver code.
8333
8334 The number of scheduler threads is determined at emulator
8335 boot time and cannot be changed later. However, the number
8336 of schedulers online can be changed at any time.
8337
8338 See also erlang:system_flag(schedulers_online, SchedulersOn‐
8339 line), erlang:system_info(schedulers_online), erlang:sys‐
8340 tem_info(scheduler_id), erlang:system_flag(multi_scheduling,
8341 BlockState), erlang:system_info(multi_scheduling),
8342 erlang:system_info(normal_multi_scheduling_blockers) and
8343 erlang:system_info(multi_scheduling_blockers).
8344
8345 schedulers_online:
8346 Returns the number of schedulers online. The scheduler iden‐
8347 tifiers of schedulers online satisfy the relationship 1 <=
8348 SchedulerId <= erlang:system_info(schedulers_online).
8349
8350 For more information, see erlang:system_info(schedulers) and
8351 erlang:system_flag(schedulers_online, SchedulersOnline).
8352
8353 smp_support:
8354 Returns true.
8355
8356 threads:
8357 Returns true.
8358
8359 thread_pool_size:
8360
8361
8362 Returns the number of async threads in the async thread pool
8363 used for asynchronous driver calls
8364 (erl_driver:driver_async()). The value is given as an inte‐
8365 ger.
8366
8367 erlang:system_info(Item :: creation) -> integer()
8368
8369 erlang:system_info(Item :: delayed_node_table_gc) ->
8370 infinity | integer() >= 0
8371
8372 erlang:system_info(Item :: dist) -> binary()
8373
8374 erlang:system_info(Item :: dist_buf_busy_limit) ->
8375 integer() >= 0
8376
8377 erlang:system_info(Item :: dist_ctrl) ->
8378 {Node :: node(),
8379 ControllingEntity :: port() | pid()}
8380
8381 Returns information about Erlang Distribution in the current
8382 system as specified by Item:
8383
8384 creation:
8385 Returns the creation of the local node as an integer. The
8386 creation is changed when a node is restarted. The creation
8387 of a node is stored in process identifiers, port identi‐
8388 fiers, and references. This makes it (to some extent) possi‐
8389 ble to distinguish between identifiers from different incar‐
8390 nations of a node. The valid creations are integers in the
8391 range 1..3, but this will probably change in a future
8392 release. If the node is not alive, 0 is returned.
8393
8394 delayed_node_table_gc:
8395 Returns the amount of time in seconds garbage collection of
8396 an entry in a node table is delayed. This limit can be set
8397 on startup by passing command-line flag +zdntgc to erl(1).
8398 For more information, see the documentation of the command-
8399 line flag.
8400
8401 dist:
8402 Returns a binary containing a string of distribution infor‐
8403 mation formatted as in Erlang crash dumps. For more informa‐
8404 tion, see section How to interpret the Erlang crash dumps
8405 in the User's Guide.
8406
8407 dist_buf_busy_limit:
8408 Returns the value of the distribution buffer busy limit in
8409 bytes. This limit can be set at startup by passing command-
8410 line flag +zdbbl to erl(1).
8411
8412 dist_ctrl:
8413 Returns a list of tuples {Node, ControllingEntity}, one
8414 entry for each connected remote node. Node is the node name
8415 and ControllingEntity is the port or process identifier
8416 responsible for the communication to that node. More specif‐
8417 ically, ControllingEntity for nodes connected through TCP/IP
8418 (the normal case) is the socket used in communication with
8419 the specific node.
8420
8421 erlang:system_info(Item :: build_type) ->
8422 opt | debug | purify | quantify | purecov |
8423 gcov | valgrind | gprof | lcnt | frmptr
8424
8425 erlang:system_info(Item :: c_compiler_used) -> {atom(), term()}
8426
8427 erlang:system_info(Item :: check_io) -> [term()]
8428
8429 erlang:system_info(Item :: compat_rel) -> integer()
8430
8431 erlang:system_info(Item :: debug_compiled) -> boolean()
8432
8433 erlang:system_info(Item :: driver_version) -> string()
8434
8435 erlang:system_info(Item :: dynamic_trace) ->
8436 none | dtrace | systemtap
8437
8438 erlang:system_info(Item :: dynamic_trace_probes) -> boolean()
8439
8440 erlang:system_info(Item :: info) -> binary()
8441
8442 erlang:system_info(Item :: kernel_poll) -> boolean()
8443
8444 erlang:system_info(Item :: loaded) -> binary()
8445
8446 erlang:system_info(Item :: machine) -> string()
8447
8448 erlang:system_info(Item :: modified_timing_level) ->
8449 integer() | undefined
8450
8451 erlang:system_info(Item :: nif_version) -> string()
8452
8453 erlang:system_info(Item :: otp_release) -> string()
8454
8455 erlang:system_info(Item :: port_parallelism) -> boolean()
8456
8457 erlang:system_info(Item :: system_architecture) -> string()
8458
8459 erlang:system_info(Item :: system_logger) ->
8460 logger | undefined | pid()
8461
8462 erlang:system_info(Item :: system_version) -> string()
8463
8464 erlang:system_info(Item :: trace_control_word) ->
8465 integer() >= 0
8466
8467 erlang:system_info(Item :: version) -> string()
8468
8469 erlang:system_info(Item ::
8470 wordsize |
8471 {wordsize, internal} |
8472 {wordsize, external}) ->
8473 4 | 8
8474
8475 Returns various information about the current system (emulator)
8476 as specified by Item:
8477
8478 build_type:
8479 Returns an atom describing the build type of the runtime
8480 system. This is normally the atom opt for optimized. Other
8481 possible return values are debug, purify, quantify, purecov,
8482 gcov, valgrind, gprof, and lcnt. Possible return values can
8483 be added or removed at any time without prior notice.
8484
8485 c_compiler_used:
8486 Returns a two-tuple describing the C compiler used when com‐
8487 piling the runtime system. The first element is an atom
8488 describing the name of the compiler, or undefined if
8489 unknown. The second element is a term describing the version
8490 of the compiler, or undefined if unknown.
8491
8492 check_io:
8493 Returns a list containing miscellaneous information about
8494 the emulators internal I/O checking. Notice that the content
8495 of the returned list can vary between platforms and over
8496 time. It is only guaranteed that a list is returned.
8497
8498 compat_rel:
8499 Returns the compatibility mode of the local node as an inte‐
8500 ger. The integer returned represents the Erlang/OTP release
8501 that the current emulator has been set to be backward com‐
8502 patible with. The compatibility mode can be configured at
8503 startup by using command-line flag +R in erl(1).
8504
8505 debug_compiled:
8506 Returns true if the emulator has been debug-compiled, other‐
8507 wise false.
8508
8509 driver_version:
8510 Returns a string containing the Erlang driver version used
8511 by the runtime system. It has the form "<major ver>.<minor
8512 ver>".
8513
8514 dynamic_trace:
8515 Returns an atom describing the dynamic trace framework com‐
8516 piled into the virtual machine. It can be dtrace, systemtap,
8517 or none. For a commercial or standard build, it is always
8518 none. The other return values indicate a custom configura‐
8519 tion (for example, ./configure --with-dynamic-trace=dtrace).
8520 For more information about dynamic tracing, see dyntrace(3)
8521 manual page and the README.dtrace/README.systemtap files in
8522 the Erlang source code top directory.
8523
8524 dynamic_trace_probes:
8525 Returns a boolean() indicating if dynamic trace probes
8526 (dtrace or systemtap) are built into the emulator. This can
8527 only be true if the virtual machine was built for dynamic
8528 tracing (that is, system_info(dynamic_trace) returns dtrace
8529 or systemtap).
8530
8531 info:
8532 Returns a binary containing a string of miscellaneous system
8533 information formatted as in Erlang crash dumps. For more
8534 information, see section How to interpret the Erlang crash
8535 dumps in the User's Guide.
8536
8537 kernel_poll:
8538 Returns true if the emulator uses some kind of kernel-poll
8539 implementation, otherwise false.
8540
8541 loaded:
8542 Returns a binary containing a string of loaded module infor‐
8543 mation formatted as in Erlang crash dumps. For more informa‐
8544 tion, see section How to interpret the Erlang crash dumps in
8545 the User's Guide.
8546
8547 machine:
8548 Returns a string containing the Erlang machine name.
8549
8550 modified_timing_level:
8551 Returns the modified timing-level (an integer) if modified
8552 timing is enabled, otherwise undefined. For more information
8553 about modified timing, see command-line flag +T in erl(1)
8554
8555 nif_version:
8556 Returns a string containing the version of the Erlang NIF
8557 interface used by the runtime system. It is on the form
8558 "<major ver>.<minor ver>".
8559
8560 otp_release:
8561
8562
8563 Returns a string containing the OTP release number of the
8564 OTP release that the currently executing ERTS application is
8565 part of.
8566
8567 As from Erlang/OTP 17, the OTP release number corresponds to
8568 the major OTP version number. No erlang:system_info() argu‐
8569 ment gives the exact OTP version. This is because the exact
8570 OTP version in the general case is difficult to determine.
8571 For more information, see the description of versions in
8572 System principles in System Documentation.
8573
8574 port_parallelism:
8575 Returns the default port parallelism scheduling hint used.
8576 For more information, see command-line argument +spp in
8577 erl(1).
8578
8579 system_architecture:
8580 Returns a string containing the processor and OS architec‐
8581 ture the emulator is built for.
8582
8583 system_logger:
8584 Returns the current system_logger as set by erlang:sys‐
8585 tem_flag(system_logger, _).
8586
8587 system_version:
8588 Returns a string containing version number and some impor‐
8589 tant properties, such as the number of schedulers.
8590
8591 trace_control_word:
8592 Returns the value of the node trace control word. For more
8593 information, see function get_tcw in section Match Specifi‐
8594 cations in Erlang in the User's Guide.
8595
8596 version:
8597 Returns a string containing the version number of the emula‐
8598 tor.
8599
8600 wordsize:
8601 Same as {wordsize, internal}.
8602
8603 {wordsize, internal}:
8604 Returns the size of Erlang term words in bytes as an inte‐
8605 ger, that is, 4 is returned on a 32-bit architecture, and 8
8606 is returned on a pure 64-bit architecture. On a halfword
8607 64-bit emulator, 4 is returned, as the Erlang terms are
8608 stored using a virtual word size of half the system word
8609 size.
8610
8611 {wordsize, external}:
8612 Returns the true word size of the emulator, that is, the
8613 size of a pointer. The value is given in bytes as an inte‐
8614 ger. On a pure 32-bit architecture, 4 is returned. On both a
8615 half word and on a pure 64-bit architecture, 8 is returned.
8616
8617 erlang:system_monitor() -> MonSettings
8618
8619 Types:
8620
8621 MonSettings = undefined | {MonitorPid, Options}
8622 MonitorPid = pid()
8623 Options = [system_monitor_option()]
8624 system_monitor_option() =
8625 busy_port | busy_dist_port |
8626 {long_gc, integer() >= 0} |
8627 {long_schedule, integer() >= 0} |
8628 {large_heap, integer() >= 0}
8629
8630 Returns the current system monitoring settings set by
8631 erlang:system_monitor/2 as {MonitorPid, Options}, or undefined
8632 if no settings exist. The order of the options can be different
8633 from the one that was set.
8634
8635 erlang:system_monitor(Arg) -> MonSettings
8636
8637 Types:
8638
8639 Arg = MonSettings = undefined | {MonitorPid, Options}
8640 MonitorPid = pid()
8641 Options = [system_monitor_option()]
8642 system_monitor_option() =
8643 busy_port | busy_dist_port |
8644 {long_gc, integer() >= 0} |
8645 {long_schedule, integer() >= 0} |
8646 {large_heap, integer() >= 0}
8647
8648 When called with argument undefined, all system performance mon‐
8649 itoring settings are cleared.
8650
8651 Calling the function with {MonitorPid, Options} as argument is
8652 the same as calling erlang:system_monitor(MonitorPid, Options).
8653
8654 Returns the previous system monitor settings just like
8655 erlang:system_monitor/0.
8656
8657 erlang:system_monitor(MonitorPid, Options) -> MonSettings
8658
8659 Types:
8660
8661 MonitorPid = pid()
8662 Options = [system_monitor_option()]
8663 MonSettings = undefined | {OldMonitorPid, OldOptions}
8664 OldMonitorPid = pid()
8665 OldOptions = [system_monitor_option()]
8666 system_monitor_option() =
8667 busy_port | busy_dist_port |
8668 {long_gc, integer() >= 0} |
8669 {long_schedule, integer() >= 0} |
8670 {large_heap, integer() >= 0}
8671
8672 Sets the system performance monitoring options. MonitorPid is a
8673 local process identifier (pid) receiving system monitor mes‐
8674 sages. The second argument is a list of monitoring options:
8675
8676 {long_gc, Time}:
8677 If a garbage collection in the system takes at least Time
8678 wall clock milliseconds, a message {monitor, GcPid, long_gc,
8679 Info} is sent to MonitorPid. GcPid is the pid that was
8680 garbage collected. Info is a list of two-element tuples
8681 describing the result of the garbage collection.
8682
8683 One of the tuples is {timeout, GcTime}, where GcTime is the
8684 time for the garbage collection in milliseconds. The other
8685 tuples are tagged with heap_size, heap_block_size,
8686 stack_size, mbuf_size, old_heap_size, and
8687 old_heap_block_size. These tuples are explained in the
8688 description of trace message gc_minor_start (see
8689 erlang:trace/3). New tuples can be added, and the order of
8690 the tuples in the Info list can be changed at any time with‐
8691 out prior notice.
8692
8693 {long_schedule, Time}:
8694 If a process or port in the system runs uninterrupted for at
8695 least Time wall clock milliseconds, a message {monitor,
8696 PidOrPort, long_schedule, Info} is sent to MonitorPid.
8697 PidOrPort is the process or port that was running. Info is a
8698 list of two-element tuples describing the event.
8699
8700 If a pid(), the tuples {timeout, Millis}, {in, Location},
8701 and {out, Location} are present, where Location is either an
8702 MFA ({Module, Function, Arity}) describing the function
8703 where the process was scheduled in/out, or the atom unde‐
8704 fined.
8705
8706 If a port(), the tuples {timeout, Millis} and {port_op,Op}
8707 are present. Op is one of proc_sig, timeout, input, output,
8708 event, or dist_cmd, depending on which driver callback was
8709 executing.
8710
8711 proc_sig is an internal operation and is never to appear,
8712 while the others represent the corresponding driver call‐
8713 backs timeout, ready_input, ready_output, event, and outputv
8714 (when the port is used by distribution). Value Millis in
8715 tuple timeout informs about the uninterrupted execution time
8716 of the process or port, which always is equal to or higher
8717 than the Time value supplied when starting the trace. New
8718 tuples can be added to the Info list in a future release.
8719 The order of the tuples in the list can be changed at any
8720 time without prior notice.
8721
8722 This can be used to detect problems with NIFs or drivers
8723 that take too long to execute. 1 ms is considered a good
8724 maximum time for a driver callback or a NIF. However, a
8725 time-sharing system is usually to consider everything < 100
8726 ms as "possible" and fairly "normal". However, longer sched‐
8727 ule times can indicate swapping or a misbehaving NIF/driver.
8728 Misbehaving NIFs and drivers can cause bad resource utiliza‐
8729 tion and bad overall system performance.
8730
8731 {large_heap, Size}:
8732 If a garbage collection in the system results in the allo‐
8733 cated size of a heap being at least Size words, a message
8734 {monitor, GcPid, large_heap, Info} is sent to MonitorPid.
8735 GcPid and Info are the same as for long_gc earlier, except
8736 that the tuple tagged with timeout is not present.
8737
8738 The monitor message is sent if the sum of the sizes of all
8739 memory blocks allocated for all heap generations after a
8740 garbage collection is equal to or higher than Size.
8741
8742 When a process is killed by max_heap_size, it is killed
8743 before the garbage collection is complete and thus no large
8744 heap message is sent.
8745
8746 busy_port:
8747 If a process in the system gets suspended because it sends
8748 to a busy port, a message {monitor, SusPid, busy_port, Port}
8749 is sent to MonitorPid. SusPid is the pid that got suspended
8750 when sending to Port.
8751
8752 busy_dist_port:
8753 If a process in the system gets suspended because it sends
8754 to a process on a remote node whose inter-node communication
8755 was handled by a busy port, a message {monitor, SusPid,
8756 busy_dist_port, Port} is sent to MonitorPid. SusPid is the
8757 pid that got suspended when sending through the inter-node
8758 communication port Port.
8759
8760 Returns the previous system monitor settings just like
8761 erlang:system_monitor/0.
8762
8763 The arguments to system_monitor/2 specifies how all system moni‐
8764 toring on the node should be done, not how it should be changed.
8765 This means only one process at a time (MonitorPid) can be the
8766 receiver of system monitor messages. Also, the way to clear a
8767 specific monitor option is to not include it in the list
8768 Options. All system monitoring will, however, be cleared if the
8769 process identified by MonitorPid terminates.
8770
8771 There are no special option values (like zero) to clear an
8772 option. Some of the options have a unspecified minimum value.
8773 Lower values will be adjusted to the minimum value. For example,
8774 it is currently not possible to monitor all garbage collections
8775 with {long_gc, 0}.
8776
8777 Note:
8778 If a monitoring process gets so large that it itself starts to
8779 cause system monitor messages when garbage collecting, the mes‐
8780 sages enlarge the process message queue and probably make the
8781 problem worse.
8782
8783 Keep the monitoring process neat and do not set the system moni‐
8784 tor limits too tight.
8785
8786
8787 Failures:
8788
8789 badarg:
8790 If MonitorPid does not exist.
8791
8792 badarg:
8793 If MonitorPid is not a local process.
8794
8795 erlang:system_profile() -> ProfilerSettings
8796
8797 Types:
8798
8799 ProfilerSettings = undefined | {ProfilerPid, Options}
8800 ProfilerPid = pid() | port()
8801 Options = [system_profile_option()]
8802 system_profile_option() =
8803 exclusive | runnable_ports | runnable_procs | scheduler |
8804 timestamp | monotonic_timestamp | strict_monotonic_timestamp
8805
8806 Returns the current system profiling settings set by erlang:sys‐
8807 tem_profile/2 as {ProfilerPid, Options}, or undefined if there
8808 are no settings. The order of the options can be different from
8809 the one that was set.
8810
8811 erlang:system_profile(ProfilerPid, Options) -> ProfilerSettings
8812
8813 Types:
8814
8815 ProfilerPid = pid() | port() | undefined
8816 Options = [system_profile_option()]
8817 ProfilerSettings =
8818 undefined | {pid() | port(), [system_profile_option()]}
8819 system_profile_option() =
8820 exclusive | runnable_ports | runnable_procs | scheduler |
8821 timestamp | monotonic_timestamp | strict_monotonic_timestamp
8822
8823 Sets system profiler options. ProfilerPid is a local process
8824 identifier (pid) or port receiving profiling messages. The
8825 receiver is excluded from all profiling. The second argument is
8826 a list of profiling options:
8827
8828 exclusive:
8829 If a synchronous call to a port from a process is done, the
8830 calling process is considered not runnable during the call
8831 runtime to the port. The calling process is notified as
8832 inactive, and later active when the port callback returns.
8833
8834 monotonic_timestamp:
8835 Time stamps in profile messages use Erlang monotonic time.
8836 The time stamp (Ts) has the same format and value as pro‐
8837 duced by erlang:monotonic_time(nanosecond).
8838
8839 runnable_procs:
8840 If a process is put into or removed from the run queue, a
8841 message, {profile, Pid, State, Mfa, Ts}, is sent to Profil‐
8842 erPid. Running processes that are reinserted into the run
8843 queue after having been pre-empted do not trigger this mes‐
8844 sage.
8845
8846 runnable_ports:
8847 If a port is put into or removed from the run queue, a mes‐
8848 sage, {profile, Port, State, 0, Ts}, is sent to ProfilerPid.
8849
8850 scheduler:
8851 If a scheduler is put to sleep or awoken, a message, {pro‐
8852 file, scheduler, Id, State, NoScheds, Ts}, is sent to Pro‐
8853 filerPid.
8854
8855 strict_monotonic_timestamp:
8856 Time stamps in profile messages consist of Erlang monotonic
8857 time and a monotonically increasing integer. The time stamp
8858 (Ts) has the same format and value as produced by
8859 {erlang:monotonic_time(nanosecond), erlang:unique_inte‐
8860 ger([monotonic])}.
8861
8862 timestamp:
8863 Time stamps in profile messages include a time stamp (Ts)
8864 that has the same form as returned by erlang:now(). This is
8865 also the default if no time stamp flag is specified. If
8866 cpu_timestamp has been enabled through erlang:trace/3, this
8867 also effects the time stamp produced in profiling messages
8868 when flag timestamp is enabled.
8869
8870 Note:
8871 erlang:system_profile behavior can change in a future release.
8872
8873
8874 erlang:system_time() -> integer()
8875
8876 Returns current Erlang system time in native time unit.
8877
8878 Calling erlang:system_time() is equivalent to erlang:mono‐
8879 tonic_time() + erlang:time_offset().
8880
8881 Note:
8882 This time is not a monotonically increasing time in the general
8883 case. For more information, see the documentation of time warp
8884 modes in the User's Guide.
8885
8886
8887 erlang:system_time(Unit) -> integer()
8888
8889 Types:
8890
8891 Unit = time_unit()
8892
8893 Returns current Erlang system time converted into the Unit
8894 passed as argument.
8895
8896 Calling erlang:system_time(Unit) is equivalent to erlang:con‐
8897 vert_time_unit(erlang:system_time(), native, Unit).
8898
8899 Note:
8900 This time is not a monotonically increasing time in the general
8901 case. For more information, see the documentation of time warp
8902 modes in the User's Guide.
8903
8904
8905 term_to_binary(Term) -> ext_binary()
8906
8907 Types:
8908
8909 Term = term()
8910
8911 Returns a binary data object that is the result of encoding Term
8912 according to the Erlang external term format.
8913
8914 This can be used for various purposes, for example, writing a
8915 term to a file in an efficient way, or sending an Erlang term to
8916 some type of communications channel not supported by distributed
8917 Erlang.
8918
8919 > Bin = term_to_binary(hello).
8920 <<131,100,0,5,104,101,108,108,111>>
8921 > hello = binary_to_term(Bin).
8922 hello
8923
8924
8925 See also binary_to_term/1.
8926
8927 Note:
8928 There is no guarantee that this function will return the same
8929 encoded representation for the same term.
8930
8931
8932 term_to_binary(Term, Options) -> ext_binary()
8933
8934 Types:
8935
8936 Term = term()
8937 Options =
8938 [compressed |
8939 {compressed, Level :: 0..9} |
8940 {minor_version, Version :: 0..2}]
8941
8942 Returns a binary data object that is the result of encoding Term
8943 according to the Erlang external term format.
8944
8945 If option compressed is provided, the external term format is
8946 compressed. The compressed format is automatically recognized by
8947 binary_to_term/1 as from Erlang/OTP R7B.
8948
8949 A compression level can be specified by giving option {com‐
8950 pressed, Level}. Level is an integer with range 0..9, where:
8951
8952 * 0 - No compression is done (it is the same as giving no com‐
8953 pressed option).
8954
8955 * 1 - Takes least time but may not compress as well as the
8956 higher levels.
8957
8958 * 6 - Default level when option compressed is provided.
8959
8960 * 9 - Takes most time and tries to produce a smaller result.
8961 Notice "tries" in the preceding sentence; depending on the
8962 input term, level 9 compression either does or does not pro‐
8963 duce a smaller result than level 1 compression.
8964
8965 Option {minor_version, Version} can be used to control some
8966 encoding details. This option was introduced in Erlang/OTP
8967 R11B-4. The valid values for Version are:
8968
8969 0:
8970 Floats are encoded using a textual representation. This
8971 option is useful to ensure that releases before Erlang/OTP
8972 R11B-4 can decode resulting binary.
8973
8974 This version encode atoms that can be represented by a
8975 latin1 string using latin1 encoding while only atoms that
8976 cannot be represented by latin1 are encoded using utf8.
8977
8978 1:
8979 This is as of Erlang/OTP 17.0 the default. It forces any
8980 floats in the term to be encoded in a more space-efficient
8981 and exact way (namely in the 64-bit IEEE format, rather than
8982 converted to a textual representation). As from Erlang/OTP
8983 R11B-4, binary_to_term/1 can decode this representation.
8984
8985 This version encode atoms that can be represented by a
8986 latin1 string using latin1 encoding while only atoms that
8987 cannot be represented by latin1 are encoded using utf8.
8988
8989 2:
8990 Drops usage of the latin1 atom encoding and unconditionally
8991 use utf8 encoding for all atoms. This will be changed to the
8992 default in a future major release of Erlang/OTP. Erlang/OTP
8993 systems as of R16B can decode this representation.
8994
8995 See also binary_to_term/1.
8996
8997 throw(Any) -> no_return()
8998
8999 Types:
9000
9001 Any = term()
9002
9003 A non-local return from a function. If evaluated within a catch,
9004 catch returns value Any. Example:
9005
9006 > catch throw({hello, there}).
9007 {hello,there}
9008
9009 Failure: nocatch if not evaluated within a catch.
9010
9011 time() -> Time
9012
9013 Types:
9014
9015 Time = calendar:time()
9016
9017 Returns the current time as {Hour, Minute, Second}.
9018
9019 The time zone and Daylight Saving Time correction depend on the
9020 underlying OS. Example:
9021
9022 > time().
9023 {9,42,44}
9024
9025 erlang:time_offset() -> integer()
9026
9027 Returns the current time offset between Erlang monotonic time
9028 and Erlang system time in native time unit. Current time offset
9029 added to an Erlang monotonic time gives corresponding Erlang
9030 system time.
9031
9032 The time offset may or may not change during operation depending
9033 on the time warp mode used.
9034
9035 Note:
9036 A change in time offset can be observed at slightly different
9037 points in time by different processes.
9038
9039 If the runtime system is in multi-time warp mode, the time off‐
9040 set is changed when the runtime system detects that the OS sys‐
9041 tem time has changed. The runtime system will, however, not
9042 detect this immediately when it occurs. A task checking the time
9043 offset is scheduled to execute at least once a minute; so, under
9044 normal operation this is to be detected within a minute, but
9045 during heavy load it can take longer time.
9046
9047
9048 erlang:time_offset(Unit) -> integer()
9049
9050 Types:
9051
9052 Unit = time_unit()
9053
9054 Returns the current time offset between Erlang monotonic time
9055 and Erlang system time converted into the Unit passed as argu‐
9056 ment.
9057
9058 Same as calling erlang:convert_time_unit(erlang:time_offset(),
9059 native, Unit) however optimized for commonly used Units.
9060
9061 erlang:timestamp() -> Timestamp
9062
9063 Types:
9064
9065 Timestamp = timestamp()
9066 timestamp() =
9067 {MegaSecs :: integer() >= 0,
9068 Secs :: integer() >= 0,
9069 MicroSecs :: integer() >= 0}
9070
9071 Returns current Erlang system time on the format {MegaSecs,
9072 Secs, MicroSecs}. This format is the same as os:timestamp/0 and
9073 the deprecated erlang:now/0 use. The reason for the existence of
9074 erlang:timestamp() is purely to simplify use for existing code
9075 that assumes this time stamp format. Current Erlang system time
9076 can more efficiently be retrieved in the time unit of your
9077 choice using erlang:system_time/1.
9078
9079 The erlang:timestamp() BIF is equivalent to:
9080
9081 timestamp() ->
9082 ErlangSystemTime = erlang:system_time(microsecond),
9083 MegaSecs = ErlangSystemTime div 1000000000000,
9084 Secs = ErlangSystemTime div 1000000 - MegaSecs*1000000,
9085 MicroSecs = ErlangSystemTime rem 1000000,
9086 {MegaSecs, Secs, MicroSecs}.
9087
9088 It, however, uses a native implementation that does not build
9089 garbage on the heap and with slightly better performance.
9090
9091 Note:
9092 This time is not a monotonically increasing time in the general
9093 case. For more information, see the documentation of time warp
9094 modes in the User's Guide.
9095
9096
9097 tl(List) -> term()
9098
9099 Types:
9100
9101 List = [term(), ...]
9102
9103 Returns the tail of List, that is, the list minus the first ele‐
9104 ment, for example:
9105
9106 > tl([geesties, guilies, beasties]).
9107 [guilies, beasties]
9108
9109 Allowed in guard tests.
9110
9111 Failure: badarg if List is the empty list [].
9112
9113 erlang:trace(PidPortSpec, How, FlagList) -> integer()
9114
9115 Types:
9116
9117 PidPortSpec =
9118 pid() |
9119 port() |
9120 all | processes | ports | existing | existing_processes |
9121 existing_ports | new | new_processes | new_ports
9122 How = boolean()
9123 FlagList = [trace_flag()]
9124 trace_flag() =
9125 all | send | 'receive' | procs | ports | call | arity |
9126 return_to | silent | running | exiting | running_procs |
9127 running_ports | garbage_collection | timestamp |
9128 cpu_timestamp | monotonic_timestamp |
9129 strict_monotonic_timestamp | set_on_spawn |
9130 set_on_first_spawn | set_on_link | set_on_first_link |
9131 {tracer, pid() | port()} |
9132 {tracer, module(), term()}
9133
9134 Turns on (if How == true) or off (if How == false) the trace
9135 flags in FlagList for the process or processes represented by
9136 PidPortSpec.
9137
9138 PidPortSpec is either a process identifier (pid) for a local
9139 process, a port identifier, or one of the following atoms:
9140
9141 all:
9142 All currently existing processes and ports and all that will
9143 be created in the future.
9144
9145 processes:
9146 All currently existing processes and all that will be cre‐
9147 ated in the future.
9148
9149 ports:
9150 All currently existing ports and all that will be created in
9151 the future.
9152
9153 existing:
9154 All currently existing processes and ports.
9155
9156 existing_processes:
9157 All currently existing processes.
9158
9159 existing_ports:
9160 All currently existing ports.
9161
9162 new:
9163 All processes and ports that will be created in the future.
9164
9165 new_processes:
9166 All processes that will be created in the future.
9167
9168 new_ports:
9169 All ports that will be created in the future.
9170
9171 FlagList can contain any number of the following flags (the
9172 "message tags" refers to the list of trace messages):
9173
9174 all:
9175 Sets all trace flags except tracer and cpu_timestamp, which
9176 are in their nature different than the others.
9177
9178 send:
9179 Traces sending of messages.
9180
9181 Message tags: send and send_to_non_existing_process.
9182
9183 'receive':
9184 Traces receiving of messages.
9185
9186 Message tags: 'receive'.
9187
9188 call:
9189 Traces certain function calls. Specify which function calls
9190 to trace by calling erlang:trace_pattern/3.
9191
9192 Message tags: call and return_from.
9193
9194 silent:
9195 Used with the call trace flag. The call, return_from, and
9196 return_to trace messages are inhibited if this flag is set,
9197 but they are executed as normal if there are match specifi‐
9198 cations.
9199
9200 Silent mode is inhibited by executing erlang:trace(_, false,
9201 [silent|_]), or by a match specification executing the func‐
9202 tion {silent, false}.
9203
9204 The silent trace flag facilitates setting up a trace on many
9205 or even all processes in the system. The trace can then be
9206 activated and deactivated using the match specification
9207 function {silent,Bool}, giving a high degree of control of
9208 which functions with which arguments that trigger the trace.
9209
9210 Message tags: call, return_from, and return_to. Or rather,
9211 the absence of.
9212
9213 return_to:
9214 Used with the call trace flag. Traces the return from a
9215 traced function back to its caller. Only works for functions
9216 traced with option local to erlang:trace_pattern/3.
9217
9218 The semantics is that a trace message is sent when a call
9219 traced function returns, that is, when a chain of tail
9220 recursive calls ends. Only one trace message is sent per
9221 chain of tail recursive calls, so the properties of tail
9222 recursiveness for function calls are kept while tracing with
9223 this flag. Using call and return_to trace together makes it
9224 possible to know exactly in which function a process exe‐
9225 cutes at any time.
9226
9227 To get trace messages containing return values from func‐
9228 tions, use the {return_trace} match specification action
9229 instead.
9230
9231 Message tags: return_to.
9232
9233 procs:
9234 Traces process-related events.
9235
9236 Message tags: spawn, spawned, exit, register, unregister,
9237 link, unlink, getting_linked, and getting_unlinked.
9238
9239 ports:
9240 Traces port-related events.
9241
9242 Message tags: open, closed, register, unregister, get‐
9243 ting_linked, and getting_unlinked.
9244
9245 running:
9246 Traces scheduling of processes.
9247
9248 Message tags: in and out.
9249
9250 exiting:
9251 Traces scheduling of exiting processes.
9252
9253 Message tags: in_exiting, out_exiting, and out_exited.
9254
9255 running_procs:
9256 Traces scheduling of processes just like running. However,
9257 this option also includes schedule events when the process
9258 executes within the context of a port without being sched‐
9259 uled out itself.
9260
9261 Message tags: in and out.
9262
9263 running_ports:
9264 Traces scheduling of ports.
9265
9266 Message tags: in and out.
9267
9268 garbage_collection:
9269 Traces garbage collections of processes.
9270
9271 Message tags: gc_minor_start, gc_max_heap_size, and
9272 gc_minor_end.
9273
9274 timestamp:
9275 Includes a time stamp in all trace messages. The time stamp
9276 (Ts) has the same form as returned by erlang:now().
9277
9278 cpu_timestamp:
9279 A global trace flag for the Erlang node that makes all trace
9280 time stamps using flag timestamp to be in CPU time, not wall
9281 clock time. That is, cpu_timestamp is not be used if mono‐
9282 tonic_timestamp or strict_monotonic_timestamp is enabled.
9283 Only allowed with PidPortSpec==all. If the host machine OS
9284 does not support high-resolution CPU time measurements,
9285 trace/3 exits with badarg. Notice that most OS do not syn‐
9286 chronize this value across cores, so be prepared that time
9287 can seem to go backwards when using this option.
9288
9289 monotonic_timestamp:
9290 Includes an Erlang monotonic time time stamp in all trace
9291 messages. The time stamp (Ts) has the same format and value
9292 as produced by erlang:monotonic_time(nanosecond). This flag
9293 overrides flag cpu_timestamp.
9294
9295 strict_monotonic_timestamp:
9296 Includes an time stamp consisting of Erlang monotonic time
9297 and a monotonically increasing integer in all trace mes‐
9298 sages. The time stamp (Ts) has the same format and value as
9299 produced by { erlang:monotonic_time(nanosecond),
9300 erlang:unique_integer([monotonic])}. This flag overrides
9301 flag cpu_timestamp.
9302
9303 arity:
9304 Used with the call trace flag. {M, F, Arity} is specified
9305 instead of {M, F, Args} in call trace messages.
9306
9307 set_on_spawn:
9308 Makes any process created by a traced process inherit its
9309 trace flags, including flag set_on_spawn.
9310
9311 set_on_first_spawn:
9312 Makes the first process created by a traced process inherit
9313 its trace flags, excluding flag set_on_first_spawn.
9314
9315 set_on_link:
9316 Makes any process linked by a traced process inherit its
9317 trace flags, including flag set_on_link.
9318
9319 set_on_first_link:
9320 Makes the first process linked to by a traced process
9321 inherit its trace flags, excluding flag set_on_first_link.
9322
9323 {tracer, Tracer}:
9324 Specifies where to send the trace messages. Tracer must be
9325 the process identifier of a local process or the port iden‐
9326 tifier of a local port.
9327
9328 {tracer, TracerModule, TracerState}:
9329 Specifies that a tracer module is to be called instead of
9330 sending a trace message. The tracer module can then ignore
9331 or change the trace message. For more details on how to
9332 write a tracer module, see erl_tracer(3).
9333
9334 If no tracer is specified, the calling process receives all the
9335 trace messages.
9336
9337 The effect of combining set_on_first_link with set_on_link is
9338 the same as set_on_first_link alone. Likewise for set_on_spawn
9339 and set_on_first_spawn.
9340
9341 The tracing process receives the trace messages described in the
9342 following list. Pid is the process identifier of the traced
9343 process in which the traced event has occurred. The third tuple
9344 element is the message tag.
9345
9346 If flag timestamp, strict_monotonic_timestamp, or mono‐
9347 tonic_timestamp is specified, the first tuple element is
9348 trace_ts instead, and the time stamp is added as an extra ele‐
9349 ment last in the message tuple. If multiple time stamp flags are
9350 passed, timestamp has precedence over strict_monotonic_time‐
9351 stamp, which in turn has precedence over monotonic_timestamp.
9352 All time stamp flags are remembered, so if two are passed and
9353 the one with highest precedence later is disabled, the other one
9354 becomes active.
9355
9356 If a match specification (applicable only for call, send and
9357 'receive' tracing) contains a {message} action function with a
9358 non-boolean value, that value is added as an extra element to
9359 the message tuple either in the last position or before the
9360 timestamp (if it is present).
9361
9362 Trace messages:
9363
9364 {trace, PidPort, send, Msg, To}:
9365 When PidPort sends message Msg to process To.
9366
9367 {trace, PidPort, send_to_non_existing_process, Msg, To}:
9368 When PidPort sends message Msg to the non-existing process
9369 To.
9370
9371 {trace, PidPort, 'receive', Msg}:
9372 When PidPort receives message Msg. If Msg is set to time-
9373 out, a receive statement can have timed out, or the process
9374 received a message with the payload timeout.
9375
9376 {trace, Pid, call, {M, F, Args}}:
9377 When Pid calls a traced function. The return values of calls
9378 are never supplied, only the call and its arguments.
9379
9380 Trace flag arity can be used to change the contents of this
9381 message, so that Arity is specified instead of Args.
9382
9383 {trace, Pid, return_to, {M, F, Arity}}:
9384 When Pid returns to the specified function. This trace mes‐
9385 sage is sent if both the flags call and return_to are set,
9386 and the function is set to be traced on local function
9387 calls. The message is only sent when returning from a chain
9388 of tail recursive function calls, where at least one call
9389 generated a call trace message (that is, the functions match
9390 specification matched, and {message, false} was not an
9391 action).
9392
9393 {trace, Pid, return_from, {M, F, Arity}, ReturnValue}:
9394 When Pid returns from the specified function. This trace
9395 message is sent if flag call is set, and the function has a
9396 match specification with a return_trace or exception_trace
9397 action.
9398
9399 {trace, Pid, exception_from, {M, F, Arity}, {Class, Value}}:
9400 When Pid exits from the specified function because of an
9401 exception. This trace message is sent if flag call is set,
9402 and the function has a match specification with an excep‐
9403 tion_trace action.
9404
9405 {trace, Pid, spawn, Pid2, {M, F, Args}}:
9406 When Pid spawns a new process Pid2 with the specified func‐
9407 tion call as entry point.
9408
9409 Args is supposed to be the argument list, but can be any
9410 term if the spawn is erroneous.
9411
9412 {trace, Pid, spawned, Pid2, {M, F, Args}}:
9413 When Pid is spawned by process Pid2 with the specified func‐
9414 tion call as entry point.
9415
9416 Args is supposed to be the argument list, but can be any
9417 term if the spawn is erroneous.
9418
9419 {trace, Pid, exit, Reason}:
9420 When Pid exits with reason Reason.
9421
9422 {trace, PidPort, register, RegName}:
9423 When PidPort gets the name RegName registered.
9424
9425 {trace, PidPort, unregister, RegName}:
9426 When PidPort gets the name RegName unregistered. This is
9427 done automatically when a registered process or port exits.
9428
9429 {trace, Pid, link, Pid2}:
9430 When Pid links to a process Pid2.
9431
9432 {trace, Pid, unlink, Pid2}:
9433 When Pid removes the link from a process Pid2.
9434
9435 {trace, PidPort, getting_linked, Pid2}:
9436 When PidPort gets linked to a process Pid2.
9437
9438 {trace, PidPort, getting_unlinked, Pid2}:
9439 When PidPort gets unlinked from a process Pid2.
9440
9441 {trace, Pid, exit, Reason}:
9442 When Pid exits with reason Reason.
9443
9444 {trace, Port, open, Pid, Driver}:
9445 When Pid opens a new port Port with the running Driver.
9446
9447 Driver is the name of the driver as an atom.
9448
9449 {trace, Port, closed, Reason}:
9450 When Port closes with Reason.
9451
9452 {trace, Pid, in | in_exiting, {M, F, Arity} | 0}:
9453 When Pid is scheduled to run. The process runs in function
9454 {M, F, Arity}. On some rare occasions, the current function
9455 cannot be determined, then the last element is 0.
9456
9457 {trace, Pid, out | out_exiting | out_exited, {M, F, Arity} |
9458 0}:
9459 When Pid is scheduled out. The process was running in func‐
9460 tion {M, F, Arity}. On some rare occasions, the current
9461 function cannot be determined, then the last element is 0.
9462
9463 {trace, Port, in, Command | 0}:
9464 When Port is scheduled to run. Command is the first thing
9465 the port will execute, it can however run several commands
9466 before being scheduled out. On some rare occasions, the cur‐
9467 rent function cannot be determined, then the last element is
9468 0.
9469
9470 The possible commands are call, close, command, connect,
9471 control, flush, info, link, open, and unlink.
9472
9473 {trace, Port, out, Command | 0}:
9474 When Port is scheduled out. The last command run was Com‐
9475 mand. On some rare occasions, the current function cannot be
9476 determined, then the last element is 0. Command can contain
9477 the same commands as in
9478
9479 {trace, Pid, gc_minor_start, Info}:
9480
9481
9482 Sent when a young garbage collection is about to be started.
9483 Info is a list of two-element tuples, where the first ele‐
9484 ment is a key, and the second is the value. Do not depend on
9485 any order of the tuples. The following keys are defined:
9486
9487 heap_size:
9488 The size of the used part of the heap.
9489
9490 heap_block_size:
9491 The size of the memory block used for storing the heap and
9492 the stack.
9493
9494 old_heap_size:
9495 The size of the used part of the old heap.
9496
9497 old_heap_block_size:
9498 The size of the memory block used for storing the old
9499 heap.
9500
9501 stack_size:
9502 The size of the stack.
9503
9504 recent_size:
9505 The size of the data that survived the previous garbage
9506 collection.
9507
9508 mbuf_size:
9509 The combined size of message buffers associated with the
9510 process.
9511
9512 bin_vheap_size:
9513 The total size of unique off-heap binaries referenced from
9514 the process heap.
9515
9516 bin_vheap_block_size:
9517 The total size of binaries allowed in the virtual heap in
9518 the process before doing a garbage collection.
9519
9520 bin_old_vheap_size:
9521 The total size of unique off-heap binaries referenced from
9522 the process old heap.
9523
9524 bin_old_vheap_block_size:
9525 The total size of binaries allowed in the virtual old heap
9526 in the process before doing a garbage collection.
9527
9528 All sizes are in words.
9529
9530 {trace, Pid, gc_max_heap_size, Info}:
9531 Sent when the max_heap_size is reached during garbage col‐
9532 lection. Info contains the same kind of list as in message
9533 gc_start, but the sizes reflect the sizes that triggered
9534 max_heap_size to be reached.
9535
9536 {trace, Pid, gc_minor_end, Info}:
9537 Sent when young garbage collection is finished. Info con‐
9538 tains the same kind of list as in message gc_minor_start,
9539 but the sizes reflect the new sizes after garbage collec‐
9540 tion.
9541
9542 {trace, Pid, gc_major_start, Info}:
9543 Sent when fullsweep garbage collection is about to be
9544 started. Info contains the same kind of list as in message
9545 gc_minor_start.
9546
9547 {trace, Pid, gc_major_end, Info}:
9548 Sent when fullsweep garbage collection is finished. Info
9549 contains the same kind of list as in message gc_minor_start,
9550 but the sizes reflect the new sizes after a fullsweep
9551 garbage collection.
9552
9553 If the tracing process/port dies or the tracer module returns
9554 remove, the flags are silently removed.
9555
9556 Each process can only be traced by one tracer. Therefore,
9557 attempts to trace an already traced process fail.
9558
9559 Returns a number indicating the number of processes that matched
9560 PidPortSpec. If PidPortSpec is a process identifier, the return
9561 value is 1. If PidPortSpec is all or existing, the return value
9562 is the number of processes running. If PidPortSpec is new, the
9563 return value is 0.
9564
9565 Failure: badarg if the specified arguments are not supported.
9566 For example, cpu_timestamp is not supported on all platforms.
9567
9568 erlang:trace_delivered(Tracee) -> Ref
9569
9570 Types:
9571
9572 Tracee = pid() | all
9573 Ref = reference()
9574
9575 The delivery of trace messages (generated by erlang:trace/3,
9576 seq_trace(3), or erlang:system_profile/2) is dislocated on the
9577 time-line compared to other events in the system. If you know
9578 that Tracee has passed some specific point in its execution, and
9579 you want to know when at least all trace messages corresponding
9580 to events up to this point have reached the tracer, use
9581 erlang:trace_delivered(Tracee).
9582
9583 When it is guaranteed that all trace messages are delivered to
9584 the tracer up to the point that Tracee reached at the time of
9585 the call to erlang:trace_delivered(Tracee), then a {trace_deliv‐
9586 ered, Tracee, Ref} message is sent to the caller of
9587 erlang:trace_delivered(Tracee) .
9588
9589 Notice that message trace_delivered does not imply that trace
9590 messages have been delivered. Instead it implies that all trace
9591 messages that are to be delivered have been delivered. It is not
9592 an error if Tracee is not, and has not been traced by someone,
9593 but if this is the case, no trace messages have been delivered
9594 when the trace_delivered message arrives.
9595
9596 Notice that Tracee must refer to a process currently or previ‐
9597 ously existing on the same node as the caller of
9598 erlang:trace_delivered(Tracee) resides on. The special Tracee
9599 atom all denotes all processes that currently are traced in the
9600 node.
9601
9602 When used together with a Tracer Module, any message sent in
9603 the trace callback is guaranteed to have reached its recipient
9604 before the trace_delivered message is sent.
9605
9606 Example: Process A is Tracee, port B is tracer, and process C is
9607 the port owner of B. C wants to close B when A exits. To ensure
9608 that the trace is not truncated, C can call erlang:trace_deliv‐
9609 ered(A) when A exits, and wait for message {trace_delivered, A,
9610 Ref} before closing B.
9611
9612 Failure: badarg if Tracee does not refer to a process (dead or
9613 alive) on the same node as the caller of erlang:trace_deliv‐
9614 ered(Tracee) resides on.
9615
9616 erlang:trace_info(PidPortFuncEvent, Item) -> Res
9617
9618 Types:
9619
9620 PidPortFuncEvent =
9621 pid() |
9622 port() |
9623 new | new_processes | new_ports |
9624 {Module, Function, Arity} |
9625 on_load | send | 'receive'
9626 Module = module()
9627 Function = atom()
9628 Arity = arity()
9629 Item =
9630 flags | tracer | traced | match_spec | meta |
9631 meta_match_spec | call_count | call_time | all
9632 Res = trace_info_return()
9633 trace_info_return() =
9634 undefined |
9635 {flags, [trace_info_flag()]} |
9636 {tracer, pid() | port() | []} |
9637 {tracer, module(), term()} |
9638 trace_info_item_result() |
9639 {all, [trace_info_item_result()] | false | undefined}
9640 trace_info_item_result() =
9641 {traced, global | local | false | undefined} |
9642 {match_spec, trace_match_spec() | false | undefined} |
9643 {meta, pid() | port() | false | undefined | []} |
9644 {meta, module(), term()} |
9645 {meta_match_spec, trace_match_spec() | false | undefined} |
9646 {call_count, integer() >= 0 | boolean() | undefined} |
9647 {call_time,
9648 [{pid(),
9649 integer() >= 0,
9650 integer() >= 0,
9651 integer() >= 0}] |
9652 boolean() |
9653 undefined}
9654 trace_info_flag() =
9655 send | 'receive' | set_on_spawn | call | return_to | procs |
9656 set_on_first_spawn | set_on_link | running |
9657 garbage_collection | timestamp | monotonic_timestamp |
9658 strict_monotonic_timestamp | arity
9659 trace_match_spec() =
9660 [{[term()] | '_' | match_variable(), [term()], [term()]}]
9661 match_variable() = atom()
9662 Approximation of '$1' | '$2' | '$3' | ...
9663
9664 Returns trace information about a port, process, function, or
9665 event.
9666
9667 To get information about a port or process, PidPortFuncEvent is
9668 to be a process identifier (pid), port identifier, or one of the
9669 atoms new, new_processes, or new_ports. The atom new or new_pro‐
9670 cesses means that the default trace state for processes to be
9671 created is returned. The atom new_ports means that the default
9672 trace state for ports to be created is returned.
9673
9674 Valid Items for ports and processes:
9675
9676 flags:
9677 Returns a list of atoms indicating what kind of traces is
9678 enabled for the process. The list is empty if no traces are
9679 enabled, and one or more of the followings atoms if traces
9680 are enabled: send, 'receive', set_on_spawn, call, return_to,
9681 procs, ports, set_on_first_spawn, set_on_link, running, run‐
9682 ning_procs, running_ports, silent, exiting, monotonic_time‐
9683 stamp, strict_monotonic_timestamp, garbage_collection, time‐
9684 stamp, and arity. The order is arbitrary.
9685
9686 tracer:
9687 Returns the identifier for process, port, or a tuple con‐
9688 taining the tracer module and tracer state tracing this
9689 process. If this process is not traced, the return value is
9690 [].
9691
9692 To get information about a function, PidPortFuncEvent is to be
9693 the three-element tuple {Module, Function, Arity} or the atom
9694 on_load. No wildcards are allowed. Returns undefined if the
9695 function does not exist, or false if the function is not traced.
9696 If PidPortFuncEvent is on_load, the information returned refers
9697 to the default value for code that will be loaded.
9698
9699 Valid Items for functions:
9700
9701 traced:
9702 Returns global if this function is traced on global function
9703 calls, local if this function is traced on local function
9704 calls (that is, local and global function calls), and false
9705 if local or global function calls are not traced.
9706
9707 match_spec:
9708 Returns the match specification for this function, if it has
9709 one. If the function is locally or globally traced but has
9710 no match specification defined, the returned value is [].
9711
9712 meta:
9713 Returns the meta-trace tracer process, port, or trace module
9714 for this function, if it has one. If the function is not
9715 meta-traced, the returned value is false. If the function is
9716 meta-traced but has once detected that the tracer process is
9717 invalid, the returned value is [].
9718
9719 meta_match_spec:
9720 Returns the meta-trace match specification for this func‐
9721 tion, if it has one. If the function is meta-traced but has
9722 no match specification defined, the returned value is [].
9723
9724 call_count:
9725 Returns the call count value for this function or true for
9726 the pseudo function on_load if call count tracing is active.
9727 Otherwise false is returned.
9728
9729 See also erlang:trace_pattern/3.
9730
9731 call_time:
9732 Returns the call time values for this function or true for
9733 the pseudo function on_load if call time tracing is active.
9734 Otherwise false is returned. The call time values returned,
9735 [{Pid, Count, S, Us}], is a list of each process that exe‐
9736 cuted the function and its specific counters.
9737
9738 See also erlang:trace_pattern/3.
9739
9740 all:
9741 Returns a list containing the {Item, Value} tuples for all
9742 other items, or returns false if no tracing is active for
9743 this function.
9744
9745 To get information about an event, PidPortFuncEvent is to be one
9746 of the atoms send or 'receive'.
9747
9748 One valid Item for events exists:
9749
9750 match_spec:
9751 Returns the match specification for this event, if it has
9752 one, or true if no match specification has been set.
9753
9754 The return value is {Item, Value}, where Value is the requested
9755 information as described earlier. If a pid for a dead process
9756 was specified, or the name of a non-existing function, Value is
9757 undefined.
9758
9759 erlang:trace_pattern(MFA, MatchSpec) -> integer() >= 0
9760
9761 Types:
9762
9763 MFA = trace_pattern_mfa() | send | 'receive'
9764 MatchSpec =
9765 (MatchSpecList :: trace_match_spec()) |
9766 boolean() |
9767 restart | pause
9768 trace_pattern_mfa() = {atom(), atom(), arity() | '_'} | on_load
9769 trace_match_spec() =
9770 [{[term()] | '_' | match_variable(), [term()], [term()]}]
9771 match_variable() = atom()
9772 Approximation of '$1' | '$2' | '$3' | ...
9773
9774 The same as erlang:trace_pattern(Event, MatchSpec, []), retained
9775 for backward compatibility.
9776
9777 erlang:trace_pattern(MFA :: send, MatchSpec, FlagList :: []) ->
9778 integer() >= 0
9779
9780 Types:
9781
9782 MatchSpec = (MatchSpecList :: trace_match_spec()) | boolean()
9783 trace_match_spec() =
9784 [{[term()] | '_' | match_variable(), [term()], [term()]}]
9785 match_variable() = atom()
9786 Approximation of '$1' | '$2' | '$3' | ...
9787
9788 Sets trace pattern for message sending. Must be combined with
9789 erlang:trace/3 to set the send trace flag for one or more pro‐
9790 cesses. By default all messages sent from send traced processes
9791 are traced. To limit traced send events based on the message
9792 content, the sender and/or the receiver, use erlang:trace_pat‐
9793 tern/3.
9794
9795 Argument MatchSpec can take the following forms:
9796
9797 MatchSpecList:
9798 A list of match specifications. The matching is done on the
9799 list [Receiver, Msg]. Receiver is the process or port iden‐
9800 tity of the receiver and Msg is the message term. The pid of
9801 the sending process can be accessed with the guard function
9802 self/0. An empty list is the same as true. For more informa‐
9803 tion, see section Match Specifications in Erlang in the
9804 User's Guide.
9805
9806 true:
9807 Enables tracing for all sent messages (from send traced pro‐
9808 cesses). Any match specification is removed. This is the
9809 default.
9810
9811 false:
9812 Disables tracing for all sent messages. Any match specifica‐
9813 tion is removed.
9814
9815 Argument FlagList must be [] for send tracing.
9816
9817 The return value is always 1.
9818
9819 Examples:
9820
9821 Only trace messages to a specific process Pid:
9822
9823 > erlang:trace_pattern(send, [{[Pid, '_'],[],[]}], []).
9824 1
9825
9826 Only trace messages matching {reply, _}:
9827
9828 > erlang:trace_pattern(send, [{['_', {reply,'_'}],[],[]}], []).
9829 1
9830
9831 Only trace messages sent to the sender itself:
9832
9833 > erlang:trace_pattern(send, [{['$1', '_'],[{'=:=','$1',{self}}],[]}], []).
9834 1
9835
9836 Only trace messages sent to other nodes:
9837
9838 > erlang:trace_pattern(send, [{['$1', '_'],[{'=/=',{node,'$1'},{node}}],[]}], []).
9839 1
9840
9841 Note:
9842 A match specification for send trace can use all guard and body
9843 functions except caller.
9844
9845
9846 erlang:trace_pattern(MFA :: 'receive', MatchSpec, FlagList :: []) ->
9847 integer() >= 0
9848
9849 Types:
9850
9851 MatchSpec = (MatchSpecList :: trace_match_spec()) | boolean()
9852 trace_match_spec() =
9853 [{[term()] | '_' | match_variable(), [term()], [term()]}]
9854 match_variable() = atom()
9855 Approximation of '$1' | '$2' | '$3' | ...
9856
9857 Sets trace pattern for message receiving. Must be combined with
9858 erlang:trace/3 to set the 'receive' trace flag for one or more
9859 processes. By default all messages received by 'receive' traced
9860 processes are traced. To limit traced receive events based on
9861 the message content, the sender and/or the receiver, use
9862 erlang:trace_pattern/3.
9863
9864 Argument MatchSpec can take the following forms:
9865
9866 MatchSpecList:
9867 A list of match specifications. The matching is done on the
9868 list [Node, Sender, Msg]. Node is the node name of the
9869 sender. Sender is the process or port identity of the
9870 sender, or the atom undefined if the sender is not known
9871 (which can be the case for remote senders). Msg is the mes‐
9872 sage term. The pid of the receiving process can be accessed
9873 with the guard function self/0. An empty list is the same as
9874 true. For more information, see section Match Specifica‐
9875 tions in Erlang in the User's Guide.
9876
9877 true:
9878 Enables tracing for all received messages (to 'receive'
9879 traced processes). Any match specification is removed. This
9880 is the default.
9881
9882 false:
9883 Disables tracing for all received messages. Any match speci‐
9884 fication is removed.
9885
9886 Argument FlagList must be [] for receive tracing.
9887
9888 The return value is always 1.
9889
9890 Examples:
9891
9892 Only trace messages from a specific process Pid:
9893
9894 > erlang:trace_pattern('receive', [{['_',Pid, '_'],[],[]}], []).
9895 1
9896
9897 Only trace messages matching {reply, _}:
9898
9899 > erlang:trace_pattern('receive', [{['_','_', {reply,'_'}],[],[]}], []).
9900 1
9901
9902 Only trace messages from other nodes:
9903
9904 > erlang:trace_pattern('receive', [{['$1', '_', '_'],[{'=/=','$1',{node}}],[]}], []).
9905 1
9906
9907 Note:
9908 A match specification for 'receive' trace can use all guard and
9909 body functions except caller, is_seq_trace, get_seq_token,
9910 set_seq_token, enable_trace, disable_trace, trace, silent, and
9911 process_dump.
9912
9913
9914 erlang:trace_pattern(MFA, MatchSpec, FlagList) ->
9915 integer() >= 0
9916
9917 Types:
9918
9919 MFA = trace_pattern_mfa()
9920 MatchSpec =
9921 (MatchSpecList :: trace_match_spec()) |
9922 boolean() |
9923 restart | pause
9924 FlagList = [trace_pattern_flag()]
9925 trace_pattern_mfa() = {atom(), atom(), arity() | '_'} | on_load
9926 trace_match_spec() =
9927 [{[term()] | '_' | match_variable(), [term()], [term()]}]
9928 trace_pattern_flag() =
9929 global | local | meta |
9930 {meta, Pid :: pid()} |
9931 {meta, TracerModule :: module(), TracerState :: term()} |
9932 call_count | call_time
9933 match_variable() = atom()
9934 Approximation of '$1' | '$2' | '$3' | ...
9935
9936 Enables or disables call tracing for one or more functions. Must
9937 be combined with erlang:trace/3 to set the call trace flag for
9938 one or more processes.
9939
9940 Conceptually, call tracing works as follows. Inside the Erlang
9941 virtual machine, a set of processes and a set of functions are
9942 to be traced. If a traced process calls a traced function, the
9943 trace action is taken. Otherwise, nothing happens.
9944
9945 To add or remove one or more processes to the set of traced pro‐
9946 cesses, use erlang:trace/3.
9947
9948 To add or remove functions to the set of traced functions, use
9949 erlang:trace_pattern/3.
9950
9951 The BIF erlang:trace_pattern/3 can also add match specifications
9952 to a function. A match specification comprises a pattern that
9953 the function arguments must match, a guard expression that must
9954 evaluate to true, and an action to be performed. The default
9955 action is to send a trace message. If the pattern does not match
9956 or the guard fails, the action is not executed.
9957
9958 Argument MFA is to be a tuple, such as {Module, Function,
9959 Arity}, or the atom on_load (described below). It can be the
9960 module, function, and arity for a function (or a BIF in any mod‐
9961 ule). The atom '_' can be used as a wildcard in any of the fol‐
9962 lowing ways:
9963
9964 {Module,Function,'_'}:
9965 All functions of any arity named Function in module Module.
9966
9967 {Module,'_','_'}:
9968 All functions in module Module.
9969
9970 {'_','_','_'}:
9971 All functions in all loaded modules.
9972
9973 Other combinations, such as {Module,'_',Arity}, are not allowed.
9974 Local functions match wildcards only if option local is in
9975 FlagList.
9976
9977 If argument MFA is the atom on_load, the match specification and
9978 flag list are used on all modules that are newly loaded.
9979
9980 Argument MatchSpec can take the following forms:
9981
9982 false:
9983 Disables tracing for the matching functions. Any match spec‐
9984 ification is removed.
9985
9986 true:
9987 Enables tracing for the matching functions. Any match speci‐
9988 fication is removed.
9989
9990 MatchSpecList:
9991 A list of match specifications. An empty list is equivalent
9992 to true. For a description of match specifications, see sec‐
9993 tion Match Specifications in Erlang in the User's Guide.
9994
9995 restart:
9996 For the FlagList options call_count and call_time: restarts
9997 the existing counters. The behavior is undefined for other
9998 FlagList options.
9999
10000 pause:
10001 For the FlagList options call_count and call_time: pauses
10002 the existing counters. The behavior is undefined for other
10003 FlagList options.
10004
10005 Parameter FlagList is a list of options. The following are the
10006 valid options:
10007
10008 global:
10009 Turns on or off call tracing for global function calls (that
10010 is, calls specifying the module explicitly). Only exported
10011 functions match and only global calls generate trace mes‐
10012 sages. This is the default.
10013
10014 local:
10015 Turns on or off call tracing for all types of function
10016 calls. Trace messages are sent whenever any of the specified
10017 functions are called, regardless of how they are called. If
10018 flag return_to is set for the process, a return_to message
10019 is also sent when this function returns to its caller.
10020
10021 meta | {meta, Pid} | {meta, TracerModule, TracerState}:
10022 Turns on or off meta-tracing for all types of function
10023 calls. Trace messages are sent to the tracer whenever any of
10024 the specified functions are called. If no tracer is speci‐
10025 fied, self() is used as a default tracer process.
10026
10027 Meta-tracing traces all processes and does not care about
10028 the process trace flags set by erlang:trace/3, the trace
10029 flags are instead fixed to [call, timestamp].
10030
10031 The match specification function {return_trace} works with
10032 meta-trace and sends its trace message to the same tracer.
10033
10034 call_count:
10035 Starts (MatchSpec == true) or stops (MatchSpec == false)
10036 call count tracing for all types of function calls. For
10037 every function, a counter is incremented when the function
10038 is called, in any process. No process trace flags need to be
10039 activated.
10040
10041 If call count tracing is started while already running, the
10042 count is restarted from zero. To pause running counters, use
10043 MatchSpec == pause. Paused and running counters can be
10044 restarted from zero with MatchSpec == restart.
10045
10046 To read the counter value, use erlang:trace_info/2.
10047
10048 call_time:
10049 Starts (MatchSpec == true) or stops (MatchSpec == false)
10050 call time tracing for all types of function calls. For every
10051 function, a counter is incremented when the function is
10052 called. Time spent in the function is accumulated in two
10053 other counters, seconds and microseconds. The counters are
10054 stored for each call traced process.
10055
10056 If call time tracing is started while already running, the
10057 count and time restart from zero. To pause running counters,
10058 use MatchSpec == pause. Paused and running counters can be
10059 restarted from zero with MatchSpec == restart.
10060
10061 To read the counter value, use erlang:trace_info/2.
10062
10063 The options global and local are mutually exclusive, and global
10064 is the default (if no options are specified). The options
10065 call_count and meta perform a kind of local tracing, and cannot
10066 be combined with global. A function can be globally or locally
10067 traced. If global tracing is specified for a set of functions,
10068 then local, meta, call time, and call count tracing for the
10069 matching set of local functions is disabled, and conversely.
10070
10071 When disabling trace, the option must match the type of trace
10072 set on the function. That is, local tracing must be disabled
10073 with option local and global tracing with option global (or no
10074 option), and so on.
10075
10076 Part of a match specification list cannot be changed directly.
10077 If a function has a match specification, it can be replaced with
10078 a new one. To change an existing match specification, use the
10079 BIF erlang:trace_info/2 to retrieve the existing match specifi‐
10080 cation.
10081
10082 Returns the number of functions matching argument MFA. This is
10083 zero if none matched.
10084
10085 trunc(Number) -> integer()
10086
10087 Types:
10088
10089 Number = number()
10090
10091 Returns an integer by truncating Number, for example:
10092
10093 > trunc(5.5).
10094 5
10095
10096 Allowed in guard tests.
10097
10098 tuple_size(Tuple) -> integer() >= 0
10099
10100 Types:
10101
10102 Tuple = tuple()
10103
10104 Returns an integer that is the number of elements in Tuple, for
10105 example:
10106
10107 > tuple_size({morni, mulle, bwange}).
10108 3
10109
10110 Allowed in guard tests.
10111
10112 tuple_to_list(Tuple) -> [term()]
10113
10114 Types:
10115
10116 Tuple = tuple()
10117
10118 Returns a list corresponding to Tuple. Tuple can contain any
10119 Erlang terms. Example:
10120
10121 > tuple_to_list({share, {'Ericsson_B', 163}}).
10122 [share,{'Ericsson_B',163}]
10123
10124 erlang:unique_integer() -> integer()
10125
10126 Generates and returns an integer unique on current runtime sys‐
10127 tem instance. The same as calling erlang:unique_integer([]).
10128
10129 erlang:unique_integer(ModifierList) -> integer()
10130
10131 Types:
10132
10133 ModifierList = [Modifier]
10134 Modifier = positive | monotonic
10135
10136 Generates and returns an integer unique on current runtime sys‐
10137 tem instance. The integer is unique in the sense that this BIF,
10138 using the same set of modifiers, does not return the same inte‐
10139 ger more than once on the current runtime system instance. Each
10140 integer value can of course be constructed by other means.
10141
10142 By default, when [] is passed as ModifierList, both negative and
10143 positive integers can be returned. This to use the range of
10144 integers that do not need heap memory allocation as much as pos‐
10145 sible. By default the returned integers are also only guaranteed
10146 to be unique, that is, any returned integer can be smaller or
10147 larger than previously returned integers.
10148
10149 Modifiers:
10150
10151 positive:
10152 Returns only positive integers.
10153
10154 Notice that by passing the positive modifier you will get
10155 heap allocated integers (bignums) quicker.
10156
10157 monotonic:
10158 Returns strictly monotonically increasing integers corre‐
10159 sponding to creation time. That is, the integer returned is
10160 always larger than previously returned integers on the cur‐
10161 rent runtime system instance.
10162
10163 These values can be used to determine order between events
10164 on the runtime system instance. That is, if both X =
10165 erlang:unique_integer([monotonic]) and Y =
10166 erlang:unique_integer([monotonic]) are executed by different
10167 processes (or the same process) on the same runtime system
10168 instance and X < Y, we know that X was created before Y.
10169
10170 Warning:
10171 Strictly monotonically increasing values are inherently quite
10172 expensive to generate and scales poorly. This is because the
10173 values need to be synchronized between CPU cores. That is, do
10174 not pass the monotonic modifier unless you really need
10175 strictly monotonically increasing values.
10176
10177
10178 All valid Modifiers can be combined. Repeated (valid) Modifiers
10179 in the ModifierList are ignored.
10180
10181 Note:
10182 The set of integers returned by erlang:unique_integer/1 using
10183 different sets of Modifiers will overlap. For example, by call‐
10184 ing unique_integer([monotonic]), and unique_integer([positive,
10185 monotonic]) repeatedly, you will eventually see some integers
10186 that are returned by both calls.
10187
10188
10189 Failures:
10190
10191 badarg:
10192 if ModifierList is not a proper list.
10193
10194 badarg:
10195 if Modifier is not a valid modifier.
10196
10197 erlang:universaltime() -> DateTime
10198
10199 Types:
10200
10201 DateTime = calendar:datetime()
10202
10203 Returns the current date and time according to Universal Time
10204 Coordinated (UTC) in the form {{Year, Month, Day}, {Hour,
10205 Minute, Second}} if supported by the underlying OS. Otherwise
10206 erlang:universaltime() is equivalent to erlang:localtime().
10207 Example:
10208
10209 > erlang:universaltime().
10210 {{1996,11,6},{14,18,43}}
10211
10212 erlang:universaltime_to_localtime(Universaltime) -> Localtime
10213
10214 Types:
10215
10216 Localtime = Universaltime = calendar:datetime()
10217
10218 Converts Universal Time Coordinated (UTC) date and time to local
10219 date and time in the form {{Year, Month, Day}, {Hour, Minute,
10220 Second}} if supported by the underlying OS. Otherwise no conver‐
10221 sion is done, and Universaltime is returned. Example:
10222
10223 > erlang:universaltime_to_localtime({{1996,11,6},{14,18,43}}).
10224 {{1996,11,7},{15,18,43}}
10225
10226 Failure: badarg if Universaltime denotes an invalid date and
10227 time.
10228
10229 unlink(Id) -> true
10230
10231 Types:
10232
10233 Id = pid() | port()
10234
10235 Removes the link, if there is one, between the calling process
10236 and the process or port referred to by Id.
10237
10238 Returns true and does not fail, even if there is no link to Id,
10239 or if Id does not exist.
10240
10241 Once unlink(Id) has returned, it is guaranteed that the link
10242 between the caller and the entity referred to by Id has no
10243 effect on the caller in the future (unless the link is setup
10244 again). If the caller is trapping exits, an {'EXIT', Id, _} mes‐
10245 sage from the link can have been placed in the caller's message
10246 queue before the call.
10247
10248 Notice that the {'EXIT', Id, _} message can be the result of the
10249 link, but can also be the result of Id calling exit/2. There‐
10250 fore, it can be appropriate to clean up the message queue when
10251 trapping exits after the call to unlink(Id), as follows:
10252
10253 unlink(Id),
10254 receive
10255 {'EXIT', Id, _} ->
10256 true
10257 after 0 ->
10258 true
10259 end
10260
10261 Note:
10262 Before Erlang/OTP R11B (ERTS 5.5) unlink/1 behaved completely
10263 asynchronously, that is, the link was active until the "unlink
10264 signal" reached the linked entity. This had an undesirable
10265 effect, as you could never know when you were guaranteed not to
10266 be effected by the link.
10267
10268 The current behavior can be viewed as two combined operations:
10269 asynchronously send an "unlink signal" to the linked entity and
10270 ignore any future results of the link.
10271
10272
10273 unregister(RegName) -> true
10274
10275 Types:
10276
10277 RegName = atom()
10278
10279 Removes the registered name RegName associated with a process
10280 identifier or a port identifier, for example:
10281
10282 > unregister(db).
10283 true
10284
10285 Users are advised not to unregister system processes.
10286
10287 Failure: badarg if RegName is not a registered name.
10288
10289 whereis(RegName) -> pid() | port() | undefined
10290
10291 Types:
10292
10293 RegName = atom()
10294
10295 Returns the process identifier or port identifier with the reg‐
10296 istered name RegName. Returns undefined if the name is not reg‐
10297 istered. Example:
10298
10299 > whereis(db).
10300 <0.43.0>
10301
10302 erlang:yield() -> true
10303
10304 Voluntarily lets other processes (if any) get a chance to exe‐
10305 cute. Using this function is similar to receive after 1 -> ok
10306 end, except that yield() is faster.
10307
10308 Warning:
10309 There is seldom or never any need to use this BIF as other pro‐
10310 cesses have a chance to run in another scheduler thread anyway.
10311 Using this BIF without a thorough grasp of how the scheduler
10312 works can cause performance degradation.
10313
10314
10315
10316
10317Ericsson AB erts 10.5.6 erlang(3)