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

Subversion Repositories or1k

[/] [or1k/] [trunk/] [gdb-5.0/] [gdb/] [doc/] [gdb.info-11] - Blame information for rev 362

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

Line No. Rev Author Line
1 362 markom
This is ./gdb.info, produced by makeinfo version 4.0 from gdb.texinfo.
2 106 markom
 
3
INFO-DIR-SECTION Programming & development tools.
4
START-INFO-DIR-ENTRY
5
* Gdb: (gdb).                     The GNU debugger.
6
END-INFO-DIR-ENTRY
7
 
8
   This file documents the GNU debugger GDB.
9
 
10
   This is the Eighth Edition, March 2000, of `Debugging with GDB: the
11
GNU Source-Level Debugger' for GDB Version 5.0.
12
 
13
   Copyright (C) 1988-2000 Free Software Foundation, Inc.
14
 
15
   Permission is granted to make and distribute verbatim copies of this
16
manual provided the copyright notice and this permission notice are
17
preserved on all copies.
18
 
19
   Permission is granted to copy and distribute modified versions of
20
this manual under the conditions for verbatim copying, provided also
21
that the entire resulting derived work is distributed under the terms
22
of a permission notice identical to this one.
23
 
24
   Permission is granted to copy and distribute translations of this
25
manual into another language, under the above conditions for modified
26
versions.
27
 
28

29
File: gdb.info,  Node: GDB/MI Stack Manipulation,  Next: GDB/MI Symbol Query,  Prev: GDB/MI Miscellaneous Commands,  Up: GDB/MI
30
 
31
Stack manipulation commands in GDB/MI
32
=====================================
33
 
34
The `-stack-info-frame' Command
35
-------------------------------
36
 
37
Synopsis
38
........
39
 
40
      -stack-info-frame
41
 
42
   Get info on the current frame.
43
 
44
GDB Command
45
...........
46
 
47
   The corresponding GDB command is `info frame' or `frame' (without
48
arguments).
49
 
50
Example
51
.......
52
 
53
   N.A.
54
 
55
The `-stack-info-depth' Command
56
-------------------------------
57
 
58
Synopsis
59
........
60
 
61
      -stack-info-depth [ MAX-DEPTH ]
62
 
63
   Return the depth of the stack.  If the integer argument MAX-DEPTH is
64
specified, do not count beyond MAX-DEPTH frames.
65
 
66
GDB Command
67
...........
68
 
69
   There's no equivalent GDB command.
70
 
71
Example
72
.......
73
 
74
   For a stack with frame levels 0 through 11:
75
 
76
     (gdb)
77
     -stack-info-depth
78
     ^done,depth="12"
79
     (gdb)
80
     -stack-info-depth 4
81
     ^done,depth="4"
82
     (gdb)
83
     -stack-info-depth 12
84
     ^done,depth="12"
85
     (gdb)
86
     -stack-info-depth 11
87
     ^done,depth="11"
88
     (gdb)
89
     -stack-info-depth 13
90
     ^done,depth="12"
91
     (gdb)
92
 
93
The `-stack-list-arguments' Command
94
-----------------------------------
95
 
96
Synopsis
97
........
98
 
99
      -stack-list-arguments SHOW-VALUES
100
         [ LOW-FRAME HIGH-FRAME ]
101
 
102
   Display a list of the arguments for the frames between LOW-FRAME and
103
HIGH-FRAME (inclusive).  If LOW-FRAME and HIGH-FRAME are not provided,
104
list the arguments for the whole call stack.
105
 
106
   The SHOW-VALUES argument must have a value of 0 or 1.  A value of 0
107
means that only the names of the arguments are listed, a value of 1
108
means that both names and values of the arguments are printed.
109
 
110
GDB Command
111
...........
112
 
113
   GDB does not have an equivalent command.  `gdbtk' has a
114
`gdb_get_args' command which partially overlaps with the functionality
115
of `-stack-list-arguments'.
116
 
117
Example
118
.......
119
 
120
     (gdb)
121
     -stack-list-frames
122
     ^done,
123
     stack={
124
     frame={level="0 ",addr="0x00010734",func="callee4",
125
     file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"},
126
     frame={level="1 ",addr="0x0001076c",func="callee3",
127
     file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="17"},
128
     frame={level="2 ",addr="0x0001078c",func="callee2",
129
     file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="22"},
130
     frame={level="3 ",addr="0x000107b4",func="callee1",
131
     file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="27"},
132
     frame={level="4 ",addr="0x000107e0",func="main",
133
     file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="32"}}
134
     (gdb)
135
     -stack-list-arguments 0
136
     ^done,
137
     stack-args={
138
     frame={level="0",args={}},
139
     frame={level="1",args={name="strarg"}},
140
     frame={level="2",args={name="intarg",name="strarg"}},
141
     frame={level="3",args={name="intarg",name="strarg",name="fltarg"}},
142
     frame={level="4",args={}}}
143
     (gdb)
144
     -stack-list-arguments 1
145
     ^done,
146
     stack-args={
147
     frame={level="0",args={}},
148
     frame={level="1",
149
      args={{name="strarg",value="0x11940 \"A string argument.\""}}},
150
     frame={level="2",args={
151
     {name="intarg",value="2"},
152
     {name="strarg",value="0x11940 \"A string argument.\""}}},
153
     {frame={level="3",args={
154
     {name="intarg",value="2"},
155
     {name="strarg",value="0x11940 \"A string argument.\""},
156
     {name="fltarg",value="3.5"}}},
157
     frame={level="4",args={}}}
158
     (gdb)
159
     -stack-list-arguments 0 2 2
160
     ^done,stack-args={frame={level="2",args={name="intarg",name="strarg"}}}
161
     (gdb)
162
     -stack-list-arguments 1 2 2
163
     ^done,stack-args={frame={level="2",
164
     args={{name="intarg",value="2"},
165
     {name="strarg",value="0x11940 \"A string argument.\""}}}}
166
     (gdb)
167
 
168
The `-stack-list-frames' Command
169
--------------------------------
170
 
171
Synopsis
172
........
173
 
174
      -stack-list-frames [ LOW-FRAME HIGH-FRAME ]
175
 
176
   List the frames currently on the stack.  For each frame it displays
177
the following info:
178
 
179
`LEVEL'
180
     The frame number, 0 being the topmost frame, i.e. the innermost
181
     function.
182
 
183
`ADDR'
184
     The `$pc' value for that frame.
185
 
186
`FUNC'
187
     Function name.
188
 
189
`FILE'
190
     File name of the source file where the function lives.
191
 
192
`LINE'
193
     Line number corresponding to the `$pc'.
194
 
195
   If invoked without arguments, this command prints a backtrace for the
196
whole stack.  If given two integer arguments, it shows the frames whose
197
levels are between the two arguments (inclusive).  If the two arguments
198
are equal, it shows the single frame at the corresponding level.
199
 
200
GDB Command
201
...........
202
 
203
   The corresponding GDB commands are `backtrace' and `where'.
204
 
205
Example
206
.......
207
 
208
   Full stack backtrace:
209
 
210
     (gdb)
211
     -stack-list-frames
212
     ^done,stack=
