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

NAME

6       int - Interpreter Interface.
7

DESCRIPTION

9       The Erlang interpreter provides mechanisms for breakpoints and stepwise
10       execution of code. It is primarily intended to be used by Debugger, see
11       the User's Guide and debugger(3).
12
13       The following can be done from the shell:
14
15         * Specify the modules to be interpreted.
16
17         * Specify breakpoints.
18
19         * Monitor  the  current status of all processes executing code in in‐
20           terpreted modules, also processes at other Erlang nodes.
21
22       By attaching to a process executing interpreted code, it is possible to
23       examine variable bindings and order stepwise execution. This is done by
24       sending and receiving information to/from the process through  a  third
25       process,  called  the meta process. You can implement your own attached
26       process. See int.erl for available functions and  dbg_wx_trace.erl  for
27       possible messages.
28
29       The  interpreter  depends  on  the Kernel, STDLIB, and GS applications.
30       This means that modules belonging to any of these applications are  not
31       allowed  to  be interpreted, as it could lead to a deadlock or emulator
32       crash. This also applies to modules belonging to the Debugger  applica‐
33       tion.
34

BREAKPOINTS

36       Breakpoints  are  specified  on  a line basis. When a process executing
37       code in an interpreted module reaches  a  breakpoint,  it  stops.  This
38       means  that  a breakpoint must be set at an executable line, that is, a
39       code line containing an executable expression.
40
41       A breakpoint has the following:
42
43         * A status, which is active or inactive. An  inactive  breakpoint  is
44           ignored.
45
46         * A  trigger action. When a breakpoint is reached, the trigger action
47           specifies if the breakpoint is to continue as active  (enable),  or
48           to become inactive (disable), or to be removed (delete).
49
50         * Optionally  an  associated  condition. A condition is a tuple {Mod‐
51           ule,Name}. When the breakpoint is reached, Module:Name(Bindings) is
52           called.  If  it evaluates to true, execution stops. If it evaluates
53           to false, the breakpoint is ignored. Bindings contains the  current
54           variable  bindings. To retrieve the value for a specified variable,
55           use get_binding.
56
57       By default, a breakpoint is active, has trigger action enable, and  has
58       no  associated condition. For details about breakpoints, see the User's
59       Guide.
60

EXPORTS

