OpenCores
URL https://opencores.org/ocsvn/or1k/or1k/trunk

Subversion Repositories or1k

[/] [or1k/] [trunk/] [insight/] [gdb/] [doc/] [libgdb.texinfo] - Blame information for rev 1774

Go to most recent revision | Details | Compare with Previous | View Log

Line No. Rev Author Line
1 578 markom
\input texinfo   @c -*-texinfo-*-
2
@c %**start of header
3
@setfilename libgdb.info
4
@settitle Libgdb
5
@setchapternewpage off
6
@c %**end of header
7
 
8
@ifinfo
9
This file documents libgdb, the GNU symbolic debugger in a library.
10
 
11
This is Edition 0.3, Oct 1993, of @cite{Libgdb}.
12
Copyright 1993 Cygnus Support
13
 
14
Permission is granted to make and distribute verbatim copies of
15
this manual provided the copyright notice and this permission notice
16
are preserved on all copies.
17
 
18
@ignore
19
Permission is granted to process this file through TeX and print the
20
results, provided the printed document carries copying permission
21
notice identical to this one except for the removal of this paragraph
22
(this paragraph not being relevant to the printed manual).
23
 
24
@end ignore
25
Permission is granted to copy and distribute modified versions of this
26
manual under the conditions for verbatim copying, provided also that the
27
entire resulting derived work is distributed under the terms of a
28
permission notice identical to this one.
29
 
30
Permission is granted to copy and distribute translations of this manual
31
into another language, under the above conditions for modified versions.
32
@end ifinfo
33
 
34
@c  This title page illustrates only one of the
35
@c  two methods of forming a title page.
36
 
37
@titlepage
38
@title Libgdb
39
@subtitle Version 0.3
40
@subtitle Oct 1993
41
@author Thomas Lord
42
 
43
@c  The following two commands
44
@c  start the copyright page.
45
@page
46
@vskip 0pt plus 1filll
47
Permission is granted to make and distribute verbatim copies of
48
this manual provided the copyright notice and this permission notice
49
are preserved on all copies.
50
 
51
Copyright @copyright{} 1993 Cygnus Support
52
@end titlepage
53
 
54
@ifinfo
55
@node Top, Overview, (dir), (dir)
56
 
57
This info file documents libgdb: an API for GDB, the GNU symbolic debugger.
58
 
59
@menu
60
* Overview::                 The basics of libgdb and this document.
61
* Interpreter::              Libgdb is an Interpreter-Based Server.
62
* Top Level::                You Provide the Top Level for the Libgdb
63
                                Command Interpreter .
64
* I/O::                      How the Server's I/O Can be Used.
65
* Invoking::                 Invoking the Interpreter, Executing
66
                                Commands.
67
* Defining Commands::        How New Commands are Created.
68
* Variables::                How Builtin Variables are Defined.
69
* Asynchronous::             Scheduling Asynchronous Computations.
70
* Commands::                 Debugger Commands for Libgdb Applications
71
@end menu
72
 
73
@end ifinfo
74
@node    Overview, Interpreter, top,      top
75
@comment node-name,     next,           previous, up
76
@chapter Overview
77
@cindex overview
78
@cindex definitions
79
 
80
@heading Function and Purpose
81
 
82
Libgdb is a package which provides an API to the functionality of GDB,
83
the GNU symbolic debugger.  It is specifically intended to support the
84
development of a symbolic debugger with a graphic interface.
85
 
86
 
87
@heading This Document
88
 
89
This document is a specification of the libgdb API.  It is written in
90
the form of a programmer's manual.  So the goal of this document is to
91
explain what functions make up the API, and how they can be used in a
92
running application.
93
 
94
 
95
@heading Terminology
96
 
97
In this document, @dfn{libgdb} refers to a library containing the
98
functions defined herein, @dfn{application} refers to any program built
99
with that library.
100
 
101
 
102
@heading Dependencies
103
 
104
Programs which are linked with libgdb must be linked with libbfd,
105
libopcodes, libiberty, and libmmalloc.
106
 
107
@heading Acknowledgments
108
 
109
Essential contributions to this design were made by Stu Grossman, Jim
110
Kingdon, and Rich Pixley.
111
 