213
     {frame={level="0 ",addr="0x0001076c",func="foo",
214
       file="recursive2.c",line="11"},
215
     frame={level="1 ",addr="0x000107a4",func="foo",
216
       file="recursive2.c",line="14"},
217
     frame={level="2 ",addr="0x000107a4",func="foo",
218
       file="recursive2.c",line="14"},
219
     frame={level="3 ",addr="0x000107a4",func="foo",
220
       file="recursive2.c",line="14"},
221
     frame={level="4 ",addr="0x000107a4",func="foo",
222
       file="recursive2.c",line="14"},
223
     frame={level="5 ",addr="0x000107a4",func="foo",
224
       file="recursive2.c",line="14"},
225
     frame={level="6 ",addr="0x000107a4",func="foo",
226
       file="recursive2.c",line="14"},
227
     frame={level="7 ",addr="0x000107a4",func="foo",
228
       file="recursive2.c",line="14"},
229
     frame={level="8 ",addr="0x000107a4",func="foo",
230
       file="recursive2.c",line="14"},
231
     frame={level="9 ",addr="0x000107a4",func="foo",
232
       file="recursive2.c",line="14"},
233
     frame={level="10",addr="0x000107a4",func="foo",
234
       file="recursive2.c",line="14"},
235
     frame={level="11",addr="0x00010738",func="main",
236
       file="recursive2.c",line="4"}}
237
     (gdb)
238
 
239
   Show frames between low_frame and high_frame:
240
 
241
     (gdb)
242
     -stack-list-frames 3 5
243
     ^done,stack=
244
     {frame={level="3 ",addr="0x000107a4",func="foo",
245
       file="recursive2.c",line="14"},
246
     frame={level="4 ",addr="0x000107a4",func="foo",
247
       file="recursive2.c",line="14"},
248
     frame={level="5 ",addr="0x000107a4",func="foo",
249
       file="recursive2.c",line="14"}}
250
     (gdb)
251
 
252
   Show a single frame:
253
 
254
     (gdb)
255
     -stack-list-frames 3 3
256
     ^done,stack=
257
     {frame={level="3 ",addr="0x000107a4",func="foo",
258
       file="recursive2.c",line="14"}}
259
     (gdb)
260
 
261
The `-stack-list-locals' Command
262
--------------------------------
263
 
264
Synopsis
265
........
266
 
267
      -stack-list-locals PRINT-VALUES
268
 
269
   Display the local variable names for the current frame.  With an
270
argument of 0 prints only the names of the variables, with argument of 1
271
prints also their values.
272
 
273
GDB Command
274
...........
275
 
276
   `info locals' in GDB, `gdb_get_locals' in `gdbtk'.
277
 
278
Example
279
.......
280
 
281
     (gdb)
282
     -stack-list-locals 0
283
     ^done,locals={name="A",name="B",name="C"}
284
     (gdb)
285
     -stack-list-locals 1
286
     ^done,locals={{name="A",value="1"},{name="B",value="2"},
287
       {name="C",value="3"}}
288
     (gdb)
289
 
290
The `-stack-select-frame' Command
291
---------------------------------
292
 
293
Synopsis
294
........
295
 
296
      -stack-select-frame FRAMENUM
297
 
298
   Change the current frame.  Select a different frame FRAMENUM on the
299
stack.
300
 
301
GDB Command
302
...........
303
 
304
   The corresponding GDB commands are `frame', `up', `down',
305
`select-frame', `up-silent', and `down-silent'.
306
 
307
Example
308
.......
309
 
310
     (gdb)
311
     -stack-select-frame 2
312
     ^done
313
     (gdb)
314
 
315

316
File: gdb.info,  Node: GDB/MI Symbol Query,  Next: GDB/MI Target Manipulation,  Prev: GDB/MI Stack Manipulation,  Up: GDB/MI
317
 
318
GDB/MI Symbol Query Commands
319
============================
320
 
321
The `-symbol-info-address' Command
322
----------------------------------
323
 
324
Synopsis
325
........
326
 
327
      -symbol-info-address SYMBOL
328
 
329
   Describe where SYMBOL is stored.
330
 
331
GDB Command
332
...........
333
 
334
   The corresponding GDB command is `info address'.
335
 
336
Example
337
.......
338
 
339
   N.A.
340
 
341
The `-symbol-info-file' Command
342
-------------------------------
343
 
344
Synopsis
345
........
346
 
347
      -symbol-info-file
348
 
349
   Show the file for the symbol.
350
 
351
GDB Command
352
...........
353
 
354
   There's no equivalent GDB command.  `gdbtk' has `gdb_filnd_file'.
355
 
356
Example
357
.......
358
 
359
   N.A.
360
 
361
The `-symbol-info-function' Command
362
-----------------------------------
363
 
364
Synopsis
365
........
366
 
367
      -symbol-info-function
368
 
369
   Show which function the symbol lives in.
370
 
371
GDB Command
372
...........
373
 
374
   `gdb_get_function' in `gdbtk'.
375
 
376
Example
377
.......
378
 
379
   N.A.
380
 
381
The `-symbol-info-line' Command
382
-------------------------------
383
 
384
Synopsis
385
........
386
 
387
      -symbol-info-line
388
 
389
   Show the core addresses of the code for a source line.
390
 
391
GDB Command
392
...........
393
 
394
   The corresponding GDB comamnd is `info line'.  `gdbtk' has the
395
`gdb_get_line' `gdb_get_file' commands.
396
 
397
Example
398
.......
399
 
400
   N.A.
401
 
402
The `-symbol-info-symbol' Command
403
---------------------------------
404
 
405
Synopsis
406
........
407
 
408
      -symbol-info-symbol ADDR
409
 
410
   Describe what symbol is at location ADDR.
411
 
412
GDB Command
413
...........
414
 
415
   The corresponding GDB command is `info symbol'.
416
 
417
Example
418
.......
419
 
420
   N.A.
421
 
422
The `-symbol-list-functions' Command
423
------------------------------------
424
 
425
Synopsis
426
........
427
 
428
      -symbol-list-functions
429
 
430
   List the functions in the executable.
431
 
432
GDB Command
433
...........
434
 
435
   `info functions' in GDB, `gdb_listfunc' `gdb_search' in `gdbtk'.
436
 
437
Example
438
.......
439
 
440
   N.A.
441
 
442
The `-symbol-list-types' Command
443
--------------------------------
444
 
445
Synopsis
446
........
447
 
448
      -symbol-list-types
449
 
450
   List all the type names.
451
 
452
GDB Command
453
...........
454
 
455
   The corresponding commands are `info types' in GDB, `gdb_search' in
456
`gdbtk'.
457
 
458
Example
459
.......
460
 
461
   N.A.
462
 
463
The `-symbol-list-variables' Command
464
------------------------------------
465
 
466
Synopsis
467
........
468
 
469
      -symbol-list-variables
470
 
471
   List all the global and static variable names.
472
 
473
GDB Command
474
...........
475
 
476
   `info variables' in GDB, `gdb_search' in `gdbtk'.
477
 
478
Example
479
.......
480
 
481
   N.A.
482
 
483
The `-symbol-locate' Command
484
----------------------------
485
 
486
Synopsis
487
........
488
 
489
      -symbol-locate
490
 
491
GDB Command
492
...........
493
 
494
   `gdb_loc' in `gdbtk'.
495
 
496
Example
497
.......
498
 
499
   N.A.
500
 
501
The `-symbol-type' Command
502
--------------------------
503
 
504
Synopsis
505
........
506
 
507
      -symbol-type VARIABLE
508
 
509
   Show type of VARIABLE.
510
 
511
GDB Command
512
...........
513
 
514
   The corresponding GDB command is `ptype', `gdbtk' has
