1code(3) Erlang Module Definition code(3)
2
3
4
6 code - Erlang code server.
7
9 This module contains the interface to the Erlang code server, which
10 deals with the loading of compiled code into a running Erlang runtime
11 system.
12
13 The runtime system can be started in interactive or embedded mode.
14 Which one is decided by the command-line flag -mode:
15
16 % erl -mode interactive
17
18 The modes are as follows:
19
20 * In interactive mode, which is default, only some code is loaded
21 during system startup, basically the modules needed by the runtime
22 system. Other code is dynamically loaded when first referenced.
23 When a call to a function in a certain module is made, and the mod‐
24 ule is not loaded, the code server searches for and tries to load
25 the module.
26
27 * In embedded mode, modules are not auto loaded. Trying to use a mod‐
28 ule that has not been loaded results in an error. This mode is rec‐
29 ommended when the boot script loads all modules, as it is typically
30 done in OTP releases. (Code can still be loaded later by explicitly
31 ordering the code server to do so).
32
33 To prevent accidentally reloading of modules affecting the Erlang run‐
34 time system, directories kernel, stdlib, and compiler are considered
35 sticky. This means that the system issues a warning and rejects the re‐
36 quest if a user tries to reload a module residing in any of them. The
37 feature can be disabled by using command-line flag -nostick.
38
40 In interactive mode, the code server maintains a search path, usually
41 called the code path, consisting of a list of directories, which it
42 searches sequentially when trying to load a module.
43
44 Initially, the code path consists of the current working directory and
45 all Erlang object code directories under library directory $OTP‐
46 ROOT/lib, where $OTPROOT is the installation directory of Erlang/OTP,
47 code:root_dir(). Directories can be named Name[-Vsn] and the code
48 server, by default, chooses the directory with the highest version num‐
49 ber among those having the same Name. Suffix -Vsn is optional. If an
50 ebin directory exists under Name[-Vsn], this directory is added to the
51 code path.
52
53 Environment variable ERL_LIBS (defined in the operating system) can be
54 used to define more library directories to be handled in the same way
55 as the standard OTP library directory described above, except that di‐
56 rectories without an ebin directory are ignored.
57
58 All application directories found in the additional directories appear
59 before the standard OTP applications, except for the Kernel and STDLIB
60 applications, which are placed before any additional applications. In
61 other words, modules found in any of the additional library directories
62 override modules with the same name in OTP, except for modules in Ker‐
63 nel and STDLIB.
64
65 Environment variable ERL_LIBS (if defined) is to contain a colon-sepa‐
66 rated (for Unix-like systems) or semicolon-separated (for Windows) list
67 of additional libraries.
68
69 Example:
70
71 On a Unix-like system, ERL_LIBS can be set to the following
72
73 /usr/local/jungerl:/home/some_user/my_erlang_lib
74
75 On Windows, use semi-colon as separator.
76
77 The code paths specified by $OTPROOT, ERL_LIBS, and boot scripts have
78 their listings cached by default (except for ".") since OTP 26.0. The
79 code server will lookup the contents in their directories once and
80 avoid future file system traversals. Therefore modules added to such
81 directories after the Erlang VM boots won't be picked up. You can dis‐
82 able this behaviour by setting -cache_boot_paths false or by calling
83 code:set_path(code:get_path()).
84
85 The functions in this module and the command line options -pa and -pz
86 are not cached by default. However, many of the functions that manipu‐
87 late the code path accept the cache atom as an optional argument, which
88 will enable caching on selected paths.
89
91 Warning:
92 The support for loading code from archive files is experimental. The
93 purpose of releasing it before it is ready is to obtain early feedback.
94 The file format, semantics, interfaces, and so on, can be changed in a
95 future release. The function lib_dir/2 and flag -code_path_choice are
96 also experimental.
97
98
99 The Erlang archives are ZIP files with extension .ez. Erlang archives
100 can also be enclosed in escript files whose file extension is arbi‐
101 trary.
102
103 Erlang archive files can contain entire Erlang applications or parts of
104 applications. The structure in an archive file is the same as the di‐
105 rectory structure for an application. If you, for example, create an
106 archive of mnesia-4.4.7, the archive file must be named mnesia-4.4.7.ez
107 and it must contain a top directory named mnesia-4.4.7. If the version
108 part of the name is omitted, it must also be omitted in the archive.
109 That is, a mnesia.ez archive must contain a mnesia top directory.
110
111 An archive file for an application can, for example, be created like
112 this:
113
114 zip:create("mnesia-4.4.7.ez",
115 ["mnesia-4.4.7"],
116 [{cwd, code:lib_dir()},
117 {compress, all},
118 {uncompress,[".beam",".app"]}]).
119
120 Any file in the archive can be compressed, but to speed up the access
121 of frequently read files, it can be a good idea to store beam and app
122 files uncompressed in the archive.
123
124 Normally the top directory of an application is located in library di‐
125 rectory $OTPROOT/lib or in a directory referred to by environment vari‐
126 able ERL_LIBS. At startup, when the initial code path is computed, the
127 code server also looks for archive files in these directories and pos‐
128 sibly adds ebin directories in archives to the code path. The code path
129 then contains paths to directories that look like $OTPROOT/lib/mne‐
130 sia.ez/mnesia/ebin or $OTPROOT/lib/mnesia-4.4.7.ez/mnesia-4.4.7/ebin.
131
132 The code server uses module erl_prim_loader in ERTS (possibly through
133 erl_boot_server) to read code files from archives. However, the func‐
134 tions in erl_prim_loader can also be used by other applications to read
135 files from archives. For example, the call erl_prim_loader:list_dir(
136 "/otp/root/lib/mnesia-4.4.7.ez/mnesia-4.4.7/examples/bench)" would list
137 the contents of a directory inside an archive. See erl_prim_loader(3).
138
139 An application archive file and a regular application directory can co‐
140 exist. This can be useful when it is needed to have parts of the appli‐
141 cation as regular files. A typical case is the priv directory, which
142 must reside as a regular directory to link in drivers dynamically and
143 start port programs. For other applications that do not need this, di‐
144 rectory priv can reside in the archive and the files under the direc‐
145 tory priv can be read through erl_prim_loader.
146
147 When a directory is added to the code path and when the entire code
148 path is (re)set, the code server decides which subdirectories in an ap‐
149 plication that are to be read from the archive and which that are to be
150 read as regular files. If directories are added or removed afterwards,
151 the file access can fail if the code path is not updated (possibly to
152 the same path as before, to trigger the directory resolution update).
153
154 For each directory on the second level in the application archive
155 (ebin, priv, src, and so on), the code server first chooses the regular
156 directory if it exists and second from the archive. Function
157 code:lib_dir/2 returns the path to the subdirectory. For example,
158 code:lib_dir(megaco,ebin) can return
159 /otp/root/lib/megaco-3.9.1.1.ez/megaco-3.9.1.1/ebin while
160 code:lib_dir(megaco,priv) can return /otp/root/lib/megaco-3.9.1.1/priv.
161
162 When an escript file contains an archive, there are no restrictions on
163 the name of the escript and no restrictions on how many applications
164 that can be stored in the embedded archive. Single Beam files can also
165 reside on the top level in the archive. At startup, the top directory
166 in the embedded archive and all (second level) ebin directories in the
167 embedded archive are added to the code path. See erts:escript(1).
168
169 When the choice of directories in the code path is strict, the direc‐
170 tory that ends up in the code path is exactly the stated one. This
171 means that if, for example, the directory $OTPROOT/lib/mne‐
172 sia-4.4.7/ebin is explicitly added to the code path, the code server
173 does not load files from $OTPROOT/lib/mnesia-4.4.7.ez/mne‐
174 sia-4.4.7/ebin.
175
176 This behavior can be controlled through command-line flag
177 -code_path_choice Choice. If the flag is set to relaxed, the code
178 server instead chooses a suitable directory depending on the actual
179 file structure. If a regular application ebin directory exists, it is
180 chosen. Otherwise, the directory ebin in the archive is chosen if it
181 exists. If neither of them exists, the original directory is chosen.
182
183 Command-line flag -code_path_choice Choice also affects how module init
184 interprets the boot script. The interpretation of the explicit code
185 paths in the boot script can be strict or relaxed. It is particularly
186 useful to set the flag to relaxed when elaborating with code loading
187 from archives without editing the boot script. The default is relaxed.
188 See erts:init(3).
189
191 The code for a module can exist in two variants in a system: current
192 code and old code. When a module is loaded into the system for the
193 first time, the module code becomes 'current' and the global export ta‐
194 ble is updated with references to all functions exported from the mod‐
195 ule.
196
197 If then a new instance of the module is loaded (for example, because of
198 error correction), the code of the previous instance becomes 'old', and
199 all export entries referring to the previous instance are removed. Af‐
200 ter that, the new instance is loaded as for the first time, and becomes
201 'current'.
202
203 Both old and current code for a module are valid, and can even be eval‐
204 uated concurrently. The difference is that exported functions in old
205 code are unavailable. Hence, a global call cannot be made to an ex‐
206 ported function in old code, but old code can still be evaluated be‐
207 cause of processes lingering in it.
208
209 If a third instance of the module is loaded, the code server removes
210 (purges) the old code and any processes lingering in it are terminated.
211 Then the third instance becomes 'current' and the previously current
212 code becomes 'old'.
213
214 For more information about old and current code, and how to make a
215 process switch from old to current code, see section Compilation and
216 Code Loading in the Erlang Reference Manual.
217
219 Module and application names are atoms, while file and directory names
220 are strings. For backward compatibility reasons, some functions accept
221 both strings and atoms, but a future release will probably only allow
222 the arguments that are documented.
223
224 Functions in this module generally fail with an exception if they are
225 passed an incorrect type (for example, an integer or a tuple where an
226 atom is expected). An error tuple is returned if the argument type is
227 correct, but there are some other errors (for example, a non-existing
228 directory is specified to set_path/1).
229
231 Functions that load code (such as load_file/1) will return {error,Rea‐
232 son} if the load operation fails. Here follows a description of the
233 common reasons.
234
235 badfile:
236 The object code has an incorrect format or the module name in the
237 object code is not the expected module name.
238
239 nofile:
240 No file with object code was found.
241
242 not_purged:
243 The object code could not be loaded because an old version of the
244 code already existed.
245
246 on_load_failure:
247 The module has an -on_load function that failed when it was called.
248
249 sticky_directory:
250 The object code resides in a sticky directory.
251
253 add_path_ret() = true | {error, bad_directory}
254
255 cache() = cache | nocache
256
257 load_ret() =
258 {error, What :: load_error_rsn()} |
259 {module, Module :: module()}
260
261 load_error_rsn() =
262 badfile | nofile | not_purged | on_load_failure |
263 sticky_directory
264
265 module_status() = not_loaded | loaded | modified | removed
266
267 prepared_code()
268
269 An opaque term holding prepared code.
270
271 replace_path_ret() =
272 true | {error, bad_directory | bad_name | {badarg, term()}}
273
274 set_path_ret() = true | {error, bad_directory}
275
277 set_path(Path) -> set_path_ret()
278
279 set_path(Path, Cache :: cache()) -> set_path_ret()
280
281 Types:
282
283 Path = [Dir :: file:filename()]
284
285 Sets the code path to the list of directories Path.
286
287 An optional second argument may be set to the atom cache to con‐
288 trol if the contents of the directory must be cached on first
289 traversal. Defaults to nocache.
290
291 Returns:
292
293 true:
294 If successful
295
296 {error, bad_directory}:
297 If any Dir is not a directory name
298
299 get_path() -> Path
300
301 Types:
302
303 Path = [Dir :: file:filename()]
304
305 Returns the code path.
306
307 add_path(Dir) -> add_path_ret()
308
309 add_path(Dir, Cache :: cache()) -> add_path_ret()
310
311 add_pathz(Dir) -> add_path_ret()
312
313 add_pathz(Dir, Cache :: cache()) -> add_path_ret()
314
315 Types:
316
317 Dir = file:filename()
318 add_path_ret() = true | {error, bad_directory}
319
320 Adds Dir to the code path. The directory is added as the last
321 directory in the new path. If Dir already exists in the path, it
322 is not added.
323
324 An optional second argument may be set to the atom cache to con‐
325 trol if the contents of the directory must be cached on first
326 traversal. Defaults to nocache.
327
328 Returns true if successful, or {error, bad_directory} if Dir is
329 not the name of a directory.
330
331 add_patha(Dir) -> add_path_ret()
332
333 add_patha(Dir, Cache :: cache()) -> add_path_ret()
334
335 Types:
336
337 Dir = file:filename()
338 add_path_ret() = true | {error, bad_directory}
339
340 Adds Dir to the beginning of the code path. If Dir exists, it is
341 removed from the old position in the code path.
342
343 An optional second argument may be set to the atom cache to con‐
344 trol if the contents of the directory must be cached on first
345 traversal. Defaults to nocache.
346
347 Returns true if successful, or {error, bad_directory} if Dir is
348 not the name of a directory.
349
350 add_paths(Dirs) -> ok
351
352 add_paths(Dirs, Cache :: cache()) -> ok
353
354 add_pathsz(Dirs) -> ok
355
356 add_pathsz(Dirs, Cache :: cache()) -> ok
357
358 Types:
359
360 Dirs = [Dir :: file:filename()]
361
362 Adds the directories in Dirs to the end of the code path. If a
363 Dir exists, it is not added.
364
365 An optional second argument may be set to the atom cache to con‐
366 trol if the contents of the directory must be cached on first
367 traversal. Defaults to nocache.
368
369 Always returns ok, regardless of the validity of each individual
370 Dir.
371
372 add_pathsa(Dirs) -> ok
373
374 add_pathsa(Dirs, Cache :: cache()) -> ok
375
376 Types:
377
378 Dirs = [Dir :: file:filename()]
379
380 Traverses Dirs and adds each Dir to the beginning of the code
381 path. This means that the order of Dirs is reversed in the re‐
382 sulting code path. For example, if you add [Dir1,Dir2], the re‐
383 sulting path will be [Dir2,Dir1|OldCodePath].
384
385 If a Dir already exists in the code path, it is removed from the
386 old position.
387
388 An optional second argument may be set to the atom cache to con‐
389 trol if the contents of the directory must be cached on first
390 traversal. Defaults to nocache.
391
392 Always returns ok, regardless of the validity of each individual
393 Dir.
394
395 del_path(NameOrDir) -> boolean() | {error, What}
396
397 Types:
398
399 NameOrDir = Name | Dir
400 Name = atom()
401 Dir = file:filename()
402 What = bad_name
403
404 Deletes a directory from the code path. The argument can be an
405 atom Name, in which case the directory with the name
406 .../Name[-Vsn][/ebin] is deleted from the code path. Also, the
407 complete directory name Dir can be specified as argument.
408
409 Returns:
410
411 true:
412 If successful
413
414 false:
415 If the directory is not found
416
417 {error, bad_name}:
418 If the argument is invalid
419
420 del_paths(NamesOrDirs) -> ok
421
422 Types:
423
424 NamesOrDirs = [Name | Dir]
425 Name = atom()
426 Dir = file:filename()
427
428 Deletes directories from the code path. The argument is a list
429 of either atoms or complete directory names. If an atom Name,
430 the directory with the name .../Name[-Vsn][/ebin] is deleted
431 from the code path.
432
433 Always returns ok, regardless of the validity of each individual
434 NamesOrDirs.
435
436 clear_cache() -> ok
437
438 Clear the code path cache. If a directory is cached, its cache
439 is cleared once and then it will be recalculated and cached once
440 more in a future traversal.
441
442 If you want to clear the cache for a single path, you might re-
443 add it to the code path (with add_path/2) or replace it (with
444 replace_path/3). If you want to disable all cache, you can reset
445 the code path with code:set_path(code:get_path()).
446
447 Always returns ok.
448
449 replace_path(Name, Dir) -> replace_path_ret()
450
451 replace_path(Name, Dir, Cache :: cache()) -> replace_path_ret()
452
453 Types:
454
455 Name = atom()
456 Dir = file:filename()
457
458 Replaces an old occurrence of a directory named
459 .../Name[-Vsn][/ebin] in the code path, with Dir. If Name does
460 not exist, it adds the new directory Dir last in the code path.
461 The new directory must also be named .../Name[-Vsn][/ebin]. This
462 function is to be used if a new version of the directory (li‐
463 brary) is added to a running system.
464
465 An optional third argument may be set to the atom cache to con‐
466 trol if the contents of the directory must be cached on first
467 traversal. Defaults to nocache.
468
469 Returns:
470
471 true:
472 If successful
473
474 {error, bad_name}:
475 If Name is not found
476
477 {error, bad_directory}:
478 If Dir does not exist
479
480 {error, {badarg, [Name, Dir]}}:
481 If Name or Dir is invalid
482
483 load_file(Module) -> load_ret()
484
485 Types:
486
487 Module = module()
488 load_ret() =
489 {error, What :: load_error_rsn()} |
490 {module, Module :: module()}
491
492 Tries to load the Erlang module Module, using the code path. It
493 looks for the object code file with an extension corresponding
494 to the Erlang machine used, for example, Module.beam. The load‐
495 ing fails if the module name found in the object code differs
496 from the name Module. load_binary/3 must be used to load object
497 code with a module name that is different from the file name.
498
499 Returns {module, Module} if successful, or {error, Reason} if
500 loading fails. See Error Reasons for Code-Loading Functions for
501 a description of the possible error reasons.
502
503 load_abs(Filename) -> load_ret()
504
505 Types:
506
507 Filename = file:filename()
508 load_ret() =
509 {error, What :: load_error_rsn()} |
510 {module, Module :: module()}
511 loaded_filename() =
512 (Filename :: file:filename()) | loaded_ret_atoms()
513 loaded_ret_atoms() = cover_compiled | preloaded
514
515 Same as load_file(Module), but Filename is an absolute or rela‐
516 tive filename. The code path is not searched. It returns a value
517 in the same way as load_file/1. Notice that Filename must not
518 contain the extension (for example, .beam) because load_abs/1
519 adds the correct extension.
520
521 ensure_loaded(Module) -> {module, Module} | {error, What}
522
523 Types:
524
525 Module = module()
526 What = embedded | badfile | nofile | on_load_failure
527
528 Tries to load a module in the same way as load_file/1, unless
529 the module is already loaded. However, in embedded mode it does
530 not load a module that is not already loaded, but returns {er‐
531 ror, embedded} instead. See Error Reasons for Code-Loading Func‐
532 tions for a description of other possible error reasons.
533
534 load_binary(Module, Filename, Binary) ->
535 {module, Module} | {error, What}
536
537 Types:
538
539 Module = module()
540 Filename = loaded_filename()
541 Binary = binary()
542 What = badarg | load_error_rsn()
543 loaded_filename() =
544 (Filename :: file:filename()) | loaded_ret_atoms()
545 loaded_ret_atoms() = cover_compiled | preloaded
546
547 This function can be used to load object code on remote Erlang
548 nodes. Argument Binary must contain object code for Module.
549 Filename is only used by the code server to keep a record of
550 from which file the object code for Module comes. Thus, Filename
551 is not opened and read by the code server.
552
553 Returns {module, Module} if successful, or {error, Reason} if
554 loading fails. See Error Reasons for Code-Loading Functions for
555 a description of the possible error reasons.
556
557 atomic_load(Modules) -> ok | {error, [{Module, What}]}
558
559 Types:
560
561 Modules = [Module | {Module, Filename, Binary}]
562 Module = module()
563 Filename = file:filename()
564 Binary = binary()
565 What =
566 badfile | nofile | on_load_not_allowed | duplicated |
567 not_purged | sticky_directory | pending_on_load
568
569 Tries to load all of the modules in the list Modules atomically.
570 That means that either all modules are loaded at the same time,
571 or none of the modules are loaded if there is a problem with any
572 of the modules.
573
574 Loading can fail for one the following reasons:
575
576 badfile:
577 The object code has an incorrect format or the module name
578 in the object code is not the expected module name.
579
580 nofile:
581 No file with object code exists.
582
583 on_load_not_allowed:
584 A module contains an -on_load function.
585
586 duplicated:
587 A module is included more than once in Modules.
588
589 not_purged:
590 The object code cannot be loaded because an old version of
591 the code already exists.
592
593 sticky_directory:
594 The object code resides in a sticky directory.
595
596 pending_on_load:
597 A previously loaded module contains an -on_load function
598 that never finished.
599
600 If it is important to minimize the time that an application is
601 inactive while changing code, use prepare_loading/1 and fin‐
602 ish_loading/1 instead of atomic_load/1. Here is an example:
603
604 {ok,Prepared} = code:prepare_loading(Modules),
605 %% Put the application into an inactive state or do any
606 %% other preparation needed before changing the code.
607 ok = code:finish_loading(Prepared),
608 %% Resume the application.
609
610 prepare_loading(Modules) ->
611 {ok, Prepared} | {error, [{Module, What}]}
612
613 Types:
614
615 Modules = [Module | {Module, Filename, Binary}]
616 Module = module()
617 Filename = file:filename()
618 Binary = binary()
619 Prepared = prepared_code()
620 What = badfile | nofile | on_load_not_allowed | duplicated
621
622 Prepares to load the modules in the list Modules. Finish the
623 loading by calling finish_loading(Prepared).
624
625 This function can fail with one of the following error reasons:
626
627 badfile:
628 The object code has an incorrect format or the module name
629 in the object code is not the expected module name.
630
631 nofile:
632 No file with object code exists.
633
634 on_load_not_allowed:
635 A module contains an -on_load function.
636
637 duplicated:
638 A module is included more than once in Modules.
639
640 finish_loading(Prepared) -> ok | {error, [{Module, What}]}
641
642 Types:
643
644 Prepared = prepared_code()
645 Module = module()
646 What = not_purged | sticky_directory | pending_on_load
647
648 Tries to load code for all modules that have been previously
649 prepared by prepare_loading/1. The loading occurs atomically,
650 meaning that either all modules are loaded at the same time, or
651 none of the modules are loaded.
652
653 This function can fail with one of the following error reasons:
654
655 not_purged:
656 The object code cannot be loaded because an old version of
657 the code already exists.
658
659 sticky_directory:
660 The object code resides in a sticky directory.
661
662 pending_on_load:
663 A previously loaded module contains an -on_load function
664 that never finished.
665
666 ensure_modules_loaded(Modules :: [Module]) ->
667 ok | {error, [{Module, What}]}
668
669 Types:
670
671 Module = module()
672 What = badfile | nofile | on_load_failure
673
674 Tries to load any modules not already loaded in the list Modules
675 in the same way as load_file/1.
676
677 Returns ok if successful, or {error,[{Module,Reason}]} if load‐
678 ing of some modules fails. See Error Reasons for Code-Loading
679 Functions for a description of other possible error reasons.
680
681 delete(Module) -> boolean()
682
683 Types:
684
685 Module = module()
686
687 Removes the current code for Module, that is, the current code
688 for Module is made old. This means that processes can continue
689 to execute the code in the module, but no external function
690 calls can be made to it.
691
692 Returns true if successful, or false if there is old code for
693 Module that must be purged first, or if Module is not a (loaded)
694 module.
695
696 purge(Module) -> boolean()
697
698 Types:
699
700 Module = module()
701
702 Purges the code for Module, that is, removes code marked as old.
703 If some processes still linger in the old code, these processes
704 are killed before the code is removed.
705
706 Note:
707 As of ERTS version 9.0, a process is only considered to be lin‐
708 gering in the code if it has direct references to the code. For
709 more information see documentation of er‐
710 lang:check_process_code/3, which is used in order to determine
711 this.
712
713
714 Returns true if successful and any process is needed to be
715 killed, otherwise false.
716
717 soft_purge(Module) -> boolean()
718
719 Types:
720
721 Module = module()
722
723 Purges the code for Module, that is, removes code marked as old,
724 but only if no processes linger in it.
725
726 Note:
727 As of ERTS version 9.0, a process is only considered to be lin‐
728 gering in the code if it has direct references to the code. For
729 more information see documentation of er‐
730 lang:check_process_code/3, which is used in order to determine
731 this.
732
733
734 Returns false if the module cannot be purged because of pro‐
735 cesses lingering in old code, otherwise true.
736
737 is_loaded(Module) -> {file, Loaded} | false
738
739 Types:
740
741 Module = module()
742 Loaded = loaded_filename()
743 loaded_filename() =
744 (Filename :: file:filename()) | loaded_ret_atoms()
745 Filename is an absolute filename.
746 loaded_ret_atoms() = cover_compiled | preloaded
747
748 Checks if Module is loaded. If it is, {file, Loaded} is re‐
749 turned, otherwise false.
750
751 Normally, Loaded is the absolute filename Filename from which
752 the code is obtained. If the module is preloaded (see
753 script(4)), Loaded==preloaded. If the module is Cover-compiled
754 (see cover(3)), Loaded==cover_compiled.
755
756 all_available() -> [{Module, Filename, Loaded}]
757
758 Types:
759
760 Module = string()
761 Filename = loaded_filename()
762 Loaded = boolean()
763 loaded_filename() =
764 (Filename :: file:filename()) | loaded_ret_atoms()
765 Filename is an absolute filename.
766 loaded_ret_atoms() = cover_compiled | preloaded
767
768 Returns a list of tuples {Module, Filename, Loaded} for all
769 available modules. A module is considered to be available if it
770 either is loaded or would be loaded if called. Filename is nor‐
771 mally the absolute filename, as described for is_loaded/1.
772
773 all_loaded() -> [{Module, Loaded}]
774
775 Types:
776
777 Module = module()
778 Loaded = loaded_filename()
779 loaded_filename() =
780 (Filename :: file:filename()) | loaded_ret_atoms()
781 Filename is an absolute filename.
782 loaded_ret_atoms() = cover_compiled | preloaded
783
784 Returns a list of tuples {Module, Loaded} for all loaded mod‐
785 ules. Loaded is normally the absolute filename, as described for
786 is_loaded/1.
787
788 which(Module) -> Which
789
790 Types:
791
792 Module = module()
793 Which = loaded_filename() | non_existing
794 loaded_filename() =
795 (Filename :: file:filename()) | loaded_ret_atoms()
796 loaded_ret_atoms() = cover_compiled | preloaded
797
798 If the module is not loaded, this function searches the code
799 path for the first file containing object code for Module and
800 returns the absolute filename.
801
802 If the module is loaded, it returns the name of the file con‐
803 taining the loaded object code.
804
805 If the module is preloaded, preloaded is returned.
806
807 If the module is Cover-compiled, cover_compiled is returned.
808
809 If the module cannot be found, non_existing is returned.
810
811 get_object_code(Module) -> {Module, Binary, Filename} | error
812
813 Types:
814
815 Module = module()
816 Binary = binary()
817 Filename = file:filename()
818
819 Searches the code path for the object code of module Module. Re‐
820 turns {Module, Binary, Filename} if successful, otherwise error.
821 Binary is a binary data object, which contains the object code
822 for the module. This can be useful if code is to be loaded on a
823 remote node in a distributed system. For example, loading module
824 Module on a node Node is done as follows:
825
826 {_Module, Binary, Filename} = code:get_object_code(Module),
827 rpc:call(Node, code, load_binary, [Module, Filename, Binary]),
828
829 get_doc(Mod) -> {ok, Res} | {error, Reason}
830
831 Types:
832
833 Mod = module()
834 Res = #docs_v1{}
835 Reason = non_existing | missing | file:posix()
836
837 Searches the code path for EEP-48 style documentation and re‐
838 turns it if available. If no documentation can be found the
839 function tries to generate documentation from the debug informa‐
840 tion in the module. If no debug information is available, this
841 function will return {error,missing}.
842
843 For more information about the documentation chunk see Documen‐
844 tation Storage and Format in Kernel's User's Guide.
845
846 root_dir() -> file:filename()
847
848 Returns the root directory of Erlang/OTP, which is the directory
849 where it is installed.
850
851 Example:
852
853 > code:root_dir().
854 "/usr/local/otp"
855
856 lib_dir() -> file:filename()
857
858 Returns the library directory, $OTPROOT/lib, where $OTPROOT is
859 the root directory of Erlang/OTP.
860
861 Example:
862
863 > code:lib_dir().
864 "/usr/local/otp/lib"
865
866 lib_dir(Name) -> file:filename() | {error, bad_name}
867
868 Types:
869
870 Name = atom()
871
872 Returns the path for the "library directory", the top directory,
873 for an application Name located under $OTPROOT/lib or on a di‐
874 rectory referred to with environment variable ERL_LIBS.
875
876 If a regular directory called Name or Name-Vsn exists in the
877 code path with an ebin subdirectory, the path to this directory
878 is returned (not the ebin directory).
879
880 If the directory refers to a directory in an archive, the ar‐
881 chive name is stripped away before the path is returned. For ex‐
882 ample, if directory /usr/local/otp/lib/mnesia-4.2.2.ez/mne‐
883 sia-4.2.2/ebin is in the path, /usr/local/otp/lib/mne‐
884 sia-4.2.2/ebin is returned. This means that the library direc‐
885 tory for an application is the same, regardless if the applica‐
886 tion resides in an archive or not.
887
888 Example:
889
890 > code:lib_dir(mnesia).
891 "/usr/local/otp/lib/mnesia-4.2.2"
892
893 Returns {error, bad_name} if Name is not the name of an applica‐
894 tion under $OTPROOT/lib or on a directory referred to through
895 environment variable ERL_LIBS. Fails with an exception if Name
896 has the wrong type.
897
898 Warning:
899 For backward compatibility, Name is also allowed to be a string.
900 That will probably change in a future release.
901
902
903 lib_dir(Name, SubDir) -> file:filename() | {error, bad_name}
904
905 Types:
906
907 Name = SubDir = atom()
908
909 Returns the path to a subdirectory directly under the top direc‐
910 tory of an application. Normally the subdirectories reside under
911 the top directory for the application, but when applications at
912 least partly reside in an archive, the situation is different.
913 Some of the subdirectories can reside as regular directories
914 while others reside in an archive file. It is not checked
915 whether this directory exists.
916
917 Example:
918
919 > code:lib_dir(megaco, priv).
920 "/usr/local/otp/lib/megaco-3.9.1.1/priv"
921
922 Fails with an exception if Name or SubDir has the wrong type.
923
924 compiler_dir() -> file:filename()
925
926 Returns the compiler library directory. Equivalent to
927 code:lib_dir(compiler).
928
929 priv_dir(Name) -> file:filename() | {error, bad_name}
930
931 Types:
932
933 Name = atom()
934
935 Returns the path to the priv directory in an application. Equiv‐
936 alent to code:lib_dir(Name, priv).
937
938 Warning:
939 For backward compatibility, Name is also allowed to be a string.
940 That will probably change in a future release.
941
942
943 objfile_extension() -> nonempty_string()
944
945 Returns the object code file extension corresponding to the Er‐
946 lang machine used, namely .beam.
947
948 stick_dir(Dir) -> ok | error
949
950 Types:
951
952 Dir = file:filename()
953
954 Marks Dir as sticky.
955
956 Returns ok if successful, otherwise error.
957
958 unstick_dir(Dir) -> ok | error
959
960 Types:
961
962 Dir = file:filename()
963
964 Unsticks a directory that is marked as sticky.
965
966 Returns ok if successful, otherwise error.
967
968 is_sticky(Module) -> boolean()
969
970 Types:
971
972 Module = module()
973
974 Returns true if Module is the name of a module that has been
975 loaded from a sticky directory (in other words: an attempt to
976 reload the module will fail), or false if Module is not a loaded
977 module or is not sticky.
978
979 where_is_file(Filename) -> non_existing | Absname
980
981 Types:
982
983 Filename = Absname = file:filename()
984
985 Searches the code path for Filename, a file of arbitrary type.
986 If found, the full name is returned. non_existing is returned if
987 the file cannot be found. The function can be useful, for exam‐
988 ple, to locate application resource files.
989
990 clash() -> ok
991
992 Searches all directories in the code path for module names with
993 identical names and writes a report to stdout.
994
995 module_status() -> [{module(), module_status()}]
996
997 Types:
998
999 module_status() = not_loaded | loaded | modified | removed
1000
1001 See module_status/1 and all_loaded/0 for details.
1002
1003 module_status(Module :: module() | [module()]) ->
1004 module_status() | [{module(), module_status()}]
1005
1006 Types:
1007
1008 module_status() = not_loaded | loaded | modified | removed
1009
1010 The status of a module can be one of:
1011
1012 not_loaded:
1013 If Module is not currently loaded.
1014
1015 loaded:
1016 If Module is loaded and the object file exists and contains
1017 the same code.
1018
1019 removed:
1020 If Module is loaded but no corresponding object file can be
1021 found in the code path.
1022
1023 modified:
1024 If Module is loaded but the object file contains code with a
1025 different MD5 checksum.
1026
1027 Preloaded modules are always reported as loaded, without in‐
1028 specting the contents on disk. Cover compiled modules will al‐
1029 ways be reported as modified if an object file exists, or as re‐
1030 moved otherwise. Modules whose load path is an empty string
1031 (which is the convention for auto-generated code) will only be
1032 reported as loaded or not_loaded.
1033
1034 See also modified_modules/0.
1035
1036 modified_modules() -> [module()]
1037
1038 Returns the list of all currently loaded modules for which mod‐
1039 ule_status/1 returns modified. See also all_loaded/0.
1040
1041 get_mode() -> embedded | interactive
1042
1043 Returns an atom describing the mode of the code server: interac‐
1044 tive or embedded.
1045
1046 This information is useful when an external entity (for example,
1047 an IDE) provides additional code for a running node. If the code
1048 server is in interactive mode, it only has to add the path to
1049 the code. If the code server is in embedded mode, the code must
1050 be loaded with load_binary/3.
1051
1052
1053
1054Ericsson AB kernel 9.1 code(3)