Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
code(3)			   Erlang Module Definition		       code(3)

NAME
       code - Erlang Code Server

DESCRIPTION
       This  module  contains  the interface to	the Erlang code	server , which
       deals with the loading of compiled code into a running  Erlang  runtime
       system.

       The  runtime  system  can  be started in	either embedded	or interactive
       mode. Which one is decided by the command line flag -mode .

       % erl -mode interactive

       Default mode is interactive .

	 * In embedded mode, all code is loaded	during system start-up accord-
	   ing	to  the	boot script. (Code can also be loaded later by explic-
	   itly	ordering the code server to do so).

	 * In interactive  mode,  only	some  code  is	loaded	during	system
	   startup-up,	basically the modules needed by	the runtime system it-
	   self. Other code is dynamically loaded when first referenced.  When
	   a call to a function	in a certain module is made, and the module is
	   not loaded, the code	server searches	for and	tries to load the mod-
	   ule.

       To  prevent accidentally	reloading modules affecting the	Erlang runtime
       system itself, the kernel , stdlib and compiler directories are consid-
       ered  sticky  . This means that the system issues a warning and rejects
       the request if a	user tries to reload a module residing in any of them.
       The feature can be disabled by using the	command	line flag -nostick .

CODE PATH
       In interactive mode, the	code server maintains a	search path -- usually
       called the code path -- consisting of a list of directories,  which  it
       searches	sequentially when trying to load a module.

       Initially,  the code path consists of the current working directory and
       all Erlang object code directories under	the  library  directory	 $OTP-
       ROOT/lib	 , where $OTPROOT is the installation directory	of Erlang/OTP,
       code:root_dir() . Directories can be  named  Name[-Vsn]	and  the  code
       server, by default, chooses the directory with the highest version num-
       ber among those which have the same Name	. The -Vsn suffix is optional.
       If  an  ebin  directory	exists under Name[-Vsn]	, it is	this directory
       which is	added to the code path.

       The environment variable	ERL_LIBS (defined in the operating system) can
       be  used	 to define additional library directories that will be handled
       in the same way as the standard OTP library directory described	above,
       except  that directories	that do	not have an ebin directory will	be ig-
       nored.

       All application directories found in the	 additional  directories  will
       appear  before the standard OTP applications, except for	the Kernel and
       STDLIB applications, which will be placed before	any additional	appli-
       cations.	In other words,	modules	found in any of	the additional library
       directories will	override modules with the same name in OTP, except for
       modules in Kernel and STDLIB.

       The  environment	 variable ERL_LIBS (if defined)	shold contain a	colon-
       separated (for Unix-like	systems) or semicolon-separated	(for  Windows)
       list of additional libraries.

       Example:	 On  an	 Unix-like  system,  ERL_LIBS could be set to /usr/lo-
       cal/jungerl:/home/some_user/my_erlang_lib . (On Windows,	use semi-colon
       as separator.)

CODE PATH CACHE
       The code	server incorporates a code path	cache. The cache functionality
       is disabled by default. To activate it, start  the  emulator  with  the
       command	line  flag  -code_path_cache  or call code:rehash() . When the
       cache is	created	(or updated), the code server searches for modules  in
       the code	path directories. This may take	some time if the the code path
       is long.	After the cache	creation, the time for loading	modules	 in  a
       large  system  (one  with a large directory structure) is significantly
       reduced compared	to having the cache disabled. The code server is  able
       to look up the location of a module from	the cache in constant time in-
       stead of	having to search through the code path directories.

       Application resource files ( .app files)	are also stored	 in  the  code
       path cache. This	feature	is used	by the application controller (see ap-
       plication(3) ) to load applications efficiently in large	systems.

       Note that when the code path cache is created (or updated),  any	 rela-
       tive directory names in the code	path are converted to absolute.