515
`gdb_obj_variable'.
516
 
517
Example
518
.......
519
 
520
   N.A.
521
 
522

523
File: gdb.info,  Node: GDB/MI Target Manipulation,  Next: GDB/MI Thread Commands,  Prev: GDB/MI Symbol Query,  Up: GDB/MI
524
 
525
GDB/MI Target Manipulation Commands
526
===================================
527
 
528
The `-target-attach' Command
529
----------------------------
530
 
531
Synopsis
532
........
533
 
534
      -target-attach PID | FILE
535
 
536
   Attach to a process PID or a file FILE outside of GDB.
537
 
538
GDB command
539
...........
540
 
541
   The corresponding GDB command is `attach'.
542
 
543
Example
544
.......
545
 
546
   N.A.
547
 
548
The `-target-compare-sections' Command
549
--------------------------------------
550
 
551
Synopsis
552
........
553
 
554
      -target-compare-sections [ SECTION ]
555
 
556
   Compare data of section SECTION on target to the exec file.  Without
557
the argument, all sections are compared.
558
 
559
GDB Command
560
...........
561
 
562
   The GDB equivalent is `compare-sections'.
563
 
564
Example
565
.......
566
 
567
   N.A.
568
 
569
The `-target-detach' Command
570
----------------------------
571
 
572
Synopsis
573
........
574
 
575
      -target-detach
576
 
577
   Disconnect from the remote target.  There's no output.
578
 
579
GDB command
580
...........
581
 
582
   The corresponding GDB command is `detach'.
583
 
584
Example
585
.......
586
 
587
     (gdb)
588
     -target-detach
589
     ^done
590
     (gdb)
591
 
592
The `-target-download' Command
593
------------------------------
594
 
595
Synopsis
596
........
597
 
598
      -target-download
599
 
600
   Loads the executable onto the remote target.  It prints out an
601
update message every half second, which includes the fields:
602
 
603
`section'
604
     The name of the section.
605
 
606
`section-sent'
607
     The size of what has been sent so far for that section.
608
 
609
`section-size'
610
     The size of the section.
611
 
612
`total-sent'
613
     The total size of what was sent so far (the current and the
614
     previous sections).
615
 
616
`total-size'
617
     The size of the overall executable to download.
618
 
619
Each message is sent as status record (*note GDB/MI Output Syntax:
620
GDB/MI Output Syntax.).
621
 
622
   In addition, it prints the name and size of the sections, as they are
623
downloaded.  These messages include the following fields:
624
 
625
`section'
626
     The name of the section.
627
 
628
`section-size'
629
     The size of the section.
630
 
631
`total-size'
632
     The size of the overall executable to download.
633
 
634
At the end,  a summary is printed.
635
 
636
GDB Command
637
...........
638
 
639
   The corresponding GDB command is `load'.
640
 
641
Example
642
.......
643
 
644
   Note: each status message appears on a single line.  Here the
645
messages have been broken down so that they can fit onto a page.
646
 
647
     (gdb)
648
     -target-download
649
     +download,{section=".text",section-size="6668",total-size="9880"}
650
     +download,{section=".text",section-sent="512",section-size="6668",
651
     total-sent="512",total-size="9880"}
652
     +download,{section=".text",section-sent="1024",section-size="6668",
653
     total-sent="1024",total-size="9880"}
654
     +download,{section=".text",section-sent="1536",section-size="6668",
655
     total-sent="1536",total-size="9880"}
656
     +download,{section=".text",section-sent="2048",section-size="6668",
657
     total-sent="2048",total-size="9880"}
658
     +download,{section=".text",section-sent="2560",section-size="6668",
659
     total-sent="2560",total-size="9880"}
660
     +download,{section=".text",section-sent="3072",section-size="6668",
661
     total-sent="3072",total-size="9880"}
662
     +download,{section=".text",section-sent="3584",section-size="6668",
663
     total-sent="3584",total-size="9880"}
664
     +download,{section=".text",section-sent="4096",section-size="6668",
665
     total-sent="4096",total-size="9880"}
666
     +download,{section=".text",section-sent="4608",section-size="6668",
667
     total-sent="4608",total-size="9880"}
668
     +download,{section=".text",section-sent="5120",section-size="6668",
669
     total-sent="5120",total-size="9880"}
670
     +download,{section=".text",section-sent="5632",section-size="6668",
671
     total-sent="5632",total-size="9880"}
672
     +download,{section=".text",section-sent="6144",section-size="6668",
673
     total-sent="6144",total-size="9880"}
674
     +download,{section=".text",section-sent="6656",section-size="6668",
675
     total-sent="6656",total-size="9880"}
676
     +download,{section=".init",section-size="28",total-size="9880"}
677
     +download,{section=".fini",section-size="28",total-size="9880"}
678
     +download,{section=".data",section-size="3156",total-size="9880"}
679
     +download,{section=".data",section-sent="512",section-size="3156",
680
     total-sent="7236",total-size="9880"}
681
     +download,{section=".data",section-sent="1024",section-size="3156",
682
     total-sent="7748",total-size="9880"}
683
     +download,{section=".data",section-sent="1536",section-size="3156",
684
     total-sent="8260",total-size="9880"}
685
     +download,{section=".data",section-sent="2048",section-size="3156",
686
     total-sent="8772",total-size="9880"}
687
     +download,{section=".data",section-sent="2560",section-size="3156",
688
     total-sent="9284",total-size="9880"}
689
     +download,{section=".data",section-sent="3072",section-size="3156",
690
     total-sent="9796",total-size="9880"}
691
     ^done,address="0x10004",load-size="9880",transfer-rate="6586",
692
     write-rate="429"
693
     (gdb)
694
 
695
The `-target-exec-status' Command
696
---------------------------------
697
 
698
Synopsis
699
........
700
 
701
      -target-exec-status
702
 
703
   Provide information on the state of the target (whether it is
704
running or not, for instance).
705
 
706
GDB Command
707
...........
708
 
709
   There's no equivalent GDB command.
710
 
711
Example
712
.......
713
 
714
   N.A.
715
 
716
The `-target-list-available-targets' Command
717
--------------------------------------------
718
 
719
Synopsis
720
........
721
 
722
      -target-list-available-targets
723
 
724
   List the possible targets to connect to.
725
 
726
GDB Command
727
...........
728
 
729
   The corresponding GDB command is `help target'.
730
 
731
Example
732
.......
733
 
734
   N.A.
735
 
736
The `-target-list-current-targets' Command
737
------------------------------------------
738
 
739
Synopsis
740
........
741
 
742
      -target-list-current-targets
743
 
744
   Describe the current target.
745
 
746
GDB Command
747
...........
748
 
749
   The corresponding information is printed by `info file' (among other
750
things).
751
 
752
Example
753
.......
754
 
755
   N.A.
756
 
757
The `-target-list-parameters' Command
758
-------------------------------------
759
 
760
Synopsis
761
........
762
 
763
      -target-list-parameters
764
 
765
GDB Command
766
...........
767
 
768
   No equivalent.
769
 
770
Example
771
.......
772
 
773
   N.A.
774
 
775
The `-target-select' Command
776
----------------------------
777
 
778
Synopsis
779
........
780
 
781
      -target-select TYPE PARAMETERS ...
782
 