112
@node Interpreter, Top Level, Overview, Top
113
@comment  node-name,  next,  previous,  up
114
@chapter Libgdb is an Interpreter Based Server
115
@cindex interpreter
116
@cindex server
117
 
118
To understand libgdb, it is necessary to understand how the library is
119
structured.  Historically, GDB is written as a small interpreter for a
120
simple command language.  The commands of the language perform useful
121
debugging functions.
122
 
123
Libgdb is built from GDB by turning the interpreter into a debugging
124
server.  The server reads debugging commands from any source and
125
interprets them, directing the output arbitrarily.
126
 
127
In addition to changing GDB from a tty-based program to a server, a
128
number of new GDB commands have been added to make the server more
129
useful for a program with a graphic interface.
130
 
131
Finally, libgdb includes provisions for asynchronous processing within
132
the application.
133
 
134
Most operations that can be carried out with libgdb involve the GDB
135
command interpreter.  The usual mode of operation is that the operation
136
is expressed as a string of GDB commands, which the interpreter is then
137
invoked to carry out.  The output from commands executed in this manner
138
can be redirected in a variety of useful ways for further processing by
139
the application.
140
 
141
The command interpreter provides an extensive system of hooks so an
142
application can monitor any aspect of the debugging library's state.  An
143
application can set its own breakpoints and attach commands and
144
conditions to those.  It is possible to attach hooks to any debugger
145
command; the hooks are invoked whenever that command is about to be
146
invoked.  By means of these, the displays of a graphical interface can
147
be kept fully up to date at all times.
148
 
149
We show you how to define new primitives in the command language.  By
150
defining new primitives and using them in breakpoint scripts and command
151
hooks, an application can schedule the execution of arbitrary C-code at
152
almost any point of interest in the operation of libgdb.
153
 
154
We show you how to define new GDB convenience variables for which your
155
code computes a value on demand.  Referring to such variables in a
156
breakpoint condition is a convenient way to conditionalize breakpoints
157
in novel ways.
158
 
159
To summarize: in libgdb, the gdb command language is turned into a
160
debugging server.  The server takes commands as input, and the server's
161
output is redirectable.  An application uses libgdb by formatting
162
debugging commands and invoking the interpreter.  The application might
163
maintain breakpoints, watchpoints and many kinds of hooks.  An application
164
can define new primitives for the interpreter.
165
 
166
@node Top Level, I/O, Interpreter, Top
167
@chapter You Provide the Top Level for the Libgdb Command Interpreter
168
@cindex {top level}
169
 
170
When you use libgdb, your code is providing a @dfn{top level} for the
171
command language interpreter.  The top level is significant because it
172
provides commands for the the interpreter to execute.  In addition, the
173
top level is responsible for handling some kinds of errors, and
174
performing certain cleanup operations on behalf of the interpreter.
175
 
176
@heading Initialization
177
 
178
Before calling any other libgdb functions, call this:
179
 
180
@deftypefun void gdb_init (void)
181
Perform one-time initialization for libgdb.
182
@end deftypefun
183
 
184
An application may wish to evaluate specific gdb commands as part of its
185
own initialization.  The details of how this can be accomplished are
186
explained below.
187
 
188
@heading The Top-Level Loop
189
 
190
There is a strong presumption in libgdb that the application has
191
the form of a loop.  Here is what such a loop might look like:
192
 
193
@example
194
while (gdb_still_going ())
195
  @{
196
    if (!GDB_TOP_LEVEL ())
197
      @{
198
        char * command;
199
        gdb_start_top_loop ();
200
        command = process_events ();
201
        gdb_execute_command (command);
202
        gdb_finish_top_loop ();
203
      @}
204
    @}
205
@end example
206
 