LOADING	OF CODE	FROM ARCHIVE FILES
   Warning:
       The support for loading of code from archive files is experimental. The
       sole purpose of releasing it before it is  ready	 is  to	 obtain	 early
       feedback. The file format, semantics, interfaces	etc. may be changed in
       a future	release. The function lib_dir/2	and the	flag -code_path_choice
       are also	experimental.

       In  the	current	implementation,	Erlang archives	are ZIP	files with .ez
       extension. Erlang archives may also be enclosed in escript files	 whose
       file extension is arbitrary.

       Erlang archive files may	contain	entire Erlang applications or parts of
       applications. The structure in an archive file is the same as  the  di-
       rectory	structure  for an application. If you for example would	create
       an archive of mnesia-4.4.7 ,  the  archive  file	 must  be  named  mne-
       sia-4.4.7.ez  and  it  must  contain a top directory with the name mne-
       sia-4.4.7 . If the version part of the name is omitted, it must also be
       omitted	in  the	 archive.  That	is, a mnesia.ez	archive	must contain a
       mnesia top directory.

       An archive file for an application may  for  example  be	 created  like
       this:

	  zip:create("mnesia-4.4.7.ez",
		     ["mnesia-4.4.7"],
		     [{cwd, code:lib_dir()},
		      {compress, all},
		      {uncompress,[".beam",".app"]}]).

       Any file	in the archive may be compressed, but in order to speed	up the
       access of frequently read files,	it may be a good idea  to  store  beam
       and app files uncompressed in the archive.

       Normally	 the  top directory of an application is located either	in the
       library directory $OTPROOT/lib or in a directory	referred to by the en-
       vironment  variable ERL_LIBS . At startup when the initial code path is
       computed, the code server will also look	for archive files in these di-
       rectories  and  possibly	 add  ebin directories in archives to the code
       path. The code path will	then contain paths to directories  that	 looks
       like	$OTPROOT/lib/mnesia.ez/mnesia/ebin     or    $OTPROOT/lib/mne-
       sia-4.4.7.ez/mnesia-4.4.7/ebin .

       The code	server uses  the  module  erl_prim_loader  (possibly  via  the
       erl_boot_server	)  to read code	files from archives. But the functions
       in erl_prim_loader may also be used by other applications to read files
       from	   archives.	    For	       example,	       the	  call
       erl_prim_loader:list_dir("/otp/root/lib/mnesia-4.4.7.ez/mne-
       sia-4.4.7/examples/bench)"  would  list the contents of a directory in-
       side an archive.	See erl_prim_loader(3)

       An application archive file and a regular application directory may co-
       exist.  This  may be useful when	there is a need	of having parts	of the
       application as regular files. A typical	case  is  the  priv  directory
       which must reside as a regular directory	in order to be able to dynami-
       cally link in drivers and start port programs. For  other  applications
       that  do	 not  have this	need, the priv directory may reside in the ar-
       chive and the files under the  priv  directory  may  be	read  via  the
       erl_prim_loader .

       At the time point when a	directory is added to the code path as well as
       when the	entire code path is (re)set, the code server will decide which
       subdirectories  in  an  application that	shall be read from the archive
       and which that shall be read as regular files. If directories are added
       or removed afterwards, the file access may fail if the code path	is not
       updated (possibly to the	same path as before in order  to  trigger  the
       directory  resolution  update).	For each directory on the second level
       (ebin, priv, src	etc.) in the application archive, the code server will
       firstly choose the regular directory if it exists and secondly from the
       archive.	The function code:lib_dir/2 returns the	path to	the  subdirec-
       tory.	 For	 example    code:lib_dir(megaco,ebin)	 may	return
       /otp/root/lib/megaco-3.9.1.1.ez/megaco-3.9.1.1/ebin		 while
       code:lib_dir(megaco,priv)  may return /otp/root/lib/megaco-3.9.1.1/priv
       .

       When an escript file contains an	archive, there	are  neither  restric-
       tions  on the name of the escript nor on	how many applications that may
       be stored in the	embedded archive. Single beam files may	also reside on
       the top level in	the archive. At	startup, both the top directory	in the
       embedded	archive	as well	as all (second level) ebin directories in  the
       embedded	archive	are added to the code path. See	escript(1)

       When  the choice	of directories in the code path	is strict , the	direc-
       tory that ends up in the	code path will be exactly the stated one. This
       means  that if for example the directory	$OTPROOT/lib/mnesia-4.4.7/ebin
       is explicitly added to the code path, the code  server  will  not  load
       files   from  $OTPROOT/lib/mnesia-4.4.7.ez/mnesia-4.4.7/ebin  and  vice
       versa.

       This  behavior  can  be	controlled   via   the	 command   line	  flag
       -code_path_choice  Choice  .  If	 the flag is set to relaxed , the code
       server will instead choose a suitable directory depending on the	actual
       file  structure.	 If  there  exists  a  regular application ebin	direc-
       tory,situation it will be choosen. But if it does not exist,  the  ebin
       directory  in  the  archive is choosen if it exists. If neither of them
       exists the original directory will be choosen.

       The command line	flag -code_path_choice Choice  does  also  affect  how
       init  interprets	 the  boot script . The	interpretation of the explicit
       code paths in the boot script may be strict or relaxed .	It is particu-
       lar  useful  to set the flag to relaxed when you	want to	elaborate with
       code loading from archives without editing the boot script  .  The  de-
       fault is	relaxed	. See init(3)