783
   Connect GDB to the remote target.  This command takes two args:
784
 
785
`TYPE'
786
     The type of target, for instance `async', `remote', etc.
787
 
788
`PARAMETERS'
789
     Device names, host names and the like.  *Note Commands for
790
     managing targets: Target Commands, for more details.
791
 
792
   The output is a connection notification, followed by the address at
793
which the target program is, in the following form:
794
 
795
     ^connected,addr="ADDRESS",func="FUNCTION NAME",
796
       args={ARG LIST}
797
 
798
GDB Command
799
...........
800
 
801
   The corresponding GDB command is `target'.
802
 
803
Example
804
.......
805
 
806
     (gdb)
807
     -target-select async /dev/ttya
808
     ^connected,addr="0xfe00a300",func="??",args={}
809
     (gdb)
810
 
811

812
File: gdb.info,  Node: GDB/MI Thread Commands,  Next: GDB/MI Tracepoint Commands,  Prev: GDB/MI Target Manipulation,  Up: GDB/MI
813
 
814
GDB/MI Thread Commands
815
======================
816
 
817
The `-thread-info' Command
818
--------------------------
819
 
820
Synopsis
821
........
822
 
823
      -thread-info
824
 
825
GDB command
826
...........
827
 
828
   No equivalent.
829
 
830
Example
831
.......
832
 
833
   N.A.
834
 
835
The `-thread-list-all-threads' Command
836
--------------------------------------
837
 
838
Synopsis
839
........
840
 
841
      -thread-list-all-threads
842
 
843
GDB Command
844
...........
845
 
846
   The equivalent GDB command is `info threads'.
847
 
848
Example
849
.......
850
 
851
   N.A.
852
 
853
The `-thread-list-ids' Command
854
------------------------------
855
 
856
Synopsis
857
........
858
 
859
      -thread-list-ids
860
 
861
   Produces a list of the currently known gdb thread ids.  At the end
862
of the list it also prints the total number of such threads.
863
 
864
GDB Command
865
...........
866
 
867
   Part of `info threads' supplies the same information.
868
 
869
Example
870
.......
871
 
872
   No threads present, besides the main process.
873
 
874
     (gdb)
875
     -thread-list-ids
876
     ^done,thread-ids={},number-of-threads="0"
877
     (gdb)
878
 
879
   Several threads.
880
 
881
     (gdb)
882
     -thread-list-ids
883
     ^done,thread-ids={thread-id="3",thread-id="2",thread-id="1"},
884
     number-of-threads="3"
885
     (gdb)
886
 
887
The `-thread-select' Command
888
----------------------------
889
 
890
Synopsis
891
........
892
 
893
      -thread-select THREADNUM
894
 
895
   Make THREADNUM the current thread.  It prints the number of the new
896
current thread, and the topmost frame for that thread.
897
 
898
GDB Command
899
...........
900
 
901
   The corresponding GDB command is `thread'.
902
 
903
Example
904
.......
905
 
906
     (gdb)
907
     -exec-next
908
     ^running
909
     (gdb)
910
     *stopped,reason="end-stepping-range",thread-id="2",line="187",
911
     file="../../../devo/gdb/testsuite/gdb.threads/linux-dp.c"
912
     (gdb)
913
     -thread-list-ids
914
     ^done,
915
     thread-ids={thread-id="3",thread-id="2",thread-id="1"},
916
     number-of-threads="3"
917
     (gdb)
918
     -thread-select 3
919
     ^done,new-thread-id="3",
920
     frame={level="0 ",func="vprintf",
921
     args={{name="format",value="0x8048e9c \"%*s%c %d %c\\n\""},
922
     {name="arg",value="0x2"}},file="vprintf.c",line="31"}
923
     (gdb)
924
 
925

926
File: gdb.info,  Node: GDB/MI Tracepoint Commands,  Next: GDB/MI Variable Objects,  Prev: GDB/MI Thread Commands,  Up: GDB/MI
927
 
928
GDB/MI Tracepoint Commands
929
==========================
930
 
931
   The tracepoint commands are not yet implemented.
932
 
933

934
File: gdb.info,  Node: GDB/MI Variable Objects,  Next: GDB/MI Draft Changes to Output Syntax,  Prev: GDB/MI Tracepoint Commands,  Up: GDB/MI
935
 
936
GDB/MI Variable Objects
937
=======================
938
 
939
Motivation for Variable Objects in GDB/MI
940
-----------------------------------------
941
 
942
   For the implementation of a variable debugger window (locals, watched
943
expressions, etc.), we are proposing the adaptation of the existing code
944
used by `Insight'.
945
 
946
   The two main reasons for that are:
947
 
948
  1. It has been proven in practice (it is already on its second
949
     generation).
950
 
951
  2. It will shorten development time (needless to say how important it
952
     is now).
953
 
954
   The original interface was designed to be used by Tcl code, so it was
955
slightly changed so it could be used through flathead.  This document
956
describes the flathead operations that will be available and gives some
957
hints about their use.
958
 
959
   _Note_: In addition to the set of operations described here, we
960
expect the GUI implementation of a variable window to require, at
961
least, the following operations:
962
 
963
   * -gdb-show output-radix
964
 
965
   * -stack-list-arguments
966
 
967
   * -stack-list-locals
968
 
969
   * -stack-select-frame
970
 
971
Introduction to Variable Objects in GDB/MI
972
------------------------------------------
973
 
974
   The basic idea behind variable objects is the creation of a named
975
object to represent a variable, an expression, a memory location or
976
even a CPU register.  For each object created, a set of operations is
977
available for examining or changing its properties.
978
 
979
   Furthermore, complex data types, such as C structures, are
980
represented in a tree format.  For instance, the `struct' type variable
981
is the root and the children will represent the struct members.  If a
982
child is itself of a complex type, it will also have children of its
983
own.  Appropriate language differences are handled for C, C++ and Java.
984
 
985
   When returning the actual values of the objects, this facility allows
986
for the individual selection of the display format used in the result
987
creation.  It can be chosen among: binary, decimal, hexadecimal, octal
988
and natural.  Natural refers to a default format automatically chosen
989
based on the variable type (like decimal for an `int', hex for
990
pointers, etc.).
991
 
992
   The following is the complete set of flathead operations defined to
993
access this functionality:
994
 
995 362 markom
*Operation*            *Description*
996
-var-create            create a variable object
997
-var-delete            delete the variable object and its children
998
-var-set-format        set the display format of this variable
999
-var-show-format       show the display format of this variable
1000
-var-info-num-children tells how many children this object has
1001
-var-list-children     return a list of the object's children
1002
-var-info-type         show the type of this variable object
1003
-var-info-expression   print what this variable object represents
1004
-var-show-attributes   is this variable editable? does it exist
1005
                       here?
1006
-var-evaluate-expressionget the value of this variable
1007
-var-assign            set the value of this variable
1008
-var-update            update the variable and its children
1009 106 markom
 
1010
   In the next subsection we describe each operation in detail and
1011
suggest how it can be used.
1012
 
1013
Description And Use of Operations on Variable Objects
1014
-----------------------------------------------------
1015
 