207
The function @code{gdb_still_going} returns 1 until the gdb command
208
`quit' is run.
209
 
210
The macro @code{GDB_TOP_LEVEL} invokes setjmp to set the top level error
211
handler.  When a command results in an error, the interpreter exits with
212
a longjmp. There is nothing special libgdb requires of the top level
213
error handler other than it be present and that it restart the top level
214
loop.  Errors are explained in detail in a later chapter.
215
 
216
Each time through the top level loop two important things happen: a
217
debugger command is constructed on the basis of user input, and the
218
interpreter is invoked to execute that command.  In the sample code, the
219
call to the imaginary function @code{process_events} represents the
220
point at which a graphical interface should read input events until
221
ready to execute a debugger command.  The call to
222
@code{gdb_execute_command} invokes the command interpreter (what happens
223
to the output from the command will be explained later).
224
 
225
Libgdb manages some resources using the top-level loop.  The primary
226
reason for this is error-handling: even if a command terminates with an
227
error, it may already have allocated resources which need to be freed.
228
The freeing of such resources takes place at the top-level, regardless
229
of how the the command exits.  The calls to @code{gdb_start_top_loop}
230
and @code{gdb_finish_top_loop} let libgdb know when it is safe to
231
perform operations associated with these resources.
232
 
233
@heading Breakpoint Commands
234
 
235
Breakpoint commands are scripts of GDB operations associated with
236
particular breakpoints.  When a breakpoint is reached, its associated
237
commands are executed.
238
 
239
Breakpoint commands are invoked by the libgdb function
240
@code{gdb_finish_top_loop}.
241
 
242
Notice that if control returns to the top-level error handler, the
243
execution of breakpoint commands is bypassed.  This can happen as a
244
result of errors during either @code{gdb_execute_command} or
245
@code{gdb_finish_top_loop}.
246
 
247
@heading Application Initialization
248
 
249
Sometimes it is inconvenient to execute commands via a command loop for
250
example, the commands an application uses to initialize itself.  An
251
alternative to @code{execute_command} is @code{execute_catching_errors}.
252
When @code{execute_catching_errors} is used, no top level error handler
253
need be in effect, and it is not necessary to call
254
@code{gdb_start_top_loop} or @code{gdb_finish_top_loop}.
255
 
256
 
257
@heading Cleanup
258
 
259
The debugger command ``quit'' performs all necessary cleanup for libgdb.
260
After it has done so, it changes the return value of
261
@code{gdb_still_going} to 0 and returns to the top level error handler.
262
 
263
 
264
@node I/O, Invoking, Top Level, Top
265
@comment  node-name,  next,  previous,  up
266
@chapter How the Server's I/O Can be Used
267
@cindex I/O
268
 
269
In the last chapter it was pointed out that a libgdb application is
270
responsible for providing commands for the interpreter to execute.
271
However some commands require further input (for example, the ``quit''
272
command might ask for confirmation).  Almost all commands produce output
273
of some kind.  The purpose of this section is to explain how libgdb
274
performs its I/O, and how an application can take advantage of
275
this.
276
 
277
 
278
@heading I/O Vectors
279
 
280
Libgdb has no fixed strategy for I/O.  Instead, all operations are
281
performed by functions called via structures of function pointers.
282
Applications supply theses structures and can change them at any
283
time.
284
 
285
@deftp Type {struct gdb_input_vector}
286
@deftpx Type {struct gdb_output_vector}
287
These structures contain a set of function pointers.  Each function
288
determines how a particular type of i/o is performed.  The details of
289
these strucutres are explained below.
290
 
291
The application allocates these structures, initializes them to all bits
292
zero, fills in the function pointers, and then registers names for them
293
them with libgdb.
294
@end deftp
295
 
296
@deftypefun void gdb_name_input_vector (@var{name}, @var{vec})
297
@deftypefunx void gdb_remove_input_vector (@var{name}, @var{vec})
298
@deftypefunx void gdb_name_output_vector (@var{name}, @var{vec})
299
@deftypefunx void gdb_remove_input_vector (@var{name}, @var{vec})
300
@example
301
  char * @var{name};
302
  struct gdb_output_vector * @var{vec};
303
@end example
304
These functions are used to give and remove names to i/o vectors.  Note
305
that if a name is used twice, the most recent definition applies.
306
@end deftypefun
307
 
308
 
309
 
310
@subheading Output
311
 
312
An output vector is a structure with at least these fields:
313
 
314
@example
315
struct gdb_output_vector
316
@{
317
  /* output */
318
  void (*put_string) (struct gdb_output_vector *, char * str);
319
@}
320
@end example
321
 
322
Use the function @code{memset} or something equivalent to initialize an
323
output vector to all bits zero.  Then fill in the function pointer with
324
your function.
325
 
326
A debugger command can produce three kinds of output: error messages
327
(such as when trying to delete a non-existent breakpoint), informational
328
messages (such as the notification printed when a breakpoint is hit),
329
and the output specifically requested by a command (for example, the
330
value printed by the ``print'' command).  At any given time, then,
331
libgdb has three output vectors.  These are called the @dfn{error},
332
@dfn{info}, @dfn{value} vector respectively.
333
 
334
@subheading Input
335
 
336
@example
337
struct gdb_input_vector
338
@{
339
  int (*query) (struct gdb_input_vector *,
340
                char * prompt,
341
                int quit_allowed);
342
  int * (*selection) (struct gdb_input_vector *,
343
                      char * prompt,
344
                      char ** choices);
345
  char * (*read_string) (struct gdb_input_vector *,
346
                         char * prompt);
347
  char ** (*read_strings) (struct gdb_input_vector *,
348
                           char * prompt);
349
@}
350
@end example
351
 
352
Use the function @code{memset} or something equivalent to initialize an
353
input vector to all bits zero.  Then fill in the function pointers with
354
your functions.
355
 
356
There are four kinds of input requests explicitly made by libgdb.
357
 
358
A @dfn{query} is a yes or no question.  The user can respond to a query
359
with an affirmative or negative answer, or by telling gdb to abort the
360
command (in some cases an abort is not permitted).  Query should return
361
'y' or 'n' or 0 to abort.
362
 
363
A @dfn{selection} is a list of options from which the user selects a subset.
364
Selections should return a NULL terminated array of integers, which are
365
indexes into the array of choices.  It can return NULL instead to abort
366
the command.  The array returned by this function will be passed to
367
@code{free} by libgdb.
368
 
369
A @dfn{read_string} asks the user to supply an arbitrary string.  It may
370
return NULL to abort the command.  The string returned by @code{read_string}
371
should be allocated by @code{malloc}; it will be freed by libgdb.
372
 
373
A @dfn{read_strings} asks the user to supply multiple lines of input
374
(for example, the body of a command created using `define').  It, too,
375
may return NULL to abort.  The array and the strings returned by this
376
function will be freed by libgdb.
377
 
