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

Subversion Repositories openrisc

[/] [openrisc/] [trunk/] [gnu-old/] [gdb-7.1/] [gdb/] [doc/] [gdb.info-4] - Blame information for rev 842

Details | Compare with Previous | View Log

Line No. Rev Author Line
1 227 jeremybenn
This is gdb.info, produced by makeinfo version 4.8 from ./gdb.texinfo.
2
 
3
INFO-DIR-SECTION Software development
4
START-INFO-DIR-ENTRY
5
* Gdb: (gdb).                     The GNU debugger.
6
END-INFO-DIR-ENTRY
7
 
8
   Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996,
9
1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009,
10
2010 Free Software Foundation, Inc.
11
 
12
   Permission is granted to copy, distribute and/or modify this document
13
under the terms of the GNU Free Documentation License, Version 1.1 or
14
any later version published by the Free Software Foundation; with the
15
Invariant Sections being "Free Software" and "Free Software Needs Free
16
Documentation", with the Front-Cover Texts being "A GNU Manual," and
17
with the Back-Cover Texts as in (a) below.
18
 
19
   (a) The FSF's Back-Cover Text is: "You are free to copy and modify
20
this GNU Manual.  Buying copies from GNU Press supports the FSF in
21
developing GNU and promoting software freedom."
22
 
23
   This file documents the GNU debugger GDB.
24
 
25
   This is the Ninth Edition, of `Debugging with GDB: the GNU
26
Source-Level Debugger' for GDB (GDB) Version 7.1.
27
 
28
   Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996,
29
1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009,
30
2010 Free Software Foundation, Inc.
31
 
32
   Permission is granted to copy, distribute and/or modify this document
33
under the terms of the GNU Free Documentation License, Version 1.1 or
34
any later version published by the Free Software Foundation; with the
35
Invariant Sections being "Free Software" and "Free Software Needs Free
36
Documentation", with the Front-Cover Texts being "A GNU Manual," and
37
with the Back-Cover Texts as in (a) below.
38
 
39
   (a) The FSF's Back-Cover Text is: "You are free to copy and modify
40
this GNU Manual.  Buying copies from GNU Press supports the FSF in
41
developing GNU and promoting software freedom."
42
 
43

44
File: gdb.info,  Node: Readline Movement Commands,  Next: Readline Killing Commands,  Prev: Readline Bare Essentials,  Up: Readline Interaction
45
 
46
31.2.2 Readline Movement Commands
47
---------------------------------
48
 
49
The above table describes the most basic keystrokes that you need in
50
order to do editing of the input line.  For your convenience, many
51
other commands have been added in addition to `C-b', `C-f', `C-d', and
52
.  Here are some commands for moving more rapidly about the line.
53
 
54
`C-a'
55
     Move to the start of the line.
56
 
57
`C-e'
58
     Move to the end of the line.
59
 
60
`M-f'
61
     Move forward a word, where a word is composed of letters and
62
     digits.
63
 
64
`M-b'
65
     Move backward a word.
66
 
67
`C-l'
68
     Clear the screen, reprinting the current line at the top.
69
 
70
   Notice how `C-f' moves forward a character, while `M-f' moves
71
forward a word.  It is a loose convention that control keystrokes
72
operate on characters while meta keystrokes operate on words.
73
 
74

75
File: gdb.info,  Node: Readline Killing Commands,  Next: Readline Arguments,  Prev: Readline Movement Commands,  Up: Readline Interaction
76
 
77
31.2.3 Readline Killing Commands
78
--------------------------------
79
 