1016
The `-var-create' Command
1017
-------------------------
1018
 
1019
Synopsis
1020
........
1021
 
1022
      -var-create {NAME | "-"}
1023
         {FRAME-ADDR | "*"} EXPRESSION
1024
 
1025
   This operation creates a variable object, which allows the
1026
monitoring of a variable, the result of an expression, a memory cell or
1027
a CPU register.
1028
 
1029
   The NAME parameter is the string by which the object can be
1030
referenced.  It must be unique.  If `-' is specified, the varobj system
1031
will generate a string "varNNNNNN" automatically.  It will be unique
1032
provided that one does not specify NAME on that format.  The command
1033
fails if a duplicate name is found.
1034
 
1035
   The frame under which the expression should be evaluated can be
1036
specified by FRAME-ADDR.  A `*' indicates that the current frame should
1037
be used.
1038
 
1039
   EXPRESSION is any expression valid on the current language set (must
1040
not begin with a `*'), or one of the following:
1041
 
1042
   * `*ADDR', where ADDR is the address of a memory cell
1043
 
1044
   * `*ADDR-ADDR' - a memory address range (TBD)
1045
 
1046
   * `$REGNAME' - a CPU register name
1047
 
1048
Result
1049
......
1050
 
1051
   This operation returns the name, number of children and the type of
1052
the object created.  Type is returned as a string as the ones generated
1053
by the GDB CLI:
1054
 
1055
      name="NAME",numchild="N",type="TYPE"
1056
 
1057
The `-var-delete' Command
1058
-------------------------
1059
 
1060
Synopsis
1061
........
1062
 
1063
      -var-delete NAME
1064
 
1065
   Deletes a previously created variable object and all of its children.
1066
 
1067
   Returns an error if the object NAME is not found.
1068
 
1069
The `-var-set-format' Command
1070
-----------------------------
1071
 
1072
Synopsis
1073
........
1074
 
1075
      -var-set-format NAME FORMAT-SPEC
1076
 
1077
   Sets the output format for the value of the object NAME to be
1078
FORMAT-SPEC.
1079
 
1080
   The syntax for the FORMAT-SPEC is as follows:
1081
 
1082
      FORMAT-SPEC ==>
1083
      {binary | decimal | hexadecimal | octal | natural}
1084
 
1085
The `-var-show-format' Command
1086
------------------------------
1087
 
1088
Synopsis
1089
........
1090
 
1091
      -var-show-format NAME
1092
 
1093
   Returns the format used to display the value of the object NAME.
1094
 
1095
      format ==>
1096
      FORMAT-SPEC
1097
 
1098
The `-var-info-num-children' Command
1099
------------------------------------
1100
 
1101
Synopsis
1102
........
1103
 
1104
      -var-info-num-children NAME
1105
 
1106
   Returns the number of children of a variable object NAME:
1107
 
1108
      numchild=N
1109
 
1110
The `-var-list-children' Command
1111
--------------------------------
1112
 
1113
Synopsis
1114
........
1115
 
1116
      -var-list-children NAME
1117
 
1118
   Returns a list of the children of the specified variable object:
1119
 
1120
      numchild=N,children={{name=NAME,
1121
      numchild=N,type=TYPE},(repeats N times)}
1122
 
1123
The `-var-info-type' Command
1124
----------------------------
1125
 
1126
Synopsis
1127
........
1128
 
1129
      -var-info-type NAME
1130
 
1131
   Returns the type of the specified variable NAME.  The type is
1132
returned as a string in the same format as it is output by the GDB CLI:
1133
 
1134
      type=TYPENAME
1135
 
1136
The `-var-info-expression' Command
1137
----------------------------------
1138
 
1139
Synopsis
1140
........
1141
 
1142
      -var-info-expression NAME
1143
 
1144
   Returns what is represented by the variable object NAME:
1145
 
1146
      lang=LANG-SPEC,exp=EXPRESSION
1147
 
1148
where LANG-SPEC is `{"C" | "C++" | "Java"}'.
1149
 
1150
The `-var-show-attributes' Command
1151
----------------------------------
1152
 
1153
Synopsis
1154
........
1155
 
1156
      -var-show-attributes NAME
1157
 
1158
   List attributes of the specified variable object NAME:
1159
 
1160
      status=ATTR [ ( ,ATTR )* ]
1161
 
1162
where ATTR is `{ { editable | noneditable } | TBD }'.
1163
 
1164
The `-var-evaluate-expression' Command
1165
--------------------------------------
1166
 
1167
Synopsis
1168
........
1169
 
1170
      -var-evaluate-expression NAME
1171
 
1172
   Evaluates the expression that is represented by the specified
1173
variable object and returns its value as a string in the current format
1174
specified for the object:
1175
 
1176
      value=VALUE
1177
 
1178
The `-var-assign' Command
1179
-------------------------
1180
 
1181
Synopsis
1182
........
1183
 
1184
      -var-assign NAME EXPRESSION
1185
 
1186
   Assigns the value of EXPRESSION to the variable object specified by
1187
NAME.  The object must be "editable".
1188
 
1189
The `-var-update' Command
1190
-------------------------
1191
 
1192
Synopsis
1193
........
1194
 
1195
      -var-update {NAME | "*"}
1196
 
1197
   Update the value of the variable object NAME by evaluating its
1198
expression after fetching all the new values from memory or registers.
1199
A `*' causes all existing variable objects to be updated.
1200
 
1201

1202
File: gdb.info,  Node: GDB/MI Draft Changes to Output Syntax,  Prev: GDB/MI Variable Objects,  Up: GDB/MI
1203
 
1204
GDB/MI Draft Changes to Output Syntax
1205
=====================================
1206
 
1207
   One problem identified in the existing GDB/MI output syntax was the
1208
difficulty in differentiating between a tuple such as:
1209
 
1210
     {number="1",type="breakpoint",disp="keep",enabled="y"}
1211
 
1212
   where each value has a unique label, and a list such as:
1213
 
1214
     {"1","2","4"}
1215
     {bp="1",bp="2",bp="4"}
1216
 
1217
   where values are un-labeled or the label is duplicated.
1218
 
1219
   What follows is a draft revision to the output specification that
1220
addresses this problem.
1221
 
1222
   The output from GDB/MI consists of zero or more out-of-band records
1223
optionally followed by a single result record, the result record being
1224
for the most recent command input.  The sequence is terminated by
1225
"(gdb)".
1226
 
1227
   Asynchronous GDB/MI output is similar.
1228
 
1229
   Each output record directly associated with an input command is
1230
prefixed by the input commands `TOKEN'.
1231
 
