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
1001
1002
1003
1004
1005
1006
1007
1008
1009
|
<?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE erlref SYSTEM "erlref.dtd">
<erlref>
<header>
<copyright>
<year>1996</year><year>2018</year>
<holder>Ericsson AB. All Rights Reserved.</holder>
</copyright>
<legalnotice>
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
</legalnotice>
<title>code</title>
<prepared></prepared>
<docno></docno>
<date></date>
<rev></rev>
</header>
<module since="">code</module>
<modulesummary>Erlang code server.</modulesummary>
<description>
<p>This module contains the interface to the Erlang
<em>code server</em>, which deals with the loading of compiled
code into a running Erlang runtime system.</p>
<p>The runtime system can be started in <em>interactive</em> or
<em>embedded</em> mode. Which one is decided by the command-line
flag <c>-mode</c>:</p>
<pre>
% <input>erl -mode interactive</input></pre>
<p>The modes are as follows:</p>
<list type="bulleted">
<item>
<p>In interactive mode, which is default, only some code is loaded
during system startup, basically the modules needed by the runtime
system. Other code is dynamically loaded when first
referenced. When a call to a function in a certain module is
made, and the module is not loaded, the code server searches
for and tries to load the module.</p>
</item>
<item>
<p>In embedded mode, modules are not auto loaded. Trying to use
a module that has not been loaded results in an error. This mode is
recommended when the boot script loads all modules, as it is
typically done in OTP releases. (Code can still be loaded later
by explicitly ordering the code server to do so).</p>
</item>
</list>
<p>To prevent accidentally reloading of modules affecting the Erlang
runtime system, directories <c>kernel</c>, <c>stdlib</c>,
and <c>compiler</c> are considered <em>sticky</em>. This
means that the system issues a warning and rejects the request if
a user tries to reload a module residing in any of them.
The feature can be disabled by using command-line flag
<c>-nostick</c>.</p>
</description>
<section>
<title>Code Path</title>
<p>In interactive mode, the code server maintains a search path,
usually called the <em>code path</em>, consisting of a list of
directories, which it searches sequentially when trying to load a
module.</p>
<p>Initially, the code path consists of the current working
directory and all Erlang object code directories under library
directory <c>$OTPROOT/lib</c>, where <c>$OTPROOT</c> is
the installation directory of Erlang/OTP, <c>code:root_dir()</c>.
Directories can be named <c>Name[-Vsn]</c> and the code server,
by default, chooses the directory with the highest version number
among those having the same <c>Name</c>. Suffix <c>-Vsn</c>
is optional. If an <c>ebin</c> directory exists under
<c>Name[-Vsn]</c>, this directory is added to the code path.</p>
<p>Environment variable <c>ERL_LIBS</c> (defined in the operating
system) can be used to define more library directories to
be handled in the same way as the standard OTP library
directory described above, except that directories without
an <c>ebin</c> directory are ignored.</p>
<p>All application directories found in the additional directories
appear before the standard OTP applications, except for the
Kernel and STDLIB applications, which are placed before
any additional applications. In other words, modules found in any
of the additional library directories override modules with
the same name in OTP, except for modules in Kernel and
STDLIB.</p>
<p>Environment variable <c>ERL_LIBS</c> (if defined) is to contain
a colon-separated (for Unix-like systems) or semicolon-separated
(for Windows) list of additional libraries.</p>
<p><em>Example:</em></p>
<p>On a Unix-like system, <c>ERL_LIBS</c> can be set to the following</p>
<code>
/usr/local/jungerl:/home/some_user/my_erlang_lib</code>
<p>On Windows, use semi-colon as separator.</p>
</section>
<section>
<title>Loading of Code From Archive Files</title>
<warning><p>The support for loading code from archive files is
experimental. The purpose of releasing it before it is ready
is to obtain early feedback. The file format, semantics,
interfaces, and so on, can be changed in a future release. The function
<seemfa marker="#lib_dir/2"><c>lib_dir/2</c></seemfa>
and flag <c>-code_path_choice</c> are also
experimental.</p></warning>
<p>The Erlang archives are <c>ZIP</c>
files with extension <c>.ez</c>. Erlang archives can also be
enclosed in <c>escript</c> files whose file extension is arbitrary.</p>
<p>Erlang archive files can contain entire Erlang applications or
parts of applications. The structure in an archive file is the
same as the directory structure for an application. If you, for
example, create an archive of <c>mnesia-4.4.7</c>, the
archive file must be named <c>mnesia-4.4.7.ez</c> and it must
contain a top directory named <c>mnesia-4.4.7</c>. If the
version part of the name is omitted, it must also be omitted in
the archive. That is, a <c>mnesia.ez</c> archive must contain a
<c>mnesia</c> top directory.</p>
<p>An archive file for an application can, for example, be
created like this:</p>
<pre>
zip:create("mnesia-4.4.7.ez",
["mnesia-4.4.7"],
[{cwd, code:lib_dir()},
{compress, all},
{uncompress,[".beam",".app"]}]).</pre>
<p>Any file in the archive can be compressed, but to
speed up the access of frequently read files, it can be a good
idea to store <c>beam</c> and <c>app</c> files uncompressed in
the archive.</p>
<p>Normally the top directory of an application is located
in library directory <c>$OTPROOT/lib</c> or in a directory
referred to by environment variable <c>ERL_LIBS</c>. At
startup, when the initial code path is computed, the code server
also looks for archive files in these directories and
possibly adds <c>ebin</c> directories in archives to the code path. The
code path then contains paths to directories that look like
<c>$OTPROOT/lib/mnesia.ez/mnesia/ebin</c> or
<c>$OTPROOT/lib/mnesia-4.4.7.ez/mnesia-4.4.7/ebin</c>.</p>
<p>The code server uses module <c>erl_prim_loader</c> in ERTS
(possibly through <c>erl_boot_server</c>) to read code files from
archives. However, the functions in <c>erl_prim_loader</c> can also be
used by other applications to read files from archives. For
example, the call
<c>erl_prim_loader:list_dir( "/otp/root/lib/mnesia-4.4.7.ez/mnesia-4.4.7/examples/bench)"</c>
would list the contents of a directory inside an archive.
See <seeerl marker="erts:erl_prim_loader"><c>erl_prim_loader(3)</c></seeerl>.</p>
<p>An application archive file and a regular application directory
can coexist. This can be useful when it is needed to have
parts of the application as regular files. A typical case is the
<c>priv</c> directory, which must reside as a regular directory
to link in drivers dynamically and start port programs.
For other applications that do not need this, directory
<c>priv</c> can reside in the archive and the files
under the directory <c>priv</c> can be read through
<c>erl_prim_loader</c>.</p>
<p>When a directory is added to the code path and
when the entire code path is (re)set, the code server
decides which subdirectories in an application that are to be
read from the archive and which that are to be read as regular
files. If directories are added or removed afterwards, the file
access can fail if the code path is not updated (possibly to the
same path as before, to trigger the directory resolution
update).</p>
<p>For each directory on the second level in the application archive
(<c>ebin</c>, <c>priv</c>, <c>src</c>, and so on), the code server first
chooses the regular directory if it exists and second from the
archive. Function <c>code:lib_dir/2</c> returns the path to the
subdirectory. For example, <c>code:lib_dir(megaco,ebin)</c> can return
<c>/otp/root/lib/megaco-3.9.1.1.ez/megaco-3.9.1.1/ebin</c> while
<c>code:lib_dir(megaco,priv)</c> can return
<c>/otp/root/lib/megaco-3.9.1.1/priv</c>.</p>
<p>When an <c>escript</c> file contains an archive, there are
no restrictions on the name of the <c>escript</c> and no restrictions
on how many applications that can be stored in the embedded
archive. Single Beam files can also reside on the top
level in the archive. At startup, the top directory in the
embedded archive and all (second level) <c>ebin</c>
directories in the embedded archive are added to the code path.
See <seecom marker="erts:escript"><c>erts:escript(1)</c></seecom>.</p>
<p>When the choice of directories in the code path is
<c>strict</c>, the directory that ends up in the code path is
exactly the stated one. This means that if, for example, the
directory <c>$OTPROOT/lib/mnesia-4.4.7/ebin</c> is explicitly
added to the code path, the code server does not load files from
<c>$OTPROOT/lib/mnesia-4.4.7.ez/mnesia-4.4.7/ebin</c>.</p>
<p>This behavior can be controlled through command-line flag
<c>-code_path_choice Choice</c>. If the flag is set to <c>relaxed</c>,
the code server instead chooses a suitable directory
depending on the actual file structure. If a regular
application <c>ebin</c> directory exists, it is chosen. Otherwise,
the directory <c>ebin</c> in the archive is chosen if it
exists. If neither of them exists, the original directory is
chosen.</p>
<p>Command-line flag <c>-code_path_choice Choice</c> also
affects how module <c>init</c> interprets the <c>boot script</c>.
The interpretation of the explicit code paths in the <c>boot
script</c> can be <c>strict</c> or <c>relaxed</c>. It is
particularly useful to set the flag to <c>relaxed</c> when
elaborating with code loading from archives without editing the
<c>boot script</c>. The default is <c>relaxed</c>. See <seeerl
marker="erts:init"><c>erts:init(3)</c></seeerl>.</p></section>
<section>
<title>Current and Old Code</title>
<p>The code for a module can exist in two variants in a system:
<em>current code</em> and <em>old code</em>. When a module is
loaded into the system for the first time, the module code
becomes 'current' and the global <em>export table</em> is updated
with references to all functions exported from the module.</p>
<p>If then a new instance of the module is loaded (for example, because of
error correction), the code of the previous
instance becomes 'old', and all export entries referring to
the previous instance are removed. After that, the new instance is
loaded as for the first time, and becomes 'current'.</p>
<p>Both old and current code for a module are valid, and can even be
evaluated concurrently. The difference is that exported functions
in old code are unavailable. Hence, a global call cannot be made
to an exported function in old code, but old code can
still be evaluated because of processes lingering in it.</p>
<p>If a third instance of the module is loaded, the code server
removes (purges) the old code and any processes lingering in it
are terminated. Then the third instance becomes 'current' and
the previously current code becomes 'old'.</p>
<p>For more information about old and current code, and how to
make a process switch from old to current code, see section
Compilation and Code Loading in the
<seeguide marker="system/reference_manual:code_loading">Erlang Reference Manual</seeguide>.</p>
</section>
<section>
<title>Argument Types and Invalid Arguments</title>
<p>Module and application names are atoms, while file and directory
names are strings. For backward compatibility reasons, some functions accept
both strings and atoms, but a future release will probably only allow
the arguments that are documented.</p>
<p>Functions in this module generally fail with an
exception if they are passed an incorrect type (for example, an integer or a tuple
where an atom is expected). An error tuple is returned if the argument type
is correct, but there are some other errors (for example, a non-existing directory
is specified to <c>set_path/1</c>).</p>
</section>
<section>
<marker id="error_reasons"></marker>
<title>Error Reasons for Code-Loading Functions</title>
<p>Functions that load code (such as <c>load_file/1</c>) will
return <c>{error,Reason}</c> if the load operation fails.
Here follows a description of the common reasons.</p>
<taglist>
<tag><c>badfile</c></tag>
<item>
<p>The object code has an incorrect format or the module
name in the object code is not the expected module name.</p>
</item>
<tag><c>nofile</c></tag>
<item>
<p>No file with object code was found.</p>
</item>
<tag><c>not_purged</c></tag>
<item>
<p>The object code could not be loaded because an old version
of the code already existed.</p>
</item>
<tag><c>on_load_failure</c></tag>
<item>
<p>The module has an
<seeguide marker="system/reference_manual:code_loading#on_load">-on_load function</seeguide>
that failed when it was called.</p>
</item>
<tag><c>sticky_directory</c></tag>
<item>
<p>The object code resides in a sticky directory.</p>
</item>
</taglist>
</section>
<datatypes>
<datatype>
<name name="load_ret"/>
</datatype>
<datatype>
<name name="load_error_rsn"/>
</datatype>
<datatype>
<name name="module_status"/>
</datatype>
<datatype>
<name name="prepared_code"/>
<desc><p>An opaque term holding prepared code.</p></desc>
</datatype>
</datatypes>
<funcs>
<func>
<name name="set_path" arity="1" since=""/>
<fsummary>Set the code server search path.</fsummary>
<desc>
<p>Sets the code path to the list of directories <c><anno>Path</anno></c>.</p>
<p>Returns:</p>
<taglist>
<tag><c>true</c></tag>
<item><p>If successful</p></item>
<tag><c>{error, bad_directory}</c></tag>
<item><p>If any <c><anno>Dir</anno></c> is not a directory name</p></item>
</taglist>
</desc>
</func>
<func>
<name name="get_path" arity="0" since=""/>
<fsummary>Return the code server search path.</fsummary>
<desc>
<p>Returns the code path.</p>
</desc>
</func>
<func>
<name name="add_path" arity="1" since=""/>
<name name="add_pathz" arity="1" since=""/>
<fsummary>Add a directory to the end of the code path.</fsummary>
<type name="add_path_ret"/>
<desc>
<p>Adds <c><anno>Dir</anno></c> to the code path. The directory is added as
the last directory in the new path. If <c><anno>Dir</anno></c> already
exists in the path, it is not added.</p>
<p>Returns <c>true</c> if successful, or
<c>{error, bad_directory}</c> if <c><anno>Dir</anno></c> is not the name
of a directory.</p>
</desc>
</func>
<func>
<name name="add_patha" arity="1" since=""/>
<fsummary>Add a directory to the beginning of the code path.</fsummary>
<type name="add_path_ret"/>
<desc>
<p>Adds <c><anno>Dir</anno></c> to the beginning of the code path. If
<c><anno>Dir</anno></c> exists, it is removed from the old
position in the code path.</p>
<p>Returns <c>true</c> if successful, or
<c>{error, bad_directory}</c> if <c><anno>Dir</anno></c> is not the name
of a directory.</p>
</desc>
</func>
<func>
<name name="add_paths" arity="1" since=""/>
<name name="add_pathsz" arity="1" since=""/>
<fsummary>Add directories to the end of the code path.</fsummary>
<desc>
<p>Adds the directories in <c><anno>Dirs</anno></c> to the end of the code
path. If a <c><anno>Dir</anno></c> exists, it is not added.</p>
<p>Always returns <c>ok</c>, regardless of the validity
of each individual <c><anno>Dir</anno></c>.</p>
</desc>
</func>
<func>
<name name="add_pathsa" arity="1" since=""/>
<fsummary>Add directories to the beginning of the code path.</fsummary>
<desc>
<p>Traverses <c><anno>Dirs</anno></c> and adds
each <c><anno>Dir</anno></c> to the beginning of the code
path. This means that the order of <c><anno>Dirs</anno></c>
is reversed in the resulting code path. For example, if you
add <c>[Dir1,Dir2]</c>, the resulting path will
be <c>[Dir2,Dir1|OldCodePath]</c>.</p>
<p>If a <c><anno>Dir</anno></c> already exists in the code
path, it is removed from the old position.</p>
<p>Always returns <c>ok</c>, regardless of the validity of each
individual <c><anno>Dir</anno></c>.</p>
</desc>
</func>
<func>
<name name="del_path" arity="1" since=""/>
<fsummary>Delete a directory from the code path.</fsummary>
<desc>
<p>Deletes a directory from the code path. The argument can be
an atom <c><anno>Name</anno></c>, in which case the directory with
the name <c>.../<anno>Name</anno>[-Vsn][/ebin]</c> is deleted from the code
path. Also, the complete directory name <c><anno>Dir</anno></c> can be
specified as argument.</p>
<p>Returns:</p>
<taglist>
<tag><c>true</c></tag>
<item><p>If successful</p></item>
<tag><c>false</c></tag>
<item><p>If the directory is not found</p></item>
<tag><c>{error, bad_name}</c></tag>
<item><p>If the argument is invalid</p></item>
</taglist>
</desc>
</func>
<func>
<name name="replace_path" arity="2" since=""/>
<fsummary>Replace a directory with another in the code path.</fsummary>
<desc>
<p>Replaces an old occurrence of a directory
named <c>.../<anno>Name</anno>[-Vsn][/ebin]</c> in the code path, with
<c><anno>Dir</anno></c>. If <c><anno>Name</anno></c> does not exist, it adds
the new directory <c><anno>Dir</anno></c> last in the code path. The new
directory must also be named <c>.../<anno>Name</anno>[-Vsn][/ebin]</c>.
This function is to be used if a new version of the directory (library) is
added to a running system.</p>
<p>Returns:</p>
<taglist>
<tag><c>true</c></tag>
<item><p>If successful</p></item>
<tag><c>{error, bad_name}</c></tag>
<item><p>If <c><anno>Name</anno></c> is not found</p></item>
<tag><c>{error, bad_directory}</c></tag>
<item><p>If <c><anno>Dir</anno></c> does not exist</p></item>
<tag><c>{error, {badarg, [<anno>Name</anno>, <anno>Dir</anno>]}}</c></tag>
<item><p>If <c><anno>Name</anno></c> or <c><anno>Dir</anno></c> is invalid</p></item>
</taglist>
</desc>
</func>
<func>
<name name="load_file" arity="1" since=""/>
<fsummary>Load a module.</fsummary>
<type name="load_ret"/>
<desc>
<p>Tries to load the Erlang module <c><anno>Module</anno></c>, using
the code path. It looks for the object code file with an
extension corresponding to the Erlang machine used, for
example, <c><anno>Module</anno>.beam</c>. The loading fails if the module
name found in the object code differs from the name
<c><anno>Module</anno></c>.
<seemfa marker="#load_binary/3"><c>load_binary/3</c></seemfa> must
be used to load object code with a module name that is
different from the file name.</p>
<p>Returns <c>{module, <anno>Module</anno>}</c> if successful, or
<c>{error, Reason}</c> if loading fails.
See <seeerl marker="#error_reasons">Error Reasons for Code-Loading Functions</seeerl> for a description of the possible error reasons.</p>
</desc>
</func>
<func>
<name name="load_abs" arity="1" since=""/>
<fsummary>Load a module, residing in a specified file.</fsummary>
<type name="load_ret"/>
<type name="loaded_filename"/>
<type name="loaded_ret_atoms"/>
<desc>
<p>Same as <c>load_file(<anno>Module</anno>)</c>, but
<c><anno>Filename</anno></c> is an absolute or
relative filename. The code path is not searched. It returns
a value in the same way as
<seemfa marker="#load_file/1"><c>load_file/1</c></seemfa>. Notice
that <c><anno>Filename</anno></c> must not contain the extension (for
example, <c>.beam</c>) because <c>load_abs/1</c> adds the correct
extension.</p>
</desc>
</func>
<func>
<name name="ensure_loaded" arity="1" since=""/>
<fsummary>Ensure that a module is loaded.</fsummary>
<desc>
<p>Tries to load a module in the same way as
<seemfa marker="#load_file/1"><c>load_file/1</c></seemfa>,
unless the module is already loaded.
However, in embedded mode it does not load a module that is not
already loaded, but returns <c>{error, embedded}</c> instead.
See <seeerl marker="#error_reasons">Error Reasons for Code-Loading Functions</seeerl> for a description of other possible error reasons.</p>
</desc>
</func>
<func>
<name name="load_binary" arity="3" since=""/>
<fsummary>Load object code for a module.</fsummary>
<type name="loaded_filename"/>
<type name="loaded_ret_atoms"/>
<desc>
<p>This function can be used to load object code on remote
Erlang nodes. Argument <c><anno>Binary</anno></c> must contain
object code for <c><anno>Module</anno></c>.
<c><anno>Filename</anno></c> is only used by the code server to keep a
record of from which file the object code for <c><anno>Module</anno></c>
comes. Thus, <c><anno>Filename</anno></c> is not opened and read by
the code server.</p>
<p>Returns <c>{module, <anno>Module</anno>}</c> if successful, or
<c>{error, Reason}</c> if loading fails.
See <seeerl marker="#error_reasons">Error Reasons for Code-Loading Functions</seeerl> for a description of the possible error reasons.</p>
</desc>
</func>
<func>
<name name="atomic_load" arity="1" since="OTP 19.0"/>
<fsummary>Load a list of modules atomically</fsummary>
<desc>
<p>Tries to load all of the modules in the list
<c><anno>Modules</anno></c> atomically. That means that
either all modules are loaded at the same time, or
none of the modules are loaded if there is a problem with any
of the modules.</p>
<p>Loading can fail for one the following reasons:</p>
<taglist>
<tag><c>badfile</c></tag>
<item>
<p>The object code has an incorrect format or the module
name in the object code is not the expected module name.</p>
</item>
<tag><c>nofile</c></tag>
<item>
<p>No file with object code exists.</p>
</item>
<tag><c>on_load_not_allowed</c></tag>
<item>
<p>A module contains an
<seeguide marker="system/reference_manual:code_loading#on_load">-on_load function</seeguide>.</p>
</item>
<tag><c>duplicated</c></tag>
<item>
<p>A module is included more than once in
<c><anno>Modules</anno></c>.</p>
</item>
<tag><c>not_purged</c></tag>
<item>
<p>The object code cannot be loaded because an old version
of the code already exists.</p>
</item>
<tag><c>sticky_directory</c></tag>
<item>
<p>The object code resides in a sticky directory.</p>
</item>
<tag><c>pending_on_load</c></tag>
<item>
<p>A previously loaded module contains an
<c>-on_load</c> function that never finished.</p>
</item>
</taglist>
<p>If it is important to minimize the time that an application
is inactive while changing code, use
<seemfa marker="#prepare_loading/1">prepare_loading/1</seemfa>
and
<seemfa marker="#finish_loading/1">finish_loading/1</seemfa>
instead of <c>atomic_load/1</c>. Here is an example:</p>
<pre>
{ok,Prepared} = code:prepare_loading(Modules),
%% Put the application into an inactive state or do any
%% other preparation needed before changing the code.
ok = code:finish_loading(Prepared),
%% Resume the application.</pre>
</desc>
</func>
<func>
<name name="prepare_loading" arity="1" since="OTP 19.0"/>
<fsummary>Prepare a list of modules atomically</fsummary>
<desc>
<p>Prepares to load the modules in the list
<c><anno>Modules</anno></c>.
Finish the loading by calling
<seemfa marker="#finish_loading/1">finish_loading(Prepared)</seemfa>.</p>
<p>This function can fail with one of the following error reasons:</p>
<taglist>
<tag><c>badfile</c></tag>
<item>
<p>The object code has an incorrect format or the module
name in the object code is not the expected module name.</p>
</item>
<tag><c>nofile</c></tag>
<item>
<p>No file with object code exists.</p>
</item>
<tag><c>on_load_not_allowed</c></tag>
<item>
<p>A module contains an
<seeguide marker="system/reference_manual:code_loading#on_load">-on_load function</seeguide>.</p>
</item>
<tag><c>duplicated</c></tag>
<item>
<p>A module is included more than once in
<c><anno>Modules</anno></c>.</p>
</item>
</taglist>
</desc>
</func>
<func>
<name name="finish_loading" arity="1" since="OTP 19.0"/>
<fsummary>Finish loading a list of prepared modules atomically</fsummary>
<desc>
<p>Tries to load code for all modules that have been previously
prepared by
<seemfa marker="#prepare_loading/1">prepare_loading/1</seemfa>.
The loading occurs atomically, meaning that
either all modules are loaded at the same time, or
none of the modules are loaded.</p>
<p>This function can fail with one of the following error reasons:</p>
<taglist>
<tag><c>not_purged</c></tag>
<item>
<p>The object code cannot be loaded because an old version
of the code already exists.</p>
</item>
<tag><c>sticky_directory</c></tag>
<item>
<p>The object code resides in a sticky directory.</p>
</item>
<tag><c>pending_on_load</c></tag>
<item>
<p>A previously loaded module contains an
<c>-on_load</c> function that never finished.</p>
</item>
</taglist>
</desc>
</func>
<func>
<name name="ensure_modules_loaded" arity="1" since="OTP 19.0"/>
<fsummary>Ensure that a list of modules is loaded</fsummary>
<desc>
<p>Tries to load any modules not already loaded in the list
<c><anno>Modules</anno></c> in the same way as
<seemfa marker="#load_file/1">load_file/1</seemfa>.</p>
<p>Returns <c>ok</c> if successful, or
<c>{error,[{Module,Reason}]}</c> if loading of some modules fails.
See <seeerl marker="#error_reasons">Error Reasons for Code-Loading Functions</seeerl> for a description of other possible error reasons.</p>
</desc>
</func>
<func>
<name name="delete" arity="1" since=""/>
<fsummary>Remove current code for a module.</fsummary>
<desc>
<p>Removes the current code for <c><anno>Module</anno></c>, that is,
the current code for <c><anno>Module</anno></c> is made old. This means
that processes can continue to execute the code in the module,
but no external function calls can be made to it.</p>
<p>Returns <c>true</c> if successful, or <c>false</c> if there
is old code for <c><anno>Module</anno></c> that must be purged first, or
if <c><anno>Module</anno></c> is not a (loaded) module.</p>
</desc>
</func>
<func>
<name name="purge" arity="1" since=""/>
<fsummary>Remove old code for a module.</fsummary>
<desc>
<p>Purges the code for <c><anno>Module</anno></c>, that is, removes code
marked as old. If some processes still linger in the old code,
these processes are killed before the code is removed.</p>
<note><p>As of ERTS version 9.0, a process is only considered
to be lingering in the code if it has direct references to the code.
For more information see documentation of
<seemfa marker="erts:erlang#check_process_code/3"><c>erlang:check_process_code/3</c></seemfa>,
which is used in order to determine this.</p></note>
<p>Returns <c>true</c> if successful and any process is needed to
be killed, otherwise <c>false</c>.</p>
</desc>
</func>
<func>
<name name="soft_purge" arity="1" since=""/>
<fsummary>Remove old code for a module, unless no process uses it.</fsummary>
<desc>
<p>Purges the code for <c><anno>Module</anno></c>, that is, removes code
marked as old, but only if no processes linger in it.</p>
<note><p>As of ERTS version 9.0, a process is only considered
to be lingering in the code if it has direct references to the code.
For more information see documentation of
<seemfa marker="erts:erlang#check_process_code/3"><c>erlang:check_process_code/3</c></seemfa>,
which is used in order to determine this.</p></note>
<p>Returns <c>false</c> if the module cannot be purged because
of processes lingering in old code, otherwise <c>true</c>.</p>
</desc>
</func>
<func>
<name name="is_loaded" arity="1" since=""/>
<fsummary>Check if a module is loaded.</fsummary>
<type name="loaded_filename"/>
<type name="loaded_ret_atoms"/>
<type_desc name="loaded_filename"><c><anno>Filename</anno></c> is an absolute
filename.</type_desc>
<desc>
<p>Checks if <c><anno>Module</anno></c> is loaded. If it is,
<c>{file, <anno>Loaded</anno>}</c> is returned, otherwise <c>false</c>.</p>
<p>Normally, <c><anno>Loaded</anno></c> is the absolute filename
<c>Filename</c> from which the code is obtained. If the module
is preloaded (see
<seefile marker="sasl:script"><c>script(4)</c></seefile>),
<c>Loaded==preloaded</c>. If the module is Cover-compiled (see
<seeerl marker="tools:cover"><c>cover(3)</c></seeerl>),
<c>Loaded==cover_compiled</c>.</p>
</desc>
</func>
<func>
<name name="all_available" arity="0" since="OTP 23.0"/>
<fsummary>Get all available modules.</fsummary>
<type name="loaded_filename"/>
<type name="loaded_ret_atoms"/>
<type_desc name="loaded_filename"><c><anno>Filename</anno></c> is an absolute
filename.</type_desc>
<desc>
<p>Returns a list of tuples <c>{<anno>Module</anno>, <anno>Filename</anno>,
<anno>Loaded</anno>}</c> for all available modules. A module is considered
to be available if it either is loaded or would be loaded if called.
<c><anno>Filename</anno></c> is normally the absolute filename, as described for
<seemfa marker="#is_loaded/1"><c>is_loaded/1</c></seemfa>.</p>
</desc>
</func>
<func>
<name name="all_loaded" arity="0" since=""/>
<fsummary>Get all loaded modules.</fsummary>
<type name="loaded_filename"/>
<type name="loaded_ret_atoms"/>
<type_desc name="loaded_filename"><c><anno>Filename</anno></c> is an absolute
filename.</type_desc>
<desc>
<p>Returns a list of tuples <c>{<anno>Module</anno>, <anno>Loaded</anno>}</c> for all
loaded modules. <c><anno>Loaded</anno></c> is normally the absolute filename,
as described for
<seemfa marker="#is_loaded/1"><c>is_loaded/1</c></seemfa>.</p>
</desc>
</func>
<func>
<name name="which" arity="1" since=""/>
<fsummary>The object code file of a module.</fsummary>
<type name="loaded_filename"/>
<type name="loaded_ret_atoms"/>
<desc>
<p>If the module is not loaded, this function searches the code
path for the first file containing object code for
<c><anno>Module</anno></c> and returns the absolute filename.</p>
<p>If the module is loaded, it returns the name of the file
containing the loaded object code.</p>
<p>If the module is preloaded, <c>preloaded</c> is returned.</p>
<p>If the module is Cover-compiled, <c>cover_compiled</c> is returned.</p>
<p>If the module cannot be found, <c>non_existing</c> is returned.</p>
</desc>
</func>
<func>
<name name="get_object_code" arity="1" since=""/>
<fsummary>Gets the object code for a module.</fsummary>
<desc>
<p>Searches the code path for the object code of module
<c><anno>Module</anno></c>. Returns <c>{<anno>Module</anno>, <anno>Binary</anno>, <anno>Filename</anno>}</c>
if successful, otherwise <c>error</c>. <c><anno>Binary</anno></c> is a
binary data object, which contains the object code for
the module. This can be useful if code is to be loaded on a
remote node in a distributed system. For example, loading
module <c><anno>Module</anno></c> on a node <c>Node</c> is done as
follows:</p>
<code type="none">
...
{_Module, Binary, Filename} = code:get_object_code(Module),
rpc:call(Node, code, load_binary, [Module, Filename, Binary]),
...</code>
</desc>
</func>
<func>
<name name="get_doc" arity="1" since="OTP 23.0"/>
<fsummary>Gets the documentation for a module.</fsummary>
<desc>
<p>Searches the code path for EEP-48 style documentation and returns it
if available. If no documentation can be found the function tries to
generate documentation from the debug information in the module.
If no debug information is available, this function will return
<c>{error,missing}</c>.
</p>
<p>For more information about the documentation chunk see
<seeguide marker="kernel:eep48_chapter">Documentation Storage and Format</seeguide>
in Kernel's User's Guide.</p>
</desc>
</func>
<func>
<name name="root_dir" arity="0" since=""/>
<fsummary>Root directory of Erlang/OTP.</fsummary>
<desc>
<p>Returns the root directory of Erlang/OTP, which is
the directory where it is installed.</p>
<p><em>Example:</em></p>
<pre>
> <input>code:root_dir().</input>
"/usr/local/otp"</pre>
</desc>
</func>
<func>
<name name="lib_dir" arity="0" since=""/>
<fsummary>Library directory of Erlang/OTP.</fsummary>
<desc>
<p>Returns the library directory, <c>$OTPROOT/lib</c>, where
<c>$OTPROOT</c> is the root directory of Erlang/OTP.</p>
<p><em>Example:</em></p>
<pre>
> <input>code:lib_dir().</input>
"/usr/local/otp/lib"</pre>
</desc>
</func>
<func>
<name name="lib_dir" arity="1" since=""/>
<fsummary>Library directory for an application.</fsummary>
<desc>
<p>Returns the path
for the "library directory", the top directory, for an
application <c><anno>Name</anno></c> located under <c>$OTPROOT/lib</c> or
on a directory referred to with environment variable <c>ERL_LIBS</c>.</p>
<p>If a regular directory called <c><anno>Name</anno></c> or
<c><anno>Name</anno>-Vsn</c> exists in the code path with an <c>ebin</c>
subdirectory, the path to this directory is returned (not
the <c>ebin</c> directory).</p>
<p>If the directory refers to a directory in an archive, the
archive name is stripped away before the path is returned.
For example, if directory
<c>/usr/local/otp/lib/mnesia-4.2.2.ez/mnesia-4.2.2/ebin</c>
is in the path, <c>/usr/local/otp/lib/mnesia-4.2.2/ebin</c>
is returned. This means that the library directory for
an application is the same, regardless if the
application resides in an archive or not.</p>
<p><em>Example:</em></p>
<pre>
> <input>code:lib_dir(mnesia).</input>
"/usr/local/otp/lib/mnesia-4.2.2"</pre>
<p>Returns <c>{error, bad_name}</c> if <c><anno>Name</anno></c>
is not the name of an application under <c>$OTPROOT/lib</c> or
on a directory referred to through environment variable <c>ERL_LIBS</c>.
Fails with an exception if <c>Name</c> has the wrong type.</p>
<warning><p>For backward compatibility, <c><anno>Name</anno></c> is also
allowed to be a string. That will probably change in a future release.</p></warning>
</desc>
</func>
<func>
<name name="lib_dir" arity="2" since=""/>
<fsummary>Subdirectory for an application.</fsummary>
<desc>
<p>Returns the path to a subdirectory directly under the top
directory of an application. Normally the subdirectories
reside under the top directory for the application, but when
applications at least partly resides in an archive, the
situation is different. Some of the subdirectories can reside
as regular directories while other reside in an archive
file. It is not checked whether this directory exists.</p>
<p><em>Example:</em></p>
<pre>
> <input>code:lib_dir(megaco, priv).</input>
"/usr/local/otp/lib/megaco-3.9.1.1/priv"</pre>
<p>Fails with an exception if <c><anno>Name</anno></c> or <c><anno>SubDir</anno></c> has
the wrong type.</p>
</desc>
</func>
<func>
<name name="compiler_dir" arity="0" since=""/>
<fsummary>Library directory for the compiler.</fsummary>
<desc>
<p>Returns the compiler library directory. Equivalent to
<c>code:lib_dir(compiler)</c>.</p>
</desc>
</func>
<func>
<name name="priv_dir" arity="1" since=""/>
<fsummary>Priv directory for an application.</fsummary>
<desc>
<p>Returns the path to the <c>priv</c> directory in an
application. Equivalent to <c>code:lib_dir(<anno>Name</anno>, priv)</c>.</p>
<warning><p>For backward compatibility, <c><anno>Name</anno></c> is also allowed to
be a string. That will probably change in a future release.</p></warning>
</desc>
</func>
<func>
<name name="objfile_extension" arity="0" since=""/>
<fsummary>Object code file extension.</fsummary>
<desc>
<p>Returns the object code file extension corresponding to
the Erlang machine used, namely <c>.beam</c>.</p>
</desc>
</func>
<func>
<name name="stick_dir" arity="1" since=""/>
<fsummary>Mark a directory as sticky.</fsummary>
<desc>
<p>Marks <c><anno>Dir</anno></c> as sticky.</p>
<p>Returns <c>ok</c> if successful, otherwise <c>error</c>.</p>
</desc>
</func>
<func>
<name name="unstick_dir" arity="1" since=""/>
<fsummary>Remove a sticky directory mark.</fsummary>
<desc>
<p>Unsticks a directory that is marked as
sticky.</p>
<p>Returns <c>ok</c> if successful, otherwise <c>error</c>.</p>
</desc>
</func>
<func>
<name name="is_sticky" arity="1" since=""/>
<fsummary>Test if a module is sticky.</fsummary>
<desc>
<p>Returns <c>true</c> if <c><anno>Module</anno></c> is the
name of a module that has been loaded from a sticky directory
(in other words: an attempt to reload the module will fail),
or <c>false</c> if <c><anno>Module</anno></c> is not a loaded module or is
not sticky.</p>
</desc>
</func>
<func>
<name name="where_is_file" arity="1" since=""/>
<fsummary>Full name of a file located in the code path.</fsummary>
<desc>
<p>Searches the code path for <c><anno>Filename</anno></c>, a file of
arbitrary type. If found, the full name is returned.
<c>non_existing</c> is returned if the file cannot be found.
The function can be useful, for example, to locate
application resource files.</p>
</desc>
</func>
<func>
<name name="clash" arity="0" since=""/>
<fsummary>Search for modules with identical names.</fsummary>
<desc>
<p>Searches all directories in the code path for module names with
identical names and writes a report to <c>stdout</c>.</p>
</desc>
</func>
<func>
<name name="module_status" arity="0" since="OTP 23.0"/>
<fsummary>Return the statuses of all loaded modules.</fsummary>
<type name="module_status"/>
<desc>
<p>See <seemfa marker="#module_status/1"><c>module_status/1</c></seemfa> and <seemfa marker="#all_loaded/0"><c>all_loaded/0</c></seemfa> for details.</p>
</desc>
</func>
<func>
<name name="module_status" arity="1" since="OTP 20.0"/>
<fsummary>Return the status of a module or modules in relation to the
object files on disk.</fsummary>
<type name="module_status"/>
<desc>
<p>The status of a module can be one of:</p>
<taglist>
<tag><c>not_loaded</c></tag>
<item><p>If <c><anno>Module</anno></c> is not currently loaded.</p></item>
<tag><c>loaded</c></tag>
<item><p>If <c><anno>Module</anno></c> is loaded and the object file
exists and contains the same code.</p></item>
<tag><c>removed</c></tag>
<item><p>If <c><anno>Module</anno></c> is loaded but no
corresponding object file can be found in the code path.</p></item>
<tag><c>modified</c></tag>
<item><p>If <c><anno>Module</anno></c> is loaded but the object file
contains code with a different MD5 checksum.</p></item>
</taglist>
<p>Preloaded modules are always reported as <c>loaded</c>, without
inspecting the contents on disk. Cover compiled modules will always
be reported as <c>modified</c> if an object file exists, or as
<c>removed</c> otherwise. Modules whose load path is an empty string
(which is the convention for auto-generated code) will only be
reported as <c>loaded</c> or <c>not_loaded</c>.</p>
<p>See also <seemfa marker="#modified_modules/0"><c>modified_modules/0</c></seemfa>.</p>
</desc>
</func>
<func>
<name name="modified_modules" arity="0" since="OTP 20.0"/>
<fsummary>Return a list of all modules modified on disk.</fsummary>
<desc>
<p>Returns the list of all currently loaded modules for which
<seemfa marker="#module_status/1"><c>module_status/1</c></seemfa>
returns <c>modified</c>. See also <seemfa marker="#all_loaded/0"><c>all_loaded/0</c></seemfa>.</p>
</desc>
</func>
<func>
<name name="is_module_native" arity="1" since=""/>
<fsummary>Test if a module has native code.</fsummary>
<desc>
<p>Returns <c>false</c> if the given <c><anno>Module</anno></c> is
loaded, and <c>undefined</c> if it is not.</p>
<warning><p>This function is deprecated and will be removed in a future
release.</p></warning>
</desc>
</func>
<func>
<name name="get_mode" arity="0" since="OTP R16B"/>
<fsummary>The mode of the code server.</fsummary>
<desc>
<p>Returns an atom describing the mode of the code server:
<c>interactive</c> or <c>embedded</c>.</p>
<p>This information is useful when an external entity (for example,
an IDE) provides additional code for a running node. If the code server is
in interactive mode, it only has to add the path to the code. If the code server
is in embedded mode, the code must be loaded with
<seemfa marker="#load_binary/3"><c>load_binary/3</c></seemfa>.</p>
</desc>
</func>
</funcs>
</erlref>
|