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

NAME

6       slave - Functions for starting and controlling slave nodes.
7
8

DESCRIPTION

10       This  module  provides  functions  for starting Erlang slave nodes. All
11       slave nodes that are started by a master terminate  automatically  when
12       the  master  terminates.  All  terminal output produced at the slave is
13       sent back to the master node. File I/O is done through the master.
14
15       Slave nodes on other hosts than the current one are  started  with  the
16       ssh  program. The user must be allowed to ssh to the remote hosts with‐
17       out being prompted for a password. This can be arranged in a number  of
18       ways  (for details, see the ssh documentation). A slave node started on
19       the same host as the master inherits certain  environment  values  from
20       the  master,  such  as  the current directory and the environment vari‐
21       ables. For what can be assumed about the environment when  a  slave  is
22       started on another host, see the documentation for the ssh program.
23
24       An  alternative to the ssh program can be specified on the command line
25       to erl(1) as follows:
26
27       -rsh Program
28
29       Note that the command specified with the -rsh flag is treated as a file
30       name  which  may contain spaces. It is thus not possible to include any
31       command line options. The remote node will be launched as "$RSH"  "$RE‐
32       MOTE_HOSTNAME"  erl  -detached -noinput ..., so the erl command must be
33       found in the path on the remote host.
34
35       The slave node is to use the same file system at the master. At  least,
36       Erlang/OTP  is  to be installed in the same place on both computers and
37       the same version of Erlang is to be used.
38
39       A node running on Windows can only start slave nodes  on  the  host  on
40       which it is running.
41
42       The master node must be alive.
43

EXPORTS

45       pseudo([Master | ServerList]) -> ok
46
47              Types:
48
49                 Master = node()
50                 ServerList = [atom()]
51
52              Calls  pseudo(Master,  ServerList).  If you want to start a node
53              from the command line and set up a number of pseudo servers,  an
54              Erlang runtime system can be started as follows:
55
56              % erl -name abc -s slave pseudo klacke@super x --
57
58       pseudo(Master, ServerList) -> ok
59
60              Types:
61
62                 Master = node()
63                 ServerList = [atom()]
64
65              Starts  a  number of pseudo servers. A pseudo server is a server
66              with a registered name that does nothing but pass on all message
67              to  the  real  server  that  executes at a master node. A pseudo
68              server is an intermediary that only has the same registered name
69              as the real server.
70
71              For example, if you have started a slave node N and want to exe‐
72              cute pxw graphics code  on  this  node,  you  can  start  server
73              pxw_server  as a pseudo server at the slave node. This is illus‐
74              trated as follows:
75
76              rpc:call(N, slave, pseudo, [node(), [pxw_server]]).
77
78       relay(Pid) -> no_return()
79
80              Types:
81
82                 Pid = pid()
83
84              Runs a pseudo server. This function never returns any value  and
85              the  process  that  executes the function receives messages. All
86              messages received are simply passed on to Pid.
87
88       start(Host) -> {ok, Node} | {error, Reason}
89
90       start(Host, Name) -> {ok, Node} | {error, Reason}
91
92       start(Host, Name, Args) -> {ok, Node} | {error, Reason}
93
94              Types:
95
96                 Host = inet:hostname()
97                 Name = atom() | string()
98                 Args = string()
99                 Node = node()
100                 Reason = timeout | no_rsh | {already_running, Node}
101
102              Starts a slave node on host Host. Host names need not  necessar‐
103              ily  be specified as fully qualified names; short names can also
104              be used. This is the same condition that  applies  to  names  of
105              distributed Erlang nodes.
106
107              The  name  of  the started node becomes Name@Host. If no name is
108              provided, the name becomes the same as the  node  that  executes
109              the call (except the host name part of the node name).
110
111              The  slave node resets its user process so that all terminal I/O
112              that is produced at the slave is automatically  relayed  to  the
113              master. Also, the file process is relayed to the master.
114
115              Argument Args is used to set erl command-line arguments. If pro‐
116              vided, it is passed to the new node and can be used for a  vari‐
117              ety of purposes; see erl(1).
118
119              As  an  example,  suppose that you want to start a slave node at
120              host H with node name Name@H and want the slave node to have the
121              following properties:
122
123                * Directory Dir is to be added to the code path.
124
125                * The Mnesia directory is to be set to M.
126
127                * The  Unix  DISPLAY  environment variable is to be set to the
128                  display of the master node.
129
130              The following code is executed to achieve this:
131
132              E = " -env DISPLAY " ++ net_adm:localhost() ++ ":0 ",
133              Arg = "-mnesia_dir " ++ M ++ " -pa " ++ Dir ++ E,
134              slave:start(H, Name, Arg).
135
136              The function returns {ok, Node}, where Node is the name  of  the
137              new node, otherwise {error, Reason}, where Reason can be one of:
138
139                timeout:
140                  The  master  node  failed  to  get in contact with the slave
141                  node. This can occur in a number of circumstances:
142
143                  * Erlang/OTP is not installed on the remote host.
144
145                  * The file system on the other host has a  different  struc‐
146                    ture to the the master.
147
148                  * The Erlang nodes have different cookies.
149
150                no_rsh:
151                  No remote shell program was found on the computer. Note that
152                  ssh is used by default, but this can be overridden with  the
153                  -rsh flag.
154
155                {already_running, Node}:
156                  A node with name Name@Host already exists.
157
158       start_link(Host) -> {ok, Node} | {error, Reason}
159
160       start_link(Host, Name) -> {ok, Node} | {error, Reason}
161
162       start_link(Host, Name, Args) -> {ok, Node} | {error, Reason}
163
164              Types:
165
166                 Host = inet:hostname()
167                 Name = atom() | string()
168                 Args = string()
169                 Node = node()
170                 Reason = timeout | no_rsh | {already_running, Node}
171
172              Starts  a slave node in the same way as start/1,2,3, except that
173              the slave node is linked to the currently executing process.  If
174              that process terminates, the slave node also terminates.
175
176              For   a   description   of  arguments  and  return  values,  see
177              start/1,2,3.
178
179       stop(Node) -> ok
180
181              Types:
182
183                 Node = node()
184
185              Stops (kills) a node.
186
187
188
189Ericsson AB                       stdlib 4.2                          slave(3)
Impressum