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

FreeBSD Manual Pages

  
 
  

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

NAME
       init - Coordination of System Startup

DESCRIPTION
       The init	module is pre-loaded and contains the code for the init	system
       process which coordinates the start-up of the system. The  first	 func-
       tion  evaluated at start-up is boot(BootArgs), where BootArgs is	a list
       of command line arguments supplied to the Erlang	 runtime  system  from
       the local operating system. See erl(1).

       init reads the boot script which	contains instructions on how to	initi-
       ate the system. See script(4) for more information about	boot scripts.

       init also contains functions to restart,	reboot,	and stop the system.

EXPORTS
       boot(BootArgs) -> no_return()

	      Types:

		 BootArgs = [binary()]

	      Starts the Erlang	runtime	system.	This function is  called  when
	      the emulator is started and coordinates system start-up.

	      BootArgs	are  all  command  line	 arguments except the emulator
	      flags, that is, flags and	plain arguments. See erl(1).

	      init itself interprets some of the flags,	see Command Line Flags
	      below.  The  remaining  flags ("user flags") and plain arguments
	      are passed to the	init loop and  can  be	retrieved  by  calling
	      get_arguments/0 and get_plain_arguments/0, respectively.

       get_argument(Flag) -> {ok, Arg} | error

	      Types:

		 Flag =	atom()
		 Arg = [Values :: [string()]]

	      Returns  all  values  associated with the	command	line user flag
	      Flag. If Flag is provided	several	times, each Values is returned
	      in preserved order.

	      %	erl -a b c -a d
	      1> init:get_argument(a).
	      {ok,[["b","c"],["d"]]}

	      There  are  also	a number of flags, which are defined automati-
	      cally and	can be retrieved using this function:

		root:
		  The installation directory of	Erlang/OTP, $ROOT.

		2> init:get_argument(root).
		{ok,[["/usr/local/otp/releases/otp_beam_solaris8_r10b_patched"]]}

		progname:
		  The name of the program which	started	Erlang.

		3> init:get_argument(progname).
		{ok,[["erl"]]}

		home:
		  The home directory.

		4> init:get_argument(home).
		{ok,[["/home/harry"]]}

	      Returns error if there is	no value associated with Flag.

       get_arguments() -> Flags

	      Types:

		 Flags = [{Flag	:: atom(), Values :: [string()]}]

	      Returns all command line flags, as well as  the  system  defined
	      flags, see get_argument/1.

       get_plain_arguments() ->	[Arg]

	      Types:

		 Arg = string()

	      Returns  any  plain  command line	arguments as a list of strings
	      (possibly	empty).

       get_status() -> {InternalStatus,	ProvidedStatus}

	      Types:

		 InternalStatus	= internal_status()
		 ProvidedStatus	= term()
		 internal_status() = starting |	started	| stopping

	      The current status of the	init process can be inspected.	During
	      system startup (initialization), InternalStatus is starting, and
	      ProvidedStatus indicates how far the boot	script has been	inter-
	      preted.  Each  {progress,	 Info}	term  interpreted  in the boot
	      script affects ProvidedStatus, that is, ProvidedStatus gets  the
	      value of Info.

       reboot()	-> ok

	      All  applications	are taken down smoothly, all code is unloaded,
	      and all ports are	closed before the system  terminates.  If  the
	      -heart  command  line flag was given, the	heart program will try
	      to reboot	the system. Refer to heart(3) for more information.

	      To limit the shutdown time, the time init	is  allowed  to	 spend
	      taking  down  applications, the -shutdown_time command line flag
	      should be	used.

       restart() -> ok

	      The system is restarted inside the running  Erlang  node,	 which
	      means  that  the emulator	is not restarted. All applications are
	      taken down smoothly, all code is unloaded,  and  all  ports  are
	      closed before the	system is booted again in the same way as ini-
	      tially started. The same BootArgs	are used again.

	      To limit the shutdown time, the time init	is  allowed  to	 spend
	      taking  down  applications, the -shutdown_time command line flag
	      should be	used.

       script_id() -> Id

	      Types:

		 Id = term()

	      Get the identity of the boot script used to boot the system.  Id
	      can  be  any  Erlang  term. In the delivered boot	scripts, Id is
	      {Name, Vsn}. Name	and Vsn	are strings.

       stop() -> ok

	      All applications are taken down smoothly,	all code is  unloaded,
	      and  all	ports  are closed before the system terminates.	If the
	      -heart command line flag was given, the heart program is	termi-
	      nated  before  the Erlang	node terminates. Refer to heart(3) for
	      more information.

	      To limit the shutdown time, the time init	is  allowed  to	 spend
	      taking  down  applications, the -shutdown_time command line flag
	      should be	used.

       stop(Status) -> ok

	      Types:

		 Status	= integer() >= 0 | string()

	      All applications are taken down smoothly,	all code is  unloaded,
	      and all ports are	closed before the system terminates by calling
	      halt(Status). If the -heart command line	flag  was  given,  the
	      heart  program  is terminated before the Erlang node terminates.
	      Refer to heart(3)	for more information.

	      To limit the shutdown time, the time init	is  allowed  to	 spend
	      taking  down  applications, the -shutdown_time command line flag
	      should be	used.