62       i(AbsModule) -> {module,Module} | error
63       i(AbsModules) -> ok
64       ni(AbsModule) -> {module,Module} | error
65       ni(AbsModules) -> ok
66
67              Types:
68
69                 AbsModules = [AbsModule]
70                 AbsModule = Module | File | [Module | File]
71                  Module = atom()
72                  File = string()
73
74              Interprets the specified module(s). i/1  interprets  the  module
75              only  at  the  current  node.  ni/1 interprets the module at all
76              known nodes.
77
78              A module can be specified by its module name (atom) or filename.
79
80              If specified by its module name, the object code Module.beam  is
81              searched  for in the current path. The source code Module.erl is
82              searched for first in the same directory  as  the  object  code,
83              then in an src directory next to it.
84
85              If  specified  by  its filename, the filename can include a path
86              and the .erl extension can be  omitted.  The  object  code  Mod‐
87              ule.beam  is  searched  for  first  in the same directory as the
88              source code, then in an ebin directory next to it, and  then  in
89              the current path.
90
91          Note:
92              The  interpreter  requires  both  the source code and the object
93              code. The object code must include debug information,  that  is,
94              only  modules  compiled with option debug_info set can be inter‐
95              preted.
96
97
98              The functions returns {module,Module} if the module  was  inter‐
99              preted, otherwise error is returned.
100
101              The  argument  can  also  be  a list of modules or filenames, in
102              which case the function tries to interpret each module as speci‐
103              fied  earlier.  The  function then always returns ok, but prints
104              some information to stdout if a module cannot be interpreted.
105
106       n(AbsModule) -> ok
107       nn(AbsModule) -> ok
108
109              Types:
110
111                 AbsModule = Module | File | [Module | File]
112                  Module = atom()
113                  File = string()
114
115              Stops interpreting the specified module. n/1 stops  interpreting
116              the module only at the current node. nn/1 stops interpreting the
117              module at all known nodes.
118
119              As for i/1 and ni/1, a module can be  specified  by  its  module
120              name or filename.
121
122       interpreted() -> [Module]
123
124              Types:
125
126                 Module = atom()
127
128              Returns a list with all interpreted modules.
129
130       file(Module) -> File | {error,not_loaded}
131
132              Types:
133
134                 Module = atom()
135                 File = string()
136
137              Returns  the source code filename File for an interpreted module
138              Module.
139
140       interpretable(AbsModule) -> true | {error,Reason}
141
142              Types:
143
144                 AbsModule = Module | File
145                  Module = atom()
146                  File = string()
147                 Reason  =  no_src  |  no_beam  |  no_debug_info  |  badarg  |
148                 {app,App}
149                  App = atom()
150
151              Checks  if a module can be interpreted. The module can be speci‐
152              fied by its module name Module or its source filename  File.  If
153              specified  by  a  module name, the module is searched for in the
154              code path.
155
156              The function returns true if all of the following apply:
157
158                * Both source code and object code for the module is found.
159
160                * The module has been compiled with option debug_info set.
161
162                * The module does not belong to any of the  applications  Ker‐
163                  nel, STDLIB, GS, or Debugger.
164
165              The  function returns {error,Reason} if the module cannot be in‐
166              terpreted. Reason can have the following values:
167
168                no_src:
169                  No source code is found. It is assumed that the source  code
170                  and object code are located either in the same directory, or
171                  in src and ebin directories next to each other.
172
173                no_beam:
174                  No object code is found. It is assumed that the source  code
175                  and object code are located either in the same directory, or
176                  in src and ebin directories next to each other.
177
178                no_debug_info:
179                  The module has not been compiled with option debug_info set.
180
181                badarg:
182                  AbsModule is not found. This could be because the  specified
183                  file does not exist, or because code:which/1 does not return
184                  a BEAM filename, which is the case not only for non-existing
185                  modules  but  also  for modules that are preloaded or cover-
186                  compiled.
187
188                {app,App}:
189                  App is kernel, stdlib, gs, or debugger if AbsModule  belongs
190                  to one of these applications.
191
192              Notice  that  the  function can return true for a module that in
193              fact is not interpretable in the case where the module is marked
194              as sticky or resides in a directory marked as sticky. The reason
195              is that this is not discovered until the  interpreter  tries  to
196              load the module.
197
198       auto_attach() -> false | {Flags,Function}
199       auto_attach(false)
200       auto_attach(Flags, Function)
201
202              Types:
203
204                 Flags = [init | break | exit]
205                 Function = {Module,Name,Args}
206                  Module = Name = atom()
207                  Args = [term()]
208
209              Gets  and sets when and how to attach automatically to a process
210              executing code in interpreted modules. false means never  attach
211              automatically,  this  is the default. Otherwise automatic attach
212              is defined by a list of flags  and  a  function.  The  following
213              flags can be specified:
214
215                * init - Attach when a process for the first time calls an in‐
216                  terpreted function.
217
218                * break - Attach whenever a process reaches a breakpoint.
219
220                * exit - Attach when a process terminates.
221
222              When the specified event occurs, the function Function is called
223              as:
224
225              spawn(Module, Name, [Pid | Args])
226
227              Pid is the pid of the process executing interpreted code.
228
229       stack_trace() -> Flag
230       stack_trace(Flag)
231
232              Types:
233
234                 Flag = all | no_tail | false
235
236              Gets  and sets how to save call frames in the stack. Saving call
237              frames makes it possible to inspect the call chain of a process,
238              and  is also used to emulate the stack trace if an error (an ex‐
239              ception of class error) occurs. The following flags can be spec‐
240              ified:
241
242                all:
243                  Save  information about all current calls, that is, function
244                  calls that have not yet returned a value.
245
246                no_tail:
247                  Save information about current calls, but  discard  previous
248                  information  when a tail recursive call is made. This option
249                  consumes less memory and can be necessary to  use  for  pro‐
250                  cesses  with  long  lifetimes and many tail recursive calls.
251                  This is the default.
252
253                false:
254                  Save no information about current calls.
255
256       break(Module, Line) -> ok | {error,break_exists}
257
258              Types:
259
260                 Module = atom()
261                 Line = int()
262
263              Creates a breakpoint at Line in Module.
264
265       delete_break(Module, Line) -> ok
266
267              Types:
268
269                 Module = atom()
270                 Line = int()
271
272              Deletes the breakpoint at Line in Module.
273
274       break_in(Module, Name, Arity) -> ok | {error,function_not_found}
275
276              Types:
277
278                 Module = Name = atom()
279                 Arity = int()
280
281              Creates a breakpoint at the first line of every clause of  func‐
282              tion Module:Name/Arity.
283
284       del_break_in(Module, Name, Arity) -> ok | {error,function_not_found}
285
286              Types:
287
288                 Module = Name = atom()
289                 Arity = int()
290
291              Deletes  the  breakpoints  at  the first line of every clause of
292              function Module:Name/Arity.
293
294       no_break() -> ok
295       no_break(Module) -> ok
296
297              Deletes all breakpoints, or all breakpoints in Module.
298
299       disable_break(Module, Line) -> ok
300
301              Types:
302
303                 Module = atom()
304                 Line = int()
305
306              Makes the breakpoint at Line in Module inactive.
307
308       enable_break(Module, Line) -> ok
309
310              Types:
311
312                 Module = atom()
313                 Line = int()
314
315              Makes the breakpoint at Line in Module active.
316
317       action_at_break(Module, Line, Action) -> ok
318
319              Types:
320
321                 Module = atom()
322                 Line = int()
323                 Action = enable | disable | delete
324
325              Sets the trigger action of the breakpoint at Line in  Module  to
326              Action.
327
328       test_at_break(Module, Line, Function) -> ok
329
330              Types:
331
332                 Module = atom()
333                 Line = int()
334                 Function = {Module,Name}
335                  Name = atom()
336
337              Sets the conditional test of the breakpoint at Line in Module to
338              Function. The function must fulfill the  requirements  specified
339              in section Breakpoints.
340
341       get_binding(Var, Bindings) -> {value,Value} | unbound
342
343              Types:
344
345                 Var = atom()
346                 Bindings = term()
347                 Value = term()
348
349              Retrieves  the  binding  of Var. This function is intended to be
350              used by the conditional function of a breakpoint.
351
352       all_breaks() -> [Break]
353       all_breaks(Module) -> [Break]
354
355              Types:
356
357                 Break = {Point,Options}
358                  Point = {Module,Line}
359                  Module = atom()
360                  Line = int()
361                  Options = [Status,Trigger,null,Cond|]
362                  Status = active | inactive
363                  Trigger = enable | disable | delete
364                  Cond = null | Function
365                  Function = {Module,Name}
366                  Name = atom()
367
368              Gets all breakpoints, or all breakpoints in Module.
369
370       snapshot() -> [Snapshot]
371
372              Types:
373
374                 Snapshot = {Pid, Function, Status, Info}
375                  Pid = pid()
376                  Function = {Module,Name,Args}
377                  Module = Name = atom()
378                  Args = [term()]
379                  Status = idle | running | waiting | break | exit | no_conn
380                  Info = {} | {Module,Line} | ExitReason
381                  Line = int()
382                  ExitReason = term()
383
384              Gets information about all processes executing interpreted code.
385
386                * Pid - Process identifier.
387
388                * Function - First interpreted function called by the process.
389
390                * Status - Current status of the process.
391
392                * Info - More information.
393
394              Status is one of the following:
395
396                * idle - The process is no longer executing interpreted  code.
397                  Info={}.
398
399                * running - The process is running. Info={}.
400
401                * waiting - The process is waiting at a receive. Info={}.
402
403                * break  -  Process execution is stopped, normally at a break‐
404                  point. Info={Module,Line}.
405
406                * exit - The process is terminated. Info=ExitReason.
407
408                * no_conn - The connection is  down  to  the  node  where  the
409                  process is running. Info={}.
410
411       clear() -> ok
412
413              Clears information about processes executing interpreted code by
414              removing all information about terminated processes.
415
416       continue(Pid) -> ok | {error,not_interpreted}
417       continue(X,Y,Z) -> ok | {error,not_interpreted}
418
419              Types:
420
421                 Pid = pid()
422                 X = Y = Z = int()
423
424              Resumes process execution for Pid or c:pid(X,Y,Z).
425
426
427
428Ericsson AB                      debugger 5.3                           int(3)
Impressum