378
@heading I/O Redirection from the Application Top-Level
379
 
380
@deftypefun struct gdb_io_vecs gdb_set_io (struct gdb_io_vecs *)
381
@example
382
 
383
struct gdb_io_vecs
384
@{
385
  struct gdb_input_vector * input;
386
  struct gdb_output_vector * error;
387
  struct gdb_output_vector * info;
388
  struct gdb_output_vector * value;
389
@}
390
@end example
391
 
392
This establishes a new set of i/o vectors, and returns the old setting.
393
Any of the pointers in this structure may be NULL, indicating that the
394
current value should be used.
395
 
396
This function is useful for setting up i/o vectors before any libgdb
397
commands have been invoked (hence before any input or output has taken
398
place).
399
@end deftypefun
400
 
401
It is explained in a later chapter how to redirect output temporarily.
402
(@xref{Invoking}.)
403
 
404
@heading I/O Redirection in Debugger Commands
405
 
406
A libgdb application creates input and output vectors and assigns them names.
407
Which input and output vectors are used by libgdb is established by
408
executing these debugger commands:
409
 
410
@defun {set input-vector} name
411
@defunx {set error-output-vector} name
412
@defunx {set info-output-vector} name
413
@defunx {set value-output-vector} name
414
Choose an I/O vector by name.
415
@end defun
416
 
417
 
418
A few debugger commands are for use only within commands defined using
419
the debugger command `define' (they have no effect at other times).
420
These commands exist so that an application can maintain hooks which
421
redirect output without affecting the global I/O vectors.
422
 
423
@defun with-input-vector name
424
@defunx with-error-output-vector name
425
@defunx with-info-output-vector name
426
@defunx with-value-output-vector name
427
Set an I/O vector, but only temporarily.  The setting has effect only
428
within the command definition in which it occurs.
429
@end defun
430
 
431
 
432
@heading Initial Conditions
433
 
434
When libgdb is initialized, a set of default I/O vectors is put in
435
place.  The default vectors are called @code{default-input-vector},
436
@code{default-output-vector}, &c.
437
 
438
The default query function always returns `y'.  Other input functions
439
always abort.  The default output functions discard output silently.
440
 
