NAME

       ct_slave - Common Test framework functions for starting and stopping
           nodes for Large-Scale Testing.

DESCRIPTION

       Common Test framework functions for starting and stopping nodes for Large-Scale Testing.

       This  module  exports  functions  used by the Common Test Master to start and stop "slave"
       nodes. It is the default callback module for the  {init,  node_start}  term  in  the  Test
       Specification.

EXPORTS

       start(Node) -> Result

              Types:

                 Node = atom()
                 Result = {ok, NodeName} | {error, Reason, NodeName}
                 Reason = already_started | started_not_connected | boot_timeout | init_timeout |
                 startup_timeout | not_alive
                 NodeName = atom()

              Starts an Erlang node with name Node on the local host.

              See also ct_slave:start/3.

       start(HostOrNode, NodeOrOpts) -> Result

              Types:

                 HostOrNode = atom()
                 NodeOrOpts = atom() | list()
                 Result = {ok, NodeName} | {error, Reason, NodeName}
                 Reason = already_started | started_not_connected | boot_timeout | init_timeout |
                 startup_timeout | not_alive
                 NodeName = atom()

              Starts  an  Erlang  node  with default options on a specified host, or on the local
              host with specified options. That is, the call is interpreted as start(Host,  Node)
              when  the  second  argument  is  atom-valued and start(Node, Opts) when it is list-
              valued.

              See also ct_slave:start/3.

       start(Host, Node, Opts) -> Result

              Types:

                 Node = atom()
                 Host = atom()
                 Opts = [OptTuples]
                 OptTuples  =  {username,  Username}  |  {password,  Password}  |  {boot_timeout,
                 BootTimeout} | {init_timeout, InitTimeout} | {startup_timeout, StartupTimeout} |
                 {startup_functions,   StartupFunctions}   |    {monitor_master,    Monitor}    |
                 {kill_if_fail, KillIfFail} | {erl_flags, ErlangFlags} | {env, [{EnvVar, Value}]}
                 Username = string()
                 Password = string()
                 BootTimeout = integer()
                 InitTimeout = integer()
                 StartupTimeout = integer()
                 StartupFunctions = [StartupFunctionSpec]
                 StartupFunctionSpec = {Module, Function, Arguments}
                 Module = atom()
                 Function = atom()
                 Arguments = [term]
                 Monitor = bool()
                 KillIfFail = bool()
                 ErlangFlags = string()
                 EnvVar = string()
                 Value = string()
                 Result = {ok, NodeName} | {error, Reason, NodeName}
                 Reason = already_started | started_not_connected | boot_timeout | init_timeout |
                 startup_timeout | not_alive
                 NodeName = atom()

              Starts an Erlang node with name Node on host Host as specified by  the  combination
              of options in Opts.

              Options Username and Password are used to log on to the remote host Host. Username,
              if omitted, defaults to the current username. Password is empty by default.

              A list of functions specified in option Startup are executed after startup  of  the
              node. Notice that all used modules are to be present in the code path on Host.

              The time-outs are applied as follows:

                BootTimeout:
                  The  time  to  start the Erlang node, in seconds. Defaults to 3 seconds. If the
                  node is not  pingable  within  this  time,  the  result  {error,  boot_timeout,
                  NodeName} is returned.

                InitTimeout:
                  The  time  to  wait  for the node until it calls the internal callback function
                  informing master about a successful startup. Defaults to 1 second. In case of a
                  timed out message, the result {error, init_timeout, NodeName} is returned.

                StartupTimeout:
                  The  time  to  wait until the node stops to run StartupFunctions. Defaults to 1
                  second. If this time-out occurs, the result {error, startup_timeout,  NodeName}
                  is returned.

              Options:

                monitor_master:
                  Specifies if the slave node is to be stopped if the master node stops. Defaults
                  to false.

                kill_if_fail:
                  Specifies if the slave node is  to  be  killed  if  a  time-out  occurs  during
                  initialization  or  startup. Defaults to true. Notice that the node can also be
                  still alive it the boot time-out occurred, but it is not killed in this case.

                erlang_flags:
                  Specifies which flags are added to the parameters of the executable erl.

                env:
                  Specifies a list of environment variables that will extend the environment.

              Special return values:

                * {error, already_started, NodeName} if the  node  with  the  specified  name  is
                  already started on a specified host.

                * {error,  started_not_connected,  NodeName}  if  the  node  is  started, but not
                  connected to the master node.

                * {error, not_alive, NodeName} if the node on which ct_slave:start/3  is  called,
                  is  not  alive.  Notice  that  NodeName is the name of the current node in this
                  case.

       stop(Node) -> Result

              Types:

                 Node = atom()
                 Result = {ok, NodeName} | {error, Reason, NodeName}
                 Reason = not_started | not_connected | stop_timeout

              Stops the running Erlang node with name Node on the local host.

       stop(Host, Node) -> Result

              Types:

                 Host = atom()
                 Node = atom()
                 Result = {ok, NodeName} | {error, Reason, NodeName}
                 Reason = not_started | not_connected | stop_timeout
                 NodeName = atom()

              Stops the running Erlang node with name Node on host Host.