80
"Killing" text means to delete the text from the line, but to save it
81
away for later use, usually by "yanking" (re-inserting) it back into
82
the line.  (`Cut' and `paste' are more recent jargon for `kill' and
83
`yank'.)
84
 
85
   If the description for a command says that it `kills' text, then you
86
can be sure that you can get the text back in a different (or the same)
87
place later.
88
 
89
   When you use a kill command, the text is saved in a "kill-ring".
90
Any number of consecutive kills save all of the killed text together, so
91
that when you yank it back, you get it all.  The kill ring is not line
92
specific; the text that you killed on a previously typed line is
93
available to be yanked back later, when you are typing another line.
94
 
95
   Here is the list of commands for killing text.
96
 
97
`C-k'
98
     Kill the text from the current cursor position to the end of the
99
     line.
100
 
101
`M-d'
102
     Kill from the cursor to the end of the current word, or, if between
103
     words, to the end of the next word.  Word boundaries are the same
104
     as those used by `M-f'.
105
 
106
`M-'
107
     Kill from the cursor the start of the current word, or, if between
108
     words, to the start of the previous word.  Word boundaries are the
109
     same as those used by `M-b'.
110
 
111
`C-w'
112
     Kill from the cursor to the previous whitespace.  This is
113
     different than `M-' because the word boundaries differ.
114
 
115
 
116
   Here is how to "yank" the text back into the line.  Yanking means to
117
copy the most-recently-killed text from the kill buffer.
118
 
119
`C-y'
120
     Yank the most recently killed text back into the buffer at the
121
     cursor.
122
 
123
`M-y'
124
     Rotate the kill-ring, and yank the new top.  You can only do this
125
     if the prior command is `C-y' or `M-y'.
126
 
127

128
File: gdb.info,  Node: Readline Arguments,  Next: Searching,  Prev: Readline Killing Commands,  Up: Readline Interaction
129
 
130
31.2.4 Readline Arguments
131
-------------------------
132
 
133
You can pass numeric arguments to Readline commands.  Sometimes the
134
argument acts as a repeat count, other times it is the sign of the
135
argument that is significant.  If you pass a negative argument to a
136
command which normally acts in a forward direction, that command will
137
act in a backward direction.  For example, to kill text back to the
138
start of the line, you might type `M-- C-k'.
139
 
140
   The general way to pass numeric arguments to a command is to type
141
meta digits before the command.  If the first `digit' typed is a minus
142
sign (`-'), then the sign of the argument will be negative.  Once you
143
have typed one meta digit to get the argument started, you can type the
144
remainder of the digits, and then the command.  For example, to give
145
the `C-d' command an argument of 10, you could type `M-1 0 C-d', which
146
will delete the next ten characters on the input line.
147
 
148

149
File: gdb.info,  Node: Searching,  Prev: Readline Arguments,  Up: Readline Interaction
150
 
151
31.2.5 Searching for Commands in the History
152
--------------------------------------------
153
 
154
Readline provides commands for searching through the command history
155
for lines containing a specified string.  There are two search modes:
156
"incremental" and "non-incremental".
157
 
158
   Incremental searches begin before the user has finished typing the
159
search string.  As each character of the search string is typed,
160
Readline displays the next entry from the history matching the string
161
typed so far.  An incremental search requires only as many characters
162
as needed to find the desired history entry.  To search backward in the
163
history for a particular string, type `C-r'.  Typing `C-s' searches
164
forward through the history.  The characters present in the value of
165
the `isearch-terminators' variable are used to terminate an incremental
166
search.  If that variable has not been assigned a value, the  and
167
`C-J' characters will terminate an incremental search.  `C-g' will
168
abort an incremental search and restore the original line.  When the
169
search is terminated, the history entry containing the search string
170
becomes the current line.
171
 
172
   To find other matching entries in the history list, type `C-r' or
173
`C-s' as appropriate.  This will search backward or forward in the
174
history for the next entry matching the search string typed so far.
175
Any other key sequence bound to a Readline command will terminate the
176
search and execute that command.  For instance, a  will terminate
177
the search and accept the line, thereby executing the command from the
178
history list.  A movement command will terminate the search, make the
179
last line found the current line, and begin editing.
180
 
181
   Readline remembers the last incremental search string.  If two
182
`C-r's are typed without any intervening characters defining a new
183
search string, any remembered search string is used.
184
 
185
   Non-incremental searches read the entire search string before
186
starting to search for matching history lines.  The search string may be
187
typed by the user or be part of the contents of the current line.
188
 
189

190
File: gdb.info,  Node: Readline Init File,  Next: Bindable Readline Commands,  Prev: Readline Interaction,  Up: Command Line Editing
191
 
192
31.3 Readline Init File
193
=======================
194
 
195
Although the Readline library comes with a set of Emacs-like
196
keybindings installed by default, it is possible to use a different set
197
of keybindings.  Any user can customize programs that use Readline by
198
putting commands in an "inputrc" file, conventionally in his home
199
directory.  The name of this file is taken from the value of the
200
environment variable `INPUTRC'.  If that variable is unset, the default
201
is `~/.inputrc'.
202
 
203
   When a program which uses the Readline library starts up, the init
204
file is read, and the key bindings are set.
205
 
206
   In addition, the `C-x C-r' command re-reads this init file, thus
207
incorporating any changes that you might have made to it.
208
 
209
* Menu:
210
 
211
* Readline Init File Syntax::   Syntax for the commands in the inputrc file.
212
 
213
* Conditional Init Constructs:: Conditional key bindings in the inputrc file.
214
 
215
* Sample Init File::            An example inputrc file.
216
 
217

218
File: gdb.info,  Node: Readline Init File Syntax,  Next: Conditional Init Constructs,  Up: Readline Init File
219
 
220
31.3.1 Readline Init File Syntax
221
--------------------------------
222
 
223
There are only a few basic constructs allowed in the Readline init
224
file.  Blank lines are ignored.  Lines beginning with a `#' are
225
comments.  Lines beginning with a `$' indicate conditional constructs
226
(*note Conditional Init Constructs::).  Other lines denote variable
227
settings and key bindings.
228
 
229
Variable Settings
230
     You can modify the run-time behavior of Readline by altering the
231
     values of variables in Readline using the `set' command within the
232
     init file.  The syntax is simple:
233
 
234
          set VARIABLE VALUE
235
 
236
     Here, for example, is how to change from the default Emacs-like
237
     key binding to use `vi' line editing commands:
238
 
239
          set editing-mode vi
240
 
241
     Variable names and values, where appropriate, are recognized
242
     without regard to case.  Unrecognized variable names are ignored.
243
 
244
     Boolean variables (those that can be set to on or off) are set to
245
     on if the value is null or empty, ON (case-insensitive), or 1.
246
     Any other value results in the variable being set to off.
247
 
248
     A great deal of run-time behavior is changeable with the following
249
     variables.
250
 
251
    `bell-style'
252
          Controls what happens when Readline wants to ring the
253
          terminal bell.  If set to `none', Readline never rings the
254
          bell.  If set to `visible', Readline uses a visible bell if
255
          one is available.  If set to `audible' (the default),
256
          Readline attempts to ring the terminal's bell.
257
 
258
    `bind-tty-special-chars'
259
          If set to `on', Readline attempts to bind the control
260
          characters treated specially by the kernel's terminal driver
261
          to their Readline equivalents.
262
 
263
    `comment-begin'
264
          The string to insert at the beginning of the line when the
265
          `insert-comment' command is executed.  The default value is
266
          `"#"'.
267
 
268
    `completion-ignore-case'
269
          If set to `on', Readline performs filename matching and
270
          completion in a case-insensitive fashion.  The default value
271
          is `off'.
272
 
273
    `completion-query-items'
274
          The number of possible completions that determines when the
275
          user is asked whether the list of possibilities should be
276
          displayed.  If the number of possible completions is greater
277
          than this value, Readline will ask the user whether or not he
278
          wishes to view them; otherwise, they are simply listed.  This
279
          variable must be set to an integer value greater than or
280
          equal to 0.  A negative value means Readline should never ask.
281
          The default limit is `100'.
282
 
283
    `convert-meta'
284
          If set to `on', Readline will convert characters with the
285
          eighth bit set to an ASCII key sequence by stripping the
286
          eighth bit and prefixing an  character, converting them
287
          to a meta-prefixed key sequence.  The default value is `on'.
288
 
289
    `disable-completion'
290
          If set to `On', Readline will inhibit word completion.
291
          Completion  characters will be inserted into the line as if
292
          they had been mapped to `self-insert'.  The default is `off'.
293
 
294
    `editing-mode'
295
          The `editing-mode' variable controls which default set of key
296
          bindings is used.  By default, Readline starts up in Emacs
297
          editing mode, where the keystrokes are most similar to Emacs.
298
          This variable can be set to either `emacs' or `vi'.
299
 
300
    `enable-keypad'
301
          When set to `on', Readline will try to enable the application
302
          keypad when it is called.  Some systems need this to enable
303
          the arrow keys.  The default is `off'.
304
 
305
    `expand-tilde'
306
          If set to `on', tilde expansion is performed when Readline
307
          attempts word completion.  The default is `off'.
308
 
309
    `history-preserve-point'
310
          If set to `on', the history code attempts to place point at
311
          the same location on each history line retrieved with
312
          `previous-history' or `next-history'.  The default is `off'.
313
 
314
    `horizontal-scroll-mode'
315
          This variable can be set to either `on' or `off'.  Setting it
316
          to `on' means that the text of the lines being edited will
317
          scroll horizontally on a single screen line when they are
318
          longer than the width of the screen, instead of wrapping onto
319
          a new screen line.  By default, this variable is set to `off'.
320
 
321
    `input-meta'
322
          If set to `on', Readline will enable eight-bit input (it will
323
          not clear the eighth bit in the characters it reads),
324
          regardless of what the terminal claims it can support.  The
325
          default value is `off'.  The name `meta-flag' is a synonym
326
          for this variable.
327
 
328
    `isearch-terminators'
329
          The string of characters that should terminate an incremental
330
          search without subsequently executing the character as a
331
          command (*note Searching::).  If this variable has not been
332
          given a value, the characters  and `C-J' will terminate
333
          an incremental search.
334
 
335
    `keymap'
336
          Sets Readline's idea of the current keymap for key binding
337
          commands.  Acceptable `keymap' names are `emacs',
338
          `emacs-standard', `emacs-meta', `emacs-ctlx', `vi', `vi-move',
339
          `vi-command', and `vi-insert'.  `vi' is equivalent to
340
          `vi-command'; `emacs' is equivalent to `emacs-standard'.  The
341
          default value is `emacs'.  The value of the `editing-mode'
342
          variable also affects the default keymap.
343
 
344
    `mark-directories'
345
          If set to `on', completed directory names have a slash
346
          appended.  The default is `on'.
347
 
348
    `mark-modified-lines'
349
          This variable, when set to `on', causes Readline to display an
350
          asterisk (`*') at the start of history lines which have been
351
          modified.  This variable is `off' by default.
352
 
353
    `mark-symlinked-directories'
354
          If set to `on', completed names which are symbolic links to
355
          directories have a slash appended (subject to the value of
356
          `mark-directories').  The default is `off'.
357
 
358
    `match-hidden-files'
359
          This variable, when set to `on', causes Readline to match
360
          files whose names begin with a `.' (hidden files) when
361
          performing filename completion, unless the leading `.' is
362
          supplied by the user in the filename to be completed.  This
363
          variable is `on' by default.
364
 
365
    `output-meta'
366
          If set to `on', Readline will display characters with the
367
          eighth bit set directly rather than as a meta-prefixed escape
368
          sequence.  The default is `off'.
369
 
370
    `page-completions'
371
          If set to `on', Readline uses an internal `more'-like pager
372
          to display a screenful of possible completions at a time.
373
          This variable is `on' by default.
374
 
375
    `print-completions-horizontally'
376
          If set to `on', Readline will display completions with matches
377
          sorted horizontally in alphabetical order, rather than down
378
          the screen.  The default is `off'.
379
 
380
    `show-all-if-ambiguous'
381
          This alters the default behavior of the completion functions.
382
          If set to `on', words which have more than one possible
383
          completion cause the matches to be listed immediately instead
384
          of ringing the bell.  The default value is `off'.
385
 
386
    `show-all-if-unmodified'
387
          This alters the default behavior of the completion functions
388
          in a fashion similar to SHOW-ALL-IF-AMBIGUOUS.  If set to
389
          `on', words which have more than one possible completion
390
          without any possible partial completion (the possible
391
          completions don't share a common prefix) cause the matches to
392
          be listed immediately instead of ringing the bell.  The
393
          default value is `off'.
394
 
395
    `visible-stats'
396
          If set to `on', a character denoting a file's type is
397
          appended to the filename when listing possible completions.
398
          The default is `off'.
399
 
400
 
401
Key Bindings
402
     The syntax for controlling key bindings in the init file is
403
     simple.  First you need to find the name of the command that you
404
     want to change.  The following sections contain tables of the
405
     command name, the default keybinding, if any, and a short
406
     description of what the command does.
407
 
408
     Once you know the name of the command, simply place on a line in
409
     the init file the name of the key you wish to bind the command to,
410
     a colon, and then the name of the command.  The name of the key
411
     can be expressed in different ways, depending on what you find most
412
     comfortable.
413
 
414
     In addition to command names, readline allows keys to be bound to
415
     a string that is inserted when the key is pressed (a MACRO).
416
 
417
    KEYNAME: FUNCTION-NAME or MACRO
418
          KEYNAME is the name of a key spelled out in English.  For
419
          example:
420
               Control-u: universal-argument
421
               Meta-Rubout: backward-kill-word
422
               Control-o: "> output"
423
 
424
          In the above example, `C-u' is bound to the function
425
          `universal-argument', `M-DEL' is bound to the function
426
          `backward-kill-word', and `C-o' is bound to run the macro
427
          expressed on the right hand side (that is, to insert the text
428
          `> output' into the line).
429
 
430
          A number of symbolic character names are recognized while
431
          processing this key binding syntax: DEL, ESC, ESCAPE, LFD,
432
          NEWLINE, RET, RETURN, RUBOUT, SPACE, SPC, and TAB.
433
 
434
    "KEYSEQ": FUNCTION-NAME or MACRO
435
          KEYSEQ differs from KEYNAME above in that strings denoting an
436
          entire key sequence can be specified, by placing the key
437
          sequence in double quotes.  Some GNU Emacs style key escapes
438
          can be used, as in the following example, but the special
439
          character names are not recognized.
440
 
441
               "\C-u": universal-argument
442
               "\C-x\C-r": re-read-init-file
443
               "\e[11~": "Function Key 1"
444
 
445
          In the above example, `C-u' is again bound to the function
446
          `universal-argument' (just as it was in the first example),
447
          `C-x C-r' is bound to the function `re-read-init-file', and
448
          ` <[> <1> <1> <~>' is bound to insert the text `Function
449
          Key 1'.
450
 
451
 
452
     The following GNU Emacs style escape sequences are available when
453
     specifying key sequences:
454
 
455
    `\C-'
456
          control prefix
457
 
458
    `\M-'
459
          meta prefix
460
 
461
    `\e'
462
          an escape character
463
 
464
    `\\'
465
          backslash
466
 
467
    `\"'
468
          <">, a double quotation mark
469
 
470
    `\''
471
          <'>, a single quote or apostrophe
472
 
473
     In addition to the GNU Emacs style escape sequences, a second set
474
     of backslash escapes is available:
475
 
476
    `\a'
477
          alert (bell)
478
 
479
    `\b'
480
          backspace
481
 
482
    `\d'
483
          delete
484
 
485
    `\f'
486
          form feed
487
 
488
    `\n'
489
          newline
490
 
491
    `\r'
492
          carriage return
493
 
494
    `\t'
495
          horizontal tab
496
 
497
    `\v'
498
          vertical tab
499
 
500
    `\NNN'
501
          the eight-bit character whose value is the octal value NNN
502
          (one to three digits)
503
 
504
    `\xHH'
505
          the eight-bit character whose value is the hexadecimal value
506
          HH (one or two hex digits)
507
 
508
     When entering the text of a macro, single or double quotes must be
509
     used to indicate a macro definition.  Unquoted text is assumed to
510
     be a function name.  In the macro body, the backslash escapes
511
     described above are expanded.  Backslash will quote any other
512
     character in the macro text, including `"' and `''.  For example,
513
     the following binding will make `C-x \' insert a single `\' into
514
     the line:
515
          "\C-x\\": "\\"
516
 
517
 
518

519
File: gdb.info,  Node: Conditional Init Constructs,  Next: Sample Init File,  Prev: Readline Init File Syntax,  Up: Readline Init File
520
 
521
31.3.2 Conditional Init Constructs
522
----------------------------------
523
 
524
Readline implements a facility similar in spirit to the conditional
525
compilation features of the C preprocessor which allows key bindings
526
and variable settings to be performed as the result of tests.  There
527
are four parser directives used.
528
 
529
`$if'
530
     The `$if' construct allows bindings to be made based on the
531
     editing mode, the terminal being used, or the application using
532
     Readline.  The text of the test extends to the end of the line; no
533
     characters are required to isolate it.
534
 
535
    `mode'
536
          The `mode=' form of the `$if' directive is used to test
537
          whether Readline is in `emacs' or `vi' mode.  This may be
538
          used in conjunction with the `set keymap' command, for
539
          instance, to set bindings in the `emacs-standard' and
540
          `emacs-ctlx' keymaps only if Readline is starting out in
541
          `emacs' mode.
542
 
543
    `term'
544
          The `term=' form may be used to include terminal-specific key
545
          bindings, perhaps to bind the key sequences output by the
546
          terminal's function keys.  The word on the right side of the
547
          `=' is tested against both the full name of the terminal and
548
          the portion of the terminal name before the first `-'.  This
549
          allows `sun' to match both `sun' and `sun-cmd', for instance.
550
 
551
    `application'
552
          The APPLICATION construct is used to include
553
          application-specific settings.  Each program using the
554
          Readline library sets the APPLICATION NAME, and you can test
555
          for a particular value.  This could be used to bind key
556
          sequences to functions useful for a specific program.  For
557
          instance, the following command adds a key sequence that
558
          quotes the current or previous word in Bash:
559
               $if Bash
560
               # Quote the current or previous word
561
               "\C-xq": "\eb\"\ef\""
562
               $endif
563
 
564
`$endif'
565
     This command, as seen in the previous example, terminates an `$if'
566
     command.
567
 
568
`$else'
569
     Commands in this branch of the `$if' directive are executed if the
570
     test fails.
571
 
572
`$include'
573
     This directive takes a single filename as an argument and reads
574
     commands and bindings from that file.  For example, the following
575
     directive reads from `/etc/inputrc':
576
          $include /etc/inputrc
577
 
578

579
File: gdb.info,  Node: Sample Init File,  Prev: Conditional Init Constructs,  Up: Readline Init File
580
 
581
31.3.3 Sample Init File
582
-----------------------
583
 
584
Here is an example of an INPUTRC file.  This illustrates key binding,
585
variable assignment, and conditional syntax.
586
 
587
 
588
     # This file controls the behaviour of line input editing for
589
     # programs that use the GNU Readline library.  Existing
590
     # programs include FTP, Bash, and GDB.
591
     #
592
     # You can re-read the inputrc file with C-x C-r.
593
     # Lines beginning with '#' are comments.
594
     #
595
     # First, include any systemwide bindings and variable
596
     # assignments from /etc/Inputrc
597
     $include /etc/Inputrc
598
 
599
     #
600
     # Set various bindings for emacs mode.
601
 
602
     set editing-mode emacs
603
 
604
     $if mode=emacs
605
 
606
     Meta-Control-h:    backward-kill-word      Text after the function name is ignored
607
 
608
     #
609
     # Arrow keys in keypad mode
610
     #
611
     #"\M-OD":        backward-char
612
     #"\M-OC":        forward-char
613
     #"\M-OA":        previous-history
614
     #"\M-OB":        next-history
615
     #
616
     # Arrow keys in ANSI mode
617
     #
618
     "\M-[D":        backward-char
619
     "\M-[C":        forward-char
620
     "\M-[A":        previous-history
621
     "\M-[B":        next-history
622
     #
623
     # Arrow keys in 8 bit keypad mode
624
     #
625
     #"\M-\C-OD":       backward-char
626
     #"\M-\C-OC":       forward-char
627
     #"\M-\C-OA":       previous-history
628
     #"\M-\C-OB":       next-history
629
     #
630
     # Arrow keys in 8 bit ANSI mode
631
     #
632
     #"\M-\C-[D":       backward-char
633
     #"\M-\C-[C":       forward-char
634
     #"\M-\C-[A":       previous-history
635
     #"\M-\C-[B":       next-history
636
 
637
     C-q: quoted-insert
638
 
639
     $endif
640
 
641
     # An old-style binding.  This happens to be the default.
642
     TAB: complete
643
 
644
     # Macros that are convenient for shell interaction
645
     $if Bash
646
     # edit the path
647
     "\C-xp": "PATH=${PATH}\e\C-e\C-a\ef\C-f"
648
     # prepare to type a quoted word --
649
     # insert open and close double quotes
650
     # and move to just after the open quote
651
     "\C-x\"": "\"\"\C-b"
652
     # insert a backslash (testing backslash escapes
653
     # in sequences and macros)
654
     "\C-x\\": "\\"
655
     # Quote the current or previous word
656
     "\C-xq": "\eb\"\ef\""
657
     # Add a binding to refresh the line, which is unbound
658
     "\C-xr": redraw-current-line
659
     # Edit variable on current line.
660
     "\M-\C-v": "\C-a\C-k$\C-y\M-\C-e\C-a\C-y="
661
     $endif
662
 
663
     # use a visible bell if one is available
664
     set bell-style visible
665
 
666
     # don't strip characters to 7 bits when reading
667
     set input-meta on
668
 
669
     # allow iso-latin1 characters to be inserted rather
670
     # than converted to prefix-meta sequences
671
     set convert-meta off
672
 
673
     # display characters with the eighth bit set directly
674
     # rather than as meta-prefixed characters
675
     set output-meta on
676
 
677
     # if there are more than 150 possible completions for
678
     # a word, ask the user if he wants to see all of them
679
     set completion-query-items 150
680
 
681
     # For FTP
682
     $if Ftp
683
     "\C-xg": "get \M-?"
684
     "\C-xt": "put \M-?"
685
     "\M-.": yank-last-arg
686
     $endif
687
 
688

689
File: gdb.info,  Node: Bindable Readline Commands,  Next: Readline vi Mode,  Prev: Readline Init File,  Up: Command Line Editing
690
 
691
31.4 Bindable Readline Commands
692
===============================
693
 
694
* Menu:
695
 
696
* Commands For Moving::         Moving about the line.
697
* Commands For History::        Getting at previous lines.
698
* Commands For Text::           Commands for changing text.
699
* Commands For Killing::        Commands for killing and yanking.
700
* Numeric Arguments::           Specifying numeric arguments, repeat counts.
701
* Commands For Completion::     Getting Readline to do the typing for you.
702
* Keyboard Macros::             Saving and re-executing typed characters
703
* Miscellaneous Commands::      Other miscellaneous commands.
704
 
705
   This section describes Readline commands that may be bound to key
706
sequences.  Command names without an accompanying key sequence are
707
unbound by default.
708
 
709
   In the following descriptions, "point" refers to the current cursor
710
position, and "mark" refers to a cursor position saved by the
711
`set-mark' command.  The text between the point and mark is referred to
712
as the "region".
713
 
714

715
File: gdb.info,  Node: Commands For Moving,  Next: Commands For History,  Up: Bindable Readline Commands
716
 
717
31.4.1 Commands For Moving
718
--------------------------
719
 
720
`beginning-of-line (C-a)'
721
     Move to the start of the current line.
722
 
723
`end-of-line (C-e)'
724
     Move to the end of the line.
725
 
726
`forward-char (C-f)'
727
     Move forward a character.
728
 
729
`backward-char (C-b)'
730
     Move back a character.
731
 
732
`forward-word (M-f)'
733
     Move forward to the end of the next word.  Words are composed of
734
     letters and digits.
735
 
736
`backward-word (M-b)'
737
     Move back to the start of the current or previous word.  Words are
738
     composed of letters and digits.
739
 
740
`clear-screen (C-l)'
741
     Clear the screen and redraw the current line, leaving the current
742
     line at the top of the screen.
743
 
744
`redraw-current-line ()'
745
     Refresh the current line.  By default, this is unbound.
746
 
747
 
748

749
File: gdb.info,  Node: Commands For History,  Next: Commands For Text,  Prev: Commands For Moving,  Up: Bindable Readline Commands
750
 
751
31.4.2 Commands For Manipulating The History
752
--------------------------------------------
753
 
754
`accept-line (Newline or Return)'
755
     Accept the line regardless of where the cursor is.  If this line is
756
     non-empty, it may be added to the history list for future recall
757
     with `add_history()'.  If this line is a modified history line,
758
     the history line is restored to its original state.
759
 
760
`previous-history (C-p)'
761
     Move `back' through the history list, fetching the previous
762
     command.
763
 
764
`next-history (C-n)'
765
     Move `forward' through the history list, fetching the next command.
766
 
767
`beginning-of-history (M-<)'
768
     Move to the first line in the history.
769
 
770
`end-of-history (M->)'
771
     Move to the end of the input history, i.e., the line currently
772
     being entered.
773
 
774
`reverse-search-history (C-r)'
775
     Search backward starting at the current line and moving `up'
776
     through the history as necessary.  This is an incremental search.
777
 
778
`forward-search-history (C-s)'
779
     Search forward starting at the current line and moving `down'
780
     through the the history as necessary.  This is an incremental
781
     search.
782
 
783
`non-incremental-reverse-search-history (M-p)'
784
     Search backward starting at the current line and moving `up'
785
     through the history as necessary using a non-incremental search
786
     for a string supplied by the user.
787
 
788
`non-incremental-forward-search-history (M-n)'
789
     Search forward starting at the current line and moving `down'
790
     through the the history as necessary using a non-incremental search
791
     for a string supplied by the user.
792
 
793
`history-search-forward ()'
794
     Search forward through the history for the string of characters
795
     between the start of the current line and the point.  This is a
796
     non-incremental search.  By default, this command is unbound.
797
 
798
`history-search-backward ()'
799
     Search backward through the history for the string of characters
800
     between the start of the current line and the point.  This is a
801
     non-incremental search.  By default, this command is unbound.
802
 
803
`yank-nth-arg (M-C-y)'
804
     Insert the first argument to the previous command (usually the
805
     second word on the previous line) at point.  With an argument N,
806
     insert the Nth word from the previous command (the words in the
807
     previous command begin with word 0).  A negative argument inserts
808
     the Nth word from the end of the previous command.  Once the
809
     argument N is computed, the argument is extracted as if the `!N'
810
     history expansion had been specified.
811
 
812
`yank-last-arg (M-. or M-_)'
813
     Insert last argument to the previous command (the last word of the
814
     previous history entry).  With an argument, behave exactly like
815
     `yank-nth-arg'.  Successive calls to `yank-last-arg' move back
816
     through the history list, inserting the last argument of each line
817
     in turn.  The history expansion facilities are used to extract the
818
     last argument, as if the `!$' history expansion had been specified.
819
 
820
 
821

822
File: gdb.info,  Node: Commands For Text,  Next: Commands For Killing,  Prev: Commands For History,  Up: Bindable Readline Commands
823
 
824
31.4.3 Commands For Changing Text
825
---------------------------------
826
 
827
`delete-char (C-d)'
828
     Delete the character at point.  If point is at the beginning of
829
     the line, there are no characters in the line, and the last
830
     character typed was not bound to `delete-char', then return EOF.
831
 
832
`backward-delete-char (Rubout)'
833
     Delete the character behind the cursor.  A numeric argument means
834
     to kill the characters instead of deleting them.
835
 
836
`forward-backward-delete-char ()'
837
     Delete the character under the cursor, unless the cursor is at the
838
     end of the line, in which case the character behind the cursor is
839
     deleted.  By default, this is not bound to a key.
840
 
841
`quoted-insert (C-q or C-v)'
842
     Add the next character typed to the line verbatim.  This is how to
843
     insert key sequences like `C-q', for example.
844
 
845
`tab-insert (M-)'
846
     Insert a tab character.
847
 
848
`self-insert (a, b, A, 1, !, ...)'
849
     Insert yourself.
850
 
851
`transpose-chars (C-t)'
852
     Drag the character before the cursor forward over the character at
853
     the cursor, moving the cursor forward as well.  If the insertion
854
     point is at the end of the line, then this transposes the last two
855
     characters of the line.  Negative arguments have no effect.
856
 
857
`transpose-words (M-t)'
858
     Drag the word before point past the word after point, moving point
859
     past that word as well.  If the insertion point is at the end of
860
     the line, this transposes the last two words on the line.
861
 
862
`upcase-word (M-u)'
863
     Uppercase the current (or following) word.  With a negative
864
     argument, uppercase the previous word, but do not move the cursor.
865
 
866
`downcase-word (M-l)'
867
     Lowercase the current (or following) word.  With a negative
868
     argument, lowercase the previous word, but do not move the cursor.
869
 
870
`capitalize-word (M-c)'
871
     Capitalize the current (or following) word.  With a negative
872
     argument, capitalize the previous word, but do not move the cursor.
873
 
874
`overwrite-mode ()'
875
     Toggle overwrite mode.  With an explicit positive numeric argument,
876
     switches to overwrite mode.  With an explicit non-positive numeric
877
     argument, switches to insert mode.  This command affects only
878
     `emacs' mode; `vi' mode does overwrite differently.  Each call to
879
     `readline()' starts in insert mode.
880
 
881
     In overwrite mode, characters bound to `self-insert' replace the
882
     text at point rather than pushing the text to the right.
883
     Characters bound to `backward-delete-char' replace the character
884
     before point with a space.
885
 
886
     By default, this command is unbound.
887
 
888
 
889

890
File: gdb.info,  Node: Commands For Killing,  Next: Numeric Arguments,  Prev: Commands For Text,  Up: Bindable Readline Commands
891
 
892
31.4.4 Killing And Yanking
893
--------------------------
894
 
895
`kill-line (C-k)'
896
     Kill the text from point to the end of the line.
897
 
898
`backward-kill-line (C-x Rubout)'
899
     Kill backward to the beginning of the line.
900
 
901
`unix-line-discard (C-u)'
902
     Kill backward from the cursor to the beginning of the current line.
903
 
904
`kill-whole-line ()'
905
     Kill all characters on the current line, no matter where point is.
906
     By default, this is unbound.
907
 
908
`kill-word (M-d)'
909
     Kill from point to the end of the current word, or if between
910
     words, to the end of the next word.  Word boundaries are the same
911
     as `forward-word'.
912
 
913
`backward-kill-word (M-)'
914
     Kill the word behind point.  Word boundaries are the same as
915
     `backward-word'.
916
 
917
`unix-word-rubout (C-w)'
918
     Kill the word behind point, using white space as a word boundary.
919
     The killed text is saved on the kill-ring.
920
 
921
`unix-filename-rubout ()'
922
     Kill the word behind point, using white space and the slash
923
     character as the word boundaries.  The killed text is saved on the
924
     kill-ring.
925
 
926
`delete-horizontal-space ()'
927
     Delete all spaces and tabs around point.  By default, this is
928
     unbound.
929
 
930
`kill-region ()'
931
     Kill the text in the current region.  By default, this command is
932
     unbound.
933
 
934
`copy-region-as-kill ()'
935
     Copy the text in the region to the kill buffer, so it can be yanked
936
     right away.  By default, this command is unbound.
937
 
938
`copy-backward-word ()'
939
     Copy the word before point to the kill buffer.  The word
940
     boundaries are the same as `backward-word'.  By default, this
941
     command is unbound.
942
 
943
`copy-forward-word ()'
944
     Copy the word following point to the kill buffer.  The word
945
     boundaries are the same as `forward-word'.  By default, this
946
     command is unbound.
947
 
948
`yank (C-y)'
949
     Yank the top of the kill ring into the buffer at point.
950
 
951
`yank-pop (M-y)'
952
     Rotate the kill-ring, and yank the new top.  You can only do this
953
     if the prior command is `yank' or `yank-pop'.
954
 
955

956
File: gdb.info,  Node: Numeric Arguments,  Next: Commands For Completion,  Prev: Commands For Killing,  Up: Bindable Readline Commands
957
 
958
31.4.5 Specifying Numeric Arguments
959
-----------------------------------
960
 
961
`digit-argument (M-0, M-1, ... M--)'
962
     Add this digit to the argument already accumulating, or start a new
963
     argument.  `M--' starts a negative argument.
964
 
965
`universal-argument ()'
966
     This is another way to specify an argument.  If this command is
967
     followed by one or more digits, optionally with a leading minus
968
     sign, those digits define the argument.  If the command is
969
     followed by digits, executing `universal-argument' again ends the
970
     numeric argument, but is otherwise ignored.  As a special case, if
971
     this command is immediately followed by a character that is
972
     neither a digit or minus sign, the argument count for the next
973
     command is multiplied by four.  The argument count is initially
974
     one, so executing this function the first time makes the argument
975
     count four, a second time makes the argument count sixteen, and so
976
     on.  By default, this is not bound to a key.
977
 
978

979
File: gdb.info,  Node: Commands For Completion,  Next: Keyboard Macros,  Prev: Numeric Arguments,  Up: Bindable Readline Commands
980
 
981
31.4.6 Letting Readline Type For You
982
------------------------------------
983
 
984
`complete ()'
985
     Attempt to perform completion on the text before point.  The
986
     actual completion performed is application-specific.  The default
987
     is filename completion.
988
 
989
`possible-completions (M-?)'
990
     List the possible completions of the text before point.
991
 
992
`insert-completions (M-*)'
993
     Insert all completions of the text before point that would have
994
     been generated by `possible-completions'.
995
 
996
`menu-complete ()'
997
     Similar to `complete', but replaces the word to be completed with
998
     a single match from the list of possible completions.  Repeated
999
     execution of `menu-complete' steps through the list of possible
1000
     completions, inserting each match in turn.  At the end of the list
1001
     of completions, the bell is rung (subject to the setting of
1002
     `bell-style') and the original text is restored.  An argument of N
1003
     moves N positions forward in the list of matches; a negative
1004
     argument may be used to move backward through the list.  This
1005
     command is intended to be bound to , but is unbound by
1006
     default.
1007
 
1008
`delete-char-or-list ()'
1009
     Deletes the character under the cursor if not at the beginning or
1010
     end of the line (like `delete-char').  If at the end of the line,
1011
     behaves identically to `possible-completions'.  This command is
1012
     unbound by default.
1013
 
1014
 
1015

1016
File: gdb.info,  Node: Keyboard Macros,  Next: Miscellaneous Commands,  Prev: Commands For Completion,  Up: Bindable Readline Commands
1017
 
1018
31.4.7 Keyboard Macros
1019
----------------------
1020
 
1021
`start-kbd-macro (C-x ()'
1022
     Begin saving the characters typed into the current keyboard macro.
1023
 
1024
`end-kbd-macro (C-x ))'
1025
     Stop saving the characters typed into the current keyboard macro
1026
     and save the definition.
1027
 
1028
`call-last-kbd-macro (C-x e)'
1029
     Re-execute the last keyboard macro defined, by making the
1030
     characters in the macro appear as if typed at the keyboard.
1031
 
1032
 
1033

1034
File: gdb.info,  Node: Miscellaneous Commands,  Prev: Keyboard Macros,  Up: Bindable Readline Commands
1035
 
1036
31.4.8 Some Miscellaneous Commands
1037
----------------------------------
1038
 
1039
`re-read-init-file (C-x C-r)'
1040
     Read in the contents of the INPUTRC file, and incorporate any
1041
     bindings or variable assignments found there.
1042
 
1043
`abort (C-g)'
1044
     Abort the current editing command and ring the terminal's bell
1045
     (subject to the setting of `bell-style').
1046
 
1047
`do-uppercase-version (M-a, M-b, M-X, ...)'
1048
     If the metafied character X is lowercase, run the command that is
1049
     bound to the corresponding uppercase character.
1050
 
1051
`prefix-meta ()'
1052
     Metafy the next character typed.  This is for keyboards without a
1053
     meta key.  Typing ` f' is equivalent to typing `M-f'.
1054
 
1055
`undo (C-_ or C-x C-u)'
1056
     Incremental undo, separately remembered for each line.
1057
 
1058
`revert-line (M-r)'
1059
     Undo all changes made to this line.  This is like executing the
1060
     `undo' command enough times to get back to the beginning.
1061
 
1062
`tilde-expand (M-~)'
1063
     Perform tilde expansion on the current word.
1064
 
1065
`set-mark (C-@)'
1066
     Set the mark to the point.  If a numeric argument is supplied, the
1067
     mark is set to that position.
1068
 
1069
`exchange-point-and-mark (C-x C-x)'
1070
     Swap the point with the mark.  The current cursor position is set
1071
     to the saved position, and the old cursor position is saved as the
1072
     mark.
1073
 
1074
`character-search (C-])'
1075
     A character is read and point is moved to the next occurrence of
1076
     that character.  A negative count searches for previous
1077
     occurrences.
1078
 
1079
`character-search-backward (M-C-])'
1080
     A character is read and point is moved to the previous occurrence
1081
     of that character.  A negative count searches for subsequent
1082
     occurrences.
1083
 
1084
`insert-comment (M-#)'
1085
     Without a numeric argument, the value of the `comment-begin'
1086
     variable is inserted at the beginning of the current line.  If a
1087
     numeric argument is supplied, this command acts as a toggle:  if
1088
     the characters at the beginning of the line do not match the value
1089
     of `comment-begin', the value is inserted, otherwise the
1090
     characters in `comment-begin' are deleted from the beginning of
1091
     the line.  In either case, the line is accepted as if a newline
1092
     had been typed.
1093
 
1094
`dump-functions ()'
1095
     Print all of the functions and their key bindings to the Readline
1096
     output stream.  If a numeric argument is supplied, the output is
1097
     formatted in such a way that it can be made part of an INPUTRC
1098
     file.  This command is unbound by default.
1099
 
1100
`dump-variables ()'
1101
     Print all of the settable variables and their values to the
1102
     Readline output stream.  If a numeric argument is supplied, the
1103
     output is formatted in such a way that it can be made part of an
1104
     INPUTRC file.  This command is unbound by default.
1105
 
1106
`dump-macros ()'
1107
     Print all of the Readline key sequences bound to macros and the
1108
     strings they output.  If a numeric argument is supplied, the
1109
     output is formatted in such a way that it can be made part of an
1110
     INPUTRC file.  This command is unbound by default.
1111
 
1112
`emacs-editing-mode (C-e)'
1113
     When in `vi' command mode, this causes a switch to `emacs' editing
1114
     mode.
1115
 
1116
`vi-editing-mode (M-C-j)'
1117
     When in `emacs' editing mode, this causes a switch to `vi' editing
1118
     mode.
1119
 
1120
 
1121

1122
File: gdb.info,  Node: Readline vi Mode,  Prev: Bindable Readline Commands,  Up: Command Line Editing
1123
 
1124
31.5 Readline vi Mode
1125
=====================
1126
 
1127
While the Readline library does not have a full set of `vi' editing
1128
functions, it does contain enough to allow simple editing of the line.
1129
The Readline `vi' mode behaves as specified in the POSIX 1003.2
1130
standard.
1131
 
1132
   In order to switch interactively between `emacs' and `vi' editing
1133
modes, use the command `M-C-j' (bound to emacs-editing-mode when in
1134
`vi' mode and to vi-editing-mode in `emacs' mode).  The Readline
1135
default is `emacs' mode.
1136
 
1137
   When you enter a line in `vi' mode, you are already placed in
1138
`insertion' mode, as if you had typed an `i'.  Pressing  switches
1139
you into `command' mode, where you can edit the text of the line with
1140
the standard `vi' movement keys, move to previous history lines with
1141
`k' and subsequent lines with `j', and so forth.
1142
 
1143

1144
File: gdb.info,  Node: Using History Interactively,  Next: Formatting Documentation,  Prev: Command Line Editing,  Up: Top
1145
 
1146
32 Using History Interactively
1147
******************************
1148
 
1149
This chapter describes how to use the GNU History Library interactively,
1150
from a user's standpoint.  It should be considered a user's guide.  For
1151
information on using the GNU History Library in other programs, see the
1152
GNU Readline Library Manual.
1153
 
1154
* Menu:
1155
 
1156
* History Interaction::         What it feels like using History as a user.
1157
 
1158

1159
File: gdb.info,  Node: History Interaction,  Up: Using History Interactively
1160
 
1161
32.1 History Expansion
1162
======================
1163
 
1164
The History library provides a history expansion feature that is similar
1165
to the history expansion provided by `csh'.  This section describes the
1166
syntax used to manipulate the history information.
1167
 
1168
   History expansions introduce words from the history list into the
1169
input stream, making it easy to repeat commands, insert the arguments
1170
to a previous command into the current input line, or fix errors in
1171
previous commands quickly.
1172
 
1173
   History expansion takes place in two parts.  The first is to
1174
determine which line from the history list should be used during
1175
substitution.  The second is to select portions of that line for
1176
inclusion into the current one.  The line selected from the history is
1177
called the "event", and the portions of that line that are acted upon
1178
are called "words".  Various "modifiers" are available to manipulate
1179
the selected words.  The line is broken into words in the same fashion
1180
that Bash does, so that several words surrounded by quotes are
1181
considered one word.  History expansions are introduced by the
1182
appearance of the history expansion character, which is `!' by default.
1183
 
1184
* Menu:
1185
 
1186
* Event Designators::   How to specify which history line to use.
1187
* Word Designators::    Specifying which words are of interest.
1188
* Modifiers::           Modifying the results of substitution.
1189
 
1190

1191
File: gdb.info,  Node: Event Designators,  Next: Word Designators,  Up: History Interaction
1192
 
1193
32.1.1 Event Designators
1194
------------------------
1195
 
1196
An event designator is a reference to a command line entry in the
1197
history list.
1198
 
1199
`!'
1200
     Start a history substitution, except when followed by a space, tab,
1201
     the end of the line, or `='.
1202
 
1203
`!N'
1204
     Refer to command line N.
1205
 
1206
`!-N'
1207
     Refer to the command N lines back.
1208
 
1209
`!!'
1210
     Refer to the previous command.  This is a synonym for `!-1'.
1211
 
1212
`!STRING'
1213
     Refer to the most recent command starting with STRING.
1214
 
1215
`!?STRING[?]'
1216
     Refer to the most recent command containing STRING.  The trailing
1217
     `?' may be omitted if the STRING is followed immediately by a
1218
     newline.
1219
 
1220
`^STRING1^STRING2^'
1221
     Quick Substitution.  Repeat the last command, replacing STRING1
1222
     with STRING2.  Equivalent to `!!:s/STRING1/STRING2/'.
1223
 
1224
`!#'
1225
     The entire command line typed so far.
1226
 
1227
 
1228

1229
File: gdb.info,  Node: Word Designators,  Next: Modifiers,  Prev: Event Designators,  Up: History Interaction
1230
 
1231
32.1.2 Word Designators
1232
-----------------------
1233
 
1234
Word designators are used to select desired words from the event.  A
1235
`:' separates the event specification from the word designator.  It may
1236
be omitted if the word designator begins with a `^', `$', `*', `-', or
1237
`%'.  Words are numbered from the beginning of the line, with the first
1238
word being denoted by 0 (zero).  Words are inserted into the current
1239
line separated by single spaces.
1240
 
1241
   For example,
1242
 
1243
`!!'
1244
     designates the preceding command.  When you type this, the
1245
     preceding command is repeated in toto.
1246
 
1247
`!!:$'
1248
     designates the last argument of the preceding command.  This may be
1249
     shortened to `!$'.
1250
 
1251
`!fi:2'
1252
     designates the second argument of the most recent command starting
1253
     with the letters `fi'.
1254
 
1255
   Here are the word designators:
1256
 
1257
`0 (zero)'
1258
     The `0'th word.  For many applications, this is the command word.
1259
 
1260
`N'
1261
     The Nth word.
1262
 
1263
`^'
1264
     The first argument; that is, word 1.
1265
 
1266
`$'
1267
     The last argument.
1268
 
1269
`%'
1270
     The word matched by the most recent `?STRING?' search.
1271
 
1272
`X-Y'
1273
     A range of words; `-Y' abbreviates `0-Y'.
1274
 
1275
`*'
1276
     All of the words, except the `0'th.  This is a synonym for `1-$'.
1277
     It is not an error to use `*' if there is just one word in the
1278
     event; the empty string is returned in that case.
1279
 
1280
`X*'
1281
     Abbreviates `X-$'
1282
 
1283
`X-'
1284
     Abbreviates `X-$' like `X*', but omits the last word.
1285
 
1286
 
1287
   If a word designator is supplied without an event specification, the
1288
previous command is used as the event.
1289
 
1290

1291
File: gdb.info,  Node: Modifiers,  Prev: Word Designators,  Up: History Interaction
1292
 
1293
32.1.3 Modifiers
1294
----------------
1295
 
1296
After the optional word designator, you can add a sequence of one or
1297
more of the following modifiers, each preceded by a `:'.
1298
 
1299
`h'
1300
     Remove a trailing pathname component, leaving only the head.
1301
 
1302
`t'
1303
     Remove all leading  pathname  components, leaving the tail.
1304
 
1305
`r'
1306
     Remove a trailing suffix of the form `.SUFFIX', leaving the
1307
     basename.
1308
 
1309
`e'
1310
     Remove all but the trailing suffix.
1311
 
1312
`p'
1313
     Print the new command but do not execute it.
1314
 
1315
`s/OLD/NEW/'
1316
     Substitute NEW for the first occurrence of OLD in the event line.
1317
     Any delimiter may be used in place of `/'.  The delimiter may be
1318
     quoted in OLD and NEW with a single backslash.  If `&' appears in
1319
     NEW, it is replaced by OLD.  A single backslash will quote the
1320
     `&'.  The final delimiter is optional if it is the last character
1321
     on the input line.
1322
 
1323
`&'
1324
     Repeat the previous substitution.
1325
 
1326
`g'
1327
`a'
1328
     Cause changes to be applied over the entire event line.  Used in
1329
     conjunction with `s', as in `gs/OLD/NEW/', or with `&'.
1330
 
1331
`G'
1332
     Apply the following `s' modifier once to each word in the event.
1333
 
1334
 
1335

1336
File: gdb.info,  Node: Formatting Documentation,  Next: Installing GDB,  Prev: Using History Interactively,  Up: Top
1337
 
1338
Appendix A Formatting Documentation
1339
***********************************
1340
 
1341
The GDB 4 release includes an already-formatted reference card, ready
1342
for printing with PostScript or Ghostscript, in the `gdb' subdirectory
1343
of the main source directory(1).  If you can use PostScript or
1344
Ghostscript with your printer, you can print the reference card
1345
immediately with `refcard.ps'.
1346
 
1347
   The release also includes the source for the reference card.  You
1348
can format it, using TeX, by typing:
1349
 
1350
     make refcard.dvi
1351
 
1352
   The GDB reference card is designed to print in "landscape" mode on
1353
US "letter" size paper; that is, on a sheet 11 inches wide by 8.5 inches
1354
high.  You will need to specify this form of printing as an option to
1355
your DVI output program.
1356
 
1357
   All the documentation for GDB comes as part of the machine-readable
1358
distribution.  The documentation is written in Texinfo format, which is
1359
a documentation system that uses a single source file to produce both
1360
on-line information and a printed manual.  You can use one of the Info
1361
formatting commands to create the on-line version of the documentation
1362
and TeX (or `texi2roff') to typeset the printed version.
1363
 
1364
   GDB includes an already formatted copy of the on-line Info version
1365
of this manual in the `gdb' subdirectory.  The main Info file is
1366
`gdb-7.1/gdb/gdb.info', and it refers to subordinate files matching
1367
`gdb.info*' in the same directory.  If necessary, you can print out
1368
these files, or read them with any editor; but they are easier to read
1369
using the `info' subsystem in GNU Emacs or the standalone `info'
1370
program, available as part of the GNU Texinfo distribution.
1371
 
1372
   If you want to format these Info files yourself, you need one of the
1373
Info formatting programs, such as `texinfo-format-buffer' or `makeinfo'.
1374
 
1375
   If you have `makeinfo' installed, and are in the top level GDB
1376
source directory (`gdb-7.1', in the case of version 7.1), you can make
1377
the Info file by typing:
1378
 
1379
     cd gdb
1380
     make gdb.info
1381
 
1382
   If you want to typeset and print copies of this manual, you need TeX,
1383
a program to print its DVI output files, and `texinfo.tex', the Texinfo
1384
definitions file.
1385
 
1386
   TeX is a typesetting program; it does not print files directly, but
1387
produces output files called DVI files.  To print a typeset document,
1388
you need a program to print DVI files.  If your system has TeX
1389
installed, chances are it has such a program.  The precise command to
1390
use depends on your system; `lpr -d' is common; another (for PostScript
1391
devices) is `dvips'.  The DVI print command may require a file name
1392
without any extension or a `.dvi' extension.
1393
 
1394
   TeX also requires a macro definitions file called `texinfo.tex'.
1395
This file tells TeX how to typeset a document written in Texinfo
1396
format.  On its own, TeX cannot either read or typeset a Texinfo file.
1397
`texinfo.tex' is distributed with GDB and is located in the
1398
`gdb-VERSION-NUMBER/texinfo' directory.
1399
 
1400
   If you have TeX and a DVI printer program installed, you can typeset
1401
and print this manual.  First switch to the `gdb' subdirectory of the
1402
main source directory (for example, to `gdb-7.1/gdb') and type:
1403
 
1404
     make gdb.dvi
1405
 
1406
   Then give `gdb.dvi' to your DVI printing program.
1407
 
1408
   ---------- Footnotes ----------
1409
 
1410
   (1) In `gdb-7.1/gdb/refcard.ps' of the version 7.1 release.
1411
 
1412

1413
File: gdb.info,  Node: Installing GDB,  Next: Maintenance Commands,  Prev: Formatting Documentation,  Up: Top
1414
 
1415
Appendix B Installing GDB
1416
*************************
1417
 
1418
* Menu:
1419
 
1420
* Requirements::                Requirements for building GDB
1421
* Running Configure::           Invoking the GDB `configure' script
1422
* Separate Objdir::             Compiling GDB in another directory
1423
* Config Names::                Specifying names for hosts and targets
1424
* Configure Options::           Summary of options for configure
1425
* System-wide configuration::   Having a system-wide init file
1426
 
1427

1428
File: gdb.info,  Node: Requirements,  Next: Running Configure,  Up: Installing GDB
1429
 
1430
B.1 Requirements for Building GDB
1431
=================================
1432
 
1433
Building GDB requires various tools and packages to be available.
1434
Other packages will be used only if they are found.
1435
 
1436
Tools/Packages Necessary for Building GDB
1437
=========================================
1438
 
1439
ISO C90 compiler
1440
     GDB is written in ISO C90.  It should be buildable with any
1441
     working C90 compiler, e.g. GCC.
1442
 
1443
 
1444
Tools/Packages Optional for Building GDB
1445
========================================
1446
 
1447
Expat
1448
     GDB can use the Expat XML parsing library.  This library may be
1449
     included with your operating system distribution; if it is not, you
1450
     can get the latest version from `http://expat.sourceforge.net'.
1451
     The `configure' script will search for this library in several
1452
     standard locations; if it is installed in an unusual path, you can
1453
     use the `--with-libexpat-prefix' option to specify its location.
1454
 
1455
     Expat is used for:
1456
 
1457
        * Remote protocol memory maps (*note Memory Map Format::)
1458
 
1459
        * Target descriptions (*note Target Descriptions::)
1460
 
1461
        * Remote shared library lists (*note Library List Format::)
1462
 
1463
        * MS-Windows shared libraries (*note Shared Libraries::)
1464
 
1465
zlib
1466
     GDB will use the `zlib' library, if available, to read compressed
1467
     debug sections.  Some linkers, such as GNU gold, are capable of
1468
     producing binaries with compressed debug sections.  If GDB is
1469
     compiled with `zlib', it will be able to read the debug
1470
     information in such binaries.
1471
 
1472
     The `zlib' library is likely included with your operating system
1473
     distribution; if it is not, you can get the latest version from
1474
     `http://zlib.net'.
1475
 
1476
iconv
1477
     GDB's features related to character sets (*note Character Sets::)
1478
     require a functioning `iconv' implementation.  If you are on a GNU
1479
     system, then this is provided by the GNU C Library.  Some other
1480
     systems also provide a working `iconv'.
1481
 
1482
     On systems with `iconv', you can install GNU Libiconv.  If you
1483
     have previously installed Libiconv, you can use the
1484
     `--with-libiconv-prefix' option to configure.
1485
 
1486
     GDB's top-level `configure' and `Makefile' will arrange to build
1487
     Libiconv if a directory named `libiconv' appears in the top-most
1488
     source directory.  If Libiconv is built this way, and if the
1489
     operating system does not provide a suitable `iconv'
1490
     implementation, then the just-built library will automatically be
1491
     used by GDB.  One easy way to set this up is to download GNU
1492
     Libiconv, unpack it, and then rename the directory holding the
1493
     Libiconv source code to `libiconv'.
1494
 
1495

1496
File: gdb.info,  Node: Running Configure,  Next: Separate Objdir,  Prev: Requirements,  Up: Installing GDB
1497
 
1498
B.2 Invoking the GDB `configure' Script
1499
=======================================
1500
 
1501
GDB comes with a `configure' script that automates the process of
1502
preparing GDB for installation; you can then use `make' to build the
1503
`gdb' program.
1504
 
1505
   The GDB distribution includes all the source code you need for GDB
1506
in a single directory, whose name is usually composed by appending the
1507
version number to `gdb'.
1508
 
1509
   For example, the GDB version 7.1 distribution is in the `gdb-7.1'
1510
directory.  That directory contains:
1511
 
1512
`gdb-7.1/configure (and supporting files)'
1513
     script for configuring GDB and all its supporting libraries
1514
 
1515
`gdb-7.1/gdb'
1516
     the source specific to GDB itself
1517
 
1518
`gdb-7.1/bfd'
1519
     source for the Binary File Descriptor library
1520
 
1521
`gdb-7.1/include'
1522
     GNU include files
1523
 
1524
`gdb-7.1/libiberty'
1525
     source for the `-liberty' free software library
1526
 
1527
`gdb-7.1/opcodes'
1528
     source for the library of opcode tables and disassemblers
1529
 
1530
`gdb-7.1/readline'
1531
     source for the GNU command-line interface
1532
 
1533
`gdb-7.1/glob'
1534
     source for the GNU filename pattern-matching subroutine
1535
 
1536
`gdb-7.1/mmalloc'
1537
     source for the GNU memory-mapped malloc package
1538
 
1539
   The simplest way to configure and build GDB is to run `configure'
1540
from the `gdb-VERSION-NUMBER' source directory, which in this example
1541
is the `gdb-7.1' directory.
1542
 
1543
   First switch to the `gdb-VERSION-NUMBER' source directory if you are
1544
not already in it; then run `configure'.  Pass the identifier for the
1545
platform on which GDB will run as an argument.
1546
 
1547
   For example:
1548
 
1549
     cd gdb-7.1
1550
     ./configure HOST
1551
     make
1552
 
1553
where HOST is an identifier such as `sun4' or `decstation', that
1554
identifies the platform where GDB will run.  (You can often leave off
1555
HOST; `configure' tries to guess the correct value by examining your
1556
system.)
1557
 
1558
   Running `configure HOST' and then running `make' builds the `bfd',
1559
`readline', `mmalloc', and `libiberty' libraries, then `gdb' itself.
1560
The configured source files, and the binaries, are left in the
1561
corresponding source directories.
1562
 
1563
   `configure' is a Bourne-shell (`/bin/sh') script; if your system
1564
does not recognize this automatically when you run a different shell,
1565
you may need to run `sh' on it explicitly:
1566
 
1567
     sh configure HOST
1568
 
1569
   If you run `configure' from a directory that contains source
1570
directories for multiple libraries or programs, such as the `gdb-7.1'
1571
source directory for version 7.1, `configure' creates configuration
1572
files for every directory level underneath (unless you tell it not to,
1573
with the `--norecursion' option).
1574
 
1575
   You should run the `configure' script from the top directory in the
1576
source tree, the `gdb-VERSION-NUMBER' directory.  If you run
1577
`configure' from one of the subdirectories, you will configure only
1578
that subdirectory.  That is usually not what you want.  In particular,
1579
if you run the first `configure' from the `gdb' subdirectory of the
1580
`gdb-VERSION-NUMBER' directory, you will omit the configuration of
1581
`bfd', `readline', and other sibling directories of the `gdb'
1582
subdirectory.  This leads to build errors about missing include files
1583
such as `bfd/bfd.h'.
1584
 
1585
   You can install `gdb' anywhere; it has no hardwired paths.  However,
1586
you should make sure that the shell on your path (named by the `SHELL'
1587
environment variable) is publicly readable.  Remember that GDB uses the
1588
shell to start your program--some systems refuse to let GDB debug child
1589
processes whose programs are not readable.
1590
 
1591

1592
File: gdb.info,  Node: Separate Objdir,  Next: Config Names,  Prev: Running Configure,  Up: Installing GDB
1593
 
1594
B.3 Compiling GDB in Another Directory
1595
======================================
1596
 
1597
If you want to run GDB versions for several host or target machines,
1598
you need a different `gdb' compiled for each combination of host and
1599
target.  `configure' is designed to make this easy by allowing you to
1600
generate each configuration in a separate subdirectory, rather than in
1601
the source directory.  If your `make' program handles the `VPATH'
1602
feature (GNU `make' does), running `make' in each of these directories
1603
builds the `gdb' program specified there.
1604
 
1605
   To build `gdb' in a separate directory, run `configure' with the
1606
`--srcdir' option to specify where to find the source.  (You also need
1607
to specify a path to find `configure' itself from your working
1608
directory.  If the path to `configure' would be the same as the
1609
argument to `--srcdir', you can leave out the `--srcdir' option; it is
1610
assumed.)
1611
 
1612
   For example, with version 7.1, you can build GDB in a separate
1613
directory for a Sun 4 like this:
1614
 
1615
     cd gdb-7.1
1616
     mkdir ../gdb-sun4
1617
     cd ../gdb-sun4
1618
     ../gdb-7.1/configure sun4
1619
     make
1620
 
1621
   When `configure' builds a configuration using a remote source
1622
directory, it creates a tree for the binaries with the same structure
1623
(and using the same names) as the tree under the source directory.  In
1624
the example, you'd find the Sun 4 library `libiberty.a' in the
1625
directory `gdb-sun4/libiberty', and GDB itself in `gdb-sun4/gdb'.
1626
 
1627
   Make sure that your path to the `configure' script has just one
1628
instance of `gdb' in it.  If your path to `configure' looks like
1629
`../gdb-7.1/gdb/configure', you are configuring only one subdirectory
1630
of GDB, not the whole package.  This leads to build errors about
1631
missing include files such as `bfd/bfd.h'.
1632
 
1633
   One popular reason to build several GDB configurations in separate
1634
directories is to configure GDB for cross-compiling (where GDB runs on
1635
one machine--the "host"--while debugging programs that run on another
1636
machine--the "target").  You specify a cross-debugging target by giving
1637
the `--target=TARGET' option to `configure'.
1638
 
1639
   When you run `make' to build a program or library, you must run it
1640
in a configured directory--whatever directory you were in when you
1641
called `configure' (or one of its subdirectories).
1642
 
1643
   The `Makefile' that `configure' generates in each source directory
1644
also runs recursively.  If you type `make' in a source directory such
1645
as `gdb-7.1' (or in a separate configured directory configured with
1646
`--srcdir=DIRNAME/gdb-7.1'), you will build all the required libraries,
1647
and then build GDB.
1648
 
1649
   When you have multiple hosts or targets configured in separate
1650
directories, you can run `make' on them in parallel (for example, if
1651
they are NFS-mounted on each of the hosts); they will not interfere
1652
with each other.
1653
 
1654

1655
File: gdb.info,  Node: Config Names,  Next: Configure Options,  Prev: Separate Objdir,  Up: Installing GDB
1656
 
1657
B.4 Specifying Names for Hosts and Targets
1658
==========================================
1659
 
1660
The specifications used for hosts and targets in the `configure' script
1661
are based on a three-part naming scheme, but some short predefined
1662
aliases are also supported.  The full naming scheme encodes three pieces
1663
of information in the following pattern:
1664
 
1665
     ARCHITECTURE-VENDOR-OS
1666
 
1667
   For example, you can use the alias `sun4' as a HOST argument, or as
1668
the value for TARGET in a `--target=TARGET' option.  The equivalent
1669
full name is `sparc-sun-sunos4'.
1670
 
1671
   The `configure' script accompanying GDB does not provide any query
1672
facility to list all supported host and target names or aliases.
1673
`configure' calls the Bourne shell script `config.sub' to map
1674
abbreviations to full names; you can read the script, if you wish, or
1675
you can use it to test your guesses on abbreviations--for example:
1676
 
1677
     % sh config.sub i386-linux
1678
     i386-pc-linux-gnu
1679
     % sh config.sub alpha-linux
1680
     alpha-unknown-linux-gnu
1681
     % sh config.sub hp9k700
1682
     hppa1.1-hp-hpux
1683
     % sh config.sub sun4
1684
     sparc-sun-sunos4.1.1
1685
     % sh config.sub sun3
1686
     m68k-sun-sunos4.1.1
1687
     % sh config.sub i986v
1688
     Invalid configuration `i986v': machine `i986v' not recognized
1689
 
1690
`config.sub' is also distributed in the GDB source directory
1691
(`gdb-7.1', for version 7.1).
1692
 
1693

1694
File: gdb.info,  Node: Configure Options,  Next: System-wide configuration,  Prev: Config Names,  Up: Installing GDB
1695
 
1696
B.5 `configure' Options
1697
=======================
1698
 
1699
Here is a summary of the `configure' options and arguments that are
1700
most often useful for building GDB.  `configure' also has several other
1701
options not listed here.  *note (configure.info)What Configure Does::,
1702
for a full explanation of `configure'.
1703
 
1704
     configure [--help]
1705
               [--prefix=DIR]
1706
               [--exec-prefix=DIR]
1707
               [--srcdir=DIRNAME]
1708
               [--norecursion] [--rm]
1709
               [--target=TARGET]
1710
               HOST
1711
 
1712
You may introduce options with a single `-' rather than `--' if you
1713
prefer; but you may abbreviate option names if you use `--'.
1714
 
1715
`--help'
1716
     Display a quick summary of how to invoke `configure'.
1717
 
1718
`--prefix=DIR'
1719
     Configure the source to install programs and files under directory
1720
     `DIR'.
1721
 
1722
`--exec-prefix=DIR'
1723
     Configure the source to install programs under directory `DIR'.
1724
 
1725
`--srcdir=DIRNAME'
1726
     *Warning: using this option requires GNU `make', or another `make'
1727
     that implements the `VPATH' feature.*
1728
     Use this option to make configurations in directories separate
1729
     from the GDB source directories.  Among other things, you can use
1730
     this to build (or maintain) several configurations simultaneously,
1731
     in separate directories.  `configure' writes
1732
     configuration-specific files in the current directory, but
1733
     arranges for them to use the source in the directory DIRNAME.
1734
     `configure' creates directories under the working directory in
1735
     parallel to the source directories below DIRNAME.
1736
 
1737
`--norecursion'
1738
     Configure only the directory level where `configure' is executed;
1739
     do not propagate configuration to subdirectories.
1740
 
1741
`--target=TARGET'
1742
     Configure GDB for cross-debugging programs running on the specified
1743
     TARGET.  Without this option, GDB is configured to debug programs
1744
     that run on the same machine (HOST) as GDB itself.
1745
 
1746
     There is no convenient way to generate a list of all available
1747
     targets.
1748
 
1749
`HOST ...'
1750
     Configure GDB to run on the specified HOST.
1751
 
1752
     There is no convenient way to generate a list of all available
1753
     hosts.
1754
 
1755
   There are many other options available as well, but they are
1756
generally needed for special purposes only.
1757
 
1758

1759
File: gdb.info,  Node: System-wide configuration,  Prev: Configure Options,  Up: Installing GDB
1760
 
1761
B.6 System-wide configuration and settings
1762
==========================================
1763
 
1764
GDB can be configured to have a system-wide init file; this file will
1765
be read and executed at startup (*note What GDB does during startup:
1766
Startup.).
1767
 
1768
   Here is the corresponding configure option:
1769
 
1770
`--with-system-gdbinit=FILE'
1771
     Specify that the default location of the system-wide init file is
1772
     FILE.
1773
 
1774
   If GDB has been configured with the option `--prefix=$prefix', it
1775
may be subject to relocation.  Two possible cases:
1776
 
1777
   * If the default location of this init file contains `$prefix', it
1778
     will be subject to relocation.  Suppose that the configure options
1779
     are `--prefix=$prefix --with-system-gdbinit=$prefix/etc/gdbinit';
1780
     if GDB is moved from `$prefix' to `$install', the system init file
1781
     is looked for as `$install/etc/gdbinit' instead of
1782
     `$prefix/etc/gdbinit'.
1783
 
1784
   * By contrast, if the default location does not contain the prefix,
1785
     it will not be relocated.  E.g. if GDB has been configured with
1786
     `--prefix=/usr/local --with-system-gdbinit=/usr/share/gdb/gdbinit',
1787
     then GDB will always look for `/usr/share/gdb/gdbinit', wherever
1788
     GDB is installed.
1789
 
1790

1791
File: gdb.info,  Node: Maintenance Commands,  Next: Remote Protocol,  Prev: Installing GDB,  Up: Top
1792
 
1793
Appendix C Maintenance Commands
1794
*******************************
1795
 
1796
In addition to commands intended for GDB users, GDB includes a number
1797
of commands intended for GDB developers, that are not documented
1798
elsewhere in this manual.  These commands are provided here for
1799
reference.  (For commands that turn on debugging messages, see *Note
1800
Debugging Output::.)
1801
 
1802
`maint agent EXPRESSION'
1803
`maint agent-eval EXPRESSION'
1804
     Translate the given EXPRESSION into remote agent bytecodes.  This
1805
     command is useful for debugging the Agent Expression mechanism
1806
     (*note Agent Expressions::).  The `agent' version produces an
1807
     expression useful for data collection, such as by tracepoints,
1808
     while `maint agent-eval' produces an expression that evaluates
1809
     directly to a result.  For instance, a collection expression for
1810
     `globa + globb' will include bytecodes to record four bytes of
1811
     memory at each of the addresses of `globa' and `globb', while
1812
     discarding the result of the addition, while an evaluation
1813
     expression will do the addition and return the sum.
1814
 
1815
`maint info breakpoints'
1816
     Using the same format as `info breakpoints', display both the
1817
     breakpoints you've set explicitly, and those GDB is using for
1818
     internal purposes.  Internal breakpoints are shown with negative
1819
     breakpoint numbers.  The type column identifies what kind of
1820
     breakpoint is shown:
1821
 
1822
    `breakpoint'
1823
          Normal, explicitly set breakpoint.
1824
 
1825
    `watchpoint'
1826
          Normal, explicitly set watchpoint.
1827
 
1828
    `longjmp'
1829
          Internal breakpoint, used to handle correctly stepping through
1830
          `longjmp' calls.
1831
 
1832
    `longjmp resume'
1833
          Internal breakpoint at the target of a `longjmp'.
1834
 
1835
    `until'
1836
          Temporary internal breakpoint used by the GDB `until' command.
1837
 
1838
    `finish'
1839
          Temporary internal breakpoint used by the GDB `finish'
1840
          command.
1841
 
1842
    `shlib events'
1843
          Shared library events.
1844
 
1845
 
1846
`set displaced-stepping'
1847
`show displaced-stepping'
1848
     Control whether or not GDB will do "displaced stepping" if the
1849
     target supports it.  Displaced stepping is a way to single-step
1850
     over breakpoints without removing them from the inferior, by
1851
     executing an out-of-line copy of the instruction that was
1852
     originally at the breakpoint location.  It is also known as
1853
     out-of-line single-stepping.
1854
 
1855
    `set displaced-stepping on'
1856
          If the target architecture supports it, GDB will use
1857
          displaced stepping to step over breakpoints.
1858
 
1859
    `set displaced-stepping off'
1860
          GDB will not use displaced stepping to step over breakpoints,
1861
          even if such is supported by the target architecture.
1862
 
1863
    `set displaced-stepping auto'
1864
          This is the default mode.  GDB will use displaced stepping
1865
          only if non-stop mode is active (*note Non-Stop Mode::) and
1866
          the target architecture supports displaced stepping.
1867
 
1868
`maint check-symtabs'
1869
     Check the consistency of psymtabs and symtabs.
1870
 
1871
`maint cplus first_component NAME'
1872
     Print the first C++ class/namespace component of NAME.
1873
 
1874
`maint cplus namespace'
1875
     Print the list of possible C++ namespaces.
1876
 
1877
`maint demangle NAME'
1878
     Demangle a C++ or Objective-C mangled NAME.
1879
 
1880
`maint deprecate COMMAND [REPLACEMENT]'
1881
`maint undeprecate COMMAND'
1882
     Deprecate or undeprecate the named COMMAND.  Deprecated commands
1883
     cause GDB to issue a warning when you use them.  The optional
1884
     argument REPLACEMENT says which newer command should be used in
1885
     favor of the deprecated one; if it is given, GDB will mention the
1886
     replacement as part of the warning.
1887
 
1888
`maint dump-me'
1889
     Cause a fatal signal in the debugger and force it to dump its core.
1890
     This is supported only on systems which support aborting a program
1891
     with the `SIGQUIT' signal.
1892
 
1893
`maint internal-error [MESSAGE-TEXT]'
1894
`maint internal-warning [MESSAGE-TEXT]'
1895
     Cause GDB to call the internal function `internal_error' or
1896
     `internal_warning' and hence behave as though an internal error or
1897
     internal warning has been detected.  In addition to reporting the
1898
     internal problem, these functions give the user the opportunity to
1899
     either quit GDB or create a core file of the current GDB session.
1900
 
1901
     These commands take an optional parameter MESSAGE-TEXT that is
1902
     used as the text of the error or warning message.
1903
 
1904
     Here's an example of using `internal-error':
1905
 
1906
          (gdb) maint internal-error testing, 1, 2
1907
          .../maint.c:121: internal-error: testing, 1, 2
1908
          A problem internal to GDB has been detected.  Further
1909
          debugging may prove unreliable.
1910
          Quit this debugging session? (y or n) n
1911
          Create a core file? (y or n) n
1912
          (gdb)
1913
 
1914
`maint set internal-error ACTION [ask|yes|no]'
1915
`maint show internal-error ACTION'
1916
`maint set internal-warning ACTION [ask|yes|no]'
1917
`maint show internal-warning ACTION'
1918
     When GDB reports an internal problem (error or warning) it gives
1919
     the user the opportunity to both quit GDB and create a core file
1920
     of the current GDB session.  These commands let you override the
1921
     default behaviour for each particular ACTION, described in the
1922
     table below.
1923
 
1924
    `quit'
1925
          You can specify that GDB should always (yes) or never (no)
1926
          quit.  The default is to ask the user what to do.
1927
 
1928
    `corefile'
1929
          You can specify that GDB should always (yes) or never (no)
1930
          create a core file.  The default is to ask the user what to
1931
          do.
1932
 
1933
`maint packet TEXT'
1934
     If GDB is talking to an inferior via the serial protocol, then
1935
     this command sends the string TEXT to the inferior, and displays
1936
     the response packet.  GDB supplies the initial `$' character, the
1937
     terminating `#' character, and the checksum.
1938
 
1939
`maint print architecture [FILE]'
1940
     Print the entire architecture configuration.  The optional argument
1941
     FILE names the file where the output goes.
1942
 
1943
`maint print c-tdesc'
1944
     Print the current target description (*note Target Descriptions::)
1945
     as a C source file.  The created source file can be used in GDB
1946
     when an XML parser is not available to parse the description.
1947
 
1948
`maint print dummy-frames'
1949
     Prints the contents of GDB's internal dummy-frame stack.
1950
 
1951
          (gdb) b add
1952
          ...
1953
          (gdb) print add(2,3)
1954
          Breakpoint 2, add (a=2, b=3) at ...
1955
          58      return (a + b);
1956
          The program being debugged stopped while in a function called from GDB.
1957
          ...
1958
          (gdb) maint print dummy-frames
1959
          0x1a57c80: pc=0x01014068 fp=0x0200bddc sp=0x0200bdd6
1960
           top=0x0200bdd4 id={stack=0x200bddc,code=0x101405c}
1961
           call_lo=0x01014000 call_hi=0x01014001
1962
          (gdb)
1963
 
1964
     Takes an optional file parameter.
1965
 
1966
`maint print registers [FILE]'
1967
`maint print raw-registers [FILE]'
1968
`maint print cooked-registers [FILE]'
1969
`maint print register-groups [FILE]'
1970
     Print GDB's internal register data structures.
1971
 
1972
     The command `maint print raw-registers' includes the contents of
1973
     the raw register cache; the command `maint print cooked-registers'
1974
     includes the (cooked) value of all registers; and the command
1975
     `maint print register-groups' includes the groups that each
1976
     register is a member of.  *Note Registers: (gdbint)Registers.
1977
 
1978
     These commands take an optional parameter, a file name to which to
1979
     write the information.
1980
 
1981
`maint print reggroups [FILE]'
1982
     Print GDB's internal register group data structures.  The optional
1983
     argument FILE tells to what file to write the information.
1984
 
1985
     The register groups info looks like this:
1986
 
1987
          (gdb) maint print reggroups
1988
           Group      Type
1989
           general    user
1990
           float      user
1991
           all        user
1992
           vector     user
1993
           system     user
1994
           save       internal
1995
           restore    internal
1996
 
1997
`flushregs'
1998
     This command forces GDB to flush its internal register cache.
1999
 
2000
`maint print objfiles'
2001
     Print a dump of all known object files.  For each object file, this
2002
     command prints its name, address in memory, and all of its psymtabs
2003
     and symtabs.
2004
 
2005
`maint print statistics'
2006
     This command prints, for each object file in the program, various
2007
     data about that object file followed by the byte cache ("bcache")
2008
     statistics for the object file.  The objfile data includes the
2009
     number of minimal, partial, full, and stabs symbols, the number of
2010
     types defined by the objfile, the number of as yet unexpanded psym
2011
     tables, the number of line tables and string tables, and the
2012
     amount of memory used by the various tables.  The bcache
2013
     statistics include the counts, sizes, and counts of duplicates of
2014
     all and unique objects, max, average, and median entry size, total
2015
     memory used and its overhead and savings, and various measures of
2016
     the hash table size and chain lengths.
2017
 
2018
`maint print target-stack'
2019
     A "target" is an interface between the debugger and a particular
2020
     kind of file or process.  Targets can be stacked in "strata", so
2021
     that more than one target can potentially respond to a request.
2022
     In particular, memory accesses will walk down the stack of targets
2023
     until they find a target that is interested in handling that
2024
     particular address.
2025
 
2026
     This command prints a short description of each layer that was
2027
     pushed on the "target stack", starting from the top layer down to
2028
     the bottom one.
2029
 
2030
`maint print type EXPR'
2031
     Print the type chain for a type specified by EXPR.  The argument
2032
     can be either a type name or a symbol.  If it is a symbol, the
2033
     type of that symbol is described.  The type chain produced by this
2034
     command is a recursive definition of the data type as stored in
2035
     GDB's data structures, including its flags and contained types.
2036
 
2037
`maint set dwarf2 max-cache-age'
2038
`maint show dwarf2 max-cache-age'
2039
     Control the DWARF 2 compilation unit cache.
2040
 
2041
     In object files with inter-compilation-unit references, such as
2042
     those produced by the GCC option `-feliminate-dwarf2-dups', the
2043
     DWARF 2 reader needs to frequently refer to previously read
2044
     compilation units.  This setting controls how long a compilation
2045
     unit will remain in the cache if it is not referenced.  A higher
2046
     limit means that cached compilation units will be stored in memory
2047
     longer, and more total memory will be used.  Setting it to zero
2048
     disables caching, which will slow down GDB startup, but reduce
2049
     memory consumption.
2050
 
2051
`maint set profile'
2052
`maint show profile'
2053
     Control profiling of GDB.
2054
 
2055
     Profiling will be disabled until you use the `maint set profile'
2056
     command to enable it.  When you enable profiling, the system will
2057
     begin collecting timing and execution count data; when you disable
2058
     profiling or exit GDB, the results will be written to a log file.
2059
     Remember that if you use profiling, GDB will overwrite the
2060
     profiling log file (often called `gmon.out').  If you have a
2061
     record of important profiling data in a `gmon.out' file, be sure
2062
     to move it to a safe location.
2063
 
2064
     Configuring with `--enable-profiling' arranges for GDB to be
2065
     compiled with the `-pg' compiler option.
2066
 
2067
`maint set show-debug-regs'
2068
`maint show show-debug-regs'
2069
     Control whether to show variables that mirror the hardware debug
2070
     registers.  Use `ON' to enable, `OFF' to disable.  If enabled, the
2071
     debug registers values are shown when GDB inserts or removes a
2072
     hardware breakpoint or watchpoint, and when the inferior triggers
2073
     a hardware-assisted breakpoint or watchpoint.
2074
 
2075
`maint space'
2076
     Control whether to display memory usage for each command.  If set
2077
     to a nonzero value, GDB will display how much memory each command
2078
     took, following the command's own output.  This can also be
2079
     requested by invoking GDB with the `--statistics' command-line
2080
     switch (*note Mode Options::).
2081
 
2082
`maint time'
2083
     Control whether to display the execution time for each command.  If
2084
     set to a nonzero value, GDB will display how much time it took to
2085
     execute each command, following the command's own output.  The
2086
     time is not printed for the commands that run the target, since
2087
     there's no mechanism currently to compute how much time was spend
2088
     by GDB and how much time was spend by the program been debugged.
2089
     it's not possibly currently This can also be requested by invoking
2090
     GDB with the `--statistics' command-line switch (*note Mode
2091
     Options::).
2092
 
2093
`maint translate-address [SECTION] ADDR'
2094
     Find the symbol stored at the location specified by the address
2095
     ADDR and an optional section name SECTION.  If found, GDB prints
2096
     the name of the closest symbol and an offset from the symbol's
2097
     location to the specified address.  This is similar to the `info
2098
     address' command (*note Symbols::), except that this command also
2099
     allows to find symbols in other sections.
2100
 
2101
     If section was not specified, the section in which the symbol was
2102
     found is also printed.  For dynamically linked executables, the
2103
     name of executable or shared library containing the symbol is
2104
     printed as well.
2105
 
2106
 
2107
   The following command is useful for non-interactive invocations of
2108
GDB, such as in the test suite.
2109
 
2110
`set watchdog NSEC'
2111
     Set the maximum number of seconds GDB will wait for the target
2112
     operation to finish.  If this time expires, GDB reports and error
2113
     and the command is aborted.
2114
 
2115
`show watchdog'
2116
     Show the current setting of the target wait timeout.
2117
 
2118

2119
File: gdb.info,  Node: Remote Protocol,  Next: Agent Expressions,  Prev: Maintenance Commands,  Up: Top
2120
 
2121
Appendix D GDB Remote Serial Protocol
2122
*************************************
2123
 
2124
* Menu:
2125
 
2126
* Overview::
2127
* Packets::
2128
* Stop Reply Packets::
2129
* General Query Packets::
2130
* Architecture-Specific Protocol Details::
2131
* Tracepoint Packets::
2132
* Host I/O Packets::
2133
* Interrupts::
2134
* Notification Packets::
2135
* Remote Non-Stop::
2136
* Packet Acknowledgment::
2137
* Examples::
2138
* File-I/O Remote Protocol Extension::
2139
* Library List Format::
2140
* Memory Map Format::
2141
* Thread List Format::
2142
 
2143

2144
File: gdb.info,  Node: Overview,  Next: Packets,  Up: Remote Protocol
2145
 
2146
D.1 Overview
2147
============
2148
 
2149
There may be occasions when you need to know something about the
2150
protocol--for example, if there is only one serial port to your target
2151
machine, you might want your program to do something special if it
2152
recognizes a packet meant for GDB.
2153
 
2154
   In the examples below, `->' and `<-' are used to indicate
2155
transmitted and received data, respectively.
2156
 
2157
   All GDB commands and responses (other than acknowledgments and
2158
notifications, see *Note Notification Packets::) are sent as a PACKET.
2159
A PACKET is introduced with the character `$', the actual PACKET-DATA,
2160
and the terminating character `#' followed by a two-digit CHECKSUM:
2161
 
2162
     `$'PACKET-DATA`#'CHECKSUM
2163
   The two-digit CHECKSUM is computed as the modulo 256 sum of all
2164
characters between the leading `$' and the trailing `#' (an eight bit
2165
unsigned checksum).
2166
 
2167
   Implementors should note that prior to GDB 5.0 the protocol
2168
specification also included an optional two-digit SEQUENCE-ID:
2169
 
2170
     `$'SEQUENCE-ID`:'PACKET-DATA`#'CHECKSUM
2171
 
2172
That SEQUENCE-ID was appended to the acknowledgment.  GDB has never
2173
output SEQUENCE-IDs.  Stubs that handle packets added since GDB 5.0
2174
must not accept SEQUENCE-ID.
2175
 
2176
   When either the host or the target machine receives a packet, the
2177
first response expected is an acknowledgment: either `+' (to indicate
2178
the package was received correctly) or `-' (to request retransmission):
2179
 
2180
     -> `$'PACKET-DATA`#'CHECKSUM
2181
     <- `+'
2182
   The `+'/`-' acknowledgments can be disabled once a connection is
2183
established.  *Note Packet Acknowledgment::, for details.
2184
 
2185
   The host (GDB) sends COMMANDs, and the target (the debugging stub
2186
incorporated in your program) sends a RESPONSE.  In the case of step
2187
and continue COMMANDs, the response is only sent when the operation has
2188
completed, and the target has again stopped all threads in all attached
2189
processes.  This is the default all-stop mode behavior, but the remote
2190
protocol also supports GDB's non-stop execution mode; see *Note Remote
2191
Non-Stop::, for details.
2192
 
2193
   PACKET-DATA consists of a sequence of characters with the exception
2194
of `#' and `$' (see `X' packet for additional exceptions).
2195
 