441
 
442
@node Invoking, Defining Commands, I/O, Top
443
@chapter Invoking the Interpreter, Executing Commands
444
@cindex {executing commands}
445
@cindex {invoking the interpreter}
446
 
447
This section introduces the libgdb functions which invoke the command
448
interpreter.
449
 
450
@deftypefun void gdb_execute_command (@var{command})
451
@example
452
char * @var{command};
453
@end example
454
Interpret the argument debugger command.  An error handler must be set
455
when this function is called. (@xref{Top Level}.)
456
@end deftypefun
457
 
458
It is possible to override the current I/O vectors for the duration of a
459
single command:
460
 
461
@deftypefun void gdb_execute_with_io (@var{command}, @var{vecs})
462
@example
463
char * @var{command};
464
struct gdb_io_vecs * @var{vecs};
465
 
466
struct gdb_io_vecs
467
@{
468
  struct gdb_input_vector * input;
469
  struct gdb_output_vector * error;
470
  struct gdb_output_vector * info;
471
  struct gdb_output_vector * value;
472
@}
473
@end example
474
 
475
Execute @var{command}, temporarily using the i/o vectors in @var{vecs}.
476
 
477
Any of the vectors may be NULL, indicating that the current value should
478
be used.  An error handler must be in place when this function is used.
479
@end deftypefun
480
 
481
@deftypefun {struct gdb_str_output} gdb_execute_for_strings (@var{cmd})
482
@example
483
char * cmd;
484
@end example
485
@deftypefunx {struct gdb_str_output} gdb_execute_for_strings2 (@var{cmd}, @var{input})
486
@example
487
char * cmd;
488
struct gdb_input_vector * input;
489
@end example
490
@page
491
@example
492
struct gdb_str_output
493
@{
494
  char * error;
495
  char * info;
496
  char * value;
497
@};
498
@end example
499
 
500
Execute @var{cmd}, collecting its output as strings.  If no error
501
occurs, all three strings will be present in the structure, the
502
empty-string rather than NULL standing for no output of a particular
503
kind.
504
 
505
If the command aborts with an error, then the @code{value} field will be
506
NULL, though the other two strings will be present.
507
 
508
In all cases, the strings returned are allocated by malloc and should be
509
freed by the caller.
510
 
511
The first form listed uses the current input vector, but overrides the
512
current output vector.  The second form additionally allows the input
513
vector to be overridden.
514
 
515
This function does not require that an error handler be installed.
516
@end deftypefun
517
 
518
@deftypefun void execute_catching_errors (@var{command})
519
@example
520
char * @var{command};
521
@end example
522
Like @code{execute_command} except that no error handler is required.
523
@end deftypefun
524
 
525
@deftypefun void execute_with_text (@var{command}, @var{text})
526
@example
527
char * @var{command};
528
char ** @var{text};
529
@end example
530
Like @code{execute_catching_errors}, except that the input vector is
531
overridden.  The new input vector handles only calls to @code{query} (by
532
returning 'y') and calls to @code{read_strings} by returning a copy of
533
@var{text} and the strings it points to.
534
 
535
This form of execute_command is useful for commands like @code{define},
536
@code{document}, and @code{commands}.
537
@end deftypefun
538
 
539
 
540
 
541
@node Defining Commands, Variables, Invoking, Top
542
@comment  node-name,  next,  previous,  up
543
@chapter How New Commands are Created
544
@cindex {commands, defining}
545
 
546
Applications are, of course, free to take advantage of the existing GDB
547
macro definition capability (the @code{define} and @code{document}
548
functions).
549
 
550
In addition, an application can add new primitives to the GDB command
551
language.
552
 