COMMAND	LINE FLAGS
   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 -code_path_choice flag is also experimental.

       The init	module interprets the following	command	line flags:

	 --:
	   Everything following	-- up to the next flag is considered plain ar-
	   guments and can be retrieved	using get_plain_arguments/0.

	 -code_path_choice Choice:
	   This	flag can be set	to strict or relaxed. It controls whether each
	   directory in	the code path should be	interpreted strictly as	it ap-
	   pears in the	boot script or if init should be more relaxed and  try
	   to  find  a suitable	directory if it	can choose from	a regular ebin
	   directory and an ebin directory in an archive file.	This  flag  is
	   particular useful when you want to elaborate	with code loading from
	   archives without editing the	boot script. See  script(4)  for  more
	   information	about  interpretation  of  boot	scripts. The flag does
	   also	have a similar affect  on  how	the  code  server  works.  See
	   code(3).

	 -eval Expr:
	   Scans,  parses  and	evaluates  an arbitrary	expression Expr	during
	   system initialization. If any of these steps	 fail  (syntax	error,
	   parse  error	 or exception during evaluation), Erlang stops with an
	   error message. Here is an example that seeds	the random number gen-
	   erator:

	 % erl -eval '{X,Y,Z} =	now(), random:seed(X,Y,Z).'

	   This	example	uses Erlang as a hexadecimal calculator:

	 % erl -noshell	-eval 'R = 16#1F+16#A0,	io:format("~.16B~n", [R])' \\
	 -s erlang halt
	 BF

	   If multiple -eval expressions are specified,	they are evaluated se-
	   quentially in the order specified. -eval expressions	are  evaluated
	   sequentially	 with -s and -run function calls (this also in the or-
	   der specified). As with -s and -run,	an evaluation  that  does  not
	   terminate, blocks the system	initialization process.

	 -extra:
	   Everything  following  -extra is considered plain arguments and can
	   be retrieved	using get_plain_arguments/0.

	 -run Mod [Func	[Arg1, Arg2, ...]]:
	   Evaluates the specified function call during	system initialization.
	   Func	 defaults to start. If no arguments are	provided, the function
	   is assumed to be of arity 0.	Otherwise it is	assumed	to be of arity
	   1,  taking  the list	[Arg1,Arg2,...]	as argument. All arguments are
	   passed as strings. If an exception is raised, Erlang	stops with  an
	   error message.

	   Example:

	 % erl -run foo	-run foo bar -run foo bar baz 1	2

	   This	 starts	 the Erlang runtime system and evaluates the following
	   functions:

	 foo:start()
	 foo:bar()
	 foo:bar(["baz", "1", "2"]).

	   The	functions  are	executed  sequentially	in  an	initialization
	   process,  which  then terminates normally and passes	control	to the
	   user. This means that a -run	call which does	not return will	 block
	   further  processing;	 to  avoid  this, use some variant of spawn in
	   such	cases.

	 -s Mod	[Func [Arg1, Arg2, ...]]:
	   Evaluates the specified function call during	system initialization.
	   Func	 defaults to start. If no arguments are	provided, the function
	   is assumed to be of arity 0.	Otherwise it is	assumed	to be of arity
	   1,  taking  the list	[Arg1,Arg2,...]	as argument. All arguments are
	   passed as atoms. If an exception is raised, Erlang  stops  with  an
	   error message.

	   Example:

	 % erl -s foo -s foo bar -s foo	bar baz	1 2

	   This	 starts	 the Erlang runtime system and evaluates the following
	   functions:

	 foo:start()
	 foo:bar()
	 foo:bar([baz, '1', '2']).

	   The	functions  are	executed  sequentially	in  an	initialization
	   process,  which  then terminates normally and passes	control	to the
	   user. This means that a -s call which does not  return  will	 block
	   further  processing;	 to  avoid  this, use some variant of spawn in
	   such	cases.

	   Due to the limited length of	atoms, it is recommended that -run  be
	   used	instead.

EXAMPLE
       % erl --	a b -children thomas claire -ages 7 3 -- x y

       1> init:get_plain_arguments().
       ["a","b","x","y"]
       2> init:get_argument(children).
       {ok,[["thomas","claire"]]}
       3> init:get_argument(ages).
       {ok, [["7","3"]]}
       4> init:get_argument(silly).
       error

SEE ALSO
       erl_prim_loader(3), heart(3)

Ericsson AB			   erts	7.3			       init(3)

NAME | DESCRIPTION | EXPORTS | COMMAND LINE FLAGS | EXAMPLE | SEE ALSO

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

home | help