1code(3) Erlang Module Definition code(3)
2
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 The runtime system can be started in interactive or embedded mode.
14 Which one is decided by the command-line flag -mode:
15 % erl -mode interactive
17 The modes are as follows:
19 * 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 * 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 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
36 request 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 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 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
56 directories without an ebin directory are ignored.
57 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 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 Example:
70 On a Unix-like system, ERL_LIBS can be set to the following
72 /usr/local/jungerl:/home/some_user/my_erlang_lib
74 On Windows, use semi-colon as separator.
76
78 Warning:
79 The support for loading code from archive files is experimental. The
80 purpose of releasing it before it is ready is to obtain early feedback.
81 The file format, semantics, interfaces, and so on, can be changed in a
82 future release. The function lib_dir/2 and flag -code_path_choice are
83 also experimental.
84 The Erlang archives are ZIP files with extension .ez. Erlang archives
87 can also be enclosed in escript files whose file extension is arbi‐
88 trary.
89 Erlang archive files can contain entire Erlang applications or parts of
91 applications. The structure in an archive file is the same as the
92 directory structure for an application. If you, for example, create an
93 archive of mnesia-4.4.7, the archive file must be named mnesia-4.4.7.ez
94 and it must contain a top directory named mnesia-4.4.7. If the version
95 part of the name is omitted, it must also be omitted in the archive.
96 That is, a mnesia.ez archive must contain a mnesia top directory.
97 An archive file for an application can, for example, be created like
99 this:
100 zip:create("mnesia-4.4.7.ez",
102 ["mnesia-4.4.7"],
103 [{cwd, code:lib_dir()},
104 {compress, all},
105 {uncompress,[".beam",".app"]}]).
106 Any file in the archive can be compressed, but to speed up the access
108 of frequently read files, it can be a good idea to store beam and app
109 files uncompressed in the archive.
110 Normally the top directory of an application is located in library
112 directory $OTPROOT/lib or in a directory referred to by environment
113 variable ERL_LIBS. At startup, when the initial code path is computed,
114 the code server also looks for archive files in these directories and
115 possibly adds ebin directories in archives to the code path. The code
116 path then contains paths to directories that look like $OTP‐
117 ROOT/lib/mnesia.ez/mnesia/ebin or $OTPROOT/lib/mnesia-4.4.7.ez/mne‐
118 sia-4.4.7/ebin.
119 The code server uses module erl_prim_loader in ERTS (possibly through
121 erl_boot_server) to read code files from archives. However, the func‐
122 tions in erl_prim_loader can also be used by other applications to read
123 files from archives. For example, the call erl_prim_loader:list_dir(
124 "/otp/root/lib/mnesia-4.4.7.ez/mnesia-4.4.7/examples/bench)" would list
125 the contents of a directory inside an archive. See erl_prim_loader(3).
126 An application archive file and a regular application directory can
128 coexist. This can be useful when it is needed to have parts of the
129 application as regular files. A typical case is the priv directory,
130 which must reside as a regular directory to link in drivers dynamically
131 and start port programs. For other applications that do not need this,
132 directory priv can reside in the archive and the files under the direc‐
133 tory priv can be read through erl_prim_loader.
134 When a directory is added to the code path and when the entire code
136 path is (re)set, the code server decides which subdirectories in an
137 application that are to be read from the archive and which that are to
138 be read as regular files. If directories are added or removed after‐
139 wards, the file access can fail if the code path is not updated (possi‐
140 bly to the same path as before, to trigger the directory resolution
141 update).
142 For each directory on the second level in the application archive
144 (ebin, priv, src, and so on), the code server first chooses the regular
145 directory if it exists and second from the archive. Function
146 code:lib_dir/2 returns the path to the subdirectory. For example,
147 code:lib_dir(megaco,ebin) can return
148 /otp/root/lib/megaco-3.9.1.1.ez/megaco-3.9.1.1/ebin while
149 code:lib_dir(megaco,priv) can return /otp/root/lib/megaco-3.9.1.1/priv.
150 When an escript file contains an archive, there are no restrictions on
152 the name of the escript and no restrictions on how many applications
153 that can be stored in the embedded archive. Single Beam files can also
154 reside on the top level in the archive. At startup, the top directory
155 in the embedded archive and all (second level) ebin directories in the
156 embedded archive are added to the code path. See erts:escript(1).
157 When the choice of directories in the code path is strict, the direc‐
159 tory that ends up in the code path is exactly the stated one. This
160 means that if, for example, the directory $OTPROOT/lib/mne‐
161 sia-4.4.7/ebin is explicitly added to the code path, the code server
162 does not load files from $OTPROOT/lib/mnesia-4.4.7.ez/mne‐
163 sia-4.4.7/ebin.
164 This behavior can be controlled through command-line flag
166 -code_path_choice Choice. If the flag is set to relaxed, the code
167 server instead chooses a suitable directory depending on the actual
168 file structure. If a regular application ebin directory exists, it is
169 chosen. Otherwise, the directory ebin in the archive is chosen if it
170 exists. If neither of them exists, the original directory is chosen.
171 Command-line flag -code_path_choice Choice also affects how module init
173 interprets the boot script. The interpretation of the explicit code
174 paths in the boot script can be strict or relaxed. It is particularly
175 useful to set the flag to relaxed when elaborating with code loading
176 from archives without editing the boot script. The default is relaxed.
177 See erts:init(3).
178
180 The code for a module can exist in two variants in a system: current
181 code and old code. When a module is loaded into the system for the
182 first time, the module code becomes 'current' and the global export ta‐
183 ble is updated with references to all functions exported from the mod‐
184 ule.
185 If then a new instance of the module is loaded (for example, because of
187 error correction), the code of the previous instance becomes 'old', and
188 all export entries referring to the previous instance are removed.
189 After that, the new instance is loaded as for the first time, and
190 becomes 'current'.
191 Both old and current code for a module are valid, and can even be eval‐
193 uated concurrently. The difference is that exported functions in old
194 code are unavailable. Hence, a global call cannot be made to an
195 exported function in old code, but old code can still be evaluated
196 because of processes lingering in it.
197 If a third instance of the module is loaded, the code server removes
199 (purges) the old code and any processes lingering in it are terminated.
200 Then the third instance becomes 'current' and the previously current
201 code becomes 'old'.
202 For more information about old and current code, and how to make a
204 process switch from old to current code, see section Compilation and
205 Code Loading in the Erlang Reference Manual.
206
208 Module and application names are atoms, while file and directory names
209 are strings. For backward compatibility reasons, some functions accept
210 both strings and atoms, but a future release will probably only allow
211 the arguments that are documented.
212 Functions in this module generally fail with an exception if they are
214 passed an incorrect type (for example, an integer or a tuple where an
215 atom is expected). An error tuple is returned if the argument type is
216 correct, but there are some other errors (for example, a non-existing
217 directory is specified to set_path/1).
218
220 Functions that load code (such as load_file/1) will return {error,Rea‐
221 son} if the load operation fails. Here follows a description of the
222 common reasons.
223 badfile:
225 The object code has an incorrect format or the module name in the
226 object code is not the expected module name.
227 nofile:
229 No file with object code was found.
230 not_purged:
232 The object code could not be loaded because an old version of the
233 code already existed.
234 on_load_failure:
236 The module has an -on_load function that failed when it was called.
237 sticky_directory:
239 The object code resides in a sticky directory.
240
242 load_ret() =
243 {error, What :: load_error_rsn()} |
244 {module, Module :: module()}
245 load_error_rsn() =
247 badfile | nofile | not_purged | on_load_failure |
248 sticky_directory
249 module_status() = not_loaded | loaded | modified | removed
251 prepared_code()
253 An opaque term holding prepared code.
255
257 set_path(Path) -> true | {error, What}
258 Types:
260 Path = [Dir :: file:filename()]
262 What = bad_directory
263 Sets the code path to the list of directories Path.
265 Returns:
267 true:
269 If successful
270 {error, bad_directory}:
272 If any Dir is not a directory name
273 get_path() -> Path
275 Types:
277 Path = [Dir :: file:filename()]
279 Returns the code path.
281 add_path(Dir) -> add_path_ret()
283 add_pathz(Dir) -> add_path_ret()
285 Types:
287 Dir = file:filename()
289 add_path_ret() = true | {error, bad_directory}
290 Adds Dir to the code path. The directory is added as the last
292 directory in the new path. If Dir already exists in the path, it
293 is not added.
294 Returns true if successful, or {error, bad_directory} if Dir is
296 not the name of a directory.
297 add_patha(Dir) -> add_path_ret()
299 Types:
301 Dir = file:filename()
303 add_path_ret() = true | {error, bad_directory}
304 Adds Dir to the beginning of the code path. If Dir exists, it is
306 removed from the old position in the code path.
307 Returns true if successful, or {error, bad_directory} if Dir is
309 not the name of a directory.
310 add_paths(Dirs) -> ok
312 add_pathsz(Dirs) -> ok
314 Types:
316 Dirs = [Dir :: file:filename()]
318 Adds the directories in Dirs to the end of the code path. If a
320 Dir exists, it is not added.
321 Always returns ok, regardless of the validity of each individual
323 Dir.
324 add_pathsa(Dirs) -> ok
326 Types:
328 Dirs = [Dir :: file:filename()]
330 Traverses Dirs and adds each Dir to the beginning of the code
332 path. This means that the order of Dirs is reversed in the
333 resulting code path. For example, if you add [Dir1,Dir2], the
334 resulting path will be [Dir2,Dir1|OldCodePath].
335 If a Dir already exists in the code path, it is removed from the
337 old position.
338 Always returns ok, regardless of the validity of each individual
340 Dir.
341 del_path(NameOrDir) -> boolean() | {error, What}
343 Types:
345 NameOrDir = Name | Dir
347 Name = atom()
348 Dir = file:filename()
349 What = bad_name
350 Deletes a directory from the code path. The argument can be an
352 atom Name, in which case the directory with the name
353 .../Name[-Vsn][/ebin] is deleted from the code path. Also, the
354 complete directory name Dir can be specified as argument.
355 Returns:
357 true:
359 If successful
360 false:
362 If the directory is not found
363 {error, bad_name}:
365 If the argument is invalid
366 replace_path(Name, Dir) -> true | {error, What}
368 Types:
370 Name = atom()
372 Dir = file:filename()
373 What = bad_directory | bad_name | {badarg, term()}
374 Replaces an old occurrence of a directory named
376 .../Name[-Vsn][/ebin] in the code path, with Dir. If Name does
377 not exist, it adds the new directory Dir last in the code path.
378 The new directory must also be named .../Name[-Vsn][/ebin]. This
379 function is to be used if a new version of the directory
380 (library) is added to a running system.
381 Returns:
383 true:
385 If successful
386 {error, bad_name}:
388 If Name is not found
389 {error, bad_directory}:
391 If Dir does not exist
392 {error, {badarg, [Name, Dir]}}:
394 If Name or Dir is invalid
395 load_file(Module) -> load_ret()
397 Types:
399 Module = module()
401 load_ret() =
402 {error, What :: load_error_rsn()} |
403 {module, Module :: module()}
404 Tries to load the Erlang module Module, using the code path. It
406 looks for the object code file with an extension corresponding
407 to the Erlang machine used, for example, Module.beam. The load‐
408 ing fails if the module name found in the object code differs
409 from the name Module. load_binary/3 must be used to load object
410 code with a module name that is different from the file name.
411 Returns {module, Module} if successful, or {error, Reason} if
413 loading fails. See Error Reasons for Code-Loading Functions for
414 a description of the possible error reasons.
415 load_abs(Filename) -> load_ret()
417 Types:
419 Filename = file:filename()
421 load_ret() =
422 {error, What :: load_error_rsn()} |
423 {module, Module :: module()}
424 loaded_filename() =
425 (Filename :: file:filename()) | loaded_ret_atoms()
426 loaded_ret_atoms() = cover_compiled | preloaded
427 Same as load_file(Module), but Filename is an absolute or rela‐
429 tive filename. The code path is not searched. It returns a value
430 in the same way as load_file/1. Notice that Filename must not
431 contain the extension (for example, .beam) because load_abs/1
432 adds the correct extension.
433 ensure_loaded(Module) -> {module, Module} | {error, What}
435 Types:
437 Module = module()
439 What = embedded | badfile | nofile | on_load_failure
440 Tries to load a module in the same way as load_file/1, unless
442 the module is already loaded. However, in embedded mode it does
443 not load a module that is not already loaded, but returns
444 {error, embedded} instead. See Error Reasons for Code-Loading
445 Functions for a description of other possible error reasons.
446 load_binary(Module, Filename, Binary) ->
448 {module, Module} | {error, What}
449 Types:
451 Module = module()
453 Filename = loaded_filename()
454 Binary = binary()
455 What = badarg | load_error_rsn()
456 loaded_filename() =
457 (Filename :: file:filename()) | loaded_ret_atoms()
458 loaded_ret_atoms() = cover_compiled | preloaded
459 This function can be used to load object code on remote Erlang
461 nodes. Argument Binary must contain object code for Module.
462 Filename is only used by the code server to keep a record of
463 from which file the object code for Module comes. Thus, Filename
464 is not opened and read by the code server.
465 Returns {module, Module} if successful, or {error, Reason} if
467 loading fails. See Error Reasons for Code-Loading Functions for
468 a description of the possible error reasons.
469 atomic_load(Modules) -> ok | {error, [{Module, What}]}
471 Types:
473 Modules = [Module | {Module, Filename, Binary}]
475 Module = module()
476 Filename = file:filename()
477 Binary = binary()
478 What =
479 badfile | nofile | on_load_not_allowed | duplicated |
480 not_purged | sticky_directory | pending_on_load
481 Tries to load all of the modules in the list Modules atomically.
483 That means that either all modules are loaded at the same time,
484 or none of the modules are loaded if there is a problem with any
485 of the modules.
486 Loading can fail for one the following reasons:
488 badfile:
490 The object code has an incorrect format or the module name
491 in the object code is not the expected module name.
492 nofile:
494 No file with object code exists.
495 on_load_not_allowed:
497 A module contains an -on_load function.
498 duplicated:
500 A module is included more than once in Modules.
501 not_purged:
503 The object code cannot be loaded because an old version of
504 the code already exists.
505 sticky_directory:
507 The object code resides in a sticky directory.
508 pending_on_load:
510 A previously loaded module contains an -on_load function
511 that never finished.
512 If it is important to minimize the time that an application is
514 inactive while changing code, use prepare_loading/1 and fin‐
515 ish_loading/1 instead of atomic_load/1. Here is an example:
516 {ok,Prepared} = code:prepare_loading(Modules),
518 %% Put the application into an inactive state or do any
519 %% other preparation needed before changing the code.
520 ok = code:finish_loading(Prepared),
521 %% Resume the application.
522 prepare_loading(Modules) ->
524 {ok, Prepared} | {error, [{Module, What}]}
525 Types:
527 Modules = [Module | {Module, Filename, Binary}]
529 Module = module()
530 Filename = file:filename()
531 Binary = binary()
532 Prepared = prepared_code()
533 What = badfile | nofile | on_load_not_allowed | duplicated
534 Prepares to load the modules in the list Modules. Finish the
536 loading by calling finish_loading(Prepared).
537 This function can fail with one of the following error reasons:
539 badfile:
541 The object code has an incorrect format or the module name
542 in the object code is not the expected module name.
543 nofile:
545 No file with object code exists.
546 on_load_not_allowed:
548 A module contains an -on_load function.
549 duplicated:
551 A module is included more than once in Modules.
552 finish_loading(Prepared) -> ok | {error, [{Module, What}]}
554 Types:
556 Prepared = prepared_code()
558 Module = module()
559 What = not_purged | sticky_directory | pending_on_load
560 Tries to load code for all modules that have been previously
562 prepared by prepare_loading/1. The loading occurs atomically,
563 meaning that either all modules are loaded at the same time, or
564 none of the modules are loaded.
565 This function can fail with one of the following error reasons:
567 not_purged:
569 The object code cannot be loaded because an old version of
570 the code already exists.
571 sticky_directory:
573 The object code resides in a sticky directory.
574 pending_on_load:
576 A previously loaded module contains an -on_load function
577 that never finished.
578 ensure_modules_loaded(Modules :: [Module]) ->
580 ok | {error, [{Module, What}]}
581 Types:
583 Module = module()
585 What = badfile | nofile | on_load_failure
586 Tries to load any modules not already loaded in the list Modules
588 in the same way as load_file/1.
589 Returns ok if successful, or {error,[{Module,Reason}]} if load‐
591 ing of some modules fails. See Error Reasons for Code-Loading
592 Functions for a description of other possible error reasons.
593 delete(Module) -> boolean()
595 Types:
597 Module = module()
599 Removes the current code for Module, that is, the current code
601 for Module is made old. This means that processes can continue
602 to execute the code in the module, but no external function
603 calls can be made to it.
604 Returns true if successful, or false if there is old code for
606 Module that must be purged first, or if Module is not a (loaded)
607 module.
608 purge(Module) -> boolean()
610 Types:
612 Module = module()
614 Purges the code for Module, that is, removes code marked as old.
616 If some processes still linger in the old code, these processes
617 are killed before the code is removed.
618 Note:
620 As of ERTS version 9.0, a process is only considered to be lin‐
621 gering in the code if it has direct references to the code. For
622 more information see documentation of
623 erlang:check_process_code/3, which is used in order to determine
624 this.
625 Returns true if successful and any process is needed to be
628 killed, otherwise false.
629 soft_purge(Module) -> boolean()
631 Types:
633 Module = module()
635 Purges the code for Module, that is, removes code marked as old,
637 but only if no processes linger in it.
638 Note:
640 As of ERTS version 9.0, a process is only considered to be lin‐
641 gering in the code if it has direct references to the code. For
642 more information see documentation of
643 erlang:check_process_code/3, which is used in order to determine
644 this.
645 Returns false if the module cannot be purged because of pro‐
648 cesses lingering in old code, otherwise true.
649 is_loaded(Module) -> {file, Loaded} | false
651 Types:
653 Module = module()
655 Loaded = loaded_filename()
656 loaded_filename() =
657 (Filename :: file:filename()) | loaded_ret_atoms()
658 Filename is an absolute filename.
659 loaded_ret_atoms() = cover_compiled | preloaded
660 Checks if Module is loaded. If it is, {file, Loaded} is
662 returned, otherwise false.
663 Normally, Loaded is the absolute filename Filename from which
665 the code is obtained. If the module is preloaded (see
666 script(4)), Loaded==preloaded. If the module is Cover-compiled
667 (see cover(3)), Loaded==cover_compiled.
668 all_available() -> [{Module, Filename, Loaded}]
670 Types:
672 Module = string()
674 Filename = loaded_filename()
675 Loaded = boolean()
676 loaded_filename() =
677 (Filename :: file:filename()) | loaded_ret_atoms()
678 Filename is an absolute filename.
679 loaded_ret_atoms() = cover_compiled | preloaded
680 Returns a list of tuples {Module, Filename, Loaded} for all
682 available modules. A module is considered to be available if it
683 either is loaded or would be loaded if called. Filename is nor‐
684 mally the absolute filename, as described for is_loaded/1.
685 all_loaded() -> [{Module, Loaded}]
687 Types:
689 Module = module()
691 Loaded = loaded_filename()
692 loaded_filename() =
693 (Filename :: file:filename()) | loaded_ret_atoms()
694 Filename is an absolute filename.
695 loaded_ret_atoms() = cover_compiled | preloaded
696 Returns a list of tuples {Module, Loaded} for all loaded mod‐
698 ules. Loaded is normally the absolute filename, as described for
699 is_loaded/1.
700 which(Module) -> Which
702 Types:
704 Module = module()
706 Which = loaded_filename() | non_existing
707 loaded_filename() =
708 (Filename :: file:filename()) | loaded_ret_atoms()
709 loaded_ret_atoms() = cover_compiled | preloaded
710 If the module is not loaded, this function searches the code
712 path for the first file containing object code for Module and
713 returns the absolute filename.
714 If the module is loaded, it returns the name of the file con‐
716 taining the loaded object code.
717 If the module is preloaded, preloaded is returned.
719 If the module is Cover-compiled, cover_compiled is returned.
721 If the module cannot be found, non_existing is returned.
723 get_object_code(Module) -> {Module, Binary, Filename} | error
725 Types:
727 Module = module()
729 Binary = binary()
730 Filename = file:filename()
731 Searches the code path for the object code of module Module.
733 Returns {Module, Binary, Filename} if successful, otherwise
734 error. Binary is a binary data object, which contains the object
735 code for the module. This can be useful if code is to be loaded
736 on a remote node in a distributed system. For example, loading
737 module Module on a node Node is done as follows:
738 {_Module, Binary, Filename} = code:get_object_code(Module),
740 rpc:call(Node, code, load_binary, [Module, Filename, Binary]),
741 get_doc(Mod) -> {ok, Res} | {error, Reason}
743 Types:
745 Mod = module()
747 Res = #docs_v1{}
748 Reason = non_existing | missing | file:posix()
749 Searches the code path for EEP-48 style documentation and
751 returns it if available. If no documentation can be found the
752 function tries to generate documentation from the debug informa‐
753 tion in the module. If no debug information is available, this
754 function will return {error,missing}.
755 For more information about the documentation chunk see Documen‐
757 tation Storage and Format in Kernel's User's Guide.
758 root_dir() -> file:filename()
760 Returns the root directory of Erlang/OTP, which is the directory
762 where it is installed.
763 Example:
765 > code:root_dir().
767 "/usr/local/otp"
768 lib_dir() -> file:filename()
770 Returns the library directory, $OTPROOT/lib, where $OTPROOT is
772 the root directory of Erlang/OTP.
773 Example:
775 > code:lib_dir().
777 "/usr/local/otp/lib"
778 lib_dir(Name) -> file:filename() | {error, bad_name}
780 Types:
782 Name = atom()
784 Returns the path for the "library directory", the top directory,
786 for an application Name located under $OTPROOT/lib or on a
787 directory referred to with environment variable ERL_LIBS.
788 If a regular directory called Name or Name-Vsn exists in the
790 code path with an ebin subdirectory, the path to this directory
791 is returned (not the ebin directory).
792 If the directory refers to a directory in an archive, the ar‐
794 chive name is stripped away before the path is returned. For
795 example, if directory /usr/local/otp/lib/mnesia-4.2.2.ez/mne‐
796 sia-4.2.2/ebin is in the path, /usr/local/otp/lib/mne‐
797 sia-4.2.2/ebin is returned. This means that the library direc‐
798 tory for an application is the same, regardless if the applica‐
799 tion resides in an archive or not.
800 Example:
802 > code:lib_dir(mnesia).
804 "/usr/local/otp/lib/mnesia-4.2.2"
805 Returns {error, bad_name} if Name is not the name of an applica‐
807 tion under $OTPROOT/lib or on a directory referred to through
808 environment variable ERL_LIBS. Fails with an exception if Name
809 has the wrong type.
810 Warning:
812 For backward compatibility, Name is also allowed to be a string.
813 That will probably change in a future release.
814 lib_dir(Name, SubDir) -> file:filename() | {error, bad_name}
817 Types:
819 Name = SubDir = atom()
821 Returns the path to a subdirectory directly under the top direc‐
823 tory of an application. Normally the subdirectories reside under
824 the top directory for the application, but when applications at
825 least partly resides in an archive, the situation is different.
826 Some of the subdirectories can reside as regular directories
827 while other reside in an archive file. It is not checked whether
828 this directory exists.
829 Example:
831 > code:lib_dir(megaco, priv).
833 "/usr/local/otp/lib/megaco-3.9.1.1/priv"
834 Fails with an exception if Name or SubDir has the wrong type.
836 compiler_dir() -> file:filename()
838 Returns the compiler library directory. Equivalent to
840 code:lib_dir(compiler).
841 priv_dir(Name) -> file:filename() | {error, bad_name}
843 Types:
845 Name = atom()
847 Returns the path to the priv directory in an application. Equiv‐
849 alent to code:lib_dir(Name, priv).
850 Warning:
852 For backward compatibility, Name is also allowed to be a string.
853 That will probably change in a future release.
854 objfile_extension() -> nonempty_string()
857 Returns the object code file extension corresponding to the
859 Erlang machine used, namely .beam.
860 stick_dir(Dir) -> ok | error
862 Types:
864 Dir = file:filename()
866 Marks Dir as sticky.
868 Returns ok if successful, otherwise error.
870 unstick_dir(Dir) -> ok | error
872 Types:
874 Dir = file:filename()
876 Unsticks a directory that is marked as sticky.
878 Returns ok if successful, otherwise error.
880 is_sticky(Module) -> boolean()
882 Types:
884 Module = module()
886 Returns true if Module is the name of a module that has been
888 loaded from a sticky directory (in other words: an attempt to
889 reload the module will fail), or false if Module is not a loaded
890 module or is not sticky.
891 where_is_file(Filename) -> non_existing | Absname
893 Types:
895 Filename = Absname = file:filename()
897 Searches the code path for Filename, a file of arbitrary type.
899 If found, the full name is returned. non_existing is returned if
900 the file cannot be found. The function can be useful, for exam‐
901 ple, to locate application resource files.
902 clash() -> ok
904 Searches all directories in the code path for module names with
906 identical names and writes a report to stdout.
907 module_status() -> [{module(), module_status()}]
909 Types:
911 module_status() = not_loaded | loaded | modified | removed
913 See module_status/1 and all_loaded/0 for details.
915 module_status(Module :: module() | [module()]) ->
917 module_status() | [{module(), module_status()}]
918 Types:
920 module_status() = not_loaded | loaded | modified | removed
922 The status of a module can be one of:
924 not_loaded:
926 If Module is not currently loaded.
927 loaded:
929 If Module is loaded and the object file exists and contains
930 the same code.
931 removed:
933 If Module is loaded but no corresponding object file can be
934 found in the code path.
935 modified:
937 If Module is loaded but the object file contains code with a
938 different MD5 checksum.
939 Preloaded modules are always reported as loaded, without
941 inspecting the contents on disk. Cover compiled modules will
942 always be reported as modified if an object file exists, or as
943 removed otherwise. Modules whose load path is an empty string
944 (which is the convention for auto-generated code) will only be
945 reported as loaded or not_loaded.
946 For modules that have native code loaded (see is_mod‐
948 ule_native/1), the MD5 sum of the native code in the object file
949 is used for the comparison, if it exists; the Beam code in the
950 file is ignored. Reversely, for modules that do not currently
951 have native code loaded, any native code in the file will be
952 ignored.
953 See also modified_modules/0.
955 modified_modules() -> [module()]
957 Returns the list of all currently loaded modules for which mod‐
959 ule_status/1 returns modified. See also all_loaded/0.
960 is_module_native(Module) -> true | false | undefined
962 Types:
964 Module = module()
966 Returns:
968 true:
970 If Module is the name of a loaded module that has native
971 code loaded
972 false:
974 If Module is loaded but does not have native code
975 undefined:
977 If Module is not loaded
978 get_mode() -> embedded | interactive
980 Returns an atom describing the mode of the code server: interac‐
982 tive or embedded.
983 This information is useful when an external entity (for example,
985 an IDE) provides additional code for a running node. If the code
986 server is in interactive mode, it only has to add the path to
987 the code. If the code server is in embedded mode, the code must
988 be loaded with load_binary/3.
989Ericsson AB kernel 7.3 code(3)