553
@deftypefun void gdb_define_app_command (@var{name}, @var{fn}, @var{doc})
554
@example
555
char * @var{name};
556
gdb_cmd_fn @var{fn};
557
char * @var{doc};
558
 
559
typedef void (*gdb_cmd_fn) (char * args);
560
@end example
561
 
562
Create a new command call @var{name}.  The new command is in the
563
@code{application} help class.  When invoked, the command-line arguments
564
to the command are passed as a single string.
565
 
566
Calling this function twice with the same name replaces an earlier
567
definition, but application commands can not replace builtin commands of
568
the same name.
569
 
570
The documentation string of the command is set to a copy the string
571
@var{doc}.
572
@end deftypefun
573
 
574
@node Variables, Asynchronous, Defining Commands, Top
575
@comment  node-name,  next,  previous,  up
576
@chapter How Builtin Variables are Defined
577
@cindex {variables, defining}
578
 
579
Convenience variables provide a way for values maintained by libgdb to
580
be referenced in expressions (e.g. @code{$bpnum}).  Libgdb includes a
581
means by which the application can define new, integer valued
582
convenience variables:
583
@page
584
@deftypefun void gdb_define_int_var (@var{name}, @var{fn}, @var{fn_arg})
585
@example
586
char * @var{name};
587
int (*@var{fn}) (void *);
588
void * @var{fn_arg};
589
@end example
590
This function defines (or undefines) a convenience variable called @var{name}.
591
If @var{fn} is NULL, the variable becomes undefined.  Otherwise,
592
@var{fn} is a function which, when passed @var{fn_arg} returns the value
593
of the newly defined variable.
594
 
595
No libgdb functions should be called by @var{fn}.
596
@end deftypefun
597
 
598
One use for this function is to create breakpoint conditions computed in
599
novel ways.  This is done by defining a convenience variable and
600
referring to that variable in a breakpoint condition expression.
601
 
602
 
603
@node Asynchronous, Commands, Variables, Top
604
@chapter Scheduling Asynchronous Computations
605
@cindex asynchronous
606
 
607
 
608
A running libgdb function can take a long time.  Libgdb includes a hook
609
so that an application can run intermittently during long debugger
610
operations.
611
 
612
@deftypefun void gdb_set_poll_fn (@var{fn}, @var{fn_arg})
613
@example
614
void (*@var{fn})(void * fn_arg, int (*gdb_poll)());
615
void * @var{fn_arg};
616
@end example
617
Arrange to call @var{fn} periodically during lengthy debugger operations.
618
If @var{fn} is NULL, polling is turned off.  @var{fn} should take two
619
arguments: an opaque pointer passed as @var{fn_arg} to
620
@code{gdb_set_poll_fn}, and a function pointer.  The function pointer
621
passed to @var{fn} is provided by libgdb and points to a function that
622
returns 0 when the poll function should return.  That is, when
623
@code{(*gdb_poll)()} returns 0, libgdb is ready to continue @var{fn}
624
should return quickly.
625
 
626
It is possible that @code{(*gdb_poll)()} will return 0 the first time it
627
is called, so it is reasonable for an application to do minimal processing
628
before checking whether to return.
629
 
630
No libgdb functions should be called from an application's poll function,
631
with one exception: @code{gdb_request_quit}.
632
@end deftypefun
633
 
634
 
635
@deftypefun void gdb_request_quit (void)
636
This function, if called from a poll function, requests that the
637
currently executing libgdb command be interrupted as soon as possible,
638
and that control be returned to the top-level via an error.
639
 
640
The quit is not immediate.  It will not occur until at least after the
641
application's poll function returns.
642
@end deftypefun
643
 
644
@node Commands, Top, Asynchronous, Top
645
@comment  node-name,  next,  previous,  up
646
@chapter Debugger Commands for Libgdb Applications
647
 
648
The debugger commands available to libgdb applications are the same commands
649
available interactively via GDB.  This section is an overview of the
650
commands newly created as part of libgdb.
651
 
652
This section is not by any means a complete reference to the GDB command
653
language.  See the GDB manual for such a reference.
654
 
655
@menu
656
* Command Hooks::    Setting Hooks to Execute With Debugger Commands.
657
* View Commands::    View Commands Mirror Show Commands
658
* Breakpoints::      The Application Can Have Its Own Breakpoints
659
@end menu
660
 