2196
   Fields within the packet should be separated using `,' `;' or `:'.
2197
Except where otherwise noted all numbers are represented in HEX with
2198
leading zeros suppressed.
2199
 
2200
   Implementors should note that prior to GDB 5.0, the character `:'
2201
could not appear as the third character in a packet (as it would
2202
potentially conflict with the SEQUENCE-ID).
2203
 
2204
   Binary data in most packets is encoded either as two hexadecimal
2205
digits per byte of binary data.  This allowed the traditional remote
2206
protocol to work over connections which were only seven-bit clean.
2207
Some packets designed more recently assume an eight-bit clean
2208
connection, and use a more efficient encoding to send and receive
2209
binary data.
2210
 
2211
   The binary data representation uses `7d' (ASCII `}') as an escape
2212
character.  Any escaped byte is transmitted as the escape character
2213
followed by the original character XORed with `0x20'.  For example, the
2214
byte `0x7d' would be transmitted as the two bytes `0x7d 0x5d'.  The
2215
bytes `0x23' (ASCII `#'), `0x24' (ASCII `$'), and `0x7d' (ASCII `}')
2216
must always be escaped.  Responses sent by the stub must also escape
2217
`0x2a' (ASCII `*'), so that it is not interpreted as the start of a
2218
run-length encoded sequence (described next).
2219
 
2220
   Response DATA can be run-length encoded to save space.  Run-length
2221
encoding replaces runs of identical characters with one instance of the
2222
repeated character, followed by a `*' and a repeat count.  The repeat
2223
count is itself sent encoded, to avoid binary characters in DATA: a
2224
value of N is sent as `N+29'.  For a repeat count greater or equal to
2225
3, this produces a printable ASCII character, e.g. a space (ASCII code
2226
32) for a repeat count of 3.  (This is because run-length encoding
2227
starts to win for counts 3 or more.)  Thus, for example, `0* ' is a
2228
run-length encoding of "0000": the space character after `*' means
2229
repeat the leading `0' `32 - 29 = 3' more times.
2230
 
2231
   The printable characters `#' and `$' or with a numeric value greater
2232
than 126 must not be used.  Runs of six repeats (`#') or seven repeats
2233
(`$') can be expanded using a repeat count of only five (`"').  For
2234
example, `00000000' can be encoded as `0*"00'.
2235
 
2236
   The error response returned for some packets includes a two character
2237
error number.  That number is not well defined.
2238
 
2239
   For any COMMAND not supported by the stub, an empty response
2240
(`$#00') should be returned.  That way it is possible to extend the
2241
protocol.  A newer GDB can tell if a packet is supported based on that
2242
response.
2243
 
2244
   A stub is required to support the `g', `G', `m', `M', `c', and `s'
2245
COMMANDs.  All other COMMANDs are optional.
2246
 
2247

2248
File: gdb.info,  Node: Packets,  Next: Stop Reply Packets,  Prev: Overview,  Up: Remote Protocol
2249
 
2250
D.2 Packets
2251
===========
2252
 
2253
The following table provides a complete list of all currently defined
2254
COMMANDs and their corresponding response DATA.  *Note File-I/O Remote
2255
Protocol Extension::, for details about the File I/O extension of the
2256
remote protocol.
2257
 
2258
   Each packet's description has a template showing the packet's overall
2259
syntax, followed by an explanation of the packet's meaning.  We include
2260
spaces in some of the templates for clarity; these are not part of the
2261
packet's syntax.  No GDB packet uses spaces to separate its components.
2262
For example, a template like `foo BAR BAZ' describes a packet
2263
beginning with the three ASCII bytes `foo', followed by a BAR, followed
2264
directly by a BAZ.  GDB does not transmit a space character between the
2265
`foo' and the BAR, or between the BAR and the BAZ.
2266
 
2267
   Several packets and replies include a THREAD-ID field to identify a
2268
thread.  Normally these are positive numbers with a target-specific
2269
interpretation, formatted as big-endian hex strings.  A THREAD-ID can
2270
also be a literal `-1' to indicate all threads, or `0' to pick any
2271
thread.
2272
 
2273
   In addition, the remote protocol supports a multiprocess feature in
2274
which the THREAD-ID syntax is extended to optionally include both
2275
process and thread ID fields, as `pPID.TID'.  The PID (process) and TID
2276
(thread) components each have the format described above: a positive
2277
number with target-specific interpretation formatted as a big-endian
2278
hex string, literal `-1' to indicate all processes or threads
2279
(respectively), or `0' to indicate an arbitrary process or thread.
2280
Specifying just a process, as `pPID', is equivalent to `pPID.-1'.  It
2281
is an error to specify all processes but a specific thread, such as
2282
`p-1.TID'.  Note that the `p' prefix is _not_ used for those packets
2283
and replies explicitly documented to include a process ID, rather than
2284
a THREAD-ID.
2285
 
2286
   The multiprocess THREAD-ID syntax extensions are only used if both
2287
GDB and the stub report support for the `multiprocess' feature using
2288
`qSupported'.  *Note multiprocess extensions::, for more information.
2289
 
2290
   Note that all packet forms beginning with an upper- or lower-case
2291
letter, other than those described here, are reserved for future use.
2292
 
2293
   Here are the packet descriptions.
2294
 
2295
`!'
2296
     Enable extended mode.  In extended mode, the remote server is made
2297
     persistent.  The `R' packet is used to restart the program being
2298
     debugged.
2299
 
2300
     Reply:
2301
    `OK'
2302
          The remote target both supports and has enabled extended mode.
2303
 
2304
`?'
2305
     Indicate the reason the target halted.  The reply is the same as
2306
     for step and continue.  This packet has a special interpretation
2307
     when the target is in non-stop mode; see *Note Remote Non-Stop::.
2308
 
2309
     Reply: *Note Stop Reply Packets::, for the reply specifications.
2310
 
2311
`A ARGLEN,ARGNUM,ARG,...'
2312
     Initialized `argv[]' array passed into program. ARGLEN specifies
2313
     the number of bytes in the hex encoded byte stream ARG.  See
2314
     `gdbserver' for more details.
2315
 
2316
     Reply:
2317
    `OK'
2318
          The arguments were set.
2319
 
2320
    `E NN'
2321
          An error occurred.
2322
 
2323
`b BAUD'
2324
     (Don't use this packet; its behavior is not well-defined.)  Change
2325
     the serial line speed to BAUD.
2326
 
2327
     JTC: _When does the transport layer state change?  When it's
2328
     received, or after the ACK is transmitted.  In either case, there
2329
     are problems if the command or the acknowledgment packet is
2330
     dropped._
2331
 
2332
     Stan: _If people really wanted to add something like this, and get
2333
     it working for the first time, they ought to modify ser-unix.c to
2334
     send some kind of out-of-band message to a specially-setup stub
2335
     and have the switch happen "in between" packets, so that from
2336
     remote protocol's point of view, nothing actually happened._
2337
 
2338
`B ADDR,MODE'
2339
     Set (MODE is `S') or clear (MODE is `C') a breakpoint at ADDR.
2340
 
2341
     Don't use this packet.  Use the `Z' and `z' packets instead (*note
2342
     insert breakpoint or watchpoint packet::).
2343
 
2344
`bc'
2345
     Backward continue.  Execute the target system in reverse.  No
2346
     parameter.  *Note Reverse Execution::, for more information.
2347
 
2348
     Reply: *Note Stop Reply Packets::, for the reply specifications.
2349
 
2350
`bs'
2351
     Backward single step.  Execute one instruction in reverse.  No
2352
     parameter.  *Note Reverse Execution::, for more information.
2353
 
2354
     Reply: *Note Stop Reply Packets::, for the reply specifications.
2355
 
2356
`c [ADDR]'
2357
     Continue.  ADDR is address to resume.  If ADDR is omitted, resume
2358
     at current address.
2359
 
2360
     Reply: *Note Stop Reply Packets::, for the reply specifications.
2361
 
2362
`C SIG[;ADDR]'
2363
     Continue with signal SIG (hex signal number).  If `;ADDR' is
2364
     omitted, resume at same address.
2365
 
2366
     Reply: *Note Stop Reply Packets::, for the reply specifications.
2367
 
2368
`d'
2369
     Toggle debug flag.
2370
 
2371
     Don't use this packet; instead, define a general set packet (*note
2372
     General Query Packets::).
2373
 
2374
`D'
2375
`D;PID'
2376
     The first form of the packet is used to detach GDB from the remote
2377
     system.  It is sent to the remote target before GDB disconnects
2378
     via the `detach' command.
2379
 
2380
     The second form, including a process ID, is used when multiprocess
2381
     protocol extensions are enabled (*note multiprocess extensions::),
2382
     to detach only a specific process.  The PID is specified as a
2383
     big-endian hex string.
2384
 
2385
     Reply:
2386
    `OK'
2387
          for success
2388
 
2389
    `E NN'
2390
          for an error
2391
 
2392
`F RC,EE,CF;XX'
2393
     A reply from GDB to an `F' packet sent by the target.  This is
2394
     part of the File-I/O protocol extension.  *Note File-I/O Remote
2395
     Protocol Extension::, for the specification.
2396
 
2397
`g'
2398
     Read general registers.
2399
 
2400
     Reply:
2401
    `XX...'
2402
          Each byte of register data is described by two hex digits.
2403
          The bytes with the register are transmitted in target byte
2404
          order.  The size of each register and their position within
2405
          the `g' packet are determined by the GDB internal gdbarch
2406
          functions `DEPRECATED_REGISTER_RAW_SIZE' and
2407
          `gdbarch_register_name'.  The specification of several
2408
          standard `g' packets is specified below.
2409
 
2410
    `E NN'
2411
          for an error.
2412
 
2413
`G XX...'
2414
     Write general registers.  *Note read registers packet::, for a
2415
     description of the XX... data.
2416
 
2417
     Reply:
2418
    `OK'
2419
          for success
2420
 
2421
    `E NN'
2422
          for an error
2423
 
2424
`H C THREAD-ID'
2425
     Set thread for subsequent operations (`m', `M', `g', `G', et.al.).
2426
     C depends on the operation to be performed: it should be `c' for
2427
     step and continue operations, `g' for other operations.  The
2428
     thread designator THREAD-ID has the format and interpretation
2429
     described in *Note thread-id syntax::.
2430
 
2431
     Reply:
2432
    `OK'
2433
          for success
2434
 
2435
    `E NN'
2436
          for an error
2437
 
2438
`i [ADDR[,NNN]]'
2439
     Step the remote target by a single clock cycle.  If `,NNN' is
2440
     present, cycle step NNN cycles.  If ADDR is present, cycle step
2441
     starting at that address.
2442
 
2443
`I'
2444
     Signal, then cycle step.  *Note step with signal packet::.  *Note
2445
     cycle step packet::.
2446
 
2447
`k'
2448
     Kill request.
2449
 
2450
     FIXME: _There is no description of how to operate when a specific
2451
     thread context has been selected (i.e. does 'k' kill only that
2452
     thread?)_.
2453
 
2454
`m ADDR,LENGTH'
2455
     Read LENGTH bytes of memory starting at address ADDR.  Note that
2456
     ADDR may not be aligned to any particular boundary.
2457
 
2458
     The stub need not use any particular size or alignment when
2459
     gathering data from memory for the response; even if ADDR is
2460
     word-aligned and LENGTH is a multiple of the word size, the stub
2461
     is free to use byte accesses, or not.  For this reason, this
2462
     packet may not be suitable for accessing memory-mapped I/O devices.
2463
 
2464
     Reply:
2465
    `XX...'
2466
          Memory contents; each byte is transmitted as a two-digit
2467
          hexadecimal number.  The reply may contain fewer bytes than
2468
          requested if the server was able to read only part of the
2469
          region of memory.
2470
 
2471
    `E NN'
2472
          NN is errno
2473
 
2474
`M ADDR,LENGTH:XX...'
2475
     Write LENGTH bytes of memory starting at address ADDR.  XX... is
2476
     the data; each byte is transmitted as a two-digit hexadecimal
2477
     number.
2478
 
2479
     Reply:
2480
    `OK'
2481
          for success
2482
 
2483
    `E NN'
2484
          for an error (this includes the case where only part of the
2485
          data was written).
2486
 
2487
`p N'
2488
     Read the value of register N; N is in hex.  *Note read registers
2489
     packet::, for a description of how the returned register value is
2490
     encoded.
2491
 
2492
     Reply:
2493
    `XX...'
2494
          the register's value
2495
 
2496
    `E NN'
2497
          for an error
2498
 
2499
    `'
2500
          Indicating an unrecognized QUERY.
2501
 
2502
`P N...=R...'
2503
     Write register N... with value R....  The register number N is in
2504
     hexadecimal, and R... contains two hex digits for each byte in the
2505
     register (target byte order).
2506
 
2507
     Reply:
2508
    `OK'
2509
          for success
2510
 
2511
    `E NN'
2512
          for an error
2513
 
2514
`q NAME PARAMS...'
2515
`Q NAME PARAMS...'
2516
     General query (`q') and set (`Q').  These packets are described
2517
     fully in *Note General Query Packets::.
2518
 
2519
`r'
2520
     Reset the entire system.
2521
 
2522
     Don't use this packet; use the `R' packet instead.
2523
 
2524
`R XX'
2525
     Restart the program being debugged.  XX, while needed, is ignored.
2526
     This packet is only available in extended mode (*note extended
2527
     mode::).
2528
 
2529
     The `R' packet has no reply.
2530
 
2531
`s [ADDR]'
2532
     Single step.  ADDR is the address at which to resume.  If ADDR is
2533
     omitted, resume at same address.
2534
 
2535
     Reply: *Note Stop Reply Packets::, for the reply specifications.
2536
 
2537
`S SIG[;ADDR]'
2538
     Step with signal.  This is analogous to the `C' packet, but
2539
     requests a single-step, rather than a normal resumption of
2540
     execution.
2541
 
2542
     Reply: *Note Stop Reply Packets::, for the reply specifications.
2543
 
2544
`t ADDR:PP,MM'
2545
     Search backwards starting at address ADDR for a match with pattern
2546
     PP and mask MM.  PP and MM are 4 bytes.  ADDR must be at least 3
2547
     digits.
2548
 
2549
`T THREAD-ID'
2550
     Find out if the thread THREAD-ID is alive.  *Note thread-id
2551
     syntax::.
2552
 
2553
     Reply:
2554
    `OK'
2555
          thread is still alive
2556
 
2557
    `E NN'
2558
          thread is dead
2559
 
2560
`v'
2561
     Packets starting with `v' are identified by a multi-letter name,
2562
     up to the first `;' or `?' (or the end of the packet).
2563
 
2564
`vAttach;PID'
2565
     Attach to a new process with the specified process ID PID.  The
2566
     process ID is a hexadecimal integer identifying the process.  In
2567
     all-stop mode, all threads in the attached process are stopped; in
2568
     non-stop mode, it may be attached without being stopped if that is
2569
     supported by the target.
2570
 
2571
     This packet is only available in extended mode (*note extended
2572
     mode::).
2573
 
2574
     Reply:
2575
    `E NN'
2576
          for an error
2577
 
2578
    `Any stop packet'
2579
          for success in all-stop mode (*note Stop Reply Packets::)
2580
 
2581
    `OK'
2582
          for success in non-stop mode (*note Remote Non-Stop::)
2583
 
2584
`vCont[;ACTION[:THREAD-ID]]...'
2585
     Resume the inferior, specifying different actions for each thread.
2586
     If an action is specified with no THREAD-ID, then it is applied to
2587
     any threads that don't have a specific action specified; if no
2588
     default action is specified then other threads should remain
2589
     stopped in all-stop mode and in their current state in non-stop
2590
     mode.  Specifying multiple default actions is an error; specifying
2591
     no actions is also an error.  Thread IDs are specified using the
2592
     syntax described in *Note thread-id syntax::.
2593
 
2594
     Currently supported actions are:
2595
 
2596
    `c'
2597
          Continue.
2598
 
2599
    `C SIG'
2600
          Continue with signal SIG.  The signal SIG should be two hex
2601
          digits.
2602
 
2603
    `s'
2604
          Step.
2605
 
2606
    `S SIG'
2607
          Step with signal SIG.  The signal SIG should be two hex
2608
          digits.
2609
 
2610
    `t'
2611
          Stop.
2612
 
2613
     The optional argument ADDR normally associated with the `c', `C',
2614
     `s', and `S' packets is not supported in `vCont'.
2615
 
2616
     The `t' action is only relevant in non-stop mode (*note Remote
2617
     Non-Stop::) and may be ignored by the stub otherwise.  A stop
2618
     reply should be generated for any affected thread not already
2619
     stopped.  When a thread is stopped by means of a `t' action, the
2620
     corresponding stop reply should indicate that the thread has
2621
     stopped with signal `0', regardless of whether the target uses
2622
     some other signal as an implementation detail.
2623
 
2624
     Reply: *Note Stop Reply Packets::, for the reply specifications.
2625
 
2626
`vCont?'
2627
     Request a list of actions supported by the `vCont' packet.
2628
 
2629
     Reply:
2630
    `vCont[;ACTION...]'
2631
          The `vCont' packet is supported.  Each ACTION is a supported
2632
          command in the `vCont' packet.
2633
 
2634
    `'
2635
          The `vCont' packet is not supported.
2636
 
2637
`vFile:OPERATION:PARAMETER...'
2638
     Perform a file operation on the target system.  For details, see
2639
     *Note Host I/O Packets::.
2640
 
2641
`vFlashErase:ADDR,LENGTH'
2642
     Direct the stub to erase LENGTH bytes of flash starting at ADDR.
2643
     The region may enclose any number of flash blocks, but its start
2644
     and end must fall on block boundaries, as indicated by the flash
2645
     block size appearing in the memory map (*note Memory Map
2646
     Format::).  GDB groups flash memory programming operations
2647
     together, and sends a `vFlashDone' request after each group; the
2648
     stub is allowed to delay erase operation until the `vFlashDone'
2649
     packet is received.
2650
 
2651
     The stub must support `vCont' if it reports support for
2652
     multiprocess extensions (*note multiprocess extensions::).  Note
2653
     that in this case `vCont' actions can be specified to apply to all
2654
     threads in a process by using the `pPID.-1' form of the THREAD-ID.
2655
 
2656
     Reply:
2657
    `OK'
2658
          for success
2659
 
2660
    `E NN'
2661
          for an error
2662
 
2663
`vFlashWrite:ADDR:XX...'
2664
     Direct the stub to write data to flash address ADDR.  The data is
2665
     passed in binary form using the same encoding as for the `X'
2666
     packet (*note Binary Data::).  The memory ranges specified by
2667
     `vFlashWrite' packets preceding a `vFlashDone' packet must not
2668
     overlap, and must appear in order of increasing addresses
2669
     (although `vFlashErase' packets for higher addresses may already
2670
     have been received; the ordering is guaranteed only between
2671
     `vFlashWrite' packets).  If a packet writes to an address that was
2672
     neither erased by a preceding `vFlashErase' packet nor by some
2673
     other target-specific method, the results are unpredictable.
2674
 
2675
     Reply:
2676
    `OK'
2677
          for success
2678
 
2679
    `E.memtype'
2680
          for vFlashWrite addressing non-flash memory
2681
 
2682
    `E NN'
2683
          for an error
2684
 
2685
`vFlashDone'
2686
     Indicate to the stub that flash programming operation is finished.
2687
     The stub is permitted to delay or batch the effects of a group of
2688
     `vFlashErase' and `vFlashWrite' packets until a `vFlashDone'
2689
     packet is received.  The contents of the affected regions of flash
2690
     memory are unpredictable until the `vFlashDone' request is
2691
     completed.
2692
 
2693
`vKill;PID'
2694
     Kill the process with the specified process ID.  PID is a
2695
     hexadecimal integer identifying the process.  This packet is used
2696
     in preference to `k' when multiprocess protocol extensions are
2697
     supported; see *Note multiprocess extensions::.
2698
 
2699
     Reply:
2700
    `E NN'
2701
          for an error
2702
 
2703
    `OK'
2704
          for success
2705
 
2706
`vRun;FILENAME[;ARGUMENT]...'
2707
     Run the program FILENAME, passing it each ARGUMENT on its command
2708
     line.  The file and arguments are hex-encoded strings.  If
2709
     FILENAME is an empty string, the stub may use a default program
2710
     (e.g. the last program run).  The program is created in the stopped
2711
     state.
2712
 
2713
     This packet is only available in extended mode (*note extended
2714
     mode::).
2715
 
2716
     Reply:
2717
    `E NN'
2718
          for an error
2719
 
2720
    `Any stop packet'
2721
          for success (*note Stop Reply Packets::)
2722
 
2723
`vStopped'
2724
     In non-stop mode (*note Remote Non-Stop::), acknowledge a previous
2725
     stop reply and prompt for the stub to report another one.
2726
 
2727
     Reply:
2728
    `Any stop packet'
2729
          if there is another unreported stop event (*note Stop Reply
2730
          Packets::)
2731
 
2732
    `OK'
2733
          if there are no unreported stop events
2734
 
2735
`X ADDR,LENGTH:XX...'
2736
     Write data to memory, where the data is transmitted in binary.
2737
     ADDR is address, LENGTH is number of bytes, `XX...' is binary data
2738
     (*note Binary Data::).
2739
 
2740
     Reply:
2741
    `OK'
2742
          for success
2743
 
2744
    `E NN'
2745
          for an error
2746
 
2747
`z TYPE,ADDR,KIND'
2748
`Z TYPE,ADDR,KIND'
2749
     Insert (`Z') or remove (`z') a TYPE breakpoint or watchpoint
2750
     starting at address ADDRESS of kind KIND.
2751
 
2752
     Each breakpoint and watchpoint packet TYPE is documented
2753
     separately.
2754
 
2755
     _Implementation notes: A remote target shall return an empty string
2756
     for an unrecognized breakpoint or watchpoint packet TYPE.  A
2757
     remote target shall support either both or neither of a given
2758
     `ZTYPE...' and `zTYPE...' packet pair.  To avoid potential
2759
     problems with duplicate packets, the operations should be
2760
     implemented in an idempotent way._
2761
 
2762
`z0,ADDR,KIND'
2763
`Z0,ADDR,KIND'
2764
     Insert (`Z0') or remove (`z0') a memory breakpoint at address ADDR
2765
     of type KIND.
2766
 
2767
     A memory breakpoint is implemented by replacing the instruction at
2768
     ADDR with a software breakpoint or trap instruction.  The KIND is
2769
     target-specific and typically indicates the size of the breakpoint
2770
     in bytes that should be inserted.  E.g., the ARM and MIPS can
2771
     insert either a 2 or 4 byte breakpoint.  Some architectures have
2772
     additional meanings for KIND; see *Note Architecture-Specific
2773
     Protocol Details::.
2774
 
2775
     _Implementation note: It is possible for a target to copy or move
2776
     code that contains memory breakpoints (e.g., when implementing
2777
     overlays).  The behavior of this packet, in the presence of such a
2778
     target, is not defined._
2779
 
2780
     Reply:
2781
    `OK'
2782
          success
2783
 
2784
    `'
2785
          not supported
2786
 
2787
    `E NN'
2788
          for an error
2789
 
2790
`z1,ADDR,KIND'
2791
`Z1,ADDR,KIND'
2792
     Insert (`Z1') or remove (`z1') a hardware breakpoint at address
2793
     ADDR.
2794
 
2795
     A hardware breakpoint is implemented using a mechanism that is not
2796
     dependant on being able to modify the target's memory.  KIND has
2797
     the same meaning as in `Z0' packets.
2798
 
2799
     _Implementation note: A hardware breakpoint is not affected by code
2800
     movement._
2801
 
2802
     Reply:
2803
    `OK'
2804
          success
2805
 
2806
    `'
2807
          not supported
2808
 
2809
    `E NN'
2810
          for an error
2811
 
2812
`z2,ADDR,KIND'
2813
`Z2,ADDR,KIND'
2814
     Insert (`Z2') or remove (`z2') a write watchpoint at ADDR.  KIND
2815
     is interpreted as the number of bytes to watch.
2816
 
2817
     Reply:
2818
    `OK'
2819
          success
2820
 
2821
    `'
2822
          not supported
2823
 
2824
    `E NN'
2825
          for an error
2826
 
2827
`z3,ADDR,KIND'
2828
`Z3,ADDR,KIND'
2829
     Insert (`Z3') or remove (`z3') a read watchpoint at ADDR.  KIND is
2830
     interpreted as the number of bytes to watch.
2831
 
2832
     Reply:
2833
    `OK'
2834
          success
2835
 
2836
    `'
2837
          not supported
2838
 
2839
    `E NN'
2840
          for an error
2841
 
2842
`z4,ADDR,KIND'
2843
`Z4,ADDR,KIND'
2844
     Insert (`Z4') or remove (`z4') an access watchpoint at ADDR.  KIND
2845
     is interpreted as the number of bytes to watch.
2846
 
2847
     Reply:
2848
    `OK'
2849
          success
2850
 
2851
    `'
2852
          not supported
2853
 
2854
    `E NN'
2855
          for an error
2856
 
2857
 
2858

2859
File: gdb.info,  Node: Stop Reply Packets,  Next: General Query Packets,  Prev: Packets,  Up: Remote Protocol
2860
 
2861
D.3 Stop Reply Packets
2862
======================
2863
 
2864
The `C', `c', `S', `s', `vCont', `vAttach', `vRun', `vStopped', and `?'
2865
packets can receive any of the below as a reply.  Except for `?' and
2866
`vStopped', that reply is only returned when the target halts.  In the
2867
below the exact meaning of "signal number" is defined by the header
2868
`include/gdb/signals.h' in the GDB source code.
2869
 
2870
   As in the description of request packets, we include spaces in the
2871
reply templates for clarity; these are not part of the reply packet's
2872
syntax.  No GDB stop reply packet uses spaces to separate its
2873
components.
2874
 
2875
`S AA'
2876
     The program received signal number AA (a two-digit hexadecimal
2877
     number).  This is equivalent to a `T' response with no N:R pairs.
2878
 
2879
`T AA N1:R1;N2:R2;...'
2880
     The program received signal number AA (a two-digit hexadecimal
2881
     number).  This is equivalent to an `S' response, except that the
2882
     `N:R' pairs can carry values of important registers and other
2883
     information directly in the stop reply packet, reducing round-trip
2884
     latency.  Single-step and breakpoint traps are reported this way.
2885
     Each `N:R' pair is interpreted as follows:
2886
 
2887
        * If N is a hexadecimal number, it is a register number, and the
2888
          corresponding R gives that register's value.  R is a series
2889
          of bytes in target byte order, with each byte given by a
2890
          two-digit hex number.
2891
 
2892
        * If N is `thread', then R is the THREAD-ID of the stopped
2893
          thread, as specified in *Note thread-id syntax::.
2894
 
2895
        * If N is `core', then R is the hexadecimal number of the core
2896
          on which the stop event was detected.
2897
 
2898
        * If N is a recognized "stop reason", it describes a more
2899
          specific event that stopped the target.  The currently
2900
          defined stop reasons are listed below.  AA should be `05',
2901
          the trap signal.  At most one stop reason should be present.
2902
 
2903
        * Otherwise, GDB should ignore this `N:R' pair and go on to the
2904
          next; this allows us to extend the protocol in the future.
2905
 
2906
     The currently defined stop reasons are:
2907
 
2908
    `watch'
2909
    `rwatch'
2910
    `awatch'
2911
          The packet indicates a watchpoint hit, and R is the data
2912
          address, in hex.
2913
 
2914
    `library'
2915
          The packet indicates that the loaded libraries have changed.
2916
          GDB should use `qXfer:libraries:read' to fetch a new list of
2917
          loaded libraries.  R is ignored.
2918
 
2919
    `replaylog'
2920
          The packet indicates that the target cannot continue replaying
2921
          logged execution events, because it has reached the end (or
2922
          the beginning when executing backward) of the log.  The value
2923
          of R will be either `begin' or `end'.  *Note Reverse
2924
          Execution::, for more information.
2925
 
2926
`W AA'
2927
`W AA ; process:PID'
2928
     The process exited, and AA is the exit status.  This is only
2929
     applicable to certain targets.
2930
 
2931
     The second form of the response, including the process ID of the
2932
     exited process, can be used only when GDB has reported support for
2933
     multiprocess protocol extensions; see *Note multiprocess
2934
     extensions::.  The PID is formatted as a big-endian hex string.
2935
 
2936
`X AA'
2937
`X AA ; process:PID'
2938
     The process terminated with signal AA.
2939
 
2940
     The second form of the response, including the process ID of the
2941
     terminated process, can be used only when GDB has reported support
2942
     for multiprocess protocol extensions; see *Note multiprocess
2943
     extensions::.  The PID is formatted as a big-endian hex string.
2944
 
2945
`O XX...'
2946
     `XX...' is hex encoding of ASCII data, to be written as the
2947
     program's console output.  This can happen at any time while the
2948
     program is running and the debugger should continue to wait for
2949
     `W', `T', etc.  This reply is not permitted in non-stop mode.
2950
 
2951
`F CALL-ID,PARAMETER...'
2952
     CALL-ID is the identifier which says which host system call should
2953
     be called.  This is just the name of the function.  Translation
2954
     into the correct system call is only applicable as it's defined in
2955
     GDB.  *Note File-I/O Remote Protocol Extension::, for a list of
2956
     implemented system calls.
2957
 
2958
     `PARAMETER...' is a list of parameters as defined for this very
2959
     system call.
2960
 
2961
     The target replies with this packet when it expects GDB to call a
2962
     host system call on behalf of the target.  GDB replies with an
2963
     appropriate `F' packet and keeps up waiting for the next reply
2964
     packet from the target.  The latest `C', `c', `S' or `s' action is
2965
     expected to be continued.  *Note File-I/O Remote Protocol
2966
     Extension::, for more details.
2967
 
2968
 
2969

2970
File: gdb.info,  Node: General Query Packets,  Next: Architecture-Specific Protocol Details,  Prev: Stop Reply Packets,  Up: Remote Protocol
2971
 
2972
D.4 General Query Packets
2973
=========================
2974
 
2975
Packets starting with `q' are "general query packets"; packets starting
2976
with `Q' are "general set packets".  General query and set packets are
2977
a semi-unified form for retrieving and sending information to and from
2978
the stub.
2979
 
2980
   The initial letter of a query or set packet is followed by a name
2981
indicating what sort of thing the packet applies to.  For example, GDB
2982
may use a `qSymbol' packet to exchange symbol definitions with the
2983
stub.  These packet names follow some conventions:
2984
 
2985
   * The name must not contain commas, colons or semicolons.
2986
 
2987
   * Most GDB query and set packets have a leading upper case letter.
2988
 
2989
   * The names of custom vendor packets should use a company prefix, in
2990
     lower case, followed by a period.  For example, packets designed at
2991
     the Acme Corporation might begin with `qacme.foo' (for querying
2992
     foos) or `Qacme.bar' (for setting bars).
2993
 
2994
   The name of a query or set packet should be separated from any
2995
parameters by a `:'; the parameters themselves should be separated by
2996
`,' or `;'.  Stubs must be careful to match the full packet name, and
2997
check for a separator or the end of the packet, in case two packet
2998
names share a common prefix.  New packets should not begin with `qC',
2999
`qP', or `qL'(1).
3000
 
