1code(3)                    Erlang Module Definition                    code(3)
2
3
4

NAME

6       code - Erlang code server.
7

DESCRIPTION

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

CODE PATH

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

LOADING OF CODE FROM ARCHIVE FILES

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
85
86       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
90       Erlang archive files can contain entire Erlang applications or parts of
91       applications.  The  structure in an archive file is the same as the di‐
92       rectory 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
98       An archive file for an application can, for example,  be  created  like
99       this:
100
101       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
107       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
111       Normally  the top directory of an application is located in library di‐
112       rectory $OTPROOT/lib or in a directory referred to by environment vari‐
113       able  ERL_LIBS. At startup, when the initial code path is computed, the
114       code server also looks for archive files in these directories and  pos‐
115       sibly adds ebin directories in archives to the code path. The code path
116       then contains paths to directories  that  look  like  $OTPROOT/lib/mne‐
117       sia.ez/mnesia/ebin or $OTPROOT/lib/mnesia-4.4.7.ez/mnesia-4.4.7/ebin.
118
119       The  code  server uses module erl_prim_loader in ERTS (possibly through
120       erl_boot_server) to read code files from archives. However,  the  func‐
121       tions in erl_prim_loader can also be used by other applications to read
122       files from archives. For example,  the  call  erl_prim_loader:list_dir(
123       "/otp/root/lib/mnesia-4.4.7.ez/mnesia-4.4.7/examples/bench)" would list
124       the contents of a directory inside an archive. See erl_prim_loader(3).
125
126       An application archive file and a regular application directory can co‐
127       exist. This can be useful when it is needed to have parts of the appli‐
128       cation as regular files. A typical case is the  priv  directory,  which
129       must  reside  as a regular directory to link in drivers dynamically and
130       start port programs. For other applications that do not need this,  di‐
131       rectory  priv  can reside in the archive and the files under the direc‐
132       tory priv can be read through erl_prim_loader.
133
134       When a directory is added to the code path and  when  the  entire  code
135       path is (re)set, the code server decides which subdirectories in an ap‐
136       plication that are to be read from the archive and which that are to be
137       read  as regular files. If directories are added or removed afterwards,
138       the file access can fail if the code path is not updated  (possibly  to
139       the same path as before, to trigger the directory resolution update).
140
141       For  each  directory  on  the  second  level in the application archive
142       (ebin, priv, src, and so on), the code server first chooses the regular
143       directory   if   it  exists  and  second  from  the  archive.  Function
144       code:lib_dir/2 returns the  path  to  the  subdirectory.  For  example,
145       code:lib_dir(megaco,ebin)                   can                  return
146       /otp/root/lib/megaco-3.9.1.1.ez/megaco-3.9.1.1/ebin               while
147       code:lib_dir(megaco,priv) can return /otp/root/lib/megaco-3.9.1.1/priv.
148
149       When  an escript file contains an archive, there are no restrictions on
150       the name of the escript and no restrictions on  how  many  applications
151       that  can be stored in the embedded archive. Single Beam files can also
152       reside on the top level in the archive. At startup, the  top  directory
153       in  the embedded archive and all (second level) ebin directories in the
154       embedded archive are added to the code path. See erts:escript(1).
155
156       When the choice of directories in the code path is strict,  the  direc‐
157       tory  that  ends  up  in  the code path is exactly the stated one. This
158       means  that  if,   for   example,   the   directory   $OTPROOT/lib/mne‐
159       sia-4.4.7/ebin  is  explicitly  added to the code path, the code server
160       does   not   load    files    from    $OTPROOT/lib/mnesia-4.4.7.ez/mne‐
161       sia-4.4.7/ebin.
162
163       This   behavior   can   be   controlled   through   command-line   flag
164       -code_path_choice Choice. If the flag  is  set  to  relaxed,  the  code
165       server  instead  chooses  a  suitable directory depending on the actual
166       file structure. If a regular application ebin directory exists,  it  is
167       chosen.  Otherwise,  the  directory ebin in the archive is chosen if it
168       exists. If neither of them exists, the original directory is chosen.
169
170       Command-line flag -code_path_choice Choice also affects how module init
171       interprets  the  boot  script.  The interpretation of the explicit code
172       paths in the boot script can be strict or relaxed. It  is  particularly
173       useful  to  set  the flag to relaxed when elaborating with code loading
174       from archives without editing the boot script. The default is  relaxed.
175       See erts:init(3).
176

CURRENT AND OLD CODE

178       The  code  for  a module can exist in two variants in a system: current
179       code and old code. When a module is loaded  into  the  system  for  the
180       first time, the module code becomes 'current' and the global export ta‐
181       ble is updated with references to all functions exported from the  mod‐
182       ule.
183
184       If then a new instance of the module is loaded (for example, because of
185       error correction), the code of the previous instance becomes 'old', and
186       all  export entries referring to the previous instance are removed. Af‐
187       ter that, the new instance is loaded as for the first time, and becomes
188       'current'.
189
190       Both old and current code for a module are valid, and can even be eval‐
191       uated concurrently. The difference is that exported  functions  in  old
192       code  are  unavailable.  Hence,  a global call cannot be made to an ex‐
193       ported function in old code, but old code can still  be  evaluated  be‐
194       cause of processes lingering in it.
195
196       If  a  third  instance of the module is loaded, the code server removes
197       (purges) the old code and any processes lingering in it are terminated.
198       Then  the  third  instance becomes 'current' and the previously current
199       code becomes 'old'.
200
201       For more information about old and current code,  and  how  to  make  a
202       process  switch  from  old to current code, see section Compilation and
203       Code Loading in the Erlang Reference Manual.
204

ARGUMENT TYPES AND INVALID ARGUMENTS

206       Module and application names are atoms, while file and directory  names
207       are  strings. For backward compatibility reasons, some functions accept
208       both strings and atoms, but a future release will probably  only  allow
209       the arguments that are documented.
210
211       Functions  in  this module generally fail with an exception if they are
212       passed an incorrect type (for example, an integer or a tuple  where  an
213       atom  is  expected). An error tuple is returned if the argument type is
214       correct, but there are some other errors (for example,  a  non-existing
215       directory is specified to set_path/1).
216

ERROR REASONS FOR CODE-LOADING FUNCTIONS

218       Functions  that load code (such as load_file/1) will return {error,Rea‐
219       son} if the load operation fails. Here follows  a  description  of  the
220       common reasons.
221
222         badfile:
223           The  object  code has an incorrect format or the module name in the
224           object code is not the expected module name.
225
226         nofile:
227           No file with object code was found.
228
229         not_purged:
230           The object code could not be loaded because an old version  of  the
231           code already existed.
232
233         on_load_failure:
234           The module has an -on_load function that failed when it was called.
235
236         sticky_directory:
237           The object code resides in a sticky directory.
238

DATA TYPES

240       load_ret() =
241           {error, What :: load_error_rsn()} |
242           {module, Module :: module()}
243
244       load_error_rsn() =
245           badfile | nofile | not_purged | on_load_failure |
246           sticky_directory
247
248       module_status() = not_loaded | loaded | modified | removed
249
250       prepared_code()
251
252              An opaque term holding prepared code.
253

EXPORTS

255       set_path(Path) -> true | {error, What}
256
257              Types:
258
259                 Path = [Dir :: file:filename()]
260                 What = bad_directory
261
262              Sets the code path to the list of directories Path.
263
264              Returns:
265
266                true:
267                  If successful
268
269                {error, bad_directory}:
270                  If any Dir is not a directory name
271
272       get_path() -> Path
273
274              Types:
275
276                 Path = [Dir :: file:filename()]
277
278              Returns the code path.
279
280       add_path(Dir) -> add_path_ret()
281
282       add_pathz(Dir) -> add_path_ret()
283
284              Types:
285
286                 Dir = file:filename()
287                 add_path_ret() = true | {error, bad_directory}
288
289              Adds  Dir  to  the code path. The directory is added as the last
290              directory in the new path. If Dir already exists in the path, it
291              is not added.
292
293              Returns  true if successful, or {error, bad_directory} if Dir is
294              not the name of a directory.
295
296       add_patha(Dir) -> add_path_ret()
297
298              Types:
299
300                 Dir = file:filename()
301                 add_path_ret() = true | {error, bad_directory}
302
303              Adds Dir to the beginning of the code path. If Dir exists, it is
304              removed from the old position in the code path.
305
306              Returns  true if successful, or {error, bad_directory} if Dir is
307              not the name of a directory.
308
309       add_paths(Dirs) -> ok
310
311       add_pathsz(Dirs) -> ok
312
313              Types:
314
315                 Dirs = [Dir :: file:filename()]
316
317              Adds the directories in Dirs to the end of the code path.  If  a
318              Dir exists, it is not added.
319
320              Always returns ok, regardless of the validity of each individual
321              Dir.
322
323       add_pathsa(Dirs) -> ok
324
325              Types:
326
327                 Dirs = [Dir :: file:filename()]
328
329              Traverses Dirs and adds each Dir to the beginning  of  the  code
330              path.  This  means that the order of Dirs is reversed in the re‐
331              sulting code path. For example, if you add [Dir1,Dir2], the  re‐
332              sulting path will be [Dir2,Dir1|OldCodePath].
333
334              If a Dir already exists in the code path, it is removed from the
335              old position.
336
337              Always returns ok, regardless of the validity of each individual
338              Dir.
339
340       del_path(NameOrDir) -> boolean() | {error, What}
341
342              Types:
343
344                 NameOrDir = Name | Dir
345                 Name = atom()
346                 Dir = file:filename()
347                 What = bad_name
348
349              Deletes  a  directory from the code path. The argument can be an
350              atom  Name,  in  which  case  the  directory   with   the   name
351              .../Name[-Vsn][/ebin]  is  deleted from the code path. Also, the
352              complete directory name Dir can be specified as argument.
353
354              Returns:
355
356                true:
357                  If successful
358
359                false:
360                  If the directory is not found
361
362                {error, bad_name}:
363                  If the argument is invalid
364
365       replace_path(Name, Dir) -> true | {error, What}
366
367              Types:
368
369                 Name = atom()
370                 Dir = file:filename()
371                 What = bad_directory | bad_name | {badarg, term()}
372
373              Replaces   an   old   occurrence   of    a    directory    named
374              .../Name[-Vsn][/ebin]  in  the code path, with Dir. If Name does
375              not exist, it adds the new directory Dir last in the code  path.
376              The new directory must also be named .../Name[-Vsn][/ebin]. This
377              function is to be used if a new version of  the  directory  (li‐
378              brary) is added to a running system.
379
380              Returns:
381
382                true:
383                  If successful
384
385                {error, bad_name}:
386                  If Name is not found
387
388                {error, bad_directory}:
389                  If Dir does not exist
390
391                {error, {badarg, [Name, Dir]}}:
392                  If Name or Dir is invalid
393
394       load_file(Module) -> load_ret()
395
396              Types:
397
398                 Module = module()
399                 load_ret() =
400                     {error, What :: load_error_rsn()} |
401                     {module, Module :: module()}
402
403              Tries  to load the Erlang module Module, using the code path. It
404              looks for the object code file with an  extension  corresponding
405              to  the Erlang machine used, for example, Module.beam. The load‐
406              ing fails if the module name found in the  object  code  differs
407              from  the name Module. load_binary/3 must be used to load object
408              code with a module name that is different from the file name.
409
410              Returns {module, Module} if successful, or  {error,  Reason}  if
411              loading  fails. See Error Reasons for Code-Loading Functions for
412              a description of the possible error reasons.
413
414       load_abs(Filename) -> load_ret()
415
416              Types:
417
418                 Filename = file:filename()
419                 load_ret() =
420                     {error, What :: load_error_rsn()} |
421                     {module, Module :: module()}
422                 loaded_filename() =
423                     (Filename :: file:filename()) | loaded_ret_atoms()
424                 loaded_ret_atoms() = cover_compiled | preloaded
425
426              Same as load_file(Module), but Filename is an absolute or  rela‐
427              tive filename. The code path is not searched. It returns a value
428              in the same way as load_file/1. Notice that  Filename  must  not
429              contain  the  extension  (for example, .beam) because load_abs/1
430              adds the correct extension.
431
432       ensure_loaded(Module) -> {module, Module} | {error, What}
433
434              Types:
435
436                 Module = module()
437                 What = embedded | badfile | nofile | on_load_failure
438
439              Tries to load a module in the same way  as  load_file/1,  unless
440              the  module is already loaded. However, in embedded mode it does
441              not load a module that is not already loaded, but  returns  {er‐
442              ror, embedded} instead. See Error Reasons for Code-Loading Func‐
443              tions for a description of other possible error reasons.
444
445       load_binary(Module, Filename, Binary) ->
446                      {module, Module} | {error, What}
447
448              Types:
449
450                 Module = module()
451                 Filename = loaded_filename()
452                 Binary = binary()
453                 What = badarg | load_error_rsn()
454                 loaded_filename() =
455                     (Filename :: file:filename()) | loaded_ret_atoms()
456                 loaded_ret_atoms() = cover_compiled | preloaded
457
458              This function can be used to load object code on  remote  Erlang
459              nodes.  Argument  Binary  must  contain  object code for Module.
460              Filename is only used by the code server to  keep  a  record  of
461              from which file the object code for Module comes. Thus, Filename
462              is not opened and read by the code server.
463
464              Returns {module, Module} if successful, or  {error,  Reason}  if
465              loading  fails. See Error Reasons for Code-Loading Functions for
466              a description of the possible error reasons.
467
468       atomic_load(Modules) -> ok | {error, [{Module, What}]}
469
470              Types:
471
472                 Modules = [Module | {Module, Filename, Binary}]
473                 Module = module()
474                 Filename = file:filename()
475                 Binary = binary()
476                 What =
477                     badfile | nofile | on_load_not_allowed | duplicated |
478                     not_purged | sticky_directory | pending_on_load
479
480              Tries to load all of the modules in the list Modules atomically.
481              That  means that either all modules are loaded at the same time,
482              or none of the modules are loaded if there is a problem with any
483              of the modules.
484
485              Loading can fail for one the following reasons:
486
487                badfile:
488                  The  object  code has an incorrect format or the module name
489                  in the object code is not the expected module name.
490
491                nofile:
492                  No file with object code exists.
493
494                on_load_not_allowed:
495                  A module contains an -on_load function.
496
497                duplicated:
498                  A module is included more than once in Modules.
499
500                not_purged:
501                  The object code cannot be loaded because an old  version  of
502                  the code already exists.
503
504                sticky_directory:
505                  The object code resides in a sticky directory.
506
507                pending_on_load:
508                  A  previously  loaded  module  contains an -on_load function
509                  that never finished.
510
511              If it is important to minimize the time that an  application  is
512              inactive  while  changing  code,  use prepare_loading/1 and fin‐
513              ish_loading/1 instead of atomic_load/1. Here is an example:
514
515              {ok,Prepared} = code:prepare_loading(Modules),
516              %% Put the application into an inactive state or do any
517              %% other preparation needed before changing the code.
518              ok = code:finish_loading(Prepared),
519              %% Resume the application.
520
521       prepare_loading(Modules) ->
522                          {ok, Prepared} | {error, [{Module, What}]}
523
524              Types:
525
526                 Modules = [Module | {Module, Filename, Binary}]
527                 Module = module()
528                 Filename = file:filename()
529                 Binary = binary()
530                 Prepared = prepared_code()
531                 What = badfile | nofile | on_load_not_allowed | duplicated
532
533              Prepares to load the modules in the  list  Modules.  Finish  the
534              loading by calling finish_loading(Prepared).
535
536              This function can fail with one of the following error reasons:
537
538                badfile:
539                  The  object  code has an incorrect format or the module name
540                  in the object code is not the expected module name.
541
542                nofile:
543                  No file with object code exists.
544
545                on_load_not_allowed:
546                  A module contains an -on_load function.
547
548                duplicated:
549                  A module is included more than once in Modules.
550
551       finish_loading(Prepared) -> ok | {error, [{Module, What}]}
552
553              Types:
554
555                 Prepared = prepared_code()
556                 Module = module()
557                 What = not_purged | sticky_directory | pending_on_load
558
559              Tries to load code for all modules  that  have  been  previously
560              prepared  by  prepare_loading/1.  The loading occurs atomically,
561              meaning that either all modules are loaded at the same time,  or
562              none of the modules are loaded.
563
564              This function can fail with one of the following error reasons:
565
566                not_purged:
567                  The  object  code cannot be loaded because an old version of
568                  the code already exists.
569
570                sticky_directory:
571                  The object code resides in a sticky directory.
572
573                pending_on_load:
574                  A previously loaded module  contains  an  -on_load  function
575                  that never finished.
576
577       ensure_modules_loaded(Modules :: [Module]) ->
578                                ok | {error, [{Module, What}]}
579
580              Types:
581
582                 Module = module()
583                 What = badfile | nofile | on_load_failure
584
585              Tries to load any modules not already loaded in the list Modules
586              in the same way as load_file/1.
587
588              Returns ok if successful, or {error,[{Module,Reason}]} if  load‐
589              ing  of  some  modules fails. See Error Reasons for Code-Loading
590              Functions for a description of other possible error reasons.
591
592       delete(Module) -> boolean()
593
594              Types:
595
596                 Module = module()
597
598              Removes the current code for Module, that is, the  current  code
599              for  Module  is made old. This means that processes can continue
600              to execute the code in the  module,  but  no  external  function
601              calls can be made to it.
602
603              Returns  true  if  successful, or false if there is old code for
604              Module that must be purged first, or if Module is not a (loaded)
605              module.
606
607       purge(Module) -> boolean()
608
609              Types:
610
611                 Module = module()
612
613              Purges the code for Module, that is, removes code marked as old.
614              If some processes still linger in the old code, these  processes
615              are killed before the code is removed.
616
617          Note:
618              As  of ERTS version 9.0, a process is only considered to be lin‐
619              gering in the code if it has direct references to the code.  For
620              more      information      see      documentation     of     er‐
621              lang:check_process_code/3, which is used in order  to  determine
622              this.
623
624
625              Returns  true  if  successful  and  any  process is needed to be
626              killed, otherwise false.
627
628       soft_purge(Module) -> boolean()
629
630              Types:
631
632                 Module = module()
633
634              Purges the code for Module, that is, removes code marked as old,
635              but only if no processes linger in it.
636
637          Note:
638              As  of ERTS version 9.0, a process is only considered to be lin‐
639              gering in the code if it has direct references to the code.  For
640              more      information      see      documentation     of     er‐
641              lang:check_process_code/3, which is used in order  to  determine
642              this.
643
644
645              Returns  false  if  the  module cannot be purged because of pro‐
646              cesses lingering in old code, otherwise true.
647
648       is_loaded(Module) -> {file, Loaded} | false
649
650              Types:
651
652                 Module = module()
653                 Loaded = loaded_filename()
654                 loaded_filename() =
655                     (Filename :: file:filename()) | loaded_ret_atoms()
656                   Filename is an absolute filename.
657                 loaded_ret_atoms() = cover_compiled | preloaded
658
659              Checks if Module is loaded. If it  is,  {file,  Loaded}  is  re‐
660              turned, otherwise false.
661
662              Normally,  Loaded  is  the absolute filename Filename from which
663              the  code  is  obtained.  If  the  module  is   preloaded   (see
664              script(4)),  Loaded==preloaded.  If the module is Cover-compiled
665              (see cover(3)), Loaded==cover_compiled.
666
667       all_available() -> [{Module, Filename, Loaded}]
668
669              Types:
670
671                 Module = string()
672                 Filename = loaded_filename()
673                 Loaded = boolean()
674                 loaded_filename() =
675                     (Filename :: file:filename()) | loaded_ret_atoms()
676                   Filename is an absolute filename.
677                 loaded_ret_atoms() = cover_compiled | preloaded
678
679              Returns a list of tuples  {Module,  Filename,  Loaded}  for  all
680              available  modules. A module is considered to be available if it
681              either is loaded or would be loaded if called. Filename is  nor‐
682              mally the absolute filename, as described for is_loaded/1.
683
684       all_loaded() -> [{Module, Loaded}]
685
686              Types:
687
688                 Module = module()
689                 Loaded = loaded_filename()
690                 loaded_filename() =
691                     (Filename :: file:filename()) | loaded_ret_atoms()
692                   Filename is an absolute filename.
693                 loaded_ret_atoms() = cover_compiled | preloaded
694
695              Returns  a  list  of tuples {Module, Loaded} for all loaded mod‐
696              ules. Loaded is normally the absolute filename, as described for
697              is_loaded/1.
698
699       which(Module) -> Which
700
701              Types:
702
703                 Module = module()
704                 Which = loaded_filename() | non_existing
705                 loaded_filename() =
706                     (Filename :: file:filename()) | loaded_ret_atoms()
707                 loaded_ret_atoms() = cover_compiled | preloaded
708
709              If  the  module  is  not loaded, this function searches the code
710              path for the first file containing object code  for  Module  and
711              returns the absolute filename.
712
713              If  the  module  is loaded, it returns the name of the file con‐
714              taining the loaded object code.
715
716              If the module is preloaded, preloaded is returned.
717
718              If the module is Cover-compiled, cover_compiled is returned.
719
720              If the module cannot be found, non_existing is returned.
721
722       get_object_code(Module) -> {Module, Binary, Filename} | error
723
724              Types:
725
726                 Module = module()
727                 Binary = binary()
728                 Filename = file:filename()
729
730              Searches the code path for the object code of module Module. Re‐
731              turns {Module, Binary, Filename} if successful, otherwise error.
732              Binary is a binary data object, which contains the  object  code
733              for  the module. This can be useful if code is to be loaded on a
734              remote node in a distributed system. For example, loading module
735              Module on a node Node is done as follows:
736
737              {_Module, Binary, Filename} = code:get_object_code(Module),
738              rpc:call(Node, code, load_binary, [Module, Filename, Binary]),
739
740       get_doc(Mod) -> {ok, Res} | {error, Reason}
741
742              Types:
743
744                 Mod = module()
745                 Res = #docs_v1{}
746                 Reason = non_existing | missing | file:posix()
747
748              Searches  the  code  path for EEP-48 style documentation and re‐
749              turns it if available. If no  documentation  can  be  found  the
750              function tries to generate documentation from the debug informa‐
751              tion in the module. If no debug information is  available,  this
752              function will return {error,missing}.
753
754              For  more information about the documentation chunk see Documen‐
755              tation Storage and Format in Kernel's User's Guide.
756
757       root_dir() -> file:filename()
758
759              Returns the root directory of Erlang/OTP, which is the directory
760              where it is installed.
761
762              Example:
763
764              > code:root_dir().
765              "/usr/local/otp"
766
767       lib_dir() -> file:filename()
768
769              Returns  the  library directory, $OTPROOT/lib, where $OTPROOT is
770              the root directory of Erlang/OTP.
771
772              Example:
773
774              > code:lib_dir().
775              "/usr/local/otp/lib"
776
777       lib_dir(Name) -> file:filename() | {error, bad_name}
778
779              Types:
780
781                 Name = atom()
782
783              Returns the path for the "library directory", the top directory,
784              for  an  application Name located under $OTPROOT/lib or on a di‐
785              rectory referred to with environment variable ERL_LIBS.
786
787              If a regular directory called Name or  Name-Vsn  exists  in  the
788              code  path with an ebin subdirectory, the path to this directory
789              is returned (not the ebin directory).
790
791              If the directory refers to a directory in an  archive,  the  ar‐
792              chive name is stripped away before the path is returned. For ex‐
793              ample,  if   directory   /usr/local/otp/lib/mnesia-4.2.2.ez/mne‐
794              sia-4.2.2/ebin   is   in   the   path,   /usr/local/otp/lib/mne‐
795              sia-4.2.2/ebin is returned. This means that the  library  direc‐
796              tory  for an application is the same, regardless if the applica‐
797              tion resides in an archive or not.
798
799              Example:
800
801              > code:lib_dir(mnesia).
802              "/usr/local/otp/lib/mnesia-4.2.2"
803
804              Returns {error, bad_name} if Name is not the name of an applica‐
805              tion  under  $OTPROOT/lib  or on a directory referred to through
806              environment variable ERL_LIBS. Fails with an exception  if  Name
807              has the wrong type.
808
809          Warning:
810              For backward compatibility, Name is also allowed to be a string.
811              That will probably change in a future release.
812
813
814       lib_dir(Name, SubDir) -> file:filename() | {error, bad_name}
815
816              Types:
817
818                 Name = SubDir = atom()
819
820              Returns the path to a subdirectory directly under the top direc‐
821              tory of an application. Normally the subdirectories reside under
822              the top directory for the application, but when applications  at
823              least  partly resides in an archive, the situation is different.
824              Some of the subdirectories can  reside  as  regular  directories
825              while other reside in an archive file. It is not checked whether
826              this directory exists.
827
828              Example:
829
830              > code:lib_dir(megaco, priv).
831              "/usr/local/otp/lib/megaco-3.9.1.1/priv"
832
833              Fails with an exception if Name or SubDir has the wrong type.
834
835       compiler_dir() -> file:filename()
836
837              Returns  the   compiler   library   directory.   Equivalent   to
838              code:lib_dir(compiler).
839
840       priv_dir(Name) -> file:filename() | {error, bad_name}
841
842              Types:
843
844                 Name = atom()
845
846              Returns the path to the priv directory in an application. Equiv‐
847              alent to code:lib_dir(Name, priv).
848
849          Warning:
850              For backward compatibility, Name is also allowed to be a string.
851              That will probably change in a future release.
852
853
854       objfile_extension() -> nonempty_string()
855
856              Returns  the object code file extension corresponding to the Er‐
857              lang machine used, namely .beam.
858
859       stick_dir(Dir) -> ok | error
860
861              Types:
862
863                 Dir = file:filename()
864
865              Marks Dir as sticky.
866
867              Returns ok if successful, otherwise error.
868
869       unstick_dir(Dir) -> ok | error
870
871              Types:
872
873                 Dir = file:filename()
874
875              Unsticks a directory that is marked as sticky.
876
877              Returns ok if successful, otherwise error.
878
879       is_sticky(Module) -> boolean()
880
881              Types:
882
883                 Module = module()
884
885              Returns true if Module is the name of a  module  that  has  been
886              loaded  from  a  sticky directory (in other words: an attempt to
887              reload the module will fail), or false if Module is not a loaded
888              module or is not sticky.
889
890       where_is_file(Filename) -> non_existing | Absname
891
892              Types:
893
894                 Filename = Absname = file:filename()
895
896              Searches  the  code path for Filename, a file of arbitrary type.
897              If found, the full name is returned. non_existing is returned if
898              the  file cannot be found. The function can be useful, for exam‐
899              ple, to locate application resource files.
900
901       clash() -> ok
902
903              Searches all directories in the code path for module names  with
904              identical names and writes a report to stdout.
905
906       module_status() -> [{module(), module_status()}]
907
908              Types:
909
910                 module_status() = not_loaded | loaded | modified | removed
911
912              See module_status/1 and all_loaded/0 for details.
913
914       module_status(Module :: module() | [module()]) ->
915                        module_status() | [{module(), module_status()}]
916
917              Types:
918
919                 module_status() = not_loaded | loaded | modified | removed
920
921              The status of a module can be one of:
922
923                not_loaded:
924                  If Module is not currently loaded.
925
926                loaded:
927                  If  Module is loaded and the object file exists and contains
928                  the same code.
929
930                removed:
931                  If Module is loaded but no corresponding object file can  be
932                  found in the code path.
933
934                modified:
935                  If Module is loaded but the object file contains code with a
936                  different MD5 checksum.
937
938              Preloaded modules are always reported  as  loaded,  without  in‐
939              specting  the  contents on disk. Cover compiled modules will al‐
940              ways be reported as modified if an object file exists, or as re‐
941              moved  otherwise.  Modules  whose  load  path is an empty string
942              (which is the convention for auto-generated code) will  only  be
943              reported as loaded or not_loaded.
944
945              See also modified_modules/0.
946
947       modified_modules() -> [module()]
948
949              Returns  the list of all currently loaded modules for which mod‐
950              ule_status/1 returns modified. See also all_loaded/0.
951
952       is_module_native(Module) -> true | false | undefined
953
954              Types:
955
956                 Module = module()
957
958              Returns false if the given Module is loaded, and undefined if it
959              is not.
960
961          Warning:
962              This  function is deprecated and will be removed in a future re‐
963              lease.
964
965
966       get_mode() -> embedded | interactive
967
968              Returns an atom describing the mode of the code server: interac‐
969              tive or embedded.
970
971              This information is useful when an external entity (for example,
972              an IDE) provides additional code for a running node. If the code
973              server  is  in  interactive mode, it only has to add the path to
974              the code. If the code server is in embedded mode, the code  must
975              be loaded with load_binary/3.
976
977
978
979Ericsson AB                      kernel 8.3.2                          code(3)
Impressum