661
@node Command Hooks, View Commands, Commands, Commands
662
@comment  node-name,  next,  previous,  up
663
@section Setting Hooks to Execute With Debugger Commands.
664
 
665
Debugger commands support hooks.  A command hook is executed just before
666
the interpreter invokes the hooked command.
667
 
668
There are two hooks allowed for every command.  By convention, one hook
669
is for use by users, the other is for use by the application.
670
 
671
A user hook is created for a command XYZZY by using
672
@code{define-command} to create a command called @code{hook-XYZZY}.
673
 
674
An application hook is created for a command XYZZY by using
675
@code{define-command} to create a command called @code{apphook-XYZZY}.
676
 
677
Application hooks are useful for interfaces which wish to continuously
678
monitor certain aspects of debugger state.  The application can set a
679
hook on all commands that might modify the watched state.  When the hook
680
is executed, it can use i/o redirection to notify parts of the
681
application that previous data may be out of date.  After the top-level loop
682
resumes, the application can recompute any values that may have changed.
683
(@xref{I/O}.)
684
 
685
@node View Commands, Breakpoints, Command Hooks, Commands
686
@comment  node-name,  next,  previous,  up
687
@section View Commands Mirror Show Commands
688
 
689
The GDB command language contains many @code{set} and @code{show}
690
commands.  These commands are used to modify or examine parameters to
691
the debugger.
692
 
693
It is difficult to get the current state of a parameter from the
694
@code{show} command because @code{show} is very verbose.
695
 
696
@example
697
(gdb) show check type
698
Type checking is "auto; currently off".
699
(gdb) show width
700
Number of characters gdb thinks are in a line is 80.
701
@end example
702
 
703
For every @code{show} command, libgdb includes a @code{view} command.
704
@code{view} is like @code{show} without the verbose commentary:
705
 
706
@example
707
(gdb) view check type
708
auto; currently off
709
(gdb) view width
710
80
711
@end example
712
 
713
(The precise format of the ouput from @code{view} is subject to change.
714
In particular, @code{view} may one-day print values which can be used as
715
arguments to the corresponding @code{set} command.)
716
 
717
@node Breakpoints, Structured Output, View Commands, Commands
718
@comment  node-name,  next,  previous,  up
719
@section The Application Can Have Its Own Breakpoints
720
 
721
The GDB breakpoint commands were written with a strong presumption that
722
all breakpoints are managed by a human user.  Therefore, the command
723
language contains commands like `delete' which affect all breakpoints
724
without discrimination.
725
 
726
In libgdb, there is added support for breakpoints and watchpoints which
727
are set by the application and which should not be affected by ordinary,
728
indiscriminate commands.  These are called @dfn{protected} breakpoints.
729
 
730
@deffn {Debugger Command} break-protected ...
731
@deffnx {Debugger Command} watch-protected ...
732
These work like @code{break} and @code{watch} except that the resulting
733
breakpoint is given a negative number.  Negative numbered breakpoints do
734
not appear in the output of @code{info breakpoints} but do in that of
735
@code{info all-breakpoints}.  Negative numbered breakpoints are not
736
affected by commands which ordinarily affect `all' breakpoints (e.g.
737
@code{delete} with no arguments).
738
 
739
Note that libgdb itself creates protected breakpoints, so programs
740
should not rely on being able to allocate particular protected
741
breakpoint numbers for themselves.
742
@end deffn
743
 
744
More than one breakpoint may be set at a given location.  Libgdb adds
745
the concept of @dfn{priority} to breakpoints.  A priority is an integer,
746
assigned to each breakpoint.  When a breakpoint is reached, the
747
conditions of all breakpoints at the same location are evaluated in
748
order of ascending priority.  When breakpoint commands are executed,
749
they are also executed in ascending priority (until all have been
750
executed, an error occurs, or one set of commands continues the
751
target).
752
 
753
@deffn {Debugger Command} priority n bplist
754
Set the priority for breakpoints @var{bplist} to @var{n}.
755
By default, breakpoints are assigned a priority of zero.
756
@end deffn
757
 