CURRENT	AND OLD	CODE
       The  code  of  a	module can exists in two variants in a system: current
       code and	old code . When	a module is loaded into	 the  system  for  the
       first time, the code of the module becomes 'current' and	the global ex-
       port table is updated with references to	all  functions	exported  from
       the module.

       If  then	a new instance of the module is	loaded (perhaps	because	of the
       correction of an	error),	then the code of the previous instance becomes
       'old',  and  all	 export	entries	referring to the previous instance are
       removed.	After that the new instance is loaded as if it was loaded  for
       the first time, as described above, and becomes 'current'.

       Both old	and current code for a module are valid, and may even be eval-
       uated concurrently. The difference is that exported  functions  in  old
       code are	unavailable. Hence there is no way to make a global call to an
       exported	function in old	code, but old code may still be	evaluated  be-
       cause of	processes lingering in it.

       If  a  third instance of	the module is loaded, the code server will re-
       move (purge) the	old code and any processes lingering  in  it  will  be
       terminated.  Then  the  third instance becomes 'current'	and the	previ-
       ously current code becomes 'old'.

       For more	information about old and current code,	 and  how  to  make  a
       process switch from old to current code,	refer to Erlang	Reference Man-
       ual .

ARGUMENT TYPES AND INVALID ARGUMENTS
       Generally, module and application names are atoms, while	file  and  di-
       rectory	names  are  strings.  For backward compatibility reasons, some
       functions accept	both strings and atoms,	 but  a	 future	 release  will
       probably	only allow the arguments that are documented.

       From  the  R12B	release,  functions in this module will	generally fail
       with an exception if they are passed an incorrect type  (for  instance,
       an  integer or a	tuple where an atom was	expected). An error tuple will
       be returned if type of argument was correct, but	there was  some	 other
       error (for instance, a non-existing directory given to set_path/1 .

EXPORTS
       set_path(Path) -> true |	{error,	What}

	      Types  Path = [Dir]
		     Dir = string()
		     What = bad_directory | bad_path

	      Sets the code path to the	list of	directories Path .

	      Returns true if successful, or {error, bad_directory} if any Dir
	      is not the name of a directory, or {error, bad_path} if the  ar-
	      gument is	invalid.

       get_path() -> Path

	      Types  Path = [Dir]
		     Dir = string()

	      Returns the code path

       add_path(Dir) ->	true | {error, What}
       add_pathz(Dir) -> true |	{error,	What}

	      Types  Dir = string()
		     What = bad_directory

	      Adds  Dir	 to  the code path. The	directory is added as the last
	      directory	in the new path. If Dir	already	exists in the path, it
	      is not added.

	      Returns  true if successful, or {error, bad_directory} if	Dir is
	      not the name of a	directory.

       add_patha(Dir) -> true |	{error,	What}

	      Types  Dir = string()
		     What = bad_directory

	      Adds Dir to the beginning	of the code path. If Dir  already  ex-
	      ists, it is removed from the old position	in the code path.

	      Returns  true if successful, or {error, bad_directory} if	Dir is
	      not the name of a	directory.

       add_paths(Dirs) -> ok
       add_pathsz(Dirs)	-> ok

	      Types  Dirs = [Dir]
		     Dir = string()

	      Adds the directories in Dirs to the end of the code path.	 If  a
	      Dir  already  exists,  it	is not added. This function always re-
	      turns ok , regardless of the validity of each individual Dir .

       add_pathsa(Dirs)	-> ok

	      Types  Dirs = [Dir]
		     Dir = string()

	      Adds the directories in Dirs to the beginning of the code	 path.
	      If  a Dir	already	exists,	it is removed from the old position in
	      the code path. This function always returns ok ,	regardless  of
	      the validity of each individual Dir .

       del_path(Name | Dir) -> true | false | {error, What}

	      Types  Name = atom()
		     Dir = string()
		     What = bad_name

	      Deletes  a  directory from the code path.	The argument can be an
	      atom  Name  ,  in	 which	case  the  directory  with  the	  name
	      .../Name[-Vsn][/ebin]  is	deleted	from the code path. It is also
	      possible to give the complete directory name Dir as argument.

	      Returns true if successful, or false if  the  directory  is  not
	      found, or	{error,	bad_name} if the argument is invalid.

       replace_path(Name, Dir) -> true | {error, What}

	      Types  Name = atom()
		     Dir = string()
		     What = bad_name | bad_directory | {badarg,	term()}

	      This  function  replaces	an old occurrence of a directory named
	      .../Name[-Vsn][/ebin] , in the code path,	with  Dir  .  If  Name
	      does  not	 exist,	it adds	the new	directory Dir last in the code
	      path. The	new directory must also	be named .../Name[-Vsn][/ebin]
	      .	This function should be	used if	a new version of the directory
	      (library)	is added to a running system.

	      Returns true if successful, or {error, bad_name} if Name is  not
	      found,  or {error, bad_directory}	if Dir does not	exist, or {er-
	      ror, {badarg, [Name, Dir]}} if Name or Dir is invalid.

       load_file(Module) -> {module, Module} | {error, What}

	      Types  Module = atom()
		     What = nofile | sticky_directory |	badarg | term()

	      Tries to load the	Erlang module Module , using the code path. It
	      looks  for  the  object  code file with an extension that	corre-
	      sponds to	the Erlang machine used, for example Module.beam . The
	      loading  fails  if the module name found in the object code dif-
	      fers from	the name Module	. load_binary/3	must be	used  to  load
	      object  code  with a module name that is different from the file
	      name.

	      Returns {module, Module} if successful, or {error, nofile} if no
	      object code is found, or {error, sticky_directory} if the	object
	      code resides in a	sticky directory, or {error,  badarg}  if  the
	      argument	is  invalid. Also if the loading fails,	an error tuple
	      is returned. See erlang:load_module/2  for  possible  values  of
	      What .

       load_abs(Filename) -> {module, Module} |	{error,	What}

	      Types  Filename =	string()
		     Module = atom()
		     What = nofile | sticky_directory |	badarg | term()

	      Does  the	 same as load_file(Module) , but Filename is either an
	      absolute file name, or a relative	file name. The	code  path  is
	      not  searched. It	returns	a value	in the same way	as load_file/1
	      .	Note that Filename should not contain the extension (for exam-
	      ple ".beam" ); load_abs/1	adds the correct extension itself.

       ensure_loaded(Module) ->	{module, Module} | {error, What}

	      Types  Module = atom()
		     What  =  nofile  |	sticky_directory | embedded | badarg |
		     term()

	      Tries to to load a module	in the same way	as load_file/1	,  un-
	      less the module is already loaded. In embedded mode, however, it
	      does not load a module which is not already loaded, but  returns
	      {error, embedded}	instead.

       load_binary(Module,  Filename,  Binary)	->  {module, Module} | {error,
       What}

	      Types  Module = atom()
		     Filename =	string()
		     What = sticky_directory | badarg |	term()

	      This function can	be used	to load	object code on	remote	Erlang
	      nodes. The argument Binary must contain object code for Module .
	      Filename is only used by the code	server to  keep	 a  record  of
	      from  which  file	the object code	for Module comes. Accordingly,
	      Filename is not opened and read by the code server.

	      Returns {module, Module} if successful, or {error, sticky_direc-
	      tory}  if	the object code	resides	in a sticky directory, or {er-
	      ror, badarg} if any argument is invalid.	Also  if  the  loading
	      fails,  an error tuple is	returned. See erlang:load_module/2 for
	      possible values of What .

       delete(Module) -> true |	false

	      Types  Module = atom()

	      Removes the current code for Module , that is, the current  code
	      for  Module  is made old.	This means that	processes can continue
	      to execute the code in the module, but that no external function
	      calls can	be made	to it.

	      Returns  true  if	 successful, or	false if there is old code for
	      Module which must	be  purged  first,  or	if  Module  is	not  a
	      (loaded) module.

       purge(Module) ->	true | false

	      Types  Module = atom()

	      Purges  the  code	 for  Module , that is,	removes	code marked as
	      old. If some processes still linger in the old code, these  pro-
	      cesses are killed	before the code	is removed.

	      Returns  true if successful and any process needed to be killed,
	      otherwise	false .

       soft_purge(Module) -> true | false

	      Types  Module = atom()

	      Purges the code for Module , that	is,  removes  code  marked  as
	      old, but only if no processes linger in it.

	      Returns false if the module could	not be purged due to processes
	      lingering	in old code, otherwise true .

       is_loaded(Module) -> {file, Loaded} | false

	      Types  Module = atom()
		     Loaded = Absname |	preloaded | cover_compiled
		     Absname = string()

	      Checks if	Module is loaded. If it	 is,  {file,  Loaded}  is  re-
	      turned, otherwise	false .

	      Normally,	 Loaded	 is  the absolute file name Absname from which
	      the code was obtained. If	the module is preloaded	(see script(4)
	      ),  Loaded==preloaded  .	If  the	 module	is Cover compiled (see
	      cover(3) ), Loaded==cover_compiled .

       all_loaded() -> [{Module, Loaded}]

	      Types  Module = atom()
		     Loaded = Absname |	preloaded | cover_compiled
		     Absname = string()

	      Returns a	list of	tuples {Module,	Loaded}	for  all  loaded  mod-
	      ules.  Loaded  is	 normally the absolute file name, as described
	      for is_loaded/1 .

       which(Module) ->	Which

	      Types  Module = atom()
		     Which = Filename |	non_existing | preloaded |  cover_com-
		     piled
		     Filename =	string()

	      If  the  module  is  not loaded, this function searches the code
	      path for the first file which contains object  code  for	Module
	      and  returns the absolute	file name. If the module is loaded, it
	      returns the name of the file which contained the	loaded	object
	      code. If the module is pre-loaded, preloaded is returned.	If the
	      module is	Cover compiled,	cover_compiled is returned. non_exist-
	      ing is returned if the module cannot be found.

       get_object_code(Module) -> {Module, Binary, Filename} | error

	      Types  Module = atom()
		     Binary = binary()
		     Filename =	string()

	      Searches	the code path for the object code of the module	Module
	      .	It returns {Module, Binary, Filename} if successful, and error
	      if not. Binary is	a binary data object which contains the	object
	      code for the module. This	can be useful if code is to be	loaded
	      on  a  remote node in a distributed system. For example, loading
	      module Module on a node Node is done as follows:

	      {_Module,	Binary,	Filename} = code:get_object_code(Module),
	      rpc:call(Node, code, load_binary,	[Module, Filename, Binary]),

       root_dir() -> string()

	      Returns the root directory of Erlang/OTP,	which is the directory
	      where it is installed.

	      >	code:root_dir().
	      "/usr/local/otp"

       lib_dir() -> string()

	      Returns  the library directory, $OTPROOT/lib , where $OTPROOT is
	      the root directory of Erlang/OTP.

	      >	code:lib_dir().
	      "/usr/local/otp/lib"

       lib_dir(Name) ->	string() | {error, bad_name}

	      Types  Name = atom()

	      This function is mainly intended for finding out	the  path  for
	      the  "library  directory", the top directory, for	an application
	      Name located under $OTPROOT/lib or on a  directory  referred  to
	      via the ERL_LIBS environment variable.

	      If  there	 is a regular directory	called Name or Name-Vsn	in the
	      code path	with an	ebin subdirectory, the path to this  directory
	      is returned (not the ebin	directory). If the directory refers to
	      a	directory in an	archive, the archive name is stripped away be-
	      fore  the	 path  is  returned.  For  example,  if	 the directory
	      /usr/local/otp/lib/mnesia-4.2.2.ez/mnesia-4.2.2/ebin is  in  the
	      path,  /usr/local/otp/lib/mnesia-4.2.2/ebin  will	 be  returned.
	      This means that the library directory for	an application is  the
	      same,  regardless	 of  whether the application resides in	an ar-
	      chive or not.

	      >	code:lib_dir(mnesia).
	      "/usr/local/otp/lib/mnesia-4.2.2"

	      Returns {error, bad_name}	if Name	is not the name	of an applica-
	      tion  under  $OTPROOT/lib	 or on a directory referred to via the
	      ERL_LIBS environment variable. Fails with	an exception  if  Name
	      has the wrong type.

   Warning:
       For  backward  compatibility, Name is also allowed to be	a string. That
       will probably change in a future	release.

       lib_dir(Name, SubDir) ->	string() | {error, bad_name}

	      Types  Name = atom()
		     SubDir = atom()

	      Returns the path to a subdirectory directly under	the top	direc-
	      tory  of an application. Normally	the subdirectories resides un-
	      der the top directory for	the application, but when applications
	      at  least	 partly	resides	in an archive the situation is differ-
	      ent. Some	of the subdirectories may reside as  regular  directo-
	      ries  while  other resides in an archive file. It	is not checked
	      if this directory	really exists.

	      >	code:lib_dir(megaco, priv).
	      "/usr/local/otp/lib/megaco-3.9.1.1/priv"

	      Fails with an exception if Name or SubDir	has the	wrong type.

       compiler_dir() -> string()

	      Returns  the   compiler	library	  directory.   Equivalent   to
	      code:lib_dir(compiler) .

       priv_dir(Name) -> string() | {error, bad_name}

	      Types  Name = atom()

	      Returns the path to the priv directory in	an application.	Equiv-
	      alent to code:lib_dir(Name,priv).	.

   Warning:
       For backward compatibility, Name	is also	allowed	to be a	 string.  That
       will probably change in a future	release.

       objfile_extension() -> ".beam"

	      Returns  the  object code	file extension that corresponds	to the
	      Erlang machine used, namely ".beam" .

       stick_dir(Dir) -> ok | error

	      Types  Dir = string()
		     What = term()

	      This function marks Dir as sticky.

	      Returns ok if successful or error	if not.

       unstick_dir(Dir)	-> ok |	error

	      Types  Dir = string()
		     What = term()

	      This function unsticks a directory  which	 has  been  marked  as
	      sticky.

	      Returns ok if successful or error	if not.

       is_sticky(Module) -> true | false

	      Types  Module = atom()

	      This  function  returns  true  if	Module is the name of a	module
	      that has been loaded from	a sticky directory (or in other	words:
	      an  attempt  to reload the module	will fail), or false if	Module
	      is not a loaded module or	is not sticky.

       rehash()	-> ok

	      This function creates or rehashes	the code path cache.

       where_is_file(Filename) -> Absname | non_existing

	      Types  Filename =	Absname	= string()

	      Searches the code	path for Filename , a file of arbitrary	 type.
	      If found,	the full name is returned. non_existing	is returned if
	      the file cannot be found.	The function can be useful, for	 exam-
	      ple,  to	locate	application  resource  files. If the code path
	      cache is used, the code server will efficiently  read  the  full
	      name  from  the  cache, provided that Filename is	an object code
	      file or an .app file.

       clash() -> ok

	      Searches the entire code space for module	names  with  identical
	      names and	writes a report	to stdout .

       is_module_native(Module)	-> true	| false	| undefined

	      Types  Module = atom()

	      This  function returns true if Module is name of a loaded	module
	      that has native code loaded, and false if	Module is  loaded  but
	      does not have native. If Module is not loaded, this function re-
	      turns undefined .

Ericsson AB			 kernel	2.14.2			       code(3)

NAME | DESCRIPTION | CODE PATH | CODE PATH CACHE | LOADING OF CODE FROM ARCHIVE FILES | CURRENT AND OLD CODE | ARGUMENT TYPES AND INVALID ARGUMENTS | EXPORTS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=code&manpath=FreeBSD+8.2-RELEASE+and+Ports>

home | help