3001
   Like the descriptions of the other packets, each description here
3002
has a template showing the packet's overall syntax, followed by an
3003
explanation of the packet's meaning.  We include spaces in some of the
3004
templates for clarity; these are not part of the packet's syntax.  No
3005
GDB packet uses spaces to separate its components.
3006
 
3007
   Here are the currently defined query and set packets:
3008
 
3009
`qC'
3010
     Return the current thread ID.
3011
 
3012
     Reply:
3013
    `QC THREAD-ID'
3014
          Where THREAD-ID is a thread ID as documented in *Note
3015
          thread-id syntax::.
3016
 
3017
    `(anything else)'
3018
          Any other reply implies the old thread ID.
3019
 
3020
`qCRC:ADDR,LENGTH'
3021
     Compute the CRC checksum of a block of memory using CRC-32 defined
3022
     in IEEE 802.3.  The CRC is computed byte at a time, taking the most
3023
     significant bit of each byte first.  The initial pattern code
3024
     `0xffffffff' is used to ensure leading zeros affect the CRC.
3025
 
3026
     _Note:_ This is the same CRC used in validating separate debug
3027
     files (*note Debugging Information in Separate Files: Separate
3028
     Debug Files.).  However the algorithm is slightly different.  When
3029
     validating separate debug files, the CRC is computed taking the
3030
     _least_ significant bit of each byte first, and the final result
3031
     is inverted to detect trailing zeros.
3032
 
3033
     Reply:
3034
    `E NN'
3035
          An error (such as memory fault)
3036
 
3037
    `C CRC32'
3038
          The specified memory region's checksum is CRC32.
3039
 
3040
`qfThreadInfo'
3041
`qsThreadInfo'
3042
     Obtain a list of all active thread IDs from the target (OS).
3043
     Since there may be too many active threads to fit into one reply
3044
     packet, this query works iteratively: it may require more than one
3045
     query/reply sequence to obtain the entire list of threads.  The
3046
     first query of the sequence will be the `qfThreadInfo' query;
3047
     subsequent queries in the sequence will be the `qsThreadInfo'
3048
     query.
3049
 
3050
     NOTE: This packet replaces the `qL' query (see below).
3051
 
3052
     Reply:
3053
    `m THREAD-ID'
3054
          A single thread ID
3055
 
3056
    `m THREAD-ID,THREAD-ID...'
3057
          a comma-separated list of thread IDs
3058
 
3059
    `l'
3060
          (lower case letter `L') denotes end of list.
3061
 
3062
     In response to each query, the target will reply with a list of
3063
     one or more thread IDs, separated by commas.  GDB will respond to
3064
     each reply with a request for more thread ids (using the `qs' form
3065
     of the query), until the target responds with `l' (lower-case el,
3066
     for "last").  Refer to *Note thread-id syntax::, for the format of
3067
     the THREAD-ID fields.
3068
 
3069
`qGetTLSAddr:THREAD-ID,OFFSET,LM'
3070
     Fetch the address associated with thread local storage specified
3071
     by THREAD-ID, OFFSET, and LM.
3072
 
3073
     THREAD-ID is the thread ID associated with the thread for which to
3074
     fetch the TLS address.  *Note thread-id syntax::.
3075
 
3076
     OFFSET is the (big endian, hex encoded) offset associated with the
3077
     thread local variable.  (This offset is obtained from the debug
3078
     information associated with the variable.)
3079
 
3080
     LM is the (big endian, hex encoded) OS/ABI-specific encoding of the
3081
     the load module associated with the thread local storage.  For
3082
     example, a GNU/Linux system will pass the link map address of the
3083
     shared object associated with the thread local storage under
3084
     consideration.  Other operating environments may choose to
3085
     represent the load module differently, so the precise meaning of
3086
     this parameter will vary.
3087
 
3088
     Reply:
3089
    `XX...'
3090
          Hex encoded (big endian) bytes representing the address of
3091
          the thread local storage requested.
3092
 
3093
    `E NN'
3094
          An error occurred.  NN are hex digits.
3095
 
3096
    `'
3097
          An empty reply indicates that `qGetTLSAddr' is not supported
3098
          by the stub.
3099
 
3100
`qL STARTFLAG THREADCOUNT NEXTTHREAD'
3101
     Obtain thread information from RTOS.  Where: STARTFLAG (one hex
3102
     digit) is one to indicate the first query and zero to indicate a
3103
     subsequent query; THREADCOUNT (two hex digits) is the maximum
3104
     number of threads the response packet can contain; and NEXTTHREAD
3105
     (eight hex digits), for subsequent queries (STARTFLAG is zero), is
3106
     returned in the response as ARGTHREAD.
3107
 
3108
     Don't use this packet; use the `qfThreadInfo' query instead (see
3109
     above).
3110
 
3111
     Reply:
3112
    `qM COUNT DONE ARGTHREAD THREAD...'
3113
          Where: COUNT (two hex digits) is the number of threads being
3114
          returned; DONE (one hex digit) is zero to indicate more
3115
          threads and one indicates no further threads; ARGTHREADID
3116
          (eight hex digits) is NEXTTHREAD from the request packet;
3117
          THREAD...  is a sequence of thread IDs from the target.
3118
          THREADID (eight hex digits).  See
3119
          `remote.c:parse_threadlist_response()'.
3120
 
3121
`qOffsets'
3122
     Get section offsets that the target used when relocating the
3123
     downloaded image.
3124
 
3125
     Reply:
3126
    `Text=XXX;Data=YYY[;Bss=ZZZ]'
3127
          Relocate the `Text' section by XXX from its original address.
3128
          Relocate the `Data' section by YYY from its original address.
3129
          If the object file format provides segment information (e.g.
3130
          ELF `PT_LOAD' program headers), GDB will relocate entire
3131
          segments by the supplied offsets.
3132
 
3133
          _Note: while a `Bss' offset may be included in the response,
3134
          GDB ignores this and instead applies the `Data' offset to the
3135
          `Bss' section._
3136
 
3137
    `TextSeg=XXX[;DataSeg=YYY]'
3138
          Relocate the first segment of the object file, which
3139
          conventionally contains program code, to a starting address
3140
          of XXX.  If `DataSeg' is specified, relocate the second
3141
          segment, which conventionally contains modifiable data, to a
3142
          starting address of YYY.  GDB will report an error if the
3143
          object file does not contain segment information, or does not
3144
          contain at least as many segments as mentioned in the reply.
3145
          Extra segments are kept at fixed offsets relative to the last
3146
          relocated segment.
3147
 
3148
`qP MODE THREAD-ID'
3149
     Returns information on THREAD-ID.  Where: MODE is a hex encoded 32
3150
     bit mode; THREAD-ID is a thread ID (*note thread-id syntax::).
3151
 
3152
     Don't use this packet; use the `qThreadExtraInfo' query instead
3153
     (see below).
3154
 
3155
     Reply: see `remote.c:remote_unpack_thread_info_response()'.
3156
 
3157
`QNonStop:1'
3158
 
3159
`QNonStop:0'
3160
     Enter non-stop (`QNonStop:1') or all-stop (`QNonStop:0') mode.
3161
     *Note Remote Non-Stop::, for more information.
3162
 
3163
     Reply:
3164
    `OK'
3165
          The request succeeded.
3166
 
3167
    `E NN'
3168
          An error occurred.  NN are hex digits.
3169
 
3170
    `'
3171
          An empty reply indicates that `QNonStop' is not supported by
3172
          the stub.
3173
 
3174
     This packet is not probed by default; the remote stub must request
3175
     it, by supplying an appropriate `qSupported' response (*note
3176
     qSupported::).  Use of this packet is controlled by the `set
3177
     non-stop' command; *note Non-Stop Mode::.
3178
 
3179
`QPassSignals: SIGNAL [;SIGNAL]...'
3180
     Each listed SIGNAL should be passed directly to the inferior
3181
     process.  Signals are numbered identically to continue packets and
3182
     stop replies (*note Stop Reply Packets::).  Each SIGNAL list item
3183
     should be strictly greater than the previous item.  These signals
3184
     do not need to stop the inferior, or be reported to GDB.  All
3185
     other signals should be reported to GDB.  Multiple `QPassSignals'
3186
     packets do not combine; any earlier `QPassSignals' list is
3187
     completely replaced by the new list.  This packet improves
3188
     performance when using `handle SIGNAL nostop noprint pass'.
3189
 
3190
     Reply:
3191
    `OK'
3192
          The request succeeded.
3193
 
3194
    `E NN'
3195
          An error occurred.  NN are hex digits.
3196
 
3197
    `'
3198
          An empty reply indicates that `QPassSignals' is not supported
3199
          by the stub.
3200
 
3201
     Use of this packet is controlled by the `set remote pass-signals'
3202
     command (*note set remote pass-signals: Remote Configuration.).
3203
     This packet is not probed by default; the remote stub must request
3204
     it, by supplying an appropriate `qSupported' response (*note
3205
     qSupported::).
3206
 
3207
`qRcmd,COMMAND'
3208
     COMMAND (hex encoded) is passed to the local interpreter for
3209
     execution.  Invalid commands should be reported using the output
3210
     string.  Before the final result packet, the target may also
3211
     respond with a number of intermediate `OOUTPUT' console output
3212
     packets.  _Implementors should note that providing access to a
3213
     stubs's interpreter may have security implications_.
3214
 
3215
     Reply:
3216
    `OK'
3217
          A command response with no output.
3218
 
3219
    `OUTPUT'
3220
          A command response with the hex encoded output string OUTPUT.
3221
 
3222
    `E NN'
3223
          Indicate a badly formed request.
3224
 
3225
    `'
3226
          An empty reply indicates that `qRcmd' is not recognized.
3227
 
3228
     (Note that the `qRcmd' packet's name is separated from the command
3229
     by a `,', not a `:', contrary to the naming conventions above.
3230
     Please don't use this packet as a model for new packets.)
3231
 
3232
`qSearch:memory:ADDRESS;LENGTH;SEARCH-PATTERN'
3233
     Search LENGTH bytes at ADDRESS for SEARCH-PATTERN.  ADDRESS and
3234
     LENGTH are encoded in hex.  SEARCH-PATTERN is a sequence of bytes,
3235
     hex encoded.
3236
 
3237
     Reply:
3238
    `0'
3239
          The pattern was not found.
3240
 
3241
    `1,address'
3242
          The pattern was found at ADDRESS.
3243
 
3244
    `E NN'
3245
          A badly formed request or an error was encountered while
3246
          searching memory.
3247
 
3248
    `'
3249
          An empty reply indicates that `qSearch:memory' is not
3250
          recognized.
3251
 
3252
`QStartNoAckMode'
3253
     Request that the remote stub disable the normal `+'/`-' protocol
3254
     acknowledgments (*note Packet Acknowledgment::).
3255
 
3256
     Reply:
3257
    `OK'
3258
          The stub has switched to no-acknowledgment mode.  GDB
3259
          acknowledges this reponse, but neither the stub nor GDB shall
3260
          send or expect further `+'/`-' acknowledgments in the current
3261
          connection.
3262
 
3263
    `'
3264
          An empty reply indicates that the stub does not support
3265
          no-acknowledgment mode.
3266
 
3267
`qSupported [:GDBFEATURE [;GDBFEATURE]... ]'
3268
     Tell the remote stub about features supported by GDB, and query
3269
     the stub for features it supports.  This packet allows GDB and the
3270
     remote stub to take advantage of each others' features.
3271
     `qSupported' also consolidates multiple feature probes at startup,
3272
     to improve GDB performance--a single larger packet performs better
3273
     than multiple smaller probe packets on high-latency links.  Some
3274
     features may enable behavior which must not be on by default, e.g.
3275
     because it would confuse older clients or stubs.  Other features
3276
     may describe packets which could be automatically probed for, but
3277
     are not.  These features must be reported before GDB will use
3278
     them.  This "default unsupported" behavior is not appropriate for
3279
     all packets, but it helps to keep the initial connection time
3280
     under control with new versions of GDB which support increasing
3281
     numbers of packets.
3282
 
3283
     Reply:
3284
    `STUBFEATURE [;STUBFEATURE]...'
3285
          The stub supports or does not support each returned
3286
          STUBFEATURE, depending on the form of each STUBFEATURE (see
3287
          below for the possible forms).
3288
 
3289
    `'
3290
          An empty reply indicates that `qSupported' is not recognized,
3291
          or that no features needed to be reported to GDB.
3292
 
3293
     The allowed forms for each feature (either a GDBFEATURE in the
3294
     `qSupported' packet, or a STUBFEATURE in the response) are:
3295
 
3296
    `NAME=VALUE'
3297
          The remote protocol feature NAME is supported, and associated
3298
          with the specified VALUE.  The format of VALUE depends on the
3299
          feature, but it must not include a semicolon.
3300
 
3301
    `NAME+'
3302
          The remote protocol feature NAME is supported, and does not
3303
          need an associated value.
3304
 
3305
    `NAME-'
3306
          The remote protocol feature NAME is not supported.
3307
 
3308
    `NAME?'
3309
          The remote protocol feature NAME may be supported, and GDB
3310
          should auto-detect support in some other way when it is
3311
          needed.  This form will not be used for GDBFEATURE
3312
          notifications, but may be used for STUBFEATURE responses.
3313
 
3314
     Whenever the stub receives a `qSupported' request, the supplied
3315
     set of GDB features should override any previous request.  This
3316
     allows GDB to put the stub in a known state, even if the stub had
3317
     previously been communicating with a different version of GDB.
3318
 
3319
     The following values of GDBFEATURE (for the packet sent by GDB)
3320
     are defined:
3321
 
3322
    `multiprocess'
3323
          This feature indicates whether GDB supports multiprocess
3324
          extensions to the remote protocol.  GDB does not use such
3325
          extensions unless the stub also reports that it supports them
3326
          by including `multiprocess+' in its `qSupported' reply.
3327
          *Note multiprocess extensions::, for details.
3328
 
3329
     Stubs should ignore any unknown values for GDBFEATURE.  Any GDB
3330
     which sends a `qSupported' packet supports receiving packets of
3331
     unlimited length (earlier versions of GDB may reject overly long
3332
     responses).  Additional values for GDBFEATURE may be defined in
3333
     the future to let the stub take advantage of new features in GDB,
3334
     e.g. incompatible improvements in the remote protocol--the
3335
     `multiprocess' feature is an example of such a feature.  The
3336
     stub's reply should be independent of the GDBFEATURE entries sent
3337
     by GDB; first GDB describes all the features it supports, and then
3338
     the stub replies with all the features it supports.
3339
 
3340
     Similarly, GDB will silently ignore unrecognized stub feature
3341
     responses, as long as each response uses one of the standard forms.
3342
 
3343
     Some features are flags.  A stub which supports a flag feature
3344
     should respond with a `+' form response.  Other features require
3345
     values, and the stub should respond with an `=' form response.
3346
 
3347
     Each feature has a default value, which GDB will use if
3348
     `qSupported' is not available or if the feature is not mentioned
3349
     in the `qSupported' response.  The default values are fixed; a
3350
     stub is free to omit any feature responses that match the defaults.
3351
 
3352
     Not all features can be probed, but for those which can, the
3353
     probing mechanism is useful: in some cases, a stub's internal
3354
     architecture may not allow the protocol layer to know some
3355
     information about the underlying target in advance.  This is
3356
     especially common in stubs which may be configured for multiple
3357
     targets.
3358
 
3359
     These are the currently defined stub features and their properties:
3360
 
3361
     Feature Name            Value         Default  Probe Allowed
3362
                             Required
3363
     `PacketSize'            Yes           `-'      No
3364
     `qXfer:auxv:read'       No            `-'      Yes
3365
     `qXfer:features:read'   No            `-'      Yes
3366
     `qXfer:libraries:read'  No            `-'      Yes
3367
     `qXfer:memory-map:read' No            `-'      Yes
3368
     `qXfer:spu:read'        No            `-'      Yes
3369
     `qXfer:spu:write'       No            `-'      Yes
3370
     `qXfer:siginfo:read'    No            `-'      Yes
3371
     `qXfer:siginfo:write'   No            `-'      Yes
3372
     `qXfer:threads:read'    No            `-'      Yes
3373
     `QNonStop'              No            `-'      Yes
3374
     `QPassSignals'          No            `-'      Yes
3375
     `QStartNoAckMode'       No            `-'      Yes
3376
     `multiprocess'          No            `-'      No
3377
     `ConditionalTracepoints'No            `-'      No
3378
     `ReverseContinue'       No            `-'      No
3379
     `ReverseStep'           No            `-'      No
3380
 
3381
     These are the currently defined stub features, in more detail:
3382
 
3383
    `PacketSize=BYTES'
3384
          The remote stub can accept packets up to at least BYTES in
3385
          length.  GDB will send packets up to this size for bulk
3386
          transfers, and will never send larger packets.  This is a
3387
          limit on the data characters in the packet, including the
3388
          frame and checksum.  There is no trailing NUL byte in a
3389
          remote protocol packet; if the stub stores packets in a
3390
          NUL-terminated format, it should allow an extra byte in its
3391
          buffer for the NUL.  If this stub feature is not supported,
3392
          GDB guesses based on the size of the `g' packet response.
3393
 
3394
    `qXfer:auxv:read'
3395
          The remote stub understands the `qXfer:auxv:read' packet
3396
          (*note qXfer auxiliary vector read::).
3397
 
3398
    `qXfer:features:read'
3399
          The remote stub understands the `qXfer:features:read' packet
3400
          (*note qXfer target description read::).
3401
 
3402
    `qXfer:libraries:read'
3403
          The remote stub understands the `qXfer:libraries:read' packet
3404
          (*note qXfer library list read::).
3405
 
3406
    `qXfer:memory-map:read'
3407
          The remote stub understands the `qXfer:memory-map:read' packet
3408
          (*note qXfer memory map read::).
3409
 
3410
    `qXfer:spu:read'
3411
          The remote stub understands the `qXfer:spu:read' packet
3412
          (*note qXfer spu read::).
3413
 
3414
    `qXfer:spu:write'
3415
          The remote stub understands the `qXfer:spu:write' packet
3416
          (*note qXfer spu write::).
3417
 
3418
    `qXfer:siginfo:read'
3419
          The remote stub understands the `qXfer:siginfo:read' packet
3420
          (*note qXfer siginfo read::).
3421
 
3422
    `qXfer:siginfo:write'
3423
          The remote stub understands the `qXfer:siginfo:write' packet
3424
          (*note qXfer siginfo write::).
3425
 
3426
    `qXfer:threads:read'
3427
          The remote stub understands the `qXfer:threads:read' packet
3428
          (*note qXfer threads read::).
3429
 
3430
    `QNonStop'
3431
          The remote stub understands the `QNonStop' packet (*note
3432
          QNonStop::).
3433
 
3434
    `QPassSignals'
3435
          The remote stub understands the `QPassSignals' packet (*note
3436
          QPassSignals::).
3437
 
3438
    `QStartNoAckMode'
3439
          The remote stub understands the `QStartNoAckMode' packet and
3440
          prefers to operate in no-acknowledgment mode.  *Note Packet
3441
          Acknowledgment::.
3442
 
3443
    `multiprocess'
3444
          The remote stub understands the multiprocess extensions to
3445
          the remote protocol syntax.  The multiprocess extensions
3446
          affect the syntax of thread IDs in both packets and replies
3447
          (*note thread-id syntax::), and add process IDs to the `D'
3448
          packet and `W' and `X' replies.  Note that reporting this
3449
          feature indicates support for the syntactic extensions only,
3450
          not that the stub necessarily supports debugging of more than
3451
          one process at a time.  The stub must not use multiprocess
3452
          extensions in packet replies unless GDB has also indicated it
3453
          supports them in its `qSupported' request.
3454
 
3455
    `qXfer:osdata:read'
3456
          The remote stub understands the `qXfer:osdata:read' packet
3457
          ((*note qXfer osdata read::).
3458
 
3459
    `ConditionalTracepoints'
3460
          The remote stub accepts and implements conditional
3461
          expressions defined for tracepoints (*note Tracepoint
3462
          Conditions::).
3463
 
3464
    `ReverseContinue'
3465
          The remote stub accepts and implements the reverse continue
3466
          packet (*note bc::).
3467
 
3468
    `ReverseStep'
3469
          The remote stub accepts and implements the reverse step packet
3470
          (*note bs::).
3471
 
3472
 
3473
`qSymbol::'
3474
     Notify the target that GDB is prepared to serve symbol lookup
3475
     requests.  Accept requests from the target for the values of
3476
     symbols.
3477
 
3478
     Reply:
3479
    `OK'
3480
          The target does not need to look up any (more) symbols.
3481
 
3482
    `qSymbol:SYM_NAME'
3483
          The target requests the value of symbol SYM_NAME (hex
3484
          encoded).  GDB may provide the value by using the
3485
          `qSymbol:SYM_VALUE:SYM_NAME' message, described below.
3486
 
3487
`qSymbol:SYM_VALUE:SYM_NAME'
3488
     Set the value of SYM_NAME to SYM_VALUE.
3489
 
3490
     SYM_NAME (hex encoded) is the name of a symbol whose value the
3491
     target has previously requested.
3492
 
3493
     SYM_VALUE (hex) is the value for symbol SYM_NAME.  If GDB cannot
3494
     supply a value for SYM_NAME, then this field will be empty.
3495
 
3496
     Reply:
3497
    `OK'
3498
          The target does not need to look up any (more) symbols.
3499
 
3500
    `qSymbol:SYM_NAME'
3501
          The target requests the value of a new symbol SYM_NAME (hex
3502
          encoded).  GDB will continue to supply the values of symbols
3503
          (if available), until the target ceases to request them.
3504
 
3505
`qTBuffer'
3506
 
3507
`QTDisconnected'
3508
`QTDP'
3509
`QTDV'
3510
`qTfP'
3511
`qTfV'
3512
`QTFrame'
3513
     *Note Tracepoint Packets::.
3514
 
3515
`qThreadExtraInfo,THREAD-ID'
3516
     Obtain a printable string description of a thread's attributes from
3517
     the target OS.  THREAD-ID is a thread ID; see *Note thread-id
3518
     syntax::.  This string may contain anything that the target OS
3519
     thinks is interesting for GDB to tell the user about the thread.
3520
     The string is displayed in GDB's `info threads' display.  Some
3521
     examples of possible thread extra info strings are `Runnable', or
3522
     `Blocked on Mutex'.
3523
 
3524
     Reply:
3525
    `XX...'
3526
          Where `XX...' is a hex encoding of ASCII data, comprising the
3527
          printable string containing the extra information about the
3528
          thread's attributes.
3529
 
3530
     (Note that the `qThreadExtraInfo' packet's name is separated from
3531
     the command by a `,', not a `:', contrary to the naming
3532
     conventions above.  Please don't use this packet as a model for new
3533
     packets.)
3534
 
3535
`QTSave'
3536
 
3537
`qTsP'
3538
 
3539
`qTsV'
3540
`QTStart'
3541
`QTStop'
3542
`QTinit'
3543
`QTro'
3544
`qTStatus'
3545
`qTV'
3546
     *Note Tracepoint Packets::.
3547
 
3548
`qXfer:OBJECT:read:ANNEX:OFFSET,LENGTH'
3549
     Read uninterpreted bytes from the target's special data area
3550
     identified by the keyword OBJECT.  Request LENGTH bytes starting
3551
     at OFFSET bytes into the data.  The content and encoding of ANNEX
3552
     is specific to OBJECT; it can supply additional details about what
3553
     data to access.
3554
 
3555
     Here are the specific requests of this form defined so far.  All
3556
     `qXfer:OBJECT:read:...' requests use the same reply formats,
3557
     listed below.
3558
 
3559
    `qXfer:auxv:read::OFFSET,LENGTH'
3560
          Access the target's "auxiliary vector".  *Note auxiliary
3561
          vector: OS Information.  Note ANNEX must be empty.
3562
 
3563
          This packet is not probed by default; the remote stub must
3564
          request it, by supplying an appropriate `qSupported' response
3565
          (*note qSupported::).
3566
 
3567
    `qXfer:features:read:ANNEX:OFFSET,LENGTH'
3568
          Access the "target description".  *Note Target
3569
          Descriptions::.  The annex specifies which XML document to
3570
          access.  The main description is always loaded from the
3571
          `target.xml' annex.
3572
 
3573
          This packet is not probed by default; the remote stub must
3574
          request it, by supplying an appropriate `qSupported' response
3575
          (*note qSupported::).
3576
 
3577
    `qXfer:libraries:read:ANNEX:OFFSET,LENGTH'
3578
          Access the target's list of loaded libraries.  *Note Library
3579
          List Format::.  The annex part of the generic `qXfer' packet
3580
          must be empty (*note qXfer read::).
3581
 
3582
          Targets which maintain a list of libraries in the program's
3583
          memory do not need to implement this packet; it is designed
3584
          for platforms where the operating system manages the list of
3585
          loaded libraries.
3586
 
3587
          This packet is not probed by default; the remote stub must
3588
          request it, by supplying an appropriate `qSupported' response
3589
          (*note qSupported::).
3590
 
3591
    `qXfer:memory-map:read::OFFSET,LENGTH'
3592
          Access the target's "memory-map".  *Note Memory Map Format::.
3593
          The annex part of the generic `qXfer' packet must be empty
3594
          (*note qXfer read::).
3595
 
3596
          This packet is not probed by default; the remote stub must
3597
          request it, by supplying an appropriate `qSupported' response
3598
          (*note qSupported::).
3599
 
3600
    `qXfer:siginfo:read::OFFSET,LENGTH'
3601
          Read contents of the extra signal information on the target
3602
          system.  The annex part of the generic `qXfer' packet must be
3603
          empty (*note qXfer read::).
3604
 
3605
          This packet is not probed by default; the remote stub must
3606
          request it, by supplying an appropriate `qSupported' response
3607
          (*note qSupported::).
3608
 
3609
    `qXfer:spu:read:ANNEX:OFFSET,LENGTH'
3610
          Read contents of an `spufs' file on the target system.  The
3611
          annex specifies which file to read; it must be of the form
3612
          `ID/NAME', where ID specifies an SPU context ID in the target
3613
          process, and NAME identifes the `spufs' file in that context
3614
          to be accessed.
3615
 
3616
          This packet is not probed by default; the remote stub must
3617
          request it, by supplying an appropriate `qSupported' response
3618
          (*note qSupported::).
3619
 
3620
    `qXfer:threads:read::OFFSET,LENGTH'
3621
          Access the list of threads on target.  *Note Thread List
3622
          Format::.  The annex part of the generic `qXfer' packet must
3623
          be empty (*note qXfer read::).
3624
 
3625
          This packet is not probed by default; the remote stub must
3626
          request it, by supplying an appropriate `qSupported' response
3627
          (*note qSupported::).
3628
 
3629
    `qXfer:osdata:read::OFFSET,LENGTH'
3630
          Access the target's "operating system information".  *Note
3631
          Operating System Information::.
3632
 
3633
 
3634
     Reply:
3635
    `m DATA'
3636
          Data DATA (*note Binary Data::) has been read from the
3637
          target.  There may be more data at a higher address (although
3638
          it is permitted to return `m' even for the last valid block
3639
          of data, as long as at least one byte of data was read).
3640
          DATA may have fewer bytes than the LENGTH in the request.
3641
 
3642
    `l DATA'
3643
          Data DATA (*note Binary Data::) has been read from the target.
3644
          There is no more data to be read.  DATA may have fewer bytes
3645
          than the LENGTH in the request.
3646
 
3647
    `l'
3648
          The OFFSET in the request is at the end of the data.  There
3649
          is no more data to be read.
3650
 
3651
    `E00'
3652
          The request was malformed, or ANNEX was invalid.
3653
 
3654
    `E NN'
3655
          The offset was invalid, or there was an error encountered
3656
          reading the data.  NN is a hex-encoded `errno' value.
3657
 
3658
    `'
3659
          An empty reply indicates the OBJECT string was not recognized
3660
          by the stub, or that the object does not support reading.
3661
 
3662
`qXfer:OBJECT:write:ANNEX:OFFSET:DATA...'
3663
     Write uninterpreted bytes into the target's special data area
3664
     identified by the keyword OBJECT, starting at OFFSET bytes into
3665
     the data.  DATA... is the binary-encoded data (*note Binary
3666
     Data::) to be written.  The content and encoding of ANNEX is
3667
     specific to OBJECT; it can supply additional details about what
3668
     data to access.
3669
 
3670
     Here are the specific requests of this form defined so far.  All
3671
     `qXfer:OBJECT:write:...' requests use the same reply formats,
3672
     listed below.
3673
 
3674
    `qXfer:siginfo:write::OFFSET:DATA...'
3675
          Write DATA to the extra signal information on the target
3676
          system.  The annex part of the generic `qXfer' packet must be
3677
          empty (*note qXfer write::).
3678
 
3679
          This packet is not probed by default; the remote stub must
3680
          request it, by supplying an appropriate `qSupported' response
3681
          (*note qSupported::).
3682
 
3683
    `qXfer:spu:write:ANNEX:OFFSET:DATA...'
3684
          Write DATA to an `spufs' file on the target system.  The
3685
          annex specifies which file to write; it must be of the form
3686
          `ID/NAME', where ID specifies an SPU context ID in the target
3687
          process, and NAME identifes the `spufs' file in that context
3688
          to be accessed.
3689
 
3690
          This packet is not probed by default; the remote stub must
3691
          request it, by supplying an appropriate `qSupported' response
3692
          (*note qSupported::).
3693
 
3694
     Reply:
3695
    `NN'
3696
          NN (hex encoded) is the number of bytes written.  This may be
3697
          fewer bytes than supplied in the request.
3698
 
3699
    `E00'
3700
          The request was malformed, or ANNEX was invalid.
3701
 
3702
    `E NN'
3703
          The offset was invalid, or there was an error encountered
3704
          writing the data.  NN is a hex-encoded `errno' value.
3705
 
3706
    `'
3707
          An empty reply indicates the OBJECT string was not recognized
3708
          by the stub, or that the object does not support writing.
3709
 
3710
`qXfer:OBJECT:OPERATION:...'
3711
     Requests of this form may be added in the future.  When a stub does
3712
     not recognize the OBJECT keyword, or its support for OBJECT does
3713
     not recognize the OPERATION keyword, the stub must respond with an
3714
     empty packet.
3715
 
3716
`qAttached:PID'
3717
     Return an indication of whether the remote server attached to an
3718
     existing process or created a new process.  When the multiprocess
3719
     protocol extensions are supported (*note multiprocess
3720
     extensions::), PID is an integer in hexadecimal format identifying
3721
     the target process.  Otherwise, GDB will omit the PID field and
3722
     the query packet will be simplified as `qAttached'.
3723
 
3724
     This query is used, for example, to know whether the remote process
3725
     should be detached or killed when a GDB session is ended with the
3726
     `quit' command.
3727
 
3728
     Reply:
3729
    `1'
3730
          The remote server attached to an existing process.
3731
 
3732
    `0'
3733
          The remote server created a new process.
3734
 
3735
    `E NN'
3736
          A badly formed request or an error was encountered.
3737
 
3738
 
3739
   ---------- Footnotes ----------
3740
 
3741
   (1) The `qP' and `qL' packets predate these conventions, and have
3742
arguments without any terminator for the packet name; we suspect they
3743
are in widespread use in places that are difficult to upgrade.  The
3744
`qC' packet has no arguments, but some existing stubs (e.g. RedBoot)
3745
are known to not check for the end of the packet.
3746
 
3747

3748
File: gdb.info,  Node: Architecture-Specific Protocol Details,  Next: Tracepoint Packets,  Prev: General Query Packets,  Up: Remote Protocol
3749
 
3750
D.5 Architecture-Specific Protocol Details
3751
==========================================
3752
 
3753
This section describes how the remote protocol is applied to specific
3754
target architectures.  Also see *Note Standard Target Features::, for
3755
details of XML target descriptions for each architecture.
3756
 
3757
D.5.1 ARM
3758
---------
3759
 
3760
D.5.1.1 Breakpoint Kinds
3761
........................
3762
 
3763
These breakpoint kinds are defined for the `Z0' and `Z1' packets.
3764
 
3765
2
3766
     16-bit Thumb mode breakpoint.
3767
 
3768
3
3769
     32-bit Thumb mode (Thumb-2) breakpoint.
3770
 
3771
4
3772
     32-bit ARM mode breakpoint.
3773
 
3774
 
3775
D.5.2 MIPS
3776
----------
3777
 
3778
D.5.2.1 Register Packet Format
3779
..............................
3780
 
3781
The following `g'/`G' packets have previously been defined.  In the
3782
below, some thirty-two bit registers are transferred as sixty-four
3783
bits.  Those registers should be zero/sign extended (which?)  to fill
3784
the space allocated.  Register bytes are transferred in target byte
3785
order.  The two nibbles within a register byte are transferred
3786
most-significant - least-significant.
3787
 
3788
MIPS32
3789
     All registers are transferred as thirty-two bit quantities in the
3790
     order: 32 general-purpose; sr; lo; hi; bad; cause; pc; 32
3791
     floating-point registers; fsr; fir; fp.
3792
 
3793
MIPS64
3794
     All registers are transferred as sixty-four bit quantities