758
@node Structured Output, Commands, Breakpoints, Commands
759
@comment  node-name,  next,  previous,  up
760
@section  Structured Output, The @code{Explain} Command
761
 
762
(This section may be subject to considerable revision.)
763
 
764
When GDB prints a the value of an expression, the printed representation
765
contains information that can be usefully fed back into future commands
766
and expressions.  For example,
767
 
768
@example
769
(gdb) print foo
770
$16 = @{v = 0x38ae0, v_length = 40@}
771
@end example
772
 
773
On the basis of this output, a user knows, for example, that
774
@code{$16.v} refers to a pointer valued @code{0x38ae0}
775
 
776
A new output command helps to make information like this available to
777
the application.
778
 
779
@deffn {Debugger Command} explain expression
780
@deffnx {Debugger Command} explain /format expression
781
Print the value of @var{expression} in the manner of the @code{print}
782
command, but embed that output in a list syntax containing information
783
about the structure of the output.
784
@end deffn
785
 
786
As an example, @code{explain argv} might produce this output:
787
 
788
@example
789
(exp-attribute
790
   ((expression "$19")
791
    (type "char **")
792
    (address "48560")
793
    (deref-expression "*$19"))
794
   "$19 = 0x3800\n")
795
@end example
796
 
797
The syntax of output from @code{explain} is:
798
 
799
@example
800
<explanation> :=    <quoted-string>
801
                  | (exp-concat <explanation> <explanation>*)
802
                  | (exp-attribute <property-list> <explanation>)
803
 
804
<property-list> := ( <property-pair>* )
805
 
806
<property-pair> := ( <property-name> <quoted-string> )
807
@end example
808
 
809
The string-concatenation of all of the @code{<quoted-string>} (except
810
those in property lists) yields the output generated by the equivalent
811
@code{print} command.  Quoted strings may contain quotes and backslashes
812
if they are escaped by backslash.  "\n" in a quoted string stands for
813
newline; unescaped newlines do not occur within the strings output by
814
@code{explain}.
815
 
816
Property names are made up of alphabetic characters, dashes, and
817
underscores.
818
 
819
The set of properties is open-ended.  As GDB acquires support for new
820
source languages and other new capabilities, new property types may be
821
added to the output of this command.  Future commands may offer
822
applications some selectivity concerning which properties are reported.
823
 
824
The initial set of properties defined includes:
825
 
826
@itemize @bullet
827
@item @code{expression}
828
 
829
This is an expression, such as @code{$42} or @code{$42.x}.  The
830
expression can be used to refer to the value printed in the attributed
831
part of the string.
832
 
833
@item @code{type}
834
 
835
This is a user-readable name for the type of the attributed value.
836
 
837
@item @code{address}
838
 
839
If the value is stored in a target register, this is a register number.
840
If the value is stored in a GDB convenience variable, this is an integer
841
that is unique among all the convenience variables.  Otherwise, this is
842
the address in the target where the value is stored.
843
 
844
@item @code{deref-expression}
845
 
846
If the attributed value is a pointer type, this is an expression that
847
refers to the dereferenced value.
848
@end itemize
849
 
850
Here is a larger example, using the same object passed to @code{print}
851
in an earlier example of this section.
852
 
853
@example
854
(gdb) explain foo
855
(exp-attribute
856
  ( (expression "$16")
857
    (type "struct bytecode_vector")
858
    (address 14336) )
859
  (exp-concat
860
    "$16 = @{"
861
    (exp-attribute
862
      ( (expression "$16.v")
863
        (type "char *")
864
        (address 14336)
865
        (deref-expression "*$16.v") )
866
      "v = 0x38ae0")
867
    (exp-attribute
868
      ( (expression "$16.v_length")
869
        (type "int")
870
        (address 14340) )
871
      ", v_length = 40")
872
     "@}\n"))
873
@end example
874
 
875
It is undefined how libgdb will indent these lines of output or
876
where newlines will be included.
877
 
878
@bye

powered by: WebSVN 2.1.0

© copyright 1999-2024 OpenCores.org, equivalent to Oliscience, all rights reserved. OpenCores®, registered trademark.