1232
`OUTPUT ==>'
1233
     { OUT-OF-BAND-RECORD } `[' RESULT-RECORD `]' "(gdb)" NL
1234
 
1235
`RESULT-RECORD ==>'
1236
     `[' TOKEN `]' "^" RESULT-CLASS { "," RESULT } NL
1237
 
1238
`OUT-OF-BAND-RECORD ==>'
1239
     ASYNC-RECORD `|' STREAM-RECORD
1240
 
1241
`ASYNC-RECORD ==>'
1242
     EXEC-ASYNC-OUTPUT `|' STATUS-ASYNC-OUTPUT `|' NOTIFY-ASYNC-OUTPUT
1243
 
1244
`EXEC-ASYNC-OUTPUT ==>'
1245
     `[' TOKEN `]' "*" ASYNC-OUTPUT
1246
 
1247
`STATUS-ASYNC-OUTPUT ==>'
1248
     `[' TOKEN `]' "+" ASYNC-OUTPUT
1249
 
1250
`NOTIFY-ASYNC-OUTPUT ==>'
1251
     `[' TOKEN `]' "=" ASYNC-OUTPUT
1252
 
1253
`ASYNC-OUTPUT ==>'
1254
     ASYNC-CLASS { "," RESULT } NL
1255
 
1256
`RESULT-CLASS ==>'
1257
     "done" `|' "running" `|' "connected" `|' "error" `|' "exit"
1258
 
1259
`ASYNC-CLASS ==>'
1260
     "stopped" `|' _others depending on need as still in development_
1261
 
1262
`RESULT ==>'
1263
     STRING "=" VALUE
1264
 
1265
`VALUE ==>'
1266
     C-STRING `|' TUPPLE `|' LIST
1267
 
1268
`TUPPLE ==>'
1269
     "{}" `|' "{" RESULT { "," RESULT } "}"
1270
 
1271
`LIST ==>'
1272
     "`[]'" `|' "`['" VALUE { "," VALUE } "`]'"
1273
 
1274
`STRING ==>'
1275
     _[-A-Za-z\.0-9_]*_
1276
 
1277
`C-STRING ==>'
1278
     _See the input specification_
1279
 
1280
`STREAM-RECORD ==>'
1281
     CONSOLE-STREAM-OUTPUT `|' TARGET-STREAM-OUTPUT `|'
1282
     LOG-STREAM-OUTPUT
1283
 
1284
`CONSOLE-STREAM-OUTPUT ==>'
1285
     "~" C-STRING
1286
 
1287
`TARGET-STREAM-OUTPUT ==>'
1288
     "@" C-STRING
1289
 
1290
`LOG-STREAM-OUTPUT ==>'
1291
     "&" C-STRING
1292
 
1293
`NL ==>'
1294
     CR `|' CR-LF
1295
 
1296
`TOKEN ==>'
1297
     "any sequence of digits"
1298
 
1299
   In addition, the following are still being developed.
1300
 
1301
`QUERY'
1302
     This action is currently undefined.
1303
 
1304
   Notes:
1305
 
1306
   * All output sequences end in a single line containing a period.
1307
 
1308
   * The `TOKEN' is from the corresponding request.  If an execution
1309
     command is interrupted by the -exec-interrupt command, the token
1310
     associated with the `*stopped' message is the one of the original
1311
     execution command, not the one of the interrupt-command.
1312
 
1313
   * STATUS-ASYNC-OUTPUT contains on-going status information about the
1314
     progress of a slow operation.  It can be discarded. All status
1315
     output is prefixed by the prefix `+'.
1316
 
1317
   * EXEC-ASYNC-OUTPUT contains asynchronous state change on the target
1318
     (stopped, started, disappeared). All async output is prefixed by
1319
     the prefix `*'.
1320
 
1321
   * NOTIFY-ASYNC-OUTPUT contains supplementary information that the
1322
     client should handle (new breakpoint information). All notify
1323
     output is prefixed by the prefix `='.
1324
 
1325
   * CONSOLE-STREAM-OUTPUT is output that should be displayed as is, in
1326
     the console.  It is the textual response to a CLI command. All the
1327
     console output is prefixed by the prefix "~".
1328
 
1329
   * TARGET-STREAM-OUTPUT is the output produced by the target program.
1330
     All the target output is prefixed by the prefix "@".
1331
 
1332
   * LOG-STREAM-OUTPUT is output text coming from GDB's internals, for
1333
     instance messages that should be displayed as part of an error
1334
     log.  All the log output is prefixed by the prefix "&".
1335
 
1336
 
1337

1338
File: gdb.info,  Node: GDB Bugs,  Next: Formatting Documentation,  Prev: GDB/MI,  Up: Top
1339
 
1340
Reporting Bugs in GDB
1341
*********************
1342
 
1343
   Your bug reports play an essential role in making GDB reliable.
1344
 
1345
   Reporting a bug may help you by bringing a solution to your problem,
1346
or it may not.  But in any case the principal function of a bug report
1347
is to help the entire community by making the next version of GDB work
1348
better.  Bug reports are your contribution to the maintenance of GDB.
1349
 
1350
   In order for a bug report to serve its purpose, you must include the
1351
information that enables us to fix the bug.
1352
 
1353
* Menu:
1354
 
1355
* Bug Criteria::                Have you found a bug?
1356
* Bug Reporting::               How to report bugs
1357
 
1358

1359
File: gdb.info,  Node: Bug Criteria,  Next: Bug Reporting,  Up: GDB Bugs
1360
 
1361
Have you found a bug?
1362
=====================
1363
 
1364
   If you are not sure whether you have found a bug, here are some
1365
guidelines:
1366
 
1367
   * If the debugger gets a fatal signal, for any input whatever, that
1368
     is a GDB bug.  Reliable debuggers never crash.
1369
 
1370
   * If GDB produces an error message for valid input, that is a bug.
1371
     (Note that if you're cross debugging, the problem may also be
1372
     somewhere in the connection to the target.)
1373
 
1374
   * If GDB does not produce an error message for invalid input, that
1375
     is a bug.  However, you should note that your idea of "invalid
1376
     input" might be our idea of "an extension" or "support for
1377
     traditional practice".
1378
 
1379
   * If you are an experienced user of debugging tools, your suggestions
1380
     for improvement of GDB are welcome in any case.
1381
 
1382

1383
File: gdb.info,  Node: Bug Reporting,  Prev: Bug Criteria,  Up: GDB Bugs
1384
 
1385
How to report bugs
1386
==================
1387
 
1388
   A number of companies and individuals offer support for GNU products.
1389
If you obtained GDB from a support organization, we recommend you
1390
contact that organization first.
1391
 
1392
   You can find contact information for many support companies and
1393
individuals in the file `etc/SERVICE' in the GNU Emacs distribution.
1394
 
1395
   In any event, we also recommend that you send bug reports for GDB to
1396
this addresses:
1397
 
1398
     bug-gdb@gnu.org
1399
 
1400
   *Do not send bug reports to `info-gdb', or to `help-gdb', or to any
1401
newsgroups.*  Most users of GDB do not want to receive bug reports.
1402
Those that do have arranged to receive `bug-gdb'.
1403
 
1404
   The mailing list `bug-gdb' has a newsgroup `gnu.gdb.bug' which
1405
serves as a repeater.  The mailing list and the newsgroup carry exactly
1406
the same messages.  Often people think of posting bug reports to the
1407
newsgroup instead of mailing them.  This appears to work, but it has one
1408
problem which can be crucial: a newsgroup posting often lacks a mail
1409
path back to the sender.  Thus, if we need to ask for more information,
1410
we may be unable to reach you.  For this reason, it is better to send
1411
bug reports to the mailing list.
1412
 
1413
   As a last resort, send bug reports on paper to:
1414
 
1415
     GNU Debugger Bugs
1416
     Free Software Foundation Inc.
1417
     59 Temple Place - Suite 330
1418
     Boston, MA 02111-1307
1419
     USA
1420
 
1421
   The fundamental principle of reporting bugs usefully is this:
1422
*report all the facts*.  If you are not sure whether to state a fact or
1423
leave it out, state it!
1424
 
1425
   Often people omit facts because they think they know what causes the
1426
problem and assume that some details do not matter.  Thus, you might
1427
assume that the name of the variable you use in an example does not
1428
matter.  Well, probably it does not, but one cannot be sure.  Perhaps
1429
the bug is a stray memory reference which happens to fetch from the
1430
location where that name is stored in memory; perhaps, if the name were
1431
different, the contents of that location would fool the debugger into
1432
doing the right thing despite the bug.  Play it safe and give a
1433
specific, complete example.  That is the easiest thing for you to do,
1434
and the most helpful.
1435
 
1436
   Keep in mind that the purpose of a bug report is to enable us to fix
1437
the bug.  It may be that the bug has been reported previously, but
1438
neither you nor we can know that unless your bug report is complete and
1439
self-contained.
1440
 
1441
   Sometimes people give a few sketchy facts and ask, "Does this ring a
1442
bell?"  Those bug reports are useless, and we urge everyone to _refuse
1443
to respond to them_ except to chide the sender to report bugs properly.
1444
 
1445
   To enable us to fix the bug, you should include all these things:
1446
 
1447
   * The version of GDB.  GDB announces it if you start with no
1448
     arguments; you can also print it at any time using `show version'.
1449
 
1450
     Without this, we will not know whether there is any point in
1451
     looking for the bug in the current version of GDB.
1452
 
1453
   * The type of machine you are using, and the operating system name
1454
     and version number.
1455
 
1456
   * What compiler (and its version) was used to compile GDB--e.g.
1457
     "gcc-2.8.1".
1458
 
1459
   * What compiler (and its version) was used to compile the program
1460
     you are debugging--e.g.  "gcc-2.8.1", or "HP92453-01 A.10.32.03 HP
1461
     C Compiler".  For GCC, you can say `gcc --version' to get this
1462
     information; for other compilers, see the documentation for those
1463
     compilers.
1464
 
1465
   * The command arguments you gave the compiler to compile your
1466
     example and observe the bug.  For example, did you use `-O'?  To
1467
     guarantee you will not omit something important, list them all.  A
1468
     copy of the Makefile (or the output from make) is sufficient.
1469
 
1470
     If we were to try to guess the arguments, we would probably guess
1471
     wrong and then we might not encounter the bug.
1472
 
1473
   * A complete input script, and all necessary source files, that will
1474
     reproduce the bug.
1475
 
1476
   * A description of what behavior you observe that you believe is
1477
     incorrect.  For example, "It gets a fatal signal."
1478
 
1479
     Of course, if the bug is that GDB gets a fatal signal, then we
1480
     will certainly notice it.  But if the bug is incorrect output, we
1481
     might not notice unless it is glaringly wrong.  You might as well
1482
     not give us a chance to make a mistake.
1483
 
1484
     Even if the problem you experience is a fatal signal, you should
1485
     still say so explicitly.  Suppose something strange is going on,
1486
     such as, your copy of GDB is out of synch, or you have encountered
1487
     a bug in the C library on your system.  (This has happened!)  Your
1488
     copy might crash and ours would not.  If you told us to expect a
1489
     crash, then when ours fails to crash, we would know that the bug
1490
     was not happening for us.  If you had not told us to expect a
1491
     crash, then we would not be able to draw any conclusion from our
1492
     observations.
1493
 
1494
   * If you wish to suggest changes to the GDB source, send us context
1495
     diffs.  If you even discuss something in the GDB source, refer to
1496
     it by context, not by line number.
1497
 
1498
     The line numbers in our development sources will not match those
1499
     in your sources.  Your line numbers would convey no useful
1500
     information to us.
1501
 
1502
 
1503
   Here are some things that are not necessary:
1504
 
1505
   * A description of the envelope of the bug.
1506
 
1507
     Often people who encounter a bug spend a lot of time investigating
1508
     which changes to the input file will make the bug go away and which
1509
     changes will not affect it.
1510
 
1511
     This is often time consuming and not very useful, because the way
1512
     we will find the bug is by running a single example under the
1513
     debugger with breakpoints, not by pure deduction from a series of
1514
     examples.  We recommend that you save your time for something else.
1515
 
1516
     Of course, if you can find a simpler example to report _instead_
1517
     of the original one, that is a convenience for us.  Errors in the
1518
     output will be easier to spot, running under the debugger will take
1519
     less time, and so on.
1520
 
1521
     However, simplification is not vital; if you do not want to do
1522
     this, report the bug anyway and send us the entire test case you
1523
     used.
1524
 
1525
   * A patch for the bug.
1526
 
1527
     A patch for the bug does help us if it is a good one.  But do not
1528
     omit the necessary information, such as the test case, on the
1529
     assumption that a patch is all we need.  We might see problems
1530
     with your patch and decide to fix the problem another way, or we
1531
     might not understand it at all.
1532
 
1533
     Sometimes with a program as complicated as GDB it is very hard to
1534
     construct an example that will make the program follow a certain
1535
     path through the code.  If you do not send us the example, we will
1536
     not be able to construct one, so we will not be able to verify
1537
     that the bug is fixed.
1538
 
1539
     And if we cannot understand what bug you are trying to fix, or why
1540
     your patch should be an improvement, we will not install it.  A
1541
     test case will help us to understand.
1542
 
1543
   * A guess about what the bug is or what it depends on.
1544
 
1545
     Such guesses are usually wrong.  Even we cannot guess right about
1546
     such things without first using the debugger to find the facts.
1547
 
1548

1549
File: gdb.info,  Node: Command Line Editing,  Next: Using History Interactively,  Prev: Formatting Documentation,  Up: Top
1550
 
1551
Command Line Editing
1552
********************
1553
 
1554
   This chapter describes the basic features of the GNU command line
1555
editing interface.
1556
 
1557
* Menu:
1558
 
1559
* Introduction and Notation::   Notation used in this text.
1560
* Readline Interaction::        The minimum set of commands for editing a line.
1561
* Readline Init File::          Customizing Readline from a user's view.
1562
* Bindable Readline Commands::  A description of most of the Readline commands
1563
                                available for binding
1564
* Readline vi Mode::            A short description of how to make Readline
1565
                                behave like the vi editor.
1566
 
1567

1568
File: gdb.info,  Node: Introduction and Notation,  Next: Readline Interaction,  Up: Command Line Editing
1569
 
1570
Introduction to Line Editing
1571
============================
1572
 
1573
   The following paragraphs describe the notation used to represent
1574
keystrokes.
1575
 
1576
   The text  is read as `Control-K' and describes the character
1577
produced when the  key is pressed while the Control key is depressed.
1578
 
1579
   The text  is read as `Meta-K' and describes the character
1580
produced when the meta key (if you have one) is depressed, and the 
1581
key is pressed.  If you do not have a meta key, the identical keystroke
1582
can be generated by typing  first, and then typing .  Either
1583
process is known as "metafying" the  key.
1584
 
1585
   The text  is read as `Meta-Control-k' and describes the
1586
character produced by "metafying" .
1587
 
1588
   In addition, several keys have their own names.  Specifically,
1589
, , , , , and  all stand for themselves
1590 362 markom
when seen in this text, or in an init file (*note Readline Init File::).
1591 106 markom
 
1592

1593
File: gdb.info,  Node: Readline Interaction,  Next: Readline Init File,  Prev: Introduction and Notation,  Up: Command Line Editing
1594
 
1595
Readline Interaction
1596
====================
1597
 
1598
   Often during an interactive session you type in a long line of text,
1599
only to notice that the first word on the line is misspelled.  The
1600
Readline library gives you a set of commands for manipulating the text
1601
as you type it in, allowing you to just fix your typo, and not forcing
1602
you to retype the majority of the line.  Using these editing commands,
1603
you move the cursor to the place that needs correction, and delete or
1604
insert the text of the corrections.  Then, when you are satisfied with
1605
the line, you simply press .  You do not have to be at the end
1606
of the line to press ; the entire line is accepted regardless
1607
of the location of the cursor within the line.
1608
 
1609
* Menu:
1610
 
1611
* Readline Bare Essentials::    The least you need to know about Readline.
1612
* Readline Movement Commands::  Moving about the input line.
1613
* Readline Killing Commands::   How to delete text, and how to get it back!
1614
* Readline Arguments::          Giving numeric arguments to commands.
1615
* Searching::                   Searching through previous lines.
1616
 
1617

1618
File: gdb.info,  Node: Readline Bare Essentials,  Next: Readline Movement Commands,  Up: Readline Interaction
1619
 
1620
Readline Bare Essentials
1621
------------------------
1622
 
1623
   In order to enter characters into the line, simply type them.  The
1624
typed character appears where the cursor was, and then the cursor moves
1625
one space to the right.  If you mistype a character, you can use your
1626
erase character to back up and delete the mistyped character.
1627
 
1628
   Sometimes you may miss typing a character that you wanted to type,
1629
and not notice your error until you have typed several other
1630
characters.  In that case, you can type  to move the cursor to the
1631
left, and then correct your mistake.  Afterwards, you can move the
1632
cursor to the right with .
1633
 
1634
   When you add text in the middle of a line, you will notice that
1635
characters to the right of the cursor are `pushed over' to make room
1636
for the text that you have inserted.  Likewise, when you delete text
1637
behind the cursor, characters to the right of the cursor are `pulled
1638
back' to fill in the blank space created by the removal of the text.  A
1639
list of the basic bare essentials for editing the text of an input line
1640
follows.
1641
 
1642
1643
     Move back one character.
1644
 
1645
1646
     Move forward one character.
1647
 
1648
1649
     Delete the character to the left of the cursor.
1650
 
1651
1652
     Delete the character underneath the cursor.
1653
 
1654
Printing characters
1655
     Insert the character into the line at the cursor.
1656
 
1657
1658
     Undo the last editing command.  You can undo all the way back to an
1659
     empty line.
1660
 
1661

1662
File: gdb.info,  Node: Readline Movement Commands,  Next: Readline Killing Commands,  Prev: Readline Bare Essentials,  Up: Readline Interaction
1663
 
1664
Readline Movement Commands
1665
--------------------------
1666
 
1667
   The above table describes the most basic possible keystrokes that
1668
you need in order to do editing of the input line.  For your
1669
convenience, many other commands have been added in addition to ,
1670
, , and .  Here are some commands for moving more rapidly
1671
about the line.
1672
 
1673
1674
     Move to the start of the line.
1675
 
1676
1677
     Move to the end of the line.
1678
 
1679
1680
     Move forward a word, where a word is composed of letters and
1681
     digits.
1682
 
1683
1684
     Move backward a word.
1685
 
1686
1687
     Clear the screen, reprinting the current line at the top.
1688
 
1689
   Notice how  moves forward a character, while  moves
1690
forward a word.  It is a loose convention that control keystrokes
1691
operate on characters while meta keystrokes operate on words.
1692
 
1693

1694
File: gdb.info,  Node: Readline Killing Commands,  Next: Readline Arguments,  Prev: Readline Movement Commands,  Up: Readline Interaction
1695
 
1696
Readline Killing Commands
1697
-------------------------
1698
 
1699
   "Killing" text means to delete the text from the line, but to save
1700
it away for later use, usually by "yanking" (re-inserting) it back into
1701
the line.  If the description for a command says that it `kills' text,
1702
then you can be sure that you can get the text back in a different (or
1703
the same) place later.
1704
 
1705
   When you use a kill command, the text is saved in a "kill-ring".
1706
Any number of consecutive kills save all of the killed text together, so
1707
that when you yank it back, you get it all.  The kill ring is not line
1708
specific; the text that you killed on a previously typed line is
1709
available to be yanked back later, when you are typing another line.
1710
 
1711
   Here is the list of commands for killing text.
1712
 
1713
1714
     Kill the text from the current cursor position to the end of the
1715
     line.
1716
 
1717
1718
     Kill from the cursor to the end of the current word, or if between
1719
     words, to the end of the next word.
1720
 
1721
1722
     Kill from the cursor the start of the previous word, or if between
1723
     words, to the start of the previous word.
1724
 
1725
1726
     Kill from the cursor to the previous whitespace.  This is
1727
     different than  because the word boundaries differ.
1728
 
1729
   Here is how to "yank" the text back into the line.  Yanking means to
1730
copy the most-recently-killed text from the kill buffer.
1731
 
1732
1733
     Yank the most recently killed text back into the buffer at the
1734
     cursor.
1735
 
1736
1737
     Rotate the kill-ring, and yank the new top.  You can only do this
1738
     if the prior command is  or .
1739
 
1740

1741
File: gdb.info,  Node: Readline Arguments,  Next: Searching,  Prev: Readline Killing Commands,  Up: Readline Interaction
1742
 
1743
Readline Arguments
1744
------------------
1745
 
1746
   You can pass numeric arguments to Readline commands.  Sometimes the
1747
argument acts as a repeat count, other times it is the sign of the
1748
argument that is significant.  If you pass a negative argument to a
1749
command which normally acts in a forward direction, that command will
1750
act in a backward direction.  For example, to kill text back to the
1751
start of the line, you might type `M-- C-k'.
1752
 
1753
   The general way to pass numeric arguments to a command is to type
1754
meta digits before the command.  If the first `digit' typed is a minus
1755
sign (<->), then the sign of the argument will be negative.  Once you
1756
have typed one meta digit to get the argument started, you can type the
1757
remainder of the digits, and then the command.  For example, to give
1758
the  command an argument of 10, you could type `M-1 0 C-d'.
1759
 
1760

1761
File: gdb.info,  Node: Searching,  Prev: Readline Arguments,  Up: Readline Interaction
1762
 
1763
Searching for Commands in the History
1764
-------------------------------------
1765
 
1766
   Readline provides commands for searching through the command history
1767
for lines containing a specified string.  There are two search modes:
1768
INCREMENTAL and NON-INCREMENTAL.
1769
 
1770
   Incremental searches begin before the user has finished typing the
1771
search string.  As each character of the search string is typed,
1772
Readline displays the next entry from the history matching the string
1773
typed so far.  An incremental search requires only as many characters
1774
as needed to find the desired history entry.  The characters present in
1775
the value of the ISEARCH-TERMINATORS variable are used to terminate an
1776
incremental search.  If that variable has not been assigned a value,
1777
the  and  characters will terminate an incremental search.
1778
 will abort an incremental search and restore the original line.
1779
When the search is terminated, the history entry containing the search
1780
string becomes the current line.  To find other matching entries in the
1781
history list, type  or  as appropriate.  This will search
1782
backward or forward in the history for the next entry matching the
1783
search string typed so far.  Any other key sequence bound to a Readline
1784
command will terminate the search and execute that command.  For
1785
instance, a  will terminate the search and accept the line,
1786
thereby executing the command from the history list.
1787
 
1788
   Non-incremental searches read the entire search string before
1789
starting to search for matching history lines.  The search string may be
1790
typed by the user or be part of the contents of the current line.
1791
 

powered by: WebSVN 2.1.0

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