-
Notifications
You must be signed in to change notification settings - Fork 2.9k
/
erlang.xml
7149 lines (7080 loc) · 325 KB
/
erlang.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<?xml version="1.0" encoding="latin1" ?>
<!DOCTYPE erlref SYSTEM "erlref.dtd">
<erlref>
<header>
<copyright>
<year>1996</year><year>2013</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
The contents of this file are subject to the Erlang Public License,
Version 1.1, (the "License"); you may not use this file except in
compliance with the License. You should have received a copy of the
Erlang Public License along with this software. If not, it can be
retrieved online at http://www.erlang.org/.
Software distributed under the License is distributed on an "AS IS"
basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
the License for the specific language governing rights and limitations
under the License.
</legalnotice>
<title>erlang</title>
<prepared></prepared>
<docno></docno>
<date></date>
<rev></rev>
<file>erlang.xml</file>
</header>
<module>erlang</module>
<modulesummary>The Erlang BIFs</modulesummary>
<description>
<p>By convention, most built-in functions (BIFs) are seen as being
in the module <c>erlang</c>. A number of the BIFs are viewed more
or less as part of the Erlang programming language and are
<em>auto-imported</em>. Thus, it is not necessary to specify
the module name and both the calls <c>atom_to_list(Erlang)</c> and
<c>erlang:atom_to_list(Erlang)</c> are identical.</p>
<p>In the text, auto-imported BIFs are listed without module prefix.
BIFs listed with module prefix are not auto-imported.</p>
<p>BIFs may fail for a variety of reasons. All BIFs fail with
reason <c>badarg</c> if they are called with arguments of an
incorrect type. The other reasons that may make BIFs fail are
described in connection with the description of each individual
BIF.</p>
<p>Some BIFs may be used in guard tests, these are marked with
"Allowed in guard tests".</p>
</description>
<datatypes>
<datatype>
<name><marker id="type-ext_binary">ext_binary()</marker></name>
<desc>
<p>A binary data object, structured according to
the Erlang external term format.</p>
</desc>
</datatype>
<datatype>
<name name="timestamp"></name>
<desc><p>See <seealso marker="#now/0">now/0</seealso>.</p>
</desc>
</datatype>
</datatypes>
<funcs>
<func>
<name name="abs" arity="1" clause_i="1"/>
<name name="abs" arity="1" clause_i="2"/>
<type variable="Float" name_i="1"/>
<type variable="Int" name_i="2"/>
<fsummary>Arithmetical absolute value</fsummary>
<desc>
<p>Returns an integer or float which is the arithmetical
absolute value of <c><anno>Float</anno></c> or <c><anno>Int</anno></c>.</p>
<pre>
> <input>abs(-3.33).</input>
3.33
> <input>abs(-3).</input>
3</pre>
<p>Allowed in guard tests.</p>
</desc>
</func>
<func>
<name name="adler32" arity="1"/>
<fsummary>Compute adler32 checksum</fsummary>
<desc>
<p>Computes and returns the adler32 checksum for <c><anno>Data</anno></c>.</p>
</desc>
</func>
<func>
<name name="adler32" arity="2"/>
<fsummary>Compute adler32 checksum</fsummary>
<desc>
<p>Continue computing the adler32 checksum by combining
the previous checksum, <c><anno>OldAdler</anno></c>, with the checksum of
<c><anno>Data</anno></c>.</p>
<p>The following code:</p>
<code>
X = erlang:adler32(Data1),
Y = erlang:adler32(X,Data2).
</code>
<p>- would assign the same value to <c>Y</c> as this would:</p>
<code>
Y = erlang:adler32([Data1,Data2]).
</code>
</desc>
</func>
<func>
<name name="adler32_combine" arity="3"/>
<fsummary>Combine two adler32 checksums</fsummary>
<desc>
<p>Combines two previously computed adler32 checksums.
This computation requires the size of the data object for
the second checksum to be known.</p>
<p>The following code:</p>
<code>
Y = erlang:adler32(Data1),
Z = erlang:adler32(Y,Data2).
</code>
<p>- would assign the same value to <c>Z</c> as this would:</p>
<code>
X = erlang:adler32(Data1),
Y = erlang:adler32(Data2),
Z = erlang:adler32_combine(X,Y,iolist_size(Data2)).
</code>
</desc>
</func>
<func>
<name name="append_element" arity="2"/>
<fsummary>Append an extra element to a tuple</fsummary>
<desc>
<p>Returns a new tuple which has one element more than
<c><anno>Tuple1</anno></c>, and contains the elements in <c><anno>Tuple1</anno></c>
followed by <c><anno>Term</anno></c> as the last element. Semantically
equivalent to
<c>list_to_tuple(tuple_to_list(<anno>Tuple1</anno>) ++ [<anno>Term</anno>])</c>, but much
faster.</p>
<pre>
> <input>erlang:append_element({one, two}, three).</input>
{one,two,three}</pre>
</desc>
</func>
<func>
<name name="apply" arity="2"/>
<fsummary>Apply a function to an argument list</fsummary>
<desc>
<p>Call a fun, passing the elements in <c><anno>Args</anno></c> as
arguments.</p>
<p>Note: If the number of elements in the arguments are known at
compile-time, the call is better written as
<c><anno>Fun</anno>(Arg1, Arg2, ... ArgN)</c>.</p>
<warning>
<p>Earlier, <c><anno>Fun</anno></c> could also be given as
<c>{Module, Function}</c>, equivalent to
<c>apply(Module, Function, Args)</c>. This usage is
deprecated and will stop working in a future release of
Erlang/OTP.</p>
</warning>
</desc>
</func>
<func>
<name name="apply" arity="3"/>
<fsummary>Apply a function to an argument list</fsummary>
<desc>
<p>Returns the result of applying <c>Function</c> in
<c><anno>Module</anno></c> to <c><anno>Args</anno></c>. The applied function must
be exported from <c>Module</c>. The arity of the function is
the length of <c>Args</c>.</p>
<pre>
> <input>apply(lists, reverse, [[a, b, c]]).</input>
[c,b,a]</pre>
<p><c>apply</c> can be used to evaluate BIFs by using
the module name <c>erlang</c>.</p>
<pre>
> <input>apply(erlang, atom_to_list, ['Erlang']).</input>
"Erlang"</pre>
<p>Note: If the number of arguments are known at compile-time,
the call is better written as
<c><anno>Module</anno>:<anno>Function</anno>(Arg1, Arg2, ..., ArgN)</c>.</p>
<p>Failure: <c>error_handler:undefined_function/3</c> is called
if the applied function is not exported. The error handler
can be redefined (see
<seealso marker="#process_flag/2">process_flag/2</seealso>).
If the <c>error_handler</c> is undefined, or if the user has
redefined the default <c>error_handler</c> so the replacement
module is undefined, an error with the reason <c>undef</c>
is generated.</p>
</desc>
</func>
<func>
<name name="atom_to_binary" arity="2"/>
<fsummary>Return the binary representation of an atom</fsummary>
<desc>
<p>Returns a binary which corresponds to the text
representation of <c><anno>Atom</anno></c>. If <c><anno>Encoding</anno></c>
is <c>latin1</c>, there will be one byte for each character
in the text representation. If <c><anno>Encoding</anno></c> is
<c>utf8</c> or
<c>unicode</c>, the characters will be encoded using UTF-8
(meaning that characters from 16#80 up to 0xFF will be
encoded in two bytes).</p>
<note><p>Currently, <c>atom_to_binary(<anno>Atom</anno>, latin1)</c> can
never fail because the text representation of an atom can only contain
characters from 0 to 16#FF. In a future release, the text representation
of atoms might be allowed to contain any Unicode character
and <c>atom_to_binary(<anno>Atom</anno>, latin1)</c> will fail if the
text representation for the <c><anno>Atom</anno></c> contains a Unicode
character greater than 16#FF.</p></note>
<pre>
> <input>atom_to_binary('Erlang', latin1).</input>
<<"Erlang">></pre>
</desc>
</func>
<func>
<name name="atom_to_list" arity="1"/>
<fsummary>Text representation of an atom</fsummary>
<desc>
<p>Returns a string which corresponds to the text
representation of <c><anno>Atom</anno></c>.</p>
<pre>
> <input>atom_to_list('Erlang').</input>
"Erlang"</pre>
</desc>
</func>
<func>
<name name="binary_part" arity="2"/>
<fsummary>Extracts a part of a binary</fsummary>
<desc>
<p>Extracts the part of the binary described by <c><anno>PosLen</anno></c>.</p>
<p>Negative length can be used to extract bytes at the end of a binary:</p>
<code>
1> Bin = <<1,2,3,4,5,6,7,8,9,10>>.
2> binary_part(Bin,{byte_size(Bin), -5}).
<<6,7,8,9,10>>
</code>
<p>If <c><anno>PosLen</anno></c> in any way references outside the binary, a <c>badarg</c> exception is raised.</p>
<p><c><anno>Start</anno></c> is zero-based, i.e.:</p>
<code>
1> Bin = <<1,2,3>>
2> binary_part(Bin,{0,2}).
<<1,2>>
</code>
<p>See the STDLIB module <c>binary</c> for details about the <c><anno>PosLen</anno></c> semantics.</p>
<p>Allowed in guard tests.</p>
</desc>
</func>
<func>
<name name="binary_part" arity="3"/>
<fsummary>Extracts a part of a binary</fsummary>
<desc>
<p>The same as <c>binary_part(<anno>Subject</anno>, {<anno>Start</anno>, <anno>Length</anno>})</c>.</p>
<p>Allowed in guard tests.</p>
</desc>
</func>
<func>
<name name="binary_to_atom" arity="2"/>
<fsummary>Convert from text representation to an atom</fsummary>
<desc>
<p>Returns the atom whose text representation is
<c><anno>Binary</anno></c>. If <c><anno>Encoding</anno></c> is <c>latin1</c>, no
translation of bytes in the binary is done. If <c><anno>Encoding</anno></c>
is <c>utf8</c> or <c>unicode</c>, the binary must contain
valid UTF-8 sequences; furthermore, only Unicode characters up
to 0xFF are allowed.</p>
<note><p><c>binary_to_atom(<anno>Binary</anno>, utf8)</c> will fail if
the binary contains Unicode characters greater than 16#FF.
In a future release, such Unicode characters might be allowed
and <c>binary_to_atom(<anno>Binary</anno>, utf8)</c>
will not fail in that case. For more information on Unicode support in atoms
see <seealso marker="erl_ext_dist#utf8_atoms">note on UTF-8 encoded atoms</seealso>
in the chapter about the external term format in the ERTS User's Guide.</p></note>
<pre>
> <input>binary_to_atom(<<"Erlang">>, latin1).</input>
'Erlang'
> <input>binary_to_atom(<<1024/utf8>>, utf8).</input>
** exception error: bad argument
in function binary_to_atom/2
called as binary_to_atom(<<208,128>>,utf8)</pre>
</desc>
</func>
<func>
<name name="binary_to_existing_atom" arity="2"/>
<fsummary>Convert from text representation to an atom</fsummary>
<desc>
<p>Works like <seealso marker="#binary_to_atom/2">binary_to_atom/2</seealso>,
but the atom must already exist.</p>
<p>Failure: <c>badarg</c> if the atom does not already exist.</p>
</desc>
</func>
<func>
<name name="binary_to_float" arity="1"/>
<fsummary>Convert from text representation to a float</fsummary>
<desc>
<p>Returns the float whose text representation is <c><anno>Binary</anno></c>.</p>
<pre>
> <input>binary_to_float(<<"2.2017764e+0">>).</input>
2.2017764</pre>
<p>Failure: <c>badarg</c> if <c><anno>Binary</anno></c> contains a bad
representation of a float.</p>
</desc>
</func>
<func>
<name name="binary_to_integer" arity="1"/>
<fsummary>Convert from text representation to an integer</fsummary>
<desc>
<p>Returns an integer whose text representation is
<c><anno>Binary</anno></c>.</p>
<pre>
> <input>binary_to_integer(<<"123">>).</input>
123</pre>
<p>Failure: <c>badarg</c> if <c><anno>Binary</anno></c> contains a bad
representation of an integer.</p>
</desc>
</func>
<func>
<name name="binary_to_integer" arity="2"/>
<fsummary>Convert from text representation to an integer</fsummary>
<desc>
<p>Returns an integer whose text representation in base
<c><anno>Base</anno></c> is <c><anno>Binary</anno></c>.</p>
<pre>
> <input>binary_to_integer(<<"3FF">>, 16).</input>
1023</pre>
<p>Failure: <c>badarg</c> if <c><anno>Binary</anno></c> contains a bad
representation of an integer.</p>
</desc>
</func>
<func>
<name name="binary_to_list" arity="1"/>
<fsummary>Convert a binary to a list</fsummary>
<desc>
<p>Returns a list of integers which correspond to the bytes of
<c><anno>Binary</anno></c>.</p>
</desc>
</func>
<func>
<name name="binary_to_list" arity="3"/>
<fsummary>Convert part of a binary to a list</fsummary>
<type_desc variable="Start">1..byte_size(<anno>Binary</anno>)</type_desc>
<desc>
<p>As <c>binary_to_list/1</c>, but returns a list of integers
corresponding to the bytes from position <c><anno>Start</anno></c> to
position <c><anno>Stop</anno></c> in <c><anno>Binary</anno></c>. Positions in the
binary are numbered starting from 1.</p>
<note><p>This function's indexing style of using one-based indices for
binaries is deprecated. New code should use the functions in
the STDLIB module <c>binary</c> instead. They consequently
use the same (zero-based) style of indexing.</p></note>
</desc>
</func>
<func>
<name name="bitstring_to_list" arity="1"/>
<fsummary>Convert a bitstring to a list</fsummary>
<desc>
<p>Returns a list of integers which correspond to the bytes of
<c><anno>Bitstring</anno></c>. If the number of bits in the binary is not
divisible by 8, the last element of the list will be a bitstring
containing the remaining bits (1 up to 7 bits).</p>
</desc>
</func>
<func>
<name name="binary_to_term" arity="1"/>
<fsummary>Decode an Erlang external term format binary</fsummary>
<desc>
<p>Returns an Erlang term which is the result of decoding
the binary object <c><anno>Binary</anno></c>, which must be encoded
according to the Erlang external term format.</p>
<warning>
<p>When decoding binaries from untrusted sources, consider using
<c>binary_to_term/2</c> to prevent denial of service attacks.</p>
</warning>
<p>See also
<seealso marker="#term_to_binary/1">term_to_binary/1</seealso>
and
<seealso marker="#binary_to_term/2">binary_to_term/2</seealso>.</p>
</desc>
</func>
<func>
<name name="binary_to_term" arity="2"/>
<fsummary>Decode an Erlang external term format binary</fsummary>
<desc>
<p>As <c>binary_to_term/1</c>, but takes options that affect decoding
of the binary.</p>
<taglist>
<tag><c>safe</c></tag>
<item>
<p>Use this option when receiving binaries from an untrusted
source.</p>
<p>When enabled, it prevents decoding data that may be used to
attack the Erlang system. In the event of receiving unsafe
data, decoding fails with a badarg error.</p>
<p>Currently, this prevents creation of new atoms directly,
creation of new atoms indirectly (as they are embedded in
certain structures like pids, refs, funs, etc.), and creation of
new external function references. None of those resources are
currently garbage collected, so unchecked creation of them can
exhaust available memory.</p>
</item>
</taglist>
<p>Failure: <c>badarg</c> if <c>safe</c> is specified and unsafe data
is decoded.</p>
<p>See also
<seealso marker="#term_to_binary/1">term_to_binary/1</seealso>,
<seealso marker="#binary_to_term/1">binary_to_term/1</seealso>,
and <seealso marker="#list_to_existing_atom/1">
list_to_existing_atom/1</seealso>.</p>
</desc>
</func>
<func>
<name name="bit_size" arity="1"/>
<fsummary>Return the size of a bitstring</fsummary>
<desc>
<p>Returns an integer which is the size in bits of <c><anno>Bitstring</anno></c>.</p>
<pre>
> <input>bit_size(<<433:16,3:3>>).</input>
19
> <input>bit_size(<<1,2,3>>).</input>
24</pre>
<p>Allowed in guard tests.</p>
</desc>
</func>
<func>
<name name="bump_reductions" arity="1"/>
<fsummary>Increment the reduction counter</fsummary>
<desc>
<p>This implementation-dependent function increments
the reduction counter for the calling process. In the Beam
emulator, the reduction counter is normally incremented by
one for each function and BIF call, and a context switch is
forced when the counter reaches the maximum number of reductions
for a process (2000 reductions in R12B).</p>
<warning>
<p>This BIF might be removed in a future version of the Beam
machine without prior warning. It is unlikely to be
implemented in other Erlang implementations.</p>
</warning>
</desc>
</func>
<func>
<name name="byte_size" arity="1"/>
<fsummary>Return the size of a bitstring (or binary)</fsummary>
<desc>
<p>Returns an integer which is the number of bytes needed to contain
<c><anno>Bitstring</anno></c>. (That is, if the number of bits in <c><anno>Bitstring</anno></c> is not
divisible by 8, the resulting number of bytes will be rounded <em>up</em>.)</p>
<pre>
> <input>byte_size(<<433:16,3:3>>).</input>
3
> <input>byte_size(<<1,2,3>>).</input>
3</pre>
<p>Allowed in guard tests.</p>
</desc>
</func>
<func>
<name name="cancel_timer" arity="1"/>
<fsummary>Cancel a timer</fsummary>
<desc>
<p>Cancels a timer, where <c><anno>TimerRef</anno></c> was returned by
either
<seealso marker="#send_after/3">erlang:send_after/3</seealso>
or
<seealso marker="#start_timer/3">erlang:start_timer/3</seealso>.
If the timer is there to be removed, the function returns
the time in milliseconds left until the timer would have expired,
otherwise <c>false</c> (which means that <c><anno>TimerRef</anno></c> was
never a timer, that it has already been cancelled, or that it
has already delivered its message).</p>
<p>See also
<seealso marker="#send_after/3">erlang:send_after/3</seealso>,
<seealso marker="#start_timer/3">erlang:start_timer/3</seealso>,
and
<seealso marker="#read_timer/1">erlang:read_timer/1</seealso>.</p>
<p>Note: Cancelling a timer does not guarantee that the message
has not already been delivered to the message queue.</p>
</desc>
</func>
<func>
<name name="check_old_code" arity="1"/>
<fsummary>Check if a module has old code</fsummary>
<desc>
<p>Returns <c>true</c> if the <c><anno>Module</anno></c> has old code,
and <c>false</c> otherwise.</p>
<p>See also <seealso marker="kernel:code">code(3)</seealso>.</p>
</desc>
</func>
<func>
<name name="check_process_code" arity="2"/>
<fsummary>Check if a process is executing old code for a module</fsummary>
<desc>
<p>Returns <c>true</c> if the process <c><anno>Pid</anno></c> is executing
old code for <c><anno>Module</anno></c>. That is, if the current call of
the process executes old code for this module, or if the
process has references to old code for this module, or if the
process contains funs that references old code for this
module. Otherwise, it returns <c>false</c>.</p>
<pre>
> <input>check_process_code(Pid, lists).</input>
false</pre>
<p>See also <seealso marker="kernel:code">code(3)</seealso>.</p>
</desc>
</func>
<func>
<name name="crc32" arity="1"/>
<fsummary>Compute crc32 (IEEE 802.3) checksum</fsummary>
<desc>
<p>Computes and returns the crc32 (IEEE 802.3 style) checksum for <c><anno>Data</anno></c>.</p>
</desc>
</func>
<func>
<name name="crc32" arity="2"/>
<fsummary>Compute crc32 (IEEE 802.3) checksum</fsummary>
<desc>
<p>Continue computing the crc32 checksum by combining
the previous checksum, <c><anno>OldCrc</anno></c>, with the checksum of
<c><anno>Data</anno></c>.</p>
<p>The following code:</p>
<code>
X = erlang:crc32(Data1),
Y = erlang:crc32(X,Data2).
</code>
<p>- would assign the same value to <c>Y</c> as this would:</p>
<code>
Y = erlang:crc32([Data1,Data2]).
</code>
</desc>
</func>
<func>
<name name="crc32_combine" arity="3"/>
<fsummary>Combine two crc32 (IEEE 802.3) checksums</fsummary>
<desc>
<p>Combines two previously computed crc32 checksums.
This computation requires the size of the data object for
the second checksum to be known.</p>
<p>The following code:</p>
<code>
Y = erlang:crc32(Data1),
Z = erlang:crc32(Y,Data2).
</code>
<p>- would assign the same value to <c>Z</c> as this would:</p>
<code>
X = erlang:crc32(Data1),
Y = erlang:crc32(Data2),
Z = erlang:crc32_combine(X,Y,iolist_size(Data2)).
</code>
</desc>
</func>
<func>
<name name="date" arity="0"/>
<fsummary>Current date</fsummary>
<desc>
<p>Returns the current date as <c>{Year, Month, Day}</c>.</p>
<p>The time zone and daylight saving time correction depend on
the underlying OS.</p>
<pre>
> <input>date().</input>
{1995,2,19}</pre>
</desc>
</func>
<func>
<name name="decode_packet" arity="3"/>
<fsummary>Extracts a protocol packet from a binary</fsummary>
<desc>
<p>Decodes the binary <c><anno>Bin</anno></c> according to the packet
protocol specified by <c><anno>Type</anno></c>. Very similar to the packet
handling done by sockets with the option {packet,<anno>Type</anno>}.</p>
<p>If an entire packet is contained in <c><anno>Bin</anno></c> it is
returned together with the remainder of the binary as
<c>{ok,<anno>Packet</anno>,<anno>Rest</anno>}</c>.</p>
<p>If <c><anno>Bin</anno></c> does not contain the entire packet,
<c>{more,<anno>Length</anno>}</c> is returned. <c><anno>Length</anno></c> is either the
expected <em>total size</em> of the packet or <c>undefined</c>
if the expected packet size is not known. <c>decode_packet</c>
can then be called again with more data added.</p>
<p>If the packet does not conform to the protocol format
<c>{error,<anno>Reason</anno>}</c> is returned.</p>
<p>The following values of <c><anno>Type</anno></c> are valid:</p>
<taglist>
<tag><c>raw | 0</c></tag>
<item>
<p>No packet handling is done. Entire binary is
returned unless it is empty.</p>
</item>
<tag><c>1 | 2 | 4</c></tag>
<item>
<p>Packets consist of a header specifying the number of
bytes in the packet, followed by that number of bytes.
The length of header can be one, two, or four bytes;
the order of the bytes is big-endian. The header
will be stripped off when the packet is returned.</p>
</item>
<tag><c>line</c></tag>
<item>
<p>A packet is a line terminated with newline. The
newline character is included in the returned packet
unless the line was truncated according to the option
<c>line_length</c>.</p>
</item>
<tag><c>asn1 | cdr | sunrm | fcgi | tpkt</c></tag>
<item>
<p>The header is <em>not</em> stripped off.</p>
<p>The meanings of the packet types are as follows:</p>
<taglist>
<tag><c>asn1</c> - ASN.1 BER</tag><item></item>
<tag><c>sunrm</c> - Sun's RPC encoding</tag><item></item>
<tag><c>cdr</c> - CORBA (GIOP 1.1)</tag><item></item>
<tag><c>fcgi</c> - Fast CGI</tag><item></item>
<tag><c>tpkt</c> - TPKT format [RFC1006]</tag><item></item>
</taglist>
</item>
<tag><c>http | httph | http_bin | httph_bin</c></tag>
<item>
<p>The Hypertext Transfer Protocol. The packets
are returned with the format according to
<c><anno>HttpPacket</anno></c> described above. A packet is either a
request, a response, a header or an end of header
mark. Invalid lines are returned as <c><anno>HttpError</anno></c>.</p>
<p>Recognized request methods and header fields are returned as atoms.
Others are returned as strings. Strings of unrecognized header fields
are formatted with only capital letters first and after hyphen characters
(like <c>"Sec-Websocket-Key"</c>).</p>
<p>The protocol type <c>http</c> should only be used for
the first line when a <c><anno>HttpRequest</anno></c> or a
<c><anno>HttpResponse</anno></c> is expected. The following calls
should use <c>httph</c> to get <c><anno>HttpHeader</anno></c>'s until
<c>http_eoh</c> is returned that marks the end of the
headers and the beginning of any following message body.</p>
<p>The variants <c>http_bin</c> and <c>httph_bin</c> will return
strings (<c>HttpString</c>) as binaries instead of lists.</p>
</item>
</taglist>
<p>The following options are available:</p>
<taglist>
<tag><c>{packet_size, integer() >= 0}</c></tag>
<item><p>Sets the max allowed size of the packet body. If
the packet header indicates that the length of the
packet is longer than the max allowed length, the packet
is considered invalid. Default is 0 which means no
size limit.</p>
</item>
<tag><c>{line_length, integer() >= 0}</c></tag>
<item><p>For packet type <c>line</c>, truncate lines longer
than the indicated length.</p>
<p>Option <c>line_length</c> also applies to <c>http*</c>
packet types as an alias for option <c>packet_size</c> in the
case when <c>packet_size</c> itself is not set. This usage is
only intended for backward compatibility.</p>
</item>
</taglist>
<pre>
> <input>erlang:decode_packet(1,<<3,"abcd">>,[]).</input>
{ok,<<"abc">>,<<"d">>}
> <input>erlang:decode_packet(1,<<5,"abcd">>,[]).</input>
{more,6}</pre>
</desc>
</func>
<func>
<name name="delete_element" arity="2"/>
<fsummary>Delete element at index in a tuple</fsummary>
<type_desc variable="Index">1..tuple_size(<anno>Tuple1</anno>)</type_desc>
<desc>
<p>
Returns a new tuple with element at <c><anno>Index</anno></c> removed from
tuple <c><anno>Tuple1</anno></c>.
</p>
<pre>
> <input>erlang:delete_element(2, {one, two, three}).</input>
{one,three}</pre>
</desc>
</func>
<func>
<name name="delete_module" arity="1"/>
<fsummary>Make the current code for a module old</fsummary>
<desc>
<p>Makes the current code for <c><anno>Module</anno></c> become old code, and
deletes all references for this module from the export table.
Returns <c>undefined</c> if the module does not exist,
otherwise <c>true</c>.</p>
<warning>
<p>This BIF is intended for the code server (see
<seealso marker="kernel:code">code(3)</seealso>) and should not be
used elsewhere.</p>
</warning>
<p>Failure: <c>badarg</c> if there is already an old version of
<c>Module</c>.</p>
</desc>
</func>
<func>
<name name="demonitor" arity="1"/>
<fsummary>Stop monitoring</fsummary>
<desc>
<p>If <c><anno>MonitorRef</anno></c> is a reference which the calling process
obtained by calling
<seealso marker="#monitor/2">monitor/2</seealso>,
this monitoring is turned off. If the monitoring is already
turned off, nothing happens.</p>
<p>Once <c>demonitor(<anno>MonitorRef</anno>)</c> has returned it is
guaranteed that no <c>{'DOWN', <anno>MonitorRef</anno>, _, _, _}</c> message
due to the monitor will be placed in the caller's message queue
in the future. A <c>{'DOWN', <anno>MonitorRef</anno>, _, _, _}</c> message
might have been placed in the caller's message queue prior to
the call, though. Therefore, in most cases, it is advisable
to remove such a <c>'DOWN'</c> message from the message queue
after monitoring has been stopped.
<seealso marker="#demonitor/2">demonitor(<anno>MonitorRef</anno>, [flush])</seealso> can be used instead of
<c>demonitor(<anno>MonitorRef</anno>)</c> if this cleanup is wanted.</p>
<note>
<p>Prior to OTP release R11B (erts version 5.5) <c>demonitor/1</c>
behaved completely asynchronous, i.e., the monitor was active
until the "demonitor signal" reached the monitored entity. This
had one undesirable effect, though. You could never know when
you were guaranteed <em>not</em> to receive a <c>DOWN</c> message
due to the monitor.</p>
<p>Current behavior can be viewed as two combined operations:
asynchronously send a "demonitor signal" to the monitored entity
and ignore any future results of the monitor. </p>
</note>
<p>Failure: It is an error if <c><anno>MonitorRef</anno></c> refers to a
monitoring started by another process. Not all such cases are
cheap to check; if checking is cheap, the call fails with
<c>badarg</c> (for example if <c><anno>MonitorRef</anno></c> is a remote
reference).</p>
</desc>
</func>
<func>
<name name="demonitor" arity="2"/>
<fsummary>Stop monitoring</fsummary>
<desc>
<p>The returned value is <c>true</c> unless <c>info</c> is part
of <c><anno>OptionList</anno></c>.
</p>
<p><c>demonitor(<anno>MonitorRef</anno>, [])</c> is equivalent to
<seealso marker="#demonitor/1">demonitor(<anno>MonitorRef</anno>)</seealso>.</p>
<p>Currently the following <c><anno>Option</anno></c>s are valid:</p>
<taglist>
<tag><c>flush</c></tag>
<item>
<p>Remove (one) <c>{_, <anno>MonitorRef</anno>, _, _, _}</c> message,
if there is one, from the caller's message queue after
monitoring has been stopped.</p>
<p>Calling <c>demonitor(<anno>MonitorRef</anno>, [flush])</c>
is equivalent to the following, but more efficient:</p>
<code type="none">
demonitor(MonitorRef),
receive
{_, MonitorRef, _, _, _} ->
true
after 0 ->
true
end</code>
</item>
<tag><c>info</c></tag>
<item>
<p>The returned value is one of the following:</p>
<taglist>
<tag><c>true</c></tag>
<item><p>The monitor was found and removed. In this case
no <c>'DOWN'</c> message due to this monitor have
been nor will be placed in the message queue
of the caller.
</p>
</item>
<tag><c>false</c></tag>
<item><p>The monitor was not found and could not be removed.
This probably because someone already has placed a
<c>'DOWN'</c> message corresponding to this monitor
in the caller's message queue.
</p>
</item>
</taglist>
<p>If the <c>info</c> option is combined with the <c>flush</c>
option, <c>false</c> will be returned if a flush was needed;
otherwise, <c>true</c>.
</p>
</item>
</taglist>
<note>
<p>More options may be added in the future.</p>
</note>
<p>Failure: <c>badarg</c> if <c><anno>OptionList</anno></c> is not a list, or
if <c><anno>Option</anno></c> is not a valid option, or the same failure as for
<seealso marker="#demonitor/1">demonitor/1</seealso></p>
</desc>
</func>
<func>
<name name="disconnect_node" arity="1"/>
<fsummary>Force the disconnection of a node</fsummary>
<desc>
<p>Forces the disconnection of a node. This will appear to
the node <c><anno>Node</anno></c> as if the local node has crashed. This
BIF is mainly used in the Erlang network authentication
protocols. Returns <c>true</c> if disconnection succeeds,
otherwise <c>false</c>. If the local node is not alive,
the function returns <c>ignored</c>.</p>
</desc>
</func>
<func>
<name name="display" arity="1"/>
<fsummary>Print a term on standard output</fsummary>
<desc>
<p>Prints a text representation of <c><anno>Term</anno></c> on the standard
output.</p>
<warning>
<p>This BIF is intended for debugging only.</p>
</warning>
</desc>
</func>
<func>
<name name="element" arity="2"/>
<type_desc variable="N">1..tuple_size(<anno>Tuple</anno>)</type_desc>
<fsummary>Get Nth element of a tuple</fsummary>
<desc>
<p>Returns the <c><anno>N</anno></c>th element (numbering from 1) of
<c><anno>Tuple</anno></c>.</p>
<pre>
> <input>element(2, {a, b, c}).</input>
b</pre>
<p>Allowed in guard tests.</p>
</desc>
</func>
<func>
<name name="erase" arity="0"/>
<fsummary>Return and delete the process dictionary</fsummary>
<desc>
<p>Returns the process dictionary and deletes it.</p>
<pre>
> <input>put(key1, {1, 2, 3}),</input>
<input>put(key2, [a, b, c]),</input>
<input>erase().</input>
[{key1,{1,2,3}},{key2,[a,b,c]}]</pre>
</desc>
</func>
<func>
<name name="erase" arity="1"/>
<fsummary>Return and delete a value from the process dictionary</fsummary>
<desc>
<p>Returns the value <c><anno>Val</anno></c> associated with <c><anno>Key</anno></c> and
deletes it from the process dictionary. Returns
<c>undefined</c> if no value is associated with <c><anno>Key</anno></c>.</p>
<pre>
> <input>put(key1, {merry, lambs, are, playing}),</input>
<input>X = erase(key1),</input>
<input>{X, erase(key1)}.</input>
{{merry,lambs,are,playing},undefined}</pre>
</desc>
</func>
<func>
<name name="error" arity="1"/>
<fsummary>Stop execution with a given reason</fsummary>
<desc>
<p>Stops the execution of the calling process with the reason
<c><anno>Reason</anno></c>, where <c><anno>Reason</anno></c> is any term. The actual
exit reason will be <c>{<anno>Reason</anno>, Where}</c>, where <c>Where</c>
is a list of the functions most recently called (the current
function first). Since evaluating this function causes
the process to terminate, it has no return value.</p>
<pre>
> <input>catch error(foobar).</input>
{'EXIT',{foobar,[{erl_eval,do_apply,5},
{erl_eval,expr,5},
{shell,exprs,6},
{shell,eval_exprs,6},
{shell,eval_loop,3}]}}</pre>
</desc>
</func>
<func>
<name name="error" arity="2"/>
<fsummary>Stop execution with a given reason</fsummary>
<desc>
<p>Stops the execution of the calling process with the reason
<c><anno>Reason</anno></c>, where <c><anno>Reason</anno></c> is any term. The actual
exit reason will be <c>{<anno>Reason</anno>, Where}</c>, where <c>Where</c>
is a list of the functions most recently called (the current
function first). <c><anno>Args</anno></c> is expected to be the list of
arguments for the current function; in Beam it will be used
to provide the actual arguments for the current function in
the <c>Where</c> term. Since evaluating this function causes
the process to terminate, it has no return value.</p>
</desc>
</func>
<func>
<name name="exit" arity="1"/>
<fsummary>Stop execution with a given reason</fsummary>
<desc>
<p>Stops the execution of the calling process with the exit
reason <c><anno>Reason</anno></c>, where <c><anno>Reason</anno></c> is any term. Since
evaluating this function causes the process to terminate, it
has no return value.</p>
<pre>
> <input>exit(foobar).</input>
** exception exit: foobar
> <input>catch exit(foobar).</input>
{'EXIT',foobar}</pre>
</desc>
</func>
<func>
<name name="exit" arity="2"/>
<fsummary>Send an exit signal to a process or a port</fsummary>
<desc>
<p>Sends an exit signal with exit reason <c><anno>Reason</anno></c> to
the process or port identified by <c><anno>Pid</anno></c>.</p>
<p>The following behavior apply if <c><anno>Reason</anno></c> is any term
except <c>normal</c> or <c>kill</c>:</p>
<p>If <c><anno>Pid</anno></c> is not trapping exits, <c><anno>Pid</anno></c> itself will
exit with exit reason <c><anno>Reason</anno></c>. If <c><anno>Pid</anno></c> is trapping
exits, the exit signal is transformed into a message
<c>{'EXIT', From, <anno>Reason</anno>}</c> and delivered to the message
queue of <c><anno>Pid</anno></c>. <c>From</c> is the pid of the process
which sent the exit signal. See also
<seealso marker="#process_flag/2">process_flag/2</seealso>.</p>
<p>If <c><anno>Reason</anno></c> is the atom <c>normal</c>, <c><anno>Pid</anno></c> will
not exit. If it is trapping exits, the exit signal is
transformed into a message <c>{'EXIT', From, normal}</c>
and delivered to its message queue.</p>
<p>If <c><anno>Reason</anno></c> is the atom <c>kill</c>, that is if
<c>exit(<anno>Pid</anno>, kill)</c> is called, an untrappable exit signal
is sent to <c><anno>Pid</anno></c> which will unconditionally exit with
exit reason <c>killed</c>.</p>
</desc>
</func>
<func>
<name name="external_size" arity="1"/>
<fsummary>Calculate the maximum size for a term encoded in the Erlang
external term format</fsummary>
<desc>
<p>Calculates, without doing the encoding, the maximum byte size for
a term encoded in the Erlang external term format. The following
condition applies always:</p>
<p>
<pre>
> <input>Size1 = byte_size(term_to_binary(<anno>Term</anno>)),</input>
> <input>Size2 = erlang:external_size(<anno>Term</anno>),</input>
> <input>true = Size1 =< Size2.</input>
true
</pre>
</p>
<p>This is equivalent to a call to: <code>erlang:external_size(<anno>Term</anno>, [])
</code></p>
</desc>
</func>
<func>
<name name="external_size" arity="2"/>
<fsummary>Calculate the maximum size for a term encoded in the Erlang
external term format</fsummary>
<desc>
<p>Calculates, without doing the encoding, the maximum byte size for
a term encoded in the Erlang external term format. The following
condition applies always:</p>
<p>
<pre>
> <input>Size1 = byte_size(term_to_binary(<anno>Term</anno>, <anno>Options</anno>)),</input>
> <input>Size2 = erlang:external_size(<anno>Term</anno>, <anno>Options</anno>),</input>
> <input>true = Size1 =< Size2.</input>
true
</pre>
</p>
<p>The option <c>{minor_version, <anno>Version</anno>}</c> specifies how floats
are encoded. See
<seealso marker="#term_to_binary/2">term_to_binary/2</seealso> for
a more detailed description.
</p>
</desc>
</func>
<func>
<name name="float" arity="1"/>
<fsummary>Convert a number to a float</fsummary>
<desc>
<p>Returns a float by converting <c><anno>Number</anno></c> to a float.</p>
<pre>
> <input>float(55).</input>
55.0</pre>
<p>Allowed in guard tests.</p>
<note>
<p>Note that if used on the top-level in a guard, it will
test whether the argument is a floating point number; for
clarity, use
<seealso marker="#is_float/1">is_float/1</seealso> instead.</p>
<p>When <c>float/1</c> is used in an expression in a guard,
such as '<c>float(A) == 4.0</c>', it converts a number as
described above.</p>
</note>
</desc>
</func>