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
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

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
56       directories without an ebin directory are ignored.
57
58       All application directories found in the additional directories appears
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
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
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
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
120       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
127       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
135       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
143       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
151       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
158       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
165       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
172       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

CURRENT AND OLD CODE

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
186       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
192       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
198       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
203       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

ARGUMENT TYPES AND INVALID ARGUMENTS

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
213       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

ERROR REASONS FOR CODE-LOADING FUNCTIONS

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
224         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
228         nofile:
229           No file with object code was found.
230
231         not_purged:
232           The object code could not be loaded because an old version  of  the
233           code already existed.
234
235         on_load_failure:
236           The module has an -on_load function that failed when it was called.
237
238         sticky_directory:
239           The object code resides in a sticky directory.
240

DATA TYPES

242       load_ret() =
243           {error, What :: load_error_rsn()} |
244           {module, Module :: module()}
245
246       load_error_rsn() =
247           badfile | nofile | not_purged | on_load_failure |
248           sticky_directory
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
331              resulting code path. For example, if you  add  [Dir1,Dir2],  the
332              resulting 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
378              (library) 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
442              {error,  embedded}  instead.  See Error Reasons for Code-Loading
443              Functions 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
621              erlang: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
641              erlang: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
660              returned, 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_loaded() -> [{Module, Loaded}]
668
669              Types:
670
671                 Module = module()
672                 Loaded = loaded_filename()
673                 loaded_filename() =
674                     (Filename :: file:filename()) | loaded_ret_atoms()
675                   Filename is an absolute filename.
676                 loaded_ret_atoms() = cover_compiled | preloaded
677
678              Returns a list of tuples {Module, Loaded} for  all  loaded  mod‐
679              ules. Loaded is normally the absolute filename, as described for
680              is_loaded/1.
681
682       which(Module) -> Which
683
684              Types:
685
686                 Module = module()
687                 Which = file:filename() | loaded_ret_atoms() | non_existing
688                 loaded_ret_atoms() = cover_compiled | preloaded
689
690              If the module is not loaded, this  function  searches  the  code
691              path  for  the  first file containing object code for Module and
692              returns the absolute filename.
693
694              If the module is loaded, it returns the name of  the  file  con‐
695              taining the loaded object code.
696
697              If the module is preloaded, preloaded is returned.
698
699              If the module is Cover-compiled, cover_compiled is returned.
700
701              If the module cannot be found, non_existing is returned.
702
703       get_object_code(Module) -> {Module, Binary, Filename} | error
704
705              Types:
706
707                 Module = module()
708                 Binary = binary()
709                 Filename = file:filename()
710
711              Searches  the  code  path  for the object code of module Module.
712              Returns {Module,  Binary,  Filename}  if  successful,  otherwise
713              error. Binary is a binary data object, which contains the object
714              code for the module. This can be useful if code is to be  loaded
715              on  a  remote node in a distributed system. For example, loading
716              module Module on a node Node is done as follows:
717
718              {_Module, Binary, Filename} = code:get_object_code(Module),
719              rpc:call(Node, code, load_binary, [Module, Filename, Binary]),
720
721       root_dir() -> file:filename()
722
723              Returns the root directory of Erlang/OTP, which is the directory
724              where it is installed.
725
726              Example:
727
728              > code:root_dir().
729              "/usr/local/otp"
730
731       lib_dir() -> file:filename()
732
733              Returns  the  library directory, $OTPROOT/lib, where $OTPROOT is
734              the root directory of Erlang/OTP.
735
736              Example:
737
738              > code:lib_dir().
739              "/usr/local/otp/lib"
740
741       lib_dir(Name) -> file:filename() | {error, bad_name}
742
743              Types:
744
745                 Name = atom()
746
747              Returns the path for the "library directory", the top directory,
748              for  an  application  Name  located  under  $OTPROOT/lib or on a
749              directory referred to with environment variable ERL_LIBS.
750
751              If a regular directory called Name or  Name-Vsn  exists  in  the
752              code  path with an ebin subdirectory, the path to this directory
753              is returned (not the ebin directory).
754
755              If the directory refers to a directory in an  archive,  the  ar‐
756              chive  name  is  stripped  away before the path is returned. For
757              example,  if  directory  /usr/local/otp/lib/mnesia-4.2.2.ez/mne‐
758              sia-4.2.2/ebin   is   in   the   path,   /usr/local/otp/lib/mne‐
759              sia-4.2.2/ebin is returned. This means that the  library  direc‐
760              tory  for an application is the same, regardless if the applica‐
761              tion resides in an archive or not.
762
763              Example:
764
765              > code:lib_dir(mnesia).
766              "/usr/local/otp/lib/mnesia-4.2.2"
767
768              Returns {error, bad_name} if Name is not the name of an applica‐
769              tion  under  $OTPROOT/lib  or on a directory referred to through
770              environment variable ERL_LIBS. Fails with an exception  if  Name
771              has the wrong type.
772
773          Warning:
774              For backward compatibility, Name is also allowed to be a string.
775              That will probably change in a future release.
776
777
778       lib_dir(Name, SubDir) -> file:filename() | {error, bad_name}
779
780              Types:
781
782                 Name = SubDir = atom()
783
784              Returns the path to a subdirectory directly under the top direc‐
785              tory of an application. Normally the subdirectories reside under
786              the top directory for the application, but when applications  at
787              least  partly resides in an archive, the situation is different.
788              Some of the subdirectories can  reside  as  regular  directories
789              while other reside in an archive file. It is not checked whether
790              this directory exists.
791
792              Example:
793
794              > code:lib_dir(megaco, priv).
795              "/usr/local/otp/lib/megaco-3.9.1.1/priv"
796
797              Fails with an exception if Name or SubDir has the wrong type.
798
799       compiler_dir() -> file:filename()
800
801              Returns  the   compiler   library   directory.   Equivalent   to
802              code:lib_dir(compiler).
803
804       priv_dir(Name) -> file:filename() | {error, bad_name}
805
806              Types:
807
808                 Name = atom()
809
810              Returns the path to the priv directory in an application. Equiv‐
811              alent to code:lib_dir(Name, priv).
812
813          Warning:
814              For backward compatibility, Name is also allowed to be a string.
815              That will probably change in a future release.
816
817
818       objfile_extension() -> nonempty_string()
819
820              Returns  the  object  code  file  extension corresponding to the
821              Erlang machine used, namely .beam.
822
823       stick_dir(Dir) -> ok | error
824
825              Types:
826
827                 Dir = file:filename()
828
829              Marks Dir as sticky.
830
831              Returns ok if successful, otherwise error.
832
833       unstick_dir(Dir) -> ok | error
834
835              Types:
836
837                 Dir = file:filename()
838
839              Unsticks a directory that is marked as sticky.
840
841              Returns ok if successful, otherwise error.
842
843       is_sticky(Module) -> boolean()
844
845              Types:
846
847                 Module = module()
848
849              Returns true if Module is the name of a  module  that  has  been
850              loaded  from  a  sticky directory (in other words: an attempt to
851              reload the module will fail), or false if Module is not a loaded
852              module or is not sticky.
853
854       where_is_file(Filename) -> non_existing | Absname
855
856              Types:
857
858                 Filename = Absname = file:filename()
859
860              Searches  the  code path for Filename, a file of arbitrary type.
861              If found, the full name is returned. non_existing is returned if
862              the  file cannot be found. The function can be useful, for exam‐
863              ple, to locate application resource files.
864
865       clash() -> ok
866
867              Searches all directories in the code path for module names  with
868              identical names and writes a report to stdout.
869
870       module_status(Module :: module()) ->
871                        not_loaded | loaded | modified | removed
872
873              Returns:
874
875                not_loaded:
876                  If Module is not currently loaded.
877
878                loaded:
879                  If  Module is loaded and the object file exists and contains
880                  the same code.
881
882                removed:
883                  If Module is loaded but no corresponding object file can  be
884                  found in the code path.
885
886                modified:
887                  If Module is loaded but the object file contains code with a
888                  different MD5 checksum.
889
890              Preloaded  modules  are  always  reported  as  loaded,   without
891              inspecting  the  contents  on  disk. Cover compiled modules will
892              always be reported as modified if an object file exists,  or  as
893              removed  otherwise.  Modules  whose load path is an empty string
894              (which is the convention for auto-generated code) will  only  be
895              reported as loaded or not_loaded.
896
897              For   modules   that   have  native  code  loaded  (see  is_mod‐
898              ule_native/1), the MD5 sum of the native code in the object file
899              is  used  for the comparison, if it exists; the Beam code in the
900              file is ignored. Reversely, for modules that  do  not  currently
901              have  native  code  loaded,  any native code in the file will be
902              ignored.
903
904              See also modified_modules/0.
905
906       modified_modules() -> [module()]
907
908              Returns the list of all currently loaded modules for which  mod‐
909              ule_status/1 returns modified. See also all_loaded/0.
910
911       is_module_native(Module) -> true | false | undefined
912
913              Types:
914
915                 Module = module()
916
917              Returns:
918
919                true:
920                  If  Module  is  the  name of a loaded module that has native
921                  code loaded
922
923                false:
924                  If Module is loaded but does not have native code
925
926                undefined:
927                  If Module is not loaded
928
929       get_mode() -> embedded | interactive
930
931              Returns an atom describing the mode of the code server: interac‐
932              tive or embedded.
933
934              This information is useful when an external entity (for example,
935              an IDE) provides additional code for a running node. If the code
936              server  is  in  interactive mode, it only has to add the path to
937              the code. If the code server is in embedded mode, the code  must
938              be loaded with load_binary/3.
939
940
941
942Ericsson AB                       kernel 6.5                           code(3)
Impressum