3795
     (including thirty-two bit registers such as `sr').  The ordering
3796
     is the same as `MIPS32'.
3797
 
3798
 
3799

3800
File: gdb.info,  Node: Tracepoint Packets,  Next: Host I/O Packets,  Prev: Architecture-Specific Protocol Details,  Up: Remote Protocol
3801
 
3802
D.6 Tracepoint Packets
3803
======================
3804
 
3805
Here we describe the packets GDB uses to implement tracepoints (*note
3806
Tracepoints::).
3807
 
3808
`QTDP:N:ADDR:ENA:STEP:PASS[:FFLEN][:XLEN,BYTES][-]'
3809
     Create a new tracepoint, number N, at ADDR.  If ENA is `E', then
3810
     the tracepoint is enabled; if it is `D', then the tracepoint is
3811
     disabled.  STEP is the tracepoint's step count, and PASS is its
3812
     pass count.  If an `F' is present, then the tracepoint is to be a
3813
     fast tracepoint, and the FLEN is the number of bytes that the
3814
     target should copy elsewhere to make room for the tracepoint.  If
3815
     an `X' is present, it introduces a tracepoint condition, which
3816
     consists of a hexadecimal length, followed by a comma and
3817
     hex-encoded bytes, in a manner similar to action encodings as
3818
     described below.  If the trailing `-' is present, further `QTDP'
3819
     packets will follow to specify this tracepoint's actions.
3820
 
3821
     Replies:
3822
    `OK'
3823
          The packet was understood and carried out.
3824
 
3825
    `'
3826
          The packet was not recognized.
3827
 
3828
`QTDP:-N:ADDR:[S]ACTION...[-]'
3829
     Define actions to be taken when a tracepoint is hit.  N and ADDR
3830
     must be the same as in the initial `QTDP' packet for this
3831
     tracepoint.  This packet may only be sent immediately after
3832
     another `QTDP' packet that ended with a `-'.  If the trailing `-'
3833
     is present, further `QTDP' packets will follow, specifying more
3834
     actions for this tracepoint.
3835
 
3836
     In the series of action packets for a given tracepoint, at most one
3837
     can have an `S' before its first ACTION.  If such a packet is
3838
     sent, it and the following packets define "while-stepping"
3839
     actions.  Any prior packets define ordinary actions -- that is,
3840
     those taken when the tracepoint is first hit.  If no action packet
3841
     has an `S', then all the packets in the series specify ordinary
3842
     tracepoint actions.
3843
 
3844
     The `ACTION...' portion of the packet is a series of actions,
3845
     concatenated without separators.  Each action has one of the
3846
     following forms:
3847
 
3848
    `R MASK'
3849
          Collect the registers whose bits are set in MASK.  MASK is a
3850
          hexadecimal number whose I'th bit is set if register number I
3851
          should be collected.  (The least significant bit is numbered
3852
          zero.)  Note that MASK may be any number of digits long; it
3853
          may not fit in a 32-bit word.
3854
 
3855
    `M BASEREG,OFFSET,LEN'
3856
          Collect LEN bytes of memory starting at the address in
3857
          register number BASEREG, plus OFFSET.  If BASEREG is `-1',
3858
          then the range has a fixed address: OFFSET is the address of
3859
          the lowest byte to collect.  The BASEREG, OFFSET, and LEN
3860
          parameters are all unsigned hexadecimal values (the `-1'
3861
          value for BASEREG is a special case).
3862
 
3863
    `X LEN,EXPR'
3864
          Evaluate EXPR, whose length is LEN, and collect memory as it
3865
          directs.  EXPR is an agent expression, as described in *Note
3866
          Agent Expressions::.  Each byte of the expression is encoded
3867
          as a two-digit hex number in the packet; LEN is the number of
3868
          bytes in the expression (and thus one-half the number of hex
3869
          digits in the packet).
3870
 
3871
 
3872
     Any number of actions may be packed together in a single `QTDP'
3873
     packet, as long as the packet does not exceed the maximum packet
3874
     length (400 bytes, for many stubs).  There may be only one `R'
3875
     action per tracepoint, and it must precede any `M' or `X' actions.
3876
     Any registers referred to by `M' and `X' actions must be
3877
     collected by a preceding `R' action.  (The "while-stepping"
3878
     actions are treated as if they were attached to a separate
3879
     tracepoint, as far as these restrictions are concerned.)
3880
 
3881
     Replies:
3882
    `OK'
3883
          The packet was understood and carried out.
3884
 
3885
    `'
3886
          The packet was not recognized.
3887
 
3888
`QTDV:N:VALUE'
3889
     Create a new trace state variable, number N, with an initial value
3890
     of VALUE, which is a 64-bit signed integer.  Both N and VALUE are
3891
     encoded as hexadecimal values. GDB has the option of not using
3892
     this packet for initial values of zero; the target should simply
3893
     create the trace state variables as they are mentioned in
3894
     expressions.
3895
 
3896
`QTFrame:N'
3897
     Select the N'th tracepoint frame from the buffer, and use the
3898
     register and memory contents recorded there to answer subsequent
3899
     request packets from GDB.
3900
 
3901
     A successful reply from the stub indicates that the stub has found
3902
     the requested frame.  The response is a series of parts,
3903
     concatenated without separators, describing the frame we selected.
3904
     Each part has one of the following forms:
3905
 
3906
    `F F'
3907
          The selected frame is number N in the trace frame buffer; F
3908
          is a hexadecimal number.  If F is `-1', then there was no
3909
          frame matching the criteria in the request packet.
3910
 
3911
    `T T'
3912
          The selected trace frame records a hit of tracepoint number T;
3913
          T is a hexadecimal number.
3914
 
3915
 
3916
`QTFrame:pc:ADDR'
3917
     Like `QTFrame:N', but select the first tracepoint frame after the
3918
     currently selected frame whose PC is ADDR; ADDR is a hexadecimal
3919
     number.
3920
 
3921
`QTFrame:tdp:T'
3922
     Like `QTFrame:N', but select the first tracepoint frame after the
3923
     currently selected frame that is a hit of tracepoint T; T is a
3924
     hexadecimal number.
3925
 
3926
`QTFrame:range:START:END'
3927
     Like `QTFrame:N', but select the first tracepoint frame after the
3928
     currently selected frame whose PC is between START (inclusive) and
3929
     END (inclusive); START and END are hexadecimal numbers.
3930
 
3931
`QTFrame:outside:START:END'
3932
     Like `QTFrame:range:START:END', but select the first frame
3933
     _outside_ the given range of addresses (exclusive).
3934
 
3935
`QTStart'
3936
     Begin the tracepoint experiment.  Begin collecting data from
3937
     tracepoint hits in the trace frame buffer.
3938
 
3939
`QTStop'
3940
     End the tracepoint experiment.  Stop collecting trace frames.
3941
 
3942
`QTinit'
3943
     Clear the table of tracepoints, and empty the trace frame buffer.
3944
 
3945
`QTro:START1,END1:START2,END2:...'
3946
     Establish the given ranges of memory as "transparent".  The stub
3947
     will answer requests for these ranges from memory's current
3948
     contents, if they were not collected as part of the tracepoint hit.
3949
 
3950
     GDB uses this to mark read-only regions of memory, like those
3951
     containing program code.  Since these areas never change, they
3952
     should still have the same contents they did when the tracepoint
3953
     was hit, so there's no reason for the stub to refuse to provide
3954
     their contents.
3955
 
3956
`QTDisconnected:VALUE'
3957
     Set the choice to what to do with the tracing run when GDB
3958
     disconnects from the target.  A VALUE of 1 directs the target to
3959
     continue the tracing run, while 0 tells the target to stop tracing
3960
     if GDB is no longer in the picture.
3961
 
3962
`qTStatus'
3963
     Ask the stub if there is a trace experiment running right now.
3964
 
3965
     Replies:
3966
    `T0'
3967
          There is no trace experiment running.
3968
 
3969
    `T1'
3970
          There is a trace experiment running.
3971
 
3972
`qTV:VAR'
3973
     Ask the stub for the value of the trace state variable number VAR.
3974
 
3975
     Replies:
3976
    `VVALUE'
3977
          The value of the variable is VALUE.  This will be the current
3978
          value of the variable if the user is examining a running
3979
          target, or a saved value if the variable was collected in the
3980
          trace frame that the user is looking at.  Note that multiple
3981
          requests may result in different reply values, such as when
3982
          requesting values while the program is running.
3983
 
3984
    `U'
3985
          The value of the variable is unknown.  This would occur, for
3986
          example, if the user is examining a trace frame in which the
3987
          requested variable was not collected.
3988
 
3989
`qTfP'
3990
`qTsP'
3991
     These packets request data about tracepoints that are being used by
3992
     the target.  GDB sends `qTfP' to get the first piece of data, and
3993
     multiple `qTsP' to get additional pieces.  Replies to these
3994
     packets generally take the form of the `QTDP' packets that define
3995
     tracepoints. (FIXME add detailed syntax)
3996
 
3997
`qTfV'
3998
`qTsV'
3999
     These packets request data about trace state variables that are on
4000
     the target.  GDB sends `qTfV' to get the first vari of data, and
4001
     multiple `qTsV' to get additional variables.  Replies to these
4002
     packets follow the syntax of the `QTDV' packets that define trace
4003
     state variables.
4004
 
4005
`QTSave:FILENAME'
4006
     This packet directs the target to save trace data to the file name
4007
     FILENAME in the target's filesystem.  FILENAME is encoded as a hex
4008
     string; the interpretation of the file name (relative vs absolute,
4009
     wild cards, etc) is up to the target.
4010
 
4011
`qTBuffer:OFFSET,LEN'
4012
     Return up to LEN bytes of the current contents of trace buffer,
4013
     starting at OFFSET.  The trace buffer is treated as if it were a
4014
     contiguous collection of traceframes, as per the trace file format.
4015
     The reply consists as many hex-encoded bytes as the target can
4016
     deliver in a packet; it is not an error to return fewer than were
4017
     asked for.  A reply consisting of just `l' indicates that no bytes
4018
     are available.
4019
 
4020
 
4021

4022
File: gdb.info,  Node: Host I/O Packets,  Next: Interrupts,  Prev: Tracepoint Packets,  Up: Remote Protocol
4023
 
4024
D.7 Host I/O Packets
4025
====================
4026
 
4027
The "Host I/O" packets allow GDB to perform I/O operations on the far
4028
side of a remote link.  For example, Host I/O is used to upload and
4029
download files to a remote target with its own filesystem.  Host I/O
4030
uses the same constant values and data structure layout as the
4031
target-initiated File-I/O protocol.  However, the Host I/O packets are
4032
structured differently.  The target-initiated protocol relies on target
4033
memory to store parameters and buffers.  Host I/O requests are
4034
initiated by GDB, and the target's memory is not involved.  *Note
4035
File-I/O Remote Protocol Extension::, for more details on the
4036
target-initiated protocol.
4037
 
4038
   The Host I/O request packets all encode a single operation along with
4039
its arguments.  They have this format:
4040
 
4041
`vFile:OPERATION: PARAMETER...'
4042
     OPERATION is the name of the particular request; the target should
4043
     compare the entire packet name up to the second colon when checking
4044
     for a supported operation.  The format of PARAMETER depends on the
4045
     operation.  Numbers are always passed in hexadecimal.  Negative
4046
     numbers have an explicit minus sign (i.e. two's complement is not
4047
     used).  Strings (e.g. filenames) are encoded as a series of
4048
     hexadecimal bytes.  The last argument to a system call may be a
4049
     buffer of escaped binary data (*note Binary Data::).
4050
 
4051
 
4052
   The valid responses to Host I/O packets are:
4053
 
4054
`F RESULT [, ERRNO] [; ATTACHMENT]'
4055
     RESULT is the integer value returned by this operation, usually
4056
     non-negative for success and -1 for errors.  If an error has
4057
     occured, ERRNO will be included in the result.  ERRNO will have a
4058
     value defined by the File-I/O protocol (*note Errno Values::).  For
4059
     operations which return data, ATTACHMENT supplies the data as a
4060
     binary buffer.  Binary buffers in response packets are escaped in
4061
     the normal way (*note Binary Data::).  See the individual packet
4062
     documentation for the interpretation of RESULT and ATTACHMENT.
4063
 
4064
`'
4065
     An empty response indicates that this operation is not recognized.
4066
 
4067
 
4068
   These are the supported Host I/O operations:
4069
 
4070
`vFile:open: PATHNAME, FLAGS, MODE'
4071
     Open a file at PATHNAME and return a file descriptor for it, or
4072
     return -1 if an error occurs.  PATHNAME is a string, FLAGS is an
4073
     integer indicating a mask of open flags (*note Open Flags::), and
4074
     MODE is an integer indicating a mask of mode bits to use if the
4075
     file is created (*note mode_t Values::).  *Note open::, for
4076
     details of the open flags and mode values.
4077
 
4078
`vFile:close: FD'
4079
     Close the open file corresponding to FD and return 0, or -1 if an
4080
     error occurs.
4081
 
4082
`vFile:pread: FD, COUNT, OFFSET'
4083
     Read data from the open file corresponding to FD.  Up to COUNT
4084
     bytes will be read from the file, starting at OFFSET relative to
4085
     the start of the file.  The target may read fewer bytes; common
4086
     reasons include packet size limits and an end-of-file condition.
4087
     The number of bytes read is returned.  Zero should only be
4088
     returned for a successful read at the end of the file, or if COUNT
4089
     was zero.
4090
 
4091
     The data read should be returned as a binary attachment on success.
4092
     If zero bytes were read, the response should include an empty
4093
     binary attachment (i.e. a trailing semicolon).  The return value
4094
     is the number of target bytes read; the binary attachment may be
4095
     longer if some characters were escaped.
4096
 
4097
`vFile:pwrite: FD, OFFSET, DATA'
4098
     Write DATA (a binary buffer) to the open file corresponding to FD.
4099
     Start the write at OFFSET from the start of the file.  Unlike
4100
     many `write' system calls, there is no separate COUNT argument;
4101
     the length of DATA in the packet is used.  `vFile:write' returns
4102
     the number of bytes written, which may be shorter than the length
4103
     of DATA, or -1 if an error occurred.
4104
 
4105
`vFile:unlink: PATHNAME'
4106
     Delete the file at PATHNAME on the target.  Return 0, or -1 if an
4107
     error occurs.  PATHNAME is a string.
4108
 
4109
 
4110

4111
File: gdb.info,  Node: Interrupts,  Next: Notification Packets,  Prev: Host I/O Packets,  Up: Remote Protocol
4112
 
4113
D.8 Interrupts
4114
==============
4115
 
4116
When a program on the remote target is running, GDB may attempt to
4117
interrupt it by sending a `Ctrl-C', `BREAK' or a `BREAK' followed by
4118
`g', control of which is specified via GDB's `interrupt-sequence'.
4119
 
4120
   The precise meaning of `BREAK' is defined by the transport mechanism
4121
and may, in fact, be undefined.  GDB does not currently define a
4122
`BREAK' mechanism for any of the network interfaces except for TCP, in
4123
which case GDB sends the `telnet' BREAK sequence.
4124
 
4125
   `Ctrl-C', on the other hand, is defined and implemented for all
4126
transport mechanisms.  It is represented by sending the single byte
4127
`0x03' without any of the usual packet overhead described in the
4128
Overview section (*note Overview::).  When a `0x03' byte is transmitted
4129
as part of a packet, it is considered to be packet data and does _not_
4130
represent an interrupt.  E.g., an `X' packet (*note X packet::), used
4131
for binary downloads, may include an unescaped `0x03' as part of its
4132
packet.
4133
 
4134
   `BREAK' followed by `g' is also known as Magic SysRq g.  When Linux
4135
kernel receives this sequence from serial port, it stops execution and
4136
connects to gdb.
4137
 
4138
   Stubs are not required to recognize these interrupt mechanisms and
4139
the precise meaning associated with receipt of the interrupt is
4140
implementation defined.  If the target supports debugging of multiple
4141
threads and/or processes, it should attempt to interrupt all
4142
currently-executing threads and processes.  If the stub is successful
4143
at interrupting the running program, it should send one of the stop
4144
reply packets (*note Stop Reply Packets::) to GDB as a result of
4145
successfully stopping the program in all-stop mode, and a stop reply
4146
for each stopped thread in non-stop mode.  Interrupts received while the
4147
program is stopped are discarded.
4148
 
4149

4150
File: gdb.info,  Node: Notification Packets,  Next: Remote Non-Stop,  Prev: Interrupts,  Up: Remote Protocol
4151
 
4152
D.9 Notification Packets
4153
========================
4154
 
4155
The GDB remote serial protocol includes "notifications", packets that
4156
require no acknowledgment.  Both the GDB and the stub may send
4157
notifications (although the only notifications defined at present are
4158
sent by the stub).  Notifications carry information without incurring
4159
the round-trip latency of an acknowledgment, and so are useful for
4160
low-impact communications where occasional packet loss is not a problem.
4161
 
4162
   A notification packet has the form `% DATA # CHECKSUM', where DATA
4163
is the content of the notification, and CHECKSUM is a checksum of DATA,
4164
computed and formatted as for ordinary GDB packets.  A notification's
4165
DATA never contains `$', `%' or `#' characters.  Upon receiving a
4166
notification, the recipient sends no `+' or `-' to acknowledge the
4167
notification's receipt or to report its corruption.
4168
 
4169
   Every notification's DATA begins with a name, which contains no
4170
colon characters, followed by a colon character.
4171
 
4172
   Recipients should silently ignore corrupted notifications and
4173
notifications they do not understand.  Recipients should restart
4174
timeout periods on receipt of a well-formed notification, whether or
4175
not they understand it.
4176
 
4177
   Senders should only send the notifications described here when this
4178
protocol description specifies that they are permitted.  In the future,
4179
we may extend the protocol to permit existing notifications in new
4180
contexts; this rule helps older senders avoid confusing newer
4181
recipients.
4182
 
4183
   (Older versions of GDB ignore bytes received until they see the `$'
4184
byte that begins an ordinary packet, so new stubs may transmit
4185
notifications without fear of confusing older clients.  There are no
4186
notifications defined for GDB to send at the moment, but we assume that
4187
most older stubs would ignore them, as well.)
4188
 
4189
   The following notification packets from the stub to GDB are defined:
4190
 
4191
`Stop: REPLY'
4192
     Report an asynchronous stop event in non-stop mode.  The REPLY has
4193
     the form of a stop reply, as described in *Note Stop Reply
4194
     Packets::.  Refer to *Note Remote Non-Stop::, for information on
4195
     how these notifications are acknowledged by GDB.
4196
 
4197

4198
File: gdb.info,  Node: Remote Non-Stop,  Next: Packet Acknowledgment,  Prev: Notification Packets,  Up: Remote Protocol
4199
 
4200
D.10 Remote Protocol Support for Non-Stop Mode
4201
==============================================
4202
 
4203
GDB's remote protocol supports non-stop debugging of multi-threaded
4204
programs, as described in *Note Non-Stop Mode::.  If the stub supports
4205
non-stop mode, it should report that to GDB by including `QNonStop+' in
4206
its `qSupported' response (*note qSupported::).
4207
 
4208
   GDB typically sends a `QNonStop' packet only when establishing a new
4209
connection with the stub.  Entering non-stop mode does not alter the
4210
state of any currently-running threads, but targets must stop all
4211
threads in any already-attached processes when entering all-stop mode.
4212
GDB uses the `?' packet as necessary to probe the target state after a
4213
mode change.
4214
 
4215
   In non-stop mode, when an attached process encounters an event that
4216
would otherwise be reported with a stop reply, it uses the asynchronous
4217
notification mechanism (*note Notification Packets::) to inform GDB.
4218
In contrast to all-stop mode, where all threads in all processes are
4219
stopped when a stop reply is sent, in non-stop mode only the thread
4220
reporting the stop event is stopped.  That is, when reporting a `S' or
4221
`T' response to indicate completion of a step operation, hitting a
4222
breakpoint, or a fault, only the affected thread is stopped; any other
4223
still-running threads continue to run.  When reporting a `W' or `X'
4224
response, all running threads belonging to other attached processes
4225
continue to run.
4226
 
4227
   Only one stop reply notification at a time may be pending; if
4228
additional stop events occur before GDB has acknowledged the previous
4229
notification, they must be queued by the stub for later synchronous
4230
transmission in response to `vStopped' packets from GDB.  Because the
4231
notification mechanism is unreliable, the stub is permitted to resend a
4232
stop reply notification if it believes GDB may not have received it.
4233
GDB ignores additional stop reply notifications received before it has
4234
finished processing a previous notification and the stub has completed
4235
sending any queued stop events.
4236
 
4237
   Otherwise, GDB must be prepared to receive a stop reply notification
4238
at any time.  Specifically, they may appear when GDB is not otherwise
4239
reading input from the stub, or when GDB is expecting to read a normal
4240
synchronous response or a `+'/`-' acknowledgment to a packet it has
4241
sent.  Notification packets are distinct from any other communication
4242
from the stub so there is no ambiguity.
4243
 
4244
   After receiving a stop reply notification, GDB shall acknowledge it
4245
by sending a `vStopped' packet (*note vStopped packet::) as a regular,
4246
synchronous request to the stub.  Such acknowledgment is not required
4247
to happen immediately, as GDB is permitted to send other, unrelated
4248
packets to the stub first, which the stub should process normally.
4249
 
4250
   Upon receiving a `vStopped' packet, if the stub has other queued
4251
stop events to report to GDB, it shall respond by sending a normal stop
4252
reply response.  GDB shall then send another `vStopped' packet to
4253
solicit further responses; again, it is permitted to send other,
4254
unrelated packets as well which the stub should process normally.
4255
 
4256
   If the stub receives a `vStopped' packet and there are no additional
4257
stop events to report, the stub shall return an `OK' response.  At this
4258
point, if further stop events occur, the stub shall send a new stop
4259
reply notification, GDB shall accept the notification, and the process
4260
shall be repeated.
4261
 
4262
   In non-stop mode, the target shall respond to the `?' packet as
4263
follows.  First, any incomplete stop reply notification/`vStopped'
4264
sequence in progress is abandoned.  The target must begin a new
4265
sequence reporting stop events for all stopped threads, whether or not
4266
it has previously reported those events to GDB.  The first stop reply
4267
is sent as a synchronous reply to the `?' packet, and subsequent stop
4268
replies are sent as responses to `vStopped' packets using the mechanism
4269
described above.  The target must not send asynchronous stop reply
4270
notifications until the sequence is complete.  If all threads are
4271
running when the target receives the `?' packet, or if the target is
4272
not attached to any process, it shall respond `OK'.
4273
 
4274

4275
File: gdb.info,  Node: Packet Acknowledgment,  Next: Examples,  Prev: Remote Non-Stop,  Up: Remote Protocol
4276
 
4277
D.11 Packet Acknowledgment
4278
==========================
4279
 
4280
By default, when either the host or the target machine receives a
4281
packet, the first response expected is an acknowledgment: either `+'
4282
(to indicate the package was received correctly) or `-' (to request
4283
retransmission).  This mechanism allows the GDB remote protocol to
4284
operate over unreliable transport mechanisms, such as a serial line.
4285
 
4286
   In cases where the transport mechanism is itself reliable (such as a
4287
pipe or TCP connection), the `+'/`-' acknowledgments are redundant.  It
4288
may be desirable to disable them in that case to reduce communication
4289
overhead, or for other reasons.  This can be accomplished by means of
4290
the `QStartNoAckMode' packet; *note QStartNoAckMode::.
4291
 
4292
   When in no-acknowledgment mode, neither the stub nor GDB shall send
4293
or expect `+'/`-' protocol acknowledgments.  The packet and response
4294
format still includes the normal checksum, as described in *Note
4295
Overview::, but the checksum may be ignored by the receiver.
4296
 
4297
   If the stub supports `QStartNoAckMode' and prefers to operate in
4298
no-acknowledgment mode, it should report that to GDB by including
4299
`QStartNoAckMode+' in its response to `qSupported'; *note qSupported::.
4300
If GDB also supports `QStartNoAckMode' and it has not been disabled via
4301
the `set remote noack-packet off' command (*note Remote
4302
Configuration::), GDB may then send a `QStartNoAckMode' packet to the
4303
stub.  Only then may the stub actually turn off packet acknowledgments.
4304
GDB sends a final `+' acknowledgment of the stub's `OK' response, which
4305
can be safely ignored by the stub.
4306
 
4307
   Note that `set remote noack-packet' command only affects negotiation
4308
between GDB and the stub when subsequent connections are made; it does
4309
not affect the protocol acknowledgment state for any current connection.
4310
Since `+'/`-' acknowledgments are enabled by default when a new
4311
connection is established, there is also no protocol request to
4312
re-enable the acknowledgments for the current connection, once disabled.
4313
 
4314

4315
File: gdb.info,  Node: Examples,  Next: File-I/O Remote Protocol Extension,  Prev: Packet Acknowledgment,  Up: Remote Protocol
4316
 
4317
D.12 Examples
4318
=============
4319
 
4320
Example sequence of a target being re-started.  Notice how the restart
4321
does not get any direct output:
4322
 
4323
     -> `R00'
4324
     <- `+'
4325
     _target restarts_
4326
     -> `?'
4327
     <- `+'
4328
     <- `T001:1234123412341234'
4329
     -> `+'
4330
 
4331
   Example sequence of a target being stepped by a single instruction:
4332
 
4333
     -> `G1445...'
4334
     <- `+'
4335
     -> `s'
4336
     <- `+'
4337
     _time passes_
4338
     <- `T001:1234123412341234'
4339
     -> `+'
4340
     -> `g'
4341
     <- `+'
4342
     <- `1455...'
4343
     -> `+'
4344
 
4345

4346
File: gdb.info,  Node: File-I/O Remote Protocol Extension,  Next: Library List Format,  Prev: Examples,  Up: Remote Protocol
4347
 
4348
D.13 File-I/O Remote Protocol Extension
4349
=======================================
4350
 
4351
* Menu:
4352
 
4353
* File-I/O Overview::
4354
* Protocol Basics::
4355
* The F Request Packet::
4356
* The F Reply Packet::
4357
* The Ctrl-C Message::
4358
* Console I/O::
4359
* List of Supported Calls::
4360
* Protocol-specific Representation of Datatypes::
4361
* Constants::
4362
* File-I/O Examples::
4363
 
4364

4365
File: gdb.info,  Node: File-I/O Overview,  Next: Protocol Basics,  Up: File-I/O Remote Protocol Extension
4366
 
4367
D.13.1 File-I/O Overview
4368
------------------------
4369
 
4370
The "File I/O remote protocol extension" (short: File-I/O) allows the
4371
target to use the host's file system and console I/O to perform various
4372
system calls.  System calls on the target system are translated into a
4373
remote protocol packet to the host system, which then performs the
4374
needed actions and returns a response packet to the target system.
4375
This simulates file system operations even on targets that lack file
4376
systems.
4377
 
4378
   The protocol is defined to be independent of both the host and
4379
target systems.  It uses its own internal representation of datatypes
4380
and values.  Both GDB and the target's GDB stub are responsible for
4381
translating the system-dependent value representations into the internal
4382
protocol representations when data is transmitted.
4383
 
4384
   The communication is synchronous.  A system call is possible only
4385
when GDB is waiting for a response from the `C', `c', `S' or `s'
4386
packets.  While GDB handles the request for a system call, the target
4387
is stopped to allow deterministic access to the target's memory.
4388
Therefore File-I/O is not interruptible by target signals.  On the
4389
other hand, it is possible to interrupt File-I/O by a user interrupt
4390
(`Ctrl-C') within GDB.
4391
 
4392
   The target's request to perform a host system call does not finish
4393
the latest `C', `c', `S' or `s' action.  That means, after finishing
4394
the system call, the target returns to continuing the previous activity
4395
(continue, step).  No additional continue or step request from GDB is
4396
required.
4397
 
4398
     (gdb) continue
4399
       <- target requests 'system call X'
4400
       target is stopped, GDB executes system call
4401
       -> GDB returns result
4402
       ... target continues, GDB returns to wait for the target
4403
       <- target hits breakpoint and sends a Txx packet
4404
 
4405
   The protocol only supports I/O on the console and to regular files on
4406
the host file system.  Character or block special devices, pipes, named
4407
pipes, sockets or any other communication method on the host system are
4408
not supported by this protocol.
4409
 
4410
   File I/O is not supported in non-stop mode.
4411
 
4412

4413
File: gdb.info,  Node: Protocol Basics,  Next: The F Request Packet,  Prev: File-I/O Overview,  Up: File-I/O Remote Protocol Extension
4414
 
4415
D.13.2 Protocol Basics
4416
----------------------
4417
 
4418
The File-I/O protocol uses the `F' packet as the request as well as
4419
reply packet.  Since a File-I/O system call can only occur when GDB is
4420
waiting for a response from the continuing or stepping target, the
4421
File-I/O request is a reply that GDB has to expect as a result of a
4422
previous `C', `c', `S' or `s' packet.  This `F' packet contains all
4423
information needed to allow GDB to call the appropriate host system
4424
call:
4425
 
4426
   * A unique identifier for the requested system call.
4427
 
4428
   * All parameters to the system call.  Pointers are given as addresses
4429
     in the target memory address space.  Pointers to strings are given
4430
     as pointer/length pair.  Numerical values are given as they are.
4431
     Numerical control flags are given in a protocol-specific
4432
     representation.
4433
 
4434
 
4435
   At this point, GDB has to perform the following actions.
4436
 
4437
   * If the parameters include pointer values to data needed as input
4438
     to a system call, GDB requests this data from the target with a
4439
     standard `m' packet request.  This additional communication has to
4440
     be expected by the target implementation and is handled as any
4441
     other `m' packet.
4442
 
4443
   * GDB translates all value from protocol representation to host
4444
     representation as needed.  Datatypes are coerced into the host
4445
     types.
4446
 
4447
   * GDB calls the system call.
4448
 
4449
   * It then coerces datatypes back to protocol representation.
4450
 
4451
   * If the system call is expected to return data in buffer space
4452
     specified by pointer parameters to the call, the data is
4453
     transmitted to the target using a `M' or `X' packet.  This packet
4454
     has to be expected by the target implementation and is handled as
4455
     any other `M' or `X' packet.
4456
 
4457
 
4458
   Eventually GDB replies with another `F' packet which contains all
4459
necessary information for the target to continue.  This at least
4460
contains
4461
 
4462
   * Return value.
4463
 
4464
   * `errno', if has been changed by the system call.
4465
 
4466
   * "Ctrl-C" flag.
4467
 
4468
 
4469
   After having done the needed type and value coercion, the target
4470
continues the latest continue or step action.
4471
 
4472

4473
File: gdb.info,  Node: The F Request Packet,  Next: The F Reply Packet,  Prev: Protocol Basics,  Up: File-I/O Remote Protocol Extension
4474
 
4475
D.13.3 The `F' Request Packet
4476
-----------------------------
4477
 
4478
The `F' request packet has the following format:
4479
 
4480
`FCALL-ID,PARAMETER...'
4481
     CALL-ID is the identifier to indicate the host system call to be
4482
     called.  This is just the name of the function.
4483
 
4484
     PARAMETER... are the parameters to the system call.  Parameters
4485
     are hexadecimal integer values, either the actual values in case
4486
     of scalar datatypes, pointers to target buffer space in case of
4487
     compound datatypes and unspecified memory areas, or pointer/length
4488
     pairs in case of string parameters.  These are appended to the
4489
     CALL-ID as a comma-delimited list.  All values are transmitted in
4490
     ASCII string representation, pointer/length pairs separated by a
4491
     slash.
4492
 
4493
 
4494

4495
File: gdb.info,  Node: The F Reply Packet,  Next: The Ctrl-C Message,  Prev: The F Request Packet,  Up: File-I/O Remote Protocol Extension
4496
 
4497
D.13.4 The `F' Reply Packet
4498
---------------------------
4499
 
4500
The `F' reply packet has the following format:
4501
 
4502
`FRETCODE,ERRNO,CTRL-C FLAG;CALL-SPECIFIC ATTACHMENT'
4503
     RETCODE is the return code of the system call as hexadecimal value.
4504
 
4505
     ERRNO is the `errno' set by the call, in protocol-specific
4506
     representation.  This parameter can be omitted if the call was
4507
     successful.
4508
 
4509
     CTRL-C FLAG is only sent if the user requested a break.  In this
4510
     case, ERRNO must be sent as well, even if the call was successful.
4511
     The CTRL-C FLAG itself consists of the character `C':
4512
 
4513
          F0,0,C
4514
 
4515
     or, if the call was interrupted before the host call has been
4516
     performed:
4517
 
4518
          F-1,4,C
4519
 
4520
     assuming 4 is the protocol-specific representation of `EINTR'.
4521
 
4522
 
4523

4524
File: gdb.info,  Node: The Ctrl-C Message,  Next: Console I/O,  Prev: The F Reply Packet,  Up: File-I/O Remote Protocol Extension
4525
 
4526
D.13.5 The `Ctrl-C' Message
4527
---------------------------
4528
 
4529
If the `Ctrl-C' flag is set in the GDB reply packet (*note The F Reply
4530
Packet::), the target should behave as if it had gotten a break
4531
message.  The meaning for the target is "system call interrupted by
4532
`SIGINT'".  Consequentially, the target should actually stop (as with a
4533
break message) and return to GDB with a `T02' packet.
4534
 
4535
   It's important for the target to know in which state the system call
4536
was interrupted.  There are two possible cases:
4537
 
4538
   * The system call hasn't been performed on the host yet.
4539
 
4540
   * The system call on the host has been finished.
4541
 
4542
 
4543
   These two states can be distinguished by the target by the value of
4544
the returned `errno'.  If it's the protocol representation of `EINTR',
4545
the system call hasn't been performed.  This is equivalent to the
4546
`EINTR' handling on POSIX systems.  In any other case, the target may
4547
presume that the system call has been finished -- successfully or not
4548
-- and should behave as if the break message arrived right after the
4549
system call.
4550
 
4551
   GDB must behave reliably.  If the system call has not been called
4552
yet, GDB may send the `F' reply immediately, setting `EINTR' as `errno'
4553
in the packet.  If the system call on the host has been finished before
4554
the user requests a break, the full action must be finished by GDB.
4555
This requires sending `M' or `X' packets as necessary.  The `F' packet
4556
may only be sent when either nothing has happened or the full action
4557
has been completed.
4558
 
4559

4560
File: gdb.info,  Node: Console I/O,  Next: List of Supported Calls,  Prev: The Ctrl-C Message,  Up: File-I/O Remote Protocol Extension
4561
 
4562
D.13.6 Console I/O
4563
------------------
4564
 
