1int(3) Erlang Module Definition int(3)
2
6 int - Interpreter Interface.
7
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 The following can be done from the shell:
14 * Specify the modules to be interpreted.
16 * Specify breakpoints.
18 * Monitor the current status of all processes executing code in in‐
20 terpreted modules, also processes at other Erlang nodes.
21 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 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
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 A breakpoint has the following:
42 * A status, which is active or inactive. An inactive breakpoint is
44 ignored.
45 * 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 * 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 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
62 i(AbsModule) -> {module,Module} | error
63 i(AbsModules) -> ok
64 ni(AbsModule) -> {module,Module} | error
65 ni(AbsModules) -> ok
66 Types:
68 AbsModules = [AbsModule]
70 AbsModule = Module | File | [Module | File]
71 Module = atom()
72 File = string()
73 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 A module can be specified by its module name (atom) or filename.
79 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 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 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 The functions returns {module,Module} if the module was inter‐
99 preted, otherwise error is returned.
100 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 n(AbsModule) -> ok
107 nn(AbsModule) -> ok
108 Types:
110 AbsModule = Module | File | [Module | File]
112 Module = atom()
113 File = string()
114 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 As for i/1 and ni/1, a module can be specified by its module
120 name or filename.
121 interpreted() -> [Module]
123 Types:
125 Module = atom()
127 Returns a list with all interpreted modules.
129 file(Module) -> File | {error,not_loaded}
131 Types:
133 Module = atom()
135 File = string()
136 Returns the source code filename File for an interpreted module
138 Module.
139 interpretable(AbsModule) -> true | {error,Reason}
141 Types:
143 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 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 The function returns true if all of the following apply:
157 * Both source code and object code for the module is found.
159 * The module has been compiled with option debug_info set.
161 * The module does not belong to any of the applications Ker‐
163 nel, STDLIB, GS, or Debugger.
164 The function returns {error,Reason} if the module cannot be in‐
166 terpreted. Reason can have the following values:
167 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 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 no_debug_info:
179 The module has not been compiled with option debug_info set.
180 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 {app,App}:
189 App is kernel, stdlib, gs, or debugger if AbsModule belongs
190 to one of these applications.
191 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 auto_attach() -> false | {Flags,Function}
199 auto_attach(false)
200 auto_attach(Flags, Function)
201 Types:
203 Flags = [init | break | exit]
205 Function = {Module,Name,Args}
206 Module = Name = atom()
207 Args = [term()]
208 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 * init - Attach when a process for the first time calls an in‐
216 terpreted function.
217 * break - Attach whenever a process reaches a breakpoint.
219 * exit - Attach when a process terminates.
221 When the specified event occurs, the function Function is called
223 as:
224 spawn(Module, Name, [Pid | Args])
226 Pid is the pid of the process executing interpreted code.
228 stack_trace() -> Flag
230 stack_trace(Flag)
231 Types:
233 Flag = all | no_tail | false
235 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 all:
243 Save information about all current calls, that is, function
244 calls that have not yet returned a value.
245 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 false:
254 Save no information about current calls.
255 break(Module, Line) -> ok | {error,break_exists}
257 Types:
259 Module = atom()
261 Line = int()
262 Creates a breakpoint at Line in Module.
264 delete_break(Module, Line) -> ok
266 Types:
268 Module = atom()
270 Line = int()
271 Deletes the breakpoint at Line in Module.
273 break_in(Module, Name, Arity) -> ok | {error,function_not_found}
275 Types:
277 Module = Name = atom()
279 Arity = int()
280 Creates a breakpoint at the first line of every clause of func‐
282 tion Module:Name/Arity.
283 del_break_in(Module, Name, Arity) -> ok | {error,function_not_found}
285 Types:
287 Module = Name = atom()
289 Arity = int()
290 Deletes the breakpoints at the first line of every clause of
292 function Module:Name/Arity.
293 no_break() -> ok
295 no_break(Module) -> ok
296 Deletes all breakpoints, or all breakpoints in Module.
298 disable_break(Module, Line) -> ok
300 Types:
302 Module = atom()
304 Line = int()
305 Makes the breakpoint at Line in Module inactive.
307 enable_break(Module, Line) -> ok
309 Types:
311 Module = atom()
313 Line = int()
314 Makes the breakpoint at Line in Module active.
316 action_at_break(Module, Line, Action) -> ok
318 Types:
320 Module = atom()
322 Line = int()
323 Action = enable | disable | delete
324 Sets the trigger action of the breakpoint at Line in Module to
326 Action.
327 test_at_break(Module, Line, Function) -> ok
329 Types:
331 Module = atom()
333 Line = int()
334 Function = {Module,Name}
335 Name = atom()
336 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 get_binding(Var, Bindings) -> {value,Value} | unbound
342 Types:
344 Var = atom()
346 Bindings = term()
347 Value = term()
348 Retrieves the binding of Var. This function is intended to be
350 used by the conditional function of a breakpoint.
351 all_breaks() -> [Break]
353 all_breaks(Module) -> [Break]
354 Types:
356 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 Gets all breakpoints, or all breakpoints in Module.
369 snapshot() -> [Snapshot]
371 Types:
373 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 Gets information about all processes executing interpreted code.
385 * Pid - Process identifier.
387 * Function - First interpreted function called by the process.
389 * Status - Current status of the process.
391 * Info - More information.
393 Status is one of the following:
395 * idle - The process is no longer executing interpreted code.
397 Info={}.
398 * running - The process is running. Info={}.
400 * waiting - The process is waiting at a receive. Info={}.
402 * break - Process execution is stopped, normally at a break‐
404 point. Info={Module,Line}.
405 * exit - The process is terminated. Info=ExitReason.
407 * no_conn - The connection is down to the node where the
409 process is running. Info={}.
410 clear() -> ok
412 Clears information about processes executing interpreted code by
414 removing all information about terminated processes.
415 continue(Pid) -> ok | {error,not_interpreted}
417 continue(X,Y,Z) -> ok | {error,not_interpreted}
418 Types:
420 Pid = pid()
422 X = Y = Z = int()
423 Resumes process execution for Pid or c:pid(X,Y,Z).
425Ericsson AB debugger 5.2 int(3)