4565
By default and if not explicitly closed by the target system, the file
4566
descriptors 0, 1 and 2 are connected to the GDB console.  Output on the
4567
GDB console is handled as any other file output operation (`write(1,
4568
...)' or `write(2, ...)').  Console input is handled by GDB so that
4569
after the target read request from file descriptor 0 all following
4570
typing is buffered until either one of the following conditions is met:
4571
 
4572
   * The user types `Ctrl-c'.  The behaviour is as explained above, and
4573
     the `read' system call is treated as finished.
4574
 
4575
   * The user presses .  This is treated as end of input with a
4576
     trailing newline.
4577
 
4578
   * The user types `Ctrl-d'.  This is treated as end of input.  No
4579
     trailing character (neither newline nor `Ctrl-D') is appended to
4580
     the input.
4581
 
4582
 
4583
   If the user has typed more characters than fit in the buffer given to
4584
the `read' call, the trailing characters are buffered in GDB until
4585
either another `read(0, ...)' is requested by the target, or debugging
4586
is stopped at the user's request.
4587
 
4588

4589
File: gdb.info,  Node: List of Supported Calls,  Next: Protocol-specific Representation of Datatypes,  Prev: Console I/O,  Up: File-I/O Remote Protocol Extension
4590
 
4591
D.13.7 List of Supported Calls
4592
------------------------------
4593
 
4594
* Menu:
4595
 
4596
* open::
4597
* close::
4598
* read::
4599
* write::
4600
* lseek::
4601
* rename::
4602
* unlink::
4603
* stat/fstat::
4604
* gettimeofday::
4605
* isatty::
4606
* system::
4607
 
4608

4609
File: gdb.info,  Node: open,  Next: close,  Up: List of Supported Calls
4610
 
4611
open
4612
....
4613
 
4614
Synopsis:
4615
          int open(const char *pathname, int flags);
4616
          int open(const char *pathname, int flags, mode_t mode);
4617
 
4618
Request:
4619
     `Fopen,PATHPTR/LEN,FLAGS,MODE'
4620
 
4621
     FLAGS is the bitwise `OR' of the following values:
4622
 
4623
    `O_CREAT'
4624
          If the file does not exist it will be created.  The host
4625
          rules apply as far as file ownership and time stamps are
4626
          concerned.
4627
 
4628
    `O_EXCL'
4629
          When used with `O_CREAT', if the file already exists it is an
4630
          error and open() fails.
4631
 
4632
    `O_TRUNC'
4633
          If the file already exists and the open mode allows writing
4634
          (`O_RDWR' or `O_WRONLY' is given) it will be truncated to
4635
          zero length.
4636
 
4637
    `O_APPEND'
4638
          The file is opened in append mode.
4639
 
4640
    `O_RDONLY'
4641
          The file is opened for reading only.
4642
 
4643
    `O_WRONLY'
4644
          The file is opened for writing only.
4645
 
4646
    `O_RDWR'
4647
          The file is opened for reading and writing.
4648
 
4649
     Other bits are silently ignored.
4650
 
4651
     MODE is the bitwise `OR' of the following values:
4652
 
4653
    `S_IRUSR'
4654
          User has read permission.
4655
 
4656
    `S_IWUSR'
4657
          User has write permission.
4658
 
4659
    `S_IRGRP'
4660
          Group has read permission.
4661
 
4662
    `S_IWGRP'
4663
          Group has write permission.
4664
 
4665
    `S_IROTH'
4666
          Others have read permission.
4667
 
4668
    `S_IWOTH'
4669
          Others have write permission.
4670
 
4671
     Other bits are silently ignored.
4672
 
4673
Return value:
4674
     `open' returns the new file descriptor or -1 if an error occurred.
4675
 
4676
Errors:
4677
 
4678
    `EEXIST'
4679
          PATHNAME already exists and `O_CREAT' and `O_EXCL' were used.
4680
 
4681
    `EISDIR'
4682
          PATHNAME refers to a directory.
4683
 
4684
    `EACCES'
4685
          The requested access is not allowed.
4686
 
4687
    `ENAMETOOLONG'
4688
          PATHNAME was too long.
4689
 
4690
    `ENOENT'
4691
          A directory component in PATHNAME does not exist.
4692
 
4693
    `ENODEV'
4694
          PATHNAME refers to a device, pipe, named pipe or socket.
4695
 
4696
    `EROFS'
4697
          PATHNAME refers to a file on a read-only filesystem and write
4698
          access was requested.
4699
 
4700
    `EFAULT'
4701
          PATHNAME is an invalid pointer value.
4702
 
4703
    `ENOSPC'
4704
          No space on device to create the file.
4705
 
4706
    `EMFILE'
4707
          The process already has the maximum number of files open.
4708
 
4709
    `ENFILE'
4710
          The limit on the total number of files open on the system has
4711
          been reached.
4712
 
4713
    `EINTR'
4714
          The call was interrupted by the user.
4715
 
4716
 
4717

4718
File: gdb.info,  Node: close,  Next: read,  Prev: open,  Up: List of Supported Calls
4719
 
4720
close
4721
.....
4722
 
4723
Synopsis:
4724
          int close(int fd);
4725
 
4726
Request:
4727
     `Fclose,FD'
4728
 
4729
Return value:
4730
     `close' returns zero on success, or -1 if an error occurred.
4731
 
4732
Errors:
4733
 
4734
    `EBADF'
4735
          FD isn't a valid open file descriptor.
4736
 
4737
    `EINTR'
4738
          The call was interrupted by the user.
4739
 
4740
 
4741

4742
File: gdb.info,  Node: read,  Next: write,  Prev: close,  Up: List of Supported Calls
4743
 
4744
read
4745
....
4746
 
4747
Synopsis:
4748
          int read(int fd, void *buf, unsigned int count);
4749
 
4750
Request:
4751
     `Fread,FD,BUFPTR,COUNT'
4752
 
4753
Return value:
4754
     On success, the number of bytes read is returned.  Zero indicates
4755
     end of file.  If count is zero, read returns zero as well.  On
4756
     error, -1 is returned.
4757
 
4758
Errors:
4759
 
4760
    `EBADF'
4761
          FD is not a valid file descriptor or is not open for reading.
4762
 
4763
    `EFAULT'
4764
          BUFPTR is an invalid pointer value.
4765
 
4766
    `EINTR'
4767
          The call was interrupted by the user.
4768
 
4769
 
4770

4771
File: gdb.info,  Node: write,  Next: lseek,  Prev: read,  Up: List of Supported Calls
4772
 
4773
write
4774
.....
4775
 
4776
Synopsis:
4777
          int write(int fd, const void *buf, unsigned int count);
4778
 
4779
Request:
4780
     `Fwrite,FD,BUFPTR,COUNT'
4781
 
4782
Return value:
4783
     On success, the number of bytes written are returned.  Zero
4784
     indicates nothing was written.  On error, -1 is returned.
4785
 
4786
Errors:
4787
 
4788
    `EBADF'
4789
          FD is not a valid file descriptor or is not open for writing.
4790
 
4791
    `EFAULT'
4792
          BUFPTR is an invalid pointer value.
4793
 
4794
    `EFBIG'
4795
          An attempt was made to write a file that exceeds the
4796
          host-specific maximum file size allowed.
4797
 
4798
    `ENOSPC'
4799
          No space on device to write the data.
4800
 
4801
    `EINTR'
4802
          The call was interrupted by the user.
4803
 
4804
 
4805

4806
File: gdb.info,  Node: lseek,  Next: rename,  Prev: write,  Up: List of Supported Calls
4807
 
4808
lseek
4809
.....
4810
 
4811
Synopsis:
4812
          long lseek (int fd, long offset, int flag);
4813
 
4814
Request:
4815
     `Flseek,FD,OFFSET,FLAG'
4816
 
4817
     FLAG is one of:
4818
 
4819
    `SEEK_SET'
4820
          The offset is set to OFFSET bytes.
4821
 
4822
    `SEEK_CUR'
4823
          The offset is set to its current location plus OFFSET bytes.
4824
 
4825
    `SEEK_END'
4826
          The offset is set to the size of the file plus OFFSET bytes.
4827
 
4828
Return value:
4829
     On success, the resulting unsigned offset in bytes from the
4830
     beginning of the file is returned.  Otherwise, a value of -1 is
4831
     returned.
4832
 
4833
Errors:
4834
 
4835
    `EBADF'
4836
          FD is not a valid open file descriptor.
4837
 
4838
    `ESPIPE'
4839
          FD is associated with the GDB console.
4840
 
4841
    `EINVAL'
4842
          FLAG is not a proper value.
4843
 
4844
    `EINTR'
4845
          The call was interrupted by the user.
4846
 
4847
 
4848

4849
File: gdb.info,  Node: rename,  Next: unlink,  Prev: lseek,  Up: List of Supported Calls
4850
 
4851
rename
4852
......
4853
 
4854
Synopsis:
4855
          int rename(const char *oldpath, const char *newpath);
4856
 
4857
Request:
4858
     `Frename,OLDPATHPTR/LEN,NEWPATHPTR/LEN'
4859
 
4860
Return value:
4861
     On success, zero is returned.  On error, -1 is returned.
4862
 
4863
Errors:
4864
 
4865
    `EISDIR'
4866
          NEWPATH is an existing directory, but OLDPATH is not a
4867
          directory.
4868
 
4869
    `EEXIST'
4870
          NEWPATH is a non-empty directory.
4871
 
4872
    `EBUSY'
4873
          OLDPATH or NEWPATH is a directory that is in use by some
4874
          process.
4875
 
4876
    `EINVAL'
4877
          An attempt was made to make a directory a subdirectory of
4878
          itself.
4879
 
4880
    `ENOTDIR'
4881
          A  component used as a directory in OLDPATH or new path is
4882
          not a directory.  Or OLDPATH is a directory and NEWPATH
4883
          exists but is not a directory.
4884
 
4885
    `EFAULT'
4886
          OLDPATHPTR or NEWPATHPTR are invalid pointer values.
4887
 
4888
    `EACCES'
4889
          No access to the file or the path of the file.
4890
 
4891
    `ENAMETOOLONG'
4892
          OLDPATH or NEWPATH was too long.
4893
 
4894
    `ENOENT'
4895
          A directory component in OLDPATH or NEWPATH does not exist.
4896
 
4897
    `EROFS'
4898
          The file is on a read-only filesystem.
4899
 
4900
    `ENOSPC'
4901
          The device containing the file has no room for the new
4902
          directory entry.
4903
 
4904
    `EINTR'
4905
          The call was interrupted by the user.
4906
 
4907
 
4908

4909
File: gdb.info,  Node: unlink,  Next: stat/fstat,  Prev: rename,  Up: List of Supported Calls
4910
 
4911
unlink
4912
......
4913
 
4914
Synopsis:
4915
          int unlink(const char *pathname);
4916
 
4917
Request:
4918
     `Funlink,PATHNAMEPTR/LEN'
4919
 
4920
Return value:
4921
     On success, zero is returned.  On error, -1 is returned.
4922
 
4923
Errors:
4924
 
4925
    `EACCES'
4926
          No access to the file or the path of the file.
4927
 
4928
    `EPERM'
4929
          The system does not allow unlinking of directories.
4930
 
4931
    `EBUSY'
4932
          The file PATHNAME cannot be unlinked because it's being used
4933
          by another process.
4934
 
4935
    `EFAULT'
4936
          PATHNAMEPTR is an invalid pointer value.
4937
 
4938
    `ENAMETOOLONG'
4939
          PATHNAME was too long.
4940
 
4941
    `ENOENT'
4942
          A directory component in PATHNAME does not exist.
4943
 
4944
    `ENOTDIR'
4945
          A component of the path is not a directory.
4946
 
4947
    `EROFS'
4948
          The file is on a read-only filesystem.
4949
 
4950
    `EINTR'
4951
          The call was interrupted by the user.
4952
 
4953
 
4954

4955
File: gdb.info,  Node: stat/fstat,  Next: gettimeofday,  Prev: unlink,  Up: List of Supported Calls
4956
 
4957
stat/fstat
4958
..........
4959
 
4960
Synopsis:
4961
          int stat(const char *pathname, struct stat *buf);
4962
          int fstat(int fd, struct stat *buf);
4963
 
4964
Request:
4965
     `Fstat,PATHNAMEPTR/LEN,BUFPTR'
4966
     `Ffstat,FD,BUFPTR'
4967
 
4968
Return value:
4969
     On success, zero is returned.  On error, -1 is returned.
4970
 
4971
Errors:
4972
 
4973
    `EBADF'
4974
          FD is not a valid open file.
4975
 
4976
    `ENOENT'
4977
          A directory component in PATHNAME does not exist or the path
4978
          is an empty string.
4979
 
4980
    `ENOTDIR'
4981
          A component of the path is not a directory.
4982
 
4983
    `EFAULT'
4984
          PATHNAMEPTR is an invalid pointer value.
4985
 
4986
    `EACCES'
4987
          No access to the file or the path of the file.
4988
 
4989
    `ENAMETOOLONG'
4990
          PATHNAME was too long.
4991
 
4992
    `EINTR'
4993
          The call was interrupted by the user.
4994
 
4995
 
4996

4997
File: gdb.info,  Node: gettimeofday,  Next: isatty,  Prev: stat/fstat,  Up: List of Supported Calls
4998
 
4999
gettimeofday
5000
............
5001
 
5002
Synopsis:
5003
          int gettimeofday(struct timeval *tv, void *tz);
5004
 
5005
Request:
5006
     `Fgettimeofday,TVPTR,TZPTR'
5007
 
5008
Return value:
5009
     On success, 0 is returned, -1 otherwise.
5010
 
5011
Errors:
5012
 
5013
    `EINVAL'
5014
          TZ is a non-NULL pointer.
5015
 
5016
    `EFAULT'
5017
          TVPTR and/or TZPTR is an invalid pointer value.
5018
 
5019
 
5020

5021
File: gdb.info,  Node: isatty,  Next: system,  Prev: gettimeofday,  Up: List of Supported Calls
5022
 
5023
isatty
5024
......
5025
 
5026
Synopsis:
5027
          int isatty(int fd);
5028
 
5029
Request:
5030
     `Fisatty,FD'
5031
 
5032
Return value:
5033
     Returns 1 if FD refers to the GDB console, 0 otherwise.
5034
 
5035
Errors:
5036
 
5037
    `EINTR'
5038
          The call was interrupted by the user.
5039
 
5040
 
5041
   Note that the `isatty' call is treated as a special case: it returns
5042
1 to the target if the file descriptor is attached to the GDB console,
5043
 
5044
implementing `ioctl' and would be more complex than needed.
5045
 
5046

5047
File: gdb.info,  Node: system,  Prev: isatty,  Up: List of Supported Calls
5048
 
5049
system
5050
......
5051
 
5052
Synopsis:
5053
          int system(const char *command);
5054
 
5055
Request:
5056
     `Fsystem,COMMANDPTR/LEN'
5057
 
5058
Return value:
5059
     If LEN is zero, the return value indicates whether a shell is
5060
     available.  A zero return value indicates a shell is not available.
5061
     For non-zero LEN, the value returned is -1 on error and the return
5062
     status of the command otherwise.  Only the exit status of the
5063
     command is returned, which is extracted from the host's `system'
5064
     return value by calling `WEXITSTATUS(retval)'.  In case `/bin/sh'
5065
     could not be executed, 127 is returned.
5066
 
5067
Errors:
5068
 
5069
    `EINTR'
5070
          The call was interrupted by the user.
5071
 
5072
 
5073
   GDB takes over the full task of calling the necessary host calls to
5074
perform the `system' call.  The return value of `system' on the host is
5075
simplified before it's returned to the target.  Any termination signal
5076
information from the child process is discarded, and the return value
5077
consists entirely of the exit status of the called command.
5078
 
5079
   Due to security concerns, the `system' call is by default refused by
5080
GDB.  The user has to allow this call explicitly with the `set remote
5081
system-call-allowed 1' command.
5082
 
5083
`set remote system-call-allowed'
5084
     Control whether to allow the `system' calls in the File I/O
5085
     protocol for the remote target.  The default is zero (disabled).
5086
 
5087
`show remote system-call-allowed'
5088
     Show whether the `system' calls are allowed in the File I/O
5089
     protocol.
5090
 
5091

5092
File: gdb.info,  Node: Protocol-specific Representation of Datatypes,  Next: Constants,  Prev: List of Supported Calls,  Up: File-I/O Remote Protocol Extension
5093
 
5094
D.13.8 Protocol-specific Representation of Datatypes
5095
----------------------------------------------------
5096
 
5097
* Menu:
5098
 
5099
* Integral Datatypes::
5100
* Pointer Values::
5101
* Memory Transfer::
5102
* struct stat::
5103
* struct timeval::
5104
 
5105

5106
File: gdb.info,  Node: Integral Datatypes,  Next: Pointer Values,  Up: Protocol-specific Representation of Datatypes
5107
 
5108
Integral Datatypes
5109
..................
5110
 
5111
The integral datatypes used in the system calls are `int', `unsigned
5112
int', `long', `unsigned long', `mode_t', and `time_t'.
5113
 
5114
   `int', `unsigned int', `mode_t' and `time_t' are implemented as 32
5115
bit values in this protocol.
5116
 
5117
   `long' and `unsigned long' are implemented as 64 bit types.
5118
 
5119
   *Note Limits::, for corresponding MIN and MAX values (similar to
5120
those in `limits.h') to allow range checking on host and target.
5121
 
5122
   `time_t' datatypes are defined as seconds since the Epoch.
5123
 
5124
   All integral datatypes transferred as part of a memory read or write
5125
of a structured datatype e.g. a `struct stat' have to be given in big
5126
endian byte order.
5127
 
5128

5129
File: gdb.info,  Node: Pointer Values,  Next: Memory Transfer,  Prev: Integral Datatypes,  Up: Protocol-specific Representation of Datatypes
5130
 
5131
Pointer Values
5132
..............
5133
 
5134
Pointers to target data are transmitted as they are.  An exception is
5135
made for pointers to buffers for which the length isn't transmitted as
5136
part of the function call, namely strings.  Strings are transmitted as
5137
a pointer/length pair, both as hex values, e.g.
5138
 
5139
     `1aaf/12'
5140
 
5141
which is a pointer to data of length 18 bytes at position 0x1aaf.  The
5142
length is defined as the full string length in bytes, including the
5143
trailing null byte.  For example, the string `"hello world"' at address
5144
0x123456 is transmitted as
5145
 
5146
     `123456/d'
5147
 
5148

5149
File: gdb.info,  Node: Memory Transfer,  Next: struct stat,  Prev: Pointer Values,  Up: Protocol-specific Representation of Datatypes
5150
 
5151
Memory Transfer
5152
...............
5153
 
5154
Structured data which is transferred using a memory read or write (for
5155
example, a `struct stat') is expected to be in a protocol-specific
5156
format with all scalar multibyte datatypes being big endian.
5157
Translation to this representation needs to be done both by the target
5158
before the `F' packet is sent, and by GDB before it transfers memory to
5159
the target.  Transferred pointers to structured data should point to
5160
the already-coerced data at any time.
5161
 
5162

5163
File: gdb.info,  Node: struct stat,  Next: struct timeval,  Prev: Memory Transfer,  Up: Protocol-specific Representation of Datatypes
5164
 
5165
struct stat
5166
...........
5167
 
5168
The buffer of type `struct stat' used by the target and GDB is defined
5169
as follows:
5170
 
5171
     struct stat {
5172
         unsigned int  st_dev;      /* device */
5173
         unsigned int  st_ino;      /* inode */
5174
         mode_t        st_mode;     /* protection */
5175
         unsigned int  st_nlink;    /* number of hard links */
5176
         unsigned int  st_uid;      /* user ID of owner */
5177
         unsigned int  st_gid;      /* group ID of owner */
5178
         unsigned int  st_rdev;     /* device type (if inode device) */
5179
         unsigned long st_size;     /* total size, in bytes */
5180
         unsigned long st_blksize;  /* blocksize for filesystem I/O */
5181
         unsigned long st_blocks;   /* number of blocks allocated */
5182
         time_t        st_atime;    /* time of last access */
5183
         time_t        st_mtime;    /* time of last modification */
5184
         time_t        st_ctime;    /* time of last change */
5185
     };
5186
 
5187
   The integral datatypes conform to the definitions given in the
5188
appropriate section (see *Note Integral Datatypes::, for details) so
5189
this structure is of size 64 bytes.
5190
 
5191
   The values of several fields have a restricted meaning and/or range
5192
of values.
5193
 
5194
`st_dev'
5195
     A value of 0 represents a file, 1 the console.
5196
 
5197
`st_ino'
5198
     No valid meaning for the target.  Transmitted unchanged.
5199
 
5200
`st_mode'
5201
     Valid mode bits are described in *Note Constants::.  Any other
5202
     bits have currently no meaning for the target.
5203
 
5204
`st_uid'
5205
`st_gid'
5206
`st_rdev'
5207
     No valid meaning for the target.  Transmitted unchanged.
5208
 
5209
`st_atime'
5210
`st_mtime'
5211
`st_ctime'
5212
     These values have a host and file system dependent accuracy.
5213
     Especially on Windows hosts, the file system may not support exact
5214
     timing values.
5215
 
5216
   The target gets a `struct stat' of the above representation and is
5217
responsible for coercing it to the target representation before
5218
continuing.
5219
 
5220
   Note that due to size differences between the host, target, and
5221
protocol representations of `struct stat' members, these members could
5222
eventually get truncated on the target.
5223
 
5224

5225
File: gdb.info,  Node: struct timeval,  Prev: struct stat,  Up: Protocol-specific Representation of Datatypes
5226
 
5227
struct timeval
5228
..............
5229
 
5230
The buffer of type `struct timeval' used by the File-I/O protocol is
5231
defined as follows:
5232
 
5233
     struct timeval {
5234
         time_t tv_sec;  /* second */
5235
         long   tv_usec; /* microsecond */
5236
     };
5237
 
5238
   The integral datatypes conform to the definitions given in the
5239
appropriate section (see *Note Integral Datatypes::, for details) so
5240
this structure is of size 8 bytes.
5241
 
5242

5243
File: gdb.info,  Node: Constants,  Next: File-I/O Examples,  Prev: Protocol-specific Representation of Datatypes,  Up: File-I/O Remote Protocol Extension
5244
 
5245
D.13.9 Constants
5246
----------------
5247
 
5248
The following values are used for the constants inside of the protocol.
5249
GDB and target are responsible for translating these values before and
5250
after the call as needed.
5251
 
5252
* Menu:
5253
 
5254
* Open Flags::
5255
* mode_t Values::
5256
* Errno Values::
5257
* Lseek Flags::
5258
* Limits::
5259
 
5260

5261
File: gdb.info,  Node: Open Flags,  Next: mode_t Values,  Up: Constants
5262
 
5263
Open Flags
5264
..........
5265
 
5266
All values are given in hexadecimal representation.
5267
 
5268
       O_RDONLY        0x0
5269
       O_WRONLY        0x1
5270
       O_RDWR          0x2
5271
       O_APPEND        0x8
5272
       O_CREAT       0x200
5273
       O_TRUNC       0x400
5274
       O_EXCL        0x800
5275
 
5276

5277
File: gdb.info,  Node: mode_t Values,  Next: Errno Values,  Prev: Open Flags,  Up: Constants
5278
 
5279
mode_t Values
5280
.............
5281
 
5282
All values are given in octal representation.
5283
 
5284
       S_IFREG       0100000
5285
       S_IFDIR        040000
5286
       S_IRUSR          0400
5287
       S_IWUSR          0200
5288
       S_IXUSR          0100
5289
       S_IRGRP           040
5290
       S_IWGRP           020
5291
       S_IXGRP           010
5292
       S_IROTH            04
5293
       S_IWOTH            02
5294
       S_IXOTH            01
5295
 
5296

5297
File: gdb.info,  Node: Errno Values,  Next: Lseek Flags,  Prev: mode_t Values,  Up: Constants
5298
 
5299
Errno Values
5300
............
5301
 
5302
All values are given in decimal representation.
5303
 
5304
       EPERM           1
5305
       ENOENT          2
5306
       EINTR           4
5307
       EBADF           9
5308
       EACCES         13
5309
       EFAULT         14
5310
       EBUSY          16
5311
       EEXIST         17
5312
       ENODEV         19
5313
       ENOTDIR        20
5314
       EISDIR         21
5315
       EINVAL         22
5316
       ENFILE         23
5317
       EMFILE         24
5318
       EFBIG          27
5319
       ENOSPC         28
5320
       ESPIPE         29
5321
       EROFS          30
5322
       ENAMETOOLONG   91
5323
       EUNKNOWN       9999
5324
 
5325
   `EUNKNOWN' is used as a fallback error value if a host system returns
5326
 any error value not in the list of supported error numbers.
5327
 
5328

5329
File: gdb.info,  Node: Lseek Flags,  Next: Limits,  Prev: Errno Values,  Up: Constants
5330
 
5331
Lseek Flags
5332
...........
5333
 
5334
       SEEK_SET      0
5335
       SEEK_CUR      1
5336
       SEEK_END      2
5337
 
5338

5339
File: gdb.info,  Node: Limits,  Prev: Lseek Flags,  Up: Constants
5340
 
5341
Limits
5342
......
5343
 
5344
All values are given in decimal representation.
5345
 
5346
       INT_MIN       -2147483648
5347
       INT_MAX        2147483647
5348
       UINT_MAX       4294967295
5349
       LONG_MIN      -9223372036854775808
5350
       LONG_MAX       9223372036854775807
5351
       ULONG_MAX      18446744073709551615
5352
 
5353

5354
File: gdb.info,  Node: File-I/O Examples,  Prev: Constants,  Up: File-I/O Remote Protocol Extension
5355
 
5356
D.13.10 File-I/O Examples
5357
-------------------------
5358
 
5359
Example sequence of a write call, file descriptor 3, buffer is at target
5360
address 0x1234, 6 bytes should be written:
5361
 
5362
     <- `Fwrite,3,1234,6'
5363
     _request memory read from target_
5364
     -> `m1234,6'
5365
     <- XXXXXX
5366
     _return "6 bytes written"_
5367
     -> `F6'
5368
 
5369
   Example sequence of a read call, file descriptor 3, buffer is at
5370
target address 0x1234, 6 bytes should be read:
5371
 
5372
     <- `Fread,3,1234,6'
5373
     _request memory write to target_
5374
     -> `X1234,6:XXXXXX'
5375
     _return "6 bytes read"_
5376
     -> `F6'
5377
 
5378
   Example sequence of a read call, call fails on the host due to
5379
invalid file descriptor (`EBADF'):
5380
 
5381
     <- `Fread,3,1234,6'
5382
     -> `F-1,9'
5383
 
5384
   Example sequence of a read call, user presses `Ctrl-c' before
5385
syscall on host is called:
5386
 
5387
     <- `Fread,3,1234,6'
5388
     -> `F-1,4,C'
5389
     <- `T02'
5390
 
5391
   Example sequence of a read call, user presses `Ctrl-c' after syscall
5392
on host is called:
5393
 
5394
     <- `Fread,3,1234,6'
5395
     -> `X1234,6:XXXXXX'
5396
     <- `T02'
5397
 
5398

5399
File: gdb.info,  Node: Library List Format,  Next: Memory Map Format,  Prev: File-I/O Remote Protocol Extension,  Up: Remote Protocol
5400
 
5401
D.14 Library List Format
5402
========================
5403
 
5404
On some platforms, a dynamic loader (e.g. `ld.so') runs in the same
5405
process as your application to manage libraries.  In this case, GDB can
5406
use the loader's symbol table and normal memory operations to maintain
5407
a list of shared libraries.  On other platforms, the operating system
5408
manages loaded libraries.  GDB can not retrieve the list of currently
5409
loaded libraries through memory operations, so it uses the
5410
`qXfer:libraries:read' packet (*note qXfer library list read::)
5411
instead.  The remote stub queries the target's operating system and
5412
reports which libraries are loaded.
5413
 
5414
   The `qXfer:libraries:read' packet returns an XML document which
5415
lists loaded libraries and their offsets.  Each library has an
5416
associated name and one or more segment or section base addresses,
5417
which report where the library was loaded in memory.
5418
 
5419
   For the common case of libraries that are fully linked binaries, the
5420
library should have a list of segments.  If the target supports dynamic
5421
linking of a relocatable object file, its library XML element should
5422
instead include a list of allocated sections.  The segment or section
5423
bases are start addresses, not relocation offsets; they do not depend
5424
on the library's link-time base addresses.
5425
 
5426
   GDB must be linked with the Expat library to support XML library
5427
lists.  *Note Expat::.
5428
 
5429
   A simple memory map, with one loaded library relocated by a single
5430
offset, looks like this:
5431
 
5432
     
5433
       
5434
         
5435
       
5436
     
5437
 
5438
   Another simple memory map, with one loaded library with three
5439
allocated sections (.text, .data, .bss), looks like this:
5440
 
5441
     
5442
       
5443
         
5444
         
5445
         
5446
       
5447
     
5448
 
5449
   The format of a library list is described by this DTD:
5450
 
5451
     
5452
     
5453
     
5454
     
5455
     
5456
     
5457
     
5458
     
5459
     
5460
 
5461
   In addition, segments and section descriptors cannot be mixed within
5462
a single library element, and you must supply at least one segment or
5463
section for each library.
5464
 
5465

5466
File: gdb.info,  Node: Memory Map Format,  Next: Thread List Format,  Prev: Library List Format,  Up: Remote Protocol
5467
 
5468
D.15 Memory Map Format
5469
======================
5470
 
5471
To be able to write into flash memory, GDB needs to obtain a memory map
5472
from the target.  This section describes the format of the memory map.
5473
 
5474
   The memory map is obtained using the `qXfer:memory-map:read' (*note
5475
qXfer memory map read::) packet and is an XML document that lists
5476
memory regions.
5477
 
5478
   GDB must be linked with the Expat library to support XML memory
5479
maps.  *Note Expat::.
5480
 
5481
   The top-level structure of the document is shown below:
5482
 
5483
     
5484
     
5485
               PUBLIC "+//IDN gnu.org//DTD GDB Memory Map V1.0//EN"
5486
                      "http://sourceware.org/gdb/gdb-memory-map.dtd">
5487
     
5488
         region...
5489
     
5490
 
5491
   Each region can be either:
5492
 
5493
   * A region of RAM starting at ADDR and extending for LENGTH bytes
5494
     from there:
5495
 
5496
          
5497
 
5498
   * A region of read-only memory:
5499
 
5500
          
5501
 
5502
   * A region of flash memory, with erasure blocks BLOCKSIZE bytes in
5503
     length:
5504
 
5505
          
5506
            BLOCKSIZE
5507
          
5508
 
5509
 
5510
   Regions must not overlap.  GDB assumes that areas of memory not
5511
covered by the memory map are RAM, and uses the ordinary `M' and `X'
5512
packets to write to addresses in such ranges.
5513
 
5514
   The formal DTD for memory map format is given below:
5515
 
5516
     
5517
     
5518
     
5519
     
5520
     
5521
     
5522
     
5523
     
5524
     
5525
     
5527
     
5528
                             start   CDATA   #REQUIRED
5529
                             length  CDATA   #REQUIRED
5530
                             device  CDATA   #IMPLIED>
5531
     
5532
     
5533
     
5534
 
5535

5536
File: gdb.info,  Node: Thread List Format,  Prev: Memory Map Format,  Up: Remote Protocol
5537
 
5538
D.16 Thread List Format
5539
=======================
5540
 
5541
To efficiently update the list of threads and their attributes, GDB
5542
issues the `qXfer:threads:read' packet (*note qXfer threads read::) and
5543
obtains the XML document with the following structure:
5544
 
5545
     
5546
     
5547
         
5548
         ... description ...
5549
         
5550
     
5551
 
5552
   Each `thread' element must have the `id' attribute that identifies
5553
the thread (*note thread-id syntax::).  The `core' attribute, if
5554
present, specifies which processor core the thread was last executing
5555
on.  The content of the of `thread' element is interpreted as
5556
human-readable auxilliary information.
5557
 
5558

5559
File: gdb.info,  Node: Agent Expressions,  Next: Target Descriptions,  Prev: Remote Protocol,  Up: Top
5560
 
5561
Appendix E The GDB Agent Expression Mechanism
5562
*********************************************
5563
 
5564
In some applications, it is not feasible for the debugger to interrupt
5565
the program's execution long enough for the developer to learn anything
5566
helpful about its behavior.  If the program's correctness depends on its
5567
real-time behavior, delays introduced by a debugger might cause the
5568
program to fail, even when the code itself is correct.  It is useful to
5569
be able to observe the program's behavior without interrupting it.
5570
 
5571
   Using GDB's `trace' and `collect' commands, the user can specify
5572
locations in the program, and arbitrary expressions to evaluate when
5573
those locations are reached.  Later, using the `tfind' command, she can
5574
examine the values those expressions had when the program hit the trace
5575
points.  The expressions may also denote objects in memory --
5576
structures or arrays, for example -- whose values GDB should record;
5577
while visiting a particular tracepoint, the user may inspect those
5578
objects as if they were in memory at that moment.  However, because GDB
5579
records these values without interacting with the user, it can do so
5580
quickly and unobtrusively, hopefully not disturbing the program's
5581
behavior.
5582
 
5583
   When GDB is debugging a remote target, the GDB "agent" code running
5584
on the target computes the values of the expressions itself.  To avoid
5585
having a full symbolic expression evaluator on the agent, GDB translates
5586
expressions in the source language into a simpler bytecode language, and
5587
then sends the bytecode to the agent; the agent then executes the
5588
bytecode, and records the values for GDB to retrieve later.
5589
 
5590
   The bytecode language is simple; there are forty-odd opcodes, the
5591
bulk of which are the usual vocabulary of C operands (addition,
5592
subtraction, shifts, and so on) and various sizes of literals and
5593
memory reference operations.  The bytecode interpreter operates
5594
strictly on machine-level values -- various sizes of integers and
5595
floating point numbers -- and requires no information about types or
5596
symbols; thus, the interpreter's internal data structures are simple,
5597
and each bytecode requires only a few native machine instructions to
5598
implement it.  The interpreter is small, and strict limits on the
5599
memory and time required to evaluate an expression are easy to
5600
determine, making it suitable for use by the debugging agent in
5601
real-time applications.
5602
 
5603
* Menu:
5604
 
5605
* General Bytecode Design::     Overview of the interpreter.
5606
* Bytecode Descriptions::       What each one does.
5607
* Using Agent Expressions::     How agent expressions fit into the big picture.
5608
* Varying Target Capabilities:: How to discover what the target can do.
5609
* Rationale::                   Why we did it this way.
5610
 
5611

5612
File: gdb.info,  Node: General Bytecode Design,  Next: Bytecode Descriptions,  Up: Agent Expressions
5613
 
5614
E.1 General Bytecode Design
5615
===========================
5616
 
5617
The agent represents bytecode expressions as an array of bytes.  Each
5618
instruction is one byte long (thus the term "bytecode").  Some
5619
instructions are followed by operand bytes; for example, the `goto'
5620
instruction is followed by a destination for the jump.
5621
 
5622
   The bytecode interpreter is a stack-based machine; most instructions
5623
pop their operands off the stack, perform some operation, and push the
5624
result back on the stack for the next instruction to consume.  Each
5625
element of the stack may contain either a integer or a floating point
5626
value; these values are as many bits wide as the largest integer that
5627
can be directly manipulated in the source language.  Stack elements
5628
carry no record of their type; bytecode could push a value as an
5629
integer, then pop it as a floating point value.  However, GDB will not
5630
generate code which does this.  In C, one might define the type of a
5631
stack element as follows:
5632
     union agent_val {
5633
       LONGEST l;
5634
       DOUBLEST d;
5635
     };
5636
   where `LONGEST' and `DOUBLEST' are `typedef' names for the largest
5637
integer and floating point types on the machine.
5638
 
5639
   By the time the bytecode interpreter reaches the end of the
5640
expression, the value of the expression should be the only value left
5641
on the stack.  For tracing applications, `trace' bytecodes in the
5642
expression will have recorded the necessary data, and the value on the
5643
stack may be discarded.  For other applications, like conditional
5644
breakpoints, the value may be useful.
5645
 
5646
   Separate from the stack, the interpreter has two registers:
5647
`pc'
5648
     The address of the next bytecode to execute.
5649
 
5650
`start'
5651
     The address of the start of the bytecode expression, necessary for
5652
     interpreting the `goto' and `if_goto' instructions.
5653
 
5654
   Neither of these registers is directly visible to the bytecode
5655
language itself, but they are useful for defining the meanings of the
5656
bytecode operations.
5657
 
5658
   There are no instructions to perform side effects on the running
5659
program, or call the program's functions; we assume that these
5660
expressions are only used for unobtrusive debugging, not for patching
5661
the running code.
5662
 
5663
   Most bytecode instructions do not distinguish between the various
5664
sizes of values, and operate on full-width values; the upper bits of the
5665
values are simply ignored, since they do not usually make a difference
5666
to the value computed.  The exceptions to this rule are:
5667
memory reference instructions (`ref'N)
5668
     There are distinct instructions to fetch different word sizes from
5669
     memory.  Once on the stack, however, the values are treated as
5670
     full-size integers.  They may need to be sign-extended; the `ext'
5671
     instruction exists for this purpose.
5672
 
5673
the sign-extension instruction (`ext' N)
5674
     These clearly need to know which portion of their operand is to be
5675
     extended to occupy the full length of the word.
5676
 
5677
 
5678
   If the interpreter is unable to evaluate an expression completely for
5679
some reason (a memory location is inaccessible, or a divisor is zero,
5680
for example), we say that interpretation "terminates with an error".
5681
This means that the problem is reported back to the interpreter's caller
5682
in some helpful way.  In general, code using agent expressions should
5683
assume that they may attempt to divide by zero, fetch arbitrary memory
5684
locations, and misbehave in other ways.
5685
 
5686
   Even complicated C expressions compile to a few bytecode
5687
instructions; for example, the expression `x + y * z' would typically
5688
produce code like the following, assuming that `x' and `y' live in
5689
registers, and `z' is a global variable holding a 32-bit `int':
5690
     reg 1
5691
     reg 2
5692
     const32 address of z
5693
     ref32
5694
     ext 32
5695
     mul
5696
     add
5697
     end
5698
 
5699
   In detail, these mean:
5700
`reg 1'
5701
     Push the value of register 1 (presumably holding `x') onto the
5702
     stack.
5703
 
5704
`reg 2'
5705
     Push the value of register 2 (holding `y').
5706
 
5707
`const32 address of z'
5708
     Push the address of `z' onto the stack.
5709
 
5710
`ref32'
5711
     Fetch a 32-bit word from the address at the top of the stack;
5712
     replace the address on the stack with the value.  Thus, we replace
5713
     the address of `z' with `z''s value.
5714
 
5715
`ext 32'
5716
     Sign-extend the value on the top of the stack from 32 bits to full
5717
     length.  This is necessary because `z' is a signed integer.
5718
 
5719
`mul'
5720
     Pop the top two numbers on the stack, multiply them, and push their
5721
     product.  Now the top of the stack contains the value of the
5722
     expression `y * z'.
5723
 
5724
`add'
5725
     Pop the top two numbers, add them, and push the sum.  Now the top
5726
     of the stack contains the value of `x + y * z'.
5727
 
5728
`end'
5729
     Stop executing; the value left on the stack top is the value to be
5730
     recorded.
5731
 
5732
 
5733

5734
File: gdb.info,  Node: Bytecode Descriptions,  Next: Using Agent Expressions,  Prev: General Bytecode Design,  Up: Agent Expressions
5735
 
5736
E.2 Bytecode Descriptions
5737
=========================
5738
 
5739
Each bytecode description has the following form:
5740
 
5741
`add' (0x02): A B => A+B
5742
     Pop the top two stack items, A and B, as integers; push their sum,
5743
     as an integer.
5744
 
5745
 
5746
   In this example, `add' is the name of the bytecode, and `(0x02)' is
5747
the one-byte value used to encode the bytecode, in hexadecimal.  The
5748
phrase "A B => A+B" shows the stack before and after the bytecode
5749
executes.  Beforehand, the stack must contain at least two values, A
5750
and B; since the top of the stack is to the right, B is on the top of
5751
the stack, and A is underneath it.  After execution, the bytecode will
5752
have popped A and B from the stack, and replaced them with a single
5753
value, A+B.  There may be other values on the stack below those shown,
5754
but the bytecode affects only those shown.
5755
 
5756
   Here is another example:
5757
 
5758
`const8' (0x22) N: => N
5759
     Push the 8-bit integer constant N on the stack, without sign
5760
     extension.
5761
 
5762
 
5763
   In this example, the bytecode `const8' takes an operand N directly
5764
from the bytecode stream; the operand follows the `const8' bytecode
5765
itself.  We write any such operands immediately after the name of the
5766
bytecode, before the colon, and describe the exact encoding of the
5767
operand in the bytecode stream in the body of the bytecode description.
5768
 
5769
   For the `const8' bytecode, there are no stack items given before the
5770
=>; this simply means that the bytecode consumes no values from the
5771
stack.  If a bytecode consumes no values, or produces no values, the
5772
list on either side of the => may be empty.
5773
 
5774
   If a value is written as A, B, or N, then the bytecode treats it as
5775
an integer.  If a value is written is ADDR, then the bytecode treats it
5776
as an address.
5777
 
5778
   We do not fully describe the floating point operations here; although
5779
this design can be extended in a clean way to handle floating point
5780
values, they are not of immediate interest to the customer, so we avoid
5781
describing them, to save time.
5782
 
5783
`float' (0x01): =>
5784
     Prefix for floating-point bytecodes.  Not implemented yet.
5785
 
5786
`add' (0x02): A B => A+B
5787
     Pop two integers from the stack, and push their sum, as an integer.
5788
 
5789
`sub' (0x03): A B => A-B
5790
     Pop two integers from the stack, subtract the top value from the
5791
     next-to-top value, and push the difference.
5792
 
5793
`mul' (0x04): A B => A*B
5794
     Pop two integers from the stack, multiply them, and push the
5795
     product on the stack.  Note that, when one multiplies two N-bit
5796
     numbers yielding another N-bit number, it is irrelevant whether the
5797
     numbers are signed or not; the results are the same.
5798
 
5799
`div_signed' (0x05): A B => A/B
5800
     Pop two signed integers from the stack; divide the next-to-top
5801
     value by the top value, and push the quotient.  If the divisor is
5802
     zero, terminate with an error.
5803
 
5804
`div_unsigned' (0x06): A B => A/B
5805
     Pop two unsigned integers from the stack; divide the next-to-top
5806
     value by the top value, and push the quotient.  If the divisor is
5807
     zero, terminate with an error.
5808
 
5809
`rem_signed' (0x07): A B => A MODULO B
5810
     Pop two signed integers from the stack; divide the next-to-top
5811
     value by the top value, and push the remainder.  If the divisor is
5812
     zero, terminate with an error.
5813
 
5814
`rem_unsigned' (0x08): A B => A MODULO B
5815
     Pop two unsigned integers from the stack; divide the next-to-top
5816
     value by the top value, and push the remainder.  If the divisor is
5817
     zero, terminate with an error.
5818
 
5819
`lsh' (0x09): A B => A<
5820
     Pop two integers from the stack; let A be the next-to-top value,
5821
     and B be the top value.  Shift A left by B bits, and push the
5822
     result.
5823
 
5824
`rsh_signed' (0x0a): A B => `(signed)'A>>B
5825
     Pop two integers from the stack; let A be the next-to-top value,
5826
     and B be the top value.  Shift A right by B bits, inserting copies
5827
     of the top bit at the high end, and push the result.
5828
 
5829
`rsh_unsigned' (0x0b): A B => A>>B
5830
     Pop two integers from the stack; let A be the next-to-top value,
5831
     and B be the top value.  Shift A right by B bits, inserting zero
5832
     bits at the high end, and push the result.
5833
 
5834
`log_not' (0x0e): A => !A
5835
     Pop an integer from the stack; if it is zero, push the value one;
5836
     otherwise, push the value zero.
5837
 
5838
`bit_and' (0x0f): A B => A&B
5839
     Pop two integers from the stack, and push their bitwise `and'.
5840
 
5841
`bit_or' (0x10): A B => A|B
5842
     Pop two integers from the stack, and push their bitwise `or'.
5843
 
5844
`bit_xor' (0x11): A B => A^B
5845
     Pop two integers from the stack, and push their bitwise
5846
     exclusive-`or'.
5847
 
5848
`bit_not' (0x12): A => ~A
5849
     Pop an integer from the stack, and push its bitwise complement.
5850
 
5851
`equal' (0x13): A B => A=B
5852
     Pop two integers from the stack; if they are equal, push the value
5853
     one; otherwise, push the value zero.
5854
 
5855
`less_signed' (0x14): A B => A
5856
     Pop two signed integers from the stack; if the next-to-top value
5857
     is less than the top value, push the value one; otherwise, push
5858
     the value zero.
5859
 
5860
`less_unsigned' (0x15): A B => A
5861
     Pop two unsigned integers from the stack; if the next-to-top value
5862
     is less than the top value, push the value one; otherwise, push
5863
     the value zero.
5864
 
5865
`ext' (0x16) N: A => A, sign-extended from N bits
5866
     Pop an unsigned value from the stack; treating it as an N-bit
5867
     twos-complement value, extend it to full length.  This means that
5868
     all bits to the left of bit N-1 (where the least significant bit
5869
     is bit 0) are set to the value of bit N-1.  Note that N may be
5870
     larger than or equal to the width of the stack elements of the
5871
     bytecode engine; in this case, the bytecode should have no effect.
5872
 
5873
     The number of source bits to preserve, N, is encoded as a single
5874
     byte unsigned integer following the `ext' bytecode.
5875
 
5876
`zero_ext' (0x2a) N: A => A, zero-extended from N bits
5877
     Pop an unsigned value from the stack; zero all but the bottom N
5878
     bits.  This means that all bits to the left of bit N-1 (where the
5879
     least significant bit is bit 0) are set to the value of bit N-1.
5880
 
5881
     The number of source bits to preserve, N, is encoded as a single
5882
     byte unsigned integer following the `zero_ext' bytecode.
5883
 
5884
`ref8' (0x17): ADDR => A
5885
`ref16' (0x18): ADDR => A
5886
`ref32' (0x19): ADDR => A
5887
`ref64' (0x1a): ADDR => A
5888
     Pop an address ADDR from the stack.  For bytecode `ref'N, fetch an
5889
     N-bit value from ADDR, using the natural target endianness.  Push
5890
     the fetched value as an unsigned integer.
5891
 
5892
     Note that ADDR may not be aligned in any particular way; the
5893
     `refN' bytecodes should operate correctly for any address.
5894
 
5895
     If attempting to access memory at ADDR would cause a processor
5896
     exception of some sort, terminate with an error.
5897
 
5898
`ref_float' (0x1b): ADDR => D
5899
`ref_double' (0x1c): ADDR => D
5900
`ref_long_double' (0x1d): ADDR => D
5901
`l_to_d' (0x1e): A => D
5902
`d_to_l' (0x1f): D => A
5903
     Not implemented yet.
5904
 
5905
`dup' (0x28): A => A A
5906
     Push another copy of the stack's top element.
5907
 
5908
`swap' (0x2b): A B => B A
5909
     Exchange the top two items on the stack.
5910
 
5911
`pop' (0x29): A =>
5912
     Discard the top value on the stack.
5913
 
5914
`if_goto' (0x20) OFFSET: A =>
5915
     Pop an integer off the stack; if it is non-zero, branch to the
5916
     given offset in the bytecode string.  Otherwise, continue to the
5917
     next instruction in the bytecode stream.  In other words, if A is
5918
     non-zero, set the `pc' register to `start' + OFFSET.  Thus, an
5919
     offset of zero denotes the beginning of the expression.
5920
 
5921
     The OFFSET is stored as a sixteen-bit unsigned value, stored
5922
     immediately following the `if_goto' bytecode.  It is always stored
5923
     most significant byte first, regardless of the target's normal
5924
     endianness.  The offset is not guaranteed to fall at any particular
5925
     alignment within the bytecode stream; thus, on machines where
5926
     fetching a 16-bit on an unaligned address raises an exception, you
5927
     should fetch the offset one byte at a time.
5928
 
5929
`goto' (0x21) OFFSET: =>
5930
     Branch unconditionally to OFFSET; in other words, set the `pc'
5931
     register to `start' + OFFSET.
5932
 
5933
     The offset is stored in the same way as for the `if_goto' bytecode.
5934
 
5935
`const8' (0x22) N: => N
5936
`const16' (0x23) N: => N
5937
`const32' (0x24) N: => N
5938
`const64' (0x25) N: => N
5939
     Push the integer constant N on the stack, without sign extension.
5940
     To produce a small negative value, push a small twos-complement
5941
     value, and then sign-extend it using the `ext' bytecode.
5942
 
5943
     The constant N is stored in the appropriate number of bytes
5944
     following the `const'B bytecode.  The constant N is always stored
5945
     most significant byte first, regardless of the target's normal
5946
     endianness.  The constant is not guaranteed to fall at any
5947
     particular alignment within the bytecode stream; thus, on machines
5948
     where fetching a 16-bit on an unaligned address raises an
5949
     exception, you should fetch N one byte at a time.
5950
 
5951
`reg' (0x26) N: => A
5952
     Push the value of register number N, without sign extension.  The
5953
     registers are numbered following GDB's conventions.
5954
 
5955
     The register number N is encoded as a 16-bit unsigned integer
5956
     immediately following the `reg' bytecode.  It is always stored most
5957
     significant byte first, regardless of the target's normal
5958
     endianness.  The register number is not guaranteed to fall at any
5959
     particular alignment within the bytecode stream; thus, on machines
5960
     where fetching a 16-bit on an unaligned address raises an
5961
     exception, you should fetch the register number one byte at a time.
5962
 
5963
`getv' (0x2c) N: => V
5964
     Push the value of trace state variable number N, without sign
5965
     extension.
5966
 
5967
     The variable number N is encoded as a 16-bit unsigned integer
5968
     immediately following the `getv' bytecode.  It is always stored
5969
     most significant byte first, regardless of the target's normal
5970
     endianness.  The variable number is not guaranteed to fall at any
5971
     particular alignment within the bytecode stream; thus, on machines
5972
     where fetching a 16-bit on an unaligned address raises an
5973
     exception, you should fetch the register number one byte at a time.
5974
 
5975
`setv' (0x2d) N: => V
5976
     Set trace state variable number N to the value found on the top of
5977
     the stack.  The stack is unchanged, so that the value is readily
5978
     available if the assignment is part of a larger expression.  The
5979
     handling of N is as described for `getv'.
5980
 
5981
`trace' (0x0c): ADDR SIZE =>
5982
     Record the contents of the SIZE bytes at ADDR in a trace buffer,
5983
     for later retrieval by GDB.
5984
 
5985
`trace_quick' (0x0d) SIZE: ADDR => ADDR
5986
     Record the contents of the SIZE bytes at ADDR in a trace buffer,
5987
     for later retrieval by GDB.  SIZE is a single byte unsigned
5988
     integer following the `trace' opcode.
5989
 
5990
     This bytecode is equivalent to the sequence `dup const8 SIZE
5991
     trace', but we provide it anyway to save space in bytecode strings.
5992
 
5993
`trace16' (0x30) SIZE: ADDR => ADDR
5994
     Identical to trace_quick, except that SIZE is a 16-bit big-endian
5995
     unsigned integer, not a single byte.  This should probably have
5996
     been named `trace_quick16', for consistency.
5997
 
5998
`tracev' (0x2e) N: => A
5999
     Record the value of trace state variable number N in the trace
6000
     buffer.  The handling of N is as described for `getv'.
6001
 
6002
`end' (0x27): =>
6003
     Stop executing bytecode; the result should be the top element of
6004
     the stack.  If the purpose of the expression was to compute an
6005
     lvalue or a range of memory, then the next-to-top of the stack is
6006
     the lvalue's address, and the top of the stack is the lvalue's
6007
     size, in bytes.
6008
 
6009
 
6010

6011
File: gdb.info,  Node: Using Agent Expressions,  Next: Varying Target Capabilities,  Prev: Bytecode Descriptions,  Up: Agent Expressions
6012
 
6013
E.3 Using Agent Expressions
6014
===========================
6015
 
6016
Agent expressions can be used in several different ways by GDB, and the
6017
debugger can generate different bytecode sequences as appropriate.
6018
 
6019
   One possibility is to do expression evaluation on the target rather
6020
than the host, such as for the conditional of a conditional tracepoint.
6021
In such a case, GDB compiles the source expression into a bytecode
6022
sequence that simply gets values from registers or memory, does
6023
arithmetic, and returns a result.
6024
 
6025
   Another way to use agent expressions is for tracepoint data
6026
collection.  GDB generates a different bytecode sequence for
6027
collection; in addition to bytecodes that do the calculation, GDB adds
6028
`trace' bytecodes to save the pieces of memory that were used.
6029
 
6030
   * The user selects trace points in the program's code at which GDB
6031
     should collect data.
6032
 
6033
   * The user specifies expressions to evaluate at each trace point.
6034
     These expressions may denote objects in memory, in which case
6035
     those objects' contents are recorded as the program runs, or
6036
     computed values, in which case the values themselves are recorded.
6037
 
6038
   * GDB transmits the tracepoints and their associated expressions to
6039
     the GDB agent, running on the debugging target.
6040
 
6041
   * The agent arranges to be notified when a trace point is hit.
6042
 
6043
   * When execution on the target reaches a trace point, the agent
6044
     evaluates the expressions associated with that trace point, and
6045
     records the resulting values and memory ranges.
6046
 
6047
   * Later, when the user selects a given trace event and inspects the
6048
     objects and expression values recorded, GDB talks to the agent to
6049
     retrieve recorded data as necessary to meet the user's requests.
6050
     If the user asks to see an object whose contents have not been
6051
     recorded, GDB reports an error.
6052
 
6053
 
6054

6055
File: gdb.info,  Node: Varying Target Capabilities,  Next: Rationale,  Prev: Using Agent Expressions,  Up: Agent Expressions
6056
 
6057
E.4 Varying Target Capabilities
6058
===============================
6059
 
6060
Some targets don't support floating-point, and some would rather not
6061
have to deal with `long long' operations.  Also, different targets will
6062
have different stack sizes, and different bytecode buffer lengths.
6063
 
6064
   Thus, GDB needs a way to ask the target about itself.  We haven't
6065
worked out the details yet, but in general, GDB should be able to send
6066
the target a packet asking it to describe itself.  The reply should be a
6067
packet whose length is explicit, so we can add new information to the
6068
packet in future revisions of the agent, without confusing old versions
6069
of GDB, and it should contain a version number.  It should contain at
6070
least the following information:
6071
 
6072
   * whether floating point is supported
6073
 
6074
   * whether `long long' is supported
6075
 
6076
   * maximum acceptable size of bytecode stack
6077
 
6078
   * maximum acceptable length of bytecode expressions
6079
 
6080
   * which registers are actually available for collection
6081
 
6082
   * whether the target supports disabled tracepoints
6083
 
6084
 
6085

6086
File: gdb.info,  Node: Rationale,  Prev: Varying Target Capabilities,  Up: Agent Expressions
6087
 
6088
E.5 Rationale
6089
=============
6090
 
6091
Some of the design decisions apparent above are arguable.
6092
 
6093
What about stack overflow/underflow?
6094
     GDB should be able to query the target to discover its stack size.
6095
     Given that information, GDB can determine at translation time
6096
     whether a given expression will overflow the stack.  But this spec
6097
     isn't about what kinds of error-checking GDB ought to do.
6098
 
6099
Why are you doing everything in LONGEST?
6100
     Speed isn't important, but agent code size is; using LONGEST
6101
     brings in a bunch of support code to do things like division, etc.
6102
     So this is a serious concern.
6103
 
6104
     First, note that you don't need different bytecodes for different
6105
     operand sizes.  You can generate code without _knowing_ how big the
6106
     stack elements actually are on the target.  If the target only
6107
     supports 32-bit ints, and you don't send any 64-bit bytecodes,
6108
     everything just works.  The observation here is that the MIPS and
6109
     the Alpha have only fixed-size registers, and you can still get
6110
     C's semantics even though most instructions only operate on
6111
     full-sized words.  You just need to make sure everything is
6112
     properly sign-extended at the right times.  So there is no need
6113
     for 32- and 64-bit variants of the bytecodes.  Just implement
6114
     everything using the largest size you support.
6115
 
6116
     GDB should certainly check to see what sizes the target supports,
6117
     so the user can get an error earlier, rather than later.  But this
6118
     information is not necessary for correctness.
6119
 
6120
Why don't you have `>' or `<=' operators?
6121
     I want to keep the interpreter small, and we don't need them.  We
6122
     can combine the `less_' opcodes with `log_not', and swap the order
6123
     of the operands, yielding all four asymmetrical comparison
6124
     operators.  For example, `(x <= y)' is `! (x > y)', which is `! (y
6125
     < x)'.
6126
 
6127
Why do you have `log_not'?
6128
Why do you have `ext'?
6129
Why do you have `zero_ext'?
6130
     These are all easily synthesized from other instructions, but I
6131
     expect them to be used frequently, and they're simple, so I
6132
     include them to keep bytecode strings short.
6133
 
6134
     `log_not' is equivalent to `const8 0 equal'; it's used in half the
6135
     relational operators.
6136
 
6137
     `ext N' is equivalent to `const8 S-N lsh const8 S-N rsh_signed',
6138
     where S is the size of the stack elements; it follows `refM' and
6139
     REG bytecodes when the value should be signed.  See the next
6140
     bulleted item.
6141
 
6142
     `zero_ext N' is equivalent to `constM MASK log_and'; it's used
6143
     whenever we push the value of a register, because we can't assume
6144
     the upper bits of the register aren't garbage.
6145
 
6146
Why not have sign-extending variants of the `ref' operators?
6147
     Because that would double the number of `ref' operators, and we
6148
     need the `ext' bytecode anyway for accessing bitfields.
6149
 
6150
Why not have constant-address variants of the `ref' operators?
6151
     Because that would double the number of `ref' operators again, and
6152
     `const32 ADDRESS ref32' is only one byte longer.
6153
 
6154
Why do the `refN' operators have to support unaligned fetches?
6155
     GDB will generate bytecode that fetches multi-byte values at
6156
     unaligned addresses whenever the executable's debugging
6157
     information tells it to.  Furthermore, GDB does not know the value
6158
     the pointer will have when GDB generates the bytecode, so it
6159
     cannot determine whether a particular fetch will be aligned or not.
6160
 
6161
     In particular, structure bitfields may be several bytes long, but
6162
     follow no alignment rules; members of packed structures are not
6163
     necessarily aligned either.
6164
 
6165
     In general, there are many cases where unaligned references occur
6166
     in correct C code, either at the programmer's explicit request, or
6167
     at the compiler's discretion.  Thus, it is simpler to make the GDB
6168
     agent bytecodes work correctly in all circumstances than to make
6169
     GDB guess in each case whether the compiler did the usual thing.
6170
 
6171
Why are there no side-effecting operators?
6172
     Because our current client doesn't want them?  That's a cheap
6173
     answer.  I think the real answer is that I'm afraid of
6174
     implementing function calls.  We should re-visit this issue after
6175
     the present contract is delivered.
6176
 
6177
Why aren't the `goto' ops PC-relative?
6178
     The interpreter has the base address around anyway for PC bounds
6179
     checking, and it seemed simpler.
6180
 
6181
Why is there only one offset size for the `goto' ops?
6182
     Offsets are currently sixteen bits.  I'm not happy with this
6183
     situation either:
6184
 
6185
     Suppose we have multiple branch ops with different offset sizes.
6186
     As I generate code left-to-right, all my jumps are forward jumps
6187
     (there are no loops in expressions), so I never know the target
6188
     when I emit the jump opcode.  Thus, I have to either always assume
6189
     the largest offset size, or do jump relaxation on the code after I
6190
     generate it, which seems like a big waste of time.
6191
 
6192
     I can imagine a reasonable expression being longer than 256 bytes.
6193
     I can't imagine one being longer than 64k.  Thus, we need 16-bit
6194
     offsets.  This kind of reasoning is so bogus, but relaxation is
6195
     pathetic.
6196
 
6197
     The other approach would be to generate code right-to-left.  Then
6198
     I'd always know my offset size.  That might be fun.
6199
 
6200
Where is the function call bytecode?
6201
     When we add side-effects, we should add this.
6202
 
6203
Why does the `reg' bytecode take a 16-bit register number?
6204
     Intel's IA-64 architecture has 128 general-purpose registers, and
6205
     128 floating-point registers, and I'm sure it has some random
6206
     control registers.
6207
 
6208
Why do we need `trace' and `trace_quick'?
6209
     Because GDB needs to record all the memory contents and registers
6210
     an expression touches.  If the user wants to evaluate an expression
6211
     `x->y->z', the agent must record the values of `x' and `x->y' as
6212
     well as the value of `x->y->z'.
6213
 
6214
Don't the `trace' bytecodes make the interpreter less general?
6215
     They do mean that the interpreter contains special-purpose code,
6216
     but that doesn't mean the interpreter can only be used for that
6217
     purpose.  If an expression doesn't use the `trace' bytecodes, they
6218
     don't get in its way.
6219
 
6220
Why doesn't `trace_quick' consume its arguments the way everything else does?
6221
     In general, you do want your operators to consume their arguments;
6222
     it's consistent, and generally reduces the amount of stack
6223
     rearrangement necessary.  However, `trace_quick' is a kludge to
6224
     save space; it only exists so we needn't write `dup const8 SIZE
6225
     trace' before every memory reference.  Therefore, it's okay for it
6226
     not to consume its arguments; it's meant for a specific context in
6227
     which we know exactly what it should do with the stack.  If we're
6228
     going to have a kludge, it should be an effective kludge.
6229
 
6230
Why does `trace16' exist?
6231
     That opcode was added by the customer that contracted Cygnus for
6232
     the data tracing work.  I personally think it is unnecessary;
6233
     objects that large will be quite rare, so it is okay to use `dup
6234
     const16 SIZE trace' in those cases.
6235
 
6236
     Whatever we decide to do with `trace16', we should at least leave
6237
     opcode 0x30 reserved, to remain compatible with the customer who
6238
     added it.
6239
 
6240
 
6241

6242
File: gdb.info,  Node: Trace File Format,  Next: Copying,  Prev: Operating System Information,  Up: Top
6243
 
6244
Appendix F Trace File Format
6245
****************************
6246
 
6247
The trace file comes in three parts: a header, a textual description
6248
section, and a trace frame section with binary data.
6249
 
6250
   The header has the form `\x7fTRACE0\n'.  The first byte is `0x7f' so
6251
as to indicate that the file contains binary data, while the `0' is a
6252
version number that may have different values in the future.
6253
 
6254
   The description section consists of multiple lines of ASCII text
6255
separated by newline characters (`0xa').  The lines may include a
6256
variety of optional descriptive or context-setting information, such as
6257
tracepoint definitions or register set size.  GDB will ignore any line
6258
that it does not recognize.  An empty line marks the end of this
6259
section.
6260
 
6261
   The trace frame section consists of a number of consecutive frames.
6262
Each frame begins with a two-byte tracepoint number, followed by a
6263
four-byte size giving the amount of data in the frame.  The data in the
6264
frame consists of a number of blocks, each introduced by a character
6265
indicating its type (at least register, memory, and trace state
6266
variable).  The data in this section is raw binary, not a hexadecimal
6267
or other encoding; its endianness matches the target's endianness.
6268
 
6269
`R BYTES'
6270
     Register block.  The number and ordering of bytes matches that of a
6271
     `g' packet in the remote protocol.  Note that these are the actual
6272
     bytes, in target order and GDB register order, not a hexadecimal
6273
     encoding.
6274
 
6275
`M ADDRESS LENGTH BYTES...'
6276
     Memory block.  This is a contiguous block of memory, at the 8-byte
6277
     address ADDRESS, with a 2-byte length LENGTH, followed by LENGTH
6278
     bytes.
6279
 
6280
`V NUMBER VALUE'
6281
     Trace state variable block.  This records the 8-byte signed value
6282
     VALUE of trace state variable numbered NUMBER.
6283
 
6284
 
6285
   Future enhancements of the trace file format may include additional
6286
types of blocks.
6287
 
6288

6289
File: gdb.info,  Node: Target Descriptions,  Next: Operating System Information,  Prev: Agent Expressions,  Up: Top
6290
 
6291
Appendix G Target Descriptions
6292
******************************
6293
 
6294
*Warning:* target descriptions are still under active development, and
6295
the contents and format may change between GDB releases.  The format is
6296
expected to stabilize in the future.
6297
 
6298
   One of the challenges of using GDB to debug embedded systems is that
6299
there are so many minor variants of each processor architecture in use.
6300
It is common practice for vendors to start with a standard processor
6301
core -- ARM, PowerPC, or MIPS, for example -- and then make changes to
6302
adapt it to a particular market niche.  Some architectures have
6303
hundreds of variants, available from dozens of vendors.  This leads to
6304
a number of problems:
6305
 
6306
   * With so many different customized processors, it is difficult for
6307
     the GDB maintainers to keep up with the changes.
6308
 
6309
   * Since individual variants may have short lifetimes or limited
6310
     audiences, it may not be worthwhile to carry information about
6311
     every variant in the GDB source tree.
6312
 
6313
   * When GDB does support the architecture of the embedded system at
6314
     hand, the task of finding the correct architecture name to give the
6315
     `set architecture' command can be error-prone.
6316
 
6317
   To address these problems, the GDB remote protocol allows a target
6318
system to not only identify itself to GDB, but to actually describe its
6319
own features.  This lets GDB support processor variants it has never
6320
seen before -- to the extent that the descriptions are accurate, and
6321
that GDB understands them.
6322
 
6323
   GDB must be linked with the Expat library to support XML target
6324
descriptions.  *Note Expat::.
6325
 
6326
* Menu:
6327
 
6328
* Retrieving Descriptions::         How descriptions are fetched from a target.
6329
* Target Description Format::       The contents of a target description.
6330
* Predefined Target Types::         Standard types available for target
6331
                                    descriptions.
6332
* Standard Target Features::        Features GDB knows about.
6333
 
6334

6335
File: gdb.info,  Node: Retrieving Descriptions,  Next: Target Description Format,  Up: Target Descriptions
6336
 
6337
G.1 Retrieving Descriptions
6338
===========================
6339
 
6340
Target descriptions can be read from the target automatically, or
6341
specified by the user manually.  The default behavior is to read the
6342
description from the target.  GDB retrieves it via the remote protocol
6343
using `qXfer' requests (*note qXfer: General Query Packets.).  The
6344
ANNEX in the `qXfer' packet will be `target.xml'.  The contents of the
6345
`target.xml' annex are an XML document, of the form described in *Note
6346
Target Description Format::.
6347
 
6348
   Alternatively, you can specify a file to read for the target
6349
description.  If a file is set, the target will not be queried.  The
6350
commands to specify a file are:
6351
 
6352
`set tdesc filename PATH'
6353
     Read the target description from PATH.
6354
 
6355
`unset tdesc filename'
6356
     Do not read the XML target description from a file.  GDB will use
6357
     the description supplied by the current target.
6358
 
6359
`show tdesc filename'
6360
     Show the filename to read for a target description, if any.
6361
 
6362

6363
File: gdb.info,  Node: Target Description Format,  Next: Predefined Target Types,  Prev: Retrieving Descriptions,  Up: Target Descriptions
6364
 
6365
G.2 Target Description Format
6366
=============================
6367
 
6368
A target description annex is an XML (http://www.w3.org/XML/) document
6369
which complies with the Document Type Definition provided in the GDB
6370
sources in `gdb/features/gdb-target.dtd'.  This means you can use
6371
generally available tools like `xmllint' to check that your feature
6372
descriptions are well-formed and valid.  However, to help people
6373
unfamiliar with XML write descriptions for their targets, we also
6374
describe the grammar here.
6375
 
6376
   Target descriptions can identify the architecture of the remote
6377
target and (for some architectures) provide information about custom
6378
register sets.  They can also identify the OS ABI of the remote target.
6379
GDB can use this information to autoconfigure for your target, or to
6380
warn you if you connect to an unsupported target.
6381
 
6382
   Here is a simple target description:
6383
 
6384
     
6385
       i386:x86-64
6386
     
6387
 
6388
This minimal description only says that the target uses the x86-64
6389
architecture.
6390
 
6391
   A target description has the following overall form, with [ ] marking
6392
optional elements and ... marking repeatable elements.  The elements
6393
are explained further below.
6394
 
6395
     
6396
     
6397
     
6398
       [ARCHITECTURE]
6399
       [OSABI]
6400
       [COMPATIBLE]
6401
       [FEATURE...]
6402
     
6403
 
6404
The description is generally insensitive to whitespace and line breaks,
6405
under the usual common-sense rules.  The XML version declaration and
6406
document type declaration can generally be omitted (GDB does not
6407
require them), but specifying them may be useful for XML validation
6408
tools.  The `version' attribute for `' may also be omitted, but
6409
we recommend including it; if future versions of GDB use an incompatible
6410
revision of `gdb-target.dtd', they will detect and report the version
6411
mismatch.
6412
 
6413
G.2.1 Inclusion
6414
---------------
6415
 
6416
It can sometimes be valuable to split a target description up into
6417
several different annexes, either for organizational purposes, or to
6418
share files between different possible target descriptions.  You can
6419
divide a description into multiple files by replacing any element of
6420
the target description with an inclusion directive of the form:
6421
 
6422
     
6423
 
6424
When GDB encounters an element of this form, it will retrieve the named
6425
XML DOCUMENT, and replace the inclusion directive with the contents of
6426
that document.  If the current description was read using `qXfer', then
6427
so will be the included document; DOCUMENT will be interpreted as the
6428
name of an annex.  If the current description was read from a file, GDB
6429
will look for DOCUMENT as a file in the same directory where it found
6430
the original description.
6431
 
6432
G.2.2 Architecture
6433
------------------
6434
 
6435
An `' element has this form:
6436
 
6437
       ARCH
6438
 
6439
   ARCH is one of the architectures from the set accepted by `set
6440
architecture' (*note Specifying a Debugging Target: Targets.).
6441
 
6442
G.2.3 OS ABI
6443
------------
6444
 
6445
This optional field was introduced in GDB version 7.0.  Previous
6446
versions of GDB ignore it.
6447
 
6448
   An `' element has this form:
6449
 
6450
       ABI-NAME
6451
 
6452
   ABI-NAME is an OS ABI name from the same selection accepted by
6453
`set osabi' (*note Configuring the Current ABI: ABI.).
6454
 
6455
G.2.4 Compatible Architecture
6456
-----------------------------
6457
 
6458
This optional field was introduced in GDB version 7.0.  Previous
6459
versions of GDB ignore it.
6460
 
6461
   A `' element has this form:
6462
 
6463
       ARCH
6464
 
6465
   ARCH is one of the architectures from the set accepted by `set
6466
architecture' (*note Specifying a Debugging Target: Targets.).
6467
 
6468
   A `' element is used to specify that the target is able
6469
to run binaries in some other than the main target architecture given
6470
by the `' element.  For example, on the Cell Broadband
6471
Engine, the main architecture is `powerpc:common' or
6472
`powerpc:common64', but the system is able to run binaries in the `spu'
6473
architecture as well.  The way to describe this capability with
6474
`' is as follows:
6475
 
6476
       powerpc:common
6477
       spu
6478
 
6479
G.2.5 Features
6480
--------------
6481
 
6482
Each `' describes some logical portion of the target system.
6483
Features are currently used to describe available CPU registers and the
6484
types of their contents.  A `' element has this form:
6485
 
6486
     
6487
       [TYPE...]
6488
       REG...
6489
     
6490
 
6491
Each feature's name should be unique within the description.  The name
6492
of a feature does not matter unless GDB has some special knowledge of
6493
the contents of that feature; if it does, the feature should have its
6494
standard name.  *Note Standard Target Features::.
6495
 
6496
G.2.6 Types
6497
-----------
6498
 
6499
Any register's value is a collection of bits which GDB must interpret.
6500
The default interpretation is a two's complement integer, but other
6501
types can be requested by name in the register description.  Some
6502
predefined types are provided by GDB (*note Predefined Target Types::),
6503
and the description can define additional composite types.
6504
 
6505
   Each type element must have an `id' attribute, which gives a unique
6506
(within the containing `') name to the type.  Types must be
6507
defined before they are used.
6508
 
6509
   Some targets offer vector registers, which can be treated as arrays
6510
of scalar elements.  These types are written as `' elements,
6511
specifying the array element type, TYPE, and the number of elements,
6512
COUNT:
6513
 
6514
     
6515
 
6516
   If a register's value is usefully viewed in multiple ways, define it
6517
with a union type containing the useful representations.  The `'
6518
element contains one or more `' elements, each of which has a
6519
NAME and a TYPE:
6520
 
6521
     
6522
       
6523
       ...
6524
     
6525
 
6526
G.2.7 Registers
6527
---------------
6528
 
6529
Each register is represented as an element with this form:
6530
 
6531
     
6532
          bitsize="SIZE"
6533
          [regnum="NUM"]
6534
          [save-restore="SAVE-RESTORE"]
6535
          [type="TYPE"]
6536
          [group="GROUP"]/>
6537
 
6538
The components are as follows:
6539
 
6540
NAME
6541
     The register's name; it must be unique within the target
6542
     description.
6543
 
6544
BITSIZE
6545
     The register's size, in bits.
6546
 
6547
REGNUM
6548
     The register's number.  If omitted, a register's number is one
6549
     greater than that of the previous register (either in the current
6550
     feature or in a preceeding feature); the first register in the
6551
     target description defaults to zero.  This register number is used
6552
     to read or write the register; e.g. it is used in the remote `p'
6553
     and `P' packets, and registers appear in the `g' and `G' packets
6554
     in order of increasing register number.
6555
 
6556
SAVE-RESTORE
6557
     Whether the register should be preserved across inferior function
6558
     calls; this must be either `yes' or `no'.  The default is `yes',
6559
     which is appropriate for most registers except for some system
6560
     control registers; this is not related to the target's ABI.
6561
 
6562
TYPE
6563
     The type of the register.  TYPE may be a predefined type, a type
6564
     defined in the current feature, or one of the special types `int'
6565
     and `float'.  `int' is an integer type of the correct size for
6566
     BITSIZE, and `float' is a floating point type (in the
6567
     architecture's normal floating point format) of the correct size
6568
     for BITSIZE.  The default is `int'.
6569
 
6570
GROUP
6571
     The register group to which this register belongs.  GROUP must be
6572
     either `general', `float', or `vector'.  If no GROUP is specified,
6573
     GDB will not display the register in `info registers'.
6574
 
6575
 
6576

6577
File: gdb.info,  Node: Predefined Target Types,  Next: Standard Target Features,  Prev: Target Description Format,  Up: Target Descriptions
6578
 
6579
G.3 Predefined Target Types
6580
===========================
6581
 
6582
Type definitions in the self-description can build up composite types
6583
from basic building blocks, but can not define fundamental types.
6584
Instead, standard identifiers are provided by GDB for the fundamental
6585
types.  The currently supported types are:
6586
 
6587
`int8'
6588
`int16'
6589
`int32'
6590
`int64'
6591
`int128'
6592
     Signed integer types holding the specified number of bits.
6593
 
6594
`uint8'
6595
`uint16'
6596
`uint32'
6597
`uint64'
6598
`uint128'
6599
     Unsigned integer types holding the specified number of bits.
6600
 
6601
`code_ptr'
6602
`data_ptr'
6603
     Pointers to unspecified code and data.  The program counter and
6604
     any dedicated return address register may be marked as code
6605
     pointers; printing a code pointer converts it into a symbolic
6606
     address.  The stack pointer and any dedicated address registers
6607
     may be marked as data pointers.
6608
 
6609
`ieee_single'
6610
     Single precision IEEE floating point.
6611
 
6612
`ieee_double'
6613
     Double precision IEEE floating point.
6614
 
6615
`arm_fpa_ext'
6616
     The 12-byte extended precision format used by ARM FPA registers.
6617
 
6618
`i387_ext'
6619
     The 10-byte extended precision format used by x87 registers.
6620
 
6621
`i386_eflags'
6622
     32bit EFLAGS register used by x86.
6623
 
6624
`i386_mxcsr'
6625
     32bit MXCSR register used by x86.
6626
 
6627
 
6628

6629
File: gdb.info,  Node: Standard Target Features,  Prev: Predefined Target Types,  Up: Target Descriptions
6630
 
6631
G.4 Standard Target Features
6632
============================
6633
 
6634
A target description must contain either no registers or all the
6635
target's registers.  If the description contains no registers, then GDB
6636
will assume a default register layout, selected based on the
6637
architecture.  If the description contains any registers, the default
6638
layout will not be used; the standard registers must be described in
6639
the target description, in such a way that GDB can recognize them.
6640
 
6641
   This is accomplished by giving specific names to feature elements
6642
which contain standard registers.  GDB will look for features with
6643
those names and verify that they contain the expected registers; if any
6644
known feature is missing required registers, or if any required feature
6645
is missing, GDB will reject the target description.  You can add
6646
additional registers to any of the standard features -- GDB will
6647
display them just as if they were added to an unrecognized feature.
6648
 
6649
   This section lists the known features and their expected contents.
6650
Sample XML documents for these features are included in the GDB source
6651
tree, in the directory `gdb/features'.
6652
 
6653
   Names recognized by GDB should include the name of the company or
6654
organization which selected the name, and the overall architecture to
6655
which the feature applies; so e.g. the feature containing ARM core
6656
registers is named `org.gnu.gdb.arm.core'.
6657
 
6658
   The names of registers are not case sensitive for the purpose of
6659
recognizing standard features, but GDB will only display registers
6660
using the capitalization used in the description.
6661
 
6662
* Menu:
6663
 
6664
* ARM Features::
6665
* i386 Features::
6666
* MIPS Features::
6667
* M68K Features::
6668
* PowerPC Features::
6669
 
6670

6671
File: gdb.info,  Node: ARM Features,  Next: i386 Features,  Up: Standard Target Features
6672
 
6673
G.4.1 ARM Features
6674
------------------
6675
 
6676
The `org.gnu.gdb.arm.core' feature is required for ARM targets.  It
6677
should contain registers `r0' through `r13', `sp', `lr', `pc', and
6678
`cpsr'.
6679
 
6680
   The `org.gnu.gdb.arm.fpa' feature is optional.  If present, it
6681
should contain registers `f0' through `f7' and `fps'.
6682
 
6683
   The `org.gnu.gdb.xscale.iwmmxt' feature is optional.  If present, it
6684
should contain at least registers `wR0' through `wR15' and `wCGR0'
6685
through `wCGR3'.  The `wCID', `wCon', `wCSSF', and `wCASF' registers
6686
are optional.
6687
 
6688
   The `org.gnu.gdb.arm.vfp' feature is optional.  If present, it
6689
should contain at least registers `d0' through `d15'.  If they are
6690
present, `d16' through `d31' should also be included.  GDB will
6691
synthesize the single-precision registers from halves of the
6692
double-precision registers.
6693
 
6694
   The `org.gnu.gdb.arm.neon' feature is optional.  It does not need to
6695
contain registers; it instructs GDB to display the VFP double-precision
6696
registers as vectors and to synthesize the quad-precision registers
6697
from pairs of double-precision registers.  If this feature is present,
6698
`org.gnu.gdb.arm.vfp' must also be present and include 32
6699
double-precision registers.
6700
 
6701

6702
File: gdb.info,  Node: i386 Features,  Next: MIPS Features,  Prev: ARM Features,  Up: Standard Target Features
6703
 
6704
G.4.2 i386 Features
6705
-------------------
6706
 
6707
The `org.gnu.gdb.i386.core' feature is required for i386/amd64 targets.
6708
It should describe the following registers:
6709
 
6710
   - `eax' through `edi' plus `eip' for i386
6711
 
6712
   - `rax' through `r15' plus `rip' for amd64
6713
 
6714
   - `eflags', `cs', `ss', `ds', `es', `fs', `gs'
6715
 
6716
   - `st0' through `st7'
6717
 
6718
   - `fctrl', `fstat', `ftag', `fiseg', `fioff', `foseg', `fooff' and
6719
     `fop'
6720
 
6721
   The register sets may be different, depending on the target.
6722
 
6723
   The `org.gnu.gdb.i386.sse' feature is required.  It should describe
6724
registers:
6725
 
6726
   - `xmm0' through `xmm7' for i386
6727
 
6728
   - `xmm0' through `xmm15' for amd64
6729
 
6730
   - `mxcsr'
6731
 
6732
   The `org.gnu.gdb.i386.linux' feature is optional.  It should
6733
describe a single register, `orig_eax'.
6734
 
6735

6736
File: gdb.info,  Node: MIPS Features,  Next: M68K Features,  Prev: i386 Features,  Up: Standard Target Features
6737
 
6738
G.4.3 MIPS Features
6739
-------------------
6740
 
6741
The `org.gnu.gdb.mips.cpu' feature is required for MIPS targets.  It
6742
should contain registers `r0' through `r31', `lo', `hi', and `pc'.
6743
They may be 32-bit or 64-bit depending on the target.
6744
 
6745
   The `org.gnu.gdb.mips.cp0' feature is also required.  It should
6746
contain at least the `status', `badvaddr', and `cause' registers.  They
6747
may be 32-bit or 64-bit depending on the target.
6748
 
6749
   The `org.gnu.gdb.mips.fpu' feature is currently required, though it
6750
may be optional in a future version of GDB.  It should contain
6751
registers `f0' through `f31', `fcsr', and `fir'.  They may be 32-bit or
6752
64-bit depending on the target.
6753
 
6754
   The `org.gnu.gdb.mips.linux' feature is optional.  It should contain
6755
a single register, `restart', which is used by the Linux kernel to
6756
control restartable syscalls.
6757
 
6758

6759
File: gdb.info,  Node: M68K Features,  Next: PowerPC Features,  Prev: MIPS Features,  Up: Standard Target Features
6760
 
6761
G.4.4 M68K Features
6762
-------------------
6763
 
6764
``org.gnu.gdb.m68k.core''
6765
``org.gnu.gdb.coldfire.core''
6766
``org.gnu.gdb.fido.core''
6767
     One of those features must be always present.  The feature that is
6768
     present determines which flavor of m68k is used.  The feature that
6769
     is present should contain registers `d0' through `d7', `a0'
6770
     through `a5', `fp', `sp', `ps' and `pc'.
6771
 
6772
``org.gnu.gdb.coldfire.fp''
6773
     This feature is optional.  If present, it should contain registers
6774
     `fp0' through `fp7', `fpcontrol', `fpstatus' and `fpiaddr'.
6775
 
6776

6777
File: gdb.info,  Node: PowerPC Features,  Prev: M68K Features,  Up: Standard Target Features
6778
 
6779
G.4.5 PowerPC Features
6780
----------------------
6781
 
6782
The `org.gnu.gdb.power.core' feature is required for PowerPC targets.
6783
It should contain registers `r0' through `r31', `pc', `msr', `cr',
6784
`lr', `ctr', and `xer'.  They may be 32-bit or 64-bit depending on the
6785
target.
6786
 
6787
   The `org.gnu.gdb.power.fpu' feature is optional.  It should contain
6788
registers `f0' through `f31' and `fpscr'.
6789
 
6790
   The `org.gnu.gdb.power.altivec' feature is optional.  It should
6791
contain registers `vr0' through `vr31', `vscr', and `vrsave'.
6792
 
6793
   The `org.gnu.gdb.power.vsx' feature is optional.  It should contain
6794
registers `vs0h' through `vs31h'.  GDB will combine these registers
6795
with the floating point registers (`f0' through `f31') and the altivec
6796
registers (`vr0' through `vr31') to present the 128-bit wide registers
6797
`vs0' through `vs63', the set of vector registers for POWER7.
6798
 
6799
   The `org.gnu.gdb.power.spe' feature is optional.  It should contain
6800
registers `ev0h' through `ev31h', `acc', and `spefscr'.  SPE targets
6801
should provide 32-bit registers in `org.gnu.gdb.power.core' and provide
6802
the upper halves in `ev0h' through `ev31h'.  GDB will combine these to
6803
present registers `ev0' through `ev31' to the user.
6804
 
6805

6806
File: gdb.info,  Node: Operating System Information,  Next: Trace File Format,  Prev: Target Descriptions,  Up: Top
6807
 
6808
Appendix H Operating System Information
6809
***************************************
6810
 
6811
* Menu:
6812
 
6813
* Process list::
6814
 
6815
   Users of GDB often wish to obtain information about the state of the
6816
operating system running on the target--for example the list of
6817
processes, or the list of open files.  This section describes the
6818
mechanism that makes it possible.  This mechanism is similar to the
6819
target features mechanism (*note Target Descriptions::), but focuses on
6820
a different aspect of target.
6821
 
6822
   Operating system information is retrived from the target via the
6823
remote protocol, using `qXfer' requests (*note qXfer osdata read::).
6824
The object name in the request should be `osdata', and the ANNEX
6825
identifies the data to be fetched.
6826
 
6827

6828
File: gdb.info,  Node: Process list,  Up: Operating System Information
6829
 
6830
H.1 Process list
6831
================
6832
 
6833
When requesting the process list, the ANNEX field in the `qXfer'
6834
request should be `processes'.  The returned data is an XML document.
6835
The formal syntax of this document is defined in
6836
`gdb/features/osdata.dtd'.
6837
 
6838
   An example document is:
6839
 
6840
     
6841
     
6842
     
6843
       
6844
         1
6845
         root
6846
         /sbin/init
6847
         1,2,3
6848
       
6849
     
6850
 
6851
   Each item should include a column whose name is `pid'.  The value of
6852
that column should identify the process on the target.  The `user' and
6853
`command' columns are optional, and will be displayed by GDB.  The
6854
`cores' column, if present, should contain a comma-separated list of
6855
cores that this process is running on.  Target may provide additional
6856
columns, which GDB currently ignores.
6857
 
6858

6859
File: gdb.info,  Node: Copying,  Next: GNU Free Documentation License,  Prev: Trace File Format,  Up: Top
6860
 
6861
Appendix I GNU GENERAL PUBLIC LICENSE
6862
*************************************
6863
 
6864
                        Version 3, 29 June 2007
6865
 
6866
     Copyright (C) 2007 Free Software Foundation, Inc. `http://fsf.org/'
6867
 
6868
     Everyone is permitted to copy and distribute verbatim copies of this
6869
     license document, but changing it is not allowed.
6870
 
6871
Preamble
6872
========
6873
 
6874
The GNU General Public License is a free, copyleft license for software
6875
and other kinds of works.
6876
 
6877
   The licenses for most software and other practical works are designed
6878
to take away your freedom to share and change the works.  By contrast,
6879
the GNU General Public License is intended to guarantee your freedom to
6880
share and change all versions of a program--to make sure it remains
6881
free software for all its users.  We, the Free Software Foundation, use
6882
the GNU General Public License for most of our software; it applies
6883
also to any other work released this way by its authors.  You can apply
6884
it to your programs, too.
6885
 
6886
   When we speak of free software, we are referring to freedom, not
6887
price.  Our General Public Licenses are designed to make sure that you
6888
have the freedom to distribute copies of free software (and charge for
6889
them if you wish), that you receive source code or can get it if you
6890
want it, that you can change the software or use pieces of it in new
6891
free programs, and that you know you can do these things.
6892
 
6893
   To protect your rights, we need to prevent others from denying you
6894
these rights or asking you to surrender the rights.  Therefore, you
6895
have certain responsibilities if you distribute copies of the software,
6896
or if you modify it: responsibilities to respect the freedom of others.
6897
 
6898
   For example, if you distribute copies of such a program, whether
6899
gratis or for a fee, you must pass on to the recipients the same
6900
freedoms that you received.  You must make sure that they, too, receive
6901
or can get the source code.  And you must show them these terms so they
6902
know their rights.
6903
 
6904
   Developers that use the GNU GPL protect your rights with two steps:
6905
(1) assert copyright on the software, and (2) offer you this License
6906
giving you legal permission to copy, distribute and/or modify it.
6907
 
6908
   For the developers' and authors' protection, the GPL clearly explains
6909
that there is no warranty for this free software.  For both users' and
6910
authors' sake, the GPL requires that modified versions be marked as
6911
changed, so that their problems will not be attributed erroneously to
6912
authors of previous versions.
6913
 
6914
   Some devices are designed to deny users access to install or run
6915
modified versions of the software inside them, although the
6916
manufacturer can do so.  This is fundamentally incompatible with the
6917
aim of protecting users' freedom to change the software.  The
6918
systematic pattern of such abuse occurs in the area of products for
6919
individuals to use, which is precisely where it is most unacceptable.
6920
Therefore, we have designed this version of the GPL to prohibit the
6921
practice for those products.  If such problems arise substantially in
6922
other domains, we stand ready to extend this provision to those domains
6923
in future versions of the GPL, as needed to protect the freedom of
6924
users.
6925
 
6926
   Finally, every program is threatened constantly by software patents.
6927
States should not allow patents to restrict development and use of
6928
software on general-purpose computers, but in those that do, we wish to
6929
avoid the special danger that patents applied to a free program could
6930
make it effectively proprietary.  To prevent this, the GPL assures that
6931
patents cannot be used to render the program non-free.
6932
 
6933
   The precise terms and conditions for copying, distribution and
6934
modification follow.
6935
 
6936
TERMS AND CONDITIONS
6937
====================
6938
 
6939
  0. Definitions.
6940
 
6941
     "This License" refers to version 3 of the GNU General Public
6942
     License.
6943
 
6944
     "Copyright" also means copyright-like laws that apply to other
6945
     kinds of works, such as semiconductor masks.
6946
 
6947
     "The Program" refers to any copyrightable work licensed under this
6948
     License.  Each licensee is addressed as "you".  "Licensees" and
6949
     "recipients" may be individuals or organizations.
6950
 
6951
     To "modify" a work means to copy from or adapt all or part of the
6952
     work in a fashion requiring copyright permission, other than the
6953
     making of an exact copy.  The resulting work is called a "modified
6954
     version" of the earlier work or a work "based on" the earlier work.
6955
 
6956
     A "covered work" means either the unmodified Program or a work
6957
     based on the Program.
6958
 
6959
     To "propagate" a work means to do anything with it that, without
6960
     permission, would make you directly or secondarily liable for
6961
     infringement under applicable copyright law, except executing it
6962
     on a computer or modifying a private copy.  Propagation includes
6963
     copying, distribution (with or without modification), making
6964
     available to the public, and in some countries other activities as
6965
     well.
6966
 
6967
     To "convey" a work means any kind of propagation that enables other
6968
     parties to make or receive copies.  Mere interaction with a user
6969
     through a computer network, with no transfer of a copy, is not
6970
     conveying.
6971
 
6972
     An interactive user interface displays "Appropriate Legal Notices"
6973
     to the extent that it includes a convenient and prominently visible
6974
     feature that (1) displays an appropriate copyright notice, and (2)
6975
     tells the user that there is no warranty for the work (except to
6976
     the extent that warranties are provided), that licensees may
6977
     convey the work under this License, and how to view a copy of this
6978
     License.  If the interface presents a list of user commands or
6979
     options, such as a menu, a prominent item in the list meets this
6980
     criterion.
6981
 
6982
  1. Source Code.
6983
 
6984
     The "source code" for a work means the preferred form of the work
6985
     for making modifications to it.  "Object code" means any
6986
     non-source form of a work.
6987
 
6988
     A "Standard Interface" means an interface that either is an
6989
     official standard defined by a recognized standards body, or, in
6990
     the case of interfaces specified for a particular programming
6991
     language, one that is widely used among developers working in that
6992
     language.
6993
 
6994
     The "System Libraries" of an executable work include anything,
6995
     other than the work as a whole, that (a) is included in the normal
6996
     form of packaging a Major Component, but which is not part of that
6997
     Major Component, and (b) serves only to enable use of the work
6998
     with that Major Component, or to implement a Standard Interface
6999
     for which an implementation is available to the public in source
7000
     code form.  A "Major Component", in this context, means a major
7001
     essential component (kernel, window system, and so on) of the
7002
     specific operating system (if any) on which the executable work
7003
     runs, or a compiler used to produce the work, or an object code
7004
     interpreter used to run it.
7005
 
7006
     The "Corresponding Source" for a work in object code form means all
7007
     the source code needed to generate, install, and (for an executable
7008
     work) run the object code and to modify the work, including
7009
     scripts to control those activities.  However, it does not include
7010
     the work's System Libraries, or general-purpose tools or generally
7011
     available free programs which are used unmodified in performing
7012
     those activities but which are not part of the work.  For example,
7013
     Corresponding Source includes interface definition files
7014
     associated with source files for the work, and the source code for
7015
     shared libraries and dynamically linked subprograms that the work
7016
     is specifically designed to require, such as by intimate data
7017
     communication or control flow between those subprograms and other
7018
     parts of the work.
7019
 
7020
     The Corresponding Source need not include anything that users can
7021
     regenerate automatically from other parts of the Corresponding
7022
     Source.
7023
 
7024
     The Corresponding Source for a work in source code form is that
7025
     same work.
7026
 
7027
  2. Basic Permissions.
7028
 
7029
     All rights granted under this License are granted for the term of
7030
     copyright on the Program, and are irrevocable provided the stated
7031
     conditions are met.  This License explicitly affirms your unlimited
7032
     permission to run the unmodified Program.  The output from running
7033
     a covered work is covered by this License only if the output,
7034
     given its content, constitutes a covered work.  This License
7035
     acknowledges your rights of fair use or other equivalent, as
7036
     provided by copyright law.
7037
 
7038
     You may make, run and propagate covered works that you do not
7039
     convey, without conditions so long as your license otherwise
7040
     remains in force.  You may convey covered works to others for the
7041
     sole purpose of having them make modifications exclusively for
7042
     you, or provide you with facilities for running those works,
7043
     provided that you comply with the terms of this License in
7044
     conveying all material for which you do not control copyright.
7045
     Those thus making or running the covered works for you must do so
7046
     exclusively on your behalf, under your direction and control, on
7047
     terms that prohibit them from making any copies of your
7048
     copyrighted material outside their relationship with you.
7049
 
7050
     Conveying under any other circumstances is permitted solely under
7051
     the conditions stated below.  Sublicensing is not allowed; section
7052
     10 makes it unnecessary.
7053
 
7054
  3. Protecting Users' Legal Rights From Anti-Circumvention Law.
7055
 
7056
     No covered work shall be deemed part of an effective technological
7057
     measure under any applicable law fulfilling obligations under
7058
     article 11 of the WIPO copyright treaty adopted on 20 December
7059
     1996, or similar laws prohibiting or restricting circumvention of
7060
     such measures.
7061
 
7062
     When you convey a covered work, you waive any legal power to forbid
7063
     circumvention of technological measures to the extent such
7064
     circumvention is effected by exercising rights under this License
7065
     with respect to the covered work, and you disclaim any intention
7066
     to limit operation or modification of the work as a means of
7067
     enforcing, against the work's users, your or third parties' legal
7068
     rights to forbid circumvention of technological measures.
7069
 
7070
  4. Conveying Verbatim Copies.
7071
 
7072
     You may convey verbatim copies of the Program's source code as you
7073
     receive it, in any medium, provided that you conspicuously and
7074
     appropriately publish on each copy an appropriate copyright notice;
7075
     keep intact all notices stating that this License and any
7076
     non-permissive terms added in accord with section 7 apply to the
7077
     code; keep intact all notices of the absence of any warranty; and
7078
     give all recipients a copy of this License along with the Program.
7079
 
7080
     You may charge any price or no price for each copy that you convey,
7081
     and you may offer support or warranty protection for a fee.
7082
 
7083
  5. Conveying Modified Source Versions.
7084
 
7085
     You may convey a work based on the Program, or the modifications to
7086
     produce it from the Program, in the form of source code under the
7087
     terms of section 4, provided that you also meet all of these
7088
     conditions:
7089
 
7090
       a. The work must carry prominent notices stating that you
7091
          modified it, and giving a relevant date.
7092
 
7093
       b. The work must carry prominent notices stating that it is
7094
          released under this License and any conditions added under
7095
          section 7.  This requirement modifies the requirement in
7096
          section 4 to "keep intact all notices".
7097
 
7098
       c. You must license the entire work, as a whole, under this
7099
          License to anyone who comes into possession of a copy.  This
7100
          License will therefore apply, along with any applicable
7101
          section 7 additional terms, to the whole of the work, and all
7102
          its parts, regardless of how they are packaged.  This License
7103
          gives no permission to license the work in any other way, but
7104
          it does not invalidate such permission if you have separately
7105
          received it.
7106
 
7107
       d. If the work has interactive user interfaces, each must display
7108
          Appropriate Legal Notices; however, if the Program has
7109
          interactive interfaces that do not display Appropriate Legal
7110
          Notices, your work need not make them do so.
7111
 
7112
     A compilation of a covered work with other separate and independent
7113
     works, which are not by their nature extensions of the covered
7114
     work, and which are not combined with it such as to form a larger
7115
     program, in or on a volume of a storage or distribution medium, is
7116
     called an "aggregate" if the compilation and its resulting
7117
     copyright are not used to limit the access or legal rights of the
7118
     compilation's users beyond what the individual works permit.
7119
     Inclusion of a covered work in an aggregate does not cause this
7120
     License to apply to the other parts of the aggregate.
7121
 
7122
  6. Conveying Non-Source Forms.
7123
 
7124
     You may convey a covered work in object code form under the terms
7125
     of sections 4 and 5, provided that you also convey the
7126
     machine-readable Corresponding Source under the terms of this
7127
     License, in one of these ways:
7128
 
7129
       a. Convey the object code in, or embodied in, a physical product
7130
          (including a physical distribution medium), accompanied by the
7131
          Corresponding Source fixed on a durable physical medium
7132
          customarily used for software interchange.
7133
 
7134
       b. Convey the object code in, or embodied in, a physical product
7135
          (including a physical distribution medium), accompanied by a
7136
          written offer, valid for at least three years and valid for
7137
          as long as you offer spare parts or customer support for that
7138
          product model, to give anyone who possesses the object code
7139
          either (1) a copy of the Corresponding Source for all the
7140
          software in the product that is covered by this License, on a
7141
          durable physical medium customarily used for software
7142
          interchange, for a price no more than your reasonable cost of
7143
          physically performing this conveying of source, or (2) access
7144
          to copy the Corresponding Source from a network server at no
7145
          charge.
7146
 
7147
       c. Convey individual copies of the object code with a copy of
7148
          the written offer to provide the Corresponding Source.  This
7149
          alternative is allowed only occasionally and noncommercially,
7150
          and only if you received the object code with such an offer,
7151
          in accord with subsection 6b.
7152
 
7153
       d. Convey the object code by offering access from a designated
7154
          place (gratis or for a charge), and offer equivalent access
7155
          to the Corresponding Source in the same way through the same
7156
          place at no further charge.  You need not require recipients
7157
          to copy the Corresponding Source along with the object code.
7158
          If the place to copy the object code is a network server, the
7159
          Corresponding Source may be on a different server (operated
7160
          by you or a third party) that supports equivalent copying
7161
          facilities, provided you maintain clear directions next to
7162
          the object code saying where to find the Corresponding Source.
7163
          Regardless of what server hosts the Corresponding Source, you
7164
          remain obligated to ensure that it is available for as long
7165
          as needed to satisfy these requirements.
7166
 
7167
       e. Convey the object code using peer-to-peer transmission,
7168
          provided you inform other peers where the object code and
7169
          Corresponding Source of the work are being offered to the
7170
          general public at no charge under subsection 6d.
7171
 
7172
 
7173
     A separable portion of the object code, whose source code is
7174
     excluded from the Corresponding Source as a System Library, need
7175
     not be included in conveying the object code work.
7176
 
7177
     A "User Product" is either (1) a "consumer product", which means
7178
     any tangible personal property which is normally used for personal,
7179
     family, or household purposes, or (2) anything designed or sold for
7180
     incorporation into a dwelling.  In determining whether a product
7181
     is a consumer product, doubtful cases shall be resolved in favor of
7182
     coverage.  For a particular product received by a particular user,
7183
     "normally used" refers to a typical or common use of that class of
7184
     product, regardless of the status of the particular user or of the
7185
     way in which the particular user actually uses, or expects or is
7186
     expected to use, the product.  A product is a consumer product
7187
     regardless of whether the product has substantial commercial,
7188
     industrial or non-consumer uses, unless such uses represent the
7189
     only significant mode of use of the product.
7190
 
7191
     "Installation Information" for a User Product means any methods,
7192
     procedures, authorization keys, or other information required to
7193
     install and execute modified versions of a covered work in that
7194
     User Product from a modified version of its Corresponding Source.
7195
     The information must suffice to ensure that the continued
7196
     functioning of the modified object code is in no case prevented or
7197
     interfered with solely because modification has been made.
7198
 
7199
     If you convey an object code work under this section in, or with,
7200
     or specifically for use in, a User Product, and the conveying
7201
     occurs as part of a transaction in which the right of possession
7202
     and use of the User Product is transferred to the recipient in
7203
     perpetuity or for a fixed term (regardless of how the transaction
7204
     is characterized), the Corresponding Source conveyed under this
7205
     section must be accompanied by the Installation Information.  But
7206
     this requirement does not apply if neither you nor any third party
7207
     retains the ability to install modified object code on the User
7208
     Product (for example, the work has been installed in ROM).
7209
 
7210
     The requirement to provide Installation Information does not
7211
     include a requirement to continue to provide support service,
7212
     warranty, or updates for a work that has been modified or
7213
     installed by the recipient, or for the User Product in which it
7214
     has been modified or installed.  Access to a network may be denied
7215
     when the modification itself materially and adversely affects the
7216
     operation of the network or violates the rules and protocols for
7217
     communication across the network.
7218
 
7219
     Corresponding Source conveyed, and Installation Information
7220
     provided, in accord with this section must be in a format that is
7221
     publicly documented (and with an implementation available to the
7222
     public in source code form), and must require no special password
7223
     or key for unpacking, reading or copying.
7224
 
7225
  7. Additional Terms.
7226
 
7227
     "Additional permissions" are terms that supplement the terms of
7228
     this License by making exceptions from one or more of its
7229
     conditions.  Additional permissions that are applicable to the
7230
     entire Program shall be treated as though they were included in
7231
     this License, to the extent that they are valid under applicable
7232
     law.  If additional permissions apply only to part of the Program,
7233
     that part may be used separately under those permissions, but the
7234
     entire Program remains governed by this License without regard to
7235
     the additional permissions.
7236
 
7237
     When you convey a copy of a covered work, you may at your option
7238
     remove any additional permissions from that copy, or from any part
7239
     of it.  (Additional permissions may be written to require their own
7240
     removal in certain cases when you modify the work.)  You may place
7241
     additional permissions on material, added by you to a covered work,
7242
     for which you have or can give appropriate copyright permission.
7243
 
7244
     Notwithstanding any other provision of this License, for material
7245
     you add to a covered work, you may (if authorized by the copyright
7246
     holders of that material) supplement the terms of this License
7247
     with terms:
7248
 
7249
       a. Disclaiming warranty or limiting liability differently from
7250
          the terms of sections 15 and 16 of this License; or
7251
 
7252
       b. Requiring preservation of specified reasonable legal notices
7253
          or author attributions in that material or in the Appropriate
7254
          Legal Notices displayed by works containing it; or
7255
 
7256
       c. Prohibiting misrepresentation of the origin of that material,
7257
          or requiring that modified versions of such material be
7258
          marked in reasonable ways as different from the original
7259
          version; or
7260
 
7261
       d. Limiting the use for publicity purposes of names of licensors
7262
          or authors of the material; or
7263
 
7264
       e. Declining to grant rights under trademark law for use of some
7265
          trade names, trademarks, or service marks; or
7266
 
7267
       f. Requiring indemnification of licensors and authors of that
7268
          material by anyone who conveys the material (or modified
7269
          versions of it) with contractual assumptions of liability to
7270
          the recipient, for any liability that these contractual
7271
          assumptions directly impose on those licensors and authors.
7272
 
7273
     All other non-permissive additional terms are considered "further
7274
     restrictions" within the meaning of section 10.  If the Program as
7275
     you received it, or any part of it, contains a notice stating that
7276
     it is governed by this License along with a term that is a further
7277
     restriction, you may remove that term.  If a license document
7278
     contains a further restriction but permits relicensing or
7279
     conveying under this License, you may add to a covered work
7280
     material governed by the terms of that license document, provided
7281
     that the further restriction does not survive such relicensing or
7282
     conveying.
7283
 
7284
     If you add terms to a covered work in accord with this section, you
7285
     must place, in the relevant source files, a statement of the
7286
     additional terms that apply to those files, or a notice indicating
7287
     where to find the applicable terms.
7288
 
7289
     Additional terms, permissive or non-permissive, may be stated in
7290
     the form of a separately written license, or stated as exceptions;
7291
     the above requirements apply either way.
7292
 
7293
  8. Termination.
7294
 
7295
     You may not propagate or modify a covered work except as expressly
7296
     provided under this License.  Any attempt otherwise to propagate or
7297
     modify it is void, and will automatically terminate your rights
7298
     under this License (including any patent licenses granted under
7299
     the third paragraph of section 11).
7300
 
7301
     However, if you cease all violation of this License, then your
7302
     license from a particular copyright holder is reinstated (a)
7303
     provisionally, unless and until the copyright holder explicitly
7304
     and finally terminates your license, and (b) permanently, if the
7305
     copyright holder fails to notify you of the violation by some
7306
     reasonable means prior to 60 days after the cessation.
7307
 
7308
     Moreover, your license from a particular copyright holder is
7309
     reinstated permanently if the copyright holder notifies you of the
7310
     violation by some reasonable means, this is the first time you have
7311
     received notice of violation of this License (for any work) from
7312
     that copyright holder, and you cure the violation prior to 30 days
7313
     after your receipt of the notice.
7314
 
7315
     Termination of your rights under this section does not terminate
7316
     the licenses of parties who have received copies or rights from
7317
     you under this License.  If your rights have been terminated and
7318
     not permanently reinstated, you do not qualify to receive new
7319
     licenses for the same material under section 10.
7320
 
7321
  9. Acceptance Not Required for Having Copies.
7322
 
7323
     You are not required to accept this License in order to receive or
7324
     run a copy of the Program.  Ancillary propagation of a covered work
7325
     occurring solely as a consequence of using peer-to-peer
7326
     transmission to receive a copy likewise does not require
7327
     acceptance.  However, nothing other than this License grants you
7328
     permission to propagate or modify any covered work.  These actions
7329
     infringe copyright if you do not accept this License.  Therefore,
7330
     by modifying or propagating a covered work, you indicate your
7331
     acceptance of this License to do so.
7332
 
7333
 10. Automatic Licensing of Downstream Recipients.
7334
 
7335
     Each time you convey a covered work, the recipient automatically
7336
     receives a license from the original licensors, to run, modify and
7337
     propagate that work, subject to this License.  You are not
7338
     responsible for enforcing compliance by third parties with this
7339
     License.
7340
 
7341
     An "entity transaction" is a transaction transferring control of an
7342
     organization, or substantially all assets of one, or subdividing an
7343
     organization, or merging organizations.  If propagation of a
7344
     covered work results from an entity transaction, each party to that
7345
     transaction who receives a copy of the work also receives whatever
7346
     licenses to the work the party's predecessor in interest had or
7347
     could give under the previous paragraph, plus a right to
7348
     possession of the Corresponding Source of the work from the
7349
     predecessor in interest, if the predecessor has it or can get it
7350
     with reasonable efforts.
7351
 
7352
     You may not impose any further restrictions on the exercise of the
7353
     rights granted or affirmed under this License.  For example, you
7354
     may not impose a license fee, royalty, or other charge for
7355
     exercise of rights granted under this License, and you may not
7356
     initiate litigation (including a cross-claim or counterclaim in a
7357
     lawsuit) alleging that any patent claim is infringed by making,
7358
     using, selling, offering for sale, or importing the Program or any
7359
     portion of it.
7360
 
7361
 11. Patents.
7362
 
7363
     A "contributor" is a copyright holder who authorizes use under this
7364
     License of the Program or a work on which the Program is based.
7365
     The work thus licensed is called the contributor's "contributor
7366
     version".
7367
 
7368
     A contributor's "essential patent claims" are all patent claims
7369
     owned or controlled by the contributor, whether already acquired or
7370
     hereafter acquired, that would be infringed by some manner,
7371
     permitted by this License, of making, using, or selling its
7372
     contributor version, but do not include claims that would be
7373
     infringed only as a consequence of further modification of the
7374
     contributor version.  For purposes of this definition, "control"
7375
     includes the right to grant patent sublicenses in a manner
7376
     consistent with the requirements of this License.
7377
 
7378
     Each contributor grants you a non-exclusive, worldwide,
7379
     royalty-free patent license under the contributor's essential
7380
     patent claims, to make, use, sell, offer for sale, import and
7381
     otherwise run, modify and propagate the contents of its
7382
     contributor version.
7383
 
7384
     In the following three paragraphs, a "patent license" is any
7385
     express agreement or commitment, however denominated, not to
7386
     enforce a patent (such as an express permission to practice a
7387
     patent or covenant not to sue for patent infringement).  To
7388
     "grant" such a patent license to a party means to make such an
7389
     agreement or commitment not to enforce a patent against the party.
7390
 
7391
     If you convey a covered work, knowingly relying on a patent
7392
     license, and the Corresponding Source of the work is not available
7393
     for anyone to copy, free of charge and under the terms of this
7394
     License, through a publicly available network server or other
7395
     readily accessible means, then you must either (1) cause the
7396
     Corresponding Source to be so available, or (2) arrange to deprive
7397
     yourself of the benefit of the patent license for this particular
7398
     work, or (3) arrange, in a manner consistent with the requirements
7399
     of this License, to extend the patent license to downstream
7400
     recipients.  "Knowingly relying" means you have actual knowledge
7401
     that, but for the patent license, your conveying the covered work
7402
     in a country, or your recipient's use of the covered work in a
7403
     country, would infringe one or more identifiable patents in that
7404
     country that you have reason to believe are valid.
7405
 
7406
     If, pursuant to or in connection with a single transaction or
7407
     arrangement, you convey, or propagate by procuring conveyance of, a
7408
     covered work, and grant a patent license to some of the parties
7409
     receiving the covered work authorizing them to use, propagate,
7410
     modify or convey a specific copy of the covered work, then the
7411
     patent license you grant is automatically extended to all
7412
     recipients of the covered work and works based on it.
7413
 
7414
     A patent license is "discriminatory" if it does not include within
7415
     the scope of its coverage, prohibits the exercise of, or is
7416
     conditioned on the non-exercise of one or more of the rights that
7417
     are specifically granted under this License.  You may not convey a
7418
     covered work if you are a party to an arrangement with a third
7419
     party that is in the business of distributing software, under
7420
     which you make payment to the third party based on the extent of
7421
     your activity of conveying the work, and under which the third
7422
     party grants, to any of the parties who would receive the covered
7423
     work from you, a discriminatory patent license (a) in connection
7424
     with copies of the covered work conveyed by you (or copies made
7425
     from those copies), or (b) primarily for and in connection with
7426
     specific products or compilations that contain the covered work,
7427
     unless you entered into that arrangement, or that patent license
7428
     was granted, prior to 28 March 2007.
7429
 
7430
     Nothing in this License shall be construed as excluding or limiting
7431
     any implied license or other defenses to infringement that may
7432
     otherwise be available to you under applicable patent law.
7433
 
7434
 12. No Surrender of Others' Freedom.
7435
 
7436
     If conditions are imposed on you (whether by court order,
7437
     agreement or otherwise) that contradict the conditions of this
7438
     License, they do not excuse you from the conditions of this
7439
     License.  If you cannot convey a covered work so as to satisfy
7440
     simultaneously your obligations under this License and any other
7441
     pertinent obligations, then as a consequence you may not convey it
7442
     at all.  For example, if you agree to terms that obligate you to
7443
     collect a royalty for further conveying from those to whom you
7444
     convey the Program, the only way you could satisfy both those
7445
     terms and this License would be to refrain entirely from conveying
7446
     the Program.
7447
 
7448
 13. Use with the GNU Affero General Public License.
7449
 
7450
     Notwithstanding any other provision of this License, you have
7451
     permission to link or combine any covered work with a work licensed
7452
     under version 3 of the GNU Affero General Public License into a
7453
     single combined work, and to convey the resulting work.  The terms
7454
     of this License will continue to apply to the part which is the
7455
     covered work, but the special requirements of the GNU Affero
7456
     General Public License, section 13, concerning interaction through
7457
     a network will apply to the combination as such.
7458
 
7459
 14. Revised Versions of this License.
7460
 
7461
     The Free Software Foundation may publish revised and/or new
7462
     versions of the GNU General Public License from time to time.
7463
     Such new versions will be similar in spirit to the present
7464
     version, but may differ in detail to address new problems or
7465
     concerns.
7466
 
7467
     Each version is given a distinguishing version number.  If the
7468
     Program specifies that a certain numbered version of the GNU
7469
     General Public License "or any later version" applies to it, you
7470
     have the option of following the terms and conditions either of
7471
     that numbered version or of any later version published by the
7472
     Free Software Foundation.  If the Program does not specify a
7473
     version number of the GNU General Public License, you may choose
7474
     any version ever published by the Free Software Foundation.
7475
 
7476
     If the Program specifies that a proxy can decide which future
7477
     versions of the GNU General Public License can be used, that
7478
     proxy's public statement of acceptance of a version permanently
7479
     authorizes you to choose that version for the Program.
7480
 
7481
     Later license versions may give you additional or different
7482
     permissions.  However, no additional obligations are imposed on any
7483
     author or copyright holder as a result of your choosing to follow a
7484
     later version.
7485
 
7486
 15. Disclaimer of Warranty.
7487
 
7488
     THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
7489
     APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE
7490
     COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS"
7491
     WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED,
7492
     INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
7493
     MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE
7494
     RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.
7495
     SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
7496
     NECESSARY SERVICING, REPAIR OR CORRECTION.
7497
 
7498
 16. Limitation of Liability.
7499
 
7500
     IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN
7501
     WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES
7502
     AND/OR CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU
7503
     FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR
7504
     CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE
7505
     THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA
7506
     BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
7507
     PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
7508
     PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF
7509
     THE POSSIBILITY OF SUCH DAMAGES.
7510
 
7511
 17. Interpretation of Sections 15 and 16.
7512
 
7513
     If the disclaimer of warranty and limitation of liability provided
7514
     above cannot be given local legal effect according to their terms,
7515
     reviewing courts shall apply local law that most closely
7516
     approximates an absolute waiver of all civil liability in
7517
     connection with the Program, unless a warranty or assumption of
7518
     liability accompanies a copy of the Program in return for a fee.
7519
 
7520
 
7521
END OF TERMS AND CONDITIONS
7522
===========================
7523
 
7524
How to Apply These Terms to Your New Programs
7525
=============================================
7526
 
7527
If you develop a new program, and you want it to be of the greatest
7528
possible use to the public, the best way to achieve this is to make it
7529
free software which everyone can redistribute and change under these
7530
terms.
7531
 
7532
   To do so, attach the following notices to the program.  It is safest
7533
to attach them to the start of each source file to most effectively
7534
state the exclusion of warranty; and each file should have at least the
7535
"copyright" line and a pointer to where the full notice is found.
7536
 
7537
     ONE LINE TO GIVE THE PROGRAM'S NAME AND A BRIEF IDEA OF WHAT IT DOES.
7538
     Copyright (C) YEAR NAME OF AUTHOR
7539
 
7540
     This program is free software: you can redistribute it and/or modify
7541
     it under the terms of the GNU General Public License as published by
7542
     the Free Software Foundation, either version 3 of the License, or (at
7543
     your option) any later version.
7544
 
7545
     This program is distributed in the hope that it will be useful, but
7546
     WITHOUT ANY WARRANTY; without even the implied warranty of
7547
     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
7548
     General Public License for more details.
7549
 
7550
     You should have received a copy of the GNU General Public License
7551
     along with this program.  If not, see `http://www.gnu.org/licenses/'.
7552
 
7553
   Also add information on how to contact you by electronic and paper
7554
mail.
7555
 
7556
   If the program does terminal interaction, make it output a short
7557
notice like this when it starts in an interactive mode:
7558
 
7559
     PROGRAM Copyright (C) YEAR NAME OF AUTHOR
7560
     This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
7561
     This is free software, and you are welcome to redistribute it
7562
     under certain conditions; type `show c' for details.
7563
 
7564
   The hypothetical commands `show w' and `show c' should show the
7565
appropriate parts of the General Public License.  Of course, your
7566
program's commands might be different; for a GUI interface, you would
7567
use an "about box".
7568
 
7569
   You should also get your employer (if you work as a programmer) or
7570
school, if any, to sign a "copyright disclaimer" for the program, if
7571
necessary.  For more information on this, and how to apply and follow
7572
the GNU GPL, see `http://www.gnu.org/licenses/'.
7573
 
7574
   The GNU General Public License does not permit incorporating your
7575
program into proprietary programs.  If your program is a subroutine
7576
library, you may consider it more useful to permit linking proprietary
7577
applications with the library.  If this is what you want to do, use the
7578
GNU Lesser General Public License instead of this License.  But first,
7579
please read `http://www.gnu.org/philosophy/why-not-lgpl.html'.
7580
 

powered by: WebSVN 2.1.0

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